API Reference

本页覆盖 colony-harness 全部 18 个包的完整 API 文档。每个包包含安装命令、快速示例和参数表。

Core Runtime

Core

`colony-harness`

核心运行时包。包含 HarnessBuilder、ColonyHarness、AgenticLoop、ToolRegistry、MemoryManager、TraceHub、Guardrails 及 5 个内置护栏。

pnpm add colony-harness

HarnessBuilder

声明式构建器 API —— 唯一入口。通过链式调用组装 LLM、工具、记忆、追踪和护栏。

typescript

import { HarnessBuilder } from 'colony-harness'

const harness = new HarnessBuilder()
  .llm(provider)
  .tool(calculatorTool)
  .memory(adapter)
  .trace(exporter)
  .guard(new PromptInjectionGuard())
  .build()

方法	参数	说明
`llm(provider)`	`LLMProvider`	注入模型调用器（必需）
`tool(...tools)`	`ToolDefinition[]`	注册工具
`toolApproval(cb)`	`(name, input) => Promise<boolean>`	高风险工具审批回调
`memory(adapter)`	`MemoryAdapter`	指定记忆后端
`memoryConfig(cfg)`	见下表	配置记忆策略
`trace(...exporters)`	`TraceExporter[]`	配置 trace 导出器
`guard(...guards)`	`Guard[]`	配置护栏
`loopConfig(cfg)`	见下表	配置 Agentic Loop 行为
`systemPrompt(text)`	`string`	覆盖默认系统提示词
`build()`	—	构建并返回 `ColonyHarness` 实例

loopConfig 参数：

字段	默认值	说明
`maxIterations`	`20`	最大迭代轮次
`callTimeout`	`30000`	单次模型调用超时 (ms)
`modelFailStrategy`	`abort`	模型失败策略：`abort` / `retry`
`modelRetryMax`	`2`	模型重试最大次数（策略为 `retry` 时）
`modelRetryBaseDelayMs`	`300`	模型重试基础退避时间 (ms)
`modelRetryMaxDelayMs`	`5000`	模型重试退避时间上限 (ms)
`modelRetryJitterRatio`	`0.2`	模型重试抖动比例（0~1）
`modelRetryMaxTotalDelayMs`	`15000`	模型重试总等待预算上限 (ms)
`modelCircuitBreakerEnabled`	`true`	是否启用模型熔断器
`modelCircuitBreakerFailureThreshold`	`5`	熔断触发阈值（连续瞬态失败次数）
`modelCircuitBreakerCooldownMs`	`30000`	熔断冷却时间 (ms)
`maxTokens`	无	总 Token 上限
`toolConcurrency`	`1`	工具并发度
`toolFailStrategy`	`abort`	失败策略：`abort` / `continue` / `retry`
`toolRetryMax`	`2`	重试最大次数（策略为 `retry` 时）

memoryConfig 参数：

字段	默认值	说明
`workingMemoryTokenLimit`	`6000`	Working memory 压缩阈值
`episodicRetentionDays`	`30`	Episodic 记忆保留天数
`semanticTopK`	`5`	语义检索默认返回条数
`autoCompress`	`true`	是否自动压缩上下文
`embedder`	无	语义向量函数 `(text) => number[]`

ColonyHarness

运行时容器。注册任务处理器、构建上下文、执行护栏和追踪。

typescript

const harness = builder.build()

harness.task('chat', async (ctx) => {
  const result = await ctx.runLoop('用户的问题')
  return result
})

const result = await harness.runTask('chat', { question: 'Hello' })

方法	参数	说明
`task(capability, handler)`	`string, (ctx) => Promise`	注册任务处理器
`runTask(capability, input, opts?)`	见下表	执行任务

runTask options：

字段	说明
`taskId`	外部任务 ID（对齐控制面）
`agentId`	Agent 标识
`sessionId`	会话标识
`signal`	`AbortSignal`，用于取消

HarnessContext

任务 handler 内可用的上下文对象。

typescript

harness.task('research', async (ctx) => {
  // 运行 Agent Loop
  const reply = await ctx.runLoop('搜索最新论文')

  // 直接调用工具
  const calc = await ctx.invokeTool('calculator', { expression: '2+2' })

  // 记忆操作
  await ctx.memory.save('key', { data: 'value' })
  const recent = await ctx.memory.recent(10)

  // 追踪
  const span = ctx.trace.startSpan('step')
  span.end()
})

属性/方法	类型	说明
`runLoop(prompt)`	`string => Promise<string>`	启动 Agentic Loop
`invokeTool(name, input)`	`(string, any) => Promise<any>`	直接调用已注册工具
`callModel(messages)`	`Message[] => Promise<ModelResponse>`	直接调用 LLM
`callModelWithTools(msgs, tools)`	带工具定义的 LLM 调用	调用 LLM 并传入工具列表
`memory`	`MemoryHandle`	记忆操作接口
`trace`	`TraceHandle`	追踪操作接口
`input`	`any`	任务输入数据

内置护栏

所有护栏均从 colony-harness 包导出。

护栏	说明	配置参数
`PromptInjectionGuard`	正则检测常见注入模式	无
`PIIGuard`	脱敏中文身份证/手机号/邮箱	无
`TokenLimitGuard`	拒绝超 Token 阈值的输入	`{ maxTokens: number }`
`SensitiveWordGuard`	拒绝包含敏感词的输入	`{ words: string[] }`
`RateLimitGuard`	滑动窗口限流	`{ windowMs, maxRequests }`

错误类

错误类	场景
`HarnessError`	基础错误
`ToolNotFoundError`	工具未注册
`ToolInputValidationError`	工具输入校验失败
`ToolOutputValidationError`	工具输出校验失败
`ToolApprovalDeniedError`	工具审批被拒
`LoopMaxIterationsError`	达到最大迭代次数
`LoopMaxTokensError`	达到最大 Token 数
`GuardBlockedError`	被护栏拦截
`MemoryAdapterError`	记忆适配器异常

LLM Providers

LLM

`@colony-harness/llm-openai`

OpenAI Chat Completions API 适配器。处理 tool calling、token 追踪和超时控制。

pnpm add @colony-harness/llm-openai

typescript

import { OpenAIProvider } from '@colony-harness/llm-openai'

const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o',
})

参数	必需	默认值	说明
`apiKey`	是	—	OpenAI API Key
`model`	是	—	模型名称
`baseUrl`	否	`https://api.openai.com/v1`	自定义端点
`temperature`	否	—	采样温度
`timeoutMs`	否	—	请求超时 (ms)
`headers`	否	—	额外请求头

LLM

`@colony-harness/llm-anthropic`

Anthropic Messages API 适配器。自动分离 system 消息，映射 tool_use 格式，规范化 stop_reason。

pnpm add @colony-harness/llm-anthropic

typescript

import { AnthropicProvider } from '@colony-harness/llm-anthropic'

const provider = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-20250514',
})

参数	必需	默认值	说明
`apiKey`	是	—	Anthropic API Key
`model`	是	—	Claude 模型名
`baseUrl`	否	`https://api.anthropic.com`	自定义端点
`maxTokens`	否	—	输出 Token 上限
`temperature`	否	—	采样温度
`timeoutMs`	否	—	超时 (ms)
`anthropicVersion`	否	`2023-06-01`	API 版本
`headers`	否	—	额外请求头

LLM

`@colony-harness/llm-gemini`

Google Gemini generateContent API 适配器。映射消息角色和 functionDeclarations，规范化 finishReason。

pnpm add @colony-harness/llm-gemini

typescript

import { GeminiProvider } from '@colony-harness/llm-gemini'

const provider = new GeminiProvider({
  apiKey: process.env.GEMINI_API_KEY!,
  model: 'gemini-1.5-pro',
})

参数	必需	默认值	说明
`apiKey`	是	—	Gemini API Key
`model`	是	—	模型名称
`baseUrl`	否	Gemini API URL	自定义端点
`temperature`	否	—	采样温度
`timeoutMs`	否	—	超时 (ms)
`headers`	否	—	额外请求头

LLM

`@colony-harness/llm-openai-compatible`

兼容 OpenAI Chat Completions 协议的通用适配器。适用于国内大模型或自部署端点。继承自 OpenAIProvider。

pnpm add @colony-harness/llm-openai-compatible

typescript

import { OpenAICompatibleProvider, createOpenAICompatibleProviderFromEnv } from '@colony-harness/llm-openai-compatible'

// 手动创建
const provider = new OpenAICompatibleProvider({
  apiKey: 'your-key',
  model: 'your-model',
  baseUrl: 'https://your-endpoint.com/v1',
})

// 从环境变量创建
const provider2 = createOpenAICompatibleProviderFromEnv()

参数	必需	说明
`apiKey`	是	API Key
`model`	是	模型名称
`baseUrl`	是	兼容端点 URL（必需）
...其他	—	同 `OpenAIProvider`

所有 Provider 统一返回 ModelResponse，包含 content、toolCalls、stopReason（completed | tool_calls | max_tokens | unknown）和 usage。

Memory Adapters

Memory

`@colony-harness/memory-sqlite`

SQLite 持久化记忆适配器。支持索引加速的 agent+created_at 查询、余弦相似度语义搜索、按会话清理，自动建表。

pnpm add @colony-harness/memory-sqlite

typescript

import { SqliteMemoryAdapter } from '@colony-harness/memory-sqlite'

const memory = new SqliteMemoryAdapter({
  path: './data/agent-memory.db',
})

参数	默认值	说明
`path`	`./memory.db`	SQLite 数据库文件路径

Memory

`@colony-harness/memory-redis`

Redis 记忆适配器。Hash 存储条目、Sorted Set 时间排序、Pipeline 优化写入，JS 端余弦相似度搜索。

pnpm add @colony-harness/memory-redis

typescript

import { RedisMemoryAdapter } from '@colony-harness/memory-redis'

const memory = new RedisMemoryAdapter({
  url: process.env.REDIS_URL,
  namespace: 'my-agent',
})

参数	默认值	说明
`url`	`REDIS_URL` 环境变量	Redis 连接 URL
`namespace`	`colony:memory`	Key 前缀
`redis`	—	传入已有 ioredis 实例

Trace Exporters

Trace

`@colony-harness/trace-console`

终端彩色追踪器。ANSI 色彩展示 TraceID、任务信息、耗时、Metrics 和 Span 细节。

pnpm add @colony-harness/trace-console

typescript

import { ConsoleTraceExporter } from '@colony-harness/trace-console'

const exporter = new ConsoleTraceExporter()

无配置参数。开箱即用。

Trace

`@colony-harness/trace-file`

JSONL 文件追踪器。追加写入完成后的 Trace，支持 pretty-print JSON 模式。

pnpm add @colony-harness/trace-file

typescript

import { FileTraceExporter } from '@colony-harness/trace-file'

const exporter = new FileTraceExporter({
  path: './logs/traces.jsonl',
  pretty: true,
})

参数	默认值	说明
`path`	`./traces.jsonl`	输出文件路径
`pretty`	`false`	是否 pretty-print JSON

Trace

`@colony-harness/trace-otel`

OpenTelemetry 桥接器。将 Trace 转换为 OTel Span，对齐 OpenInference 语义字段（openinference.span.kind、session.id、user.id、input/output.value 与 mime_type）。

pnpm add @colony-harness/trace-otel

typescript

import { OpenTelemetryTraceExporter } from '@colony-harness/trace-otel'

const exporter = new OpenTelemetryTraceExporter()

需要先初始化 @opentelemetry/api SDK。Exporter 将 colony-harness 的 Span 映射为 OTel Span 上的 Event。

Trace

`@colony-harness/trace-langfuse`

Langfuse 原生导出器。使用 Batch API 发送 Trace 和 Observation，支持自定义 fetch 和 tags。

pnpm add @colony-harness/trace-langfuse

typescript

import { LangfuseTraceExporter } from '@colony-harness/trace-langfuse'

const exporter = new LangfuseTraceExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  baseUrl: 'https://cloud.langfuse.com',
})

参数	必需	说明
`publicKey`	是	Langfuse Public Key
`secretKey`	是	Langfuse Secret Key
`baseUrl`	否	Langfuse 实例 URL
`fetch`	否	自定义 fetch 实现
`tags`	否	附加 tags

Built-in Tools

Tools

`@colony-harness/tools-builtin`

8 个内置工具，覆盖数学计算、文件操作、HTTP 请求、命令执行、网页搜索、JSON 查询和模板渲染。

pnpm add @colony-harness/tools-builtin

一次性注册全部工具：

typescript

import { createBuiltinTools } from '@colony-harness/tools-builtin'

const allTools = createBuiltinTools({
  file: { baseDir: '/workspace', allowOutsideBaseDir: false },
  runCommand: { mode: 'allowlist', allowed: ['ls', 'cat', 'grep'] },
})

单个工具详情

calculatorTool — 安全数学表达式计算

typescript

import { calculatorTool } from '@colony-harness/tools-builtin'
// 输入: { expression: "1 + 2 * 3" }
// 输出: { result: 7 }

严格字符过滤，仅允许数字和基本运算符。

httpRequestTool — HTTP 请求

typescript

// 输入: { method: "GET", url: "https://api.example.com/data", headers: {} }
// 输出: { status: 200, headers: {...}, body: "..." }

可配置超时和最大 body 大小。

createReadFileTool(options) — 读取文件

typescript

import { createReadFileTool } from '@colony-harness/tools-builtin'

const readFile = createReadFileTool({
  baseDir: '/workspace',
  allowOutsideBaseDir: false,
})

路径沙箱防止目录穿越攻击。

createWriteFileTool(options) — 写入文件

typescript

const writeFile = createWriteFileTool({
  baseDir: '/workspace',
})

支持 append 模式和自动创建目录。

createRunCommandTool(options) — 执行 Shell 命令

typescript

import { createRunCommandTool } from '@colony-harness/tools-builtin'

const runCmd = createRunCommandTool({
  mode: 'allowlist',
  allowed: ['ls', 'cat', 'grep', 'node'],
  timeout: 30_000,
  approvalByRisk: {
    requiredFrom: 'medium',
    callback: async (cmd) => {
      return confirm(`Allow: ${cmd}?`)
    },
  },
})

参数	说明
`mode`	`'allowlist'` 或 `'blocklist'`
`allowed / blocked`	命令白名单/黑名单
`timeout`	执行超时 (ms)
`approvalByRisk`	风险分级审批配置

默认阻止 rm、sudo、dd 等危险命令。返回 audit 字段用于审计留痕。

createSearchWebTool(provider?) — 网页搜索

typescript

import { createSearchWebTool } from '@colony-harness/tools-builtin'

const search = createSearchWebTool() // 默认 DuckDuckGo

支持自定义 SearchWebProvider 接口接入其他搜索引擎。

jsonQueryTool — JSON 查询

typescript

// 输入: { data: { a: { b: [1, 2, 3] } }, path: "$.a.b[0]" }
// 输出: { result: 1 }

类 JSONPath 语法（$.a.b[0].c），纯查询无副作用。

templateRenderTool — 模板渲染

typescript

// 输入: { template: "Hello {{name}}, your score is {{score}}", data: { name: "Alice", score: 95 } }
// 输出: { result: "Hello Alice, your score is 95" }

占位符渲染，纯渲染无副作用。

Evaluation

Eval

`@colony-harness/evals`

完整评测工具包。包含 runEvalSuite 执行器、7 种内置 Scorer 和 evaluateGate 质量门禁。

pnpm add @colony-harness/evals

typescript

import { runEvalSuite, exactMatchScorer, evaluateGate } from '@colony-harness/evals'

const report = await runEvalSuite({
  cases: [
    { id: 'test-1', input: '1+1', expected: '2' },
  ],
  runner: async (input) => myAgent(input),
  scorer: exactMatchScorer(),
})

const gate = evaluateGate({ report, thresholds: { minPassRate: 0.95 } })

runEvalSuite

参数	类型	说明
`cases`	`EvalCase[]`	测试用例集
`runner`	`(input) => Promise<any>`	被评测执行函数
`scorer`	`Scorer`	评分函数
`signal`	`AbortSignal`	中止信号
`failFast`	`boolean`	失败后立即停止

内置 Scorer

Scorer	用途	配置
`exactMatchScorer()`	精确 JSON 结构匹配	无
`containsScorer(opts)`	包含预期短语	`{ ignoreCase?, mode: 'all' \| 'any' }`
`regexScorer(opts)`	正则匹配	`{ flags? }`
`numericRangeScorer()`	数值范围验证	`{ min?, max? }`
`llmJudgeScorer(opts)`	LLM 主观评分	`{ judge, passThreshold }`
`safetyScorer(opts)`	安全模式检查	`{ blockedPatterns?, requiredPatterns? }`
`latencyScorer(opts)`	延迟评分	`{ targetMs, maxMs }`

evaluateGate

typescript

const gate = evaluateGate({
  report,
  thresholds: {
    minPassRate: 0.95,
    minWeightedScore: 0.85,
    maxLatencyMs: 5000,
  },
})
// gate.passed: boolean
// gate.failures: string[]

Control Plane

`@colony-harness/controlplane-contract`

控制面统一端口契约。定义所有接口类型，无具体实现。

pnpm add @colony-harness/controlplane-contract

导出的核心类型：

类型	说明
`ControlPlanePort`	控制面接口：`start()`、`stop()`、`onTaskAssign()`、`onTaskCancel()`、`reportProgress()`、`reportResult()`、`reportHealth()`
`TaskEnvelope`	任务信封（包含 capability、input 等）
`TaskResultEnvelope`	任务结果信封
`TaskErrorEnvelope`	任务错误信封
`TaskProgressEvent`	进度事件
`HealthStatusEvent`	健康状态事件
`TaskExecutionMetrics`	执行指标

Control Plane

`@colony-harness/controlplane-runtime`

运行时桥接器。连接 ColonyHarness 核心与 ControlPlanePort，管理任务生命周期、注册处理器、追踪运行任务、支持 AbortController 取消。

pnpm add @colony-harness/controlplane-runtime

typescript

import { HarnessControlPlaneRuntime } from '@colony-harness/controlplane-runtime'

const runtime = new HarnessControlPlaneRuntime(harness, controlPlaneAdapter)
await runtime.start()

Control Plane

`@colony-harness/controlplane-mock-adapter`

内存 Mock 适配器。存储进度事件、结果和健康事件。支持 dispatchTask() 直接注入任务，用于测试。

pnpm add @colony-harness/controlplane-mock-adapter

typescript

import { MockControlPlaneAdapter } from '@colony-harness/controlplane-mock-adapter'

const mock = new MockControlPlaneAdapter()
await mock.dispatchTask({ capability: 'chat', input: { msg: 'hello' } })

Control Plane

`@colony-harness/controlplane-sdk-adapter`

Queen SDK 适配器。通过 colony-bee-sdk 连接 Queen 控制面。使用鸭子类型 BeeAgentLike 接口（非硬依赖），支持动态 SDK 加载。

pnpm add @colony-harness/controlplane-sdk-adapter

typescript

import { BeeSDKControlPlaneAdapter, loadBeeAgentFromModule } from '@colony-harness/controlplane-sdk-adapter'

const adapter = new BeeSDKControlPlaneAdapter({
  colonyId: 'my-colony',
  capabilities: ['analyze', 'summarize'],
})

导出的工具函数：

导出	说明
`BeeSDKControlPlaneAdapter`	Queen 控制面适配器
`loadBeeAgentFromModule(path)`	动态加载 SDK 模块
`InMemoryBeeAgentStub`	内存 BeeAgent 桩（测试用）

API Reference ​

Core Runtime ​

colony-harness ​

HarnessBuilder ​

ColonyHarness ​

HarnessContext ​

内置护栏 ​

错误类 ​

LLM Providers ​

@colony-harness/llm-openai ​

@colony-harness/llm-anthropic ​

@colony-harness/llm-gemini ​

@colony-harness/llm-openai-compatible ​

Memory Adapters ​

@colony-harness/memory-sqlite ​

@colony-harness/memory-redis ​

Trace Exporters ​

@colony-harness/trace-console ​

@colony-harness/trace-file ​

@colony-harness/trace-otel ​

@colony-harness/trace-langfuse ​

Built-in Tools ​

@colony-harness/tools-builtin ​

单个工具详情 ​

Evaluation ​

@colony-harness/evals ​

runEvalSuite ​

内置 Scorer ​

evaluateGate ​

Control Plane ​

@colony-harness/controlplane-contract ​

@colony-harness/controlplane-runtime ​

@colony-harness/controlplane-mock-adapter ​

@colony-harness/controlplane-sdk-adapter ​

API Reference

Core Runtime

`colony-harness`

HarnessBuilder

ColonyHarness

HarnessContext

内置护栏

错误类

LLM Providers

`@colony-harness/llm-openai`

`@colony-harness/llm-anthropic`

`@colony-harness/llm-gemini`

`@colony-harness/llm-openai-compatible`

Memory Adapters

`@colony-harness/memory-sqlite`

`@colony-harness/memory-redis`

Trace Exporters

`@colony-harness/trace-console`

`@colony-harness/trace-file`

`@colony-harness/trace-otel`

`@colony-harness/trace-langfuse`

Built-in Tools

`@colony-harness/tools-builtin`

单个工具详情

Evaluation

`@colony-harness/evals`

runEvalSuite

内置 Scorer

evaluateGate

Control Plane

`@colony-harness/controlplane-contract`

`@colony-harness/controlplane-runtime`

`@colony-harness/controlplane-mock-adapter`

`@colony-harness/controlplane-sdk-adapter`