支柱三 · Connector（带凭证的边缘）

更新于 · 在 sijie.xyz 查看原条目 ↗

父级：key-designs

每一次带凭证的对外接触都要经过同一层：connector.Hub + 分类插槽（category slots）。消费方（agent 能力、平台功能、IM 桥；job-loop 至今仍不是消费方）看到的是固定的分类契约（CalendarProxy、MailProxy —— backend/internal/connector/contract/），拿到的是一个调用句柄——凭证永远不会跨过这条边界（通过 cryptobox 以 AES-256-GCM 静态加密）。有两种：openapi（面向单个 SaaS 的 HTTP：spec + JSONata 绑定，凭证表单从 securitySchemes 派生而来）和protocol（SMTP/CalDAV：内置的 Go 实现，protocol_smtp.go / protocol_caldav.go；没有 IMAP）。第三个 protocol 连接器 telegram（分类 im）于 2026-09-04 落地（8c819f26d，protocol_telegram.go）：它只保存 bot token —— 没有分类契约、没有 Verifier —— 由独立的 im-bridge 通过 GET /internal/im/config 读取（cmd/server/boot_im.go）。connector.Service（service.go + svc_*.go；旧的 connectorsvc 包已于 2026-07-26 合并进来，1bc9ba8b0）是管理面（creds/connect/oauth/activate/disconnect）；retry 为每个调用类别提供策略；egress/SSRF 防护把守出口。能力依赖（Requires:["calendar"]）通过 capreg/depresolver.go 解析——依赖未满足 ⟹ 能力被隐藏，fail-closed（失败即关闭）。

现状： 代理层最先落地；可安装（installable）已落地（上传流程可用；红契约存量 = 36789537d 时 66 个 connector-*.spec.ts；fixme 尾巴已清空；TODO-impl 的 mock 基础设施缺口已于 2026-07-03 关闭，059dc5c13 —— 剩 0 处）；同步模式（sync-mode）已落地（2026-07-08，d51805372，backend/internal/connector/sync.go）—— connector.NewSyncConnector + SyncIngester 能力把"摄入"变成一等的连接器种类，/obsidian/import 现在经接口委派，而不是内联调 SyncVault（routes/admin/obsidian.go:218；DTO 在边界上 1:1 改名，于是连接器层仍然不依赖 usecase）。36789537d 时 17 个 sync-*.spec.ts / 118 条测试，行为一致。刻意推迟的，到 36789537d 仍然如此（NewSyncConnector 在 sync.go 之外没有调用方）：把它注册进 Hub 以获得一张 admin UI 卡片 —— 那需要把 cmd→server 的依赖穿下去，而sync-mode 这层抽象没有它照样承重。（Connector ≠ MCP；action 与 sync 的区别——见 confusables。）

已被取代——everything-is-a-block（eiab），2026-09-13 → 2026-09-18（在上面 36789537d 那次核对之后）

这根支柱作为独立模块已经不存在了：backend/internal/connector/ 现在是 0 个 Go 文件。 每个 connector 都变成了沙箱 JS block（backend/blocks/{caldav,smtp,google-calendar,telegram}/manifest.yaml + 一个 JS MCP server）；openapi 类型变成通用的 openapi-runtime block，protocol 实现（protocol_smtp.go/protocol_caldav.go）和分类契约（CalendarProxy/MailProxy）都退役了，依赖解析搬到 backend/internal/plugin/effect/registry_deps.go。凭证静态加密 + egress/SSRF 围栏在 block 沙箱边界上保留下来。**"sync-mode 已落地"这句是双重过时：**既没有 connector 模块，vault 同步（SyncVault）也仍是一个 bespoke admin 端点（routes/admin/obsidian.go），从不是一种 connector 种类（roadmap 1e）。下面的"现状"和 mermaid 画的都是 eiab 之前的形状。

flowchart LR
  subgraph SM["StandMeet — our box"]
    CONS["consumer
(capability / feature / im-bridge)"] --> CT["Category Contract
CalendarProxy · MailProxy"]
    CT --> BIND["Binding (JSONata map)
openapi kind"]
    BIND --> RTM["generic OpenAPI runtime
token inject → normalized return"]
    CT --> PROTO["protocol impls
SMTP · CalDAV
(telegram: token vault only, no contract)"]
    CRED[("creds, AES-GCM
never reach the consumer")] --> RTM
    CRED --> PROTO
    DEP["capreg depresolver
Requires:[calendar] — fail-closed"] --- CT
  end
  RTM --> SAAS["external SaaS APIs"]
  PROTO --> SRV["external mail / calendar servers"]

Connector 生命周期（状态）

stateDiagram-v2
  [*] --> Installed : builtin ships / owner uploads
  Installed --> CredsStored : owner enters creds (form derived from securitySchemes)
  CredsStored --> Connected : connect / OAuth dance ok
  Connected --> Active : owner activates (ONE per category slot)
  Active --> Disconnected : disconnect (creds RETAINED)
  Disconnected --> Connected : reconnect
  Active --> Active : consumed via contract handle

由红色测试钉住：每个分类插槽只能有一个活跃 connector；断开连接会保留凭证；agent 工具的暴露是叠加在 Active 之上、按操作单独开启的选项。

子节点

相关笔记