Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(i18n): mirror ACP-automation edits into the zh pairs from master

Browse Source 
Master's i18n batches added Chinese counterparts to ~50 docs this PR
edits in English. Bring each zh side along with the minimal edits
covering the en diff (recorded-hash diffs, not re-translations),
reunite the stream-workflow-progress pair under rejected/ with its
manifest entry, re-record all pairing hashes, and regenerate the
event/persistence/tool catalogs and doc graphs over the merged tree.
This commit is contained in:
Tianyi Cui
2026-07-25 01:58:42 +08:00
parent 440384fdb4
commit 16910475ef
108 changed files with 287 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-14-acp-agent-client-protocol.md: c6976ed28a254684fca62e2d309cdde7ea90340d
2026-06-14-acp-agent-client-protocol.zh.md: 6bd234f2aa3f43f4fc6cbd921161253c46aab73e
2026-06-14-acp-agent-client-protocol.md: da23bbfa247bc2423072477cc4b6277485df1c9c
2026-06-14-acp-agent-client-protocol.zh.md: ec55922e0aee57169d8bbf44c3d91b18ea83041e

6
.agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.zh.md
View File

@@ -4,6 +4,8 @@ Status: implemented
[English](2026-06-14-acp-agent-client-protocol.md) | 中文
> 已被 [ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)取代。本 Agent Note 记录已退役的面向编辑器的桥接层设计。
## 问题
harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本，但编辑器无法以结构化方式创建或恢复会话、关联提示词完成、流式输出推理（reasoning）与工具活动、渲染工具专属 UI、请求权限，或在不干扰其他对话的前提下取消某个对话。ACP（Agent Client Protocol）将这些交互定义为基于 stdio 的 JSON-RPC，Zed 是用于做出具体兼容性决策的目标客户端。
@@ -12,7 +14,7 @@ harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本
## 决策
`@deepseek-ai/dsh-acp` 是位于 `packages/ui/acp` 的 UI/客户端驱动插件。它使用 `@agentclientprotocol/sdk` 的 `AgentSideConnection`（基于 stdin/stdout），仅编排接口服务：agent 创建/恢复工厂、会话持久化、工具注册表、用户交互，以及可选的审批/bash 能力。它不修改 agent loop，也不是能力 seam 的实现。
`@deepseek-ai/dsh-acp` 曾是 `ui` 包组中的 UI/客户端驱动插件（现位于 `acp`）。它使用 `@agentclientprotocol/sdk` 的 `AgentSideConnection`（基于 stdin/stdout），仅编排接口服务：agent 创建/恢复工厂、会话持久化、工具注册表、用户交互，以及可选的审批/bash 能力。它不修改 agent loop，也不是能力 seam 的实现。
桥接层实现以下稳定的会话路径：
@@ -32,7 +34,7 @@ harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本
生命周期所有权是显式的。桥接层为每个活跃会话持有一个 `AgentHandle`。断连和 Cordis dispose（资源释放）会取消待处理的提示词，并行 dispose 所有 handle，等待循环完全停稳与持久化刷写，然后移除记录。流通知失败被隔离，因此消失的客户端不会破坏 agent 轮次。ACP 应用组合不加载 stdout logger；一个测试守卫 stdout 仅包含帧化的 JSON-RPC。
精确的已支持与已推迟的协议行列表见 [`packages/ui/acp/acp-feature-support.md`](../../../../packages/ui/acp/acp-feature-support.md)；包 README 是操作契约。
当前的协议契约见 [`dsh-acp` 包 README](../../../../packages/acp/acp/README.md)。
## 曾考虑的替代方案

4
.agents/notes/implemented/feature/2026-06-14-acp-multi-session.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-14-acp-multi-session.md: 43aa32a43fef7aa69f5efd45d4c8176da9f459cd
2026-06-14-acp-multi-session.zh.md: 6835f9623b89dc20d6c7b3054365cd9c39402aeb
2026-06-14-acp-multi-session.md: 088fe984fbc94fe0d8654702d5fce9eb0581cd3b
2026-06-14-acp-multi-session.zh.md: 2a803a6eff9b16b48fb90b2b986f74e762e5419c

24
.agents/notes/implemented/feature/2026-06-14-acp-multi-session.zh.md
View File

@@ -4,19 +4,21 @@ Status: implemented
[English](2026-06-14-acp-multi-session.md) | 中文
> 本 Agent Note 写于 ACP 还是编辑器桥接层的时期，动机来自 Zed 的多会话客户端模型。[ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)移除了编辑器接口；多路复用决策本身不变，本 Agent Note 现依照自动化契约陈述它。
## 问题
一个 ACP（Agent Client Protocol）编辑器可以在同一个 agent（智能体）子进程上保持多个对话。如果桥接层只支持单活跃会话，就不得不启动额外进程，也无法匹配 Zed 的客户端模型——该模型跟踪多个会话 id 和并发加载。多路复用引入了隔离风险：事件、提示词完成、取消、权限提示、配置选择以及可预测的后台 task id 绝不能跨越会话边界。
一个 ACP（Agent Client Protocol）自动化客户端可以在同一个 agent（智能体）子进程上保持多个对话。如果桥接层只支持单活跃会话，就不得不启动额外进程，也会阻止一个父控制器通过一条连接驱动多个独立子任务。多路复用引入了隔离风险：已提交的回答、提示词完成、取消、权限请求以及可预测的后台 task id 绝不能跨越会话边界。
## 决策
ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agent 作用域的回调使用 `ownedRecord`：在正向 map 中查找 `agent.session.id`，且仅当该记录拥有精确的 agent 对象时才接纳它，使外部的同 id 对象无法冒领会话。一条记录拥有其 agent 句柄、进行中的提示词、活跃的工具调用展示状态、待处理的空闲配置切换、会话 cwd 以及客户端能力快照。一个独立的 loading-id 集合在异步恢复之前预留每个 id，使两个流水线化的加载请求无法构造出重复的 agent；不同 id 可以并发加载。
ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agent 作用域的回调使用 `ownedRecord`：在正向 map 中查找 `agent.session.id`，且仅当该记录拥有精确的 agent 对象时才接纳它，使外部的同 id 对象无法冒领会话。一条记录拥有其 agent、精确的释放器，以及可选的进行中提示词和最终结算它的持久轮次号。会话 header 拥有其 cwd；桥接层不保留平行的工作区或客户端能力状态。
每个 `session/event` 和 `agent/status` 回调在发送或结算任何内容之前，先解析出所属记录。每个会话独立允许一个进行中的提示词。提示词记录一个日志水位线，捕获自己的 `turn/start`，并仅在匹配的 `turn/end` 到达时结算；来自已取消的前一轮次的迟到 end 不能 resolve 更新的提示词。`session/cancel` 定位到一条记录，只调用该 agent 的队列感知取消路径。
每个 `session/event` 回调在发送或结算任何内容之前，先解析出所属记录。每个会话独立允许一个进行中的提示词。提示词捕获自己源自用户消息的 `turn/start`，并仅在匹配的 `turn/end` 到达时结算；注入轮次、插件或 goal 的自主轮次，以及来自已取消的前一轮次的迟到 end 都不能 resolve 它。`session/cancel` 定位到一条记录，只调用该 agent 的队列感知取消路径。
权限归属使用对正向 map 的同一精确 agent 检查。ACP `approval/request` 应答器只向拥有发起请求的 agent 的编辑器会话发起提示，并将外部请求委托出去。用户交互引出同样按 agent 归属路由。每会话的沙箱和审批配置值只折叠该会话自身的事件，待处理的空闲切换存储在该记录上，直到下一轮次将其锚定。
权限归属使用对正向 map 的同一精确 agent 检查。ACP `approval/request` 应答器只为拥有发起请求的 agent 的会话发送一次性机器策略请求，并将外部请求或不带 call id 的请求委托出去。桥接层没有表单引导、配置选择或其他人机交互状态。
后台 bash 任务携带一个不透明的 owner token，其值等于所属会话 id。`bash_output` 和 `bash_kill` 在读取或终止之前，将调用方的 token 与执行器的任务归属进行比较；仅凭可预测的 task id 不能获得访问权。归属信息与执行器任务一起存储，因此工具插件重载不会擦除它。
后台 bash 任务携带一个不透明的 owner token，其值等于所属会话 id。`task_output` 和 `task_kill` 在读取或终止之前，将调用方的 token 与执行器的任务归属进行比较；仅凭可预测的 task id 不能获得访问权。归属信息与执行器任务一起存储，因此工具插件重载不会擦除它。
连接拆除时清空活跃 map，将每个待处理的提示词以取消状态结算，并并行 dispose（资源释放）所有 `AgentHandle`。每个句柄停止并等待其循环完成、在仍然附着时刷新会话、注销 agent 并移除会话。拆除操作被 memoize 化，由客户端断连和插件 dispose 共享。
@@ -24,13 +26,13 @@ ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agen
[ACP v1 明确允许一个连接上存在多个并发会话](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/get-started/architecture.mdx#L16-L24)，每个新会话都携带自己的主 `cwd`。本桥实现该会话级多路复用，其中包括[按会话 cwd 决策](../architecture/2026-07-02-fs-per-session-cwd.md)所记录的不同主工作区；它不会为每个会话创建一个 agent 子进程。
一个会话内部的多根项目是另一项可选能力：ACP 把[有效根目录定义为主 `cwd` 加 `additionalDirectories`](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/session-setup.mdx#L313-L367)。[Zed 仅在 agent 公布该能力时发送其余项目工作目录](https://github.com/zed-industries/zed/blob/ea77ca2818f3e059a2b61ecc7e63b67e01e1cec5/crates/agent_servers/src/acp.rs#L1139-L1145)，否则会[从会话请求中丢弃这些目录](https://github.com/zed-industries/zed/blob/ea77ca2818f3e059a2b61ecc7e63b67e01e1cec5/crates/agent_servers/src/acp.rs#L1454-L1472)。如其[已知限制](../../../../packages/ui/acp/README.md#known-limitations-and-deferred-work)所记录，桥不公布该能力，并拒绝非空值，因此当前 Zed 多根项目到达桥时只携带第一个工作目录。
一个会话内部的多根项目是另一项可选能力：ACP 把[有效根目录定义为主 `cwd` 加 `additionalDirectories`](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/session-setup.mdx#L313-L367)。自动化桥接层不公布任何多根能力，并拒绝非空的 `additionalDirectories`；如[包契约](../../../../packages/acp/acp/README.md#protocol-contract)所记录，每个全新会话恰好有一个工作区。
[标准传输是每个 stdio 连接一个由编辑器启动的 agent 子进程](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/transports.mdx#L17-L42)；多个编辑器连接因此需要多个子进程或自定义传输，而本决策保证的是一个连接内部存在多个会话。在该连接内，`ctx.sandboxPolicy` 把每个会话的 `cwd` 解析为其自己的 `workspace-write` 根目录，因此共享的 bash 和文件系统服务可以服务并发项目而不授予跨项目写入。这不会添加 ACP `additionalDirectories`；它只是从已经支持的「每会话一个主根目录」路径中移除了进程级根目录限制。
[标准传输是每个 stdio 连接一个 agent 子进程](https://github.com/agentclientprotocol/agent-client-protocol/blob/01beb5fb5eec60e9f516a80d85eb03594bac61e3/docs/protocol/v1/transports.mdx#L17-L42)；多个连接因此需要多个子进程或自定义传输，而本决策保证的是一个连接内部存在多个会话。在该连接内，`ctx.sandboxPolicy` 把每个会话的 `cwd` 解析为其自己的 `workspace-write` 根目录，因此共享的 bash 和文件系统服务可以服务并发项目而不授予跨项目写入。这不会添加 ACP `additionalDirectories`；它只是从已经支持的「每会话一个主根目录」路径中移除了进程级根目录限制。
## 曾考虑的替代方案
**每连接单活跃会话**：否决。增加进程开销，与目标客户端的多会话形态相矛盾，且并未消除编辑器端的多路复用需求。
**每连接单活跃会话**：否决。增加进程开销，并阻止程序化的父控制器多路复用可独立取消的工作。
**每会话 `ctx.extend()`**：否决。子上下文本身不会创建子插件 fiber，因此监听器仍属于桥接层 fiber。实际实现的桥接层使用全局监听器加显式 O(1) 解复用，以及每会话拥有的记录；agent 生命周期由 `AgentHandle` 管理。
@@ -38,10 +40,10 @@ ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agen
## 后果
N 个会话可以并发地进行流式输出、提示词、权限请求、配置切换和后台任务运行，而不会交错或跨会话结算。一个会话中的取消或 dispose 不影响相邻会话。桥接层为此付出了显式 map 和隔离测试的代价，但它不会为每个会话添加一组监听器，从而避免了长连接期间的监听器扇出。
N 个会话可以并发地返回已提交的回答、提交提示词、请求权限和运行后台任务，而不会交错或跨会话结算。一个会话中的取消不影响相邻会话。桥接层为此付出了显式 map 和隔离测试的代价，但它不会为每个会话添加一组监听器，从而避免了长连接期间的监听器扇出。
桥接层目前仍未暴露独立关闭单个活跃会话的协议方法。当前所有记录在连接拆除时一起离开；会话关闭/恢复的生命周期能力在 ACP 功能清单中仍处于延期状态。
桥接层不暴露独立关闭单个活跃会话的协议方法。所有记录在连接拆除时一起离开；会话导航与恢复属于 host API，而非这个自动化协议。
## 验证
多会话测试套件通过交错更新、独立的进行中提示词、定向取消、相同 id 与不同 id 的加载竞争、权限路由、配置隔离以及拆除来驱动并发会话。工具 bash 测试证明一个会话无法读取或终止另一个会话的后台任务。
多会话测试套件通过按路由投递的已提交回答、独立的进行中提示词、定向取消以及共享拆除来驱动并发会话；审批与输出边界套件覆盖权限路由和精确 agent 拒绝。工具 bash 测试证明一个会话无法读取或终止另一个会话的后台任务。

4
.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-15-code-mode.md: 94a95ba2c5760c0fed6ebfe09330546f401c42c4
2026-06-15-code-mode.zh.md: 0ba5d69258bce23a24db9a0b470ddb074840cba7
2026-06-15-code-mode.md: 8e964eeb36e430b58312427e45cf8e4a99582457
2026-06-15-code-mode.zh.md: 3de1adfcf287b69ca8307244bde35f286ce4b99d

2
.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md
View File

@@ -50,7 +50,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
**并发被序列化。** 每次 run 拥有一个分发队列，因此即使 `Promise.all` 也按提交顺序执行工具调用。结算时放弃尚未开始的排队调用。并行化需要每个工具的并发安全元数据。
**呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 ACP 和 TUI 会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。程序作为标题是因为 ACP execute 卡片可靠地渲染该字段，而某些客户端会省略 body 和 raw-input 内容。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
**呈现。** `run_code` 的 render intent 按[呈现意图 Agent Note](../architecture/2026-07-02-tool-render-intent-union.md)在此决定：`presentCall` 创建一个 `generic` 卡片，`kind: 'execute'`，以程序文本作为标题，并将同一程序文本作为 `rawInput`；`run_code` 有意不声明 `presentResult`，因此 TUI 和宿主/客户端运行时（Web）会通过通用原始内容回退机制，使用最终持久化的 `tool/result.content` 补全该卡片，其中包括捕获的日志，以及返回值、失败信息或 post-policy 输出落盘预览。这不是 `terminal` 卡片：该卡片的语义是「工作目录中的 shell 命令」，程序不是。参见[结果卡片完整性说明](../bug-fix/2026-07-20-code-mode-result-card-completeness.md)。
### 可观测性：`tool/code-dispatch`

4
.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-18-acp-terminal-and-tool-rendering.md: 166e52f8e659a78b1347279c61956ca1001e4939
2026-06-18-acp-terminal-and-tool-rendering.zh.md: 1623c8f51f9a1e0aacf374d182ab1c74dfa407cc
2026-06-18-acp-terminal-and-tool-rendering.md: e8426dbf1a0e3e4f9d9857baa19945cee6eee4b3
2026-06-18-acp-terminal-and-tool-rendering.zh.md: ff269e002a0ecea8c0bacf53fe85e553a6b9b9d5

2
.agents/notes/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.zh.md
View File

@@ -4,6 +4,8 @@ Status: implemented
[English](2026-06-18-acp-terminal-and-tool-rendering.md) | 中文
> 就 ACP 而言已被 [ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)取代。工具渲染意图对 UI 传输层仍然可用，但 ACP 不再将其投影为终端卡片。
## 问题
ACP（Agent Client Protocol）桥接层允许每个工具通过 `presentCall`/`presentResult` 自行控制调用渲染（见[工具调用 UI 呈现](2026-06-14-acp-agent-client-protocol.md)与 `packages/core/tools`）。对于 `bash`，我们将确切命令作为 `tool_call` 标题呈现，模型的 `description` 作为一个内容文本块，`kind: 'execute'`，完成后的输出包裹在 ` ```console ` 围栏文本块中。

4
.agents/notes/implemented/feature/2026-06-25-ask-user-question.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-25-ask-user-question.md: 9eab7aeb17774961dfc40224accdcfcbd5eb9d5f
2026-06-25-ask-user-question.zh.md: eb166acfef7ed8f7ab4eb3018bf161a9ecc3549e
2026-06-25-ask-user-question.md: 51b9a67bfc0fdc88d84a9fa51662d02b127f7925
2026-06-25-ask-user-question.zh.md: 4bd2c2b8664ba085919eb9d4b8c5dee92d4bf72e

14
.agents/notes/implemented/feature/2026-06-25-ask-user-question.zh.md
View File

@@ -18,7 +18,7 @@ agent（智能体）有时仅凭模型推理（inference）无法安全地继续
提供方返回 `{ answers: [{ id, selected, custom? }] }`。`selected` 始终是选中选项 label 的数组，因此单选和 `multi_select` 的答案共享同一种结果形状。`custom` 承载自由文本的「其他」答案；无选项的问题直接收集 `custom`。当 `custom` 存在时，它覆盖任何已选择的选项，`selected` 为空。支持部分完成的提供方使用现有的 `{ id, selected: [] }` 形状表示某项被有意跳过，在不扩展工具结果词汇的前提下保留其他答案。
`UserInteractionError` 继承 `HarnessError`，因此 `NO_PROVIDER`、`ASK_ABORTED`、ACP（Agent Client Protocol）取消或会话路由缺失等失败会以机器可路由的 `{ name, code }` 工具错误形式通过 `ctx.tools.execute()` 传出。这与结构化错误分类体系一致，使模型或包装插件能够区分「用户取消」与一般的抛出异常。
`UserInteractionError` 继承 `HarnessError`，因此 `NO_PROVIDER`、`ASK_ABORTED` 或请求归属缺失等失败会以机器可路由的 `{ name, code }` 工具错误形式通过 `ctx.tools.execute()` 传出。这与结构化错误分类体系一致，使模型或包装插件能够区分「用户取消」与一般的抛出异常。
## UI 映射
@@ -28,9 +28,7 @@ Web 输入区一次显示一个问题，同时在会话对象层保留每个请
`dsh-tui` 将每个问题渲染为键盘叠层，展示选项描述，支持单选、多选和自由格式自定义答案，并在中止、提供方 dispose（资源释放）或终端关闭时拒绝待处理的问题。批量请求和并发请求都会排队，确保同一时刻只有一个叠层占用键盘焦点。
`dsh-acp` 为 ACP 会话提供同一 seam。它通过 `ownedRecord` 解析调用方 `Agent`，要求位于 `agent.session.id` 的正向会话 map 记录拥有该精确 agent 对象，并为每个问题调用 ACP `unstable_createElicitation`（附带会话范围的表单）。单选选项变为 `choice` 字符串枚举；`multi_select` 选项变为 `choice` 数组枚举；无选项的问题使用必填的 `custom` 文本字段。如果客户端同时返回 `choice` 和非空 `custom`，以 custom 答案为准。ACP `decline`/`cancel`、缺失答案、缺失会话以及客户端不支持 elicitation，都会转为结构化的 `UserInteractionError`。
ACP 映射有意使用 elicitation 而非 `session/request_permission`。`request_permission` 仍保留给独立的权限门禁：它是围绕工具执行的 yes/no 或策略式授权协议。`ask_user_question` 是一个通用的信息收集工具，支持可选的自由格式答案，因此 ACP 表单 elicitation 是更贴合的协议。bridge 的会话路由与未来的权限门禁共享，但用户意图不同。
在桥接层还是编辑器 UI 时曾存在一个 ACP（Agent Client Protocol）elicitation 映射；[ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)移除了这第三个映射。
## 曾考虑的替代方案
@@ -38,18 +36,16 @@ ACP 映射有意使用 elicitation 而非 `session/request_permission`。`reques
**核心拥有的 ask-user 包。** 最初实现将 seam 和面向模型的工具分别放在 `packages/core` 和 `packages/ui`，但两者描述的是同一个由 UI 支撑的人机交互功能。seam 仍然是提供方无关的，但它不是像会话、工具或 agent 注册表那样的无提供方核心基础设施。将 `dsh-user-interaction` 和 `dsh-tool-ask-user` 一起放在 `packages/ui` 下，使包的划分与产品边界一致：应用和 bridge 提供人类答案的提供方，stdio 应用选择性加载面向模型的工具。
**ACP `session/request_permission`。** 权限请求是围绕工具执行的授权；`ask_user_question` 是带可选自由格式答案的信息收集。将权限用于通用提问会混淆两个不同的产品概念，并使未来的权限门禁更难推理。
**用权限请求处理通用提问。** 权限请求是对工具执行的授权；`ask_user_question` 是带可选自由格式答案的信息收集。复用权限通道会混淆两个不同的产品概念。
**循环级别的暂停原语。** agent loop 已经知道如何等待工具调用并从工具结果恢复。添加新的循环特殊分支会重复这一异步形状，并迫使每个循环实现都了解一个 UI 关注点。
## 后果
ACP elicitation 目前在 SDK 中标记为 unstable。回退仍然是结构化的：如果客户端未实现它，工具返回 `ASK_FAILED` 而非挂起。后续 ACP 稳定化可能重命名或重塑该方法；该迁移应限制在 `dsh-acp` 内部，因为核心 `ctx.userInteraction` 词汇是提供方无关的。
该功能赋予模型一个强大的暂停原语，因此提示词引导很重要。工具描述告诉模型：提问要简洁，尽可能使用选项。产品策略后续可以包装 `tools/execute` 来限制工具何时可用，但循环不应对其做特殊处理。
`dsh-user-interaction` 和 `dsh-tool-ask-user` 都位于 `packages/ui`，因为它们共同构成一个面向产品的人机交互能力。`agent-core` 不加载工具或提供方。`dsh-tui-demo` 选择性加载 seam、TUI 提供方和面向模型的工具。`dsh web` 在 host 运行时启动 seam/提供方，并通过选定的 Web question 插件暴露该工具。`acp-agent` 默认只保留 `userInteraction` seam/提供方：ACP elicitation 支持仍取决于客户端，因此 ACP 叶节点必须在其客户端能完成 elicitation 请求后才有意加载面向模型的工具。
`dsh-user-interaction` 和 `dsh-tool-ask-user` 都位于 `packages/ui`，因为它们共同构成一个面向产品的人机交互能力。`agent-core` 不加载工具或提供方。`dsh-tui-demo` 选择性加载 seam、TUI 提供方和面向模型的工具。`dsh web` 在 host 运行时启动 seam/提供方，并通过选定的 Web question 插件暴露该工具。ACP 自动化应用既不挂载 seam 也不挂载该工具。
## 测试
单元覆盖率固定了以下场景：提供方注册/释放、重复提供方拒绝、提供方就绪前中止、空问题拒绝、通过 `ctx.tools.execute()` 传出的结构化工具错误、批量答案、多选答案、自定义答案、显式按项跳过，以及模型 schema（包括移除 `value`、`recommended`、`allow_custom` 和 `desc`）。TUI 测试覆盖选项描述、排队请求、关闭/中止清理、无选项自由格式输入、无效选择、重复多选和批量问题流。ACP bridge 测试驱动一个真实的内存 ACP 连接（使用真实的 `ask_user_question` 工具），验证选中选项、custom 覆盖 choice、多选和无选项自由格式 elicitation 路径能继续 agent loop。Web 测试固定稳定 id 重放、响应校验、首个响应胜出的结算、重复和迟到响应、整个请求的取消与拥有方中止的区别、单选后前进、IME 安全的 Enter 提交、按项跳过保留、输入区接管、结构化批量提交，以及常规输入区的恢复。
单元覆盖率固定了以下场景：提供方注册/释放、重复提供方拒绝、提供方就绪前中止、空问题拒绝、通过 `ctx.tools.execute()` 传出的结构化工具错误、批量答案、多选答案、自定义答案、显式按项跳过，以及模型 schema（包括移除 `value`、`recommended`、`allow_custom` 和 `desc`）。TUI 测试覆盖选项描述、排队请求、关闭/中止清理、无选项自由格式输入、无效选择、重复多选和批量问题流。Web 测试固定稳定 id 重放、响应校验、首个响应胜出的结算、重复和迟到响应、整个请求的取消与拥有方中止的区别、单选后前进、IME 安全的 Enter 提交、按项跳过保留、输入区接管、结构化批量提交，以及常规输入区的恢复。

4
.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-29-todo-write-tool.md: bf5fceaafd475224914212beb460fdbc42e3dd68
2026-06-29-todo-write-tool.zh.md: 3afc03a393284e2a9c2d6e234bc95f0faebbfb48
2026-06-29-todo-write-tool.md: df1bee2801b0e01b290b63f6edbe2e5b1be80cb7
2026-06-29-todo-write-tool.zh.md: 7fa5cb2aad2b32ef0662df04ff6576be14a3a8e7

24
.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
View File

@@ -6,31 +6,27 @@ Status: implemented
## 问题
harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃任务明确（最多一个活跃，有剩余工作时恰好一个）；同时为人类提供实时进度清单。ACP（Agent Client Protocol）协议原生支持 `plan` sessionUpdate，编辑器（Zed）已能渲染它，但 bridge 从未发出过。调研的所有参考编码 agent（智能体）（claude-code、opencode、codex、oh-my-pi、pi）都提供了某种形式的此功能；本 harness 此前没有。
harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃任务明确（最多一个活跃，有剩余工作时恰好一个）；同时为交互式宿主提供实时进度清单。调研的所有参考编码 agent（智能体）（claude-code、opencode、codex、oh-my-pi、pi）都提供了某种形式的此功能；本 harness 此前没有。
## 决策
新增一个面向模型的 `todo_write(todos: [{ content, status }])` 工具，其整列表状态作为新的 `todo/write` `SessionEventMap` 变体存储在事件溯源的会话日志上。stdio UI 和 ACP bridge 均从现有的 `session/event` 渲染；ACP bridge 将列表映射为 `plan` sessionUpdate。
新增一个面向模型的 `todo_write(todos: [{ content, status }])` 工具，其整列表状态作为新的 `todo/write` `SessionEventMap` 变体存储在事件溯源的会话日志上。交互式宿主从持久事件渲染；TUI 直接折叠它，而[仅面向自动化的 ACP（Agent Client Protocol）桥接层](../simplification/2026-07-23-acp-automation-only-protocol.md)有意省略 todo 展示。
### 整列表替换，三态 status
模型每次调用发送完整列表；新列表替换旧列表（回放时 last-write-wins）。这是 claude-code V1、opencode 和 codex `update_plan` 共同采用的形状，也是模型训练最多的形状——没有逐项 id，没有 delta 协议。`status` 恰好是 `pending | in_progress | completed`：与 codex `update_plan` 相同的三元组，且关键的是**与 ACP `PlanEntryStatus` 完全一致**，bridge 因此可以 1:1 映射，无需有损转换。
模型每次调用发送完整列表；新列表替换旧列表（回放时 last-write-wins）。这是 claude-code V1、opencode 和 codex `update_plan` 共同采用的形状，也是模型训练最多的形状——没有逐项 id，没有 delta 协议。`status` 恰好是 `pending | in_progress | completed`，与 codex `update_plan` 相同的三元组；在 bridge 还把 todo 列表投影为 `plan` 更新时，它也与 ACP `PlanEntryStatus` 1:1 对应，该映射已随[仅面向自动化的 ACP 契约](../simplification/2026-07-23-acp-automation-only-protocol.md)退役。
### 状态在会话日志上，而非服务
列表作为 `todo/write` 事件追加到日志，携带完整的 `{ todos }` 快照。harness 是事件溯源的——LLM（大语言模型）历史、工具调用和轮次结构都在日志上——所以 todo 列表也在那里。这免费获得了持久性、回放和 `session/load` 重建：重新打开的会话从最后一条 `todo/write` 重新推导当前列表，ACP bridge 在加载时重新发出 `plan`，无需独立的持久化后端、无需重新注水的内存服务、无需额外接线。一个内存中的 `ctx.todos` 服务需要重新发明以上所有。
列表作为 `todo/write` 事件追加到日志，携带完整的 `{ todos }` 快照。harness 是事件溯源的——LLM（大语言模型）历史、工具调用和轮次结构都在日志上——所以 todo 列表也在那里。这免费获得了持久性、回放和恢复重建：重新打开的会话从最新的 `todo/write` 重新推导当前列表，无需独立的持久化后端、无需重新注水的内存服务、无需额外接线。一个内存中的 `ctx.todos` 服务需要重新发明以上所有。
### 不是 surface 事件
`todo/write` 被有意排除在 `SurfaceEventType` 之外。surface 是产出 LLM 消息历史（`deriveMessages()`）的投影；todo write 不产生对话消息。因此它不携带 `surfaceOp`，不加入有序 surface，不进入 `deriveMessages()`——它是持久、可回放的 *UI* 状态，与对话并行传输但不属于对话的一部分。（dev-mode 不变式仍要求它位于一个打开的轮次内，而它始终如此：它在工具调用的步骤中途追加。）
### Priority 仅在 ACP 边界合成
ACP 的 `PlanEntry` 要求 `content` + `priority` + `status`，但 `TodoItem` 没有 priority——模型从不推理它。与其在 schema 中增加一个模型每次都必须提供的字段，bridge 在构建 `plan` 时为每条条目合成常量 `priority: 'medium'`。Priority 是 ACP 协议格式（wire format）的要求，不是 harness 概念，因此它恰好存在于需要它的边界上。
### 相比 claude-code V1 舍弃的字段：`activeForm`、id、priority
claude-code V1 的条目是 `{ content, status, activeForm }`；后来（V2）增加了 id、依赖和所有权——但仅为支持 agent *集群*（磁盘持久、锁保护、逐项变更）。本工具将条目保持在最小集：`{ content, status }`。不要 `activeForm`（现在进行时标签）——UI 直接展示 `content`；不要 id——整列表替换不需要稳定标识；不要 priority——见上文。每舍弃一个字段，模型每次调用就少产出一项。
claude-code V1 的条目是 `{ content, status, activeForm }`；后来（V2）增加了 id、依赖和所有权——但仅为支持 agent *集群*（磁盘持久、锁保护、逐项变更）。本工具将条目保持在最小集：`{ content, status }`。不要 `activeForm`（现在进行时标签）——UI 直接展示 `content`；不要 id——整列表替换不需要稳定标识；不要 priority——它只曾是 ACP `PlanEntry` 的协议格式（wire format）要求，在 bridge 边界合成为常量而非建模，并已随该投影一起离开。每舍弃一个字段，模型每次调用就少产出一项。
### 单一所有者——无集群机制（YAGNI）
@@ -47,18 +43,18 @@ schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重
## 测试
四个层级，预先设计：
- **单元测试**——会话事件（append/snapshot-clone/last-write-wins/not-on-surface）；工具（schema 形状、通过真实 `ctx.tools.execute` 的参数校验、值校验、事件追加与替换、非 agent 拒绝、`presentCall`、HMR（热模块替换）安全性）；ACP `todosToPlan` 映射；stdio 渲染分支。
- **单元测试**——会话事件（append/snapshot-clone/last-write-wins/not-on-surface）；工具（schema 形状、通过真实 `ctx.tools.execute` 的参数校验、值校验、事件追加与替换、非 agent 拒绝、`presentCall`、HMR（热模块替换）安全性）；以及 TUI 折叠。
- **真实 Loader 路径**——插件通过 `Loader.unwrapExports` 运行，断言命名空间导出形状存活（它有 `inject`，因此一个意外的 default 导出会在加载时崩溃——postmortem/0001）。
- **全循环集成**——一个脚本化的 mock 模型通过真实 agent loop（智能体循环）调用 `todo_write`；`todo/write` 事件落地，第二次调用替换它。
- **`session/load` 回放**——持久化的 `todo/write` 在新的 ACP bridge 加载会话时重新发出 `plan` 更新。
- **带密钥 e2e + 快照**——真实提示词诱导一次 `todo_write`；快照预期输出获得 `plan` 通知和日志事件。
- **恢复/回放**——持久化的 `todo/write` 折叠回当前任务列表。
- **带密钥 e2e + 快照**——真实提示词诱导 `todo_write`；组装后的快照固定日志事件和交互式渲染。
## 曾考虑的替代方案
- **内存中的 `ctx.todos` 服务**——需要重新发明日志免费提供的持久性、回放和 `session/load` 重建。
- **内存中的 `ctx.todos` 服务**——需要重新发明日志免费提供的持久性、回放和恢复重建。
- **逐项 delta 协议**——仅在共享多所有者列表时需要，超出当前范围；整列表替换更简单，且与参考实现一致。
- **工具放在 `core/` 中**——`todo_write` 是注册在 `ctx.tools` 上的扩展工具，不属于主干；它像其他工具族一样位于自己的 `packages/todo/` 分组中。
## 后果
todo 列表是持久、可回放的会话状态：持久化的 `todo/write` 在 `session/load` 时重新发出编辑器的 `plan` 更新，日志（而非插件内存）是唯一真源。整列表替换意味着每次更新一次工具调用，last-write-wins；没有需要协调的 delta 协议。事件不进入 surface，因此 todo 更新永远不会扰动推导出的模型历史——模型只看到自己的工具调用和结果。
todo 列表是持久、可回放的会话状态：交互式宿主从最新持久化的 `todo/write` 重新推导它，日志（而非插件内存）是唯一真源。整列表替换意味着每次更新一次工具调用，last-write-wins；没有需要协调的 delta 协议。事件不进入模型 surface，因此 todo 更新永远不会扰动推导出的模型历史——模型只看到自己的工具调用和结果。

4
.agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-30-hook-bridges.md: b6b0894e5551563187b1631e8c641e326fa166b0
2026-06-30-hook-bridges.zh.md: 5f3adef958738d9d23c159c388be35b89f321828
2026-06-30-hook-bridges.md: c207b6901155925215548676364e903f5de2f29b
2026-06-30-hook-bridges.zh.md: d396279d7ed1991536da2cea39e2aec5e50960c2

4
.agents/notes/implemented/feature/2026-06-30-hook-bridges.zh.md
View File

@@ -31,7 +31,7 @@ harness 的扩展面是其类型化的拦截 seam（见[拦截 seam Agent Note](
| `subagent/start`（emit） | additionalContext → 注入到存活的进程内 subagent；远程 subagent 无本地注入目标 | 本桥接不支持 |
| `subagent/end`（emit） | 仅观察 | 本桥接不支持 |
CC 桥接的 `ask` 结果是一条真正的权限路径，而非终态桥接决策：`dsh-tools` 通过可选的[审批 seam](2026-07-06-approval-seam.md) 来解析它。组合式 ACP 应答器向拥有该会话的编辑器会话发起提示，`allowed-once` 后继续执行；如果没有 ApprovalService 或应答器，调用以 `deny` 安全关闭。
CC 桥接的 `ask` 结果是一条真正的权限路径，而非终态桥接决策：`dsh-tools` 通过可选的[审批 seam](2026-07-06-approval-seam.md) 来解析它。ACP 自动化客户端可以应答所属会话的一次性机器策略请求，`allowed-once` 后继续执行；如果没有 ApprovalService 或应答器，调用以 `deny` 安全关闭。
### 上下文来源始终是插件（误标签防护）
@@ -55,7 +55,7 @@ Claude Code 始终导出 `CLAUDE_PROJECT_DIR`，常见的未修改钩子引用 `
## 推迟的兼容性缺口
- **工具输入重写。** CC/Codex 的 `updatedInput` 被记录日志并发出警告，但不予执行——输入重写是一个推迟的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)），因为 pre-execution 参数被 `tool/call` 审计、`assistant/message` 历史和 ACP/tool-bash 展示共同读取，诚实的重写是一个设计单元，而非一个字段。
- **工具输入重写。** CC/Codex 的 `updatedInput` 被记录日志并发出警告，但不予执行——输入重写是一个推迟的一致性设计问题（见 [pre-tool-input-rewrite Agent Note](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)），因为 pre-execution 参数被 `tool/call` 审计、`assistant/message` 历史和工具展示共同读取，诚实的重写是一个设计单元，而非一个字段。
- **Stop 循环防护**（`TODO(stop-loop-guard)`）。Claude Code 提供 `stop_hook_active` 并在连续八次阻塞后覆盖钩子；Codex 提供 `stop_hook_active` 但未记录等效上限。两个桥接始终报告 `false`，因此一个无条件阻塞的 Stop 钩子会在每一步强制继续——在状态追踪落地之前，钩子作者必须自行限制。
- **钩子 `continue:false`（硬停止）。** 钩子可以请求终止整个运行（CC/Codex `continue:false`）；共享合并将其折叠为 `MergedHookOutcome.stop`/`stopReason`，但没有桥接对其采取行动（`TODO(hook-continue-false)`）——拦截 seam 尚无「硬停止 agent」原语（Decision 阻塞/引导的是单个点，而非整个运行）。与循环防护工作一同推迟；停止请求记录在 `hook/result` 日志中，钩子在此期间保留其逐点效果（决策/上下文）。
- **配置发现。** 路径在 `cordis.yml` 中显式指定且为进程级（见上文）；完整的多层 CC/Codex 优先级遍历、按会话的项目本地发现以及信任/hash 模型未被重新实现（`TODO(per-session-hook-config)`）。

4
.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-30-interception-seams.md: 8af489d3f575dd457e1981e433330f08cefa2043
2026-06-30-interception-seams.zh.md: 3886ed21504abfe14a2ccb344d7aa0d3f8d25064
2026-06-30-interception-seams.md: 81799f4c6e3e7a4c6b9605cd97f5728b99d11995
2026-06-30-interception-seams.zh.md: 65ae16842c632641e7ac65908162f4784dc6e1e0

2
.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md
View File

@@ -45,7 +45,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
### 工具执行前输入重写是一个独立的一致性决策
`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，ACP 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该契约属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，UI 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该契约属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
### 边界

4
.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-06-30-session-store-fork-api.md: 4e4ea7f1d3aa3290bdb21999a292dbdfd016302e
2026-06-30-session-store-fork-api.zh.md: d17daa464ad59c6b5ac4d5041b4af30c44321fa7
2026-06-30-session-store-fork-api.md: 13d411e915b2e34b15a12e632f1a5e047f4aeedc
2026-06-30-session-store-fork-api.zh.md: bcf15eb581af3993ed2d71a2b7dc604faa6e4433

2
.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.zh.md
View File

@@ -40,4 +40,4 @@ class SessionStore extends Service {
公开接口保持精简且易于发现：活跃会话分支是 `ctx.sessions` 的一部分，紧邻 `create({ seed })`，而非一个独立服务或一对两步辅助函数。持久化继续通过现有的 `session/created` 和 `session/flush` 行为运作：fork 出的子会话以种子事件开始生命，因此现有后端只需持久化该种子一次，并在 header 中保存 `parentSession`／`seedLength`。
v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备 transcript（文本记录）/快照覆盖后才广播该能力；本 Agent Note 不添加面向编辑器的更新，因此当前不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖，而本 API 则获得专门的 `dsh-session` 单元测试加 JSONL 持久化覆盖。
v1 范围仍然排除 ACP（Agent Client Protocol） `session/fork`、对未加载的已持久化会话的 fork、面向模型的工具，以及 subagent 重构。如果未来添加 ACP 方法，应在具备协议与快照覆盖后才广播该能力；本 Agent Note 不添加任何 ACP 协议行为，因此不需要 ACP 快照。fork 子会话的回放仍由现有的[种子边界测试 Agent Note](../testing/2026-06-22-fork-child-replay-seed-boundary.md) 覆盖，而本 API 则获得专门的 `dsh-session` 单元测试加 JSONL 持久化覆盖。

4
.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-05-dynamic-workflows.md: 4c8606fb617b3fb6b2e8ad9c35d77c585b1fe8b1
2026-07-05-dynamic-workflows.zh.md: 757eafb5d21f42b2ca529ebeb6b16eb8205e823d
2026-07-05-dynamic-workflows.md: bba62098c66477a3f1929f9029e81c645bfc4d41
2026-07-05-dynamic-workflows.zh.md: 6aa1ce63f0edf9dbf296d12d3bc0c62594fa33a6

2
.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md
View File

@@ -60,7 +60,7 @@ worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够
- **嵌套 `workflow()`**、**token `budget`**，以及 `effort`/`isolation`/`agentType` agent 选项（每个都以命名延迟的消息大声拒绝）。
- **整体运行的挂钟超时**：取消总能释放调用方（result 在宽限期内 settle），因此总运行时间上限是后台重设计的策略旋钮，不是此处的正确性需求。
- **超越 worker 线程的引擎加固**：在同一 seam 背后使用 isolated-vm 或独立进程引擎（真正的沙箱化；内存限制）。
- **ACP 进度 UI**（基于 `workflow/*` 事件的 `/workflows` 风格视图）；事件已为此而存在。
- **面向人类界面的进度 UI**（基于 `workflow/*` 事件的 `/workflows` 风格视图）；事件已为此而存在。
- **ACP 后端结构化输出**和 **`toolFilter`**（两者仍以能力标志 `false` 门控）。
## 曾考虑的替代方案

4
.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-05-skill-system.md: 3c328adf09ab0f6ad3388a01bac3661d45c9247e
2026-07-05-skill-system.zh.md: ba30a3735b73b00afb46baa24f969fd687a759b5
2026-07-05-skill-system.md: 95772067b3b224f15fd290876c297eccbe5ab97e
2026-07-05-skill-system.zh.md: 589410076b6da1b108b01f55bf217001b2a8404f

4
.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md
View File

@@ -12,7 +12,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
## 决策
`@deepseek-ai/dsh-skill` 是纯提供方注册表（`ctx.skills`），`@deepseek-ai/dsh-skill-local` 是随附的本地文件系统提供方，`@deepseek-ai/dsh-tool-skill` 负责会话前缀目录与面向模型的 loader 工具。`dsh-agent-spine-demo` 默认加载注册表、本地提供方和消费方，使 stdio 与 ACP（Agent Client Protocol）应用获得相同行为，同时嵌入式或远程提供方可在不修改注册表或消费方的前提下贡献 skill。其 `skills` 配置将 `registry`、`local` 和 `tool` 分支分别转发给对应的所有者。
`@deepseek-ai/dsh-skill` 是纯提供方注册表（`ctx.skills`），`@deepseek-ai/dsh-skill-local` 是随附的本地文件系统提供方，`@deepseek-ai/dsh-tool-skill` 负责会话前缀目录与面向模型的 loader 工具。`dsh-agent-spine-demo` 默认加载注册表、本地提供方和消费方，使 TUI、headless 与 ACP（Agent Client Protocol）应用获得相同行为，同时嵌入式或远程提供方可在不修改注册表或消费方的前提下贡献 skill。其 `skills` 配置将 `registry`、`local` 和 `tool` 分支分别转发给对应的所有者。
提供方插件在 `apply()` 期间同步注册。提供方成员资格是由直接 effect 持有的状态：注册与 dispose（资源释放）同步地使已完成的目录失效，发现操作按需读取当前提供方映射而非监听注册表变更事件。提供方目录从等待的 `list()` 调用返回排序后的候选项，远程提供方在此过程中执行初始化、认证和发现，同时遵守查找的 abort 信号。注册表校验每个候选项，按排名、提供方注册顺序和提供方内部顺序以先到先得方式解决同名 skill 冲突，然后按 skill 名称排序摘要以保证消费方获得确定性结果。它仅缓存已完成的目录快照，并在发现过程中提供方/运行时修订版本发生变化时重试，因此卸载操作不会将一个陈旧且不可解析的 skill 冻结到会话前缀中。运行时 `ctx.skills.register(...)` 仍作为嵌入式进程内 skill 的便捷方式保留，使用 project 优先于 user 的优先级；`runtime` 保留为注册表拥有的提供方名称。
@@ -32,7 +32,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和
**将完整 skill 正文注入每条系统提示词。** 否决，因为这破坏了渐进式披露，使每个请求都为可能不适用的指令付出代价。
**仅以斜杠命令暴露 skill。** 否决，因为模型主动加载是核心能力；斜杠/ACP 命令广播不改变发现机制。
**仅以斜杠命令暴露 skill。** 否决，因为模型主动加载是核心能力；面向人类的命令广播不改变发现机制。
**将本地文件系统扫描直接放入 `ctx.skills`。** 否决，因为编码 agent、Web agent 和未来的插件生态需要不同的 skill 来源。提供方注册表与 subagent seam 镜像：注册表拥有冲突解决和消费方，实现拥有加载。

4
.agents/notes/implemented/feature/2026-07-06-approval-seam.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-06-approval-seam.md: e28587e0185530164f300562f7dd5e57255ac515
2026-07-06-approval-seam.zh.md: 94ffb330cd36ae88975e8ae9d579b3b4606a5c25
2026-07-06-approval-seam.md: 852108f22be22eeba4578032924adb546ee10985
2026-07-06-approval-seam.zh.md: 9a08f333e0859e6d71f40b039f4b441028c38dc3

40
.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md
View File

@@ -6,13 +6,13 @@ Status: implemented
## 问题
两个调用方需要向人类提出同一个问题——「这个具体操作可以继续吗？」：`tools/pre-execute` 的 `ask` 决策（包括 Claude-Code 钩子桥的 `permissionDecision: ask`）以及[沙箱 Agent Note](2026-07-06-sandbox.md) 中拒绝后的一次性升级重试。一个共享的 seam 使它们无需各自发明独立的结果词汇、UI 路由、取消机制和审计轨迹，同时保证没有 UI 的部署永远不会批准一个无法应答的请求。
两个调用方需要同一个封闭决策——「这个具体操作可以继续吗？」：`tools/pre-execute` 的 `ask` 决策（包括 Claude-Code 钩子桥的 `permissionDecision: ask`）以及[沙箱 Agent Note](2026-07-06-sandbox.md) 中拒绝后的一次性升级重试。一个共享的 seam 使它们无需各自发明独立的结果词汇、通道路由、取消机制和审计轨迹，同时保证没有应答者的部署永远不会批准一个无法应答的请求。应答者可以是交互式宿主，也可以是自动化控制器。
路由问题的核心是归属：审批提示必须到达拥有发起请求的 agent（智能体）的编辑器会话（ACP（Agent Client Protocol）桥在一条连接上多路复用 N 个会话），对无人拥有的 agent（进程内 subagent、测试）失败关闭，并且不侵入没有组合 UI 的部署（headless、CI）。
路由问题的核心是归属：权限请求必须到达拥有发起请求的 agent（智能体）的通道，对无人拥有的 agent 失败关闭，并且不侵入没有组合应答者的部署。
## 决策
一个包 `dsh-user-approval`（`packages/ui/user-approval`），拥有词汇表和 `ctx.approval` 服务——即机制。策略——谁来应答、某个会话是否需要被询问——不在其中：应答者是 `approval/request` waterfall 监听器，由拥有通道的插件注册（ACP 桥、未来的终端 UI、测试脚本），而每会话的策略层可以在任何人类介入之前做出决定。消费方（`dsh-tools` 的 ask 路由、沙箱升级门禁）将问题解析为一个封闭结果，并从中派生各自的工具结果。刻意设计为一个包，而非能力 seam 的三包拆分（见「替代方案」）。
一个包 `dsh-user-approval`（`packages/ui/user-approval`），拥有词汇表和 `ctx.approval` 服务——即机制。策略——谁来应答、某个会话是否需要被询问——不在其中：应答者是 `approval/request` waterfall 监听器，由拥有通道的插件注册（ACP（Agent Client Protocol）桥、宿主适配器、测试脚本），而每会话的策略层可以在任何通道介入之前做出决定。消费方（`dsh-tools` 的 ask 路由和沙箱升级门禁）将问题解析为一个封闭结果，并从中派生各自的工具结果。刻意设计为一个包，而非能力 seam 的三包拆分（见「替代方案」）。
### 部署如何使用它
@@ -25,11 +25,11 @@ Status: implemented
# policy: never # deployment default for sessions without an override; 'ask' when omitted
```
仅有这条条目只提供机制，不提供通道：没有组合应答者时，每次 ask 都解析为 `unavailable`，发起请求的工具调用被拒绝——失败关闭无需配置。组合 ACP 应用（`@deepseek-ai/dsh-acp-demo`，如 [acp-agent 示例的默认树](../../../../examples/acp-agent/README.md)）即可闭环：其桥注册一个应答者，通过 `session/request_permission` 向拥有该会话的编辑器发出提示，于是钩子的 `ask` 或升级请求会以一次性 Allow/Reject 提示的形式呈现，附着在已流式输出的工具调用上。`policy: never` 是无人值守姿态：每次 ask 确定性地自动拒绝，在系统提示词中声明，无人类参与。`policy` 在插件加载时对照封闭列表校验；非法值直接抛异常。
仅有这条条目只提供机制，不提供通道：没有组合应答者时，每次 ask 都解析为 `unavailable`，发起请求的工具调用被拒绝——失败关闭无需配置。组合 ACP 应用（`@deepseek-ai/dsh-acp-demo`，如 [acp-agent 示例的默认树](../../../../examples/acp-agent/README.md)）即可闭环：其[仅面向自动化的桥接层](../simplification/2026-07-23-acp-automation-only-protocol.md)注册一个应答者，向拥有该会话的客户端发送 `session/request_permission`，携带精确的工具调用 id 和一次性 allow/reject 选项。`policy: never` 是无人值守姿态：每次 ask 确定性地自动拒绝，并在系统提示词中声明。`policy` 在插件加载时对照封闭列表校验；非法值直接抛异常。
组合部署的可观测行为：`allowed-once` 仅允许该次调用继续；拒绝、关闭和通道缺失以三种不同原因拒绝，模型可以区分；轮次内成功的请求会在发起请求的 agent 的会话日志上落一对持久的 `approval/asked`/`approval/decided` 事件；授权不会在发起请求的调用结束后继续存在。空闲时的请求或审计追加失败会拒绝，而不会返回未经审计的决策。
以下是该组合下的一次 ask，逐字取自沙箱示例录制的 `escalation-approved` 场景——模型请求沙箱升级，门禁发起 ask，桥向拥有该会话的编辑器发出提示，用户点击 Allow once：
以下是该组合下的一次 ask，取自沙箱示例录制的 `escalation-approved` 场景——模型请求沙箱升级，门禁发起 ask，自动化客户端选择 Allow once：
```
tool/call bash {"command": "printf 'escalated\n' > escalated.txt && cat escalated.txt",
@@ -40,12 +40,12 @@ approval/asked {"toolName": "bash", "callId": "call_00_…",
→ session/request_permission {"toolCall": {"toolCallId": "call_00_…"},
"options": [{"optionId": "allow-once", "name": "Allow once", "kind": "allow_once"},
{"optionId": "reject-once", "name": "Reject", "kind": "reject_once"}]}
← the user picks "Allow once" on the prompt the editor attaches to the streamed bash call
← the client selects "Allow once"
approval/decided {"outcome": "allowed-once"}
tool/result "escalated" — this one call ran under the wider mode; the grant died with it
```
`escalation-rejected` 孪生场景以 `{"outcome": "rejected"}` 结束：不执行任何操作，模型的结果携带发起方的逐字失败关闭文本（`the user rejected escalating this command to "workspace-write"`）。钩子的 `permissionDecision: ask` 走完全相同的协议；只有发起方和拒绝文本不同（§ dsh-tools 中的 Ask 路由）。在 headless 环境下，同一请求完全跳过提示，直接结算为 `unavailable`。
`escalation-rejected` 孪生场景以 `{"outcome": "rejected"}` 结束：不执行任何操作，模型的结果携带发起方的逐字失败关闭文本（`the user rejected escalating this command to "workspace-write"`）。钩子的 `permissionDecision: ask` 走完全相同的协议；只有发起方和拒绝文本不同（§ dsh-tools 中的 Ask 路由）。没有应答者时，同一请求直接结算为 `unavailable`。
### 设计细节
@@ -55,11 +55,11 @@ tool/result "escalated" — this one call ran under the wider mode; the gra
应答者是 `approval/request` waterfall 监听器。零监听器会一路委派至 `unavailable`；识别该 agent 的监听器占用先到先得的决策槽，而不识别的监听器必须调用 `next()` 委派。监听器随其 fiber dispose，因此卸载通道会失败关闭。由于兄弟插件的注册顺序不确定，部署应组合一个终端应答者，并保留 `prepend` 给「决策或委派」门禁。
`ApprovalRequest` 携带发起请求的 `agent`、`toolName`、可选的精确 `callId`、人类可读的 `reason` 和可选的 `signal`。它使用 `CallId` brand 而不导入依赖本 seam 的 `dsh-tools`。工具参数仍留在 UI 通过 `callId` 引用的、已流式输出的调用上。
`ApprovalRequest` 携带发起请求的 `agent`、`toolName`、可选的精确 `callId`、人类可读的 `reason` 和可选的 `signal`。它使用 `CallId` brand 而不导入依赖本 seam 的 `dsh-tools`。通道适配器可按 `callId` 关联任何更丰富的调用状态；审批请求本身不重复携带工具参数。
#### dsh-tools 中的 Ask 路由
`ToolRegistry.execute()` 在派发前解析 `ask`：`allowed-once` 继续执行，而拒绝、取消和通道不可用产生三种不同的拒绝原因。机会性消费 `ctx.get('approval')`，让缺失或未挂载的服务失败关闭而不阻塞注册表 fiber。无 agent 的执行同样失败关闭，因为它既没有审计会话，也没有 UI 所有者。
`ToolRegistry.execute()` 在派发前解析 `ask`：`allowed-once` 继续执行，而拒绝、取消和通道不可用产生三种不同的拒绝原因。机会性消费 `ctx.get('approval')`，让缺失或未挂载的服务失败关闭而不阻塞注册表 fiber。无 agent 的执行同样失败关闭，因为它既没有审计会话，也没有通道所有者。
#### 每会话策略层
@@ -67,9 +67,9 @@ seam 还拥有[沙箱 Agent Note](2026-07-06-sandbox.md) 所描述的会话级 `
#### ACP 应答者
ACP 桥只应答其正向会话映射所拥有的精确 agent 对象。它把 `session/request_permission` 附着到既有 `callId`，声明一次性的 allow/reject 选项，单独映射取消，并且绝不批准未知选项。外部或无调用标识的请求会委派；客户端 RPC 失败变为 `unavailable`。钩子和 `tools/pre-execute` 决定一次调用是否需要询问。
ACP 桥只应答其会话映射所拥有的精确 agent 对象。它携带既有 `callId` 发送 `session/request_permission`，声明一次性的 allow/reject 选项，单独映射取消，并且绝不批准未知选项。外部或无调用标识的请求会委派；客户端 RPC 失败变为 `unavailable`。钩子和 `tools/pre-execute` 决定一次调用是否需要询问。该通道是自动化客户端与其 agent 之间的机器策略，不是 ACP 展示层。
应答者通过 [ACP 支持 Agent Note](2026-06-14-acp-agent-client-protocol.md) 描述的桥精确 agent 归属检查进行路由，实现了[多会话 Agent Note](2026-06-14-acp-multi-session.md) 要求的每会话权限归属。
应答者通过 [ACP 支持 Agent Note](2026-06-14-acp-agent-client-protocol.md) 描述的桥精确 agent 归属检查进行路由，保留了[多会话 Agent Note](2026-06-14-acp-multi-session.md) 要求的每会话权限归属。
#### 审计，以及模型看到什么
@@ -88,13 +88,13 @@ ACP 桥只应答其正向会话映射所拥有的精确 agent 对象。它把 `s
## 延后
- **`allow_always` 授权存储**：兑现持久授权意味着设计存储、作用域标识（调用？路径？前缀？会话？时间窗口？）和撤销；在设计完成之前，只展示一次性选项（[沙箱 Agent Note](2026-07-06-sandbox.md) § Escalation 记录了开放的作用域问题）。
- **通过组合应答者录制由钩子驱动的 `ask`**：人类提示协议格式已通过沙箱示例的升级分支录制。钩子矩阵中的 `hook-cc-pretool-ask` 固定无 ApprovalService 时的后备拒绝，而钩子生产者与应答者的组合仍留在单元测试层。
- **将子 agent 的审批路由到父会话**：`subagent-acp` 的子侧自动应答自己的 `permission` 请求；将其呈现给父会话的编辑器是独立的设计。
- **通过组合应答者录制由钩子驱动的 `ask`**：权限协议格式已通过沙箱示例的升级分支录制。钩子矩阵中的 `hook-cc-pretool-ask` 固定无 ApprovalService 时的后备拒绝，而钩子生产者与应答者的组合仍留在单元测试层。
- **将子 agent 的审批路由到父会话**：`subagent-acp` 的子侧自动应答自己的权限请求；将其委派给父控制器是独立的设计。
## 曾考虑的替代方案
- **单一注册提供方而非 waterfall 监听器**：否决。`registerProvider()` 接口迫使所有组合问题——允许列表预过滤、外部钩子决策者、脚本化测试应答、人类前面的策略门禁——都塞进一个提供方实现。waterfall 从运行时已有的机制中获得组合能力、缺失时失败关闭和 HMR（热模块替换） dispose（资源释放）；seam 的 JSDoc 以约定固定单决策槽语义，而非发明一个提供方注册表。
- **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进 UI 插件，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
- **在 ACP 桥中内联 `tools/pre-execute` 权限门禁**：否决。对桥拥有的每次调用都弹出提示，会将请求策略硬编码进传输层，无法服务第二个发起方（沙箱升级发生在执行开始之后，没有 pre-execute 时刻），且钩子产生的 `ask` 决策没有共享机制。
- **通用用户交互 seam（`ctx.userInteraction`）**：否决作为审批机制。二者骨架相似（按 agent 路由、阻塞等待人类、处理缺失），但审批的契约在每个关键维度上都更窄：封闭的结果词汇而非自由文本、附着在工具调用上的协议原生提示而非通用表单、强制的缺失时失败关闭、以及审计事件。因此审批不走已交付的 `packages/ui/user-interaction` / `ask_user_question` 引出路径——引出表单不是权限提示，自由文本应答不是封闭结果；如果二者将来趋同，共享提供方管道仍然开放。
- **`dsh-tools` 中的静态可选注入**：否决。vendor 的 Cordis `Inject` 类型没有 optional 标志——对象形式将服务名映射到拦截配置，声明的 inject 会阻塞 fiber。`ctx.get('approval')` 是文档化的机会性消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测），按调用读取存在性，跨 HMR 正确降级，无需额外机制。
- **能力 seam 的三包拆分**：否决。接口/实现/消费方适合实现可替换的 seam（bash-local vs bash-sandbox）。此处服务体是固定机制，可变部分是留在各自通道拥有者插件中的监听器——拆分只会制造一个空的实现包（「不要预防性拆分」）。
@@ -107,13 +107,13 @@ ACP 桥只应答其正向会话映射所拥有的精确 agent 对象。它把 `s
- `allowed-once` 派发一次操作；其他所有结果都以不同原因拒绝，而 `'never'` 会在提示前拒绝。
- 缺失、外部、无 agent、抛异常、无效或断开连接的应答路径都会失败关闭。
- 成功的请求按精确 agent 归属路由，并追加一对可回放、对模型不可见的审计事件；空闲时和提交前失败的请求会拒绝。
- ACP 归属把提示限制在其会话内，而没有该服务的部署不产生提示或审计事件。
- ACP 归属把决策限制在其会话内，而没有该服务的部署不产生请求或审计事件。
代价与已接受的局限：
- **两个急于决策的应答者竞争同一槽位。** 兄弟插件的监听器顺序不确定，seam 无法仲裁竞争的终端应答者。通过约定缓解（每个部署一个终端应答者；仅对「先决策或委派」门禁使用 `prepend`），而非事件总线不具备的优先级机制。
- **生产环境验证依赖单一组合。** `ask` 有两个生产者家族——钩子桥通过 `tools/pre-execute`，沙箱升级通过自己的门禁——协议格式录制在沙箱示例的快照套件中；因此在更多部署组合它之前，seam 的真实覆盖面就是这一种组合。
- **归属以 `Agent` 对象标识为键。** 应答者先在 `agent.session.id` 处解析正向会话映射记录，再要求该记录拥有精确的 agent 对象；当前所有路径在 loop 和各 seam 之间传递同一对象，但未来如果某个边界克隆或代理了 agent，桥会委派并失败关闭——安全，但静默无 UI——届时需要另一种归属契约。
- **归属以 `Agent` 对象标识为键。** 应答者先在 `agent.session.id` 处解析会话映射记录，再要求该记录拥有精确的 agent 对象；当前所有路径在 loop 和各 seam 之间传递同一对象，但未来如果某个边界克隆或代理了 agent，桥会委派并失败关闭，届时需要另一种归属契约。
## FAQ
@@ -123,10 +123,10 @@ ACP 桥只应答其正向会话映射所拥有的精确 agent 对象。它把 `s
- **谁决定一次调用是否需要 ask？** 策略生产者：返回 `permissionDecision: ask` 的钩子、任何 `tools/pre-execute` 监听器、或沙箱升级门禁。seam 和桥只负责路由和应答；二者都不注入自己对「什么值得弹出提示」的判断。
- **用户关闭提示或轮次在 ask 进行中中止时会发生什么？** 关闭映射为 `cancelled` 并携带自己的拒绝文本。已中止的 signal 直接结算为 `cancelled` 而不派发；ask 进行中的中止丢弃迟到的应答。当两个审计追加都提交时，任一路径都记录恰好一对事件，绝不会两对。
- **如果客户端以 harness 从未提供的选项应答呢？** 除已提供的 `allow_once` 之外的任何选项都映射为 `rejected`——来自不合规客户端的未知 optionId 永远不能授权。
- **subagent 的审批如何路由？** 没有应答者拥有的 agent 穿过整个 waterfall 委派并失败关闭——进程内 subagent 被刻意设计为不可应答。`subagent-acp` 的子侧自动应答是独立的；将子 agent 的 ask 路由到父会话的编辑器已延后（§ 延后）。
- **subagent 的审批如何路由？** 没有应答者拥有的 agent 穿过整个 waterfall 委派并失败关闭——进程内 subagent 被刻意设计为不可应答。`subagent-acp` 的子侧自动应答是独立的；将子 agent 的 ask 路由到父控制器已延后（§ 延后）。
- **`policy: 'never'` 在运行时实际改变了什么？** 服务在派发任何应答者之前，将该会话的每次 ask 解析为 `rejected`（在服务内部，因此没有注册顺序能绕过它）；系统提示词声明该策略；切换在边界处被叙述；每次成功的自动拒绝都会记录审计对。
- **热重载或 UI 插件在会话中途卸载时会发生什么？** 应答者随其拥有的 fiber 一起 dispose，因此下一次 ask 降级为 `unavailable` 而非挂在死通道上；重新挂载会重新注册应答者，无需追赶状态。
- **用户在哪里看到自己在批准什么？** 在工具调用本身：提示通过 `callId` 附着在已流式输出的调用上（包含参数），并添加发起方的人类可读 `reason`；请求本身不携带参数副本。
- **热重载或应答者在会话中途卸载时会发生什么？** 应答者随其拥有的 fiber 一起 dispose，因此下一次 ask 降级为 `unavailable` 而非挂在死通道上；重新挂载会重新注册应答者，无需追赶状态。
- **客户端从哪里获得审批上下文？** 请求携带精确的 `callId` 和发起方的人类可读 `reason`；通道适配器可自行关联更丰富的工具调用状态，而无需在审批 seam 中重复携带参数。
## 先例
@@ -135,5 +135,5 @@ ACP 桥只应答其正向会话映射所拥有的精确 agent 对象。它把 `s
- `fs/write-intent` 门禁（`packages/fs/fs/`）——文档化的单占用决策槽 waterfall 语义（先到先得，通过 `next()` 委派），应答者契约复用了它。
- `hook/invoked`/`hook/result`——仅日志审计对先例，`approval/asked`/`approval/decided` 沿用了它；[钩子桥 Agent Note](2026-06-30-hook-bridges.md) 交付了 `permissionDecision: ask`，即第一个生产者。
- [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 的 `allow`/`deny`/`ask` 词汇，本 seam 服务其中的 `ask`。
- [ACP 支持 Agent Note](2026-06-14-acp-agent-client-protocol.md)——应答者路由时对正向会话映射执行的精确 agent 归属检查；[多会话 Agent Note](2026-06-14-acp-multi-session.md)——本设计实现的每会话权限归属阻塞项。
- [ACP 支持 Agent Note](2026-06-14-acp-agent-client-protocol.md)——应答者路由时对会话映射执行的精确 agent 归属检查；[多会话 Agent Note](2026-06-14-acp-multi-session.md)——本设计实现的每会话权限归属阻塞项。
- 机会性 `ctx.get()` 消费模式（`tool-bash` 的 owner-token 查找、loop 的持久化探测）——`dsh-tools` 消费该 seam 而不阻塞其 fiber 的方式。

4
.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-06-sandbox.md: c1307a7201ed1bc331a86d4ffee002d69fd1d5e5
2026-07-06-sandbox.zh.md: 4e3d4951f71a602bc78551c90dda04317d0f8284
2026-07-06-sandbox.md: 723ef170188dc11da24e049a1e2838fb240d0a17
2026-07-06-sandbox.zh.md: a8c7743bb3d499fb58f507ea2c202b44efe2311d

31
.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md
View File

@@ -10,7 +10,7 @@ Status: implemented
harness 是一个 SDK，因此约束必须是开发者可组合的能力：是否启用沙箱、每个平台使用哪个后端，都应作为一等条目写在叶子 `cordis.yml` 中，而非藏在某个执行器的私有机制里。而首选 runner `bwrap` 恰恰在沙箱最重要的主机上不可用（精简容器、禁用了非特权 userns、LSM 拒绝 `mount`），因此备选 runner 必须随 SDK 一起交付，而不能假设主机已有。
仅有约束还留下两个缺口。拒绝后没有升级路径就是死路：模型只能放弃，这会迫使运维人员全局配置 `workspace-write` 或 `danger-full-access`，从而使沙箱形同虚设。而模型可见的旋钮（沙箱模式、批准策略）在 agent 生命周期内会变化——ACP 用户切换按会话设置、运维人员在进程停止期间编辑 `cordis.yml`——模型绝不能基于过时的信念行动：每次请求时的实际状态是什么、agent 存活期间发生了什么变化、无人看管时又发生了什么变化，都需要有明确答案。
仅有约束还留下两个缺口。拒绝后没有升级路径就是死路：模型只能放弃，这会迫使运维人员全局配置 `workspace-write` 或 `danger-full-access`，从而使沙箱形同虚设。而沙箱模式和批准策略也会通过部署配置或可选的 UI 策略控件在 agent 生命周期内变化；执行与模型可见的策略必须派生自同一份已记录的状态。
## 决策
@@ -40,13 +40,13 @@ harness 是一个 SDK，因此约束必须是开发者可组合的能力：是
配置错误大声失败：`mode` 不在封闭词汇中时在插件加载时被拒绝；主机上没有可用后端时在 `confine()` 阶段（命令 spawn 之前）抛出结构化的 `SANDBOX_UNAVAILABLE`，而非降级为无约束执行。`dsh-sandbox-local` 上的 `runnerCommand` 是运维人员对一个 bwrap 兼容 runner 的显式断言（跳过链和探测）；它同时充当 keyless 测试的确定性 fake-runner seam。
被拒绝的文件操作返回 `[sandbox: file access denied under <mode> mode]` 标记，并附带不要绕过拒绝的指令。约束执行器添加配对的 `sandbox_permissions` 和 `justification` 字段，用于一次经批准的重试，该重试必须严格宽于会话的有效模式。授权仅放宽该次重试；拒绝则不执行任何内容，返回 `the user rejected escalating this command to "<mode>"`，且不允许再次请求。提示词不声明沙箱模式，以避免基于常驻标签的预防性拒绝。当 `dsh-permission` 被组合时，ACP 暴露一个 `Permissions` 选择器，其 preset 同时写入两个旋钮事件；不匹配的旋钮组合显示为仅可切换离开的 `custom`。只有切换到确定性的 `'never'` 批准策略才会在提示词中声明并叙述。
被拒绝的文件操作返回 `[sandbox: file access denied under <mode> mode]` 标记，并附带不要绕过拒绝的指令。约束执行器添加配对的 `sandbox_permissions` 和 `justification` 字段，用于一次经批准的重试，该重试必须严格宽于会话的有效模式。授权仅放宽该次重试；拒绝则不执行任何内容，返回 `the user rejected escalating this command to "<mode>"`，且不允许再次请求。提示词不声明沙箱模式，以避免基于常驻标签的预防性拒绝。当 `dsh-permission` 与某个 UI 适配器一起组合时，一个 preset 同时选定两个旋钮值；不匹配的组合折叠为 `custom`。[ACP 自动化组合](../../../../examples/acp-agent/README.md)不挂载该 UI 服务，而是显式选定其部署模式。
### 设计细节
#### 范围界定
OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还将适用于 ACP subagent 子进程。文件系统、web 和其他工具在进程内执行，需要在各自的 seam 层面实施策略；argv 包装无法约束一个闭包了 `ctx` 的函数。既有的 bash request/spec 拆分承载按调用的覆盖，而 `tools/pre-execute` 和 approval seam 负责人的决策。
OS 子进程约束适用于 bash 执行器（包括钩子命令），后续还将适用于 ACP subagent 子进程。文件系统、web 和其他工具在进程内执行，需要在各自的 seam 层面实施策略；argv 包装无法约束一个闭包了 `ctx` 的函数。既有的 bash request/spec 拆分承载按调用的覆盖，而 `tools/pre-execute` 和 approval seam 负责一次性策略决策。
#### seam：`ctx.sandbox`
@@ -92,7 +92,7 @@ Landlock launcher 源码和包工作区位于 `native/landlock-run`，与 harnes
effective(session) = findLast(the session's own knob events)?.value ?? the composition-config default
```
默认值是组合配置（`cordis.yml`）——运维人员拥有，进程范围。运行时切换是会话范围的覆盖，记录为该会话自身日志中的一条仅日志事件。重启免疫（恢复会话时回放其日志，覆盖自然恢复，无需追赶机制）和多会话隔离（一个编辑器标签页的 `workspace-write` 不会干扰另一个的 `read-only`）都是构造性的自然结果，且不存在任何外部配置存储。
默认值是组合配置（`cordis.yml`）——运维人员拥有，进程范围。运行时切换是会话范围的覆盖，记录为该会话自身日志中的一条仅日志事件。重启免疫（恢复会话时回放其日志，覆盖自然恢复，无需追赶机制）和多会话隔离都是构造性的自然结果，且不存在任何外部配置存储。
**每个旋钮一种事件，由其领域拥有**——这是每个既有事件族已遵循的可合并扩展 `SessionEventMap` 惯用法（`dsh-user-approval` 中的 `approval/*`、hooks 包中的 `hook/*`）：
@@ -107,9 +107,9 @@ interface SessionEventMap {
沙箱模式不在提示词中叙述；拒绝结果在需要时报告模式，避免基于常驻标签的预防性拒绝。批准策略不同：只有 `'never'` 被声明，因为自动拒绝在行为上与用户的「不」无法区分。策略变更通知被合并，由下一个步骤前检查点递送，重启后有基于日志的回退。通知来源从事件位置推断：最后一个 request header 之后的旋钮事件是用户驱动的；未记录的漂移是运维人员或配置驱动的。
**编辑器界面**是协议原生的[会话配置选项](https://agentclientprotocol.com/protocol/session-config-options)——该规范对 session modes 的替代（计划在 ACP v2 中移除），已有 SDK 类型。当 `ctx.permission` 被组合时，bridge 在 `session/new` 和 `session/load` 中公布一个 `permission` 选择器（category `mode`）；其选项是部署的 preset 表，其 `currentValue` 是 `PermissionService.current()` 对会话日志加组合默认值的结果。随附的 `workspace-write` 和 `danger-full-access` preset 各自捆绑一个沙箱模式与一个批准策略，并写入两个领域 setter；preset 表之外的旋钮组合报告为仅可切换离开的 `custom`。`session/set_config_option` 通过权限服务验证并切换，然后返回完整的刷新状态（规范契约）。
**可选的 UI 界面**是 `PermissionService`：一张部署定义的 preset 表，每个条目捆绑一个沙箱模式与一个批准策略。随附的 `workspace-write` 和 `danger-full-access` preset 写入两个领域 setter；preset 表之外的旋钮组合报告为 `custom`。UI 适配器可以把该表暴露为选择器。仅面向自动化的 ACP 传输层不公布任何配置选择器，也不挂载权限 preset 服务。
**轮次封闭是提交边界。** 开放轮次中的切换立即追加。空闲切换保持在 bridge 记录上待定，在下一次提示词提交时、assembly 或执行之前追加到开放轮次中；每个旋钮以最后写入为准。开放性来自日志边界而非 `agent.status`，setter 不从 `session/event` 监听器内追加，因为那会重排后续观察者。锚定之前，响应叠加待定值。崩溃丢弃它，重新加载返回持久 fold。
**已提交的事件是提交边界。** 运行时切换在目标会话上记录其 preset 和发生变化的旋钮事件，之后每次能力解析都折叠最后的值。选择有效的会话追加边界由适配器负责；ACP 传输层没有运行时切换路径。（原先 ACP 的空闲切换锚定——将待定的空闲选择保留到下一次提示词提交——已随该桥一并移除。）
#### 进程内工具
@@ -117,10 +117,10 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
### 测试
- **单元测试：** 固定平台选择和 profile、失败关闭的 runner 分类、按调用的模式/根目录解析、按进程事实、升级验证和结果、权限 preset fold 和写入透传、叙述器合并、ACP 公布和验证、轮次封闭的配置写入。
- **Keyless 真实 runner：** 在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；一个真实 Cordis 上下文通过已交付的 bash 和 fs 工具并发驱动两个项目会话，证明在自身根目录写入成功、在兄弟根目录写入被拒绝。Packed-install 覆盖率证明注册表 launcher 保持可执行。真实 ACP 组合固定权限切换并拒绝未知 preset。CI 拒绝静默全跳过。
- **单元测试：** 固定平台选择和 profile、失败关闭的 runner 分类、按调用的模式/根目录解析、按进程事实、升级验证和结果、权限 preset fold 和写入透传、以及叙述器合并。
- **Keyless 真实 runner：** 在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；一个真实 Cordis 上下文通过已交付的 bash 和 fs 工具并发驱动两个项目会话，证明在自身根目录写入成功、在兄弟根目录写入被拒绝。Packed-install 覆盖率证明注册表 launcher 保持可执行。CI 拒绝静默全跳过。
- **With-key：** 以只读模式启动真实 ACP 组合，让模型驱动的 bash 写入命中 runner 的拒绝标记，再通过已授权与被拒绝的 workspace-write 重试驱动 bridge 应答器和磁盘效果；不可用的凭证或 runner 自动跳过。
- **快照：** 固定权限 config-option 协议格式（wire format）、preset 和旋钮事件、提示词 delta 和通知、以及两个脚本化的 approval 分支。一个真实 ACP 示例场景把会话放在用户主目录下，同时让部署后备根目录指向 `/tmp`，然后固定一次成功的 workspace-write 变更；这能区分会话根目录解析与进程后备值，而不依赖 runner 特定的拒绝文本。其他快照以无约束启动，使无关 fixture（测试前置数据）保持平台无关；策略场景显式切换。
- **快照：** 固定提示词 delta 和通知，以及两个脚本化的 approval 分支。一个真实 ACP 示例场景把会话放在用户主目录下，同时让部署后备根目录指向 `/tmp`，然后固定一次成功的、由部署选定的 workspace-write 变更；这能区分会话根目录解析与进程后备值，而不依赖 runner 特定的拒绝文本。其他快照以无约束启动，使无关 fixture（测试前置数据）保持平台无关。
## 延迟阶段
@@ -152,7 +152,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
- **通过 `agent/user-message` + 总线事件叙述**：否决。它预设了一个不存在的轮次入口 seam（真正的 seam 是 `agent/prompt-submit`），而步骤前检查点的位置使一个监听器能够同时服务合并的轮次入口通知和轮中即时性约束。
- **提示词中常驻声明沙箱模式（+ 切换叙述器）**：先交付后移除，基于实际证据：当每个请求中都有 `Bash commands run under the "read-only" file sandbox.` 时，模型拒绝尝试被拒绝后可升级的工作（首次手动会话中十二个轮次有五个以零工具调用结束），将沙箱变成了软锁定。拒绝标记在需要时命名模式，升级字段承载恢复路径；批准旋钮保留其声明，因为自动拒绝在行为上与人的「不」无法区分。
- **用专门的簿记事件追踪「上次告知」**：否决。`request/header` fold 已记录模型看到的确切提示词；将封闭的候选句子解析回来替代了第二条簿记流——事件仅在它们本身即为存储时才需要。
- **ACP session modes 而非 config options**：否决。preset 已经是一个部署定义的 config-option 选择器，且 modes 计划在 ACP v2 中移除。
- **相互独立的沙箱与批准选择器**：否决。一个部署定义的权限 preset 让两个策略旋钮对暴露运行时切换的 UI 客户端保持一致。
## 后果
@@ -161,11 +161,11 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
- 被拒绝的命令以 `sandbox_permissions` + `justification` 重试时，通过组合的应答器链提示用户；授权使该次调用在更宽模式下运行（结果事实如此报告），而其他所有调用保持各自的有效模式；每种非授权结果产生各自不同的错误文本且不执行任何内容。
- 升级字段恰好在已挂载的执行器约束时存在；不严格宽于调用有效模式的请求以自身文本失败关闭且不提示任何人；没有 ApprovalService 的部署对升级调用失败关闭，对普通调用不影响。
- 系统提示词从不声明沙箱模式（批准 `'never'` 策略是唯一被声明的旋钮），且整个交互——header、旋钮事件、通知、批准、结果——仅从会话日志即可重建，除两个旋钮事件外无额外事件类型。
- N 次空闲切换每个旋钮最多产生一个锚定事件（净零序列不锚定任何事件——客户端回显当前选择的无操作推送不记录任何内容）；批准策略切换最多以一条合并通知叙述；轮中沙箱切换由下一次调用的盖章兑现。
- 恢复的会话的覆盖生效并报告给编辑器，无需特殊处理；进程停止期间变更的默认值在会话的首个新请求前被叙述，归因于运维人员。
- 两个并发会话永远看不到彼此的状态、通知或配置选项。
- 一次 preset 选择只记录发生变化的旋钮值，而无操作的选择不记录任何内容；批准策略切换最多以一条合并通知叙述，已提交的沙箱切换由下一次调用的盖章兑现。
- 恢复的会话的覆盖直接生效，无需追赶状态；进程停止期间变更的默认值在会话的首个新请求前被叙述，归因于运维人员。
- 两个并发会话永远看不到彼此的状态或通知。
- 同一个 Cordis 上下文中的两个并发项目会话解析各自独立的工作区根目录；bash 和 fs 写入在调用方会话的 cwd 内成功，对其相邻会话的 cwd 则失败。
- `agent-loop` 未被触及——一切搭载 `systemPrompt.section`、`SessionEventMap` 合并、`agent.inject()`、`agent/pre-step`、`agent/prompt-submit` 和 ACP handler 表面。
- `agent-loop` 未被触及——一切搭载 `systemPrompt.section`、`SessionEventMap` 合并、`agent.inject()`、`agent/pre-step`、`agent/prompt-submit` 和由能力拥有的策略解析。
代价与已接受的限制：
@@ -178,7 +178,6 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
- **模型可能过度请求。** 在没有拒绝依据的情况下升级，或在 `workspace-write` 足够时选择 `danger-full-access`：描述引导且枚举强制阶梯，但人的提示词是实际门控；`approval/asked` 原因使过度请求可审计，且 `prepend` 策略应答器可以自动拒绝部署永远不想要的模式。
- **公布的目标集是静态的，而有效模式是按会话的**（schema 是注册表全局的）——已处于最宽模式的会话仍被提供这些字段。构造上无害：执行时的严格放宽检查（而非枚举）是安全边界——非放宽请求以自身文本失败且不提示任何人。
- **授权的升级不等于可工作的沙箱。** 不可用的后端即使对授权升级到约束模式也仍然失败关闭——在平台没有链或所有探测失败时于 `confine()` 阶段，在未探测的唯一 runner 拒绝时于执行阶段（归类为沙箱失败而非命令失败）——而授权的 `danger-full-access` 运行根本不触及提供方：此时授权（而非探测）是权威。
- **空闲切换存在于 bridge 内存中，直到下一次提示词提交锚定它。** 该窗口内的崩溃将其回退（在 `session/load` 时报告），且永不再提交提示词的会话永不持久化它——已接受，loop 拥有的空闲提交轮次留作未来工作（如果持久性成为需求）。
- **批准叙述器的重启基线解析提示词文本。** 封闭的候选句子由写入模块本身拥有，因此措辞变更是同一文件中写入器+解析器的协调编辑；header 早于该段落的会话静默采用当前策略而不发通知。
- **批准段落仍是动态提示词表面**（`'never'` 切换会破坏该会话的提供方提示词前缀缓存）。已接受：策略切换罕见，且模型基于过时的 `'never'` 行动更糟。沙箱旋钮不再触及提示词。
- **模型可能持有关于沙箱模式的过时信念**（没有任何东西宣布切换）。有意接受：下一次尝试的标记或成功会纠正它，而宣布的观察到的失败模式——预防性拒绝——比一次浪费的重试更糟。
@@ -192,7 +191,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
- **沙箱限制网络或进程可见性吗？** 不——`SandboxMode` 仅声称文件操作；bwrap profile 刻意不 unshare pid，没有后端声称网络。网络限制是否成为自己的旋钮留在 § seam 中开放。
- **哪些工具实际在约束下运行？** 通过 `ctx.bash` 的 OS 子进程——bash 工具及传递性的钩子命令——再加上通过沙箱化 `ctx.fs` 提供方运行的文件系统工具（`read`/`write`/`edit`，见[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md)）：bash 通过 OS runner 约束，fs 通过进程内路径围栏约束，二者都以同一个 `ctx.sandboxPolicy` 模式为键。web/todo 仍在进程内且不受限制（web 的唯一效果是网络，不在文件效果模式词汇内）。
- **授权的升级会持久化吗？** 不会。授权由发起请求的确切前台或后台调用消费；每个相邻调用保留自己的有效模式。后续的后台拒绝通过 `task_output` 呈现，并且可以作为一次新的精确命令重试的依据。
- **编辑器的模式切换何时生效？** 轮中：立即追加，由下一次调用的盖章兑现。空闲：保持在 bridge 的会话记录上，在下一次 `agent/prompt-submit` 时锚定到其开放轮次中，N 次切换合并为最多一个事件（净零则无）；锚定前崩溃回退它，`session/load` 报告真实状态。模型不被告知——其下一个命令直接在新模式下运行。
- **运行时模式切换何时生效？** 一旦其会话事件提交，紧接着的下一次能力解析就会折叠并盖章新模式。模型不被告知常驻模式；其下一个命令直接在新策略下运行，任何拒绝都会在使用点命名该策略。
- **重启后什么存活——如果运维人员在进程停止期间改了配置默认值呢？** 覆盖从会话日志回放（`effective = fold ?? config`），因此恢复的会话以零追赶机制保持其模式；离线漂移的默认值以与切换相同的方式改变行为（批准策略因被声明，还额外以运维人员/配置归因叙述）。
- **结果上的 `enforcement: 'partial'` 是什么意思？** 所选后端强制其内核 ABI 管控的子集——例如 ABI v3 之前的 Landlock 不管控路径 truncate——并以结构化方式如此声明而非拒绝主机；探测的报告行区分各种情况。bwrap 和 Seatbelt profile 构造上管控所有承诺的文件操作，因此始终报告 `full`。

4
.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-07-mcp-client-plugin.md: 90c43383882034954f33b79459fac273e60b9e0e
2026-07-07-mcp-client-plugin.zh.md: a60aa537a03dec5add7e91fd78b91fece4e4a259
2026-07-07-mcp-client-plugin.md: 2a8ad62e3bad1f2ae47100294f5dba25ceb47d12
2026-07-07-mcp-client-plugin.zh.md: 9860d5ec805b394eb0c5f59f54349264593a5599

4
.agents/notes/implemented/feature/2026-07-07-mcp-client-plugin.zh.md
View File

@@ -99,7 +99,7 @@ type Config = StdioConfig | StreamableHttpConfig
1. 连接时：遍历 `client.listTools()` 的分页结果，推导每个工具的 `publicName`，然后通过 `ctx.tools.register()` 将其注册为原始 `ToolDefinition`。MCP 的 JSON Schema 和描述原样透传（不做 `defineTool` DSL 转换）；仅替换模型可见的 `name`。
2. 监听 `notifications/tools/list_changed` → 重新执行同步（dispose 上一代、注册新一代）。确定性命名意味着未变化的工具在重新同步后保持原名。
3. 执行器闭包持有 `rawName`；公开名称永远不发送给服务器，也永远不被解析以还原原始名称。
4. 无 `presentCall`/`presentResult`——ACP 桥接的通用卡片兜底负责渲染。
4. 无 `presentCall`/`presentResult`——UI 消费方使用提供方无关的通用卡片兜底。
5. 工具在系统提示词中是透明的——除名称本身外不附加「[via MCP]」标注。
### 公开名称规范化
@@ -201,7 +201,7 @@ v1 否决。它能防止跨服务器冲突，但无法将 MCP 注册与原生 ha
- **单元测试**（`tests/mcp-client.spec.ts`、`tests/apply.spec.ts`，mock MCP SDK）：`publicToolName` 算法（干净名称、规范化、截断加 hash、确定性、不同标识的分离）、raw 与 public 的协议纪律、跨服务器与原生工具共存、重复 `serverName` 加载失败与预留释放、无效工具列表拒绝、代切换/回滚、重新同步失败时的保留、结果映射、取消、配置 schema 校验。100% 逐文件覆盖率门禁约束该包。
- **E2E**（`tests/mcp-client.e2e.ts`，无需密钥）：使用真实 MCP 协议对接仓库内的 fixture（测试前置数据）服务器、`@modelcontextprotocol/server-everything` 和 `@modelcontextprotocol/server-filesystem`（stdio 传输），以及进程内 `StreamableHTTPServerTransport` 服务器（Streamable HTTP 传输）——命名空间下的发现、带点号名称的端到端规范化、执行往返、重复 `serverName` 拒绝、dispose。
- **快照**：刻意不做。MCP 工具不引入新的 transcript（文本记录）呈现面——它们以原始 `ToolDefinition` 注册，通过 ACP 桥接的通用卡片兜底渲染，该兜底已由桥接的单元测试套件固定（`packages/ui/acp/tests/stream-update.spec.ts`）。将 MCP 服务器添加到快照示例的 `cordis.yml` 会改变已固定的 `text-turn` 系统提示词 fixture（迫使每条录制的预期输出都需要带密钥重新录制），且使每次回放依赖于 spawn 外部 MCP 服务器进程——而新增渲染行为为零。如果后续变更为 MCP 工具引入专属渲染意图，该变更届时自行声明快照覆盖。
- **快照**：刻意不做。MCP 工具不引入新的展示形态——它们以原始 `ToolDefinition` 注册，UI 消费方使用各自展示测试套件已固定的通用卡片兜底。将 MCP 服务器添加到某个可运行的快照组合会改变其已固定的系统提示词 fixture，且使每次回放依赖于 spawn 外部 MCP 服务器进程，而新增行为为零。如果后续变更为 MCP 工具引入专属渲染意图，该变更届时自行声明快照覆盖。
## 后果

4
.agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-19-model-facing-goal-tools.md: 286329390a058c0302520fd2203e5becb8c81395
2026-07-19-model-facing-goal-tools.zh.md: b0b4fc99ada3597fbab58081f52309e21dd43bac
2026-07-19-model-facing-goal-tools.md: 2c53a7658e213dee4fecc93709244f97b821aca0
2026-07-19-model-facing-goal-tools.zh.md: aa7b5ea14b7afff88819f0efa35c5f2d5e2e933e