Five Pebbles（五块卵石）

简介

五块卵石（Five Pebbles） 是一个基于生命周期钩子的插件化 Agent 框架。它提供了灵活、可扩展的方式来构建和运行 AI Agent，支持终端 REPL、Web 界面和远程协议调用等多种交互方式。

灵感来源于《Rain World》中的迭代器「五块卵石」—— 冷静、理性、追求优雅的解决方案。

特性

🤖 强大的 Agent 引擎 — 基于生命周期钩子，在 Agent 运行的各个阶段注入自定义逻辑
🔌 插件化架构 — 通过插件动态扩展工具、命令和行为，无需修改核心代码
🖥️ 终端 REPL — 交互式命令行界面，语法高亮、自动补全、流式输出
🌐 Web 界面 — 浏览器端图形界面，开箱即用
🔗 ACP 协议 — JSON-RPC 2.0 远程调用，轻松集成 IDE、CI/CD、其他 Agent

快速安装

基本安装（核心 + CLI）

pip install fp-agent

安装后即可使用终端 REPL：

fp

安装所有组件

pip install fp-agent[all]

选择性安装

# 核心 + Web 界面
pip install fp-agent[webui]

# 核心 + ACP 协议
pip install fp-agent[acp]

要求 Python >= 3.11。

Windows 用户：推荐安装 Git for Windows（安装时勾选"Git Bash"并添加到 PATH），以获得完整的 Unix 命令支持。未安装时会自动降级到 cmd.exe，仅支持 Windows 原生命令。

快速使用

终端 REPL（默认）

fp

进入交互式对话：

>> 请用 Python 写一个斐波那契数列生成器

Web 界面

pip install fp-agent[webui]
fp --webui

浏览器访问 http://localhost:7860。

ACP 远程调用

pip install fp-agent[acp]
fp --acp

然后通过 JSON-RPC 调用：

curl http://localhost:9090 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"chat","params":{"message":"你好"}}'

配置

命令行选项

fp [OPTIONS]

选项：
  --config FILE        指定配置文件路径
  --webui             启动 Web 界面模式
  --acp               启动 ACP Server 模式
  --model NAME        指定 LLM 模型名称
  --host HOST         监听地址（默认 127.0.0.1）
  --port PORT         监听端口
  --debug             启用调试模式
  --quiet             静默模式
  --version           显示版本信息

配置文件

默认读取 ~/.config/fp/config.yaml：

llm:
  provider: openai
  model: gpt-4o
  temperature: 0.7
  api_key: ${OPENAI_API_KEY}

session:
  storage: file
  path: ~/.local/share/fp/sessions

plugins:
  - my_plugin

cli:
  theme: dark
  stream: true

项目结构

fp                          # 主包（用户入口）
├── fp-core                 # 核心引擎（Agent 逻辑、LLM 交互、插件系统）
├── fp-terminal              # 终端 REPL 界面
├── fp-webui                # Web 界面
└── fp-acp                  # ACP 通信协议（JSON-RPC 2.0）

文档

依赖

依赖	版本	说明
`fp-core`	>= 0.1.0	Agent 核心引擎（必装）
`fp-terminal`	>= 0.1.0	终端 REPL（必装）
`fp-webui`	>= 0.1.0	Web 界面（可选）
`fp-acp`	>= 0.1.0	ACP 协议（可选）

许可

MIT © zpb

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fp_agent-0.1.10.tar.gz (6.8 kB view details)

Uploaded Jul 27, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fp_agent-0.1.10-py3-none-any.whl (6.7 kB view details)

Uploaded Jul 27, 2026 Python 3

File details

Details for the file fp_agent-0.1.10.tar.gz.

File metadata

Download URL: fp_agent-0.1.10.tar.gz
Upload date: Jul 27, 2026
Size: 6.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for fp_agent-0.1.10.tar.gz
Algorithm	Hash digest
SHA256	`ce21c51cbb1edaef56214ef43da58637feb5dafda8719e0198741e50a9c0ab6d`
MD5	`cb04bd1b8e8781457ba2af45762c43a6`
BLAKE2b-256	`75140dcfc62c1fc32e1ca37fade2ca04ac3a03083ef37c7b8c009db71e92dd23`

See more details on using hashes here.

Provenance

The following attestation bundles were made for fp_agent-0.1.10.tar.gz:

Publisher: release.yml on zpb911km/fp-agent

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: fp_agent-0.1.10.tar.gz
- Subject digest: ce21c51cbb1edaef56214ef43da58637feb5dafda8719e0198741e50a9c0ab6d
- Sigstore transparency entry: 2257331623
- Sigstore integration time: Jul 27, 2026
Source repository:
- Permalink: zpb911km/fp-agent@f7caecc2eee77fd7c5e005c0318a62705bf37ef9
- Branch / Tag: refs/tags/0.1.10
- Owner: https://github.com/zpb911km
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@f7caecc2eee77fd7c5e005c0318a62705bf37ef9
- Trigger Event: push