diff --git a/Development-Workflow.-.md b/Development-Workflow.-.md index 3383c25..49efdcf 100644 --- a/Development-Workflow.-.md +++ b/Development-Workflow.-.md @@ -59,13 +59,13 @@ Agent 检查分支和工作区,只修改工单范围内的文件。发现新 - Git 提交哈希; - 相关 Wiki 页面及 revision。 -长期文档遵循唯一顺序: +长期核心文档遵循唯一顺序: ```text -修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像 +修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像 ``` -不得先编辑 `docs/` 再反向覆盖 Wiki。 +任务归档默认只更新 Wiki,不自动导出到 `docs/task/`。不得先编辑本地镜像再反向覆盖 Wiki。 ### 4. 待验收 @@ -73,21 +73,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 提供入口或适用版本说明。 @@ -141,14 +152,14 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时" | 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 | | 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 | | 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` | -| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | `docs/task/` | +| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | 人工按需导出的 `docs/task/` 快照(可能不完整) | 任务产生长期结论时,先更新对应 Wiki 主题页,再导出本地镜像。Gitea 工单全文不导出到仓库,避免形成第二份任务过程记录。 ## 稳定文档与任务归档 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。 -- 工单和任务归档解释某次为什么修改、实际改了什么以及如何验证。 +- 工单和 Wiki 任务归档解释某次为什么修改、实际改了什么以及如何验证;本地任务快照不是完整历史。 - 新人先读稳定主题页,只有追查历史原因时才读任务归档。 - 任务产生的长期结论必须合并到主题页,不能只留在归档。 @@ -196,16 +207,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 最终任务归档快照。 ## 什么时候重新确认方案 @@ -227,6 +241,6 @@ python dev_scripts/new_task_archive.py 123 "修复登录超时" | 讨论过程和临时方案 | 是 | 否 | 否 | | 实施进度和阻塞 | 是 | 否 | 否 | | 长期有效的最终方案 | 链接 | 是 | 镜像 | -| 测试结果与未验证内容 | 是 | 任务归档 | 镜像 | -| 提交哈希 | 是 | 任务归档 | 镜像 | +| 测试结果与未验证内容 | 是 | 任务归档 | 按需镜像 | +| 提交哈希 | 是 | 任务归档 | 按需镜像 | | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |