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

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

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

---

🎯 最终目标

一句话验证标准：

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 物理存储

验证：

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）

验证：

# 处理一个测试文件
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 返回答案 + 溯源链接

验证：

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

---

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

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

验证：

# 在投递区丢个新文件
cp 新文件.pdf 知识库投递区/

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

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

---

📋 分阶段实施计划

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

• NAS Gitea 真相源
• 本地 Git 工作副本
• 能 git push/pull

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

---

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

任务：

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

交付物：

• tools/kb-bridge.py（完整可运行）
• 依赖安装说明
• 使用文档

验证标准：

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 查询测试通过

验证标准：

/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

验证标准：

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 核心逻辑

#!/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 完成标准

# 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. 决定是否批量处理

---

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