docs(i18n): align Agent Note terminology
This commit is contained in:
Tianyi Cui
@@ -3,4 +3,4 @@
|
||||
# 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: 2bc6f71a8d370d65ccc3624724528a99f452bd9f
|
||||
2026-06-14-acp-agent-client-protocol.zh.md: 180a199ec0d0fca5d9deba84d8c31ca63426c519
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本，但编辑器无法以结构化方式创建或恢复会话、关联 prompt 完成、流式输出推理（reasoning）与工具活动、渲染工具专属 UI、请求权限，或在不干扰其他对话的前提下取消某个对话。ACP（Agent Client Protocol）将这些交互定义为基于 stdio 的 JSON-RPC，Zed 是用于做出具体兼容性决策的目标客户端。
|
||||
harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本，但编辑器无法以结构化方式创建或恢复会话、关联提示词完成、流式输出推理（reasoning）与工具活动、渲染工具专属 UI、请求权限，或在不干扰其他对话的前提下取消某个对话。ACP（Agent Client Protocol）将这些交互定义为基于 stdio 的 JSON-RPC，Zed 是用于做出具体兼容性决策的目标客户端。
|
||||
|
||||
桥接层必须保持 harness 既有的所有权边界。它不能依赖具体的 agent loop（智能体循环），不能绕过工具注册表，不能在编辑器中执行 shell 命令，也不能发明第二个会话真源。stdout 同时也是协议传输通道，因此任何意外的日志输出都会破坏连接。
|
||||
|
||||
@@ -16,23 +16,23 @@ harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本
|
||||
|
||||
桥接层实现以下稳定的会话路径：
|
||||
|
||||
- `initialize` 协商协议版本，声明支持 text 与 `resource_link` 类型的 prompt，并声明 `loadSession` 能力。
|
||||
- `initialize` 协商协议版本，声明支持 text 与 `resource_link` 类型的提示词，并声明 `loadSession` 能力。
|
||||
- `session/new` 校验绝对路径 `cwd`，将其存入 `SessionHeader`，通过 `ctx.agents` 创建 agent，并返回由组合层支持的配置选项。
|
||||
- `session/load` 在构造 agent 之前校验请求的 cwd 与持久化元数据是否一致，在异步恢复期间保留 id，将用户/助手/工具事件作为 ACP update 回放，并报告恢复后的 config-option 折叠结果。
|
||||
- `session/prompt` 接受文本和 resource link，拒绝不支持的或空的内容，每个会话同时只允许一个 in-flight prompt，并在该 prompt 所属的 `turn/end` 时结算。错误轮次拒绝 RPC；其他关闭轮次的原因通过一个全覆盖的 ACP stop-reason 编解码器映射。
|
||||
- `session/cancel` 调用队列感知的 agent 取消路径，仅结算被寻址会话的 prompt。
|
||||
- `session/prompt` 接受文本和 resource link，拒绝不支持的或空的内容，每个会话同时只允许一个 in-flight 提示词，并在该提示词所属的 `turn/end` 时结算。错误轮次拒绝 RPC；其他关闭轮次的原因通过一个全覆盖的 ACP stop-reason 编解码器映射。
|
||||
- `session/cancel` 调用队列感知的 agent 取消路径，仅结算被寻址会话的提示词。
|
||||
|
||||
工具调用的展示仍由工具自身负责。工具的 `presentCall` 和 `presentResult` 返回 `generic`、`terminal` 或 `diff` 渲染意图变体；桥接层对该联合类型做 switch 并映射到 ACP。没有 presenter 的工具获得通用回退。Bash 终端卡片使用 Zed 的能力门控约定 `_meta.terminal_info`、`_meta.terminal_output` 和 `_meta.terminal_exit`；harness 仍通过 `ctx.bash` 执行命令，保留沙箱、环境清洗、所有权和 cwd。不支持该扩展的客户端收到普通文本内容。文件系统工具提供 diff 卡片和文件位置，桥接层中无需硬编码工具名分支。
|
||||
|
||||
权限处理是[用户审批 seam](2026-07-06-approval-seam.md)上的一个 answerer，而非 ACP 中的「每次工具调用都询问」策略。对桥接层所属 agent 且带有 call id 的 `approval/request`，会变为该 agent 编辑器会话上的 `session/request_permission`，提供一次性允许/拒绝选项。外部请求或无 call id 的请求委托给下游；缺失或失败的 answerer 保持 fail-closed。发起询问的插件（如预执行策略或 bash 升级）拥有「是否询问」的决策权。
|
||||
权限处理是[用户审批 seam](2026-07-06-approval-seam.md)上的一个 answerer，而非 ACP 中的「每次工具调用都询问」策略。对桥接层所属 agent 且带有 call id 的 `approval/request`，会变为该 agent 编辑器会话上的 `session/request_permission`，提供一次性允许/拒绝选项。外部请求或无 call id 的请求委托给下游；缺失或失败的 answerer 会在故障时保持拒绝。发起询问的插件（如预执行策略或 bash 升级）拥有「是否询问」的决策权。
|
||||
|
||||
当 `ctx.permission` 被组合时，桥接层从部署的预设表中暴露一个 `permission` select。已发布的 `workspace-write` 和 `danger-full-access` 预设各自捆绑一个沙箱模式与一条审批策略；无法匹配的有效旋钮组合产生只能切走的 `custom` 状态。`session/set_config_option` 通过 `PermissionService.set()` 校验并写入两个所属旋钮事件。在开放轮次中的切换立即追加；空闲时的切换叠加在响应中，并在下一次 `agent/prompt-submit` 时锚定到开放轮次之前的请求组装阶段。在此之前它仅存于内存，因此崩溃后恢复的是持久化的折叠结果。ACP session mode 不被建模，因为 config option 是面向未来的协议表面；`AcpConfig.model` 保持连接级别。
|
||||
|
||||
桥接层还提供基于 ACP 的 `UserInteractionProvider`：`ask_user_question` 请求变为所属会话上的表单引导。select、multi-select、选项描述与自定义回答覆盖语义均被保留。
|
||||
|
||||
生命周期所有权是显式的。桥接层为每个活跃会话持有一个 `AgentHandle`。断连和 Cordis dispose（资源释放）会取消待处理的 prompt，并行 dispose 所有 handle，等待循环静默与持久化刷写，然后移除记录。流通知失败被隔离，因此消失的客户端不会破坏 agent 轮次。ACP 应用组合不加载 stdout logger；一个测试守卫 stdout 仅包含帧化的 JSON-RPC。
|
||||
生命周期所有权是显式的。桥接层为每个活跃会话持有一个 `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)；package README 是操作契约。
|
||||
精确的已支持与已推迟的协议行列表见 [`packages/ui/acp/acp-feature-support.md`](../../../../packages/ui/acp/acp-feature-support.md)；包 README 是操作契约。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
@@ -48,12 +48,12 @@ harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本
|
||||
|
||||
## 后果
|
||||
|
||||
编辑器可以通过一条 ACP 连接创建、加载、提交 prompt、取消、渲染、询问和重新配置多个 harness 会话，无需依赖特定的循环实现。会话事件日志仍是回放、prompt 结算、cwd 与每会话配置的持久真源。工具展示与人工回答通道仍是可扩展的插件契约，而非 ACP 专属行为。
|
||||
编辑器可以通过一条 ACP 连接创建、加载、提交提示词、取消、渲染、询问和重新配置多个 harness 会话，无需依赖特定的循环实现。会话事件日志仍是回放、提示词结算、cwd 与每会话配置的持久真源。工具展示与人工回答通道仍是可扩展的插件契约，而非 ACP 专属行为。
|
||||
|
||||
桥接层有意不实现会话列表/删除/恢复/关闭能力、MCP 透传、附加目录、图片/音频/嵌入资源 prompt、plan、斜杠命令、用量更新、编辑器文件系统委托或 ACP 终端执行子协议。后续已通过标准会话配置选项加入运行时模型选择，见 [LLM 目录与 ACP 选择 Agent Note](../architecture/2026-07-15-llm-model-catalog-and-acp-selection.md)。
|
||||
桥接层有意不实现会话列表/删除/恢复/关闭能力、MCP 透传、附加目录、图片/音频/嵌入资源提示词、plan、斜杠命令、用量更新、编辑器文件系统委托或 ACP 终端执行子协议。后续已通过标准会话配置选项加入运行时模型选择，见 [LLM 目录与 ACP 选择 Agent Note](../architecture/2026-07-15-llm-model-catalog-and-acp-selection.md)。
|
||||
|
||||
空闲时的配置选择在实时响应中是真实的，但在下一次 `agent/prompt-submit` 将其锚定到开放轮次之前不具持久性。在该边界之前崩溃会丢失待定选择；这是保持会话事件封闭于轮次内且回放安全的代价。
|
||||
|
||||
## 验证
|
||||
|
||||
ACP 测试套件覆盖内存协议编解码器、创建/加载回放、精确的 prompt 结算、取消竞争、不支持的内容、工具展示、终端能力回退、权限结果映射、config-option 校验与持久化、多会话隔离、断连/释放静默，以及 HMR（热模块替换）清理。快照测试与 built-bin 测试验证应用组合，真实 API 的 e2e 测试在无 key 时自动跳过。
|
||||
ACP 测试套件覆盖内存协议编解码器、创建/加载回放、精确的提示词结算、取消竞争、不支持的内容、工具展示、终端能力回退、权限结果映射、config-option 校验与持久化、多会话隔离、断连/释放静默，以及 HMR（热模块替换）清理。快照测试与 built-bin 测试验证应用组合，真实 API 的 e2e 测试在无 key 时自动跳过。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 012752273b469295fcf8338f809dca252fc377ac
|
||||
2026-06-14-acp-multi-session.zh.md: 6835f9623b89dc20d6c7b3054365cd9c39402aeb
|
||||
|
||||
@@ -6,19 +6,19 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
一个 ACP（Agent Client Protocol）编辑器可以在同一个 agent（智能体）子进程上保持多个对话。如果桥接层只支持单活跃会话，就不得不启动额外进程，也无法匹配 Zed 的客户端模型——该模型跟踪多个 session id 和并发加载。多路复用引入了隔离风险：事件、prompt 完成、取消、权限提示、配置选择以及可预测的后台 task id 绝不能跨越会话边界。
|
||||
一个 ACP（Agent Client Protocol）编辑器可以在同一个 agent（智能体）子进程上保持多个对话。如果桥接层只支持单活跃会话，就不得不启动额外进程，也无法匹配 Zed 的客户端模型——该模型跟踪多个会话 id 和并发加载。多路复用引入了隔离风险：事件、提示词完成、取消、权限提示、配置选择以及可预测的后台 task id 绝不能跨越会话边界。
|
||||
|
||||
## 决策
|
||||
|
||||
ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agent 作用域的回调使用 `ownedRecord`：在正向 map 中查找 `agent.session.id`，且仅当该记录拥有精确的 agent 对象时才接纳它，使外部的同 id 对象无法冒领会话。一条记录拥有其 agent 句柄、进行中的 prompt、活跃的工具调用展示状态、待处理的空闲配置切换、会话 cwd 以及客户端能力快照。一个独立的 loading-id 集合在异步恢复之前预留每个 id，使两个流水线化的加载请求无法构造出重复的 agent；不同 id 可以并发加载。
|
||||
ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agent 作用域的回调使用 `ownedRecord`：在正向 map 中查找 `agent.session.id`，且仅当该记录拥有精确的 agent 对象时才接纳它，使外部的同 id 对象无法冒领会话。一条记录拥有其 agent 句柄、进行中的提示词、活跃的工具调用展示状态、待处理的空闲配置切换、会话 cwd 以及客户端能力快照。一个独立的 loading-id 集合在异步恢复之前预留每个 id，使两个流水线化的加载请求无法构造出重复的 agent；不同 id 可以并发加载。
|
||||
|
||||
每个 `session/event` 和 `agent/status` 回调在发送或结算任何内容之前，先解析出所属记录。每个会话独立允许一个进行中的 prompt。prompt 记录一个日志水位线，捕获自己的 `turn/start`，并仅在匹配的 `turn/end` 到达时结算；来自已取消的前一轮次的迟到 end 不能 resolve 更新的 prompt。`session/cancel` 定位到一条记录，只调用该 agent 的队列感知取消路径。
|
||||
每个 `session/event` 和 `agent/status` 回调在发送或结算任何内容之前，先解析出所属记录。每个会话独立允许一个进行中的提示词。提示词记录一个日志水位线，捕获自己的 `turn/start`，并仅在匹配的 `turn/end` 到达时结算；来自已取消的前一轮次的迟到 end 不能 resolve 更新的提示词。`session/cancel` 定位到一条记录，只调用该 agent 的队列感知取消路径。
|
||||
|
||||
权限归属使用对正向 map 的同一精确 agent 检查。ACP `approval/request` 应答器只向拥有发起请求的 agent 的编辑器会话发起提示，并将外部请求委托出去。用户交互引出同样按 agent 归属路由。每会话的沙箱和审批配置值只折叠该会话自身的事件，待处理的空闲切换存储在该记录上，直到下一轮次将其锚定。
|
||||
|
||||
后台 bash 任务携带一个不透明的 owner token，其值等于所属会话 id。`bash_output` 和 `bash_kill` 在读取或终止之前，将调用方的 token 与执行器的任务归属进行比较；仅凭可预测的 task id 不能获得访问权。归属信息与执行器任务一起存储，因此工具插件重载不会擦除它。
|
||||
|
||||
连接拆除时清空活跃 map，将每个待处理的 prompt 以取消状态结算，并并行 dispose（资源释放）所有 `AgentHandle`。每个句柄停止并等待其循环完成、在仍然附着时刷新会话、注销 agent 并移除会话。拆除操作被 memoize 化，由客户端断连和插件 dispose 共享。
|
||||
连接拆除时清空活跃 map，将每个待处理的提示词以取消状态结算，并并行 dispose（资源释放）所有 `AgentHandle`。每个句柄停止并等待其循环完成、在仍然附着时刷新会话、注销 agent 并移除会话。拆除操作被 memoize 化，由客户端断连和插件 dispose 共享。
|
||||
|
||||
## 协议与工作区作用域
|
||||
|
||||
@@ -34,14 +34,14 @@ ACP 桥接层将活跃会话存储在 `Map<SessionId, SessionRecord>` 中。agen
|
||||
|
||||
**每会话 `ctx.extend()`**：否决。子上下文本身不会创建子插件 fiber，因此监听器仍属于桥接层 fiber。实际实现的桥接层使用全局监听器加显式 O(1) 解复用，以及每会话拥有的记录；agent 生命周期由 `AgentHandle` 管理。
|
||||
|
||||
**以 Agent 对象标识作为 bash 任务归属**：否决。恢复或替换后的 agent 对象可能合法地代表同一个持久会话。不透明的 session token 才是跨边界的标识，应当在插件重载后仍然存活。
|
||||
**以 Agent 对象标识作为 bash 任务归属**：否决。恢复或替换后的 agent 对象可能合法地代表同一个持久会话。不透明的会话 token 才是跨边界的标识，应当在插件重载后仍然存活。
|
||||
|
||||
## 后果
|
||||
|
||||
N 个会话可以并发地进行流式输出、prompt、权限请求、配置切换和后台任务运行，而不会交错或跨会话结算。一个会话中的取消或 dispose 不影响相邻会话。桥接层为此付出了显式 map 和隔离测试的代价，但它不会为每个会话添加一组监听器，从而避免了长连接期间的监听器扇出。
|
||||
N 个会话可以并发地进行流式输出、提示词、权限请求、配置切换和后台任务运行，而不会交错或跨会话结算。一个会话中的取消或 dispose 不影响相邻会话。桥接层为此付出了显式 map 和隔离测试的代价，但它不会为每个会话添加一组监听器，从而避免了长连接期间的监听器扇出。
|
||||
|
||||
桥接层目前仍未暴露独立关闭单个活跃会话的协议方法。当前所有记录在连接拆除时一起离开；会话关闭/恢复的生命周期能力在 ACP 功能清单中仍处于延期状态。
|
||||
|
||||
## 验证
|
||||
|
||||
多会话测试套件通过交错更新、独立的进行中 prompt、定向取消、相同 id 与不同 id 的加载竞争、权限路由、配置隔离以及拆除来驱动并发会话。工具 bash 测试证明一个会话无法读取或终止另一个会话的后台任务。
|
||||
多会话测试套件通过交错更新、独立的进行中提示词、定向取消、相同 id 与不同 id 的加载竞争、权限路由、配置隔离以及拆除来驱动并发会话。工具 bash 测试证明一个会话无法读取或终止另一个会话的后台任务。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 88fe834fdc2c0be63109dbe6dcf31859d2bc0524
|
||||
2026-06-15-code-mode.zh.md: cbc164bb4e4de9752cae4161326cb52c7d841e8b
|
||||
|
||||
@@ -18,9 +18,9 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
|
||||
|
||||
三项决策，各自在下方独立小节中展开：
|
||||
|
||||
1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式 prompt 组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
|
||||
1. **Code Mode 是 `ToolRegistry`（`dsh-tools`）的一等呈现模式**，通过经校验的 `mode` 配置选择：`'native'`（默认，贡献可见能力 schema）、`'code'`（注册表仅贡献其保留的 `run_code` 传输通道加一份生成的 SDK `.d.ts` 到系统提示词中）或 `'both'`（原生 schema 加传输通道 + SDK）。注册表在源头塑造其权威贡献；协作式提示词组装的结果仍具权威性，记录在日志中的请求头精确反映该返回的呈现。
|
||||
2. **代码执行是一个能力 seam**——`packages/code-runtime/` 包含接口包 `@deepseek-ai/dsh-code-runtime`，拥有 `ctx.codeRuntime`（[能力 seam](../architecture/2026-06-13-capability-seams.md)；消费方 = `dsh-tools`，core 消费 seam 的先例见 `agent-loop` → `dsh-llm`）。运行时对工具一无所知：它接收一段程序和命名的异步绑定，执行程序，报告 `{ value, logs, error? }`。语言和基底是后端属性，因此未来的 Python 或容器后端只是另一个实现包，而非重新设计。
|
||||
3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过 message port 桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
|
||||
3. **交付的实现是 `@deepseek-ai/dsh-code-runtime-worker`**：每次运行 spawn 一个全新的 Node worker 线程，对模型的 TypeScript 进行 type-strip 后执行，绑定通过消息端口桥接，环境为空，堆/输出/时间上限可配置，并支持硬终止。其信任姿态在设计上等同于 bash——无需 unsafe-acknowledgement flag——因为 harness 已经交付了 `dsh-bash-local`，后者以严格*更高*的环境权限执行模型编写的任意 shell 命令。
|
||||
|
||||
本说明负责定义 Code Mode 的呈现、组合、隔离与结算基础。后续的[类型化工具返回值 Agent Note](2026-07-20-code-mode-typed-tool-returns.md)负责定义生成的输出映射、规范绑定值、`ToolCallError` 和无损外层输出边界。
|
||||
|
||||
@@ -28,11 +28,11 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
|
||||
|
||||
`ToolRegistry` 获得一个经 schemastery 校验的配置（`static Config`），这是它的第一个配置：`mode: 'native' | 'code' | 'both'`，默认 `'native'`。部署通过 `cordis.yml` 翻转模式（`tools: { mode: code }`），无需改代码，遵循 no-hardcoded-tunables 约定。
|
||||
|
||||
**协议工具列表。** 注册表在 `'native'` 下贡献可见能力，在 `'code'` 下仅贡献 `run_code`，在 `'both'` 下两者都贡献。最终的 `PromptAssembly.tools` 列表记录在请求头中。`run_code` 是一个保留的呈现传输通道，位于注册和限制层之外；直接 prompt 提供方和组装 waterfall 仍各自负责自己的贡献。
|
||||
**协议工具列表。** 注册表在 `'native'` 下贡献可见能力，在 `'code'` 下仅贡献 `run_code`，在 `'both'` 下两者都贡献。最终的 `PromptAssembly.tools` 列表记录在请求头中。`run_code` 是一个保留的呈现传输通道，位于注册和限制层之外；直接提示词提供方和组装 waterfall 仍各自负责自己的贡献。
|
||||
|
||||
**与 `toolOrder` 的交互，预先说明：** 如果配置的 `systemPrompt.toolOrder` 引用了原生能力名称，在 `mode: 'code'` 下会拒绝所有组装，因为那些名称不在该模式的协议校验范围内。这是正确行为而非 bug：使用 Code Mode 的部署需要更新其 order 配置或移除它。
|
||||
|
||||
**SDK prompt 段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染 TypeScript 声明加固定的使用说明。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
|
||||
**SDK 提示词段。** 在 `'code'` 和 `'both'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染 TypeScript 声明加固定的使用说明。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
|
||||
|
||||
**组装所有权。** `run_code` 和 `tools:sdk` 作为正常的组装输入进入受信任的 `system-prompt/assemble` waterfall。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换任一贡献。waterfall 返回的组装结果是最终的，因此修改这些输入的人有责任在部署期望 Code Mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
|
||||
|
||||
@@ -46,7 +46,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
|
||||
2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
|
||||
3. **静默后结算。** 运行时结算后，桥 abort 未完成的工作并排空分发队列后再返回。成功时返回捕获的日志和完成值，将其作为规范输出；注册表再把该值渲染为持久化的 `tool/result.content`，供结果卡片直接读取。运行时失败变为 `CodeRunFailedError`；后端拒绝使用注册表的正常错误边界。两者都产生结构化的错误结果，且 `run_code` 结算后不允许子调用追加。
|
||||
|
||||
**子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute block 会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
|
||||
**子调用上下文通过父调用延后。** 在 `run_code` 内部注入会破坏父调用/结果的相邻性，因此 `ToolRunContext.deferContext()` 按分发顺序收集每个子结果的 `additionalContexts` 条目。即使程序后来抛出异常，注册表仍携带该数组；循环只在外层结果与步骤中所有兄弟结果之后追加每个条目。外层 post-execute 阻止会丢弃工具延后的条目，只暴露阻止 decision 显式附加的上下文。
|
||||
|
||||
**并发被序列化。** 每次 run 拥有一个分发队列，因此即使 `Promise.all` 也按提交顺序执行工具调用。结算时放弃尚未开始的排队调用。并行化需要每个工具的并发安全元数据。
|
||||
|
||||
@@ -75,7 +75,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
|
||||
1. **宿主侧 type-strip**，使用 Node 内置的 `stripTypeScriptTypes`（`node:module`；在本仓库的整个引擎范围 `^22.19.0 || >=24.0.0` 内可用，且保持位置不变，因此运行时错误行号与模型源码一致）。仅剥离模式拒绝不可擦除的语法（`enum`、namespaces）——该拒绝以 `error.kind: 'exception'` 加 Node 的消息返回，SDK 说明写明「仅限可擦除 TypeScript」，模型像处理其他程序错误一样自我修正。语法级失败不会 spawn worker。
|
||||
2. **每次 run spawn 一个全新 `Worker`**，来自包自身的 bootstrap 模块：`env: {}`（真正为空——比 spawn 命令的 scrubbed-env 规则更严格），`resourceLimits` 来自配置，`stdout`/`stderr` 捕获到 `logs` 而非继承。不做池化，不跨 run 保留状态：程序的世界随 worker 消亡，这使得 run 仅从日志即可重建，状态泄漏不可表达。
|
||||
3. **在 bootstrap 中执行**：剥离后的程序成为一个 `AsyncFunction` 的函数体，其参数是绑定全局变量、消费方声明的 reject 类和一个捕获式 `console` shim，因此顶层 `await` 和 `return` 可用。Code Mode 声明 `ToolCallError`，成员属性为 `toolName`；运行时无需硬编码工具即可实体化真正的构造函数。无损 JSON 完成值会精确跨越边界；`undefined` 仍表示缺席，有损值产生 `invalid-output`，过大的外层结果产生 `output-limit`，而不会退化为检查格式化后的字符串替代品。
|
||||
4. **通过 message port 桥接绑定**：worker 中的每个绑定函数发送 `{ id, global, name, args }` 并等待回复；宿主根据请求的绑定校验名称、调用、并回复 `{ id, ok, value }` 或 `{ id, ok: false, message }`（宿主侧绑定拒绝变为程序侧 rejection）。worker 侧的命名空间对象通过 `defineProperty` 构建为 null-prototype，因此名为 `__proto__`、`constructor` 或 `toString` 的绑定是普通自有属性，而非原型链碰撞。未知名称、重复 id 和结算后消息被拒绝或忽略——端口协议假设对端是恶意的，因为对端运行的是模型代码。
|
||||
4. **通过消息端口桥接绑定**：worker 中的每个绑定函数发送 `{ id, global, name, args }` 并等待回复；宿主根据请求的绑定校验名称、调用、并回复 `{ id, ok, value }` 或 `{ id, ok: false, message }`（宿主侧绑定拒绝变为程序侧 rejection）。worker 侧的命名空间对象通过 `defineProperty` 构建为 null-prototype，因此名为 `__proto__`、`constructor` 或 `toString` 的绑定是普通自有属性，而非原型链碰撞。未知名称、重复 id 和结算后消息被拒绝或忽略——端口协议假设对端是恶意的，因为对端运行的是模型代码。
|
||||
5. **强制独立预算。** `computeMs` 计量 worker 忙碌时间，允许慢速的 awaited 工具而不放过热循环。`maxWallMs` 约束总经过时间，包括未解析的等待。`maxOutputBytes` 只约束序列化后的外层日志、完成值或诊断的组合；中间绑定值没有字节数上限。到期、取消和完成都终止 worker，堆退出或外层溢出会作为显式失败报告。
|
||||
6. **dispose 至静默**：服务自身的 dispose（资源释放）终止进行中的 worker 并*等待*其退出后再 resolve，遵循[防御性模式](../../../../docs/defensive-patterns.md)。
|
||||
|
||||
@@ -94,7 +94,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
|
||||
## 测试
|
||||
|
||||
- **Worker 运行时：** 真实 worker 测试覆盖类型化的绑定值与失败、每一种无损 JSON 根类型的完成值、无效和超限输出、精确的组合账本边界、compute 和 wall 预算、恶意绑定流量、空环境以及 dispose 至静默。一个构建后包测试在纯 Node 下运行 worker 入口。
|
||||
- **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层 block 抑制以及 HMR（热模块替换）清理。
|
||||
- **注册表集成：** 测试覆盖代码生成、所有呈现模式、保留名称和限制规则、scoped 可见性、权威组装重写、`toolOrder`、运行时兼容性失败、完整流水线子分发、parent-token 关联、序列化、取消和队列排空、JSON 规范化、错误传播、日志事件、成功与失败程序中的有序上下文延后、外层阻止抑制以及 HMR（热模块替换）清理。
|
||||
- **带密钥 e2e：** 真实模型在一个程序中组合两次 bash 调用；另一个模型通过 Code Mode fs 分发发现嵌套的工作区指令。测试验证折叠的请求头、关联的分发事件、结果文件、延后上下文和模型行为。
|
||||
- **快照：** `code-mode-turn`、`both-mode-turn` 和 `code-mode-workspace-context` fixture（测试前置数据）固定 SDK 文本、请求头工具列表、分发事件、延后上下文和结果卡片。
|
||||
|
||||
@@ -122,7 +122,7 @@ SDK 指示模型编写一个异步的可擦除 TypeScript 函数体，通过 `aw
|
||||
|
||||
**`stripTypeScriptTypes` 标记为 experimental。** 它与 Node 自身原生 `.ts` 执行背后的引擎（amaro/swc）相同，在本仓库的整个引擎范围内作为 API 暴露。缓解措施：运行时的单元测试套件固定了所依赖的行为（位置保持、可擦除限制的拒绝消息形状宽松匹配），调用位于一个私有函数之后，且 `amaro`/`sucrase` 是 API 变化时的直接替代品。仅可擦除子集是面向模型的契约线，错误路径是一个可工作的反馈循环，而非死胡同。
|
||||
|
||||
**SDK 的 prompt 成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
|
||||
**SDK 的提示词成本，尤其在 `'both'` 下。** `.d.ts` 可能与它补充的原生 schema 体量相当；`'both'` 携带两种表示。前缀稳定性 + 提供方缓存摊销了每会话成本；mode 是每部署的；本 Agent Note 不做无条件节省的声明。何时优先使用哪种模式的量化指导明确属于上线后学习。
|
||||
|
||||
**注册表 scope 增长。** `dsh-tools` 吸收了代码生成、一个工具、一个桥和一个事件。通过包内的模块边界（`ts-types.ts`、`code-mode.ts` 与 `schema.ts`/`json-schema.ts`/`presentation.ts` 并列）和 seam 约束：所有基底相关的内容都在 `ctx.codeRuntime` 之后。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-18-compaction-capability-seam.md: a263b5e7d0245bd1279024a50e05b2f33edad521
|
||||
2026-06-18-compaction-capability-seam.zh.md: b86393332592bd92f6e6be81d610370c8c2bb23e
|
||||
2026-06-18-compaction-capability-seam.zh.md: df0cf9d9131978e608d47124ba0f0db0343ee12a
|
||||
|
||||
@@ -105,7 +105,7 @@ compact/end → log-only. Releases the lock (carries `error` on a recoverab
|
||||
|
||||
`compact/end` 保留其 `error?` 字段（与 `tool/result` 的自包含错误一致——一个事件即可区分成功与失败，无需关联兄弟事件）。没有单独的 `compact/error` 事件。
|
||||
|
||||
**核心 session 修复保持对压缩无感知——这是有意为之。** `interruptedTurnClosers` 从不被教导 `compact/*`。如果教导它，每个未来的 `xxx/start … xxx/end` 插件对都必须修补核心模块——这恰好是能力 seam 架构存在的意义所要避免的耦合。由于仅日志的孤儿是惰性的，不需要特殊修复：通用轮次修复加上未落地 surface 变更的惰性就足够了。
|
||||
**核心会话修复保持对压缩无感知——这是有意为之。** `interruptedTurnClosers` 从不被教导 `compact/*`。如果教导它，每个未来的 `xxx/start … xxx/end` 插件对都必须修补核心模块——这恰好是能力 seam 架构存在的意义所要避免的耦合。由于仅日志的孤儿是惰性的，不需要特殊修复：通用轮次修复加上未落地 surface 变更的惰性就足够了。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
@@ -119,7 +119,7 @@ compact/end → log-only. Releases the lock (carries `error` on a recoverab
|
||||
|
||||
- **包**：`packages/compact/compact` 提供接口，`compact-basic` 提供后端，`compact-tool-result-prune` 提供可选的确定性重写。`packages/llm/token-meter` 独立拥有回放感知的测量。消费方层推迟。
|
||||
- **自动 seam**：`agent/post-step`（`@mode serial`）处理成功调用的压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。通用 `agent/pre-step` 保持为四参数检查点，不携带压缩专属的提示词/前缀 payload。
|
||||
- **`SessionEventMap`** 通过声明合并（merge-extensible）获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。
|
||||
- **`SessionEventMap`** 通过可合并扩展的声明合并获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。
|
||||
- **`dsh-compact`** 拥有 `COMPACT_CHECKPOINT_SOURCE`、`isCompactCheckpointSource(source)`、`toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`。该标记用于跨后端实现识别替换摘要。带缓存的 surface 边缘检查会防止 `compactRegion` 和 `compactIfNeeded` 拆分工具调用/结果对，按 seq 校验当前成员关系，从每个切割点的一条平衡序列回答两侧边缘，并拒绝陈旧或缺失的 seq 与孤立结果。
|
||||
- **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、完整溯源信息和仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用；已校验的替换仍是位于轮次内的重写。
|
||||
- **接线**：`examples/tui-agent/cordis.yml` 依次加载零配置的 `dsh-token-meter`、`dsh-compact-tool-result-prune` 和 `dsh-compact-basic`；服务级默认值使组合无需重复数值策略即可使用。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-21-subagent-capability-seam.md: 9c17a93751de209e5e4e5a0ca7d7b1d8e5656a47
|
||||
2026-06-21-subagent-capability-seam.zh.md: 9cab992e86120dd32cedea05b63c777b8678d409
|
||||
2026-06-21-subagent-capability-seam.zh.md: 9386b495a03611ecbf1d45e53c8ba0aa87eaa6f0
|
||||
|
||||
@@ -20,7 +20,7 @@ harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent（智
|
||||
|
||||
### 为何不采用 bash seam 的形状
|
||||
|
||||
bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个 context 中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口 / 实现 / 消费方）；只是「一个 vs. 多个实现」这个维度不同。
|
||||
bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在每个上下文中只注册恰好一个 `BashExecutor`；加载第二个会抛异常。这对 bash 是正确的（一台机器、一种执行命令的方式），但对这里是错误的：共存才是需求。因此 subagent 服务是一个**命名提供方注册表**——每个实现以唯一名称注册，调用方按名称选择——镜像 **LLM（大语言模型）适配器注册表**（`LlmService.registerAdapter`），而非单服务的 bash 执行器。seam 仍然是由三个包构成的结构（接口 / 实现 / 消费方）；只是「一个 vs. 多个实现」这个维度不同。
|
||||
|
||||
## 决策
|
||||
|
||||
@@ -59,7 +59,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
|
||||
|
||||
### 提供方选择是配置，不面向模型
|
||||
|
||||
`dsh-tool-subagent` 绑定到恰好一个提供方名称（`Config.provider`）；模型只看到 `{ description, prompt }`。若要暴露多种传输方式，请多次加载该工具插件，每次绑定不同的提供方和不同的 `toolName`（工具注册表拒绝重名）。*服务*持有多提供方注册表；*工具*选择其中一个——本版 schema 中没有 provider/type 参数。
|
||||
`dsh-tool-subagent` 绑定到恰好一个提供方名称（`Config.provider`）；模型只看到 `{ description, prompt }`。若要暴露多种传输方式，请多次加载该工具插件，每次绑定不同的提供方和不同的 `toolName`（工具注册表拒绝重名）。*服务*持有多提供方注册表；*工具*选择其中一个——本版 schema 中没有提供方/type 参数。
|
||||
|
||||
## 测试
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-22-acp-subagent-backend.md: a45ce5e34873249969bbe4dabb87a89d10246b3d
|
||||
2026-06-22-acp-subagent-backend.zh.md: f313c11b22dc6aae6d1d1e72fce2381a572ded8d
|
||||
2026-06-22-acp-subagent-backend.zh.md: 3b6a11efc1ae0427eb5ce3b30029b77b00d6801a
|
||||
|
||||
@@ -38,7 +38,7 @@ ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`
|
||||
|
||||
## 测试
|
||||
|
||||
- **无需密钥的单元/集成测试：** 一个脚本化的 ACP 子进程通过真实 stdio 测试 prompt/output 流、所有 stop-reason 映射、信号与 dispose 取消（包括 pre-abort、pre-session 竞态和管道断裂场景）、两种权限策略、被忽略的非消息更新、命令缺失时的清理、提供方重载以及命名空间导出。
|
||||
- **无需密钥的单元/集成测试：** 一个脚本化的 ACP 子进程通过真实 stdio 测试提示词/输出流、所有 stop-reason 映射、信号与 dispose 取消（包括 pre-abort、会话前竞态和管道断裂场景）、两种权限策略、被忽略的非消息更新、命令缺失时的清理、提供方重载以及命名空间导出。
|
||||
- **无需密钥的 Loader 组合测试：** 仅用于测试的 cordis.yml 通过真实 Loader 启动 stdio 应用，并省略后端的 `cwd`；脚本化模型委派一次，脚本化子进程则证明它在父会话工作区中运行，且 ACP 也对外公布了该工作区，从而端到端覆盖 cwd 继承分支。
|
||||
- **需要密钥的 e2e 测试：** 后端 spawn 真实的 ACP 示例；其模型回答 `PONG`，写入 `proof.txt`，父进程验证该文件。
|
||||
- **快照缺口：** 每个 ACP 子 agent 是独立进程，拥有自己的回放会话，不同于进程内的按会话回放。确定性 mock 服务器覆盖率已具备；`TODO(acp-subagent-replay)` 跟踪父进程对回放中子 agent 的回放支持。
|
||||
@@ -59,4 +59,4 @@ ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`
|
||||
|
||||
## 后续提供方
|
||||
|
||||
同样的进程外 spawn/prompt/stream/cancel 形态可泛化到 seam Agent Note 中列出的其他传输方式——A2A、Codex app-server 和 Claude Code Agent SDK——每个都是按名称注册的兄弟提供方。ACP 后端证明了 seam 支持跨进程边界；其余在机制上类似。
|
||||
同样的进程外启动/提示词/流式输出/取消形态可泛化到 seam Agent Note 中列出的其他传输方式——A2A、Codex app-server 和 Claude Code Agent SDK——每个都是按名称注册的兄弟提供方。ACP 后端证明了 seam 支持跨进程边界；其余在机制上类似。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 48d5ace1192071d8b2f0017042ae21fa938ada48
|
||||
2026-06-25-ask-user-question.zh.md: eb166acfef7ed8f7ab4eb3018bf161a9ecc3549e
|
||||
|
||||
@@ -12,11 +12,11 @@ agent（智能体）有时仅凭模型推理（inference）无法安全地继续
|
||||
|
||||
## 决策
|
||||
|
||||
引入 `dsh-user-interaction` 作为 `ctx.userInteraction` 的提供方无关接口包，与面向模型的消费方 `dsh-tool-ask-user` 一同放在 `packages/ui` 下。这一分组是有意为之的：向人类提问是一种由 UI 支撑的产品功能，不属于无提供方的核心主干。seam 仍然拥有稳定的请求/应答/错误词汇，而 UI 产品界面提供收集答案的具体 provider。该工具注册 `ask_user_question`，转发 `{ questions, agent, signal }`，并将 provider 计算出的结构化答案作为工具结果返回。
|
||||
引入 `dsh-user-interaction` 作为 `ctx.userInteraction` 的提供方无关接口包，与面向模型的消费方 `dsh-tool-ask-user` 一同放在 `packages/ui` 下。这一分组是有意为之的：向人类提问是一种由 UI 支撑的产品功能，不属于无提供方的核心主干。seam 仍然拥有稳定的请求/应答/错误词汇，而 UI 产品界面提供收集答案的具体提供方。该工具注册 `ask_user_question`，转发 `{ questions, agent, signal }`，并将提供方计算出的结构化答案作为工具结果返回。
|
||||
|
||||
面向模型的请求词汇有意与产品调研 schema 对齐：`ask_user_question({ questions: [{ id, question, header?, options?: [{ label, description? }], multi_select? }] })`。`id` 按问题提供并在结果中回传，使批量请求无需依赖问题文本即可路由。`label` 既是面向用户的显示文本，也是返回给模型的选中值；没有单独的 `value`，没有 `recommended`，没有 `allow_custom`，也没有 `desc` 别名。
|
||||
|
||||
Provider 返回 `{ answers: [{ id, selected, custom? }] }`。`selected` 始终是选中选项 label 的数组，因此单选和 `multi_select` 的答案共享同一种结果形状。`custom` 承载自由文本的「其他」答案；无选项的问题直接收集 `custom`。当 `custom` 存在时，它覆盖任何已选择的选项，`selected` 为空。支持部分完成的提供方使用现有的 `{ id, selected: [] }` 形状表示某项被有意跳过，在不扩展工具结果词汇的前提下保留其他答案。
|
||||
提供方返回 `{ 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()` 传出。这与结构化错误分类体系一致，使模型或包装插件能够区分「用户取消」与一般的抛出异常。
|
||||
|
||||
@@ -26,7 +26,7 @@ Provider 返回 `{ answers: [{ id, selected, custom? }] }`。`selected` 始终
|
||||
|
||||
Web 输入区一次显示一个问题，同时在会话对象层保留每个请求。它支持单选、多选、无选项问题或显式自定义答案、描述文本与可视化推荐标记，但不会自动选中推荐项。选择单选项后会立即进入下一项；当所有项都已回答或显式跳过时，按 Enter 提交；IME 组字期间按 Enter 只会确认输入候选项。页脚只跳过当前项并保留先前的草稿；关闭控件以 `ASK_CANCELLED` 拒绝整个工具调用。常规输入区只有在 host 的 resolved 帧移除待处理项后才会恢复。
|
||||
|
||||
`dsh-tui` 将每个问题渲染为键盘叠层，展示选项描述，支持单选、多选和自由格式自定义答案，并在中止、provider dispose（资源释放）或终端关闭时拒绝待处理的问题。批量请求和并发请求都会排队，确保同一时刻只有一个叠层占用键盘焦点。
|
||||
`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`。
|
||||
|
||||
@@ -34,9 +34,9 @@ ACP 映射有意使用 elicitation 而非 `session/request_permission`。`reques
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**Assistant 文本后跟一个停止的轮次。** 模型可以在纯 assistant 文本中向用户提问然后停止。这会丢失结构化选项元数据，UI 没有提供方无关的方式来渲染选择，且下一条人类回答只能作为新的 user prompt 到达，而非作为需要答案的那次操作的结果。
|
||||
**Assistant 文本后跟一个停止的轮次。** 模型可以在纯 assistant 文本中向用户提问然后停止。这会丢失结构化选项元数据，UI 没有提供方无关的方式来渲染选择，且下一条人类回答只能作为新的 user 提示词到达，而非作为需要答案的那次操作的结果。
|
||||
|
||||
**核心拥有的 ask-user 包。** 最初实现将 seam 和面向模型的工具分别放在 `packages/core` 和 `packages/ui`，但两者描述的是同一个由 UI 支撑的人机交互功能。seam 仍然是提供方无关的，但它不是像会话、工具或 agent 注册表那样的无提供方核心基础设施。将 `dsh-user-interaction` 和 `dsh-tool-ask-user` 一起放在 `packages/ui` 下，使包的划分与产品边界一致：应用和 bridge 提供人类答案的 provider，stdio 应用选择性加载面向模型的工具。
|
||||
**核心拥有的 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` 是带可选自由格式答案的信息收集。将权限用于通用提问会混淆两个不同的产品概念，并使未来的权限门禁更难推理。
|
||||
|
||||
@@ -46,10 +46,10 @@ ACP 映射有意使用 elicitation 而非 `session/request_permission`。`reques
|
||||
|
||||
ACP elicitation 目前在 SDK 中标记为 unstable。回退仍然是结构化的：如果客户端未实现它，工具返回 `ASK_FAILED` 而非挂起。后续 ACP 稳定化可能重命名或重塑该方法；该迁移应限制在 `dsh-acp` 内部，因为核心 `ctx.userInteraction` 词汇是提供方无关的。
|
||||
|
||||
该功能赋予模型一个强大的暂停原语，因此 prompt 引导很重要。工具描述告诉模型：提问要简洁，尽可能使用选项。产品策略后续可以包装 `tools/execute` 来限制工具何时可用，但循环不应对其做特殊处理。
|
||||
该功能赋予模型一个强大的暂停原语，因此提示词引导很重要。工具描述告诉模型：提问要简洁，尽可能使用选项。产品策略后续可以包装 `tools/execute` 来限制工具何时可用，但循环不应对其做特殊处理。
|
||||
|
||||
`dsh-user-interaction` 和 `dsh-tool-ask-user` 都位于 `packages/ui`，因为它们共同构成一个面向产品的人机交互能力。`agent-core` 不加载工具或 provider。`dsh-tui-demo` 选择性加载 seam、TUI provider 和面向模型的工具。`dsh web` 在 host 运行时启动 seam/提供方，并通过选定的 Web question 插件暴露该工具。`acp-agent` 默认只保留 `userInteraction` seam/provider：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-agent` 默认只保留 `userInteraction` seam/提供方：ACP elicitation 支持仍取决于客户端，因此 ACP 叶节点必须在其客户端能完成 elicitation 请求后才有意加载面向模型的工具。
|
||||
|
||||
## 测试
|
||||
|
||||
单元覆盖率固定了以下场景：provider 注册/释放、重复 provider 拒绝、provider 就绪前中止、空问题拒绝、通过 `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 测试覆盖选项描述、排队请求、关闭/中止清理、无选项自由格式输入、无效选择、重复多选和批量问题流。ACP bridge 测试驱动一个真实的内存 ACP 连接（使用真实的 `ask_user_question` 工具），验证选中选项、custom 覆盖 choice、多选和无选项自由格式 elicitation 路径能继续 agent loop。Web 测试固定稳定 id 重放、响应校验、首个响应胜出的结算、重复和迟到响应、整个请求的取消与拥有方中止的区别、单选后前进、IME 安全的 Enter 提交、按项跳过保留、输入区接管、结构化批量提交，以及常规输入区的恢复。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 565db37b1bf36c2aa33109870df4b36a82a57bdc
|
||||
2026-06-29-todo-write-tool.zh.md: 3afc03a393284e2a9c2d6e234bc95f0faebbfb48
|
||||
|
||||
@@ -38,7 +38,7 @@ claude-code V1 的条目是 `{ content, status, activeForm }`；后来（V2）
|
||||
|
||||
### 校验：低成本的中间路线
|
||||
|
||||
schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，以及超过一个 `in_progress` 任务。claude-code 将单一 in_progress 交给 prompt 约束；oh-my-pi 在代码中强制。我们取中间路线：强制执行使计划*连贯*的低成本不变式（无空任务、无重复、最多一个活跃），但将排序和保持列表最新的纪律通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。
|
||||
schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，以及超过一个 `in_progress` 任务。claude-code 将单一 in_progress 交给提示词约束；oh-my-pi 在代码中强制。我们取中间路线：强制执行使计划*连贯*的低成本不变式（无空任务、无重复、最多一个活跃），但将排序和保持列表最新的纪律通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。
|
||||
|
||||
## 为何没有 cordis-catalog 条目 / 没有 `@mode`
|
||||
|
||||
@@ -51,7 +51,7 @@ schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重
|
||||
- **真实 Loader 路径**——插件通过 `Loader.unwrapExports` 运行，断言命名空间导出形状存活（它有 `inject`，因此一个意外的 default 导出会在加载时崩溃——postmortem/0001）。
|
||||
- **全循环集成**——一个脚本化的 mock 模型通过真实 agent loop（智能体循环）调用 `todo_write`；`todo/write` 事件落地，第二次调用替换它。
|
||||
- **`session/load` 回放**——持久化的 `todo/write` 在新的 ACP bridge 加载会话时重新发出 `plan` 更新。
|
||||
- **带密钥 e2e + 快照**——真实 prompt 诱导一次 `todo_write`；快照预期输出获得 `plan` 通知和日志事件。
|
||||
- **带密钥 e2e + 快照**——真实提示词诱导一次 `todo_write`；快照预期输出获得 `plan` 通知和日志事件。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 3b1fe00ffcd26eaf42af0c089d4659bcef60763d
|
||||
2026-06-30-hook-bridges.zh.md: 5f3adef958738d9d23c159c388be35b89f321828
|
||||
|
||||
@@ -8,7 +8,7 @@ Status: implemented
|
||||
|
||||
harness 的扩展面是其类型化的拦截 seam（见[拦截 seam Agent Note](2026-06-30-interception-seams.md)）：所谓「原生钩子」不过是一个普通的 Cordis 插件，订阅 `agent/session-start`、`agent/prompt-submit`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-continuation`、`subagent/start`、`subagent/end`。但用户带着**既有的** Claude Code（CC）和 Codex 钩子配置到来，一个 `hooks.json`（或 settings 文件中的 `hooks` 键）里满是 shell 命令钩子，并希望它们原样运行。本 Agent Note 引入两个**桥接插件**，将外部 shell 钩子协议翻译到类型化 seam 上，构建于共享的协议格式（wire format）库之上（见 [hook-protocol-lib Agent Note](2026-06-30-hook-protocol-lib.md)）。
|
||||
|
||||
贯穿整个设计的定位：**桥接是兼容性适配器，不是高级工具。** 桥接能做的事（阻止工具、注入上下文、强制继续、观察 subagent），原生 Cordis 插件都能做得更强——类型化返回值、完整 `ctx`、无序列化边界。桥接存在的理由是运行外部 CC/Codex 命令钩子中被明确支持的子集。这使每个桥接保持精简：解析配置、选择匹配模式、构建每事件的 payload、调用共享库的 `runHook` + `mergeHookOutputs`，再将中性结果映射为 seam Decision。各 package 的 README 维护着当前不支持的事件和部分字段的完整清单，以官方协议为参照。
|
||||
贯穿整个设计的定位：**桥接是兼容性适配器，不是高级工具。** 桥接能做的事（阻止工具、注入上下文、强制继续、观察 subagent），原生 Cordis 插件都能做得更强——类型化返回值、完整 `ctx`、无序列化边界。桥接存在的理由是运行外部 CC/Codex 命令钩子中被明确支持的子集。这使每个桥接保持精简：解析配置、选择匹配模式、构建每事件的 payload、调用共享库的 `runHook` + `mergeHookOutputs`，再将中性结果映射为 seam Decision。各包的 README 维护着当前不支持的事件和部分字段的完整清单，以官方协议为参照。
|
||||
|
||||
## 决策
|
||||
|
||||
@@ -39,7 +39,7 @@ CC 桥接的 `ask` 结果是一条真正的权限路径，而非终态桥接决
|
||||
|
||||
### 添加上下文不是否决——先 delegate，再 prepend
|
||||
|
||||
仅附加 `additionalContext`（没有 block/deny）的钩子并不是桥接可以独自返回的决策：在 waterfall 监听器中不调用 `next()` 就返回 `allow`/`accept`，会短路其后的每个 `agent/prompt-submit` / `tools/post-execute` 监听器，使注册在桥接之后的策略/沙箱插件看不到该提示词。因此，每个桥接都会先通过 `next()` 委托，再将自身上下文加入下游决策。两个 seam 都携带有序的 `additionalContexts` 数组，因此桥接会在保留所有下游来源、信封和元数据字段的同时，前置加入其独立来源的条目；下游 prompt block 仍会丢弃所有上下文，因为提示词从未到达模型，而 post-tool block 语义可以显式保留上下文。Code Mode 会通过外层 `run_code` 结果转送同一数组。只有钩子本身真正返回 `deny`/`block` 才会短路。测试断言：上下文钩子允许后，较晚的监听器仍能阻止提示词，且保留的 prompt 和 post-tool 上下文仍彼此分离。
|
||||
仅附加 `additionalContext`（没有 block/deny）的钩子并不是桥接可以独自返回的决策：在 waterfall 监听器中不调用 `next()` 就返回 `allow`/`accept`，会短路其后的每个 `agent/prompt-submit` / `tools/post-execute` 监听器，使注册在桥接之后的策略/沙箱插件看不到该提示词。因此，每个桥接都会先通过 `next()` 委托，再将自身上下文加入下游决策。两个 seam 都携带有序的 `additionalContexts` 数组，因此桥接会在保留所有下游来源、信封和元数据字段的同时，前置加入其独立来源的条目；下游提示词阻止仍会丢弃所有上下文，因为提示词从未到达模型，而工具后阻止语义可以显式保留上下文。Code Mode 会通过外层 `run_code` 结果转送同一数组。只有钩子本身真正返回 `deny`/`block` 才会短路。测试断言：上下文钩子允许后，较晚的监听器仍能阻止提示词，且保留的提示词和工具后上下文仍彼此分离。
|
||||
|
||||
### CLAUDE_PROJECT_DIR 默认为会话工作区
|
||||
|
||||
@@ -67,4 +67,4 @@ Claude Code 始终导出 `CLAUDE_PROJECT_DIR`，常见的未修改钩子引用 `
|
||||
|
||||
## 后果
|
||||
|
||||
匹配语义、退出码处理和合并优先级位于 `dsh-hook-protocol`；每个桥接只负责解析配置、构建方言 payload 和映射结果。逐文件覆盖率包含配置分支以及通过真实循环、`dsh-bash-local` 和 shell 脚本的端到端映射，同时一个真实 Loader 冒烟测试守护 package 的导出形态。原生插件绕过协议格式，直接返回类型化决策。
|
||||
匹配语义、退出码处理和合并优先级位于 `dsh-hook-protocol`；每个桥接只负责解析配置、构建方言 payload 和映射结果。逐文件覆盖率包含配置分支以及通过真实循环、`dsh-bash-local` 和 shell 脚本的端到端映射，同时一个真实 Loader 冒烟测试守护包的导出形态。原生插件绕过协议格式，直接返回类型化决策。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-30-hook-protocol-lib.md: 19a69119befde99417b736edf38923ec6ac5fa7c
|
||||
2026-06-30-hook-protocol-lib.zh.md: 37bdd1ad0c4f7b8e980b9f81cff787b8896dfc4c
|
||||
2026-06-30-hook-protocol-lib.zh.md: f4950eea2b02e86ed7109f8ebdaab29dd77428d8
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
hooks 子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出契约，以及相同的 command-hook 执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
|
||||
钩子子系统提供两个桥接插件：一个运行用户既有的 Claude Code（CC）钩子，另一个运行 Codex 钩子。研究参考实现（`~/repos/refs/claude-code`、`~/repos/refs/codex`）后发现一个决定性事实：**Codex 有意重新实现了 CC 钩子协议的一个子集。** 它的引擎读取相同的 `hooks.json`，使用相同的 matcher-group 形状、相同的 exit-code/structured-stdout 输出契约，以及相同的命令钩子执行模型。Codex 的源码甚至以 Claude 的引擎命名，并在注释中标注了「有意偏离」之处。因此，如果不做抽取，两个桥接插件将大量重复协议逻辑。
|
||||
|
||||
本 Agent Note 引入 `@deepseek-ai/dsh-hook-protocol`，一个**库**（不是插件——它不注册也不注入任何东西），持有两个桥接插件共同依赖的真正相同的原语。共享与方言专属之间的分界是本设计的重心。
|
||||
|
||||
@@ -16,10 +16,10 @@ hooks 子系统提供两个桥接插件：一个运行用户既有的 Claude Cod
|
||||
|
||||
**共享（本库）：**
|
||||
- **Matcher** — `matchesMatcher(pattern, query, mode)`。两种方言唯一不同的轴被收敛为 `mode` 参数：`claude` 将纯 `[A-Za-z0-9_|]+` 模式视为字面量（管道符 = 精确匹配的多选），其余视为正则；`codex` 始终是无锚定正则。缺省/`''`/`'*'` 匹配一切；无效正则匹配空集（绝不向 agent loop（智能体循环）抛异常）。
|
||||
- **Execution** — `runHook(bash, hook, options)`。通过 `ctx.bash` seam 而非自建 `spawn` 运行 command hook：执行器已提供清洗但可覆盖的 env、进程组 kill 和超时，正是协议所需的能力；`dsh-bash` 的 `stdin`/`env` 字段（正是为此添加的）是进程内桥接插件被允许使用的受信插件接口。它将桥接插件构建的 payload 序列化到 stdin（CC 时追加尾部换行），遵守钩子的 `timeoutSec`（否则使用 `DEFAULT_HOOK_TIMEOUT_MS`，即两种方言共享的 10 分钟参考默认值），且从不抛异常（执行器拒绝变为 non-blocking-error 的 `HookOutput`）。
|
||||
- **Decode** — `parseHookOutput(exit, stdout, stderr)`，exit-code + structured-stdout 编解码器，产出方言无关的 `HookOutput`。Exit `0` → 宽松 JSON 解析 stdout；exit `2` → blocking error，`stderr` 为原因（以 `decision: 'block'` 呈现，调用方无需单独处理 exit-code 分支）；其他 → non-blocking error。解析 CC structured-stdout 中在某条路径上有消费方的字段（`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`）；桥接插件只采纳对其方言有意义的子集。在任何路径上都没有消费方的字段不予解析（CC 的 `suppressOutput`——钩子 stdout 在此处从不进入 transcript（文本记录），因此无需抑制；见 [tighten-hook-protocol-contract Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)）。
|
||||
- **Merge** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，block reason 以 `\n\n` 拼接，context/system-messages 按序累积。
|
||||
- **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，declaration-merge 进 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与轮次包含关系在各桥接插件间保持一致。`appendHookResult` 还拥有持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
|
||||
- **执行** — `runHook(bash, hook, options)`。通过 `ctx.bash` seam 而非自建 `spawn` 运行命令钩子：执行器已提供清洗但可覆盖的 env、进程组 kill 和超时，正是协议所需的能力；`dsh-bash` 的 `stdin`/`env` 字段（正是为此添加的）是进程内桥接插件被允许使用的受信插件接口。它将桥接插件构建的 payload 序列化到 stdin（CC 时追加尾部换行），遵守钩子的 `timeoutSec`（否则使用 `DEFAULT_HOOK_TIMEOUT_MS`，即两种方言共享的 10 分钟参考默认值），且从不抛异常（执行器拒绝变为 non-blocking-error 的 `HookOutput`）。
|
||||
- **解码** — `parseHookOutput(exit, stdout, stderr)`，exit-code + structured-stdout 编解码器，产出方言无关的 `HookOutput`。Exit `0` → 宽松 JSON 解析 stdout；exit `2` → blocking error，`stderr` 为原因（以 `decision: 'block'` 呈现，调用方无需单独处理 exit-code 分支）；其他 → non-blocking error。解析 CC structured-stdout 中在某条路径上有消费方的字段（`continue`/`stopReason`/`decision`/`hookSpecificOutput.{permissionDecision,additionalContext,updatedInput}`/`systemMessage`）；桥接插件只采纳对其方言有意义的子集。在任何路径上都没有消费方的字段不予解析（CC 的 `suppressOutput`——钩子 stdout 在此处从不进入 transcript（文本记录），因此无需抑制；见 [收紧钩子协议契约 Agent Note](../simplification/2026-07-04-tighten-hook-protocol-contract.md)）。
|
||||
- **合并** — `mergeHookOutputs(outputs)`，将多个匹配钩子的输出折叠为一个最严格的 `MergedHookOutcome`：权限优先级 **deny > ask > allow**，halt 在首个 `continue:false` 时粘滞，阻止原因以 `\n\n` 拼接，context/system-messages 按序累积。
|
||||
- **`hook/*` 会话事件** — `hook/invoked` / `hook/result`，通过声明合并进入 `SessionEventMap`（仅日志，如 `compact/*`——不是 `SurfaceEventType`），配有 `appendHookInvoked`/`appendHookResult` 辅助函数，确保 invoked/result 配对与轮次包含关系在各桥接插件间保持一致。`appendHookResult` 还拥有持久化记录的语义：decision 字符串（钩子解析出的 decision，否则 `continue:false` 时为 `'stop'`，否则为 `'pass'`）和 500 字符的 `stderrSummary` 截断均从本库的 `HookOutput` 派生，而非各桥接插件各自实现。
|
||||
|
||||
**方言专属（桥接插件）：** 构建每个事件的 stdin payload（CC 的 base+per-event 字段集 vs Codex 的 snake_case 加 `turn_id`/`model` 额外字段）、方言的 env 与 `${CLAUDE_PLUGIN_ROOT}` 替换（CC）vs 无替换（Codex），以及将方言无关的 `HookOutput`/`MergedHookOutcome` 映射为 harness seam 专属的类型化 Decision（`PreToolDecision`、`PromptDecision`、`ContinuationDecision`、`PostToolDecision`）。
|
||||
|
||||
@@ -29,4 +29,4 @@ hooks 子系统提供两个桥接插件：一个运行用户既有的 Claude Cod
|
||||
|
||||
## 后果
|
||||
|
||||
每个桥接插件解析配置、构建方言 payload、调用共享的 runner 与 merge 逻辑、映射 decision、追加 `hook/*`。协议测试覆盖每种 matcher 模式、exit-code 与编解码器字段、runner 管道、merge 优先级和审计辅助函数，逐文件 100% 覆盖率；桥接插件测试验证库的真实加载路径。`updatedInput` 已解析但仅记录日志并发出警告，直到 [input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)落地。
|
||||
每个桥接插件解析配置、构建方言 payload、调用共享的 runner 与合并逻辑、映射 decision、追加 `hook/*`。协议测试覆盖每种 matcher 模式、exit-code 与编解码器字段、runner 管道、合并优先级和审计辅助函数，逐文件 100% 覆盖率；桥接插件测试验证库的真实加载路径。`updatedInput` 已解析但仅记录日志并发出警告，直到 [input-rewrite 提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)落地。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: fbaecf23d83357bd38984ef6948f5c2ef45e90b1
|
||||
2026-06-30-interception-seams.zh.md: 3886ed21504abfe14a2ccb344d7aa0d3f8d25064
|
||||
|
||||
@@ -6,9 +6,9 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那样在生命周期节点扩展或管控 agent（智能体）。驱动本设计的关键视角转换是：**「原生钩子」不是一个包**——原生钩子只是一个普通的 Cordis 插件，订阅规范的生命周期事件。因此真正的产品是一个*强大、类型完备的规范事件表面*；CC/Codex 桥接（`dsh-hooks-claude` / `dsh-hooks-codex` 包）只是将外部 shell-hook 协议映射到同一表面的翻译层。桥接能做的事，普通插件可以直接做——而且更强大（无序列化边界、完整 `ctx`、类型化返回值）。
|
||||
harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那样在生命周期节点扩展或管控 agent（智能体）。驱动本设计的关键视角转换是：**「原生钩子」不是一个包**——原生钩子只是一个普通的 Cordis 插件，订阅规范的生命周期事件。因此真正的产品是一个*强大、类型完备的规范事件表面*；CC/Codex 桥接（`dsh-hooks-claude` / `dsh-hooks-codex` 包）只是将外部 shell 钩子协议映射到同一表面的翻译层。桥接能做的事，普通插件可以直接做——而且更强大（无序列化边界、完整 `ctx`、类型化返回值）。
|
||||
|
||||
该表面需要为以下场景提供各自独立的契约：逐 prompt 策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md)提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
|
||||
该表面需要为以下场景提供各自独立的契约：逐提示词策略（CC 的 `UserPromptSubmit`）、会话启动观测（CC 的 `SessionStart`）、工具执行前策略、环绕调度控制、工具执行后变换、最终结果观测，以及携带面向模型的原因的继续执行。如果把这些阶段混为一谈，插件就会获得不需要的 mutation 通道，而终结性将依赖监听器的注册顺序。[事件域语义 Agent Note](../architecture/2026-06-30-event-domain-semantics.md)提供了三域规则与类型化 Decision 惯用法；本 Agent Note 将其应用于生命周期 seam。
|
||||
|
||||
## 决策
|
||||
|
||||
@@ -16,7 +16,7 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
|
||||
|
||||
**Agent 事件**（`dsh-agent`）：
|
||||
- `agent/session-start(agent, source)` ——emit，在第 1 轮次之前触发一次，携带 `SessionStartSource`（`startup` 表示全新/fork 创建，`resume` 表示重新加载的持久化会话；`clear`/`compact` 保留）。纯通知，不能阻塞启动（这是有意的空白：桥接可以记录/注入，但不管控启动）。监听器通过 `agent.inject()` 注入上下文。
|
||||
- `agent/prompt-submit(agent, content, source, signal, next) → PromptDecision` ——waterfall，在轮次唯一取得所有权的排队消息追加为 `user/message` 之前触发。显式轮次 signal 位于最后的 `next` 之前；`allow` 可以重写 prompt `content` 或附加来源各自独立的 `additionalContexts[]`，而 `block` 会追加一条持久的 `prompt/blocked`，并拒绝这个零步骤轮次。
|
||||
- `agent/prompt-submit(agent, content, source, signal, next) → PromptDecision` ——waterfall，在轮次唯一取得所有权的排队消息追加为 `user/message` 之前触发。显式轮次 signal 位于最后的 `next` 之前；`allow` 可以重写提示词 `content` 或附加来源各自独立的 `additionalContexts[]`，而 `block` 会追加一条持久的 `prompt/blocked`，并拒绝这个零步骤轮次。
|
||||
|
||||
**`agent/turn-continuation`** 接收并返回一个 `ContinuationDecision`。`{action:'continue', reason?}` 可携带面向模型的内容和来源，记录为同一轮次内的下一步 steering（中途引导）——与 `/goal` step-end-steer 模式互为类型化孪生。它不是 `context/message`，因此其类型不提供持久上下文元数据。
|
||||
|
||||
@@ -28,22 +28,22 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
|
||||
- **`ctx.tools.guard()`** 在整个 pre-execute waterfall 之后安装同步的、作用域感知的策略。guard 可以拒绝或弃权，永远不能强制允许，因此监听器顺序无法复活一个被最终不变式禁止的操作。
|
||||
- **`tools/execute`** 是用于超时、重试和指标插件的环绕调度 waterfall。包装层通过 `next()` 委托给核心调度，在此之前可以替换并恢复必需的 `exec.signal`，但不能移除它；包装层接收抛出异常或未知工具产生的、已完成规范化的规范成功／失败结果。包装层自行产生的成功结果会短路调度，并通过已解析的输出声明重新规范化。
|
||||
- **`tools/post-execute`** 是检查/变换 waterfall。其 `PostToolDecision` 接受、以反馈阻止、替换呈现内容或规范值，或附加 `additionalContexts`。替换值会重新校验并重新计算呈现；替换内容会保留程序化值，且不构成保密边界。返回的 decision 是受支持的变换通道。
|
||||
- **`ToolDefinition.finalizeContent`** 是一个可选、同步、完备且仅能处理内容的边界，在调用创建时随可见定义一起被快照。注册表将候选结果规范化并创建无损快照后，它恰好运行一次；候选结果包括绕过后续 waterfall 的 pre、around 或 post 监听器失败，以及为另一个结果字段创建快照时发现的错误。它可以替换 `content`，也可返回 `undefined` 保留原内容，但不能重写 `isError`、结构化错误身份、上下文或呈现元数据。工具在此执行自身最后一道内容不变式，而无需将策略失败转换为更弱的 block decision。
|
||||
- **`ToolDefinition.finalizeContent`** 是一个可选、同步、完备且仅能处理内容的边界，在调用创建时随可见定义一起被快照。注册表将候选结果规范化并创建无损快照后，它恰好运行一次；候选结果包括绕过后续 waterfall 的 pre、around 或 post 监听器失败，以及为另一个结果字段创建快照时发现的错误。它可以替换 `content`，也可返回 `undefined` 保留原内容，但不能重写 `isError`、结构化错误身份、上下文或呈现元数据。工具在此执行自身最后一道内容不变式，而无需将策略失败转换为更弱的阻止 decision。
|
||||
- **`tools/result`** 是在所有变换、无损 JSON 实体化和外层错误边界之后的同步封闭通知。它接收相同的冻结执行身份和权威结果的不可变快照；观测者的失败按监听器隔离，无法改变或拒绝 `ToolRegistry.execute()` 返回的结果。
|
||||
|
||||
核心调度与工具体位于规范化边界内部，因此工具、监听器、无效规范值、渲染器／投影器、非 JSON 呈现和身份形状错误均解析为 JSON 安全的 `isError` 结果，而非逃逸出轮次。post-execute 监听器因此可以检查一个抛出异常的工具；由定义拥有的最终内容不变式也会覆盖外层流水线与候选结果实体化失败；最终观测者会同时看到执行期间的规范值，以及会话日志能够持久化的确切呈现字段。[规范工具输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)定义值／投影与持久性规则。
|
||||
|
||||
**`TurnEndReason.rejected`**（`dsh-session`）：取得所有权的 prompt 被 `prompt-submit` 阻止的零步骤轮次。
|
||||
**`TurnEndReason.rejected`**（`dsh-session`）：取得所有权的提示词被 `prompt-submit` 阻止的零步骤轮次。
|
||||
|
||||
### 三个承重的循环决策
|
||||
|
||||
1. **在 prompt 策略之前开启轮次。** 被阻止的 prompt 成为零步骤的 `rejected` 轮次，保持封闭性并为 ACP（Agent Client Protocol）提供持久的终结事件。否决记录 `prompt/blocked`（含原始 prompt 和原因），而每个允许的 `additionalContexts` 条目都注入到已开启的轮次中。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个取得所有权的 ordinary-send 条目都是其轮次中的唯一消息；启动前丢弃不会创建轮次。
|
||||
1. **在提示词策略之前开启轮次。** 被阻止的提示词成为零步骤的 `rejected` 轮次，保持封闭性并为 ACP（Agent Client Protocol）提供持久的终结事件。否决记录 `prompt/blocked`（含原始提示词和原因），而每个允许的 `additionalContexts` 条目都注入到已开启的轮次中。依照[一次 send 对应一个轮次的简化](../simplification/2026-07-17-one-send-one-turn.md)，每个取得所有权的 ordinary-send 条目都是其轮次中的唯一消息；启动前丢弃不会创建轮次。
|
||||
|
||||
2. **Post-tool `additionalContexts` 与异步注入进入活跃批次 FIFO，并在该批次结算时追加。** `content`/`feedback` 塑造 `execute()` 返回的结果，但每项上下文都是独立的 `context/message`，而单个步骤或组合工具可以产生许多上下文。立即追加上下文会产生 `result(c1) → context → result(c2)` 的交错，或把嵌套上下文放在外层结果之前，破坏工具调用/结果邻接性。因此 `ToolRunContext.deferContext()` 会在失败路径上也收集嵌套调度上下文，`execute()` 在 `ToolExecutionResult` 上暴露有序数组，循环再把它接纳到与执行期间 `agent.inject()` 调用相同的 FIFO 中。FIFO 在批次结算时，于每个已记录结果之后追加，其中也包括被中断轮次关闭之前。被接受的外层调用将 deferred contexts 保留在 decision contexts 之前；被外层阻止时则丢弃 deferred contexts，只暴露阻止 decision 显式提供的上下文。
|
||||
2. **工具执行后的 `additionalContexts` 与异步注入进入活跃批次 FIFO，并在该批次结算时追加。** `content`/`feedback` 塑造 `execute()` 返回的结果，但每项上下文都是独立的 `context/message`，而单个步骤或组合工具可以产生许多上下文。立即追加上下文会产生 `result(c1) → context → result(c2)` 的交错，或把嵌套上下文放在外层结果之前，破坏工具调用/结果邻接性。因此 `ToolRunContext.deferContext()` 会在失败路径上也收集嵌套调度上下文，`execute()` 在 `ToolExecutionResult` 上暴露有序数组，循环再把它接纳到与执行期间 `agent.inject()` 调用相同的 FIFO 中。FIFO 在批次结算时，于每个已记录结果之后追加，其中也包括被中断轮次关闭之前。被接受的外层调用将 deferred contexts 保留在 decision contexts 之前；被外层阻止时则丢弃 deferred contexts，只暴露阻止 decision 显式提供的上下文。
|
||||
|
||||
3. **强制 `continue` 的 `reason` 通过 steering 通道入队**，使得下一步骤在循环顶部排空时将其记录为当前轮次的 steering——同一轮次内的下一*步骤* steering，而非下一*轮次*的 prompt（与现有的 `hasSteering` 强制继续覆盖一致）。
|
||||
3. **强制 `continue` 的 `reason` 通过 steering 通道入队**，使得下一步骤在循环顶部排空时将其记录为当前轮次的 steering——同一轮次内的下一*步骤* steering，而非下一*轮次*的提示词（与现有的 `hasSteering` 强制继续覆盖一致）。
|
||||
|
||||
### Pre-tool 输入重写是一个独立的一致性决策
|
||||
### 工具执行前输入重写是一个独立的一致性决策
|
||||
|
||||
`PreToolDecision` 不能重写参数。历史和审计调用在执行前记录，ACP 展示读取相同的输入，因此注册表在策略之前封存参数。有效的重写必须在身份创建之前同时更新历史、审计、展示和执行；该契约属于[输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)。
|
||||
|
||||
@@ -53,9 +53,9 @@ seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）；
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **将 pre-tool 输入重写作为本 seam 集的一部分发布**：推迟，视为越界信号；上文已阐述一致性问题（审计、历史和展示都读取执行前记录的 `tool/call.arguments`），[pre-tool 输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)负责该设计。
|
||||
- **将工具执行前输入重写作为本 seam 集的一部分发布**：推迟，视为越界信号；上文已阐述一致性问题（审计、历史和展示都读取执行前记录的 `tool/call.arguments`），[工具执行前输入重写提案](../../proposed/feature/2026-06-30-pre-tool-input-rewrite.md)负责该设计。
|
||||
- **将持久的 `hook/*` SessionEvents 与 seam 一起声明**：否决。原生插件使用类型化 Decision 而完全不需要钩子日志（实际示例已证明），因此持久日志属于[钩子协议库](2026-06-30-hook-protocol-lib.md)，而非 seam 表面。
|
||||
|
||||
## 后果
|
||||
|
||||
规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、prompt-submit、post-tool 上下文缓冲和 continuation；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各 package README、[核心拦截 decision](../../../../docs/core-data-structures/core.md#interception-decisions) 与[工具结构](../../../../docs/core-data-structures/tools.md)中。ACP 桥接将 `rejected` 轮次映射为其 `cancelled` 编解码值，而钩子驱动的快照端到端验证可观测的桥接行为。
|
||||
规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、prompt-submit、工具执行后上下文缓冲和 continuation；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/core-data-structures/core.md#interception-decisions) 与[工具结构](../../../../docs/core-data-structures/tools.md)中。ACP 桥接将 `rejected` 轮次映射为其 `cancelled` 编解码值，而钩子驱动的快照端到端验证可观测的桥接行为。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: d21a2a233d60bd788b79eb39f0f358b8e5b90cae
|
||||
2026-06-30-session-store-fork-api.zh.md: d17daa464ad59c6b5ac4d5041b4af30c44321fa7
|
||||
|
||||
@@ -8,11 +8,11 @@ Status: implemented
|
||||
|
||||
事件溯源的会话日志已经具备 fork 所需的原语：创建一个带有种子事件前缀的新会话，然后像回放一样从该种子日志推导模型历史。这个原语有意保持底层：`ctx.sessions.create(id, { seed, meta })` 接受任何合法种子，但常规的活跃会话分支需要围绕以下问题制定策略：哪些前缀可以被复制、子会话应打上哪些元数据、以及错误如何分类。
|
||||
|
||||
语义上的风险在于 fork 边界。一个合法的用户可见 fork 种子必须是连续的且封闭在轮次内。如果在一个活跃轮次内部 fork，会复制一个未关闭的 `turn/start`、可能还有一个未关闭的 `step/start`，以及可能悬空的工具调用。这违反了轮次封闭性与 provider-transcript 不变式，并且会创建一段误导性的子历史——看起来子会话参与了父会话中一个尚未完成的轮次。现有的 [subagent seam](2026-06-21-subagent-capability-seam.md) 有意解决的是另一个问题：工具触发的 subagent fork 通常发生在父轮次仍然打开时，因此 `dsh-subagent-fork` 会将种子裁剪到父会话最后一个已完成轮次的前缀。通用的会话 fork 不应静默裁剪；它应当要么在请求的边界处 fork，要么拒绝请求。
|
||||
语义上的风险在于 fork 边界。一个合法的用户可见 fork 种子必须是连续的且封闭在轮次内。如果在一个活跃轮次内部 fork，会复制一个未关闭的 `turn/start`、可能还有一个未关闭的 `step/start`，以及可能悬空的工具调用。这违反了轮次封闭性与提供方 transcript 不变式，并且会创建一段误导性的子历史——看起来子会话参与了父会话中一个尚未完成的轮次。现有的 [subagent seam](2026-06-21-subagent-capability-seam.md) 有意解决的是另一个问题：工具触发的 subagent fork 通常发生在父轮次仍然打开时，因此 `dsh-subagent-fork` 会将种子裁剪到父会话最后一个已完成轮次的前缀。通用的会话 fork 不应静默裁剪；它应当要么在请求的边界处 fork，要么拒绝请求。
|
||||
|
||||
## 决策
|
||||
|
||||
`dsh-session` 直接在 `ctx.sessions` 上拥有常规活跃会话 fork 的能力。不设独立的 `dsh-session-fork` 包（package），也不设 `ctx.sessionFork` 服务：该 API 没有独立的后端、事件词汇、生命周期或持久化行为，所有持久化工作都委托给现有的 session store 和持久化后端。
|
||||
`dsh-session` 直接在 `ctx.sessions` 上拥有常规活跃会话 fork 的能力。不设独立的 `dsh-session-fork` 包（package），也不设 `ctx.sessionFork` 服务：该 API 没有独立的后端、事件词汇、生命周期或持久化行为，所有持久化工作都委托给现有的会话存储和持久化后端。
|
||||
|
||||
store 暴露一个操作：
|
||||
|
||||
@@ -30,7 +30,7 @@ class SessionStore extends Service {
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**独立的 `ctx.sessionFork` 服务。** 这是最初的实现，但评审表明它过度套用了 capability-seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在 session store 原语之上执行一层策略而去发现并安装第二个服务。
|
||||
**独立的 `ctx.sessionFork` 服务。** 这是最初的实现，但评审表明它过度套用了 capability-seam 模式。代码没有可替换的后端、没有额外的事件面、没有独立的所有权生命周期，也没有超出 `ctx.sessions.create({ seed, meta })` 的持久化行为。保留独立包会迫使调用方为了在会话存储原语之上执行一层策略而去发现并安装第二个服务。
|
||||
|
||||
**两个函数：`snapshot()` 加 `fork()`。** 这保留了一个可复用的种子/元数据计算，但唯一支持的消费方会立即创建会话。它还使接口看起来比用户实际需要的具体操作更抽象。单一的 `fork()` 加显式 `boundary` 使 API 保持直接，同时仍支持对先前时间点的 fork。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-30-subagent-observe-enrich.md: a07cef95630689d1ca8cacd3eb7c50e691cb304a
|
||||
2026-06-30-subagent-observe-enrich.zh.md: f433c3cbd451e982cfe96457794895120f9bc200
|
||||
2026-06-30-subagent-observe-enrich.zh.md: 4ffa18ccc1cc45283038cb6fb861f5ed09ba090b
|
||||
|
||||
@@ -14,17 +14,17 @@ Status: implemented
|
||||
|
||||
**在 `SubagentRunEndInfo` 中添加 `lastAssistantMessage`——子 agent 的最终输出。** 在正常结束路径上，它是只读的类型化 `SubagentResult.output`，观察者无需持有 run 即可看到子 agent 产出了什么。在基础设施拒绝（不存在 `SubagentResult`）的情况下，该字段缺失，事件报告 `stopReason: 'error'`。提供方与监听方是受信任的同进程协作者，遵守借用不可变载荷的契约。
|
||||
|
||||
两个事件仍为普通 **`emit`**。异步的 `SubagentService.start()` 将结果观察附加到就绪的 provider run 上，发出 `subagent/start`，然后返回该 run；进程内监听方因此可以通过 `ctx.agents.get(info.id)` 访问已发布的子 agent，而远程 provider 无需在本地注册表中有对应条目。provider 启动被拒绝时不发出任何事件。回调保持仅观察，且逐监听方隔离确保一个异常订阅者不会阻塞活跃 run 或饿死后续监听方。
|
||||
两个事件仍为普通 **`emit`**。异步的 `SubagentService.start()` 将结果观察附加到就绪的提供方 run 上，发出 `subagent/start`，然后返回该 run；进程内监听方因此可以通过 `ctx.agents.get(info.id)` 访问已发布的子 agent，而远程提供方无需在本地注册表中有对应条目。提供方启动被拒绝时不发出任何事件。回调保持仅观察，且逐监听方隔离确保一个异常订阅者不会阻塞活跃 run 或饿死后续监听方。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**`agentType` subagent 类别标签**（CC 的 `subagent_type` 在 harness 中的对应物），放在请求与两个生命周期载荷上。早期草案曾包含它；评审中移除，因为它是 Claude Code 的概念，不适合我们自己的 seam（此处没有任何逻辑解释它，唯一消费方是 CC 方言桥接层）。CC 桥接层改为直接为其 SubagentStart/Stop 的 `agent_type` matcher 填入 Claude Code 自身的默认值 `"general-purpose"`，因此本 Agent Note 只交付**一项**丰富化：`lastAssistantMessage`。
|
||||
**`agentType` subagent 类别标签**（CC 的 `subagent_type` 在 harness 中的对应物），放在请求与两个生命周期载荷上。早期草案曾包含它；评审中移除，因为它是 Claude Code 的概念，不适合我们自己的 seam（此处没有任何逻辑解释它，唯一消费方是 CC 方言桥接层）。CC 桥接层改为直接为其 SubagentStart/Stop 的 `agent_type` matcher 填入 Claude Code 自身的默认值 `"general-purpose"`，因此本 Agent Note 只交付一项丰富化：`lastAssistantMessage`。
|
||||
|
||||
**控制流式 `subagent/end`**：推迟；见下文。
|
||||
|
||||
## 为何仅观察，以及推迟了什么
|
||||
|
||||
控制流式 `subagent/end`（一个被 await 的 waterfall，返回停止/继续决策，与其他拦截 seam 一致）需要：将 `subagent/end` 从 emit 改为 waterfall、重构 `SubagentService.start` 使其在结算前 await 监听方、在进程内 provider 中实现 `resume` 能力以便「继续」能真正重新运行子 agent。这属于[能力 seam Agent Note](2026-06-21-subagent-capability-seam.md) 已推迟的后台/steering（中途引导）subagent 重设计（同一个重设计还将统一 subagent 与 bash 之间的长时间运行工具处理）。本 Agent Note 交付钩子桥接层当前所需的仅观察丰富化；`FIXME(subagent-continuation)` / `TODO` 锚点标记了控制流版本在重设计发生时的落点。
|
||||
控制流式 `subagent/end`（一个被 await 的 waterfall，返回停止/继续决策，与其他拦截 seam 一致）需要：将 `subagent/end` 从 emit 改为 waterfall、重构 `SubagentService.start` 使其在结算前 await 监听方、在进程内提供方中实现 `resume` 能力以便「继续」能真正重新运行子 agent。这属于[能力 seam Agent Note](2026-06-21-subagent-capability-seam.md) 已推迟的后台/steering（中途引导）subagent 重设计（同一个重设计还将统一 subagent 与 bash 之间的长时间运行工具处理）。本 Agent Note 交付钩子桥接层当前所需的仅观察丰富化；`FIXME(subagent-continuation)` / `TODO` 锚点标记了控制流版本在重设计发生时的落点。
|
||||
|
||||
## 后果
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 2405e6e6746569e9327f9eb5ecbb8b37e5ef1bee
|
||||
2026-07-05-dynamic-workflows.zh.md: 9ac94d491e14915841d55b6f6f7ad631a61a98f3
|
||||
|
||||
@@ -14,7 +14,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
|
||||
|
||||
### 脚本契约（兼容 Claude Code）
|
||||
|
||||
一次工作流调用包含 JSON `meta`（`name`、`description`，以及可选的 `whenToUse`/`phases`）和一段支持顶层 `await` 并返回 JSON 值的 JavaScript `script` 正文。元数据作为数据校验，从不被执行。正文接收 `agent(prompt, options)`、`parallel(thunks)`、`pipeline(items, ...stages)`、`phase(title)`、`log(message)` 和 `args`。pipeline 各阶段接收 `(prev, item, index)`，阶段之间无屏障；失败的子 agent 和普通阶段错误将受影响的 item 解析为 `null` 并跳过其剩余阶段。Claude Code 的确定性限制通过日志化延迟处理，因此兼容的脚本正文在将 meta 头移入参数后可以使用时钟和随机数。
|
||||
一次工作流调用包含 JSON `meta`（`name`、`description`，以及可选的 `whenToUse`/`phases`）和一段支持顶层 `await` 并返回 JSON 值的 JavaScript `script` 正文。元数据作为数据校验，从不被执行。正文接收 `agent(prompt, options)`、`parallel(thunks)`、`pipeline(items, ...stages)`、`phase(title)`、`log(message)` 和 `args`。流水线各阶段接收 `(prev, item, index)`，阶段之间无屏障；失败的子 agent 和普通阶段错误将受影响的 item 解析为 `null` 并跳过其剩余阶段。Claude Code 的确定性限制通过日志化延迟处理，因此兼容的脚本正文在将 meta 头移入参数后可以使用时钟和随机数。
|
||||
|
||||
与 CC 有一处刻意的严格性差异：钩子误用——未知或延迟的选项（`effort`/`isolation`/`agentType`）、格式错误的参数、超出支持子集的 schema、触发上限、seam 启动失败——会抛出带 `fatal: true` 的 `WorkflowError`，组合器会重新抛出 fatal 错误而非将 item 置为 null。如果不这样做，一个拼错的选项会悄然变成一个与子 agent 失败无法区分的 `null`——这正是本仓库禁止的「被接受后被忽略」的失败模式。另有一处新增：工具的 `args` 参数是一个 JSON 对象（裸列表被包装为一个字段），使协议格式（wire format）保持诚实。
|
||||
|
||||
@@ -26,7 +26,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
|
||||
|
||||
**信任前提**：工作流脚本与模型的 bash 访问具有相同的信任级别。引擎容纳有缺陷的脚本，并保证结果已 settled、值为 JSON 安全、取消后静默；它不防御恶意代码。vm 上下文和 worker 线程不是安全边界：脚本可以逃逸到具有进程级权限的 Node API。沙箱化需要在此 seam 背后使用独立进程或 isolated-vm 引擎。
|
||||
|
||||
**为何选择 `node:worker_threads`**：每次运行获得一个非池化的 worker。vm 上下文限制了文档化的脚本表面，而 message-port RPC 将 `agent()` 桥接到宿主侧的子循环。worker 防止脚本的同步工作阻塞宿主，提供序列化边界，并允许取消后强制终止。`isolated-vm` 因其维护状态和部署要求被否决。
|
||||
**为何选择 `node:worker_threads`**：每次运行获得一个非池化的 worker。vm 上下文限制了文档化的脚本表面，而消息端口 RPC 将 `agent()` 桥接到宿主侧的子循环。worker 防止脚本的同步工作阻塞宿主，提供序列化边界，并允许取消后强制终止。`isolated-vm` 因其维护状态和部署要求被否决。
|
||||
|
||||
宿主在发布前校验元数据并解析正文。私有枚举键 payload 映射定义协议格式；待启动记录、已发布子记录、单一取消信号、worker 死亡回收、结果优先级与 dispose 静默，在此协议上保持 subagent run 契约。这些竞态算法归[agent 作用域运行时设计 Agent Note](../architecture/2026-07-12-agent-scope-runtime-design.md#workflow-children-are-pending-starts-or-published-records)所有。
|
||||
|
||||
@@ -38,7 +38,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`）
|
||||
|
||||
### 消费方（dsh-tool-workflow）
|
||||
|
||||
一个 `workflow` 工具，镜像 `dsh-tool-subagent` 的同步形态：启动、await、`try/finally` dispose、abort 桥接 `exec.signal`、非 `completed` → `isError`。渲染意图：一张以调用的 `meta.name` 参数为标题的 `generic` 卡片（展示是参数的纯函数）。工具描述即面向模型的编写规范。使用策略以工具自身的 `tool:<toolName>` prompt 段落随工具发布（显式请求才使用的引导——工具引导存在于工具插件中，从不在部署 persona 中）；harness 没有 ultracode 风格的 effort 门控。
|
||||
一个 `workflow` 工具，镜像 `dsh-tool-subagent` 的同步形态：启动、await、`try/finally` dispose、abort 桥接 `exec.signal`、非 `completed` → `isError`。渲染意图：一张以调用的 `meta.name` 参数为标题的 `generic` 卡片（展示是参数的纯函数）。工具描述即面向模型的编写规范。使用策略以工具自身的 `tool:<toolName>` 提示词段落随工具发布（显式请求才使用的引导——工具引导存在于工具插件中，从不在部署 persona 中）；harness 没有 ultracode 风格的 effort 门控。
|
||||
|
||||
### 基础：subagent seam 上的结构化输出
|
||||
|
||||
@@ -56,7 +56,7 @@ worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够
|
||||
|
||||
- **后台收集**（启动工具 → run id → 完成通知 → 收集），与 bash/subagent 后台统一一起设计。
|
||||
- **日志化 + 恢复**（`resumeFromRunId`、缓存的 agent() 前缀）：实现它会以脚本契约收紧的形式重新引入 CC 的确定性禁令（脚本目前可以读取时钟）。
|
||||
- **保存/打包的工作流**（`.deepseek/workflows/` 注册表、斜杠命令界面）和**脚本持久化到运行目录**（tool-call 事件已经持久记录了脚本）。
|
||||
- **保存/打包的工作流**（`.deepseek/workflows/` 注册表、斜杠命令界面）和**脚本持久化到运行目录**（工具调用事件已经持久记录了脚本）。
|
||||
- **嵌套 `workflow()`**、**token `budget`**，以及 `effort`/`isolation`/`agentType` agent 选项（每个都以命名延迟的消息大声拒绝）。
|
||||
- **整体运行的挂钟超时**：取消总能释放调用方（result 在宽限期内 settle），因此总运行时间上限是后台重设计的策略旋钮，不是此处的正确性需求。
|
||||
- **超越 worker 线程的引擎加固**：在同一 seam 背后使用 isolated-vm 或独立进程引擎（真正的沙箱化；内存限制）。
|
||||
@@ -67,7 +67,7 @@ worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够
|
||||
|
||||
- **宿主侧的恶意值防护**（无 trap 代理拒绝、从不调用访问器的描述符遍历、realm 侧预渲染抛出值、realm 构建的 promise/array/error 克隆加结构化 fatal 识别）：否决。每项防御针对的都是信任前提所接受的作者，而线程的序列化边界已经从构造上使跨 realm 值全量化。
|
||||
- **进程内 `node:vm` 执行**：机械上最简——无 RPC、无线程——但 `start()` 会在脚本的初始同步切片期间阻塞调用方，第一个 await 之后的同步自旋无法在进程内终止（vm `timeout` 仅覆盖第一个切片），且 `dispose()` 只能在宿主循环上放弃一个未 settle 的脚本。worker 线程引擎保持相同的 vm 上下文脚本表面，同时解除宿主阻塞并使终止成为现实。
|
||||
- **后台执行作为默认**（CC 的形态）：延迟。前台同步与 `dsh-tool-subagent` 的当前形态一致，后台语义应在 bash/subagent/workflow 之间统一设计一次，而非逐工具设计。
|
||||
- **后台执行作为默认**（CC 的形态）：延迟。前台同步与 `dsh-tool-subagent` 的当前形态一致，后台语义应在 bash、subagent 和工作流之间统一设计一次，而非逐工具设计。
|
||||
- **工作流层为 `agent({schema})` 做 JSON 解析**：在一个消费方重复 seam 关注点，而 seam 的能力标志仍不诚实地为 `false`。
|
||||
- **Meta 嵌入脚本中作为 `export const meta = {...}`**（CC 的确切格式）：保持脚本自包含且 CC 脚本可直接使用，但获取 meta 需要在宿主上执行模型编写的文本。即使一个空的限时 vm 上下文也无法约束脚本控制的 getter（当宿主读取结果对象时）。JSON 参数消除了扫描器、执行和宿主自旋漏洞；代价是 CC 脚本的 meta 头必须移入参数（正文保持可直接使用）。
|
||||
- **`ValueSchemaSpec` 作为 `outputSchema` 协议类型**：面向作者的形式如今具有等价词汇，但工作流提供的是来自其他 realm 的原始 JSON Schema 数据；将这类运行时数据假装成可信的作者声明，会跳过原始 schema 断言边界。
|
||||
@@ -77,4 +77,4 @@ worker 侧逻辑通过进程内 `MessageChannel` 运行，使 V8 覆盖率能够
|
||||
|
||||
## 后果
|
||||
|
||||
扇出计划现在存在于可重运行的脚本中，`outputSchema` 提供权威的结构化子 agent 结果。每次运行付出 worker 启动和 message-port RPC 成本，但宿主启动保持非阻塞，取消可以终止 worker，序列化强制执行值边界。worker 线程不是安全边界。无效选项快速失败而非退化为 Claude Code 的 `null`；消费方通过 run handle 保持控制权，观察者仅接收快照。
|
||||
扇出计划现在存在于可重运行的脚本中，`outputSchema` 提供权威的结构化子 agent 结果。每次运行付出 worker 启动和消息端口 RPC 成本，但宿主启动保持非阻塞，取消可以终止 worker，序列化强制执行值边界。worker 线程不是安全边界。无效选项快速失败而非退化为 Claude Code 的 `null`；消费方通过 run handle 保持控制权，观察者仅接收快照。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-06-explicit-tool-order.md: bd6d0a04aa470ca33e618957ae1f08c1ef15fcfe
|
||||
2026-07-06-explicit-tool-order.zh.md: b5600b54537319763e2bf7d54748f5c637461cbd
|
||||
2026-07-06-explicit-tool-order.zh.md: 5cdecc0e59ff00b6dce7134819f8230072d084cb
|
||||
|
||||
@@ -30,7 +30,7 @@ Status: implemented
|
||||
- **注册顺序（现状）**：并发导入竞态，依赖宿主环境（上述 CI 抖动），评审中不可见。
|
||||
- **插件依赖图的线性化**：该关系是偏序的，独立的工具插件不可比较；抖动发生时偏序已完全满足。
|
||||
- **每个插件在其工具贡献上标注 `weight`**：将顺序分散到各插件中，仍需一个无人拥有的全局编号约定（section 的 `order` 分段已经展示了这种协调成本需要手工承担）。
|
||||
- **在 `ToolRegistry.schemas()` 中排序（注册表层）**：同样确定，但注册表是一个成员存储，被组装之外的多方消费；排序是 prompt 组合的关注点，而组装逻辑已经拥有 section 的组合策略。
|
||||
- **在 `ToolRegistry.schemas()` 中排序（注册表层）**：同样确定，但注册表是一个成员存储，被组装之外的多方消费；排序是提示词组合的关注点，而组装逻辑已经拥有 section 的组合策略。
|
||||
- **在 `LlmService` 上加配置 + `orderTools()` 方法，由 loop 在记录 header 前调用**：可行，但仅为在远处应用一个策略就增加了一个公开服务方法和一处 loop 改动；每个未来的请求组合者都必须记得调用。在列表诞生处进行规范化使得无序列表不可表示，且零新增接口。
|
||||
- **在 `llm.stream()` 内部规范化**：在 header 事件已记录之后才运行（抖动仍然存在），且需要重建深度冻结的信封，静默地解除了重建不变式。
|
||||
- **穷举列表（无 rest 条目）**：每个新加载的工具插件都会导致启动失败；强制的 rest 条目使未列出的工具保持确定性，且其位置是显式的。
|
||||
@@ -43,8 +43,8 @@ Status: implemented
|
||||
- 快照套件中唯一固定请求头的 fixture（`text-turn`）携带新的权威工具顺序；按照固定请求头设计，其他 ACP 快照仍将大块 header 清洗为 `{{system}}`/`{{tools}}`。
|
||||
- 步骤之间的纯工具重排与其他 header 变更一样记录：一份原因是 `'change'` 的完整 `request/header` 快照。稳定的权威顺序会防止注册时序在普通路径上制造这类变化。
|
||||
- `toolOrder` 键沿 app → `agent-core` → `SystemPrompt` 的转发链传递，因此部署时将其放在 app 配置中 `persona` 旁边即可；`dsh-llm` 和 agent loop 无需改动。
|
||||
- `toolOrder` 中拼错或未加载的工具名称在 prompt 组装时使轮次失败，而非启动时：loop 在轮次内部组装（`turn/start` 之后、`step/start` 之前），因此拒绝到达轮次的外层 catch——轮次以 `error` 原因平衡关闭并携带错误消息，`agent/error` 镜像该消息，不打开步骤，不记录 `request/header`，不向适配器发出请求，agent 回到空闲状态。每个轮次都以相同方式失败，直到配置被修正；进程本身保持运行（符合仓库规则：显式配置引用不得被静默忽略——执行点是组装，因为不存在更早的通用时刻）。
|
||||
- 工具提供方返回保留的 rest 条目名称时，其 prompt 组装失败形态与未知的已列名称相同。这防止哨兵值变成一个歧义的真实工具，并保持「从不丢弃工具」的排序契约。
|
||||
- `toolOrder` 中拼错或未加载的工具名称在提示词组装时使轮次失败，而非启动时：loop 在轮次内部组装（`turn/start` 之后、`step/start` 之前），因此拒绝到达轮次的外层 catch——轮次以 `error` 原因平衡关闭并携带错误消息，`agent/error` 镜像该消息，不打开步骤，不记录 `request/header`，不向适配器发出请求，agent 回到空闲状态。每个轮次都以相同方式失败，直到配置被修正；进程本身保持运行（符合仓库规则：显式配置引用不得被静默忽略——执行点是组装，因为不存在更早的通用时刻）。
|
||||
- 工具提供方返回保留的 rest 条目名称时，其提示词组装失败形态与未知的已列名称相同。这防止哨兵值变成一个歧义的真实工具，并保持「从不丢弃工具」的排序契约。
|
||||
|
||||
## 测试
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 9e0c1615d02fed89ef0cda2a111e36385ad00497
|
||||
2026-07-06-sandbox.zh.md: b25c84a3467db26776007bb4888391ba69ada3cd
|
||||
|
||||
@@ -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` 通过 permission 服务验证并切换，然后返回完整的刷新状态（规范契约）。
|
||||
**编辑器界面**是协议原生的[会话配置选项](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` 通过权限服务验证并切换，然后返回完整的刷新状态（规范契约）。
|
||||
|
||||
**轮次封闭是提交边界。** 开放轮次中的切换立即追加。空闲切换保持在 bridge 记录上待定，在下一次 prompt 提交时、assembly 或执行之前追加到开放轮次中；每个旋钮以最后写入为准。开放性来自日志边界而非 `agent.status`，setter 不从 `session/event` 监听器内追加，因为那会重排后续观察者。锚定之前，响应叠加待定值。崩溃丢弃它，重新加载返回持久 fold。
|
||||
**轮次封闭是提交边界。** 开放轮次中的切换立即追加。空闲切换保持在 bridge 记录上待定，在下一次提示词提交时、assembly 或执行之前追加到开放轮次中；每个旋钮以最后写入为准。开放性来自日志边界而非 `agent.status`，setter 不从 `session/event` 监听器内追加，因为那会重排后续观察者。锚定之前，响应叠加待定值。崩溃丢弃它，重新加载返回持久 fold。
|
||||
|
||||
#### 进程内工具
|
||||
|
||||
@@ -117,10 +117,10 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
|
||||
|
||||
### 测试
|
||||
|
||||
- **单元测试：** 固定平台选择和 profile、失败关闭的 runner 分类、按调用的模式/根目录解析、按进程事实、升级验证和结果、permission preset fold 和写入透传、叙述器合并、ACP 公布和验证、轮次封闭的配置写入。
|
||||
- **Keyless 真实 runner：** 在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；一个真实 Cordis 上下文通过已交付的 bash 和 fs 工具并发驱动两个项目会话，证明在自身根目录写入成功、在兄弟根目录写入被拒绝。Packed-install 覆盖率证明注册表 launcher 保持可执行。真实 ACP 组合固定 permission 切换并拒绝未知 preset。CI 拒绝静默全跳过。
|
||||
- **单元测试：** 固定平台选择和 profile、失败关闭的 runner 分类、按调用的模式/根目录解析、按进程事实、升级验证和结果、权限 preset fold 和写入透传、叙述器合并、ACP 公布和验证、轮次封闭的配置写入。
|
||||
- **Keyless 真实 runner：** 在提供方和 bash 消费方层面对 bwrap、Landlock 和 Seatbelt 执行真实文件系统效果测试；一个真实 Cordis 上下文通过已交付的 bash 和 fs 工具并发驱动两个项目会话，证明在自身根目录写入成功、在兄弟根目录写入被拒绝。Packed-install 覆盖率证明注册表 launcher 保持可执行。真实 ACP 组合固定权限切换并拒绝未知 preset。CI 拒绝静默全跳过。
|
||||
- **With-key：** 以只读模式启动真实 ACP 组合，让模型驱动的 bash 写入命中 runner 的拒绝标记，再通过已授权与被拒绝的 workspace-write 重试驱动 bridge 应答器和磁盘效果；不可用的凭证或 runner 自动跳过。
|
||||
- **快照：** 固定 permission config-option 协议格式（wire format）、preset 和旋钮事件、prompt delta 和通知、以及两个脚本化的 approval 分支。一个真实 ACP 示例场景把会话放在用户主目录下，同时让部署后备根目录指向 `/tmp`，然后固定一次成功的 workspace-write 变更；这能区分会话根目录解析与进程后备值，而不依赖 runner 特定的拒绝文本。其他快照以无约束启动，使无关 fixture（测试前置数据）保持平台无关；策略场景显式切换。
|
||||
- **快照：** 固定权限 config-option 协议格式（wire format）、preset 和旋钮事件、提示词 delta 和通知、以及两个脚本化的 approval 分支。一个真实 ACP 示例场景把会话放在用户主目录下，同时让部署后备根目录指向 `/tmp`，然后固定一次成功的 workspace-write 变更；这能区分会话根目录解析与进程后备值，而不依赖 runner 特定的拒绝文本。其他快照以无约束启动，使无关 fixture（测试前置数据）保持平台无关；策略场景显式切换。
|
||||
|
||||
## 延迟阶段
|
||||
|
||||
@@ -142,16 +142,16 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
|
||||
- **提供方上的配置固定模式**：否决。每进程一个模式；无法服务具有不同策略的并发消费方，也无法表达一次性放宽重试。
|
||||
- **一个接口同时覆盖容器/VM**：否决。`confine(argv)` 预设共享文件系统；环境隔离是作为一致组部署的能力兄弟后端。
|
||||
- **通用 ToolRuntime 包装任何工具**：否决。对进程内工具（闭包了 `ctx`）机械上不成立；声明式效果重写对 fs/web/todo 而言不合理。
|
||||
- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加 prompt 的 `callId`；添加它们会让传输 seam 了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
|
||||
- **在执行器内部（`dsh-bash-sandbox`）请求批准**：否决。没有可路由的 `agent`，没有可附加提示词的 `callId`；添加它们会让传输 seam 了解会话和 UI——工具层持有两者并拥有面向模型的词汇。
|
||||
- **同一工具调用内自动重试**：否决。日志无法重建的隐藏重入：一个 `tool/call` 会产生两次具有不同策略的执行——重试是一次新的带有自身参数和结果事实的已记录调用。
|
||||
- **无条件公布升级字段**：否决。在 `dsh-bash-local` 下它们是死杠杆——公布 harness 无法兑现的选项会制造注定失败的授权；能力门控仅需注册时一次读取。
|
||||
- **默认值相对的升级阶梯（仅公布比执行器注册时默认值更宽的模式）**：否决。按会话覆盖使默认值成为错误的基线——切换到比默认值更窄的会话恰恰失去它需要的杠杆，而在 `danger-full-access` 默认值下字段完全消失，同时一个被覆盖为 `read-only` 的会话仍处于约束中却没有升级路径。枚举固定封闭的目标词汇；严格放宽是针对会话有效模式的按调用执行检查。
|
||||
- **按会话动态工具 schema**：否决。schema 设计上是注册表全局的（一套 assembly 词汇、固定 header 快照契约），按会话重新注册只能买到执行时严格放宽检查已保证的东西，代价是按会话的 schema 表面和每次切换的 header 变动。
|
||||
- **将重试硬匹配到先前的拒绝**：否决。命令字符串同一性脆弱（引号、`workdir`、env 前缀、作为失败阶段重试的管道）——要么误拒诚实的重试，要么被轻易满足；真正的边界是人看到命令 + 理由。仅在 `allow_always` 授权存储需要机器可检查的范围时才重新考虑。
|
||||
- **通用 `env/state` facts map 加拥有者服务**：否决。approval 和 sandbox 独立组合，因此任何一方的状态都不应拖入第三个包；单键 fold 各自是一个 `findLast`，拥有者服务自然消解；没有跨旋钮的不变式，因此原子多键补丁无收益。
|
||||
- **通用 `env/state` facts map 加拥有者服务**：否决。approval 和沙箱独立组合，因此任何一方的状态都不应拖入第三个包；单键 fold 各自是一个 `findLast`，拥有者服务自然消解；没有跨旋钮的不变式，因此原子多键补丁无收益。
|
||||
- **通过 `agent/user-message` + 总线事件叙述**：否决。它预设了一个不存在的轮次入口 seam（真正的 seam 是 `agent/prompt-submit`），而步骤前检查点的位置使一个监听器能够同时服务合并的轮次入口通知和轮中即时性约束。
|
||||
- **提示词中常驻声明沙箱模式（+ 切换叙述器）**：先交付后移除，基于实际证据：当每个请求中都有 `Bash commands run under the "read-only" file sandbox.` 时，模型拒绝尝试被拒绝后可升级的工作（首次手动会话中十二个轮次有五个以零工具调用结束），将沙箱变成了软锁定。拒绝标记在需要时命名模式，升级字段承载恢复路径；批准旋钮保留其声明，因为自动拒绝在行为上与人的「不」无法区分。
|
||||
- **用专门的簿记事件追踪「上次告知」**：否决。`request/header` fold 已记录模型看到的确切 prompt；将封闭的候选句子解析回来替代了第二条簿记流——事件仅在它们本身即为存储时才需要。
|
||||
- **用专门的簿记事件追踪「上次告知」**：否决。`request/header` fold 已记录模型看到的确切提示词；将封闭的候选句子解析回来替代了第二条簿记流——事件仅在它们本身即为存储时才需要。
|
||||
- **ACP session modes 而非 config options**：否决。preset 已经是一个部署定义的 config-option 选择器，且 modes 计划在 ACP v2 中移除。
|
||||
|
||||
## 后果
|
||||
@@ -169,18 +169,18 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层
|
||||
|
||||
代价与已接受的限制：
|
||||
|
||||
- **单一包装的幻觉被有意放弃。**`tools/pre-execute` 包装加 prompt 约定无法解决沙箱批准——正确的设计需要结构化拒绝、原生 runner 探测、按调用策略承载和一致的跨工具族强制，本设计为此付出了代价。
|
||||
- **单一包装的幻觉被有意放弃。**`tools/pre-execute` 包装加提示词约定无法解决沙箱批准——正确的设计需要结构化拒绝、原生 runner 探测、按调用策略承载和一致的跨工具族强制，本设计为此付出了代价。
|
||||
- **`read-only` 通过后续设计成为跨工具族边界。** 本 Agent Note 最初只交付 bash 强制；[跨工具族 fs 沙箱 Agent Note](2026-07-14-cross-family-fs-sandbox.md) 通过沙箱化的 `ctx.fs` 提供方把同一模式词汇扩展到文件系统工具，并将 mode/root 配置和 `sandbox/mode` 覆盖迁移到 `ctx.sandboxPolicy`（§ 进程内工具）。
|
||||
- **Windows 没有后端。** 其链槽保留为空——失败关闭，绝不穿透；填充它是延迟阶段。
|
||||
- **Seatbelt 层级依赖 Apple 已弃用但仍交付的 `sandbox-exec` CLI。** 作为 darwin 的唯一候选，它无需探测即被选中，因此未来移除会在执行时作为 runner 失败分类浮现——重新抛出 `SANDBOX_UNAVAILABLE`，命令从未运行；失败关闭，绝不开放。
|
||||
- **Landlock 约束的完整度取决于运行内核的 ABI。** 报告为 `enforcement: 'partial'` 而非拒绝——这是有意的权衡，使备选在旧内核主机上仍可用。
|
||||
- **launcher 作为注册表依赖到达。** 通过其自身仓库的发布流水线（经审查的 C 源码、原生 CI 构建器、字节固定的发布演练）加上本仓库的版本固定获得信任——真实内核 e2e 测试腿是通过安装字节为行为背书的。
|
||||
- **模型可能过度请求。** 在没有拒绝依据的情况下升级，或在 `workspace-write` 足够时选择 `danger-full-access`：描述引导且枚举强制阶梯，但人的 prompt 是实际门控；`approval/asked` 原因使过度请求可审计，且 `prepend` 策略应答器可以自动拒绝部署永远不想要的模式。
|
||||
- **模型可能过度请求。** 在没有拒绝依据的情况下升级，或在 `workspace-write` 足够时选择 `danger-full-access`：描述引导且枚举强制阶梯，但人的提示词是实际门控；`approval/asked` 原因使过度请求可审计，且 `prepend` 策略应答器可以自动拒绝部署永远不想要的模式。
|
||||
- **公布的目标集是静态的，而有效模式是按会话的**（schema 是注册表全局的）——已处于最宽模式的会话仍被提供这些字段。构造上无害：执行时的严格放宽检查（而非枚举）是安全边界——非放宽请求以自身文本失败且不提示任何人。
|
||||
- **授权的升级不等于可工作的沙箱。** 不可用的后端即使对授权升级到约束模式也仍然失败关闭——在平台没有链或所有探测失败时于 `confine()` 阶段，在未探测的唯一 runner 拒绝时于执行阶段（归类为沙箱失败而非命令失败）——而授权的 `danger-full-access` 运行根本不触及提供方：此时授权（而非探测）是权威。
|
||||
- **空闲切换存在于 bridge 内存中，直到下一次 prompt 提交锚定它。** 该窗口内的崩溃将其回退（在 `session/load` 时报告），且永不再提交 prompt 的会话永不持久化它——已接受，loop 拥有的空闲提交轮次留作未来工作（如果持久性成为需求）。
|
||||
- **批准叙述器的重启基线解析 prompt 文本。** 封闭的候选句子由写入模块本身拥有，因此措辞变更是同一文件中写入器+解析器的协调编辑；header 早于该段落的会话静默采用当前策略而不发通知。
|
||||
- **批准段落仍是动态 prompt 表面**（`'never'` 切换会破坏该会话的提供方 prompt 前缀缓存）。已接受：策略切换罕见，且模型基于过时的 `'never'` 行动更糟。沙箱旋钮不再触及 prompt。
|
||||
- **空闲切换存在于 bridge 内存中，直到下一次提示词提交锚定它。** 该窗口内的崩溃将其回退（在 `session/load` 时报告），且永不再提交提示词的会话永不持久化它——已接受，loop 拥有的空闲提交轮次留作未来工作（如果持久性成为需求）。
|
||||
- **批准叙述器的重启基线解析提示词文本。** 封闭的候选句子由写入模块本身拥有，因此措辞变更是同一文件中写入器+解析器的协调编辑；header 早于该段落的会话静默采用当前策略而不发通知。
|
||||
- **批准段落仍是动态提示词表面**（`'never'` 切换会破坏该会话的提供方提示词前缀缓存）。已接受：策略切换罕见，且模型基于过时的 `'never'` 行动更糟。沙箱旋钮不再触及提示词。
|
||||
- **模型可能持有关于沙箱模式的过时信念**（没有任何东西宣布切换）。有意接受：下一次尝试的标记或成功会纠正它，而宣布的观察到的失败模式——预防性拒绝——比一次浪费的重试更糟。
|
||||
|
||||
## FAQ
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# 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: 470d43ec8b4b1553304949278c26a6d1c9b9cc58
|
||||
2026-07-07-mcp-client-plugin.zh.md: ca87abc0ba3c61ae62e321a11d2f026ba5a33d5c
|
||||
|
||||
@@ -167,7 +167,7 @@ MCP 仅保证工具名在[单个服务器内](https://modelcontextprotocol.io/sp
|
||||
|
||||
延后。ACP 桥接已将 harness 暴露为 agent 服务器。再加一层 MCP server 会以不同协议重复这一功能，而用户的首要需求是消费外部工具，而非暴露自身工具。
|
||||
|
||||
### 能力 seam 三包拆分（interface / impl / consumer）
|
||||
### 能力 seam 三包拆分（接口 / 实现 / 消费方）
|
||||
|
||||
否决。可预见范围内不会有替代的 MCP 客户端实现——MCP 只有一个协议、一个 SDK。约定是「不要预防性拆分」，直到出现第二种实现。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-07-session-prefix.md: 322413f541706244a8a9a9113c0b79693fe54ccd
|
||||
2026-07-07-session-prefix.zh.md: 33afa701baf748b177a09995ab4ea4939b50f101
|
||||
2026-07-07-session-prefix.zh.md: 710cfbd2656d132640d39b1d62374ef2d16be612
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
插件经常拥有一段会话级别稳定的开场内容，模型必须始终看到它：技能目录、AGENTS.md 摘要、工作区基线。在引入本 seam 之前，harness 为这类内容提供了两个归属位置，但两者都不合适。系统提示词是一个渲染后的单一字符串：消息形态的内容（user 角色的 `<system-reminder>` 信封、多消息引导序列）放不进去，而且提供方对会话消息和系统文本的权重处理不同。持久化历史（`agent.inject()`、会话启动时的 `context/message`）使开场内容变为永久：每个 `deriveMessages()` 消费方都会回放它，压缩（compaction）的保留遍历拥有它，fork 会将其以陈旧状态固化，resume 也无法刷新它——会话诞生时捕获的目录会比它所描述的世界活得更久。
|
||||
插件经常拥有一段会话级别稳定的开场内容，模型必须始终看到它：技能目录、AGENTS.md 摘要、工作区基线。在引入本 seam 之前，harness 为这类内容提供了两个归属位置，但两者都不合适。系统提示词是一个渲染后的单一字符串：消息形态的内容（user 角色的 `<system-reminder>` 信封、多消息引导序列）放不进去，而且提供方对会话消息和系统文本的权重处理不同。持久化历史（`agent.inject()`、会话启动时的 `context/message`）使开场内容变为永久：每个 `deriveMessages()` 消费方都会回放它，压缩（compaction）的保留遍历拥有它，fork 会将其以陈旧状态固化，恢复也无法刷新它——会话诞生时捕获的目录会比它所描述的世界活得更久。
|
||||
|
||||
显而易见的第三种选项——让插件在请求发出途中编辑 `messages`——被[可重建请求 Agent Note](../architecture/2026-07-05-reconstructable-requests.md)禁止：每个由循环构建的请求都是会话日志的纯函数，因此无论哪个通道承载开场内容，都必须精确记录它所发送的内容。缺失的是一个带有持久记录的仅请求消息通道。
|
||||
|
||||
@@ -17,8 +17,8 @@ Status: implemented
|
||||
三个属性承载了这一设计：
|
||||
|
||||
- **仅请求，记录在 header 中。** `deriveMessages()` 从不返回前缀；它唯一的持久记录是实例锚定的 `request/header` 快照上的 `EpochHeader.messagePrefix`——可重建请求 Agent Note 已为请求的非历史部分拥有的通道，因此不引入新的会话事件。配套的 [`dsh-agent-loop/invariant`](../../../../packages/core/agent-loop/src/invariant.ts)对每个循环构建的请求重新计算 `messagePrefix + boundary derivation`；启用该贡献时，未记录的前缀无法到达协议格式。
|
||||
- **按实例冻结。** 复用是结构性的，而非靠纪律保证：缓存的产物在会话中途不可变，因此提供方的 prompt 缓存从构造上成立，前缀以每步零边际成本扩展了可缓存区域。进程重启或 `ctx.agents.resume()` 产生新实例：它重新组合，任何漂移都可追溯地落在 `'resume'` header 快照上。这就是本 seam 创建的路由规则：会话冻结的开场内容走前缀；会话中途变化的内容走仅追加历史通道（`agent.inject()` 或工具/prompt-submit 的 `additionalContexts`——[拦截 seam Agent Note](2026-06-30-interception-seams.md)），每条都是一次性支付的持久 `context/message`，之后被前缀缓存覆盖。
|
||||
- **在持久请求信封中保持精确。** 组合先于实例的首次 `agent/pre-step` 和请求边界。第一个已路由请求会把当前前缀记录在其 header 上，因此步骤后的 token 压力会将精确前缀与实际 prompt、工具和已路由模型一起读取；通用的步骤前检查点 seam 不携带压缩专属参数。被 cancel/dispose 中断的组合会被丢弃，永不缓存：感知中止的监听器的降级回退不会泄漏到后续请求中，下一轮次在活信号下重新组合。
|
||||
- **按实例冻结。** 复用是结构性的，而非靠纪律保证：缓存的产物在会话中途不可变，因此提供方的提示词缓存从构造上成立，前缀以每步零边际成本扩展了可缓存区域。进程重启或 `ctx.agents.resume()` 产生新实例：它重新组合，任何漂移都可追溯地落在 `'resume'` header 快照上。这就是本 seam 创建的路由规则：会话冻结的开场内容走前缀；会话中途变化的内容走仅追加历史通道（`agent.inject()` 或工具/prompt-submit 的 `additionalContexts`——[拦截 seam Agent Note](2026-06-30-interception-seams.md)），每条都是一次性支付的持久 `context/message`，之后被前缀缓存覆盖。
|
||||
- **在持久请求信封中保持精确。** 组合先于实例的首次 `agent/pre-step` 和请求边界。第一个已路由请求会把当前前缀记录在其 header 上，因此步骤后的 token 压力会将精确前缀与实际提示词、工具和已路由模型一起读取；通用的步骤前检查点 seam 不携带压缩专属参数。被取消/dispose 中断的组合会被丢弃，永不缓存：感知中止的监听器的降级回退不会泄漏到后续请求中，下一轮次在活信号下重新组合。
|
||||
|
||||
由于组合在边界快照之前运行，组合监听器的会话追加会加入当前请求的派生历史。压缩在结构上不可能触及前缀（或系统提示词）：它重写的是表面节点，而 header 状态从不进入表面。
|
||||
|
||||
@@ -30,9 +30,9 @@ Status: implemented
|
||||
|
||||
- **每请求 `before`/`after` 槽位，每步重新计算**（最初提出的形态：一个每请求触发的 waterfall，贡献冻结的 `before` 消息置于历史之前、新鲜的 `after` 消息置于历史之后）：否决。每步重新组合 `before` 会引入漂移，必须记录为完整的变更 header；`after` 槽位位于不断增长的历史之后，其 token 在每个请求中重复支付，且其后的所有内容不可缓存。对照各替代方案衡量，当前所有更新模式都能通过持久追加更廉价地满足（支付一次，此后缓存读取），而唯一没有归属的内容是会话稳定的开场——它需要的是冻结，而非重新计算。
|
||||
- **系统提示词分段**（`system-prompt/assemble`）：对此类内容否决。assembly 渲染为单一 `system` 字符串，消息形态的开场放不进去；且系统提示词被设计为每步重新组装（变化时带完整的变更 header），而开场内容需要按实例冻结的语义。
|
||||
- **持久化历史开场**（会话启动时 `inject()`）：否决。永久历史正是问题陈述中的失败模式——到处被回放、可被压缩、跨 resume 陈旧。
|
||||
- **持久化历史开场**（会话启动时 `inject()`）：否决。永久历史正是问题陈述中的失败模式——到处被回放、可被压缩、在恢复后仍保持陈旧状态。
|
||||
- **按轮次组合而非按实例组合**：否决。轮次边界的重新组合要么与日志静默失同步，要么强制产生变更 header；且它每次触发都会破坏提供方缓存。合理的刷新点是实例边界，`'resume'` 快照已在那里可追溯地记录漂移。
|
||||
- **通过 `agent/pre-step` 携带 prompt/prefix，用于临时压力估算**：否决，因为它把通用生命周期 seam 耦合到一个消费方，而且仍会遗漏更晚的请求路由和工具；步骤后的回放会从持久的已路由 header 读取请求信封的每个字段。
|
||||
- **通过 `agent/pre-step` 携带提示词/前缀，用于临时压力估算**：否决，因为它把通用生命周期 seam 耦合到一个消费方，而且仍会遗漏更晚的请求路由和工具；步骤后的回放会从持久的已路由 header 读取请求信封的每个字段。
|
||||
- **专用会话事件承载前缀**：否决。header 事件按设计就是请求的非历史记录；第二个事件会为同一事实提供第二个归属，并多出一个需要保持完整的编解码器。
|
||||
|
||||
## 后果
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-08-repeat-tool-guard.md: 67ec29c6c9fa38bf1d5935c469f3f71b1119dc3a
|
||||
2026-07-08-repeat-tool-guard.zh.md: 597a51c3a9b160f0447d22e8197917f59cd9ce11
|
||||
2026-07-08-repeat-tool-guard.zh.md: 01037f29810c781c33beee414e50412a0c9b0f89
|
||||
|
||||
@@ -14,7 +14,7 @@ harness 已经具备 pi 扩展所使用的全部 seam，而且更好：[拦截 s
|
||||
|
||||
该守卫是一个循环卫生插件，而非面向模型的工具。它统计对同一工具以相同规范化参数发起的连续调用次数，并在配置的阈值处注入建议性提醒。它从不延迟、阻止或改写调用；模型自行决定是换种方式重试还是结束。
|
||||
|
||||
插件为 `@deepseek-ai/dsh-repeat-tool-guard`，位于 `packages/guard/repeat-tool-guard/`，开辟 `guard/` 分组用于循环卫生插件（单包（package）分组有先例：[todo-write Agent Note](2026-06-29-todo-write-tool.md)发布了 `todo/tool-todo`）。它注册两个监听器，将状态保存在以存活 `Agent` 对象为键的 `WeakMap` 中——工具注册表是 context 级别的单例，其 waterfall（瀑布式事件）交错所有 agent（智能体）的调用（subagent 运行在同一个 context 上），因此按 agent 分键是正确性要求，而非锦上添花；弱对象键还使得纯清理用途的 disposal 监听器不再必要。
|
||||
插件为 `@deepseek-ai/dsh-repeat-tool-guard`，位于 `packages/guard/repeat-tool-guard/`，开辟 `guard/` 分组用于循环卫生插件（单包（package）分组有先例：[todo-write Agent Note](2026-06-29-todo-write-tool.md)发布了 `todo/tool-todo`）。它注册两个监听器，将状态保存在以存活 `Agent` 对象为键的 `WeakMap` 中——工具注册表是上下文级别的单例，其 waterfall（瀑布式事件）交错所有 agent（智能体）的调用（subagent 运行在同一个上下文上），因此按 agent 分键是正确性要求，而非锦上添花；弱对象键还使得纯清理用途的 disposal 监听器不再必要。
|
||||
|
||||
- **`tools/post-execute`（waterfall）**——唯一的检测点。监听器同时接收 `(exec, result)`，因此计数和提醒投递无需跨事件的 pending map（pi 扩展需要它，仅因为其 `tool_call`/`tool_result` 钩子是分开的事件）。它始终通过 `next()` 委托，当命中阈值时，将提醒前置到下游决策的 `additionalContexts`——这正是[钩子桥接](2026-06-30-hook-bridges.md)已采用的「观察并丰富」姿态，遵守 waterfall 契约。计数放在此处而非 `tools/pre-execute`，因为 post-execute 也会为被拒绝的调用触发（`ToolRegistry.execute` 将 deny 路由到同一条流水线），而模型反复敲击一个被拒绝的调用恰恰是值得打破的循环。
|
||||
- **`agent/prompt-submit`（waterfall）**——纯重置钩子：通过 `next()` 委托，清除提交 agent 的链。用户介入改变了上下文；跨越介入的重复不是循环。
|
||||
@@ -30,7 +30,7 @@ harness 已经具备 pi 扩展所使用的全部 seam，而且更好：[拦截 s
|
||||
|
||||
### 提醒投递
|
||||
|
||||
提醒作为独立条目搭载在 `additionalContexts` 上（source 为 `{kind: 'plugin', plugin: 'repeat-tool-guard'}`——依照 `HookContext`，该标签承载语义），绝不替换 `content`：`tool/result` 事件仍是工具自身的审计输出，循环则在步骤结果之后把缓冲的上下文追加为 `context/message`，session 将其渲染为带标签的合成 user 信封，并由派生历史回放。阈值逐级升级：第一个配置阈值获得简短的「你正在重复自己，请分析先前结果」提示；后续各阈值获得详细形式，包含工具、重复计数和规范参数（在头部截断到 `argumentsPreviewChars`，默认 500——循环中的 `write` 级 payload 不得无界地进入下一次请求；链键始终比较完整规范字符串），并说明这些调用没有取得进展。pi 原版把温和文本硬编码为字面计数 3；本守卫以 `thresholds[0]` 为键，修复了移植中的这一 bug。下游钩子桥贡献仍是独立数组条目，因此两个插件都保留各自的 source、信封与元数据。
|
||||
提醒作为独立条目搭载在 `additionalContexts` 上（source 为 `{kind: 'plugin', plugin: 'repeat-tool-guard'}`——依照 `HookContext`，该标签承载语义），绝不替换 `content`：`tool/result` 事件仍是工具自身的审计输出，循环则在步骤结果之后把缓冲的上下文追加为 `context/message`，会话将其渲染为带标签的合成 user 信封，并由派生历史回放。阈值逐级升级：第一个配置阈值获得简短的「你正在重复自己，请分析先前结果」提示；后续各阈值获得详细形式，包含工具、重复计数和规范参数（在头部截断到 `argumentsPreviewChars`，默认 500——循环中的 `write` 级 payload 不得无界地进入下一次请求；链键始终比较完整规范字符串），并说明这些调用没有取得进展。pi 原版把温和文本硬编码为字面计数 3；本守卫以 `thresholds[0]` 为键，修复了移植中的这一 bug。下游钩子桥贡献仍是独立数组条目，因此两个插件都保留各自的 source、信封与元数据。
|
||||
|
||||
### 配置
|
||||
|
||||
@@ -48,7 +48,7 @@ harness 已经具备 pi 扩展所使用的全部 seam，而且更好：[拦截 s
|
||||
|
||||
## 测试
|
||||
|
||||
- **单元测试：** 使用脚本化适配器的真实循环，覆盖计数与重置规则、未追踪透明性、dispose（资源释放）清理、按 agent 隔离、规范化参数键序、升级、被拒绝的调用、无 agent 执行、通配符转义、无效配置，以及下游 block 或 replacement 决策，达到逐文件 100% 覆盖率。
|
||||
- **单元测试：** 使用脚本化适配器的真实循环，覆盖计数与重置规则、未追踪透明性、dispose（资源释放）清理、按 agent 隔离、规范化参数键序、升级、被拒绝的调用、无 agent 执行、通配符转义、无效配置，以及下游阻止或 replacement 决策，达到逐文件 100% 覆盖率。
|
||||
- **快照测试：** keyless 的 `repeat-tool-guard` 场景发起五次相同的 `todo_write` 调用，在 ACP 输出和会话日志中固定第三次调用的温和提醒与第五次调用的详细提醒。该插件在实时示例中加载，但在其他场景中保持静默。
|
||||
- **E2e 测试：** 无。该插件是确定性的且与提供方无关，其 seam 契约由各自的所有者覆盖。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-08-self-referential-cordis-toolset.md: 80bffa3a2a959939f18fd1d3422607cf61895fc7
|
||||
2026-07-08-self-referential-cordis-toolset.zh.md: bdc8bfb7ed3b099fde2eb5d192800b2d6286201f
|
||||
2026-07-08-self-referential-cordis-toolset.zh.md: 75d024c49878e26ecbda416d24c02941a1c754db
|
||||
|
||||
@@ -46,7 +46,7 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
|
||||
|
||||
### 生成的 API 目录
|
||||
|
||||
`cordis_inspect` 从生成的目录提供 API 和事件数据，而非维护一份重复的表格。生成器复用 Cordis 目录的 AST 扫描，输出服务摘要、签名、原始服务方法与事件 JSDoc、事件模式、引用的类型声明以及继承的 context 接口面。有歧义的类型名被省略，过大的声明被标记为截断。
|
||||
`cordis_inspect` 从生成的目录提供 API 和事件数据，而非维护一份重复的表格。生成器复用 Cordis 目录的 AST 扫描，输出服务摘要、签名、原始服务方法与事件 JSDoc、事件模式、引用的类型声明以及继承的上下文接口面。有歧义的类型名被省略，过大的声明被标记为截断。
|
||||
|
||||
新鲜度像所有生成产物一样受门禁约束：`pnpm run verify-cordis-api`（在 `doc-sync` 中）在内存中重新生成并在有任何 diff 时失败，因此 JSDoc 或公开签名变更如果不重新生成模型读取的目录就无法合入。运行时 inspect 工具将目录与活跃运行时取交集而非直接转储：宽泛报告把有目录条目的活跃服务渲染为摘要 + 签名，把没有目录条目的活跃服务（挂载提供的）渲染为名称 + 所属 fiber，简要列出有目录条目但无活跃提供方的服务，再附上引用的类型形状。精确名称报告渲染一个活跃服务或事件，并把原始 JSDoc 紧靠在每个签名之前；让该细节按需出现，避免探索性列表承担其 token 成本。
|
||||
|
||||
@@ -75,7 +75,7 @@ vm 隔离了意外的全局污染，上下文门面隐藏了框架内部细节
|
||||
|
||||
**新增 `cordis/mount` 会话事件。** 一个持久的溯源事件记录每次挂载（源码、名称）有明确先例（`hook/invoked`、`compact/start`）。v1 中予以否决：挂载和卸载已经作为 `tool/call` / `tool/result` 对可见，工具集变化已经作为完整的变更 request header 被记录，因此专用事件只会重复记录。如果审计用例需要将挂载溯源从工具调用中分离出来，日后仍可添加。
|
||||
|
||||
**加固的/能力受限的沙箱。** 对 Node 内置模块设陷阱并向挂载代码提供白名单门面而非原始 context，可能暗示意图是为安全而沙箱化。这里明确不是：陷阱和门面收窄的是挂载代码所见的*接口面*——将其引导至 cordis 服务、远离易泄漏的 Node 内置模块和框架内部——目的是正确性和封堵未受保护的 context 逃逸，但门面暴露的能力（`ctx.bash`、`ctx.fs`、`ctx.web`）触及真实运行时，因此它不是安全边界。真正的安全边界（独立进程、权限提示）超出了一个开发/显式启用工具集的范围，且会与其核心目的——将活跃运行时交给模型——相冲突。
|
||||
**加固的/能力受限的沙箱。** 对 Node 内置模块设陷阱并向挂载代码提供白名单门面而非原始上下文，可能暗示意图是为安全而沙箱化。这里明确不是：陷阱和门面收窄的是挂载代码所见的*接口面*——将其引导至 cordis 服务、远离易泄漏的 Node 内置模块和框架内部——目的是正确性和封堵未受保护的上下文逃逸，但门面暴露的能力（`ctx.bash`、`ctx.fs`、`ctx.web`）触及真实运行时，因此它不是安全边界。真正的安全边界（独立进程、权限提示）超出了一个开发/显式启用工具集的范围，且会与其核心目的——将活跃运行时交给模型——相冲突。
|
||||
|
||||
## 后果
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-12-subagent-persona-tool-filter-and-depth.md: c690f4701a54272205eedf719fbfe0863bac566c
|
||||
2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: ec18becb9c3f446138e7b3573582f3ff2fbb891a
|
||||
2026-07-12-subagent-persona-tool-filter-and-depth.zh.md: be1c2c6a389bb7d800bc7a6553da93a5cf912c7f
|
||||
|
||||
@@ -18,7 +18,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
|
||||
|
||||
| 控制 | 问题 | 结果 |
|
||||
|---|---|---|
|
||||
| `persona` | 什么角色指令替换该子 agent 的部署人设？ | 一个子 agent 局部的 prompt 段落遮蔽 `deployment:persona` |
|
||||
| `persona` | 什么角色指令替换该子 agent 的部署人设？ | 一个子 agent 局部的提示词段落遮蔽 `deployment:persona` |
|
||||
| `toolFilter` | 部署全局工具中哪些进入该子 agent 的可见工具视图？ | 一个有作用域的限制在添加子 agent 局部工具之前过滤全局工具 |
|
||||
| `maxDepth` | 这棵委派树最深可以长到多少层？ | 子 agent 深度超过绝对上限时，启动请求被拒绝 |
|
||||
|
||||
@@ -26,11 +26,11 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
|
||||
|
||||
### 人设是有作用域的遮蔽
|
||||
|
||||
人设控制改变一个子 agent 的行为，而不改变部署级的 prompt 组装。在未发布的设置阶段，进程内提供方在子 agent 作用域中注册一个名为 `deployment:persona` 的段落；普通的最具体者优先解析规则仅在该子 agent 的组装中替换全局段落。
|
||||
人设控制改变一个子 agent 的行为，而不改变部署级的提示词组装。在未发布的设置阶段，进程内提供方在子 agent 作用域中注册一个名为 `deployment:persona` 的段落；普通的最具体者优先解析规则仅在该子 agent 的组装中替换全局段落。
|
||||
|
||||
其值与部署人设具有相同的严格模板语义。省略时通过全局层继承部署段落；显式空字符串则以空段落遮蔽全局人设。父级和兄弟级的人设永远不会进入子 agent 的扁平作用域。
|
||||
|
||||
这使用的是常规的系统提示词注册机制，而非第二条人设通道。因此第一次 prompt 看到的命名贡献与后续 prompt 和 prompt 检查工具看到的一致。
|
||||
这使用的是常规的系统提示词注册机制，而非第二条人设通道。因此第一次提示词看到的命名贡献与后续提示词和提示词检查工具看到的一致。
|
||||
|
||||
### 工具过滤是一条作用于全局视图的活规则
|
||||
|
||||
@@ -51,7 +51,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
|
||||
|
||||
深度限制独立于工具可见性来约束递归委派。顶层 agent 深度为零；进程内子 agent 的深度为其父级已验证深度加一。`maxDepth` 是一个绝对的非负安全整数，当推导出的子 agent 深度大于上限时，启动在子 agent 所有权开始之前即被拒绝。
|
||||
|
||||
有效父级深度取持久 `SessionHeader.delegationDepth` 与运行时 `AgentOptions.subagentDepth` 中的较大值。进程内子 agent 把推导出的深度记录在 session header 中，resume 会恢复该 header，因此重启无法降低递归计数。
|
||||
有效父级深度取持久 `SessionHeader.delegationDepth` 与运行时 `AgentOptions.subagentDepth` 中的较大值。进程内子 agent 把推导出的深度记录在会话 header 中，恢复时会重新载入该 header，因此重启无法降低递归计数。
|
||||
|
||||
每个公开入口都自行验证值域，而非依赖单一的面向模型配置路径。负值、小数、负零、非有限值、不安全整数、格式错误的存储父级深度以及推导溢出均被拒绝。直接的 `SubagentStartRequest` 可以省略上限，让此机制不约束深度；经 Loader 解析的 `dsh-tool-subagent` 配置则默认值为 `3`、接受数值覆盖，并使用显式的 `'provider-managed'` 来省略由进程外提供方部署拥有递归预算时的上限。三是一个较小的有限默认值，仍允许 root 加三代后代：[SDK 辅助函数生成的 subagent 条目](../../../../packages/sdk/helper/src/features/builtin/index.ts)和 [JSON-RPC 示例](../../../../examples/jsonrpc-agent/cordis.yml)采用这项通用策略，而已交付的交互式 ACP、headless 和 REPL 示例固定为一。提供方缺少 `depthLimit` 时，数值工具上限会在提供方挂载阶段失败。
|
||||
|
||||
@@ -67,7 +67,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
|
||||
|
||||
所有子 agent 局部的组合在子 agent 变得可观察之前完成。进程内提供方向 agent 创建提供一个设置回调；该回调在子 agent 作用域中安装人设、工具限制和结构化输出贡献。只有设置成功后，创建才发布会话和 agent 并允许驱动器启动。
|
||||
|
||||
设置失败会回滚私有子 agent。没有观察者能获取到一个「第一次 prompt 使用了部署人设或未过滤工具集、后续 prompt 才使用所请求配置」的子 agent。
|
||||
设置失败会回滚私有子 agent。没有观察者能获取到一个「第一次提示词使用了部署人设或未过滤工具集、后续提示词才使用所请求配置」的子 agent。
|
||||
|
||||
## 可见性不是授权
|
||||
|
||||
@@ -85,7 +85,7 @@ subagent 启动有三个独立的组合控制：`persona`、`toolFilter` 和 `ma
|
||||
|
||||
**在子 agent 创建时快照允许的全局工具。** 冻结的 allow 集合使未来注册统一不可用，但它改变了热注册语义并开启了授权设计。已实现的过滤器保持为活跃的注册表谓词，并直接记录 allow 与 deny 的行为。
|
||||
|
||||
**仅隐藏工具 schema。** 仅呈现层的过滤让模型可以通过 Code Mode 或伪造调用执行一个 prompt 声称不存在的工具。改为由一个解析器同时管控呈现和执行。
|
||||
**仅隐藏工具 schema。** 仅呈现层的过滤让模型可以通过 Code Mode 或伪造调用执行一个提示词声称不存在的工具。改为由一个解析器同时管控呈现和执行。
|
||||
|
||||
**把深度上限编码为自动工具过滤器。** 创建时过滤器会快照一个可能依赖运行时状态的决策，只影响一个已配置工具名，且不保护直接服务调用方或替代委派工具。提供方改为在每次启动时强制绝对上限。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user