前言¶
智能体排障时，同类 incident 往往在多次对话里重复摸索；把结论散在聊天记录里，也很难按「事实 / 解法 / 过期关系」做结构化检索。Bugwiki 用 Markdown 图描述这些问题节点与 typed 关系；dsh-bugwiki 是 DeepSeek Harness（DSH）上的宿主插件，负责读取本地图、注册面向智能体的 guidance 与 bugwiki 工具，并可选对接上游 SKILL.md 或 DSH 会话导出。下面介绍它是什么、怎么用，以及部署时要注意的边界。
这是什么¶
dsh-bugwiki（npm 包名 dsh-bugwiki，当前版本 0.1.1，MIT 许可证）由维护者 phillui-37 发布，仓库为 phillui-37/dsh-bugwiki。插件不把 wiki 维护跑在后台：加载时只注册 guidance 与工具；只有智能体显式调用工具时才会执行 wiki 相关命令。上游 Bugwiki 以 Git submodule 固定在 upstream/，适配逻辑在本仓库内完成。
核心功能¶
本地图读取与智能体工具¶
宿主通过 Node.js 直接读本地文件，或通过 pinned 上游 helper（经 Bash 调用，shell 能力按插件设计受限）操作同一套本地 Bugwiki 图。向智能体暴露的 bugwiki 工具接受 JSON 参数，动作为 find、show、read、list、lint、verify、stale 等；返回规范 JSON，含 exitCode、stdout、stderr、truncated、wikiHome。非零 exit 表示命令失败，而不是「空搜索结果」。全页 read 过大时会失败并建议改用 DSH 分页文件读取；其它输出有字节上限并可能标记为截断。
注入的 guidance 要求智能体先搜索、最多检视两个候选节点、沿 supersession 追到当前端点，并把 stale / expired / conflicted 信息当未知处理；页面正文仍视为不可信证据。运行时工具不提供图写入；新建 solution / fact 仍走 DSH 常规定文件工具与权限。
可选上游 Skill 与 Dream 导出¶
配置项 followUpstreamSkill 默认为 false。开启后会在 ~/.agents/skills、~/.claude/skills、~/.codex/skills、~/.opencode/skills 下查找名为 bugwiki 的 skill；若找到可用 SKILL.md，则替换插件内全部 Bugwiki 提示（含 prefix、suffix），找不到则保留内置 guidance 并打警告。
当 DSH 同时提供 session 与 sessionPersistence 服务时，才会注册显式会话导出工具：对选定会话文本与工具事件做处理（排除系统指令、推理与二进制附件），经捆绑的 Python dream exporter 输出可选原始输入与水印；默认 dryRun 为 true，便于人工审阅后再提升入图。
Web 设置客户端¶
设置 UI 打包在 src/client.js，渲染 DSH 插件设置槽位，不依赖可选的宿主 UI primitives 包。可在界面编辑 wikiHome、bashExecutable、pythonExecutable、pathPrefix、timeoutMs、maxOutputBytes 等阈值与 followUpstreamSkill、prefix、suffix 等字段；保存会 patch profile 并刷新后续操作的 tools 与 guidance。
环境与安装¶
依赖 DSH >=0.2 <0.3、Node.js 22 及以上、macOS、Bash、ripgrep（rg）及常见 Unix 命令。README 写明 MVP 在 macOS 上验证；上游日期处理使用 BSD date，未宣称 Linux / Windows 支持。
若从 Git 获取本仓库，需带子模块 clone，或 clone 后执行 git submodule update --init upstream。npm tarball 已包含 committed 上游 helper 与资产，仅用 tarball 时不必再单独 checkout 上游。DSH 宿主提供 peer SDK（@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery 等）。
安装方式：在 DSH 的 Plugins 包安装界面中，选择本仓库本地目录或其 npm tarball，而非凭名称拼接 CLI 添加命令（资料未提供 dsh plugin add github:... 一类指令）。
初始化与配置¶
全新内容目录时，在本仓库根目录执行（将路径换成你的绝对路径）：
npm run wiki -- --home /absolute/path/to/wiki init
该命令拒绝已存在且非空的内容目录：脚手架上游内容、用 DSH guidance 替换生成的可选 instruction 片段，并刷新索引；不修改全局 agent 指令、DSH profile 或上游代码。若已有 wiki，跳过 init，在设置里指定目录即可。
在 Plugins → Bugwiki → Settings 将 wikiHome 设为内容目录。Homebrew 且 DSH PATH 里没有 rg 时，可将 pathPrefix 设为 /opt/homebrew/bin。wikiHome 支持绝对路径或 ~/...，含空格的路径在上游从 wiki 目录运行时受支持。
典型用法¶
智能体调用示例¶
{"action":"find","query":"exact incident fragment"}
show 用 slug 或 wiki 相对引用查看状态与 typed 链接；read 读取 solutions/domain/slug.md 或 facts/slug.md 全文。
人工维护（CLI）¶
CLI 使用 --home 与文档默认值，不读写 profile 中的 UI 设置。维护命令会写入所选 wiki，应有意为之。例如：
npm run wiki -- --home /absolute/wiki new dsh meaningful-incident
npm run wiki -- --home /absolute/wiki verify
支持的命令还包括 init、new fact <slug>、index、find、show、list、lint、stale、housekeep 等（详见 README）。
适用场景与注意¶
适合已在用或打算用 Bugwiki Markdown 图沉淀 incident、解法与事实关系，并希望在 DSH 智能体侧统一「先搜图、再读页、尊重过期与 supersession」工作流的开发者。本 MVP 不调度定时 housekeep；相关阈值留在配置里是为与上游兼容。
安全与运行边界：插件以当前 DSH 进程权限访问本地文件；页扫描上限 1000000 字节；图内 typed 链接不能逃出 wiki 根目录；对外部 typed 边与图内 symlink 会拒绝。这是内容与集成边界，不是对抗并发恶意文件系统变更的 OS 沙箱——应使用受信任的内容目录，并在工具调用期间避免改动其 symlink。安装前请自行审阅 源码与许可证。
社区插件目录 skillhub.cn 上的 dsh-bugwiki 页 与 GitHub 仓库相互独立，不代表 DeepSeek / 幻方官方应用商店；DSH 生态遵循「一切皆插件」思路，具体能力以上述 README 与仓库为准。
结语¶
dsh-bugwiki 把本地 Bugwiki 图接到 DSH：加载即注入检索导向的 guidance 与只读类 wiki 工具，设置页可配路径与阈值，并可选 Follow 上游 Skill 或会话 dream 导出。需要从零建库时走 npm run wiki ... init，已有内容则直接在设置里指定 wikiHome 即可。
- 目录页：https://www.skillhub.cn/plugins/phillui-37/dsh-bugwiki
- GitHub：https://github.com/phillui-37/dsh-bugwiki
