zero-agent-core 0.2.0__py3-none-any.whl

agent_core/acp/README.md

@@ -0,0 +1,236 @@
+# ACP 模块说明
+
+本目录实现 Agent Client Protocol（ACP）的通用适配层。它不负责模型推理、Agent Loop、业务工具或
+持久化，而是负责把一个已经存在的 Agent Runtime 暴露给编辑器、CLI 或其他 ACP Client。
+
+## 1. ACP、MCP 和 Agent Runtime 的关系
+
+```text
+ACP Client（编辑器 / CLI）
+        │
+        │ ACP：客户端调用 Agent
+        ▼
+AcpStdioServer
+        │
+        │ AcpBackend：协议对象转换为应用调用
+        ▼
+应用 Agent Runtime（ReAct / LangGraph / 其他实现）
+        │
+        │ MCP：Agent 调用外部工具和资源
+        ▼
+MCP Server
+```
+
+- ACP 解决“外部客户端如何创建会话、发送提示、接收更新、审批和取消 Agent”。
+- MCP 解决“Agent 如何发现并调用外部工具、资源和提示词”。
+- `AcpBackend` 是两者之间的应用适配边界，不能把 ACP Client 提供的配置直接视为可信配置。
+
+## 2. 文件职责
+
+| 文件 | 职责 |
+| --- | --- |
+| `types.py` | 定义 `AcpSession`、`AcpUpdate`、回调类型和应用必须实现的 `AcpBackend` 协议 |
+| `server.py` | 实现基于 stdin/stdout 的双向 JSON-RPC 服务端、方法分发、更新通知、审批和取消 |
+| `__init__.py` | 统一导出公共 API |
+
+Core 只负责协议和传输。会话存储、模型调用、工具执行、访问控制和业务审批都由应用 Backend 负责。
+
+## 3. `types.py` 中的数据结构
+
+### `JsonObject`
+
+`dict[str, Any]` 的可读别名，用于描述 JSON 对象。它不负责运行时校验；服务端会在协议入口校验
+关键字段，应用 Backend 仍需校验业务字段。
+
+### `AcpSession`
+
+ACP 会话与应用会话的映射：
+
+```python
+AcpSession(
+    session_id="acp-session-id",
+    cwd="E:/workspace",
+    metadata={"thread_id": "application-thread-id"},
+)
+```
+
+- `session_id` 是 ACP Client 后续请求使用的会话标识。
+- `cwd` 是客户端声明的工作目录，仅是上下文输入，不能天然视为已授权目录。
+- `metadata` 保存应用自己的 thread、用户、租户或运行参数映射。
+
+`AcpSession` 本身不保存消息历史。历史是否持久化取决于具体 Backend。
+
+### `AcpUpdate`
+
+应用 Runtime 向协议层发送的标准化更新。Core 当前转换以下 `kind`：
+
+| `kind` | ACP 更新 | 用途 |
+| --- | --- | --- |
+| `text` | `agent_message_chunk` | 可展示给用户的文本片段 |
+| `thought` | `agent_thought_chunk` | 可选展示的运行过程说明 |
+| `tool_started` | `tool_call` | 工具开始及输入 |
+| `tool_finished` | `tool_call_update` | 工具结果和成功状态 |
+
+`AcpUpdate.text()` 和 `AcpUpdate.thought()` 是常用构造方法。工具事件使用
+`AcpUpdate(kind, payload)`，并应提供稳定的 `toolCallId`，使开始和结束事件能够对应。
+
+### `AcpEmitter` 与 `AcpPermissionRequester`
+
+它们是回调类型，不是未实现的函数：
+
+- `AcpEmitter`：Backend 调用它，把增量更新交给协议服务端。
+- `AcpPermissionRequester`：Backend 调用它，请 ACP Client 选择批准或拒绝。
+
+### `AcpBackend`
+
+`AcpBackend` 是 Python `Protocol`，采用结构化类型检查。实现类不必继承它，只要提供相同字段和
+方法即可。
+
+| 成员 | 责任 |
+| --- | --- |
+| `agent_name` / `agent_version` | 返回给 ACP Client 的 Agent 信息 |
+| `supports_load_session` | 声明是否支持恢复会话 |
+| `create_session()` | 创建应用会话，并返回 ACP 与应用会话的映射 |
+| `load_session()` | 从持久化状态恢复会话 |
+| `prompt()` | 调用真实 Agent，通过回调发送更新和请求审批 |
+| `cancel()` | 取消该会话当前正在执行的任务或 Run |
+
+`Protocol` 方法体中的 `...` 只是类型声明，运行时不会创建或调用 `AcpBackend` 实例。真正代码位于
+各应用的 Backend 实现中。
+
+## 4. `server.py` 的处理流程
+
+### 读取和并发
+
+`AcpStdioServer.run()` 从 stdin 逐行读取 JSON。每行必须是一个完整 JSON-RPC 对象。请求会创建独立
+异步任务，因此不同会话可以并发；`_write_lock` 保证响应写入 stdout 时不会互相穿插。
+
+同一个会话同时只能执行一个 `session/prompt`。服务结束或 stdin 关闭时，未完成任务会被取消并等待
+收尾。
+
+### 客户端调用 Agent 的方法
+
+| 方法 | 行为 |
+| --- | --- |
+| `initialize` | 校验协议版本，返回 Agent 信息与能力声明 |
+| `session/new` | 生成 session ID，调用 `backend.create_session()` |
+| `session/load` | 在 Backend 声明支持时调用 `backend.load_session()` |
+| `session/prompt` | 提取文本内容并调用 `backend.prompt()` |
+| `session/cancel` | 调用 `backend.cancel()`，同时取消服务端 prompt 任务 |
+
+### Agent 主动调用客户端
+
+`session/update` 是不需要响应的 JSON-RPC notification。它用于发送文本、思考过程和工具状态。
+
+`session/request_permission` 是反向 JSON-RPC request。服务端生成请求 ID，把等待结果的 Future 保存到
+`_pending_client_requests`，然后等待客户端响应。默认等待 300 秒，超时按 `reject_once` 处理。
+
+### 一次提示的完整时序
+
+```text
+Client -> initialize
+Client -> session/new
+Server -> Backend.create_session()
+
+Client -> session/prompt
+Server -> Backend.prompt()
+Backend -> emit(AcpUpdate)
+Server -> session/update -> Client
+
+Backend -> request_permission()             # 可选
+Server -> session/request_permission -> Client
+Client -> 批准或拒绝结果 -> Server
+Server -> 审批结果 -> Backend
+
+Backend -> {"stopReason": "end_turn"}
+Server -> session/prompt 最终响应 -> Client
+```
+
+### 错误映射
+
+| 场景 | JSON-RPC code |
+| --- | ---: |
+| JSON 解析失败 | `-32700` |
+| 请求对象或 method 无效 | `-32600` |
+| 参数或协议内容无效 | `-32602` |
+| 方法或能力未实现 | `-32601` |
+| 会话不存在 | `-32004` |
+| Agent 执行异常 | `-32603` |
+
+## 5. 新 Agent 如何接入
+
+应用创建一个实现 `AcpBackend` 形状的类，在 `prompt()` 中调用自己的 Runtime：
+
+```python
+class MyAcpBackend:
+    agent_name = "my-agent"
+    agent_version = "0.1.0"
+    supports_load_session = True
+
+    async def create_session(self, session_id, cwd, mcp_servers):
+        thread_id = await self.runtime.create_thread(session_id)
+        return AcpSession(session_id, cwd, {"thread_id": thread_id})
+
+    async def load_session(self, session_id, cwd, mcp_servers):
+        await self.runtime.load_thread(session_id)
+        return AcpSession(session_id, cwd, {"thread_id": session_id})
+
+    async def prompt(self, session, text, emit, request_permission):
+        async for chunk in self.runtime.stream(session.metadata["thread_id"], text):
+            await emit(AcpUpdate.text(chunk))
+        return {"stopReason": "end_turn"}
+
+    async def cancel(self, session):
+        await self.runtime.cancel(session.metadata["thread_id"])
+```
+
+然后使用：
+
+```python
+await run_acp_stdio(MyAcpBackend(runtime))
+```
+
+这是示意代码。生产实现还需要接入访问身份、租户、持久化、审批、幂等和安全的 MCP 配置白名单。
+
+## 6. 两个低空 Agent 的当前接入情况
+
+### Vanilla Agent
+
+`VanillaAcpBackend` 把 ACP `session_id` 直接映射为 `RuntimeCompat` 的 `thread_id`，创建真实 Run，
+轮询并转发模型、工具和审批事件。它支持持久化会话恢复；用户作出 ACP 审批决定后，通过恢复命令
+创建后续 Run。取消操作会调用 Runtime 的 `cancel_run()`。
+
+ACP Client 传入的 MCP 配置不会覆盖系统配置的 Gateway。
+
+### LangGraph Agent
+
+`LangGraphAcpBackend` 当前把历史保存在 ACP 进程内，调用现有图的 `ainvoke()`，发送一条过程说明和
+最终回答。它声明 `supports_load_session=False`，因此不承诺进程重启后的 ACP 会话恢复；取消操作通过
+取消当前图任务完成。
+
+当前 LangGraph Backend 尚未完整转发图内部的工具事件和人工审批事件，能力范围低于 Vanilla Backend。
+
+## 7. 空方法和占位实现审计
+
+截至 2026-09-28，ACP 相关代码没有漏写的具体方法：
+
+| 位置 | 表现 | 结论 |
+| --- | --- | --- |
+| `types.py` 的 `AcpBackend` | 4 个方法体使用 `...` | `Protocol` 接口声明，属于正确写法 |
+| `server.py` 的未知方法分支 | 抛出 `NotImplementedError` | 映射为 JSON-RPC `-32601`，不是空实现 |
+| `server.py` 的 `session/load` 检查 | Backend 不支持时抛出 `NotImplementedError` | 按能力声明拒绝请求 |
+| `VanillaAcpBackend` | 没有 `pass`、`...` 或占位方法 | 已实现全部 Backend 方法 |
+| `LangGraphAcpBackend.load_session()` | 明确抛出 `NotImplementedError` | 与 `supports_load_session=False` 一致，属于关闭的可选能力 |
+
+因此不应把 `AcpBackend` 中的 `...` 改成业务实现。Core 只定义端口，具体实现必须继续留在应用 Agent。
+
+## 8. 当前边界
+
+- 仅提供 stdio 传输，没有内置 HTTP 或 WebSocket ACP 服务。
+- 当前只接受文本 prompt；初始化能力中图片、音频和嵌入上下文均为 `False`。
+- `mcpServers` 会传给 Backend，但 Core 不负责启动、认证或信任客户端声明的 MCP Server。
+- Core 不负责用户认证、租户授权或工作目录授权，Backend 必须建立可信访问上下文。
+- 服务端 `_sessions` 是当前 ACP 进程的索引；跨进程恢复取决于 Backend 和持久化 Runtime。
+- 未识别的 `AcpUpdate.kind` 会被忽略。
+- Core 支持增量更新，但是否真正逐块输出取决于 Backend 是否持续调用 `emit()`。
+- 工具开始和结束事件必须使用同一个 `toolCallId`，否则客户端无法可靠关联。

agent_core/acp/__init__.py

@@ -0,0 +1,20 @@
+"""Agent Client Protocol（ACP）stdio 适配能力。"""
+
+from agent_core.acp.server import (
+    AcpProtocolError,
+    AcpSessionNotFoundError,
+    AcpStdioServer,
+    run_acp_stdio,
+)
+from agent_core.acp.types import AcpBackend, AcpSession, AcpUpdate, JsonObject
+
+__all__ = [
+    "AcpBackend",
+    "AcpProtocolError",
+    "AcpSession",
+    "AcpSessionNotFoundError",
+    "AcpStdioServer",
+    "AcpUpdate",
+    "JsonObject",
+    "run_acp_stdio",
+]

agent_core/acp/server.py

@@ -0,0 +1,351 @@
+"""ACP JSON-RPC stdio 服务端。
+
+该实现覆盖通用 Agent Client Protocol 会话流程：初始化、创建/恢复会话、发送提示、
+流式更新、取消和人工审批。传输层只处理 JSON-RPC，实际执行由 ``AcpBackend`` 注入。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import uuid
+from typing import TextIO
+
+from agent_core.acp.types import AcpBackend, AcpSession, AcpUpdate, JsonObject
+
+
+class AcpProtocolError(ValueError):
+    """客户端发送了不符合 ACP/JSON-RPC 要求的请求。"""
+
+
+class AcpSessionNotFoundError(LookupError):
+    """请求引用了当前 ACP 服务端不存在的会话。"""
+
+    def __init__(self, session_id: str) -> None:
+        super().__init__(session_id)
+        self.session_id = session_id
+
+
+class AcpStdioServer:
+    """基于标准输入输出运行的 ACP 双向 JSON-RPC 服务端。"""
+
+    protocol_version = 1
+
+    def __init__(
+        self,
+        backend: AcpBackend,
+        *,
+        stdin: TextIO | None = None,
+        stdout: TextIO | None = None,
+        approval_timeout_seconds: float = 300.0,
+    ) -> None:
+        if approval_timeout_seconds <= 0:
+            raise ValueError("approval_timeout_seconds 必须大于 0")
+        self._backend = backend
+        self._stdin = stdin or sys.stdin
+        self._stdout = stdout or sys.stdout
+        self._approval_timeout_seconds = approval_timeout_seconds
+        self._sessions: dict[str, AcpSession] = {}
+        self._pending_client_requests: dict[str, asyncio.Future[JsonObject]] = {}
+        self._prompt_tasks: dict[str, asyncio.Task[None]] = {}
+        self._tasks: set[asyncio.Task[None]] = set()
+        self._write_lock = asyncio.Lock()
+
+    async def run(self) -> None:
+        """持续处理 ACP Client 写入的 JSON-RPC 行，直到 stdin 关闭。"""
+        try:
+            while line := await asyncio.to_thread(self._stdin.readline):
+                await self._handle_line(line)
+        finally:
+            # 任务完成回调会从集合移除自身，先创建快照避免遍历期间修改集合。
+            for task in tuple(self._tasks):
+                task.cancel()
+            if self._tasks:
+                await asyncio.gather(*tuple(self._tasks), return_exceptions=True)
+
+    async def _handle_line(self, line: str) -> None:
+        try:
+            value = json.loads(line)
+        except json.JSONDecodeError:
+            await self._send_error(None, -32700, "JSON-RPC 解析失败")
+            return
+        if not isinstance(value, dict):
+            await self._send_error(None, -32600, "JSON-RPC 请求必须是对象")
+            return
+        if "method" not in value:
+            self._resolve_client_response(value)
+            return
+        method = value.get("method")
+        if not isinstance(method, str):
+            await self._send_error(value.get("id"), -32600, "method 必须是字符串")
+            return
+        params = value.get("params", {})
+        if not isinstance(params, dict):
+            await self._send_error(value.get("id"), -32602, "params 必须是对象")
+            return
+        task = asyncio.create_task(self._handle_request(value.get("id"), method, params))
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    def _resolve_client_response(self, value: JsonObject) -> None:
+        request_id = value.get("id")
+        if not isinstance(request_id, str):
+            return
+        future = self._pending_client_requests.pop(request_id, None)
+        if future is None or future.done():
+            return
+        error = value.get("error")
+        if isinstance(error, dict):
+            future.set_exception(AcpProtocolError(str(error.get("message") or "ACP Client 拒绝请求")))
+            return
+        result = value.get("result", {})
+        future.set_result(result if isinstance(result, dict) else {"value": result})
+
+    async def _handle_request(self, request_id: object, method: str, params: JsonObject) -> None:
+        is_request = request_id is not None
+        try:
+            result = await self._dispatch(method, params)
+        except asyncio.CancelledError:
+            if is_request:
+                await self._send_result(request_id, {"stopReason": "cancelled"})
+        except AcpProtocolError as exc:
+            if is_request:
+                await self._send_error(request_id, -32602, str(exc))
+        except AcpSessionNotFoundError as exc:
+            if is_request:
+                await self._send_error(request_id, -32004, f"会话不存在：{exc.session_id}")
+        except NotImplementedError as exc:
+            if is_request:
+                await self._send_error(request_id, -32601, str(exc))
+        except Exception as exc:
+            if is_request:
+                await self._send_error(request_id, -32603, f"ACP Agent 执行失败：{exc}")
+        else:
+            if is_request:
+                await self._send_result(request_id, result)
+
+    async def _dispatch(self, method: str, params: JsonObject) -> JsonObject:
+        if method == "initialize":
+            return self._initialize(params)
+        if method == "session/new":
+            return await self._new_session(params)
+        if method == "session/load":
+            if not getattr(self._backend, "supports_load_session", False):
+                raise NotImplementedError("当前 Agent 不支持 ACP 会话恢复")
+            return await self._load_session(params)
+        if method == "session/prompt":
+            return await self._prompt(params)
+        if method == "session/cancel":
+            return await self._cancel(params)
+        raise NotImplementedError(f"不支持的 ACP 方法：{method}")
+
+    def _initialize(self, params: JsonObject) -> JsonObject:
+        client_version = params.get("protocolVersion", self.protocol_version)
+        if not isinstance(client_version, int):
+            raise AcpProtocolError("protocolVersion 必须是整数")
+        if client_version != self.protocol_version:
+            raise AcpProtocolError(f"不支持的 ACP 版本：{client_version}，当前仅支持 {self.protocol_version}")
+        return {
+            "protocolVersion": self.protocol_version,
+            "agentCapabilities": {
+                "loadSession": bool(getattr(self._backend, "supports_load_session", False)),
+                "promptCapabilities": {
+                    "image": False,
+                    "audio": False,
+                    "embeddedContext": False,
+                },
+                "mcpCapabilities": {"http": False, "sse": False},
+            },
+            "agentInfo": {
+                "name": self._backend.agent_name,
+                "title": self._backend.agent_name,
+                "version": self._backend.agent_version,
+            },
+        }
+
+    async def _new_session(self, params: JsonObject) -> JsonObject:
+        cwd = self._require_string(params, "cwd")
+        session_id = str(uuid.uuid4())
+        session = await self._backend.create_session(session_id, cwd, self._mcp_servers(params))
+        self._sessions[session.session_id] = session
+        return {"sessionId": session.session_id, "modes": [], "configOptions": []}
+
+    async def _load_session(self, params: JsonObject) -> JsonObject:
+        session_id = self._require_string(params, "sessionId")
+        cwd = self._require_string(params, "cwd")
+        session = await self._backend.load_session(session_id, cwd, self._mcp_servers(params))
+        self._sessions[session.session_id] = session
+        return {"sessionId": session.session_id, "modes": [], "configOptions": []}
+
+    async def _prompt(self, params: JsonObject) -> JsonObject:
+        session_id = self._require_string(params, "sessionId")
+        session = self._session(session_id)
+        if session_id in self._prompt_tasks:
+            raise AcpProtocolError("该 ACP 会话已有正在执行的提示")
+        text = self._prompt_text(params.get("prompt"))
+        task = asyncio.current_task()
+        if task is None:
+            raise RuntimeError("无法获取 ACP 提示任务")
+        self._prompt_tasks[session_id] = task
+        try:
+            return await self._backend.prompt(
+                session,
+                text,
+                lambda update: self._emit_update(session_id, update),
+                lambda request: self._request_permission(session_id, request),
+            )
+        finally:
+            self._prompt_tasks.pop(session_id, None)
+
+    async def _cancel(self, params: JsonObject) -> JsonObject:
+        session_id = self._require_string(params, "sessionId")
+        session = self._session(session_id)
+        await self._backend.cancel(session)
+        task = self._prompt_tasks.get(session_id)
+        if task is not None and not task.done():
+            task.cancel()
+        return {}
+
+    async def _emit_update(self, session_id: str, update: AcpUpdate) -> None:
+        payload = self._update_payload(update)
+        if payload is None:
+            return
+        await self._send_notification("session/update", {"sessionId": session_id, "update": payload})
+
+    async def _request_permission(self, session_id: str, request: JsonObject) -> str:
+        options = request.get("options")
+        if not isinstance(options, list) or not options:
+            options = [
+                {"optionId": "approve_once", "name": "批准", "kind": "allow_once"},
+                {"optionId": "reject_once", "name": "拒绝", "kind": "reject_once"},
+            ]
+        allowed_option_ids = {
+            option["optionId"]
+            for option in options
+            if isinstance(option, dict) and isinstance(option.get("optionId"), str) and option["optionId"]
+        }
+        if not allowed_option_ids:
+            raise AcpProtocolError("审批选项必须包含非空 optionId")
+        result = await self._request_client(
+            "session/request_permission",
+            {
+                "sessionId": session_id,
+                "toolCall": request.get("toolCall", {}),
+                "options": options,
+            },
+        )
+        for key in ("selectedOptionId", "optionId", "outcome"):
+            value = result.get(key)
+            if isinstance(value, str) and value:
+                return value if value in allowed_option_ids else "reject_once"
+        return "reject_once"
+
+    async def _request_client(self, method: str, params: JsonObject) -> JsonObject:
+        request_id = f"agent-{uuid.uuid4()}"
+        future: asyncio.Future[JsonObject] = asyncio.get_running_loop().create_future()
+        self._pending_client_requests[request_id] = future
+        await self._write({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params})
+        try:
+            return await asyncio.wait_for(future, timeout=self._approval_timeout_seconds)
+        except TimeoutError:
+            return {"selectedOptionId": "reject_once"}
+        finally:
+            self._pending_client_requests.pop(request_id, None)
+
+    @staticmethod
+    def _update_payload(update: AcpUpdate) -> JsonObject | None:
+        text = update.payload.get("text")
+        if update.kind == "text" and isinstance(text, str):
+            return {
+                "sessionUpdate": "agent_message_chunk",
+                "content": {"type": "text", "text": text},
+            }
+        if update.kind == "thought" and isinstance(text, str):
+            return {
+                "sessionUpdate": "agent_thought_chunk",
+                "content": {"type": "text", "text": text},
+            }
+        if update.kind == "tool_started":
+            return {
+                "sessionUpdate": "tool_call",
+                "toolCallId": str(update.payload.get("toolCallId") or uuid.uuid4()),
+                "title": str(update.payload.get("title") or "调用工具"),
+                "kind": "other",
+                "status": "in_progress",
+                "rawInput": update.payload.get("input", {}),
+            }
+        if update.kind == "tool_finished":
+            return {
+                "sessionUpdate": "tool_call_update",
+                "toolCallId": str(update.payload.get("toolCallId") or "tool"),
+                "status": "completed" if update.payload.get("success", True) else "failed",
+                "content": update.payload.get("content", []),
+            }
+        return None
+
+    @staticmethod
+    def _prompt_text(prompt: object) -> str:
+        if not isinstance(prompt, list):
+            raise AcpProtocolError("prompt 必须是内容块数组")
+        texts: list[str] = []
+        for block in prompt:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") != "text":
+                continue
+            text = block.get("text")
+            if isinstance(text, str) and text.strip():
+                texts.append(text.strip())
+        value = "\n".join(texts).strip()
+        if not value:
+            raise AcpProtocolError("prompt 中缺少文本内容")
+        return value
+
+    @staticmethod
+    def _mcp_servers(params: JsonObject) -> list[JsonObject]:
+        value = params.get("mcpServers", [])
+        if not isinstance(value, list):
+            raise AcpProtocolError("mcpServers 必须是数组")
+        return [item for item in value if isinstance(item, dict)]
+
+    @staticmethod
+    def _require_string(params: JsonObject, key: str) -> str:
+        value = params.get(key)
+        if not isinstance(value, str) or not value.strip():
+            raise AcpProtocolError(f"{key} 必须是非空字符串")
+        return value.strip()
+
+    def _session(self, session_id: str) -> AcpSession:
+        session = self._sessions.get(session_id)
+        if session is None:
+            raise AcpSessionNotFoundError(session_id)
+        return session
+
+    async def _send_result(self, request_id: object, result: JsonObject) -> None:
+        await self._write({"jsonrpc": "2.0", "id": request_id, "result": result})
+
+    async def _send_error(self, request_id: object, code: int, message: str) -> None:
+        await self._write({"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}})
+
+    async def _send_notification(self, method: str, params: JsonObject) -> None:
+        await self._write({"jsonrpc": "2.0", "method": method, "params": params})
+
+    async def _write(self, payload: JsonObject) -> None:
+        line = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
+        async with self._write_lock:
+            await asyncio.to_thread(self._stdout.write, line)
+            await asyncio.to_thread(self._stdout.flush)
+
+
+async def run_acp_stdio(backend: AcpBackend) -> None:
+    """使用默认标准输入输出启动 ACP 服务。"""
+    await AcpStdioServer(backend).run()
+
+
+__all__ = [
+    "AcpProtocolError",
+    "AcpSessionNotFoundError",
+    "AcpStdioServer",
+    "run_acp_stdio",
+]

agent_core/acp/types.py

@@ -0,0 +1,86 @@
+"""ACP 适配器的公共协议。
+
+ACP（Agent Client Protocol）使用 JSON-RPC 双向通信。这里定义的接口不依赖
+某个 Agent 框架，业务项目只需把自己的会话和运行时接到 ``AcpBackend``。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+JsonObject = dict[str, Any]
+
+
+@dataclass
+class AcpSession:
+    """ACP 会话与业务运行时会话之间的映射。"""
+
+    session_id: str
+    cwd: str
+    metadata: JsonObject = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AcpUpdate:
+    """业务运行时向 ACP Client 推送的一条标准化更新。"""
+
+    kind: str
+    payload: JsonObject = field(default_factory=dict)
+
+    @classmethod
+    def text(cls, text: str) -> AcpUpdate:
+        """构造可显示给用户的 Agent 文本片段。"""
+        return cls("text", {"text": text})
+
+    @classmethod
+    def thought(cls, text: str) -> AcpUpdate:
+        """构造可选展示的运行过程说明。"""
+        return cls("thought", {"text": text})
+
+
+AcpEmitter = Callable[[AcpUpdate], Awaitable[None]]
+AcpPermissionRequester = Callable[[JsonObject], Awaitable[str]]
+
+
+class AcpBackend(Protocol):
+    """将具体 Agent Runtime 适配为 ACP 会话服务。"""
+
+    agent_name: str
+    agent_version: str
+    supports_load_session: bool
+
+    async def create_session(
+        self,
+        session_id: str,
+        cwd: str,
+        mcp_servers: list[JsonObject],
+    ) -> AcpSession: ...
+
+    async def load_session(
+        self,
+        session_id: str,
+        cwd: str,
+        mcp_servers: list[JsonObject],
+    ) -> AcpSession: ...
+
+    async def prompt(
+        self,
+        session: AcpSession,
+        text: str,
+        emit: AcpEmitter,
+        request_permission: AcpPermissionRequester,
+    ) -> JsonObject: ...
+
+    async def cancel(self, session: AcpSession) -> None: ...
+
+
+__all__ = [
+    "AcpBackend",
+    "AcpEmitter",
+    "AcpPermissionRequester",
+    "AcpSession",
+    "AcpUpdate",
+    "JsonObject",
+]