From 0920621e7d273388dd082e7f3a3062dc2e7f2787 Mon Sep 17 00:00:00 2001 From: ila Date: Mon, 24 Aug 2026 16:05:01 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E7=AE=80=E5=8C=96=E5=8D=95=E4=BA=BA?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E5=B7=A5=E4=BD=9C=E6=B5=81=20(#48)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/issue_template/task.md | 10 +++ AGENTS.md | 52 ++++++------ README.md | 8 +- dev_scripts/harness.py | 23 +++-- docs/00-project-profile.md | 6 +- docs/01-workflow.md | 102 +++++++++++------------ docs/05-common-changes.md | 16 ++-- docs/08-existing-project-adoption.md | 14 ++-- docs/09-product-requirements-overview.md | 8 +- docs/README.md | 12 +-- docs/templates/task-archive.md | 6 +- tests/test_harness_docs.py | 12 +++ 12 files changed, 149 insertions(+), 120 deletions(-) diff --git a/.gitea/issue_template/task.md b/.gitea/issue_template/task.md index ba355b9..26de9b1 100644 --- a/.gitea/issue_template/task.md +++ b/.gitea/issue_template/task.md @@ -98,6 +98,16 @@ +## 完成证据 + + + +- 最终差异： +- 测试结果： +- 未验证部分： +- 提交哈希： +- 长期 Wiki 页面与 revision（无长期文档影响时填“无”）： + ## 风险和回退 diff --git a/AGENTS.md b/AGENTS.md index 22594d1..1838bba 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. 永久规则 @@ -33,17 +33,19 @@ ## 2. 哪些改动需要工单 -新功能、缺陷修复、重构以及任何用户可感知或改变程序行为的修改，必须先建立单元任务工单。 +以下改动必须先建立单元任务工单：新功能、数据库迁移、API 或运行时配置契约、权限与安全、并发与删除、发布与不可逆操作、跨模块行为、重构、重大 UI/交互/导航，以及无法确定风险或行为影响的修改。 -以下小改动可以直接提交，不要求工单和任务归档： +以下修改同时满足范围明确、容易回退且不涉及上述必须建单项时，可以直接提交： - 只改错别字、注释或文档措辞； - 只做格式化、导入排序或不跨文件的内部变量改名； - 补充类型标注或文档字符串且不改变行为； -- 删除已经确认无人使用的死代码。 +- 删除已经确认无人使用的死代码； +- 只修改测试且不改变产品行为； +- 单文件低风险缺陷，只恢复已有明确行为，且不改变接口、数据库、状态、权限、安全、并发、流程、布局或可访问性； - 只修改用户看到的界面显示文案，并且满足本文件“工单与设计证据双门禁”的全部豁免条件。 -除严格符合界面显示文案豁免的修改外，只要涉及接口、数据库、状态、权限、安全、并发、用户界面，或者无法确定是否改变行为，就必须建工单。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用豁免。 +直接提交仍须保留无关工作区改动、执行受影响的最小验证并写清提交说明。有任何不确定就建单。代码组件名、类名、变量、国际化键、API 字段和数据库字段不是显示文案，不适用文案豁免。 ## 3. 需求到实施 @@ -54,8 +56,8 @@ 5. 建立新工单不要求其他工单已经完成；开始实施前检查工单声明的前置工单。真实依赖未满足时保持“待实施”，允许并行时必须写明原因。 6. 开始实施前检查分支和工作区，明确哪些现有改动不属于本任务。 7. 严格按工单范围实现；新发现的问题先记录，不顺手混入当前任务。 -8. 执行与风险相称的测试，把关键结果和未验证部分更新到工单。实施过程中出现计划外、当前无法解除的问题时才标记“阻塞”。 -9. 长期核心文档必须先修改 Wiki、读取确认，再运行 `python dev_scripts/harness.py sync` 导出本地镜像；任务归档默认只更新 Wiki，不自动导出本地。不得直接编辑镜像后反向覆盖 Wiki。 +8. 执行与风险相称的测试。开始实施时更新一次工单；只有方案、范围、根因、风险或阻塞发生重要变化时追加记录；完成后集中回写最终差异、测试、未验证项和提交证据。 +9. 只有长期事实变化时才更新核心文档：先修改 Wiki、读取确认，再运行一次 `sync` 和一次 `sync --check`。无长期文档影响时不运行 Wiki 同步，不得直接编辑镜像后反向覆盖 Wiki。 Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明确授权，不得默认绕过建单。 @@ -86,16 +88,16 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - `只分析`：只读检查并给出方案；不建单、不修改，停在等待确认。 - `建工单`：根据已确认方案创建单元任务工单；建单后停止，不修改代码。 -- `执行工单 #N`：检查工单和依赖，实施、测试、提交、归档、推送并回写证据；停在“待验收”。 +- `执行工单 #N`：检查工单和依赖，实施、测试、提交、推送并集中回写证据；仅在长期文档变化时同步 Wiki；停在“待验收”。 - `建工单并做`：依次建单和执行，`建工单，做`、`建工单,做` 含义相同；停在“待验收”。 - `继续工单 #N`：核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查。 - `检查工单 #N`：只读核对范围、验收、测试和证据并输出报告；不自动修复。 - `同步文档`：读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档；不修改 Wiki、不自动提交。 -- `导出任务归档`：人工触发 `python dev_scripts/harness.py export`，只导出新增或 revision 已变化的任务归档；不删除本地文件、不自动提交。 -- `导出全部任务归档`：人工触发 `python dev_scripts/harness.py export --all`，读取并导出全部线上任务归档；不删除本地文件、不自动提交。 -- `#N 验收通过`：仅在用户明确验收后，更新 Wiki 归档、同步必要的核心文档、推送、同步父工单并关闭任务；不自动导出任务归档。 +- `导出任务归档`：历史兼容指令；用户明确要求时运行 `python dev_scripts/harness.py export`，只导出新增或 revision 已变化的 Wiki 任务快照；不删除本地文件、不自动提交。 +- `导出全部任务归档`：历史兼容指令；用户明确要求时运行 `python dev_scripts/harness.py export --all`，读取并导出全部线上任务快照；不删除本地文件、不自动提交。 +- `#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/`；完成结果、测试、提交和验收留在 Gitea 工单。`docs/task/` 只在用户明确要求历史快照时使用，Gitea 工单全文不导出到仓库。 详细记录边界见 [开发工作流](docs/01-workflow.md) 与 [业务规则和术语](docs/03-business-rules-and-glossary.md)。 ### 效率与范围控制 -本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 +本节只用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、按需 Wiki 同步、Git 提交和人工验收要求。 #### 严格控制范围 @@ -161,19 +163,19 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 - 实现提交信息引用工单号，例如：`fix: 修复登录超时 (#123)`。 - 不为流程制造空提交。 - 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。 -- 不能验证的真机、生产、迁移或并发行为必须写入工单和归档。 +- 不能验证的真机、生产、迁移或并发行为必须写入工单。 -## 7. 完成、验收和归档 +## 7. 完成、验收和关闭 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，运行一次 `sync` 和一次 `sync --check`，并把页面 revision 写回工单；无长期文档影响时跳过。 +4. 用户验收通过后，在工单记录验收结论，关闭单元工单，并同步更新 MVP 和 Epic；不重复抄写已有证据或同步无变化的 Wiki。 +5. `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. 引导提交例外 @@ -210,7 +212,7 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 - 长期开发文档以 Gitea Wiki 为事实来源，`docs/` 默认保存显式映射生成的核心只读镜像；`docs/task/` 是人工按需快照，可能不完整或不是最新状态。 - 核心 Wiki 与镜像的固定顺序是：修改 Wiki → 读取确认 → 导出核心 `docs` → 校验差异 → 提交镜像。 -- 任务归档默认只保存在 Wiki；`导出任务归档` 或 `导出全部任务归档` 必须由用户明确提出，且不得自动传播删除或重命名。 +- 新任务默认不创建 Wiki 任务归档；既有归档与 `docs/task/` 作为历史兼容内容保留。创建或导出任务快照必须由用户明确提出，且不得自动传播删除或重命名。 - 同步配置只允许写入 `docs/` 下的 Markdown；发现镜像有未提交修改时必须停止。 - Gitea 凭据只通过进程环境或 MCP 安全配置提供，不得写入仓库。 - `dev_scripts/` 只存放 DevHarness 自身工具；业务项目的通用脚本必须使用独立目录，不得混放。 diff --git a/README.md b/README.md index 069fbe9..fd94a06 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ MVP-0 的范围、非目标和验收口径见 [产品需求总览](docs/09-produ python dev_scripts/harness.py sync --verify ``` -新仓库在 Gitea 尚未建立前允许一次不关联工单的引导提交。远端和工单系统配置完成后，所有改变程序行为的工作都必须先有单元任务工单。 +新仓库在 Gitea 尚未建立前允许一次不关联工单的引导提交。远端和工单系统配置完成后，新功能、接口/配置契约、数据库、高风险、跨模块和重大 UI 工作必须先有单元任务工单；明确的低风险修改边界见开发工作流。 ## 文档入口 @@ -42,7 +42,7 @@ MVP-0 的范围、非目标和验收口径见 [产品需求总览](docs/09-produ | 简单修改怎么做、什么时候必须停 | [docs/05-common-changes.md](docs/05-common-changes.md) | | 报错了先查什么 | [docs/06-troubleshooting.md](docs/06-troubleshooting.md) | | 怎样部署、检查、备份和回退 | [docs/10-deployment-and-operations.md](docs/10-deployment-and-operations.md) | -| 建单、实施、验收、归档流程 | [docs/01-workflow.md](docs/01-workflow.md) | +| 建单、实施、验收、关闭流程 | [docs/01-workflow.md](docs/01-workflow.md) | `docs/` 是 Wiki 的只读镜像，不是编辑入口。修改长期文档的顺序见 [项目档案](docs/00-project-profile.md) 的“文档状态”。 @@ -53,10 +53,10 @@ AGENTS.md Agent 的通用工作规则 CLAUDE.md Claude Code 的规则入口 .gitea/issue_template/ Epic、MVP、单元任务工单模板 docs/ 核心长期文档（Wiki 初始化后转为只读镜像） -docs/task/ 人工按需导出的 Wiki 任务归档快照 +docs/task/ 历史兼容或人工明确要求的 Wiki 任务快照 prototypes/ 按工单和版本保存的本地 HTML 审核快照 wiki-docs.json 核心 Wiki 页面到本地镜像的显式映射 -dev_scripts/harness.py check / sync / archive / export 单一入口 +dev_scripts/harness.py check / sync 入口，兼容 archive / export tests/ Harness 工具自动化测试 ``` diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index 4275f9a..d8bcb86 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 = { "## 面向初级维护者的修改边界", "## 每个任务的文档影响", "## 需求记录与流转", - "## 稳定文档与任务归档", + "## 稳定文档与历史任务快照", "## 自然语言快捷指令", "## 效率与范围控制", "### 严格控制范围", @@ -306,6 +306,12 @@ def check_task_template(errors: list[str], root: Path = ROOT) -> None: "- [ ] 更新已有交付文档，受众与页面：", "- [ ] 新增交付文档，受众与页面：", "- [ ] 需要目标岗位或客户代表验证：是 / 否；验证方式：", + "## 完成证据", + "- 最终差异：", + "- 测试结果：", + "- 未验证部分：", + "- 提交哈希：", + "- 长期 Wiki 页面与 revision（无长期文档影响时填“无”）：", ) for section in missing_sections(content, required): errors.append(f"单元任务模板缺少：{section}") @@ -325,7 +331,7 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "单元任务是唯一正式实施单位", "高风险修改必须停止", "用户没有明确验收通过前不得关闭", - "长期核心文档必须先修改 Wiki", + "只有长期事实变化时才更新核心文档", "### 新项目 Wiki 初始化门禁", "`Home` 不存在时必须先创建 `Home`", "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据", @@ -350,6 +356,7 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "不得臆造用户原话", "不复制完整聊天", "Gitea 工单全文不导出到仓库", + "新任务默认不创建 Wiki 任务归档", ) for section in missing_sections(content, required): errors.append(f"AGENTS.md 缺少：{section}") @@ -675,7 +682,7 @@ def run_export(args: argparse.Namespace) -> int: def main() -> int: - parser = argparse.ArgumentParser(description="DevHarness 检查、同步与归档工具") + parser = argparse.ArgumentParser(description="DevHarness 检查、同步与历史快照兼容工具") sub = parser.add_subparsers(dest="command", required=True) p_check = sub.add_parser("check", help="检查 DevHarness 项目结构") @@ -698,7 +705,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( @@ -706,7 +713,7 @@ def main() -> int: ) p_archive.set_defaults(func=run_archive) - p_export = sub.add_parser("export", help="人工按需导出 Gitea Wiki 任务归档") + p_export = sub.add_parser("export", help="按明确要求导出 Gitea Wiki 历史任务快照") p_export.add_argument( "--all", action="store_true", diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index 801a03d..6d982b0 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/chorus/wiki/Project-Profile.- -wiki_revision: 8d5cdac0cee22efe667718393466c59255c6dd17 -synchronized_at: 2026-08-24T03:36:48Z +wiki_revision: 5392ab80c7789a793ee271c85d2aca875bedc7f2 +synchronized_at: 2026-08-24T07:59:16Z # 项目档案 @@ -137,7 +137,7 @@ synchronized_at: 2026-08-24T03:36:48Z | `admin-ui/` | 固定 go-admin-ui 导入代码与定制页 | 运行时依赖 `D:\github\goadmin` | | `migrations/` | 全部生产表结构与配置种子 SQL | 测试数据、AutoMigrate、不可逆一次性修数 | | `docs/` | 核心长期文档的 Wiki 只读镜像 | 人工直接维护的最终事实 | -| `docs/task/` | 人工按需导出的任务归档快照 | 讨论过程和默认自动导出 | +| `docs/task/` | 历史兼容：仅按用户明确要求导出的 Wiki 任务快照 | 新任务的标准完成证据和默认自动导出 | | `prototypes/` | 按工单/版本保存 HTML 审核快照 | 凭据、个人信息、生产数据 | | `scripts/` | Chorus 本地开发与运行辅助脚本 | DevHarness 工具、凭据和生产数据 | | `dev_scripts/` | DevHarness 工具 | 产品业务脚本 | diff --git a/docs/01-workflow.md b/docs/01-workflow.md index fec28e7..b905b3f 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/chorus/wiki/Development-Workflow.- -wiki_revision: e65f6f00510ab961909d638f7271a2de64f8bf38 -synchronized_at: 2026-08-20T03:29:22Z +wiki_revision: 2226a80884a2363522cf856a0edafe42f74df8a3 +synchronized_at: 2026-08-24T07:59:22Z # 开发工作流 @@ -11,7 +11,7 @@ synchronized_at: 2026-08-20T03:29:22Z ## 事实来源边界 - Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。 -- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。 +- Gitea Wiki 只保存长期有效的架构说明、开发规范和操作手册；单次任务结果留在 Gitea 工单。 - Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。 - 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。 @@ -33,16 +33,29 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地 ### 先判断是否需要工单 -只有纯界面显示文案同时满足以下全部条件时，才可以免工单、免原型： +以下改动必须建立单元任务工单： + +- 新功能、数据库迁移、API 或运行时配置契约变化； +- 权限、安全、凭据、并发、数据删除、发布或其他高风险操作； +- 跨模块行为变化、重构、重大 UI、交互或导航变化； +- 无法确定影响范围、风险或是否改变既有行为的修改。 + +以下修改同时满足“范围明确、容易回退、不涉及上述必须建单项”时可以直接提交： + +- 错别字、注释、文档措辞、格式化、导入排序、单文件内部变量改名； +- 不改变产品行为的类型标注、文档字符串、测试或已确认死代码清理； +- 单文件低风险缺陷，且只是恢复已有明确行为，不改变接口、数据库、状态、权限、安全、并发、流程、布局或可访问性； +- 纯界面显示文案，并满足本页的全部文案豁免条件。 + +直接提交仍要保留无关工作区改动、执行受影响的最小验证并写清提交说明。有任何不确定就建单。 + +纯界面显示文案豁免还必须同时满足： - 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案； - 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果； - 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义； - 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符； -- 不造成明显布局、截断、换行、可访问性或支持平台问题； -- 有任何不确定时不使用豁免。 - -豁免修改只执行与受影响界面相称的最小检查，确认文字正确且没有明显布局或可访问性问题，然后停止。只要任一条件不满足，或涉及用户行为、样式布局、交互和导航，就建立单元任务工单。 +- 不造成明显布局、截断、换行、可访问性或支持平台问题。 ### 再判断设计证据 @@ -124,57 +137,40 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地 Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。 -重要进度及时写回工单： +工单以两次集中更新为默认节奏： -- 已确认的根因； -- 方案或范围变化； -- 测试结果； -- 阻塞和未验证内容； -- Git 提交哈希； -- 相关 Wiki 页面及 revision。 +1. 开始实施时将状态改为“进行中”，记录已确认方案、依赖和范围；只有根因、范围、方案、阻塞或风险发生重要变化时追加更新。 +2. 实现与测试完成后集中写入最终差异、测试结果、未验证内容、提交哈希和长期 Wiki 页面 revision，并改为“待验收”。 -长期核心文档遵循唯一顺序： +长期核心文档仅在启动、部署、架构、接口、数据结构、业务规则、安全边界等长期事实变化时更新。需要更新时遵循： ```text -修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像 +修改 Wiki → 在线回读 revision → sync 导出 docs → sync --check → 提交镜像 ``` -任务归档默认只更新 Wiki，不自动导出到 `docs/task/`。不得先编辑本地镜像再反向覆盖 Wiki。 +无长期文档影响的任务不运行 Wiki 同步。不得先编辑本地镜像再反向覆盖 Wiki。 ### 4. 待验收 实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。 -### 5. 归档和关闭 +### 5. 验收和关闭 -使用以下命令只在 Wiki 创建任务归档页： +用户明确验收通过后，在工单记录验收结论，关闭单元工单，并勾选所属 MVP 和 Epic 的任务索引。验收时不重复抄写已经记录的测试和提交证据，也不再次同步没有变化的 Wiki 页面。 -```powershell -python dev_scripts/harness.py archive 123 "修复登录超时" -``` - -归档内容以 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/` 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。 +历史兼容命令 `archive`、`export` 和 `export --all` 仅在用户明确要求保留专项快照时使用，不属于标准任务完成流程。既有 Wiki 任务归档和 `docs/task/` 快照继续保留，不自动删除、改名或补齐。 ## 文档同步规则 - 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。 -- 任务归档不逐页登记映射，由按需导出工具根据 `Task-<编号>-<标题>` 动态发现；已有镜像优先按镜像头匹配原页面。 +- 历史任务归档不逐页登记映射；用户明确要求导出时，由兼容工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。 - 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。 - 镜像头必须记录页面名、页面地址、revision 和同步时间。 - 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。 -- 核心同步的 `--check` 只检查核心镜像，不要求线上任务归档全部存在于本地。 +- 只有长期文档发生变化时才运行核心同步；一次 `sync` 后运行一次 `sync --check`，不因归档或验收重复执行。`--check` 不要求历史任务归档全部存在于本地。 - 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。 - 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。 -- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。 +- Wiki 更新成功而核心镜像导出失败时，在工单记录部分完成状态，不得把任务标为待验收。 - 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。 ## 面向初级维护者的修改边界 @@ -228,20 +224,20 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 | 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 | | 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 | | 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` | -| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | 人工按需导出的 `docs/task/` 快照（可能不完整） | +| 完成后的实现、验证、提交和遗留问题 | Gitea 单元任务工单 | 无 | 任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。 -## 稳定文档与任务归档 +## 稳定文档与历史任务快照 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。 -- 工单和 Wiki 任务归档解释某次为什么修改、实际改了什么以及如何验证；本地任务快照不是完整历史。 -- 新人先读稳定主题页，只有追查历史原因时才读任务归档。 -- 任务产生的长期结论必须合并到主题页，不能只留在归档。 +- Gitea 工单解释某次为什么修改、实际改了什么以及如何验证，是单次任务证据的事实来源。 +- 既有 Wiki 任务归档与 `docs/task/` 仅是历史或人工专项快照，不要求为新任务创建；新人先读稳定主题页，追查历史时优先读工单。 +- 任务产生的长期结论必须合并到对应主题页，不能只留在工单。 ## 效率与范围控制 -本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。 +本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、按需 Wiki 同步、Git 提交和人工验收要求。 ### 严格控制范围 @@ -268,7 +264,7 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 ### 明确停止条件 - 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。 -- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。 +- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、按需 Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。 - 未影响当前验收的相邻问题只提示或建单，不顺手处理。 ## 自然语言快捷指令 @@ -279,23 +275,23 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 |---|---|---| | `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 | | `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 | -| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” | +| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交；仅在长期文档变化时更新 Wiki 并同步镜像；集中回写完成证据 | 工单保持“待验收” | | `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” | | `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 | | `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 | | `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 | -| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 | -| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 | -| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，同步必要的核心文档，推送、同步父工单并关闭任务；不自动导出任务归档 | 工单“已完成”并关闭 | +| `导出任务归档` | 兼容指令；仅按用户明确要求增量导出历史 Wiki 任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 | +| `导出全部任务归档` | 兼容指令；仅按用户明确要求全量导出历史 Wiki 任务归档 | 显示导出结果；不删除本地文件、不自动提交 | +| `#N 验收通过` | 在工单记录验收结论，按需推送尚未推送的提交，勾选父工单并关闭任务；不创建归档，不重复同步无变化的 Wiki | 工单“已完成”并关闭 | 补充边界： - 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。 - 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。 - `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。 -- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。 -- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。 -- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存人工按需导出的 Wiki 最终任务归档快照。 +- `同步文档` 或历史任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。 +- `导出任务归档` 和 `导出全部任务归档` 是历史兼容能力，必须由用户明确提出，其他快捷指令不隐式创建或导出任务归档。 +- Gitea 工单保留讨论、完成证据和验收，不把工单全文导出到本地；`docs/task/` 只保存人工按需导出的历史 Wiki 任务快照。 ## 什么时候重新确认方案 @@ -317,6 +313,6 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务 | 讨论过程和临时方案 | 是 | 否 | 否 | | 实施进度和阻塞 | 是 | 否 | 否 | | 长期有效的最终方案 | 链接 | 是 | 镜像 | -| 测试结果与未验证内容 | 是 | 任务归档 | 按需镜像 | -| 提交哈希 | 是 | 任务归档 | 按需镜像 | +| 测试结果与未验证内容 | 是 | 否 | 否 | +| 提交哈希与验收结论 | 是 | 否 | 否 | | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 | diff --git a/docs/05-common-changes.md b/docs/05-common-changes.md index 05cbc99..93e252f 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/chorus/wiki/Common-Changes.- -wiki_revision: d7d778dd5f6e2a2b007371c6ce07f8adc4469638 -synchronized_at: 2026-08-20T08:30:34Z +wiki_revision: af13a8db3609a2b85b9dc46441bc3bd716b93c8e +synchronized_at: 2026-08-24T07:59:44Z # 常见修改指南 @@ -14,11 +14,11 @@ synchronized_at: 2026-08-20T08:30:34Z | 级别 | 例子 | 处理方式 | |---|---|---| -| 低 | 不改变含义/布局/可访问性的显示文案，注释，文档措辞 | 最小验证；符合豁免时可不建单 | -| 中 | 已确认页面的小样式、只读字段、普通日志、mock Provider 配置 | 建单并运行受影响测试 | -| 高 | retryable、SSRF、加密/轮换、迁移、租约/CAS、身份权限、点数写入、删除/清理 | 停止，Agent 分析并等待人工确认 | +| 低 | 文案、注释、文档措辞；不改变产品行为的测试；单文件且只恢复已有明确行为的小缺陷 | 满足免单条件时直接提交，执行受影响的最小验证 | +| 中 | 已确认页面的小样式、只读字段、普通日志、mock Provider 配置、跨文件行为修改 | 建单并运行受影响测试 | +| 高 | retryable、SSRF、密钥、迁移、租约/CAS、身份权限、删除/清理、发布和不可逆操作 | 必须建单；停止实施，由 Agent 分析并等待人工确认 | -风险按影响判断，不按行数判断。`internal/core` 新增 Gin/go-admin/gobreaker/imaging import 也是高风险边界破坏。 +新功能、API 或配置契约、数据库、权限、安全、并发、跨模块变化和重大 UI 必须建单。免单修改不得改变接口、数据库、状态、权限、安全、并发、流程、布局或可访问性；无法确定时建单。风险按影响判断，不按行数判断。`internal/core` 新增 Gin/go-admin/gobreaker/imaging import 也是高风险边界破坏。 ## 修改用户端显示文案 @@ -65,7 +65,7 @@ synchronized_at: 2026-08-20T08:30:34Z ## 修改 Wiki 文案 -长期文档以 Gitea Wiki 为事实来源： +只有长期事实发生变化时才修改 Wiki；Gitea Wiki 是长期文档事实来源： ```text 修改 Wiki → 在线回读 revision → sync 导出 docs → sync --check → 提交 @@ -90,7 +90,7 @@ python -m unittest discover -s tests -v python dev_scripts/harness.py check --strict ``` -不要为了让检查变绿而削弱安全、Wiki 主源或任务归档边界。 +不要为了让检查变绿而削弱安全、Wiki 主源或工单事实来源边界。archive/export 只用于用户明确要求的历史快照，不属于标准任务闭环。 ## 看懂 Agent 的修改 diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md index fce61ba..805fb1d 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/chorus/wiki/Existing-Project-Adoption-Guide.- -wiki_revision: 2b20998dd7751c6fe3edfc26922722e44bf8496b -synchronized_at: 2026-08-20T03:29:39Z +wiki_revision: 6882d8c6a20375ad07999dd48daa2fc33fd3641a +synchronized_at: 2026-08-24T08:00:02Z # 已有项目接入 DevHarness 指南 @@ -23,7 +23,7 @@ synchronized_at: 2026-08-20T03:29:39Z | 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 | | 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 | | Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 | -| 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 | +| 历史任务快照 | 默认不创建；按明确需要保留兼容能力 | 不复制 DevHarness 或其他项目的历史归档 | | 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 | 从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。 @@ -71,7 +71,7 @@ Agent 在提出方案前只读检查： - 多个应用共同完成一条产品或业务链路； - 由同一团队维护，仓库权限基本一致； - 接口变更需要在一个工单中同步修改或验证多端； -- 共享契约、业务规则和任务归档放在一起更容易保持一致； +- 共享契约、业务规则和长期文档放在一起更容易保持一致； - 仓库体积、测试时间和工具性能尚未明显影响开发； - 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。 @@ -131,7 +131,7 @@ Agent 在提出方案前只读检查： ### 7. 提交和验收 -提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。 +提交只包含当前接入工单相关文件。记录测试、未验证部分、按需 Wiki revision 和提交哈希，并保持工单“待验收”，等待用户明确验收后再关闭。 ## 后续升级 @@ -210,7 +210,7 @@ Agent 在提出方案前只读检查： 严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、 任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出 -本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持 +本地 docs 镜像。执行必要测试，提交实现，并把完成证据集中回写工单，然后保持 为“待验收”；未经我明确验收，不关闭工单。 ``` @@ -227,7 +227,7 @@ Agent 在提出方案前只读检查： - [ ] 已为每类长期文档明确事实来源和迁移状态。 - [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。 - [ ] Harness 检查已按目标项目调整并通过。 -- [ ] 必要测试、未验证部分、提交和归档证据已记录。 +- [ ] 必要测试、未验证部分、提交和验收证据已记录在工单。 - [ ] 工单处于待验收，未提前关闭。 ## 回退原则 diff --git a/docs/09-product-requirements-overview.md b/docs/09-product-requirements-overview.md index c9b3f0a..471c8e7 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/chorus/wiki/Product-Requirements-Overview.- -wiki_revision: 88fff047d243ac3d7637ae4dfaa46559881000e1 -synchronized_at: 2026-08-24T03:49:28Z +wiki_revision: b9376419b0451024cbff90d3e2f9888d033a1ef8 +synchronized_at: 2026-08-24T08:00:09Z # 产品需求总览 @@ -25,7 +25,7 @@ synchronized_at: 2026-08-24T03:49:28Z | 项目目标、用户、范围和技术基线 | Project-Profile | 链接和一句话摘要 | | 长期功能需求、业务规则和系统边界 | 对应 Wiki 主题页 | 需求领域和详情链接 | | 单次实现范围、变化和验收标准 | Gitea 单元任务工单 | 工单编号和当前状态 | -| 已完成方案、测试和遗留问题 | Wiki 任务归档 | 验收入口 | +| 已完成方案、测试、提交和遗留问题 | Gitea 单元任务工单 | 验收入口 | | 与版本绑定的原型、设计图或交互稿 | Git 中的 `design/` 或 `prototypes/` | 路径、版本和确认状态 | | 外部原型 | 原型平台 | 链接、版本或确认日期；重要版本保留可追溯快照 | @@ -185,7 +185,7 @@ MVP-2 的 API Key 存哈希、身份仍属于 `users`。提交、查询、幂等 - 唯一的详细 Wiki 页面； - 当前或主要实施工单； - 原型状态或明确写“无”； -- 已交付时的任务归档或验收入口。 +- 已交付时的 Gitea 工单与验收入口。 需求正文、接口细节、业务规则和验收标准只在各自事实来源修改。本页使用一至两句话摘要并链接过去，不复制大段内容。 diff --git a/docs/README.md b/docs/README.md index 1f520cc..5d6e5e6 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/chorus/wiki/Home -wiki_revision: 3d6efad79056ff85f7532e28a90c80f2c710c332 -synchronized_at: 2026-08-20T07:00:57Z +wiki_revision: bf4f622133bfa31a595a5c57a62d6bcb0ed4189c +synchronized_at: 2026-08-24T07:59:09Z # chorus 文档中心 @@ -22,7 +22,7 @@ chorus 是从 cmhub 设计中抽取并用 Go 重写的独立生图生文服务 6. [常见修改指南](Common-Changes.-)：修改步骤和停止条件。 7. [故障排查](Troubleshooting)：按证据定位环境、队列、上游和生成器问题。 8. [部署与运维](Deployment-and-Operations.-)：生产迁移、服务、健康、备份和回退。 -9. [开发工作流](Development-Workflow.-)：建单、确认、实施、验收与归档。 +9. [开发工作流](Development-Workflow.-)：建单、确认、实施、验收与关闭。 ## 五分钟开始 @@ -57,7 +57,7 @@ retryable、SSRF、密钥、迁移、租约/CAS、身份权限、点数写入、 |---|---| | 单元任务状态、讨论、阻塞和验收 | Gitea 工单 | | 长期需求导航 | Product-Requirements-Overview | -| 架构、规则、开发、排错、部署、归档 | Gitea Wiki | +| 架构、规则、开发、排错和部署等长期文档 | Gitea Wiki | | 生产数据库结构和配置种子 | `migrations/` 可逆 SQL | | 源码和固定版本资料 | chorus Git；外部来源提交记录在 Project-Profile | | 已确认界面与交互 | `prototypes/<工单号>/<版本>/index.html` | @@ -73,7 +73,7 @@ retryable、SSRF、密钥、迁移、租约/CAS、身份权限、点数写入、 - [代码仓库](https://git.ilapage.cn/OPC/chorus) - [新项目文档初始化](New-Project-Documentation-Setup.-) - [交付文档指南](Delivery-Documentation-Guide.-) -- [任务归档模板](Task-Archive-Template.-) +- [历史任务快照模板（兼容）](Task-Archive-Template.-) ## 同步原则 @@ -81,7 +81,7 @@ retryable、SSRF、密钥、迁移、租约/CAS、身份权限、点数写入、 修改 Wiki → 在线回读 revision → 导出 docs → 校验差异 → 提交镜像 ``` -- `wiki-docs.json` 显式映射核心和项目专用页面，普通同步不处理任务归档。 +- `wiki-docs.json` 显式映射核心和项目专用页面；仅在长期文档变化时同步，普通同步不处理历史任务快照。 - 带 `generated: true` 的文件不得手工编辑；有未提交镜像修改时同步停止。 - 页面删除、重命名和事实源变化必须先更新工单并确认。 - 凭据、个人数据、真实 prompt、生成文件和生产数据不得进入文档、工单或原型。 diff --git a/docs/templates/task-archive.md b/docs/templates/task-archive.md index 3b8982f..14d9d43 100644 --- a/docs/templates/task-archive.md +++ b/docs/templates/task-archive.md @@ -2,12 +2,14 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Task-Archive-Template wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Task-Archive-Template.- -wiki_revision: 41240e7746990f3132201ad27c8f8c3a59240189 -synchronized_at: 2026-08-20T03:29:51Z +wiki_revision: f4225cd1a9595591a5758b4e1d9cf5fd8954e06e +synchronized_at: 2026-08-24T08:00:36Z # <工单号> <标题> +> 历史兼容模板：标准任务以 Gitea 工单保存实现、测试、提交和验收证据，不再创建 Wiki 任务归档。仅在用户明确要求专项历史快照时使用本模板。 + - 类型：需求 / 缺陷 / 重构 - 所属 Epic：# - 所属 MVP / 版本：# diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index 9de44a4..067d9ae 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -177,6 +177,18 @@ class TaskTemplateTests(unittest.TestCase): errors, ) + def test_task_template_requires_completion_evidence(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) + self.assertIn("单元任务模板缺少：- 提交哈希：", errors) + def test_task_template_requires_design_and_prototype_gate(self) -> None: with tempfile.TemporaryDirectory() as directory: root = Path(directory)