191 lines
14 KiB
Markdown
191 lines
14 KiB
Markdown
# 开发与验收协作流程
|
||
|
||
更新：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 .` 混入日志、构建产物或其他工作。
|
||
|
||
开始工作或接到推送通知后，在主工作目录执行：
|
||
|
||
```sh
|
||
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` 失败即停下检查，不用强制同步消除差异。
|
||
|
||
提交／推送前再次检查并与对方确认窗口：
|
||
|
||
```sh
|
||
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 固定代码，不新增远端分支：
|
||
|
||
```sh
|
||
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. 可直接复制的记录模板
|
||
|
||
### 需求／批次（规划方主写，双方确认）
|
||
|
||
```text
|
||
批次／任务编号：B01 / YC-001
|
||
目标、优先级、负责人：
|
||
基线 SHA、依赖：
|
||
本批范围／不做：
|
||
验收标准：AC1…；AC2…（可操作、可判断，含必要异常场景）
|
||
所需环境／原版版本及 REA 证据：
|
||
双方确认、范围锁定时间：
|
||
状态／阻塞原因与解除条件：
|
||
下一批建议（不改变本批标准）：
|
||
```
|
||
|
||
### 交付（开发方主写）
|
||
|
||
```text
|
||
批次／任务编号：
|
||
完整代码 SHA／需求记录位置：
|
||
改动范围、实现／mock／未实现：
|
||
环境与依赖、构建／测试命令、结果及脱敏证据位置：
|
||
验收启动步骤、隔离数据目录／夹具要求：
|
||
已知问题、风险、未验证项：
|
||
状态：待验收（或阻塞及原因）
|
||
```
|
||
|
||
### 验收／退回（验收方主写）
|
||
|
||
```text
|
||
批次／任务编号、完整受测 SHA：
|
||
验收人／时间、系统／工具版本、干净工作树确认：
|
||
独立安装与构建命令／结果、隔离数据与夹具：
|
||
逐项标准：AC1 通过／失败／未验证；证据位置；验证层级
|
||
失败：前置条件 → 最短复现步骤 → 预期 → 实际；频率／影响
|
||
日志／截图：脱敏文件路径或共享附件地址（对应 SHA 与场景）
|
||
结论：已通过／待修复／阻塞；责任方及下一步：
|
||
复测：修复 SHA、重跑范围、结果（保留原失败记录）
|
||
下一批需求：另列编号，不覆盖本批结论
|
||
```
|
||
|
||
完成标准是“约定范围在指定 SHA 上有可复核的通过证据”，不是“代码已推送”。本文件只定义流程，不代表任何功能已经完成验收。
|
||
|
||
## 6. Git 交接消息与当前入口
|
||
|
||
提交 Git 记录后，由用户将以下短消息带到对应对话即可；双方不依赖彼此的聊天历史、电脑路径或 `.tmp` 目录。
|
||
|
||
```text
|
||
需求已发布：gitea/master，记录提交 <完整SHA>。
|
||
请阅读 docs/协作/B01-需求.md，接单后在开发端实现、自测并回传交付记录。
|
||
本批推送窗口转交开发端。
|
||
```
|
||
|
||
```text
|
||
开发已交付：受测代码 <完整SHA>，交付记录提交 <完整SHA>。
|
||
请阅读 docs/协作/B01-交付-01.md，在固定代码 SHA 的隔离检出验收。
|
||
本批推送窗口转交验收与规划端。
|
||
```
|
||
|
||
```text
|
||
验收已回传：受测代码 <完整SHA>，验收记录提交 <完整SHA>。
|
||
请阅读 docs/协作/B01-验收-01.md；结论 <通过／待修复／阻塞>。
|
||
需要修复时只处理本轮失败项；新增需求另开批次。
|
||
本批推送窗口 <转交开发端／本批关闭>。
|
||
```
|
||
|
||
用户说“检查一下／继续验收”时，验收端先 fetch 并读取最新交付记录，不自行选择一个看起来最新的 SHA。没有交付记录时可以调查，但将结果标记为探索性复测，不能宣称正式批次通过。此流程没有设置后台轮询或定时自动执行。
|
||
|
||
当前对话交互对齐的需求与问题入口：
|
||
|
||
- [完整对齐方案](../WorkBuddy对话与输入交互统一对齐方案-2026-10-21.md)：十项功能与原版证据基线。
|
||
- [Windows复测与后续开发](../对话输入对齐复测与后续开发-2026-10-21.md)：针对 `37ddb2c` 的 A01～A09，包含已证缺陷、样式偏差与真实 SDK 验收缺口；该结果不自动适用于后续代码。
|
||
|
||
首批正式需求已整理为 [B01：对话与输入交互复测问题修复](B01-需求.md)，覆盖 A01～A09，分为 YC-001～YC-004，并列明逐项 AC、测试及证据要求。状态为“待开发”，不代表已经接单、交付或验收通过。本批需求推送成功后推送窗口转交开发端；开发端创建 `B01-交付-01.md` 接单、实现并交付。
|
||
|
||
2026-10-21 新增技能页需求见 [B02：推荐技能的已安装样式与重复入口](B02-需求.md)，包含 YC-005／006。它与 B01 分开交付：推荐中已安装卡不再保留添加 Plus，移除列表底部“查看已安装技能”，保留顶部导航，并核对既有 WorkBuddy REA 恢复记录及当前证据限制。
|