harbor-sdk

图1：Harbor SDK 官方 Logo

背景：为什么需要 Harbor SDK？

在 AI Agent 大行其道的 2026 年，一个让开发者头疼的普遍问题是：**如何让 Agent 安全、可复用地调用外部工具和 API？**大多数解决方案走向两个极端：要么把工具硬编码在 Agent 内部，导致代码耦合、无法审计；要么过早依赖一个托管平台，还没验证工作流就先背上厂商锁定。

zonko-ai 团队推出的 Harbor SDK 试图给出第三条路——提供一个标准化的 SDK，让应用代码可以通过规范的 Promise 客户端调用 Harbor 平台能力，同时在本地开发时完全不依赖托管服务，按需接入。

Harbor 是什么？

Harbor 是一个 AI Agent 工具执行平台，核心解决三个问题：

1. 工具可组合性：让 Agent 调用的工具（Skill/Tool）可以像乐高积木一样自由组合
2. 密钥隔离：敏感凭据不进入 Agent 上下文，避免 Prompt Injection 泄露风险
3. 本地与托管统一：本地开发体验与生产托管平台使用同一套协议

tryharbor.ai 提供托管版，而 harbor-sdk 是这套体系的开源 SDK 包。

核心架构

Harbor SDK 采用分层架构，层次清晰：

第一层：应用端 @hrbr/client — 面向 App/Agent 代码的 Promise-first 客户端，返回普通 Promise，应用无需理解 Effect 或异步底层。支持浏览器、Node.js、CLI 等多种运行环境。

第二层：系统端 @hrbr/sdk — 面向 Harbor 平台系统本身的复合 Facade，导出 Agents、Core、Inspect、Orbit、Platform、Plugins、Protocol、Registry、Runtime 等九大命名空间，是平台 SDK 的完整入口。

第三层：本地平台 @hrbr/sdk/platform/local — 可以在本地初始化项目、启动兼容 Harbor 路由的服务器、记录执行历史，并运行一个小型前端界面，无需连接 tryharbor.ai。

Python 客户端 harbor_sdk — 与 TypeScript SDK 共享同一套生成协议（harbor_sdk_generated），同时提供同步和异步两种调用方式，适合脚本、数据管道等场景。

技术特性详解

① 密钥隔离安全模型 — Harbor 的设计哲学是：密钥和凭证存储在 Workspace 级别，Agent 运行时只能通过 Harbor API 调用工具，永远拿不到原始密钥。这从根本上规避了将 API Key 写入 Prompt 可能导致的泄露风险。

② 多语言客户端 — TypeScript 侧提供两种客户端：createHarborClient() 返回普通 Promise，@hrbr/client/effect 则将相同接口包装为 Effect 值，天然支持 Effect-TS 的错误处理和依赖注入生态。Python 侧提供 HarborClient（同步）和 AsyncHarborClient（异步），覆盖两种主流 Python 编程范式。

③ 运行时结果结构 — runtime.execute() 返回的结果包含原始 JSON 和结构化的 content 块（text、JSON、skill_bundle），应用代码可以按类型分发处理，无需自己解析 Prompt 输出。

④ 本地开发服务器 — @hrbr/sdk/platform/local 可在本地启动一个 Harbor 兼容服务，自带前端 Dashboard，数据存在本地文件，适合离线开发、安全敏感场景，以及在没有云服务的环境下验证 Harbor 工作流。

部署与上手

由于 Harbor SDK 本质是一个 SDK 包而非独立服务，部署流程取决于你的使用场景：

集成到现有项目（推荐）：TypeScript 侧 npm install @hrbr/client 或 npm install @hrbr/sdk，Python 侧 pip install harbor-sdk，然后按文档初始化 HarborClient 即可。

本地平台体验：bun run --filter local-platform-example serve 可启动本地 Harbor 兼容服务，打开浏览器访问 http://127.0.0.1:port，用 local-token 作为认证令牌即可体验完整 Dashboard。

前置依赖：Bun 1.3+（必须）、Node 22+（可选，TypeScript 开发用）、Python 3.10+（Python SDK）。无 GPU 需求，普通笔记本即可。

局限与注意事项

① 仍处于 Pre-release 阶段：v0.1.2 版本通过 GitHub Release 分发而非 npm/PyPI 正式注册包，需要通过 GitHub URL 直接安装，后续 API 可能有破坏性变更。

② 文档尚在完善：Python 客户端的 README 和示例相对 TypeScript 侧较少，对不熟悉 TypeScript 的纯 Python 开发者而言上手门槛略高。

③ 生态依赖 Harbor 平台：本地 SDK 客户端可以跑，但真正有价值的 Skill 注册、团队协作、Workspace 管理等功能需要接入 tryharbor.ai 托管平台。开源 SDK 本身只是客户端，本地服务缺乏这些协作能力。

行业意义

Harbor SDK 代表了 2026 年 AI Agent 基础设施的一个重要方向：密钥安全 + 工具标准化 + 本地优先。随着 Model Context Protocol (MCP) 生态的扩张，Agent 如何安全调用外部工具已成为行业核心议题。Harbor 的设计恰好踩在这个痛点上——不要求开发者把密钥交给 Agent，也不要求必须用某个托管平台，给了开发者更大的控制权。

从 GitHub 趋势看（398 stars，2026-05-11 创建，不到两个月），Harbor SDK 处于快速成长期。结合 zonko-ai 团队在 Agent 执行领域的积累，该项目值得持续关注。