跳到正文
AskTable

文档反馈

当前页面CLI/integrations/cli

0 / 5,000

反馈将发送给维护团队。

前往控制台
前往控制台

配置与管理

在终端和脚本里使用 CLI

以个人或系统集成身份问数,在权限范围内维护 AskTable 资源。

AskTable CLI 是官方命令行工具,npm 包名为 @datamini/asktable-cli,命令名为 asktable。它适合终端问数、脚本和外部 AI 助手;业务人员也可以直接在网页里对话。

本页以 CLI 0.0.10 为命令基线,并与服务端 v4.2.48-1026 核对。CLI 与服务端独立发布;命令存在不代表它适用于每个服务端版本,定时任务和嵌入配置的已知限制见下文。

开始前

  • 环境:Node.js 18 或更高版本。
  • 凭证:在主导航「Agent 集成」创建 Key。个人使用或让外部 Agent 以本人身份操作,选择「个人 Key」;可信业务系统选择「系统集成 Key」,该入口只向项目负责人和管理员开放。
  • 连接信息:同一页面可复制服务地址和当前项目 ID;Key 在创建后只完整展示一次。
  • 先确认准备调用的智能体,以及它所连接的数据源和你的数据权限。

操作步骤

安装并核对版本

需要复现本页命令时安装指定版本:

npm install --global @datamini/asktable-cli@0.0.10
asktable --version
asktable --help

按任务继续查看子命令帮助,例如 asktable data-agent --help、asktable query --help。升级 CLI 后重新检查帮助和内置 Skill。

登录并确认服务端身份

交互式登录依次询问 API Key 和 Server URL,验证成功后保存到 ~/.config/asktable/config.json,键名为 api_key 和 api_url:

asktable auth login
asktable auth status
asktable auth whoami --json

auth status 展示本地连接配置,不能证明凭证仍有效。auth whoami 请求服务端,返回当前项目 project_id、用户 user_id、项目角色 project_role 和 API 角色 ak_role 等信息。核对项目后再操作;不要回显 Key。

身份如何判断配置权限
个人 Key有 user_id,代表当前项目中的本人MEMBER 可创建和管理自己的智能体、技能和定时任务;OWNER / ADMIN 可治理项目配置。不能仅凭 ak_role=asker 判断个人 Key 不能配置
系统集成 admin Key没有用户身份,API 角色为 admin用于数据源、元数据、角色、策略等项目基础设施及 Agent 调用;不能读取或修改个人智能体、技能、业务文档、渠道凭据和定时任务配置
系统集成 asker Key没有用户身份,API 角色为 asker适合调用已有 Agent 问数;不能管理个人配置

asktable auth logout 清除本地配置文件;环境变量中仍有 Key 时,后续命令仍会使用它。

在脚本里注入凭证

在 CI 或脚本的运行环境中设置:

export ASKTABLE_API_KEY='YOUR_API_KEY'
export ASKTABLE_API_URL='https://<你的 AskTable 站点>'
asktable auth whoami --json

此时不需要运行交互式登录。实际凭证应从运行环境的密钥管理注入,避免留在命令历史或代码仓库中。

普通 API 命令的取值优先级为:全局参数 --api-key / --server → 环境变量 ASKTABLE_API_KEY / ASKTABLE_API_URL → 本地配置文件 → 默认服务 https://api.asktable.com。私有部署必须明确设置服务地址。

选择可用 Agent,发起第一次提问

先查看使用摘要:

asktable data-agent list --json
asktable data-agent usage <agent_id> --json

摘要中的 can_manage 表示能否管理配置。可以使用 Agent 不等于可以读取它的完整配置;data-agent get <agent_id> 另行检查配置权限。

新建问数会话必须指定 --data-agent:

asktable query "本月销售额是多少?" \
  --data-agent <agent_id> \
  --json

数据范围来自 Agent 和当前数据权限的交集。--datasources 不能替代 Agent,也不能扩大 Agent 的数据范围。个人 Key 使用成员当前绑定的数据角色,不能用 --role / --role-variable 覆盖。

系统集成 Key 可由可信后端指定数据角色和角色变量,变量可重复传入:

asktable query "本月销售额是多少?" \
  --data-agent <agent_id> \
  --role <role_id> \
  --role-variable dept_id=D001 \
  --json

query 创建会话、发送问题并轮询结果。它每隔 1 秒轮询一次,最多 120 次;达到上限会报告对话 ID 和 120s 超时。超时后先查看原对话,不要立即重复提交同一问题。

处理澄清并在原会话追问

JSON 输出包含 conversation_id、status 和 assistant 回复。用同一 ID 继续:

asktable query "按自然月、支付时间统计" \
  --conversation <conversation_id> \
  --json
asktable conv get <conversation_id> --json

clarifying 表示 Agent 在等待补充信息,带原会话 ID 回答即可;warning、error 或 paused 需要查看详情,不能当作正常完成。

复用会话时,query 的 --data-agent、--datasources、--role 等创建参数不会重新应用。旧的无 Agent 会话不能通过当前公共消息接口继续问数,应选择 Agent 新建会话。

按权限维护资源

修改前读取现有配置,完成后用对应 get 命令回读。常用命令如下:

目标命令
查看数据源asktable ds list、asktable ds get <id>
建、改、删数据源asktable ds create、asktable ds update <id>、asktable ds delete <id>
测试待接入的连接asktable ds test-connection --engine <engine> --config '<连接配置 JSON>',不接受数据源 ID
上传文件asktable ds upload <id> <file>;也可用 ds create --file <file> 创建后上传
查看、预览、同步元数据asktable ds meta get <id>、preview <id>、sync <id>
导出、导入元数据asktable ds meta export <id>、asktable ds meta import <id> <file>
改字段说明、可见性和值索引asktable ds field edit <id>,结合 --schema、--table、--field 和相应选项
改表描述asktable ds table edit <id> --schema <schema> --table <table> --desc <text>
管理训练问答对asktable ds training list/create/update/delete,按帮助提供数据源及样例 ID
管理智能体asktable data-agent list/usage/get/create/update/delete
管理业务文档asktable data-agent document list/get/create/update/delete,第一个位置参数为 Agent ID
管理技能asktable skill list/get/create/update/delete
管理角色与策略asktable role list/get/create/update/delete、asktable policy list/get/create/update/delete
管理对话asktable conv list/get/update/delete;列表支持 --query、--status、--created-by-me、--sort
压缩、取消、查看结果数据asktable conv compact <id>、cancel <id>、artifacts <id>
查看、创建、撤销对话分享asktable conv share get/create/delete <id>;创建分享前确认可公开访问的数据范围
查看模型组、项目信息asktable model-group list、asktable project get/update

新建智能体默认私有;CLI 0.0.10 没有智能体分享设置命令,需要在网页里分享。不要把对话分享与智能体分享混为一谈。

配置智能体时,可用 --domain-knowledge 和 --analysis-preferences 分别设置领域知识和分析偏好,各限 1024 字符。能力开关为 --python、--chart、--clarification、--web-search,都明确传 true 或 false;更新时 CLI 会读取当前配置,保留未指定的开关。旧的 --memory-enabled 不再提供。

绑定数据源或技能时,--datasources、--skills 替换整个列表,不能当作追加。业务文档的 --desc 必填;长正文可以使用 --content-file,它优先于 --content:

asktable data-agent document create <agent_id> \
  --title "销售额统计规范" \
  --desc "销售额计算、时间归属与退款处理" \
  --content-file ./sales-rules.md \
  --json

数据源创建或同步的 --wait 结束后,仍需回读 sync_status 和错误信息;等待结束不等于同步成功。训练样例使用 --question、--sql 和可选 --active true|false,不再提供训练样例的 --role 参数。技能模板与项目内技能是不同资源;skill list 不返回内置标记。

给外部 AI 助手安装使用说明

get-skill 将当前 CLI 随包内置的使用说明打印到标准输出,不会自动安装或更新外部助手的 Skill:

asktable get-skill > asktable-skill.md

按所用助手的规则将文件装入 Skill 目录。更新 CLI 后重新导出并更新已安装副本;只升级包不会改动已保存的说明文件。主导航「Agent 集成」也提供安装 AskTable Skill 的引导。

这份说明帮助外部助手确认身份、澄清业务口径、把知识放到合适位置并验证结果。它与 AskTable 智能体上的技能不同;领域知识、业务文档和可复用分析方法应分别保存到 AskTable 的对应配置中。

内置说明还包含 Bug 和需求反馈指引。只有用户明确要求提交时才执行;Linear 连接或凭证独立于 AskTable Key,未配置时只能保留草稿,不能宣称已提交。

当前兼容限制

CLI 0.0.10 保留 data-agent schedule 和 data-agent embed 命令组,但与服务端 v4.2.48-1026 的管理接口路径不匹配:

功能CLI 0.0.10 使用的路径当前服务端管理路径当前操作方式
定时任务/v1/data-agents/{agent_id}/schedules/v1/schedules使用网页定时任务
嵌入配置/v1/data-agents/{agent_id}/embeds/v1/embeds使用网页嵌入设置

这两个命令组在当前服务端出现 404 时,不应反复更换资源 ID 或凭证。CLI 0.0.10 尚无对应的顶级 schedule、embed 命令;不要依据网页已有功能推断 CLI 已经支持。

CLI 还移除了旧的 ats、glossary 和 project preference 命令。已有脚本应重新核对 --help;服务端升级也可能改变权限与资源边界,不能只更新 CLI 后沿用旧的 admin/asker 假设。

关键约束

项目值或默认在哪里改
Node.js 版本18 或更高本地环境
本页命令基线CLI 0.0.10;与服务端 v4.2.48-1026 核对两条版本线独立核对
配置文件~/.config/asktable/config.jsonauth login / auth logout
配置优先级全局参数 > 环境变量 > 配置文件 > 默认服务--api-key / --server 或环境变量
默认服务https://api.asktable.com--server 或 ASKTABLE_API_URL
新建问数必须指定 Agent,受当前身份与数据权限约束query --data-agent <id>
查询等待间隔 1 秒、最多轮询 120 次无等待上限选项
JSON 输出使用 --json;部分写命令仍含提示行,不能假定整个 stdout 是单个 JSON自动化应检查具体命令并回读结果
删除默认交互确认;已确认要删除时可用 --yes删除命令参数
系统集成 Keyadmin 也不获得个人配置管理权「Agent 集成」及资源授权

出问题怎么判断

现象判定条件处理
提示未配置 API Key当前命令未取得凭证运行 auth login,或注入 ASKTABLE_API_KEY
本地显示已登录,但调用失败auth status 有配置,auth whoami 失败核对服务地址、Key 是否撤销或过期,以及项目成员状态
返回 401认证失败检查 Key、服务地址与有效期,不反复尝试修改资源
返回 403,或可用 Agent 无法读取完整配置使用权与配置权不同,或使用了系统集成 Key查看 auth whoami 与使用摘要中的 can_manage;按个人身份及资源权限操作
返回 404资源、访问范围或接口路径不匹配先核对版本、命令与可见资源;定时任务和嵌入先看上方兼容限制
返回 422 或参数错误服务端拒绝请求参数按具体错误检查必填项;新建问数必须提供 --data-agent
返回 clarifyingAgent 需要补充业务信息带原 conversation_id 回答澄清问题
查询报告 120s 超时达到轮询上限用 conv get <conversation_id> 检查原对话,再决定后续操作
返回 warning、error 或 paused本轮未正常完成查看对话详情及已有错误,不将其当作成功答案
同步等待结束但数据不可用sync_status 不是成功状态,或有同步错误回读数据源详情;处理具体错误后再同步
私有部署请求发到云端生效服务地址仍是默认值设置 ASKTABLE_API_URL 或全局 --server,再用 auth whoami 核对项目

下一步