@downcity/plugins 1.0.56 → 1.0.59

package/src/asr/Dependency.ts

@@ -1,336 +0,0 @@
-/**
- * ASR Plugin Dependency Helper。
- *
- * 关键点（中文）
- * - ASR 的转写依赖现在内聚在 plugin 内部，不再暴露独立依赖端口心智。
- * - 这里统一管理检查、安装、配置读写与转写句柄解析。
- */
-
-import { execFile as execFileCb } from "node:child_process";
-import { promisify } from "node:util";
-import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
-import type { PluginCommandContext } from "@downcity/agent/internal/plugin/types/Plugin.js";
-import type {
-  VoicePluginConfig,
-  VoiceTranscriberConfig,
-  VoiceTranscriberInstallInput,
-  VoiceTranscriberHandle,
-} from "@/voice/types/VoicePlugin.js";
-import { transcribeVoiceAudio } from "@/voice/runtime/Transcriber.js";
-import {
-  VOICE_MODEL_CATALOG,
-  resolveVoiceModelId,
-} from "@/voice/runtime/Catalog.js";
-import {
-  detectLocalVoiceModelInstallState,
-  installVoiceModelFromHuggingFace,
-} from "@/voice/runtime/Installer.js";
-import {
-  installVoiceTranscribeDependencies,
-  resolveVoiceRunnersByModels,
-  resolveVoiceStrategyByModel,
-} from "@/voice/runtime/DependencyInstaller.js";
-import { resolveVoiceModelsRootDir } from "@/voice/runtime/Paths.js";
-import type { VoiceModelId } from "@/voice/types/Voice.js";
-
-const execFileAsync = promisify(execFileCb);
-
-export interface VoiceDependencyCheckResult {
-  /**
-   * 当前依赖是否可用。
-   */
-  available: boolean;
-  /**
-   * 不可用原因列表。
-   */
-  reasons: string[];
-  /**
-   * 结构化附加数据（可选）。
-   */
-  details?: JsonValue;
-}
-
-export interface VoiceDependencyInstallResult {
-  /**
-   * 安装是否成功。
-   */
-  success: boolean;
-  /**
-   * 人类可读消息（可选）。
-   */
-  message?: string;
-  /**
-   * 结构化附加数据（可选）。
-   */
-  details?: JsonValue;
-}
-
-function readVoicePluginRecord(context: PluginCommandContext): Record<string, unknown> {
-  const current = context.config.plugins?.asr;
-  if (!current || typeof current !== "object" || Array.isArray(current)) {
-    return {};
-  }
-  return current as Record<string, unknown>;
-}
-
-function toJsonObject(input: Record<string, unknown> | null | undefined): JsonObject {
-  const out: JsonObject = {};
-  if (!input) return out;
-  for (const [key, value] of Object.entries(input)) {
-    if (value === undefined) continue;
-    if (
-      value === null ||
-      typeof value === "string" ||
-      typeof value === "number" ||
-      typeof value === "boolean"
-    ) {
-      out[key] = value;
-      continue;
-    }
-    if (Array.isArray(value)) {
-      out[key] = value
-        .filter((item) => item !== undefined)
-        .map((item) => item as JsonValue);
-      continue;
-    }
-    if (typeof value === "object") {
-      out[key] = toJsonObject(value as Record<string, unknown>);
-    }
-  }
-  return out;
-}
-
-/**
- * 读取 ASR 转写依赖配置。
- */
-export function readVoiceTranscriberConfig(
-  context: PluginCommandContext,
-): VoiceTranscriberConfig {
-  const { enabled: _ignoredEnabled, ...current } = readVoicePluginRecord(
-    context,
-  ) as Record<string, unknown> & {
-    enabled?: boolean;
-  };
-  return {
-    provider: "local",
-    ...(current as VoiceTranscriberConfig),
-  };
-}
-
-/**
- * 写入 ASR 转写依赖配置。
- */
-export async function writeVoiceTranscriberConfig(params: {
-  context: PluginCommandContext;
-  value: Partial<VoiceTranscriberConfig>;
-}): Promise<VoicePluginConfig> {
-  if (!params.context.config.plugins) {
-    params.context.config.plugins = {};
-  }
-  const current = readVoicePluginRecord(params.context);
-  const next: Record<string, unknown> & {
-    enabled?: boolean;
-  } = {
-    ...current,
-    ...params.value,
-  };
-  delete next.enabled;
-  params.context.config.plugins.asr = toJsonObject(next);
-  await params.context.pluginConfig.persistProjectPlugins(params.context.config.plugins);
-  return params.context.config.plugins.asr as VoicePluginConfig;
-}
-
-async function checkLocalProviderAvailability(
-  context: PluginCommandContext,
-  config: VoiceTranscriberConfig,
-): Promise<VoiceDependencyCheckResult> {
-  const reasons: string[] = [];
-  const modelId = resolveVoiceModelId(String(config.modelId || ""));
-  if (!modelId) {
-    reasons.push("asr transcriber modelId is missing");
-    return {
-      available: false,
-      reasons,
-    };
-  }
-
-  const modelsRootDir = resolveVoiceModelsRootDir({
-    projectRoot: context.rootPath,
-    modelsDir: config.modelsDir,
-  });
-  const installState = await detectLocalVoiceModelInstallState({
-    modelId,
-    modelsRootDir,
-  });
-  if (!installState.installed) {
-    reasons.push(`asr model is not installed: ${modelId}`);
-  }
-
-  const pythonBin = String(config.pythonBin || "").trim() || "python3";
-  try {
-    await execFileAsync(pythonBin, ["--version"], {
-      timeout: 15_000,
-      maxBuffer: 1024 * 1024,
-    });
-  } catch (error) {
-    reasons.push(`python runtime missing: ${String(error)}`);
-  }
-
-  return {
-    available: reasons.length === 0,
-    reasons,
-  };
-}
-
-/**
- * 检查 ASR 转写依赖可用性。
- */
-export async function checkVoiceTranscriber(
-  context: PluginCommandContext,
-): Promise<VoiceDependencyCheckResult> {
-  const config = readVoiceTranscriberConfig(context);
-  if (config.provider === "command") {
-    const command = String(config.command || "").trim();
-    return {
-      available: Boolean(command),
-      reasons: command ? [] : ["asr transcriber command is missing"],
-    };
-  }
-  return checkLocalProviderAvailability(context, config);
-}
-
-/**
- * 安装或修复 ASR 转写依赖。
- */
-export async function installVoiceTranscriber(params: {
-  context: PluginCommandContext;
-  input?: VoiceTranscriberInstallInput;
-}): Promise<VoiceDependencyInstallResult> {
-  const context = params.context;
-  const input = params.input;
-  const config = readVoiceTranscriberConfig(context);
-  if (config.provider === "command") {
-    return {
-      success: true,
-      message: "asr command provider does not require install",
-    };
-  }
-
-  const requestedModelIds =
-    (Array.isArray(input?.modelIds) ? input?.modelIds : [])
-      .map((item) => resolveVoiceModelId(String(item || "").trim()))
-      .filter((item): item is VoiceModelId => Boolean(item));
-  const selectedModelIds: VoiceModelId[] =
-    requestedModelIds.length > 0
-      ? requestedModelIds
-      : [resolveVoiceModelId(String(config.modelId || "SenseVoiceSmall")) || "SenseVoiceSmall"];
-
-  const modelsRootDir = resolveVoiceModelsRootDir({
-    projectRoot: context.rootPath,
-    modelsDir: input?.modelsDir || config.modelsDir,
-  });
-
-  for (const modelId of selectedModelIds) {
-    const model = VOICE_MODEL_CATALOG.find((item) => item.id === modelId);
-    if (!model) {
-      throw new Error(`Unsupported asr model: ${modelId}`);
-    }
-    const installState = await detectLocalVoiceModelInstallState({
-      modelId,
-      modelsRootDir,
-    });
-    if (!installState.installed || input?.force === true) {
-      await installVoiceModelFromHuggingFace({
-        model,
-        modelsRootDir,
-        force: input?.force === true,
-        hfToken: input?.hfToken,
-      });
-    }
-  }
-
-  if (input?.installDeps !== false) {
-    await installVoiceTranscribeDependencies({
-      pythonBin:
-        String(input?.pythonBin || config.pythonBin || "").trim() || "python3",
-      runners: resolveVoiceRunnersByModels(selectedModelIds),
-    });
-  }
-
-  const activeModelId =
-    resolveVoiceModelId(String(input?.activeModel || "")) ||
-    selectedModelIds[0];
-
-  const nextConfig: VoiceTranscriberConfig = {
-    ...config,
-    provider: "local",
-    modelId: activeModelId,
-    modelsDir: modelsRootDir,
-    pythonBin:
-      String(input?.pythonBin || config.pythonBin || "").trim() || undefined,
-    ...(config.command ? { command: config.command } : {}),
-    language:
-      typeof config.language === "string" && config.language.trim()
-        ? config.language.trim()
-        : undefined,
-    strategy: resolveVoiceStrategyByModel(activeModelId),
-    installedModels: selectedModelIds,
-  };
-  await writeVoiceTranscriberConfig({
-    context,
-    value: nextConfig,
-  });
-
-  return {
-    success: true,
-    message: "asr transcriber installed",
-    details: {
-      modelIds: selectedModelIds,
-      activeModel: activeModelId,
-      modelsRootDir,
-    },
-  };
-}
-
-/**
- * 解析 ASR 转写句柄。
- */
-export async function resolveVoiceTranscriber(
-  context: PluginCommandContext,
-): Promise<VoiceTranscriberHandle> {
-  return {
-    async transcribe(input) {
-      try {
-        const result = await transcribeVoiceAudio({
-          context,
-          audioPath: input.audioPath,
-          language: input.language,
-        });
-        return {
-          success: true,
-          text: result.text,
-        };
-      } catch (error) {
-        return {
-          success: false,
-          error: String(error),
-        };
-      }
-    },
-  };
-}
-
-/**
- * 执行一次 ASR 转写。
- */
-export async function transcribeWithVoiceDependency(params: {
-  context: PluginCommandContext;
-  audioPath: string;
-  language?: string;
-}): Promise<{ success: boolean; text?: string; error?: string }> {
-  const transcriber = await resolveVoiceTranscriber(params.context);
-  return transcriber.transcribe({
-    audioPath: params.audioPath,
-    ...(params.language ? { language: params.language } : {}),
-  });
-}

package/src/asr/InboundAugment.ts

@@ -1,59 +0,0 @@
-/**
- * ASR 入站消息增强 hook。
- *
- * 关键点（中文）
- * - 只处理 voice/audio 附件，转写结果作为 plugin section 注入。
- * - 转写失败不阻塞主链路，保持 best-effort。
- */
-
-import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
-import type { ChatInboundAugmentInput } from "@/chat/types/ChatPlugin.js";
-import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
-import { transcribeWithVoiceDependency } from "@/asr/Dependency.js";
-
-/**
- * 自动转写入站语音附件。
- */
-export async function augmentAsrInboundMessage(params: {
-  context: AgentContext;
-  value: JsonValue;
-}): Promise<JsonValue> {
-  const input = params.value as unknown as ChatInboundAugmentInput;
-  const voiceAttachments = (Array.isArray(input.attachments) ? input.attachments : []).filter(
-    (item) =>
-      (item.kind === "voice" || item.kind === "audio") &&
-      typeof item.path === "string" &&
-      item.path.trim(),
-  );
-  if (voiceAttachments.length === 0) {
-    return input as unknown as JsonValue;
-  }
-
-  const pluginSections = Array.isArray(input.pluginSections)
-    ? [...input.pluginSections]
-    : [];
-
-  for (const attachment of voiceAttachments) {
-    try {
-      const result = await transcribeWithVoiceDependency({
-        context: params.context,
-        audioPath: String(attachment.path || "").trim(),
-      });
-      const text = typeof result.text === "string" ? result.text.trim() : "";
-      if (!text) continue;
-
-      const absPath = String(attachment.path || "").trim();
-      const rel = absPath.startsWith(`${params.context.rootPath}/`)
-        ? absPath.slice(params.context.rootPath.length + 1)
-        : absPath;
-      pluginSections.push(`【语音转写 ${attachment.kind}: ${rel}】\n${text}`);
-    } catch {
-      // 关键点（中文）：转写失败不阻塞主链路，保持 best-effort。
-    }
-  }
-
-  return {
-    ...input,
-    pluginSections,
-  } as unknown as JsonValue;
-}

package/src/asr/ModelCatalog.ts

@@ -1,43 +0,0 @@
-/**
- * Voice 插件模型目录封装。
- *
- * 关键点（中文）
- * - 对 plugin 层暴露稳定的 ASR 模型目录接口。
- * - plugin 不直接依赖底层 runtime 文件布局，只依赖这里的领域封装。
- */
-
-import {
-  VOICE_MODEL_CATALOG,
-  resolveVoiceModelId,
-} from "@/voice/runtime/Catalog.js";
-
-/**
- * 列出内置 voice 模型目录。
- */
-export function listVoiceModels(): Array<{
-  /**
-   * 稳定模型 ID。
-   */
-  id: string;
-  /**
-   * 用户可读标签。
-   */
-  label: string;
-  /**
-   * 用户可读说明。
-   */
-  description: string;
-}> {
-  return VOICE_MODEL_CATALOG.map((item) => ({
-    id: item.id,
-    label: item.label,
-    description: item.description,
-  }));
-}
-
-/**
- * 解析用户输入的 voice 模型 ID。
- */
-export function resolveVoicePluginModelId(input: string): string | null {
-  return resolveVoiceModelId(input);
-}

package/src/auth/Plugin.ts

@@ -1,237 +0,0 @@
-/**
- * ChatAuthorizationPlugin。
- *
- * 关键点（中文）
- * - chat-authorization 是内建且必需的 plugin，不走可选启停语义。
- * - 静态授权配置与动态观测态都收敛在项目 `.downcity/chat/authorization/`。
- * - 它只负责聊天主体授权，不负责 Town HTTP Bearer token 或路由访问鉴权。
- */
-
-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";
-import { CHAT_PLUGIN_POINTS } from "@/chat/runtime/PluginPoints.js";
-import {
-  CHAT_AUTHORIZATION_ACTIONS,
-  CHAT_AUTHORIZATION_CATALOG,
-  CHAT_AUTHORIZATION_PLUGIN_NAME,
-  type ChatAuthorizationObservePrincipalPayload,
-  type ChatAuthorizationSetUserRolePayload,
-  type ChatAuthorizationWriteConfigPayload,
-  type ChatAuthorizationConfig,
-  type ChatAuthorizationEvaluateInput,
-  type ChatAuthorizationSnapshot,
-} from "@/auth/types/AuthPlugin.js";
-import {
-  readChatAuthorizationConfig,
-  setChatAuthorizationUserRole,
-  writeChatAuthorizationConfig,
-} from "@/auth/runtime/AuthorizationConfig.js";
-import {
-  evaluateIncomingChatAuthorization,
-  resolveAuthorizedUserRole,
-} from "@/auth/runtime/AuthorizationPolicy.js";
-import {
-  readAuthorizationSnapshot,
-  recordObservedAuthorizationPrincipal,
-} from "@/auth/runtime/AuthorizationStore.js";
-import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
-
-function toChannel(value: unknown): ChatDispatchChannel | null {
-  const text = String(value || "").trim().toLowerCase();
-  if (text === "telegram" || text === "feishu" || text === "qq") return text;
-  return null;
-}
-
-function toRecord(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-  return value as Record<string, unknown>;
-}
-
-function toEvaluateInput(payload: Record<string, unknown>): ChatAuthorizationEvaluateInput {
-  const channel = toChannel(payload.channel);
-  if (!channel) {
-    throw new Error("chat-authorization.authorize_incoming requires a valid channel");
-  }
-  return {
-    channel,
-    chatId: String(payload.chatId || "").trim(),
-    ...(typeof payload.chatType === "string" ? { chatType: payload.chatType.trim() } : {}),
-    ...(typeof payload.userId === "string" ? { userId: payload.userId.trim() } : {}),
-    ...(typeof payload.username === "string" ? { username: payload.username.trim() } : {}),
-    ...(typeof payload.chatTitle === "string" ? { chatTitle: payload.chatTitle.trim() } : {}),
-  };
-}
-
-function toSnapshotData(snapshot: ChatAuthorizationSnapshot): JsonValue {
-  return {
-    catalog: CHAT_AUTHORIZATION_CATALOG as unknown as JsonValue,
-    config: snapshot.config as unknown as JsonValue,
-    users: snapshot.users as unknown as JsonValue,
-    chats: snapshot.chats as unknown as JsonValue,
-  };
-}
-
-function createChatAuthorizationPluginDefinition(): Plugin {
-  return {
-    name: CHAT_AUTHORIZATION_PLUGIN_NAME,
-    title: "Chat Access",
-    description:
-      "Controls who can talk to the agent through chat platforms, records observed users and chats, and resolves each user's effective role for downstream service decisions.",
-    availability() {
-      return {
-        enabled: true,
-        available: true,
-        reasons: [],
-      };
-    },
-    hooks: {
-      guard: {
-        [CHAT_PLUGIN_POINTS.authorizeIncoming]: [
-          async ({ context, value }) => {
-            const input =
-              value && typeof value === "object" && !Array.isArray(value)
-                ? (value as Record<string, unknown>)
-                : {};
-            const evaluateInput = toEvaluateInput(input);
-            const authorizationConfig = readChatAuthorizationConfig(context);
-            const result = evaluateIncomingChatAuthorization({
-              config: context.config,
-              channel: evaluateInput.channel,
-              input: evaluateInput,
-              authorizationConfig,
-            });
-            if (result.decision !== "allow") {
-              throw new Error(result.reason || "chat authorization blocked");
-            }
-          },
-        ],
-      },
-      effect: {
-        [CHAT_PLUGIN_POINTS.observePrincipal]: [
-          async ({ context, value }) => {
-            const input = toRecord(
-              value,
-            ) as unknown as ChatAuthorizationObservePrincipalPayload;
-            const channel = toChannel(input.channel);
-            if (!channel) {
-              throw new Error("chat.observePrincipal requires a valid channel");
-            }
-            await recordObservedAuthorizationPrincipal({
-              context,
-              channel,
-              chatId: String(input.chatId || "").trim(),
-              ...(typeof input.chatType === "string"
-                ? { chatType: input.chatType.trim() }
-                : {}),
-              ...(typeof input.chatTitle === "string"
-                ? { chatTitle: input.chatTitle.trim() }
-                : {}),
-              ...(typeof input.userId === "string"
-                ? { userId: input.userId.trim() }
-                : {}),
-              ...(typeof input.username === "string"
-                ? { username: input.username.trim() }
-                : {}),
-            });
-          },
-        ],
-      },
-    },
-    resolves: {
-      [CHAT_PLUGIN_POINTS.resolveUserRole]: async ({ context, value }) => {
-        const input =
-          value && typeof value === "object" && !Array.isArray(value)
-            ? (value as Record<string, unknown>)
-            : {};
-        const channel = toChannel(input.channel);
-        if (!channel) {
-          throw new Error("chat.resolveUserRole requires a valid channel");
-        }
-        const role = resolveAuthorizedUserRole({
-          channel,
-          userId: String(input.userId || "").trim(),
-          rootPath: context.rootPath,
-        });
-        return ((role || null) as unknown) as JsonValue;
-      },
-    },
-    actions: {
-      [CHAT_AUTHORIZATION_ACTIONS.snapshot]: {
-        execute: async ({ context }) => {
-          const snapshot = await readAuthorizationSnapshot({
-            context,
-          });
-          return {
-            success: true,
-            data: toSnapshotData(snapshot),
-          };
-        },
-      },
-      [CHAT_AUTHORIZATION_ACTIONS.readConfig]: {
-        execute: async ({ context }) => {
-          return {
-            success: true,
-            data: readChatAuthorizationConfig(context) as unknown as JsonValue,
-          };
-        },
-      },
-      [CHAT_AUTHORIZATION_ACTIONS.writeConfig]: {
-        execute: async ({ context, payload }) => {
-          const body = toRecord(
-            payload,
-          ) as unknown as ChatAuthorizationWriteConfigPayload;
-          const nextConfig =
-            body.config && typeof body.config === "object" && !Array.isArray(body.config)
-              ? (body.config as ChatAuthorizationConfig)
-              : {};
-          await writeChatAuthorizationConfig({
-            context,
-            nextConfig,
-          });
-          return {
-            success: true,
-            data: readChatAuthorizationConfig(context) as unknown as JsonValue,
-          };
-        },
-      },
-      [CHAT_AUTHORIZATION_ACTIONS.setUserRole]: {
-        execute: async ({ context, payload }) => {
-          const body = toRecord(
-            payload,
-          ) as unknown as ChatAuthorizationSetUserRolePayload;
-          const channel = toChannel(body.channel);
-          if (!channel) {
-            return {
-              success: false,
-              error: "set-user-role requires a valid channel",
-              message: "set-user-role requires a valid channel",
-            };
-          }
-          await setChatAuthorizationUserRole({
-            context,
-            channel,
-            userId: String(body.userId || "").trim(),
-            roleId: String(body.roleId || "").trim(),
-          });
-          return {
-            success: true,
-            data: readChatAuthorizationConfig(context) as unknown as JsonValue,
-          };
-        },
-      },
-    },
-  };
-}
-
-/**
- * ChatAuthorizationPlugin：统一承载聊天用户授权能力。
- */
-export class ChatAuthorizationPlugin extends BasePlugin {
-  readonly name = CHAT_AUTHORIZATION_PLUGIN_NAME;
-
-  constructor() {
-    super();
-    Object.assign(this, createChatAuthorizationPluginDefinition());
-  }
-}