OpenClaw 是一个 AI 网关/代理平台,GTS-Play 用它做开发流程的调度层。全套工具链目前包含 23 个 Skill。
为什么需要这么多 Skill?因为每个开发阶段——分析、编码、测试、部署、记忆、通知——都有专门的自动化流程。刚开始只有 3-4 个 Skill,很快就发现不够:AI 在"修 bug"时可能还需要"查日志"、"跑测试"、"保存记忆",每个都是单独的 Skill。Skill 数量从6月下旬的16个,随着内容生产、搜索等新需求持续增长到现在的23个,每个 Skill 对应一个具体的开发动作。
开发类:
| Skill | 作用 |
|---|---|
| gts-dev-feat | 新功能开发——调度 OpenCode 生成代码 |
| gts-dev-fix | Bug 修复——分析日志 + 锁定测试 + 修复 |
| gts-dev-refactor | 代码重构——不改变行为只改结构 |
三个开发 Skill 的核心区别是入口和出口:
gts-dev-feat:从需求出发,先写 Delta Specs → 确认 → 写代码 → BDD 测试 → 提交。不需要事先分析日志。gts-dev-fix:从 bug 出发,先分析日志 → 定位根因 → 写测试(RED)→ 修代码(GREEN)→ 提交。有一步必须做:分析日志之前不写代码。 有个经典反例——AI 看到 bug 不查日志直接改代码,拍脑袋修了三次都没修好,最后查日志发现是 animationName 被覆盖了。gts-dev-refactor:从现有代码出发,行为不变,结构变。完成后 BDD 测试全通过才能提交。测试类:
| Skill | 作用 |
|---|---|
| gts-e2e-test | 手动 E2E 测试(双窗口) |
| gts-e2e-auto | 自动化 E2E scenarios |
| gts-e2e-perf | 性能测试(FPS/CPU 热点) |
| gts-test | BDD 集成测试 |
测试 Skill 的设计理念是:将测试流程固化,AI 不需要思考"怎么测",只要执行。 比如 gts-e2e-test 的流程固定为:重启服务端 → 打开窗口 1 → 打开窗口 2 → 匹配 → 进入游戏 → 验证。每一次步骤都一样,AI 执行久了就像肌肉记忆。
gts-e2e-perf 是后来加的——发现前端性能优化后需要验证 FPS 是否提升,所以专门写了一个 Skill 来做双窗口 + CDP Profiler 录制 + 自动分析。
部署运维类:
| Skill | 作用 |
|---|---|
| gts-deploy | 部署到腾讯云 SCF |
| gts-service | 启动/重启/停止本地服务 |
| gts-logs | 自动抓取 SCF 日志 |
gts-service 是一个特别容易出错的 Skill。因为重启顺序必须正确(先 room 再 match),而且 room 重启后必须等它 ready 才能继续。早期 Skill 的实现是粗暴的 kill -9 && sleep 3 && yarn dev——但 room 不一定 3 秒就启动完。后来改成了健康检查轮询。
代码管理类:
| Skill | 作用 |
|---|---|
| gts-save-flow | 审核→BDD→编译→规格→笔记→记忆→提交 |
| gts-save-memory | 保存 daily log + commit |
| gts-git-commit | git add → commit(或 push) |
| gts-git-pull | 从 GitHub 拉取更新 |
gts-save-flow 是最长的 Skill——全流程跑完大约需要 5-10 分钟。早期它什么都能干(审核+BDD+编译+规格+笔记+记忆+提交),但太长了,AI 在中间容易出错(比如规格更新时忘了更新 workflow-rules.md)。所以拆成了更细的粒度的多个 Skill。
辅助类:
| Skill | 作用 |
|---|---|
| gts-analysis | 分析需求/方案,输出报告 |
| gts-code-review | 代码审查(调度 OpenCode 审) |
| gts-recall | 查记忆+近对话,分析工作进展 |
| gts-stop | 紧急停止一切操作,清理残留进程 |
| gts-conversation-end | 清理服务/定时器,结束对话 |
gts-recall 是最"软"的 Skill。它不生成代码、不跑测试——只查记忆、查近期的对话记录,然后给一个"工作简报":过去几天做了什么、有哪些进展、下一步建议。对于长期项目的回顾特别有用,尤其是兄弟隔了一周没开发,回来不知道从哪继续。
内容生产类:
| Skill | 作用 |
|---|---|
| yuque-jianshu-fetch | 抓取语雀知识库/简书文章转 Markdown 保存到笔记目录 |
| zhihu-auto-publish | CDP 控制 Chrome 粘贴 HTML 到知乎编辑器 |
| cnblogs-publish | MetaWeblog API 自动发布 Markdown 到博客园 |
yuque-jianshu-fetch 解决的是"知识同步"问题——语雀上的技术文章不能直接当本地 Markdown 用。这个 Skill 抓取语雀文档内容 + 简书文章,转为标准 Markdown 格式保存到笔记目录。语雀的 API 需要 OAuth 鉴权,简书不需要登录但需要处理 HTML 转 Markdown 的格式问题。
zhihu-auto-publish 是发布工具——通过 Playwright CDP 连接 Chrome 浏览器实例,打开知乎专栏编辑器粘贴 HTML 内容。知乎编辑器不接受 Markdown 粘贴,必须先转 HTML。这个 Skill 用到纯前端 JS 的 TurndownService(HTML→Markdown 反向工具)来处理格式转换。发布前必须人工检查,因为 CDP 控制浏览器存在死链接和误操作的风险。
cnblogs-publish 走的是博客园的 MetaWeblog API(XML-RPC 协议),纯后端操作,不需要浏览器。它处理 Markdown 渲染——博客园的 Markdown 引擎和标准的 GFM 有差异,需要在发布前用 marked + 自定义 renderer 做一次渲染适配。
搜索类:
| Skill | 作用 |
|---|---|
| web-search | 多源 Web 搜索(firecrawl/searXNG),带去重 |
web-search 是一个看起来简单但其实有坑的 Skill。搜索工具(web_search)只返回摘要,不返回完整内容——摘要可能截断了关键信息。所以标准流程是:搜索 → 读摘要筛选 → 用 web_fetch 拉完整页面 → 去重合并。中文搜索还有个额外的问题:同一 query 在不同时间返回不同结果,所以搜索后要尽量把可用的页面都抓下来,减少重复搜索。
| 通道 | 用途 | 优先级 |
|---|---|---|
| 桌面通知(msg *) | 需要兄弟确认时 | 最高 |
| 飞书通知 | 日常通知 | 正常 |
| 聊天窗口 | 普通消息 | 正常 |
规则:需要兄弟决策时,必须发桌面通知。不能假设对方在聊天工具前。
有一次 AI 完成了一项修复,在飞书上给我留言"已修复,请验收"。但我在忙别的事没有看飞书——结果 AI 等了两个小时才得到回复。后来在 gts-dev-fix 的结尾加了一步:如果 fix 需要兄弟确认,先发桌面通知(msg * "Bug XXX 已修复,请验收"),再发飞书通知。桌面通知的到达率接近 100%。
每次收到消息后,第一件事:检查后台任务是否完成。有已完成任务先汇报,再接新活。
这是最高频的违规项——但也是最容易记住的:先查后做,先汇报再接。
入口检查不只是检查子 session——还包括检查 process list 中是否有后台服务在跑。比如 room-service 被 gts-service skill 重启了,但匹配服务还没起来——这时候收到一个"帮我查一下日志"的命令,AI 应该先汇报"服务正在重启中",而不是去查日志(查到的也是旧数据)。
这条入口检查协议是用几个惨痛教训换来的。有一次 AI 在 room-service 重启过程中开始查日志——查到的日志是重启前的旧日志,AI 基于旧日志做了错误判断,又一个下午白费了。
Skill 不是一次写成的。每个 Skill 都经历了"粗→精"的过程:
以 gts-dev-fix 为例:
每个 v 都需要 1-2 天的实际使用,才能发现痛点、迭代优化。16 个 Skill 在 30 天内迭代完毕——平均 2 天一个 Skill,每个迭代 1-2 次。
以下为 6 个核心 Skill 的完整 SKILL.md 文件内容:
---
name: "gts-acceptance"
description: "循环改→测→验直到通过或超时,支持多问题顺序修复,TDD集成+E2E验收,通过后自动部署"
---
# 验收流程(硬性操作规程)
> 触发词:兄弟说「验收:<标准>」或「验收」。
> 自动循环模式:Specs 发现 → 逐个问题走 TDD 修复(注入 Specs)→ 全量集成测试 → Specs 覆盖验证 → E2E 自动验收 → 自动部署 → 双通道通知(含覆盖统计)。
> 全程自动化:执行 `gts-dev-fix` 时不需要兄弟确认。
> ⚠️ 验收结束时必须执行双通道通知,禁止只跑完不说话。
---
## 🔴 两级测试流程规则(本 Skill 所有步骤共用)
### 区分
| 层级 | 工具 | 成本 | 验证内容 |
|------|------|------|---------|
| 集成测试 | BDD / jest | 低(秒级) | 代码层逻辑,纯函数/逻辑层/API 流程 |
| 自动测试 | E2E Playwright | 高(分钟级) | 浏览器层完整渲染 + 用户交互 |
### 流程纪律
**集成测试 > E2E 自动测试** — 因为集成测试成本更低,应优先使用。
Bug → 加日志 → 写/改集成测试复现 bug → 收集数据 → 调度 OpenCode Pro 分析根因 → 修改测试使其按根因场景真实失败(RED) → 调度 OpenCode 修复代码 → 集成测试全绿(GREEN) → 调度 OpenCode 写 E2E 测试脚本 → 跑 E2E → ✅ E2E 通过 → 自动部署 → 双通道通知 → ❌ E2E 失败 → 调度 OpenCode Pro 分析原因 → 修 → 重测
### 线上 bug 的特殊处理
E2E 只跑线上环境,本地不跑。
| 类型 | 处理 |
|------|------|
| 线上 bug | 线上 E2E 复现 → 截图+日志 → 调度 OpenCode Pro 分析 |
| 本地 bug | 本地 E2E 复现 |
| 线上部署/环境 bug | 线上 E2E |
## 通知协议(本 Skill 所有步骤共用)
验收结束时执行**双通道通知**:
### 1️⃣ 桌面通知
```bash
msg * "<30字摘要>"
{
"kind": "agentTurn",
"message": "<通知内容(≤10字)>",
"delivery": { "mode": "announce", "channel": "feishu", "to": "user:ou_..." }
}
msg *test/e2e/auto/*.cjsheadless: false登录 → 创建房间 → 加入 → 准备 → 开始游戏 → 操作 → DebugEndGame → 验证 UI 元素
→ 关闭弹窗 → 返回房间 → 再次进入 → 截图
验收流程中必须先让集成测试因 bug 真实失败,再修复代码使其通过。
通知时机: 验收结束时立即执行。
| 结果 | 桌面消息 | 飞书通知(≤10字) |
|---|---|---|
| E2E 全绿 + 部署成功 | ✅ ✅ | 验收通过+已部署 |
| E2E 失败 | ❌ | 验收未通过 |
| 部署失败 | ⚠️ 部署失败 | 部署失败 |
通知内容必须包含:
readState / writeState 真实操作如果兄弟报告了多个 bug,用一个验收流程按顺序逐个修复:
test/e2e/e2e-helpers.cjstest/e2e/auto/*.cjs
### gts-e2e-test
```markdown
---
name: "gts-e2e-test"
description: "兄弟说「e2e测试」时触发。手动双窗口,列出可选 scenarios 供选择。线上测试跳过本地服务。"
---
# E2E 手动测试(硬性操作规程)
> 触发词:兄弟说「e2e测试」/「e2e」/「e2e test」,可附带操作描述和验证目标。
> 双窗口手动操作,可选注入专用日志,停止后抓数据验证。
---
## 步骤
### Step 0:判断环境 + 重启服务 + 部署检查
**先判断测试目标:**
#### SCF 线上环境(脚本含 `scf`、URL 以 `.tcloudbaseapp.com` 结尾等)
1. **跳过本地服务重启**
2. **检查部署状态**:运行 `git diff HEAD -- packages/frontend/src/ packages/room-service/src/ packages/match-service/src/ packages/logic/src/` 检查是否有未部署的生产代码改动
- 如有改动 → 询问兄弟:「有 N 个生产文件待部署,要先部署再测吗?」
- 如兄弟说「部署」→ 走 gts-deploy skill 部署对应服务
- 如兄弟说「不用」→ 跳过,直接测线上现有版本
3. **继续 Step 1**
#### 本地环境
先确认「是 webpack dev server 还是本地 prod」→ 按以下步骤重启:
**前置检查 — 前端服务:**
1. 检查 webpack-dev-server 是否在运行:`Get-Process -Name node | Where-Object { $_.CommandLine -match 'webpack' }`
2. 如未运行 → `cd <project>\packages\frontend && yarn webpack:dev-server` 启动,等启动完成
3. 如已运行 → 跳过,保留现有 webpack 进程
**重启核心服务:**
4. Kill 现有 room (4003) + match (3000) 进程
5. 启动 room-service(`yarn dev`),等启动完成
6. 启动 match-service(`yarn dev`),等连接成功
不重启会导致 match-service WS 失连,游戏卡在"查找房间中"。
### Step 1:解析输入 + 明确验证目标
兄弟可选择指定 scenarios 或附带验收标准。
**每次测试前必须先明确验证目标**:
- 兄弟说清楚要验证什么、预期行为是什么、怎么算通过
- 如果本次测试是在某个功能变更(`feat:/fix:/refactor:`)流程中触发的,验证目标以 `笔记/项目文档/changes/<日期>-<功能名>/spec.md` 中的验证策略为准
- 如果兄弟没有说验证目标,主动问:「这次 E2E 要验证什么?预期行为是什么?」
**无指定时:** 默认跑 `scenarios/perf-scene3.json`。
**指定场景时:** 列出可选 scenarios 供兄弟选择(**动态读取 `test/e2e/scenarios/*.json`**):
=== 可用 Scenarios ===
[1] 两轮胜利弹窗 — scenarios/gameover-twocycle.json (46块, auto) [2] SCF 双窗口 — scenarios/scf-twowin.json (22块, manual) [3] 性能录制 — scenarios/perf-scene3.json (24块, perf)
运行方式:node e2e-runner.cjs scenarios/
所有 scenarios 路径相对于 `packages/frontend/test/e2e/`。
> **每次列出时动态读取** `packages/frontend/test/e2e/scenarios/*.json`。上面的列表是示例,以实际文件为准。
**有验收标准时:** 在选定 scenario 基础上修改或新增 scenario JSON。
**无验收标准时:** 直接跑选定 scenario。
### Step 2:生成并启动测试
**有验收标准:** 以选定的 scenario 为模板修改或新增 JSON,保存到 `test/e2e/scenarios/`。
**无验收标准:** 直接跑选定的 scenario:
node e2e-runner.cjs scenarios/
以 background 模式运行,**记录 session ID**。`process(action=list)` 确认进程已在运行,然后告知兄弟「开搞」。
> ⚠️ poll 只做状态检查,不拉日志数据。跑完再一次性拉日志分析。
### Step 3:不阻塞等待
- **启动后告知兄弟,不持续等待**
- **兄弟发新消息时**:
- 判断消息是否与当前测试相关(如看日志、分析结果等)→ **保留测试进程**,直接处理
- 与当前测试无关(让我干别的事)→ 先 `process(action=kill, sessionId=<记录id>)` 精准 kill 测试进程,再处理新请求
- **如果测试自然退出(收到 completion event)** → 输出结果分析 + 发通知
### Step 4:结果分析
场景退出后:
1. **日志已自动保存** — saveLogs block 或 saveE2EData 已在停止时自动保存日志
2. **简要分析** — 在会话中输出关键结论
3. **写入变更文档(如当前有变更流程)** — 如果本次测试是在某个功能变更流程中触发的,将测试结论写入对应 `log.md`:
### Step 5:双通道通知
分析后发飞书通知(≤10字)+ 桌面消息告知兄弟。
---
## 索引维护规则
> Scenarios 新增/移动/重命名后,**必须同步更新本 SKILL.md 的场景索引表**。
> 运行方式统一为:`node e2e-runner.cjs scenarios/<name>.json`
## 执行纪律
1. **判断测试环境** — SCF 线上跳过 Step 0 服务重启,但需做部署检查
2. Scenarios 在 `test/e2e/scenarios/` 目录下查找(JSON 文件)
3. 默认无指定时跑 perf-scene3
4. 有验收标准时基于 template 修改或新增 scenario JSON
5. 测试过程不阻塞等兄弟
6. 跑完后双通道通知
---
name: "gts-deploy"
description: "部署GTS-Play服务(room1/room2/match1/frontend/all)到SCF或静态托管。E2E通过后自动部署不询问"
---
# gts-deploy — 部署 GTS-Play 服务到线上
## 触发词
- `部署`
- `发布`
- `deploy`
- 本地 E2E 测试通过后自动触发(不需要确认)
## 前置条件
- 工作目录:`<project>\packages\meta3d-platform-publish`
- 部署到腾讯云 SCF(服务端)或 CloudBase 静态托管(前端)
- 生产 URL:
- room1: `wss://<appid>-<room1>.ap-shanghai.tencentscf.com?room-id=1`
- room2: `wss://<appid>-<room2>.ap-shanghai.tencentscf.com?room-id=2`
- match: `https://<appid>-<match>.ap-shanghai.tencentscf.com`
## 🔴 规则
### 规则1:不要问部署什么服务
- **从改动文件判断受影响的服务**,不询问兄弟
判断逻辑:
| 改动的目录 | 必须部署的服务 |
|-----------|---------------|
| `packages/room-service/` | room1 + room2(两个 SCF 函数都跑同一份代码) |
| `packages/match-service/` | match1 |
| `packages/frontend/` | frontend(CloudBase 静态托管) |
| `packages/logic/` | room1 + room2 + match1(所有服务端) |
| 只改 `packages/room-service/` | room1 + room2 |
| 同时改 `room-service` + `frontend` | room1 + room2 + frontend |
| 同时改 `match-service` + `frontend` | match1 + frontend |
| 同时改所有 | 全部 |
**只部署受影响的**,不多部署不必要的。
### 🔴 规则2:E2E 通过后自动部署,不问兄弟
本地 E2E 测试通过后,**立即自动调用 deploy 流程**,不再问兄弟「要不要部署」。
- 流程:E2E 全绿 ✅ → 自动进入 Step 3(执行部署)
- 部署完成后发桌面通知告知结果
- 若部署失败 → 报错并问兄弟是否要修
- 此规则优先于 Step 2 的「等兄弟确认」(自动触发时跳过 Step 2)
## 流程
### Step 1: 判断部署目标
> 不询问,自动判断。
### Step 2: 确认部署(仅手动触发时执行)
- 当兄弟明确说「部署」「发布」「deploy」时 → 直接部署不询问
- 当自动触发时(E2E 通过后)→ **跳过此步**
- **双通道通知**:桌面消息 + 飞书通知(≤10字)
### Step 3: 按目标执行
#### 服务端部署(room1 / room2 / match1)
```bash
# room1
yarn deploy_room1 # build_logic → build_room1 → zip_room1 → deploy-scf.js room1
# room2
yarn deploy_room2 # build_logic → build_room2 → zip_room2 → deploy-scf.js room2
# match1
yarn deploy_match1 # build match-service → zip_match → deploy-scf.js match1
deploy-scf.js 自动做:
UpdateFunctionCode APIUpdateFunctionConfiguration 设置并发/超时/内存等yarn publish_multiplayer_demo_static_test
gulp task 自动执行:
mark_test — 标记测试环境update_config — 写入生产配置到 ConfigUtils.tsupdate_multiplayer_config — 设置 Config.ts 为 isProduction:truebuild_multiplayer_test — webpack_origin 构建前端delete_platform_code_static — 删除 CloudBase 旧文件update_platform_code_static — 上传新文件yarn test)验证update_platform_code_static 成功msg * "<30字摘要>"packages/meta3d-platform-publish/gulpfile.jspackages/meta3d-platform-publish/scripts/deploy-scf.jsfrontend/src/logic_layer/MultiplayerUrlConfig.ts
### gts-save-flow
```markdown
---
name: "gts-save-flow"
description: "兄弟说「保存」时触发。审核→BDD→编译→规格→笔记→记忆→项目提交推送→GitHub两段同步"
---
# gts-save-flow — 保存协议(硬性操作规程)
> 触发词:兄弟说「保存」(仅二字)。
> ⚠️ git 命令在 `.openclaw/` 根目录执行(不是 workspace 子目录),明确标注目录的除外。
---
## 流程(8+1 步)
兄弟说「保存」后,严格按以下顺序执行每一步:
### Step 0:改动总结
1. 获取上次保存到现在的改动清单:
- 读取 `笔记/决策记录/.last-save` 获取上次保存的 commit SHA
- `git log --oneline <last-save-sha>..HEAD` 列出所有中间 commit
- `git diff <last-save-sha>..HEAD --stat` 列出文件改动统计
- 生成简洁的 **改动摘要**
2. **问题分析**:
- 是否改了服务端代码 → 是否重启了服务?
- 是否改动了 `node_modules` → 是否经兄弟确认?
3. 在会话中输出改动摘要 + 问题预警,不需要发飞书通知
> ⏸️ 等兄弟确认「继续」才走下一步
### Step 1:快速审核改动
- `git status` 看改动文件
- 快速过一遍改动的合理性(防止意外改动混入)
- 有问题 → 通知兄弟确认
### Step 2:跑 BDD 测试
- 如果 `packages/frontend/test/` 或 `packages/frontend/src/` 有改动:
- `cd packages/frontend && npx jest --config jest.multiplayer.json --silent`
- 如果 `packages/room-service/test/` 或 `packages/room-service/src/` 有改动:
- `cd packages/room-service && npx jest --config jest.json --silent`
- 如果 `packages/match-service/test/` 或 `packages/match-service/src/` 有改动:
- `cd packages/match-service && npx jest --config jest.json --silent`
- 测试失败 → 修到全绿再继续
### Step 2.5:编译检查
- 如果 TypeScript 文件有改动,BDD 全绿后追加 `npx tsc --noEmit`
- ⚠️ jest(ts-jest)只转译不做类型检查,必须靠 `tsc` 暴露
- 有错误 → 修到零错误,回头再跑 BDD 确认
### Step 3:规格同步(Specs 文件)
检查本次改动的业务逻辑与 `.feature` 规格文件是否一致:
1. 查看 `笔记/项目文档/changes/` 下活跃变更目录的 specs 文件
2. 对比 git diff 中改动的业务行为与 specs 描述是否匹配
3. 如果新增了业务场景/状态机转换/消息逻辑但无 specs 覆盖 → 新增场景
4. 如果 specs 与实际实现不一致 → 更新 specs
5. 同步更新对应的 `.steps.ts` 测试步骤文件(如需新步骤定义)
6. 如果需要新的状态类型 → 检查 `state/StateType.ts` 是否有对应类型
> 只在改动涉及业务逻辑时执行此步骤,纯文档/配置改动跳过。
> 更新 specs 后重新跑一遍 BDD(Step 2)确认规格与代码一致。
### Step 4:更新笔记
- 看情况更新 `笔记/` 中对应目录:
- 架构级/决策 → `项目文档/` + `决策记录/`
- 重构/功能实现 → `方案/` + `代码笔记/`
- 日常调试 → `讨论记录/`
### Step 5:更新持久记忆
- 更新 `workspace/memory/` 对应日期的文件
- 如果 `MEMORY.md` 中的配置/规则/教训需要更新 → 同时更新
### Step 6:GitHub 同步(三段提交)
> 📣 push 步骤可能需翻墙,如果失败通知兄弟手动推。
#### Part 0:提交并推送 GTS-Play 项目代码(在项目根目录执行)
```powershell
Set-Location <project>
git add -A
git commit -m "feat|fix|refactor: <改动摘要>"
git push origin dev
git status --short 确保没有意外文件混入webpack.log、截图 PNG、node_modules 等已 gitignore 的不应被包含⚠️ 顺序不可错:先写 .last-save,再 git add,确保包含在 commit 中。
Set-Location <openclaw-home>
# 1. 获取当前 HEAD SHA
$SHA = git rev-parse HEAD
# 2. 先写入 .last-save(路径:workspace/笔记/决策记录/.last-save)
Set-Content -Path workspace/笔记/决策记录/.last-save -Value $SHA -NoNewline
# 3. 再 stage(此时 .last-save 已在工作区)
git add -A
# 4. 提交
git commit -m "save: <日期> <改动摘要>"
Set-Location <openclaw-home>
git push origin main
如果 push 失败(网络/翻墙问题)→ 通知兄弟手动推。
.last-save 留在本地(Part 1).openclaw push 到 GitHub(Part 2).last-save 再 git add -A,否则 .last-save 不会被包含在保存提交中workspace/笔记/决策记录/.last-save 文件git add -A 之前写入git tag 或 git stash 记录 last-save,只用 .last-save 文本文件
### opencode-schedule
```markdown
---
name: "opencode-schedule"
description: "OpenCode 调度方式:写 .opencode-brief.md → type pipe → opencode run --attach --no-replay"
---
# opencode-schedule — OpenCode 调度协议
> 所有调度 OpenCode 的 skill 统一引用本协议。
> 不可单独使用,只能被 gts-dev-workflow / gts-dev-fix / gts-dev-feat / gts-dev-refactor / gts-code-review / gts-analysis 等 skill 引用。
## 调度方式(标准模板)
### 1️⃣ 写 brief 文件
```markdown
**文件路径:** `<projectDir>/.opencode-brief.md`
**内容要求:**
- 自动在开头注入 `笔记/项目文档/project-context.md` 的内容(bot 拼接,OpenCode 不自己读)
- 包含方案内容(如有)
- 包含 Delta Specs(如有)
- 包含 TDD 模板(先写测试、再实现)
- 包含集成测试纪律(🔴🔴🔴 先让测试因 bug 真实失败,禁止 mock 函数替代)
- 末尾写「不需要代码审核,代码审核是单独步骤」
# 简单修复 / 常规功能 / 重构 / Verify — Flash
exec(
command="cd <projectDir> && type .opencode-brief.md | opencode run -m opencode-go/deepseek-v4-flash --dir . --attach http://localhost:4096 --no-replay",
background=true,
timeout=0
)
# 方案 / 架构 / 复杂bug根因分析 — Pro + max
exec(
command="cd <projectDir> && type .opencode-brief.md | opencode run -m opencode-go/deepseek-v4-pro --variant max --dir . --attach http://localhost:4096 --no-replay",
background=true,
timeout=0
)
# 纯方案(plan agent,禁止改代码)
exec(
command="cd <projectDir> && type .opencode-brief.md | opencode run --agent plan -m opencode-go/deepseek-v4-pro --variant max --dir . --attach http://localhost:4096 --no-replay",
background=true,
timeout=0
)
| 参数 | 说明 |
|---|---|
type .opencode-brief.md | |
stdin pipe 传入 brief(PS 不支持 < 重定向) |
-m opencode-go/deepseek-v4-* |
模型名必须带 provider 前缀 opencode-go/ |
--variant max |
Pro 专用,最大 reasoning |
--agent plan |
Pro 专用,plan agent 模式(物理禁止改代码) |
--dir . |
工作目录 |
--attach http://localhost:4096 |
连接到已有 web UI 查看进度 |
--no-replay |
不需要回放 |
调度 OpenCode 后,第一件事是立即开始 poll 循环,不是等兄弟发消息再看。
核心原则:不 yield 等兄弟消息。在同一回合内连续 poll,直到完成或达到工具调用上限。
Step 1: dispatch OpenCode (background=true)
Step 2: process(action=list) 确认启动,拿到 sessionId
→ 找到 "gentle-haven",状态为 "running"
Step 3: 同一回合内连续 poll 循环:
pollCount = 0
WHILE pollCount < 40:
process(action=poll, sessionId=gentle-haven, timeout=30000)
→ 等 30 秒
→ 如果 completed:break,进 Step 4
→ 如果仍 running:
pollCount += 1
每 10 次输出一次进度
(如「OpenCode 还在跑,已等 X 分钟」)
→ 继续下一轮 poll(不 yield,不等用户消息)
IF pollCount >= 40 仍未完成(超过 20 分钟):
输出「任务超过 20 分钟,设置 cron 继续监控」
→ 设置 cron job 每 30s 自动醒来检查
→ YIELD 结束当前回合
后续由 cron 自动唤醒,不再等兄弟消息
Step 4: 任务完成 → 拉完整日志
process(action=log, sessionId=<sessionId>)
Step 5: 分析结果 → 汇报给兄弟
(按 MEMORY.md → 先汇报再继续 规则)
关键规则:
只有耗时超过 20 分钟的任务才用 cron+yield 兜底。绝大部分任务在这个时间前完成。
对照 MEMORY.md 的 token 优化规则:
tool-loop-yield:单回合 >30 轮 tool call 时主动输出进度。这里每 10 轮输出一次,符合规则spawn-subagent:超过 20 分钟的复杂任务可以考虑 spawn 子 session 独立监控exec(background=true) + stdin pipe,禁止 sessions_spawn.opencode-brief.md,再用 type 管道传timeout=0 不限时 — OpenCode 做复杂改动跑 15-30 分钟很正常| 任务类型 | 模型 | 额外参数 |
|---|---|---|
| 简单修复 / 常规实现 / 重构 | Flash | 无 |
| Verify(场景覆盖检查) | Flash | 无 |
| 代码审核 | Pro + max | --variant max |
| 方案 / 架构设计 | Pro + max, plan agent | --agent plan --variant max |
| 复杂bug根因分析 | Pro + max | --variant max |
| 兄弟指定模型 | 按兄弟说的 | 不判断 |
---
下期讲 **P27:前端性能优化(含 AI 素材管线)**——SoA、帧管理、MMD+FBX、AI 生成 3D。
**下一篇:[Vibe Coding 多人游戏(二十七)—— 前端性能优化](https://www.cnblogs.com/chaogex/p/21195307)**