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-31 14:27:30 +00:00 · 2026-10-17 19:44:15 +08:00
parent 65d2bd9e61
commit 81a3efa4df
91 changed files with 21184 additions and 224 deletions
--- a/example/commondev/pi_tools.go
+++ b/example/commondev/pi_tools.go
@ -0,0 +1,664 @@
+package main
+
+// pi 配置面工具补全（审计发现项）。
+//
+// 设计 §3.6.4 明确：**插件是 pi 配置系统的受控入口** —— 写的就是 pi 自己的
+// 配置文件，不造中间层。§3.6.3 已定的落地方式：
+//
+//	<agentdir>/models.json    providers.<name>.{baseUrl,api,apiKey,models[]}
+//	<agentdir>/auth.json      provider 凭据
+//	<agentdir>/settings.json  defaultProvider / defaultModel
+//
+// 四条实现纪律（§3.6.4）：
+//  1. 写的就是 pi 的配置文件，格式与 pi 自己写出来的一致
+//     （否则 pi 重写文件时会把我们的字段抹掉）
+//  2. **改前备份、改后校验**：json 写坏会让内层 pi 起不来；
+//     校验失败则**回滚并响亮报错**
+//  3. key 不进日志、不进返回值
+//  4. **不改用户全局**：一律带 PI_CODING_AGENT_DIR
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+// loadPiModels 读 pi 的 models.json（不存在则返回空结构）。
+func loadPiModels(agentDir string) (*piModelsFile, error) {
+	out := &piModelsFile{Providers: map[string]*piProvider{}}
+	b, err := os.ReadFile(filepath.Join(agentDir, "models.json"))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return out, nil
+		}
+		return nil, err
+	}
+	if err := json.Unmarshal(b, out); err != nil {
+		// 坏文件必须响亮报错：静默当空会**抹掉用户已有的源**
+		return nil, fmt.Errorf("models.json 已损坏（拒绝覆盖，先人工修复）: %w", err)
+	}
+	if out.Providers == nil {
+		out.Providers = map[string]*piProvider{}
+	}
+	return out, nil
+}
+
+// loadPiAuth 读 pi 的 auth.json（不存在则返回空）。
+//
+// ★ 用 map[string]interface{} 而不是 map[string]map[string]string：
+// 后者把每个 provider 的 entry 当成**扁平字符串表**，于是只能写出
+// `{"apiKey": "..."}` —— 而 pi 认的是 `{"type":"api_key","key":"..."}`
+// （权威定义见 pi 的 dist/core/auth-storage.js:
+//
+//	`if (value.type === "api_key")` 与 model-runtime.js 的
+//	`{ type: "api_key", key: apiKey }`）。
+//
+// 格式不符的后果是**完全静默**的：pi 的 auth 读取返回空 ⇒
+// `Provider is not configured: <name>`，而配置看起来完全正常。
+// 实测（2026-10-15）：内嵌 pi 因此谁都调不动，只改这个格式即恢复。
+func loadPiAuth(agentDir string) (map[string]interface{}, error) {
+	out := map[string]interface{}{}
+	b, err := os.ReadFile(filepath.Join(agentDir, "auth.json"))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return out, nil
+		}
+		return nil, err
+	}
+	if err := json.Unmarshal(b, &out); err != nil {
+		return nil, fmt.Errorf("auth.json 已损坏（拒绝覆盖）: %w", err)
+	}
+	return out, nil
+}
+
+// handlePiSourceAdd 添加/更新一个 LLM 源（直接写 pi 的配置文件）。
+//
+// 纪律 2：**先备份**，写完回读校验，失败回滚。
+func (p *Plugin) handlePiSourceAdd(args map[string]interface{}) (interface{}, error) {
+	name := strings.TrimSpace(str(args, "name"))
+	baseURL := strings.TrimSpace(str(args, "base_url"))
+	model := strings.TrimSpace(str(args, "model"))
+	if name == "" || baseURL == "" || model == "" {
+		return map[string]interface{}{"error": "name、base_url、model 必填"}, nil
+	}
+	if !validName(name) {
+		return map[string]interface{}{"error": "name 只允许 [A-Za-z0-9_-]（会成为 JSON 的键名）"}, nil
+	}
+	adapter := strings.TrimSpace(str(args, "adapter"))
+	api := adapterToAPI(adapter)
+	if api == "" {
+		return map[string]interface{}{
+			"error": fmt.Sprintf("adapter=%q 无法映射到 pi 的 api（已知：openai/anthropic）——不猜默认值", adapter),
+		}, nil
+	}
+
+	agentDir := p.piAgentDir()
+	backup, err := backupPiConfig(agentDir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+
+	models, err := loadPiModels(agentDir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	auth, err := loadPiAuth(agentDir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+
+	apiKey := str(args, "api_key")
+	m := piModel{ID: model, Name: model, Input: []string{"text"}}
+	if cw := int(numArg(args, "context_window")); cw > 0 {
+		m.ContextWindow = cw
+	}
+	if mt := int(numArg(args, "max_tokens")); mt > 0 {
+		m.MaxTokens = mt
+	}
+	if v, ok := args["vision"].(bool); ok && v {
+		m.Input = []string{"text", "image"}
+	}
+	if rb, ok := args["reasoning"].(bool); ok && rb {
+		m.Reasoning = true
+	}
+	models.Providers[name] = &piProvider{
+		BaseURL: baseURL, API: api, APIKey: apiKey, Models: []piModel{m},
+	}
+	if strings.TrimSpace(apiKey) != "" {
+		if auth == nil {
+			auth = map[string]interface{}{}
+		}
+		auth[name] = newPiAuthEntry(apiKey)
+	}
+
+	if err := p.writePiConfigs(agentDir, models, auth); err != nil {
+		rollbackPiConfig(agentDir, backup)
+		return map[string]interface{}{"error": "写入失败，已回滚: " + err.Error()}, nil
+	}
+	// ★ 返回值里**没有 key**（纪律 3）
+	return map[string]interface{}{
+		"status": "ok", "provider": name, "base_url": baseURL,
+		"api": api, "model": model,
+		"key_set": strings.TrimSpace(apiKey) != "",
+		"backup":  backup,
+	}, nil
+}
+
+// handlePiConfigGet 读取 pi 的配置（**key 一律脱敏**，纪律 3）。
+//
+// scope: plugin（默认，读 <agentdir>）| project（读 <workdir>/.pi）。
+func (p *Plugin) handlePiConfigGet(args map[string]interface{}) (interface{}, error) {
+	agentDir, err := p.piScopeDir(args)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	models, err := loadPiModels(agentDir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	providers := []map[string]interface{}{}
+	names := make([]string, 0, len(models.Providers))
+	for n := range models.Providers {
+		names = append(names, n)
+	}
+	sort.Strings(names) // 固定顺序，便于对照
+	for _, n := range names {
+		pv := models.Providers[n]
+		modelsOut := make([]string, 0, len(pv.Models))
+		for _, m := range pv.Models {
+			modelsOut = append(modelsOut, m.ID)
+		}
+		providers = append(providers, map[string]interface{}{
+			"name": n, "base_url": pv.BaseURL, "api": pv.API,
+			"models": modelsOut,
+			// ★ 只报"是否配了 key"，不返回值
+			"key_set": strings.TrimSpace(pv.APIKey) != "",
+		})
+	}
+	var settings map[string]interface{}
+	if b, err := os.ReadFile(filepath.Join(agentDir, "settings.json")); err == nil {
+		_ = json.Unmarshal(b, &settings)
+	}
+	out := map[string]interface{}{
+		"scope_dir":      agentDir,
+		"providers":      providers,
+		"count":          len(providers),
+		"settings":       settings,
+		"key_discipline": "api_key 绝不返回（与 commondev_account_list 同一条纪律）",
+	}
+	return out, nil
+}
+
+// handlePiPackageInstall 为内置 pi 装一个扩展包（pi install）。
+//
+// 设计 §3.5.2 的两种粒度：plugin（全局，装进 agentdir）/ project（装进工作目录）。
+// ★ 不擅自安装：命令与来源都显式要求，且安装失败要响亮报错。
+func (p *Plugin) handlePiPackageInstall(args map[string]interface{}) (interface{}, error) {
+	source := strings.TrimSpace(str(args, "source"))
+	if source == "" {
+		return map[string]interface{}{"error": "source 必填（如 npm:@foo/bar、git:github.com/u/r）"}, nil
+	}
+	scope := strings.TrimSpace(str(args, "scope"))
+	if scope == "" {
+		scope = "plugin"
+	}
+	agentDir, err := p.piScopeDir(map[string]interface{}{
+		"scope": scope, "workdir": str(args, "workdir"),
+	})
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	piBin := p.piBin()
+
+	argv := []string{"install", source}
+	dir := agentDir
+	if scope == "project" {
+		argv = append(argv, "-l") // pi 的 project-local 开关
+		dir = strings.TrimSpace(str(args, "workdir"))
+		if dir == "" {
+			return map[string]interface{}{"error": "scope=project 时必须给 workdir"}, nil
+		}
+	}
+
+	cmd := exec.Command(piBin, argv...)
+	cmd.Dir = dir
+	// ★ 纪律 4：绝不改用户全局（一律指向插件自己的 agentdir）
+	cmd.Env = append(os.Environ(), "PI_CODING_AGENT_DIR="+agentDir)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		// 不吞输出：pi 的报错（来源不存在、网络不通）是唯一线索
+		return map[string]interface{}{
+			"status": "failed", "error": err.Error(),
+			"output": truncate(string(out), 800),
+		}, nil
+	}
+	return map[string]interface{}{
+		"status": "ok", "source": source, "scope": scope,
+		"dir": dir, "output": truncate(string(out), 800),
+	}, nil
+}
+
+// piScopeDir 解析 scope 到具体目录（纪律 4：带显式 agentdir）。
+func (p *Plugin) piScopeDir(args map[string]interface{}) (string, error) {
+	scope := strings.TrimSpace(str(args, "scope"))
+	if scope == "" {
+		scope = "plugin"
+	}
+	switch scope {
+	case "plugin":
+		return p.piAgentDir(), nil
+	case "project":
+		wd := strings.TrimSpace(str(args, "workdir"))
+		if wd == "" {
+			return "", fmt.Errorf("scope=project 时必须给 workdir")
+		}
+		abs, err := filepath.Abs(wd)
+		if err != nil {
+			return "", err
+		}
+		if !p.isInsideProgramRoot(abs) {
+			return "", fmt.Errorf("project scope 的 workdir 必须在 program/ 工程目录下")
+		}
+		return filepath.Join(abs, ".pi"), nil
+	default:
+		return "", fmt.Errorf("scope 只能是 plugin | project")
+	}
+}
+
+// piBin 定位内置 pi 可执行文件。
+func (p *Plugin) piBin() string {
+	if v, _ := p.sdk.Settings().Get("pi_bin"); v != nil {
+		if s, _ := v.(string); strings.TrimSpace(s) != "" {
+			return s
+		}
+	}
+	if cand := filepath.Join(filepath.Dir(p.path), "runtime", "pi"); fileExists(cand) {
+		return cand
+	}
+	if cand, err := exec.LookPath("pi"); err == nil {
+		return cand
+	}
+	return "pi" // 交给 exec 报"找不到"
+}
+
+// ---------------- 改前备份 / 失败回滚（纪律 2） ----------------
+
+// backupPiConfig 把 agentDir 下的 pi 配置文件备份成一个时间戳快照。
+func backupPiConfig(agentDir string) (string, error) {
+	stamp := fmt.Sprintf("%d", time.Now().UnixNano())
+	dir := filepath.Join(agentDir, ".backup-"+stamp)
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return "", err
+	}
+	n := 0
+	for _, f := range []string{"models.json", "auth.json", "settings.json"} {
+		src := filepath.Join(agentDir, f)
+		b, err := os.ReadFile(src)
+		if err != nil {
+			continue // 不存在就不用备份
+		}
+		if err := writeFile0600(filepath.Join(dir, f), b); err != nil {
+			return "", err
+		}
+		n++
+	}
+	if n == 0 {
+		// 没什么可备份：建一个空目录标记（回滚时删除新文件即可）
+		return dir, nil
+	}
+	return dir, nil
+}
+
+// rollbackPiConfig 用备份覆盖回去（写坏时的**响亮**兜底）。
+func rollbackPiConfig(agentDir, backupDir string) {
+	if backupDir == "" {
+		return
+	}
+	for _, f := range []string{"models.json", "auth.json", "settings.json"} {
+		src := filepath.Join(backupDir, f)
+		b, err := os.ReadFile(src)
+		if err != nil {
+			// 备份里没有 ⇒ 该文件是本次新建的，删掉即回到原状
+			_ = os.Remove(filepath.Join(agentDir, f))
+			continue
+		}
+		_ = writeFile0600(filepath.Join(agentDir, f), b)
+	}
+}
+
+// handlePiPluginList 列出已装的 pi 扩展包（分 scope）。
+func (p *Plugin) handlePiPluginList(args map[string]interface{}) (interface{}, error) {
+	scope := strings.TrimSpace(str(args, "scope"))
+	agentDir := p.piAgentDir()
+	argv := []string{"list"}
+	dir := agentDir
+	env := os.Environ()
+	if scope == "project" {
+		wd := strings.TrimSpace(str(args, "workdir"))
+		if wd == "" {
+			return map[string]interface{}{"error": "scope=project 时必须给 workdir"}, nil
+		}
+		if !p.isInsideProgramRoot(wd) {
+			return map[string]interface{}{"error": "workdir 必须在 program/ 工程目录下"}, nil
+		}
+		dir = wd
+		argv = append(argv, "-l")
+	}
+	cmd := exec.Command(p.piBin(), argv...)
+	cmd.Dir = dir
+	cmd.Env = append(env, "PI_CODING_AGENT_DIR="+agentDir)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		return map[string]interface{}{
+			"status": "failed", "error": err.Error(),
+			"output": truncate(stripPiNoise(string(out)), 800),
+		}, nil
+	}
+	text := strings.TrimSpace(stripPiNoise(string(out)))
+	return map[string]interface{}{
+		"status": "ok", "scope": scopeOrDefault(scope), "dir": dir,
+		"packages": text, "count": countPiListLines(text),
+	}, nil
+}
+
+// handlePiPluginRemove 卸载一个 pi 扩展包。
+func (p *Plugin) handlePiPluginRemove(args map[string]interface{}) (interface{}, error) {
+	source := strings.TrimSpace(str(args, "source"))
+	if source == "" {
+		return map[string]interface{}{"error": "source 必填"}, nil
+	}
+	agentDir := p.piAgentDir()
+	argv := []string{"remove", source}
+	dir := agentDir
+	if strings.EqualFold(strings.TrimSpace(str(args, "scope")), "project") {
+		wd := strings.TrimSpace(str(args, "workdir"))
+		if wd == "" {
+			return map[string]interface{}{"error": "scope=project 时必须给 workdir"}, nil
+		}
+		if !p.isInsideProgramRoot(wd) {
+			return map[string]interface{}{"error": "workdir 必须在 program/ 工程目录下"}, nil
+		}
+		dir = wd
+		argv = append(argv, "-l")
+	}
+	cmd := exec.Command(p.piBin(), argv...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "PI_CODING_AGENT_DIR="+agentDir)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		return map[string]interface{}{
+			"status": "failed", "error": err.Error(),
+			"output": truncate(stripPiNoise(string(out)), 800),
+		}, nil
+	}
+	return map[string]interface{}{
+		"status": "ok", "source": source, "dir": dir,
+		"output": truncate(stripPiNoise(string(out)), 800),
+	}, nil
+}
+
+// stripPiNoise 去掉 pi 启动时那两行 A2A/ACP 端口告警。
+//
+// 为何要滤：那两行是**环境噪声**（内层 pi 尝试监听端口被占），
+// 混在结果里会让人以为安装/列出失败了。真实的错误信息不受影响。
+func stripPiNoise(s string) string {
+	var keep []string
+	for _, line := range strings.Split(s, "\n") {
+		if strings.HasPrefix(strings.TrimSpace(line), "[pi-a2a]") ||
+			strings.HasPrefix(strings.TrimSpace(line), "[pi-acp]") {
+			continue
+		}
+		keep = append(keep, line)
+	}
+	return strings.Join(keep, "\n")
+}
+
+func scopeOrDefault(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "plugin"
+	}
+	return s
+}
+
+// countPiListLines 数出已装包的行数（"No packages installed." 记 0）。
+func countPiListLines(text string) int {
+	if strings.TrimSpace(text) == "" || strings.Contains(text, "No packages installed") {
+		return 0
+	}
+	n := 0
+	for _, line := range strings.Split(text, "\n") {
+		if strings.TrimSpace(line) != "" {
+			n++
+		}
+	}
+	return n
+}
+
+// ---------------- workdir 预准备（设计 §4.1） ----------------
+
+// handleWorkdirPrepare 重新准备/修复某条分支的工作目录（幂等）。
+//
+// 与 branch_open 的区别：branch_open 是**登记一条新线**（含唯一性闸）；
+// 本工具是对**已有的线**重做目录准备 —— 目录被误删、clone 中断、需要
+// 重新从 mirror 派生时用。走后台作业（clone 可能超过 60s）。
+func (p *Plugin) handleWorkdirPrepare(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]
+	var proj *Project
+	if ok {
+		proj = p.ledger.Projects[b.ProjectID]
+	}
+	p.mu.Unlock()
+	if !ok || proj == nil {
+		return map[string]interface{}{"error": fmt.Sprintf("工程对话 %s 或其项目不存在", id)}, nil
+	}
+	jobID := fmt.Sprintf("prepare-%s-%d", id, time.Now().UnixNano()%100000)
+	p.mu.Lock()
+	p.ledger.Jobs[jobID] = &Job{
+		ID: jobID, BranchID: id, Kind: "prepare_workdir",
+		Status: "pending", StartedAt: nowRFC3339(),
+	}
+	_ = p.saveLocked()
+	p.mu.Unlock()
+
+	go p.runPrepareWorkdir(jobID, id, proj, b.Name, b.Workdir, b.Runtime, b.SSHHost)
+	return map[string]interface{}{
+		"status": "ok", "job_id": jobID, "workdir": b.Workdir,
+		"next": "用 commondev_job_status 查进度",
+	}, nil
+}
+
+// handlePiConfigSet 设置 pi settings.json 的一个顶层键（直接落盘，带备份/校验）。
+func (p *Plugin) handlePiConfigSet(args map[string]interface{}) (interface{}, error) {
+	key := strings.TrimSpace(str(args, "key"))
+	if key == "" {
+		return map[string]interface{}{"error": "key 必填"}, nil
+	}
+	dir, err := p.piScopeDir(args)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	backup, err := backupPiConfig(dir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	path := filepath.Join(dir, "settings.json")
+	cur := map[string]interface{}{}
+	if b, readErr := os.ReadFile(path); readErr == nil {
+		if err := json.Unmarshal(b, &cur); err != nil {
+			return map[string]interface{}{"error": fmt.Sprintf("settings.json 已损坏（拒绝覆盖）: %v", err)}, nil
+		}
+	} else if !os.IsNotExist(readErr) {
+		return map[string]interface{}{"error": readErr.Error()}, nil
+	}
+	raw := strings.TrimSpace(str(args, "value"))
+	if raw == "" {
+		return map[string]interface{}{"error": "value 必填（JSON 值或普通字符串）"}, nil
+	}
+	var value interface{}
+	if err := json.Unmarshal([]byte(raw), &value); err != nil {
+		value = raw
+	}
+	cur[key] = value
+	b, err := json.MarshalIndent(cur, "", "  ")
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	if err := writeFile0600(path, b); err != nil {
+		rollbackPiConfig(dir, backup)
+		return map[string]interface{}{"error": "写入失败，已回滚: " + err.Error()}, nil
+	}
+	var verify map[string]interface{}
+	if b2, err := os.ReadFile(path); err != nil || json.Unmarshal(b2, &verify) != nil {
+		rollbackPiConfig(dir, backup)
+		return map[string]interface{}{"error": "写后校验失败，已回滚"}, nil
+	}
+	return map[string]interface{}{"status": "ok", "scope": scopeOrDefault(str(args, "scope")), "key": key}, nil
+}
+
+// runPiMCP 是 pi mcp 命令的受控包装（所有写入仍落 pi 自己的 mcp.json）。
+func (p *Plugin) runPiMCP(args []string, workdir string) (interface{}, error) {
+	agentDir := p.piAgentDir()
+	cmd := exec.Command(p.piBin(), append([]string{"mcp"}, args...)...)
+	cmd.Dir = workdir
+	cmd.Env = append(os.Environ(), "PI_CODING_AGENT_DIR="+agentDir)
+	out, err := cmd.CombinedOutput()
+	clean := truncate(stripPiNoise(string(out)), 1200)
+	if err != nil {
+		return map[string]interface{}{"status": "failed", "error": err.Error(), "output": clean}, nil
+	}
+	return map[string]interface{}{"status": "ok", "output": clean}, nil
+}
+
+func (p *Plugin) mcpWorkdir(args map[string]interface{}) (string, error) {
+	scope := scopeOrDefault(str(args, "scope"))
+	if scope == "plugin" {
+		return p.piAgentDir(), nil
+	}
+	wd := strings.TrimSpace(str(args, "workdir"))
+	if wd == "" || !p.isInsideProgramRoot(wd) {
+		return "", fmt.Errorf("scope=project 时 workdir 必须在 program/ 工程目录下")
+	}
+	return wd, nil
+}
+
+func (p *Plugin) handlePiMCPList(args map[string]interface{}) (interface{}, error) {
+	wd, err := p.mcpWorkdir(args)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	return p.runPiMCP([]string{"list", "--json"}, wd)
+}
+
+func (p *Plugin) handlePiMCPAdd(args map[string]interface{}) (interface{}, error) {
+	name, source := strings.TrimSpace(str(args, "name")), strings.TrimSpace(str(args, "source"))
+	if name == "" || source == "" {
+		return map[string]interface{}{"error": "name 与 source 必填"}, nil
+	}
+	wd, err := p.mcpWorkdir(args)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	argv := []string{"add", name}
+	if scopeOrDefault(str(args, "scope")) == "project" {
+		argv = append(argv, "--local")
+	}
+	if url := strings.TrimSpace(str(args, "url")); url != "" {
+		argv = append(argv, "--url", url)
+	} else {
+		// source 是命令及其参数的 JSON 数组，避免 shell 重新解析/注入。
+		var command []string
+		if err := json.Unmarshal([]byte(source), &command); err != nil || len(command) == 0 {
+			return map[string]interface{}{"error": "source 必须是 JSON 字符串数组（stdio），或另填 url"}, nil
+		}
+		argv = append(argv, "--")
+		argv = append(argv, command...)
+	}
+	return p.runPiMCP(argv, wd)
+}
+
+func (p *Plugin) handlePiMCPRemove(args map[string]interface{}) (interface{}, error) {
+	name := strings.TrimSpace(str(args, "name"))
+	if name == "" {
+		return map[string]interface{}{"error": "name 必填"}, nil
+	}
+	wd, err := p.mcpWorkdir(args)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	argv := []string{"remove", name}
+	if scopeOrDefault(str(args, "scope")) == "project" {
+		argv = append(argv, "--local")
+	}
+	return p.runPiMCP(argv, wd)
+}
+
+// handlePiSourceRemove 删除一个 provider 及其 auth 记录。
+func (p *Plugin) handlePiSourceRemove(args map[string]interface{}) (interface{}, error) {
+	name := strings.TrimSpace(str(args, "name"))
+	if name == "" {
+		return map[string]interface{}{"error": "name 必填"}, nil
+	}
+	dir := p.piAgentDir()
+	backup, err := backupPiConfig(dir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	models, err := loadPiModels(dir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	if _, ok := models.Providers[name]; !ok {
+		return map[string]interface{}{"error": "源不存在: " + name}, nil
+	}
+	delete(models.Providers, name)
+	auth, err := loadPiAuth(dir)
+	if err != nil {
+		return map[string]interface{}{"error": err.Error()}, nil
+	}
+	delete(auth, name)
+	if err := p.writePiConfigs(dir, models, auth); err != nil {
+		rollbackPiConfig(dir, backup)
+		return map[string]interface{}{"error": "删除失败，已回滚: " + err.Error()}, nil
+	}
+	return map[string]interface{}{"status": "ok", "removed": name}, nil
+}
+
+// handlePiPluginUpdate 更新一个已安装的 pi 扩展；未指定 source 时更新全部。
+func (p *Plugin) handlePiPluginUpdate(args map[string]interface{}) (interface{}, error) {
+	agentDir := p.piAgentDir()
+	dir := agentDir
+	argv := []string{"update"}
+	if source := strings.TrimSpace(str(args, "source")); source != "" {
+		argv = append(argv, source)
+	}
+	if scopeOrDefault(str(args, "scope")) == "project" {
+		wd := strings.TrimSpace(str(args, "workdir"))
+		if wd == "" || !p.isInsideProgramRoot(wd) {
+			return map[string]interface{}{"error": "scope=project 时 workdir 必须在 program/ 工程目录下"}, nil
+		}
+		dir = wd
+		argv = append(argv, "-l")
+	}
+	cmd := exec.Command(p.piBin(), argv...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "PI_CODING_AGENT_DIR="+agentDir)
+	out, err := cmd.CombinedOutput()
+	result := map[string]interface{}{"scope": scopeOrDefault(str(args, "scope")), "dir": dir, "output": truncate(stripPiNoise(string(out)), 800)}
+	if err != nil {
+		result["status"] = "failed"
+		result["error"] = err.Error()
+		return result, nil
+	}
+	result["status"] = "ok"
+	return result, nil
+}