opc/dev_harness
2
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Task-1-Wiki-文档主源
Pages
Architecture-and-Code-Map Audience-Document-Template Business-Rules-and-Glossary Common-Changes Delivery-Documentation-Guide Development-Workflow Existing-Project-Adoption-Guide Home Local-Development-and-Verification New-Project-Documentation-Setup Project-Profile Task-1-Wiki-文档主源 Task-10-需求记录与流转规则 Task-11-交付文档指南与岗位文档模板 Task-12-已有项目接入DevHarness指南 Task-13-多子项目与独立交付单元 Task-14-任务归档按需导出 Task-15-开源建设基线评估 Task-16-DevHarness-后续升级与基线记录 Task-2-Junior-Maintainer-Docs Task-3-Dev-Scripts-Rename Task-4-Agent-Efficiency-Scope Task-5-Simplify-Agents Task-6-优化ClaudeCode规则入口 Task-7-ClaudeCode模型路由 Task-8-最小工单依赖规则 Task-9-Agent自然语言快捷指令 Task-Archive-Template Troubleshooting
Clone
4
Task-1-Wiki-文档主源
ila edited this page 2026-08-08 09:10:56 +08:00
Table of Contents

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)