主题
调试与排查
技能调试
在「技能开发」应用中调试
技能开发应用（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/ 目录 |
运行时排查
查看智能体日志
排查智能体运行行为时，可以查看容器日志：
bash
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" | |
| | +------------------------------------+ |
+----------------------------------------------------------+划词标注与导出
在对话界面中，可以对智能体的输出进行划词标注，标记回答质量（好/差），并导出标注数据用于后续分析和改进。
系统冒烟测试技能
平台内置了冒烟测试技能，可以快速验证智能体的基础能力是否正常（如工具调用、技能加载等）。