131 lines
7.4 KiB
Markdown
131 lines
7.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
> [!IMPORTANT]
|
||
> **当前阶段与已实现范围只以根目录 `README.md` 为准。**
|
||
>
|
||
> 1. 本仓库是实验室共用的 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` 是实验室共用的 Markdown 清洗研究与基础工具库。它用于理解 PDF、DOCX、OCR、网页等上游管线
|
||
生成的 Markdown 噪音，定义清洗边界，比较候选方案并积累可复核证据。
|
||
|
||
当前阶段、已经完成的工作和实际能力边界只查阅根目录 `README.md`，不在本文件维护第二份进度清单。
|
||
源码目录、测试目录、依赖配置、命令行接口、规则格式和评估体系都必须先经对应 design 批准后才能建立或改变；
|
||
已经存在某个核心接口或单项组件，不表示完整规则集、文件适配、CLI、profile 或生产接口已经实现。
|
||
|
||
本仓库的研究结论不会自动成为其他仓库的生产契约。跨仓落地必须在目标仓库重新评审并获得授权。
|
||
|
||
## 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. 沟通与协作
|
||
|
||
- 像同事协作一样，用直接、可读的中文说明判断、变化和风险。要用人话讲解！别创造黑话，别堆积信息密度极大的长难句！
|
||
- 问什么答什么，一次聚焦当前问题，不把未经请求的后续工作一起推进；
|
||
- 能在授权范围内安全判断的事项直接完成；会改变范围或契约的选择交给用户；
|
||
- 进度和最终报告必须对应真实工具输出，不把计划描述成结果；
|
||
- 不输出内部思维链，只提供可复核的依据、实际变更和验证结果。
|