JGuang
EN

智能体与 CLI

Agent and CLI setup · Astryx

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

智能体与 CLI

使用本页右上角“交给 Agent”获取整套 Astryx 接入提示词，而不只当前示例。Agent 应先检查项目依赖、构建工具、样式入口和既有规范，再按需安装。

npx @astryxdesign/cli@0.7.1 init
npx @astryxdesign/cli@0.7.1 component Button
npx @astryxdesign/cli@0.7.1 component --list
npx @astryxdesign/cli@0.7.1 doctor

init 写入 Agent 指南，不等于已配置样式和 Provider。先检查既有 AGENTS.md / CLAUDE.md，保留用户规则。没有安装官方 CLI 时不要使用裸 npx astryx，它可能解析到其他同名包。

通过 JGuang MCP 使用 get_resource("astryx")、search_components 和 read_docs。MCP 返回资料与命令，不自动在用户项目执行安装。

上游完整参考（英文）

Working with AI

How to set up AI coding tools to generate correct component code.

Overview

The design system is built to be AI-friendly: consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props.

The CLI includes a built-in agent docs system that generates context files for your AI tool of choice. One command sets up everything your AI needs to write correct component code.

Set up agent docs

Tell your AI to install the CLI and set itself up:

Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.

That's it. The init --features agents command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, astryx upgrade --from <old version> reports a stale block and adding --apply refreshes it.

By default this creates AGENTS.md (the tool-agnostic standard most agents read). To target a specific tool's file instead:

npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
npx @astryxdesign/cli init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)
npx @astryxdesign/cli init --features agents --agent all       # every agent file present, else AGENTS.md and .claude/CLAUDE.md

What Gets Generated

The generated context teaches your AI a 3-step workflow before writing any UI code:

  • astryx build "<idea>": get the page template to start from (always one: the closest match, or the app shell), two other templates, and the blocks and components for the parts it lacks
  • astryx template <name> <path>: scaffold that template into the project, keep its frame and spacing, and replace its content
  • astryx component <Name>: read props and examples for every component used

It also includes rules that prevent common mistakes (start every page from a template, no raw divs, no style={{}}, use tokens not magic values), a CLI quick reference, and package-labeled integration guidance when a configured manifest declares agentDocs. After setup, you shouldn't need to manually correct your AI on these conventions; the agent docs handle it at the system level.

Cursor Setup

Cursor reads project rules from .cursor/rules/. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as .cursor/rules/astryx.mdc; an absolute path is refused.

npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc

Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as alwaysApply: true) stays.

Checking Your Setup

Paste this into your AI before writing any component code. If your AI can't answer these questions, it'll know to install the agent docs first.

Before writing any Astryx code, check your knowledge:

1. What is the correct import path for Button?
2. How do you make a Dialog non-dismissible?
3. What prop does Selector use for its items?

If you don't know all three, run `npx @astryxdesign/cli init --features agents` to generate agent docs, then read the generated file.

The astryx Pattern

AI agents frequently invoke the CLI with incorrect paths (e.g. node_modules/@astryxdesign/cli/bin/docs.mjs instead of astryx.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.

"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}

With this alias, agents run npm run astryx -- component --list instead of guessing the binary path. The -- separator is standard npm convention for passing flags to scripts.

npm run astryx -- component --list
npm run astryx -- component Dialog --dense
npm run astryx -- docs styling --full --detail brief
npm run astryx -- docs tokens --dense

Shorter output: --detail and --dense

For a shorter read, add --detail brief (one line per section) or --detail compact. --dense swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.

astryx docs styling --full --detail brief
astryx component Dialog --detail compact
astryx docs principles --dense

MCP Server

Astryx ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the Astryx design system directly, searching for components, reading full documentation, and pulling code examples on demand.

The MCP server exposes two tools: search(query) for discovering components, doc topics, and templates; and get(name) for retrieving full documentation with props, usage, and examples.

Add the server to your MCP config file. This works with any MCP-compatible tool: Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.

{
  "mcpServers": {
    "astryx": {
      "type": "url",
      "url": "https://astryx.atmeta.com/mcp"
    }
  }
}

Once connected, your AI tool can search for components by natural language (e.g. "dropdown menu", "success message") and retrieve full documentation without any manual CLI invocation. The server uses the same keyword index from component docs, so search quality improves automatically as component documentation is updated.