Adds optional NATS-based task distribution alongside the existing
SQLite flow. When [nats] is absent from config, zero behaviour change.
New internal/nats package:
- Subject constants matching PRD §2 (archie.task.{bug,feature,default,bootstrap})
- Client: Connect (stream + durable pull consumer), PublishTask
(Nats-Msg-Id dedup), Fetch, DecodeTask
- Tests with embedded NATS server (connect/publish, dedup, subject routing)
Config: NATSConfig{URL, TokenEnv} on Config, commented-out [nats] block
in config.example.toml
Store: ClaimByIssue atomic claim by owner/repo/number for NATS consumer
Daemon: Nats client field, poll() branches to pollNATS/pollSQLite,
Cycle() branches to drainNATS/drainSQLite (NATS fetch then SQLite
ClaimNext fallback for requeued tasks), processNATSTask
(decode → EnqueueIssue → ClaimByIssue → process → Ack)
Scratch: explorer and plan agent outputs from parallel-explore phase
12 KiB
agentexec-protocol
我现在掌握了所有需要的信息。以下是完整的报告。
报告:Archie 核心中的代理执行协议和 Runner 架构
1. Runner 接口
定义位置:/work/apps/archie-core/internal/agentexec/inprocess.go,第 20-22 行
type Runner interface {
Run(ctx context.Context, workspace string, req Request) (Result, error)
}
一个单一方法接口: Run 接受一个上下文、一个工作目录路径(字符串)和一个 Request,返回一个 Result 和一个错误。工作目录路径与请求分开传递,供容器运行器将主机路径映射到内部文件系统。
该接口有两个具体实现:
-
InProcessRunner(/work/apps/archie-core/internal/agentexec/inprocess.go,第 29-33 行) -- 拥有一个*runtime.Runtime、一个*slog.Logger和一个loopFunc字段(默认为agentloop.Run)。它在与archied相同的进程空间中运行代理循环。 -
SubprocessRunner(/work/apps/archie-core/internal/agentexec/subprocess.go,第 17-27 行) -- 拥有Command、Args、Environ、AdditionalEnv、Diagnostics io.Writer和Providers。它将完整的Invocation序列化到 stdin,启动一个archie-agent二进制文件,并从 stdout 解码Response。
2. 线路协议
所有消息类型都定义在 /work/apps/archie-core/internal/agentexec/protocol.go 中。
Invocation (第 139-144 行) -- 被 archie-agent 接受的完整请求:
type Invocation struct {
Version int `json:"version"`
Workspace string `json:"workspace"`
Request Request `json:"request"`
Providers map[string]Provider `json:"providers"`
}
Request (第 59-74 行) -- 代理阶段的有效载荷:
type Request struct {
Version int `json:"version"`
TaskID int64 `json:"task_id"`
Attempt int `json:"attempt"`
Stage string `json:"stage"`
Model string `json:"model"`
Mission string `json:"mission"`
ExtraRules string `json:"extra_rules,omitempty"`
ReadOnly bool `json:"read_only,omitempty"`
Budget Budget `json:"budget"`
Gate Gate `json:"gate"`
Preflight []Command `json:"preflight,omitempty"`
Protection Protection `json:"protection"`
Notes string `json:"notes,omitempty"`
CaptureTools []CaptureTool `json:"capture_tools,omitempty"`
}
Result (第 97-111 行) -- 输出:
type Result struct {
Version int `json:"version"`
TaskID int64 `json:"task_id"`
Attempt int `json:"attempt"`
Stage string `json:"stage"`
Status string `json:"status"`
StopReason string `json:"stop_reason,omitempty"`
Changes []string `json:"changes,omitempty"`
Iterations int `json:"iterations,omitempty"`
TokensUsed int `json:"tokens_used,omitempty"`
Summary string `json:"summary,omitempty"`
Detail string `json:"detail,omitempty"`
AppendedNotes []string `json:"appended_notes,omitempty"`
Captures map[string][]json.RawMessage `json:"captures,omitempty"`
}
Response (第 168-172 行) -- 从 archie-agent 返回的顶层信封:
type Response struct {
Version int `json:"version"`
Result Result `json:"result"`
Error string `json:"error,omitempty"`
}
辅助类型:
Command(第 18-22 行):Name、Argv、ExpectFailureGate(第 25-28 行):Commands、MaxConsecutiveFailuresBudget(第 31-35 行):MaxSteps、MaxTokens、WallClockProtection(第 38-41 行):Suffixes、GlobsCaptureTool(第 45-53 行):Name、Description、Parameters、RequiredFields、NonEmptyStrings、BooleanFields、MaxCallsProvider(第 115-119 行):Class、APIKeyEnv、BaseURL
协议通过 JSON 在 stdin/stdout 上使用。ServeOne (worker.go,第 16-43 行) 解码一个 Invocation,验证它,构建一个 InProcessRunner,运行它,然后将单个 Response 写入 stdout。ServeOne 不会循环——它处理一个调用然后返回。
3. cmd/archied 如何连接 Runner
在 /work/apps/archie-core/cmd/archied/main.go 中,第 109-125 行:
providers := executionProviders(cfg)
llm := agentexec.NewRuntime(providers)
var agentRunner agentexec.Runner
if llm != nil {
switch cfg.Agent.Mode {
case "subprocess":
agentRunner = &agentexec.SubprocessRunner{
Command: cfg.Agent.Command,
Environ: os.Environ(),
AdditionalEnv: cfg.Agent.Env,
Diagnostics: os.Stderr,
Providers: providers,
}
case "inprocess":
agentRunner = agentexec.NewInProcessRunner(llm, log)
}
}
运行器模式由 cfg.Agent.Mode 控制,它来自配置 TOML。有两个 case:
"subprocess":创建一个SubprocessRunner,将完整的环境、一个可执行文件命令(来自cfg.Agent.Command,通常是archie-agent二进制文件的路径)以及提供者映射传递给它。"inprocess":通过NewInProcessRunner(llm, log)创建一个InProcessRunner,其中llm是runtime.NewRuntime(providers)的结果。
然后,agentRunner 被放入 Daemon 结构体 (/work/apps/archie-core/internal/daemon/daemon.go,第 33 行) 作为 Agent agentexec.Runner。守护进程的 process 方法 (第 356-377 行) 将其传递到 TaskContext:
workflow.Run(ctx, wf, &workflow.TaskContext{
Task: task,
Repo: repo,
...
Agent: d.Agent,
...
})
如果 cfg.Agent.Mode 既不是 "subprocess" 也不是 "inprocess",或者如果 llm 是 nil(没有提供者),则 agentRunner 保持为 nil。当 Agent 为 nil 时,AgentStage.Stage() 方法 (agent.go,第 49-50 行) 返回一个合适的错误。
4. TaskContext 和 Agent 字段
定义位置:/work/apps/archie-core/internal/workflow/workflow.go,第 26-57 行。
type TaskContext struct {
Task *store.Task
Repo config.Repo
Cfg config.Config
Forge forge.Forge
Store *store.Store
Trees *worktree.Manager
Agent agentexec.Runner // <-- 第 33 行
Bus *events.Bus
Log *slog.Logger
CustomStages func(dir string) ([]Stage, error)
Dir string
Branch string
BuildSummary string
ReproProof string
decision *decision
Outcome Outcome
}
Agent 字段是 agentexec.Runner。工作流通过 AgentStage.Stage() (agent.go,第 47-148 行) 调用它。核心调用顺序是:
AgentStage.Stage()从上下文字段 (agent.go,第 94-109 行) 构建一个agentexec.Request。- 调用
tc.Agent.Run(ctx, tc.Dir, req)(第 110 行)。 - 然后处理结果:验证 (
ValidateFor,第 114 行)、追加笔记 (第 117-124 行)、累积代币/迭代次数 (第 129-130 行)、检查非"passed"状态 (第 136-141 行),以及分派给OnResult回调 (第 143-145 行)。
只有 InProcessRunner 使用 runtime.Runtime 直接调用 agentloop.Run。SubprocessRunner 构建一个 Invocation,通过提供者名称映射将完整的请求序列化,并通过 exec.CommandContext 启动一个子进程。
5. 使 archie-agent 成为长期运行的消息总线进程所需的变化
以下是关键的变化领域:
A. 入口点 (cmd/archie-agent/main.go)
- 目前它调用
agentexec.ServeOne,后者解码一个 JSON 调用,执行,并将一个 JSON 响应写入 stdout。这严格是一次性的。 - 要变为长期运行,
main()需要初始化一个消息总线客户端(例如,NATS、RabbitMQ、AMQP 甚至是简单的 gRPC 流),订阅一个主题/队列,并在每个传入的Invocation上循环调用ServeOne(或者更确切地说,其核心逻辑)。 - 信号处理需要优雅地等待进行中的工作完成,而不是在
SIGTERM时直接退出。
B. worker.go 中的 ServeOne 函数
- 目前它在全局范围内构建一个
InProcessRunner(将NewRuntime(invocation.Providers)传递给NewInProcessRunner)。 - 如果进程是长期运行的,则
runtime.Runtime应该在启动时构造一次(可能来自配置或环境变量),而不是每个调用都动态构建。提供者配置会在进程的生命周期内保持不变,因此没有理由每次从 JSON 重新创建运行时。 protocol.go中的Invocation类型包含Providers——如果一个长期运行的 worker 已经在启动时知道其提供者,这可能就不需要了。工作区路径也有问题:对于长期运行的进程,工作区可能由消息路由到(或使用单独的 RPC 调用来准备),而不是嵌入在调用请求中。
C. 线路协议适配
- 当前协议是 request/reply(1 个 JSON 值用于输入,1 个用于输出)。对于总线,
Response会被发布到单独的回复主题/队列,而不是写入 stdout。 - 运行器接口本身 (
Runner.Run(ctx, workspace, req)) 是同步的,这很适合总线——每个消息都可以通过Run处理,结果被发布出去。 - 调用/响应帧中的
Version、TaskID、Attempt、Stage字段提供了足够的路由/关联上下文——Response中的TaskID和Stage使得在回复主题上正确路由变得简单。
D. 环境架构
- 目前,
SubprocessRunner通过继承的环境变量传递 API 密钥,并使用WorkerEnvironment进行过滤(subprocess.go,第 155-162 行)。一个长期运行的进程已经在进行中,但需要能够更新/重新加载提供者凭证而不重新启动(例如,密钥轮换)。这可能需要一个控制通道或一个动态重新加载配置的方法。
E. 配置和工作目录
- 目前,
Invocation承载Workspace,并且每个路径都是请求的一部分。一个基于总线的 worker 可能希望要么:- 在工作区已经准备就绪时接收带外消息(例如,一个单独的“准备”RPC),或者
- 除了运行代理之外,还执行一些较小的设置步骤(克隆 repo)。
- 守护进程当前通过
worktree.Manager(steps.go,第 22-30 行) 处理工作目录准备。如果archie-agent处理其自己的工作目录设置,这会创建一个职责划分问题。
F. SubprocessRunner 对 agentexec 包的依赖
SubprocessRunner是archied端的替代品——它从archied启动archie-agent。如果archie-agent是一个长期运行的进程,archied不会直接启动它;连接成为出站消息总线连接。SubprocessRunner可能会变得过时或需要重构为一个“远程”运行器,该运行器通过总线发送消息而不是生成子进程。
G. 错误处理和死信队列
- 目前,
cmd.Run()中的进程退出代码表示协议失败。对于长期运行的进程,反序列化故障或无效调用应发布到死信队列主题。
总而言之,Runner 接口 (Run(ctx, workspace, req)) 本身不需要改变。然而,它的调用方式会改变:
cmd/archie-agent/main.go将从一次性 stdin/stdout 变为总线主题订阅循环。cmd/archied/main.go将使用一个基于总线的远程运行器,而不是SubprocessRunner。- 提供者查找和运行时生命周期管理将从每次调用(
worker.go中的ServeOne)移动到进程启动时。