sci-agent 0.2.0__py3-none-any.whl

sci_agent-0.2.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: sci-agent
+Version: 0.2.0
+Summary: Agent-first lightweight CI/CD tool
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.29.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: python-dotenv>=1.0.0

sci_agent-0.2.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+simple_ci/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+simple_ci/__main__.py,sha256=YIoplXdVfuRoyOvqsoug6Od_-a249Ac1vvHpLQZHwhM,944
+simple_ci/errors.py,sha256=ynp6VbS1qW9AjfEYwXhaY3IKCl0IGGRoQqIS7TpEw0c,833
+simple_ci/models.py,sha256=6rCqAdyHQ-ZmFC9Jw7knf8Ll0ikJyNUF44AMhZvc12w,3289
+simple_ci/actions/__init__.py,sha256=eK5B9ao0l5smSECBFWhHAmRlmJ6iZ3mdEAe3LKKwcAA,5295
+simple_ci/actions/base.py,sha256=o-iTWZTqyHlCFC4jSv6_RS41YUULxZM44v_o3PJPIQ4,11205
+simple_ci/actions/build.py,sha256=C_yh33gUDYJzEdceYkuJQRdExU-vmtV8c9FSeg7zpuM,1028
+simple_ci/actions/deploy.py,sha256=JeSmmhnyd4zeDJqIAJKVr6LVxl5VJzoZJBRnXbYGJAc,774
+simple_ci/actions/hooks.py,sha256=WcG4xxaMhgMSH47jRrMvn63R7Op-BXgfTXVEX9K5uYU,5652
+simple_ci/actions/image.py,sha256=QRZbZ6CR1fTEKtTGlf0pbPqUk4b7XJVzXad7QsF1ahI,927
+simple_ci/actions/source.py,sha256=zpLlCyDebOHHbHXnOwrpYTqcM5E6iSwk9OuMYTfVhMo,1303
+simple_ci/actions/target.py,sha256=dQix1l8L_k6MZFTZs06WT736p7wB2P5VbVWH3OrGXvE,2452
+simple_ci/cli/__init__.py,sha256=HIkUk4xoUaWl5Ofb_TvkeI69rrjsn-8U5t2B9u-62t0,43
+simple_ci/cli/client.py,sha256=q15rE0lgtZsv2tGrmJ-ftjsI-ZpMdwf1tG6fW_Ysw5s,3753
+simple_ci/cli/config.py,sha256=5witFegb_enyu3DUS_CtehsaG3t74nInykW3hsuAb_g,10221
+simple_ci/cli/history.py,sha256=GJGIfT-XqVdWz48sUcZ-aVeepaAw6HhiYCO8YQmJQGs,3182
+simple_ci/cli/main.py,sha256=xgJ3J3hqBlS9UUvWzy1V7Pd5jOSihanKqiAApdmYmsI,12319
+simple_ci/cli/render.py,sha256=0w7ORoT5bDJD3XtsAAsHxpE3-Pp5ba4QLmTZTLd6R-A,4475
+simple_ci/server/__init__.py,sha256=LKhOcdwXsWF0t6Q_EEPns-ejWLOyUbkv3xOcSx_Pej0,37
+simple_ci/server/app.py,sha256=8rNfOfQkQD9PWaz-q6lpidRRxE-Rh_uSdtg2KOwMIUY,4290
+simple_ci/server/auth.py,sha256=5dJNbj4qYVghI4SOb27eDxDcPh51CFUmWl-UOSrcwtY,1238
+simple_ci/server/executor.py,sha256=iFj9wx7Isu7-RCWtSSBeiyTcXzfK2nuSyxZ8-fmqtjg,11510
+simple_ci/server/main.py,sha256=QRENvOsETmVZ54H0FqqyVsB83b5sUdSZ3OTWWE4Fqag,1277
+simple_ci/server/store.py,sha256=rb61GnyDTG8NMLnLM1UN8JG7IiUFNRC1yXJ4j-qllXM,5683
+simple_ci/ui/__init__.py,sha256=vS3jZTRIuS_rR1jQpByrZUZmdsAON_RKVJHF6nmEiuM,36
+simple_ci/ui/server.py,sha256=U1NdrD_1WjyhANXb1SZApPKbFWq0WuGqWkrIxTwsiLU,10490
+simple_ci/ui/static/index.html,sha256=DZCKag6wIkyFSmnglxugFA9u3HLqjo554MqRgIAb6i4,7421
+sci_agent-0.2.0.dist-info/METADATA,sha256=hXS44DQFzYwNrlPpSpz-mBIFEfXuAw17gzUM4d-_wPE,316
+sci_agent-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sci_agent-0.2.0.dist-info/entry_points.txt,sha256=lRMsTKjsUiJIN91rWAgolkwiMMHmV6w0rt6qXpfraiY,54
+sci_agent-0.2.0.dist-info/top_level.txt,sha256=hTpiAlOFooM9fjs8LKNs9u2T-ZhJimLn0rDiVQOk85M,10
+sci_agent-0.2.0.dist-info/RECORD,,

sci_agent-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sci_agent-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sci-agent = simple_ci.__main__:main

sci_agent-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simple_ci

simple_ci/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

simple_ci/__main__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import ctypes
+import sys
+
+
+def _configure_stdio_encoding() -> None:
+    if sys.platform == "win32":
+        try:
+            kernel32 = ctypes.windll.kernel32
+            kernel32.SetConsoleOutputCP(65001)
+            kernel32.SetConsoleCP(65001)
+        except Exception:
+            pass
+
+    for stream in (sys.stdout, sys.stderr, sys.stdin):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
+def main() -> None:
+    _configure_stdio_encoding()
+
+    argv = sys.argv[1:]
+    if argv and argv[0] == "server":
+        from simple_ci.server.main import handle_server
+
+        handle_server(argv[1:])
+    elif argv and argv[0] == "run":
+        from simple_ci.cli.main import handle_run
+
+        handle_run(argv[1:])
+    else:
+        from simple_ci.ui.server import run_ui
+
+        run_ui(argv)
+
+
+if __name__ == "__main__":
+    main()

simple_ci/actions/__init__.py

@@ -0,0 +1,136 @@
+"""内置动作入口与调度注册表。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from simple_ci.actions import base
+from simple_ci.actions.build import build_maven_command
+from simple_ci.actions.deploy import build_compose_command
+from simple_ci.actions.image import build_image_command, build_push_command
+from simple_ci.actions.source import build_git_pull_command
+from simple_ci.actions.target import build_target_shell_command
+
+ActionHandler = Callable[[dict[str, Any], dict[str, Any]], base.ActionResult]
+
+
+def dispatch_action(step: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+    """根据 step.uses 分发内置动作，并返回可 JSON 序列化的动作结果。"""
+
+    action_name = str(step.get("uses") or step.get("action") or "")
+    handler = ACTION_REGISTRY.get(action_name)
+    if handler is None:
+        return base.ActionResult(
+            rendered_command="",
+            exit_code=1,
+            stderr_tail=f"Unknown action: {action_name or '<missing>'}",
+        ).to_dict()
+    return handler(step, payload).to_dict()
+
+
+def _params(step: dict[str, Any]) -> dict[str, Any]:
+    """兼容配置文件中的 with 字段与 Python 调用中的 with_ 字段。"""
+
+    value = step.get("with", step.get("with_", {}))
+    return dict(value) if isinstance(value, dict) else {}
+
+
+def _run_built_command(
+    command: list[str] | list[list[str]] | str,
+    params: dict[str, Any],
+    *,
+    allow_shell: bool = False,
+) -> base.ActionResult:
+    """统一执行命令并注入动作参数中的敏感值用于结果脱敏。"""
+
+    return base.run_command(
+        command,
+        cwd=params.get("cwd") or params.get("workdir"),
+        env=params.get("env"),
+        secret_values=base.collect_secret_values(params),
+        timeout_seconds=float(params.get("timeout_seconds", 300)),
+        allow_shell=allow_shell,
+    )
+
+
+def _source_git_pull(step: dict[str, Any], _payload: dict[str, Any]) -> base.ActionResult:
+    params = _params(step)
+    if isinstance(params.get("credential"), str):
+        message = "Unresolved credential id for source.git_pull; CLI must send a credential dict."
+        return base.ActionResult(rendered_command="", exit_code=1, stderr_tail=message, error=message)
+    return _run_built_command(build_git_pull_command(params), params)
+
+
+def _build_maven(step: dict[str, Any], _payload: dict[str, Any]) -> base.ActionResult:
+    params = _params(step)
+    return _run_built_command(build_maven_command(params), params)
+
+
+def _shell_action(step: dict[str, Any], _payload: dict[str, Any]) -> base.ActionResult:
+    params = _params(step)
+    command = params.get("command") or step.get("command")
+    if not isinstance(command, (str, list)):
+        return base.ActionResult(rendered_command="", exit_code=1, stderr_tail="Missing shell command.")
+    return _run_built_command(command, params, allow_shell=True)
+
+
+def _target_shell(step: dict[str, Any], payload: dict[str, Any]) -> base.ActionResult:
+    """执行目标脚本或 inline 命令；script 模式使用 argv，inline 字符串保留 shell 能力。"""
+
+    params = _params(step)
+    try:
+        command = build_target_shell_command(params, payload)
+    except ValueError as exc:
+        return base.ActionResult(rendered_command="", exit_code=1, stderr_tail=str(exc), error=str(exc))
+    return _run_built_command(command, params, allow_shell=isinstance(command, str))
+
+
+def _image_build(step: dict[str, Any], _payload: dict[str, Any]) -> base.ActionResult:
+    params = _params(step)
+    result = _run_built_command(build_image_command(params), params)
+    if result.exit_code == 0:
+        result.image_tag = f"{params['image']}:{params.get('tag', 'latest')}"
+    return result
+
+
+def _image_push(step: dict[str, Any], _payload: dict[str, Any]) -> base.ActionResult:
+    params = _params(step)
+    return _run_built_command(build_push_command(params), params)
+
+
+def _deploy_compose(step: dict[str, Any], _payload: dict[str, Any]) -> base.ActionResult:
+    params = _params(step)
+    return _run_built_command(build_compose_command(params), params)
+
+
+def _deploy_healthcheck(step: dict[str, Any], _payload: dict[str, Any]) -> base.ActionResult:
+    """执行 HTTP 健康检查；失败时以非零退出码进入流水线短路。"""
+
+    params = _params(step)
+    return base.run_healthcheck(
+        str(params.get("url", "")),
+        timeout=float(params.get("timeout", 10)),
+        expected_status=int(params.get("expected_status", 200)),
+        retries=int(params.get("retries", 0)),
+        interval_seconds=float(params.get("interval_seconds", 0)),
+        expect_body_contains=(
+            str(params["expect_body_contains"]) if params.get("expect_body_contains") is not None else None
+        ),
+        secret_values=base.collect_secret_values(params),
+    )
+
+
+ACTION_REGISTRY: dict[str, ActionHandler] = {
+    "source.git_pull": _source_git_pull,
+    "build.maven": _build_maven,
+    "build.shell": _shell_action,
+    "image.build": _image_build,
+    "image.push": _image_push,
+    "deploy.compose": _deploy_compose,
+    "deploy.healthcheck": _deploy_healthcheck,
+    "deploy.shell": _shell_action,
+    "target.shell": _target_shell,
+}
+
+__all__ = ["ACTION_REGISTRY", "dispatch_action"]

simple_ci/actions/base.py

@@ -0,0 +1,318 @@
+"""动作执行结果、命令运行与脱敏工具。"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote, urlsplit, urlunsplit
+
+import httpx
+
+TAIL_LIMIT = 10 * 1024
+SECRET_KEY_RE = re.compile(r"token|secret|password|credential", re.IGNORECASE)
+URL_CREDENTIAL_RE = re.compile(r"(https?://)([^/\s@]+)@")
+INLINE_SECRET_RE = re.compile(
+    r"(?i)(\b(?:--)?(?:token|password|secret|credential)(?:[_-]?[a-z0-9]+)?\b\s*(?:=|\s+))([^\s\"']+)"
+)
+
+
+@dataclass
+class ActionResult:
+    """动作统一结果；stdout/stderr 只保留尾部，命令与输出默认脱敏。"""
+
+    rendered_command: str = ""
+    exit_code: int | None = None
+    stdout_tail: str = ""
+    stderr_tail: str = ""
+    http_status: int | None = None
+    http_body: str | None = None
+    image_tag: str | None = None
+    retries: int = 0
+    error: str | None = None
+
+    @classmethod
+    def from_completed_command(
+        cls,
+        command: list[str] | str,
+        *,
+        exit_code: int,
+        stdout: str,
+        stderr: str,
+        secret_values: set[str] | None = None,
+    ) -> "ActionResult":
+        """从子进程结果构造动作结果，并对命令及日志尾部做统一脱敏。"""
+
+        rendered_command = render_command(command)
+        secrets = set(secret_values or set()) | infer_secrets_from_text(rendered_command)
+        return cls(
+            rendered_command=redact_secrets(rendered_command, secrets),
+            exit_code=exit_code,
+            stdout_tail=redact_secrets(tail_text(stdout), secrets),
+            stderr_tail=redact_secrets(tail_text(stderr), secrets),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """返回执行器可直接落库或序列化的稳定字典结构。"""
+
+        result: dict[str, Any] = {
+            "rendered_command": self.rendered_command,
+            "exit_code": self.exit_code,
+            "stdout_tail": self.stdout_tail,
+            "stderr_tail": self.stderr_tail,
+        }
+        optional_fields = {
+            "http_status": self.http_status,
+            "http_body": self.http_body,
+            "image_tag": self.image_tag,
+            "retries": self.retries,
+            "error": self.error,
+        }
+        for key, value in optional_fields.items():
+            if value not in (None, 0):
+                result[key] = value
+        return result
+
+
+def run_command(
+    command: list[str] | list[list[str]] | str,
+    *,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+    secret_values: set[str] | None = None,
+    timeout_seconds: float | None = None,
+    allow_shell: bool = False,
+) -> ActionResult:
+    """运行本地命令；仅显式 shell 动作允许字符串命令交给 shell 处理。"""
+
+    rendered_command = render_command(command)
+    commands = _normalize_commands(command)
+    stdout_parts: list[str] = []
+    stderr_parts: list[str] = []
+    exit_code = 0
+    timeout = 300 if timeout_seconds is None else timeout_seconds
+
+    for current in commands:
+        use_shell = isinstance(current, str)
+        if use_shell and not allow_shell:
+            return ActionResult(
+                rendered_command=redact_secrets(rendered_command, secret_values),
+                exit_code=1,
+                stderr_tail="String commands require an explicit shell action.",
+                error="String commands require an explicit shell action.",
+            )
+        try:
+            completed = subprocess.run(
+                current,
+                cwd=cwd,
+                env=env,
+                shell=use_shell,
+                check=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired as exc:
+            stdout = _coerce_timeout_text(exc.output)
+            stderr = _coerce_timeout_text(exc.stderr)
+            message = f"Command timed out after {timeout:g}s."
+            result = ActionResult.from_completed_command(
+                command,
+                exit_code=1,
+                stdout=stdout,
+                stderr=stderr or message,
+                secret_values=secret_values,
+            )
+            result.error = redact_secrets(message, set(secret_values or set()) | infer_secrets_from_text(rendered_command))
+            return result
+
+        stdout_parts.append(completed.stdout)
+        stderr_parts.append(completed.stderr)
+        exit_code = completed.returncode
+        if exit_code != 0:
+            break
+
+    return ActionResult.from_completed_command(
+        command,
+        exit_code=exit_code,
+        stdout="".join(stdout_parts),
+        stderr="".join(stderr_parts),
+        secret_values=secret_values,
+    )
+
+
+def _normalize_commands(command: list[str] | list[list[str]] | str) -> list[list[str] | str]:
+    """把单命令或多命令统一为顺序执行列表。"""
+
+    if isinstance(command, str):
+        return [command]
+    if command and all(isinstance(item, list) for item in command):
+        return command  # type: ignore[return-value]
+    return [command]  # type: ignore[list-item]
+
+
+def _coerce_timeout_text(value: str | bytes | None) -> str:
+    """TimeoutExpired 可能返回 bytes，统一转成可脱敏文本。"""
+
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return value
+
+
+def run_healthcheck(
+    url: str,
+    *,
+    timeout: float,
+    expected_status: int,
+    retries: int = 0,
+    interval_seconds: float = 0,
+    expect_body_contains: str | None = None,
+    secret_values: set[str] | None = None,
+) -> ActionResult:
+    """执行 HTTP GET 健康检查，支持状态码、正文包含断言和有限重试。"""
+
+    rendered = f"GET {url}"
+    secrets = set(secret_values or set()) | infer_secrets_from_text(rendered)
+    attempts = max(1, retries + 1)
+    last_result: ActionResult | None = None
+    for attempt_index in range(attempts):
+        try:
+            response = httpx.get(url, timeout=timeout)
+        except Exception as exc:  # noqa: BLE001 - 动作边界需要转换为失败结果。
+            message = redact_secrets(str(exc), secrets)
+            last_result = ActionResult(
+                rendered_command=redact_secrets(rendered, secrets),
+                exit_code=1,
+                stderr_tail=message,
+                retries=attempt_index,
+                error=message,
+            )
+        else:
+            last_result = _healthcheck_result(
+                rendered,
+                response,
+                expected_status=expected_status,
+                expect_body_contains=expect_body_contains,
+                retries=attempt_index,
+                secrets=secrets,
+            )
+        if last_result.exit_code == 0 or attempt_index == attempts - 1:
+            return last_result
+        if interval_seconds > 0:
+            time.sleep(interval_seconds)
+    return last_result or ActionResult(rendered_command=redact_secrets(rendered, secrets), exit_code=1)
+
+
+def _healthcheck_result(
+    rendered: str,
+    response: httpx.Response,
+    *,
+    expected_status: int,
+    expect_body_contains: str | None,
+    retries: int,
+    secrets: set[str],
+) -> ActionResult:
+    """把一次 HTTP 响应转换为健康检查结果，并生成可读失败原因。"""
+
+    body_tail = redact_secrets(tail_text(response.text), secrets)
+    errors: list[str] = []
+    if response.status_code != expected_status:
+        errors.append(f"Expected status {expected_status}, got {response.status_code}.")
+    if expect_body_contains is not None and expect_body_contains not in response.text:
+        errors.append("Expected response body to contain configured text.")
+    return ActionResult(
+        rendered_command=redact_secrets(rendered, secrets),
+        exit_code=0 if not errors else 1,
+        stdout_tail=body_tail,
+        stderr_tail=" ".join(errors),
+        http_status=response.status_code,
+        http_body=body_tail,
+        retries=retries,
+        error=" ".join(errors) or None,
+    )
+
+
+def render_command(command: list[str] | list[list[str]] | str) -> str:
+    """将命令参数渲染为日志友好的字符串；不负责 shell 转义语义。"""
+
+    if isinstance(command, str):
+        return command
+    if command and all(isinstance(item, list) for item in command):
+        return " && ".join(render_command(item) for item in command)  # type: ignore[arg-type]
+    return " ".join(str(part) for part in command)
+
+
+def tail_text(text: str, limit: int = TAIL_LIMIT) -> str:
+    """保留文本末尾指定字节级近似长度，避免超大日志进入 API 响应。"""
+
+    return text[-limit:]
+
+
+def collect_secret_values(value: Any) -> set[str]:
+    """递归收集 token/password/credential 等敏感字段值。"""
+
+    secrets: set[str] = set()
+
+    def collect(current: Any, key: str | None = None) -> None:
+        if isinstance(current, dict):
+            for child_key, child_value in current.items():
+                child_key_text = str(child_key)
+                if (
+                    (SECRET_KEY_RE.search(child_key_text) or key == "credential")
+                    and isinstance(child_value, str)
+                    and child_value
+                ):
+                    secrets.add(child_value)
+                    secrets.add(quote(child_value, safe=""))
+                collect(child_value, child_key_text)
+        elif isinstance(current, list):
+            for item in current:
+                collect(item, key)
+
+    collect(value)
+    return secrets
+
+
+def infer_secrets_from_text(value: str) -> set[str]:
+    """从 URL 凭据片段中提取用户名和密码，补足显式 secret 列表。"""
+
+    secrets: set[str] = set()
+    for match in URL_CREDENTIAL_RE.finditer(value):
+        credential = match.group(2)
+        if ":" in credential:
+            username, password = credential.split(":", 1)
+            secrets.add(username)
+            secrets.add(password)
+    return secrets
+
+
+def redact_secrets(value: str, secret_values: set[str] | None = None) -> str:
+    """脱敏 URL 凭据、敏感字段赋值和已知敏感值。"""
+
+    redacted = URL_CREDENTIAL_RE.sub(r"\1***:***@", value)
+    for secret in sorted(secret_values or set(), key=len, reverse=True):
+        if secret:
+            redacted = redacted.replace(secret, "***")
+    return INLINE_SECRET_RE.sub(r"\1***", redacted)
+
+
+def inject_basic_auth(repo: str, credential: dict[str, Any] | None) -> str:
+    """向 HTTPS Git URL 注入基础认证；非 HTTPS 地址保持原样。"""
+
+    if not credential:
+        return repo
+    username = credential.get("username")
+    password = credential.get("password")
+    if not username or not password:
+        return repo
+    parts = urlsplit(repo)
+    if parts.scheme not in {"http", "https"} or "@" in parts.netloc:
+        return repo
+    netloc = f"{quote(str(username), safe='')}:{quote(str(password), safe='')}@{parts.netloc}"
+    return urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment))

simple_ci/actions/build.py

@@ -0,0 +1,31 @@
+"""构建相关内置动作的命令构造。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_maven_command(params: dict[str, Any]) -> list[str]:
+    """根据模块、目标和属性构造 Maven 命令，函数本身不产生副作用。"""
+
+    command = ["mvn"]
+    module = params.get("module")
+    if module:
+        command.extend(["-pl", str(module)])
+    goals = params.get("goals") or [params.get("goal", "test")]
+    command.extend(str(goal) for goal in goals)
+    if params.get("skip_tests"):
+        command.append("-DskipTests")
+    properties = params.get("properties") or {}
+    for key, value in properties.items():
+        command.append(f"-D{key}={value}")
+    return command
+
+
+def build_shell_command(params: dict[str, Any]) -> list[str] | str:
+    """返回调用方声明的 shell 命令，供 build.shell 等动作复用。"""
+
+    command = params.get("command")
+    if not isinstance(command, (str, list)):
+        raise ValueError("Missing shell command.")
+    return command

simple_ci/actions/deploy.py

@@ -0,0 +1,23 @@
+"""部署相关内置动作的命令构造。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_compose_command(params: dict[str, Any]) -> list[str]:
+    """构造 docker compose up -d 命令，支持 file/project/env_file/services。"""
+
+    command = ["docker", "compose"]
+    compose_file = params.get("file")
+    if compose_file:
+        command.extend(["-f", str(compose_file)])
+    project_name = params.get("project_name")
+    if project_name:
+        command.extend(["--project-name", str(project_name)])
+    env_file = params.get("env_file")
+    if env_file:
+        command.extend(["--env-file", str(env_file)])
+    command.extend(["up", "-d"])
+    command.extend(str(service) for service in params.get("services", []))
+    return command