cube-configure-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configure the Cube agent

配置Cube Agent

Mostly know-how rather than commands. Two CLI calls read the current state; everything else is writing markdown into the data model, which means the dev-mode workflow from

cube-build-model

applies.

这部分主要是实操经验而非命令。有两个CLI命令用于读取当前状态；其余操作均为在数据模型中编写Markdown，这意味着需要遵循

cube-build-model

的开发模式工作流。

Preflight

预检查

bash

command -v cube >/dev/null || echo "Cube CLI not installed: curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh"
cube whoami || echo "Not authenticated. Interactive: cube login. Headless: set CUBE_API_URL + CUBE_API_KEY."
cube context list

bash

command -v cube >/dev/null || echo "Cube CLI not installed: curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh"
cube whoami || echo "Not authenticated. Interactive: cube login. Headless: set CUBE_API_URL + CUBE_API_KEY."
cube context list

See what's configured

查看当前配置

bash

cube agents list <deployment>
cube agents skills <deployment>
cube agents skills <deployment> --space <space> --branch <branch>

cube agents skills

returns name, title and description — the metadata the agent matches on. It does not return the instructions; read those from the model files below.

bash

cube agents list <deployment>
cube agents skills <deployment>
cube agents skills <deployment> --space <space> --branch <branch>

cube agents skills

会返回名称、标题和描述——即Agent用于匹配的元数据。它不会返回具体指令，需从下方的模型文件中查看。

Agent config lives in the data model

Agent配置存储在数据模型中

Under

agents/

in the project, as markdown:

agents/
  rules/               always-on instructions
  certified_queries/   trusted, named queries
  skills/              named multi-step workflows, run from the / menu

Read and write them with

cube data-model

, on a dev-mode branch:

bash

cube data-model get <deployment> agents/rules/revenue-definitions.md
cube data-model dev-mode <deployment> main
cube data-model put <deployment> agents/skills/weekly-revenue-report.md --file ./skill.md --branch <dev-branch>
cube data-model commit <deployment> -m "Add weekly revenue report skill" --branch <dev-branch>

The filename is the identity.

weekly-revenue-report.md

becomes the skill

weekly-revenue-report

. Because these are project files, they inherit the project's git flow, review and access policies — a rule on a dev branch is testable before it reaches anyone.

位于项目的

agents/

目录下，以Markdown文件形式存在：

agents/
  rules/               始终生效的指令
  certified_queries/   可信的命名查询
  skills/              命名的多步骤工作流，可从/菜单调用

在开发模式分支上，使用

cube data-model

命令读写这些文件：

bash

cube data-model get <deployment> agents/rules/revenue-definitions.md
cube data-model dev-mode <deployment> main
cube data-model put <deployment> agents/skills/weekly-revenue-report.md --file ./skill.md --branch <dev-branch>
cube data-model commit <deployment> -m "Add weekly revenue report skill" --branch <dev-branch>

文件名即为标识。

weekly-revenue-report.md

会成为名为

weekly-revenue-report

的Skill。由于这些是项目文件，它们会继承项目的Git流程、审核和访问策略——开发分支上的规则可先进行测试，再推送给其他用户。

Which one to reach for

选择合适的配置类型

This is the judgement the skill exists to carry.

Use	When
Rule	A fact or constraint that should apply to every answer. "Revenue excludes refunds." "Never show data before 2024." Always in context, so keep them few and short.
Certified query	A specific question with one correct query. Pins the answer so the agent stops re-deriving it.
Skill	A repeatable multi-step workflow a person would otherwise re-type. "Weekly revenue report" — pull, break down, compare, summarize.

The common mistake is writing a rule for something that should be a skill. Rules are always loaded, so every rule is charged to every conversation; a long list of them dilutes all of them. If the instruction only matters when someone asks for a particular thing, it is a skill.

这是该Skill要解决的判断问题。

用途	适用场景
规则	适用于所有回答的事实或约束条件。例如“收入不含退款”、“绝不显示2024年之前的数据”。规则始终处于生效状态，因此应保持数量少且简洁。
认证查询	对应特定问题的唯一正确查询。固定答案，避免Agent重复推导。
Skill	用户原本需要重复输入的可重复多步骤工作流。例如“每周收入报告”——提取、拆分、对比、汇总。

常见错误是将应设为Skill的内容写成规则。规则始终会加载，因此每条规则都会影响所有对话；过多的规则会削弱整体效果。如果指令仅在用户询问特定内容时才需要生效，则应设为Skill。

Writing a good rule

编写优质规则

State the fact, not the behaviour. "Active user means logged in within 28 days" beats "always calculate active users correctly".
One idea per rule. Split compound rules; they are easier to review and to delete when they go stale.
Prefer fixing the model. A rule that explains what a badly named measure means is a workaround — renaming the measure with
```
cube-build-model
```
fixes it for every consumer, not just the agent.

陈述事实，而非行为。例如“活跃用户指28天内登录过的用户”比“始终正确计算活跃用户”更好。
每条规则仅包含一个核心内容。拆分复合规则，这样更便于审核，也便于在规则失效时删除。
优先修复模型。如果规则是为了解释命名不当的度量指标的含义，那只是权宜之计——使用
```
cube-build-model
```
重命名度量指标，可为所有使用者解决问题，而不仅仅是Agent。

Writing a good skill

编写优质Skill

Frontmatter

title

and

description

(both required), markdown body for the instructions. The

description

is what the agent matches free-text requests against, so write it the way a user would ask, not the way you would file it.

Number the steps. Say what the output should look like. If a step depends on a certified query or a specific view, name it.

需要包含必填的Frontmatter

title

和

description

，Markdown正文为具体指令。

description

是Agent匹配用户自由文本请求的依据，因此应按照用户提问的方式撰写，而非文件归档的方式。

对步骤进行编号。说明输出应呈现的样式。如果某一步依赖于认证查询或特定视图，请明确指出。

Diagnosing a bad answer

诊断错误回答

When someone says the agent got something wrong, check in this order:

Is the model right? A wrong measure produces a wrong answer no amount of instruction fixes. Verify with
```
cube-run-query
```
.
Is the field exposed? If it is not in a view, the agent cannot use it.
Is there a conflicting rule? Read every rule, not just the relevant one. Contradictory rules are common and the symptom is inconsistency.
Only then add a rule or certified query.

Skipping to step 4 is how deployments end up with thirty rules that paper over four model problems.

当用户反馈Agent回答错误时，请按以下顺序排查：

模型是否正确？ 错误的度量指标会导致错误的回答，再多的指令也无法修正。使用
```
cube-run-query
```
验证。
字段是否已暴露？ 如果字段不在视图中，Agent无法使用它。
是否存在冲突规则？ 查看所有规则，而不仅仅是相关规则。矛盾的规则很常见，症状是回答不一致。
最后再添加规则或认证查询。

直接跳到步骤4会导致部署环境中出现30条规则，却只是掩盖了4个模型问题。

When something fails

故障排查

Symptom	Cause
Skill does not appear	Not on the branch the chat is using, or the branch has not been built
Write rejected	Not on a dev-mode branch — see `cube-build-model`
`cube agents skills` returns nothing	No skills authored, or the wrong `--space` / `--branch`

症状	原因
Skill未显示	不在聊天使用的分支上，或分支未构建
写入被拒绝	不在开发模式分支上——请查看 `cube-build-model`
`cube agents skills` 未返回任何内容	未创建任何Skill，或 `--space` / `--branch` 参数错误