sapientpants/agentic-node-ts-starter

# Agentic Node + TypeScript 启动模板 ## 📊 构建状态与质量指标 ### CI/CD 工作流 [](https://github.com/sapientpants/agentic-node-ts-starter/actions/workflows/main.yml) [](https://github.com/sapientpants/agentic-node-ts-starter/actions/workflows/pr.yml) [](https://github.com/sapientpants/agentic-node-ts-starter/actions/workflows/codeql.yml) ### 测试覆盖率与质量 [](https://github.com/sapientpants/agentic-node-ts-starter/actions) [](https://github.com/sapientpants/agentic-node-ts-starter/actions) [](https://github.com/sapientpants/agentic-node-ts-starter/actions) ### 代码质量指标 [](https://github.com/sapientpants/agentic-node-ts-starter/actions) [](https://github.com/sapientpants/agentic-node-ts-starter/actions) ### 元信息 [](LICENSE) [](https://nodejs.org) [](https://pnpm.io) [](https://github.com/sapientpants/agentic-node-ts-starter/releases) 一个**功能完备**的 TypeScript 启动模板，包含全面的测试、代码质量自动化和安全扫描。专为现代 Node.js 开发与 AI 辅助编码工作流构建。 ## 🤔 什么是 Agentic 开发？ **“Agentic”在此语境下指的是 AI 辅助的开发工作流**，而非 AI 智能体运行时。此模板旨在与 [Claude Code](https://claude.ai/code) 等 AI 开发工具无缝协作，通过以下方式提升您的生产力： - 🤖 **AI 驱动的代码生成** - 让 AI 助手协助编写样板代码和测试 - 🔄 **自动化重构** - AI 工具可以在全面的测试覆盖下安全地进行重构 - 📝 **文档辅助** - AI 可以帮助维护文档与代码的同步 - 🎯 **Issue 到实现的工作流** - 用于 AI 驱动开发的自定义命令 ## 🛠️ 技术栈 **核心：** Node.js 22+ • TypeScript ^5.9.2 (strict) • pnpm 10.15 **测试：** Vitest • fast-check (property testing) • 最低 80% 覆盖率 **质量：** ESLint 9 • Prettier • Husky • Commitlint **安全：** CodeQL • OSV Scanner • SBOM • SLSA attestations **CI/CD：** GitHub Actions • Changesets • 自动化发布 ## 📖 文档 **[完整文档 →](./docs/README.md)** - **[快速入门](./docs/GETTING_STARTED.md)** - 设置和安装 - **[开发指南](./docs/DEVELOPMENT.md)** - 工作流和命令 - **[测试](./docs/TESTING.md)** - 测试模式和覆盖率 - **[Docker](./docs/DOCKER.md)** - Docker 配置和健康检查 - **[模式](./docs/PATTERNS.md)** - 复制粘贴代码示例 - **[故障排除](./docs/TROUBLESHOOTING.md)** - 常见问题 ## 🚀 快速开始 ``` # Clone 和设置 git clone https://github.com/sapientpants/agentic-node-ts-starter.git my-project cd my-project # 安装依赖 (需要 Node.js 22+ 和 pnpm 10.15) pnpm install # 设置配置 (必需) cp .env.example .env # 使用你的配置编辑 .env # 有关必需的环境变量，请参阅 docs/CONFIG.md # 验证一切正常 pnpm test pnpm verify # Full quality check # 开始开发 pnpm dev # TypeScript watch mode ``` **前置条件：** Node.js 22+, pnpm 10.15, GitHub 仓库 (用于 CI/CD) **完整设置指南：** [docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md) ## 📚 主要命令 ``` # 开发 pnpm dev # TypeScript watch mode pnpm build # Build to dist/ pnpm verify # Run all quality checks # 测试 (需要 80% 覆盖率) pnpm test # Run tests pnpm test:watch # Watch mode pnpm test:coverage # With coverage report # 质量 pnpm lint # Check linting pnpm lint:fix # Fix linting issues pnpm format # Check formatting pnpm format:fix # Fix formatting pnpm typecheck # Type check only # 发布 pnpm changeset # Create changeset pnpm sbom # Generate SBOM ``` **完整命令参考：** [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) ## 📊 代码质量仪表板 每次 CI 运行时自动追踪全面的质量指标： ### 测试指标 | 指标 | 当前值 | 阈值 | 状态 | 本地命令 | | ---------------------- | ------- | --------- | ---------- | -------------------- | | **行覆盖率** | 93.77% | ≥80% | ✅ 通过 | `pnpm test:coverage` | | **分支覆盖率** | 84.95% | ≥80% | ✅ 通过 | `pnpm test:coverage` | | **函数覆盖率** | 100% | ≥80% | ✅ 通过 | `pnpm test:coverage` | | **语句覆盖率** | 93.65% | ≥80% | ✅ 通过 | `pnpm test:coverage` | | **变异分数** | N/A | ≥80% | ⏳ 待定 | `pnpm mutation-test` | ### 代码质量指标 | 指标 | 当前值 | 阈值 | 状态 | 本地命令 | | --------------------------- | ------- | --------- | ------- | -------------------- | | **代码重复率** | 0% | <2% | ✅ 通过 | `pnpm duplication` | | **圈复杂度** | 最大 10 | ≤10 | ✅ 通过 | `pnpm lint` | | **函数最大行数** | 最大 50 | ≤50 | ✅ 通过 | `pnpm lint` | | **函数最大参数数量** | 最大 4 | ≤4 | ✅ 通过 | `pnpm lint` | | **最大嵌套深度** | 最大 3 | ≤3 | ✅ 通过 | `pnpm lint` | | **循环依赖** | 0 | 0 | ✅ 通过 | `pnpm deps:circular` | | **死代码** | 0 | 0 | ✅ 通过 | `pnpm dead-code` | ### 安全指标 | 指标 | 状态 | 工具 | 本地命令 | | ----------------------------- | ------ | ----------- | --------------------- | | **严重漏洞** | ✅ 0 | pnpm audit | `pnpm audit` | | **高危漏洞** | ✅ 0 | OSV Scanner | 仅 CI | | **CodeQL 发现** | ✅ 0 | CodeQL | 仅 CI | | **容器漏洞** | ✅ 0 | Trivy | `pnpm scan:container` | ### 构建与依赖 | 指标 | 状态 | 工具 | 本地命令 | | -------------------------- | ------- | ---------- | --------------------- | | **TypeScript 编译** | ✅ 通过 | tsc | `pnpm typecheck` | | **ESLint 违规** | ✅ 0 | ESLint | `pnpm lint` | | **Prettier 格式化** | ✅ 通过 | Prettier | `pnpm format` | | **工作流验证** | ✅ 通过 | actionlint | `pnpm lint:workflows` | ### 使用的工具和分析器 - **覆盖率：** Vitest with V8 coverage provider - **变异测试：** Stryker Mutator (JavaScript/TypeScript) - **重复检测：** jscpd (Copy/Paste Detector) - **复杂度：** ESLint with complexity rules - **循环依赖：** madge (dependency graph analyzer) - **死代码：** Knip (unused exports, files, dependencies, types) - **安全：** pnpm audit, OSV Scanner, CodeQL, Trivy - **类型安全：** TypeScript strict mode + type-aware ESLint rules ## 🎯 质量标准 本项目执行严格的质量标准，以确保可维护性、安全性和可靠性： ### 为什么制定这些标准？ **80% 最低覆盖率** - 确保全面的测试覆盖，而不强求 100%（这可能导致收益递减） **低复杂度限制** - 圈复杂度 > 10 的函数更难理解、测试和维护 **零重复目标** - DRY 原则减少了维护负担和 Bug **无循环依赖** - 防止紧耦合并实现更好的模块化 **无死代码** - 保持代码库精简和可维护 **零严重/高危漏洞** - 安全优先的方法保护用户和基础设施 ### 复杂度理由 | 限制 | 理由 | | ------------------------- | ----------------------------------------------------------------- | | 圈复杂度 ≤10 | 可维护代码的行业标准 (NIST, IEEE) | | 函数最多 50 行 | 单屏视图提高理解能力 | | 最多 4 个参数 | 减少认知负荷，鼓励更好的抽象 | | 最大嵌套深度 3 | 防止难以推理的深层嵌套代码 | | 最多 15 条语句 | 强制函数分解，提高可测试性 | | 代码重复率 <2% | 允许少量必要重复的最低阈值 | | 变异分数 ≥80% | 确保测试实际验证行为，而不仅仅是达到覆盖率 | ### 测试文件例外 测试文件 (`tests/**/*.ts`) 有放宽的限制： - 圈复杂度：≤15 (vs 10) - 每个函数最大行数：≤600 (vs 50) - 允许包含大量测试用例的大型 describe 块 ### Pre-commit 质量门禁 `pnpm precommit` 命令按优化顺序运行检查，以提供快速反馈： 1. **安全** (`pnpm audit`) - 阻止有严重漏洞的提交 2. **格式化** (`pnpm format`) - 快速，易于修复 3. **YAML/Markdown Lint** - 快速文件验证 4. **工作流验证** - 防止 GitHub Actions 损坏 5. **类型检查** (`pnpm typecheck`) - 类型感知 lint 规则所需 6. **Linting** (`pnpm lint`) - 全面的质量检查 7. **结构分析** - 循环依赖、重复代码、死代码 8. **测试与覆盖率** (`pnpm test:coverage`) - 最慢的检查放在最后 **变异测试**由于性能原因不包含在 pre-commit 中 - 定期运行（每周/每月）。 ## 🤖 Claude Code 集成 本项目包含 [Claude Code](https://claude.ai/code) 的特殊配置： ### 自定义命令 - `/analyze-and-fix-github-issue` - 修复 GitHub issue 的完整工作流 - `/release` - 自动化发布流程 - `/update-dependencies` - 带有 PR 工作流的依赖更新 ### Git 钩子 - 防止使用 `--no-verify` 标志绕过验证 - 确保所有提交通过质量检查 详情请参阅 [CLAUDE.md](./CLAUDE.md) 获取 Claude Code 的详细指南。 ## 📁 项目结构 ``` . ├── .claude/ # Claude Code configurations │ ├── commands/ # Custom slash commands │ └── hooks/ # Git hook scripts ├── .github/ # GitHub Actions workflows ├── docs/ # Documentation ├── src/ # Source code ├── tests/ # Test files │ ├── *.spec.ts # Unit tests │ └── *.property.spec.ts # Property-based tests ├── mise.toml # Tool version management ├── package.json # Dependencies and scripts └── tsconfig.json # TypeScript configuration ``` ## 🔄 功能特性 ### 配置与环境 - 🔐 **类型安全的配置**，使用 Zod 验证 - 🔌 **可配置的日志输出** - 将日志重定向到 stderr、文件、syslog 或完全禁用（参见 [docs/LOGGING_OUTPUT.md](./docs/LOGGING_OUTPUT.md)） - 🔐 **启动时的环境验证**，带有清晰的错误提示 - 🔐 **错误消息中的敏感值脱敏** - 📝 配置指南请参见 [docs/CONFIG.md](./docs/CONFIG.md) ### 测试与质量 - ✅ **Vitest** 配合基于属性的测试 - ✅ **强制执行 80% 最低覆盖率** - ✅ **严格的 TypeScript** 配合类型感知的 linting - ✅ **Pre-commit 钩子**，使用 Husky & lint-staged - ✅ **Markdown 和 YAML lint**，确保文档/配置一致性 ### 安全与供应链 - 🔒 **CodeQL** 静态分析 - 🔒 **OSV Scanner** 依赖扫描 - 🔒 **SBOM 生成** (CycloneDX) - 🔒 **SLSA attestations** 用于制品 ### 自动化 - 🚀 **GitHub Actions** CI/CD 流水线 - 🚀 **Changesets** 版本管理 - 🚀 **自动化发布**及变更日志 - 🚀 **Claude Code** 集成 ## ⚙️ 必要设置 ### GitHub 仓库设置 **Actions 权限** (Settings → Actions → General): - ✅ Read and write permissions - ✅ Allow GitHub Actions to create and approve pull requests **自动合并** (Settings → General → Pull Requests): - ✅ Allow auto-merge - ✅ Automatically delete head branches **对于自动化发布**，添加密钥： - `RELEASE_TOKEN` - 具有 repo/workflow 权限的 GitHub PAT（触发发布工作流） - `NPM_TOKEN` - 用于 npm 发布（可选） ## 📦 发布分发 ### NPM 发布 启用 npm 发布： 1. 在仓库设置中添加 `NPM_TOKEN` secret 2. 从 package.json 中移除 `"private": true` 3. 使用作用域包名：`@yourorg/package-name` ### Docker 发布 启用 Docker 构建： 1. 设置仓库变量 `ENABLE_DOCKER_RELEASE` 为 `true` 2. 为 Docker Hub 添加密钥（可选）： - `DOCKERHUB_USERNAME` - `DOCKERHUB_TOKEN` 3. 镜像会自动推送到 GitHub Container Registry ## 🔒 安全特性 - **依赖审计**：每次 CI 运行时检查严重漏洞 - **SBOM 生成**：CycloneDX 格式，用于供应链透明度 - **CodeQL 分析**：静态安全分析 - **OSV 扫描**：开源漏洞检测 - **SLSA 来源证明**：构建证明 - **容器证明**：Docker 镜像的 SBOM 和来源证明 ## 📚 其他资源 - [贡献指南](./CONTRIBUTING.md) - 如何为本项目做出贡献 - [开发流程](./docs/PROCESS.md) - 端到端工作流和检查清单 - [架构决策](./docs/architecture/decisions/) - ADR 记录 ## 📄 许可证 这是一个模板仓库。可随意用于您的项目。

标签：Agentic, AI辅助开发, Anchore, Boilerplate, Claude Code, CodeQL, DevSecOps, DNS 反向解析, GNU通用公共许可证, MITM代理, Node.js, OSV, SBOM, TypeScript, Vercel, 上游代理, 企业级, 复杂度控制, 安全扫描, 安全插件, 安全评估工具, 属性测试, 文档安全, 时序注入, 测试覆盖率, 生产就绪, 硬件无关, 脚手架, 自动化攻击, 请求拦截, 跌倒检测, 软件物料清单, 项目模板