Node.js项目架构规范

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

nodejs-project-arch

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

这是一个 OpenClaw / 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/tool.md
内容/工具类	生成器、库、发布工具、文件处理	references/tool.md
看板/监控	图表、实时数据、告警、指标	references/tool.md
API 服务	REST 接口、中间件、微服务	references/tool.md
SDK/库	共享模块、构建步骤、多消费者	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 用户

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

# 克隆并复制
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 项目
重构大型单文件代码库
拆分超大文件

手动参考

直接浏览参考文档：

游戏架构 —— 基于 Canvas/Phaser 的 H5 游戏
工具架构 —— 数据工具、看板、API 服务
SDK 架构 —— 共享库与 SDK

📖 文档

完整文档可在 Wiki 上查阅：

首页 —— 概览
安装指南 —— 配置步骤
游戏架构 —— H5 游戏规范
工具架构 —— 非游戏项目规范
SDK 架构 —— 库/SDK 规范
配置模式 —— 通用 config.json 模式
管理后台 —— 管理面板规范
Token 节省分析 —— Token 节省效果分析

🔧 快速示例：config.json 模式

// 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 中针对 Node.js 的专项模式——project-arch-core 是面向 AI 辅助开发的语言无关架构原则集合。

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

许可证

MIT

6.1 KiB Raw Blame History Unescape Escape