ycode/docs/协作/开发与验收协作流程.md

开发与验收协作流程

更新：2026-10-21（Asia/Shanghai）。本流程以 Gitea 为唯一交接源；以下角色按职责定义，不使用随电脑变化的“本机／另一台”指代。

1. 两台电脑，一条主线

• 开发端（用户另一台电脑上的开发对话）：负责业务源码、测试脚本、依赖与构建配置；实现需求、自测、构建并提交交付记录。开发端可以按根目录约定委派子 agent，由开发主对话集成和自测。
• 验收与规划端（当前对话）：独立拉取指定提交、安装依赖和构建，验收、记录问题并规划下一批；默认只修改需求、验收与交接文档，不修改业务源码、测试脚本、依赖或构建配置。子 agent 在这里用于调查、测试及评审；发现问题回传开发端。用户明确授权本地修复时才改变此边界，并记录责任转移。
• 唯一交接仓库：远程名 gitea，地址 https://gitea.iiiii.run/admin/ycode.git，交接主线 gitea/master。origin 目前指向 GitHub，不用于本流程的拉取、推送或交付 SHA 判断，也不自动双向同步；保持其现有配置。
• 使用当前仓库的 master 协作，不另设长期开发／验收分支。Git/Gitea 保存需求、代码、证据索引和结论，不会自动执行开发或验收；每次交接须明确通知对方批次、记录位置和 SHA。
• master 是交接主线，可能包含“待验收”代码；分支名或推送成功都不代表已验收。可用版本以对应验收记录中的完整 SHA 与逐项结论为准。
• 开始前阅读根目录 AGENTS.md、docs/接手状态-2026-10-15.md 及本批相关记录。原版 WorkBuddy 取证只通过 REA，不能因验收困难绕过。

2. 批次与状态

1. 规划方给任务稳定编号，如 YC-001，归入批次 B01，写清范围、优先级、依赖、逐项验收标准和不做的内容。
2. 双方确认后，锁定本批范围和验收标准。开发方接单并更新状态；新增想法进入下一批，不暗中改变正在验收的标准。
3. 开发方实现、自测、提交代码，再提交交付记录，指明完整代码提交 SHA。交付记录自身可以是后续文档提交，不要求自引用其 SHA。
4. 验收方按该 SHA 独立构建、逐项验收，提交结论。失败项退回开发方；修复后交付新 SHA，保留旧失败记录并重新验收。
5. 本批全部约定标准通过后才关闭；受环境或证据限制的项目标记“阻塞／未验证”，不能算通过。

任务状态：待确认 → 待开发 → 开发中 → 待验收 → 已通过；验收失败为 待修复 → 开发中 → 待验收。任何阶段可标记 阻塞 并写原因、责任方及解除条件；取消须记录原因。

验收 B01 时可以规划 B02，但两批记录分开；B01 的验收结果不受随后 master 上的 B02 代码影响。

3. 文件归属与推送顺序

• 开发方主写业务源码和交付记录；验收方主写需求、验收结果和下一批规划。同一记录的同一段一次只由一方编辑，转交前先提交、推送并通知。
• 双方可以并行工作，但一次只由一方推送：约定推送窗口，推送完交还；另一方先同步再继续提交。无需引入自动锁或新系统。
• 按需在 docs/协作/ 保存批次记录，使用下面的内联模板即可；本流程不要求预先建立一套空文件。
• 推荐文件名：B01-需求.md（验收端主写）、B01-交付-01.md（开发端主写）、B01-验收-01.md（验收端主写）。修复轮次递增为 02，保留历史交付与失败结论。开发端接单状态放交付记录，不与验收端同时改需求文件。
• 推送窗口按交接回合转交：验收端发布需求后交给开发端；开发端发布交付后交回验收端。持有窗口的一方可提交本批记录；另一方可在固定 SHA 的隔离工作树工作、规划下一批，但不抢推。需要提前交接时通过用户传话明确约定；Git 不提供这把协作锁。
• 提交只包含本批相关文件；先检查差异，避免 git add . 混入日志、构建产物或其他工作。

开始工作或接到推送通知后，在主工作目录执行：

git status --short --branch
git remote get-url gitea
git fetch gitea
git log --oneline --left-right HEAD...gitea/master
# 确认当前在 master、工作区干净且没有分叉后：
git pull --ff-only gitea master

若开发端是新 clone，且该 Gitea 地址被命名为 origin，先执行 git remote -v；确认目标确实是上述 Gitea 地址后，用 git remote rename origin gitea 统一名称。已有 GitHub origin 的检出只需按需 git remote add gitea https://gitea.iiiii.run/admin/ycode.git，不要覆盖 GitHub 地址。可以将本地 master 的上游设为 gitea/master，但本流程中的命令仍显式带 gitea，避免裸 git push 误推。

有未提交修改时先检查并保留：适合提交的做独立提交，否则明确暂存并记录恢复方式；不要直接覆盖或清理。pull --ff-only 失败即停下检查，不用强制同步消除差异。

提交／推送前再次检查并与对方确认窗口：

git diff --check
git diff
# git add <明确的文件路径>
git diff --cached
# git commit -m "docs(B01): 记录验收结果"  # 按实际类型和批次填写
git fetch gitea
git log --oneline --left-right HEAD...gitea/master
git push gitea HEAD:master
git rev-parse HEAD
git ls-remote gitea refs/heads/master

只有本次推送成功且远端 SHA 与本次 HEAD 一致，才报告“已交接”。代码 SHA 和交接记录所在的提交 SHA 可以不同，必须分别标明。

若推送被拒绝，先 git fetch gitea、审阅双方新增提交；工作区干净后按实际情况快进，分叉则协商并显式 git merge gitea/master。冲突由文件负责人逐项核对、解决、检查后提交，再推送。涉及代码的合并必须重跑相关测试；若交付代码变了，登记新的交付 SHA。禁止 push --force，禁止用 reset --hard 或删除文件丢掉另一方／本地修改。

4. 固定 SHA 的独立验收

不要把“验收时最新的 master”当作交付版本。记录 git rev-parse HEAD、工作区状态、系统／架构、Node/npm 版本、依赖安装与构建命令；验收工作树应无源码改动。不能复用开发机的 node_modules 或旧构建产物来代替独立构建。

可选：主工作目录保留 master 写验收记录，另建 detached worktree 固定代码，不新增远端分支：

git fetch gitea
# 将 <完整交付SHA> 替换为交付记录中的真实值；目标目录须不存在。
git worktree add --detach ../ycode-accept-B01 <完整交付SHA>
cd ../ycode-accept-B01
git rev-parse HEAD
git status --short
node --version
npm --version
npm ci --legacy-peer-deps
npm run build
# 再执行本批交付记录列出的针对性测试；先阅读脚本，确认数据隔离。

只有明确指定 SHA、确认工作目录干净且实际运行该目录的构建，才开始验收。启动 dev 时记录检出绝对路径、完整 SHA、启动命令、实际端口与窗口，确认 renderer 属于本次检出；不能因为看到一个 YCode 窗口，就认定加载的是新版本。旧 dev 占用端口时只处理已确认属于本次测试的进程，不批量结束所有 Electron／Node。

当前锁文件存在已知 peer 依赖冲突，暂用 --legacy-peer-deps 与现有构建说明一致；后续修复依赖约束后同步更新此步骤。

构建失败先记录安装／构建阶段、命令、错误及环境差异，不把环境失败冒充功能失败，也不擅自升级依赖或修改锁文件。验收结束回主工作目录同步，再提交文档；不要在 detached worktree 提交验收记录。

数据与环境安全

• 启动前检查 src/main/index.ts 的数据初始化逻辑：默认 userData 在特定迁移条件下可能被清空。先备份重要数据，每轮必须显式设置独立的 YCODE_USER_DATA_DIR，使用全新绝对路径，并确认启动进程继承变量。
• Windows PowerShell 示例：$env:YCODE_USER_DATA_DIR = 'C:\ycode-qa\B01-run01'；创建该目录后，在同一终端启动该 SHA 构建的应用。每次复测使用新的隔离目录，或明确记录恢复的测试夹具。
• 只用测试账号、脱敏夹具和专用工作目录；禁止用正式用户数据验收。隔离 userData 不等于隔离所有外部服务与工作区，运行前另行核对路径、账号和外部写操作。
• 不提交令牌、密码、私钥、真实用户配置或含敏感信息的日志／截图。证据须脱敏，注明仓库相对路径或双方可访问的附件地址；仅本机临时路径不能作为唯一交付证据。

验证层级必须分开写

层级	能说明什么／不能替代什么
静态检查、类型检查、构建	代码与产物基础检查；不等于功能运行通过
单元测试、mock／回环测试	指定逻辑和模拟通路；不等于真实服务可用
真实 Electron 集成	主进程、预加载、渲染器及实际交互；注明使用开发态还是构建产物
Windows 安装包／运行环境	目标平台启动、打包与系统集成；不能用其他平台结果替代
原版对照／像素验收	按约定版本、窗口、缩放、字体、主题和状态比较；记录 REA Evidence ID 与限制

逐项区分“已实现”“mock／占位”“已验证”“未验证”。像素比较算法自测、token 对齐或构建成功均不是完整 1:1 验收；无相应环境／证据时如实标注，不补写通过结论。

5. 可直接复制的记录模板

需求／批次（规划方主写，双方确认）

批次／任务编号：B01 / YC-001
目标、优先级、负责人：
基线 SHA、依赖：
本批范围／不做：
验收标准：AC1…；AC2…（可操作、可判断，含必要异常场景）
所需环境／原版版本及 REA 证据：
双方确认、范围锁定时间：
状态／阻塞原因与解除条件：
下一批建议（不改变本批标准）：

交付（开发方主写）

批次／任务编号：
完整代码 SHA／需求记录位置：
改动范围、实现／mock／未实现：
环境与依赖、构建／测试命令、结果及脱敏证据位置：
验收启动步骤、隔离数据目录／夹具要求：
已知问题、风险、未验证项：
状态：待验收（或阻塞及原因）

验收／退回（验收方主写）

批次／任务编号、完整受测 SHA：
验收人／时间、系统／工具版本、干净工作树确认：
独立安装与构建命令／结果、隔离数据与夹具：
逐项标准：AC1 通过／失败／未验证；证据位置；验证层级
失败：前置条件 → 最短复现步骤 → 预期 → 实际；频率／影响
日志／截图：脱敏文件路径或共享附件地址（对应 SHA 与场景）
结论：已通过／待修复／阻塞；责任方及下一步：
复测：修复 SHA、重跑范围、结果（保留原失败记录）
下一批需求：另列编号，不覆盖本批结论

完成标准是“约定范围在指定 SHA 上有可复核的通过证据”，不是“代码已推送”。本文件只定义流程，不代表任何功能已经完成验收。

6. Git 交接消息与当前入口

提交 Git 记录后，由用户将以下短消息带到对应对话即可；双方不依赖彼此的聊天历史、电脑路径或 .tmp 目录。

需求已发布：gitea/master，记录提交 <完整SHA>。
请阅读 docs/协作/B01-需求.md，接单后在开发端实现、自测并回传交付记录。
本批推送窗口转交开发端。

开发已交付：受测代码 <完整SHA>，交付记录提交 <完整SHA>。
请阅读 docs/协作/B01-交付-01.md，在固定代码 SHA 的隔离检出验收。
本批推送窗口转交验收与规划端。

验收已回传：受测代码 <完整SHA>，验收记录提交 <完整SHA>。
请阅读 docs/协作/B01-验收-01.md；结论 <通过／待修复／阻塞>。
需要修复时只处理本轮失败项；新增需求另开批次。
本批推送窗口 <转交开发端／本批关闭>。

用户说“检查一下／继续验收”时，验收端先 fetch 并读取最新交付记录，不自行选择一个看起来最新的 SHA。没有交付记录时可以调查，但将结果标记为探索性复测，不能宣称正式批次通过。此流程没有设置后台轮询或定时自动执行。

当前对话交互对齐的需求与问题入口：

• 完整对齐方案：十项功能与原版证据基线。
• Windows复测与后续开发：针对 37ddb2c 的 A01～A09，包含已证缺陷、样式偏差与真实 SDK 验收缺口；该结果不自动适用于后续代码。

建议按依赖安排后续批次：问答分发／折叠／回答卡（A01、A03、A04），运行进度（A02），界面与加载（A05～A08），真实会话授权矩阵（A09）。这只是待规划清单，尚未接单、派发或关闭；每批应把上述需求模板补成可验收标准后再交给开发端。