dev_harness/docs/01-workflow.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Development-Workflow wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.- wiki_revision: 98acbf90ebad7a515f1a805defe6d963e5153e48 synchronized_at: 2026-08-19T01:51:50Z

开发工作流

事实来源边界

• Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
• Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。
• Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
• 本地 docs/ 仅供浏览和审查，不是长期文档编辑入口。

新项目 Wiki 初始化门禁

从 DevHarness 创建新项目时，本地 docs/ 即使完整存在，也只能证明模板镜像存在，不能证明新项目的线上 Wiki 已初始化。开始任何产品代码前必须完成以下闭环：

1. 先创建 Gitea 远端仓库并启用 Wiki，再把 wiki-docs.json 指向该仓库。
2. 优先使用项目已配置的 Gitea MCP 查询 Wiki 页面；MCP 不可用或不支持所需写操作时，才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
3. 查询线上页面列表；没有 Home 时先创建 Home，回读正文并记录 revision，然后再创建或更新其他核心映射页面。
4. 每个核心页面写入后都要在线回读；页面可读取且取得 revision 才算创建成功，不能用本地 docs/ 文件替代这项证据。
5. 运行 python dev_scripts/harness.py sync --verify。任一映射页面不存在、无法回读或镜像不一致时，停止产品编码并完成初始化。

Gitea 暂时不可用时可以准备工单和 Wiki 草稿，但不得把本地草稿宣称为线上事实，也不得绕过此门禁开始产品功能开发。

工单与设计证据双门禁

开始正式实现前依次判断“是否需要工单”和“需要什么设计证据”。原型确认不能代替方案、工单、安全检查或技术验证；工单存在也不能绕过原型确认。

先判断是否需要工单

只有纯界面显示文案同时满足以下全部条件时，才可以免工单、免原型：

• 只修改用户看到的组件显示名称、按钮文字、标题、提示语或其他文案；
• 不改变业务含义、操作流程、权限、状态、接口、数据和验收结果；
• 不涉及法律条款、安全提示、支付、金额、单位或其他高风险含义；
• 不修改国际化键、代码组件名、类名、变量、API 字段、数据库字段或其他程序标识符；
• 不造成明显布局、截断、换行、可访问性或支持平台问题；
• 有任何不确定时不使用豁免。

豁免修改只执行与受影响界面相称的最小检查，确认文字正确且没有明显布局或可访问性问题，然后停止。只要任一条件不满足，或涉及用户行为、样式布局、交互和导航，就建立单元任务工单。

再判断设计证据

修改类型	最低设计证据	正式编码门禁
纯显示文案且满足全部豁免条件	无原型	完成最小界面检查即可
现有界面的小范围样式或布局调整	标注截图或低保真线框图；没有设计不确定性时说明复用的现有规范	工单确认设计证据后编码
新组件但复用现有设计体系	组件状态、错误和边界说明；按需提供低保真图	工单确认状态和复用边界后编码
新页面、独立用户功能、重大交互或导航变化	Quant-UX 或其他合适工具制作的可审阅原型	用户确认原型和文字需求后才能编写生产代码
后端、接口、数据处理或定时任务	架构、API、数据、状态或流程设计	用户确认技术方案后编码，不制作无意义的 UI 原型
恢复既有确认行为的 Bug	原设计、已确认截图、复现步骤或现有验收证据	确认是恢复而不是改变行为后修复

采用最低成本、足以让用户确认的证据，不为了形式制作高保真原型。草稿原型可以用于需求讨论；草稿需要写入 Git/Wiki、多人协作或单独实施时，应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。

本地 HTML 审核快照

新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照：

• 可编辑设计源仍保存在 Quant-UX 或原设计工具；Git 中的 HTML 只是与需求和代码版本绑定的审核证据，Wiki 和工单只保存索引与确认记录。
• 快照放入 prototypes/<工单号>/<版本>/index.html；图片、样式、脚本和字体使用该版本目录内的相对路径。需要网络资源才能显示时，不得标记为可离线浏览。
• 用户通过 index.html 审核；浏览器限制直接打开时，在工单记录最小本地静态服务命令和访问地址，不新增项目专用服务脚本。
• 提交或请求审核前检查入口可打开、主要页面和交互可访问、图片和字体不缺失，并删除令牌、账号、个人信息和生产数据。
• 页面结构、主要流程、状态、权限、异常处理或验收结果发生变化时，在新版本目录重新导出并重新确认；不得覆盖已经确认的版本。
• 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML；仍使用双门禁表规定的最低证据。
• 设计工具无法生成可用 HTML 时必须在工单说明限制并停止审核，由用户确认等效的本地可浏览原型方案；不得只保留难以访问的线上链接后直接编码。

记录和重新确认

需要设计证据的工单必须记录：

• 原型或设计的链接、Git 路径或对应事实来源；
• 版本、revision 或确认日期；
• 状态：无、草稿、已确认或已废弃；
• 确认人和确认时间；
• 本次确认覆盖的页面、组件、流程和边界；
• 不需要 UI 原型时采用的技术设计，或无需任何原型的原因。

页面结构、主要流程、状态、权限、异常处理或验收结果变化时，先更新原型或文字需求并重新确认，再继续正式编码。只读技术检查可以在确认前进行；确需可行性代码验证时，必须由用户明确同意，隔离为不可进入生产的技术验证，不得悄悄扩展成正式实现。

一次任务怎样完成

1. 讨论

用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。

2. 建单

方案确认后，使用 .gitea/issue_template/task.md 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。

新产品或较大版本先建立 Epic，再建立 MVP：

[Epic] 产品或长期目标
└── [MVP] 第一个可交付版本
    ├── #101 单元任务
    ├── #102 单元任务
    └── #103 单元任务

每个单元任务都应目标单一，能够独立测试、提交和回退。

依赖与并行

建立新工单不要求其他工单已经完成，也不按工单编号限制实施顺序。每个单元任务必须声明：

• 前置工单，没有时填写“无”；
• 是否允许与未完成的前置工单并行；
• 判断可以或不可以并行的原因。

开始修改前，Agent 检查工单声明的前置工单：

• 没有前置工单，或前置工单已经完成，可以进入“进行中”；
• 前置工单未完成且存在实际依赖时，不得开始实施，工单保持“待实施”；
• 与前置工单没有实施冲突、允许并行时，可以进入“进行中”，但必须在工单写明原因；
• 已经进入实施后出现计划外、当前无法解除的问题，才使用“阻塞”。

依赖不改变单元任务边界。依赖满足后，该任务仍须拥有独立的范围、提交、测试和回退方式。

3. 实施

Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。

重要进度及时写回工单：

• 已确认的根因；
• 方案或范围变化；
• 测试结果；
• 阻塞和未验证内容；
• Git 提交哈希；
• 相关 Wiki 页面及 revision。

长期核心文档遵循唯一顺序：

修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像

任务归档默认只更新 Wiki，不自动导出到 docs/task/。不得先编辑本地镜像再反向覆盖 Wiki。

4. 待验收

实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。

5. 归档和关闭

使用以下命令只在 Wiki 创建任务归档页：

python dev_scripts/harness.py archive 123 "修复登录超时"

归档内容以 Wiki 页面为事实来源。默认不修改 wiki-docs.json，也不写入 docs/task/。把 Wiki 页面、revision 和实现提交哈希写回工单；用户明确验收通过后，关闭单元工单并勾选父工单中的任务。

只有用户明确提出时才导出任务归档：

python dev_scripts/harness.py export        # 增量：新增或 revision 变化
python dev_scripts/harness.py export --all  # 全量：读取全部线上任务归档

导出不得自动删除本地文件。docs/task/ 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。

文档同步规则

• 核心页面映射保存在 wiki-docs.json；普通同步只处理这些核心长期文档。
• 任务归档不逐页登记映射，由按需导出工具根据 Task-<编号>-<标题> 动态发现；已有镜像优先按镜像头匹配原页面。
• 所有同步和导出只实现 Wiki → docs/，不提供反向同步。
• 镜像头必须记录页面名、页面地址、revision 和同步时间。
• 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
• 核心同步的 --check 只检查核心镜像，不要求线上任务归档全部存在于本地。
• 已经导出的任务镜像仍必须具有来源页面、revision 和同步时间，并通过 Harness 格式检查。
• 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
• Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
• 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。

面向初级维护者的修改边界

风险	示例	处理方式
低	文案、简单校验、查询条件、独立 UI、小范围回归 Bug	初级程序员可在 Agent 协助下理解、修改和验证
中	API、配置、依赖、跨模块逻辑、数据结构	由 Agent 实现，程序员检查差异并执行验证
高	权限、安全、并发、迁移、支付、删除数据、不可逆操作	停止修改，由 Agent 分析并等待人工确认

风险由影响范围决定，不按代码行数判断。

每个任务的文档影响

单元任务必须明确选择：

• 不影响长期文档，并说明原因；
• 更新项目档案或运行验证；
• 更新架构与代码地图；
• 更新业务规则与术语；
• 更新常见修改或故障排查；
• 新增或调整其他 Wiki 页面。

以下变化必须更新相关 Wiki：

• 启动、测试、部署或排错命令变化；
• 模块入口、目录职责或主要调用路径变化；
• 配置项、API、数据结构或状态变化；
• 业务规则、安全边界或权限变化；
• 日志位置、错误定位或常见处理方式变化。

部署命令的落点：有常驻服务的项目更新自己的 Deployment-and-Operations 页面（由部署文档模板复制建立）；没有常驻服务的项目在工单记录“无部署文档影响”及原因，不要创建空的部署页。

普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。

需求记录与流转

聊天用于分析和确认，不是正式需求的长期事实来源。创建单元任务工单时，Agent 应记录：

• 原始需求的来源和提出时间；
• 能表达用户目的、使用场景和限制的少量关键原话；
• 整理后的目标、非目标、确认方案、验收标准和文档影响；
• 实施期间影响范围、接口、数据、风险或验收的需求变化，以及变化原因和用户确认。

只摘录完成追踪所需的内容，不复制完整聊天，不保存 Agent 内部推理，不写入密码、令牌、个人数据或生产数据。包含敏感信息的原话必须删除敏感部分或改写为脱敏摘要。

需求按以下边界流转：

内容	事实来源	本地镜像
关键原始需求、确认后的单次任务需求	Gitea 单元任务工单	无
讨论、决定和需求变化	Gitea 工单正文或评论	无
长期有效的产品需求、业务规则和系统边界	对应 Gitea Wiki 主题页	docs/
完成后的实现、验证和遗留问题	Wiki 任务归档	人工按需导出的 docs/task/ 快照（可能不完整）

任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。

稳定文档与任务归档

• Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
• 工单和 Wiki 任务归档解释某次为什么修改、实际改了什么以及如何验证；本地任务快照不是完整历史。
• 新人先读稳定主题页，只有追查历史原因时才读任务归档。
• 任务产生的长期结论必须合并到主题页，不能只留在归档。

效率与范围控制

本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。

严格控制范围

• 默认严格按用户确认的目标和单元任务范围执行，不主动扩展相邻问题。
• 除非任务目标、仓库强制规则或已发现的真实阻塞需要，不新增额外文档、辅助脚本、备份文件、框架、重构或扩展性设计。
• 不执行与本次验收无关的验证；安全检查、受影响范围测试、回归测试和仓库规定的闭环验证不属于“额外验证”。
• 新发现的相邻问题最多用一句话提示或记录到独立工单，不自动修复或混入当前提交。

渐进执行和修复

• 完成已知必要的安全与前置检查后，优先执行能够产生真实反馈的最小命令。
• 一次执行后先处理首个可定位、可行动的真实错误，不同时猜测并修改多个可能原因。
• 采用“执行 → 查看错误 → 最小修复 → 从失败点继续或按需重跑”的闭环。
• 不在真实证据出现前堆叠与已知风险无关的预防性检查。
• 涉及凭据、权限、安全、数据、迁移、并发、删除、发布或不可逆操作时，必须先完成相应前置检查，不得通过试错获取风险反馈。

复用已验证事实

• 在同一任务和同一环境状态下，已经通过的路由、连接、恢复和环境检查不重复执行。
• 只有会话、环境、代码、配置、依赖、凭据、远端状态或关键前提发生变化时才重新检查。
• 代码修改后，受影响测试和最终验收必须重新执行；提交前工作区检查、推送前远端分支检查不得因为之前通过而省略。
• Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。

明确停止条件

• 完成用户确认的验收标准和仓库规定的必要闭环后立即停止，不主动继续优化。
• “最小验收条件”包括当前工单要求的实现、必要测试、文档影响处理、Wiki 镜像检查、提交和证据回写，不等同于功能第一次运行成功。
• 未影响当前验收的相邻问题只提示或建单，不顺手处理。

自然语言快捷指令

快捷指令是对本工作流的自然语言别名，供 Claude Code、Codex 和维护者使用。它们只减少重复描述，不得绕过方案确认、前置依赖、安全规则、工单范围、Wiki 主源、必要验证或人工验收。

指令	执行动作	停止位置
只分析	只读检查需求、代码、日志和文档，区分事实与假设并给出方案	输出方案并等待确认；不建单、不修改
建工单	根据已经确认的方案创建单元任务工单	工单创建并记录完成；不修改代码
执行工单 #N	读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据	工单保持“待验收”
建工单并做	依次执行“建工单”和“执行工单”；建工单，做、建工单,做 含义相同	工单保持“待验收”
继续工单 #N	核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查	到达该工单当前流程的停止条件
检查工单 #N	只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分	输出检查报告；不自动修复
同步文档	读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档	显示结果和差异；不修改 Wiki、不自动提交
导出任务归档	人工触发增量导出，只写入新增或 revision 已变化的任务归档	显示导出或跳过结果；不删除本地文件、不自动提交
导出全部任务归档	人工触发全量读取并导出线上全部任务归档	显示导出结果；不删除本地文件、不自动提交
#N 验收通过	记录明确验收，更新 Wiki 归档为“已完成”，同步必要的核心文档，推送、同步父工单并关闭任务；不自动导出任务归档	工单“已完成”并关闭

补充边界：

• 方案未确认时，建工单、建工单并做 和 执行工单 #N 不得绕过确认；Agent 应停在方案确认。
• 前置依赖未满足且不允许并行时，实施类指令停在“待实施”。
• #N 验收通过 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
• 同步文档 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
• 导出任务归档 和 导出全部任务归档 必须由用户明确提出，其他快捷指令不隐式执行。
• Gitea 工单保留讨论和过程，不把工单全文导出到本地；docs/task/ 只保存人工按需导出的 Wiki 最终任务归档快照。

什么时候重新确认方案

以下变化必须先更新工单，再由用户确认：

• 交付结果或用户操作发生变化；
• 增加或删除接口、数据库字段或迁移；
• 安全边界、权限或不可逆操作发生变化；
• 原方案不可行，需要更换主要技术路线；
• 任务范围明显扩大；
• Wiki 页面删除、重命名或事实源边界改变。

普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。

工单、Wiki 与 Git 分别写什么

信息	Gitea 工单	Gitea Wiki	Git / docs 镜像
讨论过程和临时方案	是	否	否
实施进度和阻塞	是	否	否
长期有效的最终方案	链接	是	镜像
测试结果与未验证内容	是	任务归档	按需镜像
提交哈希	是	任务归档	按需镜像
与具体代码版本绑定的说明	可链接	提供入口	是