@downcity/plugins 1.0.174 → 1.0.193

package/src/chat/types/ChatStorage.ts

@@ -0,0 +1,37 @@
+/**
+ * Chat Plugin 存储维护类型。
+ *
+ * 关键点（中文）
+ * - 这些类型只描述 Chat Plugin 自己的持久化数据维护能力。
+ * - Agent、Server 与 CLI 不需要知道 channel meta 或 chat history 的实际目录结构。
+ */
+
+/**
+ * 清理单个 Chat 会话存储的输入。
+ */
+export interface ChatStorageCleanInput {
+  /** 当前 Agent 项目根目录。 */
+  root_path: string;
+  /** 已知的 Session 标识；提供时优先使用。 */
+  session_id?: string;
+  /** Chat 渠道名称；未提供 Session 标识时用于解析目标会话。 */
+  channel?: string;
+  /** Chat 渠道目标标识；未提供 Session 标识时用于解析目标会话。 */
+  chat_id?: string;
+  /** 可选的 Chat 目标类型，用于缩小路由匹配范围。 */
+  target_type?: string;
+  /** 可选的消息线程标识，用于缩小路由匹配范围。 */
+  thread_id?: number;
+}
+
+/**
+ * 清理单个 Chat 会话存储的结果。
+ */
+export interface ChatStorageCleanResult {
+  /** 最终解析出的 Session 标识；未找到目标时为空字符串。 */
+  session_id: string;
+  /** 是否删除了 Chat 事件目录。 */
+  removed_chat_dir: boolean;
+  /** 是否从 channel meta 中删除了路由映射。 */
+  removed_route: boolean;
+}

package/src/contact/Action.ts

@@ -9,6 +9,7 @@
 import type { AgentContext } from "@downcity/agent";
 import type { JsonObject, JsonValue } from "@downcity/agent";
 import type { PluginActions } from "@downcity/agent";
+import type { PluginRunContext } from "@downcity/agent";
 import { createAction } from "@downcity/agent";
 import { z } from "zod";
 import type {
@@ -44,13 +45,18 @@ export type ContactActionHandlers = {
   /**
    * 生成一次性联系码。
    */
-  link: (context: AgentContext, payload: ContactLinkCommandPayload) => Promise<JsonValue>;
+  link: (
+    context: AgentContext,
+    payload: ContactLinkCommandPayload,
+    run_context?: PluginRunContext,
+  ) => Promise<JsonValue>;
   /**
    * 使用联系码建立 contact。
    */
   approve: (
     context: AgentContext,
     payload: ContactApproveCommandPayload,
+    run_context?: PluginRunContext,
   ) => Promise<JsonValue>;
   /**
    * 检查 contact 或 endpoint 可用性。
@@ -124,6 +130,7 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         data: await handlers.link(
           params.context,
           params.input as ContactLinkCommandPayload,
+          params.run_context,
         ),
       }),
     }),
@@ -166,6 +173,7 @@ export function createContactActions(handlers: ContactActionHandlers): PluginAct
         data: await handlers.approve(
           params.context,
           params.input as unknown as ContactApproveCommandPayload,
+          params.run_context,
         ),
       }),
     }),

package/src/contact/ContactPlugin.ts

@@ -8,6 +8,7 @@
  */
 
 import type { AgentContext } from "@downcity/agent";
+import type { PluginRunContext } from "@downcity/agent";
 import type { JsonValue } from "@downcity/agent";
 import type { PluginActions } from "@downcity/agent";
 import { BasePlugin } from "@downcity/agent";
@@ -82,32 +83,40 @@ import {
 
 async function resolveSelfEndpoint(
   context: AgentContext,
+  options: ContactPluginOptions,
   endpointOverride?: string,
+  effective_env?: Readonly<Record<string, string>>,
 ): Promise<string> {
   const explicit = String(endpointOverride || "").trim();
   if (explicit) return normalizeContactEndpoint(explicit);
-  const start = context.config.start || {};
   const env = {
     ...process.env,
     ...context.env,
+    ...effective_env,
   };
   const runtimePort = Number(process.env.DC_CITY_PORT || env.DC_CITY_PORT || "");
   // 关键点（中文）：link code 必须写入当前 runtime 的真实监听端口，不能使用可能已经过期的配置端口。
-  const port = Number.isFinite(runtimePort) && runtimePort > 0 ? runtimePort : start.port;
+  const port = Number.isFinite(runtimePort) && runtimePort > 0
+    ? runtimePort
+    : options.port;
   const runtimeHost = String(process.env.DC_CITY_HOST || env.DC_CITY_HOST || "").trim();
   return normalizeContactEndpoint(
     await resolveContactSelfEndpoint({
-      host: runtimeHost || start.host,
+      host: runtimeHost || options.host,
       port,
       env,
     }),
   );
 }
 
-function hasRuntimePublicEndpointEnv(context: AgentContext): boolean {
+function hasRuntimePublicEndpointEnv(
+  context: AgentContext,
+  effective_env?: Readonly<Record<string, string>>,
+): boolean {
   const env = {
     ...process.env,
     ...context.env,
+    ...effective_env,
   };
   return Boolean(
     String(env.DOWNCITY_PUBLIC_URL || "").trim() ||
@@ -116,7 +125,7 @@ function hasRuntimePublicEndpointEnv(context: AgentContext): boolean {
 }
 
 function getAgentName(context: AgentContext): string {
-  return String(context.config.id || "downcity-agent").trim() || "downcity-agent";
+  return String(context.agent_id || "downcity-agent").trim() || "downcity-agent";
 }
 
 function requireOutboundContact(contact: AgentContact): {
@@ -155,10 +164,10 @@ export class ContactPlugin extends BasePlugin {
     super();
     this.options = options || {};
     this.actions = createContactActions({
-      link: async (context, payload) =>
-        (await this.link(context, payload)) as unknown as JsonValue,
-      approve: async (context, payload) =>
-        (await this.approve(context, payload)) as unknown as JsonValue,
+      link: async (context, payload, run_context) =>
+        (await this.link(context, payload, run_context)) as unknown as JsonValue,
+      approve: async (context, payload, run_context) =>
+        (await this.approve(context, payload, run_context)) as unknown as JsonValue,
       check: async (context, payload) =>
         (await this.check(context, payload)) as unknown as JsonValue,
       chat: async (context, payload) =>
@@ -180,7 +189,11 @@ export class ContactPlugin extends BasePlugin {
     return buildContactPluginSystemText();
   }
 
-  private async link(context: AgentContext, payload: ContactLinkCommandPayload) {
+  private async link(
+    context: AgentContext,
+    payload: ContactLinkCommandPayload,
+    run_context?: PluginRunContext,
+  ) {
     const now = Date.now();
     const ttlSeconds = Math.max(
       60,
@@ -190,7 +203,9 @@ export class ContactPlugin extends BasePlugin {
     const secret = createContactToken();
     const endpoint = await resolveSelfEndpoint(
       context,
+      this.options,
       payload.endpoint || this.options.endpoint,
+      run_context?.agentEnv,
     );
     const agentName = getAgentName(context);
 
@@ -224,7 +239,11 @@ export class ContactPlugin extends BasePlugin {
     };
   }
 
-  private async approve(context: AgentContext, payload: ContactApproveCommandPayload) {
+  private async approve(
+    context: AgentContext,
+    payload: ContactApproveCommandPayload,
+    run_context?: PluginRunContext,
+  ) {
     const parsed = parseContactLinkCode(payload.code);
     // 关键点（中文）：approve 端不使用本机时钟预判过期，避免两台机器时钟不一致时把本来可用的 link 提前拦截。
     // 是否过期统一交给 link 持有方在远端按本地记录判断。
@@ -232,11 +251,16 @@ export class ContactPlugin extends BasePlugin {
     const targetReachability = classifyContactEndpoint(parsed.endpoint);
     const shouldResolveRequesterEndpoint =
       payload.endpoint ||
-      hasRuntimePublicEndpointEnv(context) ||
+      hasRuntimePublicEndpointEnv(context, run_context?.agentEnv) ||
       targetReachability === "loopback" ||
       targetReachability === "private";
     const requesterEndpointCandidate = shouldResolveRequesterEndpoint
-      ? await resolveSelfEndpoint(context, payload.endpoint || this.options.endpoint)
+      ? await resolveSelfEndpoint(
+          context,
+          this.options,
+          payload.endpoint || this.options.endpoint,
+          run_context?.agentEnv,
+        )
       : undefined;
     const callbackDecision = buildContactApproveCallbackDecision({
       targetEndpoint: parsed.endpoint,
@@ -458,7 +482,7 @@ export class ContactPlugin extends BasePlugin {
     return await approveContactLinkRequest({
       projectRoot: context.rootPath,
       ownerAgentName: getAgentName(context),
-      ownerEndpoint: await resolveSelfEndpoint(context),
+      ownerEndpoint: await resolveSelfEndpoint(context, this.options),
       request,
     });
   }

package/src/contact/runtime/ChatRuntime.ts

@@ -64,7 +64,7 @@ export async function receiveContactChatMessage(params: {
   });
 
   const sessionId = `contact_${contact.id}`;
-  const turn = await params.context.session.get(sessionId).prompt({
+  const turn = await params.context.sessions.runtime(sessionId).prompt({
     query: params.message,
   });
   const result = await turn.finished;

package/src/contact/types/ContactPluginOptions.ts

@@ -19,6 +19,12 @@ export interface ContactPluginOptions {
    */
   endpoint?: string;
 
+  /** 当前 Agent HTTP runtime 的监听 host。 */
+  host?: string;
+
+  /** 当前 Agent HTTP runtime 的监听 port。 */
+  port?: number;
+
   /**
    * 默认 link 有效秒数。
    *

package/src/index.ts

@@ -26,8 +26,7 @@ export { ImagePlugin } from "./image/ImagePlugin.js";
 export { ChatChannelAccountManager } from "./chat/accounts/ChannelAccountManager.js";
 export { SkillPlugin } from "./skill/Plugin.js";
 export { WebPlugin } from "./web/Plugin.js";
-export { AsrPlugin } from "./asr/Plugin.js";
-export { TtsPlugin } from "./tts/Plugin.js";
+export { SoundPlugin } from "./sound/Plugin.js";
 export { WorkboardPlugin } from "./workboard/Plugin.js";
 export { TaskPlugin } from "./task/TaskPlugin.js";
 export { MemoryPlugin } from "./memory/MemoryPlugin.js";
@@ -39,10 +38,15 @@ export {
 } from "./chat/access/ChatAccessService.js";
 export { get_chat_access_db_path } from "./chat/access/ChatAccessStore.js";
 export { CHAT_ACCESS_ACTIONS } from "./chat/types/ChatAccess.js";
+export { clean_chat_storage } from "./chat/runtime/ChatStorage.js";
 
 export type {
   ChatChannelAccountListItem,
 } from "./chat/types/ChannelAccount.js";
+export type {
+  ChatStorageCleanInput,
+  ChatStorageCleanResult,
+} from "./chat/types/ChatStorage.js";
 export type {
   BaseChatChannelOptions,
   ChatChannelEnv,
@@ -52,7 +56,6 @@ export type {
 } from "./chat/channels/RuntimeChannel.js";
 export type {
   ChatChannel,
-  ChatChannelRuntimePatch,
   ChatPluginOptions,
 } from "./chat/types/ChatPluginOptions.js";
 export type { ContactPluginOptions } from "./contact/types/ContactPluginOptions.js";
@@ -85,17 +88,16 @@ export type {
   MemoryWikiPageDraft,
 } from "./memory/types/Memory.js";
 export type {
-  AsrPluginInput,
-  AsrPluginOptions,
-  AsrPluginResult,
-} from "./asr/types/AsrPlugin.js";
-export type {
-  TtsPluginInput,
-  TtsPluginOptions,
-  TtsPluginResult,
-  TtsPluginSimpleAudioResult,
-  TtsPluginUiMessageResult,
-} from "./tts/types/TtsPlugin.js";
+  SoundPluginAsrInput,
+  SoundPluginAsrResult,
+  SoundPluginAsrSegment,
+  SoundPluginCapability,
+  SoundPluginModel,
+  SoundPluginModelsResult,
+  SoundPluginOptions,
+  SoundPluginTtsInput,
+  SoundPluginTtsResult,
+} from "./sound/types/SoundPlugin.js";
 export type {
   ImagePluginContent,
   ImagePluginDefaultModel,

package/src/memory/Action.ts

@@ -12,6 +12,7 @@ import { isTextUIPart } from "ai";
 import type { PluginActionResult } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type { JsonValue } from "@downcity/agent";
+import type { SessionMessage } from "@downcity/agent";
 import type {
   MemoryDigestPayload,
   MemoryDigestResponse,
@@ -67,6 +68,20 @@ function extractReadableLine(message: unknown): string {
   return `${role}: ${text}`;
 }
 
+/** 从 canonical Session Message 提取 Memory digest 文本。 */
+function extract_session_message_line(message: SessionMessage): string {
+  if (message.type !== "user" && message.type !== "assistant") return "";
+  const role = message.type === "user" ? "User" : "Assistant";
+  const text = message.parts
+    .flatMap((part) =>
+      part.type === "text" ? [String(part.text || "").trim()] : [],
+    )
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+  return text ? `${role}: ${text}` : "";
+}
+
 function readDigestPages(result: Awaited<ReturnType<NonNullable<MemoryPluginOptions["digest"]>>>): {
   pages: Array<{ path?: string; title?: string; content: string; tags?: string[] }>;
   summary?: string;
@@ -267,12 +282,12 @@ export async function digestMemoryAction(
     const maxMessages = Number.isFinite(payload.maxMessages)
       ? Math.max(1, Math.floor(payload.maxMessages as number))
       : 30;
-    const historyStore = context.session.get(sessionId).getHistoryStore();
-    const total = await historyStore.record_count();
+    const snapshot = await context.sessions.runtime(sessionId).context();
+    const total = snapshot.messages.length;
     const start = Math.max(0, total - maxMessages);
-    const messages = await historyStore.slice_records(start, total);
+    const messages = snapshot.messages.slice(start);
     const lines = messages
-      .map((msg) => extractReadableLine(msg))
+      .map((message) => extract_session_message_line(message))
       .filter((line) => line.length > 0);
     const transcript =
       lines.length > 0

package/src/memory/runtime/Store.ts

@@ -143,33 +143,6 @@ export async function listMemorySourceFiles(
     );
   }
 
-  const sessionRootDir = path.join(rootPath, ".downcity", "session");
-  let sessions: Dirent[] = [];
-  try {
-    sessions = await fsp.readdir(sessionRootDir, { withFileTypes: true });
-  } catch {
-    sessions = [];
-  }
-  for (const sessionDir of sessions) {
-    if (!sessionDir.isDirectory() || sessionDir.isSymbolicLink()) {
-      continue;
-    }
-    const workingPath = path.join(
-      sessionRootDir,
-      sessionDir.name,
-      "memory",
-      "working.md",
-    );
-    if (!(await pathExists(workingPath))) {
-      continue;
-    }
-    out.push({
-      source: "working",
-      absPath: workingPath,
-      relPath: normalizeRelPath(rootPath, workingPath),
-    });
-  }
-
   return out;
 }
 

package/src/memory/runtime/Writer.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - `sources/` 保存原始证据，`wiki/` 保存整理后的长期记忆。
- * - 所有外部传入路径都必须限制在 `.downcity/memory` 或 session working memory 内。
+ * - 所有外部传入路径都必须限制在 Memory Plugin 自己的 `.downcity/memory` 目录内。
  * - 无 LLM 注入时使用 append fallback，保证 MemoryPlugin 仍然可用。
  */
 
@@ -83,11 +83,8 @@ function resolveAllowedReadPath(context: AgentContext, relPath: string): string
   }
   const absPath = path.resolve(context.rootPath, normalized);
   const memoryRoot = path.resolve(path.join(context.rootPath, ".downcity", "memory"));
-  const sessionRoot = path.resolve(context.paths.getDowncitySessionRootDirPath());
   const isMemoryPath = isWithin(memoryRoot, absPath);
-  const isWorkingPath =
-    isWithin(sessionRoot, absPath) && normalized.endsWith("/memory/working.md");
-  if (!isMemoryPath && !isWorkingPath) {
+  if (!isMemoryPath) {
     throw new Error("path is not allowed");
   }
   if (!normalized.toLowerCase().endsWith(".md")) {

package/src/skill/Command.ts

@@ -1,15 +1,12 @@
 /**
- * `downcity skill` 命令 helper。
+ * Skill 安装命令 helper。
  *
  * 设计目标（中文）
- * - 尽量不自建 registry：直接复用社区的 `npx skills` 生态（find/install）。
- * - 同时提供本地视角的 `list`：按 SkillPlugin 默认构造参数列出当前项目 skills。
+ * - 不自建 registry，直接复用社区的 `npx skills` 安装生态。
+ * - 当前 helper 由需要准备 skill 依赖的其他 plugin 复用，不作为 SkillPlugin action 暴露。
  */
 
-import path from "node:path";
 import { execa } from "execa";
-import { discoverSkillsSync } from "@/skill/runtime/Discovery.js";
-import { getSkillSearchRoots } from "@/skill/runtime/Paths.js";
 
 async function runNpxSkills(args: string[], opts?: { yes?: boolean }): Promise<number> {
   const yes = opts?.yes !== false;
@@ -19,15 +16,6 @@ async function runNpxSkills(args: string[], opts?: { yes?: boolean }): Promise<n
   return result.exitCode ?? 0;
 }
 
-/**
- * 执行远程 skill 查找。
- */
-export async function skillFindCommand(query: string): Promise<void> {
-  const q = String(query || "").trim();
-  if (!q) throw new Error("Missing query");
-  await runNpxSkills(["find", q], { yes: true });
-}
-
 /**
  * skill 安装选项。
  */
@@ -68,21 +56,3 @@ export async function skillInstallCommand(
 
   await runNpxSkills(args, { yes });
 }
-
-/**
- * 输出当前项目的本地 skill 列表。
- */
-export async function skillListCommand(cwd: string = "."): Promise<void> {
-  const projectRoot = path.resolve(String(cwd || "."));
-  const roots = getSkillSearchRoots(projectRoot);
-  const skills = discoverSkillsSync(projectRoot);
-
-  console.log("Skill roots:");
-  for (const root of roots) console.log(`- [${root.source}] ${root.display}`);
-
-  console.log(`\nFound: ${skills.length}`);
-  for (const skill of skills) {
-    const desc = skill.description ? ` — ${skill.description}` : "";
-    console.log(`- [${skill.source}] ${skill.id}: ${skill.name}${desc}`);
-  }
-}

package/src/skill/PROMPT.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/skill/PROMPT.ts.txt
-const TEXT_MODULE_CONTENT = "# Skill Plugin\n\nSkills are capabilities available to you. For every user request or task, first consider whether a relevant skill can help you complete it with higher quality.\n\n## Usage\n\nBefore using a skill, load its content through the `skill` plugin's `lookup` action.\n\nIf `plugin_call` is available, use:\n\n```ts\nplugin_call({\n  plugin: \"skill\",\n  action: \"lookup\",\n  payload: {\n    name: \"<skill-name>\",\n  },\n});\n```\n\nAvailable actions include `list`, `find`, `install`, and `lookup`.\n";
+const TEXT_MODULE_CONTENT = "# Skill Plugin\n\nSkills are capabilities available to you. For every user request or task, first consider whether a relevant skill can help you complete it with higher quality.\n\n## Usage\n\nBefore using a skill, load its content through the `skill` plugin's `lookup` action.\n\nIf `plugin_call` is available, use:\n\n```ts\nplugin_call({\n  plugin: \"skill\",\n  action: \"lookup\",\n  payload: {\n    name: \"<skill-name>\",\n  },\n});\n```\n\nAvailable actions are `find`, `install`, `list`, and `lookup`.\n\n`find` and `install` are instruction-only actions. They return the Shell steps the agent should take, but never execute commands, access the network, install a skill, or change files themselves. The `install` instructions are generated from this SkillPlugin instance's configured scan roots.\n\nThe returned installation prompt tells the agent to call `list` after running the Shell command. This is workflow guidance, not code-level enforcement. If the installed skill appears in `list`, call `lookup` before using it.\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/skill/PROMPT.ts.txt

@@ -18,4 +18,8 @@ plugin_call({
 });
 ```
 
-Available actions include `list`, `find`, `install`, and `lookup`.
+Available actions are `find`, `install`, `list`, and `lookup`.
+
+`find` and `install` are instruction-only actions. They return the Shell steps the agent should take, but never execute commands, access the network, install a skill, or change files themselves. The `install` instructions are generated from this SkillPlugin instance's configured scan roots.
+
+The returned installation prompt tells the agent to call `list` after running the Shell command. This is workflow guidance, not code-level enforcement. If the installed skill appears in `list`, call `lookup` before using it.