@lark-base-open/base-database-cli 1.0.0 → 1.1.1

package/skills/lark-base-database/references/database-capability-skill.md

@@ -1,24 +1,40 @@
 # 应用能力 Skill
 
-能力 Skill 使用 `base-database-<hash>` 名称和 `base-database-managed-skill` 管理标记。
-命令统一使用 `database-skill`；同一应用和环境使用固定目录，安装或部署时更新本工具管理的 `SKILL.md`，保留附加文件。
-目标目录的管理标记不匹配或存在符号链接冲突时停止并报告，不覆盖冲突内容。
+本应用 Skill 用于在后续会话中发现并调用已发布的正式版 Function，不依赖建站工程。生成文件仅保存应用、环境与 profile 定位、发现及调用流程，不缓存 Function 列表或参数 Schema，不包含凭证、源码或工程绝对路径。当前发现范围仅限 应用所有者；安装成功不证明接口已开通或当前用户有访问权限。
 
-部署成功时 CLI 自动安装/更新本应用 Skill，结果在 `agentGuide.skill`。模板由 CLI 包维护，生成文件只包含应用和环境定位、发现及调用流程，不缓存 Function 列表或参数 Schema，不包含凭证、源码或工程绝对路径。
+## 安装与恢复
 
-安装失败、需要重新生成或要安装到另一 Agent 的用户技能目录时，使用发布结果中的真实应用 token，以及已确认的应用名称：
+普通 `deploy` 在本次 Preview / Prod 轮询成功后自动安装或更新本地 Skill；安装结果在 `agentGuide.skill`。按实际证据交付：
+
+| 返回状态 | 可报告的结果 | 后续动作 |
+| --- | --- | --- |
+| `installed` / `updated` | 本地安装成功，附 `name`、`path` | 核对目标客户端的发现目录，再按客户端方式刷新 |
+| `failed` | 应用发布成功，但 Skill 安装失败 | 说明 `error`，处理目录权限或冲突；此分支没有 `name`、`path` |
+| 仅通过 `deployments status` 查询或恢复发布成功 | 发布成功，Skill 安装状态未确认 | 不假定安装成功；需要时显式安装 |
+
+`deployments status`（包括 `--wait`）只查询发布任务并按需恢复回执，不安装 Skill，也不返回 `agentGuide`。补装不需要再次 deploy。使用发布结果中的真实 应用 appToken 和已确认的应用名称：
 
 ```bash
-npx @lark-base-open/base-database-cli database-skill install --app-token <app-token> --title '<应用名称>'
+base-database-cli --profile <profile-name> database-skill install --app-token <app-token> --title '<应用名称>'
 ```
 
-默认安装到 `$CODEX_HOME/skills`，未配置时使用 `~/.codex/skills`。`--dir <skills-root>` 可指定其他 Agent 的技能目录。此操作只安装本地 Skill，不发布应用、不调用远端、不更改授权。安装器仅更新带有相同应用/环境管理标记的 `SKILL.md`；无管理标记的文件、同名目录或符号链接冲突会报错，先向用户说明，不删除冲突内容。
+此操作通过 `lark-cli config show` 读取所选账号的本地元信息，再安装 Skill，不发布应用、不调用远端、不更改授权。安装器仅更新带有相同应用/环境/profile 管理标记的 `SKILL.md`；无管理标记的文件、同名目录或符号链接冲突会报错。报告冲突路径，不删除用户文件来强行安装。
+
+默认安装到 `$CODEX_HOME/skills`，未配置时使用 `~/.codex/skills`。其他客户端可通过 `--dir <skills-root>` 指定其实际技能目录，但先确认目标路径可写且被客户端发现。不能由“文件已写入”推断“当前 Agent 已加载”；目录正确时才尝试客户端支持的刷新或重开会话。受管沙箱可能使用另一发现目录或只读技能目录，不能为安装擅自修改其全局配置或权限。
+
+跨设备使用须在目标设备安装对应 CLI 和 Skill，并完成该环境的用户登录。沙箱内安装不等于用户电脑已安装；不能通过拷贝凭证完成迁移。
 
-后续使用不需要应用开发工程目录。已安装的 Skill 会通过以下独立入口实时发现正式版能力，并根据 Schema 调用；环境由当前 CLI 固定，不支持在调用参数里覆盖环境或用户身份：
+独立 `database-skill` 命令不读取项目配置，修复安装时显式传入部署使用的 profile。发现与调用固定该 profile，不跟随默认账号变化；宿主提供凭证且未选择 profile 时保持宿主凭证模式，不写入本地 profile。跨设备须配置并授权同名 profile；缺失或与注入凭证冲突时停止，不回退其他账号。
+
+## 发现与调用
+
+后续命令可在任意目录执行；环境由当前 CLI 固定，不支持在调用参数里覆盖环境或用户身份：
 
 ```bash
-npx @lark-base-open/base-database-cli database-skill discover --app-token <app-token> --page-size 20
-npx @lark-base-open/base-database-cli database-skill invoke --app-token <app-token> --function-id <发现的-id> --params '<业务参数JSON>'
+base-database-cli --profile <profile-name> database-skill discover --app-token <app-token> --page-size 20
+base-database-cli --profile <profile-name> database-skill invoke --app-token <app-token> --function-id <发现的-id> --params '<业务参数JSON>'
 ```
 
-`invoke --params` 是业务值本身（SQL 为数组），CLI 只包一层 `params` 并固定使用 `env=prod`。写操作需要用户明确授权对应业务动作；自动安装不构成写入授权。跨设备使用必须在目标设备安装对应 CLI 和 Skill，并完成该环境的用户登录，不能拷贝凭证。
+发现始终读取正式版。Preview 部署不代表正式版已有对应能力；不要因安装而额外发现或调用正式版，本次约定的 Preview 数据验证与通知收尾仍须完成。
+
+`invoke --params` 是业务值本身（SQL 为数组），CLI 只包一层 `params` 并固定使用 `env=prod`。仅按实时发现的 Function 与 Schema 调用。写操作需用户明确授权相应业务动作，自动安装不构成授权；写入结果未知时仅用已发现的只读能力核对，无法核对则保留待确认，不自动重试写入。