makemd/doc/AI友好项目结构.md

AI 友好项目结构设计指南

本指南适用于所有项目，帮助 AI 快速理解模块职责、依赖关系和业务流程

---

1. 项目总体设计原则

1.1 模块化

• 每个模块（Module）单一职责，明确功能边界
• 避免跨模块调用深层内部函数，只通过接口或导出函数进行通信

1.2 层级清晰

• 分层原则（Layered Architecture）：
  • core 核心逻辑
  • service 服务/业务逻辑
  • controller 控制层/路由层
  • ui 界面或前端组件
• AI 能通过路径快速推断模块职责

1.3 依赖方向一致

• 只允许高层模块依赖低层模块，禁止低层模块依赖高层模块
• 可用 PROJECT_MAP.md 来可视化依赖关系，帮助 AI 理解边界

1.4 明确接口（Interface）

• 每个模块导出统一接口，并在模块目录下放置 module_info.md 描述：
  • 功能
  • 输入/输出
  • 调用约束

---

2. 推荐项目结构

project-root/
├─ core/                     # 核心模块，最低依赖层
│   ├─ utils/                # 公共工具函数
│   │   ├─ string_utils.js
│   │   └─ array_utils.js
│   └─ constants.js
├─ service/                  # 业务逻辑层
│   ├─ userService/
│   │   ├─ index.js
│   │   └─ module_info.md
│   └─ orderService/
│       ├─ index.js
│       └─ module_info.md
├─ controller/               # 控制层
│   ├─ userController.js
│   └─ orderController.js
├─ ui/                       # 前端组件层
│   ├─ components/
│   └─ pages/
├─ docs/                     # 项目文档
│   ├─ core/
│   ├─ service/
│   ├─ controller/
│   ├─ ui/
│   ├─ architecture/
│   ├─ README.md
│   └─ _nav.yaml
└─ package.json

---

3. AI 友好文件规范

3.1 模块信息文件（module_info.md）

每个模块必须包含：

# UserService 模块
## 功能
- 用户信息管理
- 登录/注册逻辑
- 用户权限验证
## 接口
- `createUser(data: UserData): Promise<User>`
- `getUserById(id: string): Promise<User>`
- `validateUserCredentials(username: string, password: string): Promise<boolean>`
## 依赖
- core/utils
- core/constants
## 被调用方
- controller/userController
## 示例
```javascript
import { createUser } from './userService';
const newUser = await createUser({ username: 'Alice', password: '1234' });
console.log(newUser);

3.2 输入输出映射文件（*_io.yaml）

每个服务模块建议包含：

module: userService
inputs:
  - source: controller/userController.createUser
    type: UserData
  - source: controller/userController.getUser
    type: { id: string }
outputs:
  - destination: controller/userController.sendUserCreatedResponse
    type: User
  - destination: controller/userController.sendUserResponse
    type: User

3.3 项目文档文件

文件	用途
PROJECT_MAP.md	模块依赖关系可视化
PROJECT_RULES.md	编码和依赖规范
ARCHITECTURE.md	架构说明
FEATURE_MAP.md	功能模块映射
CALL_MAP.md	业务调用链
_nav.yaml	结构化文档路由

---

4. 文档路由优化

4.1 分层路由结构

docs/
├─ core/
│   └─ utils.md
├─ service/
│   ├─ userService.md
│   └─ orderService.md
├─ controller/
│   ├─ userController.md
│   └─ orderController.md
├─ architecture/
│   ├─ PROJECT_MAP.md
│   ├─ PROJECT_RULES.md
│   ├─ FEATURE_MAP.md
│   └─ CALL_MAP.md
├─ README.md         # 索引页
└─ _nav.yaml         # 结构化路由文件

4.2 统一文档结构

每个模块文档保持相同的结构：

1. 功能
2. 接口
3. 输入输出
4. 依赖
5. 被调用方
6. 示例

4.3 跨文档引用

使用相对链接引用依赖模块：

## 依赖
- [core/utils](../core/utils.md)
- [userService](../service/userService.md)

---

5. 可视化工具

5.1 依赖图生成

生成脚本（generate_mermaid.js）：

const fs = require('fs');
const path = require('path');
const yaml = require('js-yaml');

const NAV_FILE = path.join(__dirname, 'docs/_nav.yaml');
const OUTPUT_FILE = path.join(__dirname, 'docs/DEPENDENCY_GRAPH.md');

// 读取 _nav.yaml
const navContent = fs.readFileSync(NAV_FILE, 'utf-8');
const navData = yaml.load(navContent);

// 用于存储 Mermaid 节点和依赖
let nodes = [];
let edges = [];

// 遍历模块生成节点
navData.forEach(moduleGroup => {
  moduleGroup.docs.forEach(doc => {
    const moduleName = `${moduleGroup.module}/${doc.name}`;
    nodes.push(moduleName);
    
    // 尝试读取 module_info.md 获取依赖
    const modulePath = path.join(__dirname, 'docs', moduleGroup.module, `${doc.name}.md`);
    if (fs.existsSync(modulePath)) {
      const mdContent = fs.readFileSync(modulePath, 'utf-8');
      const depMatches = [...mdContent.matchAll(/## 依赖\s*([\s\S]*?)(?:##|$)/g)];
      if (depMatches.length) {
        const depText = depMatches[0][1];
        const depLines = depText.split('\n').map(l => l.trim()).filter(Boolean);
        depLines.forEach(depLine => {
          // 解析 Markdown 链接 [模块](路径)
          const match = depLine.match(/\[([^\]]+)\]/);
          if (match) {
            const depModule = match[1].replace(/\//g, '/');
            edges.push({ from: moduleName, to: depModule });
          }
        });
      }
    }
  });
});

// 生成 Mermaid 文件
let mermaidContent = '```mermaid\nflowchart TD\n';

// 添加节点
nodes.forEach(node => {
  const safeNode = node.replace(/\//g, '_');
  mermaidContent += `    ${safeNode}[${node}]\n`;
});

// 添加边
edges.forEach(edge => {
  const fromNode = edge.from.replace(/\//g, '_');
  const toNode = edge.to.replace(/\//g, '_');
  mermaidContent += `    ${fromNode} --> ${toNode}\n`;
});

mermaidContent += '```';

// 写入文件
fs.writeFileSync(OUTPUT_FILE, mermaidContent, 'utf-8');
console.log('✅ DEPENDENCY_GRAPH.md 已生成');

5.2 调用链生成

升级版脚本：同时生成依赖图和调用链

---

6. AI 友好特性

6.1 模块边界清晰

• 每个模块都有 module_info.md + io_map.yaml
• 明确的输入输出和依赖关系

6.2 依赖透明化

• PROJECT_MAP.md 和 FEATURE_MAP.md 让 AI 快速理解依赖和功能分类
• 可视化依赖图帮助识别循环依赖

6.3 调用链可视化

• CALL_MAP.md 让 AI 理解业务流程
• Mermaid 图表直观展示调用关系

6.4 标准化接口

• 所有函数和模块都有明确输入输出类型
• 统一的文档结构便于 AI 解析

6.5 示例代码

• examples/ 提供最小调用示例，方便 AI 理解使用方式

---

7. 最佳实践

7.1 命名规范

• 模块名：小写短横线（kebab-case）
• 函数名：驼峰命名（camelCase）
• 类名：大驼峰命名（PascalCase）
• 常量：全大写（UPPER_CASE）

7.2 文件大小限制

• 单文件：≤ 2000 行
• 单函数：≤ 120 行
• 模块：≤ 10 文件

7.3 依赖规则

• 高层模块可以依赖低层模块
• 低层模块不能依赖高层模块
• 同级模块可以相互依赖，但要避免循环依赖

7.4 文档维护

• 新增模块时更新 _nav.yaml
• 修改依赖时更新 PROJECT_MAP.md
• 保持文档与代码同步

---

8. 工具推荐

8.1 依赖分析工具

• JS/TS: madge、dependency-cruiser
• Python: pydeps

8.2 文档生成工具

• Markdown: VS Code + Markdown Preview Enhanced
• Mermaid: 支持流程图和时序图

8.3 代码质量工具

• ESLint: 代码风格检查
• Prettier: 代码格式化
• TypeScript: 类型检查

---

9. 模板文件

9.1 模块信息模板（module_info.md）

# {模块名} 模块
## 功能
- 功能1
- 功能2
- 功能3
## 接口
- `method1(param1: type): returnType`
- `method2(param1: type, param2: type): returnType`
## 输入输出
- 输入: 来源和类型
- 输出: 目标和类型
## 依赖
- [依赖模块1](路径)
- [依赖模块2](路径)
## 被调用方
- 调用方1
- 调用方2
## 示例
```javascript
// 使用示例

9.2 输入输出模板（*_io.yaml）

module: {模块名}
inputs:
  - source: 来源模块.方法
    type: 输入类型
outputs:
  - destination: 目标模块.方法
    type: 输出类型

9.3 导航模板（_nav.yaml）

- module: core
  docs:
    - name: utils
      path: core/utils.md
    - name: constants
      path: core/constants.md
- module: service
  docs:
    - name: userService
      path: service/userService.md
    - name: orderService
      path: service/orderService.md

---

10. 总结

AI 友好项目结构的核心是：

1. 清晰的模块边界：每个模块有明确的职责和接口
2. 一致的依赖方向：高层依赖低层，避免循环
3. 标准化的文档：统一结构，便于 AI 解析
4. 可视化的依赖关系：帮助 AI 理解整体架构
5. 示例代码：方便 AI 学习使用方式

通过这套结构，AI 可以：

• 快速理解模块职责和依赖关系
• 避免循环依赖和架构混乱
• 定位问题和辅助重构
• 生成符合项目规范的代码

---

本指南适用于所有项目，可根据具体项目需求进行调整。