mindcode 0.2.0__py3-none-any.whl

mindcode/config.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+CONFIG_DIR = Path.home() / ".cache" / "mindcode"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+SESSIONS_DIR = CONFIG_DIR / "sessions"
+
+
+CONFIG_TEMPLATE = """\
+# mindcode configuration
+# Located at: ~/.cache/mindcode/config.toml
+#
+# Edit this file to add or modify channels. API keys are stored locally
+# and never sent anywhere except the channel endpoint.
+#
+# Inside the mindcode REPL you can also:
+#   /channels         pick or add an API channel
+#   /models           list and switch models of current channel
+
+# Channel used when -p/--provider is not passed on the command line.
+default_provider = "rotor"
+
+# ────────────────────────────────────────────────────────────────────────
+# Rotor gateway — OpenAI-compatible gateway endpoint
+# ────────────────────────────────────────────────────────────────────────
+[providers.rotor]
+protocol = "openai"
+api_key = ""
+base_url = "http://127.0.0.1:8000/v1"
+default_model = "glm-5.2"
+models = [
+    "glm-5.2",
+    "glm-5.1",
+    "glm-4.7",
+]
+"""
+
+
+@dataclass
+class ProviderConfig:
+    name: str
+    api_key: str
+    base_url: str
+    default_model: str
+    protocol: str = "openai"
+    models: list[str] = field(default_factory=list)
+
+    def resolve_model(self, override: str | None) -> str:
+        if override:
+            return override
+        if self.default_model:
+            return self.default_model
+        if self.models:
+            return self.models[0]
+        raise ValueError(f"provider {self.name} 没有可用 model")
+
+    def validate(self) -> list[str]:
+        problems: list[str] = []
+        if self.protocol not in {"openai", "anthropic"}:
+            problems.append(
+                f"providers.{self.name}.protocol 不支持: {self.protocol}"
+            )
+        if not self.api_key:
+            problems.append(f"providers.{self.name}.api_key 未配置")
+        if not self.base_url:
+            problems.append(f"providers.{self.name}.base_url 未配置")
+        try:
+            self.resolve_model(None)
+        except ValueError as exc:
+            problems.append(str(exc))
+        return problems
+
+
+@dataclass
+class MindcodeConfig:
+    default_provider: str
+    providers: dict[str, ProviderConfig]
+    config_path: Path
+
+    def get_provider(self, name: str | None) -> ProviderConfig:
+        target = name or self.default_provider
+        if not target:
+            raise ValueError(
+                "config.toml 中未设置 default_provider，"
+                "请用 -p/--provider 显式指定"
+            )
+        if target not in self.providers:
+            available = ", ".join(sorted(self.providers)) or "(无)"
+            raise ValueError(
+                f"未知 provider: {target}；可用: {available}"
+            )
+        return self.providers[target]
+
+
+def _render_toml(
+    default_provider: str,
+    providers: dict[str, ProviderConfig],
+) -> str:
+    lines: list[str] = [
+        "# mindcode configuration",
+        f"# Located at: {CONFIG_FILE}",
+        "# Edit this file to add or modify providers.",
+        "",
+        f'default_provider = "{default_provider}"',
+        "",
+    ]
+    for name, p in providers.items():
+        lines.append(f"[providers.{name}]")
+        lines.append(f'protocol = "{p.protocol}"')
+        lines.append(f'api_key = "{p.api_key}"')
+        lines.append(f'base_url = "{p.base_url}"')
+        lines.append(f'default_model = "{p.default_model}"')
+        if len(p.models) <= 1:
+            inner = ", ".join(f'"{m}"' for m in p.models)
+            lines.append(f"models = [{inner}]")
+        else:
+            lines.append("models = [")
+            for m in p.models:
+                lines.append(f'    "{m}",')
+            lines.append("]")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def load_config(path: Path | None = None) -> MindcodeConfig:
+    """Load config from path; create with template if missing."""
+    config_path = path or CONFIG_FILE
+    if not config_path.exists():
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text(CONFIG_TEMPLATE, encoding="utf-8")
+        os.chmod(config_path, 0o600)
+    return _read_config(config_path)
+
+
+def save_config(config: MindcodeConfig) -> None:
+    """Write config back to its config_path atomically."""
+    path = config.config_path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = _render_toml(config.default_provider, config.providers)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+
+
+def _read_config(path: Path) -> MindcodeConfig:
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    providers_raw = data.get("providers", {})
+    if not isinstance(providers_raw, dict):
+        providers_raw = {}
+    providers: dict[str, ProviderConfig] = {}
+    for name, raw in providers_raw.items():
+        if not isinstance(raw, dict):
+            continue
+        providers[name] = ProviderConfig(
+            name=name,
+            protocol=str(raw.get("protocol", "openai")),
+            api_key=str(raw.get("api_key", "")),
+            base_url=str(raw.get("base_url", "")),
+            default_model=str(raw.get("default_model", "")),
+            models=list(raw.get("models", []) or []),
+        )
+    return MindcodeConfig(
+        default_provider=str(data.get("default_provider", "")),
+        providers=providers,
+        config_path=path,
+    )

mindcode/mcp.py

@@ -0,0 +1,205 @@
+"""Minimal MindCode-side MCP client and tool adapter.
+
+This module deliberately defines a transport-neutral client protocol. A host
+can provide an MCP implementation, while tests can use a tiny in-memory fake;
+MindCode itself does not add a network dependency.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from mindagent.core import ActionRisk
+from mindagent.tools.base import BaseTool, ToolContext, ToolDefinition
+
+
+@dataclass(frozen=True)
+class MCPToolSpec:
+    """Transport-independent description returned by an MCP server."""
+
+    name: str
+    description: str = ""
+    input_schema: dict[str, Any] = field(
+        default_factory=lambda: {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        }
+    )
+    risk: ActionRisk = ActionRisk.WRITE
+
+    def __post_init__(self) -> None:
+        name = self.name.strip()
+        if not name:
+            raise ValueError("MCP tool name 不能为空")
+        if not isinstance(self.input_schema, dict):
+            raise TypeError("MCP tool input_schema 必须是 object schema")
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "description", self.description.strip())
+        object.__setattr__(self, "input_schema", dict(self.input_schema))
+        if not isinstance(self.risk, ActionRisk):
+            object.__setattr__(self, "risk", _coerce_risk(self.risk))
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, Any]) -> "MCPToolSpec":
+        annotations = value.get("annotations")
+        if not isinstance(annotations, Mapping):
+            annotations = {}
+        risk = value.get("risk", annotations.get("risk"))
+        if risk is None and annotations.get("readOnlyHint") is True:
+            risk = ActionRisk.READ_ONLY
+        if risk is None and annotations.get("destructiveHint") is True:
+            risk = ActionRisk.DANGEROUS
+        return cls(
+            name=str(value.get("name", "")),
+            description=str(value.get("description", "")),
+            input_schema=dict(
+                value.get("input_schema", value.get("inputSchema", {}))
+                or {}
+            ),
+            risk=_coerce_risk(risk),
+        )
+
+
+@runtime_checkable
+class MCPClient(Protocol):
+    """Small client contract required by :func:`adapt_mcp_tools`.
+
+    ``list_tools`` is synchronous so runtime construction remains synchronous;
+    ``call_tool`` may return a value or an awaitable.
+    """
+
+    def list_tools(self) -> Iterable[MCPToolSpec | Mapping[str, Any]]: ...
+
+    def call_tool(self, name: str, arguments: dict[str, Any]) -> Any: ...
+
+
+class MCPToolAdapter(BaseTool):
+    """Expose one MCP tool through MindAgent's ordinary ``BaseTool`` API."""
+
+    def __init__(
+        self,
+        client: MCPClient,
+        spec: MCPToolSpec | Mapping[str, Any],
+        *,
+        namespace: str | None = None,
+        close_client: bool = False,
+    ):
+        self.client = client
+        self.spec = _coerce_spec(spec)
+        self._close_client = close_client
+        public_name = self.spec.name
+        if namespace:
+            public_name = f"{namespace}_{public_name}"
+        self.definition = ToolDefinition(
+            name=public_name,
+            description=self.spec.description or f"MCP tool {self.spec.name}",
+            parameters=self.spec.input_schema,
+            risk=self.spec.risk,
+        )
+
+    async def execute(
+        self,
+        arguments: dict[str, Any],
+        context: ToolContext,
+    ) -> Any:
+        result = self.client.call_tool(self.spec.name, arguments)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    async def close(self) -> None:
+        if not self._close_client:
+            return
+        self._close_client = False
+        close = getattr(self.client, "close", None)
+        if close is None:
+            close = getattr(self.client, "aclose", None)
+        if callable(close):
+            result = close()
+            if inspect.isawaitable(result):
+                await result
+
+
+def adapt_mcp_tools(
+    client: MCPClient,
+    *,
+    namespace: str | None = None,
+) -> list[MCPToolAdapter]:
+    """Discover a synchronous MCP client and return ordinary BaseTool adapters."""
+    listed = client.list_tools()
+    if inspect.isawaitable(listed):
+        raise TypeError(
+            "MCPClient.list_tools() 必须同步；异步客户端请先在宿主侧发现工具"
+        )
+    if isinstance(listed, Mapping):
+        listed = listed.get("tools", ())
+    specs = [_coerce_spec(value) for value in listed]
+    return [
+        MCPToolAdapter(
+            client,
+            spec,
+            namespace=namespace,
+            close_client=index == 0,
+        )
+        for index, spec in enumerate(specs)
+    ]
+
+
+async def aload_mcp_tools(
+    client: MCPClient,
+    *,
+    namespace: str | None = None,
+) -> list[MCPToolAdapter]:
+    """Async counterpart for clients whose tool discovery is awaitable."""
+    listed = client.list_tools()
+    if inspect.isawaitable(listed):
+        listed = await listed
+    if isinstance(listed, Mapping):
+        listed = listed.get("tools", ())
+    specs = [_coerce_spec(value) for value in listed]
+    return [
+        MCPToolAdapter(
+            client,
+            spec,
+            namespace=namespace,
+            close_client=index == 0,
+        )
+        for index, spec in enumerate(specs)
+    ]
+
+
+def _coerce_spec(value: MCPToolSpec | Mapping[str, Any]) -> MCPToolSpec:
+    if isinstance(value, MCPToolSpec):
+        return value
+    if isinstance(value, Mapping):
+        return MCPToolSpec.from_mapping(value)
+    raise TypeError("MCP tools 必须是 MCPToolSpec 或 mapping")
+
+
+def _coerce_risk(value: Any) -> ActionRisk:
+    if isinstance(value, ActionRisk):
+        return value
+    if value is None:
+        return ActionRisk.WRITE
+    try:
+        return ActionRisk(str(value).lower())
+    except ValueError as exc:
+        raise ValueError(f"未知 MCP tool risk: {value}") from exc
+
+
+# Common spelling for callers that model MCP's tool description directly.
+MCPToolDefinition = MCPToolSpec
+
+
+__all__ = [
+    "MCPClient",
+    "MCPToolAdapter",
+    "MCPToolDefinition",
+    "MCPToolSpec",
+    "adapt_mcp_tools",
+    "aload_mcp_tools",
+]

mindcode/policy.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from enum import Enum
+
+from mindagent.core import (
+    ActionRequest,
+    ActionRisk,
+    AgentContext,
+    ValidationResult,
+)
+
+
+class ApprovalMode(str, Enum):
+    """The two supported MindCode permission modes.
+
+    ``ASK`` and ``AUTO`` remain enum aliases so sessions created by older
+    MindCode versions keep working. Their values are the new canonical
+    ``ask_user`` and ``full_accept`` values. Short CLI spellings are handled
+    by ``_missing_`` for the same migration reason.
+    """
+
+    ASK_USER = "ask_user"
+    FULL_ACCEPT = "full_accept"
+
+    # Source compatibility for callers that imported the old names.
+    ASK = ASK_USER
+    AUTO = FULL_ACCEPT
+
+    @classmethod
+    def _missing_(cls, value: object) -> "ApprovalMode | None":
+        if not isinstance(value, str):
+            return None
+        aliases = {
+            "ask": cls.ASK_USER,
+            "full": cls.FULL_ACCEPT,
+            "full-access": cls.FULL_ACCEPT,
+            "auto": cls.FULL_ACCEPT,
+        }
+        return aliases.get(value.strip().lower())
+
+
+def approval_mode_label(mode: ApprovalMode | str) -> str:
+    """Return the user-facing name for an approval mode."""
+    selected = ApprovalMode(mode)
+    if selected is ApprovalMode.ASK_USER:
+        return "Ask User"
+    return "Full Accept"
+
+
+ApprovalCallback = Callable[[AgentContext, ActionRequest], Awaitable[bool]]
+
+
+def _validate_session_policy(
+    context: AgentContext,
+    action: ActionRequest,
+) -> ValidationResult | None:
+    """Enforce session-scoped capability limits before mode approval.
+
+    MindCode's policy is the first extension invoked by ``AgentRuntime`` when
+    a custom policy is installed, so it must retain the same capability
+    checks as MindAgent's default policy instead of relying on a separate
+    ``AgentSession`` wrapper.
+    """
+    session_policy = context.session_policy
+    if session_policy is None:
+        return None
+    if (
+        session_policy.allowed_action_types is not None
+        and action.action_type not in session_policy.allowed_action_types
+    ):
+        return ValidationResult(False, "当前 session 不允许该 action 类型")
+    if (
+        session_policy.allowed_tools is not None
+        and action.name not in session_policy.allowed_tools
+    ):
+        return ValidationResult(
+            False,
+            f"当前 session 不允许工具: {action.name}",
+        )
+    if action.risk == ActionRisk.WRITE and not session_policy.allow_write:
+        return ValidationResult(False, "当前 session 不允许写操作")
+    if (
+        action.risk == ActionRisk.DANGEROUS
+        and not session_policy.allow_dangerous
+    ):
+        return ValidationResult(False, "当前 session 不允许危险操作")
+    return None
+
+
+async def _default_approval_callback(
+    context: AgentContext,
+    action: ActionRequest,
+) -> bool:
+    """Ask in the MindCode shell when no host callback was supplied."""
+    # Lazy import avoids importing the CLI (and prompt_toolkit) for library
+    # users that construct a policy in a non-interactive process.
+    from .approval import describe_action
+    from .cli.shell.menu import prompt_yes_no
+
+    summary = describe_action(action)
+    return await prompt_yes_no(f"允许执行 {summary}?", default_yes=False)
+
+
+class AskUserPolicy:
+    """Allow reads and ask the user before writes or dangerous actions.
+
+    注意：validate_action 内阻塞式 confirm 是产品层授权等待（用户决策），
+    已豁免 step 超时、受 total_timeout 监督。未来 Policy 解耦（deferred +
+    挂起 validation 待审批后恢复）需 core 支持挂起/恢复机制，本次不做。
+    """
+
+    def __init__(self, confirm: ApprovalCallback | None = None):
+        self._confirm = confirm or _default_approval_callback
+
+    async def validate_action(
+        self,
+        context: AgentContext,
+        action: ActionRequest,
+    ) -> ValidationResult:
+        session_result = _validate_session_policy(context, action)
+        if session_result is not None:
+            return session_result
+        if action.risk == ActionRisk.READ_ONLY:
+            return ValidationResult(allowed=True, reason="只读动作已授权")
+        approved = await self._confirm(context, action)
+        if approved:
+            return ValidationResult(
+                allowed=True,
+                reason=f"用户已批准 {action.risk.value} 操作",
+            )
+        return ValidationResult(
+            allowed=False,
+            reason=f"用户拒绝执行 {action.risk.value} 操作",
+        )
+
+
+class FullAcceptPolicy:
+    """Allow every action selected by the current session policy."""
+
+    async def validate_action(
+        self,
+        context: AgentContext,
+        action: ActionRequest,
+    ) -> ValidationResult:
+        session_result = _validate_session_policy(context, action)
+        if session_result is not None:
+            return session_result
+        return ValidationResult(allowed=True, reason="full access 已授权")
+
+
+def make_policy(
+    mode: ApprovalMode | str,
+    *,
+    approval_callback: ApprovalCallback | None = None,
+) -> AskUserPolicy | FullAcceptPolicy:
+    """Build the product policy for ``mode``.
+
+    ``approval_callback`` is useful for a host UI or deterministic tests. The
+    interactive shell gets the default callback automatically.
+    """
+    selected = ApprovalMode(mode)
+    if selected is ApprovalMode.ASK_USER:
+        return AskUserPolicy(approval_callback)
+    if selected is ApprovalMode.FULL_ACCEPT:
+        return FullAcceptPolicy()
+    raise ValueError(f"未知 ApprovalMode: {mode}")
+
+
+# Compatibility names for callers that imported the old policy classes. They
+# intentionally map to the new two-mode semantics; there is no suggest mode.
+AskPolicy = AskUserPolicy
+AutoPolicy = FullAcceptPolicy