generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Development-Workflow wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Development-Workflow.- wiki_revision: 62ddbe4469740c02ce4a6ca2fd1966a89a79322f synchronized_at: 2026-09-05T07:16:44Z # 开发工作流 ## 语言与术语 - 用户可以使用中文、英文或合理的中英混合语言交流；默认使用中文分析、回复、编写工单和维护内部项目文档。 - 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样；必要时补充简短中文解释。 - 用户明确要求某次回复或交付物使用其他语言时，按该次要求执行，不改写接口契约或影响搜索和执行的原文。 ## 事实来源 | 信息 | 唯一事实来源 | |---|---| | Epic/MVP 目标、版本范围和子工单索引 | Gitea Epic/MVP | | 单次任务需求、变化、方案、实现、测试、提交、阻塞和验收 | Gitea 单元工单 | | 长期需求、架构、契约、业务规则、安全边界和操作说明 | Gitea Wiki | | 源码、迁移、测试、版本绑定分析、本地原型和核心 Wiki 镜像 | Git | | 可编辑交互设计 | QuantUX；App ID、版本、链接和确认状态记录在工单 | 核心页面通过 `wiki-docs.json` 显式映射，固定执行 Wiki → `docs/` 单向同步。日常 `sync` 与 `sync --check` 先比较页面 revision，revision 未变化时不重复下载正文；疑似镜像损坏或需要完整核对时显式使用 `sync --deep-check`。既有 Wiki 任务归档和 `docs/task/` 只作历史兼容；标准任务不创建或导出，只有用户明确要求专项快照时才使用 `archive` / `export`。 ## 权威源与事实边界 发生冲突时按以下顺序裁决： 1. 可执行代码与自动化测试。 2. 状态为已批准的共享契约和决策。 3. 当前长期 Wiki。 4. 旧设计稿。 5. 注释、UI 文案和历史示例。 “当前实现”只能描述指定 commit 上可复核的行为；“目标契约”是尚待实施或验收的目标，不能用来宣称现有能力。能力状态使用“未发现实现 / 仅设计 / 部分实现 / 已实现某一端”等带限定的表达。 进行基线或差距审计时，记录 source commit、核验日期、证据路径、GAP-ID、审计范围、不在范围和证据边界。轻量日常工单不强制建立完整 SRS/SAD/ADR 文档集，但接口、状态机和跨端决策必须进入对应长期契约。 ## Gitea 交互与工单最小读取 - 所有工单和 Wiki 的查询、创建、更新、评论、状态变更及关闭优先使用项目已配置的 Gitea MCP；MCP 不可用或不支持所需操作时才回退 Gitea API，并在当前工单记录原因。凭据只从环境或 MCP 安全配置读取。 - 首次接手任务时读取工单确认基线和完成当前判断所需的评论，不因节省上下文跳过范围、依赖、安全、验收或重要变化。 - 同一任务、同一会话且关键前提未变化时复用仍有效的工单事实，优先关注当前状态、最新评论和首个未完成步骤。 - 会话、代码、配置、依赖、凭据、远端状态或关键前提变化，或最新评论改变范围、方案、风险和验收时，重新读取必要历史；无法判断影响范围时读取完整工单。 - 连接器不支持评论分页或增量读取时可以读取完整工单，但不得为规避完整读取而建立本地缓存或第二事实来源。 - 正确性、安全规则和已确认范围优先于读取成本；边界不确定时补读必要证据。 ## 新项目 Wiki 初始化门禁 本项目 Wiki 已于 2026-08-17 初始化并启用 Wiki-first，本节适用于从本仓库派生新项目的场景。 - 先创建 Gitea 远端仓库并启用工单和 Wiki，再配置 `wiki-docs.json`；不得把本地 `docs/` 当作线上 Wiki 已初始化的证据。 - 优先使用已配置的 Gitea MCP 查询和写入 Wiki；MCP 不可用或不支持所需操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只从安全配置读取。 - `Home` 不存在时先创建并在线回读 revision，再逐页创建或更新其他核心映射页面。 - 每个核心页面写入后必须在线回读并取得 revision。页面缺失、回读失败或没有 revision 时停止初始化。 - 产品编码前运行 `python dev_scripts/harness.py sync --verify`；全部成功才表示初始化完成。 ## 项目治理模式与不可裁剪底线 GoAuto 默认采用轻量治理。文案、注释、格式、局部样式或布局、预期行为明确的小 Bug，以及不改变接口、数据结构、权限和安全边界的单模块低风险调整可以直接实施，无需为了留痕补建工单。完整独立需求、新页面、跨模块功能，以及 API、数据结构、权限、安全、迁移或范围不明确的变化必须建单。 采购、创建订单、真实个人或生产数据、权限、安全、并发、数据库迁移、删除数据、发布和其他不可逆操作始终升级为高风险。无论任务采用何种最小门禁，凭据保护、永久禁止付款、个人与生产数据最小化、设备互斥、Agent 禁止 OCR/VLM、控件树与整屏截图禁存、工作区保护、真实测试和人工验收均不可裁剪。 ### 明确授权后的执行 - 当前聊天中用户给出的明确指令，或 Gitea 工单中能够归属于有权人工的明确授权，可以作为执行依据，不要求把同一授权重复复制到工单后再次确认。 - 授权必须能识别操作、对象和范围；Agent 自动生成的工单、草稿、摘要或对用户意图的转述不能单独构成人工授权。 - 获得有效授权后，只核对准确目标、授权范围和当前状态等最小必要前提，不得仅因操作不可逆而重复询问或拒绝。 - 授权不自动覆盖相邻对象或后续任务；环境、对象、范围或影响发生实质变化时重新确认。平台自身强制的审批、安全策略或权限限制继续有效。 ## 工单与设计证据双门禁 正式实施前先判断是否需要工单，再判断需要什么设计证据。工单不能替代原型确认，原型也不能替代技术方案、安全检查和单元工单。 ### 工单豁免 直接提交必须同时满足：范围明确、容易回退、不涉及接口/数据库/状态/权限/安全/并发/重大 UI 等必须建单项，并完成受影响范围的最小验证。可包括： - 错别字、注释、文档措辞、格式化和导入排序； - 单文件内部变量改名、类型标注、文档字符串或不改变产品行为的测试； - 已确认无人使用的死代码； - 单文件低风险且只恢复已有明确行为的缺陷； - 不改变业务含义、流程、权限、状态、接口、数据、布局和可访问性的纯显示文案。 有任何不确定就建立单元工单。 ### 最低设计证据 | 修改类型 | 最低证据 | 正式实施门禁 | |---|---|---| | 纯显示文案且满足豁免 | 无原型 | 最小界面检查 | | 现有界面小范围样式或布局 | 标注截图、低保真图或明确复用规范 | 工单确认后实施 | | 新组件 | 正常、空、加载、失败、禁用和权限边界 | 工单确认后实施 | | 新页面、独立功能、重大交互或导航 | QuantUX 或其他可审阅原型 | 用户确认文字需求、原型和覆盖范围后实施 | | 后端、接口、数据或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后实施 | | 恢复既有行为的 Bug | 原设计、截图、复现步骤或已有验收证据 | 确认是恢复而不是改需求 | ### 线上原型审核与按需导出 - 完整原型默认通过 QuantUX 或其他设计工具的可访问线上链接审核；工单记录链接、App ID、版本/revision 或确认日期、审核版本识别方式、确认人、确认时间和覆盖范围。 - 线上链接无法访问或不能区分审核版本时停止审核，等待用户确认等效方案。 - 只有用户明确要求 `导出原型 #N`、`导出全部原型`，或项目专用规则明确要求离线证据时，才导出到 `prototypes/<工单号>/<版本>/index.html`；导出不自动提交。 - 已确认的本地快照不得原位覆盖；结构、流程、状态、权限、异常处理或验收结果变化时建立新版本并重新确认。 - 导出后检查入口、主要交互、相对资源完整性，并删除凭据、账号、个人信息和生产数据。 - 设计工具无法完成用户明确要求的 HTML 导出时，记录限制并停止该导出；只要线上原型可访问且版本明确，线上审核不因此阻塞。纯文案、小范围 UI、非 UI 和恢复已有行为的 Bug 不强制完整原型或 HTML。 存量 `quantux-*.html` 平铺快照建立于规则前，保持原样；新目录规则自 #47 生效。 ## 任务层级与状态 ```text [Epic] 长期产品目标 └── [MVP] 一个可交付版本 ├── 单元任务 #N └── 单元任务 #N+1 ``` 单元任务是唯一正式实施单位。状态为： ```text 待确认 → 待实施 → 进行中 → 待验收 → 已完成 └→ 阻塞 ``` 真实依赖未满足且不能并行时保持待实施；开始后遇到无法解除的问题才标记阻塞。 ## 单元任务闭环 1. 只读确认当前代码事实、目标、非目标、依赖、设计证据、风险、回退、验证和长期文档影响。 2. 需要建单时创建单元工单并记录脱敏需求摘要；实施开始时检查分支和工作区并标记进行中。 3. 严格按工单范围实施；根因、范围、主要方案、风险或阻塞变化时先更新工单并按需重新确认。 4. 执行与风险相称的格式、单元、契约、集成、浏览器、真机或高风险验证；记录未验证内容。 5. 只有长期事实变化时更新 Wiki、在线回读 revision、运行一次 `sync` 和一次 `sync --check`；无长期影响时在工单说明原因并跳过。 6. 提交并推送当前工单文件，在工单集中回写最终差异、测试、未验证内容、提交哈希和 Wiki revision，保持待验收。 7. 用户明确验收后记录时间和结论、关闭单元工单并更新 Epic/MVP；没有新的长期事实变化时不重复同步 Wiki。 高风险数据库迁移、设备认证、并发租约、地址修改、创建订单、权限、删除、发布和不可逆动作必须单独建单并再次等待人工确认。任何自动支付需求直接拒绝。 ## 标准任务节奏 默认只更新工单三次： 1. **开始实施**：确认依赖、范围、工作区和设计证据。 2. **待验收**：集中记录最终差异、测试、未验证项、提交和长期文档影响。 3. **验收关闭**：记录用户验收结论，关闭任务并更新父工单。 只有根因、范围、主要方案、风险或阻塞发生重要变化时才增加过程记录。不重复抄写完整聊天、Agent 内部推理、已存在的测试证据或提交信息。 ## 需求记录与流转 - 聊天用于分析和确认，不是长期事实来源。 - 单元工单记录来源、提出时间和表达目的所需的少量关键原话或脱敏摘要，不保存凭据、个人数据或生产数据。 - 长期稳定需求进入产品需求或对应主题 Wiki；共享接口只进入 API 契约。 - 工单必须区分当前代码事实、目标契约和假设；不得把目标写成已有能力。 - 标准任务不创建 Wiki 任务归档。已有任务归档不删除、不补齐；用户明确要求专项历史快照时才按需创建或导出。 ## 自然语言快捷指令 | 指令 | 执行动作 | 停止位置 | |---|---|---| | `只分析` | 只读检查并给出方案 | 等待确认，不建单、不修改 | | `建工单` | 根据已确认方案创建单元任务 | 工单创建后停止 | | `执行工单 #N` | 检查依赖，实施、测试、提交、推送并回写证据；仅在明确要求时创建任务快照 | 工单待验收 | | `建工单并做` | 依次建单和执行 | 工单待验收 | | `继续工单 #N` | 优先核对当前状态、最新评论、Git 和必要 Wiki 证据，从首个未完成步骤继续 | 到当前停止条件 | | `检查工单 #N` | 只读检查范围、验收、测试和证据 | 输出报告，不自动修复 | | `同步文档` | 读取 Wiki，导出核心镜像并检查一致性 | 不修改 Wiki、不处理任务快照、不自动提交 | | `导出原型 #N` | 用户明确要求时导出指定工单已确认的原型版本 | 写入版本目录，不扩展范围、不自动提交 | | `导出全部原型` | 用户明确要求时导出当前项目明确范围内的全部已确认原型 | 不扩展范围、不自动提交 | | `导出任务归档` | 用户明确要求时按 revision 导出历史任务快照 | 只写 `docs/task/` | | `导出全部任务归档` | 用户明确要求时全量导出历史任务快照 | 只写 `docs/task/` | | `#N 验收通过` | 记录验收、关闭任务并同步父工单 | 无新长期事实时不再同步 Wiki | 快捷指令不能绕过方案确认、依赖、安全、设计证据、工单范围、必要验证或人工验收。 ## 效率与范围控制 - 默认严格按已确认范围实施，不顺手修复相邻问题。 - 完成必要安全和前置检查后，优先执行能产生真实反馈的最小命令。 - 采用“执行 → 查看首个可行动错误 → 最小修复 → 继续”的闭环。 - 同一任务、同一环境已经验证的事实不重复检查；环境或关键前提变化后再验证。 - Skill 和平台规则是否需要重新读取，按当前 Agent 平台和任务触发规则执行，不自行跳过。 - 不新增与验收无关的文档、脚本、框架、重构或扩展性设计。 - 完成工单范围、必要验证、按影响触发的文档闭环和证据回写后立即停止。 ## 文档影响 每个单元工单必须二选一：说明“无长期文档影响”的原因；或列出要更新的 Wiki 页面。 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新长期 Wiki。部署命令或常驻服务运维方式变化时，更新项目自己的 `Deployment-and-Operations` 页面；当前真实部署拓扑尚未确认时不得用模板占位值冒充事实。普通内部重构只有在入口、行为、配置和验证方式都不变时才可记为无影响。 Wiki 同步由长期事实变化触发，不由任务完成触发。有影响时只执行一轮：修改 Wiki → 在线回读 revision → `sync` → `sync --check` → 提交镜像；验收时内容未变化不重复执行。不得直接修改映射镜像后反向覆盖 Wiki。