@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/issue/issue_26.3.1.6.md

@@ -0,0 +1,100 @@
+# Issue 26.3.1.6
+
+## 版本信息
+
+- **版本号**: 26.3.1.6
+- **基线版本**: 26.3.1
+- **类型**: Quality / Bug Fix
+- **日期**: 2026-07-02
+
+## 变更概述
+
+1. **CSS 自定义属性统一** — 将组件中使用的 CSS 自定义属性从旧命名规范迁移到新规范（`--aithe-duration-normal` → `--aithe-duration-base`/`--aithe-duration-slow`，`--aithe-container-radius` → `--aithe-container-radius-md`，`--aithe-border-radius-md` → `--aithe-radius-md`，`--aithe-font-mono` → `--aithe-font-family-mono`）
+2. **CSS 变量新增** — `global.css.ts` 新增 `--aithe-font-size-base`/`--aithe-font-size-3xl`/`--aithe-font-size-4xl`/`--aithe-font-size-5xl` 字体尺寸变量
+3. **主题系统增强** — 所有 24 个主题统一新增 `--aithe-fill-1`/`--aithe-fill-2`/`--aithe-color-surface-hover`/`--aithe-color-text-secondary`/`--aithe-color-bg-muted`/`--aithe-color-bg-hover`/`--aithe-color-border-subtle`/`--aithe-primary-6-rgb` 8 个 CSS 变量
+4. **`<aithe-desc>` 样式重构** — 移除 `desc-cell-label` 的 `padding`，改用 flex 居中；移除 `desc-item` 的 `padding`；`desc-cell-content` 的 `background` 移除回退值
+5. **`<aithe-mini-box>` 样式修复** — hover 背景色移除嵌套的 `--aithe-color-bg-hover` 回退
+6. **`<aithe-autoform-item>` 颜色修正** — `box-shadow` 中的 `--aithe-primary-6-rgb` 回退值从 `59, 130, 246` 改为 `77, 141, 255`
+7. **`<aithe-sidebar>` 导入增强** — 新增 `browserEnv` 导入
+8. **`<aithe-element>` JSDoc 更新** — 类注释补充浏览器环境检测说明
+9. **`AitheUI` 类增强** — 新增 `_ua` 私有字段和 10 个浏览器环境检测 getter（`isMobile`/`isAndroid`/`isIOS`/`isChrome`/`isEdge`/`isWechat`/`isWindows`/`isMacOS`/`isRealMobile`/`isChromeEmulator`/`supportsTouch`）
+
+## 破坏性变更
+
+无。
+
+## 变更内容
+
+### 新增
+
+#### 字体尺寸变量
+
+- **`src/styles/global.css.ts`** — 新增 `--aithe-font-size-base: 14px`、`--aithe-font-size-3xl: 32px`、`--aithe-font-size-4xl: 48px`、`--aithe-font-size-5xl: 64px` CSS 自定义属性
+
+#### 主题 CSS 变量统一
+
+- **`src/styles/theme/*.ts`（24 个主题）** — 每个主题统一新增 8 个 CSS 变量：
+  - `--aithe-fill-1` / `--aithe-fill-2`：填充色（浅色主题 `#f7f8fa`/`#f0f1f3`，深色主题 `#1a2133`/`#1e263a`）
+  - `--aithe-color-surface-hover`：表面悬停色（浅色 `rgba(0,0,0,0.04)`，深色 `rgba(255,255,255,0.04)`）
+  - `--aithe-color-text-secondary`：次要文本色（浅色 `#3d4a66`，深色 `#8894ab`）
+  - `--aithe-color-bg-muted`：背景静默色（浅色 `#e8ecf4`，深色 `#151c2b`）
+  - `--aithe-color-bg-hover`：背景悬停色（浅色 `rgba(0,0,0,0.04)`，深色 `rgba(255,255,255,0.04)`）
+  - `--aithe-color-border-subtle`：边框弱色（浅色 `rgba(76,94,132,0.10)`，深色 `rgba(172,188,217,0.08)`）
+  - `--aithe-primary-6-rgb`：主色 RGB 值（浅色 `77,141,255`，深色 `74,125,255`）
+
+#### `AitheUI` 浏览器环境检测
+
+- **`src/styles/aithe-ui.ts`** — 新增 `_ua` 私有字段（构造时缓存 `navigator.userAgent`）；新增 10 个 getter：
+  - `isMobile` — Android/iOS/WebOS/Blackberry
+  - `isAndroid` — Android
+  - `isIOS` — iPhone/iPad/iPod
+  - `isChrome` — Chrome（非 Edge）
+  - `isEdge` — Edge
+  - `isWechat` — 微信内置浏览器
+  - `isWindows` — Windows
+  - `isMacOS` — macOS
+  - `isRealMobile` — 真实移动设备（UA + 触摸 + 小屏幕 + 非桌面 OS）
+  - `isChromeEmulator` — Chrome DevTools 设备模拟
+  - `supportsTouch` — 触摸事件支持
+
+#### `<aithe-sidebar>` 导入
+
+- **`src/components/framework/sidebar.ts`** — 新增 `import { browserEnv } from '@utils'`
+
+### 修改
+
+#### CSS 自定义属性重命名
+
+- **`src/components/data/tree-menu.ts`** — `--aithe-duration-normal` → `--aithe-duration-base`
+- **`src/components/display/code-editor.ts`** — `--aithe-container-radius` → `--aithe-container-radius-md`
+- **`src/components/display/desc.ts`** — `--aithe-border-radius-md` → `--aithe-radius-md`（2 处）
+- **`src/components/display/markdown-editor.ts`** — `--aithe-container-radius` → `--aithe-container-radius-md`
+- **`src/components/display/markdown.ts`** — `--aithe-container-radius` → `--aithe-container-radius-md`
+- **`src/components/framework/dashboard-panel.ts`** — `--aithe-duration-normal` → `--aithe-duration-base`
+- **`src/components/framework/dashboard.ts`** — `--aithe-duration-normal` → `--aithe-duration-slow`（4 处面板过渡）、`--aithe-duration-normal` → `--aithe-duration-base`（4 处面板定位过渡）
+- **`src/components/framework/log-panel.ts`** — `--aithe-font-mono` → `--aithe-font-family-mono`
+- **`src/components/framework/sidebar.ts`** — `--aithe-duration-normal` → `--aithe-duration-base`
+
+#### `<aithe-desc>` 样式重构
+
+- **`src/components/display/desc.ts`** — `.desc-cell-label` 移除 `padding`，新增 `display: flex; align-items: center` 实现居中；`.desc-cell-content.is-bordered:hover` 的 `background` 移除 `#e8e9ed` 回退值
+
+#### `<aithe-desc-item>` 样式清理
+
+- **`src/components/display/desc-item.ts`** — `.item-label` 移除 `padding: var(--aithe-space-2, 8px) var(--aithe-space-3, 12px)`
+
+#### `<aithe-mini-box>` 样式修复
+
+- **`src/components/display/mini-box.ts`** — hover 背景色从 `var(--aithe-color-surface-hover, var(--aithe-color-bg-hover, rgba(0,0,0,0.02)))` 简化为 `var(--aithe-color-surface-hover, rgba(0,0,0,0.02))`
+
+#### `<aithe-autoform-item>` 颜色修正
+
+- **`src/components/form/autoform-item.ts`** — `box-shadow` 中 `--aithe-primary-6-rgb` 回退值从 `59, 130, 246` 修正为 `77, 141, 255`
+
+#### `<aithe-element>` JSDoc 更新
+
+- **`src/core/aithe-element.ts`** — 类注释补充"浏览器环境检测"说明
+
+### 删除
+
+无。

package/docs/issue/issue_26.3.1.7.md

@@ -0,0 +1,78 @@
+# Issue 26.3.1.7
+
+## 版本信息
+
+- **版本号**: 26.3.1.7
+- **基线版本**: 26.3.1
+- **类型**: Quality / Bug Fix
+- **日期**: 2026-08-06
+
+## 变更概述
+
+1. **DataHub 错误处理增强** — HTTP 非 2xx 错误响应优先用 APIStyle 解析响应体，提取业务错误信息（code/message），避免丢失后端返回的友好错误描述；`DataHubError` 新增 `data` 字段携带原始响应体
+2. **K8s APIStyle 错误响应支持** — `k8sStyle.onResponse` 新增对 K8s `Status` 对象（`{kind:"Status", status:"Failure", message, reason, code}`）的识别，正确解析非 2xx 错误响应的 `reason`/`message`
+3. **DataHub 导入路径规范化** — datahub 模块内 5 个文件的 `../` 跨目录相对路径导入统一改为 `@core/datahub/*` 别名导入，符合 `src/core/AGENTS.md` 规范
+4. **Filter 测试导入路径规范化** — `filter/__tests__/index.test.ts` 的相对路径导入改为 `@core/filter/*` 别名导入
+5. **SSR 环境适配** — `<aithe-log-panel>`、`<aithe-affix>`、`<aithe-back-top>`、`<aithe-theme-switch>` 4 个组件的 `window` 引用改为 `globalThis`，兼容非浏览器环境
+6. **API 文档补充** — 新增 `<aithe-log-panel>`、`<aithe-desc-item>`、`<aithe-autoform-item>` 3 个组件的 API 文档；更新 `summary.md` 索引
+
+## 破坏性变更
+
+无。
+
+## 变更内容
+
+### 新增
+
+#### API 文档
+
+- **`docs/api/framework/log-panel.md`** — 新增 `<aithe-log-panel>` 组件 API 文档
+- **`docs/api/display/desc-item.md`** — 新增 `<aithe-desc-item>` 组件 API 文档
+- **`docs/api/form/autoform-item.md`** — 新增 `<aithe-autoform-item>` 组件 API 文档
+
+#### DataHub 类型字段
+
+- **`src/core/datahub/types.ts`** — `DataHubErrorDetail` 接口新增 `data?: unknown` 字段（原始响应体）；`DataHubError` 类新增 `data?: unknown` 只读属性，构造函数同步赋值
+
+### 修改
+
+#### DataHub 错误处理增强
+
+- **`src/core/datahub/core/datahub-core.ts`** — HTTP 非 2xx 错误处理逻辑优化：`!res.ok` 时优先调用 `requestStyle.onResponse` 解析响应体，提取业务 `code`/`message` 后抛出 `DataHubError`；无 APIStyle 时回退到 `createTransportError`。复用 `:217` 已计算的 `requestStyle`，消除 `resolveRequestStyle` 重复调用
+- **`src/core/datahub/core/datahub-core.ts`** — `createTransportError` 方法补充 `data: res.data`，与错误路径保持一致
+- **`src/core/datahub/core/api-styles.ts`** — `k8sStyle.onResponse` 新增 K8s `Status` 错误对象识别：当 `!res.ok && typeof obj.status === 'string'` 时，返回 `{code: obj.reason ?? obj.status, message: obj.message, data: rawData}`，精确区分错误响应（顶层 `status` 为字符串）与正常响应（`status` 为对象）
+
+#### DataHub 导入路径规范化
+
+- **`src/core/datahub/core/adapter/fetch-adapter.ts`** — `../../types` → `@core/datahub/types`
+- **`src/core/datahub/core/adapter/mock-adapter.ts`** — `../../types` → `@core/datahub/types`
+- **`src/core/datahub/core/api-styles.ts`** — `../types` → `@core/datahub/types`
+- **`src/core/datahub/core/datahub-core.ts`** — `../types`、`../config/strategy`、`../utils/*` → `@core/datahub/types`、`@core/datahub/config/strategy`、`@core/datahub/utils/*`（同目录的 `./api-styles`、`./adapter/*` 保持不变）
+- **`src/core/datahub/config/strategy.ts`** — `../types`、`../utils/is-query` → `@core/datahub/types`、`@core/datahub/utils/is-query`
+- **`src/core/datahub/utils/idempotent.ts`** — `../types` → `@core/datahub/types`（同目录的 `./common` 保持不变）
+
+#### Filter 测试导入路径规范化
+
+- **`src/core/filter/__tests__/index.test.ts`** — `../types`、`../builtins`、`../factory`、`../index` → `@core/filter/types`、`@core/filter/builtins`、`@core/filter/factory`、`@core/filter/index`
+
+#### SSR 环境适配
+
+- **`src/components/framework/log-panel.ts`** — `window.innerHeight` → `globalThis.innerHeight`
+- **`src/components/layout/affix.ts`** — `window.addEventListener/removeEventListener('resize'/'scroll')` → `globalThis.addEventListener/removeEventListener`
+- **`src/components/navigation/back-top.ts`** — `window.scrollY`、`window.scrollTo` → `globalThis.scrollY`、`globalThis.scrollTo`
+- **`src/components/theme/theme-switch.ts`** — `window.addEventListener/removeEventListener('resize'/'scroll')` → `globalThis.addEventListener/removeEventListener`
+
+#### API 文档更新
+
+- **`docs/api/summary.md`** — 索引表新增 `<aithe-log-panel>` 行；表格列宽对齐调整
+- **`docs/api/basic/tag.md`** — 文档内容更新
+- **`docs/api/data/table.md`** — 文档内容更新
+- **`docs/api/data/table-column.md`** — 文档内容更新
+- **`docs/api/feedback/popover.md`** — 文档内容更新
+- **`docs/api/feedback/tooltip.md`** — 文档内容更新
+- **`docs/api/form/select.md`** — 文档内容更新
+- **`docs/quickstart.md`** — 文档内容更新
+
+### 删除
+
+无。

package/docs/markdown.md

@@ -0,0 +1,432 @@
+# Markdown 模块 / Markdown Module
+
+Aithe UI 内置零依赖的 Markdown 解析与渲染引擎，采用插件架构设计，提供从轻量标签到完整文档渲染的全链路支持。
+
+## 架构概览 / Architecture Overview
+
+```bash
+┌─────────────────────────────────────────────────────┐
+│                    Components                        │
+│  ┌──────────┐  ┌──────────────┐  ┌────────────────┐ │
+│  │ AitheLabel│  │ AitheMarkdown│  │AitheMarkdownEditor││
+│  │ (行内子集)│  │ (完整 GFM)   │  │ (编辑器+预览)    ││
+│  └─────┬────┘  └──────┬───────┘  └───────┬────────┘ │
+└────────┼──────────────┼──────────────────┼──────────┘
+         │              │                  │
+┌────────▼──────────────▼──────────────────▼──────────┐
+│                    Parsers                            │
+│  ┌──────────────────┐  ┌──────────────────────────┐  │
+│  │SimpleMarkdownParser│  │  FullMarkdownParser      │  │
+│  │ (6 plugins)       │  │  (16 plugins)            │  │
+│  └────────┬─────────┘  └───────────┬──────────────┘  │
+│           │                        │                  │
+│           └──────────┬─────────────┘                  │
+│                 ┌────▼────┐                           │
+│                 │MarkdownParser (基类)│                 │
+│                 └────┬────┘                           │
+└──────────────────────┼──────────────────────────────┘
+                       │
+┌──────────────────────▼──────────────────────────────┐
+│                    Plugins                            │
+│  bold  italic  code  del  link  image  heading        │
+│  table  codeFence  list  taskList  blockquote         │
+│  emoji  icon  setextHeading  thematicBreak            │
+└─────────────────────────────────────────────────────┘
+```
+
+### 核心模块文件 / Core Files
+
+| 文件                           | 说明                                                                         |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `src/core/markdown/parser.ts`  | 解析器基类 `MarkdownParser`，及 `SimpleMarkdownParser`、`FullMarkdownParser` |
+| `src/core/markdown/plugins.ts` | 所有内置插件定义（16 个 AST 插件 + emoji 映射表）                            |
+| `src/core/markdown/types.ts`   | `AstNode`、`AstPlugin`、`MarkdownLinkHook` 类型定义                          |
+| `src/core/markdown/index.ts`   | 模块统一导出入口                                                             |
+
+---
+
+## MarkdownParser — 解析器基类
+
+`MarkdownParser` 是一个基于 AST（抽象语法树）的 Markdown → HTML 转换器，采用两阶段解析架构（块级 → 行内），零外部依赖。
+
+### 构造函数
+
+```ts
+new MarkdownParser();
+```
+
+### 方法
+
+| 方法             | 签名                                 | 说明                              |
+| ---------------- | ------------------------------------ | --------------------------------- |
+| `use`            | `(plugin: AstPlugin) => this`        | 注册一个 AST 插件，支持链式调用   |
+| `addLinkHook`    | `(hook: MarkdownLinkHook) => this`   | 添加链接处理 hook，支持链式调用   |
+| `removeLinkHook` | `(hook: MarkdownLinkHook) => this`   | 移除指定的链接处理 hook           |
+| `parse`          | `(markdown: string) => string`       | 将 Markdown 文本转换为 HTML       |
+| `parseToAst`     | `(markdown: string) => DocumentNode` | 将 Markdown 文本解析为 AST 文档树 |
+
+### 解析流程
+
+`parse()` 方法内部按以下阶段顺序处理：
+
+1. **块级解析** — 遍历行数组，依次尝试各块级插件（标题、代码块、表格、引用、列表等），匹配则消费对应行并生成块级 AST 节点
+2. **段落处理** — 未被块级插件覆盖的连续文本，收集为段落节点，内部递归执行行内解析
+3. **行内解析** — 对段落文本，依次尝试各行内插件（加粗、斜体、链接等），生成行内 AST 节点
+4. **AST → HTML** — 遍历完整 AST 文档树，渲染器将各节点类型转换为对应 HTML 标签
+5. **链接 Hook** — 渲染 `link` 节点时，依次调用注册的 `linkHook`，返回空字符串则降级为纯文本
+
+### 基本用法
+
+```ts
+import { MarkdownParser, plugins } from '@core/markdown';
+
+const parser = new MarkdownParser()
+  .use(plugins.boldPlugin)
+  .use(plugins.codePlugin)
+  .use(plugins.linkPlugin);
+
+parser.parse('**bold** and `code`');
+// → '<strong class="md-strong">bold</strong> and <code class="md-code">code</code>'
+```
+
+---
+
+## SimpleMarkdownParser — 简易解析器
+
+适用于标签、描述、表单提示等轻量场景。仅支持行内语法，不处理块级结构。
+
+### 注册的插件（6 个）
+
+| 顺序 | 插件          | 语法          | 输出                         |
+| ---- | ------------- | ------------- | ---------------------------- |
+| 1    | `boldPlugin`  | `**text**`    | `<strong class="md-strong">` |
+| 2    | `codePlugin`  | `` `code` ``  | `<code class="md-code">`     |
+| 3    | `delPlugin`   | `~~text~~`    | `<del class="md-del">`       |
+| 4    | `linkPlugin`  | `[text](url)` | `<a class="md-link">`        |
+| 5    | `emojiPlugin` | `:smile:`     | Unicode Emoji                |
+| 6    | `iconPlugin`  | `:iconName:`  | `<aithe-icon>`               |
+
+### 构造函数
+
+```ts
+new SimpleMarkdownParser();
+```
+
+### 链接处理
+
+使用 `addLinkHook()` 方法注册链接处理 hook。默认行为：外部链接（http/https/ftp/绝对路径）转为纯文本。
+
+```ts
+import { SimpleMarkdownParser } from '@core/markdown';
+
+const parser = new SimpleMarkdownParser();
+parser.addLinkHook((url) => (url.startsWith('/') ? url : ''));
+parser.parse('[internal](/page) [external](https://example.com)');
+// → '<a class="md-link" href="/page">internal</a> external'
+```
+
+### 使用示例
+
+```ts
+import { SimpleMarkdownParser } from '@core/markdown';
+
+const parser = new SimpleMarkdownParser();
+parser.parse('**Bold** ~~strike~~ `code` :smile:');
+// → '<strong class="md-strong">Bold</strong> <del class="md-del">strike</del> <code class="md-code">code</code> 😄'
+```
+
+---
+
+## FullMarkdownParser — 完整解析器
+
+适用于文档渲染、文章展示等富文本场景。支持 GFM（GitHub Flavored Markdown）全语法。
+
+### 注册的插件（16 个）
+
+**Leaf blocks / 叶子块：**
+
+| 顺序 | 插件                  | 语法                    | 输出                                        |
+| ---- | --------------------- | ----------------------- | ------------------------------------------- |
+| 1    | `codeFencePlugin`     | `` ```lang````` / `~~~` | `<aithe-code-editor class="md-code-fence">` |
+| 2    | `setextHeadingPlugin` | `Title\n===`            | `<h1>` / `<h2>`                             |
+| 3    | `headingPlugin`       | `# ` ~ `###### `        | `<h1>` ~ `<h6>`                             |
+| 4    | `thematicBreakPlugin` | `---` / `***` / `___`   | `<hr class="md-hr">`                        |
+| 5    | `tablePlugin`         | `\| col1 \| col2 \|`    | `<table class="md-table">`                  |
+
+**Container blocks / 容器块：**
+
+| 顺序 | 插件               | 语法                 | 输出                                 |
+| ---- | ------------------ | -------------------- | ------------------------------------ |
+| 6    | `blockquotePlugin` | `> text`             | `<blockquote class="md-blockquote">` |
+| 7    | `taskListPlugin`   | `- [ ]` / `- [x]`    | `<li><input type="checkbox">`        |
+| 8    | `listPlugin`       | `- item` / `1. item` | `<li class="md-li">`                 |
+
+**Inlines / 行内：**
+
+| 顺序 | 插件           | 语法                | 输出                         |
+| ---- | -------------- | ------------------- | ---------------------------- |
+| 9    | `imagePlugin`  | `![alt](url)`       | `<img class="md-image">`     |
+| 10   | `linkPlugin`   | `[text](url)`       | `<a class="md-link">`        |
+| 11   | `boldPlugin`   | `**text**`          | `<strong class="md-strong">` |
+| 12   | `italicPlugin` | `*text*` / `_text_` | `<em class="md-em">`         |
+| 13   | `codePlugin`   | `` `code` ``        | `<code class="md-code">`     |
+| 14   | `delPlugin`    | `~~text~~`          | `<del class="md-del">`       |
+| 15   | `emojiPlugin`  | `:smile:`           | Unicode Emoji                |
+| 16   | `iconPlugin`   | `:iconName:`        | `<aithe-icon>`               |
+
+### 构造函数
+
+```ts
+new FullMarkdownParser();
+```
+
+### 链接处理
+
+使用 `addLinkHook()` 方法注册链接处理 hook。默认行为：外部链接（http/https/ftp/绝对路径）转为纯文本。
+
+```ts
+import { FullMarkdownParser } from '@core/markdown';
+
+const parser = new FullMarkdownParser();
+parser.addLinkHook((url) => (url.startsWith('/') ? url : ''));
+parser.parse('[internal](/page) [external](https://example.com)');
+// → '<a class="md-link" href="/page">internal</a> external'
+```
+
+### 使用示例
+
+```ts
+import { FullMarkdownParser } from '@core/markdown';
+
+const parser = new FullMarkdownParser();
+parser.parse(`# Hello\n\n**Bold** and \`code\`.`);
+// → '<h1 class="md-heading">Hello</h1><p class="md-p"><strong class="md-strong">Bold</strong> and <code class="md-code">code</code>.</p>'
+```
+
+---
+
+## 插件系统 / Plugin System
+
+### AstPlugin 接口
+
+```ts
+interface AstPlugin {
+  name: string; // 插件唯一标识
+  block?: BlockParser; // 块级解析器（接收行数组，返回块级节点列表）
+  inline?: InlineParser; // 行内解析器（接收文本，返回行内节点列表）
+}
+
+type BlockParser = (lines: string[]) => { nodes: AstNode[]; consumed: number } | null;
+
+type InlineParser = (text: string) => { nodes: AstNode[]; consumed: number } | null;
+```
+
+- `name` — 插件唯一标识，用于调试和日志
+- `block` — 块级解析器函数，接收从当前位置开始的剩余行数组，返回解析出的 AST 节点列表和消费的行数；返回 `null` 表示不匹配
+- `inline` — 行内解析器函数，接收从当前位置开始的剩余文本，返回解析出的 AST 节点列表和消费的字符数；返回 `null` 表示不匹配
+- 一个插件可同时提供 `block` 和 `inline` 解析器（如 `linkPlugin`）
+
+### MarkdownLinkHook 类型
+
+```ts
+type MarkdownLinkHook = (url: string, text: string) => string | undefined | null;
+```
+
+- 返回 `string` 时，使用该返回值作为最终 URL
+- 返回 `undefined` 或 `null` 时，传递给下一个 hook
+- 所有 hook 均返回 `undefined` 时，使用原始 URL
+- 返回空字符串时，链接被阻止，仅显示文本
+
+### 内置插件列表
+
+| 导出名                | name               | block | 说明                         |
+| --------------------- | ------------------ | ----- | ---------------------------- |
+| `headingPlugin`       | `'heading'`        | ✅    | ATX 标题 `#` ~ `######`      |
+| `setextHeadingPlugin` | `'setext-heading'` | ✅    | Setext 标题 `===` / `---`    |
+| `thematicBreakPlugin` | `'thematic-break'` | ✅    | 分隔线 `---` / `***` / `___` |
+| `codeFencePlugin`     | `'code-fence'`     | ✅    | 围栏代码块 ` ``` ` / `~~~`   |
+| `tablePlugin`         | `'table'`          | ✅    | GFM 表格                     |
+| `blockquotePlugin`    | `'blockquote'`     | ✅    | 引用块 `>`                   |
+| `listPlugin`          | `'list'`           | ✅    | 无序/有序列表                |
+| `taskListPlugin`      | `'task-list'`      | ✅    | 任务列表 `- [ ]` / `- [x]`   |
+| `boldPlugin`          | `'bold'`           | ❌    | 加粗 `**text**`              |
+| `italicPlugin`        | `'italic'`         | ❌    | 斜体 `*text*` / `_text_`     |
+| `codePlugin`          | `'code'`           | ❌    | 行内代码 `` `code` ``        |
+| `delPlugin`           | `'delete'`         | ❌    | 删除线 `~~text~~`            |
+| `linkPlugin`          | `'link'`           | ❌    | 链接 `[text](url)`           |
+| `imagePlugin`         | `'image'`          | ❌    | 图片 `![alt](url)`           |
+| `emojiPlugin`         | `'emoji'`          | ❌    | Emoji 短代码 `:smile:`       |
+| `iconPlugin`          | `'icon'`           | ❌    | Aithe 图标 `:iconName:`      |
+
+### 自定义插件
+
+```ts
+import { MarkdownParser, type AstPlugin } from '@core/markdown';
+
+const highlightPlugin: AstPlugin = {
+  name: 'highlight',
+  inline(text: string) {
+    const match = text.match(/^==(.+?)==/);
+    if (!match) return null;
+    return {
+      nodes: [{ type: 'text', value: match[1] }],
+      consumed: match[0].length,
+    };
+  },
+};
+
+const parser = new MarkdownParser().use(highlightPlugin);
+
+parser.parse('==highlighted==');
+// → 'highlighted'
+```
+
+### 自定义 link hooks
+
+```ts
+import { FullMarkdownParser } from '@core/markdown';
+
+// 只允许内部链接，外部链接转为纯文本
+const parser = new FullMarkdownParser();
+parser.addLinkHook((url) => (url.startsWith('/') ? url : ''));
+
+parser.parse('[internal](/page) [external](https://evil.com)');
+// → '<a class="md-link" href="/page">internal</a> external'
+```
+
+---
+
+## Emoji 支持 / Emoji Support
+
+内置 50+ 常用 Emoji 短代码映射。命名风格参考 GitHub Flavored Markdown 约定。
+
+| 短代码       | 结果 | 短代码      | 结果 | 短代码         | 结果 |
+| ------------ | ---- | ----------- | ---- | -------------- | ---- |
+| `:smile:`    | 😄   | `:wink:`    | 😉   | `:heart_eyes:` | 😍   |
+| `:thumbsup:` | 👍   | `:fire:`    | 🔥   | `:rocket:`     | 🚀   |
+| `:check:`    | ✅   | `:warning:` | ⚠️   | `:heart:`      | ❤️   |
+| `:star:`     | ⭐   | `:bug:`     | 🐛   | `:trophy:`     | 🏆   |
+
+> 完整映射表见 `src/core/markdown/plugins.ts` 的 `EMOJI_MAP` 常量。
+
+### Emoji 与图标插件的区分
+
+| 插件          | 匹配模式             | 示例                | 输出           |
+| ------------- | -------------------- | ------------------- | -------------- |
+| `emojiPlugin` | `:[a-z_][a-z0-9_]*:` | `:smile:` `:check:` | Unicode Emoji  |
+| `iconPlugin`  | `:[a-zA-Z]\w*:`      | `:Home:` `:Search:` | `<aithe-icon>` |
+
+两者互不冲突，emojiPlugin 优先注册，先处理小写短代码。
+
+---
+
+## 代码块渲染 / Code Block Rendering
+
+围栏代码块（` ``` ` / `~~~`）被渲染为 `<aithe-code-editor>` 组件，自带语法高亮、行号、工具栏、主题选择器、复制按钮。
+
+### 语言别名映射
+
+代码块的语言标识支持常用别名，自动映射为标准语言 ID：
+
+| 别名                | 标准 ID             | 别名               | 标准 ID | 别名 | 标准 ID |
+| ------------------- | ------------------- | ------------------ | ------- | ---- | ------- |
+| `ts` → `typescript` | `js` → `javascript` | `py` → `python`    |
+| `rb` → `ruby`       | `sh` → `bash`       | `yml` → `yaml`     |
+| `md` → `markdown`   | `rs` → `rust`       | `kt` → `kotlin`    |
+| `jsx` → `jsx`       | `tsx` → `tsx`       | `m` → `objectivec` |
+| `h` → `c`           | `hpp` → `cpp`       | `tex` → `latex`    |
+
+### 示例
+
+````markdown
+```ts
+const greeting: string = 'Hello';
+```
+````
+
+渲染结果：
+
+```html
+<aithe-code-editor
+  readonly
+  show-toolbar
+  show-theme
+  value="..."
+  language="typescript"
+  class="md-code-fence"
+></aithe-code-editor>
+```
+
+## 安全机制 / Security
+
+### XSS 防护
+
+- 解析过程中的 HTML 转义阶段，将 `& < > "` 转义为实体编码
+- 代码块内容在插件内部额外转义了 `` ` * _ ~ [ ] ( ) ! `` 等 Markdown 语法字符
+- 输出通过 `unsafeHTML` directive 注入 DOM（组件层负责使用 `unsafeHTML`）
+
+### 外部链接防护
+
+默认情况下，所有外部链接（http/https/ftp/绝对路径）被阻止，仅显示链接文本。通过 `linkHooks` 可自定义策略。
+
+### ReDoS 防护
+
+所有内置正则表达式均添加了长度限制（`{0,200}`、`{1,500}` 等），防止恶意构造的长文本导致正则表达式拒绝服务。
+
+---
+
+## 组件层 / Component Layer
+
+### AitheLabel
+
+使用 `SimpleMarkdownParser`，用于标签、描述、表单提示等轻量场景。
+
+```html
+<aithe-label content="**Bold** and `code` :smile:"></aithe-label>
+```
+
+| 属性        | 类型                 | 说明                |
+| ----------- | -------------------- | ------------------- |
+| `content`   | `string`             | Markdown 源文本     |
+| `linkHooks` | `MarkdownLinkHook[]` | 自定义链接处理 hook |
+
+> 完整文档见 [AitheLabel API](api/display/label.md)
+
+### AitheMarkdown
+
+使用 `FullMarkdownParser`，用于文档渲染、文章展示等富文本场景。
+
+```html
+<aithe-markdown content="# Hello\n**Bold** text and `code`."></aithe-markdown>
+```
+
+| 属性        | 类型                 | 默认值 | 说明                |
+| ----------- | -------------------- | ------ | ------------------- |
+| `content`   | `string`             | `''`   | Markdown 源文本     |
+| `linkHooks` | `MarkdownLinkHook[]` | —      | 自定义链接处理 hook |
+
+> 完整文档见 [AitheMarkdown API](api/display/markdown.md)
+
+### AitheMarkdownEditor
+
+基于 `aithe-code-editor` 封装的 Markdown 编辑器，语言固定为 `"markdown"`，集成实时预览。
+
+```html
+<aithe-markdown-editor value="# Hello" show-toolbar></aithe-markdown-editor>
+```
+
+| 属性              | 类型                              | 默认值   | 说明            |
+| ----------------- | --------------------------------- | -------- | --------------- |
+| `value`           | `string`                          | `''`     | Markdown 源文本 |
+| `previewStrategy` | `'auto' \| PreviewStrategyConfig` | `'auto'` | 预览刷新策略    |
+
+#### 预览策略 / Preview Strategy
+
+```ts
+interface PreviewStrategyConfig {
+  changeCount?: number; // 每 N 次变更后刷新
+  updateSeconds?: number; // 每 N 秒最多刷新一次
+}
+```
+
+> 完整文档见 [AitheMarkdownEditor API](api/display/markdown-editor.md)