feat: export task archives on demand (#14)

docs/00-project-profile.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Project-Profile.-
-wiki_revision: c35c1737161ea428c487c066cb39eba4923535d2
-synchronized_at: 2026-08-10T11:02:51Z
+wiki_revision: 62d1251f807f7d1b60017790c35d46186ffb9617
+synchronized_at: 2026-08-16T11:18:50Z
 <!-- gitea-wiki-mirror:end -->
 
 # 项目档案
@@ -63,9 +63,11 @@ synchronized_at: 2026-08-10T11:02:51Z
 | 查看工作区 | `git status --short --branch` | 显示分支且没有无关修改 |
 | 检查模板结构 | `python dev_scripts/check_harness.py --strict` | 输出“DevHarness 检查通过” |
 | 运行单元测试 | `python -m unittest discover -s tests -v` | 所有测试通过 |
-| 导出 Wiki 镜像 | `python dev_scripts/sync_wiki_docs.py` | 映射页面写入 `docs/` |
-| 检查 Wiki 镜像 | `python dev_scripts/sync_wiki_docs.py --check` | 输出镜像与 Wiki 一致 |
-| 创建任务归档 | `python dev_scripts/new_task_archive.py 123 "修复登录超时"` | 先创建 Wiki 归档页，再登记并导出本地镜像 |
+| 导出核心 Wiki 镜像 | `python dev_scripts/sync_wiki_docs.py` | 核心页面写入 `docs/`，不处理任务归档 |
+| 检查核心 Wiki 镜像 | `python dev_scripts/sync_wiki_docs.py --check` | 输出核心镜像与 Wiki 一致 |
+| 创建任务归档 | `python dev_scripts/new_task_archive.py 123 "修复登录超时"` | 只创建 Wiki 归档页，不写入本地 |
+| 增量导出任务归档 | `python dev_scripts/export_task_archives.py` | 只导出新增或 revision 已变化的任务归档 |
+| 全量导出任务归档 | `python dev_scripts/export_task_archives.py --all` | 读取并导出全部线上任务归档 |
 
 ## 目录边界
 
@@ -73,13 +75,13 @@ synchronized_at: 2026-08-10T11:02:51Z
 |---|---|---|
 | `.gitea/issue_template/` | Gitea 工单模板 | 凭据、任务最终归档 |
 | `docs/` | Wiki 自动导出的只读镜像 | 人工直接维护的长期文档 |
-| `docs/task/` | Wiki 任务归档页的只读镜像 | 讨论过程和临时方案 |
+| `docs/task/` | 人工按需导出的 Wiki 任务归档只读快照，可能不是完整历史 | 讨论过程和临时方案 |
 | `dev_scripts/` | Harness 检查、Wiki 同步和归档工具 | 产品功能代码 |
 | `tests/` | Harness 工具自动化测试 | 生产数据 |
 
 ## 环境、配置与凭据
 
-- Wiki 同步配置：仓库根目录 `wiki-docs.json`。
+- 核心 Wiki 同步配置：仓库根目录 `wiki-docs.json`；任务归档不逐页登记，由按需导出工具动态发现。
 - Gitea 地址可由配置提供，也可通过 `GITEA_URL` 覆盖。
 - Gitea PAT 仅通过 `GITEA_TOKEN` 或 MCP 安全配置提供，不写入仓库。
 - Token 至少需要读取仓库权限；创建或更新 Wiki 时还需要写仓库权限。
@@ -90,7 +92,7 @@ synchronized_at: 2026-08-10T11:02:51Z
 
 ## 项目专用验收要求
 
-- 长期文档必须先更新 Wiki，再导出本地镜像。
+- 长期核心文档必须先更新 Wiki，再导出本地镜像；任务归档默认只保存在 Wiki，用户明确要求时才增量或全量导出。
 - 镜像必须包含来源页面、revision 和同步时间。
 - 页面删除、重命名和映射变更必须人工确认。
 - 新增核心文档时必须更新 Home、显式映射和 Harness 检查。

docs/01-workflow.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Development-Workflow
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.-
-wiki_revision: ea3912217443b40f0fee66a6dc8e951d06e2c2f9
-synchronized_at: 2026-08-10T03:51:34Z
+wiki_revision: 3f50238b637bc2f896ceab6caa5ab8ab1ded2a4b
+synchronized_at: 2026-08-16T11:18:52Z
 <!-- gitea-wiki-mirror:end -->
 
 # 开发工作流
@@ -67,13 +67,13 @@ Agent 检查分支和工作区，只修改工单范围内的文件。发现新
 - Git 提交哈希；
 - 相关 Wiki 页面及 revision。
 
-长期文档遵循唯一顺序：
+长期核心文档遵循唯一顺序：
 
 ```text
-修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
+修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像
 ```
 
-不得先编辑 `docs/` 再反向覆盖 Wiki。
+任务归档默认只更新 Wiki，不自动导出到 `docs/task/`。不得先编辑本地镜像再反向覆盖 Wiki。
 
 ### 4. 待验收
 
@@ -81,21 +81,32 @@ Agent 检查分支和工作区，只修改工单范围内的文件。发现新
 
 ### 5. 归档和关闭
 
-使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像：
+使用以下命令只在 Wiki 创建任务归档页：
 
 ```powershell
 python dev_scripts/new_task_archive.py 123 "修复登录超时"
 ```
 
-归档内容以 Wiki 页面为主源；本地 `docs/task/<编号>-<短标题>.md` 是镜像。归档镜像单独提交，再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
+归档内容以 Wiki 页面为事实来源。默认不修改 `wiki-docs.json`，也不写入 `docs/task/`。把 Wiki 页面、revision 和实现提交哈希写回工单；用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
+
+只有用户明确提出时才导出任务归档：
+
+```powershell
+python dev_scripts/export_task_archives.py        # 增量：新增或 revision 变化
+python dev_scripts/export_task_archives.py --all  # 全量：读取全部线上任务归档
+```
+
+导出不得自动删除本地文件。`docs/task/` 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。
 
 ## 文档同步规则
 
-- 映射保存在 `wiki-docs.json`，每个 Wiki 页面对应唯一仓库路径。
-- 同步脚本只实现 Wiki → `docs/`，不提供反向同步。
+- 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。
+- 任务归档不逐页登记映射，由按需导出工具根据 `Task-<编号>-<标题>` 动态发现；已有镜像优先按镜像头匹配原页面。
+- 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。
 - 镜像头必须记录页面名、页面地址、revision 和同步时间。
 - 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
-- `--check` 只检查，不写文件；页面缺失、revision 不一致或正文不一致均失败。
+- 核心同步的 `--check` 只检查核心镜像，不要求线上任务归档全部存在于本地。
+- 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。
 - 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
 - Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
 - 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。
@@ -149,14 +160,14 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 | 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 |
 | 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 |
 | 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` |
-| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | `docs/task/` |
+| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | 人工按需导出的 `docs/task/` 快照（可能不完整） |
 
 任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。
 
 ## 稳定文档与任务归档
 
 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
-- 工单和任务归档解释某次为什么修改、实际改了什么以及如何验证。
+- 工单和 Wiki 任务归档解释某次为什么修改、实际改了什么以及如何验证；本地任务快照不是完整历史。
 - 新人先读稳定主题页，只有追查历史原因时才读任务归档。
 - 任务产生的长期结论必须合并到主题页，不能只留在归档。
 
@@ -204,16 +215,19 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 | `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” |
 | `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
 | `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 |
-| `同步文档` | 读取 Wiki，导出已映射的 `docs/` 镜像并检查一致性 | 显示结果和差异；不修改 Wiki、不自动提交 |
-| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，导出并提交镜像，推送、同步父工单并关闭任务 | 工单“已完成”并关闭 |
+| `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 |
+| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 |
+| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 |
+| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，同步必要的核心文档，推送、同步父工单并关闭任务；不自动导出任务归档 | 工单“已完成”并关闭 |
 
 补充边界：
 
 - 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。
 - 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
 - `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
-- `同步文档` 发现镜像有未提交改动时停止，不覆盖现有修改。
-- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存 Wiki 最终任务归档的镜像。
+- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
+- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。
+- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存人工按需导出的 Wiki 最终任务归档快照。
 
 ## 什么时候重新确认方案
 
@@ -235,6 +249,6 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时"
 | 讨论过程和临时方案 | 是 | 否 | 否 |
 | 实施进度和阻塞 | 是 | 否 | 否 |
 | 长期有效的最终方案 | 链接 | 是 | 镜像 |
-| 测试结果与未验证内容 | 是 | 任务归档 | 镜像 |
-| 提交哈希 | 是 | 任务归档 | 镜像 |
+| 测试结果与未验证内容 | 是 | 任务归档 | 按需镜像 |
+| 提交哈希 | 是 | 任务归档 | 按需镜像 |
 | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |

docs/07-new-project-documentation-setup.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: New-Project-Documentation-Setup
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/New-Project-Documentation-Setup.-
-wiki_revision: a443c206780ecd40ae45732ca10686427f393349
-synchronized_at: 2026-08-10T11:03:03Z
+wiki_revision: cf49e125e7e73d8c818df61153d76abac6abfaaa
+synchronized_at: 2026-08-16T11:19:05Z
 <!-- gitea-wiki-mirror:end -->
 
 # 新项目文档初始化
@@ -46,9 +46,9 @@ synchronized_at: 2026-08-10T11:03:03Z
 
 ### 4. 修改镜像配置
 
-把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；核心主题映射保留。
+把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目；只保留核心主题映射，任务归档不逐页登记。
 
-确认当前目录确实是新项目副本、且 DevHarness 历史归档不需要保留后，移除属于 DevHarness 的任务归档映射和对应 `docs/task/` 镜像。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。
+确认当前目录确实是新项目副本、且 DevHarness 历史归档快照不需要保留后，可以移除对应 `docs/task/` 文件。不要在原 DevHarness 仓库或已有业务项目中执行这项清理。
 
 不要把 PAT 写入配置。
 
@@ -115,7 +115,7 @@ python dev_scripts/sync_wiki_docs.py --check
 python -m unittest discover -s tests -v
 ```
 
-只有线上 Wiki 确认后才导出 `docs/`。旧项目的任务归档不能带入新项目历史。
+只有线上 Wiki 确认后才导出核心 `docs/`。任务归档默认不导出；用户明确要求时再运行 `python dev_scripts/export_task_archives.py` 或加 `--all`。旧项目的任务归档快照不能带入新项目历史。
 
 ## 完成标准
 

docs/README.md

@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Home
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home
-wiki_revision: 55d89b7aec659f55a61e7ceef881ef34a62d9379
-synchronized_at: 2026-08-10T06:58:38Z
+wiki_revision: 52e9a6f8fe4fe03db8c65792ef500cc9a5084384
+synchronized_at: 2026-08-16T11:18:48Z
 <!-- gitea-wiki-mirror:end -->
 
 # DevHarness 文档中心
@@ -65,7 +65,8 @@ python dev_scripts/sync_wiki_docs.py --check
 | 任务状态、讨论、阻塞、验收过程 | Gitea 工单 |
 | 架构、业务规则、开发规范、操作手册、交付文档、任务归档 | Gitea Wiki |
 | 源码和与特定代码版本强绑定的文档 | Git 仓库 |
-| 离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 |
+| 核心长期文档的离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 |
+| 完整任务归档 | Gitea Wiki；`docs/task/` 仅是人工按需导出的快照 |
 
 本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。
 
@@ -84,9 +85,10 @@ python dev_scripts/sync_wiki_docs.py --check
 修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
 ```
 
-- 页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射。
+- 核心页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射；普通同步不处理任务归档。
+- 任务归档默认只保存在 Wiki，只有用户明确提出时才增量或全量导出到 `docs/task/`。
 - 镜像头记录来源页面、Wiki revision 和同步时间。
 - 已映射镜像存在未提交修改时同步必须停止。
 - 页面删除、重命名和映射变更必须人工确认。
-- Wiki 或导出失败时，相关任务不能标记为完成。
+- 核心 Wiki 或必要同步失败时，相关任务不能标记为完成；未请求任务归档导出不阻止任务完成。
 - 凭据、个人数据和生产数据不得进入 Wiki 或镜像。