@lark-apaas/coding-steering 0.1.32-beta.0 → 0.1.32-dev.4f80f68

package/steering/nestjs-react-fullstack/skills/plugin-guide/references/plugin-coding-guide.md

@@ -68,7 +68,9 @@
 ```markdown
 [Schema 摘录卡]
 - pluginInstanceId / actionKey / outputMode
-- input.required / output.fields / readme.constraints
+- input.required: [字段名: 类型, ...]
+- output.fields: [字段名: 类型, ...]（每个字段必须在代码中被消费，未消费需注释说明原因）
+- readme.constraints
 - 调用侧决策: Client | Server
 ```
 
@@ -339,6 +341,18 @@ this.somePluginInstanceSideEffect(input).catch(error => {
 
 ---
 
+### 调用错误分类与应对
+
+| 错误类型 | 含义 | 应对策略 |
+|----------|------|---------|
+| `InputValidationError` | 入参不符合 schema | 修复参数后重试，不应出现在生产环境 |
+| `RateLimitError` | 触发限流 | 指数退避重试（1s/2s/4s），最多 3 次 |
+| `ExecutionError` | 插件执行失败 | 记录日志 + 降级方案（如规则计算）+ 通知用户 |
+| `OutputValidationError` | 返回值不符合 schema | 记录异常返回 + 使用默认值或降级 |
+| 网络超时 | 请求超时 | 重试 + 超时后降级 |
+
+---
+
 ### outputMode 与调用侧选择
 
 先通过 `get_plugin_ai_json(pluginInstanceId)` 获取 `actions[].outputMode`：

package/steering/nestjs-react-fullstack/skills/plugin-guide/references/table.md

@@ -146,6 +146,20 @@
 ❌ searchRecords 拉全量 → find 找单条 → 必须用 getRecord
 ```
 
+## 数据架构选择（应用读取多维表格数据时）
+
+按**查询模式**选择架构：
+
+| 查询模式 | 架构选择 | 实现方式 |
+|---------|---------|---------|
+| 展示/编辑单条记录 | 纯插件 | `getRecord` / `batchUpdateRecords` |
+| 列表分页浏览 | 纯插件 | `searchRecords` + `pageToken` 游标分页 |
+| 统计聚合（计数/求和/平均） | **纯插件 + aggregateQuery** | 禁止 searchRecords 全量拉取后内存计算 |
+| 统计 + 明细下钻 | 纯插件 | 聚合用 `aggregateQuery`，下钻用 `searchRecords` + filter |
+| 排行榜 / TOP N | 纯插件 | `searchRecords` + sort + pageSize=N |
+| 复杂排序/多表关联/全文搜索 | 插件同步 + 本地数据库 | 定时/Webhook 同步到 postgres，复杂查询走数据库 |
+| 高频写入 + 读取 | 本地数据库为主 | 多维表格仅作展示/备份 |
+
 ## 数据分析类Action补充说明
 
 `aggregateQuery` 用于分组聚合统计，支持 dimensions（分组维度）和 measures（聚合计算）。
@@ -301,23 +315,25 @@ const chartData =
 
 ## 推荐 UI 组件
 
-| BizType                      | 展示                                                                  | 录入                                        |
-| ---------------------------- | --------------------------------------------------------------------- | ------------------------------------------- |
-| `User`                       | `<UserDisplay users={ids.map(id => ({ user_id: id.toString() }))} />` | `<UserSelect multiple />`                   |
-| `Url`                        | `<Hyperlink value={val} readOnly />`                                  | `<Hyperlink readOnly={false} />`            |
-| `SingleSelect`/`MultiSelect` | 文本/标签                                                             | `<Select>` 选项来自 enumValues              |
-| `DateTime`                   | `new Date(ts).toLocaleDateString()`                                   | `<Input type="date" />`                     |
-| `Checkbox`                   | `value ? '是' : '否'`                                                 | `<Checkbox />`                              |
-| `Currency`                   | `¥${value.toFixed(2)}`                                                | `<Input type="number" />`                   |
-| `Progress`                   | `${value}%` 或进度条                                                  | `<Input type="number" min={0} max={100} />` |
-| `Rating`                     | `'★'.repeat(value) + '☆'.repeat(5-value)`                             | `<Input type="number" min={0} max={5} />`   |
+| BizType                      | 展示                                                                 | 录入                                        |
+| ---------------------------- | -------------------------------------------------------------------- | ------------------------------------------- |
+| `User`                       | `<UserDisplay value={ids.map(id => id.toString())} />`               | `<UserSelect multiple />`                   |
+| `Url`                        | `<Hyperlink value={val} readOnly />`                                 | `<Hyperlink readOnly={false} />`            |
+| `SingleSelect`/`MultiSelect` | 文本/标签                                                            | `<Select>` 选项来自 enumValues              |
+| `DateTime`                   | `new Date(ts).toLocaleDateString()`                                  | `<Input type="date" />`                     |
+| `Checkbox`                   | `value ? '是' : '否'`                                                | `<Checkbox />`                              |
+| `Currency`                   | `¥${value.toFixed(2)}`                                               | `<Input type="number" />`                   |
+| `Progress`                   | `${value}%` 或进度条                                                 | `<Input type="number" min={0} max={100} />` |
+| `Rating`                     | `'★'.repeat(value) + '☆'.repeat(5-value)`                            | `<Input type="number" min={0} max={5} />`   |
+
+BizType 为 `User` 的字段展示必须使用 business-ui `UserDisplay`；不要直接渲染、拼接或 `join` 用户 ID 文本。
 
 ### 组件代码示例
 
 ```tsx
-// 人员展示
+// 人员展示（business-ui UserDisplay 使用 value；不要传 users）
 <UserDisplay
-  users={record['人员字段']?.map(userId => ({ user_id: userId.toString() })) || []}
+  value={record['人员字段']?.map(userId => userId.toString()) || []}
   size="small"
   showLabel={true}
 />
@@ -365,13 +381,13 @@ const chartData =
 const columns = [
   // 文本字段 - 注意读取格式是 { text: string }
   { title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' },
-  // 人员字段 - 使用 UserDisplay 组件
+  // 人员字段 - 使用 business-ui UserDisplay 组件，传 value（用户 ID 字符串数组），不要传 users
   {
     title: '负责人',
     key: 'user',
     render: (_, record) => (
       <UserDisplay
-        users={record.record['人员字段']?.map((id) => ({ user_id: id.toString() })) || []}
+        value={record.record['人员字段']?.map((id) => id.toString()) || []}
         size="small"
       />
     ),

package/steering/nestjs-react-fullstack/skills/raw-sql-boundary-audit/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: raw-sql-boundary-audit
+description: >-
+  Use when editing or reviewing NestJS backend database code that contains Drizzle raw `sql` tagged templates,
+  db.execute(sql`...`), report/statistics/aggregation endpoints, filter (...), CASE WHEN, window functions,
+  or custom type / Date range parameters.
+steering: true
+steering-inclusion: always
+steering-topic: raw_sql_boundary_audit
+match-template-name: nestjs-react-fullstack
+unavailable-agents:
+  - AppInit
+  - SpecDoc
+---
+
+# Drizzle raw SQL 参数边界审计
+
+本 skill 只管一件事：改 NestJS 后端数据库代码时，raw `sql` 模板里的 `${...}` 参数必须是数据库 driver 可直接接收的标量。Drizzle helper 绑定 schema 列会按列 encoder 处理；raw `sql` 模板参数不会自动调用列的 `toDriver`。
+
+## 何时必须执行审计
+
+满足任一条件就执行：
+
+- 正在修改 `server/**/*.service.ts` 或 repository 中的数据库查询；
+- 文件里有 `sql\``、`db.execute(sql`、`filter (...)`、`CASE WHEN`、窗口函数或复杂 where；
+- 需求涉及统计、报表、趋势、排行、周期范围、截止时间、创建/完成时间等后端汇总接口。
+
+## 审计步骤（写代码前和提交前各做一次）
+
+1. 先读 `server/database/schema.ts`，确认相关列类型和 custom type。
+2. 枚举当前 service/repository 里的 raw SQL 模板；不要只看刚新增的查询。可用搜索辅助，但结论以读代码为准：
+
+   ```bash
+   rg -n 'sql`|db\.execute\(sql|filter \(|CASE WHEN|OVER \(' server
+   ```
+
+3. 对每个 raw SQL 模板逐个检查 `${...}` 参数：
+   - 已是 string/number/boolean、ISO string、普通 ID、`sql.join(...)` 中逐个参数化的标量：可以保留；
+   - `user_profile` 是特殊 custom type，不适用“普通 ID 标量即可”的泛化判断；raw SQL 遇到 `user_profile` 列必须按 coding-guide 的三侧写法处理：读 `(col).user_id`，写 `ROW(${userId})::user_profile`，过滤 `(col).user_id = ${userId}`；禁止裸列 SELECT、`col = ${userId}`、`col::text = ${userId}` 或 `col = ROW(...)::user_profile` 比较；
+   - 是 `Date`、date/timestamptz/custom type 的运行时对象，或变量来源不明但表示时间/自定义结构：先转 driver-safe 标量再传入 raw SQL；日期时间用 `.toISOString()`；
+   - 如果能用 `gte(col, Date)` / `lt(col, Date)` / `eq(col, value)` / `insert().values()` / `update().set()` 等绑定 schema 列的 helper 表达，就优先改回 helper。
+4. 保留 helper 安全路径：不要把 `gte(col, Date)`、`lt(col, Date)` 这类绑定列的 Drizzle helper 当成坏边界。
+5. 改完后调用受影响的真实 API，至少覆盖一个会触发该 raw SQL 的范围/筛选参数；HTTP 200 且后端无参数序列化错误才算完成。
+
+## 写法示例
+
+```typescript
+const rangeStart: Date = getRangeStart(range);
+const rangeStartIso: string = rangeStart.toISOString();
+
+// helper 绑定 schema 列，可以直接传 Date
+where: gte(tasks.createdAt, rangeStart)
+
+// raw SQL 参数先转 driver-safe 标量
+total: sql<number>`
+  count(*) filter (where ${tasks.createdAt} >= ${rangeStartIso})
+`
+
+// 不要把 Date/custom type 运行时对象直接放进 raw SQL 模板参数
+total: sql<number>`
+  count(*) filter (where ${tasks.createdAt} >= ${rangeStart})
+`
+```

package/steering/nestjs-react-fullstack/skills/server-builtins-file-storage-service/SKILL.md

@@ -11,7 +11,7 @@ match-template-name: nestjs-react-fullstack
 在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
 
 > **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
-> CLI 调试场景请参考 `file-storage` skill。
+> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件用 `miaoda file` CLI（见 `miaoda-file` skill）。二者与本 SDK 操作同一个应用存储桶，但 **`miaoda file` CLI 禁止写进服务端代码**。
 
 ## 使用场景
 

package/steering/nestjs-react-fullstack/skills_common/trigger-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trigger-guide
-description: 自动化任务触发器代码开发指南，支持 cron 定时触发器、record_change 数据变更触发器和 webhook 触发器，包含 @Automation/@BindTrigger 装饰器用法、handler 入参解析和 Crontab 表达式规范。Use when 需要：(1) 为已创建的自动化任务/定时任务编写业务 handler，(2) 编写 automation 代码绑定触发器，或其他自动化任务相关开发
+description: 自动化任务触发器配置与代码开发指南，支持 cron 定时触发器、record_change 数据变更触发器和 webhook 触发器，包含 @Automation/@BindTrigger 装饰器用法和 Crontab 表达式规范。Use when 需要：(1) 创建或配置自动化任务/定时任务，(2) 编写 automation 代码绑定触发器，或其他自动化任务相关开发
 steering: true
 steering-topic: trigger_guide
 match-template-name: nestjs-react-fullstack
@@ -30,7 +30,7 @@ server
 1. 每个模块只应该有一个存放自动化任务逻辑的文件，业务逻辑需要聚合到该文件中。
 2. 如果该模块只有对应的自动化任务，无需编写 Controller
 
-### 触发器类型
+### 触发器类型与入参
 
 触发器类型（`triggerType`）有三种：
 
@@ -38,15 +38,151 @@ server
 - `cron`：定时触发器，**无入参**
 - `webhook`：Webhook 触发器，**有入参**
 
-各触发器 handler 的入参类型定义（`TaskHandlerArgs`、`DataChangeEventInput`、`WebhookEvent`）见 [触发器入参类型与代码示例](references/trigger-lifecycle.md)。
+```typescript
+// 有入参触发器的入参类型（triggerType = 'record_change' 时）
+interface TaskHandlerArgs {
+  attributes: {
+    trigger: string;
+    triggerID?: string;
+    triggerType: 'record_change' | 'cron' | 'webhook';
+    instanceID: string;
+    startAt?: number;
+  };
+  content: {
+    input: string;  // JSON 字符串，根据 triggerType 解析为对应类型
+  };
+}
 
-### 指定值限制
+// record_change：input 解析后的数据结构
+interface DataChangeEventInput {
+  id: string;
+  tenant_id: number;
+  workspace: string;
+  branch: string;
+  app: string;
+  table: string;
+  type: 'INSERT' | 'UPDATE' | 'DELETE';
+  timestamp: number;
+  before?: Record<string, unknown>;  // DELETE 时有值，其他情况可能为空
+  after?: Record<string, unknown>;   // INSERT/UPDATE 时有值，其他情况可能为空
+  msg_id: string;
+}
 
-1. Webhook 触发器不可以设置指定值，并且告知用户。
+// webhook：input 解析后的数据结构
+interface WebhookEvent {
+  method: 'GET' | 'POST';
+  url: string;                          // 完整 URL（含查询参数）
+  host: string;                         // 不含查询参数的 URL
+  path: string;                         // 路径部分
+  query: Record<string, string[]>;      // URL 查询参数，值为字符串数组
+  headers: Record<string, string[]>;    // 请求头，值为字符串数组
+  body: string;                         // 请求体，JSON 字符串
+  meta: {
+    timestamp: number;                  // 请求时间戳（秒）
+    traceID: string;                    // 追踪 ID
+    env: 'development' | 'online';      // 环境：开发/线上
+  };
+}
+```
 
-### 代码绑定
+### 指定值限制
+1. Webhook 触发器不可以设置指定值，并且告知用户。
 
-你需要根据触发器创建后确定的自动化任务名字（应用内唯一），编写并绑定到对应的方法上：`@BindTrigger('<任务名字>')` 中的名字必须与创建触发器时确定的名字逐字相同，不能用 trigger ID 或方法名代替。`@Automation()` 标记的类需注册为对应 `<module>.module.ts` 的 provider，且该 module 必须被 `server/app.module.ts` 直接或传递 import，否则装饰器不会生效。完整代码示例见 [触发器入参类型与代码示例](references/trigger-lifecycle.md)。
+### 代码示例
+
+你需要根据 `automation_trigger_manager` 工具返回的自动化任务名字，编写并绑定到对应的方法上。具体代码示例如下：
+
+```typescript
+// 文件名：demo.automation.ts
+import { Logger } from '@nestjs/common';
+// 必须导入
+import { Automation, BindTrigger } from '@lark-apaas/fullstack-nestjs-core';
+
+/**
+ * 示例自动化任务服务
+ * 使用 @Automation 装饰器标记 class，@BindTrigger 绑定具体 function
+ */
+@Automation()
+export class DemoAutomationTasksService {
+  // 务必使用 logger 打印日志
+  private readonly logger = new Logger(DemoAutomationTasksService.name);
+
+  @BindTrigger('triggerName1')
+  // 任务对应具体的实现
+  async helloWorld() {
+    this.logger.log('执行 Hello World 任务');
+    // do logic
+    // return logic result or throw Error
+  }
+
+  @BindTrigger('triggerName2')
+  // 任务对应具体的实现
+  async sendNotification() {
+    this.logger.log('开始发送通知');
+    // do logic
+    this.logger.log('通知发送完成');
+    // return logic result or throw Error
+  }
+
+  @BindTrigger('recordChangeTrigger')
+  // 记录变更任务（triggerType = 'record_change'）
+  async handleDataChange(event: TaskHandlerArgs) {
+    // 1. 校验并解析 input
+    const input = event.content.input;
+    if (typeof input !== 'string') {
+      this.logger.error('input 类型错误');
+      return;
+    }
+
+    let eventData: DataChangeEventInput;
+    try {
+      eventData = JSON.parse(input);
+    } catch (error) {
+      this.logger.error('JSON 解析失败', error);
+      return;
+    }
+
+    // 2. 根据操作类型获取数据：INSERT/UPDATE 用 after，DELETE 用 before
+    const record = eventData.after || eventData.before;
+    if (!record) {
+      this.logger.error('记录数据为空');
+      return;
+    }
+    this.logger.log(`处理 ${eventData.type} 事件，记录ID: ${record.id}`);
+    // do logic
+    // return logic result or throw Error
+  }
+
+  @BindTrigger('webhookTrigger')
+  // Webhook 任务（triggerType = 'webhook'）
+  async handleWebhook(event: TaskHandlerArgs) {
+    // 1. 校验并解析 input
+    const input = event.content.input;
+    if (typeof input !== 'string') {
+      this.logger.error('input 类型错误');
+      return;
+    }
+
+    let webhookEvent: WebhookEvent;
+    try {
+      webhookEvent = JSON.parse(input);
+    } catch (error) {
+      this.logger.error('JSON 解析失败', error);
+      return;
+    }
+
+    // 2. 获取请求信息
+    const { method, path, query, headers, body } = webhookEvent;
+    this.logger.log(`处理 Webhook 请求：${method} ${path}`);
+
+    // 3. 按需解析 body（body 本身也是 JSON 字符串）
+    // const bodyData = JSON.parse(body);
+
+    // do logic
+    // return logic result or throw Error
+  }
+}
+```
 
 ### 任务代码实现约束
 
@@ -62,12 +198,148 @@ server
 
 ### 技术实现路径参考
 
-以下常见需求的推荐实现路径，帮助你在平台能力限制下找到合理的技术方案；完整代码见 [触发器入参类型与代码示例](references/trigger-lifecycle.md)。
+以下是一些常见需求的推荐实现路径，帮助你在平台能力限制下找到合理的技术方案。
+
+#### 场景一：用户需要管理页面控制定时任务的启停
+
+平台侧不支持通过 API 动态启停触发器。推荐方案：**平台定时触发器始终保持开启，在任务执行时查询数据库中的开关状态，决定是否真正执行业务逻辑。**
+
+实现步骤：
+
+1. 在数据库中建一张配置表（或复用已有配置表），存储任务开关状态
+2. 前端管理页面提供开关操作，修改数据库中的状态
+3. 定时任务触发时，先查询开关状态，关闭则直接跳过
+
+```typescript
+@Automation()
+export class ReportAutomationService {
+  private readonly logger = new Logger(ReportAutomationService.name);
+
+  constructor(private readonly configService: ConfigService) {}
+
+  @BindTrigger('dailyReportTrigger')
+  async generateDailyReport() {
+    // 1. 先查询任务开关状态
+    const config = await this.configService.getTaskConfig('dailyReport');
+    if (!config?.enabled) {
+      this.logger.log('每日报告任务已被管理员关闭，跳过执行');
+      return;
+    }
+
+    // 2. 开关开启，执行实际业务逻辑
+    this.logger.log('开始生成每日报告');
+    // do logic
+  }
+}
+```
+
+#### 场景二：定时任务需要将结果通知给特定用户
+
+自动化任务执行时无法获取当前用户上下文。推荐方案：**在数据库中预存需要通知的用户 ID，任务执行时从数据库查询目标用户，再调用飞书插件发送通知。**
+
+```typescript
+@Automation()
+export class NotifyAutomationService {
+  private readonly logger = new Logger(NotifyAutomationService.name);
+
+  constructor(
+    private readonly userConfigService: UserConfigService,
+  ) {}
+
+  @BindTrigger('weeklyDigestTrigger')
+  async sendWeeklyDigest() {
+    // 1. 从数据库查询订阅了周报的用户列表
+    const subscribers = await this.userConfigService.getSubscribers('weeklyDigest');
+    if (!subscribers.length) {
+      this.logger.log('无订阅用户，跳过发送');
+      return;
+    }
+
+    // 2. 生成周报内容
+    const reportContent = await this.buildWeeklyReport();
+
+    // 3. 逐个发送通知
+    for (const user of subscribers) {
+      // 调用插件发送飞书消息
+      this.logger.log(`已发送周报给用户: ${user.userId}`);
+    }
+  }
+}
+```
+
+#### 场景三：记录变更触发器需要做防抖/去重
+
+高频数据变更场景下，同一条记录可能短时间内触发多次。推荐方案：**利用数据库记录最近一次处理时间戳，对比 event 时间戳进行去重。**
+
+```typescript
+@BindTrigger('orderStatusChange')
+async handleOrderChange(event: TaskHandlerArgs) {
+  const eventData: DataChangeEventInput = JSON.parse(event.content.input);
+  const record = eventData.after;
+  if (!record) return;
+
+  const orderId = record.id as string;
+
+  // 查询上次处理时间，跳过短时间内的重复事件
+  const lastProcessed = await this.orderService.getLastProcessedTime(orderId);
+  if (lastProcessed && eventData.timestamp - lastProcessed < 5000) {
+    this.logger.log(`订单 ${orderId} 短时间内重复触发，跳过`);
+    return;
+  }
+
+  // 记录本次处理时间并执行业务逻辑
+  await this.orderService.updateLastProcessedTime(orderId, eventData.timestamp);
+  this.logger.log(`处理订单状态变更: ${orderId}`);
+  // do logic
+}
+```
+
+#### 场景四：用户需要自定义定时任务的触发时间
+
+平台侧的 cron 表达式在触发器创建后无法由用户动态修改。推荐方案：**平台设置一个固定的高频定时器（如每 30 分钟执行一次），在任务执行时从数据库读取用户配置的触发时间，判断当前是否命中再决定是否执行。**
+
+实现步骤：
+
+1. 平台侧创建一个每 30 分钟执行的 cron 触发器（最小粒度）
+2. 数据库中存储用户配置的期望执行时间（如 `"09:00"`、`"每周一 14:00"` 等）
+3. 前端管理页面提供时间配置界面，用户可随时修改
+4. 每次触发时，读取配置并判断当前时间是否匹配，不匹配则跳过
+
+```typescript
+@Automation()
+export class ScheduleAutomationService {
+  private readonly logger = new Logger(ScheduleAutomationService.name);
+
+  constructor(private readonly scheduleConfigService: ScheduleConfigService) {}
+
+  @BindTrigger('fixedIntervalTrigger') // 平台侧固定每 30 分钟触发
+  async checkAndExecuteTasks() {
+    // 1. 查询所有用户配置的定时任务
+    const tasks = await this.scheduleConfigService.getAllActiveTasks();
+
+    const now = new Date();
+    for (const task of tasks) {
+      // 2. 判断当前时间是否命中用户配置的执行时间
+      if (!this.isTimeMatched(now, task.scheduledTime)) {
+        continue;
+      }
+
+      // 3. 命中则执行对应业务逻辑
+      this.logger.log(`执行任务: ${task.name}, 配置时间: ${task.scheduledTime}`);
+      await this.executeTask(task);
+    }
+  }
+
+  private isTimeMatched(now: Date, scheduledTime: string): boolean {
+    // 将当前时间取到半小时精度，与用户配置的时间比较
+    // 例如 scheduledTime = "09:00"，当前 08:46~09:15 之间的某次触发即命中
+    const [hour, minute] = scheduledTime.split(':').map(Number);
+    return now.getHours() === hour && now.getMinutes() === minute;
+  }
+}
+```
 
-- **场景一：管理页面控制定时任务启停** —— 平台侧不支持通过 API 动态启停触发器；定时触发器始终保持开启，在任务执行时查询数据库中的开关状态决定是否执行。
-- **场景二：定时任务通知特定用户** —— 任务执行时无法获取用户上下文；在数据库预存目标用户 ID，执行时查询再调用飞书插件发送。
-- **场景三：记录变更触发器防抖/去重** —— 利用数据库记录最近一次处理时间戳，对比 event 时间戳进行去重。
-- **场景四：自定义定时任务触发时间** —— cron 创建后不可动态改；平台设固定高频定时器（如每 30 分钟），执行时读数据库配置判断是否命中。
+> 注意：由于平台最小调度间隔为 30 分钟，用户可配置的时间精度也应限制为 30 分钟的整数倍（如 `09:00`、`09:30`），前端做好校验提示。
 
 ## Crontab 表达式规范
 

package/steering/nestjs-react-fullstack/skills_local/plugin-guide/SKILL.md

@@ -8,6 +8,8 @@ steering-topic: plugin_guide
 match-template-name: nestjs-react-fullstack
 ---
 
+{% raw %}
+
 # Plugin 集成指南（本地开发）
 
 AI 插件集成规范，使用 lark-cli 命令管理插件包与实例，通过 capabilityClient / CapabilityService 生成调用代码。
@@ -578,3 +580,5 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 5. **禁止用 `npm install` 安装插件包** — 插件包和 npm 包是两套独立机制。
 6. **禁止 Mock** — 必须走真实插件实例调用链路。
 7. **formValue 禁止 Handlebars 控制语法** — 仅允许 `{{input.xxx}}`。
+
+{% endraw %}

package/steering/vite-react/skills/plugin-guide/SKILL.md

@@ -180,7 +180,7 @@ const structured = await (jsonExtractor as any).call('textToJson', { text: rawRe
 - **Plugin（插件）**：底层承载单元，包含插件元信息与表单定义（form.schema）。模型侧只感知插件及其表单字段，不感知插件内部实现细节。
 - **PluginInstance（插件实例配置）**：基于某个 Plugin 的表单做"业务封装"，以 **单文件 JSON** 的形式存储（每个插件实例一个文件，语义化 id）。
   - 通过 `paramsSchema` 暴露业务入参
-  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{{input.xxx}}`）
+  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{% raw %}{{input.xxx}}{% endraw %}`）
 - **PluginInstanceAIJson（pluginInstance.ai.json）**：工程转化层产物，是 pluginInstance 的**运行时投影 / 调用合同（Runtime Spec）**。
   - 包含插件定位信息、actions 入口列表、input/output schema、outputMode、readme 等
   - Code Agent 在生成**调用代码**前，必须读取它作为权威依据（使用 `capabilityClient` 调用）
@@ -224,6 +224,7 @@ Plugin 的具体内容以JSON格式给出，例如：
 
 PluginInstance 的配置以 JSON 形式输出，例如：
 
+{% raw %}
 ```json
 {
   "id": "create_feishu_group",       // 全局唯一语义化 ID
@@ -245,6 +246,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
   }
 }
 ```
+{% endraw %}
 
 **注意**paramsSchema 支持以下 4 种参数类型,需要按下面规定的格式进行填充：
 

package/steering/vite-react/skills/react-three-fiber/SKILL.md

@@ -5,6 +5,8 @@ steering: true
 steering-topic: react_three_fiber
 ---
 
+{% raw %}
+
 # React Three Fiber (R3F) 编码指南
 
 实现 3D 场景 / 3D 游戏 / 3D 数据可视化时, MUST 用 **react-three-fiber + drei** 声明式栈, 严禁用 React + CSS / SVG / `transform: rotateX` 伪 3D.
@@ -220,3 +222,5 @@ npm install react-error-boundary        # 必装! Canvas 外包 ErrorBoundary
 
 - `client-coding-guide` - vite-react 通用编码规范
 - `component-conventions` - React 组件命名 / 文件结构
+
+{% endraw %}