balacli

Knowledge Claw 命令行工具，提供流式问答、知识库管理、文件上传、文档检索与仓库文档生成能力。

版本号规则：本包按发布日期命名，CalVer YYYY.MMDD.N（major = 年，minor = MMDD，patch = 当日发布序号），如 2026.806.0。 balacli --version 直接输出该版本号，与 package.json 完全一致；同一天多次发布时最后一位递增。 不用 2026.08.05 是因为 npm 不接受前导零（会被规范化为 2026.8.5）且无可递增位。

快速开始

安装

npm install -g balacli

若需锁定特定版本（如配合已发布的技能文档使用），带上精确版本号：npm install -g [email protected]。

配置服务地址（必需）

本包不内置任何服务地址，使用前必须先指向你的 Knowledge Claw 服务端：

export BALA_API_BASE="https://your-site.example.com"   # 站点根域名，不带路径

也可在下一步 balacli init 中写入配置文件。未配置时任何联网命令会直接报错并引导你完成配置。

初始化配置

balacli init

交互式引导创建配置文件 ~/.balacli/config.json，已有配置时可重新运行以更新。

{
  "apiBase": "https://your-site.example.com",
  "apiKey": "sk-your-api-key",
  "userId": "[email protected]"
}

配置字段说明

| 字段 | 必填 | 用途 | 示例值 | |---|---|---|------------------------| | apiBase | 是 | 服务站点根域名（本包无内置地址） | https://your-site.example.com | | apiKey | 是 | API 密钥（从个人中心 API Key 管理页面获取），作为 X-Api-Key 请求头发送 | abc123... | | userId | 是 | 用户标识（推荐填真实账号/邮箱，以保证数据集权限生效） | [email protected] | | llm | 可选 | repowiki 文档生成使用的 LLM 配置（baseUrl / apiKey / model，另支持 protocol / maxTokens / temperature） | 见下文「仓库文档生成」 |

优先级：环境变量 > 配置文件。环境变量可用于临时覆盖：

BALA_USER_ID="[email protected]" balacli ask "你好"

对应环境变量名：BALA_API_KEY、BALA_USER_ID、BALA_API_BASE；repowiki LLM 对应 BALA_LLM_BASE_URL、BALA_LLM_API_KEY、BALA_LLM_MODEL。

用法

流式问答

# 纯对话
balacli ask "用一句话介绍一下你自己"

# 启用 RAG（指定一个或多个知识库 ID）
balacli ask "项目最近的发布要点" --kb <datasetId>

# 调试模式：原样打印每个 SSE 事件 JSON
balacli ask "..." --json

# 保留思考块（默认会自动剥离 <think>...</think>）
balacli ask "..." --show-think

参数：

| 选项 | 说明 | |---|---| | --kb <ids> | dataset_ids，逗号分隔；不传则纯对话 | | --session <id> | 会话 ID，缺省随机 UUID | | --user <id> | 用户标识，缺省读取配置文件中的 userId | | --json | 输出原始 SSE 事件 | | --show-think | 不剥离 <think> 思考块 | | --debug | 打印实际发送的 URL / Headers / Body 到 stderr |

按 Ctrl-C 中断。

文件上传

# 通过知识库名称上传（自动查找对应 ID）
balacli upload --kb "产品研究知识库" ./report.pdf ./notes.md

# 通过知识库 ID 上传
balacli upload --kb a6733f55-b0e3-5ef9-a7e4-8de6cf5b343c ./a.pdf ./b.docx

# 切换 VLM loader 模型
balacli upload --kb "研发文档" --vlm qwen-vl-max ./scan.pdf

# 关闭后台处理（默认开启，关闭后接口会同步等待）
balacli upload --kb "周报" --no-background ./small.txt

# 上传后轮询等待后端处理（add/cognify）完成
balacli upload --kb "周报" --wait ./report.pdf

# 自定义等待超时（秒），默认 600
balacli upload --kb "周报" --wait --wait-timeout 1200 ./big.pdf

# 上传到指定文件夹（folder_id 可用 `balacli kb folders <kb>` 获取）
balacli upload --kb "周报" --folder <folderId> ./report.pdf

参数：

| 选项 | 说明 | 默认 | |---|---|---| | --kb <nameOrId> | 目标知识库（必填，支持名称或 ID） | — | | --vlm <model> | dke_loader 的 vlm_model | qwen3-vl-flash | | --folder <id> | 目标文件夹 folder_id | （根目录） | | --no-background | 关闭 runInBackground | （默认开启） | | --wait | 注册后轮询 /v1/datasets/status 直至处理完成或失败 | （默认关闭） | | --wait-timeout <sec> | --wait 的轮询超时秒数 | 600 |

名称解析规则：如果 --kb 的值是 UUID 格式则直接使用；否则按名称精确匹配（不区分大小写）。存在多个同名时会报错并列出 ID 供选择。

上传限制（本地预校验，不合规文件自动跳过）：

| 限制项 | 值 | |---|---| | 单批文件数 | ≤ 1000 | | 视频文件 | ≤ 5GB | | 文档文件 | ≤ 100MB | | 图片文件 | ≤ 10MB | | 其他文件 | ≤ 500MB | | 支持格式 | 文本、文档、演示、表格、网页、图片、音频、视频、邮件、压缩包（130+ 种扩展名） |

输出示例：

正在查找名为「产品研究知识库」的知识库...
已找到: 产品研究知识库 → a6733f55-b0e3-5ef9-a7e4-8de6cf5b343c
[1/3] 正在获取 OSS 上传凭证...
[2/3] 上传到 OSS bucket=xxx
(1/1) report.pdf 100%
[3/3] 注册到知识库 datasetId=a6733f55-...

=== 上传结果 ===
[OK]        report.pdf  (oss://xxx/knowledge_engine_daily/data/<user>/report_4f2a9c1b8e3d.pdf)

共 1 个文件，重复 0 个；runInBackground=true（后端处理可能仍在进行中）

URL 导入

将在线文档 URL 直接导入知识库（无需先下载再上传），选项与 upload 一致。

# 导入单个在线文档
balacli import "https://url" --kb "我的知识库"

# 导入多个 URL
balacli import "https://url1" "https://url2" --kb <datasetId>

# 导入到指定文件夹，并等待后端处理完成
balacli import "https://url" --kb <datasetId> --folder <folderId> --wait

参数：

| 选项 | 说明 | 默认 | |---|---|---| | --kb <nameOrId> | 目标知识库（必填，支持名称或 ID） | — | | --vlm <model> | dke_loader 的 vlm_model | qwen3-vl-flash | | --folder <id> | 目标文件夹 folder_id | （根目录） | | --no-background | 关闭 runInBackground | （默认开启） | | --wait | 注册后轮询直至处理完成或失败 | （默认关闭） | | --wait-timeout <sec> | --wait 的轮询超时秒数 | 600 |

首次导入可能需授权：若目标文档平台尚未授权，命令会返回需要在浏览器打开的授权链接；完成授权后重新执行即可。权限不足时会提示具体原因。

知识库管理

# 列出所有可访问的知识库（个人 + 团队）
balacli kb list

# 仅查看团队知识库
balacli kb list --scope team

# 仅查看个人知识库
balacli kb list --scope personal

# 按类型过滤
balacli kb list --kind FILE

# 分页
balacli kb list --offset 0 --limit 20

# 输出原始 JSON（便于脚本处理）
balacli kb list --json

参数：

| 选项 | 说明 | 默认 | |---|---|---| | --offset <n> | 分页偏移量 | — | | --limit <n> | 每页数量 | — | | --kind <type> | 类型过滤：FILE / DATABASE / KV | — | | --scope <scope> | 范围过滤：personal / team / all | all | | --json | 输出原始 JSON | — |

知识库搜索

# 搜索指定知识库
balacli kb search "如何部署前端" --kb <datasetId>

# 搜索多个知识库
balacli kb search "最佳实践" --kb id1,id2

# 使用 BM25 搜索、返回 Top 5
balacli kb search "关键词" --kb <id> --search-type BM25 --top-k 5

参数：

| 选项 | 说明 | 默认 | |---|---|---| | --kb <ids> | 要搜索的知识库 ID（必填，多个逗号分隔） | — | | --search-type <type> | 搜索类型 | GRAPH_COMPLETION | | --top-k <n> | 返回结果数量 | 10 | | --json | 输出原始 JSON | — |

⚠️ 与其他命令不同，kb search 仅支持知识库 ID，不支持名称。若传入非 UUID 值会提前报错，请先用 balacli kb list 获取 ID。

知识库处理进度

# 查看全部正在处理（add / cognify）的知识库
balacli kb status

# 仅查看指定知识库（支持名称或 ID）
balacli kb status --kb "产品研究知识库"

# 输出归一化后的 JSON
balacli kb status --kb <datasetId> --json

输出示例：

共 2 个数据集状态：

数据集 ID                              名称                     状态/进度
─────────────────────────────────────────────
a1b2c3d4-...                           产品研究知识库           COMPLETED 100% (3/3)
e5f6a7b8-...                           balacli-smoke-kb         PROCESSING 40% (2/5)

参数：

| 选项 | 说明 | |---|---| | --kb <nameOrId> | 仅查看指定知识库（名称或 ID） | | --json | 输出原始 JSON |

对应后端 GET /v1/datasets/status?detail=true，输出包含「数据集 ID / 名称 / 状态进度」三列，状态形如 COMPLETED 100% (3/3)。名称额外从 /v1/datasets/accessible 拉取并按 ID 匹配（拿不到时显示 -）。知识库无处理任务时不会出现在列表中。

知识库创建 / 重命名 / 删除

# 创建个人知识库
balacli kb create "我的知识库"

# 带描述，并归属团队
balacli kb create "团队知识库" --desc "产品文档" --tenant <tenantId>

# 重命名（支持名称或 ID）
balacli kb rename "旧名称" "新名称"

# 删除（不可逆，会交互确认；-y 跳过确认）
balacli kb delete "待删知识库"
balacli kb delete <datasetId> -y

参数：

| 命令 | 选项 | 说明 | |---|---|---| | kb create <name> | --desc <text> | 知识库描述 | | | --tenant <id> | 所属团队 tenant_id（缺省创建个人知识库） | | | --json | 输出原始 JSON | | kb rename <kb> <newName> | — | 重命名 | | kb delete <kb> | -y, --yes | 跳过删除确认（非交互环境必须显式传） |

知识图谱构建（cognify）

# 触发单个知识库图谱构建（默认后台）
balacli kb cognify "产品研究知识库"

# 多个知识库一次触发
balacli kb cognify id1,id2

# 增量加载
balacli kb cognify <datasetId> --incremental

# 关闭后台处理（接口同步等待）
balacli kb cognify <datasetId> --no-background

参数：

| 选项 | 说明 | 默认 | |---|---|---| | --no-background | 关闭 runInBackground | （默认开启） | | --incremental | 增量加载 | — |

后台模式下可用 balacli kb status --kb <id> 跟进构建进度。

文件夹树

# 列出知识库的文件夹层级（拿 folder_id 用于上传）
balacli kb folders "产品研究知识库"
balacli kb folders <datasetId> --json

输出行末的 ID 即 folder_id，可用于 balacli upload --folder <id>。

创建文件夹

# 在知识库根目录创建文件夹（支持名称或 ID）
balacli kb folder-create "产品研究知识库" "季度报告"

# 在指定父文件夹下创建子文件夹
balacli kb folder-create <datasetId> "2026Q1" --parent <parentFolderId>

# 输出原始 JSON
balacli kb folder-create <datasetId> "归档" --json

参数：

| 选项 | 说明 | 默认 | |---|---|---| | --parent <folderId> | 父文件夹 folder_id | （根目录） | | --json | 输出原始 JSON | — |

创建成功后会返回新文件夹 ID，可直接用于 balacli upload --folder <id>。父文件夹 ID 可用 balacli kb folders <kb> 查看。

Agent 列表

# 列出所有可用 Agent
balacli agent list

# 输出原始 JSON
balacli agent list --json

文档列表

# 列出知识库根目录下的文件夹与文档（支持名称或 ID）
balacli doc list "产品研究知识库"

# 仅列出文档条目（隐藏文件夹），方便拿 dataId
balacli doc list <kbId> --data-only

# 进入指定文件夹
balacli doc list <kbId> --folder <folderId>

# 关键字过滤 + 分页
balacli doc list <kbId> --keyword 周报 --offset 0 --limit 20

# 输出原始 JSON
balacli doc list <kbId> --json

参数：

| 选项 | 说明 | 默认 | |---|---|---| | --offset <n> | 分页偏移量 | 0 | | --limit <n> | 每页数量 | 50 | | --keyword <kw> | 按名称关键字过滤 | — | | --folder <id> | 进入指定文件夹（folder_id） | （根目录） | | --data-only | 仅显示文档条目，隐藏文件夹 | — | | --json | 输出原始 JSON | — |

输出中 📄 DOC 行的 ID 即 dataId，可直接用于 balacli doc get <kbId> <dataId>。

文档原文获取

# 获取某知识库中某文档的解析后原文
balacli doc get <kbId> <dataId>

# 输出到文件
balacli doc get <kbId> <dataId> -o ./output.txt

# JSON 格式化输出
balacli doc get <kbId> <dataId> --json

参数：

| 选项 | 说明 | |---|---| | -o, --output <path> | 保存到文件而非 stdout | | --json | 格式化 JSON 输出 |

文档删除

# 删除知识库中的单个文档（不可逆，会交互确认）
balacli doc delete "产品研究知识库" <dataId>

# 跳过确认
balacli doc delete <kbId> <dataId> -y

参数：

| 选项 | 说明 | |---|---| | -y, --yes | 跳过删除确认（非交互环境必须显式传） |

dataId 可通过 balacli doc list <kbId> 获取。

仓库文档生成（repowiki）

从代码仓库生成并增量更新三套文档：人类 Wiki（架构总览 + 模块文档 + HTML 单页）、AI Agent 上下文（AGENTS.md / llms.txt / llms-full.txt）、产品文档（PRD / 使用手册），输出到 <repo>/balawiki/。

其中 AGENTS.md 生成在 balawiki/agent/ 下，内容中声明“理解本工程时读取 balawiki/agent/ 目录作为参考”；仓库根目录的 AGENTS.md 仅写入该声明（不复制完整内容）——不存在则创建；已存在则以标记区块（<!-- BEGIN/END balawiki:AGENTS -->）合并进去：区块内重复生成时原位替换，区块外的手写内容保留。配置 shareAgentsMd: false 可关闭共享（不再插入根目录，并自动清理此前插入的区块）。

# 1. （可选）在目标仓库根目录生成配置 balawiki.config.json（LLM 未配置时会提示补写）
balacli repowiki init [repo]

# 2. 生成 / 增量更新文档（在仓库根目录运行；未初始化时自动生成配置）
balacli repowiki generate

# 只看差异不调 LLM / 忽略缓存全量重生成
balacli repowiki generate --dry-run
balacli repowiki generate --force

# 检查文档漂移（有漂移退出码 1，可作 CI 门禁）
balacli repowiki status

# 只重新生成产品文档（复用已有模块摘要，仅 2 次 LLM 调用）
balacli repowiki product

# 不调 LLM，从已有文档重建 llms.txt / llms-full.txt / HTML 单页
balacli repowiki render

配置分两层：

| 配置 | 位置 | 内容 | |---|---|---| | 仓库配置 | <repo>/balawiki.config.json（随仓库提交） | projectName / description（项目用途描述，注入提示词并以 > 项目描述：… 插入产出文档，便于知识库检索）/ prompt（自定义附加提示词，拼入全部 LLM 调用；变更会触发全部文档重建）/ moduleRoots / moduleDepth / include / exclude / maxModuleChars / shareAgentsMd（是否将声明插入根目录 AGENTS.md，默认 true）/ kbId（bala 知识库 ID，上传预留）/ uploadDocs（待上传文档，相对 outDir，默认 ["product"]）；repo（默认配置所在目录）与 outDir（默认 ./balawiki）可省略 | | LLM 配置 | ~/.balacli/config.json 的 llm 段（或 BALA_LLM_* 环境变量） | baseUrl / apiKey / model / protocol / maxTokens / temperature |

• LLM 配置在 balacli init 中为可选项；repowiki init / generate / product 运行时检测到缺失会交互式提示补写。
• 支持 OpenAI 兼容端点与 Anthropic Messages 网关（baseUrl 含 "anthropic" 时自动识别，也可显式指定 protocol）；baseUrl 填 mock 可不调远端验证流水线。
• 增量状态存于 <outDir>/.repowiki/state.json：模块文档按模块内容哈希只重生成变更模块；衍生文档（总览 / AGENTS.md / 产品文档）按输入哈希增量重建，模块摘要等输入未变时跳过对应 LLM 调用，--force 可强制全量重建。

开发说明

环境要求

• Node.js ≥ 18（依赖原生 fetch / FormData / Web Streams）

构建

cd cli                  # workspaces 根
npm install
npm run build:public    # 产物：packages/public/dist/index.js（带 shebang）
npm run dev:public      # watch 模式
npm run typecheck       # 全 workspace 类型检查

npm publish 时会自动执行 build 与产物审计（通过 prepublishOnly 钩子），无需手动构建。

目录结构

cli/
├── packages/core/src/        # 通用能力（内部包，不发布，构建时内联进产物）
│   ├── commands/             # ask / upload / import / init / kb / agent / doc / repowiki
│   ├── lib/                  # 终端 UI、SSE 解析、OSS 直传、交互确认、repowiki 流水线
│   ├── config.ts             # 配置优先级管理
│   ├── edition.ts            # 版本形态（EditionProfile）定义与注入
│   ├── http.ts               # 鉴权头、Agent ID 管理
│   └── register.ts           # 全部命令注册
└── packages/public/src/      # 本包
    ├── profile.ts            # 公网版形态：无内置站点、严格 TLS
    └── index.ts              # 入口：setEdition + registerCore

内部机制

• 版本号：CalVer YYYY.MMDD.N（semver 合法、单调递增），通过 tsup define 在构建时注入为 __PKG_VERSION__ 常量并直接作为 --version 输出（无展示形态映射），产物中不会打包整个 package.json。
• Agent ID：无需手动配置，CLI 启动时调用 /api/v1/activity/agents 自动拉取首个可用 Agent，并作为 X-Agent-Id 请求头发送。
• TLS 证书校验：保持 Node 默认的严格校验，不做任何降级。
• 知识库名称解析：--kb 支持传入名称，CLI 调用 GET /v1/datasets/accessible 按名称精确匹配后返回 ID，覆盖个人和团队知识库。
• 上传预校验：上传前本地校验文件扩展名白名单、大小限制、空文件检测，不合规文件跳过并报告，合规文件继续上传。

冒烟测试

手动验证脚本位于 workspaces 根 test/manual-smoke.sh，按分组逐段执行：

cd cli
npm run build:public
EDITION=public ./test/manual-smoke.sh repowiki   # 全离线（mock LLM），可随时跑
EDITION=public ./test/manual-smoke.sh edition    # 全离线，校验版本形态边界
EDITION=public ./test/manual-smoke.sh readonly   # 需要可用服务端与 BALA_API_BASE

分组：readonly / create / upload / cognify / import / repowiki / edition / rename / delete / all / help。

关键变量可用环境变量覆盖（未提供依赖资源时对应用例会自动跳过）：

| 变量 | 用途 | 默认 | |---|---|---| | EDITION | 测试的版本形态 | internal（测本包需显式设为 public） | | BALACLI | 运行的 CLI 命令 | node packages/$EDITION/dist/index.js | | KB | 只读用例使用的已有知识库 | 产品研究知识库 | | TMP_KB | create/rename/delete 使用的临时知识库名 | balacli-smoke-kb | | DATA_ID | doc delete 需要（来自 doc list） | — | | FOLDER_ID | upload --folder 需要（来自 kb folders） | — | | IMPORT_URL | import 需要的在线文档 URL | — | | UPLOAD_FILE | 上传文件；留空则自动生成临时文件 | — |

脚本不使用 set -e，单条失败不会中断，便于逐条观察输出与退出码；破坏性用例需显式指定 delete 分组。