dsh-plugin-guide 0.3.1 → 0.3.2

package/references/official-docs/docs/user/develop/basic/config.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/config.md
-config.md: 21ba39fd7de1795e9139aff3e2b11743eedd4833
-config.zh.md: a882c4d59b0ac8e8ec27a5b32da5376b534a7f62
+config.md: d935fc3f3b5b42c5b3fbd8d3b0d398a2608aead3
+config.zh.md: 642a413950e2d8deb8591bc688968607604c050d

package/references/official-docs/docs/user/develop/basic/config.md

@@ -102,5 +102,5 @@ A configuration edit hot-replaces the plugin: the framework unloads the old inst
 ## Next steps
 
 - [Package and install a plugin](./publish.md) — ship the plugin as an installable package
-- [Plugins and lifecycle](../framework/) — understand the full plugin lifecycle
+- [Plugins and lifecycle](../framework/index.md) — understand the full plugin lifecycle
 - [Services and dependencies](../framework/service.md) — provide a service to other plugins

package/references/official-docs/docs/user/develop/basic/config.zh.md

@@ -93,7 +93,7 @@ export interface Config {
 
 ### 配置错误要响亮
 
-在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.md) 会介绍这项约定。
+在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.zh.md) 会介绍这项约定。
 
 ## 配合 HMR
 
@@ -101,6 +101,6 @@ export interface Config {
 
 ## 下一步
 
-- [打包与安装插件](./publish.md) — 把插件以可安装包的形式交付
-- [插件与生命周期](../framework/) — 深入了解插件的完整生命周期
-- [服务与依赖](../framework/service.md) — 让你的插件对外提供服务
+- [打包与安装插件](./publish.zh.md) — 把插件以可安装包的形式交付
+- [插件与生命周期](../framework/index.zh.md) — 深入了解插件的完整生命周期
+- [服务与依赖](../framework/service.zh.md) — 让你的插件对外提供服务

package/references/official-docs/docs/user/develop/basic/index.i18n.yaml

@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/index.md
 index.md: 08199624e638aaf4a36b04446c39c228b2af6025
-index.zh.md: c45a30d0bfffaf4a6c78303f9ca043c3397c8a08
+index.zh.md: 2ea894079ffb3c5b8c4563fd535fe6e654861b1b

package/references/official-docs/docs/user/develop/basic/index.zh.md

@@ -2,7 +2,7 @@
 
 [English](index.md) | 中文
 
-本教程会创建一个最小的 Harness 插件，并将其加载到 Web UI 中。请从已完成[从源码运行路径](../../../../README.md#run-from-source)的仓库检出开始。
+本教程会创建一个最小的 Harness 插件，并将其加载到 Web UI 中。请从已完成[从源码运行路径](../../../../README.zh.md#run-from-source)的仓库检出开始。
 
 ## 创建本地项目
 
@@ -135,10 +135,10 @@ export default class MyService extends Service {
 }
 ```
 
-大多数情况下，函数形式足够了。当插件需要向其他插件提供服务时，可使用类形式（见 [服务与依赖](../framework/service.md)）。
+大多数情况下，函数形式足够了。当插件需要向其他插件提供服务时，可使用类形式（见 [服务与依赖](../framework/service.zh.md)）。
 
 ## 下一步
 
-- [开发一个工具](./tool.md) — 了解工具定义 DSL
-- [插件配置](./config.md) — 让插件接受用户配置
-- [Cordis 框架教程](../../../cordis-tutorial/index.md) — 底层的插件框架，在临时目录中动手构建，无需 API 密钥
+- [开发一个工具](./tool.zh.md) — 了解工具定义 DSL
+- [插件配置](./config.zh.md) — 让插件接受用户配置
+- [Cordis 框架教程](../../../cordis-tutorial/index.zh.md) — 底层的插件框架，在临时目录中动手构建，无需 API 密钥

package/references/official-docs/docs/user/develop/basic/publish.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md
-publish.md: 9548fe2f8e4636dd160c79cd0d50f01f8bdfd3d1
-publish.zh.md: 2cff05edcca55bac5fde9d2e7d24ed9c8b48a6f5
+publish.md: 89a28e2e44a5171a3f5c48c003f5af5ec2e9e750
+publish.zh.md: 590fee6f035af3009e25bf3669ba4321951f7d07

package/references/official-docs/docs/user/develop/basic/publish.md

@@ -53,7 +53,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:
@@ -170,7 +170,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:
 
@@ -179,5 +179,5 @@ If you would rather not ask users for the allowance, distribute built artifacts
 
 ## Next steps
 
-- [Plugins and lifecycle](../framework/) — the full plugin lifecycle
+- [Plugins and lifecycle](../framework/index.md) — the full plugin lifecycle
 - [CLI behavior reference](../../../../apps/cli/reference/README.md) — exact layer precedence, flags, and profile mechanics

package/references/official-docs/docs/user/develop/basic/publish.zh.md

@@ -2,9 +2,9 @@
 
 [English](publish.md) | 中文
 
-前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。本文假设 `dsh` CLI 已安装。请先完成[插件配置](./config.md)。
+前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。本文假设 `dsh` CLI 已安装。请先完成[插件配置](./config.zh.md)。
 
-如果改用全新的源码 checkout，请先按照[从源码运行章节](../../../../README.md#run-from-source)完成准备，将本教程的 `hello-plugin` 目录放在仓库根目录，并从该目录把下文的 `dsh ...` 命令改为 `pnpm dsh ...`。构建与启动器行为见[源码执行](../../../../apps/cli/reference/README.md#source-execution)。
+如果改用全新的源码 checkout，请先按照[从源码运行章节](../../../../README.zh.md#run-from-source)完成准备，将本教程的 `hello-plugin` 目录放在仓库根目录，并从该目录把下文的 `dsh ...` 命令改为 `pnpm dsh ...`。构建与启动器行为见[源码执行](../../../../apps/cli/reference/README.zh.md#source-execution)。
 
 ## 两个概念，两种 manifest
 
@@ -53,7 +53,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:
@@ -136,7 +136,7 @@ dsh --profile demo
   name: 'dsh-hello-plugin/startup'
 ```
 
-该插件导出 `inject = ['cmdlineArgs']`，使用自己的 commander program 调用 [`@deepseek-ai/dsh-cmdline`](../../../../packages/boot/cmdline/README.md) 中的 `parseCmdline`，再在 program 自己的 action 中把应用自有服务提供出去。启动器把自身 flag 之后的同一份不可变参数交给每个插件，因此添加应用专属 flag 无需修改启动器，多个插件也可以解析该快照。Loader 行不需要启动器标记或特殊类型。
+该插件导出 `inject = ['cmdlineArgs']`，使用自己的 commander program 调用 [`@deepseek-ai/dsh-cmdline`](../../../../packages/boot/cmdline/README.zh.md) 中的 `parseCmdline`，再在 program 自己的 action 中把应用自有服务提供出去。启动器把自身 flag 之后的同一份不可变参数交给每个插件，因此添加应用专属 flag 无需修改启动器，多个插件也可以解析该快照。Loader 行不需要启动器标记或特殊类型。
 
 受这些参数配置的行会注入提供方服务，并在自己的 `!!js` 选项中读取它，同时把部署取值写在旁边作为回退：
 
@@ -170,7 +170,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>`），让后续推送无法悄悄改变实际运行的内容。
 
 如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
 
@@ -179,5 +179,5 @@ dsh plugin --profile demo add github:you/hello-plugin
 
 ## 下一步
 
-- [插件与生命周期](../framework/) — 插件的完整生命周期
-- [CLI（命令行界面）行为参考](../../../../apps/cli/reference/README.md) — 确切的层优先级、flag 与 profile 机制
+- [插件与生命周期](../framework/index.zh.md) — 插件的完整生命周期
+- [CLI（命令行界面）行为参考](../../../../apps/cli/reference/README.zh.md) — 确切的层优先级、flag 与 profile 机制

package/references/official-docs/docs/user/develop/basic/tool.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/basic/tool.md
-tool.md: eb262d131a7f2b540827e86e56f8c0a28cb5f904
-tool.zh.md: d33d9946a73881df2cd44ebf3695819d02d013ab
+tool.md: aeed5cf0e742cdde33bdcb86bfac4de471ae2597
+tool.zh.md: 25538e42b7777fe3b05b361379a8bce70d6ec5f5

package/references/official-docs/docs/user/develop/basic/tool.md

@@ -2,7 +2,7 @@
 
 English | [中文](tool.zh.md)
 
-This tutorial adds a `greet` tool to the Web UI. Complete [Your first plugin](./) first and keep its `scratch-plugin` directory.
+This tutorial adds a `greet` tool to the Web UI. Complete [Your first plugin](./index.md) first and keep its `scratch-plugin` directory.
 
 ## Create the tool plugin
 
@@ -48,5 +48,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](../../../cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, Code Mode, and UI cards.
-- [Capability layering](../practice/) — split a replaceable capability into Service Definition, Service Provider, and Consumer packages.
+- [Tool authoring 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/references/official-docs/docs/user/develop/basic/tool.zh.md

@@ -2,7 +2,7 @@
 
 [English](tool.md) | 中文
 
-本教程会在 Web UI 中添加一个 `greet` 工具。请先完成[第一个插件](./)，并保留其中的 `scratch-plugin` 目录。
+本教程会在 Web UI 中添加一个 `greet` 工具。请先完成[第一个插件](./index.zh.md)，并保留其中的 `scratch-plugin` 目录。
 
 ## 创建工具插件
 
@@ -47,6 +47,6 @@ pnpm dsh web --patch ./scratch-plugin/cordis.yml
 
 ## 下一步
 
-- [插件配置](./config.md) — 让问候语可配置。
-- [工具编写参考](../../../cookbook/adding-a-tool.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、Code Mode 和 UI 卡片。
-- [能力分层](../practice/) — 将可替换能力拆分为 Service Definition、Service Provider 和 Consumer 三类包。
+- [插件配置](./config.zh.md) — 让问候语可配置。
+- [工具编写参考](../../../cookbook/adding-a-tool.zh.md) — 查阅嵌套 schema、规范值、后台工作、策略钩子、PTC mode 和 UI 卡片。
+- [能力分层](../practice/index.zh.md) — 将可替换能力拆分为 Service Definition、Service Provider 和 Consumer 三类包。

package/references/official-docs/docs/user/develop/framework/events.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/framework/events.md
-events.md: 1d9fe5c8f5068de6ad8b2abaa85cf67be35c8459
-events.zh.md: 8bb9447a270cc2db966b1e01298a831a60a1b9c1
+events.md: c8c1bc753a2353f735f3f0d56f1c7e7f37b5be6d
+events.zh.md: 366c37ca4dc02a97d8ecb43d0425da141ec4253d

package/references/official-docs/docs/user/develop/framework/events.md

@@ -101,7 +101,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](../../../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](../../../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`.
 
@@ -139,5 +139,5 @@ export function apply(ctx: Context) {
 
 ## Next steps
 
-- [Capability layering](../practice/) — understand events within capability interfaces
+- [Capability layering](../practice/index.md) — understand events within capability interfaces
 - [LLM adapters](../practice/llm-adapter.md) — implement a complete LLM backend

package/references/official-docs/docs/user/develop/framework/events.zh.md

@@ -101,7 +101,7 @@ declare module '@deepseek-ai/cordis' {
 
 ## Cordis 事件与会话记录
 
-Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.md)上生成的 `cordis-surface` 区块。
+Harness 的 Cordis 事件遵循 `namespace/action` 命名，例如 `agent/pre-step`、`agent/request`、`agent/request-error`、`tools/result` 和 `session/event`。完整签名与触发模式见[子系统页面](../../../subsystems/core.zh.md)上生成的 `cordis-surface` 区块。
 
 `turn/*`、`step/*`、`tool/call`、`tool/result` 和 `compaction/*` 是持久化的会话事件类型，不是同名 Cordis 事件。需要观察它们时，监听 `session/event` 并检查 `event.type`。
 
@@ -139,5 +139,5 @@ export function apply(ctx: Context) {
 
 ## 下一步
 
-- [能力分层](../practice/) — 了解能力接口中的事件
-- [LLM（大语言模型）适配器](../practice/llm-adapter.md) — 实现一个完整的 LLM 后端
+- [能力分层](../practice/index.zh.md) — 了解能力接口中的事件
+- [LLM（大语言模型）适配器](../practice/llm-adapter.zh.md) — 实现一个完整的 LLM 后端

package/references/official-docs/docs/user/develop/framework/index.i18n.yaml

@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/framework/index.md
 index.md: 8cc673148d7fec4f7d9b994907e17293bc3a6a97
-index.zh.md: 1a1f7feb8685e124babb182544bde332b52da42c
+index.zh.md: 8f55bd1cdd472b2f7b90e9280c58d15533ffce57

package/references/official-docs/docs/user/develop/framework/index.zh.md

@@ -132,6 +132,6 @@ effect cleaned up
 
 ## 下一步
 
-- [服务与依赖](./service.md) — 让插件向其他插件提供能力
-- [事件系统](./events.md) — 在插件之间通信
-- [Cordis 框架教程](../../../cordis-tutorial/index.md) — 在 Cordis 运行时上逐步搭出同一套生命周期、服务与事件
+- [服务与依赖](./service.zh.md) — 让插件向其他插件提供能力
+- [事件系统](./events.zh.md) — 在插件之间通信
+- [Cordis 框架教程](../../../cordis-tutorial/index.zh.md) — 在 Cordis 运行时上逐步搭出同一套生命周期、服务与事件

package/references/official-docs/docs/user/develop/framework/service.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/framework/service.md
-service.md: 03f4e7dc4df934495a4b203066183753b621339e
-service.zh.md: 2f4c01e0ea6a87a87ca694b265b07e07098f3e59
+service.md: 1bcfe2e7690d9f93b871500660e0fbe1e3439b3f
+service.zh.md: b275c3d200fb50b1fab0e762d0154477c7ca4447

package/references/official-docs/docs/user/develop/framework/service.md

@@ -145,4 +145,4 @@ The repository generates the service names, public methods, and source locations
 ## Next steps
 
 - [Event system](./events.md) — communicate between plugins without tight coupling
-- [Capability layering](../practice/) — use services as capability interfaces
+- [Capability layering](../practice/index.md) — use services as capability interfaces

package/references/official-docs/docs/user/develop/framework/service.zh.md

@@ -142,9 +142,9 @@ export function apply(ctx: Context) {
 
 ## Harness 内置服务
 
-服务名、公开方法和源码位置由仓库自动生成到各服务的[子系统页面](../../../subsystems/core.md)。开发插件时应以这些生成区块和服务的 TypeScript 接口为准，不要维护另一份静态清单。
+服务名、公开方法和源码位置由仓库自动生成到各服务的[子系统页面](../../../subsystems/core.zh.md)。开发插件时应以这些生成区块和服务的 TypeScript 接口为准，不要维护另一份静态清单。
 
 ## 下一步
 
-- [事件系统](./events.md) — 插件间松耦合通信
-- [能力分层](../practice/) — 将服务用作能力接口
+- [事件系统](./events.zh.md) — 插件间松耦合通信
+- [能力分层](../practice/index.zh.md) — 将服务用作能力接口

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/user/develop/practice/dynamic-cordis.md
+dynamic-cordis.md: 5e324f88c9fc5ac8f770749cf4ab2c97d175121d
+dynamic-cordis.zh.md: 69486cd0d2bacf7c0831e12801128be22fb209ef

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.md

@@ -0,0 +1,15 @@
+# Extend a running agent with Cordis tools
+
+English | [中文](dynamic-cordis.zh.md)
+
+This practice guide enables [`@deepseek-ai/dsh-tool-cordis`](../../../../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](../../../../packages/extensions/tool-cordis/README.md) defines the tool arguments, lifetime, cleanup, and safety contracts.

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.zh.md

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

package/references/official-docs/docs/user/develop/practice/index.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/index.md
-index.md: cc6bd7a234305f6fa193341f15354b40855f72e9
-index.zh.md: aed13b00f9bc74946aace614953bed30705c8281
+index.md: f7e10e14b78da0b2eb922ca0cafd3151d412efd1
+index.zh.md: 55ed3d3a93008f63a3e677de935c1de4be8872e5

package/references/official-docs/docs/user/develop/practice/index.md

@@ -2,7 +2,7 @@
 
 English | [中文](index.zh.md)
 
-This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
+This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/index.md) and [services tutorial](../framework/service.md) first.
 
 ## Concept reference
 

package/references/official-docs/docs/user/develop/practice/index.zh.md

@@ -2,7 +2,7 @@
 
 [English](index.md) | 中文
 
-本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
+本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/index.zh.md)和[服务教程](../framework/service.zh.md)。
 
 ## 概念参考
 
@@ -53,7 +53,7 @@
 - Consumer 依赖 Service Definition。
 - Service Provider 和 Consumer **互不依赖**。
 
-当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.md)负责。
+当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.zh.md)负责。
 
 ## 教程：开发三种角色的能力
 
@@ -152,4 +152,4 @@ export function apply(ctx: Context) {
 
 ## 下一步
 
-- [LLM（大语言模型）适配器](./llm-adapter.md)：实现一个 LLM 提供方
+- [LLM（大语言模型）适配器](./llm-adapter.zh.md)：实现一个 LLM 提供方

package/references/official-docs/docs/user/develop/practice/llm-adapter.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/llm-adapter.md
-llm-adapter.md: 882e82d880ac622cf886c6c24e75a1987e1c6702
-llm-adapter.zh.md: 27c480af2a19a68ac35900a2ce1b5e9dbdc85bf8
+llm-adapter.md: 7e30847cdf265bca8f55aac40f73686101ec185d
+llm-adapter.zh.md: 22a3c54f45088a41362c1a8e903d2441ed4fc93b

package/references/official-docs/docs/user/develop/practice/llm-adapter.md

@@ -54,7 +54,8 @@ export function apply(ctx: Context, config: Config) {
 `stream()` yields chunks using this protocol:
 
 ```ts
-import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import { brandString } from '@deepseek-ai/dsh-brand'
+import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
 
 async function* exampleChunks(): AsyncIterable<StreamChunk> {
   // 1. Start each content block with block-start.
@@ -76,7 +77,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
   yield {
     type: 'tool-call-delta',
     index: 1,
-    id: CallId('call-123'),
+    id: brandString<ToolCallId>('call-123'),
     name: 'bash',
     argumentsDelta: '{"command":"ls"}',
   }
@@ -85,7 +86,7 @@ async function* exampleChunks(): AsyncIterable<StreamChunk> {
     index: 1,
     block: {
       type: 'tool-call',
-      id: CallId('call-123'),
+      id: brandString<ToolCallId>('call-123'),
       name: 'bash',
       arguments: '{"command":"ls"}',
     },

package/references/official-docs/docs/user/develop/practice/llm-adapter.zh.md

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

package/references/official-docs/docs/user/guide/github-review.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/user/guide/github-review.md
+github-review.md: 69c61df95ce7d461b8a120cf6ae4a568ce201f78
+github-review.zh.md: 114aa6546d2366cf34a4a2d3057e9a26e4c43c96

package/references/official-docs/docs/user/guide/github-review.md

@@ -0,0 +1,102 @@
+# Create review Sessions from GitHub webhooks
+
+English | [中文](github-review.zh.md)
+
+This opt-in overlay adds a signed GitHub endpoint to `dsh web`. When a pull request in the configured repository changes from draft to ready for review, the rule creates a titled root Session under the repository's Web Workspace and starts a read-only review prompt.
+
+## Prerequisites
+
+- A local checkout that DSH may register as a Web Workspace.
+- A high-entropy GitHub webhook secret available through the `DSH_GITHUB_WEBHOOK_SECRET` credential reference.
+- A TLS reverse proxy or tunnel that can forward one public URL to the loopback listener.
+- GitHub webhook subscription to the Pull requests event with content type `application/json`.
+
+The overlay defaults the Workspace to the launch directory and the listener to `127.0.0.1:3081`. Override them with `DSH_GITHUB_REVIEW_WORKSPACE` and `DSH_GITHUB_WEBHOOK_PORT`.
+
+## Start DSH
+
+Generate a secret and retain the same value across restarts:
+
+```sh
+export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
+printf '%s\n' "$DSH_GITHUB_WEBHOOK_SECRET"
+```
+
+From a development checkout:
+
+```sh
+export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
+pnpm dsh web --patch apps/cli/config/examples/github-review/cordis.yml
+```
+
+An installed DSH uses the same overlay through an absolute path:
+
+```sh
+dsh web --patch /absolute/path/to/github-review/cordis.yml
+```
+
+For a permanent profile, place `github-ready-review-rule.mjs` beside `$DSH_HOME/profiles/web/cordis.patch.yml`, append the rows from `cordis.yml` to that patch, and start with `dsh web`. The shipped CLI already contains both webhook packages; the overlay alone activates them.
+
+## Expose the dedicated endpoint
+
+The main Web UI and `/api` remain on port 3080. The overlay mounts a second WebServer in an isolated realm; only `POST /github` is registered there, and every other path returns `404`.
+
+A Caddy configuration can expose only that listener:
+
+```caddyfile
+hooks.example.com {
+  route {
+    @github path /github
+    reverse_proxy @github 127.0.0.1:3081
+    respond 404
+  }
+}
+```
+
+Configure GitHub with:
+
+```text
+Payload URL:  https://hooks.example.com/github
+Content type: application/json
+Secret:       DSH_GITHUB_WEBHOOK_SECRET value
+Events:       Pull requests
+Active:       yes
+```
+
+## Rule behavior
+
+The rule accepts only source `primary-github`, repository `deepseek-harness/deepseek-harness`, event `pull_request`, and action `ready_for_review`. It passes the exact head SHA plus selected PR fields to the review prompt, labeling the JSON as untrusted metadata and forbidding file, branch, PR, or GitHub mutation.
+
+The Session request selects the `standard` agent preset and `read-only` permission preset. `workspacePath` is canonicalized through `WorkspaceRegistry.create()`, so the first matching delivery creates the Web Workspace when absent and later deliveries reuse it.
+
+The HTTP response is intentionally weaker than the Agent outcome: `202` means the signature and JSON were accepted and rule calls were scheduled in memory. It does not mean this rule matched or that a Session was created.
+
+## Programmatic extensions
+
+`run()` is ordinary trusted JavaScript. A deployment can query an internal policy service before returning a Session request:
+
+```js
+const response = await fetch('https://policy.internal/pr-review', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ repository: payload.repository.full_name }),
+  signal,
+})
+if (!response.ok || (await response.json()).automaticReview !== true) return null
+```
+
+It can also map repositories to different local paths:
+
+```js
+const workspacePath = {
+  'deepseek-harness/deepseek-harness': '/path/to/deepseek-harness',
+  'deepseek-harness/dsh-sdk': '/path/to/dsh-sdk',
+}[payload.repository.full_name]
+if (workspacePath === undefined) return null
+```
+
+## Delivery semantics
+
+The webhook runtime stores no delivery or execution state. Repeated delivery runs the rule and may create another Session. A crash loses rule calls that have not admitted their prompt. After prompt admission, the ordinary Session log, persistence, Workspace, and Agent lifecycle own the work.
+
+The webhook secret authenticates inbound GitHub data only. It grants neither rule code nor the created Agent outbound GitHub access; configure that authority separately when a rule or Agent needs it.