3

Task-22-项目档案按需读取

ila edited this page 2026-08-18 22:11:16 +08:00

Table of Contents

• 22 项目档案按需读取
• 背景与目标
• 最终方案
• 修改文件
• 验收结果
• 测试
• 相关提交
• 附带处理（不属于本工单范围）

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

22 项目档案按需读取

• 类型：重构
• 所属 Epic：无
• 所属 MVP / 版本：无
• 状态：已完成
• 日期：2026-08-18
• 验收通过：2026-08-18，确认人 ila
• Gitea 工单：#22
• Wiki 页面：Task-22-项目档案按需读取

背景与目标

AGENTS.md 原有一条无条件规则「开始工作前先阅读项目档案」。docs/00-project-profile.md 约 2100 tokens， 每个新任务都要重读一次且不命中 prompt cache，而实际高频使用的只有其中的常用命令表（6 行）。

目标是取消无条件读取、改为按明确触发条件按需读取，并把高频命令内联到 AGENTS.md， 在不删减项目档案任何内容的前提下降低每个任务的固定输入开销。

最终方案

与建单方案的差异：建单时预计需要同步更新 Wiki 页面 Development-Workflow，实施时核实发现 「开始工作前先阅读项目档案」这条规则只存在于 AGENTS.md:5，Development-Workflow 未涉及， 因此本任务不修改任何 Wiki 页面，范围相应缩小。该变化已记入工单需求变化记录。

实际实现：

1. AGENTS.md 开头规则改为无条件只要求阅读任务涉及目录的 AGENTS.md。
2. 新增一段说明项目档案的按需读取触发条件：需要环境、配置或凭据来源；需要确认目录边界； 需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。
3. 新增「常用命令」小节，内联 8 条常用命令，命令集合与 docs/00-project-profile.md 完全一致。

未改变任何安全红线、门禁、验收要求和项目档案本身。

修改文件

• AGENTS.md：改写阅读入口规则，新增按需读取触发条件与「常用命令」表。

验收结果

验收标准	结果
AGENTS.md 不再包含无条件阅读项目档案的要求，改为列出明确触发条件	通过
AGENTS.md 内含常用命令表，命令与 docs/00-project-profile.md 一致	通过（命令集合 diff 为空）
docs/00-project-profile.md 内容未被删改	通过（git diff 无输出）
Wiki 已更新并回读取得 revision，核心镜像已导出	不适用，本任务经核实无 Wiki 改动
python dev_scripts/check_harness.py --strict 通过	通过
python -m unittest discover -s tests -v 通过	通过（Ran 40 tests, OK）
python dev_scripts/sync_wiki_docs.py --check 通过	通过（Wiki 镜像检查通过）

测试

• 执行命令：python dev_scripts/check_harness.py --strict
• 结果：DevHarness 检查通过
• 执行命令：python -m unittest discover -s tests -v
• 结果：Ran 40 tests，OK
• 执行命令：python dev_scripts/sync_wiki_docs.py --check
• 结果：Wiki 镜像检查通过，14 个核心镜像全部一致
• 未验证部分：本次改动为规则文本，无法用自动化验证「Agent 是否真的少读了项目档案」， 该效果需在后续任务中人工观察。

相关提交

• 65ead42 refactor: 项目档案改为按需读取并内联常用命令 (#22)

附带处理（不属于本工单范围）

行尾归一提交 a59dd19 为独立的免工单格式化改动，见 AGENTS.md 第 2 节豁免条款。