@lark-apaas/coding-steering 0.1.32-beta.0 → 0.1.32-dev.1b5c337

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/tool-authoring.md

@@ -0,0 +1,197 @@
+# 工具类写法
+
+API 形状以 `node_modules/@lark-apaas/nestjs-mcp/dist/index.d.ts` 为准。下面是当前版本的写法与约束；字段名对不上时以 d.ts 为准。
+
+## 骨架
+
+```typescript
+// server/mcp/tools/order.tools.ts
+import { z } from 'zod';
+import {
+  McpTools,
+  McpTool,
+  McpToolError,
+  type Infer,
+  type McpContext,
+  type McpToolResult,
+} from '@lark-apaas/fullstack-nestjs-core';
+import { OrderService } from '@server/modules/order/order.service';
+
+// schema 提成常量：方法签名用 Infer<typeof …> 引用，清单导出也从这里取
+export const SearchOrdersInput = {
+  keyword: z.string().optional().describe('客户名关键字，模糊匹配'),
+  limit: z.number().int().min(1).max(50).default(20).describe('单页条数'),
+  cursor: z.string().optional().describe('上一页返回的 nextCursor；首页不传'),
+};
+export const SearchOrdersOutput = {
+  items: z.array(
+    z.object({
+      id: z.string(),
+      customer: z.string(),
+      amount: z.number().describe('金额，单位元'),
+      status: z.enum(['pending', 'paid', 'cancelled']),
+    }),
+  ),
+  nextCursor: z.string().nullable().describe('还有下一页时非空，原样传回 cursor'),
+};
+
+export const CancelOrderInput = { orderId: z.string().describe('订单 ID，来自 order_search 的 items[].id') };
+export const CancelOrderOutput = { orderId: z.string(), status: z.literal('cancelled') };
+
+@McpTools({ prefix: 'order_' })
+export class OrderMcpTools {
+  constructor(private readonly orders: OrderService) {}
+
+  @McpTool({
+    title: '查询订单',
+    description:
+      '按客户名关键字分页查询当前用户可见的订单。用户想找订单、看订单列表时调用；一页最多 50 条，超出用 cursor 翻页。',
+    inputSchema: SearchOrdersInput,
+    outputSchema: SearchOrdersOutput,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  })
+  async search(
+    input: Infer<typeof SearchOrdersInput>,
+    ctx: McpContext,
+  ): Promise<McpToolResult<typeof SearchOrdersOutput>> {
+    const userId = ctx.user.userId!; // requireUser 默认开启，执行到这里必有值；取一次往下传
+    const page = await this.orders.search({ ...input, userId });
+    return {
+      structuredContent: page,
+      content: [{ type: 'text', text: `找到 ${page.items.length} 条订单` }],
+    };
+  }
+
+  @McpTool({
+    title: '取消订单',
+    description:
+      '取消一个待支付订单。仅在用户明确要求取消、且订单状态为 pending 时调用；订单不存在返回 ORDER_NOT_FOUND，状态不允许返回 ORDER_NOT_CANCELLABLE。重复取消同一订单返回同一结果。',
+    inputSchema: CancelOrderInput,
+    outputSchema: CancelOrderOutput,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  })
+  async cancel(
+    input: Infer<typeof CancelOrderInput>,
+    ctx: McpContext,
+  ): Promise<McpToolResult<typeof CancelOrderOutput>> {
+    const userId = ctx.user.userId!;
+    const order = await this.orders.findVisibleTo(input.orderId, userId);
+    if (!order) throw new McpToolError('订单不存在', { code: 'ORDER_NOT_FOUND' });
+    if (order.status === 'cancelled') return { structuredContent: { orderId: order.id, status: 'cancelled' } };
+    if (order.status !== 'pending') {
+      throw new McpToolError(`订单状态为 ${order.status}，不能取消`, { code: 'ORDER_NOT_CANCELLABLE' });
+    }
+    await this.orders.cancel(order.id, userId);
+    return { structuredContent: { orderId: order.id, status: 'cancelled' } };
+  }
+}
+```
+
+```typescript
+// server/modules/order/order.module.ts —— 工具类和它依赖的 Service 注册在同一个模块
+import { Module } from '@nestjs/common';
+// OrderController / OrderService / OrderMcpTools 的 import 略
+
+@Module({
+  controllers: [OrderController],
+  providers: [OrderService, OrderMcpTools],
+})
+export class OrderModule {}
+```
+
+`@McpTools()` 自带 `@Injectable()`。SDK 启动时用 DiscoveryService 扫所有 provider；类没进任何模块的 `providers` 就扫不到它，启动日志不会有任何提示，工具静默缺席——启动日志「已注册 N 个 MCP 工具：…」列出的名字才是真相，对不上就是没注册。工具类及其依赖必须是单例：request / transient 作用域会在启动时抛「MCP 工具必须使用单例及单例依赖」，整个应用起不来。
+
+## 装饰器选项
+
+`@McpTool(options)`：
+
+| 字段 | 说明 |
+|---|---|
+| `name?` | 默认取方法名；最终工具名 = `prefix + name`，需匹配 `^[A-Za-z0-9_.-]{1,128}$`，全应用唯一 |
+| `title?` | 面向人的展示名，面板里显示 |
+| `description` | 必填，面向模型 |
+| `inputSchema?` / `outputSchema?` | zod：原始形状 `{ a: z.string() }` 或 `z.object({...})` 都行；顶层必须是对象 |
+| `annotations?` | `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`，四项都写 |
+| `ui?` | `{ resourceUri: 'ui://…', visibility?: ['model' \| 'app'] }`，见 `mcp-apps.md` |
+| `meta?` | 额外 `_meta`，与 `ui` 生成的字段合并 |
+
+`@McpTools({ prefix? })`：给类下所有工具名加前缀，如 `order_`。
+
+## 方法签名与返回值
+
+- 固定 `(input, ctx)`。无入参的工具 `input` 为 `Record<string, never>`，仍要写第二个参数 `ctx`。
+- 声明了 `outputSchema`：返回 `{ structuredContent }`，类型由 schema 推导；`content` 可选，SDK 会自动补一份 JSON 文本给不支持结构化输出的客户端。加一句业务摘要的 `content` 让文本客户端也能读。
+- 未声明 `outputSchema`：返回 `{ content: [{ type: 'text', text }] }`；`content` 还支持 `image` / `audio` / `resource_link` 块。
+- `isError: true` 由 SDK 在捕获 `McpToolError` 时设置，不需要手动返回。
+
+## McpContext
+
+| 字段 | 用途 |
+|---|---|
+| `user` | 与 REST 里的 `req.userContext` 同源：`userId` / `tenantId` / `roles` / `env`（`preview` \| `runtime`）等，字段全部可选（`userId?: string`）。默认 `requireUser: true`，缺 `userId` 时 SDK 直接返回 `MCP_USER_REQUIRED`、方法不执行，所以方法体开头 `const userId = ctx.user.userId!;` 取一次往下传；不要为迁就类型去改 Service 签名 |
+| `request` | 原始 HTTP 请求，读 header、logid |
+| `signal` | 客户端取消时触发，长任务把它传给下游 |
+| `requestId` | MCP 请求 id |
+| `extra` | SDK 的 `RequestHandlerExtra`（`sessionId` / `requestId` / `authInfo` 等）。它有 `sendNotification`，但端点是无状态 JSON 模式，`notifications/progress` 发不到客户端——长任务别靠进度通知续命，拆成「发起 + 查状态」两个工具 |
+
+## 错误处理
+
+- 可预期的业务失败抛 `new McpToolError(message, { code?, data? })`：SDK 转成 `isError: true`，`message` / `code` / `data` 原样进 Agent 上下文。`code` 用 `SCREAMING_SNAKE`，并在 `description` 里预告，Agent 才知道怎么应对。
+- 其他异常：SDK 记日志、返回通用失败提示，Agent 看不到原因。调试时看到「通用失败提示」就去读 Trace-ID 日志。
+- 入参校验交给 zod，方法体不重复判空；zod 失败由 SDK 返回，方法不执行。
+
+## description 怎么写
+
+消费方 Agent 只靠 `description` 与字段 `.describe()` 决定调不调、怎么填。写全五件事：用途、何时调用（含前置条件）、参数从哪来（「来自 order_search 的 items[].id」）、返回什么、失败会返回哪些 code。写操作再加一句幂等语义（「重复取消返回同一结果」）。
+
+字段描述写单位、格式、取值来源；枚举用 `z.enum`；入参不用 `z.any()` / `z.unknown()`。
+
+## 开通（首次）
+
+1. 前置检查通过（见 SKILL.md）。
+2. 建 `server/mcp/tools/<域>.tools.ts`，至少一个只读工具复用现有 Service。
+3. 把工具类加进所属业务模块的 `providers`。
+4. 写 `server/mcp/SKILL.md`（下节）。
+5. `npx miaoda-mcp validate` 通过，`.spark/mcp/manifest.json` 一起提交。
+6. 进 `debugging.md` 的调试回路。
+
+## 应用 Skill：`server/mcp/SKILL.md`
+
+给消费方 Agent 的使用说明，SDK 自动注册为资源 `skill://app/SKILL.md`（`text/markdown`），每次请求重新读文件，改完不用重启；上限 1 MiB，必须是工程内的普通文件。
+
+必含：`name` / `description` frontmatter、适用场景、实际工具名与关键参数、调用顺序、需要用户确认的边界、身份与权限要求、每个错误 code 的处理、界面 URI（如有）。只写已实现的能力；不写凭证、用户数据、内部实现。
+
+```markdown
+---
+name: orders
+description: 查询当前用户可见的订单，并在用户明确要求后取消待支付订单。
+---
+# 订单能力
+- 需要已登录用户身份；只返回当前用户可见的订单。
+- 找订单：order_search，keyword 模糊匹配客户名；nextCursor 非空时用 cursor 翻页。
+- 取消订单：只有用户明确要求取消、且 status 为 pending 时调用 order_cancel；orderId 取自 order_search 的 items[].id。
+- ORDER_NOT_FOUND：请用户核对订单 ID。ORDER_NOT_CANCELLABLE：告知当前状态，不重试。
+- 支持界面的宿主会用 ui://order/list 展示查询结果。
+```
+
+## 校验与清单
+
+- `npx miaoda-mcp validate`：用工程自身 TypeScript 加载 `server/mcp` 源码（不启动应用），检查工具名格式、重名、`ui://` 前缀、`ui.resourceUri` 引用，写入 `.spark/mcp/manifest.json`。
+- `npx miaoda-mcp validate --check`：只比对不写入，CI 用。
+- 开发态启动应用也会写清单；生产不写。删光工具、资源与应用 Skill 后再跑一次 `validate` 清理旧清单。
+- 启动期同样的校验失败会阻断启动（「MCP 定义校验失败」），一个方法不能同时标 `@McpTool()` 与 `@McpUiResource()`。
+
+## 模块配置（一般不动）
+
+```typescript
+PlatformModule.forRoot({
+  mcp: {
+    serverName: 'my-app',   // 默认 SUDA_APP_ID，再缺省为 miaoda-app
+    serverVersion: '1.0.0',
+    instructions: '…',      // initialize 响应里的说明
+  },
+});
+// 关闭端点：PlatformModule.forRoot({ mcp: false })
+```
+
+`requireUser` 保持默认 `true`。零工具、零资源、无应用 Skill 时端点返回 404，这是正常状态不是故障。

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 %}