PicoBot/docs/CHANGELOG.md

变更日志

本文件记录 Picobot 各版本的显著变更，遵循 Keep a Changelog 风格。

0.2.0 - 2026-07-31

较 0.1.2 的 47 个 commit 迭代，聚焦 能力策略、模型独立配置、话题级并发隔离 与 Agent Loop 性能优化 四大方向。

新增功能

能力策略（CapabilityPolicy）统一模型

• 新增 CapabilityPolicy 领域模型，统一管理专家/子代理/技能的 allowed_skills / denied_skills / allowed_tools / denied_tools 四类白/黑名单。
• 专家和子代理的 Markdown frontmatter 支持上述四类字段，在 create_agent 时按策略过滤 ToolRegistry（快照语义）。
• 子代理支持数据驱动的工具过滤，删除旧版内置 explore 白名单。
• 新增 HTTP 端点 GET /api/tools 与 PUT /api/subagents/update，供前端动态加载工具清单与更新子代理配置。
• 前端引入通用 CheckboxList 勾选组件，将 capability 字段从自由文本 textarea 改为按来源分组的勾选式编辑，避免手输工具名。

模型独立配置

• 专家和子代理的 Markdown frontmatter 新增 provider 与 model 可选字段，引用 config.json 中的 providers / models 表，可独立指定模型而不再继承主 agent。
• 主 agent 支持会话级模型覆盖（provider / model 在配置层覆盖）。
• 前端编辑模态框新增"模型配置"卡片，含 provider/model 下拉选择，选项由 GET /api/model-options 提供。
• 专家引用不存在的 provider/model 时阻断会话并报错；子代理引用失败时将错误回传给 LLM。

话题级并发隔离

• 实现聊天消息串行锁，确保同一聊天的消息处理串行执行。
• 串行锁按 topic_id 键化，支持多话题并发执行，互不阻塞。
• topic_id 全程显式传递（从消息接收到历史加载），修复消息错投与并发阻塞。
• 内存历史缓存按 topic_id 键化（原按 chat_id），修复 DB 压缩时的 TOCTOU 覆盖问题。

子代理嵌套深度配置

• 暴露 tools.task.max_nesting_depth 为可配置项（默认 2），前端"Task 子代理"卡片新增输入框。
• 保留双重防护：工具调用前校验 + 工具集构造时按深度移除 task 工具。

专家配置热更新

• 专家配置保存后即时生效，无需重启网关。

工具调用序列前向检查

• 添加工具调用序列的前向校验，确保 tool 消息紧随 assistant 的 tool_calls 消息，避免 OpenAI/DeepSeek API 400 错误。

前端测试基础设施

• 引入 vitest 测试基础设施，添加 useChat handleServerMessage 特征测试。

性能优化

Agent Loop 性能（P0）

• 工具定义缓存：get_definitions() 从每轮迭代调用一次改为 process() 循环外构建一次。基于快照语义——单次 process() 内 Arc<ToolRegistry> 不变，专家切换只影响下一次 create_agent。
• 轻量 token 估算：新增 estimate_text_tokens_from_chat_messages，直接基于 ChatMessage 累加字段长度，消除中间 text_only_messages: Vec<Message> 构造（原方案每条消息 × 5 字段双克隆）。
• 工具 token 估算循环外预算：serde_json::to_string 全量序列化工具定义从每轮一次降为 process() 内一次。
• DB 写 offload：PersistingEmittedMessageHandler 用 tokio::task::spawn_blocking 包装 SQLite 同步写，解除 tokio worker 线程阻塞，不改变失败语义（仅记日志不阻断主流程）。

SessionPool 锁范围收敛

• ensure_session_internal 改为 double-checked locking：先短暂持锁检查存在性，释放锁后执行耗时的 session 创建（含配置加载、agent 工厂构造），再次持锁插入并处理竞态。避免跨 session_factory.create().await 持有全局锁导致所有 channel 的 session 访问串行化。

修复

安全修复

• 修复 SSRF 重定向绕过漏洞。
• 修复符号链接路径遍历漏洞。
• 修复 TodoItemSummary 字段缺失。

并发与稳定性

• replace_todos 用 transaction() 包裹 DELETE + INSERT，保证原子性——中途失败自动回滚，避免 todos 列表丢失。事务内复用同一连接查询返回值，消除 drop(conn) 后重新 pool.get() 的冗余。
• 修复话题隔离下 topic_id 全程显式传递，解决消息错投与并发阻塞。
• 修复内存历史按 topic_id 键化，新增 replace_topic_history 修复 DB 压缩覆盖。
• 修复 http.rs 重启信号吞错（P1）。
• 修复 prompt 注入吞错（P0）。

前端修复

• 修复点击设置后白屏：React hooks 顺序违规（useEffect 放在条件 return 之后导致 #310 错误）。
• 修复 useEffect 依赖项缺失（P0）。
• 修复子智能体视图间歇性丢消息：同步前置 subAgentViewRef / subAgentStackRef。
• 修复子智能体工具消息去重：改为按 id + type 去重，修复工具状态卡在执行中。
• 修复高亮消息时退出子智能体视图的问题。
• 修复专家发现与前端选择多项问题。
• 兼容 base_url 末尾斜杠，避免拼接产生双斜杠导致 404。
• TodoWriteTool merge 模式内存为空时从 DB 回填，防止丢失旧项。

依赖与构建

• 升级 wechatbot 的 reqwest 至 0.13，消除版本冲突。
• 将 rmcp 依赖从 git branch 迁移到 crates.io 版本。
• 提交 Cargo.lock 以保证二进制构建可复现（binary 项目约定）。

重构

前端架构

• 重写 useChat 为组合根，消除上帝 Hook。
• 抽取 useChat 的领域子 hook 与 messageMappers。
• 建立前端 API 客户端层，消除硬编码路径与重复 fetch。
• 拆分 ConfigPage.tsx 与 storage/mod.rs（P2）。
• 清理 P0/P1 技术债（any 类型、React key、dead_code、硬编码 URL）。

后端架构

• 重构 AgentLoop 中的消息处理逻辑，简化工具结果处理和 LLM 请求构建。
• 重构工具提示提供者，整合工具使用说明；删除冗余的 TodoPromptProvider。
• get_current / save_topic 直读 DB 加载消息，移除 SessionManager 依赖。
• 改用 gray_matter 解析 Markdown frontmatter，增加相应日志。
• 优化工具使用说明，简化记忆检索和写入规则。
• 移除未使用的 cli_sessions 变量，优化 ws.rs 中的代码。

内部改进

• 增加整理意识，确保同类工作输出到同一文件夹。
• 修复 MCP 日志输出。

---

0.1.2 - 2026-07-28

新增

• WebSocket 连接泄漏修复，使用 CancellationToken 实现优雅重启。
• 交互式 Shell 会话管理。
• 数据库连接池优化会话存储，新增错误处理。
• 平台特定的进程输入等待检查，增强 Bash 工具的用户授权检测。
• 前端静态文件嵌入二进制。
• React Web UI 前端界面。