langchain-agentx-python 1.3.2__py3-none-any.whl → 1.3.4__py3-none-any.whl

langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "1.3.2"
+__version__ = "1.3.4"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

langchain_agentx/command/dispatcher.py

@@ -22,6 +22,12 @@ from .registry import CommandRegistry
 from .result import CommandResult
 from .types import CommandDefinition
 from ..plugin.registries import CommandEntry, CommandRegistry as PluginCommandRegistry
+from ..tools.skill.catalog import (
+    SkillCatalogService,
+    build_skill_catalog_for_context,
+    resolve_dynamic_catalog,
+    _session_store_from_context,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -31,9 +37,11 @@ class CommandDispatcher:
         self,
         registry: CommandRegistry,
         plugin_command_registry: PluginCommandRegistry | None = None,
+        skill_catalog: SkillCatalogService | None = None,
     ) -> None:
         self._registry = registry
         self._plugin_registry = plugin_command_registry
+        self._skill_catalog = skill_catalog
         self._plugin_markdown_cache: dict[Path, tuple[tuple[int, int, int], tuple[str, str]]] = {}
 
     def is_slash_command(self, user_input: str) -> bool:
@@ -53,6 +61,9 @@ class CommandDispatcher:
             if lookup_error is not None:
                 return CommandResult(error=self._format_error("lookup", lookup_error))
         if command is None:
+            skill_result = await self._dispatch_disk_skill(name, args, context)
+            if skill_result is not None:
+                return skill_result
             return CommandResult(error=self._format_error("lookup", f"unknown command: /{name}"))
         if not command.user_invocable:
             return CommandResult(
@@ -186,6 +197,64 @@ class CommandDispatcher:
             return None, f"unknown command: /{name} (ambiguous plugin command: {candidates})"
         return None, None
 
+    async def _dispatch_disk_skill(
+        self,
+        name: str,
+        args: str,
+        context: CommandContext,
+    ) -> CommandResult | None:
+        catalog = self._skill_catalog or build_skill_catalog_for_context(context)
+        segment = context.workspace_cfg.agent_home_segment
+        session_store = _session_store_from_context(context)
+        dynamic = resolve_dynamic_catalog(session_store, agent_home_segment=segment)
+        cmd = catalog.find_by_name(
+            name,
+            dynamic_catalog=dynamic,
+            session_store=session_store,
+            agent_home_segment=segment,
+        )
+        if cmd is None:
+            return None
+        if not catalog.is_user_invocable(cmd):
+            return CommandResult(
+                error=self._format_error(
+                    "permission",
+                    (
+                        f'/{name} can only be invoked by the model via the Skill tool, '
+                        f'not directly by users. Ask the agent to use the "{name}" skill.'
+                    ),
+                )
+            )
+        expanded = catalog.expand_for_slash(
+            name,
+            args,
+            dynamic_catalog=dynamic,
+            session_store=session_store,
+            agent_home_segment=segment,
+        )
+        if expanded is None:
+            return None
+        from langchain_agentx.tools.skill.hook_registration import (
+            register_skill_hooks,
+            resolve_hooks_snapshot,
+        )
+
+        register_skill_hooks(
+            resolve_hooks_snapshot(
+                session_store=session_store,
+                hook_engine=context.hook_engine,
+            ),
+            skill_name=expanded.command.name,
+            skill_root=expanded.command.path.parent,
+            frontmatter=expanded.command.frontmatter,
+        )
+        return CommandResult(
+            should_query=True,
+            injected_prompt=expanded.content,
+            allowed_tools=list(expanded.allowed_tools) if expanded.allowed_tools else None,
+            execution_context=expanded.execution_context,
+        )
+
     @staticmethod
     def _format_error(error_type: str, detail: str) -> str:
         return f"[command/{error_type}] {detail}"

langchain_agentx/loop/graph/factory.py

@@ -573,6 +573,11 @@ class LoopGraphBuilder:
             if self._services.hooks is not None
             else HooksConfigSnapshot()
         )
+        if session_store is not None:
+            session_store.hooks_snapshot = self._hook_snapshot
+            from langchain_agentx.tools.skill.repository_factory import build_skill_repository
+
+            session_store.skill_repository = build_skill_repository(self._workspace_cfg)
         self._trace_callback_handler: TraceCallbackHandler | None = None
         self._trace_tool_callback_handler: TraceCallbackHandler | None = None
         hook_event_emitter = None
@@ -1539,11 +1544,32 @@ class LoopGraphBuilder:
                 # Let providers optionally ingest current loop messages before reserve.
                 # This enables auto-bridge scenarios like tool_use_summary without external pump.
                 state_messages = list(state.get("messages") or [])
+                session_store = None
+                try:
+                    from langgraph.config import get_config
+
+                    configurable = (get_config() or {}).get("configurable") or {}
+                    session_store = configurable.get("session_store")
+                except Exception:
+                    pass
                 for provider in provider_chain:
                     ingest = getattr(provider, "ingest_from_messages", None)
                     if callable(ingest):
                         try:
-                            ingest(scope=scope, messages=state_messages)
+                            ingest(
+                                scope=scope,
+                                messages=state_messages,
+                                session_store=session_store,
+                            )
+                        except TypeError:
+                            try:
+                                ingest(scope=scope, messages=state_messages)
+                            except Exception:
+                                logger.debug(
+                                    "provider ingest_from_messages failed; skip provider=%s",
+                                    provider.__class__.__name__,
+                                    exc_info=True,
+                                )
                         except Exception:
                             logger.debug(
                                 "provider ingest_from_messages failed; skip provider=%s",
@@ -1766,7 +1792,18 @@ class LoopGraphBuilder:
                     content = getattr(msg, "content", "")
                     if isinstance(content, str) and "[skill_listing]" in content:
                         return {}
-                hint = skill_prefetch_provider._build_listing_hint(scope=skill_init_scope)
+                session_store = None
+                try:
+                    from langgraph.config import get_config
+
+                    configurable = (get_config() or {}).get("configurable") or {}
+                    session_store = configurable.get("session_store")
+                except Exception:
+                    pass
+                hint = skill_prefetch_provider._build_listing_hint(
+                    scope=skill_init_scope,
+                    session_store=session_store,
+                )
                 if hint is None:
                     return {}
                 # skill_listing 以 HumanMessage 注入（非 SystemMessage），与 CC role=user 对齐

langchain_agentx/session/agent_session.py

@@ -427,6 +427,21 @@ class AgentSession:
     def list_commands(self) -> list[dict[str, object]]:
         return self._runtime_command_registry.list_for_help()
 
+    def list_skills(self) -> dict[str, object]:
+        """CLI ``/skills`` 菜单：按 source 分组 + token 估算。"""
+        from ..tools.skill.catalog import build_skill_catalog, resolve_dynamic_catalog
+
+        catalog = build_skill_catalog(
+            workspace_root=self._workspace_cfg.workspace_root,
+            agent_home_segment=self._workspace_cfg.agent_home_segment,
+            plugin_registry=self._skill_registry,
+        )
+        dynamic = resolve_dynamic_catalog(
+            self._resolve_session_store(),
+            agent_home_segment=self._workspace_cfg.agent_home_segment,
+        )
+        return catalog.list_skills_menu(dynamic_catalog=dynamic)
+
     async def _execute_hook(self, event: HookEvent) -> None:
         ctx = HookContext(event=event, state={}, session_id=self._session_id)
         # HookEngine 当前主接口是 execute；若未来扩展 execute_async，优先兼容新接口。

langchain_agentx/session/conversation_session.py

@@ -34,6 +34,7 @@ from ..command.builtin import (
     make_memory_command,
     make_reload_plugins_command,
 )
+from ..loop.config import merge_run_config
 from ..loop.config.loop_runtime_overlay import LoopRuntimeOverlay
 from ..loop.context.compaction_service import default_loop_context_compaction
 from ..loop.context.message_utils import total_estimated_tokens_for_messages
@@ -119,12 +120,14 @@ class ConversationSession:
                 capabilities=self._capabilities,
             ),
         )
+        run_config = merge_run_config(graph, None)
         try:
             result = await graph.ainvoke(
                 {
                     "messages": list(self._messages),
                     "_session_id": self._conversation_id,
-                }
+                },
+                config=run_config,
             )
         except Exception:
             # 回滚本轮 append，避免异常路径消息重复累积。
@@ -174,13 +177,15 @@ class ConversationSession:
         prompt = result.injected_prompt or user_input
         appended_message = HumanMessage(content=prompt)
         self._messages.append(appended_message)
+        run_config = merge_run_config(graph, None)
         try:
             apply_command_tool_scope(store, result.allowed_tools)
             loop_output = await graph.ainvoke(
                 {
                     "messages": list(self._messages),
                     "_session_id": self._conversation_id,
-                }
+                },
+                config=run_config,
             )
         except Exception:
             if self._messages and self._messages[-1] is appended_message:
@@ -220,6 +225,7 @@ class ConversationSession:
         )
         output_messages: list[Any] | None = None
         graph_output: dict[str, Any] | None = None
+        run_config = merge_run_config(graph, config)
         driver = LoopStreamDriver()
         try:
             async for event in driver.run(
@@ -228,7 +234,7 @@ class ConversationSession:
                     "messages": list(self._messages),
                     "_session_id": self._conversation_id,
                 },
-                config=config,
+                config=run_config,
                 version="v2",
             ):
                 if event.get("event") == "on_chain_end" and event.get("name") == "LangGraph":
@@ -313,6 +319,24 @@ class ConversationSession:
     def list_commands(self) -> list[dict[str, object]]:
         return self._runtime_command_registry.list_for_help()
 
+    def list_skills(self) -> dict[str, object]:
+        """CLI ``/skills`` 菜单：按 source 分组 + token 估算。"""
+        from ..tools.skill.catalog import build_skill_catalog, resolve_dynamic_catalog
+
+        catalog = build_skill_catalog(
+            workspace_root=self._workspace_cfg.workspace_root,
+            agent_home_segment=self._workspace_cfg.agent_home_segment,
+            plugin_registry=self._skill_registry,
+        )
+        dynamic = resolve_dynamic_catalog(
+            self._resolve_session_store(),
+            agent_home_segment=self._workspace_cfg.agent_home_segment,
+        )
+        return catalog.list_skills_menu(dynamic_catalog=dynamic)
+
+    def _resolve_session_store(self) -> Any | None:
+        return None
+
     async def _execute_hook(self, event: HookEvent) -> None:
         ctx = HookContext(event=event, state={}, session_id=self._conversation_id)
         execute_async = getattr(self._hook_engine, "execute_async", None)

langchain_agentx/task_runtime/skill_prefetch/provider.py

@@ -30,6 +30,8 @@ from .attachments import SkillAttachmentBuilder
 from .models import SkillHint
 
 if TYPE_CHECKING:
+    from langchain_agentx.tools.skill.catalog import SkillCatalogService
+    from langchain_agentx.tools.skill.dynamic_catalog import DynamicSkillSessionCatalog
     from langchain_agentx.tools.skill.loader import SkillCommandRepository
 
 _PRIORITY_ORDER = {
@@ -56,6 +58,7 @@ class SkillPrefetchProvider:
         agent_home_segment: str = ".langchain_agentx",
         skills_root: str | Path | None = None,
         repository: "SkillCommandRepository | None" = None,
+        catalog: "SkillCatalogService | None" = None,
         attachment_builder: SkillAttachmentBuilder | None = None,
         max_queue_size: int | None = None,
         ttl_sec: float | None = None,
@@ -70,12 +73,22 @@ class SkillPrefetchProvider:
             if skills_root
             else workspace_cfg.skills_dir
         )
-        if repository is None:
-            # 延迟导入，避免 task_runtime <-> tools 初始化循环依赖。
-            from langchain_agentx.tools.skill.loader import SkillCommandRepository
-
-            repository = SkillCommandRepository(skills_dir)
-        self._repository = repository
+        if catalog is not None:
+            self._catalog = catalog
+        elif repository is not None:
+            from langchain_agentx.tools.skill.catalog import SkillCatalogService
+
+            self._catalog = SkillCatalogService(repository=repository)
+        else:
+            from langchain_agentx.tools.skill.catalog import build_skill_catalog
+
+            self._catalog = build_skill_catalog(
+                workspace_root=workspace_root,
+                agent_home_segment=agent_home_segment,
+                skills_root=skills_root,
+            )
+        self._repository = self._catalog.repository
+        self._agent_home_segment = agent_home_segment
         self._attachment_builder = attachment_builder or SkillAttachmentBuilder()
         self._lock = RLock()
         self._queue: list[SkillHint] = []
@@ -204,25 +217,29 @@ class SkillPrefetchProvider:
                 for item in self._queue
             )
 
-    def ingest_from_messages(self, *, scope: TaskScope, messages: list) -> int:
-        # v1：仅触发 listing 刷新（幂等），不从 messages 抽取动态候选。
-        # v2 特性：基于 messages 做 dynamic_skill 候选提取，待专项设计后启用。
+    def ingest_from_messages(
+        self,
+        *,
+        scope: TaskScope,
+        messages: list,
+        session_store: object | None = None,
+    ) -> int:
+        # v1：listing 刷新（幂等）；dynamic 来自 session_store 上的 walk-up catalog。
         del messages
-        hint = self._build_listing_hint(scope=scope)
+        hint = self._build_listing_hint(scope=scope, session_store=session_store)
         if hint is None:
             return 0
         self.enqueue_hint(hint)
         return 1
 
-    def _build_listing_hint(self, *, scope: TaskScope) -> SkillHint | None:
-        # 1) 从仓库读取所有命令并做可见性过滤（description/when_to_use/disable-model-invocation）。
-        # 2) 通过签名判断是否变化，未变化则不重复注入（减少上下文噪声）。
-        # 3) 生成“仅 metadata”的 listing 文本，正文由 skill 工具按需加载。
-        commands = self._repository.list_commands()
-        if not commands:
-            return None
-        ordered = sorted((c for c in commands if c.name), key=lambda c: c.name)
-        visible = [c for c in ordered if c.visible_in_slash_command_tool_listing()]
+    def _build_listing_hint(
+        self,
+        *,
+        scope: TaskScope,
+        session_store: object | None = None,
+    ) -> SkillHint | None:
+        dynamic = self._resolve_dynamic_catalog(session_store)
+        visible = self._catalog.list_for_listing(dynamic_catalog=dynamic)
         if not visible:
             return None
         signature = tuple(
@@ -251,6 +268,18 @@ class SkillPrefetchProvider:
             dedup_key=f"skill_listing:{scope_id}",
         )
 
+    def _resolve_dynamic_catalog(
+        self, session_store: object | None
+    ) -> "DynamicSkillSessionCatalog | None":
+        if session_store is None:
+            return None
+        from langchain_agentx.tools.skill.catalog import resolve_dynamic_catalog
+
+        return resolve_dynamic_catalog(
+            session_store,
+            agent_home_segment=self._agent_home_segment,
+        )
+
     @staticmethod
     def _scope_id(scope: TaskScope) -> str:
         return scope.agent_id or "main"

langchain_agentx/tool_runtime/read_permission.py

@@ -196,6 +196,13 @@ class ReadPathAuthorizer:
                 policy_id="readable_internal_project_temp",
                 message="Read allowed for project temp directory path.",
             )
+
+        if self._internal.is_bundled_skills_path(real_path):
+            return AuthorizationDecision(
+                behavior="allow",
+                policy_id="readable_internal_bundled_skills",
+                message="Read allowed for bundled skill reference files.",
+            )
         return None
 
     def _evaluate_unc(self, real_path: str) -> AuthorizationDecision | None:

langchain_agentx/tool_runtime/session_store.py

@@ -15,6 +15,8 @@ runtime/session_store.py — 会话级状态存储
         granted_roots     — 动态扩展的 read/write 边界（Phase 2 grant API）
         denial_tracking   — L3 连续拒绝计数（GAP-7；子代理 fork_local 隔离）
         dynamic_skill_catalog — 嵌套 skills walk-up 缓存（D6c；类型为 tools.skill 侧 catalog）
+        hooks_snapshot — HookEngine 可变快照引用（skill frontmatter hooks 注册用）
+        skill_repository — 会话级 skill 仓库（Read/Write/Edit 条件 skill seed 用）
 
 链路位置：
     GraphFactory 注入 configurable["session_store"] → LangChainAdapter.build_tool_execution_context
@@ -123,6 +125,8 @@ class AgentSessionStore:
         self._root_grant_manager: Any | None = None
         self._denial_tracker: Any | None = None
         self.dynamic_skill_catalog: Any = None
+        self.hooks_snapshot: Any = None
+        self.skill_repository: Any = None
 
     def record_file_read(
         self,

langchain_agentx/tools/ask_user_question/constants.py

@@ -24,3 +24,13 @@ MAX_PREVIEW_SNAPSHOT_CHARS: int = 8192
 
 # present()：每段 preview / snapshot 写入模型可见文本时的默认截断
 PRESENT_PREVIEW_SNIPPET_MAX: int = 500
+
+# 全角问号（中文输入法常见）；校验要求 ASCII '?'
+FULLWIDTH_QUESTION_MARK: str = "\uff1f"
+
+
+def normalize_question_text(text: str) -> str:
+    """将题干末尾全角 ``？`` 规范为 ASCII ``?``（CC / QuestionValidator 一致）。"""
+    if text.endswith(FULLWIDTH_QUESTION_MARK):
+        return text[:-1] + "?"
+    return text

langchain_agentx/tools/ask_user_question/tool.py

@@ -29,7 +29,7 @@ from langchain_agentx.tool_runtime.models import (
     ValidationResult,
 )
 
-from .constants import PRESENT_PREVIEW_SNIPPET_MAX
+from .constants import PRESENT_PREVIEW_SNIPPET_MAX, normalize_question_text
 from .html_preview import HtmlPreviewValidator
 from .models import AskUserQuestionInput, AskUserQuestionOutput, QuestionAnnotation
 from .prompt import (
@@ -116,8 +116,19 @@ class AskUserQuestionTool(RuntimeTool):
         questions = data.get("questions")
         if isinstance(questions, list):
             for q in questions:
-                if isinstance(q, dict) and "multiSelect" not in q:
-                    q["multiSelect"] = False
+                if isinstance(q, dict):
+                    if "multiSelect" not in q:
+                        q["multiSelect"] = False
+                    qt = q.get("question")
+                    if isinstance(qt, str):
+                        q["question"] = normalize_question_text(qt)
+        for key in ("answers", "annotations"):
+            mapping = data.get(key)
+            if isinstance(mapping, dict) and mapping:
+                data[key] = {
+                    normalize_question_text(k) if isinstance(k, str) else k: v
+                    for k, v in mapping.items()
+                }
         if "answers" not in data or data["answers"] is None:
             data["answers"] = {}
         if "annotations" not in data or data["annotations"] is None:

langchain_agentx/tools/skill/__init__.py

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

langchain_agentx/tools/skill/bundled/__init__.py

@@ -0,0 +1,157 @@
+"""
+tools/skill/bundled/__init__.py — Product bundled skill 初始化
+
+职责：
+    进程级注册 debug / simplify / batch / update-config bundled skill。
+
+链路位置：
+    ``SkillCatalogService`` / ``SkillRuntimeTool`` / ``build_skill_catalog`` 启动时调用。
+"""
+
+from __future__ import annotations
+
+from langchain_agentx.utils.agent_settings import normalize_agent_home_segment
+
+from ..models import SkillCommand
+from .prompts import (
+    BATCH_MISSING_INSTRUCTION,
+    BATCH_NOT_GIT_REPO,
+    SIMPLIFY_PROMPT,
+    build_batch_prompt,
+    build_debug_prompt,
+    build_update_config_prompt,
+)
+from .registry import (
+    BundledSkillDefinition,
+    BundledSkillRegistry,
+    bundled_skills_disabled,
+)
+
+_registry: BundledSkillRegistry | None = None
+
+
+def _settings_hint(agent_home_segment: str = ".langchain_agentx") -> str:
+    seg = normalize_agent_home_segment(agent_home_segment)
+    return (
+        f"- Project settings: `{seg}/settings.json`\n"
+        f"- Local overrides: `{seg}/settings.local.json` (typically gitignored)"
+    )
+
+
+def _register_debug(registry: BundledSkillRegistry) -> None:
+    hint = _settings_hint()
+
+    def _content(args: str) -> str:
+        return build_debug_prompt(args=args, settings_hint=hint)
+
+    registry.register(
+        BundledSkillDefinition(
+            name="debug",
+            description="Enable debug logging for this session and help diagnose issues",
+            content=_content,
+            allowed_tools=["Read", "Grep", "Glob"],
+            disable_model_invocation=True,
+            user_invocable=True,
+        )
+    )
+
+
+def _register_simplify(registry: BundledSkillRegistry) -> None:
+    def _content(args: str) -> str:
+        prompt = SIMPLIFY_PROMPT
+        if args.strip():
+            prompt += f"\n\n## Additional Focus\n\n{args.strip()}\n"
+        return prompt
+
+    registry.register(
+        BundledSkillDefinition(
+            name="simplify",
+            description=(
+                "Review changed code for reuse, quality, and efficiency, then fix any issues found."
+            ),
+            content=_content,
+            user_invocable=True,
+        )
+    )
+
+
+def _register_batch(registry: BundledSkillRegistry) -> None:
+    def _content(args: str) -> str:
+        instruction = args.strip()
+        if not instruction:
+            return BATCH_MISSING_INSTRUCTION
+        try:
+            from pathlib import Path
+
+            if not (Path.cwd() / ".git").exists():
+                return BATCH_NOT_GIT_REPO
+        except OSError:
+            pass
+        return build_batch_prompt(instruction)
+
+    registry.register(
+        BundledSkillDefinition(
+            name="batch",
+            description=(
+                "Research and plan a large-scale change, then execute it in parallel across "
+                "isolated worktree agents that each open a PR."
+            ),
+            when_to_use=(
+                "Use when the user wants a sweeping mechanical change across many files "
+                "that can be decomposed into independent parallel units."
+            ),
+            content=_content,
+            user_invocable=True,
+            disable_model_invocation=True,
+        )
+    )
+
+
+def _register_update_config(registry: BundledSkillRegistry) -> None:
+    hint = _settings_hint()
+
+    def _content(args: str) -> str:
+        return build_update_config_prompt(args=args, settings_hint=hint)
+
+    registry.register(
+        BundledSkillDefinition(
+            name="update-config",
+            description="Update agent settings.json / settings.local.json safely",
+            content=_content,
+            allowed_tools=["Read"],
+            user_invocable=True,
+        )
+    )
+
+
+def init_bundled_skills() -> BundledSkillRegistry:
+    global _registry
+    if _registry is not None:
+        return _registry
+    registry = BundledSkillRegistry()
+    if not bundled_skills_disabled():
+        _register_debug(registry)
+        _register_simplify(registry)
+        _register_batch(registry)
+        _register_update_config(registry)
+    _registry = registry
+    return registry
+
+
+def get_bundled_skill_commands() -> list[SkillCommand]:
+    return init_bundled_skills().list_commands()
+
+
+def reset_bundled_skills_for_tests() -> None:
+    """测试专用：清空进程级 registry。"""
+    global _registry
+    _registry = None
+
+
+__all__ = [
+    "BundledSkillDefinition",
+    "BundledSkillRegistry",
+    "get_bundled_skill_commands",
+    "init_bundled_skills",
+    "reset_bundled_skills_for_tests",
+]