codeflow

Codeflow

将实时编码代理会话流式传输至 Discord 或 Telegram。零 AI Token 消耗。

重要说明：

• 命令名称：/codeflow
• 环境变量前缀：CODEFLOW_*

初始化配置

首次配置：请参阅 [references/setup.md](references/setup.md)，了解 webhook 创建、unbuffer 安装、机器人 Token 及冒烟测试（smoke test）。

如需实现硬性线程作用域强制策略（即技能专属的 /codeflow + 插件级工具调用拦截），请在宿主机上一次性安装捆绑的 enforcer 插件：

bash {baseDir}/scripts/codeflow enforcer install --restart

若该插件未安装，/codeflow 仍可在软模式下运行。按钮/无按钮行为必须由确定性路由脚本（deterministic router script）控制，不得交由自由形式的助手文本（free-form assistant prose）决定。

开发者检查（可选）

运行本地完整性校验套件（Python 语法编译 + 单元测试 + bash -n 静态检查）：

bash {baseDir}/scripts/codeflow check

/codeflow 命令契约（会话作用域）

当用户调用 /codeflow 时，应首先将其视为 控制命令（control command），其次才是会话作用域的声明：

1. 对于当前 OpenClaw 会话，所有编码、开发或评审任务（包括代码/架构/安全/产品评审），以及任何直接调用 Codex 或 Claude Code 的行为，必须通过 Codeflow 中继 + 本地 Codex/Claude Code 执行（除非用户明确要求直接编辑，否则禁止直接修改）。
2. 遵循 Codeflow 输出规范（在适用时包含紧凑型 Telegram 行为）。
3. 若用户请求的是非代码类任务（如文档撰写、会议安排等），按常规方式处理；本契约仅适用于编码、开发与评审类任务。
4. 该契约持续至当前会话上下文结束。若用户重置会话或开启新会话，则需重新调用 /codeflow。

重要命令顺序规则：

• 纯控制消息（如 /codeflow、/codeflow on、/codeflow status、/codeflow off 或 callback_data: cfe:install）不构成编码任务请求。
• 对此类控制消息，切勿发送通用确认语句（例如 “已就绪，请指示下一步操作？”）。
• 必须首先执行下方确定性控制路由器（deterministic control router）。
• 若路由器执行成功，则以 NO_REPLY 结束本轮响应（因路由器已自行向用户发送面向用户的控制回复）。
• 此后，同一会话中后续出现的编码任务才需在 Codeflow 契约下执行。
• 若同一条入站消息中同时包含 /codeflow 命令与实际编码任务内容，则先执行控制路由器，再继续处理剩余任务文本。

软回退契约（soft fallback contract）：

• /codeflow 始终由技能（skill）拥有。这是公开入口点，也是软回退路径。
• 捆绑的 enforcer 插件为可选组件。安装后，它会在技能流程之上增加硬性的 before_prompt_build / before_tool_call 拦截；但它并不拥有 /codeflow 命令本身。
• 步骤 0）调用 session_status，读取当前 OpenClaw 对话的 sessionKey。
• 步骤 1）始终运行确定性控制脚本：

bash {baseDir}/scripts/codeflow control \
  --session-key "" \
  --text ""

• 该脚本负责处理以下情形：

  • /codeflow 或 /codeflow on|enable|activate
  • /codeflow status
  • /codeflow off|disable|deactivate
  • callback_data: cfe:install（或原始字符串 cfe:install）
• 对纯 /codeflow 消息，必须首先路由至此脚本，禁止自行构造文本回复。

• 该脚本自行完成全部实质性工作：

  • 在需要时运行 codeflow guard activate|deactivate
  • 运行 codeflow enforcer status --json --session-key
  • 自行通过 Gateway 的 message.send 发送最终消息
  • 当 Telegram 路由可用时，包含 recommendation.buttons
  • 当无法发送按钮时，自动降级为纯文本 Install: / Restart: 命令
• 正常路径：脚本已发送面向用户的回复，因此本轮响应以 NO_REPLY 结束。
• 回退路径：若脚本以退出码 3 退出，且 stdout 以 NEED_LLM_ROUTE 开头，则解析下一行的 JSON 负载（格式为 {message, buttons}）并由你自行发送。若当前渠道/工具不支持附加按钮，请严格保留所提供的纯文本内容。
• 安装器说明：处理 cfe:install 时，请明确告知用户，网关重启可能导致当前对话/线程中断或重置。

守卫（Guard）强制机制（脚本内硬约束）：

• 所有可提交/执行工作的执行模式（run、resume、review、parallel）默认受守卫保护。review 和 parallel 必须在克隆仓库、创建工作树或发布启动摘要前完成守卫预检。
• 守卫管理命令（codeflow guard activate|deactivate|status|current）绕过预检。
• 守卫绑定至聊天/主题上下文（并在可用时关联 session key）。
• 每次允许/拒绝决策均追加至 ${XDG_STATE_HOME:-$HOME/.local/state}/codeflow/guard-audit.jsonl（仅存储 commandHint —— 已脱敏并截断；绝不记录完整命令）。
• 若被拦截，请提示用户在同一聊天/主题中重新运行 /codeflow。

默认推断规则（仅在存在歧义时询问）：

• 任务内容：缺失时需向用户询问。
• 工作目录（Workdir）：从近期聊天/上下文/任务历史中推断（不可盲目使用当前 workspace）。若不明确，应请用户重新声明工作目录。
• 平台（Platform）：根据当前渠道（Telegram/Discord）推断。
• 目标聊天/线程（Target chat/thread）：根据入站元数据（当前聊天/线程）推断。

/codeflow 下的 Codex 会话策略：

• 在可用时，复用与相同 -w 关联的先前 Codex 会话（以 realpath(workdir) 为键）。
• 若未找到先前会话，则在任务分派时创建新会话。
• 仅当用户显式请求时，才强制新建会话。

在 /codeflow 下，若工作目录/平台/聊天目标可从上下文中推导，则避免主动询问。

调用方式

使用 exec background:true 启动。后台 exec 会话可跨代理轮次（agent turns）持续存在。退出通知（如 notifyOnExit）由宿主运行时（OpenClaw）提供，而非 Codeflow 自身。

exec background:true command:"cat 

Prompt 引用技巧（规避 Shell 转义陷阱）：

• 对 Codex，codex exec（及 codex exec resume）在 PROMPT 为 -（或 exec 中省略）时从 stdin 读取 prompt。对于多行 prompt 或含 Shell 元字符（如反引号）的 prompt，推荐使用 stdin + 引号包裹的 heredoc。
• 对 Claude Code，claude -p 同样支持从 stdin 读取 prompt；出于相同原因，也推荐使用 stdin 方式。

注意响应中返回的会话 ID —— 可用于通过 process 命令进行监控。

CLI（稳定接口）

公共入口点（请勿直接调用 _internal/ 脚本）：

bash {baseDir}/scripts/codeflow  [...]

支持的命令：

• codeflow run [run-flags] -- — 启动中继会话
• codeflow guard activate|deactivate|status|current [run-flags] — 管理/查询会话级守卫
• codeflow control --session-key --text — 确定性 /codeflow 软模式控制路由器
• codeflow resume [run-flags] — 从 stream.jsonl 重放先前会话
• codeflow review [...] — PR 评审模式
• codeflow parallel [...] — 并行任务模式
• codeflow bridge [...] — Discord 网关桥接器
• codeflow enforcer install|update|uninstall|status [--json] — 管理/查询捆绑的 OpenClaw enforcer 插件
• codeflow check — 本地检查（语法 + 单元测试）
• codeflow smoke — 配置/前置条件冒烟测试

查看权威 CLI 文档，请运行：bash {baseDir}/scripts/codeflow --help

运行标志（codeflow run）

Prompt 模式亦可通过环境变量设置：CODEFLOW_PROMPT_MODE=auto|argv|stdin（默认：auto）。

限速说明（Telegram 加固）：parse-stream 现在将所有投递统一经由进程内 投递治理器（delivery governor） 处理，并严格执行 429 错误应对：

• Telegram 429 退避：next_allowed_at = now + retry_after + 1s（严格遵循 Telegram 返回的 retry_after；额外 +1s 以避免立即再次触发 429）
• 在 next_allowed_at 之前不得发送任何请求
• 队列优先级：final > event > state
• 紧凑型 state 卡片（thinking/cmd）采用严格快照覆盖（latest-wins）；在 429 窗口期间，更新在内存中合并，仅窗口开启后应用最新快照

若仍需进一步降低输出量，可结合使用 CODEFLOW_OUTPUT_MODE（见下文）及现有调节项（--skip-reads、CODEFLOW_SAFE_MODE=true、CODEFLOW_COMPACT）。

关于 PR 评审、并行任务、Discord 桥接及 Codex 结构化输出，请参阅 [references/advanced-modes.md](references/advanced-modes.md)。

代理启动检查清单

1. 启动后台会话 → 记录 exec 响应中的会话 ID
2. codeflow run 自动发布会话头部并流式推送事件至目标频道
3. 监控：使用 process log / process poll；终止：使用 process kill

完成检测

完成通知依赖于运行时（OpenClaw）。Codeflow 本身仅在内部代理命令退出时即退出。

备用方案：在内部代理的 prompt 末尾追加以下语句，作为额外完成信号：

当完全完成时，执行：openclaw system event --text "Done: " --mode now

监控命令

process poll sessionId:        # 检查状态
process log sessionId:         # 查看最近输出
process kill sessionId:        # 停止会话

安全模式（可选）

若将中继输出流式传输至共享频道，请启用：

• CODEFLOW_SAFE_MODE=true

效果：

• 抑制文件内容预览（Claude Write）
• 抑制命令输出正文（Claude Bash 输出、Codex command_execution 输出、原始模式输出）
• 对高风险字段应用更严格的脱敏处理

输出模式

通过环境变量控制频道发布内容的详细程度：

• CODEFLOW_OUTPUT_MODE=minimal|balanced|verbose（默认：balanced）

  • minimal：仅输出 warning/error/final
  • balanced：关键进度 + warning/error/final
  • verbose：近乎全量（调试用途；Telegram 更易触发 429）

Telegram 紧凑型状态卡片（严格快照覆盖）：

• thinking/cmd 卡片始终 edit 同一锚点（不产生额外帖子）
• 每次 edit 替换整个快照（无累积日志）；在 429 窗口期间，更新在内存中合并（latest-wins），仅窗口开启后应用最新快照
• 仅当消息超出平台限制时，才进行截断/压缩并标记 …(truncated)；否则不折叠/隐藏内容

Telegram 反垃圾邮件模式（默认启用）

当使用 -P telegram 时，Codex 会话默认以紧凑模式运行：

• 每轮仅一个滚动“思考中”消息（原地编辑）
• 每轮仅一个滚动“命令/结果”消息（原地编辑）
• 一个独立的轮次完成输出消息（全文；超长时分页）

下一轮开始时，重新初始化一对滚动消息。

可通过环境变量覆盖：

• CODEFLOW_COMPACT=true|false（默认 auto，Telegram 场景下为 true）

Telegram 429 / 锚点稳定性（紧凑模式）：

• 编辑失败不会“立即发布新锚点”（避免锚点爆炸）；状态卡片维持单一锚点编辑语义
• 触发 429 时，Codeflow 休眠 retry_after + 1s（非固定 10s）；窗口开启后按优先级刷新（final > event > state）

Telegram 适配器内存防护（超大消息编辑组）：

• CODEFLOW_TELEGRAM_EDIT_GROUPS_MAX=：最多跟踪的组数（LRU 策略，默认 64；设为 0 则禁用跟踪）
• CODEFLOW_TELEGRAM_TRACK_EDIT_GROUPS=true|false：启用/禁用跟踪（默认 true）

说明：

• 此设置仅影响 platforms/telegram.py 中 edit() 的多消息编辑；紧凑模式使用 edit_single，不受影响。
• 禁用跟踪意味着 edit() 无法删除/覆盖已拆分帖子的先前尾部消息。

Codex 会话复用策略（硬性工作流约束）

对 codex exec ...，Codeflow 在代码层面强制执行会话策略（而不仅限于文档说明）：

• 默认 auto：若存在，复用同一工作目录的先前 Codex 会话
• 若 prompt 中含 /new（auto 模式下）：对该次运行强制新建会话
• --new-session：强制新建会话
• --reuse-session：强制复用并恢复先前会话（若不存在则报错）

可选环境变量覆盖：

• CODEFLOW_CODEX_SESSION_MODE=auto|new|reuse（默认 auto）
• CODEFLOW_CODEX_SESSION_MAP=/tmp/dev-relay-codex-sessions.json（会话映射路径）

代理支持情况

会话追踪

• 活跃会话：/tmp/dev-relay-sessions/.json（结束时自动移除）
• 事件日志：/tmp/dev-relay.XXXXXX/stream.jsonl（7 天自动清理）
• 流日志策略：CODEFLOW_STREAM_LOG=full|redacted|off（默认：full；若 CODEFLOW_SAFE_MODE=true 且 CODEFLOW_STREAM_LOG 未设置，则默认为 redacted）。off 仅写入最小元数据（恢复/调试能力受限）。
• 投递异常事件：以 codeflow.delivery.* 形式追加至 stream.jsonl（仅异常；不含消息体/Token/URL）。
• 投递统计（本地）：/tmp/dev-relay.XXXXXX/delivery-summary.json（单文件摘要；含限速计数、丢弃数等）。
• 守卫状态：${XDG_STATE_HOME:-$HOME/.local/state}/codeflow/guard.json（仅存储 commandHint —— 已脱敏 + 截断）
• 守卫审计日志：${XDG_STATE_HOME:-$HOME/.local/state}/codeflow/guard-audit.jsonl（JSONL 格式）

• 交互式输入：process submit sessionId: data:"message"

  • 若 XDG 状态目录不可写，守卫/状态/审计日志将回退至 {baseDir}/scripts/ 下的点文件（详见 codeflow/scripts/_internal/bin/lib.sh）。
• Telegram/Discord 投递不再派生 curl 子进程；Token/Webhook 不出现在子进程 argv 中（避免 ps 泄露）。
• /tmp/dev-relay-sessions/.json 以原子方式写入（临时文件 + rename，尽力 fsync）并最小化（不持久化完整命令/上下文）。

参考文档

• [配置指南](references/setup.md) — 首次安装、webhook、机器人 Token
• [高级模式](references/advanced-modes.md) — PR 评审、并行任务、Discord 桥接、Codex
• [Discord 输出](references/discord-output.md) — 消息格式、架构、环境变量、故障排查