feat: 引入 Wiki 文档镜像流程 (#1)
This commit is contained in:
QiuSW
+37
-19
@@ -1,23 +1,32 @@
|
||||
<!-- gitea-wiki-mirror:start -->
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Project-Profile
|
||||
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Project-Profile.-
|
||||
wiki_revision: 845266496196a4fc33462dfda779d0f899fa4c18
|
||||
synchronized_at: 2026-08-07T15:53:58Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 项目档案
|
||||
|
||||
复制模板后先填写本页。这里保存不经常变化、所有维护者都需要知道的信息。
|
||||
本页记录不经常变化、所有维护者都需要知道的信息。它是项目档案的事实来源；仓库内 `docs/00-project-profile.md` 是只读镜像。
|
||||
|
||||
## 基本信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|---|---|
|
||||
| 项目名称 | `<填写>` |
|
||||
| 一句话目标 | `<填写>` |
|
||||
| Gitea 地址 | `<例如 https://gitea.example.com>` |
|
||||
| 仓库 | `<owner/repository>` |
|
||||
| 项目名称 | DevHarness |
|
||||
| 一句话目标 | 提供以 Gitea 工单、Wiki 和 Git 为事实来源的 AI 辅助开发工作流模板 |
|
||||
| Gitea 地址 | http://ilaer.eicp.net:8418 |
|
||||
| 仓库 | `opc/dev_harness` |
|
||||
| 默认分支 | `main` |
|
||||
| 主要维护者 | `<填写>` |
|
||||
| 主要维护者 | `ila` |
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 部分 | 技术 | 规则文件 |
|
||||
|---|---|---|
|
||||
| `<子项目或服务>` | `<语言、框架、版本>` | `<路径/AGENTS.md>` |
|
||||
| Harness 规则和模板 | Markdown、Gitea | `AGENTS.md` |
|
||||
| Wiki 镜像与结构检查 | Python 3 标准库 | `AGENTS.md` |
|
||||
|
||||
## 常用命令
|
||||
|
||||
@@ -25,26 +34,35 @@
|
||||
|
||||
| 用途 | 命令 | 预期结果 |
|
||||
|---|---|---|
|
||||
| 安装依赖 | `<填写>` | `<填写>` |
|
||||
| 启动开发环境 | `<填写>` | `<填写>` |
|
||||
| 格式检查 | `<填写>` | `<填写>` |
|
||||
| 静态检查 | `<填写>` | `<填写>` |
|
||||
| 单元测试 | `<填写>` | `<填写>` |
|
||||
| 集成测试 | `<填写或写“不适用”>` | `<填写>` |
|
||||
| 检查模板结构 | `python scripts/check_harness.py --strict` | 输出“DevHarness 检查通过” |
|
||||
| 运行单元测试 | `python -m unittest discover -s tests -v` | 所有测试通过 |
|
||||
| 导出 Wiki 镜像 | `python scripts/sync_wiki_docs.py` | 映射页面写入 `docs/` |
|
||||
| 检查 Wiki 镜像 | `python scripts/sync_wiki_docs.py --check` | 输出镜像与 Wiki 一致 |
|
||||
| 创建任务归档 | `python scripts/new_task_archive.py 123 "修复登录超时"` | 先创建 Wiki 归档页，再登记并导出本地镜像 |
|
||||
|
||||
## 目录边界
|
||||
|
||||
| 目录 | 职责 | 不应放入 |
|
||||
|---|---|---|
|
||||
| `<路径>` | `<填写>` | `<填写>` |
|
||||
| `.gitea/issue_template/` | Gitea 工单模板 | 凭据、任务最终归档 |
|
||||
| `docs/` | Wiki 自动导出的只读镜像 | 人工直接维护的长期文档 |
|
||||
| `docs/task/` | Wiki 任务归档页的只读镜像 | 讨论过程和临时方案 |
|
||||
| `scripts/` | Harness 检查、Wiki 同步和归档工具 | 产品功能代码 |
|
||||
| `tests/` | Harness 工具自动化测试 | 生产数据 |
|
||||
|
||||
## 环境与凭据
|
||||
|
||||
- 本地配置文件：`<填写>`
|
||||
- 配置示例文件：`<填写>`
|
||||
- 凭据保存位置：`<只写保存方式，不填写真实凭据>`
|
||||
- 日志和构建产物位置：`<填写>`
|
||||
- Wiki 同步配置：仓库根目录 `wiki-docs.json`。
|
||||
- Gitea 地址可由配置提供，也可通过 `GITEA_URL` 覆盖。
|
||||
- Gitea Personal Access Token 仅通过 `GITEA_TOKEN` 环境变量提供，不写入仓库。
|
||||
- Token 至少需要读取仓库权限；创建 Wiki 任务归档时还需要写仓库权限。
|
||||
- 日志和构建产物：本项目不持久化运行日志；Python 缓存不提交。
|
||||
|
||||
## 项目专用验收要求
|
||||
|
||||
- `<填写>`
|
||||
- 长期文档必须先更新 Wiki，再导出本地镜像。
|
||||
- 镜像必须包含来源页面、revision 和同步时间。
|
||||
- 页面删除、重命名和映射变更必须人工确认。
|
||||
- `python scripts/check_harness.py --strict` 必须通过。
|
||||
- `python -m unittest discover -s tests -v` 必须通过。
|
||||
- 未执行或无法覆盖的验证必须记录到工单。
|
||||
|
||||
+54
-18
@@ -1,14 +1,29 @@
|
||||
<!-- gitea-wiki-mirror:start -->
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Development-Workflow
|
||||
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.-
|
||||
wiki_revision: ae9f9aac5df77f1e3e1c2a34bd00c849c1f63cbf
|
||||
synchronized_at: 2026-08-07T15:54:03Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 开发工作流
|
||||
|
||||
## 事实来源边界
|
||||
|
||||
- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
|
||||
- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。
|
||||
- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
|
||||
- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
|
||||
|
||||
## 一次任务怎样完成
|
||||
|
||||
### 1. 讨论
|
||||
|
||||
用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍，让用户确认。
|
||||
用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。
|
||||
|
||||
### 2. 建单
|
||||
|
||||
方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码。
|
||||
方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。
|
||||
|
||||
新产品或较大版本先建立 Epic，再建立 MVP：
|
||||
|
||||
@@ -24,29 +39,49 @@
|
||||
|
||||
### 3. 实施
|
||||
|
||||
Agent 检查工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果它不影响当前验收，另建工单，不扩大当前任务。
|
||||
Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。
|
||||
|
||||
重要进度应及时写回工单：
|
||||
重要进度及时写回工单：
|
||||
|
||||
- 已确认的根因；
|
||||
- 方案或范围变化；
|
||||
- 测试结果；
|
||||
- 阻塞和未验证内容；
|
||||
- Git 提交哈希。
|
||||
- Git 提交哈希；
|
||||
- 相关 Wiki 页面及 revision。
|
||||
|
||||
长期文档遵循唯一顺序：
|
||||
|
||||
```text
|
||||
修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
|
||||
```
|
||||
|
||||
不得先编辑 `docs/` 再反向覆盖 Wiki。
|
||||
|
||||
### 4. 待验收
|
||||
|
||||
实现和测试完成后，Agent 提交代码并将工单更新为待验收。用户验收前工单保持开启。
|
||||
实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。
|
||||
|
||||
### 5. 归档和关闭
|
||||
|
||||
使用以下命令创建归档草稿：
|
||||
使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像：
|
||||
|
||||
```powershell
|
||||
python scripts/new_task_archive.py 123 "修复登录超时"
|
||||
```
|
||||
|
||||
填写实际结果后单独提交归档，再把路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
|
||||
归档内容以 Wiki 页面为主源；本地 `docs/task/<编号>-<短标题>.md` 是镜像。归档镜像单独提交，再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
|
||||
|
||||
## 文档同步规则
|
||||
|
||||
- 映射保存在 `wiki-docs.json`，每个 Wiki 页面对应唯一仓库路径。
|
||||
- 同步脚本只实现 Wiki → `docs/`，不提供反向同步。
|
||||
- 镜像头必须记录页面名、页面地址、revision 和同步时间。
|
||||
- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
|
||||
- `--check` 只检查，不写文件；页面缺失、revision 不一致或正文不一致均失败。
|
||||
- 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
|
||||
- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
|
||||
- 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。
|
||||
|
||||
## 什么时候重新确认方案
|
||||
|
||||
@@ -56,17 +91,18 @@ python scripts/new_task_archive.py 123 "修复登录超时"
|
||||
- 增加或删除接口、数据库字段或迁移；
|
||||
- 安全边界、权限或不可逆操作发生变化；
|
||||
- 原方案不可行，需要更换主要技术路线；
|
||||
- 任务范围明显扩大。
|
||||
- 任务范围明显扩大；
|
||||
- Wiki 页面删除、重命名或事实源边界改变。
|
||||
|
||||
普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。
|
||||
|
||||
## 工单与文档分别写什么
|
||||
## 工单、Wiki 与 Git 分别写什么
|
||||
|
||||
| 信息 | Gitea 工单 | `docs/task` |
|
||||
|---|---:|---:|
|
||||
| 讨论过程和临时方案 | 是 | 否 |
|
||||
| 实施进度和阻塞 | 是 | 否 |
|
||||
| 最终实现方案 | 是 | 是 |
|
||||
| 测试结果与未验证内容 | 是 | 是 |
|
||||
| 提交哈希 | 是 | 是 |
|
||||
| 长期有效的最终结论 | 可链接 | 是 |
|
||||
| 信息 | Gitea 工单 | Gitea Wiki | Git / `docs` 镜像 |
|
||||
|---|---:|---:|---:|
|
||||
| 讨论过程和临时方案 | 是 | 否 | 否 |
|
||||
| 实施进度和阻塞 | 是 | 否 | 否 |
|
||||
| 长期有效的最终方案 | 链接 | 是 | 镜像 |
|
||||
| 测试结果与未验证内容 | 是 | 任务归档 | 镜像 |
|
||||
| 提交哈希 | 是 | 任务归档 | 镜像 |
|
||||
| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |
|
||||
|
||||
+43
-6
@@ -1,8 +1,45 @@
|
||||
# 文档索引
|
||||
<!-- gitea-wiki-mirror:start -->
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Home
|
||||
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home
|
||||
wiki_revision: ff8425429da943ad2ce9380d950458dc49a72658
|
||||
synchronized_at: 2026-08-07T15:53:56Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
- [项目档案](00-project-profile.md)：仓库、技术栈、命令和负责人等稳定信息。
|
||||
- [开发工作流](01-workflow.md)：从需求讨论到工单关闭的完整顺序。
|
||||
- [任务归档模板](templates/task-archive.md)：任务完成后的固定格式。
|
||||
- `task/`：已经完成并与代码版本对应的任务记录。
|
||||
# DevHarness 文档中心
|
||||
|
||||
临时进度、方案讨论和待办事项写入 Gitea 工单，不写进长期文档。
|
||||
DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。
|
||||
|
||||
## 事实来源
|
||||
|
||||
| 信息 | 事实来源 |
|
||||
|---|---|
|
||||
| 任务状态、讨论、阻塞、验收过程 | Gitea 工单 |
|
||||
| 架构说明、开发规范、操作手册、任务归档 | Gitea Wiki |
|
||||
| 源码和与特定代码版本强绑定的文档 | Git 仓库 |
|
||||
| 离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 |
|
||||
|
||||
本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。
|
||||
|
||||
## 文档入口
|
||||
|
||||
- [项目档案](Project-Profile)
|
||||
- [开发工作流](Development-Workflow)
|
||||
- [任务归档模板](Task-Archive-Template)
|
||||
- [Gitea 工单](http://ilaer.eicp.net:8418/opc/dev_harness/issues)
|
||||
- [代码仓库](http://ilaer.eicp.net:8418/opc/dev_harness)
|
||||
|
||||
## 同步原则
|
||||
|
||||
固定顺序：
|
||||
|
||||
```text
|
||||
修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
|
||||
```
|
||||
|
||||
- 页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射。
|
||||
- 镜像头记录来源页面、Wiki revision 和同步时间。
|
||||
- 同步工具发现已跟踪镜像存在未提交修改时必须停止。
|
||||
- 页面删除、重命名和映射变更必须人工确认，不自动传播。
|
||||
- Wiki 或导出失败时，相关任务不能标记为完成。
|
||||
- 凭据、个人数据和生产数据不得进入 Wiki 或镜像。
|
||||
|
||||
Vendored
+10
@@ -1,3 +1,11 @@
|
||||
<!-- gitea-wiki-mirror:start -->
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Task-Archive-Template
|
||||
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-Archive-Template.-
|
||||
wiki_revision: 8f8d1bb9c596a79d37631d670aaf95818d74e7c8
|
||||
synchronized_at: 2026-08-07T15:54:05Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# <工单号> <标题>
|
||||
|
||||
- 类型：需求 / 缺陷 / 重构
|
||||
@@ -6,6 +14,8 @@
|
||||
- 状态：待验收 / 已完成
|
||||
- 日期：YYYY-MM-DD
|
||||
- Gitea 工单：<链接>
|
||||
- Wiki 页面：<页面名>
|
||||
- Wiki revision：见本地镜像头
|
||||
|
||||
## 背景与目标
|
||||
|
||||
|
||||
Reference in New Issue
Block a user