配置与管理
在终端和脚本里使用 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 --jsonauth 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 \
--jsonquery 创建会话、发送问题并轮询结果。它每隔 1 秒轮询一次,最多 120 次;达到上限会报告对话 ID 和 120s 超时。超时后先查看原对话,不要立即重复提交同一问题。
处理澄清并在原会话追问
JSON 输出包含 conversation_id、status 和 assistant 回复。用同一 ID 继续:
asktable query "按自然月、支付时间统计" \
--conversation <conversation_id> \
--json
asktable conv get <conversation_id> --jsonclarifying 表示 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.json | auth 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 | 删除命令参数 |
| 系统集成 Key | admin 也不获得个人配置管理权 | 「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 |
返回 clarifying | Agent 需要补充业务信息 | 带原 conversation_id 回答澄清问题 |
| 查询报告 120s 超时 | 达到轮询上限 | 用 conv get <conversation_id> 检查原对话,再决定后续操作 |
返回 warning、error 或 paused | 本轮未正常完成 | 查看对话详情及已有错误,不将其当作成功答案 |
| 同步等待结束但数据不可用 | sync_status 不是成功状态,或有同步错误 | 回读数据源详情;处理具体错误后再同步 |
| 私有部署请求发到云端 | 生效服务地址仍是默认值 | 设置 ASKTABLE_API_URL 或全局 --server,再用 auth whoami 核对项目 |