yi-ge · Oct 15, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/PLAN.md b/PLAN.md
diff --git a/README.md b/README.md
@@ -124,6 +124,12 @@ Keep this convention and AGENTS.md consistent when updating either file.
 - Replace implementation-status caveats with an effective version, current support scope, or visible steps. Keep component names and technical details when they help with configuration, troubleshooting, permissions, or licenses.
 - Keep advice for documentation authors out of user-facing prose. Apply this approach in both languages while preserving actual limitations and authorization conditions.
 
+### API documentation
+
+Public API guides live in `docs/07-api/`, with matching English files under `i18n/en/docusaurus-plugin-content-docs/current/07-api/`. Keep endpoint provenance and publication scope in [api/endpoint-catalog.json](./api/endpoint-catalog.json); follow [the API maintenance guide](./api/README.md) when updating contracts and examples.
+
+Run `pnpm api:check` to check the selected bilingual pages and JSON examples. After `pnpm build`, run `pnpm api:check -- --build` to check their local routes, language links, canonical URLs, and sitemap entries. The check does not certify client implementation or replace request and response validation.
+
 ## License
 
 - Source code, theme customizations, and project configuration in this repository are licensed under the [MIT License](LICENSE).

diff --git a/api/README.md b/api/README.md
@@ -0,0 +1,67 @@
+# 公开 API 文档维护
+
+`docs/07-api/` 维护公开接入指南，英文镜像位于 `i18n/en/docusaurus-plugin-content-docs/current/07-api/`。本目录维护经过筛选的端点来源、公开范围与验证记录，不进入 Docusaurus 文档路由。
+
+## 公开范围
+
+8 组中英文页面覆盖接入认证、Agent Webhook 管理与触发、只读 Agent/Run/回执、HTTP + Socket.IO 对话、模型代理、工作流与 OpenAPI 下载。24 个 HTTP 操作按服务分成三个自包含 OpenAPI 3.1 文件；对话事件和恢复规则维护在指南与可运行 Node.js 示例中。
+
+Webhook 所有者管理依赖握手 `capabilities.webhookManagement: true`，由可信入口选择实际工具并生成文件范围快照；旧服务仅支持已有事件。该支持条件没有被改写成未经核对的客户端发行号。现有 Write/Bash 与审批模型保留，不把配置文件宣称为不可修改的安全边界。
+
+默认 Caddy 未代理 `/health`、Workflow 路径或本机 Compat Proxy。三种服务的地址、认证和权限分别维护。Workflow 只公开管理员预置定义的触发与观察，不伪造直接运行所需 grant 的公开签发流程。
+
+独立示例包在 [examples/agent-client](./examples/agent-client/README.md)，静态下载副本为 `static/api-examples/agent-client.mjs`；二者必须逐字一致。依赖和锁文件在示例目录维护，不改变站点依赖。
+
+## 修改步骤
+
+1. 固定核对的代码 SHA，核查实际 listener、路由、中间件、请求 Schema、响应和异步行为。
+2. 在 `endpoint-catalog.json` 更新相应操作；同一服务中的方法与路径、全局 `operationId` 不重复。来源使用仓库相对路径，不填写本机绝对路径。
+3. 修改对应中英文页面，保持字段、错误、版本约束和支持范围一致。一个能力由同一编辑负责人维护两种语言。
+4. 使用隔离测试数据验证实际请求和关键失败。区分 Schema 检查、mock query 的路由测试、真实 listener 测试和真实模型运行。
+5. 执行离线文档检查与双语构建，核对导航、代码复制、语言切换和窄屏阅读。
+6. 根据 Git 发布流程发布；自动部署成功后再检查生产 URL。当前 sitemap 检查器访问生产地址，不能替代部署前的本地检查。
+
+```bash
+pnpm api:check
+pnpm typecheck
+pnpm build
+pnpm api:check -- --build
+```
+
+`api:check` 检查清单、两种语言的显式 slug、JSON 示例、版本提示框及 OpenAPI 范围、引用、鉴权和下载链接；`--build` 额外读取本地 HTML 和 sitemap。它不读取私有源仓库、不访问生产 URL，也不证明翻译语义或接口运行已验收。
+
+## 清单字段
+
+`pages` 列出本批公开页面的 `id`、源码 `file` 和稳定 `slug`。`endpoints` 使用以下字段：
+
+| 字段 | 用途 |
+|---|---|
+| `operationId`、`service`、`method`、`path`、`doc` | 操作身份、所属服务、实际路径和正文来源 |
+| `deploymentModes`、`authentication`、`permissions` | 支持范围、认证和额外权限条件 |
+| `resultDelivery` | 实际响应与结果交付方式 |
+| `source`、`schemaRefs` | 固定来源 SHA、路由/认证文件和已有 Schema |
+| `effectiveVersion`、`versionEvidence` | 确需版本约束时记录依据；无约束时为 `null`，不得推断首次可用版本 |
+| `securitySchemes` | 该操作的实际认证方案，与规范逐项一致 |
+| `verification` | 验证记录和未覆盖范围 |
+| `spec` | 对应服务的公开 OpenAPI 文件；未收录项才为 `null` |
+
+遵循根 `AGENTS.md` 与 `README.md` 的生效版本和用户写作规范。已有明确版本不得改成默认值；协议修订、服务版本字段和客户端功能生效版本分别保留含义。
+
+## 端点页面模板
+
+一个能力的中英文页面按相同顺序组织，删除不适用的章节：
+
+1. 用途、目标读者与当前支持范围。
+2. 调用前准备：地址、凭据、配置和权限的实际获取方式。
+3. 方法、路径、请求头、参数表与合法 JSON 示例。
+4. 一次完整请求示例，以及实际响应和成功判定。
+5. 异步结果的观察方法与尚未提供的能力。
+6. 现行重试、去重、超时及恢复合同。
+7. 实际错误表：状态、字段/机器码、触发条件与调用方动作。
+8. 用户可操作的排查步骤和相关指南。
+
+不要从模板补造响应壳、凭据签发、幂等或结果回调。来源、代码基线和验证记录写入本目录，用户正文只保留能帮助配置、调用和排查的技术细节。
+
+## 当前验证记录
+
+参见 [核查与验证](./verification.md)。后续更改认证、路由、配置入口或结果交付时，只重新核对受影响合同和相关示例，不将本批测试结果传播为其它功能的运行保证。
diff --git a/api/ci-base-attribution.json b/api/ci-base-attribution.json
@@ -0,0 +1,134 @@
+{
+  "baseline": "5714a1899c0cc80d26463e596f1cadfcc1dd4533",
+  "platform": "darwin",
+  "architecture": "arm64",
+  "node": "v26.4.0",
+  "vitest": "5.0.3",
+  "scope": {
+    "files": 9,
+    "executed": 16,
+    "failures": 16,
+    "passed": 0,
+    "skippedCollectedCases": 2559,
+    "ciNameMatches": 16,
+    "excluded": "The two service-metadata cases are outside this baseline-attribution assignment."
+  },
+  "submodules": {
+    "docs": {
+      "gitlink": "de4b857a48f350b2abba253d44657a195001fa01",
+      "checkedOut": "f620bc410063301cb5828f2ad63f9a10ce61f086",
+      "remoteDefault": "origin/main"
+    },
+    "drawio": {
+      "gitlink": "88ee1f5ab4d40603a8f3aaa0d9d6dc3794c6b3f0",
+      "checkedOut": "88ee1f5ab4d40603a8f3aaa0d9d6dc3794c6b3f0",
+      "remoteDefault": "origin/dev"
+    }
+  },
+  "dependencies": {
+    "workspacePackages": 12,
+    "workspaceLocation": "Each points to the baseline checkout packages directory.",
+    "thirdParty": "Reused installed dependencies entry-by-entry; published @desirecore/super-doc 0.2.16 is not a workspace."
+  },
+  "failures": [
+    {
+      "file": "app/stores/__tests__/chat-store-pending-message.test.ts",
+      "name": "chat.store 排队消息机制 多个会话的排队请求分组发送，不跨会话合并",
+      "signature": "AssertionError: expected \"vi.fn()\" to be called with arguments: [ 'A1\\nA2', ObjectContaining{…}, …(6) ]",
+      "seenInCI": true
+    },
+    {
+      "file": "app/components/market/__tests__/MarketAgentDetail.test.tsx",
+      "name": "MarketAgentDetail 可信度与骨架 已安装 Agent 在 listing-only 阻断新获取时仍可卸载",
+      "signature": "AssertionError: expected true to be false // Object.is equality",
+      "seenInCI": true
+    },
+    {
+      "file": "app/components/market/__tests__/MarketAgentDetail.test.tsx",
+      "name": "MarketAgentDetail 可信度与骨架 已安装 Agent 在 client-incompatible 阻断新获取时仍可卸载",
+      "signature": "AssertionError: expected true to be false // Object.is equality",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/agent-git-conflicts.unit.test.ts",
+      "name": "commitAgentChange / auto-commit 阶段 Should call add when file exists with unstaged modifications / 文件被改但未暂存 → 调用 add",
+      "signature": "Error: ENOENT: no such file or directory, lstat '/tmp/test-facade-agents/test-agent-001/modified.txt'",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tool-definition-budget.test.ts",
+      "name": "内置工具定义体积预算 AppManage 的描述不超过上限",
+      "signature": "AssertionError: AppManage [posix / zh / 目录描述]: description=1050 rules=281 schema=678 total=2009: expected 1050 to be less than or equal to 600",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tool-schema-sync.test.ts",
+      "name": "内置工具 params 与 inputSchema 同步守卫 array/object 参数必须有结构（零豁免；有意开放用 additionalProperties: true 显式声明） AppManage.file_ref",
+      "signature": "AssertionError: AppManage.file_ref 的 inputSchema 缺少 properties/additionalProperties 结构。真自由形态请显式写 additionalProperties: true 并在工具文件注释说明有意开放。: expected false to be true // Object.is equality",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tool-schema-sync.test.ts",
+      "name": "内置工具 params 与 inputSchema 同步守卫 array/object 参数必须有结构（零豁免；有意开放用 additionalProperties: true 显式声明） AppManage.release_request",
+      "signature": "AssertionError: AppManage.release_request 的 inputSchema 缺少 properties/additionalProperties 结构。真自由形态请显式写 additionalProperties: true 并在工具文件注释说明有意开放。: expected false to be true // Object.is equality",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tool-schema-sync.test.ts",
+      "name": "内置工具 params 与 inputSchema 同步守卫 array/object 参数必须有结构（零豁免；有意开放用 additionalProperties: true 显式声明） AppManage.owner_request",
+      "signature": "AssertionError: AppManage.owner_request 的 inputSchema 缺少 properties/additionalProperties 结构。真自由形态请显式写 additionalProperties: true 并在工具文件注释说明有意开放。: expected false to be true // Object.is equality",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tool-schema-sync.test.ts",
+      "name": "内置工具 params 与 inputSchema 同步守卫 array/object 参数必须有结构（零豁免；有意开放用 additionalProperties: true 显式声明） AppManage.export_file_ref",
+      "signature": "AssertionError: AppManage.export_file_ref 的 inputSchema 缺少 properties/additionalProperties 结构。真自由形态请显式写 additionalProperties: true 并在工具文件注释说明有意开放。: expected false to be true // Object.is equality",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tools-all.test.ts",
+      "name": "Tool Registration / 工具注册 内置工具应全部注册 / All builtin tools should be registered",
+      "signature": "AssertionError: expected [ 'AppData', 'AppManage', …(119) ] to deeply equal [ 'AppManage', …(118) ]",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tools-all.test.ts",
+      "name": "Tool Registration / 工具注册 getAllBuiltinToolsAsRegistered 返回有效 RegisteredTool[] / getAllBuiltinToolsAsRegistered returns valid RegisteredTool[]",
+      "signature": "AssertionError: expected 121 to be 119 // Object.is equality",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tools-static-closure-budget.test.ts",
+      "name": "内置工具静态闭包预算 builtin-tools/terminal-control.ts 的静态闭包不超过 110 个模块",
+      "signature": "AssertionError: builtin-tools/terminal-control.ts 的模块初始化期静态闭包为 113，超过预算 110。",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/__tests__/builtin-tools-static-closure-budget.test.ts",
+      "name": "内置工具静态闭包预算 除已知遗留外，没有内置工具静态可达 socket-server",
+      "signature": "AssertionError: 这些内置工具的静态闭包里出现了 socket-server —— 一条新的间接回边成环了。",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/builtin-tools/__tests__/tool-text-translations-guard.test.ts",
+      "name": "内置工具文本的语言守卫 每个内置工具都有英文视图",
+      "signature": "AssertionError: expected [ 'AppData', 'ApplicationObject' ] to deeply equal []",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/agent-service/src/builtin-tools/__tests__/tool-text-translations-guard.test.ts",
+      "name": "内置工具文本的语言守卫 声明了英文视图的工具，英文视图里没有中文",
+      "signature": "AssertionError: expected [ …(21) ] to deeply equal []",
+      "seenInCI": true
+    },
+    {
+      "file": "packages/schemas/src/agent-service/__tests__/embedded-service-process.test.ts",
+      "name": "Embedded Agent Service utility process frame schema 所有控制字段和 payload 字段都有 description",
+      "signature": "AssertionError: $.oneOf[8].properties.payload.oneOf[20].properties.params.properties.request.properties.resourceRef.oneOf[13].properties.pin 缺少 description: expected undefined to deeply equal Any<String>",
+      "seenInCI": true
+    }
+  ],
+  "ciMergeRevision": "6bbd71a944419858e130e70429bba1931aaf0a89",
+  "ciFeatureRevision": "d3bac348db5f15ce6a59469ffef8f495c84ced59",
+  "interpretation": "All 16 selected failures reproduce at the fixed CI first-parent baseline. This record attributes failures; it is not a successful acceptance run. The additional two service-metadata expectations were repaired separately in the API feature branch."
+}