原子命令

内置命令共 17 个，按分类如下。

AtomixCommandExecutor.execute(...) 的处理顺序：

1. DefaultCommandParser 解析原始命令行为 CommandInvocation。
2. CommandRegistry 按命令名/别名查找 CommandDefinition。
3. 若带 --help 或 -h，直接返回 HelpCommandResponse（不走业务 handler）。
4. 按命令分类路由到 ReadCommandExecutor、WriteCommandExecutor、EditCommandExecutor。
5. 对应 *CommandParser 解析参数，生成 *CommandRequest。
6. BaseCategoryCommandExecutor 补充通用字段：
   • request.command
   • request.rawCommand
7. 从 CommandHandlerRegistry 获取命令 handler 并执行。
8. 若成功响应且 outputContent 为空，使用 OutputRenderer 渲染。

由 DefaultCommandParser + CommandLineTokenizer 决定：

• kb 前缀可省略，kb ls 和 ls 都可解析。
• 支持长参数 --key value 与 --key=value。
• 支持短参数 flag（如 -l、-n）。
• 同一选项可重复出现，getOptionValues 可取多值（如 --must）。
• 支持单引号、双引号、反斜杠转义。

READ 类命令均为只读操作，不修改任何数据。

• 用法：kb ls [path] [-l] [--sort name|updated|size] [--limit N]
• 别名：dir
• 要点：最多 1 个位置参数。
• 参数说明：

• Request：LsCommandRequest(path, longFormat, sortBy, limit)
• Response：LsCommandResponse(entries: List<Entry>)

每个 Entry 包含：

示例：

# 列出根目录
kb ls

# 列出指定仓库的详细内容，按修改时间排序，限制 20 条
kb ls my-repo/docs -l --sort updated --limit 20

• 用法：kb tree <repo/path/> [--depth N] [--limit N]
• 要点：必须且只能有 1 个路径参数。
• 参数说明：

• Request：TreeCommandRequest(path, depth, limit)
• Response：TreeCommandResponse(root: TreeNode, renderedTree: String)

TreeNode 结构：

示例：

# 展示仓库目录树，深度限制为 3
kb tree my-repo --depth 3 --limit 50

• 用法：kb cat --name <repo/path.md> | --code <doc_code> [--range A:B | --head N | --tail N] [-n]
• 要点：--name 与 --code 二选一；--range/--head/--tail 互斥。
• 参数说明：

• Request：CatCommandRequest(name, code, lineNumbers, head, tail, range)
• Response：CatCommandResponse(code, name, path, type, createTime, modifiedTime, author, content: List<String>)

示例：

# 读取文件并显示行号
kb cat --name my-repo/docs/readme.md -n

# 读取文件的第 100 到 200 行
kb cat --name my-repo/docs/readme.md --range 100:200

# 通过 code 读取文件的前 50 行
kb cat --code abc123 --head 50

• 用法：kb summary --name <path> | --code <doc_code>
• 别名：sum
• 要点：--name 与 --code 二选一。
• 参数说明：

• Request：SummaryCommandRequest(name, code)
• Response：SummaryCommandResponse(code, name, type, createTime, modifiedTime, author, content: List<String>)

示例：

# 通过路径获取文件摘要
kb summary --name my-repo/docs/readme.md

# 通过 code 获取摘要（使用别名 sum）
kb sum --code abc123

• 用法：kb search "query" [scope] [--topk N] [--repo ...] [--path ...] [--mode lex|sem|hybrid] ...
• 别名：s
• 搜索模式：--lex / --sem / --hybrid 或 --mode lex|sem|hybrid，默认 LEX。
• 参数说明：

• Request：SearchCommandRequest(query, topk, offset, page, pageSize, repo, path, file, docCode, codes, repoCode, must, mustNot, mode, summaryOnly, titleOnly, headingOnly)
• Response：SearchCommandResponse(hits: List<SearchHit>)

每个 SearchHit 包含：

示例：

# 语义搜索，返回 Top 5
kb search "agent memory" --mode sem --topk 5

# 在指定 repo 中搜索，带 must 条件
kb search "部署指南" --repo my-repo --must "标签:重要"

# 搜索标题
kb search "API 文档" --title-only

• 用法：kb skill <skill_code> 或 kb skill -g <sub_doc_code>
• 要点：普通模式与 -g 子文档模式二选一。
• 参数说明：

• Request：SkillCommandRequest(skillCode, subDocCode)
• Response：SkillCommandResponse(skillCode, skillName, skillContent, root, renderedTree, subDoc)

SkillTreeNode 结构：

示例：

# 查看知识库概览
kb skill my-skill-code

# 获取某个子文档内容
kb skill my-skill-code -g sub-doc-code

• 用法：kb render <doc_code,doc_code,...> 或 kb render --codes <c1,c2,...>
• 要点：位置参数与 --codes 不能同时使用。
• 参数说明：

• Request：RenderCommandRequest(codes: List<String>)
• Response：RenderCommandResponse(items, failCount, failCodes)

每个 Item 包含：

示例：

# 渲染单个文档
kb render doc-code-1

# 渲染多个文档
kb render code1,code2,code3

# 使用 --codes 选项
kb render --codes code1,code2

• 用法：kb download_link --code <file_code> [--extract-is true|false]
• 要点：--code 必填。
• 参数说明：

• Request：DownloadLinkCommandRequest(code, extractIs)
• Response：DownloadLinkCommandResponse

示例：

# 获取原始文件下载链接
kb download_link --code file-code-123

# 获取解析后的内容下载链接
kb download_link --code file-code-123 --extract-is true

WRITE 类命令为写操作，会修改数据。

• 用法：kb write --name <path> | --repo-code <code> --path <path> --content <text> | --content-url <url> [--status draft|publish] [--if-match <etag>]
• 要点：
  • --name 与 --repo-code/--path 二选一。
  • --content 与 --content-url 二选一。
• 参数说明：

• Request：WriteCommandRequest(name, repoCode, path, content, contentUrl, status, message, ifMatch)
• Response：WriteCommandResponse(docCode, path, status, linesWritten, repoCode)

示例：

# 通过路径写入文件
kb write --name my-repo/docs/readme.md --content "# Hello World"

# 通过 repo-code + path 写入，并指定状态
kb write --repo-code repo-123 --path docs/readme.md --content-url https://example.com/content.md --status publish

# 带版本检查的写入
kb write --name my-repo/docs/readme.md --content "updated" --if-match "etag-abc"

• 用法：kb mkdir <repo/dir/> 或 kb mkdir --repo-code <code> --path <dir/> [-p|--parents] [--exist-ok true|false]
• 要点：
  • 路径参数模式与 --repo-code/--path 模式二选一。
  • parents 默认 true。
  • existOk 默认 true。
• 参数说明：

• Request：MkdirCommandRequest(name, repoCode, path, parents, existOk, message)
• Response：MkdirCommandResponse(repoCode, path, code, created)

示例：

# 创建目录
kb mkdir my-repo/docs/new-folder/

# 递归创建（默认行为）
kb mkdir --repo-code repo-123 --path docs/a/b/c/

# 已存在时报错
kb mkdir my-repo/docs/ --exist-ok false

• 用法：kb mv <src> <dst> 或 kb mv --from <src> --to <dst> 或 kb mv --doc-code <code> --to <dst>
• 要点：--doc-code 模式下不能再给源路径；支持 --if-match。
• 参数说明：

• Request：MvCommandRequest(from, to, docCode, ifMatch, message)
• Response：MvCommandResponse(docCode, oldPath, newPath, moved)

示例：

# 使用位置参数移动
kb mv my-repo/docs/old.md my-repo/docs/new.md

# 通过 doc-code 移动
kb mv --doc-code doc-123 --to my-repo/docs/new.md

# 带版本检查的移动
kb mv --from old.md --to new.md --if-match "etag-abc"

• 用法：kb cp --from <src> --to <dst> [--recursive] [--exist-ok true|false] [--publish true|false] 或 kb cp --doc-code <code> --to <dst> ...
• 要点：--from 与 --doc-code 二选一，--to 必填。
• 参数说明：

• Request：CpCommandRequest(from, docCode, to, recursive, existOk, publish)
• Response：CpCommandResponse(payload: Map<String, Object>)

示例：

# 复制文件
kb cp --from my-repo/docs/a.md --to my-repo/docs/b.md

# 通过 doc-code 复制并发布
kb cp --doc-code doc-123 --to my-repo/docs/copy.md --publish true

• 用法：kb rm <repo/path.md> 或 kb rm --doc-code <code> [--if-match <etag>]
• 要点：至少给一个目标（路径或 doc-code）。
• 参数说明：

• Request：RmCommandRequest(name, docCode, ifMatch)
• Response：RmCommandResponse(docCode, path, oldStatus, newStatus)

示例：

# 通过路径删除
kb rm my-repo/docs/old-file.md

# 通过 doc-code 删除，带版本检查
kb rm --doc-code doc-123 --if-match "etag-abc"

• 用法：kb publish --doc-code <code> | --name <path> [--if-match <etag>]
• 要点：--doc-code 与 --name 二选一。
• 参数说明：

• Request：PublishCommandRequest(docCode, name, ifMatch)
• Response：PublishCommandResponse(docCode, path, published, publishedAt)

示例：

# 通过 doc-code 发布
kb publish --doc-code doc-123

# 通过路径发布
kb publish --name my-repo/docs/draft.md

# 带版本检查
kb publish --doc-code doc-123 --if-match "etag-abc"

• 用法：kb init <skill_name>
• 要点：skill_name 为必填位置参数。
• 参数说明：

• Request：InitCommandRequest(skillName)
• Response：InitCommandResponse

示例：

# 初始化一个新知识库
kb init my-new-skill

• 用法：kb validate <skill_code>
• 要点：skill_code 为必填位置参数。
• 参数说明：

• Request：ValidateCommandRequest(skillCode)
• Response：ValidateCommandResponse

示例：

# 校验知识库结构
kb validate skill-code-123

• 用法：kb edit --patch <patch-body> [--help]
• 要点：
  • patch 必须包含 *** Begin Patch 与 *** End Patch。
  • patch 头必须显式声明 --name 或 --code（例如 *** Update File --name: ...）。
  • 也可通过 CommandExecutionContext.body 传 patch。
• 参数说明：

• Request：EditCommandRequest(patchBody, patchMeta: EditPatchMeta)
• Response：EditCommandResponse

Patch 格式：

*** Begin Patch
*** Update File --name: src/demo.txt
@@ -1,1 +1,2 @@
-line1
+line1 updated
+line2
*** End Patch

示例：

# 更新已有文件
kb edit --patch "*** Begin Patch
*** Update File --name: my-repo/docs/readme.md
@@ -1,1 +1,1 @@
-old content
+new content
*** End Patch"

# 新增文件
kb edit --patch "*** Begin Patch
*** Add File --name: my-repo/docs/new-file.md
+# New File
+Some content here
*** End Patch"

接口地址：POST /kb/atomix/execute

权限要求：atomix_command READ

请求参数：

请求示例：

{
  "command": "kb ls demo-repo/docs -l --sort updated --limit 20"
}

响应示例：

{
  "code": 8200,
  "message": "操作成功",
  "data": {
    "success": true,
    "command": "ls",
    "data": {
      "outputContent": "..."
    },
    "errorCode": null,
    "errorMessage": null,
    "errorDetails": {},
    "operation_source": "demo-repo/docs",
    "operation_target": null
  }
}

curl 示例：

curl -X POST "${domain}/kb/atomix/execute" \
  -H "Authorization: Bearer tk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "kb cat --name demo-repo/docs/intro.md --head 20 -n"
  }'

框架级错误码：