fp-core 0.1.1.dev0__tar.gz

fp_core-0.1.1.dev0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: fp-core
+Version: 0.1.1.dev0
+Summary: 五块卵石 Agent 引擎 - 基于生命周期钩子的插件化 Agent 核心
+Author: zpb
+License-Expression: MIT
+Keywords: agent,llm,lifecycle,plugin,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: wcwidth>=0.2.0
+Requires-Dist: pyyaml>=6.0
+
+# fp-core — 五块卵石 Agent 引擎
+
+[![PyPI](https://img.shields.io/pypi/v/fp-core)](https://pypi.org/project/fp-core/)
+[![Python](https://img.shields.io/pypi/pyversions/fp-core)](https://pypi.org/project/fp-core/)
+[![License](https://img.shields.io/pypi/l/fp-core)](LICENSE)
+
+## 简介
+
+**fp-core** 是五块卵石（Five Pebbles）Agent 框架的核心引擎。它提供了 Agent 生命周期管理、LLM 交互、工具执行、会话管理及插件化扩展等基础能力，是整个框架的基石。
+
+> 如果你只是**使用** Agent，请安装 [`fp`](https://pypi.org/project/fp/) 主包；如果你要**自定义/扩展** Agent 行为，你正在正确的地方。
+
+---
+
+## 特性
+
+- **生命周期钩子系统** — 在 Agent 的启动、消息处理、工具调用、响应生成等阶段注入自定义逻辑
+- **插件化架构** — 通过插件动态加载工具、命令、事件监听器，无需修改核心代码
+- **多 LLM 支持** — 统一的 LLM 交互接口，可接入 OpenAI、Claude、本地模型等
+- **工具执行引擎** — 安全的沙箱化工具执行，支持同步/异步、超时控制、结果缓存
+- **会话管理** — 持久化的会话存储与恢复，支持多会话并行
+- **提示词模板** — 结构化提示词组装，支持动态注入上下文与历史
+
+---
+
+## 安装
+
+```bash
+pip install fp-core
+```
+
+要求 Python >= 3.11。
+
+---
+
+## 快速使用
+
+### 初始化 Agent 引擎
+
+```python
+from fp_core import AgentEngine
+
+engine = AgentEngine(config={
+    "llm": {"provider": "openai", "model": "gpt-4o"},
+    "session": {"storage": "file", "path": "./sessions"},
+})
+```
+
+### 注册插件
+
+```python
+from fp_core.plugins import BasePlugin
+
+class MyPlugin(BasePlugin):
+    name = "my_plugin"
+    
+    def on_agent_start(self, ctx):
+        print("Agent 启动了！")
+
+    def on_message(self, ctx, message):
+        # 在消息处理前注入逻辑
+        return message
+
+engine.plugin_manager.register(MyPlugin())
+```
+
+### 执行一次对话
+
+```python
+response = engine.chat("你好，请介绍一下你自己")
+print(response)
+```
+
+---
+
+## 架构概览
+
+```
+fp_core/
+├── core/           # 核心运行时：AgentEngine, LLM 接口, 上下文管理
+│   ├── agent.py        # Agent 主循环
+│   ├── llm.py          # LLM 客户端抽象
+│   └── context.py      # 会话上下文
+├── commands/       # 内置命令（内置工具）
+├── tools/          # 工具执行引擎与内置工具集
+│   └── plugins/        # 工具插件加载器
+├── plugins/        # 插件系统
+│   └── base/           # 插件基类与钩子定义
+├── prompts/        # 提示词模板管理
+├── skills/         # 技能定义与加载
+└── sessions/       # 会话存储与管理
+```
+
+### 生命周期钩子
+
+插件可以通过实现以下钩子方法介入 Agent 运行流程：
+
+| 钩子 | 触发时机 | 典型用途 |
+|------|---------|---------|
+| `on_agent_start` | Agent 初始化完成 | 加载自定义资源 |
+| `on_agent_stop` | Agent 关闭前 | 资源清理 |
+| `on_message` | 收到用户消息后 | 消息预处理/校验 |
+| `before_llm_call` | 调用 LLM 前 | 注入系统提示词 |
+| `after_llm_call` | 收到 LLM 响应后 | 响应后处理/过滤 |
+| `before_tool_exec` | 执行工具前 | 权限检查/参数校验 |
+| `after_tool_exec` | 工具执行完成后 | 结果格式化/缓存 |
+| `on_response` | 生成最终响应前 | 响应润色/转译 |
+
+---
+
+## 依赖
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| `httpx` | >= 0.28.0 | LLM API 异步 HTTP 请求 |
+| `rich` | >= 14.0.0 | 控制台输出格式化 |
+| `wcwidth` | >= 0.2.0 | 终端文本宽度计算 |
+| `pyyaml` | >= 6.0 | 配置文件解析 |
+
+---
+
+## 扩展开发
+
+### 编写自定义插件
+
+```python
+from fp_core.plugins import BasePlugin
+from fp_core.plugins.base import hook
+
+class LogPlugin(BasePlugin):
+    name = "logger"
+    
+    @hook("on_message")
+    def log_message(self, ctx, message):
+        print(f"[LOG] 收到消息: {message[:50]}...")
+        return message
+    
+    @hook("before_llm_call")
+    def inject_system_prompt(self, ctx, messages):
+        messages.insert(0, {"role": "system", "content": "请用简洁的语言回答"})
+        return messages
+```
+
+### 编写自定义工具
+
+```python
+from fp_core.tools import BaseTool
+
+class WeatherTool(BaseTool):
+    name = "get_weather"
+    description = "获取指定城市的天气"
+    
+    async def execute(self, city: str) -> dict:
+        # 实现天气查询逻辑
+        return {"city": city, "temperature": 22}
+```
+
+注册到 Agent：
+
+```python
+engine.tool_manager.register_tool(WeatherTool())
+```
+
+---
+
+## 许可
+
+MIT © zpb

fp_core-0.1.1.dev0/README.md

@@ -0,0 +1,168 @@
+# fp-core — 五块卵石 Agent 引擎
+
+[![PyPI](https://img.shields.io/pypi/v/fp-core)](https://pypi.org/project/fp-core/)
+[![Python](https://img.shields.io/pypi/pyversions/fp-core)](https://pypi.org/project/fp-core/)
+[![License](https://img.shields.io/pypi/l/fp-core)](LICENSE)
+
+## 简介
+
+**fp-core** 是五块卵石（Five Pebbles）Agent 框架的核心引擎。它提供了 Agent 生命周期管理、LLM 交互、工具执行、会话管理及插件化扩展等基础能力，是整个框架的基石。
+
+> 如果你只是**使用** Agent，请安装 [`fp`](https://pypi.org/project/fp/) 主包；如果你要**自定义/扩展** Agent 行为，你正在正确的地方。
+
+---
+
+## 特性
+
+- **生命周期钩子系统** — 在 Agent 的启动、消息处理、工具调用、响应生成等阶段注入自定义逻辑
+- **插件化架构** — 通过插件动态加载工具、命令、事件监听器，无需修改核心代码
+- **多 LLM 支持** — 统一的 LLM 交互接口，可接入 OpenAI、Claude、本地模型等
+- **工具执行引擎** — 安全的沙箱化工具执行，支持同步/异步、超时控制、结果缓存
+- **会话管理** — 持久化的会话存储与恢复，支持多会话并行
+- **提示词模板** — 结构化提示词组装，支持动态注入上下文与历史
+
+---
+
+## 安装
+
+```bash
+pip install fp-core
+```
+
+要求 Python >= 3.11。
+
+---
+
+## 快速使用
+
+### 初始化 Agent 引擎
+
+```python
+from fp_core import AgentEngine
+
+engine = AgentEngine(config={
+    "llm": {"provider": "openai", "model": "gpt-4o"},
+    "session": {"storage": "file", "path": "./sessions"},
+})
+```
+
+### 注册插件
+
+```python
+from fp_core.plugins import BasePlugin
+
+class MyPlugin(BasePlugin):
+    name = "my_plugin"
+    
+    def on_agent_start(self, ctx):
+        print("Agent 启动了！")
+
+    def on_message(self, ctx, message):
+        # 在消息处理前注入逻辑
+        return message
+
+engine.plugin_manager.register(MyPlugin())
+```
+
+### 执行一次对话
+
+```python
+response = engine.chat("你好，请介绍一下你自己")
+print(response)
+```
+
+---
+
+## 架构概览
+
+```
+fp_core/
+├── core/           # 核心运行时：AgentEngine, LLM 接口, 上下文管理
+│   ├── agent.py        # Agent 主循环
+│   ├── llm.py          # LLM 客户端抽象
+│   └── context.py      # 会话上下文
+├── commands/       # 内置命令（内置工具）
+├── tools/          # 工具执行引擎与内置工具集
+│   └── plugins/        # 工具插件加载器
+├── plugins/        # 插件系统
+│   └── base/           # 插件基类与钩子定义
+├── prompts/        # 提示词模板管理
+├── skills/         # 技能定义与加载
+└── sessions/       # 会话存储与管理
+```
+
+### 生命周期钩子
+
+插件可以通过实现以下钩子方法介入 Agent 运行流程：
+
+| 钩子 | 触发时机 | 典型用途 |
+|------|---------|---------|
+| `on_agent_start` | Agent 初始化完成 | 加载自定义资源 |
+| `on_agent_stop` | Agent 关闭前 | 资源清理 |
+| `on_message` | 收到用户消息后 | 消息预处理/校验 |
+| `before_llm_call` | 调用 LLM 前 | 注入系统提示词 |
+| `after_llm_call` | 收到 LLM 响应后 | 响应后处理/过滤 |
+| `before_tool_exec` | 执行工具前 | 权限检查/参数校验 |
+| `after_tool_exec` | 工具执行完成后 | 结果格式化/缓存 |
+| `on_response` | 生成最终响应前 | 响应润色/转译 |
+
+---
+
+## 依赖
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| `httpx` | >= 0.28.0 | LLM API 异步 HTTP 请求 |
+| `rich` | >= 14.0.0 | 控制台输出格式化 |
+| `wcwidth` | >= 0.2.0 | 终端文本宽度计算 |
+| `pyyaml` | >= 6.0 | 配置文件解析 |
+
+---
+
+## 扩展开发
+
+### 编写自定义插件
+
+```python
+from fp_core.plugins import BasePlugin
+from fp_core.plugins.base import hook
+
+class LogPlugin(BasePlugin):
+    name = "logger"
+    
+    @hook("on_message")
+    def log_message(self, ctx, message):
+        print(f"[LOG] 收到消息: {message[:50]}...")
+        return message
+    
+    @hook("before_llm_call")
+    def inject_system_prompt(self, ctx, messages):
+        messages.insert(0, {"role": "system", "content": "请用简洁的语言回答"})
+        return messages
+```
+
+### 编写自定义工具
+
+```python
+from fp_core.tools import BaseTool
+
+class WeatherTool(BaseTool):
+    name = "get_weather"
+    description = "获取指定城市的天气"
+    
+    async def execute(self, city: str) -> dict:
+        # 实现天气查询逻辑
+        return {"city": city, "temperature": 22}
+```
+
+注册到 Agent：
+
+```python
+engine.tool_manager.register_tool(WeatherTool())
+```
+
+---
+
+## 许可
+
+MIT © zpb

fp_core-0.1.1.dev0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=64.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fp-core"
+dynamic = ["version"]
+description = "五块卵石 Agent 引擎 - 基于生命周期钩子的插件化 Agent 核心"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "zpb"}]
+keywords = ["agent", "llm", "lifecycle", "plugin", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "httpx>=0.28.0",
+    "rich>=14.0.0",
+    "wcwidth>=0.2.0",
+    "pyyaml>=6.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["fp_core*"]
+
+[tool.setuptools.package-data]
+"fp_core" = ["*.md", "*.json", "*.yaml", "*.yml"]
+
+[tool.setuptools_scm]
+root = "../.."
+local_scheme = "no-local-version"

fp_core-0.1.1.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fp_core-0.1.1.dev0/src/fp_core/__init__.py

@@ -0,0 +1,21 @@
+"""fp-core - 五块卵石 Agent 引擎"""
+
+__version__ = "0.1.0"
+__license__ = "MIT"
+__author__ = "zpb"
+
+from fp_core.core.agent import Agent, Message, Response
+from fp_core.core.lifecycle import HookContext, LifecycleHook, LifecycleManager
+from fp_core.plugins.base.plugin import Plugin, PluginConfig, PluginRegistry
+
+__all__ = [
+    "Agent",
+    "Message",
+    "Response",
+    "LifecycleManager",
+    "LifecycleHook",
+    "HookContext",
+    "Plugin",
+    "PluginConfig",
+    "PluginRegistry",
+]

fp_core-0.1.1.dev0/src/fp_core/commands/__init__.py

@@ -0,0 +1,132 @@
+"""
+commands/__init__.py — 命令注册表与自动发现
+
+自动扫描 commands/ 目录下所有 .py 文件（排除 __init__.py），
+导入每个模块并检查 name/execute 接口，构建命令名→模块的映射（含别名）。
+"""
+
+import asyncio
+import importlib
+import importlib.util
+import os
+
+from fp_core import display
+
+# 缓存：命令名 → 模块对象
+_commands: dict[str, "CommandModule"] = {}
+
+
+# 类型标注
+class CommandModule:
+    name: str
+    aliases: list[str]
+    description: str
+
+    # execute 返回 (已处理, 输出文本)；
+    # 兼容旧版：也可只返回 bool（自动转为 ("", False/True)）
+    # 同步或异步均可，由 execute() 自动适配
+    async def execute(self, arg: str) -> tuple[bool, str]: ...
+
+
+def _discover_commands():
+    """扫描并注册所有命令模块（内置 → 用户，同名覆盖）"""
+    global _commands
+    _commands = {}
+
+    builtin_dir = os.path.dirname(os.path.abspath(__file__))
+    _scan_dir(builtin_dir, "fp_core.commands")
+
+    # 用户命令目录
+    _xdg_data = os.environ.get("XDG_DATA_HOME", os.path.join(os.path.expanduser("~"), ".local", "share"))
+    user_dir = os.path.join(_xdg_data, "fp", "commands")
+    _scan_dir(user_dir)  # 直接 import 路径，通过 sys.path 解析
+
+
+def _scan_dir(directory: str, package_prefix: str | None = None):
+    """扫描单个目录下的命令文件"""
+    if not os.path.isdir(directory):
+        return
+
+    for fname in sorted(os.listdir(directory)):
+        if not fname.endswith(".py") or fname == "__init__.py":
+            continue
+
+        mod_name = fname[:-3]
+        try:
+            if package_prefix:
+                mod = importlib.import_module(f"{package_prefix}.{mod_name}")
+            else:
+                spec = importlib.util.spec_from_file_location(mod_name, os.path.join(directory, fname))
+                if spec is None or spec.loader is None:
+                    continue
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)
+        except Exception as e:
+            display.warning(f"⚠️  命令加载失败 [{mod_name}]: {e}")
+            continue
+
+        # 校验接口
+        if not hasattr(mod, "name") or not hasattr(mod, "execute"):
+            display.warning(f"⚠️  命令模块 [{mod_name}] 缺少 name/execute，已跳过")
+            continue
+
+        name = mod.name
+        if name in _commands:
+            display.warning(f"⚠️  命令 [{name}] 重复定义，已覆盖")
+        _commands[name] = mod
+
+        # 注册别名
+        for alias in getattr(mod, "aliases", []):
+            if alias in _commands:
+                display.warning(f"⚠️  别名 [{alias}] 与已有命令/别名冲突，已跳过")
+                continue
+            _commands[alias] = mod
+
+
+_discover_commands()
+
+
+def get_command(name: str) -> CommandModule | None:
+    """根据命令名（含斜杠）或别名查找命令模块"""
+    return _commands.get(name)
+
+
+def get_all_commands() -> dict[str, str]:
+    """返回 {命令名: 描述} 字典（只返回主名称，不含别名）"""
+    result: dict[str, str] = {}
+    seen: set[int] = set()
+    for name, mod in _commands.items():
+        mod_id = id(mod)
+        if mod_id in seen:
+            continue
+        if hasattr(mod, "name") and mod.name == name:
+            result[name] = getattr(mod, "description", "")
+            seen.add(mod_id)
+    return result
+
+
+async def execute(agent, cmd_name: str, arg: str) -> tuple[bool, str]:
+    """执行命令，返回 (是否已处理, 输出文本)。
+
+    兼容旧版只返回 bool 的命令（自动补为 ("", False/True)）。
+    新版命令可返回 tuple[bool, str] 或 tuple[bool, str, str]。
+    """
+    mod = get_command(cmd_name)
+    if mod is None:
+        return (False, "")
+
+    # 执行命令（自动适配同步/异步）
+    if asyncio.iscoroutinefunction(mod.execute):
+        result = await mod.execute(agent, arg)
+    else:
+        result = mod.execute(agent, arg)
+
+    # 兼容旧版：只返回 bool
+    if isinstance(result, bool):
+        return (result, "")
+
+    # 新版：返回 (handled, output)
+    if isinstance(result, tuple):
+        return result
+
+    return (True, str(result))

fp_core-0.1.1.dev0/src/fp_core/commands/back.py

@@ -0,0 +1,73 @@
+"""back 命令 — 回退到对话的某个历史时刻
+
+用法:
+  /back list           查看历史消息列表（仅非 system 消息，按 1-based 编号）
+  /back <index>        回退到指定位置（删除后续消息）
+  /back <index> 2      同上（删除后续消息）
+"""
+
+name = "back"
+aliases = []
+description = "回退到对话的某个历史时刻。用法: /back list 查看列表, /back <N> 直接回退"
+
+
+async def execute(agent, arg: str) -> tuple[bool, str]:
+    parts = arg.strip().split()
+
+    if not parts:
+        msg = "❌ 用法: /back list (查看列表) 或 /back <N> (直接回退)"
+        agent.io.error(msg)
+        return (True, msg)
+
+    cmd = parts[0]
+
+    # ── /back list ─────────────────────────────────────────────
+    if cmd == "list":
+        history_msgs = agent.get_history_for_display()
+        if not history_msgs:
+            msg = "没有历史记录"
+            agent.io.info(msg)
+            return (True, msg)
+
+        roles_zh = {"user": "👤 用户", "assistant": "🤖 AI", "tool": "🔧 工具"}
+        lines = [f"📜 对话历史（共 {len(history_msgs)} 条消息，使用 /back <N> 回退）:"]
+        for i, msg in enumerate(history_msgs):
+            role = roles_zh.get(msg["role"], msg["role"])
+            content = msg.get("content", "")
+            if msg["role"] == "tool":
+                content = content[:60] + "..." if len(content) > 60 else content
+            else:
+                content = content[:120] + "..." if len(content) > 120 else content
+            content = content.replace("\n", " ")
+            lines.append(f"  [{i + 1:3d}] {role}: {content}")
+
+        agent.io.info(lines[0])
+        for line in lines[1:]:
+            agent.io.item(line)
+
+        return (True, "\n".join(lines))
+
+    # ── /back <index> [2] ──────────────────────────────────────
+    try:
+        index = int(cmd)
+    except ValueError:
+        msg = f"❌ 无效参数：'{cmd}' — 请用 /back list 查看列表，/back <N> 回退"
+        agent.io.error(msg)
+        return (True, msg)
+
+    mode = None
+    if len(parts) >= 2:
+        try:
+            mode = int(parts[1])
+            if mode != 2:
+                msg = "❌ mode=1（保留后续消息）暂不支持，请用 mode=2 或 /fork"
+                agent.io.error(msg)
+                return (True, msg)
+        except ValueError:
+            msg = f"❌ 无效参数：'{parts[1]}' 不是数字"
+            agent.io.error(msg)
+            return (True, msg)
+
+    result = await agent.back(target_idx=index, mode=mode)
+    agent.io.info(result)
+    return (True, result)

fp_core-0.1.1.dev0/src/fp_core/commands/clear.py

@@ -0,0 +1,14 @@
+"""clear 命令 — 清空当前会话"""
+
+from fp_core import display
+
+name = "clear"
+aliases = []
+description = "清空当前会话"
+
+
+def execute(agent, arg: str) -> tuple[bool, str]:
+    agent.clear_session()
+    msg = "🧹 当前会话已清空"
+    display.info(msg)
+    return (True, msg)

fp_core-0.1.1.dev0/src/fp_core/commands/compact.py

@@ -0,0 +1,10 @@
+"""compact 命令 — 压缩对话历史（异步）"""
+
+name = "compact"
+aliases = []
+description = "压缩对话历史"
+
+
+async def execute(agent, arg: str) -> tuple[bool, str]:
+    await agent.compact_context()
+    return (True, "📦 历史已压缩")

fp_core-0.1.1.dev0/src/fp_core/commands/exit_bang.py

@@ -0,0 +1,27 @@
+"""exit! 命令 — 核弹级退出：删除当前会话、不留痕迹"""
+
+import os
+
+from fp_core import display
+
+name = "exit!"
+aliases = []
+description = "核弹级退出：删除当前会话、不留痕迹"
+
+
+def execute(agent, arg: str) -> bool:
+    sid = agent.session.session_id
+    path = agent.session.get_session_path()
+
+    # 标记核弹退出 — shutdown 时会删除会话文件
+    agent.set_nuclear_exit()
+
+    # 提前删除文件（shutdown 也会删，双重保险）
+    if os.path.exists(path):
+        try:
+            os.remove(path)
+            display.info(f"💥 会话 {sid} 已删除，不留痕迹")
+        except Exception as e:
+            display.warning(f"⚠️  删除失败: {e}")
+
+    raise SystemExit()

fp_core-0.1.1.dev0/src/fp_core/commands/exit_cmd.py

@@ -0,0 +1,9 @@
+"""exit 命令 — 退出程序"""
+
+name = "exit"
+aliases = ["quit"]
+description = "退出程序"
+
+
+def execute(agent, arg: str) -> bool:
+    raise SystemExit()