加载项与桌面端的协同诊断 一份联调日志

chayuan-wps 加载项跟 察元AI智能体 联调诊断。这一篇讲一份完整联调日志。

联调场景

某员工反馈：在 WPS 里问 KB 偶尔报错 检索失败。

排查需要 chayuan-wps（前端）+ 察元AI智能体（后端）的联合日志。

启用调试模式

chayuan-wps 加载项设置 - 调试 - 开启详细日志。

察元AI智能体 设置 - 调试 - 开启详细日志。

两边都生成详细日志。

实战日志

用户操作：在 WPS 里问 客户 X 的合同状态。

chayuan-wps 日志。

[2026-05-10 14:23:05] [chayuan-wps] User asked: "客户 X 的合同状态" [2026-05-10 14:23:05] [chayuan-wps] Selected KBs: ["doc:contracts", "office:zhangsan:notes"] [2026-05-10 14:23:05] [chayuan-wps] Calling 察元AI智能体 POST /api/v1/kb-query/search [2026-05-10 14:23:05] [chayuan-wps] Request body: {...} [2026-05-10 14:23:05] [chayuan-wps] Trace ID: abc123

察元AI智能体 日志。

[2026-05-10 14:23:05] [察元AI智能体] Received search request, trace=abc123 [2026-05-10 14:23:05] [察元AI智能体] orchestrator: dispatching to adapters [2026-05-10 14:23:05] [察元AI智能体] document adapter: searching doc:contracts [2026-05-10 14:23:05] [察元AI智能体] office adapter: searching office:zhangsan:notes [2026-05-10 14:23:06] [察元AI智能体] document adapter: found 5 chunks (320ms) [2026-05-10 14:23:08] [察元AI智能体] office adapter: ERROR - timeout (3000ms) [2026-05-10 14:23:08] [察元AI智能体] orchestrator: returning partial results, 1 source failed [2026-05-10 14:23:08] [察元AI智能体] reranking 5 chunks [2026-05-10 14:23:08] [察元AI智能体] returning 5 chunks to caller

chayuan-wps 收到响应日志。

[2026-05-10 14:23:08] [chayuan-wps] Received 5 chunks, but office:* search failed [2026-05-10 14:23:08] [chayuan-wps] Showing partial results to user with warning

联调发现

从联调日志看出。

doc:contracts 检索正常。

office:zhangsan:notes 检索 timeout。

具体原因 察元AI智能体 进一步日志。

[2026-05-10 14:23:08] [察元AI智能体] office adapter detail: - sqlite query timed out - sqlite-vec extension may have lock contention - suggestion: optimize KB index

诊断到具体原因。

解决

发现 office:zhangsan:notes KB 太大（10 万 chunk）+ 没建索引。

优化建议。

察元AI智能体 设置 - 知识库 - 优化索引 [优化 office:zhangsan:notes] 预计 5 分钟。

优化后查询恢复。

跨进程 trace

每次请求一个 trace_id。

chayuan-wps 生成 trace_id 传给 察元AI智能体。察元AI智能体 内部所有 span 用同一 trace_id。日志能关联。

日志的位置

chayuan-wps 日志。

~/.chayuan/logs/wps-addin/

察元AI智能体 日志。

~/.chayuan/logs/desktop/

便于开发者收集。

日志的脱敏

某些日志含敏感数据（用户问题、KB chunk 内容）。察元AI智能体 / chayuan-wps 默认脱敏。

"用户问题：[姓名]的[文档类型]"

调试模式开启时可关闭脱敏（仅本地用）。

联调工具

察元AI智能体 提供联调工具。

察元AI智能体 --debug-tool

启动一个 web UI（127.0.0.1:62582）显示实时联调日志。两边日志合在一起按 trace_id 排序。

便于复杂问题排查。

国产化场景

党政军场景排查问题不能联网（不能发日志给开发者远程调试）。

察元AI智能体 的本地联调工具是必要。

某些场景需要把日志带出内网走审批。察元AI智能体 的脱敏 + 导出工具支持。

chayuan-server 的对应

chayuan-server 多用户场景下日志聚合。察元AI智能体 单机本地日志。chayuan-wps 跟两者协议一致。

总结

加载项与桌面端的协同诊断是 察元AI智能体 + chayuan-wps 在排查问题上的工程能力。免费开源的AI软件 让 跨组件 bug 也能精准定位。察元AI智能体 的 trace 关联 + 详细日志 + 联调工具让两端协同诊断顺畅。