72 lines
4.8 KiB
Markdown
72 lines
4.8 KiB
Markdown
# 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 容器内执行：
|
||
|
||
```bash
|
||
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`、`idle_consolidation_minutes`、`timeline_retention_days` 和 `max_failures_before_degrade` 都能被配置解析，但每轮 Knowledge 召回仍固定为 5，自动 idle consolidation、Timeline 清理和失败降级循环尚未接入。以当前代码行为为准。
|
||
|
||
## Q: Gateway 为什么无法立即退出？
|
||
|
||
正常关停会先停止渠道，再取消受 TaskSupervisor 管理的后台任务，并最多等待 10 秒。飞书自身另有 5 秒连接任务兜底。如果持续超过这些上限，应检查是否新增了未受监督的 `tokio::spawn`、不可取消的外部 I/O，或没有 timeout 的 JoinHandle 等待。
|