@coze-arch/cli 0.0.19-beta.1 → 0.0.20-alpha.d2b336

package/lib/__templates__/nuxt-vue/app/pages/index.vue

@@ -1,3 +1,9 @@
+<script setup lang="ts">
+  // 显式声明多词组件名，否则 index.vue 会命中 vue/multi-word-component-names，导致 lint 报错。
+  defineOptions({
+    name: 'LandingPage',
+  });
+</script>
 <template>
   <div class="flex min-h-screen items-center justify-center">
     <main class="flex w-full max-w-3xl flex-col items-center justify-center px-16 py-32">

package/lib/__templates__/nuxt-vue/nuxt.config.ts

@@ -9,7 +9,8 @@ export default defineNuxtConfig({
   compatibilityDate: '2025-07-15',
   // Disable devtools in CI/test environments (prevents hanging in headless mode)
   devtools: {
-    enabled: process.env.CI !== 'true' && process.env.COZE_PROJECT_ENV !== 'PROD',
+    enabled:
+      process.env.CI !== 'true' && process.env.COZE_PROJECT_ENV !== 'PROD',
   },
   telemetry: false,
 
@@ -79,7 +80,6 @@ export default defineNuxtConfig({
   // Vite configuration (similar to Next.js allowedDevOrigins)
   vite: {
     server: {
-      host: '0.0.0.0',
       cors: {
         origin: ['*.dev.coze.site'],
         credentials: true,

package/lib/__templates__/pi-agent/AGENTS.md

@@ -93,9 +93,14 @@
 - 新增 skill：
   - `pi-resources/skills/<skill-name>/SKILL.md`
   - 必要的 `scripts/*`
-- 用户要求新建 Markdown 文档、方案、总结、设计稿等 `.md` 文件：
+- 用户运行时要求产出 Markdown 文档、方案、总结、设计稿等 `.md` 文件：
   - 默认放在 `cwd`
-  - 不要默认放进 `src/` 或其他源码目录
+  - 只有当用户明确指定路径时，才放到对应位置
+- 二次开发过程中新增给开发者看的 Markdown 文档，例如功能使用说明、代码上下文说明、设计约束、排障手册：
+  - 默认放在 `docs/` 下，按内容选择合适的子目录
+  - 文件名使用小写 kebab-case，不要使用大写字母命名
+  - 如果该文档会成为后续开发过程中的长期参考资料，同步更新 `docs/project-overview.md`，写明推荐阅读时机
+  - 不要默认放进 repo 根目录、`src/` 或其他源码目录
 - 新增 extension / runtime tool：
   - `pi-resources/extensions/<extension-name>/index.ts`
   - 或 `pi-resources/extensions/*.ts`

package/lib/__templates__/pi-agent/README.md

@@ -49,6 +49,8 @@ npm run dev
 `npm run dev` 会先按顺序加载 `.env` 和 `.env.local`，然后启动 `src/index.ts`。
 默认会使用 `pi` runtime；如果你只是想走本地 mock 链路，可以额外设置 `PI_BOT_AGENT_MODE=mock`。
 
+如果默认的 `<%= workspaceDir %>/config.json` 不存在，启动时会输出 warning，并自动回退到最小 mock 配置；此时默认会以 `mock` runtime 运行。
+
 ## 用户文档
 
 启动后，可以在 Dashboard 的 `Docs` 页面查看当前项目的用户指引，默认地址是：

package/lib/__templates__/pi-agent/docs/project-overview.md

@@ -52,7 +52,6 @@
 │   │   ├── config-store.ts
 │   │   ├── api
 │   │   │   ├── channels.ts
-│   │   │   ├── docs.ts
 │   │   │   ├── models.ts
 │   │   │   └── overview.ts
 │   │   ├── web
@@ -131,8 +130,7 @@
 - `src/channels/wechat`
   - 微信消息标准化和回复发送
 - `src/dashboard/*`
-  - 本地 Dashboard（HTTP + WebSocket），用于查看运行状态、编辑配置、以及以 UI 方式调试聊天会话
-  - 同时提供 `Docs` 页面，直接展示项目内的快速开始文档
+  - 本地 Dashboard（HTTP + WebSocket），用于查看运行状态、编辑配置（默认模型、飞书渠道）、以及以 UI 方式调试聊天会话
   - 开发态通过 Vite middleware 提供前端资源；生产态直接托管 `src/dashboard/web/dist`
 - `src/dashboard/config-store.ts`
   - Dashboard 配置存储抽象
@@ -153,8 +151,6 @@
   - `coze_web_fetch` 工具单测：覆盖 text/markdown/json 格式渲染、textOnly 模式、链接过滤、图片尺寸、并发抓取、异常处理
 - `tests/web-search.test.ts`
   - `coze_web_search` 工具单测：覆盖基本搜索、摘要、内容包含、图片搜索、路由判断、默认参数、空结果、异常处理
-- `tests/dashboard-docs-api.test.ts`
-  - Dashboard docs API 测试
 - `tests/dashboard-models-api.test.ts`
   - Dashboard models API 测试
 - `tests/feishu-channel.test.ts`
@@ -204,18 +200,16 @@ Dashboard 是一个「和 Bot 同进程」启动的本地 HTTP 服务，默认
 
 前端路由位于 `src/dashboard/web/src/main.tsx`，当前页面：
 
-- `/overview`：运行状态与关键路径（workspace/agent dir 等）
-- `/docs`：项目快速开始文档
-- `/models`：切换默认模型
-- `/channels`：编辑渠道配置
+- `/overview`：系统摘要（运行状态、启用渠道）、默认模型切换、飞书渠道配置
 - `/chat`：调试聊天会话（含历史、reset、WebSocket 流式）
 
+导航栏仅包含「聊天」和「概览」两个入口，md 断点及以上直接展示带文字标签的侧边栏。
+
 ### 3.3 HTTP API（服务端）
 
 当前主要接口（均在同一进程内，不做鉴权）：
 
-- `GET /api/overview`：运行状态/路径/启用渠道等
-- `GET /api/docs`：读取 `docs/user/` 下的用户文档并返回当前文档内容
+- `GET /api/overview`：运行状态/启用渠道等
 - `GET /api/models`：通过 `ConfigStore` 读取配置并返回默认模型与可选模型列表（用于下拉选择）
 - `POST /api/models`：仅写回默认模型（请求体只包含 `defaultModel`；服务端会基于当前配置扫描列表做校验）
 - `GET /api/channels`：通过 `ConfigStore` 读取配置并返回可编辑结构
@@ -230,13 +224,13 @@ Dashboard 是一个「和 Bot 同进程」启动的本地 HTTP 服务，默认
 - `createBotApp(..., { dashboardConfigStore })` 可注入自定义存储实现
 - `tests/smoke/run-smoke.ts` 当前使用内存型 `ConfigStore`，直接验证 dashboard 配置的读写 API 行为
 
-### 3.4 模型配置页能力边界
+### 3.4 模型配置能力边界
 
-当前 `/models` 页面的目标，是以 UI 方式快速切换默认模型，降低直接手改 JSON 的成本。当前页面支持：
+概览页面中的「默认模型」区域，以 UI 方式快速切换默认模型，降低直接手改 JSON 的成本。当前支持：
 
 - 修改默认模型（写回 `agents.defaults.model.primary`）
 
-当前页面不支持：
+当前不支持：
 
 - 编辑 Provider 配置
 - 编辑模型参数
@@ -369,6 +363,6 @@ npm run dashboard:build
 - `docs/project-overview.md`
   - 面向维护者的架构介绍
 - `docs/user/getting-started.md`
-  - 面向项目使用者的快速开始文档，Dashboard 的 `Docs` 页面会直接读取并展示
+  - 面向项目使用者的快速开始文档
 
 最贴近现状的介绍文档是这份 `docs/project-overview.md`。如果其他文档与当前目录结构冲突，应以当前源码、`README.md` 和本文件为准。

package/lib/__templates__/pi-agent/docs/user/getting-started.md

@@ -9,11 +9,10 @@ title: 快速开始
 
 ## 接入飞书机器人
 
-1. 打开 [渠道](/channels) 页面。
+1. 打开 [概览](/overview) 页面的「飞书配置」区域。
 2. 填写 `App ID` 和 `App Secret`。
-3. 按需填写 `domain`、`encryptKey`、`verificationToken`。
-4. 点击保存。
-5. 重启应用让配置生效。
+3. 点击保存。
+4. 重启应用让配置生效。
 
 ### 飞书机器人配置
 

package/lib/__templates__/pi-agent/pi-resources/skills/coze-asr/SKILL.md

@@ -10,14 +10,15 @@ Transcribe audio from a URL or local file using Coze ASR.
 ## Quick start
 
 ```bash
-node {skillDir}/scripts/asr.mjs --url "https://example.com/audio.mp3"
-node {skillDir}/scripts/asr.mjs --file ./recording.mp3
+npx coze-coding-ai asr --url "https://example.com/audio.mp3"
+npx coze-coding-ai asr --file ./recording.mp3
 ```
 
 ## Options
 
 - `--url <url>`, `-u <url>` remote audio URL
-- `--file <path>`, `-f <path>` local audio file
+- `--file <path>`, `-f <path>` local audio file path (will be base64 encoded)
+- `--header <key:value>`, `-H <key:value>` custom HTTP header; repeatable
 
 ## Behavior
 
@@ -27,10 +28,3 @@ node {skillDir}/scripts/asr.mjs --file ./recording.mp3
 - Supported audio formats follow the SDK/API capability: WAV, MP3, OGG Opus, M4A.
 - Recommended limits from the SDK docs: duration up to 2 hours, size up to 100MB.
 - The CLI prints recognized `text`, and may also print `duration` and `segments`.
-- The CLI does not print full `utterances` details or raw response payload.
-- This skill does not expose custom headers such as `--header`, `-H`, or mock mode.
-
-## Notes
-
-- `{skillDir}` means the directory containing this `SKILL.md`.
-- Local files are read and uploaded as base64 audio content.

package/lib/__templates__/pi-agent/pi-resources/skills/coze-image-gen/SKILL.md

@@ -7,35 +7,23 @@ description: Generate one or more images from text prompts using Coze image gene
 
 Generate one or more images from a prompt using Coze.
 
-This skill runs as a Node CLI wrapper around the backend SDK. Do not use the SDK from client-side code.
-
 ## Quick start
 
 ```bash
-node {skillDir}/scripts/gen.mjs --prompt "A futuristic city at sunset"
-node {skillDir}/scripts/gen.mjs --prompt "A serene mountain landscape" --count 2 --size 4K
-node {skillDir}/scripts/gen.mjs --prompt "A hero's journey through magical lands" --sequential --max-sequential 5
-node {skillDir}/scripts/gen.mjs --prompt "Transform into anime style" --image "https://example.com/input.jpg"
-node {skillDir}/scripts/gen.mjs --prompt "A modern office workspace" --response-format url
+npx coze-coding-ai image --prompt "A futuristic city at sunset"
+npx coze-coding-ai image --prompt "A serene mountain landscape" --size 4K
+npx coze-coding-ai image --prompt "Transform into anime style" --size 2K
 ```
 
 ## Options
 
-- `--prompt <text>` required prompt text
-- `--count <n>` number of independent generation requests, default `1`
+- `--prompt <text>`, `-p <text>` required prompt text
 - `--size <size>` image size: `2K`, `4K`, or `WIDTHxHEIGHT`, default `2K`
-- `--image <url>` reference image URL; repeat the flag to pass multiple images
-- `--response-format <format>` only supports `url`
-- `--watermark <true|false>` whether to keep watermark
-- `--optimize-prompt-mode <mode>` prompt optimization mode passed through to the SDK
-- `--sequential` enable sequential image generation
-- `--max-sequential <n>` max sequential frames, default `15`
-- `--header <key:value>` custom HTTP header; repeatable, alias `-H`
+- `--output <path>`, `-o <path>` output file path (optional)
+- `--header <key:value>`, `-H <key:value>` custom HTTP header; repeatable
 
 ## Notes
 
-- `{skillDir}` means the directory containing this `SKILL.md`.
 - Successful runs print generated URLs directly.
 - Printed image URLs must be kept exactly intact, complete, and accurate. All URL parameters must be preserved without truncation, rewriting, omission, or reordering; in particular, parameters inside the query string such as `sign` must not be dropped, otherwise the image may be inaccessible.
 - Unless the user explicitly asks to download the URL content, only return the complete URL link to the user.
-- This skill does not expose base64 output.

package/lib/__templates__/pi-agent/pi-resources/skills/coze-tts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coze-tts
-description: Convert text to speech using Coze TTS. Use when you need to synthesize spoken audio from one text input or multiple text segments, optionally with a specific speaker, format, sample rate, or speech settings.
+description: Convert text to speech using Coze TTS. Use when you need to synthesize spoken audio from text input, optionally with a specific speaker voice.
 ---
 
 # Coze TTS
@@ -10,43 +10,15 @@ Generate speech audio URLs from text using Coze TTS.
 ## Quick start
 
 ```bash
-node {skillDir}/scripts/tts.mjs --text "Hello, welcome to our service"
-node {skillDir}/scripts/tts.mjs --texts "Chapter 1" "Chapter 2" --speaker zh_male_m191_uranus_bigtts
-node {skillDir}/scripts/tts.mjs --text "Fast announcement" --speech-rate 30 --format mp3 --sample-rate 48000
+npx coze-coding-ai tts --text "Hello, welcome to our service"
+npx coze-coding-ai tts --text "你好，欢迎使用我们的服务" --speaker zh_male_m191_uranus_bigtts
 ```
 
 ## Options
 
-- `--text <text>` single text input. If both `--text` and `--texts` are provided, `--text` takes precedence.
-- `--texts <texts...>` multiple text inputs. Values are read until the next `--flag`.
-- `--speaker <id>` speaker id, default `zh_female_xiaohe_uranus_bigtts`
-- `--format <fmt>` audio format: `mp3`, `pcm`, or `ogg_opus`. Default is SDK default (`mp3`).
-- `--sample-rate <hz>` sample rate. Supported values: `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000`. Default is SDK default (`24000`).
-- `--speech-rate <n>` speech rate adjustment, range `-50` to `100`, default `0`
-- `--loudness-rate <n>` loudness adjustment, range `-50` to `100`, default `0`
-
-## Behavior
-
-- At least one of `--text` or `--texts` is required.
-- This skill currently supports plain text input only. It does not expose `ssml`, `--header`, `-H`, or `--mock`.
-- The CLI prints one audio URL per generated segment. It does not download audio files locally.
-- Printed audio URLs must be kept exactly intact, complete, and accurate. All URL parameters must be preserved without truncation, rewriting, omission, or reordering; in particular, parameters inside the query string such as `sign` must not be dropped, otherwise the audio may be inaccessible.
-- Unless the user explicitly asks to download the URL content, only return the complete URL link to the user.
-- The CLI does not print `audioSize`, even though the underlying SDK returns it.
-- Invalid ranges or unsupported values are passed through to the SDK and may fail there.
-
-## Sample Rates
-
-Supported: `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000` Hz
-
-- `8000-16000`: Phone quality
-- `22050-24000`: Standard quality (default)
-- `32000-48000`: High quality
-
-## Tuning
-
-- `speechRate`: range `-50` to `100`, default `0`. Negative values slow speech down, positive values speed it up.
-- `loudnessRate`: range `-50` to `100`, default `0`. Negative values make output quieter, positive values make it louder.
+- `--text <text>`, `-t <text>` text to convert to speech (required)
+- `--speaker <id>` speaker voice id, default `zh_female_xiaohe_uranus_bigtts`
+- `--header <key:value>`, `-H <key:value>` custom HTTP header; repeatable
 
 ## Voices
 
@@ -80,6 +52,6 @@ Supported: `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000` Hz
 
 ## Notes
 
-- `{skillDir}` means the directory containing this `SKILL.md`.
-- The script prints one audio URL per generated segment.
-- The returned URL must be used as-is, in full, and with every parameter preserved exactly, especially query parameters such as `sign`, otherwise the audio may not be accessible.
+- The CLI prints one audio URL per generated segment. It does not download audio files locally.
+- Printed audio URLs must be kept exactly intact, complete, and accurate. All URL parameters must be preserved without truncation, rewriting, omission, or reordering; in particular, parameters inside the query string such as `sign` must not be dropped, otherwise the audio may be inaccessible.
+- Unless the user explicitly asks to download the URL content, only return the complete URL link to the user.

package/lib/__templates__/pi-agent/pi-resources/skills/coze-video-gen/SKILL.md

@@ -7,47 +7,34 @@ description: Generate a video from text prompts and/or image inputs using Coze v
 
 Generate a video URL from text and image inputs using Coze.
 
-This skill runs as a Node CLI wrapper around the backend SDK. Do not use the SDK from client-side code.
-
 ## Quick start
 
 ```bash
-node {skillDir}/scripts/gen.mjs --prompt "A serene mountain landscape with flowing clouds"
-node {skillDir}/scripts/gen.mjs --prompt "A cinematic robot walking through neon rain" --duration 6 --ratio 9:16 --resolution 1080p
-node {skillDir}/scripts/gen.mjs --prompt "Animate this concept art" --first-frame "https://example.com/first.png"
-node {skillDir}/scripts/gen.mjs --prompt "Transition from sunrise to night" --first-frame "https://example.com/start.png" --last-frame "https://example.com/end.png" --return-last-frame true
+npx coze-coding-ai video --prompt "A serene mountain landscape with flowing clouds"
+npx coze-coding-ai video --prompt "A cinematic robot walking through neon rain" --duration 6 --size 1080x1920
+npx coze-coding-ai video --prompt "Animate this concept art" --image-url "https://example.com/first.png"
+npx coze-coding-ai video --prompt "Transition from sunrise to night" --image-url "https://example.com/start.png,https://example.com/end.png" --return-last-frame
 ```
 
 ## Options
 
-- `--prompt <text>` text prompt
-- `--image <url>` reference image URL; repeat the flag to pass multiple images
-- `--first-frame <url>` first frame image URL
-- `--last-frame <url>` last frame image URL
-- `--model <id>` model id, default SDK model is `doubao-seedance-1-5-pro-251215`
-- `--duration <seconds>` video duration in seconds
-- `--ratio <ratio>` one of `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `adaptive`
-- `--resolution <value>` one of `480p`, `720p`, `1080p`
-- `--watermark <true|false>` whether to keep watermark
-- `--seed <n>` fixed random seed for reproducibility
-- `--camera-fixed <true|false>` whether to fix the camera
-- `--generate-audio <true|false>` whether to generate synced audio
-- `--return-last-frame <true|false>` whether to return the last-frame image URL
-- `--max-wait-time <seconds>` max synchronous wait time
-- `--callback-url <url>` async callback URL passed through to the SDK
-- `--header <key:value>` custom HTTP header; repeatable, alias `-H`
+- `--prompt <text>`, `-p <text>` text prompt
+- `--image-url <url>`, `-i <url>` image URL (single or comma-separated two URLs for first/last frame)
+- `--size <size>`, `-s <size>` video resolution (e.g., `1920x1080`)
+- `--duration <seconds>`, `-d <seconds>` video duration in seconds (`5`-`10`), default `5`
+- `--model <model>`, `-m <model>` model name, default `doubao-seedance-1-0-pro-fast-251015`
+- `--callback-url <url>` async callback URL
+- `--return-last-frame` return last frame image URL
+- `--watermark` add watermark
+- `--seed <number>` fixed random seed for reproducibility
+- `--camerafixed` fix the camera
+- `--output <path>`, `-o <path>` output file path (JSON)
+- `--header <key:value>`, `-H <key:value>` custom HTTP header; repeatable
 
 ## Behavior
 
-- At least one of `--prompt`, `--image`, `--first-frame`, or `--last-frame` is required.
+- At least one of `--prompt` or `--image-url` is required.
 - Successful runs print `Task ID`, `Status`, `Video URL`, and optionally `Last Frame URL`.
 - The CLI does not download video files locally.
 - Printed video URLs and frame URLs must be kept exactly intact, complete, and accurate. All URL parameters must be preserved without truncation, rewriting, omission, or reordering; in particular, parameters inside the query string such as `sign` must not be dropped, otherwise the asset may be inaccessible.
 - Unless the user explicitly asks to download the URL content, only return the complete URL link to the user.
-
-## Notes
-
-- `{skillDir}` means the directory containing this `SKILL.md`.
-- The default model `doubao-seedance-1-5-pro-251215` supports text input plus `first_frame` and `last_frame`. Generic `reference_image` inputs from `--image` may be rejected by that model.
-- Only use `--image` when you have selected a model that explicitly supports `reference_image`.
-- The returned video URL is already hosted with a valid expiration period. Unless the user explicitly needs rehosting or download, use it directly.

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

@@ -93,6 +93,7 @@ export interface LoadedConfig {
   path: string;
   directory: string;
   workspaceDir: string;
+  source: "file" | "fallback-mock";
   thinkingLevel?: ThinkingLevel;
   config: Config;
   providers: Record<string, ProviderConfig>;
@@ -127,6 +128,56 @@ const DEFAULT_APP_NAME = "starter-bot";
 const DEFAULT_CONFIG_FILENAME = "config.json";
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 
+function createMockConfig(): Config {
+  return {
+    agents: {
+      defaults: {
+        workspace: ".",
+        model: {
+          primary: "openai/gpt-5-mini"
+        }
+      }
+    },
+    channels: {
+      feishu: {
+        enabled: false,
+        requireMention: true,
+        thinkingReaction: {
+          enabled: true,
+          emojiType: "OneSecond"
+        }
+      },
+      wechat: {
+        enabled: false,
+        requireMention: false
+      }
+    }
+  };
+}
+
+function createLoadedConfig(
+  configPath: string,
+  parsed: Config,
+  source: LoadedConfig["source"]
+): LoadedConfig {
+  const directory = dirname(configPath);
+  const workspaceDir = resolve(directory, parsed.agents?.defaults?.workspace ?? ".");
+  const defaultModelReference = parsed.agents?.defaults?.model?.primary;
+
+  return {
+    path: configPath,
+    directory,
+    workspaceDir,
+    source,
+    thinkingLevel: parsed.agents?.defaults?.thinkingLevel,
+    config: parsed,
+    providers: parsed.models?.providers ?? {},
+    defaultModel: defaultModelReference
+      ? parseModelReference(defaultModelReference, "agents.defaults.model.primary")
+      : undefined
+  };
+}
+
 export function parseModelReference(reference: string, description = "model reference"): ModelReference {
   const normalized = reference.trim();
   const splitIndex = normalized.indexOf("/");
@@ -145,7 +196,8 @@ export function parseModelReference(reference: string, description = "model refe
 
 export function loadConfig(configPath: string): LoadedConfig {
   if (!existsSync(configPath)) {
-    throw new Error(`Config not found: ${configPath}`);
+    console.warn(`[pi-bot] Config not found: ${configPath}. Falling back to mock config.`);
+    return createLoadedConfig(configPath, createMockConfig(), "fallback-mock");
   }
 
   let parsed: Config;
@@ -160,25 +212,11 @@ export function loadConfig(configPath: string): LoadedConfig {
     );
   }
 
-  const directory = dirname(configPath);
-  const workspaceDir = resolve(directory, parsed.agents?.defaults?.workspace ?? ".");
-  const defaultModelReference = parsed.agents?.defaults?.model?.primary;
-
-  return {
-    path: configPath,
-    directory,
-    workspaceDir,
-    thinkingLevel: parsed.agents?.defaults?.thinkingLevel,
-    config: parsed,
-    providers: parsed.models?.providers ?? {},
-    defaultModel: defaultModelReference
-      ? parseModelReference(defaultModelReference, "agents.defaults.model.primary")
-      : undefined
-  };
+  return createLoadedConfig(configPath, parsed, "file");
 }
 
 export function loadOptionalConfig(configPath: string | undefined): LoadedConfig | undefined {
-  if (!configPath || !existsSync(configPath)) {
+  if (!configPath) {
     return undefined;
   }
 
@@ -261,11 +299,14 @@ export function loadBotAppConfig(
 
   return {
     appName: DEFAULT_APP_NAME,
+    configRoot: loadedConfig.config as Record<string, unknown>,
     agent: {
-      mode: (env.PI_BOT_AGENT_MODE as BotAppConfig["agent"]["mode"] | undefined) ?? "pi",
+      mode:
+        (env.PI_BOT_AGENT_MODE as BotAppConfig["agent"]["mode"] | undefined) ??
+        (loadedConfig.source === "fallback-mock" ? "mock" : "pi"),
       provider: defaultModel?.provider ?? "openai",
       model: defaultModel?.modelId ?? "gpt-5-mini",
-      configPath,
+      configPath: loadedConfig.source === "file" ? configPath : undefined,
       thinkingLevel: loadedConfig.thinkingLevel,
       cwd: workspaceDir,
       agentDir: workspaceDir

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

@@ -108,6 +108,7 @@ export interface BotRoutingConfig {
 
 export interface BotAppConfig {
   appName: string;
+  configRoot?: Record<string, unknown>;
   agent: AgentRuntimeConfig;
   routing: BotRoutingConfig;
   channels: {

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

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

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

@@ -6,7 +6,6 @@ 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";
@@ -34,8 +33,6 @@ 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");
 
@@ -229,15 +226,6 @@ 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,12 +1,9 @@
 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";
@@ -18,9 +15,6 @@ 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 }) {
@@ -132,15 +126,7 @@ export function AppLayout(props: { children: React.ReactNode }) {
         ) : null}
 
         <div className="flex min-h-0 flex-1 items-stretch">
-          <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">
+          <aside className="hidden shrink-0 p-3 md: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,10 +4,7 @@ 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 (
@@ -16,9 +13,6 @@ 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>