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

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/index.ts

@@ -4,47 +4,9 @@ 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 };
@@ -55,7 +17,10 @@ export function createDashboard(args: {
     args.configStore ??
     (args.botConfig.agent.configPath
       ? createFileConfigStore(args.botConfig.agent.configPath)
-      : createMemoryConfigStore(args.botConfig.configRoot ?? createFallbackConfigRoot(args.botConfig)));
+      : undefined);
+  if (!configStore) {
+    throw new Error("Missing botConfig.agent.configPath for dashboard.");
+  }
 
   return createDashboardServer({
     runtime: {

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

@@ -6,6 +6,7 @@ import express from "express";
 import { createServer as createViteServer, type ViteDevServer } from "vite";
 import { WebSocketServer, type RawData, type WebSocket } from "ws";
 import type { DashboardServer, DashboardServerOptions } from "./types.js";
+import { readDocsResponse } from "./api/docs.js";
 import { buildOverviewResponse } from "./api/overview.js";
 import { readChannelsResponse, saveChannelsRequest } from "./api/channels.js";
 import { ValidationError, readModelsResponse, saveModelsRequest } from "./api/models.js";
@@ -33,6 +34,8 @@ function readHost(explicitHost: string | undefined): string {
 }
 
 const DASHBOARD_DIR = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(DASHBOARD_DIR, "..", "..");
+const USER_DOCS_DIR = resolve(PROJECT_ROOT, "docs", "user");
 const WEB_ROOT = resolve(DASHBOARD_DIR, "web");
 const WEB_DIST = resolve(WEB_ROOT, "dist");
 
@@ -226,6 +229,15 @@ export function createDashboardServer(options: DashboardServerOptions): Dashboar
       }
     });
 
+    app.get("/api/docs", (req, res) => {
+      try {
+        const slug = typeof req.query.slug === "string" ? req.query.slug : undefined;
+        res.json(readDocsResponse({ docsDir: USER_DOCS_DIR, slug }));
+      } catch (err) {
+        res.status(500).json({ ok: false, error: String(err) });
+      }
+    });
+
     app.get("/api/chat/sessions", (_req, res) => {
       try {
         const sessions = options.agentRuntime.listSessionKeys();

package/lib/__templates__/pi-agent/src/dashboard/web/src/components/app-layout.tsx

@@ -1,9 +1,12 @@
 import React from "react";
 import {
+  BookOpenText as DocsIcon,
+  Cpu as CpuIcon,
   LayoutDashboard as OverviewIcon,
   Menu as MenuIcon,
   MessageSquare as MessageIcon,
   Moon as MoonIcon,
+  Settings as SettingsIcon,
   Sun as SunIcon,
 } from "lucide-react";
 import { NavLink, useLocation } from "react-router-dom";
@@ -15,6 +18,9 @@ import { useLocalStorageState } from "../hooks/use-local-storage-state";
 const navItems = [
   { to: "/chat", label: "聊天", icon: MessageIcon },
   { to: "/overview", label: "概览", icon: OverviewIcon },
+  { to: "/docs", label: "文档", icon: DocsIcon },
+  { to: "/models", label: "模型", icon: CpuIcon },
+  { to: "/channels", label: "渠道", icon: SettingsIcon },
 ];
 
 export function AppLayout(props: { children: React.ReactNode }) {
@@ -126,7 +132,15 @@ export function AppLayout(props: { children: React.ReactNode }) {
         ) : null}
 
         <div className="flex min-h-0 flex-1 items-stretch">
-          <aside className="hidden shrink-0 p-3 md:block">
+          <aside className="hidden shrink-0 p-2 md:block xl:hidden">
+            <nav className="grid gap-1">
+              {navItems.map((item) => (
+                <NavItem key={item.to} item={item} compact={true} />
+              ))}
+            </nav>
+          </aside>
+
+          <aside className="hidden shrink-0 p-3 xl:block">
             <nav className="grid gap-1">
               {navItems.map((item) => (
                 <NavItem key={item.to} item={item} compact={false} />

package/lib/__templates__/pi-agent/src/dashboard/web/src/main.tsx

@@ -4,7 +4,10 @@ import "./styles.css";
 import "streamdown/styles.css";
 import { AppLayout } from "./components/app-layout";
 import { OverviewPage } from "./pages/overview-page";
+import { ChannelsPage } from "./pages/channels-page";
 import { ChatPage } from "./pages/chat-page";
+import { DocsPage } from "./pages/docs-page";
+import { ModelsPage } from "./pages/models-page";
 
 function App() {
   return (
@@ -13,6 +16,9 @@ function App() {
         <Routes>
           <Route path="/" element={<Navigate to="/chat" replace />} />
           <Route path="/overview" element={<OverviewPage />} />
+          <Route path="/docs" element={<DocsPage />} />
+          <Route path="/models" element={<ModelsPage />} />
+          <Route path="/channels" element={<ChannelsPage />} />
           <Route path="/chat" element={<ChatPage />} />
         </Routes>
       </AppLayout>

package/lib/__templates__/pi-agent/src/dashboard/web/src/pages/channels-page.tsx

@@ -0,0 +1,188 @@
+import React from "react";
+import { Alert, AlertDescription, AlertTitle } from "../components/ui/alert";
+import { Button } from "../components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../components/ui/card";
+import { Input } from "../components/ui/input";
+import { Label } from "../components/ui/label";
+import { useFetch } from "../hooks/use-fetch";
+import { toast } from "sonner";
+import { Link } from "react-router-dom";
+
+type Channels = {
+  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 function ChannelsPage() {
+  const { data, error, loading } = useFetch<Channels>("/api/channels");
+  const [saving, setSaving] = React.useState(false);
+  const [form, setForm] = React.useState<Channels | null>(null);
+
+  React.useEffect(() => {
+    if (data) setForm(data);
+  }, [data]);
+
+  const patch = (fn: (draft: Channels) => void) => {
+    if (!form) return;
+    const draft = { ...form, feishu: { ...form.feishu }, wechat: { ...form.wechat } };
+    fn(draft);
+    setForm(draft);
+  };
+
+  const onSave = async () => {
+    if (!form) return;
+    setSaving(true);
+    try {
+      const res = await fetch("/api/channels", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ channels: form }),
+      });
+      const json = (await res.json()) as { ok?: boolean; error?: string };
+      if (!res.ok || json.ok === false) {
+        throw new Error(json.error || `${res.status} ${res.statusText}`);
+      }
+      toast.success("已保存（需要重启进程生效）");
+    } catch (e) {
+      toast.error(`保存失败：${String(e)}`, { duration: 4500 });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <section className="space-y-4 px-4 pb-4 pt-0 sm:px-5 sm:pb-5 sm:pt-0 md:px-6 md:pb-6 md:pt-0">
+      <div className="sticky top-0 z-20 -mx-4 bg-background px-4 pb-3 pt-4 sm:-mx-5 sm:px-5 sm:pb-4 sm:pt-5 md:-mx-6 md:px-6 md:pb-5 md:pt-6">
+        <div className="flex flex-col gap-3 bg-background md:flex-row md:items-start md:justify-between">
+          <div className="space-y-1">
+            <h1 className="text-lg font-semibold tracking-tight">渠道配置</h1>
+            <p className="text-sm text-muted-foreground">管理各渠道的启用状态与接入参数。</p>
+          </div>
+          <Button
+            onClick={onSave}
+            disabled={!form || saving || loading || Boolean(error)}
+            className="shrink-0"
+          >
+            {saving ? "保存中…" : "保存"}
+          </Button>
+        </div>
+      </div>
+
+      {loading ? (
+        <Alert>
+          <AlertTitle>加载中</AlertTitle>
+          <AlertDescription>正在读取渠道配置。</AlertDescription>
+        </Alert>
+      ) : error ? (
+          <Alert className="border-destructive/20 bg-destructive/5 text-destructive">
+            <AlertTitle>读取失败</AlertTitle>
+            <AlertDescription>错误：{error}</AlertDescription>
+          </Alert>
+        ) : form ? (
+          <>
+            <div className="space-y-4">
+              <Card className="border-border/60 bg-background/70 shadow-none">
+                <CardHeader>
+                  <div className="flex items-center gap-3">
+                    <CardTitle>飞书</CardTitle>
+                    <Link
+                      to="/docs"
+                      className="text-sm font-medium text-muted-foreground underline decoration-border underline-offset-4 transition-colors hover:text-primary"
+                    >
+                      接入说明
+                    </Link>
+                  </div>
+                  <CardDescription>管理飞书渠道的启用状态与接入凭证。</CardDescription>
+                </CardHeader>
+                <CardContent className="grid gap-4">
+                  <CheckboxField
+                    label="启用状态"
+                    checked={!!form.feishu.enabled}
+                    onChange={(checked) => patch((d) => (d.feishu.enabled = checked))}
+                  />
+                  <TextField
+                    label="App ID"
+                    value={form.feishu.appId ?? ""}
+                    onChange={(value) => patch((d) => (d.feishu.appId = value))}
+                  />
+                  <TextField
+                    label="App Secret"
+                    value={form.feishu.appSecret ?? ""}
+                    onChange={(value) => patch((d) => (d.feishu.appSecret = value))}
+                  />
+                </CardContent>
+              </Card>
+            </div>
+          </>
+        ) : null}
+    </section>
+  );
+}
+
+function FieldShell(props: { label: string; children: React.ReactNode; description?: string }) {
+  return (
+    <div className="space-y-2">
+      <Label className="text-xs uppercase tracking-[0.16em] text-muted-foreground">{props.label}</Label>
+      {props.children}
+      {props.description ? <p className="text-xs text-muted-foreground">{props.description}</p> : null}
+    </div>
+  );
+}
+
+function TextField(props: {
+  label: string;
+  value: string;
+  placeholder?: string;
+  onChange: (value: string) => void;
+}) {
+  return (
+    <FieldShell label={props.label}>
+      <Input
+        className="font-mono text-xs sm:text-sm"
+        value={props.value}
+        placeholder={props.placeholder}
+        onChange={(e) => props.onChange(e.target.value)}
+      />
+    </FieldShell>
+  );
+}
+
+function CheckboxField(props: {
+  label: string;
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+}) {
+  return (
+    <FieldShell label={props.label}>
+      <label className="flex h-10 items-center gap-3 rounded-md border border-input bg-background/80 px-3 text-sm">
+        <input
+          type="checkbox"
+          className="h-4 w-4 rounded border-border accent-primary"
+          checked={props.checked}
+          onChange={(e) => props.onChange(e.target.checked)}
+        />
+        <span className="text-sm text-foreground">{props.checked ? "已启用" : "未启用"}</span>
+      </label>
+    </FieldShell>
+  );
+}

package/lib/__templates__/pi-agent/src/dashboard/web/src/pages/chat-page.tsx

@@ -8,6 +8,7 @@ import { useLocalStorageState } from "../hooks/use-local-storage-state";
 import { Streamdown } from "streamdown";
 import { code } from "@streamdown/code";
 import { cn } from "../utils";
+import { Link } from "react-router-dom";
 
 type ChatUiMessage = {
   role: "user" | "assistant";
@@ -423,6 +424,16 @@ export function ChatPage() {
             </Button>
           </div>
         </div>
+        <div className="px-1 text-xs text-muted-foreground">
+          如需接入飞书机器人，见
+          <Link
+            to="/docs"
+            className="ml-1 underline decoration-border underline-offset-4 transition-colors hover:text-primary"
+          >
+            飞书接入文档
+          </Link>
+          。
+        </div>
       </div>
     </section>
   );

package/lib/__templates__/pi-agent/src/dashboard/web/src/pages/docs-page.tsx

@@ -0,0 +1,65 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { Streamdown } from "streamdown";
+import { code } from "@streamdown/code";
+import { Link } from "react-router-dom";
+import { Alert, AlertDescription, AlertTitle } from "../components/ui/alert";
+import { useFetch } from "../hooks/use-fetch";
+
+type DashboardDocDetail = {
+  slug: string;
+  title: string;
+  content: string;
+};
+
+type DashboardDocsResponse = {
+  selectedDoc: DashboardDocDetail | null;
+};
+
+const DEFAULT_DOC_SLUG = "getting-started";
+
+function DocsLink(props: ComponentPropsWithoutRef<"a">) {
+  const href = typeof props.href === "string" ? props.href : "";
+  const isInternalRoute = href.startsWith("/") && !href.startsWith("//");
+
+  if (isInternalRoute) {
+    return (
+      <Link to={href} className={props.className} title={props.title}>
+        {props.children}
+      </Link>
+    );
+  }
+
+  return <a {...props} />;
+}
+
+export function DocsPage() {
+  const { data, error, loading } = useFetch<DashboardDocsResponse>(`/api/docs?slug=${DEFAULT_DOC_SLUG}`);
+  const selectedDoc = data?.selectedDoc ?? null;
+
+  return (
+    <section className="p-4 sm:p-5 md:p-6">
+      {loading ? (
+        <Alert>
+          <AlertTitle>加载中</AlertTitle>
+          <AlertDescription>正在读取项目文档。</AlertDescription>
+        </Alert>
+      ) : error ? (
+        <Alert className="border-destructive/20 bg-destructive/5 text-destructive">
+          <AlertTitle>读取失败</AlertTitle>
+          <AlertDescription>错误：{error}</AlertDescription>
+        </Alert>
+      ) : !selectedDoc ? (
+        <Alert>
+          <AlertTitle>暂无文档</AlertTitle>
+          <AlertDescription>当前项目里还没有可展示的用户文档。</AlertDescription>
+        </Alert>
+      ) : (
+        <div className="docs-content streamdown-content">
+          <Streamdown plugins={{ code }} parseIncompleteMarkdown={true} components={{ a: DocsLink }}>
+            {selectedDoc.content}
+          </Streamdown>
+        </div>
+      )}
+    </section>
+  );
+}