From 902c90884fd8902d8346365bf588183fdb6b00a3 Mon Sep 17 00:00:00 2001 From: ila Date: Mon, 10 Aug 2026 15:02:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E6=88=90=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#12=20=E5=BD=92=E6=A1=A3=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...%E5%85%A5DevHarness%E6%8C%87%E5%8D%97.-.md | 68 ++++++++++++++----- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/Task-12-%E5%B7%B2%E6%9C%89%E9%A1%B9%E7%9B%AE%E6%8E%A5%E5%85%A5DevHarness%E6%8C%87%E5%8D%97.-.md b/Task-12-%E5%B7%B2%E6%9C%89%E9%A1%B9%E7%9B%AE%E6%8E%A5%E5%85%A5DevHarness%E6%8C%87%E5%8D%97.-.md index 05a99c3..556856d 100644 --- a/Task-12-%E5%B7%B2%E6%9C%89%E9%A1%B9%E7%9B%AE%E6%8E%A5%E5%85%A5DevHarness%E6%8C%87%E5%8D%97.-.md +++ b/Task-12-%E5%B7%B2%E6%9C%89%E9%A1%B9%E7%9B%AE%E6%8E%A5%E5%85%A5DevHarness%E6%8C%87%E5%8D%97.-.md @@ -1,9 +1,9 @@ -# 12 已有项目接入DevHarness指南 +# 12 已有项目接入 DevHarness 指南 -- 类型：需求 / 缺陷 / 重构 -- 所属 Epic：# -- 所属 MVP / 版本：# -- 状态：待验收 / 已完成 +- 类型：开发流程优化 +- 所属 Epic：无 +- 所属 MVP / 版本：无 +- 状态：待验收 - 日期：2026-08-10 - Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/12 - Wiki 页面：Task-12-已有项目接入DevHarness指南 @@ -11,32 +11,66 @@ ## 背景与目标 - +现有“新项目文档初始化”面向从模板创建的新项目，没有完整覆盖已有项目中现存规则、文档、工单、Wiki、Git 历史、未完成任务和工作区改动的保护与增量接入方式。 + +本任务新增独立的已有项目接入指南，让 Claude、Codex 等 Agent 能先只读盘点、识别冲突、等待方案确认，再通过单元任务安全地分阶段接入 DevHarness。 ## 最终方案 - +- 新增 `Existing-Project-Adoption-Guide`，明确与新项目初始化的适用边界。 +- 接入前盘点 Agent 规则、README、文档、Wiki、工单、Git 历史、未提交改动、技术栈、命令、权限、安全及任务状态。 +- 区分代码或系统事实、负责人确认规则、待确认假设、规则冲突和必须保留的无关改动。 +- 明确保留 Git 历史、项目专用规则、现有任务状态和无关工作区改动。 +- 禁止复制 DevHarness 历史归档、覆盖已有规则、把模板占位值当成项目事实或自动清理旧文档。 +- 采用“确认差异方案 → 建立单元工单 → 接入规则和工单流程 → 确定长期文档事实来源 → 接入必要 Harness 工具 → 分阶段验证 → 提交和验收”的顺序。 +- 为已有文档提供保留在 Git、迁移到 Wiki、合并、暂不迁移和停止维护五种明确状态。 +- 提供可直接发送给 Agent 的“只分析”和“方案确认后实施”两段指令。 +- 规定冲突、删除重命名、产品行为变化、重叠修改、权限不可用和事实不明时的停止条件。 +- Home 增加指南入口和已有项目接入导航。 +- 页面映射到 `docs/08-existing-project-adoption.md`，并纳入 Harness 核心映射和章节检查。 +- 未增加自动迁移脚本，未修改任何实际业务项目，未改变事实来源边界。 + +实施结果与已确认方案一致。 ## 修改文件 -- `<文件>`：<改动说明> +- `dev_scripts/check_harness.py`：增加已有项目接入指南的核心映射和章节检查。 +- `tests/test_harness_docs.py`：验证指南属于必需核心页面。 +- `wiki-docs.json`：登记指南和本任务归档镜像。 +- `docs/README.md`：Home Wiki 只读镜像，增加已有项目接入入口。 +- `docs/08-existing-project-adoption.md`：已有项目接入指南只读镜像。 +- `docs/task/12-已有项目接入DevHarness指南.md`：本页的自动导出镜像。 ## 验收结果 | 验收标准 | 结果 | |---|---| -| | 通过 / 未通过 | +| Wiki 存在独立的已有项目接入指南 | 通过 | +| 明确区分已有项目接入与新项目初始化 | 通过 | +| 覆盖只读盘点、内容保护、冲突处理和停止条件 | 通过 | +| 给出分阶段增量接入顺序 | 通过 | +| 包含可直接复制的分析和实施指令 | 通过 | +| 禁止复制历史归档和覆盖已有项目内容 | 通过 | +| Home 可进入指南 | 通过 | +| 页面具有显式映射和有效 revision | 通过 | +| Harness 严格检查和单元测试 | 通过 | +| 实现和归档提交已推送 | 进行中：归档提交后回写工单 | +| 用户明确验收 | 待验收 | ## 测试 -- 执行命令：`<命令>` -- 结果： -- **未验证部分**： - -## 遗留问题 - - +- 执行命令：`python dev_scripts/check_harness.py --strict` +- 结果：通过。 +- 执行命令：`python -m unittest discover -s tests -v` +- 结果：23/23 通过。 +- 执行命令：`python dev_scripts/sync_wiki_docs.py --check` +- 结果：归档前 24/24 映射一致；归档完成后重新检查。 +- 执行命令：`git diff --check` +- 结果：通过。 +- 人工检查：两段 Agent 指令未授权覆盖、删除、重命名或自动迁移已有项目内容。 +- **未验证部分**：未在真实业务仓库执行完整接入，因为修改实际项目属于本任务非目标；首次实际接入时应按指南建立独立工单并记录项目专用验证。 ## 相关提交 -- `<提交哈希>` <提交说明> +- `0271a3e` `docs: 新增已有项目接入指南 (#12)` +- 归档提交哈希在提交后回写 Gitea 工单，避免归档自引用。