@banana-peeljj12/dsh-docs

专门用于维护项目文档与 LikeC4 架构即代码的 DeepSeek Harness (DSH) 插件。提供 Docsify Wiki 自动治理、LikeC4 看板构建与语法校验、结构化文档读取与原子更新、坏链体检、ADR 脚手架以及 Web UI 控制台。

核心特性

1. Wiki 静态页面自动维护：
   • 自动扫描 Markdown 目录树并生成/同步规范的 _sidebar.md；
   • 保护开发者手工维护的特殊链接区块（<!-- custom-links-start -->）；
   • 内置基于 Node.js 的轻量本地实时预览 HTTP 服务器（支持 CORS / 自动端口避让）。
2. LikeC4 架构即代码构建与校验：
   • 优先探测项目本地 node_modules/.bin/likec4，无缝调度；
   • 语法格式与架构语义校验，提供清晰的文件、行号、列号结构化错误；
   • 一键构建交互式静态架构看板（生成纯静态 HTML/JS 产物）；
   • 自动将架构看板挂载至 Wiki 侧边栏导航。
3. 文档结构化读取与安全更新：
   • docs_read：按章节标题精准抽取段落、Frontmatter 元数据与大纲目录；
   • docs_update：支持全量覆盖、末尾追加与单章节替换，具备 Git 未提交修改防冲保护与 dry_run 差异对比，写入自动创建 .bak 备份。
4. 工程质量体检套件：
   • 死链与断图检测（docs_audit）：全量排查相对链接、图片路径与已删除文件；
   • 孤立文档扫描：发现未在目录树和侧边栏收录的遗留文档；
   • ADR 自动脚手架（docs_adr_create）：自动提取最大编号并递增（如 ADR-014-...），套用标准模板并自动挂载至侧边栏。
5. 双模路径配置：
   • 支持在工作区 .dsh/docs-config.json 中持久化配置 docsRoot 与 c4Root；
   • 每次调用均支持通过入参动态显式覆盖，支持多文档域管理。
6. DSH Web 文档阅读入口：
   • 会话顶部的「文档」按钮打开宽幅只读阅读浮层，无需先向 Agent 发消息；空会话在输入区提供互斥入口。
   • 按标题或相对路径筛选，阅读 Markdown、表格、代码块和项目内图片，支持文档链接、标题锚点和阅读历史。
   • 文档根沿用项目 .dsh/docs-config.json 的 docsPath，默认使用 docs/，不存在则使用项目根。Web 阅读仅限会话项目内，超出项目的配置根会被明确拒绝；不启动预览、不构建、不写文件。
   • 完整架构画布、编辑器和自动修复不在本次阅读入口范围，原有 Agent 工具仍然保留。

阅读入口的构建与加载

客户端源码位于 src/client.jsx；运行 npm run build:client 生成发布用 classic ModuleLoader bundle。宿主提供 React 与 Modal，Markdown/GFM 解析依赖内联，不能直接把 JSX 源文件交给宿主。

npm test 和 npm pack 会先重新构建客户端；npm run check:client 可检测生成产物是否过期。安装或通过 link 加载后，后端变更需要重载插件或重启宿主，前端需要刷新现有 GUI；没有确认构建 watcher 时不承诺热更新。入口必须在真实 GUI 中验收，不能以注册对象测试代替。

读取使用宿主 ctx.fs，目录、正文和图片请求绑定会话。默认最多扫描 1000 篇文档、12 层目录，正文上限 2 MiB，单张 PNG/JPEG/WebP/GIF 图片上限 10 MiB；超限和读取失败会明确提示。原始 HTML、危险协议和远程图片不会执行或自动加载。

DSH Agent Tools 清单

CIDI 管线（CI/CD + 文档集成）

仓库内置两条工作流，代码质量与文档/架构集成同时过关才允许发布：

本地等价的提交前检查：

npm ci
npm run ci        # = npm test && npm run pipeline
npm run pack:check

完整阶段说明、fixture 设计与发布约定见 docs/PIPELINE.md。

运行测试

cd E:/dsh_plugins/dsh-docs
npm test          # 构建客户端并执行回归测试（临时 fixture，无本机路径依赖）
npm run pipeline  # Wiki → ADR → 审计 → LikeC4 校验/构建 端到端管线

开源协议

MIT License