byted-viking-cli

## 目标 把用户的需求转换为可直接执行的`viking-cli`命令并执行，如果覆盖不了则提示用户。 `viking-cli` 在用户安装后位于系统 `PATH` 中，直接执行 `viking-cli`。 ## 触发与决策 - 按用户目标选择产品： - 向量库管理、索引管理、向量数据增删改查、id/关键词检索走 `vikingdb`； - 知识库管理、文档管理、知识库检索、知识服务问答走 `knowledge`； - 记忆库管理、会话记忆写入、用户记忆检索走 `memory`。 - 如果用户没有明确产品 但提到“知识库(Knowledge)/记忆库(Memory)/向量库(VikingDB)”，先根据目标选择最接近的命令分支。 ## 安装 CLI 用户可用一条命令完成安装（免下载脚本）： ```bash curl -fsSL https://viking-skills.tos-cn-beijing.volces.com/viking-cli/install.sh | bash ``` 如需安装到系统目录（可能需要权限）： ```bash curl -fsSL https://viking-skills.tos-cn-beijing.volces.com/viking-cli/install.sh | sudo bash -s -- --prefix /usr/local ``` 安装完成后验证： ```bash viking-cli version ``` ## 工作原则 - 涉及复杂 JSON、中文、嵌套数组时，优先推荐文件输入方式；如果当前命令不支持文件输入，再给命令行 JSON 示例。 - 如果用户没有指定collection，则可省略 `--collection` 的参数，默认使用配置文件中的 collection 。 - 如果用户需求超出当前 CLI 能力边界，要明确说“当前 CLI 未实现该子命令”。 ## 命令树 - `viking-cli version` - `viking-cli auth` - `viking-cli vikingdb` - `setup` - `collection {create|get|list|update|delete}` - `index {create|get|list|update|delete|enable|disable}` - `upsert` - `fetch` - `delete` - `search-by-id` - `search-by-keywords` - `viking-cli memory` - `setup` - `collection {create|get|list|update|delete}` - `add-session` - `search` - `viking-cli knowledge` - `open` - `setup` - `collection {create|get|list|delete}` - `add-doc` - `add-file` - `add-dir` - `get-doc` - `list-docs` - `update-doc` - `delete-doc` - `search-collection` - `search-knowledge` - `list-services` - `service-chat` ## 全局配置 CLI 通过 `viking-cli auth` 交互式写入 `~/.viking/config`，后续命令默认从配置文件读取 AK / SK / Region / Project， 如无特殊情况，命令行无需指定--region和--project参数。 用户执行过对应产品的 `setup`，创建的collection name会写入配置文件，后续很多数据面命令可以不再显式传 `--collection`。 ### 交互式配置（推荐） ```bash viking-cli auth ``` 执行后，根据提示依次输入： - AccessKey (AK) - SecretKey (SK) - Cloud (`volcengine`、`byteplus` 或 `bytecloud`，默认 `volcengine`；) - Region (如 `cn-beijing`) - Project (如 `default`) ### 全局 Flags（命令行参数） 当前实际支持的全局 flags： - `--cloud`：云环境，`volcengine`、`byteplus` 或 `bytecloud` - `--region`：Region（用于推导默认 endpoint） - `--project`：默认 project - `--format`：输出格式，`json` 或 `text` - `--timeout`：请求超时，例如 `120s` ## JSON 输入策略 部分 control plane 命令支持： - `--input-json '<JSON_OBJECT>'` - `--input-file /path/to/payload.json` 这类命令会先用结构化 flags 组装 payload，再 merge `--input-json/--input-file` 的内容。 建议： - 结构简单时，用显式 flags - JSON 结构复杂时，用 `--input-file` - `memory add-session` 复杂内容优先推荐 `--messages-file`；`metadata` 可选，传文件用 `--metadata-file` ## 输出约定 默认输出为格式化 JSON；若用户需要纯文本，使用 `--format text`。 ## 版本与鉴权配置 ```bash viking-cli version viking-cli auth ``` ## VikingDB / Setup 通过本地数据样本自动推断 schema，并一键创建 collection、index，并 upsert 数据 【推荐】。 `vikingdb setup` 支持默认命名（允许不传 `--collection` / `--index`）： - 默认 collection：`viking_cli_{userid}` - 默认 index：`viking_cli_{userid}_index`（即 `<collection>_index`） ```bash viking-cli --region <region> vikingdb setup --collection <collection_name> --index <index_name> --file data.csv --id-field item_id viking-cli --region <region> vikingdb setup --collection <collection_name> --index <index_name> --file data.csv --fields '[{"FieldName":"avatar","FieldType":"image"},{"FieldName":"content","FieldType":"text"}]' viking-cli --region <region> vikingdb setup --collection <collection_name> --index <index_name> --file data.jsonl --vectorize-field content ``` ## VikingDB / Collection 创建： ```bash viking-cli --region <region> vikingdb collection create --name <collection_name> --desc '<description>' --fields-json '<json_array>' --fulltext-json '<json_object>' --tags-json '<json_value>' --vectorize-json '<json_object>' ``` 完整 payload： ```bash viking-cli --region <region> vikingdb collection create --input-file /path/to/create_collection.json ``` 查询： ```bash viking-cli --region <region> vikingdb collection get --name <collection_name> ``` 列表： ```bash viking-cli --region <region> vikingdb collection list --page-number 1 --page-size 10 --filter-json '<json_value>' ``` 更新： ```bash viking-cli --region <region> vikingdb collection update --name <collection_name> --desc '<description>' --fields-json '<json_value>' ``` 删除： ```bash viking-cli --region <region> vikingdb collection delete --name <collection_name> ``` ## VikingDB / Index 创建： ```bash viking-cli --region <region> vikingdb index create --name <index_name> --collection <collection_name> --desc '<description>' --cpu-quota 2 --shard-count 1 --shard-policy '<policy>' --vector-index-json '<json_object>' --scalar-index-json '<json_value>' ``` 查询： ```bash viking-cli --region <region> vikingdb index get --name <index_name> --collection <collection_name> ``` 列表： ```bash viking-cli --region <region> vikingdb index list --page-number 1 --page-size 10 ``` 更新： ```bash viking-cli --region <region> vikingdb index update --name <index_name> --collection <collection_name> --desc '<description>' --cpu-quota 4 --scalar-index-json '<json_value>' ``` 启用 / 禁用： ```bash viking-cli --region <region> vikingdb index enable --name <index_name> --collection <collection_name> viking-cli --region <region> vikingdb index disable --name <index_name> --collection <collection_name> ``` 删除： ```bash viking-cli --region <region> vikingdb index delete --name <index_name> --collection <collection_name> ``` ## VikingDB / Data 导入 / 更新数据： ```bash viking-cli --region <region> vikingdb upsert --collection <collection_name> --file data.csv --id-field id --batch-size 200 viking-cli --region <region> vikingdb upsert --collection <collection_name> --file data.jsonl --batch-size 200 ``` 获取数据： ```bash viking-cli --region <region> vikingdb fetch --collection <collection_name> --ids-json '["id1","id2"]' ``` 删除数据： ```bash viking-cli --region <region> vikingdb delete --collection <collection_name> --ids-json '["id1","id2"]' viking-cli --region <region> vikingdb delete --collection <collection_name> --del-all ``` 相似搜索： ```bash viking-cli --region <region> vikingdb search-by-id --collection <collection_name> --index <index_name> --id '<document_id>' --limit 10 ``` Query或关键词搜索： ```bash viking-cli --region <region> vikingdb search-by-keywords --collection <collection_name> --index <index_name> --query '<search_text>' --limit 10 ``` ## Memory / Setup 与 Collection 一键创建个人记忆库，默认命名为 `viking_cli_{userid}`： ```bash viking-cli --region <region> memory setup viking-cli --region <region> memory setup --name <collection_name> ``` 创建： ```bash viking-cli --region <region> memory collection create --name <collection_name> --desc '<description>' --cpu-quota 2 ``` 列表： ```bash viking-cli --region <region> memory collection list ``` 查询 / 更新： ```bash viking-cli --region <region> memory collection get --name <collection_name> viking-cli --region <region> memory collection update --name <collection_name> --desc '<description>' --cpu-quota 4 ``` 删除： ```bash viking-cli --region <region> memory collection delete --name <collection_name> ``` ## Memory / Session 与搜索 记录会话内容： ```bash viking-cli --region <region> memory add-session --collection <collection_name> --session-id '<session_id>' --messages-file ./messages.json [--metadata-file ./metadata.json] ``` `messages.json` 示例： ```json [ {"role": "user", "content": "我喜欢打篮球"}, {"role": "assistant", "content": "好的，记下了"} ] ``` `metadata.json` 结构（可选，未传时 CLI 会自动生成）： ```json { "default_user_id": "user_id", "default_user_name": "user_name", "default_assistant_id": "assistant_id", "default_assistant_name": "assistant_name" } ``` `filter-json` 结构（可选，未传时 CLI 会自动生成）： ```json { "memory_type": ["sys_event_v1", "sys_profile_v1"], "user_id": "user_id", "assistant_id": "assistant_id" } ``` 记忆搜索: ```bash viking-cli --region <region> memory search --collection <collection_name> --query '打篮球' --filter-json '<json_object>' --limit 10 ``` ## Knowledge / Setup 与 Collection 开通知识库服务（支持 `volcengine` / `byteplus`，幂等：已开通则直接返回当前状态，未开通时执行开通）： ```bash viking-cli --region <region> knowledge open ``` 一键创建个人知识库，默认命名为 `viking_cli_{userid}`。在 `volcengine` / `byteplus` 下，`setup` 会先检查知识库服务是否已开通，未开通时自动开通，再创建 collection： ```bash viking-cli --region <region> knowledge setup viking-cli --region <region> knowledge setup --name <collection_name> ``` 创建： ```bash viking-cli --region <region> knowledge collection create --name <collection_name> --desc '<description>' --version 4 --data-type unstructured_data ``` 列表 / 查询： ```bash viking-cli --region <region> knowledge collection list viking-cli --region <region> knowledge collection get --name <collection_name> ``` 删除： ```bash viking-cli --region <region> knowledge collection delete --name <collection_name> ``` ## Knowledge / 文档与搜索 新增文档（直接传 URI）： ```bash viking-cli --region <region> knowledge add-doc --collection <collection_name> --uri <uri> --doc-id <doc_id> --doc-name '<doc_name>' --doc-type '<doc_type>' --desc '<description>' --tag-list-json '<json_value>' ``` 上传本地文件： ```bash viking-cli --region <region> knowledge add-file --collection <collection_name> --file /path/to/local_file.pdf ``` 上传目录： ```bash viking-cli --region <region> knowledge add-dir --collection <collection_name> --dir /path/to/local_directory ``` 获取 / 列表 / 更新 / 删除文档： ```bash viking-cli --region <region> knowledge get-doc --collection <collection_name> --doc-id <doc_id> viking-cli --region <region> knowledge list-docs --collection <collection_name> --offset 0 --limit 10