cofluxd 0.12.0 → 0.13.0

package/README.md

@@ -43,6 +43,8 @@ cofluxd ports                                             # 端口 + 可直接
 
 不需要任何凭证：daemon 用调用方 pid 反查进程树确认它属于哪个会话，**coflux 会话之外的进程一律拒绝**，权限也天然限定在该会话所属的工作区内。
 
+每个 coflux 开出来的 PTY 会话里还注入了一组 `COFLUX_*` 环境变量（由 supervisor 组装，中心只下发 id）：`COFLUX_DEVICE_ID` / `COFLUX_PROJECT_ID`（目录工作区为空串）/ `COFLUX_WORKSPACE_ID` / `COFLUX_TASK_ID` / `COFLUX_SESSION_ID` / `COFLUX_MCP_URL`。agent 读它们就知道自己在哪台设备、哪个项目/工作区/终端，值与中心 MCP `list_*` 返回的 id 完全一致，可直接传给 MCP tools。本地命令与 MCP 的分工：本工作区内的开终端/读/等/输入/播报/叫人/端口用上面的零凭证命令；开子工作区、跨工作区/跨设备读写、或从 coflux 之外接入，用中心的 `coflux` MCP（`claude mcp add --transport http coflux "$COFLUX_MCP_URL"`，一次 OAuth 授权）。supervisor 不走热升级，旧机器要 `cofluxd update && cofluxd restart` 之后会话里才有这些变量；skill 里写了变量为空时的降级分支。
+
 配套的 skill 在 `skills/coflux/SKILL.md`（随包分发），装给 Claude Code：
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "coflux daemon 管理 CLI：装/起/停/升级 Rust daemon（supervisor + worker）",
   "type": "module",
   "bin": {

package/skills/coflux/SKILL.md

@@ -1,17 +1,49 @@
 ---
 name: coflux
-description: 当你运行在 coflux 终端里时，把长任务、并行工作和求助外化成用户在 coflux web/手机上看得见、能随时接管的真实终端。适用于跑测试/构建/dev server 等耗时命令、需要用户接管或决策、想给用户一个可点开的预览 URL 的场景。
+description: 当你运行在 coflux 终端里时，把长任务、并行工作和求助外化成用户在 coflux web/手机上看得见、能随时接管的真实终端；读 COFLUX_* 环境变量知道自己在哪台设备/项目/工作区/终端，本工作区内用本地 cofluxd 命令，开子工作区或跨工作区/跨设备操作用中心的 coflux MCP。适用于跑测试/构建/dev server 等耗时命令、需要用户接管或决策、想给用户一个可点开的预览 URL、要在隔离的子工作区并行干活的场景。
 ---
 
 # 在 coflux 里工作
 
 你可能正跑在 coflux 的一个终端里。coflux 让用户在浏览器和手机上盯着各台机器上的
-agent 干活，随时接管。这套命令让你把自己的工作**变成用户看得见的东西**。
+agent 干活，随时接管。这个 skill 让你把自己的工作**变成用户看得见的东西**，并在需要时
+操作账号下的其它工作区和设备。
 
-先判断自己在不在 coflux 里：任意一条命令返回「不在 coflux 终端里」就说明不在，
-这时忘掉这个 skill，照常用你自己的工具。
+有两条轨道，分工固定：
 
-## 什么时候用
+| 轨道 | 凭证 | 能触达的范围 | 用在 |
+|---|---|---|---|
+| 本地命令 `cofluxd terminal/progress/notify/ports` | 零凭证（daemon 按你的进程树认身份） | 只有**你所在的工作区** | 本工作区内开终端、读、等、输入、播报、叫人、拿预览 URL——最省事的路径 |
+| 中心 MCP `coflux`（14 个 tools） | 用户在宿主里做一次 OAuth 授权 | **整个账号**：所有设备、项目、工作区、终端 | 开子工作区（git worktree）、跨工作区/跨设备读写、从 coflux 之外接入 |
+
+## 先判断自己在哪
+
+先看环境变量：
+
+```sh
+env | grep '^COFLUX_'
+```
+
+- **`COFLUX_WORKSPACE_ID` 非空** → 你在 coflux 终端里，且 daemon 已是新版。下面的变量就是
+  你的坐标，MCP tools 要的 id 直接从这里拿，不用去 `list_*` 里猜：
+
+  | 变量 | 含义 |
+  |---|---|
+  | `COFLUX_DEVICE_ID` | 你所在机器的设备 id（`list_devices` 的 id） |
+  | `COFLUX_PROJECT_ID` | 所属项目 id；无仓库的目录工作区为空串 |
+  | `COFLUX_WORKSPACE_ID` | 所属工作区 id（`list_workspaces` 的 id） |
+  | `COFLUX_TASK_ID` | 你这个终端的 id（`list_terminals` / `read_terminal` 用的 terminalId） |
+  | `COFLUX_SESSION_ID` | 你这个 PTY 会话 id |
+  | `COFLUX_MCP_URL` | 中心 MCP 地址，用户配 MCP 时就用它 |
+
+- **变量为空或不存在** → 跑一条 `cofluxd terminal list`：
+  - 返回「不在 coflux 终端里」→ 你不在 coflux 里，忘掉这个 skill，照常用你自己的工具
+    （除非用户已经在宿主里配了 coflux MCP，那时 MCP tools 照用，只是没有「我在哪」的坐标）。
+  - 能列出终端 → 你在 coflux 里，但 daemon 还没升级到注入环境变量的版本：本地命令全部可用，
+    只是你不知道自己的 id；要用 MCP 就先 `list_devices` / `list_workspaces` 按路径对一下
+    `pwd`，并顺手告诉用户 `cofluxd update && cofluxd restart` 之后就有环境变量了。
+
+## 什么时候用本地命令
 
 **用 `cofluxd terminal new` 而不是自己后台起进程**——只要这条命令满足任一条：
 
@@ -26,7 +58,7 @@ agent 干活，随时接管。这套命令让你把自己的工作**变成用户
 **不要用**在一次性的快命令上（`ls`、`grep`、`git status`、读文件）——你自己的工具更快，
 给用户开一堆一秒就结束的终端只是噪音。
 
-## 命令
+## 本地命令
 
 ### 开终端跑命令
 
@@ -44,6 +76,8 @@ cofluxd terminal new --title "跑单测" --cmd "pnpm -C tests test"
 关掉颜色和进度条。极少数程序在非 tty 下行为不同（比如不输出进度、切成 CI 模式），如果你
 依赖那种行为，自己在 Bash 里跑。
 
+新开的终端里同样有 `COFLUX_*` 变量（指向它自己的 task/session id，工作区与你相同）。
+
 ### 看跑到哪了
 
 ```sh
@@ -117,12 +151,72 @@ cofluxd ports
 列出本工作区所有监听端口和对应的公网预览 URL。起了 dev server 之后用它拿 URL 直接
 告诉用户，他点开就能看，不用自己去翻。
 
+## 中心 MCP：跨出本工作区
+
+本地命令只看得见你所在的工作区。要做下面这些事，用宿主里名为 `coflux` 的 MCP server：
+
+- **开一个隔离的子工作区并行干活**：`create_workspace`（项目 id 用 `$COFLUX_PROJECT_ID`）
+  在设备上真的 `git worktree add`，然后 `create_terminal` 在那里跑命令。
+- **看/操作别的工作区、别的设备上的终端**：`list_*` → `read_terminal` / `send_terminal_input`。
+- **不在 coflux 终端里**（比如用户在自己电脑上开的 Claude Code）时接入账号下的一切。
+
+### 没配 MCP 时
+
+先 `claude mcp list`（Codex：`codex mcp list`）看有没有 `coflux`。没有就告诉用户一行接入，
+地址用 `$COFLUX_MCP_URL`（它就是中心公网地址 + `/mcp`）：
+
+```sh
+claude mcp add --transport http coflux "$COFLUX_MCP_URL"     # Claude Code
+codex mcp add coflux --url "$COFLUX_MCP_URL"                 # Codex
+```
+
+之后宿主会引导用户在浏览器完成一次 OAuth 授权（Claude Code 里是 `/mcp`）。授权是用户的事，
+你只需要把地址和命令给他；没配好之前本工作区内的活照样用本地命令干。
+
+### 14 个 tools
+
+id 优先从 `COFLUX_*` 环境变量拿；跨出本工作区的 id 用 `list_*` 查。
+
+| tool | 用途 |
+|---|---|
+| `list_devices` | 账号下的设备（跑着 daemon 的机器）：id、名称、在线、版本 |
+| `list_projects` | 导入的项目（git 仓库）：id、所在设备、仓库路径、默认分支 |
+| `list_workspaces` | 工作区（主工作区 = 仓库本身，其余是 worktree；目录工作区 projectId 为 null），可按 projectId 筛 |
+| `list_terminals` | 终端：id、工作区、标题、状态 idle/running/exited、退出码，可按 workspaceId 筛 |
+| `read_terminal` | 读终端纯文本（去 ANSI，默认尾 200 行）：source=log 是命令终端的完整日志（退出后仍可读），snapshot 是当前画面，checkpoint 是设备离线时中心的最近快照 |
+| `list_ports` | 终端里检测到的监听端口 + 可直接打开的预览 URL |
+| `create_workspace` | 在项目下新建 git worktree 工作区（可新建分支），设备真在磁盘上建目录 |
+| `rename_workspace` | 改工作区名（纯展示） |
+| `remove_workspace` | 删 worktree 工作区：先关其下所有终端再 `git worktree remove --force`（未提交改动会丢）；主工作区不可删 |
+| `create_terminal` | 在某工作区开真实终端跑一条命令（用户可接管、侧栏可见），跑完带退出码；输出落日志供 `read_terminal` |
+| `send_terminal_input` | 往运行中的终端写文本（默认追加回车） |
+| `wait_terminal` | 有界等待终端退出并拿退出码（默认 30 秒、上限 50 秒） |
+| `stop_terminal` | 结束终端会话（等价 web 上的停止） |
+| `remove_terminal` | 删终端记录；运行中的必须先 `stop_terminal` |
+
+### 用 MCP 的三条纪律
+
+1. **人类优先**：`send_terminal_input` 在用户正在接管那个终端时会被拒，错误里写明
+   「用户正在接管」——把交互留给用户，不要重试；要沟通用本工作区的 `cofluxd notify`。
+   `send` 之前先 `read_terminal` 看清它在等什么；回执超时先 `read` 再决定要不要重发。
+2. **有界等待**：`wait_terminal` 最多等 50 秒，到期返回 `timedOut=true` 不是错误——需要更久
+   就再调一次，**别自己写轮询循环去 `read_terminal`**。`create_workspace` / `create_terminal`
+   最多等 30 秒启动回执，到期返回「已提交」并附 id，稍后用 `list_*` 查。
+3. **「需要升级」就停**：写 tools 在目标设备的 daemon 太旧时立即返回「该设备的 daemon 需要
+   升级」——这是能力门禁，不是暂时故障。转告用户在那台机器上 `cofluxd update && cofluxd restart`，
+   别重试也别换 tool 绕。
+
+本地命令的纪律（先 read 再 send、被拒即停、`progress` 与 `notify` 分界、用 `wait` 别轮询）
+在 MCP 里同样成立。
+
 ## 边界
 
 - 你能开、读、等、输入，但**输入是人类优先的受限写权**：用户正在接管的终端你写不进去
   （会被明确拒绝），用户随时接管也会把你顶掉。别和人抢终端。
-- 能看到的只有**你自己所在的工作区**，别的工作区和别的机器都看不见也碰不到。
+- 本地命令只看得见**你自己所在的工作区**；别的工作区和别的机器要经 MCP，且限于同一账号。
 - 一个工作区同时活着的终端有上限（默认 8，含用户自己开的）。撞上限先 `list` 看看，
   多半是有跑完没收的；真是用户占满了，就 `notify` 告诉他，别硬试。
-- 这些命令都要 daemon 连着中心才能用——毕竟「让用户看见」就是它们的全部意义。
+- 这些命令与 tools 都要 daemon 连着中心才能用——毕竟「让用户看见」就是它们的全部意义。
   连不上时会明确报错，不会默默降级。
+- `COFLUX_*` 变量只在 coflux 开出来的 PTY 里有；你自己 `export` 或改它们没有任何效果，
+  中心只认它自己下发的 id。