From 5821ea0d085522500928be7bf67d37bfb216e9ad Mon Sep 17 00:00:00 2001 From: ila Date: Tue, 25 Aug 2026 08:39:52 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=B2=BE=E7=AE=80=E5=8D=95=E4=BA=BA?= =?UTF-8?q?=E4=BB=BB=E5=8A=A1=E4=BA=8B=E5=AE=9E=E6=9D=A5=E6=BA=90=E5=B9=B6?= =?UTF-8?q?=E5=88=86=E7=BA=A7=E5=B7=A5=E7=A8=8B=E5=9F=BA=E7=BA=BF=20(#25)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/issue_template/task.md | 9 ++++ AGENTS.md | 44 +++++++-------- README.md | 13 ++--- dev_scripts/harness.py | 22 +++++--- docs/00-project-profile.md | 12 ++--- docs/01-workflow.md | 63 ++++++++++++---------- docs/02-architecture-and-code-map.md | 21 ++++---- docs/03-business-rules-and-glossary.md | 10 ++-- docs/05-common-changes.md | 6 +-- docs/07-new-project-documentation-setup.md | 22 ++++++-- docs/08-existing-project-adoption.md | 14 ++--- docs/09-product-requirements-overview.md | 10 ++-- docs/README.md | 14 ++--- tests/test_harness_docs.py | 22 ++++++++ 14 files changed, 174 insertions(+), 108 deletions(-) diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index ba355b9..29fbb0b 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -89,6 +89,15 @@ - [ ] 新增交付文档，受众与页面： - [ ] 需要目标岗位或客户代表验证：是 / 否；验证方式： +## 任务记录与可选快照 + +- 单次任务事实来源：当前 Gitea 工单正文与评论 +- [ ] 默认不创建任务快照 +- [ ] 用户明确要求专项快照；用途和范围： +- [ ] 项目专用规则要求任务快照；规则入口： + + + ## 验收标准 - [ ] diff --git a/AGENTS.md b/AGENTS.md index b4e6dc3..1527324 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent 开发规则 -本仓库采用 DevHarness 工作流：Gitea 工单是任务过程的事实来源，Gitea Wiki 是长期开发文档和任务归档的事实来源，Git 是代码与版本绑定资料的变更记录。`docs/` 默认保存核心 Wiki 的只读镜像，`docs/task/` 只保存人工按需导出的任务归档快照。人负责确认方案与验收，Agent 负责检查、实现、测试和留下证据。 +本仓库采用 DevHarness 工作流：Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的事实来源，Gitea Wiki 是长期开发文档的事实来源，Git 是代码与版本绑定资料的变更记录。`docs/` 默认保存核心 Wiki 的只读镜像，`docs/task/` 只保存人工明确要求的专项或历史兼容快照。人负责确认方案与验收，Agent 负责检查、实现、测试和留下证据。 开始工作前先阅读任务涉及目录中的 `AGENTS.md`。目录越深的规则越具体，但不得削弱上级安全规则。 @@ -17,9 +17,9 @@ | 运行单元测试 | `python -m unittest discover -s tests -v` | | 导出核心 Wiki 镜像 | `python dev_scripts/harness.py sync` | | 检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --check` | -| 创建任务归档 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | -| 增量导出任务归档 | `python dev_scripts/harness.py export` | -| 全量导出任务归档 | `python dev_scripts/harness.py export --all` | +| 创建可选任务快照 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | +| 增量导出已有快照 | `python dev_scripts/harness.py export` | +| 全量导出已有快照 | `python dev_scripts/harness.py export --all` | ## 1. 永久规则 @@ -35,7 +35,7 @@ 新功能、缺陷修复、重构以及任何用户可感知或改变程序行为的修改，必须先建立单元任务工单。 -以下小改动可以直接提交，不要求工单和任务归档： +以下小改动可以直接提交，不要求工单： - 只改错别字、注释或文档措辞； - 只做格式化、导入排序或不跨文件的内部变量改名； @@ -55,7 +55,9 @@ 6. 开始实施前检查分支和工作区，明确哪些现有改动不属于本任务。 7. 严格按工单范围实现；新发现的问题先记录，不顺手混入当前任务。 8. 执行与风险相称的测试，把关键结果和未验证部分更新到工单。实施过程中出现计划外、当前无法解除的问题时才标记“阻塞”。 -9. 长期核心文档必须先修改 Wiki、读取确认，再运行 `python dev_scripts/harness.py sync` 导出本地镜像；任务归档默认只更新 Wiki，不自动导出本地。不得直接编辑镜像后反向覆盖 Wiki。 +9. 只有长期事实变化时才修改 Wiki、读取确认，再运行 `python dev_scripts/harness.py sync` 导出本地镜像；没有长期文档影响时在工单说明原因并跳过 Wiki 同步。不得直接编辑镜像后反向覆盖 Wiki。 + +工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和文档影响；用户验收后再追加验收时间与结论，不重复覆盖或抄写已有证据。 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。 @@ -86,16 +88,16 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - `只分析`：只读检查并给出方案；不建单、不修改，停在等待确认。 - `建工单`：根据已确认方案创建单元任务工单；建单后停止，不修改代码。 -- `执行工单 #N`：检查工单和依赖，实施、测试、提交、归档、推送并回写证据；停在“待验收”。 +- `执行工单 #N`：检查工单和依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照；停在“待验收”。 - `建工单并做`：依次建单和执行，`建工单，做`、`建工单,做` 含义相同；停在“待验收”。 - `继续工单 #N`：核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查。 - `检查工单 #N`：只读核对范围、验收、测试和证据并输出报告；不自动修复。 - `同步文档`：读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档；不修改 Wiki、不自动提交。 - `导出任务归档`：人工触发 `python dev_scripts/harness.py export`，只导出新增或 revision 已变化的任务归档；不删除本地文件、不自动提交。 - `导出全部任务归档`：人工触发 `python dev_scripts/harness.py export --all`，读取并导出全部线上任务归档；不删除本地文件、不自动提交。 -- `#N 验收通过`：仅在用户明确验收后，更新 Wiki 归档、同步必要的核心文档、推送、同步父工单并关闭任务；不自动导出任务归档。 +- `#N 验收通过`：仅在用户明确验收后，在工单追加验收结论；按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档。 -方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 `#N 验收通过` 外，快捷指令不得关闭待验收工单。任务归档导出必须由用户明确提出，其他指令不得隐式执行。Gitea 工单不导出全文，`docs/task/` 只是可能不完整的 Wiki 任务归档快照。详细语义见 [开发工作流](docs/01-workflow.md)。 +方案未确认或前置依赖未满足时，实施类指令必须停在对应门禁；除 `#N 验收通过` 外，快捷指令不得关闭待验收工单。任务快照的创建和导出必须由用户明确提出或项目专用规则明确要求，其他指令不得隐式执行。Gitea 工单不导出全文，`docs/task/` 只是可能不完整的专项或历史兼容快照。详细语义见 [开发工作流](docs/01-workflow.md)。 ### 需求记录与流转 @@ -103,13 +105,13 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 工单中的目标、非目标、已确认方案、验收标准和文档影响构成确认后的正式任务需求。 - 影响范围、接口、数据、风险或验收的需求变化必须记录日期、内容、原因和用户确认；会改变已确认结果时先更新工单并等待再次确认。 - 不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据；包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。 -- 长期有效的产品需求、业务规则和系统边界进入对应 Wiki 主题页并导出核心 `docs/`；完成结果进入 Wiki 任务归档，仅在用户明确要求时导出 `docs/task/`。Gitea 工单全文不导出到仓库。 +- 长期有效的产品需求、业务规则和系统边界进入对应 Wiki 主题页并导出核心 `docs/`；单次任务的完成结果和验收保留在工单正文与评论。只有用户明确要求专项快照或项目专用规则要求时才创建 Wiki 任务快照并按需导出 `docs/task/`。Gitea 工单全文不导出到仓库。 详细记录边界见 [开发工作流](docs/01-workflow.md) 与 [业务规则和术语](docs/03-business-rules-and-glossary.md)。 ### 效率与范围控制 -本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 +本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。 #### 严格控制范围 @@ -161,19 +163,19 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 实现提交信息引用工单号，例如：`fix: 修复登录超时 (#123)`。 - 不为流程制造空提交。 - 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。 -- 不能验证的真机、生产、迁移或并发行为必须写入工单和归档。 +- 不能验证的真机、生产、迁移或并发行为必须写入工单；存在明确要求的任务快照时再同步记录。 -## 7. 完成、验收和归档 +## 7. 完成和验收 -1. 逐项完成验收、测试和实现提交，并把最终方案、差异、结果、提交及遗留问题写回工单。 +1. 逐项完成验收、测试和实现提交，在工单追加最终证据评论，记录最终方案、差异、结果、提交、遗留问题和文档影响。 2. 工单保持“待验收”，用户没有明确验收通过前不得关闭。 -3. 运行 `python dev_scripts/harness.py archive <编号> "<短标题>"`，只创建 Wiki 任务归档，不登记或导出本地镜像。 -4. 读取确认 Wiki，运行 `python dev_scripts/harness.py sync --check` 检查核心镜像，并把任务归档页面、revision 和提交哈希写回工单。只有用户明确提出时才增量或全量导出任务归档。 -5. 用户验收通过后关闭单元工单，并同步更新 MVP 和 Epic。 +3. 有长期文档影响时，读取确认 Wiki，运行 `python dev_scripts/harness.py sync --check` 检查核心镜像，并把页面 revision 和镜像提交哈希写回工单；没有长期文档影响时不运行 Wiki 同步。 +4. 用户验收通过后，在工单追加验收时间和结论，关闭单元工单，并同步更新 MVP 和 Epic；没有真实变化的 Wiki 不重复更新或检查。 +5. 默认不创建任务归档。只有用户明确要求专项快照或项目专用规则明确要求时，才运行 `python dev_scripts/harness.py archive <编号> "<短标题>"`；`export` 和 `export --all` 同样必须显式触发。 MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才能关闭 MVP。Epic 的全部范围完成后才能关闭 Epic。 -详细归档顺序和字段见 [开发工作流](docs/01-workflow.md)。 +详细证据回写、可选快照和文档同步边界见 [开发工作流](docs/01-workflow.md)。 ## 8. 可维护性 @@ -196,7 +198,7 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 - 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。 - 部署命令变化时，有常驻服务的项目更新自己的 `Deployment-and-Operations` 页面（由 [部署文档模板](docs/templates/deployment.md) 复制建立）；没有常驻服务的项目记录为无部署文档影响，不创建空的部署页。 - 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。 -- 必需核心页面及结构以 `python dev_scripts/harness.py check --strict` 和 [新项目文档初始化](docs/07-new-project-documentation-setup.md) 为准；稳定文档与任务归档的分工见 [开发工作流](docs/01-workflow.md)。 +- 必需核心页面及结构以 `python dev_scripts/harness.py check --strict` 和 [新项目文档初始化](docs/07-new-project-documentation-setup.md) 为准；稳定文档与可选历史快照的分工见 [开发工作流](docs/01-workflow.md)。 ## 9. 引导提交例外 @@ -208,9 +210,9 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 -- 长期开发文档以 Gitea Wiki 为事实来源，`docs/` 默认保存显式映射生成的核心只读镜像；`docs/task/` 是人工按需快照，可能不完整或不是最新状态。 +- 长期开发文档以 Gitea Wiki 为事实来源，单次任务证据以 Gitea 工单为事实来源；`docs/` 默认保存显式映射生成的核心只读镜像，`docs/task/` 是人工明确要求的专项或历史兼容快照，可能不完整或不是最新状态。 - 核心 Wiki 与镜像的固定顺序是：修改 Wiki → 读取确认 → 导出核心 `docs` → 校验差异 → 提交镜像。 -- 任务归档默认只保存在 Wiki；`导出任务归档` 或 `导出全部任务归档` 必须由用户明确提出，且不得自动传播删除或重命名。 +- 默认不创建任务归档；`archive`、`导出任务归档` 或 `导出全部任务归档` 必须由用户明确提出或项目专用规则明确要求，且不得自动传播删除或重命名。 - 同步配置只允许写入 `docs/` 下的 Markdown；发现镜像有未提交修改时必须停止。 - Gitea 凭据只通过进程环境或 MCP 安全配置提供，不得写入仓库。 - `dev_scripts/` 只存放 DevHarness 自身工具；业务项目的通用脚本必须使用独立目录，不得混放。 diff --git a/README.md b/README.md index e2ab1cb..4a63def 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,9 @@ DevHarness 是一个以 Gitea 工单管理任务过程、以 Gitea Wiki 管理 -> 创建 Epic / MVP / 单元任务工单 -> Agent 实现并测试 -> 提交代码并更新工单 - -> 人工验收 - -> 归档 Wiki；任务快照仅在人工提出时导出 - -> 关闭工单并更新父工单 + -> 工单集中回写最终证据并等待人工验收 + -> 人工验收后在工单记录结论 + -> 关闭工单并更新父工单；长期事实变化时才同步 Wiki ``` ## 快速开始 @@ -43,8 +43,8 @@ CLAUDE.md Claude Code 的规则入口 docs/00-project-profile.md Wiki 项目档案的只读镜像 docs/01-workflow.md Wiki 开发工作流的只读镜像 docs/02-07*.md 代码地图、业务、验证、修改、排错和初始化镜像 -docs/templates/task-archive.md Wiki 任务归档模板的只读镜像 -docs/task/ 人工按需导出的 Wiki 任务归档快照 +docs/templates/task-archive.md 可选 Wiki 任务快照模板的只读镜像 +docs/task/ 人工明确要求的专项或历史兼容快照 wiki-docs.json 核心 Wiki 页面到本地镜像的显式映射 dev_scripts/harness.py check / sync / archive / export 单一入口 dev_scripts/wiki_docs.py Gitea Wiki 客户端与镜像生成库 @@ -53,7 +53,8 @@ dev_scripts/wiki_docs.py Gitea Wiki 客户端与镜像生成库 ## 设计原则 - 人决定目标、范围和验收结果，Agent 负责检查、实现和验证。 -- 工单记录实施过程，Wiki 保存长期有效的最终事实，`docs/` 默认保存核心镜像；任务归档快照按需导出。 +- Gitea 工单是单次任务唯一事实来源；Wiki 保存长期有效事实，Git 保存代码和版本绑定资料，`docs/` 默认保存核心镜像。 +- 默认不创建任务归档；`archive`、`export` 和 `export --all` 只作为人工显式触发的兼容能力。 - 一个单元工单只解决一个可独立测试和回退的问题。 - 实现提交与必要的核心文档镜像提交分开，便于审查与追溯。 - 凭据、个人数据和生产数据不得进入代码、工单或归档。 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index 4275f9a..11f7466 100644 --- a/dev_scripts/harness.py +++ b/dev_scripts/harness.py @@ -1,10 +1,10 @@ """DevHarness 单一命令行入口。 子命令： - check 检查必需文件、核心文档和任务归档结构 + check 检查必需文件、核心文档和已有任务快照结构 sync 从 Gitea Wiki 单向导出或校验核心 docs 镜像 - archive 在 Gitea Wiki 创建任务归档 - export 人工按需把 Wiki 任务归档导出到 docs/task + archive 显式在 Gitea Wiki 创建可选任务快照 + export 人工按需把已有 Wiki 任务快照导出到 docs/task 各子命令的实现逻辑取自原来的 check_harness.py、sync_wiki_docs.py、 new_task_archive.py 和 export_task_archives.py，行为未改变。 @@ -85,7 +85,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "## 面向初级维护者的修改边界", "## 每个任务的文档影响", "## 需求记录与流转", - "## 稳定文档与任务归档", + "## 稳定文档与可选历史快照", "## 自然语言快捷指令", "## 效率与范围控制", "### 严格控制范围", @@ -125,6 +125,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "## 初始化顺序", "#### 需求总览启用条件", "### 2. 选择建设基线", + "#### 工程基线裁剪", "#### 判断案例", "### 3. 识别子项目与交付单元", "### 7. 确定交付对象和文档", @@ -306,6 +307,11 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "- [ ] 更新已有交付文档，受众与页面：", "- [ ] 新增交付文档，受众与页面：", "- [ ] 需要目标岗位或客户代表验证：是 / 否；验证方式：", + "## 任务记录与可选快照", + "- 单次任务事实来源：当前 Gitea 工单正文与评论", + "- [ ] 默认不创建任务快照", + "- [ ] 用户明确要求专项快照；用途和范围：", + "- [ ] 项目专用规则要求任务快照；规则入口：", ) for section in missing_sections(content, required): errors.append(f"单元任务模板缺少：{section}") @@ -325,7 +331,9 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "单元任务是唯一正式实施单位", "高风险修改必须停止", "用户没有明确验收通过前不得关闭", - "长期核心文档必须先修改 Wiki", + "只有长期事实变化时才修改 Wiki", + "Gitea 工单是单次任务需求、变化、实现、测试、提交和验收的事实来源", + "默认不创建任务归档", "### 新项目 Wiki 初始化门禁", "`Home` 不存在时必须先创建 `Home`", "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据", @@ -368,6 +376,8 @@ def check_repository_readme(errors: list[str], root: Path = ROOT) -> None: "`Home` 不存在时先创建并回读 `Home`", "本地 `docs/` 的存在不能证明线上 Wiki 已初始化", "python dev_scripts/harness.py sync --verify", + "Gitea 工单是单次任务唯一事实来源", + "默认不创建任务归档", ) for section in missing_sections(content, required): errors.append(f"README.md 缺少：{section}") @@ -698,7 +708,7 @@ def main() -> int: ) p_sync.set_defaults(func=run_sync) - p_archive = sub.add_parser("archive", help="在 Gitea Wiki 创建任务归档") + p_archive = sub.add_parser("archive", help="显式在 Gitea Wiki 创建可选任务快照") p_archive.add_argument("issue_number", help="Gitea 工单号，例如 123") p_archive.add_argument("title", help="简短任务标题") p_archive.add_argument( diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index 4fa00c7..41cb480 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Project-Profile.- -wiki_revision: dae88cec817721fe640aebba5c95842f812095c0 -synchronized_at: 2026-08-18T13:34:36Z +wiki_revision: 5a9d3e4ffa72ef7f10ee3480fbbf3820cbfce1c7 +synchronized_at: 2026-08-24T08:55:19Z # 项目档案 @@ -79,7 +79,7 @@ synchronized_at: 2026-08-18T13:34:36Z | 运行单元测试 | `python -m unittest discover -s tests -v` | 所有测试通过 | | 导出核心 Wiki 镜像 | `python dev_scripts/harness.py sync` | 核心页面写入 `docs/`，不处理任务归档 | | 检查核心 Wiki 镜像 | `python dev_scripts/harness.py sync --check` | 输出核心镜像与 Wiki 一致 | -| 创建任务归档 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | 只创建 Wiki 归档页，不写入本地 | +| 创建可选任务快照 | `python dev_scripts/harness.py archive 123 "修复登录超时"` | 仅在人工或项目规则明确要求时创建 Wiki 快照 | | 增量导出任务归档 | `python dev_scripts/harness.py export` | 只导出新增或 revision 已变化的任务归档 | | 全量导出任务归档 | `python dev_scripts/harness.py export --all` | 读取并导出全部线上任务归档 | @@ -89,13 +89,13 @@ synchronized_at: 2026-08-18T13:34:36Z |---|---|---| | `.gitea/issue_template/` | Gitea 工单模板 | 凭据、任务最终归档 | | `docs/` | Wiki 自动导出的只读镜像 | 人工直接维护的长期文档 | -| `docs/task/` | 人工按需导出的 Wiki 任务归档只读快照，可能不是完整历史 | 讨论过程和临时方案 | +| `docs/task/` | 人工明确要求后导出的专项或历史兼容快照，可能不是完整历史 | 默认任务记录、讨论过程和临时方案 | | `dev_scripts/` | Harness 检查、Wiki 同步和归档工具 | 产品功能代码 | | `tests/` | Harness 工具自动化测试 | 生产数据 | ## 环境、配置与凭据 -- 核心 Wiki 同步配置：仓库根目录 `wiki-docs.json`；任务归档不逐页登记，由按需导出工具动态发现。 +- 核心 Wiki 同步配置：仓库根目录 `wiki-docs.json`；可选任务快照不逐页登记，仅在显式归档或导出时动态发现。 - Gitea 地址可由配置提供，也可通过 `GITEA_URL` 覆盖。 - Gitea PAT 仅通过 `GITEA_TOKEN` 或 MCP 安全配置提供，不写入仓库。 - Token 至少需要读取仓库权限；创建或更新 Wiki 时还需要写仓库权限。 @@ -106,7 +106,7 @@ synchronized_at: 2026-08-18T13:34:36Z ## 项目专用验收要求 -- 长期核心文档必须先更新 Wiki，再导出本地镜像；任务归档默认只保存在 Wiki，用户明确要求时才增量或全量导出。 +- 只有长期事实变化时才更新核心 Wiki 并导出本地镜像；单次任务证据保存在工单，默认不创建任务归档，用户或项目专用规则明确要求时才创建或导出专项快照。 - 镜像必须包含来源页面、revision 和同步时间。 - 页面删除、重命名和映射变更必须人工确认。 - 新增核心文档时必须更新 Home、显式映射和 Harness 检查。 diff --git a/docs/01-workflow.md b/docs/01-workflow.md index 9568a97..daee964 100644 --- a/docs/01-workflow.md +++ b/docs/01-workflow.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Development-Workflow wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.- -wiki_revision: 98acbf90ebad7a515f1a805defe6d963e5153e48 -synchronized_at: 2026-08-19T01:51:50Z +wiki_revision: 5a79c3a71235e802484c8f5bd19bda37ccde8e46 +synchronized_at: 2026-08-24T08:55:25Z # 开发工作流 @@ -11,7 +11,7 @@ synchronized_at: 2026-08-19T01:51:50Z ## 事实来源边界 - Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。 -- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。 +- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。 - Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。 - 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。 @@ -133,41 +133,45 @@ Agent 检查分支和工作区，只修改工单范围内的文件。发现新 - Git 提交哈希； - 相关 Wiki 页面及 revision。 -长期核心文档遵循唯一顺序： +工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。 + +只有长期事实发生变化时才执行核心文档闭环： ```text 修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像 ``` -任务归档默认只更新 Wiki，不自动导出到 `docs/task/`。不得先编辑本地镜像再反向覆盖 Wiki。 +没有长期文档影响时，在工单写明原因并跳过 Wiki 更新、核心镜像同步和任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。 ### 4. 待验收 实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。 -### 5. 归档和关闭 +### 5. 待验收和关闭 -使用以下命令只在 Wiki 创建任务归档页： +实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。 + +用户明确验收通过后： + +1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据； +2. 关闭单元工单并勾选所属 MVP/Epic 子任务； +3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki； +4. 默认不创建或导出任务归档。 + +任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行： ```powershell python dev_scripts/harness.py archive 123 "修复登录超时" +python dev_scripts/harness.py export # 增量导出已有归档 +python dev_scripts/harness.py export --all # 全量导出已有归档 ``` -归档内容以 Wiki 页面为事实来源。默认不修改 `wiki-docs.json`，也不写入 `docs/task/`。把 Wiki 页面、revision 和实现提交哈希写回工单；用户明确验收通过后，关闭单元工单并勾选父工单中的任务。 - -只有用户明确提出时才导出任务归档： - -```powershell -python dev_scripts/harness.py export # 增量：新增或 revision 变化 -python dev_scripts/harness.py export --all # 全量：读取全部线上任务归档 -``` - -导出不得自动删除本地文件。`docs/task/` 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。 +可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 `docs/task/` 快照不自动删除、重命名或补齐。 ## 文档同步规则 - 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。 -- 任务归档不逐页登记映射，由按需导出工具根据 `Task-<编号>-<标题>` 动态发现；已有镜像优先按镜像头匹配原页面。 +- 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。 - 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。 - 镜像头必须记录页面名、页面地址、revision 和同步时间。 - 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。 @@ -228,20 +232,20 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 | 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 | | 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 | | 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` | -| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | 人工按需导出的 `docs/task/` 快照（可能不完整） | +| 完成后的实现、验证、遗留问题和验收 | Gitea 单元任务工单正文与评论 | 无；用户明确要求时可创建专项 Wiki 快照 | 任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。 -## 稳定文档与任务归档 +## 稳定文档与可选历史快照 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。 -- 工单和 Wiki 任务归档解释某次为什么修改、实际改了什么以及如何验证；本地任务快照不是完整历史。 -- 新人先读稳定主题页，只有追查历史原因时才读任务归档。 -- 任务产生的长期结论必须合并到主题页，不能只留在归档。 +- 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。 +- 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。 +- 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。 ## 效率与范围控制 -本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 +本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。 ### 严格控制范围 @@ -279,14 +283,14 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 |---|---|---| | `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 | | `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 | -| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” | +| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像 | 工单保持“待验收” | | `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” | | `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 | | `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 | | `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 | | `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 | | `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 | -| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，同步必要的核心文档，推送、同步父工单并关闭任务；不自动导出任务归档 | 工单“已完成”并关闭 | +| `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 | 补充边界： @@ -295,7 +299,7 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 - `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。 - `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。 - `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。 -- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存人工按需导出的 Wiki 最终任务归档快照。 +- Gitea 工单是单次任务唯一事实来源，不导出全文；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。 ## 什么时候重新确认方案 @@ -317,6 +321,7 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 | 讨论过程和临时方案 | 是 | 否 | 否 | | 实施进度和阻塞 | 是 | 否 | 否 | | 长期有效的最终方案 | 链接 | 是 | 镜像 | -| 测试结果与未验证内容 | 是 | 任务归档 | 按需镜像 | -| 提交哈希 | 是 | 任务归档 | 按需镜像 | +| 测试结果与未验证内容 | 是 | 否 | 否 | +| 提交哈希和验收结论 | 是 | 否 | 否 | +| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 | | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 | diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index d534d19..36adba4 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Architecture-and-Code-Map wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Architecture-and-Code-Map.- -wiki_revision: 5c8801853ca850e78dd920b7740b1d2b5dc528ad -synchronized_at: 2026-08-18T13:34:44Z +wiki_revision: ee55cd9499b6210b533f149b3eaf220903fa8045 +synchronized_at: 2026-08-24T08:55:28Z # 架构与代码地图 @@ -41,7 +41,7 @@ DevHarness 不是业务应用，而是一套开发工作流模板。它约束 Ag | Wiki 页面映射 | `wiki-docs.json` | `mappings` | 页面名、本地路径 | `harness.py sync --check` | 中 | | Wiki API 和镜像生成 | `dev_scripts/wiki_docs.py` | `WikiClient`、`sync_all` | 配置、页面、镜像元数据 | `tests/test_wiki_docs.py` | 中 | | 同步与校验 | `dev_scripts/harness.py` | `run_sync()` | `sync [--check] [--verify]` | 线上 Wiki 对照检查 | 低 | -| 任务归档 | `dev_scripts/harness.py` | `run_archive()` | `archive <编号> <短标题>` | 单元测试和正式归档 | 中 | +| 可选任务快照 | `dev_scripts/harness.py` | `run_archive()` | `archive <编号> <短标题>` | 单元测试和显式专项归档 | 中 | | Harness 结构检查 | `dev_scripts/harness.py` | `run_check()` | 必需文件、镜像、归档检查 | `check --strict` | 中 | | 本地文档镜像 | `docs/` | `docs/README.md` | 生成元数据和 Wiki 正文 | 同步检查 | 低 | | 自动化测试 | `tests/` | `test_wiki_docs.py` | 映射、同步和安全边界 | `unittest discover` | 低 | @@ -59,16 +59,17 @@ wiki-docs.json → --check 对照正文和 revision ``` -### 任务归档 +### 可选任务快照 ```text -读取 Wiki 归档模板 -→ 创建 Task-<编号>-<标题> 页面 -→ 追加显式页面映射 -→ 导出 docs/task 镜像 -→ 提交镜像并回写工单 +用户或项目专用规则明确要求专项快照 +→ 读取 Wiki 归档模板 +→ 创建 Task-<编号>-<标题> 页面并链接原工单 +→ 按需 export 到 docs/task ``` +默认任务流程不调用这条路径。单次任务的需求、实现、测试、提交和验收保存在 Gitea 工单；既有归档和导出功能仅用于历史兼容或明确的专项快照。 + ## 修改影响判断 | 修改内容 | 通常还要检查 | @@ -81,7 +82,7 @@ wiki-docs.json ## 不可破坏的边界 -- 工单管理过程，Wiki 管理长期文档，Git 管理代码和镜像。 +- 工单管理单次任务，Wiki 管理长期文档，Git 管理代码和版本绑定资料；可选任务快照不是默认事实来源。 - `docs/` 不是长期文档编辑入口。 - 同步只允许写入 `docs/` 下的 Markdown。 - 页面删除、重命名和本地脏镜像不能被静默处理。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index 95ea1cf..77796d0 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Business-Rules-and-Glossary wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Business-Rules-and-Glossary.- -wiki_revision: f78f2f92f563ec8dce5e399d4ee2b37896fa98dd -synchronized_at: 2026-08-10T03:51:38Z +wiki_revision: b03332bbf337d58428c2b9617a954c421a454882 +synchronized_at: 2026-08-24T08:55:34Z # 业务规则与术语 @@ -46,8 +46,10 @@ synchronized_at: 2026-08-10T03:51:38Z - 建立后续工单不要求已有工单全部完成；实施前必须检查工单声明的前置依赖。 - 前置工单未完成且存在实际依赖时保持“待实施”；允许并行时必须写明原因。 - 需求、接口、数据、安全边界或验收标准变化时先更新工单。 -- 工单只保存关键原始需求、确认后的正式需求和重要变化，不保存完整聊天或 Agent 内部推理。 -- 长期有效的产品需求和业务规则进入 Wiki；Gitea 工单全文不导出到本地。 +- 工单正文保存关键原始需求和确认后的任务基线；重要变化、最终证据和验收结论通过评论追加，不保存完整聊天或 Agent 内部推理。 +- 单次任务需求、实现、测试、提交和验收以 Gitea 工单为唯一事实来源；默认不创建 Wiki 任务归档。 +- 长期有效的产品需求和业务规则进入 Wiki；只有长期事实变化时才执行 Wiki 更新和镜像同步，Gitea 工单全文不导出到本地。 +- 用户明确要求专项快照或项目专用规则要求时可以创建 Wiki 任务快照；它不替代原工单，既有归档不删除。 - 长期文档必须先修改 Wiki，再导出本地镜像。 - 测试结果必须真实；未执行的验证必须明确记录。 - 用户未明确验收前，工单保持开启。 diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md index 7851e21..3c1c975 100644 --- a/docs/05-common-changes.md +++ b/docs/05-common-changes.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Common-Changes wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Common-Changes.- -wiki_revision: f3bc14df51d06393466ab49a1e5f490a21d6d8b3 -synchronized_at: 2026-08-18T13:34:51Z +wiki_revision: be03ec592df2d491cbc576001f0dda1bbbd39f7e +synchronized_at: 2026-08-24T08:55:46Z # 常见修改指南 @@ -20,7 +20,7 @@ synchronized_at: 2026-08-18T13:34:51Z | 中风险 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员理解差异并执行验证 | | 高风险 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 | -“代码行数少”不等于低风险。 +“代码行数少”不等于低风险。风险等级只决定由谁实施和验证，不改变建单门禁：新功能、缺陷修复、重构及行为变化仍需工单；只有 AGENTS.md 明确列出的非行为修改和纯显示文案豁免可以直接提交。 ## 修改 Wiki 文案 diff --git a/docs/07-new-project-documentation-setup.md b/docs/07-new-project-documentation-setup.md index fc3e013..53c41de 100644 --- a/docs/07-new-project-documentation-setup.md +++ b/docs/07-new-project-documentation-setup.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: New-Project-Documentation-Setup wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/New-Project-Documentation-Setup.- -wiki_revision: 581e2e04edbe7b34d62482e45aa0e4548960d93d -synchronized_at: 2026-08-19T01:52:06Z +wiki_revision: 49985341fad6947b93c3b83ee6046dc56c1110e6 +synchronized_at: 2026-08-24T08:55:52Z # 新项目文档初始化 @@ -48,6 +48,20 @@ synchronized_at: 2026-08-19T01:52:06Z 采用开源基线时，在 Project-Profile 的“技术栈与运行环境”记录上游项目名称、仓库地址、基线版本或提交、许可证、保留能力、定制范围和上游升级策略。尚未确认的候选和取舍先写入首个技术方案工单，不得把假设写成项目事实。 +#### 工程基线裁剪 + +所有项目采用最小工程基线，不按项目规模免除事实和验收要求： + +- 用完整 Git commit 和核验日期固定“当前事实”的代码基线； +- 分开记录“当前已经实现什么”和“目标规范要求什么”，不得用目标描述宣称现有能力； +- 写明证据路径、可确认行为、未覆盖范围和证据不能证明什么； +- 明确目标、非目标、安全边界和可判定的验收标准； +- 跨子项目接口或契约指定唯一事实来源和各端验证命令。 + +当前事实以指定 commit 的代码、可执行测试和运行证据为依据；目标行为以人工批准的契约、ADR 和业务规则为依据。两者冲突时登记为带编号的差距或缺陷，不允许现有错误实现覆盖目标规范，也不允许目标设计冒充当前实现。 + +出现跨团队或跨仓库协作、外部交付、接口或状态机复杂、权限安全、迁移并发、明显文档漂移等情况时，采用增强工程基线：按需增加 GAP-ID 差距表、带状态的 ADR、接口与数据契约、需求追踪测试矩阵，以及 PR、RC、Definition of Done 分层门禁。SRS、SAD、安全、运维和测试文档按风险与读者选择，不强制小型单人项目建立完整文档集。 + #### 判断案例 以下案例用于说明判断方式，不代表必须选择某种技术或具体开源项目。 @@ -108,7 +122,7 @@ synchronized_at: 2026-08-19T01:52:06Z ### 5. 修改镜像配置 -把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射，任务归档不逐页登记。 +把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射。可选任务快照不逐页登记，默认任务流程不创建。 确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 `docs/task/` 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。 @@ -187,7 +201,7 @@ python dev_scripts/harness.py sync --verify python -m unittest discover -s tests -v ``` -只有线上 Wiki 确认后才导出核心 `docs/`。任务归档默认不导出；用户明确要求时再运行 `python dev_scripts/harness.py export` 或加 `--all`。旧项目的任务归档快照不能带入新项目历史。 +只有线上 Wiki 确认后才导出核心 `docs/`。默认不创建或导出任务归档；用户明确要求专项快照时才运行 `archive`、`export` 或 `export --all`。旧项目的任务归档快照不能带入新项目历史。 `harness.py sync --check` 会在线读取全部显式映射页面；任一页面不存在、无法读取或 revision 与镜像不一致时，初始化不通过。只有上述命令全部成功后才允许开始产品代码。 diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md index 353dbfa..aacef33 100644 --- a/docs/08-existing-project-adoption.md +++ b/docs/08-existing-project-adoption.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Existing-Project-Adoption-Guide wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Existing-Project-Adoption-Guide.- -wiki_revision: 2ef3d7cd26874f652e9bfab2a5c2f6c8273ab7ac -synchronized_at: 2026-08-16T11:50:18Z +wiki_revision: 3575ecb437d5a7eac4073b0ad3e162da8b5c1100 +synchronized_at: 2026-08-24T08:55:55Z # 已有项目接入 DevHarness 指南 @@ -23,7 +23,7 @@ synchronized_at: 2026-08-16T11:50:18Z | 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 | | 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 | | Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 | -| 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 | +| 任务证据 | Gitea 工单；任务快照仅显式按需创建 | 保留已有工单；不复制 DevHarness 或其他项目的历史归档 | | 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 | 从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。 @@ -71,7 +71,7 @@ Agent 在提出方案前只读检查： - 多个应用共同完成一条产品或业务链路； - 由同一团队维护，仓库权限基本一致； - 接口变更需要在一个工单中同步修改或验证多端； -- 共享契约、业务规则和任务归档放在一起更容易保持一致； +- 共享契约和业务规则由同一项目维护并指定唯一事实来源； - 仓库体积、测试时间和工具性能尚未明显影响开发； - 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。 @@ -131,7 +131,7 @@ Agent 在提出方案前只读检查： ### 7. 提交和验收 -提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。 +提交只包含当前接入工单相关文件。在工单评论集中记录测试、未验证部分、提交哈希，以及真实变化的 Wiki revision 或“无长期文档影响”；保持工单“待验收”，等待用户明确验收后再关闭。默认不创建任务归档。 ## 后续升级 @@ -210,8 +210,8 @@ Agent 在提出方案前只读检查： 严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、 任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出 -本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持 -为“待验收”；未经我明确验收，不关闭工单。 +本地 docs 镜像。执行必要测试，提交实现并把最终证据回写工单，然后 +保持“待验收”；默认不创建任务归档，未经我明确验收不关闭工单。 ``` 路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md index dc825bc..a35304c 100644 --- a/docs/09-product-requirements-overview.md +++ b/docs/09-product-requirements-overview.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements-Overview wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Product-Requirements-Overview.- -wiki_revision: 8c1aeabb190c5b97b0c411f15dcab9fb3a3665e3 -synchronized_at: 2026-08-19T02:05:55Z +wiki_revision: 5fb2cfe4208a25f0a5c4cba6b94d688d6c8e5e30 +synchronized_at: 2026-08-24T08:55:58Z # 产品需求总览 @@ -21,7 +21,7 @@ synchronized_at: 2026-08-19T02:05:55Z | 项目目标、用户、范围和技术基线 | Project-Profile | 链接和一句话摘要 | | 长期功能需求、业务规则和系统边界 | 对应 Wiki 主题页 | 需求领域和详情链接 | | 单次实现范围、变化和验收标准 | Gitea 单元任务工单 | 工单编号和当前状态 | -| 已完成方案、测试和遗留问题 | Wiki 任务归档 | 验收入口 | +| 单次任务方案、实现、测试、遗留问题和验收 | Gitea 单元任务工单 | 工单链接；专项 Wiki 快照仅按需附加 | | 与版本绑定的原型、设计图或交互稿 | Git 中的 `design/` 或 `prototypes/` | 路径、版本和确认状态 | | 外部原型 | 原型平台 | 链接、版本或确认日期；重要版本保留可追溯快照 | @@ -31,7 +31,7 @@ synchronized_at: 2026-08-19T02:05:55Z | 需求领域 | 用户与场景 | 状态 | 版本 / MVP | 详细说明 | 实施工单 | 原型 | 验收入口 | |---|---|---|---|---|---|---|---| -| 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯 | 已交付（Wiki 初始化门禁） | 模板核心 | [开发工作流](Development-Workflow.-) | [#1](https://git.ilapage.cn/OPC/dev_harness/issues/1)、[#10](https://git.ilapage.cn/OPC/dev_harness/issues/10)、[#14](https://git.ilapage.cn/OPC/dev_harness/issues/14)、[#20](https://git.ilapage.cn/OPC/dev_harness/issues/20) | 无（流程文档） | [#1 归档](Task-1-Wiki-文档主源)、[#10 归档](Task-10-需求记录与流转规则)、[#14 归档](Task-14-任务归档按需导出)、[#20 归档](Task-20-Gitea-Wiki首页初始化硬门禁) | +| 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯且不重复归档 | 开发中（单人任务治理） | 模板核心 | [开发工作流](Development-Workflow.-) | [#1](https://git.ilapage.cn/OPC/dev_harness/issues/1)、[#10](https://git.ilapage.cn/OPC/dev_harness/issues/10)、[#14](https://git.ilapage.cn/OPC/dev_harness/issues/14)、[#20](https://git.ilapage.cn/OPC/dev_harness/issues/20)、[#25](https://git.ilapage.cn/OPC/dev_harness/issues/25) | 无（流程文档） | [#25](https://git.ilapage.cn/OPC/dev_harness/issues/25)；旧 Wiki 归档保留为历史证据 | | 初级维护者文档 | 初级程序员需要理解项目并处理简单修改 | 已交付 | 模板核心 | [项目档案](Project-Profile.-)、[代码地图](Architecture-and-Code-Map.-)、[常见修改](Common-Changes.-) | [#2](https://git.ilapage.cn/OPC/dev_harness/issues/2)、[#3](https://git.ilapage.cn/OPC/dev_harness/issues/3) | 无（流程文档） | [#2 归档](Task-2-Junior-Maintainer-Docs)、[#3 归档](Task-3-Dev-Scripts-Rename) | | Agent 范围、效率和 Claude 协作 | Agent 按确认范围实施并选择合适模型 | 已交付（原型 HTML 快照） | 模板核心 | [开发工作流](Development-Workflow.-)、仓库 `AGENTS.md` 和 `CLAUDE.md` | [#4](https://git.ilapage.cn/OPC/dev_harness/issues/4)–[#9](https://git.ilapage.cn/OPC/dev_harness/issues/9)、[#19](https://git.ilapage.cn/OPC/dev_harness/issues/19)、[#21](https://git.ilapage.cn/OPC/dev_harness/issues/21) | 无（流程文档） | 对应 `Task-4` 至 `Task-9` Wiki 归档；[#19 归档](Task-19-UI原型确认与文字修改双门禁)、[#21 归档](Task-21-Quant-UX原型本地HTML审核快照) | | 交付文档 | 其他岗位和客户需要与版本匹配的使用、部署或支持说明 | 待验收 | 模板核心 | [交付文档指南](Delivery-Documentation-Guide.-)、[岗位文档模板](Audience-Document-Template.-) | [#11](https://git.ilapage.cn/OPC/dev_harness/issues/11) | 无（文档模板） | [#11 归档](Task-11-交付文档指南与岗位文档模板) | @@ -52,7 +52,7 @@ synchronized_at: 2026-08-19T02:05:55Z - 唯一的详细 Wiki 页面； - 当前或主要实施工单； - 原型状态或明确写“无”； -- 已交付时的任务归档或验收入口。 +- 已交付时的 Gitea 工单验收入口。 需求正文、接口细节、业务规则和验收标准只在各自事实来源修改。本页使用一至两句话摘要并链接过去，不复制大段内容。 diff --git a/docs/README.md b/docs/README.md index 9b5ba22..6702bf7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Home wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Home -wiki_revision: 9eeda7d498edb029e8055eb8b3ac78ead630da2a -synchronized_at: 2026-08-18T13:34:34Z +wiki_revision: 4f5f2282034c784d0cc23fe3eb37f28815139612 +synchronized_at: 2026-08-24T08:55:15Z # DevHarness 文档中心 @@ -66,10 +66,10 @@ python dev_scripts/harness.py sync --check |---|---| | 任务状态、讨论、阻塞、验收过程 | Gitea 工单 | | 长期产品需求的统一导航和状态 | Gitea Wiki 的 Product-Requirements-Overview | -| 架构、业务规则、开发规范、操作手册、交付文档、任务归档 | Gitea Wiki | +| 架构、业务规则、开发规范、操作手册和交付文档 | Gitea Wiki | | 源码和与特定代码版本强绑定的文档 | Git 仓库 | | 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 | -| 完整任务归档 | Gitea Wiki；`docs/task/` 仅是人工按需导出的快照 | +| 单次任务需求、实现、测试和验收 | Gitea 工单；专项 Wiki 快照仅在人工明确要求时创建 | 本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。 @@ -81,7 +81,7 @@ python dev_scripts/harness.py sync --check - [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-) - [交付文档指南](Delivery-Documentation-Guide.-) - [岗位文档模板](Audience-Document-Template.-) -- [任务归档模板](Task-Archive-Template.-) +- [可选任务归档模板（兼容）](Task-Archive-Template.-) ## 同步原则 @@ -90,9 +90,9 @@ python dev_scripts/harness.py sync --check ``` - 核心页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射；普通同步不处理任务归档。 -- 任务归档默认只保存在 Wiki，只有用户明确提出时才增量或全量导出到 `docs/task/`。 +- 默认不创建任务归档；只有用户明确要求专项快照或项目专用规则要求时，才创建 Wiki 归档并按需导出到 `docs/task/`。 - 镜像头记录来源页面、Wiki revision 和同步时间。 - 已映射镜像存在未提交修改时同步必须停止。 - 页面删除、重命名和映射变更必须人工确认。 -- 核心 Wiki 或必要同步失败时，相关任务不能标记为完成；未请求任务归档导出不阻止任务完成。 +- 长期事实发生变化而核心 Wiki 或必要同步失败时，相关任务不能标记为完成；没有长期文档变化时不运行 Wiki 同步，未请求可选归档不阻止任务完成。 - 凭据、个人数据和生产数据不得进入 Wiki 或镜像。 diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 9de44a4..7a45d4e 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -92,6 +92,14 @@ class CoreDocumentTests(unittest.TestCase): self.assertIn("## 新项目 Wiki 初始化门禁", workflow) self.assertIn("#### 在线创建与回读门禁", setup) + def test_workflow_requires_issue_only_task_record(self) -> None: + workflow = CORE_DOCUMENT_REQUIREMENTS["docs/01-workflow.md"] + setup = CORE_DOCUMENT_REQUIREMENTS[ + "docs/07-new-project-documentation-setup.md" + ] + self.assertIn("## 稳定文档与可选历史快照", workflow) + self.assertIn("#### 工程基线裁剪", setup) + def test_existing_project_adoption_requires_upgrade_process(self) -> None: required = CORE_DOCUMENT_REQUIREMENTS[ "docs/08-existing-project-adoption.md" @@ -199,6 +207,20 @@ class TaskTemplateTests(unittest.TestCase): errors, ) + def test_task_template_requires_optional_snapshot_policy(self) -> None: + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + template = root / ".gitea" / "issue_template" / "task.md" + template.parent.mkdir(parents=True) + template.write_text("## 基本信息\n", encoding="utf-8") + errors: list[str] = [] + check_task_template(errors, root) + self.assertIn("单元任务模板缺少：## 任务记录与可选快照", errors) + self.assertIn( + "单元任务模板缺少：- [ ] 默认不创建任务快照", + errors, + ) + def test_task_template_requires_subproject_impact(self) -> None: with tempfile.TemporaryDirectory() as directory: root = Path(directory)