@lovrabet/lovrabet-cli 2.1.23 → 2.2.0

package/skills/lovrabet/references/dataset-discovery-workflow.md

@@ -0,0 +1,160 @@
+# Dataset Discovery Workflow
+
+## 概述
+
+在执行 Instant API 数据操作前，需要先找到目标数据集并了解其字段结构。
+
+## 先不要默认查 app
+
+`dataset` 工作流的第一步不是固定的 `app list`，而是先判断当前是否已经有明确 app 上下文。
+
+### 直接进入数据集发现
+
+以下情况可以直接执行 `dataset list`：
+
+- 用户已经给了 `--appcode`
+- 用户已经给了 `--app <name>`
+- 当前问题明显是在上文已确认的同一 app 里继续操作
+- 用户明确说“当前应用”“默认应用”，且没有新的业务域线索
+
+`defaultApp` 只是默认候选。用户提到订单、商品、库存、客户、证照等业务对象且未显式指定 app 时，先在默认候选里按关键词查数据集；命中合理再继续，无命中或不合理再扩大到 app 目录。
+
+### 需要先做应用决议
+
+以下情况应先获取应用信息，再决定目标 app：
+
+- 用户只说了业务需求，没有给 app 线索
+- 当前没有显式 `--appcode` / `--app`，且需求包含业务域或数据对象线索
+- 需求描述可能对应多个业务应用
+- 已经在 `defaultApp` 下按关键词验证过，但没有合理数据集命中
+
+若当前有 `defaultApp`，推荐先执行：
+
+```bash
+lovrabet dataset list --name "<关键词>"
+```
+
+默认候选无命中、弱命中或语义不合理时，再执行：
+
+```bash
+lovrabet app list
+```
+
+再根据业务关键词挑 1-2 个候选应用，执行：
+
+```bash
+lovrabet dataset list --app <name> --name "<关键词>"
+```
+
+通过数据集命中结果反向确认 app，而不是只看 app 名称猜测。
+
+## 命令
+
+### api-doc list/detail — 查看运行态 API 文档
+
+写 personal BFF 或复杂数据访问说明前，先用 API 文档收敛可用接口：
+
+```bash
+lovrabet api-doc list --category dataset
+lovrabet api-doc list --keyword aggregate
+lovrabet api-doc detail --code dataset_data_filter
+```
+
+`api-doc` 是只读文档发现命令，不是通用 HTTP fetch；不要把它替代成任意路径调用。
+
+### dataset list — 列出数据集
+
+```bash
+# 列出全部
+lovrabet dataset list
+
+# 按名称过滤（服务端模糊匹配）
+lovrabet dataset list --name "订单"
+
+# 按 code 过滤（服务端精确匹配）
+lovrabet dataset list --code "abc123def4567890abcdef012345678"
+
+# JSON 格式输出（AI Agent 推荐）
+lovrabet dataset list --format json
+```
+
+返回字段: id, code, name, source, description, table, datasetKey, pk, **fields**
+
+其中 `fields` 是从 `dbtableConfig.allFields` 解析出的字段名数组，可直接用于构造 `data filter` 的 `select` 和 `where` 参数，无需再调 `dataset detail`。
+
+| Flag | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--name` | string | 否 | 按名称模糊过滤（服务端） |
+| `--code` | string | 否 | 按 dataset code 精确过滤（服务端，32 位 hex） |
+| `--format` | string | 否 | 输出格式：`json` / `pretty` / `table` |
+
+### dataset detail — 查看数据集结构
+
+```bash
+lovrabet dataset detail --code <datasetCode>
+
+# 返回 CLI 归一化 JSON 结构
+lovrabet dataset detail --code <datasetCode> --format json
+```
+
+| Flag | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--code` | string | **是** | 数据集 code（32 位 hex UUID） |
+| `--format` | string | 否 | 输出格式：`json` / `pretty` / `compress` |
+
+返回内容:
+- **字段列表** — name, displayName, type, dbType, pk, required, description, options
+- **关联信息** — `relations` 直接透出接口返回的原始关联信息；结构以服务端返回为准，CLI 不做补全推断
+- **操作列表** — name, method, path（getList, getOne, create, update, delete 等）
+- **统计** — fieldCount, operationCount
+
+当运行态详情接口未返回 `fields` / `properties` 时，CLI 会从 `dataset list` 兜底字段名，保证 `fieldCount` 和字段名可用于 `data filter`；此时类型、必填、选项等详细字段属性可能为空。
+
+### dataset sdk-doc — 查看 SDK 使用文档
+
+```bash
+lovrabet dataset sdk-doc --code <datasetCode>
+```
+
+`dataset sdk-doc` 只接受 32 位数据集 code，不接受数字 ID。返回为空时，CLI 会给出稳定的空文档提示。
+
+## 典型工作流
+
+```bash
+# 0. 如果默认候选验证不成立，再看应用目录
+lovrabet app list
+
+# 1. 在候选 app 中搜索数据集
+lovrabet dataset list --app crm --name "公司"
+
+# 2. 命中后查看字段结构
+lovrabet dataset detail --code 2874b19935c240659e8872e9e2416ae3
+
+# 3. 确认字段名后，开始 Instant API 数据操作
+lovrabet data filter --code 2874b19935c240659e8872e9e2416ae3 \
+  --params '{"where":{"name":{"$contain":"test"}},"currentPage":1,"pageSize":20}'
+```
+
+如果当前 app 已明确，则直接：
+
+```bash
+# 1. 搜索数据集
+lovrabet dataset list --name "公司"
+
+# 2. list 已返回 fields 数组，可直接用于构造查询
+#    如果需要字段类型等详细信息，再调 detail
+lovrabet dataset detail --code 2874b19935c240659e8872e9e2416ae3
+
+# 3. 确认字段名后，开始 Instant API 数据操作
+lovrabet data filter --code 2874b19935c240659e8872e9e2416ae3 \
+  --params '{"where":{"name":{"$contain":"test"}},"currentPage":1,"pageSize":20}'
+```
+
+## 注意事项
+
+1. 使用 `--format json` 获取结构化输出，便于程序解析
+2. `dataset list` 返回的 `fields` 数组包含所有字段名，多数场景下无需额外调 `detail`
+3. `dataset detail` 返回的字段兼容 v1（properties）和 v2（fields）两种数据集格式；运行态接口未给完整字段时会兜底字段名
+4. 数据集的 code 是 32 位 hex UUID，是所有 `data *` 命令的必填参数
+5. 当业务需求不明确落在哪个 app 时，先验证 `defaultApp`；验证不成立再 `app list`，并用 `dataset list --app <name> --name <关键词>` 做验证式收敛
+6. 写 personal BFF 或其他数据访问源码前，除非用户已经提供明确数据，否则先用 `api-doc`、`dataset detail`、`dataset sdk-doc` 和只读 `data` 命令确认真实结构

package/skills/lovrabet/references/instant-api-workflow.md

@@ -0,0 +1,259 @@
+# Instant API Workflow
+
+## 概述
+
+通过运行态 CLI 对数据集记录进行增删改查和聚合统计。`Instant API` 分组下的所有 `data` 子命令共享统一接口：
+
+```bash
+lovrabet data <command> --code <datasetCode> --params '<json>'
+```
+
+- `--code`：数据集 code（路由标识，必填）
+- `--params`：JSON 请求体，直接透传给运行态 API
+
+## data 之前如何确定 app
+
+`data` 子命令本身只依赖 `dataset code`，但这个 `dataset code` 总是来自某个具体 app。
+
+因此决策顺序应该是：
+
+1. 先判断当前 app 是否已明确
+2. 当前 app 明确时，直接 `dataset list --name ...`
+3. 当前 app 不明确但有 `defaultApp` 时，先 `dataset list --name <关键词>` 验证默认候选
+4. 默认候选无命中、弱命中或语义不合理时，再 `app list`
+5. 再用 `dataset list --app <name> --name <关键词>` 收敛到正确 app
+6. 拿到 `dataset code` 后，再执行 `data filter/getOne/create/batchCreate/update/delete`
+
+不要直接在 app 未决议的情况下盲目构造 `data` 命令。
+
+## 架构说明
+
+7 个 data 子命令对应 7 个运行态 API 端点：
+
+| 子命令 | 说明 | 风险等级 |
+|--------|------|----------|
+| `filter` | 条件查询（分页） | read |
+| `getOne` | 按 ID 获取单条 | read |
+| `aggregate` | 聚合统计（分组、求和、计数等） | read |
+| `create` | 新建记录 | write |
+| `batchCreate` | 批量新建同一数据集记录 | write |
+| `update` | 更新记录 | write |
+| `delete` | 删除记录（需 `--yes`） | high-risk-write |
+
+`--params` JSON 就是 API 请求体，无额外封装。
+
+### Backend Function HOOK
+
+Backend Function HOOK 绑定到某个 Dataset 的一个具体 Instant API operation 及 BEFORE/AFTER 节点。Agent 不直接调用 HOOK；HOOK 是否已绑定必须来自可信业务 Skill 或平台已确认契约。绑定已确认时，执行对应的 `data` 命令会进入 Instant API 请求管线；服务端成功解析并加载绑定脚本时，HOOK 会在同一管线中执行。
+
+`--dry-run` 不会触发 HOOK，它只预览 CLI 将发送的请求。基础访问权限由平台 RBAC 控制；HOOK 仅用于补充个性化校验和处理。已成功加载并执行的 BEFORE HOOK 失败时会阻止对应 Instant API 主操作；绑定查询或脚本加载异常会记录日志并跳过 HOOK，补充逻辑可能被跳过，因此不得把 HOOK 作为必须强制执行的合规或业务校验唯一保障。AFTER HOOK 失败时不能据此断言主操作已回滚，也不能直接重试。对于写操作，先按业务唯一键只读回查主记录和必要的后置结果，再依据可信的事务、幂等或可重试契约决定下一步。
+
+### 超长整数标识
+
+运行态数据中的 BIGINT 标识可能超过 JavaScript 安全整数范围。CLI 会在首次解析响应时把这类整数字面量保留为字符串，避免相邻标识被舍入成同一个值；`--params` 中超过安全范围的整数也会按字符串传递。业务编排仍应把商品、SKU、品牌等标识当作不透明字符串，不对标识执行算术、`Number(...)` 或 `parseInt(...)`。已经被其他工具解析成不安全 `number` 的值无法靠后续 `tostring` 恢复，应重新从无损边界读取。
+
+## 各命令详解
+
+### data filter — 条件查询
+
+`where`、`select`、`orderBy`、`currentPage`、`pageSize` 必须放在同一个 `--params` JSON 对象中。它们不是独立 CLI flags；禁止使用 `--where`、`--select`、`--order-by`、`--current-page`、`--page`、`--page-size`。
+
+```bash
+# 查全部（默认第一页）
+lovrabet data filter --code <code> --params '{"orderBy":[{"id":"asc"}],"currentPage":1,"pageSize":20}'
+
+# 带条件
+lovrabet data filter --code <code> --params '{"where":{"status":{"$eq":"active"}},"orderBy":[{"id":"asc"}],"currentPage":1,"pageSize":20}'
+
+# 翻页：完整复制上一页参数，只递增 currentPage
+lovrabet data filter --code <code> --params '{"where":{"status":{"$eq":"active"}},"orderBy":[{"id":"asc"}],"currentPage":2,"pageSize":20}'
+
+# 完整示例：条件 + 分页 + 排序 + 选字段
+lovrabet data filter --code <code> --params '{
+  "where": {"$and":[{"status":{"$eq":"active"}},{"amount":{"$gte":100}}]},
+  "select": ["id","name","status"],
+  "orderBy": [{"id":"desc"}],
+  "currentPage": 1,
+  "pageSize": 20
+}'
+```
+
+**--params 结构：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `where` | object | 查询条件 |
+| `select` | string[] | 返回字段列表 |
+| `orderBy` | object[] | 稳定排序，例如按唯一字段 `[{"id":"asc"}]` |
+| `currentPage` | number | 页码，从 1 开始 |
+| `pageSize` | number | 每页条数；翻页时保持不变 |
+
+翻页时必须保持 `where`、`select`、`orderBy`、`pageSize` 不变，只递增 `currentPage`。分页查询优先使用唯一且稳定的排序字段，避免跨页重复或遗漏。查询后可投影记录和分页元数据：
+
+```bash
+lovrabet data filter --code <code> --params '{"where":{"status":{"$eq":"active"}},"orderBy":[{"id":"asc"}],"currentPage":2,"pageSize":20}' --format compress --jq '.data.result | {tableData, paging}'
+```
+
+确认 `paging.currentPage`、`paging.pageSize` 与请求一致，并检查 `tableData` 是否满足 `where`。条件未生效或返回形状异常时，本次结果不可作为业务结论；先修正查询，不要把未过滤内容解释为完整业务事实。
+
+### data getOne — 单条查询
+
+```bash
+lovrabet data getOne --code <code> --params '{"id":123}'
+```
+
+### data aggregate — 聚合统计
+
+对数据集进行分组、求和、计数、平均值等聚合操作。
+
+`aggregate` 仅支持单个 `DB_TABLE` 数据集；`METADATA` 数据集不支持 `aggregate` 或 Custom SQL。JOIN、跨表统计、数据库特有函数或 `aggregate` 无法表达的查询，应在编码前显式选择已有且契约可信的 Custom SQL；不要在运行时静默切换，也不要动态拼接 SQL。
+
+```bash
+# 按状态分组求总金额
+lovrabet data aggregate --code <code> --params '{
+  "aggregate": [{"column": "amount","type":"SUM","alias":"total"}],
+  "groupBy": ["status"]
+}'
+
+# 按地区统计活跃订单数
+lovrabet data aggregate --code <code> --params '{
+  "aggregate": [{"column": "id","type":"COUNT","alias":"cnt"}],
+  "groupBy": ["region"],
+  "where": {"status":{"$eq":"active"}}
+}'
+
+# 多维聚合：按状态和地区分组，求总金额并按聚合结果排序
+lovrabet data aggregate --code <code> --params '{
+  "aggregate": [{"column": "amount","type":"SUM","alias":"total"}],
+  "groupBy": ["status","region"],
+  "having": {"status":{"$notNull":true}},
+  "orderBy": [{"total":"desc"}]
+}'
+```
+
+**--params 结构：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aggregate` | object[] | **必填**。聚合定义列表 |
+| `groupBy` | string[] | 分组字段 |
+| `where` | object | 聚合前过滤（与 filter 相同的 where 语法） |
+| `having` | object | 聚合后过滤；使用与 `where` 相同的对象结构，字段必须是真实数据集字段，不支持聚合别名 |
+| `select` | string[] | 随聚合结果返回的原始字段 |
+| `orderBy` | object[] | 排序；可以引用聚合输出别名，如 `[{"total":"desc"}]` |
+| `currentPage` | number | 页码 |
+| `pageSize` | number | 每页条数 |
+
+`aggregate[].column` 必须使用真实数据集字段；`aggregate[].alias` 只定义返回结果字段名，不会成为新的数据集字段。
+
+| 位置 | 聚合别名 | 约束 |
+|------|----------|------|
+| `aggregate[].alias` | 支持 | 仅定义返回结果字段名 |
+| `select` | 不支持 | 使用真实数据集字段 |
+| `where` | 不支持 | 使用真实数据集字段 |
+| `having` | 不支持 | 使用真实数据集字段 |
+| `groupBy` | 不支持 | 使用真实数据集字段 |
+| `orderBy` | 支持 | 可以引用聚合输出别名 |
+
+需要按聚合结果过滤且 `aggregate` 无法用真实字段表达时，使用已有且契约可信的 Custom SQL。不要在运行时静默切换到 Custom SQL，也不要动态拼接 SQL。
+
+**聚合类型：**
+
+| type | 说明 | 示例 |
+|------|------|------|
+| `SUM` | 求和 | `{"column": "amount","type":"SUM","alias":"total"}` |
+| `COUNT` | 计数 | `{"column": "id","type":"COUNT","alias":"cnt"}` |
+| `COUNT` (distinct) | 去重计数 | `{"column": "id","type":"COUNT","alias":"cnt","distinct":true}` |
+| `AVG` | 平均值 | `{"column": "score","type":"AVG","alias":"avg_score"}` |
+| `AVG` (rounded) | 带精度平均值 | `{"column": "score","type":"AVG","alias":"avg","round":true,"precision":2}` |
+
+### data create — 新建记录
+
+```bash
+# 预览
+lovrabet data create --code <code> --params '{"name":"test","amount":100}' --dry-run
+
+# 执行
+lovrabet data create --code <code> --params '{"name":"test","amount":100}'
+```
+
+### data batchCreate — 批量新建同一数据集记录
+
+```bash
+# 预览
+lovrabet data batchCreate --code <code> --params '[{"name":"a"},{"name":"b"}]' --dry-run
+
+# 执行
+lovrabet data batchCreate --code <code> --params '[{"name":"a"},{"name":"b"}]'
+```
+
+`--params` 可以是 JSON 数组，也可以是 `{"items":[...]}`。该命令适合同一数据集多条新增，用于减少请求次数。
+
+不要把 `batchCreate` 当作正式业务流程入口。跨多个数据集、upsert、依赖顺序、频率保护、幂等恢复或 handoff 结果要求，应封装在 Backend Function/CLI service 中，再由内部按需使用 `batchCreate`。Backend Function 写入类执行仍需先确认业务授权、Studio 权限和人工确认语义；CLI 将 `bff exec` 标记为 `read`，不等同于免审批写入。
+
+### data update — 更新记录
+
+```bash
+# 单条预览
+lovrabet data update --code <code> --params '{"id":123,"status":"completed"}' --dry-run
+
+# 单条执行
+lovrabet data update --code <code> --params '{"id":123,"status":"completed"}'
+
+# 批量预览
+lovrabet data update --code <code> --params '{"id":[1,2,3],"status":"completed"}' --dry-run
+
+# 批量执行
+lovrabet data update --code <code> --params '{"id":[1,2,3],"status":"completed"}'
+```
+
+`id` 支持单值或数组。数组不能为空，id 必须是正整数或数字字符串，一次最多 1000 条。批量更新成功时 CLI 会用稳定 envelope 表达结果：`operation:"update"`、`mode:"batch"`、`ids`、`total`、`result`。为兼容当前运行时 metadata 路径，批量数组 id 会在实际请求体和 dry-run 预览中序列化为逗号字符串，例如 `id:"1,2,3"`；用户输入仍使用数组。底层服务端批量回查仍在 follow-up 中。
+
+### data delete — 删除记录
+
+```bash
+# 预览
+lovrabet data delete --code <code> --params '{"id":123}' --dry-run
+
+# 执行（需确认）
+lovrabet data delete --code <code> --params '{"id":123}' --yes
+```
+
+## where 查询语法
+
+| 操作符 | 含义 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{"status":{"$eq":"active"}}` |
+| `$ne` | 不等于 | `{"status":{"$ne":"deleted"}}` |
+| `$gte/$gteq/$lte/$lteq` | 比较 | `{"amount":{"$gte":100}}` |
+| `$contain` | 包含匹配 | `{"name":{"$contain":"test"}}` |
+| `$startWith` | 前缀匹配 | `{"name":{"$startWith":"pre"}}` |
+| `$endWith` | 后缀匹配 | `{"name":{"$endWith":"suf"}}` |
+| `$notNull` | 非空判断 | `{"app_code":{"$notNull":true}}` |
+| `$in` | 包含 | `{"status":{"$in":["active","pending"]}}` |
+| `$and` | AND 组合 | `{"$and":[cond1, cond2]}` |
+| `$or` | OR 组合 | `{"$or":[cond1, cond2]}` |
+
+## aggregate 参数结构（与 SDK 对齐）
+
+```json
+{
+  "select": ["category_id"],
+  "aggregate": [
+    { "type": "SUM", "column": "amount", "alias": "total_amount", "round": true, "precision": 2 }
+  ],
+  "where": { "status": { "$eq": "active" } },
+  "groupBy": ["category_id"],
+  "having": { "category_id": { "$notNull": true } },
+  "orderBy": [{ "total_amount": "desc" }],
+  "currentPage": 1,
+  "pageSize": 20
+}
+```
+
+## 错误处理
+
+- 缺少认证 → `Error: No authentication configured`
+- `--params` 不是合法 JSON → `Error: Invalid JSON for --params: ...`
+- 数据集不存在 → API 返回错误
+- 非交互模式下 delete 未加 `--yes` → 高风险保护拦截

package/skills/lovrabet/references/lovrabet-app-config.md

@@ -0,0 +1,51 @@
+# app-config — 运行态 app-config value 查询
+
+按当前应用和配置 key 读取运行态 app-config value。
+
+app-config 用于应用维度的运行态配置管理。`app-config get` 直接输出 value，返回值可能包含敏感信息。
+
+## app-config get
+
+```bash
+lovrabet app-config get <key>
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `<key>` | string | 是 | app-config key |
+
+**风险等级**：`read`
+
+**输出**：`data` 为 value 的具体结果：
+
+```json
+{
+  "ok": true,
+  "command": "lovrabet app-config get",
+  "risk": "read",
+  "data": "example-value"
+}
+```
+
+## 边界
+
+- `lovrabet app-config get` 不支持 `--reveal`，命令直接输出 value。
+- `lovrabet` 不提供 app-config 的 set/delete/list 管理入口。
+- 不要把 app-config value 写入 `.lovrabet.json`、缓存、日志、命令参数或业务 Skill 入参。
+- 输出可能是敏感值，Agent 只在用户明确要求查询指定 key 时执行。
+- 示例 key 仅用于说明；实际执行必须使用调用方明确给出的 key，不能猜测、按 tags 查找或默认使用示例 key。
+- Agent 执行 Skill 需要 value 时也调用该 CLI，不创建或复用取配置 BFF。
+- value 只在当前任务内消费；除非用户明确要求查看，最终答复默认不重复展示。
+
+## 示例
+
+```bash
+lovrabet app-config get example_api_key --format compress
+```
+
+若 key 不存在、当前 AK 无权限或运行态只读接口不可用，命令会返回错误。错误排查只基于 key、appCode、traceId 等定位信息，不应要求用户提供或回显明文 value。
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [lovrabet-output-format-jq.md](lovrabet-output-format-jq.md)

package/skills/lovrabet/references/lovrabet-app.md

@@ -0,0 +1,113 @@
+# app — 应用管理
+
+`app` 子命令负责应用目录发现和本地缓存刷新：
+
+- **应用目录发现**：通过远端接口和本地 cache 获取当前 AK 可运行态访问的应用列表
+- **缓存刷新**：在需要显式更新本地应用目录时使用 `app pull`
+
+> **核心边界**：平台应用列表不再写入 `.lovrabet.json`。`.lovrabet.json` 只保存用户配置；应用目录缓存位于 `~/.lovrabet/cache/...`。
+>
+> 给当前工作目录绑定默认应用时，使用 `lovrabet workspace init/use`；命令选择取决于当前目录是否已经存在应用绑定。
+
+## app list — 列出当前 AK 可运行态访问应用
+
+```bash
+lovrabet app list
+lovrabet app list --local
+lovrabet app list --no-cache
+lovrabet app list --env daily
+lovrabet app list --include-unpublished
+```
+
+| Flag | 说明 |
+|------|------|
+| `--env <env>` | 指定环境，默认当前环境 |
+| `--local` | 只读本地 cache，不打远端 |
+| `--no-cache` | 强制打远端并刷新 cache |
+| `--include-unpublished` | 排查用：包含未发布应用 |
+
+**行为**：
+- 默认：远端优先，成功后刷新 cache，只展示已发布应用
+- 远端失败且本地有 cache：回退到 cache
+- `--local`：只读 cache
+- `--include-unpublished`：仅用于确认未发布应用是否在远端目录或 cache 中；不要把未发布应用作为 `dataset` / `data` / `sql` / `bff` 目标
+- 输出中的 `meta.source` 为 `remote` / `cache` / `mock`
+
+**缓存路径**：
+
+```text
+~/.lovrabet/cache/<env>/<ak-fingerprint>/my-apps.json
+```
+
+**输出**：
+- `data.items`：应用列表；默认只包含已发布、可运行态访问的应用
+- `data.items[].enableI18n`：应用是否开启国际化；旧缓存或远端缺失该字段时为 `null`
+- `data.items[].languages`：应用支持的语种列表，来自平台真实 `i18nInfo.langs`
+- `data.items[].i18nInfo`：平台返回的应用国际化配置
+- `data.items[].locale`：CLI 本地兼容配置字段，不代表应用支持语种，可能为 `null`
+- `data.meta.env`：环境
+- `data.meta.source`：来源
+- `data.meta.fetchedAt`：最近同步时间
+- `data.meta.cachePath`：cache 文件路径
+- `data.meta.defaultApp` / `defaultAppSource`：当前默认候选应用决议结果
+- `data.meta.remoteTotal`：远端或 cache 原始应用数量
+- `data.meta.hiddenUnpublishedCount`：默认列表中因未发布被隐藏的应用数量
+- `data.meta.includeUnpublished`：本次是否包含未发布应用
+
+## 何时应该先跑 app list
+
+应该先跑 `app list` 的场景：
+
+- 用户只说了业务域，没有给 app 线索
+- 当前没有显式 `--appcode` / `--app`，且需求包含业务域、对象名或数据集线索
+- 你怀疑需求可能落在多个 app 中
+- 你需要先确认当前 AK 在该环境下有哪些可运行态访问的应用
+- 已经在 `defaultApp` 下按关键词验证过，但没有合理数据集命中
+
+不需要先跑 `app list` 的场景：
+
+- 用户已经给了 `--appcode`
+- 用户已经给了 `--app <name>`
+- 问题明显沿用上文已确认的同一 app 上下文
+- 用户明确说“当前应用”“默认应用”，且没有新的业务域线索
+
+`defaultApp` 只是默认候选，不是强上下文。未显式指定 app 且存在 `defaultApp` 时，应先用 `dataset list --name <关键词>` 验证默认候选；命中不合理时，再通过 `app list` 扩大搜索。
+
+## 如何选择使用哪个应用
+
+推荐方法不是只看 app 名，而是：
+
+1. 有 `defaultApp` 时，先在默认候选下执行 `dataset list --name <关键词>`
+2. 默认候选命中合理时直接继续
+3. 默认候选无命中、弱命中或语义不合理时，再用 `app list` 拿到候选 app
+4. 按需求关键词挑 1-2 个候选，对每个候选执行 `dataset list --app <name> --name <关键词>`
+5. 用数据集命中情况反向确认正确 app
+
+这样比纯靠 app 名猜测更稳。
+
+## app pull — 手动刷新本地 app cache
+
+```bash
+lovrabet app pull
+lovrabet app pull --env daily
+lovrabet app pull --local
+lovrabet app pull --no-cache
+```
+
+| Flag | 说明 |
+|------|------|
+| `--env <env>` | 指定环境，默认当前环境 |
+| `--local` | 只读 cache，不请求远端 |
+| `--no-cache` | 强制打远端并刷新 cache |
+
+**注意**：
+- 平时优先用 `lovrabet app list`；只有你明确想单独刷新缓存时才用 `app pull`
+- `app pull` **不再**把远端应用列表写入 `.lovrabet.json`
+- 它的职责只是“刷新本地 cache”
+
+详见 [lovrabet-workspace.md](lovrabet-workspace.md)。
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [lovrabet-config.md](lovrabet-config.md)