前言¶
在 DSH（DeepSeek Harness）里让智能体读懂一个代码库，常见做法是反复扫目录、贴片段，或依赖会把仓库内容传到外部的在线文档服务。前者难沉淀成可检索的叙事文档，后者与「数据不出本机」的目标冲突。社区插件目录里也有若干「地图 / 引用 / 图」类方案，但要么缺分页正文，要么依赖第二套工具链或停更。
dsh-wiki（@acfufu/dsh-wiki）面向同一类需求：在本地由 agent 读懂仓库，生成带 路径:行号 证据的分页 wiki，并构建可离线浏览的单文件站点，全程不上传、不发起网络请求。下面介绍它是什么、如何安装与使用，以及使用时需要注意的边界。
这是什么¶
dsh-wiki 是维护者 Acfufu 发布的 DSH 社区插件，在 SkillHub 分类为「记忆」。当前 package 版本为 0.1.2，许可证 MIT，兼容 DSH >=0.2.0-rc.1（README 写明 peer 覆盖 ^0.1.1-rc.1 || ^0.2.0-rc.1，并在 0.2.2-rc.1 实测通过）。
装好插件后，你会得到四类入口：
| 入口 | 形式 | 作用 |
|---|---|---|
dsh-wiki 技能 |
runtime skill | 对话中说「给这个仓库生成 wiki」等，走盘点 → 配置 → 语言判定 → 页面树 → 逐页写作 → build + selfcheck |
/wiki 命令 |
slash command | generate / view / list |
| 侧栏 Wiki 面板 | 左栏全局面板 | 列出已构建 wiki，应用内嵌阅读 |
| Wiki 按钮 | 会话头部槽位 | 独立窗口打开本机索引页 |
生成结果落在各仓库内的 .dsh-wiki/（目录名可通过配置修改），主要包括：
wiki.json：分页结构与内嵌 markdown（schemarepo-wiki-local/1）pages/<id>.md：每页导出副本，便于 diffgeneration-meta.json：生效配置与字段来源site/index.html：单文件自包含站点（目录树、全文搜索、深浅主题、mermaid 离线渲染等）
正文中的 `path:line` 引用会经 selfcheck 机检：文件须存在、行号须在范围内，否则生成失败。站点还会做零外链机检，避免外链脚本、字体等泄露出网。
核心功能¶
本地生成与机检¶
智能体在本地完成仓库理解与 wiki 写作，不把仓库内容上传。构建器为纯 Python 3.7+ 标准库实现，README 写明无需 pip 安装第三方依赖。
证据引用¶
与「只有引用没有正文」或「只有图」的方案不同，dsh-wiki 强调叙事正文与强制机检的 路径:行号 证据并存；越界引用会导致生成失败，而不是 silently 坏链。
离线站点¶
site/index.html 为自包含单页：搜索、双主题、窄屏适配、内联 SVG 净化等。可在 DSH 桌面宿主的本机回环路由下浏览，也可通过侧栏或独立窗口打开。
发现与迁移¶
插件从会话事件记住工作目录，持久化在 <profile home>/dsh-wiki/registry.json，并扫描已知目录的同级目录以发现已有 site/index.html。可选 config.wikiRoots 补充扫描根路径。从 ZCode 存量 wiki（~/.zcode/v2/repo-wiki/<hash>）可通过 import-legacy 导入，格式与 zcode-repo-wiki 兼容。
安装与启用¶
前置：DSH Desktop 或 web profile（dsh-base + dsh-web-app）、python3 ≥ 3.7。
路线 A（GUI）：侧栏「插件」→ 添加插件 → 填写本仓库路径或 https://github.com/Acfufu/dsh-wiki → 安装并启用。desktop profile 为 patchReload: live，装完刷新页面即可。
路线 B（CLI）：README 给出的示例如下（macOS 桌面应用内 CLI 路径；Linux 用户需改为你本机 dsh 可执行文件路径）：
CLI="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$CLI" plugin --profile desktop add github:Acfufu/dsh-wiki
"$CLI" plugin --profile desktop list
安装前建议自行查看 GitHub 源码与 MIT 许可证；插件在 DSH 宿主进程权限下运行，与其它社区插件一样，宜配合来源审查（README 提及可配合 @jieai/dsh-plugin-vet 自查）。
典型用法¶
在 DSH 会话中使用斜杠命令：
/wiki generate # 为当前工作区生成完整 wiki（fork 子代理执行技能）
/wiki generate /path/repo # 指定仓库路径
/wiki view # 输出当前仓库站点的本机 URL
/wiki list # 列出所有已知 wiki
本机路由（桌面宿主回环）包括：
/dsh-wiki/— wiki 索引页/dsh-wiki/site?path=<仓库>/.dsh-wiki— 打开某个站点/dsh-wiki/api/status— JSON 状态
也可以在对话中直接说「给这个仓库生成 wiki」，由 dsh-wiki 技能接管流程。
配置要点¶
插件行 config（GUI 可改）示例：
- id: dsh-wiki
config:
wikiDirName: .dsh-wiki # 各仓库内 wiki 目录名
wikiRoots: [] # 额外扫描的绝对路径数组
生成侧另有四层合并：内置默认 → ~/.dsh/dsh-wiki/config.json → <仓库>/.dsh-wiki/config.json → --set k=v。预设含 compact / standard / deep / legacy，可调语言、页数、粒度、图表密度、引用档位（relaxed / strict）等。具体字段以仓库文档为准。
适用场景与注意¶
适合谁：希望在 DSH 工作流里把「读懂仓库」固化为可搜索、可离线打开的本地 wiki，且要求正文带来源行证据、数据不出网的团队或个人。
与云端 DeepWiki 的区别（README FAQ）：云端 DeepWiki 需把仓库交给托管服务；dsh-wiki 使用本机会话中的模型，产物为本地 HTML。
profile 限制：README 写明 headless / tui 下技能与 /wiki view|list 可用；/wiki generate 与本机站点路由依赖带 webServer 的 web 桌面宿主。
隐私边界：不上传仓库与 Git 对象内容；不发起生成/图表相关网络请求；宿主路由仅回环 Host、目录名须等于 wikiDirName、只读单文件服务。可选例外：可选用 git log --oneline -15 作摘要。
同类对照（摘自 README 对比表）：相对 dsh-openwiki 无需外挂 CLI；相对 dsh-plugin-codemap 具备分页叙事正文；相对 archify 除图外还有正文与自包含站点。维护状态以各上游仓库为准，dsh-wiki 在 README 中标注为活跃。
结尾¶
dsh-wiki 把「本地 agent 读库 → 带证据的分页 wiki → 单文件离线站点」收进一个 DSH bundle，分类上可归入记忆与文档沉淀。若要查插件摘要与分类，可打开 SkillHub 目录页；安装、命令与配置细节以 GitHub 仓库 README 为准。
