ycode/docs/协作/日常操作SOP.md

# YCode 日常操作 SOP

目的：在新对话里用一句“拉取代码”“运行 dev”准确执行已知流程，而不是重新研究项目或临时拼命令。本制度是**仓库内约定 + 固定脚本入口**，不是跨对话全局记忆，也不自动选择模型、开新任务或保证额度消耗。

## 1. 新会话只需定位一次

- 已在工具中打开本仓库：读取 `AGENTS.md`，使用已确认的仓库根目录。
- 尚未定位项目：用户给出当前机器的绝对路径；只问这一个缺失信息，不扫描整台机器、不猜历史目录。
- 默认根目录取当前 cwd 所属的 Git 仓库，并校验项目身份；也可显式传 `--root "<已确认绝对路径>"`。本入口没有跨机器路径注册表，不自动发现或切换其他检出。
- 首次使用需该检出已包含 `scripts/ops.mjs`。如果缺失，报告入口尚未安装，不能假称已启用或自行拼命令替代。

可复制的新对话首条消息（替换尖括号内容）：

```text
项目是 <本机 YCode 仓库绝对路径>。请读 AGENTS.md，按 docs/协作/日常操作SOP.md 执行。现在运行 dev（当前代码，不拉取）；遇到阻塞只报告错误码和日志，不自行修复。
```

之后在该上下文中直接说下面动作即可。另一台电脑或全新未打开仓库的会话仍须提供路径。

## 2. 意图 → 唯一固定动作

从已确认的仓库根目录调用，以下命令适用于 shell 与 PowerShell：

| 用户说 | 固定调用 | 边界 |
| --- | --- | --- |
| 拉取代码／同步最新代码 | `node scripts/ops.mjs pull --json` | 同步 `gitea/master`；不启动 dev |
| 运行 dev／启动 dev／启动当前代码 | `node scripts/ops.mjs dev --json` | 保留当前代码与本地修改；不拉取 |
| 拉取并启动／启动最新代码 | `node scripts/ops.mjs dev-latest --json` | 同步成功才进入 dev；同步失败不称“最新” |
| 重启 dev | `node scripts/ops.mjs restart-dev --json` | 重启当前检出的可确认归属实例；不拉取 |
| 停止 dev | `node scripts/ops.mjs stop-dev --json` | 仅停止当前目录中归属已验证的受管 dev；未知进程不杀 |
| 构建 | `node scripts/ops.mjs build --json` | 当前代码构建，含项目 build 定义的类型检查；不是全量验收 |
| 打包／生成 Windows 安装包 | `node scripts/ops.mjs package --json` | Windows x64 的安装包流程；不发布、不签名保证、不自动安装 |
| 查看状态／dev 在运行吗 | `node scripts/ops.mjs status --json` | 检查仓库与运行证据；不启动或同步 |

`doctor` 是明确要求环境诊断时的固定只读入口，不在每次操作前额外执行。除非用户指定限制，使用脚本默认超时；需要时可用 `--timeout-ms`（1000–3600000）。不将任意用户文本转成 shell 命令。

## 3. 助手执行纪律

1. 确认目录和意图后，直接调用对应入口**一次**；不要先跑全量测试、REA、业务研究、依赖升级或拆子任务。动作自身的检查由脚本执行。
2. 读取结构化终态。build/package 等可能超过工具首次等待时间；工具返回 session ID 时，允许续读同一执行会话至脚本终态或既定时间预算，不另起重复操作、不重新调用 ops。首次空输出不代表 PASS；不要把等待输出误作重新执行授权。
3. `PASS` 只表示该动作在输出证据范围内成功。dev 的端口开放、HTTP 响应或进程存活不等于真实窗口可用；窗口未核验时明确说“窗口未验证”，不宣称完整启动验收。
4. `BLOCKED`、`FAIL`、`UNSUPPORTED`：报告错误码、原因、日志与所需下一步，停止依赖该结果的操作。只允许脚本内部已编码、有超时/次数上限的恢复；模型不得自行循环重试、升级依赖、修代码或扩大检查。
5. 更复杂故障交给明确授权的诊断/修复任务；保留本次 JSON 和日志作为交接。不要借“快速执行”绕过网络、文件、进程、安装或其他审批。

## 4. 不可变安全边界

- `pull`/`dev-latest` 只接受脚本校验通过的仓库、远端和 `master`，在干净工作区快进到此次 fetch 的 `gitea/master`。不以缓存 SHA 证明最新。
- 脏工作区、分支不匹配、分叉、远端不匹配、凭据缺失或网络失败均按结构化阻塞处理；不 stash、reset、强推、改凭据、换仓库或另建 worktree。当前代码模式可保留本地修改，须如实报告 dirty。
- 不按进程名批量杀 node/Electron；仅脚本验证归属的受管实例可被重启。无法确认归属就保留并报告。
- dev 保留 `YCODE_SKIP_KERNEL_DATA_RESET=1`，不主动切换生产/测试数据目录，不发模型消息验证启动。
- 当前 dev 活跃或归属未知时，`pull`、`dev-latest`、`build`、`package` 可能阻塞，以避免覆盖正在运行的文件。用户明确要求停止后使用 `stop-dev`，再按授权执行原动作；不自动停止。未知进程不得为解除阻塞而杀掉。
- 工作区操作锁冲突不自动解锁。超时后若子进程可能仍写入，锁可能保留；不要删除锁或 PID 状态文件来绕过另一个任务。
- 打包不等于发布、上传、安装、签名或产品功能验收，这些需单独授权及证据。

## 5. 统一结果与回复

入口 JSON 的稳定顶层字段：`schemaVersion`、`action`、`status`、`ok`、`code`、`summary`、`root`、`git`、`evidence`、`logs`。取得 Git 信息后位于 `git.sha`、`git.dirty`、`git.branch`；早期失败可能没有 Git 信息。动作专属证据位于 `evidence`，日志也可能在 `evidence.logPath`。退出码：`PASS=0`、`BLOCKED=2`、`FAIL=3`、`UNSUPPORTED=4`。

回复保留以下信息；不适用或未取得的字段明确标注，不补猜值：

| 信息 | 要求 |
| --- | --- |
| 目录／版本 | 实际 `root`、SHA、dirty；本地修改存在时不称“纯提交版本” |
| 动作／结果 | `action`、`status`、`code`、简短摘要；失败不能省略错误码 |
| 日志 | JSON 返回的实际日志位置或“无日志” |
| dev | 实际 URL/端口、PID、复用或新启、窗口验证范围；不能固定写 5173 或历史 PID |
| 构建／打包 | 返回的实际产物路径；未生成就写未生成，存在旧文件不等于本次成功 |

推荐短回复：

```text
<动作>：<状态>（<code>）。
目录：<root>；版本：<SHA>；本地修改：<有/无/未知>。
<dev URL、PID 与窗口验证范围，或实际产物路径>。
日志：<实际位置/无>。<若失败：阻塞原因及需要用户决定的下一步>。
```

## 6. dev 机器检查与验收边界

- dev/重启/停止的原生生命周期当前面向 Windows；其他平台依输出明确标为 `UNSUPPORTED`，不以后台 HTTP 服务冒充 Electron 桌面启动。Windows 实际启动、停止、重启与窗口行为仍需目标机器验收，离线自测通过不等于已获 Windows 实机证明。
- dev 成功判定包含目标进程归属、响应窗口、renderer 应用目录、实际端口和仓库组件响应，并要求本次运行的可见应用 DOM 布局心跳。开发钩子 `src/main/dev-ops-health.ts` 仅在非打包且设置 ops run UUID 时启用；心跳在 `.tmp/ops/renderer-health.json`，绑定本次运行及进程，不增加网络/CDP 通道。
- 机器检查能防止“只有进程或 Local URL 就报成功”，不证明业务功能、模型调用或完整 UI 行为正确。陈述成功仍须限定为实际返回的证据。
- dev 状态、日志和心跳在本检出的 `.tmp/ops/`；调度器操作锁和日志在 Git 私有目录的 `ycode-ops/`。报告实际输出路径，不将其复制成其他机器的固定路径。
- `UNTRACKED_DEV` 不自动收编或删除；启动超时保留单个可追踪进程，不反复新建。重启和停止仅作用于 PID、创建时间及命令行归属已验证的进程树。缺少依赖按阻塞报告，不自动重装。

真实 dev 窗口的详细验收标准见 [Dev 启动 SOP](Dev启动SOP.md)；业务开发与独立验收仍按原有协作流程，日常操作成功不替代产品验收。