Code4History
主题无关、可重复使用、以史料溯源为核心的历史研究模板（Codex + Markdown + Git）。
起步
- 根
USERINFO.md是用户自填的最高优先级本地配置文件，初始完全空白（0字节）。可以记录全局偏好、研究协作规则或覆盖默认的教学门槛。请勿将隐私与凭证提交到公开仓库。 - 根
topic.md的 Q1—Q20 是具体研究项目的问答配置；Q18 模式默认为collaborative，选择training后才执行严格训练。Q19（选题及大纲评分门槛）留空为95/100；Q20（逐段反馈字数）留空为50字，均可由用户填写其他有效数值，且可被USERINFO.md明确覆盖。 - 运行
python tools/doctor.py检查环境；从项目根目录启动 Codex。它会自动发现唯一的 Codex 入口AGENTS.md，无需agent.md。 - 用
$history-writing-workflow-c4h按三阶段九环节推进研究，并将证据与问题写入可持久化文件。所有目录都有readme.md说明用途和约束。
三个仓库级 Skill（已安装，无需联网）
| Skill | 何时用 | 路径 |
|---|---|---|
$history-writing-workflow-c4h |
正常的历史研究、阅读、论证、写作、审稿 | .agents/skills/history-writing-workflow-c4h/ |
$source-intake-c4h |
直接收到 PDF/书信/档案/扫描件，需要拆分内容归档 | .agents/skills/source-intake-c4h/ |
$discussion-to-topic-c4h |
先与 AI 自由讨论了选题，需要把决定填入 topic.md |
.agents/skills/discussion-to-topic-c4h/ |
对话转主题的用户步骤与可复制提示词参见 DISCUSSION_TO_TOPIC.md。摄入史料时先登记原件（SRC），再建转录、证据（EV）、问题（Q）、假说（H）、概念/人物/事件及冲突记录；不要把未经批判的一份来源直接当作论文结论。
人机共写交接区（v0.8）
upload/：直接放入report.pdf与可选的report.pdf.source.md（作者、出处、馆藏号、链接、版本、获取日期）。Codex 每轮检查，先按来源归档再按需提取证据；只有保存成功才移走待处理原件。requests/：把想交给 Agent 的任务写成独立 Markdown；完成后归档到requests/archive/。todo/：Agent 给你的具体问题或核对请求。在任务文件的“用户回复”下填写（自动识别为已回复），Agent 下轮会读取、落实到研究文件并归档。handoff/latest.md：打开即可查看本轮已做什么、哪些地方需要你的回答、下一步怎么推进。
从仓库根目录可运行 python tools/interaction.py scan 查看状态。每轮正式运行指令见 INTERACTION.md，不需要后台程序或额外数据库。
避免防御性循环
本项目对事实与引文严格核验，但鼓励有证据依据的历史解释：研究问题可以先提出，论点可以暂定，正文不需要每段都撤回上句话。审计应集中在 08_review/，不是代替论文论证。Codex 必读 INTERPRETATION.md。
在现有项目中快速纠偏的提示词见 QUICK_FIX.md。
**避免无意义的学术腔与伪结论：**阅读 ARGUMENT_DENSITY.md。必要时让 Codex 执行一次删冗余编辑：同义反复直接删除，不为每条材料强行升华，也不因此开启新的审查循环。
**避免“一个证据一个结论”的流水账：**阅读 SYNTHESIS_AND_PROSE.md。按共同问题把多个 EV 组织为 SYN-*，让段落之间真正形成对照、转折、因果或递进。词义和争议本身重要时，优先直接引用核对过的历史原话并分析；普通史实可转述。
python tools/new_item.py --kind synthesis --slug evidence-comparison 可以建立综合卡；10_templates/section-plan.md 可选用于策划小节逻辑。
主要文件
AGENTS.md：Codex 默认指令入口；启动先读USERINFO.md，再读框架、主题与状态。code4history.md：框架设计、目录关系、源流溯源、研究质量规范。topic.md：由用户填写的选题问答，不包含预置历史主题。USERINFO.md：空白全局覆写文件，只在用户自填后生效。STATE.md与00_governance/：进度快照、审批关口、研究日志、决策记录。01_sources/—08_review/：材料与研究过程；09_outputs/：构建产物；10_templates/：卡片模板。
命令
python tools/doctor.py
python tools/new_item.py --help
python tools/new_item.py --kind primary --slug archive-letter
python tools/new_item.py --kind evidence --slug source-statement
python tools/new_item.py --kind synthesis --slug cross-source-analysis
python tools/validate.py
python tools/assemble.py
python -m unittest discover -s tests -v
工具只依赖 Python 3.10+ 标准库。tools/validate.py 仅检查结构/引用关系，不能自动证明历史陈述、期刊创新性或研究伦理合格。
更新旧版项目
已经使用 v0.2 的用户请先阅读 MIGRATION.md。仅把新 ZIP 覆盖旧文件不会自动删除退役的 agent.md 与旧 Skill 目录，可能发生名字冲突。
来源与分发
history-writing-workflow-c4h 依据用户上传的原 history-writing-workflow-main.zip 重写，故意采用新名字以免与原版冲突。修改说明见 UPSTREAM.md。原始 ZIP 未见明确授权文件，公开再分发前请确认其版权条件。原始 PDF 与受版权限制资料默认不进入公开 Git 仓库，具体见 .gitignore 与各目录说明。
每个独立课题应创建自己的仓库副本，不覆盖旧研究；发布/投稿前应核对引文、版本、目标期刊要求及 AI 使用政策。
升级旧研究项目（v0.8）
使用 tools/migrate.py 导出研究数据并恢复到新模板，无需人工逐项复制。支持 v0.1—v0.6 研究项目，包括原始 PDF、topic.md、USERINFO.md、STATE.md、证据卡、论点、正文、日志及输出。默认保留旧项目，保护已修改的目标文件，旧框架个性化修改移入人工审阅区。详细命令见 UPGRADE_v0.7.md。
升级到 v0.8 请查阅 UPGRADE_v0.8.md：新增交接区和 interaction.py，已有研究资料及未完成交接事项均必须保留。