loom-bridge — CodexLoom→Claude Code 实时执行桥:persistent Monitor 双流监听 + claude-code: 任务协议 + subagent 执行

loom-bridge-1-SKILL.md

name	loom-bridge
description	在当前 Claude Code 会话挂起 CodexLoom→Claude Code 实时执行桥:persistent Monitor 双流监听 CodexLoom 消息(comms.ndjson + agent 线程 userMessage),捕获 `claude-code:` 任务简报, spawn subagent 执行,以 `claude-code-result:` 回帖。Use when 用户说 /loom-bridge、挂桥、 接 codexloom 任务、监听 loom、bridge waiting、把这个会话变成执行桥。 Exclude:CodexLoom 服务本体的配置/重启、Codex model provider 配置、把桥固化为系统服务。
metadata	owner validated Peng Xiao 2026-08-05(三轮闭环:协议公告→自测任务→结果回帖,误报两类已修)

Copyright (c) 2026 Peng Xiao

loom-bridge — CodexLoom → Claude Code 执行桥

CodexLoom 的 Codex agent 受 sandbox 限制(实测:worktree 内 git add 被拒 index.lock: Operation not permitted),需要完整仓库权限或项目技能的执行由本桥承接。 桥 = 本会话的一个 persistent Monitor(等待期 0 token)+ 任务处理纪律。

前置探活

curl -s -m 3 localhost:4870/api/version | head -c 80   # CodexLoom 实例在跑
ls ~/.codex-loom/comms.ndjson ~/.codex-loom/events/     # 数据流存在

任一失败:报告用户,不挂桥。

挂桥

用 Monitor 工具(persistent: true),command 如下(过滤逻辑在脚本里,勿内联复制):

tail -n 0 -F ~/.codex-loom/comms.ndjson ~/.codex-loom/events/*.ndjson 2>/dev/null \
  | python3 ~/.claude/skills/loom-bridge/scripts/monitor_filter.py

description 建议:loom-bridge:claude-code 任务监听(双流)。 挂好后告知用户:桥已上线,等待期零消耗,事件即唤醒。

任务处理循环(每个 Monitor 事件)

1. 解析事件行四字段:任务详情 / 契约引用 / 工作路径 / 验收标准。
2. 缺字段:用 scripts/loom_send.py 回帖点名缺口,要求补发,本轮结束。不猜。
3. 齐全:spawn 一个一次性 subagent 执行(模型分层:实现类 Sonnet、难调试 Opus、 机械活 Haiku,绝不 Fable)。简报必须自包含——把四字段原文 + 相关文件路径写进 subagent prompt;subagent 与 CodexLoom 线程零共享上下文。
4. 验证后回帖:claude-code-result: 前缀 + commit hash / 测试结果 / 一段摘要。 回帖正文不得出现裸 claude-code: 字样(防自触发)。
5. 主会话只保留事件行与结果摘要,过程细节留在 subagent。

消息协议(与三个 agent Profile 中的约定一致)

任务方(agent 或 Owner)发消息,正文含:

claude-code: <一句话任务>
- 任务详情: <做什么、边界>
- 契约引用: <commit/文档路径>
- 工作路径: <绝对路径 + 分支>
- 验收标准: <怎么算完成>

回帖工具:

python3 ~/.claude/skills/loom-bridge/scripts/loom_send.py --topic <topic_id> "<text>"
# topic_id 缺省读 env LOOM_TOPIC;409 自动重试(responsible agent 忙)

已知坑(均为 2026-08-05 实测)

1. Owner 的 topic send 不进 comms.ndjson——只落 responsible agent 线程的 userMessage。双流监听即为此而设,不可退回单看 comms。
2. 投递的 userMessage 附带 <loom_context> 编译上下文,内含历史消息,历史里的 marker 会误触发。过滤脚本先截 <loom_context 再匹配,勿移除该逻辑。
3. topic send 409 = responsible agent 正在 turn 中,10 秒间隔重试即可,非错误。
4. 谈论协议本身也会触发——给 agent 的指令里写出带冒号的完整 marker 即命中过滤器 (2026-08-05 实测误触发)。指代协议时写"claude-code 前缀"(无冒号)或"桥协议"。

执行边界

• 不 push 远端、不动 cloud 资源、不做生产发布——这些回帖说明后转 Owner。
• 破坏性/不可逆操作:回帖要求 Owner 明示授权,不代批。
• Monitor 随会话存活;会话结束桥停,新会话重新 /loom-bridge 挂起。
• 同会话不重复挂:先 TaskStop 旧 Monitor 再挂新的。

loom-bridge-2-README.md

loom-bridge

Copyright (c) 2026 Peng Xiao

把当前 Claude Code 会话变成 CodexLoom 的实时执行臂:agent/Owner 发 claude-code: 简报, 桥秒级唤醒、subagent 执行、claude-code-result: 回帖。等待期零 token(persistent Monitor block waiting,推理只在有任务时发生)。

• 挂桥:新会话里 /loom-bridge
• 协议与坑:见 SKILL.md(loom_context 截断、双流监听、409 重试——均为实测教训)
• 验证记录:2026-08-05 三轮闭环(公告→自测→回帖),两类误报修复后通过

Owner: Peng Xiao · 个人环境专用(依赖 localhost:4870 的 CodexLoom 实例),不发布。

loom-bridge-3-interface.yaml

interface:
  display_name: "Loom Bridge"
  short_description: "把当前 Claude Code 会话变成 CodexLoom 的实时执行桥"
  default_prompt: "挂起 loom-bridge:先探活 CodexLoom(localhost:4870 与 ~/.codex-loom 数据流),然后用 persistent Monitor 双流监听任务简报(claude-code: 前缀,四项必填),任务到达时 spawn subagent 执行(Sonnet 起步,绝不 Fable),验证后以 claude-code-result: 回帖。缺字段回帖要求补发,不猜。不 push、不动 cloud、破坏性操作转 Owner。"
  examples:
    - "/loom-bridge"
    - "挂桥,接 codexloom 的任务"
    - "把这个会话变成 loom 执行桥"
    - "bridge waiting for codexloom tasks"
compatibility:
  canonical_format: "agent-skills"
  adapter_targets:
    - "claude"
  activation:
    mode: "manual"
    paths: []
  execution:
    context: "inline"
    shell: "bash"
  trust:
    source_tier: "local"
    remote_inline_execution: "forbid"
contract:
  inputs:
    - "claude-code 任务简报(任务详情/契约引用/工作路径/验收标准)"
    - "env LOOM_TOPIC(缺省回帖 topic)"
  outputs:
    - "persistent Monitor(任务事件唤醒)"
    - "claude-code-result 回帖(commit hash/测试结果/摘要)"
  forbidden:
    - "git push / cloud 资源变更 / 生产发布(转 Owner)"
    - "破坏性操作代批"

loom-bridge-4-manifest.json

{
  "name": "loom-bridge",
  "version": "1.0.0",
  "owner": "Peng Xiao",
  "updated_at": "2026-08-05",
  "status": "active",
  "maturity_tier": "scaffold",
  "lifecycle_stage": "personal",
  "context_budget_tier": "scaffold",
  "review_cadence": "as-needed",
  "target_platforms": ["claude-code"],
  "publish": false,
  "evidence": {
    "validated_at": "2026-08-05",
    "method": "三轮实时闭环(协议公告→自测任务→结果回帖);过滤器 5 固定用例单测",
    "known_fixes": ["Owner 消息仅在线程流", "loom_context 截断", "结果前缀排除", "消息 id 去重", "409 重试"]
  }
}

loom-bridge-scripts-loom_send.py

#!/usr/bin/env python3
"""向 CodexLoom topic 回帖,409(responsible agent 占线)自动重试。

用法:
  python3 loom_send.py --topic tpc_xxx "text..."
  python3 loom_send.py "text..."            # topic 取 env LOOM_TOPIC
  echo "text" | python3 loom_send.py --topic tpc_xxx -
"""
import argparse, json, os, sys, time, urllib.request, urllib.error

def main():
    p = argparse.ArgumentParser()
    p.add_argument('--topic', default=os.environ.get('LOOM_TOPIC'))
    p.add_argument('--base', default='http://localhost:4870')
    p.add_argument('--retries', type=int, default=30)
    p.add_argument('text')
    a = p.parse_args()
    if not a.topic:
        sys.exit('no topic: pass --topic or set LOOM_TOPIC')
    text = sys.stdin.read() if a.text == '-' else a.text
    body = json.dumps({'text': text}).encode()
    url = f"{a.base}/api/topics/{a.topic}/send"
    for i in range(a.retries):
        req = urllib.request.Request(url, method='POST', data=body,
                                     headers={'Content-Type': 'application/json'})
        try:
            with urllib.request.urlopen(req, timeout=10) as r:
                print(f"sent {r.status} (attempt {i+1})")
                return
        except urllib.error.HTTPError as e:
            if e.code != 409:
                sys.exit(f"error {e.code}: {e.read().decode()[:200]}")
        time.sleep(10)
    sys.exit(f"still 409 after {a.retries} attempts")

if __name__ == '__main__':
    main()

loom-bridge-scripts-monitor_filter.py

#!/usr/bin/env python3
"""loom-bridge 事件过滤器:stdin 接 tail -F 双流,stdout 每行一个任务事件。

流两类:
  comms.ndjson          -> {"message": {...}}                agent 对 agent
  events/*.ndjson       -> {"type":"item/completed",...}     topic/Owner 投递的 userMessage

规则(每条都有实测事故背书,勿删):
  - 线程消息先截 <loom_context 再匹配 —— 投递附带的编译上下文含历史 marker,会误触发
  - claude-code-result: 不触发 —— 桥自己的回帖
  - 按消息/条目 id 去重 —— CodexLoom 存在同消息多次落盘(重投递)
"""
import sys, json

seen = set()
for line in sys.stdin:
    line = line.strip()
    if not line or line.startswith('==>'):
        continue
    try:
        obj = json.loads(line)
    except Exception:
        continue
    mid, src, frm, to, subj, body = None, None, '', '', '', ''
    if 'message' in obj:
        m = obj['message']
        mid, src = m.get('id'), 'comms'
        frm, to = m.get('from', ''), m.get('to', '')
        subj, body = m.get('subject') or '', m.get('body') or ''
    elif obj.get('type') == 'item/completed':
        it = (obj.get('data') or {}).get('item') or {}
        if it.get('type') != 'userMessage':
            continue
        mid, src = it.get('id'), 'thread'
        body = ' '.join(c.get('text', '') for c in (it.get('content') or [])
                        if c.get('type') == 'text')
    else:
        continue
    body = body.split('<loom_context')[0]
    subj = subj.split('<loom_context')[0]
    txt = subj + ' ' + body
    if 'claude-code:' not in txt.replace('claude-code-result:', ''):
        continue
    if not mid or mid in seen:
        continue
    seen.add(mid)
    print(f"TASK[{src}] {mid} {frm}->{to} {subj[:60]} | "
          f"{body.replace(chr(10), ' ')[:400]}", flush=True)