monkeycode-sdk 1.7.0__py3-none-any.whl

monkeycode/consts.py

@@ -0,0 +1,29 @@
+"""枚举常量。"""
+from enum import Enum
+
+
+class TaskType(str, Enum):
+    """任务类型。"""
+
+    DEVELOP = "develop"
+    DESIGN = "design"
+    REVIEW = "review"
+
+
+class TaskSubType(str, Enum):
+    """任务子类型。"""
+
+    GENERATE_DOCS = "generate_docs"
+    GENERATE_REQUIREMENT = "generate_requirement"
+    GENERATE_DESIGN = "generate_design"
+    GENERATE_TASKLIST = "generate_tasklist"
+    EXECUTE_TASK = "execute_task"
+    PR_REVIEW = "pr_review"
+
+
+class CliName(str, Enum):
+    """CLI 名称。"""
+
+    CODEX = "codex"
+    CLAUDE = "claude"
+    OPENCODE = "opencode"

monkeycode/errors.py

@@ -0,0 +1,30 @@
+"""异常定义。"""
+
+
+class MonkeyCodeError(Exception):
+    """所有 MonkeyCode SDK 异常的基类。"""
+
+
+class APIError(MonkeyCodeError):
+    """接口返回业务错误（HTTP 成功但 code != 0）。"""
+
+    def __init__(self, message: str, code: int | None = None, raw: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.raw = raw or {}
+
+
+class AuthenticationError(APIError):
+    """认证失败（邮箱/密码错误、未登录、会话失效）。"""
+
+
+class CaptchaRequiredError(AuthenticationError):
+    """登录需要验证码（captcha_token 缺失或无效）。"""
+
+
+class RateLimitError(APIError):
+    """触发限流（HTTP 429）。"""
+
+
+class TaskError(MonkeyCodeError):
+    """任务相关错误（创建失败、状态异常、超时）。"""

monkeycode/links.py

@@ -0,0 +1,138 @@
+"""任务预览链接提取与存活检测。
+
+从任务历史轮次（get_task_rounds）中提取 AI 拉起的预览链接，
+过滤出 MonkeyCode 预览域名 / localhost / 8000 端口，并做 HTTP 存活检测。
+"""
+from __future__ import annotations
+
+import base64
+import json
+import re
+from typing import Any
+
+import httpx
+
+_URL_RE = re.compile(r'https?://[^\s"\'<>\)\]\}]+')
+
+# MonkeyCode 预览域名 / 本地回环 / deploy-website 默认预览端口
+_PREVIEW_HOST_RE = re.compile(
+    r"monkeycode-ai\.online|localhost|127\.0\.0\.1|:8000\b"
+)
+
+_MAX_PAGES = 500
+
+
+def _decode_data(data: Any) -> str:
+    """把 chunk.data 解码为可提取 URL 的文本。"""
+    if not isinstance(data, str):
+        return json.dumps(data, ensure_ascii=False)
+    try:
+        decoded = base64.b64decode(data).decode("utf-8", errors="replace")
+        return decoded
+    except Exception:
+        return data
+
+
+def _to_text(decoded: str) -> str:
+    """尝试把解码结果还原为 JSON 文本，否则原样返回。"""
+    try:
+        obj = json.loads(decoded)
+        if isinstance(obj, (dict, list)):
+            return json.dumps(obj, ensure_ascii=False)
+        if isinstance(obj, str):
+            return obj
+    except Exception:
+        pass
+    return decoded
+
+
+def _unescape(text: str) -> str:
+    """还原 markdown/JSON 转义，避免 URL 粘连转义字符。"""
+    text = text.replace("\\r", "")
+    text = text.replace("\\t", " ")
+    text = text.replace("\\n", "\n")
+    text = text.replace('\\"', '"')
+    text = text.replace("\\\\", "\\")
+    return text
+
+
+def _clean_url(url: str) -> str:
+    """清洗单条 URL：按换行截断、去掉尾部标点与反斜杠。"""
+    url = url.split("\n")[0]
+    url = url.rstrip(".,;:!?`)]}>'\"")
+    while url.endswith("\\") or url.endswith("`"):
+        url = url[:-1]
+    return url
+
+
+def _is_junk(url: str) -> bool:
+    """过滤占位符/无意义链接。"""
+    if "..." in url:
+        return True
+    # http://localhost: 但没有端口
+    if re.match(r"^http://localhost:(\D|$)", url):
+        return True
+    # 清洗后只剩 http://localhost（无端口）
+    if re.match(r"^http://localhost$", url):
+        return True
+    if url.endswith(":\\") or url.endswith(":/"):
+        return True
+    return False
+
+
+def extract_urls_from_chunk(chunk: dict[str, Any]) -> list[str]:
+    """从单个轮次 chunk 中提取预览 URL 列表。"""
+    data = chunk.get("data")
+    if data is None:
+        return []
+    text = _to_text(_decode_data(data))
+    text = _unescape(text)
+    urls: list[str] = []
+    for m in _URL_RE.finditer(text):
+        raw_url = m.group(0)
+        if _is_junk(raw_url):
+            continue
+        url = _clean_url(raw_url)
+        if url and not _is_junk(url) and _PREVIEW_HOST_RE.search(url):
+            urls.append(url)
+    return urls
+
+
+def check_url_status(url: str) -> tuple[str, int | None]:
+    """探测链接存活状态，返回 (状态标记, HTTP 状态码)。
+
+    - HTTP < 400  -> ("在线", code)
+    - HTTP >= 400 -> ("异常", code)
+    - 连接失败     -> ("已关闭", None)
+    """
+    try:
+        resp = httpx.get(url, timeout=8, follow_redirects=True)
+        code = resp.status_code
+        if code < 400:
+            return ("在线", code)
+        return ("异常", code)
+    except Exception:
+        return ("已关闭", None)
+
+
+def collect_preview_links(
+    get_rounds, task_id: str, max_pages: int = _MAX_PAGES
+) -> dict[str, int]:
+    """分页拉取任务轮次，收集预览链接及出现次数。
+
+    get_rounds: 可调用对象，签名 (task_id, cursor, limit) -> dict
+    """
+    counts: dict[str, int] = {}
+    cursor: str | None = None
+    for _ in range(max_pages):
+        data = get_rounds(task_id, cursor=cursor, limit=10)
+        if not isinstance(data, dict):
+            break
+        for chunk in data.get("chunks") or []:
+            for url in extract_urls_from_chunk(chunk):
+                counts[url] = counts.get(url, 0) + 1
+        if data.get("has_more") and data.get("next_cursor"):
+            cursor = data["next_cursor"]
+        else:
+            break
+    return counts

monkeycode/models.py

@@ -0,0 +1,227 @@
+"""数据模型（轻量 dataclass，不引入 pydantic 依赖）。"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RepoReq:
+    """任务仓库信息。"""
+
+    repo_url: str
+    branch: str = "main"
+    repo_filename: str = ""
+    zip_url: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "repo_url": self.repo_url,
+            "branch": self.branch,
+            "repo_filename": self.repo_filename,
+            "zip_url": self.zip_url,
+        }
+
+
+@dataclass
+class VMResource:
+    """云端虚拟机资源。
+
+    默认值为 MonkeyCode 桌面端建任务的默认档位：
+    2 核 / 8GB 内存 / 3 小时。
+    """
+
+    core: int = 2
+    memory: int = 8 << 30  # 8GB（与桌面端常量一致，字节为单位）
+    life: int = 3 * 60 * 60  # 3 小时（秒）
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "core": self.core,
+            "memory": self.memory,
+            "life": self.life,
+        }
+
+
+@dataclass
+class TaskExtraConfig:
+    """任务扩展配置（对应 domain.TaskExtraConfig）。"""
+
+    skill_ids: list[str] | None = None
+    plugin_ids: list[str] | None = None
+    project_id: str | None = None
+    issue_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        if self.skill_ids:
+            out["skill_ids"] = self.skill_ids
+        if self.plugin_ids:
+            out["plugin_ids"] = self.plugin_ids
+        if self.project_id:
+            out["project_id"] = self.project_id
+        if self.issue_id:
+            out["issue_id"] = self.issue_id
+        return out
+
+
+@dataclass
+class Task:
+    """任务对象（响应的精简视图）。"""
+
+    id: str
+    status: str
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def title(self) -> str:
+        return str(self.raw.get("title") or "")
+
+    @property
+    def summary(self) -> str:
+        return str(self.raw.get("summary") or "")
+
+    @property
+    def content(self) -> str:
+        return str(self.raw.get("content") or "")
+
+    @property
+    def branch(self) -> str:
+        return str(self.raw.get("branch") or "")
+
+    @property
+    def repo_url(self) -> str:
+        return str(self.raw.get("repo_url") or "")
+
+    @property
+    def pr_url(self) -> str | None:
+        return (self.raw.get("pr_url") or self.raw.get("pull_request_url")) or None
+
+    @property
+    def model(self) -> dict[str, Any] | None:
+        return self.raw.get("model") or None
+
+    @property
+    def image(self) -> dict[str, Any] | None:
+        return self.raw.get("image") or None
+
+    @property
+    def extra(self) -> TaskExtraConfig | None:
+        extra = self.raw.get("extra")
+        if isinstance(extra, dict):
+            return TaskExtraConfig(
+                skill_ids=extra.get("skill_ids"),
+                plugin_ids=extra.get("plugin_ids"),
+                project_id=extra.get("project_id"),
+                issue_id=extra.get("issue_id"),
+            )
+        return None
+
+    @property
+    def created_at(self) -> int | None:
+        v = self.raw.get("created_at")
+        return int(v) if v is not None else None
+
+    @property
+    def completed_at(self) -> int | None:
+        v = self.raw.get("completed_at")
+        return int(v) if v is not None else None
+
+    @property
+    def result(self) -> Any:
+        return self.raw.get("result")
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Task":
+        return cls(
+            id=str(data.get("id") or data.get("task_id") or ""),
+            status=str(data.get("status") or ""),
+            raw=data,
+        )
+
+
+@dataclass
+class TaskRound:
+    """任务历史轮次（domain.TaskRound 精简视图）。"""
+
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def seq(self) -> int | None:
+        v = self.raw.get("seq")
+        return int(v) if v is not None else None
+
+    @property
+    def role(self) -> str:
+        return str(self.raw.get("role") or "")
+
+    @property
+    def content(self) -> str:
+        return str(self.raw.get("content") or "")
+
+
+@dataclass
+class CaptchaChallenge:
+    """验证码质询。"""
+
+    token: str
+    expires: int
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TaskStreamChunk:
+    """任务 WebSocket 流式事件。"""
+
+    type: str
+    data: Any = None
+    timestamp: int = 0
+    turn_seq: int = 0
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UserInputPayload:
+    """上行用户输入（user-input 内层数据）。"""
+
+    content: str
+    attachments: list[dict] = field(default_factory=list)
+
+    def encode(self) -> str:
+        """按协议编码为内层 JSON 字符串（content 为 base64）。"""
+        import base64
+
+        inner = {
+            "content": base64.b64encode(self.content.encode("utf-8")).decode("ascii"),
+            "attachments": self.attachments,
+        }
+        return json.dumps(inner, ensure_ascii=False)
+
+
+@dataclass
+class CaptchaVerification:
+    """验证码兑换结果。"""
+
+    success: bool
+    token: str = ""
+    message: str = ""
+    expires: int = 0
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class APIKeyInfo:
+    """OhMyAgent API Key（仅创建响应返回明文，需立即保存）。"""
+
+    api_key: str
+    key_id: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "APIKeyInfo":
+        return cls(
+            api_key=str(data.get("api_key") or data.get("apiKey") or ""),
+            key_id=str(data.get("key_id") or data.get("id") or ""),
+            raw=data,
+        )

monkeycode/pow.py

@@ -0,0 +1,65 @@
+"""MonkeyCode PoW 验证码求解器。
+
+协议：SHA-256 前缀碰撞（工作量证明），无需识别图片。
+流程：
+  1. POST /api/v1/public/captcha/challenge 获取 {challenge: {c,s,d}, token}
+  2. 对每个 i(1..c)：用确定性 PRNG 生成 salt 和 target，
+     爆破 nonce 使 sha256(salt + nonce) 以 target 开头
+  3. POST /api/v1/public/captcha/redeem 提交 solutions，得到 captcha_token
+
+参考实现：chaitin/MonkeyCode desktop/src/baizhi/pow.rs
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def fnv1a32(s: str) -> int:
+    """FNV-1a 32 位哈希，用于播种 PRNG。"""
+    h = 0x811C9DC5
+    for byte in s.encode("utf-8"):
+        h ^= byte
+        h = (h * 0x01000193) & 0xFFFFFFFF
+    return h
+
+
+def prng(seed: str, length: int) -> str:
+    """xorshift32 确定性 PRNG，生成指定长度的十六进制串。"""
+    state = fnv1a32(seed)
+    result: list[str] = []
+    total = 0
+    while total < length:
+        state ^= (state << 13) & 0xFFFFFFFF
+        state ^= state >> 17
+        state ^= (state << 5) & 0xFFFFFFFF
+        state &= 0xFFFFFFFF
+        result.append(f"{state:08x}")
+        total += 8
+    return "".join(result)[:length]
+
+
+def solve(
+    token: str,
+    c: int,
+    s: int,
+    d: int,
+    max_nonce: int = 5_000_000,
+) -> list[int]:
+    """求解 PoW 验证码，返回 solutions（每个子质询的 nonce）。"""
+    solutions: list[int] = []
+    for i in range(1, c + 1):
+        base = f"{token}{i}"
+        salt = prng(base, s)
+        target = prng(f"{base}d", d)
+        nonce = 0
+        while True:
+            digest = hashlib.sha256(f"{salt}{nonce}".encode("utf-8")).hexdigest()
+            if digest.startswith(target):
+                solutions.append(nonce)
+                break
+            nonce += 1
+            if nonce > max_nonce:
+                raise TimeoutError(
+                    f"子质询 {i} 超过最大尝试次数 {max_nonce}（salt={salt}, target={target}）"
+                )
+    return solutions

monkeycode/session.py

@@ -0,0 +1,140 @@
+"""任务高层会话封装（轻量自动重连 + 事件缓冲）。
+
+AgentSession 在 TaskStream 之上提供：
+- 断线自动重连（可配置次数与间隔）
+- 后台事件拉取与 asyncio.Queue 缓冲
+- 发送消息前确保连接可用
+
+注意：不做消息乱序去重。服务端事件通常按顺序到达，
+turn_seq 仅作标识；如需严格有序，调用方可自行按 turn_seq 排序。
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncIterator
+
+import websockets
+
+from monkeycode.models import TaskStreamChunk
+from monkeycode.stream import TaskStream
+
+_TERMINAL_TYPES = {"task-ended", "task-error"}
+
+
+class AgentSession:
+    """任务高层会话。
+
+    用法：
+        session = AgentSession(client, task_id, mode="new")
+        await session.start()
+        await session.send_user_input("继续")
+        async for chunk in session.events():
+            print(chunk.type, chunk.data)
+            if chunk.type == "task-ended":
+                break
+        await session.close()
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        task_id: str,
+        mode: str = "new",
+        max_reconnects: int = 3,
+        reconnect_delay: float = 1.0,
+    ) -> None:
+        self.client = client
+        self.task_id = task_id
+        self.mode = mode
+        self.max_reconnects = max_reconnects
+        self.reconnect_delay = reconnect_delay
+        self._stream = TaskStream(client, task_id, mode=mode)
+        self._queue: asyncio.Queue[TaskStreamChunk] = asyncio.Queue()
+        self._pump_task: asyncio.Task[None] | None = None
+        self._running = False
+
+    async def start(self) -> None:
+        """建立连接并启动后台事件拉取循环。"""
+        await self._ensure_connected()
+        if self._running:
+            return
+        self._running = True
+        self._pump_task = asyncio.create_task(self._pump())
+
+    async def _ensure_connected(self) -> None:
+        """确保 WebSocket 已连接；断线时自动重连。"""
+        if self._stream._ws is not None:
+            return
+        attempts = 0
+        while True:
+            try:
+                await self._stream.connect()
+                return
+            except Exception:
+                attempts += 1
+                if attempts > self.max_reconnects:
+                    raise
+                await asyncio.sleep(self.reconnect_delay)
+
+    async def _pump(self) -> None:
+        """后台拉取事件放入队列；断线时自动重连。"""
+        while self._running:
+            try:
+                chunk = await self._stream.recv()
+                await self._queue.put(chunk)
+                if chunk.type in _TERMINAL_TYPES:
+                    break
+            except (websockets.ConnectionClosed, asyncio.TimeoutError, OSError):
+                if not self._running:
+                    break
+                try:
+                    await self._ensure_connected()
+                except Exception:
+                    # 重连失败：结束事件循环，由调用方决定后续
+                    break
+
+    async def send_user_input(
+        self, content: str, attachments: list[dict] | None = None
+    ) -> None:
+        """发送用户消息；断线时自动重连后重发。"""
+        await self._ensure_connected()
+        await self._stream.send_user_input(content, attachments)
+
+    async def send_reply_question(
+        self, request_id: str, answers: list[str]
+    ) -> None:
+        """回复 AI 提问（自动确保连接可用）。"""
+        await self._ensure_connected()
+        await self._stream.send_reply_question(request_id, answers)
+
+    async def send_auto_approve(self, enable: bool = True) -> None:
+        """开启/关闭自动批准（自动确保连接可用）。"""
+        await self._ensure_connected()
+        await self._stream.send_auto_approve(enable)
+
+    async def events(self) -> AsyncIterator[TaskStreamChunk]:
+        """异步迭代事件队列，直到任务结束或出错。"""
+        while True:
+            chunk = await self._queue.get()
+            yield chunk
+            if chunk.type in _TERMINAL_TYPES:
+                break
+
+    async def close(self) -> None:
+        """停止后台拉取并关闭连接。"""
+        self._running = False
+        if self._pump_task is not None:
+            self._pump_task.cancel()
+            try:
+                await self._pump_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._pump_task = None
+        await self._stream.close()
+
+    async def __aenter__(self) -> "AgentSession":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()