@lark-apaas/coding-steering 0.1.70 → 0.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.70",
+  "version": "0.1.72",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

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

@@ -27,6 +27,7 @@ match-template-name: nestjs-react-fullstack
 - **上传在 Agent 侧验不了**：`uploadFile` 走平台 runtime 接口，Agent 的验证入口不经平台网关，在沙箱里点上传恒 404；**用户在预览态或发布运行态访问时正常**。按本 skill 写法即为正确，不要为此改代码，也不要据此判断上传能力不可用。开发期改用接口测试打你自己写的后端接口，或复用库里已有的文件 URL。详见 coding-guide「`__runtime__` 接口在 Agent 验证入口下不可达」。
 - 上传成功后，普通 `text` / `varchar` / `JSON` 业务字段默认保存 `data.download_url`，并把它作为页面展示 / 下载 URL
 - **⚠️ 场景区分（重要）**：`dataloom.storage` 仅适用于需要持久化存储文件或获取 `download_url` 保存到数据库的场景。如果文件仅作为插件输入（传给 `capabilityClient`），**必须直接传 File/Blob 对象，禁止先走 dataloom 上传再传 URL**；插件调用（capability）不属于 dataloom，详见 plugin-guide
+- **复用已存图片作插件入参**：`ai-image-to-image` 等图片插件复用已存图片时，不要直接传 `download_url`；由后端按下一条签成临时 URL 后再传给插件，详见 plugin-guide「复用已存图片作插件入参」。
 - **Server 侧 AI capability 边界**：文件已上传并持久化后，若由后端调用 `CapabilityService` 做文档解析/图片理解，不要把前端展示用 `download_url` 当插件入参；把 `file_path` 和 `bucket_id` 传给后端，由后端 `FileService` 签成临时 http(s) URL。
 - **download_url 格式说明**：`download_url` 可能是相对路径。**禁止**拼接 `window.location.origin` 或任何运行态前缀；平台会自动解析相对路径，直接使用原始值。
 - **文件URL**：调用 `generateDownloadUrlFromFilePath` 时，`file_path` 必须来自数据库 `file_attachment` 类型字段，禁止拼接；普通业务字段已有 `download_url` 时不要调用本方法。

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

@@ -811,6 +811,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 - `justify-between/around/evenly` 必须配合 `space-x-*` 或 `gap`
 - `justify-start/end` 的水平 flex 行应加 `flex-wrap`
 - shadcn Button 不要显式控制 padding/height，用 sizes/variants API
+- `tailwind-theme.css` 里设 `position: relative` 的那组 `.hover-elevate:not(.no-default-hover-elevate)` 规则，没被 `:where()` 包住时要包上（每个选择器各包一层，如 `:where(.hover-elevate:not(.no-default-hover-elevate))`），否则 `Button`/`Badge` 上的 `absolute`/`fixed`/`sticky` 会失效。改主题文件时顺手检查；遇到按钮定位不生效也先查这里，由主 agent 修改
 - 颜色优先级：语义化 token（`bg-primary`）> 自定义 token > Tailwind 预设。禁止 `bg-[--primary]`（Tailwind 4 限制）
 - **arbitrary values 中空格用下划线**：`from-[hsl(215_60%_18%)]` 非 `from-[hsl(215 60% 18%)]`
 - `tailwind-theme.css` 自定义属性用 `hsl(H, S%, L%)` 格式（非 `23 10% 23%`）
@@ -885,7 +886,7 @@ return <h1>{data?.title || '未知标题'}</h1>;
    - **必须包含**：「无文字、无字母、无符号」明确说明
    - **禁止出现**：① 使用场景（"适合移动端"）② 功能描述（"适合/用于/作为"）③ 目标用途（"品牌展示/课程封面"）④ 观众定位（"吸引年轻人"）⑤ 预期效果（"视觉冲击力/引人注目"）⑥ 媒介格式（"移动端/印刷品"）
 3. 内置 Avatar（仅头像）— `@client/src/utils/img-resources/avatar-placeholders.ts`
-4. Picsum（临时）— `https://picsum.photos/seed/${seed}/${w}/${h}`（必须带 seed）
+4. Picsum（仅数据库图片字段在生图失败时兜底）— `https://picsum.photos/seed/${seed}/${w}/${h}`（必须带 seed）；页面配图位生图失败时按视觉方向用图形或色块替代，不用随机图
 
 ### 静态资产引用（图片/视频/字体等同理）
 

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

@@ -1,190 +1,221 @@
 ---
 name: design-guide
-description: 写第一个页面、组件或样式文件之前确定并记录视觉方向：沿用已有设计、遵循用户指定、匹配预置风格，或交给 frontend-design 自行设计。
+description: 新建应用或写第一个页面前、要改 tailwind-theme.css 或 AGENTS.md 的设计规范前必须先加载。应用视觉基线规范：首屏骨架阶段按场景定出配色、字体、圆角、阴影、字号和点睛样式，写进 AGENTS.md 和 tailwind-theme.css，并给首屏准备示例数据、设计配套页面；派发页面任务和做视觉验收时也要按它执行。用户提到风格、配色、好看、美观、改样式时也召回。触发词：视觉基线, 设计规范, 主题, 配色, 字体, 圆角, 风格, 美观, 好看, tailwind-theme
 steering: true
 steering-topic: frontend_design
 match-template-name: nestjs-react-fullstack
 control-by-feature-ab: true
-hook: SessionStart
+gate-tools:
+  - tool: write
+    when-contains:
+      path: "tailwind-theme.css"
+  - tool: multi_edit
+    when-contains:
+      path: "tailwind-theme.css"
 available-agents:
   - Code
+  - Worker
+  - Reviewer
 metadata:
   display-names:
     zh-CN: 设计指南
     en-US: Design Guide
 ---
 
-# 设计指南
+# Visual Baseline Skill
 
-写第一个页面、组件或样式文件之前，先确定应用要呈现什么样子。设计要有明确特点，并适合当前产品。
+模板主题（主色 `hsl(221 83% 53%)`、`--radius: 0.5rem`、系统字体、近乎透明的阴影）是出厂值，不是设计结果。首屏骨架阶段先按本规范定出视觉基线，写进 AGENTS.md 和 `client/src/tailwind-theme.css`，再写页面。
 
-仅修改现有应用的数据、功能或局部内容，且用户没有要求调整整体视觉时，沿用已有设计，不重新匹配风格，也不改写已有设计方向。新增页面或组件本身不代表需要换风格。
+## Guidelines
 
-需要确定新的视觉方向时，先理解产品做什么、给谁使用、最重要的任务是什么，以及用户期望的氛围和使用感受。设计元素可以来自产品相关的材料、工具、物品和常用说法。推断必须有用户需求或已知上下文作为依据，不补写用户没有表达的审美偏好。
+**定基线（首屏骨架阶段，Code 执行）**
 
-## 选择设计方向
+- 先找出这个应用服务或代表的主体（企业、学校、品牌、门店、活动、城市、球队、产品线等）。用户所在企业（环境信息里的 `The company name where the user works is '…'`）只有在应用给本企业内部用、且需求没有点名其他主体时才算；测试、占位、个人名或空值不算
+- 主体真实存在、有识别色的优先用它的识别色和标志。用户给了色值就用；否则只要有联网搜索能力，一律先搜官网或权威页面核对再定色（找 logo、按钮和导航的颜色、对外语气），自认为记得色值也要搜。多个来源不一致时以官网或官方 VI 规范为准，不在几种说法里按自己偏好挑。搜不到可靠来源才按虚构主体从场景物件取色，不凭印象编色值。出处写进基线表
+- 用户给了风格描述时以用户原话为准；业务系统里识别色只用在主色或侧栏，信息密度和状态色仍按〈应用类型〉定
+- 先写 3–5 条场景约束：谁在用、在哪看（工位长时间操作 / 投屏 / 手机）、页面的视觉主角是什么、信息密度多高。用户给了风格描述时原话照抄，后续不得偏离
+- 写一句产品定位，句式：「<谁>用它<做什么>，用起来像<产品世界里的一个具体物件或场合>，而不是又一个<平庸版本>」。反例：「一个简洁的 xx 管理系统」
+- 按〈应用类型〉定信息密度、颜色力度、字体倾向、动效和记忆点，不同类型不要套同一种力度
+- 列出这个产品世界里的 3–5 个具体物件、材质或场合（如做什么用的单据、工具、场地、行话），方向名和字体气质从这里取；没有可用识别色时，主色也从这里取
+- 物件主要用来取颜色、材质和气质，不是把它画到界面上。邮戳、票根、手写批注、贴纸这类道具式元素只用于个人工具和展示型页面
+- 业务工具挑一个最要紧的状态（通常就是视觉主角）专门设计呈现方式，如按到期天数分级的色带、超阈值数字的强调底色；其余状态用统一的标签样式
+- 给视觉方向起一个具体名字，由本应用的产品和用户推出，形式是「<产品世界里的物件或场合> + <气质>」；禁止「简洁」「现代」「大气」这类形容词，也禁止沿用本 skill 里出现过的任何名字。方向名只是给开发用的内部代号，只写在 AGENTS.md，不得出现在页面标题、品牌名、按钮、提示等任何界面文案里；产品名和页标题按用户需求起
+- 按〈视觉基线模板〉填出具体值，每一格都能直接写进代码，不需要的项填「无」。本 skill 不提供推荐色值、字体或点睛实现，Example 里的 `<…>` 都由你按场景填；填完对照〈避开默认长相〉过一遍
+- 圆角按场景取：严谨业务（法务、财务、审批）2–4px；常规后台 6–8px；创作、内容、C 端 10–14px
+- 禁止只换主色、其余保持模板默认；禁止沿用模板蓝 `hsl(221 83% 53%)` 作主色（用蓝色、或识别色接近模板蓝时，调明度或饱和度拉开差距，并与背景、字体一起成套调整）；禁止统计卡片统一配彩色圆底图标；状态色和主色同一体系，不直接用通用红黄绿蓝
+- 背景、侧栏、强调色至少有一处带着方向本身的颜色；方向是「安静」「克制」时也要有颜色，指柔和、低饱和，不是只剩黑白灰
 
-无论最终走哪条路径，往 `client/src/tailwind-theme.css` 写颜色前都先读 `references/token-mapping.md`，按其中的槽位含义落色。
+**落代码（首屏骨架阶段，Code 执行）**
 
-按以下顺序判断：
+- 基线完整写进 AGENTS.md 的设计规范一节（场景约束 + 方向名 + 模板表 + 间距档位 + 页面实现约束 + 配图清单），不能只写间距
+- 项目根目录已有 DESIGN.md 时，以它为设计规范的落点：设计规范一节写进 DESIGN.md，tailwind-theme.css 照常改；AGENTS.md 只留一行「设计规范见 DESIGN.md，改界面前先读」和「页面实现约束」小节
+- 改 `client/src/tailwind-theme.css` 的 `:root`，见 Example 1。颜色保持 `hsl(H S% L%)` 写法；业务语义色（如逾期、高风险、已完成）新增变量并追加到已有的 `@theme inline` 块，页面里用变量，禁止写死色值
+- 网络字体只走妙搭字体镜像 `https://miaoda.feishu.cn/fonts/css2`（语法同 Google Fonts css2），禁止直连 `fonts.googleapis.com`，见 Example 2
+- `client/src/index.css` 末尾加 5–10 行全局样式（等宽数字、展示标题、入场动效、悬停与过渡规则、记忆点），见 Example 3
+- antd 表格在 `client/src/index.css` 一次性写全局覆盖，跟随主题变量；禁止在每个表格外层各写一遍 `[&_.ant-table-*]`，见 Example 4
+- 图表配色从色板取 hex（charts-skill 要求 hex），不用 ECharts 默认色
 
-### 1. 遵循用户明确指定的方向
+**配图**
 
-用户点名某个预置风格时，直接采用该风格。用户要求还原或沿用某个参考设计，或已经给出足以确定整体视觉方向的配色、排版与组件形态时，按用户指定执行。
+- 配图位：展示型页面的头图和章节图、消费类应用的商品或场地图、业务系统里的实物（如设备）；业务表格、表单页不配装饰图。来源优先级、提示词和展示组件按 coding-guide「图片规范」；画风、和色板的关系、2–3 种宽高比写进基线表「配图风格」
+- 生成的图按返回的站内路径原样引用，不下载、不另存；位置和路径记进配图清单
+- 生图失败时换成按视觉方向设计的图形或色块，不用随机占位图，不留空框或灰色占位
 
-“高级一点”“有科技感”“活泼一些”“偏深色”等属于偏好线索，不是完整方案；“深色背景”“绿色主色”等局部要求需要保留，但仍应在这些要求内继续匹配预置风格或自行设计。截图、附件或产品链接只有在用户明确要求参考其视觉时，才作为视觉方向；只用于提供功能或内容时，不据此判断用户指定了风格。
+**首屏示例数据**
 
-### 2. 匹配预置风格
+- 业务系统建表后写入 3–10 条示例数据（派 CodeAct 单元执行），首页打开不能是空表或一排 0
+- 示例数据写进数据库，是真实记录，不是前端 mock；每条明确标「示例」（名称前缀或 `is_demo` 字段 + 界面标签），覆盖各种状态（含逾期、待处理等需要醒目的状态）
+- 首页默认按当前用户过滤（「我的 xx」）时，新用户无数据必然空页：默认展示全部，或空态里展示示例并给出操作引导
+- 工具类页面（输入后生成结果）初始态要有预填示例输入、一句操作说明和结果区占位
 
-用户没有给出完整方案时，不要看到某类应用就固定选择一种风格。先从下面四方面找出 2–4 个都可能合适的预置风格：
+**配套页面**
 
-1. 页面主要用途：操作、分析数据、阅读内容、填写表单或展示产品。
-2. 用户想要的感觉：冷静或亲和、克制或张扬、明亮或深色、现代或杂志感。
-3. 实际使用情况：频繁操作或沉浸浏览、内容紧凑或留白较多、主要在电脑使用或经常在窄屏使用。
-4. 产品自身特点：所属行业、常见物品、材料、目标用户和常用说法能否自然融入该风格。
+- 设置页、404、无权限页、空态、加载态、出错提示和主页面用同一套视觉，同样要设计，不能是默认白页加一行灰字
+- 空态要说清现在为什么是空的、下一步做什么，并给出操作入口
 
-索引只帮助初步选择，不表示某类应用只能使用某个风格。同一种应用通常有多个合理候选。比较候选时，先按主要界面机制缩小范围，而不是按行业名称决定：
+**派发（Code）**
 
-- 高频操作、表格和表单为主：区分标准组件化软件、冷白平面与企业蓝焦点的紧凑组件系统、温和紧凑的指标工作台、开阔的数据分析画布、绿色轻影的任务与指标面板。
-- 报告、知识和连续阅读为主：区分冷静的纸面规格文档、米白纸面与等宽台账构成的数据报告、人文研究编辑界面、杂志式纸张层次、新闻印刷结构。
-- 强视觉展示或沉浸浏览为主：区分深色技术面板、毛玻璃舞台、明暗叙事区块、粗边硬影或漫画拼贴。
-- 轻量查询、填写或个人工具：只有大留白、超大圆角、自然色和稀疏结构确实适合主要操作时，才使用对应的有机方向；需要密集表格或连续高频操作时，回到操作型候选。
+- 派发前端单元时只需写明本页的视觉主角，其余以 AGENTS.md 设计规范为准；页面有配图位时在任务里写明配图位
 
-在相邻候选之间，按下面的视觉机制完成最后比较；这些差异只解释已有索引，不改变各风格含义：
-
-- 明亮操作与数据界面：区分标准化中圆角组件与完整明暗模式、冷白浅灰平面与企业蓝焦点、暖米白细边无影、草绿浅影卡片、白色与浅蓝静区、直角蓝线编号结构和工程图纸标记。
-- 深色技术与分析界面：区分绿色终端语法、蓝黑圆角嵌套面板、紫色紧凑直角面板、红色毛玻璃舞台和明暗交替的深红叙事区块。
-- 文档与编辑界面：区分冷灰蓝规格纸、米白纸面上的衬线数字与等宽台账、人文奶油研究界面、旋转纸卡杂志层次和黑白新闻印刷结构。
-- 轻量与表达型界面：区分白底超大圆角自然留白、暖黄渐变与深浅卡片、手写纸张、黑白橙粗边硬影和高饱和漫画拼贴。
-
-采用一个风格，需要能说明需求中的哪些特征与该风格的布局密度、组件几何、主要配色关系、排版、材质、交互方式或标志性细节相呼应。清晰层级、熟悉控件、现代、专业、简洁、易用和响应式属于所有合格界面的基础质量，只用于检查可用性，不能单独作为区分预置风格的证据。一个颜色、一个形容词，或登录、保存、增删改查、统计等单个普通功能也不能单独决定风格。
-
-如果多项操作共同决定了主界面的长期结构，例如持续使用的表格与表单、筛选和批量操作、多角色工作区、审批与状态流转、排期与资源分配、看板拖拽，那么由此形成的布局密度、组件形态和交互节奏属于呈现约束，可以作为候选的正向证据；仍需比较相邻候选，不能只按企业应用类别决定。
-
-同一组中的候选如果仍只能用共同的业务用途或基础质量解释，无法用上述视觉或结构证据区分，就使用 frontend-design。否则选择差异证据最具体、同时不影响使用效率的一项；如果最初只找到一个候选，再找一个用途相近和一个感觉相近的候选进行比较，不要随机选择。
-
-选定后，完整读取对应的 `references/<风格英文名>.md`。允许根据实际内容调整信息密度、间距、尺寸和局部布局；决定风格辨识度的主要配色关系、核心材质和标志形态应保持一致。需要替换这些主要元素才能适配时，不采用该风格。
-
-### 3. 使用 frontend-design
-
-没有明确贴合的预置风格，或核实完整规格后发现需要替换主要视觉元素才能满足需求时，直接读取 `references/frontend-design.md`，按其中的方法确定产品主题、质感、配色和最有辨识度的设计元素。保留用户已经表达的局部要求和偏好。
-
-frontend-design 只需定下基础设计要素（主题、质感、配色、签名元素），不要在 `design.md` 里展开成预置风格那样的完整规格文档；具体色值、字体、组件样式变量落进主题样式文件，`design.md` 与 `AGENTS.md` 只保留精简概述。
-
-不需要为了召回而选出一个风格，也不需要逐一排除全部预置风格。
-
-## 保存设计方向
-
-命中预置风格时，用 `bash` 工具把你刚完整读取的那个风格文件**复制**成应用根目录的 `design.md`，并在首行加入受管标识 `<!-- miaoda-design-guide: managed preset=<风格英文名> -->`。不要用 `write` 逐字重写整份规格——既浪费上下文，也容易和源文件产生偏差。复制命令示例（`<刚读取的风格文件路径>` 用你实际读取的那个 references 路径替换）：
-
-```bash
-{ printf '<!-- miaoda-design-guide: managed preset=<风格英文名> -->\n'; cat "<刚读取的风格文件路径>"; } > design.md
-```
-
-覆盖前先检查现有 `design.md`：
-
-- 文件不存在时直接生成。
-- 首行是受管标识时，可以用上面的命令重新生成；切换风格时同样用新风格文件完整覆盖。
-- 首行没有受管标识时，将它视为用户文件，不覆盖；停止写入并说明冲突。
-
-frontend-design 自定义方向没有可复制的源文件，只把基础设计要素写进 `design.md`，不要展开成预置风格那样的完整规格。
-
-后续只引用项目中的 `design.md`。先确认 `design.md` 写入成功，再更新 `AGENTS.md`。
-
-需要确定新视觉方向时，在 `AGENTS.md` 中保留唯一一个简短的 `## 设计方向` 章节。已有章节时更新，不重复追加；已有多个同名章节时停止并说明冲突。根据实际情况选择一种格式：
+---
 
-```markdown
-## 设计方向
+## 视觉基线模板
 
-- 预置风格：`design.md`（<风格中文名>）
-```
+写进 AGENTS.md 时照此填写：
 
 ```markdown
-## 设计方向
-
-- 用户指定：<一句话说清用户给的方向与来源，如“用户附件设计稿：深蓝主色 + 卡片式布局”>
+## 设计规范
+
+### 场景约束
+- 产品定位：…（一句话：谁在用、什么感觉、和平庸版本差在哪）
+- 应用类型：…；判定理由：…
+- 使用者与场合：…
+- 视觉主角：…
+- 信息密度：…
+- 用户风格原话：…（没有则写「无」）
+
+### 视觉方向：<方向名>
+（方向名是内部代号，不得出现在任何界面文案里）
+| 项 | 取值 | 用途 | 出处 |
+|---|---|---|---|
+| 背景 | hsl(…) | 页面底色 | … |
+| 正文 | hsl(…) | 文字 | |
+| 主色 | hsl(…) | 主操作、选中、侧栏 | …（如「官网按钮色」「校色」「场景物件：xx」） |
+| 强调色 | hsl(…) | 少量点缀（写清用在哪几处） | … |
+| 边框 | hsl(…) | 分隔线、输入框 | |
+| 语义色 | 逾期 hsl(…) / 预警 hsl(…) / 完成 hsl(…) | 状态标签 | |
+| 字体 | 标题 … / 正文 … / 数字 … | | |
+| 圆角 | …px | | |
+| 阴影 | 不用 / 仅浮层 / 卡片轻阴影 | | |
+| 图标线宽 | …px | 按视觉方向定，全应用统一 | |
+| 字号阶梯 | 11 / 12 / 13 / 14 / 18 / 24px | 辅助 / 表格 / 正文 / 小标题 / 区块标题 / 页标题 | |
+| 点睛样式 | …（按〈应用类型〉的记忆点一栏填，不设填「无」） | 一个只属于这个产品的细节 | |
+| 动效 | 入场：… / 页面切换与面板展开：… / 悬停与选中：… | 三项都填 | |
+| 配图风格 | 画风 … / 和色板的关系 … / 比例 … | 不需要配图填「无」 | |
+
+### 间距
+- …（沿用原有间距规则）
+
+### 页面实现约束
+- 颜色、字体、圆角只用 tailwind-theme.css 变量和 index.css 里的全局类，禁止写死色值；状态色用 …（本应用的 --status-* 变量）
+- 不改 tailwind-theme.css 和 index.css 里的点睛样式
+- 金额、日期、编号加 `.tnum`；页面主标题用 `.font-display`；有记忆点时写清 `.…` 用在哪几处
+- 悬停和选中全应用一套规则：卡片、按钮悬停至少变化两样（底色加深一档、轻微上浮或阴影出现、边框换成主色），不能只换文字颜色；表格行、列表行悬停只加深底色，不上浮；选中态比悬停态更明确（如主色左边框或主色浅底）
+- 页面切换、tab 切换、抽屉和弹窗展开要有过渡（淡入或轻微位移，0.15–0.3s），不要瞬间跳变；动效按 animation-skill 实现，必须尊重 `prefers-reduced-motion`
+- 操作要有看得见的反馈：保存、删除、勾选完成、复制成功都要有状态变化（按钮态、行内提示、条目淡出等），不只靠 toast
+- 配图按上面的配图风格生成，生成后补进配图清单
+- 圆角只用 `--radius` 派生的几档（rounded-sm / md / lg，标签、头像用 rounded-full），一个页面不超过 3 种；嵌套时内层圆角 = 外层圆角 − 内边距
+- 图标尺寸跟着文字走（12px 文字配 12px 图标，14 配 14，16 配 16）；纯图标按钮全应用统一一种尺寸
+- 一个应用只用一种主导航（侧栏或顶栏），不在两处重复同一组入口
+- 纹理、线条、图案等装饰只放在背景或留白处，不能穿过文字和控件；影响可读性就去掉
+- 视觉方向只决定视觉，不改变文案语气。文案按产品功能和使用者写：页面标题说清这是什么、能做什么，按钮写清点了会发生什么，同一个动作全流程同名
+- 方向名、产品定位句只写在 AGENTS.md，不出现在界面上；界面语言和用户一致，不加装饰性的外文小标签
+
+### 配图清单
+- <位置>：<生成返回的路径>（没有配图写「无」）
 ```
 
-```markdown
-## 设计方向
-
-- 自定义：产品主题 <一句话> / 质感 <一句话> / 配色 <主色与基础色，给色值> / 辨识度设计 <一句话>
-```
-
-用户点名预置风格时使用“预置风格”格式。完整的自定义视觉方案使用“用户指定”格式。frontend-design 生成的方向使用“自定义”格式。具体颜色和样式变量写入主题样式文件，不写入 `AGENTS.md`。
-
-## 页面适配底线
+## 应用类型
 
-- 先让桌面宽屏拥有完整的信息层级和合理密度，再设计窄屏重排；不要把桌面端做成放大的手机单列页。
-- 页面宽度要跟随窗口变化并设置最大宽度；网格要能自动增减列数；在内容排不下时切换布局。主要布局不要写死宽高。
-- 窄屏优先改变排列、折叠次要信息和收纳导航，不缩小到不可读；除数据表格等必要区域外，不产生整页横向滚动。
-- 生成持续可见的桌面左侧菜单时，最好增加收起和展开操作，并优先复用模板已有的侧栏组件；用户明确要求固定菜单时除外。
-- 按钮和其他可点击区域要足够大。固定侧栏、悬浮装饰、超大标题和多栏内容在窄屏都要有明确的调整方式。
+| 类型 | 例子 | 信息密度 | 颜色力度 | 字体倾向 | 动效 | 记忆点 |
+|---|---|---|---|---|---|---|
+| 业务工具 | 台账、工单、CRM、审批、后台 | 高：一屏多看数据，密而有序 | 克制但要有立场：主色和字体是专门挑的，强调色只用在关键处 | 以无衬线为主，靠字重和字号分层；衬线标题只用于档案、编辑、出版这类本身带纸面阅读感的产品 | 少而准：入场、面板展开、操作反馈 | 不单设，填「无」；辨识度放在配色、字体、悬停与过渡、空态和最要紧状态的呈现上 |
+| 个人工具 | 记账、习惯打卡、读书清单、日记 | 中低：留白多，一次只做一件事 | 温和但有颜色，让人愿意打开 | 圆润或手写感的展示字体做标题，正文无衬线 | 多一些小交互：勾选、完成、切换都有手感 | 可选，合适时可以用物件式元素；没有合适的填「无」 |
+| 消费类应用 | 点评、预约、二手交易、社区、小商城 | 中：图片和卡片为主，一眼能挑 | 有个性，配色要让人记住，但不能影响找东西、下单 | 有个性的无衬线或展示字体，不用衬线 | 反馈做足：点赞、收藏、加购、下单成功都有明确的状态变化 | 不要求；视觉主角是商品、门店、帖子等内容本身，精力放在图片质量、卡片排布和操作反馈上 |
+| 展示型页面 | 活动页、报名页、品牌介绍、作品集 | 低：靠大字、大图、节奏 | 大胆，可以用鲜明的主色和大面积色块 | 标题用有性格的展示字体，按主题选，可粗可窄 | 可以丰富：滚动出现、分段入场 | 必须有一个只属于这个产品的细节，可以是物件式元素 |
 
-界面图形和状态标识不使用 emoji，使用项目现有图标或文字。
+判定类型时写一句理由。多人协作、要批量处理、数据长期累积的按业务工具；一个人自用的按个人工具。一个应用里同时有两类页面时（如报名页 + 管理后台），按页面分组各定类型，但共用同一套色板和字体。
 
-## 风格索引
+## 避开默认长相
 
-索引只概括视觉特征，不限定业务场景。具体规格与例外以对应风格文件为准。
+下面这些是不看场景就会冒出来的默认答案。用户、品牌或主体识别色明确时照办；否则填完基线后逐条对照，命中就回到产品世界重新推导：
 
-- `sap-fiori-horizon` **晨光远航**
-  视觉：冷白画布、浅灰分组面与深蓝文字，企业蓝仅标记主操作、链接、选中态和焦点 / Inter 与中文无衬线兜底，14px 正文、等宽数字 / 6px 控件、8px 卡片、1px 边框，普通卡片无阴影 / 紧凑表格、表单、工具栏与明确状态反馈 / 窄屏重排并保留操作能力
+- 深藏蓝主色（色相约 215–230、明度低于 30%），尤其配暖白底和金色点缀
+- 任何类型都用衬线标题（Noto Serif SC 之类）+ 等宽数字的组合
+- 页标题下一条从实色渐隐的细线作为点睛
+- 紫色 / 蓝紫渐变、发光、玻璃拟态
+- 白底 + 灰字 + 一个主色
+- 方向名套用通用说法（「xx 档案」「xx 工作台」「xx 便签板」），而不是本产品自己的物件
 
-- `finance-report` **财报纸本**
-  视觉：米白画布、白色内容面与近黑文字，青蓝仅标记图表主序列、进度和关键结论 / 衬线标题与关键数字、无衬线正文、等宽标签和右对齐数字列 / 内部数据块无阴影，仅外层纸面使用单层柔影 / 细行线、粗表头线、墨线合计行与单个淡蓝结论框
+## 自查清单
 
-- `industry` **工业图纸**
-  视觉：冷灰白图纸底与单一钢蓝构成技术色调，深钢蓝仅作分节强调 / Barlow Condensed 压缩标题搭配 Barlow 正文和等宽标记 / 直角发丝线框，卡片与图框可带四角套准十字 / 内容照片双色化、工程编号和制图标记增强识别 / 冷静、工程化、精确
+- [ ] 一眼看得出是什么场景的应用，不像模板换了主色；能对上产品定位那句话
+- [ ] 方向名说得出来自本产品的哪个物件，且没有出现在任何界面文案里；主色出处能对上主体识别色或场景物件
+- [ ] 逐条过〈避开默认长相〉和〈页面实现约束〉，都没命中、都做到了；每个颜色都说得出用途
+- [ ] 标题与正文字体或字重有明显区分；同组紧、异组松；表格的表头、字号、颜色与页面一致
+- [ ] 没有文字截断、贴边、空下拉框、图表尖刺；375 宽无横向滚动，侧栏收成折叠菜单，表格可横向滚动或改卡片
+- [ ] 首屏有内容；配套页面、空态、长文本、超多条目都有专门样式；配图风格统一，没有空框或随机图
+- [ ] 界面上的按钮和入口都能用；对比度够，关键操作可用键盘完成
 
-- `cybernetic-vault-terminal` **赛博机库**
-  视觉：深蓝黑画布、藏蓝表面、白色主文字与灰色辅助文字，天蓝和亮蓝用于主要行动 / Inter 中等字重大标题与常规正文，JetBrains Mono 承载小型技术标签 / 24px 圆角卡片与细边框，控件采用约 23px 圆角或胶囊形态 / 紧凑的嵌套面板与突出数值 / 冷峻、理性
-
-- `nexuscore-analytics` **核心分析**
-  视觉：近黑画布与深灰表面，白色主文字、灰色辅助文字，紫色集中于主要行动 / Inter 中等字重大标题与常规正文，JetBrains Mono 承载小型标签 / 8px 圆角卡片与控件，细边框区分嵌套表面 / 紧凑的模块化面板、清晰的信息层级与数值强调 / 冷静、紧凑
-
-- `crimson-frosted-glass` **暗黑毛玻璃**
-  视觉：黑底叠加模糊背景图与渐变遮罩，白色文字、亮红强调 / 超大粗体无衬线标题，紧字距，大数值突出 / 半透明白色毛玻璃卡片，24px 大圆角与细边框，卡片不依赖投影分层 / 透景层次、大幅图卡与数据块组合 / 沉浸、鲜明、具有空间深度
-
-- `nebula-crimson` **深红星云**
-  视觉：白色、浅灰与近黑大面积交替，暗酒红用于品牌区块和重点信息 / 超粗巨型标题与紧字距，全大写宽字距小标签 / 中到大圆角面板，暗区半透明玻璃容器，局部柔和或品牌色投影 / 全幅明暗交替、网格线、局部碳纤维纹理与深红模糊光斑 / 庄重、浓烈、富有叙事节奏
+---
 
-- `dashboard` **陶土净台**
-  视觉：暖米白底、纯白卡片与暖黑文字，陶土橙集中于主按钮和主图表，次级图表采用中性色 / 系统无衬线字体，常规正文与中等字重小标题，大数字收紧字距，小标签全大写宽字距 / 10px 圆角卡片、6px 圆角控件，1px 暖灰边框，无投影 / 疏朗的指标面板与细线表格，以灰度、大小写和字距建立层级 / 温润、干净、克制
+## Example
 
-- `minimal-jade` **简约翡翠**
-  视觉：浅灰蓝底、独立白卡与草绿强调，首要图表序列用草绿、次级序列按黑色透明度递减 / 无衬线超大粗标题，JetBrains Mono 对齐指标和表格数字 / 12px 圆角、浅阴影与悬停上浮，边框由透明转浅灰 / 草绿装饰条、图标和进度形成连续识别线索
+### 1. tailwind-theme.css
 
-- `metabase` **湖光蓝调**
-  视觉：纯白主面与大块极浅蓝静区，深蓝文字配明亮蓝主按钮和交互焦点 / Lato 人文无衬线字体，粗体标题、常规正文和弱化元信息 / 4–12px 圆角、1px 半透明边框，平铺卡片使用轻投影，浮层使用更深漫射阴影 / 实底蓝主按钮、描边次按钮和浅蓝筛选区形成层级
+改 `:root` 里这些变量，值都按本应用的基线填，颜色写成 `hsl(H S% L%)`：
 
-- `pm-spec` **规格蓝本**
-  视觉：冷灰蓝底、白色纸面与深墨文字，靛紫用于小面积结构性强调 / Charter 衬线标题与引用，无衬线正文，等宽体承载全大写微标签 / 10px 圆角卡片、1px 细边框，无投影，引用块配强调色左边线 / 单栏纸面文档流、紧凑正文、元信息条与局部分栏信息块 / 严肃、克制、秩序感
+- 颜色组：`--background`、`--foreground`、`--primary(-foreground)`、`--accent(-foreground)`、`--muted(-foreground)`、`--border`、`--input`、`--ring`、`--destructive`、`--sidebar*`、`--chart-1…5`
+- 字体：`--font-sans`（正文）、`--font-serif`（标题或展示字体，按〈应用类型〉的字体倾向选，不一定是衬线）、`--font-mono`（数字）
+- `--radius`、`--shadow-*`（用就写成套，只给浮层就只改浮层那一档）
+- 业务语义色 `--status-<状态名>`，并追加到文件里已有的 `@theme inline` 块，不要另起一个：
 
-- `claude-editorial-research` **陶色书卷**
-  视觉：暖奶油画布、米色卡片与暖近黑产品面，陶土珊瑚用于主按钮和强调色块 / 常规字重衬线展示标题配负字距，人文无衬线正文，代码采用等宽体 / 中等圆角、发丝边框，层次主要来自表面色差，投影稀疏 / 奶油与深色表面交替，整块珊瑚强调卡与深色代码窗 / 温和、沉思、社论感
+```css
+@theme inline {
+  --color-status-<状态名>: var(--status-<状态名>);
+}
+```
 
-- `digital-e-guide` **暖陶刊物**
-  视觉：暖陶粉径向渐变背景，奶油纸卡与暖黑文字，马克红主强调、暖橙少量辅助 / Cormorant 大衬线标题与斜体强调，DM Serif Text 衬线正文，等宽体承载元信息 / 4px 微圆角纸卡、长柔阴影与发丝分隔线 / 纸卡交替微旋，双栏正文、外缘引文卡与圆贴纸形成摊开杂志的层次 / 温暖、文艺、印刷感
+### 2. 字体加载
 
-- `broadsheet` **新闻大报**
-  视觉：纸白与近黑墨色为主，青、洋红和工艺黄只作克制点色 / Source Serif 4 衬线字体贯穿标题、正文和控件，主要靠字阶与留白建立层级 / 1–4px 微圆角、细线分隔，卡片仅用于真正离散的条目 / CMYK 套印偏移、网点图像和印版标记形成新闻印刷签名 / 理性、编辑感、公共信息气质
+写在 `client/src/index.css` 第一行，放在已有的 `@import` 之前（`@import` 必须位于所有其他规则之前）。不要改 `client/index.html`（平台关键文件）：
 
-- `organic-minimalism` **有机极简**
-  视觉：纯白画布与浅暖灰绿表面，柔和石灰绿强调激活态、按钮和结果 / 简洁无衬线排版，标题与数值通过字重和字号区分 / 40–48px 超大圆角主卡片，极淡边框与浅阴影 / 大留白、极简线性图标、稀疏装饰 / 自然、轻盈、松弛
+```css
+@import url("https://miaoda.feishu.cn/fonts/css2?family=<标题字体>:wght@<字重>&family=<正文字体>:wght@400;500;700&family=<数字字体>:wght@400;500&display=swap");
+```
 
-- `warm-elegance` **暖调精致**
-  视觉：暖米、暖灰与暖黄渐变背景，白色卡片与深灰黑反转区，黄色点缀主行动和活跃信息 / 无衬线标题与正文，轻字重大数值、等宽辅助数据，局部斜体小标签 / 32px 主卡片与 24px 深色嵌入卡片，浅区轻投影，深区更强投影与局部光晕 / 深浅卡片对比，纤细胶囊柱图、环形进度与磨砂玻璃标签 / 温暖、柔和、安心
+可用字体与 Google Fonts 一致，按气质挑，不要每个应用都用同一组。常用：中文无衬线 Noto Sans SC；中文衬线 Noto Serif SC、ZCOOL XiaoWei；中文展示 / 手写 ZCOOL QingKe HuangYou、ZCOOL KuaiLe、Ma Shan Zheng、Long Cang；西文与数字 Space Grotesk、Manrope、DM Sans、Outfit、IBM Plex Sans、Barlow Condensed、JetBrains Mono、IBM Plex Mono。
 
-- `flowbite` **Flowbite**
-  视觉：白色与浅灰表面、深灰标题，蓝色主按钮和链接，支持对应暗色配色 / Inter 无衬线排版，超粗大标题配紧字距，正文常规字重 / 规整中圆角，以 8px 为主，1px 浅边框与轻投影 / 实底蓝按钮、浅蓝徽章、浅灰输入框，组件形态统一 / 清晰、规整、务实
+### 3. 点睛样式（client/src/index.css 末尾）
 
-- `handwritten-sketch` **手绘草稿**
-  视觉：米黄纸底、白色卡片与墨黑文字，标记笔红、钢笔蓝和便利贴黄点缀 / Kalam 手写标题与 Patrick Hand 手写正文，中文使用系统字体兜底 / 不规则弯曲圆角、3px 墨黑粗边与零模糊偏移硬阴影 / 圆点纸纹、微旋卡片、透明胶带、图钉和波浪下划线，局部黑板反色 / 亲和、轻松、手工感
+类名 `.tnum`、`.font-display`、`.rise` 固定，Worker 会直接用：
 
-- `wild-orange` **橙色野性**
-  视觉：纯白画布、黑色文字与粗边，橙色主强调搭配少量浅橙和灰阶 / 粗体大写无衬线标题，Playfair 斜体衬线点缀装饰文字与小数值 / 直角卡片、2–4px 黑色粗边、4–8px 零模糊硬阴影 / 几何装饰圆、橙色横幅、圆形编号，卡片按压式位移与阴影收缩 / 自信、大胆、图形感
+```css
+.tnum{font-variant-numeric:tabular-nums;font-family:var(--font-mono);}
+.font-display{font-family:<标题字体变量>;letter-spacing:<按字体调>;}
+.lucide{stroke-width:<基线表的图标线宽>;}
+/* 记忆点：要不要设按〈应用类型〉记忆点列，类名按用途起 */
+.<记忆点类名>{<实现>}
+@keyframes rise{from{opacity:0;transform:translateY(6px)}to{opacity:1;transform:none}}
+.rise{animation:rise .35s cubic-bezier(.2,.7,.2,1) both}
+@media (prefers-reduced-motion:reduce){.rise{animation:none}}
+```
 
-- `pop-art` **波普艺术**
-  视觉：明亮黄色主背景，白色卡片，红、绿、蓝高饱和色块搭配纯黑 / 漫画展示字体、超粗标题与醒目标签，中文使用无衬线兜底 / 粗黑描边、零模糊偏移硬阴影，大圆角卡片与胶囊按钮搭配直角色块 / 半色调网点、轻微倾斜的拼贴标题、按压位移交互 / 热烈、直接、漫画感
+### 4. 表格跟随主题（client/src/index.css）
 
-这份列表只用于初步选择。选定后，颜色、圆角、字号、组件样式和例外情况一律以对应风格文件为准。
+```css
+.ant-table{font-family:var(--font-sans);font-size:13px;color:var(--foreground);}
+.ant-table-thead>tr>th{font-size:12px;font-weight:500;color:var(--muted-foreground);background:var(--muted);}
+.ant-table-tbody>tr>td{border-color:var(--border);}
+.ant-table-tbody>tr:hover>td{background:var(--accent);}
+```

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

@@ -84,6 +84,7 @@ gate-tools:
    - 必须先调 `get_plugin_ai_json(pluginInstanceId)`，再产出 **Schema 摘录卡**（格式见 `references/plugin-coding-guide.md`）；摘录卡字段缺失禁止编码，`output.fields` 必须完整列出且每个输出字段在代码中被消费（持久化或展示）
    - 按 `actions[].key` 选 actionKey；严格按 `inputSchema` 构造入参（`type: array` 字段必须传数组）、按 `outputSchema` 解析出参——流式 chunk 是**对象**（按字段解构如 `chunk.content`，禁止当字符串拼接），非流式同理按字段名读取；**务必阅读并遵循 `readme`**
    - 调用侧：优先 Client（`unary` → `call()`，`stream` → `callStream()`）；触发器/定时任务、敏感凭证、强事务、结果需落库 → Server 侧
+   - **复用已存图片作插件入参（如 `ai-image-to-image` 参考图）**：路径含 `/api/v1/storage/object/` 的图片 URL（插件生图结果、storage / dataloom `download_url`）不要直接传给插件，也不要在浏览器下载后再上传；先请求后端接口，按 references/plugin-coding-guide.md「Server 侧已持久化文件进入 AI capability」解析出 bucket 与 file path并签成临时 URL，再把签名 URL 传给插件（Client 侧 `capabilityClient` 或 Server 侧 `CapabilityService` 均可）。用户刚选择的文件直接传 `File`，其他 http(s) URL 直接传。
    - 高耗时 AI capability 闸门：若运行时投影或功能设计显示输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，禁止把完整生成放进一个同步 HTTP 请求等待；能由前端承接时优先 `callStream` 渐进展示，需保存则流式结束后复用 CRUD 落库；仅在 Client 侧无法满足时后端创建任务记录后快速返回、由前端短轮询状态/结果，或拆成多个独立小调用
 4. **代码放置**：Client（默认，用户交互触发）→ `client/` 组件/hooks；Server（兜底）→ `server/` Service。
 5. **真实调用冒烟（完成前必须）**：至少成功调用一次 SDK `call(actionKey, input)` 或 `callStream(actionKey, input)`（按 outputSchema 读 chunk）；失败日志含最小字段（见 `references/plugin-coding-guide.md`）。绕过 SDK 手动复测 capability HTTP/debug 入口前，先读 `references/plugin-coding-guide.md` 的“服务端 capability 手动 HTTP 调试与排障”；无冒烟结果不得宣告完成。
@@ -219,6 +220,8 @@ const structured = await capabilityClient
 
 > **已知必填配置值的传入**：用户对话中已给出的必填配置（如飞书 base URL 含 AppToken/TableID），CREATE 时**必须显式列入 `requirementsSummary` 字段**让平台 LLM 装配到 formValue。例：`requirementsSummary: "创建飞书多维表格写入实例，appToken=ZeHhbA4MxxxX, tableID=tblMQ9OgxxxW, 用于把 Excel 行批量插入"`。
 
+> **feishu-bitable 字段类型的传入**：用户只给了 Base 链接、没有在界面上选择表格时，平台不读取源表结构，`fields` 的类型由平台 LLM 按 `requirementsSummary` 生成，会按字段名猜（如「价格」→ Currency、「状态」→ SingleSelect）。CREATE 前，lark-cli 可用时先执行 `lark-cli base +field-list --base-token <appToken> --table-id <tableID>` 读取真实字段，在 `requirementsSummary` 里逐个写明「字段名:类型」，单选 / 多选字段附上选项值。例：`字段：物料编码:Text, 标准价格:Text, 同步状态:SingleSelect(待同步/已同步)`。多维表格实例不允许 UPDATE，类型写错只能重新 CREATE。
+
 ## 插件调用错误处理
 
 错误分类与应对策略详见 `references/plugin-coding-guide.md`「调用错误分类与应对」。必须遵守：
@@ -287,4 +290,5 @@ const url = `https://${req.hostname}${process.env.CLIENT_BASE_PATH}${routePath}`
 | 前端调插件后不保存结果（页面刷新丢失），或为保存结果单独新建 API 端点 | 需持久化时 Server 侧调用直接落库（优先），或 Client 侧调用后立即经**已有** CRUD 接口保存 |
 | Server 侧把非标准相对路径、误拼 origin 的 storage object path、前端展示 URL 或非法 base64 data URL 传给 `file` / `picture` / `plugin-file-url` / `plugin-image-url` 参数 | 已持久化文件优先用 `file_path` 或 `bucket_id + file_path` 生成 1h 签名 http(s) URL 后再传；标准 storage download URL 要先解析 bucket 与 file path，再从对应 bucket 签名 |
 | 创建了 PluginInstance 但只建不调 | CREATE 后必须接 `get_plugin_ai_json` → 生成调用代码 → 集成业务逻辑 |
+| 把路径含 `/api/v1/storage/object/` 的图片 URL 直接作为 `ai-image-to-image` 参考图 | 经后端接口解析 bucket 与 file path 签成临时 URL 后传入 |
 | 插件返回值 `as any` 直接取字段 | 按 outputSchema 生成 TypeScript interface |

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

@@ -620,6 +620,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 - `justify-between/around/evenly` 必须配合 `space-x-*` 或 `gap`
 - `justify-start/end` 的水平 flex 行应加 `flex-wrap`
 - shadcn Button 不要显式控制 padding/height，用 sizes/variants API
+- `tailwind-theme.css` 里设 `position: relative` 的那组 `.hover-elevate:not(.no-default-hover-elevate)` 规则，没被 `:where()` 包住时要包上（每个选择器各包一层，如 `:where(.hover-elevate:not(.no-default-hover-elevate))`），否则 `Button`/`Badge` 上的 `absolute`/`fixed`/`sticky` 会失效。改主题文件时顺手检查；遇到按钮定位不生效也先查这里，由主 agent 修改
 - 颜色优先级：语义化 token（`bg-primary`）> 自定义 token > Tailwind 预设。禁止 `bg-[--primary]`（Tailwind 4 限制）
 - **arbitrary values 中空格用下划线**：`from-[hsl(215_60%_18%)]` 非 `from-[hsl(215 60% 18%)]`
 - `tailwind-theme.css` 自定义属性用 `hsl(H, S%, L%)` 格式（非 `23 10% 23%`）

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

@@ -43,6 +43,7 @@ lark-cli apps --help 2>&1 | grep -q '+plugin-install' && echo "READY" || echo "M
 
 > **capabilityClient 导入警告**：`capabilityClient` 是从 `@lark-apaas/client-toolkit` 直接导入的独立对象，**不是**从 `getDataloom()` 上获取的。正确且唯一的方式：`import { capabilityClient } from '@lark-apaas/client-toolkit'`。
 > **文件类参数**：Client 侧原始 `File` / `Blob` 直接传 `capabilityClient`，禁止先经 dataloom 上传再传 URL。已持久化文件/图片由 Server 侧 `CapabilityService` 调 AI 插件时，优先取 `file_path`（或 `bucket_id + file_path`）用 `FileService.createSignedUrl(filePath, 3600)` / `fileService.from(bucketId).createSignedUrl(filePath, 3600)` 签成临时 http(s) URL 后传入。旧记录只有标准 `/app` 或 `/spark/app/.../runtime/api/v1/storage/object/<bucket>/<key>` download URL 时，必须先解析其中的 bucket 与 file path，再调用 `fileService.from(bucketId).createSignedUrl(filePath, 3600)`；默认 `createSignedUrl()` 只使用默认 bucket，不能从 URL 切换 bucket。禁止给标准路径拼接 `localhost`、`window.location.origin` 或 `/app/<app_id>`；非标准相对路径、前端展示 URL、非法 data URL 不作稳定入参。签名失败或返回空 URL 时要 `warn`，业务状态保持 `failed` / `pending` / `null`，不写成功态。
+> **复用已存图片作插件入参（如 `ai-image-to-image` 参考图）**：路径含 `/api/v1/storage/object/` 的图片 URL（插件生图结果、storage / dataloom `download_url`）不要直接传给插件，也不要在浏览器下载后再上传；先请求后端接口，按 references/plugin-coding-guide.md「Server 侧已持久化文件进入 AI capability」解析出 bucket 与 file path并签成临时 URL，再把签名 URL 传给插件（Client 侧 `capabilityClient` 或 Server 侧 `CapabilityService` 均可）。用户刚选择的文件直接传 `File`，其他 http(s) URL 直接传。
 > **稳定契约**：已持久化文件不得先下载再转 base64；应统一使用签名 URL。缺少可识别的文件路径、签名失败或返回空 URL 时记录警告，写入 `failed` / `pending` / `null`，并停止调用插件；不得改用原始 URL。
 
 ## Plugin 代码编写指南

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

@@ -91,7 +91,7 @@ match-template-name: vite-react
 | **内容生成** | `ai-speech-synthesis` | 文本→语音（44+音色） |
 | **图片处理** | `ai-image-matting` | 图片→抠图/去背景/去水印 |
 | **图片处理** | `ai-background-replace` | 主体图+背景→合成图 |
-| **图片处理** | `ai-image-to-image` | 参考图(1-5张)+描述→编辑/风格转换 |
+| **图片处理** | `ai-image-to-image` | 参考图(1-5张)+描述→编辑/风格转换。复用站内图片先读成 File 再传（见下文） |
 | **图片处理** | `ai-image-compare` | 两张图→对比分析（流式） |
 | **外部服务** | `feishu-bitable` | CRUD 飞书多维表格（5个Action） |
 | **外部服务** | `send-feishu-message` | 发送飞书卡片消息 |
@@ -164,6 +164,8 @@ const structured = await (jsonExtractor as any).call('textToJson', { text: rawRe
 > ```
 >
 > ⚠️ `capabilityClient` 支持此能力，SDK 自动处理文件上传。
+>
+> **复用站内图片作插件入参（如 `ai-image-to-image` 参考图）**：路径含 `/api/v1/storage/object/` 的图片 URL（相对路径或本站域名的绝对 URL；插件生图结果、storage / dataloom `download_url` 多为此类）不要直接传，先用浏览器 `fetch` 读成带扩展名的 `File` 再传给 `capabilityClient`；其他 http(s) URL 直接传；用户刚选择的文件直接传 `File`；生成或上传当下已持有的 File/Blob 留着复用。读取失败时提示用户重新选择原图。读图写法与验证方式见 `references/plugin-coding-guide.md`「图片编辑参考图」，不要因读图在验证环境失败而改回直接传 URL。
 
 ### 创建结构化提取 PluginInstance 的关键要求
 
@@ -292,7 +294,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
    }
    ```
 
-> **注意**：`format: "file"` 和 `format: "picture"` 的字段支持直接传入 File/Blob 对象，`capabilityClient` SDK 会自动处理上传。
+> **注意**：`format: "file"` 和 `format: "picture"` 的字段支持直接传入 File/Blob 对象，`capabilityClient` SDK 会自动处理上传。即使运行时投影里的字段类型显示为 `string` / `string[]`，只要语义是图片/文件输入，也可以直接传 File/Blob。
 >
 #### PluginInstanceAIJson（运行时投影 / 工程转化层产物：pluginInstance.ai.json）
 
@@ -385,6 +387,8 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
 4. 调用侧在生成调用代码前，**必须**通过 get_plugin_ai_json 获取该插件实例的运行时投影（plugin_Instance.ai.json），并以其作为入参/出参 schema 与 action 列表的唯一权威依据，禁止自行猜测。
 5. 若插件表单字段中包含 card_content 且其语义为飞书消息卡片，则生成/更新 PluginInstance 配置时，formValue.card_content 必须是 JSON Object，不能是转义字符串；并且卡片 DSL 的最后两个元素必须固定。
 
+> **feishu-bitable 字段类型的传入**：用户只给了 Base 链接、没有在界面上选择表格时，平台不读取源表结构，`fields` 的类型由平台 LLM 按 `requirementsSummary` 生成，会按字段名猜（如「价格」→ Currency、「状态」→ SingleSelect）。CREATE 前，lark-cli 可用时先执行 `lark-cli base +field-list --base-token <appToken> --table-id <tableID>` 读取真实字段，在 `requirementsSummary` 里写明 appToken、tableID，并逐个写明「字段名:类型」，单选 / 多选字段附上选项值。例：`字段：物料编码:Text, 标准价格:Text, 同步状态:SingleSelect(待同步/已同步)`。多维表格实例不允许 UPDATE，类型写错只能重新 CREATE。
+
 ---
 
 ## GetPluginInstanceAIJson 工具使用指南
@@ -459,6 +463,7 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
 | 未读 `inputSchema` 就假设参数类型（如 string vs array） | 先调用 `get_plugin_ai_json` 查看 `inputSchema`，注意 `type: array` 字段 |
 | 通过 `getDataloom().capability` 或 `(dataloom as any).capability` 调用插件 | `capabilityClient` 是独立导入，不通过 dataloom 访问。dataloom 仅提供 storage 和 service |
 | 调用插件时，先通过 dataloom 上传文件拿 URL 再传给插件 | 可直接传 File/Blob 对象给 `capabilityClient`，SDK 自动处理上传 |
+| 把路径含 `/api/v1/storage/object/` 的图片 URL（插件生图结果 / storage / dataloom `download_url`）直接作为 `ai-image-to-image` 参考图，或手拼 origin | 浏览器 fetch 读成带扩展名的 File（校验 `image/*`）再传；其他 http(s) URL 直接传 |
 | 前端调用插件后不保存结果到数据库，导致页面刷新后数据丢失 | 调用插件成功后，必须通过已有 CRUD 接口立即保存结果 |
 | 为保存插件结果单独新建 API 端点（如 `PATCH /api/xxx/ai-analysis`） | 优先复用已有的业务 CRUD 接口（create/update）扩展字段 |
 

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

@@ -22,6 +22,50 @@
 - `actions[].inputSchema / outputSchema`：入参/出参结构
 - `actions[].outputMode`：`unary | stream`（决定调用与结果处理方式）
 
+#### 图片编辑参考图
+
+给 `ai-image-to-image` 等插件传图片时，按 URL 形态判断：
+
+- 路径含 `/api/v1/storage/object/`（相对路径或本站域名的绝对 URL；插件生图结果、storage / dataloom `download_url` 多为此类）：不要直接传，先在浏览器读成 `File` 再交给 `capabilityClient`。
+- 其他 http(s) URL（用户粘贴的外链、插件返回的其他绝对地址）：直接传，不要 fetch。
+- 用户刚选择的文件：直接传 `File`。
+
+> 实例 ID、`actionKey`、字段名（`image_editor_instance` / `imageToImage` / `images` / `prompt`）仅为示意，以 `get_plugin_ai_json` 返回的 `actions[].key` 与 `inputSchema` 为准。
+
+```typescript
+const IMAGE_EXT: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+};
+
+const isStorageObjectUrl = (url: string) =>
+  new URL(url, window.location.href).pathname.includes('/api/v1/storage/object/');
+
+async function toPluginImage(url: string): Promise<File | string> {
+  if (!isStorageObjectUrl(url)) return url;
+  const response = await fetch(url); // 保持默认 credentials，不要改成 include
+  if (!response.ok) throw new Error(`读取参考图失败：HTTP ${response.status}`);
+  const blob = await response.blob();
+  if (!blob.type.startsWith('image/')) {
+    throw new Error(`参考图读取结果不是图片：${blob.type || 'unknown'}`);
+  }
+  return new File([blob], `reference.${IMAGE_EXT[blob.type] ?? 'png'}`, { type: blob.type });
+}
+
+const image = await toPluginImage(imageUrl);
+const editor = (capabilityClient as any).load('image_editor_instance');
+const edited = await (editor as any).call('imageToImage', {
+  images: [image],
+  prompt,
+});
+```
+
+- 读取失败或不是图片时报错并提示用户重新选择原图；不要退回直接传 URL，也不要换成外部随机图片。
+- 读出的 Blob 包成带扩展名的 `File` 再传。
+- 验证：沙箱验证入口下读站内图片拿不到图片（`image/*` 校验报错），用户预览态 / 运行态正常；不要因此改回直接传 URL。
+
 #### call / callStream 函数签名
 
 ```typescript