company-kb/落地方案.md

# 公司知识库 · 完整落地方案

> 从架构到实施的一站式方案：整体框架 + 飞书对接 + 分阶段落地
> 更新时间：2026-07-16

---

# 第一部分：整体架构

## 1.1 这是什么系统？

一个 **AI 原生的公司知识库**：
- **文件柜（Git 仓库）** = 存所有知识，无数据库
- **标签纸（frontmatter）** = 每篇文档的元数据，让 AI 快速识别
- **AI 管理员（Claude）** = 常驻，自动采集、生成、问答

**核心理念（4 条铁律）**：
1. **单一真相源** = Git 仓库本身，文件即真相
2. **编译过的链接** = 不搬原件，提炼精华 + 留 source_link 指回原文
3. **溯源铁律** = 每条结论必挂原始链接，无据报 Gap，绝不编造
4. **AI 权限边界** = 安全项自动做（补字段/建链），有损项挂起交人（删除/合并）

## 1.2 四层架构

```
┌────────────────────────────────────────────────┐
│ L4 呈现层  Obsidian编辑 + 飞书展示 + Claude问答   │
├────────────────────────────────────────────────┤
│ L3 处理层  lint校验 + AI语义检索 + 去重           │
├────────────────────────────────────────────────┤
│ L2 汇聚层  Git仓库 + OKF frontmatter ★真相源★    │
├────────────────────────────────────────────────┤
│ L1 采集层  飞书 + NAS投递区 + 手动点名            │
└────────────────────────────────────────────────┘
```

## 1.3 目录结构

```
company-kb/                     # Git 根 = 唯一真相源
├── projects/                   # 项目知识
│   ├── <代号>/                 # 每个项目一个档案盒
│   │   ├── _index.md           # 项目门户 (type: project)
│   │   ├── docs/               # 外部文档 (type: doc)
│   │   ├── decisions/          # 决策记录 (type: decision)
│   │   ├── conversations/      # 聊天沉淀 (type: conversation)
│   │   └── assets/             # 原始附件（免 frontmatter）
│   └── _example/               # 示例项目（照抄即合规）
├── company/                    # 公司基本信息（P3 启用）
├── learning/                   # 共享学习库（ai/management/industry）
├── entities/ concepts/ questions/  # 预留 type（未激活）
├── meta/
│   ├── kb-contract.yaml        # ★唯一契约：type/字段/enum 规则
│   ├── ingest-manifest.json    # 去重台账
│   └── stats.md                # 统计观察点
├── tools/                      # 工具脚本
└── .claude/commands/           # Claude 命令面板 (/kb-*)
```

## 1.4 两个核心概念

### frontmatter = 文件的"标签纸"

每个 .md 文件顶部用 `---` 包起来的元数据：

```yaml
---
type: decision              # 类型（唯一硬必填）
title: "客户A阶梯定价"       # 标题
description: 因预算分期改用阶梯定价  # 一句话描述
tags: [报价, 客户-a]        # 标签（筛选用）
timestamp: 2026-06-20       # 发生时间
source: 飞书群              # 来源渠道
source_link: https://...    # 原始链接（溯源）
status: mature             # 成熟度 seed/developing/mature
created: 2026-06-20         # 创建时间
ingested: 2026-06-24        # 录入时间
related: ["[[项目门户]]"]   # 关联页面
---
```

**作用**：让 AI 先看标签筛选（快、准），再读内容；回答时能挂原文链接（可溯源）。

### projects/<代号>/ = 项目档案盒

每个项目一个统一结构的文件夹，所有资料按类型放进对应抽屉（docs/decisions/conversations/assets）。好处：结构统一、AI 友好、照抄即合规。

**创建方式**：`bash tools/kb-init.sh <项目代号>`（自动生成骨架 + _index.md）

---

# 第二部分：现状盘点

## 2.1 已完成（70%）

| 组件 | 完成度 | 功能 | 位置 |
|------|--------|------|------|
| **feishu-sync.py** | ✅ 100% | 飞书采集+去重+图片下载+简单frontmatter | 飞书同步工具包/ |
| **run-sync.sh** | ✅ 100% | 定时任务包装 | 飞书同步工具包/ |
| **安装.command** | ✅ 100% | 一键装环境+配定时任务 | 飞书同步工具包/ |
| kb-lint-fm.py | ✅ 100% | frontmatter 校验器 | tools/ |
| kb-init.sh | ✅ 100% | 项目骨架生成 | tools/ |
| kb-contract.yaml | ✅ 100% | type/字段/enum 契约 | meta/ |
| Claude 命令面板 | ✅ 100% | 7个 /kb-* 命令 | .claude/commands/ |
| 示例项目 | ✅ 100% | _example/ | projects/ |

**关键**：你的 `feishu-sync.py` 已经把「飞书采集」这一最难的环节做完了——递归拉取、docx转markdown、下载图片、去重、定时任务全有。

## 2.2 待补全（30%）

| 组件 | 状态 | 工作量 | 优先级 | 功能 |
|------|------|--------|--------|------|
| **kb-bridge.py** | ❌ 不存在 | 1-2天 | **P0** | 飞书markdown → 知识库知识页 |
| **Git 仓库部署** | ❌ 未建 | 半天 | **P0** | NAS Gitea 真相源 |
| **auto-sync.sh** | ❌ 不存在 | 半天 | **P0** | 整合采集+桥接的定时脚本 |
| nas-watch.py | ❌ 不存在 | 1天 | P1 | 监控投递区自动采集 |
| feishu-render.py | ❌ 骨架 | 2天 | P1 | 推送到飞书多维表格 |
| pre-commit hook | ❌ 不存在 | 半天 | P1 | Git提交前自动校验 |

---

# 第三部分：完整流程图

## 3.1 采集与处理流程

```mermaid
graph TB
    A1[飞书文档] --> B{采集方式}
    A2[飞书群聊] --> B
    A3[NAS投递区] --> B

    B -->|手动| C1["/kb-ingest命令"]
    B -->|定时自动| C2["feishu-sync.py<br/>每天10:00"]
    B -->|实时监控| C3["nas-watch.py"]

    C1 --> D[kb-bridge.py<br/>桥接脚本]
    C2 --> D
    C3 --> D

    D --> E[AI分析<br/>Claude API]
    E --> F{判断type}

    F -->|决策| G1[projects/xxx/decisions/]
    F -->|文档| G2[projects/xxx/docs/]
    F -->|聊天| G3[projects/xxx/conversations/]

    G1 --> H[Git commit + push]
    G2 --> H
    G3 --> H
    H --> I[NAS Git仓库<br/>真相源]

    style C2 fill:#90EE90
    style D fill:#FFB6C1
    style E fill:#87CEEB
    style I fill:#FFD700
```

## 3.2 数据存储拓扑

```mermaid
graph LR
    subgraph NAS
    A[Gitea Git仓库<br/>真相源]
    B[投递区]
    C[定时任务]
    end

    subgraph Mac
    D[工作副本]
    E[Obsidian]
    F[Claude Code]
    end

    subgraph 飞书
    G[飞书文档]
    H[多维表格展示]
    end

    G -->|feishu-sync.py| I[临时目录]
    I -->|kb-bridge.py| A
    B -->|nas-watch.py| A
    A <-->|git pull/push| D
    D --> E
    D --> F
    A -->|feishu-render.py| H

    style A fill:#FFD700
    style I fill:#FFB6C1
```

## 3.3 日常工作流时序

```mermaid
sequenceDiagram
    participant 飞书
    participant 定时任务
    participant feishu_sync
    participant kb_bridge
    participant Claude
    participant Git仓库

    Note over 飞书,定时任务: 每天10:00
    定时任务->>feishu_sync: 触发
    feishu_sync->>飞书: 扫描新文档
    飞书-->>feishu_sync: 返回docx
    feishu_sync->>feishu_sync: 转markdown+下图
    feishu_sync->>kb_bridge: 传markdown
    kb_bridge->>Claude: 分析+判断type
    Claude-->>kb_bridge: type/tags/要点
    kb_bridge->>kb_bridge: 生成完整frontmatter
    kb_bridge->>Git仓库: commit+push
```

## 3.4 三个关键位置

```
位置1：真相源（NAS Git仓库）
  http://192.168.0.101:3002/robert/company-kb
  作用：唯一权威版本，所有人 pull/push

位置2：工作区（你的Mac）
  ~/work/company-kb/
  作用：Obsidian编辑、Claude问答、Git提交

位置3：投递区（NAS共享文件夹）
  SynologyDrive-zhishiku/知识库投递区/
  作用：同事丢文件，监控脚本自动采集
```

---

# 第四部分：分阶段实施

## 阶段 0：环境准备（半天）

### 0.1 NAS 建 Git 仓库

```bash
# NAS 上（SSH/DSM终端）
cd /volume1/git/repos/robert/
git init --bare company-kb.git

# 本地 clone
cd ~/work/
git clone ssh://用户名@192.168.0.101/volume1/git/repos/robert/company-kb.git
cd company-kb/

# 推送现有知识库
cp -r "现有知识库路径"/* .
git add . && git commit -m "Initial commit" && git push
```

### 0.2 整合飞书工具

```bash
cd ~/work/company-kb/
cp "飞书同步工具包/feishu-sync.py" tools/
cp "飞书同步工具包/run-sync.sh" tools/
git add tools/ && git commit -m "Add feishu-sync" && git push
```

## 阶段 1：核心对接（1-2天，P0）

### 1.1 创建 kb-bridge.py

**作用**：把 feishu-sync.py 拉下来的 markdown，用 AI 分析后转成合规知识页。

**核心逻辑**：
```python
# 伪代码
for md_file in feishu输出目录:
    content = 读取(md_file)
    分析 = Claude_API分析(content)   # 判断type、提取tags、写description
    frontmatter = 生成完整frontmatter(分析, 契约)
    保存到 projects/<代号>/{分析.type对应目录}/
git commit + push
```

**安装**：
```bash
pip3 install anthropic pyyaml
export ANTHROPIC_API_KEY="你的Key"
cp kb-bridge.py tools/
```

### 1.2 测试完整流程

```bash
# 步骤1：拉飞书到临时目录
python3 tools/feishu-sync.py --folder ROOT --out /tmp/test --skip-big

# 步骤2：桥接处理到知识库
python3 tools/kb-bridge.py --input /tmp/test --project wanniu-l1

# 步骤3：校验
python3 tools/kb-lint-fm.py projects/wanniu-l1/
# 期望：错误 0 | 警告 0

# 步骤4：推送
git add . && git commit -m "Test ingest" && git push
```

### 1.3 创建统一定时脚本 auto-sync.sh

```bash
#!/bin/bash
# 1. 拉飞书 → 临时目录
python3 tools/feishu-sync.py --folder ROOT --out /tmp/sync-$(date +%s) --skip-big
# 2. 桥接 → 知识库
python3 tools/kb-bridge.py --input /tmp/sync-* --project auto
# 3. 清理临时目录
rm -rf /tmp/sync-*
```

### 1.4 配置定时任务

```bash
# NAS cron 或 Mac crontab
0 10 * * * cd ~/work/company-kb && git pull && bash tools/auto-sync.sh
```

## 阶段 2：验证（1天，P0）

- [ ] 手动跑 `bash tools/auto-sync.sh`，看日志
- [ ] 检查 projects/ 下是否有新知识页
- [ ] `python3 tools/kb-lint-fm.py` 全部通过
- [ ] Claude Code 里 `/kb-ask` 测试问答

## 阶段 3：锦上添花（P1，可选）

- **nas-watch.py**：监控投递区，文件一丢就处理（1天）
- **feishu-render.py**：推送知识库到飞书多维表格（2天）
- **pre-commit hook**：Git提交前自动校验（半天）

---

# 第五部分：日常使用

## 常用命令

```bash
# 创建新项目
bash tools/kb-init.sh <项目代号>

# 手动录入
/kb-ingest <项目代号> <飞书链接/文件>

# 查询知识
/kb-ask <问题>

# 校验知识库
python3 tools/kb-lint-fm.py   # 或 /kb-check

# 同步代码
git pull   # 拉最新
git push   # 推更新

# 查看统计
/kb-status
```

## 五种使用场景

| 场景 | 操作 |
|------|------|
| **查信息** | `/kb-ask 万牛会L1怎么安排的？` → AI答案+溯源 |
| **手动录入** | `/kb-ingest wanniu-l1 <飞书链接>` |
| **看自动同步** | `tail -100 sync.log` |
| **编辑知识** | Obsidian打开 → 改 → git push |
| **健康检查** | `/kb-check` → 报告缺字段/死链 |

---

# 第六部分：关键决策与FAQ

## 改造前 vs 改造后

**改造前（纯手工）**：打开飞书→复制→建md→手写12字段frontmatter→粘贴→commit，每篇5-10分钟，累且易错。

**改造后（自动化）**：每天10:00全自动采集+生成+提交，你只需 `git pull` 和 `/kb-ask`，每天0分钟。

## FAQ

**Q: API 会不会很贵？**
Sonnet约$3/百万token，每天10篇×2000字≈$0.12/天，月约$3.6，可接受。

**Q: 要不要上向量库/RAG？**
现阶段不用。文档明确 P5（~100源/几百页且定位不准）才考虑，Claude语义检索够用。

**Q: 定时任务失败怎么办？**
查 `sync.log`。常见：飞书登录过期（重新 `lark-cli auth login`）、API Key失效、Git冲突（手动pull）。

**Q: NAS和本地怎么同步？**
用 Git pull/push（可靠），不要用群晖Drive自动同步（易冲突）。

---

# 快速启动清单（3天跑通）

## Day 1：环境搭建
- [ ] NAS 建 Git 仓库
- [ ] 本地 clone 到 ~/work/company-kb/
- [ ] 推送知识库内容
- [ ] 整合 feishu-sync.py 到 tools/

## Day 2：核心对接
- [ ] 安装 kb-bridge.py + 配 API Key
- [ ] 测试：feishu-sync → kb-bridge → lint → push
- [ ] 创建 auto-sync.sh

## Day 3：定时与验证
- [ ] 手动跑 auto-sync.sh
- [ ] 配置定时任务
- [ ] /kb-ask 测试问答
- [ ] 记录问题准备优化

---

**核心结论**：你已完成最难的70%（飞书采集），只需补 kb-bridge.py（1-2天）就能打通全流程。建议先走「快速启动3天」验证价值，再决定是否补 P1 自动化。