@yh-ui/yh-ui-skill 1.0.38 → 1.0.42

package/assets/llms-full.txt

@@ -20,6 +20,8 @@ Read `skills/yh-ui/SKILL.md` first. Then load only the references relevant to th
 - `skills/yh-ui/references/recipes-form-schema.md`
 - `skills/yh-ui/references/recipes-ai.md`
 - `skills/yh-ui/references/recipes-flow.md`
+- `skills/yh-ui/references/recipes-theme.md`
+- `skills/yh-ui/references/recipes-icons.md`
 - `skills/yh-ui/references/codegen-rubric.md`
 - `skills/yh-ui/references/eval-scenarios.md`
 

package/assets/llms.txt

@@ -18,5 +18,7 @@ High-value references:
 - `skills/yh-ui/references/recipes-form-schema.md`: YhFormSchema deep recipe.
 - `skills/yh-ui/references/recipes-ai.md`: YhAi component deep recipe.
 - `skills/yh-ui/references/recipes-flow.md`: Flow deep recipe.
+- `skills/yh-ui/references/recipes-theme.md`: Theme deep recipe.
+- `skills/yh-ui/references/recipes-icons.md`: Icons deep recipe.
 
 Use `@yh-ui/nuxt` for Nuxt, `@yh-ui/components` for component-only imports, `@yh-ui/yh-ui` for all-in-one Vue install, `@yh-ui/request` for request state, `@yh-ui/flow` for flow editors, and `@yh-ui/ai-sdk` for AI SDK integrations.

package/assets/metadata.json

@@ -1,4 +1,4 @@
 {
   "packageName": "@yh-ui/yh-ui-skill",
-  "version": "1.0.38"
+  "version": "1.0.42"
 }

package/assets/skills/yh-ui/README.md

@@ -1,53 +1,56 @@
 # YH-UI Agent Skill
 
-This directory packages YH-UI knowledge for modern AI coding agents. It is designed as a small cross-platform skill: one `SKILL.md` file plus progressively loaded reference files.
+[中文文档 (Chinese Documentation)](./README.zh-CN.md)
+
+This directory packages YH-UI knowledge for modern AI coding agents. It is designed as a small, progressive cross-platform skill: one `SKILL.md` file acting as the entry point, plus progressively loaded reference files.
 
 ## Use Cases
 
-- Generate Vue 3 or Nuxt code with YH-UI components.
-- Choose the right YH-UI package for a task.
-- Avoid hallucinated component names, package paths, theme APIs, and locale paths.
-- Give AI agents compact examples for admin pages, AI chat, request hooks, flow editors, themes, icons, and locale setup.
-- Anchor generated code to source exports documented in `references/source-truth.md`.
+- Generate Vue 3 or Nuxt 3 code with YH-UI components.
+- Choose the correct YH-UI package boundary for a task.
+- Avoid hallucinated component names, packages, theme options, and locale paths.
+- Enforce 100% prioritization of YH-UI's built-in components and utilities over writing custom HTML elements.
+- Provide AI agents with precise recipes for data tables, form schemas, AI chat bubbles, flow canvases, themes, and icons.
 
 ## Design Principles
 
-- `SKILL.md` stays as the operating manual and trigger surface.
-- Reference files are loaded progressively by task, keeping agent context small.
-- `source-truth.md` is the compact export map and must match source exports.
-- `api-cheatsheet.md` is generated from source using TypeScript AST extraction for priority props, emits, slots, and exposed methods.
-- Deep recipe files hold opinionated high-value patterns for complex components.
-- `codegen-rubric.md` defines what generated YH-UI code must satisfy.
-- `eval-scenarios.md` captures regression prompts for checking AI behavior over time.
-
-## How To Use
-
-### ChatGPT, Codex, Claude, and compatible skill loaders
+- `SKILL.md` is the trigger surface and central manual for the AI.
+- Reference files are loaded progressively by task, keeping the agent's context small and efficient.
+- `references/source-truth.md` is the compiled export map generated from source packages.
+- `references/vue-component-practices.md` defines Vue 3.5+ setup guidelines, TS type-safety structures, and component encapsulation decisions.
+- Deep recipe files hold high-value code blocks for advanced scenarios:
+  - `recipes-table.md`: Virtual scrolls, cell slots, data export, printing.
+  - `recipes-form-schema.md`: Repeating lists (`type: 'list'`), custom renderers.
+  - `recipes-ai.md`: DeepSeek-R1 thinking steps (`YhAiThoughtChain`), code execution, Mermaid diagrams.
+  - `recipes-flow.md`: BPMN and AI workflow nodes, resizers, toolbars, undo/redo logs.
+  - `recipes-theme.md`: Global config providers, density, preset themes, WCAG contrast.
+  - `recipes-icons.md`: Iconify collection loads, inline SVG.
+- `codegen-rubric.md` provides strict evaluation rules (fails the AI if it writes custom CSS/HTML for controls supported by YH-UI).
 
-Add the `skills/yh-ui` folder as a project skill or knowledge folder. The primary entry is `SKILL.md`.
+## Installation & Usage
 
-### Claude.ai / Claude Code style
+You can deploy these rules into your local IDE setups using the monorepo CLI:
 
-Upload or reference this folder as a skill. The YAML frontmatter in `SKILL.md` provides the name and trigger description. Reference files are intentionally split so the model can load only what it needs.
+```bash
+# Install to Cursor (.cursor/rules/)
+npx @yh-ui/yh-ui-skill install --target cursor
 
-### Cursor, Codex, and engineering agents
+# Install to Trae (.traerules or root config)
+npx @yh-ui/yh-ui-skill install --target cursor
 
-Point the agent to `skills/yh-ui/SKILL.md` before asking it to generate YH-UI code. For repository-level rules, reuse the core rules from `SKILL.md` in your agent instructions.
+# Export to general project directory (.yh-ui/)
+npx @yh-ui/yh-ui-skill install --target project
+```
 
-### ChatGPT project knowledge
+### Manual Configuration
 
-Upload `SKILL.md` plus the `references` directory. Tell the assistant to read `SKILL.md` first and open reference files only when relevant.
+- **Cursor**: Create/update `.cursorrules` or drop these files into `.cursor/rules/`.
+- **Trae**: Create/update `.traerules` at the project root with the core rules from `SKILL.md`. In chats, use `#SKILL.md` to reference rules.
+- **Claude Project / Custom GPTs**: Upload `SKILL.md` and the `references/` files as custom knowledge documents.
 
 ## Release Checklist
 
 - Run `pnpm verify:yh-ui-skill`.
 - Run `pnpm generate:yh-ui-skill` when component exports or priority APIs change.
-- Confirm package versions in the repository are current.
-- Confirm `references/source-truth.md` matches package exports when components are added or renamed.
+- Confirm `references/source-truth.md` and `references/api-cheatsheet.md` matches package exports when components are added or renamed.
 - Run the prompts in `references/eval-scenarios.md` against at least one target AI model before a major skill release.
-- Confirm README links still resolve.
-- Regenerate the skill if component package boundaries change.
-
-## License
-
-MIT. See `LICENSE.txt`.

package/assets/skills/yh-ui/README.zh-CN.md

@@ -0,0 +1,55 @@
+# YH-UI Agent Skill (智能 Agent 辅助开发规则库)
+
+[English Documentation (英文文档)](./README.md)
+
+此目录封装了 YH-UI 组件库的专业知识，专为现代 AI 编码助手（如 Cursor、Trae、Claude Code 等）设计。它采用轻量化的跨平台 Skill 设计结构：由一个作为入口导向的 `SKILL.md` 文件以及一组按需加载的 Reference 参考文件组成。
+
+## 主要用途
+
+- 生成符合 YH-UI 规范的 Vue 3 或 Nuxt 3 页面与组件代码。
+- 引导 AI 选择正确的 YH-UI 模块包边界，避免引入多余的三方依赖。
+- 杜绝 AI 凭空捏造不存在的组件名、属性、主题配置或语言包路径。
+- **100% 强制 AI 优先使用已有的 YH-UI 组件**，严禁在组件库有支持时手写原生 HTML/CSS 重复造轮子。
+- 为 AI 助手提供高价值的进阶 Recipes（表格虚拟滚动、嵌套表单 Schema、AI 思维链、可视化流程图、全局国际化及主题配置）。
+
+## 设计原则
+
+- **`SKILL.md`**：作为 AI 的系统指令入口与核心操作指南，定义了严格的防错守卫。
+- **按需渐进加载**：参考文件按职责细分，AI 仅在处理特定任务（如 Table 或 Flow）时才读取对应文件，保持上下文体积小巧高效。
+- **`references/source-truth.md`**：由源码 AST 自动提取生成的导出真相图谱，确保名字 100% 准确。
+- **`references/vue-component-practices.md`**：定义了 Vue 3.5+ 响应式属性解构、严格 TypeScript 类型、组件销毁内存清理以及组件库二次封装工作流。
+- **核心业务 Recipes**：
+  - `recipes-table.md`：大列表虚拟滚动、表格插槽自定义、Excel 导入导出与打印 API。
+  - `recipes-form-schema.md`：动态表单 Schema、重复嵌套列表（`type: 'list'`）、自定义 render 渲染 VNode。
+  - `recipes-ai.md`：AI 聊天气泡、DeepSeek-R1 思维链（`YhAiThoughtChain`）渲染、代码沙箱执行、Mermaid 图表渲染。
+  - `recipes-flow.md`：BPMN 与 AI 智能工作流节点注册、NodeResizer、NodeToolbar、撤销/重做历史记录。
+  - `recipes-theme.md`：全局 ConfigProvider 国际化配置、Preset 预设、密度调整、色盲友好模式、WCAG 2.1 对比度无障碍校验。
+  - `recipes-icons.md`：Iconify 图标集异步加载、自定义 SVG 渲染、旋转动画。
+- **`codegen-rubric.md`**：代码生成评审准则，若 AI 绕过 YH-UI 手写重复控制，则判定生成失败。
+
+## 安装与集成方法
+
+您可以使用 Monorepo 提供的命令行工具将这些规则自动同步到本地 IDE 配置中：
+
+```bash
+# 自动部署到 Cursor 规则目录 (.cursor/rules/)
+npx @yh-ui/yh-ui-skill install --target cursor
+
+# 自动部署到 Trae 规则目录
+npx @yh-ui/yh-ui-skill install --target cursor
+
+# 导出到项目当前目录 (.yh-ui/)
+npx @yh-ui/yh-ui-skill install --target project
+```
+
+### 手动引入上下文
+
+- **Cursor**：将 `SKILL.md` 的内容粘贴至根目录的 `.cursorrules` 文件中，或将 references 下的文件直接拖入 `.cursor/rules/` 文件夹。
+- **Trae**：在根目录下创建 `.traerules` 并粘贴 `SKILL.md` 内容。在提问时，使用 **`#SKILL.md`** 引入对应规则作为对话上下文。
+- **Claude Project / Custom GPTs**：将 `SKILL.md` 和 `references/` 目录上传至知识库（Knowledge）中。
+
+## 维护与发布流程
+
+- 开发中如新增组件，应运行 `pnpm generate:yh-ui-skill` 重新生成 API 导出。
+- 修改规则后，执行 `pnpm verify:yh-ui-skill` 进行链接与 frontmatter 静态校验（通过 21 个文档的测试方可提交）。
+- 执行 `pnpm format` 以对齐 Markdown 排版。

package/assets/skills/yh-ui/SKILL.md

@@ -25,8 +25,9 @@ Do not use this skill for:
 
 ## Core Rules
 
-- Prefer existing YH-UI components over hand-written base controls.
-- Do not invent components, props, hooks, package paths, or theme APIs.
+- **Strict YH-UI Prioritization**: Under no circumstances should you generate custom HTML/CSS controls (e.g. custom buttons, inputs, tables, dialogs, drawers, scrollbars, markdown cards) or manually construct network fetches/stream connections when YH-UI packages support them. You must 100% prioritize utilizing YH-UI components and utilities.
+- **Extension & Re-encapsulation Principle**: If a YH-UI component does not fully meet a specific UI requirement, you must first try to extend it using slot customisation, CSS overrides, or component composition. Writing custom elements from scratch is a last resort, and you must justify why YH-UI could not be extended.
+- Do not invent components, props, hooks, package paths, or theme APIs. Check `references/source-truth.md` to ensure names are real.
 - Use `@yh-ui/yh-ui` for ordinary Vue apps that want the all-in-one entry.
 - Use `@yh-ui/nuxt` for Nuxt apps and rely on auto-imported components/composables.
 - Use `@yh-ui/components` when the user asks for component-only usage.
@@ -73,6 +74,33 @@ import App from './App.vue'
 createApp(App).use(YhUI).mount('#app')
 ```
 
+### Global Config & i18n (Root Setup)
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { YhConfigProvider } from '@yh-ui/components'
+import zhCn from '@yh-ui/locale/lang/zh-cn'
+import en from '@yh-ui/locale/lang/en'
+
+const locale = ref(zhCn)
+const currentSize = ref<'default' | 'small' | 'large'>('default')
+
+function toggleLang() {
+  locale.value = locale.value.name === 'zh-cn' ? en : zhCn
+}
+</script>
+
+<template>
+  <YhConfigProvider :locale="locale" :size="currentSize">
+    <button @click="toggleLang">Switch Language</button>
+    <AppLayout>
+      <router-view />
+    </AppLayout>
+  </YhConfigProvider>
+</template>
+```
+
 ### On-Demand Components
 
 ```vue
@@ -147,6 +175,31 @@ const edges: FlowEdge[] = []
 </template>
 ```
 
+### Theme
+
+```ts
+import { ThemePlugin } from '@yh-ui/theme'
+
+app.use(ThemePlugin, {
+  preset: 'blue',
+  dark: false,
+  persist: true
+})
+```
+
+### Icons
+
+```vue
+<script setup lang="ts">
+import { Icon } from '@yh-ui/icons/vue'
+</script>
+
+<template>
+  <Icon icon="mdi:home" :size="20" color="var(--yh-color-primary)" />
+  <Icon icon="mdi:loading" spin />
+</template>
+```
+
 ## Progressive References
 
 Read only the file needed for the task:
@@ -165,6 +218,8 @@ Read only the file needed for the task:
 - Deep form schema recipe: `references/recipes-form-schema.md`
 - Deep AI recipe: `references/recipes-ai.md`
 - Deep Flow recipe: `references/recipes-flow.md`
+- Deep Theme recipe: `references/recipes-theme.md`
+- Deep Icons recipe: `references/recipes-icons.md`
 - Code generation acceptance rubric: `references/codegen-rubric.md`
 - Evaluation prompts for regression testing: `references/eval-scenarios.md`
 

package/assets/skills/yh-ui/references/codegen-rubric.md

@@ -4,29 +4,33 @@ Use this checklist before returning YH-UI code.
 
 ## Must Pass
 
-- Imports use real package paths from `source-truth.md`.
-- Component names exist in `source-truth.md`.
-- Vue examples include required CSS when using component-only imports.
-- Nuxt examples use `@yh-ui/nuxt` and rely on auto-import unless the user disabled it.
-- Locale imports use `@yh-ui/locale/lang/zh-cn`, `@yh-ui/locale/lang/en`, or another real locale path pattern.
-- Theme customization uses `@yh-ui/theme`, `ThemePlugin`, `useTheme`, or CSS variables.
-- Request examples use `createRequest` and `useRequest` instead of stale factory names.
-- Flow examples set an explicit height.
-- AI examples do not expose provider API keys in frontend code.
-- Vue SFC examples follow `vue-component-practices.md` for block order, TypeScript, props/emits, reactivity, accessibility, SSR, and performance.
+- **Prioritize YH-UI**: 100% of UI elements and utility actions (like tables, dropdowns, dialogs, scrolls, loading icons, fetch hooks) use YH-UI packages if supported. Writing custom elements when YH-UI supports them **fails** code generation.
+- **Strict Extensions**: Any customization or gaps in YH-UI controls are addressed via slot templates, custom style parameters, or composites. Writing raw custom controls is only permitted as a last resort and must be documented.
+- **Real Exports Only**: Imports use actual package boundaries and names listed inside `source-truth.md`. Hallucinated names or paths **fail** code generation.
+- Vue examples include required component CSS when importing `@yh-ui/components` on-demand.
+- Nuxt examples use `@yh-ui/nuxt` and rely on auto-imports (without manually importing YH-UI components in pages).
+- Locale imports use `@yh-ui/locale/lang/zh-cn`, `@yh-ui/locale/lang/en`, or other real locale paths.
+- Theme customization uses `@yh-ui/theme`, `ThemePlugin`, `useTheme`, or standard CSS design variables.
+- Request client instances use `createRequest` and `useRequest` from `@yh-ui/request` (no custom axios or raw fetch queries).
+- Flow examples wrap editor canvases inside explicitly dimensioned heights, and use `<ClientOnly>` in SSR.
+- AI examples do not expose provider keys in client-side script code.
+- Vue SFC files strictly match block sequences, TS variables structure, reactivity parameters, and onUnmounted cleanups detailed in `vue-component-practices.md`.
 
 ## Should Pass
 
 - Pick the smallest YH-UI surface that solves the task.
 - Prefer composable AI UI for custom products and `YhAiChat` for complete chat surfaces.
 - Include empty, loading, and error states for data-heavy pages.
-- Keep examples TypeScript-friendly.
-- Avoid unrelated dependencies when YH-UI already provides the capability.
+- Keep templates TypeScript-friendly: use `import type`, type template refs with `InstanceType<typeof YhComponent>`, and define typed interface objects.
+- Avoid unrelated dependencies (like lodash, element-plus, custom hooks) when YH-UI already provides the capability.
 - Keep generated UI code readable and production-shaped, not demo-only.
 - Use stable `:key` values, computed derived state, and explicit loading/error/empty states where relevant.
 
 ## Red Flags
 
+- **Hallucinated Controls**: Reinventing standard visual controls (e.g. custom scroll elements, custom select components, custom modal popups) instead of using the corresponding YH-UI components.
+- **Custom Fetches**: Initiating direct `fetch` / `axios` connections in views instead of utilizing `createRequest` or `useRequest` from `@yh-ui/request`.
+- **Untyped Ref Handles**: Declaring component template refs without type-casting them using `InstanceType<typeof ...>` (e.g. `const refVal = ref(null)`).
 - Invented `Yh*` components.
 - Old APIs such as `createYhTheme` or `createRequestInstance`.
 - Nuxt pages manually importing many YH-UI components despite auto-import.

package/assets/skills/yh-ui/references/nuxt.md

@@ -42,9 +42,55 @@ The module auto-imports common hooks and utilities such as `useNamespace`, `useZ
 
 `useId` is imported as `useYhId` to avoid conflicts with Vue/Nuxt native `useId`.
 
+## SSR Request Fetching
+
+When fetching data during Nuxt server-side rendering (SSR), integrate `@yh-ui/request` within Nuxt's `useAsyncData` to ensure proper hydration and prevent duplicate requests on the client side:
+
+```vue
+<script setup lang="ts">
+import { createRequest } from '@yh-ui/request'
+
+const api = createRequest({ baseURL: '/api' })
+
+// Fetch data using Nuxt's useAsyncData to support SSR hydration
+const { data: users, pending, error } = await useAsyncData('users', () => api.get('/users'))
+</script>
+
+<template>
+  <div v-if="pending">Loading...</div>
+  <div v-else-if="error">{{ error.message }}</div>
+  <YhTable v-else :data="users" :columns="[{ prop: 'name', label: 'Name' }]" />
+</template>
+```
+
+## AI & Private Server Routes
+
+Never make AI provider calls (OpenAI, DeepSeek, Anthropic) directly from client code. Always proxy them through Nuxt Server Routes (`server/api/*`) using Nitro's server capabilities:
+
+### Server Route (`server/api/chat.ts`)
+
+```ts
+import { defineEventHandler, readBody } from 'h3'
+import { createProviderAdapter } from '@yh-ui/ai-sdk'
+
+export default defineEventHandler(async (event) => {
+  const { messages } = await readBody(event)
+  const config = useRuntimeConfig()
+
+  const provider = createProviderAdapter({
+    provider: 'deepseek',
+    apiKey: config.deepseekApiKey,
+    defaultModel: 'deepseek-chat'
+  })
+
+  // Return the streamed response securely from the server
+  return provider.chatStream(messages)
+})
+```
+
 ## SSR Rules
 
-- Use `<ClientOnly>` around browser-heavy flow editors.
-- Do not assume `window`, `document`, or `localStorage` exists during SSR.
-- Keep API keys on the server side, especially for AI provider routes.
+- Use `<ClientOnly>` around browser-heavy flow editors, Monaco code editors, charts, or SVG animators.
+- Do not assume `window`, `document`, `localStorage`, or browser event listeners exist during server-side compilation.
+- Keep API keys and model keys on the server side; inject them via `useRuntimeConfig()` in Nitro event handlers.
 - Let the module inject CSS unless the user explicitly disabled `importStyle`.

package/assets/skills/yh-ui/references/recipes-ai.md

@@ -1,58 +1,150 @@
-# Deep Recipe: YhAi Components
+# Deep Recipe: YH-UI AI Components
 
-Use this recipe for AI chat, copilots, assistant panels, generated artifacts, citations, attachments, and code-heavy AI answers.
+Use this recipe when building rich AI chat applications, assistant portals, Copilot interfaces, reasoning process visualisations, interactive code environments, and AI server integrations.
 
 ## Default Choice
 
-- Use `YhAiChat` for a complete chat surface.
-- Compose `YhAiBubbleList`, `YhAiBubble`, `YhAiSender`, `YhAiSources`, `YhAiAttachments`, and `YhAiActionGroup` for custom products.
-- Use `@yh-ui/ai-sdk/vue` for Vue chat state.
-- Keep provider secrets in server routes.
+Combine `@yh-ui/components` (for frontend AI components) with `@yh-ui/ai-sdk/vue` (for Vue composition API chat hooks) and `@yh-ui/ai-sdk` (for server provider adapters, security filters, and tracing).
 
-## Source-Aligned API Highlights
+## AI Frontend Component Selection
 
-- `YhAiChat`: `messages`, `loading`, `suggestions`, `virtualScroll`, `virtualHeight`, `estimatedItemHeight`; emits `send`, `update:messages`, `clear`; slots `header`, `message`, `loading`, `sender`.
-- `YhAiBubble`: `content`, `markdown`, `role`, `placement`, `loading`, `typing`, `streaming`, `citations`, `multimodal`, `structuredData`, `enableSanitizer`; slots `avatar`, `header`, `default`, `footer`.
-- `YhAiSender`: `modelValue`, `placeholder`, `disabled`, `loading`, `clearable`, `commands`, `mentionOptions`, `attachments`; emits `update:modelValue`, `send`, `change`, `clear`, `command`, `remove-attachment`, `upload`; slots `prefix`, `actions`, `submit`.
+- **`YhAiBubble`**: Renders message bubbles. It supports typed animations, markdown parsing, syntax highlighting, and custom sanitization filters.
+- **`YhAiThoughtChain`**: Visualises multi-step reasoning processes (e.g. DeepSeek-R1 thinking logs).
+- **`YhAiCodeRunner` / `YhAiCodeEditor`**: Provides interactive playgrounds where AI-generated code can be edited and executed directly.
+- **`YhAiMermaid`**: Renders standard Mermaid graph syntax dynamically in real-time.
+- **`YhAiSources`**: Shows cited articles, files, or document passages with relevance scores.
 
-## Pattern: Custom Chat
+## Pattern: Interactive Chat Interface with Code Execution
+
+This template implements streamed text answers, rendering of reasoning logs, interactive code execution inside Pyodide/python runtimes, and Mermaid diagrams:
 
 ```vue
 <script setup lang="ts">
-import { YhAiAttachments, YhAiBubble, YhAiSender, YhAiSources } from '@yh-ui/components'
+import { ref } from 'vue'
+import {
+  YhAiBubble,
+  YhAiSender,
+  YhAiThoughtChain,
+  YhAiMermaid,
+  YhAiCodeRunner
+} from '@yh-ui/components'
 import { useAIChat } from '@yh-ui/ai-sdk/vue'
 
+// Custom interface for message structures
+interface ChatMessage {
+  id: string
+  role: 'user' | 'assistant'
+  content: string
+  thinkingSteps?: Array<{ title: string; content: string; status: 'thinking' | 'done' }>
+  codeToRun?: string
+  mermaidSyntax?: string
+}
+
 const { messages, input, isLoading, sendMessage, stop } = useAIChat({
-  api: '/api/chat'
+  api: '/api/chat',
+  onResponse: () => console.log('Streaming response started')
 })
+
+const activeTab = ref<'chat' | 'runner'>('chat')
+const currentCode = ref('print("Hello from YH-UI AI!")')
 </script>
 
 <template>
-  <section class="chat-shell">
-    <YhAiBubble
-      v-for="message in messages"
-      :key="message.id"
-      :role="message.role"
-      :content="message.content"
-      :loading="message.status === 'loading'"
-      streaming
-    />
-
-    <YhAiSources v-if="messages.at(-1)?.sources?.length" :sources="messages.at(-1).sources" />
-    <YhAiAttachments
-      v-if="messages.at(-1)?.attachments?.length"
-      :items="messages.at(-1).attachments"
-    />
-
-    <YhAiSender v-model="input" :loading="isLoading" @send="sendMessage" @cancel="stop" />
-  </section>
+  <div class="ai-chat-layout">
+    <div class="chat-main">
+      <div class="message-feed">
+        <div v-for="msg in messages" :key="msg.id" class="message-row">
+          <!-- Render Reasoning Chain if available -->
+          <YhAiThoughtChain
+            v-if="msg.thinkingSteps && msg.thinkingSteps.length"
+            :items="msg.thinkingSteps"
+            title="Reasoning Chain"
+            auto-collapse
+          />
+
+          <!-- Main Message Bubble -->
+          <YhAiBubble
+            :role="msg.role"
+            :content="msg.content"
+            :markdown="true"
+            :enable-sanitizer="true"
+            streaming
+          />
+
+          <!-- Mermaid syntax parsed and rendered dynamically -->
+          <YhAiMermaid v-if="msg.mermaidSyntax" :code="msg.mermaidSyntax" class="mermaid-block" />
+
+          <!-- Live Python/JS execution if generated code block is present -->
+          <YhAiCodeRunner
+            v-if="msg.codeToRun"
+            :code="msg.codeToRun"
+            language="python"
+            autorun
+            class="runner-block"
+          />
+        </div>
+      </div>
+
+      <YhAiSender
+        v-model="input"
+        :loading="isLoading"
+        clearable
+        placeholder="Type a message or mention prompts using /..."
+        @send="sendMessage"
+        @cancel="stop"
+      />
+    </div>
+  </div>
 </template>
 ```
 
-## Security And UX Rules
+## Pattern: AI Server Configuration, Tracing & Safety Filters
+
+Configure standard LLM adapters, safety moderation filters, and telemetry tracers on the backend (`@yh-ui/ai-sdk`):
+
+```ts
+import { createProviderAdapter, createSafetyFilter, createTracer } from '@yh-ui/ai-sdk'
+
+// 1. Setup provider adapter (DeepSeek endpoint example)
+const provider = createProviderAdapter({
+  provider: 'deepseek',
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  defaultModel: 'deepseek-reasoner'
+})
+
+// 2. Setup safety and content guardrails
+const guardrail = createSafetyFilter({
+  blockHostileContent: true,
+  censorProfanity: true,
+  customBlockWords: ['private_token', 'db_password']
+})
+
+// 3. Setup telemetry and tracing
+const tracer = createTracer({
+  projectName: 'yh-ui-ai-ops',
+  serviceName: 'assistant-service'
+})
+
+export async function processAiRequest(prompt: string, history: any[]) {
+  // Check user input against safety filters
+  const scanResult = await guardrail.scanInput(prompt)
+  if (!scanResult.safe) {
+    throw new Error(`Input violated safety rules: ${scanResult.reason}`)
+  }
+
+  // Trace the LLM execution call
+  return await tracer.traceSpan('llm_generation', async () => {
+    const stream = await provider.chatStream([...history, { role: 'user', content: prompt }])
+
+    // Scan stream chunks to prevent secret leakage
+    return guardrail.pipeOutput(stream)
+  })
+}
+```
+
+## Agent Rules
 
-- Never expose provider keys through `VITE_*` env vars or browser code.
-- Treat model output as untrusted content; keep sanitizer enabled unless the server sanitizes output.
-- Do not display hidden chain-of-thought text. Use `YhAiThoughtChain` for explicit user-facing reasoning steps.
-- Use `YhAiSources` for citations and `YhAiArtifacts` for rich generated outputs.
-- Use `YhAiCodeBlock`, `YhAiCodeEditor`, and `YhAiCodeRunner` for code-centric responses instead of raw `<pre>` blocks when interaction matters.
+- **Client Sanitization**: Keep `:enable-sanitizer="true"` on `YhAiBubble` to ensure user inputs and raw markdown rendering cannot inject hostile scripts.
+- **Explicit Reasoning**: Never hide thinking logs inside ordinary paragraph text. Always use `YhAiThoughtChain` for models that output logical step arrays.
+- **Python Runtime URL**: When using python code execution in `YhAiCodeRunner`, ensure a valid Pyodide URL or remote execution API endpoint is supplied if defaults are disabled.
+- **API Secret Keys**: Never output provider secret API keys inside frontend environment variables (`VITE_`). Keep adapters configured strictly inside server endpoints.