How One Backend Serves Three Audiences: OpenAPI, CLI, and Frontend

01 | One Backend, Three Faces

The platform’s backend is a single OpenAPI contract ( backend-api) that powers all capabilities. Instead of duplicating the contract, it is exposed in three different forms for three audiences:

OpenAPI ( backend-api): stable contract for third‑party developers.

CLI ( a-cli in cli-repo): task‑ and lifecycle‑oriented atomic commands for AI agents.

Frontend ( web-repo): full‑screen web console for human users.

Each face has its own organization, granularity, and design philosophy. The diagram in the article illustrates how the same backend capabilities are mapped to different structures: resources for OpenAPI, tasks for CLI, and UI scenes for the frontend.

02 | Agent Lifecycle: A Closed Loop

The lifecycle consists of a create‑dev‑publish loop, a consumption workspace for user chats, and an iteration workspace where AI analyses and syncs back to the development workspace. Key points:

The iteration workspace does not serve user requests directly; only the published consumption workspace does.

AI downloads the .agent_context/ directory, performs local analysis, uploads results, and pushes them back to the dev workspace. The CLI provides the atomic building blocks ( workspace pack, upload, sync) while AI makes the decisions.

Tools must not replace AI judgment; they only provide reliable, retryable bricks.

03 | CLI Command Tree: What Atomic Commands Look Like

The top‑level a-cli is split into seven domains that correspond to the agent lifecycle stages. Each domain contains clear, semantic atomic commands:

a-cli
├── create          # create an agent (local or remote)
├── dev             # config / workspace / git / resources / publish
├── iterate         # workspace / container / sync / task
├── use             # chat / session / task / instance
├── resources       # skill / knowledge / mcp / subscription
├── organization    # search (forced keyword, top‑5 only)
└── tools           # git query / model query

In contrast, the OpenAPI side is organized by resource paths (e.g., /backend-api/Skill/...). The same backend endpoint does not appear as a command in the CLI; instead, it is expressed as higher‑level actions such as dev config consumers add. This demonstrates that "command surface ≠ API surface".

04 | Exposing All Atomic Capabilities to AI via a Skill

All atomic CLI commands are made available to AI, but AI needs guidance on how to combine them. The platform ships a Markdown‑based Skill ( SKILL.md + references/*.md) that acts as an operation manual for AI, describing which command sequences to use, when to ask a human, and which actions are unsafe.

Example workflow for “turn recent conversations into a knowledge base”:

User intent: turn recent conversation into knowledge base
↓
Skill references/iterate.md tells AI:
1. iterate workspace pack          ← pack iteration workspace
2. local analysis .agent_context/user_chat/   ← AI decides
3. extract knowledge entries
4. resources knowledge add      ← write to knowledge store
5. iterate sync --target_type knowledge   ← sync back to dev workspace
Constraints (from Skill):
- If conversation contains sensitive info, confirm with user first.
- If >50 knowledge items, add in batches.
- Must run workspace upload before sync.

The Skill separates execution (atomic commands) from judgment (AI’s decision‑making).

05 | Pitfall 1: Adding Users to the Wrong Channel

The platform distinguishes two role concepts:

Users (can use an agent) – stored in roles as member groups.

Collaborators (can co‑develop an agent) – stored in a separate developer list.

Initially the CLI exposed a dev config roles command that passed the low‑level role‑write API directly to AI. AI mistakenly routed a "add user" request to the collaborator channel because the documentation used the ambiguous term "developer".

Fixes applied in the CLI code:

Remove the public config roles command; downgrade the raw role‑write API to an internal fetchJson call that is never exposed to AI.

Introduce two explicit commands: config consumers (add user) and config collaborators (add collaborator).

Update the Skill to hard‑code routing rules: ambiguous additions default to consumers; only explicit co‑development adds go to collaborators.

If multiple groups are possible, the CLI exits with a non‑zero code and lists the --role options, forcing AI to defer the choice to a human.

Enforce idempotent addition and cross‑group constraints at the command layer.

06 | Pitfall 2: Organization Search Almost Became a Data‑Leak Vector

The backend organization search endpoint supports pagination and an optional keyword, which could be abused to dump the entire organization hierarchy. The CLI initially exposed the endpoint unchanged, allowing AI to request all pages.

Remediation in the CLI code:

Make the keyword parameter mandatory; empty keywords cause an error.

Hard‑code page=1&page_size=5 and hide pagination parameters from callers.

Strip sensitive fields such as parent_org_id and return only the first five results.

Require a three‑step flow: search → select → consumers add --org_id; deletion is limited to the agent’s authorized scope.

The design principle is to place "leak‑prevention" constraints in the tool layer rather than relying on callers to be careful.

07 | The Fourth Face: MCP – The Opposite Direction of CLI

Beyond the three primary faces, MCP (Model‑Compute‑Platform) represents another AI‑oriented surface with two opposite orientations:

MCP (expose) : provides usage‑channel APIs that external AIs call to consume a published agent.

MCP (mount) : registers MCP resources as capabilities that the agent can invoke external tools.

CLI is the "operator" side (AI → platform), while MCP expose is the "consumer" side (external AI → your agent) and MCP mount is the "capability" side (your agent → external tool). The directionality determines the design and security considerations.

Summary

One backend can be presented as three distinct faces—OpenAPI for developers, CLI for AI agents, and a web UI for humans—without duplicating the contract.

CLI is not a simple command‑line wrapper of the OpenAPI; it reorganizes functionality by task and lifecycle, turning low‑level endpoints into semantic actions.

The design’s core is the "judgment gap": tools provide atomic bricks, AI performs analysis and decision‑making.

Exposing raw interfaces to AI also exposes risk; concrete incidents (mis‑routed user addition and organization‑search leakage) illustrate why constraints must be enforced at the tool layer.

MCP adds a fourth face with opposite data flow, highlighting that different AI‑oriented surfaces require different design philosophies.

Security constraints belong in the tool layer, not in documentation or caller discipline.