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

任务归档改为人工按需增量或全量导出 #14

New Issue
Closed
opened 2026-08-16 23:06:51 +08:00 by ila · 0 comments
ila commented 2026-08-16 23:06:51 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：单元任务
  • 状态：已完成
  • 所属 Epic：无
  • 所属 MVP / 版本：无

依赖与并行

  • 前置工单：#13
  • 是否允许与前置工单并行：否
  • 原因：本任务调整 #13 后的任务归档与镜像边界；#13 已完成并关闭。

子项目影响

  • 仅影响的子项目 / 交付单元：DevHarness 模板、Wiki 同步与任务归档工具。
  • 是否跨子项目：否。
  • 是否修改共享接口或契约：是；调整自然语言快捷指令和归档命令语义，事实来源为 AGENTS.md 与 Development-Workflow。
  • 各子项目需要执行的验证：严格检查、单元测试、核心 Wiki 镜像检查、按需任务归档导出测试。

原始需求

  • 来源：用户与 Agent 对话
  • 提出时间：2026-08-16
  • 关键原话或脱敏摘要：“不再每次自动导出 task 到本地，人工提出导出后再把全部或增量导出到本地”“按照你的方案来建工单，做”
  • 已确认方案：核心长期文档继续自动同步；任务归档默认只保存在 Wiki，用户明确要求时才增量或全量导出。

要解决什么

当前每个任务完成都把 Wiki 任务归档登记到 wiki-docs.json 并提交 docs/task/ 镜像，导致任务越多，全量同步越慢、配置和仓库持续增长。目标是在保留核心文档本地镜像的同时，把任务归档改为人工触发的按需导出。

做什么 / 不做什么

做

  • 默认核心文档同步排除任务归档。
  • 创建任务归档时只创建线上 Wiki 页面，不自动登记或导出本地镜像。
  • 增加任务归档增量导出和全量导出命令。
  • 增量导出依据本地镜像头中的 Wiki revision 判断新增或变化。
  • 已导出的任务镜像继续保持只读头和安全边界。
  • 页面删除或重命名不自动删除本地文件。
  • 更新 Wiki 工作流、项目档案和相关入口，导出核心镜像。
  • 更新 Harness 检查和单元测试。
  • 完成提交、推送、Wiki 任务归档和待验收闭环。

不做

  • 不删除当前已有的 docs/task/ 镜像。
  • 不自动迁移或删除现有任务映射造成的数据。
  • 不建立通用备份系统。
  • 不改变 Gitea 工单和 Wiki 的事实来源。
  • 不让普通“同步文档”隐式导出任务归档。

已确认方案

  1. wiki-docs.json 的核心页面映射继续用于普通同步；现有任务映射从默认核心同步范围移出，但保留已有本地文件。
  2. new_task_archive.py 只创建 Wiki 归档，不再自动修改映射和导出。
  3. 新增按需导出入口：
    • 增量：导出本地不存在或 revision 改变的全部任务归档；
    • 全量：读取并导出全部线上任务归档，未变化页面允许跳过；
    • 两者都不自动删除本地文件。
  4. 任务文件名由 Task-<编号>-<标题> 稳定转换到 docs/task/<编号>-<标题>.md。
  5. 默认严格检查只要求核心页面一致，并检查已存在任务镜像格式；不要求任务历史全部在本地。
  6. 更新快捷指令，明确“导出任务归档”和“导出全部任务归档”必须由用户提出。

文档影响

  • 不影响长期文档，原因：
  • 更新项目档案：同步命令和目录边界
  • 更新架构与代码地图
  • 更新业务规则与术语
  • 更新常见修改或故障排查
  • 更新其他 Wiki：Development-Workflow、Home（如入口语义需要）

交付文档影响

  • 无交付文档影响，原因：只调整内部开发文档归档与镜像策略。
  • 更新已有交付文档：
  • 新增交付文档：
  • 需要目标岗位或客户代表验证：否；由维护者验证命令语义。

验收标准

  • 创建任务归档不再自动修改 wiki-docs.json 或写入 docs/task/。
  • 普通“同步文档”只同步核心长期文档。
  • 增量导出只写入新增或 revision 已变化的任务归档。
  • 全量导出能够读取全部线上任务归档。
  • 页面删除或重命名不会自动删除本地文件。
  • 已有任务镜像保留且严格检查不要求线上任务全部导出。
  • Wiki 工作流和项目档案已先更新并导出核心镜像。
  • 严格检查和单元测试通过。
  • 实现提交已推送，任务归档已更新 Wiki 且按新规则不创建本地归档提交。
  • 用户已于 2026-08-16 明确验收通过。

验证方式

  • python dev_scripts/check_harness.py --strict
  • python -m unittest discover -s tests -v
  • python dev_scripts/sync_wiki_docs.py --check
  • 新建临时 Wiki 客户端模拟：验证创建归档不写本地、增量选择、全量导出、删除不传播。
  • git diff --check
  • git status --short --branch

风险和回退

  • 风险：维护者误以为 docs/task/ 是完整历史；通过规则明确它只是人工按需快照。
  • 风险：动态标题生成不安全路径；复用并加强现有标题清理和路径约束。
  • 风险：旧任务映射继续拖慢普通同步；实现时把核心与任务范围明确分离。
  • 回退：恢复任务归档自动登记和导出流程；不删除 Wiki 页面或现有本地镜像。

实施结果与证据

  • 实现提交：d1f55f9，已推送至 origin/main。
  • 任务归档 Wiki：Task-14-任务归档按需导出。
  • 任务归档 revision：9010f9e9aa3b52cb954d6f8ca0329def5e25810c。
  • Home revision：52e9a6f8fe4fe03db8c65792ef500cc9a5084384。
  • Project-Profile revision：62d1251f807f7d1b60017790c35d46186ffb9617。
  • Development-Workflow revision：3f50238b637bc2f896ceab6caa5ab8ab1ded2a4b。
  • New-Project-Documentation-Setup revision：cf49e125e7e73d8c818df61153d76abac6abfaaa。
  • 严格检查：通过。
  • 单元测试：31 项全部通过。
  • 核心镜像检查：13 个页面全部一致。
  • 真实增量导出：13 份已有快照全部按 revision 跳过，无工作区变化。
  • 真实创建 #14 归档：仅创建 Wiki，未写入 wiki-docs.json 或 docs/task/。
  • 未验证：未真实执行全量导出，因为该动作按新规则必须由用户明确提出；自动化测试已覆盖。

验收完成

  • 用户验收日期：2026-08-16
  • 最终任务归档 revision：958a2d49bba9905ec160d8667b6d208f736c4b00
  • 按 #14 确立的规则，任务归档仅保留在线 Wiki，本次未自动导出到 docs/task/。
## 基本信息 - 类型：单元任务 - 状态：已完成 - 所属 Epic：无 - 所属 MVP / 版本：无 ## 依赖与并行 - 前置工单：#13 - 是否允许与前置工单并行：否 - 原因：本任务调整 #13 后的任务归档与镜像边界；#13 已完成并关闭。 ## 子项目影响 - 仅影响的子项目 / 交付单元：DevHarness 模板、Wiki 同步与任务归档工具。 - 是否跨子项目：否。 - 是否修改共享接口或契约：是；调整自然语言快捷指令和归档命令语义，事实来源为 AGENTS.md 与 Development-Workflow。 - 各子项目需要执行的验证：严格检查、单元测试、核心 Wiki 镜像检查、按需任务归档导出测试。 ## 原始需求 - 来源：用户与 Agent 对话 - 提出时间：2026-08-16 - 关键原话或脱敏摘要：“不再每次自动导出 task 到本地，人工提出导出后再把全部或增量导出到本地”“按照你的方案来建工单，做” - 已确认方案：核心长期文档继续自动同步；任务归档默认只保存在 Wiki，用户明确要求时才增量或全量导出。 ## 要解决什么 当前每个任务完成都把 Wiki 任务归档登记到 `wiki-docs.json` 并提交 `docs/task/` 镜像，导致任务越多，全量同步越慢、配置和仓库持续增长。目标是在保留核心文档本地镜像的同时，把任务归档改为人工触发的按需导出。 ## 做什么 / 不做什么 ### 做 - 默认核心文档同步排除任务归档。 - 创建任务归档时只创建线上 Wiki 页面，不自动登记或导出本地镜像。 - 增加任务归档增量导出和全量导出命令。 - 增量导出依据本地镜像头中的 Wiki revision 判断新增或变化。 - 已导出的任务镜像继续保持只读头和安全边界。 - 页面删除或重命名不自动删除本地文件。 - 更新 Wiki 工作流、项目档案和相关入口，导出核心镜像。 - 更新 Harness 检查和单元测试。 - 完成提交、推送、Wiki 任务归档和待验收闭环。 ### 不做 - 不删除当前已有的 `docs/task/` 镜像。 - 不自动迁移或删除现有任务映射造成的数据。 - 不建立通用备份系统。 - 不改变 Gitea 工单和 Wiki 的事实来源。 - 不让普通“同步文档”隐式导出任务归档。 ## 已确认方案 1. `wiki-docs.json` 的核心页面映射继续用于普通同步；现有任务映射从默认核心同步范围移出，但保留已有本地文件。 2. `new_task_archive.py` 只创建 Wiki 归档，不再自动修改映射和导出。 3. 新增按需导出入口： - 增量：导出本地不存在或 revision 改变的全部任务归档； - 全量：读取并导出全部线上任务归档，未变化页面允许跳过； - 两者都不自动删除本地文件。 4. 任务文件名由 `Task-<编号>-<标题>` 稳定转换到 `docs/task/<编号>-<标题>.md`。 5. 默认严格检查只要求核心页面一致，并检查已存在任务镜像格式；不要求任务历史全部在本地。 6. 更新快捷指令，明确“导出任务归档”和“导出全部任务归档”必须由用户提出。 ## 文档影响 - [ ] 不影响长期文档，原因： - [x] 更新项目档案：同步命令和目录边界 - [ ] 更新架构与代码地图 - [ ] 更新业务规则与术语 - [ ] 更新常见修改或故障排查 - [x] 更新其他 Wiki：Development-Workflow、Home（如入口语义需要） ## 交付文档影响 - [x] 无交付文档影响，原因：只调整内部开发文档归档与镜像策略。 - [ ] 更新已有交付文档： - [ ] 新增交付文档： - [x] 需要目标岗位或客户代表验证：否；由维护者验证命令语义。 ## 验收标准 - [x] 创建任务归档不再自动修改 `wiki-docs.json` 或写入 `docs/task/`。 - [x] 普通“同步文档”只同步核心长期文档。 - [x] 增量导出只写入新增或 revision 已变化的任务归档。 - [x] 全量导出能够读取全部线上任务归档。 - [x] 页面删除或重命名不会自动删除本地文件。 - [x] 已有任务镜像保留且严格检查不要求线上任务全部导出。 - [x] Wiki 工作流和项目档案已先更新并导出核心镜像。 - [x] 严格检查和单元测试通过。 - [x] 实现提交已推送，任务归档已更新 Wiki 且按新规则不创建本地归档提交。 - [x] 用户已于 2026-08-16 明确验收通过。 ## 验证方式 - `python dev_scripts/check_harness.py --strict` - `python -m unittest discover -s tests -v` - `python dev_scripts/sync_wiki_docs.py --check` - 新建临时 Wiki 客户端模拟：验证创建归档不写本地、增量选择、全量导出、删除不传播。 - `git diff --check` - `git status --short --branch` ## 风险和回退 - 风险：维护者误以为 `docs/task/` 是完整历史；通过规则明确它只是人工按需快照。 - 风险：动态标题生成不安全路径；复用并加强现有标题清理和路径约束。 - 风险：旧任务映射继续拖慢普通同步；实现时把核心与任务范围明确分离。 - 回退：恢复任务归档自动登记和导出流程；不删除 Wiki 页面或现有本地镜像。 ## 实施结果与证据 - 实现提交：`d1f55f9`，已推送至 `origin/main`。 - 任务归档 Wiki：`Task-14-任务归档按需导出`。 - 任务归档 revision：`9010f9e9aa3b52cb954d6f8ca0329def5e25810c`。 - Home revision：`52e9a6f8fe4fe03db8c65792ef500cc9a5084384`。 - Project-Profile revision：`62d1251f807f7d1b60017790c35d46186ffb9617`。 - Development-Workflow revision：`3f50238b637bc2f896ceab6caa5ab8ab1ded2a4b`。 - New-Project-Documentation-Setup revision：`cf49e125e7e73d8c818df61153d76abac6abfaaa`。 - 严格检查：通过。 - 单元测试：31 项全部通过。 - 核心镜像检查：13 个页面全部一致。 - 真实增量导出：13 份已有快照全部按 revision 跳过，无工作区变化。 - 真实创建 #14 归档：仅创建 Wiki，未写入 `wiki-docs.json` 或 `docs/task/`。 - 未验证：未真实执行全量导出，因为该动作按新规则必须由用户明确提出；自动化测试已覆盖。 ## 验收完成 - 用户验收日期：2026-08-16 - 最终任务归档 revision：`958a2d49bba9905ec160d8667b6d208f736c4b00` - 按 #14 确立的规则，任务归档仅保留在线 Wiki，本次未自动导出到 `docs/task/`。
ila closed this issue 2026-08-16 23:06:52 +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#14