dsh-plugin-dev-kb 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [1.0.8] - 2026-08-29
+
+- 文档：首屏数字带（168 页 · 52 篇 · 223 索引 · 0 依赖）；安装 yaml 标注「唯一的一步，复制即用」；新增「5 分钟验证」节；
+- 元数据：description/keywords 搜索工程（keywords 10 → 17）；
+- 新增英文版 README.en.md 与双语切换行。
+## [1.0.7] - 2026-08-25
+
+- 相关插件段新增 dsh-plugin-windows-guard（Windows 环境防坑守则 skill 插件，互相引流）。
+
+
 ## [1.0.6] - 2026-08-21
 
 - 整理：package.json 补 `selfcheck` / `rebuild-index` npm 脚本（发布前可一键自检）；

package/README.en.md

@@ -0,0 +1,144 @@
+[中文](./README.md) | **English**
+
+# dsh-plugin-dev-kb
+
+![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)
+
+> **168-page official mirror · 52 supplementary docs · 223-file search index · 0 runtime dependencies**
+
+**The official docs at your side whenever you write dsh plugins**: the entire content of the DeepSeek Harness official documentation site
+<https://deepseek-harness.github.io/deepseek-harness/> is organized into a form natively usable by dsh —
+once this plugin is installed, the agent automatically loads the knowledge base when writing plugins and locates docs by task scenario, so you never have to dig through web pages again.
+
+## What is this
+
+- **Complete site mirror**: the official docs (VitePress) are generated as a projection of the raw Markdown in
+  `docs/` of the `deepseek-ai/deepseek-harness` repository (links rewritten to site routes, verbatim identical to the live site). 168 pages in both Chinese and English.
+- **Supplementary docs**: 52 development references from the repo's `docs/` that were not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.).
+- **Agent-friendly**: the `skills/dsh-plugin-dev-kb.md` skill lets dsh auto-load it during plugin development tasks, providing the knowledge base location,
+  topic navigation, and search strategy; `kb/meta/topics.md` maps task scenarios to the files to read; `kb/meta/search-index.json` provides full search coverage.
+
+## Features
+
+- **Complete mirror of the official docs**: the entire content of the deepseek-ai/deepseek-harness official documentation site, organized into a form natively usable by dsh,
+  168 pages in both Chinese and English, links rewritten to site routes, verbatim identical to the live site;
+- **Repo supplementary docs**: 52 development references not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.);
+- **Agent-friendly**: the `dsh-plugin-dev-kb` skill lets dsh auto-load the knowledge base during plugin development tasks;
+  `kb/meta/topics.md` maps task scenarios to the files to read, and `kb/meta/search-index.json` provides full search coverage;
+- **Human-usable**: browse the `kb/` directory directly, or open `kb/INDEX.md` to look things up by URL mapping;
+- Pure data plugin, zero runtime dependencies, registers no tools.
+
+## Configuration
+
+No configuration required — it works right after installation:
+
+- Reads no environment variables, needs no API key / token, writes no config files;
+- After mounting, the `skills/dsh-plugin-dev-kb.md` skill enters the available skills list at session startup and takes effect automatically;
+- Knowledge base updates go through `npm run rebuild-index` (see "Updating the knowledge base"); there are no manual configuration items.
+
+## Install / Mount
+
+```powershell
+# npm (recommended)
+dsh plugin --profile web add dsh-plugin-dev-kb
+# or GitHub
+dsh plugin --profile web add github:Pasumao/dsh-plugin-dev-kb
+```
+
+Install from source (local development / debugging):
+
+```bash
+git clone https://github.com/Pasumao/dsh-plugin-dev-kb.git
+cd dsh-plugin-dev-kb
+npm install
+# mount into the profile as a link: dependency
+```
+
+This plugin is a "pure data + skill" plugin and does not ship with automatic bundle mounting. After installation, add one line at the end of the profile's
+`cordis.patch.yml` to mount it manually (**the only one-time step, just copy it**;
+it mounts as a plugin row in the profile root layer, and its `skills/` skill enters the global layer):
+
+```yaml
+- insert:
+    - id: dsh-plugin-dev-kb
+      name: dsh-plugin-dev-kb
+```
+
+> Only after restarting / creating a new dsh session will the `dsh-plugin-dev-kb` skill appear in the available skills list (the skill catalog is snapshotted at session startup).
+
+## 5-minute verification
+
+After restarting, open a new session and simply ask:
+
+> Help me write a minimal dsh plugin
+
+The agent will automatically load the `dsh-plugin-dev-kb` skill (visible in the skill catalog), locate the docs via `kb/meta/topics.md`,
+and only then start working — if you see it referencing `kb/site/...` paths, the verification has passed.
+
+## Directory structure
+
+```
+dsh-plugin-dev-kb/
+├── cordis.patch.yml   mount declaration
+├── package.json       plugin metadata
+├── skills/
+│   └── dsh-plugin-dev-kb.md   ★ knowledge base usage guide (the skill the agent loads)
+├── kb/
+│   ├── site/          site mirror: guide/ develop/ reference/ (+ en/ English site)
+│   ├── extra/         repo supplementary docs: glossary, defensive-patterns, module-graph, postmortem/, i18n/ …
+│   ├── meta/
+│   │   ├── topics.md         ★ topic navigation: task scenario → files
+│   │   ├── search-index.json full index (223 files)
+│   │   ├── source.json       source commit / time / stats
+│   │   └── site-pages.txt    list of live site pages
+│   ├── INDEX.md        site URL ↔ local file mapping
+│   └── README.md       knowledge base overview and update instructions
+└── LICENSE
+```
+
+## Usage
+
+- **Agent side**: when writing plugins / Tools / config / services / events / packaging / LLM adapters, load
+  the `dsh-plugin-dev-kb` skill → read `kb/meta/topics.md` to locate → read/grep as needed.
+- **Human side**: browse the `kb/` directory directly, or open `kb/INDEX.md` to look things up by URL mapping.
+
+## Self-check
+
+Run the structural self-check before publishing (offline, zero dependencies):
+
+```powershell
+npm run selfcheck   # structural integrity + entry / bundle patch existence
+```
+
+## Updating the knowledge base
+
+See `kb/README.md`: re-clone `deepseek-ai/deepseek-harness` (master branch), install the projection dependencies, then
+call `projectDocs()` from `scripts/project-doc-site.ts` inside the repo to generate `website/.generated/`,
+overwrite this plugin's `kb/site/` (and sync `kb/extra/` according to the publishing checklist), then run
+`node scripts/rebuild-index.mjs` in this plugin's root directory to rebuild the index and INDEX.md.
+
+## Related plugins
+
+This plugin is part of **Pasumao's dsh plugin ecosystem**; other published plugins in the same series can be used alongside it:
+
+| Plugin (npm) | GitHub | Description |
+|---|---|---|
+| [dsh-notify](https://www.npmjs.com/package/dsh-notify) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-notify) | Native Windows notifications + system tray |
+| [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-choice-refresh) | Choice enhancement: regenerate options / more options |
+| [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-image-tools) | Image choice cards + inline images in replies + image handoff for blind models |
+| [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-table-zoom) | Floating viewer for long chat tables + one-click copy as Markdown |
+| [dsh-plugin-windows-guard](https://www.npmjs.com/package/dsh-plugin-windows-guard) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-windows-guard) | Windows environment pitfall prevention: rule skills + mojibake detection / dangerous-write interception / encoding diagnosis & repair |
+| [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-workbench) | VS Code-style file explorer + editable preview |
+
+> See [Pasumao · dsh plugins](https://github.com/Pasumao) for the rest of the series; if you find them useful, a ⭐ on GitHub is much appreciated.
+
+## AI-generated content statement
+
+The knowledge base content is an organized mirror of the official documentation (sources noted in `kb/meta/source.json`); the index and
+navigation were AI-assisted (DeepSeek Harness), and all of it has been manually verified.
+
+## License
+
+MIT

package/README.md

@@ -4,6 +4,10 @@
 ![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-dev-kb)
 ![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
 
+[**中文**](./README.md) | [English](./README.en.md)
+
+> **168 页官方镜像 · 52 篇补充文档 · 223 文件搜索索引 · 0 运行时依赖**
+
 **写 dsh 插件时的随身官方文档**：把 DeepSeek Harness 官方文档站点
 <https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态——
 装了这个插件，agent 写插件时自动加载知识库，按任务场景定位文档，不用再翻网页。
@@ -53,7 +57,8 @@ npm install
 ```
 
 本插件是「纯数据 + 技能」插件，不自带 bundle 自动挂载，装完后在 profile 的
-`cordis.patch.yml` 末尾加一行手动挂载（挂载为 profile 根层插件行，其 `skills/` 技能进入全局层）：
+`cordis.patch.yml` 末尾加一行手动挂载（**唯一的一次性步骤，复制即用**；
+挂载为 profile 根层插件行，其 `skills/` 技能进入全局层）：
 
 ```yaml
 - insert:
@@ -63,6 +68,15 @@ npm install
 
 > 重新启动 / 新建 dsh 会话后，`dsh-plugin-dev-kb` 技能才会出现在可用技能列表中（技能清单在会话启动时快照）。
 
+## 5 分钟验证
+
+重启后开一个新会话，直接问：
+
+> 帮我写一个最小的 dsh 插件
+
+agent 会自动加载 `dsh-plugin-dev-kb` 技能（技能清单里可见），按 `kb/meta/topics.md`
+定位文档后再动手——看到它引用 `kb/site/...` 路径即验证通过。
+
 ## 目录结构
 
 ```
@@ -115,6 +129,7 @@ npm run selfcheck   # 结构完整 + 入口 / bundle patch 存在性
 | [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-choice-refresh) | 选择增强：重新生成选项 / 更多选项 |
 | [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-image-tools) | 图片选择卡 + 回复内嵌图片 + 盲模型收图 |
 | [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-table-zoom) | 聊天长表格浮窗查看 + 一键复制 Markdown |
+| [dsh-plugin-windows-guard](https://www.npmjs.com/package/dsh-plugin-windows-guard) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-windows-guard) | Windows 环境防坑：守则技能 + 乱码检测 / 危险写拦截 / 编码诊断修复 |
 | [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-workbench) | VS Code 风格文件浏览器 + 可编辑预览 |
 
 > 本系列其余插件见 [Pasumao · dsh 插件](https://github.com/Pasumao)；觉得好用欢迎到 GitHub 点 ⭐。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-dev-kb",
-  "description": "DeepSeek Harness (dsh) 插件开发知识库：官方文档站点的完整 Markdown 镜像（中英双语 168 页）+ 仓库补充文档（52 篇）+ 主题导航与搜索索引，以 dsh-plugin-dev-kb 技能形式让 agent 在插件开发任务中自动加载定位文档。纯数据插件，无运行时依赖。",
-  "version": "1.0.6",
+  "description": "dsh 插件开发知识库：DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 168 页）+ 52 篇仓库补充开发参考 + 主题导航与 223 文件全量搜索索引；以 dsh-plugin-dev-kb 技能让 agent 在插件开发任务中自动加载定位文档。纯数据插件，零运行时依赖。",
+  "version": "1.0.8",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -15,6 +15,7 @@
     "scripts",
     "cordis.patch.yml",
     "README.md",
+    "README.en.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -30,9 +31,16 @@
     "cordis",
     "plugin",
     "knowledge",
+    "knowledge-base",
     "documentation",
+    "official-docs",
+    "documentation-mirror",
     "kb",
-    "plugin-development"
+    "plugin-development",
+    "agent-skills",
+    "skills",
+    "retrieval",
+    "rag"
   ],
   "repository": {
     "type": "git",