@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.6ef2b6f → 0.1.0-dev.72ac425

package/miaoda/charts-skill/SKILL.md

@@ -5,7 +5,7 @@ description: "shadcn/ui + ReactECharts 图表开发规范。Use when creating or
 
 ## L0 基础配置
 
-- **库**: `import ReactECharts from 'echarts-for-react'` (v5.6.0)
+- **库**: `import ReactECharts from 'echarts-for-react'` (echarts v6.1.x)
 - **主题**: `theme="ud"`
 - **颜色**: 🚨 只能用 hex（如 `#1890ff`），禁止 hsl/rgb
 - **高度**: ≥300px (`className='h-[300px]'`)

package/miaoda/creative-to-fullstack/SKILL.md

@@ -8,245 +8,57 @@ workspace-contains:
 
 # 把创意设计稿实现为全栈应用
 
-`source_package/creative/` 是创意模式设计稿，是本次开发的唯一视觉规格。交付标准：
+以 `source_package/creative/` 中的原创意设计应用为依据，在当前工程中交付真实可运行的全栈应用，而不是静态原型。源稿是只读的视觉与业务意图权威，不能作为交付应用的运行时依赖。目标是在保证以下结果的前提下尽快完成。
 
-1. **视觉与源稿一致**：每个页面的文案、数值、色值、条目与顺序与设计稿逐字段一致。
-2. **可见功能真实可用**：设计稿上每个可交互组件（可点、可输入、可筛选）都产生真实、闭环的结果。
+## 工程规范与最小规划
 
-两条核心规则：**一切视觉内容直接从源稿代码照抄，不经过任何文字转述**；**动手实现前先完成业务设计并写入 `docs/business-design.md`，后续每个阶段以该文件为执行依据**。
+- **开发前必读 `coding-guide`**：使用当前技术栈的工程、共享类型、平台能力及规范。开发 Worker 同样必读，只按需加载专项 skill；不另发明行数/目录规则或限定文件数。在独占页面/模块目录内，首次编码即可按该规范拆私有组件与逻辑文件；必要的后置重构须基于完整源码局部移动，不能依据截断读取整体重写。
+- **先写 `docs/business-design.md` 再编码**：只写支持实现与验收的决策，不誊写源稿视觉细节、实际种子值或逐控件功能全集。正文需覆盖下表，短列表或合并表格均可；同一事实只定义一次。
+- **契约先行**：当前并行批次所需的最小 shared 类型、路由参数、ID/状态/单位口径、实际 schema 与接口落盘可引用后即可开工，不等全部业务契约或公共组件实现完成；代码契约不与文档维护两份字段定义。执行期主 Agent 与 Worker 均不得擅改契约；阻断核心链路时暂停受影响任务，统一修订设计与契约，只通知受影响消费者并调整其任务。
+- 用 TodoWrite 记录实现、验收及未完成项，每批完成或提交前按事实更新。实际阻塞在设计文档中登记，交付时如实披露。
 
-## 流程
+### 业务设计必须回答的问题
 
-| 步骤 | 做什么 | 谁做 |
-|------|--------|------|
-| 1 | 通读源稿 | 主 Agent |
-| 2 | 业务设计（写入 docs/business-design.md） | 主 Agent |
-| 3 | 基建：结构骨架、建表、初始数据、共享视觉文件、插件实例 | 主 Agent + Worker |
-| 4 | 按业务域派发前后端完整实现 | Worker |
-| 5 | 验收 | 主 Agent + E2E |
+| 内容 | 最小产出 |
+| --- | --- |
+| 核心链路 | 按用户目标识别核心链路，每条链路定义：真实可见入口与目标对象 → 输入/动作 → 必要中间态 → 真实结果 → 回读位置。链路内各步骤作用于同一目标对象，每一步写入产生的对象、状态及其关联记录须满足下一步操作与回读页所需的数据条件，任一条件不满足即视为链路未闭环。 |
+| 非核心功能 | 不属于任何核心链路的功能点逐项列出，全部保留源稿视觉；其展示数据来自数据库中的真实记录，不实现业务写入、状态流转与外部能力接入。对应控件保持外观并呈现不可用语义，不显示虚假成功，不删除页面或区块。该清单与核心链路清单共同构成本次交付范围，收尾时按同一清单如实说明。 |
+| 页面与视觉来源 | 记录全部源稿页面对应的目标路由/目录、对象参数、源文件/区块，以及用户可见的到达路径；核心结果页明确其上游操作入口。记录全局 Layout 和真正跨页组件的归属，以及素材来源与迁移/复用方案。 |
+| 最小业务模型 | 核心实体、稳定 ID/关联、关键状态及前置条件、必要唯一性与可空规则；初始事实的源稿位置与字段映射，缺失事实按空态展示。 |
+| 接口与结果口径 | 核心动作的必要用户输入、前置条件、状态变化与回读结果在接口契约中一一对应。记录方法/路径、请求/响应类型及 shared 路径、错误/空态语义；动态结果明确事实来源、计算/筛选口径与变化触发。前后端共同引用对象 ID、状态、单位/取整、时间及可空字段口径。平台/插件能力按实际需要选型并确认可用契约。 |
+| 验收与阻塞 | 按源事实定义每条核心链路的可见操作路径、目标对象/状态、可判定的结果与刷新/跨页回读；覆盖相关中间态及动态变化，合并共享链路，另列全页面视觉检查。记录影响核心交付的外部依赖、资源缺失及实际阻塞。 |
 
-### 第 1 步：通读源稿
+设计以能开工、能判定结果为止；不扩成全产品设计、字段血缘大全或多层门禁。遇到新事实只改受影响条目，不反复读写整份文档。视觉实现者直接读取对应源稿，不凭主 Agent 转述实现。
 
-读取 `source_package/creative/` 下全部页面源文件（index.html、pages/、components/ 等）。该目录只读，是实现期间反复对照的唯一视觉权威；工程代码不得引用它，也不要修改它。稿内 `data-miaoda-*` 属性与 `<script type="text/babel">` 是创意平台预览机制，本工程不使用。
+## 交付目标
 
-### 第 2 步：业务设计（主 Agent 的核心职责）
+### 1. 页面视觉效果 100% 还原
 
-从源稿可见信息推断应用的业务模型。完成以下四项分析，**写入工程文件 `docs/business-design.md`**，作为第 3/4/5 步的执行依据：
+保留所有源稿页面、导航、布局、层级、尺寸、间距、字体、颜色、固定文案、素材主体与图表形态。素材优先复用/迁移；不可复用时替代图须保持原用途、主体、色调和裁切。以源稿中的实际业务页面为还原对象。
 
-**2.1 业务域划分**。按「业务模块闭环拆解规则」（见下方规则章节）从源稿划分业务域，产出各域的名称、覆盖的源稿页面与功能、服务端模块归属。
+动态数字来自当前业务事实，保持与源稿一致的单位、格式和排布。视觉验收关注整体呈现效果，允许动态数值和无影响的小图标差异。
 
-**2.2 数据模型**。以 2.1 划定的业务域为单位设计数据库。源稿页面上的展示数据分两类去向：与服务端逻辑相关的写入数据库、经服务端接口回到页面；不相关的以前端代码的形式展示。按以下顺序执行：
+### 2. 核心功能完整，操作链路与数据闭环
 
-1. **设计表结构**：为每个业务域设计该域的业务实体表，产出表名、字段（含类型）、表间关联。字段以支撑 2.3 的功能为准：筛选器的每个筛选维度要有对应字段，状态流转的状态字段枚举值从源稿可见的状态文案提取，插件结果需落库的（见拆解规则第 4 条）预留对应字段。建模范围按以下两条判据裁剪，**命中任一即入库**：
+- **承诺与结果一致**：核心动作必须真实完成其业务含义，写入后可按对象 ID 重新查询，成功页刷新/重进仍能显示该结果；仅 toast、跳页、接口 200 或数据库有记录不足以证明闭环。中间态与终态区分，不能提前显示全部完成或过早清空后续页面所需状态。
+- **对象身份一致**：入口、路由参数、详情、子记录和结果内容属于同一对象。已存在的合法对象不能仅因未出现在最近/摘要列表中就不可访问。无效 ID、无关联记录返回明确空态/错误，不能默认第一条记录来掩盖问题；新对象的可空字段不得使详情崩溃，空链接不渲染可点击目标。
+- **事实与状态来源**：初始数据从源稿明确的既有事实映射、去重并建立有依据的关联，保留各对象所处的业务状态。核心操作按业务规则生成必要关联记录，状态、时间与用户输入随实际执行更新；结果页读取执行后的事实。缺失事实如实展示空态，业务完成依据实际状态判定。
+- **动态数据同一口径**：会随业务变化的展示从事实实时计算，不用预置统计字段/常数替代。写入后的计数、进度、余额与聚合联动；周期选择一致作用于标题、明细和统计；分子分母、过程/结算/历史、时钟与取整口径统一。只为本身具有独立业务生命周期的快照保留持久化，不为展示另造真源。
+- **真实能力与明确边界**：核心 AI、媒体和外部能力取得真实结果或明确失败；检索计数/字符串模板不是 AI 回答，动画计时不是播放。按需读取 `plugin-guide` 并确认运行时 schema，不把普通数据库、定位/导航/扫码或内部演示支付机械判成插件。已明确采用内部演示的能力标识模拟边界，并使用一致、可复核的状态/计算，不能伪称外部执行成功；缺少核心资源则报告阻塞。
 
-  - 参与服务端逻辑：查询、筛选、排序、聚合、写入、状态变化；
-  - 属于开放集合实体的页面可见内容：实体会随业务增长（人、内容条目、业务记录等）时，该实体在页面上呈现的一切内容都入库，包含纯展示的长文本与列表——页面按实体标识渲染，写死会让所有实体呈现同一份内容。
+## 提效时的执行约束
 
-  两条都不命中的留在前端代码中：
+- 共享层只准备当前批次必要结构与接口，复用已有模板；不批量造空 API/DTO，主 Agent 不先写完所有服务和 SQL 才派发业务任务。
+- 以独占写入范围拆任务。优先按页面拆前端、按 server module 拆后端，让独立页面、后端模块与种子任务同批开始；不要把多页与整个后端塞进一个长任务。公共层一个写入者；公共组件有稳定接口即可并行消费，不等其实现完成。仅消费必要插件/素材的任务等待其结果，不让无关任务一起等待。
+- 种子数据：CodeAct 写种子数据与业务任务并行，按实际 schema 写入源稿已有对象及必要关联，写入成功即完成。统计数据基于实际数据计算，允许与源稿数值不同；运行时验证统一由主 Agent 完成。
+- 开发任务只检查自己改动的类型/契约等静态问题，达标即返回。不运行接口冒烟、启动服务联调、读运行时日志、读库验收或执行 E2E；运行时验证交由主 Agent 组织，避免开发与测试同时改同一资源。
+- 任务单引用所属核心链路、契约路径和独占写入范围，仅补充本任务特有的实现信息。前后端沿用同一结果、状态与统计口径；契约缺口由主 Agent 定点协调修订。回传改动文件、检查结果、实际阻塞和未完成项。
 
-  - 与页面结构绑定的固定文案：区块标题、页脚文案、静态导航项；
-  - 封闭枚举实体的装饰字段：实体是页面上固定的少数几项且不随业务增长时，其图标、配色不入库；该实体因参与筛选等逻辑而入库时也不带这些字段，由前端按实体标识映射；
-  - 平台内置服务已覆盖的数据（如用户信息、文件存储）不建表，使用内置服务。
+## 验收准则
 
-2. **确定建表顺序**：存在引用关系的表，被引用的表先建；该顺序供 3.2 建表与 3.3 数据写入按序执行。
+**验收前必读 `testing-guide`**，使用设计阶段已确定的清单，不在验收阶段重新扩展业务或以实际弱化实现改写通过标准。
 
-3. **标注数据来源**：为第 1 步建模的每张表标注初始数据取自哪个源稿文件、哪个区块；同一张表的数据散落在多个页面时逐条列全。只写位置指针，**设计文档中禁止出现任何初始数据内容**——不写字段值、不写示例记录、不做数据摘要；数据内容只在 3.3 执行时由 Worker 从源稿誊写，设计文档中出现的数据值一律不作为写入依据。
-
-**2.3 可见功能业务模型与 API 设计**。按 2.1 的业务域逐域进行，为每个域产出核心功能清单与接口设计。范围界定：仅涉及页面内交互、不读写业务数据的行为（Tab 切换、折叠展开、弹窗开关、表单字段校验）随页面视觉还原自然实现，不进入本节设计。
-
-对每个业务域依次完成：
-
-1. **识别核心功能**。从该域覆盖的源稿页面中，按以下类型识别核心功能（组件类型与功能信号的对照见 [references/ui-to-function.md](references/ui-to-function.md)）：
-  - 业务数据的写操作：新建、编辑、删除、提交、状态变更；
-  - 影响数据展示范围与形态的读操作：搜索、筛选、排序、分页；
-  - 页面间的业务流转：列表项进详情、详情进编辑等携带真实数据的跳转；
-  - 涉及外部能力的操作：上传、AI 处理、消息通知、定时任务。
-
-   每条功能记录为：「功能名称 + 所在页面 + 用户操作与预期结果」；操作结果需要跳转到另一个页面时一并写明目标页面，目标页面不在源稿里时标注为新增页面，由 3.1 规划路由与占位。
-
-2. **能力选型**。对每条核心功能按以下顺序判定实现方式：
-  - 平台内置服务（用户、文件、权限、消息、自动化/定时）可满足 → 直接使用，标注「使用平台内置服务：[服务名]」，禁止自建同等能力；
-  - 功能涉及 AI、智能、自动生成、大模型、文本生成、图片生成、飞书、消息通知、群组、机器人等能力 → 判定为插件能力，登记进 2.4 做插件设计；普通前后端能可靠实现的不硬凑插件；
-  - 两者都不满足 → 自建服务端 API，进入第 3 条。
-
-   判定插件能力时同时对照源稿代码补漏：用假逻辑模拟、但未以可交互组件呈现的此类能力（如定时提醒、自动通知），一并登记进 2.4。
-
-3. **API 设计**。为自建 API 的功能设计接口：
-  - 同一数据实体的操作合并设计：列表查询一个接口，入参覆盖该页全部筛选维度、搜索关键词与分页参数；新建、更新、删除、详情各一个接口；
-  - 每个接口写明：方法与路径、入参与出参、读写的表、支撑的功能。
-
-本节产出是第 4 步各域任务服务端子步骤的实现范围（域任务的 Service/Controller 按 API 清单逐接口实现），也是第 5 步核心验收目标的选取来源。
-
-**2.4 插件设计（条件步骤，仅当 2.3 判定出插件能力时执行）**。先读取 `plugin-guide` skill 了解插件目录与调用规范，然后对 2.3 登记的插件需求逐项设计。
-
-设计原则：
-
-- **原子化拆分**：一个插件实例只做一件事——不同输出类型（文本/图片/消息）建独立实例，不同业务语义（如标题与正文）建独立实例；
-- **链路完整性**：从用户输入到展示/落库，每一步都有对应插件——链式场景如文档解析→结构化提取需要两个插件；
-- **调用方式选择**：默认前端 capabilityClient 直接调用；以下情形改为服务端调用并说明原因：调用前需验证权限、需记录调用日志、结果需先落库、定时任务或 Webhook 无前端上下文、需聚合多个插件结果。
-
-输出格式，每个插件一行：
-
-| 插件名称 | 基础插件 | 用途 | 调用方式 | 关联页面/接口 | 输入参数 | 输出类型 |
-| --- | --- | --- | --- | --- | --- | --- |
-
-`docs/business-design.md` 写完后，用 TodoWrite 建执行清单，条目至少覆盖：每个基建项、每个业务域实现任务、**验收任务**（此刻即加入清单）。
-
-### 第 3 步：基建
-
-**执行者划分（不可调整）**：凡产出承载源稿可见内容（文案、色值、条目、数值、素材）的，一律派 Worker 实现——Worker 的任务范围窄、开工即按标注读取源稿，写前必然读到原文；主 Agent 亲写的范围只有纯结构骨架与数据库 DDL，这两类没有任何内容取自源稿。初始数据既承载源稿内容、又需要执行 SQL，派 `CodeAct`——它兼具读文件与执行能力，读源与写库在同一上下文内完成。主 Agent 不得亲自编写页面、组件、导航、页脚、主题色板、Service、Controller，也不得凭通读记忆写入任何源稿可见内容。
-
-**派发指令的内容边界（所有派发通用）**：派发指令只写任务目标、源稿位置、验收标准。**禁止在指令里复述源稿的任何具体内容**——色值、文案、条目、名称、数值一律不写，主 Agent 通读源稿形成的记忆不得以任何形式进入指令；Worker 需要的源稿内容由它自己按位置读取。每个派发任务都要带**双权威声明**：视觉、文案、色值、数据以源稿源码为唯一权威，工程契约（路由、表结构、接口、插件实例）以落盘文件为准，指令中的文字描述仅作辅助，与两者冲突时以文件为准——**指令里出现的源稿内容不作为实现依据**。
-
-**3.1 代码架构设计与结构骨架（主 Agent）**。先读取 coding-guide skill 了解项目编码规范与目录结构。本步分先后两段：先完成全部规划，再一次性落盘所有会被多个后续任务共同引用或修改的结构文件；禁止边实现边定结构。
-
-第一段，规划内容：
-
-- 前端目录结构：pages、页面内组件、跨页面公共组件、hooks/api/types/utils 的文件归属，明确入口页文件位置；
-- 路由与导航结构：源稿每个页面一条路由，加上 2.3 记录的新增页面（路径语义化，不用查询参数冒充路由）、默认页、Layout 承载方式与菜单入口；
-- 服务端模块边界：按 2.1 的业务域确定各模块的目录与内部文件结构；
-
-第二段，落盘结构文件——**只落结构，不写任何源稿可见内容**：
-
-- 全局路由配置与默认页；
-- Layout 容器：只搭出页面容器与内容插槽，**不写导航项、logo、搜索框、按钮文案与色值**（这些属于 3.4）；
-- 占位页面：为源稿每个页面与 2.3 记录的新增页面创建最小可渲染的占位页并接入路由，路由挂载不得引用不存在的页面；页面真实内容由第 4 步实现；
-- shared 契约类型：按 2.2 表结构与 2.3 接口设计，定义实体类型和各接口的请求/响应类型；
-- 服务端模块注册骨架：每个业务域一个空 Module + 空 Service/Controller 类，**类体保持为空**——不写任何方法、查询或业务逻辑，这些属于第 4 步域任务。
-
-规则：
-
-- 提交时工程可编译运行，禁止引用后续任务才会创建的页面或模块；
-- 完成后对照源稿检查：每个页面都有路由与目录归属、每个业务域都有模块边界与契约类型，发现缺失在本步补齐；
-
-**3.2 建表（主 Agent）**。按 `docs/business-design.md` 2.2 确定的建表顺序逐张建表，被引用的表先建。表结构取自 2.2 设计，不涉及源稿内容誊写。只建 2.2 建模的表——不参与服务端逻辑的展示数据没有对应表，保留在前端代码中。建完后跑数据库 schema 代码生成刷新 `server/database/schema.ts`：它是真实列名与类型的唯一来源，3.3 的 Worker 无法查库，只能靠这个文件。
-
-**3.3 初始数据插入（派 CodeAct）**。数据内容必须由读到源稿原文的执行者当场写入，读源与写库之间不经过任何交接。
-
-派发对象：`CodeAct`——它同时具备读文件与执行 SQL 的能力，读完源稿即可落库，报错时源稿仍在上下文中可直接改正。
-
-**派发内容**：本次负责的表清单、每张表在 2.2 的源稿位置标注、建表顺序、`server/database/schema.ts` 的路径。
-
-**任务要求**：
-
-- 按标注打开源稿文件、定位到该区块后再写；区块落在文件后段时读到该区块为止，禁止只凭文件开头写数据；
-- 列名与类型照 `server/database/schema.ts`；`_` 前缀的系统字段与主键不写，由数据库默认值生成；
-- 字段值逐字原样来自读到的源稿原文，**这是誊写不是创作**：不改写措辞、不缩写字段值、不换算数值、不增删记录、不补充源稿没有的条目；
-- 源稿里属于该表的可见记录全部写入，一条不漏；同一实体在多个页面出现时按标识字段去重、合并各页可见字段，不重复插入；
-- 子表外键用 `SELECT` 子查询按业务键（标题、名称等）关联父行，禁止硬编码 UUID。
-
-**权限边界**：只允许对 2.2 建模的表执行 `INSERT` 与必要的 `SELECT`。出现 `DDL` / `UPDATE` / `DELETE`、或写入 2.2 未建模的表，均为越界。
-
-达标标准：每张表在源稿页面上可见的记录，首次查询即可返回且内容与源稿一致。禁止把初始数据做成运行时 mock 接口或前端写死。
-
-**3.4 共享视觉文件（派发 Worker，域任务之前串行完成）**。导航、页脚、主题色板承载源稿可见内容，且被所有页面引用，必须由单一 Worker 一次写完，禁止主 Agent 代写、禁止拆给多个域任务并行写。
-
-派发时给出源稿共享组件文件与设计 token 文件的位置，由 Worker 自行读取。任务范围：
-
-- 导航：项数、文案、顺序、logo 形态、搜索框、操作区按钮全部照源稿组件转写；链接先读既定路由文件，只指向已注册路由，无承载页面的项保持不可跳转；
-- 页脚：源稿有页脚的页面共用同一个页脚组件，分栏、项数、文案照抄；
-- 主题文件：源稿设计 token 的色值、字体逐条写入，色值原样，不做近似换算或色彩空间转换。
-
-回传后主 Agent 打开源稿对应位置核对导航项数、文案、顺序与主题色值，不一致立刻退回重做；核对通过后，第 4 步各域页面直接复用这些组件与主题变量，不再逐页另行实现。
-
-**3.5 插件实例（条件步骤，2.4 有产出时执行；主 Agent）**。按 2.4 清单逐个建实例并确认契约，调用代码由第 4 步域任务实现：
-
-1. 调用 `plugin_instance` 工具创建插件实例；禁止手工修改 `server/capabilities/` 目录；
-2. 获取运行时 schema，逐字段确认 inputSchema 与 outputSchema 的字段名、类型、是否必填；
-3. 把实例名与 schema 摘要（字段名、类型、必填）写进该插件所属域的派发指令，供域任务按 schema 编写调用代码。
-
-规则：
-
-- 禁止只创建实例而不在域任务中安排调用代码——未生成调用代码的插件实例是无效的；
-- 域任务编写调用代码时，入参出参的字段名与类型以运行时 schema 为准，禁止从设计文档推测（设计可能与插件实际 schema 不一致）；入参中的动态配置值（接收人、通知模板、阈值等）禁止硬编码，从配置表或平台 API 获取；
-- 插件结果需要持久化时，优先在该域 Service 内调用插件并在同一方法内落库；保持前端调用的，成功后通过已有业务 CRUD 接口保存结果，不为此单独新建 API；
-- 后续任一阶段发现缺插件实例，主 Agent 立即用 `plugin_instance` 工具补建，禁止用 pluginKey 冒充 instanceId 调用或跳过该功能。
-
-### 第 4 步：按业务域派发实现（Worker）
-
-按「业务模块闭环拆解规则」把每个业务域派发为一个 Worker 任务。派发前重读 `docs/business-design.md`，按其中的业务域划分逐域生成任务。
-
-**核心原则**
-
-- 任务范围是该域的前后端完整实现：Service、Controller、页面、组件、接口集成都在同一个任务内；
-- 服务端代码不得摘出来由主 Agent 代写——Worker 跑不了接口测试与运行时日志是预期的，运行时验证统一在第 5 步做；
-- **派发指令不写源稿的具体内容**: 避免实现时没有按照原稿而是按照指令开发。
-
-**每个任务必须携带**：
-
-- 权威文件位置：该域相关的源稿文件、`docs/business-design.md`、该域的 shared 契约文件与既定路由文件——只给路径，禁止用文字概述替代源文件，由 Worker 自行读取；
-- 双权威声明：视觉、文案、布局、数据以源稿源码为唯一权威；表结构、API、插件调用以 `docs/business-design.md` 该域章节为准；
-- 一句话验收标准（acceptance），落在真实能力层（如「提交后经真实接口落库且刷新后可回查」），达标即完成，禁止超出标准的冗余自查。
-
-**任务内执行顺序**
-
-1. 读取 coding-guide 及与本域相关的 skill；
-2. 读源稿该域文件，读 `docs/business-design.md` 该域章节（功能清单、表结构、API 清单）；
-3. 检查 shared 契约与该域表结构、接口设计一致；按 3.1 既定的目录结构落文件，不另建与之平行的目录；
-4. Service 层：业务编排、落库、插件调用聚合、内置服务调用；服务端调用的插件逐条写明「调用 [实例名]，触发条件为 [条件]」；
-5. Controller 层：REST API，按该域 API 清单逐接口实现，避免纯透传接口；
-6. 页面接入既定路由，不改全局结构；
-7. 页面与组件实现：打开源稿对应区段对照实现，文案、色值、条目数量与顺序、示例值照源码转写；页面数据一律来自本域真实接口，禁止 mock 业务数据；组件不拆出独立任务；
-8. 前端插件集成（2.4 设计为前端调用的插件）：获取插件运行时 schema，按 schema 调用 [实例名]；结果需持久化的，调用成功后通过已有业务接口保存；
-9. 代码级自查：类型一致性、契约覆盖、shared 定义对齐；禁止运行时验证（见拆解规则第 7 条）。
-
-指令里给出的文件路径是**必读下限，不是可读上限**：实现中需要的其他工程文件（既有组件、工具函数、全局配置、路由表）一律按需自行读取。禁止的是重新推导架构：不重新规划目录与路由结构、不反复 glob 全工程、不修改允许范围外的文件。
-
-Worker 回传后，主 Agent 至少读一个关键产物文件抽查（页面是否调真实 API、功能链路是否接通）；回传中的「已完成、已验证」不作为核验依据。
-
-**自动化任务**：2.3 中选型为平台自动化内置服务的功能（定时触发、数据变更触发），作为独立任务实现，依赖其用到的表与插件：
-
-1. 读取 trigger-guide skill 了解触发器配置与代码开发规范；
-2. 创建触发器，实现任务逻辑：触发条件判断、去重、插件调用、状态更新；
-3. 完成后验证代码可编译。
-
-
-### 第 5 步：验收（清单里的任务，不是可选动作）
-
-commit 的静态检查只覆盖编译与 lint，证明不了功能可用与视觉一致。验收开始前先读取 testing-guide skill 了解 E2E 验收流程，并重读 `docs/business-design.md`，以其中的 2.3 功能与 API 清单为验收目标来源。按以下结构执行，完成前不得提交收尾：
-
-1. **架构与入口检查**：先对照 3.1 检查路由、shared 契约、模块边界是否被遵守，对照 3.4 检查导航、页脚、主题色值是否与源稿一致，发现偏离先修结构再继续。再做三项核对：
-   - **链接目标可达**：枚举代码中全部跳转目标（导航项、按钮、卡片、搜索、面包屑）与路由表比对，任一指向未注册路由即未通过；
-   - **页面均有入口**：每个已注册页面至少有一个应用内可达入口，只能手输 URL 到达的页面即未通过；
-   - 应用入口页面可正常打开，打不开（白屏 / Page not found）则停止验收，只记录阻塞问题。
-2. **核心验收目标 1~3 个**（超过 3 个属于错误输出）：从 2.3 的功能映射中选取最核心的业务链路，每个目标写成「验收对象 —— 可判定的通过标准」。通过标准必须是应用内可判定的结果：状态更新、提交后列表刷新、成功/失败提示、结果区出现内容或错误态、确认弹窗、详情数据变化；「页面渲染正常」「控件可见」「按钮可点击」不构成通过标准。派发 E2E agent 实际执行这些目标。
-3. **非核心降级范围**：AI 内容质量、真实消息送达、复杂批量数据一致性、导出文件内容正确性、低风险视觉细节可降级不阻塞；但被降级能力在应用内的触发、状态与错误反馈仍必须保留在核心验收目标中，不得完全消失。
-4. **数据核对**：对每张初始数据表做 COUNT 与文案抽查，与源稿对照；条数或文案不符即为未通过。
-5. **静态残留检查**：grep 两类问题，任一命中即未通过——
-   - 假实现：simulate、写死结果的 setTimeout、picsum、假 toast、Math.random 业务值；
-   - 无行为的可点击元素：按钮与带可点击外观的元素是否都有事件处理或路由跳转。
-6. **验收对照表**：把以上结果逐项列出后再提交。未执行的项写明原因，不得笼统声称"验收通过"。
-7. **摘除注入标记**：以上各项全部通过后执行 `rm -f source_package/creative/.upgrade-manifest.json`。该文件是本指引的 SessionStart 注入门控，删除后本指引停止注入，后续迭代不再重复进入升级流程；源稿其余文件保留供以后对照。任一项未通过时不得删除——下轮修复仍需本指引在场。
-
-## 业务模块闭环拆解规则
-
-按业务域（Module）拆分实现任务，每个任务同时覆盖该域的服务端实现（Service + Controller + DTO）与对应前端页面（路由 + 页面 + 组件 + 接口集成），命名为 `[业务模块名]模块开发（含前后端）`。**同一业务域的前后端禁止拆成独立任务**。与通用全栈开发的唯一差异：拆解依据是**创意模式的源稿代码**（页面结构与可见交互组件），而非需求文档。
-
-1. **模块边界判定**：任务拆分优先服从代码所有权边界，而非仅按页面归属或功能语义拆分。若多个页面、功能最终落在同一个 server module 中实现，必须合并为同一个模块任务，不得拆成多个并行任务。
-2. **server module 判定口径**：同一个 server module 包括但不限于同一业务目录下的 Service、Controller、DTO、Repository、模块注册文件、聚合导出文件，以及需要共同修改的 shared 契约文件。
-3. **纯展示/即时场景**：若某业务功能已规划在前端使用插件实现，且不需要数据库存储，则该模块任务中无需包含服务端 Service/Controller 子步骤，仅保留前端 + 插件集成。
-4. **需持久化场景**：若插件调用的结果需要保存到数据库，优先在该模块的 Service 中调用插件并落库；或在已有业务 CRUD 接口中扩展字段接收前端传来的插件结果。禁止为"保存插件结果"单独新建模块。
-5. **平台内置服务**：模块内需使用的平台内置服务，在该模块的 Service 部分完成配置与调用。
-6. **入口模块优先**：将承载入口页（列表页/首页）的模块任务置于全部模块任务的第一项。
-7. **并行安全**：模块任务内**禁止包含运行时验证**（接口冒烟测试、启动前后端服务联调、读取服务端/前端运行时错误日志、E2E 测试），统一推迟到第 5 步验收阶段。允许保留的验证限定为代码级静态自查（类型一致性、契约覆盖、shared 定义对齐）。
-8. **精确依赖**：每个模块任务只依赖基建（结构骨架 + 共享视觉文件 + 自身所需的表与初始数据 + 插件实例）；模块任务之间无数据依赖时全部可并行，禁止链式依赖。
-9. **粒度保底**：单个模块子步骤明显超限时，允许拆为 `[模块名]服务端开发` + `[模块名]前端开发` 两个任务，前端任务依赖同模块服务端任务，仅此一种拆法。
-
-## 视觉一致性规则（全程适用）
-
-- 布局用 flex/grid 加 gap 直接转写源稿结构，不重新设计。
-- 页面一切可见内容（文案、数值与单位、条目数量与顺序、色值、字符图标、选中状态、素材）与源稿逐字段一致：入库的经初始数据与接口到达页面，前端的直接从源稿代码复制。
-- 字符图标保持原字符；源稿已有的图片、SVG、CSS 渐变复用或等价转写，不得用生成图替换。
-- 写任何产生页面可见内容的代码之前，重新打开源稿对应位置读取。
-- 确有必要的转换（如固定画布改响应式）需说明转换前后形态，且不改变源稿参考尺寸下的构图。
-
-## 功能真实性规则（全程适用）
-
-- 写操作必须走完「前端事件 → 接口 → 数据库/插件 → 界面反馈」全链路，写入结果刷新后仍能读到。
-- 搜索、筛选、排序、分页的参数必须传入真实查询；跳转、Tab、弹窗到达正确的路由或状态。
-- **链接目标必须存在**：写任何跳转前先读既定路由文件，目标只能是已注册路由。源稿有入口但应用内无承载页面时，只有两条出路——回到 2.3 的功能记录里补上新增页面并在 3.1 注册路由后实现，或让该元素保持不可跳转；禁止指向未注册路由。
-- 持久化业务结果由服务端校验前提并写入，前端只展示重新读取的事实。
-- 有数据库时禁止用 mock 数据代替真实查询；插件返回值严禁 mock，前端用 capabilityClient 真实调用，或调用集成了插件的真实服务端接口。
-- 自建 HTTP API 不实现 SSE/WebSocket；插件链路的流式输出（outputMode=stream）不受此限。
-- **可点击外观与真实行为必须同时存在**：转写源稿的按钮与可点击元素时，能用 2.3 已设计的接口或既定路由接上的直接接上；接不上的改成非交互形态——去掉指针手型与按钮态、或呈现禁用态，并在回传中列出这些元素与接不上的原因，由主 Agent 决定是否回到 2.3 补设计。禁止保留看起来能点、点了没反应的元素。
-- 禁止：空链接、只切换图标不产生数据变化、写死的"成功"提示。
+1. **真实操作核心链路**：验收从应用首页或正常业务起点开始，通过用户可见的导航、按钮或业务操作到达目标页面，记录入口操作与到达结果。同一核心链路连续使用同一对象；包含创建时，将新建结果用于后续操作。一次执行核对必要输入的保存与回读、关键状态变化、真实结果及关联动态输出，并完成刷新或跨页回读。
+2. **完整视觉**：覆盖全部源稿页面，逐页确认主要布局、内容、图表、导航与图片；允许动态数值和无影响的小图标差异。
+3. **针对性修复**：先看失败步骤的请求、ID、状态及相关代码，结合源事实区分应用缺陷、测试假设错误与平台问题；只修核心功能问题或实质视觉问题，不新增身份/权限体系或源稿外业务。已有平台与 coding-guide 约束仍须满足。应用或测试修正、平台恢复后定向复测受影响链路；提交自动修复改变关键行为后也须复测。同一结果复用证据，不重复整套无关验收。不以关键词命中或同名组件一概判错，不搞全库对账。
+4. **如实交付**：清单逐项记录通过/失败/未测和证据，复测保留各核心功能的实际验收状态，披露核心阻塞。核心功能和视觉验收全部通过后宣称完成，并移除 `source_package/creative/.upgrade-manifest.json` 停止重复注入；其他源稿保留。存在失败或未测项时保留标记与证据，如实交付当前状态。

package/miaoda/feishu/SKILL.md

@@ -143,14 +143,14 @@ npm install @larksuiteoapi/node-sdk
 
 ### FeishuService 单例
 
-> ⚠️ **凭证写入源码**：全栈框架不支持自定义环境变量，因此 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须直接写在源码常量中，**不要改为 `process.env`**。
+> ⚠️ **凭证直接写入源码常量**：妙搭全栈当前不提供这类飞书自建应用凭证的运行时环境变量注入。用户提供真实的 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 后，直接写入 `FeishuService` 源码常量；不要把它们称为环境变量，也不要改成 `process.env`。在用户提供凭证前，不生成真实值或占位值。
 
 ```typescript
 import { Injectable } from '@nestjs/common';
 import * as lark from '@larksuiteoapi/node-sdk';
 
-const FEISHU_APP_ID = 'cli_xxxx';      // ← 用户提供的真实值
-const FEISHU_APP_SECRET = 'xxxx';      // ← 用户提供的真实值
+const FEISHU_APP_ID = '用户提供的真实 App ID';
+const FEISHU_APP_SECRET = '用户提供的真实 App Secret';
 
 @Injectable()
 export class FeishuService {
@@ -258,7 +258,7 @@ for await (const items of await client.contact.user.listWithIterator({
 
 | 错误 | 正确做法 |
 |------|----------|
-| 将凭证改为 process.env 读取 | 全栈框架不支持自定义环境变量，凭证必须写入源码常量 |
+| 把凭证称为环境变量或改用 `process.env` | 按当前全栈平台契约，在用户提供真实凭证后写入 `FeishuService` 源码常量；未提供前不要生成代码中的凭证值 |
 | `content` 传对象而非 JSON 字符串 | `content: JSON.stringify({ text: 'hello' })` |
 | 每次请求都新建 `lark.Client` | NestJS `@Injectable()` 单例模式复用 |
 | `receive_id_type` 与 ID 前缀不匹配 | `oc_` → `chat_id`, `ou_` → `open_id`, `on_` → `union_id` |

package/miaoda/forms-skill/SKILL.md

@@ -13,6 +13,7 @@ Shadcn Form + React Hook Form + Zod 表单开发。
 - 所有字段必须有默认值
 - 必须用 Shadcn 组件，禁止原生 input
 - 同行 FormField 必须等宽
+- 表单提交到必填 API/DTO/Request/interface 前，先读目标 shared/server 类型，在 `handleSubmit` 回调里用 `data` 逐字段构造 typed request（见 Patterns）；不要整体传 `data`、`schema.parse(data)` 或 `.required().parse(data)`，也不要用 `any`/`as` 绕过 TS2322。修完后跑 LSP 或 `typecheck`。
 
 ---
 
@@ -100,6 +101,14 @@ const form = useForm<FormData>({ resolver: zodResolver(schema), defaultValues: {
 // 必填标记
 <FormLabel>字段 <span className="text-destructive">*</span></FormLabel>
 
+// 必填 Request/DTO 桥接：zodResolver 负责运行时校验，DTO 边界负责静态类型匹配。
+// 用 handleSubmit 回调的 data，不要用 getValues（拿到的是 coerce 前的原始值）。
+import type { SaveRequest } from "@/shared/api";
+form.handleSubmit(async (data) => {
+  const request: SaveRequest = { field: data.field };
+  await api.save(request);
+});
+
 // 调试
 logger.info("errors:", form.formState.errors);
 ```

package/miaoda/lark-apps-db/SKILL.md

@@ -64,8 +64,9 @@ gate-tools:
 | 规则 | 要求 |
 |---|---|
 | SQL 执行通道 | 只用 `+db-execute`，不要裸连数据库或调用其它 SQL 工具 |
-| 查结构只认 DB | 表结构 / 字段 / 索引 / 约束一律 `+db-table-list` / `+db-table-get --table <table>`。`server/database/schema.ts` 只在写 TS 代码对齐类型时读，**不能用来回答结构问题**——它是生成产物，可能滞后于 DB |
-| `schema.ts` 禁止手改 | DB 结构不对就改 DDL 后重跑 codegen；DB 正确但 `schema.ts` 渲染错误时同样不手改，向用户说明是 codegen bug |
+| 查结构只认 DB | 表结构 / 字段 / 索引 / 约束一律 `+db-table-list` / `+db-table-get --table <table>`。`server/database/schema.ts` 只在写 TS 代码对齐类型时读，**不能用来回答结构问题**——它是生成产物，除了可能滞后于 DB，还会静默丢掉条件索引的 `WHERE` 和 CHECK 约束（丢掉 WHERE 后，部分唯一索引在 `schema.ts` 里读起来是全表唯一） |
+| `schema.ts` 禁止手改 | `schema.ts` 是 `npm run gen:db-schema` 的生成产物。DB 结构不对就改 DDL 后重跑 `npm run gen:db-schema`；DB 正确但 `schema.ts` 渲染错误时同样不手改，向用户说明是 schema 生成器 bug |
+| DDL 后刷新 `schema.ts` | `+db-execute` **不会**自动刷新 `schema.ts`。每次 DDL 成功后立即在应用工程根目录执行 `npm run gen:db-schema`，再写引用新表 / 新列的 TS 代码 |
 | 变更历史只认 DB | 结构变更历史用 `+db-changelog-list`。`git log -- server/database/schema.ts` 只是代码侧痕迹，**不等价**，不能用来回答"做过哪些 DDL 改动" |
 | 要数据就查库 | 用户要的是查询结果本身（计数 / 明细 / 统计）时，直接 `+db-execute` 查完把结果给用户；**不要为一次性查询去新增接口或 service 代码** |
 | DDL 原子性 | CREATE TABLE + RLS + policy + COMMENT + INDEX 放在一次 `--sql` 调用；需要全回滚时显式 `BEGIN; ... COMMIT;` |
@@ -131,6 +132,7 @@ CREATE POLICY "修改本人数据" ON <table>
 4. CREATE TABLE / CREATE INDEX / ALTER TABLE ADD COLUMN 必须带 `IF NOT EXISTS`，避免重复执行失败。
 5. 执行前向用户展示目标对象和变更内容；DROP / DROP COLUMN 还要说明数据丢失风险并取得明确授权。
 6. 执行：`lark-cli apps +db-execute --app-id "$app_id" --sql "<ddl>" --yes`。多条 DDL 是一个逻辑单元时放在一次调用；需要全回滚则显式包事务。
+7. DDL 成功后**立即**在应用工程根目录执行 `npm run gen:db-schema` 刷新 `server/database/schema.ts`——`+db-execute` 不会自动刷新。多批 DDL 每批成功后都跑一次。
 
 ### DDL Do / Don't
 
@@ -176,12 +178,12 @@ CREATE POLICY "修改本人数据" ON <table>
 |---|---|
 | 数量 | 新建表默认插 3-6 条（除非用户明确不要）；现有表仅用户要求时造数据；要求更多时单表最多 20 条，再多走 `+db-data-import` |
 | 字段一致性 | 页面 / 业务会读的同表字段必须都在 SQL mock 中提供，禁止一半 DB 一半代码拼 |
-| user_id 来源 | 上下文明确 user_id > `env.userId` / `env.user.id` > 测试用户列表；禁止编造 |
+| user_id 来源 | 上下文明确 user_id > `env.userId` / `env.user.id` > 测试用户列表；禁止编造。外发字段（通知/发送/提醒/审批/群发/消息收件人，或传给飞书/邮件/IM/审批服务）禁止用测试用户列表或测试用户 `COALESCE`/默认/兜底；只用登录用户、用户明确 @ 或提供的可达对象。无可达对象时，留空收件人，或把样例状态设为 `pending`/`disabled`/仅展示。 |
 | 图片 URL | 写入数据库的任何图片字段，包括 JSONB 内嵌图片，都按“用户上传图 -> 历史语义匹配图 -> `generate_image`”顺序处理；只有工具失败才用带 seed 的 Picsum 兜底 |
 | 关联 | 外键 / 子查询引用的数据必须已存在；UUID 字段不用手写 |
 | 审计列 | `_created_at` / `_updated_at` 可省略；需要归属时显式写 `_created_by` / `_updated_by` |
 
-测试用户（**只用于数据库 `user_profile` 列**）：`1847292357012580` 张伟、`1847292986161210` 李明、`1838411738368010` 刘洋、`1847292458018820` 赵丽、`1847286122258458` 孙强、`1846114399229988` John Smith、`1847298549409911` Emma Johnson、`1847291727560708` Michael Brown、`1848568929333380` Robert Wilson、`1847751107397639` Maria Garcia。
+测试用户（**仅用于数据库 `user_profile` 展示/筛选样例**）：`1847292357012580` 张伟、`1847292986161210` 李明、`1838411738368010` 刘洋、`1847292458018820` 赵丽、`1847286122258458` 孙强、`1846114399229988` John Smith、`1847298549409911` Emma Johnson、`1847291727560708` Michael Brown、`1848568929333380` Robert Wilson、`1847751107397639` Maria Garcia。
 
 > ⚠️ 这些是妙搭数字 user_id，**不是飞书 open_id**：禁止传给 `+role-member-add/remove` 的 `--users`（只收 `ou_`）或任何要 open_id 的飞书接口。
 

package/miaoda/lark-apps-db/references/full-reference.md

@@ -403,11 +403,20 @@ $$;
 
 JSONB 图片字段同样适用：只要 `@type` 中包含 `image` / `cover_url` / `avatar` / `gallery` / `images` / `photos` 等图片地址语义，就不能跳过 `generate_image`。
 
-## `schema.ts` Codegen Split
+## `schema.ts` 生成与刷新（`npm run gen:db-schema`）
 
-`server/database/schema.ts` 是 DB 元数据生成产物，只能只读辅助确认结构，禁止手改。
+`server/database/schema.ts` 是 DB 元数据生成产物，只能只读辅助确认结构，禁止手改。唯一的刷新方式是在应用工程根目录执行工程自带的 npm script：
+
+```bash
+npm run gen:db-schema
+```
+
+该 script 反查 DB 元数据重写 `schema.ts`（当前模板背后是 `@lark-apaas/db-schema-sync`，早期应用是 `fullstack-cli gen-db-schema`）。**认这个 script 名，不要自己去调背后的包或猜别的命令。**
+
+`lark-cli apps +db-execute` **只执行 SQL，不碰工程文件**：DDL 成功后不会自动刷新 `schema.ts`。每次 DDL（含分批执行的每一批）成功后都要立即手动跑一次，再写引用新表 / 新列的 TS 代码，否则类型检查会报找不到表 / 列。
 
 | 现象 | 处理 |
 |---|---|
-| DB 结构、默认值、类型或约束不对 | 改 DDL 后重跑 codegen，让 `schema.ts` 跟随真源刷新 |
-| DB 正确但 `schema.ts` 展示错误 | 视为 codegen 渲染 bug；不要手改产物，说明平台侧需修复 |
+| DB 结构、默认值、类型或约束不对 | 改 DDL 后重跑 `npm run gen:db-schema`，让 `schema.ts` 跟随真源刷新 |
+| `schema.ts` 缺新建的表 / 列 | DDL 后漏跑了 `npm run gen:db-schema`，补跑一次 |
+| DB 正确但 `schema.ts` 展示错误 | 视为 schema 生成器渲染 bug；不要手改产物，说明平台侧需修复 |

package/miaoda/lark-apps-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-apps-ops
-description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, +release-, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、导出应用源码为 zip（+export）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 导出源码, 源码快照, 下载源码, zip, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, +release-, +export, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -37,6 +37,7 @@ control-by-feature-ab: true
 | 本地开发：改代码、调试数据库（仅全栈应用有数据库）、提交推送（源码已在工作区），再走发布链路上线。**执行前必读**，含部署流程和领域规则 | 原生 `git`（提交推送）+ 下方发布链路 | [local-dev](references/lark-apps-local-dev.md) |
 | **部署/上线应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）、`+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）、`+release-list` | [release-create](references/lark-apps-release-create.md)、[release-get](references/lark-apps-release-get.md)、[release-list](references/lark-apps-release-list.md) |
 | 管理应用环境变量（查看/设置/删除） | `+env-list`、`+env-set`、`+env-delete` | [env](references/lark-apps-env.md) |
+| 导出应用源码为 zip（要一份源码快照：读代码/审计/归档/静态分析；或取**别人分享给你的**创意应用源码，你对其仓库无权限）。仅取快照、不继续开发 | `+export`（下载 zip，只读；`--app-id` 与 `--meta-token` 恰传其一） | [export](references/lark-apps-export.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`、`+log-get`、`+trace-list`、`+trace-get`、`+metric-list`、`+analytics-list` | [observability](references/lark-apps-observability.md) |
 | 应用数据库：看表/改表、执行 SQL、导入导出、多环境发布、审计、时间点恢复、DB 用量 | `+db-*` 命令族 | **→ [lark-apps-db](../lark-apps-db/SKILL.md)** |
 | 应用文件存储：上传/下载/列出/删除文件、临时分享链接、存储用量 | `+file-*` 命令族 | **→ [lark-apps-file](../lark-apps-file/SKILL.md)** |

package/miaoda/lark-apps-ops/references/lark-apps-export.md

@@ -0,0 +1,46 @@
+# apps +export
+
+把妙搭应用的源码打成 zip 下载到本地。运行时命令事实以 `lark-cli apps +export --help` 为准。只读操作。
+
+## 何时用
+
+只要一份源码快照的场景：读代码、审计、归档、做静态分析、把源码喂给别的工具。
+
+**跨应用是它的核心价值**：创意应用的分享链接（`/page/<token>`）指向别人的应用，你对那个仓库没有权限，`git clone` 走不通；`+export` 只要求你对该应用有下载权限。
+
+## 不要用它的时候
+
+当前应用要继续开发时不用它——当前应用源码通常已在工作区，直接改。`+export` 只给一个 zip：无 git 历史、无远端、无凭证、不拉环境变量，改完发不回去，只适合「拿一份只读快照」。
+
+## 导出的是「最后一次提交」，不是沙箱当前状态
+
+服务端对远端仓库跑 `git archive`，从不读沙箱文件系统。沙箱里改了文件但没提交或发布，**那些改动不在归档里**。若导出结果看起来"少了刚写的代码"，先确认改动是否已提交，而不是重试导出。
+
+## 命令骨架
+
+- `--app-id` 与 `--meta-token` **恰传其一**：前者是应用 ID（`$app_id`），后者是分享链接 `/page/<token>` 里的 token。两者作为独立字段走 `POST /apps/export`（`app_id` / `meta_token`），服务端按传入字段区分。
+- 两者都只收**裸标识符**。拿到的是整条链接（`.../app/<app_id>` 或 `.../page/<token>`）时只传最后一段——整条 URL 传进来会被本地拦下并提示，不会变成看起来像"应用不存在"的 404。
+- `--output` 可选，相对当前目录；省略时用服务端给的文件名（通常 `<app_id>.zip`）。
+
+## 示例
+
+```bash
+lark-cli apps +export --app-id "$app_id" --output ./src.zip
+lark-cli apps +export --app-id "$app_id"                     # 存成 ./<app_id>.zip
+lark-cli apps +export --meta-token <share-token>             # 别人分享给你的应用
+lark-cli apps +export --app-id "$app_id" --dry-run
+```
+
+## 输出契约
+
+- 成功时 stdout 是 JSON envelope，含 `output`（落盘的绝对路径）与 `size_bytes`；传了 `--app-id` 时还会回显 `app_id`。
+- 归档以流式写盘，不会整包驻留内存，大仓库也安全。
+- 失败时不会留下半个文件。
+
+## 错误处理
+
+| 情况 | 怎么办 |
+|---|---|
+| 应用尚未发布（`code 40901 app not published`） | 该应用是产物托管形态（如静态 HTML 应用），导出的是「最新已发布产物」，而它还没有成功发布过版本，此刻没有可导的东西。**先发布应用再重试**——不是 app_id 写错，重试也没用 |
+| 权限不足（403） | 需要该应用的下载权限。**持有分享 token 不等于有权限** |
+| 应用不存在（404） | 核对 `--app-id` / `--meta-token` 传的是不是对应的裸标识符（不是整条 URL） |