@coze-arch/cli 0.0.14-alpha.5e3bce → 0.0.14-alpha.c52ee4

package/lib/__templates__/nextjs/scripts/prepare.sh

@@ -7,4 +7,3 @@ cd "${COZE_WORKSPACE_PATH}"
 
 echo "Installing dependencies..."
 pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
-coze check-bins --fix

package/lib/__templates__/nuxt-vue/scripts/prepare.sh

@@ -7,7 +7,6 @@ cd "${COZE_WORKSPACE_PATH}"
 
 echo "Installing dependencies..."
 pnpm install --prefer-frozen-lockfile --prefer-offline
-coze check-bins --fix
 
 echo "Preparing Nuxt project..."
 pnpm exec nuxt prepare

package/lib/__templates__/pi-agent/.coze

@@ -0,0 +1,10 @@
+[project]
+requires = ["nodejs-24"]
+
+[dev]
+build = ["bash", "./scripts/prepare.sh"]
+run = ["bash", "./scripts/dev.sh"]
+
+[deploy]
+build = ["bash", "pnpm install"]
+run = ["bash", "./scripts/dev.sh"]

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

@@ -0,0 +1,150 @@
+# Pi Bot AGENTS Guide
+
+## 1. 项目定位
+
+- 这是一个已经交付给用户、会继续被迭代的 Pi Bot 项目。
+- 你面对的是“当前用户的项目”，不是一个需要保持通用性的初始化模板。
+- 当新需求和现有行为冲突时，默认优先保护已有功能、配置兼容性、会话数据和可调试性。
+
+## 2. 工作区与配置
+
+- 用户工作区和运行时配置默认位于相邻目录 `<%= workspaceDir %>/`。
+- 默认配置文件路径是 `<%= workspaceDir %>/config.json`。
+- 运行时配置的代码入口是 `src/config.ts`。不要绕过它再引入新的平行配置源。
+- 如果要修改配置写回逻辑，必须保留无关字段，避免覆盖用户已有配置。
+
+## 3. 必读顺序
+
+在进行较大修改前，优先按下面顺序理解项目：
+
+1. `README.md`
+2. `docs/project-overview.md`
+3. 与需求相关的源码入口
+4. 与改动相关的测试
+
+不要依赖当前目录之外的文档。
+
+## 4. 核心架构约束
+
+### 4.1 消息与分层
+
+- 平台消息必须先归一化为 `BotMessage`，再进入 runtime。
+- `channel` 层负责平台协议适配、路由过滤、消息发送。
+- `runtime` 层负责 agent 调用、session 生命周期和流式输出。
+- `dashboard` 负责调试界面、运行态观察和受控配置编辑。
+- 不要把平台逻辑、UI 逻辑、模型逻辑混写在一起。
+
+### 4.2 Session 与持久化
+
+- 会话归类规则以 `src/core.ts` 中的 `getSessionKey()` 为准，不要随意改动会话 key 规则。
+- `src/session-store.ts` 负责 session 索引、transcript 文件和 reset 归档逻辑。
+- reset session 时必须归档旧 transcript，不能直接覆盖旧会话文件。
+- 不要删除、清空或重置 .pi-bot/ 下的会话数据，除非用户明确要求。
+
+### 4.3 配置与兼容性
+
+- 用户可编辑配置以 `<%= workspaceDir %>/config.json` 为 source of truth。
+- 新增配置项时，优先采用向后兼容的方式；避免无说明地重命名、删除或改变现有字段语义。
+- Dashboard 的配置写回必须是“局部更新”，不能把不相关配置抹掉。
+- 若变更会影响配置 schema、session 持久化格式、HTTP API shape 或默认行为，先确认再修改。
+
+### 4.4 外部平台的降级能力
+
+- 飞书、微信、模型 provider、流式卡片等外部能力都可能失败。
+- 外部能力失败时，优先保证主链路可用，并提供合理降级。
+- 例如 reaction、streaming card 或可选增强能力失败时，不应阻断最终回复。
+
+### 4.5 Agent 能力扩展方式
+
+- 新增“搜索 / 检索 / 信息采集 / 外部知识 / 热点汇总”这类能力时，默认优先使用 `pi-coding-agent` / `pi-mono` 生态已有的扩展方式：
+  - `customTools`
+  - extensions
+  - `ResourceLoader`
+  - skills / prompt templates
+- 不要在 `channel` 层、`onMessage()`、`createBotApp()` 或其他 host 侧装配代码里，通过关键词匹配、意图判断或硬编码分支，手动把请求路由到某个 `collector`、`searcher`、`crawler`。
+- `channel` 层只负责平台协议适配、消息归一化、路由过滤和发送回复；不负责“这个问题该不该调用外部信息能力”的业务决策。
+- `runtime` 层负责把能力注册为 agent 可调用的 tool / extension，再由 agent 在对话过程中决定是否使用。
+- 如果需求确实无法通过 tool / extension / skill 方式实现，必须先说明为什么现有扩展点不适用，再考虑增加 host 侧分流逻辑。
+- 反例：
+  - 在 `onMessage()` 里判断“如果用户提到 Hacker News / GitHub 就直接调用 collector”
+- 正例：
+  - 在 runtime 注册一个“抓取热点内容”的自定义 tool，让 agent 自主决定何时调用
+
+## 5. 修改策略
+
+- 优先做小步、增量、可验证的修改，避免没有必要的大规模重写。
+- 用户可见行为发生变化时，优先考虑是否应该做成配置项，而不是直接硬编码。
+- 修 bug 或加功能时，同时检查是否需要补测试和文档。
+
+## 6. 常见改动的落点
+
+- 改运行时配置或模型/provider 解析：
+  - `src/config.ts`
+  - `tests/config.test.ts`
+- 改 session 行为或 transcript 持久化：
+  - `src/core.ts`
+  - `src/agent.ts`
+  - `src/session-store.ts`
+  - `tests/session-store.test.ts`
+- 改飞书/微信 channel：
+  - `src/channels/*`
+  - 对应 channel tests
+- 改 Dashboard 接口或配置编辑：
+  - `src/dashboard/api/*`
+  - `src/dashboard/server.ts`
+  - 对应 API tests
+- 改 Dashboard 前端：
+  - `src/dashboard/web/src/*`
+  - 必要时补充前后端联动验证
+
+## 7. 验证要求
+
+默认情况下：
+
+- 代码改动后至少运行：
+  - `npm test`
+  - `npm run typecheck`
+- 如果修改了 Dashboard 前端或其构建相关内容，再运行：
+  - `npm run dashboard:build`
+- 如果修改影响了跨模块主链路，例如 config、channel、runtime、session、dashboard 联动，再运行：
+  - `npm run smoke`
+
+如果因为环境限制无法完成验证，需要在最终说明中明确指出未验证项和风险，并给出用户手动验证的方式。
+
+## 8. 文档同步要求
+
+出现以下情况时，同步更新相关文档：
+
+- 启动或配置方式变化
+- 用户可见行为变化
+- 目录结构或核心模块职责变化
+- 测试方式或验证要求变化
+
+### 8.1 文档落点与命名规范
+
+- 除 `README.md`、`AGENTS.md` 这类仓库入口文件外，不要随意在项目根目录新增文档。
+- 架构说明、设计说明、实现说明、迭代记录等开发文档，放在 `docs/` 下。
+- 面向最终用户的使用说明、接入说明、操作指南，放在 `docs/user/` 下。
+- 新增文档文件名使用 kebab-case，例如 `agent-tooling-guide.md`、`dashboard-chat-flow.md`。
+- 不要创建语义含糊的文件名，例如 `new-doc.md`、`notes.md`、`temp.md`、`test.md`。
+- 如果某次改动需要补文档，优先更新已有文档；只有在现有文档承载不合适时，才新增文档文件。
+- 新增文档后，应该让相关入口文档能找到它，避免产生“写了但没人知道在哪”的文档孤岛。
+
+## 9. 需要先确认的高风险变更
+
+遇到以下改动，先暂停并与用户确认：
+
+- 修改 `config.json` schema 或默认值语义
+- 修改 `getSessionKey()` 规则
+- 修改 session 文件格式、索引格式或归档规则
+- 修改默认 channel 行为，导致消息路由或触发条件变化
+- 删除现有 API、页面、配置项或持久化数据
+
+## 10. 目标
+
+你的目标是在当前项目基础上持续迭代，稳定交付用户需要的能力，同时尽量保持：
+
+- 现有行为可预测
+- 配置与数据可兼容
+- 出问题时便于排查
+- 后续继续迭代时容易维护

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

@@ -0,0 +1,155 @@
+# Pi Bot
+
+这是一个基于 `pi-mono` / `@mariozechner/pi-coding-agent` 的 Bot 项目。
+
+## 当前结构
+
+- `src/config.ts`
+  - 项目唯一配置入口，读取 `config.json` 并装配 `BotAppConfig`
+- `src/index.ts`
+  - 应用启动入口
+- `src/agent.ts`
+  - agent runtime 封装
+- `src/dashboard/config-store.ts`
+  - Dashboard 配置读写抽象，支持文件和内存两种存储
+- `src/core.ts`
+  - 通用消息协议、共享类型和 helper
+- `src/channels/feishu`
+  - 飞书 channel
+- `src/channels/wechat`
+  - 微信 channel
+- `tests/smoke`
+  - 基础 smoke test（使用内存配置存储验证 dashboard 配置读写链路）
+- `tests/config.test.ts`
+  - config 解析与模型构建测试
+- `types`
+  - 本地类型声明补充
+- `docs/project-overview.md`
+  - 项目结构与实现介绍
+- `docs/user/getting-started.md`
+  - 用户快速开始文档，Dashboard 的 `Docs` 页面会直接展示这份 Markdown
+
+## Start
+
+```bash
+npm install
+npm run dev
+```
+
+`npm run dev` 会先按顺序加载 `.env` 和 `.env.local`，然后启动 `src/index.ts`。
+
+## 用户文档
+
+启动后，可以在 Dashboard 的 `Docs` 页面查看当前项目的用户指引，默认地址是：
+
+```txt
+http://127.0.0.1:5000/docs
+```
+
+用户文档的 Markdown 源文件位于 `docs/user/getting-started.md`。如果你修改了接入步骤或调整了用户可见行为，请同步更新这份文档。
+
+## 常用命令
+
+```bash
+npm run dev
+npm test
+npm run smoke
+npm run typecheck
+```
+
+## Agent 模式
+
+- `PI_BOT_AGENT_MODE=mock`
+  - 使用 mock runtime，适合本地链路验证
+- `PI_BOT_AGENT_MODE=pi`
+  - 使用真实 `pi-coding-agent` runtime
+
+除 `PI_BOT_AGENT_MODE` 和飞书相关环境变量外，agent 的模型、provider、workspace、thinking level 都从 `<%= workspaceDir %>/config.json` 读取。
+
+## Provider 配置
+
+provider 不再通过项目内的特化实现硬编码，而是从 `<%= workspaceDir %>/config.json` 的 `models.providers` 读取。
+
+如果你已经启动了本地 Dashboard，现在也可以直接在界面里切换默认模型：
+
+- `http://127.0.0.1:5000/models`
+  - 选择默认模型（选择后会自动保存）
+
+默认情况下，Dashboard 会通过文件型 `ConfigStore` 读写 `<%= workspaceDir %>/config.json`，保存后需要重启进程让配置生效。测试或嵌入场景也可以通过 `createBotApp(..., { dashboardConfigStore })` 注入内存型 `ConfigStore`，避免依赖真实配置文件。
+
+默认主模型来自：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "thinkingLevel": "medium",
+      "model": {
+        "primary": "coze/glm-4-7-251222"
+      }
+    }
+  }
+}
+```
+
+provider 定义示例：
+
+```json
+{
+  "models": {
+    "providers": {
+      "coze": {
+        "api": "openai-completions",
+        "apiKey": "${COZE_WORKLOAD_IDENTITY_API_KEY}",
+        "baseUrl": "${COZE_INTEGRATION_MODEL_BASE_URL}",
+        "models": [
+          {
+            "id": "glm-4-7-251222",
+            "name": "GLM 4.7",
+            "reasoning": false,
+            "input": ["text"],
+            "contextWindow": 200000,
+            "maxTokens": 8192,
+            "cost": {
+              "input": 0,
+              "output": 0,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+后续要扩展新的 openai-compatible provider，只需要在 `<%= workspaceDir %>/config.json` 里新增一个 provider 配置和模型定义即可。
+
+当前 Dashboard 的模型配置页仅用于切换默认模型，不支持编辑 Provider 或模型参数。如果要扩展或修改 provider/model，仍然建议直接编辑 `<%= workspaceDir %>/config.json`。
+
+## Feishu Debug
+
+如果你在联调真实飞书机器人，并想排查重复回复或事件重试问题，可开启：
+
+```bash
+export PI_BOT_DEBUG_FEISHU=1
+npm run dev
+```
+
+飞书 channel 会输出收到事件、过滤原因、去重结果和发送回复等关键日志。
+
+默认情况下，飞书 channel 会在 bot 开始处理消息时给原消息加一个 `OneSecond` reaction，并在发送回复前移除它。这里的 `emojiType` 需要填写飞书文档里的 `emoji_type` 枚举值，比如 `OneSecond`、`MUSCLE`。你也可以在 `<%= workspaceDir %>/config.json` 里覆盖这个行为：
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "thinkingReaction": {
+        "enabled": true,
+        "emojiType": "OneSecond"
+      }
+    }
+  }
+}
+```

package/lib/__templates__/pi-agent/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.env

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

@@ -0,0 +1,273 @@
+# Pi Bot 项目总览
+
+## 1. 项目定位
+
+`pi-bot` 是一个基于 `pi-mono` / `@mariozechner/pi-coding-agent` 的 Bot 项目。
+
+这个目录直接承载三类能力：
+
+- 初始化骨架
+- 平台 channel 接入
+- provider 扩展
+
+项目里的关键运行时代码集中在这里，阅读、修改和扩展都会更直接。
+
+## 2. 当前目录结构
+
+```txt
+.
+├── docs
+│   ├── project-overview.md
+│   └── user
+├── src
+│   ├── agent.ts
+│   ├── config.ts
+│   ├── core.ts
+│   ├── session-store.ts
+│   ├── dashboard
+│   │   ├── config-store.ts
+│   │   ├── api
+│   │   │   ├── channels.ts
+│   │   │   ├── models.ts
+│   │   │   └── overview.ts
+│   │   ├── web
+│   │   │   ├── src
+│   │   │   │   ├── components
+│   │   │   │   │   ├── ui
+│   │   │   │   │   └── app-layout.tsx
+│   │   │   │   ├── pages
+│   │   │   │   ├── utils
+│   │   │   │   ├── main.tsx
+│   │   │   │   └── styles.css
+│   │   │   ├── index.html
+│   │   │   ├── postcss.config.cjs
+│   │   │   ├── tsconfig.json
+│   │   │   └── vite.config.ts
+│   │   ├── index.ts
+│   │   ├── server.ts
+│   │   └── types.ts
+│   ├── index.ts
+│   ├── channels
+│   │   ├── feishu
+│   │   └── wechat
+├── tests
+│   ├── config.test.ts
+│   └── smoke
+└── types
+```
+
+各部分职责：
+
+- `src/config.ts`
+  - 项目唯一配置入口，读取 `config.json` 并装配 agent、channel、routing 等运行配置
+- `src/index.ts`
+  - 应用装配层，创建 channel 并把消息交给 runtime
+- `src/agent.ts`
+  - `pi-coding-agent` runtime 封装
+- `src/core.ts`
+  - 通用消息协议、共享类型和基础 helper
+- `src/session-store.ts`
+  - session 持久化索引层
+  - 负责维护 `sessionKey -> sessionId/sessionFile` 映射，并管理 transcript header、reset 归档等文件操作
+- `src/channels/feishu`
+  - 飞书消息接收、标准化、去重、过滤和回复发送
+- `src/channels/wechat`
+  - 微信消息标准化和回复发送
+- `src/dashboard/*`
+  - 本地 Dashboard（HTTP + WebSocket），用于查看运行状态、编辑配置、以及以 UI 方式调试聊天会话
+  - 同时提供 `Docs` 页面，直接展示项目内的快速开始文档
+  - 开发态通过 Vite middleware 提供前端资源；生产态直接托管 `src/dashboard/web/dist`
+- `src/dashboard/config-store.ts`
+  - Dashboard 配置存储抽象
+  - 默认使用文件存储读写 `workspace/config.json`
+  - 也支持内存存储，便于 smoke test 或宿主注入
+- `tests/smoke`
+  - 基础链路 smoke test
+  - 当前会额外覆盖 dashboard 的 models/channels 配置读写，并使用内存 `ConfigStore` 避免依赖真实配置文件
+- `tests/config.test.ts`
+  - config 解析与模型构建测试
+- `types`
+  - 第三方 SDK 的类型补充
+
+## 3. Dashboard（现状实现）
+
+Dashboard 是一个「和 Bot 同进程」启动的本地 HTTP 服务，默认地址：
+
+- `http://127.0.0.1:5000`
+- 端口/Host 可通过环境变量覆盖：`PI_BOT_DASHBOARD_PORT`、`PI_BOT_DASHBOARD_HOST`
+
+服务端入口：
+
+- [`src/dashboard/server.ts`](../src/dashboard/server.ts) 负责 Express 路由、Vite 开发中间件、以及 WebSocket（聊天流式）
+- [`src/dashboard/index.ts`](../src/dashboard/index.ts) 负责把 Bot runtime 信息注入 Dashboard server
+- [`src/dashboard/config-store.ts`](../src/dashboard/config-store.ts) 负责把 Dashboard 的配置读写抽象成 `ConfigStore`
+
+### 3.1 前端技术栈
+
+- Vite + React + React Router
+- Tailwind CSS v4（`styles.css` 里使用 `@import "tailwindcss"` / `@theme`）
+- shadcn 风格组件（代码内置于 `src/dashboard/web/src/components/ui/*`）
+- 暗黑模式：通过在 `documentElement` 上切换 `dark` class，并在 `styles.css` 提供 `:root` / `.dark` token
+
+### 3.2 页面与路由
+
+前端路由位于 `src/dashboard/web/src/main.tsx`，当前页面：
+
+- `/overview`：运行状态与关键路径（workspace/agent dir 等）
+- `/docs`：项目快速开始文档
+- `/models`：切换默认模型
+- `/channels`：编辑渠道配置
+- `/chat`：调试聊天会话（含历史、reset、WebSocket 流式）
+
+### 3.3 HTTP API（服务端）
+
+当前主要接口（均在同一进程内，不做鉴权）：
+
+- `GET /api/overview`：运行状态/路径/启用渠道等
+- `GET /api/docs`：读取 `docs/user/` 下的用户文档并返回当前文档内容
+- `GET /api/models`：通过 `ConfigStore` 读取配置并返回默认模型与可选模型列表（用于下拉选择）
+- `POST /api/models`：仅写回默认模型（请求体只包含 `defaultModel`；服务端会基于当前配置扫描列表做校验）
+- `GET /api/channels`：通过 `ConfigStore` 读取配置并返回可编辑结构
+- `POST /api/channels`：通过 `ConfigStore` 写回配置；默认文件存储会落回 `workspace/config.json`，保存后需要重启进程生效
+- `GET /api/chat/history`：按 session identity 计算 sessionKey，并按需加载持久化 transcript 后返回消息
+- `POST /api/chat/reset`：重置指定 sessionKey 的会话；会切换到新的 `sessionId/sessionFile`，旧 transcript 归档到 `archive/`
+- `WS /api/chat/ws`：聊天流式（推荐的 UI 通道）
+
+补充说明：
+
+- 生产/日常开发默认使用文件型 `ConfigStore`
+- `createBotApp(..., { dashboardConfigStore })` 可注入自定义存储实现
+- `tests/smoke/run-smoke.ts` 当前使用内存型 `ConfigStore`，直接验证 dashboard 配置的读写 API 行为
+
+### 3.4 模型配置页能力边界
+
+当前 `/models` 页面的目标，是以 UI 方式快速切换默认模型，降低直接手改 JSON 的成本。当前页面支持：
+
+- 修改默认模型（写回 `agents.defaults.model.primary`）
+
+当前页面不支持：
+
+- 编辑 Provider 配置
+- 编辑模型参数
+- 新增/删除 Provider 或模型条目
+
+因此，如果要接入新的 openai-compatible provider、修改模型定义或参数，仍然建议直接编辑默认文件存储对应的 `workspace/config.json`；补充完成后，Dashboard 会自动读取并展示这些新模型供选择。
+
+### 3.5 Session 持久化
+
+当前 `pi-bot` 已支持 session 持久化，逻辑参考 `openclaw` 的 transcript/sessionFile 模式：
+
+- `src/core.ts` 里的 `getSessionKey()` 仍然负责根据 channel / conversation / thread 等信息生成稳定的业务会话键
+- `src/session-store.ts` 负责把这个 `sessionKey` 映射到一个可落盘的 transcript 文件
+- `src/agent.ts` 在创建真实 `pi-coding-agent` session 时，不再只依赖进程内 `Map`，而是通过 `SessionManager.open(sessionFile)` 绑定到固定 transcript
+
+默认持久化目录位于：
+
+```txt
+<agentDir>/.pi-bot/sessions/
+├── index.json
+├── transcripts/
+└── archive/
+```
+
+其中：
+
+- `index.json`
+  - 保存 `sessionKey -> { sessionId, sessionFile, updatedAt }` 的索引
+- `transcripts/`
+  - 保存当前活跃会话的 transcript（`.jsonl`）
+- `archive/`
+  - 保存 reset 后被归档的旧 transcript
+
+补充说明：
+
+- 持久化覆盖全部 channel：`dashboard` / `feishu` / `wechat`
+- transcript 文件名不会直接使用原始 `sessionKey`，而是基于其 hash 生成，避免特殊字符和超长文件名问题
+- Dashboard 重启后仍可通过 `GET /api/chat/history` 恢复已有会话消息
+- Reset 不会直接覆盖旧 transcript，而是新建 session 并归档旧文件，便于排查和追溯
+
+### 3.6 构建方式
+
+前端生产构建命令：
+
+```bash
+npm run dashboard:build
+```
+
+该脚本对应 Vite 配置：
+
+- [`src/dashboard/web/vite.config.ts`](../src/dashboard/web/vite.config.ts)
+
+开发态（`NODE_ENV !== "production"`）：
+
+- Dashboard server 通过 Vite middleware 直接服务前端（无需单独启动 Vite dev server）
+
+生产态（`NODE_ENV=production`）：
+
+- Dashboard server 托管 `src/dashboard/web/dist` 的静态文件
+  - 如果你需要生产态可用，记得先运行 `npm run dashboard:build`
+
+## 4. 运行模型
+
+当前项目的运行链路如下：
+
+1. channel 接收平台事件
+2. channel 把事件转换成 `BotMessage`
+3. `src/index.ts` 调用 `runtime.run(message)`
+4. `src/agent.ts` 根据配置选择 mock 或真实 `pi-coding-agent`
+5. 真实 runtime 会先通过 `getSessionKey()` 确定业务会话，再通过 `src/session-store.ts` 找到或创建对应的持久化 transcript
+6. runtime 基于该 transcript 执行 prompt，新的 user / assistant 消息持续写入 sessionFile
+7. runtime 返回文本
+8. channel 把文本发回原平台
+
+## 4.1 飞书卡片与流式输出
+
+`pi-bot` 的飞书回复有两种渲染形态：
+
+- 普通文本：`msg_type: "text"`
+- Markdown 卡片：`msg_type: "interactive"`（卡片内使用 `tag: "markdown"`）
+
+默认情况下会按内容自动选择是否使用卡片（与 `openclaw` 的判断一致）：
+
+- 命中代码块（```...```，流式阶段也接受仅出现 opening fence）或 Markdown 表格时，使用卡片渲染
+- 其他普通文本/普通 Markdown，使用文本消息
+
+当启用流式回复（`onStreamMessage` + `runtime.stream()`）时，如果内容命中“使用卡片”的条件，会尝试使用 CardKit 的 streaming card API 做实时更新：
+
+- 创建 streaming card（CardKit `cardkit/v1/cards`）
+- reply 一条 `interactive` 卡片引用到原消息
+- 按增量内容持续更新卡片中的 markdown 元素
+- 最终关闭 streaming 模式并更新 summary
+
+注意：流式卡片需要飞书开放平台开通 CardKit 相关权限（例如 `cardkit:card:write`）。如果权限未开通，streaming card 创建/更新会失败并自动回退为“最终一次性回复”。
+
+如果 streaming card 创建失败（例如未开通 CardKit 权限、参数/租户不匹配等），会自动回退为“最终一次性回复”，不会影响正常出消息。
+
+补充说明：
+
+- 进程内仍保留 `Map<string, AgentSession>` 作为热缓存，避免同一 session 在单次运行期间重复创建
+- 但真正的“可恢复会话”依赖的是磁盘上的 transcript，而不是这个内存 `Map`
+- 因此进程重启后，只要 `sessionKey` 不变，就可以重新打开对应 transcript 继续对话
+- 飞书 thinking reaction 默认 emoji 已调整为 `OneSecond`，也可通过 `channels.feishu.thinkingReaction.emojiType` 覆盖
+
+## 5. 当前建议的开发顺序
+
+如果后续继续扩展，建议按这个顺序理解项目：
+
+1. 阅读根目录 `README.md`
+2. 阅读 `docs/project-overview.md`
+3. 阅读 `src/config.ts`
+4. 阅读 `src/index.ts`
+5. 阅读 `src/agent.ts`
+6. 根据需要再进入 `src/channels/*`、`src/dashboard/*` 和相关测试
+
+## 6. 关于 docs
+
+`docs/` 目录中保留了两类材料：
+
+- `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

@@ -0,0 +1,46 @@
+---
+title: 快速开始
+---
+
+# 快速开始
+
+即使暂时没有打通外部渠道，你也可以先用 Dashboard 的 `聊天` 页面验证 Agent 行为。
+
+## 接入飞书机器人
+
+1. 打开 [渠道](/channels) 页面。
+2. 填写 `App ID` 和 `App Secret`。
+3. 按需填写 `domain`、`encryptKey`、`verificationToken`。
+4. 点击保存。
+5. 重启应用让配置生效。
+
+### 飞书机器人配置
+
+1. 在「权限管理」中配置以下权限：
+
+```json
+{
+  "scopes": {
+    "tenant": [
+      "cardkit:card:write",
+      "docx:document:readonly",
+      "im:message.group_at_msg:readonly",
+      "im:message.p2p_msg:readonly",
+      "im:message.reactions:read",
+      "im:message.reactions:write_only",
+      "im:message:send_as_bot"
+    ],
+    "user": [
+      "docx:document:readonly"
+    ]
+  }
+}
+```
+
+2. 在「事件与回调」中添加 `im.message.receive_v1` 事件，并将订阅方式设置为“使用长连接接收事件”。
+
+## 发送第一条飞书消息
+
+飞书接通后，你可以直接给机器人发私聊消息。
+
+如果当前配置开启了群聊提及限制，那么群聊里需要先 `@机器人`，消息才会进入处理链路。