@lark-apaas/coding-steering 0.1.6-alpha.9 → 0.1.6-beta.0

package/steering/nestjs-react-fullstack/skills/feishu/references/calendar.md

@@ -1,6 +1,6 @@
 # 日历与会议室 (Calendar)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/calendar-v4/overview.md
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/calendar-v4/overview.md>
 
 使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理日程、预约会议室和查询忙闲状态。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/contacts.md

@@ -1,6 +1,6 @@
 # 通讯录 (Contacts)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/contact-v3/resources.md
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/contact-v3/resources.md>
 
 使用 `@larksuiteoapi/node-sdk` 在 NestJS 中查询飞书通讯录用户和部门信息。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/doc.md

@@ -1,6 +1,7 @@
 # 云文档 (Document)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/docs-overview
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/docs/docs-overview>
+.md
 
 使用 `@larksuiteoapi/node-sdk` 在 NestJS 中操作飞书云文档。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/drive.md

@@ -1,6 +1,7 @@
 # 云空间 (Drive)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/drive-v1/introduction
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/docs/drive-v1/introduction>
+.md
 
 使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理飞书云空间文件和文件夹。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/events.md

@@ -1,6 +1,7 @@
 # 事件订阅 (Events)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/event-subscription-guide/overview
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/event-subscription-guide/overview>
+.md
 
 通过 WebSocket 长连接接收飞书事件推送，无需公网 IP / 域名，无需加解密。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/id-convert.md

@@ -1,8 +1,8 @@
 # 妙搭与飞书开放平台 — ID 识别与转换
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/spark-v1/overview.md
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/spark-v1/overview.md>
 >
-> 飞书用户身份体系官方说明：https://open.larkoffice.com/document/platform-overveiw/basic-concepts/user-identity-introduction/introduction
+> 飞书用户身份体系官方说明：<https://open.larkoffice.com/document/platform-overveiw/basic-concepts/user-identity-introduction/introduction>
 >
 > **承接 `user-identity` skill 决策树**：如果只需 妙搭 userId → 飞书 user_id（employee_id），在 nestjs-react-fullstack 项目内优先用 `AuthNPaasService`。本文覆盖 `AuthNPaasService` 不支持的场景：需要 `open_id` / `union_id`、或需要任何方向的反查、或不在该模板内的项目。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/messaging.md

@@ -1,6 +1,6 @@
 # 消息 (Messaging)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/im-v1/introduction.md
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/im-v1/introduction.md>
 
 使用 `@larksuiteoapi/node-sdk` 在 NestJS 中发送和回复飞书消息。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/oauth.md

@@ -1,6 +1,7 @@
 # OAuth 用户授权
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM>
+.md
 
 默认的 tenant_access_token 以应用身份调用 API。
 部分场景（个人日历、搜索联系人）需要 user_access_token 代表用户操作。

package/steering/nestjs-react-fullstack/skills/feishu/references/perm.md

@@ -1,6 +1,7 @@
 # 权限管理 (Permission)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/permission/overview
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/docs/permission/overview>
+.md
 
 使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理飞书云文档的协作者权限。
 

package/steering/nestjs-react-fullstack/skills/feishu/references/wiki.md

@@ -1,6 +1,7 @@
 # 知识库 (Wiki)
 
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/wiki-v2/wiki-overview
+> 开放平台文档（Markdown 版）：<https://open.larkoffice.com/document/server-docs/docs/wiki-v2/wiki-overview>
+.md
 
 使用 `@larksuiteoapi/node-sdk` 在 NestJS 中操作飞书知识库。
 
@@ -151,7 +152,7 @@ Wiki API 不提供搜索功能。获取内容需通过以下方式：
 
 1. 打开知识空间 → 设置 → 成员管理
 2. 添加机器人应用
-3. 参考：https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa
+3. 参考：<https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa>
 
 ## Common Mistakes
 

package/steering/nestjs-react-fullstack/skills/openapi-guide/SKILL.md

@@ -72,6 +72,7 @@ modules/orders/
 ```
 
 在 `orders.module.ts` 中注册：
+
 ```typescript
 @Module({
   controllers: [OrdersController, OpenApiOrdersController],

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

@@ -134,17 +134,20 @@ const structured = await capabilityClient
 ```
 
 > **Client 侧提示**：`capabilityClient` 支持直接传 File/Blob 对象作为文件参数，无需先上传到 dataloom 获取 URL：
+>
 > ```typescript
 > // Client 侧：直接传 File 对象，SDK 自动处理上传
 > const rawResult = await capabilityClient
 >   .load('doc_parser_instance')
 >   .call('parseDocToMarkdown', { fileUrl: [file] }); // file 为 File/Blob 对象
 > ```
+>
 > ⚠️ 仅 `capabilityClient`（Client 侧）支持此能力，Server 侧 `CapabilityService` 仅支持 URL 字符串。
 
 ### 创建结构化提取 PluginInstance 的关键要求
 
 创建 `ai-text-to-json` 或 `ai-image-to-json` 类型的 PluginInstance 时：
+
 1. **必须一次性定义所有需要提取的字段**（参考数据库 schema / 表单定义 / UI 设计），宁多勿漏
 2. 字段类型仅支持 String / Number / Boolean，最多 20 个字段
 3. 先调用 `get_plugin_ai_json` 确认上游插件的 `outputSchema`，确保输入格式正确
@@ -190,6 +193,7 @@ const structured = await capabilityClient
 2. **明确报错**：plugin 未配置/未就绪时直接 `toast.error('未配置飞书多维表格，请前往设置页配置')` + 跳转配置页，**不**编一个假的"同步成功"
 
 ## 核心概念
+
 新版链路中，**Plugin（插件）**、**PluginInstance（插件实例配置）**、**PluginInstanceAIJson（运行时投影：pluginInstance.ai.json）** 的关系如下：
 
 - **Plugin（插件）**：底层承载单元，包含插件元信息与表单定义（form.schema）。模型侧只感知插件及其表单字段，不感知插件内部实现细节。
@@ -201,9 +205,10 @@ const structured = await capabilityClient
   - Code Agent 在生成**调用代码**前，必须读取它作为权威依据（Server 侧用 `CapabilityService`，Client 侧用 `capabilityClient`）
 
 ### 插件 Plugin
+
 插件是插件实例的承载单元，包含：
-	•	插件元信息（tags/name/description/version/...）
-	•	插件表单定义（form.schema），用于描述"这个插件需要哪些表单字段"。
+ • 插件元信息（tags/name/description/version/...）
+ • 插件表单定义（form.schema），用于描述"这个插件需要哪些表单字段"。
 重要：模型侧只感知插件与其表单 schema，不感知插件内部实现（如 Action的实现、API 细节等）。
 
 Plugin 的具体内容以JSON格式给出，例如：
@@ -227,17 +232,19 @@ Plugin 的具体内容以JSON格式给出，例如：
 ```
 
 ### 插件实例 PluginInstance
+
 开发框架内置 `plugin` 工具，用于创建和管理基于 **Plugin（插件表单）** 的业务插件实例（PluginInstance）。
 
 **重要说明**：
+
 - PluginInstance 的配置以"单文件 JSON"形式存储在 `server/capabilities/`（每个插件实例一个文件，逻辑上对应 server/capabilities/<id>.json）。
 - 运行时调用前，Code Agent 需要通过 get_plugin_ai_json 获取对应插件实例的 pluginInstance.ai.json，再基于其中的 actions/schema/outputMode 生成调用代码。
 - 运行时调用入口统一走 SDK/Service：
-	- Server 侧：CapabilityService.load(pluginInstanceId).call(actionKey, input)
-	- Client 侧：capabilityClient.load(pluginInstanceId).call(actionKey, input)（流式用 callStream）
-
+  - Server 侧：CapabilityService.load(pluginInstanceId).call(actionKey, input)
+  - Client 侧：capabilityClient.load(pluginInstanceId).call(actionKey, input)（流式用 callStream）
 
 PluginInstance 的配置以 JSON 形式输出，例如：
+
 ```json
 {
   "id": "create_feishu_group",       // 全局唯一语义化 ID
@@ -263,6 +270,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
 **注意**paramsSchema 支持以下 4 种参数类型,需要按下面规定的格式进行填充：
 
 1. **文本** - 单行或多行文本输入
+
    ```json
    {
      "type": "string",
@@ -271,6 +279,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
    ```
 
 2. **数组** - 字符串数组（如 ID 列表、标签列表等）
+
    ```json
    {
      "type": "array",
@@ -283,6 +292,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
    ```
 
 3. **图片** - 图片资源（需指定 format 为 picture）
+
    ```json
    {
      "type": "string",
@@ -292,6 +302,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
    ```
 
 4. **文件** - 文件资源（需指定 format 为 file）
+
    ```json
    {
      "type": "string",
@@ -301,17 +312,20 @@ PluginInstance 的配置以 JSON 形式输出，例如：
    ```
 
 > **注意**：`format` 为 `file`、`picture` 或 `plugin-file-url` 的字段在 Client 侧调用时均支持直接传入 File/Blob 对象，`capabilityClient` SDK 会自动处理上传；Server 侧 `CapabilityService` 仅支持 URL 字符串。**禁止**Client 侧先通过 dataloom 上传文件拿 URL 再传给插件——dataloom 的 `download_url` 是内部存储路径，插件服务端可能无法访问。
+>
 #### PluginInstanceAIJson（运行时投影 / 工程转化层产物：pluginInstance.ai.json）
+
 pluginInstance.ai.json 是从 PluginInstance 配置派生出的运行时插件实例说明（Runtime Spec），用于 Code Agent 动态生成调用代码。
 它包含：
-	•	插件实例元数据（id/pluginKey/pluginVersion/name/description）
-	•	可执行入口列表 actions[]（每个入口包含 key/inputSchema/outputSchema/outputMode）
-	•	详细说明 readme
-	•	type：单入口/多入口（single_action | multi_action）
+ • 插件实例元数据（id/pluginKey/pluginVersion/name/description）
+ • 可执行入口列表 actions[]（每个入口包含 key/inputSchema/outputSchema/outputMode）
+ • 详细说明 readme
+ • type：单入口/多入口（single_action | multi_action）
 
 **重要**：模型不能自行猜测某个插件实例有哪些 action、入参/出参结构；在生成调用代码前必须通过工具读取该 pluginInstance.ai.json。
 
 PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
+
   ```json
 {
   "type": "multi_action", // 插件实例类型：single_action 表示仅 1 个 action；multi_action 表示多个 action（调用前需选择 actionKey）
@@ -347,17 +361,21 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
   ```
 
 ## 可用的 Plugin
+
 ```
 {{available_plugins}}
 ```
+
 说明：先从可用的 PluginInstance 进行选择，如果无法满足需求，看可用的 Plugin，如果有满足的插件，调用插件生成工具进行生成，如果没有，直接拒答。
 
 ## 可用的 PluginInstance
+
 ```
 {{available_plugin_instances}}
 ```
 
 ### 使用方式
+
 1. **创建/修改 PluginInstance（配置层）**：调用 `plugin_instance` 工具生成/更新单文件 PluginInstance JSON（基于插件表单封装）。
 2. **查询已有 PluginInstance（配置层）**：优先使用可用的 PluginInstance；如仍需核对细节，再读取对应插件实例配置(调用'get_plugin_ai_json')。
 3. **生成运行时代码（调用层）**：
@@ -366,17 +384,19 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
    - 仔细阅读返回的 readme，必须严格遵循里面制定的规则
 
 ### 典型场景示例
+
 - **消息通知类**：封装"发送飞书消息"相关插件为业务插件实例
 - **群组管理类**：封装"创建飞书群组"相关插件为业务插件实例
 - **AI 生成类**：封装"AI 生文/生图/图片理解"相关插件为业务插件实例
 
 ### 使用限制
+
 - PluginInstance 必须通过 `plugin_instance` 工具创建/更新，不支持 agent 直接手改 `server/capabilities/` 下的配置文件
 - 调用前必须通过 `get_plugin_ai_json` 获取权威 schema，禁止猜测入参/出参结构
 - PluginInstance 配置信息存储在 `server/capabilities/` 目录
 - 运行时调用统一走  SDK/Service，不再为每个插件实例预生成固定的 call 文件
-  -  Server 侧：CapabilityService.load(capabilityId).call(actionKey, input)
-  -	Client 侧：capabilityClient.load(capabilityId).call(actionKey, input)（流式用 callStream）
+  - Server 侧：CapabilityService.load(capabilityId).call(actionKey, input)
+  - Client 侧：capabilityClient.load(capabilityId).call(actionKey, input)（流式用 callStream）
 
 ## PluginInstance 生成约束
 
@@ -441,11 +461,7 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
 ### 第一步：检查现有 PluginInstance（复用优先）
 
 1) 用户描述需求后，优先基于上下文提供的插件实例列表检索是否已存在可复用插件实例。  
-2) 若存在候选插件实例但你无法确认其是否满足需求，必须调用 `get_plugin_ai_json` 获取该插件实例的运行时投影（pluginInstance.ai.json），根据其中的：
-- `actions[].key`
-- `actions[].inputSchema / outputSchema`
-- `actions[].outputMode`
-来判断是否可复用以及如何调用。  
+2) 若存在候选插件实例但你无法确认其是否满足需求，必须调用 `get_plugin_ai_json` 获取该插件实例的运行时投影（pluginInstance.ai.json），根据其中的 `actions[].key`、`actions[].inputSchema / outputSchema`、`actions[].outputMode` 判断是否可复用以及如何调用。
 3) 禁止按旧链路去读取/维护 `server/capabilities/capabilities.json` 来做复用判断。
 
 > 结论：**复用判断以插件实例列表 + get_plugin_ai_json 为准**，禁止猜测 action、入参/出参、输出模式。
@@ -459,8 +475,9 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
   - 其他情况：告知用户该需求目前无法满足
 
 **强制约束**：
+
 - 创建/更新 PluginInstance **必须**通过 `plugin_instance` 工具完成，绝对禁止直接修改 `server/capabilities/` 下的配置文件。
-- UPDATE 场景严禁修改保护字段：`id / pluginKey / pluginVersion / createdAt `。
+- UPDATE 场景严禁修改保护字段：`id / pluginKey / pluginVersion / createdAt`。
 
 ### 第三步：生成调用代码
 
@@ -524,6 +541,7 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
 用户会用「AI 生文」「AI 生图」「发送飞书消息」等**业务语言**描述需求；这些关键词必须被识别为**待使用或待创建的 PluginInstance**。
 
 开发流程：
+
 1. 收到需求后，先看可用的 PluginInstance 是否有可以直接使用的插件实例
 2. 若有候选但不确定是否满足，调用 `get_plugin_ai_json` 查看其 actions/schema/outputMode 再决策
 3. 若无，立即调用 `plugin_instance` 工具新建
@@ -577,6 +595,7 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
 > **关键区分**：`formValue` 中配置固定值 ≠ 代码中硬编码。`formValue` 是插件实例的声明式配置，修改不需要改代码；而代码中硬编码的值散落在业务逻辑中，难以维护。
 
 当接收人/配置值是动态的，获取途径：
+
 1. 通过平台角色 API 获取（如"所有 admin_hr 角色的用户"）
 2. 存入应用配置表，通过 API 读取
 3. 通过环境变量注入

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

@@ -58,7 +58,9 @@
 ### Client 侧调用方式（默认首选）
 
 #### 1. 调用前获取权威依据
+
 在为某个插件实例生成调用代码前，必须先通过 `get_plugin_ai_json` 工具获取该插件实例的运行时投影（plugin_Instance.ai.json），并以其中信息为准：
+
 - `actions[].key`：调用时要传的 `actionKey`
 - `actions[].inputSchema / outputSchema`：入参/出参结构
 - `actions[].outputMode`：`unary | stream`（决定调用与结果处理方式）
@@ -175,7 +177,7 @@ function readFirstStringField(
 
 **核心原则**：在插件设计阶段按「原子化拆解」拆分，避免单插件返回多字段 JSON。
 
-#####  推荐：多插件并行流式
+##### 推荐：多插件并行流式
 
 适用于需求涉及多种输出（标题、正文、图片等），各输出相对独立。
 
@@ -350,6 +352,7 @@ this.somePluginInstanceSideEffect(input).catch(error => {
 | 任意（兜底场景） | Server 侧 | `capabilityService.load(id).call(actionKey, input)` |
 
 **选择原则**：
+
 - 不涉及持久化时，优先在 Client 侧直接调用
 - `outputMode = stream` 时，Client 侧使用 `callStream` 做渐进式渲染
 - 涉及持久化、触发器、敏感凭证、事务编排等场景时，使用 Server 侧

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

@@ -12,8 +12,8 @@
 
 在查看本插件的 Action 时，你将同时获得两部分信息：
 
-1.  **本文档 (README)**: 提供高级指引、业务逻辑、使用场景、重要约束。
-2.  **Action 的 `inputSchema` 和 `outputSchema`**: 提供精确的 JSON Schema 格式的输入/输出结构。
+1. **本文档 (README)**: 提供高级指引、业务逻辑、使用场景、重要约束。
+2. **Action 的 `inputSchema` 和 `outputSchema`**: 提供精确的 JSON Schema 格式的输入/输出结构。
 
 **请遵循以下原则：**
 
@@ -464,6 +464,7 @@ const columns = [
 **2. Formula 字段不支持 filter 和 sum/avg 聚合**
 
 同一数据常有两个字段：原始 Number 字段（如 `金额`，单位元）和计算 Formula 字段（如 `金额(万元)`）。聚合和过滤**必须用 Number 字段**，在代码里做单位转换：
+
 ```typescript
 // ❌ 错误：金额(万元) 是 Formula，不能聚合也不能过滤
 { fieldName: '金额(万元)', aggregation: 'sum' }
@@ -479,6 +480,7 @@ const columns = [
 与 searchRecords 不同，aggregateQuery 中 `isNot` 会把字段值为空的记录也排除。如果很多记录的该字段为空，结果会远少于预期甚至为 0。
 
 解决方案：不在 filter 里用 `isNot` 排除 Text 值，改为在 dimensions 里加上该字段，在结果侧用 if 跳过不要的分组：
+
 ```typescript
 // ❌ 错误：isNot 会把「目前进展」为空的记录也排掉
 filter: { conditions: [{ fieldName: '目前进展', operator: 'isNot', value: ['已完成'] }] }

package/steering/nestjs-react-fullstack/skills/react-hook-best-practices/SKILL.md

@@ -10,10 +10,10 @@ match-template-name: nestjs-react-fullstack
 
 ## ⚡️ 核心原则 (TL;DR)
 
-1.  **优先 React 19 新特性**: 用 `use()` 读取异步数据，用 `useActionState` 管理表单，替代繁琐的 `useEffect` + `useState`。
-2.  **拒绝冗余 State**: 能计算得到的变量（派生状态），绝不存入 State，直接计算 or `useMemo`。
-3.  **事件驱动 > Effects**: 用户交互（点击、提交）产生的逻辑写在事件处理函数中，`useEffect` 仅用于同步外部系统（订阅、DOM）。
-4.  **依赖诚实**: `useEffect/useCallback/useMemo` 的依赖数组必须包含所有引用的响应式变量，禁止欺骗 Linter。
+1. **优先 React 19 新特性**: 用 `use()` 读取异步数据，用 `useActionState` 管理表单，替代繁琐的 `useEffect` + `useState`。
+2. **拒绝冗余 State**: 能计算得到的变量（派生状态），绝不存入 State，直接计算 or `useMemo`。
+3. **事件驱动 > Effects**: 用户交互（点击、提交）产生的逻辑写在事件处理函数中，`useEffect` 仅用于同步外部系统（订阅、DOM）。
+4. **依赖诚实**: `useEffect/useCallback/useMemo` 的依赖数组必须包含所有引用的响应式变量，禁止欺骗 Linter。
 
 ---
 

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

@@ -86,6 +86,7 @@ interface WebhookEvent {
 ```
 
 ### 指定值限制
+
 1. Webhook 触发器不可以设置指定值，并且告知用户。
 
 ### 代码示例

package/steering/nestjs-react-fullstack/skills/user-identity/SKILL.md

@@ -208,6 +208,7 @@ const UserInfoPanel = () => {
 ```
 
 **注意**：
+
 - `lark_user_id` 通过额外异步请求获取，可能晚于 `user_id` 等基础字段就绪
 - 请求失败或用户无对应飞书账号时值为 `undefined`，**必须用条件渲染**
 - `useCurrentUserProfile()` 的返回值里**不存在** `open_id`、`feishu_id`、`openId` 字段——在这个 Hook 的消费代码里飞书 ID 唯一字段名是 `lark_user_id`（仅约束本 Hook；项目其他场景调 spark `id_convert` / 通讯录 API 出现 `open_id` 是正常的）

package/steering/nestjs-react-fullstack/skills_local/code-fix/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: code-fix
-description: Use when encountering code errors such as import failures, TypeScript/Dto type mismatches, JSX syntax issues, API call exceptions (traceid troubleshooting), production log troubleshooting that should route through miaoda-cli, route 404 errors, or **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, traceid, 线上日志, 线上日志查询, 查询线上日志, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, "请修复错误" 通用排错
-steering: true
-steering-topic: code_fix
-match-template-name: nestjs-react-fullstack
+description: Use when encountering code errors such as import failures, TypeScript/Dto type mismatches, JSX syntax issues, API call exceptions, route 404 errors, PostgresError connection verification failed, or **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, "请修复错误" 通用排错, please re-obtain a valid database connection
 ---
 
 
@@ -70,7 +67,7 @@ import { ListPlus, Cake, Home, Building, Twitter } from "lucide-react";
 
 1. **不确定就查**：图标名不在你已知列表里 → 先 `Read packages/client/lucide-react/iconMappings.json`（或 lucide-react 包的 d.ts 导出列表）确认存在，再写 import
 2. **替换图标必须连同 import 列表一起检查**：把旧图标替换成新图标时，**必须先 grep 当前文件 import 列表**确认新名未已 import，避免触发 LSP "标识符重复" / `no-redeclare`
-3. **LSP 警告是硬约束**：multi_edit / 写代码后看到 LSP 任意 "Cannot find name" / "标识符重复" → **必须先修完警告才能 commit**，禁止带 LSP 错误跑 `commit_task`
+3. **LSP 警告是硬约束**：写代码后看到 LSP 任意 "Cannot find name" / "标识符重复" → **必须先修完警告才能 commit**，禁止带 LSP 错误提交
 
 ### 同名 export 重复（修复 SOP）
 
@@ -82,30 +79,38 @@ import { ListPlus, Cake, Home, Building, Twitter } from "lucide-react";
 2. 预防规则（跨子组件常量前缀化、行内/桶导出二选一）见 `coding-guide` 的「TypeScript 规范 · 命名约定」与「文件命名约定 · 导入导出」
 
 ### 前端 Dto 类型使用错误
+
 **问题描述**：代码中使用的 Dto 类型属性与实际定义不一致，导致 TypeScript 类型检查报错
 
 **核心原则**：遇到类型错误，先查 `@client/src/api/gen/types.gen.ts` 确认定义，再修改代码
 
 **错误示例**：
+
 - 示例1： 赋值时缺失必需属性
+
 ```
 Property 'dueDate' is missing in type {...} but required in type 'CreateBorrowRecordDto'
 ```
 
 - 示例2：访问不存在的属性
+
 ```
 Property 'avatar' does not exist on type 'LotteryParticipantResponseDto'
 ```
 
 - 示例3：导入不存在的类型
+
 ```
 Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponseDto'
 ```
+
 **解决步骤**：
+
 1. 在 `@client/src/api/gen/types.gen.ts` 中搜索目标Dto实际定义
 2. 确认类型名称是否正确，明确完整定义
 
 **检查清单**：
+
 - [ ] 已查看 `@client/src/api/gen/types.gen.ts` 中的类型定义
 - [ ] 已对比代码使用与实际定义的差异
 - [ ] 已根据实际定义修正代码
@@ -156,22 +161,11 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 
 ## 调用生成的 API 异常
 
-### 需要查询线上日志时使用 miaoda-cli
-
-**适用场景**：仅当用户提供 traceid、logid、线上报错、发布错误日志、线上运行日志、线上链路追踪，或排查必须依赖线上前端/后端日志。
+### 查看本地运行日志
 
-**处理要求**：引导并使用 `miaoda-cli` skill 查询线上日志。优先通过 `miaoda observability log/trace` 查询线上运行日志与链路追踪；排查发布错误时使用 `miaoda deploy error-log`。本地开发日志、构建日志、测试日志、浏览器控制台日志不在此范围内，按当前技能或对应工具排查。拿到线上日志后再回到本技能继续定位与修复代码问题。
+**适用场景**：本地开发期 API 调用异常、控制台报错、后端进程行为异常。
 
-### 用户提供了 traceid，排查错误
-
-**解决方案**：使用 `miaoda-cli` skill 读取线上前端与后端日志，获取详细错误
-
-**排查示例**：
-
-用户输入：8ae6724e-277e-4d51-afbf-b524b654f27f 看看这个 trace 为什么报错了
-排查路径：
-1. 使用 `miaoda-cli` skill 查询线上服务端与 trace 日志
-2. 根据服务端日志中对应的日志内容修复对应代码逻辑
+**处理要求**：本地日志由 `scripts/dev.js` 落到 `logs/` 目录(`dev.log`、`server.log` 及对应的 `.std.log`),直接 `cat` / `tail -F` 查看;浏览器侧错误看 DevTools Console。本地版**不接管线上日志/traceid 排查链路**(那条路径由发布平台和 oncall 工具承接)。
 
 ### 调用 API 客户端时后端返回异常
 
@@ -195,25 +189,45 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 错误信息：服务内部错误
 错误堆栈（可选）：Error: 这是测试异常：HelloController.getConfig方法故意抛出的错误\n    at HelloController.getConfig (/home/gem/workspace/dist/server/modules/hello/hello.controller.js:17:15)\n    at /home/gem/workspace/node_modules/@nestjs/core/router/router-execution-context.js:38:29\n    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
 
-2. 如果错误堆栈存在，优先按照错误堆栈中的相关文件与行列号找到对应文件，读取内容并启发式分析
-3. 如果错误堆栈不存在，按照请求的 URL 找到对应的 controller，检查其中的逻辑，启发式的分析依赖。如发现问题可以直接处理。若仍未发现问题，可以在 controller 抛出的错误对象上增加 `message` 属性，改变 message 内容方便 debug。你可以在增加完之后让用户重新请求触发问题。
+1. 如果错误堆栈存在，优先按照错误堆栈中的相关文件与行列号找到对应文件，读取内容并启发式分析
+2. 如果错误堆栈不存在，按照请求的 URL 找到对应的 controller，检查其中的逻辑，启发式的分析依赖。如发现问题可以直接处理。若仍未发现问题，可以在 controller 抛出的错误对象上增加 `message` 属性，改变 message 内容方便 debug。你可以在增加完之后让用户重新请求触发问题。
 
 ```typescript
 try {
-	// some logic
+ // some logic
 } catch (err) {
         // 后端异常必须在后端打印日志
-	this.logger.error('...')
-   	// 后端异常同时需要抛出到前端，方便修复
-	// 构造为 http-errors compatible 的对象
-   	err.statusCode = 500;
-   	err.message = err.stack; // 抛出 stack 信息，保障有足够的错误内容透出
-   	throw err;
+ this.logger.error('...')
+    // 后端异常同时需要抛出到前端，方便修复
+ // 构造为 http-errors compatible 的对象
+    err.statusCode = 500;
+    err.message = err.stack; // 抛出 stack 信息，保障有足够的错误内容透出
+    throw err;
 }
 ```
 
 注意：优先让错误信息中包含堆栈信息，以更精确的定位错误发生位置。
 
+## 数据库连接问题
+
+### PG 连接串过期 / 失效
+
+**问题描述**：`npm run dev` 启动后，后端访问数据库时报类似如下错误（关键特征是 `connection verification failed` + `expired or invalid connection link`，endpoint 域名以实际为准）：
+
+```
+PostgresError: connection verification failed for endpoint "<pg-endpoint>": expired or invalid connection link, please re-obtain a valid database connection
+```
+
+**根因**：PG connection string 注入在 `.env.local` 中，由于安全策略，连接串 **5 天过期**。`npm run dev` 启动时只会读取一次 `.env.local`，过期后旧连接串就会触发上述报错。
+
+**修复方案**：**重新运行 `npm run dev`** 即可。启动脚本会重新拉取并注入最新的 PG connection string 到 `.env.local`，新进程读取到的就是有效连接串。不要去改后端代码或 ORM 配置。
+
+**注意**：
+
+- 不要尝试手工编辑 `.env.local` 里的 PG connection string，连接串由启动流程统一管理
+- 不要把这个错误当成业务代码 bug 去排查 controller / service / 数据库 schema
+- 重启 `npm run dev` 后若仍报同样错误，再按其它通用排查路径处理
+
 ## 路由和导航问题
 
 ### 路由 404 错误诊断