技能与解决方案调试

技能调试

在「技能开发」应用中调试

技能开发应用（http://<host>:8020/studio/skill-editor）提供技能的在线编辑和调试能力。在该应用中可以：

实时编辑 SKILL.md 并测试效果
上传完整的解决方案包进行集成调试
查看技能解析结果和工具列表

+----------------------------------------------------------+
|  技能开发应用  http://<host>:8020/studio/skill-editor     |
+----------------------------------------------------------+
|  左侧面板           |  右侧对话区                         |
|  +--------------+   |  +----------------------------+     |
|  | SKILL.md     |   |  | 用户: 帮我分析这份数据     |     |
|  | 编辑器       |   |  |                            |     |
|  |              |   |  | 智能体: 正在调用技能...     |     |
|  | ---          |   |  | [工具调用详情]              |     |
|  | name: xxx    |   |  |                            |     |
|  | description: |   |  +----------------------------+     |
|  | ---          |   |                                     |
|  |              |   |  状态: 技能已加载 | 工具: 3 个      |
|  +--------------+   |                                     |
+----------------------------------------------------------+

上传解决方案时自动校验

在技能开发应用中上传解决方案包时，系统会自动校验目录结构和字段合法性。校验不通过时，界面会提示具体的错误信息。

+----------------------------------------------------------+
|  上传解决方案                                              |
+----------------------------------------------------------+
|                                                          |
|  [拖拽或点击上传 solution.zip]                             |
|                                                          |
|  校验结果:                                                |
|  x 错误: role.yaml 中的 id "prd" 与目录名 "sf_prd" 不一致 |
|  x 错误: local_skills 引用的 "analyzer" 在 skills/ 下不存在|
|  ! 警告: 未设置 initial_message                           |
|                                                          |
+----------------------------------------------------------+

常见校验错误

错误	原因	解决方法
`id` 与目录名不一致	`role.yaml` 中的 `id` 与所在目录名不同	保持 `id` 和目录名一致
技能路径不存在	`local_skills` 引用的技能在 `skills/` 下找不到	在 `skills/<id>/` 下创建 `SKILL.md`
`roles` 列表为空	`solution.yaml` 中没有定义角色	至少添加一个角色 id
包含未知字段	YAML 中存在不支持的字段	移除多余字段或检查拼写
v3 不支持角色级技能目录	在 `roles/<id>/skills/` 下放了技能	将技能移到 Solution 级 `skills/` 目录

运行时排查

查看智能体日志

排查智能体运行行为时，可以查看容器日志：

docker logs <container_name> --tail 100 -f

日志包含 session 创建、技能同步、错误信息等运行时事件。

LLM 观测页面

在智能体高级设置中，可以进入 LLM 观测页面 查看完整的 LLM payload 业务日志，包括：

每轮对话发送给模型的完整 prompt
模型返回的原始响应
工具调用的输入输出

+----------------------------------------------------------+
|  高级设置 > LLM 观测                                      |
+----------------------------------------------------------+
|  会话列表      |  请求详情                                 |
|  +----------+  |  +------------------------------------+  |
|  | 会话 1   |  |  | 时间: 2024-01-15 10:32:05          |  |
|  | 会话 2 ← |  |  | 模型: gpt-4                        |  |
|  | 会话 3   |  |  | Token: 输入 1234 / 输出 567        |  |
|  +----------+  |  |                                    |  |
|                |  | [System Prompt]                    |  |
|  过滤:         |  | 你是一个专业的...                    |  |
|  [ 全部  v ]   |  |                                    |  |
|                |  | [Tool Call] bash_tool              |  |
|                |  | 输入: {"command": "ls"}            |  |
|                |  | 输出: "file1.txt\nfile2.txt"       |  |
|                |  +------------------------------------+  |
+----------------------------------------------------------+

划词标注与导出

在对话界面中，可以对智能体的输出进行划词标注，标记回答质量（好/差），并导出标注数据用于后续分析和改进。

系统冒烟测试技能

平台内置了冒烟测试技能，可以快速验证智能体的基础能力是否正常（如工具调用、技能加载等）。

常见运行时失败

现象	先确认	处理
沙箱一直启动中	Docker daemon、镜像是否存在、磁盘和挂载权限	查看 Blade Agent 与 Docker 日志；不要只刷新页面重复创建会话
模型请求超时或空响应	模型源健康、配额、LLM Gateway 延迟	在 LLM 观测页找首个上游错误；确认没有把全局模型状态误关
浏览器登录态失效	页面是否回到登录页，Cookie 是否过期	让用户重新登录或接管浏览器；不要盲目重试业务按钮
长任务中断	是否收到 `system:error`、后台任务是否仍在运行	保存 `session_id` 和工具输出；检查后台任务接口，再决定恢复或重跑
Skill 显示已安装但会话找不到	会话技能快照、Solution 引用、版本是否一致	重新同步会话 Skill；检查 `local_skills` / `imported_skills` 与注册中心版本
工作区文件不存在	上传目录、文件名、会话是否正确	用工作区列表接口核对路径，不要让智能体猜文件名

排障时先保留 session_id、Blade Agent 版本、Solution、BizRole 和 Skill 版本。只截一张错误弹窗通常不够。