txcode-sdk

AI Agent SDK with built-in tools for Python projects.

Installation

• 要求：Python >= 3.6（含 3.6/3.7/3.8/3.9/3.10/3.11/3.12）
• 零第三方运行时依赖（仅标准库，适合门禁设备等离线环境）

pip install txcode-sdk

Quick Start

import asyncio
from txcode_sdk import TxCodeClient

async def main():
    client = TxCodeClient(
        api_key="sk-xxx",
        base_url="https://api.openai.com/v1",
        model="gpt-4",
    )
    result = await client.chat("Hello!")
    print(result.answer)

asyncio.get_event_loop().run_until_complete(main())

Features

• ReAct Agent loop with tool calling
• Multiple agent types: code, chat, common, task, plan, shell, skill, test, design, discuss, dream, name
• 10 built-in tools: read_file, write_file, edit_file, glob, grep, bash, memory, web_shell_exec, todo_read, todo_write
• Session management with JSON file persistence
• Context compression for long conversations
• Multimodal input support (images)
• Extensible custom tools
• Self-developed HTTP client (urllib, no openai/tiktoken dependency), supports OpenAI / DeepSeek / any OpenAI-compatible API

WebSocket Server

SDK 内置零第三方依赖的 WebSocket 服务端（RFC 6455 自研协议层，Python 3.6 兼容）， 支持 txcode 桌面版远程连接：把 SDK 安装到门禁 ARM 设备（Ubuntu 18 / Python 3.6）后， Agent 循环与全部内置工具（read_file / write_file / edit_file / glob / grep / bash / todo 等） 在设备本地执行，桌面版仅作为远程操作界面——实现"直接在门禁系统上开发门禁系统代码"。

一条命令启动（主推）

pip install txcode-sdk

txcode-sdk serve --work-dir 您的目录

• --work-dir：门禁代码目录（必填，仅首次启动无当前项目时注册为当前项目），Agent 与内置工具在此目录下本地执行
• --host / --port：默认 0.0.0.0:41000
• --agent-type：默认 code
• --models：默认供应商初始模型列表 [显示名=]模型名 逗号分隔（仅首次注册默认供应商时使用）；缺省读 TXCODE_MODELS，再缺省 = 不限制
• TXCODE_API_KEY：可选——仅当 ~/.txcode/providers.json 不存在且希望首次自动注册默认供应商时使用；未设置时服务以空配置正常启动（stderr 打印 WARN 提示），供应商由桌面端通过 WS add_provider / switch_provider 动态添加，无需重启
• 兜底启动：python -m txcode_sdk.server serve --work-dir ...（无脚本路径时同样可用）

启动装配（JSON 为权威源，0.4.1）

服务启动时以用户层 JSON 为权威源恢复上次状态，重启自动恢复上次激活供应商/模型与当前项目：

1. 供应商：加载 ~/.txcode/providers.json——存在则取激活供应商的 (api_key, base_url, model) 直接构造 TxCodeClient（不读 TXCODE_BASE_URL / TXCODE_MODEL）；不存在（首次启动/全新环境）且设置了 TXCODE_API_KEY（可选）时以 TXCODE_BASE_URL / TXCODE_MODEL 注册默认供应商并激活（--models 作为初始模型列表）； 未设置 TXCODE_API_KEY 时以空配置正常启动（占位 client，不发起任何 API 请求）， 供应商由桌面端经 WS add_provider / switch_provider 动态添加；未配置供应商前 chat / name_session 会收到「No active provider configured」提示，其余能力（WS 握手、ping、配置/项目管理消息）全部可用
2. 项目：加载 ~/.txcode/projects.json——有当前项目则其 path 作为 work_dir（不读 TXCODE_WORK_DIR）； 无当前项目则 --work-dir 注册为当前项目后使用

配置（供应商/模型/项目列表）存用户层 ~/.txcode/，跨项目共享、切换项目不影响； 会话仍按项目分别存于各自工作目录 {work_dir}/.txcode/session/。

桌面版连接

1. 桌面版「主机管理」添加远程主机：IP = 门禁设备 IP，端口 = 41000
2. 桌面版自动以 ws://{ip}:{port}/ws/code 连接（无需任何桌面版改动）
3. 发起对话：AI 在门禁系统本地读写文件、执行 bash 编译/运行/调试代码
4. 文件变更实时推送（file:changed 事件），前端自动刷新文件树与编辑器

协议消息

供应商与模型管理

服务端支持动态添加/编辑/删除多个供应商（OpenAI / DeepSeek / 自建网关），配置实时持久化到用户层 ~/.txcode/providers.json，服务重启自动恢复；聊天消息携带 modelName 命中即切换（自动匹配供应商）， 也可用 switch_provider 显式切换。

~/.txcode/providers.json 结构（配置在用户层，跨项目共享，不随 work_dir 变化）：

{
  "providers": [
    {
      "id": "3f2a...",
      "name": "OpenAI",
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-xxx",
      "models": [{"name": "gpt-4o", "display_name": "GPT-4o"}],
      "created_at": "2026-08-14T...",
      "updated_at": "2026-08-14T..."
    }
  ],
  "active_provider_id": "3f2a...",
  "active_model": "gpt-4o"
}

• 模型限制规则：供应商 models 为空列表 = 不限制（向后兼容）；非空 = 白名单校验
• 显示名：display_name 对齐桌面版模型选择器语义（如 DeepSeek V3 = deepseek-chat）， 匹配 name 与 display_name 双通道；add_model 缺省 display_name = name
• api_key 安全：WS 协议返回打码值（sk-*** + 后 4 位）；update_provider 传打码值/空不改原 key； 明文仅存于用户层本地文件（权限建议 chmod 600）
• 模型解析定序：激活供应商优先 → 跨供应商按列表顺序第一个命中 → 未限制放行 → 全未命中回 error: Model not allowed: xxx, available: [..]

项目管理

远程模式下桌面版右上角「打开项目 / 选择项目」由 SDK 侧 WS 协议提供等价能力：项目列表 / 打开（目录校验）/ 选择（切换当前项目）/ 删除（不删实际文件），数据持久化到用户层 ~/.txcode/projects.json（跨项目记忆）； 选择/打开项目后 SDK 实时切换 work_dir（Agent 与内置工具基准目录立即生效，切换前中断全部运行中会话）。

~/.txcode/projects.json 结构：

{
  "projects": [
    {"id": "a1b2...", "name": "door-access", "path": "/opt/door-access",
     "created_at": "2026-08-14T...", "updated_at": "2026-08-14T..."}
  ],
  "current_project_id": "a1b2..."
}

安全边界：供应商 api_key 明文存于用户层 ~/.txcode/providers.json（本地文件，与 TS 版 sys_config 数据库同等级别），仅限内网/受信网络部署，建议 chmod 600；WS 协议无鉴权，建议防火墙限制端口来源。

step 事件数据形状（对齐桌面版）：

{
  "type": "step",
  "data": {
    "reasoning": "...",
    "toolCalls": [{"id": "call-1", "type": "function", "function": {"name": "bash", "arguments": "{\"command\": \"python3 main.py\"}"}, "status": "completed"}],
    "success": true,
    "iteration": 1,
    "sessionId": "xxx",
    "usage": {"promptTokens": 10, "completionTokens": 5, "totalTokens": 15}
  }
}

自定义工具（进阶，需写代码）

txcode-sdk serve CLI 只支持内置工具（远程开发场景完全够用）。 需要对接门禁硬件控制（open_door / get_door_status 等）时，走进阶示例 src/example/ws_server.py：注册自定义工具 + 启动 TxCodeServer。

import asyncio
from txcode_sdk import Tool, ToolResult, TxCodeClient
from txcode_sdk.server import TxCodeServer

def open_door(args, ctx):
    return ToolResult(success=True, output="door opened")

client = TxCodeClient(
    api_key="sk-xxx", work_dir="/opt/door-access",
    tools=[Tool(name="open_door", description="打开门禁",
                parameters={"type": "object", "properties": {}}, execute=open_door)],
)
server = TxCodeServer(client, host="0.0.0.0", port=41000)
asyncio.get_event_loop().run_until_complete(server.start())
asyncio.get_event_loop().run_forever()

门禁系统部署（Ubuntu 18 / ARM）

# 1. 安装（离线可先下载 wheel 拷贝）
pip install txcode-sdk
python3 -c "import txcode_sdk; print(txcode_sdk.__version__)"

# 2. 验证端口监听
txcode-sdk serve --work-dir /opt/door-access &
ss -ltn | grep 41000

# 3. systemd 常驻（/etc/systemd/system/txcode-sdk.service）
# [Service] Environment=TXCODE_API_KEY=sk-xxx
# ExecStart=/usr/local/bin/txcode-sdk serve --work-dir /opt/door-access
# Restart=always

安全边界：协议无鉴权（与桌面版/TS 版一致），仅限内网/受信网络部署， 建议防火墙限制 41000 端口来源；鉴权（token 校验）列为二期增强。