Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: anchor each subsystem page to its package group; make group READMEs thin tables

Browse Source 
core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow.

Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
This commit is contained in:
Tianyi Cui
2026-08-02 05:54:15 +08:00
parent 2886ba45db
commit aa0ca6c836
137 changed files with 1680 additions and 1507 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
packages/acp/README.i18n.yaml
View File

@@ -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/acp/README.md
README.md: 3ba247598f29f2244456061fe7f9a3282086148f
README.zh.md: c13bc05b12fff2ef97b4d547936aa14a6556430a
README.md: 97af6d164b265bf0e98e3c9f5a444cffad4face5
README.zh.md: 266b108c108b9f543d93cbb727ddbc01ab4bef36

4
packages/acp/README.md
View File

@@ -2,10 +2,10 @@
English | [中文](README.zh.md)
The ACP group exposes harness agents to programmatic clients. It is an interoperability transport, not a presentation or human-interaction layer.
The ACP group exposes harness agents to programmatic clients over the Agent Client Protocol. It is an interoperability transport, not a presentation or human-interaction layer; the matching out-of-process subagent *client* lives in [`subagent/subagent-acp`](../subagent/subagent-acp/README.md) because it implements the subagent provider interface.
| Package | Role |
|---|---|
| [`acp/`](acp/README.md) | Automation-only ACP server. |
The matching out-of-process subagent client remains in [`subagent/subagent-acp`](../subagent/subagent-acp/README.md) because it implements the subagent provider interface; arbitrary ACP clients may drive the same server contract.
The server contract is documented in [`acp/README.md`](acp/README.md).

4
packages/acp/README.zh.md
View File

@@ -2,10 +2,10 @@
[English](README.md) | 中文
ACP（Agent Client Protocol）组将 harness 中的 agent（智能体）公开给程序化客户端。它是互操作传输层，而非展示层或人机交互层。
ACP 组通过 Agent Client Protocol 把 harness agent 暴露给编程客户端。它是互操作传输层，不是展示或人机交互层；配对的进程外 subagent *客户端*在 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现的是 subagent 提供方接口。
| 包 | 职责 |
|---|---|
| [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器。 |
与之匹配的进程外 subagent 客户端仍位于 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现 subagent 提供方接口；任意 ACP 客户端都可以按照同一服务器契约驱动该服务器。
服务器契约见 [`acp/README.md`](acp/README.md)。

4
packages/bash/README.i18n.yaml
View File

@@ -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/README.md
README.md: 601782caad24d3555a206365a3f1954d81af1cf0
README.zh.md: 8b96c4f80ba8776bfd8bdde178178cea946ff36c
README.md: 7395a051742af24b96842966b71297dc01853dca
README.zh.md: 1d5825e077c46284dbd4895e285cda8f39c252a3

2
packages/bash/README.md
View File

@@ -15,3 +15,5 @@ The capability family spans the canonical executor seam, its implementations, th
| [`tool-pwsh/`](tool-pwsh/README.md) | Exposes PowerShell execution to the model. | (registers on `ctx.tools`) |
A leaf `cordis.yml` selects one executor implementation and the model-facing tools it needs. A sandboxed composition also selects a `ctx.sandbox` provider; the [ACP example](../../examples/acp-agent/) shows one complete wiring.
The subsystem reference — request/spec vocabulary, results, background processes, the service, and events — is [docs/subsystems/bash.md](../../docs/subsystems/bash.md).

2
packages/bash/README.zh.md
View File

@@ -15,3 +15,5 @@
| [`tool-pwsh/`](tool-pwsh/README.md) | 向模型公开 PowerShell 执行。 | （注册到 `ctx.tools`） |
叶节点 `cordis.yml` 选择一个执行器实现和所需的面向模型工具。沙箱化组合还会选择一个 `ctx.sandbox` 提供方；[ACP（Agent Client Protocol）示例](../../examples/acp-agent/)展示一套完整接线。
子系统参考——请求/spec 词汇、结果、后台进程、服务与事件——见 [docs/subsystems/bash.md](../../docs/subsystems/bash.md)。

4
packages/boot/README.i18n.yaml
View File

@@ -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/boot/README.md
README.md: 7727f4fbab62a930051fd3b92d04513ac9f5d218
README.zh.md: aa9a56619ee55c3be8feb58881f77c460861b1ac
README.md: 5e4e483b60adab0b22ddb5279f4cd8fb699b9c35
README.zh.md: d49afa45b9fb93f6fa83944167057f0c933cd05d

4
packages/boot/README.md
View File

@@ -2,8 +2,10 @@
English | [中文](README.zh.md)
The channel-neutral boot library the app bins share. A role-complete single-package group: it belongs to no channel and no assembly — `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
The channel-neutral boot library the app bins share: `apps/cli`, the [`scaffold/`](../scaffold/README.md) launcher, and the [`examples/`](../examples/README.md) demo bins all consume it.
| Package | Role | ctx key |
|---|---|---|
| `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
The boot sequence and personal-config contract are documented in [`app-boot/README.md`](app-boot/README.md).

4
packages/boot/README.zh.md
View File

@@ -2,8 +2,10 @@
[English](README.md) | 中文
各 app bin 共享、与通道无关的启动库。一个角色完备的单包组：它不归属任何通道也不归属任何组装——`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器和 [`examples/`](../examples/README.md) 各演示 bin 都消费它。
各 app bin 共享的、与渠道无关的启动库：`apps/cli`、[`scaffold/`](../scaffold/README.md) 启动器与 [`examples/`](../examples/README.md) demo bin 都消费它。
| 包 | 职责 | ctx 键 |
|---|---|---|
| `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
启动序列与个人配置契约见 [`app-boot/README.md`](app-boot/README.md)。

4
packages/client/README.i18n.yaml
View File

@@ -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/client/README.md
README.md: b6fa426fbe541e2b22d2bf5f19d4397361cf0899
README.zh.md: 5a55bb8c2c31b5215fc73e75e1c4f3aca79add64
README.md: 56b9363cc724515ecbd11127ea4c13aba84283df
README.zh.md: edd378bf80b63e9ab2481ab555320ed18de85139

2
packages/client/README.md
View File

@@ -38,3 +38,5 @@ The browser side of the dsh web GUI: shell boot, browser-host communication, sha
| [`ui-models/`](ui-models/README.md) | Provides model-provider configuration and DeepSeek onboarding. |
Each child reference owns its contract and detailed behavior. The [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) and [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) own the cross-package composition and loading decisions.
The subsystem reference is [client-modules.md](../../docs/subsystems/client-modules.md); the [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) is the definitive slot model, and the [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) owns the loading chain and object layer.

2
packages/client/README.zh.md
View File

@@ -38,3 +38,5 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
| [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |
每个子文档负责自身的契约和详细行为。[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)与 [Web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)负责跨包组合与加载决策。
子系统参考是 [client-modules.md](../../docs/subsystems/client-modules.md)；[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威 slot 模型，[web 客户端架构说明](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)拥有加载链与对象层。

4
packages/code-runtime/README.i18n.yaml
View File

@@ -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/code-runtime/README.md
README.md: f20a287419b94b1a9dc1d8da7303fc4d3032cfd3
README.zh.md: f5cd4c9949f2bd7a7d6d7cd078144910712a3819
README.md: 45dd55b8609fd33b7116f6b2ea36df3b3332e419
README.zh.md: ebf288a49f87ad01b1ec80c3843c87c91206af26

2
packages/code-runtime/README.md
View File

@@ -10,3 +10,5 @@ The code-execution capability seam (see [capability seams](../../.agents/notes/i
| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker-thread backend | registers `ctx.codeRuntime` |
Backends register the seam without changing its consumer. The child READMEs own language, isolation, and execution-budget details.
The subsystem reference — run requests/results, binding namespaces, the failure taxonomy — is [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md).

2
packages/code-runtime/README.zh.md
View File

@@ -10,3 +10,5 @@
| [`code-runtime-worker/`](code-runtime-worker/README.md) | Worker 线程后端 | 注册 `ctx.codeRuntime` |
后端在不改变消费方的情况下注册该 seam。子 README 负责语言、隔离和执行预算细节。
子系统参考——运行请求/结果、绑定命名空间、失败分类体系——见 [docs/subsystems/code-runtime.md](../../docs/subsystems/code-runtime.md)。

4
packages/compact/README.i18n.yaml
View File

@@ -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/README.md
README.md: 509ea2764250f42e492f787deba959a8dd9967b7
README.zh.md: adc52690dbe9e904d8f24199cb78493dab3333a4
README.md: 0a83b87f57e4c948ee6df9e622f17964aff00f0f
README.zh.md: cba53ee7bb917a981a0fd4b77d833b8fb7dd2c3f

2
packages/compact/README.md
View File

@@ -12,3 +12,5 @@ A compaction capability family (see [capability seams](../../.agents/notes/imple
| [`command-compact/`](command-compact/README.md) | Human compaction command | registers on `ctx.commands` |
The backend, optional pruner, and human command compose through the seam; token measurement remains a separate LLM-family service. The [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md) owns the dependency rationale.
The subsystem reference — the `compact/*` events, `CompactionResult`, the service, pruning outcomes — is [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md); the seam's deliberate `dsh-session`/`dsh-llm` dependency is recorded in the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).

2
packages/compact/README.zh.md
View File

@@ -12,3 +12,5 @@
| [`command-compact/`](command-compact/README.md) | 用户压缩命令 | 注册到 `ctx.commands` |
后端、可选修剪器和用户命令通过该 seam 组合；token 测量仍是独立的 LLM（大语言模型）家族服务。[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)负责依赖关系的设计原理。
子系统参考——`compact/*` 事件、`CompactionResult`、服务、剪除结果——见 [docs/subsystems/compaction.md](../../docs/subsystems/compaction.md)；seam 有意依赖 `dsh-session`/`dsh-llm` 的决定记录在[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)。

4
packages/context/README.i18n.yaml
View File

@@ -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/context/README.md
README.md: a0b5eef51740b3aa67b9e158a00357f849b8bf57
README.zh.md: d6ed8050f3a64f740a951883f0dc321ac08e978a
README.md: 237f6191329f89834ec9bd9f72c0a1fd1d94651e
README.zh.md: 7c55dd91dbf7e3fca222e4b6f6bed2769f5c253c

2
packages/context/README.md
View File

@@ -12,3 +12,5 @@ Product plugins that add model-visible request context without defining a tool.
| [`workspace-context/`](workspace-context/README.md) | Workspace-instruction context | — |
The [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) explains its per-agent/session isolation and lifecycle split.
Session references are documented in [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md); the [`workspace-context` decision record](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md) owns its per-agent/session isolation and lifecycle split.

2
packages/context/README.zh.md
View File

@@ -12,3 +12,5 @@
| [`workspace-context/`](workspace-context/README.md) | workspace 指令上下文 | — |
[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)解释其逐 agent（智能体）／会话隔离和生命周期拆分。
会话引用见 [docs/subsystems/session-reference.md](../../docs/subsystems/session-reference.md)；[`workspace-context` 决策记录](../../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)拥有其按 agent/会话隔离与生命周期拆分。

4
packages/core/README.i18n.yaml
View File

@@ -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/README.md
README.md: d51ef73f7f545920f8cd527b2b0d597305ae86d0
README.zh.md: 729f41fafb6b9585a66e58fe8d6ac63c1f235acc
README.md: 40a888183a9338805d83c86bab9ae16f1c7bc04f
README.zh.md: 496d547a173a63ac9d8d2ce0f005877dab92d358

2
packages/core/README.md
View File

@@ -16,3 +16,5 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable.
Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.
The subsystem reference — the package-by-package loop map, the `Agent` handle and its delivery/interception contracts — is [docs/subsystems/core.md](../../docs/subsystems/core.md); the default runnable composition is [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md).

2
packages/core/README.zh.md
View File

@@ -16,3 +16,5 @@
`scope` 提供共享作用域原语。`agent` 负责公开 seam，`agent-loop` 是其默认实现；扩展插件依赖该 seam，从而保持驱动器可替换。
可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；该分组只负责可替换的主干组件。
子系统参考——逐包循环地图、`Agent` 句柄及其投递/拦截契约——见 [docs/subsystems/core.md](../../docs/subsystems/core.md)；默认可运行组合是 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)。

4
packages/credentials/README.i18n.yaml
View File

@@ -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/credentials/README.md
README.md: c08831c90333f8515bf86a5af717c38c50b50817
README.zh.md: c9756c010af5d2db0fc41f3108eabdc7f1161293
README.md: 75e3941ff6421ca7e41a71ab2bfe8b30209ce598
README.zh.md: d7c958689fdffc82830a82b04e2a06802bc81634

2
packages/credentials/README.md
View File

@@ -10,3 +10,5 @@ The credential capability family separates reference resolution from its provide
| [`credentials-local/`](credentials-local/README.md) | Environment and local-file provider | registers `ctx.credentials` |
Configuration carries references, not secret values. Consumers resolve those references at their operation boundary; the child READMEs own mutation, precedence, and storage semantics.
The subsystem reference — `CredentialRef`, per-operation resolution, UI-safe `CredentialInfo`, provider layers — is [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md).

2
packages/credentials/README.zh.md
View File

@@ -10,3 +10,5 @@
| [`credentials-local/`](credentials-local/README.md) | 环境与本地文件提供方 | 注册 `ctx.credentials` |
配置携带引用而非机密值。消费方在其操作边界解析这些引用；变更、优先级与存储语义由子级 README 负责。
子系统参考——`CredentialRef`、按操作解析、对 UI 安全的 `CredentialInfo`、提供方层——见 [docs/subsystems/credentials.md](../../docs/subsystems/credentials.md)。

4
packages/fs/README.i18n.yaml
View File

@@ -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/fs/README.md
README.md: b15012e882b60847e1ad22edf08d1202ba64fe5b
README.zh.md: 628f6c74894bc67559d49f7cf5d1378d0ece2382
README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
README.zh.md: b2929b17be6ce90051f0808c2cdf4bbf643f8f13

2
packages/fs/README.md
View File

@@ -19,3 +19,5 @@ The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesyst
## No timeouts on file IO
`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
The subsystem reference — targets, outcomes, guards, policy events, the error taxonomy, and why file IO takes no timeout — is [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md); the sandbox fence in the [cross-family fs sandbox Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md).

2
packages/fs/README.zh.md
View File

@@ -19,3 +19,5 @@
## 文件 I/O 不设超时
`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。

4
packages/goal/README.i18n.yaml
View File

@@ -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/README.md
README.md: 9fc6b0c18b1862a8be08275785ea3b6185e9bdbc
README.zh.md: 08f15bcc4e405e25d4dfd5981bbc99408833403c
README.md: 9d307278b39ecee61df9feace9fec4235b45d794
README.zh.md: 7217c174ba5382c53204ae3678be42375fc63db5

4
packages/goal/README.md
View File

@@ -2,7 +2,7 @@
English | [中文](README.zh.md)
The goal family owns durable objective state independently of the model-facing tools and continuation policy that consume it.
Durable objective state for an agent session, owned independently of the model-facing tools and continuation policy that consume it. Goal state is part of the owning session log; consumers depend on `dsh-goal`, never on the concrete agent loop.
| Package | Role | ctx key |
|---|---|---|
@@ -11,4 +11,4 @@ The goal family owns durable objective state independently of the model-facing t
| [`tool-goal/`](tool-goal/README.md) | Model-facing goal tools | — |
| [`command-goal/`](command-goal/README.md) | Human-facing goal command | — |
Goal state is part of the owning session log. Consumers depend on `dsh-goal`, not on the concrete agent loop; continuation behavior belongs in a separate plugin on the public agent seams.
The subsystem reference — goal identity, lifecycle snapshots, activation, change records — is [docs/subsystems/goal.md](../../docs/subsystems/goal.md).

4
packages/goal/README.zh.md
View File

@@ -2,7 +2,7 @@
[English](README.md) | 中文
goal 家族负责持久目标状态，与消费该状态的面向模型工具和续行策略相互独立。
agent 会话的持久目标状态，独立于消费它的模型工具与续跑策略。goal 状态是所属会话日志的一部分；消费方依赖 `dsh-goal`，绝不依赖具体 agent loop。
| 包 | 职责 | ctx 键 |
|---|---|---|
@@ -11,4 +11,4 @@ goal 家族负责持久目标状态，与消费该状态的面向模型工具和
| [`tool-goal/`](tool-goal/README.md) | 面向模型的目标工具 | 无 |
| [`command-goal/`](command-goal/README.md) | 面向用户的目标命令 | 无 |
目标状态是其所属会话日志的一部分。消费方依赖 `dsh-goal`，而不是具体的 agent loop（智能体循环）；续行行为由基于公开 agent seam 的独立插件负责。
子系统参考——goal 标识、生命周期快照、激活、变更记录——见 [docs/subsystems/goal.md](../../docs/subsystems/goal.md)。

4
packages/guard/README.i18n.yaml
View File

@@ -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/guard/README.md
README.md: 5791474a2fd6aeda728d4c335c930069ade6e023
README.zh.md: 82d779d2f1834317672b8fb03f2a4a875bb566fc
README.md: f0a80b1f497ee5b2459bebb55f886b42d74e4323
README.zh.md: c7747e2febcb1656925fd556743eb2dd28090e37

2
packages/guard/README.md
View File

@@ -8,3 +8,5 @@ Behavioral guard plugins watch the agent loop for unproductive patterns and enfo
|---|---|---|
| [`repeat-tool-guard/`](repeat-tool-guard/README.md) | Advisory reminders for repeated tool calls | listens on tool and agent events |
| [`timeout-policy/`](timeout-policy/README.md) | Arms per-call tool deadlines as deployment policy | registers a `tools/execute` listener |
Reminders travel as `additionalContexts` on the `tools/post-execute` decision and are appended as logged plugin-sourced `user/message` events ([tools](../../docs/subsystems/tools.md)); the timeout split across `dsh-timeout`, capability termination, and this policy layer is recorded in the [timeout-library Agent Note](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md).

2
packages/guard/README.zh.md
View File

@@ -8,3 +8,5 @@
|---|---|---|
| [`repeat-tool-guard/`](repeat-tool-guard/README.md) | 针对重复工具调用的建议性提醒 | 监听工具和 agent 事件 |
| [`timeout-policy/`](timeout-policy/README.md) | 以部署策略形式设置单次工具调用截止时间 | 注册 `tools/execute` 监听器 |
提醒作为 `additionalContexts` 随 `tools/post-execute` 决策传递，并以插件来源的 `user/message` 事件记录（[工具](../../docs/subsystems/tools.md)）；跨 `dsh-timeout`、能力方终止与本策略层的超时拆分记录在[超时库 Agent Note](../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)。

4
packages/host/README.i18n.yaml
View File

@@ -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/host/README.md
README.md: 269a27f51c842f13bc11c175916b7be22db72bd2
README.zh.md: 559bf785eb45d59a30f676b98c14143c69d57edd
README.md: 926cb0b6b87a8ee76cb2dab745a31f620f4e7f5c
README.zh.md: dc617084c756b80716f9a02bd2d22ba6954030f6

2
packages/host/README.md
View File

@@ -15,3 +15,5 @@ The host side of the dsh web GUI: the API gateway every client shape shares, and
| [`directory-picker-auto/`](directory-picker-auto/README.md) | Host-adaptive picker composition | mounts a backend |
`apiproxy` remains transport-independent; [`client/connection`](../client/connection/README.md) supplies the browser/HTTP carrier. Picker implementations replace one another behind the shared seam.
The subsystem references: [http-server.md](../../docs/subsystems/http-server.md) and [workspace.md](../../docs/subsystems/workspace.md) (the picker seam).

2
packages/host/README.zh.md
View File

@@ -15,3 +15,5 @@ dsh Web GUI 的宿主侧：所有客户端形态共享的 API 网关，以及承
| [`directory-picker-auto/`](directory-picker-auto/README.md) | 宿主自适应选择器组合 | 挂载一个后端 |
`apiproxy` 保持传输无关；[`client/connection`](../client/connection/README.md) 提供浏览器／HTTP 载体。选择器实现可在共享 seam 后互相替换。
子系统参考：[http-server.md](../../docs/subsystems/http-server.md) 与 [workspace.md](../../docs/subsystems/workspace.md)（挑选 seam）。

4
packages/interaction/README.i18n.yaml
View File

@@ -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/interaction/README.md
README.md: 506b47753fc9250f9f7bd971265421ad46a106b2
README.zh.md: 34d336f3d3c10deab166d5c13bb86c13ee9bced0
README.md: 31a306cb08fe69297b0d0843b57b5e491c0bbe44
README.zh.md: 6eafe8726ba59edd3a6bf739deacc037a9b56b76

2
packages/interaction/README.md
View File

@@ -13,3 +13,5 @@ The seams through which a human collaborates with a running agent — questions,
| [`tool-ask-user/`](tool-ask-user/README.md) | Exposes human questions to the model. | (registers on `ctx.tools`) |
These packages integrate through existing agent and session contracts rather than changing the loop. Interactive applications provide the concrete command, approval, and question adapters; automation uses [`acp/`](../acp/README.md), and runnable demo bundles live under [`examples/`](../examples/README.md). The product [`dsh`](../../apps/cli/README.md) CLI composes these packages directly.
The subsystem references: [approval.md](../../docs/subsystems/approval.md), [permission.md](../../docs/subsystems/permission.md), [user-interaction.md](../../docs/subsystems/user-interaction.md), [commands.md](../../docs/subsystems/commands.md), and [tui.md](../../docs/subsystems/tui.md). The automation-only ACP transport is [`acp/`](../acp/README.md), the SDK's JSON-RPC server half [`scaffold/server`](../scaffold/README.md), and the shared bin boot glue [`boot/`](../boot/README.md).

2
packages/interaction/README.zh.md
View File

@@ -13,3 +13,5 @@
| [`tool-ask-user/`](tool-ask-user/README.md) | 向模型公开用户问题。 | （注册到 `ctx.tools`） |
这些包通过现有的 agent（智能体）和会话契约集成，而不改变循环。交互式应用提供具体的命令、审批和提问适配器；自动化使用 [`acp/`](../acp/README.md)，可运行的演示组合包位于 [`examples/`](../examples/README.md)。产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）直接组合这些包。
子系统参考：[approval.md](../../docs/subsystems/approval.md)、[permission.md](../../docs/subsystems/permission.md)、[user-interaction.md](../../docs/subsystems/user-interaction.md)、[commands.md](../../docs/subsystems/commands.md) 与 [tui.md](../../docs/subsystems/tui.md)。仅自动化的 ACP 传输在 [`acp/`](../acp/README.md)，SDK 的 JSON-RPC 服务器一半在 [`scaffold/server`](../scaffold/README.md)，共享 bin 启动胶水在 [`boot/`](../boot/README.md)。

4
packages/llm/README.i18n.yaml
View File

@@ -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/llm/README.md
README.md: 92d9fbfa2b8c8db4700562009db49229b2189ab3
README.zh.md: 5c6e7aad1db6511bdb660b86e257652128db131f
README.md: 077ae600c89cff80cd71830e37bda00707c1d837
README.zh.md: e2bdad7fd0b33116498b50bfa6527974fa140fc9

2
packages/llm/README.md
View File

@@ -13,3 +13,5 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
| [`llm-pi-ai/`](llm-pi-ai/README.md) | Multi-provider pi-ai adapter | registers on `ctx.llm` |
Adapters register provider routes on the seam; retry and token measurement remain separate consumers. The child READMEs own routing, metadata, replay, and provider-wire details; the [LLM architecture decisions](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) own the rationale.
The subsystem reference — messages and blocks, the model request, the `StreamChunk` protocol, the adapter contract — is [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md) (token measurement: [token-meter.md](../../docs/subsystems/token-meter.md)); see the [twin adapters](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md), [replay token meter](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md), and [routed model context](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Notes.

2
packages/llm/README.zh.md
View File

@@ -13,3 +13,5 @@ LLM（大语言模型）seam 及其提供方适配器。接口包（`llm`）负
| [`llm-pi-ai/`](llm-pi-ai/README.md) | 多提供方 pi-ai 适配器 | 注册到 `ctx.llm` |
适配器在 seam 上注册提供方路由；重试与 token 测量仍是独立消费方。子 README 负责路由、元数据、回放和提供方协议细节；[LLM 架构决策](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)负责设计原理。
子系统参考——消息与内容块、模型请求、`StreamChunk` 协议、适配器契约——见 [docs/subsystems/llm-streaming.md](../../docs/subsystems/llm-streaming.md)（token 计量：[token-meter.md](../../docs/subsystems/token-meter.md)）；另见[孪生适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)、[回放 token 计量](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)与[按路由模型上下文](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) Agent Note。

4
packages/lsp/README.i18n.yaml
View File

@@ -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/lsp/README.md
README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7
README.md: 01c464c9993571990e0542df9fadb2848a6c9a79
README.zh.md: fa7dddeb011bd34c1f9cbe3a9dbf746d7f163897

2
packages/lsp/README.md
View File

@@ -13,3 +13,5 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.
The subsystem reference — operations, coordinates, requests/results, `LspError` — is [docs/subsystems/lsp.md](../../docs/subsystems/lsp.md); design rationale in the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md).

2
packages/lsp/README.zh.md
View File

@@ -13,3 +13,5 @@
接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。
子系统参考——操作、坐标、请求/结果、`LspError`——见 [docs/subsystems/lsp.md](../../docs/subsystems/lsp.md)；设计依据见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)。

4
packages/plan/README.i18n.yaml
View File

@@ -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/plan/README.md
README.md: 598974e105aaeaf3c35418aec0655de2a5ba6888
README.zh.md: 0f54299af5d34555d86d82e83b92d185045e770f
README.md: 535a2b02e297d7c3bc68538fa1d03226089372e0
README.zh.md: f068bf37b44daa0d724fbb85ad85a4d62883e847

2
packages/plan/README.md
View File

@@ -9,3 +9,5 @@ Plan mode is logged, per-agent collaboration state rather than a generic mode re
| [`plan-mode/`](plan-mode/README.md) | Owns plan-mode state, guidance, commands, and review flow | `ctx.planMode` |
The [plan-specific collaboration state](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md) decision records the family design.
The subsystem reference — the `plan/mode` fold, the step-boundary flush, configuration, the exit tool — is [docs/subsystems/plan.md](../../docs/subsystems/plan.md); design in [plan-specific collaboration state](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md).

2
packages/plan/README.zh.md
View File

@@ -9,3 +9,5 @@ Plan mode 是按 agent（智能体）记录的协作状态，而不是通用模
| [`plan-mode/`](plan-mode/README.md) | 负责 plan mode 状态、指引、命令和评审流程 | `ctx.planMode` |
[plan 专用协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)决策记录了该家族的设计。
子系统参考——`plan/mode` 折叠、步边界冲刷、配置、退出工具——见 [docs/subsystems/plan.md](../../docs/subsystems/plan.md)；设计见[计划专属协作状态](../../.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md)。

4
packages/pty/README.i18n.yaml
View File

@@ -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/pty/README.md
README.md: a4f743056b4a524be9623b0f700f37e0534b463f
README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf
README.md: 2afb3cd61ef4bfba460716549d41f799e419ff46
README.zh.md: 57a5c93047ccb970f499f02c0168db7e9f71b622

2
packages/pty/README.md
View File

@@ -11,3 +11,5 @@ English | [中文](README.zh.md)
| `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).
The subsystem reference — ids, backend/session contracts, send readiness, bounded reads — is [docs/subsystems/pty.md](../../docs/subsystems/pty.md); design and deferred boundaries in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).

2
packages/pty/README.zh.md
View File

@@ -11,3 +11,5 @@
| `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
子系统参考——id、后端/会话契约、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与延后边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。

4
packages/sandbox/README.i18n.yaml
View File

@@ -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/README.md
README.md: 1ba56d22330c26302c9283b2319d983ebf902219
README.zh.md: 5daf830854297fe14c6560dbcde8a380ad079a0e
README.md: 61127118c895cce728ab0b4eed387f51054a83f1
README.zh.md: 984a677aad6ab97579abf861ea8b99f149c07d08

2
packages/sandbox/README.md
View File

@@ -11,3 +11,5 @@ This family applies per-session confinement policy to process execution. It cove
| [`sandbox-policy/`](sandbox-policy/README.md) | Resolves durable per-session sandbox policy | `ctx.sandboxPolicy` |
See the [sandbox decision](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) for the capability boundary and the [filesystem integration decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) for cross-family policy use.
The subsystem reference — modes and enforcement, per-call policy, wrapped-argv dialects, fail-closed errors — is [docs/subsystems/sandbox.md](../../docs/subsystems/sandbox.md); the boundary and the cross-family phase live in the [sandbox](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) and [cross-family fs sandbox](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) Agent Notes.

2
packages/sandbox/README.zh.md
View File

@@ -11,3 +11,5 @@
| [`sandbox-policy/`](sandbox-policy/README.md) | 解析持久的逐会话沙箱策略 | `ctx.sandboxPolicy` |
[沙箱决策](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)记录了能力边界，[文件系统集成决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)记录了跨家族策略的使用方式。
子系统参考——模式与强制执行、按调用策略、包装 argv 方言、故障关闭错误——见 [docs/subsystems/sandbox.md](../../docs/subsystems/sandbox.md)；边界与跨家族阶段见[沙箱](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)与[跨家族 fs 沙箱](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) Agent Note。

2
packages/self-modification/README.i18n.yaml
View File

@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/self-modification/README.md
README.md: 53f700993cce8df8729fba5a92a9498fff2412cd
README.zh.md: 9874ead263e9860b94992cb176be3c6f8c454ece
README.zh.md: 90030cda33f47d128041b7619546ac1309b8465a

4
packages/self-modification/README.zh.md
View File

@@ -2,9 +2,11 @@
[English](README.md) | 中文
这些面向模型的工具作用于 agent（智能体）自身所在的实时 Cordis 运行时，可检查已加载的插件和服务接口、挂载模型编写的插件，并将其 dispose（资源释放）——外加受限 repository Plugin 运行时。该组也是未来自我修改类包的落点。设计说明见[工具集 Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
agent 修改自身运行时：检查已加载的插件与服务接口、挂载模型编写的插件并再次 dispose，外加受限 repository Plugin 运行时。该组是未来自我修改类包的落点。设计居所：[工具集 Agent Note](../../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)。
| 包（package） | 角色 | ctx 键 |
|---|---|---|
| [`tool-cordis/`](tool-cordis/README.md) | `cordis_inspect`／`cordis_mount`／`cordis_unmount` 工具：读取当前进程运行时，并在一个自有分组 fiber 下管理内存中的临时插件 | 注册到 `ctx.tools` |
| [`repository-plugin/`](repository-plugin/README.md) | 通过 DSH 自有子 Plugin 准备并挂载静态 repository skills 与通用 `.mcp.json` server | 注册一个 Loader builtin |
工具契约见 [`tool-cordis/README.md`](tool-cordis/README.md) 与 [`repository-plugin/README.md`](repository-plugin/README.md)。

4
packages/session-query/README.i18n.yaml
View File

@@ -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/session-query/README.md
README.md: a9c9f33e2dc67e837c2be728d2b1a937ce50f13d
README.zh.md: a29dedba09271baa5836cb2d9d57c753ee41c660
README.md: 3d5db8da74cb825c701fe50cf518505e9e6bcad9
README.zh.md: fc430cbdc4130f77eb8857c4d88a2435ad0cc97f

2
packages/session-query/README.md
View File

@@ -9,3 +9,5 @@ This family provides authorized retrieval over live and durable session logs, in
| [`session-query/`](session-query/README.md) | Defines trusted reads, relationship queries, and search operations | `ctx.sessionQuery` |
| [`session-query-sqlite/`](session-query-sqlite/README.md) | Implements session queries with SQLite full-text search | `ctx.sessionQuery` |
| [`tool-session-query/`](tool-session-query/README.md) | Exposes workspace-authorized session queries to the model | registers on `ctx.tools` |
The subsystem reference — logical records, bounded reads, traces, filters, result pages — is [docs/subsystems/session-query.md](../../docs/subsystems/session-query.md).

2
packages/session-query/README.zh.md
View File

@@ -9,3 +9,5 @@
| [`session-query/`](session-query/README.md) | 定义可信读取、关系查询和搜索操作 | `ctx.sessionQuery` |
| [`session-query-sqlite/`](session-query-sqlite/README.md) | 使用 SQLite 全文搜索实现会话查询 | `ctx.sessionQuery` |
| [`tool-session-query/`](tool-session-query/README.md) | 向模型公开经过工作区授权的会话查询 | 注册到 `ctx.tools` |
子系统参考——逻辑记录、有界读取、追踪、筛选器、结果页——见 [docs/subsystems/session-query.md](../../docs/subsystems/session-query.md)。

4
packages/session/README.i18n.yaml
View File

@@ -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/session/README.md
README.md: 45eff16ad57ec1ccc8ebdd55db82f41b5adfc111
README.zh.md: 2d67e28ef169f4e4376b2a644a3b842e5835df04
README.md: 586d1be0286a0de935b0b08313e6965452b85376
README.zh.md: 60e58e6d471a48d3ced03a518e96aeeae79110e8

2
packages/session/README.md
View File

@@ -47,3 +47,5 @@ Projects session activity into outbound telemetry and delegates delivery to a co
|---|---|
| [`session-telemetry/`](session-telemetry/README.md) | Defines capture, redaction, projection, and live or on-demand backend delivery. |
| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | Delivers telemetry through OpenTelemetry logs in `FULL`, `FEEDBACK_ONLY`, or `DISABLED` mode. |
The subsystem references: [persistence.md](../../docs/subsystems/persistence.md), [session-projection.md](../../docs/subsystems/session-projection.md), [session-title.md](../../docs/subsystems/session-title.md), and [telemetry.md](../../docs/subsystems/telemetry.md). Only one title provider may register at a time; the demo spine mounts the fallback service and leaves both model providers out of default composition.

2
packages/session/README.zh.md
View File

@@ -47,3 +47,5 @@
|---|---|
| [`session-telemetry/`](session-telemetry/README.md) | 定义捕获、脱敏、投影，以及实时或按需后端投递。 |
| [`session-telemetry-otel/`](session-telemetry-otel/README.md) | 通过 OpenTelemetry 日志以 `FULL`、`FEEDBACK_ONLY` 或 `DISABLED` 模式投递遥测。 |
子系统参考：[persistence.md](../../docs/subsystems/persistence.md)、[session-projection.md](../../docs/subsystems/session-projection.md)、[session-title.md](../../docs/subsystems/session-title.md) 与 [telemetry.md](../../docs/subsystems/telemetry.md)。同一时间只允许一个标题提供方注册；demo 主干挂载回退服务，两个模型提供方都留在默认组合之外。

4
packages/settings/README.i18n.yaml
View File

@@ -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/settings/README.md
README.md: 3f43647f0558abf53c373ef7d97af16c0e17d2fe
README.zh.md: b5779bfe5da4cae148bcc6515ef13790f78bca7a
README.md: 6f3719c58564a90fec3bd9f305cfaeb2b7bf0bf4
README.zh.md: 0efb16dd4e5d5faa5f16814b94d55a20dc4c06c3

2
packages/settings/README.md
View File

@@ -8,3 +8,5 @@ This family resolves user-editable configuration through registered namespaces a
|---|---|---|
| [`settings/`](settings/README.md) | Defines namespace registration, layered resolution, and commits | `ctx.settings` |
| [`settings-local/`](settings-local/README.md) | Stores settings in a local file and observes external edits | registers on `ctx.settings` |
The subsystem reference — namespaces, owner scopes, resolution order, hot commits — is [docs/subsystems/settings.md](../../docs/subsystems/settings.md).

2
packages/settings/README.zh.md
View File

@@ -8,3 +8,5 @@
|---|---|---|
| [`settings/`](settings/README.md) | 定义命名空间注册、分层解析与提交 | `ctx.settings` |
| [`settings-local/`](settings-local/README.md) | 在本地文件中存储设置并观察外部编辑 | 注册到 `ctx.settings` |
子系统参考——命名空间、owner scope、解析顺序、热提交——见 [docs/subsystems/settings.md](../../docs/subsystems/settings.md)。

4
packages/skill/README.i18n.yaml
View File

@@ -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/skill/README.md
README.md: 533904859ad998de4f371a073fde98b68660097b
README.zh.md: 1fad581cc61a05251f671577dcb7edab37281283
README.md: cd606e778335249bf8ecc876d3b1a4e5feb79448
README.zh.md: 4db7e2524596f4c62144ec7eabe7c6af63e2e270

2
packages/skill/README.md
View File

@@ -12,3 +12,5 @@ This family discovers reusable agent instructions and exposes them to the model
| [`tool-skill/`](tool-skill/README.md) | Publishes the skill catalog and model-facing loader | registers on `ctx.tools` |
This capability remains outside the core control spine and can use local, embedded, or remote providers without changing the model-facing contract.
The subsystem reference — discovery priority, catalog snapshots, the `skill` loader — is [docs/subsystems/skills.md](../../docs/subsystems/skills.md).

2
packages/skill/README.zh.md
View File

@@ -12,3 +12,5 @@
| [`tool-skill/`](tool-skill/README.md) | 发布 skill 目录和面向模型的 loader | 注册到 `ctx.tools` |
该能力位于核心控制主干之外，可以使用本地、嵌入式或远程提供方，而无需更改面向模型的契约。
子系统参考——发现优先级、目录快照、`skill` 加载器——见 [docs/subsystems/skills.md](../../docs/subsystems/skills.md)。

4
packages/spill/README.i18n.yaml
View File

@@ -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/spill/README.md
README.md: b96375b1a332cd6e3e4da9c8b1c98011aa97c8bc
README.zh.md: c8495068edf1035937c99198dfdb5db65c9a9e59
README.md: 74fd4837cb23767754174df168f2f4ba71c2b938
README.zh.md: 16d677719a9c3f4245a2f446017641ff6b50ffa8

2
packages/spill/README.md
View File

@@ -11,3 +11,5 @@ This family persists oversized tool output and replaces the inline result with a
| [`spill-policy/`](spill-policy/README.md) | Applies the post-execution spill policy | listens on `ctx.tools` |
See the [tool-output spill decision](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the boundary between storage, retention, and tool-owned output handling.
The subsystem reference — `SaveTextSpill`, owners/sources, the branded locator — is [docs/subsystems/spill.md](../../docs/subsystems/spill.md); rationale in the [tool output spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md).

2
packages/spill/README.zh.md
View File

@@ -11,3 +11,5 @@
| [`spill-policy/`](spill-policy/README.md) | 应用执行后 spill 策略 | 监听 `ctx.tools` |
参见[工具输出 spill 决策](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中记录了存储、保留和工具自有输出处理之间的边界。
子系统参考——`SaveTextSpill`、owner/来源、品牌化定位符——见 [docs/subsystems/spill.md](../../docs/subsystems/spill.md)；依据见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。

4
packages/storage/README.i18n.yaml
View File

@@ -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/storage/README.md
README.md: a5f9d0204b93445699d28b1285a4a18f0408930e
README.zh.md: 0710dfb57f96011755b253ad95a0f9d2c0923a70
README.md: a178495fca5cc433182b8e75f20d479cb7c5bc99
README.zh.md: 1a08f1676e5c699a55f9956a42059d1f5acf7e8d

2
packages/storage/README.md
View File

@@ -12,3 +12,5 @@ This family persists application data other than session event logs through name
| [`storage-domain/`](storage-domain/README.md) | Provides validated domain-record storage | `ctx.storageDomain` |
Consumers use a data form rather than accessing a backend directly. The [domain storage decision](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) records the family design.
The subsystem reference — the backend seam, `StorageForms`, `DomainSpec`/`Domain`, `domain/changed` — is [docs/subsystems/storage.md](../../docs/subsystems/storage.md).

2
packages/storage/README.zh.md
View File

@@ -12,3 +12,5 @@
| [`storage-domain/`](storage-domain/README.md) | 提供经过验证的领域记录存储 | `ctx.storageDomain` |
消费方使用数据形式，而不是直接访问后端。[领域存储决策](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)记录了该家族的设计。
子系统参考——后端 seam、`StorageForms`、`DomainSpec`/`Domain`、`domain/changed`——见 [docs/subsystems/storage.md](../../docs/subsystems/storage.md)。

4
packages/subagent/README.i18n.yaml
View File

@@ -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/subagent/README.md
README.md: 0a342569e66539e4987710b2e56f2946c97b1ac1
README.zh.md: 5d2f7beef478b8bfd27b4772c7a951ea62cb10ef
README.md: c8969ad313fc673456d2740b40d90c6d8db794ac
README.zh.md: fb18afba5d8680408f0f37ab75056a3fb0ef660a

2
packages/subagent/README.md
View File

@@ -19,3 +19,5 @@ This family lets an agent delegate work to child agents. Multiple named provider
| [`tool-subagent-report/`](tool-subagent-report/README.md) | Provides the child-to-parent report channel | registers in child scopes |
See the decisions for the [capability family](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable children](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [control tools](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
The subsystem reference — start requests, results, live runs, the provider seam, continuable background children — is [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md); design rationale in the [subagent capability seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [continuable background subagents](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), and [merged subagent control service](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Notes.

2
packages/subagent/README.zh.md
View File

@@ -19,3 +19,5 @@
| [`tool-subagent-report/`](tool-subagent-report/README.md) | 提供从子级到父级的报告通道 | 注册到子级作用域 |
参见[能力家族](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续执行的子级](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)和[控制工具](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)决策。
子系统参考——启动请求、结果、实时运行、提供方 seam、可续跑后台子 agent——见 [docs/subsystems/subagent.md](../../docs/subsystems/subagent.md)；设计依据见 [subagent 能力 seam](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可续跑后台 subagent](../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md) 与[合并 subagent 控制服务](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md) Agent Note。

4
packages/subprocess/README.i18n.yaml
View File

@@ -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/README.md
README.md: f2b19436da40feb14d067e2cfc706222625680b5
README.zh.md: 938312448dd5c0a691ed07ddc9843cf2c4445637
README.md: 9a8628e2b6d16852895be33ae516c8b33b078502
README.zh.md: d2c539fb1c66a914aa5f758d928fba01b5600d15

2
packages/subprocess/README.md
View File

@@ -10,3 +10,5 @@ The shared process substrate for one execution world: executable lookup, fully-s
| [`subprocess-local`](subprocess-local/README.md) (`@deepseek-ai/dsh-subprocess-local`) | — | The local implementation: detached process trees, bounded collection/spill, `node-pty`, foreground/session inspection, tree signalling, and terminate-and-join disposal |
The service owns process lifetime across consumer reloads; consumers own what a process means (a bash command, a future non-shell runner) and every default that shapes one.
The subsystem reference — spawn specs, output readers, outcomes, the `DSH_*` environment — is [docs/subsystems/subprocess.md](../../docs/subsystems/subprocess.md); the seam decision in the [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).

2
packages/subprocess/README.zh.md
View File

@@ -10,3 +10,5 @@
| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、有界收集／spill、`node-pty`、前台／会话检查、进程树信号发送，以及先终止再等待退出的资源释放 |
即使消费方重载，进程生命周期仍由服务负责管理；消费方负责定义进程的含义（一条 bash 命令、未来的非 shell 运行器），以及决定塑造该进程的每一项默认值。
子系统参考——spawn spec、输出读取器、结果、`DSH_*` 环境——见 [docs/subsystems/subprocess.md](../../docs/subsystems/subprocess.md)；seam 决定见 [subprocess seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。

4
packages/support/README.i18n.yaml
View File

@@ -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/support/README.md
README.md: 15cb82d3d76a1241af8b40e1c8536292618409a9
README.zh.md: ff8595b47f1a1220912dc77a072463adf74f7bf9
README.md: bf0bba1ea7d21700a6743195ec966512c20e01bc
README.zh.md: 47eba4d51c66914f388ba4a5925323173d5ed7e2

2
packages/support/README.md
View File

@@ -14,3 +14,5 @@ These packages support repository development, tests, and examples rather than p
| [`llm-replay/`](llm-replay/README.md) | Replays recorded model responses for keyless tests and demos |
A package moves out of `support/` when it gains a product contract and product consumers.
The invariants contract is documented in [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md).

2
packages/support/README.zh.md
View File

@@ -14,3 +14,5 @@
| [`llm-replay/`](llm-replay/README.md) | 为无密钥测试和演示回放已记录的模型响应 |
当一个包获得产品契约和产品消费方时，它会移出 `support/`。
不变式契约记录在 [docs/subsystems/invariants.md](../../docs/subsystems/invariants.md)。

4
packages/tasks/README.i18n.yaml
View File

@@ -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/README.md
README.md: 05ed9c439684337c45abe11f03c861a1b795b2ac
README.zh.md: 16fe6c0a2b183b719cb6aa8ac068e34d51832a2b
README.md: e0b6769cd1d28cc7159310a6ec6f5c8d94a81a24
README.zh.md: d030081470a503fb52fd72dcc6f89f4c535dc38c

2
packages/tasks/README.md
View File

@@ -11,3 +11,5 @@ This family gives long-running tools one owner-isolated background-task protocol
| [`tool-tasks/`](tool-tasks/README.md) | Exposes task control and completion notices to the model | registers on `ctx.tools` |
See the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) decisions.
The subsystem reference — the id scheme, the owner-fenced contract, snapshots — is [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md); design in the [background-task runtime](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and [task-registry seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Notes.

2
packages/tasks/README.zh.md
View File

@@ -11,3 +11,5 @@
| [`tool-tasks/`](tool-tasks/README.md) | 向模型公开任务控制和完成通知 | 注册到 `ctx.tools` |
参见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和[任务注册表](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)决策。
子系统参考——id 方案、拥有者围栏契约、快照——见 [docs/subsystems/tasks.md](../../docs/subsystems/tasks.md)；设计见[后台任务运行时](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与[任务注册表 seam](../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md) Agent Note。

4
packages/todo/README.i18n.yaml
View File

@@ -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/todo/README.md
README.md: 66abf18131ee53d87e933757c40117841e94b07f
README.zh.md: 38a6b3c22653b8e22cc0b693eb666620513a3d8c
README.md: 6c7dccbbfb007737593550cea91444f8f735cf81
README.zh.md: 3c1c35187b5111f1fdb607d70b980be57e3e79c1

2
packages/todo/README.md
View File

@@ -9,3 +9,5 @@ The model-facing todo capability. It is a single **product** package because one
| [`tool-todo/`](tool-todo/README.md) | Stores and exposes the session's todo list. | (registers on `ctx.tools`) |
The child README owns the tool, persistence, and rendering contract.
The event payload is documented on [docs/subsystems/session.md](../../docs/subsystems/session.md).

2
packages/todo/README.zh.md
View File

@@ -9,3 +9,5 @@
| [`tool-todo/`](tool-todo/README.md) | 存储并公开会话的 todo 列表。 | （注册到 `ctx.tools`） |
子级 README 负责工具、持久化和渲染契约。
事件载荷记录在 [docs/subsystems/session.md](../../docs/subsystems/session.md)。

4
packages/web/README.i18n.yaml
View File

@@ -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/web/README.md
README.md: 65b3dde1e2f9c35c308a10ca80245064f7a0361e
README.zh.md: 43b8b7d9c53336e984d9c61fa9b612fc1733e31f
README.md: 811c8b3439a8962116df0e8b3ab4f6e282ecb3d2
README.zh.md: e328447d5d026c0abc815b269179ba6c4cd9acfc

2
packages/web/README.md
View File

@@ -14,3 +14,5 @@ This family provides provider-neutral web search and fetch operations plus the m
| [`tool-web/`](tool-web/README.md) | Exposes web search and fetch to the model | registers on `ctx.tools` |
The [web capability decision](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) records why search and fetch share one provider-selection service.
The subsystem reference — search/fetch requests and results, availability, `WebError` — is [docs/subsystems/web.md](../../docs/subsystems/web.md); rationale (including deferred SSRF protection) in the [web capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md).

2
packages/web/README.zh.md
View File

@@ -14,3 +14,5 @@
| [`tool-web/`](tool-web/README.md) | 向模型公开 web 搜索和抓取 | 注册到 `ctx.tools` |
[web 能力决策](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)记录了搜索和抓取共用一项提供方选择服务的原因。
子系统参考——搜索/抓取请求与结果、可用性、`WebError`——见 [docs/subsystems/web.md](../../docs/subsystems/web.md)；依据（含延后的 SSRF 防护）见 [web 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)。

4
packages/workflow/README.i18n.yaml
View File

@@ -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/workflow/README.md
README.md: 2416e26e73340a6d8624b8e77681dfc9f55fe7c5
README.zh.md: a5c94a0a9799d78e5cca72394385b38d2fb2ba70
README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22

2
packages/workflow/README.md
View File

@@ -12,3 +12,5 @@ This family runs model-authored orchestration workflows over subagents and expos
| [`tool-ralph/`](tool-ralph/README.md) | Exposes the fixed fresh-agent Ralph workflow | registers on `ctx.tools` |
Worker threads isolate workflow execution from the host event loop but are not a security boundary. See the [dynamic-workflow](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) and [Ralph tool](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) decisions.
The subsystem reference — start requests, `WorkflowMeta`, results, live runs, `workflow/*` events — is [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md); decisions in the [dynamic-workflows](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) and [Ralph consumer](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Notes.

2
packages/workflow/README.zh.md
View File

@@ -12,3 +12,5 @@
| [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。

4
packages/workspace/README.i18n.yaml
View File

@@ -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/workspace/README.md
README.md: 9f6ead776c1e5d36af5b6917ad8f27725b11e6a0
README.zh.md: aa691ec681112f4c25a6391c33eabd2711c7abfc
README.md: 7e30f26a9854031b4907ad3e7edb35da5986d5d9
README.zh.md: 6315ccb6b3a8b86161728e8296746efd0c334a29

2
packages/workspace/README.md
View File

@@ -9,3 +9,5 @@ This family owns persistent workspaces: user directories with titles and ordered
| [`workspace/`](workspace/README.md) | Registers workspaces and accounts for their sessions | `ctx.workspace` |
The [workspace package reference](workspace/README.md) owns lifecycle, persistence, and deletion semantics.
The subsystem reference — the entity, realpath canon, registration/resolution — is [docs/subsystems/workspace.md](../../docs/subsystems/workspace.md); storage design in the [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).

Some files were not shown because too many files have changed in this diff Show More