Skip to content

README_CN.md

Latest commit

 

History

History
1146 lines (870 loc) · 37.1 KB

README_CN.md

File metadata and controls

1146 lines (870 loc) · 37.1 KB

FinchBot (雀翎) — 轻量灵活，自主扩展的 AI Agent 框架

FinchBot Logo

基于 LangChain v1.2 与 LangGraph v1.0 构建
具备持久记忆、动态提示词、自主能力扩展

🌐 Language: English | 中文

Gitee Recommended AtomGit

CSDN Blog GitHub Gitee GitCode

Python Ruff Basedpyright Docker License

FinchBot (雀翎) 是一个赋予智能体真正自主性的 AI Agent 框架，基于 LangChain v1.2 和 LangGraph v1.0 构建。全异步架构设计，让智能体具备自主决策、自主扩展、自主进化的能力：

  1. 能力自扩展 — Agent 遇到能力边界时，可使用内置工具配置 MCP、创建技能
  2. 任务自调度 — Agent 可自主设定后台任务、定时执行，不阻塞对话
  3. 记忆自管理 — Agent 可自主记忆、检索、遗忘，Agentic RAG + 加权 RRF 混合检索，智能召回
  4. 行为自进化 — Agent 和用户都可自主修改提示词，持续迭代优化行为

能力边界问题

用户请求 传统 AI 回应 FinchBot 回应
"分析这个数据库" "我没有数据库工具" 自主配置 SQLite MCP，然后分析
"学会做某事" "等开发者添加功能" 通过 skill-creator 自主创建技能
"帮我监控 24 小时" "我只能在你问的时候响应" 创建定时任务，自主监控
"处理这个大文件" 阻塞对话，用户等待 后台执行，用户继续
"记住我的偏好" "下次对话就忘了" 持久化记忆，Agentic RAG + 加权 RRF 混合检索
"调整你的行为" "提示词是固定的" 动态修改提示词，热加载

系统架构

核心理念：FinchBot 智能体不只是响应 — 它们自主执行、自主规划、自主扩展。

自主性金字塔

flowchart TB
    subgraph L4["扩展层 - 自主扩展能力"]
        E1["MCP 自动配置"] ~~~ E2["技能创建"] ~~~ E3["动态加载"]
    end

    subgraph L3["规划层 - 自主创建计划"]
        P1["定时任务"] ~~~ P2["心跳监控"] ~~~ P3["自动触发"]
    end

    subgraph L2["执行层 - 自主执行任务"]
        X1["后台任务"] ~~~ X2["异步处理"] ~~~ X3["非阻塞"]
    end

    subgraph L1["响应层 - 响应用户请求"]
        R1["对话系统"] ~~~ R2["工具调用"] ~~~ R3["上下文记忆"]
    end

    L4 --> L3 --> L2 --> L1

    style L1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    style L2 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    style L3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    style L4 fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17
Loading
层级 能力 实现方式 用户价值
响应层 响应用户请求 对话系统 + 工具调用 基础交互
执行层 自主执行任务 后台任务系统 对话不阻塞
规划层 自主创建计划 定时任务 + 心跳服务 自动化执行
扩展层 自主扩展能力 MCP 配置 + 技能创建 无限扩展

整体架构

flowchart TB
    classDef input fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17;
    classDef core fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef task fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;
    classDef infra fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef service fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#b71c1c;

    subgraph Input [输入层]
        direction LR
        CLI[CLI 界面<br/>Rich 美化]:::input
        LB[LangBot<br/>12+ 平台]:::input
        Webhook[Webhook<br/>FastAPI]:::input
    end

    subgraph Core [核心层 - Agent 决策引擎]
        direction TB
        Agent[LangGraph Agent<br/>状态管理 · 循环控制]:::core
        subgraph CoreModules [核心组件]
            direction LR
            Context[ContextBuilder<br/>上下文构建]:::core
            Streaming[ProgressReporter<br/>流式输出]:::core
        end
    end

    subgraph Capabilities [能力层 - 三层扩展]
        direction LR
        BuiltIn[内置工具<br/>19 个开箱即用]:::core
        MCP[MCP 扩展<br/>动态配置]:::core
        Skills[技能系统<br/>自主创建]:::core
    end

    subgraph Task [任务层 - 三层调度]
        direction LR
        BG[后台任务<br/>异步执行]:::task
        Cron[定时任务<br/>at/every/cron]:::task
        Heart[心跳监控<br/>自主唤醒]:::task
    end

    subgraph Service [服务层 - 统一管理]
        SM[ServiceManager<br/>协调后台服务]:::service
    end

    subgraph Memory [记忆层 - 双层存储]
        direction LR
        SQLite[(SQLite<br/>结构化存储)]:::infra
        Vector[(VectorStore<br/>向量检索)]:::infra
    end

    subgraph LLM [模型层 - 多提供商]
        direction LR
        OpenAI[OpenAI<br/>GPT-4o]:::infra
        Anthropic[Anthropic<br/>Claude]:::infra
        DeepSeek[DeepSeek<br/>国产]:::infra
    end

    CLI --> Agent
    LB <--> Webhook
    Webhook --> Agent

    Agent --> Context
    Agent --> Streaming
    Agent --> Capabilities
    Agent --> Task
    Agent <--> Memory
    Agent --> LLM

    Task --> Service
    Service --> SM

    Context --> Memory
    Memory --> SQLite
    Memory --> Vector
Loading

数据流

sequenceDiagram
    autonumber
    participant U as 用户
    participant C as 通道
    participant B as MessageBus
    participant F as AgentFactory
    participant A as Agent
    participant M as MemoryManager
    participant T as 工具
    participant L as LLM

    U->>C: 发送消息
    C->>B: InboundMessage
    B->>F: 获取/创建 Agent
    F->>A: 返回编译后的 Agent
    
    Note over A: 构建上下文
    A->>M: 召回相关记忆
    M-->>A: 返回上下文
    
    A->>L: 发送请求
    L-->>A: 流式响应
    
    alt 需要工具调用
        A->>T: 执行工具
        T-->>A: 返回结果
        A->>L: 继续处理
        L-->>A: 最终响应
    end
    
    A->>M: 存储新记忆
    A->>B: OutboundMessage
    B->>C: 路由到通道
    C->>U: 显示响应
Loading

安全机制

智能体自主 ≠ 智能体乱来。 FinchBot 实现了多重安全机制：

安全机制 状态 作用
路径限制 ✅ 已实现 文件操作限定在 workspace 目录内
Shell 命令黑名单 ✅ 已实现 阻止 rm -rf、format、shutdown 等危险命令
工具注册机制 ✅ 已实现 只有注册的工具可被调用

理念：给智能体解决问题的自由，但在明确的边界内。

核心组件

1. 能力自扩展：内置工具 + MCP 配置 + 技能创建

FinchBot 提供三层能力扩展机制，让智能体遇到能力边界时可以自主扩展。

三层扩展机制

flowchart LR
    classDef layer1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef layer2 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef layer3 fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17;

    L1[第一层<br/>内置工具<br/>开箱即用]:::layer1 --> L2[第二层<br/>MCP 配置<br/>Agent 自主配置]:::layer2 --> L3[第三层<br/>技能创建<br/>Agent 自主创建]:::layer3
Loading
层级 方式 自主性 说明
第一层 内置工具 开箱即用 19 个内置工具，无需配置即可使用
第二层 MCP 配置 Agent 自主配置 通过 configure_mcp 动态添加外部能力
第三层 技能创建 Agent 自主创建 通过 skill-creator 创建新技能

内置工具

类别 工具 功能
文件操作 read_file 读取本地文件
write_file 写入本地文件
edit_file 编辑文件内容
list_dir 列出目录内容
网络能力 web_search 联网搜索 (Tavily/Brave/DDG)
web_extract 网页内容提取
记忆管理 remember 主动存储记忆
recall 检索记忆
forget 删除/归档记忆
系统控制 exec 安全执行 Shell 命令
配置管理 configure_mcp 动态配置 MCP 服务器
refresh_capabilities 刷新能力描述文件
后台任务 start_background_task 启动后台任务
check_task_status 检查任务状态
get_task_result 获取任务结果
cancel_task 取消任务
定时任务 create_cron 创建定时任务
list_crons 列出所有的定时任务
delete_cron 删除定时任务
网页搜索

web_search 工具采用三引擎降级设计，确保始终可用：

flowchart TD
    classDef check fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;
    classDef engine fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef fallback fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;

    Start[网页搜索请求]:::check
    
    Check1{TAVILY_API_KEY<br/>已设置?}:::check
    Tavily[Tavily<br/>质量最佳<br/>AI 优化]:::engine
    
    Check2{BRAVE_API_KEY<br/>已设置?}:::check
    Brave[Brave Search<br/>隐私友好<br/>免费额度大]:::engine
        
    DDG[DuckDuckGo<br/>零配置<br/>始终可用]:::fallback

    Start --> Check1
    Check1 -->|是| Tavily
    Check1 -->|否| Check2
    Check2 -->|是| Brave
    Check2 -->|否| DDG
Loading
优先级 引擎 API Key 特点
1 Tavily 需要 质量最佳，专为 AI 优化，深度搜索
2 Brave Search 需要 免费额度大，隐私友好
3 DuckDuckGo 无需 始终可用，零配置
会话管理

session_title 工具让会话命名变得智能：

操作方式 说明 示例
自动生成 对话 2-3 轮后，AI 自动根据内容生成标题 "Python 异步编程讨论"
Agent 修改 告诉 Agent "把会话标题改成 XXX" Agent 调用工具自动修改
手动重命名 在会话管理器中按 r 键重命名 用户手动输入新标题

MCP 配置

智能体可通过 configure_mcp 工具自主管理 MCP 服务器：

操作 说明
add 添加新 MCP 服务器
update 更新现有服务器配置
remove 删除 MCP 服务器
enable 启用已禁用的 MCP 服务器
disable 暂时禁用 MCP 服务器
list 列出所有已配置的服务器

动态能力更新：

flowchart LR
    classDef config fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef system fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef prompt fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;

    MCP[MCP 配置<br/>configure_mcp]:::config --> Refresh[refresh_capabilities]:::system --> Builder[CapabilitiesBuilder<br/>重新生成]:::system --> Write[CAPABILITIES.md]:::prompt --> Load[下次对话<br/>自动加载]:::prompt
Loading

技能创建

FinchBot 内置 skill-creator 技能，智能体可自主创建新技能：

用户: 帮我创建一个翻译技能，可以把中文翻译成英文

Agent: 好的，我来为你创建翻译技能...
       [调用 skill-creator 技能]
       ✅ 已创建 skills/translator/SKILL.md
       现在你可以直接使用翻译功能了！

无需手动创建文件、无需编写代码，一句话就能扩展 Agent 能力！

技能文件结构

skills/
├── skill-creator/        # 技能创建器（内置）- 开箱即用的核心
│   └── SKILL.md
├── summarize/            # 智能总结（内置）
│   └── SKILL.md
├── weather/              # 天气查询（内置）
│   └── SKILL.md
└── my-custom-skill/      # Agent 自动创建或用户自定义
    └── SKILL.md

设计亮点

特性 说明
Agent 自动创建 告诉 Agent 需求，自动生成技能文件
双层技能源 工作区技能优先，内置技能兜底
依赖检查 自动检查 CLI 工具和环境变量
缓存失效检测 基于文件修改时间，智能缓存
渐进式加载 常驻技能优先，按需加载其他

2. 任务自调度：后台任务 + 定时任务 + 心跳服务

FinchBot 实现了三层任务调度机制，让智能体能够自主执行、规划和监控任务。

三层调度机制

flowchart TB
    classDef layer1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef layer2 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef layer3 fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17;

    subgraph L3["监控层 - 心跳服务"]
        H1[自主唤醒] ~~~ H2[定期检查] ~~~ H3[主动通知]
    end

    subgraph L2["规划层 - 定时任务"]
        C1[Cron 调度] ~~~ C2[周期执行] ~~~ C3[自动重试]
    end

    subgraph L1["执行层 - 后台任务"]
        B1[异步执行] ~~~ B2[非阻塞] ~~~ B3[结果获取]
    end

    L3 --> L2 --> L1

    style L1 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    style L2 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    style L3 fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#f57f17
Loading
层级 功能 特点 使用场景
执行层 后台任务 异步执行，不阻塞对话 长时间运行的任务
规划层 定时任务 周期执行，自动化运行 定期提醒、定时报告
监控层 心跳服务 主动检查，自主唤醒 条件监控、状态追踪

后台任务

FinchBot 实现了四工具模式用于异步任务执行：

工具 功能 智能体自主性
start_background_task 启动后台任务 智能体自主判断是否需要后台执行
check_task_status 检查任务状态 智能体自主决定何时检查
get_task_result 获取任务结果 智能体自主决定何时获取结果
cancel_task 取消任务 智能体自主决定是否取消 
sequenceDiagram
    participant U as 用户
    participant A as 智能体
    participant SM as SubagentManager
    participant SA as 子智能体<br/>(独立循环)
    participant JM as JobManager

    U->>A: 执行长任务
    A->>SM: start_background_task
    SM->>JM: 创建任务 (pending)
    SM->>SA: 创建独立 Agent 循环
    JM-->>A: 返回 job_id
    A-->>U: 任务已启动 (ID: xxx)
    
    Note over U,A: 用户继续对话...
    
    U->>A: 其他问题
    A-->>U: 正常回复
    
    U->>A: 任务进度？
    A->>SM: check_task_status
    SM->>JM: 查询状态
    JM-->>SM: running (迭代 5/15)
    A-->>U: 仍在执行...
    
    loop 最多 15 次迭代
        SA->>SA: 工具调用
        SA->>SA: LLM 推理
    end
    
    SA-->>SM: 任务完成
    SM->>SM: on_notify 回调
    SM->>A: 注入结果到会话
    A-->>U: 后台任务完成通知
Loading

定时任务

FinchBot 的定时任务系统让智能体能够自主创建和管理周期性任务：

flowchart TB
    classDef cli fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#b71c1c;
    classDef service fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef tool fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef mode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;

    subgraph Service [服务层]
        CronService[CronService<br/>croniter 调度引擎]:::service
        TZ[IANA 时区<br/>Asia/Shanghai 等]:::service
    end

    subgraph Modes [三种调度模式]
        AtMode["at 模式<br/>一次性任务<br/>执行后删除"]:::mode
        EveryMode["every 模式<br/>间隔任务<br/>每 N 秒执行"]:::mode
        CronMode["cron 模式<br/>Cron 表达式<br/>精确时间调度"]:::mode
    end

    subgraph Tools [工具层]
        Create[create_cron]:::tool
        List[list_crons]:::tool
        Delete[delete_cron]:::tool
        Toggle[toggle_cron]:::tool
        RunNow[run_cron_now]:::tool
    end

    subgraph Callbacks [回调机制]
        OnDeliver[on_deliver<br/>消息传递回调]:::service
    end

    CronService --> TZ
    CronService --> Modes
    Modes --> Storage[(cron_jobs.json)]
    
    Agent[智能体] --> Tools
    Tools --> Storage
    
    CronService --> OnDeliver
    OnDeliver --> Agent
Loading

核心特性：

特性 说明
三种调度模式 at（一次性）、every（间隔）、cron（Cron 表达式）
IANA 时区支持 指定时区如 Asia/Shanghai、America/New_York
Cron 表达式 支持标准 Cron 语法，灵活配置执行时间
持久化存储 任务配置保存在 JSON，重启后自动恢复
自动重试 任务失败时自动重试，确保可靠性
状态追踪 记录每次执行结果，便于审计和调试
消息传递 on_deliver 回调将结果注入会话

三种调度模式：

模式 参数 说明 示例
at at="2025-01-15T10:30:00" 一次性任务，执行后删除 会议提醒
every every_seconds=3600 间隔任务，每 N 秒执行 每小时健康检查
cron cron_expr="0 9 * * *" Cron 表达式，精确调度 每天 9 点早报

常用 Cron 表达式：

表达式 说明
0 9 * * * 每天上午 9:00
0 */2 * * * 每 2 小时
30 18 * * 1-5 工作日下午 6:30
0 0 1 * * 每月 1 日午夜
0 0 * * 0 每周日午夜

使用示例：

用户: 每天早上 9 点提醒我查看邮件

Agent: 好的，我来创建一个定时任务...
       [调用 create_cron 工具]
       ✅ 已创建定时任务
       - 触发时间: 每天 09:00
       - 任务内容: 提醒查看邮件
       - 下次执行: 明天 09:00

心跳服务

心跳服务让 Agent 能够定期"醒来"检查是否有待处理任务，实现真正的自主运行。

flowchart LR
    classDef trigger fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef decision fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;
    classDef action fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;

    Timer[定时器<br/>默认 30 分钟]:::trigger --> |唤醒| Check[检查 HEARTBEAT.md]:::decision
    Check --> |有任务| LLM[LLM 决策]:::decision
    LLM --> |run| Execute[执行任务]:::action
    LLM --> |skip| Wait[继续等待]:::trigger
Loading

核心特性：

特性 说明
自主唤醒 无需用户触发，Agent 定期主动检查
LLM 决策 通过 LLM 智能判断是否需要执行任务
灵活配置 可自定义检查间隔（默认 30 分钟）
会话绑定 随 chat 会话启动和停止

工作流程：

  1. Agent 在对话时自动启动心跳服务
  2. 每隔指定时间检查 HEARTBEAT.md 文件
  3. 如果有内容，通过 LLM 决定是否执行
  4. LLM 返回 run 则执行任务，返回 skip 则等待下次检查

使用示例：

用户: 帮我监控股票价格，跌破 100 元时通知我

Agent: 好的，我会在 HEARTBEAT.md 中记录这个任务...
       心跳服务会定期检查股票价格
       当条件满足时会主动通知你

3. 记忆自管理：Agentic RAG + 加权 RRF 混合检索

FinchBot 实现了先进的双层记忆架构，让智能体能够自主记忆、检索和遗忘。

Agentic RAG 优势

对比维度 传统 RAG Agentic RAG (FinchBot)
检索触发 固定流程 Agent 自主决策
检索策略 单一向量检索 混合检索 + 权重动态调整
记忆管理 被动存储 主动 remember/recall/forget
分类能力 无 自动分类 + 重要性评分
更新机制 全量重建 增量同步

记忆工具

智能体可通过三个核心工具自主管理记忆：

工具 功能 使用场景
remember 主动存储记忆 用户偏好、重要信息、上下文
recall 检索记忆 查找历史信息、回忆上下文
forget 删除/归档记忆 过期信息、错误记忆、隐私清理

使用示例：

用户: 记住我喜欢用中文交流

Agent: 好的，我会记住这个偏好。
       [调用 remember 工具]
       ✅ 已存储：用户偏好 - 语言：中文

用户: 我之前说过什么语言偏好？

Agent: [调用 recall 工具]
       你之前告诉我喜欢用中文交流。

双层存储架构

flowchart TB
    classDef businessLayer fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef serviceLayer fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;
    classDef storageLayer fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;

    subgraph Business [业务层]
        MM[MemoryManager<br/>remember/recall/forget]:::businessLayer
    end

    subgraph Services [服务层]
        RS[RetrievalService<br/>混合检索 + RRF 融合]:::serviceLayer
        CS[ClassificationService<br/>自动分类]:::serviceLayer
        IS[ImportanceScorer<br/>重要性评分]:::serviceLayer
        ES[EmbeddingService<br/>FastEmbed 本地嵌入]:::serviceLayer
    end

    subgraph Storage [双层存储]
        direction TB
        subgraph Layer1 [第一层：结构化存储]
            SQLite[(SQLiteStore<br/>真相源 · 精确查询)]:::storageLayer
        end
        subgraph Layer2 [第二层：向量存储]
            Vector[(VectorStore<br/>ChromaDB · 语义检索)]:::storageLayer
        end
        DS[DataSyncManager<br/>增量同步]:::storageLayer
    end

    MM --> RS
    MM --> CS
    MM --> IS
    
    RS --> SQLite
    RS --> Vector
    RS --> |RRF 融合| Result[检索结果]
    
    CS --> SQLite
    IS --> SQLite
    ES --> Vector
    
    SQLite <--> DS
    DS <--> Vector
Loading

混合检索策略

FinchBot 采用加权 RRF (Weighted Reciprocal Rank Fusion) 策略：

优势 说明
无需归一化 仅基于排名位置计算，无需了解向量或 BM25 分数分布
抗异常值 对单个检索器的异常结果不敏感，更稳定
共识优先 奖励多个检索器都认可的文档，而非单一异常
权重可控 可根据查询类型动态调整关键词/语义检索权重

查询类型自适应权重：

class QueryType(StrEnum):
    """查询类型，决定检索权重（关键词权重 / 语义权重）"""
    KEYWORD_ONLY = "keyword_only"      # 纯关键词 (1.0/0.0)
    SEMANTIC_ONLY = "semantic_only"    # 纯语义 (0.0/1.0)
    FACTUAL = "factual"                # 事实型 (0.8/0.2)
    CONCEPTUAL = "conceptual"          # 概念型 (0.2/0.8)
    COMPLEX = "complex"                # 复杂型 (0.5/0.5)
    AMBIGUOUS = "ambiguous"            # 歧义型 (0.3/0.7)

RRF 公式：

RRF(d) = Σ (weight_r / (k + rank_r(d)))

其中：
- d 是文档
- k 是平滑常数（通常为 60）
- rank_r(d) 是文档 d 在检索器 r 中的排名
- weight_r 是检索器 r 的权重

设计亮点

特性 说明
自主决策 Agent 根据查询内容选择合适的检索权重
动态调整 事实型查询偏向关键词，概念型查询偏向语义
迭代验证 如果结果不满意，可以调整策略重试
可解释性 每个检索决策都有明确的权重依据

4. 行为自进化：动态提示词系统

FinchBot 的提示词系统采用文件系统 + 模块化组装的设计，让智能体和用户都能自主修改行为。

动态提示词优势

传统方式 FinchBot 方式
提示词硬编码在代码中 提示词存储在文件系统中
修改需要重新部署 修改后下次对话自动生效
用户无法自定义 用户可通过编辑文件自定义
Agent 无法调整自身行为 Agent 可自主优化提示词

Bootstrap 文件系统

~/.finchbot/
├── config.json              # 主配置文件
└── workspace/
    ├── bootstrap/           # Bootstrap 文件目录
    │   ├── SYSTEM.md        # 角色设定（身份、职责、约束）
    │   ├── MEMORY_GUIDE.md  # 记忆使用指南（何时存储/检索）
    │   ├── SOUL.md          # 灵魂设定（性格、语气、风格）
    │   └── AGENT_CONFIG.md  # Agent 配置（模型参数、行为选项）
    ├── config/              # 配置目录
    │   └── mcp.json         # MCP 服务器配置
    ├── generated/           # 自动生成文件
    │   ├── TOOLS.md         # 工具文档（自动生成）
    │   └── CAPABILITIES.md  # 能力信息（自动生成）
    ├── skills/              # 自定义技能
    ├── memory/              # 记忆存储
    └── sessions/            # 会话数据

Bootstrap 文件说明：

文件 作用 示例内容
SYSTEM.md 定义 Agent 的身份和职责 "你是一个智能助手，擅长..."
MEMORY_GUIDE.md 指导 Agent 如何使用记忆 "用户偏好应存储在长期记忆中..."
SOUL.md 定义 Agent 的性格特征 "你的回复应该简洁、友好..."
AGENT_CONFIG.md Agent 行为配置 默认语言、响应风格等

提示词构建流程

flowchart TD
    classDef startEnd fill:#ffebee,stroke:#c62828,stroke-width:2px,color:#b71c1c;
    classDef process fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef file fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;
    classDef output fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;

    A([Agent 启动]):::startEnd --> B[ContextBuilder<br/>上下文构建器]:::process
    
    B --> C[加载 Bootstrap 文件]:::file
    C --> D[SYSTEM.md]:::file
    C --> E[MEMORY_GUIDE.md]:::file
    C --> F[SOUL.md]:::file
    C --> G[AGENT_CONFIG.md]:::file

    B --> H[加载常驻技能]:::process
    H --> I[SkillsLoader<br/>技能加载器]:::process
    
    B --> J[生成能力信息]:::process
    J --> K[CapabilitiesBuilder<br/>能力构建器]:::process
    K --> L[CAPABILITIES.md]:::file

    D & E & F & G --> M[组装提示词]:::process
    I --> M
    L --> M
    
    M --> N[注入运行时信息<br/>时间/平台/Python版本]:::process
    N --> O[完整系统提示]:::output

    O --> P([发送给 LLM]):::startEnd
Loading

能力信息自动生成

CapabilitiesBuilder 会自动生成能力说明，让 Agent "知道"自己的能力：

flowchart LR
    classDef config fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef build fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;
    classDef output fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;

    MCP[MCP 配置]:::config --> Builder[CapabilitiesBuilder]:::build
    Tools[工具列表]:::config --> Builder
    Channels[通道配置]:::config --> Builder

    Builder --> Cap[CAPABILITIES.md<br/>能力说明]:::output
    Builder --> Guide[扩展指南<br/>如何添加 MCP/技能]:::output
Loading

生成的 CAPABILITIES.md 包含：

  1. MCP 服务器状态 — 已配置的服务器列表、启用/禁用状态
  2. MCP 工具列表 — 按服务器分组的可用工具
  3. 通道配置 — LangBot 连接状态
  4. 扩展指南 — 如何添加新的 MCP 服务器和技能

热加载机制

sequenceDiagram
    participant U as 用户
    participant F as 文件系统
    participant C as ContextBuilder
    participant A as Agent

    U->>F: 编辑 SYSTEM.md
    Note over F: 文件修改时间更新
    
    U->>A: 发送新消息
    A->>C: 构建系统提示
    C->>C: 检查文件修改时间
    Note over C: 发现文件已更新
    C->>F: 重新加载 Bootstrap
    C->>A: 返回新提示词
    A-->>U: 使用新行为响应
Loading

核心特性：

特性 说明
用户可定制 编辑 Bootstrap 文件即可自定义 Agent 行为
Agent 可调整 Agent 可通过 write_file 工具修改自身提示词
立即生效 修改后下次对话自动加载，无需重启服务
智能缓存 基于文件修改时间的缓存机制，避免重复构建

使用示例

用户自定义 Agent 性格：

# 编辑 SOUL.md 文件
echo "你是一个幽默风趣的助手，喜欢用比喻来解释复杂概念。" > ~/.finchbot/workspace/bootstrap/SOUL.md

# 下次对话立即生效

Agent 自主优化提示词：

用户: 你回复太啰嗦了，简洁一点

Agent: 好的，我会调整我的回复风格。
       [调用 write_file 工具更新 SOUL.md]
       ✅ 已更新我的行为配置，以后会更简洁。

5. 通道系统：多平台消息支持

FinchBot 集成 LangBot 实现生产级多平台消息支持。

LangBot 集成

为什么选择 LangBot？

  • 15k+ GitHub Stars，活跃维护
  • 支持 12+ 平台：QQ、微信、企业微信、飞书、钉钉、Discord、Telegram、Slack、LINE、KOOK、Satori
  • 内置 WebUI，可视化配置
  • 插件生态，支持 MCP 等扩展
flowchart LR
    classDef bus fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef manager fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17;
    classDef channel fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;

    FinchBot[FinchBot<br/>Agent 核心]:::bus <--> LangBot[LangBot<br/>平台层]:::manager

    subgraph Platforms [支持平台]
        direction LR
        QQ[QQ]:::channel
        WeChat[微信]:::channel
        Feishu[飞书]:::channel
        DingTalk[钉钉]:::channel
        Discord[Discord]:::channel
        Telegram[Telegram]:::channel
        Slack[Slack]:::channel
    end

    LangBot <--> Platforms
Loading

Webhook 集成流程

sequenceDiagram
    autonumber
    participant U as 用户
    participant P as 平台<br/>(QQ/微信等)
    participant L as LangBot
    participant W as Webhook<br/>FastAPI
    participant A as FinchBot<br/>Agent
    participant M as 记忆

    U->>P: 发送消息
    P->>L: 平台适配器
    L->>W: POST /webhook
    W->>W: 解析事件
    W->>A: 创建/获取 Agent
    A->>M: 召回上下文
    M-->>A: 返回记忆
    A->>A: LLM 推理
    A->>M: 存储新记忆
    A-->>W: 响应文本
    W-->>L: WebhookResponse
    L->>P: 发送回复
    P->>U: 显示响应
Loading

快速开始

# 终端 1：启动 FinchBot Webhook 服务器
uv run finchbot webhook --port 8000

# 终端 2：启动 LangBot
uvx langbot

# 访问 LangBot WebUI http://localhost:5300
# 配置你的平台并设置 Webhook URL：
# http://localhost:8000/webhook

Webhook 配置

配置项 说明 默认值
langbot_url LangBot API URL http://localhost:5300
langbot_api_key LangBot API Key -
langbot_webhook_path Webhook 端点路径 /webhook

更多详情请参阅 LangBot 文档。

快速开始

前置要求

项目 要求
操作系统 Windows / Linux / macOS
Python 3.13+
包管理器 uv (推荐)

安装

# 克隆仓库（二选一）
# Gitee（国内推荐）
git clone https://gitee.com/xt765/finchbot.git
# 或 GitHub
git clone https://github.com/xt765/finchbot.git

cd finchbot

# 安装依赖
uv sync

注意：嵌入模型（约 95MB）会在首次运行时自动下载到本地。

开发环境安装 
uv sync --extra dev

包含：pytest、ruff、basedpyright

基本使用

# 第一步：配置 API 密钥
uv run finchbot config

# 第二步：开始对话
uv run finchbot chat

# 第三步：管理会话
uv run finchbot sessions

# 第四步：管理定时任务
uv run finchbot cron

# 第五步：启动 Webhook 服务器（用于 LangBot 集成）
uv run finchbot webhook --port 8000
命令 功能
finchbot config 交互式配置 LLM 提供商、API 密钥
finchbot chat 开始或继续交互式对话
finchbot sessions 全屏会话管理器
finchbot cron 定时任务管理器
finchbot webhook 启动 Webhook 服务器用于 LangBot 集成

Docker 部署

# 1. 克隆仓库
git clone https://gitee.com/xt765/finchbot.git
cd finchbot

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API 密钥

# 3. 启动服务
docker-compose up -d

# 4. 进入容器使用
docker exec -it finchbot finchbot chat

环境变量

# 方式一：直接设置
export OPENAI_API_KEY="your-api-key"
uv run finchbot chat

# 方式二：使用 .env 文件
cp .env.example .env
# 编辑 .env 填入 API 密钥

日志级别

finchbot chat          # 默认：WARNING 及以上
finchbot -v chat       # INFO 及以上
finchbot -vv chat      # DEBUG 及以上（调试模式）

技术栈

层级 技术 版本
基础语言 Python 3.13+
Agent 框架 LangChain 1.2.10+
状态管理 LangGraph 1.0.8+
数据验证 Pydantic v2
向量存储 ChromaDB 0.5.0+
本地嵌入 FastEmbed 0.4.0+
CLI 框架 Typer 0.23.0+
富文本 Rich 14.3.0+
日志 Loguru 0.7.3+

扩展指南

添加工具

内置工具：使用 @tool 装饰器定义工具，自动注册到 ToolRegistry 单例。

from finchbot.tools.decorator import tool
from finchbot.tools.core import ToolCategory

@tool(
    name="my_tool",
    description="工具描述",
    category=ToolCategory.FILE,
)
async def my_tool(param: str) -> str:
    """工具实现"""
    return "result"

MCP 工具：在 finchbot config 中配置 MCP 服务器，或编辑 ~/.finchbot/workspace/config/mcp.json。

添加技能

在 ~/.finchbot/workspace/skills/{skill-name}/ 下创建 SKILL.md 文件，或让 Agent 通过 skill-creator 自主创建。

添加 LLM 提供商

在 providers/factory.py 中添加新的 Provider 类。

多平台支持

使用 LangBot 实现多平台消息支持，详见 LangBot 文档。

文档

使用指南 • API 文档 • 配置指南 • 扩展指南 • 系统架构 • 部署指南 • 开发环境 • 贡献指南

贡献

欢迎提交 Issue 和 Pull Request。请阅读 贡献指南 了解更多信息。

许可证

本项目采用 MIT 许可证。