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

Merge branch 'master' into worktree/python-sdk-model-visible-assertions

Browse Source
This commit is contained in:
Yichen Jiang
2026-08-17 17:01:52 +08:00
committed by GitHub
parent 8692a1b76b e0bb7cafc0
commit 47d6760052
995 changed files with 10894 additions and 69959 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/architecture.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 docs/architecture.md
architecture.md: ad5b9072d2731b0b68c5f6035dafe37bc6229de8
architecture.zh.md: 24ccd3bfbbd86213134201e49c8e768037eecd38
architecture.md: a1507fa5e54f6703e89f09a5d387e6c9afc81ade
architecture.zh.md: 4642a1e7691bccf4d52d9a84c92c8237c3c6658b

4
docs/architecture.md
View File

@@ -97,7 +97,7 @@ The session log is the source of the context the model sees. `deriveMessages()`
## Capability seams
A **seam** is a swappable capability with three roles: a **Service Definition** declaring the interface, a **Service provider** implementing it, and a **Consumer** using it, commonly a model-facing tool. A package may combine roles, but one role alone is not a seam; adding a capability means designing all three ([capability graph](capability-seams.md)).
A **seam** is a swappable capability with three roles: a **Service Definition** declaring the interface, a **Service Provider** implementing it, and a **Consumer** using it, commonly a model-facing tool. A package may combine roles, but one role alone is not a seam; adding a capability means designing all three ([capability graph](capability-seams.md)).
Seams are why one provider swap changes the whole product. Filesystem and subprocess providers share one execution world, so pointing them at a remote sandbox moves Bash, PTY, and LSP with them, with no provider forks. [Subagent providers](subsystems/subagent.md) vary just as widely behind one interface, from a fresh child agent to a delegated turn in another product.
@@ -126,4 +126,4 @@ New behavior attaches to a documented extension point. Changing the loop itself
| Fork a live session | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
| Scope a registration to one agent | use that agent's `agent.ctx` |
The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities and indexes the step-by-step guides for [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [Chat nodes](cookbook/adding-a-conversation-node.md).
The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities and indexes the step-by-step guides for [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), [Chat nodes](cookbook/adding-a-conversation-node.md), and [settings cards](cookbook/adding-a-settings-card.md).

8
docs/architecture.zh.md
View File

@@ -50,6 +50,8 @@ dsh --profile web --dump-config
| [`core/scope`](subsystems/scope.md) | 按 agent 划分作用域的注册原语 | 库，无 ctx 键 |
| [`llm/llm`](subsystems/llm-streaming.md) | 消息与流式词汇表，以及适配器 seam | `ctx.llm` |
<a id="events"></a>
## 事件
事件就是扩展点，而选对事件域是大多数改动的第一个决定。
@@ -60,6 +62,8 @@ dsh --profile web --dump-config
[事件映射](event-producer-consumer.md)列出每个事件的生产方与消费方。
<a id="turn-flow"></a>
## 轮次流程
一个**步骤**是一次模型请求加上它调用的工具。一个**轮次**包含零个或多个步骤：它在领取首条输入之前打开，并在不再欠下任何工作时关闭。
@@ -97,7 +101,7 @@ turn/end
## 能力 seam
一个 **seam** 是一项可替换能力，包含三种角色：声明接口的 **Service Definition**、实现它的 **Service provider**，以及使用它的 **Consumer**（通常是面向模型的工具）。一个包可以合并承担多个角色，但单一角色本身不是 seam；添加一项能力意味着把三者一并设计（[能力图](capability-seams.md)）。
一个 **seam** 是一项可替换能力，包含三种角色：声明接口的 **Service Definition**、实现它的 **Service Provider**，以及使用它的 **Consumer**（通常是面向模型的工具）。一个包可以合并承担多个角色，但单一角色本身不是 seam；添加一项能力意味着把三者一并设计（[能力图](capability-seams.md)）。
seam 正是替换一个提供方就能改变整个产品的原因。文件系统与进程提供方共享同一个执行世界，因此把它们指向远程沙箱，也就把 Bash、PTY 和 LSP 一并搬了过去，无需提供方专用 fork。[subagent 提供方](subsystems/subagent.md)在同一个接口之后同样千差万别，从新建一个子 agent，到把一个轮次委派给另一个产品。
@@ -126,4 +130,4 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统
| fork 活跃会话 | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
| 将注册项限定到单个 agent | 使用该 agent 的 `agent.ctx` |
[扩展实操手册](cookbook/extension-cookbook.md)将功能映射到能力，并索引[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM（大语言模型）适配器](cookbook/adding-an-llm-adapter.md)和 [Chat 节点](cookbook/adding-a-conversation-node.md)的分步指南。
[扩展实操手册](cookbook/extension-cookbook.md)将功能映射到能力，并索引[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM（大语言模型）适配器](cookbook/adding-an-llm-adapter.md)、[Chat 节点](cookbook/adding-a-conversation-node.md)和[设置卡片](cookbook/adding-a-settings-card.md)的分步指南。

4
docs/config-catalog.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 docs/config-catalog.md
config-catalog.md: 09c6064c2c6bb3c1da6283a885db33a5b4a674df
config-catalog.zh.md: 0bd95a5ab24b7acf85ba7ca00125ea9135e7dd82
config-catalog.md: 4f22ed3da7de81f94d6fc5ee55a305d117c126e7
config-catalog.zh.md: 7054ec8b52a8c46bc1ace97112f086119a61cfec

247
docs/config-catalog.md
View File

@@ -9,6 +9,8 @@ This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verifie
A `Requires:` line lists the service keys the plugin `inject`s: its `cordis.yml` tree must also load providers for those services. Scope is the harness tier (`packages/`); the vendored cordis plugins a config tree may also load (`hmr`, the console logger, …) are pinned upstream source ([vendoring policy](../vendor/README.md)) and not catalogued here.
<a id="deepseek-aidsh-acp"></a>
## `@deepseek-ai/dsh-acp`
Requires: `agents`
@@ -29,6 +31,8 @@ Depends on: `Stream` (`@agentclientprotocol/sdk`)
Source: [`packages/acp/acp/src/index.ts:70`](../packages/acp/acp/src/index.ts)
<a id="deepseek-aidsh-acp-demo"></a>
## `@deepseek-ai/dsh-acp-demo`
```ts config-catalog
@@ -82,6 +86,8 @@ Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) ·
Source: [`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
<a id="deepseek-aidsh-agent-default-model"></a>
## `@deepseek-ai/dsh-agent-default-model`
```ts config-catalog
@@ -96,6 +102,8 @@ export interface Config {
Source: [`packages/core/agent-default-model/src/index.ts:41`](../packages/core/agent-default-model/src/index.ts)
<a id="deepseek-aidsh-agent-instructions"></a>
## `@deepseek-ai/dsh-agent-instructions`
```ts config-catalog
@@ -124,6 +132,8 @@ export interface Config {
Source: [`packages/context/agent-instructions/src/config.ts:18`](../packages/context/agent-instructions/src/config.ts)
<a id="deepseek-aidsh-agent-loop"></a>
## `@deepseek-ai/dsh-agent-loop`
Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt`
@@ -154,6 +164,8 @@ Depends on: [`AgentOptions`](subsystems/core.md) · [`SessionId`](subsystems/cor
Source: [`packages/core/agent-loop/src/index.ts:255`](../packages/core/agent-loop/src/index.ts)
<a id="deepseek-aidsh-agent-presets"></a>
## `@deepseek-ai/dsh-agent-presets`
Requires: `loader`
@@ -190,15 +202,18 @@ export type PresetTrust = 'system' | 'user'
Source: [`packages/preset/agent-presets/src/preset.ts:52`](../packages/preset/agent-presets/src/preset.ts)
<a id="deepseek-aidsh-agent-spine-demo"></a>
## `@deepseek-ai/dsh-agent-spine-demo`
```ts config-catalog
/**
* Bundle config: each field forwarded verbatim to the child that owns it —
* `agents` to the agent loop (an app that pre-creates no agents, like the ACP
* bridge, simply omits it), `includeHarnessIdentity`, `persona`, and `toolOrder`
* to the system-prompt plugin (the fixed opener, deployment persona, and explicit
* model-facing tool order), the `tools` object to the tool registry (its presentation `mode`),
* bridge, simply omits it), `includeHarnessIdentity`, `includeRuntimeContext`,
* `persona`, and `toolOrder` to the system-prompt plugin (the fixed opener,
* dynamic-context policy, deployment persona, and explicit model-facing tool
* order), the `tools` object to the tool registry (its presentation `mode`),
* `dshHome` to bash environment and local skill discovery, `sessionTitle` to
* the fallback title service, `skills` to the
* skill registry/local provider/tool consumer, `workspaceContext` to the
@@ -222,6 +237,8 @@ export interface Config {
maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls']
/** Whether the system prompt includes the fixed Harness identity (default true). */
includeHarnessIdentity?: SystemPromptConfig['includeHarnessIdentity']
/** Whether model history includes dynamic runtime-context snapshots (default true). */
includeRuntimeContext?: SystemPromptConfig['includeRuntimeContext']
/** The deployment persona (see dsh-system-prompt's `Config`). */
persona?: SystemPromptConfig['persona']
/** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
@@ -275,7 +292,9 @@ export interface GoalConfig {
Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`GoalDomainConfig`](#deepseek-aidsh-goal) · [`InvariantConfig`](#deepseek-aidsh-invariants) · [`JobsConfig`](#deepseek-aidsh-jobs-local) · [`SessionTitleConfig`](#deepseek-aidsh-session-title) · [`SkillFileSystem`](../packages/skill/skill-filesystem/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/shell/tool-bash/src/index.ts) · [`toolGoal`](../packages/goal/tool-goal/src/index.ts) · [`toolJobs`](../packages/jobs/tool-jobs/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`workspaceContext`](../packages/context/agent-instructions/src/index.ts)
Source: [`packages/examples/agent-spine-demo/src/index.ts:91`](../packages/examples/agent-spine-demo/src/index.ts)
Source: [`packages/examples/agent-spine-demo/src/index.ts:92`](../packages/examples/agent-spine-demo/src/index.ts)
<a id="deepseek-aidsh-agent-tool-presentation"></a>
## `@deepseek-ai/dsh-agent-tool-presentation`
@@ -299,6 +318,8 @@ Depends on: [`ToolPresentationMode`](subsystems/tools.md)
Source: [`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts)
<a id="deepseek-aidsh-attachment-local"></a>
## `@deepseek-ai/dsh-attachment-local`
```ts config-catalog
@@ -319,6 +340,8 @@ export interface Config {
Source: [`packages/attachment/attachment-local/src/index.ts:24`](../packages/attachment/attachment-local/src/index.ts)
<a id="deepseek-aidsh-bash-local"></a>
## `@deepseek-ai/dsh-bash-local`
Requires: `subprocess`
@@ -343,6 +366,8 @@ export interface Config {
Source: [`packages/shell/bash-local/src/index.ts:41`](../packages/shell/bash-local/src/index.ts)
<a id="deepseek-aidsh-bash-sandbox"></a>
## `@deepseek-ai/dsh-bash-sandbox`
Requires: `subprocess` · `sandbox` · `sandboxPolicy`
@@ -362,6 +387,8 @@ Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local)
Source: [`packages/shell/bash-sandbox/src/index.ts:35`](../packages/shell/bash-sandbox/src/index.ts)
<a id="deepseek-aidsh-client-connection"></a>
## `@deepseek-ai/dsh-client-connection`
Requires: `webServer`
@@ -385,6 +412,8 @@ export interface ConnectionConfig {
Source: [`packages/client/connection/src/index.ts:50`](../packages/client/connection/src/index.ts)
<a id="deepseek-aidsh-client-hmr"></a>
## `@deepseek-ai/dsh-client-hmr`
Requires: `clientModules` · `webServer`
@@ -399,6 +428,8 @@ export interface Config {
Source: [`packages/client/hmr/src/index.ts:31`](../packages/client/hmr/src/index.ts)
<a id="deepseek-aidsh-code-runtime-worker-thread"></a>
## `@deepseek-ai/dsh-code-runtime-worker-thread`
```ts config-catalog
@@ -434,6 +465,8 @@ export interface Config {
Source: [`packages/code-runtime/code-runtime-worker-thread/src/index.ts:25`](../packages/code-runtime/code-runtime-worker-thread/src/index.ts)
<a id="deepseek-aidsh-compaction-basic"></a>
## `@deepseek-ai/dsh-compaction-basic`
Requires: `llm` · `tokenMeter` · `sessions`
@@ -478,6 +511,8 @@ export interface ModelCompactPolicyConfig extends CompactionPolicyConfig {
Source: [`packages/compaction/compaction-basic/src/types.ts:38`](../packages/compaction/compaction-basic/src/types.ts)
<a id="deepseek-aidsh-compaction-tool-result-pruner"></a>
## `@deepseek-ai/dsh-compaction-tool-result-pruner`
Requires: `tokenMeter`
@@ -496,6 +531,8 @@ export interface ToolResultPruneConfig {
Source: [`packages/compaction/compaction-tool-result-pruner/src/types.ts:4`](../packages/compaction/compaction-tool-result-pruner/src/types.ts)
<a id="deepseek-aidsh-cordis-host-runner"></a>
## `@deepseek-ai/dsh-cordis-host-runner`
Requires: `tools`
@@ -510,6 +547,8 @@ export interface Config {
Source: [`packages/extensions/cordis-host-runner/src/index.ts:88`](../packages/extensions/cordis-host-runner/src/index.ts)
<a id="deepseek-aidsh-credentials-local"></a>
## `@deepseek-ai/dsh-credentials-local`
```ts config-catalog
@@ -528,6 +567,8 @@ export interface Config {
Source: [`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
<a id="deepseek-aidsh-e2b"></a>
## `@deepseek-ai/dsh-e2b`
```ts config-catalog
@@ -544,6 +585,8 @@ export interface Config {
Source: [`packages/e2b/e2b/src/index.ts:43`](../packages/e2b/e2b/src/index.ts)
<a id="deepseek-aidsh-fs-local"></a>
## `@deepseek-ai/dsh-fs-local`
```ts config-catalog
@@ -561,6 +604,8 @@ export interface Config {
Source: [`packages/fs/fs-local/src/index.ts:41`](../packages/fs/fs-local/src/index.ts)
<a id="deepseek-aidsh-fs-sandbox"></a>
## `@deepseek-ai/dsh-fs-sandbox`
Requires: `sandboxPolicy`
@@ -579,6 +624,8 @@ Depends on: [`LocalConfig`](#deepseek-aidsh-fs-local)
Source: [`packages/fs/fs-sandbox/src/index.ts:49`](../packages/fs/fs-sandbox/src/index.ts)
<a id="deepseek-aidsh-goal"></a>
## `@deepseek-ai/dsh-goal`
Requires: `agents`
@@ -593,6 +640,8 @@ export interface Config {
Source: [`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.ts)
<a id="deepseek-aidsh-headless"></a>
## `@deepseek-ai/dsh-headless`
Requires: `agentDefaultModel` · `agents` · `sessions`
@@ -607,6 +656,8 @@ export interface Config {
Source: [`packages/bundle/headless/src/index.ts:31`](../packages/bundle/headless/src/index.ts)
<a id="deepseek-aidsh-hooks-claude-code"></a>
## `@deepseek-ai/dsh-hooks-claude-code`
Requires: `shell`
@@ -643,6 +694,8 @@ export interface Config {
Source: [`packages/hooks/hooks-claude-code/src/index.ts:45`](../packages/hooks/hooks-claude-code/src/index.ts)
<a id="deepseek-aidsh-hooks-codex"></a>
## `@deepseek-ai/dsh-hooks-codex`
Requires: `shell`
@@ -668,6 +721,8 @@ export interface Config {
Source: [`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-codex/src/index.ts)
<a id="deepseek-aidsh-host-apiproxy"></a>
## `@deepseek-ai/dsh-host-apiproxy`
Requires: `agentDefaultModel` · `agents` · `attachments` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userQuestions` · `workspaceRegistry`
@@ -689,11 +744,19 @@ export interface Config {
* @default 6
*/
sessionExportCompressionLevel?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
/**
* Maximum physical size of a cold Session artifact eligible for blankness
* verification. Zero disables probes.
* @default 1024
*/
coldBlankProbeMaxBytes?: number
}
```
Source: [`packages/host/apiproxy/src/index.ts:41`](../packages/host/apiproxy/src/index.ts)
<a id="deepseek-aidsh-host-directory-picker-browse"></a>
## `@deepseek-ai/dsh-host-directory-picker-browse`
```ts config-catalog
@@ -706,6 +769,8 @@ export interface Config {
Source: [`packages/host/directory-picker-browse/src/index.ts:181`](../packages/host/directory-picker-browse/src/index.ts)
<a id="deepseek-aidsh-host-frontend-static"></a>
## `@deepseek-ai/dsh-host-frontend-static`
Requires: `webServer`
@@ -720,6 +785,8 @@ export interface Config {
Source: [`packages/host/frontend-static/src/index.ts:28`](../packages/host/frontend-static/src/index.ts)
<a id="deepseek-aidsh-host-webserver"></a>
## `@deepseek-ai/dsh-host-webserver`
```ts config-catalog
@@ -734,6 +801,8 @@ export interface Config {
Source: [`packages/host/webserver/src/index.ts:45`](../packages/host/webserver/src/index.ts)
<a id="deepseek-aidsh-invariants"></a>
## `@deepseek-ai/dsh-invariants`
```ts config-catalog
@@ -750,6 +819,8 @@ export interface Config {
Source: [`packages/runtime-diagnostics/invariants/src/index.ts:15`](../packages/runtime-diagnostics/invariants/src/index.ts)
<a id="deepseek-aidsh-jobs-local"></a>
## `@deepseek-ai/dsh-jobs-local`
```ts config-catalog
@@ -765,6 +836,8 @@ export interface Config {
Source: [`packages/jobs/jobs-local/src/index.ts:31`](../packages/jobs/jobs-local/src/index.ts)
<a id="deepseek-aidsh-llm-deepseek"></a>
## `@deepseek-ai/dsh-llm-deepseek`
Requires: `llm`
@@ -786,7 +859,7 @@ export interface Config {
/** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
thinking?: 'enabled' | 'disabled'
/** Default thinking effort (default `high`); `off` disables thinking per request. */
reasoningEffort?: 'off' | 'high' | 'max'
reasoningEffort?: 'off' | 'low' | 'high' | 'max'
/** Default per-request output cap (default 256,000); a model's own cap and explicit request values win. */
maxTokens?: number
/** Positive context capacity used when the selected model has no exact value (default 1,000,000). */
@@ -818,6 +891,8 @@ Depends on: [`RetryPolicyConfig`](../packages/llm/llm/src/index.ts)
Source: [`packages/llm/llm-deepseek/src/index.ts:62`](../packages/llm/llm-deepseek/src/index.ts)
<a id="deepseek-aidsh-llm-pi-ai"></a>
## `@deepseek-ai/dsh-llm-pi-ai`
Requires: `llm`
@@ -1006,6 +1081,8 @@ Depends on: `Api` (`@earendil-works/pi-ai`) · `CacheRetention` (`@earendil-work
Source: [`packages/llm/llm-pi-ai/src/config.ts:172`](../packages/llm/llm-pi-ai/src/config.ts)
<a id="deepseek-aidsh-llm-replay"></a>
## `@deepseek-ai/dsh-llm-replay`
Requires: `llm`
@@ -1072,6 +1149,8 @@ Depends on: [`ModelModality`](../packages/llm/llm/src/index.ts) · [`RetryPolicy
Source: [`packages/test-support/llm-replay/src/index.ts:776`](../packages/test-support/llm-replay/src/index.ts)
<a id="deepseek-aidsh-llm-retry"></a>
## `@deepseek-ai/dsh-llm-retry`
Requires: `agents`
@@ -1083,6 +1162,8 @@ export type Config = Readonly<Record<string, never>>
Source: [`packages/llm/llm-retry/src/index.ts:24`](../packages/llm/llm-retry/src/index.ts)
<a id="deepseek-aidsh-lsp-stdio"></a>
## `@deepseek-ai/dsh-lsp-stdio`
Requires: `fs` · `lsp` · `subprocess`
@@ -1123,6 +1204,8 @@ export interface LspLocalServerConfig {
Source: [`packages/lsp/lsp-stdio/src/index.ts:82`](../packages/lsp/lsp-stdio/src/index.ts)
<a id="deepseek-aidsh-mcp-client"></a>
## `@deepseek-ai/dsh-mcp-client`
Requires: `tools`
@@ -1194,6 +1277,8 @@ export interface ReconnectConfig {
Source: [`packages/mcp/mcp-client/src/index.ts:98`](../packages/mcp/mcp-client/src/index.ts)
<a id="deepseek-aidsh-message-feedback"></a>
## `@deepseek-ai/dsh-message-feedback`
Requires: `storageDomain` · `sessionPersistence` · `sessions`
@@ -1208,6 +1293,8 @@ export interface Config {
Source: [`packages/feedback/message-feedback/src/index.ts:49`](../packages/feedback/message-feedback/src/index.ts)
<a id="deepseek-aidsh-permission-presets"></a>
## `@deepseek-ai/dsh-permission-presets`
Requires: `shell` · `approval` · `sessions`
@@ -1245,6 +1332,8 @@ Depends on: [`ApprovalPolicy`](subsystems/approval.md) · [`SandboxMode`](subsys
Source: [`packages/interaction/permission-presets/src/index.ts:140`](../packages/interaction/permission-presets/src/index.ts)
<a id="deepseek-aidsh-persona"></a>
## `@deepseek-ai/dsh-persona`
Requires: `systemPrompt`
@@ -1260,11 +1349,15 @@ export interface Config {
text: string
/** Make this persona the complete system prompt, suppressing every other section. */
complete?: boolean
/** Suppress dynamic runtime-context snapshots for this persona's agent scope. */
includeRuntimeContext?: boolean
}
```
Source: [`packages/preset/persona/src/index.ts:34`](../packages/preset/persona/src/index.ts)
<a id="deepseek-aidsh-plan-mode"></a>
## `@deepseek-ai/dsh-plan-mode`
Requires: `tools` · `systemPrompt`
@@ -1279,6 +1372,8 @@ export interface PlanModeConfig {
Source: [`packages/plan/plan-mode/src/index.ts:70`](../packages/plan/plan-mode/src/index.ts)
<a id="deepseek-aidsh-pwsh-local"></a>
## `@deepseek-ai/dsh-pwsh-local`
Requires: `subprocess`
@@ -1310,6 +1405,8 @@ export interface Config {
Source: [`packages/shell/pwsh-local/src/index.ts:58`](../packages/shell/pwsh-local/src/index.ts)
<a id="deepseek-aidsh-pwsh-sandbox"></a>
## `@deepseek-ai/dsh-pwsh-sandbox`
Requires: `subprocess` · `sandbox` · `sandboxPolicy`
@@ -1330,6 +1427,8 @@ Depends on: [`LocalConfig`](#deepseek-aidsh-pwsh-local)
Source: [`packages/shell/pwsh-sandbox/src/index.ts:40`](../packages/shell/pwsh-sandbox/src/index.ts)
<a id="deepseek-aidsh-repeat-tool-reminder"></a>
## `@deepseek-ai/dsh-repeat-tool-reminder`
```ts config-catalog
@@ -1362,6 +1461,8 @@ export interface Config {
Source: [`packages/guard/repeat-tool-reminder/src/index.ts:28`](../packages/guard/repeat-tool-reminder/src/index.ts)
<a id="deepseek-aidsh-sandbox-local"></a>
## `@deepseek-ai/dsh-sandbox-local`
```ts config-catalog
@@ -1392,6 +1493,8 @@ export interface Config {
Source: [`packages/sandbox/sandbox-local/src/index.ts:44`](../packages/sandbox/sandbox-local/src/index.ts)
<a id="deepseek-aidsh-sandbox-policy"></a>
## `@deepseek-ai/dsh-sandbox-policy`
```ts config-catalog
@@ -1417,6 +1520,8 @@ Depends on: [`SandboxMode`](subsystems/sandbox.md)
Source: [`packages/sandbox/sandbox-policy/src/index.ts:67`](../packages/sandbox/sandbox-policy/src/index.ts)
<a id="deepseek-aidsh-sdk-jsonrpc-server"></a>
## `@deepseek-ai/dsh-sdk-jsonrpc-server`
Requires: `agents`
@@ -1439,6 +1544,8 @@ Depends on: `Readable` (`node:stream`) · `Writable` (`node:stream`)
Source: [`packages/sdk/server/src/index.ts:25`](../packages/sdk/server/src/index.ts)
<a id="deepseek-aidsh-session-persistence-jsonl"></a>
## `@deepseek-ai/dsh-session-persistence-jsonl`
Requires: `sessions`
@@ -1476,6 +1583,8 @@ export type JsonlCompression = 'zstd' | 'none'
Source: [`packages/session/session-persistence-jsonl/src/index.ts:60`](../packages/session/session-persistence-jsonl/src/index.ts)
<a id="deepseek-aidsh-session-persistence-sqlite"></a>
## `@deepseek-ai/dsh-session-persistence-sqlite`
Requires: `sessions`
@@ -1519,6 +1628,8 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
Source: [`packages/session/session-persistence-sqlite/src/index.ts:70`](../packages/session/session-persistence-sqlite/src/index.ts)
<a id="deepseek-aidsh-session-projection-cache"></a>
## `@deepseek-ai/dsh-session-projection-cache`
Requires: `storageDomain` · `sessionProjections` · `sessionPersistence` · `sessions`
@@ -1540,6 +1651,8 @@ export interface Config {
Source: [`packages/session/session-projection-cache/src/index.ts:42`](../packages/session/session-projection-cache/src/index.ts)
<a id="deepseek-aidsh-session-query-sqlite"></a>
## `@deepseek-ai/dsh-session-query-sqlite`
Requires: `sessions`
@@ -1553,7 +1666,13 @@ export interface Config extends SessionQueryConfig {
* POSIX filesystems; existing modes are preserved.
*/
path: string
/** Open the SQLite module and handle at service activation or the first search. Defaults to `startup`. */
/**
* Open the SQLite module and handle at service activation or the first
* search, or `never` to disable full-text search: the inherited exact
* reads, filters, and traces stay available, while `searchSessions` and
* `searchEvents` fail with `SESSION_QUERY_SEARCH_DISABLED` and SQLite is
* never imported or opened. Defaults to `startup`.
*/
openAt?: OpenAt
/** SQLite journal mode. Defaults to `wal`. */
journalMode?: JournalMode
@@ -1567,8 +1686,8 @@ export interface Config extends SessionQueryConfig {
persistedInspectConcurrency?: number
}
/** SQLite module/handle opening phase. */
export type OpenAt = 'startup' | 'first-search'
/** SQLite module/handle opening phase; `never` disables full-text search entirely. */
export type OpenAt = 'startup' | 'first-search' | 'never'
/** Supported SQLite journal modes. */
export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
@@ -1578,6 +1697,8 @@ Depends on: [`SessionQueryConfig`](../packages/session-query/session-query/src/i
Source: [`packages/session-query/session-query-sqlite/src/index.ts:89`](../packages/session-query/session-query-sqlite/src/index.ts)
<a id="deepseek-aidsh-session-reference"></a>
## `@deepseek-ai/dsh-session-reference`
Requires: `sessionQuery`
@@ -1596,6 +1717,8 @@ export interface Config {
Source: [`packages/context/session-reference/src/config.ts:11`](../packages/context/session-reference/src/config.ts)
<a id="deepseek-aidsh-session-telemetry-otel"></a>
## `@deepseek-ai/dsh-session-telemetry-otel`
Requires: `sessions`
@@ -1640,6 +1763,8 @@ Depends on: `BatchLogRecordProcessorOptions` (`@opentelemetry/sdk-logs`) · `OTL
Source: [`packages/session/session-telemetry-otel/src/index.ts:91`](../packages/session/session-telemetry-otel/src/index.ts)
<a id="deepseek-aidsh-session-title"></a>
## `@deepseek-ai/dsh-session-title`
Requires: `sessions`
@@ -1658,6 +1783,8 @@ export interface Config {
Source: [`packages/session/session-title/src/index.ts:79`](../packages/session/session-title/src/index.ts)
<a id="deepseek-aidsh-session-title-all-prompts-llm"></a>
## `@deepseek-ai/dsh-session-title-all-prompts-llm`
Requires: `sessionTitle` · `llm` · `sessions`
@@ -1671,6 +1798,8 @@ Depends on: [`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/
Source: [`packages/session/session-title-all-prompts-llm/src/index.ts:15`](../packages/session/session-title-all-prompts-llm/src/index.ts)
<a id="deepseek-aidsh-session-title-first-prompt-llm"></a>
## `@deepseek-ai/dsh-session-title-first-prompt-llm`
Requires: `sessionTitle` · `llm` · `sessions`
@@ -1684,6 +1813,8 @@ Depends on: [`SessionTitleLlmConfig`](../packages/session/session-title-llm/src/
Source: [`packages/session/session-title-first-prompt-llm/src/index.ts:15`](../packages/session/session-title-first-prompt-llm/src/index.ts)
<a id="deepseek-aidsh-settings-file"></a>
## `@deepseek-ai/dsh-settings-file`
```ts config-catalog
@@ -1702,6 +1833,8 @@ export interface Config {
Source: [`packages/settings/settings-file/src/index.ts:21`](../packages/settings/settings-file/src/index.ts)
<a id="deepseek-aidsh-shell-env"></a>
## `@deepseek-ai/dsh-shell-env`
```ts config-catalog
@@ -1714,6 +1847,8 @@ export interface Config {
Source: [`packages/shell/shell-env/src/index.ts:29`](../packages/shell/shell-env/src/index.ts)
<a id="deepseek-aidsh-skill"></a>
## `@deepseek-ai/dsh-skill`
```ts config-catalog
@@ -1726,6 +1861,8 @@ export interface Config {
Source: [`packages/skill/skill/src/index.ts:279`](../packages/skill/skill/src/index.ts)
<a id="deepseek-aidsh-skill-filesystem"></a>
## `@deepseek-ai/dsh-skill-filesystem`
Requires: `skills`
@@ -1762,6 +1899,8 @@ export interface Config {
Source: [`packages/skill/skill-filesystem/src/index.ts:49`](../packages/skill/skill-filesystem/src/index.ts)
<a id="deepseek-aidsh-spill-local"></a>
## `@deepseek-ai/dsh-spill-local`
```ts config-catalog
@@ -1778,6 +1917,8 @@ export interface Config {
Source: [`packages/spill/spill-local/src/index.ts:22`](../packages/spill/spill-local/src/index.ts)
<a id="deepseek-aidsh-spill-policy"></a>
## `@deepseek-ai/dsh-spill-policy`
Requires: `tools`
@@ -1796,6 +1937,8 @@ export interface Config {
Source: [`packages/spill/spill-policy/src/index.ts:60`](../packages/spill/spill-policy/src/index.ts)
<a id="deepseek-aidsh-storage-domain"></a>
## `@deepseek-ai/dsh-storage-domain`
Requires: `storage`
@@ -1817,6 +1960,8 @@ export interface Config {
Source: [`packages/storage/storage-domain/src/index.ts:52`](../packages/storage/storage-domain/src/index.ts)
<a id="deepseek-aidsh-storage-json"></a>
## `@deepseek-ai/dsh-storage-json`
Requires: `storage`
@@ -1836,6 +1981,8 @@ export interface Config {
Source: [`packages/storage/storage-json/src/index.ts:27`](../packages/storage/storage-json/src/index.ts)
<a id="deepseek-aidsh-storage-sqlite"></a>
## `@deepseek-ai/dsh-storage-sqlite`
Requires: `storage`
@@ -1874,6 +2021,8 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
Source: [`packages/storage/storage-sqlite/src/index.ts:24`](../packages/storage/storage-sqlite/src/index.ts)
<a id="deepseek-aidsh-subagent-acp"></a>
## `@deepseek-ai/dsh-subagent-acp`
Requires: `subagents` · `subprocess`
@@ -1925,6 +2074,8 @@ export type PermissionPolicy = 'allow' | 'reject'
Source: [`packages/subagent/subagent-acp/src/index.ts:27`](../packages/subagent/subagent-acp/src/index.ts)
<a id="deepseek-aidsh-subagent-claude-code"></a>
## `@deepseek-ai/dsh-subagent-claude-code`
Requires: `subagents` · `subprocess`
@@ -1944,6 +2095,8 @@ export interface Config {
Source: [`packages/subagent/subagent-claude-code/src/index.ts:32`](../packages/subagent/subagent-claude-code/src/index.ts)
<a id="deepseek-aidsh-subagent-codex"></a>
## `@deepseek-ai/dsh-subagent-codex`
Requires: `subagents` · `subprocess`
@@ -1963,6 +2116,8 @@ export interface Config {
Source: [`packages/subagent/subagent-codex/src/index.ts:30`](../packages/subagent/subagent-codex/src/index.ts)
<a id="deepseek-aidsh-subagent-dsh-sdk"></a>
## `@deepseek-ai/dsh-subagent-dsh-sdk`
Requires: `subagents`
@@ -2014,6 +2169,8 @@ export interface Config {
Source: [`packages/subagent/subagent-dsh-sdk/src/index.ts:29`](../packages/subagent/subagent-dsh-sdk/src/index.ts)
<a id="deepseek-aidsh-subagent-fork-in-process"></a>
## `@deepseek-ai/dsh-subagent-fork-in-process`
Requires: `subagents`
@@ -2028,6 +2185,8 @@ export interface Config {
Source: [`packages/subagent/subagent-fork-in-process/src/index.ts:31`](../packages/subagent/subagent-fork-in-process/src/index.ts)
<a id="deepseek-aidsh-subagent-spawn-in-process"></a>
## `@deepseek-ai/dsh-subagent-spawn-in-process`
Requires: `subagents`
@@ -2042,6 +2201,8 @@ export interface Config {
Source: [`packages/subagent/subagent-spawn-in-process/src/index.ts:25`](../packages/subagent/subagent-spawn-in-process/src/index.ts)
<a id="deepseek-aidsh-subprocess-e2b"></a>
## `@deepseek-ai/dsh-subprocess-e2b`
Requires: `e2b`
@@ -2056,6 +2217,8 @@ export interface Config {
Source: [`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts)
<a id="deepseek-aidsh-system-prompt"></a>
## `@deepseek-ai/dsh-system-prompt`
```ts config-catalog
@@ -2063,6 +2226,8 @@ Source: [`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subproce
export interface Config {
/** Include the fixed DeepSeek Harness identity before the deployment persona (default true). */
includeHarnessIdentity?: boolean
/** Include dynamic runtime-context snapshots in model history (default true). */
includeRuntimeContext?: boolean
/**
* Deployment-wide order-0 persona template. A scoped section named
* `deployment:persona` shadows it; `{{variable}}` references are strict.
@@ -2079,6 +2244,8 @@ export interface Config {
Source: [`packages/core/system-prompt/src/index.ts:186`](../packages/core/system-prompt/src/index.ts)
<a id="deepseek-aidsh-terminal-bash"></a>
## `@deepseek-ai/dsh-terminal-bash`
Requires: `terminals` · `sandboxPolicy` · `subprocess`
@@ -2122,6 +2289,8 @@ export interface Config {
Source: [`packages/terminal/terminal-bash/src/config.ts:6`](../packages/terminal/terminal-bash/src/config.ts)
<a id="deepseek-aidsh-time-context"></a>
## `@deepseek-ai/dsh-time-context`
Requires: `agents`
@@ -2138,6 +2307,8 @@ export interface Config {
Source: [`packages/context/time-context/src/index.ts:27`](../packages/context/time-context/src/index.ts)
<a id="deepseek-aidsh-tmux-context"></a>
## `@deepseek-ai/dsh-tmux-context`
Requires: `agents`
@@ -2152,6 +2323,8 @@ export interface Config {
Source: [`packages/context/tmux-context/src/index.ts:34`](../packages/context/tmux-context/src/index.ts)
<a id="deepseek-aidsh-token-meter"></a>
## `@deepseek-ai/dsh-token-meter`
```ts config-catalog
@@ -2161,6 +2334,8 @@ export type TokenMeterConfig = Record<string, never>
Source: [`packages/llm/token-meter/src/types.ts:12`](../packages/llm/token-meter/src/types.ts)
<a id="deepseek-aidsh-tool-bash"></a>
## `@deepseek-ai/dsh-tool-bash`
Requires: `tools` · `shell` · `systemPrompt` · `shellEnv`
@@ -2175,6 +2350,8 @@ export interface Config {
Source: [`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts)
<a id="deepseek-aidsh-tool-bash-persistent"></a>
## `@deepseek-ai/dsh-tool-bash-persistent`
Requires: `tools` · `terminals`
@@ -2193,7 +2370,9 @@ export interface Config {
}
```
Source: [`packages/shell/tool-bash-persistent/src/index.ts:405`](../packages/shell/tool-bash-persistent/src/index.ts)
Source: [`packages/shell/tool-bash-persistent/src/index.ts:400`](../packages/shell/tool-bash-persistent/src/index.ts)
<a id="deepseek-aidsh-tool-fs"></a>
## `@deepseek-ai/dsh-tool-fs`
@@ -2215,6 +2394,8 @@ export interface Config {
Source: [`packages/fs/tool-fs/src/index.ts:25`](../packages/fs/tool-fs/src/index.ts)
<a id="deepseek-aidsh-tool-fs-search"></a>
## `@deepseek-ai/dsh-tool-fs-search`
Requires: `tools` · `systemPrompt` · `subprocess`
@@ -2248,6 +2429,8 @@ export interface Config {
Source: [`packages/fs/tool-fs-search/src/index.ts:73`](../packages/fs/tool-fs-search/src/index.ts)
<a id="deepseek-aidsh-tool-goal"></a>
## `@deepseek-ai/dsh-tool-goal`
Requires: `agents` · `goals` · `tools` · `systemPrompt`
@@ -2262,6 +2445,8 @@ export interface Config {
Source: [`packages/goal/tool-goal/src/index.ts:26`](../packages/goal/tool-goal/src/index.ts)
<a id="deepseek-aidsh-tool-jobs"></a>
## `@deepseek-ai/dsh-tool-jobs`
Requires: `tools` · `jobs` · `systemPrompt`
@@ -2294,6 +2479,8 @@ export type CompletionDelivery = 'quiet' | 'wakeup'
Source: [`packages/jobs/tool-jobs/src/index.ts:32`](../packages/jobs/tool-jobs/src/index.ts)
<a id="deepseek-aidsh-tool-lsp"></a>
## `@deepseek-ai/dsh-tool-lsp`
Requires: `tools` · `lsp` · `systemPrompt`
@@ -2312,6 +2499,8 @@ export interface Config {
Source: [`packages/lsp/tool-lsp/src/index.ts:58`](../packages/lsp/tool-lsp/src/index.ts)
<a id="deepseek-aidsh-tool-pwsh"></a>
## `@deepseek-ai/dsh-tool-pwsh`
Requires: `tools` · `shell` · `systemPrompt` · `shellEnv`
@@ -2326,6 +2515,8 @@ export interface Config {
Source: [`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts)
<a id="deepseek-aidsh-tool-ralph"></a>
## `@deepseek-ai/dsh-tool-ralph`
Requires: `tools` · `workflowEngine` · `subagents` · `systemPrompt`
@@ -2346,6 +2537,8 @@ export interface Config {
Source: [`packages/workflow/tool-ralph/src/index.ts:23`](../packages/workflow/tool-ralph/src/index.ts)
<a id="deepseek-aidsh-tool-session-query"></a>
## `@deepseek-ai/dsh-tool-session-query`
Requires: `tools` · `systemPrompt` · `sessionQuery`
@@ -2362,6 +2555,8 @@ export interface Config {
Source: [`packages/session-query/tool-session-query/src/index.ts:29`](../packages/session-query/tool-session-query/src/index.ts)
<a id="deepseek-aidsh-tool-skill"></a>
## `@deepseek-ai/dsh-tool-skill`
Requires: `agents` · `tools` · `skills`
@@ -2376,6 +2571,8 @@ export interface Config {
Source: [`packages/skill/tool-skill/src/index.ts:61`](../packages/skill/tool-skill/src/index.ts)
<a id="deepseek-aidsh-tool-str-replace-editor"></a>
## `@deepseek-ai/dsh-tool-str-replace-editor`
Requires: `tools` · `fs`
@@ -2392,6 +2589,8 @@ export interface Config {
Source: [`packages/fs/tool-str-replace-editor/src/index.ts:497`](../packages/fs/tool-str-replace-editor/src/index.ts)
<a id="deepseek-aidsh-tool-subagent"></a>
## `@deepseek-ai/dsh-tool-subagent`
Requires: `tools` · `subagents` · `systemPrompt`
@@ -2455,6 +2654,8 @@ Depends on: [`AgentOptions`](subsystems/core.md)
Source: [`packages/subagent/tool-subagent/src/index.ts:29`](../packages/subagent/tool-subagent/src/index.ts)
<a id="deepseek-aidsh-tool-subagent-report"></a>
## `@deepseek-ai/dsh-tool-subagent-report`
Requires: `subagents` · `tools` · `systemPrompt`
@@ -2475,6 +2676,8 @@ Depends on: [`SubagentReportDelivery`](subsystems/subagent.md)
Source: [`packages/subagent/tool-subagent-report/src/index.ts:27`](../packages/subagent/tool-subagent-report/src/index.ts)
<a id="deepseek-aidsh-tool-terminal"></a>
## `@deepseek-ai/dsh-tool-terminal`
Requires: `terminals` · `tools` · `systemPrompt`
@@ -2491,6 +2694,8 @@ export interface Config {
Source: [`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts)
<a id="deepseek-aidsh-tool-todo"></a>
## `@deepseek-ai/dsh-tool-todo`
Requires: `tools`
@@ -2511,6 +2716,8 @@ export interface Config {
Source: [`packages/todo/tool-todo/src/index.ts:29`](../packages/todo/tool-todo/src/index.ts)
<a id="deepseek-aidsh-tool-web"></a>
## `@deepseek-ai/dsh-tool-web`
Requires: `tools` · `web` · `systemPrompt`
@@ -2535,6 +2742,8 @@ export interface Config {
Source: [`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts)
<a id="deepseek-aidsh-tool-workflow"></a>
## `@deepseek-ai/dsh-tool-workflow`
Requires: `tools` · `workflowEngine` · `systemPrompt`
@@ -2551,6 +2760,8 @@ export interface Config {
Source: [`packages/workflow/tool-workflow/src/index.ts:33`](../packages/workflow/tool-workflow/src/index.ts)
<a id="deepseek-aidsh-tools"></a>
## `@deepseek-ai/dsh-tools`
Requires: `systemPrompt`
@@ -2585,6 +2796,8 @@ export type ToolPresentationMode = 'native' | 'code' | 'both'
Source: [`packages/core/tools/src/index.ts:654`](../packages/core/tools/src/index.ts)
<a id="deepseek-aidsh-typert-loader"></a>
## `@deepseek-ai/dsh-typert-loader`
Requires: `typert` · `loader`
@@ -2599,6 +2812,8 @@ export interface Config {
Source: [`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts)
<a id="deepseek-aidsh-user-approval"></a>
## `@deepseek-ai/dsh-user-approval`
```ts config-catalog
@@ -2628,6 +2843,8 @@ export type ApprovalPolicy = 'ask' | 'never'
Source: [`packages/interaction/user-approval/src/index.ts:177`](../packages/interaction/user-approval/src/index.ts)
<a id="deepseek-aidsh-web"></a>
## `@deepseek-ai/dsh-web`
```ts config-catalog
@@ -2647,6 +2864,8 @@ export interface WebRuntimeConfig {
Source: [`packages/web/web/src/index.ts:55`](../packages/web/web/src/index.ts)
<a id="deepseek-aidsh-web-app"></a>
## `@deepseek-ai/dsh-web-app`
Requires: `webServer`
@@ -2670,6 +2889,8 @@ export interface Config {
Source: [`packages/bundle/web-app/src/index.ts:38`](../packages/bundle/web-app/src/index.ts)
<a id="deepseek-aidsh-web-fetch-http"></a>
## `@deepseek-ai/dsh-web-fetch-http`
Requires: `web`
@@ -2694,6 +2915,8 @@ export interface Config {
Source: [`packages/web/web-fetch-http/src/index.ts:34`](../packages/web/web-fetch-http/src/index.ts)
<a id="deepseek-aidsh-web-search-deepseek"></a>
## `@deepseek-ai/dsh-web-search-deepseek`
Requires: `web`
@@ -2720,6 +2943,8 @@ export interface Config {
Source: [`packages/web/web-search-deepseek/src/index.ts:46`](../packages/web/web-search-deepseek/src/index.ts)
<a id="deepseek-aidsh-web-search-exa"></a>
## `@deepseek-ai/dsh-web-search-exa`
Requires: `web`
@@ -2742,6 +2967,8 @@ export interface Config {
Source: [`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
<a id="deepseek-aidsh-web-search-perplexity"></a>
## `@deepseek-ai/dsh-web-search-perplexity`
Requires: `web`
@@ -2764,6 +2991,8 @@ export interface Config {
Source: [`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
<a id="deepseek-aidsh-workflow-worker-thread"></a>
## `@deepseek-ai/dsh-workflow-worker-thread`
Requires: `subagents`

247
docs/config-catalog.zh.md
View File

@@ -11,6 +11,8 @@
`Requires:` 行列出插件通过 `inject` 注入的服务键：其 `cordis.yml` 树还必须加载这些服务的提供者。范围限定为 harness 层级（`packages/`）；配置树还可能加载的 vendored cordis 插件（`hmr`、控制台日志记录器等）固定为上游源代码（参见 [vendoring policy](../vendor/README.md)），未收录于此目录。
<a id="deepseek-aidsh-acp"></a>
## `@deepseek-ai/dsh-acp`
需要：`agents`
@@ -31,6 +33,8 @@ export interface AcpConfig {
来源：[`packages/acp/acp/src/index.ts:70`](../packages/acp/acp/src/index.ts)
<a id="deepseek-aidsh-acp-demo"></a>
## `@deepseek-ai/dsh-acp-demo`
```ts config-catalog
@@ -84,6 +88,8 @@ export interface Config {
来源：[`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
<a id="deepseek-aidsh-agent-default-model"></a>
## `@deepseek-ai/dsh-agent-default-model`
```ts config-catalog
@@ -98,6 +104,8 @@ export interface Config {
来源：[`packages/core/agent-default-model/src/index.ts:41`](../packages/core/agent-default-model/src/index.ts)
<a id="deepseek-aidsh-agent-instructions"></a>
## `@deepseek-ai/dsh-agent-instructions`
```ts config-catalog
@@ -126,6 +134,8 @@ export interface Config {
来源：[`packages/context/agent-instructions/src/config.ts:18`](../packages/context/agent-instructions/src/config.ts)
<a id="deepseek-aidsh-agent-loop"></a>
## `@deepseek-ai/dsh-agent-loop`
需要：`agents` · `sessions` · `llm` · `tools` · `systemPrompt`
@@ -156,6 +166,8 @@ export interface Config {
来源：[`packages/core/agent-loop/src/index.ts:255`](../packages/core/agent-loop/src/index.ts)
<a id="deepseek-aidsh-agent-presets"></a>
## `@deepseek-ai/dsh-agent-presets`
需要：`loader`
@@ -192,15 +204,18 @@ export type PresetTrust = 'system' | 'user'
来源：[`packages/preset/agent-presets/src/preset.ts:52`](../packages/preset/agent-presets/src/preset.ts)
<a id="deepseek-aidsh-agent-spine-demo"></a>
## `@deepseek-ai/dsh-agent-spine-demo`
```ts config-catalog
/**
* Bundle config: each field forwarded verbatim to the child that owns it —
* `agents` to the agent loop (an app that pre-creates no agents, like the ACP
* bridge, simply omits it), `includeHarnessIdentity`, `persona`, and `toolOrder`
* to the system-prompt plugin (the fixed opener, deployment persona, and explicit
* model-facing tool order), the `tools` object to the tool registry (its presentation `mode`),
* bridge, simply omits it), `includeHarnessIdentity`, `includeRuntimeContext`,
* `persona`, and `toolOrder` to the system-prompt plugin (the fixed opener,
* dynamic-context policy, deployment persona, and explicit model-facing tool
* order), the `tools` object to the tool registry (its presentation `mode`),
* `dshHome` to bash environment and local skill discovery, `sessionTitle` to
* the fallback title service, `skills` to the
* skill registry/local provider/tool consumer, `workspaceContext` to the
@@ -224,6 +239,8 @@ export interface Config {
maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls']
/** Whether the system prompt includes the fixed Harness identity (default true). */
includeHarnessIdentity?: SystemPromptConfig['includeHarnessIdentity']
/** Whether model history includes dynamic runtime-context snapshots (default true). */
includeRuntimeContext?: SystemPromptConfig['includeRuntimeContext']
/** The deployment persona (see dsh-system-prompt's `Config`). */
persona?: SystemPromptConfig['persona']
/** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
@@ -277,7 +294,9 @@ export interface GoalConfig {
依赖：[`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`GoalDomainConfig`](#deepseek-aidsh-goal) · [`InvariantConfig`](#deepseek-aidsh-invariants) · [`JobsConfig`](#deepseek-aidsh-jobs-local) · [`SessionTitleConfig`](#deepseek-aidsh-session-title) · [`SkillFileSystem`](../packages/skill/skill-filesystem/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/shell/tool-bash/src/index.ts) · [`toolGoal`](../packages/goal/tool-goal/src/index.ts) · [`toolJobs`](../packages/jobs/tool-jobs/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`workspaceContext`](../packages/context/agent-instructions/src/index.ts)
来源：[`packages/examples/agent-spine-demo/src/index.ts:91`](../packages/examples/agent-spine-demo/src/index.ts)
来源：[`packages/examples/agent-spine-demo/src/index.ts:92`](../packages/examples/agent-spine-demo/src/index.ts)
<a id="deepseek-aidsh-agent-tool-presentation"></a>
## `@deepseek-ai/dsh-agent-tool-presentation`
@@ -301,6 +320,8 @@ export interface Config {
来源：[`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts)
<a id="deepseek-aidsh-attachment-local"></a>
## `@deepseek-ai/dsh-attachment-local`
```ts config-catalog
@@ -321,6 +342,8 @@ export interface Config {
来源：[`packages/attachment/attachment-local/src/index.ts:24`](../packages/attachment/attachment-local/src/index.ts)
<a id="deepseek-aidsh-bash-local"></a>
## `@deepseek-ai/dsh-bash-local`
需要：`subprocess`
@@ -345,6 +368,8 @@ export interface Config {
来源：[`packages/shell/bash-local/src/index.ts:41`](../packages/shell/bash-local/src/index.ts)
<a id="deepseek-aidsh-bash-sandbox"></a>
## `@deepseek-ai/dsh-bash-sandbox`
需要：`subprocess` · `sandbox` · `sandboxPolicy`
@@ -364,6 +389,8 @@ export type Config = LocalConfig
来源：[`packages/shell/bash-sandbox/src/index.ts:35`](../packages/shell/bash-sandbox/src/index.ts)
<a id="deepseek-aidsh-client-connection"></a>
## `@deepseek-ai/dsh-client-connection`
需要：`webServer`
@@ -387,6 +414,8 @@ export interface ConnectionConfig {
来源：[`packages/client/connection/src/index.ts:50`](../packages/client/connection/src/index.ts)
<a id="deepseek-aidsh-client-hmr"></a>
## `@deepseek-ai/dsh-client-hmr`
需要：`clientModuleHost` · `webServer`
@@ -401,6 +430,8 @@ export interface Config {
来源：[`packages/client/hmr/src/index.ts:31`](../packages/client/hmr/src/index.ts)
<a id="deepseek-aidsh-code-runtime-worker-thread"></a>
## `@deepseek-ai/dsh-code-runtime-worker-thread`
```ts config-catalog
@@ -436,6 +467,8 @@ export interface Config {
来源：[`packages/code-runtime/code-runtime-worker-thread/src/index.ts:25`](../packages/code-runtime/code-runtime-worker-thread/src/index.ts)
<a id="deepseek-aidsh-compaction-basic"></a>
## `@deepseek-ai/dsh-compaction-basic`
需要：`llm` · `tokenMeter` · `sessions`
@@ -480,6 +513,8 @@ export interface ModelCompactPolicyConfig extends CompactionPolicyConfig {
来源：[`packages/compaction/compaction-basic/src/types.ts:38`](../packages/compaction/compaction-basic/src/types.ts)
<a id="deepseek-aidsh-compaction-tool-result-pruner"></a>
## `@deepseek-ai/dsh-compaction-tool-result-pruner`
需要：`tokenMeter`
@@ -498,6 +533,8 @@ export interface ToolResultPruneConfig {
来源：[`packages/compaction/compaction-tool-result-pruner/src/types.ts:4`](../packages/compaction/compaction-tool-result-pruner/src/types.ts)
<a id="deepseek-aidsh-cordis-host-runner"></a>
## `@deepseek-ai/dsh-cordis-host-runner`
需要：`tools`
@@ -512,6 +549,8 @@ export interface Config {
来源：[`packages/extensions/cordis-host-runner/src/index.ts:88`](../packages/extensions/cordis-host-runner/src/index.ts)
<a id="deepseek-aidsh-credentials-local"></a>
## `@deepseek-ai/dsh-credentials-local`
```ts config-catalog
@@ -530,6 +569,8 @@ export interface Config {
来源：[`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts)
<a id="deepseek-aidsh-e2b"></a>
## `@deepseek-ai/dsh-e2b`
```ts config-catalog
@@ -546,6 +587,8 @@ export interface Config {
来源：[`packages/e2b/e2b/src/index.ts:43`](../packages/e2b/e2b/src/index.ts)
<a id="deepseek-aidsh-fs-local"></a>
## `@deepseek-ai/dsh-fs-local`
```ts config-catalog
@@ -563,6 +606,8 @@ export interface Config {
来源：[`packages/fs/fs-local/src/index.ts:41`](../packages/fs/fs-local/src/index.ts)
<a id="deepseek-aidsh-fs-sandbox"></a>
## `@deepseek-ai/dsh-fs-sandbox`
需要：`sandboxPolicy`
@@ -581,6 +626,8 @@ export type Config = LocalConfig
来源：[`packages/fs/fs-sandbox/src/index.ts:49`](../packages/fs/fs-sandbox/src/index.ts)
<a id="deepseek-aidsh-goal"></a>
## `@deepseek-ai/dsh-goal`
需要：`agents`
@@ -595,6 +642,8 @@ export interface Config {
来源：[`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.ts)
<a id="deepseek-aidsh-headless"></a>
## `@deepseek-ai/dsh-headless`
需要：`agentDefaultModel` · `agents` · `sessions`
@@ -609,6 +658,8 @@ export interface Config {
来源：[`packages/bundle/headless/src/index.ts:31`](../packages/bundle/headless/src/index.ts)
<a id="deepseek-aidsh-hooks-claude-code"></a>
## `@deepseek-ai/dsh-hooks-claude-code`
需要：`bash`
@@ -645,6 +696,8 @@ export interface Config {
来源：[`packages/hooks/hooks-claude-code/src/index.ts:45`](../packages/hooks/hooks-claude-code/src/index.ts)
<a id="deepseek-aidsh-hooks-codex"></a>
## `@deepseek-ai/dsh-hooks-codex`
需要：`bash`
@@ -670,6 +723,8 @@ export interface Config {
来源：[`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-codex/src/index.ts)
<a id="deepseek-aidsh-host-apiproxy"></a>
## `@deepseek-ai/dsh-host-apiproxy`
需要：`agentDefaultModel` · `agents` · `attachments` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
@@ -691,11 +746,19 @@ export interface Config {
* @default 6
*/
sessionExportCompressionLevel?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
/**
* Maximum physical size of a cold Session artifact eligible for blankness
* verification. Zero disables probes.
* @default 1024
*/
coldBlankProbeMaxBytes?: number
}
```
来源：[`packages/host/apiproxy/src/index.ts:41`](../packages/host/apiproxy/src/index.ts)
<a id="deepseek-aidsh-host-directory-picker-browse"></a>
## `@deepseek-ai/dsh-host-directory-picker-browse`
```ts config-catalog
@@ -708,6 +771,8 @@ export interface Config {
来源：[`packages/host/directory-picker-browse/src/index.ts:181`](../packages/host/directory-picker-browse/src/index.ts)
<a id="deepseek-aidsh-host-frontend-static"></a>
## `@deepseek-ai/dsh-host-frontend-static`
需要：`webServer`
@@ -722,6 +787,8 @@ export interface Config {
来源：[`packages/host/frontend-static/src/index.ts:28`](../packages/host/frontend-static/src/index.ts)
<a id="deepseek-aidsh-host-webserver"></a>
## `@deepseek-ai/dsh-host-webserver`
```ts config-catalog
@@ -736,6 +803,8 @@ export interface Config {
来源：[`packages/host/webserver/src/index.ts:45`](../packages/host/webserver/src/index.ts)
<a id="deepseek-aidsh-invariants"></a>
## `@deepseek-ai/dsh-invariants`
```ts config-catalog
@@ -752,6 +821,8 @@ export interface Config {
来源：[`packages/runtime-diagnostics/invariants/src/index.ts:15`](../packages/runtime-diagnostics/invariants/src/index.ts)
<a id="deepseek-aidsh-jobs-local"></a>
## `@deepseek-ai/dsh-jobs-local`
```ts config-catalog
@@ -767,6 +838,8 @@ export interface Config {
来源：[`packages/jobs/jobs-local/src/index.ts:31`](../packages/jobs/jobs-local/src/index.ts)
<a id="deepseek-aidsh-llm-deepseek"></a>
## `@deepseek-ai/dsh-llm-deepseek`
需要：`llm`
@@ -788,7 +861,7 @@ export interface Config {
/** Deployment thinking policy; `disabled` limits every conversation request to `off`. */
thinking?: 'enabled' | 'disabled'
/** Default thinking effort (default `high`); `off` disables thinking per request. */
reasoningEffort?: 'off' | 'high' | 'max'
reasoningEffort?: 'off' | 'low' | 'high' | 'max'
/** Default per-request output cap (default 256,000); a model's own cap and explicit request values win. */
maxTokens?: number
/** Positive context capacity used when the selected model has no exact value (default 1,000,000). */
@@ -820,6 +893,8 @@ export interface DeepSeekCatalogModel {
来源：[`packages/llm/llm-deepseek/src/index.ts:62`](../packages/llm/llm-deepseek/src/index.ts)
<a id="deepseek-aidsh-llm-pi-ai"></a>
## `@deepseek-ai/dsh-llm-pi-ai`
需要：`llm`
@@ -1008,6 +1083,8 @@ type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template'
来源：[`packages/llm/llm-pi-ai/src/config.ts:172`](../packages/llm/llm-pi-ai/src/config.ts)
<a id="deepseek-aidsh-llm-replay"></a>
## `@deepseek-ai/dsh-llm-replay`
需要：`llm`
@@ -1074,6 +1151,8 @@ export interface ReplayModelConfig {
来源：[`packages/test-support/llm-replay/src/index.ts:776`](../packages/test-support/llm-replay/src/index.ts)
<a id="deepseek-aidsh-llm-retry"></a>
## `@deepseek-ai/dsh-llm-retry`
需要：`agents`
@@ -1085,6 +1164,8 @@ export type Config = Readonly<Record<string, never>>
来源：[`packages/llm/llm-retry/src/index.ts:24`](../packages/llm/llm-retry/src/index.ts)
<a id="deepseek-aidsh-lsp-stdio"></a>
## `@deepseek-ai/dsh-lsp-stdio`
需要：`fs` · `lsp` · `subprocess`
@@ -1125,6 +1206,8 @@ export interface LspLocalServerConfig {
来源：[`packages/lsp/lsp-stdio/src/index.ts:82`](../packages/lsp/lsp-stdio/src/index.ts)
<a id="deepseek-aidsh-mcp-client"></a>
## `@deepseek-ai/dsh-mcp-client`
需要：`tools`
@@ -1196,6 +1279,8 @@ export interface ReconnectConfig {
来源：[`packages/mcp/mcp-client/src/index.ts:98`](../packages/mcp/mcp-client/src/index.ts)
<a id="deepseek-aidsh-message-feedback"></a>
## `@deepseek-ai/dsh-message-feedback`
需要：`storageDomain` · `sessionPersistence` · `sessions`
@@ -1210,6 +1295,8 @@ export interface Config {
来源：[`packages/feedback/message-feedback/src/index.ts:49`](../packages/feedback/message-feedback/src/index.ts)
<a id="deepseek-aidsh-permission-presets"></a>
## `@deepseek-ai/dsh-permission-presets`
需要：`bash` · `approval` · `sessions`
@@ -1247,6 +1334,8 @@ export interface PresetSpec {
来源：[`packages/interaction/permission-presets/src/index.ts:140`](../packages/interaction/permission-presets/src/index.ts)
<a id="deepseek-aidsh-persona"></a>
## `@deepseek-ai/dsh-persona`
需要：`systemPrompt`
@@ -1262,11 +1351,15 @@ export interface Config {
text: string
/** Make this persona the complete system prompt, suppressing every other section. */
complete?: boolean
/** Suppress dynamic runtime-context snapshots for this persona's agent scope. */
includeRuntimeContext?: boolean
}
```
来源：[`packages/preset/persona/src/index.ts:34`](../packages/preset/persona/src/index.ts)
<a id="deepseek-aidsh-plan-mode"></a>
## `@deepseek-ai/dsh-plan-mode`
需要：`tools` · `systemPrompt`
@@ -1281,6 +1374,8 @@ export interface PlanModeConfig {
来源：[`packages/plan/plan-mode/src/index.ts:70`](../packages/plan/plan-mode/src/index.ts)
<a id="deepseek-aidsh-pwsh-local"></a>
## `@deepseek-ai/dsh-pwsh-local`
需要：`subprocess`
@@ -1312,6 +1407,8 @@ export interface Config {
来源：[`packages/shell/pwsh-local/src/index.ts:58`](../packages/shell/pwsh-local/src/index.ts)
<a id="deepseek-aidsh-pwsh-sandbox"></a>
## `@deepseek-ai/dsh-pwsh-sandbox`
需要：`subprocess` · `sandbox` · `sandboxPolicy`
@@ -1332,6 +1429,8 @@ export type Config = LocalConfig
来源：[`packages/shell/pwsh-sandbox/src/index.ts:40`](../packages/shell/pwsh-sandbox/src/index.ts)
<a id="deepseek-aidsh-repeat-tool-reminder"></a>
## `@deepseek-ai/dsh-repeat-tool-reminder`
```ts config-catalog
@@ -1364,6 +1463,8 @@ export interface Config {
来源：[`packages/guard/repeat-tool-reminder/src/index.ts:28`](../packages/guard/repeat-tool-reminder/src/index.ts)
<a id="deepseek-aidsh-sandbox-local"></a>
## `@deepseek-ai/dsh-sandbox-local`
```ts config-catalog
@@ -1394,6 +1495,8 @@ export interface Config {
来源：[`packages/sandbox/sandbox-local/src/index.ts:44`](../packages/sandbox/sandbox-local/src/index.ts)
<a id="deepseek-aidsh-sandbox-policy"></a>
## `@deepseek-ai/dsh-sandbox-policy`
```ts config-catalog
@@ -1419,6 +1522,8 @@ export interface Config {
来源：[`packages/sandbox/sandbox-policy/src/index.ts:67`](../packages/sandbox/sandbox-policy/src/index.ts)
<a id="deepseek-aidsh-sdk-jsonrpc-server"></a>
## `@deepseek-ai/dsh-sdk-jsonrpc-server`
需要：`agents`
@@ -1441,6 +1546,8 @@ export interface JsonRpcConfig {
来源：[`packages/sdk/server/src/index.ts:29`](../packages/sdk/server/src/index.ts)
<a id="deepseek-aidsh-session-persistence-jsonl"></a>
## `@deepseek-ai/dsh-session-persistence-jsonl`
需要：`sessions`
@@ -1478,6 +1585,8 @@ export type JsonlCompression = 'zstd' | 'none'
来源：[`packages/session/session-persistence-jsonl/src/index.ts:60`](../packages/session/session-persistence-jsonl/src/index.ts)
<a id="deepseek-aidsh-session-persistence-sqlite"></a>
## `@deepseek-ai/dsh-session-persistence-sqlite`
需要：`sessions`
@@ -1521,6 +1630,8 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
来源：[`packages/session/session-persistence-sqlite/src/index.ts:70`](../packages/session/session-persistence-sqlite/src/index.ts)
<a id="deepseek-aidsh-session-projection-cache"></a>
## `@deepseek-ai/dsh-session-projection-cache`
需要：`storageDomain` · `sessionProjections` · `sessionPersistence` · `sessions`
@@ -1542,6 +1653,8 @@ export interface Config {
来源：[`packages/session/session-projection-cache/src/index.ts:42`](../packages/session/session-projection-cache/src/index.ts)
<a id="deepseek-aidsh-session-query-sqlite"></a>
## `@deepseek-ai/dsh-session-query-sqlite`
需要：`sessions`
@@ -1555,7 +1668,13 @@ export interface Config extends SessionQueryConfig {
* POSIX filesystems; existing modes are preserved.
*/
path: string
/** Open the SQLite module and handle at service activation or the first search. Defaults to `startup`. */
/**
* Open the SQLite module and handle at service activation or the first
* search, or `never` to disable full-text search: the inherited exact
* reads, filters, and traces stay available, while `searchSessions` and
* `searchEvents` fail with `SESSION_QUERY_SEARCH_DISABLED` and SQLite is
* never imported or opened. Defaults to `startup`.
*/
openAt?: OpenAt
/** SQLite journal mode. Defaults to `wal`. */
journalMode?: JournalMode
@@ -1569,8 +1688,8 @@ export interface Config extends SessionQueryConfig {
persistedInspectConcurrency?: number
}
/** SQLite module/handle opening phase. */
export type OpenAt = 'startup' | 'first-search'
/** SQLite module/handle opening phase; `never` disables full-text search entirely. */
export type OpenAt = 'startup' | 'first-search' | 'never'
/** Supported SQLite journal modes. */
export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
@@ -1580,6 +1699,8 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
来源：[`packages/session-query/session-query-sqlite/src/index.ts:89`](../packages/session-query/session-query-sqlite/src/index.ts)
<a id="deepseek-aidsh-session-reference"></a>
## `@deepseek-ai/dsh-session-reference`
需要：`sessionQuery`
@@ -1598,6 +1719,8 @@ export interface Config {
来源：[`packages/context/session-reference/src/config.ts:11`](../packages/context/session-reference/src/config.ts)
<a id="deepseek-aidsh-session-telemetry-otel"></a>
## `@deepseek-ai/dsh-session-telemetry-otel`
需要：`sessions`
@@ -1642,6 +1765,8 @@ export enum SessionTelemetryMode {
来源：[`packages/session/session-telemetry-otel/src/index.ts:91`](../packages/session/session-telemetry-otel/src/index.ts)
<a id="deepseek-aidsh-session-title"></a>
## `@deepseek-ai/dsh-session-title`
需要：`sessions`
@@ -1660,6 +1785,8 @@ export interface Config {
来源：[`packages/session/session-title/src/index.ts:79`](../packages/session/session-title/src/index.ts)
<a id="deepseek-aidsh-session-title-all-prompts-llm"></a>
## `@deepseek-ai/dsh-session-title-all-prompts-llm`
需要：`sessionTitle` · `llm` · `sessions`
@@ -1673,6 +1800,8 @@ export type Config = SessionTitleLlmConfig
来源：[`packages/session/session-title-all-prompts-llm/src/index.ts:15`](../packages/session/session-title-all-prompts-llm/src/index.ts)
<a id="deepseek-aidsh-session-title-first-prompt-llm"></a>
## `@deepseek-ai/dsh-session-title-first-prompt-llm`
需要：`sessionTitle` · `llm` · `sessions`
@@ -1686,6 +1815,8 @@ export type Config = SessionTitleLlmConfig
来源：[`packages/session/session-title-first-prompt-llm/src/index.ts:15`](../packages/session/session-title-first-prompt-llm/src/index.ts)
<a id="deepseek-aidsh-settings-file"></a>
## `@deepseek-ai/dsh-settings-file`
```ts config-catalog
@@ -1704,6 +1835,8 @@ export interface Config {
来源：[`packages/settings/settings-file/src/index.ts:21`](../packages/settings/settings-file/src/index.ts)
<a id="deepseek-aidsh-shell-env"></a>
## `@deepseek-ai/dsh-shell-env`
```ts config-catalog
@@ -1716,6 +1849,8 @@ export interface Config {
来源：[`packages/shell/shell-env/src/index.ts:29`](../packages/shell/shell-env/src/index.ts)
<a id="deepseek-aidsh-skill"></a>
## `@deepseek-ai/dsh-skill`
```ts config-catalog
@@ -1728,6 +1863,8 @@ export interface Config {
来源：[`packages/skill/skill/src/index.ts:279`](../packages/skill/skill/src/index.ts)
<a id="deepseek-aidsh-skill-filesystem"></a>
## `@deepseek-ai/dsh-skill-filesystem`
需要：`skills`
@@ -1764,6 +1901,8 @@ export interface Config {
来源：[`packages/skill/skill-filesystem/src/index.ts:49`](../packages/skill/skill-filesystem/src/index.ts)
<a id="deepseek-aidsh-spill-local"></a>
## `@deepseek-ai/dsh-spill-local`
```ts config-catalog
@@ -1780,6 +1919,8 @@ export interface Config {
来源：[`packages/spill/spill-local/src/index.ts:22`](../packages/spill/spill-local/src/index.ts)
<a id="deepseek-aidsh-spill-policy"></a>
## `@deepseek-ai/dsh-spill-policy`
需要：`tools`
@@ -1798,6 +1939,8 @@ export interface Config {
来源：[`packages/spill/spill-policy/src/index.ts:60`](../packages/spill/spill-policy/src/index.ts)
<a id="deepseek-aidsh-storage-domain"></a>
## `@deepseek-ai/dsh-storage-domain`
需要：`storage`
@@ -1819,6 +1962,8 @@ export interface Config {
来源：[`packages/storage/storage-domain/src/index.ts:52`](../packages/storage/storage-domain/src/index.ts)
<a id="deepseek-aidsh-storage-json"></a>
## `@deepseek-ai/dsh-storage-json`
需要：`storage`
@@ -1838,6 +1983,8 @@ export interface Config {
来源：[`packages/storage/storage-json/src/index.ts:27`](../packages/storage/storage-json/src/index.ts)
<a id="deepseek-aidsh-storage-sqlite"></a>
## `@deepseek-ai/dsh-storage-sqlite`
需要：`storage`
@@ -1876,6 +2023,8 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
来源：[`packages/storage/storage-sqlite/src/index.ts:24`](../packages/storage/storage-sqlite/src/index.ts)
<a id="deepseek-aidsh-subagent-acp"></a>
## `@deepseek-ai/dsh-subagent-acp`
需要：`subagents` · `subprocess`
@@ -1927,6 +2076,8 @@ export type PermissionPolicy = 'allow' | 'reject'
来源：[`packages/subagent/subagent-acp/src/index.ts:27`](../packages/subagent/subagent-acp/src/index.ts)
<a id="deepseek-aidsh-subagent-claude-code"></a>
## `@deepseek-ai/dsh-subagent-claude-code`
需要：`subagents` · `subprocess`
@@ -1946,6 +2097,8 @@ export interface Config {
来源：[`packages/subagent/subagent-claude-code/src/index.ts:32`](../packages/subagent/subagent-claude-code/src/index.ts)
<a id="deepseek-aidsh-subagent-codex"></a>
## `@deepseek-ai/dsh-subagent-codex`
需要：`subagents` · `subprocess`
@@ -1965,6 +2118,8 @@ export interface Config {
来源：[`packages/subagent/subagent-codex/src/index.ts:30`](../packages/subagent/subagent-codex/src/index.ts)
<a id="deepseek-aidsh-subagent-dsh-sdk"></a>
## `@deepseek-ai/dsh-subagent-dsh-sdk`
需要：`subagents`
@@ -2016,6 +2171,8 @@ export interface Config {
来源：[`packages/subagent/subagent-dsh-sdk/src/index.ts:29`](../packages/subagent/subagent-dsh-sdk/src/index.ts)
<a id="deepseek-aidsh-subagent-fork-in-process"></a>
## `@deepseek-ai/dsh-subagent-fork-in-process`
需要：`subagents`
@@ -2030,6 +2187,8 @@ export interface Config {
来源：[`packages/subagent/subagent-fork-in-process/src/index.ts:31`](../packages/subagent/subagent-fork-in-process/src/index.ts)
<a id="deepseek-aidsh-subagent-spawn-in-process"></a>
## `@deepseek-ai/dsh-subagent-spawn-in-process`
需要：`subagents`
@@ -2044,6 +2203,8 @@ export interface Config {
来源：[`packages/subagent/subagent-spawn-in-process/src/index.ts:25`](../packages/subagent/subagent-spawn-in-process/src/index.ts)
<a id="deepseek-aidsh-subprocess-e2b"></a>
## `@deepseek-ai/dsh-subprocess-e2b`
需要：`e2b`
@@ -2058,6 +2219,8 @@ export interface Config {
来源：[`packages/e2b/subprocess-e2b/src/index.ts:25`](../packages/e2b/subprocess-e2b/src/index.ts)
<a id="deepseek-aidsh-system-prompt"></a>
## `@deepseek-ai/dsh-system-prompt`
```ts config-catalog
@@ -2065,6 +2228,8 @@ export interface Config {
export interface Config {
/** Include the fixed DeepSeek Harness identity before the deployment persona (default true). */
includeHarnessIdentity?: boolean
/** Include dynamic runtime-context snapshots in model history (default true). */
includeRuntimeContext?: boolean
/**
* Deployment-wide order-0 persona template. A scoped section named
* `deployment:persona` shadows it; `{{variable}}` references are strict.
@@ -2081,6 +2246,8 @@ export interface Config {
来源：[`packages/core/system-prompt/src/index.ts:186`](../packages/core/system-prompt/src/index.ts)
<a id="deepseek-aidsh-terminal-bash"></a>
## `@deepseek-ai/dsh-terminal-bash`
需要：`pty` · `sandboxPolicy` · `subprocess`
@@ -2124,6 +2291,8 @@ export interface Config {
来源：[`packages/terminal/terminal-bash/src/config.ts:6`](../packages/terminal/terminal-bash/src/config.ts)
<a id="deepseek-aidsh-time-context"></a>
## `@deepseek-ai/dsh-time-context`
需要：`agents`
@@ -2140,6 +2309,8 @@ export interface Config {
来源：[`packages/context/time-context/src/index.ts:27`](../packages/context/time-context/src/index.ts)
<a id="deepseek-aidsh-tmux-context"></a>
## `@deepseek-ai/dsh-tmux-context`
需要：`agents`
@@ -2154,6 +2325,8 @@ export interface Config {
来源：[`packages/context/tmux-context/src/index.ts:34`](../packages/context/tmux-context/src/index.ts)
<a id="deepseek-aidsh-token-meter"></a>
## `@deepseek-ai/dsh-token-meter`
```ts config-catalog
@@ -2163,6 +2336,8 @@ export type TokenMeterConfig = Record<string, never>
来源：[`packages/llm/token-meter/src/types.ts:12`](../packages/llm/token-meter/src/types.ts)
<a id="deepseek-aidsh-tool-bash"></a>
## `@deepseek-ai/dsh-tool-bash`
需要：`tools` · `bash` · `systemPrompt` · `bashEnv`
@@ -2177,6 +2352,8 @@ export interface Config {
来源：[`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts)
<a id="deepseek-aidsh-tool-bash-persistent"></a>
## `@deepseek-ai/dsh-tool-bash-persistent`
需要：`tools` · `pty`
@@ -2195,7 +2372,9 @@ export interface Config {
}
```
来源：[`packages/shell/tool-bash-persistent/src/index.ts:405`](../packages/shell/tool-bash-persistent/src/index.ts)
来源：[`packages/shell/tool-bash-persistent/src/index.ts:400`](../packages/shell/tool-bash-persistent/src/index.ts)
<a id="deepseek-aidsh-tool-fs"></a>
## `@deepseek-ai/dsh-tool-fs`
@@ -2217,6 +2396,8 @@ export interface Config {
来源：[`packages/fs/tool-fs/src/index.ts:25`](../packages/fs/tool-fs/src/index.ts)
<a id="deepseek-aidsh-tool-fs-search"></a>
## `@deepseek-ai/dsh-tool-fs-search`
需要：`tools` · `systemPrompt` · `subprocess`
@@ -2250,6 +2431,8 @@ export interface Config {
来源：[`packages/fs/tool-fs-search/src/index.ts:73`](../packages/fs/tool-fs-search/src/index.ts)
<a id="deepseek-aidsh-tool-goal"></a>
## `@deepseek-ai/dsh-tool-goal`
需要：`agents` · `goals` · `tools` · `systemPrompt`
@@ -2264,6 +2447,8 @@ export interface Config {
来源：[`packages/goal/tool-goal/src/index.ts:26`](../packages/goal/tool-goal/src/index.ts)
<a id="deepseek-aidsh-tool-jobs"></a>
## `@deepseek-ai/dsh-tool-jobs`
需要：`tools` · `tasks` · `systemPrompt`
@@ -2296,6 +2481,8 @@ export type CompletionDelivery = 'quiet' | 'wakeup'
来源：[`packages/jobs/tool-jobs/src/index.ts:32`](../packages/jobs/tool-jobs/src/index.ts)
<a id="deepseek-aidsh-tool-lsp"></a>
## `@deepseek-ai/dsh-tool-lsp`
需要：`tools` · `lsp` · `systemPrompt`
@@ -2314,6 +2501,8 @@ export interface Config {
来源：[`packages/lsp/tool-lsp/src/index.ts:58`](../packages/lsp/tool-lsp/src/index.ts)
<a id="deepseek-aidsh-tool-pwsh"></a>
## `@deepseek-ai/dsh-tool-pwsh`
需要：`tools` · `bash` · `systemPrompt` · `bashEnv`
@@ -2328,6 +2517,8 @@ export interface Config {
来源：[`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts)
<a id="deepseek-aidsh-tool-ralph"></a>
## `@deepseek-ai/dsh-tool-ralph`
需要：`tools` · `workflows` · `subagents` · `systemPrompt`
@@ -2348,6 +2539,8 @@ export interface Config {
来源：[`packages/workflow/tool-ralph/src/index.ts:23`](../packages/workflow/tool-ralph/src/index.ts)
<a id="deepseek-aidsh-tool-session-query"></a>
## `@deepseek-ai/dsh-tool-session-query`
需要：`tools` · `systemPrompt` · `sessionQuery`
@@ -2364,6 +2557,8 @@ export interface Config {
来源：[`packages/session-query/tool-session-query/src/index.ts:29`](../packages/session-query/tool-session-query/src/index.ts)
<a id="deepseek-aidsh-tool-skill"></a>
## `@deepseek-ai/dsh-tool-skill`
需要：`agents` · `tools` · `skills`
@@ -2378,6 +2573,8 @@ export interface Config {
来源：[`packages/skill/tool-skill/src/index.ts:61`](../packages/skill/tool-skill/src/index.ts)
<a id="deepseek-aidsh-tool-str-replace-editor"></a>
## `@deepseek-ai/dsh-tool-str-replace-editor`
需要：`tools` · `fs`
@@ -2394,6 +2591,8 @@ export interface Config {
来源：[`packages/fs/tool-str-replace-editor/src/index.ts:497`](../packages/fs/tool-str-replace-editor/src/index.ts)
<a id="deepseek-aidsh-tool-subagent"></a>
## `@deepseek-ai/dsh-tool-subagent`
需要：`tools` · `subagents` · `systemPrompt`
@@ -2457,6 +2656,8 @@ export interface Config {
来源：[`packages/subagent/tool-subagent/src/index.ts:29`](../packages/subagent/tool-subagent/src/index.ts)
<a id="deepseek-aidsh-tool-subagent-report"></a>
## `@deepseek-ai/dsh-tool-subagent-report`
需要：`subagents` · `tools` · `systemPrompt`
@@ -2477,6 +2678,8 @@ export interface Config {
来源：[`packages/subagent/tool-subagent-report/src/index.ts:27`](../packages/subagent/tool-subagent-report/src/index.ts)
<a id="deepseek-aidsh-tool-terminal"></a>
## `@deepseek-ai/dsh-tool-terminal`
需要：`pty` · `tools` · `systemPrompt`
@@ -2493,6 +2696,8 @@ export interface Config {
来源：[`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts)
<a id="deepseek-aidsh-tool-todo"></a>
## `@deepseek-ai/dsh-tool-todo`
需要：`tools`
@@ -2513,6 +2718,8 @@ export interface Config {
来源：[`packages/todo/tool-todo/src/index.ts:29`](../packages/todo/tool-todo/src/index.ts)
<a id="deepseek-aidsh-tool-web"></a>
## `@deepseek-ai/dsh-tool-web`
需要：`tools` · `web` · `systemPrompt`
@@ -2537,6 +2744,8 @@ export interface Config {
来源：[`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts)
<a id="deepseek-aidsh-tool-workflow"></a>
## `@deepseek-ai/dsh-tool-workflow`
需要：`tools` · `workflows` · `systemPrompt`
@@ -2553,6 +2762,8 @@ export interface Config {
来源：[`packages/workflow/tool-workflow/src/index.ts:33`](../packages/workflow/tool-workflow/src/index.ts)
<a id="deepseek-aidsh-tools"></a>
## `@deepseek-ai/dsh-tools`
需要：`systemPrompt`
@@ -2587,6 +2798,8 @@ export type ToolPresentationMode = 'native' | 'code' | 'both'
来源：[`packages/core/tools/src/index.ts:654`](../packages/core/tools/src/index.ts)
<a id="deepseek-aidsh-typert-loader"></a>
## `@deepseek-ai/dsh-typert-loader`
需要：`typert` · `loader`
@@ -2601,6 +2814,8 @@ export interface Config {
来源：[`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts)
<a id="deepseek-aidsh-user-approval"></a>
## `@deepseek-ai/dsh-user-approval`
```ts config-catalog
@@ -2630,6 +2845,8 @@ export type ApprovalPolicy = 'ask' | 'never'
来源：[`packages/interaction/user-approval/src/index.ts:177`](../packages/interaction/user-approval/src/index.ts)
<a id="deepseek-aidsh-web"></a>
## `@deepseek-ai/dsh-web`
```ts config-catalog
@@ -2649,6 +2866,8 @@ export interface WebRuntimeConfig {
来源：[`packages/web/web/src/index.ts:55`](../packages/web/web/src/index.ts)
<a id="deepseek-aidsh-web-app"></a>
## `@deepseek-ai/dsh-web-app`
需要：`webServer`
@@ -2672,6 +2891,8 @@ export interface Config {
来源：[`packages/bundle/web-app/src/index.ts:38`](../packages/bundle/web-app/src/index.ts)
<a id="deepseek-aidsh-web-fetch-http"></a>
## `@deepseek-ai/dsh-web-fetch-http`
需要：`web`
@@ -2696,6 +2917,8 @@ export interface Config {
来源：[`packages/web/web-fetch-http/src/index.ts:34`](../packages/web/web-fetch-http/src/index.ts)
<a id="deepseek-aidsh-web-search-deepseek"></a>
## `@deepseek-ai/dsh-web-search-deepseek`
需要：`web`
@@ -2722,6 +2945,8 @@ export interface Config {
来源：[`packages/web/web-search-deepseek/src/index.ts:46`](../packages/web/web-search-deepseek/src/index.ts)
<a id="deepseek-aidsh-web-search-exa"></a>
## `@deepseek-ai/dsh-web-search-exa`
需要：`web`
@@ -2744,6 +2969,8 @@ export interface Config {
来源：[`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
<a id="deepseek-aidsh-web-search-perplexity"></a>
## `@deepseek-ai/dsh-web-search-perplexity`
需要：`web`
@@ -2766,6 +2993,8 @@ export interface Config {
来源：[`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
<a id="deepseek-aidsh-workflow-worker-thread"></a>
## `@deepseek-ai/dsh-workflow-worker-thread`
需要：`subagents`

4
docs/cookbook/adding-a-package.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 docs/cookbook/adding-a-package.md
adding-a-package.md: 26a380fd3ec6b8b0447ad27d7ef79d3e58433cbe
adding-a-package.zh.md: 49a9fba820698d0c82c9700c31a28039fbc030c8
adding-a-package.md: a78695735957395c5c900c3294b6778904557f85
adding-a-package.zh.md: b7a749220fdc1581875851e2e4a7189ba7642b2d

2
docs/cookbook/adding-a-package.md
View File

@@ -40,7 +40,7 @@ Covered automatically by globs or package-manifest discovery — no edits needed
## 3. Decide the package topology
For a swappable capability, separate Service Definition / Service provider / Consumer roles into packages when they evolve independently (see docs/architecture.md § "Capability seams" — the shell trio is the template). A single-purpose plugin stays one package.
For a swappable capability, separate Service Definition / Service Provider / Consumer roles into packages when they evolve independently (see docs/architecture.md § "Capability seams" — the shell trio is the template). A single-purpose plugin stays one package.
### Name the role that exists

2
docs/cookbook/adding-a-package.zh.md
View File

@@ -40,7 +40,7 @@ package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-c
## 3. 确定包拓扑
对于可替换的能力，当 Service Definition／Service provider／Consumer 角色需要独立演进时，将它们拆分到不同包中（见 docs/architecture.md § "Capability seams"——shell 三组件是模板）。单一用途的插件保持为一个包。
对于可替换的能力，当 Service Definition／Service Provider／Consumer 角色需要独立演进时，将它们拆分到不同包中（见 docs/architecture.md § "Capability seams"——shell 三组件是模板）。单一用途的插件保持为一个包。
### 使用符合实际的角色名称

6
docs/cookbook/adding-a-settings-card.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/cookbook/adding-a-settings-card.md
adding-a-settings-card.md: 56ec3be578bbc489bbb979a50bcaed063a35ace5
adding-a-settings-card.zh.md: 4643303bfd76ba77676b7e508424f46082627b62

100
docs/cookbook/adding-a-settings-card.md Normal file
View File

@@ -0,0 +1,100 @@
# Cookbook: adding a settings card
English | [中文](adding-a-settings-card.zh.md)
How a plugin puts its own configuration on the web settings page. Nothing in this path needs a change inside this repository: the Host serves every registered settings namespace, and the **Plugins** section keys its cards on the namespace they edit, so a plugin that registers both halves is paired up automatically.
The two halves live in one package — the Host half under `src/`, the browser half under `src/client/`, exported as `./client` and declared with `dsh.client`. [`packages/client/ui-theme`](../../packages/client/ui-theme) is a worked example of that packaging; the cards this section ships live in [`packages/client/ui-settings-plugins`](../../packages/client/ui-settings-plugins).
## 1. Register the namespace (Host half)
The namespace is the join key, so pick it once and spell it in both halves. A consumer that already has a `cordis.yml` entry should register through `installSettingsSection`, which layers the entry under the user document and keeps working when no settings provider is mounted:
```ts
import type { Context } from '@deepseek-ai/cordis'
import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
import z from '@deepseek-ai/schemastery'
declare function assertReachable(endpoint: string | undefined): void
declare function rebuildFromSettings(config: Config): void
export const MY_PLUGIN_NS = settingsNamespace('my-plugin')
export interface Config {
endpoint?: string
retries?: number
}
export const Config: z<Config> = z.object({
endpoint: z.string(),
retries: z.number().step(1).min(0).default(3),
})
export function apply(ctx: Context, config: Config) {
let source = () => config
installSettingsSection(ctx, MY_PLUGIN_NS, Config, config, {
// Constraints the schema cannot express refuse the write, not the next use.
validate: value => void assertReachable(value.endpoint),
setSource: (current) => { source = current },
onChange: () => { rebuildFromSettings(source()) },
})
}
```
`role('secret')` on a field keeps its value off every response; the card writes such a field into an `update`/`mutate` payload, or addresses a credential reference through the `credentials` domain instead. `applies: 'restart'` tells a configuration surface the owner acts on a change only at the next start.
## 2. Register the card (browser half)
The card registers into `settings.plugin.item` under its namespace and owns everything inside it — chrome, controls, and copy. It reads and writes through `ctx.settingsScope`, which fences each write with the revision it read:
```ts ignore-check
import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
// Type-only: the keyed slot's declaration. Cross-plugin collaboration goes
// through cordis services; a value import fails the client bundle-purity gate.
import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope']
export function apply(ctx: ClientContext): void {
const card = new MyPluginCardController(ctx.settingsScope.bind({ namespace: 'my-plugin' }))
ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
name: 'settings.plugin.item',
key: 'my-plugin',
locale: 'settings.myPlugin',
inject: () => card.inject(),
}, MyPluginCard),
)
}
```
The scope snapshot carries what a form needs: the resolved `value`, the composition `base`, and the raw `user` layer, whose key **presence** — not its value — is what marks a field overridden. `scope.set(field, value)` stores one field and `scope.unset(field)` clears it back to the composition layer.
## 3. What the tab does with it
The **Plugin configuration** tab reads which namespaces the Host serves and dispatches one slot key per namespace. A card is rendered when the Host serves its key and skipped when it does not, so a deployment that never composed the Host half shows no trace of the card. A served namespace no card claims renders nothing — that is how the namespaces owned by other pages (`ui-theme`, `permission`, `llm-*`) stay off this tab.
Cards appear in the order they registered into the slot; a keyed entry declares no `order` of its own.
## Packaging
The browser half is served to the page by the [client module system](../../packages/client/modules), which scans the enabled Loader entries for packages declaring `dsh.client` and serves each one's built `./client` export. So the plugin appears on the page as soon as a `cordis.yml` mounts it — no rebuild of the web application.
```jsonc
{
"exports": {
".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" },
"./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" }
},
"dsh": { "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-ui-settings-plugins"] } }
}
```
The bundle must be the loader's lazy-CJS factory artifact. Inside this repository `tsdown.config.ts` is three lines over the shared preset:
```ts ignore-check
import { clientBundle } from '../tsdown.client.ts'
export default clientBundle('@deepseek-ai/dsh-client-my-plugin', ['lib/types/index.js', 'lib/types/invariant.js'])
```
That preset is not published today, so a package outside this repository has to reproduce the same output format itself. The bundle-purity gate also rejects value imports across plugins, so a card cannot import this section's card chrome or its staged-form model — it renders its own, and owns its own staging and revision fencing. Both limits are recorded under [the section's known limitations](../../packages/client/ui-settings-plugins/README.md#known-limitations-and-deferred-work).

100
docs/cookbook/adding-a-settings-card.zh.md Normal file
View File

@@ -0,0 +1,100 @@
# Cookbook: 新增设置卡片
[English](adding-a-settings-card.md) | 中文
插件如何把自己的配置放上 Web 设置页。这条路径上没有任何一步需要改动本仓库：Host 服务每一个已注册的 settings 命名空间，而**插件配置**分区以卡片所编辑的命名空间为键，因此同时注册了两个半侧的插件会被自动配对。
两个半侧住在同一个包里——Host 半侧在 `src/`，浏览器半侧在 `src/client/`，以 `./client` 导出并用 `dsh.client` 声明。[`packages/client/ui-theme`](../../packages/client/ui-theme) 是这种打包方式的现成例子；本分区自带的卡片在 [`packages/client/ui-settings-plugins`](../../packages/client/ui-settings-plugins)。
## 1. 注册命名空间（Host 半侧）
命名空间就是配对用的键，所以只挑一次，并在两个半侧都写出它。已经有 `cordis.yml` entry 的消费方应通过 `installSettingsSection` 注册——它把 entry 层叠在用户文档之下，并在没有挂载 settings provider 时照常工作：
```ts
import type { Context } from '@deepseek-ai/cordis'
import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
import z from '@deepseek-ai/schemastery'
declare function assertReachable(endpoint: string | undefined): void
declare function rebuildFromSettings(config: Config): void
export const MY_PLUGIN_NS = settingsNamespace('my-plugin')
export interface Config {
endpoint?: string
retries?: number
}
export const Config: z<Config> = z.object({
endpoint: z.string(),
retries: z.number().step(1).min(0).default(3),
})
export function apply(ctx: Context, config: Config) {
let source = () => config
installSettingsSection(ctx, MY_PLUGIN_NS, Config, config, {
// Constraints the schema cannot express refuse the write, not the next use.
validate: value => void assertReachable(value.endpoint),
setSource: (current) => { source = current },
onChange: () => { rebuildFromSettings(source()) },
})
}
```
字段上的 `role('secret')` 让它的值不出现在任何响应里；卡片把这类字段写进 `update`/`mutate` 载荷，或改为经 `credentials` 领域寻址一个凭据引用。`applies: 'restart'` 告诉配置表层：拥有方要到下次启动才会对变更生效。
## 2. 注册卡片（浏览器半侧）
卡片以自己的命名空间为键注册进 `settings.plugin.item`，并拥有其中的一切——外观、控件与文案。它通过 `ctx.settingsScope` 读写，后者用读取时的 revision 为每次写入设栅：
```ts ignore-check
import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
// Type-only: the keyed slot's declaration. Cross-plugin collaboration goes
// through cordis services; a value import fails the client bundle-purity gate.
import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope']
export function apply(ctx: ClientContext): void {
const card = new MyPluginCardController(ctx.settingsScope.bind({ namespace: 'my-plugin' }))
ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
name: 'settings.plugin.item',
key: 'my-plugin',
locale: 'settings.myPlugin',
inject: () => card.inject(),
}, MyPluginCard),
)
}
```
scope 快照携带表单所需的一切：解析后的 `value`、组装层 `base`，以及原始的 `user` 层——字段是否被覆盖，取决于它在 `user` 层中是否**出现**，而非它的值。`scope.set(field, value)` 存一个字段，`scope.unset(field)` 把它清回组装层。
## 3. 标签页拿它做什么
**插件配置**标签页读取 Host 服务了哪些命名空间，并为每个命名空间派发一个 slot 键。当 Host 服务了某卡片的键时它被渲染，否则被跳过，因此从未组装过 Host 半侧的部署不会留下这张卡片的任何痕迹。被服务却无人认领的命名空间什么都不渲染——归其他页面所有的那些命名空间（`ui-theme`、`permission`、`llm-*`）正是这样留在本标签页之外的。
卡片按其注册进该 slot 的顺序出现；keyed entry 不声明自己的 `order`。
## 打包
浏览器半侧由[客户端模块系统](../../packages/client/modules)提供给页面：它扫描已启用的 Loader entries 中声明了 `dsh.client` 的包，并提供每个包构建出的 `./client` 导出。因此只要 `cordis.yml` 挂载了该插件，它就会出现在页面上——无需重新构建 Web 应用。
```jsonc
{
"exports": {
".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" },
"./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" }
},
"dsh": { "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-ui-settings-plugins"] } }
}
```
bundle 必须是 loader 的 lazy-CJS factory 产物。在本仓库内，`tsdown.config.ts` 就是基于共享预设的三行：
```ts ignore-check
import { clientBundle } from '../tsdown.client.ts'
export default clientBundle('@deepseek-ai/dsh-client-my-plugin', ['lib/types/index.js', 'lib/types/invariant.js'])
```
该预设目前未发布，因此本仓库之外的包得自行复刻同样的输出格式。bundle 纯净度门禁同时拒绝跨插件的值导入，所以卡片无法导入本分区的卡片外观或其暂存表单模型——它渲染自己的那一份，并自行拥有暂存与 revision 设栅。这两条限制都记在[本分区的已知限制](../../packages/client/ui-settings-plugins/README.md#known-limitations-and-deferred-work)里。

2
docs/cookbook/adding-a-tool.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 docs/cookbook/adding-a-tool.md
adding-a-tool.md: 37516521de4d00de964003fd6f877831774fdcd3
adding-a-tool.zh.md: 9455fa3b8d8b87632724ad4b035f184cb0c17993
adding-a-tool.zh.md: 27a90ce19653333a0a6afd989115e614a1c8f9f4

2
docs/cookbook/adding-a-tool.zh.md
View File

@@ -54,6 +54,8 @@ export function apply(ctx: Context) {
producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.jobs.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `job_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台任务运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
<a id="execution-policy-and-observation"></a>
## 执行策略与观测
尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许／拒绝／询问策略（见[权限门禁示例](extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝，后续监听器无法撤销；使用 `tools/execute` 为分发添加截止时间、重试或指标收集；使用 `tools/post-execute` 替换展示内容或返回值、阻止结果，或附加模型可见上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。替换内容不会阻止程序化访问 `value`；保密策略会屏蔽或替换该值。沙箱实现也可以在工具的执行器实现中运行；[`dsh-tools` README](../../packages/core/tools/README.md#extension-points) 定义每个扩展点的输入、顺序、返回值和失败行为。

2
docs/cookbook/extension-cookbook.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 docs/cookbook/extension-cookbook.md
extension-cookbook.md: 9618a3522c5566636fe3e49f7eca93d1e113d51a
extension-cookbook.zh.md: 7b82d7d1ff239cc2139ee424613e818669f3e2e8
extension-cookbook.zh.md: 540bc6867016d095ccae0fb0fdc79bc1b1c26290

2
docs/cookbook/extension-cookbook.zh.md
View File

@@ -8,6 +8,8 @@ harness 扩展的参考模式。代码片段省略了 import 和辅助实现，
工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果构造、`run_in_background` 模式）见 [adding-a-tool.md](adding-a-tool.md)——该指南是工具定义的真源。`ctx.tools.register()` 也直接接受原始 JSON Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是第一方工具使用的类型化辅助函数。
<a id="a-hook-plugin-permission-gate-example"></a>
## 钩子插件（以权限门禁为例）
这个权限门禁是钩子插件的一个示例。它从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用；沙箱、权限和 plan-mode 插件都可以使用该扩展点。钩子插件也可以拦截其他扩展点，本身并不等同于权限门禁。「原生钩子」是在拦截点上运行的普通 Cordis 插件，不需要外部协议。

65905
docs/cordis-paper.pdf
View File

File diff suppressed because one or more lines are too long

2
docs/cordis-primer.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 docs/cordis-primer.md
cordis-primer.md: 2a3afe180623d89b006dfa3e73aba5567c15bbe9
cordis-primer.zh.md: bdce14cf9f157959d6419f88c9c69570102b9c0c
cordis-primer.zh.md: d4d60f60717ffdc01499fdffadba2808557b285f

2
docs/cordis-primer.zh.md
View File

@@ -12,6 +12,8 @@ Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。本
- **类型化事件用于通信。** 服务通过 TypeScript 声明合并注册事件名，然后以 `emit`、`waterfall`（瀑布式事件）、`parallel` 或 `serial` 方式分发，分别对应监听者观察、包装、并行扇出或按序执行。
- **注册是可逆的副作用。** 提示词片段、工具 schema、适配器、提供方和监听器通过 `ctx.effect()` 或 `ctx.on()` 安装，reload 和 teardown 时会按预期撤销。
<a id="dispatch-modes"></a>
## 分发模式
每个事件具有以下分发模式之一，且只能通过对应方法分发。

4
docs/cordis-tutorial/03-services.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 docs/cordis-tutorial/03-services.md
03-services.md: 32007284be99ef46b4621089c9b3a80317e77189
03-services.zh.md: d82be29aa69686b8dc10cc6a45a658683c017cbd
03-services.md: ebfc400dbbc701a3c164c7d30c371dec879d7d73
03-services.zh.md: fcfd8be7f7fe654a4f4943cf591b5ab7bfc27fc6

2
docs/cordis-tutorial/03-services.md
View File

@@ -75,7 +75,7 @@ Swap the two lines in `cordis.yml` and rerun: same output. Try removing `./greet
`inject` is not a one-shot boot check. If a required service disappears while the app runs — its provider was unloaded or hot-replaced — every dependent plugin is unloaded too, and loads again when the service returns. Combined with effects ([chapter 2](02-lifecycle-and-effects.md)), this prevents a running consumer from retaining a reference to an unavailable service: its own registrations are unwound when the dependency disappears.
This is also why service replacement works in config: unload the `dsh-bash-local` entry, mount a different `bash` provider, and every plugin injecting `'bash'` cleanly restarts against the new implementation.
This is also why service replacement works in config: unload the `dsh-bash-local` entry, mount a different `shell` provider, and every plugin injecting `'shell'` cleanly restarts against the new implementation.
## Optional dependencies

2
docs/cordis-tutorial/03-services.zh.md
View File

@@ -75,7 +75,7 @@ Hello, world!
`inject` 并非一次性的启动检查。如果应用运行期间所需服务消失，例如提供方被卸载或热替换，每个依赖插件也会随之卸载，并在服务恢复后再次加载。结合 effect（[第 2 章](02-lifecycle-and-effects.md)），这能防止运行中的消费方保留对不可用服务的引用：依赖消失时，它自己的注册也会撤销。
这也是配置中可以替换服务的原因：卸载 Cordis 配置项 `dsh-bash-local`，挂载另一个 `bash` 提供方，所有注入 `'bash'` 的插件都会重新启动并使用新实现。
这也是配置中可以替换服务的原因：卸载 Cordis 配置项 `dsh-bash-local`，挂载另一个 `shell` 提供方，所有注入 `'shell'` 的插件都会重新启动并使用新实现。
## 可选依赖

4
docs/cordis-tutorial/06-composition-and-hmr.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 docs/cordis-tutorial/06-composition-and-hmr.md
06-composition-and-hmr.md: 87ea26014657ae8c8199e1ebb486556c827d96ca
06-composition-and-hmr.zh.md: 830f55de7c1be351fe701cb068197543602619a7
06-composition-and-hmr.md: 2b53aa28be99851e77a71de76337f2beb4003e8d
06-composition-and-hmr.zh.md: cd4afa1d5465a5442bfd6b771ebcd61c46fe2983

2
docs/cordis-tutorial/06-composition-and-hmr.md
View File

@@ -18,7 +18,7 @@ A config entry accepts metadata beyond `name` and `config`:
`id` gives the entry a stable identity so the loader can tell an edit to an existing entry apart from a removal plus an addition. `disabled: true` unmounts a plugin without deleting its entry — flip it back and the plugin (and everything PENDING on its services) loads again.
Groups nest a sub-list of entries that load and unload as one unit, and `isolate` gives a group its own instance of a service name — two groups can each see a differently-configured `bash` without affecting each other. The [Cordis primer](../cordis-primer.md) and the [service isolation example](../user/develop/framework/service.md#service-isolation) cover the details.
Groups nest a sub-list of entries that load and unload as one unit, and `isolate` gives a group its own instance of a service name — two groups can each see a differently configured `shell` provider without affecting each other. The [Cordis primer](../cordis-primer.md) and the [service isolation example](../user/develop/framework/service.md#service-isolation) cover the details.
## Hot module replacement

2
docs/cordis-tutorial/06-composition-and-hmr.zh.md
View File

@@ -18,7 +18,7 @@ Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
`id` 为 Cordis 配置项提供稳定标识，使 loader 能区分修改现有 Cordis 配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其 Cordis 配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。
组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `bash`，互不影响。[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `shell` 提供方，互不影响。[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
## 热模块替换

2
docs/cordis-tutorial/index.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 docs/cordis-tutorial/index.md
index.md: c51965e186ce8d78b577c1005c1c3e1831b91be1
index.zh.md: 8811930eba0f3e24ecbc47521e65582502257473
index.zh.md: 22e1918672a34219ca0cf5efaa43a8eb693e6996

2
docs/cordis-tutorial/index.zh.md
View File

@@ -10,6 +10,8 @@ Cordis 是 DeepSeek Harness 底层的插件框架：它是一个小型运行时
如果你要为 harness 本身编写插件——由 `cordis.yml` 加载、在 Web UI 中驱动，而不是下面这个启动器——请从[第一个 Harness 插件](../user/develop/basic/index.md)开始。
<a id="setup"></a>
## 准备工作
你需要克隆本仓库并安装依赖；[开发指南](../development.md#setup-tutorial)列出了前置条件。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。

4
docs/defensive-patterns.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 docs/defensive-patterns.md
defensive-patterns.md: b6e643cad6180ea35a363f2c4131b2c24f5f70af
defensive-patterns.zh.md: e1a6abdfd2138a51a13ceaf418bf6df1d0c65579
defensive-patterns.md: 9db582354628a13abd43c5bd052dbbfd6e52f79f
defensive-patterns.zh.md: 7bebbe3c1964f2b826afc523eaa4af7be180e36e

4
docs/defensive-patterns.md
View File

@@ -27,3 +27,7 @@ A user-supplied listener that throws must not reject the promise it runs inside
## Never hand untrusted output the ambient environment or predictable paths
Spawned commands get a scrubbed env (drop `*KEY*`/`*SECRET*`/`*TOKEN*`/`*PASSWORD*`) so harness credentials cannot leak into output, `env`, or spill files. Temp/spill files use a private (0700) dir, random names, and exclusive owner-only opens (`'wx'`, `0o600`) — predictable world-readable paths invite symlink races and disclosure.
## Unlink link-shaped paths
A path that may be a symlink or Windows junction is removed with `lstatSync().isSymbolicLink()` then `unlinkSync`: unlink deletes only the link and refuses a real directory, so it never follows the link into its target. Windows `rmSync(link)` throws `ERR_FS_EISDIR` on a junction; recursive deletion may descend through one into its target. Reserve recursive `rmSync` for known real directories.

6
docs/defensive-patterns.zh.md
View File

@@ -26,4 +26,8 @@
## 绝不将环境变量或可预测路径暴露给不可信输出
启动的命令应使用经过清理的环境变量，移除名称匹配 `*KEY*`、`*SECRET*`、`*TOKEN*` 或 `*PASSWORD*` 的项，防止 harness 凭证通过命令输出、`env` 或 spill 文件泄漏。临时文件和 spill 文件应放在权限为 0700 的私有目录中，使用随机文件名，并以独占且仅所有者可访问的方式打开（`'wx'`、`0o600`）；可预测且所有用户均可读的路径会引发符号链接竞态和信息泄露。
启动的命令应使用经过清理的环境变量，移除名称匹配 `*KEY*`、`*SECRET*`、`*TOKEN*` 或 `*PASSWORD*` 的项，防止 harness 凭证通过命令输出、`env` 或 spill 文件泄漏。临时文件和 spill 文件应放在权限为 0700 的私有目录中，使用随机文件名，并以独占且仅所有者可访问的方式打开（`'wx'`、`0o600`）；可预测且全局可读的路径会引发符号链接竞态和信息泄露。
## 用 unlink 删除链接形态的路径
可能是符号链接或 Windows junction 的路径，应先用 `lstatSync().isSymbolicLink()` 判断，再用 `unlinkSync` 删除：unlink 只删除链接本身并拒绝真实目录，因此绝不会跟随链接进入其目标。Windows 上对 junction 调用 `rmSync(link)` 会抛 `ERR_FS_EISDIR`；递归删除可能穿过 junction 进入其目标。真实目录才使用带 `recursive` 的 `rmSync`。

4
docs/glossary.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 docs/glossary.md
glossary.md: 1c8bbc86544092b1e8c752e53eed0a1217baa329
glossary.zh.md: 510853d3d6a6f579c8e4cd609d714fe891e9cf10
glossary.md: 9bff818d5a9f7688e8d2a2425b6e6a9555be3847
glossary.zh.md: 98bbbefb8bfd152324b23e9791eb938398c12602

2
docs/glossary.md
View File

@@ -6,7 +6,7 @@ Domain vocabulary for DeepSeek Harness uses one canonical term per concept. Term
## capability-seam
- **seam** — a *swappable capability* with three roles: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `ShellExecutor`, or a concrete registry such as `WebRuntime`, never a TypeScript `interface`), one or more **Service providers**, and one or more **Consumers** that inject the service. `packages/shell` is the canonical example: `dsh-shell` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), and `dsh-tool-bash` (Consumer). Roles normally occupy separate packages when they evolve independently, but a package may own multiple roles when they are one concern (`dsh-llm` owns its Service Definition and Consumer). The seam is the complete capability, never one role; reserve the term for that meaning and name a constituent by its role, class, service, contract, or extension point.
- **seam** — a *swappable capability* with three roles: a **Service Definition** (the Cordis `Service` that owns its `ctx.<key>` and vocabulary types — an abstract class such as `ShellExecutor`, or a concrete registry such as `WebRuntime`, never a TypeScript `interface`), one or more **Service Providers**, and one or more **Consumers** that inject the service. `packages/shell` is the canonical example: `dsh-shell` (Service Definition), `dsh-bash-local` / `dsh-bash-sandbox` (providers), and `dsh-tool-bash` (Consumer). Roles normally occupy separate packages when they evolve independently, but a package may own multiple roles when they are one concern (`dsh-llm` owns its Service Definition and Consumer). The seam is the complete capability, never one role; reserve the term for that meaning and name a constituent by its role, class, service, contract, or extension point.
## agent-scope

2
docs/glossary.zh.md
View File

@@ -6,7 +6,7 @@ DeepSeek Harness 的领域词汇为每个概念规定一个规范术语。各术
## capability-seam
- **seam**：一种包含三种角色的*可替换能力*：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `ShellExecutor` 这样的抽象类，也可以是 `WebRuntime` 这样的具体注册表，绝不是 TypeScript `interface`）、一个或多个 **Service provider**，以及一个或多个注入该服务的 **Consumer**。`packages/shell` 是规范范例：`dsh-shell`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方），以及 `dsh-tool-bash`（Consumer）。角色需要独立演进时通常位于不同包，但属于同一关注点时，一个包也可以承担多个角色（`dsh-llm` 同时承担 Service Definition 和 Consumer）。seam 是完整能力，绝不是其中一个角色；该术语仅保留此义，能力成员应按其角色、类、服务、约定或扩展点命名。
- **seam**：一种包含三种角色的*可替换能力*：**Service Definition**（拥有自身 `ctx.<key>` 和词汇类型的 Cordis `Service`——可以是 `ShellExecutor` 这样的抽象类，也可以是 `WebRuntime` 这样的具体注册表，绝不是 TypeScript `interface`）、一个或多个 **Service Provider**，以及一个或多个注入该服务的 **Consumer**。`packages/shell` 是规范范例：`dsh-shell`（Service Definition）、`dsh-bash-local` / `dsh-bash-sandbox`（提供方），以及 `dsh-tool-bash`（Consumer）。角色需要独立演进时通常位于不同包，但属于同一关注点时，一个包也可以承担多个角色（`dsh-llm` 同时承担 Service Definition 和 Consumer）。seam 是完整能力，绝不是其中一个角色；该术语仅保留此义，能力成员应按其角色、类、服务、约定或扩展点命名。
## agent-scope

5
docs/i18n/terminology.md
View File

@@ -56,7 +56,8 @@
| Round | Round | | 回合、目标回合、Ralph 回合 | 外层策略使用 Round 时，领域层级为 Session > Round > Turn（轮次） > Step（步骤）；Round 是可选的外层策略迭代，并非每个会话轮次都具有的通用层级。Goal Round 与 Ralph Round 均保留英文。一个 Round 承载一个轮次，步骤隶属于该轮次；明确的零步骤轮次仍保持原义。 |
| schema | schema | | | |
| schema DSL | schema DSL | | | |
| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/shell` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
| seam | seam | | 接缝 | 一个可替换能力的整体，包含 Service Definition / Service Provider / Consumer 三种角色；角色需要独立演化时才拆包，也可由同一包承担多个角色。以 `packages/shell` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |
| Service Provider | Service Provider | | Service provider | 能力 seam 的命名角色；单数固定写作 Service Provider，复数写作 Service Providers。泛指提供服务的 provider 不适用本词条 |
| skill | skill | skill（技能） | | |
| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |
| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |
@@ -97,7 +98,7 @@
| cancel | 取消 | | | |
| canary test | canary 测试 | | 金丝雀测试 | 本仓库保留 `canary` |
| capability | 能力 | | | 必须与 `feature` → `功能` 区分 |
| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |
| capability seam | 能力 seam | | 功能 seam、能力接缝 | 本仓库 Service Definition、Service Provider 与 Consumer 三种角色组成完整可替换能力的命名架构概念；普通 `seam` 仍按其词条处理 |
| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |
| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |
| checkpoint | 检查点 | | | |

4
docs/persistence-catalog.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 docs/persistence-catalog.md
persistence-catalog.md: 032f7ae45d05b688fd317e9aa46363f658f19b76
persistence-catalog.zh.md: 4f3ace46f7abb2d87be1cd66cbead0ac6b0cccda
persistence-catalog.md: c400298f7d37c590918820bcbda10e6550f197e8
persistence-catalog.zh.md: 65ec0e3fbdd226c51a371dc9a90f10db5c929c7a

88
docs/persistence-catalog.md
View File

@@ -96,6 +96,8 @@ Sources: [`packages/core/session/src/types.ts:336`](../packages/core/session/src
### `agent/*`
<a id="agentinboxspliced--log-only"></a>
#### `agent/inbox/spliced` — log-only
```ts persistence-catalog
@@ -117,6 +119,8 @@ Source: [`packages/core/agent/src/types.ts:19`](../packages/core/agent/src/types
### `agent-preset/*`
<a id="agent-presetselected--log-only"></a>
#### `agent-preset/selected` — log-only
```ts persistence-catalog
@@ -133,6 +137,8 @@ Source: [`packages/preset/agent-presets/src/session.ts:26`](../packages/preset/a
### `approval/*`
<a id="approvalasked--log-only"></a>
#### `approval/asked` — log-only
```ts persistence-catalog
@@ -156,6 +162,8 @@ Types: [CallId](subsystems/core.md)
Source: [`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
<a id="approvaldecided--log-only"></a>
#### `approval/decided` — log-only
```ts persistence-catalog
@@ -172,6 +180,8 @@ Source: [`packages/interaction/user-approval/src/index.ts:44`](../packages/inter
Source: [`packages/interaction/user-approval/src/index.ts:55`](../packages/interaction/user-approval/src/index.ts)
<a id="approvalpolicy--log-only"></a>
#### `approval/policy` — log-only
```ts persistence-catalog
@@ -194,6 +204,8 @@ Source: [`packages/interaction/user-approval/src/index.ts:67`](../packages/inter
### `assistant/*`
<a id="assistantchunk--log-only"></a>
#### `assistant/chunk` — log-only
```ts persistence-catalog
@@ -205,6 +217,8 @@ Types: [StreamChunk](subsystems/llm-streaming.md)
Source: [`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
<a id="assistantmessage--surface"></a>
#### `assistant/message` — surface
```ts persistence-catalog
@@ -223,6 +237,8 @@ Source: [`packages/core/session/src/types.ts:273`](../packages/core/session/src/
### `command/*`
<a id="commanddone--log-only"></a>
#### `command/done` — log-only
```ts persistence-catalog
@@ -242,6 +258,8 @@ Source: [`packages/core/session/src/types.ts:273`](../packages/core/session/src/
Source: [`packages/interaction/commands/src/types.ts:95`](../packages/interaction/commands/src/types.ts)
<a id="commandrun--log-only"></a>
#### `command/run` — log-only
```ts persistence-catalog
@@ -262,6 +280,8 @@ Source: [`packages/interaction/commands/src/types.ts:88`](../packages/interactio
### `compaction/*`
<a id="compactionend--log-only"></a>
#### `compaction/end` — log-only
```ts persistence-catalog
@@ -274,6 +294,8 @@ Source: [`packages/interaction/commands/src/types.ts:88`](../packages/interactio
Source: [`packages/compaction/compaction/src/types.ts:71`](../packages/compaction/compaction/src/types.ts)
<a id="compactionprune--log-only"></a>
#### `compaction/prune` — log-only
```ts persistence-catalog
@@ -298,6 +320,8 @@ Source: [`packages/compaction/compaction/src/types.ts:71`](../packages/compactio
Source: [`packages/compaction/compaction/src/types.ts:81`](../packages/compaction/compaction/src/types.ts)
<a id="compactionstart--log-only"></a>
#### `compaction/start` — log-only
```ts persistence-catalog
@@ -311,6 +335,8 @@ Source: [`packages/compaction/compaction/src/types.ts:81`](../packages/compactio
Source: [`packages/compaction/compaction/src/types.ts:23`](../packages/compaction/compaction/src/types.ts)
<a id="compactionsummary--log-only"></a>
#### `compaction/summary` — log-only
```ts persistence-catalog
@@ -365,6 +391,8 @@ Source: [`packages/compaction/compaction/src/types.ts:33`](../packages/compactio
### `feedback/*`
<a id="feedbackrecord--log-only"></a>
#### `feedback/record` — log-only
```ts persistence-catalog
@@ -379,6 +407,8 @@ Source: [`packages/feedback/command-feedback/src/index.ts:62`](../packages/feedb
### `goal/*`
<a id="goalchange--log-only"></a>
#### `goal/change` — log-only
```ts persistence-catalog
@@ -392,6 +422,8 @@ Source: [`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain
### `hook/*`
<a id="hookinvoked--log-only"></a>
#### `hook/invoked` — log-only
```ts persistence-catalog
@@ -415,6 +447,8 @@ Source: [`packages/goal/goal/src/domain.ts:66`](../packages/goal/goal/src/domain
Source: [`packages/hooks/hook-protocol/src/types.ts:19`](../packages/hooks/hook-protocol/src/types.ts)
<a id="hookresult--log-only"></a>
#### `hook/result` — log-only
```ts persistence-catalog
@@ -438,6 +472,8 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-
### `llm/*`
<a id="llmretry--log-only"></a>
#### `llm/retry` — log-only
```ts persistence-catalog
@@ -447,6 +483,8 @@ Source: [`packages/hooks/hook-protocol/src/types.ts:31`](../packages/hooks/hook-
Source: [`packages/llm/llm-retry/src/types.ts:9`](../packages/llm/llm-retry/src/types.ts)
<a id="llmretry-started--log-only"></a>
#### `llm/retry-started` — log-only
```ts persistence-catalog
@@ -458,6 +496,8 @@ Source: [`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src
### `permission/*`
<a id="permissionpreset--log-only"></a>
#### `permission/preset` — log-only
```ts persistence-catalog
@@ -474,6 +514,8 @@ Source: [`packages/interaction/permission-presets/src/index.ts:50`](../packages/
### `plan/*`
<a id="planmode--log-only"></a>
#### `plan/mode` — log-only
```ts persistence-catalog
@@ -489,6 +531,8 @@ Source: [`packages/plan/plan-mode/src/index.ts:53`](../packages/plan/plan-mode/s
### `request/*`
<a id="requestcontext--log-only"></a>
#### `request/context` — log-only
```ts persistence-catalog
@@ -501,6 +545,8 @@ Source: [`packages/plan/plan-mode/src/index.ts:53`](../packages/plan/plan-mode/s
Source: [`packages/core/session/src/types.ts:309`](../packages/core/session/src/types.ts)
<a id="requestheader--log-only"></a>
#### `request/header` — log-only
```ts persistence-catalog
@@ -515,6 +561,8 @@ Source: [`packages/core/session/src/types.ts:304`](../packages/core/session/src/
### `sandbox/*`
<a id="sandboxmode--log-only"></a>
#### `sandbox/mode` — log-only
```ts persistence-catalog
@@ -536,6 +584,8 @@ Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/s
### `schedule/*`
<a id="schedulechange--log-only"></a>
#### `schedule/change` — log-only
```ts persistence-catalog
@@ -552,6 +602,8 @@ Source: [`packages/schedule/schedule/src/types.ts:219`](../packages/schedule/sch
### `session/*`
<a id="sessionend-seed--log-only"></a>
#### `session/end-seed` — log-only
```ts persistence-catalog
@@ -582,6 +634,8 @@ Source: [`packages/schedule/schedule/src/types.ts:219`](../packages/schedule/sch
Source: [`packages/core/session/src/types.ts:332`](../packages/core/session/src/types.ts)
<a id="sessiontitle--log-only"></a>
#### `session/title` — log-only
```ts persistence-catalog
@@ -596,6 +650,8 @@ Types: [SessionTitleEventData](subsystems/session-title.md)
Source: [`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
<a id="sessiontitle-llm-request--log-only"></a>
#### `session/title-llm-request` — log-only
```ts persistence-catalog
@@ -609,6 +665,8 @@ Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/sessi
### `step/*`
<a id="stepend--log-only"></a>
#### `step/end` — log-only
```ts persistence-catalog
@@ -618,6 +676,8 @@ Source: [`packages/session/session-title-llm/src/index.ts:43`](../packages/sessi
Source: [`packages/core/session/src/types.ts:256`](../packages/core/session/src/types.ts)
<a id="stepstart--log-only"></a>
#### `step/start` — log-only
```ts persistence-catalog
@@ -629,6 +689,8 @@ Source: [`packages/core/session/src/types.ts:254`](../packages/core/session/src/
### `subagent/*`
<a id="subagentdescriptor--log-only"></a>
#### `subagent/descriptor` — log-only
```ts persistence-catalog
@@ -646,6 +708,8 @@ Source: [`packages/subagent/subagent/src/descriptor.ts:37`](../packages/subagent
### `todo/*`
<a id="todowrite--log-only"></a>
#### `todo/write` — log-only
```ts persistence-catalog
@@ -659,6 +723,8 @@ Source: [`packages/core/session/src/types.ts:299`](../packages/core/session/src/
### `tool/*`
<a id="toolcall--log-only"></a>
#### `tool/call` — log-only
```ts persistence-catalog
@@ -674,6 +740,8 @@ Types: [CallId](subsystems/core.md)
Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
<a id="toolcode-dispatch--log-only"></a>
#### `tool/code-dispatch` — log-only
```ts persistence-catalog
@@ -697,6 +765,8 @@ Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/
Source: [`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types.ts)
<a id="toolcode-dispatch-start--log-only"></a>
#### `tool/code-dispatch-start` — log-only
```ts persistence-catalog
@@ -718,6 +788,8 @@ Source: [`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types
Source: [`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types.ts)
<a id="toolresult--surface"></a>
#### `tool/result` — surface
```ts persistence-catalog
@@ -745,6 +817,8 @@ Source: [`packages/core/session/src/types.ts:291`](../packages/core/session/src/
### `tool-workflow/*`
<a id="tool-workflowagent-end--log-only"></a>
#### `tool-workflow/agent-end` — log-only
```ts persistence-catalog
@@ -757,6 +831,8 @@ Source: [`packages/core/session/src/types.ts:291`](../packages/core/session/src/
Source: [`packages/workflow/tool-workflow/src/types.ts:57`](../packages/workflow/tool-workflow/src/types.ts)
<a id="tool-workflowagent-start--log-only"></a>
#### `tool-workflow/agent-start` — log-only
```ts persistence-catalog
@@ -769,6 +845,8 @@ Source: [`packages/workflow/tool-workflow/src/types.ts:57`](../packages/workflow
Source: [`packages/workflow/tool-workflow/src/types.ts:52`](../packages/workflow/tool-workflow/src/types.ts)
<a id="tool-workflowrun-end--log-only"></a>
#### `tool-workflow/run-end` — log-only
```ts persistence-catalog
@@ -781,6 +859,8 @@ Source: [`packages/workflow/tool-workflow/src/types.ts:52`](../packages/workflow
Source: [`packages/workflow/tool-workflow/src/types.ts:62`](../packages/workflow/tool-workflow/src/types.ts)
<a id="tool-workflowrun-start--log-only"></a>
#### `tool-workflow/run-start` — log-only
```ts persistence-catalog
@@ -795,6 +875,8 @@ Source: [`packages/workflow/tool-workflow/src/types.ts:47`](../packages/workflow
### `turn/*`
<a id="turnend--log-only"></a>
#### `turn/end` — log-only
```ts persistence-catalog
@@ -813,6 +895,8 @@ Types: [TurnEndReason](subsystems/session.md)
Source: [`packages/core/session/src/types.ts:252`](../packages/core/session/src/types.ts)
<a id="turnstart--log-only"></a>
#### `turn/start` — log-only
```ts persistence-catalog
@@ -829,6 +913,8 @@ Source: [`packages/core/session/src/types.ts:243`](../packages/core/session/src/
### `user/*`
<a id="usermessage--surface"></a>
#### `user/message` — surface
```ts persistence-catalog
@@ -846,6 +932,8 @@ Source: [`packages/core/session/src/types.ts:264`](../packages/core/session/src/
### `web/*`
<a id="webdeepseek-search-llm-request--log-only"></a>
#### `web/deepseek-search-llm-request` — log-only
```ts persistence-catalog

88
docs/persistence-catalog.zh.md
View File

@@ -98,6 +98,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `agent/*`
<a id="agentinboxspliced--log-only"></a>
#### `agent/inbox/spliced` — log-only
```ts persistence-catalog
@@ -119,6 +121,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `agent-preset/*`
<a id="agent-presetselected--log-only"></a>
#### `agent-preset/selected` — log-only
```ts persistence-catalog
@@ -135,6 +139,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `approval/*`
<a id="approvalasked--log-only"></a>
#### `approval/asked` — log-only
```ts persistence-catalog
@@ -158,6 +164,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/interaction/user-approval/src/index.ts:44`](../packages/interaction/user-approval/src/index.ts)
<a id="approvaldecided--log-only"></a>
#### `approval/decided` — log-only
```ts persistence-catalog
@@ -174,6 +182,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/interaction/user-approval/src/index.ts:55`](../packages/interaction/user-approval/src/index.ts)
<a id="approvalpolicy--log-only"></a>
#### `approval/policy` — log-only
```ts persistence-catalog
@@ -196,6 +206,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `assistant/*`
<a id="assistantchunk--log-only"></a>
#### `assistant/chunk` — log-only
```ts persistence-catalog
@@ -207,6 +219,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
<a id="assistantmessage--surface"></a>
#### `assistant/message` — surface
```ts persistence-catalog
@@ -225,6 +239,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `command/*`
<a id="commanddone--log-only"></a>
#### `command/done` — log-only
```ts persistence-catalog
@@ -244,6 +260,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/interaction/commands/src/types.ts:95`](../packages/interaction/commands/src/types.ts)
<a id="commandrun--log-only"></a>
#### `command/run` — log-only
```ts persistence-catalog
@@ -264,6 +282,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `compaction/*`
<a id="compactionend--log-only"></a>
#### `compaction/end` — log-only
```ts persistence-catalog
@@ -276,6 +296,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/compaction/compaction/src/types.ts:71`](../packages/compaction/compaction/src/types.ts)
<a id="compactionprune--log-only"></a>
#### `compaction/prune` — log-only
```ts persistence-catalog
@@ -300,6 +322,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/compaction/compaction/src/types.ts:81`](../packages/compaction/compaction/src/types.ts)
<a id="compactionstart--log-only"></a>
#### `compaction/start` — log-only
```ts persistence-catalog
@@ -313,6 +337,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/compaction/compaction/src/types.ts:23`](../packages/compaction/compaction/src/types.ts)
<a id="compactionsummary--log-only"></a>
#### `compaction/summary` — log-only
```ts persistence-catalog
@@ -367,6 +393,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `feedback/*`
<a id="feedbackrecord--log-only"></a>
#### `feedback/record` — log-only
```ts persistence-catalog
@@ -381,6 +409,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `goal/*`
<a id="goalchange--log-only"></a>
#### `goal/change` — log-only
```ts persistence-catalog
@@ -394,6 +424,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `hook/*`
<a id="hookinvoked--log-only"></a>
#### `hook/invoked` — log-only
```ts persistence-catalog
@@ -417,6 +449,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/hooks/hook-protocol/src/types.ts:19`](../packages/hooks/hook-protocol/src/types.ts)
<a id="hookresult--log-only"></a>
#### `hook/result` — log-only
```ts persistence-catalog
@@ -440,6 +474,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `llm/*`
<a id="llmretry--log-only"></a>
#### `llm/retry` — log-only
```ts persistence-catalog
@@ -449,6 +485,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/llm/llm-retry/src/types.ts:9`](../packages/llm/llm-retry/src/types.ts)
<a id="llmretry-started--log-only"></a>
#### `llm/retry-started` — log-only
```ts persistence-catalog
@@ -460,6 +498,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `permission/*`
<a id="permissionpreset--log-only"></a>
#### `permission/preset` — log-only
```ts persistence-catalog
@@ -476,6 +516,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `plan/*`
<a id="planmode--log-only"></a>
#### `plan/mode` — log-only
```ts persistence-catalog
@@ -491,6 +533,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `request/*`
<a id="requestcontext--log-only"></a>
#### `request/context` — log-only
```ts persistence-catalog
@@ -503,6 +547,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/session/src/types.ts:309`](../packages/core/session/src/types.ts)
<a id="requestheader--log-only"></a>
#### `request/header` — log-only
```ts persistence-catalog
@@ -517,6 +563,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `sandbox/*`
<a id="sandboxmode--log-only"></a>
#### `sandbox/mode` — log-only
```ts persistence-catalog
@@ -538,6 +586,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `schedule/*`
<a id="schedulechange--log-only"></a>
#### `schedule/change` — log-only
```ts persistence-catalog
@@ -554,6 +604,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `session/*`
<a id="sessionend-seed--log-only"></a>
#### `session/end-seed` — log-only
```ts persistence-catalog
@@ -584,6 +636,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/session/src/types.ts:332`](../packages/core/session/src/types.ts)
<a id="sessiontitle--log-only"></a>
#### `session/title` — log-only
```ts persistence-catalog
@@ -598,6 +652,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/session/session-title/src/index.ts:100`](../packages/session/session-title/src/index.ts)
<a id="sessiontitle-llm-request--log-only"></a>
#### `session/title-llm-request` — log-only
```ts persistence-catalog
@@ -611,6 +667,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `step/*`
<a id="stepend--log-only"></a>
#### `step/end` — log-only
```ts persistence-catalog
@@ -620,6 +678,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/session/src/types.ts:256`](../packages/core/session/src/types.ts)
<a id="stepstart--log-only"></a>
#### `step/start` — log-only
```ts persistence-catalog
@@ -631,6 +691,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `subagent/*`
<a id="subagentdescriptor--log-only"></a>
#### `subagent/descriptor` — log-only
```ts persistence-catalog
@@ -648,6 +710,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `todo/*`
<a id="todowrite--log-only"></a>
#### `todo/write` — log-only
```ts persistence-catalog
@@ -661,6 +725,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `tool/*`
<a id="toolcall--log-only"></a>
#### `tool/call` — log-only
```ts persistence-catalog
@@ -676,6 +742,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
<a id="toolcode-dispatch--log-only"></a>
#### `tool/code-dispatch` — log-only
```ts persistence-catalog
@@ -699,6 +767,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/tools/src/types.ts:56`](../packages/core/tools/src/types.ts)
<a id="toolcode-dispatch-start--log-only"></a>
#### `tool/code-dispatch-start` — log-only
```ts persistence-catalog
@@ -720,6 +790,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/tools/src/types.ts:40`](../packages/core/tools/src/types.ts)
<a id="toolresult--surface"></a>
#### `tool/result` — surface
```ts persistence-catalog
@@ -747,6 +819,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `tool-workflow/*`
<a id="tool-workflowagent-end--log-only"></a>
#### `tool-workflow/agent-end` — log-only
```ts persistence-catalog
@@ -759,6 +833,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/workflow/tool-workflow/src/types.ts:57`](../packages/workflow/tool-workflow/src/types.ts)
<a id="tool-workflowagent-start--log-only"></a>
#### `tool-workflow/agent-start` — log-only
```ts persistence-catalog
@@ -771,6 +847,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/workflow/tool-workflow/src/types.ts:52`](../packages/workflow/tool-workflow/src/types.ts)
<a id="tool-workflowrun-end--log-only"></a>
#### `tool-workflow/run-end` — log-only
```ts persistence-catalog
@@ -783,6 +861,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/workflow/tool-workflow/src/types.ts:62`](../packages/workflow/tool-workflow/src/types.ts)
<a id="tool-workflowrun-start--log-only"></a>
#### `tool-workflow/run-start` — log-only
```ts persistence-catalog
@@ -797,6 +877,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `turn/*`
<a id="turnend--log-only"></a>
#### `turn/end` — log-only
```ts persistence-catalog
@@ -815,6 +897,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
来源：[`packages/core/session/src/types.ts:252`](../packages/core/session/src/types.ts)
<a id="turnstart--log-only"></a>
#### `turn/start` — log-only
```ts persistence-catalog
@@ -831,6 +915,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `user/*`
<a id="usermessage--surface"></a>
#### `user/message` — surface
```ts persistence-catalog
@@ -848,6 +934,8 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
### `web/*`
<a id="webdeepseek-search-llm-request--log-only"></a>
#### `web/deepseek-search-llm-request` — log-only
```ts persistence-catalog

4
docs/subsystems/code-runtime.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 docs/subsystems/code-runtime.md
code-runtime.md: e677bcaef26f7999181825934b880514e425f615
code-runtime.zh.md: e94dd77b1e430e7bd15633881d65521409819574
code-runtime.md: 09036819d4fb6a4e2f83cf7923584780ca2211f8
code-runtime.zh.md: 2e717f17313ce23cb37616199bd83776c0a40756

2
docs/subsystems/code-runtime.md
View File

@@ -2,7 +2,7 @@
English | [中文](code-runtime.zh.md)
The code-execution seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose Service Definition ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread Service provider and tool-registry Consumer are specified by the [Code Mode foundation](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md).
The code-execution seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose Service Definition ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread Service Provider and tool-registry Consumer are specified by the [Code Mode foundation](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md).
Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)

2
docs/subsystems/code-runtime.zh.md
View File

@@ -2,7 +2,7 @@
[English](code-runtime.md) | 中文
代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其 Service Definition（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread Service provider 与工具注册表 Consumer 的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
代码执行 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：其 Service Definition（[dsh-code-runtime](../../packages/code-runtime/code-runtime)，`ctx.codeRuntime`）使用宿主提供的异步绑定运行一段模型编写的程序，并报告其打印内容与返回值。代码执行是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。各后端的执行基底与源语言不同，这两项均为服务上的只读描述符；worker-thread Service Provider 与工具注册表 Consumer 的约定见 [Code Mode 基础设计](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) 和[类型化返回约定](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)。
源码：[`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)

4
docs/subsystems/compaction.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 docs/subsystems/compaction.md
compaction.md: 1e14c60161ef945069d9e6f72767dabdfa42e702
compaction.zh.md: 60f5afb8c673c94c9c6f5802fb4f12e224e04203
compaction.md: 95a3d4b844c6126a09d4fdaafdedcf987b21d1c6
compaction.zh.md: 3b72bb4f81675119d869fb2f7439f4640e6a5a86

2
docs/subsystems/compaction.md
View File

@@ -2,7 +2,7 @@
English | [中文](compaction.zh.md)
The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: Service Definition ([dsh-compaction](../../packages/compaction/compaction), `ctx.compaction`), Service provider (a backend such as [dsh-compaction-basic](../../packages/compaction/compaction-basic)), and human Consumer ([dsh-command-compact](../../packages/compaction/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)).
The compaction seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) split like bash: Service Definition ([dsh-compaction](../../packages/compaction/compaction), `ctx.compaction`), Service Provider (a backend such as [dsh-compaction-basic](../../packages/compaction/compaction-basic)), and human Consumer ([dsh-command-compact](../../packages/compaction/command-compact)). Compaction is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A tokenizer- or template-based backend is a sibling package implementing the same interface. Unlike bash, the interface necessarily depends on `dsh-session` and `dsh-llm`: its verbs act on an agent-owned `Session`, and its durable summary event uses the `ContentBlock` vocabulary (see the [compaction capability-seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)).
Source: [`packages/compaction/compaction/src/types.ts`](../../packages/compaction/compaction/src/types.ts)

2
docs/subsystems/compaction.zh.md
View File

@@ -2,7 +2,7 @@
[English](compaction.md) | 中文
压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为 Service Definition（[dsh-compaction](../../packages/compaction/compaction)，`ctx.compaction`）、Service provider（例如 [dsh-compaction-basic](../../packages/compaction/compaction-basic) 后端）和面向用户的 Consumer（[dsh-command-compact](../../packages/compaction/command-compact)）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。
压缩 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)，与 bash 一样分为 Service Definition（[dsh-compaction](../../packages/compaction/compaction)，`ctx.compaction`）、Service Provider（例如 [dsh-compaction-basic](../../packages/compaction/compaction-basic) 后端）和面向用户的 Consumer（[dsh-command-compact](../../packages/compaction/command-compact)）。压缩是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。基于 tokenizer 或模板的后端是实现同一接口的兄弟包。与 bash 不同，该接口必然依赖 `dsh-session` 和 `dsh-llm`：其动词作用于 agent 所有的 `Session`，而其持久摘要事件使用 `ContentBlock` 词汇（见[压缩能力 seam Agent Note](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md)）。
源码：[`packages/compaction/compaction/src/types.ts`](../../packages/compaction/compaction/src/types.ts)

4
docs/subsystems/core.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 docs/subsystems/core.md
core.md: 6eda80cbd164168c3c4a846c9bc50a8fc12b0c92
core.zh.md: 14c2e78bc3fff959fb0c0040eae0f382985ecdf4
core.md: d14ad52e57572d5b0b110a0b16ff734e3499bdf5
core.zh.md: 9ace28731f2532f571b66f2e7f6a3ea4a2c4e345

2
docs/subsystems/core.md
View File

@@ -257,6 +257,8 @@ Its full fields, the `defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` typed
Two patterns recur across every subsystem and are documented once, here.
<a id="the-map--derived-union-pattern"></a>
### The `…Map → derived-union` pattern
Almost every extensible sum type in the harness follows one pattern: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.

2
docs/subsystems/core.zh.md
View File

@@ -263,6 +263,8 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
两个模式在每个子系统中反复出现，只在此处记录一次。
<a id="the-map--derived-union-pattern"></a>
### `…Map → derived-union` 模式
harness 中几乎所有可扩展的和类型都遵循同一模式：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包。

4
docs/subsystems/jobs.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 docs/subsystems/jobs.md
jobs.md: 67998599f8bc8c9b50278e9eaab8b6a5c70a33bc
jobs.zh.md: 41f60e450dcb85ee867a6c44f1e0053950f3ec71
jobs.md: b11dc7fbe869dcaa9e71e6956a76559476391775
jobs.zh.md: 03c3ceee8953c8c4c70f060b7e9d88371c1ebd7b

2
docs/subsystems/jobs.md
View File

@@ -154,7 +154,7 @@ interface JobRead {
## Service behavior
The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, failure-isolated `onJobDone` and `onJobsChanged` listeners, and when `attachController` becomes available; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service provider. Authorization compares owner sessions; owner cleanup and admission use the exact registered `Agent` instance. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer.
The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, failure-isolated `onJobDone` and `onJobsChanged` listeners, and when `attachController` becomes available; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the exact registered `Agent` instance. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer.
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->

2
docs/subsystems/jobs.zh.md
View File

@@ -154,7 +154,7 @@ interface JobRead {
## 服务行为
抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onJobDone` 与 `onJobsChanged` 监听器，以及 `attachController` 何时可用；[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是其进程局部 Service provider。授权会比较拥有者会话；拥有者清理与准入会使用确切的已注册 `Agent` 实例。本地 Service provider 的 `maxConcurrentJobsPerOwner` 配置必须是正的安全整数，默认值为 `10`；它按确切 owner 统计 `running` 与 `stopping` 记录，所有无 owner 任务共享一个服务级桶，并在生产方终止结算后释放容量。Service Definition 约定见 [`dsh-jobs`](../../packages/jobs/jobs/README.md)，注册表生命周期与准入策略见 [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md)，面向模型的 Consumer 见 [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md)。
抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onJobDone` 与 `onJobsChanged` 监听器，以及 `attachController` 何时可用；[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是其进程局部 Service Provider。授权会比较拥有者会话；拥有者清理与准入会使用确切的已注册 `Agent` 实例。本地 Service Provider 的 `maxConcurrentJobsPerOwner` 配置必须是正的安全整数，默认值为 `10`；它按确切 owner 统计 `running` 与 `stopping` 记录，所有无 owner 任务共享一个服务级桶，并在生产方终止结算后释放容量。Service Definition 约定见 [`dsh-jobs`](../../packages/jobs/jobs/README.md)，注册表生命周期与准入策略见 [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md)，面向模型的 Consumer 见 [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md)。
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->

4
docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
llm-streaming.md: 0f395245332e735c04997bd1ca82f66fa9286104
llm-streaming.zh.md: fbaa47d14d57e7377be4db6ecaa04f11997572a6
llm-streaming.md: 7c0e0865f8dcc0e7722bb2205d0129d9e0ca3086
llm-streaming.zh.md: 5c31909ee79137c6c5eef101235b43a2419b1339

41
docs/subsystems/llm-streaming.md
View File

@@ -151,10 +151,35 @@ type ContextFormed =
| { readonly form: 'recall' }
```
<a id="streamchunk--the-raw-protocol"></a>
## `StreamChunk` — the raw protocol
A streaming response interleaves several typed blocks (text, reasoning, multiple tool calls). `index` ties each delta to its block; `block-end` carries the fully-assembled `ContentBlock` so consumers don't have to re-assemble deltas themselves. It is a **closed** discriminated union — a `switch` over `type` ends with `assertNever`, so adding a variant breaks compilation at every consumer that must handle it.
```ts type-equiv
/**
* Adapter-private lossless-JSON state for replaying a successful response,
* carried by a terminal `finish` chunk and stored on the assembled assistant
* message's model source. Both halves stay opaque to the harness; only the
* split is shared vocabulary, so assembly can keep stored metadata aligned
* with stored content without reading either half.
*/
interface ReplayEnvelope {
/** Response-level adapter-private metadata (ids, native stop reason). */
response: unknown
/**
* Per-block adapter-private metadata, one entry per emitted block in
* first-seen stream order. When assembly drops a block it drops the entry at
* the same position; entries whose length does not match the emitted block
* count discard the whole envelope. An adapter whose metadata is independent
* of block structure omits this field and the envelope passes through
* assembly unchanged.
*/
blocks?: readonly unknown[]
}
```
```ts type-equiv
/**
* Raw streaming protocol emitted by adapters.
@@ -174,8 +199,8 @@ type StreamChunk =
| {
type: 'finish'
reason: FinishReason
/** Adapter-private lossless-JSON state for replaying a successful response. */
replayState?: unknown
/** Replay metadata for a successful response; see {@link ReplayEnvelope}. */
replayState?: ReplayEnvelope
}
```
@@ -211,7 +236,7 @@ Every adapter MUST obey these, and every consumer may rely on them:
- **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
- **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test.
- **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmRuntime` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state.
- **Replay state is adapter-owned; its split is shared.** A successful `finish` may carry a `ReplayEnvelope`: opaque response-level metadata plus optional per-block entries aligned with the emitted block sequence. The alignment is the harness's vocabulary — when assembly drops a block it drops the entry at the same position, so stored metadata always describes stored content. The loop stores the pruned envelope with the assembled assistant message. On a later request, `LlmRuntime` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state. Durable content stays authoritative: a stored state the reading adapter cannot use degrades that one message to provider-neutral conversion with a diagnostic instead of failing the request.
## `ResolvedRetryPolicy`
@@ -265,6 +290,8 @@ interface TokenUsage {
`BlockAssembler` ([`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)) is the single shared implementation that folds a `StreamChunk` stream back into `ContentBlock`s, usage, finish reason, and replay state. The loop logs the raw chunks while feeding the same chunks through an assembler, then stores the assembled assistant content with the provider and model that produced it. A consumer that needs the assembled result without re-implementing the fold uses this.
One keep/drop decision covers content and metadata together: a `max-tokens` finish drops every tool call because a truncated call is unsafe to execute, and the same decision prunes the replay envelope's per-block entry at each dropped position. `blocks()` and `replayState` therefore cannot disagree, whatever assembly removes.
```ts public-api
/**
* Incrementally assembles raw {@link StreamChunk}s into complete
@@ -294,8 +321,12 @@ declare class BlockAssembler {
get usage(): TokenUsage | undefined;
/** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
get finish(): FinishReason;
/** Adapter-private replay state from the terminal finish chunk, if any. */
get replayState(): unknown;
/**
* Replay metadata from the terminal finish chunk, if any, with per-block
* entries pruned in step with {@link blocks}. Undefined when the envelope's
* entries do not align with the emitted blocks.
*/
get replayState(): ReplayEnvelope | undefined;
/**
* The assembled assistant message.
* @param source - producer attribution for the assembled message.

39
docs/subsystems/llm-streaming.zh.md
View File

@@ -157,6 +157,29 @@ type ContextFormed =
一个流式响应交错包含多种类型的块（文本、推理（reasoning）、多个工具调用）。`index` 将每个 delta 关联到其所属块；`block-end` 携带完整组装好的 `ContentBlock`，消费方无需自行重新组装 delta。这是一个**封闭的**可辨识联合类型：对 `type` 的 `switch` 以 `assertNever` 结尾，因此新增变体会在每个必须处理它的消费方处触发编译错误。
```ts type-equiv
/**
* Adapter-private lossless-JSON state for replaying a successful response,
* carried by a terminal `finish` chunk and stored on the assembled assistant
* message's model source. Both halves stay opaque to the harness; only the
* split is shared vocabulary, so assembly can keep stored metadata aligned
* with stored content without reading either half.
*/
interface ReplayEnvelope {
/** Response-level adapter-private metadata (ids, native stop reason). */
response: unknown
/**
* Per-block adapter-private metadata, one entry per emitted block in
* first-seen stream order. When assembly drops a block it drops the entry at
* the same position; entries whose length does not match the emitted block
* count discard the whole envelope. An adapter whose metadata is independent
* of block structure omits this field and the envelope passes through
* assembly unchanged.
*/
blocks?: readonly unknown[]
}
```
```ts type-equiv
/**
* Raw streaming protocol emitted by adapters.
@@ -176,8 +199,8 @@ type StreamChunk =
| {
type: 'finish'
reason: FinishReason
/** Adapter-private lossless-JSON state for replaying a successful response. */
replayState?: unknown
/** Replay metadata for a successful response; see {@link ReplayEnvelope}. */
replayState?: ReplayEnvelope
}
```
@@ -215,7 +238,7 @@ interface LlmFailure {
- **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
- **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明。
- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmRuntime` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。
- **回放状态归适配器所有；其切分是共享词汇。** 成功的 `finish` 可以携带一个 `ReplayEnvelope`：不透明的响应级元数据，加上与发射块序列对齐的可选逐块条目。对齐关系是 harness 的词汇——组装丢弃某个块时，同一位置的条目一并丢弃，因此存储的元数据始终描述存储的内容。循环把裁剪后的数据与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmRuntime` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。持久化内容保持权威：读取适配器无法使用的已存状态只会把这一条消息降级为提供方无关转换并带出诊断，而不是让请求失败。
## `ResolvedRetryPolicy`
@@ -273,6 +296,8 @@ interface TokenUsage {
`BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同生成它的提供方和模型一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。
内容与元数据共用同一次保留/丢弃决定：`max-tokens` 结束会丢弃每个工具调用，因为被截断的调用不能安全执行，而同一决定会在每个被丢弃的位置裁剪回放数据的逐块条目。无论组装移除什么，`blocks()` 与 `replayState` 都不可能不一致。
```ts public-api
/**
* Incrementally assembles raw {@link StreamChunk}s into complete
@@ -302,8 +327,12 @@ declare class BlockAssembler {
get usage(): TokenUsage | undefined;
/** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
get finish(): FinishReason;
/** Adapter-private replay state from the terminal finish chunk, if any. */
get replayState(): unknown;
/**
* Replay metadata from the terminal finish chunk, if any, with per-block
* entries pruned in step with {@link blocks}. Undefined when the envelope's
* entries do not align with the emitted blocks.
*/
get replayState(): ReplayEnvelope | undefined;
/**
* The assembled assistant message.
* @param source - producer attribution for the assembled message.

4
docs/subsystems/lsp.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 docs/subsystems/lsp.md
lsp.md: 66317acc25860cfeaa3d8fb35daf2947e811e18c
lsp.zh.md: 8d975e30cb5065fd89645166c657050233eb81da
lsp.md: 18ed0e178c73702534a9964557a3dabf7bb9dd11
lsp.zh.md: 8b154143057f05d74bf28b715a385a2ec65fbbff

2
docs/subsystems/lsp.md
View File

@@ -2,7 +2,7 @@
English | [中文](lsp.zh.md)
The LSP seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: Service Definition ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic Service provider ([dsh-lsp-stdio](../../packages/lsp/lsp-stdio), a configured stdio language-server host), and Consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
The LSP seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: Service Definition ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic Service Provider ([dsh-lsp-stdio](../../packages/lsp/lsp-stdio), a configured stdio language-server host), and Consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation.
Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)

2
docs/subsystems/lsp.zh.md
View File

@@ -2,7 +2,7 @@
[English](lsp.md) | 中文
LSP seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：Service Definition（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用 Service provider（[dsh-lsp-stdio](../../packages/lsp/lsp-stdio)，经过配置的 stdio 语言服务器宿主）和 Consumer（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换提供方不会改变模型请求导航的方式。
LSP seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)：它在单一 `ctx.lsp` 服务上公开语义代码导航，并拆分到多个包：Service Definition（[dsh-lsp](../../packages/lsp/lsp)，`ctx.lsp` + 提供方注册表）、通用 Service Provider（[dsh-lsp-stdio](../../packages/lsp/lsp-stdio)，经过配置的 stdio 语言服务器宿主）和 Consumer（[dsh-tool-lsp](../../packages/lsp/tool-lsp)，即 `lsp` 工具 schema）。LSP 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换提供方不会改变模型请求导航的方式。
源文件：[`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts)

4
docs/subsystems/persistence.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 docs/subsystems/persistence.md
persistence.md: fde8348d64a200eda5133abf66deedee6be09857
persistence.zh.md: a2a836d81d153a2697c1d739345501e7e6770eef
persistence.md: 5b1b224e419aca205baba69894ed64467b8fb4e1
persistence.zh.md: a91e7d66b92270c82287d054e619b665e96ea206

2
docs/subsystems/persistence.md
View File

@@ -36,6 +36,8 @@ interface SessionLocation {
}
```
<a id="sessionheader--metadata-beside-the-log"></a>
## `SessionHeader` — metadata beside the log
Per-session metadata travels **separately** from the event log: format version, cwd, lineage, and the seed boundary are storage concerns, not conversation events, so they stay out of `SessionEventMap` and never reach `deriveMessages()`. The header is attached to a `Session` via `session.header`.

2
docs/subsystems/persistence.zh.md
View File

@@ -36,6 +36,8 @@ interface SessionLocation {
}
```
<a id="sessionheader--metadata-beside-the-log"></a>
## `SessionHeader`：日志旁的元数据
每个会话的元数据与事件日志**分开**存储：格式版本、cwd、血统与 seed 边界是存储层关注点而非对话事件，因此不进入 `SessionEventMap`，也不会到达 `deriveMessages()`。header 通过 `session.header` 附加到 `Session` 上。

4
docs/subsystems/session-query.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 docs/subsystems/session-query.md
session-query.md: 647b50a297a434308769ab3c5f1af0af7480b937
session-query.zh.md: 7b03f8515501abe5e1ab35d50f6a6a230a96cf0c
session-query.md: 6ddde5b8a19ebc65952b5a24003c48f55ff5a244
session-query.zh.md: b7d4ab4910c99c9f77c17f0279f2d4fd3c336659

3
docs/subsystems/session-query.md
View File

@@ -332,7 +332,7 @@ interface SessionEventTraceObservation extends SessionEventTrace {
## Errors
The closed code union distinguishes request validation, missing targets, malformed surface logs, optional-backend failure, and contradictory source metadata.
The closed code union distinguishes request validation, missing targets, malformed surface logs, optional-backend failure, deployment-disabled search, and contradictory source metadata.
```ts type-equiv
/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
@@ -350,6 +350,7 @@ type SessionQueryErrorCode =
| 'SESSION_QUERY_INVALID_SURFACE'
| 'SESSION_QUERY_INVALID_WINDOW'
| 'SESSION_QUERY_PERSISTENCE_FAILED'
| 'SESSION_QUERY_SEARCH_DISABLED'
| 'SESSION_QUERY_SESSION_NOT_FOUND'
| 'SESSION_QUERY_STALE_CURSOR'
| 'SESSION_QUERY_SOURCE_CONFLICT'

3
docs/subsystems/session-query.zh.md
View File

@@ -332,7 +332,7 @@ interface SessionEventTraceObservation extends SessionEventTrace {
## 错误
封闭的 code 联合类型区分请求校验、目标缺失、surface 日志格式错误、可选后端故障与矛盾的源元数据。
封闭的 code 联合类型区分请求校验、目标缺失、surface 日志格式错误、可选后端故障、部署关闭搜索与矛盾的源元数据。
```ts type-equiv
/** Stable machine-routable failure taxonomy for session reads, traces, and search. */
@@ -350,6 +350,7 @@ type SessionQueryErrorCode =
| 'SESSION_QUERY_INVALID_SURFACE'
| 'SESSION_QUERY_INVALID_WINDOW'
| 'SESSION_QUERY_PERSISTENCE_FAILED'
| 'SESSION_QUERY_SEARCH_DISABLED'
| 'SESSION_QUERY_SESSION_NOT_FOUND'
| 'SESSION_QUERY_STALE_CURSOR'
| 'SESSION_QUERY_SOURCE_CONFLICT'

4
docs/subsystems/session-telemetry.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 docs/subsystems/session-telemetry.md
session-telemetry.md: f6a51dbd1de43525e0a1b062f11a140317a1cdd9
session-telemetry.zh.md: 8cfd04121f9ab9741fd4a968c3f73eb6983992b7
session-telemetry.md: dd00e428c3ecb1e0158be09cce83d1a262ab0c62
session-telemetry.zh.md: 835fc0ff2f2daa1f4ac90fe615a62aa36f7fe41d

2
docs/subsystems/session-telemetry.md
View File

@@ -2,7 +2,7 @@
English | [中文](session-telemetry.zh.md)
Outbound session reporting is split as a [capability seam](../capability-seams.md): the Service Definition and capture coordinator ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.sessionTelemetry`) own the capture points, fixed chunk projection, `session-telemetry/record` redaction waterfall, handoff cursor, and minimal backend contract; the Service provider a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [Service Definition README](../../packages/session/session-telemetry/README.md).
Outbound session reporting is split as a [capability seam](../capability-seams.md): the Service Definition and capture coordinator ([dsh-session-telemetry](../../packages/session/session-telemetry), `ctx.sessionTelemetry`) own the capture points, fixed chunk projection, `session-telemetry/record` redaction waterfall, handoff cursor, and minimal backend contract; the Service Provider a deployment loads ([dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)) is the OpenTelemetry JS SDK's log pipeline configured verbatim. It is one optional capability, not part of the agent-loop spine, and nothing here reaches a model request. The boundary axiom — the harness's aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK — and the rejected alternatives are pinned in the [revival Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md); the capture points, cursor, and projection contracts live in the [Service Definition README](../../packages/session/session-telemetry/README.md).
Source: [`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)

2
docs/subsystems/session-telemetry.zh.md
View File

@@ -2,7 +2,7 @@
[English](session-telemetry.md) | 中文
对外的会话上报拆分为一项[能力 seam](../capability-seams.md)：Service Definition 与捕获协调器（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.sessionTelemetry`）拥有捕获点、固定分片投影、`session-telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的 Service provider（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [Service Definition README](../../packages/session/session-telemetry/README.md)。
对外的会话上报拆分为一项[能力 seam](../capability-seams.md)：Service Definition 与捕获协调器（[dsh-session-telemetry](../../packages/session/session-telemetry)，`ctx.sessionTelemetry`）拥有捕获点、固定分片投影、`session-telemetry/record` 脱敏 waterfall（瀑布式事件）、handoff 游标与最小后端约定；部署方加载的 Service Provider（[dsh-session-telemetry-otel](../../packages/session/session-telemetry-otel)）则是原样配置的 OpenTelemetry JS SDK 日志流水线。它是一项可选能力，不属于 agent loop（智能体循环）主干，这里也没有任何内容会进入模型请求。边界公理（harness 的职责止于 `emit()`；批处理、重试、排队与丢失策略都属于上报 SDK）连同被否决的替代方案，均已在[复活 Agent Note](../../.agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md)中定案；捕获点、游标与投影的约定见 [Service Definition README](../../packages/session/session-telemetry/README.md)。
源码：[`packages/session/session-telemetry/src/index.ts`](../../packages/session/session-telemetry/src/index.ts)

4
docs/subsystems/session.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 docs/subsystems/session.md
session.md: 4c40971fe58952b32635aa5eb767a42f73108b00
session.zh.md: d958b03fcdad91b58cc277636e599cce46a2c7fb
session.md: aea9d00b38e384e7a973ce168c3a75a62e70a8bb
session.zh.md: 8c56029af5144569f1ab6df73a8fe2278f9ef5b4

4
docs/subsystems/session.md
View File

@@ -149,6 +149,8 @@ interface TodoItem {
}
```
<a id="the-request-header-event-requestheader"></a>
### The request header event: `request/header`
The request envelope — the `EpochHeader` (call config + markers for adapter-supplied defaults + rendered system prompt + assembled tool schemas) — is logged session state, so every conversation request is a pure function of the log (the reconstructability Agent Note). A full `request/header` snapshot with reason `'initial'` or `'resume'` records each loop-instance boundary; a later changed request records another full snapshot with reason `'change'`. `foldRequestHeader(events)` reconstructs the header by selecting the latest snapshot. The event is not a `SurfaceEventType`: it produces no LLM message.
@@ -586,7 +588,7 @@ An explicitly supplied empty seed writes `session/end-seed` at seq 0, which dist
It exists because seed history and live work are otherwise byte-identical, which defeats any plugin owning a standalone open/close bracket: an unmatched `compaction/start` reads the same whether the writer crashed mid-compaction or is compacting right now. An opening marker before `session/end-seed` came from the constructor seed and belongs to an ended lifecycle, whatever ended it (a crash, a succeeding process, or a fork out of a still-running parent), so its owner may treat it as dead. That covers only brackets *this* session inherited: a concurrently live session holding an open bracket over the same history has its own boundary elsewhere, so tolerating concurrent writers needs a liveness signal beyond the log. Core writes the boundary and reads nothing from it — a bracket's vocabulary stays with its owning plugin, which is why crash repair closes turn/step/tool boundaries and never `compaction/*`.
Activity ordering excludes the boundary through `lastActivityTime(events)`: picking a session up is not work, and lazy resume means browsing writes one, so a resume picker or session list ordering by log tail would float every opened session to the top.
Consumers that order Sessions by human activity exclude this boundary: picking a Session up is not work, so ordering by the log tail would float every opened Session to the top.
## Plugin-contributed log-only events

2
docs/subsystems/session.zh.md
View File

@@ -590,7 +590,7 @@ interface TurnEndReasonMap {
它之所以必要，是因为种子历史与实时工作在字节层面完全相同，这会让任何拥有独立开／闭括号的插件失效：一个未配对的 `compaction/start`，无论写入方是在压缩中途崩溃、还是此刻正在压缩，读起来都一样。在 `session/end-seed` 之前的开启标记来自构造种子，并且属于一个已结束的生命周期，无论结束原因为何（崩溃、进程接替，或从仍在运行的父会话 fork 出来），因此其所有方可以视之为已死。这只覆盖*本*会话继承的括号：另一个并发存活的会话可能在同一段历史上持有开放括号，而它自己的边界在别处，因此容忍并发写入方还需要日志之外的存活信号。核心写入该边界但不从中读取任何内容——括号的词汇表仍归其所属插件，这也正是崩溃修复只关闭轮次／步骤／工具边界而从不处理 `compaction/*` 的原因。
活动排序通过 `lastActivityTime(events)` 排除该边界：接手会话不算工作，而惰性恢复意味着浏览就会写入一个，因此按日志尾部排序的恢复选择器或会话列表会把每个打开过的会话顶到最前。
按真人活动排序 Session 的消费方会排除该边界：接手 Session 不算工作，因此按日志尾部排序会把每个打开过的 Session 顶到最前。
## 插件贡献的仅日志事件

4
docs/subsystems/shell.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 docs/subsystems/shell.md
shell.md: 10f96936390a2b77f961ca6222d1e8c4019bbd9c
shell.zh.md: af0bc72b620c747ce107acdfeade699967e38568
shell.md: b9f8e3aebb69348ea241be93d6fd5559068c4029
shell.zh.md: 1ea086819f3badc92376d39cb13e584da772572b

2
docs/subsystems/shell.md
View File

@@ -2,7 +2,7 @@
English | [中文](shell.zh.md)
The bash execution seam is split across a Service Definition ([dsh-shell](../../packages/shell/shell), `ctx.shell`), Service providers ([dsh-bash-local](../../packages/shell/bash-local) and [dsh-bash-sandbox](../../packages/shell/bash-sandbox)), and Consumer ([dsh-tool-bash](../../packages/shell/tool-bash), the `bash` schema). Generic background-job ids, ownership, and controls live in [jobs.md](jobs.md); this seam returns a task-free process handle. Raw process-group mechanics live behind the [subprocess seam](subprocess.md).
The bash execution seam is split across a Service Definition ([dsh-shell](../../packages/shell/shell), `ctx.shell`), Service Providers ([dsh-bash-local](../../packages/shell/bash-local) and [dsh-bash-sandbox](../../packages/shell/bash-sandbox)), and Consumer ([dsh-tool-bash](../../packages/shell/tool-bash), the `bash` schema). Generic background-job ids, ownership, and controls live in [jobs.md](jobs.md); this seam returns a task-free process handle. Raw process-group mechanics live behind the [subprocess seam](subprocess.md).
Source: [`packages/shell/shell/src/types.ts`](../../packages/shell/shell/src/types.ts)

2
docs/subsystems/shell.zh.md
View File

@@ -2,7 +2,7 @@
[English](shell.md) | 中文
bash 执行 seam 分为 Service Definition（[dsh-shell](../../packages/shell/shell)，`ctx.shell`）、Service provider（[dsh-bash-local](../../packages/shell/bash-local) 与 [dsh-bash-sandbox](../../packages/shell/bash-sandbox)）和 Consumer（[dsh-tool-bash](../../packages/shell/tool-bash)，即 `bash` schema）。通用后台任务的 job id、所有权与控制位于 [jobs.md](jobs.md)；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制封装在[子进程 seam](subprocess.md)之后。
bash 执行 seam 分为 Service Definition（[dsh-shell](../../packages/shell/shell)，`ctx.shell`）、Service Provider（[dsh-bash-local](../../packages/shell/bash-local) 与 [dsh-bash-sandbox](../../packages/shell/bash-sandbox)）和 Consumer（[dsh-tool-bash](../../packages/shell/tool-bash)，即 `bash` schema）。通用后台任务的 job id、所有权与控制位于 [jobs.md](jobs.md)；本 seam 返回一个不含任务概念的进程句柄。原始进程组机制封装在[子进程 seam](subprocess.md)之后。
源码：[`packages/shell/shell/src/types.ts`](../../packages/shell/shell/src/types.ts)

4
docs/subsystems/skills.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 docs/subsystems/skills.md
skills.md: 98d5efea0b534e8232aeae03eda3de10259756e3
skills.zh.md: 8a2b03da4b7bab0a3142eab3cc07f66f379dfd28
skills.md: cd935692c00f89544dc324b33e847d8d588b78a8
skills.zh.md: f574db048e1850ee425309fe015cd21a075eefc6

2
docs/subsystems/skills.md
View File

@@ -2,7 +2,7 @@
English | [中文](skills.zh.md)
The [skill capability family](../../packages/skill) includes the Service Definition ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local Service provider ([dsh-skill-filesystem](../../packages/skill/skill-filesystem)), the optional packaged badge provider ([dsh-skill-badge](../../packages/skill/skill-badge)), and the Consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs across its host and per-scope layers; providers contribute local or packaged skills; the Consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
The [skill capability family](../../packages/skill) includes the Service Definition ([dsh-skill](../../packages/skill/skill), `ctx.skills`), the local Service Provider ([dsh-skill-filesystem](../../packages/skill/skill-filesystem)), the optional packaged badge provider ([dsh-skill-badge](../../packages/skill/skill-badge)), and the Consumer ([dsh-tool-skill](../../packages/skill/tool-skill)). The registry merges provider catalogs across its host and per-scope layers; providers contribute local or packaged skills; the Consumer owns the initial and replacement catalogs plus the model-facing `skill` tool. Skills are optional instructions, not session events, so their vocabulary lives here rather than in [core.md](core.md).
Source: [`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts), [`packages/skill/skill-filesystem/src/index.ts`](../../packages/skill/skill-filesystem/src/index.ts), [`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts), and [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts).

2
docs/subsystems/skills.zh.md
View File

@@ -2,7 +2,7 @@
[English](skills.md) | 中文
[skill（技能）能力族](../../packages/skill) 包含 Service Definition（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）、本地 Service provider（[dsh-skill-filesystem](../../packages/skill/skill-filesystem)）、可选的随包徽章提供方（[dsh-skill-badge](../../packages/skill/skill-badge)）和 Consumer（[dsh-tool-skill](../../packages/skill/tool-skill)）。注册表在其宿主层与各 scope 层之间合并各提供方的目录；提供方贡献本地或随包 skill；Consumer 拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
[skill（技能）能力族](../../packages/skill) 包含 Service Definition（[dsh-skill](../../packages/skill/skill)，`ctx.skills`）、本地 Service Provider（[dsh-skill-filesystem](../../packages/skill/skill-filesystem)）、可选的随包徽章提供方（[dsh-skill-badge](../../packages/skill/skill-badge)）和 Consumer（[dsh-tool-skill](../../packages/skill/tool-skill)）。注册表在其宿主层与各 scope 层之间合并各提供方的目录；提供方贡献本地或随包 skill；Consumer 拥有初始目录和替换目录，以及面向模型的 `skill` 工具。skill 是可选的指令而非会话事件，因此其词汇定义在此处而非 [core.md](core.md)。
源码：[`packages/skill/skill/src/index.ts`](../../packages/skill/skill/src/index.ts)、[`packages/skill/skill-filesystem/src/index.ts`](../../packages/skill/skill-filesystem/src/index.ts)、[`packages/skill/skill-badge/src/index.ts`](../../packages/skill/skill-badge/src/index.ts) 与 [`packages/skill/tool-skill/src/index.ts`](../../packages/skill/tool-skill/src/index.ts)。

4
docs/subsystems/spill.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 docs/subsystems/spill.md
spill.md: 97d18ca2cf06c2062655eb6b22547280e4ee93e7
spill.zh.md: 32783c748d6097359a7b71950f14ad97ebc924f5
spill.md: ad59e88b1f059d0127bdf48155450890b1bf7c9a
spill.zh.md: 015ff6fc378c21e30f1cd84c985843f8c06cd44a

2
docs/subsystems/spill.md
View File

@@ -2,7 +2,7 @@
English | [中文](spill.zh.md)
The spill storage seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) that persists a tool's oversized text and returns a model-facing locator plus retrieval guidance, split across packages: Service Definition ([dsh-spill](../../packages/spill/spill), `ctx.spillStore`), Service provider ([dsh-spill-local](../../packages/spill/spill-local), private session-scoped files on the host filesystem), and Consumer ([dsh-spill-policy](../../packages/spill/spill-policy), the `tools/post-execute` policy). Spill is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Preview mechanics stay in [dsh-output-retention](../../packages/util/output-retention); this seam only saves the final text the policy hands it.
The spill storage seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) that persists a tool's oversized text and returns a model-facing locator plus retrieval guidance, split across packages: Service Definition ([dsh-spill](../../packages/spill/spill), `ctx.spillStore`), Service Provider ([dsh-spill-local](../../packages/spill/spill-local), private session-scoped files on the host filesystem), and Consumer ([dsh-spill-policy](../../packages/spill/spill-policy), the `tools/post-execute` policy). Spill is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Preview mechanics stay in [dsh-output-retention](../../packages/util/output-retention); this seam only saves the final text the policy hands it.
Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)

2
docs/subsystems/spill.zh.md
View File

@@ -2,7 +2,7 @@
[English](spill.md) | 中文
spill 存储 seam 是一项[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：Service Definition（[dsh-spill](../../packages/spill/spill)，`ctx.spillStore`）、Service provider（[dsh-spill-local](../../packages/spill/spill-local)，宿主文件系统中会话作用域的私有文件）和 Consumer（[dsh-spill-policy](../../packages/spill/spill-policy)，`tools/post-execute` 策略）。spill 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 [core.md](core.md) 中。预览机制仍归 [dsh-output-retention](../../packages/util/output-retention) 所有；该 seam 只保存策略交给它的最终文本。
spill 存储 seam 是一项[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：Service Definition（[dsh-spill](../../packages/spill/spill)，`ctx.spillStore`）、Service Provider（[dsh-spill-local](../../packages/spill/spill-local)，宿主文件系统中会话作用域的私有文件）和 Consumer（[dsh-spill-policy](../../packages/spill/spill-policy)，`tools/post-execute` 策略）。spill 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 [core.md](core.md) 中。预览机制仍归 [dsh-output-retention](../../packages/util/output-retention) 所有；该 seam 只保存策略交给它的最终文本。
源码：[`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)

4
docs/subsystems/storage.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 docs/subsystems/storage.md
storage.md: 33933f70176e1f4960eb423f9a1067f50b6762e4
storage.zh.md: 2ab3473a83b7588f186ce8f3b83819b29985ae88
storage.md: 7e7f8d2b5a98b20308ae8115484a25066c045d52
storage.zh.md: 41d2d1520a846d988c6c7a0b08a7576cee44ff7a

2
docs/subsystems/storage.md
View File

@@ -2,7 +2,7 @@
English | [中文](storage.zh.md)
The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and Service Definition ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the Service providers ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the Consumer data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend contract's only Consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
The storage subsystem persists everything that is not a session event log (session logs have their own seam — [persistence.md](persistence.md)). It is one optional capability, not part of the agent-loop spine, split as a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): the hub and Service Definition ([dsh-storage](../../packages/storage/storage), `ctx.storage`), the Service Providers ([dsh-storage-json](../../packages/storage/storage-json), registered as `json`, and [dsh-storage-sqlite](../../packages/storage/storage-sqlite), registered as `sqlite`), and the Consumer data form ([dsh-storage-domain](../../packages/storage/storage-domain), `ctx.storageDomain`, also reachable as `ctx.storage.domain`) — the backend contract's only Consumer and the typed API everything else uses. The hub performs no IO itself: backends own media, data forms own semantics, and product packages never touch backends directly. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md).
Source: [`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)

2
docs/subsystems/storage.zh.md
View File

@@ -2,7 +2,7 @@
[English](storage.md) | 中文
存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) 拆分：枢纽（hub）与 Service Definition（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、Service provider（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及 Consumer 数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端约定的唯一 Consumer，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
存储子系统持久保存一切不属于会话事件日志的数据（会话日志有自己的 seam——见 [persistence.md](persistence.md)）。它是一项可选能力，不属于 agent loop（智能体循环）主干，并按[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) 拆分：枢纽（hub）与 Service Definition（[dsh-storage](../../packages/storage/storage)，`ctx.storage`）、Service Provider（注册为 `json` 的 [dsh-storage-json](../../packages/storage/storage-json) 与注册为 `sqlite` 的 [dsh-storage-sqlite](../../packages/storage/storage-sqlite)），以及 Consumer 数据形式（[dsh-storage-domain](../../packages/storage/storage-domain)，`ctx.storageDomain`，也可经 `ctx.storage.domain` 访问）——它是后端约定的唯一 Consumer，也是其他一切所使用的类型化 API。枢纽自身不做任何 IO：后端拥有介质，数据形式拥有语义，产品包绝不直接触碰后端。设计记录：[领域 KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
源码：[`packages/storage/storage/src/backend.ts`](../../packages/storage/storage/src/backend.ts) · [`packages/storage/storage-domain/src/spec.ts`](../../packages/storage/storage-domain/src/spec.ts) · [`packages/storage/storage-domain/src/events.ts`](../../packages/storage/storage-domain/src/events.ts)

4
docs/subsystems/subagent.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 docs/subsystems/subagent.md
subagent.md: 4d02c177533e8dbc192d5460b65bb4348f565c41
subagent.zh.md: 483446187dcd2386f0f3d7d50d3fa7b97d09e02c
subagent.md: a683a679e6017351540ee4b73adc74375ef0a1d6
subagent.zh.md: 61391cd297c0eb14f4c0d8eac4539b551cb60bda

2
docs/subsystems/subagent.md
View File

@@ -4,7 +4,7 @@ English | [中文](subagent.zh.md)
The subagent seam lets an agent delegate work to a child agent. Like [bash](shell.md), it is **one optional capability**, not part of the agent loop, so its types live here rather than in [core.md](core.md). It differs from the other capability seams because **multiple provider implementations coexist** in one context, registered by name (`ctx.subagents`), while bash allows only one executor. Its registry follows the [LLM adapter registry](llm-streaming.md), not the single-service bash executor.
Service Definition: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Service providers are sibling packages (`dsh-subagent-spawn-in-process`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing Consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
Service Definition: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Service Providers are sibling packages (`dsh-subagent-spawn-in-process`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing Consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message`, `interrupt_agent`, and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only child and descendant discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)

2
docs/subsystems/subagent.zh.md
View File

@@ -4,7 +4,7 @@
subagent seam 让一个 agent（智能体）将工作委派给子 agent。与 [bash](shell.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环），因此其类型定义在此而非 [core.md](core.md) 中。它不同于其他能力 seam，因为**同一上下文中可共存多个提供方实现**，并按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。该注册表遵循 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
Service Definition：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。Service provider 是六个兄弟包：`dsh-subagent-spawn-in-process`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的 Consumer 包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
Service Definition：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。Service Provider 是六个兄弟包：`dsh-subagent-spawn-in-process`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的 Consumer 包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message`、`interrupt_agent` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接基于会话存储和可选的会话持久化提供只读的 child 与后代发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)

4
docs/subsystems/subprocess.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 docs/subsystems/subprocess.md
subprocess.md: 3cc6e33ce2befc6bc65e258507881df542b7c149
subprocess.zh.md: 1189ceb0526418ee92e0da280e118c10991508d5
subprocess.md: af6770e8c04f79ab1981967d5a3bca5a39b954be
subprocess.zh.md: 19f20e7fcd675d87cf768258d1ab9c37bf80a836

2
docs/subsystems/subprocess.md
View File

@@ -2,7 +2,7 @@
English | [中文](subprocess.zh.md)
The subprocess seam is split across a Service Definition ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and Service provider ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its Consumers are other capability seams and out-of-process backends: the [bash executor family](shell.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-shell](../../packages/shell/shell) re-exports the vocabulary so bash consumers keep one import root.
The subprocess seam is split across a Service Definition ([dsh-subprocess](../../packages/subprocess/subprocess), `ctx.subprocess`) and Service Provider ([dsh-subprocess-local](../../packages/subprocess/subprocess-local)); its Consumers are other capability seams and out-of-process backends: the [bash executor family](shell.md) uses collected batch output, LSP uses raw protocol pipes, the PTY backend uses the terminal primitive, and the ACP subagent backend uses piped ndjson plus inherited stderr. This seam owns the managed `DSH_*` environment namespace, the shared credential scrub (`scrubbedParentEnv`), and the `CollectedOutput` shape; [dsh-shell](../../packages/shell/shell) re-exports the vocabulary so bash consumers keep one import root.
Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) and [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)

2
docs/subsystems/subprocess.zh.md
View File

@@ -2,7 +2,7 @@
[English](subprocess.md) | 中文
子进程 seam 分为 Service Definition（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与 Service provider（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的 Consumer 是其他能力 seam 与进程外后端：[bash 执行器家族](shell.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用通过管道传输的 ndjson，并让 stderr 采用 inherit。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-shell](../../packages/shell/shell) 重导出这套词汇，使 bash 消费方保持单一导入入口。
子进程 seam 分为 Service Definition（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与 Service Provider（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的 Consumer 是其他能力 seam 与进程外后端：[bash 执行器家族](shell.md)使用收集模式的批量输出，LSP 使用原始协议管道，PTY 后端使用终端原语，ACP（Agent Client Protocol）subagent 后端则使用通过管道传输的 ndjson，并让 stderr 采用 inherit。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-shell](../../packages/shell/shell) 重导出这套词汇，使 bash 消费方保持单一导入入口。
源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts) 与 [`packages/subprocess/subprocess/src/index.ts`](../../packages/subprocess/subprocess/src/index.ts)

4
docs/subsystems/system-prompt.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 docs/subsystems/system-prompt.md
system-prompt.md: f03d11866bcdcf3bcb5c5fe96931b059cb8d0336
system-prompt.zh.md: 23b3e0b20cc4772baf22727d2e57866aa7cbbeb0
system-prompt.md: 8a6006d0b96552b52d0b050c304a11a95add8d9e
system-prompt.zh.md: 02be9eed795d3a6c8e43403048f135d493b6509d

10
docs/subsystems/system-prompt.md
View File

@@ -117,6 +117,14 @@ section(section: PromptSection): () => void
*/
context(context: PromptContext): () => void
/**
* Suppress every dynamic runtime-context contribution in the calling
* context's scope without changing the services that own or enforce those
* facts. Multiple suppressors remain independently disposable.
* @returns the exact Cordis effect disposer.
*/
suppressRuntimeContext(): () => void
/**
* Register a tool-schema provider in the calling context's scope. Global and
* matching scoped providers both contribute; returning the reserved
@@ -148,7 +156,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
```
Source: [`packages/core/system-prompt/src/index.ts:334`](../../packages/core/system-prompt/src/index.ts)
Source: [`packages/core/system-prompt/src/index.ts:338`](../../packages/core/system-prompt/src/index.ts)
<a id="system-prompt-events"></a>

10
docs/subsystems/system-prompt.zh.md
View File

@@ -117,6 +117,14 @@ section(section: PromptSection): () => void
*/
context(context: PromptContext): () => void
/**
* Suppress every dynamic runtime-context contribution in the calling
* context's scope without changing the services that own or enforce those
* facts. Multiple suppressors remain independently disposable.
* @returns the exact Cordis effect disposer.
*/
suppressRuntimeContext(): () => void
/**
* Register a tool-schema provider in the calling context's scope. Global and
* matching scoped providers both contribute; returning the reserved
@@ -148,7 +156,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
```
Source: [`packages/core/system-prompt/src/index.ts:334`](../../packages/core/system-prompt/src/index.ts)
Source: [`packages/core/system-prompt/src/index.ts:338`](../../packages/core/system-prompt/src/index.ts)
<a id="system-prompt-events"></a>

4
docs/subsystems/web.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 docs/subsystems/web.md
web.md: 741df8d92c20817cb3115dafffba7c7be9205aec
web.zh.md: 0cce8500834896c156ff85d935b9e80853a3196c
web.md: 3bcd3ac24927c8c51baeabd770e2bd91c5ad1b77
web.zh.md: 3348be2b808dc286364f5a795b236cb299acd6a6

2
docs/subsystems/web.md
View File

@@ -2,7 +2,7 @@
English | [中文](web.zh.md)
The web access seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two operations** (search and fetch) on one `ctx.web` service, split across packages: Service Definition ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), Service providers ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-http](../../packages/web/web-fetch-http)), and Consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-provider swap does not change how the model asks for a URL.
The web access seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) that spans **two operations** (search and fetch) on one `ctx.web` service, split across packages: Service Definition ([dsh-web](../../packages/web/web), `ctx.web` + the provider registries), Service Providers ([dsh-web-search-exa](../../packages/web/web-search-exa), [dsh-web-search-perplexity](../../packages/web/web-search-perplexity), [dsh-web-search-deepseek](../../packages/web/web-search-deepseek), [dsh-web-fetch-http](../../packages/web/web-fetch-http)), and Consumer ([dsh-tool-web](../../packages/web/tool-web), the `web_search`/`web_fetch` tool schemas). Web is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A search-provider swap does not change how the model asks for a query, and a fetch-provider swap does not change how the model asks for a URL.
Source: [`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)

2
docs/subsystems/web.zh.md
View File

@@ -2,7 +2,7 @@
[English](web.md) | 中文
Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项操作**（search 与 fetch），并拆分到多个包：Service Definition（[dsh-web](../../packages/web/web)，`ctx.web` + 提供方注册表）、Service provider（[dsh-web-search-exa](../../packages/web/web-search-exa)、[dsh-web-search-perplexity](../../packages/web/web-search-perplexity)、[dsh-web-search-deepseek](../../packages/web/web-search-deepseek)、[dsh-web-fetch-http](../../packages/web/web-fetch-http)）与 Consumer（[dsh-tool-web](../../packages/web/tool-web)，即 `web_search`/`web_fetch` 工具 schema）。Web 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 提供方也不会改变模型请求 URL 的方式。
Web 访问 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)，在同一个 `ctx.web` 服务上横跨**两项操作**（search 与 fetch），并拆分到多个包：Service Definition（[dsh-web](../../packages/web/web)，`ctx.web` + 提供方注册表）、Service Provider（[dsh-web-search-exa](../../packages/web/web-search-exa)、[dsh-web-search-perplexity](../../packages/web/web-search-perplexity)、[dsh-web-search-deepseek](../../packages/web/web-search-deepseek)、[dsh-web-fetch-http](../../packages/web/web-fetch-http)）与 Consumer（[dsh-tool-web](../../packages/web/tool-web)，即 `web_search`/`web_fetch` 工具 schema）。Web 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。更换 search 提供方不会改变模型提交查询的方式，更换 fetch 提供方也不会改变模型请求 URL 的方式。
源码：[`packages/web/web/src/types.ts`](../../packages/web/web/src/types.ts)

4
docs/subsystems/workflow.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 docs/subsystems/workflow.md
workflow.md: bf11ec3a40f9c964fbc535a0368b30e422b5452e
workflow.zh.md: b87bffd4780d167b4106276bfbca53e48ef6d833
workflow.md: f2c987fbc2ca3a334c55bf0b299764e2b3e6bb06
workflow.zh.md: b4e6e6afe73b20f1da39c1548c072cf7aeb1f441

2
docs/subsystems/workflow.md
View File

@@ -4,7 +4,7 @@ English | [中文](workflow.zh.md)
The workflow seam lets an agent run a model-written orchestration SCRIPT that starts subagents. Like [subagent](subagent.md) it is **one optional capability**, not part of the agent loop, so its types and operations live here rather than in [core.md](core.md). Like bash, it permits ONE engine implementation per context to provide `ctx.workflowEngine`; there is no named-provider registry (a second engine replaces the first through plugin configuration rather than running beside it).
Service Definition: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflowEngine` + the vocabulary below). The Service provider is [dsh-workflow-worker-thread](../../packages/workflow/workflow-worker-thread) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing Consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md).
Service Definition: [dsh-workflow](../../packages/workflow/workflow) (`ctx.workflowEngine` + the vocabulary below). The Service Provider is [dsh-workflow-worker-thread](../../packages/workflow/workflow-worker-thread) (a `node:worker_threads` engine — one worker per run, the script's vm context inside it); the model-facing Consumer is [dsh-tool-workflow](../../packages/workflow/tool-workflow). The proposal and rationale: [the dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md).
Sources: browser-safe vocabulary in [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts), Host request and live-run handles in [`runtime-types.ts`](../../packages/workflow/workflow/src/runtime-types.ts).

2
docs/subsystems/workflow.zh.md
View File

@@ -4,7 +4,7 @@
工作流 seam 允许 agent（智能体）运行由模型编写、会启动 subagent 的编排脚本。与 [subagent](subagent.md) 一样，它是**一项可选能力**，不属于 agent loop，因此其类型和操作记录在此处，而非 [core.md](core.md)。与 bash 一样，每个上下文只允许一个引擎实现提供 `ctx.workflowEngine`；没有命名提供方注册表（第二个引擎通过插件配置替换第一个，而不与它同时运行）。
Service Definition：[dsh-workflow](../../packages/workflow/workflow)（`ctx.workflowEngine` + 下文词汇）。Service provider 是 [dsh-workflow-worker-thread](../../packages/workflow/workflow-worker-thread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的 Consumer 是 [dsh-tool-workflow](../../packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
Service Definition：[dsh-workflow](../../packages/workflow/workflow)（`ctx.workflowEngine` + 下文词汇）。Service Provider 是 [dsh-workflow-worker-thread](../../packages/workflow/workflow-worker-thread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的 Consumer 是 [dsh-tool-workflow](../../packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
源码：浏览器安全词汇位于 [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts)，Host 请求与活跃运行句柄位于 [`runtime-types.ts`](../../packages/workflow/workflow/src/runtime-types.ts)。

4
docs/tool-catalog.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 docs/tool-catalog.md
tool-catalog.md: ea89508500ec6e73e6e56c4e5d0ac2c35897b342
tool-catalog.zh.md: 076cc63151e3b9ee8b3828ded65df9ebf09c9430
tool-catalog.md: 50563c97c6cd5496871ea7fa52c4823a56b088fd
tool-catalog.zh.md: ed0c7e3f70cffbecd3d20a1556bcb0cd4204df00

50
docs/tool-catalog.md
View File

@@ -40,6 +40,8 @@ This table connects model-visible tool names to the plugin package and service s
| `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflowEngine`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - |
| `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. |
<a id="deepseek-aidsh-tool-ask-user"></a>
## `@deepseek-ai/dsh-tool-ask-user`
### `ask_user_question`
@@ -112,11 +114,13 @@ Source: [`packages/interaction/tool-ask-user/src/index.ts`](../packages/interact
ask_user_question pauses the tool call until the active UI provider returns a human answer.
<a id="deepseek-aidsh-tools"></a>
## `@deepseek-ai/dsh-tools`
### `run_code`
Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.
Execute a TypeScript program against the available tools. Takes two required arguments: `code`, the BODY of an async function (erasable syntax only; top-level `await` and `return` work), and `description`, a short summary of what the program does. Call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.
```json
{
@@ -142,6 +146,8 @@ Source: [`packages/core/tools/src/code-mode.ts`](../packages/core/tools/src/code
Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry's only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime's language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.
<a id="deepseek-aidsh-plan-mode"></a>
## `@deepseek-ai/dsh-plan-mode`
### `exit_plan_mode`
@@ -167,6 +173,8 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../packages/plan/plan-mode/src/
exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-questions seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary.
<a id="deepseek-aidsh-tool-bash"></a>
## `@deepseek-ai/dsh-tool-bash`
### `bash`
@@ -209,6 +217,8 @@ Source: [`packages/shell/tool-bash/src/index.ts`](../packages/shell/tool-bash/sr
The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.jobs` runtime and is collected/stopped through the `job_*` tools from `@deepseek-ai/dsh-tool-jobs`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled.
<a id="deepseek-aidsh-tool-pwsh"></a>
## `@deepseek-ai/dsh-tool-pwsh`
### `pwsh`
@@ -251,6 +261,8 @@ Source: [`packages/shell/tool-pwsh/src/index.ts`](../packages/shell/tool-pwsh/sr
The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.shell`); it mirrors the bash tool call-for-call minus sandbox controls — `run_in_background` runs register with the generic `ctx.jobs` runtime and are collected/stopped through the `job_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-shell-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\...` paths and `$env:NAME` variables.
<a id="deepseek-aidsh-tool-cordis"></a>
## `@deepseek-ai/dsh-tool-cordis`
### `cordis_define`
@@ -487,6 +499,8 @@ Source: [`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/
Not in any shipped tree (a deliberate opt-in — dynamic package code reaches the real runtime, see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). The toolset injects `ctx.dynamicCordisRunner` from `@deepseek-ai/dsh-cordis-host-runner`, which owns the definition registry and the vm sandbox; a composition missing it never activates the tools. A running package may register ADDITIONAL model-visible tools until it is stopped, undefined, or DSH restarts; a full changed request header logs those tool-set changes.
<a id="deepseek-aidsh-tool-bash-persistent"></a>
## `@deepseek-ai/dsh-tool-bash-persistent`
### `bash`
@@ -512,6 +526,8 @@ Source: [`packages/shell/tool-bash-persistent/src/index.ts`](../packages/shell/t
One owner-isolated persistent bash tool; deployment composition supplies the PTY backend and may override the model-facing environment description.
<a id="deepseek-aidsh-tool-str-replace-editor"></a>
## `@deepseek-ai/dsh-tool-str-replace-editor`
### `str_replace_editor`
@@ -580,6 +596,8 @@ Source: [`packages/fs/tool-str-replace-editor/src/index.ts`](../packages/fs/tool
Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal API.
<a id="deepseek-aidsh-tool-fs"></a>
## `@deepseek-ai/dsh-tool-fs`
### `edit`
@@ -695,6 +713,8 @@ Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts
The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-observation-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. `read_image` is not registered without `ctx.attachments`; its schema is route-independent, and execution refuses unless the exact routed model declares image input.
<a id="deepseek-aidsh-tool-fs-search"></a>
## `@deepseek-ai/dsh-tool-fs-search`
### `glob`
@@ -753,6 +773,8 @@ Source: [`packages/fs/tool-fs-search/src/index.ts`](../packages/fs/tool-fs-searc
glob and grep are unconditional discovery tools that spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess as ordinary foreground calls (never background jobs) — no host `rg` install and no shell layer. The catalog uses `sampleOverCapGlobResults: true`; deployments must choose that behavior explicitly. Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments.
<a id="deepseek-aidsh-tool-terminal"></a>
## `@deepseek-ai/dsh-tool-terminal`
### `terminal_close`
@@ -916,6 +938,8 @@ Source: [`packages/terminal/tool-terminal/src/index.ts`](../packages/terminal/to
The six terminal tools are opt-in and complement one-shot shell/filesystem tools. `terminal_send(run_in_background: true)` registers with `ctx.jobs`; TUI, named key sequences, BEL, resize, auto-start, and cross-agent sharing are absent from the schema.
<a id="deepseek-aidsh-tool-goal"></a>
## `@deepseek-ai/dsh-tool-goal`
### `create_goal`
@@ -1008,6 +1032,8 @@ Source: [`packages/goal/tool-goal/src/index.ts`](../packages/goal/tool-goal/src/
create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds.
<a id="deepseek-aidsh-schedule"></a>
## `@deepseek-ai/dsh-schedule`
### `schedule_create`
@@ -1103,6 +1129,8 @@ Source: [`packages/schedule/schedule/src/tools.ts`](../packages/schedule/schedul
Registered only inside live root Agent scopes created after the opt-in Schedule plugin loads. Version 1 accepts after_seconds, explicit absolute at, and bounded fixed-rate every_seconds, and discloses session-local delivery; management reads and mutations require the shared Session persistence barrier.
<a id="deepseek-aidsh-tool-lsp"></a>
## `@deepseek-ai/dsh-tool-lsp`
### `lsp`
@@ -1149,6 +1177,8 @@ Source: [`packages/lsp/tool-lsp/src/index.ts`](../packages/lsp/tool-lsp/src/inde
The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-stdio`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema.
<a id="deepseek-aidsh-tool-ralph"></a>
## `@deepseek-ai/dsh-tool-ralph`
### `ralph`
@@ -1178,6 +1208,8 @@ Source: [`packages/workflow/tool-ralph/src/index.ts`](../packages/workflow/tool-
A fixed foreground workflow starts one fresh structured child per round; the model selects only the immutable objective and an optional round cap.
<a id="deepseek-aidsh-tool-skill"></a>
## `@deepseek-ai/dsh-tool-skill`
### `skill`
@@ -1201,6 +1233,8 @@ Load the full instructions for an available skill. Call this with the exact skil
Source: [`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/src/index.ts)
<a id="deepseek-aidsh-tool-session-query"></a>
## `@deepseek-ai/dsh-tool-session-query`
### `session_event_read`
@@ -1434,6 +1468,8 @@ Source: [`packages/session-query/tool-session-query/src/index.ts`](../packages/s
The five read-only tools hide provider cursors and authorize every result from the immutable calling agent session. The package is opt-in; compositions that need enforced deadlines or bounded inline output also mount the generic timeout or spill policies.
<a id="deepseek-aidsh-tool-subagent"></a>
## `@deepseek-ai/dsh-tool-subagent`
### `subagent`
@@ -1468,6 +1504,8 @@ Source: [`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/to
The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped compositions load this package once per subagent backend, so the model additionally sees `subagent_fork` bound to the fork backend. Each instance's description, `run_in_background` parameter, and system-prompt policy follow its own `backgroundMode` and `enableRunInBackground`, so the two shipped schemas are not identical: `subagent` is `continuable` and defaults omitted calls to background with automatic settlement delivery, while `subagent_fork` stays `one-shot` and defaults them to foreground — see `packages/bundle/base/cordis.patch.yml` and `examples/acp-agent/cordis.yml`.
<a id="deepseek-aidsh-tool-subagent-control"></a>
## `@deepseek-ai/dsh-tool-subagent-control`
### `interrupt_agent`
@@ -1541,6 +1579,8 @@ Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/sub
The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries).
<a id="deepseek-aidsh-tool-subagent-report"></a>
## `@deepseek-ai/dsh-tool-subagent-report`
### `report`
@@ -1566,6 +1606,8 @@ Source: [`packages/subagent/tool-subagent-report/src/index.ts`](../packages/suba
Registered per continuable in-process child rather than globally, so this schema is visible only inside such a child and survives its global `toolFilter`. The same contribution installs the child-scoped `tool:report` prompt section, which this catalog does not render. The parent-facing `send_message` tool is installed independently.
<a id="deepseek-aidsh-tool-jobs"></a>
## `@deepseek-ai/dsh-tool-jobs`
### `job_kill`
@@ -1637,6 +1679,8 @@ Source: [`packages/jobs/tool-jobs/src/index.ts`](../packages/jobs/tool-jobs/src/
The kind-agnostic background-job controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers' `ctx.jobs.start()`.
<a id="deepseek-aidsh-tool-todo"></a>
## `@deepseek-ai/dsh-tool-todo`
### `todo_write`
@@ -1685,6 +1729,8 @@ Source: [`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/
todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task.
<a id="deepseek-aidsh-tool-workflow"></a>
## `@deepseek-ai/dsh-tool-workflow`
### `workflow`
@@ -1778,6 +1824,8 @@ Constraints: concurrency and total-agent caps apply; no filesystem, network, tim
Source: [`packages/workflow/tool-workflow/src/index.ts`](../packages/workflow/tool-workflow/src/index.ts)
<a id="deepseek-aidsh-tool-web"></a>
## `@deepseek-ai/dsh-tool-web`
### `web_fetch`

50
docs/tool-catalog.zh.md
View File

@@ -42,6 +42,8 @@
| `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflowEngine`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - |
| `@deepseek-ai/dsh-tool-web` | `web_fetch`、`web_search` | `ctx.tools`、`ctx.web`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | web_search 和 web_fetch 将提供方选择置于 ctx.web 之后，使模型可见 schema 在更换后端时保持稳定。 |
<a id="deepseek-aidsh-tool-ask-user"></a>
## `@deepseek-ai/dsh-tool-ask-user`
### `ask_user_question`
@@ -114,11 +116,13 @@
ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类答案。
<a id="deepseek-aidsh-tools"></a>
## `@deepseek-ai/dsh-tools`
### `run_code`
针对可用工具执行 TypeScript 程序。请编写异步函数的**函数体**（仅使用可擦除语法；支持顶层 `await` 和 `return`），并根据系统提示词中的声明，以 `await tools.name(args)` 形式调用工具。只有打印或返回的内容会传回，请谨慎筛选。
针对可用工具执行 TypeScript 程序。接受两个必填参数：`code`，即异步函数的**函数体**（仅使用可擦除语法；支持顶层 `await` 和 `return`）；以及 `description`，简要说明该程序做什么。请根据系统提示词中的声明，以 `await tools.name(args)` 形式调用工具。只有打印或返回的内容会传回，请谨慎筛选。
```json
{
@@ -144,6 +148,8 @@ ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类
在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。
<a id="deepseek-aidsh-plan-mode"></a>
## `@deepseek-ai/dsh-plan-mode`
### `exit_plan_mode`
@@ -169,6 +175,8 @@ ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类
规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。
<a id="deepseek-aidsh-tool-bash"></a>
## `@deepseek-ai/dsh-tool-bash`
### `bash`
@@ -211,6 +219,8 @@ ask_user_question 会暂停工具调用，直到当前 UI 提供方返回人类
bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.jobs` 运行时，并通过 `job_*` 工具（来自 `@deepseek-ai/dsh-tool-jobs`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。
<a id="deepseek-aidsh-tool-pwsh"></a>
## `@deepseek-ai/dsh-tool-pwsh`
### `pwsh`
@@ -253,6 +263,8 @@ bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_bac
pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.shell` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.jobs` 运行时，并通过 `job_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-shell-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。
<a id="deepseek-aidsh-tool-cordis"></a>
## `@deepseek-ai/dsh-tool-cordis`
### `cordis_define`
@@ -489,6 +501,8 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
不在任何随产品发布的树中，需要显式选择启用；动态 Package 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。该工具集注入 `@deepseek-ai/dsh-cordis-host-runner` 提供的 `ctx.dynamicCordisRunner`，后者拥有定义注册表和 vm 沙箱；组合缺少它时这些工具不会激活。运行中的 Package 在停止、undefine 或 DSH 重启前可以注册**额外的**模型可见工具；发生这类工具集变化时，系统会记录完整且有变动的请求头。
<a id="deepseek-aidsh-tool-bash-persistent"></a>
## `@deepseek-ai/dsh-tool-bash-persistent`
### `bash`
@@ -514,6 +528,8 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。
<a id="deepseek-aidsh-tool-str-replace-editor"></a>
## `@deepseek-ai/dsh-tool-str-replace-editor`
### `str_replace_editor`
@@ -584,6 +600,8 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。
<a id="deepseek-aidsh-tool-fs"></a>
## `@deepseek-ai/dsh-tool-fs`
### `edit`
@@ -699,6 +717,8 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
先读后写／编辑策略由 `@deepseek-ai/dsh-fs-observation-policy` 添加；它是一个 `fs/*` 事件门禁插件，不会改变 schema。加载这些工具的部署按预期也应加载该插件。没有 `ctx.attachments` 时 `read_image` 不会注册；其 schema 与路由无关，执行时除非确切路由的模型声明图像输入，否则拒绝。
<a id="deepseek-aidsh-tool-fs-search"></a>
## `@deepseek-ai/dsh-tool-fs-search`
### `glob`
@@ -757,6 +777,8 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。
<a id="deepseek-aidsh-tool-terminal"></a>
## `@deepseek-ai/dsh-tool-terminal`
### `terminal_close`
@@ -920,6 +942,8 @@ glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn
这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.jobs`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。
<a id="deepseek-aidsh-tool-goal"></a>
## `@deepseek-ai/dsh-tool-goal`
### `create_goal`
@@ -1012,6 +1036,8 @@ glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn
create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。
<a id="deepseek-aidsh-schedule"></a>
## `@deepseek-ai/dsh-schedule`
### `schedule_create`
@@ -1107,6 +1133,8 @@ create、edit、pause 和 resume 要求直接来自人类的根权限；complete
仅在选择启用的 Schedule 插件加载后创建的 live 根 Agent scope 内注册。版本 1 接受 after_seconds、显式绝对 at 和有界固定速率 every_seconds，并披露 session-local 交付；管理读取与变更必须通过共享的 Session 持久化 barrier。
<a id="deepseek-aidsh-tool-lsp"></a>
## `@deepseek-ai/dsh-tool-lsp`
### `lsp`
@@ -1153,6 +1181,8 @@ create、edit、pause 和 resume 要求直接来自人类的根权限；complete
lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-stdio`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。
<a id="deepseek-aidsh-tool-ralph"></a>
## `@deepseek-ai/dsh-tool-ralph`
### `ralph`
@@ -1182,6 +1212,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。
<a id="deepseek-aidsh-tool-skill"></a>
## `@deepseek-ai/dsh-tool-skill`
### `skill`
@@ -1205,6 +1237,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
来源：[`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/src/index.ts)
<a id="deepseek-aidsh-tool-session-query"></a>
## `@deepseek-ai/dsh-tool-session-query`
### `session_event_read`
@@ -1438,6 +1472,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
这 5 个只读工具会隐藏提供方游标，并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用；需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。
<a id="deepseek-aidsh-tool-subagent"></a>
## `@deepseek-ai/dsh-tool-subagent`
### `subagent`
@@ -1472,6 +1508,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
注册的工具名称取决于加载时 `toolName` 配置（默认为 `subagent`）；上述 schema 对应默认值。随产品发布的组合会为每个 subagent 后端加载一次该包，因此模型还会看到绑定到 fork 后端的 `subagent_fork`。每个实例的描述、`run_in_background` 参数与 system prompt 策略取决于它自己的 `backgroundMode` 和 `enableRunInBackground`，因此两个随附 schema 并不相同：`subagent` 为 `continuable`，省略参数时默认后台运行，并由 runtime 自动投递结束结果；`subagent_fork` 保持 `one-shot`，省略参数时默认前台运行。详见 `packages/bundle/base/cordis.patch.yml` 和 `examples/acp-agent/cordis.yml`。
<a id="deepseek-aidsh-tool-subagent-control"></a>
## `@deepseek-ai/dsh-tool-subagent-control`
### `interrupt_agent`
@@ -1545,6 +1583,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
这些是控制可继续后台 subagent 的全局命名工具：绑定提供方的 `tool-subagent` 实例注册不同的委派工具；本包注册一次 `send_message` 和 `interrupt_agent`，另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供，其目录行使用 sessionProjections 和实时 Agent 注册表。
<a id="deepseek-aidsh-tool-subagent-report"></a>
## `@deepseek-ai/dsh-tool-subagent-report`
### `report`
@@ -1570,6 +1610,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
按可继续的进程内子级注册，而非全局注册，因此该 schema 仅在这种子级内部可见，并且不受其全局 `toolFilter` 影响。同一份贡献还会安装子级作用域的 `tool:report` 系统提示词 section，本目录不渲染该 section。面向父级的 `send_message` 工具单独安装。
<a id="deepseek-aidsh-tool-jobs"></a>
## `@deepseek-ai/dsh-tool-jobs`
### `job_kill`
@@ -1641,6 +1683,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
与任务种类无关的后台任务控制器：后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器，从而启用生产方的 `ctx.jobs.start()`。
<a id="deepseek-aidsh-tool-todo"></a>
## `@deepseek-ai/dsh-tool-todo`
### `todo_write`
@@ -1689,6 +1733,8 @@ lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，
todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项，因此本目录明确选择 `true`，对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具，但描述会要求只能有 1 个活动任务。
<a id="deepseek-aidsh-tool-workflow"></a>
## `@deepseek-ai/dsh-tool-workflow`
### `workflow`
@@ -1783,6 +1829,8 @@ todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为
来源：[`packages/workflow/tool-workflow/src/index.ts`](../packages/workflow/tool-workflow/src/index.ts)
<a id="deepseek-aidsh-tool-web"></a>
## `@deepseek-ai/dsh-tool-web`
### `web_fetch`

4
docs/user/develop/basic/index.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 docs/user/develop/basic/index.md
index.md: 494b7869be6ffdf5767fac260b36b2585305b516
index.zh.md: a55b8e31151c5cfa5445069974be9fa022fea1eb
index.md: 08199624e638aaf4a36b04446c39c228b2af6025
index.zh.md: c45a30d0bfffaf4a6c78303f9ca043c3397c8a08

6
docs/user/develop/basic/index.md
View File

@@ -45,14 +45,16 @@ export function apply(ctx: Context) {
## Register it in cordis.yml
Create `scratch-plugin/cordis.yml` as a Web overlay that inserts the local plugin:
Run `pwd` from the repository root, then create `scratch-plugin/cordis.yml` as a Web overlay that inserts the local plugin. Replace `/absolute/path/to/deepseek-harness` below with the printed path:
```yaml
- insert:
- id: hello
name: './src/my-plugin.ts'
name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
```
The plugin path must be absolute. A patch file contributes configuration but does not change the profile directory from which the loader resolves module paths.
Start the Web UI with that overlay:
```sh

6
docs/user/develop/basic/index.zh.md
View File

@@ -45,14 +45,16 @@ export function apply(ctx: Context) {
## 注册到 cordis.yml
创建 `scratch-plugin/cordis.yml`，作为插入本地插件的 Web 覆盖层：
在仓库根目录运行 `pwd`，然后创建 `scratch-plugin/cordis.yml`，作为插入本地插件的 Web 覆盖层。请将下文的 `/absolute/path/to/deepseek-harness` 替换为命令打印的路径：
```yaml
- insert:
- id: hello
name: './src/my-plugin.ts'
name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
```
插件路径必须是绝对路径。patch 文件只贡献配置，不会改变 loader 解析模块路径时使用的 profile 目录。
使用该覆盖层启动 Web UI：
```sh

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