feat: 更新 README.md，添加消息流转图和项目架构图，优化模块描述和配置项说明
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
parent
04fc2c0710
commit
3111abf4db
131
README.md
131
README.md
@ -35,18 +35,113 @@ PicoBot 的设计目标不是“只会聊天”的单进程 Bot，而是一个
|
||||
5. 生成的 user / assistant / tool / system 消息按真实顺序写入 SQLite
|
||||
6. OutboundDispatcher 将结果投递到目标通道
|
||||
|
||||
### 2.1 消息流转图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant U as User / External Chat
|
||||
participant C as Channel
|
||||
participant B as MessageBus
|
||||
participant P as InboundProcessor
|
||||
participant SM as SessionManager
|
||||
participant SES as Session
|
||||
participant AES as AgentExecutionService
|
||||
participant AL as AgentLoop
|
||||
participant T as ToolRegistry
|
||||
participant DB as SQLite
|
||||
participant OD as OutboundDispatcher
|
||||
|
||||
U->>C: 输入消息
|
||||
C->>B: publish_inbound
|
||||
B->>P: consume_inbound
|
||||
P->>SM: handle_message(channel, sender, chat, content)
|
||||
SM->>SES: active_session(channel)
|
||||
AES->>SES: ensure_persistent_session / ensure_chat_loaded
|
||||
AES->>DB: 追加 user / system 消息
|
||||
AES->>AL: process(history)
|
||||
AL->>T: 调用工具
|
||||
T-->>AL: 返回 tool result
|
||||
AL-->>AES: emitted_messages
|
||||
AES->>DB: 按真实顺序持久化 assistant / tool / assistant
|
||||
AES->>SES: 安排后台历史压缩
|
||||
AES-->>SM: outbound messages
|
||||
SM-->>P: outbound messages
|
||||
P->>B: publish_outbound
|
||||
B->>OD: consume_outbound
|
||||
OD->>C: dispatch
|
||||
C-->>U: 最终回复
|
||||
```
|
||||
|
||||
### 2.2 项目架构图
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Edge[接入层]
|
||||
CLI[CLI Client / WebSocket]
|
||||
FEI[Feishu Channel]
|
||||
HTTP[HTTP Health / WS Gateway]
|
||||
end
|
||||
|
||||
subgraph Gateway[网关与运行时编排]
|
||||
CM[ChannelManager]
|
||||
BUS[MessageBus]
|
||||
IP[InboundProcessor]
|
||||
OD[OutboundDispatcher]
|
||||
SSM[SessionManager]
|
||||
SVC[SessionLifecycle / Message / ScheduledTask Services]
|
||||
AES[AgentExecutionService]
|
||||
end
|
||||
|
||||
subgraph Agent[Agent 执行层]
|
||||
LOOP[AgentLoop]
|
||||
COMP[ContextCompressor]
|
||||
SK[SkillRuntime]
|
||||
TOOLS[ToolRegistry]
|
||||
PROV[LLM Providers]
|
||||
end
|
||||
|
||||
subgraph Runtime[持久化与后台能力]
|
||||
STORE[SessionStore / SQLite]
|
||||
SCH[Scheduler]
|
||||
MEM[Memory Maintenance]
|
||||
end
|
||||
|
||||
CLI --> HTTP
|
||||
FEI --> CM
|
||||
HTTP --> CM
|
||||
CM --> BUS
|
||||
BUS --> IP
|
||||
IP --> SSM
|
||||
SSM --> SVC
|
||||
SVC --> AES
|
||||
AES --> LOOP
|
||||
LOOP --> TOOLS
|
||||
LOOP --> SK
|
||||
LOOP --> PROV
|
||||
AES --> COMP
|
||||
SSM --> STORE
|
||||
AES --> STORE
|
||||
SCH --> BUS
|
||||
SCH --> SSM
|
||||
MEM --> STORE
|
||||
BUS --> OD
|
||||
OD --> CM
|
||||
```
|
||||
|
||||
主要模块如下：
|
||||
|
||||
- src/gateway：网关入口、HTTP 健康检查、WebSocket 控制面、Session 池、CLI 会话服务、OutboundDispatcher 与 Agent 执行编排
|
||||
- src/gateway：网关生命周期、InboundProcessor、OutboundDispatcher、SessionManager，以及消息执行、调度任务执行、Prompt 注入、历史压缩和记忆维护编排
|
||||
- src/bus：消息总线队列与消息结构定义，不包含渠道投递逻辑
|
||||
- src/agent：AgentLoop 与上下文压缩器
|
||||
- src/providers：不同 LLM Provider 的统一抽象，当前支持 openai 和 anthropic
|
||||
- src/tools：内置工具集合
|
||||
- src/tools：内置工具集合与 ToolRegistry
|
||||
- src/storage：SQLite 持久化实现
|
||||
- src/channels：渠道适配层，当前已有 CLI 与飞书通道
|
||||
- src/scheduler：数据库驱动的计划任务调度器
|
||||
- src/skills：技能发现、加载与运行时管理
|
||||
- src/client / src/cli：本地 CLI 客户端和交互命令
|
||||
- src/client / src/cli：本地 CLI 客户端、输入命令解析与会话交互
|
||||
- src/protocol：WebSocket 入站 / 出站协议结构
|
||||
|
||||
## 3. 消息机制
|
||||
|
||||
@ -142,7 +237,7 @@ PicoBot 会在 ~/.picobot/agent/AGENT.md 维护一份持久化 Agent 画像文
|
||||
带有 agent_prompt 和 scheduled_system_prompt 标记的 system 消息会被原样保留，避免丢失 Agent 基本设定和调度任务附加约束。
|
||||
6. 除这些必须保留的 system 消息外，分界点之前的其余消息会被整理成一段待摘要 transcript。
|
||||
transcript 会保留角色信息；tool 消息还会带上工具名，方便摘要时保留关键操作和结果。
|
||||
7. 如果 transcript 本身已经过长，会先按 context_summary_max_chars 截断，再交给模型总结。
|
||||
7. 如果 transcript 本身已经过长，会先按当前模型上下文窗口推导出的摘要字符预算截断，再交给模型总结。
|
||||
8. 摘要调用和主对话使用同一个 provider，提示词明确要求保留：
|
||||
用户请求、关键标识符、文件路径、URL、工具调用、命令、结果、错误、决策、偏好和当前任务状态。
|
||||
如果摘要调用失败，会退化为直接截断 transcript，而不会中断主流程。
|
||||
@ -270,7 +365,7 @@ PicoBot 不只是“把记忆存进去”，还内置了记忆整理逻辑。
|
||||
Scheduler 默认内置一个任务：
|
||||
|
||||
- builtin.memory_maintenance_daily
|
||||
- 每天本地时间 03:00 运行
|
||||
- 默认按本地时区每 4 小时运行一次（cron: 0 */4 * * *）
|
||||
|
||||
这个任务以 internal_event 的方式触发 memory_maintenance 事件。触发后，系统会遍历所有已有用户 scope，逐个执行记忆维护，并在全部处理完成后统一更新 AGENT.md 中的“用户记忆摘要”托管区块。
|
||||
|
||||
@ -280,8 +375,12 @@ PicoBot 支持基于文件系统的技能系统，用来给 Agent 注入某一
|
||||
|
||||
### 7.1 技能发现位置
|
||||
|
||||
- 项目级技能：.picobot/skills/*/SKILL.md
|
||||
当前技能运行时按从低到高优先级合并多个来源，后加载来源可覆盖同名技能：
|
||||
|
||||
- 用户级技能：~/.picobot/skills/*/SKILL.md
|
||||
- 用户 Agent 级技能：~/.picobot/agent/skills/*/SKILL.md
|
||||
- 项目级技能：.picobot/skills/*/SKILL.md
|
||||
- 项目 Agent 级技能：.picobot/agent/skills/*/SKILL.md
|
||||
|
||||
### 7.2 最小 SKILL.md 格式
|
||||
|
||||
@ -328,7 +427,7 @@ skills 配置示例：
|
||||
{
|
||||
"skills": {
|
||||
"enabled": true,
|
||||
"sources": ["project", "user"],
|
||||
"sources": ["user", "user_agent", "project", "project_agent"],
|
||||
"max_index_chars": 4000,
|
||||
"max_listed_skills": 32
|
||||
}
|
||||
@ -340,12 +439,14 @@ skills 配置示例：
|
||||
PicoBot 的 Agent 是围绕工具调用构建的。当前默认注册的工具包括：
|
||||
|
||||
- calculator：简单数学计算
|
||||
- time：获取当前时间与时区上下文
|
||||
- file_read：读取文件
|
||||
- file_write：写文件
|
||||
- file_edit：编辑文件
|
||||
- memory_search：读取长期记忆
|
||||
- memory_manage：写入 / 更新 / 删除长期记忆
|
||||
- scheduler_manage：管理调度任务
|
||||
- skill_activate：读取并激活某个技能内容
|
||||
- skill_list：列出技能
|
||||
- skill_manage：管理技能
|
||||
- bash：执行 shell 命令
|
||||
@ -357,6 +458,7 @@ PicoBot 的 Agent 是围绕工具调用构建的。当前默认注册的工具
|
||||
- 文件工具适合做代码库和文档操作
|
||||
- 记忆工具适合维持长期用户画像
|
||||
- scheduler_manage 允许 Agent 自主创建后续计划任务
|
||||
- skill_activate 负责把具体技能正文注入当前任务上下文
|
||||
- bash / http_request / web_fetch 让 Agent 具备更强的外部交互能力
|
||||
|
||||
## 9. 调度器机制
|
||||
@ -406,6 +508,8 @@ silent_agent_task 和 agent_task 使用同一套 Agent 执行能力，但路由
|
||||
|
||||
任务定义和状态都会写进 SQLite，所以重启后仍可恢复。
|
||||
|
||||
当前内置任务只默认写入记忆维护任务；`session_cleanup` 作为 `internal_event` 仍然受支持，但如果需要启用，需在配置中显式声明。
|
||||
|
||||
调度器配置示例：
|
||||
|
||||
```json
|
||||
@ -543,7 +647,8 @@ CLI 中已实现的交互命令包括：
|
||||
"type": "openai",
|
||||
"base_url": "<OPENAI_BASE_URL>",
|
||||
"api_key": "<OPENAI_API_KEY>",
|
||||
"extra_headers": {}
|
||||
"extra_headers": {},
|
||||
"llm_timeout_secs": 120
|
||||
}
|
||||
},
|
||||
"models": {
|
||||
@ -557,19 +662,21 @@ CLI 中已实现的交互命令包括：
|
||||
"default": {
|
||||
"provider": "default",
|
||||
"model": "default",
|
||||
"max_tool_iterations": 100,
|
||||
"tool_result_max_chars": 20000,
|
||||
"context_summary_max_chars": 20000,
|
||||
"context_tool_result_trim_chars": 2000
|
||||
}
|
||||
},
|
||||
"gateway": {
|
||||
"host": "0.0.0.0",
|
||||
"port": 19876,
|
||||
"show_tool_results": false,
|
||||
"agent_prompt_reinject_every": 100
|
||||
},
|
||||
"scheduler": {
|
||||
"enabled": true,
|
||||
"tick_resolution_ms": 1000,
|
||||
"worker_queue_capacity": 128,
|
||||
"misfire_policy": "skip",
|
||||
"jobs": []
|
||||
}
|
||||
@ -579,10 +686,10 @@ CLI 中已实现的交互命令包括：
|
||||
常用配置项：
|
||||
|
||||
- providers：Provider 连接信息
|
||||
- models：模型参数
|
||||
- agents：Agent 级别的工具轮次、token 上限和上下文裁剪参数
|
||||
- models：模型参数，包括上下文窗口估算所用的 context_window_tokens
|
||||
- agents：Agent 级别的工具轮次、工具结果裁剪与上下文裁剪参数
|
||||
- gateway：监听地址、端口、工具结果展示、会话 TTL、Prompt 重注入策略
|
||||
- scheduler：调度器开关和任务列表
|
||||
- scheduler：调度器开关、worker 队列容量、误触发策略和任务列表
|
||||
- channels：飞书等通道配置
|
||||
- skills：技能来源与索引限制
|
||||
- time.timezone：时区，默认应使用 IANA 时区名，例如 Asia/Shanghai
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user