ae-kb

ae-kb

跨技能协作

当剩余工作超出此技能的范围，或所需的前置条件需要其他能力时，请遵循协作协议。根据能力从本次运行中可用的技能里进行选择，保留已验证的上下文，并继续完成剩余任务。如果已加载此协议，请重复使用。

AE CLI（ae-cli）知识库命令通过以下方式调用：

ae-cli kb +<command> [options]
ae-cli kb source <create-text|read-text|replace|restore|preview|commit|cancel|check-updates|check-url-updates> [options]

全局规则

• 将此技能用于 AE 知识库任务：创建、导入已编译的快照、查询、使用大模型提问、列出可访问的知识库及其来源、检查索引、搜索页面、读取页面、检查状态、上传来源、添加 URL 来源、生成架构、编译、移除来源文件，以及删除知识库。
• 从知识库中搜索答案是最常见的任务。如果你要做的是这个，请直接前往探索知识库页面，并首先阅读 references/query-workflow.md——这是检索流程。下面的其他命令用于管理知识库，而不是从中获取答案。
• 如果检索到的页面将用于指导项目范围内的业务数据分析，请在运行任何数据查询之前阅读并遵循 references/analysis-workflow.md。当知识库命中内容确定了资产、定义、参数、时间规则、冲突或决策边界时，此要求为强制要求。执行前请验证语义覆盖范围；相关页面或知识库的局限性不代表任务已完成。对于未覆盖的要求，请继续常规分析，不要直接跳到未经验证的临时分析或 SQL。
• 知道必要输入后，可以直接执行读取操作。写入操作需要用户明确表达意图。只有 high-risk-write 命令需要 CLI 确认提示；获得明确授权后使用 --yes。
• 如果用户尚未验证目标，在执行破坏性或大范围写入之前，优先使用 --dry-run。
• 不要编造知识库名称、范围、来源 ID、来源显示名称或 JSON 负载。缺少值时请询问用户或查询已知上下文。
• 构造 --sources 引用（或 +read --source）时，请从 +list 输出中复制准确的 scope 和 name——如果不知道某个命名知识库的范围，请先运行 ae-cli kb +list。
• JSON 标志必须是有效的 JSON 字符串，通常在 shell 命令中用单引号括起来。
• 成功的命令默认返回 JSON。只有在表格更便于人工查看时才使用 --format table。信封中可能包含可选的 _notice.host_compat。
• --host <url> 可覆盖当前启用的 AE 主机。所有命令都支持此选项，且可放在子命令之后，例如：ae-cli kb +<command> --host <url>。
• 关键——主机兼容性（首先执行此操作）： 每次运行 ae-cli 后，检查 stderr 和 _notice.host_compat。如果任一处存在内容，请在回复开头用简短的 ⚠️ 版本警告提示，并逐字引用 npm i -g / npx skills add（或 update-cluster）命令行，然后再说明业务结果。这只是软性提示；ok: true 仍可能附带此通知。
• 检索（+index / +grep / +read）是确定性的，且不使用服务端大模型；简单事实查询请使用这些命令。如果问题需要综合多个页面的信息或进行多跳推理，请使用 +ask。

命令

命令	风险	用途
source create-text	写入	从文本、UTF-8 文件或显式标准输入创建一份普通 Markdown 源；保存时不进行编译。
source read-text	读取	读取完整的普通文本及其对应版本；可选择将原始 UTF-8 字节保存到新文件。
source check-url-updates	写入	为一个已编译的自定义 URL 源提交异步检查；成功仅表示已受理。
source check-updates	写入	使用计划检测器检查一个已编译的 Feishu 源；标记变更但不进行编译。
+ask	读取	在知识库中进行由大模型驱动的问答；适用于多页面综合或多跳问题。
+ask-status	读取	通过 --execution-id 查询某次 ask 执行的当前状态，无需轮询。
+list	读取	列出可访问的知识库，并按 buildStatus 筛选（默认：已编译）。
+list-sources	读取	列出某个知识库的源元数据，以便安全地查找准确的源标识符。
+index	读取	列出可访问的知识库及其 index.md 导航地图。
+grep	读取	对知识库页面进行关键词搜索；返回页面级结果数组（hitCount / pageKind / sections previews）。
+read	读取	读取完整的知识库页面、指定行范围，或（使用 --outline）仅读取页面标题树。
+new	写入	创建新的个人或公司知识库。
+import	写入	将已编译的 Markdown ZIP 导入为个人或公司只读快照；--scope 默认为 personal。
+import-status	读取	通过 --request-id 查询某个快照导入任务，无需轮询；输出包含已持久化的 scope。
+add	写入	上传本地文件（包括 ZIP 目录源）、非递归目录，或转换为 Markdown 的 HTTP(S) 页面。
+url	写入	直接上传 URL 源，可选显示名称和解析说明。
+schema	写入	为知识库生成编译架构。
+compile	写入	以增量或完整模式编译知识库。
+status	读取	查询知识库的当前状态。
usage list	读取	列出一页编译用量日志，包括以毫秒为单位的耗时。
+rm-source	高风险写入	通过稳定 ID 删除知识库中的一个源；准确的显示名称仅用于旧版兼容。
+remove	写入	删除整个知识库。

编译用量日志

ae-cli kb usage list --name handbook --scope personal --page 1 --page-size 20
ae-cli kb usage list --name handbook --jq '.items | map({createdAt, taskType, status, durationMs})' --format table

• 返回 { items, total, page, pageSize }。--page 默认为 1；--page-size 默认为 20，接受 1–100。请显式获取每一页。
• durationMs 是用量日志的 finishedAt - startedAt，单位为毫秒。时间戳缺失或无效时返回 null；零仍为零。即使 usageAvailable 为 false，失败记录也可能有耗时。
• 不会根据编译运行记录重建历史缺失的耗时。startedAt 和 finishedAt 是 ISO 时间戳或 null。
• 需要与 Web 编译用量列表相同的 Schema 读取权限。导入的快照不会公开用量。--scope 会精确选择个人或公司；省略时保留现有的先查个人、再查公司的逻辑。
• --dry-run 会预览读取操作而不发送请求。默认输出保留数字/null 值；如需紧凑表格，可使用现有的 --jq 和 --format table 选项。

过渡状态：过渡中 所属模块：te-claude External Knowledge Base Usage API 当前传输方式：通过 kbApi 进行经过身份验证的 External REST 网关目标：待定（编译用量列表） 复审时间：2026-12-14 退出条件：在 Gateway 提供等效功能后迁移，同时保留类型化分页及耗时/null 语义。

已发布版本历史

使用 references/versions.md 中介绍的九个版本命令，检查不可变的已发布历史、比较源内容变更，并明确将较早版本回滚为一次新的发布。这些命令用于管理历史记录；+index/+grep/+read/+ask 仍使用当前已发布的内容。

命令	风险	用途
+versions	读取	列出已发布版本和 latestVersionId。
+version-show	读取	显示一个版本的摘要。
+version-sources	读取	查找历史源 ID。
+version-diff	读取	比较两个版本。
+version-tree	读取	列出历史 ZIP/URL 源目录。
+version-read	读取	预览历史目录中的子文件。
+version-download	读取	保存一个普通历史文件源；不支持下载目录。
+rollback	高风险写入	恢复较早版本并创建新版本。
+rollback-status	读取	查询已持久化的回滚 Operation，不进行轮询。

源草稿替换与恢复

使用 references/source-mutations.md 进行文件/ZIP 源的替换与恢复。这些新命令使用 kb source <action>；+rollback 仍是整个知识库的发布操作。

命令	风险	用途
source replace	写入	替换普通文件草稿，或准备 ZIP 归档替换预览。
source restore	写入	从已发布版本恢复文件草稿，或准备 ZIP 源/子文件恢复预览。
source preview	读取	在确认前读取一页 ZIP 候选变更。
source commit	高风险写入	确认已审核的 ZIP 候选，其中可能包含删除操作。
source cancel	高风险写入	丢弃未提交的 ZIP 候选。

执行变更时，必须提供完全匹配的 --name、--scope、当前 --id 和当前 --expected-revision。文件替换会保留原始格式，但允许使用不同文件名。ZIP 文件必须使用 .zip 扩展名。不支持 URL/Feishu 和已删除的父源。更新仅影响草稿；仍需编译才能发布。不得自动提交 ZIP 预览。对于结果不确定的写入，不要重试。

ZIP 目录源

使用 +add --files '["./sources.zip"]' 将一个 ZIP 上传为一个可编辑的父级源，并保留其内部层级。服务器会执行归档校验并强制实施限制。这与 +import 不同，后者会创建只读的编译快照。将本地目录传给 +add 仍然只会上传其中直接包含的受支持文件；不会递归打包该目录。

使用 +list-sources 查找准确的父级 ID。ZIP 行包含 fileCount、sizeBytes、contentRevision 和 updateStatus。

命令	风险	用途
+source-ls	读取	列出一个目录页，其中包含修订版本、当前子项，以及相对于上次成功基线的已删除路径。
+source-read	读取	以 UTF-8/base64 格式读取子源文件，或保存原始字节。
+source-put	写入	添加一个本地文件，或显式替换 ZIP 相对路径完全匹配的文件。
+source-rm	高风险写入	删除一个子文件，或递归删除一个子目录。

ae-cli kb +source-ls --name handbook --id <source-id> --path "" --limit 100
ae-cli kb +source-ls --name handbook --id <source-id> --path "guides" --cursor <nextCursor>
ae-cli kb +source-read --name handbook --id <source-id> --path "guides/intro.md"
ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --output ./chart.png
ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --encoding base64
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7 --dry-run
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./revised.md --action replace --expected-revision 8
ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/new.md" --expected-revision 9
ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/obsolete" --recursive --expected-revision 10
ae-cli kb +compile --name handbook --mode incremental

• 从当前发现结果中复制源 ID、路径和修订版本。名称会先匹配个人范围，再匹配公司范围，遵循现有 External API；这些命令不支持覆盖范围。
• --path 是相对于 ZIP 根目录的路径，不是本地文件系统路径，也不是 raw/zip/... 路径。根目录列表使用空路径。非空路径不能是绝对路径，也不能包含空、点、父级或反斜杠路径段。
• 列表一次返回一页；继续查询时使用 nextCursor 和相同路径。修订版本发生变化时，写入前请重新开始发现流程。
• +source-read 读取源字节；+read 读取已编译的 Wiki 页面。默认的 UTF-8 输出遇到无效 UTF-8 时会失败。Base64 可保留二进制数据。--output 会创建新的本地文件，并拒绝覆盖现有文件。
• +source-put 接受一个不超过 50 MB 的文件。默认的 --action add 会拒绝已存在的路径；--action replace 会显式授权覆盖现有子项。不会静默执行 upsert。试运行会显示元数据，并隐藏文件内容。
• 写入时必须提供 --expected-revision。发生 409 冲突时会返回服务器错误代码；命令绝不会自动刷新后重试写入。
• +source-rm 会保留父级源。删除非空目录需要 --recursive；删除操作遵循 CLI 确认门控。只有在已获授权自动删除确切目标时才使用 --yes。+rm-source --id 会删除整个父级源。
• 修改会将父级源标记为已更改，但不会启动编译或重新生成 Schema。请显式运行增量编译；等待发布成功后再进入下一测试阶段。
• +status 是现有的聚合状态查询；它不是针对单次运行的事件查询，也不是 ZIP Diff 读取器。不要将其编译提交响应视为发布成功。
• 当前 KB 实现中未注册 Gateway 对应功能。这些命令复用了类型化的 External 源 API。

迁移状态：过渡中
所属模块：te-claude External Knowledge Base Sources API
当前传输方式：通过 kbApi 和多部分 kbUpload 进行经过身份验证的 External REST 调用
Gateway 目标：待定（ZIP 源目录和原始文件功能）
复审时间：2026-12-06
退出条件：当具备等效的类型化 Gateway 文件、目录和支持修订版本感知的修改功能时进行迁移；保留 CLI 文件处理和显式修改语义。

常见工作流

创建知识库

使用 +new 并指定名称。--scope 为可选参数，默认值为 company；有效范围为 personal 和 company。

ae-cli kb +new \
  --scope company \
  --name engineering-handbook \
  --description "Engineering handbook" \
  --tags '["engineering","handbook"]'

可选字段：

• --scope：范围，默认为 company。
• --description：描述，最多 200 个字符。
• --tags：JSON 数组，最多 2 个标签，每个最多 15 个字符。
• --project-id：可选的关联项目 ID。
• --project-name：可选的项目显示名称。

导入已编译的快照

仅当 ZIP 根目录包含 index.md 和至少一个 wiki/**/*.md 页面时，才使用 +import。服务会验证所有归档路径、限制、UTF-8 文本和 Wiki 链接。

ae-cli kb +import \
  --file ./knowledge-base.zip \
  --name "Imported handbook" \
  --description "Compiled documentation snapshot" \
  --tags '["docs","handbook"]'

# The submission returns requestId + queued. Query one snapshot later:
ae-cli kb +import-status --request-id <requestId>

• 结果始终是 personal 只读快照；没有 --scope、--force 或替换选项。

• 导入的快照支持列表、读取 Index/Wiki、grep/read、Ask 和删除。它们不提供 source、Schema、usage、compile、member、settings、所有权转移或公司发布操作。

• ZIP 限制为 50 MB，且仅支持 Markdown 文本。服务器会拒绝本地图片、附件、其他二进制文件、失效的 Wiki 链接和有歧义的 Wiki 链接。

• 提交会立即返回 {requestId, status: "queued"}，不会等待 ZIP 验证或发布完成。

• +import-status 会返回 queued、running、succeeded 或 failed 之一；成功时包含 knowledgeBaseId，失败时包含稳定的错误代码/消息。

• 如果已返回 requestId，请在重试前查询该请求。如果未收到请求 ID，请在使用相同名称重试前运行 ae-cli kb +list。重复导入同名内容会被拒绝。

• 过渡状态：过渡中

• 所属模块：te-claude External Knowledge Base Import API

• 当前传输方式：通过 kbUpload 提交、通过 kbApi 查询状态的已认证 KB 外部 REST。

• 网关目标：待定（拟议为 kb.snapshot.import）

• 复审时间：2026-12-01

• 退出条件：当提供等效的 multipart 导入能力时，迁移到类型化 Gateway 能力；或者，如果动态 Gateway 执行提供相同的文件处理和输出契约，则移除此命令。

上传文件或目录

当源是本地文件、本地目录，或需要先抓取并转换为 Markdown 再上传的页面时，使用 +add。

ae-cli kb +add \
  --name engineering-handbook \
  --scope company \
  --files '["./README.md","./docs","https://example.com/guide"]'

输入规则：

• --files 必须是字符串组成的 JSON 数组。
• 本地目录读取不递归。
• URL 条目必须以 http:// 或 https:// 开头。
• 支持的扩展名包括 Markdown/文本、办公文档、PDF、电子表格、演示文稿和常见图片。本地文件会以 multipart 文件 Blob 的形式上传；HTTP(S) 页面会先被抓取并转换为 Markdown。
• 重名文件会自动添加后缀，例如 name-1.ext、name-2.ext 等。

添加 URL 来源

添加单个 URL 来源，并可选传入显示名称或解析说明时，使用 +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"

--url 必须是 http(s)。服务器会根据 URL 自动检测平台：*.feishu.cn 或 *.larksuite.com 子域名下的 URL 会使用飞书处理流程解析（包括子文档，并使用服务器自身的飞书解析说明——这些 URL 会忽略 --parse-instruction）；所有其他 URL 都会作为常规网页抓取。

生成架构并编译

如果知识库需要编译架构，请先生成架构。

ae-cli kb +schema --name engineering-handbook --scope company

仅当 +status 报告 schema_generating，且用户明确要求替换当前生成尝试时，才使用 --force。替换可能会消耗额外的令牌。

架构和编译接受相同的可选模型引用。优先使用 ae-cli agent +list-models 返回的模型记录 id（Model.id）。历史上的 modelId 和无歧义的 modelId::scope 格式仍受支持。模型 displayName 是用于展示的文本，不是稳定的引用。

若要为本次生成添加一次性指导，而不更改已存储的知识库元数据，请传入 --custom-instructions。服务端会去除该值的首尾空白，将纯空白输入视为未提供，并接受最多 10,000 个 Unicode 字符。请勿包含机密或凭据。

ae-cli kb +schema \
  --name engineering-handbook \
  --scope company \
  --model <model-ref> \
  --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"

使用 --dry-run 可在发送请求前检查请求正文。生成进行期间，未使用 --force 的请求仅在未提供新模型或有效自定义指令时才是幂等的；否则会失败并返回 KB_SCHEMA_GENERATION_IN_PROGRESS。使用 --force 时，所选模型和自定义指令将应用于替换尝试。文本无效时会失败并返回 KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID。

源文件和架构准备就绪后进行编译：

ae-cli kb +compile --name engineering-handbook --scope company --mode incremental --model <model-ref>

有效的编译模式为 incremental 和 full；默认值为 incremental。

检查知识库状态

使用 +status 检查知识库的当前状态。

ae-cli kb +status --name engineering-handbook --scope company

询问知识（大模型）

当问题需要综合多个页面的信息或进行多跳推理时，使用 +ask——服务端 Agent 会运行完整的检索循环，并返回综合答案及其来源路径。如果确定性检索已足够，优先使用 +index -> +grep -> +read。

+ask 命令使用异步提交/轮询机制：默认情况下，它会自动轮询直至完成（每隔 5s 一次，最长 10 分钟），并输出最终答案及其执行 ID、来源、模型用量、工具调用次数和模型 ID。

# Default: submit and poll for completion
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

# Submit only, return executionId immediately (for batch processing)
ae-cli kb +ask --question "..." --no-wait

# Query execution status later
ae-cli kb +ask-status --execution-id <id>

• --question，别名 -q：必填的自然语言问题（1-2000 个字符）。
• --sources：可选的知识库引用 JSON 数组。省略时会搜索所有可访问的知识库。
• --model-id：可选的大模型 ID。省略时使用平台默认值。
• --locale：可选的区域设置：zh、en、ja 或 ko。
• --no-wait：可选的布尔标志。提交后立即返回 {executionId, status}，不进行轮询。
• 失败处理：如果执行失败，命令将以非零状态码退出，并在 stderr 上输出统一的 JSON 错误信封：{"ok":false,"error":{"type":"api","code":"<server-code>","message":"..."}}。稳定的服务端错误代码包括 model_unavailable、sandbox_unavailable、agent_skill_unavailable、dispatch_auth_unavailable、provider_failed、retrieval_error、timeout 和 process_restart。

列出可访问的知识库

如果只需要可访问知识库的元数据，而不需要加载 index.md 导航映射，请使用 +list。省略 --build-status 时默认使用 compiled；传入 idle / pending / compiling / compiled / failed 可按特定状态筛选（无论状态如何，都会列出系统知识库）：

ae-cli kb +list
ae-cli kb +list --locale zh
ae-cli kb +list --build-status compiled

探索知识库页面

当 Agent 需要像探索代码仓库一样探索知识库内容时，请使用确定性检索原语。这些端点不会在服务器端调用 LLM。

执行实际查询前，请先阅读 references/query-workflow.md — 它会在不进行爬取的情况下选择下一步有用的检索操作。内容涵盖候选项索引、复制路径 grep、直接读取有界范围内的链接短页面、读取同一页面的窗口、必要时对链接页面重新执行 grep、可选的基于大纲的范围，以及覆盖范围评估。下方内容是该工作流所依据的逐命令参考。

首先使用 +list 或 +index 查找可访问的知识库。如果还需要导航映射，请使用 +index：

ae-cli kb +list

ae-cli kb +index \
  --sources '[{"scope":"company","name":"engineering-handbook"}]'

然后使用 +grep 定位可能相关的页面：

ae-cli kb +grep \
  --query "sandbox configuration" \
  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
  --paths '["wiki/sandbox.md"]' \
  --top-k 10

响应是一个页面级 results 数组：每个条目对应一个页面，包含完整的 hitCount、pageKind（content 或 catalog）、最多 4 个 sections 预览（面包屑、sectionStartLine/sectionEndLine、文本预览）以及 moreSections。根据 hitCount 和预览决定要读取哪些页面；pageKind: "catalog" 表示模块目录页面 — 请将其条目视为详情页导航，而不是答案来源。使用 --offset sectionStartLine / --limit sectionEndLine - sectionStartLine + 1 读取相应章节范围；如果 moreSections > 0 且预览中没有答案，请对该页面单独重新执行 grep，以查看其所有命中结果。

当当前目标页面没有可靠的 grep 范围，且需要标题来选择章节时，请使用 +read --outline：

ae-cli kb +read \
  --source '{"scope":"company","name":"engineering-handbook"}' \
  --path "wiki/sandbox.md" \
  --outline

然后使用 +read 打开选定的窗口，窗口范围可依据页面组的章节边界或相邻的两个大纲标题确定：

ae-cli kb +read \
  --source '{"scope":"company","name":"engineering-handbook"}' \
  --path "wiki/sandbox.md" \
  --offset 42 \
  --limit 60 \
  --expand block

创建、读取或编辑文本源

收集文本、读取完整的可编辑源内容，或更新普通的 .md、.markdown 或 .txt 源时，请阅读文本源工作流。内容涵盖明确的范围、UTF-8/BOM/换行符保留、独占式本地输出、修订冲突、脱敏试运行和手动编译。Web 和 CLI 使用相同的源 ID。

列出源

首先列出源，以查找目标源的稳定标识符：

ae-cli kb +list-sources --name engineering-handbook --scope company

将响应中的确切 id 复制到 +rm-source。不要根据本地文件名、URL、显示名称或较早的上传响应来猜测源 ID。

• 过渡状态：过渡中
• 所属模块：te-claude 知识库源管理
• 当前传输方式：外部知识库 REST API
• 网关目标：待定
• 复审日期：2026-11-12
• 退出条件：当存在等效的源列表能力时，迁移到类型化的 Gateway 能力；或者，如果动态 Gateway 执行能提供同等的可发现性和安全输出契约，则移除此命令。

移除单个源

使用 +rm-source --id，并提供当前 +list-sources 响应返回的确切 ID。这是一个 high-risk-write 操作；除非用户已明确授权使用 --yes，否则请保留交互式确认。

ae-cli kb +rm-source \
  --name engineering-handbook \
  --scope company \
  --id cm-source-id

仅当稳定源 ID 不可用时，才为兼容旧版本而保留 --display-name：

ae-cli kb +rm-source \
  --name engineering-handbook \
  --display-name kb-1780046712-guide.md

如果用户只提供了不精确的源名称，不要猜测源 ID。运行 +list-sources，根据返回的元数据确定目标条目；仅当仍有多个条目无法区分时，才向用户询问。

删除知识库

使用 +remove 删除整个知识库。如果目标名称有任何歧义，请向用户确认。

ae-cli kb +remove --name engineering-handbook --scope company

命令参考

+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]

• --question，别名 -q：必填的自然语言问题（1-2000 个字符）。
• --sources：可选的知识库引用 JSON 数组。省略则搜索所有可访问的知识库。
• --model-id：可选的大模型 ID。省略则使用平台默认值。
• --locale：可选的区域设置：zh、en、ja 或 ko。
• --no-wait：可选。立即返回 {executionId, status}，而不是轮询。
• 适用场景：多页面综合或多跳问题。对于简单的事实查询，优先使用 +index / +grep / +read。
• 输出：默认情况下，轮询并返回 {executionId, answer, sources, modelUsage, toolCallCount, modelId}。使用 --no-wait 时，立即返回 {executionId, status}。失败时，以非零状态码退出，并通过统一的 stderr 信封返回，其中包含 error.type="api"、服务端的 error.code（model_unavailable、sandbox_unavailable、agent_skill_unavailable、dispatch_auth_unavailable、provider_failed、retrieval_error、timeout 或 process_restart）以及 error.message。

+ask-status

ae-cli kb +ask-status --execution-id <id>

• --execution-id：必填。由 +ask 提交后返回的执行 ID。
• 输出：返回一个成功的 CLI 信封快照。执行失败时，稳定的服务端代码仍位于 data.error.code：{"ok":true,"data":{"executionId":"...","status":"failed","error":{"code":"retrieval_error","message":"..."}}}。不会轮询。

+list

ae-cli kb +list [--build-status compiled] [--locale zh|en|ja|ko]

• --build-status：可选；取值为 idle / pending / compiling / compiled / failed 之一。省略时默认为 compiled（系统知识库无论状态如何都会列出）。
• --locale：可选的区域设置：zh、en、ja 或 ko。
• 响应项包含 buildStatus。

+index

ae-cli kb +index [--sources '[{"scope":"company","name":"kb-name"}]'] [--locale zh|en|ja|ko]

• --sources：可选的知识库引用 JSON 数组。省略则列出所有可访问的知识库。
• --locale：可选的区域设置：zh、en、ja 或 ko。

+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：必填的 wiki 页面或子目录 JSON 数组，必须复制自当前 +index、+grep 或 +read 导航链接。请勿自行编造路径。单个页面也必须使用数组，例如 ["wiki/sandbox.md"]。这与 +read --path（单个字符串）不同。
• --top-k：可选的最大命中数，1-50，默认为 10。
• --locale：可选的区域设置：zh、en、ja 或 ko。
• 结果中的每个页面条目都包含 hitCount（完整匹配数）、pageKind，以及带有 sectionStartLine / sectionEndLine 的 sections 预览；请使用节范围作为 +read 的读取窗口。

+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]

• --source：必填的 JSON 对象，指向一个且仅一个知识库。
• --path：必填的页面路径，相对于知识库根目录，例如 index.md 或 wiki/concepts/data-model.md。
• --offset：可选的 1 起始行号。
• --limit：可选的最大行数，1-2000。
• --expand：可选的 Markdown 块扩展模式。block 允许服务端在请求的行窗口之外包含完整的 Markdown 块；none 则严格遵循指定的 offset/limit 窗口。省略时使用服务端默认值 block。
• --outline：可选。仅返回整页的标题树（{level, heading, line}），内容为空，不受 --offset / --limit 影响。对于较长页面，可用此选项确定要读取的节。
• --locale：可选的区域设置：zh、en、ja 或 ko。

+new

ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."] [--project-name "..."]

+add

ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]' [--scope personal|company]

+import

ae-cli kb +import --file "./knowledge-base.zip" --name "<name>" [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."]

• --file：必填的本地 .zip 文件。
• --name：必填的个人知识库名称，最多 30 个字符。
• --description：可选，最多 200 个字符。
• --tags：可选的 JSON 数组，最多包含 2 个不重复的标签，每个标签最多 15 个字符。
• Scope 和最终构建状态由服务端生成，客户端无法提供。
• 输出：{requestId, status: "queued"}。请使用 +import-status；此命令不会轮询。

+import-status

ae-cli kb +import-status --request-id <requestId>

• --request-id：+import 返回的必填 ID。
• 输出：{requestId, status, knowledgeBaseId?, errorCode?, errorMessage?}。
• 返回单个快照，不会轮询。导入失败时，返回 status: "failed"，并附带稳定的错误代码和错误消息；请求未知或无权访问时，命令将以非零状态退出。

+url

ae-cli kb +url --name "<name>" --url "https://example.com/page" [--scope personal|company] [--display-name "..."] [--parse-instruction "..."]

+schema

ae-cli kb +schema --name "<name>" [--scope personal|company] [--force] [--model <model-ref>] [--custom-instructions "<one-time guidance>"]

• --custom-instructions：可选的单次运行架构生成指导。不会持久保存；仅包含空白字符的输入会被省略。服务端最多允许 10,000 个 Unicode 字符，并会拒绝不允许的控制字符。请勿包含机密或凭据。
• --force：仅当架构生成已在运行且用户明确请求替换时，才替换当前尝试。选定的模型和自定义指令将应用于新尝试，这可能会消耗额外的令牌。
• --dry-run：显示执行时将发送的相同 customInstructions 请求字段。
• --model：可选的稳定模型引用。优先使用 ae-cli agent +list-models 返回的 Model.id；历史 modelId 和 modelId::scope 仍兼容。
• --scope：可选的精确知识库范围。省略时，保留旧版从个人到公司的查找顺序。
• 错误：KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID 表示该字段未通过验证。KB_SCHEMA_GENERATION_IN_PROGRESS 表示生成正在进行，且未使用 --force 的请求提供了新模型或有效的自定义指令。

+compile

ae-cli kb +compile --name "<name>" [--scope personal|company] [--mode incremental|full] [--model <model-ref>]

+status

ae-cli kb +status --name "<name>" [--scope personal|company]

+list-sources

ae-cli kb +list-sources --name "<name>" [--scope personal|company] [--content-type all|text]

• --name：必填的知识库名称。
• --content-type：默认为 all；text 会选择普通的 .md、.markdown 和 .txt 来源（不区分大小写），并排除 URL 和 ZIP 来源。此列表命令中的范围为可选项。
• 输出：items 包含带有稳定 id 的有效来源。pendingDeletions 包含已软删除但仍包含在当前成功版本中的来源。deletionMaintenance 是独立字段，可能会报告已发布、但仍待清理的删除项。不会返回路径、哈希、凭据或来源内容。
• 在解读删除列表前，请检查 deletionProjection.state 和其 baseline。ready 且 pendingDeletions: [] 表示该基线下没有待处理删除项。若状态为 changing、review_required 或 unavailable，且 pendingDeletions: null，则表示无法确定；请显示 reasonCode，切勿将 null 转换为空列表。对于缺少可验证完整发布清单的旧版知识库，在发布真实版本前会返回 unavailable。
• 回滚会创建新的当前版本。较旧的删除回执无法覆盖该版本中的成员关系。之后删除来源需要再次发布。
• 删除来源前，请从当前响应中复制准确的 id；切勿猜测。

+rm-source

ae-cli kb +rm-source --name "<name>" --id "<source-id>" [--scope personal|company]

• --id：优先使用从 +list-sources 复制的稳定来源标识符。
• --display-name：仅在 ID 不可用时使用的旧版兼容选择器。
• 如果两者都提供，则以 --id 为准。该命令仅移除一个来源。

+remove

ae-cli kb +remove --name "<name>" [--scope personal|company]

导入和替换编译规则

使用架构导入命令上传、验证、编辑、修复、审查并应用 Markdown 编译规则候选项。这些操作不会根据来源生成规则，也不会导入已编译的快照。

检查飞书来源是否有更新

ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company

从 kb +list-sources 复制 ID。需要来源写入权限。只有已编译且未删除的飞书 URL 来源符合条件。API 使用与计划任务相同的检测器，包括跳过已有待处理变更的来源，以及使用来源所有者的沙盒凭据。它不会启动编译或清除待处理变更。

同步响应包含 sourceId、scanned、updated、failed、urlChangeState 和 updateStatus。scanned 统计候选项，而非已完成内容比较的数量；updated 统计新标记的来源。更新数为零可能表示内容未变、已有待处理变更、旧原始数据不可用，或状态已被并发修改。不得将其报告为所有内容完全相同的证明。检查失败会返回非 2xx 响应和 CLI 错误。超时不能证明操作已完成或已取消；决定是否重试前，请先读取 kb +list-sources。

传输方式：POST /agent/api/external/knowledge-bases/sources/check-updates，请求正文为 {name, sourceId, scope?}。--dry-run 只预览请求，不会进行身份验证或检查远程权限。

准入记录：source check-updates

• 分类：过渡性（此新检测器触发方式在 Gateway 中没有对应功能）。
• 负责模块：te-claude 知识库来源管理。
• 当前传输方式：通过 kbApi 和 CLI 令牌使用 KB 外部 REST。
• Gateway 目标：待定；有可用的等效来源更新检查功能时予以复用。
• 复审时间：2026-10-16 之后。
• 退出条件：Gateway 提供等效的授权和检测器语义后，将类型化命令迁移至 L2；如果没有额外价值，则使用 L3。

提交普通 URL 更新检查

ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company

只有尚未删除、sourceType=url、platform=custom、已编译且没有待处理更新的来源符合条件。Wiki/Schema 编译或输入准备正在进行时，请求会被拒绝。成功时返回 {accepted:true,sourceId}，仅表示请求已受理。它不提供最终统计数、任务 ID、检查状态、等待模式或完成情况查询。请读取 kb +list-sources 查看更新标记；状态未变无法区分操作已执行、没有变更、操作失败或结果已丢弃。标记为已变更后，请显式运行现有的增量编译。飞书仍使用同步的 source check-updates。

传输方式：POST /agent/api/external/knowledge-bases/sources/check-url-updates，请求正文为 {name,sourceId,scope?}。Dry-run 会预览请求，但不会发送请求。提交错误会保留服务器错误代码、详细信息和非零退出码。

准入记录：source check-url-updates

• 过渡状态：过渡性（此新 KB 外部功能在 Gateway 中没有对应功能）。
• 负责模块：te-claude 知识库来源管理。
• 当前传输方式：通过 kbApi 和 CLI 令牌使用 KB 外部 REST。
• Gateway 目标：待定；复用等效的异步普通 URL 来源检查功能。
• 复审时间：2026-10-24 之后。
• 退出条件：Gateway 提供等效的授权和异步提交语义后，若类型化标志有价值则迁移至 L2，否则使用 L3。