@coze-arch/cli 0.0.18 → 0.0.19-alpha.502ddf

package/lib/__templates__/pi-agent/src/core.ts

@@ -0,0 +1,219 @@
+export type ChannelName = "feishu" | "wechat" | "dashboard";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export type AgentMode = "mock" | "pi";
+
+export interface BotMessage {
+  // A channel package must normalize platform-specific payloads into this shape
+  // before handing control to the app runtime.
+  channel: ChannelName;
+  conversationId: string;
+  senderId: string;
+  messageId: string;
+  text: string;
+  isDirectMessage: boolean;
+  mentions: string[];
+  threadId?: string;
+  raw?: unknown;
+}
+
+export interface BotReply {
+  text: string;
+}
+
+export type ChannelReply = string | BotReply | null | void;
+
+export interface ChannelStreamHandlers {
+  onMeta?(meta: { sessionKey: string }): void;
+  onDelta?(delta: string): void;
+  onError?(error: string): void;
+}
+
+export interface ChannelHandler {
+  onMessage?(message: BotMessage): Promise<ChannelReply> | ChannelReply;
+  onStreamMessage?(
+    message: BotMessage,
+    handlers: ChannelStreamHandlers
+  ): Promise<ChannelReply> | ChannelReply;
+}
+
+export interface ChannelInstance {
+  name: ChannelName;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+export interface ChannelTransport<TOutgoingMessage> {
+  start?(): Promise<void> | void;
+  stop?(): Promise<void> | void;
+  send?(message: TOutgoingMessage): Promise<void> | void;
+}
+
+export interface RoutingGateConfig {
+  requireMention?: boolean;
+}
+
+export interface SessionStore<TValue> {
+  get(key: string): TValue | undefined;
+  set(key: string, value: TValue): TValue;
+  has(key: string): boolean;
+  delete(key: string): boolean;
+  clear(): void;
+  entries(): Array<[string, TValue]>;
+}
+
+export interface AgentRuntime {
+  // App projects own the agent runtime on purpose. We keep it out of channel/core
+  // so future work can use raw pi-coding-agent APIs directly.
+  run(message: BotMessage): Promise<string>;
+  dispose(): Promise<void>;
+}
+
+export interface AgentRuntimeConfig {
+  mode: AgentMode;
+  provider?: string;
+  model?: string;
+  configPath?: string;
+  thinkingLevel?: ThinkingLevel;
+  baseUrl?: string;
+  cwd?: string;
+  agentDir?: string;
+}
+
+export interface BotChannelConfig {
+  enabled: boolean;
+}
+
+export interface FeishuBotChannelConfig extends BotChannelConfig {
+  appId?: string;
+  appSecret?: string;
+  domain?: string;
+  encryptKey?: string;
+  verificationToken?: string;
+  thinkingReaction?: {
+    enabled?: boolean;
+    emojiType?: string;
+  };
+}
+
+export interface WechatBotChannelConfig extends BotChannelConfig {
+  implementation?: "mock";
+}
+
+export interface BotRoutingConfig {
+  feishuGroupRequireMention: boolean;
+  wechatGroupRequireMention: boolean;
+}
+
+export interface BotAppConfig {
+  appName: string;
+  configRoot?: Record<string, unknown>;
+  agent: AgentRuntimeConfig;
+  routing: BotRoutingConfig;
+  channels: {
+    feishu?: FeishuBotChannelConfig;
+    wechat?: WechatBotChannelConfig;
+  };
+}
+
+export function normalizeReply(reply: ChannelReply): BotReply | null {
+  if (reply == null) return null;
+  if (typeof reply === "string") return { text: reply };
+  if (typeof reply === "object" && typeof reply.text === "string") {
+    return { text: reply.text };
+  }
+
+  throw new TypeError("Reply must be a string, an object with a text field, or null.");
+}
+
+export function assertBotMessage(message: unknown): asserts message is BotMessage {
+  if (!message || typeof message !== "object") {
+    throw new TypeError("BotMessage must be an object.");
+  }
+
+  const requiredFields: Array<keyof BotMessage> = [
+    "channel",
+    "conversationId",
+    "senderId",
+    "messageId",
+    "text",
+    "isDirectMessage",
+    "mentions"
+  ];
+
+  for (const field of requiredFields) {
+    if (!(field in message)) {
+      throw new TypeError(`BotMessage is missing required field: ${field}`);
+    }
+  }
+}
+
+export function getSessionKey(message: BotMessage): string {
+  assertBotMessage(message);
+
+  // Session routing is deterministic and host-controlled.
+  // The model never decides where a message should be threaded.
+  if (message.isDirectMessage) {
+    return `${message.channel}:dm:${message.senderId}`;
+  }
+
+  if (message.threadId) {
+    return `${message.channel}:thread:${message.conversationId}:${message.threadId}`;
+  }
+
+  return `${message.channel}:group:${message.conversationId}`;
+}
+
+export function shouldHandleGroupMessage(
+  message: BotMessage,
+  routing: RoutingGateConfig = {}
+): boolean {
+  assertBotMessage(message);
+
+  // Mention gating lives in the host/channel layer, not in the model prompt.
+  if (message.isDirectMessage) return true;
+  if (!routing.requireMention) return true;
+
+  return Array.isArray(message.mentions) && message.mentions.length > 0;
+}
+
+export function createInMemorySessionStore<TValue>(): SessionStore<TValue> {
+  const sessions = new Map<string, TValue>();
+
+  return {
+    get(key) {
+      return sessions.get(key);
+    },
+    set(key, value) {
+      sessions.set(key, value);
+      return value;
+    },
+    has(key) {
+      return sessions.has(key);
+    },
+    delete(key) {
+      return sessions.delete(key);
+    },
+    clear() {
+      sessions.clear();
+    },
+    entries() {
+      return Array.from(sessions.entries());
+    }
+  };
+}
+
+export function createBotMessage(overrides: Partial<BotMessage> = {}): BotMessage {
+  return {
+    channel: overrides.channel ?? "feishu",
+    conversationId: overrides.conversationId ?? "conversation-1",
+    senderId: overrides.senderId ?? "user-1",
+    messageId: overrides.messageId ?? `msg-${Date.now()}`,
+    text: overrides.text ?? "",
+    isDirectMessage: overrides.isDirectMessage ?? true,
+    mentions: overrides.mentions ?? [],
+    threadId: overrides.threadId,
+    raw: overrides.raw
+  };
+}

package/lib/__templates__/pi-agent/src/dashboard/api/channels.ts

@@ -0,0 +1,104 @@
+import {
+  getConfigStore,
+  type ConfigSource,
+} from "../config-store.js";
+import { updateString, updateBool } from "../../config.js";
+
+export type DashboardChannelsResponse = {
+  routing: {
+    feishuGroupRequireMention: boolean;
+    wechatGroupRequireMention: boolean;
+  };
+  feishu: {
+    enabled: boolean;
+    requireMention?: boolean;
+    appId?: string;
+    domain?: string;
+    encryptKey?: string;
+    verificationToken?: string;
+    appSecret?: string;
+    thinkingReaction?: {
+      enabled?: boolean;
+      emojiType?: string;
+    };
+  };
+  wechat: {
+    enabled: boolean;
+    requireMention?: boolean;
+    implementation?: string;
+  };
+};
+
+export type DashboardChannelsSaveRequest = {
+  channels: DashboardChannelsResponse;
+};
+
+export function readChannelsResponse(args: ConfigSource): DashboardChannelsResponse {
+  const root = getConfigStore(args).read();
+  const cfg = root as {
+    channels?: { feishu?: Record<string, unknown>; wechat?: Record<string, unknown> };
+  };
+  const feishuRaw = cfg.channels?.feishu ?? {};
+  const wechatRaw = cfg.channels?.wechat ?? {};
+
+  const feishuEnabled = Boolean((feishuRaw as { enabled?: unknown }).enabled);
+  const wechatEnabled = Boolean((wechatRaw as { enabled?: unknown }).enabled);
+  const feishuRequireMention = Boolean((feishuRaw as { requireMention?: unknown }).requireMention);
+  const wechatRequireMention = Boolean((wechatRaw as { requireMention?: unknown }).requireMention);
+
+  return {
+    routing: {
+      feishuGroupRequireMention: feishuRequireMention,
+      wechatGroupRequireMention: wechatRequireMention,
+    },
+    feishu: {
+      enabled: feishuEnabled,
+      requireMention: feishuRequireMention,
+      appId: (feishuRaw as { appId?: string }).appId,
+      domain: (feishuRaw as { domain?: string }).domain,
+      appSecret: (feishuRaw as { appSecret?: string }).appSecret,
+      encryptKey: (feishuRaw as { encryptKey?: string }).encryptKey,
+      verificationToken: (feishuRaw as { verificationToken?: string }).verificationToken,
+      thinkingReaction: (feishuRaw as { thinkingReaction?: unknown }).thinkingReaction as
+        | { enabled?: boolean; emojiType?: string }
+        | undefined,
+    },
+    wechat: {
+      enabled: wechatEnabled,
+      requireMention: wechatRequireMention,
+      implementation: (wechatRaw as { implementation?: string }).implementation,
+    },
+  };
+}
+
+export function saveChannelsRequest(args: ConfigSource & { body: DashboardChannelsSaveRequest }) {
+  const { channels } = args.body;
+  const configStore = getConfigStore(args);
+  const root = configStore.read();
+
+  updateBool(root, ["channels", "feishu", "enabled"], channels.feishu.enabled);
+  updateBool(root, ["channels", "feishu", "requireMention"], channels.feishu.requireMention);
+  updateString(root, ["channels", "feishu", "appId"], channels.feishu.appId);
+  updateString(root, ["channels", "feishu", "domain"], channels.feishu.domain);
+  updateString(root, ["channels", "feishu", "appSecret"], channels.feishu.appSecret);
+  updateString(root, ["channels", "feishu", "encryptKey"], channels.feishu.encryptKey);
+  updateString(root, ["channels", "feishu", "verificationToken"], channels.feishu.verificationToken);
+  if (channels.feishu.thinkingReaction) {
+    updateBool(
+      root,
+      ["channels", "feishu", "thinkingReaction", "enabled"],
+      channels.feishu.thinkingReaction.enabled,
+    );
+    updateString(
+      root,
+      ["channels", "feishu", "thinkingReaction", "emojiType"],
+      channels.feishu.thinkingReaction.emojiType,
+    );
+  }
+
+  updateBool(root, ["channels", "wechat", "enabled"], channels.wechat.enabled);
+  updateBool(root, ["channels", "wechat", "requireMention"], channels.wechat.requireMention);
+  updateString(root, ["channels", "wechat", "implementation"], channels.wechat.implementation);
+
+  configStore.write(root);
+}

package/lib/__templates__/pi-agent/src/dashboard/api/models.ts

@@ -0,0 +1,98 @@
+import {
+  getConfigStore,
+  type ConfigSource,
+} from "../config-store.js";
+import { ensureObject, readString, updateString } from "../../config.js";
+
+export type DashboardModelOption = {
+  value: string;
+  label: string;
+};
+
+export type DashboardModelsResponse = {
+  defaultModel: string;
+  options: DashboardModelOption[];
+};
+
+export type DashboardModelsSaveRequest = {
+  models: {
+    defaultModel: string;
+  };
+};
+
+export class ValidationError extends Error {
+  statusCode = 400 as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+function validateDefaultModel(args: { defaultModel: string; allowed: Set<string> }) {
+  if (typeof args.defaultModel !== "string") {
+    throw new ValidationError("Invalid payload.");
+  }
+
+  const defaultModel = args.defaultModel.trim();
+  if (!defaultModel) return;
+
+  const parts = defaultModel.split("/");
+  if (parts.length !== 2) {
+    throw new ValidationError(`Invalid defaultModel: "${args.defaultModel}". Expected "provider/model".`);
+  }
+
+  const providerId = parts[0] ?? "";
+  const modelId = parts[1] ?? "";
+  const idPattern = /^[A-Za-z0-9_.-]+$/;
+  if (!idPattern.test(providerId) || !idPattern.test(modelId)) {
+    throw new ValidationError(`Invalid defaultModel: "${args.defaultModel}". Expected "provider/model".`);
+  }
+
+  if (!args.allowed.has(defaultModel)) {
+    throw new ValidationError(`Invalid defaultModel: "${args.defaultModel}" is not in the configured model list.`);
+  }
+}
+
+export function readModelsResponse(args: ConfigSource): DashboardModelsResponse {
+  const root = getConfigStore(args).read();
+  const agents = ensureObject(root.agents);
+  const defaults = ensureObject(agents.defaults);
+  const defaultModel = readString(ensureObject(defaults.model).primary);
+  const providersRoot = ensureObject(ensureObject(root.models).providers);
+
+  const options = Object.entries(providersRoot).flatMap(([providerId, providerValue]) => {
+    const provider = ensureObject(providerValue);
+    const rawModels = Array.isArray(provider.models) ? provider.models : [];
+    return rawModels.flatMap((rawModel) => {
+      const model = ensureObject(rawModel);
+      const id = readString(model.id);
+      if (!id) {
+        return [];
+      }
+      const name = readString(model.name) || id;
+      return [
+        {
+          value: `${providerId}/${id}`,
+          label: `${providerId} / ${name}`,
+        },
+      ];
+    });
+  });
+
+  return {
+    defaultModel,
+    options,
+  };
+}
+
+export function saveModelsRequest(args: ConfigSource & { body: DashboardModelsSaveRequest }) {
+  const configStore = getConfigStore(args);
+  const root = configStore.read();
+  const current = readModelsResponse({ configStore });
+  const allowed = new Set(current.options.map((option) => option.value));
+  validateDefaultModel({ defaultModel: args.body.models.defaultModel, allowed });
+
+  updateString(root, ["agents", "defaults", "model", "primary"], args.body.models.defaultModel);
+
+  configStore.write(root);
+}

package/lib/__templates__/pi-agent/src/dashboard/api/overview.ts

@@ -0,0 +1,33 @@
+export type DashboardOverviewResponse = {
+  appName: string;
+  botStatus: string;
+  dashboardUrl: string;
+  agentMode: string;
+  workspaceDir: string;
+  agentDir: string;
+  enabledChannels: Array<{ id: string; enabled: boolean }>;
+};
+
+export function buildOverviewResponse(args: {
+  dashboardUrl: string;
+  dashboardStarted: boolean;
+  appName: string;
+  agentMode: string;
+  workspaceDir: string;
+  agentDir: string;
+  enabledChannels: { feishu: boolean; wechat: boolean };
+}): DashboardOverviewResponse {
+  const { dashboardUrl, dashboardStarted } = args;
+  return {
+    appName: args.appName,
+    botStatus: dashboardStarted ? "running" : "stopped",
+    dashboardUrl,
+    agentMode: args.agentMode,
+    workspaceDir: args.workspaceDir || "Not set",
+    agentDir: args.agentDir || "Not set",
+    enabledChannels: [
+      { id: "feishu", enabled: Boolean(args.enabledChannels.feishu) },
+      { id: "wechat", enabled: Boolean(args.enabledChannels.wechat) },
+    ],
+  };
+}

package/lib/__templates__/pi-agent/src/dashboard/config-store.ts

@@ -0,0 +1,64 @@
+import { readFileSync, writeFileSync } from "node:fs";
+
+export interface ConfigStore {
+  read(): Record<string, unknown>;
+  write(root: Record<string, unknown>): void;
+}
+
+export type ConfigSource =
+  | {
+      configPath: string;
+      configStore?: never;
+    }
+  | {
+      configPath?: never;
+      configStore: ConfigStore;
+    };
+
+function cloneConfig(root: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(root)) as Record<string, unknown>;
+}
+
+function ensureConfigRoot(value: unknown, source: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid config.json shape at ${source}`);
+  }
+  return value as Record<string, unknown>;
+}
+
+export function createFileConfigStore(configPath: string): ConfigStore {
+  return {
+    read() {
+      const raw = readFileSync(configPath, "utf-8");
+      return ensureConfigRoot(JSON.parse(raw) as unknown, configPath);
+    },
+    write(root) {
+      writeFileSync(configPath, `${JSON.stringify(root, null, 2)}\n`, "utf-8");
+    },
+  };
+}
+
+export function createMemoryConfigStore(
+  initialRoot: Record<string, unknown>,
+): ConfigStore & { snapshot(): Record<string, unknown> } {
+  let current = cloneConfig(initialRoot);
+
+  return {
+    read() {
+      return cloneConfig(current);
+    },
+    write(root) {
+      current = cloneConfig(root);
+    },
+    snapshot() {
+      return cloneConfig(current);
+    },
+  };
+}
+
+export function getConfigStore(source: ConfigSource): ConfigStore {
+  if (source.configStore) {
+    return source.configStore;
+  }
+  return createFileConfigStore(source.configPath);
+}

package/lib/__templates__/pi-agent/src/dashboard/index.ts

@@ -0,0 +1,74 @@
+import type { BotAppConfig } from "../core.js";
+import { createDashboardServer } from "./server.js";
+import type { DashboardServer } from "./types.js";
+import type { PiAgentRuntime } from "../agent.js";
+import {
+  createFileConfigStore,
+  createMemoryConfigStore,
+  type ConfigStore,
+} from "./config-store.js";
+
+function createFallbackConfigRoot(botConfig: BotAppConfig): Record<string, unknown> {
+  return {
+    agents: {
+      defaults: {
+        model: {
+          primary:
+            botConfig.agent.provider && botConfig.agent.model
+              ? `${botConfig.agent.provider}/${botConfig.agent.model}`
+              : ""
+        }
+      }
+    },
+    models: {
+      providers: {}
+    },
+    channels: {
+      feishu: {
+        enabled: botConfig.channels.feishu?.enabled ?? false,
+        requireMention: botConfig.routing.feishuGroupRequireMention,
+        appId: botConfig.channels.feishu?.appId,
+        appSecret: botConfig.channels.feishu?.appSecret,
+        domain: botConfig.channels.feishu?.domain,
+        encryptKey: botConfig.channels.feishu?.encryptKey,
+        verificationToken: botConfig.channels.feishu?.verificationToken,
+        thinkingReaction: {
+          enabled: botConfig.channels.feishu?.thinkingReaction?.enabled ?? true,
+          emojiType: botConfig.channels.feishu?.thinkingReaction?.emojiType
+        }
+      },
+      wechat: {
+        enabled: botConfig.channels.wechat?.enabled ?? false,
+        requireMention: botConfig.routing.wechatGroupRequireMention
+      }
+    }
+  };
+}
+
+export function createDashboard(args: {
+  botConfig: BotAppConfig;
+  channels: { feishu?: unknown; wechat?: unknown };
+  agentRuntime: PiAgentRuntime;
+  configStore?: ConfigStore;
+}): DashboardServer {
+  const configStore =
+    args.configStore ??
+    (args.botConfig.agent.configPath
+      ? createFileConfigStore(args.botConfig.agent.configPath)
+      : createMemoryConfigStore(args.botConfig.configRoot ?? createFallbackConfigRoot(args.botConfig)));
+
+  return createDashboardServer({
+    runtime: {
+      appName: args.botConfig.appName,
+      agentMode: args.botConfig.agent.mode,
+      workspaceDir: args.botConfig.agent.cwd ?? "",
+      agentDir: args.botConfig.agent.agentDir ?? "",
+      enabledChannels: {
+        feishu: Boolean(args.channels.feishu),
+        wechat: Boolean(args.channels.wechat),
+      },
+    },
+    agentRuntime: args.agentRuntime,
+    configStore,
+  });
+}