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+。
开始使用
- 在 DSH Web 中注册或选择一个工作区。
- 创建一个绑定到该工作区的会话。
- 打开会话顶部的 Wiki 标签。
- 使用“新建页面”记录事实、决策和约束，或让 Agent 创建待审核提案。
- 添加工作区相对的来源文件，例如
src/services/auth.ts。 - 代码变化后点击“扫描过期”，检查哪些页面需要更新。
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 搜索、来源过期检测、提案审核、反向链接和路径逃逸防护。
No comments yet. Be the first to write one.