076 API 9dd0e001

API 详细参考

本文档提供 FinchBot 核心类和方法的详细 API 参考。

目录

1. Agent 模块
2. Memory 模块
3. Tools 模块
4. Skill 模块
5. Channel 模块
6. Config 模块
7. I18n 模块
8. Providers 模块

1. Agent 模块 (finchbot.agent)

1.1 AgentFactory

Agent 工厂类，负责组装和配置 Agent 实例。

class AgentFactory:
    @staticmethod
    def create_for_cli(
        model: BaseChatModel,
        workspace: Path,
        session_id: str,
        config: Config,
        session_metadata_store: SessionMetadataStore | None = None,
    ) -> tuple[CompiledStateGraph, SqliteSaver | MemorySaver, list[BaseTool]]:

参数:

• model: 基础聊天模型实例
• workspace: 工作目录路径
• session_id: 会话 ID
• config: 配置对象
• session_metadata_store: 会话元数据存储（可选）

返回:

• (agent, checkpointer, tools) 元组

1.2 create_finch_agent

创建并配置一个 FinchBot 智能体实例。

async def create_finch_agent(
    model: BaseChatModel,
    workspace: Path,
    tools: Sequence[BaseTool] | None = None,
    use_persistent: bool = True,
) -> tuple[CompiledStateGraph, AsyncSqliteSaver | MemorySaver]:

参数:

• model: 基础聊天模型实例 (如 ChatOpenAI, ChatAnthropic)
• workspace: 工作目录路径 (Path 对象)，用于文件操作、记忆存储等
• tools: 可用工具序列 (可选，默认为 None)
• use_persistent: 是否启用持久化存储 (Checkpointing)

返回:

• (agent, checkpointer) 元组:
  • agent: 编译后的 LangGraph 状态图
  • checkpointer: 持久化存储对象

示例:

import asyncio
from pathlib import Path
from langchain_openai import ChatOpenAI
from finchbot.agent import create_finch_agent

async def main():
    model = ChatOpenAI(model="gpt-4")
    workspace = Path("./workspace")
    agent, checkpointer = await create_finch_agent(model, workspace)

    response = await agent.ainvoke(
        {"messages": [("user", "Hello!")]}, 
        config={"configurable": {"thread_id": "1"}}
    )

if __name__ == "__main__":
    asyncio.run(main())

1.3 ContextBuilder

动态系统提示词构建器。

class ContextBuilder:
    def __init__(self, workspace: Path): ...
    
    def build_system_prompt(self, skill_names, use_cache=True) -> str: ...

方法:

• build_system_prompt(): 生成完整的系统提示词字符串

提示词组成:

• SYSTEM.md: 基础角色设定
• MEMORY_GUIDE.md: 记忆使用准则
• SOUL.md: 灵魂设定（性格特征）
• AGENT_CONFIG.md: Agent 配置
• SKILL.md: 动态加载的技能描述
• TOOLS.md: 自动生成的工具文档
• 运行时信息 (OS, Time, Python Version)

1.4 get_sqlite_checkpointer

获取 SQLite 持久化检查点。

def get_sqlite_checkpointer(db_path: Path) -> SqliteSaver:

参数:

• db_path: SQLite 数据库文件路径

返回:

• SqliteSaver 实例

2. Memory 模块 (finchbot.memory)

2.1 MemoryManager

记忆系统的统一入口。

class MemoryManager:
    def __init__(
        self, 
        workspace: Path, 
        embedding_model: str = "BAAI/bge-small-zh-v1.5"
    ): ...

remember

保存一条新记忆。

def remember(
    self,
    content: str,
    category: str | None = None,
    importance: float | None = None,
    tags: list[str] | None = None,
) -> str:

参数:

• content: 记忆的文本内容
• category: 分类 (可选，如 "personal", "work")
• importance: 重要性评分 (0.0-1.0，可选)
• tags: 标签列表 (可选)

返回:

• memory_id: 新创建的记忆 ID (UUID)

recall

检索相关记忆。

def recall(
    self,
    query: str,
    top_k: int = 5,
    category: str | None = None,
    query_type: QueryType = QueryType.COMPLEX,
    similarity_threshold: float = 0.5,
    include_archived: bool = False,
) -> list[dict[str, Any]]:

参数:

• query: 查询文本 (自然语言)
• top_k: 返回结果数量 (默认 5)
• category: 按分类过滤 (可选)
• query_type: 查询类型 (默认 QueryType.COMPLEX)
• similarity_threshold: 相似度阈值 (默认 0.5)
• include_archived: 是否包含归档的记忆 (默认 False)

QueryType 枚举:

返回:

• 记忆字典列表，每个包含 id, content, category, importance, similarity 等字段

forget

删除或归档记忆。

def forget(self, pattern: str) -> dict[str, Any]:

参数:

• pattern: 用于匹配记忆内容的字符串

返回:

• 删除统计信息字典

其他方法

def get_stats(self) -> dict: ...
def search_memories(self, query: str, ...) -> list[dict]: ...
def get_recent_memories(self, days: int = 7, limit: int = 20) -> list[dict]: ...
def get_important_memories(self, min_importance: float = 0.8, limit: int = 20) -> list[dict]: ...

使用示例

from finchbot.memory import MemoryManager, QueryType
from pathlib import Path

manager = MemoryManager(Path.home() / ".finchbot" / "workspace")

memory = manager.remember(
    content="用户偏好使用深色主题",
    category="preference",
    importance=0.8
)

results = manager.recall(
    query="用户界面偏好",
    query_type=QueryType.CONCEPTUAL,
    top_k=5
)

stats = manager.forget("旧邮箱")

2.2 QueryType

查询类型枚举。

class QueryType(StrEnum):
    KEYWORD_ONLY = "keyword_only"
    SEMANTIC_ONLY = "semantic_only"
    FACTUAL = "factual"
    CONCEPTUAL = "conceptual"
    COMPLEX = "complex"
    AMBIGUOUS = "ambiguous"

3. Tools 模块 (finchbot.tools)

3.1 FinchTool (基类)

所有工具的基类。

class FinchTool(BaseTool):
    name: str
    description: str
    parameters: ClassVar[dict[str, Any]]
    
    def _run(self, *args, **kwargs) -> Any: ...
    async def _arun(self, *args, **kwargs) -> Any: ...

3.2 ToolFactory

工具工厂类。

class ToolFactory:
    @staticmethod
    def create_default_tools(
        workspace: Path,
        config: Config,
        session_metadata_store: SessionMetadataStore | None = None,
    ) -> list[BaseTool]:

参数:

• workspace: 工作目录路径
• config: 配置对象
• session_metadata_store: 会话元数据存储（可选）

返回:

• 工具列表

3.3 ToolRegistry

工具注册表（单例模式）。

class ToolRegistry:
    _instance: ClassVar[ToolRegistry | None] = None
    _tools: dict[str, BaseTool]
    
    @classmethod
    def get_instance(cls) -> ToolRegistry: ...
    
    def register(self, tool: BaseTool) -> None: ...
    def get(self, name: str) -> BaseTool | None: ...
    def list_tools(self) -> list[str]: ...
    def get_all_tools(self) -> list[BaseTool]: ...

3.4 创建自定义工具

from finchbot.tools.base import FinchTool
from typing import Any, ClassVar

class MyCustomTool(FinchTool):
    """自定义工具示例"""
    
    name: str = "my_custom_tool"
    description: str = "我的自定义工具描述"
    parameters: ClassVar[dict[str, Any]] = {
        "type": "object",
        "properties": {
            "input_text": {
                "type": "string",
                "description": "输入文本"
            }
        },
        "required": ["input_text"]
    }
    
    def _run(self, input_text: str) -> str:
        return f"处理结果: {input_text}"

3.5 内置工具

4. Skill 模块 (finchbot.agent.skills)

4.1 SkillsLoader

技能加载器。

class SkillsLoader:
    def __init__(self, workspace: Path): ...
    
    def list_skills(self, use_cache: bool = True) -> list[dict]: ...
    def load_skill(self, name: str, use_cache: bool = True) -> str | None: ...
    def get_always_skills(self) -> list[str]: ...
    def build_skills_summary(self) -> str: ...

方法:

• list_skills(): 扫描并列出所有可用技能
• load_skill(): 加载指定技能内容
• get_always_skills(): 获取所有常驻技能
• build_skills_summary(): 构建 XML 格式的技能摘要

4.2 技能文件格式

---
name: skill-name
description: 技能描述
metadata:
  finchbot:
    emoji: ✨
    always: false
    requires:
      bins: [curl, jq]
      env: [API_KEY]
---
# 技能正文 (Markdown)

5. Channel 模块 (finchbot.channels)

5.1 BaseChannel

通道抽象基类。

class BaseChannel(ABC):
    @abstractmethod
    async def start(self) -> None: ...
    
    @abstractmethod
    async def stop(self) -> None: ...
    
    @abstractmethod
    async def send(self, message: OutboundMessage) -> None: ...
    
    @abstractmethod
    async def receive(self) -> AsyncGenerator[InboundMessage, None]: ...

5.2 MessageBus

异步消息路由器。

class MessageBus:
    def __init__(self): ...
    
    @property
    def inbound(self) -> asyncio.Queue[InboundMessage]: ...
    
    @property
    def outbound(self) -> asyncio.Queue[OutboundMessage]: ...
    
    async def publish_inbound(self, message: InboundMessage) -> None: ...
    async def publish_outbound(self, message: OutboundMessage) -> None: ...
    async def consume_inbound(self) -> AsyncGenerator[InboundMessage, None]: ...
    async def consume_outbound(self) -> AsyncGenerator[OutboundMessage, None]: ...

5.3 ChannelManager

通道管理器。

class ChannelManager:
    def __init__(self, bus: MessageBus): ...
    
    def register_channel(self, channel: BaseChannel) -> None: ...
    def unregister_channel(self, channel_id: str) -> None: ...
    async def start_all(self) -> None: ...
    async def stop_all(self) -> None: ...

5.4 消息模型

class InboundMessage(BaseModel):
    """入站消息"""
    channel_id: str
    user_id: str
    content: str
    session_id: str | None = None
    metadata: dict = {}

class OutboundMessage(BaseModel):
    """出站消息"""
    channel_id: str
    user_id: str
    content: str
    session_id: str | None = None
    metadata: dict = {}

6. Config 模块 (finchbot.config)

6.1 Config (根配置)

class Config(BaseSettings):
    language: str = "en-US"
    language_set_by_user: bool = False
    default_model: str = "gpt-5"
    default_model_set_by_user: bool = False
    agents: AgentsConfig = Field(default_factory=AgentsConfig)
    providers: ProvidersConfig = Field(default_factory=ProvidersConfig)
    tools: ToolsConfig = Field(default_factory=ToolsConfig)

6.2 load_config

加载配置。

def load_config() -> Config: ...

说明:

• 自动合并默认配置、~/.finchbot/config.json 和环境变量
• 环境变量优先级最高 (前缀 FINCHBOT_)

6.3 配置结构

Config (根配置)
├── language
├── default_model
├── agents
│   └── defaults
├── providers
│   ├── openai
│   ├── anthropic
│   ├── deepseek
│   ├── moonshot
│   ├── dashscope
│   ├── groq
│   ├── gemini
│   ├── openrouter
│   └── custom
└── tools
    ├── web.search
    ├── exec
    └── restrict_to_workspace

7. I18n 模块 (finchbot.i18n)

7.1 I18nLoader

国际化加载器。

class I18nLoader:
    def __init__(self, locale: str = "en-US"): ...
    
    def get(self, key: str, default: str = "") -> str: ...
    def t(self, key: str, **kwargs) -> str: ...

方法:

• get(): 获取翻译文本
• t(): 获取翻译文本并支持变量替换

示例:

from finchbot.i18n import I18nLoader

i18n = I18nLoader("zh-CN")

text = i18n.get("cli.help")
text = i18n.t("cli.chat.session", session_id="abc123")

7.2 支持的语言

8. Providers 模块 (finchbot.providers)

8.1 create_chat_model

创建聊天模型。

def create_chat_model(
    provider: str,
    model: str,
    config: Config,
) -> BaseChatModel:

参数:

• provider: 提供商名称
• model: 模型名称
• config: 配置对象

返回:

• BaseChatModel 实例

8.2 支持的提供商

8.3 使用示例

from finchbot.providers import create_chat_model
from finchbot.config import load_config

config = load_config()

model = create_chat_model(
    provider="openai",
    model="gpt-5",
    config=config,
)