fp-core 0.1.0__py3-none-any.whl

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/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/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/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/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/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/commands/exit_cmd.py

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

fp_core/commands/fork.py

@@ -0,0 +1,16 @@
+"""fork 命令 — 基于当前上下文新建会话"""
+
+from fp_core import display
+
+name = "fork"
+aliases = []
+description = "基于当前上下文新建会话"
+
+
+def execute(agent, arg: str) -> tuple[bool, str]:
+    result = agent.fork()
+    if result:
+        display.info(result)
+        return (True, result)
+    display.info("当前会话没有消息，无法 fork")
+    return (True, "")

fp_core/commands/help.py

@@ -0,0 +1,25 @@
+"""help 命令 — 显示帮助信息"""
+
+from fp_core import display
+
+name = "help"
+aliases = ["?"]
+description = "显示此帮助"
+
+
+def execute(agent, arg: str) -> tuple[bool, str]:
+    from fp_core.commands import get_all_commands
+
+    cmds = get_all_commands()
+    lines = ["可用命令:"]
+    for c, d in sorted(cmds.items()):
+        lines.append(f"  /{c:11s}  {d}")
+    output = "\n".join(lines)
+
+    # CLI 模式：输出到终端（保持着色）
+    display.info("可用命令:")
+    for c, d in sorted(cmds.items()):
+        display.item(f"  /{c:11s}  {d}")
+
+    # WebUI 模式：通过返回值传递输出
+    return (True, output)

fp_core/commands/history.py

@@ -0,0 +1,32 @@
+"""history 命令 — 查看当前对话历史"""
+
+from fp_core import display
+
+name = "history"
+aliases = []
+description = "查看当前对话历史"
+
+
+def execute(agent, arg: str) -> tuple[bool, str]:
+    history_msgs = agent.history()
+
+    if not history_msgs:
+        display.info("暂无对话历史")
+        return (True, "")
+
+    roles_zh = {"user": "👤 用户", "assistant": "🤖 AI", "tool": "🔧 工具"}
+    display.info(f"\n📜 对话历史（共 {len(history_msgs)} 条）:")
+    print()
+
+    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[:80] + "..." if len(content) > 80 else content
+        else:
+            content = content[:120] + "..." if len(content) > 120 else content
+        content = content.replace("\n", " ")
+        display.item(f"  [{i + 1:3d}] {role}: {content}")
+
+    print()
+    return (True, "📜 历史已显示（终端）")

fp_core/commands/memory_cmd.py

@@ -0,0 +1,30 @@
+"""memory 命令 — 查看持久化记忆"""
+
+import os
+
+from fp_core import config, display
+
+name = "memory"
+aliases = []
+description = "查看持久化记忆"
+
+
+def execute(agent, arg: str) -> tuple[bool, str]:
+    lines = ["📋 记忆列表:", ""]
+    memory_dir = config.MEMORY_DIR
+    if os.path.isdir(memory_dir):
+        for f in sorted(os.listdir(memory_dir)):
+            if f.endswith(".md"):
+                name = f[:-3]
+                lines.append(f"  • {name}")
+    if len(lines) == 2:
+        lines.append("  （暂无记忆）")
+    output = "\n".join(lines)
+    hint = "💡 使用 memory_read / memory_save 工具管理记忆"
+
+    # CLI 模式：保持着色
+    display.info(output)
+    display.hint(hint)
+
+    # WebUI 模式：通过返回值传递
+    return (True, output + "\n" + hint)

fp_core/commands/model.py

@@ -0,0 +1,24 @@
+"""model 命令 — 显示当前模型配置"""
+
+from fp_core import config, display
+
+name = "model"
+aliases = []
+description = "显示当前模型配置"
+
+
+def execute(agent, arg: str) -> tuple[bool, str]:
+    lines = [
+        f"模型:   {agent.model}",
+        f"温度:   {config.LLM_TEMPERATURE}",
+        f"最大 Token: {config.LLM_MAX_TOKENS}",
+        f"会话目录: {config.SESSIONS_DIR}",
+    ]
+    output = "\n".join(lines)
+
+    # CLI 模式
+    for line in lines:
+        display.info(line)
+
+    # WebUI 模式
+    return (True, output)

fp_core/commands/resume.py

@@ -0,0 +1,166 @@
+"""resume 命令 — 切换/删除历史会话（非交互式）
+
+用法:
+  /resume list              列出所有会话
+  /resume latest            切换到最新会话
+  /resume <sid>             切换到指定会话
+  /resume delete list       列出可删除的会话
+  /resume delete <sid>      删除指定会话
+"""
+
+name = "resume"
+aliases = []
+description = "切换/删除历史会话。用法: /resume list, /resume latest, /resume <sid>, /resume delete <sid>"
+
+
+def _display_width(s: str) -> int:
+    """计算字符串的显示宽度（中文=2，英文/数字/符号=1）"""
+    width = 0
+    for c in s:
+        if "\u4e00" <= c <= "\u9fff" or "\u3000" <= c <= "\u303f" or c in "（）":
+            width += 2
+        else:
+            width += 1
+    return width
+
+
+def _pad_to_width(s: str, width: int) -> str:
+    """用空格填充到指定显示宽度"""
+    return s + " " * max(0, width - _display_width(s))
+
+
+async def execute(agent, arg: str) -> tuple[bool, str]:
+    arg = arg.strip()
+
+    # ── /resume delete list ────────────────────────────────────
+    if arg == "delete list":
+        sessions = agent.session.list_sessions()
+        if not sessions:
+            msg = "暂无历史会话"
+            agent.io.info(msg)
+            return (True, msg)
+
+        current_sid = agent.session.session_id
+        sorted_items = sorted(
+            sessions.items(),
+            key=lambda x: x[1].get("updated", ""),
+            reverse=True,
+        )
+
+        deletable = [(sid, meta) for sid, meta in sorted_items if sid != current_sid]
+        if not deletable:
+            msg = "没有可删除的会话（当前会话不可删除）"
+            agent.io.info(msg)
+            return (True, msg)
+
+        summary_width = 44
+        lines = ["🗑️ 可删除的会话（使用 /resume delete <sid> 删除）:"]
+        for i, (sid, meta) in enumerate(deletable, 1):
+            raw_summary = meta.get("summary", "") or ""
+            msg_count = meta.get("message_count", 0)
+            created = meta.get("created", "?")[:16]
+            if not raw_summary:
+                display_summary = "(无摘要)"
+            else:
+                display_summary = ""
+                for ch in raw_summary:
+                    candidate = display_summary + ch
+                    if _display_width(candidate) > summary_width - 1:
+                        display_summary += "…"
+                        break
+                    display_summary = candidate
+            line = f"  [{i}] {_pad_to_width(display_summary, summary_width)} ({msg_count:3d}条, {created})  [{sid}]"
+            lines.append(line)
+
+        agent.io.info(lines[0])
+        for line in lines[1:]:
+            agent.io.item(line)
+
+        return (True, "\n".join(lines))
+
+    # ── /resume delete <sid> ───────────────────────────────────
+    if arg.startswith("delete "):
+        sid = arg[7:].strip()
+        if sid == agent.session.session_id:
+            msg = "❌ 不能删除当前正在使用的会话"
+            agent.io.error(msg)
+            return (True, msg)
+        if agent.delete_session(sid):
+            msg = f"🗑️ 已删除会话: {sid}"
+            agent.io.info(msg)
+            return (True, msg)
+        else:
+            msg = f"❌ 会话 {sid} 不存在或删除失败"
+            agent.io.error(msg)
+            return (True, msg)
+
+    # ── /resume delete (无参数) ─────────────────────────────────
+    if arg == "delete":
+        msg = "❌ 用法: /resume delete list (查看可删除会话) 或 /resume delete <sid> (直接删除)"
+        agent.io.error(msg)
+        return (True, msg)
+
+    # ── /resume list ───────────────────────────────────────────
+    if arg == "list":
+        sessions = agent.session.list_sessions()
+        if not sessions:
+            msg = "暂无历史会话"
+            agent.io.info(msg)
+            return (True, msg)
+
+        current_sid = agent.session.session_id
+        sorted_items = sorted(
+            sessions.items(),
+            key=lambda x: x[1].get("updated", ""),
+            reverse=True,
+        )
+
+        summary_width = 44
+        lines = ["📂 会话列表（使用 /resume <sid> 切换，/resume latest 切换到最新）:"]
+        for i, (sid, meta) in enumerate(sorted_items, 1):
+            raw_summary = meta.get("summary", "") or ""
+            msg_count = meta.get("message_count", 0)
+            marker = "  ⬅" if sid == current_sid else ""
+
+            if not raw_summary:
+                display_summary = "(无摘要)"
+            else:
+                display_summary = ""
+                for ch in raw_summary:
+                    candidate = display_summary + ch
+                    if _display_width(candidate) > summary_width - 1:
+                        display_summary += "…"
+                        break
+                    display_summary = candidate
+
+            line = f"  [{i}] {_pad_to_width(display_summary, summary_width)} ({msg_count:3d}条, {sid}){marker}"
+            lines.append(line)
+
+        agent.io.info(lines[0])
+        for line in lines[1:]:
+            agent.io.item(line)
+
+        return (True, "\n".join(lines))
+
+    # ── /resume latest ─────────────────────────────────────────
+    if arg == "latest":
+        agent.resume_latest()
+        msg = f"📂 已切换到最新会话: {agent.session.session_id}"
+        agent.io.info(msg)
+        return (True, msg)
+
+    # ── /resume <无参数> ────────────────────────────────────────
+    if not arg:
+        msg = "❌ 用法: /resume list (查看列表) | /resume latest | /resume <sid> (直接切换)"
+        agent.io.error(msg)
+        return (True, msg)
+
+    # ── /resume <sid> ──────────────────────────────────────────
+    if agent.switch_session(arg):
+        msg = f"📂 已切换到会话: {arg}"
+        agent.io.info(msg)
+        return (True, msg)
+    else:
+        msg = f"❌ 会话 {arg} 不存在。使用 /resume list 查看可用会话"
+        agent.io.error(msg)
+        return (True, msg)

fp_core/commands/session.py

@@ -0,0 +1,13 @@
+"""session 命令 — 显示当前会话信息"""
+
+from fp_core import display
+
+name = "session"
+aliases = []
+description = "显示当前会话信息"
+
+
+def execute(agent, arg: str) -> tuple[bool, str]:
+    msg = f"📂 当前会话: {agent.session.session_id}"
+    display.info(msg)
+    return (True, msg)