@downcity/plugins 1.0.56 → 1.0.57

package/src/tts/types/TtsPlugin.ts

@@ -1,164 +1,129 @@
 /**
- * TTS Plugin 类型定义。
+ * TtsPlugin 类型定义。
  *
  * 关键点（中文）
- * - TTS 的行为配置与本地模型依赖统一收敛到 `plugins.tts`。
- * - Console 只需要理解 plugin setup，不需要理解底层 asset 细节。
+ * - TTS plugin 只定义 agent 侧协议，不绑定本地模型、Python 或 City 具体实现。
+ * - 真实语音合成能力通过 constructor 的 `tts` 函数注入，推荐传入 `city.ai.tts`。
+ * - action 最终统一返回 AI SDK UIMessage，便于 agent 统一处理音频 file part。
  */
 
-import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
-import type { TtsAudioFormat, TtsProvider } from "@/tts/types/Tts.js";
+import type { UIMessage } from "ai";
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 
 /**
- * TTS Plugin 配置。
+ * TTS 输入。
  */
-export interface TtsPluginConfig {
+export interface TtsPluginInput {
   /**
-   * 兼容统一结构化配置约束的索引签名。
+   * 需要合成为语音的文本。
    */
-  [key: string]: JsonValue | undefined;
-  /**
-   * 语音合成 provider 类型。
-   *
-   * 说明（中文）
-   * - 当前固定为 `local`。
-   */
-  provider?: TtsProvider;
-  /**
-   * 当前激活的本地模型 ID。
-   */
-  modelId?: string;
-  /**
-   * 本地模型根目录（可选）。
-   */
-  modelsDir?: string;
+  text: string;
   /**
-   * Python 可执行文件（可选）。
-   */
-  pythonBin?: string;
-  /**
-   * 默认语言提示（可选）。
-   *
-   * 说明（中文）
-   * - `auto` / `zh` / `en` 等简短值即可。
+   * 语言提示，例如 `auto`、`zh`、`en`。
    */
   language?: string;
   /**
-   * 默认音色 ID（可选）。
-   *
-   * 说明（中文）
-   * - 主要给运行时做覆盖；Console 默认不要求手动填写。
+   * 音色提示或上游 provider 的 voice id。
    */
   voice?: string;
   /**
-   * 默认输出格式。
+   * 输出格式提示，例如 `wav`、`mp3`、`ogg`。
    */
-  format?: TtsAudioFormat;
+  format?: string;
   /**
-   * 默认语速倍率。
+   * 语速倍率。
    */
   speed?: number;
   /**
-   * 输出目录。
-   *
-   * 说明（中文）
-   * - 可为相对项目根目录或绝对路径。
-   * - 为空时默认写到 `.downcity/.cache/tts/`。
-   */
-  outputDir?: string;
-  /**
-   * 单次合成超时时间（毫秒，可选）。
+   * Provider 私有参数。
    */
-  timeoutMs?: number;
+  provider_options?: JsonObject;
   /**
-   * 已安装模型列表（可选）。
-   *
-   * 说明（中文）
-   * - 仅作为状态快照使用，不应作为真实安装判断唯一依据。
+   * 允许外部 tts 函数接收其他 JSON 可序列化参数。
    */
-  installedModels?: string[];
+  [key: string]: JsonValue | undefined;
 }
 
 /**
- * TTS 安装输入。
+ * TTS 返回的标准 UIMessage。
  */
-export interface TtsInstallInput {
-  /**
-   * 兼容统一结构化配置约束的索引签名。
-   */
-  [key: string]: JsonValue | undefined;
-  /**
-   * 需要安装的模型 ID 列表（可选）。
-   */
-  modelIds?: string[];
+export type TtsPluginUiMessageResult = UIMessage;
+
+/**
+ * TTS 返回的简单音频结果。
+ */
+export interface TtsPluginSimpleAudioResult {
   /**
-   * 安装完成后激活的模型 ID（可选）。
+   * 音频 URL，可为远程 URL、本地路径或 data URL。
    */
-  activeModel?: string;
+  url?: string;
   /**
-   * 是否强制覆盖已存在资源。
+   * data URL 音频内容。
    */
-  force?: boolean;
+  data_url?: string;
   /**
-   * 模型目录（可选）。
+   * 本地音频文件路径。
    */
-  modelsDir?: string;
+  audio_path?: string;
   /**
-   * Python 可执行文件（可选）。
+   * 音频 MIME 类型，例如 `audio/wav`。
    */
-  pythonBin?: string;
+  media_type?: string;
   /**
-   * 是否同时安装 Python 依赖。
+   * 建议文件名。
    */
-  installDeps?: boolean;
+  filename?: string;
   /**
-   * HuggingFace Token（可选）。
+   * 可选说明文本。
    */
-  hfToken?: string;
+  text?: string;
   /**
-   * 安装完成后默认输出格式（可选）。
+   * 允许外部 tts 函数返回其他 JSON 可序列化字段。
    */
-  format?: TtsAudioFormat;
+  [key: string]: JsonValue | undefined;
 }
 
 /**
- * TTS 合成输入。
+ * TTS 输出。
  */
-export interface TtsSynthesizeInput {
-  /**
-   * 兼容统一结构化配置约束的索引签名。
-   */
-  [key: string]: JsonValue | undefined;
+export type TtsPluginResult =
+  | TtsPluginUiMessageResult
+  | TtsPluginSimpleAudioResult;
+
+/**
+ * TtsPlugin 构造参数。
+ */
+export interface TtsPluginOptions {
   /**
-   * 需要合成的文本内容。
+   * Plugin 稳定名称，默认 `tts`。
    */
-  text?: string;
+  name?: string;
   /**
-   * 覆盖当前使用的模型 ID。
+   * Plugin 展示标题，默认 `TTS`。
    */
-  modelId?: string;
+  title?: string;
   /**
-   * 覆盖当前语言提示（可选）。
+   * Plugin 用途说明。
    */
-  language?: string;
+  description?: string;
   /**
-   * 覆盖当前音色（可选）。
+   * 真实 TTS 能力函数。
+   *
+   * 说明（中文）
+   * - 推荐传入 `(input) => city.ai.tts(input)`。
+   * - plugin 只负责调用该函数，不关心模型、provider、鉴权或运行依赖。
    */
-  voice?: string;
+  tts: (input: TtsPluginInput) => Promise<TtsPluginResult> | TtsPluginResult;
   /**
-   * 覆盖当前输出格式。
+   * 默认语言提示。
    */
-  format?: TtsAudioFormat;
+  language?: string;
   /**
-   * 覆盖当前语速倍率。
+   * 默认音色提示。
    */
-  speed?: number;
+  voice?: string;
   /**
-   * 覆盖当前输出路径或目录。
-   *
-   * 说明（中文）
-   * - 若传入带扩展名的路径，则直接写该文件。
-   * - 若传入目录，则按默认命名生成文件。
+   * 默认输出格式提示。
    */
-  output?: string;
+  format?: string;
 }

package/src/web/PROMPT.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/web/PROMPT.ts.txt
-const TEXT_MODULE_CONTENT = "# Web Plugin\n\n此 plugin 已内化 `web-access` 的核心联网策略。只要 plugin 启用，就应把联网任务当作一等能力处理。\n\n## 总原则\n\n- 目标驱动：像人一样思考，先定义成功标准，再选择最可能直达的起点。\n- 过程校验：每一步结果都是证据。路径不推进时，及时切换方法，不在错误方式上反复重试。\n- 一手来源优先：搜索引擎用于发现线索，结论尽量回到官网、官方平台、原始页面、官方文档或源码。\n- 完成即停止：达到目标后不要为了“看起来更完整”继续消耗额外步骤。\n\n## 工具选择\n\n- 需要发现信息来源、查关键词脉络：优先 `WebSearch`\n- 已知 URL，需要定向提取页面正文或答案：优先 `WebFetch`\n- 已知 URL，需要原始 HTML、meta、JSON-LD 等结构化内容：优先 `curl`\n- 需要登录态、动态渲染、站内导航、复杂交互或反爬站点：直接使用浏览器/CDP 能力\n- 页面正文导向内容可优先考虑 Jina 类 markdown 预处理，以节省 token；但数据面板、商品页、复杂布局页面不要盲信预处理结果\n\n## 浏览器策略\n\n- 进入浏览器层后，先理解页面结构，再决定下一步动作\n- 程序化手段快但更容易触发反爬；GUI 交互更慢但确定性更高。程序化受阻时，回退到 GUI\n- 优先使用页面自身生成的链接，不要手工猜测或裁剪站内 URL 参数\n- 只操作自己创建的标签页，不打扰用户已有标签页；任务结束后关闭自己创建的标签页\n- 遇到登录墙时，先判断它是否真的阻挡目标；只有目标确实拿不到时再要求用户登录\n\n## 并行与核实\n\n- 多个独立调研目标可并行拆分；有依赖关系的目标不要盲目并行\n- 核实类任务要回到一手来源，不要用多个二手报道互相循环印证\n\n来源说明：该内化策略参考 `https://github.com/eze-is/web-access`，并按 Downcity plugin 体系进行了收敛与改写。\n";
+const TEXT_MODULE_CONTENT = "# Web Plugin\n\n此 plugin 主要注入通用联网方法论。它不选择 provider，也不保证某个具体联网工具一定存在。\n\n如果需要准备联网相关依赖，可以通过 `web` plugin 的 `install` action 安装 `web-access`、`agent-browser` 等 skill / CLI 依赖。安装只负责准备能力，不表示运行时必须使用某个 provider。\n\n当任务需要联网、查证、阅读网页、操作网页或使用浏览器时，先根据当前可用 tools、skills 与用户目标选择合适路径。\n\n## 总原则\n\n- 目标驱动：像人一样思考，先定义成功标准，再选择最可能直达的起点。\n- 过程校验：每一步结果都是证据。路径不推进时，及时切换方法，不在错误方式上反复重试。\n- 一手来源优先：搜索引擎用于发现线索，结论尽量回到官网、官方平台、原始页面、官方文档或源码。\n- 完成即停止：达到目标后不要为了“看起来更完整”继续消耗额外步骤。\n- 能力自检：不要假设某个联网 skill/tool 一定存在；优先使用当前 system、tool 列表和已 lookup 的 skill 中明确可用的能力。\n\n## 工具选择\n\n- 需要发现信息来源、查关键词脉络：优先使用当前可用的搜索类工具或 web-access 类 skill。\n- 已知 URL，需要定向提取页面正文或答案：优先使用当前可用的 fetch/read 类工具。\n- 已知 URL，需要原始 HTML、meta、JSON-LD 等结构化内容：优先使用当前可用的 HTTP/curl/shell 能力。\n- 需要登录态、动态渲染、站内导航、复杂交互或反爬站点：优先使用当前可用的浏览器、Chrome、agent-browser 或 computer-use 类能力。\n- 页面正文导向内容可优先考虑 Jina 类 markdown 预处理，以节省 token；但数据面板、商品页、复杂布局页面不要盲信预处理结果\n\n## 浏览器策略\n\n- 进入浏览器层后，先理解页面结构，再决定下一步动作\n- 程序化手段快但更容易触发反爬；GUI 交互更慢但确定性更高。程序化受阻时，回退到 GUI\n- 优先使用页面自身生成的链接，不要手工猜测或裁剪站内 URL 参数\n- 只操作自己创建的标签页，不打扰用户已有标签页；任务结束后关闭自己创建的标签页\n- 遇到登录墙时，先判断它是否真的阻挡目标；只有目标确实拿不到时再要求用户登录\n\n## 并行与核实\n\n- 多个独立调研目标可并行拆分；有依赖关系的目标不要盲目并行\n- 核实类任务要回到一手来源，不要用多个二手报道互相循环印证\n\n## 与 skills/tools 的关系\n\n- 如果当前环境有 `web-access` skill，联网搜索、网页抓取与资料核实任务可以优先参考它的说明。\n- 如果当前环境有 `agent-browser`、browser 或 Chrome 能力，动态页面与登录态任务可以优先使用它们。\n- 如果缺少必要联网能力，直接说明缺失能力，不要假装已经联网。\n\n## 可用 action\n\n- `install`：准备联网相关 skill / CLI 依赖。\n\n调用示例：\n\n```ts\nplugin_call({\n  plugin: \"web\",\n  action: \"install\",\n  payload: {\n    target: \"agent-browser\",\n    scope: \"user\",\n  },\n});\n```\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/web/PROMPT.ts.txt

@@ -1,6 +1,10 @@
 # Web Plugin
 
-此 plugin 已内化 `web-access` 的核心联网策略。只要 plugin 启用，就应把联网任务当作一等能力处理。
+此 plugin 主要注入通用联网方法论。它不选择 provider，也不保证某个具体联网工具一定存在。
+
+如果需要准备联网相关依赖，可以通过 `web` plugin 的 `install` action 安装 `web-access`、`agent-browser` 等 skill / CLI 依赖。安装只负责准备能力，不表示运行时必须使用某个 provider。
+
+当任务需要联网、查证、阅读网页、操作网页或使用浏览器时，先根据当前可用 tools、skills 与用户目标选择合适路径。
 
 ## 总原则
 
@@ -8,13 +12,14 @@
 - 过程校验：每一步结果都是证据。路径不推进时，及时切换方法，不在错误方式上反复重试。
 - 一手来源优先：搜索引擎用于发现线索，结论尽量回到官网、官方平台、原始页面、官方文档或源码。
 - 完成即停止：达到目标后不要为了“看起来更完整”继续消耗额外步骤。
+- 能力自检：不要假设某个联网 skill/tool 一定存在；优先使用当前 system、tool 列表和已 lookup 的 skill 中明确可用的能力。
 
 ## 工具选择
 
-- 需要发现信息来源、查关键词脉络：优先 `WebSearch`
-- 已知 URL，需要定向提取页面正文或答案：优先 `WebFetch`
-- 已知 URL，需要原始 HTML、meta、JSON-LD 等结构化内容：优先 `curl`
-- 需要登录态、动态渲染、站内导航、复杂交互或反爬站点：直接使用浏览器/CDP 能力
+- 需要发现信息来源、查关键词脉络：优先使用当前可用的搜索类工具或 web-access 类 skill。
+- 已知 URL，需要定向提取页面正文或答案：优先使用当前可用的 fetch/read 类工具。
+- 已知 URL，需要原始 HTML、meta、JSON-LD 等结构化内容：优先使用当前可用的 HTTP/curl/shell 能力。
+- 需要登录态、动态渲染、站内导航、复杂交互或反爬站点：优先使用当前可用的浏览器、Chrome、agent-browser 或 computer-use 类能力。
 - 页面正文导向内容可优先考虑 Jina 类 markdown 预处理，以节省 token；但数据面板、商品页、复杂布局页面不要盲信预处理结果
 
 ## 浏览器策略
@@ -30,4 +35,25 @@
 - 多个独立调研目标可并行拆分；有依赖关系的目标不要盲目并行
 - 核实类任务要回到一手来源，不要用多个二手报道互相循环印证
 
-来源说明：该内化策略参考 `https://github.com/eze-is/web-access`，并按 Downcity plugin 体系进行了收敛与改写。
+## 与 skills/tools 的关系
+
+- 如果当前环境有 `web-access` skill，联网搜索、网页抓取与资料核实任务可以优先参考它的说明。
+- 如果当前环境有 `agent-browser`、browser 或 Chrome 能力，动态页面与登录态任务可以优先使用它们。
+- 如果缺少必要联网能力，直接说明缺失能力，不要假装已经联网。
+
+## 可用 action
+
+- `install`：准备联网相关 skill / CLI 依赖。
+
+调用示例：
+
+```ts
+plugin_call({
+  plugin: "web",
+  action: "install",
+  payload: {
+    target: "agent-browser",
+    scope: "user",
+  },
+});
+```