acpx

type Agent ¶

type Agent interface {
	// Name agent 标识（claude / codex / opencode / zcode / minimax）。
	Name() string
	// Run 执行一次任务（headless 模式）。
	Run(ctx context.Context, req RunRequest) (*RunResult, error)
	// Capabilities 声明对 RunRequest 控制面字段的支持度。能力声明是接口契约的
	// 一部分（编译期强制，不给实现者"忘记声明"的余地）：Registry.Run 对请求中
	// 声明不支持的非零字段 fail-fast——静默丢弃已证伪（kimi 收到 Sandbox=readonly
	// 实则全自主裸跑，安全语义静默降级不可接受）。
	Capabilities() Capability
}

Agent CLI 编码 agent 统一接口。

type Capability ¶

type Capability struct {
	Model        bool // 响应 Model 覆盖
	Session      bool // 响应 SessionID 续聊
	MaxTurns     bool // 响应 MaxTurns 轮数上限
	AllowedTools bool // 响应 AllowedTools 工具白名单
	Sandbox      bool // 响应 Sandbox 沙箱级别
}

Capability agent 对 RunRequest 控制面字段的支持声明（五字段独立判定）。

type ClaudeCode ¶

type ClaudeCode struct {
	Bin string // 默认 "claude"
	// contains filtered or unexported fields
}

ClaudeCode Claude Code 适配器（headless：`claude -p --output-format stream-json`）。

func NewClaudeCode() *ClaudeCode

func NewZCode() *ClaudeCode

func (c *ClaudeCode) Capabilities() Capability

func (a *ClaudeCode) Name() string

func (c *ClaudeCode) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type Codex ¶

type Codex struct {
	Bin string // 默认 "codex"
}

Codex OpenAI Codex CLI 适配器（`codex exec --json --output-last-message <file>`）。

func NewCodex() *Codex

func (c *Codex) Capabilities() Capability

func (c *Codex) Name() string

func (c *Codex) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type Event ¶

type Event struct {
	Type string // text | thinking | tool_call | tool_result | error | result
	Text string
	Tool string // tool_call/tool_result 的工具名
	Raw  json.RawMessage
}

Event 流式事件。 各适配器转发覆盖（v0.10.10 起错误事件全量转发——此前只转 text，纯错误跑的 transcript 为空、排障断链）：mimo=error/text/result(step_finish)；codex= error/text；claude=text/thinking/tool_call/result(is_error 以 error 型转发)； pi=error(含 abort)/text/assistant 终态(result)；kimi=text；gemini/ opencode 非流式（错误走 Run 返回值，无流式事件）。

type Gemini ¶

type Gemini struct {
	Bin string // 默认 "gemini"
	// contains filtered or unexported fields
}

Gemini Gemini CLI 适配器（google-gemini/gemini-cli；Qwen Code 为其 fork，参数同族）。

协议要点（非交互模式）：

• `gemini -p "<prompt>" --output-format json` 输出单 JSON 对象： {"response":"...","stats":{"models":{"<model>":{"tokens":{"prompt":N,"candidates":N}}}}}
• `-m/--model`；`--approval-mode default|auto_edit|yolo`（沙箱映射）

func NewGemini() *Gemini

func NewQwen() *Gemini

func (g *Gemini) Capabilities() Capability

func (a *Gemini) Name() string

func (g *Gemini) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type GenericAgent ¶

type GenericAgent struct {
	AgentName string   // agent 标识（Name() 返回值）
	Argv      []string // argv 模板
	IsJSON    bool
}

GenericAgent 通用 CLI agent：以显式 argv 模板驱动任意 agent。 模板占位符：{prompt}（原样单参传入，无 shell 注入面）、{model}、{session}。 flag+占位符是**条件单元**：{model}/{session} 缺值时整体移除——连带移除紧邻的 前一个以 "-" 开头的参数（如 ["run","--model","{model}"] 在无 Model 时展开为 ["run"]，绝不产生吞掉后续位置参数的悬空 flag）。 IsJSON=true 时按 {"text","sessionID","tokens":{"input","output"}} 解析输出。

用途：CLI 参数协议未稳定或私有 agent 的快速接入；协议稳定后应收敛为 专用适配器（mcode 于 2026-10-04 收敛为 Mcode，Minimax 预设随之移除）。

func NewDsh() *GenericAgent

func NewGenericAgent(name string, argv []string, isJSON bool) *GenericAgent

func (g *GenericAgent) Capabilities() Capability

func (g *GenericAgent) Name() string

func (g *GenericAgent) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type Kimi ¶

type Kimi struct {
	Bin string // 默认 "kimi"
}

Kimi Kimi Code CLI 适配器（MoonshotAI/kimi-code，参数经本机真实 CLI --help 核实）。

协议要点（非交互模式，headless）：

• `kimi -p "<prompt>"` 非交互执行（本身即全自主；不可与 --auto 组合——真实 CLI 实测报错）
• `--output-format stream-json` 输出 JSONL 消息流：{"role":"assistant","content":"..."}
• `-m/--model NAME` 覆盖模型；`-S/--session ID` 续聊

注：文档站描述的旧版 kimi-cli 用 `--print`；新一代 kimi-code 已改为 `-p` 直跑。

func NewKimi() *Kimi

func (k *Kimi) Capabilities() Capability

func (k *Kimi) Name() string

func (k *Kimi) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type Mcode ¶

type Mcode struct {
	Bin string // 默认 "mcode"
	// contains filtered or unexported fields
}

Mcode MiniMax Code CLI 适配器（`mcode exec <prompt> --output-format json`， 参数与信封经本机真实 CLI 核实）。注册名沿历史键 "minimax"（bin 名为 mcode）。

协议要点（0.6.2 实弹）：

• exec 单 JSON 信封输出（stdout 单行）： {"schemaVersion","type":"exec.result","sessionId":"mvs_...","status": "succeeded","output","model":{...},"usage":{"inputTokens","outputTokens", "cacheReadTokens","totalTokens"},"usageIncomplete"}
• ⚠ 运行期失败 exit code 仍为 0（假模型名实弹核实）——失败识别只能靠信封 status=failed + error{category,message}，本适配器如实上抛并经 EventError 全量转发（不因 exit 0 或有部分文本而当成功——mimo 同纪律）
• `--model provider/model` 覆盖模型；不传用 CLI 缺省（实测 MiniMax-M3.1-Flash-Preview）
• `--session mvs_...` 续聊（实测跨轮记忆成立，sessionId 稳定不变）
• `--max-steps N` 轮数预算（对应 MaxTurns）
• ⚠ 无沙箱可映射：--permission smart 在 headless 下工作区外写也放行 （实测于 $HOME 建文件成功），无"工作区内放行/外禁止"的运行时硬边界—— Capabilities 不声明 Sandbox，工作区硬条款仅剩 prompt 纪律（mimo 同款）
• 非 JSON 输出（版本差异/日志混入）走全文兜底，不崩不误报

func NewMcode() *Mcode

func (m *Mcode) Capabilities() Capability

func (a *Mcode) Name() string

func (m *Mcode) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type Mimo ¶

type Mimo struct {
	Bin string // 默认 "mimo"
	// DefaultModel 请求未指定 Model 时的缺省模型（xiaomi/ 全名）。空 = 尊重
	// 本机 CLI 配置（其缺省模型可能已被服务端下线）。
	DefaultModel string
	// contains filtered or unexported fields
}

Mimo 小米 MiMo Code 适配器（`mimo run --format json`，参数经本机真实 CLI 核实）。

协议要点：

• `mimo run "<prompt>" --format json` 输出 JSONL 事件： {"type":"text","part":{"text":"..."}}" 增量文本 {"type":"step_finish","sessionID":"...","part":{"tokens":{"input","output"},"cost":N}} {"type":"error","error":{"data":{"message":"..."},"message":"..."}}（错误详情在 error.data.message——2026-09 实弹核实；error.message 顶层路径为兼容回退）
• `-m provider/model` 覆盖模型：**须 xiaomi/ 全名前缀**（短名被服务端拒绝； 本机 CLI 缺省模型可能被服务端下线——ultraspeed 前车之鉴，生产装配建议显式 配置 DefaultModel）
• `-s/--session ID` 续聊
• ⚠ 运行期错误 exit code 仍为 0——错误识别只能靠事件流，本适配器对 error 事件如实上抛（不因恰好有部分文本而掩盖），并经 EventError 全量转发

func NewMimo() *Mimo

func (m *Mimo) Capabilities() Capability

func (a *Mimo) Name() string

func (m *Mimo) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type OpenCode ¶

type OpenCode struct {
	Bin string // 默认 "opencode"
}

OpenCode opencode 适配器（`opencode run --json`）。

func NewOpenCode() *OpenCode

func (c *OpenCode) Capabilities() Capability

func (c *OpenCode) Name() string

func (c *OpenCode) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type Pi ¶

type Pi struct {
	Bin string // 默认 "pi"
	// DefaultModel 请求未指定 Model 时的缺省（provider/id 形态）。空 = 尊重
	// 本机 CLI 配置。
	DefaultModel string
	// contains filtered or unexported fields
}

Pi pi-coding-agent 适配器（`pi --mode json -p --no-session`，参数经本机真实 CLI 核实，2026-09-28 实弹采样）。

协议要点：

• `pi --mode json -p "<prompt>"` 输出 JSONL 事件流： {"type":"message_start","message":{"role":...,"provider":...,"model":...}} {"type":"message_update","assistantMessageEvent":{"type":"text_delta",...}} {"type":"message_end","message":{"role":"assistant","content":[{"type": "thinking",...},{"type":"text","text":"..."}],"usage":{"input","output", "totalTokens","cost":{...}},"stopReason":...}} {"type":"turn_end"| "agent_end" | "agent_settled" | "session" | ...} 文本取 assistant message_end 的 "text" 内容块（thinking 块不计入正文）； usage 含 input/output/reasoning 与 cost（多轮 message_end 后者覆盖前者）。
• `-p/--print` 非交互执行；`--no-session` 不落会话（acpx 语义：每次 Run = 独立任务，不在 ~/.pi 留状态）；扩展/技能/AGENTS.md 发现保持本机默认 （编码任务需要这些环境）。
• `--model provider/id[:thinking]` 覆盖模型（支持 provider/id 形态）。
• 中止形态（turn_abort 等）无 assistant message_end：有 exit!=0 时以退出错 误为准；exit=0 且事件流含 abort 类事件时如实报错（不静默空成功）。

func NewPi() *Pi

func (p *Pi) Capabilities() Capability

func (a *Pi) Name() string

func (p *Pi) Run(ctx context.Context, req RunRequest) (*RunResult, error)

type Registry ¶

type Registry struct {

	// OnRun 每次经本 Registry 发起的运行结束后的回调（nil 安全）。
	// 观测入口：接结构化日志/Prometheus/trace 均可，本包不硬依赖任何观测后端。
	OnRun func(RunEvent)
	// contains filtered or unexported fields
}

Registry agent 注册表：名字 → Agent 实例。

func NewRegistry() *Registry

func (r *Registry) AsTool() tool.BaseTool

func (r *Registry) Get(name string) (Agent, bool)

func (r *Registry) Names() []string

func (r *Registry) Register(a Agent)

func (r *Registry) Run(ctx context.Context, name string, req RunRequest) (*RunResult, error)

type RunEvent ¶

type RunEvent struct {
	Agent     string        // agent 名
	Duration  time.Duration // 运行耗时
	Err       error         // 非空 = 运行失败
	TextLen   int           // 产出文本长度（不落内容，防泄露）
	Usage     Usage
	SessionID string
}

RunEvent 一次 agent 运行的观测事件（Registry.OnRun 钩子载荷）。

type RunRequest ¶

type RunRequest struct {
	Prompt  string // 任务描述
	WorkDir string // 工作目录（agent 在此目录下执行）
	Model   string // 模型覆盖（空 = agent 默认）
	// SessionID 续接会话（Claude --resume / opencode --session；Codex 暂不支持续聊）。
	SessionID string
	// MaxTurns 最大 agent 轮数上限（防失控循环；0 = agent 默认）。
	MaxTurns int
	// AllowedTools 工具白名单（claude 族语义："Bash(git:*)" "Read" "Edit"；
	// 空 = agent 默认）。
	AllowedTools []string
	// Sandbox 沙箱级别：readonly | workspace | full（Codex 原生支持；
	// claude 族映射 permission-mode）。
	Sandbox string
	// Env 额外环境变量白名单，两种形态：纯名（"HF_TOKEN"）按名从当前进程
	// 透传；"KEY=VALUE" 字面注入（同名父进程值不透传——显式注入优先，见
	// procx.ChildEnv）。值会进入子进程环境，调用方自负泄漏面。
	Env []string
	// Timeout 单次运行超时（0 = 10 分钟缺省）。
	Timeout time.Duration
	// OnEvent 流式事件回调（nil = 只取最终结果）。
	// 注意：回调在 stdout 读取 goroutine 中同步执行——不得阻塞（拖慢子进程
	// 输出消费），不得 panic（会击穿整个进程）。
	OnEvent func(Event)
}

RunRequest 统一运行请求。

type RunResult ¶

type RunResult struct {
	Text      string // 最终 assistant 文本
	SessionID string // 会话 ID（供续聊）
	Usage     Usage
	Duration  time.Duration
	ExitCode  int
	Raw       []byte // 原始 stdout（调试用）
	// Stderr 子进程 stderr 尾巴（≤400 字节，rune 对齐；空 = 无输出）。成功
	// 解析路径也有值——CLI 的告警/弃用提示走 stderr，transcript 排障需要。
	Stderr string
	// Interrupted 执行被中断（超时/调用方取消/被信号杀死，tools#46）：
	// Text 只是**部分输出**、任务未完成，且返回值同时带非 nil error——
	// kimi 形态（无协议终态事件）下部分文本不得代理终态。nil error 时恒为
	// false；「正常完成但退出码非零」（终态优先路径）不算中断。
	Interrupted bool
}

RunResult 统一运行结果。

type Usage ¶

type Usage struct {
	InputTokens  int
	OutputTokens int
	CostUSD      float64
}

Usage token 用量与成本（agent 输出缺失时为 0）。