Merge remote-tracking branch 'origin/master' into xtr/agent-loop-message-machine
# Conflicts: # .agents/notes/archived/feature/2026-07-21-tui-steering-queue-badge.i18n.yaml # .agents/notes/archived/simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.i18n.yaml # .agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.i18n.yaml # .agents/notes/archived/simplification/2026-07-04-remove-agent-steering-mirror.i18n.yaml # .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml # .agents/notes/implemented/feature/2026-07-07-session-prefix.i18n.yaml # .agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.i18n.yaml # docs/core-data-structures/session.i18n.yaml # docs/event-producer-consumer.md # examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl # packages/core/session/README.i18n.yaml # packages/host/apiproxy/src/api-proxy.ts # packages/support/acp-snapshot/README.i18n.yaml # packages/support/acp-snapshot/README.md # packages/support/acp-snapshot/README.zh.md
This commit is contained in:
_Kerman
7
.agents/notes/archived/AGENTS.md
Normal file
7
.agents/notes/archived/AGENTS.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# AGENTS.md — Archived Agent Notes
|
||||
|
||||
Archived Agent Note triplets under the kind directories are frozen historical snapshots, not current authority. Never edit, reformat, translate, repair, delete, or move a sealed artifact; use an active Agent Note or current documentation for new decisions and facts.
|
||||
|
||||
The archival change may only relocate a complete English/Chinese/sidecar triplet, insert the identical `Archived: YYYY-MM-DD` line below both `Status: implemented` lines, re-record the sidecar, and repair or delete inbound links. Do not inspect, verify, or repair links out of archived notes.
|
||||
|
||||
Run the [`dsh-archive-agent-notes`](../../skills/dsh-archive-agent-notes/SKILL.md) workflow and append new artifact hashes with `pnpm run verify-archived-agent-notes --write`. The normal verifier rejects changed or missing sealed artifacts, incomplete triplets, unknown kind folders, and invalid archive metadata.
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-11-custom-schema-dsl.md: e09fea6c4bb80e287b1b64471eee4c87f24fba4a
|
||||
2026-06-11-custom-schema-dsl.zh.md: 2bacbde02838ef61b05f38796bbeeea262fc2d23
|
||||
@@ -0,0 +1,24 @@
|
||||
# Agent Note: Custom typed tool-schema DSL instead of schemastery
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-06-11-custom-schema-dsl.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Tool parameters must reach the model as standard JSON Schema while giving tool authors typed `execute(args)` without casts. Schemastery already serves plugin config, but the tool-author API needs per-property `required: true` booleans rather than JSON Schema's separate `required` array.
|
||||
|
||||
## Decision
|
||||
|
||||
This decision is superseded by the [unified JSON-value schema DSL](2026-07-20-unified-json-value-schema-dsl.md), which retains the small authoring surface while making parameters and typed values share one vocabulary. `ParameterSchemaSpec` keeps per-property `required: true`; `InferArgs<S>` maps required keys to non-optional properties; `parameterSchemaSpecToJsonSchema()` compiles the implicit open object root; and `defineTool()` ties inference, compilation, and validation together. Raw JSON-Schema `ToolDefinition`s remain accepted by `ToolRegistry.register()` for MCP and other external tools.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Schemastery** (already vendored, used for plugin Config) was evaluated and rejected for this use: it targets validation / transformation against StandardSchema, not JSON Schema *generation*, so it would add indirection without producing the wire format cleanly.
|
||||
|
||||
## Consequences
|
||||
|
||||
- First-party tool authors get zero-cast typed args; the type gymnastics cost stays inside the core package (sanctioned by the AGENTS.md type-safety policy).
|
||||
- The owning unified note defines the current nodes, literal constraints, unions, JSON-value boundary, and object-openness rules.
|
||||
- The `InferArgs` mapping is regression-tested at the type level after an early optionality bug.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Agent Note: 使用自定义类型化工具 schema DSL 替代 schemastery
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-06-11-custom-schema-dsl.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
工具参数必须以标准 JSON Schema 形式到达模型，同时让工具作者在 `execute(args)` 中获得类型化的参数而无需类型断言。Schemastery 已用于插件配置，但工具作者 API 需要逐属性的 `required: true` 布尔值，而非 JSON Schema 的独立 `required` 数组。
|
||||
|
||||
## 决策
|
||||
|
||||
该决策已由[统一 JSON 值 schema DSL](2026-07-20-unified-json-value-schema-dsl.md)取代；新设计保留小型编写接口，同时让参数与类型化值共享一套词汇。`ParameterSchemaSpec` 保留逐属性的 `required: true`；`InferArgs<S>` 将必需键映射为非可选属性；`parameterSchemaSpecToJsonSchema()` 编译隐式开放的对象根；`defineTool()` 则将类型推导、编译与校验串联起来。原始 JSON Schema 的 `ToolDefinition` 仍是 `ToolRegistry.register()` 接受的输入，供 MCP 和其他外部工具使用。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**Schemastery**（已作为 vendor 引入，用于插件 Config）经评估后被否决：它面向的是基于 StandardSchema 的校验／转换，而非 JSON Schema *生成*，因此会增加间接层却无法干净地产出协议格式（wire format）。
|
||||
|
||||
## 后果
|
||||
|
||||
- 第一方工具作者获得零类型断言的类型化参数；类型体操的成本留在核心包内部（符合 AGENTS.md 的类型安全策略）。
|
||||
- 当前节点、字面量约束、联合类型、JSON 值边界与对象开放性规则均由上述统一说明定义。
|
||||
- `InferArgs` 映射在类型层面有回归测试，源于早期一个可选性 bug。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-20-extract-example-app-packages.md: 06466aa575a535afe0ba614fb2c2c5b3e857aeab
|
||||
2026-06-20-extract-example-app-packages.zh.md: ccd8eae1524210d75770248566810423280df3b0
|
||||
@@ -0,0 +1,58 @@
|
||||
# Agent Note: Extract example apps into packages
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-06-20-extract-example-app-packages.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
An example folder is supposed to be *thin* — the variable wiring of a demo, not the demo's machinery. Before this change it was thick. Each example carried a hand-rolled `start.ts` boot bootstrap, an infra preamble (`timer`, and — for the stdio demos — `logger` + `hmr`), nested includes of three shared YAML fragments (`base.yml` / `base-core.yml` / `acp-agent/acp-tail.yml`), and per-example `agent-loop`/persistence/system-prompt config. The actual app — the spine of services every agent needs — was spread across the leaf and those includes.
|
||||
|
||||
The leaf configs also owned coupled front doors. ACP requires stdout purity and creates agents through `session/new`; terminal and Headless apps pre-create `main` but have different process I/O contracts. Prose warnings were the only guard against combining these incorrectly, while three `start.ts` files duplicated the Loader bootstrap and lifecycle code.
|
||||
|
||||
## Decision
|
||||
|
||||
Each example is now **mostly an invocation of an app package**, splitting the wiring along the existing [interface / implementation / consumer seam](2026-06-13-capability-seams.md): the **app package owns the composition**, the leaf `cordis.yml` owns only the **swappable choices** (which LLM adapter, which bash executor, model, prompt, persistence root).
|
||||
|
||||
- **`@deepseek-ai/dsh-agent-spine-demo`** ([packages/examples/agent-spine-demo](../../../../packages/examples/agent-spine-demo)) composes the providerless, executor-less, UI-less spine and forwards the loop's agent-list config. Its dependency on the concrete loop is intentional because this package composes the spine rather than extending it; swapping the loop means supplying another bundle.
|
||||
- **`@deepseek-ai/dsh-tui-demo`**, **`@deepseek-ai/dsh-cli-demo`**, and **`@deepseek-ai/dsh-acp-demo`** bake in their process roles. TUI includes the full-screen UI and a pre-created `main`; Headless includes the one-shot driver and a pre-created `main`; ACP includes the bridge and no pre-created agent. All three include JSONL persistence and omit stdout loggers.
|
||||
- **`start.ts` is gone.** Each app package exposes a bin; the `demo:*` scripts invoke it. Loader boot, `.env` loading, and fail-loud guards live in the shared [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) package (unit-tested under the per-file coverage gate — see [share the app bins' boot glue](../simplification/2026-07-04-share-app-bin-boot-glue.md)); the thin self-executing entries are driven by keyless Loader-path tests.
|
||||
- **Each leaf `cordis.yml` collapses** to backends, optional product tools, and one app entry carrying the app config. TUI and Headless route model/session choices onto a pre-created agent; ACP routes the initial provider/model onto its bridge.
|
||||
- **`base.yml`, `base-core.yml`, and `acp-agent/acp-tail.yml` are retired** — the spine they shared now lives in `dsh-agent-spine-demo`.
|
||||
|
||||
`bash-local` and the LLM adapter stay **leaf choices**: the bundle ships `tool-bash` (the consumer schema), the leaf picks the executor implementation, so a sandboxed executor or replay adapter swaps in without touching the app.
|
||||
|
||||
### Amendment on implementation: `hmr` stays a leaf entry
|
||||
|
||||
The proposal listed `hmr` among the interactive app's baked-in front-door cluster. Validating against the code, baking `hmr` into the app package fights Cordis in two ways, so it ships as a **leaf `cordis.yml` entry** instead:
|
||||
|
||||
1. `@cordisjs/plugin-hmr` is a Loader-only, subprocess-only dev plugin — it requires the live `loader` service and its internal module access, so it can only run in the real `demo:*`/bin subprocess, never in the in-process unit/coverage tier.
|
||||
2. The in-process test tier (vitest) cannot even *import* the vendored `hmr` module (its class-decorator `@Inject` form fails under Vite's transform), so a package whose `apply` statically imported it could never satisfy the per-file 100% coverage gate on its headline function.
|
||||
|
||||
Crucially, `hmr` is not a stdout-purity footgun: a stray entry in the ACP config does not corrupt JSON-RPC frames. Every shipped app omits a stdout console logger; the app or protocol driver alone owns stdout.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### Why not keep the wiring in shared YAML includes?
|
||||
|
||||
The old `base*.yml`/`acp-tail.yml` includes already deduped the *config*, but a YAML include cannot **encapsulate** the front-door coupling — it can only describe it in a comment and trust every leaf to obey. It also cannot own a `bin`, so the boot glue stayed copied across three `start.ts` files. A package turns "the ACP app never logs to stdout" from a prose warning into a property of the artifact: there is no logger entry in the leaf to get wrong.
|
||||
|
||||
## Verification
|
||||
|
||||
- Example directories contain only their config, README, and tests: `start.ts`, the infrastructure preamble, and the shared YAML includes are gone.
|
||||
- `demo:tui`, `demo:headless`, and `demo:acp` invoke the app-package bins.
|
||||
- Each new package has a README and per-file 100% coverage; each app package also has a keyless real-Loader-path bin smoke that catches export-shape failures described in [postmortem 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
|
||||
- The ACP replay suite boots through the app-package bin, so protocol wiring and assembled backend behavior cross the real Loader boundary.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **The bare-plugin-tree pedagogy.** The spine lives behind a bundle, so seeing the whole tree means opening `dsh-agent-spine-demo`. The app package's README carries that teaching weight.
|
||||
- **A layer of indirection.** "What does this demo load?" becomes a package read, not a single YAML scan.
|
||||
|
||||
## Related
|
||||
|
||||
- Supersedes [Make the shared example base providerless](../../rejected/architecture/2026-06-20-providerless-example-base.md): renaming `base.yml` to the providerless core is moot once the spine moves into `dsh-agent-spine-demo` and the `base*.yml` files are deleted.
|
||||
- Builds on the [capability-seams](2026-06-13-capability-seams.md) interface/implementation/consumer split — backends and presentation stay leaf choices; the spine is the shared bundle.
|
||||
- Complements [Reorganize packages into a modular hierarchy](2026-06-20-package-hierarchy.md): the new app/core packages slot into existing groups under that hierarchy (`core` for the reusable spine bundle, `ui` for the app-specific front doors).
|
||||
- The later [redundant-agent removal](../simplification/2026-07-20-remove-stdio-and-echo-agents.md) owns the final TUI/Headless split and removes the line-oriented and mock-only leaves.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Agent Note: 将示例应用提取为独立包
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-06-20-extract-example-app-packages.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
示例目录本应是*精简的*——只包含演示的可变接线，而非演示的基础设施。在此次变更之前，它是臃肿的。每个示例都携带一份手写的 `start.ts` 启动引导、一段基础设施前导（`timer`，以及 stdio 演示所需的 `logger` + `hmr`（热模块替换））、三个共享 YAML 片段的嵌套引用（`base.yml` / `base-core.yml` / `acp-agent/acp-tail.yml`），还有各示例自身的 `agent-loop`/持久化/系统提示词配置。真正的应用——每个 agent（智能体）都需要的服务主干——散落在叶子配置和那些 include 中。
|
||||
|
||||
叶子配置还拥有耦合的前门。ACP（Agent Client Protocol）要求 stdout 纯净，并通过 `session/new` 创建 agent；终端应用和 Headless 应用则预创建 `main`，但进程 I/O 契约不同。防止错误组合的唯一屏障是文档中的文字警告，而三个 `start.ts` 文件重复着 Loader 引导和生命周期代码。
|
||||
|
||||
## 决策
|
||||
|
||||
每个示例现在**主要是对一个应用包（package）的调用**，沿着既有的[接口 / 实现 / 消费方 seam](2026-06-13-capability-seams.md) 拆分接线：**应用包拥有组合**，叶子 `cordis.yml` 只拥有**可替换的选择**（哪个 LLM（大语言模型）适配器、哪个 bash 执行器、模型、提示词、持久化根目录）。
|
||||
|
||||
- **`@deepseek-ai/dsh-agent-spine-demo`**（[packages/examples/agent-spine-demo](../../../../packages/examples/agent-spine-demo)）组合了不含提供方、不含执行器、不含 UI 的主干，并转发 agent loop（智能体循环）的 agent 列表配置。它对具体 loop 的依赖是有意为之，因为该包组合的是主干而非扩展主干；替换 loop 意味着提供另一个 bundle。
|
||||
- **`@deepseek-ai/dsh-tui-demo`**、**`@deepseek-ai/dsh-cli-demo`** 和 **`@deepseek-ai/dsh-acp-demo`** 各自内置其进程角色。TUI 包含全屏 UI 和预创建的 `main`；Headless 包含 one-shot driver 和预创建的 `main`；ACP 包含 bridge 且不预创建 agent。三者都包含 JSONL 持久化，并省略 stdout logger。
|
||||
- **`start.ts` 已移除。** 每个应用包都暴露一个 bin；`demo:*` 脚本调用它。Loader 引导、`.env` 加载和快速失败守卫位于共享的 [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) 包（在逐文件覆盖率门禁下有单元测试——见[共享应用 bin 的启动胶水](../simplification/2026-07-04-share-app-bin-boot-glue.md)）；精简的自执行入口由 keyless 的 Loader 路径测试驱动。
|
||||
- **每个叶子 `cordis.yml` 精简为**后端、可选产品工具，以及一个承载应用配置的 app 条目。TUI 和 Headless 把模型/会话选择路由到预创建的 agent；ACP 把初始提供方/模型路由到 bridge。
|
||||
- **`base.yml`、`base-core.yml` 和 `acp-agent/acp-tail.yml` 已退役**——它们共享的主干现在位于 `dsh-agent-spine-demo` 中。
|
||||
|
||||
`bash-local` 和 LLM 适配器仍然是**叶子选择**：bundle 提供 `tool-bash`（消费方 schema），叶子选择执行器实现，因此沙箱执行器或回放适配器无需触碰应用即可替换。
|
||||
|
||||
### 实现修正：`hmr` 保留为叶子条目
|
||||
|
||||
提案最初将 `hmr` 列入交互式应用内置的前门集群。对照代码验证后发现，将 `hmr` 内置到应用包中会在两个方面与 Cordis 冲突，因此改为作为**叶子 `cordis.yml` 条目**交付：
|
||||
|
||||
1. `@cordisjs/plugin-hmr` 是一个仅限 Loader、仅限子进程的开发插件——它需要活跃的 `loader` 服务及其内部模块访问权限，因此只能在真实的 `demo:*`/bin 子进程中运行，不能在进程内的单元/覆盖率测试层运行。
|
||||
2. 进程内测试层（vitest）甚至无法*导入* vendor 的 `hmr` 模块（其 class-decorator `@Inject` 形式在 Vite 的 transform 下会失败），因此一个 `apply` 静态导入了它的包永远无法满足其主函数的逐文件 100% 覆盖率门禁。
|
||||
|
||||
关键在于，`hmr` 不是 stdout 纯净隐患：ACP 配置中误加该条目不会破坏 JSON-RPC 帧。所有已交付应用都省略 stdout 控制台 logger；stdout 只归应用或协议 driver 所有。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
### 为什么不继续用共享 YAML include 来管理接线？
|
||||
|
||||
旧的 `base*.yml`/`acp-tail.yml` include 已经去重了*配置*，但 YAML include 无法**封装**前门耦合——它只能在注释中描述，并信任每个叶子遵守。它也无法拥有 `bin`，因此启动胶水一直在三个 `start.ts` 文件中重复。包将「ACP 应用绝不向 stdout 输出日志」从文字警告变成了产物的属性：叶子中不存在可以写错的 logger 条目。
|
||||
|
||||
## 验证
|
||||
|
||||
- 示例目录只包含配置、README 和测试：`start.ts`、基础设施前导和共享 YAML include 已移除。
|
||||
- `demo:tui`、`demo:headless` 和 `demo:acp` 调用应用包的 bin。
|
||||
- 每个新包都有 README 和逐文件 100% 覆盖率；每个应用包还有一个 keyless 的真实 Loader 路径 bin 冒烟测试，用于捕获[事后分析 0001](../../../../docs/postmortem/0001-acp-default-export-drops-inject.md) 中描述的导出形状故障。
|
||||
- ACP 回放套件通过应用包的 bin 启动，因此协议接线与组装后的后端行为都跨越真实的 Loader 边界。
|
||||
|
||||
## 后果
|
||||
|
||||
- **裸插件树的教学性。** 主干现在隐藏在 bundle 之后，查看完整树意味着打开 `dsh-agent-spine-demo`。应用包的 README 承担了这份教学职责。
|
||||
- **多了一层间接。**「这个演示加载了什么？」从扫描单个 YAML 变成了阅读一个包。
|
||||
|
||||
## 相关
|
||||
|
||||
- 取代[使共享示例基础配置与提供方无关](../../rejected/architecture/2026-06-20-providerless-example-base.md)：一旦主干移入 `dsh-agent-spine-demo` 且 `base*.yml` 文件被删除，将 `base.yml` 重命名为无提供方核心便不再有意义。
|
||||
- 基于[能力 seam](2026-06-13-capability-seams.md)的接口/实现/消费方拆分——后端和展示层保持为叶子选择；主干是共享 bundle。
|
||||
- 与[将包重组为模块化层级结构](2026-06-20-package-hierarchy.md)互补：新的 app/core 包按该层级结构归入既有分组（`core` 放可复用的主干 bundle，`ui` 放应用特有的前门）。
|
||||
- 后续的[冗余 agent 移除](../simplification/2026-07-20-remove-stdio-and-echo-agents.md)拥有最终的 TUI/Headless 拆分，并移除行式与仅 mock 的叶子。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-03-filesystem-directory-listing-seam.md: eb2650daf567d4bd98ed8553a4b743f5a01d945c
|
||||
2026-07-03-filesystem-directory-listing-seam.zh.md: 4bcda9f093f22c06348d4c69c4de3bd62f216f8e
|
||||
@@ -0,0 +1,54 @@
|
||||
# Agent Note: Add direct directory listing to the filesystem seam
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-03-filesystem-directory-listing-seam.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
`@deepseek-ai/dsh-fs` is the provider seam for filesystem access, with local and future non-local backends behind the same `ctx.fs` contract. Before this change it could resolve paths, stat targets, read text, stream text, write text, and edit text. That was enough for model-facing file tools, but not for non-model-facing consumers that need to enumerate directories without importing `node:fs`.
|
||||
|
||||
The immediate pressure came from skill loading: reading an individual `SKILL.md` can already go through `ctx.get('fs')`, but discovering which skill roots contain `<name>/SKILL.md` or `<name>.md` still needs directory enumeration. Adding directory listing only in `dsh-skill` would either keep a direct Node dependency there or invent a one-off local helper outside the filesystem provider stack.
|
||||
|
||||
This decision adds the provider capability without a model-facing `ls`/`list` tool or skill-discovery change. Those consumers require separate UX, prompt, and policy decisions.
|
||||
|
||||
## Decision
|
||||
|
||||
Add `FileSystem.listDir(target, signal?)` to `@deepseek-ai/dsh-fs`.
|
||||
|
||||
`listDir` lists one directory level only. It returns direct children in stable name order and includes:
|
||||
|
||||
- `name`: the child basename.
|
||||
- `type`: `file`, `directory`, or `other`.
|
||||
- `target`: the resolved child `FsTarget`.
|
||||
- `version`: cheap metadata when available.
|
||||
- `size`: regular-file size when available.
|
||||
|
||||
It never reads file contents. Recursive traversal, globbing, pagination, search, file watching, and model-facing rendering are intentionally out of scope.
|
||||
|
||||
The local backend implements this through `readdir({ withFileTypes: true })`, `resolveLocalTarget`, and metadata `stat`/`realpath` probes. The result order is deterministic (`name.localeCompare`) to keep prompt/listing output stable for future consumers and improve prefix-cache reuse.
|
||||
|
||||
Broken or disappeared children may be represented as `type: 'other'` without `version`/`size`; they do not abort the whole listing. Permission or backend I/O failures while listing the directory or resolving/probing child metadata fail the whole listing with structured `FsError` codes:
|
||||
|
||||
- `FS_NOT_FOUND` for missing targets.
|
||||
- `FS_NOT_DIRECTORY` for existing non-directory targets.
|
||||
- `FS_PERMISSION_DENIED` for permission failures.
|
||||
- `FS_IO_ERROR` for other backend I/O failures.
|
||||
- `FS_ABORTED` for aborted calls.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Add a model-facing list tool with the seam.** Rejected because its prompt, schema, and rendering contracts are independent of the provider primitive.
|
||||
|
||||
**Keep directory enumeration in each consumer.** Rejected. That would bind product packages such as `dsh-skill` to Node/local filesystem behavior and bypass policy/remote/sandboxed backends.
|
||||
|
||||
**Make `listDir` recursive or glob-shaped.** Rejected for now. Skill-root discovery only needs direct children, and a simple direct listing is the smallest backend contract future consumers can safely compose.
|
||||
|
||||
**Skip children that fail metadata resolution.** Rejected. The API promises resolved child targets, so permission/IO failures while resolving a child are contract failures. Broken or disappeared children are the exception because they can still be represented without claiming a live resolved file.
|
||||
|
||||
## Consequences
|
||||
|
||||
Every filesystem backend must now implement one additional provider primitive. That is deliberate foundation work while the harness is still unreleased, but it does mean future sandboxed/remote backends need to define equivalent direct-child listing behavior.
|
||||
|
||||
The capability remains provider-facing. Until a consumer lands, ACP/model sessions will still need existing tools such as `bash` for directory listing. The absence of a model-facing `listdir` tool is expected, not a wiring failure.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Agent Note: 为文件系统 seam 添加直接目录列举能力
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-03-filesystem-directory-listing-seam.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
`@deepseek-ai/dsh-fs` 是文件系统访问的提供方 seam，本地后端与未来的非本地后端共享同一个 `ctx.fs` 契约。在本次变更之前，它能解析路径、stat 目标、读取文本、流式读取文本、写入文本和编辑文本。这对面向模型的文件工具已经足够，但对于需要枚举目录而又不想直接导入 `node:fs` 的非模型侧消费方来说还不够。
|
||||
|
||||
直接的压力来自 skill（技能）加载：读取单个 `SKILL.md` 已经可以走 `ctx.get('fs')`，但发现哪些 skill 根目录包含 `<name>/SKILL.md` 或 `<name>.md` 仍需要目录枚举。如果仅在 `dsh-skill` 中添加目录列举，要么保留对 Node 的直接依赖，要么在文件系统提供方栈之外发明一个一次性的本地辅助函数。
|
||||
|
||||
本决策只添加提供方能力，不涉及面向模型的 `ls`/`list` 工具或 skill 发现机制的变更。那些消费方需要独立的 UX、提示词与策略决策。
|
||||
|
||||
## 决策
|
||||
|
||||
在 `@deepseek-ai/dsh-fs` 中添加 `FileSystem.listDir(target, signal?)`。
|
||||
|
||||
`listDir` 仅列举一层目录。它以稳定的名称顺序返回直接子项，包含以下字段：
|
||||
|
||||
- `name`：子项的 basename；
|
||||
- `type`：`file`、`directory` 或 `other`；
|
||||
- `target`：已解析的子项 `FsTarget`；
|
||||
- `version`：可用时返回的轻量元数据；
|
||||
- `size`：可用时返回的常规文件大小。
|
||||
|
||||
它从不读取文件内容。递归遍历、glob 匹配、分页、搜索、文件监听和面向模型的渲染均有意不在范围内。
|
||||
|
||||
本地后端通过 `readdir({ withFileTypes: true })`、`resolveLocalTarget` 以及元数据 `stat`/`realpath` 探测来实现。结果顺序是确定性的（`name.localeCompare`），以保持未来消费方的提示词/列表输出稳定，并提高前缀缓存复用率。
|
||||
|
||||
损坏或已消失的子项可以表示为 `type: 'other'`（不带 `version`/`size`）；它们不会中止整个列举。在列举目录或解析/探测子项元数据时遇到权限或后端 I/O 故障，则以结构化的 `FsError` 错误码使整个列举失败：
|
||||
|
||||
- `FS_NOT_FOUND`：目标不存在；
|
||||
- `FS_NOT_DIRECTORY`：目标存在但不是目录；
|
||||
- `FS_PERMISSION_DENIED`：权限不足；
|
||||
- `FS_IO_ERROR`：其他后端 I/O 故障；
|
||||
- `FS_ABORTED`：调用被中止。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**在添加 seam 的同时添加面向模型的 list 工具。** 否决。其提示词、schema 和渲染契约与提供方原语相互独立。
|
||||
|
||||
**让每个消费方自行枚举目录。** 否决。这会将 `dsh-skill` 等产品包绑定到 Node/本地文件系统行为上，绕过策略/远程/沙箱后端。
|
||||
|
||||
**让 `listDir` 支持递归或 glob 形式。** 暂时否决。skill 根发现只需要直接子项，而简单的单层列举是未来消费方可以安全组合的最小后端契约。
|
||||
|
||||
**跳过元数据解析失败的子项。** 否决。API 承诺返回已解析的子项 target，因此解析子项时的权限/IO 故障属于契约失败。损坏或已消失的子项是例外，因为它们仍可在不声称拥有一个活跃已解析文件的前提下被表示。
|
||||
|
||||
## 后果
|
||||
|
||||
每个文件系统后端现在必须多实现一个提供方原语。这是 harness 尚未发布时有意为之的基础工作，但也意味着未来的沙箱/远程后端需要定义等价的直接子项列举行为。
|
||||
|
||||
该能力仍停留在提供方层面。在消费方落地之前，ACP（Agent Client Protocol）/模型会话仍需使用 `bash` 等既有工具来列举目录。缺少面向模型的 `listdir` 工具是预期行为，而非接线错误。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-05-windows-fs-permissions.md: da3aabd872156d04e27b8b5521486e1190ac1173
|
||||
2026-07-05-windows-fs-permissions.zh.md: 8cb3e90922894f1755e8861411a36463d1ec7367
|
||||
@@ -0,0 +1,34 @@
|
||||
# Agent Note: Windows write-permission semantics — inherited DACLs, not mode bits
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-05-windows-fs-permissions.zh.md)
|
||||
|
||||
The replacement-file decision in this record is superseded by [Windows DACL preservation](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md).
|
||||
|
||||
## Problem
|
||||
|
||||
`writeFileAtomic` in `@deepseek-ai/dsh-fs-local` protects write-in-progress content with POSIX mode bits: the staging directory is created `0o700`, the temp file is opened `0o600`, and new files default to `0o600`. On POSIX this keeps temporary content owner-only regardless of the parent directory's permissions.
|
||||
|
||||
Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL: a newly created file or directory inherits from its parent, while replacement needs the explicit handling owned by the superseding Agent Note.
|
||||
|
||||
## Decision
|
||||
|
||||
New Windows files use directory inheritance rather than synthetic mode bits: the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit the destination directory's DACL. Replacement files follow the stricter [DACL preservation contract](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md).
|
||||
|
||||
Tests assert mode bits on POSIX only. Native Windows coverage pins the package-owned replacement behavior; new-file inheritance remains an operating-system contract rather than a machine-specific ACL allowlist.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Explicit owner-only DACLs for new files.** Rejected because they would break inheritance and surprise users whose project directories are deliberately shared. Replacement writes copy the target's existing DACL rather than inventing an owner-only policy.
|
||||
|
||||
**Test-side ACL verification.** A `Get-Acl` SID allowlist or `icacls` would verify Windows inheritance and the machine's `%TEMP%` ACL rather than package behavior; `icacls` also localizes well-known account names, making parsing locale-fragile.
|
||||
|
||||
**Skip `chmod` on Windows.** Platform-guarding benign no-op calls adds branches without changing behavior.
|
||||
|
||||
## Consequences
|
||||
|
||||
POSIX keeps owner-only temp content regardless of the parent directory. A new Windows target inside a broadly accessible directory inherits that accessibility by design; a replacement retains the target's narrower DACL when one exists.
|
||||
|
||||
Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced there because publication fails before the synthetic mode would matter.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Agent Note: Windows 写入权限语义：继承 DACL，而非权限模式位
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-05-windows-fs-permissions.md) | 中文
|
||||
|
||||
本记录中关于替换文件的决策已由 [Windows DACL 保留机制](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)取代。
|
||||
|
||||
## 问题
|
||||
|
||||
`writeFileAtomic` 在 `@deepseek-ai/dsh-fs-local` 中使用 POSIX 权限模式位保护正在写入的内容：以 `0o700` 创建暂存目录，以 `0o600` 打开临时文件，新文件也默认使用 `0o600`。在 POSIX 上，无论父目录的权限如何，这些设置都能保证临时内容仅对所有者可见。
|
||||
|
||||
Windows 在同一 API 背后没有可用的对等机制。Node 的 `chmod` 在 Windows 上只会驱动只读属性（此包传入的每种模式都包含所有者写权限，因此这些调用是无害的空操作），`stat().mode` 则报告合成的 `0o666`/`0o444` 权限位。真正的安全状态由文件的 DACL 决定：新建文件或目录会从父目录继承，替换操作则需要由取代本文的 Agent Note 所定义的显式处理。
|
||||
|
||||
## 决策
|
||||
|
||||
Windows 新建文件使用目录继承，而不使用合成的权限模式位：暂存目录在目标的父目录（`dirname(absolutePath)`）内创建，因此它和临时文件都会继承目标目录的 DACL。替换文件遵循更严格的 [DACL 保留契约](../bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)。
|
||||
|
||||
测试仅在 POSIX 上断言权限模式位。Windows 原生覆盖率锁定由本包（package）负责的替换行为；新文件继承仍属于操作系统契约，而不是针对特定机器的 ACL 允许清单。
|
||||
|
||||
## 备选方案
|
||||
|
||||
**为新文件显式设置仅所有者可用的 DACL。** 不予采纳，因为这会破坏继承，也会使特意共享项目目录的用户感到意外。替换写入会复制目标现有的 DACL，而不会自行设计仅所有者可用的策略。
|
||||
|
||||
**在测试中验证 ACL。** `Get-Acl` SID 允许清单或 `icacls` 验证的是 Windows 继承机制以及当前机器的 `%TEMP%` ACL，而非包的行为；`icacls` 还会对知名账户名进行本地化，导致解析容易受语言区域影响。
|
||||
|
||||
**在 Windows 上跳过 `chmod`。** 为无害的空操作调用增加平台守卫分支，不会改变任何行为。
|
||||
|
||||
## 后果
|
||||
|
||||
无论父目录的权限如何，POSIX 都会继续将临时内容限制为仅所有者可用。Windows 中的新目标如果位于广泛可访问的目录内，将按设计继承这种可访问性；如果替换目标存在更严格的 DACL，则会保留该 DACL。
|
||||
|
||||
在 Windows 上，替换时的模式保留会退化为空操作：可写文件的探测结果为 `0o666`，通过 `chmod` 重放该模式会使只读属性继续保持清除状态。由于发布操作会在合成模式发挥作用前失败，Windows 上无法替换只读目标。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-23-unified-session-query-service.md: f69836f60dfd73f9d8490687294b8407e53e9b32
|
||||
2026-07-23-unified-session-query-service.zh.md: bf25f4337dc8696ae54ffb16a7dd74437d45858b
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: Unified session query service
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-23-unified-session-query-service.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Exact reads, semantic filters, relationship traces, and full-text search operate on the same live-preferred session corpus. Exposing full-text search under a second context key makes consumers and app compositions treat one capability as two services, even though the SQLite implementation is the only backend-specific part.
|
||||
|
||||
The interface package already owns the shared record, filter, trace, search-request, cursor, and error contracts. A provider registry or coordinator would add runtime selection semantics unsupported by any current consumer.
|
||||
|
||||
## Decision
|
||||
|
||||
`SessionQueryService` is the single abstract service registered as `ctx.sessionQuery`. It concretely implements listing, title and event reads, surface reads, filtering, and relationship tracing through its backend-independent `SessionCorpus`. Its only abstract methods are `searchSessions()` and `searchEvents()`.
|
||||
|
||||
`SessionQuerySqlite` extends that service and is the sole concrete backend. One mounted instance therefore exposes every operation through `ctx.sessionQuery`; its inherited exact operations use the shared corpus implementation, while its SQLite-owned lifecycle observes sources, reconciles the derived FTS index, ranks matches, and owns cursor generations. The interface package has no standalone concrete plugin, search-provider registry, or second context key.
|
||||
|
||||
SQLite reconciliation is one quiescent serialized state machine. It passes the caller's exact abort signal into durable snapshot listing and inspection, awaits each started backend operation itself, and checks cancellation after every await and before starting the next source or index operation. Cancellation therefore cannot release the serializer while an ignored or cooperative backend call is still cleaning up, and it cannot start a subsequent listing, inspection, reconciliation, or query after the signal is observed.
|
||||
|
||||
Backend configuration includes the inherited `readWindowMax` setting alongside its own index path, journal mode, page limits, and snippet limit. First-party apps that need session queries mount the SQLite backend and place its disposable index beside their configured persistence root.
|
||||
|
||||
This service topology supersedes the separate-key portion of the [exact query decision](../feature/2026-07-10-session-query-service.md) and [SQLite search decision](../feature/2026-07-10-sqlite-session-query-provider.md); their corpus, query, tokenizer, reconciliation, and safety decisions remain in force.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Keep `ctx.sessionQuery` and `ctx.sessionSearch` separate** — rejected because both expose operations over one logical corpus, force consumers to discover two keys, and let apps accidentally mount only a partial query surface.
|
||||
- **Keep a concrete base service and let the SQLite plugin register or mutate two search methods** — rejected because method availability would depend on plugin order and teardown, and the service would need a provider registration protocol for one implementation.
|
||||
- **Move every query implementation into the SQLite package** — rejected because exact reads, filters, and traces require no index and are shared behavior that belongs with their provider-independent contracts.
|
||||
|
||||
## Consequences
|
||||
|
||||
Consumers inject one service and can combine exact and full-text operations without a second capability lookup. A production composition must choose a concrete backend even when one consumer currently calls only inherited exact methods; tests may use a minimal subclass when backend behavior is outside their scope.
|
||||
|
||||
The unified object deliberately retains two internal observation strategies: exact operations read authoritative live/persisted sources per call, while full-text operations reconcile a disposable index. Sharing the context key does not make the derived index authoritative or couple exact-read availability to an FTS query.
|
||||
|
||||
Queued cancellation remains prompt. Cancellation during active asynchronous source observation waits for that started operation to settle, which makes rejection a quiescence boundary and preserves single-file execution for a following search. Synchronous SQLite statements remain non-preemptible and are bracketed by signal checks.
|
||||
|
||||
Unit coverage pins inherited and abstract behavior on one key, SQLite coverage exercises both operation families on the concrete backend, and the real Loader path verifies that one exported plugin registers the combined service.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: 统一会话查询服务
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-23-unified-session-query-service.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
精确读取、语义过滤、关系追踪与全文搜索都作用于同一个实时源优先的会话语料库。将全文搜索暴露在第二个上下文键下，会让消费方与应用组合把同一项查询功能视为两个服务，尽管只有 SQLite 实现是后端特有的部分。
|
||||
|
||||
接口包已经拥有共享的记录、过滤、追踪、搜索请求、游标与错误契约。提供方注册表或协调器会引入运行时选择语义，而目前没有任何消费方支持这种语义。
|
||||
|
||||
## 决策
|
||||
|
||||
`SessionQueryService` 是注册为 `ctx.sessionQuery` 的唯一抽象服务。它通过后端无关的 `SessionCorpus` 具体实现列表查询、标题与事件读取、表层读取、过滤和关系追踪。仅有 `searchSessions()` 与 `searchEvents()` 两个方法为抽象方法。
|
||||
|
||||
`SessionQuerySqlite` 扩展该服务，并且是唯一的具体后端。因此，一个挂载实例便可通过 `ctx.sessionQuery` 暴露全部操作；其继承的精确操作使用共享的语料库实现，而由 SQLite 管理的生命周期负责观察数据源、对齐派生 FTS 索引、对匹配项排序并管理游标代际。接口包不提供独立的具体插件、搜索提供方注册表或第二个上下文键。
|
||||
|
||||
SQLite 的对齐过程是一个具备静止性保证的串行状态机。它将调用方的原始中止信号传给持久化快照列表与检查操作，直接等待每个已经启动的后端操作，并在每次等待后以及启动下一个数据源或索引操作前检查是否已取消。因此，即使后端忽略取消或正在配合清理，串行器也不会提前释放；观察到中止信号后，也不会再启动后续的列表、检查、对齐或查询操作。
|
||||
|
||||
后端配置除了自身的索引路径、日志模式、分页限制与文本片段长度上限外，还包含继承的 `readWindowMax` 设置。需要会话查询的第一方应用挂载 SQLite 后端，并将其可丢弃索引放在已配置的持久化根目录旁。
|
||||
|
||||
这一服务拓扑取代了[精确查询决策](../feature/2026-07-10-session-query-service.md)和 [SQLite 搜索决策](../feature/2026-07-10-sqlite-session-query-provider.md)中关于分离上下文键的部分；其中关于语料库、查询、分词器、对齐与安全性的决策仍然有效。
|
||||
|
||||
## 已考虑的替代方案
|
||||
|
||||
- **保留相互独立的 `ctx.sessionQuery` 与 `ctx.sessionSearch`**：不予采纳，因为二者都针对同一逻辑语料库提供操作，迫使消费方识别两个键，还可能让应用误挂载一组不完整的查询接口。
|
||||
- **保留具体的基础服务，再由 SQLite 插件注册或修改两个搜索方法**：不予采纳，因为方法是否可用将取决于插件顺序与资源释放时机，而且该服务需要为唯一的实现定义一套提供方注册协议。
|
||||
- **将所有查询实现移入 SQLite 包**：不予采纳，因为精确读取、过滤与追踪不需要索引，并且都属于应与提供方无关契约放在一起的共享行为。
|
||||
|
||||
## 后果
|
||||
|
||||
消费方只需注入一个服务，无需再次查找其他功能，便可组合精确操作与全文操作。生产环境的组合必须选择一个具体后端，即使当前某个消费方只调用继承的精确方法；如果后端行为不在测试范围内，测试可以使用最小子类。
|
||||
|
||||
统一后的对象有意保留两种内部观察策略：精确操作在每次调用时读取权威的实时源或持久化源，全文操作则使可丢弃索引与数据源对齐。共用上下文键不会让派生索引成为权威来源，也不会使精确读取的可用性依赖 FTS 查询。
|
||||
|
||||
排队阶段的取消仍会及时生效。在异步数据源观察已经开始后取消时，调用方会等待该操作完成清理后才收到拒绝；因此拒绝本身构成静止边界，并保证后续搜索仍按单一串行流程执行。同步 SQLite 语句无法在执行中被抢占，服务会在其前后检查中止信号。
|
||||
|
||||
单元测试在同一个键上同时固定继承实现与抽象方法的契约，SQLite 测试在具体后端上覆盖两类操作，真实 Loader 路径则验证单个导出的插件能够注册组合后的服务。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-24-dsh-commander-argument-adapter.md: a5f6e580b91c0de1cdb433e1973bdff960384f06
|
||||
2026-07-24-dsh-commander-argument-adapter.zh.md: 4321ab154996c9b23ce58175b112234c92013cb8
|
||||
@@ -0,0 +1,54 @@
|
||||
# Agent Note: Parse `dsh` argv through one Commander adapter
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-24-dsh-commander-argument-adapter.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The `dsh` CLI entry (`apps/cli`) parsed argv in three hand-rolled idioms that did not compose and gave no `--help`/`--version`. `bin.ts` dispatched by raw inspection — `argv[0] === 'web'`, then `argv.includes('-p') || argv.includes('--prompt')`, else TUI — which is positional-blind: a prompt flag or a config path in the wrong position could misroute the mode, and `argv.includes('-p')` could not tell a real flag from an incidental token. `headless.ts` and `web.ts` each ran their own `node:util` `parseArgs` with inline host/port validation, and `dsh-app-boot` carried `parseResumeArg`, a ~30-line bespoke scanner reimplementing flag/`=`-form/value/repeat handling for `--resume`. Usage was a single hardcoded `usage: dsh -p "task"` line; there was no version flag and no rendered help.
|
||||
|
||||
## Decision
|
||||
|
||||
Argv is parsed once, in `apps/cli/src/args.ts`, through a Commander adapter (the same parser the SDK bins — `create-sdk`, `dsh-scripts` — already standardize on). `parseDshArgs(argv, version)` returns a discriminated `DshInvocation` union of the three real modes: `{ mode: 'tui', config?, resume? }`, `{ mode: 'headless', prompt }`, or `{ mode: 'web', host?, port?, dev }`. It does **not** model help/version/errors as data: Commander owns those, printing usage or the diagnostic and exiting at the point of failure. `exitOverride()` turns each into a thrown `CommanderError` carrying the intended code (0 for help/version, 1 for a parse or domain error), which one `try/catch` in `parseDshArgs` turns into `process.exit`.
|
||||
|
||||
`bin.ts` calls the adapter once and switches on `mode` (closed union, `satisfies never` default), dynamic-importing only the chosen mode's module; only a valid, non-help invocation reaches the switch, so it has no help/version/error cases. Each mode module consumes already-parsed values: `runTui(config, resume)`, `runHeadless(task)`, `runWeb(host, port, dev, workspaceRoot)` — none re-reads argv. It is **one Commander program**: the default surface (no subcommand) carries option-only flags — `--config <path>`, `-p/--prompt <task>`, `--resume <id>` — and `web` is a real `program.command('web')` subcommand. The default surface takes no positional argument, which is what lets `web` be a real subcommand without a positional collision, so `dsh --help` lists `web` natively (no hand-pasted command text). The default action and the `web` action set the resolved mode, then bail via `command.error(...)` (print + exit 1) on the domain checks Commander cannot express: `--prompt` selects headless and rejects an empty task or a `--config`/`--resume` alongside it rather than silently dropping a TUI input; an empty `--resume=` id fails loud (agent-loop treats `''` as no-resume). Commander parses the default-surface options on either side of the `web` token into `program.opts()`; since `web` shares none of them, the `web` action rejects a leaked `--config`/`-p`/`--resume` (`dsh web -p x`, `dsh --config c.yml web`) rather than silently serving and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the adapter assigns no default and does no validation, only `Number`-coercing the port string (the schema wants a number). The `dsh-host-webserver` schemastery `Config` (`host` a `127.0.0.1`/`0.0.0.0` literal union, `port` a natural ≤ 65535) is the single source of both the default (the shipped `apps/cli/cordis.yml` `webserver` row stands when a flag is absent) and validity — `AppCLIEntry` patches an explicit flag straight into that row, so a bad host/port fails loud at the schema on boot, not at parse. `--dev` mounts the client HMR driver and bundle watch, and `--workspace-root <path>` is a plain pass-through to `AppCLIEntry` (the parent directory for name-created workspaces). A repeated `--resume`, or a following flag captured as a `--resume`/`--prompt` value, is Commander's standard behavior (last-wins / next-token) and is left alone; a bad id fails loud downstream when the session cannot load. `--version` reads this app's `package.json`.
|
||||
|
||||
`dsh` takes no positional argument. `--config <path>` names an alternate cordis tree to boot instead of the shipped default; it exists only so the demo/test call sites (`demo:cordis`, `demo:code-mode`, the keyless PTY smokes) can point the shipped bin at an example tree. A bare `dsh` boots the shipped tree plus the `~/.dsh/config.yaml` personal overlay; a real user never passes `--config`.
|
||||
|
||||
CLI parsing lives entirely in `apps/cli`. `dsh-app-boot` holds the boot/env/config/personal-overlay helpers and no argv scanner.
|
||||
|
||||
## Session resume through the boot context
|
||||
|
||||
`dsh --resume <id>` is the one way to resume a persisted session, with no environment variable. `runTui` provides the parsed id on the boot context through `boot`'s `prepare(ctx)` hook — `ctx.provide(RESUME_SESSION_ID_KEY, id)` (a `dsh-app-boot` export, value `'resumeSessionId'`) — and the shipped tui-agent/cordis configs read it as a bare identifier: `resumeSessionId: !!js "typeof resumeSessionId === 'string' ? resumeSessionId : undefined"`. The expression is quoted because YAML otherwise parses the `?`/`:` as a mapping; the `typeof` guard tolerates a launcher that never provides the slot. The `/resume` in-place handoff (`process.execve`) rebuilds its re-exec argv from the parsed values as `dsh --resume=<id> [--config <path>]`.
|
||||
|
||||
## One terminal front door: `dsh`
|
||||
|
||||
`dsh` is the only terminal entry point; the `dsh-tui-demo` package ships the TUI app bundle plugin the shipped config mounts, and no bin of its own. `demo:cordis`, `demo:code-mode`, and both the tui-agent and cordis-agent keyless PTY smokes launch through `apps/cli/src/bin.ts` with `--config <path>`. `dsh`'s TTY guard (refuse piped stdio before booting, pointing at `dsh -p` for automation) is pinned by `apps/cli/tests/built-bin.e2e.ts`, which runs the built `lib/bin.js` under plain Node with piped stdio (`apps/cli/tests` is in the e2e vitest include). `cli-demo`, `acp-demo`, and `jsonrpc-demo` keep their own bins because each is a distinct surface (headless, ACP, JSON-RPC) `dsh` does not provide.
|
||||
|
||||
## Package topology
|
||||
|
||||
The argument surface stays inside `apps/cli`, the assembly tier, not a `packages/*` library: it is this one app's routing, not a reusable seam. `dsh-app-boot` shrinks to boot glue with no CLI-parsing responsibility. `commander@^15` is added to `apps/cli/package.json`, matching the SDK bins' pin.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep `node:util` `parseArgs` and only unify the dispatch** — rejected: `parseArgs` has no subcommand model, no rendered help, and no version flag, so `web` routing and `--help`/`--version` would stay hand-rolled. The repo already chose Commander for its other CLIs; a second parser idiom for `dsh` alone is the fragmentation this change removes.
|
||||
|
||||
**Keep `parseResumeArg` as a shared helper and feed it Commander's residual args** — rejected: the whole point is to retire the bespoke scanner. Commander parses `--resume` (space and `=` forms, missing-value, position-independence) natively; keeping a parallel hand-written path for the one flag would preserve the duplication the change exists to end.
|
||||
|
||||
**A bare `dsh <config>` positional for the alternate tree** — rejected: a root positional and a real `web` subcommand cannot coexist in one Commander program (the subcommand claims the first positional). A positional would force `web` into a reserved-first-token dispatch to a separate parser and a hand-maintained `web` line in `--help`. Only the demo/test sites ever need to name an alternate tree, so a `--config` flag serves them while leaving the default surface positional-free — `web` is then a normal subcommand in one program with native `--help`.
|
||||
|
||||
**Make the argument surface a `packages/*` seam** — rejected: nothing outside `dsh` consumes it, and capability seams are not split preemptively. The Commander adapter is `apps/cli`'s own concern.
|
||||
|
||||
**Keep `RESUME_SESSION_ID` as the resume bridge** — rejected: with `--resume` parsed into a value the bin already holds, threading it through an environment variable the config re-reads is indirection with no benefit, and it left the demo bin a second, env-only resume path. Providing the id on the boot context is the same channel `boot`'s `prepare` hook already uses for `tuiResumeHost`.
|
||||
|
||||
**Keep the `dsh-tui-demo` bin** — rejected: it duplicated `dsh --config <path>` exactly, and keeping it forced the demo-only `RESUME_SESSION_ID` fallback to stay alive. Its plugin is what the configs actually mount; only the front-door bin was redundant, and `dsh` is the one terminal entry point.
|
||||
|
||||
## Testing
|
||||
|
||||
`apps/cli/tests/args.spec.ts` (new; `apps/*/tests` added to the vitest include and `apps/cli/tests` to `tsconfig.host.json`) covers the adapter at the level that matters: mode routing by shape (including `web --dev` and the host/port pass-through), the exit-code behavior for the adapter's fail-loud checks (empty resume/prompt, `--prompt` mixed with a config/`--resume`, unknown option, stray positional), and `--help`/`--version`, captured through a `process.exit` spy. Host/port validity is the webserver schema's job, exercised on boot by the web smoke, not the adapter spec. Both PTY smoke groups in `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` now drive the real `apps/cli/src/bin.ts`: the `tui-agent` group boots an example tree through `--config`, and the `dsh CLI` group covers default boot, personal overlay, invalid config, the `--resume` config intake, the `process.execve` in-place resume handoff, and the source-path prompt. `examples/cordis-agent/tests/keyless-smoke.e2e.ts` likewise launches through `dsh`. `packages/ui/app-boot/tests/app-boot.spec.ts` drops its `parseResumeArg`/`replaceResumeArg` blocks; the TUI unit and snapshot fixtures use the `dsh --resume {session}` resume command.
|
||||
|
||||
## Consequences
|
||||
|
||||
`dsh` has rendered `--help`/`--version` and consistent fail-loud parse errors, and mode routing does not depend on flag position. Argv parsing lives in one place with one parser idiom shared with the SDK bins, at the cost of a `commander` dependency on `apps/cli` and Commander's parse semantics (its error strings, its `exitOverride` contract) sitting on the CLI's front door. `dsh-app-boot` owns no CLI-parsing surface; a consumer needing `--resume`-style parsing composes Commander. Session resume rides the boot context rather than an environment variable, and `dsh` is the single terminal front door — the `dsh-tui-demo` package is a plugin bundle a config mounts.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Agent Note: 通过单个 Commander 适配器解析 `dsh` 的 argv
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-24-dsh-commander-argument-adapter.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
`dsh` 的 CLI（命令行界面）入口（`apps/cli`）以三种手写方式解析 argv，这些方式无法组合，也不提供 `--help`/`--version`。`bin.ts` 通过原始检查进行分发：先判断 `argv[0] === 'web'`，再判断 `argv.includes('-p') || argv.includes('--prompt')`，否则走 TUI。这种方式对位置不敏感：位置错误的 prompt 标志或配置路径可能把模式路由错，而 `argv.includes('-p')` 无法区分真正的标志和偶然出现的 token。`headless.ts` 和 `web.ts` 各自运行自己的 `node:util` `parseArgs`，并内联校验 host/port，而 `dsh-app-boot` 携带 `parseResumeArg`——一个约 30 行的定制扫描器，为 `--resume` 重新实现了标志、`=` 形式、取值和重复的处理。用法说明只有一行硬编码的 `usage: dsh -p "task"`；既没有版本标志，也没有渲染出的帮助信息。
|
||||
|
||||
## 决策
|
||||
|
||||
argv 只在 `apps/cli/src/args.ts` 中解析一次，并使用 Commander 适配器（SDK bin `create-sdk`、`dsh-scripts` 已经统一采用的同一解析器）。`parseDshArgs(argv, version)` 返回仅包含三种实际模式的判别式 `DshInvocation` 联合类型：`{ mode: 'tui', config?, resume? }`、`{ mode: 'headless', prompt }` 或 `{ mode: 'web', host?, port?, dev }`。它**不会**将帮助、版本信息或错误建模为数据：这些情况由 Commander 处理，在触发处打印用法或诊断信息并退出。`exitOverride()` 会将每种情况转为抛出的 `CommanderError`，并携带预期退出码（帮助或版本为 0，解析错误或领域错误为 1）；唯一一处 `try/catch` 位于 `parseDshArgs` 中，捕获错误后调用 `process.exit`。
|
||||
|
||||
`bin.ts` 只调用适配器一次，并对 `mode` 做分支切换（封闭联合类型，默认分支为 `satisfies never`），仅动态导入所选模式对应的模块；只有合法的非帮助请求才会进入这段分支逻辑，因此其中没有帮助、版本或错误分支。每个模式模块只消费已解析好的值：`runTui(config, resume)`、`runHeadless(task)`、`runWeb(host, port, dev, workspaceRoot)`，都不会再次读取 argv。整个 CLI 由**单个 Commander 程序**实现：默认接口（不使用子命令时）只包含选项标志——`--config <path>`、`-p/--prompt <task>`、`--resume <id>`——而 `web` 是通过 `program.command('web')` 定义的真正子命令。默认接口不接受位置参数，因此 `web` 可以成为真正的子命令且不会发生位置参数冲突，`dsh --help` 也会原生列出 `web`，无需手工拼接命令文本。默认命令和 `web` 子命令的处理函数会设置解析得到的模式，随后对 Commander 无法表达的领域校验调用 `command.error(...)` 立即终止（打印信息并以退出码 1 退出）：`--prompt` 选择 headless 模式；如果任务为空，或调用中还包含 `--config` 或 `--resume`，它会拒绝调用，而不会静默丢弃 TUI 输入；空的 `--resume=` id 会显式失败（agent-loop 把 `''` 视为不恢复）。Commander 会将 `web` token 前后的默认接口选项都解析进 `program.opts()`；由于 `web` 不与默认接口共用任何选项，`web` 子命令的处理函数会拒绝误入的 `--config`/`-p`/`--resume`（`dsh web -p x`、`dsh --config c.yml web`），而不是静默启动服务并丢弃这些选项。`dsh web` 的 `--host`/`--port` 是未经校验、直接透传的覆盖值：适配器既不设置默认值，也不执行校验，只使用 `Number` 将端口字符串转换为数字（schema 要求该值为数字）。`dsh-host-webserver` 的 schemastery `Config`（`host` 是 `127.0.0.1`/`0.0.0.0` 字面量联合类型，`port` 是不大于 65535 的自然数）是默认值与有效性的唯一真源：未提供标志时，随产品提供的 `apps/cli/cordis.yml` 中 `webserver` 配置项保持原值；`AppCLIEntry` 将显式标志的值直接写入该配置项，因此无效的 host/port 会在启动时触发 schema 校验并显式失败，而不是在参数解析阶段失败。`--dev` 会挂载客户端 HMR（热模块替换）驱动，并启用构建产物监视，`--workspace-root <path>` 则是直接透传给 `AppCLIEntry` 的选项（按名称创建 workspace 时使用的父目录）。重复提供 `--resume`，或后续标志被捕获为 `--resume` 或 `--prompt` 的值，都是 Commander 的标准行为（最后一次取值生效／将下一 token 作为值），本适配器不作干预；无效 id 会在下游无法加载会话时显式失败。`--version` 读取本应用的 `package.json`。
|
||||
|
||||
`dsh` 不接受位置参数。`--config <path>` 指定一份替代 Cordis 配置树，系统启动该配置树而不是随产品提供的默认配置树；该标志仅用于让演示和测试调用点（`demo:cordis`、`demo:code-mode`、无密钥 PTY 冒烟测试）通过随产品提供的 bin 启动一份示例树。直接运行 `dsh` 会启动随产品提供的配置树，并叠加 `~/.dsh/config.yaml` 个人覆盖；实际用户从不传入 `--config`。
|
||||
|
||||
CLI 解析完全位于 `apps/cli` 中。`dsh-app-boot` 提供启动、环境变量、配置和个人覆盖辅助函数，不包含 argv 扫描器。
|
||||
|
||||
## 通过启动上下文恢复会话
|
||||
|
||||
`dsh --resume <id>` 是恢复持久化会话的唯一方式，无需环境变量。`runTui` 通过 `boot` 的 `prepare(ctx)` 钩子，在启动上下文中提供已解析的 id：`ctx.provide(RESUME_SESSION_ID_KEY, id)`（`dsh-app-boot` 的一项导出，值为 `'resumeSessionId'`）；随产品提供的 tui-agent/cordis 配置将该值作为裸标识符读取：`resumeSessionId: !!js "typeof resumeSessionId === 'string' ? resumeSessionId : undefined"`。这个表达式需要加引号，否则 YAML 会把 `?` 和 `:` 解析为映射；`typeof` 守卫使从未提供该槽位的启动器也能正常运行。`/resume` 原地交接（`process.execve`）根据已解析的值将重新执行时的 argv 构造成 `dsh --resume=<id> [--config <path>]`。
|
||||
|
||||
## 唯一的终端入口：`dsh`
|
||||
|
||||
`dsh` 是唯一的终端入口；`dsh-tui-demo` 包（package）提供 TUI 应用组合插件，随产品提供的配置会挂载该插件，而该包不提供自己的 bin。`demo:cordis`、`demo:code-mode` 以及 tui-agent 和 cordis-agent 的无密钥 PTY 冒烟测试都通过 `apps/cli/src/bin.ts` 启动，并传入 `--config <path>`。`dsh` 的 TTY 守卫会在启动前拒绝标准输入输出接入管道的调用，并提示自动化场景使用 `dsh -p`；`apps/cli/tests/built-bin.e2e.ts` 锁定了这一行为：该测试将标准输入输出接入管道，并通过普通 Node 运行构建后的 `lib/bin.js`（e2e Vitest 的 include 包含 `apps/cli/tests`）。`cli-demo`、`acp-demo` 和 `jsonrpc-demo` 保留各自的 bin，因为它们分别提供 `dsh` 所没有的独立接口（headless、ACP（Agent Client Protocol）、JSON-RPC）。
|
||||
|
||||
## 包拓扑
|
||||
|
||||
参数解析留在 `apps/cli`（组装层）内，而不是 `packages/*` 库中：它是这一个应用自身的路由，而非可复用的 seam。`dsh-app-boot` 收缩为纯粹的 boot 胶水代码，不再承担 CLI 解析职责。`commander@^15` 被加入 `apps/cli/package.json`，与 SDK bin 锁定的版本一致。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**保留 `node:util` `parseArgs`，只统一分发。** 已否决：`parseArgs` 没有子命令模型、没有渲染出的帮助、也没有版本标志，因此 `web` 路由和 `--help`/`--version` 仍将保持手写。本仓库其他 CLI 已经选择了 Commander；单独为 `dsh` 引入第二套解析器方式，正是这次变更要消除的碎片化。
|
||||
|
||||
**保留 `parseResumeArg` 作为共享辅助函数，并向它喂入 Commander 的残余参数。** 已否决：整件事的核心就是要退役这个定制扫描器。Commander 原生解析 `--resume`（空格和 `=` 形式、缺值、位置无关性）；为这一个标志保留一条平行的手写路径，只会保留这次变更要终结的重复。
|
||||
|
||||
**使用裸 `dsh <config>` 位置参数指定替代配置树。** 已否决：根级位置参数与真正的 `web` 子命令无法在同一个 Commander 程序中共存（子命令会占用第一个位置参数）。位置参数会迫使系统把位于首位的 `web` 作为保留 token 分发给另一个解析器，并手工维护一行 `web` 文本，供 `--help` 显示。只有演示和测试调用点需要指定替代配置树，因此 `--config` 标志既能满足这些调用点，又能让默认接口不包含位置参数；这样，`web` 就能在单个程序中成为普通子命令，并由原生 `--help` 展示。
|
||||
|
||||
**把参数解析做成 `packages/*` 的 seam。** 已否决：`dsh` 之外没有任何消费方使用它，而能力 seam 不应被提前拆分。这个 Commander 适配器是 `apps/cli` 自身的事务。
|
||||
|
||||
**保留 `RESUME_SESSION_ID` 作为恢复通道**：不予采纳。`--resume` 已被解析成 bin 当前持有的值；若再通过环境变量传递并由配置重新读取，只会引入无益的间接层，还会使演示 bin 保留第二条仅依赖环境变量的恢复路径。在启动上下文中提供 id，与 `boot` 的 `prepare` 钩子为 `tuiResumeHost` 提供值所采用的是同一通道。
|
||||
|
||||
**保留 `dsh-tui-demo` bin**：不予采纳。它与 `dsh --config <path>` 的功能完全重复；保留它还会迫使演示专用的 `RESUME_SESSION_ID` 回退路径继续存在。配置实际挂载的是该包的插件；冗余的只有作为终端入口的 bin，而 `dsh` 是唯一的终端入口。
|
||||
|
||||
## 测试
|
||||
|
||||
`apps/cli/tests/args.spec.ts`（新增；`apps/*/tests` 加入 vitest include，`apps/cli/tests` 加入 `tsconfig.host.json`）覆盖适配器的关键行为：根据参数形态进行模式路由（包括 `web --dev` 和 host/port 透传），并通过 `process.exit` spy 捕获适配器的显式报错检查（恢复 id 或提示词为空、`--prompt` 与配置或 `--resume` 混用、未知选项、多余的位置参数）以及 `--help`/`--version` 的退出码。host/port 的有效性由 webserver schema 负责，并由 web 冒烟测试在启动时验证，不属于适配器测试的覆盖范围。`examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 中的两组 PTY 冒烟测试现在都驱动真实的 `apps/cli/src/bin.ts`：`tui-agent` 组通过 `--config` 启动示例树，`dsh CLI` 组覆盖默认启动、个人覆盖、无效配置、配置对 `--resume` 的接收、通过 `process.execve` 原地恢复交接，以及包含源码路径的系统提示词。`examples/cordis-agent/tests/keyless-smoke.e2e.ts` 同样通过 `dsh` 启动。`packages/ui/app-boot/tests/app-boot.spec.ts` 移除其 `parseResumeArg` 和 `replaceResumeArg` 测试块；TUI 单元测试和快照 fixture（测试前置数据）使用 `dsh --resume {session}` 恢复命令。
|
||||
|
||||
## 影响
|
||||
|
||||
`dsh` 会渲染 `--help`/`--version`，并以一致方式显式报告解析错误；模式路由不依赖标志位置。argv 解析集中在一处，并与 SDK bin 共用一套解析器方式，代价是 `apps/cli` 依赖 `commander`，且 Commander 的解析语义（错误字符串和 `exitOverride` 契约）成为 CLI 入口的一部分。`dsh-app-boot` 不提供任何 CLI 解析接口；需要 `--resume` 式解析的消费方通过组合 Commander 来实现。会话恢复通过启动上下文完成，而不使用环境变量；`dsh` 是唯一的终端入口；`dsh-tui-demo` 包是由配置挂载的插件组合包。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-20-code-mode-result-card-completeness.md: aff755e40b238e7ee448013fe0063bb26450fffe
|
||||
2026-07-20-code-mode-result-card-completeness.zh.md: 275e870c4be73e1adaa485f4e9fb979054fbf7c2
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: Keep the Code Mode result card complete
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-20-code-mode-result-card-completeness.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The outer `run_code` tool persisted complete rendered content, but its UI presenter ignored that content and rebuilt the card body from a logs-only `presentationMeta` projection. A result-only run appeared correct because an empty presenter body let consumers fall back to `tool/result.content`. Once the program emitted a log, the presenter supplied non-empty content, that fallback stopped, and the returned value disappeared from the completed card. A spill policy's final head/tail preview was vulnerable to the same split ownership whenever captured logs made the stale projection non-empty.
|
||||
|
||||
Nested Code calls never owned cards, so producing metadata for the outer call solely to reconstruct one incomplete card also obscured the intended one-card boundary.
|
||||
|
||||
## Decision
|
||||
|
||||
The canonical tool registry pipeline owns the final model-facing outer content. On success, the `run_code` output renderer renders captured logs followed by the return value or the explicit no-output marker. Runtime failures and pre-execution policy denials are normalized into error content by `ToolRegistry` without invoking that renderer. A post-execute block runs after successful rendering and replaces the result with error content; other post-execute policy and spill decisions may replace content before persistence.
|
||||
|
||||
`run_code` omits `presentResult`. The established generic result fallback keeps the pending program title and renders the raw final `tool/result.content`; that durable, replayable, post-policy projection is the card's only result-content source. The host API proxy therefore omits a separate result view instead of serializing the same content in both `event.data.content` and `view.view.content`. The redundant logs-only `presentationMeta` projection remains removed.
|
||||
|
||||
Nested dispatch remains unchanged. Calls marked by `exec.parent` emit `tool/code-dispatch` events (full rendered content) but no `tool/call` or `tool/result` surface cards, so one outer `run_code` invocation still produces exactly one card.
|
||||
|
||||
## Testing
|
||||
|
||||
Tool unit coverage drives logs-only, result-only, logs-plus-result, no-output, spilled-result, and failure outcomes through the canonical registry, then pins the durable content and absence of a result presenter. A host-mux regression uses a call-only presenter to prove the result frame carries raw content exactly once and no view. These cases prove stale metadata cannot replace final content without making the host duplicate that content.
|
||||
|
||||
The keyless ACP backend and TUI Code Mode snapshots execute one outer program that performs two nested bash calls, logs `captured output`, and returns `CODE_ONE+CODE_TWO`. The persisted ACP log pins the complete result; the TUI surface shows one completed outer card containing both lines and no nested cards.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Append the return value to logs metadata.** Rejected because metadata would duplicate the renderer, need a second stable formatting contract for every JSON root, and still miss post-policy content replacement or spill previews.
|
||||
|
||||
**Merge presenter metadata with `result.content`.** Rejected because the rendered content already contains the logs; merging would duplicate them and require brittle deduplication.
|
||||
|
||||
**Forward `result.content` through a generic result presenter.** Rejected because the durable event already carries that content and UI consumers already have a generic raw-content fallback. The host mux serializes a tool-owned result view beside the event, so forwarding would duplicate the rendered content in one frame merely to recreate the fallback; the default worker alone admits a 64 MiB variable-payload budget before rendering.
|
||||
|
||||
**Create one card per nested dispatch.** Rejected because intermediate values are intentionally execution-local and never model-facing. Multiple cards would expose an implementation trace instead of the single Code Mode operation the model and user invoked.
|
||||
|
||||
## Consequences
|
||||
|
||||
TUI and JSON-RPC/Web display the same complete content the model receives and replay persists, including post-policy spill previews, through their generic result fallback. The host API retains the pending program title without duplicating the raw result in a separate view payload. New `run_code` results no longer carry the optional logs metadata, but this requires no session-format bump: existing records remain valid because presentation reads their durable rendered content.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: 保证 Code Mode 结果卡片内容完整
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-20-code-mode-result-card-completeness.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
外层 `run_code` 工具会持久化完整的渲染内容，但其 UI 展示器忽略了这些内容，转而根据仅含日志的 `presentationMeta` 投影重新构建卡片正文。仅有结果的运行看似正确，是因为展示器正文为空时，消费方会回退到 `tool/result.content`。只要程序输出一条日志，展示器就会提供非空内容，回退随即停止，返回值便会从完成态卡片中消失。当已捕获的日志使陈旧投影变为非空时，输出落盘策略最终生成的头尾预览也会受到同一职责拆分的影响。
|
||||
|
||||
嵌套 Code 调用从不生成自己的卡片。因此，仅仅为了重建这一张不完整卡片而给外层调用生成元数据，还掩盖了每次外层调用只生成一张卡片的预期边界。
|
||||
|
||||
## 决策
|
||||
|
||||
规范的工具注册表流水线负责最终面向模型的外层内容。成功时，`run_code` 输出渲染器先渲染已捕获的日志，然后渲染返回值或显式的无输出标记。运行时失败和执行前策略拒绝由 `ToolRegistry` 归一化为错误内容，过程中不会调用该渲染器。Post-execute 阻断发生在成功渲染之后，并把结果替换为错误内容；其他 post-execute 策略与输出落盘决策可以在持久化之前替换内容。
|
||||
|
||||
`run_code` 不提供 `presentResult`。既有的通用结果回退机制会保留待完成的程序标题，并渲染原始的最终 `tool/result.content`；这一持久、可回放且经过 post-policy 处理的投影是卡片中结果内容的唯一来源。宿主 API 代理因此不提供单独的结果视图，而不会在 `event.data.content` 与 `view.view.content` 中重复序列化同一内容。冗余的仅含日志的 `presentationMeta` 投影继续保持移除状态。
|
||||
|
||||
嵌套分发保持不变。带有 `exec.parent` 标记的调用会发出 `tool/code-dispatch` 事件（携带完整渲染内容），但不会生成与 `tool/call` 或 `tool/result` 对应的界面卡片，因此一次外层 `run_code` 调用仍然只会生成一张卡片。
|
||||
|
||||
## 测试
|
||||
|
||||
工具单元测试通过规范注册表覆盖仅有日志、仅有结果、日志与结果并存、无输出、结果落盘和失败的结果，然后固定持久内容以及结果展示器不存在这一事实。宿主 mux 回归测试使用仅有调用的展示器，证明结果帧恰好携带一次原始内容，且不含视图。这些案例证明陈旧元数据无法替换最终内容，同时不会让宿主重复该内容。
|
||||
|
||||
无密钥的 ACP（Agent Client Protocol）后端快照与 TUI Code Mode 快照会执行一个外层程序：程序进行两次嵌套 bash 调用，记录 `captured output`，并返回 `CODE_ONE+CODE_TWO`。ACP 持久化日志固定完整结果；TUI 界面只显示一张完成态外层卡片，其中包含这两行内容，且没有嵌套卡片。
|
||||
|
||||
## 备选方案
|
||||
|
||||
**把返回值追加到日志元数据：**不予采纳。元数据会与渲染器重复，并且需要为每一种 JSON 根另行维护稳定的格式化契约；post-policy 内容替换或输出落盘预览仍然会被遗漏。
|
||||
|
||||
**把展示元数据与 `result.content` 合并：**不予采纳。渲染内容已经包含日志；合并会造成重复，还需要依赖脆弱的去重逻辑。
|
||||
|
||||
**通过通用结果展示器转发 `result.content`：**不予采纳。持久事件已经携带该内容，UI 消费方也已有通用的原始内容回退机制。宿主 mux 会在事件旁序列化工具拥有的结果视图，因此转发仅仅是为了重建该回退机制，却会在一个帧中重复渲染内容；仅默认 worker 在渲染前允许 64 MiB 的可变载荷预算。
|
||||
|
||||
**为每次嵌套分发创建一张卡片：**不予采纳。中间值有意只存在于执行期间，永远不面向模型。多张卡片会暴露实现轨迹，而不是模型与用户调用的单次 Code Mode 操作。
|
||||
|
||||
## 影响
|
||||
|
||||
TUI 与 JSON-RPC／Web 通过通用结果回退机制显示与模型接收及回放持久化相同的完整内容，其中包括 post-policy 输出落盘预览。宿主 API 保留待完成的程序标题，同时不在单独的视图负载中重复原始结果。新的 `run_code` 结果不再携带可选的日志元数据，但无需提升会话格式版本：现有记录仍然有效，因为展示逻辑会读取其中持久化的渲染内容。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-22-collapsed-sidebar-control-rail.md: 6b61f5c64f3f1db19a2e242e9d9f054f30cb470c
|
||||
2026-07-22-collapsed-sidebar-control-rail.zh.md: b487950fc2c261060c44ad5b0ddc5820ca326006
|
||||
@@ -0,0 +1,30 @@
|
||||
# Agent Note: A collapsed sidebar retains its control rail
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-22-collapsed-sidebar-control-rail.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The sidebar close action persisted a zero width preference, and the layout mapped that preference to a zero-width grid track. The only sidebar toggle and the settings entry both lived inside that clipped track, so closing the sidebar removed every visible recovery control. Reloading preserved the closed preference and reproduced the lockout.
|
||||
|
||||
## Decision
|
||||
|
||||
The layout maps a closed sidebar (persisted width `0`) to the fixed `SIDEBAR_COLLAPSED` width of 56px: a 24px icon column between the sidebar's 16px horizontal paddings. The sidebar track is fixed-width in the solver — open or collapsed it never concedes to viewport pressure (only details shrinks, then auto-closes) — and the rail retains its right border while the stored expanded width remains untouched.
|
||||
|
||||
`AppFrame` marks the sidebar collapsed from the persisted width preference rather than from the resolved track width, removes the resize handle while collapsed, and passes `collapsed` to the sidebar slot as owner props from the render site. Collapse and expand animate: the frame transitions `grid-template-columns` (and the remaining handle its `left`) on the deepsuite sider curve — `--ds-ease-in-out` over `--ds-transition-duration-slow`, both supplied by ui-theme's base sheet; transitions pause during drags and under `prefers-reduced-motion`.
|
||||
|
||||
`SidebarRoot` reads the owner `collapsed` prop and transitions as a slide + crossfade: the expanded content freezes at its width (inline style) and fades out in place over 150ms while the sliding grid column clips it — nothing reflows mid-slide. At settle the wide-only content (brand, labels, input, session tree) unmounts — dropping the sessions subscription and leaving the rendered and accessibility trees — and the control rows snap to the rail (open toggle, new session, new workspace, search, the same top-down order as their expanded rows) fading in as the slide ends. Each rail control keeps its expanded counterpart's behavior (the search icon expands the sidebar and focuses the search box after the slide), carries a tooltip, and the toggle rests as the whale mark with the panel icon on hover. The search query lives with the root and survives the round trip.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Render an expand button over the center column** — rejected because it recovers only the toggle, not the persistent settings area, and splits sidebar chrome across two package owners.
|
||||
- **Keep a zero-width grid track and let the rail overflow it** — rejected because the rail would overlap the center column and leave hit testing and responsive geometry disconnected from the grid.
|
||||
- **Keep the complete sidebar tree mounted and hide it with clipping** — rejected because hidden controls remain in the semantic tree and continue subscribing and rendering even though only two controls belong in the collapsed state.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A collapsed sidebar reserves 56px instead of yielding the entire width to the center column. Expanding restores the persisted width and drag behavior.
|
||||
- The settings entry remains visible but retains its existing placeholder behavior; this change does not introduce an account or settings screen.
|
||||
- Layout solver tests pin the compact width, sidebar component tests pin the visible controls, and the keyless real-bundle web smoke test pins collapse and recovery through the assembled client.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Agent Note: 侧边栏折叠后保留控制栏
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-22-collapsed-sidebar-control-rail.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
侧边栏关闭操作会持久化宽度偏好 `0`，布局再将该偏好映射为宽度为零的网格轨道。侧边栏唯一的开关与设置入口都位于这个被裁切的轨道内，因此关闭侧边栏会移除所有可见的恢复控件。页面重新加载时仍会读取关闭偏好，从而再次陷入无法恢复的状态。
|
||||
|
||||
## 决策
|
||||
|
||||
布局将关闭的侧边栏（持久化宽度为 `0`）映射为固定的 `SIDEBAR_COLLAPSED` 宽度 56px：在侧边栏两侧各 16px 的水平内边距之间放置一列 24px 的图标控件。侧边栏轨道在求解器中是定宽的——无论展开还是折叠都不向视口压力让步（只有 details 会收缩、继而自动关闭）；控制栏保留右侧边框，已存储的展开宽度保持不变。
|
||||
|
||||
`AppFrame` 根据持久化的宽度偏好标记侧边栏是否折叠，而不是根据求解后的轨道宽度来判断；折叠时移除尺寸调整手柄，并在渲染点把 `collapsed` 作为 owner props 传给侧边栏插槽。折叠与展开带动画：frame 对 `grid-template-columns`（以及余下手柄的 `left`）应用 deepsuite 侧栏曲线过渡——`--ds-ease-in-out` 配 `--ds-transition-duration-slow`，两个变量由 ui-theme 的 base 表提供；拖拽期间和 `prefers-reduced-motion` 下过渡暂停。
|
||||
|
||||
`SidebarRoot` 读取 owner 的 `collapsed` 属性，过渡是滑动 + 交叉淡变：展开内容以内联样式冻结在原宽度、150ms 原地淡出，滑动中的网格列裁切它——滑动途中不发生任何重排。settle 时宽态专属内容（品牌标识、文字标签、输入框、会话树）卸载——随之退订会话列表并离开渲染树与可访问性树——控件行落位到控制栏（打开开关、新建会话、新建工作区、搜索，自上而下与展开态各行顺序一致），随滑动结束淡入。每个控制栏控件保持与展开态对应控件一致的行为（搜索图标展开侧边栏并在滑动结束后聚焦搜索框）并带 tooltip；开关静止时显示鲸鱼标，悬停切换为面板图标。搜索关键词由根组件持有，折叠往返后保留。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **在中心列上方渲染展开按钮**：不予采纳，因为这只能恢复开关，无法保留常驻设置区域，同时还会让侧边栏 UI 由两个包（package）分别持有。
|
||||
- **保留宽度为零的网格轨道，让控制栏溢出显示**：不予采纳，因为控制栏会与中心列重叠，还会使命中测试和响应式几何关系脱离网格布局。
|
||||
- **保持完整侧边栏树挂载，并通过裁切将其隐藏**：不予采纳，因为隐藏控件仍留在语义树中，而且会继续订阅和渲染，尽管折叠状态下只需要两个控件。
|
||||
|
||||
## 后果
|
||||
|
||||
- 折叠的侧边栏占用 56px，而不是把全部宽度让给中心列。展开时恢复持久化宽度与拖动行为。
|
||||
- 设置入口持续可见，但保留既有占位行为；本次改动不提供账户或设置页面。
|
||||
- 布局求解器测试固定紧凑宽度，侧边栏组件测试固定可见控件，基于真实构建产物的无密钥 Web 冒烟测试则通过组装后的客户端固定折叠与恢复行为。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-23-demo-web-builds-client-bundles.md: abd031c4ee6aeb7ed8c0baa61dfac16e5d64cc33
|
||||
2026-07-23-demo-web-builds-client-bundles.zh.md: 70604b344b5607b01815382da316805a9beaf27e
|
||||
@@ -0,0 +1,28 @@
|
||||
# Agent Note: demo:web builds the client plugin bundles
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-23-demo-web-builds-client-bundles.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
`dsh web` serves each web-client plugin's bundle from `GET /plugins/<id>/client.js`, resolving the path from the package's `exports["./client"]` (`lib/client.js`). Those bundles are produced only by the root `pnpm run build` (`tsc -b` then the per-package `tsdown.client.ts` configs); the Vite `build:web` step builds the frontend shell alone. `demo:web` and the README's Web UI instructions ran only `build:web`, so on a checkout without a prior full build every plugin bundle 404s, the client loader marks every plugin failed, and the boot screen shows "Failed to load plugins". The frontend shell built fine, hiding the missing artifact behind a runtime browser failure.
|
||||
|
||||
## Decision
|
||||
|
||||
`demo:web` runs `npm run build` before `npm run build:web`, so the plugin `lib/client.js` bundles exist before `dsh web` serves them. The README's Web UI section runs `pnpm run build && pnpm run build:web` for the installed `~/.dsh/source` checkout, which the installer never builds.
|
||||
|
||||
## Verification
|
||||
|
||||
After the full build, all eight `/plugins/<id>/client.js` endpoints return 200 and a headless Chromium load of `http://127.0.0.1:3080` renders the shell with no "Failed to load plugins" state.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Build the bundles inside `dsh web` at startup.** The app runs from source via tsx and owns no build step; folding an artifact build into the server boot crosses the source/artifact separation and slows every launch.
|
||||
|
||||
**Widen the tsdown root config to emit client bundles from `pnpm run build:web`.** `build:web` is the Vite frontend build; the client bundles are a separate tsdown pass over `lib/types`. Merging the two conflates the shell build with the package build and still leaves the root `build` as the only producer.
|
||||
|
||||
## Consequences
|
||||
|
||||
`demo:web` now pays the full `tsc -b && tsdown` cost on every invocation instead of only the Vite build. That is the price of a runnable web demo from a clean tree; a caller who already built can invoke `dsh web` directly.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Agent Note: demo:web 构建客户端插件的打包产物
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-23-demo-web-builds-client-bundles.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
`dsh web` 通过 `GET /plugins/<id>/client.js` 提供每个 web 客户端插件的打包产物，其路径由包的 `exports["./client"]`（`lib/client.js`）解析得到。这些打包产物只由根目录的 `pnpm run build`（先 `tsc -b`，再执行各包的 `tsdown.client.ts` 配置）生成；Vite 的 `build:web` 步骤只构建前端外壳。`demo:web` 与 README 的 Web UI 说明只运行了 `build:web`，因此在未预先完整构建的检出上，每个插件的打包产物都返回 404，客户端 loader 将所有插件标记为失败，启动界面显示 "Failed to load plugins"。前端外壳能正常构建，把缺失的产物掩藏在浏览器运行时的失败背后。
|
||||
|
||||
## Decision
|
||||
|
||||
`demo:web` 在 `npm run build:web` 之前先运行 `npm run build`，使插件的 `lib/client.js` 打包产物在 `dsh web` 提供它们之前已经存在。README 的 Web UI 小节针对已安装的 `~/.dsh/source` 检出运行 `pnpm run build && pnpm run build:web`，因为安装器从不构建它。
|
||||
|
||||
## Verification
|
||||
|
||||
完整构建后，全部八个 `/plugins/<id>/client.js` 端点均返回 200，无头 Chromium 加载 `http://127.0.0.1:3080` 能渲染出外壳，不再出现 "Failed to load plugins" 状态。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**在 `dsh web` 启动时构建打包产物。** 该应用通过 tsx 从源码运行，本身没有构建步骤；把产物构建塞进服务器启动流程会越过源码与产物的分离，并拖慢每次启动。
|
||||
|
||||
**扩大 tsdown 根配置，使 `pnpm run build:web` 也产出客户端打包产物。** `build:web` 是 Vite 前端构建；客户端打包产物是对 `lib/types` 的另一趟独立 tsdown 处理。把两者合并会混淆外壳构建与包构建，而且根目录的 `build` 仍是唯一的产出者。
|
||||
|
||||
## Consequences
|
||||
|
||||
`demo:web` 现在每次调用都要付出完整的 `tsc -b && tsdown` 代价，而不再只是 Vite 构建。这是从干净的代码树运行 web 演示所要付出的代价；已经完成构建的调用方可以直接调用 `dsh web`。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-23-thinking-row-disclosure-target.md: 9f748b6d76b9ddfe657e56da9f9e7f576b05599e
|
||||
2026-07-23-thinking-row-disclosure-target.zh.md: e33c951ca33e032e2eb2d306d90979d1e8471a17
|
||||
@@ -0,0 +1,30 @@
|
||||
# Agent Note: Thinking rows use one disclosure target
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-23-thinking-row-disclosure-target.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
A collapsed reasoning entry presents `Think` and its one-line reasoning summary as one visual row, but an icon-only disclosure control leaves both visible labels inert. Applying title expansion to every tool row would instead break the generic tool-row contract, where the row opens details and only the leading control expands arguments.
|
||||
|
||||
## Decision
|
||||
|
||||
`ToolRow` exposes the opt-in `expandOnRowClick` policy. `ThinkRow` enables it so the title and reasoning summary form one accessible disclosure target; pointer clicks, Enter, and Space toggle the same component-local expanded state. Tool rows that do not opt in retain row-to-details selection and leading-control argument expansion.
|
||||
|
||||
## Verification
|
||||
|
||||
The component spec pins both Think click targets and the unchanged generic tool-row handoff. The keyless browser fixture loads the real sidebar and conversation bundles, opens an authored reasoning session, clicks the summary and title, and checks the disclosure state and expanded body.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Expand every tool row from its title.** Generic tool rows use row clicks for details selection, so sharing this behavior would conflate two controls.
|
||||
|
||||
**Keep icon-only disclosure.** The smallest hit target remains disconnected from the labels that describe the hidden content.
|
||||
|
||||
**Render separate title and summary buttons.** Two controls for one expanded state add duplicate focus stops and ambiguous semantics.
|
||||
|
||||
## Consequences
|
||||
|
||||
Thinking rows gain a larger pointer target and keyboard disclosure semantics without changing other tool interactions. The generic row component carries one optional policy because disclosure ownership differs between reasoning and tool calls.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Agent Note: thinking 行使用单一展开目标
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-23-thinking-row-disclosure-target.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
折叠的推理（reasoning）条目在同一视觉行中呈现 `Think` 和单行推理摘要，但仅图标可展开会让两个可见标签都无法交互。若让所有工具行均可通过标题展开，又会破坏通用工具行的契约：整行负责打开详情，只有前导控件负责展开参数。
|
||||
|
||||
## 决策
|
||||
|
||||
`ToolRow` 提供显式启用的 `expandOnRowClick` 策略。`ThinkRow` 启用该策略，让标题和推理摘要组成单一且无障碍的展开目标；鼠标点击、Enter 和 Space 都切换同一个组件本地展开状态。未启用该策略的工具行仍由整行完成详情选择，由前导控件展开参数。
|
||||
|
||||
## 验证
|
||||
|
||||
组件测试固定两个 Think 点击目标以及未改变的通用工具行交接行为。无密钥浏览器 fixture（测试前置数据）加载真实的侧边栏与会话 bundle，打开包含推理内容的既定会话，点击摘要与标题，并检查展开状态和展开后的正文。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**让每个工具行都可通过标题展开。** 通用工具行将整行点击用于详情选择，共享这一行为会混淆两个控件。
|
||||
|
||||
**保留仅图标展开。** 最小的点击目标仍与描述隐藏内容的标签脱节。
|
||||
|
||||
**把标题和摘要分别渲染为按钮。** 两个控件共享一个展开状态，会增加重复的焦点停靠点并产生含糊语义。
|
||||
|
||||
## 后果
|
||||
|
||||
thinking 行获得更大的鼠标点击目标和键盘展开语义，同时不改变其他工具交互。通用行组件承担一个可选策略，因为推理与工具调用的展开所有权不同。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-26-intent-draft-same-tick-echo.md: 3ef91b123f9abe0817bf5f7e1ad48e2e6f1e2cb3
|
||||
2026-07-26-intent-draft-same-tick-echo.zh.md: d890a68f4b9c83713b7a52c44ecb6bcd16265669
|
||||
@@ -0,0 +1,28 @@
|
||||
# Agent Note: Intent draft echoes in the same tick
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-26-intent-draft-same-tick-echo.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The hero composer ("Let's start building") is a controlled textarea whose value is the frontend Session Intent's retained prompt, read from the sessions **list** snapshot (`EmptyState` binds `intent.prompt` via `useSessions`). Typing routed through `SessionManager.updateIntent → Session.updatePendingPrompt`, which flushes the **Session's own** notifier synchronously — but the list snapshot the composer actually renders from only heard about the change through the intent watch subscription in `startIntent`, which calls `markDirty()`, a microtask-deferred flush.
|
||||
|
||||
A deferred echo violates the controlled-input contract documented on the Notifier (see the [web client architecture note](../architecture/2026-07-19-gui-web-client-architecture.md)): React compares the DOM value against the still-stale snapshot during the same tick as `onChange` and rolls the textarea back. With plain typing this shows as caret jumps; with an IME it corrupts input — every composition update gets rolled back and re-applied against a stale value, so typing Pinyin "nihao" commits fragments like "nnini hni hani hao你好". The resident composer (`ConversationRoot`) was not affected: its draft lives in the chat store (sync flush) or comes from `updateSessionPrompt`, which reads the Session snapshot directly rather than the list projection.
|
||||
|
||||
## Decision
|
||||
|
||||
`SessionManager.updateIntent` calls `this.notifier.notifyNow()` after `updatePendingPrompt`, flushing the list snapshot in the same tick as the change event. This matches the Notifier's channel rule: a direct echo of a user gesture whose controlled input renders from this snapshot uses `notifyNow`; the intent watch keeps `markDirty` for every other (async) intent transition.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Change the intent watch callback in `startIntent` to `notifyNow`.** Wrong channel for that seam: the watch also fires on frame-driven Session changes (publication, send phases), and the architecture note bans `notifyNow` for frame-driven sources because it collapses batching.
|
||||
|
||||
**Have `EmptyState` read the prompt from the Session snapshot instead of the list.** Restructures the slot contract (EmptyState is deliberately bound to the standard `useSessions` feed and has no session scope yet — the frontend Session is page-local) for no gain over flushing the projection it already reads.
|
||||
|
||||
**Suppress the rollback in `InputBar` with local uncontrolled state.** Hides the symptom, forfeits the single-source-of-truth draft (the retained prompt must survive workspace retargeting and send/retry), and leaves every other list-snapshot-controlled input exposed.
|
||||
|
||||
## Consequences
|
||||
|
||||
Typing in the hero composer, IME composition included, echoes synchronously. `updateIntent` on a no-intent state stays a no-op with no notification. The web workspace-flow snapshot's composer helper now asserts the same-tick echo instead of waiting for it, so a regression to a deferred echo fails the keyless snapshot gate; a runtime unit test pins the same contract at the manager seam.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Agent Note: Intent draft echoes in the same tick
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-26-intent-draft-same-tick-echo.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
hero composer（「Let's start building」）是一个受控（controlled）的 textarea，它的值取自前端 Session Intent 保留下来的提示词，读自会话**列表**快照（`EmptyState` 通过 `useSessions` 绑定 `intent.prompt`）。输入经由 `SessionManager.updateIntent → Session.updatePendingPrompt`，后者会同步刷新 **Session 自身的** notifier——但 composer 实际渲染所依据的那份列表快照，只能通过 `startIntent` 中的 intent watch 订阅得知这次变更，而该订阅调用的是 `markDirty()`，即一次延迟到微任务的刷新。
|
||||
|
||||
延迟的回显违反了 Notifier 上所记录的受控输入契约（见 [web 客户端架构笔记](../architecture/2026-07-19-gui-web-client-architecture.md)）：React 在与 `onChange` 相同的 tick 内，把 DOM 值与仍然陈旧的快照相比对，随后把 textarea 回滚。普通输入时，这表现为光标跳动；使用输入法（IME）时，它会损坏输入——每一次 composition 更新都会被回滚，并针对陈旧的值重新应用，因此输入拼音「nihao」会提交出类似「nnini hni hani hao你好」这样的片段。resident composer（`ConversationRoot`）不受影响：它的草稿存放在 chat store 中（同步刷新），或来自 `updateSessionPrompt`，后者直接读取 Session 快照，而不是列表投影。
|
||||
|
||||
## Decision
|
||||
|
||||
`SessionManager.updateIntent` 在 `updatePendingPrompt` 之后调用 `this.notifier.notifyNow()`，从而在与变更事件相同的 tick 内刷新列表快照。这符合 Notifier 的通道规则：当某个用户手势的受控输入正是从该快照渲染时，对它的直接回显使用 `notifyNow`；而 intent watch 对其余所有（异步的）intent 状态转换仍保留 `markDirty`。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**把 `startIntent` 中的 intent watch 回调改为 `notifyNow`。** 对那个 seam 而言是错误的通道：该 watch 也会在帧驱动的 Session 变更（发布、发送阶段）时触发，而架构笔记禁止对帧驱动的来源使用 `notifyNow`，因为那会瓦解批处理。
|
||||
|
||||
**让 `EmptyState` 从 Session 快照而非列表读取提示词。** 这会重构槽位契约（EmptyState 有意绑定到标准的 `useSessions` 数据源，且尚无 session 作用域——前端 Session 是页面本地的），相比刷新它本就读取的那份投影并无收益。
|
||||
|
||||
**在 `InputBar` 中用本地的非受控状态抑制回滚。** 这只是掩盖症状，放弃了单一真源的草稿（保留下来的提示词必须在工作区重定向以及发送／重试后依然存在），并让其余每一个由列表快照控制的输入都暴露在同一问题之下。
|
||||
|
||||
## Consequences
|
||||
|
||||
在 hero composer 中输入（包括输入法 composition 在内）会同步回显。在无 intent 的状态上调用 `updateIntent` 仍是一次空操作，不发出任何通知。web workspace-flow 快照的 composer 辅助函数现在断言的是同一 tick 内的回显，而不是等待它，因此一旦回退成延迟回显，就会让无密钥快照门禁失败；一个运行时单元测试在 manager 这一 seam 处钉住了同一份契约。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-14-acp-agent-client-protocol.md: ee616a58cbd0201f14c7000672aec7c2485af0b1
|
||||
2026-06-14-acp-agent-client-protocol.zh.md: 8af061a30fed72c60c9e7a1747970a23415d530f
|
||||
@@ -0,0 +1,62 @@
|
||||
# Agent Note: Agent Client Protocol (ACP) support — drive the coding agent from external editors
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-06-14-acp-agent-client-protocol.zh.md)
|
||||
|
||||
> Superseded by [ACP as an automation-only protocol](../simplification/2026-07-23-acp-automation-only-protocol.md). This note records the retired editor-facing bridge design.
|
||||
|
||||
## Problem
|
||||
|
||||
The harness originally exposed agents only through a readline loop. That surface could carry text, but it gave an editor no structured way to create or resume sessions, correlate prompt completion, stream reasoning and tool activity, render tool-specific UI, ask for permission, or cancel one conversation without disturbing another. ACP defines those interactions as JSON-RPC over stdio, and Zed is the target client used to make concrete compatibility decisions.
|
||||
|
||||
The bridge must preserve the harness's existing ownership boundaries. It cannot depend on the concrete agent loop, bypass the tool registry, execute shell commands in the editor, or invent a second source of session truth. stdout is also the protocol transport, so any accidental log output corrupts the connection.
|
||||
|
||||
## Decision
|
||||
|
||||
`@deepseek-ai/dsh-acp` was a UI/client-driver plugin in the `ui` package group (it now lives in `acp`). It used `@agentclientprotocol/sdk`'s `AgentSideConnection` over stdin/stdout and programmed only interface services: the agent create/resume factory, session persistence, tool registry, user interaction, and optional approval/bash capabilities. It did not change the agent loop and was not a capability-seam implementation.
|
||||
|
||||
The bridge implements the following stable session path:
|
||||
|
||||
- `initialize` negotiates the protocol version, advertises text plus `resource_link` prompts, and advertises `loadSession`.
|
||||
- `session/new` validates an absolute `cwd`, stores it in `SessionHeader`, creates an agent through `ctx.agents`, and returns any composition-backed config options.
|
||||
- `session/load` validates the requested cwd against persisted metadata before constructing an agent, reserves the id across the asynchronous resume, replays user/assistant/tool events as ACP updates, and reports the resumed config-option fold.
|
||||
- `session/prompt` accepts text and resource links, rejects unsupported or empty content, allows one in-flight prompt per session, and settles against that prompt's owning `turn/end`. An error turn rejects the RPC; other closed turn reasons map through a total ACP stop-reason codec.
|
||||
- `session/cancel` calls the queue-aware agent cancel path and settles only the addressed session's prompt.
|
||||
|
||||
Tool-call presentation remains tool-owned. A tool's `presentCall` and `presentResult` return the `generic`, `terminal`, or `diff` render-intent variants; the bridge switches on that union and maps it to ACP. Presenter-less tools receive a generic fallback. Bash terminal cards use Zed's capability-gated `_meta.terminal_info`, `_meta.terminal_output`, and `_meta.terminal_exit` convention; the harness still executes the command through `ctx.bash`, preserving sandbox, environment scrub, ownership, and cwd. Clients without that extension receive ordinary text content. Filesystem tools provide diff cards and file locations without hard-coded tool-name branches in the bridge.
|
||||
|
||||
Permission handling is an answerer on the [user-approval seam](2026-07-06-approval-seam.md), not an ask-every-tool policy in ACP. An `approval/request` for a bridge-owned agent with a call id becomes `session/request_permission` on that agent's editor session, with one-shot allow/reject choices. Foreign or call-less requests delegate; a missing or failed answerer remains fail-closed. The plugin that asks—such as a pre-execute policy or bash escalation—owns the decision to ask.
|
||||
|
||||
When `ctx.permission` is composed, the bridge exposes one `permission` select from the deployment's preset table. The shipped `workspace-write` and `danger-full-access` presets each bundle a sandbox mode with an approval policy; unmatched effective knobs produce the switch-away-only `custom` state. `session/set_config_option` validates through `PermissionService.set()` and writes both owning knob events. A switch during an open turn appends immediately; an idle switch is overlaid in responses and anchored at the next `agent/prompt-submit`, before request assembly. Until then it is memory-only, so a crash restores the durable fold. ACP session modes are not modeled because config options are the forward protocol surface; `AcpConfig.model` remains connection-wide.
|
||||
|
||||
The bridge also provides the ACP-backed `UserInteractionProvider`: `ask_user_question` requests become form elicitations on the owning session. Select, multi-select, option descriptions, and custom-answer override semantics are preserved.
|
||||
|
||||
Lifecycle ownership is explicit. The bridge holds an `AgentHandle` per live session. Disconnect and Cordis disposal cancel pending prompts, dispose every handle in parallel, await loop quiescence and persistence flush, and then remove the records. Stream notification failures are contained so a vanished client cannot corrupt an agent turn. The ACP app composition loads no stdout logger; a test guards stdout as framed JSON-RPC only.
|
||||
|
||||
The current protocol contract lives in the [`dsh-acp` package README](../../../../packages/acp/acp/README.md).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**A prepended `tools/execute` listener that asks on every ACP-owned call** — rejected. It would hard-code permission policy into the UI bridge, ask even when no policy requires it, and could not serve approval requests that arise after execution begins. The shared user-approval seam keeps mechanism, asking policy, and UI answerer separate.
|
||||
|
||||
**Inject the concrete `agentLoop`** — rejected. Agent creation, resume, idle observation, and disposal are interface-level ownership operations on `dsh-agent`; a UI plugin does not need a dependency-rule exception.
|
||||
|
||||
**Execute bash through ACP `terminal/*`** — rejected. That would move execution outside the harness and bypass its sandbox, credential scrub, task ownership, cwd resolution, and session log. Terminal metadata is presentation only.
|
||||
|
||||
**Represent permission presets as ACP session modes** — rejected. The deployment-defined preset is already one config-option select, while session modes are the legacy surface slated for removal in ACP v2.
|
||||
|
||||
**Hijack stdout defensively** — rejected. Process-wide monkey-patching is outside Cordis effect ownership and races the protocol transport. The app composition owns stdout purity.
|
||||
|
||||
## Consequences
|
||||
|
||||
Editors can create, load, prompt, cancel, render, ask, and reconfigure multiple harness sessions over one ACP connection without a loop-specific dependency. The session event log remains the durable source for replay, prompt settlement, cwd, and per-session configuration. Tool presentation and human-answer channels remain extensible plugin contracts instead of ACP-specific behavior.
|
||||
|
||||
The bridge deliberately does not implement session list/delete/resume/close capabilities, MCP passthrough, additional directories, image/audio/embedded-resource prompts, plans, slash commands, usage updates, editor filesystem delegation, or the ACP terminal execution sub-protocol. Runtime model selection was added later through standard session config options by the [LLM catalog and ACP selection Agent Note](../architecture/2026-07-15-llm-model-catalog-and-acp-selection.md).
|
||||
|
||||
An idle config selection is truthful in the live response but not durable until the next `agent/prompt-submit` anchors it inside the open turn. Crashing before that boundary loses the pending selection; this is the cost of keeping session events turn-enclosed and replay-safe.
|
||||
|
||||
## Verification
|
||||
|
||||
The ACP suites cover the in-memory protocol codec, create/load replay, exact prompt settlement, cancellation races, unsupported content, tool presentation, terminal capability fallback, permission outcome mapping, config-option validation and persistence, multi-session isolation, disconnect/disposal quiescence, and HMR cleanup. Snapshot and built-bin tests exercise the app composition, while the real-API e2e self-skips without a key.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Agent Note: Agent Client Protocol（ACP）支持——从外部编辑器驱动编码 agent
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-06-14-acp-agent-client-protocol.md) | 中文
|
||||
|
||||
> 已被 [ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)取代。本 Agent Note 记录已退役的面向编辑器的桥接层设计。
|
||||
|
||||
## 问题
|
||||
|
||||
harness 最初仅通过 readline 循环暴露 agent。该接口能传输文本，但编辑器无法以结构化方式创建或恢复会话、关联提示词完成、流式输出推理（reasoning）与工具活动、渲染工具专属 UI、请求权限，或在不干扰其他对话的前提下取消某个对话。ACP（Agent Client Protocol）将这些交互定义为基于 stdio 的 JSON-RPC，Zed 是用于做出具体兼容性决策的目标客户端。
|
||||
|
||||
桥接层必须保持 harness 既有的所有权边界。它不能依赖具体的 agent loop（智能体循环），不能绕过工具注册表，不能在编辑器中执行 shell 命令，也不能发明第二个会话真源。stdout 同时也是协议传输通道，因此任何意外的日志输出都会破坏连接。
|
||||
|
||||
## 决策
|
||||
|
||||
`@deepseek-ai/dsh-acp` 曾是 `ui` 包组中的 UI/客户端驱动插件（现位于 `acp`）。它使用 `@agentclientprotocol/sdk` 的 `AgentSideConnection`（基于 stdin/stdout），仅编排接口服务：agent 创建/恢复工厂、会话持久化、工具注册表、用户交互，以及可选的审批/bash 能力。它不修改 agent loop，也不是能力 seam 的实现。
|
||||
|
||||
桥接层实现以下稳定的会话路径：
|
||||
|
||||
- `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 提示词，并在该提示词所属的 `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 会在故障时保持拒绝。发起询问的插件（如预执行策略或 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（资源释放）会取消待处理的提示词，并行 dispose 所有 handle，等待循环完全停稳与持久化刷写，然后移除记录。流通知失败被隔离，因此消失的客户端不会破坏 agent 轮次。ACP 应用组合不加载 stdout logger；一个测试守卫 stdout 仅包含帧化的 JSON-RPC。
|
||||
|
||||
当前的协议契约见 [`dsh-acp` 包 README](../../../../packages/acp/acp/README.md)。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**在 `tools/execute` 监听器前置一层，对每个 ACP 所属调用都询问权限**：否决。这会将权限策略硬编码到 UI 桥接层，即使没有策略要求也会询问，且无法服务于执行开始后才产生的审批请求。共享的 user-approval seam 将机制、询问策略和 UI answerer 分离。
|
||||
|
||||
**注入具体的 `agentLoop`**：否决。agent 的创建、恢复、空闲观察与释放是 `dsh-agent` 上的接口级所有权操作；UI 插件不需要依赖规则例外。
|
||||
|
||||
**通过 ACP `terminal/*` 执行 bash**：否决。这会将执行移到 harness 之外，绕过其沙箱、凭证清洗、任务所有权、cwd 解析与会话日志。终端元数据仅用于展示。
|
||||
|
||||
**将权限预设表示为 ACP session mode**：否决。部署定义的预设已经是一个 config-option select，而 session mode 是 ACP v2 计划移除的遗留接口。
|
||||
|
||||
**防御性劫持 stdout**：否决。进程级 monkey-patching 超出 Cordis 副作用所有权范围，且与协议传输存在竞争。应用组合拥有 stdout 纯净性。
|
||||
|
||||
## 后果
|
||||
|
||||
编辑器可以通过一条 ACP 连接创建、加载、提交提示词、取消、渲染、询问和重新配置多个 harness 会话，无需依赖特定的循环实现。会话事件日志仍是回放、提示词结算、cwd 与每会话配置的持久真源。工具展示与人工回答通道仍是可扩展的插件契约，而非 ACP 专属行为。
|
||||
|
||||
桥接层有意不实现会话列表/删除/恢复/关闭能力、MCP 透传、附加目录、图片/音频/嵌入资源提示词、plan、斜杠命令、用量更新、编辑器文件系统委托或 ACP 终端执行子协议。后续已通过标准会话配置选项加入运行时模型选择，见 [LLM 目录与 ACP 选择 Agent Note](../architecture/2026-07-15-llm-model-catalog-and-acp-selection.md)。
|
||||
|
||||
空闲时的配置选择在实时响应中是真实的，但在下一次 `agent/prompt-submit` 将其锚定到开放轮次之前不具持久性。在该边界之前崩溃会丢失待定选择；这是保持会话事件封闭于轮次内且回放安全的代价。
|
||||
|
||||
## 验证
|
||||
|
||||
ACP 测试套件覆盖内存协议编解码器、创建/加载回放、精确的提示词结算、取消竞争、不支持的内容、工具展示、终端能力回退、权限结果映射、config-option 校验与持久化、多会话隔离、断连/释放后的完全停稳，以及 HMR（热模块替换）清理。快照测试与 built-bin 测试验证应用组合，真实 API 的 e2e 测试在无 key 时自动跳过。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-18-acp-terminal-and-tool-rendering.md: 3ffe9b698d453a5d53ce4cc28bc85d8dd75f37a0
|
||||
2026-06-18-acp-terminal-and-tool-rendering.zh.md: 3dd8a110260519d0b6342f8984be98a2d1c53f01
|
||||
@@ -0,0 +1,51 @@
|
||||
# Agent Note: Rich ACP bash rendering — the terminal card via the `_meta` convention
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-06-18-acp-terminal-and-tool-rendering.zh.md)
|
||||
|
||||
> Superseded for ACP by [ACP as an automation-only protocol](../simplification/2026-07-23-acp-automation-only-protocol.md). Tool render intents remain available to UI transports, but ACP no longer projects them into terminal cards.
|
||||
|
||||
## Problem
|
||||
|
||||
The ACP bridge lets each tool own its call rendering via `presentCall`/`presentResult` (see [tool-call UI presentation](2026-06-14-acp-agent-client-protocol.md) and `packages/core/tools`). For `bash` we surface the exact command as the `tool_call` title, the model's `description` as a content text block, `kind: 'execute'`, and the completed output wrapped in a fenced ` ```console ` text block.
|
||||
|
||||
Reference editors render terminal metadata as a dedicated card with cwd, command, live-style output, and exit status; plain text loses that structure. The command is the title because execute cards hide raw input, while the human-readable description remains a separate block above the card.
|
||||
|
||||
## Key finding: agent-executed terminals use a `_meta` convention, NOT `terminal/create`
|
||||
|
||||
The ACP spec has a *client-side* terminal sub-protocol — the agent calls the client's `terminal/create` with `{ command, args, cwd, env }` and the **editor** executes the process, then the agent reads `terminal/output` / `wait_for_exit`. That model is wrong for us: our harness executes bash itself through `dsh-bash` (sandboxed env-scrub, background-task ownership, per-session cwd). Routing execution to the editor would bypass all of that and fork execution into two backends.
|
||||
|
||||
Studying the two reference agents (2026-06-18) shows neither uses `terminal/create` for their own shell tool — **both keep agent-side execution and emit a `_meta` convention** that Zed special-cases:
|
||||
|
||||
- **`claude-agent-acp`** (`tools.ts`, `acp-agent.ts`): gated on `clientCapabilities._meta.terminal_output`. The `tool_call` carries `content: [{ type: 'terminal', terminalId }]` and `_meta.terminal_info.{ terminal_id, cwd }`; output/exit arrive on the `tool_call_update`'s `_meta.terminal_output.{ terminal_id, data }` and `_meta.terminal_exit.{ terminal_id, exit_code, signal }`.
|
||||
- **`codex-acp`** (`CodexToolCallMapper.ts`, `TerminalOutputMode.ts`): same `terminal_info` on the call; output via `_meta.terminal_output` (full) or `_meta.terminal_output_delta` (incremental), selected from the same `_meta.terminal_output` capability.
|
||||
|
||||
Zed's side (`crates/agent_servers/src/acp.rs`, verified): on a `ToolCall` whose `_meta.terminal_info.terminal_id` is set, it registers a **display-only** terminal (header = `terminal_info.cwd`, label = `tool_call.title`); on a `ToolCallUpdate`, `_meta.terminal_output.data` writes to that terminal and `_meta.terminal_exit.{exit_code,signal}` sets the status. It advertises the capability as `clientCapabilities._meta.terminal_output = true`. `_meta` itself is a spec-blessed ACP extensibility point (typed `{[k]: unknown} | null` on `ToolCall`/`ToolCallUpdate`); the *specific keys* here (`terminal_info`/`terminal_output`/`terminal_exit`) are a Zed convention, not part of the ACP spec — but they are the de-facto contract for the Zed integration and the only way to get the terminal card while keeping execution agent-side.
|
||||
|
||||
## Decision
|
||||
|
||||
Keep `dsh-bash` agent-side execution; render the terminal card via the `_meta` convention, capability-gated, with the ` ```console ` text block as the guaranteed fallback.
|
||||
|
||||
1. **Capability.** `initialize` reads `clientCapabilities._meta.terminal_output` and the bridge remembers it per connection.
|
||||
2. **Neutral presentation vocabulary.** `dsh-tools` gains a terminal-shaped presentation a tool can return — provider-neutral (`cwd`, the output `data`, an `exitCode`/`signal`), NO ACP types. `dsh-tool-bash` returns it for `bash` (cwd from the resolved workdir; output + exit parsed from the run result).
|
||||
3. **Bridge mapping.** When the client advertised the capability, the bridge maps that presentation to: on `tool_call`, `content:[…, {type:'terminal', terminalId}]` (any tool `content`, e.g. the description, rendered BEFORE the terminal block) + `_meta.terminal_info.{terminal_id,cwd}`; on `tool_call_update`, `_meta.terminal_output.{terminal_id,data}` (the captured output) + `_meta.terminal_exit.{terminal_id, exit_code|signal}` (the parsed exit), with the update's text `content` OMITTED (an ACP `tool_call_update.content` REPLACES the call's content collection, so re-sending the fenced block would clobber the terminal content block). `terminalId` is derived from the harness `callId` (stable, unique per call). When the capability is absent, the bridge sends the description content block on the call and the existing ` ```console ` text content on the update — unchanged.
|
||||
4. **The exit pill is parsed from the rendered output; no new execution path, no live streaming.** Output is attached at completion (from the agent's own `tool/result`), not streamed token-by-token. The exit-status pill (`_meta.terminal_exit.{exit_code,signal}`) IS emitted: the pure `presentResult(args, result)` seam sees only content blocks, so `dsh-tool-bash` recovers the structured exit by parsing the status markers (`[exit code: N]` / `[killed by signal: …]`) that `renderResult` appended — the parse is the exact inverse of the marker emission, the two co-evolve in one file, and a round-trip test guards the pair. Disposal is unaffected: nothing new to tear down, since the bridge never creates a client-side terminal.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **The ACP client-side terminal sub-protocol (`terminal/create`)** — explicitly rejected: the editor would execute the process, bypassing `dsh-bash`'s env scrub, background-task ownership, and per-session cwd, and forking execution into two backends. Both reference agents reject it the same way (the key finding above); agent-side execution plus the `_meta` convention is the only shape that yields the terminal card while keeping the harness's execution policy.
|
||||
- **Threading a structured exit through the event schema** — rejected in favor of the marker round-trip: the pure `presentResult(args, result)` seam sees only content blocks, and the parse is the exact inverse of the marker emission, co-evolving in one file under a round-trip test.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **Zed-convention `_meta` keys.** The terminal card rides on Zed-specific keys (`terminal_info`/`terminal_output`/`terminal_exit`) inside ACP's spec-blessed `_meta` extensibility point, NOT on the ACP terminal sub-protocol. A client that doesn't recognize the keys still gets the text fallback (the capability gate ensures we only emit them when the client opted in via `_meta.terminal_output`), so a non-Zed client is never worse off. If ACP later standardizes agent-executed terminals, migrate to that and drop the convention keys.
|
||||
- **Capability honesty.** Emit terminal metadata ONLY when the client advertised `_meta.terminal_output`; the text fallback is the contract for everyone else and must never regress. Covered by a no-capability test asserting the ` ```console ` path.
|
||||
- **terminalId collisions.** Deriving it from the per-call `callId` keeps it unique within a session and stable across the call/result pair; never reuse one across calls.
|
||||
- **Exit parsed from rendered text.** The exit pill recovers `exit_code`/`signal` by parsing `renderResult`'s status markers rather than threading a structured exit through the event schema (which the pure `presentResult` seam never sees). The parse is the exact inverse of the marker emission and lives in the same file; a round-trip test pins the pair so a marker-format change that breaks the parse fails the suite. If the markers ever need to diverge from what the pill wants, surface a structured exit on the result event instead.
|
||||
- **Provider-neutral vocabulary creep.** The terminal presentation widens the `dsh-tools` surface; keep it neutral (no ACP types leak into `dsh-tools`) and only as rich as a second UI consumer would also want.
|
||||
|
||||
## Out of scope / non-goals
|
||||
|
||||
The text-block baseline stays the no-capability default. Two follow-ups are deliberately NOT built here and would each warrant their own Agent Note when someone takes them on: **live incremental streaming** (`_meta.terminal_output_delta` as chunks arrive, which needs an incremental-output seam on `dsh-bash`), and **command classification** (parsing a `cat`/`sed` as a `read` card with a file location, a `grep` as a `search`, etc., falling back to the terminal card — display-only, must never change what executes).
|
||||
@@ -0,0 +1,51 @@
|
||||
# Agent Note: 富 ACP bash 渲染——通过 `_meta` 约定实现终端卡片
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-06-18-acp-terminal-and-tool-rendering.md) | 中文
|
||||
|
||||
> 就 ACP 而言已被 [ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)取代。工具渲染意图对 UI 传输层仍然可用，但 ACP 不再将其投影为终端卡片。
|
||||
|
||||
## 问题
|
||||
|
||||
ACP（Agent Client Protocol）桥接层允许每个工具通过 `presentCall`/`presentResult` 自行控制调用渲染（见[工具调用 UI 呈现](2026-06-14-acp-agent-client-protocol.md)与 `packages/core/tools`）。对于 `bash`，我们将确切命令作为 `tool_call` 标题呈现，模型的 `description` 作为一个内容文本块，`kind: 'execute'`，完成后的输出包裹在 ` ```console ` 围栏文本块中。
|
||||
|
||||
参考编辑器将终端元数据渲染为一张专用卡片，包含 cwd、命令、实时风格的输出和退出状态；纯文本则丢失了这些结构。命令之所以作为标题，是因为执行卡片隐藏原始输入，而人类可读的描述保留为卡片上方的独立块。
|
||||
|
||||
## 关键发现：agent 执行的终端使用 `_meta` 约定，而非 `terminal/create`
|
||||
|
||||
ACP 规范有一个*客户端侧*终端子协议：agent（智能体）调用客户端的 `terminal/create`（传入 `{ command, args, cwd, env }`），由**编辑器**执行进程，然后 agent 读取 `terminal/output` / `wait_for_exit`。这个模型不适合我们：我们的 harness 通过 `dsh-bash` 自行执行 bash（沙箱化的环境清理、后台任务所有权、按会话的 cwd）。将执行路由到编辑器会绕过所有这些机制，并将执行分叉到两个后端。
|
||||
|
||||
研究两个参考 agent（2026-06-18）发现，二者都没有为自己的 shell 工具使用 `terminal/create`——**两者都保持 agent 侧执行，并发出一套 `_meta` 约定**，由 Zed 特殊处理：
|
||||
|
||||
- **`claude-agent-acp`**（`tools.ts`、`acp-agent.ts`）：以 `clientCapabilities._meta.terminal_output` 为门控。`tool_call` 携带 `content: [{ type: 'terminal', terminalId }]` 与 `_meta.terminal_info.{ terminal_id, cwd }`；输出和退出通过 `tool_call_update` 的 `_meta.terminal_output.{ terminal_id, data }` 与 `_meta.terminal_exit.{ terminal_id, exit_code, signal }` 到达。
|
||||
- **`codex-acp`**（`CodexToolCallMapper.ts`、`TerminalOutputMode.ts`）：调用上同样携带 `terminal_info`；输出通过 `_meta.terminal_output`（完整）或 `_meta.terminal_output_delta`（增量），由同一个 `_meta.terminal_output` 能力选择。
|
||||
|
||||
Zed 侧（`crates/agent_servers/src/acp.rs`，已验证）：收到 `ToolCall` 且其 `_meta.terminal_info.terminal_id` 已设置时，注册一个**仅展示**的终端（header = `terminal_info.cwd`，label = `tool_call.title`）；收到 `ToolCallUpdate` 时，`_meta.terminal_output.data` 写入该终端，`_meta.terminal_exit.{exit_code,signal}` 设置状态。客户端通过 `clientCapabilities._meta.terminal_output = true` 声明此能力。`_meta` 本身是 ACP 规范认可的扩展点（在 `ToolCall`/`ToolCallUpdate` 上类型为 `{[k]: unknown} | null`）；这里的*具体键*（`terminal_info`/`terminal_output`/`terminal_exit`）是 Zed 约定，不属于 ACP 规范，但它们是 Zed 集成的事实契约，也是在保持 agent 侧执行的前提下获得终端卡片的唯一方式。
|
||||
|
||||
## 决策
|
||||
|
||||
保持 `dsh-bash` 的 agent 侧执行；通过 `_meta` 约定渲染终端卡片，以能力声明为门控，以 ` ```console ` 文本块作为保底回退。
|
||||
|
||||
1. **能力声明。** `initialize` 读取 `clientCapabilities._meta.terminal_output`，桥接层按连接记住它。
|
||||
2. **提供方无关的展示词汇。** `dsh-tools` 新增一种终端形态的展示结构，工具可返回它——提供方无关（`cwd`、输出 `data`、`exitCode`/`signal`），不含 ACP 类型。`dsh-tool-bash` 为 `bash` 返回该结构（cwd 来自解析后的工作目录；输出与退出从运行结果解析）。
|
||||
3. **桥接映射。** 当客户端声明了该能力时，桥接层将展示结构映射为：在 `tool_call` 上，`content:[…, {type:'terminal', terminalId}]`（工具的任何 `content`，如描述，渲染在终端块之前）+ `_meta.terminal_info.{terminal_id,cwd}`；在 `tool_call_update` 上，`_meta.terminal_output.{terminal_id,data}`（捕获的输出）+ `_meta.terminal_exit.{terminal_id, exit_code|signal}`（解析后的退出），且 update 的文本 `content` 被省略（ACP 的 `tool_call_update.content` 会替换调用的 content 集合，因此重新发送围栏块会覆盖终端内容块）。`terminalId` 由 harness 的 `callId` 派生（稳定、每次调用唯一）。当能力未声明时，桥接层在调用上发送描述内容块，在 update 上发送既有的 ` ```console ` 文本内容——行为不变。
|
||||
4. **退出信息从渲染输出中解析；无新执行路径，无实时流式传输。** 输出在完成时附加（来自 agent 自身的 `tool/result`），不逐 token 流式传输。退出状态（`_meta.terminal_exit.{exit_code,signal}`）确实会发出：纯 `presentResult(args, result)` seam 只能看到内容块，因此 `dsh-tool-bash` 通过解析 `renderResult` 追加的状态标记（`[exit code: N]` / `[killed by signal: …]`）来恢复结构化退出信息——解析是标记发出的精确逆操作，二者在同一文件中共同演进，一个往返测试守护这对关系。资源释放不受影响：无需新增拆除逻辑，因为桥接层从未创建客户端侧终端。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **ACP 客户端侧终端子协议（`terminal/create`）**：明确否决。编辑器将执行进程，绕过 `dsh-bash` 的环境清理、后台任务所有权和按会话的 cwd，并将执行分叉到两个后端。两个参考 agent 以同样的方式否决了它（见上述关键发现）；agent 侧执行加 `_meta` 约定是在保持 harness 执行策略的同时获得终端卡片的唯一形态。
|
||||
- **通过事件 schema 传递结构化退出信息**：否决，改用标记往返方案。纯 `presentResult(args, result)` seam 只能看到内容块，而解析是标记发出的精确逆操作，二者在同一文件中共同演进，由往返测试守护。
|
||||
|
||||
## 后果
|
||||
|
||||
- **Zed 约定的 `_meta` 键。** 终端卡片依赖 Zed 特有的键（`terminal_info`/`terminal_output`/`terminal_exit`），位于 ACP 规范认可的 `_meta` 扩展点内，而非 ACP 终端子协议。不识别这些键的客户端仍然获得文本回退（能力门控确保我们仅在客户端通过 `_meta.terminal_output` 声明支持时才发出这些键），因此非 Zed 客户端不会变差。如果 ACP 日后标准化了 agent 执行的终端，则迁移到该标准并移除约定键。
|
||||
- **能力诚实。** 仅在客户端声明了 `_meta.terminal_output` 时才发出终端元数据；文本回退是对其他所有客户端的契约，绝不可退化。由一个无能力测试覆盖，断言 ` ```console ` 路径。
|
||||
- **terminalId 冲突。** 从每次调用的 `callId` 派生，保证在会话内唯一且在 call/result 对之间稳定；绝不跨调用复用。
|
||||
- **退出信息从渲染文本解析。** 退出信息通过解析 `renderResult` 的状态标记恢复 `exit_code`/`signal`，而非通过事件 schema 传递结构化退出（纯 `presentResult` seam 看不到后者）。解析是标记发出的精确逆操作，且位于同一文件中；往返测试固定了这对关系，标记格式变更若破坏解析则测试套件失败。如果标记格式日后需要与退出信息分道扬镳，则改为在 result 事件上暴露结构化退出。
|
||||
- **提供方无关词汇的蔓延。** 终端展示结构扩大了 `dsh-tools` 的接口面；保持其中立性（不让 ACP 类型泄漏到 `dsh-tools`），且只提供第二个 UI 消费方同样需要的丰富度。
|
||||
|
||||
## 超出范围 / 非目标
|
||||
|
||||
文本块基线仍为无能力声明时的默认行为。以下两项后续工作有意不在此处构建，各自需要单独的 Agent Note：**实时增量流式传输**（在分片到达时发出 `_meta.terminal_output_delta`，需要在 `dsh-bash` 上新增增量输出 seam）；**命令分类**（将 `cat`/`sed` 解析为带文件位置的 `read` 卡片，将 `grep` 解析为 `search`，回退到终端卡片——仅展示，绝不改变实际执行内容）。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-30-subagent-observe-enrich.md: 7140616ac4a9725652ed779cba3d4232b6b5127b
|
||||
2026-06-30-subagent-observe-enrich.zh.md: 5cf81e9ace48650b834f2cf5e8ec7cc81b8b0e4d
|
||||
@@ -0,0 +1,32 @@
|
||||
# Agent Note: Subagent lifecycle enrichment — lastAssistantMessage (observe-only)
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-06-30-subagent-observe-enrich.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The hooks subsystem ([interception seams Agent Note](2026-06-30-interception-seams.md)) lets a plugin observe and gate the agent at lifecycle points. Claude Code and Codex both expose **SubagentStart / SubagentStop** hooks, and CC's carry the subagent's final message. The harness already emits `subagent/start` and `subagent/end` lifecycle events ([the subagent capability-seam](2026-06-21-subagent-capability-seam.md)), but their payloads were minimal (`provider`, `id`, and on end `stopReason`) — not enough for a hooks bridge to report WHAT a subagent produced without separately reaching for the live run.
|
||||
|
||||
This Agent Note enriches the end payload. It is deliberately **observe-only**: no control-flow change and no waterfall. A run-affecting subagent-stop decision (continuation, injection that changes the run) is a separate, larger redesign and stays out of scope.
|
||||
|
||||
## Decision
|
||||
|
||||
**Add `lastAssistantMessage` — the child's final output — to `SubagentRunEndInfo`.** On the settle path it is the readonly typed `SubagentResult.output`, so an observer sees what the child produced without holding the run. On an infrastructure rejection where no `SubagentResult` exists, it is absent and the event reports `stopReason: 'error'`. Providers and listeners are trusted same-process collaborators and honor the borrowed immutable payload contract.
|
||||
|
||||
Both events stay plain **`emit`s**. Async `SubagentService.start()` attaches result observation to the ready provider run, emits `subagent/start`, and then returns the run; an in-process listener can therefore reach the published child via `ctx.agents.get(info.id)`, while a remote provider need not have a local registry entry. A rejected provider start emits neither event. The callbacks remain observe-only and per-listener containment keeps one bad subscriber from stranding a live run or starving later listeners.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**An `agentType` subagent-kind label** (the harness analogue of CC's `subagent_type`) on the request + both lifecycle payloads — an earlier draft shipped it; dropped in review because it is a Claude-Code concept that does not fit our own seam (nothing here interprets it, and the only consumer was a CC-dialect bridge). The CC bridge instead feeds Claude Code's own default matcher value `"general-purpose"` for its SubagentStart/Stop `agent_type` matcher, so this Agent Note ships ONE enrichment: `lastAssistantMessage`.
|
||||
|
||||
**A control-flow `subagent/end`** — deferred; see below.
|
||||
|
||||
## Why observe-only, and what is deferred
|
||||
|
||||
A control-flow `subagent/end` (an awaited waterfall returning a stop/continue decision, like the other interception seams) would require: reshaping `subagent/end` from emit to waterfall, restructuring `SubagentService.start` to await listeners before settling, and implementing the `resume` capability in the in-process provider so a "continue" can actually re-run the child. That belongs to the background/steering subagent redesign the [capability-seam Agent Note](2026-06-21-subagent-capability-seam.md) already defers (the same redesign that unifies long-running-tool handling across subagents and bash). This Agent Note ships the observe-only enrichment a hooks bridge needs today; `FIXME(subagent-continuation)` / `TODO` anchors mark where the control-flow version would land if and when that redesign happens.
|
||||
|
||||
## Consequences
|
||||
|
||||
A hooks bridge (or a native plugin) can now forward the child's `lastAssistantMessage` to a SubagentStop handler by subscribing to the existing emits — no new control-flow surface. The vocabulary addition is documented in [docs/core-data-structures/subagent.md](../../../../docs/core-data-structures/subagent.md) (the events prose) and the two subagent READMEs; the catalog is regenerated. No production behavior changes — the events fire exactly as before, with one more (optional) field on the end payload — so no snapshot or e2e change is needed.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Agent Note: Subagent 生命周期丰富化——lastAssistantMessage（仅观察）
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-06-30-subagent-observe-enrich.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
钩子子系统（[拦截 seam Agent Note](2026-06-30-interception-seams.md)）允许插件在生命周期节点观察和拦截 agent（智能体）。Claude Code 和 Codex 都暴露了 **SubagentStart / SubagentStop** 钩子，且 CC 的钩子携带 subagent 的最终消息。harness 已经发出 `subagent/start` 和 `subagent/end` 生命周期事件（[subagent 能力 seam](2026-06-21-subagent-capability-seam.md)），但其载荷极为精简（`provider`、`id`，以及 end 时的 `stopReason`），不足以让钩子桥接层在不单独访问活跃 run 的情况下报告 subagent 产出了什么。
|
||||
|
||||
本 Agent Note 丰富 end 载荷。它刻意限定为**仅观察**：不改变控制流，不引入 waterfall（瀑布式事件）。影响 run 的 subagent-stop 决策（续行、改变 run 的注入）属于另一个更大的重设计，不在本 Agent Note 范围内。
|
||||
|
||||
## 决策
|
||||
|
||||
**在 `SubagentRunEndInfo` 中添加 `lastAssistantMessage`——子 agent 的最终输出。** 在正常结束路径上，它是只读的类型化 `SubagentResult.output`，观察者无需持有 run 即可看到子 agent 产出了什么。在基础设施拒绝（不存在 `SubagentResult`）的情况下，该字段缺失，事件报告 `stopReason: 'error'`。提供方与监听方是受信任的同进程协作者，遵守借用不可变载荷的契约。
|
||||
|
||||
两个事件仍为普通 **`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`。
|
||||
|
||||
**控制流式 `subagent/end`**：推迟；见下文。
|
||||
|
||||
## 为何仅观察，以及推迟了什么
|
||||
|
||||
控制流式 `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` 锚点标记了控制流版本在重设计发生时的落点。
|
||||
|
||||
## 后果
|
||||
|
||||
钩子桥接层（或原生插件）现在可以通过订阅既有 emit 将子 agent 的 `lastAssistantMessage` 转发给 SubagentStop 处理器，无需新的控制流接口。词汇新增记录在 [docs/core-data-structures/subagent.md](../../../../docs/core-data-structures/subagent.md)（事件行文部分）与两个 subagent README 中；catalog 已重新生成。生产行为无变化——事件触发方式与之前完全一致，end 载荷上多了一个可选字段——因此无需更新快照或 e2e 测试。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-07-plan-mode.md: dfc81c04baeb924ae04fbb51a27d282c5050f217
|
||||
2026-07-07-plan-mode.zh.md: 20662e208a2211a3c6add266845b746b31af20d9
|
||||
197
.agents/notes/archived/feature/2026-07-07-plan-mode.md
Normal file
197
.agents/notes/archived/feature/2026-07-07-plan-mode.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Agent Note: Plan mode — a logged per-agent session mode
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-07-plan-mode.zh.md)
|
||||
|
||||
> **Superseded vocabulary (2026-07-22):** [Collapse named session modes into plan mode](../simplification/2026-07-22-plan-specific-collaboration-state.md) replaces this note's generic `dsh-mode`, `mode/set`, definition map, and `ctx.modes` design with the current plan-specific `dsh-plan-mode`, `plan/mode`, `{ section }`, and `ctx.planMode` contract. The review, boundary, reconstructability, and sandbox-orthogonality decisions below remain in force; generic API examples are retained as the historical design this simplification removed.
|
||||
|
||||
> **Superseded ACP mapping:** [ACP as an automation-only protocol](../simplification/2026-07-23-acp-automation-only-protocol.md) removes the picker, config-option, and elicitation mappings described below. Plan mode remains available to human-facing interfaces.
|
||||
|
||||
## Problem
|
||||
|
||||
Before this change, the harness had no durable way to put one agent into a distinct working stance. Plan mode needs the agent to explore and design under planning guidance, produce a reviewable artifact, cross an explicit approval boundary, and restore that state across resume and fork without making the model-visible request diverge from the session log.
|
||||
|
||||
The extension seams already supplied the surrounding pieces: [`system-prompt/assemble`](../../../../packages/core/system-prompt/README.md) shapes guidance per step and the shipped request is logged in `request/header*` events ([reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md)); [`ctx.userInteraction`](../../../../packages/ui/user-interaction/README.md) carries the approval question and corrective feedback ([ask-user precedent](../../implemented/feature/2026-06-25-ask-user-question.md)); `SessionEventMap` carries durable per-agent facts ([the `todo/write` precedent](../../implemented/feature/2026-06-29-todo-write-tool.md)). The missing piece was the named session state that joins those seams while leaving execution enforcement on the independent sandbox and approval axes.
|
||||
|
||||
## Decision
|
||||
|
||||
The deliverable is **plan mode**. It ships as the first **session mode** — a named, logged, per-agent COLLABORATION state: a mode definition is deployment-configured guidance the model sees, while the mode IN FORCE for an agent is session state folded from its log. Modes are one axis and the enforcement knobs — the sandbox mode, the approval policy — are others: they never read or write each other, matching how Codex keeps its Plan/Default collaboration presets separate from its sandbox and approval settings. One new product package, `@deepseek-ai/dsh-mode` at `packages/mode/mode/`, owns the event vocabulary, a thin `ctx.modes` service, and every listener; the loop does not change. `plan` is the only required definition — the mode-shaped vocabulary exists so a second mode never renames durable event types, not because more modes ship now.
|
||||
|
||||
The state is one `SessionEventMap` member: **`mode/set`**, a log-only, non-surface event carrying `{ mode: string }` with whole-value-replace semantics, plus a pure `foldMode(events)` that returns the mode in force — the last `mode/set`, or the default mode when none exists. Because [the log is the fact channel](../../implemented/architecture/2026-06-30-event-domain-semantics.md), resume, fork, and compaction restore the mode with no extra machinery, and UIs read flips off `session/event`. The default mode is the absence of mode guidance — no section, filtering, or gate. Loading `dsh-mode` still contributes one stable `exit_plan_mode` schema in every mode; that fixed cost avoids tool-catalog churn at mode boundaries.
|
||||
|
||||
A mode's whole surface is soft: a `mode:policy` prompt section renders the active definition's guidance, while `exit_plan_mode` remains in the registered tool catalog across every mode and rejects at execution unless the folded mode is `plan`. A transition therefore changes only the system-prompt portion of the attributable `request/header` on the next step, keeping [reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md) green without changing native schemas or Code Mode's SDK. A mode deliberately enforces NOTHING: no execution gate, no tool filtering, no reach into the sandbox or approval knobs — a user who wants a hard read-only floor while planning switches the sandbox-mode option beside the mode picker, in either order, and neither axis disturbs the other. There is likewise NO per-mode tool allow/deny list — which tools a mode admits is an effects question, parked until tool definitions declare their effects ([Deferred](#deferred)); a mode's restraint is its section's guidance plus the exit review.
|
||||
|
||||
The model leaves plan mode through the **`exit_plan_mode`** tool: its single argument is the plan text, which makes the plan reconstructable from the log, and the tool conducts the review itself through the user-interaction seam — a question whose supporting detail carries the exact plan, with options and a free-text channel, not a bare permission — so an approval flips the logged mode back to the default, and a rejection becomes the corrective error carrying the user's feedback verbatim, which keeps the model planning with direction. A user flips the mode from any surface through `ctx.modes.set()`; the flip is applied at the next turn boundary (session events are turn-enclosed) and narrated to the model once, only when the model-visible state actually changed.
|
||||
|
||||
## High-level API
|
||||
|
||||
### A plan-mode session end to end
|
||||
|
||||
The user switches the session to plan mode through the ACP mode picker or `/plan [message]` in a terminal front door, and from the next step every request ships the configured plan guidance section. When the optional message is present, that same command submits it into the affected step. The `exit_plan_mode` schema was already present in default and remains byte-identical.
|
||||
|
||||
The model explores and designs; the section's guidance is what defers changes into the plan. The sandbox and approval knobs keep whatever the user set them to — a deployment (or user) that wants kernel-enforced read-only during planning pairs plan mode with the independent sandbox-mode option.
|
||||
|
||||
When ready, the model calls `exit_plan_mode` with the plan markdown as its argument; the review question carries that exact markdown as supporting detail — approve, or keep planning, with free-text feedback welcome. A native call also renders the plan card; a Code Mode nested dispatch has no native card, so the review detail is the common presentation surface.
|
||||
|
||||
On approve, the tool flips the logged mode back to the default: the next step drops the plan section while retaining the same tool catalog (the changed header is in the log), and execution tracking from there is already `todo_write`'s job. On keep-planning, the model receives a corrective error carrying the user's feedback text, revises, and re-presents.
|
||||
|
||||
### Deployment configuration
|
||||
|
||||
Mode definitions are validated plugin Config — per repo convention, changeable from `cordis.yml` with no code edit. The deployment must provide the complete `plan` section; the package embeds no model instructions. Additional modes use the same config map:
|
||||
|
||||
```yaml
|
||||
- id: mode
|
||||
name: '@deepseek-ai/dsh-mode'
|
||||
config:
|
||||
modes:
|
||||
plan:
|
||||
section: |
|
||||
You are in plan mode: explore and design, then present the
|
||||
plan for approval through exit_plan_mode.
|
||||
```
|
||||
|
||||
A definition is exactly `{ section }` — there is deliberately no per-mode tool list and no enforcement field ([FAQ](#faq)). Definition names use the lowercase slash-command subset `/^[a-z][a-z0-9_-]*$/u`; `default` is reserved (the absence of policy) and rejected as a key. An invalid name or unknown definition key — a `tools` list or an `access` cap included — fails validation at load; an unknown mode name fails loudly at `set()` time.
|
||||
|
||||
### In the terminal
|
||||
|
||||
Terminal front doors get one entry command per configured definition through the plugin-owned command registry (`@deepseek-ai/dsh-commands`): `dsh-mode` registers `/plan [message]` for the required definition and, for example, `/review [message]` when `review` is configured. Each command records its named switch; a non-empty optional message is trimmed and passed to `agent.steer()`, which places it in a running agent's next step or delegates to `send()` for a new idle turn. The command name and result stay out of model history, while that explicit message is logged as an ordinary user message under the selected mode. The synthetic `default` entry contributes no command. The exit review prompts right in the terminal with no new machinery: it is an ordinary user-interaction question, so it rides the composed user-interaction provider's prompt queue that `ask_user_question` already uses.
|
||||
|
||||
### Over ACP
|
||||
|
||||
The mode PICKER is this package's surface: `session/new`/`session/load` advertise `availableModes`/`currentModeId` from `ctx.modes` (consumed opportunistically via `ctx.get`, the `tool-bash` pattern), `session/set_mode` calls `set()` and notifies `current_mode_update` optimistically (the pending mode IS the user's selection; the logged `mode/set` follows at the boundary), and a `session/event` listener re-notifies on each logged flip that differs from the last sent. The exit tool reuses the user-interaction ACP provider's elicitation flow; its ACP mapping carries the review `detail` because Code Mode nested dispatches have no native plan card, while native calls may additionally stream the plan card. Individual environment knobs — sandbox mode, approval policy, the model — are NOT modes and belong to `session/set_config_option` ([FAQ](#faq)).
|
||||
|
||||
### For agent creators
|
||||
|
||||
`ctx.modes` is the whole programmatic surface: `list()` returns the configured definitions plus the synthetic `default` entry (for pickers), `get(agent)` returns the folded mode plus any pending intent, and `set(agent, mode)` validates the name against `list()`'s vocabulary and records the boundary-applied intent — `default` is always a valid target, so exiting a mode is the same call as entering one. There is no creation-time mode option — a caller selects through `set()` before the first turn, which flushes identically. There is no live `agent/*` mirror to subscribe: UIs read `mode/set` off `session/event`, per [event-domain semantics](../../implemented/architecture/2026-06-30-event-domain-semantics.md).
|
||||
|
||||
## Detailed design
|
||||
|
||||
### Vocabulary
|
||||
|
||||
```text
|
||||
'mode/set': { mode: string } // SessionEventMap merge in dsh-mode: log-only, non-surface,
|
||||
// whole-value replace — the last one in the log wins
|
||||
DEFAULT_MODE = 'default' // the fold of a log with no mode/set; reserved, not definable
|
||||
```
|
||||
|
||||
The payload carries no reason/provenance field: a tool-driven flip sits next to its `tool/call` in the log and a user flip sits at its turn boundary, so the cause is log-adjacent — the same "narrative fields are derivable" call the [reconstructability Agent Note](../architecture/2026-07-05-reconstructable-requests.md) made for request-header facts (the in-flight `env/state` event carries a `source` precisely because its drift variant has NO log-adjacent cause — a contrast, not a conflict). Mode names are config-declared vocabulary, not opaque cross-boundary ids, so they stay bare strings (no `Branded<B>`).
|
||||
|
||||
### Config and the resolve step
|
||||
|
||||
```text
|
||||
interface ModeDefinition { section: string } // prompt text — a mode's whole vocabulary
|
||||
interface ModeConfig { modes: Record<string, ModeDefinition> } // plan is required and owns its complete prompt
|
||||
resolveConfig(config): ResolvedModes // explicit resolve (the dsh-bash template), fail-loud:
|
||||
// missing plan, 'default', blank sections, and unknown keys rejected
|
||||
```
|
||||
|
||||
The one-field shape is deliberate minimalism, not the final vocabulary: a per-tool policy dimension returns as effects metadata on tool definitions ([Deferred](#deferred)), read here rather than re-declared per mode — the config shape must not need a migration when it arrives.
|
||||
|
||||
### The fold, the service, and the flush
|
||||
|
||||
`foldMode(events)` is pure (exported for reconstructors and tests) and folds the append-only session log directly; `mode/set` is not a surface node, so compaction cannot shadow it. `set(agent, mode)` validates the name against `list()`'s vocabulary — the configured definitions plus the reserved `default`, which is rejected as a config KEY but always accepted as a `set()` TARGET — drops a no-op (target equals pending, else current), and otherwise records `{ mode, narrate }` in a `WeakMap` pending-intent slot. It cannot append immediately because [every session event is turn-enclosed](../../implemented/architecture/2026-06-15-turn-enclosure-invariant.md) and an idle agent has no open turn.
|
||||
|
||||
Contained listeners on the loop's interception seams ([defensive patterns](../../../../docs/defensive-patterns.md): a policy plugin must not block a prompt or a turn) flush the pending intent as a `mode/set` append — `agent/prompt-submit` fires inside the just-opened turn before its first assembly, and `agent/turn-continuation` fires after an ordinary step closes before its successor. Automatic request recovery bypasses continuation, so a prepended `agent/request-error` wrapper delegates through the composed policy and asynchronous backoff, then flushes only a `retry` decision before the waterfall returns to the loop; an effect-scoped lifetime guard suppresses a captured wrapper that resumes after plugin disposal. All three paths sit outside tool execution and log publication (post-commit `session/event` observers are observe-only), so every step runs under the mode its assembly folded. When the flushed mode differs from the fold at the last `request/header`, the flush appends one coalesced `context/message` notice in the same frame ("The user switched this session to plan mode."); the user-visible narration cases are enumerated in the [FAQ](#faq).
|
||||
|
||||
### The soft layer: a computed section and a stable exit schema
|
||||
|
||||
The registered prompt section reads the calling agent's mode from `AssembleContext.agent` and resolves to the active definition's guidance or `''`. The loop renders per step and logs a complete `request/header` whenever the rendered header changes, so entering or leaving a mode is attributable. The section is static per mode and the plan itself stays in the conversation as messages and tool arguments; re-injecting separate plan state on every request ([Prior art](#prior-art)'s compaction-survival hack) is unnecessary prompt churn.
|
||||
|
||||
The guidance contribution is `{ name: 'mode:policy', order: 50, text: context => … }`: after persona (0), before tool guidance (100–199), and empty for default or agent-less assembly. `exit_plan_mode` is registered once through `ctx.tools` and never filtered, so native schemas and Code Mode's generated SDK remain byte-identical across mode switches; a deployment without `dsh-mode` lacks that one binding. There is NO `tools/pre-execute` listener: a mode gates nothing, while the exit tool's own folded-mode check rejects out-of-plan calls. The exit review is a question with options and feedback, not a permission, so it lives inside the tool's execution over the user-interaction seam.
|
||||
|
||||
### `exit_plan_mode`
|
||||
|
||||
`defineTool` has one required `plan: string` argument. Native execution records it in the ordinary `tool/call`; Code Mode records the outer `run_code` source before execution and appends the normalized nested arguments in `tool/code-dispatch` after the dispatch settles. `execute` rejects an agent-less call (the [`todo_write` precedent](../../implemented/feature/2026-06-29-todo-write-tool.md)), rejects any folded mode other than `plan`, rejects an empty or heading-less plan before asking the reviewer, then conducts one single-select `ctx.userInteraction.ask()` review whose `detail` is the exact plan — approve or keep planning — with free-text feedback open. Only exactly one `Approve` selection consents; every other shape fails closed. Approval records a SILENT boundary-applied intent to switch to `default` and returns a short confirmation. The deployment guidance tells the model to make this the only and final tool call in its response; if a model violates that rule, the runtime still holds plan guidance for the rest of the batch, and the next step logs a changed header with the guidance removed and tool schemas unchanged. Every non-approval outcome returns a corrective `isError` and leaves the mode in `plan`.
|
||||
|
||||
Its [render intent](../../implemented/architecture/2026-07-02-tool-render-intent-union.md), decided up front: `presentCall` is a `generic` card titled by the plan's first heading with the plan markdown as content, plus a `generic` result card. Native front doors show that card before the question; Code Mode nested dispatches do not produce native call-card events, so the user-interaction `detail` independently carries the same plan on every provider. The seam is consumed opportunistically (`ctx.get('userInteraction')`), so `dsh-mode` composes without it and degrades to the manual exit pinned in the [FAQ](#faq).
|
||||
|
||||
### Dependencies and surfaces
|
||||
|
||||
`dsh-mode` is one product package, not a capability-seam trio ([Alternatives considered](#alternatives-considered)): it peers on `cordis`, `dsh-session`, `dsh-agent`, `dsh-tools`, and `dsh-system-prompt`, injects `['tools', 'systemPrompt']`, and reads `ctx.userInteraction` opportunistically at execute time (a type-only peer edge on `dsh-user-interaction`); its only UI-facing edges are optional type-only peers (`dsh-commands` for the per-definition entry commands). Beyond the `ctx.modes` call surface everything participates through listeners, so dropping the package gracefully removes modes rather than breaking a consumer. Terminal front doors need no mode-specific code: `dsh-mode` itself registers each definition's command on the command registry when one is composed (an optional type-only peer edge on `dsh-commands`), and the exit review rides the composed user-interaction provider's prompt queue. The ACP wire mapping is pinned in [High-level API](#over-acp); package-wise the bridge takes a type-only peer edge on `dsh-mode` and reads the service opportunistically, so a bridge without the plugin behaves exactly as today.
|
||||
|
||||
### The recorded scenario and the harness op
|
||||
|
||||
`input.json` gains one step op, `{ "op": "setMode", "modeId": "plan" }`, driven through the real `session/set_mode` RPC, and a scripted `elicitationAnswers` queue. The `plan-mode` scenario enters plan before turn 1, runs a real `cat` under the independently configured sandbox, presents a plan through `exit_plan_mode`, receives scripted approval, then edits on the next step. The first `request/header` contains the full stable toolset plus the configured mode section; the post-approval changed header retains byte-identical tool schemas and removes only that section. `plan-mode-reject` pins corrective free-text feedback and the unchanged plan state. Both recordings replay host commands under Seatbelt or bwrap; backend-specific sandbox denial stays at the bash-tool unit tier.
|
||||
|
||||
### The mechanical tail
|
||||
|
||||
No new cordis event is declared (`mode/set` rides `session/event`; the listeners attach to existing waterfalls), so the events catalog is untouched. Regenerated in the same change: the persistence log catalog (`mode/set`), the services catalog (`ctx.modes`, JSDoc-complete), the config catalog (`ModeConfig`), the tool catalog (`exit_plan_mode`), the producer/consumer map and doc graphs, and the module graph. Repo plumbing: a root tsconfig `paths` entry, the new group's README plus a [packages map](../../../../packages/README.md) row (a new top-level group is the deliberate act that table names), an `architecture.md` capability-services row for `ctx.modes` (budget-checked), and the cookbook row upgrade.
|
||||
|
||||
## Deferred
|
||||
|
||||
Each behind its own decision: subagent mode inheritance via a forwarded creation-time mode option (removed as unconsumed; it returns with its first consumer), preset modes beyond `plan` (read-only, accept-edits), the idle-record primitive if pending-intent loss proves real, and — the big one — **effects self-declaration on tool definitions**: a per-tool read-only/mutating classification (the MCP `ToolAnnotations` vocabulary — `readOnlyHint`/`destructiveHint` — is the natural template, with its untrusted-hint caveat implying trust tiers). That item is what a general per-mode tool policy waits on: this Agent Note first shipped an interim per-mode name allowlist and removed it before release — a hand-maintained list mislabels the effects question, must track every tool a deployment composes, and rots silently as tools arrive — so mode-scoped tool availability (and per-tool `ask` policies) returns as a CONSUMER of declared effects, which is its restart trigger.
|
||||
|
||||
The ACP automation composition does not mount plan mode or the question tool. Human-facing compositions own plan selection and review; focused plan-mode tests and interactive-interface snapshots pin its logged state, guidance, review, and stable tool schemas.
|
||||
|
||||
## FAQ
|
||||
|
||||
Behavioral clarifications of the chosen design; rejected designs live in [Alternatives considered](#alternatives-considered), accepted costs in [Consequences](#consequences).
|
||||
|
||||
**When does a user's mode flip take effect?** At the next pre-assembly boundary: `agent/prompt-submit` covers the first step, `agent/turn-continuation` covers a normal successor, and the post-composed `agent/request-error` retry decision covers automatic recovery. A mode selected while a request or retry backoff is in flight therefore shapes the following model request. This is the "applies to subsequent requests" semantics every product in [Prior art](#prior-art) ships.
|
||||
|
||||
**When is a mode change narrated to the model?** Only when the model-visible state actually changed: the flush compares the flushed mode against the fold at the last `request/header` and narrates once, coalesced. A net-zero flip sequence (plan then back, all before the boundary) narrates nothing; a tool-driven exit narrates through its own tool result instead; a mode set before the first turn narrates nothing — the section is the state statement. The principle is the in-flight env-state proposal's boundary narration: a silently flipped prompt surface leaves the transcript arguing from a state the header no longer has.
|
||||
|
||||
**What happens on resume when the config no longer defines the folded mode?** A folded mode name the current config no longer defines behaves as the default mode without a notice, so the session neither gains a substitute restriction nor becomes unusable. `set()`'s loud validation covers only the write path; a resumed log answers to the config it finds.
|
||||
|
||||
**What if a deployment composes no user-interaction provider?** Plan mode stays safe but manual: `ctx.userInteraction.ask()` throws `NO_PROVIDER` (and an absent seam never resolves at all), the tool returns the corrective `isError`, and the exit degrades to the user toggling modes — never to an unreviewed exit. The mode section tells the model to present its plan through `exit_plan_mode` — and to ask the user in prose if that fails — so it keeps presenting instead of stalling.
|
||||
|
||||
**Why is there no per-mode tool allowlist?** Because "which tools are safe in a planning mode" is a property of each TOOL (its effects), not of the mode — a per-mode name list re-declares that fact in the wrong home, must enumerate every tool the deployment composes (MCP servers included), and rots silently as tools arrive. Until tool definitions declare their effects ([Deferred](#deferred), where the removed interim allowlist is archived with its restart trigger), a mode restrains by its section and the exit review; the exposure is an accepted cost ([Consequences](#consequences)).
|
||||
|
||||
**Do subagents inherit the parent's mode?** A fork child inherits for free — the parent's `mode/set` is inside the seeded prefix. A spawn child starts in the default mode; a creation-time mode option and automatic forwarding by subagent providers are deferred together ([Deferred](#deferred)).
|
||||
|
||||
**How does plan mode relate to the sandbox's read-only mode?** They are separate axes that never touch: the mode is the collaboration stance (a `mode/set` fold), the sandbox mode is an enforcement knob (a `bash/sandbox-mode` fold, [the sandbox Agent Note](2026-07-06-sandbox.md)) — plan mode neither reads nor caps it, exactly as Codex keeps its Plan/Default presets separate from its sandbox and approval settings. A user who wants kernel-enforced read-only while planning sets both: flip the mode picker AND the sandbox-mode option, in either order; each switch changes only its own fold, so there is no interference and no restore step to crash out of. The log attributes each axis to its own event — the stance to `mode/set`, the confinement to `bash/sandbox-mode`.
|
||||
|
||||
**Why aren't sandbox mode, approval policy, or the model themselves modes?** They are individual environment knobs independent of collaboration state. The retired ACP mapping is recorded by the [automation-only protocol decision](../simplification/2026-07-23-acp-automation-only-protocol.md). A mode definition may later bundle env facts (applied through `ctx.envState` where mounted) so a Codex-style preset stays a single mode; fusing approval policy into the mode CONCEPT itself is rejected in [Alternatives considered](#alternatives-considered).
|
||||
|
||||
## Prior art
|
||||
|
||||
A survey of shipped plan modes (Claude Code, Cursor, Copilot, OpenCode, Gemini CLI, Cline, Windsurf, Codex) shows the same five parts everywhere — the low-authority tool policy, plan artifact, approval moment, execution-state switch, and durable state that [Problem](#problem) builds on.
|
||||
|
||||
The mode surface is a LIST everywhere it is advertised, never a boolean: Claude Code's picker offers `plan` beside `acceptEdits` (plus an auto-mode entry into plan), and Codex exposes `Plan` beside `Default` as collaboration-mode presets while keeping approval and sandbox settings separate. The ACP transport does not advertise this human-facing control.
|
||||
|
||||
The deployment-owned example prompt borrows the instrumental behavior, not product-specific mechanics. From Codex: remain in plan mode despite imperative implementation language, explore before asking, distinguish repository facts from user-owned choices, and make the plan decision-complete across APIs, data flow, failures, tests, and assumptions. From Claude Code: prohibit mutations and commits, prefer existing patterns, use questions only for requirements or approach choices, and finish through the exit tool rather than a prose approval request. It deliberately omits Codex protocol tags and Claude's plan-file or phased-subagent machinery because those belong to their runtimes, not this plugin contract.
|
||||
|
||||
The ecosystems that leave modes to convention show the failure shapes to avoid. Pi-style mode extensions fight over a last-wins global active-tool list, enforce "read-only" by prompt text alone (a hallucinated call to a still-registered tool executes), and re-inject plan state into every request to survive compaction. The contested global list and the re-injection hack close structurally here — per-agent folded state, and a log-only non-surface event compaction cannot shadow. The prompt-only shape, by contrast, is deliberately KEPT — it is what Codex ships for Plan, and it is why the mode axis composes freely with the enforcement axes: a deployment that wants a hard floor pairs the mode with the independent sandbox knob instead of the mode carrying its own enforcement ([FAQ](#faq)).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Permission modes as the concept (the Claude Code shape).** One `permissionMode` fusing approval policy and tool policy. Here those are two axes with two owners: the approval seam owns "who answers this question", modes own "what surface does the model get". ACP models them as related but distinct (a mode may select an approval policy later — a mode definition gains a field, not a merger).
|
||||
|
||||
**A capability-seam trio.** Interface/implementation/consumer fits a swappable backend; a mode's variable parts are config values, not implementations. Splitting would manufacture an empty implementation package — the same "don't split preemptively" call the approval seam and [`todo/`](../../implemented/feature/2026-06-29-todo-write-tool.md) made.
|
||||
|
||||
**Loop-owned mode state.** Rejected on the standing rule (plugins, not loop changes): every hook the feature needs — assemble, pre-execute, turn boundaries, session events — is already a documented seam, so a loop edit would buy nothing but coupling.
|
||||
|
||||
**A per-mode tool allowlist with a deny-by-default gate (the first shipped shape).** Removed before release. A hand-maintained name list re-declares a per-TOOL fact (its effects) per MODE: it must enumerate every tool the deployment composes — MCP servers and future registrations included — and it rots silently as tools arrive (a new read-only tool is blocked until someone edits every mode; the author burden lands on whoever knows the mode, not whoever knows the tool). It also over-promises: the list looks like a security boundary while the real boundary for anything non-shell does not exist. The general dimension is parked on effects self-declaration ([Deferred](#deferred)); the consequence — plan mode is guidance-only, the very Pi hole the gate once closed — is accepted deliberately, priced in [Consequences](#consequences).
|
||||
|
||||
**An `access` sandbox cap on the mode (the second shipped shape).** Also removed before release. `ModeDefinition.access` clamped the bash seam's per-call sandbox resolution to a mode-declared ceiling (a `bash/resolve-mode` waterfall + ladder-min listener, with guards withholding bash under an unconfinable executor and denying escalation mid-mode). The state stayed orthogonal — the clamp never wrote the sandbox knob — but the AXES did not: entering plan changed what the sandbox enforced, fusing the collaboration stance with an enforcement level and contradicting the Codex-shaped separation the review converged on (Plan/Default presets never touch sandbox or approval settings). One user-visible symptom of the fusion: flipping the sandbox option to `workspace-write` while planning silently did nothing. The cap, the waterfall, and the mode→bash dependency edge were removed together; a deployment gets kernel-enforced read-only planning by pairing the mode with the independent sandbox-mode option, and a mode-triggered PRESET (a mode definition bundling suggested knob values, applied as ordinary knob switches) can return later without re-fusing the axes.
|
||||
|
||||
**Runtime-only mode (UI- or bridge-local, unlogged).** Resume and fork would silently drop the mode, and the header deltas a mode causes would have no attributable cause in the log. Logged state is what makes the mode auditable and restorable for free.
|
||||
|
||||
**Mode flips as `context/message` via `agent.inject()`.** Reuses an existing turn-enclosure path, but puts policy state into the model transcript — the model does not need to be told twice (the section already tells it), and a log-only fact should not occupy surface.
|
||||
|
||||
**A plan-file store (`.plans/` directory).** A second durable home for what the log already carries replayably; a deployment wanting files can add a tool that writes them. One home per fact.
|
||||
|
||||
**A boolean `planMode` instead of named modes.** Too narrow for the surface the repo already tracks: ACP advertises a mode LIST and the shipped pickers fill it with more than plan ([Prior art](#prior-art)); generalizing later would rename durable event vocabulary. The string-shaped mechanism costs nothing extra now; only `plan` ships as a definition.
|
||||
|
||||
**A tool-policy-stack service (the Pi-critique remedy).** A dedicated composition service for tool policies is premature: this implementation performs no mode-scoped tool filtering, and future effect policies can compose through the existing guarded execution seams. Formalize only when declared tool effects create a concrete composition requirement.
|
||||
|
||||
**Exit approval through the approval seam (a `{ kind: 'ask' }` gate decision).** The original sketch, natural while the approval seam was the only asking machinery in flight — but it seats a review in a permission chair: the seam's outcome vocabulary is deliberately closed and one-shot (`allowed-once`/`rejected`), so a rejection carries no feedback and an approval can never grow options (approve-and-accept-edits). The exit moment is a question, not a permission — the user-interaction seam gives it options plus the free-text channel, and the rejection feedback reaches the model verbatim. The approval seam remains the right seat for genuine permission gates (the sandbox escalation), and the registry's `ask` vocabulary stays available to deployments that want one there.
|
||||
|
||||
**Exit by prose or steering instead of a tool.** No artifact and no approval moment — the tool's argument IS the reviewable plan, and its review question is what gives the human a structured yes/no attached to the exact transition.
|
||||
|
||||
## Consequences
|
||||
|
||||
What holds now, pinned by the unit, protocol, snapshot, and real-API tiers:
|
||||
|
||||
- The mode in force is a pure function of the session log: resume and fork restore it with no extra machinery, and a `mode/set` is followed by a matching complete `request/header` on the next changed step.
|
||||
- A user-driven flip narrates exactly once at the next boundary and a net-zero flip sequence narrates nothing; a tool-driven exit narrates only through its tool result.
|
||||
- In default mode the plugin contributes no mode section but does contribute the stable `exit_plan_mode` schema; a deployment without `dsh-mode` lacks that binding.
|
||||
- Native tool schemas and Code Mode's SDK stay byte-identical across default, plan, and custom-mode transitions; only the configured guidance section changes.
|
||||
- Plan mode changes nothing on the enforcement axes: the toolset, the sandbox mode, escalation, and the approval policy behave identically in plan and default — pairing the mode with the independent sandbox/approval knobs is how a deployment hardens planning.
|
||||
- Mode definitions are changeable from `cordis.yml` with no code edit; the complete plan instructions are required there, while missing plan config, malformed definitions, and unknown keys fail at load and unknown mode names fail at `set()`.
|
||||
- `exit_plan_mode` is always advertised, rejects outside plan, drops only plan guidance after approval, and carries keep-planning feedback in a corrective `isError`; each human-facing surface's user-interaction provider carries the review.
|
||||
- The docs tail shipped with the landing: READMEs, regenerated catalogs (persistence log, config, cordis services, tools), the packages map and architecture rows, and the cookbook row.
|
||||
|
||||
The accepted costs: a pending user flip set while idle is lost if the process dies before the next turn (the UI re-applies; the idle-record primitive is the escape hatch if this bites in practice). A mode transition changes the system prompt at order 50, so the cache path from that point onward changes, but the tool schemas and Code Mode SDK no longer churn. **A mode restrains by guidance alone**: a model that ignores the section CAN mutate during plan — the review moment, the session log, and independent sandbox, approval, and filesystem policies are the containment surface. Hardening planning means setting those knobs, not widening the mode; the removed enforcement shapes and their effects-declaration restart trigger remain in [Alternatives considered](#alternatives-considered) and [Deferred](#deferred). Human-facing interfaces own the plan picker and review interaction; the ACP automation transport carries neither.
|
||||
197
.agents/notes/archived/feature/2026-07-07-plan-mode.zh.md
Normal file
197
.agents/notes/archived/feature/2026-07-07-plan-mode.zh.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Agent Note: plan mode——记录到日志的逐 agent 会话模式
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-07-plan-mode.md) | 中文
|
||||
|
||||
> **已取代的词汇（2026-07-22）：**[将具名会话模式收敛为 plan mode](../simplification/2026-07-22-plan-specific-collaboration-state.md) 已将本笔记中通用的 `dsh-mode`、`mode/set`、定义 map 与 `ctx.modes` 设计，替换为当前 plan 专用的 `dsh-plan-mode`、`plan/mode`、`{ section }` 和 `ctx.planMode` 契约。下文的评审、边界、可重建性与沙箱正交性决策仍然有效；通用 API 示例则作为此次简化所移除的历史设计保留下来。
|
||||
|
||||
> **已取代的 ACP（Agent Client Protocol）映射：**[ACP 作为仅面向自动化的协议](../simplification/2026-07-23-acp-automation-only-protocol.md)移除了下文所述的选择器、配置选项和 elicitation 映射。面向人类的接口仍可使用 plan mode。
|
||||
|
||||
## 问题
|
||||
|
||||
此次变更之前，harness 无法持久地让某个 agent（智能体）采用独特的工作姿态。Plan mode 要求 agent 在规划指引下探索和设计，产出可供评审的产物，跨过明确的审批边界，并在恢复与 fork 后还原该状态，同时不能让模型可见请求偏离会话日志。
|
||||
|
||||
既有扩展 seam 已经提供了周边机制：[`system-prompt/assemble`](../../../../packages/core/system-prompt/README.md) 为每个步骤塑造指引，已发送的请求则记录在 `request/header*` 事件中（参见[可重建性](../../implemented/architecture/2026-07-05-reconstructable-requests.md)）；[`ctx.userInteraction`](../../../../packages/ui/user-interaction/README.md) 承载审批问题与纠正反馈（参见 [ask-user 先例](../../implemented/feature/2026-06-25-ask-user-question.md)）；`SessionEventMap` 承载逐 agent 的持久事实（参见 [`todo/write` 先例](../../implemented/feature/2026-06-29-todo-write-tool.md)）。缺少的是将这些 seam 连在一起的具名会话状态，同时仍让独立的沙箱轴与审批轴负责执行约束。
|
||||
|
||||
## 决策
|
||||
|
||||
交付项是 **plan mode**。它作为首个**会话模式**发布，即一个具名、记录到日志且逐 agent 生效的协作状态：模式定义是由部署配置、供模型查看的指引；对某个 agent 生效的模式则是从其日志折叠出的会话状态。模式构成一条轴，强制约束旋钮——沙箱模式与审批策略——构成其他轴；它们从不互相读写，这与 Codex 将 Plan／Default 协作预设同沙箱及审批设置分开的做法一致。新的产品包（package）`@deepseek-ai/dsh-mode` 位于 `packages/mode/mode/`，拥有事件词汇、精简的 `ctx.modes` 服务和全部监听器；循环无需改动。`plan` 是唯一的必需定义；采用模式形状的词汇，是为了以后增加第二种模式时无需重命名持久事件类型，而不是因为当前还会发布其他模式。
|
||||
|
||||
该状态是 `SessionEventMap` 的一个成员：**`mode/set`** 是只记录日志、不进入 surface 的事件，携带具有整值替换语义的 `{ mode: string }`；另有纯函数 `foldMode(events)` 返回生效模式，即最后一个 `mode/set`，没有该事件时则返回默认模式。由于[日志是事实通道](../../implemented/architecture/2026-06-30-event-domain-semantics.md)，恢复、fork 和压缩无需额外机制即可还原模式，UI 则从 `session/event` 读取模式切换。默认模式表示不存在模式指引，即没有段落、过滤或门禁。加载 `dsh-mode` 后，每种模式仍会贡献同一个稳定的 `exit_plan_mode` schema；这项固定成本避免了模式边界处的工具目录抖动。
|
||||
|
||||
模式的所有外显行为都是软约束：`mode:policy` 提示词段落渲染当前定义的指引，而 `exit_plan_mode` 在每种模式下都留在已注册的工具目录中，仅当折叠模式不是 `plan` 时才在执行阶段拒绝。因此，转换只会在下一步骤改变可归因 `request/header` 中的系统提示词部分，从而在不改变 Native schema 或 Code Mode SDK 的情况下继续满足[可重建性](../../implemented/architecture/2026-07-05-reconstructable-requests.md)。模式有意不强制执行任何约束：没有执行门禁，不过滤工具，也不触及沙箱或审批旋钮。若用户希望规划期间存在硬性的只读下限，可以在模式选择器旁切换沙箱模式选项；二者先后顺序任意，任何一条轴都不会扰动另一条轴。同样也不存在逐模式的工具允许／拒绝清单；模式允许哪些工具属于副作用问题，在工具定义能够声明自身副作用前暂缓处理（见[延期工作](#deferred)）。模式只依靠其段落指引与退出评审来约束行为。
|
||||
|
||||
模型通过 **`exit_plan_mode`** 工具离开 plan mode。其唯一参数是 plan 文本，因此可以从日志重建 plan；该工具自行通过用户交互 seam 完成评审：问题的辅助详情携带确切 plan，并提供选项与自由文本通道，而不是只有一项裸权限。审批通过后，记录到日志的模式切回默认模式；拒绝则成为携带用户逐字反馈的纠正错误，让模型能沿明确方向继续规划。用户可从任意接口通过 `ctx.modes.set()` 切换模式；切换会在下一个轮次边界应用（会话事件都封闭在轮次内），且只有模型可见状态确实变化时才向模型讲述一次。
|
||||
|
||||
## 高层 API
|
||||
|
||||
### 一次端到端的 plan-mode 会话
|
||||
|
||||
用户通过 ACP 模式选择器或终端入口中的 `/plan [message]` 将会话切换到 plan mode；从下一步骤开始，每个请求都携带已配置的 plan 指引段落。如果给出可选消息，同一命令还会把它提交到受影响的步骤中。`exit_plan_mode` schema 在默认模式下已经存在，并会保持逐字节不变。
|
||||
|
||||
模型进行探索与设计；段落中的指引会让它把变更推迟到 plan 中。沙箱与审批旋钮保持用户设置的值不变；希望规划期间由内核强制只读的部署方（或用户），可以把 plan mode 与独立的沙箱模式选项配合使用。
|
||||
|
||||
准备就绪后，模型调用 `exit_plan_mode`，并把 plan markdown 作为参数；评审问题将这段确切 markdown 作为辅助详情，用户可以批准，也可以要求继续规划并自由填写反馈。Native 调用还会渲染 plan 卡片；Code Mode 嵌套分发没有 Native 卡片，因此评审详情是共用的呈现接口。
|
||||
|
||||
批准后，工具把记录到日志的模式切回默认模式：下一步骤会移除 plan 段落，但保留同一个工具目录（变化后的 header 已记录到日志），此后的执行跟踪本就由 `todo_write` 负责。要求继续规划时，模型会收到携带用户反馈文本的纠正错误，随后修改并再次呈现。
|
||||
|
||||
### 部署配置
|
||||
|
||||
模式定义是经过校验的插件 Config；依照仓库约定，它可以通过 `cordis.yml` 修改，无需编辑代码。部署必须提供完整的 `plan` 段落；该包不内置任何模型指令。其他模式使用同一份配置 map：
|
||||
|
||||
```yaml
|
||||
- id: mode
|
||||
name: '@deepseek-ai/dsh-mode'
|
||||
config:
|
||||
modes:
|
||||
plan:
|
||||
section: |
|
||||
You are in plan mode: explore and design, then present the
|
||||
plan for approval through exit_plan_mode.
|
||||
```
|
||||
|
||||
定义的精确形状是 `{ section }`；其中有意不提供逐模式工具清单或强制约束字段（见[常见问题](#faq)）。定义名称使用小写斜杠命令子集 `/^[a-z][a-z0-9_-]*$/u`；`default` 是保留项（表示没有策略），不能用作键。名称无效或存在未知定义键——包括 `tools` 清单或 `access` 上限——会在加载时校验失败；未知模式名称则会在调用 `set()` 时大声失败。
|
||||
|
||||
### 在终端中
|
||||
|
||||
终端入口通过插件自有的命令注册表（`@deepseek-ai/dsh-commands`），为每个已配置定义获得一条进入命令：`dsh-mode` 为必需定义注册 `/plan [message]`，例如还会注册 `/review [message]`（当配置 `review` 时）。每条命令都记录其具名切换；非空的可选消息会去除首尾空白并传给 `agent.steer()`，后者会把消息放入运行中 agent 的下一步骤，或委托给 `send()` 以开启新的空闲轮次。命令名称与结果不会进入模型历史；这条显式消息则会作为所选模式下的普通用户消息记录到日志。合成的 `default` 条目不贡献命令。退出评审无需新机制即可直接在终端中提示：它是普通的用户交互问题，因此会进入组合后的用户交互提供方提示队列，与 `ask_user_question` 使用的队列相同。
|
||||
|
||||
### 通过 ACP
|
||||
|
||||
模式选择器是该包的对外接口：`session/new`／`session/load` 会通告 `availableModes`／`currentModeId`，其值来自 `ctx.modes`（通过 `ctx.get` 机会式消费，沿用 `tool-bash` 模式）；`session/set_mode` 调用 `set()` 并乐观通知 `current_mode_update`（待生效模式就是用户的选择，记录到日志的 `mode/set` 会在边界处跟进）；`session/event` 监听器则会在每次已记录切换不同于最近一次已发送值时再次通知。退出工具复用用户交互 ACP 提供方的 elicitation 流程；其 ACP 映射会携带评审 `detail`，因为 Code Mode 嵌套分发没有 Native plan 卡片，而 Native 调用还可以额外流式传输该卡片。沙箱模式、审批策略和模型等单项环境旋钮不是模式，应归入 `session/set_config_option`（见[常见问题](#faq)）。
|
||||
|
||||
### 面向 agent 创建方
|
||||
|
||||
`ctx.modes` 是完整的程序化接口：`list()` 返回已配置定义和供选择器使用的合成 `default` 条目；`get(agent)` 返回折叠模式与可能存在的待生效意图；`set(agent, mode)` 则根据 `list()` 的词汇校验名称，并记录将在边界应用的意图。`default` 始终是有效目标，因此退出模式与进入模式使用同一次调用。创建时没有模式选项；调用方在首个轮次前通过 `set()` 选择模式，随后以相同方式刷写。系统也不提供可订阅的实时 `agent/*` 镜像：UI 依照[事件领域语义](../../implemented/architecture/2026-06-30-event-domain-semantics.md)读取 `mode/set`，该事件来自 `session/event`。
|
||||
|
||||
## 详细设计
|
||||
|
||||
### 词汇
|
||||
|
||||
```text
|
||||
'mode/set': { mode: string } // SessionEventMap merge in dsh-mode: log-only, non-surface,
|
||||
// whole-value replace — the last one in the log wins
|
||||
DEFAULT_MODE = 'default' // the fold of a log with no mode/set; reserved, not definable
|
||||
```
|
||||
|
||||
载荷不携带原因／溯源字段：工具驱动的切换在日志中紧邻其 `tool/call`，用户切换则位于轮次边界，因此原因就在日志相邻位置。这与[可重建性 Agent Note](../architecture/2026-07-05-reconstructable-requests.md)针对请求头事实所作的「叙述字段可以派生」决策相同（进行中的 `env/state` 事件之所以携带 `source`，正是因为其漂移变体在日志相邻位置没有原因；二者形成对照，并不冲突）。模式名称是配置声明的词汇，不是不透明的跨边界 id，因此仍使用裸字符串（不使用 `Branded<B>`）。
|
||||
|
||||
### 配置与解析步骤
|
||||
|
||||
```text
|
||||
interface ModeDefinition { section: string } // prompt text — a mode's whole vocabulary
|
||||
interface ModeConfig { modes: Record<string, ModeDefinition> } // plan is required and owns its complete prompt
|
||||
resolveConfig(config): ResolvedModes // explicit resolve (the dsh-bash template), fail-loud:
|
||||
// missing plan, 'default', blank sections, and unknown keys rejected
|
||||
```
|
||||
|
||||
单字段形状是有意采用的最简设计，并非最终词汇：逐工具策略维度会以工具定义中的副作用元数据形式回归（见[延期工作](#deferred)），在此处读取，而不是由每种模式重新声明；该维度到来时，配置形状不应需要迁移。
|
||||
|
||||
### 折叠、服务与刷写
|
||||
|
||||
`foldMode(events)` 是纯函数（导出供重建方与测试使用），直接折叠仅追加的会话日志；`mode/set` 不是 surface 节点，因此压缩无法遮蔽它。`set(agent, mode)` 根据 `list()` 的词汇校验名称，即已配置定义加上保留的 `default`；后者不能用作配置键，却始终可以作为 `set()` 目标。目标与待生效模式相同（没有待生效模式时则与当前模式相同）时，该方法丢弃无操作；其余情况会把 `{ mode, narrate }` 记录到 `WeakMap` 的待生效意图槽中。它不能立即追加，因为[每个会话事件都封闭在轮次内](../../implemented/architecture/2026-06-15-turn-enclosure-invariant.md)，而空闲 agent 没有打开的轮次。
|
||||
|
||||
循环拦截 seam 上经过故障隔离的监听器（参见[防御模式](../../../../docs/defensive-patterns.md)：策略插件不得阻塞提示词或轮次）会把待生效意图刷写为一条 `mode/set` 追加：`agent/prompt-submit` 在刚打开的轮次中、首次组装前触发；`agent/turn-continuation` 则在普通步骤关闭后、后续步骤开始前触发。自动请求恢复会绕过 continuation，因此，前置的 `agent/request-error` 包装器会先委托给组合后的策略和异步退避，只在 waterfall 返回循环前刷写 `retry` 决策；effect 作用域的生命周期守卫会抑制在插件资源释放后才恢复的已捕获包装器。三条路径都位于工具执行与日志发布之外（提交后的 `session/event` 观察器只负责观察），因此每个步骤都在其组装所折叠出的模式下运行。刷写模式与最后一个 `request/header` 处的折叠结果不同时，刷写会在同一帧中追加一条合并后的 `context/message` 通知（「用户已将此会话切换到 plan mode。」）；面向用户的叙述情形列在[常见问题](#faq)中。
|
||||
|
||||
### 软层：计算得出的段落与稳定的退出 schema
|
||||
|
||||
已注册的提示词段落从 `AssembleContext.agent` 读取调用 agent 的模式，并解析为当前定义的指引或 `''`。循环逐步骤渲染，并在渲染后的 header 发生变化时记录完整的 `request/header`，因此进入或离开模式均可归因。该段落在每种模式内保持静态，plan 本身则以消息和工具参数留在对话中；无需为了跨压缩保留状态，而在每个请求中重新注入独立的 plan 状态（[既有方案](#prior-art)采用的办法），徒增提示词抖动。
|
||||
|
||||
指引贡献为 `{ name: 'mode:policy', order: 50, text: context => … }`：排在人设（0）之后、工具指引（100–199）之前，并在默认模式或没有 agent 的组装中为空。`exit_plan_mode` 只通过 `ctx.tools` 注册一次且从不过滤，因此模式切换期间 Native schema 与 Code Mode 生成的 SDK 保持逐字节相同；未部署 `dsh-mode` 的环境则没有这项绑定。系统不注册 `tools/pre-execute` 监听器：模式不设置任何门禁，退出工具自身的折叠模式检查会拒绝 plan 之外的调用。退出评审是一个带选项和反馈的问题，不是权限，因此位于工具通过用户交互 seam 执行的过程内。
|
||||
|
||||
### `exit_plan_mode`
|
||||
|
||||
`defineTool` 有一个必填的 `plan: string` 参数。Native 执行会把它记录在普通 `tool/call` 中；Code Mode 在执行前记录外层 `run_code` 源码，并在分发结算后把规范化的嵌套参数追加到 `tool/code-dispatch`。`execute` 会拒绝没有 agent 的调用（沿用 [`todo_write` 先例](../../implemented/feature/2026-06-29-todo-write-tool.md)）和折叠模式不是 `plan` 的调用，并在询问评审人前拒绝空 plan 或不含标题的 plan；随后，它通过 `ctx.userInteraction.ask()` 发起一次单选评审，其 `detail` 是确切 plan，并开放自由文本反馈，供用户批准或要求继续规划。只有恰好选择一个 `Approve` 才表示同意，其他任何形状都按失败关闭处理。批准会记录一项将在边界生效且不叙述的意图，用于切换到 `default`，并返回简短确认。部署指引要求模型把这次调用作为回复中唯一且最后一次工具调用；如果模型违反该规则，运行时仍会让该批次剩余部分保留 plan 指引，下一步骤才记录变化后的 header，其中移除指引而工具 schema 保持不变。所有未获批准的结果都会返回纠正性的 `isError`，并让模式留在 `plan`。
|
||||
|
||||
其[渲染意图](../../implemented/architecture/2026-07-02-tool-render-intent-union.md)在设计之初就已确定：`presentCall` 是 `generic` 卡片，以 plan 的首个标题命名、以 plan markdown 作为内容，另配一张 `generic` 结果卡片。Native 入口会在问题之前显示该卡片；Code Mode 嵌套分发不会产生 Native 调用卡片事件，因此用户交互 `detail` 会在每个提供方上独立携带同一份 plan。系统机会式消费该 seam（`ctx.get('userInteraction')`），所以 `dsh-mode` 在没有它时仍可组合，并降级为[常见问题](#faq)中确定的手动退出方式。
|
||||
|
||||
### 依赖与接口
|
||||
|
||||
`dsh-mode` 是一个产品包，而不是由三个包组成的能力 seam（见[考虑过的替代方案](#alternatives-considered)）：它对等依赖 `cordis`、`dsh-session`、`dsh-agent`、`dsh-tools` 与 `dsh-system-prompt`，注入 `['tools', 'systemPrompt']`，并在执行时机会式读取 `ctx.userInteraction`（指向 `dsh-user-interaction` 的仅类型对等依赖边）；其仅有的 UI 侧边也是可选的仅类型对等依赖（逐定义进入命令使用 `dsh-commands`）。除 `ctx.modes` 调用接口外，所有内容都通过监听器参与，因此移除该包会平稳移除模式，而不会破坏消费方。终端入口无需模式专用代码：组合命令注册表后，`dsh-mode` 会自行注册每个定义的命令（指向 `dsh-commands` 的可选仅类型对等依赖边），退出评审则使用组合后的用户交互提供方提示队列。[高层 API](#over-acp) 已确定 ACP 协议映射；在包关系上，桥接层对 `dsh-mode` 采用仅类型对等依赖边并机会式读取服务，所以不含该插件的桥接层行为与当前完全相同。
|
||||
|
||||
### 已记录场景与 harness 操作
|
||||
|
||||
`input.json` 新增一种步骤操作 `{ "op": "setMode", "modeId": "plan" }`，通过真实的 `session/set_mode` RPC 驱动，并配有脚本化的 `elicitationAnswers` 队列。`plan-mode` 场景在第 1 个轮次前进入 plan，在独立配置的沙箱下运行真实的 `cat`，通过 `exit_plan_mode` 呈现 plan，接收脚本化审批，然后在下一步骤编辑。首个 `request/header` 包含完整、稳定的工具集和已配置模式段落；批准后变化的 header 会保留逐字节相同的工具 schema，只移除该段落。`plan-mode-reject` 固定纠正性的自由文本反馈和未变化的 plan 状态。两份记录都在 Seatbelt 或 bwrap 下回放宿主命令；后端特有的沙箱拒绝仍留在 bash 工具单元层。
|
||||
|
||||
### 机械收尾
|
||||
|
||||
系统不声明新的 Cordis 事件（`mode/set` 通过 `session/event` 传递，监听器附着到现有 waterfall），因此事件目录不变。同一变更重新生成以下内容：持久化日志目录（`mode/set`）、服务目录（`ctx.modes`，JSDoc 完整）、配置目录（`ModeConfig`）、工具目录（`exit_plan_mode`）、生产方／消费方 map 与文档图，以及模块图。仓库接线包括：根 tsconfig 的 `paths` 条目、新包组 README 和[包索引](../../../../packages/README.md)中的一行（新增顶层包组正是该表所命名的有意操作）、`architecture.md` 中经过预算检查的 `ctx.modes` 能力服务行，以及实操手册对应行的升级。
|
||||
|
||||
## 延期工作
|
||||
|
||||
以下各项都需要独立决策：通过转发的创建时模式选项实现 subagent 模式继承（由于没有消费方而移除，将随首个消费方回归）；`plan` 之外的预设模式（只读、接受编辑）；若待生效意图丢失被证明是真实问题，则引入空闲记录原语；以及最重要的**在工具定义上自行声明副作用**，即逐工具的只读／变更分类（MCP `ToolAnnotations` 词汇——`readOnlyHint`／`destructiveHint`——是自然模板，其中对不可信提示的警告意味着还需区分信任层级）。通用的逐模式工具策略正在等待这一项：本 Agent Note 最初发布过临时的逐模式名称允许清单，并在发布前移除；手工维护的清单错误地表达了副作用问题，必须跟踪部署所组合的每个工具，且会随工具增加而无声腐化。因此，按模式限制的工具可用性（以及逐工具 `ask` 策略）会作为已声明副作用的消费方回归，而首项消费需求就是其重启触发条件。
|
||||
|
||||
ACP 自动化组合不挂载 plan mode 或问题工具。面向人类的组合拥有 plan 选择与评审；聚焦的 plan-mode 测试和交互接口快照会固定其已记录状态、指引、评审和稳定工具 schema。
|
||||
|
||||
## 常见问题
|
||||
|
||||
以下内容澄清选定设计的行为；遭否决的设计见[考虑过的替代方案](#alternatives-considered)，已接受的代价见[后果](#consequences)。
|
||||
|
||||
**用户切换模式后何时生效？** 在下一个组装前边界生效：`agent/prompt-submit` 覆盖首个步骤，`agent/turn-continuation` 覆盖普通后续步骤，组合策略之后的 `agent/request-error` 重试决策覆盖自动恢复。因此，在请求或重试退避进行期间选择的模式会塑造下一次模型请求。这就是[既有方案](#prior-art)中每项产品都采用的「应用于后续请求」语义。
|
||||
|
||||
**何时向模型讲述模式变化？** 仅当模型可见状态确实变化时：刷写会把刚刷写的模式与最后一个 `request/header` 处的折叠结果进行比较，并合并讲述一次。净变化为零的切换序列（先进入 plan，再在边界前切回）不会产生叙述；工具驱动的退出只通过自身工具结果叙述；首个轮次前设置的模式也不叙述，因为该段落本身就是状态说明。该原则来自进行中 env-state 提案的边界叙述：如果提示词表层悄然切换，transcript（文本记录）仍会依据 header 已不再具备的状态进行论述。
|
||||
|
||||
**恢复时，配置已不再定义折叠出的模式会怎样？** 当前配置不再定义的折叠模式名称会在不通知的情况下表现为默认模式，因此会话既不会获得替代约束，也不会变得不可用。`set()` 的大声校验只覆盖写入路径；恢复后的日志以当时找到的配置为准。
|
||||
|
||||
**如果部署没有组合用户交互提供方，会怎样？** Plan mode 仍然安全，但只能手动退出：`ctx.userInteraction.ask()` 会抛出 `NO_PROVIDER`（seam 不存在时甚至无法解析到该服务），工具返回纠正性的 `isError`，退出方式降级为由用户切换模式，绝不会在未经评审时退出。模式段落会要求模型通过 `exit_plan_mode` 呈现 plan，并在失败时改用普通文本询问用户，因此模型会继续呈现，而不会停滞。
|
||||
|
||||
**为何没有逐模式工具允许清单？** 因为「哪些工具在规划模式下安全」是每个工具自身的属性（即副作用），不是模式的属性。逐模式名称清单会在错误的归属位置重新声明该事实，必须枚举部署所组合的每个工具（包括 MCP 服务器），且会随工具到来而无声腐化。在工具定义声明其副作用前（见[延期工作](#deferred)，其中归档了被移除的临时允许清单及其重启触发条件），模式只通过自身段落和退出评审约束行为；由此产生的暴露面属于已接受代价（见[后果](#consequences)）。
|
||||
|
||||
**subagent 是否继承父级模式？** fork 子级可以直接继承，因为父级的 `mode/set` 位于种子前缀中。spawn 子级从默认模式开始；创建时模式选项与 subagent 提供方的自动转发一并延期（见[延期工作](#deferred)）。
|
||||
|
||||
**plan mode 与沙箱只读模式有何关系？** 二者是互不接触的独立轴：模式是协作姿态（`mode/set` 折叠），沙箱模式是强制约束旋钮（`bash/sandbox-mode` 折叠，参见[沙箱 Agent Note](2026-07-06-sandbox.md)）。Plan mode 既不读取也不限制沙箱模式，与 Codex 将 Plan／Default 预设同沙箱及审批设置分开的做法完全一致。希望规划期间由内核强制只读的用户需要同时设置两者：以任意顺序切换模式选择器与沙箱模式选项；每次切换只改变自身折叠结果，因此二者互不干扰，也不存在可能崩溃的还原步骤。日志会把每条轴归因到各自事件：协作姿态对应 `mode/set`，隔离约束对应 `bash/sandbox-mode`。
|
||||
|
||||
**为何沙箱模式、审批策略或模型本身不属于模式？** 它们是独立于协作状态的单项环境旋钮。已退役的 ACP 映射记录在[仅面向自动化的协议决策](../simplification/2026-07-23-acp-automation-only-protocol.md)中。未来模式定义可以捆绑环境事实（在挂载处通过 `ctx.envState` 应用），让 Codex 风格的预设仍是一种模式；但把审批策略融合进模式概念本身的方案已在[考虑过的替代方案](#alternatives-considered)中遭否决。
|
||||
|
||||
## 既有方案
|
||||
|
||||
对已发布 plan mode（Claude Code、Cursor、Copilot、OpenCode、Gemini CLI、Cline、Windsurf、Codex）的调研表明，各产品都包含同样五个部分：低权限工具策略、plan 产物、审批时刻、执行状态切换，以及[问题](#problem)所依赖的持久状态。
|
||||
|
||||
只要产品公开模式接口，该接口就一定是清单，绝不是布尔值：Claude Code 的选择器提供 `plan`，旁边是 `acceptEdits`（另有自动进入 plan 的模式）；Codex 则把 `Plan` 与 `Default` 并列公开为协作模式预设，同时让审批和沙箱设置保持独立。ACP 传输层不公开这项面向人类的控制。
|
||||
|
||||
由部署拥有的示例提示词借鉴工具性行为，而非产品特有机制。它借鉴 Codex 的以下做法：即使收到祈使式实现语言也留在 plan mode；提问前先探索；区分仓库事实与由用户决定的选择；让 plan 完整覆盖 API、数据流、失败、测试和假设，从而足以作出决策。它还借鉴 Claude Code 的以下做法：禁止变更与提交；优先沿用现有模式；只针对需求或方案选择提问；通过退出工具完成规划，而不在普通文本中请求审批。它有意省略 Codex 协议标签，以及 Claude 的 plan 文件或分阶段 subagent 机制，因为这些属于各自运行时，而非本插件契约。
|
||||
|
||||
把模式留给约定的生态展示了应避免的失败形态。Pi 风格的模式扩展会争抢一个后写覆盖的全局活跃工具清单，只靠提示词文本强制「只读」（模型幻觉调用一个仍已注册的工具时，该调用会实际执行），并在每个请求中重新注入 plan 状态以跨过压缩。这里通过逐 agent 的折叠状态，以及压缩无法遮蔽的只记录日志、非 surface 事件，从结构上消除了有争议的全局清单和重复注入补丁。相较之下，仅靠提示词的形态被有意保留：Codex 的 Plan 正是如此实现，这也是模式轴可以与强制约束轴自由组合的原因。需要硬性下限的部署会把模式与独立的沙箱旋钮配对，而不是让模式携带自身强制约束（见[常见问题](#faq)）。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**以权限模式作为核心概念（Claude Code 的形态）。** 用一个 `permissionMode` 融合审批策略和工具策略。本设计中，它们是归不同所有者负责的两条轴：审批 seam 拥有「谁回答这个问题」，模式拥有「模型获得什么接口」。ACP 将二者建模为相关但有区别的概念（模式以后可以选择审批策略；届时是模式定义增加字段，而不是合并两者）。
|
||||
|
||||
**由三个包组成的能力 seam。** 接口／实现／消费方适合可替换后端；模式的可变部分是配置值，而不是实现。拆分会制造一个空实现包，与审批 seam 及 [`todo/`](../../implemented/feature/2026-06-29-todo-write-tool.md) 作出的「不要过早拆分」决策相同。
|
||||
|
||||
**由循环拥有模式状态。** 依据既有规则（用插件，而不修改循环）予以否决：该功能所需的每个钩子——组装、执行前处理、轮次边界、会话事件——都已经是有文档记录的 seam，修改循环只会增加耦合，别无收益。
|
||||
|
||||
**带默认拒绝门禁的逐模式工具允许清单（首个发布形态）。** 已在发布前移除。手工维护的名称清单会逐模式重新声明一项逐工具事实（即其副作用）：它必须枚举部署所组合的每个工具，包括 MCP 服务器和未来注册项，并会随工具增加而无声腐化（新增只读工具时，在有人编辑每种模式前都会被阻止；编写负担落在了解模式的人身上，而不是了解工具的人身上）。它还过度承诺：该清单看似安全边界，但 shell 之外的任何能力其实都不存在这种真实边界。通用维度已停放到副作用自声明（见[延期工作](#deferred)）；由此产生的后果——plan mode 只提供指引，也就是该门禁一度弥补的 Pi 缺口——是有意接受的，并计入[后果](#consequences)。
|
||||
|
||||
**模式上的 `access` 沙箱上限（第二个发布形态）。** 同样已在发布前移除。`ModeDefinition.access` 会把 bash seam 的逐调用沙箱解析限制在模式声明的上限内（一个 `bash/resolve-mode` waterfall 加上取阶梯最小值的监听器；守卫会在执行器无法施加约束时隐藏 bash，并在模式中途拒绝提升权限）。状态仍保持正交，因为上限从不写入沙箱旋钮；但两条轴并不正交：进入 plan 会改变沙箱实际强制执行的内容，把协作姿态与强制约束级别融合起来，违背评审最终达成的 Codex 形态分离方式（Plan／Default 预设从不触及沙箱或审批设置）。这种融合有一项用户可见症状：规划期间把沙箱选项切换为 `workspace-write` 不会产生任何效果。上限、waterfall 和 mode→bash 依赖边随后一并移除；部署可以把模式与独立沙箱模式选项配合使用，从而在规划期间由内核强制只读。以后也可以重新引入模式触发的预设（模式定义捆绑建议的旋钮值，并作为普通旋钮切换加以应用），而无需再次融合两条轴。
|
||||
|
||||
**仅存在于运行时的模式（只在 UI 或桥接层本地存在，不记录日志）。** 恢复与 fork 会悄然丢失模式，模式引起的 header 增量在日志中也没有可归因原因。记录到日志的状态让模式无需额外机制即可审计和还原。
|
||||
|
||||
**把模式切换作为 `context/message` 并通过 `agent.inject()` 写入。** 这样可以复用现有的轮次封闭路径，却会把策略状态放入模型 transcript；模型无需被告知两次（段落已经告诉它），而只记录日志的事实不应占用 surface。
|
||||
|
||||
**plan 文件存储（`.plans/` 目录）。** 这会为日志已经以可回放方式承载的内容创建第二个持久归属位置；需要文件的部署可以添加一个写入文件的工具。同一事实只应有一个归属位置。
|
||||
|
||||
**用布尔值 `planMode` 取代具名模式。** 对仓库已经跟踪的接口而言过于狭窄：ACP 通告的是模式清单，已发布的选择器也不只填入 plan（见[既有方案](#prior-art)）；以后再泛化会重命名持久事件词汇。字符串形状的机制现在不产生额外成本；只有 `plan` 作为定义发布。
|
||||
|
||||
**工具策略栈服务（对 Pi 批评的补救方案）。** 现在就为工具策略建立专用组合服务为时过早：本实现不执行按模式限制的工具过滤，未来的副作用策略可以通过现有带守卫的执行 seam 组合。只有已声明的工具副作用产生具体组合需求后，才应正式建立该服务。
|
||||
|
||||
**通过审批 seam 执行退出审批（一个 `{ kind: 'ask' }` 门禁决策）。** 最初草案提出该方案；当时审批 seam 是唯一正在落地的询问机制，所以显得自然，但它把评审放进了权限的位置。该 seam 的结果词汇有意封闭且仅供单次使用（`allowed-once`／`rejected`），因此拒绝无法携带反馈，批准也永远无法增加选项（例如「批准并接受编辑」）。退出时刻是一个问题，而非权限；用户交互 seam 为其提供选项与自由文本通道，拒绝反馈也会逐字传给模型。审批 seam 仍适合真正的权限门禁（沙箱提升权限），注册表的 `ask` 词汇也继续供希望在该处设置询问的部署使用。
|
||||
|
||||
**使用普通文本或 steering（中途引导）退出，而不使用工具。** 这样既没有产物，也没有审批时刻。工具参数本身就是可供评审的 plan，而评审问题会把结构化的是／否选择附着到确切转换上并交给人类。
|
||||
|
||||
## 后果
|
||||
|
||||
以下保证现在已经由单元、协议、快照和真实 API 测试层固定：
|
||||
|
||||
- 生效模式是会话日志的纯函数：恢复与 fork 无需额外机制即可还原它；下一变化步骤中，一条 `mode/set` 后会出现匹配的完整 `request/header`。
|
||||
- 用户驱动的切换会在下一边界恰好叙述一次，净变化为零的切换序列不会产生叙述；工具驱动的退出只通过自身工具结果叙述。
|
||||
- 默认模式下，插件不贡献模式段落，但会贡献稳定的 `exit_plan_mode` schema；未部署 `dsh-mode` 的环境没有这项绑定。
|
||||
- 默认、plan 与自定义模式之间转换时，Native 工具 schema 与 Code Mode SDK 保持逐字节相同；只有已配置的指引段落发生变化。
|
||||
- Plan mode 不改变强制约束轴上的任何内容：工具集、沙箱模式、权限提升和审批策略在 plan 与默认模式下表现完全相同；部署通过把模式与独立的沙箱／审批旋钮配合使用来强化规划。
|
||||
- 模式定义可通过 `cordis.yml` 修改，无需编辑代码；其中必须提供完整 plan 指令。缺失 plan 配置、定义畸形和未知键会在加载时失败，未知模式名称会在 `set()` 时失败。
|
||||
- `exit_plan_mode` 始终通告，在 plan 之外会拒绝；批准后只移除 plan 指引，并通过纠正性的 `isError` 携带继续规划反馈；每个面向人类的接口都由其用户交互提供方承载评审。
|
||||
- 随功能落地一并交付的文档收尾包括：README、重新生成的目录（持久化日志、配置、Cordis 服务、工具）、包索引与架构行，以及实操手册中的对应行。
|
||||
|
||||
已接受的代价如下：在 agent 空闲时设置的待生效用户切换，如果进程在下一轮次前退出，就会丢失（UI 会重新应用；若实践中出现问题，空闲记录原语就是逃生口）。模式转换会改变顺序 50 处的系统提示词，因此从该处开始的缓存路径也会变化，但工具 schema 与 Code Mode SDK 不再抖动。**模式只依靠指引约束行为**：忽略该段落的模型可以在 plan 期间执行变更；评审时刻、会话日志以及独立的沙箱、审批和文件系统策略共同构成约束边界。强化规划意味着设置这些旋钮，而不是扩大模式职责；被移除的强制约束形态及其副作用声明重启触发条件仍记录在[考虑过的替代方案](#alternatives-considered)和[延期工作](#deferred)中。面向人类的接口拥有 plan 选择器与评审交互；ACP 自动化传输层两者都不承载。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-14-time-context-plugin.md: 89d6fca7c473a932e8f014ff0576cecfd6f2e4e0
|
||||
2026-07-14-time-context-plugin.zh.md: 11e642f0361209cd29e86441e9ee82d845ea63dd
|
||||
@@ -0,0 +1,60 @@
|
||||
# Agent Note: Optional time-context plugin
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-14-time-context-plugin.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The dynamic system-prompt storage and refresh decision in this record is superseded by [Durable per-step time context](2026-07-16-durable-per-step-time-context.md). The opt-in package, zoned formatting, and validation remain; the follow-up owns the current model-visible and durability contract.
|
||||
|
||||
An agent request has no live clock unless a deployment puts one in prompt text or gives the model a query tool. Static text becomes stale, while a tool call adds overhead to ordinary reasoning about dates, deadlines, or idle time. Without elapsed time, the model cannot distinguish an immediate follow-up from one sent hours after the preceding message.
|
||||
|
||||
Prompt assembly can derive both facts per step from durable session timestamps, and request-header logging can record the exact rendered value. Accumulating stale readings in conversation history or waking idle agents would violate the existing request lifecycle.
|
||||
|
||||
## Decision
|
||||
|
||||
`@deepseek-ai/dsh-time-context` is an opt-in function plugin at `packages/context/time-context/`. The `context/` product group holds bounded request-context enrichments that define neither a tool nor a service. `dsh-agent-spine-demo` and shipped examples do not load the package; deployments mount it explicitly when its token and disclosure costs are acceptable.
|
||||
|
||||
The plugin registers the global `context:time` system-prompt section at order 10, after the deployment persona and before tool guidance. For an active turn it emits an ISO-shaped timestamp with numeric UTC offset and IANA zone, plus a compact whole-second duration since the last model-visible message before the turn opened. Bare and idle assemblies receive an empty section.
|
||||
|
||||
### Previous-message baseline
|
||||
|
||||
At a turn's first assembly, the provider scans before `turn/start` for the latest `user/message`, `assistant/message`, `tool/result`, `context/message`, or `steering/message`. It excludes the current prompt so the duration expresses the inter-turn gap instead of approximately zero. Every refresh in that turn keeps the same baseline, and the first turn reports `unavailable (no earlier message in this session)`.
|
||||
|
||||
The baseline is the session event's append time, not an unlogged client timestamp. Resume and fork behavior are therefore deterministic from the durable log, and the model-visible value remains reconstructable without a new event. A backward wall-clock adjustment clamps the duration to zero.
|
||||
|
||||
### Refresh policy
|
||||
|
||||
`refreshIntervalMs` defaults to 60,000 and must be a non-negative safe integer. Every turn's first request refreshes. Later assemblies in that turn reuse the block until its age reaches the interval; `0` refreshes every step. No timer creates work during model calls, tools, or idle time because refresh is request-bound.
|
||||
|
||||
When `timeZone` is omitted, `Intl.DateTimeFormat` resolves the Node process's system zone once at plugin load. Node honors `TZ`; without that override, the host or container supplies the zone. An explicit value must be an IANA identifier and is validated at load. The captured zone remains stable until plugin reload, and the ISO-shaped local timestamp includes its current numeric offset so daylight-saving changes stay explicit. This is the deployment process's zone, not a remote user's zone.
|
||||
|
||||
### Logging and token shape
|
||||
|
||||
The loop records the temporal block in full `request/header` snapshots before transmission, satisfying the [reconstructable-requests contract](../architecture/2026-07-05-reconstructable-requests.md). Each request carries one current block; earlier readings do not remain in conversation history. The plugin owns the fact and contributes it through the prompt registry, following the [prompt-variables Agent Note](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) without a loop special case.
|
||||
|
||||
## Testing
|
||||
|
||||
Unit tests pin formatting, baselines, refresh policy, validation, per-agent state, disposal, and load-time system-zone capture. A real agent-loop test pins the transmitted prompt and full `request/header` snapshots. A keyless subprocess e2e boots a test-only `cordis.yml` through the real Loader and stdio app, omits `timeZone` under a controlled `TZ`, drives two turns, and verifies the persisted request headers externally. Default snapshot compositions omit the plugin, so their transcript fixtures contain no temporal block.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Append a `context/message` on every turn or refresh** — rejected because readings and token cost would accumulate in history. Replacing a prior surface node would preserve its old position, while replacing the tail would hide intervening conversation.
|
||||
- **Use `agent/session-prefix`** — rejected because the session-stable prefix cannot represent a per-turn or per-step clock.
|
||||
- **Mutate requests in `agent/request`** — rejected because that seam shapes call config after the message boundary; inserted model content would bypass prompt-pressure accounting and request-header logging.
|
||||
- **Register separate `{{current_time}}` and `{{elapsed}}` variables** — rejected because independent providers can sample different instants and require shared caching. One section records the pair atomically without a deployment-authored template.
|
||||
- **Refresh from a background timer** — rejected because a new value has no consumer outside request assembly. Timer-driven `agent.inject()` would create turns and wake idle sessions merely to report time passing.
|
||||
- **Keep UTC as the omitted default** — rejected because an explicitly enabled clock should follow its deployment environment unless the operator chooses UTC. `timeZone: UTC` remains available when a deployment requires it.
|
||||
- **Add a time-zone detection library** — rejected because Node's `Intl` runtime already exposes the process's IANA zone. Another dependency cannot infer a remote user's zone either.
|
||||
- **Mount the plugin in `dsh-agent-spine-demo`** — rejected because time zone, disclosure, token budget, and freshness are deployment policy. Opt-in keeps default context stable.
|
||||
- **Place the package in `core/`** — rejected because `core/` owns the product API spine, while this plugin is an optional leaf with no service key.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Opted-in models receive a zoned clock and inter-turn duration without a tool call. The system-prompt cost is fixed per request instead of growing with the session.
|
||||
- An omitted `timeZone` follows the process's `TZ`, host, or container zone as observed at plugin load. Operators must configure an explicit zone when the deployment environment does not represent the intended user.
|
||||
- A refresh changes the request header and can add a full `request/header` snapshot with reason `change`. `refreshIntervalMs` trades freshness against the number and size of durable full snapshots; `0` records a new value on every step whose whole-second rendering changes.
|
||||
- No request exists solely to refresh time. A long-running tool leaves the prior reading until the next step assembles.
|
||||
- Duration reflects harness processing time at durable append boundaries, not client-network latency before logging. Preserving a client-origin timestamp requires a separate durable input contract.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Agent Note: 可选时间上下文插件
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-14-time-context-plugin.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
本记录中的动态系统提示词存储和刷新决策已由[持久的逐步骤时间上下文](2026-07-16-durable-per-step-time-context.md)取代。需要显式启用的包（package）、分区时间格式和校验仍然保留；后续 Agent Note 负责当前的模型可见与持久性契约。
|
||||
|
||||
如果部署方既未在提示词中提供时钟，也未给模型提供查询工具，agent（智能体）请求就无法获得实时准确的时间。静态文本会变得陈旧，而对于日期、截止时间或闲置时长等常规推理，调用工具会增加开销。缺少已经过去的时长时，模型无法区分紧接着发送的消息与上一条消息几小时后才发送的消息。
|
||||
|
||||
提示词组装流程可以在每个步骤中根据持久会话时间戳派生这两项信息，请求头日志则可以记录实际渲染的确切值。在会话历史中累积陈旧读数或唤醒空闲 agent 都会违反现有请求生命周期。
|
||||
|
||||
## 决策
|
||||
|
||||
`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 产品分组用于容纳既不定义工具、也不定义服务的有界请求上下文增强。`dsh-agent-spine-demo` 和仓库提供的示例都不会加载该包；只有当 token 与信息披露成本可接受时，部署方才显式挂载它。
|
||||
|
||||
该插件注册顺序值为 10 的全局系统提示词区段 `context:time`，位置在部署方角色设定之后、工具指导之前。对于活跃轮次，它会输出带数字 UTC 偏移和 IANA 时区、形似 ISO 的时间戳，以及从轮次开始前最后一条模型可见消息起算的紧凑整秒时长。未绑定 agent 或 agent 处于空闲状态时，该区段为空。
|
||||
|
||||
### 上一条消息基线
|
||||
|
||||
在轮次首次组装时，提供方会在 `turn/start` 之前查找最近的 `user/message`、`assistant/message`、`tool/result`、`context/message` 或 `steering/message`。它会排除当前提示词，使时长表达轮次间隔，而不是接近零。同一轮次中的每次刷新都保留这条基线；首个轮次报告 `unavailable (no earlier message in this session)`。
|
||||
|
||||
基线采用会话事件的追加时间，而不是日志中不存在的客户端时间戳。因此，恢复和 fork 行为可以从持久日志中确定性重现，模型可见值也无需新增事件即可重建。系统挂钟向后调整时，插件会将时长钳制为零。
|
||||
|
||||
### 刷新策略
|
||||
|
||||
`refreshIntervalMs` 默认值为 60,000，并且必须是非负安全整数。每个轮次的首次请求都会刷新。同一轮次中的后续组装会复用该区块，直至其存在时间达到该间隔；设为 `0` 时每个步骤都刷新。刷新仅由请求驱动，因此在模型调用、工具运行或空闲期间，计时器不会创建任务。
|
||||
|
||||
省略 `timeZone` 时，`Intl.DateTimeFormat` 会在插件加载时解析一次 Node 进程的系统时区。Node 会遵循 `TZ`；没有该覆盖值时，时区由主机或容器提供。显式值必须是 IANA 标识符，并在加载时接受校验。捕获的时区在插件重新加载前保持稳定，形似 ISO 的本地时间戳包含其当前数字偏移，使夏令时变化保持显式可见。该默认值代表部署进程的时区，而不是远程用户的时区。
|
||||
|
||||
### 日志与 token 形态
|
||||
|
||||
agent loop（智能体循环）会在发送前通过完整的 `request/header` 快照记录时间区块，从而满足[可重建请求契约](../architecture/2026-07-05-reconstructable-requests.md)。每个请求只携带一个当前区块；先前的读数不会保留在会话历史中。该插件拥有时间信息，并按照[提示词变量 Agent Note](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)通过提示词注册表贡献该信息，无需为循环添加特殊分支。
|
||||
|
||||
## 测试
|
||||
|
||||
单元测试固定格式化、基线、刷新策略、校验、逐 agent 状态、资源释放行为，以及系统时区在加载时的捕获行为。使用真实 agent loop 的测试固定实际发送的提示词和完整的 `request/header` 快照。无密钥子进程端到端测试通过真实 Loader 和 stdio 应用启动测试专用 `cordis.yml`，在受控 `TZ` 下省略 `timeZone`，驱动两个轮次，并从外部校验持久请求头。默认快照组合不包含该插件，因此其中的 transcript（文本记录）fixture（测试前置数据）不包含时间区块。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
- **每个轮次或每次刷新都追加一条 `context/message`**——不予采纳，因为读数和 token 成本会在历史中累积。替换先前的表层节点会保留其旧位置，而替换尾部节点会隐藏中间的会话内容。
|
||||
- **使用 `agent/session-prefix`**——不予采纳，因为会话期间保持稳定的前缀无法表示逐轮次或逐步骤变化的时钟。
|
||||
- **在 `agent/request` 中修改请求**——不予采纳，因为该边界在消息边界之后塑造调用配置；插入模型可见内容会绕过提示词压力核算和请求头日志。
|
||||
- **注册独立的 `{{current_time}}` 和 `{{elapsed}}` 变量**——不予采纳，因为独立提供方可能在不同时间点采样，并且需要共享缓存。单个区段会以原子方式记录两项信息，也不需要部署方编写时间模板。
|
||||
- **通过后台计时器刷新**——不予采纳，因为请求组装之外没有消费新值的对象。由计时器驱动 `agent.inject()` 会创建轮次，并且只为报告时间流逝就唤醒空闲会话。
|
||||
- **省略配置时仍默认使用 UTC**——不予采纳，因为显式启用的时钟应跟随部署环境，除非运维方选择 UTC。需要 UTC 的部署仍可配置 `timeZone: UTC`。
|
||||
- **引入时区探测库**——不予采纳，因为 Node 的 `Intl` 运行时已经能够提供进程的 IANA 时区，而且额外依赖同样无法推断远程用户的时区。
|
||||
- **在 `dsh-agent-spine-demo` 中挂载插件**——不予采纳，因为时区、信息披露、token 预算和新鲜度都属于部署策略。选择加入能保持默认上下文稳定。
|
||||
- **将包放入 `core/`**——不予采纳，因为 `core/` 负责产品 API 主干，而该插件是没有服务键的可选叶节点。
|
||||
|
||||
## 后果
|
||||
|
||||
- 选择加入的模型无需调用工具，即可获得分区时钟和轮次间隔时长。每个请求的系统提示词成本固定，不会随会话增长。
|
||||
- 省略 `timeZone` 时，插件采用加载时观察到的进程 `TZ`、主机或容器时区。当部署环境不能代表目标用户时，运维方必须显式配置时区。
|
||||
- 刷新会改变请求头，并可能新增一份 reason 为 `change` 的完整 `request/header` 快照。`refreshIntervalMs` 用新鲜度换取完整持久快照的数量与大小；设为 `0` 时，每个整秒渲染结果发生变化的步骤都会记录新值。
|
||||
- 系统不会仅为刷新时间而创建请求。长时间运行的工具会保留先前读数，直至下一步骤开始组装。
|
||||
- 时长反映持久追加边界处的 harness 处理时间，不包含消息进入日志之前的客户端网络延迟。若要保留客户端来源时间戳，需要单独的持久输入契约。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-20-tui-startup-slogans.md: aa847f96ebe13c4b1833531074577561faa2afb9
|
||||
2026-07-20-tui-startup-slogans.zh.md: bd667dfe9f54bbe923c48d0adf2889735b1255c5
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: Startup slogans replace the configured TUI welcome line
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-20-tui-startup-slogans.zh.md)
|
||||
|
||||
> **Superseded** for the slogan/animation half by the [banner sweep Agent Note](2026-07-21-tui-banner-sweep.md): the slogan bank and typewriter reveal shipped, read as weird in use, and were replaced by a subtitle-free banner with a whole-banner sweep. The removal of the configured demo welcome and the animation-lifecycle groundwork (start after `ui.start()`, clear through `detachListeners`) stand.
|
||||
|
||||
## Problem
|
||||
|
||||
The TUI header subtitle came from a `welcome` config the demo leaf set to "TUI agent ready. Give it a coding task." — instructional filler that told a returning user nothing, restated what the product is on every boot, and had a hardcoded twin (`'ready.'`) as the schema default in two packages. The product wanted a startup moment with some character instead of a static banner caption.
|
||||
|
||||
## Decision
|
||||
|
||||
- `examples/tui-agent/cordis.yml` no longer configures `welcome`; the config key stays for deployments and fixtures that need a fixed, deterministic subtitle (the Code Mode overlay and every snapshot/scripted fixture keep theirs).
|
||||
- When `welcome` is unset, `dsh-tui` picks one member of an exported `STARTUP_SLOGANS` bank per boot (`pickStartupSlogan`, injectable random source) and reveals it with a typewriter animation: one character per 40 ms frame, a `▌` block cursor trailing until complete. The reveal starts only after `ui.start()` succeeds and its interval is cleared on dispose alongside the other listeners.
|
||||
- The slogan bank is presentation copy, deliberately not config: deployments that want controlled wording already have `welcome`. Slogans are ASCII-only by contract because the reveal slices per character.
|
||||
- `dsh-tui-demo` forwards `welcome` only when configured instead of defaulting it, so the app no longer decides the TUI's idle subtitle.
|
||||
- The keyless PTY boot scenario now waits for the reveal cursor (`▌` — the only source of that glyph in an empty transcript) instead of the removed welcome text.
|
||||
|
||||
The same change restores `packages/ui/tui/src/index.ts` to 100 % per-file coverage, which the color-scheme merge had broken on the integration branch: the editor border-color reassignment inside `applyColorScheme` was dead (the `setStatus` call right after re-derives it) and is removed, and the color-scheme query's `.then`/`.catch` arrows became named, tested handlers (`applyReportedScheme`, `ignoreSchemeQueryFailure` — the latter pinned by a test whose terminal throws on the DSR query write).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**A fixed cooler slogan.** Rejected: one string re-read on every boot decays into wallpaper exactly like the line it replaces; a small rotating bank keeps the moment alive at no complexity cost.
|
||||
|
||||
**Making the bank and reveal speed configurable.** Rejected: that is two new knobs for presentation copy; `welcome` is already the escape hatch for deployments with an opinion, and the no-hardcoded-tunables rule targets deployment-varying behavior, not brand copy.
|
||||
|
||||
**Animating in `HeaderComponent` itself.** Rejected: the component would need a TUI handle and its own lifecycle; the chat already owns a render loop, timers, and a disposal path, so the reveal lives beside the other `createTuiChat` effects and `detachListeners` clears it.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Boot output is no longer byte-deterministic when `welcome` is unset (random slogan, timed frames). Every recorded or snapshot surface pins `welcome` explicitly, so no snapshot changed; the PTY smoke anchors on the reveal cursor and the session-id line instead.
|
||||
- The `welcome` schema default disappeared from both `dsh-tui` and `dsh-tui-demo`; a direct caller passing no welcome now gets a slogan, not `'ready.'`.
|
||||
- Adding a slogan is a one-line bank edit; tests assert membership, not specific text.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` pins deterministic bank selection with an injected random source, the reveal (a bank member fully rendered, cursor frames observed), the configured-welcome path rendering verbatim with no cursor, and dispose stopping a mid-reveal animation. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` boots the real tree in a PTY and waits on the reveal cursor. Verified live in tmux (mid-reveal frame `no map below▌` then the full slogan).
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: 启动 slogan 取代配置化的 TUI 欢迎语
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-20-tui-startup-slogans.md) | 中文
|
||||
|
||||
> **已被取代**：slogan/动画的那一半由[横幅扫入 Agent Note](2026-07-21-tui-banner-sweep.md)取代：slogan 库和打字机动画上线后实际使用中显得怪异，已替换为无副标题的横幅加整体扫入。移除示例配置中欢迎语的决定与动画生命周期基础设施（`ui.start()` 后启动、经 `detachListeners` 清除）保持不变。
|
||||
|
||||
## Problem
|
||||
|
||||
TUI 头部副标题来自一个 `welcome` 配置，示例叶子配置把它设为 "TUI agent ready. Give it a coding task."——一句说明书式的填充语，对老用户毫无信息量，每次启动都在复述产品是什么，而且它还有一个硬编码的孪生兄弟（`'ready.'`）作为两个包里的 schema 默认值。产品需要的是一个有性格的启动时刻，而不是一条静态横幅说明。
|
||||
|
||||
## Decision
|
||||
|
||||
- `examples/tui-agent/cordis.yml` 不再配置 `welcome`；该配置键保留给需要固定、确定性副标题的部署与 fixture（Code Mode overlay 和所有快照/脚本化 fixture 都保留各自的欢迎语）。
|
||||
- `welcome` 未设置时，`dsh-tui` 每次启动从导出的 `STARTUP_SLOGANS` 库里挑选一条（`pickStartupSlogan`，随机源可注入），并以打字机动画逐字显示：每帧 40 ms 一个字符，完成前尾随一个 `▌` 块状光标。动画只在 `ui.start()` 成功后启动，其定时器与其他监听器一起在 dispose 时清除。
|
||||
- slogan 库是展示文案，刻意不做成配置：想控制措辞的部署已经有 `welcome` 这个出口。按契约 slogan 只含 ASCII，因为逐字显示按字符切片。
|
||||
- `dsh-tui-demo` 只在配置了 `welcome` 时才转发它，不再填默认值，应用不再替 TUI 决定空闲副标题。
|
||||
- 无 key 的 PTY 启动场景改为等待逐字显示的光标（`▌`——空 transcript 里该字形的唯一来源），不再等待已删除的欢迎文本。
|
||||
|
||||
同一变更把 `packages/ui/tui/src/index.ts` 恢复到 100% 的单文件覆盖率（颜色方案合并曾在集成分支上破坏它）：`applyColorScheme` 里对编辑器边框颜色的重新赋值是死代码（紧随其后的 `setStatus` 调用会重新推导它），已删除；颜色方案查询的 `.then`/`.catch` 箭头函数改为具名、有测试的处理器（`applyReportedScheme`、`ignoreSchemeQueryFailure`——后者由一个让终端在 DSR 查询写入时抛错的测试固定）。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**换一条更酷的固定 slogan。** 否决：一条每次启动都重读的字符串会和它取代的那行一样退化成墙纸；一个小的轮换库以零复杂度代价让这个时刻保持新鲜。
|
||||
|
||||
**把 slogan 库和显示速度做成配置。** 否决：那是为展示文案新增两个旋钮；对措辞有主张的部署已经有 `welcome` 这个出口，而「插件里不许硬编码可调参数」规则针对的是随部署变化的行为，不是品牌文案。
|
||||
|
||||
**在 `HeaderComponent` 内部做动画。** 否决：组件将需要持有 TUI 句柄和自己的生命周期；聊天层已经拥有渲染循环、定时器和释放路径，所以逐字显示与 `createTuiChat` 的其他资源放在一起，由 `detachListeners` 清除。
|
||||
|
||||
## Consequences
|
||||
|
||||
- `welcome` 未设置时启动输出不再字节级确定（随机 slogan、定时帧）。所有录制或快照表面都显式固定 `welcome`，因此没有快照变化；PTY 冒烟测试改为锚定逐字显示光标和会话 id 行。
|
||||
- `welcome` 的 schema 默认值从 `dsh-tui` 和 `dsh-tui-demo` 中消失；不传 welcome 的直接调用方现在得到的是 slogan，而不是 `'ready.'`。
|
||||
- 新增一条 slogan 只需在库里加一行；测试断言成员归属，不断言具体文本。
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 固定以下行为：注入随机源后的确定性选取、逐字显示（库中某条完整渲染、观察到光标帧）、配置了 welcome 时逐字动画不启动且原文渲染、以及 dispose 停止进行中的动画。`examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 在 PTY 里启动真实配置树并等待显示光标。已在 tmux 中实机验证（中途帧 `no map below▌`，随后是完整 slogan）。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-dsh-system-prompt-source-path.md: 9581966d10693e1ccbdce1a860314a34387e225e
|
||||
2026-07-21-dsh-system-prompt-source-path.zh.md: 392fcd44d988d483306effc34d4aaf4211803b4e
|
||||
@@ -0,0 +1,38 @@
|
||||
# Agent Note: dsh tells the agent where its own source lives
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-dsh-system-prompt-source-path.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The `dsh` CLI is the self-referential surface: its `cordis` toolset lets the agent inspect and modify the very harness runtime it runs in. But the agent had no way to learn where that source lives on disk. `dsh` is normally symlinked onto PATH and launched from an arbitrary working directory — the project under work — so neither the cwd nor `argv` reliably points at the harness checkout. Without the path, "read your own source" is guesswork.
|
||||
|
||||
## Decision
|
||||
|
||||
The `dsh` launcher (`apps/cli/src/tui.ts`) computes the harness checkout root from its own module URL — `fileURLToPath(new URL('../../..', import.meta.url))`, three hops up from `apps/cli/{src,lib}` — so it resolves to the real source location however `dsh` is launched (a PATH symlink, an arbitrary cwd). After `boot()` settles the tree, the launcher calls the new `addHarnessSourceSection(ctx, sourceRoot)` helper from `dsh-app-boot`, which registers a global `harness:source` prompt section reading `Your own source code is the checkout at <path>; you can read it there to learn how dsh works and how to extend it.` The section orders at `-99`, just after the harness identity opener (`-100`) and before the deployment persona (`0`).
|
||||
|
||||
The testable logic lives in `dsh-app-boot`, not in `apps/cli`, because `apps/*` are not coverage-gated and `packages/*` are. Resolving the optional `systemPrompt` service, registering the section, and returning the disposer belong where per-file 100% coverage applies; the launcher keeps only the thin glue — compute the path, call the helper — covered by the CLI's PTY e2e. When the booted tree has no `systemPrompt` service the helper is a no-op returning `undefined`.
|
||||
|
||||
## Scope
|
||||
|
||||
Only the `dsh` CLI adds this. The demo bins (`dsh-cli-demo`, `dsh-acp-demo`) boot their committed trees verbatim and gain no source section: they are not the self-modification surface, and their checkout root is not a fact the model needs.
|
||||
|
||||
## HMR
|
||||
|
||||
The section is registered against the booted `systemPrompt` service's own fiber (through `ctx.get('systemPrompt')`), so a dev HMR reload of the system-prompt plugin drops it until the next boot. Production HMR watches the config, not the built lib, so this is a dev-only wrinkle and acceptable.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Register the section inside the system-prompt service constructor.** It would then appear in every deployment, not just the self-referential CLI, and the source root would have to be threaded through config to reach the constructor. The path is a launcher fact, so the launcher owns injecting it.
|
||||
|
||||
**Keep the whole thing in `apps/cli/src/tui.ts`.** Apps are not coverage-gated, so the registration and absent-service branches would ship untested. Extracting the tested helper into `dsh-app-boot` keeps the gate meaningful; the launcher glue is exercised by the CLI's keyless PTY smoke.
|
||||
|
||||
**Add a cordis.yml config field for the path.** The path is not a deployment choice — it is mechanically the launcher's own location. A config field invites a stale hand-entered path and adds a knob with no legitimate variation.
|
||||
|
||||
**Resolve from `process.cwd()` or `process.argv[1]`.** The cwd is the user's project, and a PATH symlink makes `argv[1]` the symlink path; `import.meta.url` is the only handle on the real source location.
|
||||
|
||||
## Consequences
|
||||
|
||||
The agent's system prompt now names its own checkout, so the `cordis` toolset can read and edit harness source with no discovery step. `dsh-app-boot` gains a type-only dependency on `dsh-system-prompt` (peer + dev, matching the acp package's side-effect type import) for the `ctx.get('systemPrompt')` declaration merge; there is no runtime dependency. The section is model-visible text, pinned verbatim in an app-boot unit test and asserted end to end through the CLI's keyless PTY smoke — which boots `dsh` against the scripted config, runs a turn, and reads the path back out of the persisted `request/header` system prompt. The line sits before per-request content, so it does not perturb the KV cache across turns.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Agent Note: dsh 告知 agent 其自身源码所在位置
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-dsh-system-prompt-source-path.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
`dsh` CLI 是自我引用的接口：其 `cordis` 工具包让 agent（智能体）得以查看并修改它自身运行其上的 harness（智能体框架）运行时。但 agent 此前无从得知这份源码在磁盘上的位置。`dsh` 通常以符号链接的形式挂到 PATH 上，并从任意工作目录（正在处理的项目）启动，因此无论是 cwd 还是 `argv` 都无法可靠地指向 harness 检出目录。缺了这个路径，"读取你自己的源码"便只能靠猜。
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh` 启动器（`apps/cli/src/tui.ts`）从它自身的模块 URL 计算 harness 检出根目录——`fileURLToPath(new URL('../../..', import.meta.url))`，从 `apps/cli/{src,lib}` 向上三级——因此无论 `dsh` 以何种方式启动（PATH 符号链接、任意 cwd），它都能解析到真实的源码位置。在 `boot()` 使插件树就位之后，启动器调用来自 `dsh-app-boot` 的新辅助函数 `addHarnessSourceSection(ctx, sourceRoot)`，它注册一个全局 `harness:source` 提示词段，内容为 `Your own source code is the checkout at <path>; you can read it there to learn how dsh works and how to extend it.`。该段的 order 为 `-99`，恰在 harness 身份开场（`-100`）之后、部署 persona（`0`）之前。
|
||||
|
||||
可测试的逻辑放在 `dsh-app-boot` 而非 `apps/cli` 中，因为 `apps/*` 不受覆盖率门禁约束，而 `packages/*` 受约束。解析可选的 `systemPrompt` 服务、注册该段、返回 dispose（资源释放）器，这些都属于按文件 100% 覆盖率生效的地方；启动器只保留那层薄薄的黏合——计算路径、调用辅助函数——由 CLI 的 PTY e2e 覆盖。当就位的插件树没有 `systemPrompt` 服务时，该辅助函数是一个返回 `undefined` 的空操作。
|
||||
|
||||
## Scope
|
||||
|
||||
只有 `dsh` CLI 会加入这一段。demo bin（`dsh-cli-demo`、`dsh-acp-demo`）原样引导它们已提交的插件树，不会获得 source 段：它们不是自我修改的接口，其检出根目录也不是模型需要知道的事实。
|
||||
|
||||
## HMR
|
||||
|
||||
该段是针对就位后的 `systemPrompt` 服务自身的 fiber 注册的（通过 `ctx.get('systemPrompt')`），因此对 system-prompt 插件做一次开发态 HMR（热模块替换）重载会丢弃它，直到下一次引导为止。生产环境的 HMR 监视的是配置而非构建产物 lib，所以这只是一个仅限开发态的小瑕疵，可以接受。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**在 system-prompt 服务的构造函数内注册该段。** 那样它会出现在每一个部署中，而不只是自我引用的 CLI，而且源码根目录还得穿过配置才能到达构造函数。这个路径是启动器的事实，所以由启动器负责注入它。
|
||||
|
||||
**把整件事都留在 `apps/cli/src/tui.ts` 里。** apps 不受覆盖率门禁约束，因此注册逻辑与服务缺失分支会以未受测的形式发布。把受测的辅助函数抽取到 `dsh-app-boot` 让门禁保持有效；启动器的黏合部分由 CLI 的无密钥 PTY 冒烟测试演练。
|
||||
|
||||
**为该路径新增一个 cordis.yml 配置键。** 这个路径不是一项部署选择——它在机制上就是启动器自身的位置。配置键会招致手工填入的路径变陈旧，并新增一个没有合理变化空间的旋钮。
|
||||
|
||||
**从 `process.cwd()` 或 `process.argv[1]` 解析。** cwd 是用户的项目，而 PATH 符号链接会使 `argv[1]` 成为符号链接自身的路径；`import.meta.url` 是唯一能抓住真实源码位置的把手。
|
||||
|
||||
## Consequences
|
||||
|
||||
agent 的系统提示词现在会写明它自己的检出目录，因此 `cordis` 工具包无需一个发现步骤就能读取并编辑 harness 源码。`dsh-app-boot` 为 `ctx.get('systemPrompt')` 的声明合并新增了一个对 `dsh-system-prompt` 的仅类型依赖（peer dependency（对等依赖）+ dev，与 acp 包的副作用型类型 import 模式一致）；不存在运行时依赖。该段是模型可见文本，在 app-boot 单元测试中逐字锁定，并通过 CLI 的无密钥 PTY 冒烟测试端到端断言——该测试以脚本化配置引导 `dsh`、运行一个轮次，再从持久化的 `request/header` 系统提示词中把路径读回来。这一行位于按请求变化的内容之前，所以它不会在多个轮次间扰动 KV Cache。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-auto-pane-title.md: 5235ffb12807b7e24ef952df594052ed7aa65cdf
|
||||
2026-07-21-tui-auto-pane-title.zh.md: 0b93d5a0a9d31e9f4321ca7ae975c1db74d2229e
|
||||
@@ -0,0 +1,42 @@
|
||||
# Agent Note: Auto-titled terminal from the first message
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-auto-pane-title.zh.md)
|
||||
|
||||
> **Superseded** by the [session-title consolidation Agent Note](../simplification/2026-07-22-tui-titles-from-session-title-service.md): the TUI-local `autoTitle` generation is removed; titles come from the log-backed session-title service, and the terminal rename consumes `session/title` events.
|
||||
|
||||
> **Superseded** for the default and the resume behavior by the [auto-title default-on Agent Note](2026-07-21-tui-auto-title-default-on.md): `autoTitle` now defaults on, and a resumed session re-derives its title from the stored first message instead of keeping the static one. The OSC 0 path, the one-shot latch, the model-summary shape, the fire-and-forget call, and every failure fallback below stand.
|
||||
|
||||
## Problem
|
||||
|
||||
The TUI's terminal title is a single static string (`title`, default `DeepSeek Harness`) shared by every session. A user who runs one agent per tmux pane or terminal tab sees the same label on all of them, so panes are indistinguishable at a glance and the tab bar carries no signal about what each session is doing.
|
||||
|
||||
## Decision
|
||||
|
||||
- `TuiConfig` gains an `autoTitle` boolean (default `false`). When it is on, the TUI issues one background model call after the first user message of a fresh session and replaces the terminal title with a short, model-generated label; the static `title` is the pre-title and the fallback.
|
||||
- The label is a model summary, not a truncation of the prompt. The request carries a fixed task instruction (summarize the request as a short title of two to five lowercase words, no punctuation) plus the user's first message and no tools; the TUI takes the first non-empty line of the reply and caps it at 40 characters (39 plus an ellipsis).
|
||||
- The title is set through `runtime.terminal.setTitle`, the same OSC 0 path the static `title` already uses. No new terminal-control surface is introduced, and pi-tui keeps ownership of terminal writes.
|
||||
- The call is fire-and-forget and one-shot per session. A `titleSettled` latch guards it: with `autoTitle` off it is pre-settled and never runs; on a resumed session whose first `user/message` is already logged it is pre-settled so the static title stands; a whitespace-only first message is skipped without consuming the slot. Any failure, an empty reply, a missing `llm` service, or a missing agent provider/model leaves the static title untouched. A dedicated `AbortController` cancels an in-flight request on shutdown.
|
||||
- The title call reaches `ctx.llm.stream` directly rather than through `agent.send`, so it never appends to the session or transcript and cannot perturb the agent loop.
|
||||
- The feature defaults off and is enabled only in the interactive product config (`examples/tui-agent/cordis.yml`) and the scripted PTY fixture. Enabling it in the shared `dsh-tui-demo` schema default would fire an extra model call in keyless replay and boot scenarios that send no user message.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Truncate the first user message instead of a model title.** Rejected: the user chose a short model-made label; a truncated raw prompt is noisy, often begins with boilerplate, and rarely reads as a title.
|
||||
|
||||
**Rename the window (OSC 2) or the tmux window.** Rejected: OSC 0 sets only `pane_title`, so it labels the pane without renaming or leaking into the user's window title; the user confirmed OSC is the right lever.
|
||||
|
||||
**Default the feature on.** Rejected: enabling it in the shared demo schema perturbs keyless replay and boot snapshots and spends a model call on every fresh session; opt-in per deployment keeps the default surface inert.
|
||||
|
||||
**Fold this into the log-backed session-title work (PR #451).** Rejected: that change is session metadata persisted to the log; this is a terminal label with no persistence. Keeping them independent leaves each self-contained and avoids a shared dependency.
|
||||
|
||||
**Block the first turn until the title resolves.** Rejected: awaiting the title before sending the user's message adds latency to the actual request; fire-and-forget makes the rename invisible to the turn.
|
||||
|
||||
## Consequences
|
||||
|
||||
- When enabled, a fresh session spends one extra, tool-less model call with a single short user message and a few output tokens; off by default, it costs nothing.
|
||||
- Because the title call stamps `sessionId`, it shares the session's `llm-replay` cursor: enabling `autoTitle` in a replay-backed snapshot scenario would consume a recorded script entry. This is why the default is off and the scripted PTY fixture answers the call with a tool-branching adapter rather than replay.
|
||||
- `packages/ui/tui/tests/tui.spec.ts` pins the behavior with a mock `llm` adapter: a generated title replaces the static one, over-long output is truncated with an ellipsis, a whitespace-only first message keeps the one-shot slot, empty or failing replies leave the title, a resumed session never fires, and the feature-off / no-service / missing-provider / missing-model paths keep the static title. A shutdown test asserts the in-flight request is aborted.
|
||||
- `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` proves the real Loader-booted path: the scripted adapter answers the tool-less title call with a fixed string, and the conversation scenario asserts the OSC 0 sequence reaches the PTY. Boot scenarios send no user message, so they never fire the call.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Agent Note: 从首条消息自动命名终端
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-auto-pane-title.md) | 中文
|
||||
|
||||
> **已被取代**：见[标题归一 Agent Note](../simplification/2026-07-22-tui-titles-from-session-title-service.md)。TUI 本地的 `autoTitle` 生成已移除；标题来自日志承载的 session-title 服务，终端重命名消费 `session/title` 事件。
|
||||
|
||||
> **已被取代**（就默认值与恢复行为而言），见[自动标题默认开启 Agent Note](2026-07-21-tui-auto-title-default-on.md)：`autoTitle` 现默认开启，恢复会话会从已存储的首条消息重新推导标题，而非保留静态标题。下文的 OSC 0 路径、一次性门闩、模型概括形态、发出后不等待其返回的调用，以及每一条失败兜底，均仍然成立。
|
||||
|
||||
## Problem
|
||||
|
||||
TUI 的终端标题是一个所有会话共用的静态字符串（`title`，默认 `DeepSeek Harness`）。在 tmux 每个窗格或每个终端标签页各跑一个 agent（智能体）的用户看来，它们的标签全都一样，因此窗格一眼看去无从区分，标签栏也不携带任何关于各会话正在做什么的信号。
|
||||
|
||||
## Decision
|
||||
|
||||
- `TuiConfig` 新增布尔字段 `autoTitle`（默认 `false`）。开启后，TUI 会在全新会话的首条用户消息之后发起一次后台模型调用，并用一个简短的、模型生成的标签替换终端标题；静态 `title` 是替换前的初值，也是兜底。
|
||||
- 该标签是模型概括，而非对提示词的截断。请求携带一段固定的任务指令（将该请求概括为两到五个小写单词、不含标点的简短标题）加上用户的首条消息，且不带工具；TUI 取回复的首个非空行并截断到 40 个字符（39 个字符加一个省略号）。
|
||||
- 标题通过 `runtime.terminal.setTitle` 设置——静态 `title` 已经在用的同一条 OSC 0 路径。不引入任何新的终端控制面，终端写入仍归 pi-tui 所有。
|
||||
- 该调用发出后不等待其返回，且每会话仅一次。一个 `titleSettled` 门闩守护它：`autoTitle` 关闭时它预先置为已结算、从不运行；在首条 `user/message` 已入日志的恢复会话中它预先结算，因此静态标题得以保留；仅含空白的首条消息被跳过且不消耗名额。任何失败、空回复、缺少 `llm` 服务、或缺少 agent 的 `provider` 或 `model`，都会让静态标题保持不动。一个专用的 `AbortController` 在关闭时取消尚在进行的请求。
|
||||
- 标题调用直接抵达 `ctx.llm.stream`，而非经由 `agent.send`，因此它从不追加进会话或 transcript（文本记录），也无法扰动 agent loop（智能体循环）。
|
||||
- 该功能默认关闭，仅在交互式产品配置（`examples/tui-agent/cordis.yml`）与脚本化 PTY fixture（测试前置数据）中开启。若在共享的 `dsh-tui-demo` schema 默认值里开启，会在不发送任何用户消息的无密钥回放与启动场景中多发一次模型调用。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**截断首条用户消息，而非用模型生成标题。** 否决：用户选择的是简短的、模型制作的标签；截断后的原始提示词嘈杂、常以样板文字开头，且很少读起来像标题。
|
||||
|
||||
**重命名窗口（OSC 2）或 tmux 窗口。** 否决：OSC 0 只设置 `pane_title`，因此它标记窗格而不重命名、也不泄漏进用户的窗口标题；用户确认 OSC 是正确的手段。
|
||||
|
||||
**让该功能默认开启。** 否决：在共享的 demo schema 里开启会扰动无密钥回放与启动快照，并在每个全新会话上花掉一次模型调用；按部署选择性开启可让默认面保持惰性。
|
||||
|
||||
**并入日志支撑的会话标题工作（PR #451）。** 否决：那项改动是持久化到日志的会话元数据；本项是不做持久化的终端标签。让二者相互独立可使各自自成一体，并避免共享依赖。
|
||||
|
||||
**阻塞首轮直到标题就绪。** 否决：在发送用户消息前先等待标题，会给实际请求增加延迟；发出后不等待其返回可让重命名对该轮次不可见。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 开启时，全新会话会多花一次无工具的模型调用，只带单条简短的用户消息和少量输出 token；默认关闭时它不产生任何开销。
|
||||
- 由于标题调用会打上 `sessionId`，它与会话的 `llm-replay` 游标共享：在以回放支撑的快照场景中开启 `autoTitle` 会消耗一条录制脚本条目。这正是它默认关闭、且脚本化 PTY fixture 用按工具分支的适配器而非回放来回答该调用的原因。
|
||||
- `packages/ui/tui/tests/tui.spec.ts` 用一个 mock `llm` 适配器固定该行为：生成的标题替换静态标题、过长输出以省略号截断、仅含空白的首条消息保留一次性名额、空回复或失败回复保留标题、恢复的会话从不触发，以及功能关闭 / 无服务 / 缺提供方 / 缺模型各路径都保留静态标题。一项关闭测试断言尚在进行的请求被中止。
|
||||
- `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 证明真实的经 Loader 启动的路径：脚本化适配器以固定字符串回答无工具的标题调用，对话场景断言 OSC 0 序列抵达 PTY。启动场景不发送用户消息，因此它们从不触发该调用。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-auto-title-default-on.md: 498c6095fcd05c40ce2ad48364a9ac02beb9aa05
|
||||
2026-07-21-tui-auto-title-default-on.zh.md: 8bd426c8705d84f674f811347c04ef42de7cae15
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: Auto-title on by default, re-derived on resume
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-auto-title-default-on.zh.md)
|
||||
|
||||
> **Superseded** by the [session-title consolidation Agent Note](../simplification/2026-07-22-tui-titles-from-session-title-service.md): the TUI-local `autoTitle` generation is removed; titles come from the log-backed session-title service, and the terminal rename consumes `session/title` events.
|
||||
|
||||
## Problem
|
||||
|
||||
The [auto-title Agent Note](2026-07-21-tui-auto-pane-title.md) shipped `autoTitle` off by default and, on a resumed session, kept the static title because the first `user/message` was already logged. In use both choices defeated the feature's purpose. A per-session descriptive pane title is what makes one tmux pane or terminal tab distinguishable from the next; leaving it off by default means the product ships an inert feature that almost no user turns on, and skipping re-derivation on resume means a resumed session — exactly the long-lived session most worth labelling — falls back to the shared static string. The user asked for a descriptive per-session name to be the normal experience.
|
||||
|
||||
## Decision
|
||||
|
||||
- `autoTitle` defaults **on** (`z.boolean().default(true)`, mirrored by `resolveTuiConfig`'s `?? true`). A deployment with an `llm` service and an agent provider/model gets a model-made pane title on every session without opting in; one without them keeps the static title, so default-on is inert where the call cannot run.
|
||||
- A **resumed** session re-derives the title on mount from its already-logged first `user/message`: `createTuiChat` scans `agent.session.events` for the first such event and feeds its text to the same one-shot `generateTitle`. The title is never persisted (the session header carries no title field), so it is always derived, never restored.
|
||||
- The one-shot latch is now simply `titleSettled = !resolved.autoTitle`. The prior pre-settle-on-resume clause is gone: on resume `generateTitle` runs once from the stored first message and then latches, so a message that arrives *after* the resume does not re-title. A fresh session has no stored `user/message` at mount, so the resume scan is a no-op and the live `session/event` listener titles the first message instead.
|
||||
- Everything else from the [auto-title Agent Note](2026-07-21-tui-auto-pane-title.md) stands unchanged: the OSC 0 `runtime.terminal.setTitle` path, the model-summary shape (two-to-five lowercase words, first non-empty line, 40-char cap), the fire-and-forget `ctx.llm.stream` call that never touches the session or transcript, the shutdown `AbortController`, and every failure fallback (empty reply, missing `llm`, missing provider/model, whitespace-only prompt).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the feature off by default.** Rejected: this is a direct reversal of the [auto-title Agent Note](2026-07-21-tui-auto-pane-title.md)'s "default off" decision at the user's request. Off-by-default ships an inert feature; the descriptive name is only useful if it is the normal experience. The keyless-replay concern that motivated off-by-default is addressed by pinning `autoTitle: false` in the replay-backed snapshot scenarios rather than by suppressing it for every deployment.
|
||||
|
||||
**Persist the derived title in the session header.** Rejected: the header has no title field and adding one would make a terminal label into session metadata — the boundary the [auto-title Agent Note](2026-07-21-tui-auto-pane-title.md) already drew against the log-backed session-title work. Re-deriving from the stored first message costs one tool-less call on resume and keeps the label a pure function of the conversation.
|
||||
|
||||
**Re-derive on resume from the latest message instead of the first.** Rejected: the title summarises what the session is *about*, which its opening request captures; a mid-conversation message would make the pane label drift as the work moves on.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A fresh session with a working `llm` now spends one extra tool-less model call by default (previously only when opted in); a resumed session spends one on mount. Deployments without an `llm` or provider/model are unaffected.
|
||||
- The replay-backed `examples/tui-agent/tests/tui.snapshot.ts` must opt **out**: it pins `autoTitle: false`, because a default-on title request is not among the recorded turns and `installLlmReplay` fails loud on an unrecorded request. The unit `packages/ui/tui/tests/tui.snapshot.ts` needs no opt-out — it mounts no `llm` service, so `generateTitle` short-circuits and the default flip is inert there. The interactive `examples/tui-agent/cordis.yml` and the scripted PTY fixture already set `autoTitle: true`, so the keyless smoke's OSC 0 assertion is unchanged.
|
||||
- `packages/ui/tui/tests/tui.spec.ts` pins the new defaults: the config-default test expects `autoTitle: true`; the disabled-path test now sets `autoTitle: false` explicitly; and the former "resumed session never fires" test is rewritten to assert re-derivation from the stored first message and that a later live message does not re-title. `docs/config-catalog.md` regenerates to "On by default".
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: 自动标题默认开启，恢复时重新推导
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-auto-title-default-on.md) | 中文
|
||||
|
||||
> **已被取代**：见[标题归一 Agent Note](../simplification/2026-07-22-tui-titles-from-session-title-service.md)。TUI 本地的 `autoTitle` 生成已移除；标题来自日志承载的 session-title 服务，终端重命名消费 `session/title` 事件。
|
||||
|
||||
## Problem
|
||||
|
||||
[自动标题 Agent Note](2026-07-21-tui-auto-pane-title.md) 交付时 `autoTitle` 默认关闭，并且在恢复会话中因首条 `user/message` 已入日志而保留静态标题。实际使用中这两个选择都违背了该功能的初衷。让一个 tmux 窗格或终端标签页区别于下一个的，正是每会话各异的描述性窗格标题；默认关闭意味着产品交付了一个几乎无人开启的惰性功能，而恢复时不重新推导，则意味着恢复会话——恰恰是最值得标记的长命会话——退回到共用的静态字符串。用户要求把每会话的描述性名称做成常态体验。
|
||||
|
||||
## Decision
|
||||
|
||||
- `autoTitle` 默认**开启**（`z.boolean().default(true)`，`resolveTuiConfig` 以 `?? true` 与之对齐）。带有 `llm` 服务与 agent 提供方/模型的部署无需选择性开启即可在每个会话获得模型制作的窗格标题；不具备它们的部署保留静态标题，因此在调用无法运行处，默认开启是惰性的。
|
||||
- **恢复**会话在挂载时从其已入日志的首条 `user/message` 重新推导标题：`createTuiChat` 在 `agent.session.events` 中扫描首个此类事件，并把其文本喂给同一个一次性的 `generateTitle`。标题从不持久化（会话头不携带标题字段），因此它始终是推导得来，而非恢复而来。
|
||||
- 一次性门闩现在只是 `titleSettled = !resolved.autoTitle`。此前"恢复即预先结算"的分句已删除：恢复时 `generateTitle` 从已存储的首条消息运行一次随后上闩，因此恢复*之后*到达的消息不会再改标题。全新会话在挂载时没有已存储的 `user/message`，因此恢复扫描是空操作，改由实时的 `session/event` 监听器为首条消息命名。
|
||||
- [自动标题 Agent Note](2026-07-21-tui-auto-pane-title.md) 的其余一切保持不变：OSC 0 的 `runtime.terminal.setTitle` 路径、模型概括形态（两到五个小写单词、首个非空行、40 字符上限）、从不触碰会话或 transcript（文本记录）的发出后不等待其返回的 `ctx.llm.stream` 调用、关闭时的 `AbortController`，以及每一条失败兜底（空回复、缺 `llm`、缺提供方/模型、仅含空白的提示词）。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**让该功能保持默认关闭。** 否决：这是应用户要求，对[自动标题 Agent Note](2026-07-21-tui-auto-pane-title.md)"默认关闭"决策的直接反转。默认关闭交付的是惰性功能；只有当描述性名称成为常态体验时它才有用。当初促成默认关闭的无密钥回放顾虑，改由在以回放支撑的快照场景中固定 `autoTitle: false` 来处理，而非为每个部署都压制该功能。
|
||||
|
||||
**把推导出的标题持久化进会话头。** 否决：会话头没有标题字段，加一个会把终端标签变成会话元数据——正是[自动标题 Agent Note](2026-07-21-tui-auto-pane-title.md)已经对日志支撑的会话标题工作划出的边界。从已存储的首条消息重新推导，代价是恢复时一次无工具调用，并让标签保持为对话的纯函数。
|
||||
|
||||
**恢复时从最新消息而非首条消息重新推导。** 否决：标题概括的是会话*关于什么*，而这由其开场请求捕获；一条对话中途的消息会让窗格标签随工作推进而漂移。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 带可用 `llm` 的全新会话现在默认多花一次无工具的模型调用（此前只在选择性开启时才有）；恢复会话在挂载时花掉一次。不具备 `llm` 或提供方/模型的部署不受影响。
|
||||
- 以回放支撑的 `examples/tui-agent/tests/tui.snapshot.ts` 必须选择**关闭**：它固定 `autoTitle: false`，因为默认开启的标题请求不在录制轮次之列，而 `installLlmReplay` 对未录制的请求会显式报错。单元 `packages/ui/tui/tests/tui.snapshot.ts` 无需选择关闭——它不挂载 `llm` 服务，因此 `generateTitle` 提前短路，默认值的翻转在那里是惰性的。交互式的 `examples/tui-agent/cordis.yml` 与脚本化 PTY fixture（测试前置数据）已设 `autoTitle: true`，因此无密钥冒烟测试的 OSC 0 断言保持不变。
|
||||
- `packages/ui/tui/tests/tui.spec.ts` 固定新的默认值：config 默认测试期望 `autoTitle: true`；关闭路径测试现在显式设 `autoTitle: false`；此前的"恢复会话从不触发"测试改写为断言从已存储首条消息重新推导，并断言之后的实时消息不会再改标题。`docs/config-catalog.md` 重新生成为"On by default"。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-banner-brand-gradient.md: 3516b0dcf9b6949721ec3e0d062f2d135da21083
|
||||
2026-07-21-tui-banner-brand-gradient.zh.md: 6fd0f140d474d26860eef77d64d5df550709d940
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: TUI banner brand gradient
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-banner-brand-gradient.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The TUI startup banner rendered the product name `DEEPSEEK` in the palette's flat accent color, which carries no brand identity and does not resemble the wordmark on deepseek.com. The request was to make the banner match the site logo's blue gradient specifically — not to recolor the rest of the coding harness.
|
||||
|
||||
The banner is the one surface where that matters, and it conflicts with a load-bearing invariant: the TUI palette is deliberately theme-agnostic. It uses only standard 16-color ANSI (SGR) codes and attributes so a user's terminal scheme remaps every color; the `themeViolations()` snapshot gate rejects any RGB, extended-palette, or explicit-background cell. A smooth logo-matching gradient cannot be built from 16 palette colors, so reproducing it requires 24-bit truecolor, which the gate flags by design.
|
||||
|
||||
## Decision
|
||||
|
||||
The banner paints `DEEPSEEK` with a per-letter 24-bit truecolor foreground sweeping the deepseek.com brand gradient — `#4D6BFE` → `#3982FF` → `#2498FF` — via piecewise-linear interpolation across those three stops; `HARNESS` stays bold with the default foreground. The gradient is foreground-only, so it stays legible on any terminal background, and it is confined to the banner's product name. This is the sole sanctioned exception to the theme-agnostic palette; every other surface remains standard-ANSI and theme-adaptive.
|
||||
|
||||
The gradient is gated on `resolved.color && resolved.truecolor`. When truecolor is unavailable the banner falls back to the existing flat bright-blue accent, so nothing about the theme-agnostic guarantee or the recorded snapshots changes unless truecolor is explicitly in play.
|
||||
|
||||
`truecolor` is a validated `Config` field with no schema default. When it is unset, `apply()` auto-detects it at the process boundary from `COLORTERM` (`truecolor` or `24bit`); an explicit config value always wins. Detection reads `process.env` only in `apply()` — never in the pure `resolveTuiConfig` resolver — keeping the resolver a pure function of its input.
|
||||
|
||||
The gradient stops are fixed brand identity, treated like a protocol constant, so they are hardcoded in the plugin rather than exposed as a tunable. Whether truecolor is *enabled* is terminal- and deployment-varying, so that is the validated `Config` field. The banner text is UI-only and never reaches a model request, so no session event is required.
|
||||
|
||||
## Testing
|
||||
|
||||
A dedicated `banner-gradient` terminal snapshot pins the real per-letter RGB output in an xterm emulator (`fg=#4d6bfe`…`#2498ff`, each letter bold). The shared `checkpoint()` helper takes a `bannerGradient` flag: for that one checkpoint it asserts the theme violations are non-empty and that every violation ends in `rgb-fg` — i.e. truecolor is present but confined to the banner foreground, with no background or extended-palette leak. Every other checkpoint keeps the strict `themeViolations()` `.toEqual([])` assertion, so the fence is mechanically enforced. A `tui.spec.ts` unit test mounts with `color`+`truecolor` enabled to cover the header's gradient branch and the `gradientText`/`brandColorAt` helpers.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**A theme-safe stepped gradient built from the 16-color palette.** Approximating the sweep with bright-blue palette variants would keep the banner fully theme-agnostic and avoid touching the gate. It was rejected by the requester: 16 fixed colors cannot reproduce the smooth logo gradient, and the request was explicitly to match the site wordmark.
|
||||
|
||||
**Recoloring the whole harness palette blue.** The original phrasing was "update the harness color to blue." That was narrowed to the banner only; a global blue palette would break theme-agnosticism everywhere, not just on one brand surface.
|
||||
|
||||
**Always emitting truecolor.** Many terminals lack 24-bit support and would render the raw or degraded codes. Gating on detection with an ANSI fallback keeps the banner correct everywhere while still showing the gradient where it works.
|
||||
|
||||
**Detecting truecolor inside `resolveTuiConfig`.** The resolver is a pure defaulting step and must not read `process.env`. Environment probing belongs at the process boundary in `apply()`, so `mountTui`/`createTuiChat` stay driven purely by their config input and remain fully testable with a fake terminal.
|
||||
|
||||
## Consequences
|
||||
|
||||
The banner now carries the DeepSeek brand identity on truecolor terminals while the theme-agnostic guarantee holds everywhere else — and even on the banner itself when truecolor is unavailable. The cost is one narrow, documented crack in the theme-agnostic invariant: a fixed-color surface that will not adapt to a user's terminal scheme, accepted because it is brand identity and foreground-only, so it stays legible on both light and dark backgrounds. The crack is fenced by the `banner-gradient` snapshot assertion, which confines truecolor to the banner foreground and fails if any other RGB, extended-palette, or background color ever appears.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: TUI 启动横幅品牌渐变
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-banner-brand-gradient.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
TUI 启动横幅原本用调色板的扁平强调色渲染产品名 `DEEPSEEK`，它不承载任何品牌标识，也不像 deepseek.com 上的字标。需求明确是让横幅匹配站点 logo 的蓝色渐变——而不是给整个 coding harness 重新上色。
|
||||
|
||||
横幅是唯一在意这件事的界面，而它与一条承重不变量冲突：TUI 调色板刻意做到主题无关。它只使用标准 16 色 ANSI（SGR）代码与属性，好让用户的终端配色方案能够重映射每一种颜色；`themeViolations()` 快照门禁会拒绝任何 RGB、扩展调色板或显式背景色的单元格。用 16 种调色板颜色无法拼出平滑的、与 logo 一致的渐变，因此复现它需要 24 位真彩色（truecolor），而门禁按设计会将其标记出来。
|
||||
|
||||
## 决策
|
||||
|
||||
横幅用逐字母的 24 位真彩色前景色渲染 `DEEPSEEK`，沿 deepseek.com 品牌渐变——`#4D6BFE` → `#3982FF` → `#2498FF`——在这三个色标之间做分段线性插值；`HARNESS` 保持加粗并使用默认前景色。渐变仅作用于前景色，因此在任何终端背景上都保持可读，并且被限制在横幅的产品名内。这是主题无关调色板唯一获准的例外；其余每个界面都保持标准 ANSI 且随主题自适应。
|
||||
|
||||
渐变以 `resolved.color && resolved.truecolor` 为开关。当真彩色不可用时，横幅回退到既有的扁平亮蓝强调色，因此除非显式启用真彩色，主题无关保证与已录制的快照都不会改变。
|
||||
|
||||
`truecolor` 是一个经校验的 `Config` 字段，schema 不设默认值。当它未设置时，`apply()` 会在进程边界从 `COLORTERM`（`truecolor` 或 `24bit`）自动探测；显式的配置值始终优先。探测只在 `apply()` 中读取 `process.env`——绝不在纯粹的 `resolveTuiConfig` 解析器中——从而让解析器保持为其输入的纯函数。
|
||||
|
||||
渐变色标是固定的品牌标识，被当作协议常量对待，因此硬编码在插件里，而不作为可调项暴露。是否*启用*真彩色则随终端与部署而变，所以那才是经校验的 `Config` 字段。横幅文本仅面向界面，永不进入任何模型请求，因此不需要会话事件。
|
||||
|
||||
## 测试
|
||||
|
||||
一个专门的 `banner-gradient` 终端快照在 xterm 模拟器中固定了真实的逐字母 RGB 输出（`fg=#4d6bfe`…`#2498ff`，每个字母加粗）。共享的 `checkpoint()` 辅助函数接受一个 `bannerGradient` 标志：仅对该 checkpoint，它断言主题违规项非空，且每一项都以 `rgb-fg` 结尾——即真彩色确实存在，但被限制在横幅前景色，没有背景色或扩展调色板的泄漏。其余每个 checkpoint 都保持严格的 `themeViolations()` `.toEqual([])` 断言，因此这道围栏是机械强制的。一个 `tui.spec.ts` 单元测试在同时启用 `color` 与 `truecolor` 时挂载，以覆盖 header 的渐变分支以及 `gradientText`/`brandColorAt` 辅助函数。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**用 16 色调色板拼出的主题安全阶梯渐变。** 用亮蓝的调色板变体近似这段渐变可以让横幅完全保持主题无关，并避免触碰门禁。它被需求方否决了：16 种固定颜色无法复现平滑的 logo 渐变，而需求明确是匹配站点字标。
|
||||
|
||||
**给整个 harness 调色板重新上蓝色。** 最初的说法是"把 harness 颜色改成蓝色"。它被收窄到只改横幅；全局蓝色调色板会在各处而非仅一个品牌界面上破坏主题无关性。
|
||||
|
||||
**始终发射真彩色。** 许多终端不支持 24 位，会渲染出原始或降级的代码。以探测为开关并配以 ANSI 回退，能让横幅在各处都正确，同时仍在支持的地方展示渐变。
|
||||
|
||||
**在 `resolveTuiConfig` 内探测真彩色。** 该解析器是纯粹的默认值填充步骤，绝不能读取 `process.env`。环境探测属于 `apply()` 中的进程边界，从而让 `mountTui`/`createTuiChat` 完全由其配置输入驱动，并在使用假终端时保持完全可测。
|
||||
|
||||
## 后果
|
||||
|
||||
现在横幅会在真彩色终端上承载 DeepSeek 品牌标识，而主题无关保证在其余各处依然成立——甚至当真彩色不可用时在横幅自身上也成立。代价是主题无关不变量上一道狭窄且有记录的裂缝：一个不会随用户终端配色方案自适应的固定颜色界面，之所以接受，是因为它是品牌标识且仅作用于前景色，从而在浅色与深色背景上都保持可读。这道裂缝由 `banner-gradient` 快照断言把守，它将真彩色限制在横幅前景色，一旦其他任何 RGB、扩展调色板或背景色出现就会失败。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-banner-sweep.md: 3351ff40e50fb3ef4de569cab0a33f311ea24a46
|
||||
2026-07-21-tui-banner-sweep.zh.md: e783ec20158c5a3be07b4afdf539463763d40948
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: The banner sweeps in; the subtitle line is gone
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-banner-sweep.zh.md)
|
||||
|
||||
> **Superseded** by the [no-banner Agent Note](2026-07-21-tui-no-banner.md): the banner itself was removed, taking the sweep with it.
|
||||
|
||||
## Problem
|
||||
|
||||
The [startup-slogans Agent Note](2026-07-20-tui-startup-slogans.md) replaced the instructional welcome line with a random slogan bank revealed by a per-character typewriter. In use the quotes read as weird — random flavor text in a tool's header — and the animation was slow (40 ms/char over a full sentence) while animating only one line of a four-line banner. This note supersedes that decision's slogan half; the removal of the configured demo welcome and the animation-lifecycle groundwork stand.
|
||||
|
||||
## Decision
|
||||
|
||||
- The slogan bank, `pickStartupSlogan`, and the typewriter reveal are deleted. When `welcome` is unset the banner simply has **no subtitle line** — title and model/session detail only. The `welcome` config remains for deployments and fixtures that want a fixed subtitle, rendered frame-deterministically with no animation.
|
||||
- The startup animation is now the **whole banner**: `HeaderComponent` gains a `revealWidth` clip, and the header box wipes in left-to-right over ~24 frames at 15 ms (~360 ms total, ~60 fps), started after `ui.start()` succeeds and cleared through the same `detachListeners` path the typewriter used. `stopBannerReveal` also resets the clip so a disposed-mid-sweep header re-renders whole.
|
||||
- The PTY smoke's boot marker changes from the typewriter cursor (`▌`) to the banner's top-right corner (`╮`), which only renders once the sweep completes.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the animation as-is and only change the copy.** Rejected: any fixed or rotating phrase re-read on every boot decays into wallpaper; the user's judgment was that the quotes themselves, not just their content, were wrong for the surface.
|
||||
|
||||
**Animate per banner line (top-down) instead of a left-right sweep.** Rejected: with only four lines the animation would have four visible steps — closer to a flicker than a reveal; the horizontal sweep uses the full terminal width for a smooth motion at the same total duration.
|
||||
|
||||
**Character-level clipping via `revealWidth` on styled text.** Adopted with `truncateToWidth` from pi-tui, the same ANSI-aware clipper the header already uses for width overflow, so the sweep cannot tear escape sequences.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Boot output with `welcome` unset is again animation-dependent but no longer random: every boot sweeps the same banner. Configured welcomes (all snapshot/scripted fixtures, the Code Mode overlay) stay frame-deterministic and unchanged.
|
||||
- The `STARTUP_SLOGANS`/`pickStartupSlogan` exports are gone; no consumer outside the deleted tests referenced them.
|
||||
- The default banner is one line shorter (no subtitle), so PTY assertions anchored on banner geometry use the corner glyph rather than any subtitle text.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` pins: the sweep completes to a full banner (both corners + title) and produced at least one clipped mid-sweep frame; a configured welcome renders verbatim with no clipped frames; the unset-welcome banner has no subtitle; and dispose clears the sweep's own interval handle. The PTY smoke boots on the `╮` completion marker across the tui-demo bin, the dsh CLI, and the personal-overlay scenarios. Verified live in tmux.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: 横幅整体扫入；副标题行移除
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-banner-sweep.md) | 中文
|
||||
|
||||
> **已被取代**：由[移除启动横幅 Agent Note](2026-07-21-tui-no-banner.md)取代：横幅本身已移除，扫入动画随之移除。
|
||||
|
||||
## Problem
|
||||
|
||||
[启动 slogan Agent Note](2026-07-20-tui-startup-slogans.md) 用随机 slogan 库加逐字打字机动画取代了说明书式的欢迎行。实际使用中这些引语显得怪异——工具头部出现随机的风味文案——而且动画很慢（每字符 40 ms，扫完一整句），却只动画四行横幅中的一行。本 note 取代该决定中 slogan 的那一半；移除示例配置中欢迎语的决定与动画生命周期的基础设施保持不变。
|
||||
|
||||
## Decision
|
||||
|
||||
- 删除 slogan 库、`pickStartupSlogan` 和打字机动画。`welcome` 未设置时横幅直接**没有副标题行**——只有标题和模型/会话详情。`welcome` 配置保留给想要固定副标题的部署与 fixture，无动画、逐帧确定地渲染。
|
||||
- 启动动画现在作用于**整个横幅**：`HeaderComponent` 增加 `revealWidth` 裁剪，头部盒子以约 24 帧、每帧 15 ms（总计约 360 ms、约 60 fps）从左到右扫入，在 `ui.start()` 成功后启动，经打字机动画用过的同一条 `detachListeners` 路径清除。`stopBannerReveal` 同时重置裁剪，因此扫入中途被 dispose 的头部会重新完整渲染。
|
||||
- PTY 冒烟测试的启动标记从打字机光标（`▌`）改为横幅右上角（`╮`），它只在扫入完成后才渲染。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**保留动画原样、只改文案。** 否决：任何每次启动都被重读的固定或轮换语句都会退化成墙纸；用户的判断是引语本身——而不只是内容——对这个表面来说就是错的。
|
||||
|
||||
**按横幅行逐行（自上而下）动画而非左右扫入。** 否决：只有四行时动画只有四个可见步骤——更像闪烁而不是展开；水平扫入用满终端宽度，在相同总时长内动作更平滑。
|
||||
|
||||
**用 `revealWidth` 对带样式文本做字符级裁剪。** 采用 pi-tui 的 `truncateToWidth`——头部处理宽度溢出时已在使用的同一个 ANSI 感知裁剪器——因此扫入不可能撕裂转义序列。
|
||||
|
||||
## Consequences
|
||||
|
||||
- `welcome` 未设置时启动输出再次依赖动画但不再随机：每次启动扫入同一幅横幅。配置了欢迎语的场景（全部快照/脚本化 fixture、Code Mode overlay）保持逐帧确定且不变。
|
||||
- `STARTUP_SLOGANS`/`pickStartupSlogan` 导出移除；除被删除的测试外没有消费者引用它们。
|
||||
- 默认横幅少一行（无副标题），因此锚定横幅几何的 PTY 断言使用角落字形而非任何副标题文本。
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 固定：扫入完成为完整横幅（两个角 + 标题）且产生了至少一个裁剪的中途帧；配置的欢迎语原文渲染且无裁剪帧；未设置欢迎语的横幅没有副标题；dispose 清除扫入自己的定时器句柄。PTY 冒烟测试在 tui-demo bin、dsh CLI 和个人 overlay 场景中以 `╮` 完成标记启动。已在 tmux 中实机验证。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-borderless-banner.md: 09fe713544134865687162c4624090b8e9aa3ebf
|
||||
2026-07-21-tui-borderless-banner.zh.md: b11c6d3c8cd327d7779617b4a7939ce55d8b765c
|
||||
@@ -0,0 +1,47 @@
|
||||
# Agent Note: The banner returns, borderless
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-borderless-banner.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
An intermediate no-banner design removed the boxed startup banner: it deleted `HeaderComponent` and its sweep, moved the model into the footer, dropped the session id, and rendered `welcome` as the transcript's first line. The user's verdict reversed that: bring the banner back — "just remove the border". The four-row box frame was the objectionable chrome, not the identifying facts it carried (model, session id) nor the sweep-in motion.
|
||||
|
||||
## Decision
|
||||
|
||||
- `HeaderComponent` and its left-to-right sweep return, but render **borderless**: no `╭─╮`/`╰─╯` corners and no `│` side bars. Each line is a single leading space plus `truncateToWidth`-clipped content, so the sweep's width clip can never tear an escape sequence and no fixed frame is drawn. The reveal advances through about 24 frames at 15 ms each.
|
||||
- The header carries the title (`DEEPSEEK HARNESS`), a `<model> • <session-id>` detail line, and — when `welcome` is set — a muted subtitle. With `welcome` unset the header is title + detail only: there is no fixed or random slogan.
|
||||
- The model **also** stays in the footer's left segment, so the driving model remains glanceable after the transient banner scrolls out of view.
|
||||
- `welcome` reverts to a banner subtitle; the transcript-first-line notice is removed from `rebuildTranscript`.
|
||||
- The sweep animates only when `welcome` is unset. A configured `welcome` renders the whole banner immediately, keeping fixtures and snapshots frame-deterministic. The sweep starts after `ui.start()` succeeds and is cleared through the same `detachListeners` path via `stopBannerReveal`, which also resets the clip so a header disposed mid-sweep re-renders whole.
|
||||
|
||||
This note owns the current result of the discarded startup variants: random slogans with a per-character typewriter, a boxed whole-banner sweep, and no banner. The example composition does not set `welcome`; deployments and deterministic fixtures may still provide one. The model's persistent footer home from the no-banner variant remains.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the box but thin it or use lighter glyphs.** Rejected: the instruction was "just remove the border"; any surrounding glyph is the frame chrome the user objected to.
|
||||
|
||||
**Keep a random or fixed slogan when `welcome` is unset.** Rejected because repeated flavor copy becomes wallpaper and the per-character reveal was slow while animating only one line. An unset welcome therefore produces no subtitle, and the whole banner supplies the startup motion.
|
||||
|
||||
**Remove the banner entirely.** Rejected because the persistent footer is a good home for the model but not for the full identifying detail, while putting `welcome` in the transcript makes presentation configuration behave like conversation content.
|
||||
|
||||
**Reveal the banner top-down.** Rejected because four row-sized steps read as a flicker. The horizontal width clip uses the terminal span for smooth motion and reuses the ANSI-aware truncation path.
|
||||
|
||||
**Drop the model from the footer now that the banner shows it again.** Rejected: the banner is transient and scrolls away with the transcript, while the footer keeps the model visible for the whole session; that persistent location is deliberately preserved.
|
||||
|
||||
**Leave the session id out of the banner.** Rejected: with the box gone the detail line costs one row, and the user asked for the banner "as before", which carried `model • session-id`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Boot output with `welcome` unset is animation-dependent again (the sweep); configured welcomes stay frame-deterministic, so every snapshot and scripted fixture keeps a fixed subtitle.
|
||||
- The demo no longer supplies instructional welcome filler; an unset `welcome` means a subtitle-free banner, while the config remains the deterministic escape hatch for deployments and fixtures.
|
||||
- The model now appears twice at boot — banner detail and footer — intended redundancy: the banner is transient, the footer persistent.
|
||||
- `/clear` empties the transcript but not the header, so the banner and its configured subtitle survive `/clear`, unlike a transcript-based welcome line.
|
||||
- All pi-tui terminal snapshots and the examples/tui-agent replay snapshots re-recorded (`test:snapshot:refresh`): banner rows return with no box glyphs; footer rows keep the model prefix.
|
||||
- Anything that anchored on banner absence re-anchors on its presence: the PTY smoke boots on the detail line's `main-session-` id (revealed late in the sweep) and asserts `DEEPSEEK`/`HARNESS` present with no box corners.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` pins: the borderless banner sweeps to natural completion — no box corners, title and `main-session` detail present — with at least one clipped mid-sweep frame; a configured `welcome` renders the whole banner with no clipped frame; the unset-welcome banner has no subtitle; and dispose clears the sweep interval mid-sweep. Independent color-scheme cases cover reported light/dark transitions, a same-scheme no-op, and a terminal that throws on the DSR query write; `applyColorScheme` relies on `setStatus` to rederive the editor border instead of repeating the dead assignment that had broken per-file coverage. The tui-agent and dsh-CLI PTY smokes boot on the `main-session-` detail marker and assert no box corners. Snapshots verify the full frames.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Agent Note: 横幅回归，无边框
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-borderless-banner.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
一个中间的无横幅设计删掉了带框的启动横幅：它删除了 `HeaderComponent` 及其扫入动画，把模型移入页脚，丢弃了会话 id，并把 `welcome` 渲染为 transcript 的第一行。用户的裁决把这一切反转：把横幅拿回来——"just remove the border"。令人反感的装饰是那四行盒子边框，而不是它承载的识别信息（模型、会话 id），也不是扫入动效。
|
||||
|
||||
## Decision
|
||||
|
||||
- `HeaderComponent` 及其从左到右的扫入动画回归，但以**无边框**方式渲染：没有 `╭─╮`/`╰─╯` 边角，也没有 `│` 侧边。每一行都是一个前导空格加上经 `truncateToWidth` 裁剪的内容，因此扫入的宽度裁剪永远不会撕裂转义序列，也不绘制任何固定边框。扫入大约经过 24 帧完成，每帧间隔 15 ms。
|
||||
- 头部承载标题（`DEEPSEEK HARNESS`）、一条 `<model> • <session-id>` 详情行，以及——当设置了 `welcome` 时——一条弱化的副标题。`welcome` 未设置时头部只有标题加详情：不含固定或随机标语。
|
||||
- 模型**同时**保留在页脚的左段，因此在短暂的横幅滚出视野后，会话使用的模型仍可一瞥可见。
|
||||
- `welcome` 恢复为横幅副标题；transcript 第一行的通知从 `rebuildTranscript` 中移除。
|
||||
- 仅当 `welcome` 未设置时才播放扫入动画。配置了 `welcome` 会立即渲染整个横幅，使 fixture 和快照保持帧确定性。扫入在 `ui.start()` 成功后启动，并经与之前相同的 `detachListeners` 路径通过 `stopBannerReveal` 清理；后者还会重置裁剪，使扫入中途被销毁的头部重新完整渲染。
|
||||
|
||||
本 Agent Note 统一记录几种已弃用启动方案的当前结论：带逐字打字机效果的随机标语、带边框的整幅横幅扫入动画，以及完全移除横幅。示例组装不设置 `welcome`；部署和确定性 fixture 仍可提供该值。无横幅方案为模型设置的常驻页脚位置继续保留。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**保留盒子但做细或改用更轻的字符。** 否决：指令是 "just remove the border"；任何环绕的字符都是用户所反对的边框装饰。
|
||||
|
||||
**在未设置 `welcome` 时保留随机或固定标语。** 否决：反复出现的氛围文案很快失去信息价值，而逐字揭示仅为一行制作动画，速度又慢。因此，未设置 `welcome` 时不显示副标题，由整个横幅提供启动动效。
|
||||
|
||||
**完全移除横幅。** 否决：常驻页脚很适合显示模型，却无法承载完整识别详情；把 `welcome` 放入 transcript 还会使展示配置表现成对话内容。
|
||||
|
||||
**自上而下揭示横幅。** 否决：按四行分成四步看起来像闪烁。横向宽度裁剪利用终端横向空间实现平滑动效，并复用 ANSI 感知的截断路径。
|
||||
|
||||
**既然横幅重新显示模型，就把模型从页脚移除。** 否决：横幅是短暂的，会随 transcript 滚走，而页脚在整个会话中保持模型可见；这个常驻位置被刻意保留。
|
||||
|
||||
**将会话 id 留在横幅之外。** 否决：盒子去掉后详情行只占一行，且用户要求横幅"和以前一样"，而以前它承载 `model • session-id`。
|
||||
|
||||
## Consequences
|
||||
|
||||
- `welcome` 未设置时的启动输出再次依赖动画（扫入）；配置了欢迎语则保持帧确定性，因此每个快照和脚本 fixture 都保留一个固定副标题。
|
||||
- demo 不再提供教学性质的欢迎填充文案；`welcome` 未设置就表示横幅没有副标题，而该配置仍是部署和 fixture 获得确定性输出的配置手段。
|
||||
- 模型现在在启动时出现两次——横幅详情与页脚——这是有意的冗余：横幅短暂，页脚常驻。
|
||||
- `/clear` 清空 transcript 但不清头部，因此横幅及其配置的副标题在 `/clear` 后存活，不同于基于 transcript 的欢迎行。
|
||||
- 全部 pi-tui 终端快照与 examples/tui-agent 回放快照重新录制（`test:snapshot:refresh`）：横幅行以无盒子字符方式回归；页脚行保留模型前缀。
|
||||
- 一切锚定横幅缺失的内容改为锚定其存在：PTY 冒烟测试以详情行的 `main-session-` id 为启动标记（它在扫入后段才被揭示），并断言 `DEEPSEEK`/`HARNESS` 出现且无盒子角。
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 固定：无边框横幅扫入至自然完成——无盒子角、标题与 `main-session` 详情出现——且至少有一帧扫入中途被裁剪；配置的 `welcome` 完整渲染横幅且无裁剪帧；未设置 `welcome` 的横幅无副标题；销毁会在扫入中途清掉扫入定时器。独立的配色方案用例覆盖终端报告的浅色/深色转换、相同方案下的空操作，以及写入 DSR 查询时抛出异常的终端；`applyColorScheme` 依靠 `setStatus` 重新推导编辑器边框，而不再重复那个导致逐文件覆盖率未达标的无效赋值。tui-agent 与 dsh CLI 的 PTY 冒烟测试以 `main-session-` 详情标记为启动标记并断言无盒子角。快照验证完整帧。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-footer-cache-hit-rate.md: 9e6ec734030088f063c049312ea345dc07303554
|
||||
2026-07-21-tui-footer-cache-hit-rate.zh.md: ec761df2cb9cad1dd922082f4ff1a8bb25cbdd69
|
||||
@@ -0,0 +1,42 @@
|
||||
# Agent Note: TUI footer shows the session cache hit rate
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-footer-cache-hit-rate.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The footer summed the session's token usage as `↑<input> ↓<output>`, where `↑` is the uncached input reported by the model. `TokenUsage` counts are disjoint: billed prompt tokens are `inputTokens` (uncached) plus `cacheReadTokens` and `cacheWriteTokens`. With only the uncached number visible, a user could not tell how much of each turn's prompt the provider cache served — the signal that most directly reflects whether the reused request prefix is paying off. On a long session dominated by cache reads the `↑` figure stays small and hides that the prompt is large but cheap.
|
||||
|
||||
## Decision
|
||||
|
||||
The footer appends `cache <rate>%` after `↑<input> ↓<output>`, where the rate is the share of billed prompt tokens served from the provider cache.
|
||||
|
||||
- `TokenTotals` accumulates the four disjoint buckets (`input`, `output`, `cacheRead`, `cacheWrite`). `addUsage` folds one call's `TokenUsage` into the totals, treating a missing `cacheReadTokens`/`cacheWriteTokens` as zero.
|
||||
- `cacheHitRate(totals)` is `round(cacheRead / (input + cacheRead + cacheWrite) * 100)`, and `undefined` before any input is billed. `FooterComponent` omits the whole ` cache N%` segment while the rate is `undefined`, so an empty session shows no meaningless zero.
|
||||
- `↑` keeps meaning uncached input, not billed input: the disjoint-bucket convention holds across the footer, and the cache percent supplies the reuse signal the raw counts cannot.
|
||||
- Totals are rebuilt on mount by `sessionTokens`, which sums usage over `assistant/message` events (never `assistant/chunk`, to avoid double counting), and updated live from each `assistant/message` event that carries usage.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Show billed input (`input + cacheRead + cacheWrite`) as `↑` instead of a separate percent.** Rejected: it would redefine `↑` away from the disjoint `inputTokens` bucket the rest of the harness reports, and it would still hide the reuse share the user actually wants; a derived percent adds the signal without overloading the count.
|
||||
|
||||
**Compute the rate against all tokens (`input + output + cache`).** Rejected: output tokens are never cache-served, so folding them into the denominator understates the rate for no meaning; cache hit rate is a property of the prompt.
|
||||
|
||||
**Drop `cacheWrite` from the denominator.** Rejected: cache writes are billed input the provider spent to populate the cache, so excluding them overstates the hit rate on a writing turn. DeepSeek reports no cache-write metric today, but the formula stays general and the write path is covered.
|
||||
|
||||
**Render `cache 0%` on an empty session.** Rejected: the billed input is `0`, the ratio is `0/0`, and a `0%` badge on a fresh session is a lie about a value that does not exist yet; the segment stays hidden until input is billed.
|
||||
|
||||
**Give the metric its own right-aligned footer element beside `tools:`.** Rejected: it derives from the adjacent token counts and reads best in the `input → output → cache` order; grouping it left also keeps the lower-priority `tools:` indicator as the element that clips first under width pressure, matching the footer's existing layout priority.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The left group grew by ` cache N%`, so on a narrow footer the right-side `tools:` state clips sooner. This follows the footer's pre-existing left-priority truncation and is an accepted trade-off.
|
||||
- The metric is best-effort live UI state derived from `assistant/message` usage: rebuilt from the session on mount, updated live, and never persisted.
|
||||
- `packages/ui/tui/src/index.ts` stays at 100 % per-file coverage.
|
||||
- The `examples/tui-agent` terminal snapshots carry the segment: a turn with cache reads renders e.g. `cache 49%`, and a first cold turn renders `cache 0%`.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` drives the footer through the real `createTuiChat`: an empty session renders `↑0 ↓0` with no cache segment (the hidden path), a cold turn (`inputTokens` only) renders `cache 0%`, and a live warm turn carrying `cacheReadTokens` and `cacheWriteTokens` updates it to `cache 60%` while no longer showing `cache 0%`. The `examples/tui-agent` snapshot suite replays green against the recorded expected output.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Agent Note: TUI 页脚展示会话缓存命中率
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-footer-cache-hit-rate.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
页脚原本把会话的 token 用量汇总为 `↑<input> ↓<output>`，其中 `↑` 是模型上报的未缓存输入。`TokenUsage` 的各项计数互不重叠：计费的输入 token 由 `inputTokens`（未缓存）加上 `cacheReadTokens` 与 `cacheWriteTokens` 构成。只暴露未缓存的那个数字，用户就无从判断每轮提示词有多少由提供方缓存承接——而这恰是最能反映复用的请求前缀是否奏效的信号。在以缓存读取为主的长会话里，`↑` 始终很小，掩盖了提示词其实很大但很便宜的事实。
|
||||
|
||||
## Decision
|
||||
|
||||
页脚在 `↑<input> ↓<output>` 之后追加 `cache <rate>%`，该比率是计费输入 token 中由提供方缓存承接的占比。
|
||||
|
||||
- `TokenTotals` 累加四个互不重叠的桶（`input`、`output`、`cacheRead`、`cacheWrite`）。`addUsage` 把单次调用的 `TokenUsage` 折入总量，缺失的 `cacheReadTokens`/`cacheWriteTokens` 视为零。
|
||||
- `cacheHitRate(totals)` 为 `round(cacheRead / (input + cacheRead + cacheWrite) * 100)`，在尚无输入计费前返回 `undefined`。比率为 `undefined` 时 `FooterComponent` 整段略去 ` cache N%`，因此空会话不会显示无意义的零。
|
||||
- `↑` 仍表示未缓存输入，而非计费输入：页脚全程遵守互不重叠的桶约定，缺失的复用信号由缓存百分比补足。
|
||||
- 挂载时由 `sessionTokens` 重建总量，它对带 usage 的 `assistant/message` 事件求和（绝不用 `assistant/chunk`，以免重复计数）；此后每条携带 usage 的 `assistant/message` 事件都会实时更新。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**把计费输入（`input + cacheRead + cacheWrite`）作为 `↑`，不单列百分比。** 否决：这会让 `↑` 偏离 harness 其余部分上报的互不重叠 `inputTokens` 桶，且仍旧藏住用户真正想要的复用占比；派生一个百分比既补上信号，又不给计数加载额外含义。
|
||||
|
||||
**用全部 token（`input + output + cache`）作分母计算比率。** 否决：输出 token 从不由缓存承接，把它折进分母只会无意义地拉低比率；缓存命中率是提示词的属性。
|
||||
|
||||
**从分母里去掉 `cacheWrite`。** 否决：缓存写入是提供方为填充缓存而付费的计费输入，剔除它会在写入的那一轮高估命中率。DeepSeek 目前不上报缓存写入指标，但公式保持通用，写入路径也有覆盖。
|
||||
|
||||
**在空会话上渲染 `cache 0%`。** 否决：此时计费输入为 `0`，比值是 `0/0`，在全新会话上打出 `0%` 是对一个尚不存在的值撒谎；在输入计费之前该段一直隐藏。
|
||||
|
||||
**给该指标单独一个右对齐的页脚元素，紧挨 `tools:`。** 否决：它派生自相邻的 token 计数，按 `input → output → cache` 的顺序阅读最顺；左置分组还让优先级更低的 `tools:` 指示成为宽度紧张时最先被裁剪的元素，与页脚既有的布局优先级一致。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 左段增加了 ` cache N%`，因此窄终端上右侧的 `tools:` 状态更早被裁剪。这沿用页脚既有的左段优先裁剪策略，是可接受的取舍。
|
||||
- 该指标是从 `assistant/message` 的 usage 派生的尽力而为实时 UI 状态：挂载时从会话重建、随后实时更新、从不持久化。
|
||||
- `packages/ui/tui/src/index.ts` 保持 100% 单文件覆盖率。
|
||||
- `examples/tui-agent` 终端快照带有该段：有缓存读取的一轮渲染为如 `cache 49%`，首个冷启动轮次渲染为 `cache 0%`。
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 通过真实的 `createTuiChat` 驱动页脚：空会话渲染 `↑0 ↓0` 且无缓存段（隐藏路径），冷启动一轮（仅 `inputTokens`）渲染 `cache 0%`，随后实时的热轮次携带 `cacheReadTokens` 与 `cacheWriteTokens`，把它更新为 `cache 60%` 且不再显示 `cache 0%`。`examples/tui-agent` 快照套件对已录制的预期输出回放通过。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-no-banner.md: bfe78b2ba958193cc7bfe483b17faf5ae27eb4bb
|
||||
2026-07-21-tui-no-banner.zh.md: c92ad46d4176ec0444e5db766350c4e74c137645
|
||||
40
.agents/notes/archived/feature/2026-07-21-tui-no-banner.md
Normal file
40
.agents/notes/archived/feature/2026-07-21-tui-no-banner.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Agent Note: No startup banner
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-no-banner.zh.md)
|
||||
|
||||
> **Superseded** by the [borderless-banner Agent Note](2026-07-21-tui-borderless-banner.md): the banner and its sweep return without the box. The model's footer home this note added stays.
|
||||
|
||||
## Problem
|
||||
|
||||
The TUI opened with a boxed product banner ("DEEPSEEK HARNESS" + model/session detail), most recently with a sweep-in animation ([banner sweep Agent Note](2026-07-21-tui-banner-sweep.md)). The user's verdict: remove it. A product title re-read on every boot is chrome, the box spends four rows before any content, and the identifying facts it carried (model, session) have better homes.
|
||||
|
||||
## Decision
|
||||
|
||||
- `HeaderComponent`, the sweep animation, and its lifecycle wiring are deleted. The TUI mounts straight into the transcript; startup renders nothing above the separator.
|
||||
- The model name moves into the footer status line's left segment (`<model> <cwd> ↑tokens ↓tokens`), so the session's driving model stays visible at all times, not just at boot. The session id is no longer displayed — it lives in the session log and `./.sessions` filenames, where `dsh --resume <id>` and the `/resume` selector retrieve it.
|
||||
- `welcome`, when configured, renders as the transcript's first line (a muted notice) inside `rebuildTranscript`, so palette swaps preserve it. Unset renders nothing. Fixtures keep their configured welcomes; the PTY smoke's boot marker becomes the footer's model name, the only mounted-TUI text guaranteed to render regardless of cwd length.
|
||||
|
||||
This supersedes the [banner sweep Agent Note](2026-07-21-tui-banner-sweep.md) entirely: both the sweep and the banner it animated are gone.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep a one-line header (no box).** Rejected: the only load-bearing fact was the model name, and the footer already aggregates session status; a dedicated header row for one fact is the same chrome, smaller.
|
||||
|
||||
**Show the session id in the footer too.** Rejected: a 36-char UUID dominates the 100-column footer and clips the status segment; it identifies the session for resume, which is a log/filesystem concern, not a glanceable one.
|
||||
|
||||
**Print the welcome outside the transcript (above the separator).** Rejected: any fixed region above the transcript is a banner again; as a transcript line it scrolls away naturally and survives rebuilds through the same path as every other transcript element.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Startup output is fully deterministic again — no animation frames at all; the interval-lifecycle machinery from the two animation iterations is gone.
|
||||
- All 26 pi-tui terminal snapshots re-recorded (`test:snapshot:refresh`): banner rows gone, footer rows gain the model prefix.
|
||||
- Anything that anchored on banner text (`DEEPSEEK`, box corners) re-anchors on the footer model name; `main-session-` no longer appears in boot output.
|
||||
- `/clear` now wipes the welcome line too: it is an ordinary transcript line, and `/clear` empties the transcript (the old banner survived `/clear` only by sitting outside it).
|
||||
- The footer's left segment is wider; on narrow terminals the right status segment clips earlier.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` pins: no box corners/product title and an empty transcript when `welcome` is unset, with the model in the footer; a configured welcome as the first transcript line without a banner; and the welcome surviving a palette-swap transcript rebuild. The PTY smoke boots on the footer model name and asserts `DEEPSEEK HARNESS` is absent. Snapshots verify the full frames.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: 移除启动横幅
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-no-banner.md) | 中文
|
||||
|
||||
> **已被取代**，见[无边框横幅 Agent Note](2026-07-21-tui-borderless-banner.md)：横幅及其扫入动画回归，只是去掉了盒子。本 note 为模型设立的页脚归宿得以保留。
|
||||
|
||||
## Problem
|
||||
|
||||
TUI 启动时展示一个带框的产品横幅（"DEEPSEEK HARNESS" + 模型/会话详情），最近一版还带扫入动画（[横幅扫入 Agent Note](2026-07-21-tui-banner-sweep.md)）。用户的裁决：删掉它。每次启动都被重读的产品标题是装饰，盒子在任何内容之前先占掉四行，而它承载的识别信息（模型、会话）有更好的去处。
|
||||
|
||||
## Decision
|
||||
|
||||
- 删除 `HeaderComponent`、扫入动画及其生命周期接线。TUI 直接挂载进 transcript；启动时分隔线之上不渲染任何东西。
|
||||
- 模型名移入页脚状态行的左段（`<model> <cwd> ↑tokens ↓tokens`），会话使用的模型因此始终可见，而不只是启动时。会话 id 不再显示——它存在于会话日志和 `./.sessions` 文件名中，`dsh --resume <id>` 和 `/resume` 选择器会从中获取该 id。
|
||||
- 配置了 `welcome` 时，它作为 transcript 的第一行（一条弱化的通知）在 `rebuildTranscript` 内渲染，因此调色板切换会保留它。未设置则什么也不渲染。fixture 保留各自配置的欢迎语；PTY 冒烟测试的启动标记改为页脚的模型名——无论 cwd 多长都保证渲染的唯一挂载后文本。
|
||||
|
||||
本 note 完全取代[横幅扫入 Agent Note](2026-07-21-tui-banner-sweep.md)：扫入动画和它所动画的横幅都已移除。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**保留单行头部（去掉盒子）。** 否决：唯一有承载价值的信息是模型名，而页脚已经聚合会话状态；为一条信息保留专用头部行仍是同一种装饰，只是小一点。
|
||||
|
||||
**把会话 id 也放进页脚。** 否决：36 字符的 UUID 会占满 100 列页脚并裁掉状态段；它的用途是恢复会话的标识，属于日志/文件系统关注点，不是需要一瞥可见的信息。
|
||||
|
||||
**把欢迎语渲染在 transcript 之外（分隔线上方）。** 否决：transcript 上方任何固定区域都会再次变成横幅；作为 transcript 行它自然滚走，并通过与其他 transcript 元素相同的路径在重建后保留。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 启动输出再次完全确定——没有任何动画帧；两轮动画迭代留下的定时器生命周期机制全部移除。
|
||||
- 全部 26 个 pi-tui 终端快照重新录制（`test:snapshot:refresh`）：横幅行消失，页脚行增加模型前缀。
|
||||
- 锚定横幅文本（`DEEPSEEK`、盒子角）的内容改为锚定页脚模型名；启动输出中不再出现 `main-session-`。
|
||||
- `/clear` 现在也会清掉欢迎行：它是普通的 transcript 行，而 `/clear` 清空 transcript（旧横幅能在 `/clear` 后存活只因为它在 transcript 之外）。
|
||||
- 页脚左段变宽；窄终端上右侧状态段更早被裁剪。
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 固定：`welcome` 未设置时无盒子角/产品标题、transcript 为空、模型在页脚；配置的欢迎语作为 transcript 第一行且无横幅；欢迎语在调色板切换的 transcript 重建后保留。PTY 冒烟测试以页脚模型名为启动标记并断言 `DEEPSEEK HARNESS` 不出现。快照验证完整帧。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-reload-command.md: e491e8f4510128b7fda03d41bc1d13e4dfdc9f5e
|
||||
2026-07-21-tui-reload-command.zh.md: ed96c689fe4ba700f5b6836d7b7727e0252737a2
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: The /reload command re-reads loader configs on demand
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-reload-command.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
HMR's file watcher only reacts to in-place `change` events under its configured roots (the config leaf's directory in the shipped demos). Editors that replace files by rename (BSD `sed -i`, `git checkout`) produce no event, and runtimes without the HMR entry have no config reload path at all. During development that means restarting the TUI to apply a config edit the watcher missed. Widening the watch roots to the whole repo was considered and rejected in discussion: dense package sharing makes module-level HMR a remount-most-of-the-tree operation with unpredictable externals boundaries.
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh-tui` gains an **experimental, dev-only** `/reload` slash command: it walks `ctx.loader.entries()` and calls `refresh()` on every file-backed subtree (`Include`), i.e. the exact code path the HMR watcher's config-change branch drives, invoked manually and watcher-independent. Unchanged files are no-ops (content comparison in `Include.read`); invalid files warn and keep the running tree (the hot-reload-resilience contract); include `patches` — including the dsh CLI's personal overlay — re-apply on every re-read.
|
||||
|
||||
The TUI reaches the Loader **structurally** (`ctx.loader` via a local type, not `inject`): tests and embedders run the TUI without a Loader, where `/reload` degrades to a warning notice instead of failing the mount. Module-source hot reload stays watcher-owned; `/reload` refreshes configs only.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Widening the HMR watch roots to `packages/`/`apps/`.** Rejected for now: plugin-source changes reload every dependent plugin's fiber, and the repo's dense shared packages (`dsh-session`, `dsh-llm`, `dsh-tools`) make that a teardown of the spine and the UI mid-session — a restart in disguise with partial-reload hazards. A manual config-scope command captures the safe, predictable subset.
|
||||
|
||||
**Declaring `loader` in `inject`.** Rejected: it would make the Loader a hard dependency of the TUI, breaking every Loader-less composition (unit harness, embedders) for a dev convenience.
|
||||
|
||||
**A `cordis_reload` model-facing tool in dsh-tool-cordis.** Rejected: this is an operator action for the human at the terminal, not a capability the model should trigger; the cordis toolset's mount/unmount surface already covers the model's runtime-modification story.
|
||||
|
||||
## Consequences
|
||||
|
||||
- `/reload` appears in the help line, autocomplete (marked EXPERIMENTAL (dev)), and the two help-rendering snapshots (re-recorded).
|
||||
- The command reports tree count and completion as transcript notices; per-file failures surface only in loader logs, which the TUI does not display — acceptable for a dev-only surface, noted in the completion message.
|
||||
- A re-entrancy guard serializes reloads: `/reload` while one is in flight is refused with a warning, keeping the loader's unmutexed tree-update pass single-writer; the guard releases on completion or failure.
|
||||
- `/reload` runs only while the agent is idle: a reload can dispose and re-mount entries, which under an active turn could tear tools or the adapter out from under in-flight calls. The check is advisory (a send can race in after it) but removes the common footgun.
|
||||
- If `refresh()`'s never-reject contract ever changes, the command reports the failure instead of leaving an unhandled rejection.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` pins: `/reload` refreshes every file-backed subtree and skips plain entries (structural fake Loader), reports completion, refuses re-entry while a gated refresh is in flight and runs again after release, releases the guard on the failure arm, refuses a running agent and runs again at idle, reports a rejecting refresh, and degrades to a warning without a Loader — including mounted as a real plugin fiber, where a throwing service lookup would escape. Verified live in tmux against the real tree: probe edit → reload applies; invalid edit → reload keeps the running tree.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: /reload 命令按需重读 loader 配置
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-reload-command.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
HMR 的文件监听器只对其配置根目录（示例中即配置叶子所在目录）下的就地 `change` 事件起反应。以重命名方式替换文件的编辑器（BSD `sed -i`、`git checkout`）不产生事件，而没有挂载 HMR 配置项的运行时则完全没有配置重载路径。开发时这意味着监听器漏掉一次配置编辑就得重启 TUI。曾考虑把监听根目录扩大到整个仓库，讨论后否决：包之间的密集共享使模块级 HMR 变成「重挂大半棵树」的操作，externals 边界也不可预测。
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh-tui` 增加一个**实验性、仅供开发**的 `/reload` 斜杠命令：遍历 `ctx.loader.entries()`，对每个文件后端的子树（`Include`）调用 `refresh()`——即 HMR 监听器配置变更分支所走的同一条代码路径，改为手动触发、不依赖监听器。未变化的文件是无操作（`Include.read` 做内容比较）；无效文件记录警告并保留运行中的树（热重载韧性契约）；include 的 `patches`——包括 dsh CLI 的个人 overlay——在每次重读时重新应用。
|
||||
|
||||
TUI 以**结构方式**访问 Loader（通过局部类型访问 `ctx.loader`，而非 `inject`）：测试和嵌入方在没有 Loader 的情况下运行 TUI，此时 `/reload` 退化为一条警告通知而不是挂载失败。模块源码热重载仍由监听器负责；`/reload` 只刷新配置。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**把 HMR 监听根目录扩大到 `packages/`/`apps/`。** 暂缓否决：插件源码变更会重载每个依赖插件的 fiber，而仓库中密集共享的包（`dsh-session`、`dsh-llm`、`dsh-tools`）使其等同于会话中途拆掉主干和 UI——伪装成热重载的重启，还带部分重载的隐患。手动的、只覆盖配置范围的命令抓住了安全、可预测的那个子集。
|
||||
|
||||
**在 `inject` 中声明 `loader`。** 否决：那会让 Loader 成为 TUI 的硬依赖，为了一个开发便利破坏所有无 Loader 的组合（单元测试 harness、嵌入方）。
|
||||
|
||||
**在 dsh-tool-cordis 里做一个面向模型的 `cordis_reload` 工具。** 否决：这是终端前人类操作者的动作，不是模型应当触发的能力；cordis 工具集的 mount/unmount 表面已经覆盖模型的运行时修改需求。
|
||||
|
||||
## Consequences
|
||||
|
||||
- `/reload` 出现在帮助行、自动补全（标注 EXPERIMENTAL (dev)）和两个渲染帮助的快照中（已重新录制）。
|
||||
- 命令以 transcript 通知报告树数量与完成；单文件失败只出现在 loader 日志里，TUI 不显示——对仅供开发的表面可以接受，完成消息中已注明。
|
||||
- 重入保护串行化重载：前一次进行中时 `/reload` 会被拒绝并提示警告，使 loader 无互斥的树更新过程保持单写者；保护在完成或失败时释放。
|
||||
- `/reload` 只在 agent 空闲时运行：重载可能卸载并重新挂载配置项，在活跃轮次下这会把工具或适配器从进行中的调用脚下抽掉。检查是建议性的（检查后仍可能有 send 竞争进来），但消除了常见的坑。
|
||||
- 若 `refresh()` 的永不 reject 契约将来改变，命令会报告失败而不是留下未处理的 rejection。
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 固定：`/reload` 刷新每个文件后端子树并跳过普通配置项（结构化的假 Loader）、报告完成、在门控的刷新进行中拒绝重入并在释放后可再次运行、失败分支同样释放保护、拒绝运行中的 agent 并在空闲后可再次运行、报告 reject 的 refresh、无 Loader 时退化为警告——包括作为真实插件 fiber 挂载的情形，在那里会抛出的服务查找会泄露出去。已在 tmux 中对真实配置树实机验证：探针编辑 → reload 生效；无效编辑 → reload 保留运行中的树。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-steering-queue-badge.md: 37e8a11c0dd30a0674107ff33d51a31d92385ada
|
||||
2026-07-21-tui-steering-queue-badge.zh.md: 6ef412b26a32c3aa359215404ca81635fca776c1
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: TUI status line badges queued steering messages
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-steering-queue-badge.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
While a turn runs, an editor submission calls `agent.steer()` and joins the steering queue behind the running turn ([front-door Agent Note](2026-07-17-dedicated-full-screen-tui-front-door.md)). The running status line ended only with the `Enter sends steering, Esc cancels` hint, so pressing Enter gave no feedback that the message landed or how many were waiting to reach the model. A user steering several times could not tell the queue from a dropped keystroke.
|
||||
|
||||
## Decision
|
||||
|
||||
The agent's inbox is the authoritative steering queue but is not observable from the TUI, so the badge is a live count reconstructed from successful TUI steering submissions and `steering/message` events rather than a projection of the queue itself.
|
||||
|
||||
- The running status line composes through `formatTurnStatus`, which inserts a `${queued} queued · ` badge before the `Enter sends steering, Esc cancels` hint when `queued > 0` and shows the plain hint at zero; the phase label and elapsed timing before it are the [verbose status line](2026-07-21-tui-verbose-status-line.md)'s.
|
||||
- `createTuiChat` records each successful running-state `agent.steer()` submission, removes its matching source on each `steering/message` session event as the loop drains one, and resets the list whenever the agent leaves `running`.
|
||||
- The count refreshes onto the live `Loader` through `setMessage`; the refresh is a no-op while idle because the loader exists only during a running turn.
|
||||
- The reset lives in the `agent/status` transition, not in `setStatus`, because `setStatus` also runs on mid-turn palette changes and must not clear a live count.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Derive the count from the session log alone** (enqueued minus drained, recomputed on replay). Rejected: a cancellation clears the inbox without logging a drain, so the log cannot distinguish a drained message from a discarded one; the reset-on-non-running anchor is simpler and self-correcting each turn.
|
||||
|
||||
**Reset inside `setStatus`.** Rejected: `setStatus` re-runs on `applyColorScheme` mid-turn, which would wrongly zero a live count; the status transition is the only place a turn actually ends.
|
||||
|
||||
**Count every public inbox enqueue.** Rejected: `AgentMessage` intentionally omits driver routing state, so an observer cannot distinguish queued turns from steering. The TUI instead owns the submissions represented by its badge.
|
||||
|
||||
**Make the wording or a threshold configurable.** Rejected: the no-hardcoded-tunables rule targets deployment-varying behavior, not brand copy; the `welcome`/hint strings are already fixed presentation.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The badge is best-effort live UI state, not a logged surface: it is rebuilt from events and reset each turn, never persisted, so a resumed running turn starts its badge from zero.
|
||||
- A cancellation mid-queue clears the badge cleanly through the non-running reset, and a drain past zero is a no-op — neither can strand a stale count.
|
||||
- Steering submitted outside this TUI is absent from the badge; the count describes feedback for this editor's submissions rather than the agent's complete inbox.
|
||||
- `packages/ui/tui/src/index.ts` stays at 100 % per-file coverage.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` drives the running status frame through the real `createTuiChat`: the plain hint at zero, the increment to `2 queued` after editor submissions, the decrement as each message drains, an unrelated drain ignored, and the reset when the turn ends.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Agent Note: TUI 状态行标示排队中的 steering 消息
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-steering-queue-badge.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
轮次运行期间，编辑器提交会调用 `agent.steer()`，在运行中的轮次后面加入 steering（中途引导）队列（[前门 Agent Note](2026-07-17-dedicated-full-screen-tui-front-door.md)）。运行时的状态行只以 `Enter sends steering, Esc cancels` 提示收尾，因此按下 Enter 后没有任何反馈表明消息已入队、也看不出有多少条正在等待送达模型。连续 steering 多次的用户无法把队列和被吞掉的按键区分开。
|
||||
|
||||
## Decision
|
||||
|
||||
agent（智能体）的收件箱（inbox）才是权威的 steering 队列，但 TUI 无法观测它，因此徽标是根据 TUI 成功提交的 steering 和 `steering/message` 事件重建出的实时计数，而非对队列本身的投影。
|
||||
|
||||
- 运行时的状态行经 `formatTurnStatus` 组装：`queued > 0` 时在 `Enter sends steering, Esc cancels` 提示前插入 `${queued} queued · ` 徽标，为零时是纯提示文本；其前的阶段标签与耗时归[详细状态行](2026-07-21-tui-verbose-status-line.md)所有。
|
||||
- `createTuiChat` 记录每一次在 `running` 状态下成功的 `agent.steer()` 提交；agent loop（智能体循环）每排空一条并发出 `steering/message` 会话事件时，就按来源移除匹配项；agent 离开 `running` 时则重置整个列表。
|
||||
- 计数通过 `setMessage` 刷新到实时的 `Loader` 上；空闲时刷新是空操作，因为 loader 只在运行中的轮次期间存在。
|
||||
- 重置放在 `agent/status` 状态切换里，而非 `setStatus` 中，因为 `setStatus` 在轮次中途的颜色方案变化时也会运行，绝不能清掉一个实时计数。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**仅从会话日志推导计数**（入队数减去排空数，回放时重算）。否决：取消会清空 inbox 而不记录排空，因此日志无法区分一条消息是被排空还是被丢弃；「离开运行态即重置」这个锚点更简单，且每轮自我校正。
|
||||
|
||||
**在 `setStatus` 内重置。** 否决：`setStatus` 会在轮次中途的 `applyColorScheme` 时重新运行，会错误地把实时计数清零；状态切换才是轮次真正结束的唯一位置。
|
||||
|
||||
**统计每一次公开的 inbox 入队。** 否决：`AgentMessage` 刻意省略驱动器路由状态，因此观察方无法区分排队轮次与 steering。TUI 转而自行维护徽标所代表的那些提交。
|
||||
|
||||
**把措辞或某个阈值做成配置。** 否决：「插件里不许硬编码可调参数」规则针对的是随部署变化的行为，不是品牌文案；`welcome`/提示字符串本就是固定的展示文案。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 徽标是尽力而为的实时 UI 状态，不写入日志：它由事件重建、每轮重置、从不持久化，因此恢复（resume）出的运行中轮次徽标从零开始。
|
||||
- 队列中途取消会经由「离开运行态即重置」干净地清掉徽标，排空到零以下则是空操作——两者都不会残留一个陈旧计数。
|
||||
- 通过此 TUI 以外的入口提交的 steering 不会出现在徽标中；该计数反馈的是此编辑器的提交，而不是 agent 的完整 inbox。
|
||||
- `packages/ui/tui/src/index.ts` 保持 100% 的单文件覆盖率。
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 通过真实的 `createTuiChat` 驱动运行时状态帧：为零时显示纯提示，编辑器提交后递增到 `2 queued`，每条消息排空时递减，忽略无关的排空，并在轮次结束时重置。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-21-tui-verbose-status-line.md: 9ed396b0dbf4325d6fdd2a4f20f8d81b5b408171
|
||||
2026-07-21-tui-verbose-status-line.zh.md: 14c9b36646e226715156ba8db8f62cd6090ce9a0
|
||||
@@ -0,0 +1,37 @@
|
||||
# Agent Note: The running status line shows the turn phase and elapsed time
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-21-tui-verbose-status-line.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
While a turn ran, the [full-screen TUI](2026-07-17-dedicated-full-screen-tui-front-door.md) showed a single static "Working" spinner. It conveyed neither how long the current step had taken nor what the agent was doing — waiting on the model, thinking, streaming a response, or running tools — so a slow or stalled turn was indistinguishable from a fast one.
|
||||
|
||||
## Decision
|
||||
|
||||
- While a turn runs, the status line above the editor shows a derived phase label with elapsed time, keeping the trailing `— Enter sends steering, Esc cancels` hint. The four phases and their labels are `waiting` → "Waiting for the first token", `thinking` → "Thinking", `responding` → "Responding", and `executing` → "Executing tools".
|
||||
- The phase is presentation state the TUI derives from live session events, not a session event or agent status of its own. `step/start` enters `waiting`; an `assistant/chunk` reasoning delta or reasoning block-start enters `thinking`; a text delta or text block-start enters `responding`; a `tool/call` enters `executing`. The event map is merge-extensible, so every other event kind falls through a default and leaves the phase unchanged.
|
||||
- The label reports two clocks — `<phase> <phase-elapsed> · total <step-elapsed>` — except `waiting`, which shows only the step total. The phase clock resets on a genuine phase change or a new step; the step clock resets on `step/start`. Durations format as `8s` below a minute and `1m05s` at or above one. Tool time between `step/end` and the next `step/start` accrues to the finishing step's total.
|
||||
- A single `RunningStatus` controller — the loader, the phase, the two baselines, and a refresh timer — exists only while a turn runs. A one-second `setInterval` refreshes the elapsed time; a phase event refreshes it immediately. `clearStatus` clears the interval, stops the loader, and drops the controller, so any transition to idle or disposed leaves no live timer, matching the [borderless banner](2026-07-21-tui-borderless-banner.md)'s timer hygiene. A mid-turn palette rebuild (`setStatus` re-derives the editor border on a terminal color-scheme change) carries the phase and both baselines across, so a running status never snaps back to `waiting`.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Emit the phase as a session event or agent status.** Rejected: the phase is a presentation detail the TUI reconstructs from events already logged. A durable, model-visible phase would demand a new session event under the model-visible ⟺ logged rule, for no model benefit.
|
||||
|
||||
**Reuse pi-tui's `Loader` animation timer to refresh the elapsed text.** Not available: the vendored `Loader` animates only its spinner glyph, and its dist is not ours to change. The TUI owns a separate one-second interval, cleared on teardown.
|
||||
|
||||
**Infer the phase from tool-drain or streaming-component state.** Rejected: the `step/start`, `assistant/chunk`, and `tool/call` lifecycle events are cleaner signals, already handled in the same live listener, and avoid coupling the status line to other components.
|
||||
|
||||
**Show only elapsed time, or only the phase.** Rejected: both are wanted — the per-phase time answers what the agent is doing, the per-step total answers how long the step has taken.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The status line reads, for example, `Thinking 4s · total 8s — Enter sends steering, Esc cancels`, so the agent's current activity and step duration are legible and a stall is visible.
|
||||
- Phase detection is best-effort presentation: an unhandled future chunk or event kind leaves the last phase in place and never throws.
|
||||
- Exactly one `setInterval` runs per active turn, cleared with the controller on every idle or disposed transition and on shutdown.
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` pins each phase label against its triggering event (`step/start`, reasoning and text deltas and block-starts, `tool/call`), that a new step reopens the wait window, that the elapsed time advances on the controller's own timer past one second, that a step beyond a minute renders `1m…`, that a mid-turn color-scheme change preserves the phase and elapsed time, and that a live event arriving before the turn runs moves no status. Verified live in tmux.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Agent Note: 运行状态行展示轮次阶段与已用时长
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-21-tui-verbose-status-line.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
在轮次运行期间，[全屏 TUI](2026-07-17-dedicated-full-screen-tui-front-door.md) 只显示一个静态的 "Working" loader 动画。它既不表明当前步骤已耗时多久，也不表明 agent（智能体）正在做什么——等待模型、思考、流式输出回复，还是运行工具——因此运行缓慢或卡住的轮次与运行很快的轮次无从区分。
|
||||
|
||||
## 决策
|
||||
|
||||
- 轮次运行期间，编辑器上方的状态行显示一个派生的阶段标签及已用时长，并保留末尾的 `— Enter sends steering, Esc cancels` 提示。四个阶段及其标签为 `waiting` → "Waiting for the first token"、`thinking` → "Thinking"、`responding` → "Responding"、`executing` → "Executing tools"。
|
||||
- 阶段是 TUI 从实时会话事件派生出的呈现状态，而非它自有的会话事件或 agent 状态。`step/start` 进入 `waiting`；`assistant/chunk` 的 reasoning 分片或 reasoning 块开始（`block-start`）进入 `thinking`；text 分片或 text 块开始进入 `responding`；`tool/call` 进入 `executing`。该事件映射可合并扩展，因此其余任何事件类型都落入默认分支，保持阶段不变。
|
||||
- 标签汇报两个时钟——`<phase> <phase-elapsed> · total <step-elapsed>`——但 `waiting` 只显示步骤总时长。阶段时钟在真正发生阶段切换或进入新步骤时重置；步骤时钟在 `step/start` 时重置。时长在不足一分钟时格式化为 `8s`，达到或超过一分钟时格式化为 `1m05s`。`step/end` 与下一个 `step/start` 之间的工具时间计入结束步骤的总时长。
|
||||
- 单一的 `RunningStatus` 控制器——loader、阶段、两个基准时刻以及一个刷新定时器——仅在轮次运行期间存在。一个每秒触发的 `setInterval` 刷新已用时长；阶段事件则立即刷新。`clearStatus` 清除该 interval、停止 loader 并丢弃控制器，因此任何向 idle 或 disposed 的转变都不会遗留活动定时器，与[无边框横幅](2026-07-21-tui-borderless-banner.md)的定时器清理保持一致。轮次进行中的调色板重建（终端颜色方案变化时 `setStatus` 会重新派生编辑器边框）会将阶段与两个基准时刻一并沿用过来，因此运行中的状态绝不会退回 `waiting`。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**将阶段作为会话事件或 agent 状态发出。** 已否决：阶段是 TUI 从已记录事件重建出的呈现细节。一个持久、模型可见的阶段会依据 model-visible ⟺ logged 规则要求新增一个会话事件，而对模型没有任何好处。
|
||||
|
||||
**复用 pi-tui 的 `Loader` 动画定时器来刷新已用时长文本。** 不可行：`Loader` 是 vendored 依赖，只驱动其加载动画字形，其 dist 不归我们改动。TUI 自持一个独立的每秒 interval，并在拆卸时清除。
|
||||
|
||||
**从工具耗尽或流式组件状态推断阶段。** 已否决：`step/start`、`assistant/chunk` 和 `tool/call` 这些生命周期事件是更干净的信号，已在同一个实时监听器中处理，且避免让状态行与其他组件耦合。
|
||||
|
||||
**只显示已用时长，或只显示阶段。** 已否决：两者都需要——按阶段的时长回答 agent 在做什么，按步骤的总时长回答该步骤已耗时多久。
|
||||
|
||||
## 后果
|
||||
|
||||
- 状态行例如显示 `Thinking 4s · total 8s — Enter sends steering, Esc cancels`，从而 agent 的当前活动与步骤时长一目了然，卡顿也随之可见。
|
||||
- 阶段检测是尽力而为的呈现：未处理的未来分片或事件类型会保持上一个阶段不变，绝不抛错。
|
||||
- 每个活动轮次恰好运行一个 `setInterval`，在每次向 idle 或 disposed 的转变以及关停时随控制器一并清除。
|
||||
|
||||
## 测试
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 针对触发事件锁定每个阶段标签（`step/start`、reasoning 与 text 的分片及块开始、`tool/call`），并锁定新步骤会重新开启等待窗口、已用时长在控制器自有定时器上超过一秒后递增、超过一分钟的步骤渲染为 `1m…`、轮次进行中的颜色方案变化会保留阶段与已用时长，以及轮次开始前到达的实时事件不移动任何状态。已在 tmux 中实机验证。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-23-trajectory-step-cell.md: 871f02d72b74bb6dbeb782fde3b639b237cf71e1
|
||||
2026-07-23-trajectory-step-cell.zh.md: 3ebb4becd569242bfdea222df6d042a4c00ad096
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: Trajectory step cell and turn list chrome
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-23-trajectory-step-cell.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The trajectory tab needs a reusable step row and turn-list chrome that can show expanded assistant blocks, own-duration times, Message token columns, and in-flight work. Without folding session event times into conversation nodes and expanding blocks into cells, the UI cannot match the product chrome.
|
||||
|
||||
## Decision
|
||||
|
||||
[`@deepseek-ai/dsh-client-ui-trajectory`](../../../../packages/client/ui-trajectory/README.md) owns the presentational trajectory list chrome:
|
||||
|
||||
- [`TrajectoryCell`](../../../../packages/client/ui-trajectory/src/client/TrajectoryCell.tsx) — 38px step row with kinds User / Message / Tool (no Think, Call, or Result rows). Reasoning blocks are skipped (no block-level clock). Each `tool-call` + paired `tool-result` folds into one Tool row (`name ·` truncated args) whose Time is `result.time − callTime` when both are known. Message rows carry Input/Output/Think token columns from `assistant.usage`. Own-duration Time uses `+Ns` / `+N.1s`, or `—` when absent. Selected state draws a 2px inset `--dsw-alias-brand-primary-new-colorprimary-new-color` ring (`selected` prop) and is not wired to chat selection.
|
||||
- [`TrajectoryTurn`](../../../../packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx) / header / group header — sticky Turn bar paints full-bleed `ghost-active-fill`; title/columns and the Message/Step body sit in a centered `max-width: 880px` lane. Cell trailing columns share the Turn header geometry (`320 = 4×71 + 3×12`); cells use pad 20/8.
|
||||
- [`deriveTrajectoryLayout`](../../../../packages/client/ui-trajectory/src/client/layout.ts) expands assistant `blocks[]` into cells, pairs tool-calls with `tool-result` by `callId` into Tool, folds `partial` and `runningCalls` (deduped), hangs usage on Message only (including the empty fallback when there is no text block), and builds group descriptions as wall-span + tool histogram (`1.5s bash×6`). `user/message` has no wire turn, so each User row is enclosed in the next assistant/steering turn, else the in-flight `partial` turn, else `lastAssistantTurn + 1` (or `1`). Context nodes emit no cell but still advance the Message duration cursor.
|
||||
|
||||
[`ConversationNode`](../../../../packages/client/runtime/src/client/sessions/conversation.ts) carries `time` from `SessionEvent.time`; `ToolResultNode.callTime` and `RunningToolCall.time` come from the paired `tool/call`. Duration rules: User `+0s`; Message = assistant.time − previous surface time (including skipped context); Tool = result.time − callTime when both known; in-flight Tool = `—`. Group header duration is earliest→latest absolute time in the group (wall span; Tool contributes start and start+duration).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep a Think cell for reasoning blocks.** Rejected: a single `assistant/message.time` cannot yield Think own-duration without chunk-level clocks; omit the row rather than show `—`.
|
||||
|
||||
**Keep separate Call and Result rows.** Rejected: Result had no own duration to show; one Tool row carries the call→result interval.
|
||||
|
||||
**Cumulative elapsed from session/turn start.** Rejected; the Time column is each row's own duration.
|
||||
|
||||
**Hang usage on the first expanded row.** Rejected; usage attaches to Message only.
|
||||
|
||||
**Show in-flight tool durations via Date.now().** Deferred; in-flight Time stays `—`.
|
||||
|
||||
## Consequences
|
||||
|
||||
The Trajectory tab can render expanded finalized and in-flight rows with own-duration times once fold emits `time`. Behavior-shaped coverage lives in `packages/client/ui-trajectory/tests/{cell,layout,views}.spec.tsx`. Chat selection deep-links and finer block-level clocks remain deferred.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: Trajectory 步骤单元格与轮次列表 chrome
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-23-trajectory-step-cell.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
trajectory 标签页需要可复用的步骤行与轮次列表 chrome，以展示展开后的 assistant 块、自身耗时、Message token 列，以及进行中的工作。若不将会话事件时间折叠进会话节点，并将块展开为单元格，UI 就无法对齐产品 chrome。
|
||||
|
||||
## Decision
|
||||
|
||||
[`@deepseek-ai/dsh-client-ui-trajectory`](../../../../packages/client/ui-trajectory/README.md) 拥有展示型 trajectory 列表 chrome：
|
||||
|
||||
- [`TrajectoryCell`](../../../../packages/client/ui-trajectory/src/client/TrajectoryCell.tsx) — 高 38px 的步骤行，类型为 User / Message / Tool（无 Think、Call、Result 行）。reasoning 块跳过（无块级时钟）。每对 `tool-call` + `tool-result` 折成一行 Tool（`name ·` 加截断参数），Time 在两端皆知时为 `result.time − callTime`。Message 行携带来自 `assistant.usage` 的 Input/Output/Think token 列。自身耗时 Time 使用 `+Ns` / `+N.1s`，缺失时为 `—`。选中态绘制 2px 内嵌的 `--dsw-alias-brand-primary-new-colorprimary-new-color` 环（`selected` prop），且未接线到 chat 选中。
|
||||
- [`TrajectoryTurn`](../../../../packages/client/ui-trajectory/src/client/TrajectoryTurn.tsx) / header / group header — 粘性 Turn 条背景通栏铺 `ghost-active-fill`；标题／列标与 Message/Step 主体落在居中的 `max-width: 880px` 内容道。单元格右侧列与 Turn 标头共用几何（`320 = 4×71 + 3×12`）；cell pad 20/8。
|
||||
- [`deriveTrajectoryLayout`](../../../../packages/client/ui-trajectory/src/client/layout.ts) 将 assistant `blocks[]` 展开为单元格，按 `callId` 将 tool-call 与 tool-result 配对为 Tool，折叠 `partial` 与 `runningCalls`（去重），仅将用量挂在 Message 上（含无 text 块时的空回退行），并以墙钟跨度 + 工具直方图构建分组描述（`1.5s bash×6`）。`user/message` 无线上 turn，故每条 User 行归入下一 assistant/steering 的 turn，否则归入进行中的 `partial` turn，否则为 `lastAssistantTurn + 1`（或 `1`）。context 节点不产出单元格，但仍推进 Message 耗时游标。
|
||||
|
||||
[`ConversationNode`](../../../../packages/client/runtime/src/client/sessions/conversation.ts) 携带来自 `SessionEvent.time` 的 `time`；`ToolResultNode.callTime` 与 `RunningToolCall.time` 来自配对的 `tool/call`。耗时规则：User 为 `+0s`；Message = assistant.time − 上一表面时间（含跳过的 context）；Tool = 在两者皆知时 result.time − callTime；进行中 Tool = `—`。分组标头耗时为组内最早→最晚绝对时间（墙钟跨度；Tool 贡献起点与起点+自身耗时）。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**为 reasoning 块保留 Think 单元格。** 否决：单条 `assistant/message.time` 无法给出 Think 自身耗时（除非上 chunk 级时钟）；与其显示 `—`，不如省略该行。
|
||||
|
||||
**保留分开的 Call 与 Result 行。** 否决：Result 没有可展示的自身耗时；一行 Tool 承载 call→result 区间。
|
||||
|
||||
**自会话／轮次起点累计耗时。** 否决；Time 列是每行自身的耗时。
|
||||
|
||||
**将用量挂在展开后的第一行。** 否决；用量仅附着于 Message。
|
||||
|
||||
**用 Date.now() 显示进行中工具的耗时。** 延后；进行中的 Time 保持为 `—`。
|
||||
|
||||
## Consequences
|
||||
|
||||
一旦 fold 发出 `time`，Trajectory 标签页即可渲染带自身耗时的已定稿与进行中展开行。行为导向的覆盖位于 `packages/client/ui-trajectory/tests/{cell,layout,views}.spec.tsx`。chat 选中深链与更细的块级时钟仍延后。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-24-new-session-clears-to-empty-state.md: c9b57fec3aa093062847aacba4d01b877edf4bd5
|
||||
2026-07-24-new-session-clears-to-empty-state.zh.md: 82a4f8b1e933d6aa3531556e8be4839b204ea562
|
||||
@@ -0,0 +1,24 @@
|
||||
# Agent Note: New Session clears onto the empty-state launch
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-24-new-session-clears-to-empty-state.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Sidebar "New Session" created and opened a blank session immediately, so the center column showed `ConversationRoot` with an empty transcript and the resident composer. The Figma NEW SESSION screen (`EmptyState` + shared `InputBar` hero) only rendered when `sessions.current` was already undefined, so the launch page was unreachable from the primary creation control.
|
||||
|
||||
## Decision
|
||||
|
||||
`SessionsService.clear()` wipes the persisted selection and `list.current`. Top-level sidebar creation entries (`onCreate()` with no cwd — New Session and New Workspace) call `clear()` so `AppFrame` renders `conversation.empty`. The empty state's first send still runs `conversation.startSession` (create → open → send) and reuses the same `InputBar` component as the resident composer (`variant="hero"`). Per-project "+" (`onCreate(cwd)`) keeps create-then-open until the empty-state picker can accept a seeded cwd.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep create-then-open for New Session and add a second empty chrome inside ConversationRoot when the transcript is empty.** Rejected: that duplicates the launch InputBar and breaks the empty→content ruling that one InputBar moves position rather than swapping components.
|
||||
|
||||
**Route New Session through a dedicated route or slot outside selection.** Rejected for this pass: `conversation.empty` already owns the launch UI; clearing `current` is the existing empty branch.
|
||||
|
||||
## Consequences
|
||||
|
||||
New Session no longer mints a host session until the first send. Reloading after clear stays on the empty state. Project-scoped "+" still creates immediately. `EmptyState` stacks the Figma hero (Input_Bottom 75:8208) as fish + title, a Menu-backed workspace chip above the card, then shared `InputBar` (`variant="hero"`, max-width 800, r20 card matching the composer — not a taller r24 hero), with a soft ellipse glow (figma 313:14109) centered behind the picker + card and width-locked to the card (`1051/776` asset ratio) so it scales with it. The chip uses the soft interactive hover fill + 12px radius from 75:8208 and opens MenuDropdown (figma 122:9481; `--dsw-specific-menu` + `--dsw-shadow-lv3`): basename rows with folder icons and a trailing check, then a separator and "New Workspace" whose submenu (figma 419:16920) offers "Use a existing folder" and "Create new". Use a existing folder opens the path Dialog (figma 451:18655 copy — "Enter an existing folder path" / Open Folder) over a full-viewport mask (`--dsw-alias-bg-mask-1` + `--dsw-mask-blur`) and sets the chip cwd. Create new opens the same Dialog chrome to name a folder under `host.describe().cwd`; success runs `sessions.createWorkspace` → host `session.create` (mkdir recursive) → `sessions.open`, so a default session lands in the new workspace. `InputBar` paints the bottom chrome (attach / Plan / Read-only / model) with local native `<select>` state only — host plan, access, and model seams remain unwired.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Agent Note: New Session clears onto the empty-state launch
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-24-new-session-clears-to-empty-state.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
侧栏「New Session」会立即创建并打开空白会话，因此中间栏显示带空 transcript（文本记录）与常驻 composer 的 `ConversationRoot`。Figma 的 NEW SESSION 屏（`EmptyState` + 共用的 `InputBar` hero）仅在 `sessions.current` 已为 undefined 时渲染，因而主创建控件无法到达启动页。
|
||||
|
||||
## Decision
|
||||
|
||||
`SessionsService.clear()` 清除持久化选中项与 `list.current`。顶层侧栏创建入口（无 cwd 的 `onCreate()`——New Session 与 New Workspace）调用 `clear()`，使 `AppFrame` 渲染 `conversation.empty`。空态的首次发送仍走 `conversation.startSession`（create → open → send），并复用与常驻 composer 相同的 `InputBar` 组件（`variant="hero"`）。按项目的「+」（`onCreate(cwd)`）继续 create-then-open，直到空态选择器能接受预填的 cwd。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**为 New Session 保留 create-then-open，并在 transcript 为空时于 ConversationRoot 内再加一套空态 chrome。** 否决：这会重复启动页的 InputBar，并破坏 empty→content 的约定——同一 InputBar 应移动位置，而非互换组件。
|
||||
|
||||
**将 New Session 路由到选中状态之外的专用 route 或 slot。** 本轮否决：`conversation.empty` 已拥有启动 UI；清除 `current` 即是既有的空态分支。
|
||||
|
||||
## Consequences
|
||||
|
||||
New Session 在首次发送前不再创建 host 会话。clear 后重新加载仍停留在空态。项目范围的「+」仍立即创建。`EmptyState` 按 Figma 堆叠英雄区（Input_Bottom 75:8208）：鱼标 + 标题、卡片上方由 Menu 驱动的工作区 chip，再接共用的 `InputBar`（`variant="hero"`，max-width 800，与 composer 一致的 r20 卡片——而非更高的 r24 英雄区），选择器与卡片背后居中铺一层柔光椭圆（figma 313:14109），宽度按卡片锁定为 `1051/776` asset 比例，随卡片缩放。Chip 采用 75:8208 的柔和交互 hover 填充与 12px 圆角，并打开 MenuDropdown（figma 122:9481；`--dsw-specific-menu` + `--dsw-shadow-lv3`）：带文件夹图标与尾随勾选的 basename 行，分隔线后是 "New Workspace"，其子菜单（figma 419:16920）提供 "Use a existing folder" 与 "Create new"。Use a existing folder 打开路径 Dialog（figma 451:18655 copy — "Enter an existing folder path" / Open Folder），置于全视口遮罩（`--dsw-alias-bg-mask-1` + `--dsw-mask-blur`）之上，并设置 chip 的 cwd。Create new 打开同一套 Dialog chrome，在 `host.describe().cwd` 下命名文件夹；成功则走 `sessions.createWorkspace` → host `session.create`（mkdir recursive）→ `sessions.open`，在新 workspace 中默认落下一会话。`InputBar` 绘制底栏 chrome（attach / Plan / Read-only / model），仅用本地原生 `<select>` 状态——host 侧的 plan、access、model 接缝仍未接线。
|
||||
182
.agents/notes/archived/manifest.json
Normal file
182
.agents/notes/archived/manifest.json
Normal file
@@ -0,0 +1,182 @@
|
||||
{
|
||||
"version": 1,
|
||||
"files": {
|
||||
"architecture/2026-06-11-custom-schema-dsl.i18n.yaml": "sha256:f05d94c11762e506183044ddb1494a2b200ca16999ef3cef51c7b3a324eec945",
|
||||
"architecture/2026-06-11-custom-schema-dsl.md": "sha256:71286f2676f8b47d0bd56c6cc43cf8102946e6d195942860a5810b9c534d2b2b",
|
||||
"architecture/2026-06-11-custom-schema-dsl.zh.md": "sha256:999ff59565a4459184a644c4de6ef98c1bb1a174712e529f5c8417342abdd437",
|
||||
"architecture/2026-06-20-extract-example-app-packages.i18n.yaml": "sha256:d99b612cc1051c86d883d74737c72e921735e7a28e0b5e6351d3870c664bdcc4",
|
||||
"architecture/2026-06-20-extract-example-app-packages.md": "sha256:9c7aca3a1e9a1ccc3729961663bc649b90076e671cae23e3db8203305983ccce",
|
||||
"architecture/2026-06-20-extract-example-app-packages.zh.md": "sha256:19bd50232d9f25d35aa3f9dc72d9af0df457dd0eaca8b982d5aa625e5b95bcff",
|
||||
"architecture/2026-07-03-filesystem-directory-listing-seam.i18n.yaml": "sha256:636a822f3240e0401cdddad6a21f3454af1c1593fff14d4c9ce6613495f7dac1",
|
||||
"architecture/2026-07-03-filesystem-directory-listing-seam.md": "sha256:809a3c79f4d602607e8fa93aafd1ebccf4fae50c31f1fb1b1e386bb7ad089153",
|
||||
"architecture/2026-07-03-filesystem-directory-listing-seam.zh.md": "sha256:13735cd4c9fe990e6df3b028d6da01da89e94fde454dc0e968e517151cbd4281",
|
||||
"architecture/2026-07-05-windows-fs-permissions.i18n.yaml": "sha256:7e61ee9bbd9de4bf3285a6f250d9625bd062e5fb90279dbffd64c820f1f7fe6b",
|
||||
"architecture/2026-07-05-windows-fs-permissions.md": "sha256:03734da511eae3b0736f7cad73d9da76ae2f69f9d5ed09089b0121ccb135a861",
|
||||
"architecture/2026-07-05-windows-fs-permissions.zh.md": "sha256:454848057ea905fe76c88d17264e71e71fb685f08f82088de6976878372865c3",
|
||||
"architecture/2026-07-23-unified-session-query-service.i18n.yaml": "sha256:e8733b6543d9602ec206a087d9e89815f041f60fb57e93bee80e1309b9f03067",
|
||||
"architecture/2026-07-23-unified-session-query-service.md": "sha256:28d003686f29ec5e072e51e73da353575bcdcba5af20fefdfad88340e1ddd32c",
|
||||
"architecture/2026-07-23-unified-session-query-service.zh.md": "sha256:cfbe6525bc3b072fbc6db6bdca7a4d8cb4fc5507b1655bebc6af0589ed29ed31",
|
||||
"architecture/2026-07-24-dsh-commander-argument-adapter.i18n.yaml": "sha256:cf99eda0e58b49630d5f95792459d7095666fafbef61f614165d5cdd031b7118",
|
||||
"architecture/2026-07-24-dsh-commander-argument-adapter.md": "sha256:705654c8a43bcd199f72c21a77d24ca8bfa02447aff1c7f3e4e820be61dcd562",
|
||||
"architecture/2026-07-24-dsh-commander-argument-adapter.zh.md": "sha256:3844f02d7659d18caf5d39e1131ed775c789cbf92dc44b4a446c7d6468aa5d00",
|
||||
"bug-fix/2026-07-20-code-mode-result-card-completeness.i18n.yaml": "sha256:1035dae11d049d32ab09fd7d4f950eceae44bf46ba498b3cfaf3c75102b9fb64",
|
||||
"bug-fix/2026-07-20-code-mode-result-card-completeness.md": "sha256:6ca2c9d4df98be18813ef38b7462db880900b5bcd6944fbcd1b8f2258006b93e",
|
||||
"bug-fix/2026-07-20-code-mode-result-card-completeness.zh.md": "sha256:ed85fa7f935e5f525d566bc37a92014614983e649c75de9a9f244939097a7991",
|
||||
"bug-fix/2026-07-22-collapsed-sidebar-control-rail.i18n.yaml": "sha256:98de4a1ae016608b88010d413a204c2d33695f4b1d7217e5d1b705be09c1b669",
|
||||
"bug-fix/2026-07-22-collapsed-sidebar-control-rail.md": "sha256:b58620a3cf203507a5d651b90554bb7897e9d271613dc7c32d0f3bec992475bb",
|
||||
"bug-fix/2026-07-22-collapsed-sidebar-control-rail.zh.md": "sha256:f36ef24f26ead60b01169c8e4a2a01b396c3f4284f14979e4d52b47c9589075c",
|
||||
"bug-fix/2026-07-23-demo-web-builds-client-bundles.i18n.yaml": "sha256:f657e2166a05d6164c1ca65560bdd168ed969f7354217d8ec7a00274fd6c4307",
|
||||
"bug-fix/2026-07-23-demo-web-builds-client-bundles.md": "sha256:a9d8dfcd153b1d10479e9d42848f07adf89398cb685e1a09afafcecff14e36d9",
|
||||
"bug-fix/2026-07-23-demo-web-builds-client-bundles.zh.md": "sha256:dd06828964980798f343b8aafdeded2580b5b2e4c794305221fe73dab0a7eba2",
|
||||
"bug-fix/2026-07-23-thinking-row-disclosure-target.i18n.yaml": "sha256:fd926967311f30ea4a222e88b845f95d74af75d1e94b24ebef59186593b9ca78",
|
||||
"bug-fix/2026-07-23-thinking-row-disclosure-target.md": "sha256:92815c170972b1b91c3d75dd0c846c070805ec1e99ce368b6aae37b048e19869",
|
||||
"bug-fix/2026-07-23-thinking-row-disclosure-target.zh.md": "sha256:0e09f5f5e14d74214e5157ceb5859c866bab6de701c47e2ce5c450866d75aecf",
|
||||
"bug-fix/2026-07-26-intent-draft-same-tick-echo.i18n.yaml": "sha256:c623947c4fa00e6d4b51792c7972ba09582bbcb7605beb373725c0dd666f2c81",
|
||||
"bug-fix/2026-07-26-intent-draft-same-tick-echo.md": "sha256:fa8b1417b2cdd3deecbf8e55bdddd73dd3a8c6e3486fd399b0b8bdf317e56373",
|
||||
"bug-fix/2026-07-26-intent-draft-same-tick-echo.zh.md": "sha256:00ce72552dbaa11562fbc541343a5d33f9449edabbe6dd354eb879a7d4d530f8",
|
||||
"feature/2026-06-14-acp-agent-client-protocol.i18n.yaml": "sha256:006795baa43ae962a8d125cc0f1e9f134bc2ee9fb758b6e7669e3fa0126e1918",
|
||||
"feature/2026-06-14-acp-agent-client-protocol.md": "sha256:6828c0af74bb3fb96206ca6b21c0e56a000b50e4744aad4bc2c05092f3a5a31b",
|
||||
"feature/2026-06-14-acp-agent-client-protocol.zh.md": "sha256:ba104e841a1fb84edbd3b6c8119d50445b7785255a7a8d13bb9ac8a2cb4d2e69",
|
||||
"feature/2026-06-18-acp-terminal-and-tool-rendering.i18n.yaml": "sha256:79592f96bb25713d01865f37972a6919b2bfb3b66368df0f275bbd59d09ebcf6",
|
||||
"feature/2026-06-18-acp-terminal-and-tool-rendering.md": "sha256:946d0c580705ef2e7c7ac1897ada074e72f2ec4209c1e7531b6eccf116e9aecc",
|
||||
"feature/2026-06-18-acp-terminal-and-tool-rendering.zh.md": "sha256:fd815817925a038f79b52b6fab43abdb2d655db3ec07974ce1320ea3674f2afc",
|
||||
"feature/2026-06-30-subagent-observe-enrich.i18n.yaml": "sha256:08c2478ba394429f46c1e87a9f055e88704a9000e5d250d5600c0c85124cb17f",
|
||||
"feature/2026-06-30-subagent-observe-enrich.md": "sha256:0630975c3e325975a932f58a65a178b79c624dc56ebd29e288e96f5a189cfbfa",
|
||||
"feature/2026-06-30-subagent-observe-enrich.zh.md": "sha256:b9fbb44a7d81f4063faf3baaf97c382a2f5106be533feb4de792ee57b766c1a4",
|
||||
"feature/2026-07-07-plan-mode.i18n.yaml": "sha256:c59b6a6c218d741cdef8edf625f1d015e409a39411fa64e65200fdebb1c49394",
|
||||
"feature/2026-07-07-plan-mode.md": "sha256:7bf1bb8e826edf68f0ec919dfd4f66955b935b46b4400d7de85fac3e4663edbc",
|
||||
"feature/2026-07-07-plan-mode.zh.md": "sha256:5b08cbcd8023f26744e481386177dd0e82423e8b0032829d0dbc22a92cced0cd",
|
||||
"feature/2026-07-14-time-context-plugin.i18n.yaml": "sha256:670c093817c77e093562e02f43984d42ed44ebcced7c91d09366839e412d05e1",
|
||||
"feature/2026-07-14-time-context-plugin.md": "sha256:618b121da38a8b610bcadaecf121ca823b2c8c13598c012b350c214b82fd238f",
|
||||
"feature/2026-07-14-time-context-plugin.zh.md": "sha256:1e9eee8ba427a6f2ee08c79e2fcb33c0948e67a80758fdf9f8c9f7dff9aea361",
|
||||
"feature/2026-07-20-tui-startup-slogans.i18n.yaml": "sha256:265d1fd79dae6c785201c81ffe2de3baa9fe9e3b6c0f84aac79c90f4040ced15",
|
||||
"feature/2026-07-20-tui-startup-slogans.md": "sha256:aaaab4b419d35ce24317b7730f15af0029878bf3d17c6f184b05138c2cd44930",
|
||||
"feature/2026-07-20-tui-startup-slogans.zh.md": "sha256:01fba568cd92e9c54857f6dba1a3a5a6a4d0e906f36915d7e64682e67d456708",
|
||||
"feature/2026-07-21-dsh-system-prompt-source-path.i18n.yaml": "sha256:22efaf3237425fecbac1b40a444454e0fc244a3c85c2f6a14535de22ea777719",
|
||||
"feature/2026-07-21-dsh-system-prompt-source-path.md": "sha256:5fa554932c62a8bbd5a619581710d7f8b6b65d79ec1e340129cda96d279c5ae3",
|
||||
"feature/2026-07-21-dsh-system-prompt-source-path.zh.md": "sha256:995cd593074881c72510a6af3ba80108bbf986d49508cce9f698c2fcb493fd23",
|
||||
"feature/2026-07-21-tui-auto-pane-title.i18n.yaml": "sha256:0e9ad2adf0810811b2981435e761fd57b1e2cd89e5aa084522150c41e3cf3876",
|
||||
"feature/2026-07-21-tui-auto-pane-title.md": "sha256:0dd4572eacefc5fba508df8d1ff3f28b55e10b4b178e1f9773db3434a337c527",
|
||||
"feature/2026-07-21-tui-auto-pane-title.zh.md": "sha256:3ac195bf3fc63d40c2d36e6a38d6a41c73d8b21daa5e668412fd28b8a2630aa1",
|
||||
"feature/2026-07-21-tui-auto-title-default-on.i18n.yaml": "sha256:46815dbc1cbacfb11cb9f18f8df0f54dc1c4e5f9c051591dd3af97ad338b6c47",
|
||||
"feature/2026-07-21-tui-auto-title-default-on.md": "sha256:0caad9db58e031f9f667e93a3f53ebcf3c1f0700efc6decd51acafa3657372ac",
|
||||
"feature/2026-07-21-tui-auto-title-default-on.zh.md": "sha256:4e85a028e47caaa3f1cfcb01e143616c2a5a4916662c5f49f2b070386745d2e2",
|
||||
"feature/2026-07-21-tui-banner-brand-gradient.i18n.yaml": "sha256:adc228a5e6797096002619ba5bd8c47d49f2d5e98e40dd168ae5e07bc57bc460",
|
||||
"feature/2026-07-21-tui-banner-brand-gradient.md": "sha256:9b14ab1ae88eab598cd0f8d2d1cfbe53cec89a5374e3e3c765b487c91579e1eb",
|
||||
"feature/2026-07-21-tui-banner-brand-gradient.zh.md": "sha256:111dfde012857af10b2f7b9b8a9b9f783522e4ad14dad3ff5e25706b5bbffcbe",
|
||||
"feature/2026-07-21-tui-banner-sweep.i18n.yaml": "sha256:4cf71f8a8436bd9151be10aa7ae71ed1656206b49f056ae173e2b3e88bf9efea",
|
||||
"feature/2026-07-21-tui-banner-sweep.md": "sha256:87654f4b1960ab4f7455e993de298d2ee75f63ceb66fccea6136238ff0134b7a",
|
||||
"feature/2026-07-21-tui-banner-sweep.zh.md": "sha256:91b98a38c1111a561072d749a985c023ecaef0d749d6c1aaa320bfe0034660bd",
|
||||
"feature/2026-07-21-tui-borderless-banner.i18n.yaml": "sha256:9e80de590085e6e02f0830fedb149289387bb83eaa073c9f99a4eb7af1afba80",
|
||||
"feature/2026-07-21-tui-borderless-banner.md": "sha256:e3237b4de432cd97262a4baf1f64fee6bea48c3180a2e773575f603ed008d44c",
|
||||
"feature/2026-07-21-tui-borderless-banner.zh.md": "sha256:6c65cd654a1aed704d80b5882aba8ae0a2c1090709d672189847f5d0a6f58122",
|
||||
"feature/2026-07-21-tui-footer-cache-hit-rate.i18n.yaml": "sha256:56898ebb26741c83bb1c5de4c6e64bd3ca06b5e3b90ab79107823f19353596eb",
|
||||
"feature/2026-07-21-tui-footer-cache-hit-rate.md": "sha256:c66a1485d21fe6a4b975ffeed56c021c0d9556488bfadc4fb32648b3948c1fea",
|
||||
"feature/2026-07-21-tui-footer-cache-hit-rate.zh.md": "sha256:6fc2efe5817e83a9deb057a2de9b31b4c786700ebf40d38369abb5cefae231d0",
|
||||
"feature/2026-07-21-tui-no-banner.i18n.yaml": "sha256:26d98ba4a5c04504d649ada26d666dec0115026b9724af160483d0fcfa535903",
|
||||
"feature/2026-07-21-tui-no-banner.md": "sha256:a75c8535ac348199c9de0c2a6e266b3b4c21fe188f86ad1388a5241ad03c5a73",
|
||||
"feature/2026-07-21-tui-no-banner.zh.md": "sha256:05659d5e54a10fbace886f4407ec7a457cbab85139af03e3ae59612fa7611988",
|
||||
"feature/2026-07-21-tui-reload-command.i18n.yaml": "sha256:9be416ccd681aed0781fdfd2c44c4821c1e45f2a0deccb1f2b47d46163bde488",
|
||||
"feature/2026-07-21-tui-reload-command.md": "sha256:b8616457822ae87c90062308bc8c0d2badd5f368092ec65847d0d9520b1ac372",
|
||||
"feature/2026-07-21-tui-reload-command.zh.md": "sha256:c24bfcb0df13977a9c11c4d0fe433169e535b5f764995b668430dbb14a8e6b33",
|
||||
"feature/2026-07-21-tui-steering-queue-badge.i18n.yaml": "sha256:a029da558a6e14e1f13269960b98273ca9af0141579967acfbc19b656775f4a5",
|
||||
"feature/2026-07-21-tui-steering-queue-badge.md": "sha256:9aabd68c8910fdc7e7b05674492ddb8dc9285dd691fe554adcb84026fb846cc8",
|
||||
"feature/2026-07-21-tui-steering-queue-badge.zh.md": "sha256:919fd737866c3700f945751628071dab89eabdbf8f809deab93b9e6fbe2c8c59",
|
||||
"feature/2026-07-21-tui-verbose-status-line.i18n.yaml": "sha256:4371b9a46d713d4180aa5d0b1ecde1ff3cae948380a8f56474c895e6113d7824",
|
||||
"feature/2026-07-21-tui-verbose-status-line.md": "sha256:9dcba19ee725b1593e9413a1da5398c205a258aff2e384acd406bb618e86c7f0",
|
||||
"feature/2026-07-21-tui-verbose-status-line.zh.md": "sha256:203c2abac99cedf7afa2540c925367ba66f00b61b926d1cc86472a603ad2bb07",
|
||||
"feature/2026-07-23-trajectory-step-cell.i18n.yaml": "sha256:fe2e935a0affdef877902a40d9861ef5f55b30f40650469f6a52a4d45a92793f",
|
||||
"feature/2026-07-23-trajectory-step-cell.md": "sha256:185e3b87174cb6d2f2d2271fd2a74b1517d03e8570be602570d027bf6002d106",
|
||||
"feature/2026-07-23-trajectory-step-cell.zh.md": "sha256:51f46be43d2f5c4f78a05ed9aeec92d1f33ac988f45cf24d35528e9c43828ef3",
|
||||
"feature/2026-07-24-new-session-clears-to-empty-state.i18n.yaml": "sha256:978638cbf18bc6dce9fea0817654f41cc307f99004a637b85a63ae2208fe9095",
|
||||
"feature/2026-07-24-new-session-clears-to-empty-state.md": "sha256:b6b71d3883a167056070713e3dffb5046de953bdd218074d17c88e7690e03d83",
|
||||
"feature/2026-07-24-new-session-clears-to-empty-state.zh.md": "sha256:82a80b48337487029acd05a0137d268f0850f46801fa44a0e62733cacd00d5e9",
|
||||
"process/2026-06-11-doc-sync-enforcement.i18n.yaml": "sha256:33b6d5874427bd7a2bd82e7e2f4f482b12448b2464aef15a9c57975edb48554d",
|
||||
"process/2026-06-11-doc-sync-enforcement.md": "sha256:aa2fe83d519fc30d48dff19e596e83c8922aacc9e063e14fe2cc35b769b9100e",
|
||||
"process/2026-06-11-doc-sync-enforcement.zh.md": "sha256:698017bd35f030fdea3eac51df9e43138c48140f504739d687b7251d13fced2b",
|
||||
"process/2026-07-03-documentation-graph-atlas.i18n.yaml": "sha256:b1e1ed4b7865d87f939dbf8c94c0ea1069fdf7af6fa68f695e6c9d6eccbeb123",
|
||||
"process/2026-07-03-documentation-graph-atlas.md": "sha256:b62e92bb12123bfa4c4dac806f584aabb6b60af4c5a6a4ab88f84bb9153e766d",
|
||||
"process/2026-07-03-documentation-graph-atlas.zh.md": "sha256:3485ede4a5e695643bcf9e744a62f8914cff788ae35717dac5eb6bf77e0d65cf",
|
||||
"process/2026-07-06-parallel-github-ci-gates.i18n.yaml": "sha256:0f6ece268d9a51bc20cb8eb929f26d8838761603a64eb08dc24521198f10da36",
|
||||
"process/2026-07-06-parallel-github-ci-gates.md": "sha256:6249bd7396ae7f2d0dc671879ce21cefab33a47ace6ef17a25a70e8650b815af",
|
||||
"process/2026-07-06-parallel-github-ci-gates.zh.md": "sha256:cf7edb9bcf97ab1d4e452330c0df0b127a664509ec3f11597ace3eabeb663a5b",
|
||||
"process/2026-07-21-doc-sync-through-gate-scheduler.i18n.yaml": "sha256:1dbe70d21dd510bec4f2f56ae39d0fdc7290d5648280ca0b67224cd23b3a02a8",
|
||||
"process/2026-07-21-doc-sync-through-gate-scheduler.md": "sha256:b3eb3f2395ad8f1b77f44aa3fdac79856e5d0b6b4873560d0cc87b63de2ea2e0",
|
||||
"process/2026-07-21-doc-sync-through-gate-scheduler.zh.md": "sha256:e262e02c3d08057b83b0d29281eadb92723f0fe5b3f54424528f47be137bc760",
|
||||
"process/2026-07-22-installer-in-repo-skip-clone.i18n.yaml": "sha256:677aa91c3ccd9eda8a658b10410699ac608d3891d2fa32529898a3432fb56660",
|
||||
"process/2026-07-22-installer-in-repo-skip-clone.md": "sha256:4e30c0dd5429db33638a91a30afdd3386ac1a4705bd259a5eef325b5f86cced8",
|
||||
"process/2026-07-22-installer-in-repo-skip-clone.zh.md": "sha256:1d93c99f5a8d56077e766242c33245621626be55cf481d01c83bb5cbbe9a74d7",
|
||||
"process/2026-07-23-browser-demo-gif-recording.i18n.yaml": "sha256:808ccdda39e540645b440e40a2124baed737b98636265d8f6d8cf036a70f0d50",
|
||||
"process/2026-07-23-browser-demo-gif-recording.md": "sha256:4d3a3dc829c75b66f4f57a6a763b4b9562ce10efb90a19308142f598c5ea8524",
|
||||
"process/2026-07-23-browser-demo-gif-recording.zh.md": "sha256:409e5d31ea87f35c5227fcd1bd105167f580a8a24d29a223ce390b29eb31639a",
|
||||
"simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.i18n.yaml": "sha256:ad3d1263cb0051b885173bf064de62065e2c646ccaae2d7250723da3b4eab90c",
|
||||
"simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.md": "sha256:8fb061d51c8c23b47d2367814bab3623c6d5b972f38d207a273caa9030b579bd",
|
||||
"simplification/2026-06-20-drop-unconsumed-llm-adapter-change-event.zh.md": "sha256:2ffeaca91f82844a5616d6dcce6b4af514bb8a7c46f78e47f668b204ac6edc04",
|
||||
"simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.i18n.yaml": "sha256:f01960a5e8fab5e4f284f35ced6b84400aab257b243805db797a9c4a00ff525e",
|
||||
"simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.md": "sha256:0020f6b80e8bea5a8441b5bf7385a9bcfacbe14485f0e77de5d8b4fe3d2f69d0",
|
||||
"simplification/2026-06-20-drop-unconsumed-llm-assembled-surfaces.zh.md": "sha256:21647760eb06e57f8a38b35196233c634b8284a178b99b14f504a791758e9088",
|
||||
"simplification/2026-06-20-prune-dead-seam-methods.i18n.yaml": "sha256:0594648368c942f429599ac0ff5977d62c89c70a31d4bdbac61b0a30fe15ef3b",
|
||||
"simplification/2026-06-20-prune-dead-seam-methods.md": "sha256:fd3b0eaf600e178eeeef0c6cedc71f2382878733c557f1915d3b47f74a1d0d6d",
|
||||
"simplification/2026-06-20-prune-dead-seam-methods.zh.md": "sha256:4f5feef9331e3a1346bc362ffb39cfa373db2c609041bfeee6d88a10392464b1",
|
||||
"simplification/2026-07-04-drop-inert-request-knobs.i18n.yaml": "sha256:e4c992a27ae0e37e5ef663c2cddf55eefe20387fd6103bebf655834d8e75e9db",
|
||||
"simplification/2026-07-04-drop-inert-request-knobs.md": "sha256:8735c2b868a85b13235e0491a0fa7b9570dd090eef5170324fc5e93782687b67",
|
||||
"simplification/2026-07-04-drop-inert-request-knobs.zh.md": "sha256:78b243f5d580f2a6fbbdb7d26574295d6ed74feb8d9bba34bbcdf4aa87624b5c",
|
||||
"simplification/2026-07-04-drop-unconsumed-web-observation-surface.i18n.yaml": "sha256:30cbf5f573ad9df5140a2bc57181c6465dc3cb0717d192a8bbbb5b1c68a56f29",
|
||||
"simplification/2026-07-04-drop-unconsumed-web-observation-surface.md": "sha256:2d4d4ad2d0b72c602a20af6082392c22c889e4cf455614177fdc9e892069948e",
|
||||
"simplification/2026-07-04-drop-unconsumed-web-observation-surface.zh.md": "sha256:012b4fb2a346e01d5d88a53913a790df713650907ad7987b744bba456be36bbf",
|
||||
"simplification/2026-07-04-fold-stdio-ui-helper.i18n.yaml": "sha256:e0e476ec897d29a8688b201746a1db47033486b560c07244b37d91058d39e07a",
|
||||
"simplification/2026-07-04-fold-stdio-ui-helper.md": "sha256:d6cb5b0cbada51a19e4c2b1aab8dc738a30760ec8e7348e090ad44c8b80e3955",
|
||||
"simplification/2026-07-04-fold-stdio-ui-helper.zh.md": "sha256:57618fe935bf3310f1d91ab7d1940d8dff7b21919dbe82f1fa0137ae5f7c2189",
|
||||
"simplification/2026-07-04-prune-producerless-vocabulary-variants.i18n.yaml": "sha256:338c2290ae2cdcbeb758e996970e7f9dc8c36261f076302e358d70508604bac6",
|
||||
"simplification/2026-07-04-prune-producerless-vocabulary-variants.md": "sha256:87a269ba0c849084bf16b546fe8fff3e6bba188d3565b10099721109551ada5a",
|
||||
"simplification/2026-07-04-prune-producerless-vocabulary-variants.zh.md": "sha256:1485426f46ae46bf5c25ab95962cb7edc4dd3b43f3bd2211c0e41f02c505e1fc",
|
||||
"simplification/2026-07-04-prune-write-only-fs-surface.i18n.yaml": "sha256:6c8ed11b067c34f1af060d6c36de3685f3a15874786d811620b57e42c2b8d5c6",
|
||||
"simplification/2026-07-04-prune-write-only-fs-surface.md": "sha256:5602e09004f9f2b81f447abed4de10b18a96df5f44b13fd1cc0c06ffd3ce5b4a",
|
||||
"simplification/2026-07-04-prune-write-only-fs-surface.zh.md": "sha256:086f2cce3dc120f0c31c7dbc1855390f72e3940f2ffa92108de20fa175fff86a",
|
||||
"simplification/2026-07-04-remove-agent-steering-mirror.i18n.yaml": "sha256:24fb3c525cae7334841b7daca4c65783f013aa53910a81d20e092b4dd7081cda",
|
||||
"simplification/2026-07-04-remove-agent-steering-mirror.md": "sha256:3351fef50ba8635e5a3829a39cad24333bf3285799602b0891acdec312aa858f",
|
||||
"simplification/2026-07-04-remove-agent-steering-mirror.zh.md": "sha256:75ad399226bc42950128e410be9666cb3d0b76ca673418f31cd2a57a8f56e513",
|
||||
"simplification/2026-07-04-share-app-bin-boot-glue.i18n.yaml": "sha256:bd64279826444b41f6f1dc5d92fecd974edc3663885470f2eae226978926a59b",
|
||||
"simplification/2026-07-04-share-app-bin-boot-glue.md": "sha256:de0f4dca1e89c0c19d649aa37989df1991376d2cac1a5ec72c1a3ca0dce27e49",
|
||||
"simplification/2026-07-04-share-app-bin-boot-glue.zh.md": "sha256:e014ac4c2b609b70c467540ff0985c59a74df0eaf3062c43ffcaf1ac35d18ce2",
|
||||
"simplification/2026-07-04-trim-acp-bridge-unreachable-surface.i18n.yaml": "sha256:9080af48de70cc519f935896ae90134bcecdf4cee56bb5abb3e909672f2dded3",
|
||||
"simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md": "sha256:c11fbdea4bdd14eba517dc6377f8e59eb73fc05779424f38833cc662baf04fd5",
|
||||
"simplification/2026-07-04-trim-acp-bridge-unreachable-surface.zh.md": "sha256:f1bceae26fdea3fc71d8a0e32530eadb00342590a611b9fbc7ff09d0fc8aa3b8",
|
||||
"simplification/2026-07-12-drop-unconsumed-skill-provider-events.i18n.yaml": "sha256:cb9f223b74ea3ba0279f17d2bfd59033b67d1ea7b525b0ebee01fb9ee74da4be",
|
||||
"simplification/2026-07-12-drop-unconsumed-skill-provider-events.md": "sha256:cc78d0f80438e52e7d928b786101a902a15e4317fb0db2a47833c44520937c60",
|
||||
"simplification/2026-07-12-drop-unconsumed-skill-provider-events.zh.md": "sha256:ccb7146536c8a0f956d4799ddafc7b7cfea264fbc642107bd8aa24f06d88932d",
|
||||
"simplification/2026-07-12-prune-unused-web-seam-fields.i18n.yaml": "sha256:896dea8f5430603c445169fa79bfba997421a76d48fa4336349ec693572e6167",
|
||||
"simplification/2026-07-12-prune-unused-web-seam-fields.md": "sha256:e732eb5eed007e95f40f32eddd8d94cd34f0ce579f1a70b16ca072a48a3989b4",
|
||||
"simplification/2026-07-12-prune-unused-web-seam-fields.zh.md": "sha256:ac427d5cf6525c155b12dc7605954ebe3ce1f3edb6da0d0305e8d79cf475460b",
|
||||
"simplification/2026-07-19-retire-subagent-mock-package.i18n.yaml": "sha256:a7e5e21bf8a3a06bbf1272c677a7fff980e7548459405835416b88f1537bfe92",
|
||||
"simplification/2026-07-19-retire-subagent-mock-package.md": "sha256:3df91519b77efcc413a54927adb2f829e944ce7f827211ac6ae66d4b5e0398a7",
|
||||
"simplification/2026-07-19-retire-subagent-mock-package.zh.md": "sha256:c86d96800abc5aebf2d63694cb2cdcb21867091b2867de44493212f302498889",
|
||||
"simplification/2026-07-19-use-one-session-surface-manager.i18n.yaml": "sha256:602ab8fda1facb04a8f04d088267cbbd0426d607a8cc8c3fc056887f4a2696d9",
|
||||
"simplification/2026-07-19-use-one-session-surface-manager.md": "sha256:267882c357527a12d8581c9d78249819a987c766a74a2d47f351dc5b14bf7d0a",
|
||||
"simplification/2026-07-19-use-one-session-surface-manager.zh.md": "sha256:21c68a432c22209a3c19c8424da8e03fe91415d9ce3753cf17d727663077e4c9",
|
||||
"simplification/2026-07-20-retire-readline-front-door.i18n.yaml": "sha256:48b8573d325d280b65e7debde660140e7afdf1db793d4eb32c839c635121a965",
|
||||
"simplification/2026-07-20-retire-readline-front-door.md": "sha256:f632cd22fd81cc470992ff4e5f695a118a2aaed53748a860da7e9a78ca99ebbd",
|
||||
"simplification/2026-07-20-retire-readline-front-door.zh.md": "sha256:3612b25120a87f0e1c9d075c9e3c4b6a9449f38c8b219dd1aef506c6e6f92d98",
|
||||
"simplification/2026-07-21-tui-remove-cancel-command.i18n.yaml": "sha256:17ee6e9a3db867b85d8399879c40552a6771b5d7585f7b58e33601428a1309e3",
|
||||
"simplification/2026-07-21-tui-remove-cancel-command.md": "sha256:e90ad809b5ea241a653641f7331893347a1a0be7c677c99cbfc6bba8c907ab19",
|
||||
"simplification/2026-07-21-tui-remove-cancel-command.zh.md": "sha256:94d388753157eb498b9a8dbd9050dc07e5ee893e9b5a07f4c265b2e8e66f6338",
|
||||
"simplification/2026-07-21-tui-todo-write-opt-in.i18n.yaml": "sha256:633975e45444f179e5fcd258d3c4bce924975583505fa97f18cff21861a88ca2",
|
||||
"simplification/2026-07-21-tui-todo-write-opt-in.md": "sha256:7c4c0818f5cb5b1a506dabb71a56b7d79b811e4b912d492865f1404f4d1ece99",
|
||||
"simplification/2026-07-21-tui-todo-write-opt-in.zh.md": "sha256:2c121b8ea03182f7854e7d834b07967fdb6790af6a2a38c1d24bb0ca968496ba",
|
||||
"testing/2026-06-20-remove-redundant-snapshot-log-expected-output.i18n.yaml": "sha256:4177012c0821a8c22499852ecdf096af56d7263cb91c5d9d1bcd552cc26a3e00",
|
||||
"testing/2026-06-20-remove-redundant-snapshot-log-expected-output.md": "sha256:45234e7cc04b6010c6141f8d5924c04547300098f96262d423c50108e7c7011a",
|
||||
"testing/2026-06-20-remove-redundant-snapshot-log-expected-output.zh.md": "sha256:15e5a4ad3dee0bb711480cabe45cd97ec37bbdba19c2c2b47d1e9c203b07a48b",
|
||||
"testing/2026-06-22-fork-snapshot-scenarios.i18n.yaml": "sha256:d9fb0a30bbf58bbd6fcb45c84bee204f3f97a8a4cf7b867eec7320ba8663abf7",
|
||||
"testing/2026-06-22-fork-snapshot-scenarios.md": "sha256:2bd6458490789f68110ec6a7fb6ea55af544f09df854c163fcb83f04a440da98",
|
||||
"testing/2026-06-22-fork-snapshot-scenarios.zh.md": "sha256:f39e26c527dcb92d364b00bd3294f79bb30960ff35a4309bde00563aa594ec08",
|
||||
"testing/2026-07-04-hook-snapshot-matrix.i18n.yaml": "sha256:f8fe2a2893e929d3a0476151f4f44ce9b4c26790aae84f6ddbf365239ce6a0bb",
|
||||
"testing/2026-07-04-hook-snapshot-matrix.md": "sha256:287b9e0d97ea2e79a3ec6175c02ab01ef1314652528d5911a3a971e008094b6e",
|
||||
"testing/2026-07-04-hook-snapshot-matrix.zh.md": "sha256:25b33993da3b8eb94113b90050ac03b72d40bf085bff72b3119d38105a2d7ee2",
|
||||
"testing/2026-07-04-single-source-acp-replay-config.i18n.yaml": "sha256:cdf1ede909bc51792b1dcd74d5928111f75d4aba5020e8b30b3f395887348329",
|
||||
"testing/2026-07-04-single-source-acp-replay-config.md": "sha256:a94352fe79201949e28028abe4c7d932fd0d2e81d869e7d3b58d22f54a649417",
|
||||
"testing/2026-07-04-single-source-acp-replay-config.zh.md": "sha256:bed4dcd236a07192dd3de6c76e4a5c47dd5ec35963ce830bd5521bbb41d3f3a3",
|
||||
"testing/2026-07-06-pin-request-header-content-in-one-scenario.i18n.yaml": "sha256:4f3ebae0faea8a38ffe0d5291a33b3bcf99ed723f8e0cc5cccecbedbf4fb9ce9",
|
||||
"testing/2026-07-06-pin-request-header-content-in-one-scenario.md": "sha256:050bf8044ce22a27a0f57b5cef84ccff0dc45b1a3f6b70aa41950d41038d0702",
|
||||
"testing/2026-07-06-pin-request-header-content-in-one-scenario.zh.md": "sha256:cac75d4475666239bbe0030b90c0fa7cc66024af5b9f8ef217e53018be64890e"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-11-doc-sync-enforcement.md: 00fc6e904f1908b5cc4ddbe02b6eecf46b06408b
|
||||
2026-06-11-doc-sync-enforcement.zh.md: 9daaf88626d18093f8af7ba9ee5b6ce9e596d011
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: Doc-sync enforcement
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-06-11-doc-sync-enforcement.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
AGENTS.md promises that docs and code stay strictly in sync, but the promise was verified by eyeball. Review caught drift twice — a cookbook example contradicting the type policy, and a README citing the wrong `registerAdapter` call. Out-of-sync docs are worse than no docs, and this codebase is built primarily by agents that follow gates far more reliably than prose (mechanical quality gates). Two classes of doc drift are mechanically checkable: code blocks that no longer compile, and the event-taxonomy table that duplicates the `interface Events` declarations.
|
||||
|
||||
## Decision
|
||||
|
||||
Two gates, mirroring the existing `scripts/` style (tsx ESM, one job each):
|
||||
|
||||
1. **`doc-typecheck`** extracts every fenced ` ```ts ` block from `README.md`, `docs/**`, and `packages/*/README.md`, writes them to a temp project extending the root `tsconfig.json`, and compiles it with `tsc -b`. The temp project reuses the source `paths` map and the root project references, so documentation examples see source while vendored code remains checked under its own tsconfig settings. A block that is a deliberate sketch opts out with an explicit ` ```ts ignore-check ` info string; the script reports the opt-out ratio and fails if it exceeds half, so the escape hatch can't quietly become the norm.
|
||||
2. **`verify-event-taxonomy`** extracts the event names from the `interface Events` blocks across `packages/*/src` and from the taxonomy table in `docs/architecture.md`, and asserts the two sets match exactly. Verify, don't generate: the table keeps its hand-written Mode/Purpose columns; only the set of names is checked. (Landing this surfaced three events the table had been missing — `tools/change`, `llm/adapter-change`, `system-prompt/change`.) **Superseded** by [the generated cordis catalog](2026-06-20-generated-cordis-catalog.md): this gate and its `architecture.md` table are retired in favor of the fully-generated `docs/cordis-catalog/events.md` + `docs/cordis-catalog/services.md` and their `verify-cordis-catalog` freshness gate. The other gates here (`doc-typecheck`, and the `verify-md-wrap` amendment below) are unaffected.
|
||||
|
||||
Both run via a shared `doc-sync` package.json script that contributors invoke for relevant documentation changes and CI invokes exhaustively. The [fast local Git hooks](2026-07-22-fast-local-git-hooks.md) decision keeps this surface-selected work out of commit and push hooks.
|
||||
|
||||
**Amendment (2026-06-17):** a third gate, **`verify-md-wrap`**, was later folded into `doc-sync`. It parses each in-scope Markdown file (`README.md`, `docs/**`, `packages/*/README.md`, plus `AGENTS.md` / `packages/AGENTS.md`) with `mdast-util-from-markdown` + GFM and fails on any `paragraph` node spanning more than one source line, enforcing the docs/AGENTS.md "one physical line per paragraph" writing rule. Same verify-don't-generate principle: it reports hard-wraps and never rewrites, so it adds no formatting churn. `doc-sync` is now three gates.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **API-extractor golden reports** ([the deferred proposal](../../proposed/process/2026-06-11-api-extractor-reports.md)) — deliberately deferred: low value for an internal monorepo where reviewers already see the source diff, and a heavy, finicky dependency.
|
||||
- **Generating the taxonomy table from source** instead of verifying names — rejected as more machinery than the problem warranted; the table kept its hand-written Mode/Purpose columns until [the generated cordis catalog](2026-06-20-generated-cordis-catalog.md) superseded the check entirely.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Doc drift in the checkable classes fails `doc-sync` and CI instead of waiting for a reviewer to notice. This is an instance of the "mechanical gates over prose" principle.
|
||||
- Making doc snippets compile costs a few stub imports/`declare`s; the `ignore-check` ratio must stay low or the gate is theater (the ratio guard enforces this).
|
||||
- The taxonomy check is name-only — a wrong Mode or Purpose column still needs human review.
|
||||
- API reports remain available to revisit if the packages are ever published externally.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: Doc-sync 强制
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-06-11-doc-sync-enforcement.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
AGENTS.md 承诺文档与代码严格同步，但这一承诺此前仅靠人眼核查。评审曾两次发现漂移：一次是实操手册（cookbook）示例与类型策略矛盾，一次是 README 引用了错误的 `registerAdapter` 调用。失去同步的文档比没有文档更糟；而本代码库主要由 agent（智能体）构建，agent 遵守门禁远比遵守行文约定可靠（机械质量门禁）。有两类文档漂移可以被机械检查：不再能编译的代码块，以及与 `interface Events` 声明重复的事件分类体系表。
|
||||
|
||||
## 决策
|
||||
|
||||
两道门禁，沿用既有的 `scripts/` 风格（tsx ESM，每个脚本一项职责）：
|
||||
|
||||
1. **`doc-typecheck`** 从 `README.md`、`docs/**` 和 `packages/*/README.md` 中提取所有 ` ```ts ` 围栏代码块，写入一个继承根 `tsconfig.json` 的临时项目，然后用 `tsc -b` 编译。临时项目复用源码的 `paths` 映射和根 project references，因此文档示例能看到源码，而 vendor 代码仍在其自身的 tsconfig 设置下被检查。刻意作为草图的代码块可通过显式的 ` ```ts ignore-check ` 信息字符串来 opt-out；脚本会报告 opt-out 比例，超过一半即失败，防止该豁免机制悄然成为常态。
|
||||
2. **`verify-event-taxonomy`** 从 `packages/*/src` 中的 `interface Events` 块和 `docs/architecture.md` 中的分类体系表分别提取事件名称，断言两个集合完全一致。只校验，不生成：表格保留手写的 Mode/Purpose 列，仅检查名称集合。（落地此门禁时发现了表格遗漏的三个事件：`tools/change`、`llm/adapter-change`、`system-prompt/change`。）**已被取代**：由[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)取代。此门禁及其 `architecture.md` 表格已退役，取而代之的是完全生成的 `docs/cordis-catalog/events.md` + `docs/cordis-catalog/services.md` 及其 `verify-cordis-catalog` 新鲜度门禁。本 Agent Note（agent 决策记录）中的其他门禁（`doc-typecheck` 以及下文修订中的 `verify-md-wrap`）不受影响。
|
||||
|
||||
两者都通过 package.json 中共享的 `doc-sync` 脚本运行；贡献者在相关文档变更中调用它，CI 则执行完整检查。[快速本地 Git 钩子](2026-07-22-fast-local-git-hooks.md)决策使这类按变更面选择的工作不进入 commit 和 push 钩子。
|
||||
|
||||
**修订（2026-06-17）：** 第三道门禁 **`verify-md-wrap`** 随后被纳入 `doc-sync`。它使用 `mdast-util-from-markdown` + GFM 解析范围内的每个 Markdown 文件（`README.md`、`docs/**`、`packages/*/README.md`，加上 `AGENTS.md` / `packages/AGENTS.md`），如果任何 `paragraph` 节点跨越多个源码行则失败，从而强制执行 docs/AGENTS.md 中「一个段落一个物理行」的写作规则。同样遵循只校验不生成的原则：它报告硬换行但从不重写，因此不会引入格式化噪音。`doc-sync` 现在包含三道门禁。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **API-extractor 基准报告**（[已推迟的提案](../../proposed/process/2026-06-11-api-extractor-reports.md)）：有意推迟。对于评审者已能直接看到源码 diff 的内部 monorepo 而言价值有限，且依赖重、配置繁琐。
|
||||
- **从源码生成分类体系表**而非仅校验名称：否决，机制比问题本身更重；表格保留了手写的 Mode/Purpose 列，直到[生成式 Cordis 目录](2026-06-20-generated-cordis-catalog.md)完全取代了这项检查。
|
||||
|
||||
## 后果
|
||||
|
||||
- 可检查类别中的文档漂移会直接使 `doc-sync` 和 CI 失败，而不是等评审人发现。这是「机械门禁优于行文规范」原则的具体应用。
|
||||
- 让文档代码片段可编译需要少量 stub import/`declare`；`ignore-check` 比例必须保持低位，否则门禁形同虚设（比例守卫强制执行此约束）。
|
||||
- 分类体系检查仅限名称——Mode 或 Purpose 列的错误仍需人工评审。
|
||||
- 如果包（package）未来对外发布，API 报告方案仍可重新考虑。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-03-documentation-graph-atlas.md: 6f2949e3673c43018f961cc954c9925945875f55
|
||||
2026-07-03-documentation-graph-atlas.zh.md: 731ae8a97a8437216c706adf86574d1982d7c484
|
||||
@@ -0,0 +1,70 @@
|
||||
# Agent Note: Documentation graph index for maintainers and SDK users
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-03-documentation-graph-atlas.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The repo already had several high-trust documentation surfaces, each on a different axis: [module-graph.md](../../../../docs/module-graph.md) is generated from package `peerDependencies`, the generated [Cordis events](../../../../docs/cordis-catalog/events.md) and [services](../../../../docs/cordis-catalog/services.md) catalogs are generated from Cordis `Events` and `Context` declarations, [tool-catalog.md](../../../../docs/tool-catalog.md) is generated by booting shipped tool plugins, and [core-data-structures/](../../../../docs/core-data-structures/core.md) uses `ts type-equiv` blocks to keep pasted type definitions synchronized with source.
|
||||
|
||||
Those references are accurate, but they are mostly catalogs. A maintainer still has to synthesize the relationships: which packages form a capability seam, which app bundles a concrete spine, which event is durable vs live, where a hook or policy plugin can intercept work, and which model-facing tool depends on which service. An SDK user has the same problem from another angle: "Which package do I install or load for the behavior I want, and which event/service/tool do I extend?"
|
||||
|
||||
The hooks subsystem makes event producer/consumer topology and interception points much more important, and the filesystem seam makes capability seams, policy vetoes, tool presentation, and SDK assembly paths much more important — relationship graphs scoped to a small bash/todo/subagent surface would have gone stale immediately.
|
||||
|
||||
## Decision
|
||||
|
||||
Add generated relationship graph docs, indexed at [docs/graph-atlas.md](../../../../docs/graph-atlas.md), produced by focused generators and verified by `pnpm run verify-doc-graphs` / existing catalog freshness checks as part of `doc-sync`.
|
||||
|
||||
The index is a relationship layer above the existing catalogs. It does not replace exact references; instead, it links to them and explains how their pieces fit together.
|
||||
|
||||
### Maintenance modes
|
||||
|
||||
Every graph page declares one maintenance mode:
|
||||
|
||||
- **Generated**: all nodes and edges are discovered from source; `--check` fails if the committed artifact is stale.
|
||||
- **Hybrid generated**: source discovers the inventory, a small manifest classifies irreducible policy, and a completeness guard fails if discovered items are unclassified.
|
||||
- **Curated**: the diagram explains design intent, temporal order, or ownership; it is emitted by the generator so the graph docs remain a regenerated unit, but the content is deliberately authored.
|
||||
|
||||
### First shipped index
|
||||
|
||||
The index links ten relationship surfaces. Package topology and tool-package affordances live in the existing generated catalogs that already own those facts; the remaining focused diagrams are generated by `scripts/gen-doc-graphs.ts`.
|
||||
|
||||
| Graph | Maintenance mode | Source of truth |
|
||||
|---|---|---|
|
||||
| [module dependency graph](../../../../docs/module-graph.md) | generated | `packages/*/*/package.json` peer dependencies plus package group paths |
|
||||
| [tool schema catalog and package map](../../../../docs/tool-catalog.md) | generated | boot-harvested tool schemas plus tool-package service/effect metadata |
|
||||
| [capability seams and core services](../../../../docs/capability-seams.md) | hybrid generated | Cordis service declarations plus a role manifest in `gen-doc-graphs.ts` |
|
||||
| [tui-agent app composition](../../../../examples/tui-agent/composition.md) | hybrid generated | `examples/tui-agent/cordis.yml` plugin list plus curated app/bundle expansion |
|
||||
| [headless-agent app composition](../../../../examples/headless-agent/composition.md) | hybrid generated | `examples/headless-agent/cordis.yml` plugin list plus curated app/bundle expansion |
|
||||
| [cordis-agent app composition](../../../../examples/cordis-agent/composition.md) | hybrid generated | `examples/cordis-agent/cordis.yml` plugin list plus curated app/bundle expansion |
|
||||
| [acp-agent app composition](../../../../examples/acp-agent/composition.md) | hybrid generated | `examples/acp-agent/cordis.yml` plugin list plus curated app/bundle expansion |
|
||||
| [event producer/consumer matrix](../../../../docs/event-producer-consumer.md) | hybrid generated | Cordis event declarations, AST-scanned `ctx.on/emit/parallel/serial/waterfall` sites, and explicit dynamic dispatch overrides |
|
||||
| [agent turn and step lifecycle](../../../../docs/agent-lifecycle.md) | curated | architecture.md loop lifecycle, Cordis catalog links, and session event semantics |
|
||||
| [tool execution pipeline](../../../../docs/tool-execution-pipeline.md) | curated | tool pipeline semantics and the `tools/execute` waterfall |
|
||||
|
||||
### Why generators own the docs
|
||||
|
||||
Package topology stays in `gen-module-graph.ts`, and tool-package affordances stay in `gen-tool-catalog.ts`, because those generators already own the canonical facts and freshness gates. `gen-doc-graphs.ts` owns the remaining relationship pages and the index. The tradeoff is that curated diagrams are edited in TypeScript string blocks rather than directly in Markdown. That is acceptable for this first cut because the user-facing artifact is still plain Markdown/Mermaid, and a future change can split the curated pages out if authorship ergonomics matter more than regeneration.
|
||||
|
||||
### Completeness guards
|
||||
|
||||
The hybrid pages must fail loud when their manifests are stale:
|
||||
|
||||
- The module graph reads every package's `peerDependencies` and groups each package by its `packages/<group>/<pkg>` path.
|
||||
- The tool catalog boot-harvests shipped tools and renders the package/service/effect map from the same manifest that its completeness guard already checks.
|
||||
- The capability seam graph imports the Cordis service collector and asserts every discovered harness `ctx.<key>` is classified in `SERVICE_ROLES`, and every classified key still exists.
|
||||
- The event producer/consumer matrix labels itself hybrid because subagent lifecycle events deliberately use `ctx.events.dispatch` for per-listener containment; those dynamic edges are explicit overrides rather than invisible omissions.
|
||||
- `verify-mermaid` parses every repo-authored ` ```mermaid ` fence with Mermaid's own parser, so syntax errors fail `doc-sync` locally and in CI instead of showing up as broken GitHub-rendered diagrams.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
Committed diagrams use Mermaid because GitHub renders it in Markdown and it adds no new docs build dependency; dense many-to-many data such as event producer/consumer relationships uses Markdown tables instead. **PlantUML, hosted diagram services, and generated SVGs** were considered and deliberately not adopted until Mermaid becomes the limiting factor.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Maintainers get visual entry points for topology, seams, event flow, lifecycle, and app composition.
|
||||
- SDK users get a path from use case to package composition instead of only bottom-up package references.
|
||||
- `doc-sync` now includes `verify-doc-graphs` and `verify-mermaid`, so graph drift and Mermaid syntax errors are caught with the other doc freshness gates.
|
||||
- Future fs and hooks work has a concrete place to land new complexity: fs should expand the capability docs and tool catalog, while hooks should expand the event matrix and tool execution pipeline.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Agent Note: 面向维护者与 SDK 用户的文档关系图索引
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
[English](2026-07-03-documentation-graph-atlas.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
仓库已经有若干高可信文档表面，各自覆盖不同维度：[module-graph.md](../../../../docs/module-graph.md) 根据包（package）的 `peerDependencies` 生成；生成式 [Cordis 事件](../../../../docs/cordis-catalog/events.md)和[服务](../../../../docs/cordis-catalog/services.md)目录根据 Cordis `Events` 和 `Context` 声明生成；[tool-catalog.md](../../../../docs/tool-catalog.md) 通过启动已发布工具插件生成；[core-data-structures/](../../../../docs/core-data-structures/core.md) 则使用 `ts type-equiv` 块使粘贴的类型定义与源码保持同步。
|
||||
|
||||
这些参考文档是准确的，但大多是目录式的。维护者仍需自行综合关系：哪些包构成一个能力 seam、哪个应用组装了具体的主干、哪些事件是持久的而哪些是实时的、钩子或策略插件在哪里可以拦截工作、以及哪个面向模型的工具依赖哪个服务。SDK 用户从另一个角度面临同样的问题：「我想要某种行为，应该安装或加载哪个包？应该扩展哪个事件/服务/工具？」
|
||||
|
||||
钩子子系统使事件的生产者/消费方拓扑与拦截点变得更加重要；文件系统 seam 使能力 seam、策略否决、工具呈现与 SDK 组装路径变得更加重要。如果关系图的范围仅限于一个小的 bash/todo/subagent 表面，它们会立即陈旧。
|
||||
|
||||
## 决策
|
||||
|
||||
新增生成式关系图文档，由聚焦的生成器产出并在 [docs/graph-atlas.md](../../../../docs/graph-atlas.md) 建立索引；作为 `doc-sync` 的一部分，通过 `pnpm run verify-doc-graphs` / 现有目录新鲜度检查进行验证。
|
||||
|
||||
该索引是既有目录之上的关系层。它不取代精确的参考文档，而是链接到它们并解释各部分如何组合在一起。
|
||||
|
||||
### 维护模式
|
||||
|
||||
每个关系图页面声明一种维护模式：
|
||||
|
||||
- **Generated（生成）**：所有节点和边均从源码发现；如果已提交的产物陈旧，`--check` 失败。
|
||||
- **Hybrid generated（混合生成）**：源码发现清单，一个小型 manifest 对不可约的策略进行分类，完整性守卫在发现的条目未被分类时失败。
|
||||
- **Curated（人工策划）**：图表解释设计意图、时序或归属；它由生成器输出以使关系图文档保持为可重新生成的整体，但内容是有意撰写的。
|
||||
|
||||
### 首批发布的索引
|
||||
|
||||
该索引链接十种关系表面。包拓扑和工具包所提供的功能位于已经拥有这些事实的现有生成式目录中；其余聚焦图表由 `scripts/gen-doc-graphs.ts` 生成。
|
||||
|
||||
| 关系图 | 维护模式 | 真源 |
|
||||
|---|---|---|
|
||||
| [模块依赖图](../../../../docs/module-graph.md) | 生成式 | `packages/*/*/package.json` 的对等依赖（peer dependency）与包分组路径 |
|
||||
| [工具 schema 目录与包映射](../../../../docs/tool-catalog.md) | 生成式 | 启动后采集的工具 schema，以及工具包服务/效应元数据 |
|
||||
| [能力 seam 与核心服务](../../../../docs/capability-seams.md) | 混合生成式 | Cordis 服务声明，以及 `gen-doc-graphs.ts` 中的角色清单 |
|
||||
| [tui-agent 应用组合](../../../../examples/tui-agent/composition.md) | 混合生成式 | `examples/tui-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
|
||||
| [headless-agent 应用组合](../../../../examples/headless-agent/composition.md) | 混合生成式 | `examples/headless-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
|
||||
| [cordis-agent 应用组合](../../../../examples/cordis-agent/composition.md) | 混合生成式 | `examples/cordis-agent/cordis.yml` 插件列表，以及人工维护的应用/bundle 展开 |
|
||||
| [acp-agent 应用组合](../../../../examples/acp-agent/composition.md) | 混合生成式 | `examples/acp-agent/cordis.yml` 插件列表加人工策划的应用/bundle 展开 |
|
||||
| [事件生产者/消费方矩阵](../../../../docs/event-producer-consumer.md) | 混合生成式 | Cordis 事件声明、经 AST 扫描的 `ctx.on/emit/parallel/serial/waterfall` 位置，以及显式动态分派覆盖 |
|
||||
| [agent 轮次与步骤生命周期](../../../../docs/agent-lifecycle.md) | 人工维护 | architecture.md 循环生命周期、Cordis 目录链接，以及会话事件语义 |
|
||||
| [工具执行管线](../../../../docs/tool-execution-pipeline.md) | 人工维护 | 工具管线语义与 `tools/execute` waterfall（瀑布式事件）|
|
||||
|
||||
### 为什么由生成器拥有文档
|
||||
|
||||
包拓扑留在 `gen-module-graph.ts`，工具-包能力映射留在 `gen-tool-catalog.ts`，因为这些生成器已经拥有权威事实和新鲜度门禁。`gen-doc-graphs.ts` 拥有其余关系页面和索引。代价是人工策划的图表需要在 TypeScript 字符串块中编辑，而非直接编辑 Markdown。对于首版来说这是可接受的，因为面向用户的产物仍然是纯 Markdown/Mermaid；未来如果撰写体验比可重新生成更重要，可以将人工策划的页面拆分出去。
|
||||
|
||||
### 完整性守卫
|
||||
|
||||
混合生成的页面在其 manifest 陈旧时必须显式报错：
|
||||
|
||||
- 模块图读取每个包的 `peerDependencies`，并按 `packages/<group>/<pkg>` 路径对包进行分组。
|
||||
- 工具目录通过启动收集已发布的工具，并从同一份 manifest 渲染包/服务/副作用映射（其完整性守卫已在检查该 manifest）。
|
||||
- 能力 seam 图导入 Cordis 服务收集器，断言每个发现的 harness `ctx.<key>` 都已在 `SERVICE_ROLES` 中分类，且每个已分类的 key 仍然存在。
|
||||
- 事件生产者/消费方矩阵标记为 hybrid，因为 subagent 生命周期事件有意使用 `ctx.events.dispatch` 实现逐监听器隔离；这些动态边是显式覆盖而非无声遗漏。
|
||||
- `verify-mermaid` 使用 Mermaid 自身的解析器解析仓库中每个 ` ```mermaid ` 围栏，因此语法错误在本地和 CI 的 `doc-sync` 阶段即被捕获，而非在 GitHub 渲染时才显示为损坏的图表。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
已提交的图表使用 Mermaid，因为 GitHub 在 Markdown 中原生渲染它且不引入新的文档构建依赖；密集的多对多数据（如事件生产者/消费方关系）改用 Markdown 表格。**PlantUML、托管图表服务和生成的 SVG** 曾被考虑，但在 Mermaid 成为瓶颈之前有意不采用。
|
||||
|
||||
## 后果
|
||||
|
||||
- 维护者获得了拓扑、seam、事件流、生命周期与应用组合的可视化入口。
|
||||
- SDK 用户获得了从用例到包组合的路径，而非仅有自底向上的包参考。
|
||||
- `doc-sync` 现在包含 `verify-doc-graphs` 和 `verify-mermaid`，因此关系图漂移和 Mermaid 语法错误与其他文档新鲜度门禁一起被捕获。
|
||||
- 未来的文件系统和钩子工作有了承载新复杂度的具体位置：文件系统应扩展能力文档和工具目录，钩子应扩展事件矩阵和工具执行流水线。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-06-parallel-github-ci-gates.md: 0a621e0cf0b37d3ba6f612aaf1d9d7d052496929
|
||||
2026-07-06-parallel-github-ci-gates.zh.md: 340e5301b941fcb4774e2625e6706ab092a78c26
|
||||
@@ -0,0 +1,51 @@
|
||||
# Agent Note: Parallel GitHub CI gates
|
||||
|
||||
Status: implemented
|
||||
Archived: 2026-07-26
|
||||
|
||||
English | [中文](2026-07-06-parallel-github-ci-gates.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The keyless GitHub CI gates are mostly orthogonal: typecheck, lint, documentation freshness, coverage, snapshot replay, build, package-publication hygiene, demo smoke, and built-bin smoke fail for different reasons and do not need each other's runtime state. Running them as one ordered command chain makes the workflow wall clock equal the sum of those gates, while splitting every short leaf into its own GitHub job repeats checkout, Node setup, pnpm restore, and install work until orchestration overhead becomes the bottleneck.
|
||||
|
||||
The original broad-lane split stopped meeting that balance as the workspace grew. On the merge of PR #404, Linux static, coverage, snapshot, and artifact jobs took 148, 195, 94, and 230 seconds; Windows static and artifacts took 251 and 482 seconds. Package-manager packing once per package dominated both artifact validators, coverage needlessly rebuilt output before a source-only suite, and CPU-heavy gates contended inside the static and coverage lanes.
|
||||
|
||||
The artifact boundary remains load-bearing. `publint`, `verify-node-next-types`, compiled invariant loading, and built-bin smoke tests need emitted `lib/` output. Sharding cannot race those consumers ahead of build or replace their published-artifact signal with source execution.
|
||||
|
||||
## Decision
|
||||
|
||||
The production topology below is historical and is superseded by [Evidence-based larger hosted runners](2026-07-22-evidence-based-larger-hosted-runners.md). The larger-runner decision removes its shard selectors and workflow jobs; this note preserves why that earlier topology was implemented.
|
||||
|
||||
[CI](../../../../.github/workflows/ci.yml) treats one minute for non-Windows jobs and three minutes for Windows jobs as observed performance targets, not cancellation deadlines. Hosted-runner variance should leave complete timing evidence and useful failure logs instead of cancelling an otherwise-correct gate. The [serial cross-platform CI reference](2026-07-21-serial-cross-platform-ci-reference.md) independently runs the complete unsharded primary Node aggregate on Linux, macOS, and Windows so the optimized lane inventory is not its own completeness oracle.
|
||||
|
||||
In that topology, [scripts/run-gates.ts](../../../../scripts/run-gates.ts) was the common bounded scheduler and GitHub supplied explicit shard names for the expensive gate families. `scripts/static-shards.ts` partitioned static gates into foundation, documentation-type, API-contract, catalog, prose, documentation-projection, and documentation-build ownership and rejected a missing or duplicate gate assignment. Linux lint used disjoint A-C, D-M, N-S, and T-Z package-source and package-test lanes, while Windows used complete package-source and package-test lanes; both included a repository complement starting from `.` so new top-level targets could not disappear between shards and owned the single cross-file duplication run. `scripts/coverage-shards.ts` assigned every workspace package to exactly one source-coverage lane. Directory filters retained a trailing separator because Vitest positional filters match substrings and would otherwise admit prefix-named siblings. Each coverage lane included only its owned source files, repeated the exhaustive companion topology test, and ran without a preceding build because the complete coverage suite passes from a tree with every generated `lib/` removed.
|
||||
|
||||
Snapshot replay used two explicit multi-file lanes and eight scenario partitions of the large ACP file. `scripts/snapshot-shards.ts` owned that inventory, and its test discovered every file admitted by the snapshot config. Each snapshot job installed dependencies while its Linux runner prepared Bubblewrap, built the shipped runtime, and ran only its assigned replay surface. The suite retained bounded concurrency of five subprocesses because replay spent most of its time waiting on child protocol I/O. Fixture guards still inspected the complete ACP scenario table in every partition.
|
||||
|
||||
Cold standalone documentation typechecking rebuilds the complete project-reference graph, so a dedicated documentation-type lane builds once and checks Markdown blocks against those declarations. The Linux documentation lane uses VitePress's MPA build to retain page rendering and dead-link validation within the observed non-Windows target; separate blocking Windows build and production-site lanes preserve the emitted-package and shipped-site checks without putting both critical paths in one job.
|
||||
|
||||
Artifacts use two lanes: one metadata lane for `publint`, NodeNext declarations, and compiled invariant loading, plus one built-bin smoke lane. Each lane produces its own build before its consumers. Repeating the short build costs runner minutes but avoids an upload/download dependency and keeps each job's critical path bounded.
|
||||
|
||||
[scripts/publint-all.ts](../../../../scripts/publint-all.ts) calls publint's supported API in-process against an in-memory publication view made from each manifest's declared files and npm's mandatory metadata files. This preserves the distinction between workspace files and published files without spawning a package-manager pack command 103 times. [scripts/verify-built-package-invariants.mjs](../../../../scripts/verify-built-package-invariants.mjs) stages those structurally validated manifest-declared `lib/` files below the real package, then imports the compiled self-reference through plain Node and Cordis Loader normalization. A companion that reaches an undeclared runtime chunk still fails.
|
||||
|
||||
Compatibility lanes run the source worker and Zstandard runtime smokes on every advertised Node line. TypeScript checks the source graph once in a dedicated primary Node 24 lane; repeating the same compiler analysis in runtime compatibility jobs added time without runtime-specific signal.
|
||||
|
||||
The workflow caches the pnpm store, keys each immutable ESLint cache to its owning lint shard, preserves native PowerShell for Windows measurements, and retains one aggregate `all checks passed` status for branch protection. Windows reuses the three exhaustive lint partitions and groups foundation/catalog/prose plus documentation-type/API-contract gates behind shared runner setups; only scheduling differs from the Linux partitions. Windows build and production-site validation remain blocking, while the wider Windows static, lint, and artifact matrix remains observational.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Keep the broad lanes** - minimizes workflow YAML, but it preserves the measured multi-minute feedback loop.
|
||||
- **Run every leaf gate as a separate GitHub job** - maximizes fan-out, but short generators and prose checks would spend more time preparing a runner than checking the repository.
|
||||
- **Upload one build to artifact consumers** - avoids repeated compilation, but upload/download and dependency scheduling lengthen wall time; the clean build is short enough to repeat inside bounded lanes.
|
||||
- **Keep package-manager packing in both publication gates** - delegates inventory selection to pnpm, but repeats more than 200 package-manager processes. The manifest structural gate plus publication-view fixtures make the optimized inventory contract explicit and fail on an on-disk but unpublished dependency.
|
||||
- **Keep build before coverage** - provides emitted output the source suite no longer consumes; a clean-tree coverage proof showed it was pure latency.
|
||||
- **Typecheck on every Node version** - repeats compiler work while the compatibility smokes already exercise actual Node-specific loading and compression behavior.
|
||||
|
||||
## Consequences
|
||||
|
||||
The shard inventories and matrix jobs described above are not part of the current repository contract. The superseding larger-runner decision keeps the complete primary inventory in one process and uses the serial suite as its independent completeness oracle.
|
||||
|
||||
The optimized publication validators rely on the manifest `files` contract enforced by `verify-package-invariants`. If publication rules grow beyond that contract, the structural gate and both staged views must change together.
|
||||
|
||||
Compatibility jobs no longer claim that TypeScript itself was exercised under every Node runtime. They prove runtime-sensitive source loading on Node 22, 24, and 26, while the primary runtime owns the single source-graph typecheck.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user