catalog/repos/abczsl520--nodejs-project-arch.md

# Node.js项目架构规范

`Node.js` `项目架构` `AI开发` `代码规范` `模块化`

# nodejs-project-arch

**面向 AI 辅助开发的 Node.js 项目架构规范。**

这是一个 [OpenClaw](https://openclaw.ai) / AI 智能体技能，用于强制执行模块化文件结构，将每个文件控制在足够小的体积，使 AI 能够在不超出上下文窗口的情况下读取和编辑。

## ✨ 为什么需要它？

当 AI 智能体处理大型单文件代码库时，问题会迅速暴露：

| 场景 | 每次读取的 Token 数 | 上下文占用（200K） |
|------|----------------|-----------------|
| 3000 行的 `server.js` | ~40K | 20% |
| 200 行的模块 | ~2.7K | 1.3% |

**结论：** 拆分文件意味着在上下文压缩前可完成 **10-15 轮高效操作**，而单体文件只能完成 3-5 轮。这相当于每次文件读取节省了 **70-93% 的 Token**。

## 📐 核心规则

- **单文件 ≤ 400 行** / `index.html` ≤ 200 行 / `server.js` 入口 ≤ 100 行
- **所有可调参数**存入 `config.json`——运行时加载，可通过管理后台编辑
- **后端：** `routes/` 按业务域划分，`services/` 存放共享逻辑，`db.js` 负责数据库初始化
- **前端：** HTML 仅保留骨架，JS/CSS 分离存放于 `public/` 目录下
- **每个项目**都包含 `admin.html` + `routes/admin.js`，用于配置热重载和统计信息

## 🎮 支持的项目类型

| 类型 | 识别信号 | 参考文档 |
|------|---------|---------|
| **H5 游戏** | Canvas、Phaser、Matter.js、游戏循环、精灵图 | [references/game.md](references/game.md) |
| **数据工具** | 爬虫、采集器、调度器、数据同步、数据分析 | [references/tool.md](references/tool.md) |
| **内容/工具类** | 生成器、库、发布工具、文件处理 | [references/tool.md](references/tool.md) |
| **看板/监控** | 图表、实时数据、告警、指标 | [references/tool.md](references/tool.md) |
| **API 服务** | REST 接口、中间件、微服务 | [references/tool.md](references/tool.md) |
| **SDK/库** | 共享模块、构建步骤、多消费者 | [references/sdk.md](references/sdk.md) |

## 📁 典型目录结构

```
project-name/
  server.js          ← 入口文件，仅挂载路由（<100 行）
  config.json        ← 所有可调参数（管理后台可编辑）
  db.js              ← 数据库初始化 + 工具函数
  routes/
    auth.js          ← 认证路由
    game.js          ← 核心游戏/业务路由
    admin.js         ← 管理员 API（配置增删改查、统计信息）
  services/          ← 共享业务逻辑
  public/
    index.html       ← 纯 HTML 骨架（<200 行）
    admin.html       ← 管理后台
    css/style.css
    js/              ← 按职责拆分，每个文件 <400 行
    assets/
```

## 🚀 安装方式

### OpenClaw 用户

将技能复制到你的智能体技能目录：

```bash
# 克隆并复制
git clone https://github.com/abczsl520/nodejs-project-arch.git
cp -r nodejs-project-arch ~/.agents/skills/

# 或者如果你安装了 clawhub：
# clawhub install nodejs-project-arch
```

当你要求 AI 智能体执行以下操作时，该技能会自动激活：
- 创建新的 Node.js 项目
- 重构大型单文件代码库
- 拆分超大文件

### 手动参考

直接浏览参考文档：
- [游戏架构](references/game.md) —— 基于 Canvas/Phaser 的 H5 游戏
- [工具架构](references/tool.md) —— 数据工具、看板、API 服务
- [SDK 架构](references/sdk.md) —— 共享库与 SDK

## 📖 文档

完整文档可在 [Wiki](https://github.com/abczsl520/nodejs-project-arch/wiki) 上查阅：

- [首页](https://github.com/abczsl520/nodejs-project-arch/wiki) —— 概览
- [安装指南](https://github.com/abczsl520/nodejs-project-arch/wiki/Installation) —— 配置步骤
- [游戏架构](https://github.com/abczsl520/nodejs-project-arch/wiki/Game-Architecture) —— H5 游戏规范
- [工具架构](https://github.com/abczsl520/nodejs-project-arch/wiki/Tool-Architecture) —— 非游戏项目规范
- [SDK 架构](https://github.com/abczsl520/nodejs-project-arch/wiki/SDK-Architecture) —— 库/SDK 规范
- [配置模式](https://github.com/abczsl520/nodejs-project-arch/wiki/Config-Pattern) —— 通用 config.json 模式
- [管理后台](https://github.com/abczsl520/nodejs-project-arch/wiki/Admin-Dashboard) —— 管理面板规范
- [Token 节省分析](https://github.com/abczsl520/nodejs-project-arch/wiki/Token-Savings) —— Token 节省效果分析

## 🔧 快速示例：config.json 模式

```javascript
// server.js —— 加载并提供配置
const config = JSON.parse(fs.readFileSync('./config.json', 'utf8'));

app.get('/api/config', (req, res) => {
  const safe = { ...config };
  delete safe.admin;
  res.json(safe);
});

// 管理员热重载
app.post('/admin/config', requireAdmin, (req, res) => {
  fs.writeFileSync('./config.json.bak', fs.readFileSync('./config.json'));
  fs.writeFileSync('./config.json', JSON.stringify(req.body, null, 2));
  Object.assign(config, req.body);
  res.json({ ok: true });
});
```

## 📊 真实场景 Token 节省数据

| 场景 | 优化前 | 优化后 | 节省比例 |
|------|--------|-------|---------|
| 读取游戏功能代码 | ~40K Token | ~2.7K Token | **93%** |
| 单轮开发（读取→编辑→验证） | ~52K Token | ~4K Token | **92%** |
| 4 轮 SDK 开发会话 | ~196K Token | ~69K Token | **65%** |
| 大型数据工具模块 | ~84K Token | ~8K Token | **90%** |

## 🧬 project-arch 家族的一员

该技能实现了 [project-arch-core](https://github.com/abczsl520/project-arch-core) 中针对 Node.js 的专项模式——project-arch-core 是面向 AI 辅助开发的语言无关架构原则集合。

| 技能 | 语言 | 状态 |
|------|------|------|
| **project-arch-core** | 通用原则 | ✅ 基础版 |
| **nodejs-project-arch**（本项目） | Node.js / Express | ✅ 已发布 |
| [react-project-arch](https://github.com/abczsl520/react-project-arch) | React / Vite | ✅ 已发布 |
| python-project-arch | Python | 🔲 欢迎社区贡献 |
| go-project-arch | Go | 🔲 欢迎社区贡献 |

## 许可证

MIT