162 lines
9.2 KiB
Markdown
162 lines
9.2 KiB
Markdown
# YCode Dev 启动 SOP
|
||
|
||
适用：用户说“启动 dev”“启动当前代码”“启动最新代码”“使用子代理启动”。这是执行任务，目标是让正确版本的真实窗口可用；不要先做业务调研、REA、方案设计、全量测试或依赖升级。
|
||
|
||
## 0. 先选目录和版本
|
||
|
||
按顺序选，不猜：
|
||
|
||
1. 用户明确指定路径／版本时，使用指定目标。
|
||
2. 用户说“当前／本地代码”时，使用已确认的用户预览目录，保留本地修改，不自动同步远端。
|
||
3. 用户说“最新代码”或明确要求同步时，目标是 fetch 后的 **`gitea/master`**，在干净的用户预览检出同步。
|
||
4. 用户只说“启动 dev”时，复用上次确认的用户预览目录，不擅自切分支或换目录。
|
||
|
||
**当前验收电脑的用户预览目录：**
|
||
|
||
```text
|
||
C:\Users\Administrator\.codex\worktrees\workbuddy-alignment-audit\YCode
|
||
```
|
||
|
||
这不是跨机器通用路径。另一台电脑以用户明确指定的开发目录为准，不照搬该路径。下列命令中的 `$devRoot` 都须一致指向目标目录。
|
||
|
||
- `C:\Users\Administrator\code\YCode` 是当前对话原工作区，可能停留在旧 master 并有文档修改，不能仅因它是环境 cwd 就拿来启动最新版本。
|
||
- `b01-accept-01` 等验收检出不用于用户预览；已有验收进程可能正在被另一任务使用，不顺手停止或更新。
|
||
- `b01-review-records` 是协作文档检出，也不是默认 dev 目录。
|
||
- 不记忆某个旧 SHA 作为“最新”；每次从实际 Git 状态取值。
|
||
|
||
如果预览目录不存在，用应用的 `list_artifacts` 查找可复用检出；没有适用检出时用 `create_worktree(ref="gitea/master")` 创建。等待工具返回最终路径后，再继续。不要覆盖用户原目录或重用固定版本验收目录。
|
||
|
||
## 1. 首次工具动作：检查 Git 和正在运行的 dev
|
||
|
||
在选定目录执行下面命令。`exec_command` 的 `workdir` 也设为该目录。
|
||
|
||
```powershell
|
||
$devRoot = 'C:\Users\Administrator\.codex\worktrees\workbuddy-alignment-audit\YCode'
|
||
git -C $devRoot rev-parse --show-toplevel
|
||
git -C $devRoot rev-parse HEAD
|
||
git -C $devRoot status --short
|
||
Get-CimInstance Win32_Process |
|
||
Where-Object { $_.Name -eq 'node.exe' -and $_.CommandLine -match 'electron-vite' } |
|
||
Select-Object ProcessId, ParentProcessId, CommandLine | Format-List
|
||
Get-Process electron -ErrorAction SilentlyContinue |
|
||
Where-Object { $_.MainWindowHandle -ne 0 } |
|
||
Select-Object Id, MainWindowTitle, Responding | Format-Table
|
||
```
|
||
|
||
执行规则：
|
||
|
||
- 当前目录、版本均正确且已正常运行：直接核验并复用，不再执行第二次 `npm run dev`。
|
||
- “当前代码”允许保留脏工作区；报告 SHA 时同时说明有本地修改，不能把它称为纯提交版本。
|
||
- “最新代码”遇到脏工作区：不要 stash、reset、清理或直接合并；换干净预览检出，保留原修改。
|
||
- 需要停止旧 dev 时，先用命令行、进程树确认属于**目标预览目录**，再只停止对应的主 Electron 与 Vite 进程。不要使用 `Stop-Process -Name node,electron` 等批量操作，也不要复制本文中的历史 PID。
|
||
- 不知道进程归属时先不停止。Vite 可使用其他端口；最后必须说明实际端口。
|
||
|
||
## 2. 仅“最新代码”执行同步
|
||
|
||
“当前／本地代码”跳过本节。干净的预览检出执行：
|
||
|
||
```powershell
|
||
$devRoot = 'C:\Users\Administrator\.codex\worktrees\workbuddy-alignment-audit\YCode'
|
||
if (git -C $devRoot status --porcelain) { throw '目标有本地修改，改用干净预览检出' }
|
||
git -C $devRoot fetch gitea
|
||
if ($LASTEXITCODE -ne 0) { throw 'fetch 失败，尚未确认最新版本' }
|
||
git -C $devRoot merge --ff-only --quiet gitea/master
|
||
if ($LASTEXITCODE -ne 0) { throw '无法快进，不要强制覆盖；改用干净检出' }
|
||
git -C $devRoot rev-parse HEAD
|
||
git -C $devRoot rev-parse gitea/master
|
||
```
|
||
|
||
末尾两个完整 SHA 必须相同。不要使用 `origin`、强制推送或 `reset --hard`。fetch 失败可以报告失败并保留已有窗口，但不能把缓存中的版本称为“已同步最新”。
|
||
|
||
## 3. 启动，只运行 dev
|
||
|
||
已有可用依赖就复用，用户预览不要求每次重装。正式独立验收另按[协作流程](开发与验收协作流程.md)，不能用预览复用依赖替代验收。
|
||
|
||
使用 `exec_command`：
|
||
|
||
- `workdir`：选定的 `$devRoot`。
|
||
- `yield_time_ms`：`1000`。
|
||
- `cmd`：下面整块命令。
|
||
|
||
```powershell
|
||
$devRoot = 'C:\Users\Administrator\.codex\worktrees\workbuddy-alignment-audit\YCode'
|
||
Set-Location -LiteralPath $devRoot
|
||
$env:YCODE_SKIP_KERNEL_DATA_RESET = '1'
|
||
npm run dev
|
||
```
|
||
|
||
**保留返回的 session ID，拿到启动日志即继续核验，不等待 dev 自己退出。**
|
||
|
||
- 环境变量必须与 npm 在同一命令／进程设置；不要假定不同 exec 调用会保留变量。
|
||
- `YCODE_SKIP_KERNEL_DATA_RESET=1` 防止启动迁移清理正常用户数据，不能漏。
|
||
- 普通预览不新设 `YCODE_QA_OFFSCREEN`、`YCODE_QA_DIRECTORY`、临时 `YCODE_USER_DATA_DIR`。若已有这些变量，先核对其用途，不要意外启动隐藏窗口或测试数据。
|
||
- 不用 `npm run build`／preview 替代 dev；electron-vite dev 会构建需要的 main／preload。
|
||
- 不额外开启可见终端，不用 `Start-Job` 或另建复杂后台服务。现有 exec session 就能承载 dev。
|
||
- 端口以日志中的 `Local: http://localhost:.../` 为准，不能硬写 5173。
|
||
|
||
缺依赖时才执行 `npm ci --legacy-peer-deps --no-audit --no-fund`，不得升级 package.json 或锁文件。如果当前 npm 明确跳过 Electron postinstall 且 Electron 无法启动，执行项目现有的 `node node_modules/electron/install.js`，不要全局放开所有未知安装脚本。
|
||
|
||
## 4. 必须核验窗口，不能见到 Local URL 就宣布成功
|
||
|
||
至少核对：
|
||
|
||
1. 目标目录的 Git SHA；最新模式与此次 fetch 的 `gitea/master` 一致。
|
||
2. Vite 日志中的实际端口和 node 命令行指向选定预览目录。
|
||
3. 有对应的真实 YCode 窗口，`Responding=True`。
|
||
4. 对应 renderer 的 `--app-path` 指向选定目录；HTTP 能返回该目录的组件。不是另一个旧窗口刚好叫 YCode。
|
||
|
||
下面是只读核验命令，`$devPort` 要填本次日志中的端口：
|
||
|
||
```powershell
|
||
$devRoot = 'C:\Users\Administrator\.codex\worktrees\workbuddy-alignment-audit\YCode'
|
||
$devPort = 5174 # 示例值；必须按本次启动日志修改
|
||
git -C $devRoot rev-parse HEAD
|
||
Get-NetTCPConnection -State Listen -LocalPort $devPort |
|
||
Select-Object LocalPort, OwningProcess
|
||
Get-CimInstance Win32_Process |
|
||
Where-Object { $_.Name -eq 'electron.exe' -and $_.CommandLine -match '--type=renderer' } |
|
||
Select-Object ProcessId, ParentProcessId, CommandLine | Format-List
|
||
Get-Process electron -ErrorAction SilentlyContinue |
|
||
Where-Object { $_.MainWindowHandle -ne 0 } |
|
||
Select-Object Id, MainWindowTitle, Responding | Format-Table
|
||
$response = Invoke-WebRequest -Uri "http://localhost:$devPort/src/components/ChatPane.tsx" -UseBasicParsing
|
||
Write-Output "RendererStatus=$($response.StatusCode)"
|
||
```
|
||
|
||
注意 node_modules 可能是 junction，Electron 可执行文件可能来自原仓库。判断应用目录要看 Vite 启动命令与 renderer 的 `--app-path`，不能只看 electron.exe 所在位置。
|
||
|
||
窗口还没出现时，读取该 exec session 输出，短暂等待后再检查；若明确报错，处理该错误。不要不断启动新实例。不要为确认界面而发送模型消息、操作用户会话或修改用户设置。
|
||
|
||
## 5. 用户要求子代理时
|
||
|
||
没有明确要求就无需为启动任务额外委派。要求子代理时：
|
||
|
||
- 使用当前 AGENTS 约定的模型与推理配置，不在 SOP 中另设模型。
|
||
- 只派“按本 SOP 启动”，不附带源码研究、原版取证、修复、测试矩阵等任务。
|
||
- 子代理首个执行动作是第 1 节，不先写长计划。拿到启动 session、SHA 和 URL 就回报，主线程最终核验。
|
||
- 主线程不要每 10 秒反复询问或追加整套指令。委派后约 30 秒检查一次结果；60 秒仍未进入执行工具时，不再启动相同配置的第二个子代理。
|
||
- 如必须接手，先中断原子代理，再重新检查进程和端口；工具启动的进程可能仍活着，不能因代理已中断就认为没有启动。能复用则复用，确认未运行才接手启动。
|
||
- 如实际由主线程启动，最终如实说明，不能声称子代理已完成。
|
||
|
||
推荐委派消息：
|
||
|
||
```text
|
||
按 docs/协作/Dev启动SOP.md 启动用户指定的 dev。
|
||
目标目录：填已确认绝对路径；版本策略：当前代码／最新 gitea/master。
|
||
不改源码、不提交、不运行额外测试。先执行第1节。
|
||
拿到 SHA、URL、exec session ID 后立即回报，主线程核验窗口。
|
||
```
|
||
|
||
## 6. 完成回复
|
||
|
||
成功必须同时有“版本正确、进程存活、真实窗口响应、renderer 正常”证据。最终回复只需：
|
||
|
||
```text
|
||
dev 已启动，窗口正常响应。
|
||
版本：实际短 SHA（有本地修改则注明）。
|
||
地址：本次实际 URL。
|
||
如并存旧 dev，明确其端口；本次操作不代表功能已验收。
|
||
```
|
||
|
||
失败则写清卡在 fetch、依赖、构建、端口还是窗口，并给实际错误；不以“我会启动”“已有 Local URL”或“子代理还在运行”代替完成结果。
|