planify 1.0.0__py3-none-any.whl

planify/__init__.py

@@ -0,0 +1,7 @@
+"""重构的代理系统
+
+具有分离关注点的模块化代理系统。
+原始实现：agents/s_full.py
+"""
+
+__version__ = "1.0.0"

planify/agent/__init__.py

@@ -0,0 +1,5 @@
+"""代理模块。"""
+
+from .runner import Agent, run_agent_loop
+
+__all__ = ["Agent", "run_agent_loop"]

planify/agent/runner.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+代理运行器 - 核心代理循环 (s01)
+
+提供代理主循环和系统提示词生成。
+持续调用 LLM 并执行工具，直到模型停止调用工具。
+支持多用户多会话架构。
+"""
+
+import asyncio
+import dataclasses
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..core.llm.types import TextBlock, Tool, ToolUseBlock
+
+
+class Agent:
+    """
+    代理类 - 管理代理状态和执行循环。
+
+    代理循环包含：
+    1. 微压缩 (s06) - 清理旧的 tool_result
+    2. 自动压缩检查 (s06) - 超过阈值时压缩上下文
+    3. 后台通知处理 (s08) - 获取已完成的后台任务
+    4. 收件箱检查 (s09) - 读取队友消息
+    5. LLM 调用
+    6. 工具执行
+    7. Todo 提醒检查 (s03) - 3 轮未更新后提醒
+
+    关键洞察："整个秘密就是一个模式：while stop_reason == 'tool_use'"
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        model: str,
+        tools: List[Dict],
+        tool_handlers: Dict[str, Any],
+        todo_manager: Any,
+        bg_manager: Any,
+        bus: Any,
+        skills_loader: Any,
+        config: Dict[str, Any],
+        logger: Any,
+        runtime: Optional[Any] = None,
+        tool_callback: Optional[callable] = None,
+        tool_result_callback: Optional[callable] = None,
+        system_prompt_extra: Optional[str] = None,
+    ):
+        """
+        初始化代理。
+
+        Args:
+            client: Anthropic API 客户端
+            model: 模型名称
+            tools: 工具定义列表
+            tool_handlers: 工具处理器字典
+            todo_manager: Todo 管理器
+            bg_manager: 后台管理器
+            bus: 消息总线
+            skills_loader: 技能加载器
+            config: 配置字典
+            logger: 日志记录器
+            runtime: AgentRuntime 实例（可选）
+            tool_callback: 工具调用回调函数 (name, args) -> None
+            tool_result_callback: 工具结果回调函数 (name, result) -> None
+            system_prompt_extra: 宿主应用注入的额外 system prompt 段（可选）
+        """
+        # provider 是 client 的别名（LLMProvider 抽象接口），
+        # 所有调用点（包括 compact）已迁移完成。
+        self.provider = client
+        self.model = model
+        self.tools = tools
+        self.tool_handlers = tool_handlers
+        self.todo_mgr = todo_manager
+        self.bg_manager = bg_manager
+        self.bus = bus
+        self.skills = skills_loader
+        self.config = config
+        self.logger = logger
+        self.runtime = runtime
+        self.tool_callback = tool_callback
+        self.tool_result_callback = tool_result_callback
+        self._system_prompt_extra = system_prompt_extra
+
+        # 延迟导入以避免循环依赖（使用相对导入）
+        from ..context import estimate_tokens, microcompact, auto_compact
+        from ..context.compact import MICROCOMPACT_GATE_RATIO
+        from ..prompts import SystemPromptBuilder
+
+        self._estimate_tokens = estimate_tokens
+        self._microcompact = microcompact
+        self._auto_compact = auto_compact
+        self._microcompact_gate_ratio = MICROCOMPACT_GATE_RATIO
+        self._prompt_builder = SystemPromptBuilder()
+
+    def get_system_prompt(self) -> str:
+        """
+        获取系统提示词。
+
+        Returns:
+            系统提示词字符串
+        """
+        workdir = self.config.get("workdir", ".")
+        return self._prompt_builder.get(
+            workdir, agent_type="agent", extra_prompt=self._system_prompt_extra
+        )
+
+    def run(self, messages: List[Dict]) -> None:
+        """
+        运行代理循环。
+
+        Args:
+            messages: 消息历史列表（将被就地修改）
+        """
+        system = self.get_system_prompt()
+        rounds_without_todo = 0
+        loop_count = 0
+
+        while True:
+            loop_count += 1
+
+            # === 日志记录 ===
+            try:
+                msg_json = json.dumps(messages[-3:], ensure_ascii=False, default=str)
+                self.logger.info(f"[LLM Call #{loop_count}] Input messages: {msg_json}")
+            except Exception:
+                self.logger.info(f"[LLM Call #{loop_count}] Input messages: (encoding error)")
+
+            # === s06: 压缩管道 ===
+            # 缓存友好：清理推迟到逼近 auto_compact 阈值（默认 80%）才触发，
+            # 避免历史中段单点突变打废整体前缀缓存（国产端点双倍代价）
+            self._microcompact(
+                messages,
+                min_estimated_tokens=int(
+                    self.config["token_threshold"] * self._microcompact_gate_ratio
+                ),
+            )
+            if self._estimate_tokens(messages) > self.config["token_threshold"]:
+                # 压缩 transcript 目录：注意 config["transcript_dir"] 是
+                # .planify/transcript.json 文件路径（语义不符），统一用
+                # <workdir>/.transcripts/
+                transcript_dir = Path(self.config.get("workdir", ".")) / ".transcripts"
+                compacted = self._auto_compact(messages, self.provider, transcript_dir)
+
+                # 本地列表必须就地替换（runtime 路径下两者可能是不同列表）；
+                # 若本就是同一列表，二次替换幂等无害
+                messages[:] = compacted
+                if self.runtime:
+                    self.runtime.replace_messages_in_place(compacted)
+
+            # === s08: 后台通知 ===
+            notifs = self.bg_manager.drain()
+            if notifs:
+                txt = "\n".join(
+                    f"[bg:{n['task_id']}] {n['status']}: {n['result']}"
+                    for n in notifs
+                )
+                messages.append({
+                    "role": "user",
+                    "content": f"<background-results>\n{txt}\n</background-results>"
+                })
+                messages.append({
+                    "role": "assistant",
+                    "content": "Noted background results."
+                })
+
+            # === s09: 检查 lead 收件箱 ===
+            inbox = self.bus.read_inbox("lead")
+            if inbox:
+                messages.append({
+                    "role": "user",
+                    "content": f"<inbox>{json.dumps(inbox, indent=2)}</inbox>"
+                })
+                messages.append({
+                    "role": "assistant",
+                    "content": "Noted inbox messages."
+                })
+
+            # === LLM 调用 ===
+            response = self.provider.chat(
+                messages=messages,
+                system=system,
+                tools=[
+                    Tool(
+                        name=t["name"],
+                        description=t.get("description", ""),
+                        input_schema=t.get("input_schema", {"type": "object"}),
+                    )
+                    for t in self.tools
+                ],
+                max_tokens=8000,
+            )
+
+            # === 记录响应 ===
+            self.logger.info(f"[LLM Call #{loop_count}] Stop reason: {response.stop_reason}")
+            try:
+                resp_json = json.dumps(
+                    [b.model_dump() if hasattr(b, 'model_dump') else str(b) for b in response.content],
+                    ensure_ascii=False
+                )
+                self.logger.debug(f"[LLM Call #{loop_count}] Response: {resp_json[:2000]}")
+            except Exception:
+                self.logger.debug(f"[LLM Call #{loop_count}] Response: (encoding error)")
+
+            messages.append({
+                "role": "assistant",
+                "content": [
+                    b if isinstance(b, dict) else dataclasses.asdict(b)
+                    for b in response.content
+                ],
+            })
+            if response.stop_reason != "tool_use":
+                return
+
+            # === 工具执行 ===
+            results = []
+            used_todo = False
+            manual_compress = False
+
+            for block in response.content:
+                if isinstance(block, ToolUseBlock) or (
+                    isinstance(block, dict) and block.get("type") == "tool_use"
+                ):
+                    # 触发工具调用回调（用于 CLI 输出）
+                    if self.tool_callback:
+                        try:
+                            self.tool_callback(block.name, block.input)
+                        except Exception as e:
+                            self.logger.debug(f"tool_callback 失败: {block.name}, {e}")
+
+                    # 记录工具调用
+                    try:
+                        input_json = json.dumps(block.input, ensure_ascii=False)
+                        self.logger.info(f"[Tool Call] {block.name} | Input: {input_json}")
+                    except Exception:
+                        self.logger.info(f"[Tool Call] {block.name} | Input: (encoding error)")
+
+                    # 检测手动压缩请求
+                    if block.name == "compress":
+                        manual_compress = True
+
+                    # 执行工具
+                    handler = self.tool_handlers.get(block.name)
+                    try:
+                        if handler:
+                            if asyncio.iscoroutinefunction(handler):
+                                output = asyncio.run(handler(**block.input))
+                            else:
+                                output = handler(**block.input)
+                        else:
+                            output = f"Unknown tool: {block.name}"
+                    except Exception as e:
+                        output = f"Error: {e}"
+
+                    # 记录工具结果
+                    try:
+                        output_str = str(output)
+                        self.logger.info(f"[Tool Result] {block.name} | Output: {output_str[:500]}")
+                    except Exception:
+                        self.logger.info(f"[Tool Result] {block.name} | Output: (encoding error)")
+
+                    # 触发工具结果回调
+                    if self.tool_result_callback:
+                        try:
+                            self.tool_result_callback(block.name, str(output))
+                        except Exception as e:
+                            self.logger.debug(f"tool_result_callback 失败: {block.name}, {e}")
+
+                    results.append({
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": str(output)
+                    })
+
+                    if block.name == "TodoWrite":
+                        used_todo = True
+
+            # === s03: Todo 提醒 ===
+            rounds_without_todo = 0 if used_todo else rounds_without_todo + 1
+            if self.todo_mgr.has_open_items() and rounds_without_todo >= 3:
+                results.insert(0, {"type": "text", "text": "<reminder>Update your todos.</reminder>"})
+
+            messages.append({"role": "user", "content": results})
+
+            # === s06: 手动压缩 ===
+            if manual_compress:
+                transcript_dir = Path(self.config.get("workdir", ".")) / ".transcripts"
+                compacted = self._auto_compact(messages, self.provider, transcript_dir)
+
+                # 同上：本地列表 + runtime 双写（同一列表时幂等）
+                messages[:] = compacted
+                if self.runtime:
+                    self.runtime.replace_messages_in_place(compacted)
+
+    @property
+    def has_runtime(self) -> bool:
+        """是否绑定了 AgentRuntime"""
+        return self.runtime is not None
+
+
+def run_agent_loop(
+    messages: List[Dict],
+    client: Any,
+    model: str,
+    tools: List[Dict],
+    tool_handlers: Dict[str, Any],
+    todo_manager: Any,
+    bg_manager: Any,
+    bus: Any,
+    skills_loader: Any,
+    config: Dict[str, Any],
+    logger: Any,
+    runtime: Optional[Any] = None,
+    tool_callback: Optional[callable] = None,
+    tool_result_callback: Optional[callable] = None,
+) -> None:
+    """
+    运行代理循环（函数式接口）。
+
+    此函数持续调用 LLM 并执行工具，直到模型停止调用工具。
+
+    Args:
+        messages: 消息历史列表（将被就地修改）
+        client: Anthropic API 客户端
+        model: 模型名称
+        tools: 工具定义列表
+        tool_handlers: 工具处理器字典
+        todo_manager: Todo 管理器
+        bg_manager: 后台管理器
+        bus: 消息总线
+        skills_loader: 技能加载器
+        config: 配置字典
+        logger: 日志记录器
+        runtime: AgentRuntime 实例（可选）
+        tool_callback: 工具调用回调函数 (name, args) -> None
+        tool_result_callback: 工具结果回调函数 (name, result) -> None
+    """
+    agent = Agent(
+        client=client,
+        model=model,
+        tools=tools,
+        tool_handlers=tool_handlers,
+        todo_manager=todo_manager,
+        bg_manager=bg_manager,
+        bus=bus,
+        skills_loader=skills_loader,
+        config=config,
+        logger=logger,
+        runtime=runtime,
+        tool_callback=tool_callback,
+        tool_result_callback=tool_result_callback,
+    )
+    agent.run(messages)

planify/bootstrap.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+应用初始化模块
+
+负责初始化 RuntimeManager 并提供运行时（AgentRuntime）管理接口。
+不再使用全局单例模式，支持多用户并发访问。
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .core import RuntimeManager, get_config, get_user_config_dict
+from .subagent.runner import run_subagent
+
+
+# RuntimeManager 单例（通过 get_instance() 访问）
+_manager: Optional[RuntimeManager] = None
+
+# Planify 配置注册表（由主应用注入）
+_registered_config: Dict[str, Any] = {}
+
+
+# ============================================================================
+# 主应用依赖注册
+# ============================================================================
+
+def register_app_dependencies(
+    external_tools=None,
+    external_handlers=None,
+) -> None:
+    """
+    注册主应用（FastAPI backend）提供的外部工具。
+
+    当 third_party.planify 作为独立模块被主应用集成时，
+    主应用通过此函数注册其提供的工具。
+
+    Args:
+        external_tools: 外部工具定义列表
+        external_handlers: 外部工具处理器字典
+    """
+    if external_tools or external_handlers:
+        from .tools.registry import register_external_tools
+        register_external_tools(
+            tools=external_tools or [],
+            handlers=external_handlers or {},
+        )
+        print("已注册外部工具")
+
+
+def register_planify_config(
+    api_key: str = "",
+    model_id: str = "claude-opus-4-6",
+    base_url: str = "",
+    protocol: str = "",
+    baidu_weather_api_url: str = "https://api.map.baidu.com/weather/v1/",
+    baidu_weather_ak: str = "",
+    baidu_weather_data_type: str = "fc",
+    **extra: Any,
+) -> None:
+    """
+    注册 Planify 配置（由主应用在启动时调用）。
+
+    配置优先级：
+    1. 通过此函数注册的配置（最高）
+    2. 环境变量
+    3. 默认值
+
+    Args:
+        api_key: LLM Provider API Key
+        model_id: 模型 ID
+        base_url: API 端点（留空则用 SDK 默认）
+        protocol: 协议类型（"anthropic" / "openai_compat"，默认 "anthropic"）
+        baidu_weather_api_url: 百度天气 API URL
+        baidu_weather_ak: 百度天气 AK
+        baidu_weather_data_type: 百度天气数据类型
+        **extra: 其他额外配置项
+    """
+    global _registered_config
+    _registered_config = {
+        "api_key": api_key,
+        "model_id": model_id,
+        "base_url": base_url,
+        "protocol": protocol,
+        "baidu_weather_api_url": baidu_weather_api_url,
+        "baidu_weather_ak": baidu_weather_ak,
+        "baidu_weather_data_type": baidu_weather_data_type,
+        **extra,
+    }
+
+    # 将配置同步到 core/config.py，使其对 RuntimeManager 可见
+    from .core.config import register_config
+    register_config(_registered_config)
+
+    print("已注册 Planify 配置")
+
+
+def get_registered_config() -> Dict[str, Any]:
+    """获取已注册的 Planify 配置"""
+    return _registered_config
+
+
+def get_manager() -> RuntimeManager:
+    """
+    获取 RuntimeManager 单例实例。
+
+    Returns:
+        RuntimeManager 实例
+
+    Raises:
+        RuntimeError: 如果应用尚未初始化
+    """
+    global _manager
+    if _manager is None:
+        raise RuntimeError("应用尚未初始化。请先调用 initialize()。")
+    return _manager
+
+
+def initialize(base_workdir: Optional[Path] = None) -> RuntimeManager:
+    """
+    初始化应用并返回 RuntimeManager 单例。
+
+    此函数创建 RuntimeManager 单例，用于管理所有用户运行时。
+    在初始化时自动检查并迁移旧的多会话数据。
+
+    Args:
+        base_workdir: 基础工作目录（默认为当前目录）
+
+    Returns:
+        RuntimeManager 实例
+    """
+    global _manager
+
+    if _manager is not None:
+        return _manager
+
+    if base_workdir is None:
+        base_workdir = Path.cwd()
+
+    _manager = RuntimeManager(base_workdir)
+
+    # 自动检查并迁移数据
+    print("检查并迁移用户数据...")
+    migration_results = _manager.check_and_migrate_all_users()
+    successful_migrations = sum(1 for result in migration_results.values() if result)
+    if successful_migrations > 0:
+        print(f"成功迁移 {successful_migrations} 个用户的数据")
+    else:
+        print("没有需要迁移的数据")
+
+    return _manager
+
+
+def reset():
+    """
+    重置应用状态（主要用于测试）。
+
+    清除 RuntimeManager 单例，允许重新初始化。
+    """
+    global _manager
+    _manager = None
+    RuntimeManager.reset()
+
+
+# ============================================================================
+# 简化的运行时管理 API
+# ============================================================================
+
+def get_or_create_runtime(user_id: str, user_config: dict, **overrides):
+    """
+    获取或创建用户的默认运行时。
+
+    每个用户只有一个默认运行时，如果不存在则自动创建。
+
+    Args:
+        user_id: 用户 ID
+        user_config: 用户配置字典
+        **overrides: 覆盖配置的额外参数
+
+    Returns:
+        AgentRuntime 实例
+    """
+    manager = get_manager()
+    runtime = manager.get_or_create_runtime(user_id, user_config, **overrides)
+    manager.initialize_runtime_components(runtime)
+
+    # 设置子代理处理器（使用运行时隔离的工作目录）
+    from .tools import handle_task
+    runtime.tool_handlers["task"] = lambda **kw: handle_task(
+        kw["prompt"],
+        kw.get("agent_type", "Explore"),
+        runtime.config.workdir,
+        runtime.client,
+        runtime.model,
+        runtime.tool_handlers,
+        run_subagent=run_subagent,
+        runtime=runtime
+    )
+
+    return runtime
+
+
+def list_all_runtimes():
+    """
+    列出所有运行时。
+
+    Returns:
+        所有活跃运行时列表
+    """
+    manager = get_manager()
+    return manager.list_all_runtimes()
+
+
+# ============================================================================
+# 简化的运行时管理 API（别名）
+# ============================================================================
+
+def get_runtime_simple(user_id: str):
+    """
+    获取用户的默认运行时。
+
+    Args:
+        user_id: 用户 ID
+
+    Returns:
+        AgentRuntime 实例，如果不存在则返回 None
+    """
+    manager = get_manager()
+    return manager.get_runtime_simple(user_id)
+
+
+def close_runtime_simple(user_id: str) -> bool:
+    """
+    关闭并移除用户的默认运行时。
+
+    Args:
+        user_id: 用户 ID
+
+    Returns:
+        是否成功关闭
+    """
+    manager = get_manager()
+    return manager.close_runtime(user_id)
+
+
+# ============================================================================
+# 向后兼容：旧的 API 接口（单用户模式）
+# ============================================================================
+
+# 这些全局变量仅用于向后兼容，不推荐在新代码中使用
+config = None
+logger = None
+client = None
+todo_mgr = None
+task_mgr = None
+bg_mgr = None
+bus = None
+team = None
+skills = None
+tools = None
+tool_handlers = None
+workdir = None
+model = None
+token_threshold = None
+
+
+def init_legacy_runtime(user_id: str = "default", session_id: str = "default"):
+    """
+    初始化旧版单用户模式的运行时（向后兼容）。
+
+    此函数创建一个运行时并将其组件同步到全局变量。
+
+    现在使用新的简化 API 自动创建用户的默认运行时。
+
+    Args:
+        user_id: 用户 ID
+        session_id: 会话 ID（已废弃，保留参数以兼容）
+    """
+    global config, logger, client
+    global todo_mgr, task_mgr, bg_mgr, bus, team, skills
+    global tools, tool_handlers, workdir, model, token_threshold
+
+    # 使用新的简化 API 创建默认运行时
+    app_config = get_config()
+    runtime = get_or_create_runtime(
+        user_id,
+        user_config=get_user_config_dict(
+            model_id=app_config.get("model_id"),
+            api_key=app_config.get("api_key"),
+            base_url=app_config.get("base_url"),
+            token_threshold=app_config.get("token_threshold"),
+            poll_interval=app_config.get("poll_interval"),
+            idle_timeout=app_config.get("idle_timeout"),
+        )
+    )
+
+    # 同步到全局变量
+    config = runtime.config
+    logger = runtime.logger
+    client = runtime.client
+    todo_mgr = runtime.todo_mgr
+    task_mgr = runtime.task_mgr
+    bg_mgr = runtime.bg_mgr
+    bus = runtime.bus
+    team = runtime.team
+    skills = runtime.skills
+    tools = runtime.tools
+    tool_handlers = runtime.tool_handlers
+    workdir = runtime.config.workdir
+    model = runtime.model
+    token_threshold = runtime.token_threshold
+
+    return runtime