my-pi-agent 0.1.0

package/src/my_agent_core/main.py

@@ -0,0 +1,134 @@
+# pyright: reportUnusedCallResult=false
+"""demo 入口：跑三个固定问题，展示原生异步 ReAct 循环、流式打字机与并发工具执行。
+
+运行：uv run python -m my_agent_core.main（在项目根目录执行，需要 .env 里的 OPENAI_API_KEY）
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import sys
+from datetime import datetime
+from typing import Any
+
+from dotenv import find_dotenv, load_dotenv
+
+from my_agent_core.agent import Agent
+from my_agent_core.events import (
+    AgentEnd,
+    Event,
+    MessageUpdate,
+    ToolExecutionEnd,
+    ToolExecutionStart,
+    TurnStart,
+)
+from my_agent_core.session import SessionStore
+from my_agent_core.tools import tool
+from my_agent_llm import LLM, Config  # pyright: ignore[reportMissingImports]
+
+QUESTIONS = [
+    "Use the multiply tool to calculate 37 times 19.",
+    "What time is it now?",
+    "What's the weather like in Tokyo and Paris?",
+]
+
+
+@tool(is_parallel_safe=True)
+def multiply(a: int, b: int) -> int:
+    """Multiply two integers."""
+    return a * b
+
+
+@tool(is_parallel_safe=True)
+def get_current_time() -> str:
+    """Get the current date and time."""
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+@tool(is_parallel_safe=True)
+def get_weather(city: str) -> str:
+    """Get the weather for a city (simulated data)."""
+    return f"{city}: sunny, 22°C (simulated)"
+
+
+TOOLS = [multiply, get_current_time, get_weather]
+
+# 演示层的系统提示词：my_agent_core 库层没有默认值，
+# 给什么提示词是应用层（本 demo）的选择。
+DEMO_SYSTEM_PROMPT = (
+    "You are a helpful assistant. Use the available tools when they help; "
+    "answer directly when they don't."
+)
+
+
+def print_events(event: Event) -> None:
+    """把循环事件打印成 demo 过程输出（Agent 不内置 print，输出是应用层的选择）。"""
+    if isinstance(event, TurnStart):
+        print(f"\n[round {event.iteration}]")
+    elif isinstance(event, MessageUpdate):
+        # 流式 Token 打字机增量打印
+        if event.chunk and getattr(event.chunk, "content", None):
+            sys.stdout.write(event.chunk.content)
+            sys.stdout.flush()
+    elif isinstance(event, ToolExecutionStart):
+        print(f"\n  [Tool] {event.tool_name}({event.args})")
+    elif isinstance(event, ToolExecutionEnd):
+        print(f"  [Obs] {event.result}")
+    elif isinstance(event, AgentEnd):
+        print(f"\n[End] stop_reason={event.stop_reason}, iterations={event.iterations}")
+    return None  # 纯观察，不干预
+
+
+def build_llm() -> LLM:
+    load_dotenv(find_dotenv(usecwd=True))
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        raise RuntimeError("OPENAI_API_KEY is missing. Add it to .env.")
+    options: dict[str, Any] = {"provider": "openai", "api_key": api_key}
+    if base_url := os.getenv("OPENAI_BASE_URL"):
+        options["base_url"] = base_url
+    if model := os.getenv("OPENAI_MODEL"):
+        options["model"] = model
+    return LLM(config=Config(**options))
+
+
+async def amain() -> None:
+    load_dotenv(find_dotenv(usecwd=True))
+    llm = build_llm()
+    store = SessionStore()  # 默认 workspace=cwd
+    for question in QUESTIONS:
+        print(f"\n{'=' * 20} 问题: {question} {'=' * 20}")
+        session = store.create()
+        agent = Agent(
+            llm=llm,
+            tools=TOOLS,
+            session=session,
+            system_prompt=DEMO_SYSTEM_PROMPT,
+        )
+        agent.subscribe(print_events)
+        answer = await agent.run(question)
+        if answer is None:
+            print("（达到 max_iterations 上限，未得到最终回答）")
+        else:
+            print(f"\n[Answer] {answer}")
+
+
+def _force_utf8_streams() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        if (
+            stream
+            and getattr(stream, "encoding", "").lower().replace("-", "") != "utf8"
+        ):
+            with contextlib.suppress(Exception):
+                stream.reconfigure(encoding="utf-8", errors="replace")  # pyright: ignore[reportAttributeAccessIssue]
+
+
+def main() -> None:
+    _force_utf8_streams()
+    asyncio.run(amain())
+
+
+if __name__ == "__main__":
+    main()

package/src/my_agent_core/memory.py

@@ -0,0 +1,241 @@
+"""MemoryStore - 条目化长期记忆存储与 System Prompt 冻结快照管理。
+
+采用 Markdown 文件（MEMORY.md / USER.md）持久化存储，支持 `\\n§\\n` 条目分隔、
+utf-8-sig 编码容错、唯原子串定位增删改、字符上限约束与原子落盘。
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Literal
+
+from my_agent_core.tools import Tool, tool
+
+ENTRY_DELIMITER = "\n§\n"
+MEMORY_CHAR_LIMIT = 2200
+USER_CHAR_LIMIT = 1375
+
+TargetType = Literal["memory", "user"]
+
+
+class MemoryStore:
+    """管理 MEMORY.md 与 USER.md 的持久化记忆存储仓储（支持 Frozen Snapshot 与原子落盘）。"""
+
+    def __init__(
+        self,
+        mem_dir: Path | str,
+        memory_char_limit: int = MEMORY_CHAR_LIMIT,
+        user_char_limit: int = USER_CHAR_LIMIT,
+    ) -> None:
+        self.mem_dir = Path(mem_dir)
+        self.limits: dict[str, int] = {
+            "memory": memory_char_limit,
+            "user": user_char_limit,
+        }
+        self.files: dict[str, str] = {
+            "memory": "MEMORY.md",
+            "user": "USER.md",
+        }
+        self._entries: dict[str, list[str]] = {"memory": [], "user": []}
+        self._snapshot: dict[str, str] = {"memory": "", "user": ""}
+
+    def load_from_disk(self) -> None:
+        """从磁盘读取 MEMORY.md 和 USER.md，解析并冻结 System Prompt 快照。"""
+        self.mem_dir.mkdir(parents=True, exist_ok=True)
+        for target, filename in self.files.items():
+            path = self.mem_dir / filename
+            entries: list[str] = []
+            if path.exists():
+                try:
+                    content = path.read_text(encoding="utf-8-sig").strip()
+                    if content:
+                        raw_parts = [p.strip() for p in content.split(ENTRY_DELIMITER)]
+                        # 去重且保持插入顺序
+                        entries = list(dict.fromkeys(p for p in raw_parts if p))
+                except Exception:
+                    entries = []
+            self._entries[target] = entries
+            self._snapshot[target] = ENTRY_DELIMITER.join(entries) if entries else ""
+
+    def _atomic_save(self, target: str) -> None:
+        """将指定 target 的 entries 原子写入对应文件。"""
+        self.mem_dir.mkdir(parents=True, exist_ok=True)
+        path = self.mem_dir / self.files[target]
+        text = ENTRY_DELIMITER.join(self._entries[target])
+        tmp_fd, tmp_path = tempfile.mkstemp(
+            prefix=f".{self.files[target]}.", dir=str(self.mem_dir)
+        )
+        try:
+            with os.fdopen(tmp_fd, "w", encoding="utf-8-sig") as f:
+                f.write(text)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp_path, str(path))
+        except Exception:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+            raise
+
+    def add(self, target: str, content: str) -> str:
+        """追加一条记忆条目并落盘。"""
+        if target not in self.files:
+            return f"Invalid target '{target}'. Must be 'memory' or 'user'."
+        text = content.strip()
+        if not text:
+            return "Content cannot be empty."
+
+        entries = self._entries[target]
+        if text in entries:
+            return f"Entry already exists in {target}."
+
+        candidate = entries + [text]
+        full_text = ENTRY_DELIMITER.join(candidate)
+        limit = self.limits[target]
+        if len(full_text) > limit:
+            current_dump = "\n---\n".join(entries) if entries else "(empty)"
+            return (
+                f"Cannot add: total length ({len(full_text)}) exceeds limit ({limit}) for {target}.\n"
+                f"Please consolidate or remove older entries first.\n"
+                f"Current entries:\n{current_dump}"
+            )
+
+        self._entries[target] = candidate
+        self._atomic_save(target)
+        return f"Added to {target} ({len(full_text)}/{limit} chars used)."
+
+    def replace(self, target: str, old_text: str, new_content: str) -> str:
+        """根据 old_text 唯原子串匹配定位替换条目。"""
+        if target not in self.files:
+            return f"Invalid target '{target}'. Must be 'memory' or 'user'."
+        old_needle = old_text.strip()
+        if not old_needle:
+            return "old_text cannot be empty."
+        new_text = new_content.strip()
+        if not new_text:
+            return "new_content cannot be empty."
+
+        entries = self._entries[target]
+        matches = [i for i, entry in enumerate(entries) if old_needle in entry]
+
+        if not matches:
+            return f"Text '{old_needle}' not found in {target}."
+        if len(matches) > 1:
+            matching_texts = "\n---\n".join(entries[i] for i in matches)
+            return (
+                f"Ambiguous match: found {len(matches)} entries matching '{old_needle}' in {target}.\n"
+                f"Please provide a more specific old_text.\nMatching entries:\n{matching_texts}"
+            )
+
+        idx = matches[0]
+        candidate = list(entries)
+        candidate[idx] = new_text
+
+        full_text = ENTRY_DELIMITER.join(candidate)
+        limit = self.limits[target]
+        if len(full_text) > limit:
+            return (
+                f"Cannot replace: total length ({len(full_text)}) exceeds limit ({limit}) for {target}.\n"
+                f"Please consolidate or shorten entries."
+            )
+
+        self._entries[target] = candidate
+        self._atomic_save(target)
+        return f"Replaced in {target} ({len(full_text)}/{limit} chars used)."
+
+    def remove(self, target: str, old_text: str) -> str:
+        """根据 old_text 唯原子串匹配定位删除条目。"""
+        if target not in self.files:
+            return f"Invalid target '{target}'. Must be 'memory' or 'user'."
+        old_needle = old_text.strip()
+        if not old_needle:
+            return "old_text cannot be empty."
+
+        entries = self._entries[target]
+        matches = [i for i, entry in enumerate(entries) if old_needle in entry]
+
+        if not matches:
+            return f"Text '{old_needle}' not found in {target}."
+        if len(matches) > 1:
+            matching_texts = "\n---\n".join(entries[i] for i in matches)
+            return (
+                f"Ambiguous match: found {len(matches)} entries matching '{old_needle}' in {target}.\n"
+                f"Please provide a more specific old_text.\nMatching entries:\n{matching_texts}"
+            )
+
+        idx = matches[0]
+        candidate = [e for i, e in enumerate(entries) if i != idx]
+        self._entries[target] = candidate
+        self._atomic_save(target)
+        limit = self.limits[target]
+        curr_len = len(ENTRY_DELIMITER.join(candidate)) if candidate else 0
+        return f"Removed from {target} ({curr_len}/{limit} chars used)."
+
+    def format_for_system_prompt(self, target: str) -> str | None:
+        """获取冻结的快照字符串（返回 None 代表无内容）。"""
+        snapshot = self._snapshot.get(target, "")
+        return snapshot if snapshot else None
+
+    def format_all_for_system_prompt(self) -> str | None:
+        """将冻结的快照格式化为注入 System Prompt 的 XML 块。"""
+        blocks = []
+        mem = self.format_for_system_prompt("memory")
+        if mem:
+            blocks.append(f"## MEMORY.md (Agent Notes)\n{mem}")
+        usr = self.format_for_system_prompt("user")
+        if usr:
+            blocks.append(f"## USER.md (User Profile)\n{usr}")
+
+        if not blocks:
+            return None
+        joined = "\n\n".join(blocks)
+        return (
+            "<MEMORY_CONTEXT>\n"
+            "The following is your long-term memory across sessions. "
+            "Use the `memory` tool to update it when learning new facts or preferences.\n\n"
+            f"{joined}\n"
+            "</MEMORY_CONTEXT>"
+        )
+
+
+def make_memory_tool(store: MemoryStore) -> Tool:
+    """生成受控的 memory 工具，供 Agent 维护长期记忆（add/replace/remove）。"""
+
+    @tool(
+        name="memory",
+        description=(
+            "Manage long-term memory across sessions. "
+            "Target 'memory' for agent knowledge/notes, 'user' for user preferences/profile. "
+            "Keep entries concise, high-signal, and consolidate when approaching limits."
+        ),
+    )
+    def memory(
+        target: Literal["memory", "user"],
+        action: Literal["add", "replace", "remove"],
+        content: str | None = None,
+        old_text: str | None = None,
+        new_content: str | None = None,
+    ) -> str:
+        """执行记忆的增删改操作。"""
+        if action == "add":
+            if not content:
+                raise ValueError("`content` is required when action is 'add'.")
+            return store.add(target, content)
+        elif action == "replace":
+            if not old_text:
+                raise ValueError("`old_text` is required when action is 'replace'.")
+            effective_new = new_content or content
+            if not effective_new:
+                raise ValueError("`new_content` is required when action is 'replace'.")
+            return store.replace(target, old_text, effective_new)
+        elif action == "remove":
+            if not old_text:
+                raise ValueError("`old_text` is required when action is 'remove'.")
+            return store.remove(target, old_text)
+        else:
+            raise ValueError(
+                f"Unknown action '{action}'. Must be 'add', 'replace', or 'remove'."
+            )
+
+    return memory

package/src/my_agent_core/message_queue.py

@@ -0,0 +1,110 @@
+"""动态干预消息队列 —— 驱动 Pi 风格的 Steer 转向与 Follow-up 追问。"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Literal
+
+
+class MessageType(str, Enum):
+    """排队干预消息类型。"""
+
+    STEERING = "steering"  # 内层循环即时转向（安全点打断）
+    FOLLOWUP = "followup"  # 外层循环排队追问（任务完成后驱动）
+
+
+@dataclass
+class QueuedMessage:
+    """队列中的一条干预消息。"""
+
+    content: str
+    type: MessageType
+    created_at: float = field(default_factory=time.time)
+
+
+class MessageQueue:
+    """管理运行期动态干预消息的队列。"""
+
+    def __init__(
+        self,
+        steering_mode: Literal["one-at-a-time", "all"] = "one-at-a-time",
+        followup_mode: Literal["one-at-a-time", "all"] = "one-at-a-time",
+    ) -> None:
+        self.queue: list[QueuedMessage] = []
+        self.steering_mode = steering_mode
+        self.followup_mode = followup_mode
+
+    def add_steering(self, message: str) -> None:
+        """追加一条 Steering 转向消息。"""
+        self.queue.append(QueuedMessage(content=message, type=MessageType.STEERING))
+
+    def add_followup(self, message: str) -> None:
+        """追加一条 Follow-up 追问消息。"""
+        self.queue.append(QueuedMessage(content=message, type=MessageType.FOLLOWUP))
+
+    def get_steering_messages(self) -> list[QueuedMessage]:
+        """获取并弹出待消费的 steering 消息。"""
+        steering = [m for m in self.queue if m.type == MessageType.STEERING]
+        if not steering:
+            return []
+
+        if self.steering_mode == "one-at-a-time":
+            first = steering[0]
+            self.queue.remove(first)
+            return [first]
+
+        self.queue = [m for m in self.queue if m.type != MessageType.STEERING]
+        return steering
+
+    def get_followup_messages(self) -> list[QueuedMessage]:
+        """获取并弹出待消费的 followup 消息。"""
+        followup = [m for m in self.queue if m.type == MessageType.FOLLOWUP]
+        if not followup:
+            return []
+
+        if self.followup_mode == "one-at-a-time":
+            first = followup[0]
+            self.queue.remove(first)
+            return [first]
+
+        self.queue = [m for m in self.queue if m.type != MessageType.FOLLOWUP]
+        return followup
+
+    def has_steering(self) -> bool:
+        """检查是否存在未决的 steering 消息。"""
+        return any(m.type == MessageType.STEERING for m in self.queue)
+
+    def has_followup(self) -> bool:
+        """检查是否存在未决的 followup 消息。"""
+        return any(m.type == MessageType.FOLLOWUP for m in self.queue)
+
+    def peek(self) -> QueuedMessage | None:
+        """查看队首消息但不弹出。"""
+        return self.queue[0] if self.queue else None
+
+    def clear(self) -> list[QueuedMessage]:
+        """清空队列并返回被清除的消息列表。"""
+        cleared = list(self.queue)
+        self.queue.clear()
+        return cleared
+
+    def get_status(self) -> str:
+        """获取当前队列的可读状态。"""
+        if not self.queue:
+            return "Queue empty"
+        steering_count = sum(1 for m in self.queue if m.type == MessageType.STEERING)
+        followup_count = sum(1 for m in self.queue if m.type == MessageType.FOLLOWUP)
+        parts = []
+        if steering_count:
+            parts.append(f"{steering_count} steering")
+        if followup_count:
+            parts.append(f"{followup_count} follow-up")
+        return f"Queued: {', '.join(parts)}"
+
+    def __len__(self) -> int:
+        return len(self.queue)
+
+    def __bool__(self) -> bool:
+        return len(self.queue) > 0

package/src/my_agent_core/plugins.py

@@ -0,0 +1,212 @@
+"""Claude Code Plugin system - 自包含功能聚合与分发包管理。
+
+对齐 Claude Code 官方 Plugin 标准规范与 OpenHands 实践：
+- Manifest 解析：支持 .claude-plugin/plugin.json 与 .plugin/plugin.json，支持无 manifest 时的目录名推断兜底；
+- 组件目录映射：skills/（或 commands/ 兼容，或根级 SKILL.md 简写）、agents/、.mcp.json；
+- 资源解构与分发：PluginManager 扫描后将解构目录无缝提供给 SkillManager、SubagentManager 及 MCP 客户端。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+PLUGIN_MANIFEST_DIRS = [".claude-plugin", ".plugin"]
+PLUGIN_MANIFEST_FILE = "plugin.json"
+
+
+@dataclass(frozen=True)
+class PluginAuthor:
+    """插件作者信息。支持字符串或字典输入。"""
+
+    name: str
+    email: str | None = None
+    url: str | None = None
+
+    @classmethod
+    def from_value(cls, value: Any) -> PluginAuthor:
+        if isinstance(value, str):
+            m = re.match(r"^(.*?)(?:\s*<([^>]+)>)?$", value.strip())
+            if m:
+                name = m.group(1).strip()
+                email = m.group(2).strip() if m.group(2) else None
+                return cls(name=name, email=email)
+            return cls(name=value)
+        if isinstance(value, dict):
+            return cls(
+                name=value.get("name", ""),
+                email=value.get("email"),
+                url=value.get("url"),
+            )
+        return cls(name="unknown")
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    """插件元数据清单。对齐 Claude Code plugin.json 结构。"""
+
+    name: str
+    version: str = "1.0.0"
+    description: str = ""
+    author: PluginAuthor | None = None
+    homepage: str | None = None
+    repository: str | None = None
+    license: str | None = None
+    keywords: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Plugin:
+    """表示一个已发现的 Claude Code 插件包。"""
+
+    name: str
+    path: Path
+    manifest: PluginManifest
+    enabled: bool = True
+
+    @classmethod
+    def from_directory(cls, plugin_dir: Path | str) -> Plugin:
+        """从目录加载插件，优先查找清单文件，缺失或损坏时按目录名兜底推断。"""
+        p = Path(plugin_dir).resolve()
+        manifest_path = None
+        for m_dir in PLUGIN_MANIFEST_DIRS:
+            candidate = p / m_dir / PLUGIN_MANIFEST_FILE
+            if candidate.is_file():
+                manifest_path = candidate
+                break
+        if manifest_path is None:
+            root_candidate = p / PLUGIN_MANIFEST_FILE
+            if root_candidate.is_file():
+                manifest_path = root_candidate
+
+        if manifest_path:
+            try:
+                data = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
+                author = None
+                if "author" in data:
+                    author = PluginAuthor.from_value(data["author"])
+                manifest = PluginManifest(
+                    name=data.get("name") or p.name,
+                    version=data.get("version", "1.0.0"),
+                    description=data.get("description", ""),
+                    author=author,
+                    homepage=data.get("homepage"),
+                    repository=data.get("repository"),
+                    license=data.get("license"),
+                    keywords=data.get("keywords", []),
+                )
+                return cls(name=manifest.name, path=p, manifest=manifest)
+            except Exception as e:
+                logger.warning(f"Failed to parse manifest at {manifest_path}: {e}")
+
+        # 智能兜底推断（无清单或清单损坏）
+        fallback_manifest = PluginManifest(
+            name=p.name,
+            version="1.0.0",
+            description=f"Plugin loaded from {p.name}",
+        )
+        return cls(name=p.name, path=p, manifest=fallback_manifest)
+
+    @property
+    def skills_dir(self) -> Path | None:
+        """返回技能目录：优先 skills/，次选 commands/，单技能简写直接返回插件根目录。"""
+        skills = self.path / "skills"
+        if skills.is_dir():
+            return skills
+        commands = self.path / "commands"
+        if commands.is_dir():
+            return commands
+        # 官方单 skill 简写：根目录直接有 SKILL.md
+        if (self.path / "SKILL.md").is_file():
+            return self.path
+        return None
+
+    @property
+    def agents_dir(self) -> Path | None:
+        """返回子代理目录 agents/。"""
+        agents = self.path / "agents"
+        return agents if agents.is_dir() else None
+
+    @property
+    def mcp_config_path(self) -> Path | None:
+        """返回 MCP 配置文件路径 .mcp.json。"""
+        mcp = self.path / ".mcp.json"
+        return mcp if mcp.is_file() else None
+
+
+class PluginManager:
+    """管理 Claude Code 格式插件的发现、解析与子资源目录解构提取。"""
+
+    def __init__(self, dirs: Sequence[str | Path] | None = None) -> None:
+        """构造即发现：None → 探测 <cwd>/.agents/plugins；[] → 禁用；非空 → 显式目录。"""
+        self.plugins: dict[str, Plugin] = {}
+        if dirs is None:
+            default_dir = Path.cwd() / ".agents" / "plugins"
+            if default_dir.is_dir():
+                self._discover_from_dir(default_dir)
+        elif dirs:
+            for d in dirs:
+                p = Path(d).resolve()
+                if p.is_dir():
+                    if self._is_single_plugin(p):
+                        self._load_one_plugin(p)
+                    else:
+                        self._discover_from_dir(p)
+
+    def _is_single_plugin(self, p: Path) -> bool:
+        """判断是否为单个插件的根目录。"""
+        for m_dir in PLUGIN_MANIFEST_DIRS:
+            if (p / m_dir / PLUGIN_MANIFEST_FILE).is_file():
+                return True
+        if (p / PLUGIN_MANIFEST_FILE).is_file():
+            return True
+        return (
+            (p / "skills").is_dir()
+            or (p / "agents").is_dir()
+            or (p / "commands").is_dir()
+            or (p / "SKILL.md").is_file()
+        )
+
+    def _load_one_plugin(self, p: Path) -> None:
+        """安全加载单个插件，隔离异常。"""
+        try:
+            plugin = Plugin.from_directory(p)
+            self.plugins[plugin.name] = plugin
+        except Exception as e:
+            logger.warning(f"Failed to load plugin from {p}: {e}")
+
+    def _discover_from_dir(self, root: Path) -> None:
+        """扫描目录下的直接子目录。"""
+        try:
+            for item in sorted(root.iterdir()):
+                if item.is_dir() and not item.name.startswith((".", "_")):
+                    self._load_one_plugin(item)
+        except Exception as e:
+            logger.warning(f"Failed to discover plugins from {root}: {e}")
+
+    def get_skill_dirs(self) -> list[Path]:
+        """收集所有启用插件的 skills 目录。"""
+        return [
+            p.skills_dir for p in self.plugins.values() if p.enabled and p.skills_dir
+        ]
+
+    def get_subagent_dirs(self) -> list[Path]:
+        """收集所有启用插件的 agents 目录。"""
+        return [
+            p.agents_dir for p in self.plugins.values() if p.enabled and p.agents_dir
+        ]
+
+    def get_mcp_config_paths(self) -> list[Path]:
+        """收集所有启用插件的 .mcp.json 配置文件路径。"""
+        return [
+            p.mcp_config_path
+            for p in self.plugins.values()
+            if p.enabled and p.mcp_config_path
+        ]