<!-- 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)