zclaw_openfang/wiki/known-issues.md

title, updated, status, tags

title	updated	status	tags
已知问题	2026-04-16	active	issues bugs

已知问题

从 index 导航。完整清单见 docs/TRUTH.md §3

当前状态

级别	数量	状态
P0 (崩溃)	2	全部已修复
P1 (功能失效)	9	全部已修复
P1.5 (代码质量)	7	全部已修复
P2 (代码质量)	10	待处理
V13 P1 (断链)	3	全部已修复
V13 P2 (差距)	3	全部已修复

V13 审计修复 (2026-04-13 全部完成)

P1 — 功能断链 ✅ 全部已修复

ID	问题	修复
V13-GAP-01	TrajectoryRecorderMiddleware 未注册到中间件链	✅ 已注册 @650，Hermes 轨迹数据开始流入
V13-GAP-02	industryStore 存在但无组件导入	✅ 已接入 ButlerPanel，桌面端展示行业专长卡片
V13-GAP-03	桌面端未接入 Knowledge Search API	✅ saas-knowledge mixin + VikingPanel SaaS KB 搜索 UI

P2 — 代码清洁度 ✅ 全部已修复

ID	问题	修复
V13-GAP-04	Webhook 孤儿表	✅ deprecated 标注 + down migration 注释
V13-GAP-05	Structured Data Source 无 Admin UI	✅ Admin Knowledge 新增"结构化数据"Tab
V13-GAP-06	PersistentMemoryStore 遗留模块	✅ 全量移除 — persistent.rs 611→57 行

Heartbeat 参数名修复 (2026-04-16)

问题	级别	状态
Tauri invoke 参数名 snake_case 错误	P1	✅ 已修复

根因: Tauri 2.x #[tauri::command] 默认 rename_all = "camelCase"，前端 invoke 必须用 camelCase（agentId 不是 agent_id）。intelligence-client.ts 中 3 处 invoke 调用使用了错误的 snake_case。

修复: commit f6c5dd2 — 3 处参数名修正 + HealthPanel.tsx 恢复正确命名。

教训: 所有 Tauri invoke 调用的参数名必须用 camelCase，与 Rust 端 snake_case 参数名对应。参见 browser-client.ts 中已有的正确示例。

Relay API Key 解密自愈 (2026-04-16)

问题	级别	状态
Provider Key 解密失败导致整个 relay 500	P1	✅ 已修复

根因: key_pool.rs 的 select_best_key 遍历 key 时，第一个解密失败的 key 就通过 ? 直接返回 500，不会尝试下一个。如果 DB 中有旧的加密 key（密钥已变更），整个 relay 请求被阻断。重新保存只能临时解决，旧 key 仍在 DB 中。

修复: commit b69dc61:

• 解密失败时 warn + continue 跳到下一个 key
• 启动自愈 heal_provider_keys(): 逐个解密并重新加密，无法解密的标记 inactive

教训: 密钥池选择应容错（skip bad keys），而不是 fail-fast。加密数据迁移应自动化。

设置页面清理 (2026-04-16)

变更	说明
删除"用量统计"页面	与"订阅与计费"功能重复
删除"积分详情"页面	与"订阅与计费"功能重复

commit 7dea456 — 移除 UsageStats + Credits 组件及菜单项。

三端联调测试 V2 (2026-04-15)

通过 Chrome DevTools MCP + Tauri MCP 实际界面操作验证。

已修复

问题	级别	修复
SSE 中转任务 Token (入/出) 全部为 0	P2	✅ SseUsageCapture 增加 stream_done 标志 + 前缀兼容

已验证通过

功能	状态	验证方式
桌面端登录 (SaaS 模式)	✅	Tauri MCP 实际登录
聊天流 (kimi-for-coding)	✅	发送消息并收到流式回复
模型切换	✅	切换 deepseek → kimi
智能体面板	✅	显示"默认助手"
设置 20 个选项卡	✅	逐页检查：用量统计/模型/记忆/SaaS平台
语义记忆搜索	✅	100 条记忆，FTS5 + TF-IDF
Admin V2 仪表盘	✅	Chrome DevTools: 30 账号/3 服务商/17 请求
Admin V2 账号管理	✅	30 用户正常展示
Admin V2 模型服务	✅	DeepSeek/Kimi/zhipu 3 个 Provider
Admin V2 API 密钥	✅	不再崩溃（上次修复验证）
Admin V2 知识库	✅	6 条目 + 5 个 Tab
Admin V2 行业配置	✅	4 个内置行业
Admin V2 计费管理	✅	团队版 570/20000 中转请求
Admin V2 角色权限	✅	3 角色（超管/管理/用户）
Admin V2 操作日志	✅	2088 条记录
Admin V2 Agent 模板	✅	10 模板（3 内置 + 7 自定义）

待处理 / 观察项

问题	级别	说明
Admin 用量统计 0/0	P2	用量统计页显示请求=0/Token=0，但仪表盘显示 17 请求/6304 Token。数据来源不同
Deepseek 中转任务卡 processing	P3	Provider Key 禁用后已有任务不会自动清理，需手动处理
桌面端 Token 统计为 0	P2	用量统计页 Token 输入/输出=0，但图表显示 ~3.6M，数据不一致

三端联调测试 (2026-04-14)

30+ API / 16 Admin / 8 Tauri 全量测试结果：

问题	级别	状态
API 密钥页崩溃 (undefined .map)	P1	✅ 已修复
桌面端 401 后不自动恢复	P1	✅ 已修复
用量统计全零 (telemetry SQL timestamptz)	P1	✅ 已修复
行业选择 500 (industry 类型匹配)	P1	✅ 已修复
管理员切换订阅计划 500	P1	✅ 已修复
SaaS 启动崩溃 (config_items 约束)	P1	✅ 已修复
SaaS 模型选择残留模型 ID	P0	✅ 已修复

代码健康度指标（2026-04-14）

指标	值	变化	说明
TODO/FIXME 前端	1	4→1	大幅减少
TODO/FIXME Rust	3	4→3
@reserved 标注	22	33→22	Butler/MCP 已接通
dead_code 标记	16	76→16	大幅减少
前端孤立 invoke	0	不变	已清理

长期观察项

问题	说明	位置
Tauri 命令孤儿	注册 189 命令，前端调用 106 处，@reserved 22 个，剩余 ~61 可能内部调用	desktop/src-tauri/src/lib.rs
Embedding 未激活	NoOpEmbeddingClient 为默认值，用户配置后替换为真实 provider	zclaw-growth/src/retrieval/semantic.rs
SaaS embedding deferred	pgvector 索引就绪，生成未实现	zclaw-saas/src/workers/generate_embedding.rs
SkillIndex 条件注册	无技能时 skill_index 中间件不注册	kernel/mod.rs:309

已修复的关键问题（历史记录）

ID	问题	修复日期
SEC2-P0-01	skill_execute 反序列化崩溃	04-02
SEC2-P0-02	TaskTool::default() panic	04-02
SEC2-P1-01~09	9 项功能失效 (FactStore/路径/监听/...)	04-02
SEC2-P1.5-01~07	7 项代码质量修复	04-02
P0-2/P0-3	usage 端点 + refresh token 类型	04-10
P1-02	浏览器聊天 SaaS fixture	04-10
P1-04	AuthGuard 竞态条件	04-10
BREAKS 全部	全部 P0/P1/P2 已修复	04-10
V13-GAP-01~06	6 项断链/差距全部修复	04-13
三端联调 P0/P1	7 项全部修复	04-14

→ 模块详情见各模块页面: routing chat saas memory middleware