@coze-arch/cli 0.0.13 → 0.0.14-alpha.c52ee4

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` 事件，并将订阅方式设置为“使用长连接接收事件”。
+
+## 发送第一条飞书消息
+
+飞书接通后，你可以直接给机器人发私聊消息。
+
+如果当前配置开启了群聊提及限制，那么群聊里需要先 `@机器人`，消息才会进入处理链路。

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

@@ -0,0 +1,52 @@
+{
+  "name": "pi-bot",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "scripts": {
+    "dev": "bash scripts/dev.sh",
+    "start": "npm run dev",
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "smoke": "node --import tsx tests/smoke/run-smoke.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dashboard:build": "vite build --config src/dashboard/web/vite.config.ts"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.60.0",
+    "@mariozechner/pi-agent-core": "^0.63.2",
+    "@mariozechner/pi-ai": "^0.63.2",
+    "@mariozechner/pi-coding-agent": "^0.63.2",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@streamdown/code": "^1.1.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "express": "^4.21.2",
+    "lodash-es": "^4.18.1",
+    "lucide-react": "^1.8.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0",
+    "sonner": "^2.0.7",
+    "streamdown": "^2.5.0",
+    "tailwind-merge": "^3.5.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.2.2",
+    "@types/express": "^4.17.22",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^24.3.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@types/ws": "^8.5.10",
+    "@vitejs/plugin-react": "^4.3.3",
+    "autoprefixer": "^10.4.27",
+    "postcss": "^8.5.9",
+    "tailwindcss": "^4.2.2",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2",
+    "vite": "^6.0.6"
+  }
+}