@vvfx/artis-agent-sdk

@vvfx/artis-agent-sdk 为第三方创意平台提供版本化的 Canvas 协议，以及 Artis 的受控画布 bridge。Artis Agent 应用自身的 REST、SSE、持久化和 Media Provider 契约不属于这个公开 SDK。

安装与入口

pnpm add @vvfx/artis-agent-sdk @vvfx/artis

浏览器应用默认从根入口导入 bridge 和协议类型：

import { createArtisCanvasBridge, type CanvasCommandProposal } from '@vvfx/artis-agent-sdk'
import { Artis } from '@vvfx/artis'

const artis = new Artis(container)
await artis.run({ items })

const bridge = createArtisCanvasBridge(artis, {
  allowedResourceDomains: ['assets.example.com'],
})

const snapshot = await bridge.getSnapshot()
const validation = await bridge.validate(proposal)
if (validation.status === 'valid') {
  const receipt = await bridge.execute(proposal)
}

bridge.dispose()

不需要加载 Artis runtime 的消费者可从 protocol 子路径导入 Canvas DTO 和 parser：

import {
  parseCanvasSnapshot,
  parseCanvasCommandProposal,
  parseCanvasCommandResult,
  type CanvasContextUpdate,
} from '@vvfx/artis-agent-sdk/protocol'

可用 exports：

| 入口 | 用途 | | --- | --- | | @vvfx/artis-agent-sdk | protocol 与 createArtisCanvasBridge | | @vvfx/artis-agent-sdk/bridge | bridge API | | @vvfx/artis-agent-sdk/protocol | JSON-safe Canvas DTO 与 schema parser |

Bridge 生命周期

CanvasBridge 提供 getSnapshot、subscribe、validate、execute、locate 与 dispose。

• 初始运行和每次用户发送消息前读取强一致 snapshot。
• subscribe 的 document.changed 已经过合并与防抖，selection.changed 不增加文档 revision。
• canvasRevision 是乐观并发栅栏；提议的 baseCanvasRevision 不一致时返回 stale，不会静默覆盖用户修改。
• proposalId 的 receipt 会在 bridge 内有界缓存，SSE 重放不应重复执行同一提议。
• 销毁或替换 Artis 实例前必须调用 dispose() 解绑事件。

命令边界

Agent 执行策略由 SDK 的 CommandAgentMetadata 声明：agentCallable、risk、changesDocument、requiresConfirmation、argsSchema 和 resolveTargetIds。Artis registry 只负责报告命令是否已注册并执行/撤销命令；仅注册命令工厂不会开放 Agent 权限，SDK 只允许同时已注册且由 SDK 策略显式声明的命令。Artis 本身不依赖或存储 Agent metadata。

内建声明通过 getBuiltInAgentCommandMetadata 获取；自定义声明通过 createArtisCanvasBridge 的 agentCommandMetadata option 提供。该策略表归 SDK/调用方所有，不写入 Artis CommandService。能力发现会与 Artis 当前 getRegisteredCommands() 求交集；变更策略表后立即影响能力发现，执行前重新读取 metadata 并校验。注册清单只证明命令工厂存在，不单独授予 Agent 权限。

风险和确认要求由宿主决定，模型不能降低；目标解析器必须返回所有读取/修改目标，包括嵌套字段和外部父子引用。SDK 对解析结果统一执行存在性、锁定与 Effects 只读检查，不按命令前缀推断是否修改文档。根 Skills 仅提供工作流、参数说明和示例，SDK 生产代码不读取 Skills 文件。

Artis 的原子命令计划只接受 2 到 4 条已注册的同步命令，并作为一个可撤销的 History 事务执行；其他 proposal 仍按 maxCommands 和当前 Registry 能力校验。无法证明完整回滚时，bridge 会返回失败回执。

策略层会拒绝未知命令、只读文档编辑、缺失/锁定目标、私网或非 HTTPS 资源、越过 allowlist 的资源 URL，以及试图携带 token/cookie/secret 等敏感参数的 payload。创建元素时，bridge 生成自身拥有的新 element ID。

安全检查

• 在 bridge 与 Agent 接入边界调用 protocol parser；不能信任模型或其他外部 payload。
• 传给 Agent 的 snapshot 应保留资源域名、元素数、文本和属性大小上限。
• 资源 URL 需使用明确 HTTPS allowlist；不接受 file:、data:、私网 IP 或未审查重定向。
• 接入层用 proposalId 做业务去重，用 canvasRevision 管理并发。
• 高风险删除和卡片内容覆盖应在产品 UI 中显示 diff 并要求用户确认。

验证

pnpm --filter @vvfx/artis-agent-sdk check:ts
pnpm --filter @vvfx/artis-agent-sdk test
pnpm --filter @vvfx/artis-agent-sdk build