@lovrabet/lovrabet-cli 2.1.23 → 2.2.0

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

@@ -0,0 +1,111 @@
+# Custom SQL 查询工作流
+
+查看和执行 Custom SQL。Custom SQL 在 Lovrabet 平台上创建，CLI 用于查看详情和执行。
+
+## 前置条件
+
+- `sql detail` 和 `sql exec` 使用当前 CLI 认证，默认推荐 **accessKey（client-ak）**
+
+## 先判断 app 是否明确
+
+`sql` 命令组也不要默认先查 app。
+
+### 可以直接进入 Detail 的场景
+
+以下情况直接进入 `sql detail`，但不能跳过契约与数据范围核对：
+
+- 用户已经给了 `--appcode`
+- 用户已经给了 `--app <name>`
+- 当前问题明显沿用上文已确认的同一 app 上下文
+- 用户明确说“当前应用”“默认应用”，且没有新的业务域线索
+
+`defaultApp` 只是默认候选。Custom SQL 可能按业务域分布在不同 app 中；用户提到新的业务域且未指定 app 时，先把 `defaultApp` 当第一个候选验证，验证不成立再扩大到应用列表。
+
+### 需要先做应用决议的场景
+
+以下情况才扩大到 `lovrabet app list`：
+
+- 用户只给了业务需求，没有明确说明是哪个应用里的 Custom SQL
+- 当前没有显式 `--appcode` / `--app`，且需求包含业务域线索
+- 同一类业务可能落在多个 app 中
+- 已经把 `defaultApp` 作为候选检查过，但无法确认它承载本次 Custom SQL
+
+推荐方式：
+
+1. 有 `defaultApp` 时，先把它作为第一个候选
+2. 无法确认默认候选承载本次 Custom SQL 时，再 `lovrabet app list`
+3. 用业务关键词选 1-2 个候选 app
+4. 从业务 Skill、可信 Service Tree、前序已确认上下文或可信 KB 候选定位 Custom SQL；无法唯一定位时停止，不猜测
+5. 再回到 `lovrabet sql detail`；契约、参数和数据范围核对通过后才执行 `sql exec`
+
+## sql detail — 查看 Custom SQL 详情
+
+```bash
+lovrabet sql detail --sqlcode <code>
+
+# 返回原始完整 API 响应
+lovrabet sql detail --sqlcode <code> --verbose
+```
+
+| Flag | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--sqlcode` | string | **是** | Custom SQL 标识字段 `sqlCode`，格式：`xxxxxxxx-xxxxxxxx`（8 位 hex + 8 位 hex） |
+| `--verbose` | boolean | 否 | 返回完整原始对象 |
+
+**输出**：Custom SQL 名称、SQL 内容和关联的数据库等。
+
+Custom SQL 只有在标识来源可信、所属应用匹配且 Detail 实际返回的名称、数据库和 SQL 内容与当前任务一致时，才作为稳定查询规则复用。`sql detail` 不单独提供参数约束或副作用契约；缺失信息仍视为未知。Custom SQL 已存在或 `detail` 成功本身不代表业务口径正确，也不代表已经获得执行授权。
+
+SQL 内容属于敏感实现资产。当前 `sql detail` 会按真实接口返回 SQL 内容，Agent 只用于当前任务的契约核对，不写入 KB、业务 Skill、日志或全量规则目录，最终答复默认不回显；用户明确要求查看时，也只能在服务端授权成功后按最小必要范围展示。不提供 `sql list` 只能降低批量枚举和暴露面，不能替代服务端资源级授权；`detail` 与 `exec` 仍需按当前 AK、应用和具体 Custom SQL 独立鉴权，知道或猜到 `sqlCode` 不代表有权查看或执行。
+
+## sql exec — 执行 Custom SQL
+
+```bash
+# 无参数执行
+lovrabet sql exec --sqlcode <code>
+
+# 带参数执行
+lovrabet sql exec --sqlcode <code> --params '{"status":"active"}'
+```
+
+| Flag | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--sqlcode` | string | **是** | Custom SQL 标识字段 `sqlCode`，格式：`xxxxxxxx-xxxxxxxx` |
+| `--params` | string | 否 | 查询参数，JSON 格式 |
+
+**CLI 风险元数据**：`read`。这只反映命令注册，不代表真实副作用。Custom SQL 可能包含业务写入、`DROP`、`TRUNCATE` 等破坏性语句；执行前必须核对 SQL 内容、权限和用户授权，副作用不明确时不自动执行。
+
+**输出**：查询结果数据，格式由 `--format` 控制。
+
+## 典型工作流
+
+```bash
+# 0. 如果默认候选验证不成立，再看应用目录
+lovrabet app list
+
+# 1. 如果不知道 sqlCode，从业务 Skill、可信 Service Tree、
+#    前序已确认上下文或可信 KB 候选定位；无法唯一定位时停止
+
+# 2. 查看 Custom SQL 详情，核对名称、数据库和 SQL 内容
+lovrabet sql detail --sqlcode 2305f915-dd48cd4c
+
+# 3. 核对契约、参数和数据范围后执行 Custom SQL
+lovrabet sql exec --sqlcode 2305f915-dd48cd4c --params '{"status":"active"}'
+
+# 4. 指定 JSON 格式输出，便于程序解析
+lovrabet sql exec --sqlcode 2305f915-dd48cd4c --params '{"status":"active"}' --format json
+```
+
+## 注意
+
+- Custom SQL 标识字段 `sqlCode` 的格式为 `{8位hex}-{8位hex}`，如 `2305f915-dd48cd4c`
+- `--params` 必须是合法 JSON 字符串
+- `lovrabet` 没有 `sql list` 命令；`sqlCode` 必须来自用户明确输入、业务 Skill、可信 Service Tree、前序已确认上下文或可信 KB 候选
+- 运行态发现业务能力，不枚举 Custom SQL 实现资产；基础事实查询优先使用已治理 Dataset，稳定规则由业务 Skill 或可信 Service Tree 绑定到已发布 Custom SQL
+- 不知道 `sqlCode` 时不猜测，也不从 Dataset 原始字段重写已有稳定规则
+- 当业务归属不清时，先验证 `defaultApp`；验证不成立再 `app list` 做应用决议，再去确认 `sqlCode`，而不是直接盲猜当前 app
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [instant-api-workflow.md](instant-api-workflow.md)

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

@@ -0,0 +1,34 @@
+# update — 一体更新 CLI 与 Built-in Skill
+
+`lovrabet update` 从 npm registry 查询 CLI 包的 dist-tags，不依赖 CDN 配置文件。CLI 与 Built-in Skill 一体升级，不提供拆分升级模式。
+
+默认升级入口是 `lovrabet update`；beta 预览和精确版本复现才使用对应选项。
+
+## 命令
+
+```bash
+# 默认等价于 --latest
+lovrabet update
+
+lovrabet update --latest
+lovrabet update --beta
+lovrabet update --version <version>
+```
+
+`--latest`、`--beta`、`--version <version>` 互斥；精确版本必须是完整 semver，例如 `2.1.23` 或 `2.2.0-beta.1`。
+
+## 行为
+
+- npm 安装包携带同版本 Built-in Skill，安装阶段自动完成 Agent Skill 安装。
+- CLI 升级成功后，旧进程只验证目标版本 Skill 是否已安装，不使用旧包内容重复覆盖。
+- CLI 已经是目标版本时，命令从当前 npm 包内检查并修复 Built-in Skill。
+- Skill 缺失、版本不一致或验证失败时，命令返回失败并提示 `lovrabet cli-skill install`；不要把“CLI 包已更新”误报为完整成功。
+- `lovrabet skill install` 仍只管理当前应用的业务 Skill，与 Built-in Skill 生命周期相互独立。
+
+手动复现或修复 npm 安装问题时，可以使用：
+
+```bash
+npm install -g @lovrabet/lovrabet-cli@<version>
+lovrabet doctor
+lovrabet cli-skill install
+```

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

@@ -0,0 +1,82 @@
+# workspace — 工作目录配置
+
+`workspace` 用来给**当前工作目录**绑定默认应用。适合 WorkBuddy、Agent 项目目录、客户交付目录这类“打开一个目录就知道默认操作哪个应用”的场景。
+
+它解决的是本地使用体验，不是平台权限配置：
+
+- 配置文件固定写到当前目录的 `.lovrabet.json`
+- 不写 AccessKey
+- 不同步远端应用目录
+- 不影响其他目录
+
+## 命令
+
+```bash
+lovrabet workspace init --appcode <appcode> [--env daily]
+lovrabet workspace init --app <name> [--env daily]
+lovrabet workspace use --appcode <appcode> [--env daily]
+lovrabet workspace use --app <name> [--env daily]
+```
+
+`init` 和 `use` 对应不同的目录生命周期：
+
+- `init`：只为尚未绑定应用的目录建立 Lovrabet 应用上下文；已有绑定时停止并提示使用 `use`
+- `use`：只修改已有应用绑定；尚未绑定时停止并提示先使用 `init`
+
+状态判断只读取当前目录 `.lovrabet.json`，不会把全局配置中的应用选择当作当前目录已经初始化。只有顶层非空 `appcode`，或 `defaultApp` 指向有效的 `apps.<name>.appcode`，才算已有活动绑定；旧字段、未选中的 alias 和无效 `defaultApp` 不算绑定。配置文件只包含 `format`、域名等非应用字段时，仍可执行 `init`。
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `--app <name>` | 应用名称。CLI 会用当前 AK 在指定环境的已发布应用列表中解析 appcode |
+| `--appcode <code>` | 直接写入 appcode，不需要远端查询 |
+| `--env <env>` | 可选。写入当前目录配置，取值为 `production` / `development` / `daily` |
+
+必须且只能传 `--app` 或 `--appcode` 之一。
+
+## 写入效果
+
+直接用 appcode：
+
+```bash
+lovrabet workspace init --appcode app-64e32817 --env daily
+```
+
+当前目录 `.lovrabet.json`：
+
+```json
+{
+  "env": "daily",
+  "appcode": "app-64e32817"
+}
+```
+
+用业务名称绑定默认应用：
+
+```bash
+lovrabet workspace use --app crm --env daily
+```
+
+当前目录 `.lovrabet.json`：
+
+```json
+{
+  "env": "daily",
+  "defaultApp": "crm",
+  "apps": {
+    "crm": {
+      "appcode": "app-64e32817"
+    }
+  }
+}
+```
+
+## 注意事项
+
+- 不要主动创建或修改工作目录配置；只有用户明确要求“初始化当前目录”“记住这个应用”“绑定这个工作目录”等语义时，才执行 `workspace init/use`
+- 执行前先判断当前目录状态：没有应用绑定用 `workspace init`，已有应用绑定用 `workspace use`
+- 如果连续多次在同一目录使用同一个 app 或 appcode，可以提醒用户是否要写入当前目录 `.lovrabet.json`，但必须先得到明确同意
+- `--app <name>` 需要当前已有合法 AccessKey，因为 CLI 要查询当前 AK 可见的应用列表
+- 未发布应用不能被绑定为工作目录默认应用
+- 如果只是临时执行一次命令，优先直接在目标命令上传 `--app` 或 `--appcode`

package/skills/lovrabet.manifest.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "name": "lovrabet",
+  "packageName": "@lovrabet/lovrabet-cli",
+  "packageVersion": "2.2.0",
+  "skillVersion": "2.2.0",
+  "files": [
+    "SKILL.md",
+    "guides/app-resolution.md",
+    "guides/dataset-and-data-workflow.md",
+    "guides/sql-and-bff-workflow.md",
+    "guides/troubleshooting.md",
+    "references/dataset-discovery-workflow.md",
+    "references/instant-api-workflow.md",
+    "references/lovrabet-app-config.md",
+    "references/lovrabet-app.md",
+    "references/lovrabet-auth.md",
+    "references/lovrabet-bff-workflow.md",
+    "references/lovrabet-config-commands.md",
+    "references/lovrabet-config.md",
+    "references/lovrabet-doctor.md",
+    "references/lovrabet-file-workflow.md",
+    "references/lovrabet-kb-workflow.md",
+    "references/lovrabet-logs.md",
+    "references/lovrabet-ocr-workflow.md",
+    "references/lovrabet-output-format-jq.md",
+    "references/lovrabet-personal-bff-workflow.md",
+    "references/lovrabet-schedule-workflow.md",
+    "references/lovrabet-service-tree.md",
+    "references/lovrabet-skill-authoring.md",
+    "references/lovrabet-skill-install.md",
+    "references/lovrabet-skill-sync.md",
+    "references/lovrabet-sql-workflow.md",
+    "references/lovrabet-update.md",
+    "references/lovrabet-workspace.md"
+  ],
+  "digest": "41997c71249469e316f2e856791221c8c27d5c389a645745b2ba3361f30f11d2"
+}