11-02 · 约定驱动开发：AGENTS.md 即规范

# AGENTS.md:1-4

---
description: 
alwaysApply: true
---

# AGENTS.md:8-15

## 通用要求

- 每次回答使用中文。
- 接到新任务时，先用自己的理解复述目标；如果问题有歧义或关键信息缺失，先向用户确认，不要盲目修改。
- 优先通过读取仓库上下文后再动手修改，不要先入为主。
- 任务适合并行探索、验证或定点修改时，优先使用子代理；不适合的任务不要强行拆分。
- 搜索文件或文本优先使用 `rg`。
- 不要覆盖或回退用户未明确要求处理的改动。

# AGENTS.md:17-28（全文）

## 代码约定

- 组件目录统一放在 `packages/components/<name>`，通常包含 `index.ts`、`src/`、`__tests__/`。
- 组件命名统一以 kebab-case 主名为准，例如 `button`、`form-item`、`time-picker`、`input-number`。
- TypeScript 中使用对应的 PascalCase 标识符，例如 `XyButton`、`XyFormItem`、`XyTimePicker`。
- Vue 模板、文档示例、测试模板中的组件标签统一使用 `xy-button`、`xy-form-item`、`xy-time-picker` 这类 kebab-case。
- 新增或修改组件时，除源码外，优先同步检查这些入口是否需要更新：
  - `packages/components/component-manifest.ts`
  - `packages/components/index.ts`
  - `packages/theme/index.css`
- 组件清单、文档侧边栏、聚合安装断言和一致性校验以 `packages/components/component-manifest.ts` 为主源，避免多处手工同步。
- 修改组件相关逻辑后，优先补齐或更新对应单测；如果组件有类型导出或安装入口变化，也要检查 `tests/types/fixtures` 中对应夹具。

// scripts/check-components.mjs:83-126（节选自六组 mismatch 定义）
const mismatches = [
  {
    message: "组件目录与 manifest 不一致：",
    values: [
      ...diff(componentNames, componentDirs),
      ...diff(componentDirs, componentNames).map((name) => `${name} (多余目录)`)
    ]
  },
  {
    message: "导出入口与 manifest 不一致：",
    values: [
      ...diff(componentNames, exportedComponentNames),
      ...diff(exportedComponentNames, componentNames).map((name) => `${name} (多余导出)`)
    ]
  },
  {
    message: "组件文档与 manifest 不一致：",
    values: [
      ...diff(componentNames, docComponentNames),
      ...diff(docComponentNames, componentNames).map((name) => `${name} (多余文档)`)
    ]
  },
  {
    message: "类型夹具与 manifest 不一致：",
    values: [
      ...diff(componentNames, typeFixtureNames),
      ...diff(typeFixtureNames, componentNames).map((name) => `${name} (多余夹具)`)
    ]
  },
  {
    message: "组件单测与 manifest 不一致：",
    values: [
      ...diff(componentNames, unitTestNames),
      ...diff(unitTestNames, componentNames).map((name) => `${name} (多余单测目录)`)
    ]
  },
  {
    message: "样式入口与 manifest 不一致：",
    values: [
      ...diff(styleNames, themeImportNames),
      ...diff(themeImportNames, styleNames).map((name) => `${name} (多余样式导入)`)
    ]
  }
];

# .github/workflows/ci.yml:21-26
      - run: pnpm check:components
      - run: pnpm lint
      - run: pnpm typecheck
      # CI runner 内存有限，文件级并行曾致 OOM flaky（同一提交在 Release job 中全部通过）
      - run: pnpm test -- --no-file-parallelism
      - run: pnpm build

# AGENTS.md:30-54（全文，23 条）

## 增强层导出规则

- 增强组件源码统一位于 `packages/pro-components/<name>`，并通过 `packages/pro-components/component-manifest.json` 维护正式公开增强组件清单。
- 新增或修改增强组件时，优先同步检查这些入口是否需要更新：
  - `packages/pro-components/component-manifest.json`
  - `packages/pro-components/exports.ts`
  - `packages/pro-components/index.ts`
  - `packages/pro-components/style.css`
  - `tests/types/fixtures/xiaoye-pro-components.ts`
  - `tests/types/fixtures/pro-root-boundary.ts`
  - `scripts/check-pro-components.mjs`
- `packages/pro-components/exports.ts` 只允许显式导出正式公开增强组件值，例如 `XyProTable`、`XyListPage`；不要在这里使用 `export *`，也不要把组件类型从这里抛到包根。
- `packages/pro-components/index.ts` 是增强层根入口白名单：
  - 只允许导出正式公开增强组件值。
  - 类型只允许导出每个公开增强组件的主 `Props / Instance / 主数据类型`，以及 `core.ts` 里的稳定共享协议类型。
  - 插槽入参、事件载荷、组件内部状态枚举、props 字面量联合、对共享类型的业务别名，默认不应出现在根入口。
- 如果某个类型只适合组件子入口使用，应保留在 `packages/pro-components/<name>/index.ts` 或源码内部，不要再把它抬到 `xiaoye-pro-components`（`packages/pro-components/index.ts`）根入口。
- 旧兼容类型如果必须保留，应只保留在源码层，并显式标注 `@deprecated`；默认不要继续从组件 `index.ts` 或包根对外导出。
- 增强层根入口边界由两层守卫共同维护：
  - `scripts/check-pro-components.mjs` 会校验组件值导出白名单和根入口类型白名单。
  - `tests/types/fixtures/pro-root-boundary.ts` 会校验一批已降级的细节类型无法再从根入口导入。
- 修改增强层公开导出后，至少补跑：
  - `pnpm check:pro-components`
  - `pnpm typecheck:types`
  - 视影响范围再补 `pnpm typecheck:packages`、`pnpm build:docs`、`pnpm build:lib`

// scripts/check-pro-components.mjs:10-75（rootTypeWhitelist 全文）
const rootTypeWhitelist = {
  "search-form": ["SearchFormField", "SearchFormInstance", "SearchFormProps"],
  "pro-form": ["ProFormInstance", "ProFormProps"],
  "overlay-form": ["OverlayFormInstance", "OverlayFormProps", "OverlayFormSubmitPayload"],
  "dialog-form": ["DialogFormInstance", "DialogFormProps", "DialogFormSubmitPayload"],
  "drawer-form": ["DrawerFormInstance", "DrawerFormProps", "DrawerFormSubmitPayload"],
  "steps-form": ["StepsFormInstance", "StepsFormProps", "StepsFormStep"],
  "filter-panel": ["FilterPanelProps"],
  "request-form": ["RequestFormProps", "RequestFormSubmitContext"],
  "login-form": [
    "LoginFormInstance",
    "LoginFormModel",
    "LoginFormProps",
    "LoginFormThirdPartyItem"
  ],
  "page-toolbar": ["PageToolbarProps"],
  "page-header": ["PageHeaderProps", "PageIcon", "PageMetaItem"],
  "page-container": ["PageContainerProps"],
  "avatar-menu": ["AvatarMenuCommand", "AvatarMenuItem", "AvatarMenuProps"],
  "pro-table": ["ProTableColumn", "ProTableInstance", "ProTableProps"],
  "header-tabs": ["HeaderTabItem", "HeaderTabsMenuAction", "HeaderTabsProps"],
  "notice-center": [
    "NoticeCenterAction",
    "NoticeCenterItem",
    "NoticeCenterProps",
    "NoticeCenterTab"
  ],
  "stat-card": ["StatCardProps", "StatTrend"],
  "column-setting-panel": ["ColumnSettingPanelColumn", "ColumnSettingPanelProps"],
  "saved-view-tabs": ["SavedViewTabItem", "SavedViewTabsProps"],
  "table-filter-drawer": ["TableFilterDrawerProps"],
  "import-result-table": ["ImportResultSummary", "ImportResultTableProps"],
  "audit-timeline": ["AuditTimelineAttachment", "AuditTimelineEntry", "AuditTimelineProps"],
  "detail-panel": ["DetailPanelInstance", "DetailPanelProps"],
  "detail-page": [
    "DetailPageAction",
    "DetailPageAttachmentFile",
    "DetailPageBreadcrumbItem",
    "DetailPageProps"
  ],
  "async-state-container": ["AsyncStateContainerProps"],
  "list-page": ["ListPageActionRef", "ListPageBatchAction", "ListPageProps"],
  "crud-page": ["CrudPageProps"],
  "split-layout-page": ["SplitLayoutPageProps"],
  "approval-flow-panel": ["ApprovalFlowNode", "ApprovalFlowPanelProps"],
  "import-wizard": ["ImportWizardProps", "ImportWizardStep"],
  "export-task-panel": ["ExportTaskItem", "ExportTaskPanelProps"],
  core: [
    "ProDisplayFormatter",
    "ProDisplayHtmlRenderer",
    "ProDisplayOption",
    "ProDisplayOptionGroup",
    "ProDisplayRenderContext",
    "ProDisplayRenderer",
    "ProDisplayValueType",
    "ProActionRef",
    "ProFieldSchema",
    "ProFieldSchemaBuiltinComponent",
    "ProFieldSchemaOption",
    "ProPageAction",
    "ProRequestActionRef",
    "ProRequestContext",
    "ProRequestData",
    "ProRequestResult"
  ]
};

// scripts/check-pro-components.mjs:319-331
  {
    message: "增强根入口类型白名单与约定不一致：",
    values: diffNamedExportMap(rootTypeWhitelist, rootTypeExports)
  }
];

mismatches
  .filter((entry) => entry.values.length > 0)
  .forEach((entry) => fail(entry.message, entry.values));

if (process.exitCode !== 1) {
  console.log(`增强组件一致性校验通过，共校验 ${componentNames.length} 个增强组件。`);
}

// tests/types/fixtures/pro-root-boundary.ts:1-20（前半，@xiaoye/pro-components 侧）
// @ts-expect-error 根入口不再暴露 ProTable 工具栏动作细节类型
import type { ProTableToolbarAction } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露 ProTable 排序载荷细节类型
import type { ProTableSortChangePayload } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露 ProTable 单元格插槽细节类型
import type { ProTableCellSlotProps } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露审批动作别名
import type { ApprovalFlowAction } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露时间线内部状态枚举
import type { AuditTimelineStatus } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露浮层表单容器细节类型
import type { OverlayFormContainer } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露浮层表单模式细节类型
import type { OverlayFormMode } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露详情面板容器细节类型
import type { DetailPanelContainer } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露分栏布局字面量类型
import type { SplitLayoutPageLayout } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露 SearchForm 内建组件枚举
import type { SearchFormFieldBuiltinComponent } from "@xiaoye/pro-components";

# AGENTS.md:56-63（全文）

## 当前组件范围

- 当前 `packages/components/component-manifest.json`（同步驱动 `packages/components/index.ts` 导出）共 72 个组件：
  - 基础（basic，23 个）：`icon`、`button`、`link`、`breadcrumb`、`text`、`badge`、`avatar`、`image`、`watermark`、`card`、`check-card`、`carousel`、`affix`、`anchor`、`menu`、`row`、`col`、`scrollbar`、`splitter`、`divider`、`tag`、`space`、`tabs`
  - 表单（form，19 个）：`config-provider`、`input`、`auto-complete`、`cascader`、`radio`、`checkbox`、`switch`、`input-tag`、`input-number`、`rate`、`slider`、`date-picker`、`time-picker`、`time-select`、`select`、`tree-select`、`form`、`upload`、`editor`
  - 反馈与浮层（feedback，17 个）：`alert`、`message`、`notification`、`backtop`、`collapse`、`collapse-transition`、`empty`、`loading`、`skeleton`、`result`、`tooltip`、`popover`、`popconfirm`、`dropdown`、`transfer`、`dialog`、`drawer`
  - 数据展示（data，13 个）：`statistic`、`countdown`、`progress`、`steps`、`timeline`、`scheduler`、`descriptions`、`tree`、`table`、`pagination`、`charts`、`audio-player`、`video-player`
- 更新 `AGENTS.md`、文档导航或任务说明时，组件清单应以 `component-manifest.json` 为准，不要沿用旧列表。

# AGENTS.md:65-70（全文）

## 设计令牌约定

- 令牌唯一事实源是 `packages/xiaoye-primitives/src/theme/tokens.css`，采用基元（`--xy-{色板}-{阶}`）/ 语义（`--xy-{角色}[-{状态}]`）/ 刻度（`--xy-{刻度}-{档}`）三层架构，蓝本为 Stripe 设计语言（亮暗双主题锚点值取自 design.hagicode.com 收录的 Stripe 官方 token 目录）。
- `packages/tokens` 的 TS 常量层由 `pnpm generate:tokens` 从 tokens.css 生成，不要手工编辑生成物；调整令牌后先改 tokens.css 再重新生成。
- 组件样式只消费语义层与刻度层；新代码禁止使用 tokens.css 末尾 `@deprecated` 兼容层里的旧命名（`--xy-color-primary`、`--xy-text-color-*`、`--xy-bg-color-*`、`--xy-shadow-xs/sm/md/lg` 等）。
- 改动令牌值或新增令牌后，同步更新 `apps/docs/design-tokens.md` 与 `apps/docs/guide/theming.md` 的变量表，并重新生成 llms 文档。

// scripts/check-generated.mjs:2-9（头注释节选）
/**
 * 生成物漂移守卫：校验"由事实源生成"的产物是否与事实源保持同步。
 *
 * 流程：快照当前生成物到临时目录 → 重新执行生成命令 → 逐文件对比
 * （--ignore 可按行正则过滤时间戳等易变行）→ 无论通过与否都还原快照，
 * 保证对工作区零副作用（不能用 git diff 判断，本地未提交改动会误报）。
 * 失败时把重新生成的产物保留在临时目录作为证据，并输出修复处方。
 */

# AGENTS.md:72-76（全文）

## 发布流程

- 版本与变更日志统一走 Changesets：完成一批需要发版的改动后，用 `pnpm changeset` 写一条变更记录（选对 bump 级别：破坏性 major、新增能力 minor、修复 patch）。
- push 到 main 后 `.github/workflows/release.yml` 中的 changesets action 会自动创建/更新 "Version Packages" PR；该 PR 合并后自动构建 `build:lib` 并执行 `changeset publish` 发布到 npm。
- 不要手工改 `packages/*/package.json` 的版本号，也不要手工编辑 changesets 生成的 `packages/*/CHANGELOG.md`。

# AGENTS.md:78-89（全文）

## 文档与测试约定

- 组件文档页位于 `apps/docs/components/<name>.md`。
- 组件示例位于 `apps/docs/examples/<name>/`；组合型示例目前还包含 `apps/docs/examples/basic-form`、`apps/docs/examples/feedback-data`、`apps/docs/examples/admin.md`。
- 文档站配置与主题扩展主要位于：
  - `apps/docs/.vitepress/config.ts`
  - `apps/docs/.vitepress/theme`
  - `apps/docs/.vitepress/plugins`
  - `apps/docs/.vitepress/utils`
- 组件单元测试通常放在 `packages/components/<name>/__tests__/*.spec.ts`。
- 类型测试夹具位于 `tests/types/fixtures/*.ts`；新增组件或调整导出类型时，优先补齐对应夹具。全部夹具通过 `pnpm typecheck:types` 参与检查，不要把新夹具排除在 tsconfig 之外。
- 文档示例和测试中的组件使用方式，应该与 `packages/components/index.ts` 的对外导出保持一致。

# AGENTS.md:91-114（全文，22 条）

## 仓库命令

- 安装依赖：`pnpm install`
- 启动文档：`pnpm dev` 或 `pnpm dev:docs`
- 启动联调：`pnpm dev:playground`
- 测试：`pnpm test`
- 测试监听：`pnpm test:watch`
- 类型检查：`pnpm typecheck`
- 包与应用类型检查拆分命令：
  - `pnpm typecheck:packages`
  - `pnpm typecheck:types`
- Lint：`pnpm lint`
- 构建全部产物：`pnpm build`
- 分别构建：
  - `pnpm build:lib`
  - `pnpm build:docs`
  - `pnpm build:playground`
- 文档预览：`pnpm preview:docs`
- 双主题视觉巡检：`pnpm audit:visual`（--save-baseline 保存基线；存在基线时自动做像素 diff，差异超 0.5% 退出码 1）
- Changesets 相关：
  - `pnpm changeset`
  - `pnpm version-packages`
  - `pnpm release`
- 清理构建产物：`pnpm clean`

# AGENTS.md:116-128（全文）

## 目录提示

- `apps/docs`：VitePress 文档站，组件文档、示例和首页内容都在这里。
- `apps/playground`：本地联调 playground。
- `packages/components`：基础组件源码（包名 `xiaoye-components`）、安装入口和单测。
- `packages/pro-components`：增强组件源码（包名 `xiaoye-pro-components`）。
- `packages/xiaoye-primitives`：基础设施包（包名 `xiaoye-primitives`），`src/composables` 是跨组件复用的组合式逻辑，`src/utils` 是类型、DOM、Vue 工具函数。
- `packages/theme`：组件样式入口与 CSS 实现（private）。
- `packages/tokens`：设计令牌相关源码（private）。
- `packages/mcp-server`：面向 AI 工具的 MCP Server（包名 `xiaoye-mcp-server`）。
- `tests/types`：类型测试夹具与独立 tsconfig。
- `scripts`：仓库脚本。
- `.changeset`：版本变更记录。

# AGENTS.md:130-143（全文）

## 本地产物与忽略项

- 以下目录通常属于本地生成内容，不应在未明确要求时提交：
  - `.playwright-cli/`
  - `apps/docs/.vitepress/cache`
  - `apps/docs/.vitepress/dist`
  - `apps/docs/.vitepress/.temp`
  - `apps/playground/dist`
  - `packages/components/dist`
  - `packages/pro-components/dist`
  - `packages/xiaoye-primitives/dist`
  - `coverage`
  - `output/`
- 修改忽略规则时，先以根目录 `.gitignore` 为准，避免把调试日志、页面快照或构建产物带入提交。

$ git log --follow --oneline --date=short --pretty='%h %ad %s' -- AGENTS.md
7645d5c 2026-09-16 feat: 设计令牌体系重构为 Stripe 设计语言
2231dc1 2026-09-14 docs: 落实审查建议——发布门禁兜底与工程上下文更新
622a240 2026-09-14 docs: 修正 AI 协作上下文与安装指引，归档过期规划
323e9a7 2026-04-21 feat(xiaoye-ui): 完成前台基础组件库 Phase 1 + Phase 2 核心组件
a32e399 2026-03-30 feat: 新增 pro 组件并增强表单与表格能力
6b6b247 2026-03-28 refactor: 收敛组件清单与导出流程并整理工程配置
4eb1885 2026-03-27 feat: 新增反馈导航组件并以 dialog 替换 modal
9200bba 2026-03-25 feat: 新增展示组件并增强浮层与分页交互
ff2024b 2026-03-21 feat: 初始化组件库基础设施与MVP交互组件

# a32e399 对 AGENTS.md 的增量（节选）
+- 增强组件源码统一位于 `packages/pro-components/<name>`，并通过 `packages/pro-components/component-manifest.json` 维护 21 个正式公开增强组件清单。

# 622a240 对 AGENTS.md 的关键增量（节选）
-- 当前 `packages/components/index.ts` 已导出 62 个组件：
-  - 配置入口：`config-provider`
-  （……62 组件手抄清单，6 组分组……）
-- 更新 `AGENTS.md`、文档导航或任务说明时，组件清单应以上述导出入口为准，不要沿用旧列表。
+- 当前 `packages/components/component-manifest.json`（同步驱动 `packages/components/index.ts` 导出）共 72 个组件：
+  （……72 组件清单，按 manifest 四分组重抄……）
+- 更新 `AGENTS.md`、文档导航或任务说明时，组件清单应以 `component-manifest.json` 为准，不要沿用旧列表。