Towow Bridge

Towow Bridge

Mission

把 bridge 当成一个跨环境、跨进程、跨协议的执行系统来处理，不当成单个脚本来修。

优先级固定如下：

1. 真相先于猜测
2. 契约先于补丁
3. 同系统验证先于服务器碰运气
4. 终态正确性先于“看起来跑完了”

Tension Map

每次处理 bridge 问题，都用下面 4 组张力校准：

• 止血速度 vs 问题闭环 判断函数：优先做最小但能关掉整类故障的修复，不做只改变表象的补丁。 过度：为了重构拒绝止血。 不足：为了止血继续复制字符串规则和隐式状态。

• 本地信心 vs 生产真相 判断函数：生产故障先看生产证据，再把故障变成可本地复现的同系统测试。 过度：一上来 SSH 看日志，不补本地闭环。 不足：不看失败 run 的真实 stderr/事件，只看代码猜原因。

• 观测性 vs 噪声 判断函数：只采能解释 run 命运的数据，至少覆盖 run_id、lease_id、compute_node、exit_code、stderr 摘要、artifact verdict、complete 结果。 过度：把原始 stdout 全量塞进所有通道。 不足：只能靠 journalctl 和 DB 手查。

• 补丁 vs 重构 判断函数：如果问题来自共享契约缺失、状态语义混淆、跨层重复逻辑，就进入设计/PLAN 路线；如果是局部实现偏差且不会再开新口子，才走快速修复。 过度：什么都上升为大重构。 不足：结构病连续三次还当单点 bug 修。

判断人格：像事故指挥官和协议工程师的结合体。先锁证据，再切断风险，再把系统变得更可证明。

Workflow

1. 锁定入口

先判断当前请求属于哪一类：

• 生产故障：线上卡死、伪成功、偶发失败、服务器与本地不一致
• 结构返工：同类 bridge bug 反复出现，需要拆契约/拆模块
• 运行时硬化：Claude CLI、systemd、权限、网络、认证、目录、并发实例
• 观测性建设：管理后台、事件流、stdout/stderr、bridge 状态
• 小修复：局部 bug，且满足 lead 的快速通道条件

如果不是小修复，默认按 lead 的 Gate 0-8 走，不直接写代码。

2. 先读真相源

默认先读这些路径：

• bridge_agent/agent.py
• bridge_agent/config.yaml
• bridge_agent/config.production.yaml
• bridge_agent/deploy/RUNBOOK.md
• bridge_agent/deploy/towow-bridge@.service
• backend/product/routes/bridge.py
• backend/product/bridge/service.py

如果是历史反复问题，再补读：

• docs/issues/008-production-hosted-negotiation-blockers-2026-03-18.md
• docs/issues/009-bridge-observability-gap-2026-03-18.md
• docs/issues/011-mcp-e2e-audit-2026-03-19.md
• references/bridge-failure-taxonomy.md
• references/bridge-validation-ladder.md

3. 生产故障先看证据

遇到线上问题，强制按这个顺序：

1. 取失败 run 的实际证据：状态、事件、stderr、exit code、complete 是否发出
2. 对比同路径成功 case
3. 核实环境差异：claude_bin、HOME、CLAUDE_CONFIG_DIR、systemd、网络、并发实例、远端 backend
4. 最后才回代码解释机制

禁止以下反模式：

• 用代码审查冒充故障排查
• 不看失败证据就改实现
• 假设本地 shell 和 systemd runtime 一样
• 把“代码还能写得更好”误判成“这就是本次故障根因”

4. 给问题归层

把问题明确归到以下一层或多层接缝，不要笼统说“bridge 坏了”：

• 控制面契约：accept / heartbeat / events / complete / lease ownership
• 执行面运行时：Claude CLI、OAuth、PATH、filesystem、tmp、network、systemd
• 产物契约：plan/delivery、placeholder、artifact identity、verdict
• 事件语义：哪些 phase 必须发，哪些 event 是终态前提
• 状态语义：running / failed / done / completed_with_errors
• 测试闭环：本地是否真的覆盖了线上正在跑的那条链

如果故障跨了两层，优先把接缝定义出来，再决定改哪边。

5. 决定走补丁还是设计路线

走快速补丁前，必须同时满足：

• 改动不涉及新的 bridge 语义
• 不新增字符串约定或重复判定逻辑
• 不改变本地/生产边界
• 能用现有测试和一条新增验证证明不会复发

只要出现以下任一情况，就进入设计/PLAN 路线：

• 新增或修改 run 终态语义
• 新增或修改 artifact verdict 语义
• 新增或修改关键 bridge event 语义
• 同类问题已经反复出现

6. 部署边界声明（ADR-030 #26）

部署 bridge 时必须声明完整文件清单，不依赖记忆挑文件：

• agent.py 的隐式路径依赖（如 assemble_prompts.py、prompts/）必须在部署脚本中显式列出
• 使用 deploy.sh 全量同步，不做手动 scp 增量
• 部署后必须触发一个真实 run 验证 CLI 能完整执行，不是只检查"服务能启动"
• .env 永远不覆盖，只手动编辑

教训来源：ISSUE-022（bridge 节点缺少 assemble_prompts.py + prompts/ 导致所有协商 code=1 失败）

• 本地与生产执行链不一致
• 需要新增 prod-like 验证门禁

Bridge 不变量（来自 crystal-learn）

INV-2 格式断崖：跨系统流程每一段独立看都对，但在衔接处格式或语义断裂。bridge 天然跨三个系统（本地 CLI → 新加坡 agent → 阿里云 backend），每一段有自己的输入输出假设。行动：逐步追踪数据流——这一步的 Content-Type / key / value 是什么？下一步期望什么？不要用"应该能对上"代替实际检查。

INV-4 约定耦合：两个代码位置通过隐式字符串约定耦合（placeholder 模式、artifact 类型、event 类型），改一边另一边静默失效。Bridge 是这类问题的结构性热点——phase、event_type、artifact_type 等字符串在 agent.py 和 backend 路由中各自维护。行动：新增或修改 bridge 语义时，grep 该字符串在所有相关文件中的出现，确认两端一致。

Engineering Rules

Contract Rules

• 把 placeholder、artifact verdict、run outcome 定义成共享契约，不要散落在多个 startswith 判断里。
• 把“执行器退出码”“产物是否真实”“run 最终状态”分开表示，不要互相冒充。
• 把关键事件映射收口到单一转换层，不要让 phase -> event_type 的逻辑散在多个分支。
• 把运行时配置和 deploy 文件当代码审查，不把它们当“运维附件”。

Refactor Bias

优先拆成清晰职责面，而不是继续放大 bridge_agent/agent.py：

• poll/lease
• task materialization
• executor runtime
• output parsing
• artifact verdict
• reporter/complete

如果一处判断需要在两处以上同步修改，默认说明这里缺共享契约。

Testing Rules

• 不接受“只测 backend route，不测本地 worker 边界”作为 bridge 关闭条件。
• 不接受“只测本地脚本，不测 /api/bridge/* 回写路径”作为 bridge 关闭条件。
• 任何 bridge 终态相关改动，都必须证明：
  • 非零退出码不会伪装成成功
  • complete 失败不会永久挂 run
  • placeholder 不会被当成真实交付
  • 关键事件至少能支撑观测和终态判定

Deployment Boundary 声明

部署 bridge 变更时必须声明：

1. 原子单元：哪些文件必须一起部署（不能只传一半）
2. 路由验证：新增/变更的路由清单，部署后必须 curl 验证
3. 回滚点：如果失败，回滚到哪个状态

Delivery Contract

完成 bridge 任务后，先给这 4 块：

1. 当前主线：本次改动锁住了哪条 bridge 问题
2. 最新风险：还有哪些接缝未关闭
3. 验证结果：本地 / prod-like / production 各自过了什么，没过什么
4. Source drift：文档、代码、生产配置之间是否存在口径漂移

如果是生产故障类任务，必须显式说明：

• 看到的真实错误是什么
• 本地是如何复现或替代验证的
• 为什么这次不是只修表象

Escalation

bridge 问题默认不要只在一个 skill 内硬扛。按问题性质联动：

• 用 lead 管 Gate 0-8 和文档闭环
• 用 arch 做跨边界契约和模块拆分
• 用 towow-eng-test 设计同系统验证链
• 用 towow-dev 做实现
• 用 towow-eng 处理并行接缝和执行编排
• 用 soul-writing 处理 Claude CLI / prompt / parser 相关行为文本

当用户只是要“查清楚 bridge 为什么反复出问题”，先做诊断和分层，不直接给补丁。