dsh-plugin-zbk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 智宝项目组
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PLUGIN.md

@@ -0,0 +1,5 @@
+# dsh-plugin-zbk（DSH 插件）
+
+> 本文件只是指针：**安装 / 使用 / 安全 / 自检 / 实施记录见 [README.md](README.md)**。
+
+正文只维护 README.md 一份（npm 包内同名文件），此处不重复，避免双写。

package/README.md

@@ -1,3 +1,342 @@
-# Temporary Holding Version
+# dsh-plugin-zbk —— zbk 可移植看板工具包的 DSH 插件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **状态（2026-11-11）**：**脚手架完成，未安装、未发布 npm**（按卡：安装由总控/项目方决定）。
+> 本包把仓库内 `tools/zbk/` 工具包（第 1 步成果，commit `13383d28`，selftest 16/16）
+> 包成 DSH 插件：让任意项目在 DSH 会话里**一句话拉起看板**（init → serve → check → open）。
+
+---
+
+## 1. 这是什么
+
+| 工具 | 等价 CLI | 什么时候用 | 返回 |
+|---|---|---|---|
+| `zbk_init` | `python tools/zbk/zbk.py init --dir <项目>/.zbk` | 项目还没有 `.zbk` 数据目录，要开看板/反馈栈/流程图 | 数据目录、端口、**一次性令牌**、PASS/FAIL |
+| `zbk_serve` | `python tools/zbk/zbk.py serve --dir … --port …` | 要在本机浏览器打开看板前 | 访问 URL、pid、是否新起/已在跑 |
+| `zbk_check` | `python tools/zbk/zbk.py check --dir … --json` | 改过数据后确认没写坏 | **PASS/FAIL** + 错误列表 + 计数 |
+| `zbk_open` | （无直接 CLI，等价于打开 `http://127.0.0.1:<port>/`） | 用户要看板地址 | URL + 服务是否健康 |
+
+**插件只是入口，CLI 仍是事实源**：
+
+- 真正干活的是 `tools/zbk/zbk.py`（init/serve/token/check），插件只负责在会话里**按顺序调用它**；
+- 数据归项目自己的 `.zbk/` 目录（`config.json / data.json / feedback.json / flows.json / uploads/`），
+  插件**不接管数据所有权、不复制数据、不改数据格式**；
+- 四页静态资源（脑图/反馈栈/流程图/需求引导）仍由 `zbk.py serve` 自己提供，插件**不打包、不代理**页面；
+- 不装本插件时，`tools/zbk/` 仍可独立用（与第 1 步的"可移植目录"定位一致）。
+
+---
+
+## 2. 目录结构
+
+```text
+tools/zbk/dsh-plugin/
+├── package.json        # name=dsh-plugin-zbk；type=module；main/exports；peerDependencies；dsh.bundle.patch
+├── cordis.patch.yml    # 把插件行 insert 进 loader 树（id/name = dsh-plugin-zbk）
+├── lib/
+│   └── index.js        # host 入口（ESM）：导出 name / inject / apply，注册 4 个工具
+├── README.md           # 本文件（含安装/安全/自检/实施记录）
+└── PLUGIN.md           # 指针：正文只维护 README.md（照抄本机插件示例惯例）
+```
+
+三处一致性（loader 身份）：`package.json.name` = `cordis.patch.yml` 的 `id`/`name` = `lib/index.js` 导出的 `name`
+= **`dsh-plugin-zbk`**。
+
+---
+
+## 3. 运行时要求
+
+| 依赖 | 要求 | 说明 |
+|---|---|---|
+| DSH | `>= 0.2.0-0`（见 peerDependencies） | 用 `@deepseek-ai/dsh-tools` 的 `defineTool` + `ctx.tools.register` |
+| Cordis | `^4.0.5`（见 peerDependencies） | 插件框架 |
+| Node.js | 18+（DSH host 自带） | 只用 `node:` 内置模块 + 全局 `fetch`/`AbortSignal` |
+| Python | 3.8+（只用标准库） | 调用 `zbk.py`；默认 Windows=`python`、其它=`python3`（可用 `ZBK_PYTHON` 覆盖） |
+| 项目文件 | 项目内有 `tools/zbk/zbk.py` | 找不到时插件报可读错误并提示 `project_dir` / `ZBK_ZBK_PY` |
+
+**无第三方运行时依赖**：`dependencies: {}`，不声明 `Config`（不引 schemastery/zod），不引 React/client 产物。
+
+---
+
+## 4. 安装步骤（截图级；**本卡未执行安装**）
+
+> 安装动作由总控/项目方做；本卡只交付脚手架 + 说明。安装会改 `~/.dsh/profiles/<profile>/`，
+> 属"动用户环境"，本卡红线不碰。
+
+### 4.1 推荐：Web 插件页 / `plugin_manager` 工具（本地绝对路径）
+
+1. 确认本包目录的**绝对路径**，例如：
+   `D:/deepseek harness/zhibao/tools/zbk/dsh-plugin`
+   （plugin manager 的本地路径 spec **必须绝对**，`file:`/`link:` 前缀可带可不带）。
+2. 在 DSH 的 **Plugins** 页选择安装并粘贴上述绝对路径；或在会话里调用 `plugin_manager` 工具：
+   ```json
+   {"action": "install_bundle", "target": "D:/deepseek harness/zhibao/tools/zbk/dsh-plugin"}
+   ```
+3. 安装器会（按 `@deepseek-ai/dsh-plugin-manager` 源码行为）：
+   - 读本包 `package.json`（`dsh.bundle.patch` 必须存在，否则拒绝安装）；
+   - 用 profile 的 pnpm 以本地路径依赖安装本包（`pnpm add <路径>`，save 本地路径）；
+   - 校验 `engines.dsh` / `@deepseek-ai/dsh*` peer 与运行版本（本包 peer 用下界 `>=0.2.0-0`，见第 9 节）；
+   - 把 `dsh-plugin-zbk` 加入 profile `package.json` 的 `dsh.profile.bundles` 并**默认启用**；
+   - profile 的 `cordis.patch.yml` **不需要手工编辑**：bundle 的补丁层会自动插入插件行。
+4. 无 HMR 的运行实例会提示 **restart-required** → 重启 DSH 后生效（Web 源/开发桌面支持热更新时可即时生效）。
+
+### 4.2 CLI（存在，但本卡**未实测语法**）
+
+`dsh plugin` 支持安装本地路径（源码中 install 失败提示即 `run 'dsh plugin install'`）；预期形如
+`dsh plugin --profile desktop install <绝对路径>`。**本机 PATH 无 `dsh` 可执行文件，未实测**，以 §4.1 为准。
+
+### 4.3 本地开发（link:）
+
+DSH Source Web / development Desktop 提供 `link:<绝对 workspace 包目录>` 形式；本包是纯 JS（无 build），
+link 后重启 DSH 即可。修改本包后需重启/热更新，无编译步骤。
+
+### 4.4 安装后自检
+
+- 会话里问"用 zbk 工具初始化看板"→ 模型应能调 `zbk_init`；
+- 或在 Web Plugins 页看到 **dsh-plugin-zbk** 已启用、无 error；
+- 若插件加载失败：Plugins 页会显示 error（bundle 列 `error` 字段），先看 DSH 日志里
+  `zbk: host plugin loaded` 是否出现。
+
+---
+
+## 5. 启用 / 禁用 / 卸载
+
+| 操作 | 做法 | 影响 |
+|---|---|---|
+| 禁用/启用 | Plugins 页 toggle，或 `plugin_manager` `set_plugin`（`enabled:false/true`） | 只改 profile `cordis.patch.yml` 中该行的 `disabled`，不删包 |
+| 卸载 | `plugin_manager` `remove_bundle`，target=`dsh-plugin-zbk` | 从 profile `package.json` 与 `dsh.profile.bundles` 移除；**项目 `.zbk/` 数据不受影响** |
+| 手工兜底 | 从 profile `package.json` 依赖与 `dsh.profile.bundles` 删 `dsh-plugin-zbk`；必要时在用户 patch 层加 `- id: dsh-plugin-zbk\n  disabled: true` | 与 CLI/管理器等价，不推荐手改 |
+
+> 卸载只影响"能不能在会话里调 4 个工具"；`tools/zbk/` 与项目 `.zbk/` 数据完全独立。
+
+---
+
+## 6. 配置（无 Config 块；全部走工具参数 / 环境变量）
+
+工具参数（每次调用可选）：
+
+| 参数 | 用于 | 说明 |
+|---|---|---|
+| `project_dir` | 全部 | 项目根目录（其下应有 `tools/zbk/zbk.py`）；省略时按 环境变量 → 会话工作目录 → 进程 cwd |
+| `data_dir` | 全部 | `.zbk` 数据目录，默认 `<project_dir>/.zbk`，也接受绝对路径 |
+| `port` | init/serve/open | 端口；serve/open 省略时读 `config.json`，再缺省 8810 |
+| `host` | serve | 绑定地址；默认读 `config.json`（通常 127.0.0.1）；**0.0.0.0 需自备反代与鉴权** |
+| `force` | init | 数据目录非空时强制重置（会丢弃现有数据并生成新令牌） |
+
+环境变量（DSH 进程级；适用"不想每次传参"的场景）：
+
+| 变量 | 作用 |
+|---|---|
+| `ZBK_PROJECT_DIR` | 默认项目根目录 |
+| `ZBK_ZBK_PY` | `zbk.py` 绝对路径（找不到 `tools/zbk/zbk.py` 时用） |
+| `ZBK_ROOT` | 工具包根目录（其下或 `tools/zbk/` 下有 `zbk.py`） |
+| `ZBK_PYTHON` | Python 可执行文件（默认 Windows=`python`、其它=`python3`） |
+
+`zbk.py` 定位顺序：`ZBK_ZBK_PY` → `ZBK_ROOT` 下两种布局 → 从 `project_dir` 向上最多 6 层找
+`tools/zbk/zbk.py`、`zbk/zbk.py`。全找不到时报错里会列出**所有已查找路径**。
+
+子进程固定注入 `PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`、`PYTHONUNBUFFERED=1`
+（Windows 下 Python 管道输出默认走 locale 代码页，不强制 UTF-8 会把"一次性令牌/端口"解析坏——本卡实测踩过）。
+
+---
+
+## 7. 安全
+
+- **只绑本机**：`zbk.py serve` 默认 `127.0.0.1`；插件只在用户显式传 `host` 时才改绑定，
+  且 README/工具描述都提示公网需自备反代 + 访问控制。
+- **令牌**：`init` 生成随机编辑令牌，CLI 只打印一次；插件把令牌作为工具返回值交给会话
+  （等同用户在本机终端看到一次），**插件自身不写任何日志/文件**；令牌仍只存
+  `<数据目录>/config.json`。请把 `.zbk/` 加入项目 `.gitignore`（含令牌与业务数据）。
+- **写权限模型不变**：页面/API 的鉴权仍是 `X-ZB-Map-Token`，插件不绕过、不改鉴权；
+  未配置令牌时写操作 fail-closed（503/401 由 zbk.py 决定）。
+- **无 shell 拼接**：调用 Python 用 `spawn(cmd, [args…])` 数组参数（无 shell），路径来自参数/环境变量。
+- **上传文件不解析不执行**：由 zbk.py 既有实现负责（按扩展名落盘 `<数据目录>/uploads/`）。
+- **进程不托管**：`zbk_serve` 以 detached 方式起本地服务，DSH 退出后**可能仍在运行**；
+  停/重启由用户负责（插件不持有 pidfile、不自动清理）。这是有意的取舍，见第 9 节风险。
+- **不做公网暴露**：本插件只面对本机会话；公网发布看板是用户侧反代/HTTPS 的事，不在本包范围。
+
+---
+
+## 8. 自检（本卡真跑证据）
+
+环境：Windows 10.0.26200 · Node **v24.19.0**（系统）/ v24.21.0（DSH 内置）· Python 3.12.10 · npm 11.x。
+
+### 8.1 语法：`node --check`
+
+```text
+$ cd "D:\deepseek harness\zhibao\tools\zbk\dsh-plugin"
+$ node --check lib\index.js ; echo $LASTEXITCODE
+EXIT_CHECK=0
+$ & "C:\Users\hrj\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe" --check lib\index.js
+EXIT_CHECK_BUNDLED=0
+```
+
+### 8.2 打包：`npm pack --dry-run`
+
+见 §8.6（只含预期 5 个文件：package.json / cordis.patch.yml / lib/index.js / README.md / PLUGIN.md；
+不产生实际 tgz）。
+
+### 8.3 脱离 DSH 运行时 import：给出明确报错（符合预期）
+
+```text
+$ node -e "import(require('node:url').pathToFileURL('.../lib/index.js').href).catch(e=>{console.log(e.code);console.log(e.message.split('\n')[0])})"
+ERR_MODULE_NOT_FOUND
+Cannot find package '@deepseek-ai/dsh-tools' imported from D:\deepseek harness\zhibao\tools\zbk\dsh-plugin\lib\index.js
+```
+
+⇒ 插件依赖 DSH 运行时提供的 `@deepseek-ai/dsh-tools`（peer，由安装器提供、按 app-boot 的
+"两锚点解析"从 DSH 安装目录解析）；**不是可独立 `node` 运行的库**。
+
+### 8.4 stub 运行时冒烟（真 python + 真 zbk.py，跑完删除，不入库）
+
+用临时目录伪造 `node_modules/@deepseek-ai/dsh-tools`（`defineTool(d)=>d`）+ 假 `ctx`，
+导入本插件并**逐个执行 4 个工具的 `execute`**：
+init（新目录）→ check（PASS）→ 写坏 data.json → check（FAIL）→ init --force → open（未起服务）→
+serve（真起服务 + 健康检查）→ open（健康）→ 传一个没有 `tools/zbk` 的目录验证报错可读。
+
+```text
+$ node run.mjs
+  ✓ 导出 name 与包名一致
+  ✓ inject 含 tools/workingDirectory
+  ✓ 注册 4 个工具
+  ✓ zbk_init 有 description/parameters/output/execute
+  ✓ zbk_serve 有 description/parameters/output/execute
+  ✓ zbk_check 有 description/parameters/output/execute
+  ✓ zbk_open 有 description/parameters/output/execute
+  ✓ zbk_init ok
+  ✓ zbk_init 返回一次性令牌
+  ✓ zbk_init 返回端口
+  ✓ init 令牌与 config.json 一致
+  ✓ zbk_check PASS
+  ✓ zbk_check 坏数据 FAIL
+  ✓ zbk_init force 重置
+  ✓ zbk_open 返回 URL（未起服务）
+  ✓ zbk_serve 启动或已运行
+  ✓ zbk_serve 返回 URL
+  ✓ zbk_open 服务健康
+  ✓ 找不到 zbk.py 时报错可读
+  （已结束临时 serve pid=25280）
+SMOKE PASS
+EXIT=0
+```
+
+### 8.5 结构断言（静态）
+
+- `package.json`: `name=dsh-plugin-zbk`、`type=module`、`main=lib/index.js`、`dsh.bundle.patch=./cordis.patch.yml`、`dependencies={}`；
+- `cordis.patch.yml`: 顶层 `insert` 一项，`id=name=dsh-plugin-zbk`；用 PyYAML 解析实测：
+  `[{'insert': [{'id': 'dsh-plugin-zbk', 'name': 'dsh-plugin-zbk'}]}]`；
+- `lib/index.js`: `export { apply, inject, name }`，`name="dsh-plugin-zbk"`，`inject=["tools","workingDirectory"]`；
+- 三处一致（脚本断言 + 冒烟输出第一行）。
+
+### 8.6 `npm pack --dry-run` 输出
+
+```text
+$ cd "D:\deepseek harness\zhibao\tools\zbk\dsh-plugin"
+$ npm pack --dry-run
+npm notice package: dsh-plugin-zbk@0.1.0
+npm notice Tarball Contents
+npm notice 240B PLUGIN.md
+npm notice 18.8kB README.md
+npm notice 778B cordis.patch.yml
+npm notice 23.2kB lib/index.js
+npm notice 1.9kB package.json
+npm notice Tarball Details
+npm notice name: dsh-plugin-zbk
+npm notice version: 0.1.0
+npm notice filename: dsh-plugin-zbk-0.1.0.tgz
+npm notice package size: 16.2 kB
+npm notice unpacked size: 44.9 kB
+npm notice shasum: e1d17c9e4bb9b4194d403249f3844b2185f5c484
+npm notice integrity: sha512-pKnEIoxnRSo+m[...]WOOiYjKyVjv7Q==
+npm notice total files: 5
+```
+
+`--dry-run` 不落 tgz（目录内确认无 `dsh-plugin-zbk-0.1.0.tgz`）。
+
+---
+
+## 9. 未验证项 / 已知风险（本卡明确声明，**未装 profile**）
+
+1. **未安装进任何 DSH profile**（红线）：未验证 loader 实际加载本包、peer 解析、4 个工具出现在模型工具集。
+   上述结构/工具实现是按本机现成插件（`dsh-plugin-control-your-development`）与 DSH 内置
+   `@deepseek-ai/dsh-tool-todo` / `dsh-tool-present` 源码/README 的 API 写的，不是猜 API。
+2. **未发布 npm**：`plugin_manager` 从 registry 安装的路径未验证；本地绝对路径 spec 已按
+   `@deepseek-ai/dsh-plugin-manager` 的 `parseInstallSpec`（本地路径必须绝对）设计。
+3. **`dsh plugin install` CLI 语法未实测**（本机 PATH 无 `dsh`）。
+4. **未让真模型调用这 4 个工具**：工具 schema/description 只做静态校验 + stub execute 真跑。
+5. **`workingDirectory` 服务是 inject 必需项**：极简 profile 若没有该服务，插件不会加载
+   （桌面 profile 已有；见 `@deepseek-ai/dsh-working-directory`）。
+6. **zbk_serve 不托管进程**：detached 服务在 DSH 退出后可能残留；端口占用/多实例未做防护
+   （`zbk.py` 自身单进程文件锁只保护数据写；端口冲突会由 health 探测发现并在提示里给出换端口建议）。
+7. **未在 Linux/macOS 实测**：Python 候选（`python3`）、路径分隔符已按 `node:path` 处理，但只有 Windows 真跑。
+8. **`json` 类型**：`zbk_check` 的 `stats` 用 DSH schema DSL 的 author-only `json` 类型（按 dsh-tools README
+   的 schema 支持列表），未在真 registry 里校验输出 schema。
+9. **工具名冲突**：若用户已装同名工具（zbk_init 等）会被 later registration 覆盖/报错，属 DSH 工具注册语义，
+   本包不做改名开关。
+
+---
+
+## 10. 实施记录（六段式，2026-11-11）
+
+> 任务来源：DSH 共享任务板 `task-13`《工具包第2步 dsh-plugin-zbk 插件脚手架》。
+> 上游：`tools/zbk/` 第 1 步（commit `13383d28`，`selftest.py` 16/16，全量目录说明见 `tools/zbk/README.md`）。
+
+### ① 背景与范围
+
+- **背景**：`tools/zbk` 已能独立用（CLI + 四页），但每次要在项目里手动跑 `init/serve`；
+  目标是包成 DSH 插件，让任意 DSH 会话一句话拉起看板。
+- **范围**：只新建 `tools/zbk/dsh-plugin/**`（package.json / cordis.patch.yml / lib/index.js / README.md / PLUGIN.md）；
+  不改 `tools/zbk` 现有文件、不改 `~/.dsh` profile、**不安装插件、不发布 npm**。
+- **事实源**：本机现成插件 `C:\Users\hrj\.dsh\profiles\desktop\node_modules\dsh-plugin-control-your-development\`
+  （package.json / cordis.patch.yml / PLUGIN.md 结构）、DSH 内置 `@deepseek-ai/dsh-tool-todo` /
+  `dsh-tool-present` 的 `defineTool` 用法、`@deepseek-ai/dsh-app-boot` 的 profile/bundle 文档注释。
+
+### ② 做了什么（做了什么 + 能力地图）
+
+| 文件 | 内容 |
+|---|---|
+| `package.json` | `name=dsh-plugin-zbk`、`type=module`、`main/exports`、`files`、`peerDependencies`（@deepseek-ai/cordis ^4.0.5；dsh-tools/dsh-working-directory `>=0.2.0-0`）、`dependencies:{}`、`dsh.bundle.patch` |
+| `cordis.patch.yml` | `insert` 一行：`id=name=dsh-plugin-zbk`；无 config 块（本插件不声明 Config） |
+| `lib/index.js` | host ESM：`name` / `inject=["tools","workingDirectory"]` / `apply`；注册 4 个 `defineTool` |
+| `README.md` / `PLUGIN.md` | 安装/启用/卸载/安全/配置/自检/未验证项 + 本六段记录；PLUGIN.md 为指针（遵循示例惯例，正文只维护 README 一份） |
+
+**4 个工具的实现要点**：
+
+- `zbk_init`：`zbk.py init --dir <data> [--port] [--force]` → 解析「一次性令牌/端口」→ 返回并提示用户立即保存；
+- `zbk_serve`：先 `/health` 探测；未运行则 **detached** 起 `serve` 并轮询 `/health`（≤3s），返回 URL/pid；
+- `zbk_check`：`check --json` → 解析 `{ok,errors,stats}` → PASS/FAIL 摘要 + 错误列表；
+- `zbk_open`：读 `config.json` 端口 → 探 `/health` → 返回 `http://127.0.0.1:<port>/`（服务未起也返回 URL + 提示）。
+
+**能力地图更新（AGENTS §10.1b）**：本卡只新增 DSH 插件入口，**未改任何既有生产能力/端点/接线**；
+`docs/代码地图-*.md` 无需更新（`tools/zbk` 属工具包，不在地图覆盖范围）。若总控希望收录，
+建议在工具类地图加一条：「zbk 看板工具包 + DSH 插件 dsh-plugin-zbk（`tools/zbk/dsh-plugin`）——宿主入口 4 工具；
+接线状态：脚手架已交付、未安装」。
+
+### ③ 部署台账
+
+**不适用**——未部署、未安装插件、未改 `~/.dsh` profile（红线）；无设备/二进制变更，父仓 `docs/部署台账.md` 无新增行。
+
+### ④ 验收证据
+
+- 语法/打包/import 失败/stub 冒烟/结构断言：见 §8（`node --check` exit 0、`npm pack --dry-run` 只含预期文件、
+  冒烟 19/19 PASS）；
+- 真跑覆盖：`zbk_init`（新目录/force）、`zbk_check`（PASS/FAIL 负控）、`zbk_open`（未起/已起）、
+  `zbk_serve`（真起服务 + health）、缺 `zbk.py` 的可读报错；
+- 红线自查：本卡只新增 `tools/zbk/dsh-plugin/**` 五个文件；未安装插件、未改 profile、未发布 npm；
+  提交逐路径 `git add --`。
+
+### ⑤ 红项 / 遗留
+
+- 无红项（脚手架层面）。未验证项 9 条见 §9，其中最需要总控在安装时确认的是：
+  1) 本地路径安装的 pnpm 行为与 peer 检查；2) 重启后 4 个工具是否出现在模型工具集；3) `workingDirectory` 注入可用性。
+
+### ⑥ 下一步
+
+1. **总控/项目方决定是否安装**（本卡红线：安装归你们）：按 §4.1 传绝对路径安装到目标 profile，
+   重启后按 §4.4 自检，把"已安装/已验证"写回本 README 的状态行。
+2. 安装后**真模型调用验收**：让模型执行 `zbk_init`（临时项目）→ `zbk_serve` → `zbk_open` → 浏览器打开四页 →
+   `zbk_check`；把真实输出补进 §8.6/§10④。
+3. 若确认可用，再考虑：发布 npm（`publishConfig`/仓库地址待定）、加 `zbk_stop` 工具（需先解决进程托管语义）、
+   或把四页也纳入插件静态资源（当前有意不做，保持 CLI 为事实源）。
+
+---
+
+*创建：2026-11-11 · 执行：队友 `executor-b`（DSH Agent Team）· 卡：共享任务板 `task-13` · 未安装/未发布*

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# 只插入本插件自己的一行；不替换任何官方组件。
+# 行 id 与 name 必须等于 package.json 的 name，也必须等于 lib/index.js 导出的 name（三处一致）。
+# 安装（plugin_manager install_bundle / `dsh plugin install`）会把本包加入 profile 的
+# dsh.profile.bundles 并默认启用；本文件只负责把插件挂到 loader 树上。
+- insert:
+    - id: dsh-plugin-zbk
+      name: dsh-plugin-zbk
+      # 用户在自己的 profile patch 层覆盖本行时，config 是「整块替换」而不是深合并。
+      # 本插件不声明 Config：配置一律走工具参数（project_dir / data_dir / port）或环境变量
+      # （ZBK_PROJECT_DIR / ZBK_ZBK_PY / ZBK_PYTHON），因此这里不需要 config 块。
+      # config: {}

package/lib/index.js

@@ -0,0 +1,592 @@
+/**
+ * dsh-plugin-zbk —— 把 tools/zbk 可移植看板工具包暴露成 4 个 DSH 工具：
+ *   zbk_init / zbk_serve / zbk_check / zbk_open
+ *
+ * 设计边界（与任务卡一致）：
+ * - 插件只是「入口」：真正干活的仍是 zbk.py（init/serve/token/check），数据归项目自己的 .zbk/ 目录；
+ * - 只依赖 node: 内置模块 + 宿主提供的 @deepseek-ai/dsh-tools（defineTool）；
+ * - 不声明 Config（避免给用户 profile 增装 schemastery）；配置走工具参数 + 环境变量；
+ * - 不托管服务生命周期：zbk_serve 只负责后台拉起 + 健康探测，停服务由用户/系统负责；
+ * - 不复制/代理四页静态资源：URL 指向 zbk.py serve 自己起的本地服务。
+ *
+ * 环境变量（均可选）：
+ *   ZBK_PROJECT_DIR  默认项目目录（工具参数 project_dir 优先）
+ *   ZBK_ZBK_PY       zbk.py 的绝对路径（找不到 tools/zbk/zbk.py 时使用）
+ *   ZBK_PYTHON       指定 Python 可执行文件（默认 Windows=python、其它=python3）
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+/** Stable Loader identity：须与 package.json name、cordis.patch.yml 的 id/name 三处一致。 */
+const name = "dsh-plugin-zbk";
+
+/** 本插件只注册工具；另用 workingDirectory 把会话工作目录作为默认项目目录。 */
+const inject = ["tools", "workingDirectory"];
+
+const DEFAULT_PORT = 8810;
+const DEFAULT_DATA_DIR = ".zbk";
+const RUN_TIMEOUT_MS = 60000;
+const REQUEST_TIMEOUT_MS = 8000;
+
+// ── 小工具 ────────────────────────────────────────────────────────────────
+
+/** @param {number} ms */
+function sleep(ms) {
+  return new Promise((done) => setTimeout(done, ms));
+}
+
+/**
+ * 解析项目目录：工具参数 > ZBK_PROJECT_DIR > 会话工作目录 > 进程 cwd。
+ * @param {{project_dir?: string}} args
+ * @param {{agent?: unknown, signal?: AbortSignal}} exec
+ * @param {any} ctx
+ */
+async function resolveProjectDir(args, exec, ctx) {
+  const explicit = typeof args.project_dir === "string" ? args.project_dir.trim() : "";
+  if (explicit) return resolve(explicit);
+  const fromEnv = (process.env.ZBK_PROJECT_DIR || "").trim();
+  if (fromEnv) return resolve(fromEnv);
+  try {
+    if (exec && exec.agent !== undefined && ctx.workingDirectory !== undefined) {
+      const cwd = await ctx.workingDirectory.ensure(exec.agent, exec.signal);
+      if (typeof cwd === "string" && cwd.trim() !== "") return resolve(cwd);
+    }
+  } catch {
+    /* 工作目录服务不可用（或 programmatic 调用无 agent）→ 落进程 cwd */
+  }
+  return resolve(process.cwd());
+}
+
+/** @param {string} projectDir @param {string | undefined} dataDir */
+function resolveDataDir(projectDir, dataDir) {
+  const raw = typeof dataDir === "string" ? dataDir.trim() : "";
+  return isAbsolute(raw) ? raw : resolve(projectDir, raw || DEFAULT_DATA_DIR);
+}
+
+/**
+ * 找 tools/zbk/zbk.py：显式 env → 环境根 → 从项目目录向上最多 6 层。
+ * @param {string} projectDir
+ * @returns {string}
+ */
+function resolveZbkPy(projectDir) {
+  const candidates = [];
+  const explicit = (process.env.ZBK_ZBK_PY || "").trim();
+  if (explicit) candidates.push(resolve(explicit));
+  const envRoot = (process.env.ZBK_ROOT || "").trim();
+  if (envRoot) {
+    const root = resolve(envRoot);
+    candidates.push(join(root, "zbk.py"), join(root, "tools", "zbk", "zbk.py"));
+  }
+  let dir = resolve(projectDir);
+  for (let i = 0; i < 6; i += 1) {
+    candidates.push(join(dir, "tools", "zbk", "zbk.py"), join(dir, "zbk", "zbk.py"));
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  for (const file of candidates) {
+    try {
+      if (existsSync(file) && statSync(file).isFile()) return file;
+    } catch {
+      /* 忽略不可读候选，继续找 */
+    }
+  }
+  throw new Error(
+    "找不到 zbk.py（zbk 工具包）。已查找：" +
+      candidates.join(" ; ") +
+      "。请在调用时传 project_dir（含 tools/zbk/zbk.py 的项目根目录），" +
+      "或设置环境变量 ZBK_ZBK_PY（zbk.py 绝对路径）/ ZBK_PROJECT_DIR。",
+  );
+}
+
+/** Python 候选（环境变量优先；其次平台默认，找不到再退另一个）。 */
+function pythonCandidates() {
+  const explicit = (process.env.ZBK_PYTHON || "").trim();
+  if (explicit) return [explicit];
+  return process.platform === "win32" ? ["python", "py"] : ["python3", "python"];
+}
+
+/**
+ * 子进程环境：强制 UTF-8 输出。
+ * Windows 下 python 的 stdout 默认走 locale 代码页（cp936 等），Node 按 UTF-8 解码会乱码，
+ * 导致「一次性令牌 / 端口」解析失败；PYTHONIOENCODING + PYTHONUTF8 双保险。
+ */
+function childEnv() {
+  return { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1", PYTHONUNBUFFERED: "1" };
+}
+
+/**
+ * 跑一次性 zbk.py 命令，捕获 stdout/stderr，60s 超时，支持协作取消。
+ * @param {string} python
+ * @param {string} zbkPy
+ * @param {string[]} argv
+ * @param {{cwd?: string, signal?: AbortSignal, timeoutMs?: number}} options
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+function runZbk(python, zbkPy, argv, options = {}) {
+  const timeoutMs = options.timeoutMs ?? RUN_TIMEOUT_MS;
+  return new Promise((settle) => {
+    let child;
+    try {
+      child = spawn(python, [zbkPy, ...argv], {
+        cwd: options.cwd,
+        windowsHide: true,
+        env: childEnv(),
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      settle({ code: -1, stdout: "", stderr: String(error && error.message ? error.message : error) });
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let finished = false;
+    const finish = (code) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      settle({ code, stdout, stderr });
+    };
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      stderr += String(error && error.message ? error.message : error);
+      finish(-1);
+    });
+    child.on("close", (code) => finish(typeof code === "number" ? code : -1));
+    const timer = setTimeout(() => {
+      stderr += `\n[zbk-plugin] 命令超时（${timeoutMs}ms），已终止`;
+      try {
+        child.kill();
+      } catch {
+        /* 已退出 */
+      }
+      finish(-2);
+    }, timeoutMs);
+    if (options.signal) {
+      const abort = () => {
+        try {
+          child.kill();
+        } catch {
+          /* 已退出 */
+        }
+      };
+      if (options.signal.aborted) abort();
+      else options.signal.addEventListener("abort", abort, { once: true });
+    }
+  });
+}
+
+/**
+ * 带 Python 候选回退地跑 zbk.py（仅在 spawn ENOENT 时换下一个候选）。
+ * @param {string} zbkPy
+ * @param {string[]} argv
+ * @param {{cwd?: string, signal?: AbortSignal}} options
+ */
+async function runZbkWithFallback(zbkPy, argv, options) {
+  let last = null;
+  for (const python of pythonCandidates()) {
+    // 先用 `zbk.py --help` 探测该解释器是否可执行，避免把 ENOENT 混进业务错误。
+    const probe = await runZbk(python, zbkPy, ["--help"], { ...options, timeoutMs: 15000 });
+    if (probe.code !== -1 || !/ENOENT|not found|cannot find/i.test(probe.stderr)) {
+      if (argv.length === 0) return { result: probe, python };
+      const result = await runZbk(python, zbkPy, argv, options);
+      return { result, python };
+    }
+    last = probe;
+  }
+  throw new Error(
+    "找不到可用的 Python 解释器（已尝试：" +
+      pythonCandidates().join(", ") +
+      "）。请设置环境变量 ZBK_PYTHON 指向 python 可执行文件。" +
+      (last ? " 最后一次错误：" + last.stderr.trim() : ""),
+  );
+}
+
+/** @param {string} projectDir @param {string | undefined} dataDir */
+function readConfig(dataDir) {
+  try {
+    const raw = readFileSync(join(dataDir, "config.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 取 init 输出里的「只显示一次」令牌。 */
+function parseToken(stdout) {
+  const match = /保存）[：:]\s*(\S+)/.exec(stdout || "");
+  return match ? match[1] : "";
+}
+
+/** 取 init 输出里的端口。 */
+function parseInitPort(stdout) {
+  const match = /端口[：:]\s*(\d+)/.exec(stdout || "");
+  return match ? Number(match[1]) : undefined;
+}
+
+/** 从可能夹带日志的 stdout 里抠出第一个完整 JSON 对象（zbk.py check --json）。 */
+function extractJsonObject(text) {
+  const source = String(text || "");
+  const start = source.indexOf("{");
+  const end = source.lastIndexOf("}");
+  if (start === -1 || end === -1 || end <= start) return null;
+  try {
+    return JSON.parse(source.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+}
+
+/** 探测本地 zbk 服务 /health；返回健康体或 null。 */
+async function probeHealth(port, timeoutMs) {
+  const deadline = Date.now() + (timeoutMs || 1500);
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/health`, {
+        signal: AbortSignal.timeout(600),
+      });
+      if (response.ok) return await response.json().catch(() => ({}));
+    } catch {
+      /* 还没起来 / 端口未监听，继续等 */
+    }
+    await sleep(150);
+  }
+  return null;
+}
+
+/**
+ * detached 起 zbk.py serve（不接管进程生命周期；host 退出后服务仍在）。
+ * @returns {number} pid（拿不到时 0）
+ */
+function startDetachedServe(python, zbkPy, argv, cwd) {
+  const child = spawn(python, [zbkPy, ...argv], {
+    cwd,
+    detached: true,
+    windowsHide: true,
+    env: childEnv(),
+    stdio: "ignore",
+  });
+  child.unref();
+  return typeof child.pid === "number" ? child.pid : 0;
+}
+
+// ── 工具定义 ──────────────────────────────────────────────────────────────
+
+/** 共用参数：project_dir / data_dir（写进每个工具的 parameters）。 */
+const COMMON_PARAMETERS = {
+  project_dir: {
+    type: "string",
+    description:
+      "项目根目录（其下应有 tools/zbk/zbk.py）。省略时依次用 ZBK_PROJECT_DIR、会话工作目录、进程 cwd。",
+  },
+  data_dir: {
+    type: "string",
+    description: "zbk 数据目录，默认 <project_dir>/.zbk；也接受绝对路径。",
+  },
+};
+
+/** @param {any} ctx */
+function registerTools(ctx) {
+  ctx.tools.register(
+    defineTool({
+      name: "zbk_init",
+      description:
+        "初始化 zbk 可移植看板的数据目录（等价于 `python tools/zbk/zbk.py init --dir <项目>/.zbk`）：生成空模板 data/feedback/flows + uploads/ + config.json（随机编辑令牌，只打印一次）。什么时候用：用户要给某个项目开 zbk 看板/反馈栈/流程图，且该项目还没有 .zbk 数据目录时。返回数据目录、端口和一次性令牌——务必提醒用户立刻保存令牌。",
+      parameters: {
+        project_dir: COMMON_PARAMETERS.project_dir,
+        data_dir: COMMON_PARAMETERS.data_dir,
+        port: { type: "integer", description: "默认端口（写进 config.json），默认 8810。" },
+        force: { type: "boolean", description: "数据目录非空时强制重置为空模板并生成新令牌（会丢弃现有数据）。" },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            ok: { type: "boolean", required: true },
+            exit_code: { type: "integer", required: true },
+            data_dir: { type: "string", required: true },
+            port: { type: "integer" },
+            token: { type: "string" },
+            summary: { type: "string", required: true },
+            hint: { type: "string" },
+            stdout: { type: "string", required: true },
+            stderr: { type: "string", required: true },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.summary +
+              (value.token ? `\n令牌（只显示一次，请让用户立即保存）：${value.token}` : "") +
+              (value.hint ? `\n${value.hint}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const projectDir = await resolveProjectDir(args, exec, ctx);
+        const zbkPy = resolveZbkPy(projectDir);
+        const dataDir = resolveDataDir(projectDir, args.data_dir);
+        const argv = ["init", "--dir", dataDir];
+        if (Number.isInteger(args.port) && args.port > 0) argv.push("--port", String(args.port));
+        if (args.force === true) argv.push("--force");
+        const { result } = await runZbkWithFallback(zbkPy, argv, {
+          cwd: projectDir,
+          signal: exec.signal,
+        });
+        const ok = result.code === 0;
+        const token = ok ? parseToken(result.stdout) : "";
+        return {
+          ok,
+          exit_code: result.code,
+          data_dir: dataDir,
+          port: parseInitPort(result.stdout) ?? (Number.isInteger(args.port) ? args.port : DEFAULT_PORT),
+          token,
+          summary: ok
+            ? `zbk 初始化成功：${dataDir}（端口 ${parseInitPort(result.stdout) ?? DEFAULT_PORT}）`
+            : `zbk 初始化失败（退出码 ${result.code}）`,
+          hint: ok
+            ? "令牌只显示这一次：请让用户立即保存；接着调 zbk_serve 起服务、zbk_open 取地址。"
+            : result.code === 2
+              ? "数据目录已存在且非空；确认要重置时再传 force=true（会生成新令牌并清空空模板数据）。"
+              : "检查 python 与 zbk.py 路径：可传 project_dir，或设置 ZBK_ZBK_PY / ZBK_PYTHON。",
+          stdout: result.stdout,
+          stderr: result.stderr,
+        };
+      },
+    }),
+  );
+
+  ctx.tools.register(
+    defineTool({
+      name: "zbk_serve",
+      description:
+        "在后台启动 zbk 看板服务（等价于 `python tools/zbk/zbk.py serve --dir <项目>/.zbk --port <端口>`，只绑 127.0.0.1）：先探测 /health，未运行则 detached 拉起并等待健康响应，返回访问 URL。什么时候用：用户要在本机打开看板/反馈栈/流程图页面前。插件不托管进程生命周期（停服务/重启由用户负责）。",
+      parameters: {
+        project_dir: COMMON_PARAMETERS.project_dir,
+        data_dir: COMMON_PARAMETERS.data_dir,
+        port: { type: "integer", description: "服务端口；省略时读 .zbk/config.json，再缺省 8810。" },
+        host: {
+          type: "string",
+          description: "绑定地址（默认读 config.json，通常 127.0.0.1）；填 0.0.0.0 需用户自备反代与鉴权。",
+        },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            ok: { type: "boolean", required: true },
+            started: { type: "boolean", required: true },
+            already_running: { type: "boolean", required: true },
+            url: { type: "string", required: true },
+            port: { type: "integer", required: true },
+            pid: { type: "integer" },
+            summary: { type: "string", required: true },
+            hint: { type: "string" },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: value.summary + (value.hint ? `\n${value.hint}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const projectDir = await resolveProjectDir(args, exec, ctx);
+        const zbkPy = resolveZbkPy(projectDir);
+        const dataDir = resolveDataDir(projectDir, args.data_dir);
+        const config = readConfig(dataDir);
+        const configured = config && Number.isInteger(config.port) ? config.port : DEFAULT_PORT;
+        const port = Number.isInteger(args.port) && args.port > 0 ? args.port : configured;
+
+        const existing = await probeHealth(port, 700);
+        if (existing) {
+          return {
+            ok: true,
+            started: false,
+            already_running: true,
+            url: `http://127.0.0.1:${port}/`,
+            port,
+            pid: 0,
+            summary: `zbk 服务已在运行：http://127.0.0.1:${port}/`,
+            hint: "用 zbk_open 取地址；需要重启时先停掉现有进程再调本工具。",
+          };
+        }
+
+        const argv = ["serve", "--dir", dataDir, "--port", String(port)];
+        if (typeof args.host === "string" && args.host.trim() !== "") {
+          argv.push("--host", args.host.trim());
+        }
+        let pid = 0;
+        let errorText = "";
+        for (const python of pythonCandidates()) {
+          try {
+            pid = startDetachedServe(python, zbkPy, argv, projectDir);
+            break;
+          } catch (error) {
+            errorText = String(error && error.message ? error.message : error);
+          }
+        }
+        const health = pid > 0 || errorText === "" ? await probeHealth(port, 3000) : null;
+        const ok = Boolean(health);
+        return {
+          ok,
+          started: ok,
+          already_running: false,
+          url: `http://127.0.0.1:${port}/`,
+          port,
+          pid,
+          summary: ok
+            ? `zbk 服务已启动：http://127.0.0.1:${port}/`
+            : `zbk 服务启动失败（3s 内 /health 未响应）`,
+          hint: ok
+            ? "用 zbk_open 取地址后让用户用浏览器打开；停/重启由用户手动管理（插件不托管进程）。"
+            : `可手动执行：python "${zbkPy}" serve --dir "${dataDir}" --port ${port}` +
+              (errorText ? `（spawn 错误：${errorText}）` : ""),
+        };
+      },
+    }),
+  );
+
+  ctx.tools.register(
+    defineTool({
+      name: "zbk_check",
+      description:
+        "校验 zbk 数据（等价于 `python tools/zbk/zbk.py check --dir <项目>/.zbk --json`）：data.json 结构合法性 + 反馈/流程计数；坏数据 FAIL 且退出码非 0。什么时候用：用户改过看板/反馈数据后，或保存后要确认数据没坏时。返回 PASS/FAIL 摘要与错误列表。",
+      parameters: {
+        project_dir: COMMON_PARAMETERS.project_dir,
+        data_dir: COMMON_PARAMETERS.data_dir,
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            ok: { type: "boolean", required: true },
+            pass: { type: "boolean", required: true },
+            summary: { type: "string", required: true },
+            errors: {
+              type: "array",
+              required: true,
+              items: { type: "string" },
+            },
+            stats: { type: "json" },
+            hint: { type: "string" },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text:
+              value.summary +
+              (value.errors.length ? "\n错误：\n- " + value.errors.join("\n- ") : "") +
+              (value.hint ? `\n${value.hint}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const projectDir = await resolveProjectDir(args, exec, ctx);
+        const zbkPy = resolveZbkPy(projectDir);
+        const dataDir = resolveDataDir(projectDir, args.data_dir);
+        const { result } = await runZbkWithFallback(zbkPy, ["check", "--dir", dataDir, "--json"], {
+          cwd: projectDir,
+          signal: exec.signal,
+        });
+        const parsed = extractJsonObject(result.stdout);
+        const pass = result.code === 0 && parsed !== null && parsed.ok === true;
+        const errors = Array.isArray(parsed && parsed.errors)
+          ? parsed.errors.map((item) => String(item))
+          : pass
+            ? []
+            : [result.stderr.trim() || `zbk.py check 退出码 ${result.code}`];
+        return {
+          ok: pass,
+          pass,
+          summary: pass ? "PASS：zbk 数据校验通过" : "FAIL：zbk 数据校验未通过",
+          errors,
+          stats: (parsed && parsed.stats) || {},
+          hint: pass
+            ? undefined
+            : "按错误项修 .zbk/data.json（或重新 init 空模板）；结构与校验规则见 tools/zbk/README.md。",
+        };
+      },
+    }),
+  );
+
+  ctx.tools.register(
+    defineTool({
+      name: "zbk_open",
+      description:
+        "返回 zbk 看板的本机访问 URL（http://127.0.0.1:<port>/）并顺带探测服务是否在跑。什么时候用：用户要看板地址、准备在浏览器打开/贴给别人时。服务未启动时仍返回 URL，并提示先调 zbk_serve。",
+      parameters: {
+        project_dir: COMMON_PARAMETERS.project_dir,
+        data_dir: COMMON_PARAMETERS.data_dir,
+        port: { type: "integer", description: "覆盖端口；省略时读 .zbk/config.json，再缺省 8810。" },
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            ok: { type: "boolean", required: true },
+            url: { type: "string", required: true },
+            port: { type: "integer", required: true },
+            healthy: { type: "boolean", required: true },
+            summary: { type: "string", required: true },
+            hint: { type: "string" },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: "text",
+            text: value.summary + (value.hint ? `\n${value.hint}` : ""),
+          },
+        ],
+      },
+      async execute(args, exec) {
+        const projectDir = await resolveProjectDir(args, exec, ctx);
+        const dataDir = resolveDataDir(projectDir, args.data_dir);
+        const config = readConfig(dataDir);
+        const configured = config && Number.isInteger(config.port) ? config.port : DEFAULT_PORT;
+        const port = Number.isInteger(args.port) && args.port > 0 ? args.port : configured;
+        const health = await probeHealth(port, 1200);
+        return {
+          ok: true,
+          url: `http://127.0.0.1:${port}/`,
+          port,
+          healthy: Boolean(health),
+          summary: health
+            ? `zbk 看板地址：http://127.0.0.1:${port}/（服务健康）`
+            : `zbk 看板地址：http://127.0.0.1:${port}/（服务当前未响应）`,
+          hint: health
+            ? "用浏览器打开该地址；四页（脑图/反馈栈/流程图/需求引导）互相有导航。"
+            : "先调 zbk_serve，或手动执行 `python tools/zbk/zbk.py serve`。",
+        };
+      },
+    }),
+  );
+}
+
+/**
+ * Cordis 插件入口。
+ * @param {any} ctx
+ */
+function apply(ctx) {
+  ctx.logger?.info?.("zbk: host plugin loaded (tools: zbk_init / zbk_serve / zbk_check / zbk_open)");
+  registerTools(ctx);
+}
+
+export { apply, inject, name };

package/package.json

@@ -1,6 +1,56 @@
-{
-  "name": "dsh-plugin-zbk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "dsh-plugin-zbk",
+  "version": "0.1.0",
+  "description": "zbk 可移植看板工具包的 DSH 插件：会话内一句话 init / serve / check / open（插件只是入口，CLI 仍是事实源）",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "PLUGIN.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-0",
+    "@deepseek-ai/dsh-working-directory": ">=0.2.0-0"
+  },
+  "dependencies": {},
+  "//": [
+    "JSON 没有注释语法，说明按惯例放在 \"//\" 键里（npm/pnpm 忽略，不影响 npm pack / npm pkg get）。",
+    "peerDependencies 按 DSH 插件工厂惯例：只写 @deepseek-ai/* 前缀 + 下界；@deepseek-ai/dsh-* 由 DSH 运行时装（含 app.asar 内置副本）提供，profile 的 pnpm-workspace 设 autoInstallPeers:false，因此写 peer 不会真的装进用户 profile。",
+    "dependencies 必须为空：本插件只用 node: 内置模块 + 宿主提供的 @deepseek-ai/dsh-tools；不引 schemastery/zod（不声明 Config），避免给用户 profile 增装第三方运行时依赖。",
+    "本包无 client 产物：只有 host 工具（lib/index.js），因此 exports 不含 \"./client\"；四页静态资源仍由 zbk.py 自带的 web/ 提供，插件不复制、不代理页面。",
+    "dsh.bundle.patch 必须存在：plugin_manager 的 installBundle 只接受带 bundle patch 的包；本文件把插件行插进 loader 树。"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "zbk",
+    "看板",
+    "脑图",
+    "feedback"
+  ],
+  "engines": {
+    "dsh": ">=0.2.0-0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/new-service/zb-kvm.git",
+    "directory": "tools/zbk/dsh-plugin"
+  },
+  "homepage": "https://zb.aiopc.space/map/"
+}