dsh-plugin-dev-kb 1.6.0 → 1.8.0

package/kb/site/en/reference/tool-execution-pipeline.md

@@ -8,7 +8,7 @@ rawMarkdownPath: "en/reference/tool-execution-pipeline.md"
 
 # Tool Execution Pipeline
 
-This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
+Built-in executors own raw batch parsing, scheduling, cancellation, and Session call/result logging. This graph shows where their shared invocation pipeline applies policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
 
 ```mermaid
 flowchart TD
@@ -25,14 +25,15 @@ flowchart TD
   owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
   project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
   post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
-  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  normalized["Invocation pipeline normalization<br/>pipeline/result snapshot throws become isError"]
   finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
   final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
   context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
   toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
   allResults["Tool batch settled<br/>recorded tool/result events complete"]
   presentResult["UI completed card<br/>presentResult(args, result)"]
-  model --> toolCall
+  executor["Selected ToolExecutor.execute<br/>raw batch, Agent, optional logging step"]
+  model --> executor --> toolCall
   toolCall --> presentCall
   toolCall --> pre
   pre -->|allow| guards
@@ -65,6 +66,6 @@ flowchart TD
   allResults --> context
 ```
 
-Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
+Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The pipeline losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its ordered sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
 
 Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.

package/kb/site/guide/network-proxy.md

@@ -60,7 +60,7 @@ export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
 
 Node 只在进程启动时读取该变量，所以要在运行 `dsh` 之前导出。
 
-**DSH 替你运行的工具遵循同一个代理。** bash 工具里的命令、`git`、`gh`，以及作为子进程启动的 MCP 服务器都会继承这些变量。子进程若本身是 Node 程序，则需 Node 22.21 或更高版本才会遵循；更旧的 Node 会直连。如果你的某个代理变量是 DSH 拒绝的值——比如 SOCKS URL——基于 Node 的工具同样直连而不是起不来，`curl` 与 `git` 则仍会读取那个值。
+**DSH 替你运行的工具遵循同一个代理。** bash 工具里的命令、`git`、`gh`，以及作为子进程启动的 MCP 服务器都会继承这些变量。Node 子程序使用自己安装的运行时：Node 22.21+ 和 Node 24+ 遵循这些变量；更旧的运行时会直连。如果你的某个代理变量是 DSH 拒绝的值——比如 SOCKS URL——基于 Node 的工具同样直连而不是起不来，`curl` 与 `git` 则仍会读取那个值。
 
 **代理 URL 里的密码同样会到达这些工具。** `HTTPS_PROXY=http://alice:s3cret@proxy.example:8080` 就是一个普通环境变量，因此 DSH 运行的每一条命令——包括模型编写的那些——都能读到它，而打印环境的命令会把密码写进被保留的输出。这与该变量在你 shell 里对其他一切程序的行为一致。若这一点重要，请为代理提供一个无需凭据的入口，或改用 URL 之外的方式认证。
 

package/kb/site/guide/plugin-market.md

@@ -3,11 +3,11 @@ editSource: "docs/user/guide/plugin-market.zh.md"
 rawMarkdownPath: "guide/plugin-market.md"
 ---
 
-# 插件市场
+# 插件索引
 
 ## 概述
 
-插件市场是一个 JSON 索引文件，列出可安装的 DSH 组合包（bundle）及其标题、图标、作者和版本。打开实验性的**自定义插件市场**组合包后，可以在插件页的**发现**标签页中浏览市场，并在确认后安装列出的版本。要发布市场，编写或生成一个索引文件，并把它和图标文件一起放到任意静态主机上。
+插件索引是一个 JSON 文件，列出可安装的 DSH 组合包（bundle）及其标题、图标、作者和版本。打开实验性的**自定义插件索引**组合包后，可以在插件页的**发现**标签页中浏览索引，并在确认后安装列出的版本。要发布索引，编写或生成一个索引文件，并把它和图标文件一起放到任意静态主机上。
 
 ## 目录
 
@@ -21,20 +21,20 @@ rawMarkdownPath: "guide/plugin-market.md"
 <a id="turn-on"></a>
 ## 打开「发现」
 
-打开**插件**，点击**实验性插件**旁的**更多**，找到**自定义插件市场**并打开开关。**已安装**旁边会出现**发现**标签页，Creator 模式也会获得只读的 `plugin_market` 工具。关闭该组合包会再次移除这两者。
+打开**插件**，在**实验性插件**下找到**自定义插件索引**并打开开关。**已安装**旁边会出现**发现**标签页，Creator 模式也会获得只读的 `plugin_market` 工具。关闭该组合包会再次移除这两者。
 
-DSH 不内置任何索引源。选择**发现**，点击**添加索引源**，输入一个索引文件的 URL。URL 必须使用 `http:` 或 `https:`，并且不能包含用户名、密码或 `#` 片段。网络路径上的任何人都能修改 `http:` 索引，包括其中列出的安装 spec，因此经由不受你控制的网络访问的市场应使用 `https:`。每个索引源属于当前 profile。
+DSH 不内置任何索引源。选择**发现**，点击**添加索引源**，输入一个索引文件的 URL。URL 必须使用 `http:` 或 `https:`，并且不能包含用户名、密码或 `#` 片段。网络路径上的任何人都能修改 `http:` 索引，包括其中列出的安装 spec，因此经由不受你控制的网络访问的索引应使用 `https:`。每个索引源属于当前 profile。
 
 <a id="browse-and-install"></a>
 ## 浏览和安装
 
-工具栏左侧的市场菜单用于切换索引源，并可打开**管理索引源…**，其中每个索引源显示它最近一次的错误。搜索匹配名称、作者、关键词，以及所有语言的标题、描述、分类和标签，并容忍拼写错误；在你选择其他排序之前，结果按最佳匹配排序。**标签**菜单、分类按钮和**排序**菜单使用市场声明的分类、标签和排序键，**发布时间**按每个插件最新版本的时间排序。
+工具栏左侧的索引菜单用于切换索引源，并可打开**管理索引源…**，其中每个索引源显示它最近一次的错误。搜索匹配名称、作者、关键词，以及所有语言的标题、描述、分类和标签，并容忍拼写错误；在你选择其他排序之前，结果按最佳匹配排序。**标签**菜单、分类按钮和**排序**菜单使用索引声明的分类、标签和排序键，**发布时间**按每个插件最新版本的时间排序。
 
 每张卡片显示插件的推荐版本：与当前运行的 DSH 兼容、且不是预发布版本的最高版本；插件没有列出任何非预发布版本时，则是兼容的最高预发布版本。**安装**会打开确认框，显示该版本的来源：npm 包和注册表，或 Git 仓库、提交和目录。确认后开始常规的插件安装，包括其中的兼容性检查和注册表检查；未经确认不会安装任何内容。
 
 选择卡片会打开插件页面。**版本**列表显示列出的每个版本及其兼容性，并为 DSH 接受的任何版本提供**安装**，包括旧版本和预发布版本。显示**已安装**、**有新版本**或**随 DSH 提供**的卡片会改为打开已安装的组合包。
 
-市场是第三方内容。每个插件的标题、描述、图标、作者和来源都由市场决定；DSH 检查文件格式，但不验证这些声明。只添加你信任的索引源，并在安装前核对确认框中的来源。
+索引是第三方内容。每个插件的标题、描述、图标、作者和来源都由索引决定；DSH 检查文件格式，但不验证这些声明。只添加你信任的索引源，并在安装前核对确认框中的来源。
 
 <a id="publish-an-index"></a>
 ## 发布索引
@@ -100,7 +100,7 @@ https://gitlab.example.com/team/dsh-plugins
 pnpm --filter @deepseek-ai/dsh-plugin-market-generator start --input plugins.txt --output site/index.json --title "Team plugins"
 ```
 
-对于 npm 包，索引列出所有未弃用且声明了 `dsh.bundle` 的版本。对于 Git 仓库，生成器在默认分支上查找组合包，列出它们在 `vX.Y.Z`、`X.Y.Z` 和 `<name>@X.Y.Z` 标签处的版本，以及每个包在默认分支上的版本。标题、描述、图标、作者和主页取自每个插件的最高版本。路径相对于你运行 pnpm 的目录。
+对于 npm 包，索引列出所有未弃用、未设为私有且声明了 `dsh.bundle` 的版本。对于 Git 仓库，生成器在默认分支上查找 `package.json` 没有设置 `"private": true` 的组合包，列出它们在 `vX.Y.Z`、`X.Y.Z` 和 `<name>@X.Y.Z` 标签处的版本，以及每个包在默认分支上的版本。标题、描述、图标、作者和主页取自每个插件的最高版本。路径相对于你运行 pnpm 的目录。
 
 生成器只下载和读取文件，从不安装包或运行其代码。它在列表旁的 `.plugin-market-cache` 中保存缓存，因此再次运行时只下载新的版本和提交。按上文所述发布输出目录，即 `index.json` 及其 `icons/` 目录。
 
@@ -112,10 +112,10 @@ pnpm --filter @deepseek-ai/dsh-plugin-market-generator start --input plugins.txt
 | 索引字段 | 必填 | 含义 |
 |---|---|---|
 | `format` | 是 | `1`。 |
-| `title`、`description` | 仅 `title` | 市场名称和描述，类型为 `LocalizedText`。 |
+| `title`、`description` | 仅 `title` | 索引名称和描述，类型为 `LocalizedText`。 |
 | `metadata.categories`、`metadata.labels` | 否 | 将 id 映射为 `{ "title": LocalizedText }` 的对象。 |
 | `metadata.sortKeys` | 否 | 将 id 映射为 `{ "title": LocalizedText, "order": "asc" \| "desc" }` 的对象；`order` 是初始方向。 |
-| `plugins` | 是 | 按市场默认顺序排列的插件。 |
+| `plugins` | 是 | 按索引默认顺序排列的插件。 |
 
 | 插件字段 | 必填 | 含义 |
 |---|---|---|
@@ -143,7 +143,7 @@ DSH 将 npm 版本安装为 `name@version`，存在 `registry` 时先询问它
 ## 延伸阅读
 
 - [「发现」标签页参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-plugin-market/README.zh.md)说明该标签页的控件和状态。
-- [插件市场服务](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-market/README.zh.md)说明获取限制、缓存和 `plugin_market` 工具。
+- [插件索引服务](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-market/README.zh.md)说明获取限制、缓存和 `plugin_market` 工具。
 - [索引校验器](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/util/plugin-market-index/README.zh.md)是生成器可以用来在发布前检查索引的库。
 
 ## 开发备注

package/kb/site/guide/providers.md

@@ -15,6 +15,8 @@ rawMarkdownPath: "guide/providers.md"
 
 密钥是只写的。保存后，页面只会收到脱敏描述符，永远不会收到明文密钥。密钥存储在 `$DSH_HOME/.credentials.yaml` 中，settings 只保留它的凭据引用。
 
+保存了密钥且使用默认端点时，DeepSeek 的模型跟随 DeepSeek API 发布的列表。第一次需要模型时加载列表，使用期间约每十分钟在后台刷新一次，无法加载时退回内置模型。在**自定义设置**里编辑**模型目录**会改用你自己的列表，不再跟随发布的列表；点**恢复默认模型**会重新跟随并重新加载。使用发布的列表时，卡片上显示的是内置模型，因此新发布的模型只出现在模型选择器中。列表、兜底和门控规则见 [API key 提供方参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-deepseek-api-key/README.zh.md)。
+
 ## 添加第三方提供商
 
 选择**添加模型提供商**。卡片默认打开在**第三方模型提供商**：选取 dsh 自带的提供商——列表显示的是提供商 id，例如 `anthropic`、`openai`、Kimi 对应的 `moonshotai`、GLM 对应的 `zai`——输入其 API 密钥并保存。已安装目录会提供端点、协议和模型列表。
@@ -35,7 +37,7 @@ Provider ID 是永久的，因为请求、已保存会话、模型默认值和
 
 ### 探测模型
 
-在**模型目录**中选择**获取可用模型**，即可询问端点它提供哪些模型。请求使用表单当前的 API 地址、协议和密钥，已保存的提供商则用已存储的密钥；响应会打开一个可搜索的选择框，搜索、勾选想要的模型，再点**添加所选**。保存或创建提供商之前不会存储任何内容。
+在**模型目录**中选择**获取可用模型**，即可询问端点它提供哪些模型。请求使用表单当前的 API 地址、协议和密钥，已保存的提供商则用已存储的密钥；响应会打开一个可搜索的选择框，列表中已有的模型默认勾选，搜索后勾选要添加的模型、取消勾选要移除的模型，再点**更新列表**。端点未列出的已配置模型保持不变。保存或创建提供商之前不会存储任何内容。
 
 探测读取的是常见网关公开的列表格式，但并非每个端点都用这些格式作答，所以它只是便利手段而非保证：探测失败或列表为空时，手动添加模型 ID 即可，效果完全一样。内置提供商一律由已安装目录作答，即使其 API 地址指向网关也是如此，要查看网关实际提供的模型，请通过自定义提供商探测。
 
@@ -43,6 +45,8 @@ Provider ID 是永久的，因为请求、已保存会话、模型默认值和
 
 已配置的提供商会出现在模型选择器中。选择模型也会将其设为新会话的默认值。已发送过请求的会话会保留自身日志中记录的模型。
 
+在**设置 → 模型**中编辑提供商，打开**自定义设置**，再拖动模型的三横线手柄，即可调整该提供商内的模型顺序。也可以聚焦手柄后按上下方向键。保存会保留顺序；取消会放弃修改。模型选择器会按该提供商保存的顺序列出模型。
+
 如果已保存默认值指向已删除的提供商，输入框会显示**选择模型**，并在选择其他模型前阻止输入。
 
 ## 进阶配置

package/kb/site/guide/python-sdk.md

@@ -94,7 +94,7 @@ python python/sdk/examples/minimal.py `
 
 :::
 
-脚本会打印最终 assistant 响应。所选 home 会保存生成的 `sdk-minimal` profile、已安装插件，以及 `sessions/` 下的未压缩 JSONL 会话日志。示例与 SDK 绝不会静默读取 `~/.dsh`。
+脚本会打印最终 assistant 响应或所选 profile 提供的命令结果。所选 home 会保存生成的 `sdk-minimal` profile、已安装插件，以及 `sessions/` 下的未压缩 JSONL 会话日志。示例与 SDK 绝不会静默读取 `~/.dsh`。
 
 ## 在程序中使用 SDK
 
@@ -165,6 +165,21 @@ dsh plugin --profile sdk-minimal add file:C:/work/my-plugin-bundle
 
 构造 `DeepSeekHarness(profile="sdk-minimal", ...)` 时传入 `patches=("/absolute/path/to/editor.patch.yml",)`，或将 patch 写入 `$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml` 以持久保存配置。下次运行时启动后，模型请求会在默认工具之外包含 `str_replace_editor`。本地文件系统后端以运行时工作目录解析相对路径；与极简 shell 一样，它不会将访问限制在该目录内。该 patch 也适用于标准 `sdk` profile。
 
+<a id="enable-team-mode"></a>
+### 启用 Team 模式
+
+使用 Agent Teams 时选择标准 `sdk` profile；`sdk-minimal` 不包含子代理或 Team 服务。将 [Team patch](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/config/examples/team-mode.yml) 保存为 `team-mode.yml`：
+
+```yaml
+- id: agent-team
+  config:
+    defaultEnabled: true
+```
+
+选择 `profile="sdk"`，并在 SDK 的 `patches` 选项中传入其绝对路径。Python 使用 `patches=("/absolute/path/to/team-mode.yml",)`；TypeScript 使用 `patches: ["/absolute/path/to/team-mode.yml"]`。此 patch 替换 `agent-team` 配置项的整个配置，因此自定义 `maxTasks` 限制也应写在同一个映射中。
+
+创建新根 Session，让它创建并列出共享任务。首次模型请求即包含 Team 工具和协作提示词。根会话保存其模式，子代理共享该模式。恢复已有 Session 时保留其模式，即使它被明确关闭或从未启用；修改或移除此 patch 不会覆盖已保存的选择。模式和任务语义参见 [Team 服务参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/team/agent-team/README.zh.md#use-this-package)。
+
 ## 理解极简 profile
 
 | 属性 | 值 |
@@ -179,7 +194,7 @@ dsh plugin --profile sdk-minimal add file:C:/work/my-plugin-bundle
 
 该 profile 的唯一组合包会在空根之上插入完整配置树，且不包含 `dsh-base`，因此基础 profile 以后新增的工具不会隐式出现。它包含 SDK 协议、一个由环境配置的 DeepSeek 适配器、本地执行与持久化；文本文件工具、settings、托管凭据、OTel 遥测、Web 工具、subagent、本地指令发现均不存在。[DeepSeek 会话日志贡献器](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/session/session-log-deepseek/README.zh.md)默认随 DeepSeek 请求上传未接受的日志事件，每次请求最多 `maxBytes`（8 MiB）；在 profile patch 中设置 `session-log-deepseek.enabled: false` 可将其关闭。它固定使用 `danger-full-access`，因此按平台选择的持久 shell 可以修改运行时可见的任何路径；应使用一次性 checkout 或容器。
 
-图片读取需要支持图片输入的路由。自动压缩保留完整 Session 日志；模型与存储影响见[组合包参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/sdk-minimal/README.zh.md)。SDK 提示词文本不会执行 `/compact` 或其他斜杠命令。
+图片读取需要支持图片输入的路由。自动压缩保留完整 Session 日志；模型与存储影响见[组合包参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/sdk-minimal/README.zh.md)。在这个 `sdk-minimal` 组合中，不支持的斜杠输入保持为普通提示词文本。
 
 已安装 wheel 仍会打包完整 `web` profile 与前端产物。如果 Python SDK 部署还需要浏览器应用，请针对显式 `DSH_HOME` 运行 `dsh web`；`web` 是独立 CLI 应用，不能为 Python SDK client 提供服务。
 

package/kb/site/guide/schedule.md

@@ -7,13 +7,13 @@ rawMarkdownPath: "guide/schedule.md"
 
 ## 概述
 
-在对话中创建提醒，再从自动化任务页面查看活动和未运行任务，并修改活动任务的名称、指令和运行时间。每日提醒遵循保存的本地时间与时区；固定速率提醒遵循经过的时间间隔。已投递的一次性任务会保留到显式删除为止。
+在对话中请模型创建、列出、查看、修改、暂停、恢复或删除提醒。每条提醒按其规则重复，并把指令投递到一个现有对话、一个新对话，或在每个发生时点投递到一个新对话。自动化任务页面列出宿主的所有提醒，并可创建、修改、运行、暂停、恢复和删除提醒。已投递的一次性任务会保留到显式删除为止。
 
 ## 目录
 
 - [创建提醒](#create-reminders)
-- [查看和删除任务](#manage-tasks)
-- [修改活动任务](#edit-timing)
+- [查看、运行和删除任务](#manage-tasks)
+- [修改任务](#edit-timing)
 - [时间与投递参考](#timing-and-delivery)
 - [延伸阅读](#further-exploration)
 
@@ -22,59 +22,78 @@ rawMarkdownPath: "guide/schedule.md"
 
 发布的 Web profile 自带宿主 Schedule 服务与自动化任务页面。在请求模型创建提醒前，先配置模型 provider。
 
-`standard`、`cordis` 和 `ptc` preset 声明四个提醒工具与把当前时间和浏览器时区交给模型的时钟上下文，因此这些 preset 提供 `schedule_create`、`schedule_list`、`schedule_update` 和 `schedule_delete`；`minimal` preset 两者都不声明。被委派的子 agent 看不到这四个工具，因为三个 preset 的委派行已将其 deny；即使某个调用仍能到达工具，也会被拒绝。
+`standard`、`cordis` 和 `ptc` preset 声明四个提醒工具与把当前时间和浏览器时区交给模型的时钟上下文，因此这些 preset 提供 `schedule_create`、`schedule_list`、`schedule_view` 和 `schedule_edit`；`minimal` preset 两者都不声明。被委派的 subagent 能看到这四个工具，但每个工具都会拒绝来自被委派 subagent 的调用，因此 subagent 无法读取或修改提醒。
 
-向模型提出创建、列出、修改或删除提醒的请求。模型使用 `schedule_create`、`schedule_list`、`schedule_update` 和 `schedule_delete`（更新原地修改一条提醒，保留其 id 与已保存的投递记录）；「自动化任务」页面的「新建」操作则为创建打开一个新会话，其 composer 已写好该请求。支持正整数秒的一次性延迟、绝对日期时间、至少一分钟的固定间隔、带 IANA 时区的每日本地时间、带 IANA 时区和 ISO 星期（周一 1 至周日 7）的每周本地时间，以及带显式 IANA 时区的五字段 cron 表达式（表达式以规范化形式保存）。
+向模型提出创建、列出、查看、修改、暂停、恢复或删除提醒的请求。模型用 `schedule_create` 创建提醒，用 `schedule_list` 列出所有对话的提醒，用 `schedule_view` 读取一条提醒，用 `schedule_edit` 修改、暂停、恢复或删除一条提醒；修改保留提醒 id 与已保存的投递记录。模型创建的提醒有名称、指令、UTC 或某个 IANA 时区下的开始时间，以及一条 RFC 5545 重复规则，例如每个工作日 09:00 或仅一次。它投递到当前对话、首次投递时创建的一个新对话，或在每次投递时投递到一个新对话；新对话使用当前对话的工作目录与 preset。同一提醒的每次投递都在上一次投递的计划时间或上一次“立即执行”之后至少一分钟；每次投递都打开新对话的提醒改为等待宿主的最小运行间隔，默认为一分钟。延迟的投递（例如宿主重启之后）不会推迟下一次投递。
 
-例如，请求：“每天 Asia/Shanghai 时区 23:00 提醒我查看天气。”打开自动化任务页面并选择刚创建的提醒，检查频率显示的是每日规则和所需时区，而非仅一次。一次性提醒不会在投递后变成重复任务。
+投递创建的对话加入在其工作目录注册的 Workspace，并以提醒名称作为标题。对于每次投递都打开新对话的提醒，标题还写出该提醒规则所用时区下的启动时间，例如 `Weekday digest · 2026-10-12 09:00`。
+
+例如，请求：“每天 Asia/Shanghai 时区 23:00 提醒我查看天气。”回复下方的卡片显示刚创建的提醒的名称和频率；“打开”在右侧栏显示其详情。检查频率是每天 23:00 重复，而非“仅一次”。一次性提醒不会在投递后变成重复任务。提醒删除后，卡片显示“已删除”，且不再打开该提醒。
+
+不经模型创建提醒时，从侧栏打开自动化任务页面，打开“新建”旁的“选择创建方式”，再选择“手动创建”；尚无任务时，“新建自动化任务”打开同一编辑页。已有任务也使用此页面，填写“自动化任务名称”“自动化任务内容”“执行位置”“关联工作区”和“运行时间”。初始运行时间为“仅一次”，时间为浏览器时区下的一小时后，初始执行位置为“新建对话并复用”。“执行位置”提供“新建对话并复用”和“每次新建对话”：前者在首次运行时创建一个对话并在之后沿用，后者在每次运行时创建独立对话，并显示宿主的最小运行间隔。“关联工作区”列出每个已注册的 Workspace 及其目录，并选择新对话使用其目录的 Workspace；初始值为“默认工作区”，未注册默认 Workspace 时为第一个 Workspace。尚无任何 Workspace 时，“关联工作区”显示“未分组”，并使用宿主项目目录。新对话使用默认 preset。“创建”创建该任务并在列表中选中它，“放弃”关闭编辑页而不创建任务。若宿主拒绝该任务，编辑页保留你的输入并说明问题，例如日期和时间必须在未来。
+
+“新建”以及同一菜单中的“在对话中创建”会在当前或最近使用的 Workspace 中打开一个新对话；在其中请模型创建该任务。
 
 <a id="manage-tasks"></a>
-## 查看和删除任务
+## 查看、运行和删除任务
+
+请模型列出提醒，可查看所有对话的提醒，活动提醒在前；也可请模型按 id 显示、暂停、恢复或删除一条提醒。
 
-从侧栏打开自动化任务页面，可跨 Session 查看提醒，而不激活相应对话。按任务已存储的名称、指令或任务所属的内部 Session id 搜索，并用唯一的“全部/已开启/未运行”状态筛选行过滤。Session 行在其 Session 有至少一个活动任务、自身空闲且未归档时显示时钟标识；归档行该格留空，其实时状态只在悬浮卡片中显示。悬停任一带活动任务的 Session 行时，最多列出其中两个任务及其频率，以及设备时区下的下次运行时间与相对时长。已打开 Session 的顶部在有活动提醒时显示仅图标时钟入口：只有一个任务时直接打开其详情，否则列出该 Session 的提醒。
+从侧栏打开自动化任务页面，可跨 Session 查看提醒，而不激活相应对话。按任务名称、指令或任务所属对话的 id 搜索，并用“任务状态”（“全部”“已开启”“已暂停”或“已结束”）过滤。各行按计划时间排列，最早的在前。每行显示任务名称和一行摘要：已暂停或已结束任务的状态、频率，以及已开启任务的“下次计划时间”与其本地时间和相对时间。
 
-选择任务打开“规则”，再选择“任务运行记录”加载最新的 20 条已保存记录。每条已保存记录为一行紧凑信息：时钟图标、任务保存时区下的发生时间（一次性或间隔任务则为浏览器时区），以及保存过的指令。没有保存指令的记录不会用当前指令顶替。“加载更早的记录”增加下一页。记录按保存顺序从新到旧排列，即使时钟回拨也不改变顺序；它们不描述模型执行结果。原会话入口位于详情页签条内，因此在“规则”视图滚动时都保持可见。不带修饰键的左右方向键和 Home/End 可切换已聚焦的页签；不会拦截与 Alt、Ctrl、Meta 或 Shift 的组合。刷新任务会保留当前页签。
+一个 Session 的任务包括投递到该 Session 的任务（对于每次运行都新建对话的任务，以其最近一次运行为准），以及该 Session 的 Agent（智能体）创建或修改过的任务。空闲、未归档且至少有一个活动任务的 Session 行显示时钟标识；归档行该格留空，其实时状态只在悬浮卡片中显示。长时间悬停在带活动任务的 Session 行上时，最多列出其中两个任务及其频率，以及设备时区下的下次运行时间与相对时长。已打开 Session 的顶部在该 Session 有活动任务时显示仅图标的提醒时钟：只有一个任务时，它在右侧栏打开该任务的详情；否则列出这些任务，每行可打开任务详情或删除任务。
 
-记录空态表示查询成功且没有返回已保存记录。加载中、请求失败、任务不存在和较早记录游标无效分别显示不同提示。请求失败或返回任务不存在时，使用“重试加载发送记录”；游标无效时，使用“刷新发送记录”重新加载最新一页。请求失败时，此前加载的记录可能仍会显示，并附有警告。新的最近一次投递会刷新最新一页。离开任务或视图后才到达的响应不会替换当前视图。
+选择任务打开其详情。“规则”显示任务名称、“下次运行”及其本地时间和相对时间（已暂停或已结束的任务显示其状态）、指令、“重复”和“执行位置”；投递到现有对话的任务，“执行位置”显示“当前关联对话”。详情底部显示“关联会话”；对于每次运行都新建对话的任务，显示“最近运行对话”。其按钮在 Session 可用且未归档时打开该对话，否则禁用；首次运行创建对话之前，该条目显示“待创建”。对于投递到现有对话的任务，“规则”会说明该对话已归档、不可用或仍在加载。即使对话无法打开，任务详情与删除操作仍然可用。浏览任务不会取消 Session 归档。
 
-没有已保存历史的任务只能显示已有的最近一次回执，直到新投递增加记录；后续投递不会恢复缺失历史或清除相应提示。未保存的更早记录和指令快照无法恢复，不会用当前指令代替缺失的已保存指令。仅当宿主标记更早记录不可用时，才显示更早历史提示；尚未投递的新任务显示空态，不显示该提示。
+选择“任务运行记录”加载最新的 20 条已保存记录。每条记录显示任务规则所用时区下的发生时间（规则未指定时区时为浏览器时区）、一个在接收该投递的对话可用时打开它的按钮，以及保存过的指令；“展开”完整显示较长的指令。没有保存指令的记录不会用当前指令顶替。“加载更多”增加下一页。记录按保存顺序从新到旧排列，即使时钟回拨也不改变顺序；它们不描述模型执行结果。左右方向键和 Home/End 可切换已聚焦的页签。
 
-活动任务参与调度；未运行任务不会再次安排投递。一次性任务在提醒持久写入对话收件箱后变为未运行；选择所有任务或未运行即可找到它。对话顶部目录和模型 `schedule_list` 仅显示活动提醒，因此从这些视图消失并不表示保留的任务已被删除。
+记录空态表示查询成功且没有返回已保存记录。加载中、请求失败、任务不存在和较早记录游标无效分别显示不同提示。请求失败或返回任务不存在时，使用“重试”；游标无效时，使用“刷新”重新加载最新一页。请求失败时，此前加载的记录可能仍会显示，并附有警告。新的最近一次投递会刷新最新一页。离开任务或视图后才到达的响应不会替换当前视图。
 
-详情页签条内的关联会话入口在元数据就绪、Session 可用且未归档时打开原对话；否则入口禁用并显示原因。即使原 Session 无法打开，任务详情与删除操作仍然可用。浏览任务不会取消 Session 归档。
+保留上限移除了更早的记录时，最后一页提示“更早的运行记录已清理”，“保留规则”说明每个任务保留的记录条数和天数。没有已保存历史的旧任务只显示其最近一次投递，且不含指令，直到新投递增加记录。未保存的更早记录和指令快照无法恢复。
 
-选择删除任务并确认，可停止未来投递并将该任务从列表中移除，包括未运行任务。删除会移除该任务及其已保存的发送记录，因此该任务的已保存历史随之消失。确认删除会关闭发起删除的面板或页签，并在同一个应用级提示里报告结果——已删除，或失败（失败时任务保留、可重试）；删除不会删除原对话，也不会撤回已进入队列的消息。该行会保留到成功查询确认剩余任务为止。查询失败时可通过重试重新加载目录；错误不会被视为查询成功的空结果。
+活动任务参与调度；已暂停和已结束的任务不会再次安排投递。一次性任务在提醒持久写入对话收件箱后结束，重复任务在其规则的最后一个发生时点后结束；在“任务状态”中选择“全部”或“已结束”即可找到已结束的任务。Session 顶部的提醒时钟、Session 行的时钟标识和悬浮卡片只显示活动任务，因此从这些视图消失并不表示任务已被删除。
+
+详情中的“暂停任务”停止活动任务之后的投递，“恢复任务”重新启动已暂停的任务。“自动化任务操作”菜单中的“立即执行”请宿主现在投递一次指令，并保留下次计划运行；已暂停或已结束的任务也可以这样运行。投递到现有对话或一个新对话的任务的一次投递已排队或正在运行时，字段、“保存修改”“暂停任务”“恢复任务”“立即执行”和“删除任务”均禁用，详情说明此任务已排队或执行中，请在会话中管理任务；详情底部的按钮打开该会话。每次运行都创建新对话的任务不会这样禁用；它的各次运行并行继续。一次投递之后，“立即执行”保持禁用，直到该任务的最小投递间隔结束；仅因间隔禁用时，将指针停在“立即执行”上或用键盘移到该项，即可查看它恢复可用的时间。若宿主因上述原因之一拒绝运行，详情会说明该任务已排队、执行中或刚执行过。任务投递到的对话已归档时，“立即执行”同样禁用。若在任务指令仍在对话中等待时停止该对话，指令会保持排队，直到你的下一条消息、该任务的下一次计划运行或“立即执行”使其开始。
+
+从“自动化任务操作”菜单选择“删除任务”并确认，可停止未来投递并将该任务从列表中移除，包括已暂停或已结束的任务。删除会移除该任务及其已保存的发送记录，因此该任务的已保存历史随之消失。确认删除会在同一个应用级提示里报告结果——已删除（同时关闭详情），或失败（失败时任务保留、可重试）；删除不会删除相关对话，也不会撤回已进入其队列的消息。该行会保留到成功查询确认剩余任务为止。查询失败时，“重试”重新加载目录；错误不会被视为查询成功的空结果。
 
 <a id="edit-timing"></a>
-## 修改活动任务
+## 修改任务
+
+请模型修改提醒的名称、指令、重复规则或投递目标，或暂停、恢复提醒；修改保留提醒 id 与已保存的投递记录。
+
+在自动化任务页面选择任务，即可直接修改其“自动化任务名称”“自动化任务内容”“执行位置”“关联工作区”和“运行时间”，包括已暂停或已结束的任务。修改先保存在本地草稿中，直到选择“保存修改”。编辑保留任务 id、最近一次投递回执以及全部已保存的发送记录。规则改变后，已结束的任务重新变为活动，已暂停的任务保持暂停。对于投递到现有对话的任务，“执行位置”显示“当前关联对话”；选择其他选项后，之后的运行会创建各自的对话，“关联工作区”也设为其初始值，与“手动创建”相同。Workspace 保持不变时，任务保留已存储的 preset；改换 Workspace 后使用默认 preset。
 
-在自动化任务页面选择活动任务，打开“规则”，即可修改其名称、指令和运行时间。未运行任务保持只读，修改先保存在本地草稿中，直到选择“保存更改”。编辑保留任务 id、原对话、最近一次投递回执以及全部已保存的发送记录。
+- “仅一次”：“日期”打开月历，“时间”打开“时”“分”“秒”三列，“时区”决定如何解释它们。任务运行一次后结束。
+- “每 N 分钟”和“每 N 小时”：“重复间隔”设置分钟数或小时数，至少为 1。间隔从你保存任务时所在的分钟起算。
+- “每天”：“重复间隔”设置天数，“时间”打开“时”“分”两列。
+- “每周”和“周一至周五”：“重复间隔”设置周数，“星期”选择日子，“时间”打开“时”“分”“秒”三列。“周一至周五”一次选中这五天。
+- “每月”：“重复间隔”设置月数，“每月日期”选择 1 到 31 日中的一天，“时间”打开“时”“分”“秒”三列。某月没有所选日期时，任务在该月最后一天运行。
+- “自定义”：“自定义规则”包含规则文本。其他选项无法重现的规则以“自定义”打开。没有可编辑规则文本的已有任务显示其原频率，并保留该时间规则，直到你保存替代规则。
 
-- Daily 和 Weekly：修改“时间”和“时区”；每周规则还可切换“星期”。时钟行显示整秒，未改动的行在提交时保留已存储的毫秒值，已存储的 IANA 时区保持不变。规则改变后，按下文的夏令时规则选择首个未来时点。
-- Every：选择“每 N 小时”“每 N 分钟”或“每 N 秒”，并按行内标出的单位填写数量；该单位下的最小间隔为 1 小时、1 分钟或 60 秒，提交的间隔为整秒。新间隔从宿主接受保存的时间起算，首个目标为一个新间隔之后。时区不影响这个经过时间间隔。
-- 一次性 After/At：分别修改“日期”“时间”两行以及“时区”。初始时区取记录已存储的时区；记录未保存时区时取本设备时区，初始钟表值在该时区下仍表示同一已存储瞬时。未保存时区的一次性规则会显示一条提示，说明输入的日期时间按所选时区解释。更改时区会保留这些钟表值并改变时点。目标改变后以相同任务 id 保存为 At，不将时区保留为重复规则元数据。
+“时区”先列出最近选择的时区，标出系统时区，并可按 UTC 偏移、IANA 标识或城市搜索。引导式选项和使用独立时区的“自定义”表达式显示此字段；其他“自定义”规则由文本指定时区。
 
-各行只修改本地草稿。“保存更改”会以一次更新提交名称、指令和完整规则；草稿与已存储任务不同时显示保存栏，“取消”恢复已存储的值。“重复”菜单提供每周、周一至周五、每天、每 N 小时、每 N 分钟、每 N 秒、仅一次和自定义（cron），宿主接受其中任何一项，因此一次性 After 可保存为 At。规范化后等价的规则不写入或重设目标：相同的 Every 间隔不会重新起算，未变更的一次性目标保留 After 或 At。保存期间卡片各行禁用。离开卡片不会回滚宿主已开始的写入。
+各字段只修改本地草稿。若任务指向已有会话，执行位置仍提供“当前关联会话”，可撤销目标变更而保留其他修改。编辑期间，详情底部显示“有未保存的修改”以及“放弃”和“保存修改”；“保存修改”以一次更新只提交已修改的字段，“放弃”恢复已存储的值。只有时间规则改变时，保存才会提交新规则。只有实际修改且字段和时间规则有效时，才能“保存修改”。无效的自定义文本保留在草稿中，并显示纠正提示；宿主也会在保存时校验规则。有未保存修改时，先保存或放弃更改，才能暂停、恢复、立即执行或删除。保存进行期间，各字段禁用。离开详情不会回滚宿主已开始的写入。
 
-刷新目录会保留你已修改的字段，其余字段取自已刷新的记录，因此其他字段的并发变化不会被未保存的修改覆盖。输入无效时显示错误并阻止保存。若投递或其他编辑改变了任务，冲突会阻止覆盖该变化；请重试以修改最新规则。更新被接受后刷新目录。更新被拒绝或无法确认与目录加载错误相互区分：应使用“重试”重新加载目录，而不是重复已确认的更新。若更新本身无法确认，应在重试前检查任务。关闭详情或切换任务后才到达的响应不会替换当前视图。
+切换任务或离开页面时保留未保存的草稿。刷新目录会更新未修改的表单；已修改的表单保留全部字段和原版本。若投递或其他编辑改变了任务，详情会在收到新版本后说明任务已在其他位置更新，并禁用“保存修改”。宿主也会在保存时检查版本。“保留修改并复核”保留你改过的名称、内容、时间和目标字段组，其余字段组载入最新值。保存前请复核整份表单；此操作本身不保存。若同一字段组在其他位置也有更改，表单优先保留你的修改。“放弃”用最新存储值替换整份草稿。保存因其他原因失败时，草稿保留，详情提示你重试；对于结果未知的更新，请在重试前检查任务。更新被接受后刷新目录。关闭详情或切换任务后才到达的响应不会替换当前视图。
 
 <a id="timing-and-delivery"></a>
 ## 时间与投递参考
 
-Session 未打开时，提醒仍然保存。宿主运行期间，在提醒到期时恢复原 Session 并排入 follow-up，不中断当前工作。重启后检查存储的任务，投递逾期的一次性提醒，或每条重复任务最近错过的一次。关闭宿主后，调度停止，直到宿主再次启动。同一 Session 的到期重复任务可以共用一条消息。
+Session 未打开时，提醒仍然保存。宿主运行期间，在提醒到期时恢复或创建目标 Session 并排入 follow-up，不中断当前工作。重启后检查存储的任务，投递逾期的一次性提醒，或每条重复任务最近错过的一次。关闭宿主后，调度停止，直到宿主再次启动。同一 Session 的到期重复任务可以共用一条消息。
 
-固定速率提醒在间隔改变前与创建时间对齐；间隔改变后与接受保存的时间对齐。每日提醒则遵循保存的本地时间与 IANA 时区。不存在的每日本地时间或日期会被跳过；重叠时间选择当天较早的一次。绝对时间请求会拒绝不存在的本地时间，并在重叠时选择较早时刻。浏览器提供其时区来解释自然语言请求；显式指定时区可以避免歧义。任务详情在频率文案里保留钟表规则保存的时区，并把每个下一目标显示为设备时区的钟点；一次性任务仅存储 UTC 时点，因此其时间戳使用浏览器时区。
+IANA 时区下的重复规则遵循本地钟表时间：跳过不存在的本地时间，重复出现的本地时间取较早的时刻。已有任务在你保存新规则之前保留其时间规则：固定速率提醒保持与创建时间对齐，每日、每周或 cron 提醒遵循其 IANA 时区下保存的本地时间。浏览器提供其时区来解释自然语言请求；显式指定时区可以避免歧义。自动化任务页面把每个下次运行时间显示为浏览器时区的钟点；规则的时区与浏览器时区不同时，频率文本会标出该时区；未指定时区的规则使用浏览器时区。
 
-已保存的发送记录确认消息已持久化到对话收件箱，不表示模型完成了所请求的工作。收件箱持久化或任务写入失败时，不增加已保存记录。收件箱持久化后崩溃或任务写入失败，可能留下未记入发送记录的已投递消息，并重复投递；不保证恰好投递一次。这不是执行历史，也不是外部通知渠道。
+已保存的发送记录确认消息已持久化到对话收件箱，不表示模型完成了所请求的工作。收件箱持久化或任务写入失败时，不增加已保存记录。收件箱持久化后崩溃或任务写入失败，可能留下未记入发送记录的已投递消息，并重复投递；不保证恰好投递一次。关闭宿主会丢弃仍在对话收件箱中等待的每条消息：其已保存记录仍然保留，模型不会收到该消息，宿主也不会再次发送。这不是执行历史，也不是外部通知渠道。
 
 已保存的记录在追加确认时裁剪：宿主保留确认时间落在配置的 `deliveryHistoryDays` 窗口内的记录（窗口以本次追加回执的 `deliveredAt` 向前计算），且最多保留最新的 `deliveryHistoryRecords` 条。最近一次回执始终保留，发生裁剪时标记更早记录不可用。宿主将保留的历史保存在内存中，每次确认均重写完整任务行。分页限制返回的记录数，不限制保留的历史或指令字节数。
 
-不支持暂停和每次运行新建 Session。名称、指令和运行时间的修改对模型开放：`schedule_update` 原地修改提醒并保留其 id 与已保存的投递记录；自动化任务页面也可按所选任务的绑定修改。两者都不是跨会话转交工作流。仅记录在旧 Session 日志中的提醒不会自动调度；请重新创建仍需要的提醒。此前已删除的任务记录不会被重建。
+模型可通过 `schedule_edit` 修改每条提醒的名称、指令、时间规则和目标，或暂停、恢复提醒；自动化任务页面也可对每条提醒这样做。两者都不是跨会话转交工作流。每次修改都会在每个 Agent 已加载的关联对话的下一次模型请求中加入一条通知，发起修改的对话除外。仅记录在旧 Session 日志中的提醒不会自动调度；请重新创建仍需要的提醒。此前已删除的任务记录不会被重建。
 
 <a id="further-exploration"></a>
 ## 延伸阅读
 
-- [Schedule 参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/schedule/schedule/README.zh.md) 说明精确的时间选择器、持久化与投递限制。
+- [Schedule 参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/schedule/schedule/README.zh.md) 说明任务字段、投递目标、重复规则、持久化与投递限制。
 - [自动化任务页面参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-schedule/README.zh.md) 说明全局页面与对话顶部目录。
 
 ## 开发备注

package/kb/site/reference/agent-lifecycle.md

@@ -30,7 +30,8 @@ sequenceDiagram
   Note over Agent,Driver: claim pending next-step input plus one queued prompt
   Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
   Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>Tools: resolve({ agent, modelSelection, signal }) once per proposed step
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall with the step tool set
   Driver->>Hooks: <code>agent/pre-step</code> waterfall
   Hooks-->>Driver: authoritative reject or enter(messages)
   alt proposed step rejected, first batch empty, or pre-step failed
@@ -70,6 +71,7 @@ sequenceDiagram
     end
   end
   Driver->>Session: <code>step/end</code>
+  Driver->>Tools: dispose the step tool set
   opt natural stop and next-step inbox empty
     Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
   end

package/kb/site/reference/api-gateway.md

@@ -17,7 +17,7 @@ rawMarkdownPath: "reference/api-gateway.md"
 
 `@RemoteScope(key)` 表示先通过 `ctx.typert.contexts` 把 identity 解析为一个作用域 Context，再从该 Context 取得服务并调用方法。它适用于方法本身依赖作用域组合、而不需要显式接收 `Agent` 等对象的情形。
 
-`@Remote` 接受导出名或 `{ name?, mode?, resources? }`；`@RemoteScope(key, option?)` 的第二个参数接受导出名（如下文的 `@RemoteScope('agent', 'current')`）或 `{ name?, resources? }`。`resources` 按资源种类给出读取函数，返回一次调用所访问资源的身份，供访问控制使用；每个读取函数以方法的 wire 参数作为自身参数，类型从被装饰方法推断。多数方法不声明读取函数，因为 Gateway 还会从声明了 `resource` 的 lookup 参数与作用域 Context 以及 `typert.resources` 中的默认字段读取身份；[Typert 子系统](./subsystems/typert.md)负责该顺序。
+`@Remote` 接受导出名或 `{ name?, mode?, resources? }`；`@RemoteScope(key, option?)` 的第二个参数接受导出名（如下文的 `@RemoteScope('agent', 'current')`）或 `{ name?, resources? }`。`resources` 按资源种类给出读取函数，返回一次调用所访问资源的身份，供访问控制使用；每个读取函数以方法的 wire 参数作为自身参数，类型从被装饰方法推断。多数方法不声明读取函数，因为 Gateway 还会从声明了 `resource` 的 lookup 参数与作用域 Context 以及 `typert.resources` 中的默认字段或 resolver 读取身份；[Typert 子系统](./subsystems/typert.md)负责该顺序。
 
 服务通常继承 `TypertRemoteService`，让 Cordis 服务 key 与默认 Remote namespace 在构造器中显式绑定。已有其他基类的服务可以改为声明 `readonly typertRemote = bindTypertRemote(this, serviceKey)`；两种方式都会留下可检查的公开 binding，不依赖编译器向构造函数注入 symbol。
 
@@ -104,11 +104,11 @@ API Gateway 包同时拥有 Host dispatcher 与 Client Remote endpoint 两个对
 
 ## 严格生成流水线
 
-根构建依次编译并打包 Host face、Client face，再构建 Web 壳层（[步骤顺序](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.zh.md#typescript-project-layout)）。Host 阶段先编译 Host 包 reference，再运行 `tsdown --env.DSH_BUILD_FACE host`；Typert generator 由正常 Host Project Reference 图编译，并在这次 tsdown 中以 Host aggregate 为唯一 `ts.Program` 种子运行。Client 阶段随后编译 Client 包 reference 并运行 `tsdown --env.DSH_BUILD_FACE client`，使用刚生成的 Remote Client 声明和运行时贡献，但不再次启动 Typert。
+根构建首先通过 `scripts/generate-typert.ts` 运行仅源码的 Host 分析，再编译并打包 Host 与 Client face，最后构建 Web（[步骤顺序](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.zh.md#typescript-project-layout)）。生成器以 Host aggregate 为唯一 `ts.Program` 种子，在包编译前写出 Remote 声明。Host tsdown 阶段转换装饰器，但不重复生成元数据；Client 阶段消费这些声明与运行时贡献。
 
 两次 tsdown 都匹配 `vendor/*`、`packages/*/*` 与 `apps/cli`，Host 阶段另外匹配 `apps/desktop-host`（[构建顺序](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.zh.md#typescript-project-layout)），且都只打包 `lib/types` 中由对应 tsc 阶段发射的 JavaScript。根配置不扫描 Client 产物、不按包名分类，也不向 tsdown 传维护式 filter；各包的本地配置根据 `DSH_BUILD_FACE` 返回当前阶段的入口。普通 Client 插件在 Client 阶段一起生成 Node loader 入口与 browser bundle。
 
-`api/remotes`、`api/gateway`、`api/session-controller` 与 `api/workspace-controller`（外加 `client/connection`）都拆分 TypeScript face。`api/remotes` 的 Client project 依赖业务包在 Host tsdown 中生成的 `/remote` 声明；根 aggregate 与直接消费方必须分别引用各拆分包自己的 `tsconfig.host.json` 或 `tsconfig.client.json`。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 让 Host 入口在 Host tsdown 中生成，让 Client tsdown 只生成 browser 入口。Agent/Session lookup 策略位于 `@deepseek-ai/dsh-api-session-controller`，而非 `api-remotes`。
+`api/remotes`、`api/gateway`、`api/session-controller` 与 `api/workspace-controller`（外加 `client/connection`）都拆分 TypeScript face。`api/remotes` 的 Client project 依赖业务包在包编译前生成的 `/remote` 声明；根 aggregate 与直接消费方必须分别引用各拆分包自己的 `tsconfig.host.json` 或 `tsconfig.client.json`。`api-remotes` 的 `clientBundle(..., { hostPhase: true })` 让 Host 入口在 Host tsdown 中生成，让 Client tsdown 只生成 browser 入口。Agent/Session lookup 策略位于 `@deepseek-ai/dsh-api-session-controller`，而非 `api-remotes`。
 
 每个贡献业务包把生成文件写入自己的 `lib/`，而不是源码目录：
 
@@ -162,7 +162,7 @@ pnpm run dev:web
 pnpm run build:lib
 ```
 
-运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 先以不打包的 Typert 生成刷新 Host 约定，再运行 Client tsc；CI 的构建 lane 与发布构建则在 Client tsc 之前的 Host bundle 阶段生成它。
+运行中的 Client watcher 会在重新打包时消费这些生成文件。若已单独运行 `pnpm run build:lib:host` 刷新 Host 约定，也可再运行 `pnpm run build:lib:client` 完成 Client 侧；干净工作树不能跳过 Host 阶段。仅重新编译前端源码不能从 Host decorator 推导新类型。`pnpm run typecheck` 先以不打包的 Typert 生成刷新 Host 约定，再运行 Client tsc；CI 的构建 lane 与发布构建同样在包编译之前使用仅源码生成。
 
 <a id="boundaries"></a>