dev_harness/docs/task/1-Wiki-文档主源.md

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: dbbf9ddfb2e703486c7054f275538e8e03a570b3 synchronized_at: 2026-08-08T01:11:20Z

1 引入 Gitea Wiki 作为长期开发文档主源

• 类型：需求
• 所属 Epic：无
• 所属 MVP / 版本：无
• 状态：已完成
• 日期：2026-08-07
• Gitea 工单：opc/dev_harness#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)