@downcity/plugins 1.0.216 → 1.0.233

package/src/skill/Plugin.ts

@@ -9,7 +9,7 @@
  */
 
 import { BasePlugin } from "@downcity/agent";
-import { createAction } from "@downcity/agent";
+import { create_action } from "@downcity/agent";
 import { z } from "zod";
 import type { Plugin } from "@downcity/agent";
 import type { JsonObject, JsonValue } from "@downcity/agent";
@@ -60,17 +60,17 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
     title: "Skill Catalog And Loader",
     description:
       "Lists and reads local skills, and injects scan-aware discovery and installation guidance into system prompts.",
-    async system(context, run_context) {
+    async system(context, execution_context) {
       const dynamicText = String(
         await buildSkillsSystemText({
-          rootPath: context.rootPath,
+          rootPath: context.workspace_path,
           options,
-        }, run_context),
+        }, execution_context),
       ).trim();
       return [SKILL_PLUGIN_PROMPT, dynamicText].filter(Boolean).join("\n\n");
     },
     actions: {
-      [SKILL_PLUGIN_ACTIONS.find]: createAction({
+      [SKILL_PLUGIN_ACTIONS.find]: create_action({
         description:
           "Return shell instructions for finding a skill. This action does not execute the search.",
         input_schema: {
@@ -100,7 +100,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
           configure(command) {
             command.argument("<query>");
           },
-          mapInput({ args }): SkillPluginFindPayload {
+          map_input({ args }): SkillPluginFindPayload {
             const query = String(args[0] || "").trim();
             if (!query) throw new Error("Missing query");
             return { query };
@@ -119,7 +119,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
           };
         },
       }),
-      [SKILL_PLUGIN_ACTIONS.install]: createAction({
+      [SKILL_PLUGIN_ACTIONS.install]: create_action({
         description:
           "Return scan-aware shell instructions for installing a skill. This action does not install anything.",
         input_schema: {
@@ -149,7 +149,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
           configure(command) {
             command.argument("<spec>");
           },
-          mapInput({ args }): SkillPluginInstallPayload {
+          map_input({ args }): SkillPluginInstallPayload {
             const spec = String(args[0] || "").trim();
             if (!spec) throw new Error("Missing spec");
             return { spec };
@@ -164,7 +164,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
               kind: "instructions",
               spec: payload.spec,
               prompt: render_skill_install_prompt(
-                params.context.rootPath,
+                params.context.workspace_path,
                 options,
                 payload.spec,
               ),
@@ -172,7 +172,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
           };
         },
       }),
-      [SKILL_PLUGIN_ACTIONS.list]: createAction({
+      [SKILL_PLUGIN_ACTIONS.list]: create_action({
         description: "List currently learned skills discoverable locally.",
         input_schema: {
           zod: z.object({}).passthrough(),
@@ -189,7 +189,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
         ],
         command: {
           description: "List currently learned skills discoverable locally.",
-          mapInput() {
+          map_input() {
             return {};
           },
         },
@@ -199,11 +199,11 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
         execute(params): PluginActionResult<JsonObject> {
           return {
             success: true,
-            data: listSkills(params.context.rootPath, options) as unknown as JsonObject,
+            data: listSkills(params.context.workspace_path, options) as unknown as JsonObject,
           };
         },
       }),
-      [SKILL_PLUGIN_ACTIONS.lookup]: createAction({
+      [SKILL_PLUGIN_ACTIONS.lookup]: create_action({
         description: "Read learned skill content (SKILL.md).",
         input_schema: {
           zod: z.object({
@@ -228,7 +228,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
           configure(command) {
             command.argument("<name>");
           },
-          mapInput({ args }): SkillPluginLookupPayload {
+          map_input({ args }): SkillPluginLookupPayload {
             const name = String(args[0] || "").trim();
             if (!name) throw new Error("Missing name");
             return { name };
@@ -236,7 +236,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
         },
         api: {
           method: "POST",
-          async mapInput(c): Promise<SkillPluginLookupPayload> {
+          async map_input(c): Promise<SkillPluginLookupPayload> {
             const body = readJsonObject(await c.req.json());
             const name = String(body.name || "").trim();
             if (!name) throw new Error("Missing name");
@@ -246,7 +246,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
         async execute(params): Promise<PluginActionResult<JsonObject>> {
           const payload = params.input as SkillPluginLookupPayload;
           const result = await lookupSkill({
-            projectRoot: params.context.rootPath,
+            project_root: params.context.workspace_path,
             request: {
               name: payload.name,
             },

package/src/skill/runtime/Discovery.ts

@@ -57,7 +57,7 @@ function shouldIgnoreSkill(
  * 扫描并发现本地 skills。
  *
  * 关键点（中文）
- * - skills 的扫描根目录与 projectRoot 强相关（默认 `.agents/skills`）
+ * - skills 的扫描根目录与 project_root 强相关（默认 `.agents/skills`）
  * - 这里做成同步函数：启动时扫描一次，产出 prompt section 与 tools 索引
  */
 /**
@@ -68,10 +68,10 @@ function shouldIgnoreSkill(
  * 4) 最终按 name 排序，保证输出稳定
  */
 export function discoverSkillsSync(
-  projectRoot: string,
+  project_root: string,
   options?: SkillPluginOptions | null,
 ): SkillDefinition[] {
-  const root = String(projectRoot || "").trim();
+  const root = String(project_root || "").trim();
   if (!root) return [];
   const resolvedOptions = resolveSkillPluginOptions(options);
   const roots = getSkillSearchRoots(root, resolvedOptions);

package/src/skill/runtime/Paths.ts

@@ -29,15 +29,15 @@ function normalizeSkillRootCandidate(candidate: string): string {
   return normalized;
 }
 
-function resolveSkillRootPath(projectRoot: string, raw: string): string {
+function resolveSkillRootPath(project_root: string, raw: string): string {
   const expanded = expandHome(raw);
   return path.isAbsolute(expanded)
     ? path.normalize(expanded)
-    : path.resolve(projectRoot, expanded);
+    : path.resolve(project_root, expanded);
 }
 
 export function getSkillSearchRoots(
-  projectRoot: string,
+  project_root: string,
   options?: SkillPluginOptions | null,
 ): SkillRoot[] {
   const skillPluginOptions = resolveSkillPluginOptions(options);
@@ -58,7 +58,7 @@ export function getSkillSearchRoots(
 
   // 1) project roots（最高优先级）
   for (const raw of rawProject) {
-    const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(projectRoot, raw));
+    const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(project_root, raw));
     roots.push({
       source: "project",
       raw,
@@ -71,7 +71,7 @@ export function getSkillSearchRoots(
 
   // 2) constructor paths：用户显式传入的路径，统一视为 custom 来源
   for (const raw of rawConfigured) {
-    const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(projectRoot, raw));
+    const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(project_root, raw));
     roots.push({
       source: "custom",
       raw,
@@ -84,7 +84,7 @@ export function getSkillSearchRoots(
 
   // 3) home root（用户目录）
   for (const raw of rawHome) {
-    const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(projectRoot, raw));
+    const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(project_root, raw));
     roots.push({
       source: "home",
       raw,

package/src/skill/runtime/Store.ts

@@ -15,15 +15,15 @@ import type {
 const sessionSkillStateStore = new Map<string, SessionSkillStateInternal>();
 
 /**
- * 归一化 sessionId。
+ * 归一化 session_id。
  *
  * 关键点（中文）
- * - 空 sessionId 视为调用错误，直接抛异常，避免污染全局状态。
+ * - 空 session_id 视为调用错误，直接抛异常，避免污染全局状态。
  */
-function normalizeSessionId(sessionId: string): string {
-  const value = String(sessionId || "").trim();
+function normalizeSessionId(session_id: string): string {
+  const value = String(session_id || "").trim();
   if (!value) {
-    throw new Error("sessionId is required for session skills state");
+    throw new Error("session_id is required for session skills state");
   }
   return value;
 }
@@ -31,14 +31,14 @@ function normalizeSessionId(sessionId: string): string {
 /**
  * 获取或创建 session 技能状态。
  */
-function getOrCreateState(sessionId: string): SessionSkillStateInternal {
-  const key = normalizeSessionId(sessionId);
+function getOrCreateState(session_id: string): SessionSkillStateInternal {
+  const key = normalizeSessionId(session_id);
   const existing = sessionSkillStateStore.get(key);
   if (existing) return existing;
 
   const created: SessionSkillStateInternal = {
     allSkillsById: new Map(),
-    updatedAt: Date.now(),
+    updated_at: Date.now(),
   };
   sessionSkillStateStore.set(key, created);
   return created;
@@ -51,10 +51,10 @@ function getOrCreateState(sessionId: string): SessionSkillStateInternal {
  * - 以 id 归一化后整体替换，避免残留脏状态。
  */
 export function setSessionAvailableSkills(
-  sessionId: string,
+  session_id: string,
   skills: SkillDefinition[],
 ): void {
-  const state = getOrCreateState(sessionId);
+  const state = getOrCreateState(session_id);
   const next = new Map<string, SkillDefinition>();
 
   for (const skill of Array.isArray(skills) ? skills : []) {
@@ -64,35 +64,35 @@ export function setSessionAvailableSkills(
   }
 
   state.allSkillsById = next;
-  state.updatedAt = Date.now();
+  state.updated_at = Date.now();
 }
 
 /**
  * 获取会话技能状态快照。
  */
-export function getSessionSkillState(sessionId: string): SessionSkillStateSnapshot {
-  const key = normalizeSessionId(sessionId);
+export function getSessionSkillState(session_id: string): SessionSkillStateSnapshot {
+  const key = normalizeSessionId(session_id);
   const state = sessionSkillStateStore.get(key);
 
   if (!state) {
     return {
-      sessionId: key,
+      session_id: key,
       allSkills: [],
-      updatedAt: 0,
+      updated_at: 0,
     };
   }
 
   return {
-    sessionId: key,
+    session_id: key,
     allSkills: Array.from(state.allSkillsById.values()),
-    updatedAt: state.updatedAt,
+    updated_at: state.updated_at,
   };
 }
 
 /**
  * 清理会话技能状态。
  */
-export function clearSessionSkillState(sessionId: string): void {
-  const key = normalizeSessionId(sessionId);
+export function clearSessionSkillState(session_id: string): void {
+  const key = normalizeSessionId(session_id);
   sessionSkillStateStore.delete(key);
 }

package/src/skill/runtime/SystemProvider.ts

@@ -7,7 +7,7 @@
  * - `lookup` 行为为无状态：由 action 读取 SKILL.md 后通过协议注入 user message
  */
 
-import type { PluginRunContext } from "@downcity/agent";
+import type { PluginExecutionContext } from "@downcity/agent";
 import { discoverSkillsSync } from "./Discovery.js";
 import { render_skills_prompt_section } from "./Prompt.js";
 import { setSessionAvailableSkills } from "./Store.js";
@@ -28,16 +28,16 @@ type SkillSystemRuntime = {
  */
 export async function buildSkillsSystemText(
   runtime: SkillSystemRuntime,
-  run_context?: PluginRunContext,
+  execution_context?: PluginExecutionContext,
 ): Promise<string> {
-  const sessionId = String(run_context?.sessionId || "").trim();
+  const session_id = String(execution_context?.session_id || "").trim();
   const discoveredSkills = discoverSkillsSync(
     runtime.rootPath,
     runtime.options,
   );
 
-  if (sessionId) {
-    setSessionAvailableSkills(sessionId, discoveredSkills);
+  if (session_id) {
+    setSessionAvailableSkills(session_id, discoveredSkills);
   }
 
   return render_skills_prompt_section(

package/src/skill/runtime/Types.ts

@@ -8,9 +8,9 @@ import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
  * - core 不依赖该结构
  */
 export type SessionSkillStateSnapshot = {
-  sessionId: string;
+  session_id: string;
   allSkills: SkillDefinition[];
-  updatedAt: number;
+  updated_at: number;
 };
 
 /**
@@ -18,5 +18,5 @@ export type SessionSkillStateSnapshot = {
  */
 export type SessionSkillStateInternal = {
   allSkillsById: Map<string, SkillDefinition>;
-  updatedAt: number;
+  updated_at: number;
 };

package/src/sound/Plugin.ts

@@ -5,14 +5,14 @@
  * - 对 Agent 暴露 `models`、`asr`、`tts` 三个 action。
  * - 模型目录与真实 ASR/TTS 能力全部由 FED/City constructor 回调注入。
  * - 本地音频只负责读取并转换为 data URL，不加载或运行任何本地语音模型。
- * - TTS 返回 AI SDK UIMessage，音频 file part 由 agent 统一落盘。
+ * - TTS 返回已经落盘的本地音频 UIMessage Parts，并由 Action 声明 Assistant Message。
  */
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import { BasePlugin, createAction } from "@downcity/agent";
+import { BasePlugin, create_action } from "@downcity/agent";
 import { z } from "zod";
-import type { AgentContext, JsonObject, JsonValue } from "@downcity/agent";
+import type { PluginContext, JsonObject, JsonValue } from "@downcity/agent";
 import { CHAT_PLUGIN_POINTS } from "@/chat/runtime/PluginPoints.js";
 import type {
   ChatInboundAugmentInput,
@@ -224,12 +224,12 @@ async function local_audio_to_data_url(input: {
  * 把 Agent 公开 ASR 输入解析为可直接发送给 FED 的输入。
  */
 async function resolve_asr_input(
-  context: AgentContext,
+  context: PluginContext,
   input: SoundPluginAsrInput,
 ): Promise<SoundPluginAsrInput> {
   if (!input.audio_path) return input;
   const local = await local_audio_to_data_url({
-    root_path: context.rootPath,
+    root_path: context.workspace_path,
     audio_path: input.audio_path,
     media_type: input.media_type,
   });
@@ -372,6 +372,16 @@ function normalize_tts_result(result: SoundPluginTtsResult): SoundPluginTtsResul
   if (!has_audio_file) {
     throw new TypeError("SoundPlugin tts UIMessage must contain an audio file part");
   }
+  for (const part of record.parts) {
+    const part_record = to_record(part);
+    if (part_record?.type !== "file") continue;
+    const url = String(part_record.url || "").trim();
+    if (!url || url.startsWith("data:") || /^https?:\/\//i.test(url)) {
+      throw new TypeError(
+        "SoundPlugin tts file parts must be saved locally before returning",
+      );
+    }
+  }
   return result;
 }
 
@@ -401,12 +411,12 @@ function append_voice_text(
   input: ChatInboundAugmentInput,
   voice_blocks: string[],
 ): ChatInboundAugmentInput {
-  const current = String(input.bodyText || "").trim();
+  const current = String(input.body_text || "").trim();
   const addition = voice_blocks.map((item) => item.trim()).filter(Boolean).join("\n\n");
   if (!addition) return input;
   return {
     ...input,
-    bodyText: [current, addition].filter(Boolean).join("\n\n"),
+    body_text: [current, addition].filter(Boolean).join("\n\n"),
   };
 }
 
@@ -464,7 +474,7 @@ export class SoundPlugin extends BasePlugin {
   /**
    * SoundPlugin 给 Agent 的使用说明。
    */
-  system(_context: AgentContext): string {
+  system(_context: PluginContext): string {
     return [
       "# Sound Plugin",
       "",
@@ -488,7 +498,7 @@ export class SoundPlugin extends BasePlugin {
       "## Results",
       "",
       "ASR returns transcript text and may include timed segments, language, and duration.",
-      "TTS returns an AI SDK UIMessage. Its audio file part is saved under project resources and attached to the assistant response automatically.",
+      "TTS returns an AI SDK UIMessage whose audio file part already points to a local file, and that part is attached to the assistant response.",
       "Do not invent a transcript or audio result when a FED call fails.",
       "",
       `When unsure, use \`plugin_read { plugin: \"${this.name}\", action: \"...\" }\` to inspect the complete schema.`,
@@ -499,7 +509,7 @@ export class SoundPlugin extends BasePlugin {
    * 执行一次 ASR 转写。
    */
   private async transcribe(
-    context: AgentContext,
+    context: PluginContext,
     input: SoundPluginAsrInput,
   ): Promise<SoundPluginAsrResult> {
     const model = resolve_model_id("asr", input.model, this.default_asr_model);
@@ -531,7 +541,7 @@ export class SoundPlugin extends BasePlugin {
    */
   private async auto_transcribe_inbound(input: {
     /** 当前 Agent 上下文。 */
-    context: AgentContext;
+    context: PluginContext;
     /** chat 入站管道值。 */
     value: JsonValue;
   }): Promise<JsonValue> {
@@ -552,7 +562,7 @@ export class SoundPlugin extends BasePlugin {
           ...(attachment.contentType ? { media_type: attachment.contentType } : {}),
           ...(attachment.fileName ? { filename: attachment.fileName } : {}),
         });
-        const src = to_display_src(input.context.rootPath, attachment);
+        const src = to_display_src(input.context.workspace_path, attachment);
         voice_blocks.push(
           `<voice src="${escape_xml_attr(src)}">${escape_xml_text(result.text)}</voice>`,
         );
@@ -569,7 +579,7 @@ export class SoundPlugin extends BasePlugin {
   readonly hooks = {
     pipeline: {
       [CHAT_PLUGIN_POINTS.augmentInbound]: [
-        async ({ context, value }: { context: AgentContext; value: JsonValue }) =>
+        async ({ context, value }: { context: PluginContext; value: JsonValue }) =>
           await this.auto_transcribe_inbound({ context, value }),
       ],
     },
@@ -579,7 +589,7 @@ export class SoundPlugin extends BasePlugin {
    * 显式 action 集合。
    */
   readonly actions = {
-    models: createAction({
+    models: create_action({
       description: "List FED models that support ASR or TTS.",
       input_schema: {
         zod: SOUND_MODELS_INPUT_SCHEMA,
@@ -617,7 +627,7 @@ export class SoundPlugin extends BasePlugin {
         }
       },
     }),
-    asr: createAction({
+    asr: create_action({
       description:
         "Transcribe audio with a FED ASR model. Local audio paths are converted to data URLs before the FED call.",
       input_schema: {
@@ -640,7 +650,7 @@ export class SoundPlugin extends BasePlugin {
         { title: "Local audio", payload: { model: "asr-model-id", audio_path: "./input.wav" } },
         { title: "Remote audio", payload: { model: "asr-model-id", url: "https://example.com/audio.mp3" } },
       ],
-      execute: async ({ context, input }: { context: AgentContext; input: JsonValue }) => {
+      execute: async ({ context, input }: { context: PluginContext; input: JsonValue }) => {
         try {
           const result = await this.transcribe(context, normalize_asr_payload(input));
           return {
@@ -654,7 +664,7 @@ export class SoundPlugin extends BasePlugin {
         }
       },
     }),
-    tts: createAction({
+    tts: create_action({
       description:
         "Synthesize speech with a FED TTS model and return an AI SDK UIMessage containing audio.",
       input_schema: {
@@ -686,8 +696,11 @@ export class SoundPlugin extends BasePlugin {
           const result = await this.synthesize(normalize_tts_payload(input));
           return {
             success: true,
-            data: result as unknown as JsonObject,
             message: "speech synthesized",
+            messages: [{
+              role: "assistant" as const,
+              parts: result.parts,
+            }],
           };
         } catch (error) {
           const message = describe_error(error);