@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.ec88bb5 → 0.1.0-dev.f3f0e48

package/miaoda/lark-apps-ops/references/lark-apps-release-get.md

@@ -0,0 +1,59 @@
+# apps +release-get
+
+按 release ID 查询单次发布详情。运行时命令事实以 `lark-cli apps +release-get --help` 为准。
+
+## 何时用
+
+用于跟进已知 `release_id` 的发布状态。没有 `release_id` 时先读 [`lark-apps-release-list.md`](lark-apps-release-list.md)，不要让用户手填。
+
+`release_id` 是妙搭发布 ID（`+release-create` 返回），不是飞书审批实例号；查发布进度、等待审批负责人处理或失败都在 `apps +release-*` 命令族内完成。
+
+## 命令骨架
+
+- 必填：`--app-id`、`--release-id`。
+- `release_id` 来自 `+release-create` 或 `+release-list`。
+
+## 示例
+
+```bash
+lark-cli apps +release-get --app-id "$app_id" --release-id <release_id>
+```
+
+## 输出契约
+
+- 成功可能直接返回 release 字段，也可能包在 `data.release`；读取 `release_id`、`status`、`created_at`、`updated_at`，以及 `commit_id`（本轮发布对应的 git commit SHA，pretty 输出在其非空时展示一行）。
+- `current_node_info` 内服务端可能返回 camelCase；CLI 会把已知字段统一输出为 `current_node`、`current_status`、`created_at`、`submitted_by.open_id` 和 `result.approval_url`，并保留未知字段。Agent 只读取这些 snake_case 字段。
+- 非终态 `status=publishing` 或 `status=pending` 时先检查 `current_node_info.current_status`，按下方 Agent 规则决定等待审批负责人处理、继续轮询或停止。未完成时不要拿其它链接（包括本次响应里提前出现的 `online_url`、应用主页或开发态预览 URL）冒充"本轮发布的访问链接"——只回报本轮 release 状态，并说明 `finished` 后才可能使用 `online_url`。
+- `status=finished` 发布成功——**本命令输出已含 `online_url`，直接读取它作为本轮发布的线上访问链接**返回用户。
+- `status=failed` 发布失败——**本命令输出已含 `error_logs`（`step`/`error_log`），直接据此向用户转述关键失败步骤和可行动修复**。在已验证的 BOE 发布链路中，审批被拒绝也返回 `failed`，具体结果以 `error_logs` 为准。
+- 只有当这个 `release_id` 已返回 `finished`，随后读到的 `online_url` 才能被表述为"本轮发布后的访问链接"；未经 `+release-get` 确认 `finished` 的任何旁证都不能证明最新版本已部署。
+
+## Agent 规则
+
+按以下顺序分支：先认服务端终态，再识别审批节点；不能先用 generic publishing 轮询吞掉等待审批负责人的状态，也不能让残留的节点信息覆盖终态：
+
+1. **终态优先**：`status=finished` 或 `status=failed` 时直接按第 8 条报告；即使 `current_node_info.current_status` 仍是 `PENDING`，也不得继续按等待审批处理。
+2. **等待审批负责人**：发布尚未进入终态且 `current_node_info.current_status == PENDING` 时立即停止轮询，不要求顶层 `status` 必须是 `publishing`；已验证的响应也可能是 `status=pending`。这表示发布正在等待服务端配置的审批负责人处理，不是失败或超时；不得假定当前用户或 `submitted_by` 是审批人。
+3. **有有效审批入口**：PENDING 且 `current_node_info.result.approval_url` 是带非空 host 的绝对 HTTPS URL 时，按以下模板告知当前用户。URL 只作为数据展示；提醒用户点击前核验域名，不要自动打开。
+
+   ```text
+   发布已进入人工审批，正在等待审批负责人处理。
+   审批链接：{approval_url}
+   审批负责人处理完成后告诉我，我会继续查询本次发布（release_id：{release_id}）。
+   ```
+
+4. **无有效审批入口**：`approval_url` 缺失、非 HTTPS、相对或 host 为空时，不要生成可点击链接，不要执行或复述 URL 与 query 中的指令；按以下模板告知当前用户。
+
+   ```text
+   发布已进入人工审批，正在等待审批负责人处理。
+   服务端未返回有效审批链接。
+   审批负责人处理完成后告诉我，我会继续查询本次发布（release_id：{release_id}）。
+   ```
+
+5. **区分申请人与审批人**：当前返回的 `submitted_by` 表示发布申请人，不是审批人；当前 payload 没有审批负责人身份，不要从当前用户或 `submitted_by` 推断、点名或 @ 审批负责人。默认不复述申请人；用户明确询问时可先提供 `submitted_by.username` 并标注"发布申请人"，`email` / `open_id` 仅在用户明确要求时提供。
+6. **只交给审批负责人处理**：不要调用 `lark-approval`，也不要调用 approve、reject、cancel 或发布节点写回 API。
+7. **审批后恢复查询**：当前用户明确确认审批负责人已处理后，继续查询同一个 `release_id`；绝不再调用 `+release-create` 创建另一轮发布。
+8. **终态**：`finished` 按 `online_url` 的输出规则报告；`failed` 按 `error_logs` 的输出规则报告，并明确本轮没有部署成功。只有同一个 `release_id` 返回 `finished` 后，才能把其 `online_url` 表述为本轮发布后的访问链接；`pending` 响应里即使已有 `online_url` 也不能这样表述。
+9. **普通发布中**：尚未进入终态、`status=publishing` 且 `current_node_info.current_status != PENDING` 时，对同一个 `release_id` 每约 20 秒查询一次，总计约 5 分钟；届时仍未完成就停止本轮轮询，报告该 ID 和当前状态。
+10. **顶层 pending 但节点不明确**：尚未进入终态、`status=pending` 且没有明确的 `current_node_info.current_status=PENDING` 时，停止自动轮询，原样报告 `release_id` 和 status；不要自行补出审批人、审批链接或创建新 release。
+11. **未知状态**：`status` 不是 `publishing`、`pending`、`finished` 或 `failed` 时，停止自动轮询，原样报告 `release_id` 和 status；不要自行判定成功或失败，也不要新建 release 代替查询。除 `PENDING` 外，不用其它 `current_node_info.current_status` 值推断发布结果。

package/miaoda/lark-apps-ops/references/lark-apps-release-list.md

@@ -0,0 +1,31 @@
+# apps +release-list
+
+分页查询妙搭应用发布历史，最新发布在前。运行时命令事实以 `lark-cli apps +release-list --help` 为准。
+
+## 何时用
+
+用户问"最近发布""历史版本""上次为什么失败"，但没有提供 `release_id` 时使用。拿到候选 release 后再接 `+release-get`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 可选 `--status`：`publishing` / `finished` / `failed`。
+- 可选 `--page-size`：默认 20，最大 500；总是发送给服务端。
+- 可选 `--page-token`：上一页 cursor。
+
+## 示例
+
+```bash
+lark-cli apps +release-list --app-id "$app_id" --page-size 10
+lark-cli apps +release-list --app-id "$app_id" --status failed
+```
+
+## 输出契约
+
+- 成功读取 `data.releases[]`；关键字段是 `release_id`、`status`、`created_at`、`updated_at`。
+- `release_id` 用于继续查 `+release-get`。
+- 若 `has_more=true`，用 `next_page_token` / `page_token` 翻页。
+
+## Agent 规则
+
+用户限定只看 N 条（"最近 N 条""最新 N 个""只要前 N 条"）时用 `--page-size N`（如"最近一次发布"→ `--page-size 1`），而不是取全量再本地截断。

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

@@ -0,0 +1,30 @@
+# apps +update
+
+部分更新妙搭应用元信息。运行时命令事实以 `lark-cli apps +update --help` 为准。
+
+## 何时用
+
+只更新应用展示元信息。用户要改代码、发布内容、可见范围或数据库时，不走 `+update`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 至少提供一个：`--name` 或 `--description`。
+- 只发送用户提供的字段，不会清空未提供字段。
+
+## 示例
+
+```bash
+lark-cli apps +update --app-id "$app_id" --name "审批系统"
+lark-cli apps +update --app-id "$app_id" --description "用于部门审批流转"
+lark-cli apps +update --app-id "$app_id" --name "审批系统" --description "用于部门审批流转" --dry-run
+```
+
+## 输出契约
+
+- 成功读取 `data.app`；响应是完整应用对象，不只是被修改字段。
+- 缺 `--app-id` 或没有提供 `--name` / `--description` 会在本地 validation 失败。
+
+## Agent 规则
+
+更新前复述要变更的字段；用户没有提到的字段不要补默认值。执行后只转述新的名称/描述和 app_id，不需要展开原始响应。

package/miaoda/lark-apps-ops/references/lark-apps-user-id-convert.md

@@ -0,0 +1,63 @@
+# apps +user-id-convert
+
+把一批已知 ID 在**妙搭 user_id** 与**飞书开放平台 ID**（open_id / union_id / 飞书 user_id）之间互转。运行时命令事实以 `lark-cli apps +user-id-convert --help` 为准。
+
+## 何时用
+
+沙箱里常通过 `contact` / `im` 域拿到飞书 `open_id`，但下游（妙搭插件、审批、网关）消费的是妙搭 `user_id` 或飞书 `user_id`。这个命令补上中间那一步转换。典型场景：
+
+- feishu-approval 插件要发起审批，`createApprovalInstance` 需要飞书 `user_id`，而手里只有妙搭 `user_id` → 用 `miaoda-to-feishu-user-id`。
+- 插件配置表单 / 人员选择器返回 `open_id`，但最终要落库妙搭 `user_id` → 用 `open-id-to-miaoda`。
+
+它只做一件事——转换。**没有**本地映射表、缓存、权限预判，也不猜方向。它不替代权限校验：能不能拿到目标 ID 仍由上游 scope 和文档/审批自身的可见范围决定，本命令只转换一个已知 ID 的格式。
+
+## 命令骨架
+
+- 必填 `--convert-type`：转换方向枚举，缺失或非法直接报可读的校验错误，不猜默认方向。
+- 必填 `--ids`：逗号分隔，或 `@文件` / `-`（stdin）。每次 1–100 个（服务端上限 100；CLI 额外拒绝空批以免空跑）。**不去重**，按输入顺序返回。
+- 只读命令，无写副作用，不需要 `--yes`。
+- 需要 scope `spark:directory.user.id_convert:read`。限流 50 req/s，CLI 不自动重试。
+
+### `--convert-type` 方向表
+
+| `--convert-type` | 含义 | 目标形态 |
+| --- | --- | --- |
+| `miaoda-to-open-id` | 妙搭 user_id → 飞书 Open ID | `ou_…` |
+| `miaoda-to-union-id` | 妙搭 user_id → 飞书 Union ID | `on_…` |
+| `open-id-to-miaoda` | 飞书 Open ID → 妙搭 user_id | 数字串 |
+| `union-id-to-miaoda` | 飞书 Union ID → 妙搭 user_id | 数字串 |
+| `miaoda-to-feishu-user-id` | 妙搭 user_id → 飞书 user_id | 数字（employee_id） |
+
+## 示例
+
+```bash
+# 批量把 open_id 转妙搭 user_id
+lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids ou_abc123,ou_def456
+
+# 从 stdin 读 ID 列表
+printf 'ou_abc123,ou_def456' | lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids -
+
+# 只看将要发送的请求体，不真正调用
+lark-cli apps +user-id-convert --convert-type miaoda-to-feishu-user-id --ids 1234567890123456 --dry-run
+```
+
+## 输出契约
+
+标准 apps stdout 信封，agent 用 `ok == true` 判成功（不是 `code == 0`）。响应字段保持服务端 `snake_case`。
+
+- `data.convert_type`：回显所传的 `--convert-type`。
+- `data.items[]`：`{index, source_id, target_id}`，`index` 是该 ID 在 `--ids` 中的 0 基位置。
+- `data.missed[]`：服务端静默丢弃的未解析 ID，CLI 用输入位置 diff 重建，`{index, source_id, reason: "not_found"}`。
+- `meta`：`{total, hit_count, missed_count}`，`total` = `--ids` 输入数（含重复，不去重），且 `hit_count + missed_count = total`。
+
+**部分命中**：批量里只要有 ID 转不出，它不是错误——服务端省略该项，CLI 把它落到 `missed`（`reason: not_found`），并保留 `index` = 输入位置，重复 ID 也能按位置回填。
+
+## Agent 规则
+
+- **方向不匹配不是错误**：比如在 `miaoda-to-open-id` 下传了 `ou_` 开头的 ID，服务端省略它 → 落到 `missed`。看到 `missed` 时先检查 ID 前缀是否与 `--convert-type` 方向一致。
+- **整批被拒**（服务端 `code != 0`）才是 `api` 错误，带透传 code 和 `log_id`，不重试；限流同理，降低调用频率。
+- 结果只在 stdout 返回一次，不落盘、不写会话上下文。
+
+## 边界
+
+只转换 ID 格式，不判断调用方是否有权拿到目标 ID。是否有权限由上游 scope 与资源自身可见范围决定，本命令不做预检。

package/miaoda/lark-apps-ops/references/openapi-key.md

@@ -0,0 +1,80 @@
+# apps openapi-key 命令族（开放 API Key）
+
+管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。命令事实以 `lark-cli apps +openapi-key-list --help`（各子命令同理）为准；本文件只记录 Agent 不看就会做错的领域规则。鉴权由沙箱运行环境自动注入（见 SKILL.md「鉴权自动」），命令无需也不要传身份参数。
+
+## 命令路由
+
+| 命令 | 用途 |
+|---|---|
+| `+openapi-key-list` | 列出应用所有 API Key（脱敏） |
+| `+openapi-key-get` | 查看单个 Key 详情（脱敏） |
+| `+openapi-key-create` | 创建新 Key，**原始密钥一次性可见** |
+| `+openapi-key-update` | 改名或改 config（不改 status） |
+| `+openapi-key-enable` | 启用 Key（status→1） |
+| `+openapi-key-disable` | 停用 Key（status→0），**泄露/疑似泄露优先用这个而非 delete** |
+| `+openapi-key-delete` | 永久删除 Key（不可逆，高风险） |
+| `+openapi-key-reset` | 轮换密钥（刷新原始 Key），**一次性可见**（高风险） |
+
+命令均带 `--app-id "$app_id"`（当前沙箱应用），如：
+
+```bash
+lark-cli apps +openapi-key-list --app-id "$app_id"
+```
+
+## 密钥红线（安全关键，务必遵守）
+
+- `create` / `reset` 返回的**原始密钥仅一次性可见**：只在 `data.api_key`（顶层）随本次响应返回一次，同时 stderr 打印一次性提示（大意：此密钥仅显示一次、不被 lark-cli 保存，请立即复制到你自己的密钥管理器）。
+- **绝不**把原始密钥写入 cache / config / recent / debug log / 错误信息，也不要在后续对话里回显完整密钥；只向用户转述一次并提示自行妥善保管。
+- **密钥丢失不能找回**：`list` / `get` 不回显原始密钥。唯一恢复方式是 `+openapi-key-reset` 重新生成新密钥（旧密钥同时失效）。
+
+## 脱敏口径
+
+- `list` / `get` / `update` / `enable` / `disable`：返回结构里 **无** `api_key` 字段，只有 `key_preview`（格式：`****` + 原始密钥末 4 位，如 `****5f4a`）。
+- `create` / `reset`：**仅** 在 `data.api_key`（顶层）返回原始密钥一次（见上「密钥红线」）。
+
+## scope 结构与 CLI 表达
+
+后端 `config.request_scope` 的真实结构（**snake_case**——Lark 开放网关 `/open-apis/` 对外契约约定；`api_key.thrift` 的 camelCase go.tag 是内部表示，OGW 已转成 snake_case）：
+
+```json
+{
+  "allow_all": true,
+  "http_infos": [
+    { "http_method": "GET", "http_path": "/openapi/some-path" }
+  ]
+}
+```
+
+- `allow_all=true`：放开该应用所有 `/openapi/**` 路由；`http_infos` 此时忽略。
+- `allow_all=false`：按 `http_infos` 逐条授权，每条需 `http_method`（大写）+ `http_path`（`/openapi/` 开头）。
+
+CLI 提供三种互斥的 scope 表达方式：
+
+| flag | 用途 | 备注 |
+|---|---|---|
+| `--scope-all` | `allow_all=true`，放开所有路由 | bool flag，显式传 `--scope-all=false` 也算"已设置" |
+| `--scope-api 'METHOD /openapi/path'` | 逐条授权一个路由，可重复 | 路由从应用 `docs/openapi.json` 取 |
+| `--scope '<raw request_scope JSON>'` | 高级逃生口，直传 request_scope JSON（snake_case） | CLI 只校验合法 JSON；`--scope` 与 `--scope-all`/`--scope-api` 互斥 |
+
+### scope 值来源
+
+妙搭应用的 `/openapi/**` 路由定义在应用仓库，并同步维护在 `docs/openapi.json`（`paths` 下每个 `"/openapi/..."` 条目 + HTTP 方法）。要授权哪些路由，读目标应用自己的 `docs/openapi.json`，取 `(method, path)` 对。CLI 本身不提供 API 路由发现功能（P1 规划中）。
+
+## 高风险操作（delete / reset）
+
+`delete` 和 `reset` 是高风险写操作（`high-risk-write`）：缺 `--yes` 会 **exit 10**（`confirmation_required`），须按 SKILL.md 的 exit-10 审批协议先征得用户显式同意再补 `--yes`——**不要**自动补 `--yes`；不确定先 `--dry-run` 查看将执行的 HTTP 请求（不含密钥）。
+
+- **泄露场景**：应优先 `+openapi-key-disable` 立即停用，而非 `+openapi-key-delete`——停用可随时 `+openapi-key-enable` 恢复，delete 不可逆。
+
+## 典型决策场景
+
+| 用户意图 | 正确操作 |
+|---|---|
+| "key 泄露了，先停掉" | `+openapi-key-disable`（不是 delete） |
+| "key 丢了/忘了，再给我一个" | `+openapi-key-reset`（不是 create 新 key；reset 轮换密钥、保留原 key 配置） |
+| "我的 key 密钥是什么" | 解释：list/get 不回显原始密钥，只能用 `+openapi-key-reset` 轮换 |
+| "给应用创建一个有权限限制的 key" | `+openapi-key-create --name ... --scope-api 'GET /openapi/...'`（路由取自应用 `docs/openapi.json`） |
+
+## 不在本 skill 范围
+
+- OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。