@@ -53,3 +53,7 @@ packages/cli/scene/**/outputs/
 
 # Local scratch / plan drafts (never commit)
 .scratch/
+
+# Internal planning and QA handoff documents stay outside the public repository
+/docs/superpowers/
+/docs/testing/
@@ -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
@@ -76,6 +76,7 @@ Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐
 | 安装文档          | 改安装、鉴权、验证流程或线上 install 页面                             | [docs/agents/install-doc-change.md](docs/agents/install-doc-change.md)       |
 | 发布              | channel / stable 发布到 npm（CI 驱动）                                | [docs/agents/publish.md](docs/agents/publish.md)                             |
 | Change Log        | 发版说明 / 历史版本说明                                               | [docs/agents/changelog-write.md](docs/agents/changelog-write.md)             |
+| 公开内容检查      | 公开前检查凭证、真实资源、内部文档及 Git 历史                         | [docs/agents/public-content-review.md](docs/agents/public-content-review.md) |
 | 工具链调整        | lint 规则 / 构建配置 / 依赖升级                                       | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md)               |
 | Command Pack      | 扩展包 / 白名单 / plugin 管理命令                                     | [docs/agents/command-pack.md](docs/agents/command-pack.md)                   |
 | dsh 插件          | 改 `packages/bailian-kb-dsh` / `bailian-memo-dsh`、dsh 依赖、插件发布 | [docs/agents/dsh-plugin.md](docs/agents/dsh-plugin.md)                       |
 
@@ -6,6 +6,25 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 [中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md)
 
+## [2.6.0] - 2026-10-27
+
+### Added
+
+- **Knowledge initialization**: Add `knowledge init` to upload a sample, create a knowledge base and retrieval service, and verify retrieval, with recovery and resource reuse.
+- **Directory sync and file import**: Add `knowledge doc sync` and `knowledge doc import` for local directories and existing files.
+- **Multimedia knowledge bases**: Support audio/video knowledge bases, parser configuration, streaming uploads, image-only search, and online search filters.
+- **Agent capability discovery**: Add `--introspect` and the `bailian-knowledge` skill, with corresponding capabilities in Knowledge Studio CLI.
+
+### Changed
+
+- **Chat output**: Separate answers, phases, tools, sources, and usage in structured output; quiet mode emits only the final answer.
+- **Knowledge-base creation**: Add billing notices, resource records, and cleanup guidance.
+
+### Fixed
+
+- Reject blank required inputs in knowledge commands.
+- Report completed, unconfirmed, and unexecuted batches when chunk deletion fails.
+
 ## [2.5.1] - 2026-10-23
 
 ### Added
 
@@ -6,6 +6,25 @@
 
 [English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md)
 
+## [2.6.0] - 2026-10-27
+
+### 新增
+
+- **知识库初始化**：新增 `knowledge init`，串联样例上传、建库、检索服务创建及首次检索验证，支持恢复和资源复用。
+- **目录同步与文件导入**：新增 `knowledge doc sync` 和 `knowledge doc import`，支持同步本地目录及导入已有文件。
+- **多媒体知识库**：支持音视频知识库、解析配置、流式上传、纯图片检索及在线检索过滤配置。
+- **Agent 能力发现**：新增 `--introspect` 结构化命令说明和 `bailian-knowledge` Skill；Knowledge Studio CLI 同步提供对应能力。
+
+### 变更
+
+- **知识库问答输出**：结构化输出区分最终答案、阶段、工具、来源和用量；quiet 模式仅输出最终答案。
+- **建库提示**：补充计费说明、资源记录与清理指引。
+
+### 修复
+
+- 拒绝知识库命令中的空白必填参数。
+- 切片批量删除失败时，明确报告已完成批次、结果未确认批次及未执行部分。
+
 ## [2.5.1] - 2026-10-23
 
 ### 新增
 
@@ -126,6 +126,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?spm=a2ty07.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)
@@ -221,3 +233,7 @@ Memory documentation (Chinese): [capability matrix](https://github.com/modelstud
 | Get API Key                  | https://bailian.console.aliyun.com/cn-beijing/?spm=a2ty07.github&tab=app#/api-key                   |
 | Get Token Plan API Key       | https://bailian.console.aliyun.com/cn-beijing?spm=a2ty07.github&tab=plan#/efm/subscription/overview |
 | Get AccessKey                | https://ram.console.aliyun.com/manage/ak                                                            |
+
+### RAG audio and video
+
+`bl knowledge doc import --index-id <id> --doc-id <fileId>` imports an existing file into a knowledge base; `doc list --details` shows per-file processing settings. Media support includes parser options, streaming uploads, and media references in search/chunk output. Chat JSON separates the final answer from phases, tools, docs, usage, and raw events; quiet mode emits only the final answer. See the [command guide](docs/knowledge/knowledge-cli-guide.md).
@@ -125,6 +125,18 @@ irm https://bailian.aliyun.com/cli/install.ps1 | iex
 
 > 更多案例与使用场景：[阿里云百炼 CLI 官方主页](https://bailian.console.aliyun.com/cli?spm=a2ty07.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，推荐）
@@ -220,3 +232,7 @@ Memory 用户文档：[能力矩阵](https://github.com/modelstudioai/cli/blob/m
 | 获取 API Key            | https://bailian.console.aliyun.com/cn-beijing/?spm=a2ty07.github&tab=app#/api-key                   |
 | 获取 Token Plan API Key | https://bailian.console.aliyun.com/cn-beijing?spm=a2ty07.github&tab=plan#/efm/subscription/overview |
 | 获取 AccessKey          | https://ram.console.aliyun.com/manage/ak                                                            |
+
+### RAG 音视频接入
+
+`bl knowledge doc import --index-id <id> --doc-id <fileId>` 将历史文件导入已有库；`doc list --details` 查看文件级处理参数。支持音视频 parser、流式上传，以及检索/切片中的媒体来源展示。问答 JSON 将最终 answer 与 phases/tools/docs/usage/events 分开保存，quiet 仅输出最终回答。参阅 [命令指南](docs/knowledge/knowledge-cli-guide.md)。
@@ -87,14 +87,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
 
@@ -29,6 +29,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
@@ -53,6 +55,7 @@ pnpm -F bailian-cli exec tsx src/main.ts <command> --new-flag x   # 实测一遍
 
 ## 常见漏点
 
+- `required: true` 只校验参数是否提供，不拒绝空字符串；服务 ID 等非空约束放在命令 `validate` 中，并覆盖空值、纯空白值及 dry-run 的 stderr JSON / 退出码。多模态消息须在解析角色前缀后判断内容，保留有效图片和工具调用。
 - SDK 的通用参数解析器可能接受其他 Provider 的资源类型；产品命令应在鉴权和 dry-run 输出前限制支持的类型，错误文案不得回显资源凭证或任意输入值。
 - 定向创建仅解析新增资源声明；已有项目中的 instructions / Memory 正文已完成文件读取，不能再把它们当作原始文件路径解析。跨资源引用继续交给完整项目的定向 plan 校验。
 - 修改请求超时时，检查底层 HTTP 限制：core 的公共 HTTP 请求层仅为已设置超时计时器的请求关闭 `headersTimeout`，由请求 `AbortSignal` 控制响应头等待；保留 `bodyTimeout` 空闲保护，不全局关闭其他请求的超时。仅设置 Agent 默认值会被 Node `fetch` 的逐请求默认值覆盖。流式读取的总时长另由调用方管理，不能据此宣称 `--timeout` 覆盖整个流。