@tencent-ai/codebuddy-code 2.67.0-next.ed1b89f.20260329 → 2.68.0

package/dist/web-ui/docs/cn/cli/sdk-python.md

@@ -0,0 +1,783 @@
+# Python SDK 参考
+
+> **版本要求**：本文档针对 CodeBuddy Agent SDK v0.1.0 及以上版本。
+
+本文档提供 Python SDK 的完整 API 参考。有关快速入门和使用示例，请参阅 [SDK 概览](sdk.md)。
+
+## Requirements
+
+| 依赖 | 版本要求 |
+|---------|----------|
+| Python | >= 3.10 |
+| CodeBuddy CLI | 已安装 |
+
+**异步运行时**：SDK 基于 `asyncio`，所有 API 都是异步的。
+
+## Installation
+
+推荐使用 [uv](https://docs.astral.sh/uv/) 进行依赖管理：
+
+```bash
+uv add codebuddy-agent-sdk
+```
+
+或使用 pip：
+
+```bash
+pip install codebuddy-agent-sdk
+```
+
+### 环境变量
+
+| 变量名 | 说明 | 必需 |
+|--------|------|------|
+| `CODEBUDDY_CODE_PATH` | CodeBuddy CLI 可执行文件路径 | 可选 |
+
+如果未设置，SDK 会按以下顺序查找 CLI：
+1. 环境变量 `CODEBUDDY_CODE_PATH`
+2. SDK 包内置的二进制文件
+3. 开发环境 monorepo 路径
+
+### 认证配置
+
+SDK 支持使用已有登录凭据、API Key 或 OAuth Client Credentials 认证，详见 [SDK 概览 - 认证配置](sdk.md#认证配置）。
+
+## Functions
+
+### query()
+
+主要 API 入口，创建一个查询并返回消息异步迭代器。
+
+```python
+async def query(
+    *,
+    prompt: str | AsyncIterable[dict[str, Any]],
+    options: CodeBuddyAgentOptions | None = None,
+    transport: Transport | None = None,
+) -> AsyncIterator[Message]:
+```
+
+**参数**：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `prompt` | `str \| AsyncIterable[dict]` | 查询提示词或用户消息流 |
+| `options` | `CodeBuddyAgentOptions` | 配置选项（可选） |
+| `transport` | `Transport` | 自定义传输层（可选） |
+
+**返回值**：`AsyncIterator[Message]` - 消息异步迭代器
+
+**示例**：
+
+```python
+from codebuddy_agent_sdk import query, AssistantMessage, TextBlock
+
+async for message in query(prompt="What is 2+2?"):
+    if isinstance(message, AssistantMessage):
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                print(block.text)
+```
+
+## Client Class
+
+### CodeBuddySDKClient
+
+用于双向交互式对话的客户端类。支持多轮对话、中断和动态控制。
+
+```python
+class CodeBuddySDKClient:
+    def __init__(
+        self,
+        options: CodeBuddyAgentOptions | None = None,
+        transport: Transport | None = None,
+    ): ...
+```
+
+**方法**：
+
+#### connect()
+
+连接到 CodeBuddy。
+
+```python
+async def connect(
+    self,
+    prompt: str | AsyncIterable[dict[str, Any]] | None = None
+) -> None:
+```
+
+#### query()
+
+发送用户消息。
+
+```python
+async def query(
+    self,
+    prompt: str | AsyncIterable[dict[str, Any]],
+    session_id: str = "default",
+) -> None:
+```
+
+#### receive_response()
+
+接收消息直到收到 ResultMessage。
+
+```python
+async def receive_response(self) -> AsyncIterator[Message]:
+```
+
+#### receive_messages()
+
+接收所有消息（不会自动停止）。
+
+```python
+async def receive_messages(self) -> AsyncIterator[Message]:
+```
+
+#### disconnect()
+
+断开连接。
+
+```python
+async def disconnect(self) -> None:
+```
+
+**上下文管理器支持**：
+
+```python
+async with CodeBuddySDKClient() as client:
+    await client.query("Hello!")
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+#### mcp_server_status()
+
+获取 MCP 服务器连接状态。
+
+```python
+async def mcp_server_status(self) -> list[McpServerStatus]:
+```
+
+## Authentication
+
+SDK 提供独立的认证 API，采用 **two-phase** 设计：先获取登录 URL，再等待用户完成认证。
+
+### authenticate()
+
+启动认证流程，返回 `AuthFlow` 对象。
+
+```python
+async def authenticate(
+    *,
+    method_id: str = "external",
+    environment: str | None = None,
+    endpoint: str | None = None,
+    codebuddy_code_path: str | None = None,
+    env: dict[str, str] | None = None,
+    timeout: float = 300.0,
+) -> AuthFlow:
+```
+
+**参数**：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `method_id` | `str` | 认证方法标识（默认 `"external"`） |
+| `environment` | `str \| None` | 预定义环境名 |
+| `endpoint` | `str \| None` | 自定义端点 URL（与 environment 互斥） |
+| `codebuddy_code_path` | `str \| None` | CLI 可执行文件路径 |
+| `env` | `dict[str, str] \| None` | 额外环境变量 |
+| `timeout` | `float` | 用户完成登录的超时时间（秒，默认 300） |
+
+**返回值**：`AuthFlow` — 携带登录 URL 的可等待对象
+
+**示例**：
+
+```python
+from codebuddy_agent_sdk import authenticate
+
+# Two-phase: 获取 URL → 展示给用户 → 等待完成
+auth = await authenticate()
+if auth.auth_url:
+    print(f"请访问: {auth.auth_url}")
+result = await auth
+print(f"欢迎, {result.userinfo.user_name}")
+
+# 已登录时 auth.auth_url 为空，await 立即返回
+auth = await authenticate()
+result = await auth  # 已登录则立即返回
+
+# 自定义超时
+auth = await authenticate()
+result = await auth.wait(timeout=60)
+```
+
+### AuthFlow
+
+认证流程对象，由 `authenticate()` 返回。实现了 `__await__` 协议，可直接 `await`。
+
+**属性**：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `auth_url` | `str` | 登录 URL（已登录时为空字符串） |
+| `method_id` | `str \| None` | 认证方法标识 |
+
+**方法**：
+
+#### wait()
+
+等待用户完成认证。
+
+```python
+async def wait(self, timeout: float | None = None) -> AuthenticateResponse:
+```
+
+#### cancel()
+
+取消认证流程并释放资源。
+
+```python
+async def cancel(self) -> None:
+```
+
+### logout()
+
+登出并清除缓存的认证令牌。
+
+```python
+async def logout(
+    *,
+    environment: str | None = None,
+    endpoint: str | None = None,
+    codebuddy_code_path: str | None = None,
+    env: dict[str, str] | None = None,
+) -> None:
+```
+
+**示例**：
+
+```python
+from codebuddy_agent_sdk import logout
+
+await logout()
+```
+
+## Unstable API
+
+> **警告**：以下 API 处于实验阶段，接口可能在未来版本中变更。
+
+### interrupt()
+
+发送中断信号。
+
+```python
+async def interrupt(self) -> None:
+```
+
+### set_permission_mode()
+
+动态修改权限模式。
+
+```python
+async def set_permission_mode(self, mode: str) -> None:
+```
+
+### set_model()
+
+动态修改模型。
+
+```python
+async def set_model(self, model: str | None = None) -> None:
+```
+
+## Types
+
+### CodeBuddyAgentOptions
+
+完整配置选项：
+
+```python
+@dataclass
+class CodeBuddyAgentOptions:
+    allowed_tools: list[str] = field(default_factory=list)
+    disallowed_tools: list[str] = field(default_factory=list)
+    system_prompt: str | AppendSystemPrompt | None = None
+    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
+    permission_mode: PermissionMode | None = None
+    continue_conversation: bool = False
+    resume: str | None = None
+    max_turns: int | None = None
+    model: str | None = None
+    fallback_model: str | None = None
+    cwd: str | Path | None = None
+    codebuddy_code_path: str | Path | None = None
+    env: dict[str, str] = field(default_factory=dict)
+    extra_args: dict[str, str | None] = field(default_factory=dict)
+    stderr: Callable[[str], None] | None = None
+    hooks: dict[HookEvent, list[HookMatcher]] | None = None
+    include_partial_messages: bool = False
+    fork_session: bool = False
+    agents: dict[str, AgentDefinition] | None = None
+    setting_sources: list[SettingSource] | None = None
+    can_use_tool: CanUseTool | None = None
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `allowed_tools` | `list[str]` | 自动允许的工具白名单 |
+| `disallowed_tools` | `list[str]` | 禁止使用的工具黑名单 |
+| `system_prompt` | `str \| AppendSystemPrompt` | 系统提示词配置 |
+| `mcp_servers` | `dict[str, McpServerConfig]` | MCP 服务器配置 |
+| `permission_mode` | `PermissionMode` | 权限模式 |
+| `continue_conversation` | `bool` | 继续最近的会话 |
+| `resume` | `str` | 要恢复的会话 ID |
+| `max_turns` | `int` | 最大对话轮数 |
+| `model` | `str` | 指定模型 |
+| `fallback_model` | `str` | 备用模型 |
+| `cwd` | `str \| Path` | 工作目录 |
+| `codebuddy_code_path` | `str \| Path` | CLI 可执行文件路径 |
+| `env` | `dict[str, str]` | 环境变量 |
+| `extra_args` | `dict[str, str \| None]` | 额外的 CLI 参数 |
+| `stderr` | `Callable[[str], None]` | stderr 回调 |
+| `hooks` | `dict[HookEvent, list[HookMatcher]]` | Hook 配置 |
+| `include_partial_messages` | `bool` | 包含部分消息 |
+| `fork_session` | `bool` | 分叉会话 |
+| `agents` | `dict[str, AgentDefinition]` | 自定义 Agent |
+| `setting_sources` | `list[SettingSource]` | 设置来源 |
+| `can_use_tool` | `CanUseTool` | 权限回调函数 |
+| `max_thinking_tokens` | `int` | 最大思考 token 数（已废弃，请使用 `thinking`） |
+| `thinking` | `ThinkingConfig` | 思考模式配置：`{"type": "adaptive"}`、`{"type": "enabled", "budget_tokens": N}` 或 `{"type": "disabled"}` |
+| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh'` | 模型推理努力程度 |
+
+### PermissionMode
+
+```python
+PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"]
+```
+
+| 值 | 说明 |
+|-----|------|
+| `"default"` | 默认模式，所有操作需确认 |
+| `"acceptEdits"` | 自动批准文件编辑 |
+| `"plan"` | 规划模式，仅允许读取 |
+| `"bypassPermissions"` | 跳过所有权限检查 |
+
+### PermissionResult
+
+```python
+PermissionResult = PermissionResultAllow | PermissionResultDeny
+
+@dataclass
+class PermissionResultAllow:
+    updated_input: dict[str, Any]
+    behavior: Literal["allow"] = "allow"
+    updated_permissions: list[dict[str, Any]] | None = None
+
+@dataclass
+class PermissionResultDeny:
+    message: str
+    behavior: Literal["deny"] = "deny"
+    interrupt: bool = False
+```
+
+### CanUseTool
+
+```python
+CanUseTool = Callable[
+    [str, dict[str, Any], CanUseToolOptions],
+    Awaitable[PermissionResult],
+]
+
+@dataclass
+class CanUseToolOptions:
+    tool_use_id: str
+    signal: Any | None = None
+    agent_id: str | None = None
+    suggestions: list[dict[str, Any]] | None = None
+    blocked_path: str | None = None
+    decision_reason: str | None = None
+```
+
+### AgentDefinition
+
+```python
+@dataclass
+class AgentDefinition:
+    description: str        # Agent 描述
+    prompt: str             # 系统提示词
+    tools: list[str] | None = None           # 允许的工具
+    disallowed_tools: list[str] | None = None  # 禁止的工具
+    model: str | None = None                 # 使用的模型
+```
+
+### McpServerConfig
+
+```python
+class McpStdioServerConfig(TypedDict):
+    type: NotRequired[Literal["stdio"]]
+    command: str
+    args: NotRequired[list[str]]
+    env: NotRequired[dict[str, str]]
+
+McpServerConfig = McpStdioServerConfig
+```
+
+### HookEvent
+
+```python
+HookEvent = (
+    Literal["PreToolUse"]
+    | Literal["PostToolUse"]
+    | Literal["UserPromptSubmit"]
+    | Literal["Stop"]
+    | Literal["SubagentStop"]
+    | Literal["PreCompact"]
+    | Literal["WorktreeCreate"]
+    | Literal["WorktreeRemove"]
+)
+```
+
+### HookMatcher
+
+```python
+@dataclass
+class HookMatcher:
+    matcher: str | None = None      # 匹配模式（支持正则）
+    hooks: list[HookCallback] = field(default_factory=list)
+    timeout: float | None = None    # 超时时间（秒）
+```
+
+### HookCallback
+
+```python
+HookCallback = Callable[
+    [Any, str | None, HookContext],
+    Awaitable[HookJSONOutput],
+]
+
+class HookContext(TypedDict):
+    signal: Any | None
+
+class SyncHookJSONOutput(TypedDict):
+    continue_: NotRequired[bool]
+    suppressOutput: NotRequired[bool]
+    stopReason: NotRequired[str]
+    decision: NotRequired[Literal["block"]]
+    reason: NotRequired[str]
+```
+
+### SettingSource
+
+控制 SDK 从哪些文件系统位置加载配置。
+
+```python
+SettingSource = Literal["user", "project", "local"]
+```
+
+| 值 | 说明 | 位置 |
+|-----|------|------|
+| `"user"` | 全局用户设置 | `~/.codebuddy/settings.json` |
+| `"project"` | 项目共享设置 | `.codebuddy/settings.json` |
+| `"local"` | 项目本地设置 | `.codebuddy/settings.local.json` |
+
+**默认行为**：当 `setting_sources` 未指定时，SDK **不加载任何文件系统配置**。这提供了完全干净的运行环境。
+
+```python
+# 默认：不加载任何配置（干净环境）
+async for msg in query(prompt="..."):
+    pass
+
+# 加载项目配置
+options = CodeBuddyAgentOptions(setting_sources=["project"])
+
+# 加载所有配置（类似 CLI 行为）
+options = CodeBuddyAgentOptions(setting_sources=["user", "project", "local"])
+```
+
+### AppendSystemPrompt
+
+```python
+@dataclass
+class AppendSystemPrompt:
+    append: str  # 追加到默认系统提示词的内容
+```
+
+## Message Types
+
+### Message
+
+所有消息类型的联合：
+
+```python
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent
+```
+
+### SystemMessage
+
+```python
+@dataclass
+class SystemMessage:
+    subtype: str
+    data: dict[str, Any]
+```
+
+### UserMessage
+
+```python
+@dataclass
+class UserMessage:
+    content: str | list[ContentBlock]
+    uuid: str | None = None
+    parent_tool_use_id: str | None = None
+```
+
+### AssistantMessage
+
+```python
+@dataclass
+class AssistantMessage:
+    content: list[ContentBlock]
+    model: str
+    parent_tool_use_id: str | None = None
+    error: str | None = None
+```
+
+### ResultMessage
+
+```python
+@dataclass
+class ResultMessage:
+    subtype: str
+    duration_ms: int
+    duration_api_ms: int
+    is_error: bool
+    num_turns: int
+    session_id: str
+    total_cost_usd: float | None = None
+    usage: dict[str, Any] | None = None
+    result: str | None = None
+```
+
+### StreamEvent
+
+```python
+@dataclass
+class StreamEvent:
+    uuid: str
+    session_id: str
+    event: dict[str, Any]
+    parent_tool_use_id: str | None = None
+```
+
+### ContentBlock
+
+```python
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+
+@dataclass
+class TextBlock:
+    text: str
+
+@dataclass
+class ThinkingBlock:
+    thinking: str
+    signature: str
+
+@dataclass
+class ToolUseBlock:
+    id: str
+    name: str
+    input: dict[str, Any]
+
+@dataclass
+class ToolResultBlock:
+    tool_use_id: str
+    content: str | list[dict[str, Any]] | None = None
+    is_error: bool | None = None
+```
+
+## Input Types
+
+### AskUserQuestionInput
+
+```python
+@dataclass
+class AskUserQuestionInput:
+    questions: list[AskUserQuestionQuestion]
+    answers: dict[str, str] | None = None
+```
+
+### AskUserQuestionQuestion
+
+```python
+@dataclass
+class AskUserQuestionQuestion:
+    question: str     # 完整问题文本（应以 ? 结尾）
+    header: str       # 简短标签（最多 12 个字符）
+    options: list[AskUserQuestionOption]
+    multi_select: bool  # 是否允许多选
+```
+
+### AskUserQuestionOption
+
+```python
+@dataclass
+class AskUserQuestionOption:
+    label: str        # 显示文本（1-5 个单词）
+    description: str  # 选项说明
+```
+
+## Errors
+
+所有异常都继承自 `CodeBuddySDKError`。
+
+### CodeBuddySDKError
+
+```python
+class CodeBuddySDKError(Exception):
+    """Base exception for CodeBuddy SDK errors."""
+    pass
+```
+
+### CLIConnectionError
+
+当连接到 CLI 失败或未建立连接时抛出。
+
+```python
+class CLIConnectionError(CodeBuddySDKError):
+    pass
+```
+
+### CLINotFoundError
+
+当找不到 CLI 可执行文件时抛出。
+
+```python
+class CLINotFoundError(CodeBuddySDKError):
+    def __init__(
+        self,
+        message: str,
+        platform: str | None = None,
+        arch: str | None = None,
+    ): ...
+```
+
+**属性**：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `platform` | `str \| None` | 当前平台 |
+| `arch` | `str \| None` | 当前架构 |
+
+### CLIJSONDecodeError
+
+当 CLI 输出的 JSON 解码失败时抛出。
+
+```python
+class CLIJSONDecodeError(CodeBuddySDKError):
+    pass
+```
+
+### ProcessError
+
+当 CLI 进程遇到错误时抛出。
+
+```python
+class ProcessError(CodeBuddySDKError):
+    pass
+```
+
+### CLIStartupError
+
+当 CLI 进程在启动阶段崩溃或未产生任何输出时抛出。
+
+```python
+class CLIStartupError(CodeBuddySDKError):
+    def __init__(
+        self,
+        message: str,
+        stderr: str = "",
+        exit_code: int | None = None,
+    ): ...
+```
+
+**属性**：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `stderr` | `str` | CLI 进程的 stderr 输出 |
+| `exit_code` | `int \| None` | 进程退出码 |
+
+### ExecutionError
+
+当执行失败时抛出（如认证错误、API 错误）。包含 ResultMessage 中的 errors 数组。
+
+```python
+class ExecutionError(CodeBuddySDKError):
+    def __init__(self, errors: list[str], subtype: str): ...
+```
+
+**属性**：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `errors` | `list[str]` | 错误消息列表 |
+| `subtype` | `str` | 错误子类型 |
+
+### AuthenticationError
+
+当认证失败时抛出。
+
+```python
+class AuthenticationError(CodeBuddySDKError):
+    def __init__(self, error_type: str, message: str): ...
+```
+
+**属性**：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `error_type` | `str` | 错误类型（如 `"timeout"`, `"auth_failed"`） |
+
+## Auth Types
+
+### AuthenticateResponse
+
+```python
+@dataclass(slots=True)
+class AuthenticateResponse:
+    userinfo: UserInfo
+```
+
+### UserInfo
+
+```python
+@dataclass(slots=True)
+class UserInfo:
+    user_id: str
+    user_name: str = ""
+    user_nickname: str = ""
+    token: str = ""
+    enterprise_id: str | None = None
+    enterprise: str | None = None
+```
+
+### McpServerStatus
+
+```python
+@dataclass(slots=True)
+class McpServerStatus:
+    name: str
+    status: Literal["connected", "failed", "needs-auth", "pending"]
+    server_info: dict[str, Any] | None = None
+```
+
+## 相关文档
+
+- [SDK 概览](sdk.md) - 快速入门和使用示例
+- [TypeScript SDK 参考](sdk-typescript.md) - TypeScript 版本 API
+- [Hook 参考指南](hooks.md) - 详细的 Hook 配置说明
+- [MCP 集成](mcp.md) - MCP 服务器配置指南