acf74981b2
Replace the unconditional top-5 keyword recall with a deterministic, layered gate so only relevant Knowledge entries reach the prompt. - New src/memory/recall.rs: tokenization with stopword filtering and a bounded term list; ranking combines lexical relevance, importance and recency; double gate (min_relevance + min_score) drops weak or stale matches; hard tokio::time::timeout wraps the SQL search so a slow FTS5 query never delays a turn. - MemoryConfig gains recall_min_relevance, recall_min_score, recall_recency_half_life_days, recall_timeout_ms (default 1000ms); recall_limit is now actually wired instead of being a dead field. - MemoryManager::recall_for_context exposes the gated path; the memory_recall tool keeps the raw search. - Storage::search_memories / search_memories_by_time share a single jieba-based tokenizer via the new module; search_memories_by_terms accepts pre-tokenized input for the gated path. - Docs and example configs (README, about-picobot references, both config.example.json templates) updated to reflect the new behavior.
5.0 KiB
PicoBot 常见问题
Q: 如何切换模型？
修改 config.json 中 agents 配置，指定不同的 provider 和 model。如需新的 provider，在 providers 中添加对应 API 配置。
Q: 如何添加新的渠道？
在 config.json 的 channels 中添加新条目。目前支持飞书 (feishu)，CLI 客户端无需配置。
Q: 如何安装 skill？
将包含 SKILL.md 的目录放入 ~/.picobot/skills/，程序自动检测。也可通过 agent 在 workspace 的 skills/ 下创建新 skill。
Q: 为什么 get_skill 找不到某个 skill？
确保 skill 目录中有 SKILL.md 文件，且文件头有正确的 frontmatter（name、description）。用 get_skill action="list" 查看当前加载的所有 skill。注意同名 skill 按目录优先级覆盖。
Q: 内置的 about-picobot 文档在哪里？
~/.picobot/skills/about-picobot/ 下，SKILL.md 为索引，references/ 下为各详细文档，assets/ 下为 config 示例。如被删除，重启程序自动重新安装。
内置 Skill 只在目标目录不存在时释放，不会覆盖已安装目录。升级 PicoBot 后如需获取新版内置文档，应先备份自己的修改，再删除旧的 ~/.picobot/skills/about-picobot/ 并重启。也可把定制版放在 {workspace}/skills/about-picobot/，它的优先级更高。
Q: Docker 部署如何获取 WebUI 设备配对码？
在 Gateway 容器内执行：
docker compose exec picobot picobot pair --gateway-url http://127.0.0.1:19876
使用 docker-compose.test.yml 时增加 -f docker-compose.test.yml。签发接口要求请求来自 Gateway 的真实回环地址，并校验 /app/.picobot/web_admin_token；因此不要从宿主机经发布端口直接请求，也不要复制或输出管理密钥。代码为 8 位、5 分钟有效且只能使用一次。
Q: 数据库文件在哪里？
默认 {config_dir}/data/picobot.db，config_dir 默认 ~/.picobot，与 workspace 相互独立。
Q: 如何禁用某个 skill 或 MCP 服务器？
Skill 安装后默认启用，可在 WebUI「工具 → Skills」页用开关禁用；禁用状态记录在 ~/.picobot/skills_state.json，被禁用的 skill 不再进入提示词、列表和 get_skill。MCP 服务器在配置 mcp.servers[].enabled（默认 true）中控制，可在 WebUI「工具 → MCP」页开关；关闭后下次启动/重载时不连接该服务器。
Q: 如何查看历史会话？
使用 chat_manager 工具：action="list_sessions" 列出会话，action="list_messages" 查看指定会话消息，支持 offset 翻页、before_time/after_time 时间范围过滤。
Q: 如何创建定时任务？
使用 cron_add 创建，cron_list 查看，cron_update、cron_enable、cron_disable、cron_remove 管理。Schedule 类型为 at（Unix 毫秒时间戳）、every（毫秒间隔）或 6 段 cron 表达式，可指定 IANA 时区。
Q: 上下文压缩是什么意思？
对话接近模型 token 限制时，PicoBot 用一份累计 checkpoint 摘要替代 Provider 上下文中的旧前缀，并原样保留近期消息尾部。原始消息和工具结果仍永久保存在聊天历史/SQLite 中，只是不再永久占用模型上下文；语义摘要还可通过 timeline_recall 检索。Model 的 token_limit 是窗口硬上限，未配置时为 128K；Agent 的可选 token_limit 只能收紧它，两者都有时取最小值。自动阈值采用窗口减 reserve 的机制，摘要输入按有效窗口动态限制而非固定 32K；换成更小模型后若历史已经超限，会在首次普通模型请求前压缩或明确降级。/compact 可在阈值前手动强制执行。
Q: 如何修改 gateway 监听端口？
在 config.json 的 gateway.port 中设置，重启网关生效。默认 19876。
Q: 如何查看 LLM 调用日志？
LLM 调用记录存储在 llm_calls 表中。可通过 SQLite 客户端直接查询，或在代码中通过 storage 模块访问。
该表可能包含完整用户消息、工具参数和模型响应，按敏感数据处理；不要直接上传或粘贴到公开 issue。
Q: 为什么修改了某些 memory 配置却没有看到行为变化？
当前 recall_limit 以及新增的 recall_min_relevance、recall_min_score、recall_recency_half_life_days、recall_timeout_ms 均已生效，控制每轮自动知识召回的相关性门槛、加权与超时。idle_consolidation_minutes、timeline_retention_days 和 max_failures_before_degrade 仍只是配置解析：自动 idle consolidation、Timeline 清理（由维护任务执行）和失败降级循环尚未接入。以当前代码行为为准。
Q: Gateway 为什么无法立即退出？
正常关停会先停止渠道，再取消受 TaskSupervisor 管理的后台任务，并最多等待 10 秒。飞书自身另有 5 秒连接任务兜底。如果持续超过这些上限，应检查是否新增了未受监督的 tokio::spawn、不可取消的外部 I/O，或没有 timeout 的 JoinHandle 等待。