harness

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 11, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
const DefaultID = "omp"

DefaultID 默认 harness(omp)。

View Source
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

View Source
var ErrUpgraderNotConfigured = fmt.Errorf("harness upgrade: no upgrader configured for this harness")

ErrUpgraderNotConfigured 该 harness 未配置 Upgrader(Registry 里 Upgrader=nil)。 调用方据此给前端「暂不支持升级」的提示,而非把它当普通错误。

View Source
var ErrUserCommandEmpty = errors.New("harness command must not be empty")

ErrUserCommandEmpty 用户 harness 命令为空(AddHarness 唯一的结构性硬错;name 可空、id 由命令派生)。

View Source
var KnownCatalog []KnownHarness

KnownCatalog 已知 harness 目录(README 列出的非内置 ACP agent,顺序稳定)。

View Source
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 自身升级逻辑一致)。
View Source
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

func Command(id string) string

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

func ExtractVersionForTest(output string) string

ExtractVersionForTest 暴露 extractVersion 给外部测试包用(同 defaultProbe 的解析行为)。

func IsBuiltin

func IsBuiltin(id string) bool

IsBuiltin 判断 id 是否内置 harness(写死在 Supported,如 omp/opencode)。 编辑 / 删除只对用户自添加的 harness 开放(内置不可改);前端据此决定编辑按钮是否出现。

func Normalize

func Normalize(id string) string

Normalize 把 harness id 归一化:空或未知回退到默认(omp)。 在 effectiveSupported(静态 + 用户 harness 合并视图)上判定 —— 用户加的 harness 也算「已知」, 不被误判回退到默认(否则用户 session 的 harness 会丢)。

func SetProbe

func SetProbe(p Probe)

SetProbe 替换全局 Probe(仅测试用,生产禁用)。

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,免污染其它测试。

func Upgrade

func Upgrade(ctx context.Context, id string) error

Upgrade 对 harness id 触发升级;id 未配置 Upgrader 返 ErrUpgraderNotConfigured。 升级完成后不会自动重查版本 —— 调用方应再调 Discover 刷新缓存。

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 留空 → 前端显示「已是最新」徽章(自然自洽)。

func (CommandSource) Latest

func (c CommandSource) Latest(ctx context.Context) (Release, error)

Latest 跑配置的命令,按 Pattern(或 extractVersion 回退)解析输出里的最新版本号。 命令非 0 退出、或解析不到版本号,都返 error(不假装成功)。

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"}。

func (CommandUpgrader) Upgrade

func (c CommandUpgrader) Upgrade(ctx context.Context) error

Upgrade 跑配置好的命令;命令非 0 退出则返 wrapped error。

type GitHubSource

type GitHubSource struct {
	Repo string // "owner/repo",如 "sst/opencode"
}

GitHubSource 从 GitHub Releases(/releases/latest)查最新版本。

用 v3 REST API(免鉴权有 60/小时/IP 限额,桌面应用够用)。失败不致命: Discovered 会把空 LatestVersion 视为「查不到」,前端只显示本地版本。

func (*GitHubSource) Latest

func (g *GitHubSource) Latest(ctx context.Context) (Release, error)

Latest 查 GitHub 最新 release。网络/解析失败返 error;Discovered 据此降级。

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

func Discover(ctx context.Context) []Harness

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:

  1. command-keyword matching for auto-selection (MatchKnownHarness, Add Harness dialog);
  2. 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

type ReleaseSource interface {
	Latest(ctx context.Context) (Release, error)
}

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 Upgrader

type Upgrader interface {
	Upgrade(ctx context.Context) error
}

Upgrader 把指定 harness 升级到最新版本。 实现应阻塞到升级流程结束(成功/失败),由调用方包 ctx 控制超时/取消。

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)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL