Article body
Full article
Language models excel at understanding goals and generating plans, while enterprise systems rely on deterministic interfaces, parameters, and state. A governed execution layer must bridge the two. A CLI suits agent use because commands have clear structures, inputs and outputs can be serialized, and execution fits existing scripts, containers, and audit systems.
Skills Map Business Language to Commands
An agent-oriented CLI should not expose hundreds of isolated commands. Skills organize capabilities around data, permissions, dashboards, and workflows, explaining prerequisites, parameter constraints, and failure handling. The agent selects a business capability before calling a command, which reduces the risk of interpreting “give a user access to a dashboard” as “change the dashboard’s public access.”
Commands also need stable structured output. Successful results return resource IDs, state, and next steps; failures distinguish insufficient permissions, invalid parameters, network timeouts, and business conflicts. The agent can then correct parameters, request authorization, or stop the task. If human-readable logs are the only interface, the model must guess what errors mean.
Dry Run Makes a Write Visible Before It Happens
When an agent prepares to create, change, or delete a resource, Dry Run first calculates the impact. A user can review target objects, permission changes, planned calls, and irreversible risk before deciding whether to proceed. At that stage, the system can also enforce policies such as blocking cross-tenant sharing, limiting bulk exports, or requiring approval in production.
A Dry Run result should include a signature or version identifier. During execution, the platform confirms that the resource has not changed. If someone modifies the target after the preview, the agent generates a new preview instead of overwriting newer content with an outdated plan.
SSE Provides Feedback for Long-Running Tasks
Modeling, batch queries, and workflows may run for tens of seconds or longer. SSE can continuously return the plan, progress, tool results, and errors, so a user can see where a task is blocked. Events should include a task ID, step ID, time, state, and readable explanation. Clients can reconnect and resume from the last received position.
The progress stream also supports audit. A team can reconstruct which parameters an agent used at a step, why it retried, and when a user approved a write. Sensitive fields need redaction before they enter logs, and event content must never include tokens or secrets.
Four Hard Constraints for the Execution Layer
- Every command has an explicit schema; agents cannot concatenate arbitrary scripts.
- Every call uses the current user’s and tenant’s permissions; tools cannot inherit an overprivileged service account.
- Writes support preview, approval, idempotency, and rollback, so failure does not leave unknown state.
- Long-running tasks expose progress, cancellation, and audit, so users can take over at any time.
Models will change, but the execution contract must remain stable. Once a company packages business capabilities as governed CLI and API tools, it can replace the model above them and allow different agents to reuse the same security boundary. Agent value comes from work that can be completed, observed, and held accountable.
Engineering Details and Implementation Notes
1. Background and Problem Domain
1.1 The Execution Challenges AI Agents Face in BI
Coding agents such as Claude Code and Codex are gaining ground, while resident agents such as OpenClaw and Hermes Agent are becoming common. AI Agents are moving deeper into enterprise data analysis. When these agents interact with BI systems, a core tension appears: BI API surfaces are often broad and complex, while agents have limited reasoning windows and weak fault tolerance.
Traditional BI API invocation has several recurring problems:
These problems remain manageable in CLIs built for people: people can use documentation, error prompts, and interactive confirmations to compensate for an imperfect API. For an agent that depends entirely on reasoning and code generation, those design gaps grow exponentially and drive the success rate for BI tasks far below expectations.
1.2 The Role of HENGSHI CLI
HENGSHI CLI serves as a BI execution layer for coding agents and resident agents. Its engineered interface targets AI Agent execution, with goals distinct from those of a traditional human-facing CLI:
┌─────────────────────────────────────────────────────────────┐
│ Agentic BI 三位一体架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Agent │───▶│ CLI │───▶│ Headless │ │
│ │ 推理层 │ │ 执行层 │ │ 引擎 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ │ 稳定化的命令树 低延迟API │
│ │ Skills路由 查询路由 │
│ │ Dry-Run治理 缓存优化 │
│ │ SSE回显 │
│ │
└─────────────────────────────────────────────────────────────┘Within this architecture, the CLI serves as the execution layer. It accepts high-level intent from an agent, such as “create an East China regional cockpit dashboard,” uses Skills routing to break it into a stable command sequence, and uses Dry Run and SSE to keep the process predictable and reviewable.
2. Core Capabilities
HENGSHI CLI’s three core capabilities, Skills routing, Dry Run governance, and SSE feedback, do not stand alone. Together, they provide an assurance system for agent-led BI operations.
2.1 Skills Routing
Traditional CLI tools usually offer a flat set of commands with little semantic connection. An agent must infer each command’s meaning and dependencies on its own. HENGSHI CLI introduces a Skills routing system that divides BI operations into three independent Skill layers by semantic and responsibility boundaries:
2.1.1 Layer Overview
┌──────────────────────────────────────────────────────────────┐
│ Skills Router (路由层) │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│ │ everest-core │ │ everest-data │ │everest-workflow││
│ │ (核心技能) │ │ (数据技能) │ │ (工作流技能) ││
│ └────────┬────────┘ └────────┬────────┘ └──────┬───────┘│
│ │ │ │ │
│ 规范化术语处理 资源定位处理 编排协调处理 │
│ 认证与会话管理 app/dataset/model 跨域执行 │
│ │ │ │ │
└───────────┼────────────────────┼───────────────────┼────────┘
▼ ▼ ▼2.1.2 everest-core: Normalization and Authentication
everest-core forms the foundation of the Skills system. It handles the baseline capabilities required for every BI operation:
- Terminology normalization: Converts an agent’s natural-language description into the system’s standard terms. When an agent says “list all reports,” the core layer normalizes the request to a list operation on the
reportresource. When the agent mentions a “dataset,” the core layer makes sure it targetsdatasetrather thandatasource. - Authentication and session management: Maintains the connection to the HENGSHI BI platform and handles OAuth token refreshes and session renewal. The agent does not need to manage authentication details; it only needs to ensure that the request carries a valid session context.
- General metadata operations: Supports meta-queries such as retrieving current tenant information and the list of available operations.
# everest-core 内部术语映射示例
TERM_NORMALIZATION = {
"报表": "report",
"报告": "report",
"dashboard": "dashboard",
"仪表板": "dashboard",
"数据集": "dataset",
"数据源": "datasource",
"模型": "model",
"应用": "app",
"应用": "application"
}2.1.3 everest-data: Resource Resolution and Operations
everest-data handles the BI system’s core resource operations, including CRUD operations for applications (app), datasets (dataset), and data models (model). This layer focuses on deterministic resource resolution: how to identify one target resource from an ambiguous description.
# 资源定位的典型场景
$ everest dataset list --app retail-ops --output json
# 返回结构
{
"datasets": [
{
"id": "ds_001",
"name": "销售明细表",
"app_id": "app_retail_ops",
"created_at": "2026-03-15T10:30:00Z",
"schema": { "columns": 42, "rows": 1250000 }
},
{
"id": "ds_002",
"name": "客户画像表",
"app_id": "app_retail_ops",
"created_at": "2026-03-18T14:22:00Z",
"schema": { "columns": 28, "rows": 850000 }
}
],
"total": 2,
"page_token": null
}Resource resolution must address ambiguity between same-named resources. An agent might request “retrieve sales data” when several datasets include “sales” in their names. everest-data handles that ambiguity through three strategies:
- Context priority: Uses the most recently accessed application (
app) in the session context to narrow the search. - Tag matching: Supports exact filtering through metadata tags.
- Fuzzy-match scoring: Returns candidates ordered by relevance when no exact match exists.
2.1.4 everest-workflow: Cross-Domain Execution Orchestration
everest-workflow is the highest-level Skill. It handles complex BI operations that involve several resources and steps. With a traditional CLI, an agent often has to compose several commands itself; everest-workflow provides declarative orchestration instead:
# 创建一个完整的仪表板工作流
$ everest workflow execute --manifest华东驾驶舱创建流程.json --dry-run
# manifest示例结构
{
"name": "华东驾驶舱创建流程",
"steps": [
{
"skill": "everest-data",
"action": "dataset.query",
"params": {
"app": "retail-ops",
"dataset": "销售明细表",
"filters": { "region": "华东" }
}
},
{
"skill": "everest-data",
"action": "model.create",
"params": {
"name": "华东销售分析模型",
"dataset": "销售明细表(华东)",
"metrics": ["sum(revenue)", "count(orders)", "avg(order_value)"]
}
},
{
"skill": "everest-data",
"action": "dashboard.create",
"params": {
"app": "retail-ops",
"title": "华东区域驾驶舱",
"model": "华东销售分析模型"
}
}
]
}The workflow layer’s core value lies in atomicity and transactional behavior. Each step can run independently, failures can resume from a checkpoint, and the whole workflow supports transaction semantics so that it either all succeeds or all rolls back.
3. Dry Run Governance
3. Dry Run Governance
3.1 Why Agents Need Dry Run
Before running a CLI command, a person can inspect the command, confirm the parameters, and press Ctrl+C if something looks wrong. An agent runs a complete code-generation-and-execution loop. It may send several API requests within milliseconds, and their effects, particularly data changes, are often irreversible.
Dry Run (preview mode) addresses this problem. Before execution, it simulates the complete operation in read-only mode so that agents and operators can see exactly what will happen.
3.2 How Dry Run Works
HENGSHI CLI’s Dry Run is more than a simple preview. It is a complete safety-governance layer with several key components:
3.2.1 Operation Impact Analysis
When an agent sends an operation request, Dry Run first analyses the impact it may have:
# 授权操作的Dry-Run
$ everest authorize grant \
--target-type app \
--target-id app_42 \
--user 123:editor \
--dry-run
# 输出
┌─────────────────────────────────────────────────────────────┐
│ DRY-RUN PREVIEW │
├─────────────────────────────────────────────────────────────┤
│ Operation: authorize.grant │
│ │
│ Target: │
│ Type : app │
│ ID : app_42 │
│ Name : 零售运营系统 │
│ │
│ Action: │
│ Grant user 123 (editor) to app_42 │
│ │
│ Impact Analysis: │
│ ┌─────────────┬─────────────────────────────────────┐ │
│ │ Risk Level │ LOW │ │
│ │ Scope │ Single app (app_42) │ │
│ │ Reversible │ YES (via revoke) │ │
│ └─────────────┴─────────────────────────────────────┘ │
│ │
│ Prerequisites: │
│ ✓ User 123 exists │
│ ✓ Target app exists │
│ ✓ No conflicting permission │
│ │
├─────────────────────────────────────────────────────────────┤
│ Preview passed · ready for approval │
└─────────────────────────────────────────────────────────────┘3.2.2 Visualizing the Impact Scope
For high-risk operations such as data deletion and permission changes, Dry Run displays the operation’s impact scope:
┌──────────────────────────────────────────────────────────────────┐
│ DRY-RUN IMPACT REPORT │
├──────────────────────────────────────────────────────────────────┤
│ Operation: dataset.delete │
│ │
│ Target: │
│ Dataset: "客户画像表" (ds_002) │
│ App : retail-ops │
│ │
│ Dependencies Analysis: │
│ ┌────────────────────────────────────────────────────┐ │
│ │ 依赖此数据集的对象将受影响: │ │
│ │ │ │
│ │ • 模型 "华东客户分析" (model_007) │ │
│ │ └─ 引用字段: [customer_id, tags, segment] │ │
│ │ │ │
│ │ • 仪表板 "客户洞察驾驶舱" (dash_023) │ │
│ │ └─ 依赖模型 model_007 │ │
│ │ │ │
│ │ • 分享链接 3 个 │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ Cascading Effects: │
│ ┌────────────────────────────────────────────────────┐ │
│ │ [LOW] 级联删除风险 │ │
│ │ │ │
│ │ 若删除此数据集，系统将: │ │
│ │ 1. 移除模型 model_007 中的对应字段 │ │
│ │ 2. 将仪表板 dash_023 标记为"数据源不可用" │ │
│ │ 3. 使分享链接指向空数据集 │ │
│ │ │ │
│ │ 用户访问影响: 约 45 人 │ │
│ └────────────────────────────────────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────┤
│ ⚠️ Dry-Run blocked: High-impact operation requires explicit │
│ approval. Use --confirm to proceed or --cancel to abort. │
└──────────────────────────────────────────────────────────────────┘3.2.3 Approval-Workflow Integration
In team collaboration, Dry Run can integrate with an approval workflow:
# 提交Dry-Run结果到审批队列
$ everest authorize grant \
--target-type app \
--target-id app_42 \
--user 123:editor \
--dry-run \
--submit-approval
# 输出
DRY-RUN APPROVAL REQUEST
═══════════════════════════════════════════════════
Request ID : apr_20260401_001
Submitter : agent:claude-code-session-42
Timestamp : 2026-04-01T15:30:00Z
Operation : authorize.grant
Pending Approval From: [@admin-role]
Expected Resolution: 24h
Your operation has been queued for human approval.
Agent will be notified via SSE when decision is made.This design governs collaboration between AI and people: agents can explore and validate an operation plan during Dry Run, while people confirm high-risk execution.
4. SSE Feedback
4.1 The Need for Real-Time Feedback
When an agent starts a long-running operation such as a data export or report generation, it must answer key questions: Which stage has the operation reached? Did it encounter an error? When will the result be ready?
Traditional polling has low efficiency and high response latency. SSE (Server-Sent Events) solves this problem by letting the server push operation progress and results. The agent listens on one persistent connection instead of repeatedly asking for an update.
4.2 HENGSHI CLI’s SSE Architecture
┌────────────────────────────────────────────────────────────────────┐
│ SSE Event Flow │
├────────────────────────────────────────────────────────────────────┤
│ │
│ Agent HENGSHI CLI BI │
│ │ │ │ │
│ │ ┌─────────────────────┐ │ │ │
│ │─▶│ 发起命令 (异步模式) │──────▶│ │ │
│ │ └─────────────────────┘ │ │ │
│ │ │ ┌──────────────────┐ │ │
│ │ │─▶│ 建立SSE连接 │ │ │
│ │ │ └────────┬─────────┘ │ │
│ │ │ │ │ │
│ │ │ ▼ │ │
│ │ │ ┌──────────────────┐ │ │
│ │ │─▶│ 转发事件到Agent │──────▶│ │
│ │ │ └──────────────────┘ │ │
│ │ │ │ │
│ │ ◀───────────────────────────────── event stream │ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ │
└────────────────────────────────────────────────────────────────────┘4.3 Event-Type Design
HENGSHI CLI’s SSE channel defines these standard event types:
4.4 A Working Example
# 启动SSE监听模式
$ everest dashboard create \
--app retail-ops \
"华东区域驾驶舱" \
--async \
--sse-url "http://localhost:9090/events/agent-42"
# 等待SSE事件...
event: operation:started
data: {"operation_id":"op_7a2f3c","type":"dashboard.create","timestamp":"2026-04-01T16:00:00Z"}
event: operation:progress
data: {"operation_id":"op_7a2f3c","percent":25,"current_step":"validating_app_access","details":"Checking access to retail-ops app"}
event: operation:progress
data: {"operation_id":"op_7a2f3c","percent":50,"current_step":"resolving_model","details":"Resolving default model for dashboard"}
event: operation:progress
data: {"operation_id":"op_7a2f3c","percent":75,"current_step":"creating_dashboard","details":"Creating dashboard resource"}
event: operation:completed
data: {"operation_id":"op_7a2f3c","result":{"dashboard_id":"dash_128","title":"华东区域驾驶舱","app":"retail-ops"},"output_location":"/results/op_7a2f3c.json"}SSE feedback offers four advantages:
- Real-time response: Agents can detect operation-state changes within milliseconds.
- Recoverability: If an agent restarts, it can resume listening from the last known state as long as it recorded the
operation_id. - Debuggability: The full event log gives engineers detailed evidence for investigating problems.
- Composability: An agent can listen to event streams for several operations at the same time.
5. Engineering Practice
5.1 Integrating with an Agent Workflow
An agent workflow that integrates HENGSHI CLI usually follows this pattern:
┌─────────────────────────────────────────────────────────────────┐
│ Agent Workflow with HENGSHI CLI │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 理解任务 │───▶│ Dry-Run │───▶│ 执行命令 │───▶│ 处理结果 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ 意图解析 验证方案安全性 SSE监听 结果存储 │
│ 参数映射 影响范围评估 错误恢复 状态同步 │
│ │
└─────────────────────────────────────────────────────────────────┘5.2 Error-Handling Strategy
HENGSHI CLI handles errors according to three principles:
- Predictable error codes: Every error has a standardized code that agents can understand and handle.
- Recoverable error categories: The CLI distinguishes transient errors, such as network timeouts, from permanent errors, such as invalid parameters.
- Actionable error messages: An error message describes what happened and suggests how to resolve it.
# 错误示例
$ everest dashboard create --app invalid-app "测试仪表板"
# 输出
Error [E_APP_NOT_FOUND]: Application 'invalid-app' not found
├─ Suggestion: Use 'everest app list' to see available applications
├─ Did you mean: 'retail-ops' (similarity: 0.72)
└─ Error ID: err_20260401_a1b2c35.3 Performance Considerations
For high-frequency calls, HENGSHI CLI provides these optimizations:
- Connection reuse: Keeps a persistent connection to the BI platform to avoid repeated handshakes.
- Batch operations: Packages several operations of the same type for execution.
- Caching strategy: Uses a local cache for read-only operations to reduce repeat requests.
# 批量查询示例
$ everest dataset batch-get \
--ids ds_001,ds_002,ds_003 \
--cache-ttl 300
# 输出
{
"results": [...],
"cache_hit": true,
"cached_at": "2026-04-01T17:00:00Z"
}6. Summary and Outlook
6.1 Core Value
As the execution layer in an Agentic BI architecture, HENGSHI CLI addresses the core challenges AI Agents face in BI through three designs:
- Skills routing: Packages complex BI operations into semantically clear skill modules, reducing the agent’s cognitive burden.
- Dry Run governance: Provides a complete preview and impact analysis before execution, keeping automated behavior predictable and auditable.
- SSE feedback: Provides a real-time feedback channel for long-running operations, allowing agents to track execution state accurately.
6.2 Future Directions
As AI Agent technology evolves, HENGSHI CLI may next add:
- Natural-language interface improvements: Let agents describe BI tasks in natural language and route them automatically to the most suitable command combination.
- Multimodal responses: Return charts, data visualizations, and other richer forms of output alongside text.
- Intelligent retry strategies: Learn the best retry timing and parameter adjustments from historical execution data.
- Cross-platform deployment: Support more agent runtime environments, including cloud and serverless environments.
6.3 Suitable Scenarios
Sources and Verification Notes
Internal materials informed the account of HENGSHI capabilities and engineering practices. Competitor and version information was checked against official pages available on August 26, 2026. Product capabilities can vary by version, region, authorization, and deployment model, so teams should confirm them again in their target environment before procurement or release.
Further reading: HENGSHI SENSE Product and Technology White Paper.