@iamlbccc/tdxd 1.1.1 → 1.2.0

package/tdxd-ctl.mjs

@@ -6,11 +6,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import net from "node:net";
 import crypto from "node:crypto";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { ask, confirm, select, out, closePrompt } from "./lib/ui.mjs";
-import { configTpl, opencodeJsonTpl, agentsMdTpl } from "./lib/tpl.mjs";
+import { out, ok, fail, warn, note, head, cell, table, tGreen, tRed, tYellow, tDim, tCyan, tBold, dispWidth } from "./lib/ui.mjs";
+import { configTpl, detectModel } from "./lib/tpl.mjs";
 
 const HOME = process.env.TDXD_HOME || path.join(os.homedir(), ".tdx");
 const AGENTS_DIR = path.join(HOME, "agents");
@@ -34,10 +35,10 @@ function listAgents() {
 
 function pick(target) {
   const agents = listAgents();
-  if (agents.length === 0) { out(`[ctl] 无实例（查 ${AGENTS_DIR}/；初始化用 tdxd-ctl init <name>）`); process.exit(0); }
+  if (agents.length === 0) { warn(`无实例（查 ${AGENTS_DIR}/；初始化用 tdxd-ctl init <name>）`); process.exit(0); }
   if (target === "all") return agents;
   const a = agents.find((x) => x.name === target);
-  if (!a) { out(`[ctl] ✗ 未找到实例 "${target}"。现有: ${agents.map((x) => x.name).join(", ")}`); process.exit(1); }
+  if (!a) { fail(`未找到实例 "${target}"。现有: ${agents.map((x) => x.name).join(", ")}`); process.exit(1); }
   return [a];
 }
 
@@ -86,83 +87,328 @@ function lanIp() {
   return "127.0.0.1";
 }
 
-function suggestPort() {
+/** shell 式 ~ 展开（Node 不会自动做；交互输入与 flags 均经过此处） */
+function expandHome(p) {
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+/** 实际绑定探测：防"孤儿 daemon（目录已删进程还在）"占用导致 start 阶段 EADDRINUSE */
+function canBind(port, host = "0.0.0.0") {
+  return new Promise((res) => {
+    const srv = net.createServer();
+    srv.once("error", () => res(false));
+    srv.once("listening", () => srv.close(() => res(true)));
+    srv.listen(port, host);
+  });
+}
+
+async function suggestPort() {
   const used = new Set(listAgents().map((a) => a.cfg?.port).filter(Boolean));
-  for (let p = 18200; p < 18300; p++) if (!used.has(p)) return p;
+  for (let p = 18200; p < 18300; p++) if (!used.has(p) && (await canBind(p))) return p;
   return 18300;
 }
 
-// ---------- init ----------
-async function cmdInit(flags, positionalName) {
-  out();
-  out("\x1b[1mTDX-Daemon Agent 初始化\x1b[0m");
-  out("\x1b[2m──────────────────────────\x1b[0m");
-  const y = flags.yes;
-
-  let name = flags.name || positionalName;
-  if (!name && !y) name = await ask("Agent 标识（slug，小写字母/数字/-）");
-  if (!name) { out("[ctl] ✗ 缺 name（--name 或位置参数，或交互输入）"); process.exit(1); }
-  if (!NAME_RE.test(name)) { out(`[ctl] ✗ 非法 name "${name}"（须匹配 ${NAME_RE}）`); process.exit(1); }
+// ---------- skills（快照随包内置，发布时从上游 paperclip 仓库 vendor；重复 --add = 覆盖升级） ----------
+const SKILLS_SRC = path.join(path.dirname(fileURLToPath(import.meta.url)), "skills");
+
+function wsSkillsDir(a) { return path.join(a.cfg.workspace, ".opencode", "skills"); }
+
+function doAddSkill(a, name) {
+  const bundled = fs.existsSync(SKILLS_SRC) ? fs.readdirSync(SKILLS_SRC).filter((n) => fs.existsSync(path.join(SKILLS_SRC, n, "SKILL.md"))) : [];
+  if (!bundled.includes(name)) {
+    fail(`无内置 skill "${name}"。可选: ${bundled.join(", ")}`);
+    return false;
+  }
+  const dst = path.join(wsSkillsDir(a), name);
+  fs.mkdirSync(wsSkillsDir(a), { recursive: true });
+  fs.rmSync(dst, { recursive: true, force: true });
+  fs.cpSync(path.join(SKILLS_SRC, name), dst, { recursive: true });
+  return true; // 静默：成功输出由调用方决定
+}
+
+function cmdSkills(target, flags) {
+  const [a] = pick(target);
+  if (!a) return;
+  const bundled = fs.existsSync(SKILLS_SRC) ? fs.readdirSync(SKILLS_SRC).filter((n) => fs.existsSync(path.join(SKILLS_SRC, n, "SKILL.md"))) : [];
+  const installedDir = wsSkillsDir(a);
+  const installed = fs.existsSync(installedDir) ? fs.readdirSync(installedDir).filter((n) => fs.existsSync(path.join(installedDir, n, "SKILL.md"))) : [];
+
+  if (flags.rm) {
+    const d = path.join(installedDir, flags.rm);
+    if (!fs.existsSync(d)) { fail(`未安装 skill "${flags.rm}"`); process.exitCode = 1; return; }
+    fs.rmSync(d, { recursive: true, force: true });
+    ok(`已移除 ${flags.rm} ${tDim(d)}`);
+    return;
+  }
+
+  if (flags.add) {
+    if (doAddSkill(a, flags.add)) {
+      note(`新装 skill 由 opencode 下次会话加载；首问如未生效请 tdxd-ctl restart ${a.name}`);
+    } else process.exitCode = 1;
+    return;
+  }
+
+  out(`${tBold(a.name)} 的 skills  ${tDim(installedDir)}`);
+  const all = [...new Set([...installed, ...bundled])];
+  if (all.length === 0) { warn("无已装，包内也无内置——异常，请重装 tdxd"); return; }
+  table(["SKILL", "状态", "说明"], all.map((s) => [
+    cell(s, s === "paperclip" ? "cyan" : undefined),
+    cell(installed.includes(s) ? "已装" : "未装", installed.includes(s) ? "green" : "dim"),
+    cell(s === "paperclip" ? "核心：平台心跳能力（checkout→干活→PATCH），必装" : (s === "paperclip-converting-plans-to-tasks" ? "计划→子任务→分派" : "（手工放置）"), "dim"),
+  ]));
+  note(`操作：tdxd-ctl skills ${a.name} --add <skill> | --rm <skill>`);
+}
+
+// ---------- key（平台铸造的 agent key 回填，供 daemon 兜底回调） ----------
+function writeAgentKey(dir, key) {
+  const f = path.join(dir, "secret.env");
+  const lines = fs.existsSync(f) ? fs.readFileSync(f, "utf8").split("\n") : [];
+  const kept = lines.filter((l) => !/^TDXD_PAPERCLIP_KEY=/.test(l) && !l.startsWith("# 平台回调") && !/^#\s*TDXD_PAPERCLIP_KEY=/.test(l));
+  if (key) kept.splice(1, 0, `TDXD_PAPERCLIP_KEY=${key}`); // 紧跟 token 行
+  fs.writeFileSync(f, kept.filter((l, i, arr) => l !== "" || i === arr.length - 1).join("\n").replace(/\n*$/, "\n"), { mode: 0o600 });
+  return f;
+}
+
+function cmdKey(target, flags) {
+  const [a] = pick(target);
+  if (!a) return;
+  if (!flags.set && !flags.rm) {
+    fail("缺参数：--set <pcp_xxx> 或 --rm（AI/脚本调用，无交互）");
+    process.exit(1);
+  }
+  const f = writeAgentKey(a.dir, flags.rm ? "" : flags.set);
+  if (flags.rm) { ok(`已移除 ${a.name} 的 agent key（回调将降级为未配置）`); }
+  else { ok(`已写入 agent key → ${tDim(f)}`); }
+  note(`重启生效：tdxd-ctl restart ${a.name}（status 应显示 回调:启用）`);
+}
+
+// ---------- init 核心（cmdInit 与 onboard 共用；纯参数化，无交互无输出副作用） ----------
+async function initCore(flags, name) {
+  if (!name) { fail("缺 name：--name <slug> 或位置参数（无交互模式）"); process.exit(1); }
+  if (!NAME_RE.test(name)) { fail(`非法 name "${name}"（须匹配 ${NAME_RE}）`); process.exit(1); }
   const dir = path.join(AGENTS_DIR, name);
   if (fs.existsSync(path.join(dir, "config.json")) && !flags.force) {
-    out(`[ctl] ✗ 实例已存在：${dir}（--force 覆盖）`); process.exit(1);
+    fail(`实例已存在：${dir}（--force 覆盖）`); process.exit(1);
   }
 
-  const displayName = flags.display || (y ? name : await ask("显示名", name));
-  const persona = flags.persona || (y ? "coder" : (await select("角色模板", [
-    { value: "coder", label: "开发工程师", description: "读码-改动-验证-汇报" },
-    { value: "manager", label: "团队负责人", description: "拆任务/分派/跟踪/汇总" },
-    { value: "qa", label: "测试工程师", description: "用例设计/如实报告" },
-    { value: "blank", label: "空白模板", description: "自己写 AGENTS.md" },
-  ])).value);
-  const model = flags.model || (y ? "kimi-for-coding/kimi-for-coding" : await ask("模型（provider/model）", "kimi-for-coding/kimi-for-coding"));
+  const displayName = flags.display || name;
   const homeWs = path.join(os.homedir(), "workspaces", name);
-  const workspace = path.resolve(flags.workspace || (y ? homeWs : await ask("workspace 路径", homeWs)));
-  const port = Number(flags.port || (y ? suggestPort() : Number(await ask("端口", String(suggestPort())))));
-  const url = flags.url || (y ? "http://127.0.0.1:3100" : await ask("Paperclip 平台地址", "http://127.0.0.1:3100"));
-
-  let token = flags.token;
-  if (!token) {
-    const auto = y ? true : await confirm("自动生成共享 token?", true);
-    token = auto ? `tok-${crypto.randomBytes(16).toString("hex")}` : await ask("自定义 token");
-    if (!token) { out("[ctl] ✗ token 不能为空"); process.exit(1); }
-  }
+  const workspace = path.resolve(expandHome(flags.workspace || homeWs));
+  let port;
+  if (flags.port) {
+    port = Number(flags.port);
+    if (!(await canBind(port))) warn(`端口 ${port} 当前被占用（可能孤儿进程），start 阶段可能失败`);
+  } else port = await suggestPort();
+  const url = flags.url || "http://127.0.0.1:3100";
+  const clash = listAgents().find((x) => x.name !== name && x.cfg?.port === port);
+  if (clash) warn(`端口 ${port} 与实例 "${clash.name}" 冲突，同机共存将互相干扰`);
+
+  const token = flags.token || `tok-${crypto.randomBytes(16).toString("hex")}`;
+  const model = detectModel(workspace);
+  const wsExists = fs.existsSync(workspace);
 
-  // 落盘
   fs.mkdirSync(path.join(dir, "log"), { recursive: true });
   fs.mkdirSync(path.join(dir, "run"), { recursive: true });
-  fs.writeFileSync(path.join(dir, "config.json"), configTpl({ name, displayName, port, workspace, model, url }));
+  fs.writeFileSync(path.join(dir, "config.json"), configTpl({ displayName, port, workspace, url }));
   fs.writeFileSync(path.join(dir, "secret.env"), `TDXD_TOKEN=${token}\n# 平台回调用 agent key（UI 铸造后填入，选填）\n# TDXD_PAPERCLIP_KEY=pcp_xxx\n`, { mode: 0o600 });
-  fs.mkdirSync(path.join(workspace, ".opencode"), { recursive: true });
-  const oc = path.join(workspace, ".opencode", "opencode.json");
-  if (!fs.existsSync(oc)) fs.writeFileSync(oc, opencodeJsonTpl(model));
-  const am = path.join(workspace, "AGENTS.md");
-  if (!fs.existsSync(am)) fs.writeFileSync(am, agentsMdTpl(persona, displayName));
 
+  // skills 静默装配：已存在保留，缺失补装
+  const skillList = flags.skills === "none" ? [] : String(flags.skills || "paperclip,paperclip-converting-plans-to-tasks").split(",").map((x) => x.trim()).filter(Boolean);
+  const skillResults = [];
+  for (const s of skillList) {
+    const dst = path.join(workspace, ".opencode", "skills", s);
+    if (fs.existsSync(path.join(dst, "SKILL.md"))) { skillResults.push(`${s}（已存在，保留）`); continue; }
+    skillResults.push(doAddSkill({ cfg: { workspace } }, s) ? s : s);
+  }
+  return { name, displayName, dir, workspace, port, url, token, model, wsExists, skillResults };
+}
+
+// ---------- init（纯 flags，无交互——面向 AI 调用/脚本化） ----------
+async function cmdInit(flags, positionalName) {
+  // 全流程地图：首次使用者（人或 AI）一眼看清 4 步接线和验收在哪一步
   out();
-  out("\x1b[32m✓ 实例就绪\x1b[0m");
-  out(`  ${dir}`);
-  out(`  ${workspace}`);
+  head("TDX-Daemon Agent 接入");
+  out(`  ${tGreen("[1]")} init 创建实例 + 装配 skills   ${tDim("← 本命令，现在执行")}`);
+  out(`  ${tDim("[2]")} start 启动并自检`);
+  out(`  ${tDim("[3]")} 平台 UI hire（endpoint + token）`);
+  out(`  ${tDim("[4]")} 铸 agent key 回填（tdxd-ctl key / onboard 自动）`);
+  out(`  ${tDim("验收：/health 探活 → 真实唤醒一轮 → 第二轮日志 resume=true")}`);
   out();
-  out("\x1b[1m接下来：\x1b[0m");
-  out(`  1. 启动并自检:   \x1b[36mtdxd-ctl start ${name} && tdxd-ctl status ${name}\x1b[0m`);
-  out("  2. 平台 UI hire Agent（TDX-Adapter），粘贴以下参数：");
-  out(`     adapterType:  tdx_adapter`);
-  out(`     endpoint:     http://${lanIp()}:${port}`);
-  out(`     \x1b[33mtoken:        ${token}\x1b[0m \x1b[2m(明文只显示这一次)\x1b[0m`);
-  out(`  3. 验收三步: /health 探活 → 真实唤醒一轮 → 第二轮日志确认 resume=true`);
+
+  const ctx = await initCore(flags, flags.name || positionalName);
+  const { name, displayName, dir, workspace, port, token, model, wsExists, skillResults } = ctx;
+
+  // ---- 结果呈现（分段式，无边框——窄 TTY 安全）----
+  const kv = (label, value) => out(`  ${tDim(label)}${" ".repeat(Math.max(2, 12 - dispWidth(label)))}${value}`);
+  const step = (n, title, details) => {
+    out(`  ${tGreen(`${n}/4`)}  ${tBold(title)}`);
+    for (const d of details) out(`       ${d}`);
+  };
+  out();
+  ok(`1/4 完成  实例就绪  ${tBold(tCyan(name))}`);
+  if (!wsExists) warn("workspace 不存在，start 前请就位（daemon 不代建）");
+  out();
+  kv("实例目录", tDim(dir));
+  kv("workspace", workspace);
+  kv("模型", model ? `沿用 workspace 配置（${model}）` : tDim("opencode 默认（未探测到 .opencode/opencode.json）"));
+  kv("skills", skillResults.length ? skillResults.join("、") : tDim("未装配（--skills none）"));
+  kv("endpoint", `http://${lanIp()}:${port}`);
+  out();
+  out(`  ${tDim("── 接下来 " + "─".repeat(30))}`);
+  out();
+  step(2, "启动并自检", [tCyan(`tdxd-ctl start ${name} && tdxd-ctl status ${name}`)]);
+  step(3, "平台 UI hire（TDX-Adapter）", [
+    `${tDim("endpoint")}   http://${lanIp()}:${port}`,
+    `${tDim("token")}      ${tYellow(token)}  ${tDim("← 明文只显示这一次")}`,
+  ]);
+  step(4, "铸造 agent key 并回填（建议，兜底回调用）", [
+    `平台 Agent 页 → API Keys → 生成，然后：`,
+    `${tCyan(`tdxd-ctl key ${name} --set pcp_xxx && tdxd-ctl restart ${name}`)}`,
+  ]);
+  out(`  ${tDim("验收")}    /health 探活 → 真实唤醒一轮 → 第二轮日志 resume=true`);
+}
+
+// ---------- onboard（一条命令自助接入：init→start→join→等批准→claim→回填→READY） ----------
+async function fetchJson(url, opts = {}, timeoutMs = 10000) {
+  try {
+    const r = await fetch(url, {
+      method: opts.method ?? "GET",
+      headers: { "content-type": "application/json", ...(opts.headers ?? {}) },
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await r.text();
+    let json = null; try { json = JSON.parse(text); } catch { /* 非 JSON */ }
+    return { code: r.status, json, text };
+  } catch (e) {
+    return { code: 0, err: e.message };
+  }
+}
+
+function readJson600(f) { try { return JSON.parse(fs.readFileSync(f, "utf8")); } catch { return null; } }
+function writeJson600(f, obj) { fs.writeFileSync(f, JSON.stringify(obj, null, 2), { mode: 0o600 }); }
+
+async function cmdOnboard(flags) {
+  // 阶段0：解析邀请 + 平台可达
+  if (!flags.invite) { fail("缺 --invite <url>（平台 UI 生成邀请后的 onboarding.txt 地址）"); process.exit(1); }
+  const m = String(flags.invite).match(/^(https?:\/\/[^/]+)\/api\/invites\/([^/?#]+)/);
+  if (!m) { fail(`无法解析邀请 URL：${flags.invite}（期望形如 http://host:3100/api/invites/<token>/onboarding.txt）`); process.exit(1); }
+  const [, base, inviteToken] = m;
+  const hp = await fetchJson(`${base}/api/health`);
+  if (hp.code !== 200) { fail(`平台不可达（${base}/api/health → ${hp.code || hp.err}）`); process.exit(1); }
+
+  const workspace = path.resolve(expandHome(flags.workspace || process.cwd()));
+  const name = flags.name || path.basename(workspace).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+  const dir = path.join(AGENTS_DIR, name);
+  const obFile = path.join(dir, "run", "onboard.json");
+  let ob = readJson600(obFile);
+
+  head(`TDX-Daemon 自助接入  ${tBold(name)}`);
+
+  // 阶段1：init（有断点状态则跳过）
+  if (!ob) {
+    if (fs.existsSync(path.join(dir, "config.json"))) {
+      fail(`实例已存在且无接入状态：${dir}（如需重接先删除该目录）`); process.exit(1);
+    }
+    const ctx = await initCore({ ...flags, workspace }, name);
+    ok(`1/4 init 完成（端口 ${ctx.port}，skills 就绪）`);
+    ob = { stage: "init_done" };
+    writeJson600(obFile, ob);
+  } else note(`1/4 断点续跑（stage=${ob.stage}）`);
+
+  // 阶段2：start（幂等）
+  const a = { name, dir, cfgPath: path.join(dir, "config.json"), cfg: JSON.parse(fs.readFileSync(path.join(dir, "config.json"), "utf8")) };
+  const sec = readSecret(dir);
+  const r0 = startOne(a);
+  if (r0 === false) process.exit(1);
+  const h = await waitHealth(a);
+  if (h.code !== 200) { fail(`2/4 daemon 健康未过（${h.code}）：tail -20 ${path.join(dir, "log", "tdxd.log")}`); process.exit(1); }
+  ok(`2/4 daemon 运行 :${a.cfg.port} v${h.json?.version ?? "?"}`);
+
+  // 阶段3：join 提交（accept）
+  if (ob.stage === "init_done") {
+    const body = {
+      requestType: "agent",
+      agentName: a.cfg.name,
+      adapterType: "tdx_adapter",
+      capabilities: flags.capabilities || `opencode ACP agent "${name}" on ${os.hostname()}`,
+      agentDefaultsPayload: {
+        endpoint: `http://${lanIp()}:${a.cfg.port}`,
+        token: sec.TDXD_TOKEN,
+        timeoutMs: 420000,
+      },
+    };
+    const acc = await fetchJson(`${base}/api/invites/${inviteToken}/accept`, { method: "POST", body });
+    if (acc.code !== 202 || !acc.json?.id || !acc.json?.claimSecret) {
+      fail(`3/4 join 提交失败（HTTP ${acc.code}）：${(acc.json?.error ?? acc.text ?? "").slice(0, 200)}`); process.exit(1);
+    }
+    ob = { stage: "joined", base, requestId: acc.json.id, claimSecret: acc.json.claimSecret };
+    writeJson600(obFile, ob);
+    ok(`3/4 join 已提交（requestId ${acc.json.id.slice(0, 8)}…）`);
+  } else if (ob.stage === "joined") note(`3/4 join 已存在（requestId ${String(ob.requestId).slice(0, 8)}…），继续等批准`);
+
+  // 阶段4+5：等批准（claim 即轮询：409 not-approved → 继续；201 → 过闸）
+  if (ob.stage === "joined") {
+    const waitMin = Number(flags["wait-min"] || 30);
+    const deadline = Date.now() + waitMin * 60_000;
+    out(`  ${tYellow("[等待]")} 4/4 等待 board 批准（平台 UI → 入职/Join 请求 → Approve "${a.cfg.name}"；最长 ${waitMin} 分钟，每 15s 轮询）`);
+    for (;;) {
+      const c = await fetchJson(`${base}/api/join-requests/${ob.requestId}/claim-api-key`, { method: "POST", body: { claimSecret: ob.claimSecret } });
+      if (c.code === 201 && c.json?.token) {
+        writeAgentKey(dir, c.json.token); // 完整 key 只落文件，不打印
+        ob = { ...ob, stage: "claimed", agentId: c.json.agentId, keyId: c.json.keyId, claimedAt: new Date().toISOString() };
+        delete ob.claimSecret; // 单次秘密，用后即焚
+        writeJson600(obFile, ob);
+        ok(`4/4 key 已领取并写入 secret.env（${c.json.token.slice(0, 8)}…，agentId ${String(c.json.agentId).slice(0, 8)}…）`);
+        break;
+      }
+      const msg = String(c.json?.error ?? c.text ?? "");
+      if (c.code === 409 && /approved/i.test(msg)) {
+        if (Date.now() > deadline) {
+          fail(`等待批准超时（${waitMin} 分钟）。状态已保存，批准后重跑同命令即可续`); process.exit(1);
+        }
+        await new Promise((res) => setTimeout(res, 15_000));
+        continue;
+      }
+      if (c.code === 409 && /already claimed/i.test(msg)) {
+        fail("该 join 请求的 key 已被领取过（claimSecret 单次）。如丢失 key，请在平台重新铸 key 后用 tdxd-ctl key 回填"); process.exit(1);
+      }
+      if (c.code === 409 && /expired/i.test(msg)) {
+        fail("claimSecret 已过期。请操作员重新生成邀请后重跑（实例与 join 状态保留）"); process.exit(1);
+      }
+      fail(`claim 失败（HTTP ${c.code}）：${msg.slice(0, 200)}`); process.exit(1);
+    }
+  } else note(`4/4 已完成（claimed @ ${ob.claimedAt ?? "?"}）`);
+
+  // 阶段6：restart + 终检 + READY
+  await stopOneAsync(a);
+  const r2 = startOne(a);
+  if (r2 === false) process.exit(1);
+  const h2 = await waitHealth(a);
+  const sec2 = readSecret(dir);
+  out();
+  if (h2.code === 200 && sec2.TDXD_PAPERCLIP_KEY) {
+    ok(`READY  ${tBold(name)}  health=${h2.code} v${h2.json?.version}  回调:启用`);
+    out(`  endpoint  http://${lanIp()}:${a.cfg.port}`);
+    out(`  ${tDim("验收：向该 Agent 派一个测试任务 → 观察心跳执行 → 第二轮 resume=true")}`);
+  } else {
+    fail(`终检未过（health=${h2.code}，回调${sec2.TDXD_PAPERCLIP_KEY ? "启用" : "未配置"}），查日志 ${path.join(dir, "log", "tdxd.log")}`);
+    process.exit(1);
+  }
 }
 
 // ---------- 生命周期 ----------
 function startOne(a) {
   const pid = pidOf(a);
   if (pid) {
-    out(`[ctl] ${a.name} 已在运行（pid ${pid}）`);
+    note(`${a.name} 已在运行（pid ${pid}）`);
     return "running";
   }
   const sec = readSecret(a.dir);
-  if (!sec.TDXD_TOKEN) { out(`[ctl] ✗ ${a.name} 缺 secret.env TDXD_TOKEN`); return false; }
-  if (!fs.existsSync(a.cfg.workspace)) { out(`[ctl] ✗ ${a.name} workspace 不存在: ${a.cfg.workspace}`); return false; }
+  if (!sec.TDXD_TOKEN) { fail(`${a.name} 缺 secret.env TDXD_TOKEN`); return false; }
+  if (!fs.existsSync(a.cfg.workspace)) { fail(`${a.name} workspace 不存在: ${a.cfg.workspace}`); return false; }
   fs.mkdirSync(path.dirname(pidFile(a)), { recursive: true });
   const logFd = fs.openSync(path.join(a.dir, "log", "tdxd.log"), "a");
   const child = spawn(process.execPath, [DAEMON_BIN, "--config", a.cfgPath], {
@@ -186,7 +432,7 @@ async function waitHealth(a, ms = 15000) {
 
 async function stopOneAsync(a) {
   const pid = pidOf(a);
-  if (!pid) { out(`[ctl] ${a.name} 无 pid 记录（未运行或由旧方式启动）`); return; }
+  if (!pid) { note(`${a.name} 无 pid 记录（未运行或由旧方式启动）`); return; }
   try { process.kill(pid, "SIGTERM"); } catch { /* 已退 */ }
   for (let i = 0; i < 25; i++) {
     try { process.kill(pid, 0); } catch { break; }
@@ -194,20 +440,22 @@ async function stopOneAsync(a) {
   }
   try { process.kill(pid, 0); process.kill(pid, "SIGKILL"); } catch { /* 已退 */ }
   try { fs.unlinkSync(pidFile(a)); } catch { /* 无 */ }
-  out(`[ctl] ✓ ${a.name} 已停止`);
+  ok(`${a.name} 已停止`);
 }
 
 async function cmdStart(target) {
-  let ok = true;
+  let allOk = true;
   for (const a of pick(target)) {
     const r = startOne(a);
     if (r === "running") continue;
-    if (!r) { ok = false; continue; }
+    if (!r) { allOk = false; continue; }
+    note(`${a.name} 启动中 :${a.cfg.port}（等待 health ≤15s）…`);
     const h = await waitHealth(a);
-    if (h.code === 200) out(`[ctl] ✓ ${a.name} 启动成功 :${a.cfg.port}（日志 ${path.join(a.dir, "log", "tdxd.log")}）`);
-    else { out(`[ctl] ✗ ${a.name} 健康检查未过（health=${h.code}），查日志: tail -20 ${path.join(a.dir, "log", "tdxd.log")}`); ok = false; }
+    const ver = h.json?.version ? ` v${h.json.version}` : "";
+    if (h.code === 200) ok(`${a.name} 已启动 :${a.cfg.port}${ver}`);
+    else { fail(`${a.name} 健康检查未过（health=${h.code}），查日志: tail -20 ${path.join(a.dir, "log", "tdxd.log")}`); allOk = false; }
   }
-  if (!ok) process.exitCode = 1;
+  if (!allOk) process.exitCode = 1;
 }
 
 async function cmdRestart(target) {
@@ -215,15 +463,35 @@ async function cmdRestart(target) {
   await cmdStart(target);
 }
 
+/** 孤儿探测：18200-18299 区间有监听但无实例配置认领 → 目录已删进程还在的 daemon */
+async function findOrphanPorts() {
+  const claimed = new Set(listAgents().map((a) => a.cfg?.port).filter(Boolean));
+  const ports = [];
+  for (let p = 18200; p <= 18299; p++) ports.push(p);
+  const checks = await Promise.all(ports.map(async (p) => ({ p, free: await canBind(p) })));
+  return checks.filter((c) => !c.free && !claimed.has(c.p)).map((c) => c.p);
+}
+
 async function cmdStatus(target) {
-  for (const a of pick(target)) {
+  const rows = await Promise.all(pick(target).map(async (a) => {
     const pid = pidOf(a);
     const h = await healthOf(a, 2000);
     const sec = readSecret(a.dir);
-    const cb = sec.TDXD_PAPERCLIP_KEY ? "回调:启用" : "回调:未配置⚠";
-    const run = pid ? `运行(pid ${pid})` : "停";
-    const ver = h.json?.version ? ` v${h.json.version}` : "";
-    out(`${a.name}: ${run} | :${a.cfg?.port ?? "?"} health=${h.code}${ver} | ${cb}`);
+    return [
+      cell(a.name, "bold"),
+      cell(pid ? `运行 ${pid}` : "停", pid ? "green" : "red"),
+      cell(`:${a.cfg?.port ?? "?"}`),
+      cell(h.code === 200 ? "200" : String(h.code || "—"), h.code === 200 ? "green" : "red"),
+      cell(h.json?.version ? `v${h.json.version}` : "—", "dim"),
+      cell(sec.TDXD_PAPERCLIP_KEY ? "启用" : "未配置", sec.TDXD_PAPERCLIP_KEY ? "green" : "yellow"),
+    ];
+  }));
+  table(["实例", "状态", "端口", "HEALTH", "版本", "回调"], rows);
+  note(`${tDim("实例目录")} ${AGENTS_DIR}`);
+  const orphans = await findOrphanPorts();
+  if (orphans.length) {
+    warn(`疑似孤儿 daemon 端口: ${orphans.join(", ")}（实例目录已删但进程仍在，占用端口资源）`);
+    out(`       处置：ss -tlnp | grep -E '${orphans.join("|")}' 找 pid → kill <pid>`);
   }
 }
 
@@ -241,17 +509,38 @@ function parseFlags(argv) {
 }
 
 const [cmd = "status", targetArg, ...rest] = process.argv.slice(2);
+process.stdout?.on?.("error", (e) => { if (e.code === "EPIPE") process.exit(0); }); // | head 等提前关管道时静默退出
 const target = targetArg ?? "all"; // init 场景须用 targetArg（可能为 undefined），不能吃这个默认值
 const flags = parseFlags(rest);
 switch (cmd) {
-  case "init": try { await cmdInit(flags, targetArg); } finally { closePrompt(); } break;
-  case "list": for (const a of listAgents()) out(`${a.name}\t:${a.cfg?.port}\t${a.cfg?.workspace}`); break;
+  case "init": await cmdInit(flags, targetArg); break;
+  case "skills": cmdSkills(target, flags); break;
+  case "key": cmdKey(target, flags); break;
+  case "onboard": await cmdOnboard(parseFlags(process.argv.slice(3))); break; // 无位置参数：从原始 argv 解析，防首 flag 被误当 target
+  case "list": {
+    const agents = listAgents();
+    if (agents.length === 0) { warn(`无实例（查 ${AGENTS_DIR}/；初始化用 tdxd-ctl init <name>）`); break; }
+    table(["实例", "端口", "WORKSPACE"], agents.map((a) => [
+      cell(a.name, "bold"), `:${a.cfg?.port ?? "?"}`, cell(a.cfg?.workspace ?? "—", "dim"),
+    ]));
+    break;
+  }
   case "start": await cmdStart(target); break;
   case "stop": for (const a of pick(target)) await stopOneAsync(a); break;
   case "restart": await cmdRestart(target); break;
   case "status": await cmdStatus(target); break;
   default:
-    out("用法: tdxd-ctl init|list|start|stop|restart|status [name|all] [--yes --name --display --workspace --model --persona --port --token --url --force]");
+    out("用法: tdxd-ctl init|onboard|list|skills|key|start|stop|restart|status [name|all]");
+    out("  （全命令无交互、纯 flags——面向 AI 调用与脚本化；缺参即报错，由调用方补参重试）");
+    out("  init <name> [--workspace <p>] [--port <n>] [--url <u>] [--token <t>]");
+    out("            [--display <s>] [--skills <a,b>|none] [--force]");
+    out("  skills <name> [--add <skill>|--rm <skill>]   # 内置: paperclip(核心), paperclip-converting-plans-to-tasks");
+    out("  key <name> --set pcp_xxx | --rm              # 平台 agent key 回填（兜底回调），写后 restart 生效");
+    out("  onboard --invite <url> [--name] [--workspace] [--capabilities] [--wait-min 30]");
+    out("       # 一条命令自助接入：init→start→join→等批准(轮询)→claim key→回填→READY");
     out(`实例目录: ${AGENTS_DIR}`);
     process.exit(1);
 }
+// 显式退出：被 TUN/防火墙黑洞的端口，fetch abort 只解除 Promise，
+// undici 底层 connect 定时器（10s）仍挂着事件循环导致命令迟迟不返回
+process.exit(process.exitCode ?? 0);

package/tdxd.mjs

@@ -227,7 +227,7 @@ const server = http.createServer((req, res) => {
   if (req.method === "GET" && req.url === "/health") {
     if (!okAuth(req)) { res.writeHead(401); res.end(); return; }
     res.writeHead(200, { "content-type": "application/json" });
-    res.end(JSON.stringify({ ok: true, name: cfg.name, workspace: cfg.workspace, version: "1.1.1",
+    res.end(JSON.stringify({ ok: true, name: cfg.name, workspace: cfg.workspace, version: "1.2.0",
       activeSessions: router.sessions.size }));
     return;
   }
@@ -358,7 +358,7 @@ async function handleRun(wake, req, res) {
 }
 
 server.listen(cfg.port, cfg.bind, () => {
-  console.log(`[tdxd] ${cfg.name} v1.1.1 就绪 ${cfg.bind}:${cfg.port}`);
+  console.log(`[tdxd] ${cfg.name} v1.2.0 就绪 ${cfg.bind}:${cfg.port}`);
   console.log(`[tdxd] workspace=${cfg.workspace} command=${cfg.command} ${cfg.commandArgs.join(" ")}`);
   console.log(`[tdxd] idleTTL=${cfg.idleTtlMin}min maxSessions=${cfg.maxSessions} 回调=${cfg.paperclip.url ? "启用" : "未配置"}`);
 });