---
name: ant-design-x
description: Use when building or refactoring the Gongxue AI chat UI, streaming protocol, runtime skills, attachments, prompts, or agent message rendering with Ant Design X.
---

# Gongxue Ant Design X

## Runtime stack

- Use the repository-pinned `@ant-design/x`, `@ant-design/x-sdk`, and `@ant-design/x-markdown` versions.
- Use `useXChat` for message lifecycle and `useXConversations` for local conversation state.
- Use `AbstractChatProvider` with `XRequest` for authenticated SSE; provider code only handles transport and message transformation.
- Prefer `Bubble`, `Conversations`, `Sender`, `Attachments`, `Welcome`, `Prompts`, `Think`, `ThoughtChain`, `Actions`, `FileCard`, and `XMarkdown` over custom equivalents.
- Put shared AI component configuration in the root `XProvider`; custom CSS covers layout and project branding only.

## Project contracts

- Regular messages POST to `/api/ai/chat/conversations/:id/stream`.
- Regeneration POSTs to `/api/ai/chat/conversations/:id/messages/:messageId/regenerate/stream` and must not create another user message.
- Always send a UUID `clientRequestId`, attachment IDs, and the conversation skill lock.
- Treat `message.completed` as the final canonical message after applying stream deltas.
- Render reasoning with `Think`, tool events with `ThoughtChain`, attachments with `FileCard`, and copy/retry/feedback with `Actions`.

## Runtime skills

- Skill metadata comes from the server tool registry; do not duplicate permission maps in the frontend.
- Automatic mode exposes all authorized tools. A locked skill restricts both model tool discovery and execution.
- Never trust a client skill key as authorization. Server permission and business-scope checks remain mandatory.

## Safety

- Keep Markdown raw HTML escaped and DOMPurify restrictions enabled.
- Uploads are private, authenticated, limited to five files per message and 10MB per file.
- Do not render or persist raw sensitive tool arguments or results; use redacted summaries.
- Stop requests on conversation changes and persist cancelled assistant messages.

## Validation

- Run admin and server typechecks.
- Run AI chat, provider, mapper, bubble, agent-tool, attachment, and migration tests.
- Run production builds before delivery.