通用 Agent 知识库 sidleo/llm-wiki

llm-wiki —— 纯 OKF v0.2 Markdown 的通用 Agent 知识库

English · 简体中文

一个开源、通用、agent-first 的知识库项目：格式层严格遵守 Open Knowledge Format v0.2，运维层采用 Karpathy 的 llm-wiki 范式（ingest / query / lint + index / log），交付五种消费形态，共用同一核心库与同一份数据 bundle。

设计原则

1. 严格遵循 OKF v0.2——官方规范是格式层的唯一事实源；零自定义 frontmatter 字段，消费层零魔法特性。
2. 通用、与业务无关——不绑定任何领域或场景；同一份 bundle 任何 agent 都可读写。

特性

- 渐进披露——每轮会话注入工具引导与当前 bundle / 分类清单；先 wiki_list 看全貌，再检索、再深入。
- 真实交叉链接 + 自动 backlinks——概念用 Markdown 链接互相关联；读取一个概念时自动附带引用它的坑点与规则。
- 目录级规则（AGENTS.md）——每个目录可定义写入门控（哪些概念类型需 human 确认）与行为约定，向上遍历取最近、子目录覆盖父目录。
- 目录级提示词注入（APPEND_SYSTEM_PROMPT.md）——每个分类可自定义行为规则，五形态规则内容一致、改了即时生效：DSH 形态走「恒定 section + 运行时上下文快照」；pi 形态用 before_agent_start 钩子每回合现读并追加进本回合 system prompt；Codex 插件用 SessionStart / UserPromptSubmit hook 注入（内容未变不重复，规则改动后在下一轮刷新，compact 后重建）；MCP 形态在 initialize 的 instructions 里下发同一段内容（协议只在连接时下发一次，改动后重连或调 wiki rules）；skill/CLI 形态宿主没有注入钩子，改用 wiki rules（不带参数 = 载入全部规则全文）+ wiki get/create/update 响应自动附带目标目录规则（规则随数据到达，不必记得先载入）。详见 SPEC-EXTENSIONS.md。
- 生命周期——stale_after 过期、status: deprecated（概念级）与目录级批量停用、自动维护 index.md / log.md。
- 校验与体检——wiki_validate（OKF 合规）与 wiki_lint（断链、孤儿页、过期、缺 index）。
- 多目录（命名 bundle）——注册多个 wiki 目录为命名分支，可切换（会话级或全局持久）。
- 在线知识库（两种后端）——同一个 wiki_sync / wiki sync 入口，按 bundle 后端自动分派：
- 本地目录 + Git 远端：提交→拉取合并→推送，多机/多人协作；绝不 force push。
- 飞书云盘库：内容存在飞书云空间的文件夹里，就是一组原生 .md 文件（OKF 格式零损失），经 lark-cli 文件级增量读写；人在飞书里浏览/下载，agent 负责读与写。
两种后端同一套冲突规则：index.md 本地重生成、log.md 取并集（不阻塞）；概念 / AGENTS.md 两侧都改则停止同步并报清单，绝不自动覆盖。飞书后端永不删除两端文件（删除只报告）。
- 图形化配置（DSH Web GUI，DSH 0.1.7-rc.2 起；0.2.1-rc.2 已复核）——同一个页面注册进两处：设置 → llm-wiki，以及侧栏「插件」→ @sidleo3/dsh-wiki 页面。命名目录增删/改名/设默认、在线同步状态与一键同步/初始化/克隆、定时自动同步、体检（validate/lint 计数 + 重建 index）。运行参数属部署级配置（profile 的 cordis.patch.yml），页面刻意不提供编辑。

Wiki 目录结构（bundle）

一个知识库 = OKF v0.2 bundle：任意目录树，每个概念是一个 Markdown 文件。

my-wiki/
├── index.md # 保留文件：目录索引（渐进披露入口；根可带 okf_version） ├── log.md # 保留文件：时间线变更历史 ├── AGENTS.md # 保留文件：写入门控（「## 门控」节）与目录约定 ├── APPEND_SYSTEM_PROMPT.md # 保留文件（可选）：注入 agent prompt 的分类行为规则 ├── tables/ │ ├── orders.md # 概念：YAML frontmatter（type: Table）+ 正文 │ └── customers.md └── pitfalls/ └── join-inflation.md # type: Pitfall，交叉链接回 tables/orders.md

- 概念 = 一个 .md 文件：OKF 合规 frontmatter（type 必填）+ markdown 正文；概念 id = 相对 bundle 根的路径（如 tables/orders）。
- 交叉链接——用 label 或 [[wiki-link]] 引用其他概念；读取一个概念时自动附带 backlinks（引用它的概念/坑点）。
- 保留文件——任意层级只有 index.md / log.md / AGENTS.md / APPEND_SYSTEM_PROMPT.md 是特殊的；其余所有 .md 都是概念。
- 渐进披露——从注入的 bundle/分类清单 → wiki_list → wiki_search → wiki_get。

仓库结构

llm-wiki/
├── schema.md # 格式规范唯一事实源（OKF v0.2 对齐） ├── SPEC-EXTENSIONS.md # 对 OKF 的扩展声明（AGENTS.md / APPEND_SYSTEM_PROMPT.md 保留文件） ├── packages/ │ ├── core/ # 共享核心：解析/链接图/检索/校验/lint/index-log/规则解析 │ ├── dsh/ # DSH 插件 → npm @sidleo3/dsh-wiki │ ├── pi/ # pi 扩展 → npm @sidleo3/pi-wiki │ ├── mcp/ # MCP 服务端（stdio）→ npm @sidleo3/mcp-wiki │ ├── codex/ # Codex 插件（skill + 内置 MCP + hooks）→ npm @sidleo3/codex-wiki │ └── skill/ # skill 版 → SKILL.md + CLI wiki ├── examples/demo-bundle/ # 合成示例 bundle（Obsidian 可直接打开） ├── scripts/ # 开发辅助脚本 ├── tests/fixtures/ # 合成测试数据 └── obsidian/ # Obsidian 模板 / Dataview 查询示例

五种消费形态

| 形态 | 安装 | 能力 |
| DSH 插件 | dsh plugin --profile web add @sidleo3/dsh-wiki | 注入分层（恒定 section + 运行时上下文快照）+ wiki_ 工具 |
| pi 扩展 | pi install npm:@sidleo3/pi-wiki | wiki_ 工具 + prompt 引导 + before_agent_start 每回合注入分类规则 |
| MCP 服务端 | 见 packages/mcp/README.md（宿主 MCP 配置里写绝对 node 路径） | 同 14 个 wiki_ 工具；规则经 instructions + 响应附带下发，任意支持 MCP 的宿主可用 |
| Codex 插件 | codex plugin add codex@personal（见 packages/codex/README.md） | 内置 skill + 14 个 wiki_ MCP 工具 + SessionStart/UserPromptSubmit 规则注入 |
| skill + CLI | ~/.agents/skills/wiki/（见 packages/skill/INSTALL.md） | SKILL.md 引导 + wiki CLI（任意 agent 可用）；规则靠 wiki rules 与 get/create/update 响应附带 |

五形态读写同一份 bundle、行为一致——都复用 packages/core，无重复实现。

工具（14 个）

wiki_list · wiki_search · wiki_get（附 backlinks）· wiki_create · wiki_update · wiki_validate · wiki_lint · wiki_ingest · wiki_deprecate · wiki_rules · wiki_help · wiki_dirs · wiki_use · wiki_sync

在线知识库（Git 远端同步）

已有本地 bundle：挂远端并首推（--name 同时注册为命名目录） wiki sync init --remote git@host:group/wiki.git --name 团队库 --use

新机器：克隆并注册 wiki sync clone git@host:group/wiki.git ~/Documents/llm-wiki --name 团队库 --use

日常：先看状态，再同步（提交本地改动 → 拉取合并 → 推送） wiki sync status wiki sync --message "口径补充"

冲突策略：index.md（派生文件）同步时按目录树重新生成；log.md（追加式）按日期块取并集；概念 / AGENTS.md / APPEND_SYSTEM_PROMPT.md 属人工撰写内容，冲突时同步停止、报冲突清单并把工作区恢复到同步前（本地提交保留），人工解决后重跑即可。凭证交给 git（SSH agent / credential helper），本工具不保存 token，也绝不 force push。详见 wiki help sync。

飞书在线知识库（云盘文件夹 + 原生 .md）

把现有本地库复刻成一个飞书在线库（默认 dry-run，--apply 才执行；copy 不 move）
node scripts/migrate-to-feishu.mjs --from ~/Documents/llm-wiki --name 飞书库 --new-folder 团队知识库 --apply

或者：在「我的空间」新建文件夹并注册 wiki sync init --new-folder 团队知识库 --name 飞书库 --use 挂已有文件夹 / 另一台机器 wiki sync init --folder-token https://feishu.cn/drive/folder/fldcnXXXX --name 飞书库

日常 wiki sync status # 待推送 / 待拉取 / 两侧都改 / 远端已删 wiki sync # 推本地改动 + 拉远端改动（只传改动文件）

定时自动同步（开关/间隔/身份每台机器一份；定时器跑在 DSH 插件宿主进程内） wiki sync autosync status|on|off [--interval 5] [--identity auto|user|bot]

真删除（飞书后端）：v1 不同步删除，只删一侧会被下次同步复活；这条命令两侧一起删并清账本。默认预演。
wiki sync delete <路径...> # 预演 wiki sync delete <路径...> --apply # 执行

三方状态判定（本地缓存里的 .wiki-cloud.json 记录每文件的 fileToken、远端 modified_time、本地 mtime/size）：只有一侧变就单向传；两侧都变就停下来报冲突。拉取覆盖本地前会先备份到 .backup/<时间戳>/。依赖 lark-cli（lark-cli auth login，或用 scope 与文件夹权限齐备的 bot 身份）；详见 wiki help feishu。

身份自动选择：每次动作前读一次 lark-cli auth status 的身份态（绝不为了试探而读写远端）后挑身份——auto（默认，user ready 用 user，否则回退 bot）、或锁定的 user/bot（不可用即报错、不回退）。注意 bot 的权限来自应用且通常够不到私有的「我的空间」文件夹，所以 auto 实际多数时候落到 user。

删除（飞书后端）：v1 不同步删除——三方判定把「一侧有、另一侧无」当新增，所以只删一侧必被下次同步复活（本地删→拉回；飞书删→推回）。wiki sync delete（或 wiki_sync 的 action: delete）同时删两侧并清账本条目。两条红线不可协商：只删显式点名的路径（绝不按差异推断）、另一侧有未同步改动就拒删并报清单（不覆盖）。默认预演。内容只是被取代时优先用 status: deprecated。注意定时同步会扩大「误删被复活」的窗口。

定时自动同步（默认关闭）：开关/间隔/身份按机器存 ~/.agents/wiki-autosync.json，间隔默认 5 分钟（最小 1、最大 1440）。定时器在 DSH 插件宿主进程内（DSH 停则停；要 DSH 关闭也同步，改用系统计划任务调 wiki sync），且只驱动飞书后端——Git 远端同步涉及合并，保持手动。同一 bundle 不并发，失败只记录不停表，冲突照旧停下报告、绝不覆盖任一侧。

图形化配置（DSH Web GUI）

设置 → llm-wiki（或侧栏「插件」→ @sidleo3/dsh-wiki 页面；DSH 0.1.7 起同一页面注册进这两个 slot，slot 契约已在 0.2.1-rc.2 复核）：

| 区块 | 能改什么 | 落到哪 |
| 命名目录 | 增删/改名/设默认 | ~/.agents/wiki-registry.json（与 CLI/pi 共享，删除只摘注册不动数据） |
| 在线同步 | 按后端显示：Git（远端/分支/领先落后）或飞书（待推送/待拉取/冲突/文件夹链接）+ 同步/拉取/推送/初始化/克隆 | 走 core git.mjs / feishu.mjs，与 wiki_sync 同一实现 |
| 命名目录 | 新增类型可选「本地目录」或「飞书云盘库」（可一键在飞书新建文件夹并注册） | ~/.agents/wiki-registry.json（飞书条目为对象形态：kind/folderToken/cacheDir） |
| 定时自动同步 | 开关、间隔（默认 5 分钟）、飞书身份，附「立即同步一次」与上次结果 | ~/.agents/wiki-autosync.json（每台机器一份），由插件内定时器驱动 |
| 体检与索引 | validate/lint 计数与明细、重建 index | core validateBundle/lintBundle/refreshIndex |

（运行参数不在配置页里：数据目录、注入 section 名/order、各上限、缓存 TTL 都是部署级配置，改 profile 的 cordis.patch.yml。）

多目录（命名 bundle）

默认数据目录 ~/.agents/wiki；要管理多个 wiki 目录，用「命名 bundle」注册与切换：

- 注册表（跨五形态共用，默认 ~/.agents/wiki-registry.json，env WIKI_REGISTRY_FILE 覆盖）：

{ "bundles": { "工作": "/abs/path/a", "个人": "~/notes/wiki" }, "active": "工作" }

- DSH 插件也可在配置里声明式注册（与注册表合并、同名配置优先）：

- id: wiki-registry
config:
dataDirs:
工作: /abs/path/a 个人: ~/notes/wiki

- 切换——wiki_use <name> [global: true]：DSH 宿主默认会话级（按对话隔离，仅当前对话生效）；global: true 持久化为全局默认（写注册表 active，影响新会话与 CLI/pi/codex）。wiki_dirs 查看分支。CLI 用 wiki dirs / wiki use NAME [--global]，每条命令可 --wiki NAME 指定。
- 解析顺序（无显式 name）：注册表 active（若为已知名字）→ default（dataDir 兜底）。详见 wiki help bundle。

快速开始

1. 查看 demo bundle
node packages/skill/bin/wiki.mjs list --dataDir examples/demo-bundle

2. 校验 OKF 合规
node packages/skill/bin/wiki.mjs validate --dataDir examples/demo-bundle

3. 检索 + 读明细（backlinks 自动显示引用它的坑点/概念）
node packages/skill/bin/wiki.mjs search 销售额 --dataDir examples/demo-bundle
node packages/skill/bin/wiki.mjs get tables/orders --dataDir examples/demo-bundle

4. 用 Obsidian 打开 examples/demo-bundle 看 graph view 与 Dataview（见 obsidian/）

测试

node --test # 全量 214 项 —— 别用 tests/.test.mjs 通配：它会静默漏掉 -test.mjs 的 DSH 测试
node scripts/smoke-test.mjs # 36 项：core 工具链 + 注册表 + ingest/lint 端到端
node tests/dsh-mock-test.mjs # 35 项：DSH 插件（mock 宿主）工具注册 + 注入分层 + 门控 + 多目录 + 同步诊断
node --test tests/dsh-config-test.mjs # 14 项：配置页宿主半（/api/dsh-wiki/* 路由）
node --test tests/git-sync.test.mjs # 8 项：Git 远端同步（顺序写/并发 log/index 冲突/概念冲突/错误路径）
node --test tests/feishu-backend.test.mjs # 25 项：飞书云盘后端（三方差异/只推改动/冲突停止/log 并集/argv 安全黑名单）
node --test tests/dsh-client-bundle-test.mjs # 8 项：配置页产物契约（两个 slot）+ jsdom 渲染冒烟
node --test tests/dsh-020-contract-test.mjs # 9 项：DSH 0.2.0 契约离线固化（基线模块 / peer 门 / 两个 slot / 宿主半工具与路由）
(cd packages/pi && npm install --legacy-peer-deps && npm test) # 16 项：pi 扩展（mock pi）
(cd packages/mcp && npm install && npm test) # 17 项：MCP 形态（SDK stdio 客户端端到端 + 与 DSH 插件工具/输出对拍 + stdout 纯净）
(cd packages/codex && npm test) # 10 项：Codex 插件（manifest/hook + 零依赖 MCP + 与 MCP/DSH 工具契约对拍）
node --test tests/three-forms.test.mjs # 5 项：三形态读写同一 bundle 一致性
node --test tests/ref-abs-path.test.mjs # 19 项：概念引用带真实绝对路径（尖括号包裹）、id 语义未被污染、cwd 相对解析死链锁死
node --test tests/overview.test.mjs # 24 项：wiki_list 全量清单（每条标题都列出、不带绝对路径、不静默截断、不切断半行）
node --test tests/vendor-sync.test.mjs # 4 项：vendor-core 快照与 packages/core 逐字节一致（守「改 core 忘同步 vendor」的假绿）
^ 同时追加进 packages/{mcp,pi,codex} 的 test script：这些形态优先加载 vendor-core，快照落后就会静默跑旧逻辑 —— 闸门必须跑在它们跑的地方，否则形同虚设。

许可

MIT