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

package/lib/__templates__/expo/AGENTS.md

@@ -152,17 +152,25 @@ export default function TabLayout() {
     '--color-border',
   ]) as string[];
 
+  let tabBarStyle = {
+    backgroundColor: background,
+    borderTopWidth: 1,
+    borderTopColor: border,
+  };
+
+  // 用于修复 Web 上高度异常的问题（这个 if 逻辑必须添加）
+  if (Platform.OS === 'web') {
+    tabBarStyle = {
+      ...tabBarStyle,
+      height: 'auto',
+    }
+  }
+
   return (
     <Tabs
       screenOptions={{
         headerShown: false,
-        tabBarStyle: {
-          backgroundColor: background,
-          borderTopWidth: 1,
-          borderTopColor: border,
-          // 通过固定宽度 55 来修正 Web 上的表现
-          height: Platform.OS === 'web' ? 55 : 50 + insets.bottom,
-        },
+        tabBarStyle,
         tabBarActiveTintColor: accent,
         tabBarInactiveTintColor: muted,
       }}

package/lib/__templates__/expo/README.md

@@ -152,17 +152,25 @@ export default function TabLayout() {
     '--color-border',
   ]) as string[];
 
+  let tabBarStyle = {
+    backgroundColor: background,
+    borderTopWidth: 1,
+    borderTopColor: border,
+  };
+
+  // 用于修复 Web 上高度异常的问题（这个 if 逻辑必须添加）
+  if (Platform.OS === 'web') {
+    tabBarStyle = {
+      ...tabBarStyle,
+      height: 'auto',
+    }
+  }
+
   return (
     <Tabs
       screenOptions={{
         headerShown: false,
-        tabBarStyle: {
-          backgroundColor: background,
-          borderTopWidth: 1,
-          borderTopColor: border,
-          // 通过固定宽度 55 来修正 Web 上的表现
-          height: Platform.OS === 'web' ? 55 : 50 + insets.bottom,
-        },
+        tabBarStyle,
         tabBarActiveTintColor: accent,
         tabBarInactiveTintColor: muted,
       }}

package/lib/__templates__/expo/client/eslint.config.mjs

@@ -10,6 +10,7 @@ import reanimated from '../eslint-plugins/reanimated/index.js';
 import reactnative from '../eslint-plugins/react-native/index.js';
 import forbidEmoji from '../eslint-plugins/forbid-emoji/index.js';
 import restrictLinearGradient from '../eslint-plugins/restrict-linear-gradient/index.js';
+import expo from '../eslint-plugins/expo/index.js';
 
 export default [
   {
@@ -66,6 +67,7 @@ export default [
       reactnative,
       forbidEmoji,
       restrictLinearGradient,
+      expo,
     },
     rules: {
       // 关闭代码风格规则
@@ -90,6 +92,7 @@ export default [
       'reanimated/ban-mix-use': 'error',
       'forbidEmoji/no-emoji': 'error',
       'restrictLinearGradient/no-linear-gradient-backgroundcolor': 'error',
+      'expo/require-globalcss-and-provider': 'error',
       // 禁止使用 via.placeholder.com 服务
       'no-restricted-syntax': [
         'error',

package/lib/__templates__/expo/eslint-plugins/expo/index.js

@@ -0,0 +1,9 @@
+const requireGlobalCssAndProvider = require('./rule')
+
+const plugin = {
+  rules: {
+    'require-globalcss-and-provider': requireGlobalCssAndProvider,
+  },
+}
+
+module.exports = plugin

package/lib/__templates__/expo/eslint-plugins/expo/rule.js

@@ -0,0 +1,105 @@
+function normalizeFilename(filename) {
+  // ESLint may provide Windows paths; normalize to forward slashes for suffix checks.
+  return typeof filename === 'string' ? filename.replace(/\\/g, '/') : ''
+}
+
+function isTargetLayoutFile(context) {
+  return normalizeFilename(context.getFilename()).endsWith('/app/_layout.tsx')
+}
+
+function isSideEffectImportOf(node, sourceValue) {
+  return (
+    node &&
+    node.type === 'ImportDeclaration' &&
+    node.source &&
+    node.source.type === 'Literal' &&
+    node.source.value === sourceValue &&
+    Array.isArray(node.specifiers) &&
+    node.specifiers.length === 0
+  )
+}
+
+function getProviderImportLocalName(node) {
+  if (
+    !node ||
+    node.type !== 'ImportDeclaration' ||
+    !node.source ||
+    node.source.type !== 'Literal' ||
+    node.source.value !== '@/components/Provider'
+  ) {
+    return null
+  }
+
+  const specifiers = Array.isArray(node.specifiers) ? node.specifiers : []
+  if (specifiers.length !== 1) return null
+  const [specifier] = specifiers
+  if (specifier.type !== 'ImportSpecifier') return null
+  if (!specifier.imported || specifier.imported.type !== 'Identifier') return null
+  if (!specifier.local || specifier.local.type !== 'Identifier') return null
+
+  // Allow `import { Provider } ...` and `import { Provider as XXX } ...`
+  if (specifier.imported.name !== 'Provider') return null
+  return specifier.local.name
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require global.css import and Provider usage in app/_layout.tsx',
+      recommended: 'error',
+    },
+    schema: [],
+    messages: {
+      missingGlobalCssImport: `app/_layout.tsx 必须引入 global.css 文件（参考写法：import '../global.css'）`,
+      requireProviderImportAndUsage:
+        "app/_layout.tsx 必须从 @/components/Provider 导入 Provider（参考写法：import { Provider } from '@/components/Provider'），并使用导入的 Provider 包裹其余组件",
+    },
+  },
+
+  create(context) {
+    if (!isTargetLayoutFile(context)) {
+      return {}
+    }
+
+    let hasGlobalCssImport = false
+    let providerImportLocalName = null
+    let hasProviderJsxUsage = false
+
+    return {
+      Program(node) {
+        const body = Array.isArray(node.body) ? node.body : []
+        for (const stmt of body) {
+          if (isSideEffectImportOf(stmt, '../global.css')) {
+            hasGlobalCssImport = true
+          }
+          const localName = getProviderImportLocalName(stmt)
+          if (localName) {
+            providerImportLocalName = localName
+          }
+        }
+      },
+
+      JSXOpeningElement(node) {
+        if (!node || !node.name) return
+        if (
+          providerImportLocalName &&
+          node.name.type === 'JSXIdentifier' &&
+          node.name.name === providerImportLocalName
+        ) {
+          hasProviderJsxUsage = true
+        }
+      },
+
+      'Program:exit'(node) {
+        if (!hasGlobalCssImport) {
+          context.report({ node, messageId: 'missingGlobalCssImport' })
+        }
+
+        if (!providerImportLocalName || !hasProviderJsxUsage) {
+          context.report({ node, messageId: 'requireProviderImportAndUsage' })
+        }
+      },
+    }
+  },
+}

package/lib/__templates__/expo/eslint-plugins/expo/tech.md

@@ -0,0 +1,108 @@
+# expo 技术设计（layout 规则）
+
+## 目标
+- 强约束 Expo Router 的 `app/_layout.tsx` 模板结构，避免初始化项目后被误删导致运行时样式/上下文缺失
+- 校验 `app/_layout.tsx` 必须：
+  - 包含 `import '../global.css'`
+  - 使用从 `@/components/Provider` 导入的 Provider 组件作为 JSX 组件（允许 `import { Provider } ...` 或 `import { Provider as XXX } ...`）
+- 实现轻量、易维护，不引入新依赖
+
+## 规则命名与对外形态
+- 插件目录：expo/eslint-plugins/expo
+- 规则名：expo/require-globalcss-and-provider
+- 规则类型：problem
+- 默认等级：error
+
+## 规则行为定义
+### 报错
+仅对目标文件 `app/_layout.tsx` 生效，满足以下任一情况报错：
+- 缺少 side-effect import：`import '../global.css'`
+- 缺少或不符合要求的 Provider 导入语句：
+  - 必须从 `@/components/Provider` 导入
+  - 必须为命名导入，导入名必须为 `Provider`
+  - 允许形式：
+    - `import { Provider } from '@/components/Provider';`
+    - `import { Provider as XXX } from '@/components/Provider';`
+- 未在 JSX 中使用导入的 Provider 组件（例如：只导入但从未作为 JSX 组件出现）
+
+### 不报错
+- 非 `app/_layout.tsx` 文件不做检查
+- 目标文件同时满足：
+  - 存在 `import '../global.css'`
+  - 存在 Provider 命名导入（允许 as 别名）
+  - JSX 中至少出现一次 `<Provider ...>` / `<Provider>` 或 `<XXX ...>` / `<XXX>`（XXX 为别名）
+
+## 检测策略
+### 目标文件判定
+- 通过 `context.getFilename()` 获取当前文件路径
+- 仅当路径以 `/app/_layout.tsx` 结尾时启用规则（同时兼容 Windows 路径分隔符做归一化）
+
+### AST 访问节点
+- `Program`：收集顶层 `ImportDeclaration`，判定是否存在目标 import
+- `JSXOpeningElement` / `JSXElement`：判定是否使用 `<Provider>`
+
+### Import 判定细则
+- global.css：
+  - `ImportDeclaration.source.value === '../global.css'`
+  - `ImportDeclaration.specifiers.length === 0`（side-effect import）
+- Provider import（严格形式）：
+  - `ImportDeclaration.source.value === '@/components/Provider'`
+  - `ImportDeclaration.specifiers` 仅包含一个 `ImportSpecifier`
+  - `specifier.imported.name === 'Provider'`，`specifier.local.name` 允许为 `Provider` 或任意别名
+
+## 报错信息
+- messageId: missingGlobalCssImport
+  - 文案：`app/_layout.tsx 必须包含 "import '../global.css';"`
+- messageId: requireProviderImportAndUsage
+  - 文案：`app/_layout.tsx 中必须从 @/components/Provider 导入 Provider（参考写法：import { Provider } from '@/components/Provider'），并使用导入的 Provider 包裹其余组件`
+
+## 典型示例
+### 触发
+- 缺少 global.css：
+  - 未包含 `import '../global.css';`
+- Provider import 形式不对：
+  - `import Provider from '@/components/Provider'`
+  - `import { Provider } from '@/components/provider'`
+- Provider 未使用：
+  - 有 `import { Provider } ...`，但 JSX 中没有 `<Provider>`
+
+### 不触发
+```tsx
+import { Provider } from '@/components/Provider';
+import '../global.css';
+
+export default function RootLayout() {
+  return (
+    <Provider>
+      {/* ... */}
+    </Provider>
+  );
+}
+```
+
+```tsx
+import { Provider as AppProvider } from '@/components/Provider';
+import '../global.css';
+
+export default function RootLayout() {
+  return (
+    <AppProvider>
+      {/* ... */}
+    </AppProvider>
+  );
+}
+```
+
+## 边界与决策
+- 仅做结构约束，不尝试自动修复（fixer）以避免在 TSX 顶部插入 import 引起格式与注释位置变化
+- 仅检查 JSX 中的 `<Provider>` 使用，不做“必须最外层包裹”的结构分析，降低复杂度与误报
+
+## 性能考虑
+- 仅在命中目标文件时启用
+- 仅扫描顶层 import 与 JSX 标签名，复杂度 O(n)
+
+## 测试计划
+- 缺少 global.css import：报 `missingGlobalCssImport`
+- 未从 `@/components/Provider` 正确导入 Provider：报 `requireProviderImportAndUsage`
+- Provider 未在 JSX 使用：报 `requireProviderImportAndUsage`
+- 满足全部要求：不报错

package/lib/__templates__/nextjs/AGENTS.md

@@ -42,6 +42,15 @@
 
 ## 开发规范
 
+### 编码规范
+
+- 默认按 TypeScript `strict` 心智写代码；优先复用当前作用域已声明的变量、函数、类型和导入，禁止引用未声明标识符或拼错变量名。
+- 禁止隐式 `any` 和 `as any`；函数参数、返回值、解构项、事件对象、`catch` 错误在使用前应有明确类型或先完成类型收窄，并清理未使用的变量和导入。
+
+### next.config 配置规范
+
+- 配置的路径不要写死绝对路径，必须使用 path.resolve(__dirname, ...)、import.meta.dirname 或 process.cwd() 动态拼接。
+
 ### Hydration 问题防范
 
 1. 严禁在 JSX 渲染逻辑中直接使用 typeof window、Date.now()、Math.random() 等动态数据。**必须使用 'use client' 并配合 useEffect + useState 确保动态内容仅在客户端挂载后渲染**；同时严禁非法 HTML 嵌套（如 <p> 嵌套 <div>）。

package/lib/__templates__/nextjs/eslint.config.mjs

@@ -10,6 +10,15 @@ const syntaxRules = [
   },
 ];
 
+const nextConfigRestrictedSyntaxRules = [
+  {
+    selector:
+      'Property[key.name=/^(root|outputFileTracingRoot)$/] > Literal[value=/^\\//]',
+    message:
+      '禁止在 next.config 中写死绝对路径，请改用 path.resolve(__dirname, ...)、import.meta.dirname 或 process.cwd() 动态拼接。',
+  },
+];
+
 const eslintConfig = defineConfig([
   ...nextVitals,
   ...nextTs,
@@ -19,6 +28,12 @@ const eslintConfig = defineConfig([
       'no-restricted-syntax': ['error', ...syntaxRules],
     },
   },
+  {
+    files: ['next.config.ts'],
+    rules: {
+      'no-restricted-syntax': ['error', ...nextConfigRestrictedSyntaxRules],
+    },
+  },
   // Override default ignores of eslint-config-next.
   globalIgnores([
     // Default ignores of eslint-config-next:

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