ADR 005 chat input

ADR-005: 聊天框输入体验优化

日期: 2026-04-10 状态: 已确认 决策者: BOSS + AI 架构分析

---

背景

Catown 聊天框是 BOSS 与系统交互的核心入口。当前输入框仅有基础文本输入能力，存在以下问题：

1. 重复输入：BOSS 经常需要重发之前的消息（如暂停 Pipeline、查看状态），每次都要手动打字
2. 无快捷操作：查看 Agent 状态、Skills 列表等高频操作只能通过 API 或 Web UI，效率低
3. 无输入辅助：长指令拼写易错，没有补全和提示

决策

第一版实现三项核心机制：消息历史回溯 + 只读指令系统 + 双源联想补全。

写操作类指令（修改配置、重启服务等）留到后续版本，第一版只做查询类指令，降低风险。

方案

消息历史

维度	决策	理由
保留条数	50 条	聊天框操作密度低，50 条足够；200 条增加搜索噪音
存储位置	projects/{id}/.catown/input_history.json	按项目隔离，跟随 workspace
跨会话	是	BOSS 换浏览器/刷新后仍可回溯
操作方式	↑ / ↓ 箭头键	符合终端/IM 习惯

指令系统

第一版指令清单（只读）：

指令	别名	分类	说明
/help	/h	基础	显示所有可用指令及说明
/skills list	/sl	Skills	列出已安装 Skills
/skills info <name>	/si	Skills	查看 Skill 详情
/tools list	/tl	Tools	列出所有可用工具
/tools info <name>	/ti	Tools	查看工具详情
/agents list	/al	Agent	列出所有 Agent 角色及状态
/agents info <name>	/ai	Agent	查看 Agent 详情
/config get	/cg	配置	查看当前全局配置
/pipeline status	/ps	Pipeline	查看当前 Pipeline 状态

排除的指令（留到后续版本）：

指令	排除理由
/skills enable/disable	写配置，需配合审批流
/config set	写配置，改错难回滚
/service restart	危险操作，应走部署流程
/pipeline pause/resume/rollback	已有 Dashboard 按钮，指令版需二次确认 UI
/agents model	写配置，需验证模型可用性

指令别名设计原则：取各单词首字母，如 /sl = /skills list，打字最少化。

渲染样式：指令在聊天框以左侧紫色竖线 + 等宽字体显示，与普通消息区分。执行结果以系统消息卡片返回，成功绿色、失败红色。

联想补全

第一版仅两个来源：

触发	来源	说明
/	指令列表	匹配前缀，显示指令 + 参数提示
普通文本	历史搜索	匹配前缀，最多 5 条

暂不实现：

• @ Agent 提及（后续版本）
• 上下文补全（基于 Pipeline 阶段的智能建议，成本高、价值待验证）
• 模糊匹配（编辑距离，第一版精确前缀够用）

数据流：

用户输入
  ├─ / 开头 → 指令解析 → 匹配指令列表
  └─ 普通文本 → 历史前缀搜索 → 匹配结果
         ↓
    联想面板（< 100ms，本地计算）

技术约束

• 联想响应 < 100ms，纯前端/本地计算，不走 LLM
• 补全面板虚拟滚动
• 指令定义在 configs/commands.json，支持热加载扩展

影响模块

模块	改动
frontend/index.html	输入框组件：历史回溯、指令解析、联想面板
routes/api.py	新增指令执行 API（/api/commands/execute）
configs/commands.json	新增，指令定义
backend/commands/	新增，指令解析器 + 执行器

后续版本规划

• V2：写操作指令（/config set、/pipeline pause 等）+ 二次确认 UI
• V2：@ Agent 提及
• V3：上下文感知补全
• V3：指令自定义（BOSS 定义快捷指令映射）