内容
# node-boost
node-boost 是 Node 生态系统的 Boost：一个 CLI 和 MCP 指导层，安装项目特定的 AI 指令、代理技能、审计规则和守卫钩子。v0.1 针对 React 应用，对 Next.js 和 Vite React 项目提供一流支持。
无遥测。node-boost 读取本地项目，写入本地文件，不进行远程调用。
## 快速开始
```sh
npm i -D @node-boost/node-boost
npx node-boost install
```
npm 包以 `@node-boost/node-boost` 发布；安装的 CLI 二进制文件为 `node-boost`。
安装程序检测您的技术栈，写入 `node-boost.json`，组合 `.ai/guidelines/**` 和 `.ai/skills/**`，并配置选定的代理：
- Claude Code: `CLAUDE.md`，`.claude/skills/**`，`.mcp.json`，可选 `.claude/settings.json` 钩子。
- Codex: `AGENTS.md`，`.agents/skills/**`，`.codex/config.toml`，可选 `.codex/hooks.json`。
- Cursor: `.cursor/rules/node-boost.mdc`，`.cursor/mcp.json`，可选 `.cursor/hooks.json`。
## CLI
| 命令 | 目的 |
| --- | --- |
| `node-boost install` | 生成指南、技能、配置、MCP 和可选的钩子文件。 |
| `node-boost update` | 从 `node-boost.json` 重新生成，无需提示。 |
| `node-boost doctor` | 检查配置、生成的资源、代理文件、钩子、覆盖和 TS 严格性。 |
| `node-boost audit` | 扫描源文件以检查启用的架构规则。 |
| `node-boost guard` | 将 `audit --changed --agent` 作为硬 CI/代理门控运行。 |
| `node-boost explain NB-ARCH-005` | 解释发现结果并将其链接回生成的指南。 |
| `node-boost mcp` | 在标准输入/输出上启动 MCP 服务器。 |
机器可读命令使用 `--agent`：
```sh
npx node-boost audit --all --agent
npx node-boost doctor --agent
```
## MCP 工具
| 工具 | 目的 |
| --- | --- |
| `application_info` | 返回检测到的技术栈、包管理器、包、路由和 node-boost 配置摘要。 |
| `list_routes` | 列出 Next 应用路由，包括路由处理程序和平行插槽。 |
| `doctor` | 运行与 `node-boost doctor` 相同的完整检查。 |
| `audit` | 运行 `node-boost audit --all` 并返回 JSON。 |
| `explain_finding` | 解释 `NB-ARCH-005` 等规则。 |
## 架构模式
| 模式 | 保护内容 |
| --- | --- |
| `feature-modules` | 功能边界。变体 `public-api` 允许通过 `index.ts` 进行导入；变体 `forbid` 阻止所有跨功能导入。 |
| `server-first-components` | Next 应用条目保持服务器优先；客户端代码移动到子边界。 |
| `data-access-layer` | 组件调用数据函数或查询钩子，而不是原始网络客户端。 |
| `typed-contracts` | 环境和 JSON 边界集中且已验证。 |
| `state-management` | 客户端存储保存 UI 状态，而不是获取的服务器状态。 |
| `custom-hooks` | 仅为实际重用、易读性或可测试性提取钩子。 |
| `component-composition` | UI 组合保持显式且可测试。 |
| `styling-tailwind` | Tailwind 版本特定约定保持当前。 |
| `testing-strategy` | 测试目标用户可见行为和高风险边界。 |
| `error-loading-boundaries` | 异步 Next 分段具有加载/错误边界。 |
| `secure-by-default` | 默认检查公共环境名称和 HTML 注入。 |
| `modern-typescript` | 严格的 TS 且源代码中没有显式的 `any`。 |
| `ui-states` | 有意表示加载、空、错误、禁用和乐观状态。 |
## 审计和守卫
`audit` 从 `node-boost.json` 读取启用的架构：
```sh
npx node-boost audit --all
npx node-boost audit --changed --agent
npx node-boost audit --base origin/main --agent
```
仅当有原因时才禁止发现结果：
```ts
// nb-disable NB-ARCH-005 -- 旧 SDK 必须在后续版本中包装
```
没有 `-- reason` 的抑制被报告为 `NB-META-001`。
## 钩子
当启用 `features.hooks` 时，node-boost 将 `guard --hook <agent>` 连接到每个选定的代理：
- Claude Code: `.claude/settings.json` 中的 `Stop` 钩子。
- Codex: `.codex/hooks.json` 中的 `Stop` 钩子。
- Cursor: `.cursor/hooks.json` 中的 `stop` 钩子。
钩子审计更改的文件。错误发现阻止或继续代理在其原生协议中。禁用钩子，设置：
```json
{
"features": {
"hooks": false
}
}
```
然后运行：
```sh
npx node-boost update
```
## 配置
`node-boost.json` 是真实来源：
```json
{
"version": 1,
"generatedWith": "0.1.0",
"stack": "next",
"agents": ["claude-code", "codex", "cursor"],
"features": {
"guidelines": true,
"skills": true,
"mcp": true,
"architecture": true,
"hooks": false
},
"architectures": [
{ "name": "feature-modules", "boundary": "public-api" },
"server-first-components",
"data-access-layer"
],
"audit": {
"exclude": [],
"rules": {
"NB-ARCH-007": "off",
"NB-ARCH-002": "warn"
},
"ruleOptions": {
"NB-ARCH-005": {
"dataLayerGlobs": ["**/api/**", "src/orval/**"]
}
}
}
}
```
项目覆盖存放在 `.node-boost/**` 下，在 `install` 和 `update` 期间隐藏内置资源。
## CI
示例拉取请求守卫：
```yaml
name: Node Boost Guard
on:
pull_request:
push:
branches: [main]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7.0.0
with:
fetch-depth: 0
- uses: actions/setup-node@v6.4.0
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run check
- run: npx node-boost guard --base origin/main
```
此仓库还包含一个包 CI 工作流，位于 `.github/workflows/ci.yml`。
## Git 忽略
保留实现计划本地化，除非您的团队希望发布：
```gitignore
implementation-plans/
```
生成的 `.ai/**`、代理文件和 `node-boost.json` 意在消费者项目中提交。
## 路线图
- 当前 React 技术栈以外的第三方包指南，
- Angular，
- Vue，
- React Native，
- v1 待办事项中额外的架构模式。
