From 9010f9e9aa3b52cb954d6f8ca0329def5e25810c Mon Sep 17 00:00:00 2001 From: ila Date: Sun, 16 Aug 2026 19:22:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E6=88=90=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#14=20=E5=BD=92=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...3%E6%8C%89%E9%9C%80%E5%AF%BC%E5%87%BA.-.md | 58 +++++++++++++------ 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/Task-14-%E4%BB%BB%E5%8A%A1%E5%BD%92%E6%A1%A3%E6%8C%89%E9%9C%80%E5%AF%BC%E5%87%BA.-.md b/Task-14-%E4%BB%BB%E5%8A%A1%E5%BD%92%E6%A1%A3%E6%8C%89%E9%9C%80%E5%AF%BC%E5%87%BA.-.md index 1b1bac1..37f8c87 100644 --- a/Task-14-%E4%BB%BB%E5%8A%A1%E5%BD%92%E6%A1%A3%E6%8C%89%E9%9C%80%E5%AF%BC%E5%87%BA.-.md +++ b/Task-14-%E4%BB%BB%E5%8A%A1%E5%BD%92%E6%A1%A3%E6%8C%89%E9%9C%80%E5%AF%BC%E5%87%BA.-.md @@ -1,42 +1,66 @@ # 14 任务归档按需导出 -- 类型：需求 / 缺陷 / 重构 -- 所属 Epic：# -- 所属 MVP / 版本：# -- 状态：待验收 / 已完成 +- 类型：需求 +- 所属 Epic：无 +- 所属 MVP / 版本：无 +- 状态：待验收 - 日期：2026-08-16 - Gitea 工单：http://ilaer.eicp.net:8418/opc/dev_harness/issues/14 - Wiki 页面：Task-14-任务归档按需导出 -- Wiki revision：见本地镜像头 +- Wiki revision：以线上页面当前 revision 为准 ## 背景与目标 - +此前每个任务完成时都会把 Wiki 任务归档登记到 `wiki-docs.json` 并导出 `docs/task/`，导致任务越多，普通同步越慢、配置和仓库持续增长。本任务保留核心长期文档自动镜像，把任务归档改为用户明确提出后再增量或全量导出。 ## 最终方案 - +- `wiki-docs.json` 只登记 13 个核心长期页面，普通同步不处理任务归档。 +- `new_task_archive.py` 只创建线上 Wiki 归档，不修改映射、不写入 `docs/task/`。 +- 新增 `export_task_archives.py`： + - 默认按 Wiki revision 增量导出新增或变化的任务归档； + - `--all` 全量读取线上任务归档； + - 已有镜像通过元数据头匹配，兼容历史自定义文件名； + - 目标目录有未提交改动时停止； + - 不自动删除或重命名本地文件。 +- Harness 只要求核心页面具有显式映射，同时检查已经存在的任务快照格式；不要求线上任务历史全部导出。 +- AGENTS、README、项目档案、开发工作流、Home 和新项目初始化均明确任务快照可能不完整，导出必须由用户提出。 +- 当前已有 13 份 `docs/task/` 快照原样保留。 ## 修改文件 -- `<文件>`：<改动说明> +- `dev_scripts/export_task_archives.py`：新增增量与全量任务归档导出入口。 +- `dev_scripts/new_task_archive.py`：改为只创建线上 Wiki 归档。 +- `dev_scripts/wiki_docs.py`：支持复用页面列表元数据读取和安全写入单份镜像。 +- `dev_scripts/sync_wiki_docs.py`：明确只同步核心映射。 +- `dev_scripts/check_harness.py`：分离核心映射检查和已导出任务快照检查。 +- `wiki-docs.json`：移除任务逐页映射，只保留核心页面。 +- `AGENTS.md`、`README.md`：更新快捷指令和事实来源边界。 +- `tests/test_harness_docs.py`、`tests/test_wiki_docs.py`：覆盖核心映射、增量、全量、历史文件名、不删除和脏文件停止。 +- `docs/README.md`、`docs/00-project-profile.md`、`docs/01-workflow.md`、`docs/07-new-project-documentation-setup.md`：对应 Wiki 核心镜像。 ## 验收结果 | 验收标准 | 结果 | |---|---| -| | 通过 / 未通过 | +| 创建任务归档不再修改映射或写入本地 | 通过；创建本页后工作区保持干净 | +| 普通同步只同步核心长期文档 | 通过；只检查 13 个核心页面 | +| 增量导出按 revision 处理新增或变化 | 通过；真实执行时 13 份相同 revision 全部跳过 | +| 全量导出读取全部线上任务归档 | 通过；自动化测试覆盖 | +| 不自动删除或重命名本地文件 | 通过；自动化测试覆盖 | +| 保留已有任务快照且不要求完整导出 | 通过 | +| Wiki 与核心镜像一致 | 通过 | +| Harness 与单元测试通过 | 通过 | ## 测试 -- 执行命令：`<命令>` -- 结果： -- **未验证部分**： - -## 遗留问题 - - +- `python dev_scripts/check_harness.py --strict`：通过。 +- `python -m unittest discover -s tests -v`：31 项全部通过。 +- `python dev_scripts/sync_wiki_docs.py --check`：13 个核心镜像全部一致。 +- `python dev_scripts/export_task_archives.py`：13 份已有任务快照全部因 revision 相同而跳过，工作区无新增变化。 +- `python dev_scripts/new_task_archive.py 14 "任务归档按需导出"`：只创建本 Wiki 页面，未修改映射或 `docs/task/`，工作区保持干净。 +- **未验证部分**：未真实执行 `--all`，因为全量导出必须由用户明确提出；全量行为由自动化测试覆盖。 ## 相关提交 -- `<提交哈希>` <提交说明> +- `d1f55f9` feat: export task archives on demand (#14)