From 5b3dd42dce94da97e9c344ac82cc8ca6fd7fc68b Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Wed, 21 Oct 2026 12:53:19 +0900
Subject: [PATCH] docs: define two-machine development and acceptance workflow

---
 docs/协作/开发与验收协作流程.md | 141 ++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 docs/协作/开发与验收协作流程.md

diff --git a/docs/协作/开发与验收协作流程.md b/docs/协作/开发与验收协作流程.md
new file mode 100644
index 0000000..3113560
--- /dev/null
+++ b/docs/协作/开发与验收协作流程.md
@@ -0,0 +1,141 @@
+# 开发与验收协作流程
+
+## 1. 两台电脑，一条主线
+
+- **开发机（本机）**：负责业务源码、测试脚本、依赖与构建配置；实现需求、自测、构建并提交交付记录。
+- **验收与规划机（另一台）**：独立拉取指定提交、安装依赖和构建，验收、记录问题并规划下一批；不直接修改业务源码“顺手修复”。
+- 使用当前仓库的 `master` 协作，不另设长期开发／验收分支。Git/Gitea 保存需求、代码、证据索引和结论，**不会自动执行开发或验收**；每次交接须明确通知对方批次、记录位置和 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/协作/` 保存批次记录，使用下面的内联模板即可；本流程不要求预先建立一套空文件。
+- 提交只包含本批相关文件；先检查差异，避免 `git add .` 混入日志、构建产物或其他工作。
+
+开始工作或接到推送通知后，在主工作目录执行：
+
+```sh
+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` 失败即停下检查，不用强制同步消除差异。
+
+提交／推送前再次检查并与对方确认窗口：
+
+```sh
+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 固定代码，不新增远端分支：
+
+```sh
+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. 可直接复制的记录模板
+
+### 需求／批次（规划方主写，双方确认）
+
+```text
+批次／任务编号：B01 / YC-001
+目标、优先级、负责人：
+基线 SHA、依赖：
+本批范围／不做：
+验收标准：AC1…；AC2…（可操作、可判断，含必要异常场景）
+所需环境／原版版本及 REA 证据：
+双方确认、范围锁定时间：
+状态／阻塞原因与解除条件：
+下一批建议（不改变本批标准）：
+```
+
+### 交付（开发方主写）
+
+```text
+批次／任务编号：
+完整代码 SHA／需求记录位置：
+改动范围、实现／mock／未实现：
+环境与依赖、构建／测试命令、结果及脱敏证据位置：
+验收启动步骤、隔离数据目录／夹具要求：
+已知问题、风险、未验证项：
+状态：待验收（或阻塞及原因）
+```
+
+### 验收／退回（验收方主写）
+
+```text
+批次／任务编号、完整受测 SHA：
+验收人／时间、系统／工具版本、干净工作树确认：
+独立安装与构建命令／结果、隔离数据与夹具：
+逐项标准：AC1 通过／失败／未验证；证据位置；验证层级
+失败：前置条件 → 最短复现步骤 → 预期 → 实际；频率／影响
+日志／截图：脱敏文件路径或共享附件地址（对应 SHA 与场景）
+结论：已通过／待修复／阻塞；责任方及下一步：
+复测：修复 SHA、重跑范围、结果（保留原失败记录）
+下一批需求：另列编号，不覆盖本批结论
+```
+
+完成标准是“约定范围在指定 SHA 上有可复核的通过证据”，不是“代码已推送”。本文件只定义流程，不代表任何功能已经完成验收。