@lovrabet/lovrabet-cli 2.1.23-beta.4 → 2.2.0

package/skills/lovrabet/references/lovrabet-service-tree.md

@@ -0,0 +1,279 @@
+# Service Tree 业务服务树
+
+Service Tree 把底层 `data` / `sql` / `bff` 命令封装成业务命令，例如：
+
+```bash
+lovrabet crm customer list --status active
+lovrabet crm customer detail 10001
+```
+
+本地 registry 位于 `~/.lovrabet/service.json`。首期 manifest 文件通常由 Git 管理，再通过 `service import` 安装到本机。
+
+## 本地管理命令
+
+```bash
+lovrabet service validate --file ./lovrabet-services/crm.service.json
+lovrabet service validate --file ~/.lovrabet/service.json
+lovrabet service import --file ./lovrabet-services/crm.service.json --dry-run
+lovrabet service import --file ./lovrabet-services/crm.service.json
+lovrabet service import --file ~/.lovrabet/service.json --dry-run
+lovrabet service list
+lovrabet service detail --service crm
+lovrabet service export --service crm --file ./lovrabet-services/crm.service.json
+lovrabet service remove --service crm
+```
+
+`service validate` 只校验 JSON 协议，不写入本地 registry。`service validate/import --file` 同时接受单个 Service Tree manifest 和本地 registry 文件（`~/.lovrabet/service.json`）；传入 registry 时会逐个校验或导入其中保存的原始 manifest。`service import` 会把 manifest 标准化后写入 `~/.lovrabet/service.json`，同一个服务再次导入会替换旧版本。`service export` 从本地 registry 导出 Git 可管理的单个 manifest 文件。`service remove` 只移除本机 registry 条目，不删除 Git 中的 manifest 文件，也不会访问服务端。
+
+## 意图识别与主动发现
+
+当用户说的是业务目标，而不是底层 CLI 命令时，Agent 应先检查本机是否已经导入对应的业务语义服务。典型业务目标包括“查我的需求”“看项目评论”“列出待处理订单”“客户详情”“库存预警”“工单跟进”等。
+
+首选发现命令：
+
+```bash
+lovrabet service list --format compress
+```
+
+`service list` 是本地只读命令，不需要访问服务端。Agent 应使用返回的服务编码、服务名称、服务说明、命令路径、命令说明和 flags 描述来匹配用户意图。匹配明确时，再查看完整服务定义：
+
+```bash
+lovrabet service detail --service <service> --format compress
+```
+
+`service detail` 只读取本地 registry 中已导入的 manifest、标准化绑定和来源信息，不是服务端实时契约。对本地文件来源，返回的 `version`、`importedAt`、`source.path` 和 `source.hash` 可用于核对版本与来源；其他来源应使用与来源类型匹配的来源、新鲜度和兼容性证据，字段缺失本身不是拒绝理由。它可以验证本机路由，却不能证明绑定目标仍已发布、参数未变化或副作用明确；执行前还要使用目标能力支持的可信契约验证通道，并只使用该通道实际返回的字段。
+
+Service Tree 只负责定位入口，不单独证明稳定业务规则已经固化。若绑定目标是 Dataset，稳定规则还必须由业务 Skill、已治理 Dataset 契约或其他平台已确认契约承载；缺少规则契约时只能用于简单低风险事实查询。
+
+完成契约、真实副作用和用户授权判断后，才执行匹配到的动态业务命令：
+
+```bash
+lovrabet <service> [...resourcePath] <action> [flags] --format compress
+```
+
+Service Tree 精确命中时，先把已经绑定的执行入口只作为候选路由。取得与来源类型匹配的来源、新鲜度和兼容性证据，并确认与当前可信业务 Skill 或平台契约没有冲突后，才复用该入口。本地文件来源可以使用 `version`、`importedAt` 和 `source.hash`；后续来源使用各自适配器提供的证据，不把当前字段组合固化为永久门禁。无法确认来源或适用范围时，不得仅凭精确命中执行稳定规则。执行前仍要核对绑定目标、真实副作用和用户授权。
+
+出现弱命中、多个候选或术语边界不清时，先用 `kb search` 做语义消歧。KB 召回只生成候选；Service Tree 候选先用本地 `service detail` 核对绑定，再使用目标能力支持的可信契约验证通道。消歧后仍有多个合理候选时，再列给用户确认。
+
+Service Tree 未命中不是失败条件，也不代表业务能力不存在。本地 registry 可能只注册少量高频服务。没有合理匹配时：
+
+1. 先区分简单低风险事实、稳定规则和高风险确定性判断。
+2. 简单低风险事实可以继续做 app、Dataset 决议，并使用只读 Instant API。
+3. 稳定规则或高风险确定性判断不得直接退化为 Dataset 字段拼装；没有可信能力时输出局部“不判定”，并说明缺少的能力契约。
+4. 只有现有上下文、KB 和只读发现都不能收敛时，才向用户询问一个最关键的补充信息。
+
+用户已经显式给出 `datasetCode`、`sqlCode`、Backend Function 标识，或明确要求执行底层 `data/sql/bff` 命令时，不需要额外跑 Service Tree 发现，直接进入对应 Detail。`--appcode` / `--app` 只是应用上下文，不应单独阻止业务服务发现。
+
+## 推荐 Manifest 写法
+
+推荐使用树状结构：`service` 定义服务入口，`resources` 定义业务对象，`actions` 定义动作。最终命令格式是：
+
+```text
+lovrabet <service> <resource path> <action>
+```
+
+最小示例：
+
+```json
+{
+  "service": "crm",
+  "name": "CRM",
+  "description": "Customer relationship business commands.",
+  "app": "app-xxxxxxxx",
+  "resources": {
+    "customer": {
+      "name": "Customer",
+      "datasetCode": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "actions": {
+        "list": {
+          "description": "List customers.",
+          "flags": {
+            "status": "where.status.$eq",
+            "keyword": {
+              "to": "where.customer_name",
+              "op": "$contain",
+              "description": "Customer keyword."
+            }
+          },
+          "defaults": {
+            "currentPage": 1,
+            "pageSize": 20,
+            "orderBy": [{ "updated_at": "desc" }]
+          }
+        },
+        "detail": {
+          "description": "Get one customer by id.",
+          "action": "getOne",
+          "args": ["id"],
+          "map": {
+            "id": {
+              "target": "id",
+              "transform": "number"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+上面会注册两个业务命令：
+
+```bash
+lovrabet crm customer list --status active --keyword 科技
+lovrabet crm customer detail 10001
+```
+
+等价的底层能力分别是：
+
+```bash
+lovrabet data filter --code aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --params '{"where":{"status":{"$eq":"active"},"customer_name":{"$contain":"科技"}},"currentPage":1,"pageSize":20,"orderBy":[{"updated_at":"desc"}]}'
+lovrabet data getOne --code aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --params '{"id":10001}'
+```
+
+## 顶层字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `service` | 服务编码，进入命令路径，例如 `crm`。也兼容 `{ "code": "crm", "name": "CRM" }`。 |
+| `name` / `description` | 展示名称和说明，会出现在 help、schema、doctor 中。 |
+| `app` | 单应用快捷绑定。可写 appcode 或应用名。 |
+| `apps` | 多应用绑定表，例如 `{ "crm": "app-xxx", "order": { "appcode": "app-yyy", "env": "prod" } }`。 |
+| `appBindings` | 兼容旧命名，语义同 `apps`。 |
+| `defaults` | 服务级默认底层参数，会被资源和动作继承。 |
+| `resources` | 业务对象树。每个节点可继续嵌套 `resources`。 |
+
+不要把 `service` 写成 appcode。一个服务可能串联多个应用，`service` 应表达业务域，例如 `crm`、`order`、`store-ops`。
+
+## Resource 字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `name` / `description` | 业务对象展示信息。 |
+| `appRef` | 引用 `apps` / `appBindings` 里的应用别名。只有多应用时通常需要写。 |
+| `datasetCode` | 数据集 code，推荐优先使用。 |
+| `datatable` / `table` | 物理表名。未写 `datasetCode` 时，运行时会按表名解析 dataset code。 |
+| `defaults` / `params` | 资源级默认底层参数，例如分页、排序、固定条件。 |
+| `actions` | 该业务对象上的动作，例如 `list`、`mine`、`detail`、`create`。 |
+| `resources` | 子业务对象。用于 `lovrabet crm customer contact list` 这类更深路径。 |
+
+## Action 字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `description` | 命令说明。 |
+| `action` | 动作简写。默认 `filter`，可写 `getOne`、`create`、`update`、`delete`，也可写 `sql.exec`、`bff.exec`。 |
+| `kind` / `command` | `action` 的展开写法，例如 `{ "kind": "data", "command": "filter" }`。 |
+| `datasetCode` / `datatable` | 覆盖资源继承的数据集定位。 |
+| `sqlCode` | SQL 执行编码，配合 `action: "sql.exec"` 使用。 |
+| `functionName` | Backend Function ENDPOINT 名称，配合 `action: "bff.exec"` 使用。 |
+| `args` | 位置参数。字符串简写会自动变成必填参数。 |
+| `flags` | 可选参数。推荐对象写法。 |
+| `defaults` / `params` | 动作级默认底层参数。 |
+| `map` / `mapTo` | 显式映射规则。`map` 是推荐短名，`mapTo` 兼容旧名。 |
+| `risk` | 风险等级。只读可省略；写入用 `write`，删除/不可逆操作用 `high-risk-write`。 |
+
+Backend Function 动作示例：
+
+```json
+{
+  "description": "Process an order.",
+  "action": "bff.exec",
+  "functionName": "processOrder",
+  "params": { "source": "service-tree" }
+}
+```
+
+## flags 和 map
+
+`flags` 推荐对象写法：
+
+```json
+{
+  "flags": {
+    "status": "where.status.$eq",
+    "ownerId": {
+      "to": "where.owner_id",
+      "op": "$eq",
+      "type": "number",
+      "transform": "number"
+    },
+    "startDate": {
+      "to": "where.created_at",
+      "op": "$gte"
+    }
+  }
+}
+```
+
+对外使用时，camelCase flag 会自动转成 kebab-case：
+
+```bash
+lovrabet crm customer list --owner-id 12 --start-date 2026-01-01
+```
+
+`map` 适合位置参数、上下文和固定值：
+
+```json
+{
+  "args": ["id"],
+  "map": {
+    "id": { "target": "id", "transform": "number" },
+    "context.userId": { "target": "where.owner_id", "operator": "$eq", "transform": "number" },
+    "const.deleted": { "target": "where.deleted", "operator": "$eq", "value": 0 }
+  }
+}
+```
+
+未带前缀的 `map` key 会按名字自动匹配 `args` 或 `flags`；匹配不到时按 `flags.<name>` 处理。显式来源仍支持 `flags.`、`args.`、`context.`、`ctx.` 和 `const.`。
+
+## 数据集定位
+
+data target 推荐直接配置 `datasetCode`。如果只配置 `datatable` / `table`，动态命令执行时会在当前 app 的数据集列表中按物理表名解析 dataset code；解析失败时命令会停止，并提示补充 `datasetCode` 或确认表名。
+
+## 发现与诊断
+
+导入后的业务服务会出现在 CLI 发现面：
+
+```bash
+lovrabet service list --format compress
+lovrabet service detail --service <service> --format compress
+lovrabet --help
+lovrabet schema --format compress
+lovrabet doctor
+```
+
+`lovrabet service list/detail` 是 Agent 根据业务意图主动发现本机动态服务的轻量入口；`lovrabet --help` 会列出本地已导入服务及其多级业务命令；`lovrabet schema` 会把动态业务命令作为机器可读 command schema 导出；`lovrabet doctor` 会展示本机 registry 路径、加载状态、服务数、命令数和每个服务的 manifest 来源文件。
+
+动态命令仍走 Lovrabet CLI 的统一 runner：认证、appcode 决议、已发布应用访问限制、risk、dry-run、`--format` 和 `--jq` 都会生效。manifest 的应用绑定只提供默认值；用户显式传入的 `--appcode`、`--app`、`--env` 优先。
+
+## 兼容旧格式
+
+旧版 `commands` 数组仍然可用，但不再作为推荐写法：
+
+```json
+{
+  "service": { "code": "crm", "name": "CRM" },
+  "commands": [
+    {
+      "path": "customer list",
+      "description": "List customers.",
+      "target": {
+        "kind": "data",
+        "command": "filter",
+        "datasetCode": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      }
+    }
+  ]
+}
+```
+
+新配置优先使用 `resources/actions`，因为它能自然表达业务对象层级，也避免在 JSON key 或 `path` 里用空格拼命令。
+
+## 边界
+
+- Service Tree 本地 registry 是运行态发现和执行入口，不是服务端配置中心。
+- `service import/export` 只管理本机 `~/.lovrabet/service.json`，不会上传服务端。
+- 动态命令不会绕过应用发布状态和当前 AK 权限。
+- Runtime registry 只消费 manifest 中已经绑定的目标，不枚举 SQL、函数源码或其他实现资产。

package/skills/lovrabet/references/lovrabet-skill-authoring.md

@@ -0,0 +1,128 @@
+# Skill 创建、更新与发布工作流
+
+`lovrabet skill create/validate/install/list/push` 用于当前应用下 personal/company 业务 Skill 的本地开发和同步。Builtin Skill 由 sandbox 镜像或 CLI Built-in Skill 安装源提供，不通过 `lovrabet skill install` 拉取。
+
+## 目录约定
+
+所有新建或更新的 Skill 都在当前 workspace 的 `.agents/skills/<skillCode>/` 下完成。
+
+- `skillCode` 使用简短英文 kebab-case，不超过 64 字符。
+- `SKILL.md` 必须位于 Skill 目录根部。
+- `lovrabet.skill.json` 必须位于 Skill 目录根部。
+- 需要较长规则、schema、示例或脚本时，放入 `references/`、`scripts/` 或 `assets/`，并在 `SKILL.md` 中说明读取时机。
+- `SKILL.md` frontmatter 中 `name` 固定写稳定 `skillCode`，不要写展示文案；面向用户的业务展示名写顶层 `displayName`，即使展示名暂时等于 `skillCode` 也应显式保留。
+- 顶层 `example` 是一条用户可以直接发送、用于触发该 Skill 的推荐话术，例如 `example: 上传这份产品资料`。
+- `example` 可选；缺失、空白或不是单个标量时，`lovrabet skill validate` 会给出 warning，但不阻断 push。
+- 不要把正文说明、内部 CLI 命令、执行步骤或多个示例写入 `example`，也不要自动生成该字段。
+
+### Thin Prompt，Thick Skill
+
+用户 Prompt 只表达本次任务相对于稳定契约发生变化的目标、对象、范围等变量；稳定规则、执行步骤、能力标识、输出契约、安全边界和降级策略由业务 Skill 承载，不要求用户重复输入。
+
+- `example`：一句用户可直接发送的最简典型诉求。
+- `description`：说明触发语义以及何时使用或不使用。
+- `SKILL.md` 与其明确引用的 `references/`：承载完整稳定契约。
+
+如果用户必须在每次 Prompt 中重复 Skill 名称、内部命令或完整规则才能正确触发和执行，应优先补齐 `description` 或 Skill 契约，而不是继续加长 Prompt。
+
+## 新建
+
+```bash
+lovrabet skill create --name "<skillCode>" --type read --target .agents/skills
+lovrabet skill validate --dir .agents/skills/<skillCode> --strict
+lovrabet skill push --dir .agents/skills/<skillCode> --diagram-file ./<skillCode>.mmd --format compress
+```
+
+业务 Skill 模板类型仅支持 `read | write`。Agent 必须根据业务目标显式传入 `--type`；无法判断是否存在业务副作用时，停止并请求澄清。仅查询、汇总或核对且不改变业务状态时选择 `read`；涉及创建、更新、删除、状态流转、发送、发布或上传等业务副作用时选择 `write`，并在 Skill 契约中定义预览、用户确认、正式执行、读回核对和失败恢复。
+
+`displayName` 是给人看的展示名，`description` 是触发依据，要说明 Skill 做什么、什么时候使用、什么时候不要使用；`example` 则是一句推荐给用户直接发送的最简触发话术。
+
+## 更新
+
+本地已有目录时，直接编辑 `.agents/skills/<skillCode>/SKILL.md` 和必要资源。当前 workspace 没有目标 Skill 时，先安装当前应用可见的业务 Skill：
+
+```bash
+lovrabet skill install --project --code <skillCode> --format compress
+lovrabet skill validate --dir .agents/skills/<skillCode> --strict
+lovrabet skill push --dir .agents/skills/<skillCode> --diagram-file ./<skillCode>.mmd --format compress
+```
+
+`skill install` 默认安装到用户级 Agent Skill 目录。这里需要直接编辑当前项目中的 Skill，所以显式添加 `--project`，把有效链接写到当前工作目录的 `.agents/skills/<skillCode>`。
+
+如果安装得到的是 company Skill，默认不要覆盖 company 源；新建或更新 personal 副本，通过带 `--diagram-file` 的 `lovrabet skill push` 保存为个人 Skill。
+
+### 配置 YAML frontmatter
+
+当用户要求修改展示名、推荐话术、读写类型或其他明确字段时，直接编辑目标 `SKILL.md` 顶部的 YAML frontmatter：
+
+- 只修改用户明确指定的字段，保留其他字段和 Markdown 正文。
+- `name` 是稳定 `skillCode`，普通配置任务不得修改。
+- `displayName` 根据用户实际展示诉求填写人类可读名称。
+- `example` 写一句用户可直接发送的最简触发话术。
+- `metadata.type` 只能是 `read` 或 `write`。
+- 不创建或开启 `metadata.internal`；未知字段默认保留，语义不明确时不修改。
+
+修改后执行 `lovrabet skill validate --dir <dir> --strict`。只有用户明确要求更新 company 源并提交审核时，才按既有流程先 dry-run，再执行带 `--diagram-file` 的 `push --scope company`；否则遵循上文规则创建或更新 personal 副本。company 新版本审核通过前不得声称已生效。
+
+推荐用户话术：
+
+> 请把企业 Skill `<skillCode>` 的 YAML frontmatter 中 `displayName` 改为「<展示名>」，保持 `name` 不变；校验通过后提交企业版新版本审核。
+
+## 生成作用流程图
+
+每次创建 Skill 或修改源码并准备发布新版本时，Agent 必须在 push 前读取本次上传的 `SKILL.md` 及其明确引用的必要文件，直接编写一张 Mermaid flowchart。不要要求用户提供流程图。流程图是该 SkillVersion 的作用说明，不是实际执行记录。
+
+图中应覆盖：
+
+- 触发条件和主要输入。
+- 关键执行步骤，以及影响结果的重要条件分支。
+- 权限不足、契约缺失、校验失败或结果不确定时的停止、澄清或安全降级。
+- 最终输出或业务副作用；写入类 Skill 还要体现确认与读回核对。
+
+只写文档能够支持的步骤，标签保持简短，不逐段复述正文，也不编造能力。源码不足以形成可信流程图时，先完善 Skill 契约或向用户澄清，再发布；不得提交空图或占位图。
+
+建议从 `flowchart TD` 开始，使用清晰的节点、边和条件标签表达作用流程。提交的文件必须是语法正确的 Mermaid；先让 dry-run 通过，再使用同一份文件正式发布。
+
+将原始 Mermaid 保存为 `.mmd` 文本并通过 `--diagram-file` 传给 dry-run 和正式 push；两次必须使用同一份 Skill 源码和 Mermaid。文件可以放在 Skill 目录内或外；CLI 会把所选文件作为独立 diagram 提交，并在它位于 Skill 目录内时按规范化真实路径从包扫描中精确排除，不会忽略其他 `.mmd` 文件。也可以用 `--diagram-file -` 从标准输入读取。任一部分失败时修正后整体重试，不改成分步发布。
+
+## 发布扫描告警
+
+personal `skill push --dry-run` 会用 `visibility=PRIVATE` 调用 SkillHub publish validate，提前返回正式发布会遇到的 errors 和 warnings。errors 始终阻断；正式 push 遇到 warnings 时会展示告警并停止。人工复核后，personal 或 company push 都需显式添加 `--confirm-warnings`，提交未经改写的同一份包。CLI 不根据 warning 文案自行分类。
+
+发布扫描告警是打包反馈，不是修改业务 Skill 的授权。不要为了通过扫描删除、替换或改写业务 Skill 中的标识、映射、路径、规则、scripts 或 references。先确认告警内容：
+
+- 真实问题（例如明文凭证、违规扩展名或内容格式不匹配）：personal push 不会因 warning 自动停止，仍需根据返回结果尽快修复；涉及凭证时还必须轮换。
+- 已确认的误报：保留源码，不要创建内容不同的临时发布副本。
+
+CLI 不自动创建脱敏包，也不自动改写源 Skill。
+
+## 发布公司级版本
+
+本地目录确认可交付后，可提交公司级 Skill 新版本审核：
+
+```bash
+lovrabet skill validate --dir .agents/skills/<skillCode> --strict
+lovrabet skill push --scope company --dir .agents/skills/<skillCode> --diagram-file ./<skillCode>.mmd --dry-run
+lovrabet skill push --scope company --dir .agents/skills/<skillCode> --diagram-file ./<skillCode>.mmd --confirm-warnings --format compress
+```
+
+`push --scope company` 使用 SkillHub `NAMESPACE_ONLY` 可见性把 Skill 包与 Mermaid 一起提交审核。命令成功只表示带图的新版本已提交 review；审核通过前不要声称该版本已对所有成员生效。需要本机 Agent 使用生效版本时，审核后再执行 `lovrabet skill install --code <skillCode>`。
+
+## 内容要求
+
+- `SKILL.md` 面向未来 Agent，使用精简 Markdown。
+- 正文写可执行流程、命令、边界和输出要求。
+- 不引用 RuntimeAgent 原生 `skill_load`、`skill_update`，也不要把不存在的 pull 类 Skill 操作写成 `lovrabet` 命令。
+- 不把明文凭证、cookie、AK、用户私有路径写入 Skill。
+- 不把临时调试记录、变更日志或面向人的安装说明放入 `SKILL.md`。
+
+## 发布后检查
+
+`lovrabet skill push` 成功后，使用下面命令确认本地和云端可见性：
+
+```bash
+lovrabet skill list --scope all --format compress
+lovrabet skill list --local --scope all --format compress
+```
+
+命令失败时报告 CLI 错误和当前 appCode，不声称已保存。

package/skills/lovrabet/references/lovrabet-skill-install.md

@@ -0,0 +1,34 @@
+# skill install
+
+安装当前应用、当前租户可生效的业务 Skill。默认安装到用户级 Agent Skill 目录，让本机 Agent 可发现并使用这些业务 Skill；也可以显式安装到当前项目。
+
+## 用法
+
+```bash
+lovrabet skill install [--scope all|personal|company] [--code <skillCode>] [--project]
+lovrabet skill install --project
+```
+
+## 说明
+
+- 需要 AccessKey 和 App Code。
+- 默认等价于 `--scope all`，安装当前应用下当前用户可见的 personal/company 业务 Skill。
+- 默认将有效 Skill 链接到用户级 Agent Skill 目录，并保留 `<appCode>--<skillCode>` 名称，避免不同应用同名 Skill 冲突。
+- 只有明确需要绑定当前项目时才传 `--project`；项目链接写入当前工作目录的 `.agents/skills/<skillCode>`，适合 `/workspace/<appCode>` 这类一应用一项目目录。
+- 用户级与项目级安装可以共存；显式项目安装不会删除已有用户级链接，也会保留这些链接仍在引用的缓存。
+- 项目安装会拒绝覆盖 `lovrabet`、`runtime-observe`、`secret-retriever` 等平台保留 Skill 名称。
+- personal 与 company 出现同一 `skillCode` 时，personal 版本生效。
+- `--scope personal` 只安装个人业务 Skill；`--scope company` 只安装公司业务 Skill。
+- `--code` 只安装指定业务 Skill，并清理该 code 对应的失效链接或 cache。
+- 安装产物面向 Agent 消费，不建议直接编辑；新建或修改业务 Skill 时使用 `lovrabet skill create` / `lovrabet skill validate` / `lovrabet skill push --diagram-file <mermaid-file>`。
+- 下载缓存仍保存在 `~/.lovrabet/cache/<env>/<ak_fingerprint>/skills/<appCode>/...`，不会复制到项目目录。
+
+## CLI Built-in Skill
+
+`lovrabet skill install` 仅安装当前应用的业务 Skill。CLI Built-in Skill 已包含在当前 npm 包内，并在安装或升级 CLI 时自动安装。诊断显示缺失、版本不一致或内容不一致时，使用当前包内的确定版本修复：
+
+```bash
+lovrabet cli-skill install
+```
+
+该命令只使用已校验的包内目录；外部 `skills` CLI 负责把它安装到 Agent 可发现的位置。失败时根据稳定错误码处理网络、权限或安装目标问题，再重试同一命令。

package/skills/lovrabet/references/lovrabet-skill-sync.md

@@ -0,0 +1,146 @@
+# skill install / create / validate / list / push
+
+安装当前应用业务 Skill，创建本地运行态 Skill 草稿，检查必要元数据，查看云端或本地 CLI 管理的 Skill 列表，并将本地个人 Skill 改动推回平台。
+
+## 创建本地草稿
+
+```bash
+lovrabet skill create --name invoice-review --type write
+lovrabet skill create --name customer-summary --type read --target ./skills
+lovrabet skill create --name invoice-review --type write --dry-run
+```
+
+`create` 只写本地文件，不需要 AK、不需要 appcode、不上传、不发布、不写业务数据。默认生成：
+
+```text
+.agents/skills/<skill-name>/
+  SKILL.md
+  references/runtime-contract.md
+  references/output-contract.md
+```
+
+生成的草稿带有 `【...】` 占位符。Agent 必须根据业务目标显式传入 `--type read|write`；无法判断是否存在业务副作用时停止并请求澄清。frontmatter `name` 是稳定 `skillCode`，`displayName` 根据用户实际展示诉求填写人类可读名称，`description` 应写模型触发语义，说明何时使用、不要使用的边界和关键词。CLI 会检查 `SKILL.md` 与 frontmatter 必要字段；缺少顶层 `displayName` 会 warning，但正文、章节、references、占位符和输出协议不参与 CLI validate 或 push 阻断。
+
+## 必要元数据检查
+
+```bash
+lovrabet skill validate --dir .agents/skills/invoice-review
+lovrabet skill validate --dir .agents/skills/invoice-review --strict
+```
+
+`validate` 只检查本地目录是否具备上传和识别所需的最小信息。`--strict` 为兼容保留，不启用额外检查。
+
+检查项：
+
+- 根目录存在普通文件 `SKILL.md`。
+- `SKILL.md` 以 frontmatter 开头。
+- frontmatter 中 `name`、`description` 非空。
+- `metadata.type` 可选；若填写，必须是 `write` 或 `read`。
+
+正文内容、章节名称、`references/*`、占位符、输出协议、明文凭证和外部链接不参与 CLI validate。
+
+## 查看列表
+
+```bash
+lovrabet skill list
+lovrabet skill list --scope personal
+lovrabet skill list --scope company
+lovrabet skill list --scope all
+lovrabet skill list --code sales_playbook
+lovrabet skill list --local
+lovrabet skill list --local --scope all
+lovrabet skill list --local --project
+```
+
+默认等价于 `--scope all`，查询 SkillHub-backed 云端 personal 和 company 业务 Skill，不安装、不下载内容。Builtin Skill 由 sandbox 镜像内置提供，不通过远端 `skill list` 查询。
+
+`--local` 只读取当前 env、AK、App 下 CLI 管理的本地 cache 与用户级链接，依赖 `lovrabet.skill.json` 识别元数据；它不请求云端、不下载 package、不物化文件，也不清理旧目录。查看当前项目链接时使用 `skill list --local --project`。需要查看本地是否已经安装时用 `lovrabet skill list --local`，需要看云端是否存在时用不带 `--local` 的 `lovrabet skill list`。
+
+## 安装业务 Skill
+
+```bash
+lovrabet skill install
+lovrabet skill install --scope all
+lovrabet skill install --scope personal
+lovrabet skill install --scope company
+lovrabet skill install --code sales_playbook
+lovrabet skill install --project
+```
+
+默认等价于 `--scope all`，安装当前 App 下当前 AK 可见的 `personal` 和 `company` 业务 Skill，不安装 `builtin`。有效链接默认写入用户级 Agent Skill 目录；只有用户明确要求绑定当前项目时才添加 `--project`。
+
+安装过程会使用当前环境和 AK 指纹隔离的 CLI 管理缓存：
+
+```text
+~/.lovrabet/cache/<env>/<ak_fingerprint>/skills/<appCode>/<scope>/<skillCode>/
+  SKILL.md
+  lovrabet.skill.json
+```
+
+- `SKILL.md` 是本地 Agent 可直接发现的入口文件；后端 Skill `content` 缺少 YAML frontmatter 时，CLI 会根据 Skill 元数据补齐 `name`、`displayName` 和 `description`；已有 frontmatter 时会同步顶层 `displayName`，但不改写 `name`；即使展示名等于 `skillCode`，也会显式写入 `displayName`
+- `lovrabet.skill.json` 保存 `appCode`、`skillCode`、`scope`、版本、标签、content hash 等 Lovrabet 元数据；展示名以 `SKILL.md` 顶层 `displayName` 为可编辑入口
+- 同名 `skillCode` 的 personal 和 company 副本都会保留，effective 链接优先 personal
+- 完整 `skill install` 会移除当前 App 下远端已删除 Skill 对应的 CLI 管理链接和当前 AK 缓存目录；`--code <skillCode>` 只同步和清理指定 code
+
+## 本地链接
+
+默认用户级有效 Skill 会链接到：
+
+```text
+~/.agents/skills/<appCode>--<skillCode>
+~/.claude/skills/<appCode>--<skillCode>
+```
+
+显式执行 `lovrabet skill install --project` 时，项目级链接不重复携带 appCode：
+
+```text
+<cwd>/.agents/skills/<skillCode>
+```
+
+personal 与 company 同名时 personal 优先；只有 company 时链接 company。用户级与项目级安装可以共存，CLI 只在本次选择的链接目标中替换或移除指向 `~/.lovrabet` cache 且 metadata 归属当前 App/code 的已管理 symlink，不覆盖或删除普通文件、目录、外部 symlink 或其他 App 的链接。显式项目安装清理缓存时，会保留已有用户级链接仍在引用的目录；项目安装也会拒绝覆盖 `lovrabet`、`runtime-observe`、`secret-retriever` 等平台保留 Skill 名称。
+
+## 推送
+
+```bash
+lovrabet skill push --dir ~/.lovrabet/cache/production/<ak_fingerprint>/skills/app-1/personal/sales_playbook --diagram-file ./sales-playbook.mmd
+lovrabet skill push --dir ./app-1--sales_playbook --diagram-file ./sales-playbook.mmd
+```
+
+`push` 读取目录下的 `SKILL.md`。frontmatter `name` 继续用于推导稳定 `skillCode`；顶层 `displayName` 会作为远端展示名提交到 SkillHub。没有 `displayName` 时，CLI 才回退使用 `lovrabet.skill.json` 中的名称。没有元数据时从目录名推导 `skillCode`，并去掉当前 App 的 `<appCode>--` 前缀。上传前会用该 `skillCode` 在当前 App namespace 下精确查询远端 Skill，命中时先把远端 scope、版本、状态、名称和描述写回 `lovrabet.skill.json`，再重新读取本地目录进入上传逻辑。
+
+`push` 默认创建或更新 personal Skill。发布新 SkillVersion 时 `--diagram-file` 必填；文件内容是 Agent 根据本次 Skill 源码直接编写、且语法正确的原始 Mermaid flowchart，也可传 `--diagram-file -` 从标准输入读取。文件可位于 Skill 目录内或外；CLI 不把流程图加入 Skill 包、本地元数据或安装目录，而是与 Skill 包在同一个发布请求中提交。位于 Skill 目录内时，只有 `--diagram-file` 选中的规范化真实路径会从包扫描中排除，其他 `.mmd` 文件仍按普通包文件处理。SkillHub 必须明确确认图已校验、已绑定；缺少回执的旧服务会被视为不支持联合发布。流程图缺失、Mermaid 语法错误或服务端拒绝时，整个 push 失败，不先发布无图版本。若远端刷新后的元数据 scope 是 `company`，默认 personal push 会在上传前失败，并提示使用公司级 push 工作流。Builtin Skill 不能 push，也不能通过 company scope 提交审核。
+
+## 公司级发布
+
+```bash
+lovrabet skill push --scope company --dir .agents/skills/sales-playbook --diagram-file ./sales-playbook.mmd --dry-run
+lovrabet skill push --scope company --dir .agents/skills/sales-playbook --diagram-file ./sales-playbook.mmd --confirm-warnings
+```
+
+`push --scope company` 读取本地 Skill 目录与流程图并向 SkillHub 提交公司级新版本审核。`--dry-run` 会同时校验 Skill 包和 Mermaid，不创建版本或审核任务；正式提交使用 `visibility=NAMESPACE_ONLY`，两者必须一起成功，成功后版本进入审核，不代表已经成为 effective Skill。审核通过并需要本机 Agent 使用时，再运行 `lovrabet skill install` 安装已生效版本。
+
+## 精确版本流程图维护
+
+正常创建或更新源码版本时始终使用带 `--diagram-file` 的 `skill push`。只有为历史版本补图或修正已发布版本的图时，才使用独立命令：
+
+```bash
+lovrabet skill diagram-show --skill-code <skillCode> --version <version> --scope personal|company --format compress
+lovrabet skill diagram-validate --skill-code <skillCode> --version <version> --scope personal|company --source-fingerprint <sha256> --expected-diagram-revision <revision> --diagram-file <mermaid-file> --format compress
+lovrabet skill diagram-push --skill-code <skillCode> --version <version> --scope personal|company --source-fingerprint <sha256> --expected-diagram-revision <revision> --diagram-file <mermaid-file> --format compress
+```
+
+每次独立维护都先运行 `diagram-show`，只复制该次输出中的服务端 canonical `sourceFingerprint` 和 `expectedDiagramRevision`，不要自行计算 fingerprint、猜 revision 或复用旧读结果。已有图时 `expectedDiagramRevision` 等于当前 `diagramRevision`；`found=false` 表示该精确版本当前无图，但响应仍必须带该版本的 `sourceFingerprint`，并给出 `diagramRevision=null`、`expectedDiagramRevision=0` 供首次写入。若响应缺少 fingerprint，CLI 会按服务能力不完整失败，不能把它解释为无图。先 validate，再用完全相同的目标、fingerprint、revision 和 Mermaid 执行 push。revision 或 source fingerprint 冲突时重新读取并核对，不使用强制覆盖；认证、权限、网络或服务端错误同样不能解释为无图。
+
+## 与 RuntimeAgent 原生 Skill 工具的关系
+
+CLI 的 Skill 能力是目录同步：
+
+- `skill install`：把当前应用下当前 AK 可见的 personal/company Skill 默认安装到用户级目录；`--project` 才安装到当前项目 `.agents/skills`。
+- `skill create --name <name> --type read|write`：生成本地自包含 Skill 草稿，不上传。
+- `skill validate --dir <dir>`：检查 Skill 必要元数据。
+- `skill list`：查看云端 Skill 列表；`--local` 查看 CLI 管理的本地 cache 和链接。
+- `skill push --dir <dir> --diagram-file <mermaid-file>`：检查必要上传信息和流程图后创建或更新 personal SkillVersion。
+- `skill push --scope company --dir <dir> --diagram-file <mermaid-file>`：检查本地目录和流程图后提交 company Skill 新版本审核。
+- `skill diagram-validate/diagram-push/diagram-show`：维护一个精确历史 SkillVersion 的流程图，不替代正常联合发布。
+
+RuntimeAgent 原生的 `skill_load`、`skill_update` 等工具是 Agent 服务内部的资源读写能力，不是 `lovrabet` CLI 命令。写命令步骤时不要把这些原生工具当作 CLI 子命令，也不要要求 coworker 直接调用它们。