规则先分流，该判断时才叫 Router，活交给 Worker。

01是什么

术语

本席

负责这套系统的对话 agent 席位，兼任 Router。

thread

一个 issue 及其评论串。

ticket

Router 建出来、交给一个 Worker 负责的一件活。

Fast Path

不调模型、只用规则判定去向的接入层。

outbox

对外动作的待批队列，不自动发送。

五个要点

• 核心思路

  不调模型的部分尽量多

  去重、白名单、是否 @、已订阅的 thread，全在 Fast Path 里用规则判完。只有真要判断的消息才唤醒 Router；同一 thread 的后续消息直接推给负责它的 Worker。离线测试里，20 条无关评论加 1 条 @，只入 Router 队列 1 次。

• Router

  上下文靠库，不靠会话

  Router 不是常驻进程，每次被唤醒都从库里重建状态，只看卡片，不读代码、不读 Worker 全文。

• 对外动作

  先进 outbox，等人批

  PR、issue 评论都写进 outbox，不自动发；用户亲口批了某条才发，带去重标记。

• 实现方式

  Python 移植，不跑原型

  原型是 DSH 插件包，整体跑要装整套运行时。这里照原型逻辑用 Python 标准库 + gh CLI 重写，不引入 Node 依赖。

• 范围

  第一期只接 GitHub

  原型本身只有 GitHub 和飞书。GitLab 原型没有，放到后面再说。

02架构与数据流

各部件

• Polling

  运行中

  常驻 Python 进程，用 gh 轮询沙盒仓。通知流以 since 游标回退 5 秒，仓库流带 ETag（304 不耗限额），间隔取 60 秒、X-Poll-Interval、配置下限三者的最大值。进程只出站，不监听端口。

• Fast Path

  已测

  同 ID 去重、白名单、是否 @、thread 是否已有订阅。原文一律入 trigger 表，去向写进 disposition。已订阅的直接进该 ticket 的 inbox，不经 Router。

• Router

  本席

  由本席担任，不是常驻进程：每次被唤醒先 sa read tickets --open 重建状态，只看卡片（ID + 160 字预览 + read 路径），路由说明不超过 30 词，不读代码。

• Worker

  第 2 阶段

  一个 ticket 一个后台子任务，各自工作目录，结束时 sa report。中途的新消息，Worker 每步之间读自己的 inbox，或由 Router 续派时带上。写手和审查换不同模型，互不自审。

• outbox

  只入队

  sa reply 只写入 outbox，状态 pending、approved=false，带 <!-- sa:id --> 去重标记。发送前必须有用户批准，这一闸门是原型没有的。

• 看门狗

  计划中

  定时 routine：扫库，报告久未汇报的 ticket 和重复出现的同一错误，只报不自动重来。原型没有独立看门狗，需自写。

03消息路径

1. 接入

   1. 轮询到新条目

      poller 每约 60 秒取一次通知和 issue / 评论流。Trigger ID 是确定性的，形如 github:<repo>:issue:<n>:opened，游标回退 5 秒造成的重复，靠下一步去重吃掉。

   2. Fast Path 入库

      先查 ID：已有就返回 duplicate，什么都不写。否则原文入 trigger 表，再判去向：作者是机器人自己 → filtered/self；不在白名单 → filtered/not_allowed。

2. 分流

   3. 找订阅

      该 thread 若已有 open 的 ticket 认领，消息直接进它的 inbox，needs_router 为 false，到此结束。done 的 ticket 只有真人消息能重新唤醒；stopped 的不唤醒；[bot] 后缀不算真人。

   4. 无人认领时判断 @

      文中整词 @ 了机器人（大小写不敏感）才进 Router 队列；否则记为 filtered/not_mentioned。离线测试：20 条无关评论加 1 条 @，只入队 1 次。

   5. 攒批，唤醒 Router

      队首满 2 秒后发一次 POST，内容是 trigger 列表和读取提示。成功才清队列；没有配置 webhook 就保留队列。

3. 处理

   6. Router 路由

      Router 先读 open ticket 卡片，再用 sa route 建 ticket 并订阅该 thread。此后同 thread 的追加消息走第 3 步直推，不再经过它。

   7. Worker 干活并汇报

      Worker 在自己的目录里、沙盒仓的独立分支上改。sa report 把进展写回 ticket（截断 600 字），--done 标记完成。

4. 对外

   8. 写入 outbox

      sa reply 把要发的评论排进 outbox，返回 "sent": false。它此刻只是草稿。

   9. 用户批准，再发出 设计中 · 尚未验证

      只有用户在本席聊天里的原话算批准，别的 agent 转述不算。批准后才发送，并带去重标记，失败重试不会重复发。

04复用了原型的哪些部分

原型是什么

不是独立服务，而是 DSH（DeepSeek Harness）的一个插件包：入口靠 @deepseek-ai/cordis 插件框架注入，Router / Worker 都是 DSH Session，依赖 20 多个 0.2.1-alpha.2 的 peer 包，HTTP 面板走 dsh-host-webserver。部署要全局装 @deepseek-ai/dsh@0.2.1-rc.3、pnpm、tmux 和 DeepSeek 模型 key。

三种复用方式

1. 方案 A

   整体直接跑

   要在本机装一整套 DSH 运行时和模型凭据，Router / Worker 变成 DSH 会话，与「本席当 Router、子任务当 Worker」冲突。

   不采用

2. 方案 B

   模块级拿来用

   github.ts 依赖 cordis Context、host/poll/kv、zod；store.ts 用 node:sqlite，但与 policy / migration / versions 耦合。单抽出来要补一堆桩。

   不现实

3. 方案 C

   照原型逻辑用 Python 移植

   行为、表结构、游标和去重规则照抄，并标注出处行号。只用 Python 标准库和已登录的 gh，不引入 Node 依赖，不装新软件。

   采用

逐个部件

和原型的差异

05阶段计划

1. 第 0 阶段 · 已通过

   底座

   建库和 sa.py CLI（receive、route、read、report、reply）。

   • 假消息入库
   • 同 ID 再收返回 duplicate
   • sa read trigger/<id> 读回原文
   • route / report / reply 冒烟

2. 第 1 阶段 · 代码完成 · 待真实验收

   接入 + Fast Path

   沙盒仓 issue 里 @ 机器人账号，60–120 秒入库；20 条无关事件只唤醒本席 0 次，1 条 @ 唤醒 1 次。

   • 离线测试 13/13 通过
   • 机器人身份核对、webhook 测试唤醒 HTTP 200
   • 常驻 poller 已启动，连续空轮询约 60 秒一轮
   • 真实 @ 入库与唤醒

3. 第 2 阶段 · 未开始

   Router + Worker 闭环

   issue 里提个小改动，出分支和 PR 草稿，issue 评论草稿进 outbox。

   • 本席会话里没出现代码细节
   • 同 issue 追加一句直接进该 ticket inbox，没经过 Router

4. 第 3 阶段 · 未开始

   Outbox + 看门狗 + 恢复

   把故障和中断都演一遍。

   • 故意让 gh 失败一次，批准的消息能补发且不重复
   • 手动搁置一个 ticket 30 分钟，看门狗报出来
   • 重启进程后未完成 ticket 能接着做

06关键代码要点

def ingest(t):
    if exists(t.id):
        return "duplicate"             # 什么都不写
    save_trigger(t)                    # 原文一律入 trigger 表

    if t.author == bot_user:
        return filtered("self")        # 防自激
    if t.author not in allow:
        return filtered("not_allowed") # 留痕，但永不唤醒

    subs = subscriptions(t.thread)
    if subs:
        # open 直接进 inbox；done 仅真人可重唤醒
        # stopped 不唤醒；[bot] 后缀不算真人
        deliver_to_inbox(subs, t)
        return accepted(needs_router=False)

    # bot_user 或 mention_names，整词、大小写不敏感
    if mentioned(t.text):
        kv["router.queue"].append(t.id)
        return accepted(needs_router=True)
    return filtered("not_mentioned")

CLI 一览

$ python3 sa.py receive --json '{"id":"gh-1001", … "text":"@bot 请把 README 标题改成 Hello"}'
{ "status": "accepted", "delivered_to": [], "needs_router": true }

$ python3 sa.py receive --json '{"id":"gh-1001", … "text":"重复"}'
{ "status": "duplicate", "id": "gh-1001" }

$ python3 sa.py route gh-1001 --ticket tk-readme --thread sandbox#1 …
{ "status": "routed", "ticket": "tk-readme" }

$ python3 sa.py receive --json '{"id":"gh-1002", … "text":"顺便加一行说明"}'
{ "status": "accepted", "delivered_to": ["tk-readme"], "needs_router": false }

$ python3 sa.py reply tk-readme --target … 已改好，见分支 sa/readme-title
{ "status": "queued", "outbox": "ob-f90e0fb4", "sent": false }

$ python3 sa.py report tk-readme 完成 --done
{ "status": "reported", "ticket_status": "done" }

{
  "repo": "dailiuyi/superagent-demo",
  "allow": ["dailiuyi"],
  "bot_user": "dailiuyi-bot",
  "mention_names": ["dailiuyi-bot"],
  "webhook_url": /* 已配置，不展示 */,
  "batch_seconds": 2,
  "poll_min_seconds": 60
}

07安全边界

1. allowlist

   配置里 allow 只有用户本人。不在名单里的作者，消息照样入库留痕，但去向记为 filtered，永远不会唤醒 Router 或进入 ticket。机器人自己的发言同样被过滤，避免自激。

2. outbox 需要人工批准

   推送、开 PR、部署、对外发消息一律要用户亲口批准；合并由用户自己做。reply 只是入队，状态是待批，不是已发。只有本席聊天里用户的原话算批准。

3. 只在 sandbox 仓里动手

   只碰沙盒仓和本项目自己的工作目录。Worker 在独立分支上提交，写手和审查用不同模型。公司仓和其他个人仓不在范围内，也不碰其他席位的交接目录。

常驻进程不监听任何端口，只出站。凭据只从环境变量和权限受限的文件读取，只传给对应的子进程，不打印、不写进日志；已核对日志里没有 token 字样。

08风险与下一步