docs(spec,skills): 文档与 skill 追平端点执行器(#5040 E9) - #5246
Merged
Conversation
执行器已落(#5040 E1–E8),整面硬拒已收窄为五道逐端点 publish 门,但三层散文 仍在讲反话。对升级者(往往只有这段文字的 AI 维护者)那不是「过期」,是把人 指离一个已经能用的能力的**指令**。 spec 内两处处方文本(本单唯一会随包发布的一半): - `App.apis` 墓碑原写「stack 级 defineStack({ apis }) 在 v17 也不可执行 (#4936)……等执行器」。一条重定向式墓碑必须对它指向的地方说真话,而这条 在同一句里把目的地称作死的 —— 顺理成章的下一步就是继续用 handler 代码写 路由。现改为:该面自 protocol 17 起真实服务,点名五道门,并带上抬到 stack 级时必须做对的两件事(carve-out 与显式 `manifest.namespace`,以及 `authRequired` 缺省 true / D6 的已装配 rateLimit 配对义务)。移除那一半 原样保留 —— `App.apis` 从未被读过,仍然是删;#4936 也仍在,历史正是这条 重定向存在的理由。 - `defineStack({ server })` 模块头原写 #5040「wires endpoint-level rateLimit —— still unwired today」。已接线。同时补上服务端预算作者真正需要的关系: 端点桶键在独立命名空间,两份预算各计各的,不共享计数器。 两者经 gen:docs 传播到 content/docs/references/ 的两页,生成物只动这两页。 手写文档:http-protocol.mdx 把「该面无执行器」的 callout 换成真正的 Declarative Endpoints 一节(匹配 → 策略链 → 委派到内建路由同款流水线;五道 门;401 / 429+Retry-After / 成功答案才有的 Cache-Control: private;以及最易 搞错的恒等语义 —— 未匹配路径与**已声明路径上的方法不匹配**都保持传输层裸 404 逐字节不变,因为这条缝是 Hono notFound 而不是注册路由,没有方法集可以 报 405)。quick-reference.mdx 补速查条目。 objectstack-api skill 不再把 ApiEndpointSchema 描述成四臂 type 联合,改为按 现状教学:何时 `apis:` 胜过 `contributes.routes`(以及何时不 —— 真需要 handler 代码时)、carve-out、把五道门当作「跑 objectstack validate」而不是 背诵的条文、D6 的 `enabled === true` 判据、映射键的最小语义。指向 `declarative-apis-endpoints-live` 升级条目而不复述第二套规则。 以上每条都对着已构建的 spec 实测而非相信:文档示例能发布、省略 `authRequired` 的形状解析为 true、`authRequired: false` 旁只写窗口配额的 rateLimit 被带处方拒绝。墓碑新文本以两侧断言钉住(必须说新话 **且** 不得再 说已退休的那句,`#4936` 仍在),空串无法蒙混过关。 Fixes #5238 Part of #5040 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EYGdmvWP1ieZSLqvAW6uyd
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 107 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
August 4, 2026 12:08
os-zhuang
enabled auto-merge
August 4, 2026 12:08
os-zhuang
marked this pull request as draft
August 4, 2026 12:09
auto-merge was automatically disabled
August 4, 2026 12:09
Pull request was converted to draft
os-zhuang
marked this pull request as ready for review
August 4, 2026 12:20
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #5238
Part of #5040(E9 —— 文档收尾件;例子已由 E8 / #5230 补齐)
这一单摘掉的是什么
执行器已落(E1–E8),
apis:的整面硬拒已收窄为五道逐端点 publish 门。但三层散文仍在讲反话 —— 而对升级者(往往只有这段文字的 AI 维护者)那不是「过期」,是一条把人指离一个已经能用的能力的指令。1. spec 内两处处方文本(本单唯一随包发布的一半)
App.apis的 retiredKey 墓碑。原文:一条重定向式墓碑必须对它指向的地方说真话。这条在同一句里把目的地称作死的,于是照着做的下一步就是继续用 handler 代码写路由 —— 恰好绕开了 E 系列刚建好的东西。
新文本只改失真的那一半:该面自 protocol 17 起真实服务、点名五道门、带上抬到 stack 级时必须做对的两件事(
/api/v1/apps/{namespace}/{subpath}carve-out 与显式manifest.namespace;authRequired缺省true,显式false是唯一打开匿名的开关,ADR-0121 D6 随即要求已装配rateLimit),并指向declarative-apis-endpoints-live升级条目。保留未动的两处:移除那一半(
App.apis从未被读过,仍然是删)、以及#4936这段历史 —— 历史正是这条重定向存在的理由,修的是时态与指针,不是抹历史。defineStack({ server })模块头。原写 #5040「wires endpoint-levelrateLimit—— still unwired today」。已接线。顺带补上服务端预算的作者真正需要的那层关系:端点桶键在独立命名空间,两份预算各计各的,不共享计数器。两者经
gen:docs传播到content/docs/references/{ui/app,system/stack-server}.mdx。2. 手写文档
protocol/kernel/http-protocol.mdx—— 原来那句「since #4936 that surface has no executor」的 callout 换成一节真正的 Declarative Endpoints:{prefix}/apps/下,METHOD+path,去一个尾斜杠)→ 策略链(rateLimit→authRequired→cacheTtl,并写明为什么计量在鉴权之前)→ 委派到内建路由同款流水线(callData/ automation),带调用者自己的 execution context,所以 RLS/FLS 与 ADR-0049 曝光门等价适用;UNAUTHENTICATED/ 429 +Retry-After/ 成功答案才有的Cache-Control: private, max-age={ttl}(并写明private是安全规则而非调优)/cacheTtl: 0→no-store/ 错误答案永不带缓存指令也永不过outputMapping;404逐字节不变 —— 因为这条缝是 HononotFound而不是注册路由,没有方法集可以报405(已注册路由的 405 契约不变);apis:声明(照 showcase 回迁件裁短)。getting-started/quick-reference.mdx—— 按本页体例补一条速查:路径形状、显式 namespace、能执行的两种type、authRequired缺省与 D6 配对、cacheTtl语义 + 一段最小示例。3.
objectstack-apiskill原文把声明式面写成一句四臂
type联合(flow/script/object_operation/proxy)加 target —— 其中两臂在 17.x 根本不执行。改为按现状教学:apis:胜过contributes.routes,以及何时不(真需要 handler 代码时);manifest.id推导」的理由);objectstack validate读报错处方」而不是背诵的条文 —— 报错自带处方,不在 skill 里复述第二套;enabled === true判据(而非键存在)明写;transform被拒、bodyless 操作上的inputMapping被拒、目标路径不得互相包含;declarative-apis-endpoints-live,单一真源。evals/目前是占位(README 明写 "Not yet implemented"),没有断言旧行为的 eval 可跑;其目录规划里那条test-api-endpoint-types.md(原注ApiEndpointSchema type/target/authRequired)已按翻转改写,并补了 carve-out /authRequired缺省 / D6 三条规划项。实测,不是相信
三条文档断言都拿已构建的 spec 跑过
defineStack:墓碑新文本以两侧断言钉住(
packages/spec/src/ui/app.test.ts):必须说新话(EXECUTES from protocol 17、carve-out、D6、升级条目 id)且不得再说已退休的那两句,同时#4936仍须在场 —— 只钉在场会被「底下又加回旧话」骗过,只钉缺席会被空串骗过。验证(真实输出)
生成物移动只有两页 reference,且逐字对应本单改的两段处方文本;numstat 无
- -行。check:skill-examples第一轮红过一次并已修:文档示例的manifest缺type,补type: 'app'—— 一个正好证明这道门有用的失败。顺手发现的、已单独立项的
cacheTtl的响应头写成public, max-age=30—— 运行时发的是private，而private是安全规则 #5244(挂为 E 系列收尾:摘除已失真的「structurally unreachable」注释 + 多租户 decline 分支补零覆盖 #5231 子单,同为「注释必须与实际一致」)——examples/app-showcase/src/system/apis/index.ts:80的注释把cacheTtl的响应头写成Cache-Control: public, max-age=30;运行时发的是private(computeCacheControl),PR test(e2e,showcase): 执行器收官验收 —— showcase 端点回迁 + 真实 boot 探针(#5040 E8) #5230 的真实 boot 探针 P1 也印着private。而private在这条链上是安全规则,且这份文件是声明式端点唯一的一手示例。compatibility仍写「Requires @objectstack/spec 16.x」—— 而它们教的已经是 17 的能力 #5245(finding)—— 十份 SKILL.md 的compatibility仍写Requires @objectstack/spec 16.x,仓库已是 17.0.0-rc.2,且三道 skill 门都不看这一行。写法(改死 17 / 改范围 / 加对账门)是维护者的决定,不在本单里替你选。边界
词表与运行时零触碰;未编辑
content/docs/releases/;与 #5231(源码注释)不重叠 —— 那批structurally unreachable措辞散在packages/runtime|metadata|rest内,本单一处未动。changeset 按纯处方文本的历史惯例记@objectstack/spec: patch。现场已清:未起任何 dev server;worktree 在 PR 后移除。
🤖 Generated with Claude Code
https://claude.ai/code/session_01EYGdmvWP1ieZSLqvAW6uyd