English | 中文
输入一个人的书、文章、演讲、访谈与案例，输出一个可追溯、可推演的「人物方法论顾问」——一个 Web 应用。 它回答的不只是"这个人说过什么"，而是——按这个人的方法，他会怎么想。
市面上的"书籍问答"（RAG）能回答"书里说了什么"，但回答不了两类问题：
- 书外新问题——书里没有直接答案（如"这位企业家会怎么看 AI 取代工人？"）
- 决策咨询——"按这个人的方法，我该先看什么？"
Book2Advisor 用 Person Method Model（人物方法模型） 解决：先把人物语料编译成结构化的方法论骨架（原则 / 规则 / 案例 / 诊断路径 / 观点张力 / 思想演变），运行时再按骨架推演——书内困境直接引用，书外新问题按方法外推，并且逐条标注"书中依据 vs 方法推演"，杜绝幻觉引用。
- Method Transfer（方法迁移）：书中没有的新问题，也能按此人的方法论给出可追溯的推演——不依赖原文"恰好提到"，而是依赖对方法论的结构化理解。这是本项目与资料问答的本质区别，也是终极验证判据
- Evidence First（证据优先）：每条原则/规则绑定原文证据（E1-E5 分级，E5 = 多源印证），全部 quote 逐字可回原文核对——不编造"他说过"
- 引用 / 推演分离：答案中"他说过的"（带出处）与"按他方法推演的"（显式标注）严格区分，读者永远知道哪句是原话、哪句是推理
- 思想演变处理：观点张力（tensions）+ 思想时间线（evolution），早晚期观点冲突时按时间回答，不平铺矛盾
- 换人只换语料：Method Model 驱动，切换人物零代码改动——已用两位语料形态完全不同的人物（自传体 vs 内部讲话体）验证
- 可审计的推理链：每次回答输出 8 段 Method Trace（问题理解 → 诊断路径 → 方法定位 → 案例 → 证据 → 推演标注），每一步可回查
- 薄骨架设计：方法模型只保留高置信度方向性内容（每人物 16-28 条原则），不做全量规则引擎、不做纯 RAG——低成本、可维护、可审计
| 维度 | 通用 RAG | Book2Advisor |
|---|---|---|
| 书外新问题 | 无方法可依，只能拼凑相似片段 | Method Transfer：按方法论外推 |
| 引用可信度 | 检索相似段落，易断章取义、张冠李戴 | 原则 ↔ 证据绑定，E1-E5 分级，逐字可溯 |
| 观点冲突 | 相关段落平铺，自相矛盾不自知 | tensions + evolution 时间线处理 |
| 决策咨询 | 给"书中说法"，不给"该怎么办" | 完整决策链：诊断路径 → 方法 → 建议 |
| 人物辨识度 | 谁的书都答成同一套百科腔 | 诊断路径与原则组合体现人物差异（Method Differentiation） |
| 维度 | 长上下文直塞 | Book2Advisor |
|---|---|---|
| 成本 | 每问都吃全部语料（几十万字 token） | 语料预编译为薄骨架，运行时只定位相关原则 |
| 一致性 | 长输入下输出漂移、遗忘、幻觉 | Schema 约束 + 证据绑定 + 引用/推演强制分离 |
| 可审计性 | 黑箱，无法解释"为什么这么答" | 8 段 Method Trace 全程可查 |
book-to-skill（本项目 Book Compiler 层的参考）把书编译为 agent 可加载的技能文件。Book2Advisor 在其之上补上了方法论顾问缺失的三块：
- Person Method Compiler：多源融合（同义合并 / 跨源印证升级 / 冲突检测 / 思想演变）——单本书之外，访谈、演讲、案例统一进入模型
- Method Runtime：8 步推理链（问题分类 → 诊断路径 → 方法定位 → 案例检索 → 证据收集 → 推演 → 标注）——从"技能文件"升级为"完整推理引擎"
- 评估体系：40 题评估集 + 独立评分标准（rubric）+ 版本间回归对比 + Method Differentiation 验证——方法论的质量可量化、可回归
┌─────────────────────────────────────┐
书 / 文章 / 演讲 │ 编译通道（离线，确定性 pipeline） │
/ 访谈 / 案例 ────► │ Package Compiler → Person Method │
│ Compiler（同义合并/跨源印证/冲突检测） │
└──────────────────┬──────────────────┘
│ Person Method Model
┌──────────────────▼──────────────────┐
│ 运行时（Method Runtime） │
用户问题 ─────────► │ 问题分类 → 诊断路径 → 方法定位 → │
│ 案例检索 → 证据收集 → 推演 → Method │
│ Trace（8 段，LLM 推理） │
└─────────────────────────────────────┘
# 1. 克隆并安装依赖
git clone https://github.com/jweokk/Book2Advisor.git
cd book2advisor
pip install -r web/requirements.txt
# 可选：文档/语料转换回退器（convert.py 在 anydoc 不可用时自动回退）
# pip install markitdown
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env：DEEPSEEK_API_KEY（LLM API key，默认 DeepSeek）
# METHOD_MODEL（方法模型路径，必填——见步骤 3-5 编译生成）
# 换模型：LLM_BASE_URL / LLM_MODEL 环境变量（任意 OpenAI 兼容端点，默认 DeepSeek 不变）
# 3. 转换语料（书/文档 → markdown）
# 耗时参考：小文件秒级；1500 页大书约 4 分钟（convert.py 默认超时 600s，超长可设 CONVERT_TIMEOUT）
python3 scripts/convert.py <your-book.pdf> --person <person> --type book
# 4. 编译方法模型（语料 → 候选提取 → 融合 → Method Model，完整流程见 docs/COMPILING.md）
# 耗时参考：小语料（1-3 份）约 5-10 分钟；大语料（10+ 份 / 100 万+字）约 1-2 小时（LLM 调用为主，可断点续跑）
python3 scripts/extract_candidates.py --src data/sources/<person>/book --out /tmp/<person>-extract
# （融合汇总为 data/methods/<person>/<model>-v0.1.yaml，含三重验证门槛）
# 5. 校验（必须 exit 0）
python3 scripts/validate_schema.py data/methods/<person>/<model>-v0.1.yaml
# 6. 启动 Web 顾问
cd web && uvicorn app.main:app --host 0.0.0.0 --port 8000
# 或 Docker：docker compose -f web/docker-compose.yml up -d --build
# 7. 浏览器访问 http://localhost:8000 ，开始咨询方法模型编译好后，一条命令导出为 agent 可加载的人物咨询 skill：
python3 scripts/export_skill.py --model data/methods/<person>/<model>.yaml --out ~/.claude/skills/<person>-method
# 产物：SKILL.md + references/{principles,rules,cases,diagnostics}.md
# 安装：复制到 ~/.claude/skills/（Claude Code）、~/.hermes/skills/（Hermes）、~/.copilot/skills/ 等
# 立即体验：python3 scripts/export_skill.py --model data/methods/example/person-example-v0.1.yaml --out /tmp/example-method之后 agent 会在你问"<人物>会怎么看这个问题"时自动加载该 skill，按「书中依据 vs 方法推演」强制分离的方式回答（详见 docs/SKILL-EXPORT.md）。
两种蒸馏路径（编译人物模型时）：
- 脚本快速路径：
scripts/extract_candidates.py→scripts/merge_candidates.py（脚本自动调 LLM，默认 DeepSeek，可换模型）——见 docs/COMPILING.md - Agent 自主蒸馏：用自己的 agent + 任意 LLM 完成提取与融合（不依赖本仓库的 LLM 脚本）——见 docs/AGENT-DISTILLATION.md，或让 agent 加载
skills/book2advisor-compiler生成器 skill
CLI 方式：
python3 scripts/ask.py "你的问题"（自动加载 METHOD_MODEL）。 语料准入标准见 docs/CORPUS-STANDARD.md，编译全流程（提取/融合/三重验证/trigger/评估）见 docs/COMPILING.md。
评估（可选但强烈推荐）：建 evaluations/<person>/（复制 evaluations/example/ 模板并改写），跑四组评估——batch_ask.py --person <person> --model <model.yaml> --group core|lures|confusions|out-of-scope + score_answers.py --person <person> --group <group>（judge 模型独立于答题模型，双 agent 盲测）。详见 docs/COMPILING.md 第 6 节。
本仓库根目录的 AGENTS.md 会被 Claude Code / Codex / Copilot 等 agent 自动读取（项目定位、命令链、路径选择规则、硬约束都在里面）。两种用法：
① 最简：把仓库克隆到本地，在 agent 中打开该目录，直接说：
请按 AGENTS.md 的指引，用 skills/book2advisor-compiler 把我的语料
（路径：<你的语料目录>）编译成 <人物名> 的方法论顾问 skill。
② 复制这段话给你的 agent（无需先克隆，agent 会自己处理）：
请访问 https://github.com/Jweokk/Book2Advisor 并按其 AGENTS.md 指引工作：
1. 把 skills/book2advisor-compiler 安装为可用 skill（如复制到 ~/.claude/skills/，或按你的 skill 机制加载）；
2. 用它把以下资料编译成人物方法论顾问：<资料位置或粘贴内容>
3. 输出：方法模型 yaml（过 validate_schema）+ 导出的 <人物>-method skill。
agent 会自动：读 AGENTS.md → 按语料规模选路径（缺省自主蒸馏，大语料提示走脚本快速路径）→ 编译 → 校验 → 导出 skill。
core/ # 核心代码
runtime/ # 运行时：8 步推理链（ask.py / llm.py / prompts.py）
schemas/ # Person Method Model Schema（JSON Schema，9 类实体）
scripts/ # CLI：convert / extract_candidates / validate_schema / ask
# / gen_triggers / merge_triggers / batch_ask / score_answers
skills/ # 生成器 skill（book2advisor-compiler：agent 自主蒸馏指令）
templates/ # 咨询流程模板（export_skill 渲染进每份人物 skill）
data/methods/example/ # 示例方法模型（导出演示 + 测试 fixture）
web/ # Web Advisor：FastAPI + 原生前端（Method Trace 展示）
tests/ # pytest（真实 LLM 集成测试：运行时 / schema / 转换单测）
docs/ # 方法论文档（语料准入标准 / 编译指南）
data/
methods/ # 方法模型（无内置模型——具体人物模型需自行编译，见快速开始）
sources/ # 语料（版权内容，不随仓库分发）
evaluations/ # 评估集：example 模板（questions/ + rubric）+ 各人物的运行产物
Book2Advisor 在演进中吸收了「书/人 → AI 技能」方向两个开源项目的方法论，并结合自身的"可追溯 Web 顾问"形态做了独立改进：
借鉴 cangjie-skill（RIA-TV++ 流水线）
- principle.trigger 触发场景设计（scenes / signals / not_for 三段式）——解决"原则选不准"：方法定位优先按 trigger 匹配，not_for 防「万能原则」（名字沾边即乱入）误触发
- 三重验证（V2 预测力 / V3 独特性）——融合阶段显式门槛：淘汰"只能复述例子"与"普通聪明人也能说的常识"候选，1 重验证通过的降级为规则而非直接淘汰
- 压力测试三组制（诱饵题 / 混淆题）——评估不只测"答得好"，还测"会不会乱调用、会不会选错原则"
借鉴 nuwa-skill（女娲）
- 边缘诚实度（超范围题）——语料未覆盖的话题必须显式声明"此为方法外推"，斩钉截铁编造本人立场 = 0 分
- 双 agent 盲测评分——答题 agent 与评分 agent 分离（LLM 自评 skill 质量准确率仅约 46%），评分模型可独立指定
- 泛问识别（GENERAL_QA 分类）——概念讨论/闲聊不再被强行套用经营原则，改为礼貌引导用户补充具体决策场景
- 边界声明（coverage）——推演 prompt 强制对语料空白话题显式标注推断性质
独立改进（超越参考项目的部分）
- 交付形态：静态 skill 文件 → 可追溯的 Web 顾问（证据 E1-E5 分级、quote 逐字可回原文、引用/推演强制分离）
- Method Transfer：书外新问题按方法论结构化外推，输出可审计的 8 段 Method Trace
- 思想演变处理：观点张力（tensions）+ 时间线（evolution），早晚期观点冲突按时间回答，不平铺矛盾
- 换人只换语料：Method Model 驱动，双人物（自传体 vs 内部讲话体）零代码改动验证
- 评估四组化：core（正向质量）+ lures（诱饵，容错 0）+ confusions（选择唯一性）+ out-of-scope（边缘诚实度），题目/评分标准可回归对比
本项目在设计实现中参考了以下开源项目与工具：
- cangjie-skill — trigger 触发场景设计、三重验证门槛、诱饵/混淆压力测试（见上节）
- nuwa-skill — 边缘诚实度评分、双 agent 盲测、泛问识别、边界声明（见上节）
- book-to-skill — Book Compiler 层的主要参考：
structure-not-summary抽取规范、方法骨架轻量化、evidence 分层存储 - anydoc — 文档转换器（office/文本 PDF → markdown）
- markitdown — 回退转换器
- MinerU — 扫描型 PDF 转换
MIT