调试与排障
从日志到请求落盘，定位 Ishiki 的各类问题
Ishiki 的调试面有三层：日志、请求落盘、流式分片。
打开调试开关
插件级配置（koishi.yml 或控制台插件配置页）：
ishiki:
logLevel: 3 # 0=ERROR 1=WARN 2=INFO 3=DEBUG，默认 2
dumpRequests: true # 每次模型请求/响应落盘
debugStream: true # 模型流分片实时打到控制台三者成本递增：logLevel: 3 常驻无妨；dumpRequests 每请求写两个文件；debugStream 只适合本地盯着看。排障结束记得关掉后两个。
看某次请求发了什么
dumpRequests: true 时，每次模型调用在 <dataPath>/requests/ 下写一对文件：
*-request.json 是发出的请求体，*-response.sse 是原始 SSE 响应流。
文件名前缀是时间戳加序号，按时间排序即可回放一次对话的所有请求。这能直接回答：系统提示词长什么样、工具目录给了哪些、历史投影后剩了什么、附件消息在不在。
密钥在请求头而不在请求体里；但响应与历史可能含聊天内容，注意文件安全。
看模型每步在想什么
debugStream: true 时控制台实时输出流分片：文本增量、工具调用、每步用量（输入/输出/缓存 token）。判断「模型为什么这么做」看这里最快。
按启动日志定位装配问题
启动期的报错集中且信息明确，对照速查：
| 日志 | 含义 | 处理 |
|---|---|---|
Model config file not found … creating an empty one | 已有数据目录缺少模型配置 | 填写新建的 models.yaml |
[<ID>] missing required service "…"; profile is waiting | profile 声明的扩展/引擎服务不存在 | 按名补装对应插件或改正拼写；装好后重载自动装配 |
[<ID>] profile skipped: … | 该 profile 解析失败或频道冲突，被整体跳过 | 看冒号后的具体原因 |
toolcall runtime unavailable, nothing loaded | 工具调用运行时加载失败，全部 profile 未装载 | 检查依赖安装是否完整 |
[<ID>] profile activation failed: … | profile 装配中途失败（如图片能力校验不过） | 按原因修 profile |
profile loading failed, nothing loaded | profiles 根目录整体加载失败 | 检查目录权限与 YAML 语法 |
运行期问题
按顺序查：频道被认领了吗（channels 匹配规则见编写 profile）→ 唤醒条件命中了吗（调整唤醒行为）→ 模型调用报错了吗（dumpRequests 看最后一次请求的响应）→ send_message 失败了吗（debug 日志有 Failed to send message）。
先看该请求的 request.json 里工具结果是什么形态；文本协议类引擎（非 native）对输出格式敏感，换模型或换引擎对比。
见接入 MCP 服务器的排错表。
见启用工作区的排错表。
数据目录的调试视角
<dataPath> 下的产物都可以直接查看，布局见参考：数据目录。两个常用点：
<profile>/runtimes/<实例>/events.jsonl是实例的完整事件流（JSONL），一行一个 JSON，是还原一次对话的最终事实。<profile>/runtimes/<实例>/resources/下的assets/、artifacts/是媒体与工具输出的落盘字节。asset 使用<uuid>.<实际扩展名>与<uuid>.metadata.json，artifact 使用内容寻址文件名与<name>.json元数据。