@downcity/agent 1.1.8 → 1.1.10

package/src/plugin/builtins/skill/runtime/Store.ts

@@ -0,0 +1,95 @@
+/**
+ * Session skills state store（skill plugin 内部状态）。
+ *
+ * 关键点（中文）
+ * - 这是 skill 子系统的运行时状态容器
+ * - core 不负责也不感知 skill/memory 业务状态
+ */
+
+import type { ClaudeSkill } from "@/plugin/builtins/skill/types/ClaudeSkill.js";
+import type {
+  SessionSkillStateInternal,
+  SessionSkillStateSnapshot,
+} from "./Types.js";
+
+const sessionSkillStateStore = new Map<string, SessionSkillStateInternal>();
+
+/**
+ * 归一化 sessionId。
+ *
+ * 关键点（中文）
+ * - 空 sessionId 视为调用错误，直接抛异常，避免污染全局状态。
+ */
+function normalizeSessionId(sessionId: string): string {
+  const value = String(sessionId || "").trim();
+  if (!value) {
+    throw new Error("sessionId is required for session skills state");
+  }
+  return value;
+}
+
+/**
+ * 获取或创建 session 技能状态。
+ */
+function getOrCreateState(sessionId: string): SessionSkillStateInternal {
+  const key = normalizeSessionId(sessionId);
+  const existing = sessionSkillStateStore.get(key);
+  if (existing) return existing;
+
+  const created: SessionSkillStateInternal = {
+    allSkillsById: new Map(),
+    updatedAt: Date.now(),
+  };
+  sessionSkillStateStore.set(key, created);
+  return created;
+}
+
+/**
+ * 设置会话可用技能集合。
+ *
+ * 算法（中文）
+ * - 以 id 归一化后整体替换，避免残留脏状态。
+ */
+export function setSessionAvailableSkills(sessionId: string, skills: ClaudeSkill[]): void {
+  const state = getOrCreateState(sessionId);
+  const next = new Map<string, ClaudeSkill>();
+
+  for (const skill of Array.isArray(skills) ? skills : []) {
+    const id = String(skill?.id || "").trim();
+    if (!id) continue;
+    next.set(id, skill);
+  }
+
+  state.allSkillsById = next;
+  state.updatedAt = Date.now();
+}
+
+/**
+ * 获取会话技能状态快照。
+ */
+export function getSessionSkillState(sessionId: string): SessionSkillStateSnapshot {
+  const key = normalizeSessionId(sessionId);
+  const state = sessionSkillStateStore.get(key);
+
+  if (!state) {
+    return {
+      sessionId: key,
+      allSkills: [],
+      updatedAt: 0,
+    };
+  }
+
+  return {
+    sessionId: key,
+    allSkills: Array.from(state.allSkillsById.values()),
+    updatedAt: state.updatedAt,
+  };
+}
+
+/**
+ * 清理会话技能状态。
+ */
+export function clearSessionSkillState(sessionId: string): void {
+  const key = normalizeSessionId(sessionId);
+  sessionSkillStateStore.delete(key);
+}

package/src/plugin/builtins/skill/runtime/SystemProvider.ts

@@ -0,0 +1,52 @@
+/**
+ * Skill plugin system 文本构建器。
+ *
+ * 关键点（中文）
+ * - 只负责输出“可用技能概览”提示词
+ * - 不再读取/写入 pinnedSkillIds，不做会话级技能注入
+ * - `lookup` 行为为无状态：由 action 读取 SKILL.md 后通过协议注入 user message
+ */
+
+import { getSessionRunScope } from "@session/SessionRunScope.js";
+import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
+import { discoverClaudeSkillsSync } from "./Discovery.js";
+import { renderClaudeSkillsPromptSection } from "./Prompt.js";
+import { setSessionAvailableSkills } from "./Store.js";
+
+type SkillSystemRuntime = {
+  rootPath: string;
+  config: DowncityConfig;
+};
+
+function getCurrentSessionId(): string {
+  const request = getSessionRunScope();
+  return String(request?.sessionId || "").trim();
+}
+
+/**
+ * 构建 skill plugin system 文本。
+ *
+ * 算法流程（中文）
+ * 1) 扫描可用 skills
+ * 2) 更新 session 的可用技能快照（仅用于观察态）
+ * 3) 输出 skills overview 文本
+ */
+export async function buildSkillsSystemText(
+  runtime: SkillSystemRuntime,
+): Promise<string> {
+  const sessionId = getCurrentSessionId();
+  const discoveredSkills = discoverClaudeSkillsSync(
+    runtime.rootPath,
+    runtime.config,
+  );
+
+  if (sessionId) {
+    setSessionAvailableSkills(sessionId, discoveredSkills);
+  }
+
+  return renderClaudeSkillsPromptSection(
+    runtime.rootPath,
+    runtime.config,
+    discoveredSkills,
+  ).trim();
+}

package/src/plugin/builtins/skill/runtime/Types.ts

@@ -0,0 +1,22 @@
+import type { ClaudeSkill } from "@/plugin/builtins/skill/types/ClaudeSkill.js";
+
+/**
+ * Session skills state 对外快照。
+ *
+ * 关键点（中文）
+ * - 这是 service 侧暴露给调试/观察的只读结构
+ * - core 不依赖该结构
+ */
+export type SessionSkillStateSnapshot = {
+  sessionId: string;
+  allSkills: ClaudeSkill[];
+  updatedAt: number;
+};
+
+/**
+ * Session skills state 内部结构。
+ */
+export type SessionSkillStateInternal = {
+  allSkillsById: Map<string, ClaudeSkill>;
+  updatedAt: number;
+};

package/src/plugin/builtins/skill/types/ClaudeSkill.ts

@@ -0,0 +1,64 @@
+/**
+ * Claude Code-compatible skill 模型。
+ *
+ * 关键点（中文）
+ * - skill 最小单元目录为 `<root>/<skill-id>/SKILL.md`。
+ * - 发现逻辑只读取 `SKILL.md` front matter 作为元数据。
+ * - 该类型为 skill plugin、CLI 与内部辅助模块的共享事实源。
+ */
+
+import type { SkillRootSource } from "@/plugin/builtins/skill/types/SkillRoot.js";
+import type { JsonValue } from "@/utils/types/Json.js";
+
+/**
+ * Claude Code-compatible skill。
+ */
+export interface ClaudeSkill {
+  /**
+   * skill 稳定标识。
+   *
+   * 说明（中文）
+   * - 通常等于 skill 目录名。
+   * - 用于 lookup、去重与排序。
+   */
+  id: string;
+  /**
+   * skill 展示名称。
+   *
+   * 说明（中文）
+   * - 优先读取 front matter 中的 `name`。
+   * - 若未声明，则回退为 `id`。
+   */
+  name: string;
+  /**
+   * skill 简要描述。
+   *
+   * 说明（中文）
+   * - 来自 front matter 的 `description`。
+   * - 未声明时为空字符串。
+   */
+  description: string;
+  /**
+   * skill 根目录来源类型。
+   */
+  source: SkillRootSource;
+  /**
+   * skill 所属根目录的绝对路径。
+   */
+  sourceRoot: string;
+  /**
+   * skill 目录的绝对路径。
+   */
+  directoryPath: string;
+  /**
+   * `SKILL.md` 文件的绝对路径。
+   */
+  skillMdPath: string;
+  /**
+   * front matter 中的 `allowed-tools` 原始值。
+   *
+   * 说明（中文）
+   * - 这里保留原始 JSON 结构，归一化工作交给上层调用方。
+   */
+  allowedTools?: JsonValue;
+}

package/src/plugin/builtins/tts/Dependency.ts

@@ -0,0 +1,473 @@
+/**
+ * TTS Plugin Dependency Helper。
+ *
+ * 关键点（中文）
+ * - TTS 的模型安装、配置读写与可用性检查都内聚在 plugin 内部。
+ * - Console 只调用 plugin action，不直接理解底层资源结构。
+ */
+
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { PluginCommandContext } from "@/plugin/types/Plugin.js";
+import type {
+  TtsInstallInput,
+  TtsPluginConfig,
+} from "@/plugin/builtins/tts/types/TtsPlugin.js";
+import type { TtsModelId } from "@/plugin/builtins/tts/types/Tts.js";
+import {
+  getTtsModelCatalogItem,
+  resolveTtsModelId,
+  TTS_MODEL_CATALOG,
+} from "@/plugin/builtins/tts/runtime/Catalog.js";
+import {
+  detectLocalTtsModelInstallState,
+  installTtsModelFromHuggingFace,
+} from "@/plugin/builtins/tts/runtime/Installer.js";
+import {
+  ensureTtsVirtualEnv,
+  installTtsDependencies,
+  resolveDefaultTtsVenvPythonBin,
+  resolveTtsRunnersByModels,
+} from "@/plugin/builtins/tts/runtime/DependencyInstaller.js";
+import { resolveTtsModelsRootDir } from "@/plugin/builtins/tts/runtime/Paths.js";
+
+const execFileAsync = promisify(execFileCb);
+
+type PythonVersionInfo = {
+  major: number;
+  minor: number;
+  patch: number;
+  raw: string;
+};
+
+export interface TtsDependencyCheckResult {
+  /**
+   * 当前依赖是否可用。
+   */
+  available: boolean;
+  /**
+   * 不可用原因列表。
+   */
+  reasons: string[];
+  /**
+   * 结构化附加数据（可选）。
+   */
+  details?: JsonValue;
+}
+
+export interface TtsDependencyInstallResult {
+  /**
+   * 安装是否成功。
+   */
+  success: boolean;
+  /**
+   * 人类可读消息（可选）。
+   */
+  message?: string;
+  /**
+   * 结构化附加数据（可选）。
+   */
+  details?: JsonValue;
+}
+
+function readTtsPluginRecord(context: PluginCommandContext): Record<string, unknown> {
+  const current = context.config.plugins?.tts;
+  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;
+}
+
+function normalizeFormat(value: unknown): "wav" | "flac" {
+  return String(value || "").trim().toLowerCase() === "flac" ? "flac" : "wav";
+}
+
+function normalizeTtsPythonBin(value: unknown): string {
+  const text = String(value || "").trim();
+  if (!text || text === "python3") {
+    return resolveDefaultTtsVenvPythonBin();
+  }
+  return text;
+}
+
+async function readPythonVersionInfo(pythonBin: string): Promise<PythonVersionInfo | null> {
+  try {
+    const { stdout, stderr } = await execFileAsync(pythonBin, ["--version"], {
+      timeout: 15_000,
+      maxBuffer: 1024 * 1024,
+    });
+    const text = String(stdout || stderr || "").trim();
+    const match = text.match(/Python\s+(\d+)\.(\d+)\.(\d+)/i);
+    if (!match) return null;
+    return {
+      major: Number(match[1]),
+      minor: Number(match[2]),
+      patch: Number(match[3]),
+      raw: text,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function getTtsPythonCompatibilityReason(params: {
+  modelId: TtsModelId;
+  version: PythonVersionInfo | null;
+}): string | null {
+  if (!params.version) return null;
+  if (params.modelId === "kokoro-82m") {
+    if (params.version.major > 3 || (params.version.major === 3 && params.version.minor >= 13)) {
+      return `kokoro-82m currently requires Python < 3.13, current is ${params.version.major}.${params.version.minor}.${params.version.patch}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * 读取 TTS Plugin 配置。
+ */
+export function readTtsPluginConfig(context: PluginCommandContext): TtsPluginConfig {
+  const { enabled: _ignoredEnabled, ...current } = readTtsPluginRecord(context) as Record<
+    string,
+    unknown
+  > & {
+    enabled?: boolean;
+  };
+  return {
+    provider: "local",
+    ...(typeof current.modelId === "string" ? { modelId: current.modelId } : {}),
+    ...(typeof current.modelsDir === "string" ? { modelsDir: current.modelsDir } : {}),
+    pythonBin: normalizeTtsPythonBin(current.pythonBin),
+    ...(typeof current.language === "string" ? { language: current.language } : {}),
+    ...(typeof current.voice === "string" ? { voice: current.voice } : {}),
+    ...(typeof current.outputDir === "string" ? { outputDir: current.outputDir } : {}),
+    ...(typeof current.timeoutMs === "number" ? { timeoutMs: current.timeoutMs } : {}),
+    ...(typeof current.speed === "number" ? { speed: current.speed } : {}),
+    format: normalizeFormat(current.format),
+    ...(Array.isArray(current.installedModels)
+      ? { installedModels: current.installedModels }
+      : {}),
+  };
+}
+
+/**
+ * 写入完整 TTS plugin 配置。
+ */
+export async function writeTtsPluginConfig(params: {
+  /**
+   * 当前执行上下文。
+   */
+  context: PluginCommandContext;
+  /**
+   * 目标配置值。
+   */
+  value: TtsPluginConfig;
+}): Promise<TtsPluginConfig> {
+  if (!params.context.config.plugins) {
+    params.context.config.plugins = {};
+  }
+  const next: Record<string, unknown> = {
+    ...(params.value as Record<string, unknown>),
+  };
+  delete next.enabled;
+  params.context.config.plugins.tts = toJsonObject(next);
+  await params.context.pluginConfig.persistProjectPlugins(params.context.config.plugins);
+  return params.context.config.plugins.tts as TtsPluginConfig;
+}
+
+async function checkPythonPackageImports(params: {
+  pythonBin: string;
+  modelId: TtsModelId;
+}): Promise<string | null> {
+  const importScript =
+    params.modelId === "qwen3-tts-0.6b"
+      ? "import qwen_tts, soundfile"
+      : "import kokoro, soundfile";
+  try {
+    await execFileAsync(params.pythonBin, ["-c", importScript], {
+      timeout: 30_000,
+      maxBuffer: 1024 * 1024,
+    });
+    return null;
+  } catch (error) {
+    return `python packages missing: ${String(error)}`;
+  }
+}
+
+/**
+ * 检查 TTS 依赖可用性。
+ */
+export async function checkTtsSynthesizer(
+  context: PluginCommandContext,
+): Promise<TtsDependencyCheckResult> {
+  const config = readTtsPluginConfig(context);
+  const reasons: string[] = [];
+  const modelId = resolveTtsModelId(String(config.modelId || ""));
+  if (!modelId) {
+    reasons.push("tts modelId is missing");
+    return {
+      available: false,
+      reasons,
+    };
+  }
+
+  const modelsRootDir = resolveTtsModelsRootDir({
+    projectRoot: context.rootPath,
+    modelsDir: config.modelsDir,
+  });
+  const installState = await detectLocalTtsModelInstallState({
+    modelId,
+    modelsRootDir,
+  });
+  if (!installState.installed) {
+    reasons.push(`tts model is not installed: ${modelId}`);
+  }
+
+  const pythonBin = normalizeTtsPythonBin(config.pythonBin);
+  const pythonVersion = await readPythonVersionInfo(pythonBin);
+  if (!pythonVersion) {
+    reasons.push(`python runtime missing: ${pythonBin}`);
+    return {
+      available: false,
+      reasons,
+    };
+  }
+
+  const compatibilityReason = getTtsPythonCompatibilityReason({
+    modelId,
+    version: pythonVersion,
+  });
+  if (compatibilityReason) {
+    reasons.push(compatibilityReason);
+    return {
+      available: false,
+      reasons,
+      details: {
+        modelDir: installState.modelDir,
+        source: installState.source || null,
+        pythonVersion: pythonVersion.raw,
+      },
+    };
+  }
+
+  const importError = await checkPythonPackageImports({
+    pythonBin,
+    modelId,
+  });
+  if (importError) {
+    reasons.push(importError);
+  }
+
+  return {
+    available: reasons.length === 0,
+    reasons,
+    details: {
+      modelDir: installState.modelDir,
+      source: installState.source || null,
+    },
+  };
+}
+
+/**
+ * 安装或修复 TTS 依赖。
+ */
+export async function installTtsSynthesizer(params: {
+  /**
+   * 当前执行上下文。
+   */
+  context: PluginCommandContext;
+  /**
+   * 安装输入（可选）。
+   */
+  input?: TtsInstallInput;
+}): Promise<TtsDependencyInstallResult> {
+  const context = params.context;
+  const input = params.input;
+  const config = readTtsPluginConfig(context);
+  const logs: string[] = [];
+
+  const requestedModelIds =
+    (Array.isArray(input?.modelIds) ? input.modelIds : [])
+      .map((item) => resolveTtsModelId(String(item || "").trim()))
+      .filter((item): item is TtsModelId => Boolean(item));
+  const selectedModelIds: TtsModelId[] =
+    requestedModelIds.length > 0
+      ? requestedModelIds
+      : [resolveTtsModelId(String(config.modelId || "qwen3-tts-0.6b")) || "qwen3-tts-0.6b"];
+
+  const modelsRootDir = resolveTtsModelsRootDir({
+    projectRoot: context.rootPath,
+    modelsDir: input?.modelsDir || config.modelsDir,
+  });
+  logs.push(`models dir: ${modelsRootDir}`);
+
+  const installResults: JsonObject[] = [];
+  for (const modelId of selectedModelIds) {
+    logs.push(`prepare model: ${modelId}`);
+    const model = getTtsModelCatalogItem(modelId);
+    if (!model) {
+      throw new Error(`Unsupported tts model: ${modelId}`);
+    }
+    const installState = await detectLocalTtsModelInstallState({
+      modelId,
+      modelsRootDir,
+    });
+    if (!installState.installed || input?.force === true) {
+      logs.push(
+        installState.installed && input?.force === true
+          ? `redownload model: ${modelId}`
+          : `download model: ${modelId}`,
+      );
+      const result = await installTtsModelFromHuggingFace({
+        model,
+        modelsRootDir,
+        force: input?.force === true,
+        hfToken: input?.hfToken,
+      });
+      logs.push(
+        `model ready: ${modelId} (downloaded ${result.downloadedFiles}, skipped ${result.skippedFiles})`,
+      );
+      installResults.push(toJsonObject({
+        modelId,
+        downloadedFiles: result.downloadedFiles,
+        skippedFiles: result.skippedFiles,
+      }));
+      continue;
+    }
+    logs.push(`reuse installed model: ${modelId}`);
+    installResults.push(toJsonObject({
+      modelId,
+      downloadedFiles: 0,
+      skippedFiles: 0,
+      reused: true,
+    }));
+  }
+
+  const basePythonBin = String(input?.pythonBin || "").trim() || "python3";
+  const basePythonVersion = await readPythonVersionInfo(basePythonBin);
+  let resolvedPythonBin = normalizeTtsPythonBin(config.pythonBin);
+  let dependencyDetails: JsonValue | undefined;
+  const compatibilityFailures = selectedModelIds
+    .map((modelId) => getTtsPythonCompatibilityReason({
+      modelId,
+      version: basePythonVersion,
+    }))
+    .filter((item): item is string => Boolean(item));
+  if (compatibilityFailures.length > 0) {
+    logs.push(...compatibilityFailures);
+    return {
+      success: false,
+      message: compatibilityFailures.join(" · "),
+      details: {
+        pythonVersion: basePythonVersion?.raw || basePythonBin,
+        logs,
+      },
+    };
+  }
+  if (input?.installDeps !== false) {
+    logs.push(`prepare python env from: ${basePythonBin}`);
+    const dependencyResult = await installTtsDependencies({
+      pythonBin: basePythonBin,
+      runners: resolveTtsRunnersByModels(selectedModelIds),
+    });
+    resolvedPythonBin = dependencyResult.pythonBin;
+    logs.push(`python env ready: ${dependencyResult.pythonBin}`);
+    for (const item of dependencyResult.items) {
+      logs.push(
+        item.skipped
+          ? `dependency ${item.runner}: already installed`
+          : `dependency ${item.runner}: installed`,
+      );
+    }
+    dependencyDetails = toJsonObject({
+      pythonBin: dependencyResult.pythonBin,
+      runners: dependencyResult.runners,
+      usedVirtualEnv: dependencyResult.usedVirtualEnv,
+      venvDir: dependencyResult.venvDir,
+    });
+  } else {
+    logs.push(`prepare python env only: ${basePythonBin}`);
+    resolvedPythonBin = await ensureTtsVirtualEnv({
+      basePythonBin,
+    });
+    logs.push(`python env ready: ${resolvedPythonBin}`);
+  }
+
+  const activeModelId =
+    resolveTtsModelId(String(input?.activeModel || "")) || selectedModelIds[0];
+  const nextConfig = await writeTtsPluginConfig({
+    context,
+    value: {
+      ...config,
+      provider: "local",
+      modelId: activeModelId,
+      modelsDir: modelsRootDir,
+      pythonBin: resolvedPythonBin,
+      format: normalizeFormat(input?.format || config.format),
+      installedModels: selectedModelIds,
+    },
+  });
+
+  return {
+    success: true,
+    message: "tts synthesizer installed",
+    details: {
+      plugin: toJsonObject(nextConfig as Record<string, unknown>),
+      models: installResults,
+      dependency: dependencyDetails || null,
+      logs,
+    },
+  };
+}
+
+/**
+ * 列出可用于 TTS 的内置模型选项。
+ */
+export function listTtsModelOptions(): Array<{
+  /**
+   * 选项标签。
+   */
+  label: string;
+  /**
+   * 选项值。
+   */
+  value: string;
+  /**
+   * 选项说明。
+   */
+  hint: string;
+}> {
+  return TTS_MODEL_CATALOG.map((item) => ({
+    label: item.label,
+    value: item.id,
+    hint: item.description,
+  }));
+}