# AGENTS.md

> [!IMPORTANT]
> **当前是文档治理基础阶段，不是已实现的清洗工具。**
>
> 1. 本仓库研究政务文档 PDF→Markdown 清洗问题；当前没有可运行实现。
> 2. 真实文档和外部数据默认只读，不修改、不复制、不提交。
> 3. 面向用户的说明使用简体中文；代码、命令、路径和标识符使用英文。
> 4. `AGENTS.md` 与 `CLAUDE.md` 是同步镜像，除第一行标题外正文必须一致。

## 0. 事实权威

发生冲突时，以对应的唯一权威为准，不把不同版本拼成新的说法。


| 事实类型              | 唯一权威                                     |
| ----------------- | ---------------------------------------- |
| 当前阶段与已经完成的工作      | 根目录 `README.md`                          |
| Wiki 分类、冻结规则与更新机制 | `research-wiki/README.md`                |
| 已批准的选择、权衡与否决方案    | `research-wiki/design/` 中对应编号记录          |
| 当前有效的清洗机制与原因      | `research-wiki/explanation/`；没有文档时就是尚未确定 |
| 参数、输入输出和运行行为      | 未来的代码与测试；代码无法表达的事实才进入 `reference/`       |
| 可复现的操作与排障步骤       | `research-wiki/guides/`                  |
| Agent 协作与执行规范     | 本文件及其同步镜像                                |


路径、参数、命令、指标口径和当前进度不得维护多个权威版本。发现冲突时，先确认权威，再修复过期内容。

## 1. 项目定位与当前阶段

`mdpolish` 是独立的清洗算法研究与治理仓库。它用于理解 PDF→Markdown 噪音、定义清洗边界、
比较候选方案并积累可复核证据。

当前只建立文档治理基础。源码目录、测试目录、依赖配置、命令行接口、规则格式和评估体系均未获批准、
也未实现。不得因为 README 中描述了目标，就把目标写成已经存在的能力。

本仓库的研究结论不会自动成为其他仓库的生产契约。跨仓落地必须在目标仓库重新评审并获得授权。

## 2. 数据与外部材料

已知外部真实材料位于 `/home/lihaoze/gov_test_data`。除非用户另行明确授权，执行以下边界：

- 真实文档、审核材料、历史产出和客户可识别内容只读；
- 不向外部数据目录回写清洗结果，不修改文件名和目录结构；
- 不把原文、软链接、大型结果或可还原客户信息的片段提交到本仓库；
- 读取外部仓库或数据不等于获得修改、发布或迁移它们的权限；
- 新增实验输出目录前，先在 design 中明确保存位置、保留周期与脱敏要求。

任何删除、覆盖、移动或公开真实材料的动作，都必须先得到用户对具体范围的明确确认。

## 3. 开始工作前

1. 阅读根目录 `README.md`、本文件、`research-wiki/README.md` 和相关 design；
2. 查看当前分支、工作区状态和最近提交，已有改动默认属于用户；
3. 区分当前事实、候选方案和未来目标；
4. 明确问题、输入范围、非目标、成功标准和验证方法；
5. 涉及真实材料时，再次确认只读来源、允许写入的位置和敏感信息边界。

不存在的命令、脚本、目录或测试不得当作可用能力引用。

## 4. 设计与确认门

以下事项实施前必须新增 design，并等待用户明确批准：

- 定义或改变清洗语义、规则优先级、误删容忍度和保真原则；
- 定义输入输出格式、统计口径、评估指标或标注方法；
- 创建源码/测试/实验目录，引入运行依赖或确定公共命令行接口；
- 改变 Wiki 分类、事实权威、数据边界或跨仓职责；
- 修改、删除、移动或公开真实数据和大型实验产出；
- 提交、推送、创建 PR、发布，或修改其他仓库与外部系统。

纯文档勘误、只读调查和已批准设计范围内的机械实施，不需要重复建立设计。

design 草稿可以在评审中修改；批准后冻结。决策发生变化时创建下一编号，用 `supersedes` 指向旧记录，
不回写历史让它看起来从未改变。

## 5. 未来实现的质量底线

当实现获得批准后：

- 正确性和正文保真优先于清洗率与性能；不确定内容默认保留；
- 清洗步骤应可追踪、可复现，并能解释每类修改的依据；
- 算法逻辑与文件读写分层，核心处理尽量保持确定性；
- 公共接口提供类型信息，复杂逻辑说明原因和不变量；
- 显式覆盖空文档、编码异常、OCR 重复、表格、图片、极端长度和幂等性；
- 不吞异常、不静默降级、不用放宽断言掩盖失败；
- 未经真实证据支持，不把局部样本结果概括为一般结论。

这些是未来实施约束，不表示当前已经存在任何代码或测试。

## 6. 文档规则

完整分类规则以 `research-wiki/README.md` 为准：

- `design/`：动工前的选择、代价与否决方案；批准后冻结；
- `explanation/`：当前有效机制及原因；事实变化时更新；
- `reference/`：代码无法完整表达的稳定查询事实；
- `guides/`：经过实际验证的操作步骤；
- `scratch/`：调研、计划和未收敛草稿，不作为当前事实引用。

新文档从实际问题或读者可观察的现象开始，写清理由、适用边界、代价和验证状态。
易漂移的路径、参数、命令和指标只链接到唯一权威，不复制出第二份。

## 7. 验证与报告

- 只报告本轮真实执行过的检查；未运行或无法验证的内容明确写“未验证”；
- 声称完成前检查实际目录、文档镜像、Git diff 和工作区状态；
- 未来实验必须能追溯输入范围、版本、参数、环境、指标和输出位置；
- 性能结论同时记录数据规模、运行条件、计时范围和重复次数；
- 区分“实现可运行”“指标改善”和“适合生产”，三者不能互相替代。

当前有效的基础检查命令只以根目录 `README.md` 为准。

## 8. Git 与文件操作

- 已有改动默认属于用户，不覆盖、不回滚、不混入无关变更；
- 不执行 `git reset --hard`、`git checkout --` 等不可恢复操作；
- 删除前确认具体目标，优先保证可从 Git 或备份恢复；
- 提交前检查 staged diff、敏感信息、大文件和验证结果；
- 未经用户明确要求，不提交、不推送、不创建 PR、不发布；
- 不在提交信息、源码或文档中添加 AI 署名。

## 9. 沟通与协作

- 像同事协作一样，用直接、可读的中文说明判断、变化和风险。要用人话讲解！别创造黑话，别堆积信息密度极大的长难句！
- 问什么答什么，一次聚焦当前问题，不把未经请求的后续工作一起推进；
- 能在授权范围内安全判断的事项直接完成；会改变范围或契约的选择交给用户；
- 进度和最终报告必须对应真实工具输出，不把计划描述成结果；
- 不输出内部思维链，只提供可复核的依据、实际变更和验证结果。