Supacode自定义脚本完全教程: 为仓库配置自动化命令, Agent运行状态实时提醒

【免费下载链接】supacodeworktree coding agents command center.项目地址: https://gitcode.com/gh_mirrors/su/supacode

Supacode 是一款 macOS 原生的 worktree 编码 Agent 指挥中心，每个任务独享一个 git worktree 和真实终端。它的自定义脚本功能让你为每个仓库配置自动化命令——一键运行、测试、部署，配合 Agent 运行状态实时提醒，在 Claude、Codex 等编码助手需要你介入的瞬间立即收到通知。本文带你从零配好脚本、跑通自动化，并掌握 CLI 与深链两种触发方式。

🚀 Supacode 自定义脚本是什么

Supacode 把"仓库常用命令"抽象成带图标和颜色的命名脚本，运行时会开一个独立标签页执行，并同步出现在工具栏 Script 菜单、命令面板（Command Palette）和深链中。脚本分两大类：

① 用户脚本（按需运行）——共 6 种类型，前 5 种自带固定图标与配色：

类型与默认样式定义在 ScriptKind.swift，单个脚本的名称、命令、图标、颜色则存储在 ScriptDefinition.swift。以 Supacode 仓库自身的配置为例，它定义了 Run / Test / Lint / Format 四个脚本，见 supacode.json。

② 生命周期脚本（自动触发）——挂在 worktree 的"生老病死"节点上：

这些字段都保存在仓库级设置 RepositorySettings.swift 中，编辑界面见 RepositoryScriptsSettingsView.swift。

⚙️ 最快配置方法：3 步配好仓库自动化命令

第 1 步：打开仓库脚本设置。选中侧边栏的仓库，进入设置 → Scripts 标签页（Setup / Archive / Delete / Open File 四个生命周期脚本在此配置，仅 git 仓库可见前两项）。

第 2 步：点击右上角+添加脚本。下拉菜单会列出你还没建过的类型（Run、Test、Deploy、Lint、Format 每类最多一个，Custom 可建任意多个）。选 Custom 时还能自定义名称和颜色，让工具栏一眼可辨。

第 3 步：填入命令。在命令编辑框输入 shell 命令即可，例如npm start或make test。删除脚本点红色 "Remove Script…" 按钮。

💡 小技巧：第一个Run 类型脚本是"主脚本"——工具栏上的一键运行按钮默认就执行它（见 ScriptDefinition.swift 中的primaryScript）。把最常用的启动命令放这里最顺手。

全局脚本：一次配置，所有仓库共享

在 设置 → 全局 Scripts 页面（GlobalScriptsSettingsView.swift）添加的脚本会出现在每个仓库的工具栏和命令面板里，适合放通用命令（比如打开端口占用检查、提交前格式化）。合并规则是"仓库脚本优先，全局脚本兜底"，同 ID 冲突时以仓库为准。

▶️ 3 种方式运行脚本

方式一：工具栏 Script 菜单。每个脚本带彩色图标，点击即在自己的标签页运行，运行状态实时可见。

方式二：命令面板。按快捷键唤起 Command Palette，模糊搜索脚本名直接执行，全程不离键盘。

方式三：CLI 或深链。在任何 Supacode 终端会话里，supacode命令默认可用（命令清单见 supacode-cli.md）：

supacode worktree script list # 列出当前 worktree 的所有脚本 supacode worktree run # 运行主 Run 脚本 supacode worktree run -c <uuid> # 按 UUID 运行指定脚本 supacode worktree stop -c <uuid> # 停止指定脚本

脚本列表命令的实现位于 WorktreeScriptCommand.swift。在 Supacode 外部（其他脚本、自动化平台）则用深链，完整路由参考 supacode-deeplinks.md：

open "supacode://worktree/<worktree_id>/run"

⚠️ 注意：深链触发的运行/危险操作需要确认，除非在 Developer 设置中允许了 "Allow dangerous actions"。

🔔 Agent 运行状态实时提醒

Supacode 自动检测每个终端里正在运行的编码 Agent（Claude Code、Codex、Copilot、Grok、Kimi 等），侧边栏和 Agent 徽章上会实时显示三种状态：忙碌中（busy）、等待输入（awaiting input）、空闲（idle）。状态识别的接入逻辑见 AgentIntegration.swift，Supacode 会为支持的 Agent 自动安装 hooks，本地和 SSH 远程仓库都有效。

配合通知能力，这套组合拳的体验是：

• Agent需要你回答/确认时，即时收到应用内或系统通知（可选提示音），侧边栏自动把"等你处理"的 worktree 提到顶部；
• 脚本运行结束、Agent 空闲下来时，同样有提示，不必守着终端；
• 多 Agent 并行干活时，用 ⌃1–⌃9 快速跳转到任意 worktree。

💡 实用工作流：Setup Script 负责拉依赖，Agent 在独立 worktree 里改代码，Test 脚本随时一键回归，等你输入时 Agent 状态徽章变黄 + 通知响起——整个循环不用手动盯守。

📝 常见问题

Q：文件夹（非 git 仓库）能用脚本吗？可以。文件夹拥有与仓库相同的标签页、脚本和外观能力，只是 Setup / Archive 两个依赖 worktree 的脚本不可用。

Q：脚本输出去哪看？每个脚本在独立标签页中执行，输出与滚动记录都保留在会话里，关闭 App 重开也不丢（会话由后台守护进程持久化）。

Q：旧配置有runScript字段？新版会自动迁移为 Run 类型脚本；旧客户端仍可通过派生字段读取，双向兼容。

结语

自定义脚本 + 生命周期钩子 + Agent 状态提醒，让 Supacode 从一个"终端窗口管理器"升级为真正的并行开发指挥中心。花 5 分钟配好 4 个脚本，之后每个 worktree 的装环境、跑测试、收通知都会自动就位。

【免费下载链接】supacodeworktree coding agents command center.项目地址: https://gitcode.com/gh_mirrors/su/supacode