mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 14:27:30 +00:00
feat(commondev): 支持取消正在运行的任务（commondev_agent_interrupt）
## 缺陷（用户实测反馈） 「commondev 无法取消正在运行的 session，agent 反馈它无法取消错误的 pi session，只能等它跑完。」 日志佐证：agent 在 09:07 收到 interrupt 请求后只能如实回答无法取消。 ## 根因不是"没实现取消"，而是取消能力从来没被暴露 pi 的 AgentSession **本身就有** abort()（agent-session.d.ts:598， "Abort current operation and wait for agent to become idle"）。 但 commondev 注册的 30 个工具里一个 cancel/stop 都没有， sidecar 也只有 ping/prompt/state/close 四个 method。 这是异步投递（2026-10-17）带来的新缺口：改动之前 prompt 是同步的， 调用方阻塞到任务结束，没有"中途要停"这个需求；改成异步投递后， 任务在后台长跑，用户却失去了停止它的手段。 ## 改动 **sidecar 三个平台各有各的取消方式：** pi → session.abort()（协作式中断，必须 await：不 await 会立刻 回"已中断"而实际还在跑 = 谎报成功） zcode → 整组杀掉当前回合的子进程（没有 abort API） spawn 时 detached=true 建了独立进程组，killTree 整组杀 **interrupt 语义如实回报：** interrupted=true 确实有任务在跑并被终止 interrupted=false 当时没有在跑的任务（不算错误） ok=false + error 该 CLI 没实现 / 调用失败 **三个收尾分支都清 currentChild**（timeout / error / close）： 不清的话 interrupt 会拿到已死的子进程去杀，或更糟 —— 误杀下一轮。 ## 判据（4 条 + 「不谎报」） · pi 的两个 sidecar 都有 interrupt 且用 await session.abort() · zcode 的 interrupt 真的 killTree 且用 currentChild · 三个 sidecar 无重复声明（我写的时候真撞了：zcode 已有 currentChild） · **不谎报成功**：sidecar 没跑 / CLI 没实现时必须 interrupted=false ## 变异验证 pi 删 interrupt case → 咬 pi 去掉 await → 咬（"会谎报已中断"） zcode 不 killTree → 咬（"只回 ok 不真杀"） ## 顺带 既有判据 TestEveryRegisteredToolHasHandler 立刻抓到我加了 RegisterTool 但没在 handlerFor 映射里登记 —— 它比我先发现漏了接线。
This commit is contained in:
JianFeeeee
@ -128,6 +128,8 @@ func handlerFor(p *Plugin, name string) func(map[string]interface{}) (interface{
|
||||
return p.handleEndpointList
|
||||
case "commondev_endpoint_remove":
|
||||
return p.handleEndpointRemove
|
||||
case "commondev_agent_interrupt":
|
||||
return p.handleAgentInterrupt
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
138
example/commondev/interrupt_test.go
Normal file
138
example/commondev/interrupt_test.go
Normal file
@ -0,0 +1,138 @@
|
||||
package main
|
||||
|
||||
// 「取消正在运行的任务」判据（2026-10-18 用户实测反馈）。
|
||||
//
|
||||
// ## 缺陷
|
||||
//
|
||||
// prompt 改成异步投递后，Go 侧只能"把任务发出去"，**无法收回**。于是用户
|
||||
// 发现派错任务、或某条 session 卡住时，除了等它自己跑完以外没有任何办法 ——
|
||||
// agent 在日志里也只能如实回答"无法取消，只能等它跑完"。
|
||||
//
|
||||
// 根因不是"没实现取消"，而是取消能力**从来没有被暴露**：pi 的 AgentSession
|
||||
// 本身就有 abort()，但 commondev 的 30 个工具里一个 cancel/stop 都没有，
|
||||
// sidecar 也只有 ping/prompt/state/close 四个 method。
|
||||
//
|
||||
// ## 判据设计
|
||||
//
|
||||
// 关键是**不谎报成功**：sidecar 没在跑、或该 CLI 没实现 interrupt 时，
|
||||
// 必须把"没有真正中断"如实回给调用方。否则用户以为停了、实际还在跑。
|
||||
|
||||
import (
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// ★★★ sidecar 必须实现 interrupt，且 pi 用的是 session.abort()
|
||||
func TestPiSidecarImplementsInterrupt(t *testing.T) {
|
||||
for _, path := range []string{
|
||||
"sidecar.mjs", // 单测/SSH e2e 用
|
||||
"rawfile/runtime/pi/sidecar.mjs", // 部署用（hmapdev 打进 rawfile）
|
||||
} {
|
||||
b, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("读 %s: %v", path, err)
|
||||
}
|
||||
src := string(b)
|
||||
if !strings.Contains(src, `case "interrupt":`) {
|
||||
t.Fatalf("★ %s 没有 interrupt method —— 取消能力无从触达", path)
|
||||
}
|
||||
// pi 必须用自带的 abort()，而不是自己造机制
|
||||
if !strings.Contains(src, "session.abort()") {
|
||||
t.Fatalf("★ %s 的 interrupt 没有调用 pi 的 session.abort()", path)
|
||||
}
|
||||
// 必须 await（abort 返回 Promise；不 await 会立刻回"已中断"但实际还在跑）
|
||||
if !strings.Contains(src, "await session.abort()") {
|
||||
t.Fatalf("★ %s 的 abort() 没有 await —— 会谎报已中断", path)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ★★★ zcode 是子进程模式，取消 = 整组杀掉当前回合
|
||||
func TestZcodeSidecarInterruptKillsChild(t *testing.T) {
|
||||
b, err := os.ReadFile("rawfile/runtime/zcode/sidecar.mjs")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
src := string(b)
|
||||
if !strings.Contains(src, `case "interrupt":`) {
|
||||
t.Fatal("★ zcode sidecar 没有 interrupt method")
|
||||
}
|
||||
// 必须真的杀进程，而不是只返回 ok
|
||||
seg := src[strings.Index(src, `case "interrupt":`):]
|
||||
if end := strings.Index(seg, `case "close":`); end > 0 {
|
||||
seg = seg[:end]
|
||||
}
|
||||
if !strings.Contains(seg, "killTree(") {
|
||||
t.Fatalf("★ zcode 的 interrupt 没有 killTree —— 只回 ok 不真杀")
|
||||
}
|
||||
if !strings.Contains(seg, "currentChild") {
|
||||
t.Fatalf("★ zcode 的 interrupt 没有用 currentChild（杀不到真实进程）")
|
||||
}
|
||||
}
|
||||
|
||||
// ★★★ 三个 sidecar 必须语法合法（node --check 之外的静态兜底：
|
||||
// 至少不能有重复声明这类必炸错误）
|
||||
func TestSidecarsHaveNoDuplicateDecl(t *testing.T) {
|
||||
for _, path := range []string{
|
||||
"sidecar.mjs",
|
||||
"rawfile/runtime/pi/sidecar.mjs",
|
||||
"rawfile/runtime/zcode/sidecar.mjs",
|
||||
} {
|
||||
b, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("读 %s: %v", path, err)
|
||||
}
|
||||
n := strings.Count(string(b), "let currentChild = null;")
|
||||
if n > 1 {
|
||||
t.Fatalf("★ %s 里 currentChild 声明了 %d 次（重复声明 = 启动即 SyntaxError）", path, n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ★★★ 核心纪律判据：**不谎报成功**。
|
||||
//
|
||||
// sidecar 没在跑、或 CLI 没实现 interrupt 时，必须如实回 interrupted=false。
|
||||
// 谎报的代价：用户以为停了，实际任务还在跑并继续改代码/推分支。
|
||||
func TestAgentInterruptNeverLiesAboutSuccess(t *testing.T) {
|
||||
p := newTestPluginForShell(t)
|
||||
p.ledger = &Ledger{
|
||||
Projects: map[string]*Project{},
|
||||
Branches: map[string]*Branch{},
|
||||
Jobs: map[string]*Job{},
|
||||
Criteria: map[string]*Criteria{},
|
||||
}
|
||||
|
||||
// ① 不存在的 branch → 报错，不能回 interrupted=true
|
||||
out, err := p.handleAgentInterrupt(map[string]interface{}{"branch_id": "br-nope"})
|
||||
if err != nil {
|
||||
t.Fatalf("不应返回 error: %v", err)
|
||||
}
|
||||
m := out.(map[string]interface{})
|
||||
if v, _ := m["interrupted"].(bool); v {
|
||||
t.Fatal("★ 对不存在的 branch 回了 interrupted=true")
|
||||
}
|
||||
if m["error"] == nil {
|
||||
t.Fatal("对不存在的 branch 应给出 error")
|
||||
}
|
||||
|
||||
// ② branch 存在但 sidecar 没跑 → interrupted=false + note
|
||||
// 直接塞进 ledger，不调 handleBranchOpen（它会触发真实 git clone）
|
||||
id := "br-iproj-ifeat"
|
||||
p.ledger.Branches[id] = &Branch{
|
||||
ID: id, ProjectID: "iproj", Name: "feat/ifeat",
|
||||
Status: "open", Runtime: "local", AgentCLI: "pi",
|
||||
}
|
||||
|
||||
out2, err := p.handleAgentInterrupt(map[string]interface{}{"branch_id": id})
|
||||
if err != nil {
|
||||
t.Fatalf("不应返回 error: %v", err)
|
||||
}
|
||||
m2 := out2.(map[string]interface{})
|
||||
if v, _ := m2["interrupted"].(bool); v {
|
||||
t.Fatal("★ sidecar 没在跑却回了 interrupted=true —— 谎报成功")
|
||||
}
|
||||
if m2["note"] == nil {
|
||||
t.Fatal("sidecar 没跑时应给出 note 说明")
|
||||
}
|
||||
}
|
||||
@ -699,6 +699,20 @@ func (p *Plugin) registerTools() {
|
||||
ParallelSafe: true,
|
||||
}, p.handleAgentState)
|
||||
|
||||
p.sdk.RegisterTool("commondev_agent_interrupt", sdk.ToolDef{
|
||||
Name: "commondev_agent_interrupt",
|
||||
Description: "取消某条工程对话**正在运行的任务**（保留会话与工作目录，可继续派新任务）。" +
|
||||
"用于派错任务、或某个 session 卡住时不再干等它跑完。" +
|
||||
"与 commondev_agent_down 的区别：这是「停当前这一轮」，那是「停整个进程」。" +
|
||||
"中断是**协作式**的，工具调用中途可能还要一小段时间才真正停下。",
|
||||
Parameters: map[string]interface{}{"type": "object", "properties": map[string]interface{}{
|
||||
"branch_id": map[string]interface{}{"type": "string", "description": "工程对话 id"},
|
||||
}, "required": []string{"branch_id"}},
|
||||
NoMemory: true,
|
||||
Serial: true,
|
||||
Timeout: "60s",
|
||||
}, p.handleAgentInterrupt)
|
||||
|
||||
p.sdk.RegisterTool("commondev_agent_down", sdk.ToolDef{
|
||||
Name: "commondev_agent_down",
|
||||
Description: "停掉一条工程对话的 agent 进程（**保留工作目录与分支状态**）。" +
|
||||
|
||||
@ -172,6 +172,35 @@ async function handle(method, params) {
|
||||
messages: Array.isArray(s.messages) ? s.messages.length : 0,
|
||||
};
|
||||
}
|
||||
// ★★ interrupt：取消正在运行的任务（2026-10-18 新增）。
|
||||
//
|
||||
// 为什么必须有：prompt 改成异步投递后，Go 侧只能"发出去"，无法收回。
|
||||
// 实测后果 —— 用户发现派错了任务、或某个 session 卡住时，**没有任何办法
|
||||
// 停下它**，只能等 pi 自己跑完（agent 在日志里如实回答"无法取消"）。
|
||||
//
|
||||
// pi 的 AgentSession 本身有 abort()：Abort current operation and wait
|
||||
// for agent to become idle。这里直接用它，不自己造机制。
|
||||
//
|
||||
// 语义说明（必须如实回给调用方）：
|
||||
// · abort() 是**协作式**的：它在下一个可中断点生效，不是 SIGKILL。
|
||||
// 工具调用中途可能还要一小段时间才真正停下。
|
||||
// · 返回 interrupted=true 表示"已发出中断且会话已回到空闲"；
|
||||
// 若当时没有在跑的任务，interrupted=false 但 ok=true（不算错误）。
|
||||
case "interrupt": {
|
||||
if (!session) return { ok: true, interrupted: false, reason: "no_session" };
|
||||
const hadInflight = inflight > 0;
|
||||
try {
|
||||
await session.abort();
|
||||
} catch (e) {
|
||||
return { ok: false, interrupted: false, error: String((e && e.message) || e) };
|
||||
}
|
||||
return {
|
||||
ok: true,
|
||||
interrupted: hadInflight,
|
||||
// 如实报告剩余在途数：>0 说明还有任务在收尾（调用方可据此决定是否再等）
|
||||
inflight,
|
||||
};
|
||||
}
|
||||
case "close": {
|
||||
try {
|
||||
session?.dispose?.();
|
||||
|
||||
@ -47,6 +47,70 @@ func (p *Plugin) handleAgentState(args map[string]interface{}) (interface{}, err
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// handleAgentInterrupt 是 commondev_agent_interrupt 的实现。
|
||||
//
|
||||
// 为什么需要它（2026-10-18 用户实测反馈）：prompt 改成异步投递后，
|
||||
// 插件只能"把任务发出去"，**无法收回**。于是用户发现派错了任务、
|
||||
// 或某条 session 卡住时，除了等它自己跑完以外没有任何办法 ——
|
||||
// agent 在日志里也只能如实回答"无法取消，只能等它跑完"。
|
||||
//
|
||||
// 三个 CLI 的取消方式不同，这里统一到 sidecar 的 interrupt method：
|
||||
//
|
||||
// pi → session.abort()（pi SDK 自带，协作式中断）
|
||||
// zcode → 整组杀掉当前回合的子进程（没有 abort API）
|
||||
// 其它 → 由各自 sidecar 决定；未实现时如实报错，不假装成功
|
||||
//
|
||||
// ★ 关键纪律：**不谎报成功**。sidecar 没在跑、或该 CLI 没实现 interrupt 时，
|
||||
// 必须把"没有真正中断"如实回给调用方 —— 否则用户以为停了，实际还在跑。
|
||||
func (p *Plugin) handleAgentInterrupt(args map[string]interface{}) (interface{}, error) {
|
||||
id := strings.TrimSpace(str(args, "branch_id"))
|
||||
if id == "" {
|
||||
return map[string]interface{}{"error": "branch_id 必填"}, nil
|
||||
}
|
||||
p.mu.Lock()
|
||||
b, ok := p.ledger.Branches[id]
|
||||
sc := p.sidecars[id]
|
||||
p.mu.Unlock()
|
||||
if !ok {
|
||||
return map[string]interface{}{"error": fmt.Sprintf("工程对话 %s 不存在", id)}, nil
|
||||
}
|
||||
if sc == nil || !sc.Alive() {
|
||||
return map[string]interface{}{
|
||||
"branch_id": id,
|
||||
"interrupted": false,
|
||||
"note": "sidecar 未在运行 —— 没有在跑的任务可取消。用 commondev_agent_up 拉起。",
|
||||
}, nil
|
||||
}
|
||||
|
||||
raw, err := sc.call("interrupt", nil)
|
||||
if err != nil {
|
||||
// 未实现 / 调用失败：如实报告，绝不返回 interrupted=true
|
||||
return map[string]interface{}{
|
||||
"branch_id": id,
|
||||
"interrupted": false,
|
||||
"error": fmt.Sprintf("sidecar 不支持或中断失败: %v", err),
|
||||
"note": "该 CLI 的 sidecar 可能还没有 interrupt 实现；" +
|
||||
"可改用 commondev_agent_down 直接停进程（会结束整个会话）。",
|
||||
}, nil
|
||||
}
|
||||
|
||||
out := map[string]interface{}{"branch_id": id, "agent_cli": cliOrPi(b.AgentCLI)}
|
||||
if m, ok := raw.(map[string]interface{}); ok {
|
||||
for k, v := range m {
|
||||
out[k] = v
|
||||
}
|
||||
}
|
||||
// ★ 只有 sidecar 明确说 interrupted=true 才算真的中断了
|
||||
if v, _ := out["interrupted"].(bool); !v {
|
||||
if r, _ := out["reason"].(string); r != "" {
|
||||
out["note"] = "没有在跑的任务（reason=" + r + "）"
|
||||
} else {
|
||||
out["note"] = "sidecar 未确认有任务被中断"
|
||||
}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// handleAgentDown 是 commondev_agent_down 的实现（幂等收尾）。
|
||||
//
|
||||
// 与 branch_close 的区别：**只杀进程、不动工作目录、不改分支状态**。
|
||||
|
||||
Reference in New Issue
Block a user