diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml index 96bb5de13f..b39cad3e24 100644 --- a/docs/defensive-patterns.i18n.yaml +++ b/docs/defensive-patterns.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -defensive-patterns.md: fda0be0d2d3b7fa099162123b3d219673eebd07d -defensive-patterns.zh.md: f6e4712a4a239c954193f63f32285037eb6d4f0e +defensive-patterns.md: 349b916df6f7544300dacd578acf42668d9436ac +defensive-patterns.zh.md: 19565f54595195a52d1b49ff487294945171ae2d diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md index f6e4712a4a..19565f5459 100644 --- a/docs/defensive-patterns.zh.md +++ b/docs/defensive-patterns.zh.md @@ -14,7 +14,7 @@ ## 异步状态不是同步状态 -`agent.send()` 不会在返回前翻转状态；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿基于一个刚刚请求的状态来控制流程——应以实际触发的事件/promise（`agent/status`、`task.done`）驱动生命周期，并观察状态转换（先看到 `running` 再看到 `idle`），而非计数你假定与轮次一一对应的操作（循环会批量处理排队消息）。这条守则是双向的：如果等待的转换永远不会发生（EOF 时没有提交过任何工作 → 永远不会进入 `running`），等待就会挂起——请显式处理「无需等待」的分支。 +`agent.send()` 不会在返回前翻转状态；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿基于一个刚刚请求的状态来控制流程——应以实际触发的事件/promise（`agent/status`、`task.done`）驱动生命周期，并观察状态转换（先看到 `running` 再看到 `idle`），而不是把状态当作单次发送的结果：多个排队发送会在同一个 `running` 区间内连续运行多个轮次，而取消或资源释放可能丢弃尚未启动的项。这条守则是双向的：如果等待的转换永远不会发生（EOF 时没有提交过任何工作 → 永远不会进入 `running`），等待就会挂起——请显式处理「无需等待」的分支。 ## Dispose 必须达到静止，而不仅仅是请求停止 diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml index fe099eb156..6352220975 100644 --- a/docs/glossary.i18n.yaml +++ b/docs/glossary.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -glossary.md: 23eebc5793e8232482a796f5bde1e794f0556208 -glossary.zh.md: a233f926ba3af0a4e90de90bf21d68a2244c3ea6 +glossary.md: c1931c0e0c630d05f5bd4fc3f30720f858f1175e +glossary.zh.md: f8f3c9489a8be94de7fb3f021dd70bea7a399d73 diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md index a233f926ba..f8f3c9489a 100644 --- a/docs/glossary.zh.md +++ b/docs/glossary.zh.md @@ -2,9 +2,9 @@ [English](glossary.md) | 中文 -DeepSeek Harness SDK 的领域词汇对每个概念使用唯一的规范术语。各术语通过标准 Markdown 锚点互相链接；实现细节留在各 package README 与 RFC 中。 +DeepSeek Harness SDK 的领域词汇为每个概念规定一个规范术语。各术语通过标准 Markdown 锚点链接到相应条目；实现细节留在各包（package）的 README 与 Agent Note（agent 决策记录）中。 -FIXME(glossary-completeness): Expand this glossary before the first release so it covers the SDK's other core and capability subsystems, not only agent scope. +FIXME(glossary-completeness): 首次发布前扩充本术语表，使其覆盖 SDK 的其他核心与能力子系统，而非仅限于 agent scope。 ## agent-scope @@ -16,4 +16,28 @@ FIXME(glossary-completeness): Expand this glossary before the first release so i - **shadowing**：最具体者胜出的名称解析：一个有范围的工具/片段/变量仅在该 scope 内替换同名的全局对应项。这是按 agent 定制 persona 和按 agent 定制工具变体的机制。 - **restriction / scope-local 注册**：restriction（`tools.restrict`）为单个 scope 过滤全局工具表面（多个 restriction 取交集组合）；scope-local 注册在过滤之后合并。被过滤掉的全局工具既不出现在提示词中，也拒绝执行，与不存在的工具无法区分。 - **setup window**：创建者组装 agent 有范围世界的创建时隙（`CreateAgentOptions.setup`）：在 scope 和 agent 对象已存在、但 agent 或会话尚未发布、`agent/session-start` 尚未触发、首次提示词尚未组装之前。setup 只做注册，从不驱动 agent。 -- **lineage**：以数据形式携带的父子关系事实（`parentSession`、`subagentDepth`）；从不影响可见性。 +- **lineage**：以数据形式携带的父子关系事实（`parentSession`、持久的 `delegationDepth`、运行时 `subagentDepth`）；从不影响可见性。 + +## 目标 + +- **目标**：附着在现有会话上的单个持久完成目标，带有按修订号演进的 `active` / `paused` / `blocked` / `complete` 阶段和目标回合上限；`blocked` 保留策略代码与说明。目标是一种状态，不是调度器，也不是一段独立对话；会话日志仍是其真源。 +- **目标回合**：为当前目标接纳的一次续行周期。同会话驱动器将目标回合具体化为一个来源为目标的[轮次](#turn)，其中可以包含多个步骤；同一会话中无关的人类轮次不消耗目标回合上限。 +- **目标激活**：续行消费方接纳下一个目标回合的进程本地权限。激活态为 `armed` 或 `disarmed`；它有意不参与持久回放，因此恢复和 fork 后，必须由人类随后通过 `/goal` 或模型工具授权恢复变更，自动工作才可开始。 + +## 人类命令 + +- **人类命令**：以斜杠开头的指令，由面向人类的适配器通过 `ctx.commands` 解释并执行，不会成为模型消息。它既不同于面向模型的工具，也不同于通过 `ctx.bash` 执行 shell 命令。 +- **命令平面**：由 UI 适配器与命令插件拥有的发现、解析、分发、取消和结果渲染。除非处理器另行改变持久领域，否则命令输出属于 UI 状态。 +- **目标命令**：`/goal` 是由 `dsh-command-goal` 提供的人类命令；它直接观察或更改当前目标，而目标领域拥有每条持久且模型可见的记录。 + +## 循环层级 + +- **轮次**：会话中一次对已接纳输入的排空过程，在模型及其工具停止工作或终止策略介入后结束。 +- **步骤**：一次模型请求，以及由模型响应引发的工具执行；一个轮次包含一个或多个步骤。 +- **回合**：包含一个轮次的外层策略迭代，例如一个[目标回合](#goal-round)或一次全新 agent Ralph 尝试。回合计数器属于该策略，并不统计会话内的每个轮次。 + +## Ralph + +- **Ralph 循环**：一次面向不可变目标的前台全新 agent 工作流运行。它是由工作流和 subagent 原语组合而成的面向模型的工具策略，不是同会话目标、agent loop（智能体循环）模式、调度器或通用工作流脚本功能。 +- **Ralph 回合**：[Ralph 循环](#ralph-loop)中的一个全新子会话。子会话不接收父会话或此前子会话的对话种子；共享工作区和一份有界的 [Ralph 交接](#ralph-handoff)承载跨回合状态。 +- **Ralph 交接**：从一个仍需继续的 Ralph 回合传给下一回合的规范化、有界结构化报告，包含状态、摘要、证据、后续步骤和阻塞说明。它补充共享工作区，而不取代工作区的权威地位。 diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml index 2a72aaa53e..224c3e6314 100644 --- a/docs/i18n/README.i18n.yaml +++ b/docs/i18n/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -README.md: c4ddf44ad2497b4ff371918356ab1ec0698c7049 -README.zh.md: 4a31af4fdee4db2d0362cf9117a6eef4fea32393 +README.md: 16c036c98176f5410fe24fc24348177c84ad47a6 +README.zh.md: b37eeea99564d602523a4ebe379de38750dbc1ba diff --git a/docs/i18n/README.md b/docs/i18n/README.md index c4ddf44ad2..16c036c981 100644 --- a/docs/i18n/README.md +++ b/docs/i18n/README.md @@ -40,7 +40,7 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co **Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them): -- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, and `docs/module-graph.md` — generated files; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list. +- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list. - `docs/AGENTS.md` and `.agents/notes/**/AGENTS.md` — agent instructions, maintained in English only like the root `AGENTS.md`. - `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction. - [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior. diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md index 4a31af4fde..b37eeea995 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -40,7 +40,7 @@ **排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）： -- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md` 与 `docs/module-graph.md`——生成文件；生成器目前只输出英文，手写译文在每次重新生成时必然陈旧。计划中的后续工作是让生成器同时输出中文，届时这些文件移出排除清单。 +- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`——生成文件；生成器目前只输出英文，手写译文在每次重新生成时必然陈旧。计划中的后续工作是让生成器同时输出中文，届时这些文件移出排除清单。 - `docs/AGENTS.md` 与 `.agents/notes/**/AGENTS.md`——agent 指令，与根 `AGENTS.md` 一样只以英文维护。 - `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)——二者本身即为中英对照文档。 - [translation-prompt.md](translation-prompt.md)——自动翻译流水线的 prompt 模板；正文逐字进入模型请求，配对翻译会改变流水线行为。 diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml index e91d6712ea..8ef18d76b6 100644 --- a/docs/testing.i18n.yaml +++ b/docs/testing.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -testing.md: ddb9da0b38e5dc9cc75ede81ec157c4744fd11c2 -testing.zh.md: 8a37a9eaffbf19b205e3b98e7609464133060cf2 +testing.md: 1de3a0754dadbad1f36a9fc8c19b8ba77071bd54 +testing.zh.md: c557dfd91bca436a9c969cde6e2a0b24237e3146 diff --git a/docs/testing.md b/docs/testing.md index 22a678a230..1de3a0754d 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -9,15 +9,15 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning - **Unit** (`pnpm run test`): vitest over `packages|examples/*/tests/**/*.spec.ts`, colocated with what they test. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Prefer edge cases, error paths, event ordering, concurrency races, and permanent contract regressions (see `packages/core/agent-loop/tests/contract-regressions.spec.ts`). - **Coverage gate** (`pnpm run test:coverage`): the gating run, per-file 100% on `packages/*/*/src`. An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped. - **Real-API e2e** (`pnpm run test:e2e`): with-key tests against live provider APIs — the DeepSeek model plus provider-specific smokes that gate on their own keys (`EXA_API_KEY`, `PERPLEXITY_API_KEY`, …); each suite self-skips without its key so keyless CI stays green ([real-API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)). -- **Snapshot** (`pnpm run test:snapshot`): transport-specific keyless expected outputs cover external presentation. ACP suites boot the real example subprocess, replay a recorded session, and diff normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); the headless suite independently pins `stream-json` through its real one-shot subprocess. TUI completed journeys replay recorded primary/child JSONL through the real agent loop and tools before projecting ANSI into semantic terminal-state expected outputs; package-local snapshots retain transient renderer states, and a real PTY conversation covers the process boundary ([TUI snapshot Agent Note](../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)). Use `pnpm run test:snapshot:record` when a model transcript must change and `pnpm run test:snapshot:refresh` when committed replay input remains correct; review every JSONL and expected-output diff. System-prompt/tool-schema content is pinned by one ACP scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header Agent Note](../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). +- **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external presentation. ACP boots the real example, replays a recorded session, and diffs normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); headless pins `stream-json` through its real one-shot process. TUI journeys replay primary/child JSONL through the real loop and tools, then project ANSI into semantic terminal-state outputs; package snapshots retain transient states and a real PTY covers the process boundary ([TUI snapshot Agent Note](../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)). Use `pnpm run test:snapshot:record` when a model transcript changes and `pnpm run test:snapshot:refresh` when replay input remains valid; review every JSONL and expected-output diff. One ACP scenario (`text-turn`) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line ([pinned-header Agent Note](../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). ## The with-key policy: inference is cheap here -We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Write many: file-writing prompts, multi-turn conversations, tool use, cancellation mid-stream. Highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal. Every example ships both a keyless smoke and a with-key smoke ([examples/AGENTS.md](../examples/AGENTS.md)). +We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Cover file-writing prompts, multi-turn conversations, tool use, and mid-stream cancellation. Highest-value are **smoke tests** that boot the real example, send one prompt, and check the world — they catch the "green unit tests, broken product" class that mocks cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). Self-skip keeps secretless CI and keyless contributors unblocked; it is not a cost signal. Every example ships keyless and with-key smokes ([examples/AGENTS.md](../examples/AGENTS.md)). ## Prefer the real implementation over a mock -Mock only the genuinely expensive or non-deterministic boundary (the LLM adapter, the network, the clock); keep everything downstream real. A hand-rolled stand-in proves the bridge moves bytes, not that the shipping tool behaves as asserted — the two drift while the test stays green. Example: bridge tool-call tests run the scripted mock MODEL but the real tool + real executor (`makeBridgeHarness({ withBash: true })` plugs `dsh-bash-local` + `dsh-tool-bash` and runs an actual `echo`). +Mock only the expensive or non-deterministic boundary (LLM adapter, network, clock); keep everything downstream real. A hand-rolled stand-in proves the bridge moves bytes, not that the shipping tool behaves as asserted. Bridge tool-call tests use the scripted mock model with the real tool and executor: `makeBridgeHarness({ withBash: true })` plugs in `dsh-bash-local` and `dsh-tool-bash`, then runs `echo`. Recovery tests separate pre/post-chunk failures by step and prove failed chunks derive no message or tool side effect. Cover exhaustion, cancellation, policy composition, persistence, status, wire counts, transport-closing idle timeouts, and shipping Loader composition. diff --git a/docs/testing.zh.md b/docs/testing.zh.md index 8a37a9eaff..c557dfd91b 100644 --- a/docs/testing.zh.md +++ b/docs/testing.zh.md @@ -2,22 +2,24 @@ [English](testing.md) | 中文 -本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；关联的 RFC 承载设计动机。 +本文说明本仓库的分层测试方式，以及保持绿色测试套件有意义的规则。命令见根目录 [AGENTS.md](../AGENTS.md)；相关 Agent Note（agent 决策记录）承载设计动机。 ## 层级 - **单元测试**（`pnpm run test`）：vitest 运行 `packages|examples/*/tests/**/*.spec.ts`，与被测代码同目录。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及永久性契约回归（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。 -- **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试，调用真实提供方 API。包括 DeepSeek 模型以及各提供方特有的冒烟测试（各自依赖自己的密钥：`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等）；缺少密钥时各套件自动跳过，keyless CI 保持绿色（[真实 API e2e RFC](rfc/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。 -- **快照测试**（`pnpm run test:snapshot`）：启动真实示例子进程，在无密钥环境下回放录制的会话，将归一化的 stdout 与重新持久化的日志与已提交的 golden 文件做 diff（[快照 RFC](rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)）。当模型 transcript（文本记录）需要变更时使用 `pnpm run test:snapshot:record`；当已提交的 transcript 仍是正确的 mock LLM（大语言模型）输入、只需无密钥重写回放 golden 时使用 `pnpm run test:snapshot:refresh`。请审查 golden diff。系统提示词/工具 schema 内容由**一个**场景（`text-turn`）固定，其余 fixture（测试前置数据）中以 token 化形式引用，因此 prompt 或 schema 的修改只影响一行已提交内容（[pinned-header RFC](rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。 +- **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。 +- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外呈现。ACP 启动真实示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 通过真实单次运行进程固定 `stream-json`。TUI 旅程通过真实循环与工具回放主会话与子会话 JSONL，再将 ANSI 投影为语义化终端状态输出；包（package）级快照保留瞬态状态，真实 PTY 覆盖进程边界（[TUI 快照 Agent Note](../.agents/notes/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)）。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。 ## 带密钥策略：推理在这里很便宜 -我们是 DeepSeek，不要吝惜真实 API 测试。无密钥测试只能证明管道通畅；只有带密钥运行才能证明 agent（智能体）在真实模型面前能正常工作。请大量编写：文件写入 prompt、多轮次对话、工具调用、流中取消。价值最高的是**冒烟测试**：启动真实示例、发送一条真实 prompt、检查外部世界的状态。它们能捕获「单元测试全绿、产品却坏了」这一类 mock 在结构上无法发现的问题（[事后分析 0001](postmortem/0001-acp-default-export-drops-inject.md)）。自动跳过机制的存在仅仅是为了不阻塞无密钥的 CI 和无密钥的贡献者，它不是成本信号。每个示例都附带一个 keyless 冒烟测试，并且——除非本身就不需要密钥——还附带一个带密钥冒烟测试（[examples/AGENTS.md](../examples/AGENTS.md)）。 +我们是 DeepSeek，不要吝惜真实 API 测试。无密钥测试只能证明底层通路；只有带密钥运行才能证明 agent（智能体）能对接真实模型正常工作。覆盖文件写入提示词、多轮对话、工具使用和流中取消。价值最高的是**冒烟测试**：启动真实示例、发送一条提示词，并检查外部世界；它们能捕获「单元测试全绿、产品却坏了」这一类 mock 无法发现的问题（[事故复盘 0001](postmortem/0001-acp-default-export-drops-inject.md)）。自动跳过让无密钥 CI 和无密钥贡献者不受阻塞；它不是成本信号。每个示例都提供无密钥和带密钥冒烟测试（[examples/AGENTS.md](../examples/AGENTS.md)）。 ## 优先使用真实实现而非 mock -只在真正昂贵或不确定的边界处 mock（LLM 适配器、网络、时钟）；下游一切保持真实。手写的替身只能证明桥接层在搬运字节，不能证明交付的工具行为符合断言——两者会漂移，而测试继续绿着。例如：bridge 工具调用测试运行脚本化的 mock 模型，但使用真实的 tool + 真实的执行器（`makeBridgeHarness({ withBash: true })` 接入 `dsh-bash-local` + `dsh-tool-bash` 并执行真正的 `echo`）。 +只 mock 开销高或不确定的边界（LLM（大语言模型）适配器、网络、时钟）；下游一切保持真实。手写替身只能证明桥接层在搬运字节，不能证明交付的工具行为符合断言。桥接工具调用测试将脚本化 mock 模型与真实工具和执行器配合使用：`makeBridgeHarness({ withBash: true })` 接入 `dsh-bash-local` 与 `dsh-tool-bash`，然后运行 `echo`。 + +恢复测试按步骤区分分片前与分片后的失败，并证明失败分片不会派生出消息或工具副作用。覆盖耗尽、取消、策略组合、持久化、状态、协议计数、会关闭传输的空闲超时，以及交付的 Loader 组合。 ## 验证外部世界，而非自我报告 @@ -27,9 +29,14 @@ e2e 断言应重新运行命令或从外部重新读取文件；对 agent 自身 - 产品可见的插件必须有一个非单元的真实组合测试。手动构建的 `ctx.plugin(...)` 套件不够：通过 Loader 和 app/process 启动仅用于测试的 `cordis.yml`，只 mock 外部/不确定边界，断言模型可见的请求/日志、持久状态或用户可见输出。不要把 opt-in 选项混入交付默认值。 - 一个守卫只有在回归真的能让它失败时才有效。对于没有 `inject` 的插件（bundle/组合插件），Loader 冒烟测试在导出形状损坏时仍然绿着——需要添加显式的 `expect('default' in mod).toBe(false)` 加 `unwrapExports` 往返断言，并证明它有效：引入回归、观察变红、回退。 -- 「真实入口路径」指已发布的产物：package 的 `bin` 指向在普通 `node` 下运行的构建产物 `lib/bin.js`，tsx 会掩盖问题（竞态、模块解析、吞掉的加载失败以 exit 0 退出）。同样适用于构建后的 package 在运行时解析的任何非 index 运行时入口（worker-thread 运行时的兄弟文件 `lib/worker.cjs`）。保持构建产物冒烟测试绿色（`packages/ui/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零退出码退出。 -- 从临时 cwd spawn 示例的 e2e 测试需要设置 `TSX_TSCONFIG_PATH` 为仓库根目录的 tsconfig，否则会静默回退到陈旧的构建产物 `lib/`（[examples/AGENTS.md](../examples/AGENTS.md)）。 +- 「真实入口路径」指已发布的产物：包的 `bin` 所运行的是构建后的 `lib/bin.js`，并由普通 `node` 执行，从而暴露 tsx 会掩盖的失败（等待稳定时的竞态、模块解析、被吞掉的加载失败）。同样的规则适用于非 index 运行时入口（worker-thread 的同级文件 `lib/worker.cjs`），也适用于多个 bundle 共享的单例模块（`packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts`）。保持构建产物冒烟测试绿色（`packages/ui/*/tests/built-bin.e2e.ts`、`packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`），并断言真正缺失的配置以非零状态退出。 + +## 测试子进程启动模式 + +- CI 与已有构建产物的测试通道通过共享双模式启动器，从构建后的 `lib/` 运行每个示例或 Cordis 配置子进程。不要为这些子进程手写 `--import tsx`。 +- 不加载 Cordis 的协议与操作系统 fixture 直接通过 Node 运行使用可擦除语法的 `.ts` 文件，不经过 tsx 或根路径映射。 +- 只有测试对象本身是源码路径解析时，才可以选择 `src`；在测试中写明这一契约。 ## 何时需要快照测试 -任何影响编辑器侧 transcript 或端到端 agent UX 的变更——ACP bridge、agent loop（智能体循环）的可观测输出、工具呈现——都需要在所属示例的快照套件中添加或更新场景（`examples//tests/snapshots/`，基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表；`examples/acp-agent` 是主套件），或在 PR 中说明为何不适用。新的能力 seam、生命周期形态或 transcript 表面在计划阶段就要列出各层级的覆盖方案，并验证 harness 能够表达它——harness 的缺口是排期工作，不是构建中途的意外。 +每项非平凡的模型可见或人类可见变更，都必须在同一 PR 中，通过可运行示例所属的快照套件添加或更新无密钥场景。包测试、e2e 断言、mock 与仅测试组合、PR 理由都不能取代组装后的 transcript；必要时应扩展 harness。ACP 接口使用 `examples//tests/snapshots/`，即基于 [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) 套件工厂的场景表（`examples/acp-agent` 为主套件）；`examples/headless-agent` 拥有 `stream-json` 快照与回放 fixture。已完成的交互式终端旅程使用 `examples/tui-agent/tests/snapshots/` 下由 JSONL 驱动的场景；瞬态呈现使用包内语义矩阵，输入、Loader 选择或终端清理发生变化时还要添加 PTY 用例。新的能力 seam、生命周期形态或 transcript 呈现接口在计划阶段就要列出每个覆盖层级，并在实现前验证 harness 能够表达它们。