langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/tools/agent/built_in/verification.py

@@ -0,0 +1,120 @@
+"""
+tools/agent/built_in/verification.py — Verification 内置类型
+
+职责：定义验证型 subagent，用于代码/配置核验，不承载执行逻辑。
+在整体链路中的位置：builtin_subagent_loader 在 LANGCHAIN_AGENTX_BUILTIN_VERIFICATION 时调用 register()。
+CC 对照：src/tools/AgentTool/built-in/verificationAgent.ts。
+当前裁剪范围：v3 对齐“强验证”语义，强调证据驱动与只读边界。
+
+典型使用场景：
+1) 非 trivial 改动完成后，需要独立验证正确性与回归风险；
+2) 需要明确 PASS/FAIL/PARTIAL 结论并附命令证据；
+3) 需要尝试边界/异常/对抗输入，而非仅走 happy path。
+"""
+
+from __future__ import annotations
+
+from ..registry.config import SubagentConfig
+from ..registry.registry import SubagentRegistry
+
+_DISALLOWED = frozenset({"Agent", "agent", "Edit", "Write", "NotebookEdit"})
+
+_SYSTEM_PROMPT = """You are a verification specialist. Your job is not to confirm the \
+implementation works — it's to try to break it.
+
+You have two documented failure patterns. First, verification avoidance: when faced with \
+a check, you find reasons not to run it — you read code, narrate what you would test, \
+write "PASS," and move on. Second, being seduced by the first 80%: you see passing tests \
+and feel inclined to pass it, not noticing half the paths do nothing or the backend crashes \
+on bad input. Your entire value is in finding the last 20%.
+
+=== CRITICAL: DO NOT MODIFY THE PROJECT ===
+You are STRICTLY PROHIBITED from:
+- Creating, modifying, or deleting any files IN THE PROJECT DIRECTORY
+- Installing dependencies or packages
+- Running git write operations (add, commit, push)
+
+You MAY write ephemeral test scripts to /tmp when inline commands aren't sufficient. \
+Clean up after yourself.
+
+=== VERIFICATION STRATEGY ===
+Adapt your strategy based on what was changed:
+
+**Backend/API changes**: Start server → curl/fetch endpoints → verify response shapes \
+against expected values (not just status codes) → test error handling → check edge cases
+**CLI/script changes**: Run with representative inputs → verify stdout/stderr/exit codes \
+→ test edge inputs (empty, malformed, boundary) → verify --help output is accurate
+**Library/package changes**: Build → full test suite → import and exercise the public API \
+as a consumer would → verify exported interfaces match docs
+**Bug fixes**: Reproduce the original bug → verify fix → run regression tests → check \
+related functionality for side effects
+**Refactoring (no behavior change)**: Existing test suite MUST pass unchanged → diff the \
+public API surface → spot-check observable behavior is identical (same inputs → same outputs)
+**Other change types**: (a) figure out how to exercise this change directly, \
+(b) check outputs against expectations, (c) try to break it with inputs the implementer didn't test.
+
+=== REQUIRED STEPS (universal baseline) ===
+1. Read CLAUDE.md / README for build/test commands. Check pyproject.toml / Makefile for script names.
+2. Run the build (if applicable). A broken build is an automatic FAIL.
+3. Run the project's test suite. Failing tests are an automatic FAIL.
+4. Run linters/type-checkers if configured (mypy, ruff, etc.).
+5. Check for regressions in related code.
+
+Then apply the type-specific strategy above.
+
+=== ADVERSARIAL PROBES ===
+Functional tests confirm the happy path. Also try to break it:
+- **Boundary values**: 0, -1, empty string, very long strings, unicode
+- **Idempotency**: same mutating request twice — duplicate created? correct no-op?
+- **Orphan operations**: reference IDs/paths that don't exist
+- **Concurrency** (where applicable): parallel requests to shared state
+
+=== RECOGNIZE YOUR OWN RATIONALIZATIONS ===
+- "The code looks correct based on my reading" — reading is not verification. Run it.
+- "The implementer's tests already pass" — verify independently.
+- "This is probably fine" — probably is not verified. Run it.
+If you catch yourself writing an explanation instead of a command, stop. Run the command.
+
+=== OUTPUT FORMAT (REQUIRED) ===
+Every check MUST follow this structure:
+
+```
+### Check: [what you're verifying]
+**Command run:**
+  [exact command you executed]
+**Output observed:**
+  [actual terminal output — copy-paste, not paraphrased]
+**Result: PASS** (or FAIL — with Expected vs Actual)
+```
+
+End with exactly one of:
+VERDICT: PASS
+VERDICT: FAIL
+VERDICT: PARTIAL
+
+PARTIAL is for environmental limitations only (tool unavailable, server can't start) — \
+not for "I'm unsure." Use the literal string `VERDICT: ` followed by exactly one of \
+`PASS`, `FAIL`, `PARTIAL`. No markdown, no punctuation, no variation."""
+
+
+def _verification_tool_filter(all_tools: list) -> list:
+    return [t for t in all_tools if getattr(t, "name", "") not in _DISALLOWED]
+
+VERIFICATION_AGENT = SubagentConfig(
+    name="verification",
+    description="Verification-focused agent for tests, assertions, and regression checks.",
+    when_to_use=(
+        "Use this agent to independently verify non-trivial changes after implementation. "
+        "It runs tests, checks regressions, and tries to break the implementation with "
+        "boundary/adversarial inputs. Returns a PASS/FAIL/PARTIAL verdict with command evidence."
+    ),
+    system_prompt_factory=lambda: _SYSTEM_PROMPT,
+    tool_filter=_verification_tool_filter,
+    tools_description="All tools except Agent/Edit/Write/NotebookEdit",
+    default_max_steps=None,
+    allow_async=False,
+    tags={"verification", "testing"},
+)
+
+def register(registry: SubagentRegistry) -> None:
+    registry.register(VERIFICATION_AGENT)

langchain_agentx/tools/agent/builtin_subagent_loader.py

@@ -0,0 +1,89 @@
+"""
+tools/agent/builtin_subagent_loader.py — 内置 subagent 的环境驱动装载
+
+职责：按环境变量解析是否装载各 built_in 子模块，并写入调用方提供的 SubagentRegistry；
+      提供进程内懒单例供 AgentRuntimeTool(registry=None)。
+在整体链路中的位置：AgentRuntimeTool → BuiltinSubagentEnvLoader / DefaultSubagentRegistryProvider；
+      built_in/ 仅保留 SubagentConfig 与各模块 register()，不包含装载策略。
+CC 对照：CC 以环境变量控制内置能力；本模块为显式 OOP 装载入口。
+
+环境变量（truthy：1/true/yes/on，大小写不敏感）：
+- LANGCHAIN_AGENTX_BUILTIN_SUBAGENTS_DISABLED — 总闸：为真时不注册任何 built-in。
+- LANGCHAIN_AGENTX_CLI — CLI 宿主；与 BUILTIN_STATUSLINE 同时为真才注册 statusline-setup。
+- LANGCHAIN_AGENTX_BUILTIN_STATUSLINE / AGENTX_GUIDE / VERIFICATION — 可选增量。
+总闸未关时固定注册：general-purpose、Explore、Plan。
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from collections.abc import Mapping
+from typing import ClassVar
+
+from .registry.registry import SubagentRegistry
+
+
+class BuiltinSubagentEnvLoader:
+    """读取环境变量，将内置 subagent 注册到已有 SubagentRegistry。"""
+
+    def __init__(self, environ: Mapping[str, str] | None = None) -> None:
+        self._environ: Mapping[str, str] = environ if environ is not None else os.environ
+
+    @staticmethod
+    def _truthy(raw: str | None) -> bool:
+        if raw is None:
+            return False
+        return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+    def _env_flag(self, name: str) -> bool:
+        return self._truthy(self._environ.get(name))
+
+    def subagents_disabled(self) -> bool:
+        return self._env_flag("LANGCHAIN_AGENTX_BUILTIN_SUBAGENTS_DISABLED")
+
+    def load_into(self, registry: SubagentRegistry) -> None:
+        if self.subagents_disabled():
+            return
+
+        from .built_in import explore, general, plan
+
+        general.register(registry)
+        explore.register(registry)
+        plan.register(registry)
+
+        if self._env_flag("LANGCHAIN_AGENTX_BUILTIN_VERIFICATION"):
+            from .built_in import verification
+
+            verification.register(registry)
+        if self._env_flag("LANGCHAIN_AGENTX_BUILTIN_AGENTX_GUIDE"):
+            from .built_in import agentx_guide
+
+            agentx_guide.register(registry)
+        if self._env_flag("LANGCHAIN_AGENTX_BUILTIN_STATUSLINE") and self._env_flag(
+            "LANGCHAIN_AGENTX_CLI"
+        ):
+            from .built_in import statusline_setup
+
+            statusline_setup.register(registry)
+
+
+class DefaultSubagentRegistryProvider:
+    """进程内懒单例：首次访问时用 BuiltinSubagentEnvLoader 填充 SubagentRegistry。"""
+
+    _registry: ClassVar[SubagentRegistry | None] = None
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    @classmethod
+    def get(cls) -> SubagentRegistry:
+        with cls._lock:
+            if cls._registry is None:
+                cls._registry = SubagentRegistry()
+                BuiltinSubagentEnvLoader().load_into(cls._registry)
+            return cls._registry
+
+    @classmethod
+    def reset_for_tests(cls) -> None:
+        """仅测试：释放单例以便 monkeypatch 环境后重新装载。"""
+        with cls._lock:
+            cls._registry = None

langchain_agentx/tools/agent/cwd_resolution.py

@@ -0,0 +1,119 @@
+"""
+tools/agent/cwd_resolution.py — Agent 工具 cwd 展开与 workspace 校验
+
+职责：
+    将可选 ``cwd`` 展开为绝对路径（``normalize_user_path_string_for_expand`` + ``expand_path``），
+    并校验落在 ``workspace_root`` 内、目录存在；UNC 不做本地 ``isdir``（与 Grep/Read 一致）。
+链路位置：
+    ``AgentRuntimeTool.validate_input``（成功时写回 ``data["cwd"]`` 供 ``invoke`` 使用）。
+当前裁剪：
+    不替代全局 PolicyEngine；仅语义校验层中文消息。无 ``workspace_root`` 时以 ``get_cwd()`` 为展开基准，
+    且不做「必须在 workspace 内」校验（与测试桩及旧编排兼容）。
+CC 对照：
+    ``AgentTool.tsx`` cwd 描述（Absolute path）；``utils/path.ts`` ``expandPath``。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from langchain_agentx.tool_runtime.models import ValidationResult
+from langchain_agentx.utils.cwd import expand_path, get_cwd
+from langchain_agentx.utils.path_user_input import normalize_user_path_string_for_expand
+from langchain_agentx.utils.unc_path import is_unc_path_skip_local_stat
+from langchain_agentx.utils.win_reserved_paths import path_uses_windows_reserved_name
+
+
+def _path_is_descendant(candidate: Path, ancestor: Path) -> bool:
+    try:
+        candidate.relative_to(ancestor)
+        return True
+    except ValueError:
+        return False
+
+
+class AgentToolCwdResolution:
+    """Agent ``cwd`` 展开与校验（单类单责，避免 ``tool.py`` 堆逻辑）。"""
+
+    @staticmethod
+    def expand_to_absolute(raw: str, *, workspace_root: str | None) -> str:
+        """相对路径相对 ``workspace_root``（若缺省则 ``get_cwd()``）展开为绝对路径。"""
+        base = workspace_root if workspace_root else get_cwd()
+        normalized = normalize_user_path_string_for_expand(raw.strip())
+        return expand_path(normalized, base_dir=base)
+
+    @staticmethod
+    def validate_expanded(absolute: str, *, workspace_root: str | None) -> str | None:
+        """返回 ``None`` 表示通过；否则为面向模型的中文错误信息。"""
+        if path_uses_windows_reserved_name(absolute):
+            return "cwd 路径包含 Windows 保留设备名，请更换为普通目录路径。"
+
+        if is_unc_path_skip_local_stat(absolute):
+            return None
+
+        if workspace_root:
+            try:
+                root = Path(workspace_root).expanduser().resolve()
+                candidate = Path(absolute).expanduser().resolve()
+            except OSError as exc:
+                return f"cwd 无法解析到 workspace 内：{exc}"
+            if not _path_is_descendant(candidate, root):
+                return (
+                    "cwd 必须位于当前 workspace 根目录之下，"
+                    "不可使用 ../ 等方式跳出工程根。"
+                )
+
+        try:
+            if not os.path.isdir(absolute):
+                return "cwd 必须是已存在的目录路径。"
+        except OSError as exc:
+            return f"cwd 无法访问（{exc}）。请确认路径存在且可读。"
+
+        return None
+
+    @classmethod
+    def resolve_and_validate(
+        cls,
+        raw_cwd: str,
+        *,
+        ctx: Any,
+    ) -> tuple[str | None, str | None]:
+        """展开并校验；成功时 ``(absolute, None)``，失败 ``(None, message)``。"""
+        ws = getattr(ctx, "workspace_root", None)
+        if not isinstance(ws, str):
+            ws = None
+        if isinstance(ws, str) and not ws.strip():
+            ws = None
+        try:
+            absolute = cls.expand_to_absolute(raw_cwd, workspace_root=ws)
+        except (OSError, ValueError) as exc:
+            return None, f"cwd 无法展开为有效绝对路径：{exc}"
+        msg = cls.validate_expanded(absolute, workspace_root=ws)
+        if msg:
+            return None, msg
+        return absolute, None
+
+
+def apply_agent_cwd_to_data(data: dict[str, Any], ctx: Any) -> ValidationResult | None:
+    """若 ``data`` 含非空 ``cwd``，展开并校验后写回绝对路径；无 cwd 或空串返回 ``None``。
+
+    供 ``validate_input`` 与 ``invoke``（绕过 pipeline 的测试/脚本路径）共用。
+    """
+    raw = data.get("cwd")
+    if raw is None:
+        return None
+    if isinstance(raw, str) and not raw.strip():
+        return None
+    abs_cwd, err = AgentToolCwdResolution.resolve_and_validate(str(raw), ctx=ctx)
+    if err:
+        return ValidationResult(ok=False, message=err)
+    data["cwd"] = abs_cwd
+    return None
+
+
+__all__ = [
+    "AgentToolCwdResolution",
+    "apply_agent_cwd_to_data",
+]

langchain_agentx/tools/agent/limits.py

@@ -0,0 +1,26 @@
+"""
+tools/agent/limits.py — AgentTool 配额常量
+
+职责：集中管理 Agent 工具输出上限、嵌套深度与步数限制，不承载执行逻辑。
+在整体链路中的位置：tool.py 的 check_permissions()/invoke() 读取这些阈值。
+CC 对照：src/tools/AgentTool/AgentTool.tsx 的 maxResultSizeChars=100_000 与深度防护语义。
+当前裁剪范围：v1 全量常量；异步输出目录为 v2 预留。
+"""
+
+from __future__ import annotations
+
+import os
+
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+MAX_OUTPUT_CHARS: int = int(
+    os.getenv("LANGCHAIN_AGENTX_AGENT_TOOL_MAX_OUTPUT_CHARS", "100000")
+)
+MAX_AGENT_DEPTH: int = int(os.getenv("LANGCHAIN_AGENTX_AGENT_TOOL_MAX_DEPTH", "3"))
+_WORKSPACE_CFG = resolve_agent_workspace_config()
+BACKGROUND_OUTPUT_DIR: str = os.path.expanduser(
+    os.getenv(
+        "LANGCHAIN_AGENTX_AGENT_TOOL_BACKGROUND_OUTPUT_DIR",
+        str(_WORKSPACE_CFG.tasks_dir),
+    )
+)

langchain_agentx/tools/agent/loader.py

@@ -0,0 +1,270 @@
+"""
+tools/agent/loader.py — 用户自定义 Agent 加载器
+
+职责：从 Markdown 文件（{agent_home}/agents/ 下扩展名 ``.md``，大小写不敏感）加载用户自定义 Agent 配置，
+      按优先级与内置原语合并后返回 SubagentRegistry。
+在整体链路中的位置：编排层初始化阶段 → AgentDefinitionLoader.load() → SubagentRegistry
+                    → AgentRuntimeTool(registry=...)
+CC 对照：src/tools/AgentTool/loadAgentsDir.ts getAgentDefinitionsWithOverrides()
+         + parseAgentFromMarkdown()
+当前裁剪范围：v1 Markdown 解析 + YAML frontmatter + 优先级合并；
+             tools/disallowedTools/maxTurns/background 字段支持；
+             agents 目录下 ``.md`` 扩展名 **大小写不敏感**（``*.MD`` / ``*.Md`` 与 ``*.md`` 同等）；
+             v2 memoization / file watcher
+
+加载优先级（后者覆盖前者，与 CC getActiveAgentsFromList 一致）：
+  built-in < userSettings < projectSettings
+
+文件格式（与 CC 一致）：
+  ---
+  name: my-agent          # 必填
+  description: Does XYZ   # 必填
+  tools: [Read, Glob]     # 可选，allowlist（省略=全部）
+  disallowedTools: [Edit] # 可选，denylist（优先级高于 tools）
+  maxTurns: 30            # 可选，default_max_steps
+  background: false       # 可选，allow_async
+  ---
+  系统提示词 body...
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .registry.config import SubagentConfig
+from .registry.registry import SubagentRegistry
+
+logger = logging.getLogger(__name__)
+
+# 子 Agent 始终禁止调用 AgentTool 本身（与 backend.py 不变量一致）
+_ALWAYS_DISALLOWED = {"Agent", "agent"}
+
+
+@dataclass
+class AgentLoadResult:
+    """加载结果：成功加载的 config 列表 + 失败文件列表。"""
+    configs: list[SubagentConfig] = field(default_factory=list)
+    failed_files: list[dict[str, Any]] = field(default_factory=list)
+
+
+class AgentDefinitionLoader:
+    """从 Markdown 文件加载用户自定义 Agent，按优先级合并到 SubagentRegistry。
+
+    优先级（后加载覆盖先加载）：built-in < userSettings < projectSettings
+    CC 对照：loadAgentsDir.ts getAgentDefinitionsWithOverrides()
+    """
+
+    def __init__(
+        self,
+        workspace_config: Any | None = None,
+        base_registry: SubagentRegistry | None = None,
+        user_agents_dir: str | Path | None = None,
+    ) -> None:
+        """
+        Args:
+            workspace_config: AgentWorkspaceConfig 实例（提供 agents_dir 路径）。
+                              None 时跳过 projectSettings 加载。
+            base_registry:    内置能力原语注册表（built-in 层）。
+            user_agents_dir:  用户级 agents 目录（~/.config/langchain_agentx/agents/）。
+                              None 时跳过 userSettings 加载。
+        """
+        self._workspace_config = workspace_config
+        self._base_registry = base_registry
+        self._user_agents_dir = Path(user_agents_dir) if user_agents_dir else None
+
+    def load(self) -> SubagentRegistry:
+        """加载所有 Agent 定义，按优先级合并，返回合并后的 SubagentRegistry。
+
+        合并规则：built-in < userSettings < projectSettings（后写覆盖前写）
+        CC 对照：getActiveAgentsFromList() 的 agentMap 合并逻辑
+        """
+        merged: dict[str, SubagentConfig] = {}
+
+        # 1. built-in（最低优先级）
+        if self._base_registry:
+            for cfg in self._base_registry.list_all():
+                merged[cfg.name] = cfg
+
+        # 2. userSettings
+        for cfg in self._load_from_dir(self._user_agents_dir):
+            merged[cfg.name] = cfg
+
+        # 3. projectSettings（最高优先级）
+        project_dir = self._get_project_agents_dir()
+        for cfg in self._load_from_dir(project_dir):
+            merged[cfg.name] = cfg
+
+        registry = SubagentRegistry()
+        for cfg in merged.values():
+            registry.register(cfg)
+        return registry
+
+    def _get_project_agents_dir(self) -> Path | None:
+        """从 workspace_config 获取 projectSettings agents 目录。"""
+        if self._workspace_config is None:
+            return None
+        agents_dir = getattr(self._workspace_config, "agents_dir", None)
+        return Path(agents_dir) if agents_dir else None
+
+    def _load_from_dir(self, directory: Path | None) -> list[SubagentConfig]:
+        """从目录加载所有 Markdown agent 文件，返回解析成功的 SubagentConfig 列表。
+
+        扩展名按 **大小写不敏感** 匹配 ``.md``（Linux 上 ``*.MD`` 与 CC 产品预期一致）。
+        目录不存在时安静跳过，不抛异常。
+        """
+        if directory is None or not directory.exists():
+            return []
+        configs: list[SubagentConfig] = []
+        for md_file in _iter_markdown_agent_files(directory):
+            cfg = self._parse_agent_from_markdown(md_file)
+            if cfg is not None:
+                configs.append(cfg)
+        return configs
+
+    def _parse_agent_from_markdown(self, file_path: Path) -> SubagentConfig | None:
+        """解析单个 Markdown agent 定义文件。
+        CC 对照：parseAgentFromMarkdown()
+
+        必填：name、description；缺失时静默跳过（可能是参考文档）。
+        """
+        try:
+            raw = file_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            logger.warning("Cannot read agent file %s: %s", file_path, exc)
+            return None
+
+        frontmatter, body = self._split_frontmatter(raw)
+        if frontmatter is None:
+            return None  # 无 frontmatter，静默跳过
+
+        name = frontmatter.get("name")
+        description = frontmatter.get("description")
+        if not name or not isinstance(name, str):
+            return None
+        if not description or not isinstance(description, str):
+            logger.warning("Agent file %s missing 'description', skipping", file_path)
+            return None
+
+        system_prompt = body.strip()
+        tools_raw = frontmatter.get("tools")
+        disallowed_raw = frontmatter.get("disallowedTools")
+        max_turns = _parse_positive_int(frontmatter.get("maxTurns"))
+        allow_async = bool(_parse_bool(frontmatter.get("background")))
+        tool_filter = self._build_tool_filter(tools_raw, disallowed_raw)
+        tools_description = _describe_tools(tools_raw, disallowed_raw)
+
+        return SubagentConfig(
+            name=name.strip(),
+            description=description.strip(),
+            system_prompt_factory=lambda sp=system_prompt: sp,
+            tool_filter=tool_filter,
+            tools_description=tools_description,
+            default_max_steps=max_turns,
+            allow_async=allow_async,
+            tags={"custom"},
+        )
+
+    def _split_frontmatter(self, text: str) -> tuple[dict | None, str]:
+        """分离 YAML frontmatter 与 body。
+        格式：--- frontmatter --- body
+        CC 对照：markdownConfigLoader.ts frontmatter 分割逻辑
+        """
+        if not text.startswith("---"):
+            return None, text
+        parts = text.split("---", 2)
+        if len(parts) < 3:
+            return None, text
+        try:
+            import yaml
+            fm = yaml.safe_load(parts[1]) or {}
+        except Exception as exc:
+            logger.warning("YAML parse error in frontmatter: %s", exc)
+            return None, text
+        return fm, parts[2]
+
+    def _build_tool_filter(
+        self,
+        tools_raw: Any,
+        disallowed_raw: Any,
+    ):
+        """根据 tools/disallowedTools 字段构建 tool_filter 函数。
+        CC 对照：parseAgentToolsFromFrontmatter() + filterToolsForAgent()
+        denylist 优先级高于 allowlist；AgentTool 本身始终在 denylist。
+        """
+        # 解析 allowlist
+        if tools_raw is None or tools_raw == ["*"]:
+            allowlist: set[str] | None = None  # None = 全工具集
+        elif isinstance(tools_raw, list):
+            allowlist = set(tools_raw)
+        else:
+            allowlist = None
+
+        # 解析 denylist（合并用户指定 + 始终禁止）
+        if isinstance(disallowed_raw, list):
+            denylist = set(disallowed_raw) | _ALWAYS_DISALLOWED
+        else:
+            denylist = set(_ALWAYS_DISALLOWED)
+
+        if allowlist is None and denylist == _ALWAYS_DISALLOWED:
+            return None  # 无过滤，全工具集（backend.py 会移除 AgentTool）
+
+        def _filter(all_tools: list) -> list:
+            result = all_tools if allowlist is None else [
+                t for t in all_tools if getattr(t, "name", "") in allowlist
+            ]
+            return [t for t in result if getattr(t, "name", "") not in denylist]
+
+        return _filter
+
+
+# ── 辅助函数 ──────────────────────────────────────────────────────────────────
+
+
+def _iter_markdown_agent_files(directory: Path) -> list[Path]:
+    """枚举 ``directory`` 下扩展名为 ``.md`` 的文件（大小写不敏感），按文件名排序。"""
+    if not directory.is_dir():
+        return []
+    paths: list[Path] = []
+    try:
+        entries = list(directory.iterdir())
+    except OSError as exc:
+        logger.warning("Cannot list agents directory %s: %s", directory, exc)
+        return []
+    for p in entries:
+        try:
+            if p.is_file() and p.suffix.lower() == ".md":
+                paths.append(p)
+        except OSError:
+            continue
+    return sorted(paths, key=lambda x: x.name.lower())
+
+
+def _parse_positive_int(raw: Any) -> int | None:
+    try:
+        v = int(raw)
+        return v if v > 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_bool(raw: Any) -> bool | None:
+    if raw in (True, "true", "True", 1):
+        return True
+    if raw in (False, "false", "False", 0):
+        return False
+    return None
+
+
+def _describe_tools(tools_raw: Any, disallowed_raw: Any) -> str:
+    if tools_raw is None or tools_raw == ["*"]:
+        base = "All tools"
+    elif isinstance(tools_raw, list):
+        base = ", ".join(tools_raw)
+    else:
+        base = "All tools"
+    if disallowed_raw:
+        return f"{base} except {', '.join(disallowed_raw)}"
+    return base