OPC/dev_harness
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: require online Wiki initialization before coding (#20)

Browse Source
This commit is contained in:
QiuSW
2026-08-17 11:24:16 +08:00
parent b1f500128d
commit 89ca159b60
7 changed files with 99 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-workflow.md
+13 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Development-Workflow
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.-
wiki_revision: 3fa437209777476101dc709444c4fe7a0015b76a
synchronized_at: 2026-08-17T02:17:54Z
wiki_revision: a9f7cf4014129840e0772b8f951da82b9573e4e5
synchronized_at: 2026-08-17T03:21:38Z
<!-- gitea-wiki-mirror:end -->
# 开发工作流
@@ -15,6 +15,17 @@ synchronized_at: 2026-08-17T02:17:54Z
- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
## 新项目 Wiki 初始化门禁
从 DevHarness 创建新项目时，本地 `docs/` 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：
1. 先创建 Gitea 远端仓库并启用 Wiki，再把 `wiki-docs.json` 指向该仓库。
2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
3. 查询线上页面列表；没有 `Home` 时先创建 `Home`，回读正文并记录 revision，然后再创建或更新其他核心映射页面。
4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 `docs/` 文件替代这项证据。
5. 运行 `python dev_scripts/sync_wiki_docs.py`、`python dev_scripts/check_harness.py --strict` 和 `python dev_scripts/sync_wiki_docs.py --check`。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。
Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。
## 工单与设计证据双门禁
开始正式实现前依次判断“是否需要工单”和“需要什么设计证据”。原型确认不能代替方案、工单、安全检查或技术验证；工单存在也不能绕过原型确认。
docs/07-new-project-documentation-setup.md
+14 -3
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: New-Project-Documentation-Setup
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/New-Project-Documentation-Setup.-
wiki_revision: 8c70a393a0537b94091224d00363fc61edadb1b6
synchronized_at: 2026-08-17T01:58:11Z
wiki_revision: 47b78d0fcba529ad677b8d208da4b5f1b2ccc971
synchronized_at: 2026-08-17T03:21:52Z
<!-- gitea-wiki-mirror:end -->
# 新项目文档初始化
@@ -102,7 +102,9 @@ synchronized_at: 2026-08-17T01:58:11Z
### 4. 建立 Gitea
创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。
创建远端仓库并完成允许的初始引导提交，开启工单和 Wiki；必须先有远端仓库，才能填写该仓库的线上 Wiki。配置项目已有的 Gitea MCP 和安全凭据；优先使用 MCP，MCP 不可用或不支持所需写操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只通过环境或 MCP 安全配置提供。
任何产品功能开发在引导提交后都必须先有单元任务工单，并且必须通过第 8 步的线上 Wiki 初始化门禁。
### 5. 修改镜像配置
@@ -139,6 +141,13 @@ Agent 只读检查：
### 8. 先创建线上 Wiki
#### 在线创建与回读门禁
1. 使用配置好的 Gitea MCP 查询目标仓库的 Wiki 页面列表；MCP 不可用时使用 Gitea API，并记录回退原因。
2. 如果 `Home` 不存在，先创建 `Home`。创建后立即在线回读正文并记录 revision；`Home` 可读取后才能继续。
3. 依照 `wiki-docs.json` 逐页创建或更新其他核心页面。每页写入后在线回读正文，记录页面名和 revision。
4. 本地 `docs/` 是模板或 Wiki 镜像；本地文件存在、标题完整或 `check_harness.py --strict` 通过，都不能单独证明线上 Wiki 已初始化。
5. 页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码；Gitea 恢复后从首个失败页面继续。
至少创建或填写：
1. Home；
@@ -178,6 +187,8 @@ python -m unittest discover -s tests -v
只有线上 Wiki 确认后才导出核心 `docs/`。任务归档默认不导出；用户明确要求时再运行 `python dev_scripts/export_task_archives.py` 或加 `--all`。旧项目的任务归档快照不能带入新项目历史。
`sync_wiki_docs.py --check` 会在线读取全部显式映射页面；任一页面不存在、无法读取或 revision 与镜像不一致时，初始化不通过。只有上述命令全部成功后才允许开始产品代码。
## 完成标准
初级程序员应能仅依靠 Home 和链接页面回答：
docs/09-product-requirements-overview.md
+3 -3
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Product-Requirements-Overview
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Product-Requirements-Overview.-
wiki_revision: 1cf7515c3dd9d98f633cdb7fad27113c11449e5b
synchronized_at: 2026-08-17T02:32:05Z
wiki_revision: 0d4b83f7e4d600614f5067fbec667d158a870d01
synchronized_at: 2026-08-17T03:21:58Z
<!-- gitea-wiki-mirror:end -->
# 产品需求总览
@@ -31,7 +31,7 @@ synchronized_at: 2026-08-17T02:32:05Z
| 需求领域 | 用户与场景 | 状态 | 版本 / MVP | 详细说明 | 实施工单 | 原型 | 验收入口 |
|---|---|---|---|---|---|---|---|
| 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯 | 已交付 | 模板核心 | [开发工作流](Development-Workflow.-) | [#1](https://git.ilapage.cn/OPC/dev_harness/issues/1)、[#10](https://git.ilapage.cn/OPC/dev_harness/issues/10)、[#14](https://git.ilapage.cn/OPC/dev_harness/issues/14) | 无（流程文档） | [#1 归档](Task-1-Wiki-文档主源)、[#10 归档](Task-10-需求记录与流转规则)、[#14 归档](Task-14-任务归档按需导出) |
| 文档事实来源与需求追溯 | 负责人和 Agent 需要从需求到实现、验收可追溯 | 开发中（Wiki 初始化门禁） | 模板核心 | [开发工作流](Development-Workflow.-) | [#1](https://git.ilapage.cn/OPC/dev_harness/issues/1)、[#10](https://git.ilapage.cn/OPC/dev_harness/issues/10)、[#14](https://git.ilapage.cn/OPC/dev_harness/issues/14)、[#20](https://git.ilapage.cn/OPC/dev_harness/issues/20) | 无（流程文档） | [#1 归档](Task-1-Wiki-文档主源)、[#10 归档](Task-10-需求记录与流转规则)、[#14 归档](Task-14-任务归档按需导出) |
| 初级维护者文档 | 初级程序员需要理解项目并处理简单修改 | 已交付 | 模板核心 | [项目档案](Project-Profile.-)、[代码地图](Architecture-and-Code-Map.-)、[常见修改](Common-Changes.-) | [#2](https://git.ilapage.cn/OPC/dev_harness/issues/2)、[#3](https://git.ilapage.cn/OPC/dev_harness/issues/3) | 无（流程文档） | [#2 归档](Task-2-Junior-Maintainer-Docs)、[#3 归档](Task-3-Dev-Scripts-Rename) |
| Agent 范围、效率和 Claude 协作 | Agent 按确认范围实施并选择合适模型 | 已交付（原型门禁） | 模板核心 | [开发工作流](Development-Workflow.-)、仓库 `AGENTS.md` 和 `CLAUDE.md` | [#4](https://git.ilapage.cn/OPC/dev_harness/issues/4)–[#9](https://git.ilapage.cn/OPC/dev_harness/issues/9)、[#19](https://git.ilapage.cn/OPC/dev_harness/issues/19) | 无（流程文档） | 对应 `Task-4` 至 `Task-9` Wiki 归档；[#19 归档](Task-19-UI原型确认与文字修改双门禁) |
| 交付文档 | 其他岗位和客户需要与版本匹配的使用、部署或支持说明 | 待验收 | 模板核心 | [交付文档指南](Delivery-Documentation-Guide.-)、[岗位文档模板](Audience-Document-Template.-) | [#11](https://git.ilapage.cn/OPC/dev_harness/issues/11) | 无（文档模板） | [#11 归档](Task-11-交付文档指南与岗位文档模板) |