@coze-arch/cli 0.0.18 → 0.0.19-beta.1

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

@@ -0,0 +1,218 @@
+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;
+  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/docs.ts

@@ -0,0 +1,204 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+export type DashboardDocSummary = {
+  slug: string;
+  title: string;
+  summary: string;
+  group: string;
+  order: number;
+  updatedAt: string;
+};
+
+export type DashboardDocDetail = DashboardDocSummary & {
+  content: string;
+};
+
+export type DashboardDocsResponse = {
+  docs: DashboardDocSummary[];
+  selectedDoc: DashboardDocDetail | null;
+  requestedSlug?: string;
+  requestedSlugFound: boolean;
+};
+
+type ParsedFrontmatter = {
+  title?: string;
+  summary?: string;
+  group?: string;
+  order?: number;
+};
+
+function listMarkdownFiles(rootDir: string): string[] {
+  if (!existsSync(rootDir)) {
+    return [];
+  }
+
+  const entries = readdirSync(rootDir, { withFileTypes: true }).sort((left, right) =>
+    left.name.localeCompare(right.name)
+  );
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listMarkdownFiles(fullPath));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function stripQuotes(value: string): string {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function parseFrontmatter(raw: string): { meta: ParsedFrontmatter; content: string } {
+  const normalized = raw.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { meta: {}, content: raw };
+  }
+
+  const lines = normalized.split("\n");
+  let closingIndex = -1;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index]?.trim() === "---") {
+      closingIndex = index;
+      break;
+    }
+  }
+
+  if (closingIndex === -1) {
+    return { meta: {}, content: raw };
+  }
+
+  const meta: ParsedFrontmatter = {};
+  for (const line of lines.slice(1, closingIndex)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const match = trimmed.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!match) continue;
+
+    const key = match[1]!;
+    const value = stripQuotes(match[2]!.trim());
+    if (!value) continue;
+
+    if (key === "order") {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) {
+        meta.order = parsed;
+      }
+      continue;
+    }
+
+    if (key === "title") meta.title = value;
+    if (key === "summary") meta.summary = value;
+    if (key === "group") meta.group = value;
+  }
+
+  return {
+    meta,
+    content: lines.slice(closingIndex + 1).join("\n").trimStart(),
+  };
+}
+
+function extractHeading(content: string): string {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  for (const line of lines) {
+    const match = line.trim().match(/^#\s+(.+)$/);
+    if (match) {
+      return match[1]!.trim();
+    }
+  }
+  return "";
+}
+
+function extractSummary(content: string): string {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  const paragraph: string[] = [];
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      if (paragraph.length > 0) break;
+      continue;
+    }
+    if (trimmed.startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      if (paragraph.length > 0) break;
+      continue;
+    }
+    if (inCodeBlock) continue;
+    if (trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith("- ") || trimmed.startsWith("* ") || /^\d+\.\s/.test(trimmed)) {
+      continue;
+    }
+
+    paragraph.push(trimmed.replace(/^>\s?/, ""));
+  }
+
+  return paragraph.join(" ").trim();
+}
+
+function createTitleFromSlug(slug: string): string {
+  const tail = slug.split("/").at(-1) ?? slug;
+  return tail
+    .split(/[-_]/g)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function loadDoc(filePath: string, docsDir: string): DashboardDocDetail {
+  const relativePath = relative(docsDir, filePath).split(sep).join("/");
+  const slug = relativePath.replace(/\.md$/i, "");
+  const raw = readFileSync(filePath, "utf-8");
+  const parsed = parseFrontmatter(raw);
+  const title = parsed.meta.title?.trim() || extractHeading(parsed.content) || createTitleFromSlug(slug);
+  const summary = parsed.meta.summary?.trim() || extractSummary(parsed.content);
+  const group = parsed.meta.group?.trim() || "其他";
+  const order = parsed.meta.order ?? Number.MAX_SAFE_INTEGER;
+  const updatedAt = statSync(filePath).mtime.toISOString();
+
+  return {
+    slug,
+    title,
+    summary,
+    group,
+    order,
+    updatedAt,
+    content: parsed.content,
+  };
+}
+
+export function readDocsResponse(args: { docsDir: string; slug?: string }): DashboardDocsResponse {
+  const docs = listMarkdownFiles(args.docsDir)
+    .map((filePath) => loadDoc(filePath, args.docsDir))
+    .sort((left, right) => {
+      if (left.order !== right.order) return left.order - right.order;
+      return left.title.localeCompare(right.title);
+    });
+
+  const requestedSlug = args.slug?.trim();
+  const selectedDoc = requestedSlug
+    ? docs.find((doc) => doc.slug === requestedSlug) ?? docs[0] ?? null
+    : docs[0] ?? null;
+
+  return {
+    docs: docs.map(({ content: _content, ...summary }) => summary),
+    selectedDoc,
+    requestedSlug,
+    requestedSlugFound: requestedSlug ? selectedDoc?.slug === requestedSlug : true,
+  };
+}

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) },
+    ],
+  };
+}