@downcity/plugins 1.0.152 → 1.0.156

package/scripts/chat-channel-config.test.mjs

@@ -0,0 +1,82 @@
+/**
+ * Chat channel 配置持久化公开行为测试。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ChatPlugin } from "../bin/index.js";
+
+function create_channel(name) {
+  let enabled = false;
+  let channel_account_id = "";
+  return {
+    name,
+    isEnabled: () => enabled,
+    getChannelAccountId: () => channel_account_id,
+    getAccount: () => null,
+    applyRuntimePatch: (patch) => {
+      if (typeof patch.enabled === "boolean") enabled = patch.enabled;
+      if (Object.prototype.hasOwnProperty.call(patch, "channelAccountId")) {
+        channel_account_id = String(patch.channelAccountId || "").trim();
+      }
+    },
+  };
+}
+
+function create_context(plugin) {
+  const writes = [];
+  const context = {
+    config: {
+      id: "agent_test",
+      version: "1.0.0",
+      plugins: { memory: { enabled: true } },
+    },
+    pluginInstances: new Map([["chat", plugin]]),
+    pluginConfig: {
+      persistProjectPlugins: async (plugins) => {
+        writes.push(structuredClone(plugins));
+        return "/tmp/agent_test";
+      },
+    },
+  };
+  return { context, writes };
+}
+
+async function execute(plugin, action_name, context, input) {
+  return await plugin.actions[action_name].execute({
+    context,
+    input,
+    pluginName: "chat",
+    actionName: action_name,
+  });
+}
+
+test("chat.open/close/configure 持久化完整 plugins 配置", async () => {
+  const telegram = create_channel("telegram");
+  const plugin = new ChatPlugin({ channels: [telegram] });
+  const { context, writes } = create_context(plugin);
+
+  await execute(plugin, "open", context, { channel: "telegram" });
+  assert.equal(writes.length, 1);
+  assert.equal(writes[0].memory.enabled, true);
+  assert.equal(writes[0].chat.channels.telegram.enabled, true);
+  assert.equal(plugin.isChannelEnabled(context, "telegram"), true);
+
+  await execute(plugin, "configure", context, {
+    channel: "telegram",
+    config: { enabled: false },
+    restart: false,
+  });
+  assert.equal(writes.length, 2);
+  assert.equal(writes[1].chat.channels.telegram.enabled, false);
+  assert.equal(plugin.isChannelEnabled(context, "telegram"), false);
+
+  await execute(plugin, "close", context, { channel: "telegram" });
+  assert.equal(writes.length, 3);
+  assert.equal(context.config.plugins.chat.channels.telegram.enabled, false);
+});
+
+test("ChatPlugin queue 只读取 constructor 配置", () => {
+  const queue = { maxConcurrency: 7, mergeDebounceMs: 123 };
+  const plugin = new ChatPlugin({ queue, channels: [] });
+  assert.deepEqual(plugin.getQueueWorkerConfig({}), queue);
+});

package/src/chat/ChatPlugin.ts

@@ -9,11 +9,7 @@
  */
 
 import { BasePlugin } from "@downcity/agent";
-import type {
-  PluginActions,
-  PluginHooks,
-  PluginResolves,
-} from "@downcity/agent";
+import type { PluginActions } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
 import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
@@ -33,11 +29,7 @@ import {
   stopChatChannels,
 } from "./runtime/ChatChannelFacade.js";
 import { createChatPluginActions } from "./runtime/ChatPluginActions.js";
-import {
-  createChatAuthorizationActions,
-  createChatAuthorizationHooks,
-  createChatAuthorizationResolves,
-} from "./runtime/ChatAuthorizationRuntime.js";
+import { create_chat_access_actions } from "./access/ChatAccessActions.js";
 import { ChatQueueWorker } from "./runtime/ChatQueueWorker.js";
 import { buildChatPluginSystem } from "./runtime/ChatPluginSystem.js";
 import { ChatQueueStore } from "./runtime/ChatQueueStore.js";
@@ -104,16 +96,6 @@ export class ChatPlugin extends BasePlugin {
    */
   readonly actions: PluginActions;
 
-  /**
-   * 当前 plugin 的 hook 定义表。
-   */
-  readonly hooks: PluginHooks;
-
-  /**
-   * 当前 plugin 的 resolve 定义表。
-   */
-  readonly resolves: PluginResolves;
-
   /**
    * 启动当前实例的 queue worker。
    */
@@ -149,10 +131,8 @@ export class ChatPlugin extends BasePlugin {
       ...createChatPluginActions({
         channelState: this.channelState,
       }),
-      ...createChatAuthorizationActions(),
+      ...create_chat_access_actions(),
     };
-    this.hooks = createChatAuthorizationHooks();
-    this.resolves = createChatAuthorizationResolves();
     this.lifecycle = {
       start: async (context) => {
         this.startQueueWorker(context);
@@ -196,7 +176,7 @@ export class ChatPlugin extends BasePlugin {
    * 更新当前实例的渠道运行态配置。
    *
    * 关键点（中文）
-   * - chat.open/close/configure 只修改当前 plugin 实例，不写 downcity.json。
+   * - chat.open/close/configure 由 action 先调用宿主持久化能力，再修改当前实例。
    * - 当前运行态只允许更新 `enabled` 与 `channelAccountId`，密钥仍来自 constructor 或账号池。
    */
   applyChannelRuntimePatch(params: {

package/src/chat/PROMPT.direct.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/chat/PROMPT.direct.ts.txt
-const TEXT_MODULE_CONTENT = "# Chat Plugin Instructions\n\n## User-Visible Reply Rules\n\n- In the current mode, your direct assistant output is sent as a message to the user's corresponding channel.\n\n## Output Protocol\n\n- For a normal reply, output plain text directly. Optional frontmatter metadata may appear at the very top of the text. Field semantics match the chat plugin direct-send protocol:\n\n- `delay` / `delayMs`: delay before sending, in milliseconds.\n- `time` / `sendAt` / `sendAtMs`: scheduled send time.\n- `reply`: whether to send with reply semantics.\n- `messageId`: target `message_id`, recommended for group chats.\n- `react`: send an emoji reaction.\n  - Single string: `react: \"thumbs up\"`\n  - Or an object/array: `emoji/big`\n  - When `messageId` is set, `react` reuses that message as the target first.\n- Attachments use `<file type=\"...\">path</file>` and support `document/photo/voice/audio/video`.\n- Attachment paths must be relative paths accessible inside the project. For multiple attachments, output multiple `<file>` tags.\n\n### Example\n\n```text\n---\nreply: true\nmessageId: \"128\"\nreact:\n  - emoji: \"done\"\n---\nHere is today's report.\n<file type=\"document\">reports/daily.md</file>\n```\n\n### Protocol Constraints\n\n- Frontmatter must be at the very beginning of the text and wrapped with `---`.\n- Except for `<file>` attachment tags, do not use angle-bracket syntax for control parameters.\n\n## Cross-Protocol Or Cross-Platform Operations\n\n- For replies inside the current conversation, prefer outputting text directly. The system will send it to the current channel automatically.\n- When a task needs cross-conversation, cross-platform, or complex routing, use chat plugin actions.\n- If `plugin_call` is available, call `plugin_call({ plugin: \"chat\", action: \"send\", payload })` or `plugin_call({ plugin: \"chat\", action: \"react\", payload })`.\n- Metadata applies only to direct outbound messages in the current conversation. Do not use metadata for cross-chat routing.\n- If cross-chat routing parameters are unclear, first read the current chat context or call chat plugin query actions instead of guessing.\n\n## Inbound Message Structure\n\n- Each queued user message contains an `<info>...</info>` metadata block plus the user text.\n- `<info>` keeps only user/request metadata such as `user_id`, `username`, `message_id`, `permissions`, and `received_at`.\n- The current chat routing environment, such as `channel`, `session_id`, `chat_key`, and `chat_id`, is injected separately through the system prompt and is no longer mixed into `<info>`.\n- Do not echo `<info>` back to the user.\n";
+const TEXT_MODULE_CONTENT = "# Chat Plugin Instructions\n\n## User-Visible Reply Rules\n\n- In the current mode, your direct assistant output is sent as a message to the user's corresponding channel.\n\n## Output Protocol\n\n- For a normal reply, output plain text directly. Optional frontmatter metadata may appear at the very top of the text. Field semantics match the chat plugin direct-send protocol:\n\n- `delay` / `delayMs`: delay before sending, in milliseconds.\n- `time` / `sendAt` / `sendAtMs`: scheduled send time.\n- `reply`: whether to send with reply semantics.\n- `messageId`: target `message_id`, recommended for group chats.\n- `react`: send an emoji reaction.\n  - Single string: `react: \"thumbs up\"`\n  - Or an object/array: `emoji/big`\n  - When `messageId` is set, `react` reuses that message as the target first.\n- Attachments use `<file type=\"...\">path</file>` and support `document/photo/voice/audio/video`.\n- Attachment paths must be relative paths accessible inside the project. For multiple attachments, output multiple `<file>` tags.\n\n### Example\n\n```text\n---\nreply: true\nmessageId: \"128\"\nreact:\n  - emoji: \"done\"\n---\nHere is today's report.\n<file type=\"document\">reports/daily.md</file>\n```\n\n### Protocol Constraints\n\n- Frontmatter must be at the very beginning of the text and wrapped with `---`.\n- Except for `<file>` attachment tags, do not use angle-bracket syntax for control parameters.\n\n## Cross-Protocol Or Cross-Platform Operations\n\n- For replies inside the current conversation, prefer outputting text directly. The system will send it to the current channel automatically.\n- When a task needs cross-conversation, cross-platform, or complex routing, use chat plugin actions.\n- If `plugin_call` is available, call `plugin_call({ plugin: \"chat\", action: \"send\", payload })` or `plugin_call({ plugin: \"chat\", action: \"react\", payload })`.\n- Metadata applies only to direct outbound messages in the current conversation. Do not use metadata for cross-chat routing.\n- If cross-chat routing parameters are unclear, first read the current chat context or call chat plugin query actions instead of guessing.\n\n## Inbound Message Structure\n\n- Each queued user message contains an `<info>...</info>` metadata block plus the user text.\n- `<info>` keeps only user/request metadata such as `user_id`, `username`, `message_id`, and `received_at`.\n- The current chat routing environment, such as `channel`, `session_id`, `chat_key`, and `chat_id`, is injected separately through the system prompt and is no longer mixed into `<info>`.\n- Do not echo `<info>` back to the user.\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/chat/PROMPT.direct.ts.txt

@@ -48,6 +48,6 @@ Here is today's report.
 ## Inbound Message Structure
 
 - Each queued user message contains an `<info>...</info>` metadata block plus the user text.
-- `<info>` keeps only user/request metadata such as `user_id`, `username`, `message_id`, `permissions`, and `received_at`.
+- `<info>` keeps only user/request metadata such as `user_id`, `username`, `message_id`, and `received_at`.
 - The current chat routing environment, such as `channel`, `session_id`, `chat_key`, and `chat_id`, is injected separately through the system prompt and is no longer mixed into `<info>`.
 - Do not echo `<info>` back to the user.

package/src/chat/access/ChatAccessActions.ts

@@ -0,0 +1,159 @@
+/**
+ * Chat Access Plugin Actions。
+ *
+ * 关键点（中文）
+ * - Control API 通过 Chat Plugin Action 管理当前 Agent 的 Access Store。
+ * - CLI 可以直接复用 ChatAccessService，不依赖运行中 Agent。
+ */
+
+import { createAction } from "@downcity/agent";
+import type { PluginActions } from "@downcity/agent";
+import type { JsonValue } from "@downcity/agent";
+import { z } from "zod";
+import { create_chat_access_service } from "@/chat/access/ChatAccessRuntime.js";
+import { CHAT_ACCESS_ACTIONS } from "@/chat/types/ChatAccess.js";
+import type { ChatAccessScopeInput } from "@/chat/types/ChatAccess.js";
+
+const scope_schema = z.enum(["direct", "group", "all"]);
+
+/** 创建 Chat Access Action 集合。 */
+export function create_chat_access_actions(): PluginActions {
+  return {
+    [CHAT_ACCESS_ACTIONS.snapshot]: createAction({
+      description: "Read Chat Access principals, grants, and requests for the current Agent.",
+      input_schema: {
+        zod: z.object({}).passthrough(),
+        json_schema: { type: "object", properties: {}, additionalProperties: true },
+      },
+      execute: async ({ context }) => ({
+        success: true,
+        data: create_chat_access_service(context).snapshot() as unknown as JsonValue,
+      }),
+    }),
+    [CHAT_ACCESS_ACTIONS.approve]: createAction({
+      description: "Approve a pending Chat Access request.",
+      input_schema: {
+        zod: z.object({
+          request_id: z.string().min(1),
+          scope: scope_schema.optional(),
+          operator: z.string().min(1),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["request_id", "operator"],
+          properties: {
+            request_id: { type: "string" },
+            scope: { type: "string", enum: ["direct", "group", "all"] },
+            operator: { type: "string" },
+          },
+        },
+      },
+      execute: async ({ context, input }) => {
+        const body = input as {
+          request_id: string;
+          scope?: ChatAccessScopeInput;
+          operator: string;
+        };
+        return {
+          success: true,
+          data: create_chat_access_service(context).approve_request(body) as unknown as JsonValue,
+        };
+      },
+    }),
+    [CHAT_ACCESS_ACTIONS.deny]: createAction({
+      description: "Deny a pending Chat Access request.",
+      input_schema: {
+        zod: z.object({
+          request_id: z.string().min(1),
+          scope: scope_schema.optional(),
+          operator: z.string().min(1),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["request_id", "operator"],
+          properties: {
+            request_id: { type: "string" },
+            scope: { type: "string", enum: ["direct", "group", "all"] },
+            operator: { type: "string" },
+          },
+        },
+      },
+      execute: async ({ context, input }) => {
+        const body = input as {
+          request_id: string;
+          scope?: ChatAccessScopeInput;
+          operator: string;
+        };
+        return {
+          success: true,
+          data: create_chat_access_service(context).deny_request(body) as unknown as JsonValue,
+        };
+      },
+    }),
+    [CHAT_ACCESS_ACTIONS.set]: createAction({
+      description: "Set allow or deny for a known Chat Access principal.",
+      input_schema: {
+        zod: z.object({
+          principal_id: z.string().min(1),
+          scope: scope_schema,
+          effect: z.enum(["allow", "deny"]),
+          operator: z.string().min(1),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["principal_id", "scope", "effect", "operator"],
+          properties: {
+            principal_id: { type: "string" },
+            scope: { type: "string", enum: ["direct", "group", "all"] },
+            effect: { type: "string", enum: ["allow", "deny"] },
+            operator: { type: "string" },
+          },
+        },
+      },
+      execute: async ({ context, input }) => {
+        const body = input as {
+          principal_id: string;
+          scope: ChatAccessScopeInput;
+          effect: "allow" | "deny";
+          operator: string;
+        };
+        return {
+          success: true,
+          data: create_chat_access_service(context).set_principal_effect(body) as unknown as JsonValue,
+        };
+      },
+    }),
+    [CHAT_ACCESS_ACTIONS.revoke]: createAction({
+      description: "Revoke Chat Access grants for a known principal.",
+      input_schema: {
+        zod: z.object({
+          principal_id: z.string().min(1),
+          scope: scope_schema,
+          operator: z.string().min(1),
+        }),
+        json_schema: {
+          type: "object",
+          required: ["principal_id", "scope", "operator"],
+          properties: {
+            principal_id: { type: "string" },
+            scope: { type: "string", enum: ["direct", "group", "all"] },
+            operator: { type: "string" },
+          },
+        },
+      },
+      execute: async ({ context, input }) => {
+        const body = input as {
+          principal_id: string;
+          scope: ChatAccessScopeInput;
+          operator: string;
+        };
+        return {
+          success: true,
+          data: {
+            removed_count: create_chat_access_service(context).revoke_grant(body),
+          },
+        };
+      },
+    }),
+  };
+}

package/src/chat/access/ChatAccessRuntime.ts

@@ -0,0 +1,41 @@
+/**
+ * Chat Access Runtime 装配辅助。
+ *
+ * 关键点（中文）
+ * - 从当前 ChatPlugin channel 配置解析稳定 issuer。
+ * - Channel Adapter、Plugin Action 和 CLI 共享同一个 Service 构造规则。
+ */
+
+import type { AgentContext } from "@downcity/agent";
+import { ChatAccessService } from "@/chat/access/ChatAccessService.js";
+import { resolveChannelAccount } from "@/chat/runtime/ChatChannelCore.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+
+const CHANNELS: ChatDispatchChannel[] = ["telegram", "feishu", "qq"];
+
+/** 解析当前 Agent 各渠道的稳定 Issuer。 */
+export function resolve_chat_access_issuer_map(
+  context: AgentContext,
+): Partial<Record<ChatDispatchChannel, string>> {
+  const issuer_by_channel: Partial<Record<ChatDispatchChannel, string>> = {};
+  for (const channel of CHANNELS) {
+    const issuer = String(resolveChannelAccount(context, channel)?.id || "").trim();
+    if (issuer) issuer_by_channel[channel] = issuer;
+  }
+  return issuer_by_channel;
+}
+
+/** 创建当前 Agent 的 ChatAccessService。 */
+export function create_chat_access_service(context: AgentContext): ChatAccessService {
+  return new ChatAccessService({
+    project_root: context.rootPath,
+  });
+}
+
+/** 解析指定渠道当前稳定 Issuer。 */
+export function resolve_chat_access_issuer(
+  context: AgentContext,
+  channel: ChatDispatchChannel,
+): string {
+  return String(resolve_chat_access_issuer_map(context)[channel] || "").trim();
+}

package/src/chat/access/ChatAccessSchema.ts

@@ -0,0 +1,104 @@
+/**
+ * Chat Access SQLite Schema。
+ *
+ * 关键点（中文）
+ * - 所有表只保存当前 Agent 的 Chat 准入数据。
+ * - 不保存 Bot Token、App Secret 或消息正文。
+ * - WAL 与 busy_timeout 保证 Agent runtime 和 CLI 可以并发读写。
+ */
+
+import type Database from "better-sqlite3";
+
+/** 当前 Chat Access Schema 版本。 */
+export const CHAT_ACCESS_SCHEMA_VERSION = "1";
+
+/**
+ * 初始化 Chat Access Schema。
+ */
+export function ensure_chat_access_schema(database: Database.Database): void {
+  database.pragma("journal_mode = WAL");
+  database.pragma("foreign_keys = ON");
+  database.pragma("busy_timeout = 5000");
+
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS chat_access_meta (
+      key TEXT PRIMARY KEY NOT NULL,
+      value TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS chat_access_principals (
+      principal_id TEXT PRIMARY KEY NOT NULL,
+      channel TEXT NOT NULL,
+      issuer TEXT NOT NULL,
+      subject_id TEXT NOT NULL,
+      display_name TEXT,
+      first_seen_at TEXT NOT NULL,
+      last_seen_at TEXT NOT NULL,
+      last_chat_id TEXT,
+      last_chat_type TEXT,
+      UNIQUE (channel, issuer, subject_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS chat_access_grants (
+      grant_id TEXT PRIMARY KEY NOT NULL,
+      principal_id TEXT NOT NULL,
+      scope TEXT NOT NULL CHECK (scope IN ('direct', 'group')),
+      effect TEXT NOT NULL CHECK (effect IN ('allow', 'deny')),
+      created_by TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      UNIQUE (principal_id, scope),
+      FOREIGN KEY (principal_id)
+        REFERENCES chat_access_principals(principal_id)
+        ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS chat_access_requests (
+      request_id TEXT PRIMARY KEY NOT NULL,
+      principal_id TEXT NOT NULL,
+      scope TEXT NOT NULL CHECK (scope IN ('direct', 'group')),
+      chat_id TEXT NOT NULL,
+      chat_type TEXT NOT NULL,
+      status TEXT NOT NULL CHECK (status IN ('pending', 'approved', 'denied', 'expired')),
+      resolved_by TEXT,
+      created_at TEXT NOT NULL,
+      last_requested_at TEXT NOT NULL,
+      resolved_at TEXT,
+      FOREIGN KEY (principal_id)
+        REFERENCES chat_access_principals(principal_id)
+        ON DELETE CASCADE
+    );
+
+    CREATE UNIQUE INDEX IF NOT EXISTS chat_access_requests_pending_uq
+    ON chat_access_requests(principal_id, scope)
+    WHERE status = 'pending';
+
+    CREATE INDEX IF NOT EXISTS chat_access_requests_status_idx
+    ON chat_access_requests(status, last_requested_at DESC);
+
+    CREATE TABLE IF NOT EXISTS chat_access_audit_events (
+      event_id TEXT PRIMARY KEY NOT NULL,
+      principal_id TEXT,
+      request_id TEXT,
+      action TEXT NOT NULL,
+      scope TEXT,
+      decision TEXT,
+      operator TEXT,
+      detail_json TEXT,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS chat_access_audit_created_idx
+    ON chat_access_audit_events(created_at DESC);
+  `);
+
+  const current_time = new Date().toISOString();
+  database.prepare(`
+    INSERT INTO chat_access_meta (key, value, updated_at)
+    VALUES ('schema_version', ?, ?)
+    ON CONFLICT(key) DO UPDATE SET
+      value = excluded.value,
+      updated_at = excluded.updated_at
+  `).run(CHAT_ACCESS_SCHEMA_VERSION, current_time);
+}