@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

package/skills/rabetbase/references/rabetbase-db-detail.md

@@ -0,0 +1,27 @@
+# db detail
+
+按 **dblink id** 拉取单条连接的完整元数据（含分析相关字段）。密码在输出中脱敏。
+
+## 何时用
+
+- 已用 `db list` 拿到 `id`，需要比列表更全的字段
+- 需要当前 **`latestAnalysisTraceId`** 查询最新分析状态；取消已知任务时仍使用正在跟踪的原 planId
+
+## 命令
+
+```bash
+rabetbase db detail --id 10157 --format compress
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--id` | number | **是** | `db list` / 工作台连接列表上的 dblink id |
+| `--appcode` | string | 否 | 覆盖当前 app |
+| `--format` | string | 否 | 默认 **compress** |
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-diff.md

@@ -0,0 +1,57 @@
+# db diff
+
+分页查看**线上库相对上次分析**的 schema 差异（新增表、删除表、改字段等）。只读。
+
+## 何时用
+
+- 表结构变更后，决定是跑全量分析还是 `analyze-start --tables …` 增量
+- 排查「平台数据集与真实库不一致」
+
+## 命令
+
+```bash
+rabetbase db diff --id 10157 --format compress
+rabetbase db diff --id 10157 --table order --page 1 --pagesize 20 --format compress
+rabetbase db diff --id 10157 --all --changed-only --format compress
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--id` | **是** | dblink id |
+| `--table` | 否 | 表名模糊过滤 |
+| `--page` / `--pagesize` | 否 | 默认 `1` / `20` |
+| `--all` | 否 | 从第 1 页开始按 `pageSize=100` 自动聚合全部分页；优先级高于 `--page / --pagesize` |
+| `--changed-only` | 否 | 只从 `tables / tableList` 排除 `ALREADY_ANALYZED`；保留 `DELETED_TABLE` |
+
+## 机器可读摘要
+
+| 字段 | 语义 |
+|------|------|
+| `summaryByType` | 本次查询范围内四种 `diffType` 的计数 |
+| `toAnalyzeTables` | 仅包含 `NEW_TABLE` 与 `MODIFIED_TABLE` 的表名，可传给 `analyze-start --tables` |
+| `deletedTables` | 仅包含 `DELETED_TABLE`，供人工确认，不自动分析或清理 |
+| `modifiedFieldDiffs` | 修改表的新增、删除、变更字段摘要 |
+
+未传 `--all` 时，上述字段只代表当前页；需要完整范围时使用 `--all`。派生字段基于过滤前的查询范围计算，因此使用 `--changed-only` 时，`summaryByType.ALREADY_ANALYZED` 仍可反映原始计数。
+
+## `diffType` 语义（与 yuntoo-web-app 增量分析抽屉一致）
+
+接口返回 `IDbTableDiffInfo.diffType`，工作台「数据库连接 → 增量分析」里对每行表的展示文案如下，可与 CLI 输出对照：
+
+| `diffType` | 界面文案 | 含义 |
+|------------|----------|------|
+| `NEW_TABLE` | 表新增 | 物理库中**有**该表，但**尚未纳入**（或尚未完成）上次智能分析；适合勾选后走 `db analyze-start --tables …` 做增量分析。 |
+| `DELETED_TABLE` | 表删除 | 相对上次已分析快照，该表在库侧**已不存在**（或已被移除）；界面上勾选增量分析时**不可选**该行。 |
+| `MODIFIED_TABLE` | 表修改 | 表仍在，但**结构相对上次分析有变**；同条记录里可能有 `fieldDiff`（`addedColumns` / `deletedColumns` / `modifiedColumns`）。 |
+| `ALREADY_ANALYZED` | 无差异 | 当前表结构与上次分析结果**一致**，无需因本表再跑增量（界面用灰色「无差异」标签）。 |
+
+`DELETED_TABLE` 不会进入 `toAnalyzeTables`。如果自动分页在达到 `totalCount` 前遇到空页或不再产生新的唯一表，命令会失败，不把部分结果当作完整结果返回。
+
+`--all` 聚合的是服务端实时分页结果，不是事务一致性快照。数据库结构在翻页期间持续变化时，结果可能来自不同查询时刻；检测到分页无进展会直接失败。此时应等待库表结构稳定后重试，并在分析结束后再次执行 `db diff --all --changed-only` 验证差异收敛。
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-list.md

@@ -0,0 +1,37 @@
+# db list
+
+列出当前应用下所有 **数据库连接（dblink）** 及最近一次**分析状态**。**先执行本命令拿到 `id`**，再调用 `db detail` / `db test` / `db tables` 等。
+
+## 何时用
+
+- 刚接手项目，需要知道有哪些库、分析是否跑完
+- 为其它 `db` 子命令准备 **`--id`**
+- 查看 **`latestAnalysisTraceId`**（连接级最新快照，可供 `db analyze-status` 使用；取消已知任务时应使用正在跟踪的原 planId）
+
+## 命令
+
+```bash
+rabetbase db list --format compress
+rabetbase db list --page 1 --pagesize 100 --format compress
+rabetbase db list --appcode app-xxxx --format compress
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--appcode` | string | 否 | 配置文件 | 覆盖当前 app |
+| `--page` | number | 否 | `1` | 页码（1-based） |
+| `--pagesize` | number | 否 | `100` | 每页条数 |
+| `--format` | string | 否 | **compress** | `json` / `compress` / `pretty` |
+
+## 输出要点
+
+- `connections[]`：每条含 `id`、`dbName`、`dbType`、`latestAnalysisStatus`、`latestAnalysisTraceId` 等
+- 返回中密码已脱敏
+- 若接口未返回分页元数据，`paging.totalCount` 为 `null` 并带 `note`，**勿将本页条数当作全量总数**
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-tables.md

@@ -0,0 +1,25 @@
+# db tables
+
+列出指定 dblink 下**物理表**及平台打上的分析标签（如是否已分析、是否新增表等）。只读。
+
+## 何时用
+
+- 写自定义 SQL / 对表前确认真实表名
+- 与 `dataset list` 对照：哪些表尚未建成数据集
+
+## 命令
+
+```bash
+rabetbase db tables --id 10157 --format compress
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--id` | **是** | dblink id（`db list`） |
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-test.md

@@ -0,0 +1,29 @@
+# db test
+
+用平台已保存的凭据**测试**到数据库的网络与登录是否成功。只读（`read`）。
+
+## 何时用
+
+- 改白名单、换 VPC、更新密码后快速验证
+- 新建连接后确认无误再跑长耗时分析
+
+## 命令
+
+```bash
+rabetbase db test --id 10157 --format compress
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--id` | **是** | dblink id |
+
+## 输出
+
+`data.connected` 为布尔语义；`data.result` 为后端响应的**摘要**（白名单字段或键名列表），不返回完整原始 body，避免泄露敏感细节。
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-db-update.md

@@ -0,0 +1,29 @@
+# db update
+
+**增量更新**已有 dblink：只传需要改的 flag，未传的字段保持服务端原值。`write`。
+
+## 何时用
+
+- 换库地址、改账号、轮换密码
+- 改描述便于他人识别
+
+## 命令
+
+```bash
+rabetbase db update --id 10157 --dburl new-host:3306 --format compress
+rabetbase db update --id 10157 --password '***' --format compress
+```
+
+## 参数
+
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--id` | **是** | dblink id（`db list`） |
+| `--dbname` / `--dburl` / `--username` / `--password` / `--dbparam` / `--dbdesc` | 否 | 仅传要覆盖的项；**不传 `--password` 则不修改密码**（空字符串行为以后端为准） |
+
+写操作支持 **`--dry-run`**：合并当前服务端记录与 CLI 覆盖项后预览（密码脱敏）。
+
+## 参考
+
+- [database-connection-workflow.md](../guides/database-connection-workflow.md)
+- [SKILL.md](../SKILL.md)

package/skills/rabetbase/references/rabetbase-doctor.md

@@ -0,0 +1,62 @@
+# doctor
+
+诊断 CLI 与 Built-in Skill 一致性、当前生效的配置、API 域名和认证状态。
+
+遇到配置错误、`auth_required`、`api_error` 等问题时，先运行此命令定位根因。
+
+## 命令
+
+```bash
+rabetbase doctor
+# 等价（Diagnostics 为单命令 service，默认子命令为 check）：
+rabetbase doctor check
+```
+
+无需额外参数，直接执行。
+
+## 输出内容
+
+| 段落 | 说明 |
+|------|------|
+| CLI Version | 当前 CLI 版本（含 build number） |
+| Built-in Skill | 目标路径、包版本、Skill 版本、内容状态；不一致时给出 `rabetbase cli-skill install` 修复命令 |
+| Config Files | 全局和项目级配置文件路径 |
+| Config JSON | 分别检测全局/项目配置文件是否为**合法 JSON**；非法时标红并给出解析错误（常见于尾随逗号、注释等，会导致该侧配置在合并时被忽略） |
+| Merged Config | 合并后的所有配置项（appCode / env / cookie / apiDir 等） |
+| Apps | 多应用模式下的应用列表及各自配置 |
+| API Endpoints | 最终生效的三个域名（apiDomain / userDomain / runtimeDomain） |
+| Auth | 登录状态及 cookie 有效性 |
+
+## 典型场景
+
+```bash
+# 独立部署后，验证域名是否正确
+rabetbase doctor
+# 查看 API Endpoints 是否为自定义域名
+
+# 认证失效时，查看 Auth 状态
+rabetbase doctor
+# 如果显示 Expired → 重新 run rabetbase auth
+
+# 多应用配置混乱时，查看 Merged Config
+rabetbase doctor
+# 确认 --app 指定的配置是否正确生效
+
+# 项目里「明明配了 apps 但行为像没配」— 先看 Config JSON 是否 Invalid
+rabetbase doctor
+# 若 Project JSON 为 ✗，修正 .rabetbase.json 语法后再试
+
+# Skill 缺失、版本不一致或内容被修改时
+rabetbase doctor
+rabetbase cli-skill install
+```
+
+## 独立部署场景
+
+如果 Lovrabet 部署在自定义域名下，先通过 `rabetbase config set` 配置域名，再用 `doctor` 验证：
+
+```bash
+rabetbase config set apiDomain https://custom-api.example.com --global
+rabetbase doctor
+# API Endpoints 应显示自定义域名
+```

package/skills/rabetbase/references/rabetbase-file.md

@@ -0,0 +1,35 @@
+# file upload / query-url
+
+应用文件命令。参数与输出约定和 `lovrabet file` 一致，通过 rabetbase 当前登录态与应用权限执行。
+
+## 上传文件
+
+```bash
+rabetbase file upload --file ./evidence.png --appcode app-demo --format compress
+```
+
+`upload` 的风险等级为 `read`，支持 `--dry-run`。上传只生成尚未绑定业务记录的远端文件对象，不创建、更新或删除业务数据；它仍会把本地文件发送到目标应用，执行前需要核对应用和敏感文件范围。本地文件必须存在、必须是普通文件且不能超过 50 MB。成功后保留返回的 `filePath`，用于业务字段或后续查询 URL。
+
+## 查询访问 URL
+
+```bash
+# 短效预览 URL
+rabetbase file query-url --filepath '20260717/hash-evidence.png' --appcode app-demo --format compress
+
+# 短效下载 URL
+rabetbase file query-url --filepath '20260717/hash-evidence.png' --download --appcode app-demo --format compress
+
+# 3 年 URL，供 Markdown、HTML、富文本等只能保存 URL 的内容使用
+rabetbase file query-url --filepath '20260717/hash-evidence.png' --long-term --appcode app-demo --format compress
+```
+
+## 选择原则
+
+- 可保存文件引用时保存 `filePath`，访问时再获取短效 URL。
+- 只有 Markdown、HTML 或富文本等 URL-only 内容才使用 `--long-term`。
+- 使用 rabetbase 当前登录态上传应用文件；不要改用 `lovrabet file upload`，避免混用两套应用权限。
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase-issue-report.md](rabetbase-issue-report.md)

package/skills/rabetbase/references/rabetbase-init.md

@@ -0,0 +1,70 @@
+# rabetbase init
+
+智能初始化 `.rabetbase.json` 配置。
+
+> **风险等级：write** — 创建或修改配置文件。
+
+## 命令
+
+```bash
+# 交互模式（从平台拉取应用列表选择）
+rabetbase init
+
+# 指定 appcode 直接写入（非交互）
+rabetbase init --appcode <code>
+
+# 指定环境
+rabetbase init --appcode <code> --env daily
+
+# 写入全局配置
+rabetbase init --appcode <code> --global
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--appcode <code>` | string | 否 | — | 直接写入配置，跳过交互选择 |
+| `--env <env>` | string | 否 | `production` | 目标环境：`production` / `daily` |
+| `--global` | boolean | 否 | `false` | 写入全局配置而非项目配置 |
+
+## 执行逻辑
+
+按优先级自动路由：
+
+1. **老项目检测**（仅 project scope）→ 若检测到旧配置文件（如 `.lovrabet.json`）且无 `.rabetbase.json`，自动触发 `project upgrade`
+2. **`--appcode`** → 直接写入配置（单应用或 CI 模式）
+3. **CI 无 `--appcode`** → 报错 `flag_missing`
+4. **TTY 交互** → 从平台拉取应用列表，用户多选后写入配置
+
+## 输出
+
+- 成功：`✓ Successfully initialized project config` 并显示 AppCode、Env、Config 路径
+- 已有配置：报错 `.rabetbase.json already exists`
+- 旧项目：自动进入 `project upgrade` 流程
+
+## 多应用
+
+交互模式支持选择多个应用，生成多应用配置：
+
+```json
+{
+  "apps": {
+    "app1": { "appcode": "code1", "env": "production" },
+    "app2": { "appcode": "code2", "env": "production" }
+  },
+  "defaultApp": "app1"
+}
+```
+
+## 提示
+
+- 这是新用户首次使用的推荐入口命令
+- CI/CD 场景必须传 `--appcode`
+- 已有配置时先删除，或用 `config set env ...` / `workspace add` / `workspace use` 修改；`config set appcode` 仅适合单应用场景，会写成 `apps + defaultApp`
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [配置参考](rabetbase-config.md)
+- [project upgrade](rabetbase-project-upgrade.md)

package/skills/rabetbase/references/rabetbase-issue-report.md

@@ -0,0 +1,132 @@
+# issue report
+
+向平台 Issue 采集链路上报一个问题。description 的核心是完整组织客观事实，供平台侧复现和排查；该入口不负责代替平台侧判断根因或设计解决方案。
+
+> **前置条件：** 已通过 `rabetbase auth login` 完成认证；未登录时命令返回 `auth_required`。
+
+## 核心边界
+
+- 只写已经观察、执行或读取到的事实，包括环境、版本、时间、命令、输入、原始输出、状态变化、错误信息和定位标识
+- 实际结果与期望结果分开记录；“期望结果”只描述用户可验证的目标，不延伸成技术实现建议
+- 不确定的信息放入“尚未确认”，明确说明缺少什么证据；不得把推测写成事实
+- 不得推测根因，不得提供修复方案，不得给出主观优先级或未经验证的影响判断
+- 不得为了简洁删除唯一事实；可以去除完全重复的输出，但必须保留首次出现位置、重复次数和可定位标识
+- Cookie、Authorization、AccessKey、密码、私钥和 JWT 等敏感值仍需由命令脱敏，不得以“保持原始事实”为由绕过安全处理
+
+## 事实模板
+
+```markdown
+## 问题概述
+
+用一句话描述已经发生的异常，不写原因判断。
+
+## 环境与标识
+
+- CLI 与版本：
+- AppCode / AppEnv：
+- 发生时间与时区：
+- TraceId / SpanId / JobId：
+
+## 复现步骤
+
+1. 按实际顺序记录操作。
+2. 命令、参数和必要输入保持可复现；敏感值使用安全占位符。
+
+## 实际结果
+
+- 原样记录状态、错误码、错误信息和关键返回字段。
+- 长输出注明完整证据的位置、字节数和摘要值。
+
+## 期望结果
+
+- 描述用户能够验证的正确行为。
+
+## 客观证据
+
+- 日志、截图、文件、URL、时间线和对应标识。
+
+## 尚未确认
+
+- 只列缺少证据、尚未执行或平台侧需要继续核对的事实问题。
+```
+
+不要在模板中增加“根因分析”“建议修复方案”“解决方案”或“建议排查方向”等章节。
+
+## 命令
+
+```bash
+rabetbase issue report --title "page push 保存失败" --description "## 实际现象\n- 点击保存后报错" --dry-run --format json
+
+cat <<'EOF' >/tmp/platform-issue.md
+## 问题概述
+page push 保存失败
+
+## 环境与标识
+- rabetbase: 2.3.6
+- AppCode: app-example
+
+## 复现步骤
+1. 执行 `rabetbase page push ...`
+
+## 实际结果
+- 命令返回 `validation_error`
+
+## 期望结果
+页面 schema 能成功推送
+
+## 客观证据
+- TraceId: `<trace-id>`
+
+## 尚未确认
+- 当前返回内容未包含具体字段信息
+EOF
+
+wc -c /tmp/platform-issue.md
+rabetbase issue report --title "TEST issue smoke" --description-file /tmp/platform-issue.md --dry-run --format json
+# 确认 issue.description_original_bytes 与上方字节数一致，且 issue.description_truncated=false
+rabetbase issue report --title "page push 保存失败" --description-file /tmp/platform-issue.md --format json
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `--title <text>` | string | 是 | — | 一句话问题摘要 |
+| `--description <markdown>` | string | 与 `--description-file` 二选一 | — | 内联 Markdown 问题描述 |
+| `--description-file <path>` | string | 与 `--description` 二选一 | — | Markdown 文件路径，适合长上下文；最终会上报文件内容文本，而不是路径 |
+| `--dry-run` | boolean | 否 | `false` | 仅预览将要写入的 trace/span/logData |
+| `--format <fmt>` | string | 否 | `compress` | 输出格式 |
+
+## 行为说明
+
+- 命令会自动补充 CLI 宿主公共上下文，不需要手动重复传入环境或用户字段
+- `--description-file` 只是本地输入来源；命令会先读取文件内容，最终上报的是 `issue.description` 的 Markdown 文本，不是本机文件路径
+- 命令不会自动附带 Agent 对话、工具历史或工作目录文件；只有显式写入 `--description` / `--description-file` 的事实会进入上报正文
+- 单次 issue 的正文业务字段只写：
+  - `issue.title`
+  - `issue.description`
+- 命令还会上报 `issue.description_original_bytes`、`issue.description_truncated`、`issue.description_redactions` 和 `issue.description_redaction_kinds`，用于核对完整性与脱敏结果
+- `--dry-run` 中若出现 `descriptionFile`，它只用于本地确认读取了哪个文件，不属于正式上报字段
+- 当前仅支持 `report`；不支持 `issue update`、`issue close`
+
+## 上报前完整性检查
+
+1. 先用 `wc -c /path/to/platform-issue.md` 记录源文件字节数，并确认文件包含所有唯一事实。
+2. 执行 `rabetbase issue report ... --dry-run --format compress`。
+3. 检查 `issue.description_original_bytes` 与源文件字节数一致，并确认 `issue.description_truncated=false`。
+4. 检查 `issue.description` 的结尾仍是源文件的最后一条事实，且 `issue.description_redactions` 只命中预期的敏感信息。
+5. 只有上述检查通过后才正式上报；正式提交成功前保留源 Markdown，便于逐字核对。
+
+如果 `issue.description_truncated=true`，不得把该结果当作完整上报。去除完全重复内容，或将大体积原始日志/文件通过文件服务保存，在正文中记录其 `filePath`、访问链接、字节数和摘要值；不得静默丢弃超出部分。
+
+## 文件与图片证据
+
+- 如需加入图片证据，先执行 `rabetbase file upload --file <图片路径>`，再用 `rabetbase file query-url --filepath <filePath> --long-term` 获取 Markdown 图片 URL
+- OSS 签名 URL 查询参数中的 `OSSAccessKeyId` 会保持原样，避免签名被脱敏改写；URL 外的 AccessKey 文本仍会脱敏
+- 需要确认当前 CLI 环境、登录态和配置时，先执行 [`rabetbase doctor`](rabetbase-doctor.md)
+
+## 参考
+
+- [SKILL.md](../SKILL.md)
+- [rabetbase-file.md](rabetbase-file.md)
+- [rabetbase-doctor.md](rabetbase-doctor.md)

package/skills/rabetbase/references/rabetbase-kb.md

@@ -0,0 +1,62 @@
+# rabetbase kb
+
+管理开发者侧当前解析应用下的 `company` 知识库。所有命令都通过标准工作区、`--app <name>` 或 `--appcode <code>` 解析目标应用，并在读写前后精确校验 `scope=company`、appCode 和 ID。
+
+> 边界：`lovrabet kb` 使用运行态 AK/当前应用/当前用户，面向个人知识库和可见知识搜索；`rabetbase kb` 使用开发者登录态，面向公司知识库管理。不要用其中一个替代另一个。
+
+## 命令
+
+```sh
+rabetbase kb list --format compress
+rabetbase kb list --appcode app-xxxxx --title "业务规则" --format compress
+rabetbase kb detail --id 60 --format compress
+rabetbase kb create --title "业务规则" --file ./knowledge.md --dry-run
+rabetbase kb create --title "业务规则" --file ./knowledge.md --yes
+rabetbase kb update --id 60 --file ./knowledge.md --expected-version 2 --dry-run
+rabetbase kb update --id 60 --file ./knowledge.md --expected-version 2 --yes
+rabetbase kb delete --id 60 --dry-run
+rabetbase kb delete --id 60 --yes
+```
+
+## 内容文件与安全输出
+
+- `create --file` 必填，`update --file` 可选；输入必须是可读的普通 UTF-8 文本或 Markdown 文件。
+- CLI 保留解码后的文本，不解析 JSON、不重排段落，也不把路径映射转换成其他格式。
+- 空白文件、目录、无效 UTF-8、缺失或不可读文件都会在网络请求前拒绝。
+- 结构化输出不包含正文，只展示 `contentByteSize`、`contentHash`、`snapshotHash` 等安全元数据。
+
+## list / detail
+
+- `list` 自动读取全部分页，并强制过滤为精确 company scope 与当前 appCode；服务端的 appCode/title LIKE 结果不能扩大客户端作用域。
+- `detail` 使用正安全整数 ID 精确读取，并验证返回 ID、scope 和 appCode。
+- 服务端 Long 字段即使序列化为十进制字符串，CLI 也只接受能安全转换的整数；超出 JavaScript 安全整数范围时失败关闭。
+
+## create
+
+- 只需 `--title`、`--file`；应用由标准全局应用解析得到。
+- 写前按 `(company, appCode, title)` 精确检查重复。
+- 正式执行必须显式 `--yes`，请求最多提交一次。
+- 正常响应使用服务端返回 VO/ID 并按 ID 回读。只有底层响应不确定时，才按同一 company/app/title 三元组做只读恢复；零条或多条都返回 outcome unknown，绝不自动重提。
+- 授权、权限、参数和其他确定性服务端错误直接失败，不能用旧状态回读伪装成成功。
+
+## update
+
+- `--id` 必填，`--title`、`--file` 至少传一个；服务端合同不支持 `--remark`。
+- 标题单独更新只发送 `{id,title}`，不会合并并回写未修改的 content，也不强求版本递增。
+- 内容更新发送 `{id,content}` 与可选 title；回读必须匹配内容哈希且版本高于写前版本。
+- `--expected-version` 是非原子的 read-before-write 断言；服务端请求没有 version 条件，不能把它描述为 compare-and-set。
+- 响应不确定时只按同一 ID 回读；证据不足返回 outcome unknown，不自动重提。
+
+## delete
+
+- 已验证服务端合同：`POST /admin/knowledge-base/delete`，请求体 `{id}`，成功为 `Result<Void>`。
+- 写前读取目标，校验 ID、company scope、appCode、可选 expected-version 和安全快照；`--expected-version` 仍是非原子断言，dry-run 明确输出 `atomicCompareAndSet: false`。
+- 目标明确不存在时返回 no-op 且不发请求；只有服务端 `DATA_NOT_EXIST (306)` 可识别为不存在，`PARAM_INVALID (103)`、权限、认证或传输错误不能降级为 no-op。
+- 正式删除最多提交一次，再按同一 ID 回读；明确不存在用于验证数据库软删除。
+- 服务端在事务提交后异步清理 RAG。CLI 不验证 RAG 文件/索引清理，不宣称物理删除。
+
+## 环境与授权
+
+- 使用 `--env daily` 或 `--env production` 选择 Profile 环境，不通过 URL 参数切换。
+- Production 写操作必须单独取得授权；需求、dry-run 或命令可用不等于写入授权。
+- 输出和错误不得包含 Cookie、Token、AccessKey 或知识正文。