YCode 日常操作 SOP

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

1. 新会话只需定位一次

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

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

项目是 <本机 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. 助手执行纪律

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

推荐短回复：

<动作>：<状态>（<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；业务开发与独立验收仍按原有协作流程，日常操作成功不替代产品验收。

8.0 KiB Raw Blame History Unescape Escape