Koder SDK

Koder SDK 让你在 JavaScript、TypeScript 或 Python 程序里使用 Koder：在一个工作区里打开会话，流式读取结果，并决定允许哪些修改和命令。当前版本 0.1.1，MIT 许可。

要求

Node.js 22.13 或更高版本。
已安装的兼容版本 Koder CLI 及其运行时。SDK 先检查 ~/.koder-cli/current。可以用 KODER_CLI_ROOT 或 cliRoot（Python 里是 cli_root）指定安装位置；路径无效时会报错，不会悄悄换成别的副本。
Python 客户端需要 Python 3.9 或更高版本，它仍然会启动一个 Node 桥接进程。
KARMENLOOP 内核单独发布，使用它自己的条款。只有源代码、没有单独发布的运行时，无法执行任务。

在本地运行示例

git clone https://github.com/KarmenLoop/koder-sdk.git
cd koder-sdk
npm run build
node examples/custom-provider.mjs

这个示例使用一个进程内的模型提供者，在临时工作区里写入 hello.txt，读回后清理。它不会发送模型 API 请求，但仍然需要 CLI 和内核。

python3 -m pip install ./python
python3 python/examples/custom_provider.py

JavaScript 和 TypeScript

import { createKoder } from "./dist/index.mjs";

const koder = await createKoder({
  workspace: process.cwd(),
  permission: "deny",
});

try {
  const session = await koder.session({ readOnly: true });
  const run = session.send("Explain the main entry point in this project.");
  for await (const event of run) {
    if (event.type === "delta") process.stdout.write(event.text);
  }
  const result = await run;
  console.log(result.status, result.files);
} finally {
  await koder.close();
}

单轮调用用 query({ workspace, prompt, ...options })。相关的多轮对话复用同一个 session，每次 send 都要 await；需要新对话时调用 session.reset()。session.messages 是记录下来的历史。

Python

import asyncio
from koder_sdk import Koder

async def main():
    async with await Koder.create(workspace=".", permission="deny") as koder:
        session = await koder.session(read_only=True)
        result = await session.send("Explain the main entry point.")
        print(result.status, result.text)

asyncio.run(main())

Python 的选项用下划线命名，例如 read_only、cli_root、base_url。

模型设置

默认模型来自 Koder 的配置，或者环境变量 KODER_MODEL、KODER_BASE_URL、KODER_API_KEY。也可以直接传入 model: { model, baseUrl, apiKey }。密钥放在环境变量或系统凭据存储里，不要写进源代码。

注意：这里说的环境变量只适用于 SDK。Koder 桌面版不从环境变量或 .env 文件读取模型密钥。

其他环境变量

KODER_NODE 和 KODER_SDK_SERVER 用于指定 Node 可执行文件和桥接程序的路径。