<div align="center">
  <img src="https://img.alicdn.com/imgextra/i3/O1CN01X7B4kK1YXeKtEDpBZ_!!6000000003069-2-tps-720-720.png" align="center" width="100px">
  <h2> cn-domain-ai-table </h2>
  <h4>菜鸟 cn-ui 扩展（业务）组件｜<a href="https://code.alibaba-inc.com/cn-ui/cn-domain-ai-table">code 代码仓库</a>｜<a href="https://cone.cainiao-inc.com/dsm/cnui/material/pc/overview">cn-ui 文档</a></h4>
</div>

![](https://img.alicdn.com/imgextra/i1/O1CN01Zm0IZh1p3HY1qCQRl_!!6000000005304-2-tps-5336-3002.png)

<div style="font-size: 14px">
  <a href="#组件开发文档">组件开发</a>
  &nbsp;&nbsp;|&nbsp;&nbsp;
  <a href="#组件消费文档">组件消费</a>
  &nbsp;&nbsp;|&nbsp;&nbsp;
  <a href="#常见问题">常见问题</a>
  &nbsp;&nbsp;|&nbsp;&nbsp;
  <a href="#ai-功能验证-skill">AI 验证 Skill</a>
</div>

<span id="组件开发文档"/>

## 🛠 组件开发文档

### 🔗 参考文档

- [AGENTS.md](./AGENTS.md)：多编辑器可用的代理约定入口
- [AI 功能验证 Skill](./docs/agent-skills/ai-function-validation/SKILL.md)：cn-ai-table 外部 URL 回归与 case（与 Cursor 解耦，权威目录在 `docs/agent-skills/`）
- [组件开发指南](https://alidocs.dingtalk.com/i/nodes/QOG9lyrgJPPNL2rXIEzZ5e4EJzN67Mw4)
- [菜鸟前后端数据规约和二方包](https://alidocs.dingtalk.com/i/spaces/nb9XJLWldKNLaGyA/overview)
- [StoryBook 组件文档编写文档](https://storybook.js.org/docs/get-started/whats-a-story)

### 📔 组件目录

```shell
src
├── components // 组件文件夹
│   ├── cn-new-button
│   │   ├── index.ts # 单组件入口文件（默认）
│   │   ├── index-onecode-m.ts # 用于覆盖H5端展示，一般场景无须使用，双端差异化开发需要
│   │   ├── types // 组件类型件夹（如有）
│   │   │   ├── cn-new-button.ts
│   │   │   └── index.ts
│   │   └── view // 组件源码文件夹（如有）
│   │       ├── cn-new-button.scss
│   │       ├── cn-new-button.tsx
│   │       └── index.ts
│   └── index.ts // 组件入口文件夹（export所有组件）
├── locales // 组件国际化多语言文件夹（如有）
├── lowcode // 低码组件配置文件夹
├── plugins // 插件文件夹
├── stories // 组件文档文件夹
├── styles // 公共样式文件夹
├── tests // 单元测试文件夹
├── types // 公共类型定义文件夹
└── utils // 公共工具类文件夹
```

### 单组件目录规范

单个组件（如 `cn-input`）推荐按以下结构组织，可根据实际需要删减无用的文件夹（如无 hooks 可删除 `hooks` 等）：

```shell
src/components/cn-input
├── __tests__                 # 单测文件
│   └── index.test.tsx
├── styles                    # 定义组件变量、紧凑模式、主题等
│   ├── variable.scss         # 定义组件变量
│   ├── compact.scss          # 紧凑模式
│   ├── theme.scss            # 主题相关
│   └── index.ts
├── view                      # 所有 UI 相关的组件，复杂组件可再分子目录
│   ├── __tests__             # 单测文件
│   │   └── cn-input.test.ts
│   ├── cn-input.scss
│   ├── cn-input.tsx
│   └── index.ts
├── hooks                     # 组件 hooks，一个文件一个 hook，无则可删
│   ├── __tests__
│   │   └── a.test.ts
│   ├── a.ts
│   └── index.ts
├── utils                     # 组件工具，一个文件一个函数，无则可删
│   ├── __tests__
│   │   └── a.test.ts
│   ├── a.ts
│   └── index.ts
├── constants                  # 组件常量（无计算逻辑），一个文件一个常量，无则可删
│   ├── a.ts
│   └── index.ts
├── types
│   ├── cn-input-props.ts
│   └── index.ts
└── index.tsx
```

### ✨ 组件特性

- 依赖[菜鸟统一工程 cone-cli@1.x](https://alidocs.dingtalk.com/i/nodes/xdqZp24KneBJzvGM6XezJvyb7RA0Nr1E)
- 依赖组件库 `@cainiaofe/cn-ui@0.x`
- 符合菜鸟组件官方规范的业务组件大包，包含源码组件、低码组件、插件;
- 稳定性
  - ✅ TypeScript 语法
  - ✅ 单测覆盖
- 高级功能
  - ✅ CSS Token
  - ✅ panda 国际化
  - ✅ 一码多端
  - ✅ 低代码组件
  - ✅ 插件开发

### 💻 组件兼容性

参考 [CNUI 浏览器兼容范围详细说明](https://alidocs.dingtalk.com/i/nodes/G1DKw2zgV2KnvL4kFwXwy7aYJB5r9YAn)

### 🔨 组件开发

- 安装 cone-cli ｜ [Cone-CLI 使用指引](https://alidocs.dingtalk.com/i/nodes/xdqZp24KneBJzvGM6XezJvyb7RA0Nr1E)
  - `tnpm i -g @alife/cone-cli@latest`
- 拉取代码
  - `git clone git@gitlab.alibaba-inc.com:cn-ui/cn-domain-ai-table.git`
- 安装依赖包
  - `cone install`
- 启动一码多端研发 (storybook 文档) & 实时构建（用于代理研发）
  - `cone start`
- 新增组件(插件)
  - `cone add`
- 提交代码
  - `git add` | `git commit` | `git push`
- 打包构建
  - `cone build`
- 创建新迭代 ｜ [x.y.z 语义化版本控制规范](https://semver.org/lang/zh-CN/)
  - `cone create i`
    > PS: 创建迭代默认会从当前分支拉取新分支
- 国际化｜ [国际化多语言使用指引](https://alidocs.dingtalk.com/i/nodes/OmLa2Gg0l5BW7gL9gbx1WvQAdYbnKEek)
  - `cone i18n`

工具库 推荐使用 @cainiaofe/cn-utils

> @cainiaofe/cn-utils 文档请查阅：https://cone.cainiao-inc.com/dsm/v3/@ali/cn-utils/overview?version=0.2.7

使用参考

```jsx
import { urlParse } from '@cainiaofe/cn-utils';
```

### 📦 组件发布

- 日常发布
  - `cone pub -d`
    > PS: 如发布前未绑定需求，则有提示要求绑定需求按提示操作即可

- 线上发布
  - `cone pub -p`

<span id="组件消费文档"/>

## ✈️ 组件消费

> 【推荐】使用<a href="https://cone.cainiao-inc.com/console/index" target="_blank" >苏铁·低码平台</a>消费组件。 <br />
> 【必须】V3 工程组件默认支持一码多端能力，构建产物为 UMD 资源（不支持 esm、cjs），请通过浏览器直接引用 CDN 资源方式消费。 <br /> > <span style="color: red">【禁止】</span>请勿直接通过 tnpm install 使用本组件，会导致一码多端失效等其他副作用。

组件消费详细文档请在组件发布后 <a href="https://cone.cainiao-inc.com/dsm/v3/@alife/cn-domain-ai-table/overview" target="_blank"> DSM 平台查看</a>

### npm / 工程化（ESM · CJS，按需）

与 **Cone `cone build` 产出的根目录 UMD（CDN / 低码）**并行，本仓库另提供 **`es/`（ESM）**、**`lib/`（CommonJS）**：由 **`tsc` 按 `src/` 目录结构 emit**，产出与源码对应的 **可读 JS + 同路径 `.d.ts`**（不做压缩、不生成 `.map`）。`src/components` 下包会提升到 **`es/` / `lib/` 根下**（无 `components/` 这一层目录名）。**`./style.css`** 由 **sass** 从 `cn-ai-list-page.scss` 展开生成。类型入口见 **`package.json#types`**（`es/index.d.ts`）。与 `dist/` 下 UMD **并列、互不覆盖**。适用于自有 Webpack / Vite 等工程按 `package.json` 的 `exports` 解析依赖。

- **构建**：`npm run build:library` → `tsc` + `tsc-alias` + 资源同步与路径修正；`npm run build:npm` 仅执行 `build:library`。若仍需单独生成 **`dist/types`**（与 `es` 重复时非必须），可执行 `npm run build:types`。
- **入口**：与 UMD 主包一致为 **`src/components/index`** 的单入口聚合（阶段一为 barrel）；按需摇树依赖应用 bundler 与本包 **`sideEffects`**。
- **样式（业务须单独引入）**：列表页聚合样式见 **`package.json#exports["./style.css"]`**（与根入口 `index` 配套的展开 CSS）：
  - `import '@alife/cn-domain-ai-table/style.css'`（推荐）
- **对等依赖**：请安装 `react`、`react-dom`、`@cainiaofe/cn-ui`；`@cainiaofe/cn-utils` / `@ali/cn-utils` 为打包 external，按业务需要安装（`peerDependenciesMeta` 可选）。

> 低码 / 一码多端场景仍以 **CDN UMD** 为准；上表仅说明 **源码工程** 通过 npm 消费 **es / lib** 的契约。

<span id="ai-功能验证-skill"/>

## AI 功能验证 Skill

本仓库在 **`docs/agent-skills/ai-function-validation/`** 维护与编辑器无关的验证说明（外部 URL、case、报告模板）。任意 AI 助手或自动化环境只要读取该目录即可执行；约定入口见根目录 **[AGENTS.md](./AGENTS.md)**。Cursor 侧 `.cursor/skills/ai-function-validation/` 仅为跳转，避免重复维护。

<span id="常见问题"/>

## 常见问题

- 启动 https 证书 报错

1. 默认情况下，启动后需要手动信任 <https://localhost:9910> 和 <https://localhost:9911> 才能访问到组件构建的资源
2. 启动前通过 trusted-cert 自动生成了可信证书，如果碰到问题，可以通过以下方式重新生成 <https://anpm.alibaba-inc.com/package/trusted-cert>

```shell
# 删除本地已生成的密钥和证书，重新启动
npx trusted-cert uninstall

# 如果install过程中三次输入密码都错误了，还可以单独运行这个命令重新添加到系统钥匙串
npx trusted-cert trust
```

其他问题请查阅 https://alidocs.dingtalk.com/i/nodes/o14dA3GK8gQlkoYwc0eDzzZBV9ekBD76?utm_scene=team_space
