Files
homeagent-sdk/example/commondev/e2e_criteria_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

178 lines
5.1 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
import (
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
)
// ★★ 真机端到端:**真实项目 + 真实 go test**,验证刀 4 能识破
// 「真 bug 藏在松判据后面」。
//
// 场景(与 /tmp/d4e2e 手工复现的一致):
//
// Clamp(v,lo,hi) 有三个分支;判据只测了 v<lo
// 代码里删掉 v>hi 分支(真 bug)⇒ 松判据**仍全绿**
//
// 复核必须给出 **pass_with_gaps** 而不是 pass,并说明"变异未被咬住"。
func TestE2E_ReviewCatchesHiddenBugBehindLooseCriteria(t *testing.T) {
if _, err := exec.Command("go", "version").Output(); err != nil {
t.Skip("环境无 go")
}
dir := t.TempDir()
write := func(rel, c string) {
p := filepath.Join(dir, rel)
os.MkdirAll(filepath.Dir(p), 0o755)
if err := os.WriteFile(p, []byte(c), 0o644); err != nil {
t.Fatal(err)
}
}
write("go.mod", "module d4demo\n\ngo 1.21\n")
write("calc.go", `package d4demo
func Clamp(v, lo, hi int) int {
if v < lo {
return lo
}
if v > hi {
return hi
}
return v
}
`)
// ★ 松判据:只测下界
write("calc_test.go", `package d4demo
import "testing"
func TestClampLoose(t *testing.T) {
if Clamp(-5, 0, 10) != 0 {
t.Fatal("低于下界时错")
}
}
`)
if err := exec.Command("git", "init", "-q", "-b", "main", dir).Run(); err != nil {
t.Skipf("git init: %v", err)
}
p := newTestPluginForCriteria(t)
p.ledger.Projects["demo"] = &Project{Name: "demo", RemoteURL: "x"}
p.ledger.Branches["br-1"] = &Branch{
ID: "br-1", ProjectID: "demo", Name: "feat/x", Workdir: dir, Status: "open"}
// 主管定义判据:正向用松判据;变异**删掉 v>hi 分支**
p.ledger.Criteria["cr-clamp"] = &Criteria{
ID: "cr-clamp", ProjectID: "demo", Name: "clamp 上下界", Kind: "unit",
Script: "go test -count=1 ./...",
Expect: "上下界都被限制",
Mutations: []Mutation{{
ID: "M1", File: "calc.go",
Old: " if v > hi {\n return hi\n }\n", New: "",
Note: "删掉上界分支(真 bug)——松判据看不见它",
}},
DefHash: "x",
}
res, err := p.reviewAll("br-1")
if err != nil {
t.Fatal(err)
}
verdict := res["verdict"].(string)
// ① 正向必须**通过**(松判据确实能过 —— 这就是问题所在)
if !res["forward_ok"].(bool) {
t.Fatalf("前提失效:松判据正向应通过。report=%v", res["report"])
}
// ② 变异必须**未被咬住**(真 bug 躲在判据盲区里)
if res["mutate_ok"].(bool) {
t.Fatal("★ 删掉整个上界分支都没被咬住却报 mutate_ok=true —— 反向阶段失效")
}
// ③ 结论绝不能被当成 "pass"
if verdict == "pass" {
t.Fatal("★★ 真 bug + 松判据 ⇒ 给了 pass。这正是刀 4 存在的理由")
}
if verdict != "pass_with_gaps" {
t.Errorf("应为 pass_with_gaps,实际 %q", verdict)
}
// ④ 报告里要能看出是**哪条**变异没被咬住
rep, _ := res["report"].([]map[string]interface{})
if len(rep) == 0 {
t.Fatal("报告为空")
}
ev := str(rep[0], "mutate_evidence")
if !strings.Contains(ev, "未被咬住") {
t.Errorf("mutate_evidence 应指出未被咬住,实际: %s", ev)
}
// ⑤ 工作目录必须**已恢复**(变异不留脏文件)
after, _ := os.ReadFile(filepath.Join(dir, "calc.go"))
if !strings.Contains(string(after), "if v > hi {") {
t.Fatal("★ 变异后未恢复 calc.go —— 工作目录被污染")
}
t.Logf("✅ 真机识破「真 bug 藏在松判据后」: verdict=%s", verdict)
t.Logf(" notes=%v", res["notes"])
}
// ★ 对照:**补一条严判据**后,同一个 bug 会被正向阶段直接抓到。
func TestE2E_TightCriteriaCatchesTheBugDirectly(t *testing.T) {
if _, err := exec.Command("go", "version").Output(); err != nil {
t.Skip("环境无 go")
}
dir := t.TempDir()
write := func(rel, c string) {
p := filepath.Join(dir, rel)
os.MkdirAll(filepath.Dir(p), 0o755)
os.WriteFile(p, []byte(c), 0o644)
}
write("go.mod", "module d4demo2\n\ngo 1.21\n")
// ★ 这个项目里 bug **已经存在**(上界分支缺失)
write("calc.go", `package d4demo2
func Clamp(v, lo, hi int) int {
if v < lo {
return lo
}
return v
}
`)
// 严判据:上下界都测
write("calc_test.go", `package d4demo2
import "testing"
func TestClampTight(t *testing.T) {
if Clamp(-5, 0, 10) != 0 {
t.Fatal("下界错")
}
if Clamp(15, 0, 10) != 10 {
t.Fatal("上界错")
}
}
`)
exec.Command("git", "init", "-q", "-b", "main", dir).Run()
p := newTestPluginForCriteria(t)
p.ledger.Projects["demo2"] = &Project{Name: "demo2", RemoteURL: "x"}
p.ledger.Branches["br-1"] = &Branch{
ID: "br-1", ProjectID: "demo2", Name: "feat/x", Workdir: dir, Status: "open"}
p.ledger.Criteria["cr-1"] = &Criteria{
ID: "cr-1", ProjectID: "demo2", Name: "clamp 上下界", Kind: "unit",
Script: "go test -count=1 ./...",
Mutations: []Mutation{{ID: "M1", File: "calc.go",
Old: "return v\n}", New: "return lo\n}"}},
DefHash: "x",
}
res, err := p.reviewAll("br-1")
if err != nil {
t.Fatal(err)
}
// 正向就抓到 bug ⇒ fail
if res["verdict"] != "fail" {
t.Fatalf("严判据应正向就抓到 bug(fail),实际 %q", res["verdict"])
}
t.Log("✅ 对照:严判据在正向阶段直接抓到同一个 bug → fail")
}