aixdb-cli

通过个人 API 密钥访问 Aix-DB，支持智能体与业务文档管理、数据源列表、智能体问答、报告及 HTML 报告导出。Node.js >= 18。

本说明对应 0.2.1 源码。npm 安装需等待该版本发布；版本是否可用以实际安装结果为准。

终端命令名为 aixdb，npm 包名为 aixdb-cli。

安装与本地运行

发布后安装：

npm install -g aixdb-cli@^0.2.1
aixdb --version

国内网络环境可使用 npm 镜像安装：

npm install -g aixdb-cli --registry=https://registry.npmmirror.com
aixdb --version

仓库开发时可直接运行，无需发布或覆盖全局安装：

npm ci --prefix aix-db-cli
node aix-db-cli/bin/aix-db-cli.js --help
node aix-db-cli/bin/aix-db-cli.js get-skill

以下示例使用已安装的 aixdb；从源码运行时，将其替换为 node aix-db-cli/bin/aix-db-cli.js。

配置 API 密钥

在 Aix-DB「个人中心 → API 密钥」创建密钥。新建密钥可在列表中重复复制；权限与当前账号一致，过期、撤销、账号停用或修改登录密码后将无法使用。

# 在终端隐藏输入密钥；验证成功后才保存配置
aixdb auth login --server http://localhost:18080

# 本地配置状态，不进行网络验证
aixdb auth status

# 验证当前凭证与服务是否可用
aixdb auth status --check --json

服务地址使用带 /sanic 代理的统一入口。本地 make dev 默认入口为 http://localhost:18080（Vite），后端内部端口为 8089。支持反向代理子路径，例如 https://example.com/aix；末尾 /sanic 会自动规范化。CLI 不自动跟随重定向，请直接使用最终服务地址。

Agent、CI 和脚本

运行环境设置 AIX_DB_API_URL 和 AIX_DB_API_KEY 后，可以直接查询，无需登录或将密钥保存到本地文件。密钥应通过运行环境的密钥管理方式提供，不写入源码。

export AIX_DB_API_URL=http://localhost:18080
# AIX_DB_API_KEY 已由运行环境注入
aixdb auth status --check --json
aixdb datasources --json

# 如确实需要持久化已注入的密钥，支持标准输入
printf '%s' "$AIX_DB_API_KEY" | aixdb auth login --api-key-stdin

配置优先级：

| 配置 | 最高优先级 | 环境变量 | 本地文件 | 默认值 | | --- | --- | --- | --- | --- | | 密钥 | --api-key / 登录时 --api-key-stdin | AIX_DB_API_KEY | apiKey | 未配置 | | 服务地址 | --server（登录兼容 --url） | AIX_DB_API_URL | baseUrl | http://localhost:18080 |

--api-key 可用于兼容已有脚本，但参数可能进入命令历史和进程列表，优先使用环境变量、stdin 或隐藏输入。

本地配置默认为 ~/.config/aix-db-cli/config.json，可用 AIX_DB_CLI_CONFIG_PATH 覆盖。文件按 0600 权限原子保存，含密钥原文；服务端保存鉴权摘要和加密密文，本地保存原文，请勿提交到 Git。Windows 的实际文件访问权限取决于系统 ACL。

# 仅删除本地配置，不撤销服务端密钥
aixdb auth logout

退出后环境变量仍然生效；若需要停止应用访问，请在个人中心撤销密钥。

快捷操作

aixdb agent list
aixdb skill list
aixdb conv list
aixdb ds use "销售库"
aixdb query "本月销售额是多少"
aixdb query "分析销售变化" --data-agent "销售助手"
aixdb report "生成销售分析报告" -o ./report.html

列表默认以文字展示，使用 --json 保留完整结构。问答数据源和智能体支持精确名称，重名时提示候选 ID；管理操作仍使用 ID。ds use 按服务地址保存默认数据源，显式指定优先，智能体自身绑定和续接原绑定不被默认值覆盖。停用的个人智能体仍可由所有者查看和重新启用，停用期间不可执行问答。

数据查询

aixdb datasources
aixdb datasources --type mysql --name 销售 --json

aixdb chat "有哪些数据表？" --datasource 48
aixdb chat "查询销售额趋势" --datasource 48 --stream
aixdb chat "分析各区域销售情况" --datasource 48 --json
aixdb report "生成销售分析报告" --datasource 48 --timeout 600 -o ./report.html

ds 是 datasources 的别名，query 是 chat 的别名。数据源列表为空或筛选无匹配时返回成功，JSON 模式返回 []。

| chat 选项 | 默认值 | 含义 | | --- | --- | --- | | --datasource <名称或ID> | 使用默认数据源 | 当前账号可访问的数据源，智能体问答优先自身绑定 | | --data-agent <名称或ID> | 未指定 | 使用智能体配置；支持 DATABASE_QA 和 REPORT_QA | | --qa-type <type> | DATABASE_QA | 可选 REPORT_QA、COMMON_QA | | --timeout <seconds> | 180 | 大于 0、不超过 86400 秒 | | --stream | 关闭 | 逐段输出，不可与 --json 或 --output 同用 | | -o, --output <file> | 未指定 | 报告模式保存 HTML 文件，同名文件会覆盖 | | -c, --conversation <id> | 新建对话 | 沿用已有对话的数据源、智能体和问答类型 | | --verbose | 关闭 | 执行步骤写入 stderr | | --json | 关闭 | 单个 JSON 结果写入 stdout |

问答 JSON 包含 conversation_id、question、datasourceId、qaType、answer 和 chartMeta；智能体问答另有 agentId；可追踪任务包含 run_id，报告导出时另有 reportFile。最终 JSON 不包含过程步骤，需查看步骤时使用 --verbose（输出到 stderr）。数据问答保留服务端图表元数据，不生成本地图片，也不返回 chartFile。

未传 -c 时 chat 生成独立会话 ID 并创建问答，支持 -c <conversation_id> 续接已有对话，暂不支持上传文件或交互澄清恢复。需要补充条件时，完善问题后重试；不支持的问答类型会在发送请求前被拒绝。

报告 HTML 输出

report "问题" 等同于 query "问题" --qa-type REPORT_QA，支持相同的问答选项。

报告模式默认向 stdout 输出 HTML 源码，不附加问题标题或会话信息，并移除 REPORT_HTML_START / REPORT_HTML_END 注释。--json 显式启用时仍返回 JSON，answer 为清理后的 HTML。

aixdb report "按商品类目统计商品数量并生成分析报告" --datasource 5
aixdb report "按商品类目统计商品数量并生成分析报告" --datasource 5 --output ./report.html

-o, --output <file> 将报告保存到指定文件（同名文件会覆盖），内嵌项目 ECharts 资源以支持直接打开；保存路径写入 stderr。与 --json 配合时另返回 reportFile。--output 不与 --stream 同用，普通数据问答输出保持不变。

智能体

aixdb agent list
aixdb data-agent binding-options --json
aixdb data-agent create --name "销售助手" --datasources <数据库ID> --skills <技能ID> --json
aixdb data-agent get <智能体ID> --json
aixdb data-agent update <智能体ID> --chart false --json
aixdb data-agent document create <智能体ID> --title "指标口径" --summary "收入定义" --content-file ./metrics.md --json
aixdb query "分析上个月销售情况" --data-agent <智能体ID> --json

agent 是 data-agent 别名。支持模板、绑定资源、运行配置、智能体 CRUD、业务文档 CRUD/重建索引。完整选项见 Skill 命令速查。默认输出易读列表或摘要，--json 输出完整接口结构。

智能体最多绑定一个数据库。更新先读取版本并保留未修改的能力开关/文档字段；409 冲突不自动覆盖。删除要求 --yes。权限完全由服务端按 API 密钥所属账号校验，联网搜索不可启用。

查询使用 --data-agent 时自动解析绑定数据库，并传入 agent_id，让业务知识、分析偏好、绑定 Skill、业务文档及能力开关进入服务端智能体执行链路。数据库/权限/启用状态不满足时明确失败；不会退回普通问答。暂不支持智能体 COMMON_QA、文件上传和交互澄清恢复。

技能与对话

数据库和报告问答使用可追踪任务：创建后通过 SSE 订阅，启动时将会话 ID、运行 ID 写入 stderr，JSON 成功结果包含 run_id。可在另一终端用 conv runs/cancel 查看或取消；需服务端配置 Redis。COMMON_QA 使用原始 SSE，不注册可取消的运行记录。旧服务端若直接返回 SSE 则兼容读取，但不会有运行 ID。

aixdb skill list
aixdb skill create --name "收入分析" --content-file ./income.md --datasources 11 --json
aixdb skill update <技能ID> --description "分析净收入" --json
aixdb skill toggle <技能ID> --enabled false --json

aixdb conv list
aixdb conv get <会话ID> --json
aixdb query "进一步分析变化原因" -c <会话ID> --json
aixdb conv runs <会话ID> --json
aixdb conv cancel <会话ID> --run <运行ID> --json

问答结果新增 conversation_id，续接时沿用历史的数据库、智能体与问答类型，禁止中途切换绑定。历史详情按页返回。skill 管理服务端业务技能，get-skill 输出 CLI 手册，两者独立。

支持技能删除、数据库范围调整和对话历史删除；删除需 --yes。对话历史删除不会停止正在运行的任务。当前没有对话重命名、分享、压缩命令，暂停问答的澄清恢复也未接入。详见 Skill 手册。

在 AI Agent 中使用

aixdb get-skill

该命令无需联网或认证，输出随包分发的 skills/aix-db-cli/SKILL.md。将输出提供给 Agent；若其支持文件式 Skill，可保存为对应技能目录的 SKILL.md。命令本身不自动修改任何 Agent 配置。

Agent 使用手册 按安装、认证、全局参数、命令速查、典型工作流和使用注意事项组织，覆盖当前 CLI 的数据源查询、数据问答、报告及图表能力。命令表与 get-skill 共用同一份文件；网页具备但 CLI 尚未开放的管理功能不会作为可执行命令列出。

错误与测试

成功退出码为 0，失败为 1；错误写入 stderr。401 提示密钥无效/过期/撤销，403 提示权限不足，超时和缺失完成标记的事件流会明确失败，不将部分回答误报为完成。

npm test --prefix aix-db-cli
npm pack ./aix-db-cli --dry-run

测试使用临时配置与本地合成 HTTP 服务，覆盖配置优先级、密钥验证、文件权限、错误退出、问答契约、SSE 分片、图表数据保留和报告导出。它们不代表真实模型问答或 npm 发布验收。