LazyCharles07/textbook-weaver

textbook-weaver —— 多源教材合编与校验

把若干部同主题教材（不同版本、不同侧重）合编为一部 LaTeX 新教材，并配一份与教材印刷题号逐一对应的习题解答。
要求：可追溯（每处内容能指回源书与页码）、可复核（关键数值可独立重算）、可检查（机械门禁 + 换人复核）、可付印
（版面、字体、书签、空白页）。

用户的常规操作只有两步：把资料放进一个目录、在会话里提出需求。安装、页码偏移实测、配置写入、门禁执行与
错误修复均由助手完成。本文档中的命令是助手与 CI 的等价入口。

版本状态（0.1.0，2026-09-22）

已验证：

- 四家 harness 的接入与功能验收：Claude Code 2.1.270、Codex 0.154.0-alpha.6.2、DeepSeek Harness 0.1.0-rc.6、Pi 0.87.0。
- DeepSeek Harness 上的目标驱动无人值守：两节解答自主完成，覆盖率门禁退出码 0，使用子代理。
- 读图（扫描件页码确认、逐页读图提纲要）：需要模型支持图像输入（多模态），四家均实测通过；
换成支持图像的模型即可，换法见验收报告。

未验证或需注意：

- MCP 工具服务与 Pi 扩展包默认不挂载（可选路径，见手册 §4）。
- 无人值守的范围由目标的判据决定：判据为「覆盖率门禁通过」时，不含编译、机械审计、付印终检与抽查。
- 成本量级：接入一本书约 1–2 次短会话；每节解答约 2 次模型调用（撰写 + 复核）。

完整验收记录、四维审查与残留风险见 docs/ACCEPTANCE-REPORT.md。

快速开始

git clone https://github.com/LazyCharles07/textbook-weaver.git
cd textbook-weaver

python install.py --yes                          # 1) 全局安装（不带 --yes 为预览）
python init.py --book  --yes  # 2) 生成配置、习题清单与解答骨架
python core/tools/check_installs.py              # 3) 接入自检（0 缺口即就绪）

之后在任何项目中调用：/textbook-weaver 。四家命令名相同，但提供方式不同——Claude Code 与
DeepSeek Harness 由技能提供，Codex 与 Pi 由提示词模板提供（对照表见
QUICKSTART.md §1）。不用助手时，等价命令为
python core/tools/run_pipeline.py --config config.toml --stage gates。

- 接入与常用口令：QUICKSTART.md
- 九类现实难题的处理方式：docs/SCENARIOS.md
- 配置字段、排错、工具速查、FAQ：docs/REFERENCE-MANUAL.md

仓库结构

| 层 | 内容 | 面向 |
|---|---|---|
| 内容层 core/ | 方法论 11 篇、角色提示词 14 份、体例与流程模板 5 份、LaTeX 模板 7 份、Python 工具 21 个、自撰演示工程 | 任何 harness、任何操作系统；也可纯手工使用 |
| 扩展层 extensions/ | 三个 TypeScript 包：MCP 工具服务、DeepSeek Harness 插件、Pi 扩展 | 需要「工具进原生列表 + 自动门禁」的生态 |

本仓库只含方法与工具，不含任何教材内容。使用者需自备合法素材；合编产物属演绎作品，公开发布前请阅读
core/references/copyright-boundary.md。

core/                          内容真源（内容改动只在此处）
├── SKILL.md                   技能入口：任务路由表、八环节、三条硬规则
├── references/ (11)  prompts/ (14)  specs/ (5)  templates/ (7)
├── tools/                     21 个脚本 + demo 工程
├── workflows/PORTABLE-ORCHESTRATION.md
└── demo/                      自撰演示工程（1 章 2 节 8 题 + 图 + 解答 + 回归基线）
extensions/                    TypeScript 扩展（MCP / dsh 插件 / Pi 扩展）
adapters/                      四生态的清单与入口模板
dist/                          生成产物：四份自包含安装包（不进版本库）
build_adapters.py              生成 dist/；--check 校验同步性；--lint 校验布局
install.py / init.py           全局安装；为书稿建工程

设计要点

- 题号语义按 LaTeX 列表嵌套深度判定，唯一实现为 core/tools/textutil.py（\item[] 不占题号；同行
\begin{enumerate} 不得使深度为负）。
- 覆盖率门禁要求每节解答条数等于该节印刷题号数；多块习题节按组校验，不只校验总数。
- 解答复核由另一执行者重算完成，撰写者与复核者不得为同一执行者。
- 页码偏移逐本源书实测；无文字层的扫描件由能看图表的模型确认页码，无法确认时交由人工，工具不代拟。
- 全流程判据为脚本退出码：0 通过、1 发现问题、2 执行失败。

四生态安装

| 生态 | 最短路径 |
|---|---|
| Claude Code | /plugin marketplace add /dist/claude-code；或拷贝 dist/claude-code/skills/textbook-weaver 至 ~/.claude/skills/ |
| Codex | 将 dist/codex/AGENTS.md 放至项目根或 ~/.codex/AGENTS.md，dist/codex/prompts/*.md 拷至 ~/.codex/prompts/；MCP 见 dist/claude-code/mcp/ |
| DeepSeek Harness | dsh plugin --profile  add /dist/deepseek-harness；或拷贝 dist/deepseek-harness/skills/textbook-weaver 至发现根 |
| Pi | pi install /dist/pi；或拷贝 dist/pi/skills/ 与 dist/pi/prompts/ 至 ~/.pi/agent/ |
| 通用 | dist/shared/.agents/skills/textbook-weaver/ 放入项目或家目录的 .agents/skills/ |

扩展层可选。无扩展时，拷贝目录 + 执行脚本 + 手动门禁同样可用。四生态映射与跨平台说明见
PORTABILITY.md。

工具一览（core/tools/）

| 脚本 | 作用 | 关键点 |
|---|---|---|
| textutil.py | 题号语义唯一实现 | 按列表嵌套深度计数；\item[] 不占题号；同行 \begin{enumerate} 陷阱；自带回归自测 |
| inventory.py | 生成习题清单（冻结 schema） | 复现 LaTeX 节号计数器；产出撰写任务与解答章骨架 |
| gate_coverage.py | 覆盖率与体例门禁 | 条数 = 题数；多块节按组校验；禁用宏、占位符；--missing |
| gate_mechanical.py | 机械审计八项 | 目录一致、\label 完整与重复、来源标签、引用解析、图环境、占位符、术语变体 |
| build_gate.py | 编译门禁 | 编译并解析日志，输出可定位的错误报告 |
| pdf_preflight.py | 付印终检七项 | 版面尺寸、字体嵌入、断引用、书签、近空白页分类 |
| render_pages.py | 页 → PNG | 印刷页与 PDF 页的唯一换算点；未实测偏移时拒绝换算 |
| scan_intake.py | 扫描书接入 | 文字层判定；偏移自动判定（抽样投票）或多锚点交叉验证；产出 bookmap.json |
| page_slicer.py | 按节切页 + 读图工单 | 输出文件名统一用 PDF 页；offset=null 时拒绝换算 |
| coveragemap.py | 覆盖门禁两向检查 | 源书每节有落点或「未采用 + 理由」；成稿不含配置外的源书代号 |
| figure_inventory.py | 图 → label → 页码 | 必须显式给偏移 |
| overfull_report.py | 溢出 → 源文件:行 | 按 pt 降序；默认报告项，--strict-overfull 可升为门禁 |
| quality_scan.py | 解答质量启发式扫描 | 平均/最短字数、套话词、结论框缺失；软判据 |
| find_label_page.py | label 反查页码 | 只读 .aux |
| run_pipeline.py | 流水线编排 | --stage / --step / --dry-run / --watch / --strict-overfull |
| check_skill.py | 技能包自检 | frontmatter 合规、引用资源存在性、文档清点与实物双向一致 |
| check_portability.py | 可移植性自检 | 无生态专名、盘符路径、平台专有字体设置、裸相对路径 |
| check_installs.py | 接入自检 | 四家发现位置、已装副本与源逐文件 sha256、扩展构建新旧、CLI 位置与版本 |
| copyright_scan.py | 版权自检 | 禁用词取自使用者的配置 |
| selftest.py | 全链路自测 | 题号语义 → 清单基线回归 → 门禁 → 编译（教材与解答）→ PDF 终检 → 包自检 |

演示工程与验证

python "$PKG/core/tools/selftest.py"              # 全链路（含编译与 PDF 终检）
python "$PKG/core/tools/selftest.py" --skip-build # 未安装 XeLaTeX 时
python "$PKG/core/tools/run_pipeline.py" --stage all --dry-run
python "$PKG/core/tools/check_portability.py"
python build_adapters.py --check --lint

core/demo/ 自撰 1 章 2 节、8 道题，包含两类计数陷阱（\item 与 \begin{enumerate} 同行；小问另起一行）
与一条 \item[] 分组说明行。清单须与 core/demo/expected/inventory.json 逐字段一致，否则自测失败。

版权与许可

- 许可：方法、脚本、模板、扩展以 MIT 发布，见 LICENSE。
- 不含内容：无教材正文、习题、译文、成品 PDF 或扫描件；core/demo/ 为本项目自撰。
- 使用者责任：合编与配解答属演绎行为，公开发布、分发、付印前须依
core/references/copyright-boundary.md 确认授权。