omp-ark-coding-plan

在 Oh My Pi（OMP）中连接火山方舟 Coding Plan，并将可用模型同步到 OMP 的模型列表。

插件提供一个 /ark 命令：

• /ark connect：输入并验证 Ark API Key，保存配置，同时完成首次模型同步。
• /ark sync：使用已保存的 API Key 刷新模型列表。

前置条件

• 已安装并可运行 OMP。
• 已开通火山方舟 Coding Plan，并取得 Ark API Key（通常以 sk- 开头）。
• 本地运行环境能够直接加载 TypeScript ESM 扩展，并提供全局 fetch。

安装

从 npm 安装

使用 OMP 的插件安装命令：

omp install omp-ark-coding-plan

安装完成后，重启或重新加载 OMP，即可使用 /ark。

从源码安装

需要开发或调试插件时，获取本仓库并在仓库根目录执行：

bun install
omp install .

插件直接以 TypeScript ESM 源码作为 OMP 扩展入口，不需要单独构建。package.json 中的 omp.extensions 指向 ./src/index.ts。

本项目没有固定 Bun/Node 版本；运行环境需要支持直接加载 TypeScript ESM 扩展并提供全局 fetch。

使用

首次连接

在支持交互输入的 OMP 会话中执行：

/ark connect

根据提示输入 Ark API Key。插件会：

1. 请求 https://ark.cn-beijing.volces.com/api/coding/v3/models 验证 API Key；
2. 筛选可用于文本聊天或编程的模型；
3. 将 ArkCodingPlan provider 写入当前 agent 的 models.yml；
4. 在宿主支持实时模型注册时，立即将模型加入 /models。

如果输入被取消、API Key 为空、凭证无效或 Ark 接口不可用，现有配置不会被本次连接覆盖。

刷新模型

连接成功后执行：

/ark sync

插件会使用 models.yml 中 ArkCodingPlan.apiKey 重新获取并合并模型。如果尚未连接，会提示先运行 /ark connect。

配置位置

插件按以下顺序确定 agent 目录：

1. OMP 宿主提供的当前 agent 目录；
2. 环境变量 PI_CODING_AGENT_DIR；
3. 默认目录 ~/.omp/agent。

配置文件为该目录下的 models.yml。连接后会包含类似内容：

providers:
  ArkCodingPlan:
    baseUrl: https://ark.cn-beijing.volces.com/api/coding/v3
    apiKey: sk-...
    api: openai-completions
    models:
      - id: example-model
        name: Ark Coding Plan - Example Model
        reasoning: true
        input: [text]
        contextWindow: 128000
        maxTokens: 32768
        cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 }

baseUrl、provider 名称和 API 类型由插件固定管理，不需要手动填写。

同步规则

• 自动排除已下线、Embedding、3D 生成、图片/视频生成等不适合作为聊天模型的条目。
• 根据 Ark 返回的能力设置文本/图片输入、推理支持、上下文窗口和最大输出长度。
• 按模型 ID 排序，重复执行 /ark sync 会得到稳定结果。
• Ark 仍返回但已不再可用的模型会被移除。
• Ark 响应中完全不存在的自定义模型 ID 或稳定别名会被保留。
• 对于相同模型 ID，手动调整过的 cost 会被保留。
• 其他 provider 和 models.yml 中无关的顶层配置会被保留。

凭证与文件安全

API Key 会以明文保存在当前 agent 的 models.yml 中，供后续 /ark sync 使用。插件写入时使用 0600 权限，并通过临时文件原子替换配置文件。

请勿提交或分享包含真实 API Key 的 models.yml。如果凭证泄露，请立即在火山方舟控制台撤销并重新生成。

常见问题

/ark connect requires an interactive UI

当前 OMP 宿主没有提供交互输入能力。请在支持输入框的 OMP 会话中执行 /ark connect。

Ark is not connected

当前 agent 的 models.yml 中没有可用的 ArkCodingPlan.apiKey。执行 /ark connect 完成连接。

Cannot read models.yml

检查当前 agent 目录、PI_CODING_AGENT_DIR 以及 YAML 格式。models.yml 的根节点和 providers 都必须是映射。

HTTP 401 或 HTTP 403

API Key 无效、已过期，或当前账号没有对应服务权限。检查火山方舟控制台中的凭证和 Coding Plan 状态。

同步成功但 /models 没有立即更新

实时更新依赖 OMP 宿主提供模型注册能力。配置已经保存到 models.yml 时，可重启或重新加载当前 OMP agent。

当前限制

• 仅支持固定的北京区域 Coding Plan 兼容端点：https://ark.cn-beijing.volces.com/api/coding/v3。
• /ark connect 必须在支持交互输入的 OMP 宿主中运行。
• 仓库当前没有自动化测试、CI 或构建产物。