dsh-plugin-dev-kb 1.0.7 → 1.0.9

package/kb/meta/site-pages.txt

@@ -1,168 +1,182 @@
-develop_basic_config.md
-develop_basic_index.md
-develop_basic_publish.md
-develop_basic_tool.md
-develop_cordis-tutorial_01-first-plugin.md
-develop_cordis-tutorial_02-lifecycle-and-effects.md
-develop_cordis-tutorial_03-services.md
-develop_cordis-tutorial_04-events.md
-develop_cordis-tutorial_05-config.md
-develop_cordis-tutorial_06-composition-and-hmr.md
-develop_cordis-tutorial_07-into-the-harness.md
-develop_cordis-tutorial_index.md
-develop_framework_events.md
-develop_framework_index.md
-develop_framework_service.md
-develop_practice_index.md
-develop_practice_llm-adapter.md
-en_develop_basic_config.md
-en_develop_basic_index.md
-en_develop_basic_publish.md
-en_develop_basic_tool.md
-en_develop_cordis-tutorial_01-first-plugin.md
-en_develop_cordis-tutorial_02-lifecycle-and-effects.md
-en_develop_cordis-tutorial_03-services.md
-en_develop_cordis-tutorial_04-events.md
-en_develop_cordis-tutorial_05-config.md
-en_develop_cordis-tutorial_06-composition-and-hmr.md
-en_develop_cordis-tutorial_07-into-the-harness.md
-en_develop_cordis-tutorial_index.md
-en_develop_framework_events.md
-en_develop_framework_index.md
-en_develop_framework_service.md
-en_develop_practice_index.md
-en_develop_practice_llm-adapter.md
-en_guide_providers.md
-en_guide_python-sdk.md
-en_guide_quickstart.md
-en_index.md
-en_reference_agent-lifecycle.md
-en_reference_capability-seams.md
-en_reference_config-catalog.md
-en_reference_cookbook_adding-a-conversation-node.md
-en_reference_cookbook_adding-an-llm-adapter.md
-en_reference_cookbook_adding-a-package.md
-en_reference_cookbook_adding-a-settings-card.md
-en_reference_cookbook_adding-a-tool.md
-en_reference_cookbook_extension-cookbook.md
-en_reference_cordis-api_context.md
-en_reference_cordis-api_events.md
-en_reference_cordis-api_fiber.md
-en_reference_cordis-api_inherited.md
-en_reference_cordis-api_registry.md
-en_reference_cordis-api_service.md
-en_reference_cordis-primer.md
-en_reference_index.md
-en_reference_persistence-catalog.md
-en_reference_subsystems_approval.md
-en_reference_subsystems_client-modules.md
-en_reference_subsystems_code-runtime.md
-en_reference_subsystems_commands.md
-en_reference_subsystems_compaction.md
-en_reference_subsystems_core.md
-en_reference_subsystems_credentials.md
-en_reference_subsystems_filesystem.md
-en_reference_subsystems_goal.md
-en_reference_subsystems_index.md
-en_reference_subsystems_invariants.md
-en_reference_subsystems_jobs.md
-en_reference_subsystems_llm-streaming.md
-en_reference_subsystems_lsp.md
-en_reference_subsystems_permission-presets.md
-en_reference_subsystems_persistence.md
-en_reference_subsystems_plan.md
-en_reference_subsystems_sandbox.md
-en_reference_subsystems_schedule.md
-en_reference_subsystems_scope.md
-en_reference_subsystems_session.md
-en_reference_subsystems_session-projection.md
-en_reference_subsystems_session-query.md
-en_reference_subsystems_session-reference.md
-en_reference_subsystems_session-telemetry.md
-en_reference_subsystems_session-title.md
-en_reference_subsystems_settings.md
-en_reference_subsystems_shell.md
-en_reference_subsystems_skills.md
-en_reference_subsystems_spill.md
-en_reference_subsystems_storage.md
-en_reference_subsystems_subagent.md
-en_reference_subsystems_subprocess.md
-en_reference_subsystems_system-prompt.md
-en_reference_subsystems_terminal.md
-en_reference_subsystems_token-meter.md
-en_reference_subsystems_tools.md
-en_reference_subsystems_typert.md
-en_reference_subsystems_user-questions.md
-en_reference_subsystems_web.md
-en_reference_subsystems_web-server.md
-en_reference_subsystems_workflow.md
-en_reference_subsystems_workspace.md
-en_reference_tool-catalog.md
-en_reference_tool-execution-pipeline.md
-guide_providers.md
-guide_python-sdk.md
-guide_quickstart.md
-index.md
-reference_agent-lifecycle.md
-reference_capability-seams.md
-reference_config-catalog.md
-reference_cookbook_adding-a-conversation-node.md
-reference_cookbook_adding-an-llm-adapter.md
-reference_cookbook_adding-a-package.md
-reference_cookbook_adding-a-settings-card.md
-reference_cookbook_adding-a-tool.md
-reference_cookbook_extension-cookbook.md
-reference_cordis-api_context.md
-reference_cordis-api_events.md
-reference_cordis-api_fiber.md
-reference_cordis-api_inherited.md
-reference_cordis-api_registry.md
-reference_cordis-api_service.md
-reference_cordis-primer.md
-reference_index.md
-reference_persistence-catalog.md
-reference_subsystems_approval.md
-reference_subsystems_client-modules.md
-reference_subsystems_code-runtime.md
-reference_subsystems_commands.md
-reference_subsystems_compaction.md
-reference_subsystems_core.md
-reference_subsystems_credentials.md
-reference_subsystems_filesystem.md
-reference_subsystems_goal.md
-reference_subsystems_index.md
-reference_subsystems_invariants.md
-reference_subsystems_jobs.md
-reference_subsystems_llm-streaming.md
-reference_subsystems_lsp.md
-reference_subsystems_permission-presets.md
-reference_subsystems_persistence.md
-reference_subsystems_plan.md
-reference_subsystems_sandbox.md
-reference_subsystems_schedule.md
-reference_subsystems_scope.md
-reference_subsystems_session.md
-reference_subsystems_session-projection.md
-reference_subsystems_session-query.md
-reference_subsystems_session-reference.md
-reference_subsystems_session-telemetry.md
-reference_subsystems_session-title.md
-reference_subsystems_settings.md
-reference_subsystems_shell.md
-reference_subsystems_skills.md
-reference_subsystems_spill.md
-reference_subsystems_storage.md
-reference_subsystems_subagent.md
-reference_subsystems_subprocess.md
-reference_subsystems_system-prompt.md
-reference_subsystems_terminal.md
-reference_subsystems_token-meter.md
-reference_subsystems_tools.md
-reference_subsystems_typert.md
-reference_subsystems_user-questions.md
-reference_subsystems_web.md
-reference_subsystems_web-server.md
-reference_subsystems_workflow.md
-reference_subsystems_workspace.md
-reference_tool-catalog.md
-reference_tool-execution-pipeline.md
+develop\basic\config.md
+develop\basic\index.md
+develop\basic\publish.md
+develop\basic\tool.md
+develop\cordis-tutorial\01-first-plugin.md
+develop\cordis-tutorial\02-lifecycle-and-effects.md
+develop\cordis-tutorial\03-services.md
+develop\cordis-tutorial\04-events.md
+develop\cordis-tutorial\05-config.md
+develop\cordis-tutorial\06-composition-and-hmr.md
+develop\cordis-tutorial\07-into-the-harness.md
+develop\cordis-tutorial\index.md
+develop\framework\events.md
+develop\framework\index.md
+develop\framework\service.md
+develop\practice\dynamic-cordis.md
+develop\practice\index.md
+develop\practice\llm-adapter.md
+en\develop\basic\config.md
+en\develop\basic\index.md
+en\develop\basic\publish.md
+en\develop\basic\tool.md
+en\develop\cordis-tutorial\01-first-plugin.md
+en\develop\cordis-tutorial\02-lifecycle-and-effects.md
+en\develop\cordis-tutorial\03-services.md
+en\develop\cordis-tutorial\04-events.md
+en\develop\cordis-tutorial\05-config.md
+en\develop\cordis-tutorial\06-composition-and-hmr.md
+en\develop\cordis-tutorial\07-into-the-harness.md
+en\develop\cordis-tutorial\index.md
+en\develop\framework\events.md
+en\develop\framework\index.md
+en\develop\framework\service.md
+en\develop\practice\dynamic-cordis.md
+en\develop\practice\index.md
+en\develop\practice\llm-adapter.md
+en\guide\github-review.md
+en\guide\mcp-memory.md
+en\guide\providers.md
+en\guide\python-sdk.md
+en\guide\quickstart.md
+en\guide\schedule.md
+en\index.md
+en\reference\agent-lifecycle.md
+en\reference\api-gateway.md
+en\reference\capability-seams.md
+en\reference\config-catalog.md
+en\reference\cookbook\adding-a-package.md
+en\reference\cookbook\adding-a-settings-card.md
+en\reference\cookbook\adding-a-tool.md
+en\reference\cookbook\adding-an-llm-adapter.md
+en\reference\cookbook\extension-cookbook.md
+en\reference\cordis-api\context.md
+en\reference\cordis-api\events.md
+en\reference\cordis-api\fiber.md
+en\reference\cordis-api\inherited.md
+en\reference\cordis-api\registry.md
+en\reference\cordis-api\service.md
+en\reference\cordis-primer.md
+en\reference\index.md
+en\reference\persistence-catalog.md
+en\reference\subsystems\approval.md
+en\reference\subsystems\client-modules.md
+en\reference\subsystems\code-runtime.md
+en\reference\subsystems\commands.md
+en\reference\subsystems\compaction.md
+en\reference\subsystems\conversation.md
+en\reference\subsystems\core.md
+en\reference\subsystems\credentials.md
+en\reference\subsystems\filesystem.md
+en\reference\subsystems\goal.md
+en\reference\subsystems\index.md
+en\reference\subsystems\invariants.md
+en\reference\subsystems\jobs.md
+en\reference\subsystems\llm-streaming.md
+en\reference\subsystems\lsp.md
+en\reference\subsystems\permission-presets.md
+en\reference\subsystems\persistence.md
+en\reference\subsystems\plan.md
+en\reference\subsystems\sandbox.md
+en\reference\subsystems\schedule.md
+en\reference\subsystems\scope.md
+en\reference\subsystems\session-projection.md
+en\reference\subsystems\session-query.md
+en\reference\subsystems\session-reference.md
+en\reference\subsystems\session-telemetry.md
+en\reference\subsystems\session-title.md
+en\reference\subsystems\session.md
+en\reference\subsystems\settings.md
+en\reference\subsystems\shell.md
+en\reference\subsystems\skills.md
+en\reference\subsystems\slots.md
+en\reference\subsystems\spill.md
+en\reference\subsystems\storage.md
+en\reference\subsystems\subagent.md
+en\reference\subsystems\subprocess.md
+en\reference\subsystems\system-prompt.md
+en\reference\subsystems\terminal.md
+en\reference\subsystems\token-meter.md
+en\reference\subsystems\tools.md
+en\reference\subsystems\typert.md
+en\reference\subsystems\user-questions.md
+en\reference\subsystems\web-client.md
+en\reference\subsystems\web-server.md
+en\reference\subsystems\web.md
+en\reference\subsystems\workflow.md
+en\reference\subsystems\workspace.md
+en\reference\tool-catalog.md
+en\reference\tool-execution-pipeline.md
+guide\github-review.md
+guide\mcp-memory.md
+guide\providers.md
+guide\python-sdk.md
+guide\quickstart.md
+guide\schedule.md
+index.md
+reference\agent-lifecycle.md
+reference\api-gateway.md
+reference\capability-seams.md
+reference\config-catalog.md
+reference\cookbook\adding-a-package.md
+reference\cookbook\adding-a-settings-card.md
+reference\cookbook\adding-a-tool.md
+reference\cookbook\adding-an-llm-adapter.md
+reference\cookbook\extension-cookbook.md
+reference\cordis-api\context.md
+reference\cordis-api\events.md
+reference\cordis-api\fiber.md
+reference\cordis-api\inherited.md
+reference\cordis-api\registry.md
+reference\cordis-api\service.md
+reference\cordis-primer.md
+reference\index.md
+reference\persistence-catalog.md
+reference\subsystems\approval.md
+reference\subsystems\client-modules.md
+reference\subsystems\code-runtime.md
+reference\subsystems\commands.md
+reference\subsystems\compaction.md
+reference\subsystems\conversation.md
+reference\subsystems\core.md
+reference\subsystems\credentials.md
+reference\subsystems\filesystem.md
+reference\subsystems\goal.md
+reference\subsystems\index.md
+reference\subsystems\invariants.md
+reference\subsystems\jobs.md
+reference\subsystems\llm-streaming.md
+reference\subsystems\lsp.md
+reference\subsystems\permission-presets.md
+reference\subsystems\persistence.md
+reference\subsystems\plan.md
+reference\subsystems\sandbox.md
+reference\subsystems\schedule.md
+reference\subsystems\scope.md
+reference\subsystems\session-projection.md
+reference\subsystems\session-query.md
+reference\subsystems\session-reference.md
+reference\subsystems\session-telemetry.md
+reference\subsystems\session-title.md
+reference\subsystems\session.md
+reference\subsystems\settings.md
+reference\subsystems\shell.md
+reference\subsystems\skills.md
+reference\subsystems\slots.md
+reference\subsystems\spill.md
+reference\subsystems\storage.md
+reference\subsystems\subagent.md
+reference\subsystems\subprocess.md
+reference\subsystems\system-prompt.md
+reference\subsystems\terminal.md
+reference\subsystems\token-meter.md
+reference\subsystems\tools.md
+reference\subsystems\typert.md
+reference\subsystems\user-questions.md
+reference\subsystems\web-client.md
+reference\subsystems\web-server.md
+reference\subsystems\web.md
+reference\subsystems\workflow.md
+reference\subsystems\workspace.md
+reference\tool-catalog.md
+reference\tool-execution-pipeline.md

package/kb/meta/source.json

@@ -3,11 +3,11 @@
   "source": "官方文档站点 https://deepseek-harness.github.io/deepseek-harness/ （VitePress）",
   "repository": "https://github.com/deepseek-ai/deepseek-harness",
   "branch": "master",
-  "commit": "b150a551b8d465e31e418e1b2eaf5e79bbb7d28e",
-  "fetchedAt": "2026-08-21T13:35:39.256Z",
+  "commit": "cd5ef8148158c3a752a658978873241fdf8e2bbc",
+  "fetchedAt": "2026-08-30T10:00:08.912Z",
   "siteBase": "https://deepseek-harness.github.io/deepseek-harness",
-  "publishedMarkdownPages": 168,
-  "siteFiles": 172,
+  "publishedMarkdownPages": 182,
+  "siteFiles": 186,
   "images": 4,
-  "extraFiles": 52
+  "extraFiles": 56
 }

package/kb/meta/topics.md

@@ -38,25 +38,29 @@
 
 ## 9. 扩展点与能力分层
 - 核心：`site/develop/practice/index.md`（能力三层拆分）、`site/reference/capability-seams.md`
-- 扩展：`site/reference/cookbook/extension-cookbook.md`（扩展模式）、`site/reference/cookbook/adding-a-conversation-node.md`
+- 扩展：`site/reference/cookbook/extension-cookbook.md`（扩展模式）、`site/develop/practice/dynamic-cordis.md`（运行时动态装配 Cordis）
 
-## 10. 新增 Package / 设置卡片 / Conversation Node
-- 核心：`site/reference/cookbook/adding-a-package.md`、`site/reference/cookbook/adding-a-settings-card.md`、`site/reference/cookbook/adding-a-conversation-node.md`
+## 10. 新增 Package / 设置卡片
+- 核心：`site/reference/cookbook/adding-a-package.md`、`site/reference/cookbook/adding-a-settings-card.md`
 
 ## 11. 子系统能力速查（按需）
 - 总览：`site/reference/subsystems/index.md`
 - 内核与作用域：`core.md`、`scope.md`、`invariants.md`（运行时不变式）
-- 会话与持久化：`session.md`、`session-query.md`、`session-reference.md`、`session-title.md`、`session-projection.md`、`persistence.md`、`spill.md`、`session-telemetry.md`
+- 会话与持久化：`session.md`、`session-query.md`、`session-reference.md`、`session-title.md`、`session-projection.md`、`conversation.md`（Conversation Node 渲染）、`persistence.md`、`spill.md`、`session-telemetry.md`
 - 模型与上下文：`llm-streaming.md`、`token-meter.md`、`system-prompt.md`、`compaction.md`（上下文压缩）
 - 执行与工具：`tools.md`、`shell.md`（Bash）、`subprocess.md`、`terminal.md`（PTY）、`jobs.md`（后台任务）、`filesystem.md`、`lsp.md`、`code-runtime.md`、`web.md`、`skills.md`、`workflow.md`、`subagent.md`
 - 策略与交互：`approval.md`（审批）、`permission-presets.md`、`sandbox.md`、`plan.md`（计划模式）、`user-questions.md`、`commands.md`、`goal.md`、`schedule.md`
-- 平台与接入：`web-server.md`（HTTP 服务器）、`typert.md`、`client-modules.md`、`storage.md`、`workspace.md`、`settings.md`、`credentials.md`
+- 平台与接入：`web-server.md`（HTTP 服务器）、`web-client.md`（Web 客户端注入）、`slots.md`（UI 插槽系统）、`typert.md`、`client-modules.md`、`storage.md`、`workspace.md`、`settings.md`、`credentials.md`
 - 以上均在 `site/reference/subsystems/` 下（如 `site/reference/subsystems/session.md`）
 
 ## 12. 架构与核心概念
 - 核心：`site/reference/index.md`（架构总览：组合、核心包、循环、seam、扩展点）、`site/reference/cordis-primer.md`（Cordis 入门）
 - 扩展：`extra/glossary.md`（术语表：capability seam 等）、`extra/module-graph.md`（模块依赖全景图，大文件请 grep）、`extra/graph-atlas.md`
 
+## 12b. API Gateway 与服务接入
+- 核心：`site/reference/api-gateway.md`（Typert API Gateway：Remote 方法声明、Host/Client 约定、RPC 与 `/api` 路由复用）
+- 扩展：`extra/subsystems/webhook.md`（webhook 接入，仓库文档）、`site/reference/subsystems/typert.md`
+
 ## 13. 系统提示词 / Token / 上下文压缩
 - `site/reference/subsystems/system-prompt.md`、`token-meter.md`、`compaction.md`
 
@@ -69,7 +73,11 @@
 ## 16. 中英对照
 - 英文站：`site/en/`（结构与中文站一致：`guide/`、`develop/`、`reference/`）；`INDEX.md` 有全部 URL ↔ 文件对照
 
+## 17. 使用指南进阶（GitHub Review / 定时任务 / MCP 记忆）
+- `site/guide/github-review.md`（用 dsh 做 GitHub 代码评审）、`site/guide/schedule.md`（定时任务）、`site/guide/mcp-memory.md`（MCP 与长期记忆）
+- 扩展：`site/reference/subsystems/schedule.md`、`extra/subsystems/todo.md`（仓库文档）
+
 ## 检索技巧
-- 全量索引：`meta/search-index.json`（223 个文件的 path/url/title/字符数）
+- 全量索引：`meta/search-index.json`（241 个文件的 path/url/title/字符数）
 - 大文件（config-catalog / tool-catalog / module-graph / subsystems/session 等 ≥100KB）先用 grep 定位关键行，再 read 局部，不要整读
 - 常用检索关键词：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`

package/kb/site/develop/basic/publish.md

@@ -55,7 +55,7 @@ export function apply() {
 }
 ```
 
-创建 `hello-plugin/cordis.patch.yml`。这个 patch 与一直在写的 `--patch` overlay 一样，是一个 patch 条目的 YAML 数组；区别是插件行按包名而不是相对源码路径引用这个包，这样 Node 的模块解析才能找到已安装的代码：
+创建 `hello-plugin/cordis.patch.yml`。这个 patch 与你写过的 `--patch` overlay 一样，是一个 patch 条目的 YAML 数组；区别是插件行按包名而不是相对源码路径引用这个包，这样 Node 的模块解析才能找到已安装的代码：
 
 ```yaml
 - insert:
@@ -172,7 +172,7 @@ dsh plugin --profile demo add github:you/hello-plugin
 
   然后重新执行 `add`。
 
-请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
+请把这项授权视为**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
 
 如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
 

package/kb/site/develop/basic/tool.md

@@ -50,5 +50,5 @@ pnpm dsh web --patch ./scratch-plugin/cordis.yml
 ## 下一步
 
 - [插件配置](./config.md) — 让问候语可配置。
-- [工具编写参考](../../reference/cookbook/adding-a-tool.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、Code Mode 和 UI 卡片。
+- [工具编写参考](../../reference/cookbook/adding-a-tool.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、PTC mode 和 UI 卡片。
 - [能力分层](../practice/index.md) — 将可替换能力拆分为 Service Definition、Service Provider 和 Consumer 三类包。

package/kb/site/develop/cordis-tutorial/07-into-the-harness.md

@@ -13,7 +13,7 @@ editSource: "docs/cordis-tutorial/07-into-the-harness.zh.md"
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { CallId } from '@deepseek-ai/dsh-llm'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
 
 export const name = 'greet-tool'
 export const inject = ['tools']
@@ -35,10 +35,10 @@ export function apply(ctx: Context) {
   }))
 
   // Drive one call through the real execution pipeline, standing in for
-  // the model. CallId brands the correlation id a provider would issue.
+  // the model. ToolCallId brands the correlation id a provider would issue.
   void (async () => {
     const result = await ctx.tools.execute({
-      callId: CallId('demo-1'),
+      callId: ToolCallId('demo-1'),
       name: 'greet',
       arguments: { name: 'Cordis' },
       signal: new AbortController().signal,
@@ -97,7 +97,7 @@ logger 会先触发：`tools/result` 在结果物化过程中发出，发生在
 
 ## 从这里走向完整 agent（智能体）
 
-真实 agent 就是这套组合再加上更多插件：LLM（大语言模型）适配器、agent loop（智能体循环）、持久化和运行入口。对照 [examples/headless-agent/cordis.yml](https://github.com/deepseek-ai/deepseek-harness/blob/master/examples/headless-agent/cordis.yml)，你现在已经可以读懂其中每个配置项。将 `greet-tool.ts` 加入该文件的副本即可。
+真实 agent 就是这套组合再加上更多插件：LLM（大语言模型）适配器、agent loop（智能体循环）、持久化和应用入口。对照 [base profile 层](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/base/cordis.patch.yml)与 [headless 层](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/headless/cordis.patch.yml)，你现在已经可以读懂其中各项。通过一个小型 `--patch` overlay 加入 `greet-tool.ts` 即可。
 
 后续可以阅读：
 

package/kb/site/develop/framework/events.md

@@ -103,7 +103,7 @@ declare module '@deepseek-ai/cordis' {
 
 ## Cordis 事件与会话记录
 
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../reference/subsystems/core.md)上生成的 `cordis-surface` 区块。
+Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../reference/subsystems/core.md)上生成的 `cordis-surface` 区块。
 
 `turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compaction/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
 

package/kb/site/develop/practice/dynamic-cordis.md

@@ -0,0 +1,17 @@
+---
+editSource: "docs/user/develop/practice/dynamic-cordis.zh.md"
+---
+
+# 用 Cordis 工具扩展运行中的智能体
+
+本实战指南启用 [`@deepseek-ai/dsh-tool-cordis`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.zh.md)。智能体可以检查当前 Cordis 进程，并在内存中挂载或卸载模型编写的插件。临时插件会在卸载或进程退出时消失，并可能影响同一进程中的其他会话。
+
+## 运行
+
+使用仓库内 overlay 启动浏览器界面：
+
+```sh
+pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
+```
+
+该命令需要模型凭据。[Cordis 工具参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.zh.md)定义了四类约定：工具参数、存续时间、清理行为和安全性。

package/kb/site/develop/practice/llm-adapter.md

@@ -56,7 +56,7 @@ export function apply(ctx: Context, config: Config) {
 `stream()` 必须按以下协议生成分片：
 
 ```ts
-import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import { ToolCallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
 
 async function* exampleChunks(): AsyncIterable<StreamChunk> {
   // 1. Start each content block with block-start.
@@ -78,7 +78,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
   yield {
     type: 'tool-call-delta',
     index: 1,
-    id: CallId('call-123'),
+    id: ToolCallId('call-123'),
     name: 'bash',
     argumentsDelta: '{"command":"ls"}',
   }
@@ -87,7 +87,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
     index: 1,
     block: {
       type: 'tool-call',
-      id: CallId('call-123'),
+      id: ToolCallId('call-123'),
       name: 'bash',
       arguments: '{"command":"ls"}',
     },

package/kb/site/en/develop/basic/publish.md

@@ -55,7 +55,7 @@ export function apply() {
 }
 ```
 
-Create `hello-plugin/cordis.patch.yml`. The patch is a YAML array like the `--patch` overlays you have been writing, except plugin rows reference the package by name instead of a relative source path so Node resolution finds the installed code:
+Create `hello-plugin/cordis.patch.yml`. The patch is a YAML array like the `--patch` overlays you wrote, except plugin rows reference the package by name instead of a relative source path so Node resolution finds the installed code:
 
 ```yaml
 - insert:
@@ -172,7 +172,7 @@ But a git install fetches **sources, not built artifacts**: nothing runs your `b
 
   and re-run the `add`.
 
-Treat that allowance as what it is: **permission to execute the package's code on your machine at install time**, outside any sandbox the agent runs under. Only allow packages whose source you trust, and pin a commit (`github:you/hello-plugin#<sha>`) so a later push cannot silently change what runs.
+Treat that allowance as **permission to execute the package's code on your machine at install time**, outside any sandbox the agent runs under. Only allow packages whose source you trust, and pin a commit (`github:you/hello-plugin#<sha>`) so a later push cannot silently change what runs.
 
 If you would rather not ask users for the allowance, distribute built artifacts instead — neither form needs any build permission:
 

package/kb/site/en/develop/basic/tool.md

@@ -50,5 +50,5 @@ Open `http://127.0.0.1:3080` and ask: `Use the greet tool to greet Ada.` The mod
 ## Next steps
 
 - [Plugin configuration](./config.md) — make the greeting configurable.
-- [Tool authoring reference](../../reference/cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, Code Mode, and UI cards.
+- [Tool authoring reference](../../reference/cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, PTC mode, and UI cards.
 - [Capability layering](../practice/index.md) — split a replaceable capability into Service Definition, Service Provider, and Consumer packages.

package/kb/site/en/develop/cordis-tutorial/07-into-the-harness.md

@@ -13,7 +13,7 @@ Create `greet-tool.ts` in `tmp/cordis-tutorial`:
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { CallId } from '@deepseek-ai/dsh-llm'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
 
 export const name = 'greet-tool'
 export const inject = ['tools']
@@ -35,10 +35,10 @@ export function apply(ctx: Context) {
   }))
 
   // Drive one call through the real execution pipeline, standing in for
-  // the model. CallId brands the correlation id a provider would issue.
+  // the model. ToolCallId brands the correlation id a provider would issue.
   void (async () => {
     const result = await ctx.tools.execute({
-      callId: CallId('demo-1'),
+      callId: ToolCallId('demo-1'),
       name: 'greet',
       arguments: { name: 'Cordis' },
       signal: new AbortController().signal,
@@ -97,7 +97,7 @@ The logger fired first: `tools/result` is emitted as part of result materializat
 
 ## From here to a full agent
 
-A real agent is this composition plus more plugins: an LLM adapter, the agent loop, persistence, an entry point. Compare [examples/headless-agent/cordis.yml](https://github.com/deepseek-ai/deepseek-harness/blob/master/examples/headless-agent/cordis.yml) — you can read every entry in it now. Add your `greet-tool.ts` to a copy of that file.
+A real agent is this composition plus more plugins: an LLM adapter, the agent loop, persistence, and an application entry. Compare the [base profile layer](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/base/cordis.patch.yml) and [headless layer](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/headless/cordis.patch.yml) — you can read their entries now. Add your `greet-tool.ts` through a small `--patch` overlay.
 
 Where to go next:
 

package/kb/site/en/develop/framework/events.md

@@ -103,7 +103,7 @@ declare module '@deepseek-ai/cordis' {
 
 ## Cordis events and session records
 
-Harness Cordis events use `namespace/action` names, including `agent/step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../reference/subsystems/core.md) record complete signatures and modes.
+Harness Cordis events use `namespace/action` names, including `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, and `session/event`. The generated `cordis-surface` regions on the [subsystem pages](../../reference/subsystems/core.md) record complete signatures and modes.
 
 `turn/*`, `step/*`, `tool/call`, `tool/result`, and `compaction/*` are durable session-event types, not same-named Cordis events. To observe them, listen to `session/event` and inspect `event.type`.
 

package/kb/site/en/develop/practice/dynamic-cordis.md

@@ -0,0 +1,17 @@
+---
+editSource: "docs/user/develop/practice/dynamic-cordis.md"
+---
+
+# Extend a running agent with Cordis tools
+
+This practice guide enables [`@deepseek-ai/dsh-tool-cordis`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.md). The agent can inspect its current Cordis process and mount or unmount model-authored plugins in memory. Temporary plugins disappear when they are unmounted or the process exits and may affect other sessions in the same process.
+
+## Run it
+
+Start the browser interface with the checked-in overlay:
+
+```sh
+pnpm dsh web --patch apps/cli/config/examples/cordis/cordis.yml
+```
+
+The command requires a model credential. The [Cordis tool reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/extensions/tool-cordis/README.md) defines the tool arguments, lifetime, cleanup, and safety contracts.