opc/dev_harness
2
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-08-07 23:47:09 +08:00 by ila · 4 comments
ila commented 2026-08-07 23:47:09 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：无
  • 所属 MVP / 版本：无
  • 阶段：已完成

要解决什么

当前 DevHarness 以 Gitea 工单记录实施过程、以 Git 记录代码变更，并把长期文档直接维护在本地 docs/。需要引入 Gitea Wiki 管理长期开发文档：先修改线上 Wiki，再单向导出到本地 docs/，本地副本仅用于离线浏览和随代码审查。

做什么 / 不做什么

  • 做：
    • 明确工单、Wiki、Git 与本地 docs/ 的事实源边界。
    • 初始化 Wiki 中的项目档案、开发工作流、文档索引和任务归档模板。
    • 建立显式 Wiki 页面到本地路径的映射。
    • 提供 Wiki → docs/ 单向同步与校验工具，写入来源页面、revision 和同步时间。
    • 防止同步覆盖本地未提交的镜像改动。
    • 更新 Harness 规则、入口文档、检查脚本和任务归档流程。
  • 不做：
    • 不实现 docs/ → Wiki 反向同步。
    • 不自动删除或重命名 Wiki 页面。
    • 不把与具体代码版本强绑定的源码文档强制迁移到 Wiki。
    • 不关闭本工单；需用户验收后关闭。

已确认方案

  • Gitea 工单：任务状态、讨论、阻塞、验收过程的事实来源。
  • Gitea Wiki：架构说明、开发规范、操作手册和最终任务归档等长期文档的事实来源。
  • Git：源码及与特定代码版本强绑定文档的事实来源。
  • 本地 docs/：Wiki 的只读镜像。
  • 固定流程：修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像。
  • 同步采用显式映射并记录 Wiki revision；发现本地镜像存在未提交修改时停止。
  • Wiki 更新失败或镜像导出失败时不得把任务标为完成。

预计修改文件：

  • AGENTS.md
  • README.md
  • CLAUDE.md
  • docs/**
  • scripts/check_harness.py
  • scripts/new_task_archive.py
  • 新增 Wiki 映射、同步及测试相关文件

验收标准

  • Wiki 页面成为长期开发文档主源，本地 docs 明确标记为镜像。
  • 可通过一条命令从 Wiki 导出所有已映射页面。
  • 每个镜像包含来源页面、Wiki revision 和同步时间。
  • 本地镜像存在未提交修改时同步会安全停止。
  • 页面删除或重命名不会被同步工具自动传播。
  • Harness 严格检查与同步工具测试通过。
  • Wiki 内容、镜像内容和流程规则互相一致。

验证方式

python scripts/check_harness.py --strict
python -m unittest discover -s tests -v
python scripts/sync_wiki_docs.py --check

另人工核对 Wiki 页面修订记录、中文内容和页面链接。

风险和回退

风险：Wiki 与镜像短暂不一致；页面标题变更导致映射失效；覆盖人工编辑的本地镜像；最新 Wiki 与历史代码分支不匹配。

控制：显式映射、revision 元数据、Git 工作区保护、仅单向同步、删除/重命名需人工确认。

回退：通过 Git 提交恢复旧 Harness 规则；通过 Wiki revision 恢复线上页面；重新导出镜像。

## 基本信息 - 类型：需求 - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：已完成 ## 要解决什么 当前 DevHarness 以 Gitea 工单记录实施过程、以 Git 记录代码变更，并把长期文档直接维护在本地 `docs/`。需要引入 Gitea Wiki 管理长期开发文档：先修改线上 Wiki，再单向导出到本地 `docs/`，本地副本仅用于离线浏览和随代码审查。 ## 做什么 / 不做什么 - 做： - 明确工单、Wiki、Git 与本地 `docs/` 的事实源边界。 - 初始化 Wiki 中的项目档案、开发工作流、文档索引和任务归档模板。 - 建立显式 Wiki 页面到本地路径的映射。 - 提供 Wiki → `docs/` 单向同步与校验工具，写入来源页面、revision 和同步时间。 - 防止同步覆盖本地未提交的镜像改动。 - 更新 Harness 规则、入口文档、检查脚本和任务归档流程。 - 不做： - 不实现 `docs/` → Wiki 反向同步。 - 不自动删除或重命名 Wiki 页面。 - 不把与具体代码版本强绑定的源码文档强制迁移到 Wiki。 - 不关闭本工单；需用户验收后关闭。 ## 已确认方案 - Gitea 工单：任务状态、讨论、阻塞、验收过程的事实来源。 - Gitea Wiki：架构说明、开发规范、操作手册和最终任务归档等长期文档的事实来源。 - Git：源码及与特定代码版本强绑定文档的事实来源。 - 本地 `docs/`：Wiki 的只读镜像。 - 固定流程：修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像。 - 同步采用显式映射并记录 Wiki revision；发现本地镜像存在未提交修改时停止。 - Wiki 更新失败或镜像导出失败时不得把任务标为完成。 预计修改文件： - `AGENTS.md` - `README.md` - `CLAUDE.md` - `docs/**` - `scripts/check_harness.py` - `scripts/new_task_archive.py` - 新增 Wiki 映射、同步及测试相关文件 ## 验收标准 - [x] Wiki 页面成为长期开发文档主源，本地 docs 明确标记为镜像。 - [x] 可通过一条命令从 Wiki 导出所有已映射页面。 - [x] 每个镜像包含来源页面、Wiki revision 和同步时间。 - [x] 本地镜像存在未提交修改时同步会安全停止。 - [x] 页面删除或重命名不会被同步工具自动传播。 - [x] Harness 严格检查与同步工具测试通过。 - [x] Wiki 内容、镜像内容和流程规则互相一致。 ## 验证方式 ```powershell python scripts/check_harness.py --strict python -m unittest discover -s tests -v python scripts/sync_wiki_docs.py --check ``` 另人工核对 Wiki 页面修订记录、中文内容和页面链接。 ## 风险和回退 风险：Wiki 与镜像短暂不一致；页面标题变更导致映射失效；覆盖人工编辑的本地镜像；最新 Wiki 与历史代码分支不匹配。 控制：显式映射、revision 元数据、Git 工作区保护、仅单向同步、删除/重命名需人工确认。 回退：通过 Git 提交恢复旧 Harness 规则；通过 Wiki revision 恢复线上页面；重新导出镜像。
ila commented 2026-08-07 23:47:38 +08:00
Author
Owner
Copy Link
Copy Source

用户已确认方案，开始实施。已确认工作区干净、Wiki 已启用但尚未初始化；先创建线上 Wiki 页面，再建立本地只读镜像和同步校验工具。

用户已确认方案，开始实施。已确认工作区干净、Wiki 已启用但尚未初始化；先创建线上 Wiki 页面，再建立本地只读镜像和同步校验工具。
ila commented 2026-08-07 23:59:03 +08:00
Author
Owner
Copy Link
Copy Source

实现完成，进入待验收

最终方案

  • 建立 wiki-docs.json 显式映射，当前覆盖 Home、项目档案、开发工作流和任务归档模板。
  • 新增标准库实现的 Wiki API 客户端与单向同步器；读取支持公共仓库匿名降级，写入只接受环境变量 GITEA_TOKEN。
  • 镜像头记录页面、规范 URL、Wiki revision 和同步时间；revision 未变化时同步保持幂等。
  • 写入前使用 Git 检查所有映射路径，发现未提交改动即停止；映射仅允许 docs/ 下的 Markdown。
  • 页面缺失时明确失败，不自动删除、重命名或传播到本地。
  • 任务归档工具改为先创建 Wiki 页面，再追加显式映射并导出 docs/task。
  • Harness 严格检查会验证所有本地 Markdown 均已映射，且镜像元数据有效。
  • Gitea 1.25 为部分连字符页面生成带 .- 的 sub_url；同步器按 API 返回的规范地址解析，首页链接也已修正。

方案差异

  • 原设想读取 Wiki 可能需要固定令牌；实测仓库允许匿名读取，因此同步器优先使用环境令牌，遇到无效/异实例令牌导致的只读 401/403/404 时安全降级匿名读取。写操作不降级。
  • 未实现任何 Wiki 页面自动删除或重命名。

测试结果

  • python -m unittest discover -s tests -v：9 项通过。
  • python scripts/check_harness.py --strict：通过。
  • python scripts/sync_wiki_docs.py --check：4 个映射页面与 Wiki revision、正文一致。
  • python -m py_compile ...：通过。
  • git diff --check：通过。
  • 人工验证：中文 Wiki 内容可读取；Home 及三个带连字符页面规范 URL 均可访问；Wiki revision 可追踪。
  • 未验证部分：未使用真实写入 PAT 执行 new_task_archive.py，避免在正式 #1 归档外额外创建测试页面；本次正式归档将通过已配置的 Gitea MCP 完成等价写入。

实现提交

  • b08a919 feat: 引入 Wiki 文档镜像流程 (#1)
  • f1a7b09 docs: 同步 Wiki 文档镜像 (#1)
  • 8c52ea2 test: 覆盖 Wiki 镜像脏文件保护 (#1)

状态保持待验收，用户确认前不关闭。

## 实现完成，进入待验收 ### 最终方案 - 建立 `wiki-docs.json` 显式映射，当前覆盖 Home、项目档案、开发工作流和任务归档模板。 - 新增标准库实现的 Wiki API 客户端与单向同步器；读取支持公共仓库匿名降级，写入只接受环境变量 `GITEA_TOKEN`。 - 镜像头记录页面、规范 URL、Wiki revision 和同步时间；revision 未变化时同步保持幂等。 - 写入前使用 Git 检查所有映射路径，发现未提交改动即停止；映射仅允许 `docs/` 下的 Markdown。 - 页面缺失时明确失败，不自动删除、重命名或传播到本地。 - 任务归档工具改为先创建 Wiki 页面，再追加显式映射并导出 `docs/task`。 - Harness 严格检查会验证所有本地 Markdown 均已映射，且镜像元数据有效。 - Gitea 1.25 为部分连字符页面生成带 `.-` 的 `sub_url`；同步器按 API 返回的规范地址解析，首页链接也已修正。 ### 方案差异 - 原设想读取 Wiki 可能需要固定令牌；实测仓库允许匿名读取，因此同步器优先使用环境令牌，遇到无效/异实例令牌导致的只读 401/403/404 时安全降级匿名读取。写操作不降级。 - 未实现任何 Wiki 页面自动删除或重命名。 ### 测试结果 - `python -m unittest discover -s tests -v`：9 项通过。 - `python scripts/check_harness.py --strict`：通过。 - `python scripts/sync_wiki_docs.py --check`：4 个映射页面与 Wiki revision、正文一致。 - `python -m py_compile ...`：通过。 - `git diff --check`：通过。 - 人工验证：中文 Wiki 内容可读取；Home 及三个带连字符页面规范 URL 均可访问；Wiki revision 可追踪。 - 未验证部分：未使用真实写入 PAT 执行 `new_task_archive.py`，避免在正式 #1 归档外额外创建测试页面；本次正式归档将通过已配置的 Gitea MCP 完成等价写入。 ### 实现提交 - `b08a919` feat: 引入 Wiki 文档镜像流程 (#1) - `f1a7b09` docs: 同步 Wiki 文档镜像 (#1) - `8c52ea2` test: 覆盖 Wiki 镜像脏文件保护 (#1) 状态保持待验收，用户确认前不关闭。
ila referenced this issue from a commit 2026-08-08 00:03:06 +08:00
docs: 归档任务 #1
ila commented 2026-08-08 00:03:29 +08:00
Author
Owner
Copy Link
Copy Source

归档与推送完成

  • Wiki 归档：Task-1-Wiki-文档主源
  • Wiki revision：3d546bcad27498e7a263b0c4f124239490cc9f50
  • 本地镜像：docs/task/1-Wiki-文档主源.md
  • 归档提交：fec8e91、3aa73fc
  • 中文页面路径修复提交：1e3915b
  • 全部 6 个任务提交已推送到 origin/main，远端当前为 3aa73fc。
  • 验收标准已逐项勾选；工单继续保持“待验收”，未关闭。

实施中发现的工具边界

gitea_mcp 0.5.2.dev4 对 Gitea 返回的中文 sub_url 会再次百分号编码，按中文标题读取时可能 404；省略显式标题更新此类页面还可能把 .- 带入显示标题。本任务已在仓库同步客户端中保留已编码的 % 并增加回归测试，线上归档标题也已恢复。MCP 包自身尚未修改，后续如需彻底消除该限制，应在 opc/gitea_mcp 单独建单修复。

最终验证

  • 单元测试：10/10 通过。
  • Harness 严格检查：通过。
  • Wiki 镜像检查：5/5 一致。
  • git diff --check：通过。
  • 工作区：干净。
## 归档与推送完成 - Wiki 归档：[Task-1-Wiki-文档主源](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` - 本地镜像：`docs/task/1-Wiki-文档主源.md` - 归档提交：`fec8e91`、`3aa73fc` - 中文页面路径修复提交：`1e3915b` - 全部 6 个任务提交已推送到 `origin/main`，远端当前为 `3aa73fc`。 - 验收标准已逐项勾选；工单继续保持“待验收”，未关闭。 ### 实施中发现的工具边界 `gitea_mcp 0.5.2.dev4` 对 Gitea 返回的中文 `sub_url` 会再次百分号编码，按中文标题读取时可能 404；省略显式标题更新此类页面还可能把 `.-` 带入显示标题。本任务已在仓库同步客户端中保留已编码的 `%` 并增加回归测试，线上归档标题也已恢复。MCP 包自身尚未修改，后续如需彻底消除该限制，应在 `opc/gitea_mcp` 单独建单修复。 ### 最终验证 - 单元测试：10/10 通过。 - Harness 严格检查：通过。 - Wiki 镜像检查：5/5 一致。 - `git diff --check`：通过。 - 工作区：干净。
ila commented 2026-08-08 09:12:11 +08:00
Author
Owner
Copy Link
Copy Source

用户已于 2026-08-08 明确验收通过。Wiki 归档状态已更新为“已完成”，revision：dbbf9ddfb2e703486c7054f275538e8e03a570b3；本地镜像已通过提交 c69c0fd 推送到 main。本工单无父级 MVP/Epic，现按流程关闭。

用户已于 2026-08-08 明确验收通过。Wiki 归档状态已更新为“已完成”，revision：`dbbf9ddfb2e703486c7054f275538e8e03a570b3`；本地镜像已通过提交 `c69c0fd` 推送到 `main`。本工单无父级 MVP/Epic，现按流程关闭。
ila closed this issue 2026-08-08 09:12:14 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: opc/dev_harness#1