开发与验收协作流程

1. 两台电脑，一条主线

开发机（本机）：负责业务源码、测试脚本、依赖与构建配置；实现需求、自测、构建并提交交付记录。
验收与规划机（另一台）：独立拉取指定提交、安装依赖和构建，验收、记录问题并规划下一批；不直接修改业务源码“顺手修复”。
使用当前仓库的 master 协作，不另设长期开发／验收分支。Git/Gitea 保存需求、代码、证据索引和结论，不会自动执行开发或验收；每次交接须明确通知对方批次、记录位置和 SHA。
开始前阅读根目录 AGENTS.md、docs/接手状态-2026-10-15.md 及本批相关记录。原版 WorkBuddy 取证只通过 REA，不能因验收困难绕过。

2. 批次与状态

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

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

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

3. 文件归属与推送顺序

开发方主写业务源码和交付记录；验收方主写需求、验收结果和下一批规划。同一记录的同一段一次只由一方编辑，转交前先提交、推送并通知。
双方可以并行工作，但一次只由一方推送：约定推送窗口，推送完交还；另一方先同步再继续提交。无需引入自动锁或新系统。
按需在 docs/协作/ 保存批次记录，使用下面的内联模板即可；本流程不要求预先建立一套空文件。
提交只包含本批相关文件；先检查差异，避免 git add . 混入日志、构建产物或其他工作。

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

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

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

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

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

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

4. 固定 SHA 的独立验收

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

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

git fetch origin
# 将 <完整交付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
# 再执行本批交付记录列出的针对性测试；先阅读脚本，确认数据隔离。

当前锁文件存在已知 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 上有可复核的通过证据”，不是“代码已推送”。本文件只定义流程，不代表任何功能已经完成验收。

8.6 KiB Raw Blame History