Skip to content

对话式 Agent ​

除了「点按钮触发某个 Skill」,砚考还有一个用自然语言办事的对话入口:

用户:帮我出 10 道计算机网络的选择题,难度中等,放进测试题库

Agent 会自己规划:查题库 → 生成 → 展示预览 → 等你确认 → 入库。

一次对话的完整链路 ​

text
POST /ai/chat  {message, sessionId?, answers?, token, identity}
        │
        ▼
  engine.chat()
        │
        ├─ 取/建会话(进程内存,TTL 30 分钟)
        ├─ 刷新 token / clientId / identity —— 以用户身份代调
        │
        ├─ 分支判断
        │    ├─ answers 非空        → 中断续跑(填完追问卡回来了)
        │    ├─ waiting 且猜到答案  → 手打答案续跑
        │    └─ 新提问              → detect_intent + extract_slots
        │
        ├─ 选 flow
        │    question_create / exam_analysis / question_search / general
        │
        └─ flow 执行
             ├─ 规划(LLM → 规则兜底 → 直接回答)
             ├─ 含写操作且未确认? → 弹确认卡,等用户点头
             ├─ 逐步执行工具/接口/技能,每步记 trace
             └─ 汇总成 Markdown

意图识别 ​

四个意图,纯正则快判(不花 token、延迟确定):

意图触发示例正则
question_create「出 10 道题」「帮我出题」「生成 5 道选择题」出\s*\d*\s*[道个条]*题|生成.*?题|来\s*\d+\s*道|...
exam_analysis「这次考得怎么样」「及格率多少」答题情况|考得怎么样|通过率|平均分|...
question_search「搜一下数据库的题」搜\s*\d*\s*[道个条]*题|找\s*\d+\s*道|有没有.*?题
chat其它兜底

匹配顺序 question_create → exam_analysis → question_search → chat。

意图用正则,槽位用 LLM

这是刻意的分工:意图特征极强,正则又快又准; 而槽位(知识点、题型、难度、题库名)千变万化,交给 LLM 语义理解, 不维护脆弱的正则映射表。

唯一例外是数量:纯数字 LLM 偶发丢字,所以用正则抽((\d+)\s*(?:道|个|条), 还认中文数字「十道」「两道」)。

槽位(Slots) ​

业务槽位:topic、count、question_type、difficulty、bank_keyword、bank_name、 new_bank_name、bank_id、exam_keyword、exam_id、exam_name、keyword、 language、reading_comprehension、status、limit、confirmed

内部槽位(双下划线前缀):

键含义
__question本轮原始问题,续跑时沿用,不被补充信息覆盖
__history最近 N 条消息
__intent__LLM 修正后的意图
__plan上一轮规划好的计划,用户确认后复用
__system_brief / __manifest系统说明书与接口清单(一轮内缓存)
__cancel__用户说「取消」

合并策略 merge_slots:新值覆盖旧值,但空值不覆盖—— 避免用户只改了题型,却用 None 把主题冲掉。

追问卡(AskForm) ​

缺参数时不猜、不报错,而是弹一张卡片让用户填。

json
{
  "kind": "form",
  "title": "还差一点信息",
  "desc": "已识别到:主题=计算机网络、数量=10 道,还缺题型与题库",
  "fields": [
    { "key": "question_type", "label": "题型", "type": "select",
      "options": [{"label":"单选题","value":"SINGLE"}], "required": true },
    { "key": "bank_id", "label": "题库", "type": "select",
      "options": [{"label":"测试题库","value":"1900000000000000001"},
                  {"label":"新建题库","value":"__new__"}] }
  ],
  "submit_text": "继续",
  "cancel_text": "取消"
}
字段说明
kindform(表单)/ choice(选项)/ confirm(确认)
fields[].typetext / number / select / multi / switch
fields[].key回传时作为 answers 的 key
submit_text / cancel_text按钮文案

选项的 value 一律是字符串

题库 ID、考试 ID 是雪花 ID(19 位), 超过 JS 的安全整数范围,走数字会丢精度。

三种中断场景 ​

场景kind说明
缺参数form缺什么一次问完——分多轮追问会让用户觉得「这玩意做不了」
多个命中form + select按名称查到多个题库/考试时让用户选,选项含「新建题库」
写操作前confirm给预览,用户点头才执行;desc 里明写「写操作会真实改动系统数据」

用户不点按钮,直接打字怎么办 ​

_guess_answers() 会猜:

  • 「取消」「算了」「不用了」 → {"__cancel__": true}
  • 「确认」「好的」「执行」 → {"confirmed": true}
  • 单个字段 → 直接填(number 抽数字;select 先按 value 精确匹配,再按 label 前缀)
  • 多字段 → 全数字填 number 字段;select 优先于 text;文本含「题库」且有 new_bank_name 字段 → 当作新建
  • 兜底只认 字段名=值 格式

猜错了比不猜更糟

兜底规则刻意保守。文本含「题库」时优先匹配 select 而不是 text, 否则「测试题库」会被 new_bank_name 文本框吞掉, 导致 bank_id 没赋值、又弹同一张卡——用户会觉得死循环了。

运行轨迹(Trace) ​

每轮返回一个 trace 数组,前端可以渲染成时间线:

json
{
  "id": "s1234567",
  "type": "tool",
  "title": "查询题库",
  "detail": "`POST /api/exam-tool/bank/list`",
  "status": "ok",
  "ref": "list_question_banks",
  "latency_ms": 42,
  "preview": ["测试题库(128 题)", "期末题库(56 题)"]
}
type含义
think思考(理解需求、规划完成)
tool调了内置工具
skill跑了 AI 技能
ask等待用户补充信息(status=waiting)
write写操作
done完成
error出错

关键设计:工具失败不抛异常,返回 status="error" 的步骤—— 对话场景不该因一次工具失败整轮崩掉。

权限门禁 ​

对话 Agent 能调 26 个工具,权限怎么收?

身份从哪来 ​

Java 侧 ChatServiceImpl.buildIdentity() 构造身份快照并传给 Agent:

json
{
  "userId": "1", "userName": "admin", "nickName": "管理员",
  "isSuperAdmin": true,
  "roles": ["admin"],
  "examPermissions": ["exam:ai:list", "system:question:add"],
  "roleScope": "admin",
  "staff": true,
  "note": "没有对应权限码的动作不要规划:即使发出去,网关也会返回 403。"
}

roleScope 判定:*:*:* → admin;有 exam: 权限 → teacher; 角色含 student/考生/学员 → student;否则 unknown。

三道门禁 ​

闸位置行为
① 身份门禁engine.py学生问「出题」/「全班情况」→ 直接转 flow_general,交给规划器按权限重新判断
② 计划门禁check_step_allowed()计划阶段就检查步骤是否越权,越权则 feasible=false 并说明原因
③ 执行门禁Java 侧白名单 + 网关鉴权真正的拦截,越权 403

第 ② 道的价值在于:在计划阶段就告诉用户做不到, 而不是执行到一半吃个 403 才说。

另外 api_manifest 返回的 identity 会覆盖 ctx 里那份——Java 侧按权限算出来的更权威。

会话存储 ​

会话存在 进程内存(app/chat/session.py),刻意不接 Redis:

python
SESSION_TTL  = 1800   # 30 分钟无活动回收
MAX_SESSIONS = 500    # 超出淘汰最久未用的
MAX_HISTORY  = 40     # 每会话保留消息数

DEFAULT_OPTIONS = {
    "context_rounds": 6,     # 带多少轮历史进上下文
    "confirm_write": True,   # 写操作必须先确认
    "model_code": "",        # 留空走默认模型
    "planner": True,         # 开放域先规划再执行
}

理由:对话是短任务,进程重启丢掉可接受; 引入 Redis 会让本地调试必须先装 Redis。

多实例部署时会话会「丢」

Agent 跑多副本时,请求可能被打到没有该会话的实例上。 生产若要多副本,需要开启会话粘性,或把 SessionStore 换成 Redis 实现。

会话里不存 trace——trace 是一次回合的执行日志,回合结束就归档,下次重新生成。

另一套记忆 ​

app/memory/store.py 是与会话独立的另一套机制,走 Redis/内存后端:

类型键TTL
短期记忆st:{session_id}1800 秒
学情画像lt:profile:{tenant_id}:{user_id}长期
评分偏好lt:scoring:{tenant_id}:{marker}长期

目前学情画像被 /api/ai/recommend/diagnose 读写(归因后回写 weak_points)。

幂等性 ​

用户填完追问卡后,engine 会从头重跑整个 flow。 因此 flow 必须满足:已确定的槽位(bank_id、exam_id)存在 slots 里, 重跑时直接跳过匹配步骤,不能重复弹同一张卡。

接口 ​

方法路径用途
POST/ai/chat对话(经网关,推荐)
GET/ai/chat/sessions历史会话列表(只带摘要)
GET/ai/chat/session/{id}会话详情(带全量消息)
GET/ai/chat/whoami当前用户的 AI 可见范围

请求体 AiChatBo:

字段说明
sessionId首轮不传
message用户消息;提交追问卡时只回 answers,message 可为 null
answers{key: value},key 对应 AiChatFieldVo.key
modelCode指定模型,不传走主备链
optionscontextRounds / confirmWrite / planner

/chat 在网关上不可达

网关只配了 Path=/ai/**,所以 /chat、/chat/sessions 走不通, 前端请统一用 /ai/chat 前缀。详见 AI 服务部署与配置。

相关文档 ​

砚考 · 让每一次考试都经得起检验