docs: 简化单人开发任务流程 (#48)

Development-Workflow.-.md

@@ -3,7 +3,7 @@
 ## 事实来源边界
 
 - Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
-- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。
+- Gitea Wiki 只保存长期有效的架构说明、开发规范和操作手册；单次任务结果留在 Gitea 工单。
 - Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
 - 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
 
@@ -25,16 +25,29 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地
 
 ### 先判断是否需要工单
 
-只有纯界面显示文案同时满足以下全部条件时，才可以免工单、免原型：
+以下改动必须建立单元任务工单：
+
+- 新功能、数据库迁移、API 或运行时配置契约变化；
+- 权限、安全、凭据、并发、数据删除、发布或其他高风险操作；
+- 跨模块行为变化、重构、重大 UI、交互或导航变化；
+- 无法确定影响范围、风险或是否改变既有行为的修改。
+
+以下修改同时满足“范围明确、容易回退、不涉及上述必须建单项”时可以直接提交：
+
+- 错别字、注释、文档措辞、格式化、导入排序、单文件内部变量改名；
+- 不改变产品行为的类型标注、文档字符串、测试或已确认死代码清理；
+- 单文件低风险缺陷，且只是恢复已有明确行为，不改变接口、数据库、状态、权限、安全、并发、流程、布局或可访问性；
+- 纯界面显示文案，并满足本页的全部文案豁免条件。
+
+直接提交仍要保留无关工作区改动、执行受影响的最小验证并写清提交说明。有任何不确定就建单。
+
+纯界面显示文案豁免还必须同时满足：
 
 - 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案；
 - 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果；
 - 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义；
 - 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符；
-- 不造成明显布局、截断、换行、可访问性或支持平台问题；
-- 有任何不确定时不使用豁免。
-
-豁免修改只执行与受影响界面相称的最小检查，确认文字正确且没有明显布局或可访问性问题，然后停止。只要任一条件不满足，或涉及用户行为、样式布局、交互和导航，就建立单元任务工单。
+- 不造成明显布局、截断、换行、可访问性或支持平台问题。
 
 ### 再判断设计证据
 
@@ -116,57 +129,40 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地
 
 Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。
 
-重要进度及时写回工单：
+工单以两次集中更新为默认节奏：
 
-- 已确认的根因；
-- 方案或范围变化；
-- 测试结果；
-- 阻塞和未验证内容；
-- Git 提交哈希；
-- 相关 Wiki 页面及 revision。
+1. 开始实施时将状态改为“进行中”，记录已确认方案、依赖和范围；只有根因、范围、方案、阻塞或风险发生重要变化时追加更新。
+2. 实现与测试完成后集中写入最终差异、测试结果、未验证内容、提交哈希和长期 Wiki 页面 revision，并改为“待验收”。
 
-长期核心文档遵循唯一顺序：
+长期核心文档仅在启动、部署、架构、接口、数据结构、业务规则、安全边界等长期事实变化时更新。需要更新时遵循：
 
 ```text
-修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像
+修改 Wiki → 在线回读 revision → sync 导出 docs → sync --check → 提交镜像
 ```
 
-任务归档默认只更新 Wiki，不自动导出到 `docs/task/`。不得先编辑本地镜像再反向覆盖 Wiki。
+无长期文档影响的任务不运行 Wiki 同步。不得先编辑本地镜像再反向覆盖 Wiki。
 
 ### 4. 待验收
 
 实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。
 
-### 5. 归档和关闭
+### 5. 验收和关闭
 
-使用以下命令只在 Wiki 创建任务归档页：
+用户明确验收通过后，在工单记录验收结论，关闭单元工单，并勾选所属 MVP 和 Epic 的任务索引。验收时不重复抄写已经记录的测试和提交证据，也不再次同步没有变化的 Wiki 页面。
 
-```powershell
-python dev_scripts/harness.py archive 123 "修复登录超时"
-```
-
-归档内容以 Wiki 页面为事实来源。默认不修改 `wiki-docs.json`，也不写入 `docs/task/`。把 Wiki 页面、revision 和实现提交哈希写回工单；用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
-
-只有用户明确提出时才导出任务归档：
-
-```powershell
-python dev_scripts/harness.py export        # 增量：新增或 revision 变化
-python dev_scripts/harness.py export --all  # 全量：读取全部线上任务归档
-```
-
-导出不得自动删除本地文件。`docs/task/` 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。
+历史兼容命令 `archive`、`export` 和 `export --all` 仅在用户明确要求保留专项快照时使用，不属于标准任务完成流程。既有 Wiki 任务归档和 `docs/task/` 快照继续保留，不自动删除、改名或补齐。
 
 ## 文档同步规则
 
 - 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。
-- 任务归档不逐页登记映射，由按需导出工具根据 `Task-<编号>-<标题>` 动态发现；已有镜像优先按镜像头匹配原页面。
+- 历史任务归档不逐页登记映射；用户明确要求导出时，由兼容工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。
 - 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。
 - 镜像头必须记录页面名、页面地址、revision 和同步时间。
 - 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
-- 核心同步的 `--check` 只检查核心镜像，不要求线上任务归档全部存在于本地。
+- 只有长期文档发生变化时才运行核心同步；一次 `sync` 后运行一次 `sync --check`，不因归档或验收重复执行。`--check` 不要求历史任务归档全部存在于本地。
 - 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。
 - 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
-- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
+- Wiki 更新成功而核心镜像导出失败时，在工单记录部分完成状态，不得把任务标为待验收。
 - 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。
 
 ## 面向初级维护者的修改边界
@@ -220,20 +216,20 @@ python dev_scripts/harness.py export --all  # 全量：读取全部线上任务
 | 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 |
 | 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 |
 | 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` |
-| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | 人工按需导出的 `docs/task/` 快照（可能不完整） |
+| 完成后的实现、验证、提交和遗留问题 | Gitea 单元任务工单 | 无 |
 
 任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。
 
-## 稳定文档与任务归档
+## 稳定文档与历史任务快照
 
 - Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
-- 工单和 Wiki 任务归档解释某次为什么修改、实际改了什么以及如何验证；本地任务快照不是完整历史。
-- 新人先读稳定主题页，只有追查历史原因时才读任务归档。
-- 任务产生的长期结论必须合并到主题页，不能只留在归档。
+- Gitea 工单解释某次为什么修改、实际改了什么以及如何验证，是单次任务证据的事实来源。
+- 既有 Wiki 任务归档与 `docs/task/` 仅是历史或人工专项快照，不要求为新任务创建；新人先读稳定主题页，追查历史时优先读工单。
+- 任务产生的长期结论必须合并到对应主题页，不能只留在工单。
 
 ## 效率与范围控制
 
-本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。
+本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、按需 Wiki 同步、Git 提交和人工验收要求。
 
 ### 严格控制范围
 
@@ -260,7 +256,7 @@ python dev_scripts/harness.py export --all  # 全量：读取全部线上任务
 ### 明确停止条件
 
 - 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
-- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
+- “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、按需 Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
 - 未影响当前验收的相邻问题只提示或建单，不顺手处理。
 
 ## 自然语言快捷指令
@@ -271,23 +267,23 @@ python dev_scripts/harness.py export --all  # 全量：读取全部线上任务
 |---|---|---|
 | `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 |
 | `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 |
-| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” |
+| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交；仅在长期文档变化时更新 Wiki 并同步镜像；集中回写完成证据 | 工单保持“待验收” |
 | `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” |
 | `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
 | `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 |
 | `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 |
-| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 |
-| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 |
-| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，同步必要的核心文档，推送、同步父工单并关闭任务；不自动导出任务归档 | 工单“已完成”并关闭 |
+| `导出任务归档` | 兼容指令；仅按用户明确要求增量导出历史 Wiki 任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 |
+| `导出全部任务归档` | 兼容指令；仅按用户明确要求全量导出历史 Wiki 任务归档 | 显示导出结果；不删除本地文件、不自动提交 |
+| `#N 验收通过` | 在工单记录验收结论，按需推送尚未推送的提交，勾选父工单并关闭任务；不创建归档，不重复同步无变化的 Wiki | 工单“已完成”并关闭 |
 
 补充边界：
 
 - 方案未确认时，`建工单`、`建工单并做` 和 `执行工单 #N` 不得绕过确认；Agent 应停在方案确认。
 - 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
 - `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
-- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
-- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。
-- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存人工按需导出的 Wiki 最终任务归档快照。
+- `同步文档` 或历史任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
+- `导出任务归档` 和 `导出全部任务归档` 是历史兼容能力，必须由用户明确提出，其他快捷指令不隐式创建或导出任务归档。
+- Gitea 工单保留讨论、完成证据和验收，不把工单全文导出到本地；`docs/task/` 只保存人工按需导出的历史 Wiki 任务快照。
 
 ## 什么时候重新确认方案
 
@@ -309,6 +305,6 @@ python dev_scripts/harness.py export --all  # 全量：读取全部线上任务
 | 讨论过程和临时方案 | 是 | 否 | 否 |
 | 实施进度和阻塞 | 是 | 否 | 否 |
 | 长期有效的最终方案 | 链接 | 是 | 镜像 |
-| 测试结果与未验证内容 | 是 | 任务归档 | 按需镜像 |
-| 提交哈希 | 是 | 任务归档 | 按需镜像 |
+| 测试结果与未验证内容 | 是 | 否 | 否 |
+| 提交哈希与验收结论 | 是 | 否 | 否 |
 | 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |