dsh-plugin-dev-kb 1.0.0

package/kb/site/reference/tool-execution-pipeline.md

@@ -0,0 +1,66 @@
+---
+editSource: "docs/tool-execution-pipeline.zh.md"
+---
+
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/tool-execution-pipeline.md` 重新记录配对。 -->
+
+# 工具执行流水线
+
+此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `finalizeContent` 和 `tools/result` 在此之后运行。
+
+```mermaid
+flowchart TD
+  model["Assistant message contains tool-call block"]
+  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
+  presentCall["UI pending card<br/>presentCall(args)"]
+  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
+  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
+  denied["denied or approval refused<br/>tool body skipped"]
+  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
+  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
+  toolBody["Registered tool execute() body"]
+  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
+  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/code-dispatch</code>"]
+  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
+  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
+  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
+  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
+  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
+  allResults["Tool batch settled<br/>recorded tool/result events complete"]
+  presentResult["UI completed card<br/>presentResult(args, result)"]
+  model --> toolCall
+  toolCall --> presentCall
+  toolCall --> pre
+  pre -->|allow| guards
+  guards -->|allow| around
+  guards -->|deny| denied
+  guards -.->|throw| normalized
+  around --> toolBody
+  pre -->|deny| denied
+  pre -->|ask| approval
+  approval -->|allowed-once| guards
+  approval -->|rejected, cancelled, unavailable| denied
+  approval -.->|throw| normalized
+  denied --> post
+  pre -.->|throw| normalized
+  toolBody --> fsGate
+  fsGate --> toolBody
+  toolBody --> owned
+  toolBody --> around
+  around --> post
+  around -.->|wrapper throws| normalized
+  post -.->|throw| normalized
+  post --> finalize
+  normalized --> finalize
+  finalize --> final
+  final --> toolResult
+  toolResult --> presentResult
+  toolResult --> allResults
+  allResults --> context
+```
+
+文件系统的先读后编辑检查位于 `tool-fs` 之下，通过 `fs/*` 事件实现。通用的前置／后置 waterfall 承载钩子与审批策略；`ctx.approval` 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。超时等环绕分发关注点对 `tools/execute` 进行包装。注册表会对候选结果进行无损快照；如果快照失败，则会先将失败规范化，之后再由可见定义中已随快照固定的 `finalizeContent` 回调强制执行其同步且仅限内容的不变式。随后，`tools/result` 会观察不可变、可由 JSON 无损表示的结果。这样一来，钩子便可跨越不同工具系列，而无需让工具与某个策略服务耦合。Code Mode 会将保留的 `run_code` 传输及其序列化子调用都送入流水线；子调用携带父级 token、记录 `tool/code-dispatch`、将拒绝呈现为具有约束力的驳回，并省略 `additionalContexts`，以保持调用与结果相邻。
+
+维护模式：英文源文件包含人工维护的 Mermaid 流程图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的工具 schema 与事件签名位于生成的目录中。

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "dsh-plugin-dev-kb",
+  "description": "DeepSeek Harness (dsh) 插件开发知识库：官方文档站点的完整 Markdown 镜像（中英双语 168 页）+ 仓库补充文档（50 篇）+ 主题导航与搜索索引，以 dsh-plugin-dev-kb 技能形式让 agent 在插件开发任务中自动加载定位文档。纯数据插件，无运行时依赖。",
+  "version": "1.0.0",
+  "type": "module",
+  "files": [
+    "kb",
+    "skills",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "harness",
+    "cordis",
+    "plugin",
+    "knowledge",
+    "documentation",
+    "kb",
+    "plugin-development"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pasumao/dsh-plugin-dev-kb.git"
+  },
+  "homepage": "https://github.com/Pasumao/dsh-plugin-dev-kb",
+  "bugs": {
+    "url": "https://github.com/Pasumao/dsh-plugin-dev-kb/issues"
+  },
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/scripts/rebuild-index.mjs

@@ -0,0 +1,88 @@
+// Rebuilds kb/INDEX.md (site URL ↔ local file) and kb/meta/search-index.json.
+// Run from the plugin root:  node scripts/rebuild-index.mjs
+import { readdirSync, readFileSync, writeFileSync, statSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PLUGIN = join(dirname(fileURLToPath(import.meta.url)), '..')
+// Normalize to forward slashes so `rel` derivation matches walk() output on Windows.
+const KB = join(PLUGIN, 'kb').replace(/\\/g, '/')
+const BASE = 'https://deepseek-harness.github.io/deepseek-harness'
+
+function walk(dir) {
+  const out = []
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry)
+    if (statSync(abs).isDirectory()) out.push(...walk(abs))
+    else out.push(abs)
+  }
+  return out
+}
+
+function stripFrontmatter(text) {
+  if (!text.startsWith('---\n')) return text
+  const end = text.indexOf('\n---\n', 4)
+  return end === -1 ? text : text.slice(end + 5)
+}
+
+function firstHeading(text) {
+  for (const line of stripFrontmatter(text).split('\n')) {
+    const m = line.match(/^#\s+(.+)$/)
+    if (m) return m[1].trim()
+  }
+  return ''
+}
+
+function routeToUrl(rel) {
+  let p = rel.replace(/\.md$/, '')
+  if (p.endsWith('/index')) p = p.slice(0, -6)
+  else if (p === 'index') p = ''
+  return p === '' ? BASE : `${BASE}/${p}`
+}
+
+// ---- collect entries ----
+const entries = []
+for (const abs of walk(KB)) {
+  if (!abs.endsWith('.md')) continue
+  const rel = abs.replace(/\\/g, '/').replace(KB + '/', '')
+  const text = readFileSync(abs, 'utf8')
+  entries.push({
+    path: `kb/${rel}`,
+    url: rel.startsWith('site/') ? routeToUrl(rel.slice(5)) : '',
+    title: firstHeading(text),
+    chars: text.length,
+    rel,
+  })
+}
+entries.sort((a, b) => a.rel.localeCompare(b.rel))
+
+// ---- search-index.json ----
+const indexRows = entries.map(({ path, url, title, chars }) => ({ path, url, title, chars }))
+mkdirSync(join(KB, 'meta'), { recursive: true })
+writeFileSync(join(KB, 'meta', 'search-index.json'), JSON.stringify(indexRows, null, 1) + '\n', 'utf8')
+
+// ---- INDEX.md ----
+const siteRows = entries.filter(e => e.rel.startsWith('site/'))
+const en = (rel) => rel.startsWith('site/en/')
+const group = (pred) => siteRows.filter(r => pred(r.rel))
+const table = (rows) => rows.length === 0
+  ? '_（无）_'
+  : ['| 页面 | 站点 URL | 本地文件 |', '| --- | --- | --- |']
+    .concat(rows.map(r => `| ${r.title || r.rel} | [${r.url}](${r.url}) | \`site/${r.rel.slice(5)}\` |`))
+    .join('\n')
+
+const md = []
+md.push('# DeepSeek Harness 文档索引', '')
+md.push(`> 由 \`scripts/rebuild-index.mjs\` 自动生成。共 ${siteRows.length} 个站点页面（中英双语），另有 ${entries.length - siteRows.length} 个补充文档在 \`extra/\`。`, '')
+md.push('## 中文站点（根路径）', '')
+md.push('### 首页', '', table(group(rel => rel === 'site/index.md')), '')
+md.push('### 入门（/guide/）', '', table(group(rel => !en(rel) && rel.startsWith('site/guide/'))), '')
+md.push('### 开发（/develop/）', '', table(group(rel => !en(rel) && rel.startsWith('site/develop/'))), '')
+md.push('### 参考（/reference/）', '', table(group(rel => !en(rel) && rel.startsWith('site/reference/'))), '')
+md.push('## 英文站点（/en/）', '')
+md.push('### 首页', '', table(group(rel => rel === 'site/en/index.md')), '')
+md.push('### 全部英文页面（/en/...）', '', table(group(rel => en(rel) && rel !== 'site/en/index.md')), '')
+md.push('---', '', `*站点页面：${siteRows.length}（中文 ${siteRows.filter(r => !en(r.rel)).length}，英文 ${siteRows.filter(r => en(r.rel)).length}）*`, '')
+writeFileSync(join(KB, 'INDEX.md'), md.join('\n') + '\n', 'utf8')
+
+console.log(`rebuilt INDEX.md + search-index.json (${entries.length} files)`)

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

@@ -0,0 +1,66 @@
+---
+name: dsh-plugin-dev-kb
+description: DeepSeek Harness 官方文档知识库的使用指南：知识库位置与结构、按任务场景的阅读路径、检索策略。写 dsh 插件 / Tool / 配置 / 服务 / 事件 / 打包发布 / LLM 适配器时先加载本技能定位文档。
+whenToUse: 开发 dsh 插件、查询 dsh 能力与 API、写 Tool、配置 cordis.yml、扩展 Harness 时
+---
+# dsh 插件开发知识库使用指南（dsh-plugin-dev-kb）
+
+本插件内置 DeepSeek Harness 官方文档的完整镜像，供插件开发时快速定位与检索。
+
+## 0. 知识库位置
+
+- **知识库根**：`D:\dsh\plugins\dsh-plugin-dev-kb\kb\`（绝对路径，可直接 read/glob/grep）
+- 数据来源：官方文档站点（VitePress）的仓库原始 Markdown，链接已按站点路由重写，与线上站点逐字一致（见 `kb/meta/source.json` 的 commit）
+
+## 1. 目录结构
+
+```
+kb/
+├── site/            线上站点完整镜像（中英双语，优先读这里）
+│   ├── guide/       入门：quickstart / providers / python-sdk
+│   ├── develop/     basic(第一个插件/tool/config/publish)、framework(生命周期/服务/事件)、
+│   │                practice(能力分层/LLM适配器)、cordis-tutorial(7章)
+│   ├── reference/   index(架构)、cordis-primer、capability-seams、agent-lifecycle、
+│   │                config-catalog、tool-catalog、cordis-api/(6)、cookbook/(6)、subsystems/(43)
+│   └── en/          英文站镜像（结构与中文站一致）
+├── extra/           仓库内未发布到站点的补充文档：glossary、defensive-patterns、
+│                    module-graph、testing、postmortem/(4)、i18n/、cookbook 与 subsystems 扩展
+├── meta/
+│   ├── topics.md    ★ 主题导航：任务场景 → 要读的文件（先用这个）
+│   ├── search-index.json  全量检索索引（220 文件：path/url/title/字符数）
+│   ├── source.json  来源信息（commit/时间/统计）
+│   └── site-pages.txt     线上站点页面清单
+├── INDEX.md         全部 站点 URL ↔ 本地文件 对照
+└── README.md        知识库总览与更新方法
+```
+
+## 2. 使用流程（三选一，从快到慢）
+
+1. **按任务找文档**：读 `kb/meta/topics.md`，找到对应主题（如"开发一个 Tool"），按核心/扩展顺序读列出的文件。
+2. **按关键词检索**：对 `kb/meta/search-index.json` 用 grep 过滤（如 `grep -i "tool" search-index.json`），或直接 grep `kb/site/` 内容定位。
+3. **按 URL 反查**：已知线上页面 URL 时，在 `kb/INDEX.md` 查对应本地文件。
+
+## 3. 阅读原则
+
+- **中文优先**：默认读 `site/` 下中文文件；需要英文原文时读 `site/en/` 对应路径。
+- **大文件局部读**：`reference/config-catalog.md`、`reference/tool-catalog.md`、`extra/module-graph.md`、`reference/subsystems/session.md` 等超过 100KB，先用 grep 定位再 read 局部，禁止整读。
+- **代码示例可直接引用**：文档中的 `apply(ctx)` 插件骨架、`ctx.tools.register`、`inject` 声明等可直接用于新代码；但需注意知识库是 commit 快照，若与当前安装版本 API 不一致，以实际安装包为准。
+- **常见检索关键词**：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`、`Branded`。
+
+## 4. 插件开发高频路径速查
+
+| 任务 | 先读 |
+| --- | --- |
+| 写第一个插件 | `site/develop/basic/index.md` |
+| 开发 Tool | `site/develop/basic/tool.md` + `site/reference/cookbook/adding-a-tool.md` |
+| 插件配置 | `site/develop/basic/config.md` |
+| 服务与依赖 | `site/develop/framework/service.md` |
+| 事件监听 | `site/develop/framework/events.md` |
+| 打包发布 | `site/develop/basic/publish.md` |
+| LLM 适配器 | `site/develop/practice/llm-adapter.md` |
+| 能力扩展 | `site/develop/practice/index.md` + `site/reference/capability-seams.md` |
+| 子系统能力 | `site/reference/subsystems/index.md` → 对应子系统页 |
+
+## 5. 更新知识库
+
+见 `kb/README.md` 的更新方法（重新克隆 `deepseek-ai/deepseek-harness` 并运行站点投影器）。