Documentation
¶
Overview ¶
discover.go:运行时发现本机已安装的 harness + 解析本地版本 + 查上游最新版本。
Probe 是注入点(§5.1 接口注入 mock):生产用 defaultProbe(exec.LookPath + 真跑命令), 单测注入 fakeProbe(假二进制 + 固定版本串),不真起子进程。
Discover 不写包级状态(纯函数):调用方(chat service)负责把结果缓存/合并。 这样测试确定性高(同输入 → 同输出),并发安全。
Package harness 提供受支持的 ACP harness 注册表与运行时发现/版本检测/升级管理。 monkey-deck 是纯 ACP client(§1.1):harness 是 peer,我们 spawn 它的 stdio ACP server。 目前已知 harness:omp(默认)/ opencode。
三层概念(分层以避免硬编码,§5.3 KISS):
- Supported(var):注册表静态默认(ID/Name/Command/Icon 四段),供 Command/Normalize/进程回收/ 前端取图标用,始终全量、顺序稳定(DefaultID 在首位)。这部分不变,保持现有契约。
- Discovered(func):运行时发现结果 —— 在 Supported 基础上补 Path/Installed/InstalledVersion/ LatestVersion/UpgradeAvailable,供前端 harness 管理面板展示「装了没 / 是否最新 / 能否升级」。
- Registry(per-Spec 配置):每个已知 harness 的发现参数(BinaryName/VersionArgs)+ 可选的 ReleaseSource(查上游最新版本)+ 可选的 Upgrader(触发升级)。Registry 是 Discovered 的输入。
各 harness 的 ACP 实现差异仍在此包抹平(§2.1)。
Package harness 提供受支持的 ACP harness 注册表与运行时发现/版本检测/升级管理。 本文件(known.go)承载一个「已知 agent 目录」(KnownCatalog,ACP 可用性由 ACPCommand 表达),与 Supported 注册表 (omp/opencode,§1.x 默认 harness 契约)严格分离:KnownCatalog 只读、不参与进程回收、 不进 SQLite、不 spawn,唯一用途是「按启动命令关键词匹配 → 自动选 harness」(Add Harness 弹窗)。
registry.go:已知 harness 的发现/版本/升级配置(每 harness 一条 Spec)。
Spec 是「静态元数据 + 行为接口」的组合:发现参数(BinaryName/VersionArgs/ExtraDirs) + 可选 ReleaseSource(查上游最新版本)+ 可选 Upgrader(触发升级)。 Registry 是 Discovered 的输入,把「我们认识哪些 harness、各自怎么找/怎么升」收敛到一处。
不硬编码可执行文件路径:实际路径由 Discover 在运行时经 PATH + ExtraDirs 解析得到(§3.2 进程回收 harness 无关化的同源思想:此处也对 harness 安装方式不作假设)。
委派优先原则(§5.3 外部事实先验证):harness 自己最清楚发布渠道(npm/brew/curl/自建 CDN), 我们替它操心会做不全。因此 Source/Upgrader 优先委派给 harness 自带的 update/upgrade 子命令, 仅当 harness 无此能力时才回退到外部源(如 GitHubSource)。
release.go:上游发布源 —— 查「最新版本」。
ReleaseSource 是接口(§5.3 成熟库优先 + 接口注入):生产用 GitHubSource 打 GitHub API, 单测注入 mock(返回固定 Release),不真打网络。
upgrade.go:升级 harness 到最新版本。
Upgrader 是接口(同 ReleaseSource 思路):生产用 CommandUpgrader 委托外部安装脚本, 单测注入 mock(不真跑命令)。
升级策略选择(§3.5 「外部事实是设计前提时先验证」):
- opencode/npm/bun 类 harness 的安装状态由外部包管理器(npm/bun/curl-install)持有, 本应用直接覆写可执行文件会与包管理器冲突(版本回写、权限、卸载残留)。故默认策略是 **委托**:CommandUpgrader 跑 harness 官方安装脚本/命令,由其自身幂等地升级到最新。
- 直接下载 release asset 到约定目录的 AssetUpgrader 留作后续按需实现(范围:本次不做, 避免与包管理器打架)。
user.go:用户自添加 harness 的内存合并视图 + 校验。
静态 Supported/Registry(omp/opencode)写死在源码里,用户要加新 harness(junie/jcode/goose/ kimi 等)只能改代码。本文件提供「用户 harness」机制:service 层从 SQLite(store.user_harnesses 表,迁移 0012)加载用户 harness 元数据,灌进本包的内存合并视图(SetUserHarnesses), 让 Discover/Command/Normalize/进程回收 都能识别它们(§5.3 复用,不另起注册体系)。
设计要点:
- 用户 harness 也是 ACP peer(§1.2),AddHarness 只记元数据,spawn/probe 走现有 ACP 路径。
- 用户 harness 不查上游、不升级(无 Source/Upgrader):只做 spawn + 本地版本检测 + 能力探测。
- 合并只在内存(不改静态 Supported/Registry 源码);去重 by ID,静态优先,用户追加在后。
- 持久化走 SQLite(store 层,§2.1 store 是 SQL 唯一入口),本包不直接碰 DB —— 保持 store-free, 由 service 层(chat)在启动 / 增删时调 SetUserHarnesses 灌入。
Index ¶
- Constants
- Variables
- func Command(id string) string
- func Commands() []string
- func ExtractVersionForTest(output string) string
- func IsBuiltin(id string) bool
- func Normalize(id string) string
- func SetProbe(p Probe)
- func SetProbeForTest(p Probe) (restore func())
- func SetUserHarnesses(u []UserHarness)
- func SwapRegistryForTest(next []Spec) (restore func())
- func Upgrade(ctx context.Context, id string) error
- type CommandSource
- type CommandUpgrader
- type GitHubSource
- type Harness
- type KnownHarness
- type Probe
- type Release
- type ReleaseSource
- type Spec
- type Upgrader
- type UserHarness
Constants ¶
const DefaultID = "omp"
DefaultID 默认 harness(omp)。
const SourceCatalog = "catalog"
SourceCatalog marks a Harness entry discovered from KnownCatalog via PATH lookup (#187). Such entries are selectable but inert: no default, no upgrade chain, no capability probe; the first session created with one materializes a real user harness row (chat side).
Variables ¶
var ErrUpgraderNotConfigured = fmt.Errorf("harness upgrade: no upgrader configured for this harness")
ErrUpgraderNotConfigured 该 harness 未配置 Upgrader(Registry 里 Upgrader=nil)。 调用方据此给前端「暂不支持升级」的提示,而非把它当普通错误。
var ErrUserCommandEmpty = errors.New("harness command must not be empty")
ErrUserCommandEmpty 用户 harness 命令为空(AddHarness 唯一的结构性硬错;name 可空、id 由命令派生)。
var KnownCatalog []KnownHarness
KnownCatalog 已知 harness 目录(README 列出的非内置 ACP agent,顺序稳定)。
var Registry = []Spec{ { ID: "opencode", BinaryName: "opencode", Source: &GitHubSource{Repo: "sst/opencode"}, Upgrader: CommandUpgrader{Cmd: []string{"opencode", "upgrade"}}, }, { ID: "omp", BinaryName: "omp", Source: &CommandSource{ Cmd: []string{"omp", "update", "--check"}, Pattern: regexp.MustCompile(`New version available:\s*(\S+)`), }, Upgrader: CommandUpgrader{Cmd: []string{"omp", "update"}}, }, }
Registry 已知 harness 的 Spec 列表,顺序与 Supported 对齐(DefaultID 在首位)。
当前配置:
- opencode:无纯 check 命令(opencode upgrade 只装不查)→ Source 继续走 GitHub Releases; Upgrader 委派给 `opencode upgrade`(它自带 --method 选 curl/npm/bun/brew/...,按用户原安装 方式升级,避免我们写死 curl 与 npm 全局副本打架)。官方文档 https://opencode.ai/docs。
- omp:自带 `omp update --check`(check-only,输出 "New version available: <ver>")→ Source 委派, Pattern 锚定关键词提取(无匹配 = 已是最新 → Latest 空 → 前端显示「已是最新」); Upgrader 委派给 `omp update`(幂等,与 omp 自身升级逻辑一致)。
var Supported = []Harness{
{ID: "omp", Name: "Oh My Pi", Command: "omp acp", Icon: "assets/harness-icons/omp.svg"},
{ID: "opencode", Name: "OpenCode", Command: "opencode acp", Icon: "assets/harness-icons/opencode.svg"},
}
Supported 受支持 harness 的静态注册表(前端选择器 + 进程回收 + Command/Normalize 用)。 第一项为默认 harness。始终全量、顺序稳定;不掺运行时数据(运行时数据走 Discovered)。
Icon 指向 assets/harness-icons/ 下的官方图标资源路径(单一事实源:文件名 = ID, 扩展名随源项目原图格式——svg 或 png,见 assets/harness-icons/README.md)。前端据此取图, 未知 harness 的 Icon 为空时由前端走 lucide Bot 兜底。
Functions ¶
func Command ¶
Command 返回 harness id 对应的 stdio ACP 启动命令;未知 id 回退到默认 harness。 在 effectiveSupported 上判定(含用户 harness),用户 harness 的 Command 由用户在 AddHarness 时填。
func Commands ¶
func Commands() []string
Commands 返回所有受支持 harness(静态 + 用户)的 stdio ACP 启动命令(如 ["omp acp","opencode acp"])。 供进程回收层识别本应用派生的 harness(§3.2):启动 + AddHarness 时注入 acp.SetHarnessCommands, 使回收层也认得用户加的 harness(回收 harness 无关化,§3.2)。
func ExtractVersionForTest ¶
ExtractVersionForTest 暴露 extractVersion 给外部测试包用(同 defaultProbe 的解析行为)。
func IsBuiltin ¶
IsBuiltin 判断 id 是否内置 harness(写死在 Supported,如 omp/opencode)。 编辑 / 删除只对用户自添加的 harness 开放(内置不可改);前端据此决定编辑按钮是否出现。
func Normalize ¶
Normalize 把 harness id 归一化:空或未知回退到默认(omp)。 在 effectiveSupported(静态 + 用户 harness 合并视图)上判定 —— 用户加的 harness 也算「已知」, 不被误判回退到默认(否则用户 session 的 harness 会丢)。
func SetProbeForTest ¶
func SetProbeForTest(p Probe) (restore func())
SetProbeForTest 替换全局 Probe 并返回还原函数(测试用 defer 调用)。 用 atomic-free 风格 —— 测试 setup/teardown 串行调用,不会与生产并发。
func SetUserHarnesses ¶
func SetUserHarnesses(u []UserHarness)
SetUserHarnesses 替换内存里的用户 harness 列表(启动加载 + AddHarness 调)。 传 nil 清空。静态 Supported/Registry 不受影响。
func SwapRegistryForTest ¶
func SwapRegistryForTest(next []Spec) (restore func())
SwapRegistryForTest 替换全局 Registry 并返回还原函数(测试用 defer 调用)。 测试改 Registry 来注入 stub Source/Upgrader,免污染其它测试。
Types ¶
type CommandSource ¶
type CommandSource struct {
Cmd []string // [name, args...] 形如 {"omp","update","--check"}
Pattern *regexp.Regexp // 可选:单 capture group 提取最新版本号;空 = 回退 extractVersion
}
CommandSource 跑一条外部命令查 harness 最新版本(委派给 harness 自己的 update --check 之类命令)。
为什么优先委派(§5.3 外部事实先验证 + §5.3 成熟库优先):harness 自己最清楚发布渠道 (npm/brew/curl/自建 CDN 等),我们替它操心会做不全 —— opencode 自带 `opencode upgrade --method npm|bun|brew|curl|...`,omp 自带 `omp update --check`(原生 check-only)。 绕开它们手搓 GitHub API 会与包管理器打架(写死 curl 在用户 npm 全局装的 opencode 旁再装一份) 或干脆漏接(omp 之前 Source=nil,永远查不到最新版本)。
解析策略(§5.3 找不变量,禁用「输出第几行」启发式):
- Pattern 非 nil:用其**单 capture group** 锚定提取(如 `New version available:\s*(\S+)`)。 协议稳定标识是关键词本身,与输出顺序、stderr 混入(oclif perf 日志)无关。
- Pattern nil:回退 extractVersion(取首行首个含数字 token,与本地版本同形),向后兼容简单命令。
「已是最新」时 omp 输出无 "New version" 行,Pattern 不匹配 → 返 error → Discover 把 LatestVersion 留空 → 前端显示「已是最新」徽章(自然自洽)。
type CommandUpgrader ¶
type CommandUpgrader struct {
Cmd []string // [name, args...] 形如 {"bash","-c","..."}
}
CommandUpgrader 跑一条外部命令来升级 harness(委托给官方安装脚本/包管理器)。 命令输出直透到 stderr/ stdout(供诊断),不捕获到内存(避免大日志撑爆)。
例:opencode 官方安装脚本 → Cmd: []string{"bash","-c","curl -fsSL https://opencode.ai/install | bash"}。
type GitHubSource ¶
type GitHubSource struct {
Repo string // "owner/repo",如 "sst/opencode"
}
GitHubSource 从 GitHub Releases(/releases/latest)查最新版本。
用 v3 REST API(免鉴权有 60/小时/IP 限额,桌面应用够用)。失败不致命: Discovered 会把空 LatestVersion 视为「查不到」,前端只显示本地版本。
type Harness ¶
type Harness struct {
ID string `json:"id"` // 标识(omp/opencode),存进 session.harness
Name string `json:"name"` // 显示名
Command string `json:"command"` // stdio ACP 启动命令(规范形,如 "omp acp")
Icon string `json:"icon"` // 官方图标资源路径(如 "assets/harness-icons/omp.svg");空 = 无 / 走兜底
UserDefined bool `json:"userDefined"` // 用户自添加(可改名/改命令/删除);内置为 false
// Source marks entry provenance (#187). Empty = a full-lifecycle member
// (static Supported or user harness). SourceCatalog = a KnownCatalog PATH
// hit: "available" only — never the default, never in the upgrade chain
// (no Spec/Source), excluded from capability deep-probing (chat side).
Source string `json:"source,omitempty"`
// NeedsAdapter marks a SourceCatalog hit whose catalog entry has no verified
// ACP entry command (#196): the binary is on PATH but cannot be spawned as an
// ACP peer. The UI grays such entries out ("needs an ACP adapter") and makes
// them non-selectable. Always false for non-catalog entries.
NeedsAdapter bool `json:"needsAdapter,omitempty"`
// 运行时(发现 + 版本检测填充)。Supported 静态默认里这些为零值。
Path string `json:"path,omitempty"` // 可执行文件绝对路径(空 = 未发现)
Installed bool `json:"installed"` // 本地是否已安装(能 LookPath 到)
InstalledVersion string `json:"installedVersion,omitempty"` // `<bin> --version` 解析版本(空 = 未装/解析失败)
LatestVersion string `json:"latestVersion,omitempty"` // 上游 release 最新版本(空 = 未查/无源)
UpgradeAvailable bool `json:"upgradeAvailable"` // InstalledVersion < LatestVersion
UpgradeError string `json:"upgradeError,omitempty"` // 上次升级报错(前端展示;空 = 无)
}
Harness 一个受支持的 ACP harness。
字段分两组:
- 静态(Supported 注册表填充):ID/Name/Command/Icon,始终非空(ID/Name/Command;Icon 空表示无官方图标)。
- 运行时(Discovered 填充):Path/Installed/InstalledVersion/LatestVersion/UpgradeAvailable/ UpgradeError,在静态基础上补充本地安装状态与上游版本信息。
func Discover ¶
Discover 在本机扫 Registry 里的每个 Spec,返回运行时 Harness 列表(顺序与 Registry 对齐)。
行为:
- 静态元数据(ID/Name/Command)从 effectiveSupported(静态 Supported + 用户 harness 合并视图)复制 (单一事实源:Supported 是 ID/Name/Command 的真相,用户 harness 追加在后)。
- Path/Installed/InstalledVersion 经 Probe(默认 exec.LookPath + 真跑版本命令)得到。
- LatestVersion 经 Spec.Source(可空)异步查;无 Source 或失败 → 空 + 不报错(降级)。
- UpgradeAvailable = Installed 且 LatestVersion 非空 且 compareVersions(Installed, Latest) < 0。
- 阶段 4 追加 KnownCatalog PATH 命中项(#187,Source=catalog 标记):仅「可用」, 不设默认、不进升级链、不进能力深探;与既有条目撞 id 时已有条目优先,目录条目跳过。
Discover 不写包级状态(纯函数):用户 harness 经 SetUserHarnesses 注入,Discover 只读合并视图。 LatestVersion 的网络查询由 ctx 控制超时/取消(默认由调用方包)。 整体阻塞 ≤ max(LookPath/Version 各 Spec 串行,Source 各 Spec 并行)。
type KnownHarness ¶
type KnownHarness struct {
ID string `json:"id"`
Name string `json:"name"`
BinaryName string `json:"binaryName"` // canonical executable name for PATH lookup (= seed alias)
Keywords []string `json:"keywords"`
// ACPCommand is the verified ACP entry command; "" = no ACP channel (gray state).
ACPCommand string `json:"acpCommand,omitempty"`
}
KnownHarness is a lightweight catalog entry for a known agent harness. Two uses:
- command-keyword matching for auto-selection (MatchKnownHarness, Add Harness dialog);
- PATH auto-discovery (#187): Discover LookPaths BinaryName; a hit yields a harness entry (Source=catalog marker).
ACPCommand expresses ACP usability (#196): the verified stdio ACP entry command, which may differ from both the discovery key (codex-cli → "codex-acp") and the "<bin> acp" default form (codebuddy → "codebuddy --acp"). Empty = no known ACP channel: the entry is still discovered and listed, but the UI grays it out as "needs an ACP adapter" and it is not selectable. Display identity (ID/Name/icon) always stays on the discovery-key side.
The frontend HarnessIcon resolves icons from ID alone (/harness-icons/<id>.<ext>), so this struct carries no icon path field (icon files live in assets/harness-icons/<id>.<ext>).
func KnownHarnessByID ¶
func KnownHarnessByID(id string) *KnownHarness
KnownHarnessByID returns the catalog entry with the given id, or nil. Linear scan is fine: the catalog is ~50 entries and lookups are rare (session creation / AddHarness collision checks).
func MatchKnownHarness ¶
func MatchKnownHarness(command string) *KnownHarness
MatchKnownHarness 按启动命令做关键词匹配,返回最匹配的已知 harness;无命中返回 nil。
匹配规则(§5.3 找不变量,不堆 if):命令转小写;对每个已知 harness,任一 keyword 命中即候选, 取 keyword 最长者(更具体的 harness 优先,如 "github-copilot" 优先于 "pi")。短 keyword (<4 字符,如 "pi"/"amp")须整词命中命令 token,避免 "pi"⊂"shipping" 这类误中。
前端「添加 harness」弹窗据返回值自动选 harness + 预填 Name(用户可覆盖)。
type Probe ¶
type Probe interface {
// LookPath 找二进制绝对路径;找不到返 ("", error)。
// bin 是不含扩展名的规范名(BinaryName);实现按平台决定是否加 .exe。
LookPath(bin string) (string, error)
// Version 跑版本命令并解析出纯版本(如 "1.2.3");失败返 ("", error)。
Version(ctx context.Context, path string, args []string) (string, error)
}
Probe 把可执行文件相关的「环境相关操作」抽象成接口,供测试注入。
实现要点:
- LookPath: 在 PATH(或 fakeProbe 的伪 PATH)里找二进制。
- Version: 跑 `<bin> <args> --version` 等价命令,返回解析后的纯版本串。
type Release ¶
type Release struct {
Version string // 不带前导 v(与本地 InstalledVersion 同形,便于比较)
}
Release 一个上游发布版本的最小描述。
type ReleaseSource ¶
ReleaseSource 能查「某 harness 的最新发布版本」。 实现须是并发安全的(LatestVersion 会被多个 harness 并行查)。
type Spec ¶
type Spec struct {
ID string // 与 Harness.ID 对齐(omp/opencode)
BinaryName string // 可执行文件名(不含扩展;Windows 上 Discover 自动加 .exe)
VersionArgs []string // 拉本地版本的参数(如 ["--version"] / ["version"]);空 = 用默认 ["--version"]
ExtraDirs []string // 额外发现目录(绝对路径;如 ~/.bun/bin 等用户级安装位);空 = 仅 PATH
// Source 查上游最新版本(可空 = 无已知发布源 → LatestVersion 永远空)。
Source ReleaseSource
// Upgrader 触发升级(可空 = 不支持升级 → Upgrade 返 ErrUpgraderNotConfigured)。
Upgrader Upgrader
}
Spec 单个已知 harness 的发现 + 版本 + 升级配置。
type UserHarness ¶
type UserHarness struct {
ID string `json:"id"`
Name string `json:"name"`
Command string `json:"command"`
Icon string `json:"icon,omitempty"` // 空 = 前端兜底(lucide Bot)
}
UserHarness 用户自添加 harness 的内存结构(只存静态元数据四段)。 运行时数据(安装路径/版本/升级)由 Discover 在合并后的视图上统一填,不在此存。 持久化落 store.UserHarness(多一个 created_at);service 层在加载时做转换。
func UserHarnesses ¶
func UserHarnesses() []UserHarness
UserHarnesses 返回当前内存里的用户 harness 列表快照(可能为空切片,不返回 nil)。