@coze-arch/cli 0.0.14 → 0.0.15-alpha.a0f5b9

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

@@ -7,3 +7,6 @@ cd "${COZE_WORKSPACE_PATH}"
 
 echo "Installing dependencies..."
 pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+if command -v coze > /dev/null 2>&1 && coze check-bins --help > /dev/null 2>&1; then
+  coze check-bins --fix
+fi

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

@@ -7,6 +7,9 @@ cd "${COZE_WORKSPACE_PATH}"
 
 echo "Installing dependencies..."
 pnpm install --prefer-frozen-lockfile --prefer-offline
+if command -v coze > /dev/null 2>&1 && coze check-bins --help > /dev/null 2>&1; then
+  coze check-bins --fix
+fi
 
 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,140 @@
+# Pi Bot AGENTS Guide
+
+## 1. 项目定位
+
+- 这是一个基于 Pi 开发、已经可运行的 agent 项目，并且可以按需要继续扩展能力。
+- 默认目标不是直接修改宿主实现，而是优先沿用 Pi 生态扩展方式交付需求。
+- repo 内长期维护、应进入版本管理的 Pi 资源，统一放在 `pi-resources/`。
+- `<%= workspaceDir %>/.pi/` 是本地覆盖层和调试层，不是 repo 内资源的主落点；除非用户明确要求做本地覆盖，否则不要把长期方案放进去。
+
+## 2. 必读顺序
+
+在进行较大修改前，优先按下面顺序理解项目：
+
+1. `README.md`
+2. `docs/project-overview.md`
+3. `src/pi-resources.ts`
+4. `pi-resources/` 下与需求相关的资源
+5. 与改动相关的测试
+
+## 3. 先做实现路径判断
+
+默认按下面优先级选择落点，能在前一层解决就不要进入后一层：
+
+- agent 的长期行为、角色、边界、默认协作方式、长期规则：
+  - `pi-resources/SYSTEM.md`
+- 可复用 prompt 模板或调用模板：
+  - `pi-resources/prompts/`
+- 可复用工作流、脚本型能力、操作指南：
+  - `pi-resources/skills/<skill-name>/`
+- 生命周期钩子、tool 注册、记忆注入、runtime 增强、agent 侧能力：
+  - `pi-resources/extensions/<extension-name>/`
+- 只有涉及宿主层时才改 `src/`：
+  - channel 协议适配、消息收发、路由 gating
+  - session key、transcript、持久化
+  - config schema、provider 解析、启动装配
+  - dashboard API / web UI
+  - `customTools` 装配
+  - 资源加载器本身
+
+如果需求能通过 `pi-resources` 实现，就不要去改 `src/`。
+
+## 4. 当前仓库里的 Pi 扩展事实
+
+- `src/pi-resources.ts` 会把 repo 内的 `pi-resources/extensions/`、`pi-resources/skills/`、`pi-resources/prompts/`、`pi-resources/SYSTEM.md` 自动接入 runtime。
+- runtime 显式关闭了 `AGENTS.md` 自动加载；不要假设 bot 运行时会读取工作区里的 `AGENTS.md`。
+- `<%= workspaceDir %>/.pi/SYSTEM.md` 的优先级高于 repo 的 `pi-resources/SYSTEM.md`，但它是覆盖层，不是版本管理主落点。
+- extension 的自动发现规则不是“目录存在就会生效”：
+  - 顶层 `*.ts` / `*.js` 文件会被加载
+  - 子目录里只有 `package.json` 的 `pi.extensions` 指向文件，或存在 `index.ts` / `index.js` 时，才会被加载
+- 当前可参考的 extension 示例：
+  - `pi-resources/extensions/test-ping.ts`
+  - `pi-resources/extensions/preference-memory/index.ts`
+- 当前可参考的 skill 示例：
+  - `pi-resources/skills/coze-asr/`
+  - `pi-resources/skills/coze-image-gen/`
+  - `pi-resources/skills/coze-tts/`
+  - `pi-resources/skills/coze-video-gen/`
+
+## 5. 宿主层边界
+
+- 不要在 `src/channels/*`、`src/index.ts`、消息入口、路由层或其他 host 代码里，通过关键词匹配、意图判断或硬编码分支，手动把请求分流到某个搜索器、抓取器、collector 或 workflow。
+- 搜索、抓取、检索、知识注入、热点汇总、项目记忆、外部服务调用等能力，默认应作为 agent 可调用的 tool、extension、skill 或 prompt 提供。
+- host 层只负责：
+  - 平台协议适配
+  - 消息归一化
+  - 路由 gating
+  - 会话归类
+  - 持久化
+  - config / provider 装配
+  - dashboard
+- 如果某能力理论上能做成 `pi-resources/extensions/*`，就不要默认在 `src/tools/*` 和 `src/agent.ts` 里新增 `customTools`。
+
+## 6. 修改策略
+
+- 优先做小步、增量、可验证的修改。
+- 新需求若能在 `pi-resources` 落地，不要顺手重构宿主代码。
+- 如果用户需求涉及产出新的 `.md` 文件，默认把文件落在当前工作目录 `cwd`，不要放进 `src/` 或其他源码目录；只有当用户明确指定路径，或明确要求更新现有文档入口时，才放到对应位置。
+- 若必须改 `src/`，最终说明里必须写清楚：
+  - 为什么 `pi-resources` 不足以承载
+  - 改动影响了哪些宿主职责
+  - 是否需要补测试和文档
+
+## 7. 常见改动落点
+
+- 调整 agent 默认行为：
+  - `pi-resources/SYSTEM.md`
+- 新增 prompt 模板：
+  - `pi-resources/prompts/`
+- 新增 skill：
+  - `pi-resources/skills/<skill-name>/SKILL.md`
+  - 必要的 `scripts/*`
+- 用户要求新建 Markdown 文档、方案、总结、设计稿等 `.md` 文件：
+  - 默认放在 `cwd`
+  - 不要默认放进 `src/` 或其他源码目录
+- 新增 extension / runtime tool：
+  - `pi-resources/extensions/<extension-name>/index.ts`
+  - 或 `pi-resources/extensions/*.ts`
+- 修改资源装配逻辑本身：
+  - `src/pi-resources.ts`
+  - `tests/pi-resources.test.ts`
+- 修改 provider、runtime、session、channel、dashboard：
+  - 对应 `src/*`
+  - 对应 `tests/*`
+
+## 8. 验证要求
+
+默认情况下：
+
+- 任何改动都至少运行与改动直接相关的验证。
+- 修改 `pi-resources`、资源装配、extensions、skills、SYSTEM 行为时，至少考虑运行：
+  - `npm test`
+  - `npm run typecheck`
+- 修改 Dashboard 前端或其构建相关内容时，再运行：
+  - `npm run dashboard:build`
+- 修改跨模块主链路，例如 config、channel、runtime、session、dashboard 联动时，再运行：
+  - `npm run smoke`
+
+如果因为环境限制无法完成验证，需要在最终说明中明确指出未验证项、风险和建议的人工验证方式。
+
+## 9. 高风险变更先确认
+
+遇到以下改动，先暂停并与用户确认：
+
+- 修改 `workspace/config.json` schema 或默认值语义
+- 修改 `getSessionKey()` 规则
+- 修改 session、transcript、index、archive 格式
+- 修改默认 channel 路由或触发条件
+- 删除现有 API、页面、配置项或持久化数据
+- 把本可通过 `pi-resources` 完成的能力，改成宿主层硬编码方案
+
+## 10. 目标
+
+你的目标是在当前项目里持续交付用户需要的能力，同时尽量保证：
+
+- 优先使用 Pi 生态扩展方式
+- 尽量少动宿主层，只有必要时才动
+- 行为可预测
+- 配置与数据兼容
+- 出问题时便于排查
+- 后续继续二次开发时容易维护

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

@@ -0,0 +1,172 @@
+# Pi Bot
+
+这是一个基于 `pi-mono` / `@mariozechner/pi-coding-agent` 的 Bot 项目。
+
+## 当前结构
+
+- `src/config.ts`
+  - 项目唯一配置入口，读取 `config.json` 并装配 `BotAppConfig`
+- `src/index.ts`
+  - 应用启动入口
+- `src/agent.ts`
+  - agent runtime 封装
+- `src/pi-resources.ts`
+  - repo 内置 Pi 资源装配，统一把源码目录接到 runtime
+- `pi-resources/`
+  - 版本管理下的 skills / prompts / extensions / SYSTEM.md 源码目录
+- `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`。
+默认会使用 `pi` runtime；如果你只是想走本地 mock 链路，可以额外设置 `PI_BOT_AGENT_MODE=mock`。
+
+## 用户文档
+
+启动后，可以在 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 模式
+
+- 默认情况下，`npm run dev` 使用 `PI_BOT_AGENT_MODE=pi`
+- `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`，避免依赖真实配置文件。
+
+## Pi 资源
+
+项目内置的 Pi 资源统一维护在 `pi-resources/` 下，并在 runtime 初始化时以代码方式注入：
+
+- `pi-resources/extensions/`
+- `pi-resources/skills/`
+- `pi-resources/prompts/`
+- `pi-resources/SYSTEM.md`
+
+`<%= workspaceDir %>/.pi/` 仍然可以作为本地调试覆盖层，但不再作为这些资源的源码真身。当前项目也会显式关闭 `AGENTS.md` 自动加载，避免工作区目录里的上下文文件混入 bot 运行时。
+
+默认主模型来自：
+
+```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/_npmrc

@@ -0,0 +1,23 @@
+loglevel=error
+registry=https://registry.npmmirror.com
+
+strictStorePkgContentCheck=false
+verifyStoreIntegrity=false
+
+# 网络优化
+network-concurrency=16
+fetch-retries=3
+fetch-timeout=60000
+
+# 严格使用 peer dependencies
+strict-peer-dependencies=false
+
+# 自动生成 lockfile
+auto-install-peers=true
+
+# lockfile 配置
+lockfile=true
+prefer-frozen-lockfile=true
+
+# 如果 lockfile 存在但过期，更新而不是失败
+resolution-mode=highest