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>
This commit is contained in:
JianFeeeee
2026-10-17 19:44:15 +08:00
committed by GitHub
parent 65d2bd9e61
commit 81a3efa4df
91 changed files with 21184 additions and 224 deletions

View File

@ -0,0 +1,378 @@
package main
// 刀 4 的判据:判据与复核(正向 + 变异)。
//
// ## 这组判据要证明的核心命题
//
// 设计 §4.5:「插件 GREEN ≠ 改对了」——
//
// 插件只能跑主管**预先写下**的判据。判据没覆盖那条 bug,插件照样打勾。
// 自动化**不会**发现假绿,只会让假绿跑得更快、更可信。
//
// ⇒ 复核必须是两步:正向(判据应过)+ 反向(变异应被咬住)。
//
// 所以本文件最重要的判据是 **TestReviewCatchesLooseCriteria**:
// 造一个「真 bug 但判据太松」的场景,断言复核**不给出 pass**。
import (
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
)
// newTestPluginForCriteria 建一个带台账的插件。
func newTestPluginForCriteria(t *testing.T) *Plugin {
t.Helper()
p := newTestPluginForShell(t)
p.ledger = &Ledger{
Projects: map[string]*Project{},
Branches: map[string]*Branch{},
Jobs: map[string]*Job{},
Criteria: map[string]*Criteria{},
}
return p
}
// writeRepo 在工作目录里放一个可被变异的最小 Go 项目。
func writeRepo(t *testing.T, loose bool) string {
t.Helper()
dir := t.TempDir()
mustWrite := func(rel, content string) {
path := filepath.Join(dir, rel)
os.MkdirAll(filepath.Dir(path), 0o755)
if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
t.Fatal(err)
}
}
mustWrite("go.mod", "module probe\n\ngo 1.21\n")
mustWrite("calc.go", `package calc
func Max(a, b int) int {
if a > b {
return a
}
return b
}
`)
if loose {
// ★ 松判据:只测 a>b 的分支
mustWrite("calc_test.go", `package calc
import "testing"
func TestMax(t *testing.T) {
if Max(5, 3) != 5 {
t.Fatal("错")
}
}
`)
} else {
// 严判据:两个方向都测
mustWrite("calc_test.go", `package calc
import "testing"
func TestMax(t *testing.T) {
if Max(5, 3) != 5 {
t.Fatal("a>b 错")
}
if Max(3, 5) != 5 {
t.Fatal("b>a 错")
}
}
`)
}
return dir
}
func gitIn(t *testing.T, dir string, args ...string) {
t.Helper()
cmd := exec.Command("git", append([]string{"-C", dir}, args...)...)
cmd.Env = append(os.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\n%s", args, err, out)
}
}
// ★★★ 本刀最重要的判据:**复核必须识破「真 bug + 松判据」**。
//
// 场景:
//
// 代码 Max 正确;判据只测 Max(5,3)(漏了 b>a)
// 变异:return b → return a(真 bug)
// 松判据**仍通过** ⇒ 该变异"未被咬住"
//
// 期望:复核结论**不是 pass**(而是 pass_with_gaps),并明确指出
// "变异未被咬住 ⇒ 判据太松"。
//
// 若这条报红,说明复核机制回到了"只看正向"——那就失去了本刀的全部意义。
func TestReviewCatchesLooseCriteria(t *testing.T) {
p := newTestPluginForCriteria(t)
dir := writeRepo(t, true) // ★ 松判据
p.ledger.Projects["probe"] = &Project{Name: "probe", RemoteURL: "x"}
p.ledger.Branches["br-1"] = &Branch{ID: "br-1", ProjectID: "probe", Name: "feat/x", Workdir: dir, Status: "open"}
p.ledger.Criteria["cr-1"] = &Criteria{
ID: "cr-1", ProjectID: "probe", Name: "max 单元判据", Kind: "unit",
Script: "go test ./...",
Expect: "两方向都正确",
Mutations: []Mutation{{
ID: "M1", File: "calc.go",
Old: "\treturn b\n}", New: "\treturn a\n}",
Note: "验证判据是否覆盖 b>a 分支",
}},
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("前提失效:松判据的正向应通过,实际 evidence=%v", res["report"])
}
// ② 反向必须**没被咬住**
if res["mutate_ok"].(bool) {
t.Fatal("★ 变异未被咬住却报 mutate_ok=true —— 反向阶段没在起作用")
}
// ③ 结论**绝不能是 pass**
if verdict == "pass" {
t.Fatal("★★ 真 bug + 松判据 却给出 pass —— " +
"这正是设计 §4.5 说的『给测试通过充值信用,直到它骗一次大的』")
}
if verdict != "pass_with_gaps" {
t.Errorf("结论应为 pass_with_gaps,实际 %q", verdict)
}
// ④ 必须明确说明原因(不能只给个模糊的黄色)
notes, _ := res["notes"].([]string)
joined := strings.Join(notes, " ")
if !strings.Contains(joined, "太松") && !strings.Contains(joined, "未被咬住") {
t.Errorf("notes 应指出『判据太松』,实际: %v", notes)
}
t.Logf("✅ 松判据被识破:verdict=%s notes=%v", verdict, notes)
}
// ★★ 判据:**严判据**时复核给出 pass(机制不能把一切都说成有问题)。
func TestReviewPassesWithTightCriteria(t *testing.T) {
p := newTestPluginForCriteria(t)
dir := writeRepo(t, false) // 严判据
p.ledger.Projects["probe"] = &Project{Name: "probe", RemoteURL: "x"}
p.ledger.Branches["br-1"] = &Branch{ID: "br-1", ProjectID: "probe", Name: "feat/x", Workdir: dir, Status: "open"}
p.ledger.Criteria["cr-1"] = &Criteria{
ID: "cr-1", ProjectID: "probe", Name: "max 单元判据", Kind: "unit",
Script: "go test ./...",
Mutations: []Mutation{{
ID: "M1", File: "calc.go",
Old: "\treturn b\n}", New: "\treturn a\n}",
Note: "b>a 分支",
}},
DefHash: "x",
}
res, err := p.reviewAll("br-1")
if err != nil {
t.Fatal(err)
}
if res["verdict"] != "pass" {
t.Fatalf("严判据应给 pass,实际 %q(notes=%v)", res["verdict"], res["notes"])
}
if !res["forward_ok"].(bool) || !res["mutate_ok"].(bool) {
t.Fatalf("正向与反向都应通过: forward=%v mutate=%v",
res["forward_ok"], res["mutate_ok"])
}
t.Log("✅ 严判据 → pass(机制不会把一切都判成有问题)")
}
// ★★ 判据:**判据实现有 bug** 时正向就报红 ⇒ fail。
func TestReviewFailsOnForwardFailure(t *testing.T) {
p := newTestPluginForCriteria(t)
dir := writeRepo(t, false)
p.ledger.Projects["probe"] = &Project{Name: "probe", RemoteURL: "x"}
p.ledger.Branches["br-1"] = &Branch{ID: "br-1", ProjectID: "probe", Workdir: dir, Status: "open"}
p.ledger.Criteria["cr-1"] = &Criteria{
ID: "cr-1", ProjectID: "probe", Name: "故意失败", Kind: "unit",
Script: "false", // 永远失败
Mutations: []Mutation{{ID: "M1", File: "calc.go", Old: "a > b", New: "a >= b"}},
DefHash: "x",
}
res, err := p.reviewAll("br-1")
if err != nil {
t.Fatal(err)
}
if res["verdict"] != "fail" {
t.Fatalf("正向失败应给 fail,实际 %q", res["verdict"])
}
if res["forward_ok"].(bool) {
t.Fatal("forward_ok 应为 false")
}
}
// ★★ 判据:**未定义变异规则**时不能给 pass(那正是"信号充值")。
func TestReviewFlagsMissingMutations(t *testing.T) {
p := newTestPluginForCriteria(t)
dir := writeRepo(t, false)
p.ledger.Projects["probe"] = &Project{Name: "probe", RemoteURL: "x"}
p.ledger.Branches["br-1"] = &Branch{ID: "br-1", ProjectID: "probe", Name: "feat/x", Workdir: dir, Status: "open"}
p.ledger.Criteria["cr-1"] = &Criteria{
ID: "cr-1", ProjectID: "probe", Name: "无变异", Kind: "unit",
Script: "go test ./...",
// ★ 刻意不给 Mutations
DefHash: "x",
}
res, err := p.reviewAll("br-1")
if err != nil {
t.Fatal(err)
}
if res["verdict"] == "pass" {
t.Fatal("★ 无变异规则却给 pass —— 等于把『没检查』当『检查通过』")
}
if res["verdict"] != "pass_with_gaps" {
t.Errorf("应为 pass_with_gaps,实际 %q", res["verdict"])
}
notes, _ := res["notes"].([]string)
if !strings.Contains(strings.Join(notes, " "), "变异规则") {
t.Errorf("notes 应指出缺变异规则: %v", notes)
}
}
// ---------------- 变异执行的安全性 ----------------
// ★★★ 判据:变异**必须恢复原文件**(否则工作目录被污染,后续全乱)。
func TestMutationAlwaysRestoresFile(t *testing.T) {
p := newTestPluginForCriteria(t)
dir := writeRepo(t, false)
orig, _ := os.ReadFile(filepath.Join(dir, "calc.go"))
c := &Criteria{
ID: "c", ProjectID: "probe", Name: "n", Kind: "unit",
Script: "go test ./...",
Mutations: []Mutation{
{ID: "M1", File: "calc.go", Old: "\treturn b\n}", New: "\treturn a\n}"},
},
}
_, _, hardErr := p.runCriteriaMutate(c, dir)
if hardErr {
t.Fatal("不该有硬错误")
}
after, err := os.ReadFile(filepath.Join(dir, "calc.go"))
if err != nil {
t.Fatal(err)
}
if string(after) != string(orig) {
t.Fatalf("★ 变异后**未恢复**原文件 —— 工作目录被污染\n前:\n%s\n后:\n%s", orig, after)
}
}
// ★★ 判据:`old` 出现 **0 次或多次**都必须报硬错误(不能算"咬住")。
//
// 为何重要:
//
// · 0 次 ⇒ 变异无效,"判据没报红"是**假警报**(其实判据没问题)
// · 多次 ⇒ 可能改错地方,"判据报红"是**假通过**(改的不是想改的那处)
func TestMutationRequiresUniqueMatch(t *testing.T) {
p := newTestPluginForCriteria(t)
dir := writeRepo(t, false)
c := &Criteria{ID: "c", ProjectID: "probe", Name: "n", Kind: "unit", Script: "true"}
// ① old 不存在
c.Mutations = []Mutation{{ID: "M1", File: "calc.go", Old: "NOT_PRESENT_ANYWHERE", New: "x"}}
caught, note, hardErr := p.runOneMutation(c, c.Mutations[0], dir)
if !hardErr {
t.Fatal("★ old 不存在时报硬错误 —— 否则『变异无效』会被误判成『判据太松』(假警报)")
}
if caught {
t.Error("硬错误时不该算咬住")
}
if !strings.Contains(note, "找不到") {
t.Errorf("说明应指出找不到片段: %s", note)
}
// ② old 出现多次
multi := filepath.Join(dir, "multi.go")
os.WriteFile(multi, []byte("package calc\n\nvar a = 1\nvar b = 1\n"), 0o644)
c.Mutations = []Mutation{{ID: "M2", File: "multi.go", Old: "= 1", New: "= 2"}}
_, note2, hardErr2 := p.runOneMutation(c, c.Mutations[0], dir)
if !hardErr2 {
t.Fatal("★ old 出现多次时报硬错误 —— 否则可能改错地方却报『咬住』(假通过)")
}
if !strings.Contains(note2, "出现 2 次") {
t.Errorf("说明应指出出现次数: %s", note2)
}
}
// ★ 判据:恢复失败/内容不一致 ⇒ 硬错误(**响亮**,不静默继续)。
func TestMutationDetectsRestoreMismatch(t *testing.T) {
p := newTestPluginForCriteria(t)
dir := writeRepo(t, false)
// 只读文件 ⇒ 写入变异会失败 ⇒ 硬错误
ro := filepath.Join(dir, "ro.go")
os.WriteFile(ro, []byte("package calc\n\nvar x = 1\n"), 0o444)
if os.Geteuid() == 0 {
t.Skip("root 下只读文件仍可写,跳过")
}
c := &Criteria{ID: "c", ProjectID: "probe", Name: "n", Kind: "unit", Script: "true"}
m := Mutation{ID: "M1", File: "ro.go", Old: "= 1", New: "= 2"}
if _, _, hardErr := p.runOneMutation(c, m, dir); !hardErr {
t.Fatal("写不进去时报硬错误")
}
}
// ---------------- 真机端到端(真实 go test) ----------------
// ★★ 判据:**真实 go test** 下,正反两阶段的结果符合预期。
//
// 上面几条用真实 git/go 项目;这一条额外确认「Go 的**测试缓存**不会
// 让变异失效」—— 实测过:变异后若命中缓存,测试根本没跑,
// "报红"就无从谈起。实现里用 `-count=1` 规避。
func TestReviewDoesNotHitGoTestCache(t *testing.T) {
if _, err := exec.LookPath("go"); err != nil {
t.Skip("环境无 go")
}
p := newTestPluginForCriteria(t)
dir := writeRepo(t, false)
// 先跑一次让缓存热起来
code, _ := runShell(dir, "go test -count=1 ./...", 120)
if code != 0 {
t.Skipf("前置 go test 未通过(环境问题),跳过: %d", code)
}
p.ledger.Projects["probe"] = &Project{Name: "probe", RemoteURL: "x"}
p.ledger.Branches["br-1"] = &Branch{ID: "br-1", ProjectID: "probe", Name: "feat/x", Workdir: dir, Status: "open"}
p.ledger.Criteria["cr-1"] = &Criteria{
ID: "cr-1", ProjectID: "probe", Name: "严判据", Kind: "unit",
Script: "go test -count=1 ./...",
Mutations: []Mutation{{
ID: "M1", File: "calc.go",
Old: "\treturn b\n}", New: "\treturn a\n}",
Note: "b>a 分支",
}},
DefHash: "x",
}
res, err := p.reviewAll("br-1")
if err != nil {
t.Fatal(err)
}
if !res["mutate_ok"].(bool) {
ev := ""
if rep, ok := res["report"].([]map[string]interface{}); ok && len(rep) > 0 {
ev = str(rep[0], "mutate_evidence")
}
t.Fatalf("★ 变异未被咬住 —— 可能是 Go 测试缓存导致变异后测试没真跑\n%s", ev)
}
t.Log("✅ 真实 go test 下变异被正确咬住(未受缓存影响)")
}