@downcity/plugins 1.0.57 → 1.0.60

package/src/contact/types/ContactPluginOptions.ts

@@ -0,0 +1,30 @@
+/**
+ * ContactPluginOptions：ContactPlugin 构造参数。
+ *
+ * 关键点（中文）
+ * - 这里只保留 agent 运行时真正需要的显式配置。
+ * - contact token、link secret 等协议密钥都由运行时自动生成，不从 constructor 传入。
+ */
+
+/**
+ * ContactPlugin 构造参数。
+ */
+export interface ContactPluginOptions {
+  /**
+   * 当前 agent 对外可访问的 HTTP endpoint。
+   *
+   * 说明（中文）
+   * - 传入后会优先写入 `contact link` 生成的一次性联系码。
+   * - 适合反向代理、tunnel、公网域名等自动探测不可靠的环境。
+   */
+  endpoint?: string;
+
+  /**
+   * 默认 link 有效秒数。
+   *
+   * 说明（中文）
+   * - `contact link` action 没有显式传 `ttlSeconds` 时使用该值。
+   * - 最终运行时仍会强制不少于 60 秒，避免生成过短的人工转交 code。
+   */
+  ttlSeconds?: number;
+}

package/src/index.ts

@@ -11,11 +11,19 @@ export {
   BUILTIN_PLUGIN_CLASSES,
   createBuiltinPlugins,
 } from "./BuiltinPlugins.js";
-export type { BuiltinPluginClass } from "./BuiltinPlugins.js";
+export type {
+  BuiltinPluginClass,
+  BuiltinPluginOptions,
+} from "./BuiltinPlugins.js";
 export { ChatPlugin } from "./chat/ChatPlugin.js";
+export { ContactPlugin } from "./contact/ContactPlugin.js";
+export {
+  FeishuChannel,
+  QqChannel,
+  TelegramChannel,
+} from "./chat/channels/RuntimeChannel.js";
 export { ImagePlugin } from "./image/ImagePlugin.js";
 export { ChatChannelAccountManager } from "./chat/accounts/ChannelAccountManager.js";
-export { ChatAuthorizationPlugin } from "./auth/Plugin.js";
 export { SkillPlugin } from "./skill/Plugin.js";
 export { WebPlugin } from "./web/Plugin.js";
 export { AsrPlugin } from "./asr/Plugin.js";
@@ -28,8 +36,9 @@ export {
 } from "./auth/runtime/AuthorizationConfig.js";
 export { resolveAuthorizedUserRole } from "./auth/runtime/AuthorizationPolicy.js";
 export {
+  CHAT_AUTHORIZATION_ACTIONS,
   CHAT_AUTHORIZATION_CHANNELS,
-  CHAT_AUTHORIZATION_PLUGIN_NAME,
+  CHAT_AUTHORIZATION_POINTS,
   createDefaultChatAuthorizationRoles,
   isChatAuthorizationChannel,
 } from "./auth/types/AuthPlugin.js";
@@ -38,11 +47,18 @@ export type {
   ChatChannelAccountListItem,
 } from "./chat/types/ChannelAccount.js";
 export type {
-  ChatPluginFeishuOptions,
+  BaseChatChannelOptions,
+  ChatChannelEnv,
+  FeishuChannelOptions,
+  QqChannelOptions,
+  TelegramChannelOptions,
+} from "./chat/channels/RuntimeChannel.js";
+export type {
+  ChatChannel,
+  ChatChannelRuntimePatch,
   ChatPluginOptions,
-  ChatPluginQqOptions,
-  ChatPluginTelegramOptions,
-} from "./chat/ChatPluginTypes.js";
+} from "./chat/types/ChatPluginOptions.js";
+export type { ContactPluginOptions } from "./contact/types/ContactPluginOptions.js";
 export type {
   AsrPluginInput,
   AsrPluginOptions,

package/src/skill/Action.ts

@@ -8,8 +8,8 @@
 
 import fs from "fs-extra";
 import path from "node:path";
-import { discoverClaudeSkillsSync } from "@/skill/runtime/Discovery.js";
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import { discoverSkillsSync } from "@/skill/runtime/Discovery.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 import type {
   SkillListResponse,
@@ -30,7 +30,7 @@ function normalizeAllowedTools(input: JsonValue | undefined): string[] {
   return Array.from(new Set(values));
 }
 
-function toSkillSummary(skill: ClaudeSkill): SkillSummary {
+function toSkillSummary(skill: SkillDefinition): SkillSummary {
   return {
     id: skill.id,
     name: skill.name,
@@ -41,7 +41,10 @@ function toSkillSummary(skill: ClaudeSkill): SkillSummary {
   };
 }
 
-function findSkillExact(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
+function findSkillExact(
+  skills: SkillDefinition[],
+  name: string,
+): SkillDefinition | null {
   const q = String(name || "").trim().toLowerCase();
   if (!q) return null;
 
@@ -52,7 +55,7 @@ function findSkillExact(skills: ClaudeSkill[], name: string): ClaudeSkill | null
   );
 }
 
-function findSkill(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
+function findSkill(skills: SkillDefinition[], name: string): SkillDefinition | null {
   const q = String(name || "").trim().toLowerCase();
   if (!q) return null;
 
@@ -67,9 +70,9 @@ function findSkill(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
 function getSkills(
   projectRoot: string,
   options?: SkillPluginOptions | null,
-): ClaudeSkill[] {
+): SkillDefinition[] {
   const root = path.resolve(projectRoot);
-  return discoverClaudeSkillsSync(root, options);
+  return discoverSkillsSync(root, options);
 }
 
 /**

package/src/skill/Command.ts

@@ -8,8 +8,8 @@
 
 import path from "node:path";
 import { execa } from "execa";
-import { discoverClaudeSkillsSync } from "@/skill/runtime/Discovery.js";
-import { getClaudeSkillSearchRoots } from "@/skill/runtime/Paths.js";
+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;
@@ -57,7 +57,7 @@ export async function skillInstallCommand(
   if (!s) throw new Error("Missing spec");
 
   const args: string[] = ["add", s];
-  const agent = String(options.agent || "claude-code").trim();
+  const agent = String(options.agent || "").trim();
   if (agent) args.push("--agent", agent);
 
   const yes = options.yes !== false;
@@ -74,8 +74,8 @@ export async function skillInstallCommand(
  */
 export async function skillListCommand(cwd: string = "."): Promise<void> {
   const projectRoot = path.resolve(String(cwd || "."));
-  const roots = getClaudeSkillSearchRoots(projectRoot);
-  const skills = discoverClaudeSkillsSync(projectRoot);
+  const roots = getSkillSearchRoots(projectRoot);
+  const skills = discoverSkillsSync(projectRoot);
 
   console.log("Skill roots:");
   for (const root of roots) console.log(`- [${root.source}] ${root.display}`);

package/src/skill/Plugin.ts

@@ -166,7 +166,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
               .argument("<spec>")
               .option("-g, --global", "全局安装（默认 true）", true)
               .option("-y, --yes", "跳过确认（默认 true）", true)
-              .option("--agent <agent>", "指定 agent", "claude-code");
+              .option("--agent <agent>", "指定 agent");
           },
           mapInput({ args, opts }): SkillPluginInstallPayload {
             const spec = String(args[0] || "").trim();

package/src/skill/runtime/Discovery.ts

@@ -12,15 +12,18 @@ import path from "path";
 import type { Dirent, Stats } from "node:fs";
 import { resolveSkillPluginOptions } from "../Config.js";
 import { parseFrontMatter } from "./Frontmatter.js";
-import { getClaudeSkillSearchRoots } from "./Paths.js";
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import { getSkillSearchRoots } from "./Paths.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type {
   SkillPluginIgnoreRule,
   SkillPluginOptions,
 } from "@/skill/types/SkillPlugin.js";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 
-function matchesIgnoreRule(skill: ClaudeSkill, rule: SkillPluginIgnoreRule): boolean {
+function matchesIgnoreRule(
+  skill: SkillDefinition,
+  rule: SkillPluginIgnoreRule,
+): boolean {
   if (typeof rule === "string") {
     const value = rule.trim().toLowerCase();
     if (!value) return false;
@@ -41,7 +44,7 @@ function matchesIgnoreRule(skill: ClaudeSkill, rule: SkillPluginIgnoreRule): boo
 }
 
 function shouldIgnoreSkill(
-  skill: ClaudeSkill,
+  skill: SkillDefinition,
   rules: SkillPluginIgnoreRule[],
 ): boolean {
   for (const rule of rules) {
@@ -51,7 +54,7 @@ function shouldIgnoreSkill(
 }
 
 /**
- * 扫描并发现 Claude Code-compatible skills。
+ * 扫描并发现本地 skills。
  *
  * 关键点（中文）
  * - skills 的扫描根目录与 projectRoot 强相关（默认 `.agents/skills`）
@@ -61,19 +64,19 @@ function shouldIgnoreSkill(
  * 发现技能算法（中文）
  * 1) 计算扫描根目录列表
  * 2) 逐目录读取 `SKILL.md` 与 frontmatter
- * 3) 按 id 去重并构造 ClaudeSkill
+ * 3) 按 id 去重并构造 SkillDefinition
  * 4) 最终按 name 排序，保证输出稳定
  */
-export function discoverClaudeSkillsSync(
+export function discoverSkillsSync(
   projectRoot: string,
   options?: SkillPluginOptions | null,
-): ClaudeSkill[] {
+): SkillDefinition[] {
   const root = String(projectRoot || "").trim();
   if (!root) return [];
   const resolvedOptions = resolveSkillPluginOptions(options);
-  const roots = getClaudeSkillSearchRoots(root, resolvedOptions);
+  const roots = getSkillSearchRoots(root, resolvedOptions);
 
-  const outById = new Map<string, ClaudeSkill>();
+  const outById = new Map<string, SkillDefinition>();
 
   for (const r of roots) {
     const sourceRoot = r.resolved;
@@ -146,7 +149,7 @@ export function discoverClaudeSkillsSync(
       const allowedTools =
         meta?.["allowed-tools"] ?? meta?.allowedTools ?? meta?.allowed_tools;
 
-      const skill: ClaudeSkill = {
+      const skill: SkillDefinition = {
         id,
         name,
         description,

package/src/skill/runtime/Paths.ts

@@ -36,7 +36,7 @@ function resolveSkillRootPath(projectRoot: string, raw: string): string {
     : path.resolve(projectRoot, expanded);
 }
 
-export function getClaudeSkillSearchRoots(
+export function getSkillSearchRoots(
   projectRoot: string,
   options?: SkillPluginOptions | null,
 ): SkillRoot[] {
@@ -105,15 +105,3 @@ export function getClaudeSkillSearchRoots(
 
   return Array.from(byResolved.values()).sort((a, b) => a.priority - b.priority);
 }
-
-// Back-compat（内部仅用于 prompt 展示）：保留旧 API 形状，避免外部 import 立刻断裂。
-export function getClaudeSkillSearchPaths(
-  projectRoot: string,
-  options?: SkillPluginOptions | null,
-): { raw: string[]; resolved: string[] } {
-  const roots = getClaudeSkillSearchRoots(projectRoot, options);
-  return {
-    raw: roots.map((r) => r.display),
-    resolved: roots.map((r) => r.resolved),
-  };
-}

package/src/skill/runtime/Prompt.ts

@@ -7,8 +7,8 @@
  * - 仅做字符串渲染，不做文件 IO。
  */
 
-import { getClaudeSkillSearchRoots } from "./Paths.js";
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import { getSkillSearchRoots } from "./Paths.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
 /**
@@ -18,12 +18,12 @@ import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
  * - 为控制 token 成本，最多展示前 40 个 skill。
  * - roots 会按扫描顺序输出，便于排查冲突覆盖。
  */
-export function renderClaudeSkillsPromptSection(
+export function renderSkillsPromptSection(
   projectRoot: string,
   options: SkillPluginOptions | null | undefined,
-  skills: ClaudeSkill[],
+  skills: SkillDefinition[],
 ): string {
-  const roots = getClaudeSkillSearchRoots(projectRoot, options);
+  const roots = getSkillSearchRoots(projectRoot, options);
 
   const skillsSection =
     skills.length > 0

package/src/skill/runtime/Store.ts

@@ -6,7 +6,7 @@
  * - core 不负责也不感知 skill/memory 业务状态
  */
 
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type {
   SessionSkillStateInternal,
   SessionSkillStateSnapshot,
@@ -50,9 +50,12 @@ function getOrCreateState(sessionId: string): SessionSkillStateInternal {
  * 算法（中文）
  * - 以 id 归一化后整体替换，避免残留脏状态。
  */
-export function setSessionAvailableSkills(sessionId: string, skills: ClaudeSkill[]): void {
+export function setSessionAvailableSkills(
+  sessionId: string,
+  skills: SkillDefinition[],
+): void {
   const state = getOrCreateState(sessionId);
-  const next = new Map<string, ClaudeSkill>();
+  const next = new Map<string, SkillDefinition>();
 
   for (const skill of Array.isArray(skills) ? skills : []) {
     const id = String(skill?.id || "").trim();

package/src/skill/runtime/SystemProvider.ts

@@ -8,8 +8,8 @@
  */
 
 import { getSessionRunContext } from "@downcity/agent/internal/executor/SessionRunScope.js";
-import { discoverClaudeSkillsSync } from "./Discovery.js";
-import { renderClaudeSkillsPromptSection } from "./Prompt.js";
+import { discoverSkillsSync } from "./Discovery.js";
+import { renderSkillsPromptSection } from "./Prompt.js";
 import { setSessionAvailableSkills } from "./Store.js";
 import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
@@ -35,7 +35,7 @@ export async function buildSkillsSystemText(
   runtime: SkillSystemRuntime,
 ): Promise<string> {
   const sessionId = getCurrentSessionId();
-  const discoveredSkills = discoverClaudeSkillsSync(
+  const discoveredSkills = discoverSkillsSync(
     runtime.rootPath,
     runtime.options,
   );
@@ -44,7 +44,7 @@ export async function buildSkillsSystemText(
     setSessionAvailableSkills(sessionId, discoveredSkills);
   }
 
-  return renderClaudeSkillsPromptSection(
+  return renderSkillsPromptSection(
     runtime.rootPath,
     runtime.options,
     discoveredSkills,

package/src/skill/runtime/Types.ts

@@ -1,4 +1,4 @@
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 
 /**
  * Session skills state 对外快照。
@@ -9,7 +9,7 @@ import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
  */
 export type SessionSkillStateSnapshot = {
   sessionId: string;
-  allSkills: ClaudeSkill[];
+  allSkills: SkillDefinition[];
   updatedAt: number;
 };
 
@@ -17,6 +17,6 @@ export type SessionSkillStateSnapshot = {
  * Session skills state 内部结构。
  */
 export type SessionSkillStateInternal = {
-  allSkillsById: Map<string, ClaudeSkill>;
+  allSkillsById: Map<string, SkillDefinition>;
   updatedAt: number;
 };

package/src/skill/types/{ClaudeSkill.ts → SkillDefinition.ts}

@@ -1,5 +1,5 @@
 /**
- * Claude Code-compatible skill 模型。
+ * Skill 定义模型。
  *
  * 关键点（中文）
  * - skill 最小单元目录为 `<root>/<skill-id>/SKILL.md`。
@@ -11,9 +11,9 @@ import type { SkillRootSource } from "@/skill/types/SkillRoot.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 
 /**
- * Claude Code-compatible skill。
+ * 可被 agent 发现与读取的 skill 定义。
  */
-export interface ClaudeSkill {
+export interface SkillDefinition {
   /**
    * skill 稳定标识。
    *

package/src/skill/types/SkillPlugin.ts

@@ -7,7 +7,7 @@
  * - 该文件只描述插件协议，不承载发现、安装或 system 组装逻辑。
  */
 
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type { SkillRootSource } from "@/skill/types/SkillRoot.js";
 
 /**
@@ -80,7 +80,7 @@ export type SkillPluginLookupPayload = {
 export type SkillPluginIgnoreRule =
   | string
   | RegExp
-  | ((skill: ClaudeSkill) => boolean);
+  | ((skill: SkillDefinition) => boolean);
 
 /**
  * SkillPlugin 构造参数。

package/src/web/Plugin.ts

@@ -145,7 +145,7 @@ export class WebPlugin extends BasePlugin {
             .option("--target <target>", "web-access、agent-browser 或 all")
             .option("--scope <scope>", "安装位置：user 或 project")
             .option("-y, --yes", "跳过确认（默认 true）", true)
-            .option("--agent <agent>", "skill installer 目标 agent", "claude-code");
+            .option("--agent <agent>", "skill installer 目标 agent");
         },
         mapInput({ opts }): JsonObject {
           return {

package/src/web/runtime/Install.ts

@@ -145,7 +145,7 @@ async function install_skill(params: {
   spec: string;
   scope: WebPluginInstallScope;
   yes: boolean;
-  agent: string;
+  agent?: string;
   steps: WebPluginInstallStep[];
 }): Promise<void> {
   await skillInstallCommand(params.spec, {
@@ -207,7 +207,7 @@ export async function installWebPluginTargets(params: {
   const target = resolve_install_target(payload.target);
   const scope = resolve_install_scope(payload.scope);
   const yes = read_boolean(payload.yes) ?? true;
-  const agent = read_string(payload.agent) || "claude-code";
+  const agent = read_string(payload.agent);
   const targets =
     target === "all" ? (["web-access", "agent-browser"] as const) : ([target] as const);
   const steps: WebPluginInstallStep[] = [];
@@ -233,7 +233,7 @@ export async function installWebPluginTargets(params: {
   return {
     target,
     scope,
-    agent,
+    ...(agent ? { agent } : {}),
     steps: serialize_steps(steps),
     nextAction:
       "Use SkillPlugin lookup/list to inspect installed skills, then let the agent choose the concrete web path during task execution.",

package/src/web/types/WebPlugin.ts

@@ -54,7 +54,8 @@ export interface WebPluginInstallPayload {
    * skill installer 的目标 agent 名称。
    *
    * 说明（中文）
-   * - 默认使用 `claude-code`，与现有 SkillPlugin 安装行为保持一致。
+   * - 留空时不向底层 skill installer 传递 `--agent`。
+   * - 只有需要显式指定 installer 目标时才传入。
    */
   agent?: string;
   /**
@@ -62,4 +63,3 @@ export interface WebPluginInstallPayload {
    */
   [key: string]: JsonValue | undefined;
 }
-

package/src/workboard/Plugin.ts

@@ -2,105 +2,33 @@
  * Workboard Plugin。
  *
  * 关键点（中文）
- * - workboard 是一个 runtime 观测面板插件，负责提供结构化工作快照。
- * - 当前同时通过 plugin action 与 HTTP 注入提供快照，供 Town RPC 与 Town HTTP gateway 复用。
+ * - workboard 是 runtime 观测面板插件，负责提供结构化工作快照。
+ * - plugin action 与 HTTP route 共享同一份快照读取逻辑。
+ * - 是否启用由是否注册该 plugin 决定，不再读取项目配置做二次开关。
  */
 
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
-import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type {
+  PluginActions,
+  PluginHttpDefinition,
+} 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 { isPluginEnabled } from "@downcity/agent/internal/plugin/core/Activation.js";
 import { getWorkboardSnapshotStore } from "@/workboard/runtime/Store.js";
 import type { WorkboardSnapshotResponse } from "@/workboard/types/Workboard.js";
 
-function createWorkboardPluginDefinition(plugin: Plugin): Plugin {
+/**
+ * 读取 workboard 快照。
+ */
+async function readWorkboardSnapshot(
+  context: AgentContext,
+): Promise<WorkboardSnapshotResponse> {
+  const snapshot = await getWorkboardSnapshotStore({
+    contextResolver: () => context,
+  }).readSnapshot();
   return {
-    name: "workboard",
-    title: "Workboard Snapshot",
-    description:
-      "Collects structured runtime activity snapshots so console surfaces can show what the current agent is doing now and what it recently worked on.",
-    availability(context) {
-      if (!isPluginEnabled({ plugin, context })) {
-        return {
-          enabled: false,
-          available: false,
-          reasons: ["workboard plugin disabled in project config"],
-        };
-      }
-      return {
-        enabled: true,
-        available: true,
-        reasons: [],
-      };
-    },
-    actions: {
-      snapshot: {
-        execute: async ({ context }) => {
-          const availability = await plugin.availability?.(context);
-          if (availability && availability.available !== true) {
-            return {
-              success: false,
-              error: availability.reasons.join("; ") || "workboard unavailable",
-            };
-          }
-
-          const snapshot = await getWorkboardSnapshotStore({
-            contextResolver: () => context,
-          }).readSnapshot();
-          return {
-            success: true,
-            data: {
-              snapshot,
-            } as unknown as JsonValue,
-          };
-        },
-      },
-    },
-    http: {
-      server: {
-        authPolicies: [
-          {
-            path: "/api/workboard/*",
-            method: "GET",
-            requireAuth: true,
-            anyPermissions: ["agent.read"],
-          },
-        ],
-        register({ app, getContext }) {
-          app.get("/api/workboard/snapshot", async (c) => {
-            try {
-              const availability = await plugin.availability?.(getContext());
-              if (availability && availability.available !== true) {
-                return c.json(
-                  {
-                    success: false,
-                    error: availability.reasons.join("; ") || "workboard unavailable",
-                  },
-                  503,
-                );
-              }
-
-              const snapshot = await getWorkboardSnapshotStore({
-                contextResolver: getContext,
-              }).readSnapshot();
-              const payload: WorkboardSnapshotResponse = {
-                success: true,
-                snapshot,
-              };
-              return c.json(payload);
-            } catch (error) {
-              return c.json(
-                {
-                  success: false,
-                  error: error instanceof Error ? error.message : String(error),
-                },
-                500,
-              );
-            }
-          });
-        },
-      },
-    },
+    success: true,
+    snapshot,
   };
 }
 
@@ -108,10 +36,67 @@ function createWorkboardPluginDefinition(plugin: Plugin): Plugin {
  * WorkboardPlugin：运行态观测面板插件。
  */
 export class WorkboardPlugin extends BasePlugin {
+  /**
+   * 当前 plugin 稳定名称。
+   */
   readonly name = "workboard";
 
-  constructor() {
-    super();
-    Object.assign(this, createWorkboardPluginDefinition(this));
-  }
+  /**
+   * 插件标题。
+   */
+  readonly title = "Workboard Snapshot";
+
+  /**
+   * 插件说明。
+   */
+  readonly description =
+    "Collects structured runtime activity snapshots so console surfaces can show what the current agent is doing now and what it recently worked on.";
+
+  /**
+   * Workboard 对外 action。
+   */
+  readonly actions: PluginActions = {
+    snapshot: {
+      execute: async ({ context }) => {
+        const response = await readWorkboardSnapshot(context);
+        return {
+          success: true,
+          data: {
+            snapshot: response.snapshot,
+          } as unknown as JsonValue,
+        };
+      },
+    },
+  };
+
+  /**
+   * Workboard HTTP route。
+   */
+  readonly http: PluginHttpDefinition = {
+    server: {
+      authPolicies: [
+        {
+          path: "/api/workboard/*",
+          method: "GET",
+          requireAuth: true,
+          anyPermissions: ["agent.read"],
+        },
+      ],
+      register({ app, getContext }) {
+        app.get("/api/workboard/snapshot", async (c) => {
+          try {
+            return c.json(await readWorkboardSnapshot(getContext()));
+          } catch (error) {
+            return c.json(
+              {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+              },
+              500,
+            );
+          }
+        });
+      },
+    },
+  };
 }