Studio Runbooks

Studio 是管理员和实施团队的日常控制面。这里不再只列栏目名，而是把高频任务拆成可执行 runbook。

适用对象

• 平台管理员
• 实施 / 运营同学
• 需要在 Studio 上排查知识、工具、评测、对话问题的研发

任务总览

任务	先看哪里	成功标志
管理 Agent 与运行时配置	Agent 列表、Agent Detail、Fusion 工作区	Agent 配置已保存，运行时 key / 挂载关系正确
维护 knowledge source 与 ingestion	Knowledge source 页面、RAG debug、manual inspection	source 已挂载，文档已 indexed，检索结果可解释
管理 MCP server、凭据和挂载	MCP Servers 页面、health check、test call	server 可用、credential 生效、agent mount 正确
维护 evaluation datasets 与运行	Evaluation Datasets 页面、run 结果页	dataset 可导入、run 可启动、结果可导出
查看 conversations、audit、takeover	Conversations、Audit Logs	session 状态、trace、turn context 可追溯
管理 scheduled tasks	Scheduled Tasks 页面与后台记录	task 创建成功、next run 正确、run history 正常

Runbook 1: Agent 与运行时配置

目标

确认一个 Agent 的类型、orchestrator、模型、RAG、MCP、Skill 或 Fusion 绑定符合预期。

关键入口

• Agent 列表与详情页
• Fusion 工作区
• 模型配置页面

后端真相源

• ai_service/api/routers/agents.py
• ai_service/orchestrator/registry.py
• ai_service/fusion/application/use_cases/manage_definition.py

失败症状

• Agent 页面保存成功，但聊天行为没有变化
• Fusion Agent 仍然执行旧 definition
• 模型路由或 MCP response config 没生效

排查动作

1. 先确认 Agent 版本和当前生效配置是否一致
2. 再确认 orchestrator_key、模型路由、MCP runtime config 是否真的持久化
3. 如果是 Fusion 相关问题，检查 Agent 与 definition 的 link 是否已同步

Runbook 2: Knowledge Source 与检索质量

目标

确认知识源是否成功挂载、文档是否完成摄取、检索质量问题属于哪一层。

关键入口

• Knowledge source 页面
• 文档列表
• RAG debug
• Manual inspection

后端真相源

• ai_service/api/routers/knowledge.py
• ai_service/services/ingestion.py
• ai_service/services/rag_debug.py
• ai_service/services/manual_inspection.py
• ai_service/services/snapshot_rebuild.py

常见症状与动作

症状	优先动作
文档上传后一直不可用	先看 ingestion job 状态与 document status
文档显示 indexed 但检索不到	先跑 RAG debug，再看 vector health
怀疑 chunking 不合适	跑 manual inspection 的 chunking_preview
怀疑向量丢失或 collection 不一致	跑 manual inspection 的 vector_health，必要时 snapshot rebuild
对话中知识错误需要长期修正	走 conversation correction 发布链路，不要手改 managed correction source

Runbook 3: MCP Server 与工具调用

目标

确认 MCP server 是否可连接、凭据是否可用、agent 是否正确挂载。

关键入口

• MCP Servers 页面
• Health check
• Test call
• Agent MCP mounts

后端真相源

• ai_service/api/routers/mcp.py
• ai_service/services/mcp_client.py
• ai_service/services/mcp_secret_manager.py
• ai_service/services/mcp_policy.py
• ai_service/services/mcp_audit.py

常见症状与动作

症状	优先动作
health check 失败	先确认 transport type 与 connection config 是否匹配
list tools 为空	检查 credential 注入、timeout、server status
工具能测通但聊天里不触发	检查 agent mount、policy、MCP response config
返回内容不符合预期	检查 quick match / intent gate / direct response field catalog

Runbook 4: Evaluation Dataset 与 Run

目标

确认评测数据可导入、评测 run 正常执行、结果可导出和复盘。

关键入口

• Evaluation Datasets 页面
• Evaluation Run 详情页
• CSV import / export

后端真相源

• ai_service/api/routers/evaluation.py
• ai_service/services/evaluation_dataset_importer.py
• ai_service/services/evaluation_runner.py
• ai_service/services/evaluation_judge.py
• ai_service/services/evaluation_gate.py

常见症状与动作

症状	优先动作
数据集导入失败	先看 CSV 解析和 import error
run 一直卡住	检查 runner supervisor、lease、resume 状态
gate 结果异常	检查 gate policy 与 judge 输出
想导出结果给外部复盘	走 results export，而不是手查数据库

Runbook 5: Conversations、Audit 与人工接管

目标

确认单个会话的 turn、上下文、审计记录、takeover 事件可追溯。

关键入口

• Conversations 页面
• Audit Logs
• Turn context / trace 链接

后端真相源

• ai_service/conversations/interfaces/http/router.py
• ai_service/services/runtime_checkpoint_service.py
• ai_service/services/admin_audit.py
• ai_service/services/mcp_audit.py
• ai_service/services/skill_audit.py

常见症状与动作

症状	优先动作
会话消息正常，但上下文看不懂	打开 turn context snapshot
MCP / Skill 调用了，但前台没解释清楚	查对应 trace id 下的 audit 记录
需要人工接管或释放接管	先看 session takeover 状态，再执行接管/释放动作

Runbook 6: Scheduled Tasks

目标

确认会话定时任务是否创建成功、触发时间正确、执行历史可追溯。

关键入口

• Scheduled Tasks 页面
• Task run history

后端真相源

• ai_service/api/routers/scheduled_tasks.py
• ai_service/services/scheduled_tasks.py
• ai_service/services/timer_scheduler.py

常见症状与动作

症状	优先动作
task 创建失败	检查 schedule payload、timezone、payload.prompt
next run 不符合预期	检查 schedule_kind、interval / cron 解析、timezone
task 已创建但没有执行	检查 timer scheduler 是否在跑、task 状态是否被 cancel
run 有记录但没有 usage 信息	检查 linked conversation turn 是否存在

发生故障时的最小判断顺序

1. 先分清问题属于 Agent、Knowledge、MCP、Evaluation、Conversation 还是 Scheduled Task
2. 再定位是控制面数据错误、运行时执行错误，还是外部依赖错误
3. 优先使用 Studio 自带的 debug / audit / run history，而不是先连数据库手查

相关系统

• 知识库相关：看 RAG 运维
• 工具接入相关：看 MCP 运维
• 单证识别相关：看 单证识别运维
• 评测相关：看 评测系统