@lovrabet/lovrabet-cli 2.1.23 → 2.2.0

package/skills/lovrabet/guides/app-resolution.md

@@ -0,0 +1,165 @@
+# App Resolution Guide
+
+## 目的
+
+在执行 `dataset`、`data`、`sql`、`bff` 之前，先判断当前任务是否需要做“应用决议”。
+
+应用决议的目标只有一个：确定这次操作应该落在哪个已发布、可运行态访问的 app 上。不要把它和“刷新配置”“同步应用列表”混在一起。
+
+这份指引面向 AI / Agent。重点不是“会不会查 app”，而是“如何把 app 决议做得足够准”。
+
+## 直接使用当前应用的场景
+
+满足以下任一条件时，直接进入业务命令，不先跑 `lovrabet app list`：
+
+1. 用户已经显式给了 `--appcode`
+2. 用户已经显式给了 `--app <name>`
+3. 当前问题明显延续上文，且 app 上下文没有变化
+4. 用户明确说“当前应用”“默认应用”，且没有新的业务域线索
+
+`defaultApp` 只是弱候选，不是强上下文。不要因为配置里存在 `defaultApp` 就直接认定它正确；也不要一上来就跳到全量 `app list`。未显式指定 app 时，先在默认候选里按关键词验证数据集是否匹配。
+
+## 必须先做应用决议的场景
+
+出现以下情况时，才扩大到：
+
+```bash
+lovrabet app list
+```
+
+`app list` 默认只返回已发布应用。未发布应用即使在 `app list --include-unpublished` 中可见，也只用于排查，不作为 `dataset` / `data` / `sql` / `bff` 的候选。
+
+典型场景：
+
+1. 用户只给了业务需求，没有给 app 线索
+2. 当前没有显式 `--appcode` / `--app`，且需求里有业务域、对象名或数据集线索
+3. 需求可能落在多个 app 中
+4. 用户明确要求“先看看有哪些应用”
+5. 已经在 `defaultApp` 下按关键词验证过，但没有合理数据集命中
+
+## 标准决议流程
+
+1. 先看是否已有明确 app 上下文
+2. 没有明确上下文但有 `defaultApp` 时，先验证默认候选：
+
+```bash
+lovrabet dataset list --name "<关键词>"
+```
+
+3. 如果默认候选命中的数据集名称、字段、描述贴合需求，继续使用默认候选
+4. 如果默认候选无命中、弱命中或语义不合理，再 `lovrabet app list`
+5. 根据业务关键词先挑 1-3 个候选 app
+6. 用候选 app 做一次验证式收敛：
+
+```bash
+lovrabet dataset list --app <name> --name "<关键词>"
+```
+
+7. 命中后再进入 `dataset detail`、`data *`、`sql *`、`bff *`
+
+## AI 如何挑候选 app
+
+不要只盯着 `name`。应综合看这些信息：
+
+1. `name`
+   - 业务域关键词是否直接匹配
+   - 是否是用户原话中的简称、系统名、团队名
+
+2. `description` / `appDesc`
+   - 是否明确描述了业务边界
+   - 是否包含目标对象、场景、部门、流程关键词
+
+3. 当前上下文
+   - 用户前文是否一直在说某个业务域
+   - 默认候选 app 是否已经稳定服务于这个业务域
+
+4. 验证结果
+   - 默认候选下的 `dataset list --name "<关键词>"` 是否能命中
+   - `dataset list --app <name> --name "<关键词>"` 是否能命中
+   - 命中的数据集名称、字段是否真的贴合需求
+
+## 推荐评分思路
+
+可以按下面的优先级判断：
+
+1. **强匹配**
+   - app 名称直接命中业务关键词
+   - description 明确描述同一业务域
+
+2. **中匹配**
+   - 名称不完全一致，但 description 或 owner / status 信息支持它是对的
+   - 在 `dataset list` 中命中相关数据集
+
+3. **弱匹配**
+   - 只有名称模糊相关
+   - 没有 description 支撑
+   - `dataset list` 验证也不明显
+
+弱匹配不要直接拍板。
+
+## 优先使用 description 的场景
+
+以下场景只看 app 名很容易误判，应主动参考 description：
+
+- 名称过短，例如 `crm`、`erp`、`oms`
+- 多个 app 名称都很接近
+- app 名称偏内部缩写，业务语义不直接
+- 用户用自然语言描述需求，而不是产品名
+
+如果 `app list --format json` 返回里带有 `description` / `appDesc`，优先把它作为候选排序的重要依据。
+
+## 不确定时如何处理
+
+当候选 app 仍然有 2 个以上都合理时，不要硬选一个。
+
+应先给出 1-2 个最可能的候选，并说明理由，然后询问用户确认。推荐表达方式：
+
+```text
+我现在更怀疑是这两个应用：
+1. crm：description 更接近客户资料/跟进场景
+2. oms：名称和订单流程更接近
+
+我可以先按 crm 继续查数据集；如果你指的是订单侧应用，我再切到 oms。
+```
+
+如果已经有验证结果，也应带上：
+
+```text
+我先在 crm 里搜到“客户档案”“联系人”两个数据集，在 oms 里没有明显命中。
+我先按 crm 继续。
+```
+
+## 何时可以直接默认继续
+
+满足下面任一条件，可以默认继续，不必反问用户：
+
+- 当前只有一个强匹配候选
+- 当前 `defaultApp` 下的数据集验证结果与需求语义一致，且没有冲突迹象
+- 已经通过 `dataset list` 验证出明显命中
+
+## 何时必须问用户
+
+出现以下情况时，应主动确认：
+
+- 两个以上候选都能自圆其说
+- `dataset list` 在多个 app 下都有命中
+- 用户给的是组织/部门语义，而不是系统语义
+- 当前默认 app 与本次需求明显可能冲突
+
+## 不要这样做
+
+- 不要每次都机械地先跑 `app list`
+- 不要只看 app 名就直接认定目标 app
+- 不要忽略 `description` / `appDesc`
+- 不要在候选不明确时静默硬选一个继续执行高影响操作
+- 不要因为本地配置里没有 app 信息，就判定该 app 不存在
+- 不要把远端 app 目录重新写回 `.lovrabet.json`
+
+## 当前架构要点
+
+- 应用目录来源：远端接口 + 本地 cache
+- 本地配置只保存用户意图：`defaultApp`、顶层 `appcode`
+- `defaultApp` 是默认候选；未显式指定 app 时先验证它，验证不成立再扩大搜索
+- `lovrabet app list`：远端优先
+- `lovrabet app pull`：只做手动刷新 cache
+- 当前目录尚未绑定应用时，用 `lovrabet workspace init --app <name>` 建立绑定；已有绑定时用 `lovrabet workspace use --app <name>` 修改。跨环境操作时带上和 `app list` 相同的 `--env`

package/skills/lovrabet/guides/dataset-and-data-workflow.md

@@ -0,0 +1,170 @@
+# Dataset And Data Workflow Guide
+
+## 目的
+
+把“业务需求 -> 应用决议 -> 数据集定位 -> Instant API 数据操作”收成一条稳定流程，避免直接盲猜 `dataset code` 或 app。
+
+## 推荐流程
+
+1. 先判断 app 是否明确  
+   不明确时，先看 [app-resolution.md](app-resolution.md)
+
+2. 需要写 personal BFF 或知识库内容时，先做发现
+
+```bash
+lovrabet api-doc list --category dataset
+lovrabet api-doc detail --code dataset_data_filter
+```
+
+如果用户已经给了明确字段和值，可以直接使用用户提供的数据；否则先确认真实 API 和数据结构。
+
+3. 定位数据集
+
+```bash
+lovrabet dataset list --name "<关键词>"
+```
+
+如需限定候选 app：
+
+```bash
+lovrabet dataset list --app <name> --name "<关键词>"
+```
+
+4. 看数据集结构
+
+```bash
+lovrabet dataset detail --code <datasetCode>
+```
+
+5. 需要 SDK 调用示例时读取数据集 SDK 文档
+
+```bash
+lovrabet dataset sdk-doc --code <datasetCode>
+```
+
+6. 拿到 `datasetCode` 后，再进入 `data` 子命令
+
+```bash
+# 第 1 页：过滤、稳定排序和分页都放进一个 --params JSON
+lovrabet data filter --code <datasetCode> --params '{"where":{"status":{"$eq":"active"}},"orderBy":[{"id":"asc"}],"currentPage":1,"pageSize":20}'
+
+# 第 2 页：复制上一页参数，只递增 currentPage
+lovrabet data filter --code <datasetCode> --params '{"where":{"status":{"$eq":"active"}},"orderBy":[{"id":"asc"}],"currentPage":2,"pageSize":20}'
+
+lovrabet data getOne --code <datasetCode> --params '<json>'
+lovrabet data create --code <datasetCode> --params '<json>'
+lovrabet data batchCreate --code <datasetCode> --params '[{"name":"a"},{"name":"b"}]'
+lovrabet data update --code <datasetCode> --params '<json>'
+lovrabet data delete --code <datasetCode> --params '<json>' --yes
+```
+
+`data filter` 的 `where`、`select`、`orderBy`、`currentPage`、`pageSize` 都是 `--params` JSON 字段。不要使用 `--where`、`--select`、`--order-by`、`--current-page`、`--page`、`--page-size`；CLI 会拒绝这些误用。翻页时保持筛选条件、返回字段、排序和 `pageSize` 不变，只递增从 1 开始的 `currentPage`。分页查询应使用唯一且稳定的排序字段，避免跨页重复或遗漏。
+
+查询后核对记录和分页元数据：
+
+```bash
+lovrabet data filter --code <datasetCode> --params '{"where":{"status":{"$eq":"active"}},"orderBy":[{"id":"asc"}],"currentPage":1,"pageSize":20}' --format compress --jq '.data.result | {tableData, paging}'
+```
+
+必须确认 `paging.currentPage`、`paging.pageSize` 与请求一致，并检查 `tableData` 是否满足 `where`。条件未生效、分页元数据不符或返回形状异常时，本次查询结果不可作为业务结论；先检查 `--params`，必要时执行 `lovrabet data filter --help`。
+
+`data update` 的 `id` 可传单值或数组；批量更新示例：`--params '{"id":[1,2,3],"status":"done"}'`。数组不能为空，一次最多 1000 条。批量数组 id 会在实际请求体和 dry-run 预览中使用逗号字符串兼容运行时解析，用户仍按数组输入。
+
+## 什么时候只用 `dataset list`
+
+以下情况只用 `dataset list` 就够：
+
+- 用户只是问“有哪些数据集”
+- 用户只是想按名称搜索数据集
+- 只需要数据集 code 和字段名数组
+
+## 什么时候必须看 `dataset detail`
+
+以下情况必须补一轮 `dataset detail`：
+
+- 要确认字段类型
+- 要确认字段是否可写
+- 要确认主键 / 操作列表
+- 要给 `data create/batchCreate/update` 组参数
+
+## 什么时候看 `dataset sdk-doc`
+
+以下场景补一轮 `dataset sdk-doc`：
+
+- 需要在 personal BFF 或其他可交付源码中调用运行态 SDK
+- 需要确认 SDK 参数结构，而不只是字段名
+- 要把数据访问方式写进可交付源码或文档
+
+## Dataset 回退准入
+
+Dataset Detail + Instant API 是简单低风险事实查询的直接路径，例如读取单条记录、列举明细或做不承载业务判定的基础统计；这类请求不强制查询 KB，也不需要包装成 Custom SQL 或 Backend Function。
+
+以下任务不能直接回退到原始 Dataset 字段：
+
+- **稳定规则**：已有已发布且契约可信的确定性能力定义固定口径时，必须复用该入口，不重新拼字段实现同一规则。当前类型包括但不限于业务 Skill、已治理 Dataset / Instant API（含 `filter`、`getOne`、`aggregate`）、Custom SQL 和 Backend Function；Service Tree 只用于定位承载规则的入口，不单独作为规则事实源。
+- **高风险确定性判断**：审批、合规、价格异常、权限、资质等结论必须使用已确认的确定性能力；没有匹配能力时，只对受影响范围输出“不判定”，并说明缺少的能力契约。
+- **副作用未知的操作**：即使 CLI risk 显示为 `read`，也要先确认真实业务写入、外部调用和不可逆动作。
+
+Dataset Detail 只证明字段与操作契约，不会自动把原始数据推导提升为稳定业务规则。
+
+### 正式规则与分析性推导
+
+- 用户询问正式业务规则时，Dataset 原始字段只能返回已经确认的直接事实；缺少可信规则契约时，对正式结论输出“不判定”，并说明缺少的规则语义、适用范围或执行入口。
+- 只有用户明确要求估算、探索或情景分析时，才可基于 Dataset 做分析性推导。输出必须展示使用字段、公式和假设，明确它不是平台正式规则，也不得把它作为自动写入、审批、退款或其他高风险业务动作的唯一依据。
+- 规则语义必须来自可信业务 Skill 或平台已确认契约；Dataset Instant API、Custom SQL 和 Backend Function 只是执行载体，能力类型或 Detail 成功本身不证明规则可信。
+- 高风险操作仍需满足服务端 RBAC、业务授权和用户确认；`--dry-run` 仅预览请求，不能替代授权、确认或执行后核验。
+
+## `data` 的使用原则
+
+`data` 命令只依赖 `datasetCode`，不直接做 app 决议。  
+所以不要在 app 未确定、dataset 未确认时直接构造 `data filter/getOne/create/batchCreate/update/delete`。
+
+## Instant API 与 HOOK
+
+Backend Function HOOK 不是 Agent 可直接执行的端点。它绑定到某个 Dataset 的一个具体 Instant API operation 及 BEFORE/AFTER 节点；当绑定关系来自可信业务 Skill 或平台已确认契约时，Agent 执行对应的 `data` 命令。服务端成功解析并加载绑定脚本时，HOOK 会在同一请求管线中执行。`dataset detail` 不保证返回 HOOK 绑定、输入输出或失败语义，缺少可信绑定契约时不能靠执行请求试探。
+
+`--dry-run` 只预览 CLI 请求，不触发 HOOK。基础访问权限由平台 RBAC 控制；HOOK 仅用于补充个性化校验和处理。已成功加载并执行的 BEFORE HOOK 失败时会阻止对应 Instant API 主操作；绑定查询或脚本加载异常会记录日志并跳过 HOOK，补充逻辑可能被跳过，因此不得把 HOOK 作为必须强制执行的合规或业务校验唯一保障。AFTER HOOK 失败时不能据此断言主操作已回滚。对写操作的返回错误、超时或 AFTER HOOK 失败，先按业务唯一键只读回查主记录和必要的后置结果，再依据可信的事务、幂等或可重试契约决定是否重试。
+
+## 批量新增的边界
+
+`lovrabet data batchCreate` 只适合“同一数据集多条新增”，用于减少请求次数。参数必须是 JSON 数组，或 `{"items":[...]}`：
+
+```bash
+lovrabet data batchCreate --code <datasetCode> --params '[{"name":"a"},{"name":"b"}]' --dry-run
+lovrabet data batchCreate --code <datasetCode> --params '[{"name":"a"},{"name":"b"}]'
+```
+
+使用前仍要先做 `dataset detail`，确认字段可写、必填字段和业务唯一键。执行后按业务唯一键只读核对，避免“请求结果未知”时重复写入。
+
+不要在执行时直接用 `data batchCreate` 绕过 Backend Function 业务编排。只要写入涉及多个数据集、upsert、依赖顺序、幂等、失败恢复或 handoff 结果，就应调用业务级 `bff exec`，由函数或 CLI service 内部决定是否使用批量新增。Backend Function 写入类执行仍需先确认业务授权、Studio 权限和人工确认语义；CLI 将 `bff exec` 标记为 `read`，不等同于免审批写入。
+
+## 高风险动作
+
+删除前先预览：
+
+```bash
+lovrabet data delete --code <datasetCode> --params '<json>' --dry-run
+lovrabet data delete --code <datasetCode> --params '<json>' --yes
+```
+
+## 常见错误
+
+### 只有业务描述，没有 dataset code
+
+不要直接问运行态接口。先：
+
+1. 决议 app
+2. `dataset list --name`
+3. `dataset detail`
+
+### app 不明确但直接跑 `data *`
+
+这通常是在跳过应用决议。先退回去做 app + dataset 定位。
+
+### 把过滤或分页字段写成独立 flag
+
+`--where`、`--page-size` 等写法不会表达 `data filter` 请求体。把所有过滤、排序和分页字段放入一个 `--params` JSON；不要删掉错误 flag 后执行空参数查询。
+
+### 返回了明显未过滤的数据
+
+不要把返回内容直接当成“系统里确实存在这些记录”。先核对 `data.result.paging`、抽查 `data.result.tableData` 是否满足 `where`，再修正查询或查看 `lovrabet data filter --help`。

package/skills/lovrabet/guides/sql-and-bff-workflow.md

@@ -0,0 +1,132 @@
+# Custom SQL 与 Backend Function 工作流
+
+## 目的
+
+统一 `sql` / `bff` 命令组的使用方式，避免在 app 未明确、Custom SQL / Backend Function 标识未确认时直接执行。
+
+## 共同原则
+
+`sql` 命令组用于消费 Custom SQL；Custom SQL 和 Backend Function 都不是“先猜再试”的能力。
+
+运行时复用既有能力的标准顺序：
+
+1. 先判断 app 是否明确
+2. 不明确时，先做应用决议
+3. 从用户明确输入、业务 Skill 固定契约、可信 Service Tree、前序已确认上下文或可信 KB 候选确认 `sqlCode` / Backend Function ENDPOINT `functionName`
+4. 先执行 `detail`，只核对该命令实际返回的字段；缺失契约继续视为未知
+5. 判断真实副作用、权限和用户授权，条件满足时才执行 `exec`
+
+Detail 成功只证明能力存在，不代表可以自动执行。副作用、权限或确认语义不明确时，不自动执行。
+
+`sql detail` 返回 Custom SQL 的名称、数据库和 SQL 内容；`bff detail` 返回 Backend Function ENDPOINT 名称、描述、版本和更新时间等元数据。它们都不会替业务 Skill 补齐参数结构、业务口径和真实副作用契约。
+
+运行态只消费已发布且契约可信的业务能力，当前类型包括但不限于已治理 Dataset / Instant API（含 `filter`、`getOne`、`aggregate`）、Custom SQL 和 Backend Function。Lovrabet Runtime CLI 尚未提供 Flow 运行态入口，因此 Flow 当前不可消费；未暴露可信入口、输入输出或副作用契约的能力不猜测命令，只对受影响范围输出“不判定”。
+
+## Custom SQL 工作流
+
+1. app 不明确时，按 [app-resolution.md](app-resolution.md) 决议：有 `defaultApp` 先验证默认候选，验证不成立再扩大到应用列表：
+
+```bash
+# 默认候选验证不成立时
+lovrabet app list
+```
+
+2. 如果没有 `sqlCode`，从业务 Skill、可信 Service Tree、前序已确认上下文或可信 KB 候选定位；仍无法唯一定位时停止，不猜测
+3. 先看详情：
+
+```bash
+lovrabet sql detail --sqlcode <code>
+```
+
+4. 核对应用、查询口径、参数和数据范围；条件满足时才执行：
+
+```bash
+lovrabet sql exec --sqlcode <code> --params '<json>'
+```
+
+## Backend Function 工作流
+
+1. app 不明确时，按 [app-resolution.md](app-resolution.md) 决议：有 `defaultApp` 先验证默认候选，验证不成立再扩大到应用列表：
+
+```bash
+# 默认候选验证不成立时
+lovrabet app list
+```
+
+2. 如果没有函数信息，从业务 Skill、可信 Service Tree、前序已确认上下文或可信 KB 候选定位；仍无法唯一定位时停止，不猜测
+3. 先看详情：
+
+```bash
+lovrabet bff detail --name <functionName>
+```
+
+4. `bff detail` 成功可确认当前应用能按名称解析该运行态 Backend Function ENDPOINT，但不会返回输入输出、函数类型或副作用契约；参数结构、输入输出和真实副作用由可信业务 Skill 或平台已确认契约补齐，参数值、执行意图和执行授权可由用户明确提供；条件满足时才执行：
+
+```bash
+lovrabet bff exec --name <functionName> --params '<json>'
+```
+
+运行态只主动发现和直接调用 ENDPOINT。HOOK 绑定到 Dataset 的一个具体 Instant API operation 及 BEFORE/AFTER 节点；Agent 不直接调用 HOOK，而是在可信契约确认绑定关系后执行对应 `data` 命令。基础访问权限由平台 RBAC 控制；HOOK 仅用于补充个性化校验和处理。服务端成功解析并加载绑定脚本时，HOOK 在同一请求管线中执行；已执行的 BEFORE HOOK 失败会阻止主操作。绑定查询或脚本加载异常会记录日志并跳过 HOOK，补充逻辑可能被跳过，因此不得把 HOOK 作为必须强制执行的合规或业务校验唯一保障。AFTER HOOK 失败时不能据此断言主操作已回滚或直接重试，应先按业务唯一键只读回查。
+
+## app-config value 查询
+
+`lovrabet app-config get <key>` 按当前 appCode 和 key 查询运行态 app-config value：
+
+```bash
+lovrabet app-config get example_api_key --format compress
+```
+
+命令的 `data` 直接返回 value；该值可能包含敏感信息，不要写入本地配置、缓存、日志、`--params` 或业务 Skill 入参。
+
+示例 key 仅用于说明；实际执行必须使用用户或业务 Skill 明确给出的 key，不能猜测或默认使用示例 key。Agent 执行 Skill 时同样调用该 CLI 获取 value，不创建取配置 Backend Function；value 只在当前任务内消费，除非用户明确要求，否则最终答复不重复展示。
+
+## personal BFF 工作流
+
+personal BFF 是当前用户在当前应用下维护的个人脚本，适合做轻量数据编排，或先验证一个临时业务接口的返回形状。
+
+标准顺序：
+
+1. `lovrabet personal-bff list` 查当前用户已有脚本
+2. `lovrabet personal-bff detail --id <id>` 查看现有脚本后再更新
+3. 从本地脚本文件 `create` 或 `update`
+4. `lovrabet personal-bff exec --id <id> --params '<json>' --format compress` 确认返回形状
+5. 再把结果形状用于下游调用或交付说明
+
+```bash
+lovrabet personal-bff create --name loadOrders --file ./load-orders.js --dry-run
+lovrabet personal-bff exec --id <id> --params '{"status":"active"}' --format compress
+```
+
+执行前确认目标脚本 ID、输入参数和已知副作用；执行后核对返回字段、空态和错误形状。
+
+## 复杂业务写入与频率保护
+
+多数据集写入、跨步骤依赖、upsert、执行时需要 handoff 结果或需要幂等恢复的业务动作，优先封装在 Backend Function 中，再通过 `lovrabet bff exec` 调用。Agent 不应在执行时直接拼多次 `data create` 或 `data batchCreate` 绕过业务入口。Backend Function 写入类执行仍需先确认业务授权、Studio 权限和人工确认语义；CLI 将 `bff exec` 标记为 `read`，不等同于免审批写入。
+
+推荐 Backend Function 入参包含业务级 `requestId` 或 `idempotencyKey`。函数内部按业务唯一键先只读核对，确认不存在再写入；遇到频率保护、超时或客户端没有拿到成功结果时，等待后再次只读核对，确认没有落地再重试。只有同一数据集多条新增时，函数或 CLI service 内部才适合使用 `batchCreate` 减少请求次数。
+
+Backend Function 返回值应包含 handoff 所需结果：已创建记录、已复用记录、失败步骤、是否可重试和 traceId。这样 Agent 拿到的是业务结果，而不是一串低层写接口的临场拼装结果。
+
+## 什么时候可以跳过 app 决议
+
+以下情况可以直接进入 `sql detail` 或 `bff detail`，但不能跳过执行前的风险与授权判断：
+
+- 用户已经给了 `--appcode`
+- 用户已经给了 `--app <name>`
+- 当前对话已经明确在某个 app 上下文中继续
+- 用户明确说“当前应用”“默认应用”，且没有新的业务域线索
+
+`defaultApp` 只是默认候选，不是强上下文。Custom SQL 和 Backend Function 经常按业务域分布在不同 app 中；用户提到新的业务域或业务对象且未指定 app 时，先把 `defaultApp` 当第一个候选验证，验证不成立再扩大到应用列表。
+
+## 不要这样做
+
+- 不要在不知道 `sqlCode` 的情况下直接跑 `sql exec`
+- 不要在不知道函数名的情况下直接跑 `bff exec`
+- 不要在 app 未明确时直接默认当前 app 一定对
+
+## 推荐配合命令
+
+- app 决议：`lovrabet app list`
+- Custom SQL 标识来源：用户明确输入、业务 Skill、可信 Service Tree、前序已确认上下文或可信 KB 候选
+- Backend Function 标识来源：用户明确输入、业务 Skill、可信 Service Tree、前序已确认上下文或可信 KB 候选
+- personal BFF：`lovrabet personal-bff list/detail/create/update/exec`

package/skills/lovrabet/guides/troubleshooting.md

@@ -0,0 +1,91 @@
+# Troubleshooting Guide
+
+## Authentication required
+
+说明当前没有可用的 `accessKey`。
+
+优先检查：
+
+1. `lovrabet auth status`
+2. `~/.lovrabet.json` 或项目 `.lovrabet.json` 是否有顶层 `accessKey`
+3. 是否设置了 `LOVRABET_ACCESS_KEY`
+
+如果确认只是没登录：
+
+- 先到 `https://user.lovrabet.com/user/ak` 创建 AccessKey
+- 想保留当前配置，执行 `lovrabet auth login`
+- 想清空当前作用域配置后重建认证，执行 `lovrabet auth init --access-key <ACCESS_KEY> [--env daily]`
+
+## 已登录，但业务命令仍失败
+
+优先检查：
+
+1. 当前 `env` 是否正确
+2. 当前 AK 对应的是否是预期用户：`lovrabet auth info`
+3. `defaultApp` 是否能在 cache 中解析到 appcode
+4. 是否需要先刷新 app cache
+
+```bash
+lovrabet app list --no-cache
+```
+
+如果你怀疑当前作用域配置已经混乱，比如：
+
+- `defaultApp` 明显不对
+- `env` 和预期不一致
+- `auth info` 返回的用户不是你预期的账号
+- 同一作用域里残留了不该继承的旧配置
+
+可直接重建认证配置：
+
+```bash
+lovrabet auth init --access-key <ACCESS_KEY> --env daily
+```
+
+注意：这会清掉当前作用域里已有的其他配置字段，不只是 `accessKey`。
+
+## `defaultApp` 已有，但仍然找不到 appcode
+
+说明当前 `defaultApp` 对应的远端 app 目录还没建立或已经失效。
+
+先执行：
+
+```bash
+lovrabet app list --no-cache
+```
+
+如果仍不行，说明：
+
+- 当前 `accessKey` 看不到这个 app
+- 或 `defaultApp` 名称本身已过时
+
+## `app list --local` 没数据
+
+说明本地还没有建立 cache，或者 cache 已清空。
+
+先执行：
+
+```bash
+lovrabet app list
+```
+
+或强制刷新：
+
+```bash
+lovrabet app list --no-cache
+```
+
+## 什么时候该看 doctor
+
+遇到以下情况时，优先执行：
+
+```bash
+lovrabet doctor
+```
+
+典型场景：
+
+- 配置来源不清楚
+- `defaultApp` / `currentApp` 判断异常
+- 环境和实际请求不一致
+- 认证信息看起来存在，但命令仍失败