@downcity/plugins 1.0.4

package/src/contact/types/Contact.ts

@@ -0,0 +1,82 @@
+/**
+ * contact 核心类型。
+ *
+ * 关键点（中文）
+ * - 一个 contact 表示一个已确认的点对点 agent 关系。
+ * - 每个 contact 固定拥有一条长期 chat history，不额外暴露 session 管理概念。
+ */
+
+/**
+ * contact 当前关系状态。
+ */
+export type ContactStatus = "trusted" | "blocked";
+
+/**
+ * contact 当前可达方向。
+ */
+export type ContactReachability = "inbound" | "outbound" | "bidirectional";
+
+/**
+ * agent contact 记录。
+ */
+export interface AgentContact {
+  /**
+   * contact 稳定标识。
+   */
+  id: string;
+  /**
+   * 对方 agent 的展示名称。
+   */
+  name: string;
+  /**
+   * 对方 agent 的 HTTP endpoint；仅 inbound contact 可以为空。
+   */
+  endpoint: string | null;
+  /**
+   * 当前 agent 与对方 agent 的可达方向。
+   */
+  reachability: ContactReachability;
+  /**
+   * 当前关系状态。
+   */
+  status: ContactStatus;
+  /**
+   * 本 agent 调用对方时携带的 token；仅 inbound contact 可以为空。
+   */
+  outboundToken: string | null;
+  /**
+   * 对方调用本 agent 时必须携带的 token hash；仅 outbound contact 可以为空。
+   */
+  inboundTokenHash: string | null;
+  /**
+   * contact 创建时间戳。
+   */
+  createdAt: number;
+  /**
+   * 最近一次成功通信时间戳。
+   */
+  lastSeenAt?: number;
+}
+
+/**
+ * contact chat 消息角色。
+ */
+export type ContactChatMessageRole = "local" | "remote";
+
+/**
+ * contact 长期对话历史中的单条消息。
+ */
+export interface ContactChatMessage {
+  /**
+   * 消息角色。
+   */
+  role: ContactChatMessageRole;
+  /**
+   * 消息正文。
+   */
+  text: string;
+  /**
+   * 消息创建时间戳。
+   */
+  createdAt: number;
+}

package/src/contact/types/ContactApproval.ts

@@ -0,0 +1,150 @@
+/**
+ * contact approve 协议运行时类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 link approve 状态机需要的输入，不包含具体存储实现。
+ * - link approve 是点对点能力码消费流程，token 由协议自动交换。
+ */
+
+import type { ContactApproveLinkRequest } from "./ContactLink.js";
+import type { ContactEndpointReachability } from "./ContactEndpoint.js";
+import type { ContactApproveCallbackReason } from "./ContactLink.js";
+
+/**
+ * approve 方对“是否提供回连候选”的本地推导结果。
+ */
+export interface ContactApproveCallbackDecision {
+  /**
+   * approve 方是否应该把自己的 endpoint/token 作为回连候选发给发起方做 confirm。
+   */
+  callbackOffered: boolean;
+  /**
+   * 本次推导的原因。
+   */
+  reason: ContactApproveCallbackReason;
+  /**
+   * approve 方自己的 endpoint；仅当推导过程解析出了 endpoint 时存在。
+   */
+  endpoint?: string;
+  /**
+   * approve 方 endpoint 的粗粒度可达范围。
+   */
+  requesterReachability: ContactEndpointReachability;
+  /**
+   * link code 中目标 endpoint 的粗粒度可达范围。
+   */
+  targetReachability: ContactEndpointReachability;
+}
+
+/**
+ * 处理远端 contact link approve 请求的输入。
+ */
+export interface ApproveContactLinkRequestInput {
+  /**
+   * 当前 agent 项目根目录，用于读取 link 记录并保存 contact。
+   */
+  projectRoot: string;
+  /**
+   * 当前 agent 名称，也就是 link 所属方名称。
+   */
+  ownerAgentName: string;
+  /**
+   * 当前 agent 对外 endpoint；当 link 记录不存在时仍会返回该值辅助诊断。
+   */
+  ownerEndpoint: string;
+  /**
+   * approve 方发来的 link id、secret、agent 名称和可选回连信息。
+   */
+  request: ContactApproveLinkRequest;
+  /**
+   * 当前时间戳；测试可注入，生产环境默认使用 Date.now()。
+   */
+  nowMs?: number;
+}
+
+/**
+ * 远端 contact confirm 请求。
+ */
+export interface ContactConfirmRequest {
+  /**
+   * 被 confirm 的 link id。
+   */
+  linkId: string;
+  /**
+   * link code 中的一次性明文 secret，用于确认请求来自同一个 approve 方。
+   */
+  secret: string;
+  /**
+   * approve 方 agent 名称。
+   */
+  agentName: string;
+  /**
+   * approve 方提供给发起方主动检查的 endpoint。
+   */
+  endpoint: string;
+  /**
+   * 发起方主动调用 approve 方时携带的 token。
+   */
+  tokenForRequester: string;
+}
+
+/**
+ * 远端 contact confirm 响应。
+ */
+export interface ContactConfirmResponse {
+  /**
+   * confirm 请求是否执行成功。
+   */
+  success: boolean;
+  /**
+   * 发起方 agent 名称。
+   */
+  agentName: string;
+  /**
+   * 发起方是否已确认可以主动回连 approve 方。
+   */
+  confirmed: boolean;
+  /**
+   * confirm 后发起方保存的 contact 方向。
+   */
+  reachability: "inbound" | "bidirectional";
+  /**
+   * confirm 失败原因。
+   */
+  error?: string;
+}
+
+/**
+ * 处理远端 contact confirm 请求的输入。
+ */
+export interface ConfirmContactLinkRequestInput {
+  /**
+   * 当前 agent 项目根目录，用于读取 link 记录并更新 contact。
+   */
+  projectRoot: string;
+  /**
+   * 当前 agent 名称，也就是 link 所属方名称。
+   */
+  ownerAgentName: string;
+  /**
+   * confirm 方发来的 link id、secret、agent 名称和回连 token。
+   */
+  request: ContactConfirmRequest;
+  /**
+   * 发起方主动 ping approve 方的验证函数；只有验证成功才能升级为 bidirectional。
+   */
+  verifyCallback: (params: {
+    /**
+     * approve 方提供的回连 endpoint。
+     */
+    endpoint: string;
+    /**
+     * 发起方调用 approve 方时携带的 token。
+     */
+    token: string;
+  }) => Promise<boolean>;
+  /**
+   * 当前时间戳；测试可注入，生产环境默认使用 Date.now()。
+   */
+  nowMs?: number;
+}

package/src/contact/types/ContactChat.ts

@@ -0,0 +1,47 @@
+/**
+ * contact chat 类型。
+ *
+ * 关键点（中文）
+ * - 一个 contact 固定一条长期 chat history。
+ * - 用户不需要主动维护 session id。
+ */
+
+/**
+ * contact chat 远端消息请求。
+ */
+export interface ContactRemoteChatRequest {
+  /**
+   * 发送方 contact id。
+   */
+  senderContactId: string;
+  /**
+   * 消息正文。
+   */
+  message: string;
+  /**
+   * 消息创建时间戳。
+   */
+  createdAt: number;
+}
+
+/**
+ * contact chat 响应。
+ */
+export interface ContactChatResponse {
+  /**
+   * chat 是否成功。
+   */
+  success: boolean;
+  /**
+   * 对方回复文本。
+   */
+  reply: string;
+  /**
+   * 本地 contact id。
+   */
+  contactId: string;
+  /**
+   * 失败原因。
+   */
+  error?: string;
+}

package/src/contact/types/ContactCheck.ts

@@ -0,0 +1,67 @@
+/**
+ * contact check 类型。
+ *
+ * 关键点（中文）
+ * - check 只检测对方 agent 当前是否在线可用。
+ * - check 不创建关系，也不写入 inbox。
+ */
+
+/**
+ * contact ping 响应。
+ */
+export interface ContactPingResponse {
+  /**
+   * ping 是否成功。
+   */
+  success: boolean;
+  /**
+   * 对方 agent 名称。
+   */
+  agentName: string;
+  /**
+   * 对方 contact plugin 是否可用。
+   */
+  plugin: "contact";
+  /**
+   * token 校验是否通过。
+   */
+  authenticated?: boolean;
+  /**
+   * 失败原因。
+   */
+  error?: string;
+}
+
+/**
+ * contact check 结果。
+ */
+export interface ContactCheckResult {
+  /**
+   * 检测目标名称或 endpoint。
+   */
+  target: string;
+  /**
+   * 目标 endpoint。
+   */
+  endpoint: string;
+  /**
+   * 目标是否可访问。
+   */
+  reachable: boolean;
+  /**
+   * contact token 是否有效。
+   */
+  authenticated?: boolean;
+  /**
+   * 往返耗时。
+   */
+  latencyMs: number;
+  /**
+   * 对方 agent 名称。
+   */
+  agentName?: string;
+  /**
+   * 失败原因。
+   */
+  error?: string;
+}

package/src/contact/types/ContactCommand.ts

@@ -0,0 +1,98 @@
+/**
+ * contact plugin command 类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 action payload/response，不承载运行时存储逻辑。
+ */
+
+/**
+ * contact link command 输入。
+ */
+export interface ContactLinkCommandPayload {
+  /**
+   * 内部解析出的本 agent 对外可访问 endpoint；CLI 不暴露该字段。
+   */
+  endpoint?: string;
+  /**
+   * link 过期秒数。
+   */
+  ttlSeconds?: number;
+}
+
+/**
+ * contact approve command 输入。
+ */
+export interface ContactApproveCommandPayload {
+  /**
+   * 人工转交的 link code。
+   */
+  code: string;
+  /**
+   * 本地保存 contact 时使用的别名。
+   */
+  name?: string;
+  /**
+   * 内部解析出的本 agent 对外可访问 endpoint；CLI 不暴露该字段，省略时 approve 方只建立主动访问对方的单向 contact。
+   */
+  endpoint?: string;
+}
+
+/**
+ * contact check command 输入。
+ */
+export interface ContactCheckCommandPayload {
+  /**
+   * 已保存 contact 名称。
+   */
+  target?: string;
+  /**
+   * 未保存 agent endpoint。
+   */
+  endpoint?: string;
+}
+
+/**
+ * contact chat command 输入。
+ */
+export interface ContactChatCommandPayload {
+  /**
+   * 已保存 contact 名称。
+   */
+  to: string;
+  /**
+   * 本轮消息正文。
+   */
+  message?: string;
+}
+
+/**
+ * contact share command 输入。
+ */
+export interface ContactShareCommandPayload {
+  /**
+   * 已保存 contact 名称。
+   */
+  to: string;
+  /**
+   * 分享的文本内容。
+   */
+  text?: string;
+  /**
+   * 分享的链接列表。
+   */
+  links?: string[];
+  /**
+   * 分享的文件或目录路径列表。
+   */
+  paths?: string[];
+}
+
+/**
+ * contact receive command 输入。
+ */
+export interface ContactReceiveCommandPayload {
+  /**
+   * inbox share id。
+   */
+  shareId: string;
+}

package/src/contact/types/ContactEndpoint.ts

@@ -0,0 +1,16 @@
+/**
+ * contact endpoint 提示类型。
+ *
+ * 关键点（中文）
+ * - endpoint 可达性只用于给 agent / 用户解释当前联系码适合谁使用。
+ * - 它不参与鉴权，鉴权仍由 link secret 与 contact token 完成。
+ */
+
+/**
+ * contact endpoint 的粗粒度可达范围。
+ */
+export type ContactEndpointReachability =
+  | "loopback"
+  | "private"
+  | "public"
+  | "unknown";

package/src/contact/types/ContactLink.ts

@@ -0,0 +1,169 @@
+/**
+ * contact link 类型。
+ *
+ * 关键点（中文）
+ * - link code 是人工转交的一次性点对点建联凭证。
+ * - approve 成功后 link 立即失效。
+ */
+
+/**
+ * link code 内部载荷。
+ */
+export interface ContactLinkCodePayload {
+  /**
+   * link code 协议版本。
+   */
+  version: 1;
+  /**
+   * link 稳定标识。
+   */
+  linkId: string;
+  /**
+   * 发起方 agent 名称。
+   */
+  agentName: string;
+  /**
+   * 发起方 HTTP endpoint。
+   */
+  endpoint: string;
+  /**
+   * 一次性明文 secret。
+   */
+  secret: string;
+  /**
+   * link 创建时间戳。
+   */
+  createdAt: number;
+  /**
+   * link 过期时间戳。
+   */
+  expiresAt: number;
+}
+
+/**
+ * 本地保存的 link 记录。
+ */
+export interface ContactLinkRecord {
+  /**
+   * link 稳定标识。
+   */
+  id: string;
+  /**
+   * 发起方 agent 名称。
+   */
+  agentName: string;
+  /**
+   * 发起方 HTTP endpoint。
+   */
+  endpoint: string;
+  /**
+   * 一次性 secret hash。
+   */
+  secretHash: string;
+  /**
+   * link 创建时间戳。
+   */
+  createdAt: number;
+  /**
+   * link 过期时间戳。
+   */
+  expiresAt: number;
+  /**
+   * link 被使用的时间戳。
+   */
+  usedAt?: number | null;
+  /**
+   * 已使用该 link 的 approve 方 agent 名称；用于同一 agent 在网络中断或本地保存失败后做幂等重试。
+   */
+  approvedAgentName?: string | null;
+  /**
+   * approve 方在建联时提供的 HTTP endpoint；没有公开 endpoint 时为空。
+   */
+  approvedEndpoint?: string | null;
+  /**
+   * 发起方发给 approve 方的明文 contact token；只保存在本地 link 记录中，用于同一 link 在有效期内重试恢复。
+   */
+  tokenForOwner?: string | null;
+  /**
+   * approve 方发给发起方的明文 contact token；仅作为 confirm 阶段的本地恢复元数据。
+   */
+  tokenForRequester?: string | null;
+  /**
+   * approve 方推导回连候选的原因；用于 confirm 失败后的诊断。
+   */
+  callbackReason?: ContactApproveCallbackReason | null;
+  /**
+   * 发起方成功 confirm 并升级为 bidirectional 的时间戳。
+   */
+  confirmedAt?: number | null;
+}
+
+/**
+ * approve 方声明自己可被回连的推导原因。
+ */
+export type ContactApproveCallbackReason =
+  | "missing-requester-endpoint"
+  | "requester-public"
+  | "same-loopback-host"
+  | "same-private-network"
+  | "requester-not-routable-from-target";
+
+/**
+ * 远端 approve link 请求。
+ */
+export interface ContactApproveLinkRequest {
+  /**
+   * link 稳定标识。
+   */
+  linkId: string;
+  /**
+   * 一次性明文 secret。
+   */
+  secret: string;
+  /**
+   * approve 方 agent 名称。
+   */
+  agentName: string;
+  /**
+   * approve 方 HTTP endpoint；缺省时只建立发起方可接收请求的单向 contact。
+   */
+  endpoint?: string;
+  /**
+   * 发起方后续调用 approve 方时使用的 token；只有 approve 方提供 endpoint 时才需要。
+   */
+  tokenForRequester?: string;
+  /**
+   * approve 方是否提供了一个回连候选；这不是双向确认结果，发起方必须再执行 confirm 主动检查。
+   */
+  callbackOffered?: boolean;
+  /**
+   * approve 方推导 `callbackOffered` 的原因，方便接收方和用户诊断网络关系。
+   */
+  callbackReason?: ContactApproveCallbackReason;
+}
+
+/**
+ * 远端 approve link 响应。
+ */
+export interface ContactApproveLinkResponse {
+  /**
+   * approve 是否成功。
+   */
+  success: boolean;
+  /**
+   * 发起方 agent 名称。
+   */
+  agentName: string;
+  /**
+   * 发起方 HTTP endpoint。
+   */
+  endpoint: string;
+  /**
+   * approve 方后续调用发起方时使用的 token。
+   */
+  tokenForOwner: string;
+  /**
+   * 失败原因。
+   */
+  error?: string;
+}