@lovrabet/lovrabet-cli 2.1.23 → 2.2.0

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

@@ -0,0 +1,19 @@
+# logs — 命令日志
+
+查看 CLI 命令执行历史。
+
+## logs show — 查看日志
+
+```bash
+lovrabet logs
+# 或
+lovrabet logs show
+```
+
+`logs` 等价于 `logs show`（默认子命令）。无需参数。
+
+输出历史命令执行记录，包含命令、时间、状态等信息。
+
+## 参考
+
+- [SKILL.md](../SKILL.md)

package/skills/lovrabet/references/lovrabet-ocr-workflow.md

@@ -0,0 +1,83 @@
+# OCR 识别工作流
+
+`ocr` 命令用于对远程 URL 或本地文件执行 OCR 识别。适用场景包括发票识别、证照识别、表格图片识别、合同或附件内容提取，以及把识别结果整理后写入业务数据。
+
+## 命令概览
+
+| 目标 | 命令 | 风险 |
+|------|------|------|
+| 识别远程 URL | `lovrabet ocr recognize --scene <scene> --image-url <url>` | read |
+| 识别本地文件 | `lovrabet ocr recognize --scene <scene> --image-file <local-path>` | read |
+
+需要机器可读输出时统一加 `--format compress`；需要截取字段时再叠加 `--jq`。
+
+OCR 识别不创建、更新或删除业务数据，因此 `ocr recognize` 的风险等级为 `read`。服务端仍可能记录审计、调用第三方服务并产生积分消耗；这些服务运行副作用不改变 CLI 风险分类。需要把识别结果写入数据集时，后续 `data create` 或 `data update` 仍按 write 规则执行。
+
+`ocr recognize` 支持 dry-run 预览。正式识别前先用 `--dry-run` 确认目标应用、输入方式和服务端调用链路；dry-run 不上传文件、不调用 OCR。
+
+## 识别场景
+
+支持的 `--scene`：
+
+| scene | 适用 |
+|-------|------|
+| `invoice` | 发票、票据 |
+| `general` | 通用图片或文档文本 |
+| `form` | 表格图片 |
+| `idCard` | 证照、身份类图片 |
+
+## 输入方式
+
+识别远程 URL：
+
+```bash
+lovrabet ocr recognize --scene invoice --image-url <url> --dry-run --format compress
+lovrabet ocr recognize --scene invoice --image-url <url> --format compress
+```
+
+识别本地文件：
+
+```bash
+lovrabet ocr recognize --scene invoice --image-file ./invoice.png --dry-run --format compress
+lovrabet ocr recognize --scene invoice --image-file ./invoice.png --format compress
+```
+
+本地文件识别会复用文件上传能力，自动串联：
+
+1. `file upload --file <local-path>`
+2. `file query-url --filepath <filePath>`
+3. `ocr recognize --image-url <temporary-url>`
+
+文件上传和临时 URL 的细节见 [文件上传工作流](lovrabet-file-workflow.md)。
+
+OCR 本地文件链路只需要短效 URL 作为中间输入，不要为 OCR 追加 `file query-url --long-term`。3 年长期 URL 仅用于富文本、Markdown、HTML 等必须把静态 URL 写入长期业务内容的场景。
+
+当前 OCR 输入必须二选一：`--image-file` 或 `--image-url`。`filePath` 需要先通过 `file query-url` 换成可访问 URL 后，才能作为 OCR URL 输入。
+
+## 结果处理
+
+OCR 返回以运行态识别结果为准，常见字段包括 `type`、`text`、`lines`、`requestId`，本地文件识别还会补充 `sourceFile.fileName` 和 `sourceFile.filePath`。
+
+处理建议：
+
+1. 向用户总结识别结论时，优先提取关键业务字段，不粘贴大段原文。
+2. 需要写入数据集时，先 `dataset detail --code <datasetCode>` 确认字段。
+3. 使用 `data create` 或 `data update` 前先 dry-run。
+4. 发票、证照、合同等敏感材料不要写入日志、配置文件或 Skill 文档示例。
+
+示例：识别发票并准备写入数据集。
+
+```bash
+lovrabet ocr recognize --scene invoice --image-file ./invoice.png --format compress
+lovrabet dataset detail --code <datasetCode> --format compress
+lovrabet data create --code <datasetCode> --params '{"invoiceNo":"<识别后的发票号>","amount":100}' --dry-run
+```
+
+## 常见错误
+
+| 现象 | 处理 |
+|------|------|
+| 本地文件不存在 | 检查 `--image-file` 路径，使用真实本地文件 |
+| 文件超过 50 MB | 拆分或压缩文件；本地文件识别会先走当前运行态上传接口 |
+| URL 过期或不可访问 | 重新执行 `file query-url` 获取新的临时 URL |
+| OCR 场景不匹配 | 换用 `general`、`form`、`invoice` 或 `idCard` |

package/skills/lovrabet/references/lovrabet-output-format-jq.md

@@ -0,0 +1,40 @@
+# 输出格式与全局 `--jq`
+
+运行态 `lovrabet` 的声明式命令统一支持**结构化输出**、**compress 默认偏好**和**全局 `--jq`**。
+
+## `--format`
+
+| 值 | 说明 |
+|----|------|
+| `json` | 缩进 JSON，信封 `{ ok, command, risk, data?, ... }` |
+| `compress` | 与 `json` 同一信封，**单行**紧凑，适合 Agent / 管道 |
+| `pretty` | 人类可读（非 JSON 信封的展示型输出，依命令而定） |
+
+解析顺序：**CLI `--format`** > 配置文件 `format` > 默认（产品默认多为 **compress**，以当前 CLI 版本 `--help` 为准）。
+
+## 结构化输出契约
+
+- `json` / `compress` 只输出机器可读信封，不携带运行时升级提示等交互式 notice。
+- 升级提示只在交互式 `pretty` 输出中写入 stderr，不污染 stdout。
+- 自动化脚本不要依赖 `_notice.update`；需要主动升级时显式执行 `lovrabet update`。
+
+## 全局 `--jq '<expr>'`
+
+- **作用**：在**最终要打印的整段 JSON 字符串**上执行 **jq** 表达式（与手动 `… \| jq '<expr>'` 一致）。
+- **适用**：仅当本次输出走 **`--format json` 或 `compress`** 时；若当前为 `pretty` 且你传了 `--jq`，管线会将格式**升格为 json** 再跑 jq。
+- **信封**：表达式作用在**完整信封**上，取业务数据多用 **`.data…`**（例如 `.data.items`、`.data.datasets[]`）。
+- **二进制**：按 **`JQ_PATH` → CLI 内置 sidecar jq → `PATH` 上的 jq** 的顺序解析。若显式设置了 **`JQ_PATH`**，它必须指向一个真实可执行文件；否则命令会直接报错，不会静默回退。
+
+## 示例
+
+```bash
+# 列表只取必要字段（compress + jq）
+lovrabet dataset list --format compress --jq '.data.datasets[] | {code, name}'
+
+# 数据集详情：投影 data 段（json）
+lovrabet dataset detail --code <数据集编码> --format json --jq '.data | {fields, operations: [.operations[].name]}'
+```
+
+## 不适用 `--jq` 的命令
+
+声明式命令里若 **`hasFormat: false`**（例如 `lovrabet doctor`），输出由命令自控，**不参与**上述 `--format` / `--jq` 管线，传 `--jq` 无意义。

package/skills/lovrabet/references/lovrabet-personal-bff-workflow.md

@@ -0,0 +1,108 @@
+# personal BFF 工作流
+
+`personal-bff` 用于当前用户在当前应用下维护个人 ENDPOINT 脚本。第一阶段支持 `list`、`detail`、`create`、`update`、`exec`；不提供删除命令。
+
+## 什么时候用
+
+- 需要把多步只读查询包装成稳定函数
+- 需要先验证一个轻量业务接口的返回形状，再交给下游调用
+
+若已有平台正式 BFF，优先复用 `bff detail/exec`。personal BFF 更适合个人工作流、验证和 Agent 生成的轻量端点。
+
+## BFF 内访问 Dataset
+
+脚本通过 `` context.client.models[`dataset_${datasetCode}`] `` 获取 Dataset accessor。当前支持 `create`、`batchCreate`、`update`、`delete`、`getOne`、`findOne`、`getList`、`filter` 和 `aggregate`。
+
+能由 Dataset Instant API 表达时，优先直接调用对应方法。只有 Instant API 无法表达需求，且已有契约可信的 Custom SQL 时，才使用 `context.client.sql.execute({ sqlCode, params })`。能力选择应在编码前完成；不得先执行 `aggregate`，再因权限、参数或运行错误静默回退 Custom SQL。
+
+同一数据集批量新增时，向 `batchCreate` 直接传非空对象数组；`batchCreate` 返回新记录 ID 数组，顺序与输入一致。不要把 `lovrabet data batchCreate` 兼容的 `{"items":[...]}` 包装传给 BFF Dataset accessor。批量更新仍调用 `update({ id, ...fields })`，其中 `id` 可以是单值或数组；不存在 `batchUpdate()`，也不要把多条更新记录数组直接传给 `update`。批量数量不得超过运行时上限（默认 1000 条）。示例字段必须替换为已确认的真实数据集字段：
+
+```js
+const createdIds = await model.batchCreate([
+  { order_id: params.orderId, sku_code: "A" },
+  { order_id: params.orderId, sku_code: "B" },
+]);
+
+await model.update({
+  id: [1, 2, 3],
+  status: "DONE",
+});
+```
+
+调用 `aggregate` 时仅支持单个 `DB_TABLE` 数据集；`METADATA` 数据集不支持 `aggregate` 或 Custom SQL。`aggregate[].column`、`select`、`where`、`having` 和 `groupBy` 必须使用真实数据集字段；`aggregate[].alias` 只定义输出字段名，只有 `orderBy` 可以引用聚合输出别名。JOIN、跨表统计、数据库特有函数，或需要按聚合结果过滤且无法用真实字段表达时，在编码阶段显式选择已有且契约可信的 Custom SQL，不要动态拼接 SQL。
+
+```js
+export default async function statsByCity(params, context) {
+  const datasetCode = "sales_order";
+  const model = context.client.models[`dataset_${datasetCode}`];
+
+  const aggregateResult = await model.aggregate({
+    aggregate: [{ column: "amount", type: "SUM", alias: "total_amount" }],
+    where: { status: { $eq: "active" } },
+    groupBy: ["city"]
+  });
+
+  return aggregateResult.tableData;
+}
+```
+
+`aggregate` 返回 `{ tableData, paging, tableColumns? }`；业务记录从 `aggregateResult.tableData` 读取，不要按 Custom SQL 的数组返回值处理。
+
+## 查看
+
+```bash
+lovrabet personal-bff list --format compress
+lovrabet personal-bff detail --id <id> --format compress
+```
+
+更新前先 `personal-bff detail`，确认函数名、脚本内容、描述和版本。
+
+## 创建
+
+脚本来自本地 UTF-8 JavaScript 或 TypeScript 文件。`--name` 必须是合法 JavaScript identifier。
+
+```bash
+lovrabet personal-bff create --name loadOrders --file ./load-orders.js --dry-run
+lovrabet personal-bff create --name loadOrders --file ./load-orders.js
+```
+
+可选：
+
+```bash
+lovrabet personal-bff create \
+  --name loadOrders \
+  --description "Load active orders for dashboard" \
+  --source-session-id <sessionId> \
+  --file ./load-orders.js \
+  --dry-run
+```
+
+## 更新
+
+```bash
+lovrabet personal-bff detail --id <id> --format compress
+lovrabet personal-bff update --id <id> --file ./load-orders-v2.js --dry-run
+lovrabet personal-bff update --id <id> --name loadActiveOrders --description "v2" --file ./load-orders-v2.js
+```
+
+`update` 至少要提供 `--name`、`--description`、`--file` 或 `--source-session-id` 之一。
+
+## 执行
+
+`exec` 会运行用户脚本，执行前必须确认目标脚本 ID、输入参数和已知副作用：
+
+```bash
+lovrabet personal-bff exec --id <id> --params '{"status":"active"}' --format compress
+```
+
+不传 `--params` 时默认 `{}`。传入值必须是 JSON 对象。
+
+## 与下游调用配合
+
+接入下游调用前先执行 personal BFF，并保存返回形状摘要：
+
+```bash
+lovrabet personal-bff exec --id <id> --params '{"status":"active"}' --format compress
+```
+
+确认字段、空态和错误形状后，再按下游调用方的契约完成接入。

package/skills/lovrabet/references/lovrabet-schedule-workflow.md

@@ -0,0 +1,175 @@
+# 创建和管理定时任务
+
+使用 `lovrabet schedule` 校验、创建、查看、立即运行和删除当前应用的定时任务。
+
+## 准备定时任务
+
+开始前确认：
+
+- 当前 AccessKey 对目标应用有权限。
+- `--app`、`--appcode` 或当前工作目录指向正确应用。
+- 时间统一使用 UTC。
+- prompt 是完整、可重复执行的任务说明，不依赖当前对话中的临时上下文。
+- prompt 不包含 AccessKey、密码或其他明文凭证。
+
+定时任务分为：
+
+- `CRON`：按五段 UTC cron 表达式重复执行。
+- `ONCE`：在一个 UTC 时间执行一次。
+
+五段 cron 的顺序是：
+
+```text
+minute hour day-of-month month day-of-week
+```
+
+支持数字、`*`、范围、列表和 step。不要使用秒字段、月份英文名或星期英文名。
+
+## 校验周期任务
+
+先校验输入，不创建计划：
+
+```bash
+lovrabet schedule validate \
+  --kind CRON \
+  --cron '0 9 * * 1-5' \
+  --title '工作日销售日报' \
+  --prompt '汇总昨日销售数据并生成报告' \
+  --channel auto
+```
+
+检查返回的 `kind`、`timezone`、`cron`、`title`、`prompt` 和 `channel`。
+
+## 校验单次任务
+
+`--scheduled-at` 使用 canonical UTC ISO datetime，至少晚于当前时间 60 秒，最多晚于当前时间 365 天：
+
+```bash
+lovrabet schedule validate \
+  --kind ONCE \
+  --scheduled-at '2026-08-01T01:30:00.000Z' \
+  --title '发布前检查' \
+  --prompt '检查当前应用的发布资料' \
+  --channel premium
+```
+
+不要同时传 `--cron` 和 `--scheduled-at`。
+
+## 创建定时任务
+
+先预览：
+
+```bash
+lovrabet schedule create \
+  --kind CRON \
+  --cron '0 9 * * 1-5' \
+  --title '工作日销售日报' \
+  --prompt '汇总昨日销售数据并生成报告' \
+  --channel auto \
+  --dry-run
+```
+
+把以下信息交给用户确认：
+
+- 应用
+- UTC 时间或 cron
+- 是否重复执行
+- 标题
+- 完整 prompt
+- channel
+
+用户明确确认后执行：
+
+```bash
+lovrabet schedule create \
+  --kind CRON \
+  --cron '0 9 * * 1-5' \
+  --title '工作日销售日报' \
+  --prompt '汇总昨日销售数据并生成报告' \
+  --channel auto \
+  --yes
+```
+
+只有返回 `scheduleId` 才表示计划创建成功。保存该值，用于详情、立即运行和删除。
+
+## 查看定时任务
+
+查看第一页：
+
+```bash
+lovrabet schedule list --limit 20
+```
+
+返回 `nextCursor` 时，把它原样传给下一次查询：
+
+```bash
+lovrabet schedule list --limit 20 --cursor '<NEXT_CURSOR>'
+```
+
+不要解析、修改或拼接 cursor。
+
+查看详情：
+
+```bash
+lovrabet schedule detail --schedule-id <SCHEDULE_ID>
+```
+
+list 和 detail 不返回完整 prompt。不要根据详情猜测或恢复创建时的 prompt。
+
+当前没有 update、pause 或 resume 命令。需要修改时，先确认删除旧计划，再创建新计划。
+
+## 立即运行一次
+
+先查看详情并预览：
+
+```bash
+lovrabet schedule detail --schedule-id <SCHEDULE_ID>
+lovrabet schedule run --schedule-id <SCHEDULE_ID> --dry-run
+```
+
+用户明确确认后执行：
+
+```bash
+lovrabet schedule run --schedule-id <SCHEDULE_ID> --yes
+```
+
+返回 `taskId` 和 `status=QUEUED` 只表示 Task 已接收，不表示已经完成。保留 `taskId`；
+无法从当前 CLI 核对终态时，明确说明“已进入队列，执行结果尚未验证”，不要声称任务成功。
+
+## 删除定时任务
+
+先查看目标并预览：
+
+```bash
+lovrabet schedule detail --schedule-id <SCHEDULE_ID>
+lovrabet schedule delete --schedule-id <SCHEDULE_ID> --dry-run
+```
+
+用户明确确认后执行：
+
+```bash
+lovrabet schedule delete --schedule-id <SCHEDULE_ID> --yes
+```
+
+删除只停止未来触发，不会取消已经创建的 Task。不要把“计划已删除”表述为“正在执行的
+Task 已取消”。
+
+## 处理失败
+
+| `errorCode` | 处理 |
+| --- | --- |
+| `UNAUTHORIZED` | 重新确认 AccessKey |
+| `ACCESS_KEY_SCOPE_MISMATCH` | 停止操作，确认目标应用权限 |
+| `SCHEDULE_NOT_FOUND` | 刷新列表；ONCE 计划可能已经执行并消失 |
+| `SCHEDULE_CONFLICT` | 重新读取列表和详情后再判断 |
+| `SCHEDULE_INPUT_INVALID` | 修正 UTC 时间、cron 或字段组合 |
+| `ACCESS_KEY_AUTH_UNAVAILABLE` | 保留输入，稍后重试 |
+| `SCHEDULE_CONTROL_UNAVAILABLE` | 不伪造成功结果，稍后重试 |
+
+## 检查完成结果
+
+- create 返回真实 `scheduleId`。
+- list 或 detail 能查到新计划。
+- run 返回 `taskId` 时只报告已进入队列。
+- delete 后列表不再包含该计划。
+- 没有把删除计划误写成取消既有 Task。