开发工作流
语言与术语
- 用户可以使用中文、英文或合理的中英混合语言交流；默认使用中文分析、回复、编写工单和维护内部项目文档。
- 代码标识符、命令、参数、路径、文件名、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。
权威源与事实边界
发生冲突时按以下顺序裁决：
- 可执行代码与自动化测试。
- 状态为已批准的共享契约和决策。
- 当前长期 Wiki。
- 旧设计稿。
- 注释、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 生效。
任务层级与状态
[Epic] 长期产品目标
└── [MVP] 一个可交付版本
├── 单元任务 #N
└── 单元任务 #N+1
单元任务是唯一正式实施单位。状态为：
待确认 → 待实施 → 进行中 → 待验收 → 已完成
└→ 阻塞
真实依赖未满足且不能并行时保持待实施；开始后遇到无法解除的问题才标记阻塞。
单元任务闭环
- 只读确认当前代码事实、目标、非目标、依赖、设计证据、风险、回退、验证和长期文档影响。
- 需要建单时创建单元工单并记录脱敏需求摘要；实施开始时检查分支和工作区并标记进行中。
- 严格按工单范围实施；根因、范围、主要方案、风险或阻塞变化时先更新工单并按需重新确认。
- 执行与风险相称的格式、单元、契约、集成、浏览器、真机或高风险验证；记录未验证内容。
- 只有长期事实变化时更新 Wiki、在线回读 revision、运行一次
sync和一次sync --check；无长期影响时在工单说明原因并跳过。 - 提交并推送当前工单文件，在工单集中回写最终差异、测试、未验证内容、提交哈希和 Wiki revision，保持待验收。
- 用户明确验收后记录时间和结论、关闭单元工单并更新 Epic/MVP；没有新的长期事实变化时不重复同步 Wiki。
高风险数据库迁移、设备认证、并发租约、地址修改、创建订单、权限、删除、发布和不可逆动作必须单独建单并再次等待人工确认。任何自动支付需求直接拒绝。
标准任务节奏
默认只更新工单三次：
- 开始实施：确认依赖、范围、工作区和设计证据。
- 待验收：集中记录最终差异、测试、未验证项、提交和长期文档影响。
- 验收关闭：记录用户验收结论，关闭任务并更新父工单。
只有根因、范围、主要方案、风险或阻塞发生重要变化时才增加过程记录。不重复抄写完整聊天、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。