# Code4History

**主题无关、可重复使用、以史料溯源为核心的历史研究模板（Codex + Markdown + Git）。**

## 起步

1. 根 `USERINFO.md` 是用户自填的**最高优先级本地配置文件**，初始**完全空白（0字节）**。可以记录全局偏好、研究协作规则或覆盖默认的教学门槛。请勿将隐私与凭证提交到公开仓库。
2. 根 `topic.md` 的 Q1—Q20 是具体研究项目的问答配置；**Q18** 模式默认为 `collaborative`，选择 `training` 后才执行严格训练。**Q19**（选题及大纲评分门槛）留空为95/100；**Q20**（逐段反馈字数）留空为50字，均可由用户填写其他有效数值，且可被 `USERINFO.md` 明确覆盖。
3. 运行 `python tools/doctor.py` 检查环境；从项目根目录启动 Codex。它会自动发现**唯一的** Codex 入口 `AGENTS.md`，无需 `agent.md`。
4. 用 `$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`](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](INTERACTION.md)，不需要后台程序或额外数据库。

## 避免防御性循环

本项目对**事实与引文**严格核验，但鼓励有证据依据的**历史解释**：研究问题可以先提出，论点可以暂定，正文不需要每段都撤回上句话。审计应集中在 `08_review/`，不是代替论文论证。Codex 必读 [`INTERPRETATION.md`](INTERPRETATION.md)。

在现有项目中快速纠偏的提示词见 [`QUICK_FIX.md`](QUICK_FIX.md)。
**避免无意义的学术腔与伪结论：**阅读 [`ARGUMENT_DENSITY.md`](ARGUMENT_DENSITY.md)。必要时让 Codex 执行一次删冗余编辑：同义反复直接删除，不为每条材料强行升华，也不因此开启新的审查循环。

**避免“一个证据一个结论”的流水账：**阅读 [`SYNTHESIS_AND_PROSE.md`](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/`：卡片模板。

## 命令

```bash
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`](MIGRATION.md)。仅把新 ZIP 覆盖旧文件不会自动删除退役的 `agent.md` 与旧 Skill 目录，可能发生名字冲突。

## 来源与分发

`history-writing-workflow-c4h` 依据用户上传的原 `history-writing-workflow-main.zip` 重写，**故意采用新名字以免与原版冲突**。修改说明见 [UPSTREAM.md](.agents/skills/history-writing-workflow-c4h/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`](UPGRADE_v0.7.md)。

升级到 v0.8 请查阅 [`UPGRADE_v0.8.md`](UPGRADE_v0.8.md)：新增交接区和 `interaction.py`，已有研究资料及未完成交接事项均必须保留。