新增已有项目接入 DevHarness 指南 #12

New Issue

2026-08-10T14:54:51+08:00

ila commented

2026-08-10 14:54:51 +08:00

基本信息

类型：单元任务
状态：已完成
所属 Epic：无
所属 MVP / 版本：无

依赖与并行

前置工单：#11
是否允许与前置工单并行：是
原因：#11 的实现和归档已经完成、仅等待验收；本任务新增独立的存量项目接入指南，不改变 #11 的交付文档方案。

原始需求

来源：用户与 Agent 对话
提出时间：2026-08-10
关键原话或脱敏摘要：“接受你的建议，建工单”
已确认上下文：为经常将 DevHarness 接入已有项目的场景，增加专门的“已有项目接入 DevHarness 指南”。

要解决什么

现有“新项目文档初始化”主要面向从模板创建的新项目。已有项目通常已经存在代码、规则、文档、工单、Wiki、提交历史和未完成工作，不能直接套用新项目初始化中的清理或替换步骤。

目标：提供一份面向 Claude、Codex 等 Agent 的存量项目增量接入指南，让 Agent 能先盘点现状、识别冲突、等待方案确认，再通过单元工单安全接入 DevHarness。

做什么 / 不做什么

做

在 Gitea Wiki 新增“已有项目接入 DevHarness 指南”。
说明适用范围以及与“新项目文档初始化”的区别。
给出接入前只读盘点清单。
规定已有规则、��档、Git 历史和未提交改动的保留原则。
规定 Gitea 工单、Wiki、docs/ 镜像和 Harness 工具的增量接入顺序。
给出可以直接发送给其他 Agent 的“只分析”和“确认后实施”指令模板。
给出冲突处理、停止条件、回退和最小验收清单。
更新 Home 和相关入口，使已有项目接入指南可发现。
将页面显式映射到本地 docs/，纳入 Harness 核心映射和章节检查。
更新相关单元测试。
按 Wiki-first 流程同步镜像、提交、归档并等待验收。

不做

不创建自动迁移或批量复制脚本。
不自动修改任何已有业务项目。
不删除、覆盖、重命名已有项目的规则、文档、Wiki 页面或历史归档。
不把 DevHarness 自身的任务归档复制到业务项目。
不要求一次性迁移全部旧文档。
不修改 DevHarness 的事实来源边界。
不把新项目初始化和已有项目接入强行合并成一个复杂流程。

已确认方案

采用单独稳定主题页进行最小实现：

新增 Existing-Project-Adoption-Guide Wiki 页面。
推荐“盘点现状 → 确认差异方案 → 建单 → 增量接入规则和工单 → 迁移长期文档到 Wiki → 建立镜像映射 → 启用严格检查”的顺序。
明确必须保留已有 AGENTS.md、README、文档、Git 历史、任务状态和无关工作区改动，冲突内容由负责人确认后合并。
提供两段可复制指令：
- 只读分析已有项目并输出接入方案；
- 方案确认后建工单并实施。
新增 Home 入口、本地只读镜像、Harness 章节检查和相应测试。
不增加迁移自动化，不修改实际业务项目。

预计修改文件：

Gitea Wiki：Existing-Project-Adoption-Guide
Gitea Wiki：Home
wiki-docs.json
dev_scripts/check_harness.py
tests/test_harness_docs.py
Wiki 导出的对应 docs/ 镜像
本任务 Wiki 归档及其镜像

需求变化记录

日期	变化内容	原因	用户确认
2026-08-10	首次确认，无变化	接受 Agent 建议	是

文档影响

不影响长期文档，原因：
更新项目档案或本地开发与验证
更新架构与代码地图
更新业务规则与术语
更新常见修改或故障排查
更新其他 Wiki 页面：新增 Existing-Project-Adoption-Guide，更新 Home

交付文档影响

无交付文档影响，原因：[internal] 本任务只增加内部开发流程指南，不改变产品交付给客户或岗位人员的操作方法。
更新已有交付文档，受众与页面：
新增交付文档，受众与页面：
需要目标岗位或客户代表验证：否；验证方式：由维护者检查指令可复制性和接入边界是否完整。

验收标准

Wiki 存在独立的已有项目接入指南。
指南明确区分已有项目接入与新项目初始化。
指南覆盖只读盘点、已有内容保护、冲突处理和停止条件。
指南给出增量接入顺序，不要求一次性替换或迁移。
指南包含可以直接发送给 Agent 的分析指令和实施指令。
指南明确禁止复制 DevHarness 历史归档和覆盖已有项目内容。
Home 可以进入已有项目接入指南。
页面具有显式 Wiki 镜像映射和有效 revision。
Harness 严格检查和单元测试通过。
实现提交与归档提交已推送。
工单已在用户明确验收通过后关闭。

验证方式

python dev_scripts/check_harness.py --strict
python -m unittest discover -s tests -v
python dev_scripts/sync_wiki_docs.py --check
git diff --check
git status --short --branch
人工检查两段 Agent 指令能否直接复制，并且不授权覆盖、删除或自动迁移已有项目内容。

风险和回退

风险：Agent 把“接��模板”理解为覆盖已有规则；通过只读盘点、冲突清单、方案确认和增量合并控制。
风险：把旧项目任务归档或历史文档错误带入新事实来源；通过禁止复制归档、逐页确认迁移控制。
风险：同时维护 Wiki 和原本地长期文档形成双事实源；指南必须为每类文档明确迁移状态和最终事实来源。
回退：恢复 Home、映射和 Harness 检查到任务前版本；新增 Wiki 页的删除属于破坏性操作，回退时需另行确认。

实施结果与证据

实施结果：与已确认方案一致；未创建迁移脚本，未修改实际业务项目。
线上 Wiki：
- Existing-Project-Adoption-Guide，revision cad12048c8aa6f54ec6d2595a79c814233e18285
- Home，revision 55d89b7aec659f55a61e7ceef881ef34a62d9379
- Task-12-已有项目接入DevHarness指南，revision 902c90884fd8902d8346365bf588183fdb6b00a3
本地镜像：
- docs/08-existing-project-adoption.md
- docs/task/12-已有项目接入DevHarness指南.md
验证：
- python dev_scripts/check_harness.py --strict：通过
- python -m unittest discover -s tests -v：23/23 通过
- python dev_scripts/sync_wiki_docs.py --check：25/25 一致
- git diff --check：通过
- 人工检查两段 Agent 指令：未授权覆盖、删除、重命名或自动迁移已有内容
提交：
- 0271a3e docs: 新增已有项目接入指南 (#12)
- eba8515 docs: archive task #12
未验证部分：未在真实业务仓库执行完整接入，这是已确认非目标；首次实际接入时应另建项目专用工单验证。
验收结果：用户于 2026-08-10 明确验收通过。
验收状态提交：105328e docs: record task #12 acceptance。

## 基本信息 - 类型：单元任务 - 状态：已完成 - 所属 Epic：无 - 所属 MVP / 版本：无 ## 依赖与并行 - 前置工单：#11 - 是否允许与前置工单并行：是 - 原因：#11 的实现和归档已经完成、仅等待验收；本任务新增独立的存量项目接入指南，不改变 #11 的交付文档方案。 ## 原始需求 - 来源：用户与 Agent 对话 - 提出时间：2026-08-10 - 关键原话或脱敏摘要：“接受你的建议，建工单” - 已确认上下文：为经常将 DevHarness 接入已有项目的场景，增加专门的“已有项目接入 DevHarness 指南”。 ## 要解决什么现有“新项目文档初始化”主要面向从模板创建的新项目。已有项目通常已经存在代码、规则、文档、工单、Wiki、提交历史和未完成工作，不能直接套用新项目初始化中的清理或替换步骤。目标：提供一份面向 Claude、Codex 等 Agent 的存量项目增量接入指南，让 Agent 能先盘点现状、识别冲突、等待方案确认，再通过单元工单安全接入 DevHarness。 ## 做什么 / 不做什么 ### 做 - 在 Gitea Wiki 新增“已有项目接入 DevHarness 指南”。 - 说明适用范围以及与“新项目文档初始化”的区别。 - 给出接入前只读盘点清单。 - 规定已有规则、��档、Git 历史和未提交改动的保留原则。 - 规定 Gitea 工单、Wiki、`docs/` 镜像和 Harness 工具的增量接入顺序。 - 给出可以直接发送给其他 Agent 的“只分析”和“确认后实施”指令模板。 - 给出冲突处理、停止条件、回退和最小验收清单。 - 更新 Home 和相关入口，使已有项目接入指南可发现。 - 将页面显式映射到本地 `docs/`，纳入 Harness 核心映射和章节检查。 - 更新相关单元测试。 - 按 Wiki-first 流程同步镜像、提交、归档并等待验收。 ### 不做 - 不创建自动迁移或批量复制脚本。 - 不自动修改任何已有业务项目。 - 不删除、覆盖、重命名已有项目的规则、文档、Wiki 页面或历史归档。 - 不把 DevHarness 自身的任务归档复制到业务项目。 - 不要求一次性迁移全部旧文档。 - 不修改 DevHarness 的事实来源边界。 - 不把新项目初始化和已有项目接入强行合并成一个复杂流程。 ## 已确认方案采用单独稳定主题页进行最小实现： 1. 新增 `Existing-Project-Adoption-Guide` Wiki 页面。 2. 推荐“盘点现状 → 确认差异方案 → 建单 → 增量接入规则和工单 → 迁移长期文档到 Wiki → 建立镜像映射 → 启用严格检查”的顺序。 3. 明确必须保留已有 `AGENTS.md`、README、文档、Git 历史、任务状态和无关工作区改动，冲突内容由负责人确认后合并。 4. 提供两段可复制指令： - 只读分析已有项目并输出接入方案； - 方案确认后建工单并实施。 5. 新增 Home 入口、本地只读镜像、Harness 章节检查和相应测试。 6. 不增加迁移自动化，不修改实际业务项目。预计修改文件： - Gitea Wiki：`Existing-Project-Adoption-Guide` - Gitea Wiki：`Home` - `wiki-docs.json` - `dev_scripts/check_harness.py` - `tests/test_harness_docs.py` - Wiki 导出的对应 `docs/` 镜像 - 本任务 Wiki 归档及其镜像 ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-10 | 首次确认，无变化 | 接受 Agent 建议 | 是 | ## 文档影响 - [ ] 不影响长期文档，原因： - [ ] 更新项目档案或本地开发与验证 - [ ] 更新架构与代码地图 - [ ] 更新业务规则与术语 - [ ] 更新常见修改或故障排查 - [x] 更新其他 Wiki 页面：新增 Existing-Project-Adoption-Guide，更新 Home ## 交付文档影响 - [x] 无交付文档影响，原因：[internal] 本任务只增加内部开发流程指南，不改变产品交付给客户或岗位人员的操作方法。 - [ ] 更新已有交付文档，受众与页面： - [ ] 新增交付文档，受众与页面： - [x] 需要目标岗位或客户代表验证：否；验证方式：由维护者检查指令可复制性和接入边界是否完整。 ## 验收标准 - [x] Wiki 存在独立的已有项目接入指南。 - [x] 指南明确区分已有项目接入与新项目初始化。 - [x] 指南覆盖只读盘点、已有内容保护、冲突处理和停止条件。 - [x] 指南给出增量接入顺序，不要求一次性替换或迁移。 - [x] 指南包含可以直接发送给 Agent 的分析指令和实施指令。 - [x] 指南明确禁止复制 DevHarness 历史归档和覆盖已有项目内容。 - [x] Home 可以进入已有项目接入指南。 - [x] 页面具有显式 Wiki 镜像映射和有效 revision。 - [x] Harness 严格检查和单元测试通过。 - [x] 实现提交与归档提交已推送。 - [x] 工单已在用户明确验收通过后关闭。 ## 验证方式 - `python dev_scripts/check_harness.py --strict` - `python -m unittest discover -s tests -v` - `python dev_scripts/sync_wiki_docs.py --check` - `git diff --check` - `git status --short --branch` - 人工检查两段 Agent 指令能否直接复制，并且不授权覆盖、删除或自动迁移已有项目内容。 ## 风险和回退 - 风险：Agent 把“接��模板”理解为覆盖已有规则；通过只读盘点、冲突清单、方案确认和增量合并控制。 - 风险：把旧项目任务归档或历史文档错误带入新事实来源；通过禁止复制归档、逐页确认迁移控制。 - 风险：同时维护 Wiki 和原本地长期文档形成双事实源；指南必须为每类文档明确迁移状态和最终事实来源。 - 回退：恢复 Home、映射和 Harness 检查到任务前版本；新增 Wiki 页的删除属于破坏性操作，回退时需另行确认。 ## 实施结果与证据 - 实施结果：与已确认方案一致；未创建迁移脚本，未修改实际业务项目。 - 线上 Wiki： - Existing-Project-Adoption-Guide，revision `cad12048c8aa6f54ec6d2595a79c814233e18285` - Home，revision `55d89b7aec659f55a61e7ceef881ef34a62d9379` - Task-12-已有项目接入DevHarness指南，revision `902c90884fd8902d8346365bf588183fdb6b00a3` - 本地镜像： - `docs/08-existing-project-adoption.md` - `docs/task/12-已有项目接入DevHarness指南.md` - 验证： - `python dev_scripts/check_harness.py --strict`：通过 - `python -m unittest discover -s tests -v`：23/23 通过 - `python dev_scripts/sync_wiki_docs.py --check`：25/25 一致 - `git diff --check`：通过 - 人工检查两段 Agent 指令：未授权覆盖、删除、重命名或自动迁移已有内容 - 提交： - `0271a3e` `docs: 新增已有项目接入指南 (#12)` - `eba8515` `docs: archive task #12` - 未验证部分：未在真实业务仓库执行完整接入，这是已确认非目标；首次实际接入时应另建项目专用工单验证。 - 验收结果：用户于 2026-08-10 明确验收通过。 - 验收状态提交：`105328e` `docs: record task #12 acceptance`。

ila referenced this issue from a commit

2026-08-10 15:01:18 +08:00

docs: 新增已有项目接入指南 (#12)

ila referenced this issue from a commit

2026-08-10 15:06:21 +08:00

docs: archive task #12

ila referenced this issue from a commit

2026-08-10 18:01:14 +08:00

docs: record task #12 acceptance

ila closed this issue

2026-08-10 18:01:28 +08:00

ila referenced this issue