dsh-plugin-dev-kb 1.1.0 → 1.4.0

package/kb/meta/site-pages.txt

@@ -1,184 +1,188 @@
-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\network-proxy.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-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\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.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\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.md
-en\reference\subsystems\web-client.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\github-review.md
-guide\mcp-memory.md
-guide\network-proxy.md
-guide\providers.md
-guide\python-sdk.md
-guide\quickstart.md
-guide\schedule.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/network-proxy.md
+en/guide/providers.md
+en/guide/public-deployments.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-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/client-resources.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/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/ptc-runtime.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/sidebar-right.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.md
+en/reference/subsystems/web-client.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/github-review.md
+guide/mcp-memory.md
+guide/network-proxy.md
+guide/providers.md
+guide/public-deployments.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-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\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.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\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.md
-reference\subsystems\web-client.md
-reference\subsystems\web-server.md
-reference\subsystems\workflow.md
-reference\subsystems\workspace.md
-reference\tool-catalog.md
-reference\tool-execution-pipeline.md
+reference/agent-lifecycle.md
+reference/api-gateway.md
+reference/capability-seams.md
+reference/config-catalog.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/client-resources.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/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/ptc-runtime.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/sidebar-right.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.md
+reference/subsystems/web-client.md
+reference/subsystems/web-server.md
+reference/subsystems/workflow.md
+reference/subsystems/workspace.md
+reference/tool-catalog.md
+reference/tool-execution-pipeline.md

package/kb/meta/source.json

@@ -1,13 +1,13 @@
-{
-  "knowledgeBase": "DeepSeek Harness 官方文档知识库",
-  "source": "官方文档站点 https://deepseek-harness.github.io/deepseek-harness/ （VitePress）",
+{
+  "knowledgeBase": "DeepSeek Harness 瀹樻柟鏂囨。鐭ヨ瘑搴?,
+  "source": "瀹樻柟鏂囨。绔欑偣 https://deepseek-harness.github.io/deepseek-harness/ 锛圴itePress锛?,
   "repository": "https://github.com/deepseek-ai/deepseek-harness",
   "branch": "master",
-  "commit": "d347e703908d0406b7a7ef80e3a0e594d86b2215",
-  "fetchedAt": "2026-09-05T10:10:32.663Z",
+  "commit": "5badb15009ae1756c3afe0ae0cef1faafc290ccc",
+  "fetchedAt": "2026-10-09T05:23:13.081Z",
   "siteBase": "https://deepseek-harness.github.io/deepseek-harness",
-  "publishedMarkdownPages": 184,
-  "siteFiles": 188,
+  "publishedMarkdownPages": 188,
+  "siteFiles": 192,
   "images": 4,
-  "extraFiles": 58
+  "extraFiles": 182
 }

package/kb/meta/topics.md

@@ -30,7 +30,7 @@
 
 ## 7. 打包与发布插件
 - 核心：`site/develop/basic/publish.md`
-- 扩展：`extra/cookbook/adding-a-vendored-package.md`（vendored 包）
+- 扩展：`extra/cookbook/adding-a-vendored-package.md`（vendored 包）、`extra/cookbook/adding-a-session-format-version.md`（新增会话格式版本号）、`extra/session-format-status.md`（会话格式状态）
 
 ## 8. LLM 适配器
 - 核心：`site/develop/practice/llm-adapter.md`、`site/reference/cookbook/adding-an-llm-adapter.md`
@@ -45,12 +45,12 @@
 
 ## 11. 子系统能力速查（按需）
 - 总览：`site/reference/subsystems/index.md`
-- 内核与作用域：`core.md`、`scope.md`、`invariants.md`（运行时不变式）
+- 内核与作用域：`core.md`、`scope.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`
+- 执行与工具：`tools.md`、`shell.md`（Bash）、`subprocess.md`、`terminal.md`（PTY）、`jobs.md`（后台任务）、`filesystem.md`、`lsp.md`、`ptc-runtime.md`（原 code-runtime，dsh 0.2.0 更名）、`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 服务器）、`web-client.md`（Web 客户端注入）、`slots.md`（UI 插槽系统）、`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`、`client-resources.md`、`storage.md`、`workspace.md`、`settings.md`、`credentials.md`、`sidebar-right.md`
 - 以上均在 `site/reference/subsystems/` 下（如 `site/reference/subsystems/session.md`）
 
 ## 12. 架构与核心概念
@@ -65,7 +65,7 @@
 - `site/reference/subsystems/system-prompt.md`、`token-meter.md`、`compaction.md`
 
 ## 14. 测试与防御
-- `extra/testing.md`（测试策略：快照/e2e/单测边界）、`extra/defensive-patterns.md`、`extra/postmortem/`（事故复盘 4 篇，含沙箱/进程故障模式）
+- `extra/testing.md`（测试策略：快照/e2e/单测边界）、`extra/defensive-patterns.md`、`extra/postmortem/`（事故复盘，含沙箱/进程故障模式）
 
 ## 15. 文档规范与贡献
 - `extra/AGENTS.md`（文档分层标准：tutorial/reference、字数预算）、`extra/development.md`（开发环境与工作流）、`extra/i18n/`（双语规范与术语）
@@ -74,10 +74,14 @@
 - 英文站：`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/guide/network-proxy.md`（代理后运行：HTTPS_PROXY 等环境变量、哪些路径保持直连）
+- `site/guide/github-review.md`（用 dsh 做 GitHub 代码评审）、`site/guide/schedule.md`（定时任务）、`site/guide/mcp-memory.md`（MCP 与长期记忆）、`site/guide/network-proxy.md`（代理后运行：HTTPS_PROXY 等环境变量、哪些路径保持直连）、`site/guide/public-deployments.md`（公共部署）
 - 扩展：`site/reference/subsystems/schedule.md`、`extra/subsystems/todo.md`（仓库文档）
 
+## 17b. 版本升级与持久化变更（dsh 0.1.x → 0.2.x 重点）
+- `extra/upgrade-guide/`（各版本升级指南：0.1.7-rc.2 / 0.2.0-rc.2，含 schedule-bundle-retired、remove-runtime-invariants、subpath-plugin-display-manifest 等）
+- `extra/persistence-changes/`（持久化格式变更记录与历史格式，含 releases/、historical-formats/）
+
 ## 检索技巧
-- 全量索引：`meta/search-index.json`（245 个文件的 path/url/title/字符数）
+- 全量索引：`meta/search-index.json`（373 个文件的 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/config.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/config.zh.md"
+rawMarkdownPath: "develop/basic/config.md"
 ---
 
 # 插件配置

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

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/index.zh.md"
+rawMarkdownPath: "develop/basic/index.md"
 ---
 
 # 第一个插件

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

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/publish.zh.md"
+rawMarkdownPath: "develop/basic/publish.md"
 ---
 
 # 打包与安装插件
@@ -63,7 +64,7 @@ export function apply() {
       name: dsh-hello-plugin
 ```
 
-没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
+`patch` 也接受一个有序的文件列表，例如 `["./base.patch.yml", "./web.patch.yml"]`；launcher 按该顺序把它们作为同一层应用，每个文件中的相对插件路径相对于该文件解析。没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
 
 ### profile manifest
 
@@ -72,7 +73,7 @@ profile 目录包含两个文件：
 - `package.json` — profile 的树外插件依赖（由 pnpm 管理），加上 `dsh.profile` manifest 及其有序的 `bundles` 列表。
 - `cordis.patch.yml` — 用户自己的 patch 层，在每个组合包层之后应用。
 
-profile manifest 从不需要手写：`dsh plugin` 负责创建和维护它。下一节展示其结果。
+profile manifest 从不需要手写：`dsh --profile <name> --from-default-profile <template>` 可以从随附应用模板创建 profile，`dsh plugin` 则创建一个以 base 为基础的 profile，并维护其中已安装的 bundle 列表。创建规则以 [CLI（命令行界面）行为参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.zh.md#profile-boot)为准；下一节展示插件路径。
 
 ## 安装进 profile
 
@@ -102,6 +103,12 @@ dsh plugin --profile demo add ./hello-plugin
 }
 ```
 
+通过链接安装的 checkout 保留自己的 `node_modules`。与 harness 自身的包一样，需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies` 中。在该 manifest 的查询位置，运行中 dsh 的 runtime resolution 已包含的 peer 使用安装中的副本；devDependency 副本供类型检查和独立测试使用。需要独立版本的第三方依赖和无状态 dsh 工具包放在 `dependencies` 中。
+
+普通 linked import 遵循 Node 的祖先顺序，检查每个目录当前的 peer 声明。更近的物理包先于更高的 peer 声明。link 目标可以没有 `package.json`，祖先 peer 仍可生效，即使该 manifest 旁没有物理 `node_modules`。显式 `require.resolve(..., { paths })` 始终是原生查询，包括指向 profile 内的路径。npm、Desktop 与源码启动共用这些规则；规则不会使已加载模块失效，也不校验 peer 版本范围。作用域和文件查询行为见[解析规则](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md)。
+
+链接整个 checkout 不会对运行中安装自身的包目录应用 peer 拦截。目标仍位于 profile 内的链接（包括它的 pnpm store）属于 profile 自己安装的内容，不算外部 linked root。外部链接互相重叠也不改变查找顺序，每个请求仍从其 importer 所在目录开始。
+
 先不启动、只验证该层，再启动：
 
 ```sh
@@ -162,7 +169,7 @@ dsh plugin --profile demo add github:you/hello-plugin
 
 但 git 安装拉取的是**源码，不是构建产物**：没有任何环节运行你的 `build` 脚本，因此 TypeScript 包到手时没有 `lib/` 输出，加载会失败。必须两边各做一件事：
 
-- **作者**提供一个 `prepare` 脚本——pnpm 在 git 安装后运行它——从源码构建出发布入口，且必须自包含：不能假设仅开发环境才有的上下文，例如旁边有一份 monorepo checkout。[turtle-ui](https://github.com/deepseek-harness/turtle-ui) 是一个可用的例子：它的 `prepare` 运行一份专用的 tsdown 配置，直接转译 `src/`，不用项目引用，也不做类型检查。
+- **作者**提供一个 `prepare` 脚本——pnpm 在 git 安装后运行它——从源码构建出发布入口，且必须自包含：不能假设仅开发环境才有的上下文，例如旁边有一份 monorepo checkout。专用的 tsdown 配置可以直接转译 `src/`，不用项目引用，也不做类型检查。
 - **用户**为构建授权。pnpm ≥10 在得到显式允许之前拒绝运行 git 依赖的 `prepare` 脚本，所以第一次 `add` 会失败；`dsh` 会指出修法——把 pnpm 打印的确切包键复制进该 profile 的 `pnpm-workspace.yaml`：
 
   ```yaml

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

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/user/develop/basic/tool.zh.md"
+rawMarkdownPath: "develop/basic/tool.md"
 ---
 
 # 开发一个工具

package/kb/site/develop/cordis-tutorial/01-first-plugin.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/01-first-plugin.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/01-first-plugin.md"
 ---
 
 # 1. 编写第一个插件

package/kb/site/develop/cordis-tutorial/02-lifecycle-and-effects.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/02-lifecycle-and-effects.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/02-lifecycle-and-effects.md"
 ---
 
 # 2. 生命周期与 effect

package/kb/site/develop/cordis-tutorial/03-services.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/03-services.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/03-services.md"
 ---
 
 # 3. 服务

package/kb/site/develop/cordis-tutorial/04-events.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/04-events.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/04-events.md"
 ---
 
 # 4. 事件

package/kb/site/develop/cordis-tutorial/05-config.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/05-config.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/05-config.md"
 ---
 
 # 5. 配置
@@ -69,6 +70,33 @@ ValidationError: invalid config:
 
 插件的 fiber 进入 FAILED 状态，本教程的启动器打印错误后以状态码 1 退出。如果某个插件的配置通过了 schema 验证，但其中指定的资源或提供方不可用，该插件也应当在能解析该引用时立即拒绝。
 
+<a id="volatile-fields"></a>
+## Volatile 字段
+
+对于插件在每次操作中读取的字段，可以使用 `.volatile()`。字段变化会更新稳定引用，无需重新挂载插件。通过 `.get()` 读取：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import Schema from '@deepseek-ai/schemastery'
+
+export const Config = Schema.object({
+  greeting: Schema.string().default('Hello').volatile(),
+})
+
+export function apply(ctx: Context, config: ReturnType<typeof Config>) {
+  ctx.on('loader/volatile-update', () => {
+    console.log(config.greeting.get())
+  })
+}
+```
+
+直接调用 `Config(raw)` 也会返回引用。没有默认值的可选字段仍然具有引用；字段缺省时，`.get()` 返回 `undefined`。可以保存引用，也可以在单次操作中保存读取值，包括跨越 `await`，但不能将该值用于后续操作。对象和数组值是脱离输入、递归冻结的普通数据快照；函数、类实例和循环引用会被拒绝。
+
+Loader 比较原始配置时忽略 schema 声明的 volatile 字段。仅 volatile 变化会经目标插件的 `internal/config` 钩子解析并校验；当所有普通字段的有效值仍然一致时，Loader 把新值提交到运行中的引用，并向所属实例发出一次 `loader/volatile-update`，参数是以键数组表示的变化路径，不进入目标插件的 `internal/update`。等值更新不通知。无效候选会记录日志，运行中的引用保持不变，直到下次激活。普通字段有效值变化（包括表达式求值结果变化）以及普通字段同时变化时沿用原更新流程，旧引用不更新也不接收通知。Group/Include 仍分发子条目更新。直接 `fiber.update()`、代码替换和依赖替换保留原有生命周期；`noSave` 仍控制直接更新的持久化。通知使用普通 `emit`，不等待资源重新配置完成。
+
+在固定对象路径上声明 volatile 字段，或将整个对象、数组标记为 volatile。数组、字典、union 或 intersect 分支、lazy、transform 或另一个 volatile 值内部的独立引用会被拒绝。配置文件保存普通值；`simplify()` 会解包引用。序列化 schema 保留字段类型、默认值、角色和 volatile 标记，供基于 schema 的表单使用。现有 settings 消费者继续使用原有 settings 接口。
+
 ## 计算得到的配置值
 
 本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值：

package/kb/site/develop/cordis-tutorial/06-composition-and-hmr.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/cordis-tutorial/06-composition-and-hmr.zh.md"
+rawMarkdownPath: "develop/cordis-tutorial/06-composition-and-hmr.md"
 ---
 
 # 6. 组合与 HMR（热模块替换）
@@ -24,7 +25,7 @@ Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
 
 ## 热模块替换
 
-卸载会释放 effect（[第 2 章](./02-lifecycle-and-effects.md)），加载则遵循依赖关系（[第 3 章](./03-services.md)），因此 HMR 可以先卸载、再加载，以替换正在运行的插件。`@deepseek-ai/cordis-plugin-hmr` 插件会监视文件，并在保存时执行这一过程。
+卸载会释放 effect（[第 2 章](./02-lifecycle-and-effects.md)），加载则遵循依赖关系（[第 3 章](./03-services.md)），因此 HMR 可以先卸载、再加载，以替换正在运行的插件。`@deepseek-ai/dsh-hmr` 插件会监视文件，并在保存时执行这一过程。
 
 在 `tmp/cordis-tutorial` 中编写 `cordis.yml`：
 
@@ -34,7 +35,7 @@ Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
 - id: timer
   name: '@deepseek-ai/cordis-plugin-timer'
 - id: hmr
-  name: '@deepseek-ai/cordis-plugin-hmr'
+  name: '@deepseek-ai/dsh-hmr'
   config:
     root: ['.']
 - id: hello