cofluxd 0.8.0 → 0.9.0

package/README.md

@@ -24,6 +24,26 @@ cofluxd uninstall [--purge]   # 卸载（--purge 连二进制/配置/凭证一
 
 默认连公共服务 `wss://api.coflux.dev/daemon`（自托管用 `--server` 改；已保存的地址继续生效，非默认时会有醒目提示）。
 
+## 给 agent 用的命令
+
+跑在 coflux 终端里的 claude/codex 可以用下面几条，把工作外化成用户在 web/手机上**看得见、能接管**的东西——而不是在自己的 Bash 里后台起一个谁也看不见的进程：
+
+```sh
+cofluxd terminal new --title "跑单测" --cmd "pnpm test"   # 开真实终端，用户可接管
+cofluxd terminal list                                     # 本工作区的终端 + 状态/退出码
+cofluxd terminal read <taskId> [--lines N]                # 读终端内容（纯文本，已退出也能读）
+cofluxd notify "需要你定一下用哪个方案"                    # 叫人：侧栏转「等待交互」
+cofluxd ports                                             # 端口 + 可直接打开的预览 URL
+```
+
+不需要任何凭证：daemon 用调用方 pid 反查进程树确认它属于哪个会话，**coflux 会话之外的进程一律拒绝**，权限也天然限定在该会话所属的工作区内。
+
+配套的 skill 在 `skills/coflux/SKILL.md`（随包分发），装给 Claude Code：
+
+```sh
+mkdir -p ~/.claude/skills && ln -sfn "$(npm root -g)/cofluxd/skills/coflux" ~/.claude/skills/coflux
+```
+
 `cofluxd up` 起服务后会打印一个一次性授权链接，在浏览器用已登录的账号打开确认即可（链接可在任意设备打开，包括无头设备），无需先去 web 控制台生成密钥。已登记设备重跑 `up` 不会重新触发授权。
 
 ## 本地优先与 doctor

package/cofluxd.mjs

@@ -747,6 +747,97 @@ async function cmdHook() {
   }
 }
 
+/* --------------------- agent 协同控制（plan 074） --------------------- */
+// 跑在 coflux 终端里的 claude/codex 用这组命令，把自己的工作外化成用户在 web/手机上
+// **看得见、能接管**的 coflux 实体——而不是在自己的 Bash 里后台起一个谁也看不见的进程。
+//
+// 不需要任何凭证：daemon 用调用方 pid 反查进程树确认它属于哪个会话，树外一律拒。
+// 与 `hook` 子命令的约定**相反**：这些命令必须写 stdout——输出就是给 agent 读的返回值。
+// 也刻意不做自动重试：terminal new 有副作用，重试会开出两个终端，失败就把错误交给 agent。
+
+const AGENT_TIMEOUT_MS = 30_000;
+const DEFAULT_READ_LINES = 200;
+
+async function agentPost(body) {
+  const portResult = localGatewayPort();
+  if (!portResult.ok) die(portResult.error);
+  let res;
+  try {
+    res = await fetch(`http://127.0.0.1:${portResult.port}/agent`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ ...body, pid: process.pid, ppid: process.ppid }),
+      signal: AbortSignal.timeout(AGENT_TIMEOUT_MS),
+    });
+  } catch (error) {
+    die(`连不上本机 daemon：${error?.message || error}（daemon 没在跑？先看 cofluxd status）`);
+  }
+  let parsed = null;
+  try { parsed = await res.json(); } catch { /* 非 JSON 响应按下面的兜底报错处理 */ }
+  if (!res.ok || !parsed?.ok) die(parsed?.error || `daemon 返回 ${res.status}`);
+  return parsed;
+}
+
+// 剥掉 ANSI/OSC 转义与 C0 控制字符，保留 \t 与 \n——snapshot 是给终端渲染的字节流，
+// agent 要的是能读的纯文本。去转义放在 CLI 侧：daemon 的 snapshot 同时是 checkpoint 的
+// 数据来源，不为 agent 的可读性改它的语义。
+const ANSI_RE =
+  /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[[\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-PR-TZcf-ntqry=><~]|[\u0000-\u0008\u000b-\u001f\u007f]/g;
+
+function stripAnsi(raw) {
+  return String(raw ?? "").replace(ANSI_RE, "");
+}
+
+/** 取最后 n 行并去掉尾部空行——VT snapshot 的下半屏通常是成片空行，对 agent 是纯噪音。 */
+function tailLines(text, n) {
+  const lines = text.split("\n");
+  while (lines.length && lines[lines.length - 1].trim() === "") lines.pop();
+  return lines.slice(-n).join("\n");
+}
+
+async function cmdTerminal(values) {
+  const sub = positionals[1];
+  if (sub === "new") {
+    const command = values.cmd;
+    if (!command) die(`terminal new 需要 --cmd "<命令>"`);
+    const result = await agentPost({ action: "terminal.new", title: values.title || "", command });
+    console.log(`已开终端 ${result.taskId}（用户可在 coflux 侧栏看到并随时接管）`);
+    console.log(`看输出：cofluxd terminal read ${result.taskId}`);
+  } else if (sub === "list") {
+    const { terminals } = await agentPost({ action: "terminal.list" });
+    if (!terminals.length) return void console.log("本工作区暂无终端");
+    for (const t of terminals) {
+      const exit = t.exitCode === undefined || t.exitCode === null ? "" : ` exit=${t.exitCode}`;
+      console.log(`${t.taskId}  ${t.status}${exit}  ${t.title}`);
+    }
+  } else if (sub === "read") {
+    const taskId = positionals[2];
+    if (!taskId) die("terminal read 需要 <taskId>（用 cofluxd terminal list 查）");
+    const requested = Number(values.lines);
+    const lines = Number.isInteger(requested) && requested > 0 ? requested : DEFAULT_READ_LINES;
+    const result = await agentPost({ action: "terminal.read", taskId });
+    const exit = result.exitCode === undefined || result.exitCode === null ? "" : ` exit=${result.exitCode}`;
+    console.log(`# ${result.status}${exit}`);
+    const text = tailLines(stripAnsi(result.ansi), lines);
+    console.log(text || "（暂无输出）");
+  } else {
+    die(`terminal 需要子命令：new | list | read`);
+  }
+}
+
+async function cmdNotify() {
+  const message = positionals.slice(1).join(" ").trim();
+  if (!message) die(`notify 需要一句话，例如：cofluxd notify "两个方案拿不准，需要你定"`);
+  await agentPost({ action: "notify", message });
+  console.log("已通知用户（工作区在侧栏转为「等待交互」）");
+}
+
+async function cmdPorts() {
+  const { ports } = await agentPost({ action: "ports" });
+  if (!ports.length) return void console.log("本工作区暂无监听端口");
+  for (const p of ports) console.log(`${p.port}  ${p.url}`);
+}
+
 const HELP = `cofluxd —— coflux daemon 管理
 
   cofluxd                 首次=up（打印浏览器授权链接），已配置=status
@@ -762,6 +853,16 @@ const HELP = `cofluxd —— coflux daemon 管理
   cofluxd hook <claude|codex>   [agent hook 信使] 读 stdin/argv 的事件 JSON，转发给本机 daemon
                           （在 claude/codex 的 hook 配置里指向本命令；失败静默，不干扰 agent）
 
+  以下几条供**跑在 coflux 终端里的 agent** 调用，把工作变成用户看得见、能接管的东西：
+
+  cofluxd terminal new --cmd "<命令>" [--title "<标题>"]
+                          开一个真实终端跑命令，用户在 coflux 侧栏能看到并随时接管
+  cofluxd terminal list   列出本工作区的终端（含 status / 退出码）
+  cofluxd terminal read <taskId> [--lines N]
+                          读某个终端的内容（纯文本，默认最后 200 行；终端已退出也能读）
+  cofluxd notify "<一句话>"  叫人：工作区在侧栏转为「等待交互」并显示这句话
+  cofluxd ports           列出本工作区的监听端口及可直接打开的预览 URL
+
 up flags: --server <ws://.../daemon>  --name <名>  --shell <路径>
 通用: --version <vX|latest>(不传时 up 沿用已有二进制，update 默认 latest)  --bin-dir <dir>(用本地 cargo 产物)  --no-start
 配置都在 ~/.coflux/settings.json（serverUrl/deviceName/shell），daemon 直接读；改后重跑 cofluxd up 生效。`;
@@ -779,6 +880,9 @@ const { values, positionals } = parseArgs({
     server: { type: "string" },
     name: { type: "string" },
     shell: { type: "string" },
+    title: { type: "string" },
+    cmd: { type: "string" },
+    lines: { type: "string" },
     version: { type: "string" },
     "bin-dir": { type: "string" },
     "no-start": { type: "boolean", default: false },
@@ -792,7 +896,7 @@ let cmd = positionals[0];
 if (values.help || cmd === "help") { console.log(HELP); process.exit(0); }
 if (!cmd) cmd = fs.existsSync(SETTINGS) ? "status" : "up"; // 首次裸跑 → 引导
 
-const handlers = { up: cmdUp, update: cmdUpdate, restart: cmdRestart, down: cmdDown, status: cmdStatus, doctor: cmdDoctor, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall, hook: cmdHook };
+const handlers = { up: cmdUp, update: cmdUpdate, restart: cmdRestart, down: cmdDown, status: cmdStatus, doctor: cmdDoctor, fda: cmdFda, logs: cmdLogs, uninstall: cmdUninstall, hook: cmdHook, terminal: cmdTerminal, notify: cmdNotify, ports: cmdPorts };
 const h = handlers[cmd];
 if (!h) die(`未知命令: ${cmd}${MIGRATED[cmd] ? `\n${MIGRATED[cmd]}` : ""}\n\n${HELP}`);
 await h(values);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "coflux daemon 管理 CLI：装/起/停/升级 Rust daemon（supervisor + worker）",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "cofluxd.mjs",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "engines": {
     "node": ">=20"

package/skills/coflux/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: coflux
+description: 当你运行在 coflux 终端里时，把长任务、并行工作和求助外化成用户在 coflux web/手机上看得见、能随时接管的真实终端。适用于跑测试/构建/dev server 等耗时命令、需要用户接管或决策、想给用户一个可点开的预览 URL 的场景。
+---
+
+# 在 coflux 里工作
+
+你可能正跑在 coflux 的一个终端里。coflux 让用户在浏览器和手机上盯着各台机器上的
+agent 干活，随时接管。这套命令让你把自己的工作**变成用户看得见的东西**。
+
+先判断自己在不在 coflux 里：任意一条命令返回「不在 coflux 终端里」就说明不在，
+这时忘掉这个 skill，照常用你自己的工具。
+
+## 什么时候用
+
+**用 `cofluxd terminal new` 而不是自己后台起进程**——只要这条命令满足任一条：
+
+- 要跑超过十几秒（测试、构建、安装依赖、迁移）
+- 会一直跑下去（dev server、watch、日志跟随）
+- 用户可能想接管（需要交互、可能要中途叫停、失败了要人去调）
+
+这类工作在你自己的 Bash 里后台跑，用户**什么也看不见**：看不到它在跑、接管不了、
+出问题只能等你转述。开成 coflux 终端，它就是侧栏里一个有标题的条目，用户能点进去、
+能接管、能自己敲命令。
+
+**不要用**在一次性的快命令上（`ls`、`grep`、`git status`、读文件）——你自己的工具更快，
+给用户开一堆一秒就结束的终端只是噪音。
+
+## 命令
+
+### 开终端跑命令
+
+```sh
+cofluxd terminal new --title "跑单测" --cmd "pnpm -C tests test"
+```
+
+`--title` 是用户在侧栏看到的名字，**认真起**：写「跑单测」「起 dev server」，
+别写「terminal 1」。命令在当前工作区目录下、用登录 shell 执行。
+
+命令跑完终端就退出，任务转 `exited` 并带上退出码——这是你判断成没成的依据。
+所以别指望在同一个终端里接着跑第二条命令，要么写成 `a && b`，要么再开一个。
+
+命令的输出会同时落一份日志供你回读，代价是它的 stdout 是管道而不是 tty——多数程序会因此
+关掉颜色和进度条。极少数程序在非 tty 下行为不同（比如不输出进度、切成 CI 模式），如果你
+依赖那种行为，自己在 Bash 里跑。
+
+### 看跑到哪了
+
+```sh
+cofluxd terminal list                      # 本工作区所有终端：id、状态、退出码、标题
+cofluxd terminal read <taskId>             # 某个终端的内容（纯文本，默认最后 200 行）
+cofluxd terminal read <taskId> --lines 50
+```
+
+`list` 的状态是 `running` / `exited` / `idle`；`exited` 会带 `exit=<码>`。
+**终端已经退出也能 read**——「命令跑完了看输出」正是最常用的场景。
+
+内容有最多约 2 秒的延迟（来自中心的定期快照），所以刚 `new` 完立刻 `read` 可能是空的。
+要等一条命令跑完，隔几秒 `list` 一次看它转没转 `exited`，别忙等。
+
+### 叫人
+
+```sh
+cofluxd notify "两个方案都能走通，需要你定一下用哪个"
+```
+
+用户的侧栏里这个工作区会转成「等待交互」并显示这句话——他在手机上也看得到。
+用在你**真的卡住**的时候：需要用户决策、要密码/权限、发现了必须人来判断的问题。
+一句话说清要什么，别写成日志。
+
+（你正常的提问和权限请求已经会自动反映到侧栏状态上，不需要额外 notify。
+这条是给「你要说的事，用户光看状态图标猜不出来」准备的。）
+
+### 给用户可点开的预览
+
+```sh
+cofluxd ports
+```
+
+列出本工作区所有监听端口和对应的公网预览 URL。起了 dev server 之后用它拿 URL 直接
+告诉用户，他点开就能看，不用自己去翻。
+
+## 边界
+
+- 你**只能开和读**，不能往别人的终端里打字。要交互就 `notify` 让用户接管。
+- 能看到的只有**你自己所在的工作区**，别的工作区和别的机器都看不见也碰不到。
+- 一个工作区同时活着的终端有上限（默认 8，含用户自己开的）。撞上限先 `list` 看看，
+  多半是有跑完没收的；真是用户占满了，就 `notify` 告诉他，别硬试。
+- 这些命令都要 daemon 连着中心才能用——毕竟「让用户看见」就是它们的全部意义。
+  连不上时会明确报错，不会默默降级。