company-kb/完整落地链路.md

# 公司知识库完整落地链路（端到端）

> 从现状到最终可用的完整路径，不是散点方案
> 更新时间：2026-07-16 18:50

---

## 🎯 最终目标

**一句话验证标准**：
```bash
cd /知识库目录
/kb-ask 万牛会L1怎么安排的？
# AI 返回：根据 [[课程大纲v1]]（来源：飞书文档），万牛会L1...
```

---

## 📍 当前状态矩阵

| 组件 | 状态 | 位置 | 说明 |
|------|------|------|------|
| **知识库框架** | ✅ 完整 | company-kb-v0.1-mvp-20260707/ | 目录结构、契约、工具、命令都有 |
| **Git 真相源** | ✅ 已建 | http://192.168.0.101:3002/qianqian/company-kb | Gitea仓库，可push/pull |
| **本地工作副本** | ✅ 已建 | Synology Drive同步盘/company-kb/ | 就是知识库目录，有.git/ |
| **原始物料** | ⚠️ 未处理 | 飞书同步/（564文件）+ 会议记录/（4文件） | 没frontmatter，AI读不到 |
| **知识页** | ⚠️ 只有示例 | projects/wanniu-l1/（7页）+ _example/ | 真实内容很少 |
| **AI查询** | ⚠️ 能跑但没内容 | /kb-ask命令存在 | 能执行，但查不到东西（内容太少） |
| **自动化** | ❌ 不存在 | 无 | 飞书→知识库没有自动链路 |

---

## 🔄 完整数据流（端到端）

### 阶段 0：环境搭建（已完成✅）

```
NAS Gitea 真相源
  ↕ git push/pull
本地 company-kb/（工作副本）
  ↕ Synology Drive
NAS 物理存储
```

**验证**：
```bash
cd company-kb目录
git status  # 能看到状态
git push    # 能推送
```

---

### 阶段 1：物料汇入（核心，当前卡在这里❌）

```
原始物料（飞书同步/、会议记录/）
  ↓ 
【处理脚本】kb-bridge.py
  ├─ 读取原始文件
  ├─ 提取文本（PDF用pdfplumber，CSV用pandas）
  ├─ 调用Claude API分析
  │  └─ 判断type（doc/decision/conversation）
  │  └─ 生成title、description、tags
  │  └─ 提炼关键内容
  ├─ 生成完整frontmatter
  │  ├─ type: doc
  │  ├─ title: ...
  │  ├─ source: 飞书文档
  │  ├─ source_link: file://...
  │  ├─ status: seed
  │  ├─ created: 2026-xx-xx
  │  └─ ingested: 2026-07-16
  └─ 保存到 projects/xxx/docs/或decisions/或conversations/
  ↓
合规知识页（.md + frontmatter）
  ↓
【校验】kb-lint-fm.py
  └─ 检查frontmatter是否符合契约
  ↓
【提交】git add + git commit + git push
  ↓
Git 真相源（Gitea）
```

**验证**：
```bash
# 处理一个测试文件
python3 tools/kb-bridge.py \
  --input "../飞书同步/AI内容反推工作流.csv" \
  --output projects/ai-workflow/docs/

# 检查
python3 tools/kb-lint-fm.py projects/ai-workflow/
# 期望：错误 0

# 查看生成的文件
cat projects/ai-workflow/docs/AI内容反推工作流.md
# 期望：有完整frontmatter + 内容

# 提交
git add projects/ai-workflow/
git commit -m "Add AI工作流文档（测试）"
git push
```

---

### 阶段 2：AI 查询（自然就能用✅）

```
你在本地工作副本
  ↓
cd company-kb目录
  ↓
/kb-ask 问题
  ↓
【Claude Code 执行】
  ├─ 扫描 projects/ 下所有 .md 文件
  ├─ 解析每个文件的 frontmatter
  ├─ 根据 type、tags 筛选相关文件
  ├─ 语义检索文件内容
  ├─ 综合答案
  └─ 挂 source_link（从frontmatter读取）
  ↓
AI 返回答案 + 溯源链接
```

**验证**：
```bash
cd company-kb目录
/kb-ask AI内容反推工作流是什么？
# 期望：AI能找到刚才生成的知识页，返回答案 + 溯源
```

---

### 阶段 3：自动化（可选，手动跑通后再建）

```
【定时任务】每天 10:00
  ↓
【扫描】知识库投递区/
  ├─ 发现新文件
  ├─ 调用 kb-bridge.py 处理
  ├─ lint 检查
  ├─ git commit + git push
  └─ 记录日志
  ↓
知识库自动更新
```

**验证**：
```bash
# 在投递区丢个新文件
cp 新文件.pdf 知识库投递区/

# 第二天看
cd company-kb目录
git pull
ls projects/  # 应该能看到新项目

/kb-ask 新文件里的内容
# AI能查到
```

---

## 📋 分阶段实施计划

### Phase 0：环境准备（已完成✅，今天）

- [x] NAS Gitea 真相源
- [x] 本地 Git 工作副本
- [x] 能 git push/pull

**用时**：已完成  
**交付物**：Git仓库可用

---

### Phase 1A：开发处理脚本（明天上午，3小时）

**任务**：
1. 创建 kb-bridge.py（核心脚本）
2. 实现功能：
   - 读取文件（支持 PDF、CSV、markdown）
   - 调用 Claude API 分析
   - 生成 frontmatter
   - 保存到 projects/

**交付物**：
- `tools/kb-bridge.py`（完整可运行）
- 依赖安装说明
- 使用文档

**验证标准**：
```bash
python3 tools/kb-bridge.py --input test.pdf --output projects/test/
ls projects/test/docs/test.md  # 文件生成
python3 tools/kb-lint-fm.py projects/test/  # 错误 0
```

---

### Phase 1B：测试处理流程（明天下午，2小时）

**任务**：
1. 选 5 个代表性文件测试：
   - 1 个会议记录 PDF
   - 1 个飞书同步 CSV
   - 1 个 markdown 文件
   - 1 个图片（测试 assets）
   - 1 个长文档（测试分段）

2. 逐个处理 → lint → git push

3. AI 查询验证

**交付物**：
- 5 个测试项目生成
- Git 提交记录
- AI 查询测试通过

**验证标准**：
```bash
/kb-ask 会议纪要里的决策
# AI能找到并回答

/kb-ask AI工作流
# AI能找到并回答
```

---

### Phase 1C：批量处理（明天晚上或后天，按需）

**任务**：
1. 批量处理所有 564 个飞书同步文件
2. 批量处理所有 4 个会议记录
3. 处理公司资产信息里的 md 文件

**方式**：
- 选项A：一次性全跑（API成本 ~$20-50）
- 选项B：分批跑（每天处理 50 个）
- 选项C：只处理重要的（手动挑选）

**交付物**：
- 所有原始物料变成知识页
- 全部 lint 通过
- 全部 git push

**验证标准**：
```bash
find projects/ -name "*.md" | wc -l
# 应该有几百个文件

/kb-ask 随机问题
# AI 能从大量知识页中找到答案
```

---

### Phase 2：飞书机器人打通（下周）

**任务**：
1. bot-v2（阿里云）clone 知识库
2. 配置定期 git pull
3. 群里 @机器人 → 调 /kb-ask → 回复

**验证标准**：
```
飞书群里：@机器人 万牛会L1怎么安排？
机器人回复：根据[[课程大纲v1]]（来源：飞书文档），...
```

---

### Phase 3：自动化（按需）

**任务**：
1. 创建定时任务脚本
2. 监控投递区新文件
3. 自动处理 + git push

**验证标准**：
- 丢个新文件到投递区
- 第二天自动出现在知识库
- AI 能查到

---

## 🔧 关键组件详细设计

### kb-bridge.py 核心逻辑

```python
#!/usr/bin/env python3
"""
知识桥接脚本：原始物料 → 知识页
"""
import anthropic
import yaml
import os
from pathlib import Path
import pdfplumber  # PDF提取
import pandas as pd  # CSV处理

def process_file(input_path, output_dir, kb_root):
    """处理单个文件"""
    # 1. 读取文件内容
    content = extract_content(input_path)
    
    # 2. 调用 Claude API 分析
    analysis = analyze_with_claude(content, input_path)
    # 返回：{
    #   "type": "doc",
    #   "title": "...",
    #   "description": "...",
    #   "tags": ["...", "..."],
    #   "key_points": "...",
    #   "project": "ai-workflow"  # AI建议的项目归属
    # }
    
    # 3. 生成 frontmatter
    frontmatter = generate_frontmatter(analysis, input_path)
    
    # 4. 生成内容（原文 + AI提炼）
    content_md = f"{frontmatter}\n\n{analysis['key_points']}\n\n## 原始内容\n\n{content}"
    
    # 5. 保存
    save_to_kb(content_md, analysis, output_dir, kb_root)
    
    return analysis

def extract_content(file_path):
    """提取文件内容"""
    ext = Path(file_path).suffix.lower()
    
    if ext == '.pdf':
        with pdfplumber.open(file_path) as pdf:
            return "\n".join(page.extract_text() for page in pdf.pages)
    
    elif ext == '.csv':
        df = pd.read_csv(file_path)
        return df.to_string()
    
    elif ext in ['.md', '.txt']:
        return Path(file_path).read_text()
    
    else:
        raise ValueError(f"不支持的文件类型：{ext}")

def analyze_with_claude(content, source_file):
    """Claude API 分析"""
    client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
    
    prompt = f"""分析这个文件，返回 JSON：

文件：{source_file}
内容（前5000字符）：
{content[:5000]}

返回格式：
{{
  "type": "doc|decision|conversation",  // 判断文档类型
  "title": "一句话标题",
  "description": "一句话描述",
  "tags": ["关键词1", "关键词2"],
  "key_points": "3-5条关键要点（markdown格式）",
  "project": "建议的项目代号（kebab-case）"
}}

判断规则：
- type=doc：外部文档、参考资料
- type=decision：决策记录、方案选择
- type=conversation：会议纪要、聊天记录
"""
    
    response = client.messages.create(
        model="claude-sonnet-3-5-20240620",
        max_tokens=2000,
        messages=[{"role": "user", "content": prompt}]
    )
    
    return parse_json(response.content[0].text)

def generate_frontmatter(analysis, source_file):
    """生成 frontmatter"""
    from datetime import date
    
    fm = {
        "type": analysis["type"],
        "title": analysis["title"],
        "description": analysis["description"],
        "tags": analysis["tags"],
        "timestamp": str(date.today()),
        "source": guess_source(source_file),  # 飞书文档/会议/NAS
        "source_link": f"file://{os.path.abspath(source_file)}",
        "status": "seed",
        "created": str(date.today()),
        "ingested": str(date.today()),
    }
    
    return "---\n" + yaml.dump(fm, allow_unicode=True) + "---\n"

def save_to_kb(content, analysis, output_dir, kb_root):
    """保存到知识库"""
    project = analysis["project"]
    type_dir = {
        "doc": "docs",
        "decision": "decisions",
        "conversation": "conversations"
    }[analysis["type"]]
    
    # 创建项目目录（如果不存在）
    project_dir = Path(kb_root) / "projects" / project
    if not project_dir.exists():
        # 用 kb-init.sh 创建骨架
        os.system(f"cd {kb_root} && bash tools/kb-init.sh {project}")
    
    # 保存文件
    output_path = project_dir / type_dir / f"{slugify(analysis['title'])}.md"
    output_path.write_text(content)
    
    print(f"✓ Saved: {output_path}")

if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", required=True, help="输入文件路径")
    parser.add_argument("--output", help="输出目录（可选，默认自动判断）")
    parser.add_argument("--kb-root", default=".", help="知识库根目录")
    args = parser.parse_args()
    
    process_file(args.input, args.output, args.kb_root)
```

---

## 📊 成本估算

### API 成本（Claude API）
- 每个文件处理：~$0.05-0.10（取决于大小）
- 564 个飞书文件：~$30-60
- 4 个会议记录：~$1-2
- **总计**：~$30-70

### 时间成本
- Phase 1A（开发脚本）：3 小时
- Phase 1B（测试）：2 小时
- Phase 1C（批量处理）：API调用时间 + 1小时监控
- **总计**：1-2 天

---

## ✅ 验收标准（怎么算完成）

### Phase 1 完成标准
```bash
# 1. 能处理各种文件
python3 tools/kb-bridge.py --input test.pdf  # 成功

# 2. 生成的文件合规
python3 tools/kb-lint-fm.py projects/  # 错误 0

# 3. AI 能查到
cd company-kb目录
/kb-ask 随机问题  # 能返回答案 + 溯源

# 4. Git 有记录
git log  # 能看到提交历史

# 5. 同事能用
# 同事 git pull → /kb-ask → 也能查到
```

---

## 🚨 风险与对策

### 风险 1：API 成本超预算
**对策**：先测试 10 个文件，评估成本，再决定是否全量处理

### 风险 2：AI 分析不准确
**对策**：Phase 1B 测试时人工核查，调整 prompt

### 风险 3：文件格式太复杂
**对策**：复杂文件先跳过，手动处理

### 风险 4：知识页太多，AI 检索不准
**对策**：先做到 P1（100页内），检索不准时再考虑 P4/P5（编译层/向量库）

---

## 📌 立刻开始（今晚或明天）

**今晚**：
1. 我生成完整的 kb-bridge.py
2. 你配置依赖（`pip3 install anthropic pdfplumber pandas pyyaml`）
3. 测试处理 1 个文件

**明天**：
1. 测试 5 个代表性文件
2. 验证 AI 能查到
3. 决定是否批量处理

---

**这次是完整链路，不是散点。你觉得清楚了吗？**