00 · 全景
四层一图:一篇文章怎么变成可调用的知识
下面各节分头讲权责、布局、流水线与门禁;这一张先把数据怎么流说完。
窄屏可左右滑动查看完整图形
两条加工路,不是一条:剪藏走引擎批量编译,重要文章走对话式 ingest(先讨论再抽取)。两者落在不同领地、权限也不同——这是第 1 节三条红线的由来。
门禁挂在写入点上,不是挂在嘴上:引擎领地由 OKF 体检把关,LLM 领地由写集校验、决策队列、保鲜三道把关。都是脚本,不是提示词(第 4 节)。
调用层有一条回流箭头:查询产出不是聊完就散,有价值的写回 outputs/。这条回流才是「知识复利」的实现。
01 · 权责边界
三层架构:谁能写什么
系统不漂移的关键,是把「谁能改哪些文件」写成可版本化的 Schema(CLAUDE.md),而不是靠约定俗成。
第三层 · Schema(CLAUDE.md)系统「宪法」:规定各角色权责边界、目录规范与工作流,约束下面两层
↓ 约束
第一层 · Raw(raw/)剪藏 / PDF / 笔记导出
只读,唯一真相来源
第二层 · Wiki(_wiki/)summaries · concepts · entities —— 引擎领地,LLM 只读
outputs/ —— LLM 产出写这里
Raw ——编译(只读源,不回写)——▸ Wiki ——调用——▸ 人:选题 / 提问 / 写作 / 决策
红线一:_wiki/summaries|concepts|entities 是编译引擎的领地,LLM 只读;产出写到 outputs/。
红线二:原始来源只读不写;笔记类原始导出永不修改,只编译其增量目录。
红线三:处理完的 todo 移入 archive/,不回 clippings/——否则重复编译。
02 · 存储布局
双库:代码与内容分离
代码库不含任何个人内容。知识内容在另一个私有仓,经符号链接挂进同一个工作目录。
mind-kit/ —— 代码库
scripts/ tests/ docs/ prompts/ evaluation/ site/ ← 真实文件
_wiki material raw writing reports/… ← 全是软链 ↓
软链指向 ↓
mind-vault/ —— 你的内容库(私有)
_wiki/ material/ raw/ writing/ reports/ ← 个人内容本体
克隆代码库后不会有 _wiki/、material/、raw/ —— 这是设计如此,跑 scripts/init-vault.sh 建自己的。
提交个人内容一律走 scripts/vault.sh commit(唯一漏斗,带写集校验门禁);不要在代码库里 git add 个人目录。
03 · 主流程
编译流水线:一条命令走完
scripts/compile.sh 把七件事串成一条命令;更外层的 update-all.sh 还会串上日报、门户与文档站。
- sage-wiki compile来源 → summaries / concepts / entities
- build-index.py重建
_wiki/index.md 导航
- sage-wiki lint健检:矛盾 / 孤立页 / 缺失交叉引用 → 记账到
reports/lint/
- freshness.py保鲜复核:按半衰期列出「该复核」的页(只提示,不改)
- decision.py check决策队列状态机不变量校验
- build-wiki-site.py生成本地浏览站
browse/wiki/(含关系图)
- vault.sh commit产物提交到内容库 —— 此处过写集校验门禁
三条路,同一个脚本update-all.sh 可由 命令行 / 网页按钮 / 定时自启 三种方式触发,单一真相、不会各行其是。
04 · 抗腐化
四道机器:让它规模化不腐化
知识库越大越怕漂移与静默腐化。除理念外,系统落了四道确定性可执行的机制——不是提示词里的软约束,而是脚本、测试与门禁。
E1本地检索栈
BM25 + 中文 bigram 分词 + RRF 三通道融合 + 双语同义扩展。
秒级、不走 LLM;索引按输入指纹自动失效重建
E2评测与回归
检索 golden case(MRR / Top-1)+ 质量 required/forbidden token 断言。
基线只增不减;锁住「认知边界」而非只测召回
E3决策队列 + 保鲜
须先确认的动作走状态机;重要页按半衰期到点提示复核。
审批与执行分离;保鲜只提示不擅改
E4写集校验门禁
提交前对变更页跑确定性校验(frontmatter、引号化、保鲜字段、证据链)。
只校本次写集(不扫全库);坏页拦在入库前,带逃生舱
为什么是「机器」而不是「规范」系统宪法里写着一条原则:
「只有脚本/测试能确定性执行的规则才算硬门禁;提示词与文档条款只是尽力遵守的软规范。想让某条规范必须遵守,就为它写可执行检查,别指望文字自我执行。」
05 · 调用
查询:两条路
① 本地检索 · /api/search秒级,不走 LLM
BM25 + bigram + RRF + 同义扩展
适合「找页面」
② 引擎查询 · /api/query数十秒,走 LLM
综合多页 + 带来源引用
适合「要答案」
▾ 有价值的产出
回写 _wiki/outputs/ 并记一条 log让探索也复利 —— 别让洞见死在聊天记录里。本地服务 brain-server.py 只绑回环地址,提供门户页与这两个 API。
06 · 隐私
边界:什么永不上网
公开site/ 文档站(部署到公网)
scripts/ tests/ docs/ prompts/ evaluation/
私有 · 永不进代码库raw/ _wiki/ material/ writing/ 内容库
browse/ 本地浏览站(gitignore)
raw/private/ 冷存层,永不读写入库
可执行门禁防回流代码库有一道测试(test_no_personal_identifiers.py)挡住个人标识回流:用形状匹配(如 ou_ + 24 位 hex)而非字面值 —— 把真实标识写进测试文件,等于泄露仍在库里。
07 · 运行时
运行时:两端如何分工
前面各节讲的是数据怎么流;这一节讲谁在什么时候跑。
窄屏可左右滑动查看完整图形
编译只在服务器端跑:互斥锁只锁同机进程,跨机器没有锁。两端同时编译再各自 push,内容库必然冲突 —— 所以编辑端的定时任务只剩 pull。
文档站只在编辑端重建:site/*.html 是提交进仓的生成物,而不同机器的 pandoc 版本会渲染出不同 HTML,谁跑谁把代码仓弄脏。服务器端显式跳过,跳过理由如实打印,不会伪装成「缺 pandoc」。
失败要能被看见:七步里三步标了「核心」,缺工具时判失败而不是跳过。但整体退出码目前没有消费者 —— 这条缺口如实记在图里,还没修。
08 · 开发
纪律:用证据而非声称
开发遵循 Superpowers 四原则:测试先行 · 系统化优于拍脑袋 · 简单为第一目标 · 用证据而非声称。
脚本改动强制 pytest-first先写会失败的测试(RED)→ 实现到通过(GREEN)→ 重构
pre-push 钩子push 前跑全量 pytest,红则拦;CI 服务端兜底
收尾必验证真跑一遍留证据,而非「应该没问题」