cli-bridge

cli-bridge — 为用户自己的 starchild 二进制文件签发 CLI 套件

此技能会在本地 clawd 上生成一个全新的 AKM 密钥（scope=chat:bridge:cli），然后向 sc-chatroom 注册该密钥，以换取一个简短的不透明代码（sc_xxxxxxxx）。交给用户的套件只包含这个简短代码——绝不包含 AKM 密钥，也不包含 Fly 机器 ID。

+----------------+   POST /agent/chat/stream   +-----------------+
| starchild CLI  |   Bearer sc_xxxxxxxx        | sc-chatroom     |
| (user laptop)  | --------------------------> | (gateway)       |
+----------------+                             +--------+--------+
                                                        |
                            resolves sc_… → AKM + container_id
                                                        |
                                                        v
                                          POST /chat/stream (Bearer sk_…
                                          + fly-force-instance-id)
                                          +----------------------+
                                          | user's own clawd     |
                                          | (Fly internal)       |
                                          +----------------------+

为什么使用简短代码，而不是原始 AKM？

早期版本会将 AKM 密钥和 Fly 机器 ID 直接写入套件。虽然可行，但有两个缺点——解码后会泄露路由元数据，而且任何持有过套件的人都会持有永久的 AKM 密钥。简短代码形式解决了这两个问题：

• 对套件进行 base64 解码后得到 {d, c:"", k:"sc_…", s, exp, l}——不含密钥，也不含 Fly 机器 ID。
• cli-revoke <sc_…> 只会使简短代码失效；底层 AKM 仍然有效（使用 cli-revoke --akm <prefix> 也将其一并撤销）。
• sc-chatroom 现在会在其数据库中保存 AKM 密钥。这是有意做出的信任边界调整——AKM 会留在 Fly 的内部网络中，而不是随着用户的笔记本电脑四处传递。

权限范围边界——请先阅读

cli-bridge 只覆盖一条路径：用户的本地 CLI 与该用户自己的 clawd 进行一对一通信。它不是加入聊天室的凭证。

使用场景	正确凭证	错误凭证
个人 CLI ↔ 自己的 clawd（本技能）	chat:bridge:cli AKM，由 sc_… 代码提供	—
加入 sc-chatroom 房间	通过 chatroom join 获取 chat:thread:chatroom-{room_id} AKM	chat:bridge:cli AKM
以访客身份浏览公开房间	无需凭证	任何 AKM

安装 CLI

本技能的其余部分假设 starchild 已位于用户的 $PATH 中——如果尚未安装，请先安装。

单行命令（自动检测操作系统和架构）

curl -fsSL https://workroom.iamstarchild.com/install/cli | bash

为 darwin/linux × arm64/amd64 选择合适的二进制文件，将其放到 $PATH 中（Apple Silicon 会安装到 /opt/homebrew/bin；Linux 会回退到 ~/.local/bin；只有目录不可由用户写入时才使用 sudo），如果安装目录原本不在 $PATH 中，则会修改用户的 shell rc 文件，并运行 starchild --version 进行自检。SHA256 etag 让重复运行成为低成本的“已是最新”无操作（HTTP 304，无需下载）。查看源代码： tools/install-cli.sh （__SERVER_URL__ 会在请求时重写）。

Homebrew

brew tap starchild/tap https://github.com/Starchild-ai-agent/homebrew-tap
brew trust starchild/tap
brew install starchild

starchild formula 提供 macOS（arm64 / amd64）和 Linux（arm64 / amd64） 二进制文件——brew install 会为主机选择合适的版本。该 formula 没有 bottle 块，因此安装时会运行一个小型 Ruby 脚本，从服务器（workroom.iamstarchild.com）下载预编译的二进制文件并将其放到 $PATH 中——无需本地编译。之后如需升级： brew update && brew upgrade starchild。

Linux 注意事项： Homebrew 本身可以在 Linux 上运行，但需要 Ruby 和构建工具链（一次性运行 apt install build-essential ruby，或安装对应发行版的软件包）。对于 Linux 主机，上面的单行命令会跳过这些步骤，功能完全相同，因此除非用户已经在使用 brew，否则建议优先使用它。starchild-app（桌面工作区）仅支持 macOS——该 formula 会从源代码构建（rust + node），且只有 macOS 构建有实际用途。

验证

starchild --version

如果刚运行完单行命令，而 shell 仍显示 command not found，请打开一个新终端——PATH 更新写入了 rc 文件，不会应用到当前会话。

先决条件

与 chatroom 相同：

• 已在此 clawd 中安装 AKM（POST /api/keys 在 loopback 上可正常工作）
• AKM 接受 scope="chat:bridge:cli"，且 /chat/stream 中间件允许该作用域使用任意 thread_id（已在 clawd 分支 aladdin/feat/akm-chatroom 中发布）
• sc-chatroom 使用包含 POST /cli-keys 的构建版本（migration 007+）
• 已设置 FLY_MACHINE_ID（或 CONTAINER_ID）环境变量
• CHATROOM_PUBLIC_URL 环境变量指向 sc-chatroom 网关（默认为 https://workroom.iamstarchild.com）
• CHATROOM_SERVER_URL 环境变量指向 Fly 内部的 sc-chatroom（默认为 http://sc-chatroom.internal:8080）

命令

cli-login — 创建新凭据包

python3 skills/cli-bridge/scripts/cli_login.py --label "my laptop"
python3 skills/cli-bridge/scripts/cli_login.py --label "codex-vm" --ttl-days 14

默认 TTL 为 90 天；最长为 365 天。输出是一行文本，用户可将其复制到 starchild login 中。该凭据包是不透明的 — sc-chatroom 会在每次调用时解析它。

cli-list — 显示有效凭据包

python3 skills/cli-bridge/scripts/cli_list.py
python3 skills/cli-bridge/scripts/cli_list.py --include-revoked

列出该用户在 sc-chatroom 上创建的所有 CLI 短码。列包括： 短码、签发时间、过期时间、使用次数、标签。

cli-revoke — 撤销凭据包

python3 skills/cli-bridge/scripts/cli_revoke.py sc_xxxxxxxx
python3 skills/cli-bridge/scripts/cli_revoke.py --akm sk_yyyyyy

默认情况下：在 sc-chatroom 上撤销该短码；底层 AKM 仍保持有效。 使用 --akm 时：也会撤销本地 clawd 上的 AKM，从而使所有由其授权的凭据包失效。

通过 agent-shell 使用本地 shell（CLI ≥ v0.2.0）

使用 --enable-shell 创建的 cli-login 凭据包也授权 Agent 在用户自己的机器上运行 shell 命令 — 例如“我的笔记本电脑上的 nginx 是否正在运行”、“整理 ~/Downloads”等。普通凭据包仅用于聊天桥接，不授予 shell 访问权限（见下文“默认关闭 shell”）。用户启动一个小型守护进程：

starchild agent-shell            # daemonizes; holds a WS open to your clawd
starchild agent-shell --foreground   # attach to the terminal for debugging
starchild agent-shell-stop       # stop the daemon

如果登录的凭据包未获授 shell 权限，agent-shell 会拒绝启动 — 它会提示用户获取 --enable-shell 凭据包，而不是连接到 clawd 会拒绝的通道。

该守护进程为单实例（pidfile + flock），仅支持 macOS/Linux。它会在启动时和定期自动更新；下载的二进制文件在替换前会使用内嵌的 Ed25519 发布密钥进行验证，因此恶意或遭 MITM 攻击的更新服务器无法向用户的机器推送任意代码。

工作原理：守护进程使用凭据包中的 sc_… 短码连接到 wss://<chatroom>/ws/cli-shell。sc-chatroom 解析短码，并将 WebSocket 反向代理到用户的 clawd 机器 — 它接受笔记本电脑发起的升级请求，使用 fly-force-instance-id 固定目标后，向 clawd 打开自己的上游 WS，并在两端之间转发字节（这不是 fly-replay：chatroom 和 clawd 是不同的 Fly 应用，跨应用重放会被拒绝并返回 403）。AKM 由服务端注入上游连接 — 不会到达笔记本电脑。clawd 在其 ShellHubService 中保持该连接；随后，仅当支持 shell 的笔记本电脑已连接时，才会向大模型开放 local_shell 工具，并通过套接字下发命令。

默认关闭 shell（能力门控）

除非传入 --enable-shell，否则 cli-login 不会授予 shell 权限。AKM 是权威的能力来源：clawd 会在 /ws/cli-shell 握手时读取它，并拒绝不具备 shell 能力的连接执行任何命令（#264）。因此，泄露的普通凭据包只是聊天凭证，绝不会导致本地 RCE。

• 授予 shell 权限：cli_login.py --label … --enable-shell → AKM capabilities: ["shell"]，凭据包包含 x: ["shell"]。
• 为现有的无 shell 凭据包升级：不能原地切换 — 创建新的 --enable-shell 凭据包，使用 starchild login 登录，然后通过 cli-revoke 撤销旧凭据包。权限提升始终需要重新签发。

Agent 开始时已知的信息（能力清单）

连接时，守护进程会发送一个 hello 帧，公布：

• 平台 — os（darwin/linux）、arch（arm64/amd64）和当前使用的 shell。这样，Agent 就知道它连接的是 BSD 还是 GNU 用户空间、 应该假定使用哪个包管理器等，不必再猜测 ps 的标志，或遇到 ps: illegal option 错误。
• 策略摘要 — mode（没有允许规则时为 default-deny，否则为 allowlist）、用户的 allowed 规则、明确的 denied_extra 规则， 以及始终生效的 builtin_denied 列表。
• 文件传输策略 — transfer_dir（始终允许使用的工作区）、 yolo 标志，以及来自 ~/.config/starchild/file-policy.toml 的 read_allow / write_allow glob 模式。只有当程序包包含 files 能力时才会显示。完整规则见下文“文件路径策略”；这里列出这些内容， 只是为了让 Agent 知道这台笔记本是否声明支持文件传输。

clawd 会将这些信息写入 Agent 的系统提示词（仅在连接期间）， 这样 Agent 就能选择获准执行的命令，或者明确告知用户本地策略禁止该操作， 而不是盲目尝试。

会话行为

• 连接级 cwd。 每个命令执行后的工作目录都会回传（通过从 stdout 中移除末尾的 pwd 哨兵），并保留为下一个命令的工作目录。因此，在一个 会话中的多次调用之间，cd 会产生实际效果，同时无需承担完整 PTY 带来的成本和脆弱性。每次调用显式指定的 cwd 会覆盖它。
• 输出截断。 stdout/stderr 各自最多保留 200 行（另有字节数上限）， 防止 find / 或日志转储淹没大模型上下文。系统会报告截断前的完整行数 （stdout_lines / stderr_lines），并设置 truncated: true，这样 Agent 可以说“显示前 200 行，共 N 行”，而不是悄悄截断。
• 心跳。 守护进程每 45 秒发送一次 ping，以保持空闲的 WebSocket 连接存活（Fly 的边缘节点会在约 2.5 分钟后切断空闲套接字）。命令执行在 goroutine 中进行，因此长时间运行的命令不会阻塞心跳。

本地执行策略（唯一的自动运行防护）

守护进程以无头模式运行（没有可用于提示的 TTY），因此每条命令都受 ~/.config/starchild/exec-policy.toml 控制（解析为精简的 YAML allow:/deny: 行格式——尽管名称如此，但不依赖 TOML）。 规则默认按子字符串匹配；将规则括在 / / 中即可使用正则表达式：

allow:
  - "ls"
  - "cat "
  - "/^git (status|log|diff)/"
  - "ps"
deny:
  - "git push"

判定顺序：内置拒绝（始终优先生效）→ 文件中的 deny → 文件中的 allow → 默认拒绝。 无论文件内容如何，以下两条硬规则始终适用：

• 内置拒绝列表中的交互式命令、阻塞 TTY 的命令和破坏性命令始终会被 拒绝：vim/vi/nano/emacs、 less/more/man、top/htop/btop、ssh/telnet、 sudo/su/doas、tmux/screen、reboot/shutdown/halt， 以及以下命令形式：rm -rf、mkfs、dd if=、… | sh、 … | bash、> /dev/sd*。
• 默认拒绝： 未匹配任何 allow 规则的命令一律拒绝。因此， 没有策略文件时，策略 mode 为 default-deny，用户明确允许命令之前， 不会执行任何命令。

限制

• 仅支持无人值守策略。 没有交互式审批提示；策略文件是唯一的防护措施。 未来版本将添加网页审批弹窗。
• 仅支持同步命令。 暂不支持后台任务或进度轮询。
• 仅支持 macOS/Linux。 守护进程拒绝在 Windows 上运行。
• 撤销： cli-revoke <sc_…> 会使短代码失效；守护进程下次重新连接时， 身份验证将失败，通道也会关闭。

通过 agent-shell 传输文件（CLI ≥ v0.3.0）

使用 --enable-files 创建捆绑包时，同一个 agent-shell 守护进程还会在用户的计算机和 Agent 的工作区之间提供文件传输。内容直接在磁盘之间流动，不会经过聊天，因此大型／二进制文件（10MB+ 的 PDF、图像、压缩包）也能正常传输。

三个面向 Agent 的工具 + 一条用户命令：

• request_upload(laptop_path) — Agent 将文件从笔记本电脑拉取到 workspace/uploads/（“拿我的 ~/big.pdf 并总结一下”）。
• write_local_file(src, dst) — Agent 将工作区文件发送到笔记本电脑（“将 workspace/output/report.pdf 保存到我的 ~/Downloads”）。src 是工作区路径，而不是内联内容。
• read_local_file(path) — 读取小型文本文件供 Agent 查看 （配置／日志片段）。大型／二进制文件通过 request_upload 传输。
• starchild push <file> — 用户主动将本地文件上传到 Agent 的 workspace/uploads/；上传后会在提示词中告知 Agent。

python3 skills/cli-bridge/scripts/cli_login.py --label "laptop" --enable-files
# combine with shell if you want both:
python3 skills/cli-bridge/scripts/cli_login.py --label "laptop" --enable-shell --enable-files

files 是与 shell 相互独立的能力 — 捆绑包可以启用其中任一项、两者都启用，或两者都不启用。与 shell 一样，它默认关闭，并由 AKM 权威控制（对于未启用此功能的连接，clawd 会拒绝传输帧）。

文件路径策略（笔记本电脑端，分层）

笔记本电脑上的路径策略会限制文件传输，规则按严格程度从高到低排列：

1. 始终拒绝访问内置受保护路径（即使使用 --yolo 也不例外）： ~/.ssh、~/.aws、shell rc（.zshrc／.bashrc／…）、.config/starchild、 launchd/systemd/cron、.git/hooks、浏览器 Cookie 存储、.env、SSH 密钥。写入这些位置会造成持久性远程代码执行；读取则会泄露凭据。

2. 专用传输目录（自动创建的 ~/starchild-transfer）——始终 允许读取和写入。它是安全的默认工作区；请优先使用。

3. 该目录以外的位置 — 除非路径匹配 ~/.config/starchild/file-policy.toml 中的 read_allow / write_allow glob，或者守护进程使用 --yolo 启动，否则一律拒绝：

   starchild agent-shell --yolo   # allow ANY path (built-in deny still applies)
   

   # ~/.config/starchild/file-policy.toml  (YAML allow-globs)
   read_allow:
     - "~/Documents/*.md"
   write_allow:
     - "~/exports/*.csv"
   

其他保障：写入的文件权限为 0644（绝不会设置为可执行）；写入采用原子操作（临时文件 + 重命名，不会产生未写完的目标文件）；会拒绝逃逸出传输目录的符号链接；每次传输上限为 100 MiB，并以分块方式流式传输，避免大型文件超出 WS 帧大小限制。

安全提示：正在运行的 agent-shell（对于启用了 --enable-shell 的捆绑包） 加上宽松的策略，实际上就相当于允许远程执行用户计算机上的命令，其权限受 AKM TTL、sc_… 代码的有效性以及 策略文件限制。默认设置较为保守：除非明确授权，否则 shell 处于关闭状态；在启用相应命令前，策略会拒绝所有操作；守护进程的自我更新会在替换二进制文件前验证 Ed25519 签名。请谨慎放宽限制。

通过 agent-shell 使用本地 MCP 服务（CLI ≥ v0.5.32）

agent-shell 就是用户计算机的 MCP Host。这个运行 local_shell 和文件传输的同一守护进程还会读取 ~/.config/starchild/mcp-servers.toml，将每个已启用的 stdio MCP 服务作为长期运行的子进程启动，执行 MCP initialize → tools/list 握手，并通过现有的 WebSocket 将 tools/call 代理到 clawd。随后，clawd 会将每个远程工具注册为 mcp__<server>__<tool>，并将其注入当前对话中 — 无需新建会话。

这是通过云端 Agent 驱动本地应用（Blender、Godot、本地 Figma 桥接、本地电脑操作、本地浏览器操作、文件系统服务等）的途径。Agent 无法通过其他方式访问用户计算机上的 localhost；clawd 自带的（直接）MCP 支持用于托管在其他位置的 远程／HTTP/SSE 服务，而非必须在用户笔记本电脑上运行的进程。

工作原理（控制通道与 local_shell 使用相同的 WS）

clawd (cloud agent)
  │  mcp_list / mcp_call frames
  │  (over the existing /ws/cli-shell WebSocket)
  ▼
agent-shell daemon (laptop) ── MCPProxy
  │  stdio JSON-RPC (newline-delimited)
  ▼
blender-mcp / figma-mcp / server-everything / … (one process per server)

笔记本电脑端负责管理 MCP 会话状态（initialize → initialized → tools/list，已缓存）。clawd 只发送高级 mcp_call，不会直接使用原始 JSON-RPC。服务器发出的 tools/list_changed 通知会触发重新获取并注册该服务器的工具。

配置服务器

编辑 ~/.config/starchild/mcp-servers.toml（尽管扩展名是 .toml，文件实际采用 YAML 格式，与 exec/file-policy 使用相同的约定）。每个条目：

servers:
  - id: blender
    command: uv
    args:
      - "--directory"
      - "/Users/aladdin/Workspace/StarChild/blender_mcp/mcp"
      - "run"
      - "blender-mcp"
    env:
      - "SOME_KEY=value"
    enabled: true

仅使用绝对路径。 不会展开 $HOME 和 ~——MCP 客户端会直接启动命令，而不会通过 shell 启动。请使用 /Users/<name>/...，切勿使用 ~/... 或 $HOME/...。

enabled 默认值为 true（没有 enabled: 的条目也会运行）。该文件支持热重载，但运行中的会话只有在守护进程重启后才会发生变化——重载会更新已解析的配置，不会在会话中途启动或终止服务器进程。应用的 Settings 面板会写入此文件，并代你重启 agent-shell。

重启 agent-shell 不会中断聊天

聊天流（你发给用户的回复）通过 clawd 的 HTTP/SSE 路径运行，而非通过 agent-shell。重启 agent-shell 只会在重新连接所需的约 2 秒内中断 local_shell / 文件传输 / mcp_call，对话本身会继续运行。因此，你可以告诉用户（或自行通过 local_shell 操作）在配置更改后重启守护进程，不会导致对话中断。

重启后，守护进程会发送一个新的 hello，其中的 mcp_manifest 会列出已启用的服务器及其各自的运行状态（ready/failed/not_started）。clawd 会立即对每个就绪的服务器调用 mcp_list 并注册工具。每轮调用时的 maybe_resync_local_mcp 补偿机制也会在后续轮次中处理那些在 hello 阶段获取失败的服务器（例如启动较慢的服务器）。

动态注入——local_mcp_status + local_mcp_reload

无需重启 agent-shell 即可应用配置更改。两个面向 Agent 的工具可实时驱动本地 MCP 运行时：

• local_mcp_status——返回每个已配置服务器的运行状态（ready 并附带工具数量、failed 并附带错误，或 not_started）。如果缺少预期的 mcp__<server>__* 工具，请调用此工具——服务器可能启动失败。
• local_mcp_reload——请求 agent-shell 在运行时重新读取 mcp-servers.toml，启动新增的服务器并停止已移除的服务器。无需重启守护进程，也不会中断聊天。 重载后，新增服务器的 mcp__<server>__* 工具会在下一轮出现（每次请求都会重新构建工具列表）。编辑配置后，使用此工具即可在无需让用户重启任何内容的情况下启用新服务器。

用户刚配置的服务器未显示工具时，通常按以下步骤操作：

1. 调用 local_mcp_status → 查看是否显示 blender: not_started 或 failed: …。 2.（如果状态为 failed，请修复配置，例如路径错误、缺少依赖等。）
2. 调用 local_mcp_reload → agent-shell 启动新服务器。
3. 下一轮，mcp__blender__* 工具就会注册。

Agent 能看到的内容

• 工具显示为 mcp__<server>__<tool>（例如 mcp__blender__get_scene、mcp__everything__echo）。它们的 description 和 input_schema 来自服务器自己的 tools/list——像调用任何原生工具一样调用它们。
• 提示词清单（build_mcp_manifest_section，位于易变尾部）会列出已连接的本地 MCP 服务器及其工具名称。如果服务器已配置但启动失败，这里也会注明（配置存在，未加载）。
• 如果你看不到预期的 mcp__<server>__* 工具，说明服务器没有启动。按以下顺序排查：
  1. 它是否已添加到 ~/.config/starchild/mcp-servers.toml，且设置了 enabled: true？
  2. 编辑后是否重启了 agent-shell？（配置会在启动时读取。）
  3. 守护进程日志（~/.starchild/sc-chatroom[-dev]/cli-shell/agent.log） 中每个服务器都有一行记录：成功时为 agent-shell: mcp: <id> ready (N tools)，失败时为 agent-shell: mcp: failed to start <id>: <reason>。通过 local_shell 读取。
  4. 对于需要本地应用桥接的服务器（Blender 的插件，监听 127.0.0.1:9876、Figma 插件等），也要确认桥接正在运行——MCP 服务器进程可以启动，但后端应用不可访问时，其工具会报错。

不要绕过 MCP 与本地应用通信

当 Blender 这样的服务器注册缓慢时，很容易想直接打开应用自己的桥接（127.0.0.1:9876）的原始套接字，直接发送 Python。不要这样做——这会绕过 MCP 工具层（没有架构、没有策略、没有逐次调用的验证），Agent 也会失去结构化的 mcp__blender__* 接口。应修复 MCP 服务器的启动问题（检查日志、确认桥接正常、重启 agent-shell）。原始桥接只能作为最后的备用方案。

服务器注意事项（按后端）

• Blender MCP（blender-mcp）：由两部分组成——stdio MCP 服务器 （uv run）和 Blender 插件的桥接（监听 127.0.0.1:9876）。两者都必须运行。即使 Blender 已关闭，MCP 服务器也会启动，但插件桥接启动前，每次工具调用都会报错。即使 Blender.app 已打开，which blender 也经常会失败——这没关系，关键是桥接。
• Figma：有两种不同的 Figma MCP。figma-mcp-server （REST 封装，只读画布）通过 bunx 在本地运行；官方 Figma 远程 MCP（可写画布、SSE）是远程服务——应在 clawd 端配置（在 agent.yaml 中设置 mcp_servers:），而不是在这里配置。此文件仅用于在笔记本电脑上运行的服务器。
• computer-use / browser-use：本质上是本地工具（它们会操作用户的屏幕／浏览器）。请在此处配置。

安全

本地 MCP 服务器可以在用户的机器上执行任意代码（Blender 的 execute_code、shell 服务器等）。添加条目到 mcp-servers.toml 时，应像放宽执行策略一样慎重：只添加用户要求的服务器，优先选择只读服务器，绝不要在聊天中填写密钥（API 密钥）——请使用 env: 字段。默认情况下，mcp-servers.toml 路径不在文件策略允许列表中；如果用户希望 Agent 直接写入配置，请将其添加到允许列表中。

端到端冒烟测试

# 1. Inside agent chat:
@agent give me a cli key for my laptop
# → outputs `starchild login starchild_<base64>` (bundle has sc_… code)

# 2. On laptop:
starchild login starchild_xxx
starchild whoami
starchild "hello, who are you?"
# → starchild sends Bearer sc_… to sc-chatroom; sc-chatroom resolves
# → it to AKM + container_id and forwards to user's clawd

# 3. Revoke the short code from chat:
@agent revoke cli code sc_xxxxxxxx

# 4. Next CLI call should fail at the gateway:
starchild "hello?"
# → "gateway rejected (401) — code may be revoked; ask your agent for a fresh CLI bundle"

管道／shell 组合（CLI ≥ v0.1.0）

配对后，starchild 支持管道输入。未提供位置提示词时，它会读取 stdin，将助手回复写入 stdout，并将诊断信息发送到 stderr——因此可以与任何 Unix 工具组合使用。

# stdin → reply
echo "explain monads in 3 lines" | starchild

# reply → downstream
starchild "what is the OWASP top 10?" | pbcopy

# full three-stage pipe with streaming output
( echo "summarize this README:"; cat README.md ) | starchild --stream | tee summary.md

# code review pattern — concatenate context + question upstream
( echo "review this diff, flag risky changes:"; git diff ) | starchild

注意：传入位置提示词时，stdin 会被忽略。 要同时发送上下文和指令，请使用 ( echo "<question>"; cat <file> ) 在上游进行拼接，而不要依赖 cat <file> | starchild "<question>"（这会静默丢弃文件内容）。

SOUL.md 提示（推荐）

将以下内容添加到 Agent 的 SOUL.md，以便大模型在用户询问 CLI 密钥时选用正确的工具：

## Issuing CLI bundles for the user's own bots/scripts

When the user asks "give me a cli key" / "create a starchild bundle" /
"let me talk to you from my terminal", run:

  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>"

This is a chat bridge only — it does NOT let you run commands on their
machine or touch their files. Two independent opt-in capabilities, each
granting local access — only add them when the user explicitly asks:

- `--enable-shell` → run commands ("run commands on my laptop", "use
  agent-shell", "organize my Downloads"). Remote command execution.
- `--enable-files` → read/write files ("save this to my laptop", "read my
  ~/notes.md"). Reads/writes files on their machine.

  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>" --enable-shell
  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>" --enable-files

Treat both as granting access to their machine — never add either by
default or "to be helpful". If they later want a capability, mint a new
bundle with the flag and have them revoke the old one.

Default the label to something like "untitled-YYYY-MM-DD" if the user
doesn't suggest one. Show them the resulting bundle and tell them how
to revoke: `cli-list` to find the code, then `cli-revoke sc_…`.

After pairing, mention they can also pipe into the CLI from their
shell — e.g. `echo "..." | starchild`, `starchild "..." | pbcopy`,
or `( echo "review:"; git diff ) | starchild`. Stdout is the reply
(pipe-safe), stderr is diagnostics. Note the gotcha: passing a
positional prompt makes stdin get ignored, so context + question
should be concatenated upstream.

## Driving a local app via MCP (agent-shell ≥ v0.5.32)

Once `--enable-shell` is granted and `agent-shell` is running, you can
also drive LOCAL apps (Blender, Godot, a local Figma-bridge,
computer-use, …) through stdio MCP servers. The agent-shell daemon IS
the MCP Host: it reads `~/.config/starchild/mcp-servers.toml`, spawns
the servers, and registers their tools as `mcp__<server>__<tool>` into
this conversation. No separate MCP client (Cursor/Claude Desktop) is
needed.

When the user asks "control Blender" / "use the local figma plugin" /
"drive my local <app> via MCP":
- Confirm `agent-shell` is connected (a `local_shell` call works).
- Add the server to `~/.config/starchild/mcp-servers.toml` (ABSOLUTE
  paths only — no `$HOME`, no `~`). The app's Settings → Local MCP
  Servers panel can do this too.
- Restart `agent-shell` (`starchild agent-shell-stop && starchild
  agent-shell`, or via the app's RestartBanner). This does NOT cut the
  chat — only `local_shell`/file-transfer pause for ~2s.
- After restart the `mcp__<server>__*` tools appear. If they don't,
  read the daemon log (`~/.starchild/sc-chatroom[-dev]/cli-shell/
  agent.log` — look for `mcp: <id> ready` or `mcp: failed to start
  <id>: <reason>`) via `local_shell`.
- For servers with a local app bridge (Blender's addon on
  127.0.0.1:9876), confirm that bridge is running too — the MCP server
  process can start but its tools error until the backend app is up.
- Prefer the `mcp__<server>__*` tools over opening a raw socket to the
  app's bridge. The MCP layer gives you schemas + validation; the raw
  bridge is a last-resort fallback.

Don't add a server the user didn't ask for — a local MCP server can
execute arbitrary code on their machine. See the "Local MCP servers via
agent-shell" section above for the full config format and per-backend
caveats (Blender two-part, Figma local-vs-remote, etc.).