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-20-assembled-assistant-messages-only.md: ba8135a3d63f292cfedd23de8b4b9d43b4455e8c
|
||||
2026-06-20-assembled-assistant-messages-only.zh.md: ef24a2eafbdeb71c7637f52804892abaa8e80fa6
|
||||
2026-06-20-assembled-assistant-messages-only.zh.md: 9a42a202425158edd85d7a3f2ef4b0b97e00da90
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Agent Note: 仅持久化组装后的 assistant 消息，不存储流式分片
|
||||
|
||||
Status: rejected — 高保真 chunk 重放、部分失败流与快照重放目前依赖持久化的 `assistant/chunk` 事件。只有具备不丢失信息的重放/artifact 替代方案后，才能删除 chunk。
|
||||
Status: rejected — 高保真分片回放、部分失败流与快照回放目前依赖持久化的 `assistant/chunk` 事件。只有具备不丢失信息的回放/产物替代方案后，才能删除分片。
|
||||
|
||||
[English](2026-06-20-assembled-assistant-messages-only.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-20-drop-acp-session-load.md: 2b6edf173506929f2d64e910b47aa70fb4f1d854
|
||||
2026-06-20-drop-acp-session-load.zh.md: c63ac09903ecfa1aaad44d41e70e452bdcb17bf3
|
||||
2026-06-20-drop-acp-session-load.zh.md: 8e03acad17cf2831a15d5992a0419a73f275719d
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 移除 ACP session/load，直到恢复具备产品形态
|
||||
# Agent Note: 移除 ACP（Agent Client Protocol）session/load，直到恢复具备产品形态
|
||||
|
||||
Status: rejected — Zed 是当前目标 ACP 客户端，它声明并实际使用支持加载的会话，还为并发的 `session/load` 保留待加载状态。桥接层应保留 `session/load` 并巩固恢复契约。
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: rejected — Zed 是当前目标 ACP 客户端，它声明并实际使
|
||||
|
||||
## 问题
|
||||
|
||||
ACP（Agent Client Protocol）声明 `loadSession: true` 并实现 `session/load`：向 bridge 注入持久化能力、校验 cwd 与存储元数据的一致性、从持久化日志重建 agent（智能体），并向客户端回放先前的 transcript（文本记录）更新。该路径有自己的竞态处理、loading-id 守卫、回放展示逻辑和测试。它还依赖规范日志保留足够的 UI 数据，以重建旧的分片和工具展示。
|
||||
ACP 声明 `loadSession: true` 并实现 `session/load`：向 bridge 注入持久化能力、校验 cwd 与存储元数据的一致性、从持久化日志重建 agent（智能体），并向客户端回放先前的 transcript（文本记录）更新。该路径有自己的竞态处理、loading-id 守卫、回放展示逻辑和测试。它还依赖规范日志保留足够的 UI 数据，以重建旧的分片和工具展示。
|
||||
|
||||
持久化仍然是基础能力，但编辑器可见的恢复尚未经过产品流程设计。目前没有会话选择器、没有标题/预览元数据，也没有明确的加载失败或部分加载的用户体验。bridge 正在为一个仅被测试、文档和当前目标客户端的会话模型所使用的功能付出复杂度代价。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-20-drop-acp-terminal-meta.md: 79da387ac1a7a0e6767e3bf24baa6039e39ef90d
|
||||
2026-06-20-drop-acp-terminal-meta.zh.md: e34cd0690beed5d3a1715db6bc3e8413e6227440
|
||||
2026-06-20-drop-acp-terminal-meta.zh.md: d29fd54618611f56fd071a0ee4a63bc207895d89
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 移除 ACP 终端 `_meta` 渲染
|
||||
# Agent Note: 移除 ACP（Agent Client Protocol）终端 `_meta` 渲染
|
||||
|
||||
Status: rejected — Zed 是当前目标客户端，terminal `_meta` 约定是有意设计的 Zed UX，同时为其他客户端保留普通 ACP 回退。
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: rejected — Zed 是当前目标客户端，terminal `_meta` 约定是
|
||||
|
||||
## 问题
|
||||
|
||||
ACP（Agent Client Protocol）桥接层通过 `_meta.terminal_info`、`_meta.terminal_output` 和 `_meta.terminal_exit` 实现了一套 Zed 特有的终端卡片约定。已实现的[富 ACP bash 渲染 Agent Note（agent 决策记录）](../../implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md)刻意回避了 ACP 客户端侧的 `terminal/create`（因为 bash 执行属于 harness 职责），但仍采用了参考 agent（智能体）的纯展示 `_meta` 约定。这在 Zed 中带来了更好的卡片效果，代价是桥接状态、能力协商、终端 id、特殊的 update 映射、文本回退测试，以及 `dsh-tool-bash` 中的 exit-pill 解析。
|
||||
ACP 桥接层通过 `_meta.terminal_info`、`_meta.terminal_output` 和 `_meta.terminal_exit` 实现了一套 Zed 特有的终端卡片约定。已实现的[富 ACP bash 渲染 Agent Note（agent 决策记录）](../../implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md)刻意回避了 ACP 客户端侧的 `terminal/create`（因为 bash 执行属于 harness 职责），但仍采用了参考 agent（智能体）的纯展示 `_meta` 约定。这在 Zed 中带来了更好的卡片效果，代价是桥接状态、能力协商、终端 id、特殊的 update 映射、文本回退测试，以及 `dsh-tool-bash` 中的 exit-pill 解析。
|
||||
|
||||
回退路径已经存在：将工具调用和完成输出渲染为普通 ACP 内容块。非 Zed 客户端本来就依赖这条路径，但 Zed 终端卡片是当前目标客户端的功能特性，而非推测性装饰。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-20-drop-bash-output-spill-files.md: b2bd1a04ee1524bab29814ffa7c22712a83ee5f7
|
||||
2026-06-20-drop-bash-output-spill-files.zh.md: 4a2a8e7d3b0477c0a221e9fe6abe879cfa513aeb
|
||||
2026-06-20-drop-bash-output-spill-files.zh.md: c1b5670fac28a90cc4eb229ba0013e39067af8eb
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Agent Note: 移除 bash 完整输出溢出文件
|
||||
|
||||
Status: rejected — 完整输出恢复是真实的 bash 行为。未来的 artifact/blob 服务或许能将其泛化，但在替代方案就位前删除溢出文件会丢失有用的命令输出。
|
||||
Status: rejected — 完整输出恢复是真实的 bash 行为。未来的产物/blob 服务或许能将其泛化，但在替代方案就位前删除溢出文件会丢失有用的命令输出。
|
||||
|
||||
[English](2026-06-20-drop-bash-output-spill-files.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-20-drop-durable-step-boundaries.md: c5c4f269a378e334c4dc509d1288146d77d9a520
|
||||
2026-06-20-drop-durable-step-boundaries.zh.md: 17d5b6d1860fd256758cadb429de0f390089826e
|
||||
2026-06-20-drop-durable-step-boundaries.zh.md: f2150699c74b16557d936d6833fcba02e7d76e69
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Agent Note: 移除持久化的步骤边界事件
|
||||
|
||||
Status: rejected — `step/end` 是模型步骤已完成的持久信号；保留对称的 `step/start` / `step/end` 对，比从相邻的步骤作用域事件推断完成状态更便于理解崩溃修复、不变式与 transcript 检查。
|
||||
Status: rejected — `step/end` 是模型步骤已完成的持久信号；保留对称的 `step/start` / `step/end` 对，比从相邻的步骤作用域事件推断完成状态更便于理解崩溃修复、不变式与 transcript（文本记录）检查。
|
||||
|
||||
[English](2026-06-20-drop-durable-step-boundaries.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-20-drop-unused-session-lineage.md: 605f1949999435b24404e0c5a72320416303ae52
|
||||
2026-06-20-drop-unused-session-lineage.zh.md: f49e9af0fe22be41228b058f5c700815cc7aa893
|
||||
2026-06-20-drop-unused-session-lineage.zh.md: 981f44189f4b8f11f513261db7094afdc650dffa
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Agent Note: 移除未使用的会话血缘元数据
|
||||
|
||||
Status: rejected — `parentSession` 是已记录的 fork/subagent seam 的一部分，并已由 agent/session 恢复路径保留。该字段面向未来，但并非意外遗留的死状态。
|
||||
Status: rejected — `parentSession` 是已记录的 fork/subagent seam 的一部分，并已由 agent（智能体）/会话恢复路径保留。该字段面向未来，但并非意外遗留的死状态。
|
||||
|
||||
[English](2026-06-20-drop-unused-session-lineage.md) | 中文
|
||||
|
||||
@@ -19,7 +19,7 @@ Status: rejected — `parentSession` 是已记录的 fork/subagent seam 的一
|
||||
## 验收标准
|
||||
|
||||
- `SessionHeader` 仅包含 version、id、createdAt 和可选的 cwd。
|
||||
- JSONL 与 SQLite 元数据 schema 不再存储 parent-session id。
|
||||
- JSONL 与 SQLite 元数据 schema 不再存储父会话 id。
|
||||
- 恢复与列表 API 不再往返传递 `parentSession`。
|
||||
- 文档和测试移除没有生产消费方支撑的 fork 血缘声明。
|
||||
- 会话格式版本、后端 schema 版本与记录的 fixture（测试前置数据）按需刷新；按预发布格式策略，非当前版本的存储数据将被拒绝，不提供迁移路径。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-20-fold-session-persistence-interface.md: 895b868b2a80d8655284bae1364a85e19e174da7
|
||||
2026-06-20-fold-session-persistence-interface.zh.md: 8b1d87431b27d91c9b9765055d783dea940b981d
|
||||
2026-06-20-fold-session-persistence-interface.zh.md: c124b16531f904eb72cb8ac3842642d819309e14
|
||||
|
||||
@@ -12,16 +12,16 @@ Status: rejected — 独立的持久化接口包是为持久后端设计的模
|
||||
|
||||
## 提案
|
||||
|
||||
将抽象的 `SessionPersistence` 服务、协调器和持久化契约辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由 session 包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
|
||||
将抽象的 `SessionPersistence` 服务、协调器和持久化契约辅助工具移入 `dsh-session`。JSONL 和 SQLite 仍作为独立的后端包，注册由会话包拥有的服务。这样既保留了后端可替换性，又删除了一个支撑包和一条跨包 seam。
|
||||
|
||||
实施 PR（Pull Request）应更新[能力 seam](../../implemented/architecture/2026-06-13-capability-seams.md) 指南，补充此例外：持久化不同于 bash 或 LLM（大语言模型），因为它的词汇和生命周期事件本就属于 session 包的核心领域。
|
||||
实施 PR（Pull Request）应更新[能力 seam](../../implemented/architecture/2026-06-13-capability-seams.md) 指南，补充此例外：持久化不同于 bash 或 LLM（大语言模型），因为它的词汇和生命周期事件本就属于会话包的核心领域。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `@deepseek-ai/dsh-session-persistence` 作为包被移除。
|
||||
- `dsh-session` 导出持久化服务类型、协调器和契约辅助工具。
|
||||
- JSONL 和 SQLite 后端包直接依赖 `dsh-session`。
|
||||
- `agent-loop` 的恢复功能使用 session 包拥有的服务键。
|
||||
- `agent-loop` 的恢复功能使用会话包拥有的服务键。
|
||||
- [会话持久化](../../implemented/architecture/2026-06-14-session-persistence.md)、[共享持久化写入协调器](../../implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)与[包文档](../../../../packages/session-persistence/session-persistence/README.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-20-generic-tool-rendering.md: 6fc610546da04e7d1e16fc17ada87483a142aa3c
|
||||
2026-06-20-generic-tool-rendering.zh.md: 4310e35a71fb13dfe1b00190da444a56bc8b4e81
|
||||
2026-06-20-generic-tool-rendering.zh.md: 11386b87d845129950a8473eb1cf4ea6ce697ac8
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# Agent Note: 收拢工具自有的 UI 展示逻辑
|
||||
|
||||
Status: rejected — 工具拥有的呈现机制应等到出现更多真实工具后再进行泛化或删除。Bash 与 ACP 目前仍需要现有的丰富呈现路径。
|
||||
Status: rejected — 工具拥有的呈现机制应等到出现更多真实工具后再进行泛化或删除。Bash 与 ACP（Agent Client Protocol）目前仍需要现有的丰富呈现路径。
|
||||
|
||||
[English](2026-06-20-generic-tool-rendering.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
工具可以定义 `presentCall()` 和 `presentResult()` 回调，返回 `ToolCallPresentation`、`ToolResultPresentation` 以及可选的 `ToolTerminal` 字段。代码本身就标记了这个设计的混乱：title、kind、raw input、content、terminal cwd、terminal output、exit code 和 signal 逐步增长为一堆可选字段。ACP（Agent Client Protocol）随后维护 pending call 状态以将 result 与原始 args 配对，在 `session/load` 时创建仅用于回放的 presenter，并将 terminal 子字段映射为 Zed 特有的 `_meta`。`dsh-tool-bash` 甚至从渲染后的文本中反向解析退出状态，因为纯回放安全的 presenter 已经拿不到结构化的 `BashRunResult`。
|
||||
工具可以定义 `presentCall()` 和 `presentResult()` 回调，返回 `ToolCallPresentation`、`ToolResultPresentation` 以及可选的 `ToolTerminal` 字段。代码本身就标记了这个设计的混乱：title、kind、raw input、content、terminal cwd、terminal output、exit code 和 signal 逐步增长为一堆可选字段。ACP 随后维护 pending call 状态以将 result 与原始 args 配对，在 `session/load` 时创建仅用于回放的 presenter，并将 terminal 子字段映射为 Zed 特有的 `_meta`。`dsh-tool-bash` 甚至从渲染后的文本中反向解析退出状态，因为纯回放安全的 presenter 已经拿不到结构化的 `BashRunResult`。
|
||||
|
||||
真正的第一方用途是为 ACP 提供 bash 展示。这不足以作为冻结一个跨包 UI 展示 API 的依据。
|
||||
真正的第一方用途是为 ACP 提供 bash 展示。这不足以作为冻结一个跨包（package）UI 展示 API 的依据。
|
||||
|
||||
## 提案
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-20-retire-mid-turn-steering.md: a8812b3222739244d77f4d4dab60cf7c0cd6907d
|
||||
2026-06-20-retire-mid-turn-steering.zh.md: f31a062e73043348183c27053e73f79168ba8cef
|
||||
2026-06-20-retire-mid-turn-steering.zh.md: 81a211a167daeb8c57b98f2a1c1451dbc54d09e4
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# Agent Note: 移除轮次中途引导
|
||||
|
||||
Status: rejected — 轮次中途 steering 是一项有意设计的 agent 能力，用于接收步骤之间的用户/插件输入以及未来的 goal/loop 工作流。它是面向产品方向的复杂度，而非 `send()` 的意外重复。
|
||||
Status: rejected — 轮次中途 steering（中途引导）是一项有意设计的 agent（智能体）能力，用于接收步骤之间的用户/插件输入以及未来的 goal/loop 工作流。它是面向产品方向的复杂度，而非 `send()` 的意外重复。
|
||||
|
||||
[English](2026-06-20-retire-mid-turn-steering.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
agent（智能体）暴露了两条用户消息路径，外观相近但生命周期语义不同：`send()` 将一条普通用户轮次排入队列，而 `steer()` 在当前运行轮次的步骤之间注入一条消息，空闲时则回退为 `send()`。这一区分贯穿整个栈：`Agent.steer()` 是公开 API；会话日志有持久化的 `steering/message` 事件；agent 事件分类体系有 `agent/steering`；agent loop（智能体循环）在排队消息 FIFO 之外还维护一个 steering FIFO；取消操作需要清空两个队列；`deriveMessages()` 必须将 steering 渲染为带标签的合成用户消息，而非普通提示词。
|
||||
agent 暴露了两条用户消息路径，外观相近但生命周期语义不同：`send()` 将一条普通用户轮次排入队列，而 `steer()` 在当前运行轮次的步骤之间注入一条消息，空闲时则回退为 `send()`。这一区分贯穿整个栈：`Agent.steer()` 是公开 API；会话日志有持久化的 `steering/message` 事件；agent 事件分类体系有 `agent/steering`；agent loop（智能体循环）在排队消息 FIFO 之外还维护一个 steering FIFO；取消操作需要清空两个队列；`deriveMessages()` 必须将 steering 渲染为带标签的合成用户消息，而非普通提示词。
|
||||
|
||||
续行 seam 进一步放大了成本。`agent/turn-continuation` 默认条件为 `hadToolCalls || steeringInjected`，因此同一轮次内的 steering（中途引导）消息即使模型未请求工具调用，也会强制循环再次调用模型。注释中提到了未来 `/goal`、`/loop` 和预算守卫的用途，但当前仓库没有生产级监听器；只有测试注册了该 waterfall（瀑布式事件）。另外，唯一调用 `steer()` 的生产 UI 是 stdio 演示。ACP（Agent Client Protocol）在轮次运行期间已经通过普通队列发送提示词。
|
||||
续行 seam 进一步放大了成本。`agent/turn-continuation` 默认条件为 `hadToolCalls || steeringInjected`，因此同一轮次内的 steering 消息即使模型未请求工具调用，也会强制循环再次调用模型。注释中提到了未来 `/goal`、`/loop` 和预算守卫的用途，但当前仓库没有生产级监听器；只有测试注册了该 waterfall（瀑布式事件）。另外，唯一调用 `steer()` 的生产 UI 是 stdio 演示。ACP（Agent Client Protocol）在轮次运行期间已经通过普通队列发送提示词。
|
||||
|
||||
## 提案
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-20-single-session-acp-bridge.md: e99de76854390a0979d1b66866d1d48aacbc0036
|
||||
2026-06-20-single-session-acp-bridge.zh.md: e4c9a4c9371749f02a4a7c4f55d724ba4641e2c0
|
||||
2026-06-20-single-session-acp-bridge.zh.md: 660e4ccf6f2fba8672315bfed30872870f401554
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 将 ACP 桥接恢复为每连接一个活跃会话
|
||||
# Agent Note: 将 ACP（Agent Client Protocol）桥接恢复为每连接一个活跃会话
|
||||
|
||||
Status: rejected — Zed 是当前目标 ACP 客户端，其 ACP 实现明确支持多会话：它把活跃会话存入 `HashMap<SessionId, AcpSession>`，跟踪 `pending_sessions`，合并同一 id 的并发加载，并测试加载期间关闭的行为。
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: rejected — Zed 是当前目标 ACP 客户端，其 ACP 实现明确支
|
||||
|
||||
## 问题
|
||||
|
||||
ACP（Agent Client Protocol）桥接现在支持在一条 JSON-RPC 连接上承载多个活跃会话。这一能力带来了多条目会话映射、反向会话/agent（智能体）查找、逐会话的提示词状态、加载中 id、每条事件的解复用、跨会话拆除，以及未来权限提示与后台任务的隔离问题。较早的[多会话 ACP 提案](../../implemented/feature/2026-06-14-acp-multi-session.md)仍在追踪未完成的权限归属部分；本 Agent Note（agent 决策记录）是与之竞争的简化路径。
|
||||
ACP 桥接现在支持在一条 JSON-RPC 连接上承载多个活跃会话。这一能力带来了多条目会话映射、反向会话/agent（智能体）查找、逐会话的提示词状态、加载中 id、每条事件的解复用、跨会话拆除，以及未来权限提示与后台任务的隔离问题。较早的[多会话 ACP 提案](../../implemented/feature/2026-06-14-acp-multi-session.md)仍在追踪未完成的权限归属部分；本 Agent Note（agent 决策记录）是与之竞争的简化路径。
|
||||
|
||||
产品目标已经证明它需要在一个 harness 进程上承载并发的编辑器对话：Zed 的 ACP 连接拥有多个会话和加载状态。快照回放层仍然避免并发模型流，因为其回放条目是位置相关的；这是测试 fixture（测试前置数据）的局限，而非移除桥接多路复用的理由。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-04-prune-unimplemented-subagent-vocabulary.md: 890aca31f09f97ab6d9bf7c00f738d894695d9ad
|
||||
2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md: f4525b609c1c1bab54a2063ceb1fa143ab75ec63
|
||||
2026-07-04-prune-unimplemented-subagent-vocabulary.zh.md: 7837759604a30ee8f58d922bb5f55f6730d1ddcb
|
||||
|
||||
@@ -6,12 +6,12 @@ Status: rejected — 延后的能力词汇（`outputSchema`/`structured`、`tool
|
||||
|
||||
## 问题
|
||||
|
||||
[subagent seam](../../implemented/feature/2026-06-21-subagent-capability-seam.md) 交付了一套两层能力设计：启动时由服务检查的能力 flag，以及 `SubagentRun` 上的可选运行时方法。三个启动时特性和两个可选运行时方法的实现数与调用数均为零：
|
||||
[subagent seam](../../implemented/feature/2026-06-21-subagent-capability-seam.md) 交付了一套两层能力设计：启动时由服务检查的能力 flag，以及 `SubagentRun` 上的可选运行时方法。三个启动时功能和两个可选运行时方法的实现数与调用数均为零：
|
||||
|
||||
- **`outputSchema`/`structured` 与 `toolFilter`**（`SubagentCapabilities`、`SubagentStartRequest`、`SubagentResult`，位于 `packages/subagent/subagent/src/types.ts`）：在作出决策时，每个真实提供方都声明 `outputSchema: false, toolFilter: false`（`packages/subagent/subagent-spawn/src/index.ts`、`packages/subagent/subagent-fork/src/index.ts`、`packages/subagent/subagent-acp/src/index.ts`）；唯一的生产环境 `ctx.subagents.start` 调用方（`packages/subagent/tool-subagent/src/index.ts`）构造 `{ prompt, parent, signal?, agentOptions? }`，结构上无法设置这两个字段；`structured` 仅出现在脚本化测试 fixture（测试前置数据）中。服务的能力检查包含两行 assert，其唯一执行者是拒绝测试。
|
||||
- **`SubagentRun.sendMessage` / `SubagentRun.resume`**（同一文件）：没有任何提供方实现——包括 mock 也没有；spawn spec 断言的正是它们的*缺失*。
|
||||
|
||||
在作出决策时，`dsh-subagent` 依赖 `dsh-tools` 的唯一原因是 `outputSchema` 的 schema 类型（现为 `ObjectJsonSchema`）。三个后续 subagent 工作流（per-session 快照回放、fork seed 边界、ACP（Agent Client Protocol） 后端）都围绕这块接口面落地，却没有增长出哪怕一个消费方。
|
||||
在作出决策时，`dsh-subagent` 依赖 `dsh-tools` 的唯一原因是 `outputSchema` 的 schema 类型（现为 `ObjectJsonSchema`）。三个后续 subagent 工作流（按会话快照回放、fork seed 边界、ACP（Agent Client Protocol）后端）都围绕这块接口面落地，却没有增长出哪怕一个消费方。
|
||||
|
||||
## 提案
|
||||
|
||||
@@ -19,7 +19,7 @@ Status: rejected — 延后的能力词汇（`outputSchema`/`structured`、`tool
|
||||
|
||||
**保留** `depthLimit`/`maxDepth` 与能力检查。进程内后端已强制执行该限制，尽管当前发布的工具尚未设置它。递归是已知的 seam 风险，因此恰当的后续工作是提供一个工具默认值，而非删除正在工作的强制逻辑。
|
||||
|
||||
审视过但有意不动的相邻接口面：`SubagentService.getProvider()`/`list()` 仅有测试 harness 消费方，但 [prune-dead-seam-methods 实现说明](../../implemented/simplification/2026-06-20-prune-dead-seam-methods.md)恰好记录了这种形态从 bash executor 中被移除后又被回退的经过——对于一个基于已跟踪 map 的单行访问器而言，测试 harness 就是消费方。`SubagentRunEndInfo.lastAssistantMessage` 是一个已记录的保留项（[subagent 观测/丰富化 Agent Note](../../implemented/feature/2026-06-30-subagent-observe-enrich.md)的评审删除了 `agentType` 但有意保留了它，因为它是进程外子 agent（智能体）唯一的最终消息通道）；它当前未接通的桥接转发是一个待补的缺口或待记录的消费方，不是本 Agent Note 要裁剪的接口面。
|
||||
审视过但有意不动的相邻接口面：`SubagentService.getProvider()`/`list()` 仅有测试 harness 消费方，但 [prune-dead-seam-methods 实现说明](../../implemented/simplification/2026-06-20-prune-dead-seam-methods.md)恰好记录了这种形态从 bash 执行器中被移除后又被回退的经过——对于一个基于已跟踪 map 的单行访问器而言，测试 harness 就是消费方。`SubagentRunEndInfo.lastAssistantMessage` 是一个已记录的保留项（[subagent 观测/丰富化 Agent Note](../../implemented/feature/2026-06-30-subagent-observe-enrich.md)的评审删除了 `agentType` 但有意保留了它，因为它是进程外子 agent（智能体）唯一的最终消息通道）；它当前未接通的桥接转发是一个待补的缺口或待记录的消费方，不是本 Agent Note 要裁剪的接口面。
|
||||
|
||||
这是[从持久化 seam 裁剪死方法](../../implemented/simplification/2026-06-20-prune-dead-seam-methods.md)在 seam 词汇层面的回响：每个实现都必须为无人声明的成员，甚至更弱，因为这里连一个实现都没有。
|
||||
|
||||
@@ -36,4 +36,4 @@ Status: rejected — 延后的能力词汇（`outputSchema`/`structured`、`tool
|
||||
|
||||
## 风险
|
||||
|
||||
subagent 生命周期事件在结束载荷上携带 `lastAssistantMessage`——该增强位于服务模块中，不在本 Agent Note 缩减的 seam 词汇范围内；observe-enrich Agent Note 记录了因缺少消费方而删除 `agentType` 兄弟字段的判断，本 Agent Note 延续了这一判断。CC hooks 桥接是这些生命周期事件的第一个外部消费方，它只读取事件载荷，不涉及本文移除的任何接口面；observe-enrich Agent Note 推迟的控制流重设计将实现 `resume` 列为自身的未来工作——恰好是本 Agent Note 模式所预期的重新添加触发点。
|
||||
subagent 生命周期事件在结束载荷上携带 `lastAssistantMessage`——该增强位于服务模块中，不在本 Agent Note 缩减的 seam 词汇范围内；observe-enrich Agent Note 记录了因缺少消费方而删除 `agentType` 兄弟字段的判断，本 Agent Note 延续了这一判断。CC 钩子桥接是这些生命周期事件的第一个外部消费方，它只读取事件载荷，不涉及本文移除的任何接口面；observe-enrich Agent Note 推迟的控制流重设计将实现 `resume` 列为自身的未来工作——恰好是本 Agent Note 模式所预期的重新添加触发点。
|
||||
|
||||
@@ -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-collapse-workflow-to-foreground-core.md: 629e2140523c3ae7caf533de99821206d05f1b8e
|
||||
2026-07-12-collapse-workflow-to-foreground-core.zh.md: 79eb61653e812647082ba6ebcb7f0636db6e0240
|
||||
2026-07-12-collapse-workflow-to-foreground-core.zh.md: f71ea19f563ff64a1f638c644d35f51148e493cb
|
||||
|
||||
@@ -8,7 +8,7 @@ Status: rejected — 工作流进度是有意设计的观测接口面；应通
|
||||
|
||||
工作流能力执行前台 JavaScript 来编排 subagent，但它同时携带了一套无人消费的进度观测系统。没有任何生产环境的监听器订阅六个 `workflow/*` 事件中的任何一个；监听器仅存在于工作流测试中。尽管如此，seam 定义了 run/phase/agent（智能体） outcome 载荷，worker 发送 phase/log/agent 生命周期协议消息，host 通过一个 `liveAgents` 配对账本转发它们，引擎维护 run id 仅仅是为了关联这些通知。
|
||||
|
||||
这套进度词汇不仅仅是未被使用；它在不经重新设计的情况下也无法服务于其唯一已命名的未来消费方。`WorkflowRunInfo` 包含 `{id, meta}` 但没有父 agent（智能体）、会话或工具调用标识，而面向模型的工具也从不暴露 run id。一个全局 ACP（Agent Client Protocol）监听器无法将事件路由到正确的客户端会话。`meta.phases` 从未被查询，`phase(title)` 不对其做校验，phase 的 `detail`/`model` 和 agent 的 `label`/`phase` 仅供事件消费，`whenToUse` 被校验和复制但从未被渲染或用于选择。`phase()` 和 `log()` 仍然跨越 worker 边界，尽管没有接收方。
|
||||
这套进度词汇不仅仅是未被使用；它在不经重新设计的情况下也无法服务于其唯一已命名的未来消费方。`WorkflowRunInfo` 包含 `{id, meta}` 但没有父 agent、会话或工具调用标识，而面向模型的工具也从不暴露 run id。一个全局 ACP（Agent Client Protocol）监听器无法将事件路由到正确的客户端会话。`meta.phases` 从未被查询，`phase(title)` 不对其做校验，phase 的 `detail`/`model` 和 agent 的 `label`/`phase` 仅供事件消费，`whenToUse` 被校验和复制但从未被渲染或用于选择。`phase()` 和 `log()` 仍然跨越 worker 边界，尽管没有接收方。
|
||||
|
||||
live handle 在观测者消失后仍重复事件时代的数据。`WorkflowRun.id` 没有非事件消费方，而工具读取 `run.meta.name` 只是为了渲染一个它已经以 `args.meta.name` 形式持有的值；两者都不属于执行/取消 handle。
|
||||
|
||||
@@ -20,11 +20,11 @@ live handle 在观测者消失后仍重复事件时代的数据。`WorkflowRun.i
|
||||
|
||||
保留已使用的核心：`agent(prompt, { schema, model })`、`parallel`、`pipeline`、`args`、并发/agent 上限、取消、有界 dispose（资源释放）、结构化结果、worker 隔离与前台工具收集。移除所有 `workflow/*` 事件及其仅供事件使用的 info/outcome 类型；移除 `phase()`、`log()`、agent 的 `label`/`phase`、phase 声明、`whenToUse` 及其 worker 消息/host 观测者；将工作流元数据收缩为工具实际使用的 name；移除仅供事件使用的 run id/meta 快照与合成的 agent-end 账本。将 `WorkflowRun` 收缩为 `result`、`cancel()` 和 `dispose()`；工具渲染请求方持有的 name。移除 `WorkflowStartRequest.signal` 及 worker host 的 input-signal listener/disarm 状态，保留调用方从其 abort signal 到 `run.cancel()` 的桥接。将 `WorkflowError` 变为单一的 fatal 错误类，不再有布尔模式或 `isFatalWorkflowError()` 辅助函数。
|
||||
|
||||
修订已实施的 dynamic-workflow Agent Note（agent 决策记录），并更新 seam/工具/worker README、工具 schema、生成的 catalog 与包（package）依赖图、worker type-equiv 记录、单元测试以及工作流快照/header fixture（测试前置数据）。如果进度 UI 工作被立项，应从一份命名了父 agent/会话/工具调用的关联契约出发，而非原样复活这套协议。
|
||||
修订已实施的动态工作流 Agent Note（agent 决策记录），并更新 seam/工具/worker README、工具 schema、生成的 catalog 与包（package）依赖图、worker type-equiv 记录、单元测试以及工作流快照/header fixture（测试前置数据）。如果进度 UI 工作被立项，应从一份命名了父 agent/会话/工具调用的关联契约出发，而非原样复活这套协议。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**为未来 UI 保留预建的观测词汇。** 当前形态类似 Claude Code 的 dynamic-workflow 元数据，host 有意地将每个转发的 agent start 与 worker 的 end 或一个合成的终止 end 配对。移除它意味着放弃形态兼容性，使进度 UI 成为一项全新的设计任务；但现有载荷仍缺少可路由的归属信息，因此仅靠平衡的生命周期也无法在不重新设计的情况下让已命名的 ACP 消费方可行。
|
||||
**为未来 UI 保留预建的观测词汇。** 当前形态类似 Claude Code 的动态工作流元数据，host 有意地将每个转发的 agent start 与 worker 的 end 或一个合成的终止 end 配对。移除它意味着放弃形态兼容性，使进度 UI 成为一项全新的设计任务；但现有载荷仍缺少可路由的归属信息，因此仅靠平衡的生命周期也无法在不重新设计的情况下让已命名的 ACP 消费方可行。
|
||||
|
||||
## 验收标准
|
||||
|
||||
|
||||
@@ -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-prune-unused-skill-registry-surface.md: 5a13effa04a6cd9954741a0a33ebc6fc3512fab8
|
||||
2026-07-12-prune-unused-skill-registry-surface.zh.md: 6d917fadf3d408c934e88b2bd0a9c7691632f91b
|
||||
2026-07-12-prune-unused-skill-registry-surface.zh.md: 46d49a02c294c492abdd6e7e611a5c92eb317c12
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 裁剪 skill 注册表中未使用的接口
|
||||
# Agent Note: 裁剪 skill（技能）注册表中未使用的接口
|
||||
|
||||
Status: rejected — 直接在运行时注册 skill 是为第三方插件保留的有意扩展路径。
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: rejected — 直接在运行时注册 skill 是为第三方插件保留
|
||||
|
||||
## 问题
|
||||
|
||||
skill（技能）服务的嵌入式运行时子系统中，`ctx.skills.register()` 没有任何生产调用方。它引入了一个保留的 `runtime` 提供方名称、一套运行时 map/rank/source、重复策略、缓存键中的第二个 revision、规范化逻辑、dispose（资源释放）器以及相应测试——而所有已交付的 skill 都只使用提供方 seam。`SkillSummary.whenToUse` 和 candidate/definition 的 `path` 被解析和复制，但没有任何生产消费方读取它们：模型目录只渲染 name/description，资源加载使用 `resourceBase`，提供方自行管理其定位器。有意开放的 `metadata` 扩展点保留不动。
|
||||
skill 服务的嵌入式运行时子系统中，`ctx.skills.register()` 没有任何生产调用方。它引入了一个保留的 `runtime` 提供方名称、一套运行时 map/rank/source、重复策略、缓存键中的第二个 revision、规范化逻辑、dispose（资源释放）器以及相应测试——而所有已交付的 skill 都只使用提供方 seam。`SkillSummary.whenToUse` 和 candidate/definition 的 `path` 被解析和复制，但没有任何生产消费方读取它们：模型目录只渲染 name/description，资源加载使用 `resourceBase`，提供方自行管理其定位器。有意开放的 `metadata` 扩展点保留不动。
|
||||
|
||||
## 提案
|
||||
|
||||
|
||||
Reference in New Issue
Block a user