AGENTS.md

Important

当前阶段与已实现范围只以根目录 README.md 为准。

本仓库是实验室共用的 Markdown 清洗研究与基础工具库；已有实现不等于完整清洗工具或生产能力。

真实文档和外部数据默认只读，不修改、不复制、不提交。

面向用户的说明使用简体中文，代码注释使用中文；代码、命令、路径和标识符使用英文。

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 是实验室共用的 Markdown 清洗研究与基础工具库。它用于理解 PDF、DOCX、OCR、网页等上游管线生成的 Markdown 噪音，定义清洗边界，比较候选方案并积累可复核证据。

当前阶段、已经完成的工作和实际能力边界只查阅根目录 README.md，不在本文件维护第二份进度清单。源码目录、测试目录、依赖配置、命令行接口、规则格式和评估体系都必须先经对应 design 批准后才能建立或改变；已经存在某个核心接口或单项组件，不表示完整规则集、文件适配、CLI、profile 或生产接口已经实现。

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

/home/lihaoze/work/mdpolish-wheel-pilot 是当前独立的项目端 wheel 消费测试仓库；除非用户明确授权，不要将其文件、测试数据或项目职责并入本仓库。

2. 数据与外部材料

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

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

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

3. 开始工作前

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

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

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. 沟通与协作

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

7.6 KiB Raw Blame History Unescape Escape