78 lines
5.3 KiB
JSON
78 lines
5.3 KiB
JSON
{
|
||
"module": "session_router",
|
||
"version": "2.0",
|
||
"purpose": "Session Router — 多通道 session 路由 + 命令循环。为 XMPP/VC/微信等通道提供类 TUI 的 session 体验：auto 模式自动绑定最近活跃 session、NL 切换 session（'切换到xxx'）、LLM 驱动的 ##command## 系统。",
|
||
"ui_location": "无直接 UI — 被 chat_bridge.py 和 xmpp_bot.py 使用",
|
||
|
||
"human_help": {
|
||
"title": "Session Router — 多通道 Session 路由",
|
||
"description": [
|
||
"session_router.py 是一个消息路由器，让多个通信通道（XMPP/VC/微信）能像 TUI 一样使用 OpenCode session：自动绑定活跃 session、自然语言切换 session、支持 LLM 命令系统。",
|
||
"命令系统：LLM 回复中的 ##command## 被拦截执行而非直接回复。支持 ##list_sessions##（列 session）、##switch_session:ID##（切换 session）、##select_session:1-5##（用户选择 session）等。",
|
||
"选择模式：当用户用自然语言说'切换到xxx session'时，router 列出匹配的 session 让用户选择，选择超时 120s。",
|
||
"消息循环（command loop）：LLM 回复后检查是否包含 ##command## → 如果包含，执行命令 → 结果追加到上下文 → 重新调用 LLM → 直到无命令或达到 MAX_LOOPS=10。"
|
||
],
|
||
"usage": [
|
||
"1. 创建: router = SessionRouter(bridge=SessionBridge(...), default_session='ses_xxm_xmpp')",
|
||
"2. 路由消息: router.route(channel='xmpp', sender='hmo', message='你好') → AI 回复",
|
||
"3. NL 切换: 用户在消息中说'切换到xxx session' → router 匹配并切换",
|
||
"4. 命令: LLM 回复中包含 ##list_sessions## → router 拦截执行而非返回用户",
|
||
"5. 选择超时: SELECTION_TIMEOUT = 120s — 超时后选择模式自动取消"
|
||
],
|
||
"troubleshooting": [
|
||
"如果命令循环死循环: MAX_LOOPS=10 限制 — 超过后直接返回最后结果",
|
||
"如果 session 切换失败: 检查 opencode.db 是否可读 — DB_PATH = ~/.local/share/opencode/opencode.db",
|
||
"如果选择模式卡住: 120s 超时后自动取消"
|
||
]
|
||
},
|
||
|
||
"ai_spec": {
|
||
"apis": [
|
||
{"method": "N/A (内部路由)", "path": "router.route(channel, sender, message)", "returns": "AI 回复文本", "note": "主入口 — 处理消息 → 调用 LLM → 解析命令 → 循环直到无命令"},
|
||
{"method": "N/A (工具函数)", "path": "extract_session_context(session_id, limit=200)", "returns": "formatted context string", "note": "从 opencode.db 提取最近 N 条会话上下文"}
|
||
],
|
||
"dependencies": [
|
||
"opencode.db (SQLite) — ~/.local/share/opencode/opencode.db",
|
||
"chat_bridge.py — SessionBridge (LLM 调用)",
|
||
"SQLite3 stdlib — 数据库读取",
|
||
"threading — 选择模式超时管理"
|
||
],
|
||
"architecture": {
|
||
"flow": "消息 → ① 检查选择模式(pending user choice) → ② extract_session_context (200条) → ③ 构建 prompt → ④ SessionBridge.chat() → ⑤ 解析回复查找 ##command## → ⑥ 有命令 → 执行命令 → 结果追加 → 回到④ → 无命令 → 返回回复",
|
||
"command_loop": "最多 10 次循环 — 每次 LLM 回复后检查 CMD_RE regex (##\\w+(?::[^#\\n]*)?##) → 拦截执行 → 追加结果 → 重新调用 LLM",
|
||
"selection_mode": "用户请求切换 session → 列出匹配 session → 设置 selection_timer (120s) → 等待用户选择 → 超时自动取消",
|
||
"context_extraction": "SQLite 查询 messages 表 → 按 role 格式化 ('用户:' / '小小莫:') → 最近 200 条"
|
||
},
|
||
"constraints": [
|
||
"MAX_LOOPS = 10 — 防止命令循环无限执行",
|
||
"SELECTION_TIMEOUT = 120s — 用户选择超时",
|
||
"RECENT_MSG_LIMIT = 200 — 上下文上限",
|
||
"SESSION_LIST_LIMIT = 15 — 列表显示最多 15 条",
|
||
"DB_PATH 依赖于系统 opencode 安装路径 — ~/.local/share/opencode/opencode.db"
|
||
],
|
||
"must_not": [
|
||
"不要在命令循环中无限 loop — MAX_LOOPS 是硬限制",
|
||
"不要修改 opencode.db 的 messages 表结构 — 只读查询",
|
||
"不要合并不同 channel 的消息 — 每条消息标记 source 标签"
|
||
],
|
||
"related_modules": [
|
||
{"module": "chat_bridge", "relation": "session_router 包装 SessionBridge，增加命令路由层"},
|
||
{"module": "xmpp_bot", "relation": "xmpp_bot 使用 SessionRouter 进行消息路由和命令处理"}
|
||
],
|
||
"tests": [
|
||
{"id": "SR01", "name": "extract_session_context 返回格式化上下文", "endpoint": "extract_session_context('ses_test') → '用户: xxx\\n小小莫: xxx'"},
|
||
{"id": "SR02", "name": "命令循环最多 10 次", "endpoint": "注入始终返回 ##dummy## 的 LLM → 10 次后停止"},
|
||
{"id": "SR03", "name": "选择模式 120s 超时", "endpoint": "设置选择模式 → 等 130s → 选择自动取消"}
|
||
],
|
||
"known_issues": [
|
||
"命令循环依赖 LLM 回复格式 — 如果 LLM 返回非标准 ##command## 格式，会直接当作回复",
|
||
"openCode.db schema 可能会随 opencode 升级变化 — 如果 messages 表结构变了，extract_session_context 需要更新"
|
||
],
|
||
"related_files": [
|
||
"gateway/scripts/session_router.py — 本文件 (635行)",
|
||
"gateway/scripts/chat_bridge.py — SessionBridge 实例",
|
||
"~/.local/share/opencode/opencode.db — Session 数据源"
|
||
]
|
||
}
|
||
}
|