组件开发 · 第 1 篇 / 共 3 篇 —— 机制

组件系统

组件就是一个继承 BaseCell 的 Python 类，丢进 components/ 目录，3 秒内被扫描、加载、包装成工具，LLM 就能直接调用。不注册、不改配置、不重启。

从文件到工具：完整链路

每一层都有独立的职责，任何一步失败都会记录在加载错误里，可用 component.info() 查到。

components/foo.py
  │ discover_components()     扫描目录，AST 提取 BaseCell 子类
  │ _instantiate_component()  动态 import + 实例化 + on_load()
  │ register_cell()           写入内存注册表 _cell_registry
  │ register_to_config()      追加到 settings.yaml enabled_components
  │ CellToolAdapter           包装成 BaseTool（含 JSON Schema）
  │ ComponentToolRegistry     线程安全注册表，version++
  ↓
AgentLoop 每轮对话 get_all_tools() → LLM 看到 foo
  ↓
execute_with_context() → _cmd_xxx() → Dict 返回

三层注册表

同一个组件在三个地方留痕，用途不同。

核心特性

工具定义怎么生成

没有手写 schema，全部从代码推导。这也是写组件时唯一需要讲究的地方。

• 方法签名决定参数名、类型和必填项（无默认值 = 必填）
• docstring 的 Args: 段决定参数描述，解析不到就退化为参数名本身
• 类型注解 int/float/bool/list/dict 分别映射为 integer/number/boolean/array/object
• 类 docstring 超过 400 字符会被截断，并自动补上命令列表和 help 提示

# 单命令：参数平铺，无 command 字段
def _cmd_ping(self) -> Dict: ...

# 多命令：command 变成 enum，其余参数全部合并到同一层
# 所以不同命令不要用同名但不同类型的参数
def _cmd_get(self, key: str) -> Dict: ...
def _cmd_set(self, key: str, value: str) -> Dict: ...

命令推断兜底

LLM 偶尔忘记传 command 字段。适配器会按「参数命中覆盖度」给每个子命令打分，必填参数权重更高，选得分最高的那个执行；显式传了 command 就完全按传入值走。

保留工具名

以下三个名字属于内置工具，组件注册同名会被拒绝，cell_name 请避开。

• shell — ShellTool
• memory — MemoryTool
• file — FileTool

沙箱与白名单

非白名单组件一律进子进程。子进程常驻并复用，但空闲会被回收。

内置免沙箱组件（硬编码，不可移除）：component、scheduler、skill_manager、skill_installer、sub_agent、web_fetch、web_search、qq_files、telegram_files、feishu_files、weixin_files。

白名单的具体操作（查看、加入、移出）放在第 2 篇，这里只讲模型本身。

内置组件

随发行版自带，源码就在 components/ 下，可以直接读、直接改。

常见故障