JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
Slash 命令体系设计(架构说明)
文档性质:架构与演进约定,描述「单一事实来源」、分层边界与落地原则。
与现有文档关系:能力清单与入口对照见命令行指令.md;本文不重复罗列全部命令,只定义如何组织与避免漂移。
1. 背景与问题
当前项目中以 / 开头的指令存在多处实现:
- Gateway:
MessageHandler._handle_channel_control处理受控通道上的/new_session、/mode …等,并决定是否拦截、不转发 Agent。 - IM 管线 / 各 Channel:例如
gateway/im_pipeline/im_inbound.py中的控制消息集合、飞书/企业微信等通道内的文本判断,可能与主逻辑集合不一致。 - CLI TUI:
jiuwenswarm/channels/tui/frontend/src/core/commands/下本地注册表,部分命令通过 WebSocket 调用后端,部分纯本地。
若不建立明确分层与单一数据源,会出现:同名命令语义不一致、文档与代码漂移、新通道重复实现解析规则。
2. 设计目标
| 目标 | 说明 |
|---|---|
| 单一事实来源(SSOT) | 对「网关侧控制的通道 slash」而言,命令名、合法形式、是否整行匹配等应在一处定义,其它模块引用而非复制常量集合。 |
| 边界清晰 | 区分「仅 Gateway」「仅客户端」「两端都需对齐名称」三类,避免把「全产品 slash」误塞进 Gateway 单一模块。 |
| 可演进 | 新增受控通道时,只需对照注册表与 _control_channel_types 等策略,减少遗漏。 |
| 与 REPL 约定一致 | 本地 UI 侧 slash(如帮助、诊断类)仍优先在客户端解析;未识别的 /xxx 不应默认当作普通用户内容上送 Gateway(见项目内 REPL 设计说明)。 |
2.1 非目标
- 不要求所有 slash 都在 Python Gateway 内执行(CLI 专属命令仍属客户端)。
- 不强制一次重构消灭所有历史分支;允许分阶段把「常量与解析」迁到 SSOT,行为保持不变。
3. 三层分类(必须遵守)
3.1 A 类:Gateway 通道控制(Channel Control)
定义:到达 Gateway 用户消息中,由 MessageHandler(或其后继统一入口)识别后,可能只改会话/模式/路由,而不进入 Agent 对话的指令。
典型:/new_session、受控通道上的 /mode agent|code|team 与 /switch plan|fast|normal|team,以及 /mode agent.plan|agent.fast|code.normal|code.team 直达写法(以当前实现为准)。TUI 本地额外支持 /mode plan、/mode team.normal,这些不属于 Gateway 受控通道白名单。
要求:
- 合法形式、是否允许带多余字符、非法时的提示方式,应由 SSOT 描述;
im_inbound、各 IM Channel 若需预判,应引用同一 SSOT,禁止私自维护另一份「子集」常量。 - 注册项中应标明 适用的通道类型(与
_control_channel_types、_session_map_channel_types等策略一致),避免「全通道一刀切」。
3.2 B 类:客户端本地(Client-Only)
定义:仅在 CLI TUI、Web REPL 等本地解析与执行,或明确不应经 Gateway 做语义拦截的命令。
典型:CLI 的界面切换、/resume、/model(若仅本地配置)、帮助/诊断类 stub 等(以 命令行指令.md 为准)。
要求:
- 不纳入 Gateway 的「拦截表」作为唯一真相;若需与后端模式对齐,通过已有协议字段(如
params.mode)传递,而不是在 Gateway 再解析一遍 CLI 专有别名。 - 文档中标注 处理进程:Node CLI / 浏览器前端等。
3.3 C 类:名称对齐、执行分端(Hybrid)
定义:用户感知的名称与帮助文案希望跨 CLI 与 IM 一致,但执行发生在客户端 + 后端组合(例如先本地校验再发 RPC)。
要求:
- 在 SSOT 或文档矩阵中增加
canonical_name+cli_alias等字段,避免「CLI 与 IM 斜杠写法不一致」时无据可查。 - Gateway 不必理解 CLI 别名;若未来需要服务端识别,应显式列为新需求并扩展协议,而非隐式复用用户输入字符串。
4. 单一事实来源(SSOT)建议形态
4.1 模块位置(建议)
- Python 侧:已实现为
jiuwenswarm/gateway/slash_command.py(受控通道解析、CONTROL_MESSAGE_TEXTS、第一批命令元数据FIRST_BATCH_REGISTRY)。亦可按演进拆分为channel_control_slash.py等。原建议职责为:- 数据:受控命令的集合、匹配规则(精确 / 前缀 / 禁止多行等)、元数据(说明、是否转发 Agent)。
- 纯函数:给定通道类型与用户文本,返回结构化判定结果(未命中 / 命中且合法 / 命中但非法),不直接做 IO(不在这里
create_task发通知)。
- 命名建议:若仅包含 A 类,模块名应避免被误解为「全站所有 slash」,以免后续贡献者把 B 类逻辑塞入 Gateway。
4.2 注册表最小字段(建议)
| 字段 | 说明 |
|---|---|
id |
内部稳定标识(如 new_session、mode_switch)。 |
patterns |
合法用户输入形式(含是否仅整句精确匹配)。 |
scope |
gateway(本设计主体)。 |
channels |
all_controlled 或显式列表,与配置中的通道类型对齐。 |
intercept |
命中且合法时是否不转发 Agent(与现 _handle_channel_control 语义一致)。 |
notes |
与 CLI 别名、文档锚点的交叉引用(链接到 命令行指令.md 章节)。 |
4.3 与 MessageHandler 的关系
- 解析与判定:调用 SSOT 模块,减少
message_handler.py内联startswith链。 - 副作用:仍在
MessageHandler(或专门的服务类)中执行取消任务、下发通知等,避免在「表模块」中掺杂异步副作用,便于单元测试。
5. 各入口如何接入(原则)
| 入口 | 原则 |
|---|---|
Gateway MessageHandler |
受控通道用户文本进入统一控制逻辑前,以 SSOT 为准做判定。 |
im_inbound 等管线 |
若需提前过滤或统计,import 同一常量/函数,禁止维护独立 frozenset 子集。 |
| Feishu / WeCom 等 Channel | 若因协议必须在 Channel 层做轻量判断,应复用 SSOT或仅做「是否可能为控制指令」的粗筛,最终语义以 Gateway 为准;若存在双点判断,须在注册表 notes 中写明并压测避免重复提示。 |
| CLI | 继续维护 TS registry;与 A 类命令名称对齐见 命令行指令.md 与本文第 3.3 节,不在 Gateway 重复实现 B 类。 |
6. 与「未知 slash」相关的协议约定
- 客户端(REPL/TUI):以
/开头的输入应先走本地命令路由器;未识别命令应对用户提示并不作为普通对话内容上送(与产品体验一致时),详见 REPL 设计文档中的 Slash 章节。 - Gateway:仅对确实会到达 Gateway 的通道保证按 SSOT 处理 A 类;不要求 Gateway 识别所有 CLI 专有命令。
7. 测试与质量保障
- 为 SSOT 提供单元测试:覆盖精确匹配、非法后缀、多行文本、
/mode一级入口与直达值、/switch合法/非法组合等与现网一致的行为。 - 回归时注意:SessionMap 通道族与普通受控通道在
session_id行为上的差异仍由现有状态机负责,SSOT 只解决「字符串层」一致性与可维护性。
8. 分阶段落地(建议)
| 阶段 | 内容 |
|---|---|
| P0 | 提炼 A 类命令到 SSOT 模块;im_inbound 等改为引用,消除集合漂移。 |
| P1 | 收敛 message_handler.py 内联解析到对 SSOT 的调用,行为不变。 |
| P2 | 在文档矩阵中补齐 B/C 类与 命令行指令.md 的交叉引用;可选:生成给前端的只读清单(若未来需要统一补全)。 |
9. 小结
- **Gateway 中的「表」**应主要承载 A 类(通道控制) 的 SSOT,而不是全产品所有 slash。
- B 类保留在客户端;C 类用文档与字段做名称对齐,避免强行集中执行逻辑。
- 成功标准:一处改命令集合,管线与 Gateway 主路径不再分叉;CLI 与 IM 的体验边界仍清晰、可文档化。
10. 当前命令现状表(基于 gateway/slash_command.py)
当前命令清单已拆分到独立文档:Slash命令表.md。