AE 知识库管理：用 ae-cli kb…

当需要通过 ae-cli kb 操作 Agentic Engine 知识库（查询、LLM 问答、导入快照、上传源、编译、版本回滚、删除）时使用。

适用场景

解决思路

1. 通过 `ae-cli kb +<command> [options]` 和 `ae-cli kb source <replace|restore|preview|commit|cancel|check-updates> [options]` 调用 AE CLI 知识库命令。
2. 搜索知识库回答问题是最常见任务：直接进入 Explore Knowledge Base Pages，并先读取 references/query-workflow.md，按其中的检索流程操作；其他命令用于管理知识库，不用于从知识库作答。
3. 当检索到的页面将指导项目范围业务数据分析时，在任何数据查询前先读取并遵循 references/analysis-workflow.md；一旦 KB 命中识别出已保存资产、定义、参数、时间规则、冲突或决策边界，不得直接跳到临时分析或 SQL。
4. 读操作在所需输入已知后直接运行；写操作要求明确用户意图，并通常保留确认提示，除非用户要求绕过确认。
5. 对破坏性或广泛写入，在用户尚未验证目标前优先使用 --dry-run。
6. 不要臆造知识库名称、scope、source ID、source 显示名或 JSON payload；缺失时询问用户或查询已知上下文。
7. 构建 --sources ref 或 +read --source 时，从 +list 输出复制精确的 scope 和 name；若命名知识库的 scope 未知，先运行 `ae-cli kb +list`。
8. JSON 标志必须是合法 JSON 字符串，通常在 shell 命令中用单引号包裹。
9. 成功命令默认返回 JSON；仅当表格更方便人工扫描时使用 `--format table`；返回信封可能包含可选的 `_notice.host_compat`。
10. `--host <url>` 可覆盖当前 AE host，每个命令都可用，可放在子命令之后，例如 `ae-cli kb +<command> --host <url>`。
11. 每次运行 ae-cli 后检查 stderr 和 `_notice.host_compat`；若任一存在，在用户回复开头加简短 ⚠️ 版本警告，并逐字引用 `npm i -g` / `npx skills add`（或 update-cluster）行，然后呈现业务结果；这是软提示，`ok: true` 也可携带该通知。
12. 检索 `+index` / `+grep` / `+read` 是确定性、服务端无 LLM 的；简单事实查找使用它们。问题需要跨多页综合或多跳推理时使用 `+ask`。
13. 使用 `source check-updates` 检查一个已编译 Feishu 源：从 `kb +list-sources` 复制 ID，要求源写权限，仅已编译且未删除的 Feishu URL 源符合条件；它使用与定时任务相同的检测器，会跳过已存在的 pending change，不启动编译、不清除 pending changes。
14. 运行 `ae-cli kb source check-updates --name 'Engineering Handbook' --id '<source-id>' --scope company --dry-run` 可预览请求；去掉 --dry-run 执行检查。
15. 解析 check-updates 同步响应中的 `sourceId`、`scanned`、`updated`、`failed`、`urlChangeState`、`updateStatus`；`scanned` 是候选计数而非完成内容比较，`updated` 是新标记数；零更新可能表示内容未变、已有 pending change、旧 raw 不可用或并发状态变化，不得报告为所有内容相同的证据。失败检查返回非 2xx 和 CLI 错误；超时不证明完成或取消，重试前读取 `kb +list-sources`。
16. 调用传输：`POST /agent/api/external/knowledge-bases/sources/check-updates`，body `{name, sourceId, scope?}`；`--dry-run` 只预览请求，不认证也不检查远程权限。
17. +ask：运行 `ae-cli kb +ask --question '<question>' [--sources '[{"scope":"company","name":"kb-name"}]'] [--model-id claude-sonnet-4-6] [--locale zh|en|ja|ko] [--no-wait]`。
18. `--question` 别名 `-q` 必填，自然语言问题 1-2000 字符。
19. `--sources` 可选 JSON 知识库引用数组；省略则搜索所有可访问知识库。
20. `--model-id` 可选 LLM 模型 ID；省略则用平台默认。
21. `--locale` 可选 `zh`、`en`、`ja`、`ko`。
22. `--no-wait` 可选；提交后立即返回 `{executionId, status}`，不轮询。
23. `+ask` 默认异步提交/轮询：每 5 秒轮询，最多 10 分钟，打印最终答案及 execution ID、sources、model usage、tool call count、model ID。
24. `+ask` 失败时命令非零退出并在 stderr 打印统一 JSON 错误信封：`{"ok":false,"error":{"type":"api","code":"<server-code>","message":"..."}}`；稳定 server codes 为 `model_unavailable`、`sandbox_unavailable`、`agent_skill_unavailable`、`dispatch_auth_unavailable`、`provider_failed`、`retrieval_error`、`timeout`、`process_restart`。
25. +ask-status：运行 `ae-cli kb +ask-status --execution-id <id>`；传入 +ask 返回的 execution ID；返回单个成功 CLI 信封快照，不轮询；失败执行时稳定 server code 在 `data.error.code`。
26. +list：运行 `ae-cli kb +list [--build-status compiled] [--locale zh|en|ja|ko]`；省略 --build-status 默认 compiled；可传 idle/pending/compiling/compiled/failed 过滤；系统知识库无论状态总是列出。
27. +list-sources：运行 `ae-cli kb +list-sources --name '<name>' [--scope personal|company]`；输出 items 含有效源及稳定 id；pendingDeletions 含软删除但仍在当前成功版本中的源；deletionMaintenance 单独报告已发布等待清理的删除；不返回路径、哈希、凭据和源内容。
28. 解释删除列表前检查 `deletionProjection.state` 及其 `baseline`；`ready` 且 `pendingDeletions: []` 表示该 baseline 无 pending deletion；`changing`、`review_required` 或 `unavailable` 且 `pendingDeletions: null` 表示未确定；显示 `reasonCode`，绝不能把 null 变成空列表；无可验证完整发布清单的旧库返回 unavailable，直到发布真实版本。
29. +index：运行 `ae-cli kb +index [--sources '[{"scope":"company","name":"kb-name"}]'] [--locale zh|en|ja|ko]`；省略 --sources 则列出所有可访问知识库。
30. +grep：运行 `ae-cli kb +grep --query '<keywords>' --sources '[{"scope":"company","name":"kb-name"}]' --paths '["wiki/page.md"]' [--top-k 10] [--locale zh|en|ja|ko]`；--query 别名 -q 必填；--sources 必填 JSON 数组；--paths 必填 JSON 数组，页面或子目录从 +index 复制，单页也用数组；与 +read --path（单个字符串）不同；--top-k 1-50 默认 10。
31. 解析 +grep 响应为页面级 `results` 数组：每项一页，含完整 `hitCount`、`pageKind`（`content` 或 `catalog`）、最多 4 个 `sections` 预览（breadcrumb、`sectionStartLine`/`sectionEndLine`、text preview）和 `moreSections`；用 hitCount 和预览决定读哪些页；`pageKind: 'catalog'` 是模块目录页，其条目作为详情页导航而非答案来源；用 `--offset sectionStartLine` / `--limit sectionEndLine - sectionStartLine + 1` 读取 section 范围；当 `moreSections > 0` 且答案不在预览中时，重新 grep 该单页查看所有命中。
32. +read：运行 `ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path 'index.md' [--offset 1] [--limit 200] [--expand block|none] [--outline] [--locale zh|en|ja|ko]`。
33. --source 必填 JSON 对象，恰好指向一个知识库；--path 必填，相对知识库根，如 index.md 或 wiki/concepts/data-model.md；--offset 可选 1-based 起始行；--limit 可选最大行数 1-2000；--expand 可选 Markdown block 扩展模式，block 允许服务器包含请求窗口外的完整 Markdown block，none 保持精确 offset/limit 窗口，省略用服务器默认 block。
34. `+read --outline` 可选，仅返回整页标题树 `{level, heading, line}` 且内容为空，独立于 --offset/--limit；在长页上用它选择要读的 section。
35. 当当前目标页没有可靠 grep 范围且需要标题选择 section 时，运行 `+read --outline`；然后用页面组 section 边界或两个相邻 outline 标题打开所选窗口，运行 `+read --offset 42 --limit 60 --expand block`。
36. +new：运行 `ae-cli kb +new --name '<name>' [--scope personal|company] [--description '...'] [--tags '["t1","t2"]'] [--project-id '...'] [--project-name '...']`；--scope 可选，默认 company；有效 scope 为 personal 和 company；--description 最多 200 字符；--tags 为 JSON 数组，最多 2 个标签，每个最多 15 字符；--project-id 可选绑定项目 ID；--project-name 可选项目显示名。
37. +import：运行 `ae-cli kb +import --file './knowledge-base.zip' --name '<name>' [--description '...'] [--tags '["t1","t2"]'] [--project-id '...']`；仅用于 ZIP 根包含 index.md 和至少一个 wiki/**/*.md 页面的编译快照；服务器验证所有归档路径、限制、UTF-8 文本和 Wiki 链接。
38. 导入结果总是 personal 只读快照；没有 --scope、--force 或替换选项；导入快照支持 list、Index/Wiki 读取、grep/read、Ask 和删除；不暴露 source、Schema、usage、compile、member、settings、ownership-transfer 或 company-publish 操作。
39. 导入 ZIP 限制 50 MB，仅支持 Markdown 文本；本地图片、附件、其他二进制、断开的 Wiki 链接和有歧义的 Wiki 链接会被服务器拒绝。
40. 提交 +import 后立即返回 `{requestId, status: 'queued'}`，不等待 ZIP 验证或发布。
41. +import-status：运行 `ae-cli kb +import-status --request-id <requestId>`；返回 queued、running、succeeded 或 failed；成功包含 knowledgeBaseId，失败包含稳定 error code/message；返回单个快照不轮询；未知或不可访问 request 非零退出。
42. 如果已返回 requestId，在重试前查询它；如果未收到 request ID，重试同名导入前运行 `ae-cli kb +list`；重复同名导入会被拒绝。
43. +add：运行 `ae-cli kb +add --name '<name>' --files '["./a.md","./docs","https://example.com/page"]' [--scope personal|company]`；--files 必须是字符串 JSON 数组；本地目录读取非递归；URL 条目必须以 http:// 或 https:// 开头。
44. +add 支持 markdown/text、office 文档、PDF、电子表格、演示文稿和常见图片等扩展名；本地文件以 multipart file blobs 上传；HTTP(S) 页面被抓取并转换为 markdown 后上传；重复文件名自动加后缀 `name-1.ext`、`name-2.ext` 等。
45. 用 `+add --files '["./sources.zip"]'` 上传一个 ZIP 作为一个可编辑父源，保留内部层级；归档验证和限制由服务器执行；这与 +import 创建只读编译快照不同。向 +add 传本地目录仍只上传其直接支持文件，不会递归打包该目录。
46. 用 +list-sources 发现精确 parent ID；ZIP 行包含 fileCount、sizeBytes、contentRevision、updateStatus。
47. +url：运行 `ae-cli kb +url --name '<name>' --url 'https://example.com/page' [--scope personal|company] [--display-name '...'] [--parse-instruction '...']`；--url 必须是 http(s)。
48. 服务器根据 URL 自动检测平台：`*.feishu.cn` 或 `*.larksuite.com` 子域名的 URL 用 Feishu pipeline 解析（包括子文档，使用服务器自己的 Feishu 解析指令，--parse-instruction 对它们被忽略）；所有其他 URL 作为普通网页抓取。
49. +schema：运行 `ae-cli kb +schema --name '<name>' [--scope personal|company] [--force] [--model <model-ref>] [--custom-instructions '<one-time guidance>']`；需要编译 schema 时先生成 schema。
50. 仅当 +status 报告 schema_generating 且用户明确想替换当前生成尝试时使用 --force；替换可能消耗额外 token。
51. Schema 和 Compile 接受相同可选模型引用；优先使用 `ae-cli agent +list-models` 返回的模型记录 `id`（`Model.id`）；历史 `modelId` 和无歧义 `modelId::scope` 仍兼容；模型 displayName 是展示文本，不是稳定引用。
52. 通过 --custom-instructions 给本次生成增加一次性指导，不改变存储的知识库元数据；服务器 trim 该值，纯空白视为缺省，最多接受 10,000 Unicode 字符；不要包含 secrets 或凭据。
53. 使用 --dry-run 在发送前检查请求体；生成运行中，不带 --force 的请求只有在未提供新模型或有效 custom instructions 时才幂等；否则失败并返回 KB_SCHEMA_GENERATION_IN_PROGRESS。带 --force 时，所选模型和 custom instructions 应用于替换尝试。无效文本失败并返回 KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID。
54. +compile：运行 `ae-cli kb +compile --name '<name>' [--scope personal|company] [--mode incremental|full] [--model <model-ref>]`；有效 compile modes 为 incremental 和 full；默认 incremental。
55. +status：运行 `ae-cli kb +status --name '<name>' [--scope personal|company]` 检查知识库当前状态。
56. +rm-source：运行 `ae-cli kb +rm-source --name '<name>' --id '<source-id>' [--scope personal|company]`；--id 首选稳定源标识符，从 +list-sources 复制；--display-name 仅在 ID 不可用时作为遗留兼容选择器；两者都提供时 --id 优先；该命令只删除一个源。
57. 若用户只给宽松源名，不要猜 source ID；运行 +list-sources，根据返回元数据识别目标行，仅当多行仍不明确时询问。
58. +remove：运行 `ae-cli kb +remove --name '<name>' [--scope personal|company]` 删除整个知识库；若有歧义，与用户确认目标名称。
59. 版本历史：用 references/versions.md 中的九个版本命令检查不可变发布历史、比较源变化并显式回滚早期版本作为新发布；这些命令管理历史，`+index/+grep/+read/+ask` 继续使用当前已发布内容。
60. +versions：运行列出已发布版本和 latestVersionId。
61. +version-show：运行显示一个版本摘要。
62. +version-sources：运行发现历史 source IDs。
63. +version-diff：运行比较两个版本。
64. +version-tree：运行列出一个历史 ZIP/URL 源目录。
65. +version-read：运行预览一个历史目录子文件。
66. +version-download：运行保存一个普通历史文件源；不支持目录下载。
67. +rollback：运行恢复较早版本并创建新版本。
68. +rollback-status：运行查询已持久化的 rollback Operation，不轮询。
69. 源草稿替换与恢复：使用 references/source-mutations.md 处理文件/ZIP 源替换和恢复；这些新命令使用 `kb source <action>`；`+rollback` 仍是整 KB 发布操作。
70. source replace：运行替换普通文件草稿，或准备 ZIP 归档替换预览。
71. source restore：运行从已发布版本恢复文件草稿，或准备 ZIP 源/子文件恢复预览。
72. source preview：运行在确认前读取 ZIP 候选变更的一页。
73. source commit：运行确认已审查的 ZIP 候选，包括任何删除。
74. source cancel：运行丢弃未提交的 ZIP 候选。
75. 源变更要求精确 --name、--scope、当前 --id 和当前 --expected-revision；文件替换保持原格式但允许不同文件名；ZIP 要求 .zip；不支持 URL/Feishu 和已删除父源；更新仅影响草稿，发布仍需编译；ZIP 预览不得自动提交；不确定的写入不要重试。
76. ZIP 目录源：使用 `+add --files '["./sources.zip"]'` 上传；用 +list-sources 发现精确 parent ID。
77. +source-ls：运行 `ae-cli kb +source-ls --name handbook --id <source-id> --path '' --limit 100` 列出一个目录页；用 `--path 'guides' --cursor <nextCursor>` 继续。
78. +source-read：运行 `ae-cli kb +source-read --name handbook --id <source-id> --path 'guides/intro.md'` 读取子源文件为 UTF-8/base64，或保存原始字节；保存用 `--output ./chart.png`，base64 用 `--encoding base64`。
79. +source-put：运行 `ae-cli kb +source-put --name handbook --id <source-id> --path 'guides/new.md' --file ./new.md --action add --expected-revision 7 --dry-run` 先 dry-run；去掉 --dry-run 执行添加；替换用 `--action replace --expected-revision 8`。
80. +source-rm：运行 `ae-cli kb +source-rm --name handbook --id <source-id> --path 'guides/new.md' --expected-revision 9` 删除一个子文件；删除非空目录加 `--recursive --expected-revision 10`。
81. ZIP 目录规则：从当前发现复制 source ID、路径和 revision；名称按 personal 再到 company 解析，遵循现有 External API；这些命令没有 scope override。
82. `--path` 相对于 ZIP 根，不是本地文件系统或 `raw/zip/...` 路径；根列表用空路径；非空路径不能是绝对路径，也不能包含空段、点段、父段或反斜杠段。
83. 列表返回一页；用 nextCursor 和相同 path 继续；revision 变化时，在写入前重启发现。
84. `+source-read` 读源字节；`+read` 读编译后的 Wiki 页面；默认 UTF-8 输出在无效 UTF-8 上失败；base64 保留二进制数据；`--output` 创建新本地文件并拒绝覆盖现有文件。
85. `+source-put` 接受一个最多 50 MB 的文件；默认 `--action add` 拒绝已存在路径；`--action replace` 显式授权覆盖已存在子文件；没有静默 upsert；dry-run 显示元数据并遮盖文件内容。
86. 写入必须提供 `--expected-revision`；409 冲突返回服务器错误码；命令绝不自动刷新并重试写入。
87. `+source-rm` 保留父源；删除非空目录需要 `--recursive`；删除遵循 CLI 确认门；仅在自动化删除确切目标已被授权时使用 `--yes`；`+rm-source --id` 删除整个父源。
88. 一次 mutation 标记父源 changed，但不启动编译或重新生成 Schema；显式运行 incremental compilation；等待成功发布后再进入下一测试阶段。
89. `+status` 是现有聚合状态查询；不是 per-run event 或 ZIP Diff reader；不要将其编译提交响应解释为成功发布。
90. 该 ZIP 源目录和 raw-file 能力当前无 Gateway 等价实现，复用 typed External source APIs；transitional，owning module 为 te-claude External Knowledge Base Sources API，传输为 authenticated External REST via kbApi 和 multipart kbUpload，Gateway target TBD，review after 2026-12-06，exit condition 为迁移到等价 typed Gateway 文件/目录/revision-aware mutation 能力。
91. 创建知识库工作流：运行 `ae-cli kb +new --scope company --name engineering-handbook --description 'Engineering handbook' --tags '["engineering","handbook"]'`。
92. 导入编译快照工作流：运行 `ae-cli kb +import --file ./knowledge-base.zip --name 'Imported handbook' --description 'Compiled documentation snapshot' --tags '["docs","handbook"]'`，然后用 `+import-status --request-id <requestId>` 查询。
93. 上传文件或目录工作流：运行 `ae-cli kb +add --name engineering-handbook --scope company --files '["./README.md","./docs","https://example.com/guide"]'`。
94. 添加 URL 源工作流：运行 `ae-cli kb +url --name engineering-handbook --scope company --url https://example.com/guide --display-name guide --parse-instruction 'Keep headings and code blocks'`。
95. 生成 Schema 和编译工作流：先运行 `ae-cli kb +schema --name engineering-handbook --scope company`；再运行 `ae-cli kb +compile --name engineering-handbook --scope company --mode incremental --model <model-ref>`。
96. 检查状态工作流：运行 `ae-cli kb +status --name engineering-handbook --scope company`。
97. Ask 工作流：需要多页综合或多跳时运行 `ae-cli kb +ask --question 'How do we troubleshoot payment alerts?' --sources '[{"scope":"company","name":"engineering-handbook"}]' --model-id claude-sonnet-4-6 --locale zh`；批量处理用 `--no-wait`；稍后用 `+ask-status --execution-id <id>` 查询。
98. 列表工作流：运行 `ae-cli kb +list`、`ae-cli kb +list --locale zh` 或 `ae-cli kb +list --build-status compiled`。
99. 探索知识库页面工作流：先运行 `ae-cli kb +list` 或 `+index` 发现可访问知识库；`+index` 用于还需要导航图时；再运行 `+grep` 定位可能页面；再 `+read --outline` 选择 section；再 `+read` 打开所选窗口。
100. 列出源工作流：运行 `ae-cli kb +list-sources --name engineering-handbook --scope company`；把响应中精确 id 复制到 `+rm-source`；不要从本地文件名、URL、显示名或旧上传响应猜测 source ID。
101. 删除一个源工作流：运行 `ae-cli kb +rm-source --name engineering-handbook --scope company --id cm-source-id`；这是 high-risk-write，保留交互确认，除非用户明确授权 --yes；仅当稳定 source ID 不可用时用 `--display-name`。
102. 删除知识库工作流：运行 `ae-cli kb +remove --name engineering-handbook --scope company`；若有歧义先与用户确认目标名。

适用边界 · 注意事项

• 当尚未选择要搜索哪个知识库时，先用 ae-kb-discovery skill；本技能在目标已选后运行检索。
• 不适用于非 AE/非 ae-cli 知识库任务；必须使用 ae-cli kb 命令，且不得猜测知识库名称、scope、页面路径、source ID、source 显示名、JSON payload 形状或 URL 格式。
• 当检索结果将指导项目范围业务数据分析时，不能直接跳到临时分析或 SQL；必须先读取并遵循 references/analysis-workflow.md。