Files
homeagent-sdk/example/commondev/full_pipeline_test.go
JianFeeeee 81a3efa4df feat(commondev): 主管式多仓库开发流水线 + sidecar 后端抽象(pi/zcode) (#3)
* feat(commondev): 主管式多仓库开发流水线 + sidecar 后端抽象(pi/zcode)

## 是什么

agent 统筹开发流程的插件:登记项目 → 开工程线(每条线一个隔离工作目录 +
一个 sidecar 子进程 + 一对通道)→ 投递任务 → 同会话续投 → 评审/合入。

38 个工具:project_*/branch_*/workdir_*/job_*/review_*/test_*/
endpoint_*/agent_*/pi_*/conflict_check。

## sidecar 后端抽象(本轮核心)

传输层(local/ssh)与后端(pi/zcode/自定义)**正交**,四个自由组合:

  driver.json 描述一个后端:script / cliPath / env / args / llmConfig
  三级查找:插件数据目录 → **随包 rawfile** → 内置 pi 描述
  占位符:{workdir} {dataDir} {pluginDir} {rawfile} {sessionId}

★ 内置 pi 回退**与默认后端解耦**(2026-10-17 修):原实现写
`if cli == defaultAgentCLI { return builtinPiDriver() }`,把"给谁兜底"
和"默认选谁"耦合到同一常量 —— 一旦有人改默认,pi 当场失去兜底,
显式 cli="pi" 开始报「驱动不存在」。现在判断字面 "pi"。

默认后端保持 **pi**(我们本地主用);交付方用 zcode 走两种局部开关:
 · 单线:commondev_branch_open(cli="zcode")
 · 按机器:commondev_endpoint_set(host=..., cli="zcode")

## zcode 接入(三条真机判据,全部要求真改工程文件)

 · TestZcodeFullPipeline(29-34s):随包 driver + 真实 ZCode CLI
 · TestZcodeOverSSH(39s):真 ssh + scp,远端 node 跑 zcode
 · TestZcodeOverSSHWithPerHostEndpoints(68s):两个 host 别名配不同
   cli_path,走端点表而不是全局 settings

★ 会话库必须隔离到工作区(sidecar.mjs 的 ensureWorkspaceSessionStore):
实测 ZCode 的会话库路径**硬编码 homedir()**,`ZCODE_DATA_BASE_DIR` 对它
完全无效(26 个会话全落全局库)。但 `<workdir>/.zcode/config.json` 的
`storage.sessionDbPath` **确实生效**。所以启动前写一份工作区配置,
一举解决:多线不共用历史 / 不污染全局 ~/.zcode / 删线不留孤儿会话。
只在不存在时写 —— 用户手工放的要尊重。

## 其他

 · rawfile:项目根 rawfile/ 默认全收,解到 <插件目录>/rawfile/,绝对路径拒绝
 · 凭证:命名引用 + ${ENV_VAR},独立 0600 文件,绝不进 config.db(0644)
 · secretshell:给不受信 agent 用的安全 shell(ackey + safeshell)
 · 冲突检查 / 评审判据 / 镜像 / 每条线独立 workdir(hash 命名,合并后删除)

判据 30+ 条,含 4 条「判据本身的判据」(防止判据假绿)。

* fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染

## 核心缺陷:插件往 stdout 打日志 = 污染 JSON-RPC 协议通道

子进程插件与内核用 stdout 传 NDJSON 帧,stderr 才是日志通道。
脚手架模板(及 4 个示例插件)用 `fmt.Printf` 打日志 ⇒ 内核收到非 JSON 文本:

    [proc] weather 收到非法 JSON 帧(21 字节): invalid character 'i'

**生产实测 1038 条**(huawei_smarthome 720 / weather 113 / rss 103 / calendar 102)。
后果不只是日志噪音:那一行日志被**丢弃**,插件看起来"没启动"。

修法:
- hmapdev 模板 `fmt.Printf` → `log.Printf`(9 处)
- 示例插件 4 个 14 处:ai_image(2) calendar(5) rss(4) weather(3)
  + 补 "log" import
- 内核侧(主仓)同步让报错可定位:内容摘要 + 可能原因 + 修法

判别法:`package main` = 子进程(协议通道,禁用 stdout 打日志);
普通库包 = 进程内插件(编译进内核,写真实终端,**不是**缺陷)——
`internal/plugins/cli` 的 `fmt.Println` 属后者。

## hmapdev

- `cmd_build.go` +136:平台产物精确匹配(`--target` 是**append** 语义,
  原脚本 `ls dist/*.hmap | head -1` 会按字典序抓到 amd64,
  **导致 arm64 包里装的是 x86-64 二进制**,且退出码 0、校验和通过)
- `cmd_init.go` +46:脚手架 stdio 纪律
- `templates/proc_main.go.tmpl`:补齐 mgrStop/mgrStart/mgrIsRuntimeStopped
  三态能力(插件管理器运行态停启)
- `templates/plg.json.tmpl` 删除(合并进 cmd_init)

## 判据

- `scaffold_stdout_test.go`(3 条):扫模板生成的代码不得写 stdout。
  ★ 判据自身先假红过一次:**模板的注释里就写了 `fmt.Printf`** ⇒
  必须 `stripTemplateComments()` 之后才判
- `example_stdout_test.go`(2 条):扫全部 20 个子进程示例插件,
  报错给**文件:行号**;变异咬住并给出准确行号
- `package_examples_test.go`(2 条):**执行真实打包脚本**
  (第一版测的是 hmapdev 而不是脚本 ⇒ 变异不咬)
- `cmd_build` / `cmd_init` 新判据

## 其他

- sdk/settings.go +15(三态能力透传)
- `docs/versions.md` +§示例插件协议通道纪律(含生产 1038 条实测表格)
- `skills/homeagent-plugin-dev/SKILL.md` +§协议通道纪律(正误代码对比)

* fix(examples): 恢复 go.mod 相对路径 + 移除 plg.json 的 sdk 固定(修 CI 红)

CI 上 `Examples (linux/amd64)` 与 `(darwin/arm64)` 双红,只有两个失败:

  ✗ commondev   构建失败
  ✗ editdoc     构建失败
  error: 项目声明 sdk=1.4.0,但本地 SDK 存储里没有这个版本

其余 20 个示例全部成功 —— 说明不是通用问题,而是这两个被改坏了。

## 根因(两个叠加)

**① go.mod 被本机绝对路径污染**

我在上一个提交里用 `git add -A`,把本机 `go build` **自动改写**过的
go.mod 一并提交了:

  require github.com/JianFeeeee/homeagentsdk v1.4.0
  replace github.com/JianFeeeee/homeagentsdk => /root/.homeagent/hmapdev/sdk/v1.4.0

基线(origin/main)是:

  require github.com/JianFeeeee/homeagentsdk v0.0.0
  replace github.com/JianFeeeee/homeagentsdk => ../../

本机那个目录真的存在 ⇒ 本地全绿;CI 没有 ⇒ 必红。

**② plg.json 声明了 `"sdk": "1.4.0"`**

一声明版本,hmapdev 就去**本地 SDK store** 找它,找不到直接拒绝构建。
全仓 20+ 示例**都不声明**,只有我改过的这两个声明了。
示例的正确依赖表达是 go.mod 的 `v0.0.0` + `replace ../../`。

## 修法

两个文件都恢复到与其余示例一致的写法。

## 判据(3 条,都是新加的)

 · `TestExampleGoModHasNoAbsoluteReplace`:任何示例 go.mod 不得含
   `/root/`、`/home/`、`/Users/`、`C:\`
 · `TestExampleGoModUsesRelativeSDKReplace`:replace 必须是相对路径 `../../`
 · `TestExamplePlgJsonDoesNotPinSDKVersion`:plg.json 不得声明 sdk

变异 2/2 咬住(重新引入绝对路径 / 重新声明 sdk,都准确报出文件路径)。

## 本地验证(模拟 CI 干净环境)

用干净 HOME 跑 `package/build-examples.sh`:
 · 修复前:成功 18 / 失败 4(commondev, editdoc, browser, rss)
 · 修复后:成功 20 / 失败 2(browser, rss —— **本机代理不通**,
   `proxy.golang.org` 超时;用本地 modcache 验证这两个可正常构建)

即 22/22 源码都能构建,CI 有网络不受影响。

## 教训

`git add -A` 会把「构建工具自动改写的文件」一起提交。
提交前必须 `git status` 逐个看,尤其 go.mod / go.sum。

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
2026-10-17 19:44:15 +08:00

191 lines
6.8 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

package main
// ★★★ 全流程判据:用**插件自己的工具**跑完整生命周期。
//
// 手写脚本证明的是"pi 能改代码";这条证明的是**插件的代码路径**能把它串起来:
// project_add → branch_open → (目录准备) → agent_up → 投递 → 收尾
//
// 与 pi_e2e_test.go 的分工:那条测 sidecar 契约,这条测**插件编排**。
import (
"encoding/json"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
)
func gitQ(t *testing.T, dir string, args ...string) {
t.Helper()
cmd := exec.Command("git", args...)
cmd.Dir = dir
cmd.Env = append(cmd.Environ(),
"GIT_AUTHOR_NAME=t", "GIT_AUTHOR_EMAIL=t@t",
"GIT_COMMITTER_NAME=t", "GIT_COMMITTER_EMAIL=t@t")
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("git %v: %v: %s", args, err, out)
}
}
// ★★★ 判据:插件工具能把一条工程线从登记走到"pi 真的改了工程文件"。
//
// 需要内嵌 node+pi 与可用 LLM 源:
//
// HA_PI_E2E=1 HA_PI_AGENTDIR=<配好的 agentdir> go test -run TestFullPipeline ./...
func TestFullPipeline(t *testing.T) {
nodeBin, sidecarPath := piE2EReady(t)
agentDir := os.Getenv("HA_PI_AGENTDIR")
if agentDir == "" {
t.Skip("需要 HA_PI_AGENTDIR(含可用 LLM 源的 pi agentdir)")
}
base := t.TempDir()
origin := filepath.Join(base, "origin")
gitQ(t, base, "init", "-q", "-b", "main", origin)
if err := os.MkdirAll(filepath.Join(origin, "src"), 0o755); err != nil {
t.Fatal(err)
}
os.WriteFile(filepath.Join(origin, "src/calc.py"),
[]byte("def add(a, b):\n return a + b\n"), 0o644)
gitQ(t, origin, "add", "-A")
gitQ(t, origin, "commit", "-qm", "initial")
// ① 登记项目(走插件工具)
p := newFlowPlugin(t)
r1, _ := p.handleProjectAdd(map[string]interface{}{
"name": "demo", "remote_url": origin, "default_branch": "main",
})
if m := r1.(map[string]interface{}); m["status"] != "ok" {
t.Fatalf("登记项目失败: %v", m)
}
// ② 开线(走插件工具)—— 它会把 clone 转后台
r2, _ := p.handleBranchOpen(map[string]interface{}{
"project": "demo", "branch": "feat/mul", "work_desc": "加 multiply",
})
m2 := r2.(map[string]interface{})
if m2["status"] != "ok" {
t.Fatalf("开线失败: %v", m2)
}
branchID := m2["branch_id"].(string)
workdir := m2["workdir"].(string)
// ③ 同步准备目录(不走后台 goroutine,避免与判据的时序竞争)
b := p.ledger.Branches[branchID]
if err := p.prepareWorkdir(p.ledger.Projects["demo"], "feat/mul", workdir); err != nil {
t.Fatalf("目录准备失败: %v", err)
}
// ★ 目录必须在目标分支上(否则 agent 会在 main 上改)
br, err := exec.Command("git", "-C", workdir, "rev-parse", "--abbrev-ref", "HEAD").Output()
if err != nil {
t.Fatal(err)
}
if strings.TrimSpace(string(br)) != "feat/mul" {
t.Fatalf("★ 目录不在目标分支: %q", strings.TrimSpace(string(br)))
}
// ④ 走 sidecar 契约投递任务(agent_up 的内核部分)
b.Workdir = workdir
_, w, rd := startSidecarForE2E(t, nodeBin, sidecarPath, workdir, branchID)
ping := callSidecar(t, w, rd, 1, "ping", nil)
if ping.Error != nil {
t.Fatalf("握手失败: %s", ping.Error.Message)
}
resp := callSidecar(t, w, rd, 2, "prompt", map[string]interface{}{
"session_id": branchID,
"text": "在 src/calc.py 里新增 multiply(a, b) 返回 a*b,保留 add。只回一句完成。",
})
if resp.Error != nil {
t.Fatalf("投递失败: %s", resp.Error.Message)
}
var pr map[string]interface{}
if err := json.Unmarshal(resp.Result, &pr); err != nil {
t.Fatal(err)
}
// ★ 会话不得漂移
if got, _ := pr["session_id"].(string); got != "" && got != branchID {
t.Fatalf("★ 会话漂移: %s vs %s", got, branchID)
}
// ⑤ **关键断言**:pi 真的改了**这个工程**的文件
b2, err := os.ReadFile(filepath.Join(workdir, "src", "calc.py"))
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(b2), "multiply") {
t.Fatalf("★ pi 没有在工程里加 multiply:\n%s", b2)
}
if !strings.Contains(string(b2), "def add") {
t.Errorf("★ 原有代码被破坏:\n%s", b2)
}
// ⑥ 提交后做冲突预检(走插件工具)
gitQ(t, workdir, "add", "-A")
gitQ(t, workdir, "commit", "-qm", "feat: add multiply")
r6, _ := p.handleConflictCheck(map[string]interface{}{
"branch_id": branchID, "target": "main",
})
if m, ok := r6.(map[string]interface{}); ok {
if e, bad := m["error"]; bad {
t.Fatalf("冲突预检失败: %v", e)
}
t.Logf("冲突预检结果: %v", m)
}
// ⑦ 收尾(走插件工具):台账标记 + 目录删除
r7, _ := p.handleBranchClose(map[string]interface{}{"branch_id": branchID})
if m, ok := r7.(map[string]interface{}); ok {
if e, bad := m["error"]; bad {
t.Fatalf("收尾失败: %v", e)
}
}
if _, err := os.Stat(workdir); !os.IsNotExist(err) {
t.Errorf("★ 收尾后工作目录应被删除: %v", err)
}
t.Logf("✅ 全流程闭环:登记 → 开线(分支正确) → 投递 → pi 真改工程 → 冲突预检 → 收尾")
}
// ★★★ 判据:**agent_up 真能拉起 sidecar**(走随包分发的脚本)。
//
// 这条覆盖的缺口(2026-10-15 实测发现):sidecar 脚本此前**没有随包分发**,
// 而插件数据目录的 runtime/<cli>/ 在部署时没人创建 ⇒ agent_up 必然失败,
// 报「找不到 pi 的 sidecar 脚本」并指向一个用户没听说过的路径。
//
// 本判据用**解包后的插件目录布局**(rawfile/runtime/pi/)验证查找链,
// 并真的拉起进程完成握手 —— 证明"脚本随包 + 查找链"这条组合可用。
func TestAgentUpFindsShippedSidecar(t *testing.T) {
nodeBin, _ := piE2EReady(t)
root, _ := os.Getwd()
// 模拟解包后的布局:脚本在 rawfile/runtime/pi/
shipped := filepath.Join(root, "rawfile", "runtime", "pi", "sidecar.mjs")
if _, err := os.Stat(shipped); err != nil {
t.Fatalf("★ 随包脚本不存在: %v", err)
}
p := newFlowPlugin(t)
p.sdk.SetRawFilesAPI(&testRawFiles{root: filepath.Join(root, "rawfile")})
// cliDir 指向**不存在的**目录(全新部署的真实状态)
cliDir := filepath.Join(t.TempDir(), "runtime", "pi")
got, err := p.locateSidecarScript(builtinPiDriver(), cliDir, "pi")
if err != nil {
t.Fatalf("★ 查找链找不到随包脚本(agent_up 会失败): %v", err)
}
// 用找到的脚本真的拉起 sidecar 并握手
workdir := t.TempDir()
_, w, r := startSidecarForE2E(t, nodeBin, got, workdir, "agentup-e2e")
ping := callSidecar(t, w, r, 1, "ping", nil)
if ping.Error != nil {
t.Fatalf("★ 用随包脚本拉起的 sidecar 握手失败: %s", ping.Error.Message)
}
var pr map[string]interface{}
json.Unmarshal(ping.Result, &pr)
if ok, _ := pr["ok"].(bool); !ok {
t.Fatalf("ping 未 ok: %v", pr)
}
t.Logf("✅ 随包 sidecar 脚本可用,pi 版本: %v", pr["pi_version"])
}