mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 14:27:30 +00:00
* 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>
191 lines
6.8 KiB
Go
191 lines
6.8 KiB
Go
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"])
|
||
}
|