docs: 同步 API 隐私投影与稳定性边界

api/README.md

@@ -93,3 +93,9 @@ v5 只对 `/more/changelog/v10.0.180` 和 `/en/more/changelog/v10.0.180` 做定
 RunMeta 接受 `handed_off`，但现行 runtime-state HTTP 入口仍对该状态返回 `404`。共享 Schema 的五值枚举不能直接当作该路由的实际响应合同。历史消息的分页窗口与返回消息条数不同，示例按请求窗口推进；媒体读取使用短期签名，附件下载使用实例身份。
 
 `publication.json`、生产和搜索验收 JSON 保留已经发布批次的事实；本批提交 PR 不代表这些新页面已经部署或收录。
+
+## 2026-10-22 稳定性复核
+
+最新核对源码为 `a101a40c14cc9d478c7f9a23d8a125ac2404509b`，内部文档指针为 `34178859da7a70cfab0b4726b85d9a37f22608a7`。本次维持35个公开HTTP操作，补齐敏感工具结果占位、引用移除、状态保留与客户端兼容处理说明，Agent Service规范描述修订为1.1.1；不把描述版本写成服务兼容性保证。详见[本次复核与验证](./stability-verification-2026-10-22.md)。
+
+RunMeta五态与runtime-state HTTP四态/转交404的差异仍存在，公开文件继续按实际路由呈现。历史读取并非无损备份，不能从占位文字自动恢复执行。此前发布与搜索验收的记录保持各自历史基线，不将本次源码核对当作新生产或安装包验收。

api/examples/agent-client/README.md

@@ -76,7 +76,7 @@ Run `npm test` for the independent HTTP + Socket.IO contract fixture. It verifie
 
 `test/source-route.fixture.ts` can be copied into a fixed-source DesireCore checkout as `packages/agent-service/src/__tests__/api-docs-node-client.integration.test.ts`. Set `DESIRECORE_API_EXAMPLE_PATH` to the absolute path of this directory's `client.mjs`, then run that single file in the repository's integration test project. It verifies this client against the actual query routes, HTTP/Socket authentication, request Schema and digest, durable admission registry and lookup, and renderer delivery room. The query runtime and follow-up execution callback remain fake. Use its isolated temporary data root; do not point it at an existing user profile.
 
-Current source review: `desirecore/desirecore` commit `7fe016c76ab98e0643ab4f2710c3733f757ef4fb`. Historical validation remains in `api/verification.md`; this extension is recorded in `api/history-attachments-verification.md`.
+Current source review: `desirecore/desirecore` commit `a101a40c14cc9d478c7f9a23d8a125ac2404509b`. Historical validation remains in `api/verification.md`; this extension is recorded in `api/history-attachments-verification.md`.
 
 - HTTP submission: `packages/agent-service/src/routes/query-routes.ts`.
 - Admission lookup: `packages/agent-service/src/routes/client-request-lookup-routes.ts`; shared Schema in `packages/schemas/src/agent-service/client-request-admission.ts`.
@@ -88,3 +88,5 @@ Current source review: `desirecore/desirecore` commit `7fe016c76ab98e0643ab4f271
 Keep the three published downloads byte-identical to their maintained files: `client.mjs` → `static/api-examples/agent-client.mjs`, `history.mjs` → `static/api-examples/history.mjs`, and `attachments.mjs` → `static/api-examples/attachments.mjs`. Revalidate the affected contracts after changes. The example is deliberately a small client, not a complete renderer, SDK, or durable execution orchestrator.
 
 `test/source-history.fixture.ts` can be copied to the fixed source tree as `packages/agent-service/src/__tests__/api-docs-history.test.ts` and run in the `unit` project. It uses actual instance authentication, history/topic/Run routes and temporary file storage. The local profile and runtime discovery are stubs. It checks owner filtering, public message projection, search validation, empty topic reads, and the actual `handed_off` detail/`404` runtime-state behavior. It does not run a model or real handoff. Website TypeScript checking excludes these two source fixtures because their imports resolve only inside DesireCore’s source repository.
+
+History output is a display projection: sensitive tool results may be placeholders, and body references may be absent. The reader preserves these payloads and optional response extensions; it does not infer tool success from placeholder text, retrieve withheld references, or execute replacement work. Current stability review and verification are recorded in `api/stability-verification-2026-10-22.md`.

api/examples/agent-client/test/history.test.mjs

@@ -114,11 +114,14 @@ test('bounds all-pages requests and reports the next offset', async t => {
 });
 
 test('uses the exact Run snapshot endpoint and leaves the public payload intact', async t => {
-  const snapshot = { runId: 'run-a', messages: [], pendingAssistant: { role: 'assistant', content: 'in progress' }, status: 'idle' };
+  const snapshot = { runId: 'run-a', messages: [{ role: 'assistant', content: '', toolUse: [
+    { id: 'private-call', name: 'BrowserScript', summary: 'Tool result withheld', status: 'failed', isError: true },
+  ] }], pendingAssistant: { role: 'assistant', content: 'in progress' }, status: 'idle', optionalExtension: { displayOnly: true } };
   const f = await fixture(t, (url, response) => { assert.equal(url.pathname, '/api/sessions/run-a'); json(response, 200, snapshot); });
   const out = await read({ command: 'session', id: 'run-a' }, f.env);
   assert.deepEqual(out.records[0].data, snapshot);
   assert.equal(out.result.exitCode, 0);
+  assert.equal(f.requests.length, 2); // Handshake and read only: withheld output never triggers execution.
 });
 
 test('overview and matter are unpaginated; a truncated matter exits 2', async t => {

api/examples/agent-client/test/source-history.fixture.ts

@@ -84,6 +84,29 @@ describe('公开历史 API 的实际路由合同', () => {
     expect((await app.inject({ method: 'GET', url: '/api/sessions/missing-run', headers })).statusCode).toBe(404)
   })
 
+  it('真实历史读取隐藏敏感失败正文和引用，同时保留失败状态', async () => {
+    createRun('privacy-run')
+    writeFileSync(join(rootRef.current, 'runs', 'privacy-run', 'messages.jsonl'), [
+      { role: 'user', content: 'fixture privacy request', timestamp: 1 },
+      { role: 'assistant', content: '', timestamp: 2, toolUse: [{
+        id: 'private-call', name: 'BrowserScript', status: 'failed', isError: true,
+        summary: 'PRIVATE-RESULT-BODY', summaryRef: { filename: 'private-result.txt', size: 19 },
+        summaryIncomplete: true,
+      }] },
+    ].map(value => JSON.stringify(value)).join('\n') + '\n')
+    for (const suffix of ['', '/messages?offset=0&limit=2']) {
+      const response = await app.inject({ method: 'GET', url: '/api/sessions/privacy-run' + suffix, headers })
+      expect(response.statusCode).toBe(200)
+      const tool = response.json().messages[1].toolUse[0]
+      expect(tool).toMatchObject({ status: 'failed', isError: true })
+      expect(typeof tool.summary).toBe('string')
+      expect(tool.summary).toContain('failed')
+      expect(tool).not.toHaveProperty('summaryRef')
+      expect(tool).not.toHaveProperty('summaryIncomplete')
+      expect(response.body).not.toMatch(/PRIVATE-RESULT-BODY|private-result\.txt/)
+    }
+  })
+
   it('搜索使用真实历史，缺少Agent或非法分页返回400', async () => {
     createRun('search-run')
     const response = await app.inject({ method: 'GET', url: '/api/sessions/messages/search?agentId=docs-agent&q=needle&limit=1&offset=0&previewChars=20', headers })

api/stability-verification-2026-10-22.md

@@ -0,0 +1,43 @@
+# API契约与稳定性复核（2026-10-22）
+
+本次复核已公开的35个HTTP操作及相关事件、历史恢复边界。它是契约和文档一致性检查，不是压测、服务可用性SLA或所有客户端版本的兼容承诺。
+
+## 来源
+
+- 源码：`desirecore/desirecore@a101a40c14cc9d478c7f9a23d8a125ac2404509b`。
+- 内部文档gitlink：`34178859da7a70cfab0b4726b85d9a37f22608a7`。
+- 公共文档基线：`4530b17`，本次从最新main建立独立分支，不改原有源码工作树。
+- Agent Service的27个操作重新核对至当前SHA。Compat Proxy、Workflow的装配与所选合同另行比较，规范仍保留各自原固定来源，未将历史运行结果改写为当前提交实跑。
+
+## 发现与修订
+
+| 范围 | 核对事实 | 本次更新 |
+|---|---|---|
+| 历史、快照和话题公开投影 | 敏感工具结果可变成占位；缺少可信调用身份或身份矛盾的协议结果也会收窄；正文引用可被移除 | 中英08、错误排查、HistoryMessage/快照/话题Schema与操作说明同步，不依赖占位措辞或假定引用必有 |
+| 工具结局 | 失败事实不会因为脱敏变成成功；部分运行中或中断摘要可缺席 | 明确保留status/isError，不能从摘要单词推断Query终态或自动重跑 |
+| 可选事件关联 | query:retrying、query:warning增加可选请求/对话标识；不是终态事件 | 中英04补充关联使用边界，不扩大成必须接收的新协议 |
+| Run转交 | RunMeta仍五态；runtime-state HTTP路由仍四态，转交返回404 | 保留已实测差异，未把共享Schema误当实际HTTP输出 |
+| 客户端兼容 | 所选请求Schema、摘要与主要接纳字段未变；响应扩展、未知状态、历史显示变化应分别处理 | 入口页增加兼容与稳定性章节，不声明没有依据的全局版本保证 |
+| 来源台账 | AgentSummary的旧schemaRefs路径误写到agent-service目录 | 修为实际的packages/schemas/src/agent/agent-summary.ts，并逐项检查固定提交来源路径 |
+
+媒体所有权写入加强了新媒体落盘失败时的清理与隔离；上传/下载路径、请求和成功响应合同未变。Webhook的模型路由决策透传及Compat Proxy的启动/序列化装配变化未改变所选HTTP合同。新增Kimi设置入口、移除旧dev路由、团队/工作目录/任务管理治理收紧均不扩入本批公开接口。
+
+没有把历史读取说成无副作用的数据库原始直读。原有恢复、显示去重、图片补全、跨页并发变化和话题120条截断规则继续适用；本批说明的是公开返回视图和调用方处理边界。
+
+## 定向验证
+
+| 层次 | 结果 | 范围 |
+|---|---|---|
+| 当前源码既有测试 | 4文件34项通过 | public-session-projection 17、冷工具隐私规则3、媒体路由13、附件路由1 |
+| 公开历史源码夹具 | 1文件6项通过 | 实际鉴权/路由/临时SessionStore；新增敏感失败结果占位、移除引用、保留失败事实回归；原Run转交404等用例继续通过 |
+| 独立Node示例 | 3文件41项通过 | 包括读取器原样保留脱敏和新增可选响应字段，不因为占位额外请求或执行 |
+| 站点与规范清单 | 通过 | api:check：10组双语页面、35操作、66个JSON块、3规范；typecheck、双语build及api:check --build通过 |
+| JSON Schema与规范工具 | 通过 | AJV Draft7：68个组件Schema、44个JSON媒体示例；Redocly CLI2.63.0：三规范0错误，保留既有47条条件Schema和3条license告警 |
+
+源码验证使用隔离的固定提交worktree，子模块初始化并fetch；Node依赖复用既有本机安装。源码夹具的本机profile和运行时发现为替身，不启动模型。测试使用临时数据，不读取个人历史或真实凭据。
+
+独立示例没有改运行逻辑或新增依赖：history读取器本来就只读并透传公开payload。本次增强现有测试输入与源码夹具；三个可下载脚本仍逐字对应维护文件。
+
+## 交付边界
+
+本批提交PR供审阅，未合并、未自动部署，也未重新触发搜索抓取。此前PR #77的生产和搜索验收继续保留其原始基线；本批本地验证不能替代新一轮生产验收。商业模型、真实用户工具副作用、已发行安装包和全量服务压测不在本次范围内。

api/verification.md

@@ -1,5 +1,7 @@
 # 当前扩展验证入口
 
+2026-10-22的最新契约复核见[API稳定性验证](./stability-verification-2026-10-22.md)；下面各批记录保留原来源和测试范围。
+
 Run状态、会话历史与消息、附件媒体的新增实现见[本批核查与验证](./history-attachments-verification.md)。下面保留既有已发布批次的来源和运行结果；其中8组页面、24个操作的数字属于当时范围，不代表本批扩展后的总数。
 
 ---

docs/07-api/03-errors-and-troubleshooting.md

@@ -103,3 +103,9 @@ Webhook 的 `200` 和 `accepted: true` 表示已接收触发。响应中没有 R
 ## 对话、代理与工作流排查
 
 对话超时后先使用示例的 `--recover` 读取准入记录；保留原请求 ID、摘要和状态文件，避免将未知状态当作未执行。详见[对话与 Run](./04-conversations-and-runs.md)。模型代理应核对本机 Base URL 和安全 token 的供应商绑定；Workflow Service 应核对独立地址和 `X-Workflow-Service-Token`，再按[工作流指南](./06-workflow-integration.md)检查 `runId` 与终态。
+
+## 历史读取成功但结果不完整 {#history-projection-troubleshooting}
+
+HTTP `200` 表示读取成功，不保证返回完整的工具结果正文。敏感结果或无法核验调用身份的结果可能只提供占位提示，并省略正文引用；这与执行失败、历史损坏或需要重跑不是一回事。保留实际的 `status`、`isError`，按[历史结果的读取边界](./08-session-history-and-messages.md#history-result-privacy)处理，不从占位文字推断成功或自动重试。
+
+逐 Run 消息中的 `offset` 是字节位置，而分页请求的 `offset` 是源行位置；按请求窗口推进，不能用返回消息条数补算下一页。历史可能在读取期间变化，参见[会话历史与消息](./08-session-history-and-messages.md)。

docs/07-api/04-conversations-and-runs.md

@@ -351,6 +351,8 @@ node agent-client.mjs \
 
 没有匹配的 `clientRequestId` 或没有结构化 `terminal` 时，示例不会把事件判成这次请求已经成功。状态文件保留已观察的信息，供后续对账。
 
+`query:retrying` 和 `query:warning` 是可选的诊断事件，可能携带 `conversationId`、`clientRequestId` 等关联字段。只在能关联到当前请求时显示为该轮的提示；缺少标识的事件不能据此结束、重发或切换当前请求。它们也不替代 `query:complete.terminal`。
+
 ### 区分各种 ID {#conversation-identifiers}
 
 | ID | 标识范围与生命周期 |

docs/07-api/08-session-history-and-messages.md

@@ -249,6 +249,17 @@ curl --silent --show-error --get \
 }
 ```
 
+## 工具结果与读取稳定性 {#history-result-privacy}
+
+这些接口返回供显示和检索使用的消息视图。某些工具结果含凭据、界面内容等敏感信息，读取历史、会话快照或话题消息时，正文会改为占位提示。协议记录缺少可核验的工具调用身份、或身份信息矛盾时，也可能不返回结果正文。
+
+- `toolUse[].summary` 或内容块中的工具结果可能被替换；执行中或中断的工具摘要也可能缺席。不要依赖占位文字的固定措辞。
+- 对被隐藏的结果，`summaryRef`、`summaryIncomplete`、`externalizedPreview` 等正文引用或预览标记可能被移除。缺少引用不表示工具没有执行，也不表示可以自行拼接文件名取得正文。
+- 判断工具结局时保留并读取实际的 `status`、`isError` 等状态字段。失败结果的占位仍表示失败；摘要中出现 `completed` 也不能证明本轮请求或整项业务成功。
+- 需要敏感结果时，让用户通过原工具或应用重新取得所需数据。不要因为占位提示自动重跑工具、重复提交对话或代替用户批准操作。
+
+同一条历史记录在不同读取时间可能因脱敏规则、显示去重或正在发生的写入得到不同的显示内容。消息 ID 和源行窗口用于定位，不保证正文始终逐字相同；这些读取接口也不代替完整备份或模型协议回放。上面的分页规则和请求终态判断仍分别适用。
+
 ## 可运行的读取示例 {#history-example}
 
 **[下载 history.mjs](pathname:///api-examples/history.mjs)**。需要 Node.js 22 或之后版本，不需要安装 npm 依赖。

docs/07-api/index.md

@@ -30,6 +30,15 @@ Agent Service 使用 `X-Agent-Service-Token`，外部 Webhook 使用 `Authorizat
 
 握手的 `200` 证明该次请求已通过认证。对话提交的 `202` 和 Webhook 的 `200 accepted` 表示接纳或接收，应按对应指南观察完成与交付。对话事件使用 Socket.IO，工作流进度使用 SSE。
 
+## 兼容性与稳定性 {#api-compatibility}
+
+接入前验证握手与所需能力，并按具体端点处理状态码、字段和异步结果。连接成功不代表所有功能都可用；三种服务的地址与凭据也不能互换。
+
+- 请求严格按对应 Schema 发送；不要把某个端点的额外字段或响应外壳套用到其它端点。
+- 响应允许扩展时，可以忽略未使用的新增可选字段；仍要校验实例身份、必要字段和已知状态。遇到未知状态或缺席字段时保留未知，不自动补成 `idle` 或成功。
+- OpenAPI 的 `info.version` 标识接口描述文件的修订，不是所有服务的统一兼容承诺，也不是客户端生效版本。具体支持条件见相应指南与实例返回值。
+- 历史读取是显示视图，可能含脱敏占位并省略正文引用；详见[历史结果的读取边界](./08-session-history-and-messages.md#history-result-privacy)。网络超时、断线和结果未知时，按[接纳对账](./04-conversations-and-runs.md#request-reconciliation)处理，不直接创建新的执行。
+
 ## 开始接入
 
 1. 向管理员取得实际服务地址与对应凭据。远程调用使用经过证书验证的 HTTPS 地址。

i18n/en/docusaurus-plugin-content-docs/current/07-api/03-errors-and-troubleshooting.md

@@ -103,3 +103,9 @@ Configuration management requires instance owner access and `capabilities.webhoo
 ## Conversations, proxy and workflow troubleshooting
 
 After a conversation timeout, use the example's `--recover` to read admission records. Preserve request IDs, digest and state files; an unknown outcome does not prove execution never started. See [conversations and Runs](./04-conversations-and-runs.md). For model calls, check the local Base URL and provider binding of the safe token. For workflows, check the independent address and `X-Workflow-Service-Token`, then follow the [workflow guide](./06-workflow-integration.md) to inspect the `runId` and terminal status.
+
+## A history read succeeds but output is incomplete {#history-projection-troubleshooting}
+
+HTTP `200` confirms the read, not availability of every tool-result body. Sensitive results or results whose call identity cannot be verified may contain only placeholders with body references omitted. This does not by itself establish execution failure, damaged history, or a need to rerun work. Preserve actual `status` and `isError` facts and follow [history-result read boundaries](./08-session-history-and-messages.md#history-result-privacy); do not infer success or retry automatically from placeholder text.
+
+A per-Run message's `offset` is a byte position, whereas the pagination request's `offset` is a source-row position. Advance by the requested window, not the number of returned messages. History can change while being read; see [session history and messages](./08-session-history-and-messages.md).

i18n/en/docusaurus-plugin-content-docs/current/07-api/04-conversations-and-runs.md

@@ -351,6 +351,8 @@ An admitted follow-up returns `202` with `ok: true`, `sessionId`, and the corres
 
 Without a matching `clientRequestId` or structured `terminal`, the example does not declare that this request succeeded. Its state file retains observed information for reconciliation.
 
+`query:retrying` and `query:warning` are optional diagnostic events and may carry correlation fields such as `conversationId` and `clientRequestId`. Show them as hints for a turn only when they can be associated with that request. Uncorrelated events must not end, replay, or switch the current request, and do not replace `query:complete.terminal`.
+
 ### Distinguish Identifiers {#conversation-identifiers}
 
 | Identifier | Scope and lifetime |