SDK 与插件

DimCode 的可嵌入运行时发布为 @archships/dim-agent-sdk。本文档对应当前版本 @archships/[email protected]。

安装

npm install @archships/[email protected]

插件开发者同时安装公共插件契约包：

npm install @archships/[email protected] @archships/[email protected]

最小 Agent

import {
  createAgent,
  createModel,
  createOpenAIAdapter,
} from '@archships/dim-agent-sdk'

const model = createModel(
  createOpenAIAdapter({
    apiKey: process.env.OPENAI_API_KEY,
    baseUrl: 'https://api.openai.com/v1',
    defaultModel: 'gpt-4o-mini',
  }),
)

const agent = createAgent({
  model,
  cwd: process.cwd(),
  hostDataDir: '.dim/host-data',
})

const session = await agent.createSession({
  systemPrompt: 'You are a coding agent. Use tools when needed.',
})

const itemId = session.send('Inspect this repo and propose the next change.')

for await (const event of session.receive()) {
  if (event.itemId !== itemId) continue
  if (event.type === 'text_delta') process.stdout.write(event.delta)
  if (event.type === 'done') console.log(event.message.content)
}

Queue-first Session

Session 采用 queue-first 流程：

• session.send(input) 入队一条 user item，并返回 itemId。
• session.sendBatch(items) 批量入队 user items。
• session.steer(input) 给下一条待执行 item 增加 steer context。
• session.receive() 消费队列并输出流式事件。
• session.getQueueStatus()、cancelQueuedItem()、clearQueue() 提供宿主侧队列控制。

常用事件包括 text_delta、thinking_delta、tool_call_start、tool_call_args_delta、tool_call_end、tool_call、plugin_event、tool_result、usage_recorded、turn_usage、done、error。

Provider Adapters

SDK 导出 createModel() 和内置 adapter：

• createOpenAIAdapter() 与 createOpenAIResponsesAdapter()
• createAnthropicAdapter()
• createGeminiAdapter()
• createZenMuxAdapter()
• createAihubmixAdapter() 与 createAihubmixResponsesAdapter()
• createMoonshotAIAdapter()
• createDeepSeekAdapter()
• createXaiAdapter() 与 createXaiResponsesAdapter()

需要 provider 侧诊断时，可在 adapter options 中设置 debug.logFilePath；密钥字段默认会被脱敏。

Builtin Tools

createAgent() 默认注册四个本地 coding tools：

Tool	用途	说明
read	读取文件上下文	UTF-8 文本返回带行号窗口和 revision；模型支持 image input 时，常见图片会变成 synthetic user file context
write	写入 UTF-8 文本	创建或覆盖文件
edit	替换文本	带 revision guard，支持 replaceAll
exec	执行命令	flat argv-style input，支持前台/后台、process polling 与 explicit termination

exec 使用字符串数组命令：

{
  command: ['pnpm', 'test'],
  cwd: process.cwd(),
  yieldTimeMs: 1000,
  timeoutMs: 30000,
}

Persistence and Usage

使用 FileStateStore 或 InMemoryStateStore 持久化 session：

import { FileStateStore, createAgent } from '@archships/dim-agent-sdk'

const agent = createAgent({
  model,
  stateStore: new FileStateStore({ directory: '.dim/snapshots' }),
})

FileStateStore 会写入 <sessionId>.json 作为主快照，并写入 <sessionId>.usage.json 作为 usage ledger。可通过 session.getUsageSummary()、session.getTurnUsage(itemId)、session.listRequestUsages() 查询用量。

Compaction

SDK 导出 DEFAULT_COMPACTION_SAFETY_RATIO、buildCompactionBudget()、calculateThresholdTokens()、isContextWindowExceededError() 等 compaction helpers。自动历史摘要由官方 @archships/dim-plugin-auto-compact 提供。

Official Plugins

Package	Version	Status
@archships/dim-plugin-auto-compact	0.0.19	supported auto compaction
@archships/dim-plugin-devtools	0.0.3	supported local inspector
@archships/dim-plugin-grep-glob	0.0.9	supported grep / glob tools
@archships/dim-plugin-mcp-client	0.0.9	supported MCP client
@archships/dim-plugin-skills	0.0.13	supported file-backed skills
@archships/dim-plugin-plan-mode	0.0.13	supported planning guardrail
@archships/dim-plugin-research-mode	0.0.4	experimental research guardrail
@archships/dim-plugin-memory	0.0.3	stub
@archships/dim-plugin-web	0.0.3	stub
@archships/dim-plugin-scheduler	0.0.3	stub

Devtools

import { createDevtoolsPlugin } from '@archships/dim-plugin-devtools'

const agent = createAgent({
  model,
  cwd: process.cwd(),
  hostDataDir: '.dim/host-data',
  plugins: [createDevtoolsPlugin({ autoOpenBrowser: false })],
})

const session = await agent.createSession()
const devtools = session.getPlugin('devtools')

console.log(await devtools?.getInspectorUrl())

Devtools plugin 使用 hostDataDir 保存 runtime journals 和 provider request history。

GoatChain Migration

从 GoatChain-style runtime 迁移时，核心概念对应如下：

GoatChain concern	Dim SDK path
Agent/session lifecycle	createAgent()、createSession()、restoreSession()
Queue execution	send()、sendBatch()、steer()、receive()
Model adapters	createModel(createOpenAIAdapter(...)) 和其他内置 adapters
Local coding tools	Built-in read、write、edit、exec
Plugins/middleware	官方 plugins 与 @archships/dim-plugin-api hooks
Persistence	FileStateStore、InMemoryStateStore、split usage ledger
Subagents	SubagentOrchestrator、in-process executors、process executors

Agent runtime 使用 SDK，通用扩展使用官方 plugins，UI、auth、tenancy、deployment policy 放在宿主应用层实现。