yu-xin-c / dsh-project-wiki

DSH Project Wiki

面向 DeepSeek Harness 的可审计、本地优先项目 Wiki。

DSH Project Wiki 把 Agent 在开发过程中获得的架构知识、设计决策、代码约束和排障结论沉淀为工作区内的 Markdown 页面。它不是隐藏的聊天记忆：被接受的知识可以阅读、编辑、审查、搜索和提交到 Git，来源文件发生变化时也会明确标记为待更新。

An auditable, workspace-local project Wiki for DeepSeek Harness, with a native Web view and review-gated Agent contributions.

为什么需要它

长时间使用 Coding Agent 时，真正有价值的上下文往往散落在会话里：模块边界、隐含约束、曾经失败的方案、关键文件和维护约定。新会话无法可靠继承这些信息，而把全部聊天记录重新塞进上下文既昂贵，也容易引入过期结论。

DSH Project Wiki 提供一层可控的项目记忆：

• 知识归属于工作区：每个已注册的 DSH workspace 拥有独立 Wiki。
• Markdown 是事实源：页面保存在仓库中，可以直接审查、备份和版本控制。
• Agent 先提案、再接受：模型生成的知识不会自动成为已确认事实。
• 结论可追溯到源码：页面可以记录工作区相对路径及其 SHA-256 指纹。
• 过期知识可见：来源文件变化或消失后，页面会显示为“待更新”。
• 索引可随时重建：SQLite FTS5 只负责检索，不承载唯一数据。

核心能力

能力	说明
原生 Web 界面	在 DSH 会话中增加 Wiki 标签，集中展示页面、提案、状态和正文
Markdown 编辑	创建、编辑和删除页面，支持 GFM 表格、列表、代码块等语法
全文检索	使用 SQLite FTS5 搜索标题、摘要、标签和正文
提案审核	Agent 提案与正式页面分开保存，用户可以在界面中接受或拒绝
来源指纹	保存页面时计算来源文件 SHA-256，并显示短指纹用于审查
过期扫描	比较已记录指纹和当前文件，标记变化或缺失的来源
知识图谱与双向链接	正文使用 [[page-slug]] 或 [[Page title]] 建立关系，自动计算反向链接并生成可交互图谱
修订记录	页面记录 revision、创建时间、更新时间及 Web/Agent 操作者
Agent 工具	根 Agent 可以搜索、读取、检查来源、创建提案和应用提案

工作方式

flowchart LR
  Session["DSH Session"] --> Registry["Workspace Registry"]
  Registry --> Service["Project Wiki Service"]
  Web["Wiki Web View"] -->|Loopback RPC| Service
  Agent["Root Agent"] -->|Wiki tools| Service
  Service --> Pages["Markdown pages"]
  Service --> Proposals["Review proposals"]
  Service --> Index["Rebuildable FTS5 index"]
  Service --> Sources["Workspace source fingerprints"]

每次 Web RPC 或 Agent 工具调用都会从活动 Session 重新取得 cwd，再通过 DSH WorkspaceRegistry 解析真实工作区。插件不会信任浏览器传入的目录，也不会让一个会话读取另一个工作区的 Wiki。

知识图谱

图谱视图把当前工作区已经接受的 Wiki 页面组织成一张可交互的有向图。它和全文检索互补：搜索适合直接找到某个结论，图谱适合观察模块之间的依赖、共同上下文和知识空白。

图结构直接从 Markdown 派生，不维护另一套不可见的图数据库：

• 节点：每个正式页面对应一个节点，标题用于显示，页面状态决定颜色。
• 有向边：页面正文中的 [[target]] 生成一条“当前页面 → 目标页面”的边。
• 目标解析：target 可以是页面 slug 或标题；匹配会进行 Unicode NFKC 规范化、去除首尾空格并忽略大小写。
• 未解析节点：链接目标尚不存在时，图中保留一个虚线空心节点，侧栏同时显示未解析数量。
• 去重：同一页面多次引用相同目标只生成一条关系，节点度数仍可用于视觉权重。
• 状态：绿色表示有效页面，琥珀色表示来源已变化，空心节点表示未解析链接；当前选中页面带蓝色描边。

图谱使用力导向布局自动组织节点。可以拖动节点、平移画布、滚轮缩放，也可以通过右上角按钮放大、缩小或重新适应画布；点击正式页面节点会回到页面视图并打开对应正文。图中不展示待审核提案，只有被用户接受的知识才会进入正式关系网。

对应的数据关系可以概括为：

WikiPage { id, slug, title, status, links[] }
WikiLink { sourcePageId -> targetPageId | unresolvedTarget }

安装

直接从 GitHub 安装

无需全局安装 DSH：

npx --yes @deepseek-ai/dsh@latest plugin --profile web add github:yu-xin-c/dsh-project-wiki
npx --yes @deepseek-ai/dsh@latest web

如果已经有全局 dsh 命令：

dsh plugin --profile web add github:yu-xin-c/dsh-project-wiki
dsh web

仓库包含预构建的 Host 和 Web bundle，因此 GitHub 安装不需要 pnpm allowBuilds。在需要可复现安装的环境中，建议固定 release tag 或 commit：

dsh plugin --profile web add github:yu-xin-c/dsh-project-wiki#<tag-or-commit>

安装本地 checkout

git clone https://github.com/yu-xin-c/dsh-project-wiki.git
cd dsh-project-wiki
pnpm install
pnpm check
dsh plugin --profile web add "$PWD"
dsh web

Node.js 要求为 22.19+ 或 24+。

开始使用

1. 在 DSH Web 中注册或选择一个工作区。
2. 创建一个绑定到该工作区的会话。
3. 打开会话顶部的 Wiki 标签。
4. 使用“新建页面”记录事实、决策和约束，或让 Agent 创建待审核提案。
5. 添加工作区相对的来源文件，例如 src/services/auth.ts。
6. 代码变化后点击“扫描过期”，检查哪些页面需要更新。

Wiki 必须依附于一个仍然存在的源 Session，并且 Session 的目录必须已注册为 DSH workspace。这样可以保证页面、来源和 Agent 工具始终处于同一个项目边界内。

Agent 工具

插件只把工具安装到 DSH 根 Agent，并绑定到该 Agent 的 Session 工作区。

工具	类型	用途
wiki_search	只读	搜索当前项目 Wiki，结果数量限制在 1-50
wiki_read	只读	按页面 ID 或 slug 读取正文、来源、修订和状态
wiki_backlinks	只读	查询链接到目标页面的其他页面
wiki_check_stale	只读	比较来源指纹，不修改已接受页面
wiki_propose	需批准	创建待审核 Wiki 提案，不覆盖正式页面
wiki_apply_proposal	需批准	接受提案并生成带新来源指纹的正式页面

wiki_propose 和 wiki_apply_proposal 会触发 DSH 人工批准流程。Web 中的保存、接受和拒绝是用户直接执行的显式操作。

数据布局

每个工作区默认使用以下目录：

.dsh/wiki/
├── pages/             # 已接受页面，Markdown + YAML frontmatter
├── proposals/         # 待审核提案，JSON
└── .index.sqlite      # 派生的 SQLite FTS5 全文索引

页面 frontmatter 保存 ID、slug、revision、标签、来源指纹、状态、时间和操作者；正文保持普通 Markdown。可以删除 .index.sqlite，插件会根据 pages/ 中的 Markdown 重新建立索引。

建议把 pages/ 纳入 Git。是否提交 proposals/ 和 .index.sqlite 可以按团队策略决定，通常不需要提交派生索引。

来源与过期检测

保存页面时，插件会对每个来源文件计算 SHA-256：

sources:
  - path: src/services/auth.ts
    sha256: 8a6f...e21c
status: current

扫描时若文件内容变化或文件不存在，页面状态变为 stale，并列出具体来源。扫描只提示知识可能过期，不会自动重写页面，也不会用新指纹掩盖旧结论。

来源路径必须：

• 使用工作区相对路径；
• 解析后仍位于当前工作区内；
• 指向普通文件；
• 单文件不超过 20 MiB。

安全边界

• Web API 仅通过 DSH loopback RPC 暴露。
• 每次调用都重新验证活动 Session 和已注册工作区。
• Wiki 目录必须是工作区内的相对目录。
• 来源路径不能通过 ..、绝对路径或符号链接逃出工作区。
• Agent 的持久化提案和提案接受操作需要人工批准。
• 正式 Markdown 页面与 Agent 提案分开存储。
• SQLite 索引是派生数据，不会取代可审查的 Markdown。
• 页面上限默认为 1000，可配置范围为 1-10000。

配置

安装 bundle 后会插入以下 Cordis 配置：

- id: dsh-project-wiki
  name: '@dsh-external/dsh-project-wiki'
  config:
    directory: .dsh/wiki
    maxPages: 1000

配置项	默认值	说明
directory	.dsh/wiki	工作区内的 Wiki 相对目录，不能指向工作区外部
maxPages	1000	单个工作区允许的最大正式页面数，范围 1-10000

用户可以在自己的 profile cordis.patch.yml 中按同一 entry ID 覆盖配置。DSH patch 会替换整段 config，因此覆盖时应同时写出所有需要保留的字段。

当前边界

• 这是项目级本地 Wiki，不提供云同步或跨工作区共享。
• 搜索目前是 FTS5 词法检索，不包含 embedding 或向量数据库。
• 插件检测来源变化，但不会自动判断新代码应该如何改写结论。
• 页面必须由 Web 用户显式保存，或由用户批准 Agent 提案后进入正式知识库。

这些限制是有意的：项目知识应该可见、可审查，并由人决定何时成为长期事实。

开发与验证

pnpm install
pnpm typecheck
pnpm test
pnpm build

也可以运行完整检查：

pnpm check

测试覆盖包契约、RPC 错误格式、Markdown 持久化、FTS 搜索、来源过期检测、提案审核、反向链接和路径逃逸防护。

License

MIT