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

langchain_agentx/tools/ripgrep_plugin_exclusions.py

@@ -0,0 +1,137 @@
+"""
+tools/ripgrep_plugin_exclusions.py — Plugin 缓存孤儿版本的 ripgrep --glob 排除
+
+职责：
+    对齐 CC src/utils/plugins/orphanedPluginFilter.ts：在搜索路径与 plugin cache 重叠时，
+    生成 `!**/<relativeVersionDir>/**` 列表，避免 Grep/Glob 命中带 `.orphaned_at` 的旧版本目录。
+
+链路位置：
+    ToolRuntimeLoader.register_default_tools -> 构造 PluginCacheGlobExclusions
+    -> GrepRuntimeTool / GlobRuntimeTool.invoke -> RipgrepBackend._build_args / build_rg_files_args
+
+当前裁剪范围：
+    仅基于 workspace 的 `plugin_cache_dir`；不实现 CC 的 main.tsx 预热与 /reload-plugins 命令
+    （clear_cache 供后续插件热重载接线）。失败时 best-effort 返回空列表，不阻断搜索。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+
+from langchain_agentx.tools.grep.backend import run_ripgrep_lines
+from langchain_agentx.utils.rg_executable import default_rg_executable
+from langchain_agentx.utils.subprocess_text import (
+    TextSubprocessRunner,
+    default_text_subprocess_runner,
+)
+
+_ORPHANED_AT = ".orphaned_at"
+
+
+class PluginCacheGlobExclusions:
+    """会话级缓存的 plugin cache `--glob` 排除串（与 CC getGlobExclusionsForPluginCache 语义对齐）。"""
+
+    def __init__(
+        self,
+        *,
+        cache_root: str | None,
+        rg_path: str | None = None,
+        timeout: int = 20,
+        text_runner: TextSubprocessRunner | None = None,
+    ) -> None:
+        if cache_root:
+            self._cache_root = os.path.normpath(os.path.realpath(os.path.expanduser(cache_root)))
+        else:
+            self._cache_root = None
+        self._rg_path = rg_path if rg_path is not None else default_rg_executable()
+        self._timeout = int(timeout)
+        self._text_runner = text_runner or default_text_subprocess_runner()
+        self._cached: list[str] | None = None
+        self._lock = threading.Lock()
+
+    def clear_cache(self) -> None:
+        """对齐 CC clearPluginCacheExclusions：插件集重载后应调用以重新扫描 marker。"""
+        with self._lock:
+            self._cached = None
+
+    @staticmethod
+    def _normalize_for_compare(path: str) -> str:
+        n = os.path.normpath(os.path.realpath(os.path.expanduser(path)))
+        if sys.platform == "win32":
+            return n.lower()
+        return n
+
+    @staticmethod
+    def paths_overlap(search_path: str, cache_root: str) -> bool:
+        """与 CC orphanedPluginFilter.pathsOverlap 等价（含根路径与前缀关系）。"""
+        na = PluginCacheGlobExclusions._normalize_for_compare(search_path)
+        nb = PluginCacheGlobExclusions._normalize_for_compare(cache_root)
+        sep = os.sep
+        return (
+            na == nb
+            or na == sep
+            or nb == sep
+            or na.startswith(nb + sep)
+            or nb.startswith(na + sep)
+        )
+
+    def get_exclusions_for_search(self, search_path: str) -> list[str]:
+        """
+        若 search_path 与 plugin cache 根无路径重叠，返回 []（与 CC 短路一致）。
+        否则返回缓存的排除 glob 列表（首次调用时扫描 `.orphaned_at`）。
+        """
+        if not self._cache_root:
+            return []
+        sp = os.path.normpath(os.path.realpath(os.path.expanduser(search_path)))
+        if not self.paths_overlap(sp, self._cache_root):
+            return []
+        with self._lock:
+            if self._cached is not None:
+                return list(self._cached)
+            self._cached = self._compute_exclusions_locked()
+            return list(self._cached)
+
+    def _compute_exclusions_locked(self) -> list[str]:
+        try:
+            if not os.path.isdir(self._cache_root):
+                return []
+            args = [
+                "--files",
+                "--hidden",
+                "--no-ignore",
+                "--max-depth",
+                "4",
+                "--glob",
+                _ORPHANED_AT,
+            ]
+            lines = run_ripgrep_lines(
+                self._rg_path,
+                args,
+                self._cache_root,
+                timeout=self._timeout,
+                text_runner=self._text_runner,
+                is_retry=False,
+            )
+            out: list[str] = []
+            cache = self._cache_root
+            for marker_path in lines:
+                mp = marker_path.strip()
+                if not mp:
+                    continue
+                version_dir = os.path.dirname(mp)
+                if os.path.isabs(version_dir):
+                    try:
+                        rel = os.path.relpath(version_dir, cache)
+                    except ValueError:
+                        continue
+                else:
+                    rel = version_dir
+                posix_rel = rel.replace("\\", "/")
+                if not posix_rel or posix_rel == ".":
+                    continue
+                out.append(f"!**/{posix_rel}/**")
+            return out
+        except Exception:
+            return []

langchain_agentx/tools/skill/__init__.py

@@ -0,0 +1,4 @@
+from .tool import SkillRuntimeTool
+
+__all__ = ["SkillRuntimeTool"]
+

langchain_agentx/tools/skill/argument_substitution.py

@@ -0,0 +1,80 @@
+"""
+tools/skill/argument_substitution.py — skill 参数展开（CC argumentSubstitution.ts 对齐子集）
+
+职责：
+    ``parse_arguments`` / ``parse_argument_names`` / ``substitute_arguments``，
+    支持 ``$ARGUMENTS``、``$ARGUMENTS[n]``、``$n`` 及 frontmatter ``arguments`` 定义的具名 ``$name``。
+
+链路位置：
+    ``SkillContentExpander.expand()`` → ``substitute_arguments()``。
+
+CC 对照：
+    ``src/utils/argumentSubstitution.ts``；本实现以 ``shlex.split`` 近似 CC 的 shell-quote 解析。
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from collections.abc import Sequence
+from typing import Any
+
+
+def parse_arguments(args: str | None) -> list[str]:
+    """将参数字符串拆成 token 列表（对齐 CC ``parseArguments``）。"""
+    if args is None or not args.strip():
+        return []
+    try:
+        return shlex.split(args, posix=True)
+    except ValueError:
+        return [p for p in args.split() if p]
+
+
+def parse_argument_names(argument_names: Any) -> list[str]:
+    """解析 frontmatter ``arguments``（对齐 CC ``parseArgumentNames``）。"""
+
+    def _valid(name: str) -> bool:
+        return bool(name.strip()) and not name.strip().isdigit()
+
+    if not argument_names:
+        return []
+    if isinstance(argument_names, list):
+        return [str(x).strip() for x in argument_names if _valid(str(x))]
+    if isinstance(argument_names, str):
+        return [p for p in argument_names.split() if _valid(p)]
+    return []
+
+
+def substitute_arguments(
+    content: str,
+    args: str | None,
+    *,
+    append_if_no_placeholder: bool = True,
+    argument_names: Sequence[str] | None = None,
+) -> str:
+    """替换正文中的参数占位符（对齐 CC ``substituteArguments`` 顺序与语义）。"""
+    if args is None:
+        return content
+
+    names = list(argument_names or [])
+    parsed = parse_arguments(args)
+    original = content
+
+    for i, name in enumerate(names):
+        if not name:
+            continue
+        pat = re.compile(rf"\${re.escape(name)}(?!\[|\w)")
+        rep = parsed[i] if i < len(parsed) else ""
+        content = pat.sub(rep, content)
+
+    def _tok_at(parsed_args: list[str], m: re.Match[str]) -> str:
+        idx = int(m.group(1))
+        return parsed_args[idx] if 0 <= idx < len(parsed_args) else ""
+
+    content = re.sub(r"\$ARGUMENTS\[(\d+)\]", lambda m: _tok_at(parsed, m), content)
+    content = re.sub(r"\$(\d+)(?!\w)", lambda m: _tok_at(parsed, m), content)
+    content = content.replace("$ARGUMENTS", args)
+
+    if content == original and append_if_no_placeholder and args:
+        content = f"{content}\n\nARGUMENTS: {args}"
+    return content

langchain_agentx/tools/skill/loader.py

@@ -0,0 +1,196 @@
+"""
+tools/skill/loader.py — Skill 加载协作者
+
+职责：
+    - SkillFrontmatterParser：解析 SKILL.md frontmatter + body
+    - SkillCommandRepository：从 skills 根目录加载并查找技能
+    - SkillContentExpander：注入 ``Base directory for this skill:`` 前缀后执行参数展开
+
+链路位置：
+    SkillRuntimeTool.invoke()
+      -> SkillCommandRepository.find_by_name()
+      -> SkillContentExpander.expand()
+
+CC 对照：
+    对齐 CC SkillTool 的 command lookup + prompt expansion 思路，
+    但实现为本工程 RuntimeTool 的 OOP 协作者，不走 middleware 旁路。
+    frontmatter：支持 ``when_to_use`` / ``whenToUse`` 与 ``description`` 的
+    单行值及常见块标量（``|`` / ``>-``，见 loadSkillsDir 的 whenToUse 语义）。
+    块标量限制：``_read_literal_block`` 以顶格 ``word:`` 作为块结束；块正文内若出现
+    顶格 ``key: value`` 行会被误截断（已知限制，复杂 YAML 请用单行或换用完整 YAML 解析）。
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from .argument_substitution import parse_argument_names, substitute_arguments
+from .models import SkillCommand
+
+# CC loadSkillsDir：when_to_use / description 常为块标量（| / >-）；须在 parser 层取出独立字符串
+_BLOCK_TEXT_KEYS = frozenset({"when_to_use", "whenToUse", "description", "argument-hint", "argument_hint"})
+
+
+def normalize_skill_name(skill_name: str) -> str:
+    return skill_name.strip().lstrip("/")
+
+
+def _normalize_when_to_use_raw(raw: Any) -> str | None:
+    """将 frontmatter 中的 when_to_use 规范为单行或多行字符串（CC whenToUse）。"""
+    if isinstance(raw, str) and raw.strip():
+        return raw.strip()
+    if isinstance(raw, list):
+        parts = [str(x).strip() for x in raw if str(x).strip()]
+        if parts:
+            return "\n".join(parts)
+    return None
+
+
+def _is_block_scalar_header(value: str) -> bool:
+    """YAML 块标量起始行：空、``|``、``|-``、``|+``、``>``、``>-`` 等（与 CC SKILL 常见写法一致）。"""
+    v = value.strip()
+    if not v:
+        return True
+    return v.startswith("|") or v.startswith(">")
+
+
+class SkillFrontmatterParser:
+    _FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL)
+
+    def parse(self, text: str) -> tuple[dict[str, Any], str]:
+        m = self._FRONTMATTER_RE.match(text)
+        if not m:
+            return {}, text
+        frontmatter_text = m.group(1)
+        body = text[m.end():]
+        return self._parse_simple_yaml(frontmatter_text), body
+
+    @staticmethod
+    def _read_literal_block(lines: list[str], start: int) -> tuple[str, int]:
+        """读取 ``key: |`` 后的块，直到下一个顶格 ``word:``（与 CC 常见 SKILL.md 一致）。
+
+        限制：块内不得出现顶格 ``foo: bar`` 示例行，否则会被当作下一个 frontmatter 键而提前结束。
+        """
+        parts: list[str] = []
+        j = start
+        while j < len(lines):
+            raw = lines[j]
+            if re.match(r"^[A-Za-z0-9_-]+:\s*", raw) and not raw[:1].isspace():
+                break
+            parts.append(raw)
+            j += 1
+        text = "\n".join(parts)
+        return text.strip("\n"), j
+
+    def _parse_simple_yaml(self, frontmatter_text: str) -> dict[str, Any]:
+        data: dict[str, Any] = {}
+        lines = frontmatter_text.splitlines()
+        i = 0
+        while i < len(lines):
+            stripped = lines[i].strip()
+            i += 1
+            if not stripped or stripped.startswith("#"):
+                continue
+
+            m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", stripped)
+            if not m:
+                continue
+
+            key, value = m.group(1), m.group(2).strip()
+            if key in _BLOCK_TEXT_KEYS and _is_block_scalar_header(value):
+                block, i = self._read_literal_block(lines, i)
+                if block.strip():
+                    data[key] = block.strip()
+                continue
+
+            if value:
+                data[key] = value
+                continue
+
+            items: list[str] = []
+            while i < len(lines):
+                nxt = lines[i].strip()
+                if not nxt:
+                    i += 1
+                    continue
+                if nxt.startswith("- "):
+                    items.append(nxt[2:].strip())
+                    i += 1
+                    continue
+                break
+            data[key] = items
+        return data
+
+
+class SkillCommandRepository:
+    def __init__(self, skills_root: Path, parser: SkillFrontmatterParser | None = None) -> None:
+        self._skills_root = skills_root
+        self._parser = parser or SkillFrontmatterParser()
+
+    def list_commands(self) -> list[SkillCommand]:
+        if not self._skills_root.exists():
+            return []
+
+        commands: list[SkillCommand] = []
+        for skill_dir in self._skills_root.iterdir():
+            if not skill_dir.is_dir():
+                continue
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.exists():
+                continue
+
+            content = skill_md.read_text(encoding="utf-8")
+            frontmatter, body = self._parser.parse(content)
+            name = str(frontmatter.get("name") or skill_dir.name).strip()
+            raw_desc = frontmatter.get("description")
+            has_user_desc = isinstance(raw_desc, str) and bool(raw_desc.strip())
+            description = raw_desc.strip() if has_user_desc else ""
+            raw_wtu = frontmatter.get("when_to_use") or frontmatter.get("whenToUse")
+            when_to_use = _normalize_when_to_use_raw(raw_wtu)
+            arg_names = parse_argument_names(frontmatter.get("arguments"))
+            commands.append(
+                SkillCommand(
+                    name=name,
+                    description=description,
+                    content=body.strip(),
+                    path=skill_md,
+                    source="local",
+                    frontmatter=frontmatter,
+                    has_user_specified_description=has_user_desc,
+                    when_to_use=when_to_use,
+                    argument_names=arg_names,
+                )
+            )
+
+        dedup: dict[str, SkillCommand] = {}
+        for cmd in commands:
+            dedup.setdefault(normalize_skill_name(cmd.name), cmd)
+        return list(dedup.values())
+
+    def find_by_name(self, skill_name: str) -> SkillCommand | None:
+        normalized = normalize_skill_name(skill_name)
+        for cmd in self.list_commands():
+            if normalize_skill_name(cmd.name) == normalized:
+                return cmd
+        return None
+
+
+class SkillContentExpander:
+    def expand(self, command: SkillCommand, args: str | None) -> str:
+        # CC createSkillCommand.getPromptForCommand：先注入 skill 根目录，再 substituteArguments。
+        body = command.content
+        skill_root = command.path.parent
+        try:
+            skill_root_s = str(skill_root.resolve())
+        except OSError:
+            skill_root_s = str(skill_root)
+        markdown = f"Base directory for this skill: {skill_root_s}\n\n{body}"
+        return substitute_arguments(
+            markdown,
+            args,
+            append_if_no_placeholder=True,
+            argument_names=command.argument_names,
+        )
+

langchain_agentx/tools/skill/models.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class SkillToolInput(BaseModel):
+    skill_name: str = Field(
+        ...,
+        description="Skill name (leading slash is optional).",
+    )
+    args: str | None = Field(
+        default=None,
+        description="Optional arguments passed to skill expansion.",
+    )
+
+    @field_validator("skill_name")
+    @classmethod
+    def _validate_skill_name(cls, value: str) -> str:
+        name = value.strip()
+        if not name:
+            raise ValueError("skill_name cannot be empty")
+        return name
+
+    @field_validator("args")
+    @classmethod
+    def _validate_args_len(cls, value: str | None) -> str | None:
+        if value and len(value) > 2000:
+            raise ValueError("args too long (max 2000 chars)")
+        return value
+
+
+class SkillToolOutput(BaseModel):
+    skill_name: str
+    content: str
+    source: Literal["local", "mcp"] = "local"
+    skill_path: str | None = None
+    command_name_tag: str | None = None
+    allowed_tools: list[str] = Field(default_factory=list)
+    model_override: str | None = None
+    constraints_applied: dict[str, Any] = Field(default_factory=dict)
+
+
+def _frontmatter_bool(value: Any) -> bool:
+    if value is True:
+        return True
+    if isinstance(value, str) and value.strip().lower() in ("true", "1", "yes", "on"):
+        return True
+    return False
+
+
+@dataclass(slots=True)
+class SkillCommand:
+    name: str
+    description: str
+    content: str
+    path: Path
+    source: Literal["local", "mcp"] = "local"
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    # CC getSlashCommandToolSkills：仅当 frontmatter 显式给出非空 description 时为 True（非正文推导）
+    has_user_specified_description: bool = False
+    # CC whenToUse / frontmatter when_to_use
+    when_to_use: str | None = None
+    # CC frontmatter ``arguments`` → parseArgumentNames → $name 占位符
+    argument_names: list[str] = field(default_factory=list)
+
+    def visible_in_slash_command_tool_listing(self) -> bool:
+        """是否出现在模型可见的 skill listing 中。
+
+        与 CC ``commands/init`` / ``SkillTool`` 侧一致：``disable-model-invocation: true`` 表示
+        仅用户侧触发，**不**对模型展示 listing（亦由 ``SkillRuntimeTool.validate_input`` 拦截工具调用）。
+        """
+        if not (self.name or "").strip():
+            return False
+        if not (self.has_user_specified_description or bool((self.when_to_use or "").strip())):
+            return False
+
+        disable_mi = _frontmatter_bool(
+            self.frontmatter.get("disable-model-invocation")
+            or self.frontmatter.get("disable_model_invocation")
+        )
+        if disable_mi:
+            return False
+        return self.source in ("local", "mcp")
+

langchain_agentx/tools/skill/policy.py

@@ -0,0 +1,80 @@
+"""
+tools/skill/policy.py — Skill frontmatter 约束协作者
+
+职责：
+    解析并评估 skill frontmatter 中与执行约束相关的字段，
+    当前 v1 支持：
+      - allowed-tools
+      - paths
+
+链路位置：
+    SkillRuntimeTool.check_permissions()
+      -> SkillConstraintEvaluator.evaluate()
+
+注意：
+    - 本模块不替代全局 PolicyEngine；全局 deny/allow 仍由 RuntimeTool 基类链路兜底。
+    - 这里仅做 skill 自身约束判定，返回 AuthorizationDecision。
+    - ``paths`` 是否在 workspace 内：用 ``Path.resolve()`` + ``Path.relative_to``，**不用** ``str.startswith``（避免 Windows 大小写/规范化误判）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from langchain_agentx.tool_runtime.models import AuthorizationDecision
+
+
+def _path_is_descendant(candidate: Path, ancestor: Path) -> bool:
+    """candidate 与 ancestor 均已 resolve；在 ancestor 目录树内（含自身）则 True。"""
+    try:
+        candidate.relative_to(ancestor)
+        return True
+    except ValueError:
+        return False
+
+
+class SkillConstraintEvaluator:
+    def __init__(self, workspace_root: Path | str) -> None:
+        root = Path(workspace_root).expanduser()
+        try:
+            self._workspace_root = root.resolve()
+        except OSError:
+            self._workspace_root = root
+
+    def evaluate(self, frontmatter: dict[str, Any]) -> AuthorizationDecision:
+        paths = frontmatter.get("paths")
+        if isinstance(paths, list):
+            ws = self._workspace_root
+            for raw in paths:
+                text = str(raw).strip()
+                if not text:
+                    continue
+                try:
+                    candidate = (ws / text).resolve()
+                except OSError:
+                    return AuthorizationDecision(
+                        behavior="deny",
+                        message=(
+                            "Permission denied: skill paths constraint could not "
+                            f"resolve path entry: {text!r}."
+                        ),
+                        policy_id="skill_paths_resolve_error",
+                    )
+                if not _path_is_descendant(candidate, ws):
+                    return AuthorizationDecision(
+                        behavior="deny",
+                        message="Permission denied: skill paths constraint escapes workspace root.",
+                        policy_id="skill_paths_outside_workspace",
+                    )
+
+        allowed_tools = frontmatter.get("allowed-tools")
+        if allowed_tools is not None and not isinstance(allowed_tools, list):
+            return AuthorizationDecision(
+                behavior="deny",
+                message="Permission denied: invalid 'allowed-tools' frontmatter format.",
+                policy_id="skill_allowed_tools_invalid",
+            )
+
+        return AuthorizationDecision(behavior="allow")
+

langchain_agentx/tools/skill/prompt.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+TOOL_NAME = "skill"
+COMMAND_NAME_TAG = "command-name"
+
+
+def get_prompt() -> str:
+    return (
+        "Execute a skill within the main conversation.\n\n"
+        "When users ask you to perform tasks, check whether any available skill matches.\n"
+        "Skills provide specialized capabilities and domain knowledge.\n"
+        "If users reference slash-command style requests such as '/commit' or '/review-pr', "
+        "treat them as skill invocations.\n\n"
+        "How to invoke:\n"
+        '- Use this tool with `skill_name` and optional `args`.\n'
+        '- Example: `skill_name=\"commit\"`\n'
+        '- Example: `skill_name=\"pdf\"`\n'
+        '- Example: `skill_name=\"commit\", args=\"-m \'Fix bug\'\"`\n'
+        '- Example: `skill_name=\"review-pr\", args=\"123\"`\n'
+        '- Example: `skill_name=\"ms-office-suite:pdf\"`\n'
+        '- Leading slash is allowed (e.g. `/commit`).\n\n'
+        "Important:\n"
+        "- Available skills are provided via skill listing reminders/messages in the conversation.\n"
+        "- If a matching skill exists, this is a BLOCKING REQUIREMENT: call this tool before "
+        "giving any task-specific guidance.\n"
+        "- Never mention a skill without calling this tool.\n"
+        "- Do not invoke a skill that is already running in the current turn.\n"
+        f"- If current turn already contains <{COMMAND_NAME_TAG}>...</{COMMAND_NAME_TAG}>, "
+        "the skill is already loaded; follow it directly instead of re-invoking.\n"
+        "- Do not use this tool for built-in CLI commands (for example /help, /clear).\n"
+    )
+
+
+DESCRIPTION = get_prompt()
+