From ba3125234a4e968d19220eeac10642c41524fc19 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Tue, 28 Jul 2026 18:06:07 +0800 Subject: [PATCH] docs: rename core-data-structures/ to subsystems/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The folder is becoming the home of one-doc-per-subsystem pages (intro + data structures + cordis services/events), so the name must describe the whole contract, not just the type-vocabulary third of it. Mechanical rename rebuilt on current master: every inbound Markdown link, generator constant, website route, type-equiv manifest path, and spec expectation moves together; the zh sides of the notes whose prose names the folder are aligned (子系统) in the same change; touched bilingual pairs re-recorded; translation-prompt snapshot re-recorded (its example embeds development.md). Historical Agent Note slugs keep their dated filenames. --- ...eneric-long-running-tool-runtime.i18n.yaml | 4 +- ...06-20-generic-long-running-tool-runtime.md | 2 +- ...20-generic-long-running-tool-runtime.zh.md | 2 +- ...andatory-app-attribution-headers.i18n.yaml | 4 +- ...06-21-mandatory-app-attribution-headers.md | 2 +- ...21-mandatory-app-attribution-headers.zh.md | 2 +- ...stdin-env-trusted-plugin-surface.i18n.yaml | 4 +- ...0-bash-stdin-env-trusted-plugin-surface.md | 2 +- ...ash-stdin-env-trusted-plugin-surface.zh.md | 2 +- ...2026-07-15-agent-initiator-scope.i18n.yaml | 4 +- .../2026-07-15-agent-initiator-scope.md | 2 +- .../2026-07-15-agent-initiator-scope.zh.md | 2 +- .../2026-06-30-interception-seams.i18n.yaml | 4 +- .../feature/2026-06-30-interception-seams.md | 2 +- .../2026-06-30-interception-seams.zh.md | 2 +- .../2026-07-05-dynamic-workflows.i18n.yaml | 4 +- .../feature/2026-07-05-dynamic-workflows.md | 2 +- .../2026-07-05-dynamic-workflows.zh.md | 2 +- .../feature/2026-07-05-skill-system.i18n.yaml | 4 +- .../feature/2026-07-05-skill-system.md | 2 +- .../feature/2026-07-05-skill-system.zh.md | 2 +- .../feature/2026-07-06-sandbox.i18n.yaml | 4 +- .../implemented/feature/2026-07-06-sandbox.md | 2 +- .../feature/2026-07-06-sandbox.zh.md | 2 +- ...-10-parallel-tool-call-execution.i18n.yaml | 4 +- ...2026-07-10-parallel-tool-call-execution.md | 2 +- ...6-07-10-parallel-tool-call-execution.zh.md | 2 +- ...7-31-code-mode-language-dispatch.i18n.yaml | 4 +- .../2026-07-31-code-mode-language-dispatch.md | 4 +- ...26-07-31-code-mode-language-dispatch.zh.md | 4 +- ...-20-core-data-structures-catalog.i18n.yaml | 4 +- ...2026-06-20-core-data-structures-catalog.md | 4 +- ...6-06-20-core-data-structures-catalog.zh.md | 2 +- ...-fork-child-replay-seed-boundary.i18n.yaml | 4 +- ...6-06-22-fork-child-replay-seed-boundary.md | 2 +- ...6-22-fork-child-replay-seed-boundary.zh.md | 2 +- .agents/skills/dsh-code-review/SKILL.md | 2 +- docs/AGENTS.md | 4 +- docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 8 +- docs/architecture.zh.md | 8 +- docs/config-catalog.md | 12 +- docs/cordis-catalog/events.md | 84 +-- docs/cordis-catalog/services.md | 78 +-- docs/development.i18n.yaml | 4 +- docs/development.md | 4 +- docs/development.zh.md | 4 +- docs/graph-atlas.md | 2 +- docs/i18n/style-samples.md | 4 +- docs/persistence-catalog.md | 26 +- ...ice-misclassified-child-failures.i18n.yaml | 4 +- ...ial-notice-misclassified-child-failures.md | 2 +- ...-notice-misclassified-child-failures.zh.md | 2 +- .../approval.i18n.yaml | 2 +- .../approval.md | 0 .../approval.zh.md | 0 .../bash.i18n.yaml | 0 .../bash.md | 0 .../bash.zh.md | 0 .../code-runtime.i18n.yaml | 0 .../code-runtime.md | 0 .../code-runtime.zh.md | 0 .../commands.i18n.yaml | 2 +- .../commands.md | 0 .../commands.zh.md | 0 .../compaction.i18n.yaml | 2 +- .../compaction.md | 0 .../compaction.zh.md | 0 .../core.i18n.yaml | 2 +- .../core.md | 0 .../core.zh.md | 0 .../credentials.i18n.yaml | 2 +- .../credentials.md | 0 .../credentials.zh.md | 0 .../filesystem.i18n.yaml | 0 .../filesystem.md | 0 .../filesystem.zh.md | 0 .../goal.i18n.yaml | 0 .../goal.md | 0 .../goal.zh.md | 0 .../llm-streaming.i18n.yaml | 2 +- .../llm-streaming.md | 0 .../llm-streaming.zh.md | 0 .../lsp.i18n.yaml | 0 .../lsp.md | 0 .../lsp.zh.md | 0 .../persistence.i18n.yaml | 2 +- .../persistence.md | 0 .../persistence.zh.md | 0 .../pty.i18n.yaml | 0 .../pty.md | 0 .../pty.zh.md | 0 .../sandbox.i18n.yaml | 0 .../sandbox.md | 0 .../sandbox.zh.md | 0 .../scope.i18n.yaml | 0 .../scope.md | 0 .../scope.zh.md | 0 .../session-query.i18n.yaml | 0 .../session-query.md | 0 .../session-query.zh.md | 0 .../session-reference.i18n.yaml | 2 +- .../session-reference.md | 0 .../session-reference.zh.md | 0 .../session-title.i18n.yaml | 2 +- .../session-title.md | 0 .../session-title.zh.md | 0 .../session.i18n.yaml | 2 +- .../session.md | 0 .../session.zh.md | 0 .../settings.i18n.yaml | 2 +- .../settings.md | 0 .../settings.zh.md | 0 .../skills.i18n.yaml | 2 +- .../skills.md | 0 .../skills.zh.md | 0 .../spill.i18n.yaml | 0 .../spill.md | 0 .../spill.zh.md | 0 .../subagent.i18n.yaml | 0 .../subagent.md | 0 .../subagent.zh.md | 0 .../subprocess.i18n.yaml | 0 .../subprocess.md | 0 .../subprocess.zh.md | 0 .../system-prompt.i18n.yaml | 2 +- .../system-prompt.md | 0 .../system-prompt.zh.md | 0 .../tasks.i18n.yaml | 0 .../tasks.md | 0 .../tasks.zh.md | 0 .../token-meter.i18n.yaml | 0 .../token-meter.md | 0 .../token-meter.zh.md | 0 .../tools.i18n.yaml | 2 +- .../tools.md | 0 .../tools.zh.md | 0 .../typert.i18n.yaml | 0 .../typert.md | 0 .../typert.zh.md | 0 .../user-interaction.i18n.yaml | 2 +- .../user-interaction.md | 0 .../user-interaction.zh.md | 0 .../web.i18n.yaml | 0 .../web.md | 0 .../web.zh.md | 0 .../workflow.i18n.yaml | 0 .../workflow.md | 0 .../workflow.zh.md | 0 docs/tool-catalog.md | 2 +- packages/bash/bash/README.i18n.yaml | 4 +- packages/bash/bash/README.md | 2 +- packages/bash/bash/README.zh.md | 2 +- packages/compact/compact/README.i18n.yaml | 4 +- packages/compact/compact/README.md | 2 +- packages/compact/compact/README.zh.md | 2 +- packages/core/session/README.i18n.yaml | 4 +- packages/core/session/README.md | 2 +- packages/core/session/README.zh.md | 2 +- packages/core/tools/src/index.ts | 2 +- packages/goal/goal/README.i18n.yaml | 4 +- packages/goal/goal/README.md | 2 +- packages/goal/goal/README.zh.md | 2 +- packages/sandbox/sandbox/README.i18n.yaml | 4 +- packages/sandbox/sandbox/README.md | 2 +- packages/sandbox/sandbox/README.zh.md | 2 +- .../session/session-title/README.i18n.yaml | 6 +- packages/session/session-title/README.md | 2 +- packages/session/session-title/README.zh.md | 2 +- .../subprocess/subprocess/README.i18n.yaml | 4 +- packages/subprocess/subprocess/README.md | 2 +- packages/subprocess/subprocess/README.zh.md | 2 +- packages/tasks/tasks/README.i18n.yaml | 4 +- packages/tasks/tasks/README.md | 2 +- packages/tasks/tasks/README.zh.md | 2 +- .../typert/generator/src/cordis-catalog.ts | 6 +- .../tests/cordis-catalog-contract.spec.ts | 2 +- scripts/gen-config-catalog.ts | 6 +- scripts/gen-cordis-catalog.ts | 2 +- scripts/gen-doc-graphs.ts | 2 +- scripts/gen-persistence-catalog.ts | 8 +- scripts/gen-tool-catalog.ts | 2 +- scripts/project-doc-site.spec.ts | 8 +- .../request-response.expected.json | 4 +- scripts/type-equiv.manifest.json | 624 +++++++++--------- website/docs.ts | 10 +- 186 files changed, 564 insertions(+), 564 deletions(-) rename docs/{core-data-structures => subsystems}/approval.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/approval.md (100%) rename docs/{core-data-structures => subsystems}/approval.zh.md (100%) rename docs/{core-data-structures => subsystems}/bash.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/bash.md (100%) rename docs/{core-data-structures => subsystems}/bash.zh.md (100%) rename docs/{core-data-structures => subsystems}/code-runtime.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/code-runtime.md (100%) rename docs/{core-data-structures => subsystems}/code-runtime.zh.md (100%) rename docs/{core-data-structures => subsystems}/commands.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/commands.md (100%) rename docs/{core-data-structures => subsystems}/commands.zh.md (100%) rename docs/{core-data-structures => subsystems}/compaction.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/compaction.md (100%) rename docs/{core-data-structures => subsystems}/compaction.zh.md (100%) rename docs/{core-data-structures => subsystems}/core.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/core.md (100%) rename docs/{core-data-structures => subsystems}/core.zh.md (100%) rename docs/{core-data-structures => subsystems}/credentials.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/credentials.md (100%) rename docs/{core-data-structures => subsystems}/credentials.zh.md (100%) rename docs/{core-data-structures => subsystems}/filesystem.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/filesystem.md (100%) rename docs/{core-data-structures => subsystems}/filesystem.zh.md (100%) rename docs/{core-data-structures => subsystems}/goal.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/goal.md (100%) rename docs/{core-data-structures => subsystems}/goal.zh.md (100%) rename docs/{core-data-structures => subsystems}/llm-streaming.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/llm-streaming.md (100%) rename docs/{core-data-structures => subsystems}/llm-streaming.zh.md (100%) rename docs/{core-data-structures => subsystems}/lsp.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/lsp.md (100%) rename docs/{core-data-structures => subsystems}/lsp.zh.md (100%) rename docs/{core-data-structures => subsystems}/persistence.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/persistence.md (100%) rename docs/{core-data-structures => subsystems}/persistence.zh.md (100%) rename docs/{core-data-structures => subsystems}/pty.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/pty.md (100%) rename docs/{core-data-structures => subsystems}/pty.zh.md (100%) rename docs/{core-data-structures => subsystems}/sandbox.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/sandbox.md (100%) rename docs/{core-data-structures => subsystems}/sandbox.zh.md (100%) rename docs/{core-data-structures => subsystems}/scope.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/scope.md (100%) rename docs/{core-data-structures => subsystems}/scope.zh.md (100%) rename docs/{core-data-structures => subsystems}/session-query.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/session-query.md (100%) rename docs/{core-data-structures => subsystems}/session-query.zh.md (100%) rename docs/{core-data-structures => subsystems}/session-reference.i18n.yaml (79%) rename docs/{core-data-structures => subsystems}/session-reference.md (100%) rename docs/{core-data-structures => subsystems}/session-reference.zh.md (100%) rename docs/{core-data-structures => subsystems}/session-title.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/session-title.md (100%) rename docs/{core-data-structures => subsystems}/session-title.zh.md (100%) rename docs/{core-data-structures => subsystems}/session.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/session.md (100%) rename docs/{core-data-structures => subsystems}/session.zh.md (100%) rename docs/{core-data-structures => subsystems}/settings.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/settings.md (100%) rename docs/{core-data-structures => subsystems}/settings.zh.md (100%) rename docs/{core-data-structures => subsystems}/skills.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/skills.md (100%) rename docs/{core-data-structures => subsystems}/skills.zh.md (100%) rename docs/{core-data-structures => subsystems}/spill.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/spill.md (100%) rename docs/{core-data-structures => subsystems}/spill.zh.md (100%) rename docs/{core-data-structures => subsystems}/subagent.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/subagent.md (100%) rename docs/{core-data-structures => subsystems}/subagent.zh.md (100%) rename docs/{core-data-structures => subsystems}/subprocess.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/subprocess.md (100%) rename docs/{core-data-structures => subsystems}/subprocess.zh.md (100%) rename docs/{core-data-structures => subsystems}/system-prompt.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/system-prompt.md (100%) rename docs/{core-data-structures => subsystems}/system-prompt.zh.md (100%) rename docs/{core-data-structures => subsystems}/tasks.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/tasks.md (100%) rename docs/{core-data-structures => subsystems}/tasks.zh.md (100%) rename docs/{core-data-structures => subsystems}/token-meter.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/token-meter.md (100%) rename docs/{core-data-structures => subsystems}/token-meter.zh.md (100%) rename docs/{core-data-structures => subsystems}/tools.i18n.yaml (80%) rename docs/{core-data-structures => subsystems}/tools.md (100%) rename docs/{core-data-structures => subsystems}/tools.zh.md (100%) rename docs/{core-data-structures => subsystems}/typert.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/typert.md (100%) rename docs/{core-data-structures => subsystems}/typert.zh.md (100%) rename docs/{core-data-structures => subsystems}/user-interaction.i18n.yaml (79%) rename docs/{core-data-structures => subsystems}/user-interaction.md (100%) rename docs/{core-data-structures => subsystems}/user-interaction.zh.md (100%) rename docs/{core-data-structures => subsystems}/web.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/web.md (100%) rename docs/{core-data-structures => subsystems}/web.zh.md (100%) rename docs/{core-data-structures => subsystems}/workflow.i18n.yaml (100%) rename docs/{core-data-structures => subsystems}/workflow.md (100%) rename docs/{core-data-structures => subsystems}/workflow.zh.md (100%) diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml index e1171d5877..cb9ed4275a 100644 --- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.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 .agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md -2026-06-20-generic-long-running-tool-runtime.md: cb9d9487cd274696ae20dddab8c6888b4cf4b833 -2026-06-20-generic-long-running-tool-runtime.zh.md: fe5ca223975445991e7fe96376cbfccf432ad241 +2026-06-20-generic-long-running-tool-runtime.md: 90100ea8f146e505c4fbb95760781839bd4bd34a +2026-06-20-generic-long-running-tool-runtime.zh.md: bdcd8e8fe2a50033177354ce5ce043c4b5264621 diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md index cb9d9487cd..90100ea8f1 100644 --- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md +++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md @@ -23,7 +23,7 @@ Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into in ## Runtime contract -The literal types live in the [task data-structure catalog](../../../../docs/core-data-structures/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id. +The literal types live in the [task data-structure catalog](../../../../docs/subsystems/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, optional positive `outputLimitBytes`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id. `outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `TaskSnapshot`; generic control surfaces apply the cap to complete model-facing output after adding their own status or notice metadata. Omitting it preserves the existing surface behavior, so the runtime does not impose a hidden default on unrelated producer families. diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md index fe5ca22397..bdcd8e8fe2 100644 --- a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md @@ -23,7 +23,7 @@ Status: implemented ## 运行时契约 -字面类型见[任务数据结构目录](../../../../docs/core-data-structures/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。 +字面类型见[任务数据结构目录](../../../../docs/subsystems/tasks.md)。生产方调用 `ctx.tasks.start()`，传入 kind、label、可选的所属 `Agent`、可选的正数 `outputLimitBytes` 与一个 `run()` 函数。运行时会在调用 `run()` 前完成所有可能失败的预检工作，并且只调用一次。`run()` 返回钩子后，注册过程不会再执行可能失败的步骤而直接提交；生产方无法启动没有可收集 task id 的工作。 `outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `TaskSnapshot`；通用控制接口添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有接口行为，因此运行时不会向无关的生产方类别施加隐式默认值。 diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml index b6788a47ef..3db3ea7fa4 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.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 .agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md -2026-06-21-mandatory-app-attribution-headers.md: ad9d65805c8f0c96bd811b5036310d019760627e -2026-06-21-mandatory-app-attribution-headers.zh.md: 3021c7fcca00f2e929d997625c303f9a27dbf673 +2026-06-21-mandatory-app-attribution-headers.md: de9125bc891cc62798480e2eccb2c90cb633de3a +2026-06-21-mandatory-app-attribution-headers.zh.md: cdada9cb235d57ad5cac98ebe0572013cac728ef diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md index ad9d65805c..de9125bc89 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md +++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md @@ -51,7 +51,7 @@ Endpoint detection is not part of this Agent Note because no endpoint-specific m The landed contract: -- `dsh-llm` documents the mandatory `User-Agent` attribution contract for `LlmAdapter` authors (`LlmAdapter` JSDoc, package README, and the adapter-contract section of `docs/core-data-structures/llm-streaming.md`). +- `dsh-llm` documents the mandatory `User-Agent` attribution contract for `LlmAdapter` authors (`LlmAdapter` JSDoc, package README, and the adapter-contract section of `docs/subsystems/llm-streaming.md`). - A shared helper (`attributionHeaders` / `userAgent`) constructs the app identity and the standard `User-Agent` value from package metadata, so adapters do not hand-copy version constants. - `dsh-llm-deepseek` sends the shared `User-Agent` on every request and its mock-server suite asserts the exact value. - `dsh-llm-pi-ai` sends the same `User-Agent` through pi-ai's `StreamOptions.headers` hook and its mock-server suite asserts the exact value. diff --git a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md index 3021c7fcca..cdada9cb23 100644 --- a/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md @@ -51,7 +51,7 @@ LLM（大语言模型）提供方请求应当标识发出请求的产品。这 已落地的契约： -- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/core-data-structures/llm-streaming.md` 的适配器契约（adapter contract）章节）。 +- `dsh-llm` 为 `LlmAdapter` 作者文档化了强制的 `User-Agent` 归属契约（`LlmAdapter` JSDoc、包 README，以及 `docs/subsystems/llm-streaming.md` 的适配器契约（adapter contract）章节）。 - 共享辅助函数（`attributionHeaders` / `userAgent`）从包元数据构建应用身份和标准 `User-Agent` 值，适配器无需手动复制版本常量。 - `dsh-llm-deepseek` 在每个请求上发送共享的 `User-Agent`，其 mock 服务器套件断言精确值。 - `dsh-llm-pi-ai` 通过 pi-ai 的 `StreamOptions.headers` 钩子发送相同的 `User-Agent`，其 mock 服务器套件断言精确值。 diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml index 5dbfcf94ef..459ffa188c 100644 --- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.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 .agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md -2026-06-30-bash-stdin-env-trusted-plugin-surface.md: 556d5dd86dfcc92c4628e68c19390f0033560d25 -2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 325e3d303bdb6836c8928fdae00de59fb954ff37 +2026-06-30-bash-stdin-env-trusted-plugin-surface.md: aa0c785be84bcb8a49f8a2670afa0f6bed6277db +2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md: 48108fdd5b8217263590fba336480f1b487e882f diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md index 556d5dd86d..aa0c785be8 100644 --- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md +++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md @@ -30,4 +30,4 @@ Three deliberate choices: ## Consequences -Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model surface remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/core-data-structures/bash.md). +Hook bridges pass JSON payloads and hook-specific variables through the existing bash seam, retaining its process-group, truncation, and spill behavior. The model surface remains unchanged, and the bash tool remains the sole owner of model-call request construction. The vocabulary lives in [the bash data-structure reference](../../../../docs/subsystems/bash.md). diff --git a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md index 325e3d303b..48108fdd5b 100644 --- a/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.zh.md @@ -30,4 +30,4 @@ Status: implemented ## 后果 -钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量，保留其进程组终止、截断和溢出行为。模型接口面不变，bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/core-data-structures/bash.md)。 +钩子桥接层通过既有的 bash seam 传递 JSON 载荷和钩子特定变量，保留其进程组终止、截断和溢出行为。模型接口面不变，bash 工具仍是模型调用请求构建的唯一所有者。相关词汇定义见 [bash 数据结构参考](../../../../docs/subsystems/bash.md)。 diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml index 233164d4e4..c85bb100aa 100644 --- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.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 .agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md -2026-07-15-agent-initiator-scope.md: 69648100e76cfc212469854188d664357fec22f1 -2026-07-15-agent-initiator-scope.zh.md: 505d198ccd2a54af1a15fc1ad6c03b27d217eca0 +2026-07-15-agent-initiator-scope.md: 2f388ae1de3dd6583686e129a03f0cd76701e18d +2026-07-15-agent-initiator-scope.zh.md: 64f70a4d1c3368d5621edb7251d0b567505affc0 diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md index 69648100e7..2f388ae1de 100644 --- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md +++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md @@ -12,7 +12,7 @@ Deep process-local infrastructure sometimes needs a trusted initiating Agent bel ## Decision -The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; a separate private run token records nested boundary lineage only for teardown bookkeeping and carries no identity. The [core-data catalog](../../../../docs/core-data-structures/core.md#initiating-agent) identifies the carried type. +The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; a separate private run token records nested boundary lineage only for teardown bookkeeping and carries no identity. The [core-data catalog](../../../../docs/subsystems/core.md#initiating-agent) identifies the carried type. `currentInitiator()` reads optionally, `requireInitiator()` throws `no initiating agent is active`, and `withInitiator(agent, operation)` preserves the operation's exact synchronous value or Promise. `withoutInitiator(operation)` establishes a clearing boundary for work that must not inherit an Agent. Session remains derived as `agent.session`; turn, step, tool call, `signal`, model, `cwd`, sandbox, and authorization stay with their existing owners. diff --git a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md index 505d198ccd..64f70a4d1c 100644 --- a/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md @@ -12,7 +12,7 @@ harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负 ## 决策 -必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；另一个私有运行标记只记录嵌套边界的谱系，供 teardown 记账使用，不携带身份。[核心数据目录](../../../../docs/core-data-structures/core.md#initiating-agent)标明了所携带的类型。 +必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；另一个私有运行标记只记录嵌套边界的谱系，供 teardown 记账使用，不携带身份。[核心数据目录](../../../../docs/subsystems/core.md#initiating-agent)标明了所携带的类型。 `currentInitiator()` 用于可选读取，`requireInitiator()` 抛出 `no initiating agent is active`，`withInitiator(agent, operation)` 保留操作返回的同步值或 Promise 本身。`withoutInitiator(operation)` 会建立清空边界，供不得继承 Agent 的工作使用。会话仍通过 `agent.session` 推导；轮次、步骤、工具调用、`signal`、模型、`cwd`、沙箱和授权继续由现有归属方管理。 diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml b/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml index 3be447fe2f..8481cc20d5 100644 --- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.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 .agents/notes/implemented/feature/2026-06-30-interception-seams.md -2026-06-30-interception-seams.md: c318e41cfb1d64230b6151f1febad85d75b1451d -2026-06-30-interception-seams.zh.md: 1b274fae4bc7fde326dbb0eeec54d57f73987803 +2026-06-30-interception-seams.md: 3b2c62cd4413f6d93cef247c51304a8d46753218 +2026-06-30-interception-seams.zh.md: 4e7b6a5ac9ca88919246508cf86c486b06888417 diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.md index c318e41cfb..3b2c62cd44 100644 --- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.md +++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.md @@ -56,4 +56,4 @@ The seam package does **not** declare `hook/*` session events (the durable hook- ## Consequences -The canonical interception surface is uniformly typed without giving every extension the same power: hooks return decisions, execution wrappers wrap, terminal guards only deny, and final observers only observe. The loop owns session-start, pre-step claim settlement, post-tool context buffering, and stopping; `dsh-tools` owns identity sealing and the five-phase execution pipeline. Their contracts are documented in [architecture.md](../../../../docs/architecture.md), package READMEs, [core interception decisions](../../../../docs/core-data-structures/core.md#interception-decisions), and [tool structures](../../../../docs/core-data-structures/tools.md). The ACP bridge settles an initial pre-step rejection from its blocked no-step turn as `end_turn`, while hook-driven snapshots verify the observable bridge behavior end to end. +The canonical interception surface is uniformly typed without giving every extension the same power: hooks return decisions, execution wrappers wrap, terminal guards only deny, and final observers only observe. The loop owns session-start, pre-step claim settlement, post-tool context buffering, and stopping; `dsh-tools` owns identity sealing and the five-phase execution pipeline. Their contracts are documented in [architecture.md](../../../../docs/architecture.md), package READMEs, [core interception decisions](../../../../docs/subsystems/core.md#interception-decisions), and [tool structures](../../../../docs/subsystems/tools.md). The ACP bridge settles an initial pre-step rejection from its blocked no-step turn as `end_turn`, while hook-driven snapshots verify the observable bridge behavior end to end. diff --git a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md index 1b274fae4b..4e7b6a5ac9 100644 --- a/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md +++ b/.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md @@ -56,4 +56,4 @@ seam 包**不**声明 `hook/*` 会话事件（持久的钩子调用日志）； ## 后果 -规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/core-data-structures/core.md#interception-decisions) 与[工具结构](../../../../docs/core-data-structures/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。 +规范拦截表面具有统一的类型化，同时不给每个扩展相同的权力：钩子返回 decision，执行包装层做包装，终结 guard 只能拒绝，最终观测者只能观测。循环负责 session-start、pre-step 领取结算、工具执行后上下文缓冲和 stopping；`dsh-tools` 负责身份封存与五阶段执行流水线。它们的契约记录在 [architecture.md](../../../../docs/architecture.md)、各包 README、[核心拦截 decision](../../../../docs/subsystems/core.md#interception-decisions) 与[工具结构](../../../../docs/subsystems/tools.md)中。ACP 桥接会把 blocked 无步骤轮次中的首次 pre-step reject 结算为 `end_turn`，而钩子驱动的快照端到端验证可观测的桥接行为。 diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml index 15054d6ba1..394af669cd 100644 --- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.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 .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md -2026-07-05-dynamic-workflows.md: bba62098c66477a3f1929f9029e81c645bfc4d41 -2026-07-05-dynamic-workflows.zh.md: 2005ca14883ae137148541273900c7f3e65769a5 +2026-07-05-dynamic-workflows.md: b0fb2349e64093beab8220ea75715b55903772e3 +2026-07-05-dynamic-workflows.zh.md: 246727649be8acc17dac1335d353e9b1591e3890 diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md index bba62098c6..b0fb2349e6 100644 --- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md +++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md @@ -20,7 +20,7 @@ One deliberate strictness DIVERGENCE from CC: hook misuse — unknown or deferre ### The seam (dsh-workflow) -`ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [core-data-structures/workflow.md](../../../../docs/core-data-structures/workflow.md). +`ctx.workflows` is an abstract `WorkflowService` in the bash shape — one engine per context, no named-provider registry (engines are deployment swaps, not co-residents). `start(request)` throws synchronously for a script that cannot begin; a returned `WorkflowRun`'s `result` NEVER rejects (failures resolve as `stopReason: 'error' | 'cancelled'`). The `workflow/*` events are observe-only emits carrying DATA SNAPSHOTS (id + meta; `workflow/end` omits the result value), per-listener contained, mirroring `subagent/start`/`subagent/end` — control stays with the run's holder. Vocabulary details: [subsystems/workflow.md](../../../../docs/subsystems/workflow.md). ### The engine (dsh-workflow-workerthread): one worker thread per run diff --git a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md index 2005ca1488..246727649b 100644 --- a/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md +++ b/.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md @@ -20,7 +20,7 @@ harness 可以将一个任务委派给一个子 agent（`dsh-tool-subagent`） ### seam（dsh-workflow） -`ctx.workflows` 是 bash 形态的抽象 `WorkflowService`——每个上下文一个引擎，无命名提供方注册表（引擎是部署级替换，不是共存者）。`start(request)` 对无法启动的脚本同步抛出；返回的 `WorkflowRun` 的 `result` 永不 reject（失败时结算为 `stopReason: 'error' | 'cancelled'`）。`workflow/*` 事件是仅观察的 emit，携带数据快照（id + meta；`workflow/end` 省略 result 值），按监听器隔离，与 `subagent/start`/`subagent/end` 对称——控制权留在 run 的持有者手中。词汇详情见 [core-data-structures/workflow.md](../../../../docs/core-data-structures/workflow.md)。 +`ctx.workflows` 是 bash 形态的抽象 `WorkflowService`——每个上下文一个引擎，无命名提供方注册表（引擎是部署级替换，不是共存者）。`start(request)` 对无法启动的脚本同步抛出；返回的 `WorkflowRun` 的 `result` 永不 reject（失败时结算为 `stopReason: 'error' | 'cancelled'`）。`workflow/*` 事件是仅观察的 emit，携带数据快照（id + meta；`workflow/end` 省略 result 值），按监听器隔离，与 `subagent/start`/`subagent/end` 对称——控制权留在 run 的持有者手中。词汇详情见 [subsystems/workflow.md](../../../../docs/subsystems/workflow.md)。 ### 引擎（dsh-workflow-workerthread）：每次运行一个 worker 线程 diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml b/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml index a98beff699..6fff14bc85 100644 --- a/.agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.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 .agents/notes/implemented/feature/2026-07-05-skill-system.md -2026-07-05-skill-system.md: a998d70ec934aed4bf7ce32aa711abd47b508a1d -2026-07-05-skill-system.zh.md: 4fa7c4fd657c2f41f16b30679ec95e61a75f8a0c +2026-07-05-skill-system.md: bb7c03a64a3d0d0f700e21bc96633f1c3ea181b9 +2026-07-05-skill-system.zh.md: 8e26e52d3366505a958dd4b19461edf8bf740b00 diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.md index a998d70ec9..bb7c03a64a 100644 --- a/.agents/notes/implemented/feature/2026-07-05-skill-system.md +++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.md @@ -28,7 +28,7 @@ Local skill filesystem I/O goes through `ctx.fs` when a filesystem service is lo The registry's `list()` returns every winning summary, while model and user consumers apply the invocation predicates owned by the [independent invocation-policy decision](2026-07-28-skill-invocation-policy.md). The `skill({ name })` tool loads one model-invocable skill for the current agent cwd and returns a tool result containing ``, ``, and ``. `resourceBase` supplies a directory, URL, or opaque provider-managed base for explicitly referenced scripts, references, and assets; resources load only as needed, without directory enumeration. An unresolved name reports that the skill is unknown or no longer available; invalid names and skills with `invocation.modelInvocable: false` retain distinct tool errors. The tool result is the model-visible disclosure path. -The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/core-data-structures/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md). +The data structures and catalog/tool contract are documented in [skills.md](../../../../docs/subsystems/skills.md), with service signatures in the generated [services catalog](../../../../docs/cordis-catalog/services.md). ## Alternatives considered diff --git a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md index 4fa7c4fd65..8e26e52d33 100644 --- a/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md +++ b/.agents/notes/implemented/feature/2026-07-05-skill-system.zh.md @@ -28,7 +28,7 @@ DeepSeek Harness 使用同一原语，使项目特定的评审、插件编写和 注册表的 `list()` 返回全部胜出摘要，而模型与用户消费方应用[独立调用策略决策](2026-07-28-skill-invocation-policy.md)定义的调用判定。`skill({ name })` 工具为当前 agent cwd 加载一个模型可调用的 skill，返回包含 ``、`` 和 `` 的工具结果。`resourceBase` 提供一个目录、URL 或不透明的提供方管理的基路径，用于显式引用的脚本、参考资料和资产；资源仅按需加载，不进行目录枚举。无法解析的名称报告该 skill 未知或不再可用；无效名称和 `invocation.modelInvocable` 为 `false` 的 skill 保留不同的工具错误。工具结果是面向模型的可见披露路径。 -数据结构与目录/工具契约记录在 [skills.md](../../../../docs/core-data-structures/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。 +数据结构与目录/工具契约记录在 [skills.md](../../../../docs/subsystems/skills.md) 中，服务签名见生成的[服务目录](../../../../docs/cordis-catalog/services.md)。 ## 曾考虑的替代方案 diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml b/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml index 7294f47357..00f475040c 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.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 .agents/notes/implemented/feature/2026-07-06-sandbox.md -2026-07-06-sandbox.md: 583b388815cd9b2b9cf94ce393839169ce3ffac3 -2026-07-06-sandbox.zh.md: e435b671a42ca5c3ea4f6800bf91d6e006da35d3 +2026-07-06-sandbox.md: 06c5590454a6947030d828f087b92f44207dad6e +2026-07-06-sandbox.zh.md: 8f575e3cd14973aaaaf9254337b985110bc99d6b diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.md index 583b388815..06c5590454 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.md +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.md @@ -200,7 +200,7 @@ Costs and accepted limits: In-repo precedents this design copies or contrasts with: - [The capability-seams Agent Note](../architecture/2026-06-13-capability-seams.md) — the interface/implementation/consumer split and the "don't split preemptively" timing rule the second consumer satisfied. -- The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/core-data-structures/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention. +- The `dsh-bash` request/spec split ([the bash vocabulary catalog](../../../../docs/subsystems/bash.md)) — the complete `sandboxPolicy` rides its per-call carrier, and the explicit-`resolve()` defaulting convention. - [The approval seam Agent Note](2026-07-06-approval-seam.md) — the channel escalation asks through; its answerer waterfall, audit pair, and one-package rationale are recorded there. - [Event-sourced sessions](../architecture/2026-06-11-event-sourced-sessions.md) and [standalone log-only events](../simplification/2026-07-28-remove-synthetic-log-only-turns.md) — the log-as-store foundation the per-session modes fold over, and the explicit durability boundary the anchoring design obeys. - [The interception-seams Agent Note](2026-06-30-interception-seams.md) — the `tools/pre-execute` vocabulary the escalation gate deliberately does not reuse (an escalating call has no pre-execute moment of its own). diff --git a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md index e435b671a4..8f575e3cd1 100644 --- a/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md +++ b/.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md @@ -200,7 +200,7 @@ fs/web/todo 在进程内执行，因此它们的沙箱语义是各自 seam 层 本设计复制或对比的仓库内先例： - [能力 seam Agent Note](../architecture/2026-06-13-capability-seams.md)——接口/实现/消费方拆分与「不要过早拆分」的时机规则（第二个消费方满足了该规则）。 -- `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/core-data-structures/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。 +- `dsh-bash` 的 request/spec 拆分（[bash 词汇目录](../../../../docs/subsystems/bash.md)）——完整的 `sandboxPolicy` 搭载其按调用载体，以及显式 `resolve()` 默认约定。 - [批准 seam Agent Note](2026-07-06-approval-seam.md)——升级请求通过的通道；其应答器 waterfall（瀑布式事件）、审计对和单包理由记录在那里。 - [事件溯源会话](../architecture/2026-06-11-event-sourced-sessions.md)与[独立纯日志事件](../simplification/2026-07-28-remove-synthetic-log-only-turns.md)——按会话模式 fold 所依赖的日志即存储基础，以及锚定设计遵守的显式持久性边界。 - [拦截 seam Agent Note](2026-06-30-interception-seams.md)——`tools/pre-execute` 词汇，升级门控刻意不复用它（升级调用没有自己的 pre-execute 时刻）。 diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml index 3119d28d71..6462a2c873 100644 --- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.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 .agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md -2026-07-10-parallel-tool-call-execution.md: 19f5dc189821433052edfa72613980a2e94e2cae -2026-07-10-parallel-tool-call-execution.zh.md: 69bff90c11fa132ded325ef610dabf5c609f21af +2026-07-10-parallel-tool-call-execution.md: 7fd540539fd358b3254470f420a0cc11f2927d45 +2026-07-10-parallel-tool-call-execution.zh.md: 985557974c79d4080c4e35ccbb9740439988261a diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md index 19f5dc1898..7fd540539f 100644 --- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md +++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md @@ -14,7 +14,7 @@ The session log remains authoritative: every started call has an audit event, or ## Decision -Each tool may provide an optional `isConcurrencySafe(args)` classifier. It is synchronous and pure: it examines only the current call's parsed arguments and performs no I/O or mutation. Only an explicit `true` opts in; a missing classifier, invalid arguments, a thrown classifier, or any other return value makes the call exclusive. The canonical type contract lives in the [tool data structures](../../../../docs/core-data-structures/tools.md). +Each tool may provide an optional `isConcurrencySafe(args)` classifier. It is synchronous and pure: it examines only the current call's parsed arguments and performs no I/O or mutation. Only an explicit `true` opts in; a missing classifier, invalid arguments, a thrown classifier, or any other return value makes the call exclusive. The canonical type contract lives in the [tool data structures](../../../../docs/subsystems/tools.md). The classifier is deliberately unary. Returning `true` is the tool's promise that this call may overlap with any sibling call that also returns `true`; the scheduler does not compare calls or prove that their resource accesses are compatible. diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md index 69bff90c11..985557974c 100644 --- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md +++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md @@ -14,7 +14,7 @@ Status: implemented ## 决策 -每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/core-data-structures/tools.md)。 +每个工具都可以提供可选的 `isConcurrencySafe(args)` 分类器。该分类器必须是同步纯函数：它只检查当前调用已解析的参数，不执行 I/O 或任何变更。只有显式返回 `true` 才表示选择并行；分类器缺失、参数无效、分类器抛错或返回任何其他值，都会使该调用按独占方式执行。规范类型契约见[工具数据结构](../../../../docs/subsystems/tools.md)。 分类器有意设计为一元函数。返回 `true` 表示工具承诺：此调用可以与任何同样返回 `true` 的并列调用重叠执行。调度器不会比较调用，也不会证明它们的资源访问相容。 diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml index 66ac99d37c..e6ca4048fd 100644 --- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.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 .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md -2026-07-31-code-mode-language-dispatch.md: 96001252d6494d058a8df9974fb5a0d59e7d7112 -2026-07-31-code-mode-language-dispatch.zh.md: aa7eb2a6b4b9117f1d707b37afcdbe12b814bad2 +2026-07-31-code-mode-language-dispatch.md: 71e4fd5a30e90ac66132dbdcea16917bacc80b68 +2026-07-31-code-mode-language-dispatch.zh.md: 1dbb3d889d28669575980d3a667e4f168a5d72db diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md index 96001252d6..71e4fd5a30 100644 --- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md +++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.md @@ -17,7 +17,7 @@ Language selection is a lookup on `ctx.codeRuntime.language`, resolved lazily at - `SDK_RENDERERS` (index.ts) maps a language to its `tools:sdk` renderer — `typescript → renderToolsSdk`, `python → renderToolsSdkPy`. The `tools:sdk` section reads the loaded runtime's language and picks the renderer; `requireCodeRuntime` rejects a `mode: code`/`both` runtime whose language is absent from the table, naming the known languages. - `RUN_CODE_FLAVORS` (code-mode.ts) maps a language to its two model-facing `run_code` strings (tool `description` and the `code` parameter description), so a language's SDK section and its transport schema always agree. -Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/core-data-structures/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change. +Both tables are read with `Object.hasOwn` before use so a language named `toString`/`constructor` cannot resolve an inherited `Object.prototype` member as a renderer. The two guards differ in reachability: `SDK_RENDERERS`' in-callback guard is unreachable because `requireCodeRuntime` validated the same `const` table earlier in the same callback (it carries a `/* v8 ignore */`), while `RUN_CODE_FLAVORS`' guard is the primary, publicly reachable rejection — any language absent from the flavor table hits it through `run_code`'s language-aware getters, which the public `schemas()` reaches without passing `requireCodeRuntime` first; the test reads one of those getters off the definition directly, under a language absent from both tables. A language present in `SDK_RENDERERS` but not `RUN_CODE_FLAVORS` is drift the shared `CodeSdkLanguage` `satisfies` pins reject at `typecheck`, so it is not an input either guard can see; what the guards still own is a mounted runtime reporting a language absent from both tables. Schema emission reads the runtime through `peekRuntime()` rather than `requireRuntime()`: `undefined` (no runtime mounted, reached by definition readers and `schemas()`, of which the doc-catalog harvest is the only shipped one and none of which feeds a model because assembly passes `requireCodeRuntime` first) degrades to the TypeScript flavor, whereas a mounted unknown language fails loud — this is NOT the silent fallback rejected below, which concerns emitting a wrong-language SDK for a real runtime. Adding a backend language is three parallel edits — a `CodeSdkLanguage` member and the two table entries — plus its renderer and the prose that names the well-known values instead of deriving them (the seam's `dsh-code-runtime` README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair; this package's own README pair and its `Config.mode` JSDoc — no gate checks any of it), with no `agent-loop` or registry-structure change. `code-mode.ts` depends only on the runtime seam (`@deepseek-ai/dsh-code-runtime`), never on a concrete backend; dispatch is by `runtime.language` at run time. The tool layer therefore lands independently of the protocol and backend PRs — it needs only the seam's `language` field, which is already on master. @@ -37,7 +37,7 @@ The standard that cap serves is grammatical validity, and the boundary is delibe ## Consequences -Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/core-data-structures/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend. +Adding a backend language is three parallel edits — a `CodeSdkLanguage` member, an `SDK_RENDERERS` entry, and a `RUN_CODE_FLAVORS` entry — plus the renderer function the second points at, with no change to `agent-loop` or the registry structure. The two tables (`SDK_RENDERERS`, `RUN_CODE_FLAVORS`) must stay in step, and that invariant is checked statically rather than left to review: both are `satisfies`-checked against that one union, so a language added to one and not the other fails `typecheck`. This is the mechanical form the drift risk deserves — the runtime `Object.hasOwn` guards would catch it too, but only once a backend reporting that language ships: one PR after the drift, at the consumer's integration point rather than where it was introduced, and on this base never, since no second backend exists. The tables keep their `Record` declared type because `CodeRuntime.language` is an unconstrained `string`; the union pins what the harness ships, the guards reject what a runtime reports. What stays outside that check is the prose that names the well-known values instead of deriving them: `dsh-code-runtime`'s README pair, its `CodeRuntime.language` JSDoc, and the `docs/subsystems/code-runtime.md` pair at the seam, plus this package's own README pair and its `Config.mode` JSDoc. Earlier notes name the values as the state at their own PR and are not on that list. Two separate reasons keep it ungated. Prose is not type-checked at all, wherever the union lives. And no type-level pin can stand in for it here: the interface package must not import its consumer's table, and `CodeRuntime.language` stays an unconstrained `string` by design, so moving the union into the seam would not apply it either. A unit test pinning the two key sets equal was rejected in favor of this: it would buy the same check at the cost of a test-only export of two private tables, and would run later than the compiler does. Which of the two runtime failures surfaces depends on the entry point, for a language absent from both tables: assembly reports the missing renderer, because `wireSchemas` calls `requireCodeRuntime` before projecting, while the public `schemas()` reaches `run_code`'s language-aware getters first and reports the missing flavor. The tool layer stays free of any concrete backend dependency, so it lands and is testable on master ahead of the Python protocol and backend. The cost is that the Python branch of both tables is unreachable on this base: `CodeRuntime.language` is set by the loaded backend, the only published backend is `dsh-code-runtime-worker` (`'typescript'`), and the registry reads the loaded runtime rather than a config field, so no assembled application can select `renderToolsSdkPy` or `PYTHON_FLAVOR`. The model-visible surface is therefore unchanged by this note's work until a backend reporting `'python'` is published, and this PR's coverage is unit-level — the renderer output plus the dispatch and rejection paths. The keyless snapshot for the Python model interface belongs to the PR that publishes that backend, because only there does a real `cordis.yml` over published plugins produce a Python assembly; a snapshot example that mounted a fixture runtime here would assert against a test double, which [docs/testing.md](../../../../docs/testing.md) rejects as a substitute for the assembled application transcript. diff --git a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md index aa7eb2a6b4..1dbb3d889d 100644 --- a/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md +++ b/.agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md @@ -17,7 +17,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd - `SDK_RENDERERS`（index.ts）把语言映射到它的 `tools:sdk` 渲染器——`typescript → renderToolsSdk`、`python → renderToolsSdkPy`。`tools:sdk` 段读取所加载运行时的语言并选出渲染器；`requireCodeRuntime` 拒绝其语言不在表中的 `mode: code`/`both` 运行时，并列出已知语言。 - `RUN_CODE_FLAVORS`（code-mode.ts）把语言映射到它那两条面向模型的 `run_code` 字符串（工具 `description` 与 `code` 参数描述），使一种语言的 SDK 段与它的传输 schema 始终一致。 -两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/core-data-structures/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。 +两张表在使用前都以 `Object.hasOwn` 读取，这样名为 `toString`/`constructor` 的语言不会把继承自 `Object.prototype` 的成员解析成渲染器。两个守卫的可达性不同：`SDK_RENDERERS` 的段内守卫不可达，因为 `requireCodeRuntime` 已在同一回调更早处校验过同一张 `const` 表（它带 `/* v8 ignore */`）；而 `RUN_CODE_FLAVORS` 的守卫是主要的、可公开到达的拒绝路径——任何缺席 flavor 表的语言都经 `run_code` 的语言感知 getter 到达它，而公共 `schemas()` 抵达那些 getter 时并未先过 `requireCodeRuntime`；测试直读 definition 上的其中一个 getter，用的是对两张表都缺席的语言。「在 `SDK_RENDERERS` 里却不在 `RUN_CODE_FLAVORS` 里」这种漂移已由共享的 `CodeSdkLanguage` `satisfies` 在 `typecheck` 处拒绝，两个守卫都看不到这种输入；它们如今负责的是所挂载运行时报告了一门两张表都缺席的语言。schema 发射通过 `peekRuntime()` 而非 `requireRuntime()` 读取运行时：`undefined`（无运行时，由直读 definition 的读者与 `schemas()` 到达，其中 doc-catalog 采集是唯一已交付的一个，而它们都不会喂给模型，因为组装路径先过 `requireCodeRuntime`）降级到 TypeScript flavor，而挂载了未知语言则 fail loud——这不是下方被否决的静默回退，那指的是为真实运行时发出错误语言的 SDK。新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员加两条表项——再加它的渲染器，以及点名已知值而非从中派生的散文（seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对；本包自己的 README 双语对与它的 `Config.mode` JSDoc，无任何 gate 检查其中任何一处），不动 `agent-loop`，也不动注册表结构。 `code-mode.ts` 只依赖运行时 seam（`@deepseek-ai/dsh-code-runtime`），绝不依赖具体后端；分发在运行时按 `runtime.language` 进行。因此工具层独立于协议和后端 PR 落地——它只需要 seam 的 `language` 字段，而该字段已在 master 上。 @@ -37,7 +37,7 @@ Code Mode 只生成一种 SDK 形态：TypeScript。`ToolRegistry` 为 `tools:sd ## Consequences -新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/core-data-structures/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。 +新增一门后端语言是三处并列编辑——一个 `CodeSdkLanguage` 成员、一个 `SDK_RENDERERS` 表项、一个 `RUN_CODE_FLAVORS` 表项——再加第二处所指向的渲染器函数，不动 `agent-loop`，也不动注册表结构。两张表（`SDK_RENDERERS`、`RUN_CODE_FLAVORS`）必须同步，且这条不变式由静态检查把关，而非交给 review：两张表都以 `satisfies` 对上述同一个 union 校验，因此只加其一而漏掉另一会在 `typecheck` 处失败。这正是该漂移风险应有的机械形式——运行期的 `Object.hasOwn` 守卫同样能捕获，但要等到有后端报告该语言之后：晚于漂移引入一个 PR，且触发点在消费方的集成处而非漂移引入处；在当前 base 上则永远不会触发，因为不存在第二个后端。两张表的声明类型仍是 `Record`，因为 `CodeRuntime.language` 是不受约束的 `string`：union 钉住本仓库交付了什么，守卫拒绝运行时报告了什么。落在这条检查之外的是点名已知值而非从中派生的散文：seam 侧的 `dsh-code-runtime` README 双语对、它的 `CodeRuntime.language` JSDoc 与 `docs/subsystems/code-runtime.md` 双语对，再加本包自己的 README 双语对与它的 `Config.mode` JSDoc。更早的 note 点名这些值时记的是其自身 PR 当时的状态，不在此列。让它无 gate 的是两条独立理由。其一，散文根本不受类型检查，union 放在哪里都一样。其二，类型级替代在这里也不可用：接口包不得 import 其消费方的表，而 `CodeRuntime.language` 按设计保持不受约束的 `string`，即便把 union 迁进 seam 也不会作用到它。用一个断言两张表键集相等的 unit test 的方案被否决：它买到的是同一条检查，代价却是把两张私有表做测试专用导出，且运行时机晚于编译器。对两张表都缺席的语言，两种运行期失败中报出哪一条随入口而异：组装路径报缺渲染器，因为 `wireSchemas` 在投影前先调 `requireCodeRuntime`；而公共 `schemas()` 先经过 `run_code` 的语言感知 getter，报的是缺 flavor 表项。工具层不依赖任何具体后端，因此它能先于 Python 协议和后端在 master 上落地并可测。 代价是两张表的 Python 分支在当前 base 上不可达：`CodeRuntime.language` 由所加载的后端设定，已发布的后端只有 `dsh-code-runtime-worker`（`'typescript'`），而注册表读取的是所加载的运行时而非某个配置字段，因此没有任何一份组装好的应用能选中 `renderToolsSdkPy` 或 `PYTHON_FLAVOR`。也就是说，在报告 `'python'` 的后端发布之前，本 note 的工作不改变模型可见表面，本 PR 的覆盖因此是 unit 级——渲染器输出加分发与拒绝路径。Python 模型界面的 keyless snapshot 归属于发布该后端的那个 PR，因为只有在那里，一份基于已发布插件的真实 `cordis.yml` 才会产出 Python 组装；在此处挂载 fixture 运行时的快照示例断言的是测试替身，而 [docs/testing.md](../../../../docs/testing.md) 明确拒绝以此替代组装好的应用 transcript。 diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml index 4acabc8700..13c54fa458 100644 --- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.i18n.yaml +++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.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 .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md -2026-06-20-core-data-structures-catalog.md: 7ee1e0ac3df7cb37fc9797702d44f409da820a94 -2026-06-20-core-data-structures-catalog.zh.md: 7cb0ae216f5c5f429c18d097862350997a8335d3 +2026-06-20-core-data-structures-catalog.md: 57433fdcb3c77976c4ba0cfe7d157f94dff331dd +2026-06-20-core-data-structures-catalog.zh.md: 3956839c8211e294280805d9b6993e5607bfe04f diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md index 7ee1e0ac3d..57433fdcb3 100644 --- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md +++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md @@ -1,4 +1,4 @@ -# Agent Note: Core-data-structures catalog and the `ts type-equiv` drift gate +# Agent Note: Subsystems catalog and the `ts type-equiv` drift gate Status: implemented @@ -12,7 +12,7 @@ So the work had two intertwined questions: **what belongs in such a catalog** (t ## Decision -A new `docs/core-data-structures/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source. +A new `docs/subsystems/` folder catalogs the vocabulary, with a new `verify-type-equiv` doc-sync gate that keeps every pasted type declaration and its JSDoc synchronized with source. ### What counts as "core" — the spine-vs-seam line diff --git a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md index 7cb0ae216f..3956839c82 100644 --- a/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md +++ b/.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.zh.md @@ -12,7 +12,7 @@ Status: implemented ## 决策 -新增的 `docs/core-data-structures/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。 +新增的 `docs/subsystems/` 目录对这些词汇编目，并配有新的 `verify-type-equiv` doc-sync（文档同步门禁），使每个粘贴的类型声明及其 JSDoc 与源码保持同步。 ### 何为「核心」——主干与 seam 的分界线 diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml index 70d56bbca5..5ef82c77de 100644 --- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.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 .agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md -2026-06-22-fork-child-replay-seed-boundary.md: ed3ec095bc14128f5ebc0a9188bc022ef97b1c8b -2026-06-22-fork-child-replay-seed-boundary.zh.md: 1d938cbf6c9c32a144d58fed48e552d85aa9c625 +2026-06-22-fork-child-replay-seed-boundary.md: 27db3b768f2503121b0bc8912f9bc0fecb00a10d +2026-06-22-fork-child-replay-seed-boundary.zh.md: f64fc55fc63e2caa4b50112407b645e6e7f12b0f diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md index ed3ec095bc..27db3b768f 100644 --- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md +++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md @@ -44,6 +44,6 @@ This closes the routing correctness gap, and two recorded fork scenarios exercis ## Consequences -- A new persisted header field across core + both backends; the core-data-structures catalog (`persistence.md`) is updated in the same change (its `SessionHeader` / `CreateSessionOptions` `type-equiv` blocks). +- A new persisted header field across core + both backends; the subsystems catalog (`persistence.md`) is updated in the same change (its `SessionHeader` / `CreateSessionOptions` `type-equiv` blocks). - Existing SQLite databases at schema v2 are rejected on open (no user data pre-release). - Spawn replay is unchanged (`seedLength` 0). Fork replay now routes a child to its own script; covered by a regression in `llm-replay`'s tests (a child fixture whose seeded prefix carries a parent chunk — the derived child script must exclude it, proven red without the slice) and a persistence round-trip test (both backends, via the shared coordinator contract). diff --git a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md index 1d938cbf6c..f64fc55fc6 100644 --- a/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md +++ b/.agents/notes/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.zh.md @@ -44,6 +44,6 @@ subagent 脚本由 [`deriveReplayScript`](../../../../packages/support/llm-repla ## 后果 -- core 与两个后端新增一个持久化 header 字段；核心数据结构目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。 +- core 与两个后端新增一个持久化 header 字段；子系统目录（`persistence.md`）在同一变更中更新（其 `SessionHeader` / `CreateSessionOptions` 的 `type-equiv` 块）。 - 既有的 schema v2 SQLite 数据库在打开时被拒绝（预发布阶段无用户数据）。 - spawn 回放不变（`seedLength` 为 0）。fork 回放现在将子会话路由到自身的脚本；由 `llm-replay` 测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的分片——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 契约）。 diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md index f933beb86b..81f63fac2f 100644 --- a/.agents/skills/dsh-code-review/SKILL.md +++ b/.agents/skills/dsh-code-review/SKILL.md @@ -21,7 +21,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo — 1. **New prose receives semantic review.** Use [dsh-prose-standard](../dsh-prose-standard/SKILL.md) to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties. 2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home. -3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry. +3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [subsystems](../../../docs/subsystems/core.md) page and any `type-equiv` entry. Internal types need no catalog entry. 4. **Registrations clean up.** Verify each new registry contribution satisfies the disposal-test contract in [packages/AGENTS.md](../../../packages/AGENTS.md). 5. **Invariant companions are semantic.** For every touched `./invariant`, require an owner event-stream or mutable-data relationship at its authoritative boundary; service or method presence, plugin metadata or effects, and fixed pure examples belong in type, load, or unit tests. Accept an empty installer when its package-specific reason establishes that no plausible runtime relationship exists; do not demand an invented check merely to eliminate emptiness ([repository rule](../../../AGENTS.md#conventions); [package contract](../../../packages/AGENTS.md)). 6. **Required evidence exists.** Verify the author ran the [relevant local checks](../../../AGENTS.md#run-relevant-checks-locally) for the diff and that CI covers the exhaustive matrix; review the semantic gaps neither can detect. diff --git a/docs/AGENTS.md b/docs/AGENTS.md index cd4e8aaaa5..3bbd4f330d 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -21,7 +21,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home. | Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home | | Subtree `AGENTS.md` (`packages/`, `examples/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries | | [architecture.md](architecture.md) | The system map: services, the loop, extension seams — read before changing `packages/` | Type shapes (→ core-data-structures), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations | -| [core-data-structures/](core-data-structures/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) | +| [subsystems/](subsystems/core.md) | The type catalog: literal shapes and semantics of the spine and seam vocabulary | Behavior narration (→ architecture.md) | | [Agent Notes](../.agents/notes/README.md) | Decision records under their own lifecycle contract | Migration plans, checklists, and spec-speak once implemented; archived notes are frozen history | | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — | | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) | @@ -37,7 +37,7 @@ Each fact has one home: the tier whose job it is. Elsewhere, link to that home. - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)). - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit. - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)). -- **The [core-data-structures catalog](core-data-structures/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](core-data-structures/core.md#what-counts-as-core)). +- **The [core-data-structures catalog](subsystems/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](subsystems/core.md#what-counts-as-core)). - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)). - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, timing, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details. - Your audience is professional programmers. Prefer concise and straight-forward English over metaphor. Do not overuse words like "gate", "vocabulary", "surface", "seams". diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 76491a37fe..15a6ba3fb5 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: cee159452fc536c98a006cfa3ea92e9d21a1e77b -architecture.zh.md: cf10e60a5d5e4fe3f39d72bef3d48fe7c2f3c105 +architecture.md: 7baf550128fe83528ce12bf2f9b40cfc8f78e322 +architecture.zh.md: 076edd0549fb7f648a7a1b06d7027a1e6eca735f diff --git a/docs/architecture.md b/docs/architecture.md index cee159452f..7baf550128 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -123,7 +123,7 @@ Adapter selection, dispatch, and iteration failures become terminal error or abo Other failures use `agent/error`; cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` reports its cause before clearing and aborting; idle calls emit nothing. Waking input that lands after the abort fires but before convergence runs at the driver's convergence boundary, while a `disposed` cancel leaves it parked ([cancel-convergence wake latch](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)). Durability distinguishes `aborted` cancellation from `disposed` teardown, which awaits quiescence ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)). -Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap). +Turn and step events are turn-enclosed; the loop appends `user/message` events only from entered batches inside a turn. A turn opens before the initial claim and pre-step, so rejection, empty input, cancellation, or failure closes a durable turn without any step events. Standalone `compact/* { turn: null }` events consume no turn, and their lock-time markers may interleave with inbox splices. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap). ### Agent Handles @@ -147,9 +147,9 @@ Between turns, owners append log-only events through `Session`, flushing only fo ### Model Content -Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](core-data-structures/token-meter.md). +Messages use typed blocks from merge-extensible `ContentBlockMap`; the pattern also types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New blocks coordinate adapters, UI, compaction, token metering, and persistence; replay measurements live in [token-meter.md](subsystems/token-meter.md). -Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](core-data-structures/llm-streaming.md)). +Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is one provider attempt; adapters report normalized failure facts, and a handling `agent/request-error` plugin returns a retry action. The loop logs chunks, successful provenance, and replay state. Remote adapters use per-read idle watchdogs. Replay crosses routes only through a shared adapter instance ([contract](subsystems/llm-streaming.md)). ## Extension And Composition @@ -157,7 +157,7 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on Capabilities separate **interface / implementation / consumer** layers. Filesystem and subprocess providers define one execution world; Bash, PTY, and LSP run there without provider forks. See the [capability graph](capability-seams.md). -Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](core-data-structures/subagent.md)). +Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](subsystems/subagent.md)). `dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. When compaction removes that baseline from the visible surface, the next entering pre-step composes the current baseline and carries it in the same request. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)). `dsh-paths` owns shared paths. diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index cf10e60a5d..076edd0549 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -123,7 +123,7 @@ idle inject: 其他故障使用 `agent/error`；取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消功能准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 会在清空队列和中止前报告原因；空闲调用不发事件。abort 触发后、收敛前到达的唤醒输入会在 driver 的收敛边界执行，而 `disposed` 取消则将其停放（[取消收敛窗口唤醒锁存](../.agents/notes/implemented/bug-fix/2026-08-07-cancel-convergence-wake-latch.md)）。持久化层以 `aborted` 区分取消，以 `disposed` 区分会等待完全停稳的拆卸（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。 -轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。 +轮次和步骤事件均位于轮次边界内；loop 只会在轮次内从进入步骤的批次追加 `user/message`。轮次会在首次领取与 pre-step 之前打开，因此拒绝、空输入、取消或失败会关闭一个不包含任何步骤事件的持久轮次。独立的 `compact/* { turn: null }` 事件不占用轮次，其锁定时刻标记可以与 inbox splice 交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](subsystems/session.md#why-a-turn-ended-turnendreasonmap)。 ### Agent 句柄 @@ -147,9 +147,9 @@ idle inject: ### 模型内容 -消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](core-data-structures/token-meter.md)。 +消息使用从可合并扩展的 `ContentBlockMap` 派生的类型化块；同一模式也为 `MessageSource`、`FinishReason`、`TurnTrigger` 和 `TurnEndReason` 定义类型。新增块会协调适配器、UI、压缩、token 计量和持久化；回放计量见 [token-meter.md](subsystems/token-meter.md)。 -流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](core-data-structures/llm-streaming.md)）。 +流式输出使用原始分片和 `BlockAssembler`。每次 `LlmAdapter.stream()` 调用代表一次提供方尝试；适配器报告标准化的故障事实，负责处理的 `agent/request-error` 插件会返回重试动作。循环会记录分片、成功结果的来源信息和回放状态。远程适配器使用逐次读取空闲看门狗。回放仅通过共用的适配器实例跨路由传递（[契约](subsystems/llm-streaming.md)）。 ## 扩展与组合 @@ -157,7 +157,7 @@ idle inject: 能力分为**接口／实现／消费方**三层。文件系统与进程管理提供方共同定义一个执行世界；Bash、PTY 和 LSP 都在其中运行，无需提供方专用 fork。参见[功能图](capability-seams.md)。 -例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](core-data-structures/subagent.md)）。 +例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](subsystems/subagent.md)）。 `dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 254d85ccd1..850f4731e2 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -3,7 +3,7 @@ # Plugin Config Catalog -Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md) documents the types these declarations reference. +Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin's full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference. This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field. @@ -106,7 +106,7 @@ export interface Config { } ``` -Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md) +Depends on: [`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/core.md) Source: [`packages/core/agent-loop/src/index.ts:236`](../packages/core/agent-loop/src/index.ts) @@ -1044,7 +1044,7 @@ export interface PresetSpec { } ``` -Depends on: [`ApprovalPolicy`](core-data-structures/approval.md) · [`SandboxMode`](core-data-structures/sandbox.md) +Depends on: [`ApprovalPolicy`](subsystems/approval.md) · [`SandboxMode`](subsystems/sandbox.md) Source: [`packages/interaction/permission/src/index.ts:140`](../packages/interaction/permission/src/index.ts) @@ -1234,7 +1234,7 @@ export interface Config { } ``` -Depends on: [`SandboxMode`](core-data-structures/sandbox.md) +Depends on: [`SandboxMode`](subsystems/sandbox.md) Source: [`packages/sandbox/sandbox-policy/src/index.ts:67`](../packages/sandbox/sandbox-policy/src/index.ts) @@ -2193,7 +2193,7 @@ export interface Config { } ``` -Depends on: [`AgentOptions`](core-data-structures/core.md) +Depends on: [`AgentOptions`](subsystems/core.md) Source: [`packages/subagent/tool-subagent/src/index.ts:25`](../packages/subagent/tool-subagent/src/index.ts) @@ -2212,7 +2212,7 @@ export interface Config { } ``` -Depends on: [`SubagentReportDelivery`](core-data-structures/subagent.md) +Depends on: [`SubagentReportDelivery`](subsystems/subagent.md) Source: [`packages/subagent/tool-subagent-report/src/index.ts:22`](../packages/subagent/tool-subagent-report/src/index.ts) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 2c99c451d2..dd9cf5bfa5 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -3,7 +3,7 @@ # Cordis Events Catalog -Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. +Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them. @@ -31,7 +31,7 @@ A fully configured agent and live session were published. Setup is composition-o 'agent/created'(this: Scoped, payload: { agent: Agent }): void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) Source: [`packages/core/agent/src/types.ts:158`](../../packages/core/agent/src/types.ts) @@ -51,7 +51,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco 'agent/disposed'(this: Scoped, payload: { agent: Agent }): void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts) @@ -73,7 +73,7 @@ A step or turn errored. The machine reports a failure here even when the error h 'agent/error'(this: Scoped, payload: { agent: Agent; turn: number; step: number; error: unknown }): void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts) @@ -95,7 +95,7 @@ One message left the inbox inside its open turn. If the proposed step is rejecte 'agent/inbox/claimed'(this: Scoped, payload: { agent: Agent; message: UserMessage; turn: number }): void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md) Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts) @@ -114,7 +114,7 @@ One message was discarded from the live inbox. 'agent/inbox/discarded'(this: Scoped, payload: { agent: Agent; message: UserMessage }): void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md) Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts) @@ -133,7 +133,7 @@ One message entered the live inbox. 'agent/inbox/inserted'(this: Scoped, payload: { agent: Agent; message: UserMessage }): void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md) Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts) @@ -156,7 +156,7 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p 'agent/pre-step'(this: Scoped, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [PreStepDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md) +Types: [Agent](../subsystems/core.md) · [PreStepDecision](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [UserMessage](../subsystems/session.md) Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts) @@ -180,7 +180,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach 'agent/request'(this: Scoped, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [LlmCallConfig](../subsystems/core.md) · [Scoped](../subsystems/scope.md) Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/types.ts) @@ -207,7 +207,7 @@ Handle one failed model-request attempt before the loop retries or closes its st 'agent/request-error'(this: Scoped, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [LlmFailure](../subsystems/llm-streaming.md) · [RequestErrorAction](../subsystems/core.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [Scoped](../subsystems/scope.md) Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts) @@ -229,7 +229,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to 'agent/session-start'(this: Scoped, payload: { agent: Agent; source: SessionStartSource }): void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [SessionStartSource](../subsystems/core.md) Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts) @@ -250,7 +250,7 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` 'agent/status'(this: Scoped, payload: { agent: Agent; status: AgentStatus }): void ``` -Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [AgentStatus](../subsystems/core.md) · [Scoped](../subsystems/scope.md) Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/types.ts) @@ -279,7 +279,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f 'agent/turn-stopping'(this: Scoped, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise | void ``` -Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [Scoped](../subsystems/scope.md) Source: [`packages/core/agent/src/types.ts:277`](../../packages/core/agent/src/types.ts) @@ -302,7 +302,7 @@ A declarative agent entry failed before it could publish a live agent. Consumers 'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void ``` -Types: [SessionId](../core-data-structures/core.md) +Types: [SessionId](../subsystems/core.md) Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts) @@ -323,7 +323,7 @@ Ask composed answerers for one decision. Return an outcome to claim the request 'approval/request'(this: Scoped, req: ApprovalRequest, next: () => Promise): Promise ``` -Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [ApprovalService](../core-data-structures/approval.md) · [Scoped](../core-data-structures/scope.md) +Types: [ApprovalOutcome](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [ApprovalService](../subsystems/approval.md) · [Scoped](../subsystems/scope.md) Source: [`packages/interaction/user-approval/src/index.ts:30`](../../packages/interaction/user-approval/src/index.ts) @@ -367,7 +367,7 @@ Committed change to a provider-managed credential source: a `set`, an `unset`, o 'credentials/updated'(ref: CredentialRef): void ``` -Types: [CredentialRef](../core-data-structures/credentials.md) +Types: [CredentialRef](../subsystems/credentials.md) Source: [`packages/credentials/credentials/src/index.ts:67`](../../packages/credentials/credentials/src/index.ts) @@ -408,7 +408,7 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined> ``` -Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) +Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md) Source: [`packages/fs/fs/src/index.ts:64`](../../packages/fs/fs/src/index.ts) @@ -428,7 +428,7 @@ Record a successful observation. Listeners must be synchronous recorders: throws 'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void ``` -Types: [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) +Types: [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md) Source: [`packages/fs/fs/src/index.ts:73`](../../packages/fs/fs/src/index.ts) @@ -448,7 +448,7 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise): Promise ``` -Types: [FsTarget](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) +Types: [FsTarget](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md) Source: [`packages/fs/fs/src/index.ts:56`](../../packages/fs/fs/src/index.ts) @@ -470,7 +470,7 @@ Goal mutation accepted by one live agent. The matching `goal/change` session eve 'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped, payload: { agent: Agent; change: GoalChanged }): void ``` -Types: [Agent](../core-data-structures/core.md) · [GoalChanged](../core-data-structures/goal.md) · [Scoped](../core-data-structures/scope.md) +Types: [Agent](../subsystems/core.md) · [GoalChanged](../subsystems/goal.md) · [Scoped](../subsystems/scope.md) Source: [`packages/goal/goal/src/domain.ts:114`](../../packages/goal/goal/src/domain.ts) @@ -515,7 +515,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable): AsyncIterable ``` -Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md) +Types: [GenerateOptions](../subsystems/core.md) · [LlmService](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md) Source: [`packages/llm/llm/src/index.ts:62`](../../packages/llm/llm/src/index.ts) @@ -540,7 +540,7 @@ Creation announcement during session publication. A synchronous throw vetoes and 'session/created'(this: Scoped, session: Session): void ``` -Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) +Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) Source: [`packages/core/session/src/index.ts:74`](../../packages/core/session/src/index.ts) @@ -561,7 +561,7 @@ Emitted once when an announced session leaves the store, including publication r 'session/disposed'(this: Scoped, session: Session): void ``` -Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) +Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) Source: [`packages/core/session/src/index.ts:84`](../../packages/core/session/src/index.ts) @@ -584,7 +584,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before 'session/event'(this: Scoped, session: Session, event: SessionEvent): void ``` -Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) +Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md) Source: [`packages/core/session/src/index.ts:96`](../../packages/core/session/src/index.ts) @@ -604,7 +604,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await 'session/flush'(this: Scoped, session: Session): Promise | void ``` -Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) +Types: [Scoped](../subsystems/scope.md) · [Session](../subsystems/session.md) Source: [`packages/core/session/src/index.ts:105`](../../packages/core/session/src/index.ts) @@ -629,7 +629,7 @@ One registered namespace's RAW user section changed, whether or not the resolved 'settings/document-updated'(ns: SettingsNamespace, revision: number): void ``` -Types: [SettingsNamespace](../core-data-structures/settings.md) +Types: [SettingsNamespace](../subsystems/settings.md) Source: [`packages/settings/settings/src/index.ts:170`](../../packages/settings/settings/src/index.ts) @@ -656,7 +656,7 @@ Committed change to one registered namespace's resolved value. Emitted after the 'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void ``` -Types: [SettingsNamespace](../core-data-structures/settings.md) · [SettingsUpdateSource](../core-data-structures/settings.md) +Types: [SettingsNamespace](../subsystems/settings.md) · [SettingsUpdateSource](../subsystems/settings.md) Source: [`packages/settings/settings/src/index.ts:157`](../../packages/settings/settings/src/index.ts) @@ -697,7 +697,7 @@ A published child settled. Scope-filtered dispatch uses the same delegating pare 'subagent/end'(this: Scoped, info: SubagentRunEndInfo): void ``` -Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md) +Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md) Source: [`packages/subagent/subagent/src/index.ts:162`](../../packages/subagent/subagent/src/index.ts) @@ -714,7 +714,7 @@ A provider became resolvable in the registry. 'subagent/provider-added'(provider: SubagentProvider): void ``` -Types: [SubagentProvider](../core-data-structures/subagent.md) +Types: [SubagentProvider](../subsystems/subagent.md) Source: [`packages/subagent/subagent/src/index.ts:136`](../../packages/subagent/subagent/src/index.ts) @@ -751,7 +751,7 @@ A provider established a published child. For in-process providers, `ctx.agents. 'subagent/start'(this: Scoped, info: SubagentRunInfo): void ``` -Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md) +Types: [Scoped](../subsystems/scope.md) · [SubagentService](../subsystems/subagent.md) Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts) @@ -775,7 +775,7 @@ Expert waterfall over the assembled sections, contexts, tools, and variables. Sc 'system-prompt/assemble'(this: Scoped, assembly: PromptAssembly, context: AssembleContext, next: () => Promise): Promise ``` -Types: [AssembleContext](../core-data-structures/system-prompt.md) · [Scoped](../core-data-structures/scope.md) · [SystemPrompt](../core-data-structures/system-prompt.md) +Types: [AssembleContext](../subsystems/system-prompt.md) · [Scoped](../subsystems/scope.md) · [SystemPrompt](../subsystems/system-prompt.md) Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts) @@ -865,7 +865,7 @@ Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before the bri 'tools/code-dispatch-log'(this: Scoped, dispatch: CodeDispatchLog, next: () => Promise): Promise ``` -Types: [CodeDispatchLog](../core-data-structures/tools.md) · [ContentBlock](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [ToolRegistry](../core-data-structures/tools.md) +Types: [CodeDispatchLog](../subsystems/tools.md) · [ContentBlock](../subsystems/core.md) · [Scoped](../subsystems/scope.md) · [ToolRegistry](../subsystems/tools.md) Source: [`packages/core/tools/src/index.ts:173`](../../packages/core/tools/src/index.ts) @@ -887,7 +887,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor 'tools/execute'(this: Scoped, exec: ToolDispatchExecution, next: () => Promise): Promise ``` -Types: [Scoped](../core-data-structures/scope.md) · [ToolDispatchExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) +Types: [Scoped](../subsystems/scope.md) · [ToolDispatchExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md) Source: [`packages/core/tools/src/index.ts:148`](../../packages/core/tools/src/index.ts) @@ -910,7 +910,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts 'tools/post-execute'(this: Scoped, exec: ToolExecution, result: Readonly, next: () => Promise): Promise ``` -Types: [PostToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) +Types: [PostToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md) Source: [`packages/core/tools/src/index.ts:160`](../../packages/core/tools/src/index.ts) @@ -931,7 +931,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv 'tools/pre-execute'(this: Scoped, exec: ToolExecution, next: () => Promise): Promise ``` -Types: [PreToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) +Types: [PreToolDecision](../subsystems/tools.md) · [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md) Source: [`packages/core/tools/src/index.ts:137`](../../packages/core/tools/src/index.ts) @@ -950,7 +950,7 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained 'tools/result'(this: Scoped, exec: Readonly, result: Readonly): undefined ``` -Types: [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md) +Types: [Scoped](../subsystems/scope.md) · [ToolExecution](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolRegistry](../subsystems/tools.md) Source: [`packages/core/tools/src/index.ts:181`](../../packages/core/tools/src/index.ts) @@ -974,7 +974,7 @@ One `agent()` call settled (clean result, child failure, or run cancellation). P 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void ``` -Types: [WorkflowRunInfo](../core-data-structures/workflow.md) +Types: [WorkflowRunInfo](../subsystems/workflow.md) Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts) @@ -995,7 +995,7 @@ One `agent()` call established a published child run. Paired with Events['workfl 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void ``` -Types: [WorkflowRunInfo](../core-data-structures/workflow.md) +Types: [WorkflowRunInfo](../subsystems/workflow.md) Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts) @@ -1016,7 +1016,7 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void ``` -Types: [WorkflowRunInfo](../core-data-structures/workflow.md) +Types: [WorkflowRunInfo](../subsystems/workflow.md) Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts) @@ -1034,7 +1034,7 @@ The script emitted a narration line (a `log(message)` call). 'workflow/log'(info: WorkflowRunInfo, message: string): void ``` -Types: [WorkflowRunInfo](../core-data-structures/workflow.md) +Types: [WorkflowRunInfo](../subsystems/workflow.md) Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts) @@ -1053,7 +1053,7 @@ The script entered a phase (a `phase(title)` call) — progress grouping for obs 'workflow/phase'(info: WorkflowRunInfo, title: string): void ``` -Types: [WorkflowRunInfo](../core-data-structures/workflow.md) +Types: [WorkflowRunInfo](../subsystems/workflow.md) Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts) @@ -1071,7 +1071,7 @@ A workflow run started — the script's meta block validated, the body about to 'workflow/start'(info: WorkflowRunInfo): void ``` -Types: [WorkflowRunInfo](../core-data-structures/workflow.md) +Types: [WorkflowRunInfo](../subsystems/workflow.md) Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts) diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 56a0d0d2e6..dbab056105 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -3,7 +3,7 @@ # Cordis Services Catalog -Every `ctx.` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against. +Every `ctx.` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against. This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them. @@ -42,7 +42,7 @@ async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [AgentOptions](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) +Types: [Agent](../subsystems/core.md) · [AgentOptions](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md) Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts) @@ -214,7 +214,7 @@ list(): Agent[] roots(): Agent[] ``` -Types: [Agent](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) +Types: [Agent](../subsystems/core.md) · [SessionId](../subsystems/core.md) Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts) @@ -260,7 +260,7 @@ async request(req: ApprovalRequest): Promise overrideOf(session: Session): ApprovalPolicy | undefined ``` -Types: [Agent](../core-data-structures/core.md) · [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalPolicy](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [Session](../core-data-structures/session.md) +Types: [Agent](../subsystems/core.md) · [ApprovalOutcome](../subsystems/approval.md) · [ApprovalPolicy](../subsystems/approval.md) · [ApprovalRequest](../subsystems/approval.md) · [Session](../subsystems/session.md) Source: [`packages/interaction/user-approval/src/index.ts:193`](../../packages/interaction/user-approval/src/index.ts) @@ -300,7 +300,7 @@ abstract run(spec: BashExecSpec): Promise abstract start(spec: BashExecSpec): BashProcess ``` -Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashProcess](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) +Types: [BashExecRequest](../subsystems/bash.md) · [BashExecSpec](../subsystems/bash.md) · [BashProcess](../subsystems/bash.md) · [BashRunResult](../subsystems/bash.md) Source: [`packages/bash/bash/src/index.ts:53`](../../packages/bash/bash/src/index.ts) @@ -331,7 +331,7 @@ collect(execution: ToolExecution): DshEnvironment list(): BashEnvVariableInfo[] ``` -Types: [DshEnvironment](../core-data-structures/subprocess.md) · [ToolExecution](../core-data-structures/tools.md) +Types: [DshEnvironment](../subsystems/subprocess.md) · [ToolExecution](../subsystems/tools.md) Source: [`packages/bash/bash-env/src/index.ts:89`](../../packages/bash/bash-env/src/index.ts) @@ -396,7 +396,7 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs abstract run(request: CodeRunRequest): Promise ``` -Types: [CodeRunRequest](../core-data-structures/code-runtime.md) · [CodeRunResult](../core-data-structures/code-runtime.md) +Types: [CodeRunRequest](../subsystems/code-runtime.md) · [CodeRunResult](../subsystems/code-runtime.md) Source: [`packages/code-runtime/code-runtime/src/index.ts:104`](../../packages/code-runtime/code-runtime/src/index.ts) @@ -449,7 +449,7 @@ find(agent: Agent, name: string): CommandDefinition | undefined async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [CommandDefinition](../core-data-structures/commands.md) · [CommandDescriptor](../core-data-structures/commands.md) +Types: [Agent](../subsystems/core.md) · [CommandDefinition](../subsystems/commands.md) · [CommandDescriptor](../subsystems/commands.md) Source: [`packages/interaction/commands/src/index.ts:305`](../../packages/interaction/commands/src/index.ts) @@ -514,7 +514,7 @@ abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, ): P abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise ``` -Types: [CompactionResult](../core-data-structures/compaction.md) · [CompactionTrigger](../core-data-structures/compaction.md) +Types: [CompactionResult](../subsystems/compaction.md) · [CompactionTrigger](../subsystems/compaction.md) Source: [`packages/compact/compact/src/index.ts:93`](../../packages/compact/compact/src/index.ts) @@ -560,7 +560,7 @@ abstract set(ref: CredentialRef, value: string): Promise abstract unset(ref: CredentialRef): Promise ``` -Types: [CredentialInfo](../core-data-structures/credentials.md) · [CredentialRef](../core-data-structures/credentials.md) · [ResolvedCredential](../core-data-structures/credentials.md) +Types: [CredentialInfo](../subsystems/credentials.md) · [CredentialRef](../subsystems/credentials.md) · [ResolvedCredential](../subsystems/credentials.md) Source: [`packages/credentials/credentials/src/index.ts:77`](../../packages/credentials/credentials/src/index.ts) @@ -719,7 +719,7 @@ abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise ``` -Types: [FsDirEntry](../core-data-structures/filesystem.md) · [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsPathInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md) · [SandboxExecutionPolicy](../core-data-structures/sandbox.md) +Types: [FsDirEntry](../subsystems/filesystem.md) · [FsEditOutcome](../subsystems/filesystem.md) · [FsEditRequest](../subsystems/filesystem.md) · [FsInfo](../subsystems/filesystem.md) · [FsPathInfo](../subsystems/filesystem.md) · [FsTarget](../subsystems/filesystem.md) · [FsVersion](../subsystems/filesystem.md) · [FsWriteIntent](../subsystems/filesystem.md) · [FsWriteOutcome](../subsystems/filesystem.md) · [SandboxExecutionPolicy](../subsystems/sandbox.md) Source: [`packages/fs/fs/src/index.ts:83`](../../packages/fs/fs/src/index.ts) @@ -814,7 +814,7 @@ block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView @Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult ``` -Types: [Agent](../core-data-structures/core.md) · [CreateGoalRequest](../core-data-structures/goal.md) · [CreateGoalResult](../core-data-structures/goal.md) · [EditGoalRequest](../core-data-structures/goal.md) · [GoalBlockReason](../core-data-structures/goal.md) · [GoalRef](../core-data-structures/goal.md) · [GoalView](../core-data-structures/goal.md) +Types: [Agent](../subsystems/core.md) · [CreateGoalRequest](../subsystems/goal.md) · [CreateGoalResult](../subsystems/goal.md) · [EditGoalRequest](../subsystems/goal.md) · [GoalBlockReason](../subsystems/goal.md) · [GoalRef](../subsystems/goal.md) · [GoalView](../subsystems/goal.md) Source: [`packages/goal/goal/src/index.ts:183`](../../packages/goal/goal/src/index.ts) @@ -1008,7 +1008,7 @@ async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise ``` -Types: [AdapterRegistrationHandle](../core-data-structures/core.md) · [DirectoryRegistrationHandle](../core-data-structures/core.md) · [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmCallConfig](../core-data-structures/core.md) · [LlmConfigurableProvider](../core-data-structures/core.md) · [LlmDiscoveredModel](../core-data-structures/core.md) · [LlmModelDiscoveryRequest](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [LlmResolvedModelInfo](../core-data-structures/core.md) · [PreparedLlmCall](../core-data-structures/llm-streaming.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md) +Types: [AdapterRegistrationHandle](../subsystems/core.md) · [DirectoryRegistrationHandle](../subsystems/core.md) · [GenerateOptions](../subsystems/core.md) · [LlmAdapter](../subsystems/llm-streaming.md) · [LlmCallConfig](../subsystems/core.md) · [LlmConfigurableProvider](../subsystems/core.md) · [LlmDiscoveredModel](../subsystems/core.md) · [LlmModelDiscoveryRequest](../subsystems/core.md) · [LlmModelInfo](../subsystems/core.md) · [LlmProviderInfo](../subsystems/core.md) · [LlmResolvedModelInfo](../subsystems/core.md) · [PreparedLlmCall](../subsystems/llm-streaming.md) · [ResolvedRetryPolicy](../subsystems/llm-streaming.md) · [StreamChunk](../subsystems/llm-streaming.md) Source: [`packages/llm/llm/src/index.ts:292`](../../packages/llm/llm/src/index.ts) @@ -1060,7 +1060,7 @@ optionOf(name: string): PresetOption set(session: Session, name: string): void ``` -Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) +Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md) Source: [`packages/interaction/permission/src/index.ts:159`](../../packages/interaction/permission/src/index.ts) @@ -1096,7 +1096,7 @@ get(agent: Agent): { active: boolean; pending?: boolean } set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop' ``` -Types: [Agent](../core-data-structures/core.md) +Types: [Agent](../subsystems/core.md) Source: [`packages/plan/plan-mode/src/index.ts:183`](../../packages/plan/plan-mode/src/index.ts) @@ -1178,7 +1178,7 @@ async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Pr list(owner: Agent): PtySessionSnapshot[] ``` -Types: [Agent](../core-data-structures/core.md) · [PtyBackend](../core-data-structures/pty.md) · [PtyReadRequest](../core-data-structures/pty.md) · [PtyReadResult](../core-data-structures/pty.md) · [PtySendOperation](../core-data-structures/pty.md) · [PtySendRequest](../core-data-structures/pty.md) · [PtySessionId](../core-data-structures/pty.md) · [PtySessionSnapshot](../core-data-structures/pty.md) · [PtySignal](../core-data-structures/pty.md) · [PtySignalResult](../core-data-structures/pty.md) · [PtySpawnRequest](../core-data-structures/pty.md) · [PtySpawnResult](../core-data-structures/pty.md) +Types: [Agent](../subsystems/core.md) · [PtyBackend](../subsystems/pty.md) · [PtyReadRequest](../subsystems/pty.md) · [PtyReadResult](../subsystems/pty.md) · [PtySendOperation](../subsystems/pty.md) · [PtySendRequest](../subsystems/pty.md) · [PtySessionId](../subsystems/pty.md) · [PtySessionSnapshot](../subsystems/pty.md) · [PtySignal](../subsystems/pty.md) · [PtySignalResult](../subsystems/pty.md) · [PtySpawnRequest](../subsystems/pty.md) · [PtySpawnResult](../subsystems/pty.md) Source: [`packages/pty/pty/src/index.ts:105`](../../packages/pty/pty/src/index.ts) @@ -1201,7 +1201,7 @@ Abstract process-sandbox service. confine must return enforcing argv or fail clo abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv ``` -Types: [ConfinedArgv](../core-data-structures/sandbox.md) · [SandboxPolicy](../core-data-structures/sandbox.md) +Types: [ConfinedArgv](../subsystems/sandbox.md) · [SandboxPolicy](../subsystems/sandbox.md) Source: [`packages/sandbox/sandbox/src/index.ts:148`](../../packages/sandbox/sandbox/src/index.ts) @@ -1229,7 +1229,7 @@ resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy overrideOf(session: Session): SandboxMode | undefined ``` -Types: [SandboxExecutionPolicy](../core-data-structures/sandbox.md) · [SandboxMode](../core-data-structures/sandbox.md) · [SandboxPolicyRequest](../core-data-structures/sandbox.md) · [Session](../core-data-structures/session.md) +Types: [SandboxExecutionPolicy](../subsystems/sandbox.md) · [SandboxMode](../subsystems/sandbox.md) · [SandboxPolicyRequest](../subsystems/sandbox.md) · [Session](../subsystems/session.md) Source: [`packages/sandbox/sandbox-policy/src/index.ts:91`](../../packages/sandbox/sandbox-policy/src/index.ts) @@ -1350,7 +1350,7 @@ abstract list(signal?: AbortSignal): Promise abstract listSnapshots(signal?: AbortSignal): Promise ``` -Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionInspection](../core-data-structures/persistence.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md) · [SessionPreparation](../core-data-structures/persistence.md) +Types: [SessionEvent](../subsystems/core.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md) · [SessionInspection](../subsystems/persistence.md) · [SessionLocation](../subsystems/persistence.md) · [SessionPersistenceSnapshot](../subsystems/persistence.md) · [SessionPreparation](../subsystems/persistence.md) Source: [`packages/session/session-persistence/src/index.ts:72`](../../packages/session/session-persistence/src/index.ts) @@ -1398,7 +1398,7 @@ async write(session: Session): Promise async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise ``` -Types: [Session](../core-data-structures/session.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) +Types: [Session](../subsystems/session.md) · [SessionHeader](../subsystems/persistence.md) · [SessionId](../subsystems/core.md) Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts) @@ -1506,7 +1506,7 @@ viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint } ``` -Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) +Types: [Session](../subsystems/session.md) · [SessionEvent](../subsystems/core.md) Source: [`packages/session/session-projection/src/index.ts:156`](../../packages/session/session-projection/src/index.ts) @@ -1633,7 +1633,7 @@ async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promi async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise ``` -Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventResultFilter](../core-data-structures/session-query.md) · [SessionEventSearchDocument](../core-data-structures/session-query.md) · [SessionEventSearchPage](../core-data-structures/session-query.md) · [SessionEventSearchRequest](../core-data-structures/session-query.md) · [SessionEventTraceObservation](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionLogSnapshot](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionResultFilter](../core-data-structures/session-query.md) · [SessionSearchExecContext](../core-data-structures/session-query.md) · [SessionSearchHit](../core-data-structures/session-query.md) · [SessionSearchPage](../core-data-structures/session-query.md) · [SessionSearchRequest](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md) · [SessionTitleObservation](../core-data-structures/session-query.md) · [SessionTitleObservationResult](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md) +Types: [SessionEventReadRequest](../subsystems/session-query.md) · [SessionEventRecord](../subsystems/session-query.md) · [SessionEventResultFilter](../subsystems/session-query.md) · [SessionEventSearchDocument](../subsystems/session-query.md) · [SessionEventSearchPage](../subsystems/session-query.md) · [SessionEventSearchRequest](../subsystems/session-query.md) · [SessionEventTraceObservation](../subsystems/session-query.md) · [SessionEventTraceRequest](../subsystems/session-query.md) · [SessionEventWindow](../subsystems/session-query.md) · [SessionId](../subsystems/core.md) · [SessionLineageTrace](../subsystems/session-query.md) · [SessionLogSnapshot](../subsystems/session-query.md) · [SessionRecord](../subsystems/session-query.md) · [SessionResultFilter](../subsystems/session-query.md) · [SessionSearchExecContext](../subsystems/session-query.md) · [SessionSearchHit](../subsystems/session-query.md) · [SessionSearchPage](../subsystems/session-query.md) · [SessionSearchRequest](../subsystems/session-query.md) · [SessionSurfaceSnapshot](../subsystems/session-query.md) · [SessionTitleObservation](../subsystems/session-query.md) · [SessionTitleObservationResult](../subsystems/session-query.md) · [SessionTitleSnapshot](../subsystems/session-title.md) Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts) @@ -1663,7 +1663,7 @@ async listCandidates( agent: Agent, query: string = '', limit: number = this.con async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [PreparedReferencedMessage](../core-data-structures/session-reference.md) · [SessionReferenceCandidate](../core-data-structures/session-reference.md) · [SessionReferenceInput](../core-data-structures/session-reference.md) +Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [PreparedReferencedMessage](../subsystems/session-reference.md) · [SessionReferenceCandidate](../subsystems/session-reference.md) · [SessionReferenceInput](../subsystems/session-reference.md) Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts) @@ -1797,7 +1797,7 @@ list(): Session[] fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session ``` -Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [PrepareSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) +Types: [CreateSessionOptions](../subsystems/persistence.md) · [PrepareSessionOptions](../subsystems/persistence.md) · [Session](../subsystems/session.md) · [SessionId](../subsystems/core.md) Source: [`packages/core/session/src/index.ts:807`](../../packages/core/session/src/index.ts) @@ -1844,7 +1844,7 @@ async refresh(session: Session, signal?: AbortSignal): Promise Promise ``` -Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md) +Types: [Session](../subsystems/session.md) · [SessionTitleProvider](../subsystems/session-title.md) · [SessionTitleSnapshot](../subsystems/session-title.md) Source: [`packages/session/session-title/src/index.ts:261`](../../packages/session/session-title/src/index.ts) @@ -1929,7 +1929,7 @@ async replace(ns: SettingsNamespace, section: object, expectedRevision?: number) async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise ``` -Types: [SettingsDescribeOptions](../core-data-structures/settings.md) · [SettingsDescriptor](../core-data-structures/settings.md) · [SettingsNamespace](../core-data-structures/settings.md) · [SettingsPathOp](../core-data-structures/settings.md) · [SettingsRegisterOptions](../core-data-structures/settings.md) · [SettingsScope](../core-data-structures/settings.md) +Types: [SettingsDescribeOptions](../subsystems/settings.md) · [SettingsDescriptor](../subsystems/settings.md) · [SettingsNamespace](../subsystems/settings.md) · [SettingsPathOp](../subsystems/settings.md) · [SettingsRegisterOptions](../subsystems/settings.md) · [SettingsScope](../subsystems/settings.md) Source: [`packages/settings/settings/src/index.ts:387`](../../packages/settings/settings/src/index.ts) @@ -1987,7 +1987,7 @@ async snapshot(options: SkillLookupOptions = {}): Promise async get(name: string, options: SkillLookupOptions = {}): Promise ``` -Types: [SkillCatalogSnapshot](../core-data-structures/skills.md) · [SkillDefinition](../core-data-structures/skills.md) · [SkillLookupOptions](../core-data-structures/skills.md) · [SkillProvider](../core-data-structures/skills.md) · [SkillProviderControl](../core-data-structures/skills.md) · [SkillRegistration](../core-data-structures/skills.md) · [SkillSummary](../core-data-structures/skills.md) +Types: [SkillCatalogSnapshot](../subsystems/skills.md) · [SkillDefinition](../subsystems/skills.md) · [SkillLookupOptions](../subsystems/skills.md) · [SkillProvider](../subsystems/skills.md) · [SkillProviderControl](../subsystems/skills.md) · [SkillRegistration](../subsystems/skills.md) · [SkillSummary](../subsystems/skills.md) Source: [`packages/skill/skill/src/index.ts:304`](../../packages/skill/skill/src/index.ts) @@ -2010,7 +2010,7 @@ Semantics every implementation must honor: abstract saveText(input: SaveTextSpill): Promise ``` -Types: [SaveTextSpill](../core-data-structures/spill.md) · [SpillRef](../core-data-structures/spill.md) +Types: [SaveTextSpill](../subsystems/spill.md) · [SpillRef](../subsystems/spill.md) Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts) @@ -2248,7 +2248,7 @@ list(): string[] async start(name: string, request: SubagentStartRequest): Promise ``` -Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [ContinuableSetupContribution](../core-data-structures/subagent.md) · [ContinuableStart](../core-data-structures/subagent.md) · [ContinuableStartSpec](../core-data-structures/subagent.md) · [MessageId](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md) · [SubagentDescendantListEntry](../core-data-structures/subagent.md) · [SubagentFollowupOptions](../core-data-structures/subagent.md) · [SubagentInterruptAuthority](../core-data-structures/subagent.md) · [SubagentListEntry](../core-data-structures/subagent.md) · [SubagentProvider](../core-data-structures/subagent.md) · [SubagentReportOptions](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md) +Types: [Agent](../subsystems/core.md) · [ContentBlock](../subsystems/core.md) · [ContinuableSetupContribution](../subsystems/subagent.md) · [ContinuableStart](../subsystems/subagent.md) · [ContinuableStartSpec](../subsystems/subagent.md) · [MessageId](../subsystems/core.md) · [SessionId](../subsystems/core.md) · [SubagentDescendantListEntry](../subsystems/subagent.md) · [SubagentFollowupOptions](../subsystems/subagent.md) · [SubagentInterruptAuthority](../subsystems/subagent.md) · [SubagentListEntry](../subsystems/subagent.md) · [SubagentProvider](../subsystems/subagent.md) · [SubagentReportOptions](../subsystems/subagent.md) · [SubagentRun](../subsystems/subagent.md) · [SubagentStartRequest](../subsystems/subagent.md) Source: [`packages/subagent/subagent/src/index.ts:167`](../../packages/subagent/subagent/src/index.ts) @@ -2297,7 +2297,7 @@ abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise ``` -Types: [SubprocessHandle](../core-data-structures/subprocess.md) · [SubprocessSpawnSpec](../core-data-structures/subprocess.md) · [SubprocessTerminalHandle](../core-data-structures/subprocess.md) · [SubprocessTerminalSpawnSpec](../core-data-structures/subprocess.md) +Types: [SubprocessHandle](../subsystems/subprocess.md) · [SubprocessSpawnSpec](../subsystems/subprocess.md) · [SubprocessTerminalHandle](../subsystems/subprocess.md) · [SubprocessTerminalSpawnSpec](../subsystems/subprocess.md) Source: [`packages/subprocess/subprocess/src/index.ts:102`](../../packages/subprocess/subprocess/src/index.ts) @@ -2353,7 +2353,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine async assemble(context: AssembleContext = {}): Promise ``` -Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptContext](../core-data-structures/system-prompt.md) · [PromptSection](../core-data-structures/system-prompt.md) · [ToolProviderResult](../core-data-structures/system-prompt.md) +Types: [AssembleContext](../subsystems/system-prompt.md) · [PromptContext](../subsystems/system-prompt.md) · [PromptSection](../subsystems/system-prompt.md) · [ToolProviderResult](../subsystems/system-prompt.md) Source: [`packages/core/system-prompt/src/index.ts:314`](../../packages/core/system-prompt/src/index.ts) @@ -2448,7 +2448,7 @@ abstract onTaskDone(listener: TaskDoneListener): () => void abstract attachSurface(name: string): () => void ``` -Types: [Agent](../core-data-structures/core.md) · [TaskDoneListener](../core-data-structures/tasks.md) · [TaskId](../core-data-structures/tasks.md) · [TaskRead](../core-data-structures/tasks.md) · [TaskSnapshot](../core-data-structures/tasks.md) · [TaskStart](../core-data-structures/tasks.md) +Types: [Agent](../subsystems/core.md) · [TaskDoneListener](../subsystems/tasks.md) · [TaskId](../subsystems/tasks.md) · [TaskRead](../subsystems/tasks.md) · [TaskSnapshot](../subsystems/tasks.md) · [TaskStart](../subsystems/tasks.md) Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts) @@ -2507,7 +2507,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement estimateMessage(message: Message): number ``` -Types: [EpochHeader](../core-data-structures/session.md) · [Message](../core-data-structures/core.md) · [Session](../core-data-structures/session.md) · [TokenMeasurement](../core-data-structures/token-meter.md) +Types: [EpochHeader](../subsystems/session.md) · [Message](../subsystems/core.md) · [Session](../subsystems/session.md) · [TokenMeasurement](../subsystems/token-meter.md) Source: [`packages/llm/token-meter/src/index.ts:74`](../../packages/llm/token-meter/src/index.ts) @@ -2547,7 +2547,7 @@ pruneContent(blocks: readonly ContentBlock[]): ContentBlock[] | null pruneSession(session: Session): PruneResult ``` -Types: [ContentBlock](../core-data-structures/core.md) · [PruneResult](../core-data-structures/compaction.md) · [Session](../core-data-structures/session.md) +Types: [ContentBlock](../subsystems/core.md) · [PruneResult](../subsystems/compaction.md) · [Session](../subsystems/session.md) Source: [`packages/compact/compact-tool-result-prune/src/index.ts:44`](../../packages/compact/compact-tool-result-prune/src/index.ts) @@ -2630,7 +2630,7 @@ executionMode(exec: ToolExecutionInput): ToolExecutionMode async execute(exec: ToolExecutionInput): Promise ``` -Types: [ScopeKey](../core-data-structures/scope.md) · [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolGuard](../core-data-structures/tools.md) · [ToolRestriction](../core-data-structures/tools.md) · [ToolSchema](../core-data-structures/tools.md) +Types: [ScopeKey](../subsystems/scope.md) · [ToolDefinition](../subsystems/tools.md) · [ToolExecutionInput](../subsystems/tools.md) · [ToolExecutionMode](../subsystems/tools.md) · [ToolExecutionResult](../subsystems/tools.md) · [ToolGuard](../subsystems/tools.md) · [ToolRestriction](../subsystems/tools.md) · [ToolSchema](../subsystems/tools.md) Source: [`packages/core/tools/src/index.ts:739`](../../packages/core/tools/src/index.ts) @@ -2743,7 +2743,7 @@ registerProvider(provider: UserInteractionProvider): () => void async ask(request: AskUserQuestionRequest): Promise ``` -Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md) +Types: [AskUserQuestionAnswer](../subsystems/user-interaction.md) · [AskUserQuestionRequest](../subsystems/user-interaction.md) · [UserInteractionProvider](../subsystems/user-interaction.md) Source: [`packages/interaction/user-interaction/src/index.ts:51`](../../packages/interaction/user-interaction/src/index.ts) @@ -2801,7 +2801,7 @@ async search(request: WebSearchRequest, signal?: AbortSignal): Promise ``` -Types: [WebFetchProvider](../core-data-structures/web.md) · [WebFetchRequest](../core-data-structures/web.md) · [WebFetchResult](../core-data-structures/web.md) · [WebSearchProvider](../core-data-structures/web.md) · [WebSearchRequest](../core-data-structures/web.md) · [WebSearchResult](../core-data-structures/web.md) +Types: [WebFetchProvider](../subsystems/web.md) · [WebFetchRequest](../subsystems/web.md) · [WebFetchResult](../subsystems/web.md) · [WebSearchProvider](../subsystems/web.md) · [WebSearchRequest](../subsystems/web.md) · [WebSearchResult](../subsystems/web.md) Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts) @@ -2819,7 +2819,7 @@ Workflow execution seam. Invalid requests throw before publication; a live run i abstract start(request: WorkflowStartRequest): WorkflowRun ``` -Types: [WorkflowRun](../core-data-structures/workflow.md) · [WorkflowStartRequest](../core-data-structures/workflow.md) +Types: [WorkflowRun](../subsystems/workflow.md) · [WorkflowStartRequest](../subsystems/workflow.md) Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts) @@ -2885,7 +2885,7 @@ archiveSession(sessionId: SessionId): Promise async resolveByPath(path: string): Promise ``` -Types: [SessionId](../core-data-structures/core.md) +Types: [SessionId](../subsystems/core.md) Source: [`packages/workspace/workspace/src/index.ts:81`](../../packages/workspace/workspace/src/index.ts) diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml index 43f985604b..13c766cc80 100644 --- a/docs/development.i18n.yaml +++ b/docs/development.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 docs/development.md -development.md: 0032000e298ef49516d618e932258e79cf90e802 -development.zh.md: d681306e31991794519b62c3edbb6ca35ebc228b +development.md: 134109fd2a09dfa36aaf2ccdba14daccf896da60 +development.zh.md: 741a860770ee3b20fe94cb0b4993bb281b605b26 diff --git a/docs/development.md b/docs/development.md index 0032000e29..134109fd2a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -156,10 +156,10 @@ Pick the tag that matches the urgency so anyone scanning the code can tell a rel ### Documenting types verbatim (`ts type-equiv`) -The [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors: +The [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors: ```json -{ "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" } +{ "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" } ``` `pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `"projection": "public-api"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change. diff --git a/docs/development.zh.md b/docs/development.zh.md index d681306e31..741a860770 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -156,10 +156,10 @@ pnpm run demo:acp ### 逐字记录类型（`ts type-equiv`） -[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号： +[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号： ```json -{ "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" } +{ "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" } ``` `pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。 diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md index e783d5fddf..0c955c9480 100644 --- a/docs/graph-atlas.md +++ b/docs/graph-atlas.md @@ -3,7 +3,7 @@ # Documentation Graph Index -These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md). +These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md). The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md). diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md index 87ef939730..b9a330f21d 100644 --- a/docs/i18n/style-samples.md +++ b/docs/i18n/style-samples.md @@ -14,9 +14,9 @@ 依赖约束规范：各类扩展插件仅依赖抽象接口，严禁直接依赖 `dsh-agent-loop`（该主循环支持替换实现）；唯一允许的特例是组合包 `dsh-agent-spine-demo`，它的职责是组装整套实体主干。 -> This document covers **behavior**; type shapes live in [core-data-structures/](../core-data-structures/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)). +> This document covers **behavior**; type shapes live in [subsystems/](../subsystems/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)). -本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。 +本文档描述整体行为逻辑；类型定义存放于 [subsystems/](../subsystems/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。 ## ② 防御模式规则 diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index b238e56399..04f992e536 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -3,11 +3,11 @@ # Session Persistence Event Catalog -Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit). +Every event type that can appear in a session's durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit). This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md). -The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction. +The envelope declarations below compose each event's `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction. ## Event envelope @@ -123,7 +123,7 @@ Source: [`packages/core/agent/src/types.ts:300`](../packages/core/agent/src/type } ``` -Types: [CallId](core-data-structures/core.md) +Types: [CallId](subsystems/core.md) Source: [`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts) @@ -172,7 +172,7 @@ Source: [`packages/interaction/user-approval/src/index.ts:67`](../packages/inter 'assistant/chunk': { turn: number; step: number; chunk: StreamChunk } ``` -Types: [StreamChunk](core-data-structures/llm-streaming.md) +Types: [StreamChunk](subsystems/llm-streaming.md) Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/types.ts) @@ -188,7 +188,7 @@ Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/ 'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage } ``` -Types: [TokenUsage](core-data-structures/llm-streaming.md) +Types: [TokenUsage](subsystems/llm-streaming.md) Source: [`packages/core/session/src/types.ts:245`](../packages/core/session/src/types.ts) @@ -328,7 +328,7 @@ Source: [`packages/compact/compact/src/types.ts:19`](../packages/compact/compact ) ``` -Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md) +Types: [ContentBlock](subsystems/core.md) · [TokenUsage](subsystems/llm-streaming.md) Source: [`packages/compact/compact/src/types.ts:29`](../packages/compact/compact/src/types.ts) @@ -555,7 +555,7 @@ Source: [`packages/core/session/src/types.ts:304`](../packages/core/session/src/ 'session/title': SessionTitleEventData ``` -Types: [SessionTitleEventData](core-data-structures/session-title.md) +Types: [SessionTitleEventData](subsystems/session-title.md) Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts) @@ -566,7 +566,7 @@ Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/ 'session/title-llm-request': SessionTitleLlmRequestEventData ``` -Types: [SessionTitleLlmRequestEventData](core-data-structures/session-title.md) +Types: [SessionTitleLlmRequestEventData](subsystems/session-title.md) Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/session/session-title-llm/src/index.ts) @@ -616,7 +616,7 @@ Source: [`packages/subagent/subagent/src/descriptor.ts:37`](../packages/subagent 'todo/write': { todos: TodoItem[] } ``` -Types: [TodoItem](core-data-structures/session.md) +Types: [TodoItem](subsystems/session.md) Source: [`packages/core/session/src/types.ts:271`](../packages/core/session/src/types.ts) @@ -633,7 +633,7 @@ Source: [`packages/core/session/src/types.ts:271`](../packages/core/session/src/ 'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string } ``` -Types: [CallId](core-data-structures/core.md) +Types: [CallId](subsystems/core.md) Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/types.ts) @@ -658,7 +658,7 @@ Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/ 'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] } ``` -Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md) +Types: [CallId](subsystems/core.md) · [ContentBlock](subsystems/core.md) Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/code-mode.ts) @@ -681,7 +681,7 @@ Source: [`packages/core/tools/src/code-mode.ts:49`](../packages/core/tools/src/c 'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown } ``` -Types: [CallId](core-data-structures/core.md) +Types: [CallId](subsystems/core.md) Source: [`packages/core/tools/src/code-mode.ts:33`](../packages/core/tools/src/code-mode.ts) @@ -726,7 +726,7 @@ Source: [`packages/core/session/src/types.ts:263`](../packages/core/session/src/ 'turn/end': { turn: number; reason: TurnEndReason } ``` -Types: [TurnEndReason](core-data-structures/session.md) +Types: [TurnEndReason](subsystems/session.md) Source: [`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts) diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml index 47a2e3fdd7..b54453f3c4 100644 --- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.i18n.yaml +++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.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 docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md -0004-landlock-partial-notice-misclassified-child-failures.md: db810fdc896f9734d1b581617838d72166f4efc9 -0004-landlock-partial-notice-misclassified-child-failures.zh.md: 4a31fb038c44b036e6a183040947295a47221967 +0004-landlock-partial-notice-misclassified-child-failures.md: ed59fa9d2b04623220a9bcd984fe6becdc619198 +0004-landlock-partial-notice-misclassified-child-failures.zh.md: 5cf3e4422a5b888553e12dfb97b8a26aad65e231 diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md index db810fdc89..ed59fa9d2b 100644 --- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md +++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md @@ -40,7 +40,7 @@ Stderr remains an in-band attribution channel. A confined child can deliberately ## Guardrails added -- [`RunnerFailureRule`](../core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) carries optional allowed exit codes, case-insensitive per-line fatal signatures, and case-insensitive exact informational-line exclusions. +- [`RunnerFailureRule`](../subsystems/sandbox.md#wrapped-argv-and-classification-dialects) carries optional allowed exit codes, case-insensitive per-line fatal signatures, and case-insensitive exact informational-line exclusions. - [`dsh-sandbox-local`](../../packages/sandbox/sandbox-local/) maps Landlock to exit 125 plus a non-notice `landlock-run:` line while bwrap, Seatbelt, and custom runners remain signature-only. - [`dsh-bash-sandbox`](../../packages/bash/bash-sandbox/) directly spawns the provider argv, so a pre-start rejection uses the spawn-error channel instead of localized shell diagnostics. Settled foreground and background execution share one evidence-returning classifier; fatal evidence outranks denial, and foreground errors report the matched fatal line without changing captured stderr. - [`dsh-tool-fs-search`](../../packages/fs/tool-fs-search/) uses packaged ripgrep through `ctx.subprocess` and remains outside the sandboxed bash seam. diff --git a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md index 4a31fb038c..5cf3e4422a 100644 --- a/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md +++ b/docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.zh.md @@ -40,7 +40,7 @@ stderr 仍是带内归因通道。受限子进程可以故意复现 runner 的 ## 已添加的防护措施 -- [`RunnerFailureRule`](../core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) 携带可选的允许退出码、不区分大小写的逐行致命签名，以及按不区分大小写的整行精确匹配排除的信息性行。 +- [`RunnerFailureRule`](../subsystems/sandbox.md#wrapped-argv-and-classification-dialects) 携带可选的允许退出码、不区分大小写的逐行致命签名，以及按不区分大小写的整行精确匹配排除的信息性行。 - [`dsh-sandbox-local`](../../packages/sandbox/sandbox-local/) 把 Landlock 映射为退出码 125 加一行非通知的 `landlock-run:` 诊断，而 bwrap、Seatbelt 和自定义 runner 仍仅依据签名。 - [`dsh-bash-sandbox`](../../packages/bash/bash-sandbox/) 直接 spawn 提供方 argv，因此启动前遭拒时使用 spawn 错误通道，而非本地化的 shell 诊断。已结算的前台与后台执行共用一个返回证据的分类器；致命证据优先于拒绝，前台错误会报告匹配到的致命行，同时保持捕获的 stderr 不变。 - [`dsh-tool-fs-search`](../../packages/fs/tool-fs-search/) 通过 `ctx.subprocess` 运行打包的 ripgrep，并继续位于沙箱化 bash seam 之外。 diff --git a/docs/core-data-structures/approval.i18n.yaml b/docs/subsystems/approval.i18n.yaml similarity index 80% rename from docs/core-data-structures/approval.i18n.yaml rename to docs/subsystems/approval.i18n.yaml index 975f631805..a3447601a4 100644 --- a/docs/core-data-structures/approval.i18n.yaml +++ b/docs/subsystems/approval.i18n.yaml @@ -1,6 +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 docs/core-data-structures/approval.md +# pnpm run verify-translation-pairing --write docs/subsystems/approval.md approval.md: 8f17f98101950e6413d67fb4cce6befc5aede069 approval.zh.md: c19285572b667512427b71d4af214acbc2baf334 diff --git a/docs/core-data-structures/approval.md b/docs/subsystems/approval.md similarity index 100% rename from docs/core-data-structures/approval.md rename to docs/subsystems/approval.md diff --git a/docs/core-data-structures/approval.zh.md b/docs/subsystems/approval.zh.md similarity index 100% rename from docs/core-data-structures/approval.zh.md rename to docs/subsystems/approval.zh.md diff --git a/docs/core-data-structures/bash.i18n.yaml b/docs/subsystems/bash.i18n.yaml similarity index 100% rename from docs/core-data-structures/bash.i18n.yaml rename to docs/subsystems/bash.i18n.yaml diff --git a/docs/core-data-structures/bash.md b/docs/subsystems/bash.md similarity index 100% rename from docs/core-data-structures/bash.md rename to docs/subsystems/bash.md diff --git a/docs/core-data-structures/bash.zh.md b/docs/subsystems/bash.zh.md similarity index 100% rename from docs/core-data-structures/bash.zh.md rename to docs/subsystems/bash.zh.md diff --git a/docs/core-data-structures/code-runtime.i18n.yaml b/docs/subsystems/code-runtime.i18n.yaml similarity index 100% rename from docs/core-data-structures/code-runtime.i18n.yaml rename to docs/subsystems/code-runtime.i18n.yaml diff --git a/docs/core-data-structures/code-runtime.md b/docs/subsystems/code-runtime.md similarity index 100% rename from docs/core-data-structures/code-runtime.md rename to docs/subsystems/code-runtime.md diff --git a/docs/core-data-structures/code-runtime.zh.md b/docs/subsystems/code-runtime.zh.md similarity index 100% rename from docs/core-data-structures/code-runtime.zh.md rename to docs/subsystems/code-runtime.zh.md diff --git a/docs/core-data-structures/commands.i18n.yaml b/docs/subsystems/commands.i18n.yaml similarity index 80% rename from docs/core-data-structures/commands.i18n.yaml rename to docs/subsystems/commands.i18n.yaml index 18df873acc..a741971a9a 100644 --- a/docs/core-data-structures/commands.i18n.yaml +++ b/docs/subsystems/commands.i18n.yaml @@ -1,6 +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 docs/core-data-structures/commands.md +# pnpm run verify-translation-pairing --write docs/subsystems/commands.md commands.md: 83ce9c2498df58110d9a9c2e7d5163a9df813e1c commands.zh.md: c486f480177c7ff8b35cc846beafac009cea42bb diff --git a/docs/core-data-structures/commands.md b/docs/subsystems/commands.md similarity index 100% rename from docs/core-data-structures/commands.md rename to docs/subsystems/commands.md diff --git a/docs/core-data-structures/commands.zh.md b/docs/subsystems/commands.zh.md similarity index 100% rename from docs/core-data-structures/commands.zh.md rename to docs/subsystems/commands.zh.md diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/subsystems/compaction.i18n.yaml similarity index 80% rename from docs/core-data-structures/compaction.i18n.yaml rename to docs/subsystems/compaction.i18n.yaml index 2ad9ea8e8a..7dc00cebfc 100644 --- a/docs/core-data-structures/compaction.i18n.yaml +++ b/docs/subsystems/compaction.i18n.yaml @@ -1,6 +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 docs/core-data-structures/compaction.md +# pnpm run verify-translation-pairing --write docs/subsystems/compaction.md compaction.md: f1df5b83bd43136af60988dabd9dc68fe32467a2 compaction.zh.md: 52540250d466f81f51cf7c681bb6f1436e29a12d diff --git a/docs/core-data-structures/compaction.md b/docs/subsystems/compaction.md similarity index 100% rename from docs/core-data-structures/compaction.md rename to docs/subsystems/compaction.md diff --git a/docs/core-data-structures/compaction.zh.md b/docs/subsystems/compaction.zh.md similarity index 100% rename from docs/core-data-structures/compaction.zh.md rename to docs/subsystems/compaction.zh.md diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/subsystems/core.i18n.yaml similarity index 80% rename from docs/core-data-structures/core.i18n.yaml rename to docs/subsystems/core.i18n.yaml index ee870f9334..3057ee36ee 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/subsystems/core.i18n.yaml @@ -1,6 +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 docs/core-data-structures/core.md +# pnpm run verify-translation-pairing --write docs/subsystems/core.md core.md: 8f413a7a064ad6f63e0caec31354869e51139020 core.zh.md: d0f02f0cfc2cd30fc67aacf5b17d1daf324295c5 diff --git a/docs/core-data-structures/core.md b/docs/subsystems/core.md similarity index 100% rename from docs/core-data-structures/core.md rename to docs/subsystems/core.md diff --git a/docs/core-data-structures/core.zh.md b/docs/subsystems/core.zh.md similarity index 100% rename from docs/core-data-structures/core.zh.md rename to docs/subsystems/core.zh.md diff --git a/docs/core-data-structures/credentials.i18n.yaml b/docs/subsystems/credentials.i18n.yaml similarity index 80% rename from docs/core-data-structures/credentials.i18n.yaml rename to docs/subsystems/credentials.i18n.yaml index d44275d97e..f7899eaf6e 100644 --- a/docs/core-data-structures/credentials.i18n.yaml +++ b/docs/subsystems/credentials.i18n.yaml @@ -1,6 +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 docs/core-data-structures/credentials.md +# pnpm run verify-translation-pairing --write docs/subsystems/credentials.md credentials.md: ef74ddeb4346e18f8d5d33488657e5d50f1d754e credentials.zh.md: 09cf374a2346fd93aa834e3372321e6eeece6ed8 diff --git a/docs/core-data-structures/credentials.md b/docs/subsystems/credentials.md similarity index 100% rename from docs/core-data-structures/credentials.md rename to docs/subsystems/credentials.md diff --git a/docs/core-data-structures/credentials.zh.md b/docs/subsystems/credentials.zh.md similarity index 100% rename from docs/core-data-structures/credentials.zh.md rename to docs/subsystems/credentials.zh.md diff --git a/docs/core-data-structures/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml similarity index 100% rename from docs/core-data-structures/filesystem.i18n.yaml rename to docs/subsystems/filesystem.i18n.yaml diff --git a/docs/core-data-structures/filesystem.md b/docs/subsystems/filesystem.md similarity index 100% rename from docs/core-data-structures/filesystem.md rename to docs/subsystems/filesystem.md diff --git a/docs/core-data-structures/filesystem.zh.md b/docs/subsystems/filesystem.zh.md similarity index 100% rename from docs/core-data-structures/filesystem.zh.md rename to docs/subsystems/filesystem.zh.md diff --git a/docs/core-data-structures/goal.i18n.yaml b/docs/subsystems/goal.i18n.yaml similarity index 100% rename from docs/core-data-structures/goal.i18n.yaml rename to docs/subsystems/goal.i18n.yaml diff --git a/docs/core-data-structures/goal.md b/docs/subsystems/goal.md similarity index 100% rename from docs/core-data-structures/goal.md rename to docs/subsystems/goal.md diff --git a/docs/core-data-structures/goal.zh.md b/docs/subsystems/goal.zh.md similarity index 100% rename from docs/core-data-structures/goal.zh.md rename to docs/subsystems/goal.zh.md diff --git a/docs/core-data-structures/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml similarity index 80% rename from docs/core-data-structures/llm-streaming.i18n.yaml rename to docs/subsystems/llm-streaming.i18n.yaml index 7168f9bd85..1ff1a1d42b 100644 --- a/docs/core-data-structures/llm-streaming.i18n.yaml +++ b/docs/subsystems/llm-streaming.i18n.yaml @@ -1,6 +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 docs/core-data-structures/llm-streaming.md +# pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md llm-streaming.md: 5c90b3ce4ac65a99997f6ba7ad5deac494b7f772 llm-streaming.zh.md: 7fd0043234cb40d6b21cec6ff101993164785a6e diff --git a/docs/core-data-structures/llm-streaming.md b/docs/subsystems/llm-streaming.md similarity index 100% rename from docs/core-data-structures/llm-streaming.md rename to docs/subsystems/llm-streaming.md diff --git a/docs/core-data-structures/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md similarity index 100% rename from docs/core-data-structures/llm-streaming.zh.md rename to docs/subsystems/llm-streaming.zh.md diff --git a/docs/core-data-structures/lsp.i18n.yaml b/docs/subsystems/lsp.i18n.yaml similarity index 100% rename from docs/core-data-structures/lsp.i18n.yaml rename to docs/subsystems/lsp.i18n.yaml diff --git a/docs/core-data-structures/lsp.md b/docs/subsystems/lsp.md similarity index 100% rename from docs/core-data-structures/lsp.md rename to docs/subsystems/lsp.md diff --git a/docs/core-data-structures/lsp.zh.md b/docs/subsystems/lsp.zh.md similarity index 100% rename from docs/core-data-structures/lsp.zh.md rename to docs/subsystems/lsp.zh.md diff --git a/docs/core-data-structures/persistence.i18n.yaml b/docs/subsystems/persistence.i18n.yaml similarity index 80% rename from docs/core-data-structures/persistence.i18n.yaml rename to docs/subsystems/persistence.i18n.yaml index eccd3f146e..697094b490 100644 --- a/docs/core-data-structures/persistence.i18n.yaml +++ b/docs/subsystems/persistence.i18n.yaml @@ -1,6 +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 docs/core-data-structures/persistence.md +# pnpm run verify-translation-pairing --write docs/subsystems/persistence.md persistence.md: 177d596d3d01134266f139b47430e1e5064d04d6 persistence.zh.md: 6582c0d7d02d1976d5c3ca3322284098130ed4ad diff --git a/docs/core-data-structures/persistence.md b/docs/subsystems/persistence.md similarity index 100% rename from docs/core-data-structures/persistence.md rename to docs/subsystems/persistence.md diff --git a/docs/core-data-structures/persistence.zh.md b/docs/subsystems/persistence.zh.md similarity index 100% rename from docs/core-data-structures/persistence.zh.md rename to docs/subsystems/persistence.zh.md diff --git a/docs/core-data-structures/pty.i18n.yaml b/docs/subsystems/pty.i18n.yaml similarity index 100% rename from docs/core-data-structures/pty.i18n.yaml rename to docs/subsystems/pty.i18n.yaml diff --git a/docs/core-data-structures/pty.md b/docs/subsystems/pty.md similarity index 100% rename from docs/core-data-structures/pty.md rename to docs/subsystems/pty.md diff --git a/docs/core-data-structures/pty.zh.md b/docs/subsystems/pty.zh.md similarity index 100% rename from docs/core-data-structures/pty.zh.md rename to docs/subsystems/pty.zh.md diff --git a/docs/core-data-structures/sandbox.i18n.yaml b/docs/subsystems/sandbox.i18n.yaml similarity index 100% rename from docs/core-data-structures/sandbox.i18n.yaml rename to docs/subsystems/sandbox.i18n.yaml diff --git a/docs/core-data-structures/sandbox.md b/docs/subsystems/sandbox.md similarity index 100% rename from docs/core-data-structures/sandbox.md rename to docs/subsystems/sandbox.md diff --git a/docs/core-data-structures/sandbox.zh.md b/docs/subsystems/sandbox.zh.md similarity index 100% rename from docs/core-data-structures/sandbox.zh.md rename to docs/subsystems/sandbox.zh.md diff --git a/docs/core-data-structures/scope.i18n.yaml b/docs/subsystems/scope.i18n.yaml similarity index 100% rename from docs/core-data-structures/scope.i18n.yaml rename to docs/subsystems/scope.i18n.yaml diff --git a/docs/core-data-structures/scope.md b/docs/subsystems/scope.md similarity index 100% rename from docs/core-data-structures/scope.md rename to docs/subsystems/scope.md diff --git a/docs/core-data-structures/scope.zh.md b/docs/subsystems/scope.zh.md similarity index 100% rename from docs/core-data-structures/scope.zh.md rename to docs/subsystems/scope.zh.md diff --git a/docs/core-data-structures/session-query.i18n.yaml b/docs/subsystems/session-query.i18n.yaml similarity index 100% rename from docs/core-data-structures/session-query.i18n.yaml rename to docs/subsystems/session-query.i18n.yaml diff --git a/docs/core-data-structures/session-query.md b/docs/subsystems/session-query.md similarity index 100% rename from docs/core-data-structures/session-query.md rename to docs/subsystems/session-query.md diff --git a/docs/core-data-structures/session-query.zh.md b/docs/subsystems/session-query.zh.md similarity index 100% rename from docs/core-data-structures/session-query.zh.md rename to docs/subsystems/session-query.zh.md diff --git a/docs/core-data-structures/session-reference.i18n.yaml b/docs/subsystems/session-reference.i18n.yaml similarity index 79% rename from docs/core-data-structures/session-reference.i18n.yaml rename to docs/subsystems/session-reference.i18n.yaml index 85bbcf8877..f119c67913 100644 --- a/docs/core-data-structures/session-reference.i18n.yaml +++ b/docs/subsystems/session-reference.i18n.yaml @@ -1,6 +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 docs/core-data-structures/session-reference.md +# pnpm run verify-translation-pairing --write docs/subsystems/session-reference.md session-reference.md: 5375677f6a1748909743ca76d5191cb9e736a40a session-reference.zh.md: 3ff4a1719926bda0a9111482a7778a8c94553370 diff --git a/docs/core-data-structures/session-reference.md b/docs/subsystems/session-reference.md similarity index 100% rename from docs/core-data-structures/session-reference.md rename to docs/subsystems/session-reference.md diff --git a/docs/core-data-structures/session-reference.zh.md b/docs/subsystems/session-reference.zh.md similarity index 100% rename from docs/core-data-structures/session-reference.zh.md rename to docs/subsystems/session-reference.zh.md diff --git a/docs/core-data-structures/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml similarity index 80% rename from docs/core-data-structures/session-title.i18n.yaml rename to docs/subsystems/session-title.i18n.yaml index ed9955472c..c85d4dfac1 100644 --- a/docs/core-data-structures/session-title.i18n.yaml +++ b/docs/subsystems/session-title.i18n.yaml @@ -1,6 +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 docs/core-data-structures/session-title.md +# pnpm run verify-translation-pairing --write docs/subsystems/session-title.md session-title.md: 7bced67f07df3f00471f02b766922cdc3e4fd29e session-title.zh.md: e8e501d3aafee49395da3d9a8efd4e91a724f09e diff --git a/docs/core-data-structures/session-title.md b/docs/subsystems/session-title.md similarity index 100% rename from docs/core-data-structures/session-title.md rename to docs/subsystems/session-title.md diff --git a/docs/core-data-structures/session-title.zh.md b/docs/subsystems/session-title.zh.md similarity index 100% rename from docs/core-data-structures/session-title.zh.md rename to docs/subsystems/session-title.zh.md diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/subsystems/session.i18n.yaml similarity index 80% rename from docs/core-data-structures/session.i18n.yaml rename to docs/subsystems/session.i18n.yaml index 16e969bd94..dd7135e8d3 100644 --- a/docs/core-data-structures/session.i18n.yaml +++ b/docs/subsystems/session.i18n.yaml @@ -1,6 +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 docs/core-data-structures/session.md +# pnpm run verify-translation-pairing --write docs/subsystems/session.md session.md: 5d54b03df8ec3345e8bf04702f242e3aacf8ec39 session.zh.md: 5a867cfe302bf02994bfe5a5a704bed55222e8ea diff --git a/docs/core-data-structures/session.md b/docs/subsystems/session.md similarity index 100% rename from docs/core-data-structures/session.md rename to docs/subsystems/session.md diff --git a/docs/core-data-structures/session.zh.md b/docs/subsystems/session.zh.md similarity index 100% rename from docs/core-data-structures/session.zh.md rename to docs/subsystems/session.zh.md diff --git a/docs/core-data-structures/settings.i18n.yaml b/docs/subsystems/settings.i18n.yaml similarity index 80% rename from docs/core-data-structures/settings.i18n.yaml rename to docs/subsystems/settings.i18n.yaml index cf262dc1e9..f4518f4414 100644 --- a/docs/core-data-structures/settings.i18n.yaml +++ b/docs/subsystems/settings.i18n.yaml @@ -1,6 +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 docs/core-data-structures/settings.md +# pnpm run verify-translation-pairing --write docs/subsystems/settings.md settings.md: bd01c1d28407af9cab26f624a054a010e25a3ddd settings.zh.md: 1cb7f8b507f29f2b6876fd48b4c37284df235e53 diff --git a/docs/core-data-structures/settings.md b/docs/subsystems/settings.md similarity index 100% rename from docs/core-data-structures/settings.md rename to docs/subsystems/settings.md diff --git a/docs/core-data-structures/settings.zh.md b/docs/subsystems/settings.zh.md similarity index 100% rename from docs/core-data-structures/settings.zh.md rename to docs/subsystems/settings.zh.md diff --git a/docs/core-data-structures/skills.i18n.yaml b/docs/subsystems/skills.i18n.yaml similarity index 80% rename from docs/core-data-structures/skills.i18n.yaml rename to docs/subsystems/skills.i18n.yaml index d0ce7b7574..6ab9693cca 100644 --- a/docs/core-data-structures/skills.i18n.yaml +++ b/docs/subsystems/skills.i18n.yaml @@ -1,6 +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 docs/core-data-structures/skills.md +# pnpm run verify-translation-pairing --write docs/subsystems/skills.md skills.md: d862cbc07135680c2377b4c8c82c80d055344221 skills.zh.md: 3f8c034ec2aa24b4acdbbc1e2ac27717c21649d5 diff --git a/docs/core-data-structures/skills.md b/docs/subsystems/skills.md similarity index 100% rename from docs/core-data-structures/skills.md rename to docs/subsystems/skills.md diff --git a/docs/core-data-structures/skills.zh.md b/docs/subsystems/skills.zh.md similarity index 100% rename from docs/core-data-structures/skills.zh.md rename to docs/subsystems/skills.zh.md diff --git a/docs/core-data-structures/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml similarity index 100% rename from docs/core-data-structures/spill.i18n.yaml rename to docs/subsystems/spill.i18n.yaml diff --git a/docs/core-data-structures/spill.md b/docs/subsystems/spill.md similarity index 100% rename from docs/core-data-structures/spill.md rename to docs/subsystems/spill.md diff --git a/docs/core-data-structures/spill.zh.md b/docs/subsystems/spill.zh.md similarity index 100% rename from docs/core-data-structures/spill.zh.md rename to docs/subsystems/spill.zh.md diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml similarity index 100% rename from docs/core-data-structures/subagent.i18n.yaml rename to docs/subsystems/subagent.i18n.yaml diff --git a/docs/core-data-structures/subagent.md b/docs/subsystems/subagent.md similarity index 100% rename from docs/core-data-structures/subagent.md rename to docs/subsystems/subagent.md diff --git a/docs/core-data-structures/subagent.zh.md b/docs/subsystems/subagent.zh.md similarity index 100% rename from docs/core-data-structures/subagent.zh.md rename to docs/subsystems/subagent.zh.md diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/subsystems/subprocess.i18n.yaml similarity index 100% rename from docs/core-data-structures/subprocess.i18n.yaml rename to docs/subsystems/subprocess.i18n.yaml diff --git a/docs/core-data-structures/subprocess.md b/docs/subsystems/subprocess.md similarity index 100% rename from docs/core-data-structures/subprocess.md rename to docs/subsystems/subprocess.md diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/subsystems/subprocess.zh.md similarity index 100% rename from docs/core-data-structures/subprocess.zh.md rename to docs/subsystems/subprocess.zh.md diff --git a/docs/core-data-structures/system-prompt.i18n.yaml b/docs/subsystems/system-prompt.i18n.yaml similarity index 80% rename from docs/core-data-structures/system-prompt.i18n.yaml rename to docs/subsystems/system-prompt.i18n.yaml index 8d9cd0897f..5c39e3cbcb 100644 --- a/docs/core-data-structures/system-prompt.i18n.yaml +++ b/docs/subsystems/system-prompt.i18n.yaml @@ -1,6 +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 docs/core-data-structures/system-prompt.md +# pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md system-prompt.md: 59193c1881abcadbc8a1778cde92f5a6572eee24 system-prompt.zh.md: 41e45417817895ccf6def70e510eca7422a65e41 diff --git a/docs/core-data-structures/system-prompt.md b/docs/subsystems/system-prompt.md similarity index 100% rename from docs/core-data-structures/system-prompt.md rename to docs/subsystems/system-prompt.md diff --git a/docs/core-data-structures/system-prompt.zh.md b/docs/subsystems/system-prompt.zh.md similarity index 100% rename from docs/core-data-structures/system-prompt.zh.md rename to docs/subsystems/system-prompt.zh.md diff --git a/docs/core-data-structures/tasks.i18n.yaml b/docs/subsystems/tasks.i18n.yaml similarity index 100% rename from docs/core-data-structures/tasks.i18n.yaml rename to docs/subsystems/tasks.i18n.yaml diff --git a/docs/core-data-structures/tasks.md b/docs/subsystems/tasks.md similarity index 100% rename from docs/core-data-structures/tasks.md rename to docs/subsystems/tasks.md diff --git a/docs/core-data-structures/tasks.zh.md b/docs/subsystems/tasks.zh.md similarity index 100% rename from docs/core-data-structures/tasks.zh.md rename to docs/subsystems/tasks.zh.md diff --git a/docs/core-data-structures/token-meter.i18n.yaml b/docs/subsystems/token-meter.i18n.yaml similarity index 100% rename from docs/core-data-structures/token-meter.i18n.yaml rename to docs/subsystems/token-meter.i18n.yaml diff --git a/docs/core-data-structures/token-meter.md b/docs/subsystems/token-meter.md similarity index 100% rename from docs/core-data-structures/token-meter.md rename to docs/subsystems/token-meter.md diff --git a/docs/core-data-structures/token-meter.zh.md b/docs/subsystems/token-meter.zh.md similarity index 100% rename from docs/core-data-structures/token-meter.zh.md rename to docs/subsystems/token-meter.zh.md diff --git a/docs/core-data-structures/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml similarity index 80% rename from docs/core-data-structures/tools.i18n.yaml rename to docs/subsystems/tools.i18n.yaml index cd2add6a82..a30f122038 100644 --- a/docs/core-data-structures/tools.i18n.yaml +++ b/docs/subsystems/tools.i18n.yaml @@ -1,6 +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 docs/core-data-structures/tools.md +# pnpm run verify-translation-pairing --write docs/subsystems/tools.md tools.md: 853eed16cff451edcc32bc3aa5c6bc7cabb0f518 tools.zh.md: ec8809f6bebd185404828c5c5879f8eff832ea9a diff --git a/docs/core-data-structures/tools.md b/docs/subsystems/tools.md similarity index 100% rename from docs/core-data-structures/tools.md rename to docs/subsystems/tools.md diff --git a/docs/core-data-structures/tools.zh.md b/docs/subsystems/tools.zh.md similarity index 100% rename from docs/core-data-structures/tools.zh.md rename to docs/subsystems/tools.zh.md diff --git a/docs/core-data-structures/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml similarity index 100% rename from docs/core-data-structures/typert.i18n.yaml rename to docs/subsystems/typert.i18n.yaml diff --git a/docs/core-data-structures/typert.md b/docs/subsystems/typert.md similarity index 100% rename from docs/core-data-structures/typert.md rename to docs/subsystems/typert.md diff --git a/docs/core-data-structures/typert.zh.md b/docs/subsystems/typert.zh.md similarity index 100% rename from docs/core-data-structures/typert.zh.md rename to docs/subsystems/typert.zh.md diff --git a/docs/core-data-structures/user-interaction.i18n.yaml b/docs/subsystems/user-interaction.i18n.yaml similarity index 79% rename from docs/core-data-structures/user-interaction.i18n.yaml rename to docs/subsystems/user-interaction.i18n.yaml index 3768cfcf7b..80ebb810c8 100644 --- a/docs/core-data-structures/user-interaction.i18n.yaml +++ b/docs/subsystems/user-interaction.i18n.yaml @@ -1,6 +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 docs/core-data-structures/user-interaction.md +# pnpm run verify-translation-pairing --write docs/subsystems/user-interaction.md user-interaction.md: ec22eb28e9554d6454bf2670f73f2e9b199df014 user-interaction.zh.md: 814f8911e41aecf568f627f76f8239bac4ea719b diff --git a/docs/core-data-structures/user-interaction.md b/docs/subsystems/user-interaction.md similarity index 100% rename from docs/core-data-structures/user-interaction.md rename to docs/subsystems/user-interaction.md diff --git a/docs/core-data-structures/user-interaction.zh.md b/docs/subsystems/user-interaction.zh.md similarity index 100% rename from docs/core-data-structures/user-interaction.zh.md rename to docs/subsystems/user-interaction.zh.md diff --git a/docs/core-data-structures/web.i18n.yaml b/docs/subsystems/web.i18n.yaml similarity index 100% rename from docs/core-data-structures/web.i18n.yaml rename to docs/subsystems/web.i18n.yaml diff --git a/docs/core-data-structures/web.md b/docs/subsystems/web.md similarity index 100% rename from docs/core-data-structures/web.md rename to docs/subsystems/web.md diff --git a/docs/core-data-structures/web.zh.md b/docs/subsystems/web.zh.md similarity index 100% rename from docs/core-data-structures/web.zh.md rename to docs/subsystems/web.zh.md diff --git a/docs/core-data-structures/workflow.i18n.yaml b/docs/subsystems/workflow.i18n.yaml similarity index 100% rename from docs/core-data-structures/workflow.i18n.yaml rename to docs/subsystems/workflow.i18n.yaml diff --git a/docs/core-data-structures/workflow.md b/docs/subsystems/workflow.md similarity index 100% rename from docs/core-data-structures/workflow.md rename to docs/subsystems/workflow.md diff --git a/docs/core-data-structures/workflow.zh.md b/docs/subsystems/workflow.zh.md similarity index 100% rename from docs/core-data-structures/workflow.zh.md rename to docs/subsystems/workflow.zh.md diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 699617eef4..a100469102 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -3,7 +3,7 @@ # Tool Schema Catalog -Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered. +Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered. This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md). diff --git a/packages/bash/bash/README.i18n.yaml b/packages/bash/bash/README.i18n.yaml index 978de64ed1..eee269c121 100644 --- a/packages/bash/bash/README.i18n.yaml +++ b/packages/bash/bash/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 packages/bash/bash/README.md -README.md: 88f519a21a0889d6b7649502c51077940c23709f -README.zh.md: 294044692133da8baa57583146352e84c1ff9946 +README.md: 690f4e61740faf2648ecbc7f5995ec0fdaa64aee +README.zh.md: c343e17bfd97eaf17316c034c263b0c71bb8327a diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md index 88f519a21a..690f4e6174 100644 --- a/packages/bash/bash/README.md +++ b/packages/bash/bash/README.md @@ -31,7 +31,7 @@ Implementations subclass `BashExecutor` and implement the abstract methods. Disp `BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, dshEnv?, sandboxPolicy?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, dshEnv?, sandboxPolicy) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxPolicy` is optional on the request and required-but-nullable on the resolved spec: it carries the complete per-call mode and workspace root. The sandbox tool path resolves it from the calling session through `ctx.sandboxPolicy`; a direct sandbox-executor caller falls back to deployment policy, while a non-sandboxing executor carries the field and confines nothing. -The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md). +The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, the `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path) is NOT here — it is policy state shared by every enforcing family, owned by [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/). `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [subsystems/bash.md](../../../docs/subsystems/bash.md). `stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md). diff --git a/packages/bash/bash/README.zh.md b/packages/bash/bash/README.zh.md index 2940446921..c343e17bfd 100644 --- a/packages/bash/bash/README.zh.md +++ b/packages/bash/bash/README.zh.md @@ -31,7 +31,7 @@ `BashExecRequest`（command、workdir?、timeoutMs?、stdoutMaxBytes?、signal?、stdin?、env?、dshEnv?、sandboxPolicy?）在执行前解析为 `BashExecSpec`（command、workdir、timeoutMs、stdoutMaxBytes、signal?、stdin?、env?、dshEnv?、sandboxPolicy）。`stdoutMaxBytes` 是受信任前台运行的捕获预算，用于必须解析完整有界 stdout 的消费方；面向模型的 bash 工具不公开该字段。`sandboxPolicy` 在请求上可选，在已解析 spec 上必填但可为 null：它携带完整的每次调用模式与工作区根目录。沙箱工具路径通过 `ctx.sandboxPolicy` 从调用会话解析它；沙箱执行器的直接调用方回退到部署策略，非沙箱执行器则携带该字段但不作限制。 -每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md)。 +每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [subsystems/bash.md](../../../docs/subsystems/bash.md)。 `stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。 diff --git a/packages/compact/compact/README.i18n.yaml b/packages/compact/compact/README.i18n.yaml index 1ab398842f..1252d99e0f 100644 --- a/packages/compact/compact/README.i18n.yaml +++ b/packages/compact/compact/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 packages/compact/compact/README.md -README.md: 5703540435b976cfc03987edca28e2b5cd24ae0d -README.zh.md: 434b9bfa3d0d7f21fc262929ac72ff5ab15d5057 +README.md: 2bf39cac91798b1e0fdb679d2a9b674caceffe22 +README.zh.md: 330b5b0cb9d5c2bf3953354112f3488447e71f87 diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md index 5703540435..2bf39cac91 100644 --- a/packages/compact/compact/README.md +++ b/packages/compact/compact/README.md @@ -24,7 +24,7 @@ All three operations are **abstract** — the backend owns trigger policy, reten | `compactNow(agent, signal)` | Explicitly compact one useful balanced older span even below automatic pressure. It synchronously reserves idle turn admission before yielding, writes nothing when no useful span exists, records a standalone `compact/* { turn: null }` attempt before summarization, and awaits its durability checkpoint before release. Expected operational failures use `ManualCompactionError`; cancellation rethrows the exact abort reason. | | `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source is `COMPACT_CHECKPOINT_SOURCE`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. | -`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/core-data-structures/compaction.md#compactionresult). +`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/subsystems/compaction.md#compactionresult). `compactIfNeeded` and `compactNow` take a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization. Automatic and explicit-region brackets recover their numeric owner from the currently open turn. Manual brackets require no open turn and stamp `turn: null`. diff --git a/packages/compact/compact/README.zh.md b/packages/compact/compact/README.zh.md index 434b9bfa3d..330b5b0cb9 100644 --- a/packages/compact/compact/README.zh.md +++ b/packages/compact/compact/README.zh.md @@ -24,7 +24,7 @@ | `compactNow(agent, signal)` | 即使未达到自动压力，也显式压缩一段有效、平衡的较早范围。该操作会在让出控制权前同步预留空闲轮次接纳；没有有效范围时不写入任何内容；在摘要前记录独立的 `compact/* { turn: null }` 尝试；释放预留前等待其持久性检查点。预期操作失败使用 `ManualCompactionError`；取消会原样重新抛出 abort 原因。 | | `compactRegion(start, end, agent, signal?)` | 强制将表层节点 `[start, end]`（包含两端 seq）从 `agent.session` 摘要为单个替换节点，其源为 `COMPACT_CHECKPOINT_SOURCE`。如果压缩已在进行、`start`／`end` 不是表层节点，或 `start` 在表层上位于 `end` 之后，则**抛出异常**。该范围是表层位置范围，不是数值 seq 区间：在之前的 replace 将新生成的高 seq 摘要节点放到已遮蔽范围的位置之后，表层顺序不再跟随 seq 顺序。 | -`CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/core-data-structures/compaction.md#compactionresult)。 +`CompactionResult` 向调用方保留原始摘要与记录操作过程的事件 seq，同时保留已遮蔽范围与 token 计量；其结构由漂移检查保障，定义见 [压缩数据结构参考](../../../docs/subsystems/compaction.md#compactionresult)。 `compactIfNeeded` 和 `compactNow` 必须传入 `signal`；`compactRegion` 的该参数可选。通过 `ctx.llm.stream()` 摘要的后端**必须** 将它转发到调用的 `GenerateOptions.signal`，因此 abort 或 fiber dispose（资源释放）会停止进行中的摘要。自动和显式范围标记对会从当前打开的轮次恢复其数字形式归属。手动标记对不要求存在打开的轮次，并标记 `turn: null`。 diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml index 0b2d50957e..c30b37e549 100644 --- a/packages/core/session/README.i18n.yaml +++ b/packages/core/session/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 packages/core/session/README.md -README.md: e2c014a1448125b23475d6cdf52c02f10fc54794 -README.zh.md: a4aeead796961bd66a6c7ca1f9a66dffb60eba5d +README.md: 07ee53006b390e5ad3979502b2f1aa24f5a6ce7a +README.zh.md: d4a90de10b92a489f8f575b926d758b45d8f5051 diff --git a/packages/core/session/README.md b/packages/core/session/README.md index e2c014a144..07ee53006b 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -56,7 +56,7 @@ The shared [storage codec](src/chunk-rows.ts) losslessly converts event sequence ### Surface types -This package owns ordered surface projection, replacement validation, replay, and the type guards that distinguish append-origin from replacement events. The [surface type catalog](../../../docs/core-data-structures/session.md#surface-types) owns the exact shapes and field semantics. A human transcript must project append-origin events rather than `session.surface`, because landed replacements shadow history the reader already saw; model-facing consumers continue to read `session.surface`. +This package owns ordered surface projection, replacement validation, replay, and the type guards that distinguish append-origin from replacement events. The [surface type catalog](../../../docs/subsystems/session.md#surface-types) owns the exact shapes and field semantics. A human transcript must project append-origin events rather than `session.surface`, because landed replacements shadow history the reader already saw; model-facing consumers continue to read `session.surface`. ### Request-header reconstruction (`request-header.ts`) diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md index a4aeead796..d4a90de10b 100644 --- a/packages/core/session/README.zh.md +++ b/packages/core/session/README.zh.md @@ -56,7 +56,7 @@ ### Surface 类型 -此包拥有有序 surface 投影、替换校验、回放，以及区分追加来源事件与替换事件的类型守卫。[surface 类型目录](../../../docs/core-data-structures/session.md#surface-types)拥有精确形状与字段语义。面向人的 transcript（文本记录）必须投影追加来源事件，而不是 `session.surface`，因为已落地的替换会遮蔽读者已经看到的历史；面向模型的消费方继续读取 `session.surface`。 +此包拥有有序 surface 投影、替换校验、回放，以及区分追加来源事件与替换事件的类型守卫。[surface 类型目录](../../../docs/subsystems/session.md#surface-types)拥有精确形状与字段语义。面向人的 transcript（文本记录）必须投影追加来源事件，而不是 `session.surface`，因为已落地的替换会遮蔽读者已经看到的历史；面向模型的消费方继续读取 `session.surface`。 ### 请求头重建（`request-header.ts`） diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index b49350c1a3..657de4578e 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -39,7 +39,7 @@ import { renderToolsSdkPy } from './py-types.ts' * the flavor table is checked against too, so any of the three left out is a * typecheck failure. What no check reaches is the prose that names the values * instead of deriving them: the seam's `dsh-code-runtime` README pair, its - * `CodeRuntime.language` JSDoc, and `docs/core-data-structures/code-runtime.md` + * `CodeRuntime.language` JSDoc, and `docs/subsystems/code-runtime.md` * with its zh pair, plus this package's own README pair and the * {@link Config.mode} JSDoc. */ diff --git a/packages/goal/goal/README.i18n.yaml b/packages/goal/goal/README.i18n.yaml index d918caf377..6362a6d1e9 100644 --- a/packages/goal/goal/README.i18n.yaml +++ b/packages/goal/goal/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 packages/goal/goal/README.md -README.md: fc2a672c11c68ad72437251b087a274e1c4388d3 -README.zh.md: eaaae5b333151b1d936effc593b21cac515471e2 +README.md: fc2fd8791096bcc9077ef7972da86b0e07c6f18e +README.zh.md: 311ec1d03436cc45bbea28df96e66579852058b0 diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md index fc2a672c11..fc2fd87910 100644 --- a/packages/goal/goal/README.md +++ b/packages/goal/goal/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -Event-sourced same-session goal state. The service retains one current completion objective in an agent's existing session while keeping permission to continue as process-local activation. The [goal-domain Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) owns the design rationale; the [goal type catalog](../../../docs/core-data-structures/goal.md) records the literal data shapes. +Event-sourced same-session goal state. The service retains one current completion objective in an agent's existing session while keeping permission to continue as process-local activation. The [goal-domain Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) owns the design rationale; the [goal type catalog](../../../docs/subsystems/goal.md) records the literal data shapes. ## Config diff --git a/packages/goal/goal/README.zh.md b/packages/goal/goal/README.zh.md index eaaae5b333..311ec1d034 100644 --- a/packages/goal/goal/README.zh.md +++ b/packages/goal/goal/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/core-data-structures/goal.md)记录具体的数据形状。 +事件溯源的同会话目标状态。该服务在 agent（智能体）的现有会话中保留一个当前完成目标，同时将继续执行的权限作为进程本地续行启用状态。[goal 领域 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-persisted-same-session-goal-domain.md) 负责设计理由；[goal 类型目录](../../../docs/subsystems/goal.md)记录具体的数据形状。 ## 配置 diff --git a/packages/sandbox/sandbox/README.i18n.yaml b/packages/sandbox/sandbox/README.i18n.yaml index 11f2a2ed86..99a5265418 100644 --- a/packages/sandbox/sandbox/README.i18n.yaml +++ b/packages/sandbox/sandbox/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 packages/sandbox/sandbox/README.md -README.md: 1b522b2c72d00bfed89650aa7f22b65a72d26085 -README.zh.md: adccd4421a74ef073ad3ffc3a23bccb0354d99aa +README.md: 8c1c747f6c7178f9c8c1a9827675ffa98f29aa6d +README.zh.md: e43d1918a99fa96688632551a8f861c2c91f9c2a diff --git a/packages/sandbox/sandbox/README.md b/packages/sandbox/sandbox/README.md index 1b522b2c72..8c1c747f6c 100644 --- a/packages/sandbox/sandbox/README.md +++ b/packages/sandbox/sandbox/README.md @@ -4,7 +4,7 @@ English | [中文](README.zh.md) Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend. -The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape. +The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape. Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy. diff --git a/packages/sandbox/sandbox/README.zh.md b/packages/sandbox/sandbox/README.zh.md index adccd4421a..e43d1918a9 100644 --- a/packages/sandbox/sandbox/README.zh.md +++ b/packages/sandbox/sandbox/README.zh.md @@ -4,7 +4,7 @@ 抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。 -用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。 +用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/subsystems/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。 diff --git a/packages/session/session-title/README.i18n.yaml b/packages/session/session-title/README.i18n.yaml index b13c6ce917..f45602ce97 100644 --- a/packages/session/session-title/README.i18n.yaml +++ b/packages/session/session-title/README.i18n.yaml @@ -1,6 +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 packages/session-title/session-title/README.md -README.md: 9a5ec27c36f3411add37ebe231262eb5d205bc9e -README.zh.md: 3960be40e74507279ed2f21927ee8ad4224fe138 +# pnpm run verify-translation-pairing --write packages/session/session-title/README.md +README.md: 13a2a1c298c3abb8c8987b9373edc46a071ce9db +README.zh.md: 9e271c044033ce17b5c8c744fe7a9cf433c7f473 diff --git a/packages/session/session-title/README.md b/packages/session/session-title/README.md index 9a5ec27c36..13a2a1c298 100644 --- a/packages/session/session-title/README.md +++ b/packages/session/session-title/README.md @@ -31,7 +31,7 @@ All limits are required; the library supplies no defaults. A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and optional model provenance. The service normalizes and validates the result before it becomes durable. -See the [session-title data structures](../../../docs/core-data-structures/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md). +See the [session-title data structures](../../../docs/subsystems/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md). ## Model Experience diff --git a/packages/session/session-title/README.zh.md b/packages/session/session-title/README.zh.md index 3960be40e7..9e271c0440 100644 --- a/packages/session/session-title/README.zh.md +++ b/packages/session/session-title/README.zh.md @@ -31,7 +31,7 @@ Fork 出的会话会原样继承种子中的标题事件。首消息节奏不会 提供方会提供带品牌类型的稳定 id、自动模式（`first-message` 或 `all-user-messages`）和 `generate(request)`。请求携带活跃会话、截至一次固定修订的所有符合条件消息、可用时当前已记录的主请求路由，以及取消信号。结果包含非空标题、该请求中唯一且有序的来源消息 seq，以及可选的模型来源信息。服务会在结果持久保存前进行规范化和验证。 -参见[会话标题数据结构](../../../docs/core-data-structures/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。 +参见[会话标题数据结构](../../../docs/subsystems/session-title.md)与[已实现决策](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)。 ## 模型体验 diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml index e67bf1a87f..86694c3c23 100644 --- a/packages/subprocess/subprocess/README.i18n.yaml +++ b/packages/subprocess/subprocess/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 packages/subprocess/subprocess/README.md -README.md: ec4a4e3328a5a600441d2e7983b3844f4ccc5e91 -README.zh.md: 3da79995fad9a2c8f2a6020ae18152a0e4459c71 +README.md: 6e4b9a9c50bc54a4752930ec14269d2c15233a76 +README.zh.md: d756cd9b7117d7ce9a2e79c6469d9fc188c9600b diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md index ec4a4e3328..6e4b9a9c50 100644 --- a/packages/subprocess/subprocess/README.md +++ b/packages/subprocess/subprocess/README.md @@ -15,7 +15,7 @@ The subprocess seam (`ctx.subprocess`) is the process half of one execution worl - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and explicit `env` merges after the scrub. The local ordinary and terminal spawns both apply it; SDK-managed transports that own their spawn may import it directly. - Disposal of the service terminates all still-running managed processes and awaits their exit. -See the [subprocess data-structure catalog](../../../docs/core-data-structures/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md). +See the [subprocess data-structure catalog](../../../docs/subsystems/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md). ## Model Experience diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md index 3da79995fa..d756cd9b71 100644 --- a/packages/subprocess/subprocess/README.zh.md +++ b/packages/subprocess/subprocess/README.zh.md @@ -15,7 +15,7 @@ - `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并。本地的普通 spawn 与终端 spawn 都应用该定义；拥有自身 spawn 的 SDK 管理传输可直接导入它。 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。 -参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。 +参见[子进程数据结构目录](../../../docs/subsystems/subprocess.md)与[seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。 ## 模型体验 diff --git a/packages/tasks/tasks/README.i18n.yaml b/packages/tasks/tasks/README.i18n.yaml index 7ceb8ff432..1d803e486e 100644 --- a/packages/tasks/tasks/README.i18n.yaml +++ b/packages/tasks/tasks/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 packages/tasks/tasks/README.md -README.md: 2f822bad139020f0ebae0165aa4e8893853f635d -README.zh.md: fdc619fbb46267b2ae550c85cb14fcf8a916f638 +README.md: b5a7380e0cb7df5dd20baecea8656db2aad3460a +README.zh.md: f2e4b10d30d81c840f5598141bbe246634bf2884 diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md index 2f822bad13..b5a7380e0c 100644 --- a/packages/tasks/tasks/README.md +++ b/packages/tasks/tasks/README.md @@ -20,7 +20,7 @@ Owned access compares the task's `SessionId` with the caller's. Ids such as `bas Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and control-surface fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters. -See the [task type catalog](../../../docs/core-data-structures/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md). +See the [task type catalog](../../../docs/subsystems/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md). ## Model Experience diff --git a/packages/tasks/tasks/README.zh.md b/packages/tasks/tasks/README.zh.md index fdc619fbb4..f2e4b10d30 100644 --- a/packages/tasks/tasks/README.zh.md +++ b/packages/tasks/tasks/README.zh.md @@ -20,7 +20,7 @@ 实现还必须兑现契约的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。 -参见[任务类型目录](../../../docs/core-data-structures/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。 +参见[任务类型目录](../../../docs/subsystems/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。 ## 模型体验 diff --git a/packages/typert/generator/src/cordis-catalog.ts b/packages/typert/generator/src/cordis-catalog.ts index e5c2c15a00..d62739acdd 100644 --- a/packages/typert/generator/src/cordis-catalog.ts +++ b/packages/typert/generator/src/cordis-catalog.ts @@ -701,7 +701,7 @@ function typeLinks(signature: string, linkedTypePages: Readonly `[${n}](../core-data-structures/${linkedTypePages[n]})`) + const links = [...seen].sort().map(n => `[${n}](../subsystems/${linkedTypePages[n]})`) return `Types: ${links.join(' · ')}` } @@ -756,7 +756,7 @@ export function renderEvents(events: EventEntry[], policy: CordisCatalogPolicy): ...BANNER, '# Cordis Events Catalog', '', - 'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.', + 'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.` surface is the sibling [services catalog](services.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around.', '', GATE_NOTICE, '', @@ -796,7 +796,7 @@ export function renderServices(services: ServiceEntry[], policy: CordisCatalogPo ...BANNER, '# Cordis Services Catalog', '', - 'Every `ctx.` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.', + 'Every `ctx.` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [subsystems/](../subsystems/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.', '', GATE_NOTICE, '', diff --git a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts index d920ea82ca..edf653c3f4 100644 --- a/packages/typert/generator/tests/cordis-catalog-contract.spec.ts +++ b/packages/typert/generator/tests/cordis-catalog-contract.spec.ts @@ -155,7 +155,7 @@ describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => { ' /**\n * Carry linked and foundation types.\n * @param value - the linked value.\n * @param preset - deployment metadata outside the core catalog.\n * @param signal - cancellation.\n * @mode parallel\n */\n \'fix/typed\'(value: Readonly, preset: PresetSpec, signal: AbortSignal): Promise', )) expect(events).toHaveLength(1) - expect(renderEvents(events)).toContain('Types: [SessionEvent](../core-data-structures/core.md)') + expect(renderEvents(events)).toContain('Types: [SessionEvent](../subsystems/core.md)') expect(renderEvents(events)).not.toContain('[PresetSpec]') }) diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts index 920688df6d..ebceec916b 100644 --- a/scripts/gen-config-catalog.ts +++ b/scripts/gen-config-catalog.ts @@ -777,7 +777,7 @@ function requiresLine(inject: string[]): string { } /** Render one reference as a link: another plugin's config type → its section, - * a curated core-data-structures name → its page, any other workspace type → + * a curated subsystems name → its page, any other workspace type → * its source file, an external type → named with its module, unlinked. */ function refLink(ref: TypeRef, byName: Map): string { const target = byName.get(ref.specifier) @@ -785,7 +785,7 @@ function refLink(ref: TypeRef, byName: Map): string { return `[\`${ref.alias}\`](#${slug(target.pkg)})` } const page = LINK_MAP[ref.imported] - if (page) return `[\`${ref.alias}\`](core-data-structures/${page})` + if (page) return `[\`${ref.alias}\`](subsystems/${page})` if (target) return `[\`${ref.alias}\`](../${target.entry})` return `\`${ref.alias}\` (\`${ref.specifier}\`)` } @@ -819,7 +819,7 @@ export function render(entries: CatalogEntry[]): string { '', '# Plugin Config Catalog', '', - 'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md) documents the types these declarations reference.', + 'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the cordis [events](cordis-catalog/events.md) + [services](cordis-catalog/services.md) catalogs, the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.', '', 'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.', '', diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 302ec7fdd9..d9f3803547 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -18,7 +18,7 @@ const OUT_EVENTS = 'docs/cordis-catalog/events.md' const OUT_SERVICES = 'docs/cordis-catalog/services.md' const OUT_RUNTIME_API = 'packages/self-modification/tool-cordis/src/api-catalog.ts' -/** One primary core-data-structures page per project type used by a generated signature. */ +/** One primary subsystems page per project type used by a generated signature. */ export const LINK_MAP: Readonly> = { Agent: 'core.md', AgentCancelCause: 'core.md', diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index e6d6acbdf2..4f72b1d953 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -1344,7 +1344,7 @@ function renderIndex(docs: GraphDoc[]): string { const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode' return [ ...generatedHeader('Documentation Graph Index'), - 'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md).', + 'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [subsystems/](subsystems/core.md).', '', 'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).', '', diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts index 685e4b65ef..800497ddb7 100644 --- a/scripts/gen-persistence-catalog.ts +++ b/scripts/gen-persistence-catalog.ts @@ -31,7 +31,7 @@ const EVENT_ENVELOPE_TYPE_NAMES = [ type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number] -/** Primary core-data-structures page for linked payload types. */ +/** Primary subsystems page for linked payload types. */ const LINK_MAP: Record = { CallId: 'core.md', ContentBlock: 'core.md', @@ -330,7 +330,7 @@ function typeLinks(payload: string): string { if (new RegExp(`\\b${name}\\b`).test(payload)) seen.add(name) } if (seen.size === 0) return '' - const links = [...seen].sort().map(n => `[${n}](core-data-structures/${LINK_MAP[n]})`) + const links = [...seen].sort().map(n => `[${n}](subsystems/${LINK_MAP[n]})`) return `Types: ${links.join(' · ')}` } @@ -352,11 +352,11 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv '', '# Session Persistence Event Catalog', '', - 'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).', + 'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](subsystems/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](subsystems/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).', '', 'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).', '', - 'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.', + 'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.', '', '## Event envelope', '', diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 55ec5eb57f..39ed4d7620 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -608,7 +608,7 @@ export function render(catalog: ToolCatalog): string { '', '# Tool Schema Catalog', '', - 'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [core-data-structures/](core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.', + 'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the cordis [events](cordis-catalog/events.md) & [services](cordis-catalog/services.md) catalogs (the wiring a plugin listens to and calls) and [subsystems/](subsystems/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.', '', 'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).', '', diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts index 89e417558c..ebdce88f6d 100644 --- a/scripts/project-doc-site.spec.ts +++ b/scripts/project-doc-site.spec.ts @@ -271,7 +271,7 @@ describe('docsPages locale routes', () => { it('projects translated core-data pages while retaining explicit English fallbacks', () => { const rootPages = docsPages.filter(page => ( - page.locale === 'root' && page.route.startsWith('reference/core-data-structures/') + page.locale === 'root' && page.route.startsWith('reference/subsystems/') )) const translated = rootPages.filter(page => page.contentLocale === 'zh-CN') const fallbacks = rootPages.filter(page => page.contentLocale === 'en-US') @@ -279,9 +279,9 @@ describe('docsPages locale routes', () => { expect(translated).toHaveLength(20) expect(translated.every(page => page.source.endsWith('.zh.md'))).toBe(true) expect(fallbacks.map(page => page.source).sort()).toEqual([ - 'docs/core-data-structures/commands.md', - 'docs/core-data-structures/goal.md', - 'docs/core-data-structures/pty.md', + 'docs/subsystems/commands.md', + 'docs/subsystems/goal.md', + 'docs/subsystems/pty.md', ]) }) diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json index 40b3f620e3..3d1ca11612 100644 --- a/scripts/snapshots/translation-prompt-v4/request-response.expected.json +++ b/scripts/snapshots/translation-prompt-v4/request-response.expected.json @@ -16,11 +16,11 @@ }, { "role": "user", - "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n" + "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-config target remains valid from either face, while a split target must name the matching leaf rather than its solution root or opposite leaf. Do not copy this structure to other packages; see the [`api-remotes` README](../packages/api/remotes/README.md) for the complete boundary.\n\nThe root build follows the generated dependency order:\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\nBoth tsdown passes use the same complete workspace match. They neither scan build artifacts to discover Client packages nor maintain a Host/Client package filter list. Package-local tsdown configs select entries for the current phase through `DSH_BUILD_FACE`: an ordinary Client plugin produces both its Node loader and browser bundle during the Client phase; `api-remotes` uses `hostPhase: true` to produce its Host entry early and only its browser bundle during the Client phase. Tsdown consumes only the JavaScript emitted to `lib/types` by the preceding tsc phase.\n\nTypeRT runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start TypeRT. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build. The [API Remotes generated-contract build note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md) records this ordering decision.\n\nStatic analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already owns an explicit dependency on the TypeRT contract pass or the complete build. See the [solution-root note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md) for the two-aggregate topology, the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership, and the [TypeRT Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.\n\nBusiness services declare callable methods on the Host with `@Remote` or `@RemoteScope`; the Host build generates Host-for-Client types and runtime contributions, and the Client's `api-remotes` composition loads those contributions under `ctx.remote` and scoped `agentCtx.remote` namespaces. See [API Gateway](api-gateway.md) for the generated artifacts on both sides, their assembly relationships, the SRC development fallback, and the Web build order.\n\nIf a relevant local check consumes built package output, build once first:\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files, and `verify-node-next-types`, which validates built declarations against a temporary NodeNext consumer. A fresh worktree has no bundled JS or declarations until `pnpm run build` runs; ordinary commits and pushes do not require that build unless their selected checks consume it.\n\n### Environment variables\n\nThe real DeepSeek adapter and key-backed agent demos read credentials from the environment or from a gitignored `.env` at the repo root:\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set.\n\n### Git integrations\n\nThe pairing merge driver derives a conflicted `.i18n.yaml` record from the confirmed ancestor, current, and other owner blobs when both language files use Git's default text strategy and merge cleanly. It fails closed on owner conflicts, non-text merge configuration, or invalid records; after an already-stopped merge, run `pnpm run resolve-translation-pairing-conflicts`, which stages every safe pairing record and exits unsuccessfully if other pairing conflicts still need manual work. See the [bilingual documentation contract](i18n/README.md#the-pairing-contract) for the exact boundary.\n\nThe installer probes the exact Node/tsx driver entrypoint before publishing its worktree configuration. If that runtime later becomes unavailable, the Node-independent launcher writes Git's ordinary text result, leaves the sidecar unresolved, and prints the recovery path; restore dependencies and run `pnpm run resolve-translation-pairing-conflicts`, or run `git merge --abort`. If `pre-merge-commit` rejects an otherwise clean merge, Git leaves the complete result staged without a commit; repair the failure and run `git commit`, or abort. The [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract) owns the exact index and `MERGE_HEAD` states.\n\nlefthook is configured in `lefthook.yml` as a fast local checkpoint:\n\n- `pre-commit` verifies staged pairing records against the staged owner blobs, applies formatting-only ESLint fixes, validates the staged files with the project-free `.oxlintrc.staged.json` profile and applies Oxlint's native fixes, regenerates `THIRD_PARTY_NOTICES.md` when a staged file is one of its inputs, checks the staged diff for whitespace errors, and runs the vendor manifest guard.\n- `pre-merge-commit` performs the same index-backed pairing check before Git creates an automatic merge commit.\n- `pre-push` runs `pnpm run typecheck`, which completes the Host lib phase, including generated TypeRT contracts, before the Client TypeScript check.\n\nThe vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.\n\nApart from the scoped staged-record verification, the hooks intentionally do not run tests, snapshots, documentation checks, builds, or hygiene. Contributors run the [checks relevant to the changed behavior](../AGENTS.md#run-relevant-checks-locally) once; CI owns exhaustive coverage, built-artifact smokes, and the Node 22.19, 24, and 26 compatibility matrix.\n\nContributors can opt into the comprehensive local gate set with `pnpm run check:all`. The command is independent of the Git hooks and is not an agent instruction.\n\n### CI gates\n\nThe keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates into broad lanes and runs a smaller compatibility signal across supported Node versions. Artifact consumers wait for one build within their lane. The separate real-API workflow runs `pnpm run test:e2e` with its configured worker bound. See [scripts/run-gates.ts](../scripts/run-gates.ts) and the workflow files for the current gate and job inventory.\n\n### Daily commands\n\nThe root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.\n\n### Demos\n\nThe one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`:\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\nThe self-referential cordis demo can inspect and modify its live plugin runtime and needs the same credentials (`web` by default, or `acp`):\n\n```sh\npnpm run demo:cordis\n```\n\nThe ACP automation server exposes fresh agent sessions over JSON-RPC stdio and also needs `DEEPSEEK_API_KEY`:\n\n```sh\npnpm run demo:acp\n```\n\n### TODO markers\n\nUse one of three comment tags to flag known issues in the code, ordered by urgency:\n\n- `FIXME` — an issue that should block a new release. A release should not ship with an open `FIXME` unless reviewers explicitly agree the change can be merged anyway.\n- `TODO` — an issue that should be fixed soon, once we have the resources.\n- `XXX` — an issue that we may fix someday; lowest priority, no commitment.\n\nPick the tag that matches the urgency so anyone scanning the code can tell a release blocker from a someday-maybe.\n\n### Documenting types verbatim (`ts type-equiv`)\n\nThe [core data structures](subsystems/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `\"projection\": \"public-api\"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate enforces a 1:1 correspondence by document, symbol, and projection between primary blocks and manifest entries; a paired `.zh.md` block reuses its unsuffixed sibling's entry only when the whole tracked fence sequence is byte-identical and ordered identically. `doc-typecheck` applies the same derivative rule to compilable fences, while skipping both source-equivalence fence kinds from compilation and its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a primary block, update the manifest in the same change.\n" }, { "role": "assistant", - "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/core-data-structures/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n" + "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全契约；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](../packages/api/remotes/README.md)。\n\n根构建按生成依赖排序：\n\n```sh\ntsc -b tsconfig.host.json\ntsdown --env.DSH_BUILD_FACE host\ntsc -b tsconfig.client.json\ntsdown --env.DSH_BUILD_FACE client\npnpm run build:web\n```\n\n两次 tsdown 都使用同一组完整 workspace 匹配，不扫描构建产物来发现 Client package，也不维护 Host/Client package 过滤表。包内 tsdown 配置根据 `DSH_BUILD_FACE` 决定当前阶段的入口：普通 Client plugin 在 Client 阶段同时生成 Node loader 与 browser bundle；`api-remotes` 通过 `hostPhase: true` 提前生成 Host 入口，再在 Client 阶段只生成 browser bundle。tsdown 只消费 `lib/types` 中由前置 tsc 发射的 JavaScript。\n\nTypeRT 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 TypeRT。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。该顺序的决策记录见 [API Remotes 生成契约构建 Note](../.agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.md)。\n\n静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本以调用它的公共命令或调度器门禁已经显式依赖 TypeRT 契约 pass 或完整构建为前提。双 aggregate 拓扑见 [solution-root Note](../.agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.md)，tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md)，门禁准备契约见 [TypeRT Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md)。\n\n业务 Service 在 Host 使用 `@Remote` 或 `@RemoteScope` 声明可调用方法；Host 构建生成 Host-for-Client 类型与运行时贡献，Client 的 `api-remotes` 组合加载这些贡献并挂到 `ctx.remote` 与作用域 `agentCtx.remote` namespace。两侧的生成产物、装配关系、SRC 开发回退和 Web 构建顺序见 [API Gateway](api-gateway.md)。\n\n如果相关的本地检查需要使用构建后的包产物，请先构建一次：\n\n```sh\npnpm run build\n```\n\n`pnpm run hygiene` 包含 `publint`（用构建出的 `lib/*.js` 文件校验 package 入口点）和 `verify-node-next-types`（用一个临时的 NodeNext 消费方校验构建出的声明文件）。新 worktree 在 `pnpm run build` 运行之前没有打包的 JS 和声明文件；普通提交和推送无需构建，除非所选检查会使用这些产物。\n\n### 环境变量\n\n真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：\n\n```sh\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://... # optional\n```\n\n`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。\n\n### Git 集成\n\n当两种语言的文件都使用 Git 默认文本策略且能干净合并时，配对合并驱动会根据已确认的祖先、当前和另一侧的配对文档 blob，推导出发生冲突的 `.i18n.yaml` 记录。配对文档发生冲突、存在非文本合并配置或记录无效时，它会拒绝处理并保留冲突；如果合并已经因冲突而停止，请运行 `pnpm run resolve-translation-pairing-conflicts`，该命令会暂存每份可安全生成的配对记录；如果其他配对冲突仍需手工处理，则以非零状态退出。确切边界见[双语文档契约](i18n/README.md#the-pairing-contract)。\n\n安装脚本在发布 worktree 配置前，会探测确切的 Node/tsx 驱动入口点。如果该运行时之后变得不可用，不依赖 Node 的启动器会写入 Git 的普通文本合并结果、让伴随文件保持未解决状态，并打印恢复路径；请恢复依赖后运行 `pnpm run resolve-translation-pairing-conflicts`，或运行 `git merge --abort`。如果 `pre-merge-commit` 拒绝原本能干净完成的合并，Git 会把完整结果留在暂存区但不创建提交；请修复失败后运行 `git commit`，或中止合并。确切的索引与 `MERGE_HEAD` 状态由[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md#failure-contract)负责记录。\n\nlefthook 在 `lefthook.yml` 中配置，作为快速的本地检查点：\n\n- `pre-commit` 对照暂存的配对文档 blob 校验暂存的配对记录，应用仅用于格式化的 ESLint 修复，使用不加载项目的 `.oxlintrc.staged.json` 配置验证暂存文件并应用 Oxlint 的原生修复，在暂存文件属于 `THIRD_PARTY_NOTICES.md` 的输入时重新生成该文件，然后检查暂存 diff 中的空白错误，并运行 vendor manifest（元数据清单）守卫；\n- `pre-merge-commit` 在 Git 创建自动合并提交前执行同样以索引为准的配对检查；\n- `pre-push` 运行 `pnpm run typecheck`；该命令会先完成包含 TypeRT 契约生成的完整 Host lib 阶段，再运行 Client TypeScript 检查。\n\nvendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。\n\n除限定范围的暂存记录校验外，这些钩子有意不运行测试、快照、文档检查、构建或 `hygiene`。贡献者只运行一次[与改动行为相关的检查](../AGENTS.md#run-relevant-checks-locally)；CI 负责全量覆盖率门禁、构建产物冒烟测试，以及 Node 22.19、24 和 26 兼容性矩阵。\n\n贡献者可以选择运行 `pnpm run check:all`，执行全面的本地门禁集。该命令独立于 Git 钩子，也不是对 agent 的指令。\n\n### CI 门禁\n\nkeyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若干宽粒度 lane，并在受支持的 Node 版本上运行一组较小的兼容性检查。产物消费方在各自 lane 内等待一次 build。单独的真实 API 工作流按其配置的 worker 上限运行 `pnpm run test:e2e`。当前门禁和 job 清单以 [scripts/run-gates.ts](../scripts/run-gates.ts) 和工作流文件为准。\n\n### 日常命令\n\n根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。\n\n### 演示\n\n单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:headless \"summarize this workspace\"\n```\n\n自指的 cordis 演示可以检查并修改其实时插件运行时，并需要相同的凭证（默认 `web`，也可用 `acp`）：\n\n```sh\npnpm run demo:cordis\n```\n\nACP 自动化服务器通过 JSON-RPC stdio 提供全新 agent 会话，同样需要 `DEEPSEEK_API_KEY`：\n\n```sh\npnpm run demo:acp\n```\n\n### TODO 标记\n\n请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：\n\n- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；\n- `TODO`：应当尽快修复的问题，等资源到位即可处理；\n- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。\n\n请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。\n\n### 逐字记录类型（`ts type-equiv`）\n\n[核心数据结构](subsystems/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：\n\n```json\n{ \"doc\": \"docs/subsystems/session.md\", \"symbol\": \"SessionEvent\", \"source\": \"packages/core/session/src/types.ts\" }\n```\n\n`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `\"projection\": \"public-api\"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁按文档、符号和投影，在主块与 manifest 条目之间强制 1:1 对应；只有当配对 `.zh.md` 块的完整受跟踪围栏序列与其无后缀兄弟文件按字节一致且顺序相同时，才会复用后者的条目。`doc-typecheck` 对可编译围栏应用同一派生规则，同时跳过两种源码等价围栏的编译，并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个主块时，请在同一个变更里更新 manifest。\n" }, { "role": "user", diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 9180a3bd9a..56c1b094be 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -2,1566 +2,1566 @@ "comment": "Maps each primary ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Paired `.zh.md` blocks are byte-identical derivatives checked through their unsuffixed sibling and have no duplicate entry. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence between primary blocks and entries. Add an entry when you add a primary source-equivalence block; remove it when you remove the block.", "entries": [ { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "AssistantProvenance", "source": "packages/llm/llm/src/message.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "Message", "source": "packages/llm/llm/src/message.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "MessageSourceMap", "source": "packages/llm/llm/src/message.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "ContextForm", "source": "packages/llm/llm/src/message.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "ContextSnapshotSection", "source": "packages/llm/llm/src/message.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "ContextFormed", "source": "packages/llm/llm/src/message.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "FinishReasonMap", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "AdapterRegistrationHandle", "source": "packages/llm/llm/src/index.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmProviderInfo", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmModelInfo", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmModelDiscoveryRequest", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmDiscoveredModel", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmModelContext", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "ReasoningEffortId", "source": "packages/llm/llm/src/brand.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmReasoningEffortInfo", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmModelReasoningInfo", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmResolvedModelInfo", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "GenerateOptions", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "ToolSchema", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmCallConfig", "source": "packages/llm/llm/src/call-config.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmCallConfigAdapterDefaults", "source": "packages/llm/llm/src/call-config.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "InboxTarget", "source": "packages/core/agent/src/inbox.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "CancelOptions", "source": "packages/core/agent/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "AgentCancelCause", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "Agent", "source": "packages/core/agent/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "PreStepDecision", "source": "packages/core/agent/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "RequestErrorAction", "source": "packages/core/agent/src/types.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" }, { - "doc": "docs/core-data-structures/scope.md", + "doc": "docs/subsystems/scope.md", "symbol": "ScopeKey", "source": "packages/core/scope/src/index.ts" }, { - "doc": "docs/core-data-structures/scope.md", + "doc": "docs/subsystems/scope.md", "symbol": "Scoped", "source": "packages/core/scope/src/index.ts" }, { - "doc": "docs/core-data-structures/scope.md", + "doc": "docs/subsystems/scope.md", "symbol": "Scope", "source": "packages/core/scope/src/index.ts" }, { - "doc": "docs/core-data-structures/scope.md", + "doc": "docs/subsystems/scope.md", "symbol": "ScopeLayer", "source": "packages/core/scope/src/store.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalRef", "source": "packages/goal/goal/src/types.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalPhase", "source": "packages/goal/goal/src/types.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalBlockReason", "source": "packages/goal/goal/src/types.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalSnapshot", "source": "packages/goal/goal/src/types.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalView", "source": "packages/goal/goal/src/types.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalSnapshotChangeMeta", "source": "packages/goal/goal/src/domain.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalClearChangeMeta", "source": "packages/goal/goal/src/domain.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalMessageSource", "source": "packages/goal/goal/src/domain.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "CreateGoalRequest", "source": "packages/goal/goal/src/types.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "EditGoalRequest", "source": "packages/goal/goal/src/types.ts" }, { - "doc": "docs/core-data-structures/goal.md", + "doc": "docs/subsystems/goal.md", "symbol": "GoalChanged", "source": "packages/goal/goal/src/domain.ts" }, { - "doc": "docs/core-data-structures/commands.md", + "doc": "docs/subsystems/commands.md", "symbol": "CommandInputDescriptor", "source": "packages/interaction/commands/src/index.ts" }, { - "doc": "docs/core-data-structures/commands.md", + "doc": "docs/subsystems/commands.md", "symbol": "CommandDefinition", "source": "packages/interaction/commands/src/index.ts" }, { - "doc": "docs/core-data-structures/commands.md", + "doc": "docs/subsystems/commands.md", "symbol": "CommandInvocation", "source": "packages/interaction/commands/src/index.ts" }, { - "doc": "docs/core-data-structures/commands.md", + "doc": "docs/subsystems/commands.md", "symbol": "CommandResult", "source": "packages/interaction/commands/src/index.ts" }, { - "doc": "docs/core-data-structures/commands.md", + "doc": "docs/subsystems/commands.md", "symbol": "CommandDescriptor", "source": "packages/interaction/commands/src/index.ts" }, { - "doc": "docs/core-data-structures/commands.md", + "doc": "docs/subsystems/commands.md", "symbol": "ParsedCommand", "source": "packages/interaction/commands/src/index.ts" }, { - "doc": "docs/core-data-structures/system-prompt.md", + "doc": "docs/subsystems/system-prompt.md", "symbol": "AssembleContext", "source": "packages/core/system-prompt/src/index.ts" }, { - "doc": "docs/core-data-structures/system-prompt.md", + "doc": "docs/subsystems/system-prompt.md", "symbol": "PromptContext", "source": "packages/core/system-prompt/src/index.ts" }, { - "doc": "docs/core-data-structures/system-prompt.md", + "doc": "docs/subsystems/system-prompt.md", "symbol": "PromptSection", "source": "packages/core/system-prompt/src/index.ts" }, { - "doc": "docs/core-data-structures/system-prompt.md", + "doc": "docs/subsystems/system-prompt.md", "symbol": "ToolProviderResult", "source": "packages/core/system-prompt/src/index.ts" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "StreamChunk", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "LlmFailure", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "BlockAssembler", "source": "packages/llm/llm/src/assembler.ts", "projection": "public-api" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "PreparedLlmCall", "source": "packages/llm/llm/src/index.ts" }, { - "doc": "docs/core-data-structures/llm-streaming.md", + "doc": "docs/subsystems/llm-streaming.md", "symbol": "LlmAdapter", "source": "packages/llm/llm/src/index.ts", "projection": "public-api" }, { - "doc": "docs/core-data-structures/token-meter.md", + "doc": "docs/subsystems/token-meter.md", "symbol": "TokenMeasurement", "source": "packages/llm/token-meter/src/types.ts" }, { - "doc": "docs/core-data-structures/token-meter.md", + "doc": "docs/subsystems/token-meter.md", "symbol": "TokenSurfaceNode", "source": "packages/llm/token-meter/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "UserMessage", "source": "packages/llm/llm/src/message.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SessionEventMap", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "EpochHeader", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "RequestContext", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "TodoItem", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "TurnEndCancelCause", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "TurnEndReasonMap", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SessionSurface", "source": "packages/core/session/src/surface.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" }, { - "doc": "docs/core-data-structures/session.md", + "doc": "docs/subsystems/session.md", "symbol": "Session", "source": "packages/core/session/src/index.ts", "projection": "public-api" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "SessionHeader", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "CreateSessionOptions", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "RestoredSessionOptions", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "PrepareSessionOptions", "source": "packages/core/session/src/types.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "SessionPreparationOptions", "source": "packages/core/session/src/preparation.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "SessionPreparation", "source": "packages/core/session/src/preparation.ts", "projection": "public-api" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "SessionInspection", "source": "packages/session/session-persistence/src/index.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "SessionLocation", "source": "packages/session/session-persistence/src/index.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventSurface", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionRecord", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionLogSnapshot", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionSurfaceSnapshot", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionTitleObservation", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionTitleObservationResult", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventRecord", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionLineageNode", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionLineageTrace", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionQueryErrorCode", "source": "packages/session-query/session-query/src/config.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventReadRequest", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventWindow", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventTraceRequest", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventTrace", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventTraceObservation", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleProviderId", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleModelProvenance", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleSource", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleEventData", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleSnapshot", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleLlmRequestEventData", "source": "packages/session/session-title-llm/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleUserMessage", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleAutomaticMode", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleProviderRequest", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleProviderResult", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-title.md", + "doc": "docs/subsystems/session-title.md", "symbol": "SessionTitleProvider", "source": "packages/session/session-title/src/index.ts" }, { - "doc": "docs/core-data-structures/session-reference.md", + "doc": "docs/subsystems/session-reference.md", "symbol": "SessionReferenceInput", "source": "packages/context/session-reference/src/types.ts" }, { - "doc": "docs/core-data-structures/session-reference.md", + "doc": "docs/subsystems/session-reference.md", "symbol": "SessionReferenceCandidate", "source": "packages/context/session-reference/src/types.ts" }, { - "doc": "docs/core-data-structures/session-reference.md", + "doc": "docs/subsystems/session-reference.md", "symbol": "PreparedReferencedMessage", "source": "packages/context/session-reference/src/types.ts" }, { - "doc": "docs/core-data-structures/session-reference.md", + "doc": "docs/subsystems/session-reference.md", "symbol": "SessionReferenceErrorCode", "source": "packages/context/session-reference/src/config.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolOutputDefinition", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolDefinition", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ValueSchemaSpec", "source": "packages/core/tools/src/schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ParameterPropertySpec", "source": "packages/core/tools/src/schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ParameterSchemaSpec", "source": "packages/core/tools/src/schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "InferValue", "source": "packages/core/tools/src/schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "InferArgs", "source": "packages/core/tools/src/schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolExecutionToken", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolExecutionInput", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolExecution", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolDispatchExecution", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolExecutionMode", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "CodeDispatchLog", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolRunContext", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolGuard", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolRestriction", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolFailure", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolExecutionSuccess", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolExecutionFailure", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ToolExecutionResult", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "PreToolDecision", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "PostToolDecision", "source": "packages/core/tools/src/index.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "JsonSchemaScalar", "source": "packages/core/tools/src/json-schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "JsonSchemaType", "source": "packages/core/tools/src/json-schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "JsonSchemaNode", "source": "packages/core/tools/src/json-schema.ts" }, { - "doc": "docs/core-data-structures/tools.md", + "doc": "docs/subsystems/tools.md", "symbol": "ObjectJsonSchema", "source": "packages/core/tools/src/json-schema.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "AskUserQuestionOption", "source": "packages/interaction/user-interaction/src/types.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "AskUserQuestionIntent", "source": "packages/interaction/user-interaction/src/types.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "AskUserQuestionItem", "source": "packages/interaction/user-interaction/src/types.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "AskUserQuestionRequest", "source": "packages/interaction/user-interaction/src/index.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "AskUserQuestionAnswerItem", "source": "packages/interaction/user-interaction/src/types.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "AskUserQuestionAnswer", "source": "packages/interaction/user-interaction/src/types.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/interaction/user-interaction/src/index.ts" }, { - "doc": "docs/core-data-structures/user-interaction.md", + "doc": "docs/subsystems/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/interaction/user-interaction/src/index.ts" }, { - "doc": "docs/core-data-structures/approval.md", + "doc": "docs/subsystems/approval.md", "symbol": "ApprovalRequestId", "source": "packages/interaction/user-approval/src/types.ts" }, { - "doc": "docs/core-data-structures/approval.md", + "doc": "docs/subsystems/approval.md", "symbol": "ApprovalOutcome", "source": "packages/interaction/user-approval/src/types.ts" }, { - "doc": "docs/core-data-structures/approval.md", + "doc": "docs/subsystems/approval.md", "symbol": "ApprovalPolicy", "source": "packages/interaction/user-approval/src/index.ts" }, { - "doc": "docs/core-data-structures/approval.md", + "doc": "docs/subsystems/approval.md", "symbol": "ApprovalRequest", "source": "packages/interaction/user-approval/src/index.ts" }, { - "doc": "docs/core-data-structures/bash.md", + "doc": "docs/subsystems/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" }, { - "doc": "docs/core-data-structures/bash.md", + "doc": "docs/subsystems/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" }, { - "doc": "docs/core-data-structures/bash.md", + "doc": "docs/subsystems/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" }, { - "doc": "docs/core-data-structures/bash.md", + "doc": "docs/subsystems/bash.md", "symbol": "BashSandboxInfo", "source": "packages/bash/bash/src/types.ts" }, { - "doc": "docs/core-data-structures/bash.md", + "doc": "docs/subsystems/bash.md", "symbol": "BashProcess", "source": "packages/bash/bash/src/types.ts" }, { - "doc": "docs/core-data-structures/bash.md", + "doc": "docs/subsystems/bash.md", "symbol": "BashProcessRead", "source": "packages/bash/bash/src/types.ts" }, { - "doc": "docs/core-data-structures/tasks.md", + "doc": "docs/subsystems/tasks.md", "symbol": "TaskKindMap", "source": "packages/tasks/tasks/src/types.ts" }, { - "doc": "docs/core-data-structures/tasks.md", + "doc": "docs/subsystems/tasks.md", "symbol": "TaskStart", "source": "packages/tasks/tasks/src/types.ts" }, { - "doc": "docs/core-data-structures/tasks.md", + "doc": "docs/subsystems/tasks.md", "symbol": "TaskHooks", "source": "packages/tasks/tasks/src/types.ts" }, { - "doc": "docs/core-data-structures/tasks.md", + "doc": "docs/subsystems/tasks.md", "symbol": "TaskOutcome", "source": "packages/tasks/tasks/src/types.ts" }, { - "doc": "docs/core-data-structures/tasks.md", + "doc": "docs/subsystems/tasks.md", "symbol": "TaskSnapshot", "source": "packages/tasks/tasks/src/types.ts" }, { - "doc": "docs/core-data-structures/tasks.md", + "doc": "docs/subsystems/tasks.md", "symbol": "TaskRead", "source": "packages/tasks/tasks/src/types.ts" }, { - "doc": "docs/core-data-structures/pty.md", + "doc": "docs/subsystems/pty.md", "symbol": "PtyWaitReason", "source": "packages/pty/pty/src/types.ts" }, { - "doc": "docs/core-data-structures/pty.md", + "doc": "docs/subsystems/pty.md", "symbol": "PtySessionStatus", "source": "packages/pty/pty/src/types.ts" }, { - "doc": "docs/core-data-structures/pty.md", + "doc": "docs/subsystems/pty.md", "symbol": "PtyBackend", "source": "packages/pty/pty/src/types.ts" }, { - "doc": "docs/core-data-structures/pty.md", + "doc": "docs/subsystems/pty.md", "symbol": "PtyBackendSession", "source": "packages/pty/pty/src/types.ts" }, { - "doc": "docs/core-data-structures/pty.md", + "doc": "docs/subsystems/pty.md", "symbol": "PtySendOperation", "source": "packages/pty/pty/src/types.ts" }, { - "doc": "docs/core-data-structures/pty.md", + "doc": "docs/subsystems/pty.md", "symbol": "PtySendResult", "source": "packages/pty/pty/src/types.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "SandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "ConfinedSandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "SandboxExecutionPolicy", "source": "packages/sandbox/sandbox/src/index.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "SandboxEnforcement", "source": "packages/sandbox/sandbox/src/index.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "SandboxPolicy", "source": "packages/sandbox/sandbox/src/index.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "SandboxPolicyRequest", "source": "packages/sandbox/sandbox-policy/src/index.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "RunnerFailureRule", "source": "packages/sandbox/sandbox/src/index.ts" }, { - "doc": "docs/core-data-structures/sandbox.md", + "doc": "docs/subsystems/sandbox.md", "symbol": "ConfinedArgv", "source": "packages/sandbox/sandbox/src/index.ts" }, { - "doc": "docs/core-data-structures/code-runtime.md", + "doc": "docs/subsystems/code-runtime.md", "symbol": "CodeJsonValue", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { - "doc": "docs/core-data-structures/code-runtime.md", + "doc": "docs/subsystems/code-runtime.md", "symbol": "CodeRunRequest", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { - "doc": "docs/core-data-structures/code-runtime.md", + "doc": "docs/subsystems/code-runtime.md", "symbol": "CodeRunResult", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { - "doc": "docs/core-data-structures/code-runtime.md", + "doc": "docs/subsystems/code-runtime.md", "symbol": "CodeBindingNamespace", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { - "doc": "docs/core-data-structures/code-runtime.md", + "doc": "docs/subsystems/code-runtime.md", "symbol": "CodeBindingErrorClass", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { - "doc": "docs/core-data-structures/code-runtime.md", + "doc": "docs/subsystems/code-runtime.md", "symbol": "CodeBindingFunction", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { - "doc": "docs/core-data-structures/code-runtime.md", + "doc": "docs/subsystems/code-runtime.md", "symbol": "CodeRunFailure", "source": "packages/code-runtime/code-runtime/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsTarget", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsTargetKey", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsVersion", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsInfo", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsPathInfo", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsDirEntry", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsWriteIntent", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsWriteOutcome", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsEditRequest", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsEditOutcome", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsErrorCode", "source": "packages/fs/fs/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FsPolicyExec", "source": "packages/fs/fs-policy/src/types.ts" }, { - "doc": "docs/core-data-structures/filesystem.md", + "doc": "docs/subsystems/filesystem.md", "symbol": "FileReadOutcome", "source": "packages/fs/tool-fs/src/read-render.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillSource", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillResourceBase", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillInvocationPolicy", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillSummary", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillCatalogSnapshot", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillCandidate", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillDefinition", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillRegistration", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillLookupOptions", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillProviderObservation", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillProvider", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "SkillProviderControl", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/skills.md", + "doc": "docs/subsystems/skills.md", "symbol": "Config", "source": "packages/skill/skill/src/index.ts" }, { - "doc": "docs/core-data-structures/compaction.md", + "doc": "docs/subsystems/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" }, { - "doc": "docs/core-data-structures/compaction.md", + "doc": "docs/subsystems/compaction.md", "symbol": "CompactionTrigger", "source": "packages/compact/compact/src/index.ts" }, { - "doc": "docs/core-data-structures/compaction.md", + "doc": "docs/subsystems/compaction.md", "symbol": "ManualCompactionErrorCode", "source": "packages/compact/compact/src/index.ts" }, { - "doc": "docs/core-data-structures/compaction.md", + "doc": "docs/subsystems/compaction.md", "symbol": "PrunedEntry", "source": "packages/compact/compact-tool-result-prune/src/types.ts" }, { - "doc": "docs/core-data-structures/compaction.md", + "doc": "docs/subsystems/compaction.md", "symbol": "PruneResult", "source": "packages/compact/compact-tool-result-prune/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentStartRequest", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "ResolvedSubagentStartRequest", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "CoordinatorMessageSource", "source": "packages/subagent/subagent/src/continuation.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentReportMessageSource", "source": "packages/subagent/subagent/src/continuation.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentReportDelivery", "source": "packages/subagent/subagent/src/continuation.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentReportOptions", "source": "packages/subagent/subagent/src/continuation.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentFollowupOptions", "source": "packages/subagent/subagent/src/continuation.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentInterruptAuthority", "source": "packages/subagent/subagent/src/continuation.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentDescendantListEntry", "source": "packages/subagent/subagent/src/list-children.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "ContinuableStart", "source": "packages/subagent/subagent/src/continuation.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "ContinuableCreateRequest", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "ContinuableCreateSpec", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentResult", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentStopReasonMap", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentRun", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/subagent.md", + "doc": "docs/subsystems/subagent.md", "symbol": "SubagentProvider", "source": "packages/subagent/subagent/src/types.ts" }, { - "doc": "docs/core-data-structures/web.md", + "doc": "docs/subsystems/web.md", "symbol": "WebSearchRequest", "source": "packages/web/web/src/types.ts" }, { - "doc": "docs/core-data-structures/web.md", + "doc": "docs/subsystems/web.md", "symbol": "WebSearchResult", "source": "packages/web/web/src/types.ts" }, { - "doc": "docs/core-data-structures/web.md", + "doc": "docs/subsystems/web.md", "symbol": "WebSearchSource", "source": "packages/web/web/src/types.ts" }, { - "doc": "docs/core-data-structures/web.md", + "doc": "docs/subsystems/web.md", "symbol": "WebFetchRequest", "source": "packages/web/web/src/types.ts" }, { - "doc": "docs/core-data-structures/web.md", + "doc": "docs/subsystems/web.md", "symbol": "WebFetchResult", "source": "packages/web/web/src/types.ts" }, { - "doc": "docs/core-data-structures/web.md", + "doc": "docs/subsystems/web.md", "symbol": "WebFetchBody", "source": "packages/web/web/src/types.ts" }, { - "doc": "docs/core-data-structures/spill.md", + "doc": "docs/subsystems/spill.md", "symbol": "SaveTextSpill", "source": "packages/spill/spill/src/types.ts" }, { - "doc": "docs/core-data-structures/spill.md", + "doc": "docs/subsystems/spill.md", "symbol": "SpillOwner", "source": "packages/spill/spill/src/types.ts" }, { - "doc": "docs/core-data-structures/spill.md", + "doc": "docs/subsystems/spill.md", "symbol": "SpillSource", "source": "packages/spill/spill/src/types.ts" }, { - "doc": "docs/core-data-structures/spill.md", + "doc": "docs/subsystems/spill.md", "symbol": "SpillRef", "source": "packages/spill/spill/src/types.ts" }, { - "doc": "docs/core-data-structures/spill.md", + "doc": "docs/subsystems/spill.md", "symbol": "SpillLocator", "source": "packages/spill/spill/src/types.ts" }, { - "doc": "docs/core-data-structures/workflow.md", + "doc": "docs/subsystems/workflow.md", "symbol": "WorkflowStartRequest", "source": "packages/workflow/workflow/src/types.ts" }, { - "doc": "docs/core-data-structures/workflow.md", + "doc": "docs/subsystems/workflow.md", "symbol": "WorkflowMeta", "source": "packages/workflow/workflow/src/types.ts" }, { - "doc": "docs/core-data-structures/workflow.md", + "doc": "docs/subsystems/workflow.md", "symbol": "WorkflowResult", "source": "packages/workflow/workflow/src/types.ts" }, { - "doc": "docs/core-data-structures/workflow.md", + "doc": "docs/subsystems/workflow.md", "symbol": "WorkflowRun", "source": "packages/workflow/workflow/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspOperation", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspPosition", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspRange", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspQueryRequest", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspProviderQuery", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspLocation", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspHover", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspQueryResult", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspProvider", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/lsp.md", + "doc": "docs/subsystems/lsp.md", "symbol": "LspService", "source": "packages/lsp/lsp/src/types.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "SessionPersistenceRevision", "source": "packages/session/session-persistence/src/revision.ts" }, { - "doc": "docs/core-data-structures/persistence.md", + "doc": "docs/subsystems/persistence.md", "symbol": "SessionPersistenceSnapshot", "source": "packages/session/session-persistence/src/index.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionResultFilter", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventResultFilter", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventSearchDocument", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionSearchCursor", "source": "packages/session-query/session-query/src/cursor.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionSearchRequest", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventSearchRequest", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionSearchPage", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventSearchPage", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionEventSearchHit", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/session-query.md", + "doc": "docs/subsystems/session-query.md", "symbol": "SessionSearchHit", "source": "packages/session-query/session-query/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessSpawnSpec", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessHandle", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessOutputReader", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessOutputRead", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessOutcome", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "DshEnvironmentKey", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "DshEnvironment", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "CollectedOutput", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessStdinMode", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessCollect", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessOutputMode", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessStdio", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/subprocess.md", + "doc": "docs/subsystems/subprocess.md", "symbol": "SubprocessCollectedOutputs", "source": "packages/subprocess/subprocess/src/types.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsNamespace", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsRegisterOptions", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsApplies", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsScope", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsDescriptor", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsUpdateSource", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/credentials.md", + "doc": "docs/subsystems/credentials.md", "symbol": "CredentialRef", "source": "packages/credentials/credentials/src/index.ts" }, { - "doc": "docs/core-data-structures/credentials.md", + "doc": "docs/subsystems/credentials.md", "symbol": "ResolvedCredential", "source": "packages/credentials/credentials/src/index.ts" }, { - "doc": "docs/core-data-structures/credentials.md", + "doc": "docs/subsystems/credentials.md", "symbol": "CredentialInfo", "source": "packages/credentials/credentials/src/index.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsDescribeOptions", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/core.md", + "doc": "docs/subsystems/core.md", "symbol": "LlmConfigurableProvider", "source": "packages/llm/llm/src/types.ts" }, { - "doc": "docs/core-data-structures/settings.md", + "doc": "docs/subsystems/settings.md", "symbol": "SettingsPathOp", "source": "packages/settings/settings/src/index.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypeRTLookupMap", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypeRTContextMap", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypeRTLookupDefinition", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypeRTCodec", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "InvocationParameterDescriptor", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "InvocationDescriptor", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypeRTService", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypeRTRemoteNamespaceMap", "source": "packages/typert/type-meta/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "InvokeRemoteRequest", "source": "packages/api/gateway/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypertGatewayErrorCode", "source": "packages/api/gateway/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypertGateway", "source": "packages/api/gateway/src/types.ts" }, { - "doc": "docs/core-data-structures/typert.md", + "doc": "docs/subsystems/typert.md", "symbol": "TypeRTClientRemote", "source": "packages/typert/type-meta/src/types.ts" } diff --git a/website/docs.ts b/website/docs.ts index 8db7951dbb..07f470319b 100644 --- a/website/docs.ts +++ b/website/docs.ts @@ -279,13 +279,13 @@ const coreDataReference = pairedPages(([ ['settings.md', '用户设置', 'User settings', 21], ['credentials.md', '用户凭据', 'User credentials', 22], ] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({ - source: `docs/core-data-structures/${file}`, - route: `reference/core-data-structures/${file}`, + source: `docs/subsystems/${file}`, + route: `reference/subsystems/${file}`, label: { root: rootLabel, en: enLabel }, sidebar: { root: 'zh-reference', en: 'en-reference' }, section: { root: '数据结构', en: 'Data structures' }, order, - ...(file === 'core.md' ? { sourceAliases: ['docs/core-data-structures'] } : {}), + ...(file === 'core.md' ? { sourceAliases: ['docs/subsystems'] } : {}), }))) const reference = mirroredPages([ @@ -339,8 +339,8 @@ const reference = mirroredPages([ ['pty.md', 'PTY 会话', 'PTY sessions', 8], ['commands.md', '命令', 'Human commands', 17], ] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({ - source: `docs/core-data-structures/${file}`, - route: `reference/core-data-structures/${file}`, + source: `docs/subsystems/${file}`, + route: `reference/subsystems/${file}`, contentLocale: 'en-US', label: { root: rootLabel, en: enLabel }, sidebar: { root: 'zh-reference', en: 'en-reference' },