用途
CCX Flow 用于在 Claude Code（CC）主会话与外部长期运行进程之间建立上下文注入通道。外部进程可以通过本地 HTTP 请求，把文本上下文注入当前 CC 主会话，无需 patch CC 二进制，也不需要启动新的 CC 实例。
主要能力
- 启用 Flow：为当前会话注册并启动 Flow Bridge，使其能够接收外部注入请求。
- 关闭 Flow（--off）：清理由 cc-expand 管理的资源，包括 bridge 进程、CC team 目录和注册表文件。
- 会话级隔离：按 Session ID 前 8 位生成 sessionShortId，使用独立端口、token 与注册表文件。
- 复用已有实例：若注册表中已有存活进程，直接复用其 port/token/pid。
关键概念
- 完整 Session ID：环境变量 CLAUDE_SESSION_ID 的值。
- 项目根目录：优先取 git 仓库顶层目录，回退为当前工作目录。
- Flow 注册表目录：<project-root>/.tmp/ccx-flow/。
- skill-path：通常为 ~/.claude/skills。
- Flow Bridge 产物：<skill-path>/scripts/flow-bootstrap.js 与 <skill-path>/scripts/flow-bridge.js。
使用方式（启用 Flow）
- 计算 sessionShortId = CLAUDE_SESSION_ID 的前 8 位。
- 计算稳定端口：
port = !npx @lionad/port-key ccx-flow-${CLAUDE_SESSION_ID.slice(0, 8)}
- 生成随机 token：
token = !node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
- 检查注册表文件 <project-root>/.tmp/ccx-flow/<sessionShortId>.json 是否存在且对应进程仍存活：
- 若存在且 pid 存活，跳到第 7 步，用注册表中已有的 port/token/pid 告知用户。
- 若不存在或 pid 已死，继续下一步。
- 调用 TeamCreateTool 创建 team：
{ "operation": "spawnTeam", "team_name": "ccx-flow-<sessionShortId>" }
记录返回的 team_name（CC 可能对其唯一化，后续步骤使用返回的名字）。
- 调用 AgentTool 创建占位 teammate ccx-flow-bridge：
{ "description": "CCX Flow placeholder teammate", "prompt": "You are ccx-flow-bridge, a placeholder teammate. Do not perform any tasks, do not call tools, do not send messages. Stay idle and wait. Acknowledge once with a single 'OK' and then remain silent.", "name": "ccx-flow-bridge", "team_name": "<teamName>", "model": "haiku", "run_in_background": true }
- 启动 Flow Bridge：
node <skill-path>/scripts/flow-bootstrap.js
--team <teamName>
--port <port>
--token <token>
--session-id ${CLAUDE_SESSION_ID}
--registry <project-root>/.tmp/ccx-flow/<sessionShortId>.json
- 如果注册表中已有存活进程，输出为 FLOW_BRIDGE_ALREADY_RUNNING ...。
- 否则输出为 FLOW_BRIDGE_STARTED ...。
- 从输出中提取实际 port、token、pid，告知用户，并给出 curl 示例：
curl -X POST http://127.0.0.1:<port>/inject
-H "Authorization: Bearer <token>"
-H "Content-Type: application/json"
-d '{"text": "Current hour: 14:00, system load normal."}'
使用方式（关闭 Flow，--off）
当用户调用 /ccx-flow --off 时：
- 读取 <project-root>/.tmp/ccx-flow/ 下所有注册表文件。
- 对每个注册表 entry：
- kill 其 bridge 进程（先 SIGTERM，2 秒后未退出则 SIGKILL）。
- 删除对应的 CC team 目录（~/.claude/teams/<sanitized-team-name>）。
- 删除注册表文件。
- 向用户汇报清理了哪些 session。
注意：--off 只清理 cc-expand 管理的资源，不会停止用户自己的第三方 Flow 进程。
安全边界
- Flow Bridge 只监听 127.0.0.1。
- 每次请求必须携带 Authorization: Bearer <token>。
- 注入的文本以普通 teammate_message XML 进入主会话，LLM 按自然语言理解；它不会自动执行 slash command、TeamDeleteTool 或 kill teammate。
适用场景
需要由外部长期运行进程持续向当前 Claude Code 主会话补充上下文（例如运行状态、时间、系统负载等）的场景。
限制
- 仅监听本地回环地址 127.0.0.1。
- 需要 Bearer token 鉴权。
- 注入内容不会自动触发 slash command 或危险工具调用。
- --off 不清理第三方 Flow 进程。
- 其他细节（如平台兼容性、计费、具体版本要求）暂未提供。