cspy / nexora-loop

Problem

三个 channel 的 chat handler 干同样的事:get-or-create conversation → persist inbound message → callBotChat → parseEscalate → 持久化 reply → 异步起 generateTicket。callBotChat 抽出来了(底层 transport),但上层流水线没抽。结果是每次加一个能力(比如 fire-and-forget 工单生成 / metadata 标准化 / 流式回复 / 跨 conversation 续接)都要在 3 个文件里手动同步。

Solution

抽 lib/messaging/chat-pipeline.ts(已有 lib/messaging/ 空目录,signal): 接收一个 ChatContext + ChannelAdapter,跑统一流水线。 Channel-specific 的事(怎么拿/建 conversation / 怎么读 user meta / 怎么 send back / 怎么 mapMessageId)走 adapter 接口。

Before / After

wechat/chat.ts:
  handleChat(openid, content, opts)
    └─ conv = getOrCreate(openid, bot)
    └─ Message.create(inbound)
    └─ result = callBotChat(bot, {...})
    └─ parseEscalateAnalysis(result.reply)
    └─ Message.create(outbound)
    └─ generateTicket(conv.id) .catch()

feishu/chat.ts:        // ~同上,8 处不同
widget/chat.ts:        // ~同上,5 处不同

新增能力 X 时 → 改 3 个文件

messaging/chat-pipeline.ts (deep):
  runChat(adapter, input) {
    conv  = adapter.openConversation(input)
    inMsg = adapter.persistInbound(conv, input)
    res   = callBotChat(adapter.bot, mapReq(input, conv))
    parsed = parseEscalateAnalysis(res.reply)
    adapter.persistOutbound(conv, parsed)
    generateTicketAsync(conv.id)
    return adapter.formatReply(parsed)
  }

wechat/adapter.ts  ~30 行
feishu/adapter.ts  ~25 行
widget/adapter.ts  ~25 行

新增能力 X → 只改 chat-pipeline.ts

Benefits

• Locality:fire-and-forget 工单 bug(skill 里记的"必须 await")只会出现 1 次,而不是 3 次踩一遍
• Leverage:wechat 跑过的 MM 流式/cross-conversation 续接,feishu/widget 自动继承
• Test surface:测 ChatPipeline 一次盖 3 channel,adapter 用 stub 替;__integration__/ 现在 17 个 case 主要测 wechat 路径,feishu/widget 实际没 case
• AI navigability:gitnexus 现在 175 个 execution flow,合并后 3 个 chat flow 变 1 个,索引更清

Problem

"状态机"在 cspy 里没有显式存在。它的实现散在: ① generate-ticket.ts 里 ACTIVE_STATUSES 数组 + "是否复用 existing" 的判定; ② execute-ticket.ts 里 status awaiting_confirm → executing → awaiting_user_push 的硬编码转换; ③ actions.ts 里 13 个 server action 各自检查 + 写不同 status; ④ admin UI 里读 status 显示不同按钮。没有任何一处文档/代码说"合法转换是哪些"。 Skill 里记的 pitfall #1("need_human 漏在 ACTIVE_STATUSES")就是这种散开必然的结果: 改了一处忘了另一处。

Solution

抽 lib/ticket/lifecycle.ts(已有 lib/ticket/ 空目录,signal): 显式状态机 + transition function。所有 status 转换必须过这一层,callers 不能直接 db.ticket.update({status})。 状态机内部知道 "这个转换需要发什么 event / 通知谁 / 触发哪个 hook"。

Before / After

// generate-ticket.ts:21
const ACTIVE_STATUSES = ["new","analyzing",
  "analyzed","awaiting_confirm","executing"];
// 没列 need_human → bug #1

// actions.ts:158
changeTicketStatus(id, status) {
  await db.ticket.update({where:{id}, data:{status}});
  // 没记 event,没触发 notification
}

// actions.ts:69
submitAdminReply(...) {
  // 内嵌 status="replied" 转换 + 写 message
  // + 推 fanout + 写 event ... 200 行
}

// lib/ticket/lifecycle.ts
type TicketEvent =
  | { type: "user_message_received", ... }
  | { type: "admin_reply_submitted", ... }
  | { type: "ai_suggestion_pushed", ... }
  | ...

export async function applyEvent(
  ticketId: string,
  event: TicketEvent
): Promise<{ticket: Ticket, sideEffects: SideEffect[]}>

// caller 只表达"发生了什么",
// 不决定"应该转到哪个 status / 写什么 event"
// 状态机内部维护 transition table

Benefits

• Locality:加新状态/规则(如"need_human 也算 active") 改一处
• Test surface:状态机可以纯函数测,不用起 PG;现在 actions.ts 测不动(全是 db 副作用)
• Audit:所有 transition 自动写 TicketEvent,不会出现"忘记记 event"
• Skill 里的 pitfall list 至少 #1 / #2 / #3 都会消失

Problem

callBotChat 接口形式上很深(传 bot + req,得 reply), 但实现里的复杂度集中在 mm/client.ts 单文件 424 行: ws 路径(sendAndWaitViaWs)+ http 路径(sendAndWaitViaHttp) + transport 选择 + edit-aware quiescence(skill 里记的 Bug A 修复)。 这是真正的 deep module(高 leverage),但 424 行混在一起难审。

Solution(若推进)

把 mm/client.ts 按 transport 切: lib/mm/transport.ts(对外 sendAndWait,做 transport 选择 + 失败兜底) + lib/mm/ws-transport.ts + lib/mm/http-transport.ts。 每个 transport 满足同一个 Transport interface = 真 seam(skill 原话:"两个 adapter 才是真 seam")。

Problem

MM 切换上线时 skill 写了 "lib/relay/* 仍保留供 lib/relay/sync.ts / lib/consult/index.ts 等模块使用"。 但实际 consult/index.ts 现在 import 的是 mm 不是 relay(我刚刚 grep 验证)。 真正还活着的只有 relayUploadMedia 给 wechat 图片消息上传媒体用。

Solution

① 把 relayUploadMedia 这个具体函数搬到 lib/wechat/media-upload.ts(它是个 wechat 专属能力) ② 删 lib/relay/client.ts 余下 220 行 + sync.ts + config.ts ③ 顺手清 .env 里 RELAY_BASE_URL / RELAY_ADMIN_TOKEN / RELAY_CHANNEL_ID(skill 里还在,但已无 caller)

什么不在这份报告里

• UI 层(admin pages 900+ 行的 _split-view): 那是组件设计问题不是架构,走 design-review 不走本 skill
• 测试组织: lib/__integration__ 三文件够清,不动
• auth / NextAuth: 跟 NextAuth v5 升级耦合,等 next 16 落地再说
• db schema: Prisma 模型本身没有 deepening 候选(扁平表是合理的)