优化核心 Wiki 镜像的增量同步性能 #29

New Issue

2026-09-02T09:33:05+08:00

ila commented

2026-09-02 09:33:05 +08:00

基本信息

类型：单元任务
阶段：待验收
原始需求来源：当前对话，2026-09-02
关键需求摘要：实际使用中同步 Wiki 很慢；采用已确认的最小增量同步方案，减少重复网络请求。
前置工单：无
是否允许并行：是；与待验收 #28 无代码依赖，若发生文件冲突则保持提交边界。
设计证据：无 UI；采用已确认的同步算法方案。

目标

一次同步只读取一次 Wiki 页面列表。
复用页面元数据中的 revision，只下载新增或 revision 变化的核心页面。
为需要逐页正文核对的场景提供显式深度检查。
避免 sync --verify 在同一次运行中重复下载页面。
保持 Wiki 为长期文档事实来源、本地 docs/ 为只读镜像。

非目标

不取消本地核心镜像。
不增加数据库、后台服务或额外缓存文件。
不并行轰炸 Gitea，不依赖 ETag。
不修改任务归档的人工触发边界。
不更新无关 Wiki 页面。

已确认方案

sync：先读取一次页面列表，比较远端 last_commit.sha 与本地镜像 wiki_revision，仅获取变化页面正文。
sync --check：快速检查远端 revision、本地镜像状态和必要一致性；不下载 revision 未变化的正文。
新增 sync --deep-check：显式下载全部映射页面正文并逐页比较。
sync --verify：用于初始化门禁，执行深度验证，但复用本轮已读取数据，避免先同步后再次下载。
保留未提交镜像保护、页面缺失和 revision 缺失时停止等现有安全边界。
更新长期工作流 Wiki，回读后同步对应本地核心镜像。

影响范围

dev_scripts/wiki_docs.py
dev_scripts/harness.py
相关单元测试
Gitea Wiki：Development-Workflow（如命令语义需要长期说明）
对应本地核心镜像
AGENTS.md、CLAUDE.md 中受影响的快捷命令说明

风险与回退

风险：仅按 revision 快速判断可能漏掉本地内容被异常改写；通过工作区保护及显式深度检查控制。
风险：不同 Gitea 返回的页面元数据可能缺少 revision；缺失时回退下载正文，不静默跳过。
回退：恢复全量正文读取逻辑；不涉及远端页面删除、数据迁移或不可逆操作。

验证

单元测试覆盖：页面列表只请求一次、未变化跳过正文、变化页面下载、revision 缺失回退、深度检查全量读取、verify 不重复读取、脏镜像保护。
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
对实际 Wiki 执行快速检查与深度检查并记录耗时/结果。

文档影响

若命令语义变化，先更新 Development-Workflow Wiki，在线回读 revision 后同步核心镜像。
更新共享 Agent 快捷命令说明，保证 Codex 与 Claude Code一致。
默认不创建任务快照。

验收标准

15 个核心页面的一次操作只获取一次页面列表。
revision 未变化的页面不下载正文。
revision 变化、缺失或本地元数据无效时获取正文并正确处理。
sync --deep-check 能逐页核对正文。
sync --verify 不在同次运行重复获取相同页面正文。
不削弱脏镜像、缺页、revision 和 Wiki 主源边界。
严格检查、单元测试及实际 Wiki 快速/深度检查通过。
代码与必要文档提交推送，证据回写后保持待验收。

## 基本信息 - 类型：单元任务 - 阶段：待验收 - 原始需求来源：当前对话，2026-09-02 - 关键需求摘要：实际使用中同步 Wiki 很慢；采用已确认的最小增量同步方案，减少重复网络请求。 - 前置工单：无 - 是否允许并行：是；与待验收 #28 无代码依赖，若发生文件冲突则保持提交边界。 - 设计证据：无 UI；采用已确认的同步算法方案。 ## 目标 - 一次同步只读取一次 Wiki 页面列表。 - 复用页面元数据中的 revision，只下载新增或 revision 变化的核心页面。 - 为需要逐页正文核对的场景提供显式深度检查。 - 避免 `sync --verify` 在同一次运行中重复下载页面。 - 保持 Wiki 为长期文档事实来源、本地 `docs/` 为只读镜像。 ## 非目标 - 不取消本地核心镜像。 - 不增加数据库、后台服务或额外缓存文件。 - 不并行轰炸 Gitea，不依赖 ETag。 - 不修改任务归档的人工触发边界。 - 不更新无关 Wiki 页面。 ## 已确认方案 1. `sync`：先读取一次页面列表，比较远端 `last_commit.sha` 与本地镜像 `wiki_revision`，仅获取变化页面正文。 2. `sync --check`：快速检查远端 revision、本地镜像状态和必要一致性；不下载 revision 未变化的正文。 3. 新增 `sync --deep-check`：显式下载全部映射页面正文并逐页比较。 4. `sync --verify`：用于初始化门禁，执行深度验证，但复用本轮已读取数据，避免先同步后再次下载。 5. 保留未提交镜像保护、页面缺失和 revision 缺失时停止等现有安全边界。 6. 更新长期工作流 Wiki，回读后同步对应本地核心镜像。 ## 影响范围 - `dev_scripts/wiki_docs.py` - `dev_scripts/harness.py` - 相关单元测试 - Gitea Wiki：Development-Workflow（如命令语义需要长期说明） - 对应本地核心镜像 - `AGENTS.md`、`CLAUDE.md` 中受影响的快捷命令说明 ## 风险与回退 - 风险：仅按 revision 快速判断可能漏掉本地内容被异常改写；通过工作区保护及显式深度检查控制。 - 风险：不同 Gitea 返回的页面元数据可能缺少 revision；缺失时回退下载正文，不静默跳过。 - 回退：恢复全量正文读取逻辑；不涉及远端页面删除、数据迁移或不可逆操作。 ## 验证 - 单元测试覆盖：页面列表只请求一次、未变化跳过正文、变化页面下载、revision 缺失回退、深度检查全量读取、verify 不重复读取、脏镜像保护。 - `python dev_scripts/harness.py check --strict` - `python -m unittest discover -s tests -v` - 对实际 Wiki 执行快速检查与深度检查并记录耗时/结果。 ## 文档影响 - 若命令语义变化，先更新 Development-Workflow Wiki，在线回读 revision 后同步核心镜像。 - 更新共享 Agent 快捷命令说明，保证 Codex 与 Claude Code一致。 - 默认不创建任务快照。 ## 验收标准 - [ ] 15 个核心页面的一次操作只获取一次页面列表。 - [ ] revision 未变化的页面不下载正文。 - [ ] revision 变化、缺失或本地元数据无效时获取正文并正确处理。 - [ ] `sync --deep-check` 能逐页核对正文。 - [ ] `sync --verify` 不在同次运行重复获取相同页面正文。 - [ ] 不削弱脏镜像、缺页、revision 和 Wiki 主源边界。 - [ ] 严格检查、单元测试及实际 Wiki 快速/深度检查通过。 - [ ] 代码与必要文档提交推送，证据回写后保持待验收。

ila referenced this issue from a commit

2026-09-02 09:38:10 +08:00

perf: 优化 Wiki 镜像增量同步 (#29)

ila commented

2026-09-02 09:38:37 +08:00

最终实施证据

状态：待验收
实现提交：cbdd27d8618efdd744c4fa90f0f26e72fd9ebec3，已推送到 origin/main
最终差异：
- 核心同步整轮只调用一次页面列表接口；
- sync 与 sync --check 按远端 revision 增量判断，未变化页面不下载正文；
- revision 变化/缺失或本地镜像元数据无效时回退读取完整页面；
- 新增 sync --deep-check 全量正文审计；
- sync --verify 完整读取一次后复用结果，不再重复下载；
- 更新共享 Agent 命令说明及 Development-Workflow Wiki/本地镜像。
单元测试：python -m unittest discover -s tests -v，52 项全部通过。
结构检查：python dev_scripts/harness.py check --strict，通过。
真实快速检查：python dev_scripts/harness.py sync --check，15 个核心页面一致，约 1.62 秒；提交后复查约 1.71 秒。
真实深度检查：python dev_scripts/harness.py sync --deep-check，15 个页面正文全部一致，约 19.29 秒。
长期文档：Development-Workflow，revision fb52a69363b53f3bce6d5f2bdc016aead0c19f90；本地镜像提交为 cbdd27d。
工作区与远端：工作区干净，main、origin/main 和远端 main 均为 cbdd27d。
未验证内容：未在其他 Gitea 版本或高延迟网络环境实测；元数据缺 revision 的回退由单元测试覆盖。
任务归档：未创建、未导出（用户未明确要求）。

请按工单验收标准验收；工单保持开启，等待人工验收。

## 最终实施证据 - 状态：待验收 - 实现提交：`cbdd27d8618efdd744c4fa90f0f26e72fd9ebec3`，已推送到 `origin/main` - 最终差异： - 核心同步整轮只调用一次页面列表接口； - `sync` 与 `sync --check` 按远端 revision 增量判断，未变化页面不下载正文； - revision 变化/缺失或本地镜像元数据无效时回退读取完整页面； - 新增 `sync --deep-check` 全量正文审计； - `sync --verify` 完整读取一次后复用结果，不再重复下载； - 更新共享 Agent 命令说明及 Development-Workflow Wiki/本地镜像。 - 单元测试：`python -m unittest discover -s tests -v`，52 项全部通过。 - 结构检查：`python dev_scripts/harness.py check --strict`，通过。 - 真实快速检查：`python dev_scripts/harness.py sync --check`，15 个核心页面一致，约 1.62 秒；提交后复查约 1.71 秒。 - 真实深度检查：`python dev_scripts/harness.py sync --deep-check`，15 个页面正文全部一致，约 19.29 秒。 - 长期文档：Development-Workflow，revision `fb52a69363b53f3bce6d5f2bdc016aead0c19f90`；本地镜像提交为 `cbdd27d`。 - 工作区与远端：工作区干净，`main`、`origin/main` 和远端 main 均为 `cbdd27d`。 - 未验证内容：未在其他 Gitea 版本或高延迟网络环境实测；元数据缺 revision 的回退由单元测试覆盖。 - 任务归档：未创建、未导出（用户未明确要求）。请按工单验收标准验收；工单保持开启，等待人工验收。

ila commented

2026-09-02 09:39:03 +08:00

验收结论

验收结果：通过
验收时间：2026-09-02（Asia/Shanghai）
验收来源：用户明确回复“#29通过”
说明：验收结论未改变长期需求或 Wiki 事实，不重复更新、检查或导出 Wiki；未创建任务归档。

## 验收结论 - 验收结果：通过 - 验收时间：2026-09-02（Asia/Shanghai） - 验收来源：用户明确回复“#29通过” - 说明：验收结论未改变长期需求或 Wiki 事实，不重复更新、检查或导出 Wiki；未创建任务归档。

ila closed this issue

2026-09-02 09:39:03 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: OPC/dev_harness#29