mosscode 0.1.0__py3-none-any.whl

mosscode/coordinator.py

@@ -0,0 +1,54 @@
+"""Coordinator mode, a role for the lead — it plans and delegates, members implement.
+
+A role constraint, not a security boundary: execute_command can still write files, and the permission
+rules apply as always.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+ENV = "MOSSCODE_COORDINATOR_MODE"
+ON_VALUES = ("1", "true", "yes")
+BADGE = "[协调]"
+STATUS = "协调者模式（配置与环境变量均已开启）"
+NO_ENV = f"协调者模式未开启：配置中 coordinator_mode 为 true，但环境变量 {ENV} 没有设为 1、true 或 yes。"
+NO_CONFIG = f"协调者模式未开启：已设置环境变量 {ENV}，但配置中 coordinator_mode 不是 true。"
+HEADLESS = "协调者模式只用于交互界面，本次运行按普通模式。"
+NO_AGENTS = "协调者模式需要工具和 Agent 团队，本次运行按普通模式。"
+WITHHELD = "协调者模式下 Lead 不使用 {name}：把实施交给团队成员或子 Agent，或用 execute_command 运行只读检查。"
+WRITE_TOOLS = frozenset({"write_file", "edit_file"})
+
+SECTION = """## 协调者模式
+
+你是协调者：负责调查、拆分、派发和验证，不亲自改代码。没有 write_file、edit_file、MCP 工具和 Skill 脚本工具；execute_command 只用于只读的查看和检查。按四个阶段工作：
+1. 调查：读代码，或派只读的子 Agent 并行调查，弄清改动范围。子 Agent 只做调查和运行测试，不派它改文件。
+2. 综合：把工作拆成任务，用 team_task_create 写清每个任务的范围、完成标准和依赖（blocked_by）。
+3. 实施：所有文件改动（哪怕只有一行）都由 team_spawn 创建的成员在自己的工作树中完成，合并时由用户确认。派发后不要自己动手，有问题用 send_message 沟通。
+4. 验证：让成员或子 Agent 运行测试；team_merge 合并后，你可以自己运行只读的检查（测试、git log、git diff），再向用户汇报。"""
+
+
+def env_on(env: Mapping[str, str]) -> bool:
+    return env.get(ENV, "").strip().lower() in ON_VALUES
+
+
+def decide(configured: bool, env: Mapping[str, str], *, interactive: bool) -> tuple[bool, str]:
+    """On only with both switches, in the interactive UI; the notice says why not."""
+    environment = env_on(env)
+    if configured and not environment:
+        return False, NO_ENV
+    if environment and not configured:
+        return False, NO_CONFIG
+    if not configured:
+        return False, ""
+    if not interactive:
+        return False, HEADLESS
+    return True, ""
+
+
+def withheld(tool) -> bool:
+    """Kept in the registry for sub-agents and members, but not offered to the lead."""
+    from .mcp_client import MCPTool
+    from .tools.skill import SkillTool
+
+    return tool.name in WRITE_TOOLS or isinstance(tool, (MCPTool, SkillTool))

mosscode/doctor.py

@@ -0,0 +1,303 @@
+"""`moss doctor` reads the installation, the configuration and the tools it relies on.
+
+It starts no session and sends no request. Credentials are reported as set or not, never shown.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+OK, WARN, ERROR = "✓", "!", "✗"
+
+
+@dataclass(frozen=True)
+class Item:
+    level: str
+    text: str
+    fix: str = ""
+
+
+def _distribution():
+    from importlib.metadata import PackageNotFoundError, distribution
+
+    try:
+        return distribution("mosscode")
+    except PackageNotFoundError:
+        return None
+
+
+def install_method(prefix: str | None = None, dist=None) -> str:
+    prefix = sys.prefix if prefix is None else prefix
+    parts = [part.lower() for part in Path(prefix).parts]
+    if "uv" in parts and "tools" in parts:
+        kind = "uv tool"
+    elif "pipx" in parts:
+        kind = "pipx"
+    elif sys.prefix != sys.base_prefix:
+        kind = f"虚拟环境 {prefix}"
+    else:
+        kind = f"Python 环境 {prefix}"
+    try:
+        direct = json.loads(dist.read_text("direct_url.json") or "{}") if dist is not None else {}
+    except (ValueError, OSError):
+        direct = {}
+    if (direct.get("dir_info") or {}).get("editable"):
+        source = direct.get("url", "").removeprefix("file:///").removeprefix("file://")
+        kind += f"，可编辑安装（源码 {Path(source)}）" if source else "，可编辑安装"
+    return kind
+
+
+def check_install() -> list[Item]:
+    from .launcher import version
+
+    dist = _distribution()
+    items = [
+        Item(OK, f"mosscode {version()}（命令 moss 与 mosscode 相同）"),
+        Item(OK, f"Python {sys.version.split()[0]}：{sys.executable}"),
+    ]
+    if dist is None:
+        items.append(
+            Item(WARN, "mosscode 没有安装，正直接从源码运行", "在仓库中运行 uv tool install --editable . 安装为命令")
+        )
+    else:
+        items.append(Item(OK, "安装方式：" + install_method(dist=dist)))
+    return items
+
+
+def _all_on_path(name: str, path: str | None = None) -> list[Path]:
+    found, seen = [], set()
+    extensions = os.environ.get("PATHEXT", ".EXE").split(os.pathsep) if os.name == "nt" else [""]
+    for folder in (os.environ.get("PATH", "") if path is None else path).split(os.pathsep):
+        if not folder:
+            continue
+        for extension in extensions:
+            candidate = Path(folder) / (name + extension.lower())
+            key = os.path.normcase(str(candidate))
+            if key not in seen and candidate.is_file():
+                seen.add(key)
+                found.append(candidate)
+    return found
+
+
+def check_path(path: str | None = None, scripts: Path | None = None) -> list[Item]:
+    """Which moss / mosscode a new terminal runs, and whether it belongs to this installation."""
+    scripts = Path(sys.executable).parent if scripts is None else scripts
+    tool = install_method().startswith(("uv tool", "pipx"))
+    items = []
+    for name in ("moss", "mosscode"):
+        found = _all_on_path(name, path)
+        if not found:
+            items.append(
+                Item(WARN, f"PATH 中找不到 {name}", "用 uv tool 安装后运行 uv tool update-shell，再打开新的终端")
+            )
+            continue
+        first = found[0]
+        same = os.path.normcase(str(first.parent)) == os.path.normcase(str(scripts)) or tool
+        text = f"{name} → {first}" + ("" if same else "（不是当前运行的这一个）")
+        others = "；".join(str(item) for item in found[1:])
+        if len(found) > 1:
+            items.append(Item(WARN, text + f"；PATH 中还有 {others}", "排在前面的生效；卸载不用的那一个"))
+        else:
+            items.append(Item(OK if same else WARN, text, "" if same else "检查 PATH 的顺序，或卸载旧的安装"))
+    return items
+
+
+def _credential(provider) -> tuple[str, str]:
+    if provider.api_key_env:
+        if os.environ.get(provider.api_key_env):
+            return OK, f"环境变量 {provider.api_key_env} 已设置"
+        return WARN, f"环境变量 {provider.api_key_env} 未设置"
+    if provider.api_key:
+        return OK, "已设置（配置文件中的 api_key）"
+    return WARN, "未配置"
+
+
+def check_config(config: str | None = None, cwd: Path | None = None, home: Path | None = None) -> list[Item]:
+    from .config import ConfigError, find_config, load_settings
+    from .setup import OFFICIAL
+
+    cwd = Path.cwd() if cwd is None else cwd
+    items = []
+    try:
+        path = Path(config) if config is not None else find_config(cwd, home)
+    except ConfigError as exc:
+        items.append(Item(ERROR, str(exc).split("。")[0], "运行 moss setup 创建配置，或用 --config 指定"))
+        path = None
+    if path is not None:
+        try:
+            settings = load_settings(path)
+        except ConfigError as exc:
+            items.append(Item(ERROR, f"配置 {path}：{exc}", "对照 config.example.yaml 修改"))
+        else:
+            items.append(Item(OK, f"配置 {path}"))
+            for provider in settings.providers:
+                level, credential = _credential(provider)
+                host = (
+                    urlsplit(provider.base_url).hostname
+                    if provider.base_url
+                    else f"{urlsplit(OFFICIAL[provider.protocol]).hostname}（官方地址）"
+                )
+                default = "（默认）" if provider.name == settings.default_provider else ""
+                items.append(
+                    Item(
+                        level,
+                        f"Provider {provider.name}{default}：{provider.protocol} · {provider.model}"
+                        f" · {host} · 凭据：{credential}",
+                        ""
+                        if level == OK
+                        else f"设置环境变量 {provider.api_key_env} 后打开新的终端"
+                        if provider.api_key_env
+                        else "在配置中填写 api_key_env",
+                    )
+                )
+    legacy = cwd / "config.yaml"
+    if config is None and legacy.is_file():
+        items.append(
+            Item(
+                WARN,
+                f"{legacy} 不会被读取（只查找 .mosscode/config.yaml 和 ~/.mosscode/config.yaml）",
+                f"需要用它时加 --config {legacy}",
+            )
+        )
+    return items
+
+
+def check_tools(which=shutil.which, windows: bool | None = None) -> list[Item]:
+    windows = os.name == "nt" if windows is None else windows
+    items = []
+    rg = which("rg")
+    items.append(
+        Item(OK, f"ripgrep：{rg}")
+        if rg
+        else Item(
+            WARN,
+            "找不到 ripgrep（rg）：搜索改用较慢的内置实现",
+            "安装 ripgrep，例如 winget install BurntSushi.ripgrep.MSVC",
+        )
+    )
+    git = which("git")
+    items.append(
+        Item(OK, f"git：{git}")
+        if git
+        else Item(WARN, "找不到 git：工作树、团队合并和差异不可用", "安装 Git for Windows")
+    )
+    if windows:
+        from .tools.shell import git_bash
+
+        bash = git_bash()
+        items.append(
+            Item(OK, f"Git Bash：{bash}")
+            if bash
+            else Item(
+                WARN,
+                "找不到 Git Bash：命令改用 PowerShell 执行",
+                "安装 Git for Windows，或在配置中设 shell: powershell",
+            )
+        )
+        wt = which("wt")
+        items.append(
+            Item(OK, f"Windows Terminal：{wt}")
+            if wt
+            else Item(WARN, "找不到 wt.exe：团队成员无法在分屏窗格中运行，改为进程内运行", "安装 Windows Terminal")
+        )
+    return items
+
+
+def check_home(home: Path | None = None) -> list[Item]:
+    from .paths import mosscode_home
+
+    folder = mosscode_home(home)
+    try:
+        folder.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(dir=folder, prefix=".doctor-", delete=True):
+            pass
+    except OSError as exc:
+        return [Item(ERROR, f"{folder} 不可写：{exc.strerror or exc}", "检查这个目录的权限")]
+    return [Item(OK, f"{folder} 可写")]
+
+
+def check_project(cwd: Path | None = None, config: str | None = None, home: Path | None = None) -> list[Item]:
+    """The project's own files under .mosscode/; nothing when it has none."""
+    cwd = Path.cwd() if cwd is None else cwd
+    from .paths import mosscode_home
+
+    folder = cwd / ".mosscode"
+    if not folder.is_dir() or os.path.normcase(os.path.abspath(folder)) == os.path.normcase(
+        os.path.abspath(mosscode_home(home))
+    ):  # In the home folder it is the user folder, not a project's.
+        return []
+    items = []
+    project_config = folder / "config.yaml"
+    if config is not None and project_config.is_file():  # Without --config it is the one checked above.
+        from .config import ConfigError, load_settings
+
+        try:
+            load_settings(project_config)
+        except ConfigError as exc:
+            items.append(Item(ERROR, f"{project_config}：{exc}", "对照 config.example.yaml 修改"))
+    from .permissions import PermissionConfigError, read_policy
+
+    for path in (folder / "permissions.yaml", folder / "permissions.local.yaml"):
+        try:
+            read_policy(path)
+        except PermissionConfigError as exc:
+            items.append(Item(ERROR, str(exc), "修改后重新启动"))
+    from .mcp_config import MCPConfigError, load_mcp_settings
+
+    try:
+        mcp = load_mcp_settings(cwd, user_path=None if home is None else home / ".mosscode" / "mcp.yaml")
+    except MCPConfigError as exc:
+        items.append(Item(ERROR, f"MCP 配置：{exc}", "修改 .mosscode/mcp.yaml"))
+    else:
+        items.extend(Item(WARN, notice) for notice in mcp.notices)
+    from .hooks.config import hook_paths, read_file
+
+    for source, path in hook_paths(cwd, home):
+        if source != "user":
+            items.extend(Item(WARN, issue) for issue in read_file(source, path)[1])
+    if not items:
+        items.append(Item(OK, f"项目配置 {folder} 可以解析"))
+    return items
+
+
+def run(config: str | None = None) -> list[Item]:
+    return [
+        *check_install(),
+        *check_path(),
+        *check_config(config),
+        *check_home(),
+        *check_tools(),
+        *check_project(config=config),
+    ]
+
+
+def report(items: list[Item]) -> str:
+    lines = []
+    for item in items:
+        lines.append(f"{item.level} {item.text}")
+        if item.fix and item.level != OK:
+            lines.append(f"    → {item.fix}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    command = argparse.ArgumentParser(
+        prog="moss doctor", description="检查安装、配置和依赖工具；不启动会话，不发送请求。"
+    )
+    command.add_argument("--config", help="检查这个配置文件，而不是按默认顺序查找")
+    args = command.parse_args(argv)
+    items = run(args.config)
+    text = report(items)
+    try:
+        print(text)
+    except UnicodeEncodeError:  # A console that cannot show ✓ and ✗.
+        print(text.encode(sys.stdout.encoding or "ascii", "replace").decode(sys.stdout.encoding or "ascii"))
+    return 1 if any(item.level == ERROR for item in items) else 0

mosscode/hooks/__init__.py

@@ -0,0 +1,22 @@
+"""User-defined hooks at the agent's lifecycle points."""
+
+from .conditions import HookConfigError, parse_condition
+from .config import Hook, HookConfig, HookFile, TrustStore, hook_paths, load_hooks
+from .engine import HookEngine, HookEvent, HookOutcome, tool_event
+from .events import EVENTS
+
+__all__ = [
+    "EVENTS",
+    "Hook",
+    "HookConfig",
+    "HookConfigError",
+    "HookEngine",
+    "HookEvent",
+    "HookFile",
+    "HookOutcome",
+    "TrustStore",
+    "hook_paths",
+    "load_hooks",
+    "parse_condition",
+    "tool_event",
+]

mosscode/hooks/actions.py

@@ -0,0 +1,151 @@
+"""Run one hook action and report what happened; the engine decides what it means."""
+
+import asyncio
+import json
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from .config import TEMPLATE, Action
+
+STREAM_HALF = 16 * 1024  # Head and tail of stdout and stderr: 32 KB each.
+BODY_LIMIT = 64 * 1024
+DETAIL_LIMIT = 500
+FEEDBACK_LIMIT = 8000
+REJECT_LIMIT = 2000
+
+
+@dataclass(frozen=True)
+class ActionResult:
+    outcome: str  # ok, failed, rejected, timeout, skipped
+    detail: str = ""  # Failure reason or the end of the output, for the log and the notice.
+    output: str = ""  # Text for the model: a prompt message or command feedback.
+    exit_code: int | None = None
+    status: int | None = None
+    reason: str = ""  # Dynamic rejection (exit code 2).
+
+
+def short(text: str, limit: int = DETAIL_LIMIT) -> str:
+    text = text.strip()
+    return text if len(text) <= limit else "…" + text[-limit:]
+
+
+def render(text: str, fields) -> str:
+    """{{field}} becomes the field's value; only ever in text for the model or a JSON string."""
+    return TEMPLATE.sub(lambda match: str(fields.get(match[1], "")), text)
+
+
+def render_json(value, fields):
+    if isinstance(value, str):
+        return render(value, fields)
+    if isinstance(value, dict):
+        return {key: render_json(item, fields) for key, item in value.items()}
+    if isinstance(value, list):
+        return [render_json(item, fields) for item in value]
+    return value
+
+
+def public_url(url: str) -> str:
+    """Never log query strings (they often carry tokens)."""
+    return urlsplit(url)._replace(query="", fragment="").geturl()
+
+
+def _executable(first: str) -> str | None:
+    if os.sep in first or "/" in first:
+        return first if Path(first).is_file() else None
+    return shutil.which(first)
+
+
+def argv(command: tuple[str, ...], values: dict[str, str]) -> list[str]:
+    """Each ${NAME} becomes one whole argument's text; nothing is re-split or interpreted."""
+    parts = []
+    for part in command:
+        for name, value in values.items():
+            part = part.replace("${" + name + "}", value)
+        parts.append(part)
+    return parts
+
+
+async def run_command(
+    action: Action, *, root: Path, shell, env: dict[str, str], values: dict[str, str], stdin: bytes, rejecting: bool
+) -> ActionResult:
+    from ..tools.base import ToolFailure
+    from ..tools.process import run_process
+
+    if isinstance(action.command, str):
+        if shell is None:
+            return ActionResult("failed", "没有可用的 shell，无法执行字符串命令；可改用 argv 数组。")
+        args = shell.args(action.command)
+        environment = {**(shell.env(action.command) or os.environ), **env}
+    else:
+        args = argv(action.command, values)
+        found = _executable(args[0])
+        if found is None:
+            return ActionResult("failed", f"找不到命令：{args[0]}")
+        args[0] = found
+        environment = {**os.environ, **env}
+    try:
+        details = await asyncio.wait_for(
+            run_process(args, root, check=False, limit=STREAM_HALF, tail=STREAM_HALF, env=environment, input=stdin),
+            timeout=action.timeout,
+        )
+    except TimeoutError:
+        return ActionResult("timeout", f"超过 {action.timeout:g} 秒未结束，已终止。")
+    except ToolFailure as exc:
+        return ActionResult("failed", str(exc))
+    except OSError as exc:
+        return ActionResult("failed", f"无法启动命令：{exc.strerror or type(exc).__name__}")
+    code, stdout, stderr = details["exit_code"], details["stdout"], details["stderr"]
+    if code == 0:
+        output = stdout.strip()[:FEEDBACK_LIMIT] if action.feedback else ""
+        return ActionResult("ok", short(stdout), output, exit_code=0)
+    if code == 2 and rejecting:
+        reason = (stderr.strip() or stdout.strip() or "未说明原因")[:REJECT_LIMIT]
+        return ActionResult("rejected", short(reason), exit_code=2, reason=reason)
+    tail = short(stderr) or short(stdout)
+    return ActionResult("failed", f"退出码为 {code}" + (f"：{tail}" if tail else ""), exit_code=code)
+
+
+async def run_http(action: Action, *, fields, context: dict) -> ActionResult:
+    import httpx
+
+    body = None
+    if action.has_json:
+        body = render_json(action.json_body, fields)
+    elif action.method in {"POST", "PUT", "PATCH"}:
+        body = context
+    options = {"json": body} if body is not None else {}
+
+    async def send():
+        async with httpx.AsyncClient(follow_redirects=False, timeout=action.timeout) as client:
+            async with client.stream(action.method, action.url, headers=dict(action.headers), **options) as response:
+                data = bytearray()
+                async for chunk in response.aiter_bytes():
+                    data.extend(chunk)
+                    if len(data) >= BODY_LIMIT:
+                        break
+                return response.status_code, bytes(data[:BODY_LIMIT]).decode("utf-8", errors="replace")
+
+    try:
+        status, text = await asyncio.wait_for(send(), timeout=action.timeout)
+    except (TimeoutError, httpx.TimeoutException):
+        return ActionResult("timeout", f"{public_url(action.url)} 超过 {action.timeout:g} 秒未响应。")
+    except httpx.HTTPError as exc:
+        return ActionResult("failed", f"{public_url(action.url)} 请求失败（{type(exc).__name__}）。")
+    if 200 <= status < 300:
+        return ActionResult("ok", text[:DETAIL_LIMIT], status=status)
+    return ActionResult(
+        "failed",
+        f"{public_url(action.url)} 返回 HTTP {status}" + (f"：{text[:200]}" if text.strip() else ""),
+        status=status,
+    )
+
+
+def stdin_json(context: dict) -> bytes:
+    return json.dumps(context, ensure_ascii=False, default=str).encode("utf-8")
+
+
+PYTHON = sys.executable