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

package/lib/__templates__/pi-agent/src/session-store.ts

@@ -0,0 +1,223 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { CURRENT_SESSION_VERSION } from "@mariozechner/pi-coding-agent";
+
+export type SessionRecord = {
+  sessionKey: string;
+  keyHash: string;
+  sessionId: string;
+  sessionFile: string;
+  updatedAt: number;
+};
+
+type IndexFileShapeV1 = {
+  version: 1;
+  updatedAt: number;
+  sessions: Record<
+    string,
+    {
+      keyHash: string;
+      sessionId: string;
+      sessionFile: string;
+      updatedAt: number;
+    }
+  >;
+};
+
+function sha256Hex(input: string): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+function safeRename(from: string, to: string): void {
+  try {
+    fs.renameSync(from, to);
+  } catch {
+    // best-effort
+  }
+}
+
+function ensureDir(dirPath: string): void {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readJsonFile(filePath: string): unknown {
+  const raw = fs.readFileSync(filePath, "utf-8");
+  return JSON.parse(raw) as unknown;
+}
+
+function writeFileAtomic(filePath: string, content: string, mode: number): void {
+  const dir = path.dirname(filePath);
+  ensureDir(dir);
+  const tmpPath = `${filePath}.tmp`;
+  fs.writeFileSync(tmpPath, content, { encoding: "utf-8", mode });
+  fs.renameSync(tmpPath, filePath);
+}
+
+function ensureTranscriptHeader(params: { sessionFile: string; sessionId: string }): void {
+  if (fs.existsSync(params.sessionFile)) {
+    return;
+  }
+  ensureDir(path.dirname(params.sessionFile));
+  const header = {
+    type: "session",
+    version: CURRENT_SESSION_VERSION,
+    id: params.sessionId,
+    timestamp: new Date().toISOString(),
+    cwd: process.cwd(),
+  };
+  fs.writeFileSync(params.sessionFile, `${JSON.stringify(header)}\n`, {
+    encoding: "utf-8",
+    mode: 0o600,
+  });
+}
+
+function decodeIndexFileShapeV1(value: unknown): IndexFileShapeV1 | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const rec = value as Record<string, unknown>;
+  if (rec.version !== 1) return null;
+  if (!("sessions" in rec) || !rec.sessions || typeof rec.sessions !== "object" || Array.isArray(rec.sessions)) {
+    return null;
+  }
+  const updatedAt = typeof rec.updatedAt === "number" ? rec.updatedAt : Date.now();
+  const sessions = rec.sessions as Record<string, unknown>;
+  const out: IndexFileShapeV1["sessions"] = {};
+  for (const [sessionKey, entry] of Object.entries(sessions)) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const e = entry as Record<string, unknown>;
+    const keyHash = typeof e.keyHash === "string" ? e.keyHash : "";
+    const sessionId = typeof e.sessionId === "string" ? e.sessionId : "";
+    const sessionFile = typeof e.sessionFile === "string" ? e.sessionFile : "";
+    const entryUpdatedAt = typeof e.updatedAt === "number" ? e.updatedAt : updatedAt;
+    if (!sessionKey || !keyHash || !sessionId || !sessionFile) continue;
+    out[sessionKey] = { keyHash, sessionId, sessionFile, updatedAt: entryUpdatedAt };
+  }
+  return { version: 1, updatedAt, sessions: out };
+}
+
+export class SessionStore {
+  private readonly sessionsDir: string;
+  private readonly indexPath: string;
+  private readonly transcriptsDir: string;
+  private readonly archiveDir: string;
+  private readonly cache = new Map<string, SessionRecord>();
+
+  constructor(private readonly agentDir: string) {
+    this.sessionsDir = path.join(agentDir, ".pi-bot", "sessions");
+    this.indexPath = path.join(this.sessionsDir, "index.json");
+    this.transcriptsDir = path.join(this.sessionsDir, "transcripts");
+    this.archiveDir = path.join(this.sessionsDir, "archive");
+  }
+
+  load(): void {
+    this.cache.clear();
+
+    if (!fs.existsSync(this.indexPath)) {
+      return;
+    }
+
+    try {
+      const decoded = decodeIndexFileShapeV1(readJsonFile(this.indexPath));
+      if (!decoded) {
+        throw new Error("invalid index.json schema");
+      }
+      for (const [sessionKey, entry] of Object.entries(decoded.sessions)) {
+        this.cache.set(sessionKey, {
+          sessionKey,
+          keyHash: entry.keyHash,
+          sessionId: entry.sessionId,
+          sessionFile: entry.sessionFile,
+          updatedAt: entry.updatedAt,
+        });
+      }
+    } catch {
+      // Keep a corrupt copy for debugging instead of crashing startup.
+      safeRename(this.indexPath, `${this.indexPath}.corrupt-${Date.now()}`);
+      this.cache.clear();
+    }
+  }
+
+  listSessionKeys(): string[] {
+    return Array.from(this.cache.keys());
+  }
+
+  get(sessionKey: string): SessionRecord | undefined {
+    return this.cache.get(sessionKey);
+  }
+
+  ensureSession(sessionKey: string): SessionRecord {
+    const existing = this.cache.get(sessionKey);
+    if (existing) {
+      // If the transcript was deleted externally, recreate the header so the
+      // session remains recoverable.
+      ensureTranscriptHeader({ sessionFile: existing.sessionFile, sessionId: existing.sessionId });
+      return existing;
+    }
+
+    const now = Date.now();
+    const keyHash = sha256Hex(sessionKey);
+    const sessionId = randomUUID();
+    const sessionFile = path.join(this.transcriptsDir, `${keyHash}-${sessionId}.jsonl`);
+    const record: SessionRecord = {
+      sessionKey,
+      keyHash,
+      sessionId,
+      sessionFile,
+      updatedAt: now,
+    };
+    this.cache.set(sessionKey, record);
+    ensureTranscriptHeader({ sessionFile, sessionId });
+    this.saveIndex();
+    return record;
+  }
+
+  resetSession(sessionKey: string): SessionRecord {
+    const prior = this.cache.get(sessionKey);
+    if (prior && fs.existsSync(prior.sessionFile)) {
+      ensureDir(this.archiveDir);
+      const baseName = path.basename(prior.sessionFile);
+      const archivedBase = baseName.endsWith(".jsonl") ? baseName : `${baseName}.jsonl`;
+      const archivedPathCandidate = path.join(this.archiveDir, archivedBase);
+      const archivedPath = fs.existsSync(archivedPathCandidate)
+        ? path.join(this.archiveDir, `${prior.keyHash}-${prior.sessionId}-${Date.now()}.jsonl`)
+        : archivedPathCandidate;
+      safeRename(prior.sessionFile, archivedPath);
+    }
+
+    // Keep keyHash stable for this sessionKey, rotate sessionId + sessionFile.
+    const now = Date.now();
+    const keyHash = prior?.keyHash ?? sha256Hex(sessionKey);
+    const sessionId = randomUUID();
+    const sessionFile = path.join(this.transcriptsDir, `${keyHash}-${sessionId}.jsonl`);
+    const next: SessionRecord = {
+      sessionKey,
+      keyHash,
+      sessionId,
+      sessionFile,
+      updatedAt: now,
+    };
+    this.cache.set(sessionKey, next);
+    ensureTranscriptHeader({ sessionFile, sessionId });
+    this.saveIndex();
+    return next;
+  }
+
+  private saveIndex(): void {
+    const now = Date.now();
+    const sessions: IndexFileShapeV1["sessions"] = {};
+    for (const [sessionKey, entry] of this.cache.entries()) {
+      sessions[sessionKey] = {
+        keyHash: entry.keyHash,
+        sessionId: entry.sessionId,
+        sessionFile: entry.sessionFile,
+        updatedAt: entry.updatedAt,
+      };
+    }
+    const payload: IndexFileShapeV1 = {
+      version: 1,
+      updatedAt: now,
+      sessions,
+    };
+    writeFileAtomic(this.indexPath, JSON.stringify(payload, null, 2), 0o600);
+  }
+}

package/lib/__templates__/pi-agent/src/tools/common/format-coze-error.ts

@@ -0,0 +1,12 @@
+export function formatCozeError(error: unknown): string {
+  if (error && typeof error === "object" && "message" in error) {
+    const message = String(error.message);
+    const status =
+      "statusCode" in error && typeof error.statusCode === "number" ? ` (${error.statusCode})` : "";
+    return `${message}${status}`;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

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

@@ -0,0 +1,2 @@
+export { cozeWebSearchTool } from "./web-search/index.js";
+export { cozeWebFetchTool } from "./web-fetch/index.js";

package/lib/__templates__/pi-agent/src/tools/web-fetch/index.ts

@@ -0,0 +1,195 @@
+import { type Static, Type } from "@sinclair/typebox";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { FetchClient, type FetchContentItem, type FetchResponse } from "coze-coding-dev-sdk";
+import { formatCozeError } from "../common/format-coze-error.js";
+
+type FetchResultLink = {
+  title?: string;
+  url?: string;
+};
+
+type FetchResultImage = {
+  url?: string;
+  width?: number;
+  height?: number;
+};
+
+type FetchResultItem = {
+  url: string;
+  title?: string;
+  text: string;
+  links: FetchResultLink[];
+  images: FetchResultImage[];
+};
+
+function joinText(items: FetchContentItem[]): string {
+  return items
+    .filter((item) => item.type === "text" && item.text)
+    .map((item) => item.text?.trim() ?? "")
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function collectLinks(items: FetchContentItem[]): FetchResultLink[] {
+  return items
+    .filter((item) => item.type === "link")
+    .map((item) => ({
+      title: item.text,
+      url: item.url,
+    }));
+}
+
+function collectImages(items: FetchContentItem[]): FetchResultImage[] {
+  return items
+    .filter((item) => item.type === "image")
+    .map((item) => ({
+      url: item.image?.display_url ?? item.image?.image_url,
+      width: item.image?.width,
+      height: item.image?.height,
+    }));
+}
+
+function normalizeFetchedItem(response: FetchResponse, textOnly: boolean): FetchResultItem {
+  const content = response.content ?? [];
+  return {
+    url: response.url ?? "",
+    title: response.title,
+    text: joinText(content),
+    links: textOnly ? [] : collectLinks(content),
+    images: textOnly ? [] : collectImages(content),
+  };
+}
+
+const MAX_CONCURRENCY = 5;
+
+async function fetchContent(
+  urls: string[],
+  textOnly: boolean,
+): Promise<FetchResultItem[]> {
+  const client = new FetchClient();
+  const results: FetchResultItem[] = new Array(urls.length);
+  let next = 0;
+
+  async function worker() {
+    while (next < urls.length) {
+      const idx = next++;
+      const response = await client.fetch(urls[idx]);
+      results[idx] = normalizeFetchedItem(response, textOnly);
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENCY, urls.length) }, () => worker()));
+
+  return results;
+}
+
+const FetchToolSchema = Type.Object(
+  {
+    urls: Type.Union(
+      [
+        Type.String({ description: "Single URL to fetch." }),
+        Type.Array(Type.String({ description: "URL to fetch." }), {
+          description: "One or more URLs to fetch.",
+          minItems: 1,
+        }),
+      ],
+      {
+        description:
+          "URL input. Accepts either a single URL string or an array of URL strings.",
+      },
+    ),
+    format: Type.Optional(
+      Type.Unsafe<"text" | "markdown" | "json">({
+        type: "string",
+        enum: ["text", "markdown", "json"],
+        description: "Formatting preference for the textual output.",
+      }),
+    ),
+    textOnly: Type.Optional(
+      Type.Boolean({ description: "Only return extracted text, without images or links." }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+function renderFetchedText(items: FetchResultItem[], format: "text" | "markdown" | "json"): string {
+  if (format === "json") {
+    return JSON.stringify(items, null, 2);
+  }
+
+  if (format === "markdown") {
+    return items
+      .map((item) => {
+        const lines: string[] = [];
+        lines.push(`# ${item.title ?? "Untitled"}`);
+        lines.push(`URL: ${item.url}`);
+        lines.push("", item.text);
+        if (item.links.length > 0) {
+          const validLinks = item.links.filter((link) => link.url);
+          if (validLinks.length > 0) {
+            lines.push("", "## Links");
+            for (const link of validLinks) {
+              lines.push(`- [${link.title ?? link.url}](${link.url})`);
+            }
+          }
+        }
+        return lines.join("\n");
+      })
+      .join("\n\n---\n\n");
+  }
+
+  return items
+    .map((item, index) => {
+      const lines: string[] = [];
+      lines.push(`${index + 1}. ${item.title ?? "Untitled"}`);
+      lines.push(`   URL: ${item.url}`);
+      lines.push(`   ${item.text}`);
+      if (item.links.length > 0) {
+        const validLinks = item.links.filter((link) => link.url);
+        if (validLinks.length > 0) {
+          lines.push("   Links:");
+          for (const link of validLinks) {
+            lines.push(`   - ${link.title ?? link.url}: ${link.url}`);
+          }
+        }
+      }
+      if (item.images.length > 0) {
+        lines.push("   Images:");
+        for (const img of item.images) {
+          lines.push(`   - ${img.url}${typeof img.width === "number" && typeof img.height === "number" ? ` (${img.width}x${img.height})` : ""}`);
+        }
+      }
+      return lines.join("\n");
+    })
+    .join("\n\n");
+}
+
+export const cozeWebFetchTool: ToolDefinition = {
+  name: "coze_web_fetch",
+  label: "Coze Web Fetch",
+  description:
+    "Fetch and extract structured content from web pages or documents through Coze.",
+  parameters: FetchToolSchema,
+  async execute(_toolCallId, rawParams) {
+    const params = rawParams as Static<typeof FetchToolSchema>;
+    const urls = typeof params.urls === "string" ? [params.urls] : params.urls;
+    const textOnly = params.textOnly === true;
+    console.log("[coze_web_fetch] urls=%s textOnly=%s format=%s", urls.join(", "), textOnly, params.format ?? "text");
+    try {
+      const items = await fetchContent(urls, textOnly);
+      console.log("[coze_web_fetch] done, %d pages fetched", items.length);
+      const format = params.format ?? "text";
+      return {
+        content: [{ type: "text", text: renderFetchedText(items, format) }],
+        details: { urls, format, count: items.length },
+      };
+    } catch (error) {
+      const message = formatCozeError(error);
+      console.error("[coze_web_fetch] error:", message);
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        details: { error: true, message },
+      };
+    }
+  },
+};

package/lib/__templates__/pi-agent/src/tools/web-search/index.ts

@@ -0,0 +1,206 @@
+import { type Static, Type } from "@sinclair/typebox";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { SearchClient, type ImageItem, type SearchResponse, type WebItem } from "coze-coding-dev-sdk";
+import { formatCozeError } from "../common/format-coze-error.js";
+
+type SearchResultItem = {
+  title: string;
+  url?: string;
+  siteName?: string;
+  snippet?: string;
+  content?: string;
+  publishTime?: string;
+  imageUrl?: string;
+  imageWidth?: number;
+  imageHeight?: number;
+};
+
+type SearchResult = {
+  query: string;
+  type: "web" | "image";
+  summary?: string;
+  items: SearchResultItem[];
+};
+
+function mapWebItem(item: WebItem): SearchResultItem {
+  return {
+    title: item.title,
+    url: item.url,
+    siteName: item.site_name,
+    snippet: item.snippet,
+    content: item.content,
+    publishTime: item.publish_time,
+  };
+}
+
+function mapImageItem(item: ImageItem): SearchResultItem {
+  return {
+    title: item.title ?? "Untitled",
+    url: item.url,
+    siteName: item.site_name,
+    publishTime: item.publish_time,
+    imageUrl: item.image?.url,
+    imageWidth: item.image?.width,
+    imageHeight: item.image?.height,
+  };
+}
+
+type SearchInput = {
+  query: string;
+  type?: "web" | "image";
+  count?: number;
+  timeRange?: string;
+  sites?: string;
+  blockHosts?: string;
+  needSummary?: boolean;
+  needContent?: boolean;
+};
+
+async function searchWeb(input: SearchInput): Promise<SearchResult> {
+  const client = new SearchClient();
+  const type = input.type ?? "web";
+  const count = input.count ?? 10;
+  let response: SearchResponse;
+
+  if (type === "image") {
+    response = await client.imageSearch(input.query, count);
+    return {
+      query: input.query,
+      type,
+      items: (response.image_items ?? []).map(mapImageItem),
+    };
+  }
+
+  const hasAdvanced = Boolean(input.timeRange || input.sites || input.blockHosts || input.needContent);
+  if (hasAdvanced) {
+    response = await client.advancedSearch(input.query, {
+      searchType: "web",
+      count,
+      timeRange: input.timeRange,
+      sites: input.sites,
+      blockHosts: input.blockHosts,
+      needSummary: input.needSummary,
+      needContent: input.needContent,
+    });
+  } else {
+    response = await client.webSearch(input.query, count, input.needSummary);
+  }
+
+  return {
+    query: input.query,
+    type,
+    summary: response.summary,
+    items: (response.web_items ?? []).map(mapWebItem),
+  };
+}
+
+const SearchToolSchema = Type.Object(
+  {
+    query: Type.String({ description: "Search query." }),
+    type: Type.Optional(
+      Type.Unsafe<"web" | "image">({
+        type: "string",
+        enum: ["web", "image"],
+        description: "Search type. Defaults to web.",
+      }),
+    ),
+    count: Type.Optional(
+      Type.Integer({
+        description: "Number of results to return.",
+        minimum: 1,
+        maximum: 20,
+      }),
+    ),
+    timeRange: Type.Optional(
+      Type.Unsafe<"1d" | "1w" | "1m">({
+        type: "string",
+        enum: ["1d", "1w", "1m"],
+        description: "Recency filter for web search.",
+      }),
+    ),
+    sites: Type.Optional(
+      Type.String({ description: "Comma-separated domains to include." }),
+    ),
+    blockHosts: Type.Optional(
+      Type.String({ description: "Comma-separated domains to exclude." }),
+    ),
+    needSummary: Type.Optional(
+      Type.Boolean({ description: "Whether to include Coze summary output." }),
+    ),
+    needContent: Type.Optional(
+      Type.Boolean({ description: "Whether to include extracted page content." }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+function buildSearchText(
+  result: SearchResult,
+  options: { includeContent: boolean },
+): string {
+  const lines = [`Coze web search: ${result.query}`];
+  if (result.summary) {
+    lines.push("", `Summary: ${result.summary}`);
+  }
+  lines.push("", `Results (${result.items.length})`);
+  for (const [index, item] of result.items.entries()) {
+    lines.push(`${index + 1}. ${item.title}`);
+    if (item.url) {
+      lines.push(`   URL: ${item.url}`);
+    }
+    if (item.imageUrl) {
+      lines.push(`   Image: ${item.imageUrl}`);
+    }
+    if (item.siteName) {
+      lines.push(`   Source: ${item.siteName}`);
+    }
+    if (item.publishTime) {
+      lines.push(`   Published: ${item.publishTime}`);
+    }
+    if (item.snippet) {
+      lines.push(`   ${item.snippet}`);
+    }
+    if (options.includeContent && item.content) {
+      lines.push("   Content:");
+      lines.push(`   ${item.content}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export const cozeWebSearchTool: ToolDefinition = {
+  name: "coze_web_search",
+  label: "Coze Web Search",
+  description:
+    "Search the web or images through Coze. Supports summaries, recency filters, and site restrictions.",
+  parameters: SearchToolSchema,
+  async execute(_toolCallId, rawParams) {
+    const params = rawParams as Static<typeof SearchToolSchema>;
+    console.log("[coze_web_search] query=%s type=%s count=%s", params.query, params.type ?? "web", params.count ?? 10);
+    try {
+      const result = await searchWeb(params);
+      console.log("[coze_web_search] done, %d results", result.items.length);
+      return {
+        content: [
+          {
+            type: "text",
+            text: buildSearchText(result, { includeContent: params.needContent === true }),
+          },
+        ],
+        details: {
+          query: result.query,
+          type: result.type,
+          summary: result.summary,
+          count: result.items.length,
+        },
+      };
+    } catch (error) {
+      const message = formatCozeError(error);
+      console.error("[coze_web_search] error:", message);
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        details: { error: true, message },
+      };
+    }
+  },
+};

package/lib/__templates__/pi-agent/template.config.js

@@ -0,0 +1,45 @@
+
+
+
+
+
+
+
+
+
+export const paramsSchema = {
+  type: 'object',
+  properties: {
+    port: {
+      type: 'number',
+      default: 5000,
+      minimum: 1024,
+      maximum: 65535,
+      description: 'Dashboard server port',
+    },
+    workspaceDir: {
+      type: 'string',
+      default: '/workspace/workspace',
+      description: 'Workspace directory path',
+    },
+  },
+  required: [],
+  additionalProperties: false,
+};
+
+const config = {
+  description:
+    'Pi Agent：`coze init ${COZE_WORKSPACE_PATH} --template pi-agent`\n' +
+    '- 适用：基于 pi-agent-core 的 AI Agent 应用\n' +
+    '- 支持飞书、微信等多渠道接入\n' +
+    '- 内置 Dashboard 管理面板\n' +
+    '- 使用 TypeScript + Express + Vite',
+  paramsSchema,
+
+  defaultParams: {
+    port: 5000,
+    workspaceDir: '/workspace/workspace',
+  },
+};
+
+export default config;