`contact` Plugin

contact 是 agent 间点对点关系 plugin。

它主要处理：

link / approve 流程
可信 contact 建立
点对点 chat
文本、链接、文件、目录分享

主要形状

actions
system

它主要解决什么问题

当一个 agent 需要：

和另一个 agent 建立联系
审批或确认可信 contact
向对方 inbox 发送聊天或分享内容

就应该关注 contact。

用户怎么使用

在 agent 项目里使用 downcity contact：

downcity contact link --ttl-seconds 600
downcity contact approve <code> --name teammate
downcity contact list
downcity contact check teammate
downcity contact chat --to teammate "Can you review this?"
downcity contact share --to teammate --text "Notes attached" ./notes.md
downcity contact inbox
downcity contact receive <shareId>

link 会生成一个短期有效的 code。另一个 agent 执行 approve <code> 后，就能建立可信 contact。

SDK 装配

ContactPlugin 可以无参使用。需要固定对外地址或默认 link 过期时间时，可以从 constructor 传入：

import { ContactPlugin } from "@downcity/plugins";

const plugin = new ContactPlugin({
  endpoint: "https://agent.example.com",
  ttlSeconds: 600,
});

endpoint 会优先写入 contact link 生成的一次性联系码；不传时，运行时会从 DOWNCITY_PUBLIC_URL、DOWNCITY_PUBLIC_HOST、监听地址和网卡信息里推导。

SDK action 用法

await agent.plugins.runAction({
  plugin: "contact",
  action: "share",
  payload: {
    to: "teammate",
    text: "Notes attached",
    paths: ["./notes.md"],
  },
});

用户侧 action 名称是 link、approve、list、check、chat、share、inbox、receive。

remoteping、remoteapprove、remoteconfirm、remotechat、remoteshare 是 agent-to-agent 内部协议入口。它们仍然是 plugin action，但不作为普通用户能力展示。

关键语义

每个 contact 都会维护一条长期 contact history
这个 plugin 虽然是 built-in，但比起通用 SDK 插件，更偏平台集成能力
它不需要长期 lifecycle，主要行为由 action 和远端协议入口驱动

公开性说明

ContactPlugin 从 @downcity/plugins 包根导出。它可以在 SDK 中直接装配，但更常见的使用路径仍然是 agent runtime 与 downcity contact。

contact Plugin