From 0271a3ebd717d02b7f34d9270787eb22b45a6a3f Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Mon, 10 Aug 2026 15:01:15 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=B7=B2=E6=9C=89?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=8E=A5=E5=85=A5=E6=8C=87=E5=8D=97=20(#12)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 dev_scripts/check_harness.py         |  15 +++
 docs/08-existing-project-adoption.md | 165 +++++++++++++++++++++++++++
 docs/README.md                       |   8 +-
 tests/test_harness_docs.py           |   9 ++
 wiki-docs.json                       |   4 +
 5 files changed, 198 insertions(+), 3 deletions(-)
 create mode 100644 docs/08-existing-project-adoption.md

diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py
index 2240c31..2628489 100644
--- a/dev_scripts/check_harness.py
+++ b/dev_scripts/check_harness.py
@@ -24,6 +24,9 @@ CORE_PAGE_PATHS = {
     "New-Project-Documentation-Setup": (
         "docs/07-new-project-documentation-setup.md"
     ),
+    "Existing-Project-Adoption-Guide": (
+        "docs/08-existing-project-adoption.md"
+    ),
     "Delivery-Documentation-Guide": "docs/delivery/README.md",
     "Audience-Document-Template": (
         "docs/delivery/audience-document-template.md"
@@ -89,6 +92,18 @@ CORE_DOCUMENT_REQUIREMENTS = {
         "### 5. 确定交付对象和文档",
         "## 完成标准",
     ),
+    "docs/08-existing-project-adoption.md": (
+        "## 与新项目初始化的区别",
+        "## 接入前只读盘点",
+        "## 已有内容保护原则",
+        "## 增量接入顺序",
+        "## 冲突处理和停止条件",
+        "## 可复制 Agent 指令",
+        "### 只分析",
+        "### 方案确认后实施",
+        "## 最小验收清单",
+        "## 回退原则",
+    ),
     "docs/delivery/README.md": (
         "## 什么时候需要交付文档",
         "## 受众与文档选择",
diff --git a/docs/08-existing-project-adoption.md b/docs/08-existing-project-adoption.md
new file mode 100644
index 0000000..02631d0
--- /dev/null
+++ b/docs/08-existing-project-adoption.md
@@ -0,0 +1,165 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Existing-Project-Adoption-Guide
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Existing-Project-Adoption-Guide.-
+wiki_revision: cad12048c8aa6f54ec6d2595a79c814233e18285
+synchronized_at: 2026-08-10T06:59:09Z
+<!-- gitea-wiki-mirror:end -->
+
+# 已有项目接入 DevHarness 指南
+
+## 本页用途
+
+本页用于把 DevHarness 的文档模板和开发流程增量接入已经存在的项目。已有项目通常已经有代码、规则、文档、工单、Wiki、Git 历史和未完成工作，因此接入目标是补齐必要能力，不是把项目重置成 DevHarness 模板副本。
+
+接入必须先只读盘点、确认差异方案，再建立单元任务工单实施。未经确认不得覆盖、删除、重命名或批量迁移已有内容。
+
+## 与新项目初始化的区别
+
+| 场景 | 新项目初始化 | 已有项目接入 |
+|---|---|---|
+| 项目事实 | 从代码骨架和负责人确认开始建立 | 优先保留并核对已有事实 |
+| 规则文件 | 可以从模板建立第一版 | 必须合并已有规则，不能直接覆盖 |
+| 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 |
+| 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 |
+| Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 |
+| 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 |
+| 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 |
+
+从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。
+
+## 接入前只读盘点
+
+Agent 在提出方案前只读检查：
+
+- 根目录和相关子目录中的 `AGENTS.md`、`CLAUDE.md` 及其他 Agent 规则；
+- README、现有 `docs/`、Wiki 页面、工单模板和任务状态；
+- Git 默认分支、远端、提交历史、未提交修改和忽略规则；
+- 语言、框架、依赖、启动入口、主要模块和目录职责；
+- 格式检查、静态检查、单元测试和必要集成测试命令；
+- 配置、日志、接口、数据模型、权限、安全、部署和发布边界；
+- 已完成、进行中、阻塞和待验收任务；
+- 现有长期文档的事实来源、负责人和更新方式。
+
+输出时区分：
+
+1. 从代码、配置或现有系统确认的事实；
+2. 项目负责人确认的业务规则；
+3. 尚待确认的假设；
+4. DevHarness 与现有规则的冲突；
+5. 与接入无关、必须保留的工作区改动。
+
+只读盘点不授权修改文件、创建 Wiki、迁移文档或改变工单状态。
+
+## 已有内容保护原则
+
+- 保留 Git 历史、分支、标签和当前任务状态。
+- 保留已有 `AGENTS.md`、README、规则和项目专用红线；DevHarness 规则按冲突结果增量合并。
+- 保留与接入无关的未提交改动，不重置、不覆盖、不混入提交。
+- 不复制 DevHarness 的 `docs/task/`、任务归档映射和历史工单。
+- 不因采用 Wiki-first 就立即删除原本地文档；先逐页确认事实来源和迁移状态。
+- 不把模板占位值当成项目事实，不臆造技术栈、命令、业务规则、凭据或环境。
+- 不把密码、令牌、Cookie、私钥、个人数据或生产数据带入工单、Wiki和镜像。
+- 页面删除、重命名、历史清理和事实来源切换必须单独确认。
+
+## 增量接入顺序
+
+### 1. 确认差异方案
+
+根据盘点结果列出目标、非目标、复用项、改写项、冲突项、影响范围、风险、回退、验证和文档影响。方案得到用户明确确认前不实施。
+
+### 2. 建立单元任务工单
+
+使用目标项目的 Gitea 建立接入工单，记录原始需求、范围、依赖、方案和验收标准。目标项目没有可用 Gitea 时，先提交完整工单草稿并说明阻塞，不默认绕过。
+
+### 3. 接入共同规则和工单流程
+
+优先增量合并根规则、Claude 入口和单元任务模板。项目专用安全、业务和目录规则继续有效；冲突时由负责人决定最终表述。
+
+### 4. 确定长期文档事实来源
+
+为每份已有文档标记：
+
+- 保留在 Git：与特定代码版本强绑定；
+- 迁移到 Wiki：长期架构、业务规则、开发规范或操作说明；
+- 合并：内容重复但各有有效事实；
+- 暂不迁移：事实未确认或当前不影响接入；
+- 停止维护：必须由负责人确认，不能由 Agent 自行删除。
+
+切换到 Wiki-first 的页面必须先在线上创建或更新、读取确认，再建立 `wiki-docs.json` 映射并导出本地镜像。避免 Wiki 和手写本地文档长期形成双事实源。
+
+### 5. 接入 Harness 工具
+
+仅复制当前项目实际需要的 `dev_scripts/` 工具、配置和测试。业务脚本使用独立目录。根据目标项目调整核心页面、路径、命令和结构检查，不照搬 DevHarness 项目值。
+
+### 6. 分阶段验证
+
+先验证工单和规则入口，再验证 Wiki 映射，最后启用严格检查。每阶段采用“执行 → 首个真实错误 → 最小修复 → 继续”的闭环，不用一次接入全部旧文档。
+
+### 7. 提交和验收
+
+提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。
+
+## 冲突处理和停止条件
+
+出现以下情况时停止实施并请求负责人确认：
+
+- 现有规则与 DevHarness 的安全、权限、事实来源或验收规则冲突；
+- 无法判断某份文档应该保留、迁移、合并还是停止维护；
+- 需要删除、重命名 Wiki 页面、覆盖已有文件或清理历史归档；
+- 需要改变接口、数据库、权限、部署、发布或其他产品行为；
+- 工作区存在可能与接入文件重叠的未知修改；
+- Gitea、Wiki、凭据或远端权限不可用；
+- 真实命令、环境或业务规则无法从证据或负责人确认。
+
+相邻问题最多提示或另建工单，不混入接入任务。
+
+## 可复制 Agent 指令
+
+### 只分析
+
+```text
+请把 <DevHarness 路径> 的文档模板和开发流程接入当前已有项目。
+
+先只分析，不修改文件、工单或 Wiki：
+
+1. 阅读 DevHarness 的 AGENTS.md、README.md、项目档案、开发工作流、
+   新项目文档初始化和已有项目接入指南。
+2. 阅读当前项目已有的 Agent 规则、README、docs、Gitea 工单模板、
+   Wiki 配置、代码入口、测试命令和目录结构。
+3. 列出已有规则、文档、任务状态、Git 历史和未提交改动。
+4. 对比后列出可复用项、必须改写项、冲突项、旧文档处理方式、
+   最小接入范围、风险、回退、验证和文档影响。
+5. 不复制 DevHarness 任务归档，不覆盖、删除或重命名已有内容，
+   不把模板占位值当成项目事实。
+6. 输出方案后停止，等待我确认。
+```
+
+### 方案确认后实施
+
+```text
+按照已确认方案建工单并做。
+
+严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、
+任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出
+本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持
+为“待验收”；未经我明确验收，不关闭工单。
+```
+
+路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。
+
+## 最小验收清单
+
+- [ ] 已盘点规则、文档、任务、Git 历史和未提交改动。
+- [ ] 已明确复用、改写、冲突和暂不处理内容。
+- [ ] 已保留项目专用规则、历史和无关改动。
+- [ ] 未复制 DevHarness 历史归档或模板项目事实。
+- [ ] 已为每类长期文档明确事实来源和迁移状态。
+- [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。
+- [ ] Harness 检查已按目标项目调整并通过。
+- [ ] 必要测试、未验证部分、提交和归档证据已记录。
+- [ ] 工单处于待验收，未提前关闭。
+
+## 回退原则
+
+接入应拆成可回退的小提交。普通回退恢复本次新增或修改的规则、配置、检查和镜像映射，不触碰原有业务提交。Wiki 页面删除、重命名、历史清理或事实来源反向切换不是普通回退，必须另行建单并等待确认。
diff --git a/docs/README.md b/docs/README.md
index 10d6520..117b4e2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Home
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home
-wiki_revision: d7c0df9a900296850ca32296211504c5274c2b26
-synchronized_at: 2026-08-10T06:23:21Z
+wiki_revision: 55d89b7aec659f55a61e7ceef881ef34a62d9379
+synchronized_at: 2026-08-10T06:58:38Z
 <!-- gitea-wiki-mirror:end -->
 
 # DevHarness 文档中心
@@ -22,7 +22,7 @@ DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期
 6. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。
 7. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和归档流程。
 
-从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。
+从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)；向已有项目增量接入本流程时阅读[已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。
 
 ## 五分钟开始
 
@@ -49,6 +49,7 @@ python dev_scripts/sync_wiki_docs.py --check
 | 想做什么 | 先读哪里 | 主要验证 |
 |---|---|---|
 | 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 |
+| 接入已有项目 | Existing-Project-Adoption-Guide | 只读盘点、差异确认和分阶段验证 |
 | 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 Wiki 同步检查 |
 | 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 |
 | 修改同步行为 | `dev_scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 |
@@ -72,6 +73,7 @@ python dev_scripts/sync_wiki_docs.py --check
 
 - [Gitea 工单](http://ilaer.eicp.net:8418/opc/dev_harness/issues)
 - [代码仓库](http://ilaer.eicp.net:8418/opc/dev_harness)
+- [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)
 - [交付文档指南](Delivery-Documentation-Guide.-)
 - [岗位文档模板](Audience-Document-Template.-)
 - [任务归档模板](Task-Archive-Template.-)
diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py
index 9c02607..61a9b1f 100644
--- a/tests/test_harness_docs.py
+++ b/tests/test_harness_docs.py
@@ -43,6 +43,15 @@ class CoreDocumentTests(unittest.TestCase):
         for page, path in CORE_PAGE_PATHS.items():
             self.assertEqual(mappings.get(page), path)
 
+    def test_existing_project_adoption_guide_is_core_document(self) -> None:
+        path = "docs/08-existing-project-adoption.md"
+        self.assertEqual(
+            CORE_PAGE_PATHS.get("Existing-Project-Adoption-Guide"),
+            path,
+        )
+        self.assertIn(path, CORE_DOCUMENT_REQUIREMENTS)
+        self.assertIn("## 可复制 Agent 指令", CORE_DOCUMENT_REQUIREMENTS[path])
+
     def test_missing_or_wrong_core_mapping_is_reported(self) -> None:
         errors = core_mapping_errors({"Home": "docs/wrong.md"})
         self.assertTrue(any("Home -> docs/README.md" in error for error in errors))
diff --git a/wiki-docs.json b/wiki-docs.json
index 8d40897..d5d4468 100644
--- a/wiki-docs.json
+++ b/wiki-docs.json
@@ -40,6 +40,10 @@
       "page": "New-Project-Documentation-Setup",
       "path": "docs/07-new-project-documentation-setup.md"
     },
+    {
+      "page": "Existing-Project-Adoption-Guide",
+      "path": "docs/08-existing-project-adoption.md"
+    },
     {
       "page": "Delivery-Documentation-Guide",
       "path": "docs/delivery/README.md"