docs: support multi-project delivery units (#13)

2026-08-10 19:05:07 +08:00
parent 105328ee2e
commit 4e1db4558c
6 changed files with 115 additions and 14 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Project-Profile.-
-wiki_revision: 2a81c9e4508cf6594f90d0b54368ec1f8a3be220
-synchronized_at: 2026-08-08T01:16:47Z
+wiki_revision: c35c1737161ea428c487c066cb39eba4923535d2
+synchronized_at: 2026-08-10T11:02:51Z
 <!-- gitea-wiki-mirror:end -->

 # 项目档案
@@ -23,6 +23,18 @@ synchronized_at: 2026-08-08T01:16:47Z
 | 主要维护者 | `ila` |
 | 文档适用范围 | 默认分支当前版本；具体镜像 revision 见每个本地文件头 |

+## 子项目与交付单元
+
+“子项目”是仓库中具有明确职责和规则边界的应用或模块；“交付单元”是能够独立构建、测试、版本化或发布的程序、服务、库或文档包。一个子项目可以对应一个交付单元，也可以包含多个交付单元。
+
+| 子项目 / 交付单元 | 职责 | 技术栈 | 构建与测试 | 版本与发布方式 | 规则入口 | 共享边界 |
+|---|---|---|---|---|---|---|
+| DevHarness 模板 | 提供 Agent 开发流程、Wiki 镜像和结构检查 | Markdown、Python 3 标准库、Gitea 1.25 | `python dev_scripts/check_harness.py --strict`；`python -m unittest discover -s tests -v` | 跟随仓库 `main` 分支，不单独发布产品程序 | 根目录 `AGENTS.md` | Gitea 工单、Wiki、Git 和 `docs/` 的事实来源边界 |
+
+单应用项目只填写一行。多应用单仓库必须逐个填写，并为技术栈、构建测试或安全规则不同的目录增加子目录 `AGENTS.md`。技术栈不同不等于必须拆分 Git 仓库；是否拆仓应根据团队、权限、发布周期、仓库效率、复用关系和共享接口稳定性判断。
+
+跨子项目接口或契约必须指定唯一事实来源，并说明各交付单元的兼容范围和验证命令。不得在多个页面维护互不确认的“权威版本”。
+
 ## 技术栈与运行环境

 | 部分 | 技术 | 规则文件 |
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: New-Project-Documentation-Setup
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/New-Project-Documentation-Setup.-
-wiki_revision: 710503a62b7a4ebd3c9d7a1a08dbd398161595d0
-synchronized_at: 2026-08-10T06:23:35Z
+wiki_revision: a443c206780ecd40ae45732ca10686427f393349
+synchronized_at: 2026-08-10T11:03:03Z
 <!-- gitea-wiki-mirror:end -->

 # 新项目文档初始化
@@ -26,11 +26,25 @@ synchronized_at: 2026-08-10T06:23:35Z

 把项目专用红线写入根目录或子目录 `AGENTS.md`。

-### 2. 建立 Gitea
+### 2. 识别子项目与交付单元
+
+先判断仓库中有几个应用、服务、客户端、库或其他可独立交付的部分。对每个部分确认：
+
+- 职责和目录边界；
+- 技术栈、依赖和支持环境；
+- 构建、测试和运行命令；
+- 是否拥有独立版本号和发布方式；
+- 适用的根目录或子目录 `AGENTS.md`；
+- 与其他子项目共享的接口、数据或业务流程；
+- 共享契约的唯一事实来源和兼容要求。
+
+把结果写入 Project-Profile 的“子项目与交付单元”。单应用项目只填写一个交付单元；多应用单仓库为规则不同的目录增加子目录 `AGENTS.md`，但不因为技术栈不同自动拆仓，也不强制统一版本和发布周期。
+
+### 3. 建立 Gitea

 创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。

-### 3. 修改镜像配置
+### 4. 修改镜像配置

 把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；核心主题映射保留。

@@ -38,7 +52,7 @@ synchronized_at: 2026-08-10T06:23:35Z

 不要把 PAT 写入配置。

-### 4. Agent 检查项目事实
+### 5. Agent 检查项目事实

 Agent 只读检查：

@@ -51,7 +65,7 @@ Agent 只读检查：

 区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。

-### 5. 确定交付对象和文档
+### 6. 确定交付对象和文档

 由项目负责人确认哪些岗位或客户会实际使用、部署、管理、支持、集成或验收产品，并为每类对象确定：

@@ -63,7 +77,7 @@ Agent 只读检查：

 按照[交付文档指南](Delivery-Documentation-Guide.-)选择文档，使用[岗位文档模板](Audience-Document-Template.-)按需创建。没有明确读者的文档不创建，不预建空白的用户手册、管理员手册或运维手册。

-### 6. 先创建线上 Wiki
+### 7. 先创建线上 Wiki

 至少创建或填写：

@@ -81,7 +95,7 @@ Agent 只读检查：

 Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。具体岗位文档仅按第 5 步确认的受众创建。

-### 7. 人工确认
+### 8. 人工确认

 项目负责人至少确认：

@@ -92,7 +106,7 @@ Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图
 - 哪些修改属于高风险；
 - 交付对象、文档可见范围和外部信息边界。

-### 8. 导出镜像并检查
+### 9. 导出镜像并检查

 ```powershell
 python dev_scripts/sync_wiki_docs.py
@@ -112,6 +126,8 @@ python -m unittest discover -s tests -v
 - 常用功能从哪个目录和入口开始读；
 - 一个简单修改通常要改哪里、验证什么；
 - 哪些情况必须停止并交给 Agent 或负责人；
+- 项目包含哪些子项目和独立交付单元，各自怎样构建、测试和发布；
+- 跨子项目共享什么接口或契约，其唯一事实来源在哪里；
 - 项目需要向哪些岗位交付什么文档，以及哪些内容不能对外提供。

 回答不了的问题应继续补充主题文档，而不是堆入任务归档。
@@ -2,8 +2,8 @@
 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
+wiki_revision: 5c187a1d1cc215c632fcc26b2a4c6df735af5d92
+synchronized_at: 2026-08-10T11:03:05Z
 <!-- gitea-wiki-mirror:end -->

 # 已有项目接入 DevHarness 指南
@@ -62,6 +62,39 @@ Agent 在提出方案前只读检查：
 - 不把密码、令牌、Cookie、私钥、个人数据或生产数据带入工单、Wiki和镜像。
 - 页面删除、重命名、历史清理和事实来源切换必须单独确认。

+## 多应用单仓库判断
+
+一个 Git 仓库可以包含多个技术栈不同、能够独立构建和发布的应用或终端。技术栈不同本身不是拆仓理由；先把每个子项目和交付单元记录到 Project-Profile，再根据实际协作边界判断。
+
+### 适合继续单仓库
+
+- 多个应用共同完成一条产品或业务链路；
+- 由同一团队维护，仓库权限基本一致；
+- 接口变更需要在一个工单中同步修改或验证多端；
+- 共享契约、业务规则和任务归档放在一起更容易保持一致；
+- 仓库体积、测试时间和工具性能尚未明显影响开发；
+- 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。
+
+### 可以考虑拆仓
+
+- 长期由不同团队独立负责并需要不同访问权限；
+- 发布周期、版本策略和验收负责人已经完全独立；
+- 某个应用被多个产品复用或需要单独对外提供；
+- 仓库体积、检出、索引或测试耗时已经持续影响效率；
+- 共享接口已经版本化、兼容周期明确，并有跨仓契约测试；
+- 跨应用任务很少，拆仓后的协调成本低于继续共仓。
+
+不满足这些条件时，优先保持单仓库并完善边界，不为了目录整洁或技术栈不同而拆仓。
+
+### 保持单仓库时的最小规则
+
+- 根目录 `AGENTS.md` 只放共同流程、安全和跨项目规则，技术栈专用规则写入子目录 `AGENTS.md`。
+- 每个交付单元拥有自己的构建、测试、版本和发布方式，不强制统一版本。
+- 单元任务必须声明只影响哪个子项目、是否跨子项目、是否修改共享接口，以及各端需要执行的验证。
+- 共享接口或契约只能指定一个事实来源；其他文档引用它，不复制一个“差不多”的版本。
+- 跨子项目契约变更在同一工单中更新事实来源，并验证所有受影响端。
+- 拆仓属于事实来源、任务和发布边界变化，必须另建工单、确认迁移和回退方案后实施。
+
 ## 增量接入顺序

 ### 1. 确认差异方案
@@ -151,6 +184,8 @@ Agent 在提出方案前只读检查：
 ## 最小验收清单

 - [ ] 已盘点规则、文档、任务、Git 历史和未提交改动。
+- [ ] 已识别所有子项目和独立交付单元。
+- [ ] 跨子项目共享契约已经指定唯一事实来源。
 - [ ] 已明确复用、改写、冲突和暂不处理内容。
 - [ ] 已保留项目专用规则、历史和无关改动。
 - [ ] 未复制 DevHarness 历史归档或模板项目事实。