@@ -19,6 +19,8 @@ git add \
   skills/bailian-sandbox/reference \
   skills/bailian-memory/SKILL.md \
   skills/bailian-memory/reference \
+  skills/bailian-knowledge/SKILL.md \
+  skills/bailian-knowledge/reference \
   skills/bailian-web-search/SKILL.md
 
 vp staged
@@ -125,6 +125,18 @@ Once installed, just describe your task to your AI Agent — no need to assemble
 
 > More examples and scenarios: [Aliyun Model Studio CLI Site](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)
 
+### Try a knowledge base
+
+With a valid API key and workspace, preview initialization first:
+
+```bash
+bl knowledge init --workspace-id <workspace-id> --dry-run
+```
+
+Knowledge bases accrue running-time charges from creation, even without queries. The one-time Standard Edition 720-hour allowance is shared across knowledge bases and expires 30 days after activation for new users. Model calls cost extra; your remaining allowance is unknown. Review the plan and [billing rules](https://help.aliyun.com/zh/model-studio/billing-for-knowledge-base), then add `--yes` to the same command **after confirming the operation**, removing `--dry-run` to execute.
+
+Keep the returned IDs and recovery record. Closing the CLI or a later failure does not stop billing; follow the reported cleanup actions to delete unused knowledge bases. See the [Knowledge Studio quick start](packages/kscli/README.md#quick-start) for retrieval and cleanup. The `bailian-knowledge` Skill is available through `bl skill init`.
+
 ## Authentication
 
 ### Console Login (OAuth, Recommended)
 
@@ -124,6 +124,18 @@ irm https://bailian.aliyun.com/cli/install.ps1 | iex
 
 > 更多案例与使用场景：[阿里云百炼 CLI 官方主页](https://bailian.console.aliyun.com/cli?source_channel=cli_github&)
 
+### 体验知识库
+
+准备有效的 API Key 和工作空间后，先预览初始化计划：
+
+```bash
+bl knowledge init --workspace-id <workspace-id> --dry-run
+```
+
+知识库创建成功即持续按时计费，即使没有检索也一样。标准版一次性 720 小时额度由多个知识库共享，新用户开通后 30 天内有效；模型调用另计，当前账户剩余额度未知。查看计划与[计费规则](https://help.aliyun.com/zh/model-studio/billing-for-knowledge-base)，**确认本次操作后**，在同一命令中去掉 `--dry-run` 并添加 `--yes` 执行。
+
+保留返回的 ID 和恢复记录。退出 CLI 或后续步骤失败不会停止计费；按返回的清理动作删除不再需要的知识库。检索及清理示例见 [Knowledge Studio 快速开始](packages/kscli/README.zh.md#快速开始)。知识库 Skill `bailian-knowledge` 通过 `bl skill init` 安装。
+
 ## 认证方式
 
 ### 控制台登录（OAuth，推荐）
 
@@ -83,14 +83,16 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 
 1. **--help**：`runCommandHelp(ROUTES, [..., "--help"])` → stderr 含主要 flags；产品层另保留少量真实子进程 help 验证 shell/stdio/env
 2. **缺参**：带无害全局 flag（如 `--quiet`）且不传 required flag → `exitCode === 2`
-3. **--dry-run**：实现在联网/上传/写盘**之前**返回；断言 stdout JSON/文本
+3. **--dry-run**：静态命令在联网/上传/写盘之前返回；prepare 命令可先鉴权并读取完整远端计划，但不得产生远端或本地写入。断言 stdout JSON/文本及请求清单。
 4. **真实集成**：放在 skip 块**末尾**
 
 高风险命令额外要求：
 
 - `--help` 展示 runtime 注入的 `--yes`
 - 无 `--yes` 返回 exit code 7 和 JSON `type: "requires_confirmation"`
-- `--dry-run` 无需 `--yes`，且必须证明在任何远端请求或本地写入之前返回
+- `--dry-run` 无需 `--yes`；静态命令证明零网络/零写入，prepare 命令证明缺凭证返回 AUTH、只调用读接口且零写入
+- prepare 命令同时验证：实际无风险可执行，有风险时错误包含 plan/notices，预览/确认前不运行自动升级，服务端错误原样透传
+- `--introspect` 根/组/叶均跳过必填、validate、prepare、auth 和 run；输出实际产品路径及确定性 JSON
 - runtime 的离线 high-risk fixture 必须覆盖带 `--yes` 确实进入 `run()`，并断言 `yes` 不进入 command 自有 flags
 
 ## Journey 层（用户旅程全链路）
 
@@ -73,11 +73,13 @@ packages/commands/src/index.ts
   - `validate`(跨 flag 校验)
   - 高风险命令必须声明 `risk: { level: "high", message: <双语文案> }`;`--yes` 由 runtime 注入,命令不得自行声明
   - 普通业务命令的 `run(ctx)` 只读 `ctx.flags` / `ctx.settings` / `ctx.client`
-  - 声明 `risk` 的 `run(ctx)` 必须在任何远端请求或本地写入之前处理 `ctx.settings.dryRun` 并返回预览;runtime 只负责确认闸门,不替命令实现 dry-run
+  - 静态 `risk` 命令在 `run(ctx)` 的任何远端请求或本地写入前处理 `settings.dryRun`。声明 `prepare` 的命令由 runtime 先鉴权、只读规划、预览/确认，再调用 `run`；`run` 通过 `ctx.prepared` 读取同一份计划
+  - `prepare` 不得写文件/锁、申请租约、上传或调用模型；可读远端（包括只读 POST），因此 dry-run 仍需要凭证。计划声明实际 risk=null 或 high；静态 risk 保留最大风险用于 help/--yes
+  - 创建持续计费资源声明 `risk.reason: "billing"`，确认前说明费用，不把政策额度当成账户余额
   - `commands/auth/**` 可用 `ctx.authStore`,`commands/config/**` 可用 `ctx.configStore`;不要把这些持久化能力扩散到普通业务命令
   - `commands/plugin/**` 可用 `ctx.commandPacks`;产品 policy 由 runtime 绑定,命令不要自行 import 产品入口
 - [ ] 用户可见 Help 文案在命令文件中就近提供 `en-US` / `zh-CN`:命令 `description`、flag `description`、`notes` 和包含自然语言的 `exampleArgs`;纯命令语法示例可保留为字符串,服务端错误不翻译
-- [ ] 如果命令执行不可逆的删除/销毁(远端资源删除、永久移除),必须提供 `yes` switch flag,并在 `run` 中于 `dry-run` 分支之后、任何网络调用之前调用 runtime 的 `confirmDangerousAction(summary, flags.yes ?? false)`(参考 `knowledge/*-delete.ts`);`--yes` 的 flag description 用「Skip the confirmation prompt / 跳过确认提示」,`notes` 里声明不可撤销
+- [ ] 不可逆删除/销毁必须声明 `risk`，`--yes` 由 runtime 注入；命令不得自行声明 yes 或调用旧的 confirmDangerousAction。notes 说明不可撤销；计费确认和删除确认都使用 code 7 / requires_confirmation。
 - [ ] `packages/commands/src/index.ts`:新增或移除对应 export
 - [ ] 如果命令调用 Console Gateway,设置 `auth: "console"`;不要重复声明 console 凭证域 flags
 - [ ] 如果命令不需要网络或自己管理配置/登录,设置 `auth: "none"`;不要绕过 runtime auth stage
 
@@ -28,6 +28,8 @@
 - [ ] 如果新 flag 影响有效配置面,改 `packages/core/src/config/schema.ts` 的 `Settings` 接口
 - [ ] 如果对应 env var 或 config 文件字段,改 `packages/core/src/config/loader.ts` 的 `buildSettings`
 
+- [ ] 新全局 flag 在根/组/叶 `--introspect` 中可发现；命令自有 flag 不得占用 introspect；跨 flag validate 仍标注为未导出
+
 ### C. 文档层
 
 - [ ] `README.md` / `README.zh.md` 如果在示例里展示了相关命令,补充新 flag
 
@@ -59,6 +59,7 @@ bailian-gen      bailian-finetune  bailian-managed-agent   bailian-web-search
 - [ ] 新增领域目录时：补齐 `SKILL.md`（含 `metadata.version`），同步 `packages/cli/package.json` 的 reference 格式化路径、`.vite-hooks/pre-commit` 的生成物暂存清单、`tools/release/check.mjs` 的生成物校验清单；同步 hub 与共享协议的领域路由
 - [ ] 跑 `pnpm run sync:skill-assets`（或 commit 走 pre-commit），提交生成的 `reference/` 与 version 同步结果
 - [ ] 高风险命令生成的 reference 必须包含 `Risk` / `Risk message` 和简短 Agent safety 提示；带 `--yes` 的示例必须标注只能在确认后执行，不要手改生成物
+- [ ] `bailian-knowledge/reference` 由 `generate-knowledge-reference.ts` 通过 runtime 的 `buildCommandSchema` 生成，与 `--introspect` 共用数据源；分别读取 bl / kscli 的真实入口 map，不用字符串替换推导产品路径。统一生成入口负责归属迁移与旧文件清理。改动后运行 `tools/generate-reference.test.ts`、`tools/generate-knowledge-reference.test.ts` 和 `tools/knowledge-reference-renderer.test.ts`。
 - [ ] 默认模型若写在领域路由表（如 `bailian-gen`）：与命令 default / [model-add-remove.md](model-add-remove.md) 一并核对
 
 ## 完成后自查
@@ -77,5 +78,6 @@ bl skill init
 - ✗ 重新加回 `companions` 并宣称安装器硬依赖 → 与 `bl skill add` 合同不符
 - ✗ 软 hand-off 写成硬路径 `../bailian-*/SKILL.md` 当执行前提 → 子集安装断链
 - ✗ 只改 SKILL、忘改 `GROUP_OWNER_SKILL` → reference 落错 skill
+- ✗ 安装测试只隔离 HOME，遗漏 `/etc/codex` 或 `/Applications/ZCode.app` 等系统安装标记 → 开发机上多检测出 Agent。单元测试应模拟这些标记，并单独覆盖标记存在的行为；不要放宽 Agent 数量断言或修改产品识别规则来迁就测试环境。
 - ✗ 手改 `skills/*/reference/*.md` → 下次 generate 被覆盖
 - ✗ 改默认模型只动 flag description / reference，忘改领域 SKILL「When to use which command」表（见 [model-add-remove.md](model-add-remove.md)）
@@ -1,11 +1,54 @@
 # 文档管理命令手册
 
-文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
+文档管理覆盖目录同步、文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
 
 > **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](knowledge-cli-guide.md#通用约定)。
 
 ---
 
+#### `bl knowledge doc sync`
+
+将本地目录增量同步到已有知识库；`kscli` 的对应路径是 `kscli doc sync`。
+
+```bash
+# 先预览；允许读取远端，不创建状态目录、不上传、不删除
+bl knowledge doc sync --dir ./docs --index-id idx-xxx --dry-run
+
+# 仅新增不要求删除确认；替换或删除会返回确认要求（退出码 7）
+bl knowledge doc sync --dir ./docs --index-id idx-xxx
+
+# 确认预览中的替换范围后执行
+bl knowledge doc sync --dir ./docs --index-id idx-xxx --yes
+
+# 本地删文件默认保留远端；显式删除也先预览
+bl knowledge doc sync --dir ./docs --index-id idx-xxx --delete --dry-run
+bl knowledge doc sync --dir ./docs --index-id idx-xxx --delete --yes
+```
+
+| 参数                        | 说明                                                              |
+| --------------------------- | ----------------------------------------------------------------- |
+| `--dir <path>`              | 必填，本地文档目录；不跟随符号链接                                |
+| `--index-id <id>`           | 必填，已有文档知识库 ID                                           |
+| `--state-file <path>`       | 默认 `<dir>/.bailian/sync-state.json`，保存文件与远端文档对应关系 |
+| `--category-id <id>`        | 首次默认解析工作空间默认类目；后续使用状态中绑定的真实类目        |
+| `--sync-id <uuid>`          | 指定同步集；恢复丢失状态时需提供原 UUID                           |
+| `--delete`                  | 删除此同步集中本地已移除的索引文档                                |
+| `--poll-interval <seconds>` | 正数，默认 5 秒                                                   |
+
+每次扫描完整内容哈希，不因大小和修改时间相同而跳过校验。内容未变的已验证文档跳过上传；更新先等待新版就绪，再删除旧索引版本。重命名视为新路径添加与旧路径保留（启用 `--delete` 才删除旧路径）。不支持的格式、音视频、符号链接以及内部目录会列入跳过项；已托管路径变为不支持或不可读时，不将其视为可以删除。
+
+同步仅管理该同步集建立的文档；手工上传和其他同步集文档不会被 `--delete` 清理。源文件始终保留在数据中心。导入可能产生解析、向量化模型费用；删除文档甚至清空文档都不等于删除知识库，不会停止知识库运行时长计费。
+
+保留状态文件；CI 中将它作为持久数据保存，并为同一个同步集配置全局串行执行。本地锁不能防止不同机器同时写入。状态绑定 API 地址、工作空间、知识库、类目和同步集，不应复制到其他目标使用。
+
+状态丢失后，显式提供原 `--sync-id` 才尝试恢复当前仍存在的本地路径。只有唯一的远端路径标签匹配才恢复关联，并经确认重新上传，以重新建立内容验证；不会把远端 MD5 当成完整内容证明。远端无法还原路径的文档作为 orphan 保留，不自动删除。多个版本对应同一路径或导入结果未知时停止，需先核对资源。
+
+执行失败后保留状态文件；下一次运行先恢复未完成操作，恢复完成后重新预览剩余变更。不要删除状态或换名称来绕过未知写请求。确认之后若本地内容、状态版本或远端清单变化，执行停止，需重新预览。
+
+JSON 输出包含 `summary`、`actions`、`skipped`、`unmanaged`、`orphans`、`notices`、`stateFile`；失败时 stderr 的 `KNOWLEDGE_SYNC_INCOMPLETE` 提供最新可读 checkpoint，原错误继续输出并返回非零退出码。中途已完成的项目以 checkpoint 为准，不将部分失败报告为全部成功。
+
+---
+
 #### `bl knowledge doc list`
 
 列出知识库中的文档及其解析/索引状态。
 
@@ -125,6 +125,8 @@ bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
 
 创建知识库并导入数据中心文件或分类。
 
+**计费与确认**：创建成功即开始按运行时长计费，即使不检索也一样。标准版一次性 720 小时额度由多个知识库共享，新用户开通后 30 天内有效；模型调用另计，当前账户剩余额度未核实。见[计费规则](https://help.aliyun.com/zh/model-studio/billing-for-knowledge-base)。先用 `--dry-run` 预览；实际创建未带 `--yes` 时返回退出码 7（`requires_confirmation`），不会创建资源。确认本次操作及范围后才添加 `--yes`。
+
 **用法**
 
 ```bash
@@ -172,7 +174,9 @@ json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和
 - 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
 - 返回知识库 ID（`pipelineId`）和初始导入任务 ID（`ingestionId`）。
 - 使用 `doc status` 或 `--wait` 跟踪导入进度。
-- 如果 `--wait` 后部分文档解析失败，CLI 以非零退出码报错，知识库已创建成功的事实会在 hint 中提示。
+- 创建响应返回后立即向 stderr 报告知识库 ID、工作空间与持续计费提醒，quiet 模式也保留；JSON 结果保留 API 响应并追加资源和提醒信息。
+- 当前产品注册了删除命令时，资源中的 `cleanup.command` 给出真实 `bin`、`path` 和 `args`；text 模式显示可复制的指令。指令不自动添加 `--yes`，不存在唯一删除路径时不猜测路径。
+- 如果后续等待失败，命令返回非零退出码，知识库仍可能已创建并持续计费。根据已输出 ID 核对资源，不要盲目重复创建。确认不再需要后，使用 `bl knowledge delete --index-id <index-id> --workspace-id <workspace-id>`（kscli 对应 `kb delete`）清理；确认删除范围后才添加 `--yes`。仅删除文档或检索服务不能停止知识库规格计费。
 
 **示例**