📋 目录
- 概述
-
TypeDOM 文档体系架构\](#typedom 文档体系架构)
-
规范规则类文档\](#二规范规则类文档告诉 ai 怎么做)
-
工作流程类文档\](#四工作流程类文档 ai 的操作手册)
-
部署运维类文档\](#六部署运维类文档 ai 的运维手册)
-
AI 专用增强文档\](#八 ai 专用增强文档 ai 的外挂大脑)
- 文档体系金字塔
- 实施检查清单
- 持续改进计划
🎯 概述
文档目的
本文档基于 TypeDOM 项目的实际文档体系，详细说明了 AI 辅助开发系统所需的完整文档架构，帮助项目团队理解、建设和维护高质量的 AI文档生态。
核心理念
基于**AI 优先 (AI-First)和 文档即代码 (Docs-as-Code)和代码即文档 (Code-as-Docs)**原则，构建:
- ✅ 机器可读的结构化知识
- ✅ 语义化的导航系统
- ✅ 可自动化的质量检查
- ✅ 持续演进的生态系统
文档分类
AI 需要的文档分为九大层次,从基础到高级依次为:
1. 核心知识类 → 让 AI 了解"是什么" (TypeDOM 框架认知)
2. 规范规则类 → 告诉 AI"怎么做" (Class + Hooks + Const 模式)
3. 工具方法类 → 给 AI 提供"工具箱" (Signals/Batch/Effect)
4. 工作流程类 → AI 的"操作手册" (组件开发流程)
5. 测试验证类 → AI 的"质检员" (Vitest 测试规范)
6. 部署运维类 → AI 的"运维手册" (NX Workspace 管理)
7. 最佳实践类 → AI 的"经验库" (UI 组件/A11y/性能)
8. AI 专用增强 → AI 的"外挂大脑" (Prompt 模板/检查清单)
9. 持续改进类 → AI 的"成长记录" (优化报告/修复记录)TypeDOM 项目文档体系特色
与通用项目不同，TypeDOM 项目文档体系具有以下特色:
1. 三层文档架构
Workspace 级 (AI-DOCS/) → 跨项目通用文档
↓
Library 级 (libs/*/AI-DOCS/) → Framework/UI/Signals 专项文档
↓
Component 级 (组件内注释) → 具体组件 API 文档2. 五类核心文档矩阵 (每个模块必备)
| 类别 | 名称 | 作用 | 示例 |
|---|---|---|---|
| 第 1 类 | AI-README | 总索引导航 | FRAMEWORK/AI-README.md |
| 第 2 类 | AI-OPTIMIZATION-GUIDE | 完整概念指南 | FRAMEWORK/AI-OPTIMIZATION-GUIDE.md |
| 第 3 类 | QUICK-REFERENCE | 快速参考卡片 | FRAMEWORK/QUICK-REFERENCE.md |
| 第 4 类 | AI-CODE-CHECKLIST | 代码修改检查清单 | FRAMEWORK/AI-CODE-CHECKLIST.md |
| 第 5 类 | SPECIAL-FEATURES-GUIDE | 专项功能指南 | UI/HOOKS-GUIDE.md, UI/A11Y-GUIDE.md |
3. 专项深度指南 (TypeDOM 特色)
- batch 批量更新完全指南 (BATCH-GUIDE.md)
- onScopeDispose 清理机制指南 (ONSCOPE-DISPOSE-GUIDE.md)
- Signals 响应式系统详解
- Class + Hooks + Const 三位一体模式
4. 测试驱动文档
- 测试修复报告 (BATCH-TEST-FIXES.md)
- 测试生成指南 (BATCH-TEST-GUIDE.md)
- 覆盖率目标：90%+
一、核心知识类文档（告诉 AI"是什么"）
1.1 项目元数据文档
作用: 让 AI 快速了解项目基本信息
内容要求:
json
{
"project": {
"name": "TypeDOM NX-Workspace",
"fullName": "TypeDOM 前端框架及组件库",
"version": "3.0.0",
"namespace": "TD",
"type": "Frontend Framework & Component Library",
"domain": "Web Development",
"languages": ["zh-CN", "en"],
"techLead": "zhang yin",
"maintainer": "TypeDOM Core Team"
},
"technicalStack": {
"framework": {
"name": "TypeDOM",
"version": "3.0.0",
"paradigm": "Object-Oriented Programming (OOP)",
"rendering": "Direct DOM Manipulation (No Virtual DOM)"
},
"reactivity": {
"name": "@type-dom/signals",
"model": "Push-Pull Model",
"features": ["Automatic Dependency Tracking", "Batch Updates"]
},
"buildTools": {
"monorepo": "Nx Workspace",
"bundler": "Vite/Rollup",
"transpiler": "TypeScript",
"packageManager": "pnpm/yarn"
},
"testing": {
"framework": "Vitest",
"coverage": "≥90%"
}
}
}示例文件:
AI-ASSISTANT-GUIDE.md- AI 助手完全指南README-USAGE.md- 使用说明文档
健康度指标:
- ✅ 完整性：100%
- ✅ 准确性：已验证
- ✅ 时效性：与代码版本同步
1.2 架构知识图谱
作用: 让 AI 理解系统结构和组件关系
内容要求:
a) 核心类继承关系图 (Mermaid ClassDiagram)
TypeNode
TypeElement
TypeHtml
TypeSvg
TypeFragment
TypeTransition
抽象基类
HTML 元素基类
片段节点
b) 四层架构图 (Mermaid Graph)
Application Layer
Signals Layer
signal/computed/effect
watch/batch/batchEffect
effectScope/onScopeDispose
Framework Core Layer
TypeNode 体系
Renderer 渲染器
Reactivity 响应式
Hooks & Utils Layer
useNamespace - BEM 命名
useModelToggle - 状态切换
useFocusTrap - 焦点管理
useLocale - 国际化
UI Components Layer
Basic - Button, Icon
Form - Input, Select
Data - Table, Tree
Feedback - Message, Dialog
Navigation - Menu, Tabs
apps/* - 14 个应用示例
UI
H
F
S
c) 响应式数据流序列图
batch() effect(() => log(c)) computed(() => s*2) signal(0) batch() effect(() => log(c)) computed(() => s*2) signal(0) batch 开始 batch 结束 初始值通知 执行 (读取 c) 建立依赖 计算并缓存 建立依赖 set(1) propagate() mark dirty notify checkDirty() get() get() recompute 新值 执行回调
示例文件:
AI-ASSISTANT-GUIDE.md- 架构图谱LIBS/FRAMEWORK/AI-DOCS/AI-OPTIMIZATION-GUIDE.md- 渲染流程详解
1.3 业务实体定义
作用: 用 TypeScript 类型定义让 AI 理解数据结构
内容要求:
typescript
// TypeDOM 核心类型定义
// 信号相关
interface Signal<T> {
get(): T;
set(value: T): void;
update(fn: (value: T) => T): void;
}
interface Computed<T> {
get(): T;
// 自动追踪依赖，缓存计算结果
}
interface Effect {
(fn: () => void): () => void; // 返回清理函数
// 自动追踪依赖，依赖变化时重新执行
}
interface WatchSource<T> {
get(): T;
}
interface WatchOptions {
immediate?: boolean; // 是否立即执行
deep?: boolean; // 深度监听
}
// 组件相关
interface TypeNode {
className: string;
props: Record<string, any>;
dom: HTMLElement;
setup(): void;
mount(parent: Element): void;
unmount(): void;
}
interface LifecycleHooks {
onCreated(fn: () => void): void;
onBeforeMount(fn: () => void): void;
onMounted(fn: () => void): void;
onBeforeUpdate(fn: () => void): void;
onUpdated(fn: () => void): void;
onBeforeUnmount(fn: () => void): void;
onUnmounted(fn: () => void): void;
}
// 批量更新相关
interface Batch {
(fn: () => void): void;
// 批量执行更新，合并多次变更为一次通知
}
interface BatchEffect {
(fn: () => void): () => void;
// effect + batch 的组合，追踪依赖且批量更新
}示例文件:
LIBS/SIGNALS/src/index.ts- Signals 类型定义LIBS/FRAMEWORK/src/core/TypeNode.ts- TypeNode 类型
1.4 状态机图
作用: 让 AI 理解组件生命周期和状态转换
内容要求:
实例创建
setup() 完成
DOM 挂载完成
响应式更新
多次更新
开始卸载
卸载完成
清理完毕
Created
BeforeMount
Mounted
Updated
BeforeUnmount
Unmounted
onCreated
可以访问 props/refs
onMounted
DOM 已就绪
onBeforeUnmount
清理定时器/事件
onUnmounted
完全清理
示例文件:
二、规范规则类文档（告诉 AI"怎么做"）
2.1 编码规范文档 ⭐
作用: 确保 AI 生成的代码符合 TypeDOM 标准
内容结构:
.lingma/rules/
├── core-rules.md # TypeDOM 核心规则
├── component-standard.md # 组件开发规范
├── hooks-guideline.md # Hooks 使用指南
└── checklist.md # 代码检查清单核心规则示例:
markdown
RULE-001: Class + Hooks + Const 三位一体模式
优先级：MUST
格式：
- Interface 定义 Props
- Const 定义默认值和配置
- Class 实现组件逻辑
✅ 正确:
interface ButtonProps {
type?: 'primary' | 'default';
onClick?: () => void;
}
const defaultProps: ButtonProps = {
type: 'default'
};
export class TdButton extends TypeHtml<ButtonProps> {
className = 'TdButton';
constructor(params = {}) {
super(params);
defaultProps(this);
}
setup() { /* ... */ }
}
❌ 错误：函数式组件 (不适用)
RULE-002: setup() 中使用 Hooks
优先级：MUST
要求：所有初始化逻辑必须在 setup() 中调用 Hooks
✅ 正确:
setup() {
const ns = useNamespace('button');
const { handleClick } = useButton(this.props, this.emit);
}
❌ 错误:
constructor() {
this.ns = useNamespace('button'); // ❌ 不能在构造函数中调用
}
RULE-003: 响应式必须使用 Signals
优先级：MUST
要求：状态管理使用 signal/computed/effect
✅ 正确:
const count = signal(0);
const double = computed(() => count.get() * 2);
effect(() => console.log(count.get()));
❌ 错误:
let count = 0; // ❌ 不是响应式
this.count = 0; // ❌ Vue 思维示例文件:
LIBS/UI/AI-DOCS/CODING-RULES.md- UI 组件编码规范LIBS/FRAMEWORK/AI-DOCS/AI-CODE-CHECKLIST.md- Framework 检查清单
2.2 代码模板库
作用: 为 AI 提供标准代码模板
基础组件模板:
typescript
/**
* @module TD.ui.Button
* @extends TypeHtml
*/
import { TypeHtml } from '@type-dom/framework';
import { useNamespace, useButton } from '@type-dom/hooks';
interface ButtonProps {
type?: 'primary' | 'default';
size?: 'small' | 'medium' | 'large';
disabled?: boolean;
onClick?: (event: MouseEvent) => void;
}
const defaultProps: ButtonProps = {
type: 'default',
size: 'medium',
disabled: false
};
export class TdButton extends TypeHtml<ButtonProps> {
className = 'TdButton';
constructor(params = {}) {
super(params);
defaultProps(this);
}
setup() {
const ns = useNamespace('button');
const { handleClick } = useButton(this.props, this.emit);
this.classList.add(ns.b());
this.classList.add(ns.m(this.props.type));
this.classList.add(ns.m(this.props.size));
if (this.props.disabled) {
this.setAttribute('disabled', '');
}
this.on('click', handleClick);
}
}Hook 模板:
typescript
/**
* Button Hook
* 用于处理按钮的交互逻辑
*/
import { useNamespace } from './useNamespace';
export function useButton(
props: ButtonProps,
emit: (event: string, ...args: any[]) => void
) {
const ns = useNamespace('button');
const handleClick = (event: MouseEvent) => {
if (props.disabled) return;
emit('click', event);
props.onClick?.(event);
};
return {
handleClick
};
}示例文件:
2.3 命名规范速查表
作用: 让 AI 快速验证命名是否正确
内容要求:
markdown
| 类型 | 格式 | 示例 |
|------|------|------|
| 组件类名 | `Td{ComponentName}` | `TdButton`, `TdInput` |
| Props Interface | `{ComponentName}Props` | `ButtonProps`, `InputProps` |
| Hook 函数 | `use{Functionality}` | `useNamespace`, `useButton` |
| CSS 类名 (BEM) | `{ns}-b / {ns}-m-{mod} / {ns}-e-{elem}` | `td-button`, `td-button--primary` |
| 文件名 | PascalCase | `Button.ts`, `TdButton.ts` |
| 文件夹 | kebab-case | `basic/`, `form/`, `data/` |
| 命名空间 | `@type-dom/{lib}` | `@type-dom/framework`, `@type-dom/ui` |示例文件:
三、工具方法类文档（AI 的"工具箱"）
3.1 Signals API 索引
作用: 让 AI 知道有哪些响应式 API 可用
内容要求:
typescript
// @type-dom/signals 完整 API
// 基础 Signals
signal<T>(value: T): Signal<T> // 创建信号
computed<T>(fn: () => T): Computed<T> // 计算属性
effect(fn: () => void): () => void // 副作用
watch<T>(source: WatchSource<T>, cb: Callback, options?: Options): () => void
// 批量更新
batch(fn: () => void): void // 批量执行
batchEffect(fn: () => void): () => void // 带批量的 effect
// Effect Scope
effectScope(): EffectScope // 创建作用域
onScopeDispose(fn: () => void): void // 注册清理回调
// 底层 API (高级)
startBatch(): void // 开始批量
endBatch(): void // 结束批量
flush(): void // 执行待处理的更新示例文件:
LIBS/SIGNALS/README.md- Signals 完整文档BATCH-GUIDE.md- batch 完全指南
3.2 常用 Hooks 索引
作用: 让 AI 了解可用的 Hooks 函数
内容要求:
typescript
// @type-dom/hooks 完整索引
// 基础 Hooks
useNamespace(block: string): {
b: () => string; // block
m: (mod: string) => string; // modifier
e: (elem: string) => string; // element
em: (elem: string, mod: string) => string;
}
useModelToggle(prop: string): {
model: Computed<boolean>;
toggle: () => void;
}
useFocusTrap(options: FocusTrapOptions): {
activate: () => void;
deactivate: () => void;
}
// 表单 Hooks
useField(name: string): {
value: Signal<any>;
error: Signal<string | null>;
validate: () => boolean;
}
// 交互 Hooks
useClickOutside(handler: () => void): {
ref: Ref<HTMLElement | null>;
}
useKeyPress(key: string, handler: () => void): void;
// 工具 Hooks
useLocale(): {
t: (key: string) => string;
locale: Signal<string>;
}
useTheme(): {
theme: Signal<'light' | 'dark'>;
toggle: () => void;
}示例文件:
LIBS/UI/AI-DOCS/HOOKS-GUIDE.md- Hooks 完全指南
3.3 配置参数手册
作用: 让 AI 了解系统配置项
内容要求:
typescript
// Nx Workspace 配置
nx.json // Nx 全局配置
workspace.json // Workspace 定义
tsconfig.base.json // TypeScript 路径映射
// 组件库配置
libs/ui/src/config.ts // UI 组件默认配置
libs/framework/src/config.ts // Framework 配置
// 构建配置
vite.config.ts // Vite 构建配置
vitest.config.ts // Vitest 测试配置
// 常用默认值
Config.ComponentPrefix = 'Td' // 组件前缀
Config.Namespace = 'td' // CSS 命名空间
Config.Test.CoverageThreshold = 90 // 测试覆盖率阈值示例文件:
nx.json- Nx 配置tsconfig.base.json- TypeScript 配置
四、工作流程类文档（AI 的"操作手册"）
4.1 AI 工作流程定义
作用: 指导 AI 如何执行特定任务
组件开发流程:
markdown
aiWorkflows: {
componentDevelopment: {
steps: [
'1. 阅读 COMPONENT-TEMPLATE.md 获取代码模板',
'2. 阅读 CODING-RULES.md 确认命名规范',
'3. 查找相关 Hooks (HOOKS-GUIDE.md)',
'4. 创建组件文件 (遵循 Class + Hooks + Const 模式)',
'5. 添加样式 (BEM 命名 + SCSS)',
'6. 编写测试用例 (参考 TESTING-GUIDE.md)',
'7. 使用 AI-CODE-CHECKLIST.md 自检',
'8. 生成组件文档 (AI-DOCUMENTATION-SYSTEM.md)'
]
},
hookDevelopment: {
steps: [
'1. 确定 Hook 的职责和接口',
'2. 参考现有 Hooks 实现 (useNamespace, useButton)',
'3. 实现 Hook 函数 (纯函数，无副作用)',
'4. 添加 JSDoc 注释和示例',
'5. 编写单元测试',
'6. 更新 HOOKS-GUIDE.md 索引'
]
},
problemDiagnosis: {
steps: [
'1. 读取错误信息和堆栈跟踪',
'2. 查看响应式数据流序列图',
'3. 对比实际代码识别偏离',
'4. 定位可能的问题点 (依赖追踪/批量更新/生命周期)',
'5. 分析根因',
'6. 提供诊断报告和修复建议',
'7. 添加测试用例防止回归'
]
},
refactoring: {
steps: [
'1. 扫描代码文件识别代码异味',
'2. 阅读 AI-OPTIMIZATION-GUIDE.md 对照标准模式',
'3. 发现偏离规范的地方',
'4. 生成重构报告和改进建议',
'5. 评估影响范围',
'6. 提供迁移方案'
]
}
}示例文件:
AI-ASSISTANT-GUIDE.md- AI 工作流程详解
4.2 质量检查清单
作用: 让 AI 自我验证代码质量
组件开发检查清单:
markdown
## 架构检查
- [ ] 是否遵循 Class + Hooks + Const 模式？
- [ ] Interface 是否正确定义 Props?
- [ ] 是否使用 defaultProps 设置默认值？
- [ ] setup() 中是否调用了所有必需的 Hooks?
- [ ] 是否正确使用了响应式 (signal/computed/effect)?
- [ ] 是否避免了直接修改响应式对象？
## 命名检查
- [ ] 组件类名是否为 Td{ComponentName}?
- [ ] Props Interface 是否为 {ComponentName}Props?
- [ ] CSS 类名是否遵循 BEM 规范？
- [ ] Hook 函数是否以 use 开头？
## 代码质量检查
- [ ] 是否有完整的 JSDoc 注释？
- [ ] 是否使用 TypeScript 类型注解？
- [ ] 函数长度是否 < 50 行？
- [ ] 是否有重复代码需要提取？
- [ ] 是否有未使用的导入或变量？
## 测试检查
- [ ] 是否编写了单元测试？
- [ ] 测试覆盖率是否 ≥90%?
- [ ] 是否覆盖了边界情况？
- [ ] 是否有 E2E 测试 (如适用)?
## 无障碍检查
- [ ] 是否有正确的 ARIA 属性？
- [ ] 是否支持键盘导航？
- [ ] 是否有焦点管理？
- [ ] 是否通过屏幕阅读器测试？示例文件:
LIBS/UI/AI-DOCS/AI-CODE-CHECKLIST.md- UI 组件检查清单LIBS/FRAMEWORK/AI-DOCS/AI-CODE-CHECKLIST.md- Framework 检查清单
五、测试验证类文档（AI 的"质检员"）
5.1 测试用例模板
作用: 指导 AI 生成规范的测试用例
组件测试模板:
typescript
/**
* TdButton 组件单元测试
*/
import { describe, test, expect, vi } from 'vitest';
import { TdButton } from '../Button';
describe('TdButton', () => {
let button: TdButton;
let container: HTMLDivElement;
beforeEach(() => {
container = document.createElement('div');
document.body.appendChild(container);
});
afterEach(() => {
if (button) {
button.unmount();
}
container.remove();
});
describe('初始化', () => {
test('应该成功创建实例', () => {
button = new TdButton();
button.mount(container);
expect(button).toBeDefined();
});
test('应该有正确的 CSS 类名', () => {
button = new TdButton();
button.mount(container);
expect(button.dom.classList).toContain('td-button');
});
test('应该应用默认的 type 属性', () => {
button = new TdButton();
button.mount(container);
expect(button.dom.classList).toContain('td-button--default');
});
});
describe('Props', () => {
test('应该支持 type 属性', () => {
button = new TdButton({ type: 'primary' });
button.mount(container);
expect(button.dom.classList).toContain('td-button--primary');
});
test('应该支持 disabled 属性', () => {
button = new TdButton({ disabled: true });
button.mount(container);
expect(button.hasAttribute('disabled')).toBe(true);
});
});
describe('事件', () => {
test('应该触发 click 事件', () => {
const handleClick = vi.fn();
button = new TdButton({ onClick: handleClick });
button.mount(container);
button.dom.click();
expect(handleClick).toHaveBeenCalledTimes(1);
});
test('disabled 状态下不应该触发点击事件', () => {
const handleClick = vi.fn();
button = new TdButton({ disabled: true, onClick: handleClick });
button.mount(container);
button.dom.click();
expect(handleClick).not.toHaveBeenCalled();
});
});
describe('响应式', () => {
test('应该响应式更新 type 属性', () => {
const type = signal<'primary' | 'default'>('default');
// 注：实际项目中可能需要通过其他方式实现响应式更新
button = new TdButton({ type: type.get() });
button.mount(container);
type.set('primary');
// 验证更新逻辑
});
});
});batch/batchEffect 测试模板:
typescript
/**
* batch 和 batchEffect 测试
*/
import { describe, test, expect, vi } from 'vitest';
import { signal, computed, effect, batch, batchEffect } from '@type-dom/signals';
describe('batch', () => {
test('应该批量更新信号', () => {
const count = signal(0);
const updates: number[] = [];
effect(() => {
updates.push(count.get());
});
batch(() => {
count.set(1);
count.set(2);
count.set(3);
});
// effect 只在 batch 结束后执行一次
expect(updates).toEqual([0, 3]);
});
test('应该支持嵌套 batch', () => {
const count = signal(0);
const updates: number[] = [];
effect(() => {
updates.push(count.get());
});
batch(() => {
count.set(1);
batch(() => {
count.set(2);
count.set(3);
});
count.set(4);
});
// 只有外层 batch 结束时才 flush
expect(updates).toEqual([0, 4]);
});
});
describe('batchEffect', () => {
test('应该追踪依赖并批量更新', () => {
const count = signal(0);
const logs: string[] = [];
batchEffect(() => {
logs.push(`count: ${count.get()}`);
});
count.set(1);
count.set(2);
// batchEffect 会追踪依赖并在变化时重新执行
expect(logs).toEqual(['count: 0', 'count: 2']);
});
test('应该返回清理函数', () => {
const count = signal(0);
let executions = 0;
const stop = batchEffect(() => {
executions++;
count.get();
});
expect(executions).toBe(1);
count.set(1);
expect(executions).toBe(2);
stop(); // 停止监听
count.set(2);
expect(executions).toBe(2); // 不再执行
});
});示例文件:
LIBS/FRAMEWORK/tests/reactivity/batch.spec.ts- batch 测试示例BATCH-TEST-GUIDE.md- 测试编写指南
5.2 测试覆盖率要求
作用: 让 AI 了解测试质量标准
内容要求:
markdown
| 测试类型 | 最低覆盖率 | 目标覆盖率 | 优先级 |
|---------|-----------|-----------|--------|
| 单元测试 | ≥90% | ≥95% | P0 |
| 集成测试 | ≥70% | ≥85% | P1 |
| E2E 测试 | ≥50% | ≥80% | P0 |
| 视觉回归 | 0% | ≥60% | P2 |
**测试命令**:
```bash
# 运行所有测试
pnpm test
# 运行单元测试
pnpm test:unit
# 运行集成测试
pnpm test:integration
# 运行 E2E 测试
pnpm test:e2e
# 生成覆盖率报告
pnpm test:coverage
# 查看覆盖率 HTML 报告
open coverage/index.html测试文件命名:
*.spec.ts- 测试文件*.test.ts- 测试文件 (等价)tests/**/*.spec.ts- 测试文件位置
示例文件:
-
LIBS/FRAMEWORK/tests/- Framework 测试目录 -
LIBS/UI/tests/- UI 组件测试目录
六、部署运维类文档（AI 的"运维手册"）
6.1 Nx Workspace 管理
作用: 让 AI 了解如何管理 Monorepo 项目
内容要求:
bash# Nx 常用命令 # 显示项目图 nx graph # 运行指定项目 nx build {project-name} nx test {project-name} nx lint {project-name} # 运行受影响的项目 nx affected:build nx affected:test # 生成新项目 nx generate @nrwl/js:library my-lib nx generate @nrwl/web:app my-app # 依赖检查 nx dep-graph nx show project {project-name}
项目结构:
nx-workspace/
├── apps/ # 应用程序
│ ├── ofd/ # OFD 阅读器示例
│ ├── ui-doc/ # UI 文档站点
│ └── samples/ # 示例应用
├── libs/ # 库
│ ├── framework/ # TypeDOM 框架核心
│ ├── ui/ # UI 组件库
│ ├── signals/ # Signals 响应式系统
│ ├── router/ # 路由库
│ ├── utils/ # 工具函数库
│ └── i18n/ # 国际化库
└── tools/ # 构建工具和脚本示例文件:
nx.json- Nx 配置workspace.json- Workspace 定义
6.2 构建和发布
作用: 让 AI 了解如何构建和发布库
内容要求:
bash
# 构建所有库
nx run-many --target=build --all
# 构建指定库
nx build framework
nx build ui
nx build signals
# 发布到 npm
cd dist/libs/framework
npm publish
# 版本管理
npm version patch # 1.0.0 -> 1.0.1
npm version minor # 1.0.0 -> 1.1.0
npm version major # 1.0.0 -> 2.0.0构建配置:
json
// tsconfig.base.json
{
"compilerOptions": {
"paths": {
"@type-dom/framework": ["libs/framework/src/index.ts"],
"@type-dom/ui": ["libs/ui/src/index.ts"],
"@type-dom/signals": ["libs/signals/src/index.ts"]
}
}
}示例文件:
vite.config.ts- Vite 构建配置package.json- NPM 包配置
七、最佳实践类文档（AI 的"经验库"）
7.1 优秀实践案例
作用: 为 AI 提供学习样板
标准组件开发案例:
libs/ui/src/components/Button/
├── Button.tsx ✅ 标准组件实现
├── Button.types.ts ✅ 类型定义
├── Button.style.scss ✅ 样式文件
├── index.ts ✅ 导出文件
└── tests/
└── Button.spec.ts ✅ 单元测试亮点:
- 完全遵循 Class + Hooks + Const 模式
- 完善的 TypeScript 类型定义
- 完整的 BEM 命名样式
- 全面的测试覆盖 (≥90%)
- 详细的 JSDoc 注释
示例文件:
LIBS/UI/src/components/Button/- 按钮组件完整实现
7.2 常见错误示例
作用: 让 AI 避免常见陷阱
错误 1: 在构造函数中调用 Hooks
typescript
// ❌ 错误：在构造函数中调用 Hook
export class TdButton extends TypeHtml {
constructor(params = {}) {
super(params);
const ns = useNamespace('button'); // ❌ 错误！
}
}
// ✅ 正确：在 setup() 中调用
export class TdButton extends TypeHtml {
setup() {
const ns = useNamespace('button'); // ✅ 正确
}
}错误 2: 直接修改响应式对象
typescript
// ❌ 错误：直接修改 signal 的值
const state = signal({ count: 0 });
state.value.count++; // ❌ 不会触发更新
// ✅ 正确：使用 update 方法
const state = signal({ count: 0 });
state.update(s => ({ ...s, count: s.count + 1 })); // ✅ 正确错误 3: 在 effect 中执行异步操作
typescript
// ❌ 错误：effect 中使用 async/await
effect(async () => {
const data = await fetchData(); // ❌ 不会追踪依赖
});
// ✅ 正确：使用 watch 或在 effect 外处理
const data = signal(null);
effect(() => {
fetchData().then(d => data.set(d)); // ✅ 正确
});示例文件:
LIBS/UI/AI-DOCS/CODING-RULES.md- 常见错误示例
7.3 性能优化技巧
作用: 让 AI 了解性能优化方法
批量更新优化:
typescript
// ✅ 推荐：使用 batch 批量更新
import { batch } from '@type-dom/signals';
batch(() => {
count.set(count.get() + 1);
name.set('new name');
status.set('active');
});
// 只触发一次通知，而不是三次
// ❌ 不推荐：多次单独更新
count.set(count.get() + 1); // 触发通知
name.set('new name'); // 触发通知
status.set('active'); // 触发通知计算属性缓存:
typescript
// ✅ 推荐：使用 computed 缓存计算结果
const count = signal(0);
const double = computed(() => count.get() * 2); // 缓存
// ❌ 不推荐：每次访问都重新计算
const getDouble = () => count.get() * 2; // 每次都计算依赖追踪优化:
typescript
// ✅ 推荐：精确追踪依赖
effect(() => {
const value = specificProp.get(); // 只追踪这个 prop
});
// ❌ 不推荐：追踪不必要的依赖
effect(() => {
const all = store.getAll(); // 追踪整个 store
});示例文件:
LIBS/UI/AI-DOCS/PERFORMANCE-GUIDE.md- 性能优化指南BATCH-GUIDE.md- batch 性能优势
八、AI 专用增强文档（AI 的"外挂大脑"）
8.1 机器可读元数据
作用: 让 AI 快速解析文档属性
Markdown 注释格式:
markdown
<!-- AI Metadata (Machine Readable) -->
<!--
{
"documentType": "navigation",
"priority": "P0",
"audience": ["AI", "Developer"],
"lastVerified": "2026-03-13",
"relatedDocuments": [
"AI-ASSISTANT-GUIDE.md",
"README-USAGE.md"
]
}
-->JSON 配置格式:
javascript
// ai-metadata.js
module.exports = {
project: {
name: 'TypeDOM NX-Workspace',
version: '3.0.0',
paradigm: 'OOP',
reactivity: 'Signals'
},
documentation: {
coreDocuments: [
'AI-ASSISTANT-GUIDE.md',
'AI-ASSISTANT-CHEATSHEET.md',
'README-USAGE.md'
],
healthMetrics: {
completeness: 100,
accuracy: 100,
timeliness: 100
}
},
aiWorkflows: {
codeGeneration: ['...'],
problemDiagnosis: ['...'],
refactoring: ['...']
}
};示例文件:
AI-ASSISTANT-GUIDE.md- 包含机器可读元数据
8.2 健康度仪表盘
作用: 让 AI 实时了解文档质量
Markdown 格式:
markdown
## 📊 文档健康度仪表盘
<!-- AI Health Metrics -->
<!--
{
"healthScore": 100,
"metrics": {
"completeness": 100,
"accuracy": 100,
"timeliness": 100
},
"lastCheck": "2026-03-13T00:00:00Z",
"status": "excellent"
}
-->
| 指标维度 | 目标值 | 当前值 | 状态 |
|---------|-------|--------|------|
| 完整性 | 100% | 100% | ✅ 优秀 |
├─ 核心知识类 | 100% | 100% | ✅ |
├─ 规范规则类 | 100% | 100% | ✅ |
├─ 工具方法类 | 100% | 100% | ✅ |
└─ 其他 | 100% | 100% | ✅ |示例文件:
README.md- 健康度仪表盘
8.3 Prompt 工程模板
作用: 为 AI 提供标准化的 Prompt 模板
场景 1: 创建新组件
markdown
@AI 我需要创建一个 {ComponentName} 组件，请参考以下文档:
**需求描述**:
- 功能：{简短描述功能}
- Props: {列出主要 Props}
- Events: {列出主要 Events}
**参考文档**:
- LIBS/UI/AI-DOCS/COMPONENT-TEMPLATE.md - 组件模板
- LIBS/UI/AI-DOCS/HOOKS-GUIDE.md - Hooks 使用
- LIBS/UI/AI-DOCS/A11Y-GUIDE.md - 无障碍要求
**输出要求**:
1. 完整的组件实现 (Class + Hooks + Const)
2. TypeScript 类型定义
3. 单元测试 (覆盖率≥90%)
4. 使用示例和文档
请给出完整的代码实现。场景 2: 性能优化
markdown
@AI 我们的 {ComponentName} 组件渲染很慢，请根据以下文档提供优化方案:
**问题描述**:
- 数据量：{约多少条数据}
- 渲染时间：{当前渲染耗时}
- 性能瓶颈：{如果知道的话}
**参考文档**:
- LIBS/UI/AI-DOCS/PERFORMANCE-GUIDE.md#虚拟滚动
- BATCH-GUIDE.md - 批量更新优化
- LIBS/SIGNALS/PERFORMANCE-BENCHMARKS.md - Signals 性能基准
**输出要求**:
1. 性能分析报告
2. 优化方案和代码实现
3. 预期性能提升
请给出详细的优化建议。场景 3: Code Review
markdown
@AI 请使用以下检查清单审查我的代码:
**代码文件**: {文件路径或代码片段}
**检查重点**:
- P0: 类型安全 (TypeScript 类型是否正确)
- P1: 响应式 (是否正确使用 signal/computed/effect)
- P2: 性能优化 (是否使用 batch 等优化手段)
- P3: 无障碍支持 (ARIA 属性、键盘导航)
**参考文档**:
- LIBS/UI/AI-DOCS/AI-CODE-CHECKLIST.md - 完整检查清单
- LIBS/UI/AI-DOCS/CODING-RULES.md - 编码规范
请指出问题并给出修改建议。示例文件:
AI-ASSISTANT-GUIDE.md- Prompt 模板大全
九、持续改进类文档（AI 的"成长记录"）
9.1 文档更新日志
作用: 记录文档演进历史
格式要求:
markdown
## 📝 更新日志
### v2.0-TypeDOM (2026-03-13)
**新增**:
- ✅ 基于 TypeDOM 项目实际的完整文档体系
- ✅ 五类核心文档矩阵 (Framework/UI/Signals)
- ✅ 专项深度指南 (batch, onScopeDispose, Signals)
- ✅ 测试驱动文档 (测试修复报告、测试指南)
**改进**:
- ✅ 删除 ExtJS 相关内容，替换为 TypeDOM 实例
- ✅ 整合现有文档资源 (AI-ASSISTANT-GUIDE 等)
- ✅ 更新所有示例代码为 TypeDOM 风格
- ✅ 增强机器可读性和 AI 友好度
**修复**:
- ✅ 统一版本号为 v2.0-TypeDOM
- ✅ 修正过时的 API 引用
- ✅ 更新项目元数据信息示例文件:
- 各文档末尾的更新日志章节
9.2 优化改进报告
作用: 总结文档优化成果
内容结构:
markdown
# 优化改进报告
## 执行摘要
- 优化背景：原文档基于 ExtJS，不符合 TypeDOM 项目实际
- 主要成果：完成全面改写，建立 TypeDOM 特色文档体系
- 效果评估：文档准确率提升至 100%，AI 理解度显著提升
## 已完成的工作
### 1. 文档体系重构
- 删除 ExtJS 特定内容 (xtype, Controller, ViewModel 等)
- 替换为 TypeDOM 概念 (Class, Hooks, Signals, batch 等)
- 建立三层文档架构 (Workspace → Library → Component)
### 2. 内容整合
- 整合 AI-ASSISTANT-GUIDE.md (1,334 行)
- 整合 README-USAGE.md (505 行)
- 整合 BATCH-GUIDE.md (741 行)
- 整合 ONSCOPE-DISPOSE-GUIDE.md (473 行)
### 3. 质量提升
- 所有示例代码更新为可运行的 TypeDOM 代码
- 所有 API 引用与实际实现一致
- 所有流程图与实际架构匹配
## 效果对比
| 指标 | 优化前 | 优化后 | 改进 |
|------|--------|--------|------|
| 文档准确率 | 60% (ExtJS) | 100% (TypeDOM) | +67% |
| AI 理解度 | 中等 | 优秀 | 显著提升 |
| 示例可用性 | 不可运行 | 完全可运行 | 质的飞跃 |
## 最佳实践总结
- ✅ AI-First 原则：为 AI 理解而设计
- ✅ Docs-as-Code 原则：版本控制、Code Review、CI/CD
- ✅ Code-as-Docs 原则：代码注释即文档
- ✅ 持续改进：定期审查、收集反馈、不断优化示例文件:
AI-GUIDE-GENERATION-REPORT.md- 指南生成报告BATCH-TEST-FIXES.md- 测试修复报告
9.3 实施清单
作用: 跟踪文档建设进度
格式要求:
markdown
# 实施清单
## ✅ 已完成功能
### 1. 核心文档体系
- [x] AI-ASSISTANT-GUIDE.md (1,334 行) - AI 助手完全指南
- [x] AI-ASSISTANT-CHEATSHEET.md (406 行) - 快速参考卡片
- [x] README-USAGE.md (505 行) - 使用说明文档
- [x] AI_DOCUMENT_REQUIREMENTS.md (本文档) - 文档需求指南
### 2. Framework 专项文档
- [x] libs/framework/AI-DOCS/AI-README.md
- [x] libs/framework/AI-DOCS/AI-OPTIMIZATION-GUIDE.md
- [x] libs/framework/AI-DOCS/QUICK-REFERENCE.md
- [x] libs/framework/AI-DOCS/AI-CODE-CHECKLIST.md
- [x] BATCH-GUIDE.md (741 行) - batch 完全指南
- [x] ONSCOPE-DISPOSE-GUIDE.md (473 行) - onScopeDispose 指南
### 3. UI 组件专项文档
- [x] libs/ui/AI-DOCS/AI-README.md
- [x] libs/ui/AI-DOCS/AI-OPTIMIZATION-GUIDE.md
- [x] libs/ui/AI-DOCS/QUICK-REFERENCE.md
- [x] libs/ui/AI-DOCS/AI-CODE-CHECKLIST.md
- [x] HOOKS-GUIDE.md (25.8KB) - Hooks 完全指南
- [x] A11Y-GUIDE.md (32.3KB) - 无障碍开发指南
- [x] PERFORMANCE-GUIDE.md (14.2KB) - 性能优化指南
- [x] TESTING-GUIDE.md (22.9KB) - 测试规范指南
- [x] BUSINESS-SCENARIOS-GUIDE.md (25.5KB) - 业务场景指南
### 4. Signals 专项文档
- [x] libs/signals/README.md (424 行)
- [x] BATCH-GUIDE.md (741 行)
- [x] ONSCOPE-DISPOSE-GUIDE.md (473 行)
### 5. 测试相关文档
- [x] batch.spec.ts (551 行) - batch/batchEffect 测试
- [x] BATCH-TEST-GUIDE.md (900 行) - 测试编写指南
- [x] BATCH-TEST-FIXES.md (440 行) - 测试修复报告
## 🔄 进行中任务
- [ ] API 参考文档自动生成
- [ ] 文档质量检查工具开发
- [ ] CI/CD 集成 (自动验证文档)
## 📅 计划中任务
- [ ] IDE 插件开发 (文档智能提示)
- [ ] 定时文档审查任务
- [ ] AI 自动生成文档初稿
- [ ] 行业标准输出 (最佳实践分享)示例文件:
SUMMARY.md- 文档体系建设总结
完整文档体系金字塔
🎯 核心知识层
(TypeDOM 框架认知、架构图谱、类型定义)
↓
📋 规范规则层
(Class+Hooks+Const 模式、编码规范、命名规则)
↓
🔧 工具方法层
(Signals API、Hooks 索引、配置参数)
↓
🎓 工作流程层
(组件开发流程、质量检查清单、AI 工作流)
↓
🧪 测试验证层
(测试模板、覆盖率要求、Vitest 规范)
↓
🚀 部署运维层
(Nx Workspace 管理、构建发布、CI/CD)
↓
💡 最佳实践层
(优秀案例、常见错误、性能优化)
↓
🤖 AI 专用增强层
(机器可读元数据、Prompt 模板、健康度)
↓
🔄 持续改进层
(更新日志、优化报告、实施清单)层次说明
| 层次 | 作用 | 必要性 | 示例文件 |
|---|---|---|---|
| 核心知识层 | 让 AI 了解 TypeDOM 框架基础 | ⭐⭐⭐⭐⭐ | AI-ASSISTANT-GUIDE.md |
| 规范规则层 | 告诉 AI 如何写 TypeDOM 代码 | ⭐⭐⭐⭐⭐ | CODING-RULES.md |
| 工具方法层 | 给 AI 提供 TypeDOM 工具箱 | ⭐⭐⭐⭐ | SIGNALS API、Hooks 索引 |
| 工作流程层 | AI 的 TypeDOM 操作手册 | ⭐⭐⭐⭐ | AI 工作流定义 |
| 测试验证层 | AI 的代码质检员 | ⭐⭐⭐⭐ | 测试模板、覆盖率要求 |
| 部署运维层 | AI 的 Nx 运维手册 | ⭐⭐⭐ | Nx 管理文档 |
| 最佳实践层 | AI 的 TypeDOM 经验库 | ⭐⭐⭐ | 优秀案例、常见错误 |
| AI 专用增强层 | AI 的 TypeDOM 外挂大脑 | ⭐⭐ | Prompt 模板、检查清单 |
| 持续改进层 | AI 的 TypeDOM 成长记录 | ⭐⭐ | 优化报告、实施清单 |
实施检查清单
基础层（必需，100% 覆盖）
核心知识类
- TypeDOM 项目元数据 (JSON 格式)
- 架构知识图谱 (Mermaid 图表)
- 核心类型 TypeScript 定义
- 生命周期状态机图
规范规则类
- Class + Hooks + Const 编码规范
- 组件开发模板库
- 命名规范速查表
工具方法类
- Signals API 完整索引
- Hooks 函数完整索引
- Nx Workspace 配置参数
进阶层（重要，≥90% 覆盖）
工作流程类
- AI 工作流程定义 (组件开发/Hook 开发/问题诊断)
- 质量检查清单 (架构/命名/代码质量/测试/无障碍)
测试验证类
- 测试用例模板 (组件/batch/响应式)
- 测试覆盖率要求 (≥90%)
- Vitest 测试规范
部署运维类
- Nx Workspace 管理文档
- 构建和发布流程
- CI/CD 配置准备
高级层（优秀，≥80% 覆盖）
最佳实践类
- 优秀实践案例 (Button 组件等)
- 常见错误示例 (Hook 调用/响应式/异步)
- 性能优化技巧 (batch/缓存/依赖追踪)
AI 专用增强类
- 机器可读元数据 (JSON/Markdown 注释)
- 健康度仪表盘
- Prompt 工程模板 (组件开发/性能优化/Code Review)
持续改进类
- 文档更新日志格式
- 优化改进报告模板
- 实施清单跟踪
持续改进计划
短期目标 (2026 Q2)
- 补充更多业务类型的 TypeScript 定义
- 完善所有核心 API 的 JSDoc 注释
- 为每个 UI 组件添加完整测试
- 建立文档自动化工具 (从代码生成文档)
中期目标 (2026 Q3-Q4)
- 实现文档与代码的同步更新 (CI/CD 集成)
- 开发文档质量检查工具
- 建立文档健康度仪表盘
- 开展文档贡献培训和激励
长期目标 (2027+)
- 实现 AI 自动生成和更新文档
- 建立知识库问答系统
- 输出最佳实践到开源社区
- 成为前端框架文档标杆案例
📞 联系方式
文档创建者 : TypeDOM Core Team
技术负责人 : zhang yin
问题反馈: GitHub Issues 或团队沟通群
📚 相关文档索引
核心文档 (必读)
AI-ASSISTANT-GUIDE.md- AI 助手完全指南 (1,334 行)AI-ASSISTANT-CHEATSHEET.md- 快速参考卡片 (406 行)README-USAGE.md- 使用说明文档 (505 行)
专项文档 (按需查阅)
LIBS/FRAMEWORK/AI-DOCS/- Framework 专项文档LIBS/UI/AI-DOCS/- UI 组件专项文档LIBS/SIGNALS/README.md- Signals 响应式系统
编码规范 (必须遵守)
LIBS/UI/AI-DOCS/CODING-RULES.md- UI 组件编码规范LIBS/FRAMEWORK/AI-DOCS/AI-CODE-CHECKLIST.md- Framework 检查清单
测试相关
BATCH-TEST-GUIDE.md- 测试编写指南BATCH-TEST-FIXES.md- 测试修复报告
文档版本 : v2.0-TypeDOM
创建日期 : 2026-03-11
更新日期 : 2026-03-13
维护者: TypeDOM Core Team
© 2026 TypeDOM Project Team. All Rights Reserved.