dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/skills/dsh-plugin-dev-kb.md

@@ -1,69 +1,71 @@
----
-name: dsh-plugin-dev-kb
-description: DeepSeek Harness 官方文档知识库的使用指南：知识库位置与结构、按任务场景的阅读路径、检索策略。写 dsh 插件 / Tool / 配置 / 服务 / 事件 / 打包发布 / LLM 适配器时先加载本技能定位文档。注意：本技能仅限 dsh（DeepSeek Harness）插件开发；写 NoneBot 插件时请加载 nonebot-plugin-dev-kb，勿用本技能。
-whenToUse: 开发 dsh 插件、查询 dsh 能力与 API、写 Tool、配置 cordis.yml、扩展 Harness 时
----
-# dsh 插件开发知识库使用指南（dsh-plugin-dev-kb）
-
-本插件内置 DeepSeek Harness 官方文档的完整镜像，供插件开发时快速定位与检索。
-
-## 0. 知识库位置
-
-- **知识库根**：`{{KB_ROOT}}`（插件挂载时由 lib/index.js 自动替换为插件内 kb/ 目录的实际绝对路径，可直接 read/glob/grep；正斜杠路径，跨机器/安装位置始终有效）
-- 数据来源：官方文档站点（VitePress）的仓库原始 Markdown，链接已按站点路由重写，与线上站点逐字一致（见 `kb/meta/source.json` 的 commit）
-
-## 1. 目录结构
-
-```
-kb/
-├── site/            线上站点完整镜像（中英双语 188 页，优先读这里）
-│   ├── guide/       入门：quickstart / providers / python-sdk / github-review / schedule / mcp-memory / network-proxy / public-deployments
-│   ├── develop/     basic(第一个插件/tool/config/publish)、framework(生命周期/服务/事件)、
-│   │                practice(能力分层/LLM适配器/动态装配)、cordis-tutorial(7章)
-│   ├── reference/   index(架构)、cordis-primer、capability-seams、agent-lifecycle、
-│   │                config-catalog、tool-catalog、api-gateway、cordis-api/(6)、cookbook/(5)、subsystems/(46)
-│   └── en/          英文站镜像（结构与中文站一致）
-├── extra/           仓库内未发布到站点的补充文档（182 篇）：glossary、defensive-patterns、
-│                    module-graph、testing、postmortem/、i18n/、cookbook 与 subsystems 扩展、
-│                    upgrade-guide/(各版本升级指南)、persistence-changes/(持久化格式变更)
-├── meta/
-│   ├── topics.md    ★ 主题导航：任务场景 → 要读的文件（先用这个）
-│   ├── search-index.json  全量检索索引（373 文件：path/url/title/字符数）
-│   ├── source.json  来源信息（commit/时间/统计）
-│   └── site-pages.txt     线上站点页面清单
-├── INDEX.md         全部 站点 URL ↔ 本地文件 对照
-└── README.md        知识库总览与更新方法
-```
-
-## 2. 使用流程（从快到慢，优先用工具）
-
-1. **dsh_kb_search 工具检索（首选）**：调用本插件的 `dsh_kb_search` 工具，一次拿到命中文件路径 + 行号 + 上下文片段，再用 read 工具按行号局部读原文。参数：`query`（关键词，空白分词；空或 `"topics"` 返回主题导航）、`scope`（`api` = 只搜 API 签名/目录类文档，查 `ctx.*` API 用）、`lang`（默认 zh）、`maxResults`。
-2. **文件工具兜底**（工具不可用时）：读 `{{KB_ROOT}}/meta/topics.md` 按主题找文件；或对 `{{KB_ROOT}}/meta/search-index.json` / `{{KB_ROOT}}/site/` 用 grep 定位。
-3. **按 URL 反查**：已知线上页面 URL 时，在 `{{KB_ROOT}}/INDEX.md` 查对应本地文件。
-
-## 3. 阅读原则
-
-- **中文优先**：默认读 `site/` 下中文文件；需要英文原文时读 `site/en/` 对应路径。
-- **大文件局部读**：`reference/config-catalog.md`、`reference/tool-catalog.md`、`extra/module-graph.md`、`reference/subsystems/session.md` 等超过 100KB，先用 grep 定位再 read 局部，禁止整读。
-- **代码示例可直接引用**：文档中的 `apply(ctx)` 插件骨架、`ctx.tools.register`、`inject` 声明等可直接用于新代码；但需注意知识库是 commit 快照，若与当前安装版本 API 不一致，以实际安装包为准。
-- **常见检索关键词**：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`、`Branded`。
-
-## 4. 插件开发高频路径速查
-
-| 任务 | 先读 |
-| --- | --- |
-| 写第一个插件 | `site/develop/basic/index.md` |
-| 开发 Tool | `site/develop/basic/tool.md` + `site/reference/cookbook/adding-a-tool.md` |
-| 插件配置 | `site/develop/basic/config.md` |
-| 服务与依赖 | `site/develop/framework/service.md` |
-| 事件监听 | `site/develop/framework/events.md` |
-| 打包发布 | `site/develop/basic/publish.md` |
-| LLM 适配器 | `site/develop/practice/llm-adapter.md` |
-| 能力扩展 | `site/develop/practice/index.md` + `site/reference/capability-seams.md` |
-| 动态装配 Cordis | `site/develop/practice/dynamic-cordis.md` |
-| API Gateway / Remote 方法 | `site/reference/api-gateway.md` |
-| 子系统能力 | `site/reference/subsystems/index.md` → 对应子系统页 |
-
-## 5. 更新知识库
-
-见 `kb/README.md` 的更新方法（重新克隆 `deepseek-ai/deepseek-harness` 并运行站点投影器）。
+---
+name: dsh-plugin-dev-kb
+description: DeepSeek Harness 官方文档知识库的使用指南：知识库位置与结构、按任务场景的阅读路径、检索策略。写 dsh 插件 / Tool / 配置 / 服务 / 事件 / 打包发布 / LLM 适配器时先加载本技能定位文档。注意：本技能仅限 dsh（DeepSeek Harness）插件开发；写 NoneBot 插件时请加载 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 开发 dsh 插件、查询 dsh 能力与 API、写 Tool、配置 cordis.yml、扩展 Harness 时
+---
+# dsh 插件开发知识库使用指南（dsh-plugin-dev-kb）
+
+本插件内置 DeepSeek Harness 官方文档的完整镜像，供插件开发时快速定位与检索。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`（插件挂载时由 lib/index.js 自动替换为插件内 kb/ 目录的实际绝对路径，可直接 read/glob/grep；正斜杠路径，跨机器/安装位置始终有效）
+- 数据来源：官方文档站点（VitePress）的仓库原始 Markdown，链接已按站点路由重写，与线上站点逐字一致（见 `kb/meta/source.json` 的 commit）
+
+## 1. 目录结构
+
+```
+kb/
+├── site/            线上站点完整镜像（中英双语 194 页，优先读这里）
+│   ├── guide/       入门：quickstart / providers / python-sdk / github-review / schedule / mcp-memory / network-proxy / public-deployments
+│   ├── develop/     basic(第一个插件/tool/config/publish)、framework(生命周期/服务/事件)、
+│   │                practice(能力分层/LLM适配器/动态装配)、cordis-tutorial(7章)
+│   ├── reference/   index(架构)、cordis-primer、capability-seams、agent-lifecycle、
+│   │                config-catalog、tool-catalog、api-gateway、cordis-api/(6)、cookbook/(5)、subsystems/(46+，含 office-kit)、
+│   │                guide/（含 desktop-uninstall-cleanup）
+│   └── en/          英文站镜像（结构与中文站一致）
+├── extra/           仓库内未发布到站点的补充文档（554 篇）：glossary、defensive-patterns、
+│                    module-graph、testing、postmortem/、i18n/、cookbook 与 subsystems 扩展、
+│                    upgrade-guide/(各版本升级指南)、persistence-changes/(持久化格式变更)
+├── meta/
+│   ├── topics.md    ★ 主题导航：任务场景 → 要读的文件（先用这个）
+│   ├── search-index.json  全量检索索引（751 文件：path/url/title/字符数）
+│   ├── source.json  来源信息（commit/时间/统计）
+│   └── site-pages.txt     线上站点页面清单
+├── INDEX.md         全部 站点 URL ↔ 本地文件 对照
+└── README.md        知识库总览与更新方法
+```
+
+## 2. 使用流程（从快到慢，优先用工具）
+
+1. **dsh_kb_search 工具检索（首选）**：调用本插件的 `dsh_kb_search` 工具，一次拿到命中文件路径 + 行号 + 上下文片段。参数：`query`（关键词，空白分词；空或 `"topics"` 返回主题导航）、`scope`（`api` = 只搜 API 签名/目录类文档，查 `ctx.*` API 用）、`lang`（默认 zh）、`maxResults`。输出自带**版本横幅**（宿主 dsh 版本 vs 知识库 master 快照 + 对应 upgrade-guide 路径），横幅提示版本差异时务必读指南。
+2. **dsh_kb_read 工具按行号窗口读原文（1.8.0 起，次选）**：拿到 path + 命中行号后用 `dsh_kb_read`（参数 `path` / `offset` / `limit`）带行号窗口读上下文，输出自动提示中英对照路径与续读位置；替代通用 read 工具，防大文件整读。
+3. **文件工具兜底**（工具不可用时）：读 `{{KB_ROOT}}/meta/topics.md` 按主题找文件；或对 `{{KB_ROOT}}/meta/search-index.json` / `{{KB_ROOT}}/site/` 用 grep 定位。
+4. **按 URL 反查**：已知线上页面 URL 时，在 `{{KB_ROOT}}/INDEX.md` 查对应本地文件。
+
+## 3. 阅读原则
+
+- **中文优先**：默认读 `site/` 下中文文件；需要英文原文时读 `site/en/` 对应路径。
+- **大文件局部读**：`reference/config-catalog.md`、`reference/tool-catalog.md`、`extra/module-graph.md`、`reference/subsystems/session.md` 等超过 100KB，先用 grep 定位再 read 局部，禁止整读。
+- **代码示例可直接引用**：文档中的 `apply(ctx)` 插件骨架、`ctx.tools.register`、`inject` 声明等可直接用于新代码；但需注意知识库是 commit 快照，若与当前安装版本 API 不一致，以实际安装包为准。
+- **常见检索关键词**：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`、`Branded`。
+
+## 4. 插件开发高频路径速查
+
+| 任务 | 先读 |
+| --- | --- |
+| 写第一个插件 | `site/develop/basic/index.md` |
+| 开发 Tool | `site/develop/basic/tool.md` + `site/reference/cookbook/adding-a-tool.md` |
+| 插件配置 | `site/develop/basic/config.md` |
+| 服务与依赖 | `site/develop/framework/service.md` |
+| 事件监听 | `site/develop/framework/events.md` |
+| 打包发布 | `site/develop/basic/publish.md` |
+| LLM 适配器 | `site/develop/practice/llm-adapter.md` |
+| 能力扩展 | `site/develop/practice/index.md` + `site/reference/capability-seams.md` |
+| 动态装配 Cordis | `site/develop/practice/dynamic-cordis.md` |
+| API Gateway / Remote 方法 | `site/reference/api-gateway.md` |
+| 子系统能力 | `site/reference/subsystems/index.md` → 对应子系统页 |
+
+## 5. 更新知识库
+
+见 `kb/README.md` 的更新方法（重新克隆 `deepseek-ai/deepseek-harness` 并运行站点投影器）。

package/skills/dsh-plugin-starter.md

@@ -0,0 +1,65 @@
+---
+name: dsh-plugin-starter
+description: dsh 插件脚手架助手：从零新建一个合规的 dsh 插件骨架（package.json 含 dsh.bundle.patch 与 peer 显式预发布范围、cordis.patch.yml、双语 README、selfcheck、CHANGELOG、GitHub topics），逐项满足 dsh 官方发布要求与 dsh-market / awesome-dsh-plugin 收录门槛。用户说「新建 dsh 插件 / 做一个插件 / 插件脚手架 / starter」时加载本技能。注意：写 NoneBot 插件时请用 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 用户要从零开始新建一个 dsh 插件，或问「插件骨架怎么搭 / 发布要准备什么文件」时
+---
+# dsh 插件脚手架（dsh-plugin-starter）
+
+帮用户从零搭一个**能通过官方校验、能进 market / awesome 收录**的 dsh 插件骨架。
+原则：每生成一个文件都对照下方清单自检；知识库文档只读不猜，拿不准就先检索确认。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`
+- 先读两篇再动手：`{{KB_ROOT}}/site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块，
+  `ctx.effect()` 自动清理）与 `{{KB_ROOT}}/site/develop/basic/publish.md`（打包发布）。
+- 配置 / 工具 / 事件写法按需检索：`dsh_kb_search`，如 query=`ctx.tools.register 工具定义`。
+
+## 1. 骨架清单（缺一 = 发布/收录会卡）
+
+在用户指定的目录 `<plugin-name>/` 下生成（命名规范：`dsh-plugin-<topic>` 或 `dsh-<topic>`）：
+
+| 文件 | 要点 |
+|---|---|
+| `package.json` | `"main": "./lib/index.js"`；`files` 数组**必须含 main 入口所在目录**；`license: "MIT"`；`homepage` 指 GitHub 仓库 `#readme`；`repository.url`；`keywords ≥3`（含 `dsh` / `dsh-plugin` / `deepseek-harness`）；**`dsh: { bundle: { patch: "./cordis.patch.yml" } }`**（只声明 `dsh.client` 会被 awesome CI 拒）；`engines.node >=18`；`peerDependencies` 若引 `@deepseek-ai/*`，**范围必须显式覆盖预发布分支**（如 `"^4.0.1"` 对 cordis 可行，对 dsh 主包要写 `">=0.2.0-rc.1 <0.3.0-0"` 形态，否则预发布构建被静默排除）；`scripts.selfcheck` 指向最小自检 |
+| `cordis.patch.yml` | 插件自注册声明（`dsh.profile.bundles` 挂载用）；含 Config 时在此声明配置 schema |
+| `lib/index.js` | `export function apply(ctx, config)`；零 `@deepseek-ai/*` 运行时 import（插件以 link:/file: 装入 profile，外部依赖按 realpath 解析不到——用原始 definition 形状注册工具，参照 dsh-plugin-windows-guard 先例）；每个注册动作包 `ctx.effect(() => ..., '说明')` |
+| `README.md` | ① 顶部标题 + 一句话描述；② `## 安装` 段**必须含标准安装命令**（`git clone` / `npm install` 等——market ease 项）；③ `## 功能` + `## 配置`/`## 示例` 双标题；④ ≥2 个代码块；⑤ `## 相关插件` 互相引用段（列同系列全部**已发布**插件：npm 链 + GitHub 链 + 一句话）；⑥ 长度 >2000 字更佳；⑦ 需要 `AI 生成声明` 段 |
+| `README.en.md` | 结构与中文一致（i18n 规范见 `{{KB_ROOT}}/extra/i18n/`） |
+| `CHANGELOG.md` | `## x.y.z - 日期` 逐版条目：修了什么/为什么/怎么验证 |
+| `LICENSE` | MIT |
+| `scripts/selfcheck.mjs` | 最小结构自检（文件存在性 + package.json 关键字段），发布前必跑 |
+| `.github/workflows/`（可选） | CI / 自动化（如每周内容同步） |
+
+## 2. 命名与元数据红线
+
+- 目录名 = npm 包名（例外如 `dsh-notify` 是历史遗留，新插件不要再造）
+- **README 里写「无需配置」时必须带否定词**（"无需 / 不需要 / zero-config"）——market 的
+  needsConfig 反向检测按裸关键词（`API_KEY` 等）扫描，否定语境会被先摘除；确需配置的插件
+  写配置项时避免裸写这些 KEY 名
+- 描述不得夸大：awesome 评审会对着源码逐条核对数字 / 命令 / API 名
+
+## 3. GitHub 侧（骨架生成后提醒用户补）
+
+```powershell
+gh api -X PATCH repos/<owner>/<repo> -f description="…（一句话中文简介，勿夸大）" -f homepage="https://github.com/<owner>/<repo>#readme"
+# topics 至少含 dsh / dsh-plugin / deepseek-harness + 主题词——缺 topics 是 market 收录失败最常见原因
+gh api -X PUT repos/<owner>/<repo>/topics --input topics.json
+```
+
+## 4. 验证闭环
+
+1. `node scripts/selfcheck.mjs` → 全部通过
+2. 用 dsh-dev-sandbox 技能建独立沙箱 profile 挂载冒烟（不污染主力 dsh）：
+   启动日志**不得**出现 `skipping profile bundle "<你的插件>"`（出现 = peer 闸门没过 = 静默失效）
+3. `npm pack --dry-run` 核对发布内容（files 不夹带内部文档）
+4. 发布流程与版本纪律见 `{{KB_ROOT}}/site/develop/basic/publish.md`
+
+## 5. 红线
+
+- **不要双挂载**：插件经 `dsh.profile.bundles` 进场后，profile 层不得再 insert 同 id
+  （`duplicate loader entry id` 启动即崩）
+- **不要在插件运行时 import `@deepseek-ai/*`**（见 lib/index.js 要点）
+- **不要把凭据写进入库文件**；用户凭据走 credentials ref / 环境变量
+- 知识库快照可能领先宿主 dsh 版本：API 行为不符时以宿主实际安装包为准，
+  版本差异读 `{{KB_ROOT}}/extra/upgrade-guide/`

package/skills/dsh-upgrade-assistant.md

@@ -0,0 +1,62 @@
+---
+name: dsh-upgrade-assistant
+description: DeepSeek Harness (dsh) 升级助手：用户升级 dsh 版本时，用知识库里的官方升级指南（upgrade-guide/）与持久化变更记录（persistence-changes/）生成迁移检查清单、预判破坏性变更、给出回滚方案。用户提到「升级 dsh / 更新 Harness / 换版本 / upgrade」或升级 dsh 后报错时加载本技能。注意：写 NoneBot 时请用 nonebot-plugin-dev-kb，勿用本技能。
+whenToUse: 用户要升级 dsh / DeepSeek Harness 版本，或升级后插件不工作、会话打不开等需要排查迁移问题时
+---
+# dsh 升级助手（dsh-upgrade-assistant）
+
+帮用户安全升级 DeepSeek Harness：先搞清「从哪版 → 到哪版」，再用知识库把两版之间的全部变更读出来，
+生成检查清单，升级后逐条验证。
+
+## 0. 知识库位置
+
+- **知识库根**：`{{KB_ROOT}}`（插件挂载时自动替换为实际绝对路径，可直接 read/glob/grep）
+- 升级相关内容在：`{{KB_ROOT}}/extra/upgrade-guide/`（逐版本升级指南）与
+  `{{KB_ROOT}}/extra/persistence-changes/`（持久化格式变更，按日期命名）
+
+## 1. 标准流程
+
+### 第一步：确定版本区间
+
+1. **当前版本**：读用户 profile 的安装信息（如 `%LOCALAPPDATA%` / profile 目录下的
+   `package.json` 中 `@deepseek-ai/dsh` 的版本，或让用户看 Desktop 关于页）。
+2. **目标版本**：`npm view @deepseek-ai/dsh version`（latest）或用户指定版本。
+3. 列出区间内的版本号，形如 `v0.2.0-rc.2 → v0.2.1-rc.4`。
+
+### 第二步：读变更（知识库检索）
+
+1. 对区间内**每个版本**读一份指南：
+   `{{KB_ROOT}}/extra/upgrade-guide/<版本>/`（目录按 `v0.1.7-rc.2` … `v0.2.2-alpha.3` 组织，
+   每个子目录是一篇 guide.md / guide.zh.md，读中文版）。
+2. 持久化/会话格式变更：列出 `{{KB_ROOT}}/extra/persistence-changes/` 中日期晚于当前版本
+   发布日的条目（文件名即日期），只读标题相关条目判断「历史会话会不会丢/迁移」。
+3. 快速定位也可用 `dsh_kb_search` 工具，如 query=`升级 upgrade-guide v0.2.1`。
+4. 优先关注三类破坏点：**删除/改名的 API**（插件会静默失效）、**会话格式升级**
+   （旧会话打不开或需要迁移）、**配置字段变更**（profile 的 cordis.patch.yml / package.json）。
+
+### 第三步：给出升级检查清单（输出给用户）
+
+清单必须包含：
+
+- **备份**：升级前备份 profile 的 `package.json` 与 `pnpm-lock.yaml`
+- **变更摘要**：区间内每个版本的破坏性变更，逐条说明「影响你吗」
+- **插件兼容**：dsh 有插件兼容闸门——`peerDependencies` 不覆盖目标版本的插件会被
+  **整体拒绝安装**或**启动时跳过（静默失效）**；把用户已装插件与目标版本对照，
+  预先列出需要升级/移除/豁免（allow-version）的插件
+- **回滚方案**：保留旧版本安装包/备份路径，回滚 = 恢复备份 + 重装旧版
+
+### 第四步：升级后验证
+
+- 启动时逐条看 stderr 的 `dsh: skipping profile bundle "X"` 警告——被跳过 = 该插件静默失效
+- 用一个旧会话验证历史消息正常加载（会话格式变更最常坏这里）
+- 逐个核心功能冒烟：新建会话、工具调用、技能加载、设置页
+- 若用户安装了 `dsh-plugin-dev-kb`，知识库可能比目标版本新（快照领先），
+  文档与实际行为不符时以实际安装包为准
+
+## 2. 红线
+
+- **不要在未备份的情况下动 profile**；备份是第一步，不是可选项
+- **不要用 allow-version 豁免兼容闸门来「绕过」不兼容插件**——除非用户明确要求并理解风险
+  （静默失效比拒绝安装更难排查）
+- 知识库是快照，若 upgrade-guide 目录里没有目标版本的目录（比如目标版本比知识库同步点新），
+  明确告知用户「该版本的官方指南未收录」，让用户看官方 release notes，不要编造变更内容

package/kb/extra/agent-lifecycle.md

@@ -1,91 +0,0 @@
-<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
-     Run `pnpm run gen-doc-graphs` to regenerate. -->
-
-# Agent Turn And Step Lifecycle
-
-This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant Agent
-  participant Driver
-  participant Hooks as hook listeners
-  participant Prompt as ctx.systemPrompt
-  participant LLM as ctx.llm
-  participant Tools as ctx.tools
-  participant Session
-  participant SDK as UI or SDK listener
-  User->>Agent: followup(content)
-  Agent-->>SDK: <code>agent/inbox/spliced</code>
-  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
-  Agent->>Driver: queued work wakes driver
-  Driver-->>SDK: <code>agent/status</code> running
-  Driver->>Session: <code>turn/start</code>
-  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->>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
-    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
-  else enter proposed step
-  Driver->>Session: <code>step/start</code>
-  Driver->>Hooks: <code>agent/request</code> waterfall
-  Driver->>LLM: prepareCall(config, signal)
-  Note over Driver,LLM: cancellation during either async phase commits neither system nor users
-  Note over Driver,Session: synchronous admission using the prepared call capability
-  Driver->>Session: <code>system/message</code> ordered per-node reconciliation
-  Driver->>Session: <code>user/message</code> per entered message
-  Driver->>Session: <code>request/header</code> and <code>request/context</code> as needed
-  Driver->>Driver: derive and freeze request from the log
-  Driver->>LLM: bound prepared call through <code>llm/stream</code> waterfall
-  LLM-->>Driver: StreamChunk*
-  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
-  alt final adapter or terminal in-band request failure
-    Driver->>Session: <code>assistant/attempt</code>
-    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-    Driver->>Hooks: <code>agent/request-error</code> waterfall
-    Hooks-->>Driver: return retry action or preserve the original error
-    Note over Driver,LLM: retry in the open step: prepare and reconcile the same rendered assembly without repeating pre-step or users
-  else model request succeeded
-  Driver->>Session: <code>assistant/message</code>
-  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-  Driver->>Tools: classify pending call by executionMode
-  loop barriers and bounded rolling pool, reclassify before start
-    opt call starts
-      Driver->>Session: <code>tool/call</code>
-      Driver->>Tools: ordered pre, concurrent execute
-      Tools-->>Session: tool-owned events when applicable
-    end
-    opt next model-order result ready
-      Driver->>Tools: ordered post
-      Driver->>Session: <code>tool/result</code>
-    end
-  end
-  Driver->>Session: <code>step/end</code>
-  opt natural stop and next-step inbox empty
-    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
-  end
-  opt next-step input is pending
-    Driver-->>Driver: claim pending next-step input
-    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-    Driver->>Hooks: <code>agent/pre-step</code> waterfall
-    Hooks-->>Driver: authoritative reject or enter(messages)
-  end
-  end
-  end
-  Driver->>Session: <code>turn/end</code>
-  Driver-->>SDK: <code>agent/status</code> idle
-```
-
-The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.
-
-`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery runs within the open step and retries only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative. Each retry prepares its call and reconciles the retained rendered assembly before request derivation, without repeating assembly, pre-step, or user admission.
-
-The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
-
-SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
-
-Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.

package/kb/extra/agent-lifecycle.zh.md

@@ -1,93 +0,0 @@
-<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
-     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
-
-# Agent 轮次与步骤生命周期
-
-[English](agent-lifecycle.md) | 中文
-
-此时序图是 [architecture.md](architecture.zh.md#turn-flow) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant Agent
-  participant Driver
-  participant Hooks as hook listeners
-  participant Prompt as ctx.systemPrompt
-  participant LLM as ctx.llm
-  participant Tools as ctx.tools
-  participant Session
-  participant SDK as UI or SDK listener
-  User->>Agent: followup(content)
-  Agent-->>SDK: <code>agent/inbox/spliced</code>
-  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
-  Agent->>Driver: queued work wakes driver
-  Driver-->>SDK: <code>agent/status</code> running
-  Driver->>Session: <code>turn/start</code>
-  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->>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
-    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
-  else enter proposed step
-  Driver->>Session: <code>step/start</code>
-  Driver->>Hooks: <code>agent/request</code> waterfall
-  Driver->>LLM: prepareCall(config, signal)
-  Note over Driver,LLM: cancellation during either async phase commits neither system nor users
-  Note over Driver,Session: synchronous admission using the prepared call capability
-  Driver->>Session: <code>system/message</code> ordered per-node reconciliation
-  Driver->>Session: <code>user/message</code> per entered message
-  Driver->>Session: <code>request/header</code> and <code>request/context</code> as needed
-  Driver->>Driver: derive and freeze request from the log
-  Driver->>LLM: bound prepared call through <code>llm/stream</code> waterfall
-  LLM-->>Driver: StreamChunk*
-  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
-  alt final adapter or terminal in-band request failure
-    Driver->>Session: <code>assistant/attempt</code>
-    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-    Driver->>Hooks: <code>agent/request-error</code> waterfall
-    Hooks-->>Driver: return retry action or preserve the original error
-    Note over Driver,LLM: retry in the open step: prepare and reconcile the same rendered assembly without repeating pre-step or users
-  else model request succeeded
-  Driver->>Session: <code>assistant/message</code>
-  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
-  Driver->>Tools: classify pending call by executionMode
-  loop barriers and bounded rolling pool, reclassify before start
-    opt call starts
-      Driver->>Session: <code>tool/call</code>
-      Driver->>Tools: ordered pre, concurrent execute
-      Tools-->>Session: tool-owned events when applicable
-    end
-    opt next model-order result ready
-      Driver->>Tools: ordered post
-      Driver->>Session: <code>tool/result</code>
-    end
-  end
-  Driver->>Session: <code>step/end</code>
-  opt natural stop and next-step inbox empty
-    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
-  end
-  opt next-step input is pending
-    Driver-->>Driver: claim pending next-step input
-    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
-    Driver->>Hooks: <code>agent/pre-step</code> waterfall
-    Hooks-->>Driver: authoritative reject or enter(messages)
-  end
-  end
-  end
-  Driver->>Session: <code>turn/end</code>
-  Driver-->>SDK: <code>agent/status</code> idle
-```
-
-`assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用，并嵌入精确的紧凑带时间 stream。空内容不会进入派生历史。失败、重试、取消或 stream error attempt 到达 settlement 时，如果没有 surface message，就会把 stream 记录为 `assistant/attempt`。实时 `agent/assistant-stream` chunk frame 是瞬态数据；回放读取任一种持久 settlement，如果进程在 settlement 前硬中断，则不会留下持久 attempt stream。
-
-`dsh-compaction-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在仍打开的步骤内，只有剪枝或摘要生成推进 surface replacement generation 时才重试，否则仍以原始请求错误为准。每次重试都会准备调用，并在派生请求之前协调保留的已渲染组装结果，不重复组装、pre-step 或用户消息准入。
-
-以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息与 `startsRequestSeries`，除非有意替换。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
-
-需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
-
-维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。