API 列表

August 14, 2026 · View on GitHub

本插件 API 的权威参考（版本 0.1.0，源码 src/）。README 为用户导向的精简版；两者冲突以本文件为准。类型信息以构建产物 lib/types/*.d.ts 为准；本文档为人工维护的概要。

1. 插件入口（`src/index.ts`）

1.1 Cordis 插件契约

导出	类型	说明
`name`	`string`	`'koboldcpp-tool'`
`inject`	`string[]`	`['tools']`
`Config`	`z<Config>`	schemastery schema（见 1.2）
`apply(ctx, config)`	`(ctx: Context, config: Config) => void`	插件入口

1.2 `Config`（插件配置；也作为 `llm-koboldcpp:` settings 段 schema）

字段	类型	默认	说明
`baseURL`	string	`http://127.0.0.1:5001`	服务器端点；`/v1/chat/completions` 被追加
`model`	string	`koboldcpp`	发送给服务器的 wire model id
`toolName`	string	`koboldcpp_run`	文本工具名
`toolDescription`	string	内置	覆盖文本工具描述
`enableVisionTool`	boolean	`true`	是否注册视觉工具
`visionToolName`	string	`koboldcpp_vision`	视觉工具名
`visionToolDescription`	string	内置	覆盖视觉工具描述
`exePath`	string	—（或 `$KOBOOLDCPP_EXE`）	koboldcpp 可执行文件绝对路径
`kcppsPath`	string	—（或 `$KOBOOLDCPP_KCPPS`）	kcpps 启动配置绝对路径
`extraArgs`	string[]	`[]`	追加的 CLI 参数（排在 `--port` 之后）
`autoStart`	boolean	`true`	无服务器时按需拉起
`stopBehavior`	`'never'\|'idle'\|'exit'`	`'exit'`	服务器停止策略
`idleStopMinutes`	number	`30`	`idle` 策略的空闲窗口（分钟）
`launchTimeoutMs`	number	`300000`	拉起后等待健康的总预算（ms）
`healthIntervalMs`	number	`2000`	健康探测间隔（ms）
`timeoutMs`	number	`120000`	单次本地模型调用预算（ms）
`maxTokens`	number	`8192`	请求默认输出上限（tokens）

1.3 `resolveOptions(config, environment?)`

(config: Config, environment?: LaunchEnvironmentSnapshot) => ResolvedOptions

配置的唯一显式解析步骤：验证 baseURL/端口/工具名/数值边界，合并环境变量（KOBOOLDCPP_EXE / KOBOOLDCPP_KCPPS），组装 launch 事实。失败抛 Error（fail loud）。

1.4 `ResolvedOptions`

baseURL: string
model: string
toolName: string
toolDescription: string
enableVisionTool: boolean
visionToolName: string
visionToolDescription: string
timeoutMs: number
maxTokens: number
launch: KoboldCppLaunchOptions

2. 工具（模型可见 API）

2.1 `koboldcpp_run` — 文本工具

参数：

参数	类型	必填	说明
`prompt`	string	是	发给本地模型的指令/文本（user 消息）
`system`	string	否	系统指令
`temperature`	number	否	采样温度 0–2
`max_tokens`	integer	否	输出上限（默认 `maxTokens`）
`stop`	string[]	否	停止序列

返回值（canonical value）：

{
  text: string            // 模型原始文本输出
  reasoning?: string      // 思考文本（模型输出时）
  model: string           // 服务器报告的模型 id
  usage: { promptTokens: integer, completionTokens: integer }
  elapsedMs: integer
}

render：text + 脚注 (ran on local <model> · <in> in / <out> out tokens · <ms>ms)。

2.2 `koboldcpp_vision` — 多模态/OCR 工具

参数：

参数	类型	必填	说明
`mode`	`'analyze'\|'ocr'\|'compare'`	否	内置提示词模板（默认 `analyze`）
`prompt`	string	否	自定义指令（覆盖模板）
`image_paths`	string[]	否	本地图片绝对路径（png/jpg/jpeg/webp/gif/bmp，≤20 MB/张）
`image_urls`	string[]	否	`data:image/...` 或 `http(s)://` URL
`temperature`	number	否	采样温度（OCR 建议 ~0.2）
`max_tokens`	integer	否	输出上限
`stop`	string[]	否	停止序列

图片来源解析顺序：image_paths + image_urls（合并）→ 会话内附件（最近的图像，经 ctx.attachments.readImage）→ 失败（isError + 清晰消息）。

返回值：同 2.1 加 images: integer（处理的图片数）。

提示词模板：mode 对应 src/prompts.ts 的三个内置模板（analyze = 8 段 # Image Analysis Report；ocr = 逐字提取；compare = 5 段 # Image Comparison Report），完整文本见 §6。

3. 进程生命周期（`src/launch.ts`）

3.1 `KoboldCppServer` 类

成员	签名	说明
`constructor`	`(ctx: Context, options: () => KoboldCppLaunchOptions)`	options 为 thunk，每次操作重新解析（支持设置热更新）
`status()`	`() => KoboldCppServerStatus`	`{ running, owned, pid? }` 当前事实
`healthy()`	`() => Promise<boolean>`	探测 `GET /v1/models`（超时 = `healthIntervalMs`）
`ensure()`	`() => Promise<void>`	确保健康服务器可达：复用外部 → 否则按 `autoStart`/`exePath` 拉起（单飞并发保护）
`stop()`	`() => Promise<void>`	停掉 owned 服务器；Windows 上 `taskkill /T /F` 杀进程树；外部服务器 no-op
`dispose()`	`() => Promise<void>`	全量清理（`stopBehavior !== 'never'` 时停服），幂等
`beginStream()` / `endStream()`	`() => void`	工具执行期间的空闲保护（进行中的调用不会被 idle 停掉）
`touch()`	`() => void`	重置空闲计时器（`stopBehavior: 'idle'` 时）

3.2 纯函数

导出	签名	说明
`portOf`	`(baseURL: string) => number`	从 baseURL 解析端口；缺省 5001
`buildLaunchArgs`	`(options: KoboldCppLaunchOptions) => string[]`	`[kcppsPath?, '--port', port, ...extraArgs]`

3.3 常量

SERVER_NOT_RUNNING_CODE / MISCONFIGURED_CODE / LAUNCH_FAILED_CODE（'SERVER_NOT_RUNNING' / 'MISCONFIGURED' / 'LAUNCH_FAILED'）。

4. 客户端（`src/koboldcpp.ts`）

导出	签名	说明
`chatCompletion`	`(baseURL: string, request: ChatCompletionRequest) => Promise<ChatCompletion>`	非流式 `/v1/chat/completions`；多模态时发送 OpenAI `content` 数组
`httpErrorCode`	`(status: number, error?: {message?; type?; code?}) => KoboldCppErrorCode`	HTTP 状态 → 稳定错误码

ChatCompletionRequest：

model: string
system?: string
prompt: string
images?: string[]          // data:image/... URL；存在时 prompt+images 组成 content 数组
temperature?: number
maxTokens?: number
stop?: string[]
signal: AbortSignal        // 必须；内部合并超时

ChatCompletion：{ text, reasoning?, model, usage: { promptTokens, completionTokens } }。

错误语义（抛 LlmError，code 稳定）：

code	触发
`TRANSPORT`	网络失败（DNS/拒绝连接/TLS）
`ABORTED`	调用方取消
`TIMEOUT`	`AbortSignal.timeout` 到期
`AUTH` / `RATE_LIMIT` / `CONTEXT_WINDOW_EXCEEDED` / `INVALID_REQUEST` / `SERVER` / `HTTP_<n>` / `QUOTA`	HTTP 状态映射（含 provider 错误正文识别）
`EMPTY_RESPONSE`	模型空输出

5. 图像准备（`src/images.ts`）

导出	签名	说明
`MAX_IMAGE_BYTES`	`const`	`20 * 1024 * 1024`
`mimeOf`	`(path: string) => string \| undefined`	扩展名 → MIME
`isSupportedImagePath`	`(path: string) => boolean`	格式支持判断
`imageFileToDataUrl`	`(path: string, signal?: AbortSignal) => Promise<string>`	本地文件 → data URL（校验存在/大小/格式）
`imageUrlToDataUrl`	`(url: string, signal: AbortSignal) => Promise<string>`	`data:` 透传；`http(s)` 下载转 data URL
`collectSessionImageDataUrls`	`(ctx: Context, exec: VisionExecContext) => Promise<string[]>`	会话内图片（最新优先，去重；无 attachment 服务时返回空）

6. 提示词模板（`src/prompts.ts`）

导出	说明
`VisionMode`	`'analyze' \| 'ocr' \| 'compare'`
`ANALYZE_PROMPT` / `OCR_PROMPT` / `COMPARE_PROMPT`	内置模板（8 段 / 逐字 / 5 段）
`VISION_FIDELITY_RULE`	fidelity 规则文本
`resolveVisionPrompt`	`(mode: VisionMode, prompt?: string) => string`（自定义优先）

7. 其他导出

KoboldCppLaunchOptions（类型）：baseURL / port / exePath? / kcppsPath? / extraArgs / autoStart / stopBehavior / idleStopMinutes / launchTimeoutMs / healthIntervalMs
KoboldCppServerStatus（类型）：{ running, owned, pid? }
VisionExecContext（类型）：{ signal: AbortSignal; agent?: { session: { events: readonly unknown[] } } }

8. 环境变量

变量	用途	优先级
`KOBOOLDCPP_EXE`	exePath 兜底	settings > cordis config > 环境变量
`KOBOOLDCPP_KCPPS`	kcppsPath 兜底	同上