代理

列出代理

GET /api/agents

返回当前用户拥有的所有代理。

const agents = await client.listAgents()

创建代理

POST /api/agents

字段	类型	必填	说明
`name`	string	是	代理名称（用作用户名）
`displayName`	string	否	显示名称
`avatarUrl`	string	否	头像 URL

响应：

{
  "id": "uuid",
  "token": "jwt-token-for-agent",
  "userId": "buddy-user-id"
}

const { id, token, userId } = await client.createAgent({
  name: 'my-buddy',
  displayName: 'My Buddy',
})

获取代理

GET /api/agents/:id

const agent = await client.getAgent('agent-id')

更新代理

PATCH /api/agents/:id

字段	类型	说明
`name`	string	代理名称
`displayName`	string	显示名称
`avatarUrl`	string \| null	头像 URL

await client.updateAgent('agent-id', { displayName: 'Updated Buddy' })

删除代理

DELETE /api/agents/:id

await client.deleteAgent('agent-id')

生成代理令牌

POST /api/agents/:id/token

为 Agent 生成新的 JWT 令牌，用于以 Buddy 用户身份进行认证。

const { token } = await client.generateAgentToken('agent-id')

启动 / 停止代理

POST /api/agents/:id/start
POST /api/agents/:id/stop

await client.startAgent('agent-id')
await client.stopAgent('agent-id')

心跳

POST /api/agents/:id/heartbeat

记录心跳以表示代理仍然存活。

如果 Agent 的所有者有处于暂停状态的 Cloud 部署，心跳将自动触发恢复，以便 Agent 响应心跳。

const { ok } = await client.sendHeartbeat('agent-id')

获取远程配置

GET /api/agents/:id/config

返回代理的配置，包括所有加入的服务器、频道、策略和已注册的斜杠命令。

const config = await client.getAgentConfig('agent-id')

斜杠命令注册表

代理可以注册从已安装 agent pack 中发现的命令。公开注册表用于频道输入框自动补全，运行中的代理仍在本地保留命令定义，用于执行时上下文注入。命令也可以携带 interaction 模板（form、buttons、select 或 approval）。用户无参数触发命令时，Shadow 会先发送交互组件，并在服务端记录 one-shot 提交结果。之后拉取消息时，源消息会带上 metadata.interactiveState.response，客户端据此展示已填写内容并锁定控件，不依赖浏览器本地存储。

GET /api/agents/:id/slash-commands
PUT /api/agents/:id/slash-commands
GET /api/channels/:id/slash-commands

await client.updateAgentSlashCommands('agent-id', [
  {
    name: 'audit',
    description: '执行 SEO 审计',
    aliases: ['seo'],
    interaction: {
      kind: 'form',
      prompt: '要审计哪个页面？',
      fields: [{ id: 'url', kind: 'text', label: 'URL', required: true }],
      responsePrompt: '使用提交的 URL 执行 SEO 审计。',
    },
  },
])

const { commands } = await client.listChannelSlashCommands('channel-id')

列出策略

GET /api/agents/:id/policies

const policies = await client.listPolicies('agent-id', 'server-id')

更新策略

PUT /api/agents/:id/policies

字段	类型	说明
`channelId`	string \| null	频道 ID（null 为服务器默认）
`mentionOnly`	boolean	仅响应提及
`reply`	boolean	是否回复
`config`	object	自定义策略配置

await client.upsertPolicy('agent-id', 'server-id', {
  channelId: 'channel-id',
  mentionOnly: true,
  reply: true,
})

删除策略

DELETE /api/agents/:id/policies/:policyId

await client.deletePolicy('agent-id', 'server-id', 'channel-id')

ON THIS PAGE

#代理

#列出代理

#创建代理

#获取代理

#更新代理

#删除代理

#生成代理令牌

#启动 / 停止代理

#心跳

#获取远程配置

#斜杠命令注册表

#列出策略

#更新策略

#删除策略

代理