@downcity/plugins 1.0.4

package/src/contact/types/ContactShare.ts

@@ -0,0 +1,172 @@
+/**
+ * contact share 类型。
+ *
+ * 关键点（中文）
+ * - share 是通用内容分享，不绑定 skill 概念。
+ * - 文本、链接、文件、目录都进入 inbox，由接收方显式 receive。
+ */
+
+/**
+ * share item 类型。
+ */
+export type ContactShareItemType = "text" | "link" | "file" | "directory";
+
+/**
+ * inbox share 状态。
+ */
+export type ContactInboxShareStatus = "pending" | "received";
+
+/**
+ * inbox share 轻量元信息。
+ */
+export interface ContactInboxShareMeta {
+  /**
+   * share 稳定标识。
+   */
+  id: string;
+  /**
+   * 发送方 contact id。
+   */
+  fromContactId: string;
+  /**
+   * 发送方 agent 名称。
+   */
+  fromAgentName: string;
+  /**
+   * 面向用户展示的标题。
+   */
+  title: string;
+  /**
+   * 当前接收状态。
+   */
+  status: ContactInboxShareStatus;
+  /**
+   * 接收时间戳。
+   */
+  receivedAt: number;
+  /**
+   * 内容总大小。
+   */
+  sizeBytes: number;
+  /**
+   * 内容条目数量。
+   */
+  itemCount: number;
+}
+
+/**
+ * share item 中的单个文件 manifest。
+ */
+export interface ContactShareFileManifest {
+  /**
+   * item 根目录内相对路径。
+   */
+  path: string;
+  /**
+   * 文件 sha256。
+   */
+  sha256: string;
+}
+
+/**
+ * share payload 中的单个 item。
+ */
+export interface ContactShareItem {
+  /**
+   * item 稳定标识。
+   */
+  id: string;
+  /**
+   * item 类型。
+   */
+  type: ContactShareItemType;
+  /**
+   * item 展示标题。
+   */
+  title: string;
+  /**
+   * 文本内容。
+   */
+  text?: string;
+  /**
+   * 链接 URL。
+   */
+  url?: string;
+  /**
+   * share files 下的根目录名。
+   */
+  root?: string;
+  /**
+   * 文件 manifest 列表。
+   */
+  files?: ContactShareFileManifest[];
+}
+
+/**
+ * 通用 share payload。
+ */
+export interface ContactSharePayload {
+  /**
+   * payload 类型。
+   */
+  kind: "share";
+  /**
+   * share item 列表。
+   */
+  items: ContactShareItem[];
+}
+
+/**
+ * inbox share payload。
+ */
+export type ContactInboxSharePayload = ContactSharePayload;
+
+/**
+ * inbox share 文件内容。
+ */
+export interface ContactInboxShareFileInput {
+  /**
+   * share files 目录下的相对路径。
+   */
+  relativePath: string;
+  /**
+   * 文件内容。
+   */
+  content: string;
+  /**
+   * 内容编码。
+   *
+   * 说明（中文）
+   * - 省略时按 `utf8` 处理，兼容测试和手写 payload。
+   * - 文件/目录分享默认使用 `base64`，避免二进制文件损坏。
+   */
+  encoding?: "utf8" | "base64";
+}
+
+/**
+ * 保存 inbox share 的输入。
+ */
+export interface SaveContactInboxShareInput {
+  /**
+   * share 轻量元信息。
+   */
+  meta: ContactInboxShareMeta;
+  /**
+   * share payload。
+   */
+  payload: ContactInboxSharePayload;
+  /**
+   * share 附带文件。
+   */
+  files: ContactInboxShareFileInput[];
+}
+
+/**
+ * 远端 receive share 请求。
+ */
+export interface ContactReceiveShareRequest extends SaveContactInboxShareInput {
+  /**
+   * 发送方 contact id。
+   */
+  senderContactId: string;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * @downcity/plugins 公开入口。
+ *
+ * 关键点（中文）
+ * - 这个包专门承载 Downcity 内建 plugin 的对外消费入口。
+ * - 本包只导出具体 plugin class 与默认内建集合工厂。
+ * - 注册、目录、HTTP、CLI、action 执行都由 `@downcity/agent` 的通用能力处理。
+ */
+
+export {
+  BUILTIN_PLUGIN_CLASSES,
+  createBuiltinPlugins,
+} from "./BuiltinPlugins.js";
+export type { BuiltinPluginClass } from "./BuiltinPlugins.js";
+export { ChatPlugin } from "./chat/ChatPlugin.js";
+export { ChatChannelAccountManager } from "./chat/accounts/ChannelAccountManager.js";
+export { AuthPlugin } from "./auth/Plugin.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 { WorkboardPlugin } from "./workboard/Plugin.js";
+export {
+  listChatAuthorizationRoles,
+  readChatAuthorizationConfigSync,
+  setChatAuthorizationUserRole,
+} from "./auth/runtime/AuthorizationConfig.js";
+export { resolveAuthorizedUserRole } from "./auth/runtime/AuthorizationPolicy.js";
+export {
+  CHAT_AUTHORIZATION_CHANNELS,
+  createDefaultChatAuthorizationRoles,
+  isChatAuthorizationChannel,
+} from "./auth/types/AuthPlugin.js";
+
+export type {
+  ChatChannelAccountListItem,
+} from "./chat/types/ChannelAccount.js";
+export type {
+  ChatPluginFeishuOptions,
+  ChatPluginOptions,
+  ChatPluginQqOptions,
+  ChatPluginTelegramOptions,
+} from "./chat/ChatPluginTypes.js";
+export type {
+  AuthObservePrincipalPayload,
+  AuthObservePrincipalResult,
+  AuthResolveUserRolePayload,
+  AuthSetUserRolePayload,
+  AuthWriteConfigPayload,
+  ChatAuthorizationCatalog,
+  ChatAuthorizationChannel,
+  ChatAuthorizationConfig,
+  ChatAuthorizationDecision,
+  ChatAuthorizationEvaluateInput,
+  ChatAuthorizationEvaluateResult,
+  ChatAuthorizationObservedChat,
+  ChatAuthorizationObservedUser,
+  ChatAuthorizationPermission,
+  ChatAuthorizationPermissionMeta,
+  ChatAuthorizationRole,
+  ChatAuthorizationSnapshot,
+  ChatAuthorizationStateFile,
+  ChatChannelAuthorizationConfig,
+} from "./auth/types/AuthPlugin.js";

package/src/memory/Action.ts

@@ -0,0 +1,147 @@
+/**
+ * Memory Service Action 逻辑。
+ *
+ * 关键点（中文）
+ * - 只处理业务动作，不包含 CLI/API 参数映射细节。
+ * - 所有动作统一返回结构化结果，失败不抛给上层。
+ */
+
+import type { PluginActionResult } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type {
+  MemoryFlushPayload,
+  MemoryGetPayload,
+  MemorySearchPayload,
+  MemoryStorePayload,
+} from "@/memory/types/Memory.js";
+import { flushMemory } from "./runtime/Flush.js";
+import {
+  collectMemoryStatus,
+  searchMemory,
+} from "./runtime/Search.js";
+import {
+  MEMORY_DEFAULTS,
+  type MemoryRuntimeState,
+} from "./runtime/Store.js";
+import { getMemory, storeMemory } from "./runtime/Writer.js";
+
+/**
+ * status action。
+ */
+export async function statusMemoryAction(
+  context: AgentContext,
+  state: MemoryRuntimeState,
+): Promise<PluginActionResult<JsonValue>> {
+  try {
+    const stats = await collectMemoryStatus(context, state);
+    return {
+      success: true,
+      data: stats as unknown as JsonValue,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+    };
+  }
+}
+
+/**
+ * search action。
+ */
+export async function searchMemoryAction(
+  context: AgentContext,
+  state: MemoryRuntimeState,
+  payload: MemorySearchPayload,
+): Promise<PluginActionResult<JsonValue>> {
+  try {
+    const response = await searchMemory(context, state, payload);
+    return {
+      success: true,
+      data: response as unknown as JsonValue,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+    };
+  }
+}
+
+/**
+ * get action。
+ */
+export async function getMemoryAction(
+  context: AgentContext,
+  payload: MemoryGetPayload,
+): Promise<PluginActionResult<JsonValue>> {
+  try {
+    const data = await getMemory(context, payload);
+    return { success: true, data: data as unknown as JsonValue };
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+    };
+  }
+}
+
+/**
+ * store action。
+ */
+export async function storeMemoryAction(
+  context: AgentContext,
+  state: MemoryRuntimeState,
+  payload: MemoryStorePayload,
+): Promise<PluginActionResult<JsonValue>> {
+  try {
+    const data = await storeMemory(context, state, payload);
+    return { success: true, data: data as unknown as JsonValue };
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+    };
+  }
+}
+
+/**
+ * flush action。
+ */
+export async function flushMemoryAction(
+  context: AgentContext,
+  state: MemoryRuntimeState,
+  payload: MemoryFlushPayload,
+): Promise<PluginActionResult> {
+  try {
+    const data = await flushMemory(context, state, payload);
+    return { success: true, data: data as unknown as JsonValue };
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+    };
+  }
+}
+
+/**
+ * 把任意 payload 归一化为 search payload。
+ */
+export function toSearchPayload(input: Record<string, unknown>): MemorySearchPayload {
+  return {
+    query: String(input.query || ""),
+    maxResults:
+      typeof input.maxResults === "number"
+        ? input.maxResults
+        : typeof input.maxResults === "string"
+          ? Number(input.maxResults)
+          : MEMORY_DEFAULTS.maxResults,
+    minScore:
+      typeof input.minScore === "number"
+        ? input.minScore
+        : typeof input.minScore === "string"
+          ? Number(input.minScore)
+          : MEMORY_DEFAULTS.minScore,
+  };
+}

package/src/memory/Index.ts

@@ -0,0 +1,9 @@
+/**
+ * Memory Plugin 导出入口。
+ *
+ * 关键点（中文）
+ * - Index 只负责导出类实现。
+ * - 真正运行时的 per-agent 实例由宿主显式创建并传给 Agent。
+ */
+
+export { MemoryPlugin } from "./MemoryPlugin.js";

package/src/memory/MemoryPlugin.ts

@@ -0,0 +1,270 @@
+/**
+ * MemoryPlugin：memory plugin 的类实现。
+ *
+ * 关键点（中文）
+ * - memory plugin state 现在归属于 plugin 实例。
+ * - agent 持有 MemoryPlugin 实例，从而天然形成 per-agent 状态边界。
+ * - 运行态只在实例内部缓存，不再放到模块级 Map。
+ */
+
+import type { Command } from "commander";
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import {
+  flushMemoryAction,
+  getMemoryAction,
+  searchMemoryAction,
+  statusMemoryAction,
+  storeMemoryAction,
+} from "./Action.js";
+import {
+  createMemoryRuntimeState,
+  isMemoryEnabled,
+  startMemoryRuntime,
+  stopMemoryRuntime,
+  type MemoryRuntimeState,
+} from "./runtime/Store.js";
+import { buildMemoryPluginSystemText } from "./runtime/SystemProvider.js";
+import { ensureMemoryDirectories } from "./runtime/Writer.js";
+
+function parsePositiveInteger(value: string): number {
+  const text = String(value || "").trim();
+  if (!/^\d+$/.test(text)) {
+    throw new Error(`Invalid positive integer: ${value}`);
+  }
+  const num = Number(text);
+  if (!Number.isFinite(num) || num < 1) {
+    throw new Error(`Invalid positive integer: ${value}`);
+  }
+  return num;
+}
+
+function parseNumber(value: string): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error("number is required");
+  }
+  const num = Number(text);
+  if (!Number.isFinite(num)) {
+    throw new Error(`Invalid number: ${value}`);
+  }
+  return num;
+}
+
+function readBodyObject(rawBody: JsonValue): JsonObject {
+  if (!rawBody || typeof rawBody !== "object" || Array.isArray(rawBody)) {
+    return {};
+  }
+  return rawBody as JsonObject;
+}
+
+function readString(body: JsonObject, key: string): string {
+  const value = body[key];
+  return typeof value === "string" ? value : "";
+}
+
+function readOptionalString(body: JsonObject, key: string): string | undefined {
+  const value = body[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readOptionalNumber(body: JsonObject, key: string): number | undefined {
+  const value = body[key];
+  return typeof value === "number" ? value : undefined;
+}
+
+/**
+ * Memory plugin 类实现。
+ */
+export class MemoryPlugin extends BasePlugin {
+  /**
+   * plugin 名称。
+   */
+  readonly name = "memory";
+
+  /**
+   * 当前实例持有的 memory plugin state。
+   */
+  public runtimeState: MemoryRuntimeState | null = null;
+
+  /**
+   * 当前 plugin 的 system 文本提供器。
+   */
+  async system(context: AgentContext): Promise<string> {
+    return await buildMemoryPluginSystemText(context);
+  }
+
+  /**
+   * 当前 plugin 生命周期。
+   */
+  readonly lifecycle = {
+    start: async (context: AgentContext): Promise<void> => {
+      await ensureMemoryDirectories(context.rootPath);
+      const state = this.getOrCreateRuntimeState(context);
+      await startMemoryRuntime(context, state);
+    },
+    stop: async (): Promise<void> => {
+      if (!this.runtimeState) return;
+      await stopMemoryRuntime(this.runtimeState);
+      this.runtimeState = null;
+    },
+  };
+
+  /**
+   * 当前 plugin action 定义表。
+   */
+  readonly actions: PluginActions = {
+    status: {
+      command: {
+        description: "查看 memory 状态（backend/files/chunks）",
+        mapInput() {
+          return {};
+        },
+      },
+      execute: async (params) => {
+        const state = this.getOrCreateRuntimeState(params.context);
+        return await statusMemoryAction(params.context, state);
+      },
+    },
+    search: {
+      command: {
+        description: "检索记忆片段",
+        configure(command: Command) {
+          command
+            .argument("<query>")
+            .option("--max-results <number>", "返回条数上限", parsePositiveInteger)
+            .option("--min-score <number>", "最小相关分数", parseNumber);
+        },
+        mapInput({ args, opts }) {
+          const payload: JsonObject = {
+            query: String(args[0] || ""),
+          };
+          if (typeof opts.maxResults === "number") {
+            payload.maxResults = opts.maxResults;
+          }
+          if (typeof opts.minScore === "number") {
+            payload.minScore = opts.minScore;
+          }
+          return payload;
+        },
+      },
+      execute: async (params) => {
+        const body = readBodyObject(params.payload);
+        const state = this.getOrCreateRuntimeState(params.context);
+        return await searchMemoryAction(params.context, state, {
+          query: readString(body, "query"),
+          maxResults: readOptionalNumber(body, "maxResults"),
+          minScore: readOptionalNumber(body, "minScore"),
+        });
+      },
+    },
+    get: {
+      command: {
+        description: "读取记忆文件片段",
+        configure(command: Command) {
+          command
+            .argument("<memoryPath>", "记忆文件路径（相对项目根目录）")
+            .option("--from <number>", "起始行（1-based）", parsePositiveInteger)
+            .option("--lines <number>", "读取行数", parsePositiveInteger);
+        },
+        mapInput({ args, opts }) {
+          const payload: JsonObject = {
+            path: String(args[0] || ""),
+          };
+          if (typeof opts.from === "number") {
+            payload.from = opts.from;
+          }
+          if (typeof opts.lines === "number") {
+            payload.lines = opts.lines;
+          }
+          return payload;
+        },
+      },
+      execute: async (params) => {
+        const body = readBodyObject(params.payload);
+        return await getMemoryAction(params.context, {
+          path: readString(body, "path"),
+          from: readOptionalNumber(body, "from"),
+          lines: readOptionalNumber(body, "lines"),
+        });
+      },
+    },
+    store: {
+      command: {
+        description: "显式写入 memory（longterm/daily/working）",
+        configure(command: Command) {
+          command
+            .requiredOption("--content <text>", "写入内容")
+            .option("--target <target>", "写入层（longterm|daily|working）")
+            .option("--session-id <sessionId>", "working 目标必填");
+        },
+        mapInput({ opts }) {
+          const payload: JsonObject = {
+            content: String(opts.content || ""),
+          };
+          if (typeof opts.target === "string") {
+            payload.target = String(opts.target).trim();
+          }
+          if (typeof opts.sessionId === "string") {
+            payload.sessionId = String(opts.sessionId).trim();
+          }
+          return payload;
+        },
+      },
+      execute: async (params) => {
+        const body = readBodyObject(params.payload);
+        const target = readOptionalString(body, "target");
+        const state = this.getOrCreateRuntimeState(params.context);
+        return await storeMemoryAction(params.context, state, {
+          content: readString(body, "content"),
+          target:
+            target === "longterm" || target === "daily" || target === "working"
+              ? target
+              : undefined,
+          sessionId: readOptionalString(body, "sessionId"),
+        });
+      },
+    },
+    flush: {
+      command: {
+        description: "将当前会话最近消息刷写到 daily memory",
+        configure(command: Command) {
+          command
+            .requiredOption("--session-id <sessionId>", "会话 ID")
+            .option("--max-messages <number>", "提取消息窗口", parsePositiveInteger);
+        },
+        mapInput({ opts }) {
+          const payload: JsonObject = {
+            sessionId: String(opts.sessionId || ""),
+          };
+          if (typeof opts.maxMessages === "number") {
+            payload.maxMessages = opts.maxMessages;
+          }
+          return payload;
+        },
+      },
+      execute: async (params) => {
+        const body = readBodyObject(params.payload);
+        const state = this.getOrCreateRuntimeState(params.context);
+        return await flushMemoryAction(params.context, state, {
+          sessionId: readString(body, "sessionId"),
+          maxMessages: readOptionalNumber(body, "maxMessages"),
+        });
+      },
+    },
+  };
+
+  /**
+   * 获取或创建当前实例绑定的 memory plugin state。
+   */
+  private getOrCreateRuntimeState(context: AgentContext): MemoryRuntimeState {
+    if (!this.runtimeState) {
+      this.runtimeState = createMemoryRuntimeState(context);
+      return this.runtimeState;
+    }
+    this.runtimeState.enabled = isMemoryEnabled(context);
+    return this.runtimeState;
+  }
+}