83 lines
4.1 KiB
Markdown
83 lines
4.1 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
|
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
|
wiki_page: Task-1-Wiki-文档主源
|
|
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-1-Wiki-%E6%96%87%E6%A1%A3%E4%B8%BB%E6%BA%90.-
|
|
wiki_revision: 3d546bcad27498e7a263b0c4f124239490cc9f50
|
|
synchronized_at: 2026-08-07T16:01:58Z
|
|
<!-- gitea-wiki-mirror:end -->
|
|
|
|
# 1 引入 Gitea Wiki 作为长期开发文档主源
|
|
|
|
- 类型：需求
|
|
- 所属 Epic：无
|
|
- 所属 MVP / 版本：无
|
|
- 状态：待验收
|
|
- 日期：2026-08-07
|
|
- Gitea 工单：[opc/dev_harness#1](http://ilaer.eicp.net:8418/opc/dev_harness/issues/1)
|
|
- Wiki 页面：Task-1-Wiki-文档主源
|
|
- Wiki revision：见本地镜像头
|
|
|
|
## 背景与目标
|
|
|
|
DevHarness 原来使用 Gitea 工单记录实施过程、使用 Git 记录代码，并把完成后的长期文档直接维护在本地 `docs/`。本任务引入 Gitea Wiki 作为长期开发文档的事实来源，本地 `docs/` 改为仅供离线浏览和代码审查的只读镜像。
|
|
|
|
## 最终方案
|
|
|
|
- Gitea 工单管理任务状态、讨论、阻塞、验证和验收过程。
|
|
- Gitea Wiki 管理架构说明、开发规范、操作手册和任务归档。
|
|
- Git 管理源码、版本绑定资料以及 Wiki 镜像。
|
|
- `wiki-docs.json` 显式登记 Wiki 页面与本地路径，映射仅允许写入 `docs/` 下的 Markdown。
|
|
- `scripts/sync_wiki_docs.py` 只实现 Wiki → docs；镜像记录页面、规范 URL、revision 和同步时间。
|
|
- 同步前检查所有映射镜像的 Git 状态，发现未提交改动立即停止。
|
|
- 页面缺失、删除或重命名时同步失败，不自动传播破坏性变化。
|
|
- `scripts/new_task_archive.py` 改为先创建 Wiki 归档，再登记映射并导出本地镜像。
|
|
- `scripts/check_harness.py --strict` 同时检查项目档案、映射完整性和镜像元数据。
|
|
|
|
Gitea 1.25 会为部分带连字符页面生成带 `.-` 的规范 `sub_url`；客户端先按标题查询页面列表，再使用服务端返回的 `sub_url` 读取内容和构造链接。
|
|
|
|
## 修改文件
|
|
|
|
- `AGENTS.md`：更新事实源、实施、归档与安全规则。
|
|
- `CLAUDE.md`：更新 Agent 文档读取和归档入口。
|
|
- `README.md`：更新工作闭环、目录和快速开始说明。
|
|
- `wiki-docs.json`：新增 Wiki 页面显式映射。
|
|
- `scripts/wiki_docs.py`：实现配置校验、Gitea API、镜像生成、脏文件保护和一致性检查。
|
|
- `scripts/sync_wiki_docs.py`：新增单向同步命令。
|
|
- `scripts/new_task_archive.py`：改为在线优先的任务归档流程。
|
|
- `scripts/check_harness.py`：增加映射和镜像元数据检查。
|
|
- `tests/test_wiki_docs.py`：覆盖映射、元数据、幂等、路径限制和脏文件保护。
|
|
- `docs/**`：由 Wiki 导出的只读镜像。
|
|
|
|
## 验收结果
|
|
|
|
| 验收标准 | 结果 |
|
|
|---|---|
|
|
| Wiki 是长期开发文档主源，docs 明确为镜像 | 通过 |
|
|
| 一条命令导出全部映射页面 | 通过 |
|
|
| 镜像包含页面、URL、revision 和同步时间 | 通过 |
|
|
| 未提交镜像改动会阻止覆盖 | 通过 |
|
|
| 删除或重命名不会自动传播 | 通过 |
|
|
| 严格检查和测试通过 | 通过 |
|
|
| Wiki、镜像和流程规则一致 | 通过 |
|
|
|
|
## 测试
|
|
|
|
- 执行命令：`python -m unittest discover -s tests -v`
|
|
- 结果：10 项测试通过。
|
|
- 执行命令：`python scripts/check_harness.py --strict`
|
|
- 结果：通过。
|
|
- 执行命令：`python scripts/sync_wiki_docs.py --check`
|
|
- 结果：映射页面的 revision 和正文均一致。
|
|
- 执行命令：`python -m py_compile scripts/check_harness.py scripts/wiki_docs.py scripts/sync_wiki_docs.py scripts/new_task_archive.py tests/test_wiki_docs.py`
|
|
- 结果：通过。
|
|
- 执行命令：`git diff --check`
|
|
- 结果：通过。
|
|
- **未验证部分**：未用独立测试 PAT 调用 `new_task_archive.py` 创建额外测试页面；正式 #1 归档通过同一 Gitea API 的 MCP 写入并导出验证。
|
|
|
|
## 相关提交
|
|
|
|
- `b08a919` feat: 引入 Wiki 文档镜像流程 (#1)
|
|
- `f1a7b09` docs: 同步 Wiki 文档镜像 (#1)
|
|
- `8c52ea2` test: 覆盖 Wiki 镜像脏文件保护 (#1)
|
|
- `1e3915b` fix: 支持中文 Wiki 页面路径 (#1)
|