Skip to content

xike110/OpenCode-Python-SDK

Repository files navigation

OpenCode Python SDK

状态: ✅ 已完成 | 版本: 0.1.0-dev | 完成度: 100% | 测试覆盖率 30%(待完成)

一个功能完整、文档齐全、测试覆盖良好的高质量 Python 客户端库。

✨ 项目特点

  • 功能完整 - 14 个资源类,75 个 API 方法
  • 类型安全 - 100% 类型提示覆盖
  • 中文注释 - 100% 中文注释
  • 异步支持 - 完整的异步 API
  • 测试完善 - 测试过30个用例,30% 测试覆盖率(其他暂未测试,拿到手自己测试)
  • 易于使用 - 简洁的 API 设计

🚀 安装

# 从 GitHub 克隆仓库
git clone https://github.com/xike110/OpenCode-Python-SDK.git

# 进入项目目录
cd OpenCode-Python-SDK

# 从本地安装
pip install -e .

🎯 新手启动步骤

第一步:环境准备

确保你已安装以下软件:

# 检查 Python 版本(需要 3.8+)
python --version

# 检查 pip 是否已安装
pip --version

第三步:验证安装

# 创建一个测试脚本 test_install.py
python -c "from opencode_sdk import OpencodeClient; print('✅ SDK 安装成功!')"

同步发行消息

创建文件 hello_opencode.py

from opencode_sdk import OpencodeClient

# 初始化客户端 - 使用 /api 前缀
client = OpencodeClient(
    base_url="http://192.168.77.28:8001",
    directory="/data/seo/workspace"
)

# 创建一个新会话
print("📝 创建会话...")
session = client.sessions.create(title="测试会话")
print(f"✅ 会话已创建,ID: {session.id}")

# 发送一条消息
print("\n💬 发送消息...")
response = client.sessions.prompt(
    session_id=session.id,
    parts=[{"type": "text", "text": "当前时间"}],
    agent="build",
    model={
        "modelID": "gpt-5-nano",
        "providerID": "opencode"
    },
    variant="low"
)

print(f"✅ 收到响应!")
print(f"消息ID: {response.id}")
print(f"角色: {response.role}")
print(f"时间: {response.time}")
print(f"模型: {response.model_id} ({response.provider_id})")
print(f"令牌: 输入={response.tokens.input}, 输出={response.tokens.output}, 推理={response.tokens.reasoning}")
print(f"部分 ({len(response.parts)}):")
for i, part in enumerate(response.parts):
    print(f"  [{i}] 类型: {part.type}")
    if hasattr(part, 'text') and part.text:
        text_preview = part.text[:100] + "..." if len(part.text) > 100 else part.text
        print(f"      文本: {text_preview}")
    if hasattr(part, 'reason'):
        print(f"      原因: {part.reason}")
    print(f"      ID: {part.id}")
print()


# 列出所有会话
print("\n📋 列出所有会话...")
sessions = client.sessions.list()
print(f"✅ 共有 {len(sessions)} 个会话")
for s in sessions[:5]:  # 只显示前5个
    print(f"  - {s.title} (ID: {s.id})")

流式消息(推荐)

使用异步方式获取流式响应,实时查看 AI 生成的内容:

import asyncio
from opencode_sdk import OpencodeClient


async def stream_chat():
    # 使用你的服务器地址
    client = OpencodeClient(base_url="http://192.168.77.28:8001")
    
    print("创建会话...")
    # 创建会话
    session = client.sessions.create(
        title="流式对话",
        directory="/data/seo/workspace"
    )
    
    print(f"会话已创建: {session.id}\n")
    print("AI 响应:\n")
    
    # 发送消息并接收流式响应
    try:
        async for event in client.events.subscribe_session(
            session_id=session.id,
            parts=[{"type": "text", "text": "当前时间"}],
            directory="/data/seo/workspace",
            agent="build",
            model={
                "modelID": "gpt-5-nano",
                "providerID": "opencode"
            },
            variant="low"
        ):
            # 只打印流式文本的增量
            if event.type == "message.part.delta":
                print(event.properties.delta, end="", flush=True)
    except Exception as e:
        print(f"\n\n错误: {type(e).__name__}: {e}")
        import traceback
        traceback.print_exc()
    
    print("\n\n会话完成,正在清理...")
    client.sessions.delete(session.id)


# 运行
asyncio.run(stream_chat())

事件订阅方式

SDK 提供三种事件订阅方式,均返回异步迭代器:

1. subscribe_session - 订阅会话事件(推荐用于对话)

订阅特定会话的事件流,可发送消息并接收实时响应:

async for event in client.events.subscribe_session(
    session_id="session_id",
    parts=[{"type": "text", "text": "消息内容"}],
    directory="/data/seo/workspace",
    agent="build",
    model={"modelID": "gpt-5-nano", "providerID": "opencode"},
    variant="low"
):
    if event.type == "message.part.delta":
        # 实时打印 AI 生成的文本
        print(event.properties.delta, end="", flush=True)
    elif event.type == "session.idle":
        # 会话完成
        break

参数说明:

  • session_id (str, 必需) - 会话 ID
  • parts (list, 必需) - 消息部分列表,每部分包含 type 和内容
  • directory (str, 可选) - 工作目录路径
  • agent (str, 可选) - 代理名称(如 "build")
  • model (dict, 可选) - 模型配置,包含 modelIDproviderID
  • variant (str, 可选) - 变体级别("low"/"medium"/"high")

返回值: AsyncIterator[Event]

2. subscribe_global - 订阅全局事件(推荐用于监控)

订阅服务器全局事件,监控所有会话的活动:

async for event in client.events.subscribe_global():
    print(f"全局事件: {event.type}")
    
    if event.type == "session.created":
        # 访问会话信息
        info = event.properties.info
        print(f"新会话: {info.get('title')} (ID: {info.get('id')})")
    elif event.type == "message.part.delta":
        # 消息增量
        print(f"消息: {event.properties.delta}")

事件数据结构: 服务器返回的事件格式为:

{
  "directory": "/data/seo/workspace",
  "payload": {
    "type": "session.created",
    "properties": {...}
  }
}

SDK 会自动解包 payload 字段,你可以直接访问 event.typeevent.properties

返回值: AsyncIterator[GlobalEvent]

3. subscribe - 通用订阅(底层方法)

订阅事件流(可选指定会话 ID):

# 订阅全局事件
async for event in client.events.subscribe():
    print(f"事件: {event.type}")

# 订阅特定会话事件
async for event in client.events.subscribe(session_id="session_id"):
    print(f"会话事件: {event.type}")

返回值: AsyncIterator[Event]

常用事件类型

事件类型 说明 属性访问
message.part.delta 流式文本增量 event.properties.delta
message.part.updated 消息部分更新 event.properties.part
session.status 会话状态变化 event.properties.status
session.created 会话已创建 event.properties.info
session.error 会话错误 event.properties.error
file.edited 文件已编辑 event.properties.file

🔧 功能特性

  • 会话管理: 创建、列表、更新、删除会话(24 个方法)
  • 消息处理: 发送消息、获取响应、流式事件
  • 文件操作: 读取、列表、搜索文件(3 个方法)
  • 提供商管理: 配置 AI 提供商和模型(4 个方法)
  • MCP 集成: 管理模型上下文协议服务器(9 个方法)
  • 事件流: 通过 SSE 订阅实时事件(3 个方法)
  • PTY 管理: 终端会话管理(6 个方法)
  • TUI 集成: 终端 UI 交互(11 个方法)
  • 类型安全: 完整的类型提示和 Pydantic 模型(100+ 个模型)
  • 异步支持: 支持 Async/await
  • 中文注释: 100% 中文文档

📊 项目统计

类别 数量
资源类 14
API 方法 75
数据模型 100+
测试用例 30+
文档 24+
代码行数 16,000+
测试覆盖率 30%

📚 文档

项目中提供的完整文档:

核心文档

API 文档

核心资源

  • Session(会话): 管理 AI 编码会话(24 个方法)
  • Event(事件): 订阅实时事件(3 个方法)
  • Project(项目): 列表和管理项目(2 个方法)
  • Config(配置): 获取和更新配置(3 个方法)
  • Provider(提供商): 管理 AI 提供商(4 个方法)
  • File(文件): 文件操作(3 个方法)
  • Find(查找): 搜索功能(3 个方法)
  • MCP: 模型上下文协议集成(9 个方法)
  • LSP: 语言服务器协议(1 个方法)
  • PTY: 终端会话(6 个方法)
  • Tool(工具): 列出可用工具(2 个方法)
  • TUI: 终端 UI 交互(11 个方法)
  • App(应用): 应用管理(3 个方法)
  • Command(命令): 命令管理(1 个方法)

📄 许可证

MIT 许可证 - 详见 LICENSE 文件。

🔗 相关链接

💬 支持

About

OpenCode Python SDK

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors