@downcity/plugins 1.0.52 → 1.0.57

package/src/asr/types/AsrPlugin.ts

@@ -0,0 +1,118 @@
+/**
+ * AsrPlugin 类型定义。
+ *
+ * 关键点（中文）
+ * - ASR plugin 只定义 agent 侧协议，不绑定本地模型、Python 或 City 具体实现。
+ * - 真实转写能力通过 constructor 的 `asr` 函数注入，推荐传入 `city.ai.asr`。
+ * - `auto` 只表示是否在 chat 入站时自动转写语音附件。
+ */
+
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+
+/**
+ * ASR 输入。
+ */
+export interface AsrPluginInput {
+  /**
+   * 本地音频文件路径。
+   *
+   * 说明（中文）
+   * - chat runtime 下载附件后会传入本地路径。
+   * - 显式 action 调用时也优先使用该字段。
+   */
+  audio_path?: string;
+  /**
+   * 远程音频 URL。
+   */
+  url?: string;
+  /**
+   * data URL 音频内容。
+   */
+  data_url?: string;
+  /**
+   * 语言提示，例如 `auto`、`zh`、`en`。
+   */
+  language?: string;
+  /**
+   * 音频 MIME 类型，例如 `audio/ogg`。
+   */
+  media_type?: string;
+  /**
+   * 原始文件名。
+   */
+  file_name?: string;
+  /**
+   * Provider 私有参数。
+   */
+  provider_options?: JsonObject;
+  /**
+   * 允许外部 asr 函数接收其他 JSON 可序列化参数。
+   */
+  [key: string]: JsonValue | undefined;
+}
+
+/**
+ * ASR 输出。
+ */
+export interface AsrPluginResult {
+  /**
+   * 转写文本。
+   */
+  text: string;
+  /**
+   * 识别到的语言（可选）。
+   */
+  language?: string;
+  /**
+   * 结果置信度（可选）。
+   */
+  confidence?: number;
+  /**
+   * Provider 原始元信息（可选）。
+   */
+  metadata?: JsonObject;
+  /**
+   * 允许外部 asr 函数返回其他 JSON 可序列化字段。
+   */
+  [key: string]: JsonValue | undefined;
+}
+
+/**
+ * AsrPlugin 构造参数。
+ */
+export interface AsrPluginOptions {
+  /**
+   * Plugin 稳定名称，默认 `asr`。
+   */
+  name?: string;
+  /**
+   * Plugin 展示标题，默认 `ASR`。
+   */
+  title?: string;
+  /**
+   * Plugin 用途说明。
+   */
+  description?: string;
+  /**
+   * 真实 ASR 能力函数。
+   *
+   * 说明（中文）
+   * - 推荐传入 `(input) => city.ai.asr(input)`。
+   * - plugin 只负责调用该函数，不关心模型、provider、鉴权或运行依赖。
+   */
+  asr: (input: AsrPluginInput) => Promise<AsrPluginResult> | AsrPluginResult;
+  /**
+   * 是否自动转写 chat 入站语音附件。
+   *
+   * 说明（中文）
+   * - `true`：遇到 voice/audio 附件时自动调用 `asr`。
+   * - `false`：仅保留显式 `transcribe` action。
+   * - 默认 `false`，避免 agent 隐式调用外部 ASR 成本。
+   */
+  auto?: boolean;
+  /**
+   * 默认语言提示。
+   */
+  language?: string;
+}
+

package/src/auth/Plugin.ts

@@ -7,7 +7,6 @@
  * - 它只负责聊天主体授权，不负责 Town HTTP Bearer token 或路由访问鉴权。
  */
 
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
@@ -231,8 +230,8 @@ function createChatAuthorizationPluginDefinition(): Plugin {
 export class ChatAuthorizationPlugin extends BasePlugin {
   readonly name = CHAT_AUTHORIZATION_PLUGIN_NAME;
 
-  constructor(agent: AgentRuntime | null = null) {
-    super(agent);
+  constructor() {
+    super();
     Object.assign(this, createChatAuthorizationPluginDefinition());
   }
 }

package/src/chat/ChatPlugin.ts

@@ -8,7 +8,6 @@
  * - action 注册表已经拆到独立模块，当前文件只保留实例骨架。
  */
 
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
@@ -107,11 +106,9 @@ export class ChatPlugin extends BasePlugin {
     worker.stop();
   }
 
-  constructor(optionsOrAgent?: ChatPluginOptions | AgentRuntime | null) {
-    super(isAgentRuntimeInput(optionsOrAgent) ? optionsOrAgent : null);
-    this.options = isAgentRuntimeInput(optionsOrAgent)
-      ? {}
-      : (optionsOrAgent || {});
+  constructor(options?: ChatPluginOptions) {
+    super();
+    this.options = options || {};
     this.actions = createChatPluginActions({
       channelState: this.channelState,
     });
@@ -239,11 +236,3 @@ export class ChatPlugin extends BasePlugin {
     };
   }
 }
-
-function isAgentRuntimeInput(
-  input: ChatPluginOptions | AgentRuntime | null | undefined,
-): input is AgentRuntime | null {
-  if (input === null) return true;
-  if (!input || typeof input !== "object") return false;
-  return typeof (input as AgentRuntime).getSession === "function";
-}

package/src/chat/PROMPT.direct.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/chat/PROMPT.direct.ts.txt
-const TEXT_MODULE_CONTENT = "# Chat Plugin 使用说明\n\n## 用户可见回复规则\n\n- 当前模式下，直接输出，即会发送消息给到用户对应的channel\n\n## 输出协议\n\n- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 `town chat send` 保持一致：\n\n- `delay` / `delayMs`：延迟发送毫秒数。\n- `time` / `sendAt` / `sendAtMs`：定时发送时间。\n- `reply`：是否使用 reply 语义发送。\n- `messageId`：目标 `message_id`（群聊推荐）。\n- `react`：发送表情反应。\n  - 单个字符串：`react: \"👍\"`\n  - 或对象/数组：`emoji/big`\n  - 设置 `messageId` 时，`react` 会优先复用该消息作为目标消息。\n- 附件使用 `<file type=\"...\">path</file>`（支持 `document/photo/voice/audio/video`）。\n- 附件路径必须是项目内可访问的相对路径。多附件可输出多个 `<file>` 标签。\n\n### 示例\n\n```text\n---\nreply: true\nmessageId: \"128\"\nreact:\n  - emoji: \"✅\"\n---\n这是今天的报告。\n<file type=\"document\">reports/daily.md</file>\n```\n\n### 协议约束\n\n- frontmatter 必须位于文本最开头（`---` 包裹）。\n- 除 `<file>` 附件标签外，不要使用尖括号格式做控制参数。\n\n## 跨协议/跨平台操作\n\n- 当任务需要跨会话、跨平台或复杂路由，必须使用 `town chat send` / `town chat react`。\n- metadata 只适用于当前会话内的 direct 出站，不要拿 metadata 做跨 chat 路由。\n- 如果需要跨 chat 发送，或者不清楚怎么发送，直接先调用 `town chat --help` 查看方法。\n- 如不确定参数或正文协议，先自行调用：\n  - `town chat --help`\n  - `town chat send --help`\n  - `town chat react --help`\n\n## 入站消息结构（仅供内部理解）\n\n- 每条入队用户消息包含 `<info>...</info>` 元信息块 + 用户正文。\n- `<info>` 仅保留 user/request 元信息，例如 `user_id`、`username`、`message_id`、`permissions`、`received_at`。\n- 当前 chat 路由环境（例如 `channel`、`session_id`、`chat_key`、`chat_id`）会通过 system prompt 单独注入，不再混在 `<info>` 里。\n- `<info>` 不要原样回传给用户。\n";
+const TEXT_MODULE_CONTENT = "# Chat Plugin 使用说明\n\n## 用户可见回复规则\n\n- 当前模式下，直接输出，即会发送消息给到用户对应的channel\n\n## 输出协议\n\n- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 chat plugin 的 direct send 协议保持一致：\n\n- `delay` / `delayMs`：延迟发送毫秒数。\n- `time` / `sendAt` / `sendAtMs`：定时发送时间。\n- `reply`：是否使用 reply 语义发送。\n- `messageId`：目标 `message_id`（群聊推荐）。\n- `react`：发送表情反应。\n  - 单个字符串：`react: \"👍\"`\n  - 或对象/数组：`emoji/big`\n  - 设置 `messageId` 时，`react` 会优先复用该消息作为目标消息。\n- 附件使用 `<file type=\"...\">path</file>`（支持 `document/photo/voice/audio/video`）。\n- 附件路径必须是项目内可访问的相对路径。多附件可输出多个 `<file>` 标签。\n\n### 示例\n\n```text\n---\nreply: true\nmessageId: \"128\"\nreact:\n  - emoji: \"✅\"\n---\n这是今天的报告。\n<file type=\"document\">reports/daily.md</file>\n```\n\n### 协议约束\n\n- frontmatter 必须位于文本最开头（`---` 包裹）。\n- 除 `<file>` 附件标签外，不要使用尖括号格式做控制参数。\n\n## 跨协议/跨平台操作\n\n- 当前会话内回复优先直接输出文本，系统会自动发送到当前 channel。\n- 当任务需要跨会话、跨平台或复杂路由，使用 chat plugin action。\n- 如果当前工具集中存在 `plugin_call`，可通过 `plugin_call({ plugin: \"chat\", action: \"send\", payload })` 或 `plugin_call({ plugin: \"chat\", action: \"react\", payload })` 触发。\n- metadata 只适用于当前会话内的 direct 出站，不要拿 metadata 做跨 chat 路由。\n- 如果不清楚跨 chat 路由参数，应先读取当前 chat context 或调用 chat plugin 的查询类 action，而不是猜测。\n\n## 入站消息结构（仅供内部理解）\n\n- 每条入队用户消息包含 `<info>...</info>` 元信息块 + 用户正文。\n- `<info>` 仅保留 user/request 元信息，例如 `user_id`、`username`、`message_id`、`permissions`、`received_at`。\n- 当前 chat 路由环境（例如 `channel`、`session_id`、`chat_key`、`chat_id`）会通过 system prompt 单独注入，不再混在 `<info>` 里。\n- `<info>` 不要原样回传给用户。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/chat/PROMPT.direct.ts.txt

@@ -6,7 +6,7 @@
 
 ## 输出协议
 
-- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 `town chat send` 保持一致：
+- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 chat plugin 的 direct send 协议保持一致：
 
 - `delay` / `delayMs`：延迟发送毫秒数。
 - `time` / `sendAt` / `sendAtMs`：定时发送时间。
@@ -39,13 +39,11 @@ react:
 
 ## 跨协议/跨平台操作
 
-- 当任务需要跨会话、跨平台或复杂路由，必须使用 `town chat send` / `town chat react`。
+- 当前会话内回复优先直接输出文本，系统会自动发送到当前 channel。
+- 当任务需要跨会话、跨平台或复杂路由，使用 chat plugin action。
+- 如果当前工具集中存在 `plugin_call`，可通过 `plugin_call({ plugin: "chat", action: "send", payload })` 或 `plugin_call({ plugin: "chat", action: "react", payload })` 触发。
 - metadata 只适用于当前会话内的 direct 出站，不要拿 metadata 做跨 chat 路由。
-- 如果需要跨 chat 发送，或者不清楚怎么发送，直接先调用 `town chat --help` 查看方法。
-- 如不确定参数或正文协议，先自行调用：
-  - `town chat --help`
-  - `town chat send --help`
-  - `town chat react --help`
+- 如果不清楚跨 chat 路由参数，应先读取当前 chat context 或调用 chat plugin 的查询类 action，而不是猜测。
 
 ## 入站消息结构（仅供内部理解）
 

package/src/chat/channels/qq/PROMPT.direct.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/chat/channels/qq/PROMPT.direct.ts.txt
-const TEXT_MODULE_CONTENT = "# QQ Adapter 使用说明（direct 模式）\n\n## 能力范围\n- 负责 QQ 官方机器人网关（WebSocket）消息接入与发送。\n- 入站消息会由 chat plugin runtime 映射到内部 `sessionId`（随机分配并持久化）。\n\n## 使用约束\n- 在 direct 模式下，你输出的 assistant 文本会自动发送到当前 QQ 会话。\n- QQ 出站回复依赖入站消息上下文（如 `chatType` 与 `messageId`）；跨会话发送请使用 `town chat send --chat-key ...`，不要在 direct metadata 中写 `chatKey`。\n- 群聊消息默认全量接入，不需要 `@` 触发。\n- 适配器会过滤机器人自回环消息并做入站去重，避免“自己回复自己”的循环。\n";
+const TEXT_MODULE_CONTENT = "# QQ Adapter 使用说明（direct 模式）\n\n## 能力范围\n- 负责 QQ 官方机器人网关（WebSocket）消息接入与发送。\n- 入站消息会由 chat plugin runtime 映射到内部 `sessionId`（随机分配并持久化）。\n\n## 使用约束\n- 在 direct 模式下，你输出的 assistant 文本会自动发送到当前 QQ 会话。\n- QQ 出站回复依赖入站消息上下文（如 `chatType` 与 `messageId`）；跨会话发送请使用 chat plugin action，不要在 direct metadata 中写 `chatKey`。\n- 群聊消息默认全量接入，不需要 `@` 触发。\n- 适配器会过滤机器人自回环消息并做入站去重，避免“自己回复自己”的循环。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/chat/channels/qq/PROMPT.direct.ts.txt

@@ -6,6 +6,6 @@
 
 ## 使用约束
 - 在 direct 模式下，你输出的 assistant 文本会自动发送到当前 QQ 会话。
-- QQ 出站回复依赖入站消息上下文（如 `chatType` 与 `messageId`）；跨会话发送请使用 `town chat send --chat-key ...`，不要在 direct metadata 中写 `chatKey`。
+- QQ 出站回复依赖入站消息上下文（如 `chatType` 与 `messageId`）；跨会话发送请使用 chat plugin action，不要在 direct metadata 中写 `chatKey`。
 - 群聊消息默认全量接入，不需要 `@` 触发。
 - 适配器会过滤机器人自回环消息并做入站去重，避免“自己回复自己”的循环。

package/src/chat/channels/telegram/Bot.ts

@@ -47,6 +47,8 @@ export class TelegramBot extends BaseChatChannel {
 
   private readonly botToken: string;
   private readonly platform: TelegramPlatformClient;
+  private startTask: Promise<void> | null = null;
+  private startupGeneration = 0;
 
   constructor(context: AgentContext, botToken: string) {
     super({ channel: "telegram", context });
@@ -143,17 +145,36 @@ export class TelegramBot extends BaseChatChannel {
       this.logger.warn("Telegram Bot Token not configured, skipping startup");
       return;
     }
+    if (this.startTask) return;
 
     this.logger.info("🤖 Starting Telegram Bot...");
+    this.platform.markStartupStarted();
+    const startupGeneration = ++this.startupGeneration;
+    // 关键点（中文）：Telegram 网络初始化不能阻塞 Agent RPC/gateway ready。
+    this.startTask = this.startInBackground(startupGeneration);
+  }
+
+  /**
+   * 后台启动 Telegram polling。
+   */
+  private async startInBackground(startupGeneration: number): Promise<void> {
     try {
       await this.platform.preparePolling();
       await this.drainPendingUpdatesToHistory({ reason: "startup" });
+      if (startupGeneration !== this.startupGeneration) {
+        return;
+      }
       this.platform.startPollingLoop();
+      this.platform.markStartupSucceeded();
     } catch (error) {
+      if (startupGeneration !== this.startupGeneration) return;
+      this.platform.markStartupFailed(error);
       this.logger.error("Failed to start Telegram Bot", {
         error: String(error),
       });
       await this.platform.stop();
+    } finally {
+      this.startTask = null;
     }
   }
 
@@ -342,6 +363,7 @@ export class TelegramBot extends BaseChatChannel {
    * 停止 Telegram bot。
    */
   async stop(): Promise<void> {
+    this.startupGeneration += 1;
     await this.platform.stop();
   }
 }

package/src/chat/channels/telegram/TelegramPlatformClient.ts

@@ -66,6 +66,8 @@ export class TelegramPlatformClient {
   private botUsername?: string;
   private botId?: number;
   private clearedWebhookOnce = false;
+  private isStarting = false;
+  private lastStartupError: string | null = null;
 
   constructor(options: TelegramPlatformClientOptions) {
     this.logger = options.context.logger;
@@ -97,26 +99,58 @@ export class TelegramPlatformClient {
         : running
           ? "unknown"
           : "disconnected";
-    return {
-      running,
-      linkState,
-      statusText:
-        linkState === "connected"
+    const statusText = this.lastStartupError
+      ? "start_failed"
+      : this.isStarting
+        ? "starting"
+        : linkState === "connected"
           ? "polling"
           : linkState === "unknown"
             ? "starting"
-            : "stopped",
+            : "stopped";
+    return {
+      running,
+      linkState,
+      statusText,
       detail: {
+        isStarting: this.isStarting,
         pollInFlight: this.pollInFlight,
         lastUpdateId: this.lastUpdateId,
         consecutivePollErrors: this.consecutivePollErrors,
         nextPollAllowedAt: this.nextPollAllowedAt || null,
         botUsername: this.botUsername || null,
         botId: typeof this.botId === "number" ? this.botId : null,
+        lastStartupError: this.lastStartupError,
       },
     };
   }
 
+  /**
+   * 标记 Telegram 后台启动开始。
+   */
+  markStartupStarted(): void {
+    this.isStarting = true;
+    this.isRunning = true;
+    this.lastStartupError = null;
+  }
+
+  /**
+   * 标记 Telegram 后台启动完成。
+   */
+  markStartupSucceeded(): void {
+    this.isStarting = false;
+    this.lastStartupError = null;
+  }
+
+  /**
+   * 标记 Telegram 后台启动失败。
+   */
+  markStartupFailed(error: unknown): void {
+    this.isStarting = false;
+    this.isRunning = false;
+    this.lastStartupError = String(error);
+  }
+
   /**
    * 获取 bot 用户名。
    */
@@ -340,9 +374,11 @@ export class TelegramPlatformClient {
    * 停止平台运行时。
    */
   async stop(): Promise<void> {
+    this.isStarting = false;
     this.isRunning = false;
     if (this.pollingInterval) {
       clearInterval(this.pollingInterval);
+      this.pollingInterval = null;
     }
     this.consecutivePollErrors = 0;
     this.nextPollAllowedAt = 0;

package/src/contact/ContactPlugin.ts

@@ -7,7 +7,6 @@
  * - `share` 分享文本、链接、文件和目录，并进入对方 inbox。
  */
 
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
@@ -146,8 +145,8 @@ export class ContactPlugin extends BasePlugin {
    */
   readonly actions: PluginActions;
 
-  constructor(agent: AgentRuntime | null) {
-    super(agent);
+  constructor() {
+    super();
     this.actions = createContactActions({
       link: async (context, payload) =>
         (await this.link(context, payload)) as unknown as JsonValue,

package/src/contact/PROMPT.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/contact/PROMPT.ts.txt
-const TEXT_MODULE_CONTENT = "Contact plugin\n\ncontact plugin 用来管理和其他 agent 的联系方式。一个 contact 代表一个已建立联系的远端 agent，并固定拥有一条长期对话历史。contact 可以是单向的：只要本 agent 能访问对方，就可以 check、chat、share。\n\n可用命令：\n- `town contact link`：生成一次性联系码，交给另一个 agent。\n- `town contact approve <code>`：使用对方给的联系码建立 contact。\n- `town contact list`：查看已保存的 agent 联系方式。\n- `town contact check <contact>` / `town contact check --to <ip:port>`：检查对方是否在线可用。\n- `town contact chat --to <contact> \"<message>\"`：和某个 agent 对话。\n- `town contact share --to <contact> --text ... | --link ... | <path...>`：分享文本、链接、文件或目录。\n- `town contact inbox`：查看收到的分享。\n- `town contact receive <share_id>`：接收某条分享。\n\n边界：\n- chat 用于对话，share 用于资料交接。\n- `town contact link` 返回中的 notes 会说明联系码适合本机、局域网还是公网 agent 使用；本地 localhost 联系码不能交给 server agent approve。\n- public-looking endpoint 仍可能被防火墙/NAT 阻断；以返回的 notes 为准，不要承诺公网一定可达。\n- `town start` 会自动写入 `DOWNCITY_PUBLIC_HOST` 供 contact link 使用；这不是要求用户手动配置的 token 或 endpoint。\n- `town contact approve` 会先建立单向关系，再由对方主动 ping 回本 agent，ping 成功才升级为 bidirectional。\n- local/private agent 连接 public agent 时通常只能 outbound-only，不要说成双向。\n- contact token 由 link/approve 自动交换；不要要求用户手动配置 token 环境变量。\n- `Contact link not found` 表示请求打到的 agent runtime 没有这条 link 记录，优先检查 endpoint/端口/agent 是否一致；过期会明确返回 `Contact link expired`。\n- receive 只接收内容，不自动执行、不安装 skill、不修改项目业务文件。\n- 不自动 approve 或 receive，除非用户明确要求。\n";
+const TEXT_MODULE_CONTENT = "Contact plugin\n\ncontact plugin 用来管理和其他 agent 的联系方式。一个 contact 代表一个已建立联系的远端 agent，并固定拥有一条长期对话历史。contact 可以是单向的：只要本 agent 能访问对方，就可以 check、chat、share。\n\n可用 action：\n- `link`：生成一次性联系码，交给另一个 agent。\n- `approve`：使用对方给的联系码建立 contact。\n- `list`：查看已保存的 agent 联系方式。\n- `check`：检查对方是否在线可用。\n- `chat`：和某个 agent 对话。\n- `share`：分享文本、链接、文件或目录。\n- `inbox`：查看收到的分享。\n- `receive`：接收某条分享。\n\n边界：\n- chat 用于对话，share 用于资料交接。\n- `link` action 返回中的 notes 会说明联系码适合本机、局域网还是公网 agent 使用；本地 localhost 联系码不能交给 server agent approve。\n- public-looking endpoint 仍可能被防火墙/NAT 阻断；以返回的 notes 为准，不要承诺公网一定可达。\n- Agent runtime 会在可用时写入 `DOWNCITY_PUBLIC_HOST` 供 contact link 使用；这不是要求用户手动配置的 token 或 endpoint。\n- `approve` action 会先建立单向关系，再由对方主动 ping 回本 agent，ping 成功才升级为 bidirectional。\n- local/private agent 连接 public agent 时通常只能 outbound-only，不要说成双向。\n- contact token 由 link/approve 自动交换；不要要求用户手动配置 token 环境变量。\n- `Contact link not found` 表示请求打到的 agent runtime 没有这条 link 记录，优先检查 endpoint/端口/agent 是否一致；过期会明确返回 `Contact link expired`。\n- receive 只接收内容，不自动执行、不安装 skill、不修改项目业务文件。\n- 不自动 approve 或 receive，除非用户明确要求。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/contact/PROMPT.ts.txt

@@ -2,22 +2,22 @@ Contact plugin
 
 contact plugin 用来管理和其他 agent 的联系方式。一个 contact 代表一个已建立联系的远端 agent，并固定拥有一条长期对话历史。contact 可以是单向的：只要本 agent 能访问对方，就可以 check、chat、share。
 
-可用命令：
-- `town contact link`：生成一次性联系码，交给另一个 agent。
-- `town contact approve <code>`：使用对方给的联系码建立 contact。
-- `town contact list`：查看已保存的 agent 联系方式。
-- `town contact check <contact>` / `town contact check --to <ip:port>`：检查对方是否在线可用。
-- `town contact chat --to <contact> "<message>"`：和某个 agent 对话。
-- `town contact share --to <contact> --text ... | --link ... | <path...>`：分享文本、链接、文件或目录。
-- `town contact inbox`：查看收到的分享。
-- `town contact receive <share_id>`：接收某条分享。
+可用 action：
+- `link`：生成一次性联系码，交给另一个 agent。
+- `approve`：使用对方给的联系码建立 contact。
+- `list`：查看已保存的 agent 联系方式。
+- `check`：检查对方是否在线可用。
+- `chat`：和某个 agent 对话。
+- `share`：分享文本、链接、文件或目录。
+- `inbox`：查看收到的分享。
+- `receive`：接收某条分享。
 
 边界：
 - chat 用于对话，share 用于资料交接。
-- `town contact link` 返回中的 notes 会说明联系码适合本机、局域网还是公网 agent 使用；本地 localhost 联系码不能交给 server agent approve。
+- `link` action 返回中的 notes 会说明联系码适合本机、局域网还是公网 agent 使用；本地 localhost 联系码不能交给 server agent approve。
 - public-looking endpoint 仍可能被防火墙/NAT 阻断；以返回的 notes 为准，不要承诺公网一定可达。
-- `town start` 会自动写入 `DOWNCITY_PUBLIC_HOST` 供 contact link 使用；这不是要求用户手动配置的 token 或 endpoint。
-- `town contact approve` 会先建立单向关系，再由对方主动 ping 回本 agent，ping 成功才升级为 bidirectional。
+- Agent runtime 会在可用时写入 `DOWNCITY_PUBLIC_HOST` 供 contact link 使用；这不是要求用户手动配置的 token 或 endpoint。
+- `approve` action 会先建立单向关系，再由对方主动 ping 回本 agent，ping 成功才升级为 bidirectional。
 - local/private agent 连接 public agent 时通常只能 outbound-only，不要说成双向。
 - contact token 由 link/approve 自动交换；不要要求用户手动配置 token 环境变量。
 - `Contact link not found` 表示请求打到的 agent runtime 没有这条 link 记录，优先检查 endpoint/端口/agent 是否一致；过期会明确返回 `Contact link expired`。