Initial commit: company-kb framework

- 完整的知识库框架（P0-P5 路线图） - 12篇治理文档 - 工具脚本（kb-init.sh, kb-lint-fm.py, feishu-sync.py, kb-bot） - 7个 Claude 命令 - 示例项目和测试项目（wanniu-l1） - 契约文件（meta/kb-contract.yaml） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-16 18:24:39 +08:00
commit 84f7950589
60 changed files with 4410 additions and 0 deletions
--- a/docs/01-方案总览.md
+++ b/docs/01-方案总览.md
@@ -0,0 +1,43 @@
+# 公司知识库 · 方案文档
+
+> 公司内部 AI 自动化 · 第一件事
+> 状态：方案阶段 | 最后更新：2026-06-24
+
+## 1. 定位
+
+知识库是公司的**信息基石**，采用分层架构。第一件事只做底下两层——把分散信息可靠汇聚、留存、可溯源；上层的信息处理（问答/摘要/喂智能体）属于第二件事，本阶段只为其预留干净接口，不锁死设计。
+
+## 2. 分层架构
+
+```
+┌─────────────────────────────────────────────┐
+│ 4 呈现消费层   飞书为主（也可 CC / 网页 / 机器人） │  ← 以后
+├─────────────────────────────────────────────┤
+│ 3 处理层(多层) 清洗 / 结构化 / 摘要 / 问答 / 路由  │  ← 留接口，暂不做
+├─────────────────────────────────────────────┤
+│ 2 原始汇聚层   统一格式 + 元数据 + 可溯源 = 本体    │  ← 第一件事
+├─────────────────────────────────────────────┤
+│ 1 采集层       飞书/钉钉/企微/微信/NAS/本地文件    │  ← 第一件事
+└─────────────────────────────────────────────┘
+```
+
+## 3. 团队与约束
+
+- 5 人微团队，全员用 Claude Code（CC）；前期技术主导，后续同事维护，录入全员参与。
+- 可用云端 API。呈现与沟通尽量以飞书为主。
+- 微信内容后续切到飞书，再统一汇入。
+
+## 4. 关键技术决策
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 本体载体 | Git + 结构化 Markdown | CC 原生可读，零成本检索，天然做下游底座 |
+| 检索方式 | 初期目录 + CC 语义检索 | 文档量小，先不上向量库，量大再加 |
+| 平台绑定 | 接入多源，不锁死 | 呈现偏飞书，但本体独立可迁移 |
+| 录入方式 | 混合 | 重要内容人工沉淀，高频流动（聊天）自动拉取 |
+
+## 5. 起步策略
+
+单点跑通：首个闭环 = **项目资料**。选一个在跑的项目，把其文档/聊天/决策汇成一处，验证闭环后再复制到其他项目与场景。
+
+详见 [02-首个闭环-项目资料.md](02-首个闭环-项目资料.md)。
--- a/docs/02-首个闭环-项目资料.md
+++ b/docs/02-首个闭环-项目资料.md
@@ -0,0 +1,61 @@
+# 首个闭环 · 项目资料
+
+> 第一件事的单点验证场景
+> 状态：方案阶段 | 最后更新：2026-06-24
+
+## 1. 目标
+
+选一个正在跑的项目，把它散落在飞书文档、微信/飞书聊天、本地文件、NAS 里的资料，汇聚成**一处结构化、带元数据、可溯源**的库。跑通一个，再复制到其他项目。
+
+## 2. 知识库本体结构
+
+```
+公司AI/
+├── README.md              # 总说明
+├── docs/                  # 方案文档（本目录）
+├── CONVENTIONS.md         # 录入规范（元数据/命名/目录约定）
+└── projects/
+    └── <项目代号>/
+        ├── _index.md      # 项目概览、状态、关键决策索引
+        ├── docs/          # 正式文档（从飞书/本地汇入）
+        ├── decisions/     # 决策记录（每条带时间/参与人/背景）
+        ├── conversations/ # 聊天沉淀（微信/飞书摘录）
+        └── assets/        # 附件、图、原始文件
+```
+
+## 3. 元数据约定（可溯源核心）
+
+每个汇入文件头部带 YAML frontmatter：
+
+```yaml
+---
+title: 文档标题
+source: 飞书文档 | 微信群 | 本地 | NAS
+source_link: 原始链接或路径
+author: 产生人
+created: 2026-06-24       # 内容产生时间
+ingested: 2026-06-24      # 汇入知识库时间
+tags: [需求, 决策]
+---
+```
+
+## 4. 录入方式（混合）
+
+- **人工沉淀**：重要文档、决策——同事按规范手动放入（全员参与）。
+- **自动拉取**：飞书文档走飞书开放 API 同步；聊天先人工摘录，后续接飞书机器人自动归集。
+
+## 5. 跑通标准（验收）
+
+选定项目资料归位后，任何人在 CC 里 `cd` 进该项目目录，就能让 AI 基于这堆资料回答：
+- 这个项目现在进展到哪了？
+- 某个决策为什么这么定？
+- 客户/需求方要的是什么？
+
+且**每条回答都能溯源到出处**（靠 frontmatter 的 source/source_link）。
+
+## 6. 动手顺序
+
+1. 建知识库骨架：`README.md` + `CONVENTIONS.md`（地基，先定死规范）。
+2. 用户给定项目代号，建 `projects/<代号>/` 结构。
+3. 现有资料先人工汇入，跑通闭环。
+4. 验证 CC 检索效果 → 再考虑接飞书 API 自动同步。
--- a/docs/03-知识库框架选型调研.md
+++ b/docs/03-知识库框架选型调研.md
@@ -0,0 +1,116 @@
+# 知识库框架选型 · 深度调研报告
+
+> 主题：卡帕西 LLM Wiki 方法论（≥2 套实现）+ Google OKF + 传统 RAG 知识库对比
+> 用途：公司分层知识库选型
+> 调研日期：2026-06-24 | 方法：smart-router → research-suite 后端 + WebSearch/WebFetch 交叉验证
+
+## 摘要（TL;DR）
+
+1. **卡帕西方法论 = "Stop Retrieving, Start Compiling"**（编译 > 检索）。2026-04 提出，X 上 1600 万阅读。核心：让 LLM 把原始资料"编译"成结构化、互链的 Markdown wiki（一次性），之后直接把 wiki 喂进上下文，而非每次查询都对原始文本跑向量检索。
+2. **Google OKF（Open Knowledge Format）= 卡帕西模式的标准化**。2026-06-12 Google Cloud 发布 v0.1，本质就是"带 YAML frontmatter 的 Markdown 目录"，唯一必填字段 `type`。是"格式不是平台"，无 SDK、无运行时、无锁定。
+3. **三者不是互斥，而是分层互补**：卡帕西原理是"地基"，OKF 是"地基的标准格式"，RAG/向量库是"规模超过几百页后的导航层"。
+4. **对我们 5 人团队的结论**：现阶段方案（Git+Markdown+frontmatter）已天然命中 OKF/卡帕西模式，**方向正确，且应直接采用 OKF 的 frontmatter 约定**以获得未来可移植性。规模红线在"~100 源 / 几百页"，远未到，**先不上 RAG**的判断成立。
+
+详见各章。来源列表见末尾。
+
+## 1. 卡帕西 LLM Wiki 方法论（方法论本体）
+
+**核心洞察**：传统 RAG 是"健忘症"——每次查询都从零检索、合成、然后忘掉。知识从不沉淀，系统永远长不大。卡帕西的替代：LLM 当"编译器"，读完所有源 → 抽取概念、压缩含义、建立交叉引用 → 产出结构化 wiki。查询时对**已编译的知识**推理，而非原始文本。
+
+**关键特征**：
+- 知识"累积"而非"检索"，是持久复利资产（与你机器里 `llm-wiki` SKILL 的"编译>检索"理念一字不差）。
+- 纯 Markdown，围绕 index.md 组织，无需向量库。
+- 版本化、类型化、API 可访问，是 agent 推理的底座。
+
+## 2. 卡帕西方法论的两套参考实现
+
+### 实现 A：llm-wiki SKILL（本机已激活，pkm-suite）
+- raw/→wiki/ 增量编译，10 步摄入流程，Delta Check（hash 去重）。
+- Frontmatter Schema：通用字段 type/title/created/updated/tags/status/related/sources + 类型特有字段（source/entity/concept/comparison/question）。
+- 三级查询（Quick/Standard/Deep）、Hot Cache（hot.md ~500 词）、8 项 Lint 健康检查、矛盾检测。
+- 融合 claude-obsidian 精华。**这是我们手里现成的卡帕西实现**。
+
+### 实现 B：Claude Code + Obsidian 社区实现
+- 用 Claude Code 把原始源编译进 Obsidian vault，sources/entities/concepts/comparisons 分目录。
+- 与实现 A 同源同构，验证了"CC 做编译器 + Markdown vault 做载体"是社区主流落地路径。
+
+## 3. Google OKF（Open Knowledge Format）v0.1
+
+**定位**：把"LLM wiki"这个涌现模式，标准化成厂商中立、可移植的格式。作者 Sam McVeety / Amir Hormati（Google Cloud），451 行规格，"a format, not a platform"。GitHub 上附 3 个样例 bundle + 2 个参考实现。
+
+**规格（frontmatter 6 字段，仅 type 必填）**：
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `type` | ✅ 唯一必填 | 概念类别（Metric/Table/Dataset/API/Runbook…） |
+| `title` | 选 | 人类可读名 |
+| `description` | 选 | 一句话摘要 |
+| `resource` | 选 | 指向底层资源的链接 |
+| `tags` | 选 | 分组关键词 |
+| `timestamp` | 选 | 信息最后有效时间 |
+
+**结构**：一个 bundle = 一个 Markdown 文件目录，一文件一概念，文件路径即标识符。生产者与消费者解耦（谁定义 type、加什么字段，由生产者决定）。建议放版本控制里，改动可审、有日期。
+
+**OKF 刻意不做的事**：不是搜索排名信号、不是 web 发现标准（不同于 sitemap/llms.txt）、不替代 schema.org/JSON-LD、v0.1 明确是草稿。
+
+**OKF 与 RAG 的关系**：OKF 面向"在公司知识上跑内部 copilot 或 RAG 的团队"，把 bundle 加载进检索层，让 agent"先读 OKF 再猜"。即 OKF 是喂给 RAG 的优质结构化输入，二者协作。
+
+## 4. 传统 RAG / 向量库 知识库
+
+**机制**：文档切块 → 向量化 → 查询时相似度检索 top-k chunk → 喂 LLM 合成答案。
+**优势**：规模无上限，适合海量、异构、高频更新语料；不需要预先"编译"。
+**痛点（卡帕西批判的核心）**：
+- chunk 不透明、缺上下文，知识从不沉淀，每次查询从零开始（"perpetual amnesia"）。
+- 准确度/速度/可维护性在"一类知识检索问题"上被 wiki 模式碾压（但仅限那一类）。
+
+## 5. 规模红线与失效模式（选型最该警惕的）⚠️
+
+卡帕西纯 wiki 模式在 **"约 100 个源 / 几百个页面"** 后破裂，两个原因：
+1. **index.md 不可导航**：目录条目太多，LLM 首读的单一摘要文件失效，定位不到相关页。
+2. **摄入悖论（循环依赖）**：编译新源时，"不先能导航大索引，就无法判断该更新哪些已有页"——要维护索引得先有可用索引。
+
+**业界共识的解法 = 混合（wiki + RAG）**：保留"编译知识"的思想，但用**向量库替代 index.md 做导航层**，从而支持任意规模。检索负责"找到相关 chunk"，wiki 构建负责"结构化它们"，结构化 wiki 作为合成的输入。结论是"RAG 没死，是 wiki 和 RAG 互补"。
+- 注意残留局限：矛盾检测受限于检索——不相似的文档永不共现，冲突检测不到。
+
+## 6. 三方对比矩阵
+
+| 维度 | 卡帕西 LLM Wiki | Google OKF | 传统 RAG |
+|------|----------------|-----------|---------|
+| 本质 | 方法论（编译>检索） | 格式标准 | 检索架构 |
+| 载体 | Markdown + index | Markdown + frontmatter | 向量库 + chunk |
+| 知识沉淀 | ✅ 累积复利 | ✅（格式层面） | ❌ 每次从零 |
+| 规模上限 | ~100源/几百页 | 同 wiki（它是格式） | 无上限 |
+| 可移植/无锁定 | ✅ | ✅✅（标准化） | 取决于实现 |
+| 检索准确度 | 高（小规模） | — | 中（chunk 噪声） |
+| 基建复杂度 | 极低 | 极低 | 高 |
+| CC 原生友好 | ✅✅ | ✅✅ | ❌ 需中间层 |
+
+## 7. 对公司分层知识库的选型建议
+
+1. **采集层 + 原始汇聚层（第一件事）= 直接落地卡帕西/OKF 模式**。我们原方案（Git+Markdown+frontmatter）已命中，只需把 frontmatter **对齐 OKF 6 字段**（type 必填）+ 保留我们溯源字段（source/author/created/ingested），获得未来可移植性与 Google 生态背书。
+2. **复用 `llm-wiki` SKILL 作为"编译器"**：raw/→wiki/ 增量编译、Lint、矛盾检测都现成，是处理层的天然第一层，不必重造。
+3. **先不上 RAG**：5 人团队、项目资料量级远低于 ~100 源红线。`先不上向量库` 的原判断被证实正确。
+4. **预留混合演进路径**：当某个领域语料逼近几百页、index 开始不可导航时，按业界混合方案引入向量库当"导航层"，wiki 编译层不变。这给处理层留了清晰的升级接口。
+5. **type 体系要早定**：OKF 把 type 交给生产者定义。我们应在 CONVENTIONS.md 里先约定一套公司 type（如 project/decision/conversation/doc/runbook/metric），避免后期不一致。
+
+## 8. 来源
+
+卡帕西方法论：
+- [Beyond RAG: Karpathy's LLM Wiki Pattern](https://nayakpplaban.medium.com/beyond-rag-how-andrej-karpathys-llm-wiki-pattern-builds-knowledge-that-actually-compounds-31a08528665e)
+- [The Compiler Analogy Explained](https://www.mindstudio.ai/blog/karpathy-llm-knowledge-base-architecture-compiler-analogy)
+- [Building an LLM Wiki with Claude Code and Obsidian](https://medium.com/@manavghosh/building-an-llm-wiki-with-claude-code-and-obsidian-eb6c0990e723)
+- [Karpathy's LLM Wiki got 16M views](https://implicator.ai/karpathys-llm-wiki-got-16-million-views-the-code-isnt-the-point-2/)
+
+Google OKF：
+- [Google Cloud 官方博客：OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
+- [OKF: What It Is, the Spec, How to Use It](https://www.startuphub.ai/ai-news/insights/2026/google-open-knowledge-format-okf-explained-2026)
+- [OKF wants to be the lingua franca](https://www.ppc.land/googles-okf-wants-to-be-the-lingua-franca-for-ai-agent-knowledge/)
+- [Google Open-Sources OKF (451 lines, 1 required field)](https://www.implicator.ai/google-open-sources-a-knowledge-format-and-wires-it-into-its-catalog/)
+- [Publishing an OKF bundle with 11ty（6 字段细节）](https://www.simoncox.com/post/2026-06-17-publishing-an-okf-bundle-with-11ty/)
+
+对比与规模失效：
+- [The LLM Wiki at Scale: From Personal Research Tool to Production RAG（规模红线）](https://michalnasternak.medium.com/the-llm-wiki-at-scale-from-personal-research-tool-to-production-rag-247710a1284c)
+- [Karpathy's AI Wiki vs Structured Databases](https://www.mindstudio.ai/blog/karpathy-wiki-vs-structured-database-ai-memory)
+- [Did Karpathy's LLM Wiki Just Kill RAG? Enterprise Verdict](https://www.epsilla.com/blogs/llm-wiki-kills-rag-karpathy-enterprise-semantic-graph)
+- [LLM Wiki vs RAG for Internal Codebase Memory](https://www.mindstudio.ai/blog/llm-wiki-vs-rag-internal-codebase-memory)
+
+> 调研方法说明：research-suite 后端本轮 GATHER 未命中（quality WARNING, 0 source），已切换 WebSearch/WebFetch 兜底并交叉验证。关键结论（OKF 发布日期、6 字段、规模红线）均 ≥2 源印证。
--- a/docs/04-架构.md
+++ b/docs/04-架构.md
@@ -0,0 +1,181 @@
+# 04 · 架构
+
+> 本文是知识库物理形态与数据流的权威描述。目录布局以此为准，`tools/kb-init.sh` 与 `CONVENTIONS.md` 必须与之一致。
+> 核心信条：**单一 Git 真相源 + OKF frontmatter + AI 主执行 + 可生长不重做**。
+
+---
+
+## 1. 四层架构
+
+知识从产生到被消费，流经四层。每层职责单一，层间靠**文件 + frontmatter**解耦，不靠数据库或服务。
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ L4 呈现层  Presentation                                        │
+│   Obsidian（个人主编辑器·wikilink·图谱） + 飞书（公司呈现）      │
+│   CC 问答（cd 进目录语义检索，MVP 默认查询方式）                 │
+├──────────────────────────────────────────────────────────────┤
+│ L3 处理层  Processing（MVP 极薄，按信号生长）                   │
+│   kb-lint-fm.py 校验 · CC 语义检索 · Delta Check 去重           │
+│   [P4 触发] llm-wiki 全量编译：raw markdown → 互链 wiki+hot+index│
+│   [P5 红线] 向量库仅作导航层，替代 index.md                     │
+├──────────────────────────────────────────────────────────────┤
+│ L2 汇聚层  Aggregation ★唯一真相源★                            │
+│   公司AI/ Git 仓库 · 扁平 projects/ 布局 · 每页带 OKF frontmatter│
+│   文件本身即真相，无 raw//wiki/ 双层，无中间数据库               │
+├──────────────────────────────────────────────────────────────┤
+│ L1 采集层  Collection                                          │
+│   人工丢资料（Obsidian 直接写） · feishu-pull.py 半自动导出      │
+│   本地/NAS 文件 · 会议记录 · 聊天摘录                            │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**各层要点：**
+
+- **L1 采集层**：知识入口。唯一强人工动作是「点名物料 + 一句说明」。三条采集通道（见下）汇入同一真相源。飞书文档经 `tools/feishu-pull.py` 半自动单向导出流入 `projects/*/docs/`；个人手记直接在 Obsidian 里写。凭据走环境变量，不入库。
+
+  **三条采集通道：**
+
+  | 通道 | 适合物料 | 方式 | 落成 |
+  |---|---|---|---|
+  | 飞书群/文档 | 对话、临时决策、协作文档 | `feishu-pull.py`（P2） | `conversation`/`doc` |
+  | NAS 各人投递区 | 文件类（PDF/Word/Excel/扫描件） | 点名或投递区扫描 | `doc`+可选 `assets` |
+  | 工作目录/URL 点名 | 任意单个文件/链接 | `/kb-link` 编译链接 | `doc`/`decision` |
+
+  **「编译过的链接」模型（核心，抗膨胀+抗失联）**：默认**不把原件搬进库**。人点名一个物料（工作目录文件 / NAS 路径 / URL），AI 读一遍→提炼精华写成一页知识→页面留 `source_link` 指向原件。好处：①库只存提炼后 markdown，不膨胀；②精华进库可检索可溯源；③原件日后移动/删除，提炼的知识仍在（纯快捷方式做不到）。少数关键且易变的原件，AI 提议、用户点头后才复制进 `assets/` 兜底。
+
+  **NAS 投递区（每人各自）**：`NAS/<同事>/📥知识库投递/`——AI 只扫这个专用子目录，**私人工作目录永不主动触碰**（隐私隔离 + 噪音从源头掐掉）。投递区跟各自 NAS 同步走，不新增基建。MVP 按需扫描，不做常驻监听 daemon（过度工程，投递频繁再说）。
+- **L2 汇聚层（真相源）**：整个体系的地基。就是 `公司AI/` 这个 Git 仓库本身。**文件即真相源**——没有 raw/ 和 wiki/ 双层，没有中间数据库。每个知识页顶部有 OKF frontmatter（见第 2 节 schema，唯一契约在 `meta/kb-contract.yaml`）。版本、审计、冲突仲裁、回滚全靠 Git。
+- **L3 处理层（MVP 极薄）**：MVP 阶段只有 `kb-lint-fm.py`（校验）+ CC 直接对 markdown 做目录/语义检索 + Delta Check 去重。**不生成** `hot.md`/`log.md`/`wiki/` 等导航产物。llm-wiki 全量编译到 **P4** 才启用，向量库到 **P5 红线**才上。
+- **L4 呈现层**：三个视图共享同一真相源。Obsidian 是个人主编辑器，飞书是公司**双向前端**（采集入口 + 群问答查询 + 呈现面），CC 是问答入口。飞书呈现走**双载体**：云文档（叙事型：项目概览/决策）+ 多维表格 Bitable（结构型：全库可筛选/看板）。群机器人问答是**读**操作（调 `/kb-ask`），不构成第二条写路径。详见 `docs/08-飞书双向前端方案.md`。
+
+---
+
+## 2. 扁平目录树
+
+```
+公司AI/                          # Git 根 = 唯一真相源
+├── README.md                    # 总索引 + 快速上手
+├── CLAUDE.md                    # CC 项目级工作记忆
+├── CONVENTIONS.md               # 录入宪法（引用 kb-contract.yaml）
+├── .gitignore                   # .obsidian/ .trash/ 生成产物 大 assets
+│
+├── docs/                        # 方案文档
+│   ├── 01-方案总览.md            # 【不动】
+│   ├── 02-首个闭环-项目资料.md    # 【不动】
+│   ├── 03-知识库框架选型调研.md    # 【不动】
+│   ├── 04-架构.md               # 本文
+│   ├── 05-路线图.md
+│   ├── 06-工具链.md
+│   ├── 07-AI-native工作流.md
+│   └── obsidian-setup.md        # 共享插件清单
+│
+├── meta/
+│   ├── kb-contract.yaml         # ★唯一机器可读契约：type 集 + 必填矩阵 + enum
+│   ├── ingest-manifest.json     # 摄入 hash 台账（去重）
+│   └── stats.md                 # 源计数/页数（红线观察点）
+│
+├── projects/                    # 项目知识（首个闭环即用）
+│   ├── _example/                # OKF 完整示例，照抄即合规
+│   │   ├── _index.md            # type: project
+│   │   ├── docs/                # type: doc
+│   │   ├── decisions/           # type: decision
+│   │   ├── conversations/       # type: conversation
+│   │   └── assets/              # 原始附件（唯一免 frontmatter 目录）
+│   └── <代号>/ ...              # 英文/拼音代号，禁纯中文目录名
+│
+├── entities/                    # type: entity（reserved，首次真实需要时建）
+├── concepts/                    # type: concept（reserved）
+├── questions/                   # type: question（reserved，查询回写）
+│
+├── tools/
+│   ├── kb-init.sh               # 建项目骨架
+│   ├── kb-lint-fm.py            # frontmatter 校验（读 kb-contract.yaml）
+│   └── feishu-pull.py           # 飞书半自动导出
+│
+└── .claude/commands/            # /kb-new /kb-ingest /kb-ask /kb-save /kb-check /kb-status
+```
+
+**布局裁决要点：**
+
+- **扁平 `projects/`**，不建 `raw//wiki/` 双层。文件本身即真相源。
+- **免 frontmatter 目录**：`assets/`（原始附件）；仓库脚手架 `README.md`/`CONVENTIONS.md`/`docs/*`。
+- **禁纯中文目录名**：项目代号用英文/拼音（CC 会把中文编码为 `-` 导致 ID 碰撞）。
+- **reserved type 目录**（`entities/`/`concepts/`/`questions/`）首次真实需要时才建，激活即在 `kb-contract.yaml` 标记 active。
+
+---
+
+## 3. gitignore 与生成产物策略
+
+编译/导航产物**不进 Git**，本地按需由 CC 重建 → 消除多人并发合并冲突。
+
+| 类别 | 是否入 Git | 说明 |
+|---|---|---|
+| markdown 知识页 + frontmatter | ✅ | 真相源，全部提交 |
+| `_index.md`（项目门户，人写/CC 维护） | ✅ | 项目导航锚点 |
+| `meta/kb-contract.yaml` / `stats.md` | ✅ | 契约与观察点 |
+| `hot.md` / `log.md` / `wiki/`（全库导航产物） | ❌ | gitignore，本地按需重建；P4 起由**单一执行者**生成并提交 |
+| `index.md`（全库索引） | ❌ | 同上 |
+| `.obsidian/` | ❌ | gitignore，插件清单共享在 `docs/obsidian-setup.md` |
+| `.trash/` | ❌ | Obsidian 回收站 |
+| 大体积 assets（视频/大图/二进制） | ❌ | 按需，超阈值不入库 |
+
+> **杀掉合并冲突磁石**：`_index.md` 之外的全库导航（`hot.md`/`log.md`/`wiki/`/`index.md`）不进 Git。MVP 阶段 CC 直接对 markdown 做检索，根本不生成这些文件。
+
+---
+
+## 4. 双前端映射
+
+两个前端物理坐在**同一个 Git 仓库** `公司AI/`，是同一真相源的两种视图。**MVP 只有一条写路径**（避免两个前端同时写 Git 起冲突）。
+
+| 前端 | 角色 | 读 | 写 |
+|---|---|---|---|
+| **Obsidian** | 个人主编辑器 | 直接把 `公司AI/` 当 vault 打开，wikilink/图谱浏览 | **唯一写路径**：直接编辑 markdown → `git push` |
+| **飞书** | 公司双向前端 | 全员看项目概览/决策（云文档+Bitable）；群 @机器人 问答 | **不直接写库**：文档经 `feishu-pull.py` 单向导入；群问答是读操作（`/kb-ask`），不写库 |
+| **CC** | AI 问答与自动化执行 | `cd` 进目录语义检索 | 录入/回写循环产出合规 markdown（受 lint 约束） |
+
+- `.obsidian/` **gitignore**，共享插件清单在 `docs/obsidian-setup.md`（装 Dataview）。Git 同步交给 CC/命令行，**不用** Obsidian Git 插件自动提交。
+- **个人草稿隐私边界**：个人未定稿走各自**本地 vault（不入共享仓）**；经一次轻量评审晋升后，文件才移入 `projects/`/`entities/`，`source` 记晋升来源。公司仓无 `personal/` 分区。
+- **删除**（对 5 人是重型基建）：飞书双向 API、机器人写回 `conversations/`、双前端一致性校验脚本。
+
+---
+
+## 5. 下游消费接口
+
+知识库对下游 agent / 工具的暴露接口，全部基于文件系统，无需服务：
+
+1. **文件系统接口**：任何 agent `cd` 进 `公司AI/` 即可 grep/read markdown。这是最低层、最稳定的接口。
+2. **frontmatter 过滤接口**：下游按 `type`/`status`/`tags`/`source` 过滤页面（例：只喂 `type: decision && status: mature` 给报价 agent）。契约在 `meta/kb-contract.yaml`，生产者与消费者依赖同一契约。
+3. **CC 子 agent 接口**：主 CC 派生子 agent 做检索/编译/校验，子 agent 读同一真相源，结论必带 `source_link` 溯源。
+4. **溯源锚点**：每页 `source` + `source_link` 是所有下游答案的强制溯源依据——**无据即报 Gap，绝不用训练数据编造**。
+
+> 未来出现**非 CC 消费方**时再建 MCP server；出现 P5 红线时向量库只做「找到相关页」的导航层，type 契约与编译层原样保留。
+
+---
+
+## 6. 演进阶梯（架构如何生长）
+
+架构分阶段生长，**后阶段是生长而非重做**；frontmatter/type 契约从 P0 到 P5 稳定不变。
+
+| 阶段 | 架构增量 | 触发信号 |
+|---|---|---|
+| **P0** | L2 真相源物理形态定死 + `kb-contract.yaml` + 命令雏形 | 照规范建页、`/kb-check` 通过、CC 能读并引用 |
+| **P1** | 首个项目全汇入，L3 仅 lint + CC 检索 | 该项目问答稳定，产生复制需求 |
+| **P2** | L1 加 `feishu-pull.py` 半自动增量导入 | 项目数 ≥3，飞书成主要文档源 |
+| **P3** | L2 加 `company/`/`domains/` 分区，Obsidian 成团队习惯 | 库覆盖主要知识，产生编译/喂 agent 需求 |
+| **P4** | L3 启用 llm-wiki 全量编译（互链 wiki + hot/index），下游 agent 消费接口 | **`_index` 首读定位失效 + 摄入悖论显现** |
+| **P5** | L3 加向量库导航层（仅替代 index.md，编译层零改动） | `~100 源/几百页` + index 首读定位不准/摄入悖论 |
+
+> **P5 向量库红线（唯一硬触发点）**：在 `~100 源/几百页` 且出现 `index 首读定位不准`/`摄入悖论` 之前，坚决不上向量库/RAG——任何「要不要上 RAG」的默认答案是「不」。详见 `docs/05-路线图.md`。
+
+---
+
+## 附：架构层面的单一真相源
+
+| 契约 | 唯一存放处 | 谁读它 |
+|---|---|---|
+| type 集 + 字段必填矩阵 + enum | `meta/kb-contract.yaml` | kb-lint-fm.py 运行时读 |
+| 目录布局 | 本文 `docs/04-架构.md` | kb-init.sh / CONVENTIONS 与之一致 |
+| 溯源锚点 | 每页 `source`/`source_link` | 所有下游 agent 答案必带 |
+
+任何脚本硬编码 type/字段一律禁止——读契约文件。
--- a/docs/05-路线图.md
+++ b/docs/05-路线图.md
@@ -0,0 +1,122 @@
+# 05 · 路线图
+
+> P0→P5 分阶段作战图。每阶段可独立交付/验收/止步；**后阶段是生长而非重做**。frontmatter/type 契约从 P0 到 P5 稳定不变。
+> 反过度工程铁律：编译层、向量库按**信号触发**延后，不预建。
+
+---
+
+## 阶段总览
+
+| 阶段 | 目标（一句） | 进入下阶段信号 |
+|---|---|---|
+| **P0 骨架+规范** | 定死唯一真相源物理形态 + 录入契约 + 命令雏形 | 任一成员照规范建合规文档、`/kb-check` 通过、CC 能读到并引用 |
+| **P1 首个项目闭环** | 一个在跑项目资料全汇入、CC 可溯源问答 | 该项目问答稳定、同事认可价值，产生复制到第 2/3 个项目的需求 |
+| **P2 多项目+飞书导入** | 扩到多项目 + `feishu-pull.py` 半自动增量导入 | 项目数 ≥3、飞书成主要文档源、公司级非项目知识无处安放 |
+| **P3 全公司领域+Obsidian 成熟** | 加 `company/`/`domains/` 分区 + Obsidian 编辑成团队习惯 | 库覆盖主要知识、录入成习惯，产生「让 AI 主动编译/问答/喂 agent」需求 |
+| **P4 处理层/编译+下游 agent** | 启用 llm-wiki 全量编译 + 下游 agent 消费接口 | **信号触发点：`_index` 首读定位失效 + 摄入悖论显现** |
+| **P5 规模化（向量库）** | 向量库仅当**导航层**替代 index.md，编译层零改动 | 终态 |
+
+---
+
+## P0 · 骨架 + 规范
+
+**目标**：定死唯一真相源物理形态 + 录入契约 + 命令雏形。
+
+**交付物**：
+- 目录骨架（`projects/` `entities/` `concepts/` `questions/` `meta/` `tools/` `.claude/commands/`）+ `.gitignore`。
+- `meta/kb-contract.yaml`（机器可读契约：types 数组含 active/reserved 标记 + 字段必填矩阵 + status/source enum）。
+- `CONVENTIONS.md` + `CLAUDE.md`（项目级）+ `docs/04~07`。
+- `tools/kb-init.sh` + `tools/kb-lint-fm.py`。
+- `projects/_example/`（OKF 完整示例，照抄即合规）。
+- `.claude/commands/`（`/kb-new` `/kb-ingest` `/kb-ask` `/kb-save` `/kb-check` `/kb-status`）。
+
+**验收**：任一成员照规范建一页合规文档 → `/kb-check` 通过 → CC `cd` 进目录能读到并在回答中引用（带 source_link）。
+
+**止步点**：若只需「可溯源 markdown + CC 检索」，停在 P0/P1 完全合理。
+
+---
+
+## P1 · 首个项目闭环
+
+**目标**：把一个在跑项目的资料全部汇入，CC 能可溯源回答「进展如何 / 为何这么定 / 需求方要什么」。
+
+**交付物**：
+- 选一个真实在跑项目 → `/kb-new <代号>` 建骨架。
+- 全部相关资料（决策/聊天/文档）汇入，frontmatter 合规。
+- CC 问答稳定，每条结论挂 `source_link`。
+
+**验收**：该项目三类问题（进展 / 决策依据 / 需求）问答稳定准确，同事认可价值。
+
+**进入 P2 信号**：产生「复制到第 2/3 个项目」的需求。
+
+---
+
+## P2 · 多项目 + 飞书导入
+
+**目标**：扩到多项目 + `feishu-pull.py` 半自动增量导入。
+
+**交付物**：
+- 复制 P1 模式到 ≥3 个项目。
+- `tools/feishu-pull.py` 上线，半自动单向导出飞书文档到 `projects/*/docs/`，AI 自动补 frontmatter。
+- `meta/ingest-manifest.json` 台账记录 hash 去重。
+- **飞书双向前端**（见 `docs/08`）：
+  - 群机器人能问能答（`tools/kb-bot/`，长连接无公网）：群 @机器人 → `/kb-ask` → 带溯源回复。
+  - 飞书呈现双载体（`tools/feishu-render.py`）：云文档（叙事）+ 多维表格 Bitable（结构，可筛选/看板）。
+- NAS 投递区扫描（`tools/nas-pull.py`，编译链接模式）。
+
+**验收**：飞书成为主要文档源；群里 @机器人 问答稳定带溯源；多维表格全库总览可用。
+
+**进入 P3 信号**：项目数 ≥3、飞书成主要文档源、**公司级非项目知识无处安放**。
+
+---
+
+## P3 · 全公司领域 + Obsidian 成熟
+
+**目标**：加 `company/`/`domains/` 分区 + Obsidian 编辑成团队习惯。
+
+**交付物**：
+- 新增公司级分区（`company/`/`domains/`），承接非项目知识。
+- 视需要激活 `entity`/`concept` type 并建目录。
+- Obsidian 成为团队日常编辑器，`docs/obsidian-setup.md` 插件清单落地（Dataview 等）。
+
+**验收**：库覆盖主要知识、录入成习惯。
+
+**进入 P4 信号**：产生「让 AI 主动编译/问答/喂 agent」的需求。
+
+---
+
+## P4 · 处理层 / 编译 + 下游 agent
+
+**目标**：启用 llm-wiki 全量编译（生成互链 wiki + hot/index）+ 下游 agent 消费接口。
+
+**交付物**：
+- llm-wiki 全量 raw→wiki 编译层启用，产物由**单一执行者**生成并提交（`wiki/`/`hot.md`/`index.md` 仍 gitignore 或按约定提交，避免并发冲突）。
+- 下游 agent 消费接口（frontmatter 过滤 + CC 子 agent）。
+
+**验收**：编译产物可用，下游 agent 能按 `type`/`status` 过滤消费。
+
+**★ 信号触发点**：`_index` 首读定位失效 + 摄入悖论显现——**在此之前坚决不启用全量编译**。
+
+---
+
+## P5 · 规模化（向量库）
+
+**目标**：向量库仅当**导航层**替代 `index.md`，卡帕西编译层与 type 契约原样保留。
+
+**★ P5 向量库红线（唯一硬触发点）**：
+> `~100 源 / 几百页` **且** 出现 `index 首读定位不准` / `摄入悖论`。
+> 在此之前——**任何「要不要上 RAG」的默认答案是「不」**。
+
+**交付物**：
+- 向量库只做「找到相关页」的导航层，替代 `index.md` 首读定位。
+- 编译层零改动，type 契约原样保留。
+
+**验收**：向量库导航准确率优于 index.md 首读定位，且未触碰 frontmatter/type 契约。
+
+---
+
+## 生长机制（预留，不落地）
+
+生长机制降为**预留接口说明**，不落地 `/kb-grow` 命令与监控脚本：
+- 仅保留 `meta/stats.md` 人工可读源计数作红线观察点。
+- **不预建**密度/熵增监控。到 P5 红线时再启用向量库导航层，接口预留。
--- a/docs/06-工具链.md
+++ b/docs/06-工具链.md
@@ -0,0 +1,78 @@
+# 06 · 工具链
+
+> 三档工具清单：立即复用 / 立即轻量自建 / 未来再建。附各脚本用途与 gitignore 策略。
+> 反过度工程：MVP 只落地「立即」两档，未来档按信号触发。
+
+---
+
+## 【立即复用】现成能力，零自建
+
+| 工具 | 用途 | MVP 边界 |
+|---|---|---|
+| **llm-wiki SKILL** (`~/.claude/skill-repository/pkm-suite/llm-wiki/SKILL.md`) | 其 lint 检查项、Delta Check、hot cache 模式作参考 | **MVP 仅借用查询/lint 思路**，全量 raw→wiki 编译 P4 才启用 |
+| **Git** | 版本 = 审计 + 冲突仲裁 + 回滚 | 唯一同步与真相源机制 |
+| **Obsidian** | 直接打开 `公司AI/` 当 vault，零镜像 | wikilink/图谱浏览；不用 Obsidian Git 插件自动提交 |
+| **CC 文件系统检索** | MVP 默认问答方式（`cd` 进目录直接语义检索 markdown） | 不生成 index/hot/wiki，直接对 markdown 检索 |
+
+---
+
+## 【立即轻量自建】P0 落地
+
+### `CLAUDE.md`（项目级）
+让 CC 感知库结构 / type / frontmatter / 溯源硬约束。type 白名单**指向契约文件不复制清单**。
+
+### `tools/kb-init.sh`
+一键幂等建 `projects/<代号>/` 骨架：
+- 建 `_index.md`（`type: project` + `status: seed`）+ `docs/` `decisions/` `conversations/` `assets/` 子目录。
+- 幂等：已存在不覆盖。
+- 目录布局与 `docs/04-架构.md` 一致。
+
+### `tools/kb-lint-fm.py`
+frontmatter 校验器：
+- **PyYAML 解析**（正确解析 `related`/`tags` 列表，不用正则）。
+- **读 `meta/kb-contract.yaml`** 判定 type 白名单 + 必填矩阵 + status/source enum，**不硬编码**。
+- 退出码非 0 供 CC 判定；输出分级（阻断 / 提示）。
+- 检查项见 `CONVENTIONS.md` §6。
+
+### `tools/feishu-pull.py`
+飞书半自动单向导出：
+- **凭据走环境变量，不入库**。
+- 拉取飞书文档 → 落 `projects/*/docs/`。
+- AI 自动补 `title`/`ingested`/`source`/`source_link`。
+- 单向（飞书→仓库），**不写回飞书**。
+
+### `.claude/commands/`
+`/kb *` 薄封装（命令表见 `docs/07-AI-native工作流.md`，此处引用不复述）：
+`/kb-new` `/kb-ingest` `/kb-ask` `/kb-save` `/kb-check` `/kb-status`。
+
+---
+
+## 【未来再建】按信号触发，不预建
+
+| 工具 | 触发信号 | 说明 |
+|---|---|---|
+| **llm-wiki 全量编译层** | P4（`_index` 首读失效 + 摄入悖论） | raw→wiki 全量编译，产物单一执行者生成 |
+| **向量库导航层** | P5 红线（~100 源/几百页 + index 定位不准） | 仅做「找到相关页」，编译层零改动 |
+| **飞书机器人查询入口** | 非 CC 消费方出现 | 飞书内直接问答 |
+| **多维表格录入** | 结构化录入需求 | 飞书多维表格 → 仓库 |
+| **MCP server** | 出现非 CC 消费方 | 对外暴露知识库接口 |
+
+> **默认答案是「不」**：任何「要不要上 RAG / 编译 / MCP」的默认答案是「不」，直到对应信号出现。
+
+---
+
+## gitignore 策略汇总
+
+| 类别 | 入 Git | 说明 |
+|---|---|---|
+| markdown 知识页 + frontmatter | ✅ | 真相源 |
+| `_index.md` | ✅ | 项目门户锚点 |
+| `meta/kb-contract.yaml` / `stats.md` / `ingest-manifest.json` | ✅ | 契约 + 台账 |
+| `tools/*` | ✅ | 脚本 |
+| `hot.md` / `log.md` / `index.md` / `wiki/` | ❌ | 生成产物，本地按需重建；消除并发冲突 |
+| `.obsidian/` | ❌ | gitignore，插件清单在 `docs/obsidian-setup.md` |
+| `.trash/` | ❌ | Obsidian 回收站 |
+| 大体积 assets | ❌ | 超阈值不入库 |
+| 凭据 / `.env` | ❌ | 走环境变量，绝不入库 |
+
+详见 `docs/04-架构.md` §3。
--- a/docs/07-AI-native工作流.md
+++ b/docs/07-AI-native工作流.md
@@ -0,0 +1,113 @@
+# 07 · AI-native 工作流
+
+> 统一命令面 `/kb <verb>` + 四循环 + 人机分工铁律。**本文是命令列表的唯一真相源**，工具链文档引用不复述。
+> 核心：AI 主执行，人是监督者与拍板者；丢资料是唯一强人工入口。
+
+---
+
+## 1. 统一命令面 `/kb <verb>`
+
+一处列全，工具链与工作流共用。命令实现在 `.claude/commands/`。
+
+| 命令 | 作用 |
+|---|---|
+| `/kb-new <代号>` | 建项目骨架（调 `kb-init.sh`） |
+| `/kb-ingest <代号> <源>` | 录入循环入口（丢资料，AI 全包） |
+| `/kb-link <文件/NAS路径/URL>` | 编译链接：点名物料，提炼精华+留指针，不搬原件 |
+| `/kb-ask <问题>` | 查询循环入口（强制溯源） |
+| `/kb-save` | 把对话洞察回写为 `questions/` 页 |
+| `/kb-check` | frontmatter 校验 + lint 体检（调 `kb-lint-fm.py`） |
+| `/kb-status` | 源计数 / 健康仪表盘（读 `meta/stats.md`） |
+
+> 删除 `/kb-grow`——生长机制降为预留接口，不落地命令与监控。
+
+---
+
+## 2. 四循环
+
+### 循环 A · 录入（Ingest）
+
+**人只做**：丢资料 + 一句说明 + 对要点点头。
+
+**AI 自动**：
+1. **Delta Check 去重** → 比对 `meta/ingest-manifest.json` hash 台账。
+2. **落原文** → 外部文档进 `projects/*/docs/` 或 `assets/`。
+3. **抽关键发现** → 从原文抽要点。
+4. **写合规页** → frontmatter 自动补齐（`title`/`ingested`/`status`/可推导 `source`）。
+5. **建 wikilink** → 识别提及的实体/项目/决策自动挂链。
+6. **矛盾不静默覆盖** → MVP 用简单标注挂起（正文加矛盾标记），**不做自动 status 降级状态机**。
+
+> **MVP 一次录入产出结构化 markdown，不做 8-15 页 wiki 编译**（P4 才编译）。
+
+### 循环 B · 查询（Ask）
+
+- CC 直接**语义检索 markdown** 回答（MVP 不依赖向量库）。
+- **每条结论挂 `source_link` 溯源**。
+- 覆盖不足**明说缺口**，**绝不用训练数据编造**——无据即报 Gap。
+- 有沉淀价值时**提议 `/kb-save`** 回写。
+
+### 循环 C · 维护（Maintain）
+
+- `/kb-check` 跑 lint（孤立页 / 死链 / 缺字段 / 过时索引）。
+- **保持轻量提示，不做周度 cron 强制门禁**；靠 Git PR review + CC 提示。
+- **安全项 AI 自动修**：补可推导字段、建 stub、加 wikilink。
+- **有损项挂起交人**：删页、解决矛盾、合并、改 type。
+
+### 循环 D · 生长（Grow，预留）
+
+- 一段说明即可——「到 P5 红线时再启用向量库导航层，接口预留」。
+- 仅保留 `meta/stats.md` 人工可读源计数作红线观察点。
+- **不预建**密度/熵增监控。
+
+### 循环 E · 飞书群问答（P2 上线）
+
+同事在飞书群 @机器人 提问，机器人查知识库带溯源回复。**长连接实现，无需公网**（见 `docs/08`）。
+
+- **人只做**：群里 @机器人 问一句。
+- **AI 自动**：`kb-bot` 收事件 → 抽问题 → 调 `/kb-ask`（复用查询循环 B 的全部铁律）→ `lark-cli` 回复到 thread。
+- **只读不写**：机器人绝不写/删知识库；答案带 `source_link`，无据回「知识库暂无」，绝不编造。
+- 人机分工同**循环 B 查询**（此处只是把入口从 CC 换成飞书群）。
+
+---
+
+## 3. 人机分工表
+
+| 环节 | 人 | AI |
+|---|---|---|
+| 采集 | **丢资料 + 一句说明**（唯一强人工入口） | 拉取/去重/落盘 |
+| frontmatter | 拍板 `type`（采集器常可推断） | 自动补 `title`/`ingested`/`status`/`source` |
+| 结构化 | 对要点点头 | 抽发现、写合规页、建 wikilink |
+| 查询 | 提问、判断可用性 | 检索、溯源回答、报 Gap |
+| 矛盾 | 拍板解决 | 标注挂起，不擅自覆盖 |
+| 维护 | review 有损操作 | 自动修安全项、提示 |
+| 删/合并/改 type | **拍板** | 挂起交人 |
+
+---
+
+## 4. 人机分工铁律
+
+1. **能让 AI 自动做的绝不让人做**——丢资料是唯一强人工入口。
+2. **AI 永不擅自有损操作**——删页/覆盖/合并/改 type 必挂起交人。
+3. **AI 永不编造**——无据即报 Gap，绝不用训练数据填坑。
+4. **人是监督者与拍板者**——AI 执行，人决策。
+
+---
+
+## 附：典型会话示范
+
+```
+用户：把客户 A 昨天飞书群里定报价那段整理进来
+  → /kb-ingest clientA 飞书群
+  → AI: Delta Check 通过（新内容）→ 落原文 → 抽出「改用阶梯定价」决策
+       → 写 projects/clientA/decisions/stepped-pricing.md
+       → frontmatter 自动补齐，related 挂到 [[project-clientA]]
+       → 请确认要点：①阶梯定价 ②牺牲首单毛利 ③锁长期合作
+  用户：对
+  → AI: 已提交。
+
+用户：客户 A 为什么不用一口价？
+  → /kb-ask 客户 A 为什么不用一口价
+  → AI: 因客户预算分期到位，改用阶梯定价锁长期合作、牺牲首单毛利。
+       溯源：projects/clientA/decisions/stepped-pricing.md
+       （source: 飞书群 https://company.feishu.cn/im/xxxx?msg=99231）
+```
--- a/docs/08-飞书双向前端方案.md
+++ b/docs/08-飞书双向前端方案.md
@@ -0,0 +1,119 @@
+# 08 · 飞书双向前端方案（群机器人 + 呈现）
+
+> 把飞书从「单向导出源」升级为「双向前端」：采集入口 + 查询入口 + 呈现面。
+> 状态：方案待批 | 底座已验证：lark-cli 已装(bot 身份 cli_a9458d254e3a5bc3)，鉴权可用。
+
+## 关键技术验证结论（已实测）
+
+| 能力 | 命令 | 状态 |
+|---|---|---|
+| 发消息 | `lark-cli im +messages-send --chat-id oc_xxx --markdown "..."` | ✅ bot 可用 |
+| 回复(thread) | `lark-cli im +messages-reply` | ✅ |
+| **收群消息** | `lark-cli event +subscribe --event-types im.message.receive_v1 --compact` | ✅ **WebSocket 长连接，无需公网回调** |
+| 找群 chat_id | `lark-cli im +chat-search --query "群名"` | ✅ |
+| 多维表格 | `lark-cli api POST /open-apis/bitable/v1/apps/...`（通用 api，CLI 1.0.3 无 bitable 子命令但通用 api 通鉴权） | ✅ |
+| 云文档 | `lark-doc-manager` skill（已激活）/ `lark-cli docs` | ✅ |
+
+> **最大收获**：能问能答走**长连接**而非公网 HTTP 回调——省掉 VPS 上常驻 web 服务，5 人团队负担骤降。
+
+---
+
+## 一、群机器人：能问能答
+
+### 架构（长连接，无公网）
+```
+同事在飞书群 @机器人 "客户A为什么不用一口价"
+   ↓ 飞书事件 (im.message.receive_v1)
+lark-cli event +subscribe  ── WebSocket 长连接 ──> 本地/VPS 常驻进程
+   ↓ NDJSON 每行一事件，--compact 提取文本
+kb-bot 调度器：解析 → 剥离 @ → 得到问题
+   ↓
+调 CC 跑 /kb-ask（基于知识库检索，强制溯源，无据报 Gap）
+   ↓
+lark-cli im +messages-reply  ── 回复到原消息 thread
+```
+
+### 落地组件
+- `tools/kb-bot/subscribe.sh` — 起长连接：`lark-cli event +subscribe --event-types im.message.receive_v1 --compact --output-dir ./events/`
+- `tools/kb-bot/handle.py` — 消费事件：过滤 @机器人 的消息 → 抽问题 → 调 CC headless (`claude -p "/kb-ask <问题>"`) → 取答案 → `lark-cli im +messages-reply`。
+- 防重：event 有 idempotency，handle 记已处理 message_id。
+- 铁律继承：答案强制带 source_link，无据回「知识库暂无，可 /kb-link 补充」，绝不编造。
+
+### 部署（MVP）
+- 跑在**一台常开机器**（你的 Mac mini / LA VPS 均可，长连接不挑落点）。
+- MVP 用 shell + 轮询 events 目录起步；稳定后再包成 launchd/systemd 常驻。
+- **不建公网服务、不开端口**——这是刻意的反过度工程。
+
+---
+
+## 二、飞书呈现架构：三层投影
+
+**核心原则：飞书是「读屏」不是「数据库」。** 真相源永远是 Git 仓库，飞书上所有内容都是从 Git **单向投影**的镜像；同事在飞书上看/问，不在飞书上改知识（改走 Obsidian/Git）。飞书怎么动都不污染真相源。
+
+三层对应同事三种消费姿势：
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 第3层 群机器人（问）  "客户A为什么不用一口价？"         │ 找答案·秒回
+│   @机器人 → /kb-ask → 带溯源回复（实时，读 Git 真相源） │
+├─────────────────────────────────────────────────────┤
+│ 第2层 多维表格（查）  全库一张表，按项目/状态筛选/看板  │ 扫全局·俯瞰
+│   每页一行：type/status/source/项目/source_link        │
+├─────────────────────────────────────────────────────┤
+│ 第1层 云文档（读）    项目概览、决策来龙去脉            │ 读故事·了解
+│   projects/*/_index + 关键 decision → 飞书文档         │
+└─────────────────────────────────────────────────────┘
+      ↑ 三层都从同一 Git 仓库单向投影，飞书只读
+```
+
+**为什么分三层**：同事需求本就分三种——「了解一个项目」读云文档、「俯瞰筛选全局」用多维表格、「要一个具体答案」问机器人。一层满足不了三种姿势。
+
+**更新节奏（反过度工程）**：MVP 第 1/2 层**不做实时同步**——录入后手动跑一次 `feishu-render`，或每天定时同步一次即可；第 3 层机器人是实时的（读 Git 真相源本身，不依赖投影）。
+
+---
+
+### 载体 A：云文档（第 1 层·叙事型呈现）
+- 用途：项目概览、决策来龙去脉——适合「读故事」。
+- 同步：`projects/<代号>/_index.md` + 关键 decision 页 → 飞书云文档。
+- 工具：`tools/feishu-render.py --docs <代号>`，调 lark-doc-manager / `lark-cli docs +create/+update`。
+- 频率：按需/手动触发（MVP 不做实时）。
+
+### 载体 B：多维表格 Bitable（第 2 层·结构型呈现）
+- 用途：全库总览——每条 decision/doc/conversation 一行，带 `type/status/source/created/项目/source_link` 字段，同事可**筛选/分组/看板/仪表盘**。这是「呈现全库」的主力。
+- 同步：扫 `projects/**/*.md` frontmatter → 每页一条记录 → 通用 api 写入 Bitable。
+- 工具：`tools/feishu-render.py --bitable`，用 `lark-cli api POST /open-apis/bitable/v1/apps/{app}/tables/{table}/records`。
+- 字段严格对齐 `meta/kb-contract.yaml`（type/status enum 一致）。
+- 频率：录入后增量 upsert（按 source_link 或页路径做唯一键）。
+
+> Wiki 空间**暂不做**（用户判断现阶段不适合）。
+
+---
+
+## 三、对既有架构的影响（需回改的文档）
+
+1. `docs/04-架构.md` L4 呈现层：飞书从「只读呈现」补充为「双向」——采集(群机器人收/kb-link)、查询(群@问答)、呈现(云文档+Bitable)。**写路径仍唯一(Obsidian/Git)**，机器人问答不写库、只读。
+2. `docs/04-架构.md` §4 双前端映射表：飞书行的「写」列注明——群机器人问答是**读**操作(调/kb-ask)，不构成第二条写路径。
+3. `docs/05-路线图.md`：群机器人 + 呈现属 **P2**（原 P2 只有 feishu-pull，现扩为完整双向）。
+4. `docs/07-AI-native工作流.md`：新增「循环 E · 飞书问答」——群 @ → /kb-ask → 回复，人机分工同查询循环。
+5. 命令面：无新 /kb 命令（机器人内部调 /kb-ask），但新增 `tools/kb-bot/` 与 `tools/feishu-render.py`。
+
+---
+
+## 四、安全与凭据
+
+- lark-cli 凭据由其自身管理（非本仓环境变量），**不入库**。
+- 机器人问答**只读知识库**，不执行写/删——继承「AI 永不擅自有损操作」铁律。
+- 群机器人回答带 source_link，同事可核。
+- 长连接进程日志不含敏感 token（--quiet 抑制 stderr）。
+
+---
+
+## 五、分步实施顺序（建议）
+
+1. **P2-a 发消息打通**：`kb-bot` 先做「只发」——手动触发把一条测试答案发到群，验证 chat-id/markdown 渲染。
+2. **P2-b 收消息打通**：起 `event +subscribe`，@机器人能在 events/ 看到事件。
+3. **P2-c 闭环**：handle.py 串起「收→/kb-ask→回复」，群里问答跑通。
+4. **P2-d 呈现-Bitable**：建一张多维表，把 _example 项目的页同步成记录。
+5. **P2-e 呈现-云文档**：把 _example 的 _index 同步成飞书文档。
+
+每步独立可验收，任一步卡住不影响已完成步骤。
--- a/docs/09-同事使用指南.md
+++ b/docs/09-同事使用指南.md
@@ -0,0 +1,75 @@
+# 09 · 同事使用指南
+
+> 给全体同事。**你不用懂 Git、frontmatter、OKF 这些技术词**——它们 AI 全包了。
+> 你只需要记住三个动作：**丢、问、看**。
+
+---
+
+## 一句话理解
+
+公司知识库 = 一个「把散落各处的资料，沉淀成能随时问、随时查的公司大脑」的系统。
+你平时怎么发飞书，就怎么用它——**成本几乎为零**。
+
+---
+
+## 三个动作
+
+### 1. 丢 —— 把值得留下的资料存进去
+
+| 场景 | 怎么做 |
+|---|---|
+| 飞书群里的文档/消息 | @机器人 说「把这个存进 X 项目」 |
+| 你电脑/NAS 里的文件 | 放进你的 `NAS/你的名字/📥知识库投递/` 目录，或跟 AI 点名「我工作目录那个合同要进库」 |
+| 一个网页链接 | 直接把链接丢给 AI |
+
+**AI 会自动**：读一遍 → 提炼要点 → 补全元数据 → 归到对应项目。你只需**丢 + 一句说明 + 对 AI 抽的要点点个头**。
+
+> 💡 **原件不用搬**：AI 只把「精华」存进库、留个链接指回原文件。所以库不会变臃肿，你的原文件也原地不动。
+
+### 2. 问 —— 快速找答案
+
+飞书群 **@机器人** 直接问，例如：
+- 「客户 A 为什么不用一口价？」
+- 「power-bid 项目现在进展到哪了？」
+
+机器人查知识库，**带着出处**回答你。查不到会直说「知识库暂无」，**绝不瞎编**。不放心就点它给的链接核对原文。
+
+### 3. 看 —— 浏览和俯瞰
+
+| 我想… | 打开 |
+|---|---|
+| 了解某个项目的来龙去脉 | 飞书里该项目的**云文档**（适合读故事） |
+| 俯瞰全局、按项目/状态筛选 | 飞书**多维表格**（适合扫全局、过滤） |
+| 深度编辑整理 | 用 **Obsidian** 打开仓库改（进阶） |
+
+---
+
+## 只需记住的三条
+
+1. **要沉淀的，主动丢一下**——这是你唯一需要主动做的事。不丢，它不会自己进来。
+2. **私人文件不用管**——AI 只处理你点名或投递的，不会翻你的工作目录。
+3. **答案都带出处**——能核对、不瞎编、查不到就说没有。
+
+---
+
+## 一个典型的一天
+
+- 🌅 开完晨会，把飞书会议纪要 @机器人「存进 clientA」→ 自动沉淀成决策页
+- ☀️ 下午想不起细节，群里 @机器人「上次定的报价方案是啥」→ 秒回带链接
+- 🌆 周会前打开多维表格，筛出所有「进行中」的项目 → 进展一览
+
+---
+
+## 常见疑问
+
+**Q：我丢错了/丢重复了怎么办？**
+A：AI 会自动去重（同一份不会进两次）；丢错了跟 AI 说一声，删改由 AI 提请、人确认，不会误删。
+
+**Q：机器人答得不对怎么办？**
+A：点它给的 `source_link` 看原文。若是知识库里资料本身过时，@机器人 说一声或补一份新的进去。
+
+**Q：我要改一条已有的知识？**
+A：知识不在飞书上直接改（飞书是「读屏」）。用 Obsidian 打开仓库改，或跟 AI 说要改哪条。
+
+**Q：涉及我个人的草稿、没定稿的东西？**
+A：放你自己的本地目录，别丢进投递区。**定稿了再丢**——进了库就是全员可见的公司知识。
--- a/docs/10-部署与运维.md
+++ b/docs/10-部署与运维.md
@@ -0,0 +1,126 @@
+# 10 · 部署与运维
+
+> 物理拓扑 + 部署步骤 + 运维手册。回答「仓库在哪、处理逻辑在哪跑、同事怎么接入」。
+> 核心：**仓库家 + 常驻处理都在公司 NAS**；交互处理在各人本机。
+
+---
+
+## 一、物理拓扑
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  公司 NAS（数据的家 + 常驻处理节点）                            │
+│  ├─ Gitea 仓库 company-kb.git ★唯一真相源★                     │
+│  ├─ 常驻：kb-bot 飞书群机器人长连接（subscribe + handle）        │
+│  └─ 定时：feishu-render 投影（云文档 + 多维表格）               │
+└──────────────────────────────────────────────────────────────┘
+      ▲ git clone/push (内网/VPN)        │ 投影(只读)
+      │                                  ▼
+┌─────────────┐                   ┌──────────────┐
+│ 各人本机     │                   │ 飞书三层呈现  │
+│ 本地 clone   │                   │ 文档/表格/机器人│
+│ CC 交互处理  │                   └──────────────┘
+│ /kb-ingest   │
+│ /kb-ask      │      ┌────────────────────────────┐
+│ /kb-link     │◀─────│ NAS 同步盘：各人工作目录↔投递区│
+└─────────────┘       │ （采集通道，单向投递，无冲突）│
+                      └────────────────────────────┘
+```
+
+**两条 NAS 用途，各司其职，不冲突：**
+
+| NAS 角色 | 机制 | 用途 | 为何不冲突 |
+|---|---|---|---|
+| **Gitea 仓库** | Git 协作 | 知识库本体（提炼后真相源） | 多人共享，Git 管合并/审计/回滚 |
+| **同步盘** | Synology Drive / SMB | 采集通道（投递原始物料） | 单向投递，无多人同改 |
+
+---
+
+## 二、处理逻辑落点
+
+| 处理类型 | 跑在哪 | 触发 | 说明 |
+|---|---|---|---|
+| **交互处理** `/kb-ingest`/`/kb-ask`/`/kb-link` | **各人本机** | 人触发 | CC 读本地 clone，天然分布式，无需中心 |
+| **常驻处理** 飞书群机器人长连接 | **NAS** | 常驻 | 读 Git 真相源实时回答，无需公网 |
+| **定时处理** feishu-render 投影 | **NAS** | 定时/手动 | md→飞书云文档+多维表格 |
+
+> 关键：常驻/定时处理需要一台常开机 = NAS。交互处理分散在各人机器，NAS 不是单点瓶颈。
+
+---
+
+## 三、部署步骤
+
+### 3.1 接 Gitea remote（需内网/VPN）
+
+```bash
+cd ~/奇域/智能体开发/公司AI
+# 在 Gitea Web (192.168.0.101:3002/robert) 建空 repo: company-kb
+git remote add origin http://192.168.0.101:3002/robert/company-kb.git
+git push -u origin main
+```
+
+> 现不在内网时 Gitea 不可达，本地提交先攒着，回公司网络再 push。
+
+### 3.2 同事接入（每人一次）
+
+```bash
+git clone http://192.168.0.101:3002/robert/company-kb.git
+cd company-kb
+# CC: cd 进来即可用 /kb-ask /kb-ingest（读项目级 CLAUDE.md 自动感知）
+# Obsidian: Open folder as vault 打开本目录（个人主编辑器）
+```
+
+日常同步：干活前 `git pull`，产出后 `git add/commit/push`（或让 CC 代跑）。
+
+### 3.3 NAS 常驻机器人（Gitea 通后）
+
+NAS 上 clone 一份 + 装 lark-cli + 起长连接：
+
+```bash
+# NAS 上（Container/SSH）
+git clone <gitea-url> && cd company-kb
+lark-cli auth status                      # 确认 bot 身份
+nohup bash tools/kb-bot/subscribe.sh > /tmp/kb-sub.log 2>&1 &
+nohup python3 tools/kb-bot/handle.py --watch > /tmp/kb-handle.log 2>&1 &
+```
+
+稳定后包成 NAS 的开机自启（Synology「任务计划」或 systemd）。NAS 侧仓库定时 `git pull` 保证机器人读到最新。
+
+### 3.4 定时投影（可选）
+
+NAS 上 crontab 每日同步飞书呈现：
+
+```cron
+# 每天 08:07 投影到飞书（错开整点）
+7 8 * * * cd /path/company-kb && git pull -q && python3 tools/feishu-render.py --bitable
+```
+
+---
+
+## 四、运维手册
+
+### 备份
+- Gitea 仓库随 NAS 备份策略走（NAS 快照/RAID）。
+- Git 本身即分布式备份：每个同事的本地 clone 都是全量副本。
+
+### 冲突处理
+- 多人改同一页 → Git 合并；`_index.md` 等导航文件已设计为低冲突。
+- 编译产物（hot/index/wiki）已 gitignore，不进 Git，无合并冲突（见 docs/04 §3）。
+
+### 权限（MVP → 演进）
+- MVP：5 人皆可直接 push main，靠 Gitea Web review + `/kb-check` 把关。
+- 演进：Gitea 上给 main 加保护分支 + PR review（团队变大或误操作增多时）。
+
+### 健康检查
+- `python3 tools/kb-lint-fm.py` — frontmatter 合规（exit 0 为健康）。
+- `/kb-status` — 源计数 / type 分布 / 红线观察（见 docs/05 P5）。
+- 机器人存活：看 `/tmp/kb-sub.log`、`/tmp/kb-handle.log`。
+
+### 凭据安全
+- lark-cli 凭据由其自身管理，**不入库**（.gitignore 已挡 .env）。
+- 飞书 App Secret 等走环境变量或 lark-cli 配置，绝不提交。
+
+### 故障恢复
+- 机器人挂 → NAS 上重跑 3.3 的两条 nohup。
+- 仓库损坏 → 从任一同事本地 clone `git push` 恢复 Gitea。
+- Gitea 不可用 → 交互处理（各人本机 CC）不受影响，仅机器人/投影暂停。
--- a/docs/11-信息全景与非项目结构.md
+++ b/docs/11-信息全景与非项目结构.md
@@ -0,0 +1,80 @@
+# 11 · 信息全景与非项目结构
+
+> 知识库不只是「项目」。本文定义公司信息全景、非项目信息的落地结构，以及**以后加新类别的登记流程**（可生长性核心）。
+
+---
+
+## 一、公司信息全景
+
+按稳定度/归属分，5 人公司的信息大致这几类。**契约已预留对应 type**，按痛感分批激活，不一次全上（反过度工程）。
+
+| 类别 | 内容 | type | 状态 |
+|---|---|---|---|
+| 项目 | 客户/内部项目的文档·决策·聊天 | project/decision/conversation/doc | ✅ 已用 |
+| **公司基本信息** | 公司档案·团队·组织·对外介绍 | doc | ✅ 本次纳入 |
+| **共享学习知识库** | 外部知识·学习资料·读书笔记 | doc | ✅ 本次纳入 |
+| 公司制度/SOP | 报销·请假·发布·入职流程 | runbook | 预留 |
+| 实体档案 | 客户/供应商/竞品（跨项目枢纽） | entity | 预留 |
+| 术语/黑话 | 缩写·产品名·行业名词 | concept | 预留 |
+| 指标口径 | KPI·财务·业务数据定义 | metric | 预留 |
+| 问答沉淀 | 高频问题的权威答案 | question | 预留 |
+
+---
+
+## 二、目录结构扩展
+
+非项目信息**提到顶层平级**（跨项目、不随项目结束消失），不塞进 projects/：
+
+```
+公司AI/
+├── projects/        # 项目（有生命周期）        ✅
+├── company/         # 公司基本信息（本次新增）
+│   └── _index.md    # 公司档案入口（type: doc）
+├── learning/        # 共享学习知识库（本次新增，按领域分）
+│   ├── _index.md    # 学习库总览
+│   ├── ai/          # 领域子目录：AI
+│   ├── management/  # 领域：管理
+│   └── industry/    # 领域：行业
+├── entities/ concepts/ questions/   # 预留 type，按需激活
+└── metrics/ company-sop 等          # 未来登记后新增
+```
+
+- **company/** 与 **learning/** 本次都用现成 `doc` type（不急着激活新 type），靠**目录 + tags** 区分，够用。
+- learning 按**领域分子目录**（用户定），每篇学习笔记归入对应领域；跨领域用 tags 补充。
+- 量大到需要专属字段时（如学习资料要「掌握程度」），再升级成独立 type（走第四节流程）。
+
+---
+
+## 三、飞书呈现映射
+
+沿用「多维表格=全库地图 + 云文档=详情」，非项目信息只是**多加视图**：
+
+| 信息类别 | 多维表格视图 | 云文档 |
+|---|---|---|
+| 公司基本信息 | 「公司信息」视图（筛 company/ 路径） | 公司介绍/团队文档 |
+| 共享学习库 | 「学习库」视图（按领域 tags 分组） | 重点学习主题长文 |
+| 项目 | 按项目分组视图（已有） | 各项目概览 |
+
+群机器人自动全覆盖——问「公司是做什么的」「XX 领域有什么学习资料」都能答（检索整库，不分项目与否）。
+
+---
+
+## 四、以后加新类别的登记流程 ★可生长性核心★
+
+加新一类信息**不用改代码**——`kb-contract.yaml` 是唯一契约，改它即可：
+
+```
+想加一类（例：以后要"财务指标库"）
+  ① 在 meta/kb-contract.yaml 的 types 加一条：
+       - name: metric
+         active: true
+         dir: metrics/
+         desc: 一个指标及其口径、来源
+     （若需专属字段/派生必填，一并在 fields/derived_rules 登记）
+  ② 建对应顶层目录（mkdir metrics/）
+  ③ 飞书多维表格加一个筛该 type 的视图
+  ④ 一次 PR 合入
+  → 完成：lint 自动认它、机器人自动能查，无需改任何脚本
+```
+
+**原则**：核心 type 集封闭稳定，扩展走这条轻量登记。**结构稳定但能生长**——不因加类别而重构。禁止在脚本里硬编码 type（一律读契约）。这也是「先少后多」策略的落地：先激活真痛的，其余登记在册、按需激活。
--- a/docs/12-治理与规则维护.md
+++ b/docs/12-治理与规则维护.md
@@ -0,0 +1,82 @@
+# 12 · 治理与规则维护
+
+> 回答「中间处理规则放哪、谁维护、怎么改」。
+> 核心区分：**物料录入=全员参与；规则修改=全员可提 PR，合入需至少一人 review。**
+
+---
+
+## 一、两类"规则"，分开放
+
+「中间处理规则」其实是两种，位置与维护完全不同，混谈会乱：
+
+| | ①数据契约规则 | ②处理程序规则 |
+|---|---|---|
+| 管什么 | 「长什么样才合格」 | 「怎么把原料变成知识」 |
+| 内容 | type 集 / 字段必填 / enum / 派生规则 | 抽要点·去重·判类型·挂链·矛盾处理·检索·lint |
+| **真相源** | `meta/kb-contract.yaml`（机器可读，唯一） | `.claude/commands/kb-*.md`（可执行 AI 指令，就是逻辑本身） |
+| 人读镜像 | `CONVENTIONS.md`（宪法，只镜像不复述） | `docs/07-AI-native工作流.md`（四循环描述） |
+| 谁执行 | `tools/kb-lint-fm.py` 运行时读 | CC 跑 `/kb-ingest`·`/kb-link`·`/kb-ask` 时执行 |
+
+**结论**：中间处理规则**已经有家**，不是没处放——数据契约在 `kb-contract.yaml`，处理逻辑在 `.claude/commands/`，说明在 CONVENTIONS + docs/07。
+
+> 前提：处理层（L3）目前**极薄**（只有 MVP 必需的去重/抽要点/补 frontmatter/lint/检索）。更深的处理（多级摘要、自动分类、喂下游智能体）属「第二件事」附近，**刻意延后不锁死**。
+
+---
+
+## 二、谁维护——归属矩阵
+
+**分两条线，不要混**：
+
+| 事项 | 谁做 | 门槛 |
+|---|---|---|
+| **物料录入**（丢资料/答问/点头） | **全员** | 无门槛，鼓励人人参与 |
+| **规则修改**（改契约/命令/lint） | **全员可提，合入需 review** | 至少一人 review 后合并 |
+
+- **物料谁都能丢，规则改动要过审**——因为改一条字段必填，全库 lint 行为就变，影响面大。
+- 无固定"负责人"，但任何规则 PR **不可自审自合**，需另一人 review。
+- 前期实际由技术主导 review；随团队成长，review 者可扩展。
+
+---
+
+## 三、规则怎么改（PR 流程）
+
+任何人想改规则，走统一轻量流程：
+
+```
+① 起分支改动（改 kb-contract.yaml / .claude/commands/ / CONVENTIONS / docs/07）
+② 本地跑 python3 tools/kb-lint-fm.py 确认全库仍 exit 0
+   （改了契约必须验证：既有页不被新规则误伤）
+③ 提 PR，说明改什么、为什么、影响面
+④ 至少一人 review → 合入 main
+```
+
+**改契约的额外铁律**：
+- 改字段必填/enum → 先跑 lint 扫全库，确认存量页不被打成 error（若会，先补齐存量再改规则）。
+- 加新 type → 走 `docs/11 §4` 登记流程（契约加条 + 建目录 + 飞书加视图）。
+- 禁止在脚本里硬编码 type/字段——一律读契约。
+
+**改命令/处理逻辑**（`.claude/commands/`）：
+- 命令是 AI 的可执行指令，改它即改处理行为。
+- review 关注：是否违背三条铁律（只读不擅改、不编造、有损操作挂起交人）。
+
+---
+
+## 四、处理层（L3）演进治理
+
+处理层刻意留白，未来按信号生长，每次生长都是一次规则扩展，同样走 PR + review：
+
+| 演进 | 触发信号 | 规则变化 | 阶段 |
+|---|---|---|---|
+| llm-wiki 全量编译 | `_index` 首读定位失效 | 加编译规则 + 编译产物归属（单一执行者） | P4 |
+| 向量库导航层 | ~100 源/几百页 + index 失效 | 加检索规则，契约/编译层不变 | P5 |
+| 喂下游智能体 | 第二件事成型 | 加 frontmatter 过滤/消费接口规则 | 第二件事 |
+
+> 原则：**处理层怎么长，契约（type/frontmatter）尽量不动**——上层生长、地基稳定。任何 L3 规则新增都登记在册、可 review、可回滚。
+
+---
+
+## 五、一句话总结
+
+- **中间处理规则不是没家**：数据契约→`kb-contract.yaml`，处理逻辑→`.claude/commands/`，说明→CONVENTIONS + docs/07。
+- **物料全员录入，规则全员可提、review 合入**（不可自审自合）。
+- **改规则先过 lint，改契约先扫全库**；处理层按信号生长，地基（契约）尽量不动。
--- a/docs/obsidian-setup.md
+++ b/docs/obsidian-setup.md
@@ -0,0 +1,47 @@
+---
+type: doc
+title: "Obsidian 前端配置（个人主编辑器）"
+status: mature
+created: 2026-07-06
+ingested: 2026-07-06
+source: 人工沉淀
+---
+
+# Obsidian 配置 · 个人主编辑器
+
+> 把 `公司AI/` 目录直接作为 Obsidian vault 打开即可。Obsidian 是**个人主编辑器 + 唯一写路径**，飞书只读呈现、CC 只读问答。
+> `.obsidian/` 已 gitignore——每人工作区配置本地私有，不互相污染；只有下面这份**推荐插件清单**共享。
+
+## 打开方式
+
+1. Obsidian → Open folder as vault → 选 `~/奇域/智能体开发/公司AI`。
+2. 首次会提示信任作者，选信任（本仓库脚本仅本地运行）。
+
+## 推荐插件（全员统一）
+
+| 插件 | 用途 | 必装 |
+|---|---|---|
+| **Dataview** | 按 frontmatter 查询/看板（如"列出所有 status: seed 的 decision"） | ✅ |
+| Templater | 新建页时自动套 OKF frontmatter 模板 | 建议 |
+| Git | 图形化提交（可选，命令行/CC 提交也行） | 可选 |
+
+> 不要装 "Obsidian Git 自动提交"——Git 同步统一走命令行或 CC，避免每人自动 push 制造冲突。
+
+## Dataview 速用示例
+
+在任意页面写代码块：
+
+    ```dataview
+    TABLE status, created, source
+    FROM "projects"
+    WHERE type = "decision"
+    SORT created DESC
+    ```
+
+即可实时列出所有决策页。字段名严格对齐 `meta/kb-contract.yaml`。
+
+## 写路径铁律
+
+- 编辑 markdown → `git add/commit/push`（或让 CC 代跑）。
+- 新建页面照抄 `projects/_example/` 的 frontmatter，或用 `/kb-new` / `/kb-ingest`。
+- 个人未定稿草稿**不要**放进本仓库——走各自本地私有 vault，晋升定稿后才进公司 Git（见 `docs/04-架构.md` 双前端映射）。