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 callerchayuan-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 关联 + 详细日志 + 联调工具让两端协同诊断顺畅。
