dsh-plugin-dev-kb 1.0.0 → 1.0.1

package/README.md

@@ -1,7 +1,12 @@
 # dsh-plugin-dev-kb
 
-DeepSeek Harness（dsh）**插件开发知识库**：把官方文档站点
-<https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态。
+![npm version](https://img.shields.io/npm/v/dsh-plugin-dev-kb)
+![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-dev-kb)
+![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
+
+**写 dsh 插件时的随身官方文档**：把 DeepSeek Harness 官方文档站点
+<https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态——
+装了这个插件，agent 写插件时自动加载知识库，按任务场景定位文档，不用再翻网页。
 
 ## 这是什么
 
@@ -13,9 +18,21 @@ DeepSeek Harness（dsh）**插件开发知识库**：把官方文档站点
 
 ## 安装 / 挂载
 
-插件目录放在 `D:\dsh\plugins\dsh-plugin-dev-kb\`（与本机其他 dsh 插件同级）。
-`cordis.patch.yml` 声明 `- insert: { id: dsh-plugin-dev-kb, name: dsh-plugin-dev-kb }`，
-挂载为 profile 根层插件行；其 `skills/` 技能进入全局层。
+```powershell
+# npm（推荐）
+dsh plugin --profile web add dsh-plugin-dev-kb
+# 或 GitHub
+dsh plugin --profile web add github:Pasumao/dsh-plugin-dev-kb
+```
+
+本插件是「纯数据 + 技能」插件，不自带 bundle 自动挂载，装完后在 profile 的
+`cordis.patch.yml` 末尾加一行手动挂载（挂载为 profile 根层插件行，其 `skills/` 技能进入全局层）：
+
+```yaml
+- insert:
+    - id: dsh-plugin-dev-kb
+      name: dsh-plugin-dev-kb
+```
 
 > 重新启动 / 新建 dsh 会话后，`dsh-plugin-dev-kb` 技能才会出现在可用技能列表中（技能清单在会话启动时快照）。
 
@@ -48,8 +65,9 @@ dsh-plugin-dev-kb/
 
 ## 更新知识库
 
-见 `kb/README.md`：重新克隆 `deepseek-ai/deepseek-harness`，安装投影依赖后运行
-`scripts/project-doc-site.ts` 生成 `website/.generated/`，覆盖 `kb/site/`，再重新生成索引。
+见 `kb/README.md`：重新克隆 `deepseek-ai/deepseek-harness`（master 分支），安装投影依赖后
+在仓库内运行 `node --experimental-strip-types run-projector.ts` 生成 `website/.generated/`，
+覆盖本插件的 `kb/site/`，再在本插件根目录运行 `node scripts/rebuild-index.mjs` 重建索引与 INDEX.md。
 
 ## License
 

package/lib/index.js

@@ -0,0 +1,113 @@
+/**
+ * dsh-plugin-dev-kb — 主机插件（纯技能载体，无工具/命令）。
+ *
+ * 挂载于 profile 根层（全局层），唯一职责：把 skills/ 目录下的
+ * dsh-plugin-dev-kb 技能注册为 runtime skill，让每个会话的 agent
+ * 在插件开发 / 查询 dsh 能力 / 写 Tool / 配置 cordis.yml 类任务时，
+ * 能按技能 description 自动加载，从而获知知识库位置与阅读路径。
+ *
+ * 知识库数据（kb/ 目录：site/ 站点镜像 + extra/ 补充文档 + meta/
+ * 主题导航与索引）是纯文档，模型通过文件工具按技能指示直接读取。
+ *
+ * 依赖纪律：本模块不 import 任何 @deepseek-ai/* 运行时包（插件以
+ * link: 方式装入 profile，Node ESM 按 realpath 解析链接包，外部依赖
+ * 从插件目录解析不到；这里本来也不需要）。
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-plugin-dev-kb'
+export const inject = ['skills']
+
+const PKG_DIR = dirname(fileURLToPath(import.meta.url))
+const SKILLS_DIR = join(PKG_DIR, '..', 'skills')
+
+/** 极简 frontmatter 解析（name/description/whenToUse）。 */
+function parseFrontmatter(md) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(md)
+  if (!match) return { name: undefined, description: undefined, whenToUse: undefined, body: md }
+  const meta = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const i = line.indexOf(':')
+    if (i <= 0) continue
+    const key = line.slice(0, i).trim()
+    if (key) meta[key] = line.slice(i + 1).trim().replace(/^["']|["']$/g, '')
+  }
+  return { ...meta, body: md.slice(match[0].length) }
+}
+
+/** 从 skills/ 目录加载技能定义（文件缺失/无 frontmatter 时跳过并警告，绝不让插件挂载失败）。 */
+function loadSkills() {
+  const out = []
+  if (!existsSync(SKILLS_DIR)) {
+    console.warn('[dsh-plugin-dev-kb] skills 目录缺失，技能未加载：' + SKILLS_DIR)
+    return out
+  }
+  for (const file of readdirSync(SKILLS_DIR)) {
+    if (!file.endsWith('.md')) continue
+    try {
+      const fm = parseFrontmatter(readFileSync(join(SKILLS_DIR, file), 'utf8'))
+      if (!fm.name || !fm.description) {
+        console.warn(`[dsh-plugin-dev-kb] 技能文件缺少 name/description frontmatter，已跳过：${file}`)
+        continue
+      }
+      out.push({
+        name: fm.name,
+        description: fm.description,
+        whenToUse: fm.whenToUse,
+        body: fm.body
+      })
+    } catch (err) {
+      console.warn(`[dsh-plugin-dev-kb] 技能文件读取失败，已跳过：${file}（${err?.message ?? err}）`)
+    }
+  }
+  return out
+}
+
+/** 挂载状态文件（自诊断：$DSH_HOME/dsh-plugin-dev-kb.state.json）。 */
+function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), '.dsh')
+}
+
+export function apply(ctx, config) {
+  const disposers = []
+  const state = { skills: [] }
+
+  // 契约（dsh-skill validateDefinition）：定义必须含 name/description/
+  // source/content 四个字符串；provider 缺省为 'runtime'。
+  for (const skill of loadSkills()) {
+    try {
+      disposers.push(ctx.skills.register({
+        name: skill.name,
+        description: skill.description,
+        ...(skill.whenToUse ? { whenToUse: skill.whenToUse } : {}),
+        source: 'runtime',
+        content: skill.body
+      }))
+      state.skills.push(skill.name)
+      console.log(`[dsh-plugin-dev-kb] 技能已注册：${skill.name}`)
+    } catch (err) {
+      console.warn(`[dsh-plugin-dev-kb] 技能注册失败：${skill.name}（${err?.message ?? err}）`)
+    }
+  }
+
+  try {
+    writeFileSync(join(dshHome(), 'dsh-plugin-dev-kb.state.json'), JSON.stringify({
+      plugin: 'dsh-plugin-dev-kb',
+      mountedAt: new Date().toISOString(),
+      skills: state.skills
+    }, null, 2), 'utf8')
+  } catch { /* 状态文件写入失败不影响挂载 */ }
+
+  console.log(`[dsh-plugin-dev-kb] 已挂载：${state.skills.length} 技能（知识库在 kb/ 目录）`)
+
+  // 卸载清理（HMR 重载时避免重复注册）。
+  return () => {
+    for (const dispose of disposers) {
+      try { dispose() } catch { /* ignore */ }
+    }
+  }
+}

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "dsh-plugin-dev-kb",
   "description": "DeepSeek Harness (dsh) 插件开发知识库：官方文档站点的完整 Markdown 镜像（中英双语 168 页）+ 仓库补充文档（50 篇）+ 主题导航与搜索索引，以 dsh-plugin-dev-kb 技能形式让 agent 在插件开发任务中自动加载定位文档。纯数据插件，无运行时依赖。",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
   "files": [
+    "lib",
     "kb",
     "skills",
     "scripts",