《第二大脑》个人知识库 · 产品需求文档(PRD)

一句话定位:一个由 LLM 持续编写与维护的、可复利的个人 Wiki 知识库 —— 把”每次提问都从零检索”的 RAG 模式,升级为”知识只编译一次、此后持续保鲜”的永久 Wiki 模式。

修订历史

版本权威性:本 .md 文件是 PRD 的唯一权威版本;同目录下的 .docx / .html 是由此导出的分发副本,每次修订 .md 后需重新导出,阅读以 .md 为准。

如何阅读本文档

本 PRD 面向”我自己按图施工”,因此在传统 PRD 结构(目标 / 用户 / 需求 / 指标 / 风险)之外,额外强化了可落地要素:目录结构、配置模板、脚本、逐阶段验收清单(见第 10 章与附录)。阅读顺序建议:

• 想先理解”为什么这么设计” → 读 §1–§2。
• 想直接开工 → 读 §6(数据模型)、§7(工作流)、§10(路线图与验收)、附录 A–F(可直接复制的模板)。
• 关心工具怎么选 → 读 §4.3–§4.4(能力→工具映射与选型),附录 G(选型对比)。

1. 概述与背景

1.1 问题陈述:为什么需要”第二大脑”

作为高强度的知识工作者,我的信息处理长期存在四个结构性痛点:

1. 知识不复利。 大多数 AI 用法是 RAG(检索增强生成):上传文件,提问时临时检索相关片段作答。每次提问都在”从零拼图”,读过的东西没有沉淀成资产,洞见散落在聊天记录里随对话消失。
2. 输入与产出脱节。 flomo 里多年的手写笔记、剪藏的文章、本地 PDF 各成孤岛;真正要写文章或做决策时,无法快速调用这些积累。
3. 整理即负担。 传统笔记法要求人来分类、打标签、建立链接,维护成本随规模上升,最终”整理知识库”本身变成一件永远做不完、也不产生价值的事。
4. 随规模腐化。 库越大,矛盾、重复、孤立页面越多,却没有机制去发现和修复,知识库逐渐失去可信度。

1.2 核心理念:Wiki 不是 RAG(Karpathy 方案)

本项目采用 Andrej Karpathy 提出的「LLM Wiki」范式,与主流 RAG 形成根本区别:

RAG:在查询时从原始文档里检索片段,临时拼答案,不留积累。 LLM Wiki:LLM 持续编写并维护一个永久性、结构化、互联的 Markdown 文件集合。每加入一个新来源,LLM 不是索引它,而是读它、提炼它、整合进已有 Wiki —— 更新实体页、修订摘要、标注矛盾。知识只需编译一次,此后持续保鲜。

其价值可以用一句话概括:“知识库是一个持续复利的制品(compounding artifact)。交叉引用已经建好,矛盾已经被标注,综述已经反映了你读过的一切。” 打个比方:Obsidian 是 IDE,LLM 是程序员,Wiki 是代码库。

调研佐证(来自 Karpathy 原文及行业分析):

• 透明可审计:全部是人类可读的 Markdown,每条结论都能回溯到具体来源,可被人核对或修改。
• 架构极简:无需向量数据库、无需 embedding 基础设施 —— “只有 markdown、全文检索和 grep”。
• 自愈:通过 LLM 的定期健检(lint)主动发现并修复矛盾与漂移,而非静态索引。
• 甜点区明确:在约 100–10,000 篇高信号文档(~40 万字量级)区间表现最佳,不引入检索噪声。这正好覆盖单人知识库的现实规模。

同时清醒认识其边界与代价(见 §8、§11):不适合百万级文档的场景;需要一定的 LLM 调用成本用于持续编译与健检;实现上需要一套自动化工具与纪律(Schema)来防止 LLM 越权或”漂移”。

1.3 方法论融合:CODE 与 PARA(Building a Second Brain)

Karpathy 方案解决”AI 如何维护知识”,Tiago Forte 的《Building a Second Brain》解决”人如何组织知识与产出”。两者在本项目中互补:

• CODE 流程(信息生命周期):Capture 捕获 → Organize 组织 → Distill 提炼 → Express 产出。本项目把 Capture/Organize/Distill 大量交给 LLM 自动完成,人聚焦在 Capture 的”选择”与 Express 的”产出”。
• PARA 组织法(按”可执行性”而非”主题”归档):Projects(有截止的项目)/ Areas(长期责任)/ Resources(未来可能有用的资源)/ Archives(归档)。本项目将其映射为 raw 来源分区与 Wiki 标签体系的设计依据。
• 渐进式总结(Progressive Summarization):与 Wiki 的”摘要页 → 实体页 → 综述”分层天然一致 —— 越常被调用的知识,被提炼得越精。
• 中间产物(Intermediate Packets):对应本项目的 material/(六类素材)与 _wiki/outputs/(查询产出),让每次写作/决策都不必从零开始。

1.4 产品定位与范围

产品定位:一个单人、本地优先、LLM 驱动、写作与决策双场景的个人知识库系统。它不是一个”更好的笔记软件”,而是一条”来源 → 编译 → 调用 → 复利”的知识流水线。

本期(v1)范围内:个人知识的摄入、编译、查询、健检、素材提取、写作回写六大能力,及其自动化与治理(Schema)。

本期明确不做(详见 §2.2):多人协作、云端 SaaS 化、移动端原生 App、公开发布/分享站点、非文本(音视频)来源的自动转写。

1.5 设计原则

1. 需求优先、工具可换:本文档以”能力”定义系统,具体工具是可替换的实现选项(§4.4 给出选型标准)。
2. 来源不可变,唯一真相:原始来源只读不写,任何时候可回溯核对。
3. LLM 干脏活,人做判断:摘要、交叉引用、归档、簿记交给 LLM;选题、探索、提好问题由人负责。
4. 任务驱动整理,而非为整理而整理:“先有写作/决策任务,再让 AI 从积累里挖宝”,绝不先花几周整理再开工。
5. 纪律高于自由:用 Schema(CLAUDE.md)明确工具与 LLM 的权责边界,防止越权与漂移。
6. 一切复利:有价值的查询分析要存回知识库,让探索和摄入一样持续复利。
7. 本地优先、可移植:数据以纯文本 Markdown 存放在本地,不锁定任何厂商,随时可迁移/备份/版本化。

1.6 名词表(速览,完整见附录 H)

2. 目标与成功指标

2.1 目标(Goals / Objectives)

2.2 非目标(Non-Goals / 明确不做)

明确划定边界,避免范围蔓延:

• 不做多人协作 / 团队知识库:v1 是纯单人系统。
• 不做云端 SaaS / 公网发布:不搭建对外分享站点或多端同步服务(本地 + 自选同步盘即可)。
• 不做移动端原生 App:以桌面(Obsidian)为主界面。
• 不自动处理音视频来源:播客、视频等需先人工转写为文本再进库。
• 不追求百万级文档规模:刻意运行在 Karpathy 方案的甜点区(≤ ~1 万篇高信号来源)。
• 不做”先整理后使用”的大而全归档:坚持任务驱动。
• 不替代人的判断:系统提供素材与综合,决策仍由人做。

2.3 成功指标(Success Metrics)

北极星指标:“调用率” —— 每周有多少次写作/决策实际从知识库里调用了素材或答案。知识库的价值在于被”用”,而非被”存”。

指标以”轻量可自查”为原则:大多可用 _wiki/log.md、Obsidian 图谱视图、Dataview 查询或简单脚本统计得到,不额外引入埋点系统。

3. 用户画像与使用场景

3.1 用户画像(单人多角色)

本系统只有一个用户 —— 我,但我在不同时刻扮演三种角色,系统需同时服务:

用户特征:技术背景(能安装 CLI、跑脚本、用 Git);已有存量资产(flomo 多年笔记、文章剪藏库、本地 PDF);重度使用 Claude / LLM;偏好本地、纯文本、低锁定;时间稀缺,厌恶”为整理而整理”。

3.2 核心使用场景(Scenarios)

场景 A:写作驱动(“从积累里挖宝”) > 我要写一篇关于「AI 对创作者经济的影响」的文章。我在侧栏用六类框架 prompt 让系统在整个知识库里搜集素材,几分钟后得到一份结构化素材库(我的金句、亲历复盘、外部权威、真实案例、框架、数据),直接开写;写完把新产生的金句和判断回写进库。

场景 B:决策驱动(五维查询) > 我在评估一个新方向。我问系统:“这个方向现在谁在做?最近有什么融资信号?有哪些工程陷阱和前车之鉴?”系统先读索引,再深入相关实体/概念页,给出带来源引用的综合答案,并把这次分析存回 _wiki/outputs/,下次直接复用。

场景 C:增量摄入(自动 + 深度) > 平时用 Web Clipper 剪藏的文章自动落地并被自动编译进 Wiki;遇到特别重要的文章,我标记为 todo,在侧栏和 AI 逐段讨论后做深度摄入,并按六类框架抽取素材。

场景 D:flomo 存量激活 > 我把 flomo 最新全量导出放进库,增量脚本自动比对出”新增笔记”,只对增量做编译与六类提取,多年笔记逐步被激活为可调用素材,而原始导出永远原样保留。

场景 E:定期健检 > 每月跑一次健检,系统列出:相互矛盾的页面、被新来源推翻的旧判断、无人链接的孤立页、被反复提及却没有独立页面的重要概念、以及”下一步值得深挖的问题”。我据此做一次维护。

3.3 用户故事(User Stories)

以”作为使用者,我希望……以便……“表述,均可追溯到 §5 的功能需求。

• US-01:作为使用者,我希望新剪藏的文章能自动进库并被编译成结构化 Wiki 页,以便我不必手动整理就能积累。(→ FR-ING、FR-CMP)
• US-02:作为使用者,我希望对重要文章能和 AI 深度讨论后再摄入,以便关键来源被充分提炼。(→ FR-ING-03)
• US-03:作为使用者,我希望提问时得到基于全库综合、且带来源引用的答案,以便我信任并核对它。(→ FR-QRY)
• US-04:作为使用者,我希望有价值的查询分析被自动存回库,以便探索也能复利。(→ FR-QRY-03)
• US-05:作为使用者,我希望写作前一键得到按六类组织的素材库,以便快速开写。(→ FR-MAT-01)
• US-06:作为使用者,我希望决策时能按五维检索,以便系统化地做判断。(→ FR-MAT-02)
• US-07:作为使用者,我希望flomo 存量只处理增量,以便不重复、不丢失、原件不被改。(→ FR-ING-04)
• US-08:作为使用者,我希望定期得到健检报告并可一键修复部分问题,以便知识库不腐化。(→ FR-LNT)
• US-09:作为使用者,我希望明确告诉 AI 哪些目录它不能碰,以便 Wiki 不被越权修改。(→ FR-SCH)
• US-10:作为使用者,我希望所有数据是本地纯文本且被 Git 版本化,以便随时回溯、备份、迁移。(→ NFR 可移植性/可靠性)

4. 系统架构与能力模型(需求优先、工具中立)

本章先用”能力”描述系统应该做什么(与工具无关),再给出推荐参考实现(四件套)与选型标准。这样即使未来更换某个工具,需求依然成立。

4.1 三层架构(逻辑架构,不依赖具体工具)

系统在逻辑上分为三层,权责清晰:

┌─────────────────────────────────────────────┐
│  第三层 Schema(CLAUDE.md)——"宪法/规范"      │
│  规定各角色权责边界、目录规范、工作流           │
└───────────────┬─────────────────────────────┘
                │ 约束
        ┌───────▼────────┐        读       ┌──────────────┐
        │  第二层 Wiki    │◄───────────────│  第一层 Raw   │
        │ 摘要/实体/概念/ │   编译(只读源)  │  文章/笔记/   │
        │ 综述/查询产出   │─────────────►  │  PDF/剪藏     │
        └───────┬────────┘   (不回写源)    └──────────────┘
                │ 人只读、导航、调用
        ┌───────▼────────┐
        │      人         │  选题 / 探索 / 提问 / 写作 / 决策
        └────────────────┘

4.2 能力域(Capability Domains)—— 系统必须具备的六大能力 + 两项支撑

功能需求(§5)围绕以下能力域组织。每个能力域是”与工具无关”的需求单元。

4.3 参考实现:能力 → 工具映射(四件套)

以下为推荐参考实现。它满足全部能力需求,且本地、低成本、低锁定。具体工具可按 §4.4 标准替换。

关键 UX 判断:Claudian 是这套方案的体验核心 —— 把”打开终端→输命令→切回 Obsidian”缩短为”打开 Obsidian 侧栏”。这决定了日常使用是否顺手,是选型时的高权重项。

4.4 选型标准与备选方案(工具可换的判据)

由于本 PRD 采用”需求优先、工具可换”,这里给出替换任一组件时必须满足的硬性标准,以及主流备选(详细对比见附录 G)。

通用硬标准(任何实现都必须满足)

1. 本地优先 / 纯文本:数据以 Markdown 存于本地,可被 Git 版本化,不锁定厂商。
2. LLM 可编程访问:LLM 能读来源、能按规范读写指定目录(最好经 MCP 或 CLI)。
3. 权责可约束:能通过配置(Schema)限定 LLM 只读/可写的范围。
4. 增量与幂等:重复运行不产生重复页;只处理新增/变化。
5. 配置语义明确:sources 显式声明的目录必须优先于其父目录的 ignore 匹配(本方案依赖 ignore: raw/flomo + sources: raw/flomo/delta 的组合;若引擎按 ignore 优先解析,flomo 增量管线会静默失效——验收见 §10.2)。
6. 可观测:每次操作可追溯(日志 + 版本记录)。

分组件备选

结论:v1 直接采用四件套作为参考实现开工;本节标准用于未来任一组件出现更优替代时,快速判断是否可平滑替换。

5. 功能需求(Functional Requirements)

说明:需求以”系统应……“表述,工具中立;每条含优先级(P0=MVP 必备 / P1=重要 / P2=增强)与验收标准。ID 前缀对应 §4.2 能力域。

5.1 摄入 Ingest(C1)

5.2 编译与 Wiki 维护 Compile(C2)

5.3 查询与综合 Query(C3)

5.4 健检 Lint(C4)

5.5 素材与双轨框架 Material(C5)

5.6 写作与回写 Express(C6)

5.7 治理与 Schema(S1)

5.8 自动化与调度(S2)

5.9 评测与回归 Evaluation(S3,2026-07 新增能力域)

golden-case 评测体系,已全部落地并接入 pytest → pre-push → CI。

5.10 需求优先级汇总(MVP 边界)

P0(MVP,第 1–2 周必须跑通):FR-ING-01/02/03/04/06、FR-CMP-01/02/03/04、FR-QRY-01/02/03、FR-LNT-01/02、FR-MAT-01/02、FR-WRT-01/03、FR-SCH-01/02/03、FR-AUT-01/02。

P1(第 3 周起完善):一源多页、按任务分模型、编译后钩子、忽略清单、五维检索、概念缺页与部分自动修复、数据缺口与新问题建议、来源偏好加权、主题素材库、写作中查询与产出存档、工作流内置与 Schema 进化、周期节奏与版本化、工作日志(日报/周报)。

2026-07 新增:已落地 —— FR-EVA-01/02/03(评测基线,接入 CI)、FR-AUT-07(浏览站新鲜度)、FR-EVA-04(摄入即沉淀,约定);已落地 —— FR-QRY-06(检索栈升级:searchlib + /api/search,难基线 3/6→6/6);已落地 —— FR-SCH-06(决策队列:decision.py 状态机 + 待确认看板);已落地 —— FR-LNT-07(轻量保鲜)、写集校验 P1-4(validate_write_set.py + vault.sh 提交门禁);规划(P1)—— FR-ING-08(附件入箱脚本化;宪法条款已生效)。

P2(增强,按需):去重提示、混合检索权重、联网补充、框架沉淀、健检记账、图片本地化。

6. 数据模型与信息架构

6.1 Vault 目录结构(唯一物理约定)

整个系统的”数据库”就是一个本地 Markdown 目录树(Obsidian Vault)。这是所有工具协作的物理约定。

Obsidian Vault/
├── config.yaml            ← 编译引擎配置(sage-wiki init --vault 生成)
├── .mcp.json              ← 编译引擎 MCP 接入 Claudian / Claude Code
├── CLAUDE.md              ← Schema:各角色权责边界与工作流(系统"宪法")
│
├── raw/                   ← 原始来源(LLM 只读不写)
│   ├── clippings/         ← Web Clipper 自动落地;编译引擎 watch 自动编译
│   ├── todo/              ← 待深度处理;不在 watch 范围内
│   ├── archive/           ← 已处理存档(两类来源都往这里放);不再编译
│   ├── flomo/             ← flomo 导出(原始保留)
│   │   ├── 2026-03-15/    ← 某次全量导出(不直接编译)
│   │   └── delta/         ← 增量脚本生成的差量文件(仅此被编译)
│   ├── pdfs/              ← 本地 PDF
│   └── assets/            ← 图片等本地附件
│
├── _wiki/                 ← 编译输出(编译引擎/LLM 全权维护)
│   ├── index.md           ← 内容导航目录(页面 + 单行摘要 + 来源数)
│   ├── log.md             ← 时序日志(只追加)
│   ├── concepts/          ← 概念页
│   ├── entities/          ← 实体页(人 / 公司 / 产品 / 模型)
│   ├── summaries/         ← 来源摘要页
│   └── outputs/           ← Query 产出与深度摄入摘要(分析、比较表、摘要页)——LLM 可写
│
├── material/              ← 六类写作素材(LLM 生成)
│   ├── quotes/            ← ① 原创金句
│   ├── stories/           ← ② 亲身经历与决策复盘
│   ├── references/        ← ③ 外部权威与市场信号
│   ├── cases/             ← ④ 真实案例(成功与失败)
│   ├── frameworks/        ← ⑤ 框架与心智模型
│   └── data/              ← ⑥ 数据、研究与趋势
│
├── writing/              ← 写作产出存档
├── reports/              ← 工作日志:daily/ 日报 + weekly/ 周报(脚本自动盘点,见 §7.7)
├── scripts/             ← 自动化脚本(见附录 E)
└── .obsidian/           ← Obsidian 配置(编译引擎忽略)

6.2 三个流转目录的分工(clippings / todo / archive)

⚠ 关键坑位:处理完的 todo 文件要移入 archive/ 而不是 clippings/。若移回 clippings/,编译引擎会当成新文件再次编译,产生重复的 Wiki 条目。直接进 archive/ 可完全规避。

6.3 页面类型与 Frontmatter 规范

每个 Wiki/来源页建议带 YAML frontmatter,便于 Dataview 动态检索与五维标签。

通用 frontmatter 模板

---
title: 页面标题
type: summary | entity | concept | output | note   # 页面类型
source: 来源标识(URL / 文件名 / flomo-export)
date: 2026-07-13
tags: [ai, 五维标签, 主题标签]
dimension: [市场与竞争, 技术判断, 产品与用户, 人与组织, 框架与心智模型]  # 决策轨五维,可多选
status: draft | stable
links: 2            # 入链数(可由脚本/Dataview 计算)
---

页面类型定义

6.4 标签体系(双轨)

• 写作轨(六类):quote / story / reference / case / framework / data —— 对应 material/ 子目录,用于快速调用可嵌入文章的素材。
• 决策轨(五维):市场与竞争 / 技术判断 / 产品与用户 / 人与组织 / 框架与心智模型 —— 作为 Wiki 页 dimension 字段与标签,用于产品决策时的系统化检索。

两套框架互不干扰:写作前用六类框架提取素材;决策时用五维框架查询。CLAUDE.md 同时定义两套,并说明何时用哪套。

6.5 两个特殊导航文件

log.md 示例

## [2026-04-08] ingest ｜ 《GPT-4o 技术报告》
## [2026-04-09] query ｜ AI 对创作者经济的影响有哪些实证研究?
## [2026-04-10] lint ｜ 第一次全库健检,发现 12 个孤立页面

7. 核心工作流

7.1 Ingest 工作流(针对 raw/todo/ 的深度处理)

1. 读取来源 → 与人讨论关键要点(不跳过这步)
2. 在 _wiki/outputs/ 写简要摘要页(不写 summaries/,那是编译引擎的领地)
3. 按六类框架抽取素材 → 存入 material/ 对应子目录
4. 在 _wiki/log.md 追加:## [日期] ingest ｜ 标题
5. 提示人可将该文件移入 raw/archive/

自动来源(raw/clippings/)则无需人工:落地 → watch 触发编译 → 更新 _wiki/ 与 index.md → 归档脚本移入 archive。

7.2 Query 工作流

1. 先读 _wiki/index.md 找相关页
2. 深入相关页 → 综合答案 → 附 Wiki 内链接 / 来源引用
3. 有价值的分析存入 _wiki/outputs/,并在 log.md 追加

7.3 Lint 工作流(定期)

检查项:
- 页面间矛盾 / 被新来源推翻的旧声明
- 孤立页面(有内容但无入链)/ 缺失的交叉引用
- 被多处提及却无独立页面的重要概念
- 可通过联网补充的数据缺口
- 建议下一步值得深挖的问题与来源
可选:对安全项(补链接等)执行自动修复,变更进入 Git

7.4 flomo 增量(delta)工作流

1. 把 flomo 最新全量导出放入 raw/flomo/<日期>/(原样保留)
2. 运行增量脚本:比对指纹 → 仅新增笔记 → 生成 raw/flomo/delta/delta-<日期-时分秒>.md
   (文件名带时间到秒,同日多次运行互不覆盖)
3. 编译引擎编译 delta(不碰原始导出)
4. 在侧栏用六类提取 prompt 处理 delta → 写入 material/
   偏好:重点①原创金句 ②自我反思与复盘 ⑤框架;弱化③外部引用 ⑥数据

7.5 写作驱动的使用节奏(先任务,再挖宝)

“先有任务框架,再让 AI 帮你从积累里挖宝。知识库不是用来整理的,是用来调用的。”

7.6 周期节奏(每周 / 每月)

每周

• 周一:检查 raw/clippings/ 是否积压 → 运行编译更新 Wiki → 运行归档脚本。
• 周三:把上周标记 todo 的文章逐篇做深度摄入 → 处理完移入 archive/。
• 周五:如有新 flomo 导出 → 运行增量脚本 → 六类提取处理 delta → 运行健检。
• 亦可开启 watch 模式(compile --watch)让 clippings 处理完全自动化。

每月

• 深度健检一次:矛盾 / 被推翻的旧声明 / 孤立页 / 缺页概念 / 数据缺口 / 下一步选题。
• 用图谱视图观察 Wiki 连接质量的成长。

7.7 工作日志(日报 / 周报)

持续记录在库上做过的工作,并方便合成周报。报告存 reports/(daily/ 与 weekly/),不参与编译。

日报(每日,可 cron):
1. python3 scripts/daily-report.py           # 默认盘点“昨天”
   自动盘点:git 提交(作者日期) + _wiki/log.md 条目 + 当天 flomo 增量
   每条结论挂 sha / log 条目,可回溯;生成 reports/daily/YYYY-MM-DD.md
2. 在日报“手记”区补写反思 / 决策复盘 / 库外工作(可由 LLM 填)
   —— 该区在 <!-- 手记开始 -->…<!-- 手记结束 --> 之间,重生成时原样保留

周报(每周):
3. python3 scripts/weekly-report.py          # 默认上一个完整 ISO 周
   聚合该周日报:汇总数字 + 每日要点(缺日报会标注) + 分类小结 + 手记汇编
4. 在周报“周度综述”区让 LLM 读本周日报写叙事(主线 / 进展 / 问题 / 下步)
   —— 同样在标记之间,重生成保留

设计要点:机械骨架(脚本自动盘点,准确、可 cron、零 API 成本)+ 叙述层(手记/综述由人或 LLM 补写并被保留)。呼应 §1.5 原则”LLM 干脏活、人做判断”与 Fable 级模型”进度断言须对齐工具结果”的取向——报告里每条自动结论都可回溯到 git 或 log。

8. 非功能需求(Non-Functional Requirements)

8.1 成本模型(参考)

• 分层模型策略:摘要/抽取/健检(高频)→ 小模型;写 Wiki 文章、复杂查询(低频、高价值)→ 强模型。
• 忽略清单:archive/、material/、writing/、scripts/、.obsidian/ 等不发送给 API,直接降低调用量。
• 增量优先:只编译新增/变化来源,避免全库重复计算。
• 规模化原则(2026-07 新增,借鉴同类项目实践):库到数千页后,不把全库检查耦合进每次日常操作——写入侧只对本次变更范围负责(写集校验、增量索引);历史漂移由定时健检全量发现、只报告不自动修;索引记录逐文件输入哈希,使”新鲜度”可按文件粒度断言。落地记录(2026-07-23):写入侧 validate_write_set.py 已接入 vault.sh 提交门禁;全库侧 lint 已含保鲜与决策队列检查。
• 预算护栏:设定月度上限;若接近上限,优先保留 query/write,降低自动 lint 频率。

9. 权责边界与治理(RACI)

系统的稳定运行取决于明确的权责边界——这是 CLAUDE.md(Schema)的核心职责,防止 LLM 越权或”漂移”。

R=负责执行,A=最终问责。核心红线:LLM 绝不直接改写编译引擎管辖的 summaries/、concepts/、entities/(只能读,产出写到 outputs/)。

10. 分阶段路线图与验收清单

三阶段渐进落地。每阶段附可勾选的验收清单(Definition of Done),便于自查。

10.1 第一周:搭骨架

任务

1. 安装运行环境(Node.js / Go / Git)。
2. 安装编译引擎(sage-wiki)、LLM CLI(Claude Code)、主界面插件(Claudian,建议 BRAT 方式自动更新)。
3. 在 Vault 根目录初始化编译引擎(sage-wiki init --vault),运行 doctor 验证 API 连接。
4. 编辑 config.yaml:配置来源目录、ignore 列表、按任务分模型(附录 B)。
5. 创建 .mcp.json 接入 MCP(附录 D);创建 CLAUDE.md(附录 C)。
6. 建立 raw/ 目录结构,将文章库复制入 raw/clippings/,flomo 最新导出放入 raw/flomo/。
7. 安装 Obsidian 插件:Web Clipper、Templater、Dataview、BRAT;配置附件目录 raw/assets/。
8. git init + .gitignore(排除密钥/缓存)+ 首次 commit。必须在首次编译前完成:config.yaml 开启了 auto_commit,归档脚本也依赖 git 记录判断哪些文件已编译。

✅ 验收清单(第一周)

• sage-wiki doctor 通过,API 连接正常。
• config.yaml 的 sources / ignore / models 均已按需配置。
• CLAUDE.md 就位,权责边界清晰(§9)。
• .mcp.json 就位,Claudian 侧栏能调用编译引擎。
• raw/ 目录结构完整;文章库与 flomo 导出已放入。
• Obsidian 四个插件启用;Web Clipper 能把文章剪藏进 raw/clippings/。
• Git 初始化并完成首次 commit;密钥不在版本库。

10.2 第二周:跑通主流程

任务

9. 运行首次编译,浏览生成质量(TUI / 图谱)。
10. 运行 flomo 增量脚本,检查 raw/flomo/delta/ 的 delta 文件。
11. 在侧栏用六类提取 prompt 处理 flomo delta → material/。
12. 找一个真实写作任务,完整走一遍:素材提取 → 写作 → 产出回写。
13. 从 raw/todo/ 挑一篇重要文章做深度对话式摄入。
14. 运行第一次健检,查看报告。

✅ 验收清单(第二周)

• 首次编译成功,_wiki/ 生成摘要/实体/概念页且 index.md 更新。
• flomo 增量脚本只生成”新增”delta,原始导出未被修改。
• raw/flomo/delta/ 的 delta 文件被编译进 _wiki/(验证引擎满足 §4.4 硬标准 5:sources 优先于父目录 ignore;若未编译,flomo 管线配置需调整)。
• 六类提取把素材写入 material/ 对应子目录。
• 完整跑通一次”写作前→写作中→写作后回写”闭环。
• 完成一次深度摄入:outputs/ 摘要 + material/ 素材 + log.md 记录。
• 健检产出报告(至少含孤立页/矛盾/建议)。
• 编译后自动 commit 生效(auto_commit),归档脚本能正确归档已编译剪藏。

10.3 第三周起:建立节奏

任务

15. 固定每周 Ingest 节奏(或开启 --watch 自动化 clippings)。
16. 每次新 flomo 导出 → 增量脚本 + 六类提取。
17. 每次写作前用六类框架调用 Wiki,写作后产出回写。
18. 根据使用反馈持续迭代 CLAUDE.md(最值得投入时间之处)。
19. 每月深度健检;用图谱视图观察连接质量成长。

✅ 验收清单(进入稳态)

• 每周节奏已固化(周一编译+归档 / 周三深度摄入 / 周五 flomo+健检),或 watch 已开启。
• 北极星”调用率”达标(≥ 5 次/周)。
• 查询产出回写率 ≥ 50%。
• CLAUDE.md 至少迭代过 1 次并记录在 Git。
• 完成一次月度深度健检,问题修复率 ≥ 80%。

10.4 里程碑

11. 风险与避坑

12. 开放问题(Open Questions)

以下问题在施工中边做边定,不阻塞开工:

1. 同步与多端:是否叠加加密同步盘或私有 Git 远端做跨设备访问?(v1 可先纯本地)
2. flomo 切分粒度:flomo 笔记以何种分隔符切分为”一条”最稳?(增量脚本目前按行首 - 切段、## 视为结构标题,需按实际导出格式微调;若导出中每条 memo 以时间戳标题行开头,可改为锚定时间戳正则切分,能同时消除头部元信息与 memo 内部 bullet 被误切的问题)
3. PDF 处理深度:本地 PDF 是否需要 OCR / 表格抽取?学术类 PDF 的图表如何进库?
4. 健检频率:月度是否足够?高摄入期是否需要双周健检?
5. 模型版本策略:随模型迭代,config.yaml 的分层模型如何定期复评性价比?
6. 素材去重:六类素材长期追加,是否需要定期去重/合并 prompt?
7. 图谱可视化利用:除观察外,是否用图谱指标(如中心度)驱动”下一步深挖”选题?

13. 附录

附录 A:目录结构速查

见 §6.1。核心记忆点:raw/(只读来源)· _wiki/(编译引擎领地;LLM 对 summaries/concepts/entities 只读、可写 outputs)· material/(六类素材,LLM 全权)· writing/(成稿,人主导)· scripts/(自动化)· 根目录三件套 config.yaml / .mcp.json / CLAUDE.md。

附录 B:config.yaml 模板(编译引擎)

本模板与仓库根目录的 config.yaml 保持一致(漂移时以仓库文件为准);全部使用 vault 内相对路径,无需按机器修改。当前后端为 GLM(OpenAI 兼容编码端点),可用 scripts/sage-backend.sh kimi 一键切 Kimi;GLM_API_KEY / KIMI_API_KEY 用环境变量注入,不写进任何文件。

version: 1
project: my-second-brain
description: "我的第二大脑 — AI/科技知识库"

sources:
  - path: raw/clippings      # Web Clip 和文章库(自动 watch)
    type: auto
    watch: true
  - path: raw/flomo/delta    # flomo 增量文件(watch)
    type: auto
    watch: true
  - path: raw/pdfs           # 本地 PDF(不 watch)
    type: auto
    watch: false

# 忽略目录:不发送给 API
ignore:
  - raw/archive              # 已处理存档,不重复编译
  - raw/todo                 # 手动处理,不自动触发
  - raw/flomo                # 原始导出;delta/ 子目录已在 sources 显式声明,
                             # sources 优先于 ignore(引擎须满足 PRD §4.4 硬标准 5)
  - raw/assets               # 图片等附件,不参与文本编译
  - material                 # 素材库
  - writing                  # 写作产出
  - reports                  # 工作日志(日报/周报),不是知识来源
  - docs                     # PRD 等设计文档,不是知识来源
  - site                     # 文档站静态产物,不是知识来源
  - scripts                  # 脚本目录
  - .obsidian
  - .claudian
  - .claude

output: _wiki

api:
  provider: openai-compatible
  base_url: https://open.bigmodel.cn/api/coding/paas/v4   # GLM 编码端点(切 Kimi:api.kimi.com/coding/v1)
  api_key: ${GLM_API_KEY}                                 # 环境变量注入,不入库;Kimi 用 ${KIMI_API_KEY}
  extra_params:
    thinking:
      type: disabled                                      # 关 GLM-4.5 思维链:CoT 会吃爆 token 预算(finish_reason=length)

# 模型:当前全部用 GLM 的 glm-4.5-flash(单一模型,不分层)。切后端用 scripts/sage-backend.sh。
# (模型版本随迭代定期复评,见 PRD §12 问题 5)
models:
  summarize: glm-4.5-flash
  extract:   glm-4.5-flash
  write:     glm-4.5-flash
  lint:      glm-4.5-flash
  query:     glm-4.5-flash

compiler:
  max_parallel: 2                  # GLM 限流较紧(HTTP 429 code 1302);4 并发会部分写入失败,降到 2
  debounce_seconds: 2
  summary_max_tokens: 1500
  extract_batch_size: 1            # 概念抽取按单摘要小批(叠加引擎 120s 硬超时,大批必败)
  extract_max_tokens: 8000         # flash 是推理模型,CoT 也计入,给足避免 length 截断
  article_max_tokens: 3000
  auto_commit: false               # 拆库后关:个人目录已 gitignore(软链 mind-vault),收尾提交走 scripts/vault.sh
  auto_lint: true                  # 编译后自动 lint

search:
  hybrid_weight_bm25: 0.7
  hybrid_weight_vector: 0.3

附录 C:CLAUDE.md 模板(Schema —— 系统”宪法”)

# CLAUDE.md — 第二大脑 Schema

## 工具权责边界(最重要)
- 编译引擎(sage-wiki)全权负责:_wiki/ 下的 summaries/ concepts/ entities/
  → 你(LLM)不要直接创建或修改这些文件
  → 你可以读取它们用于 Query,可以在 _wiki/outputs/ 创建分析报告
- 你(LLM)全权负责:material/ 目录
- 你(LLM)可写 writing/ 目录,但以用户为主导(存放用户成稿)
- 共同维护:_wiki/index.md 和 _wiki/log.md(你可以追加,不要删除)

## 目录结构
raw/clippings/ → 自动编译(不需要你处理)
raw/todo/      → 等待你做深度对话式 ingest 的文章
raw/archive/   → 已处理存档,不要碰
raw/flomo/     → flomo 原始导出(不要修改),delta/ 子目录是增量文件
_wiki/         → 编译引擎领地,你只读不写(outputs/ 除外)
material/      → 你的领地,按六类框架存放素材

## Ingest 工作流(针对 raw/todo/)
1. 读取文章,与用户讨论关键要点(不要跳过这步)
2. 在 _wiki/outputs/ 写简要摘要页(不要写到 summaries/)
3. 按六类框架提取素材存入 material/ 对应子目录
4. 在 _wiki/log.md 追加:## [日期] ingest ｜ 文章标题
5. 告知用户可把文件移入 raw/archive/

## Query 工作流
1. 先读 _wiki/index.md 找相关页面
2. 深入相关页面,综合答案,附 Wiki 内链接
3. 有价值的分析存入 _wiki/outputs/,在 log.md 追加

## flomo 处理偏好(raw/flomo/delta/)
- 重点提取:① 原创金句 ② 自我反思与决策复盘 ⑤ 框架与心智模型
- 弱化权重:③ 外部引用 ⑥ 数据(除非 flomo 笔记本身包含)

## 两套框架何时用
- 写作任务 → 六类素材框架(material/)
- 产品/竞品/融资/招聘决策 → 五维工作框架(_wiki/ 五维标签检索)

## Lint 检查项
- 页面间矛盾 / 被新来源推翻的旧声明
- 孤立页面(无入链)/ 缺失交叉引用
- 重要概念被多处提及但没有独立页面
- 可联网补充的数据缺口 / 下一步值得深挖的问题

附录 D:.mcp.json 模板(MCP 接入)

{
  "mcpServers": {
    "sage-wiki": {
      "command": "sage-wiki",
      "args": ["serve", "--project", "."]
    }
  }
}

使用相对路径 .:Claude Code / Claudian 从项目根目录启动 MCP server,工作目录即 vault 根,换机器、换路径无需修改(硬编码绝对路径是踩过的坑)。若你的客户端不以 vault 为工作目录启动,再改为绝对路径。

附录 E:自动化脚本清单

以仓库为准:脚本的权威版本是仓库 scripts/ 目录下的实际文件,本附录只描述设计要点,不再内嵌代码副本(内嵌副本会随脚本迭代而漂移)。

E.1 scripts/auto-archive.sh —— 在 sage-wiki compile 完成后运行,把 clippings/ 中已编译文件移入 archive/。设计要点:

• 判据以 git 快照为准,不依赖 mtime(同步盘/备份恢复会保留旧 mtime,mtime 不能证明文件被编译过):文件可归档,当且仅当它已存在于最近一次编译产物 commit 的 git 快照中(只统计 _wiki/summaries|concepts|entities 下 .md 的提交,不受手工提交 outputs/、log.md 追加或 .gitkeep 骨架提交的干扰),且自那次 commit 以来内容无任何改动(含未提交修改)。未入库或其后有改动的文件一律保留,等待下次 compile + commit——失败方向永远是”多留一周”,绝不误归档。
• 健壮性:set -euo pipefail;git core.quotepath=false + read -r 正确处理含空格/中文的剪藏文件名;兼容 macOS 系统自带 bash 3.2(不用关联数组等 bash 4 特性);同名归档已存在时换名,绝不覆盖;stderr 不并入变量(全新仓库、git warning 均不会破坏判断)。
• 前提:开启 auto_commit(或每周手动 commit),使编译后的库状态进入 git 历史。

E.2 scripts/flomo-delta.py —— 比对两次 flomo 全量导出,提取新增笔记生成 delta 文件(用法:python scripts/flomo-delta.py raw/flomo/<最新导出目录>)。设计要点:

• 核心流程:按 - / ## 行首切段 → 跳过导出头部元信息与纯标题块 → MD5 指纹 → 与 .processed_hashes.json 比对 → 仅新增写入 raw/flomo/delta/delta-<日期-时分秒>.md 并更新指纹。
• 健壮性:delta 文件名带时间到秒,同日多次运行互不覆盖;delta 与状态文件均为临时文件 + os.replace 原子写入;状态文件损坏时报错并给出恢复指引(而非 traceback 或静默重置);严格解码(UTF-8 → GBK 回退,均失败则报错),不静默丢字;拒绝把 raw/flomo 根目录或 delta/ 输出目录当作输入;不因笔记短就丢弃(中文一句话 memo 也是完整笔记)。
• flomo 切分粒度需按你的实际导出格式微调(见 §12 开放问题 2)。

E.3 scripts/daily-report.py / scripts/weekly-report.py(共用 scripts/reportlib.py) —— 工作日志:盘点前一天工作生成日报,并把一周日报合成周报(见 §7.7)。设计要点:

• 数据来源:git 提交(作者日期,本地时区)+ _wiki/log.md 条目 + 当天 flomo 增量;每条自动结论可回溯到具体 sha 或 log 条目;无活动的日子诚实标注,不虚构。
• 手记/综述区:日报”手记”、周报”周度综述”在 <!-- 手记开始 -->/<!-- 综述开始 --> 标记之间,重生成时原样保留(人/LLM 补写的叙述不被覆盖)。
• 健壮性:原子写入;日期/ISO 周参数严格校验;--days/--last 拒绝非正整数;周报对缺失日报的日子明确标注而非静默跳过。
• daily-report.py 支持 --date/--today/--days N;weekly-report.py 支持 --week/--this-week/--last N,默认盘点上一个完整 ISO 周。

E.4 scripts/build-site.sh(配 scripts/site-template.html) —— 从 docs/ 下 Markdown 重建文档站 site/(需 pandoc),详见发布指南。

附录 F:素材提取 Prompt 模板

F.1 flomo 六类提取(处理 raw/flomo/delta/)

读取 raw/flomo/delta/ 中今天生成的 delta 文件。
这些内容来自我多年的个人笔记,请按以下六类提取素材,
分别追加到 material/ 对应子目录的 Markdown 文件中。原始 delta 文件不要修改。

① 原创金句 → material/quotes/flomo-quotes.md(我写的、可直接引用的句子)
② 自我反思与决策复盘 → material/stories/flomo-stories.md(我的亲历、判断过程与反思)
③ 外部引用 → material/references/flomo-refs.md(他人观点/名言,注明来源)
④ 案例记录 → material/cases/flomo-cases.md(外部案例,成功或失败)
⑤ 框架与心智模型 → material/frameworks/flomo-frameworks.md(思维工具、判断框架)
⑥ 数据与趋势 → material/data/flomo-data.md(数据点、市场信号、研究结论)

注意:flomo 内容偏个人,①②⑤ 会更多,其余类若无相关内容不必强行分类。

F.2 写作主题素材库(有写作任务时)

我正在写关于「[主题]」的文章,框架是:[你的文章结构]。
请在 _wiki/ 和 raw/ 中按以下六类搜索素材,输出到 material/[主题]-素材库.md。

① 我的原创金句(material/quotes/ 和 writing/ 存档)
② 我的亲身经历和决策复盘(material/stories/)
③ 外部权威和市场信号(_wiki/entities/ 和 summaries/)
④ 真实案例(_wiki/summaries/)
⑤ 框架与心智模型(_wiki/concepts/ 和 material/frameworks/)
⑥ 数据、研究与趋势(_wiki/summaries/ 中含数据的页面)

附录 G:选型对比(需求优先下的备选评估)

判据统一回到 §4.4 硬标准:本地纯文本、LLM 可编程访问、权责可约束、增量幂等、可观测。任何备选满足这些即可平滑替换。

附录 H:术语表

附录 I:参考资料

• Karpathy — LLM Wiki(核心方案原文):gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
• VentureBeat — Karpathy 的 LLM 知识库架构(绕过 RAG)分析
• Tiago Forte — 《Building a Second Brain》:PARA 组织法与 CODE 框架、渐进式总结、中间产物
• Product School — PRD 结构与模板最佳实践
• sage-wiki — Karpathy 方案的 Go 实现:github.com/xoai/sage-wiki
• Claudian — Obsidian 内置 Claude Code 插件:github.com/YishenTu/claudian
• Claude Code 官方文档:docs.claude.com · Obsidian 官方文档:help.obsidian.md
• 依据文档:《第二大脑建设行动计划》(2026-04,他人私享文档,不随本仓发布)

附录 J:实现状态与引擎偏差(2026-07-14 核对)

本附录是 PRD 与真实施工之间的对账;动态待办与开发计划见同目录开发计划文档(活文档),本附录只做定版快照。

里程碑快照:M1 骨架 ✅ 基本完成(缺 Obsidian 4 辅助插件)· M2 主流程 🟢 大部分已在真实内容上验证(编译/查询/归档/深度 ingest/版本化)· M3 稳态 ❌ 未进入。

已验证(附证据):自动编译(FR-CMP-01,2 源→2 摘要+25 概念页)· 增量幂等(FR-CMP-03)· 自动归档(FR-AUT-01,auto-archive.sh 实测)· 编译后 auto_commit(FR-AUT-04)· 深度 ingest(FR-ING-03,6 文档→素材+摘要+log)· 六类素材(FR-MAT-01,12 文件)· 查询带引用(FR-QRY-02,答案含 [[wiki 内链]])· 查询回写(FR-QRY-03,存 _wiki/under_review/)· 治理边界(FR-SCH,CLAUDE.md 生效)· lint 可跑(FR-LNT,🟡 内容少未喂出真问题)。

引擎偏差(sage-wiki dev build 与本 PRD 假设不符,须知晓):

编译后端:PRD 附录 B 模板默认 anthropic/haiku+sonnet;实际接 GLM 编码端点,并因 GLM flaky(429/120s 超时)于 2026-07-14 增接 Kimi Coding 后端(kimi-for-coding,实测 12/12 全成、更快、中文输出),默认已切 Kimi。两后端 profile + scripts/sage-backend.sh 切换。以仓库 config.yaml / config.glm.yaml / config.kimi.yaml 为准。

“知识库越用越值钱。” Ingest 一篇,Query 一次,Lint 一回 —— 每次操作都让它更丰富。

—— 本 PRD v1.2 · 2026-07-14 · 自用施工蓝图