Inspectra

   [](https://github.com/Fascinax/Inspectra/actions/workflows/validate-config.yml) [](https://www.npmjs.com/package/inspectra)  **多智能体代码审计系统**，由 GitHub Copilot Custom Agents 和 MCP 驱动。 Inspectra 协调多个专业审计智能体——涵盖安全、测试、架构、规范、性能、文档、技术债务、无障碍、API 设计、可观测性和 i18n——生成结构化、可评分且可操作的代码质量报告。 ## 支持的语言 ### 完整支持（Phase 1 工具 + Phase 2 LLM）    ### 部分支持（仅 Phase 2 LLM）        ## 安装 ``` # Clone 仓库 git clone https://github.com/Fascinax/Inspectra.git cd Inspectra # 安装依赖 npm install # 构建 MCP server npm run build # 全局安装 npm install -g . ``` ## 快速开始 ### 前置条件 - Node.js 20+ - npm 10+ - 支持 Custom Agents 的 GitHub Copilot ### 选项 A — 全局设置（推荐，零项目占用） ``` inspectra setup ``` 此命令将所有内容安装到你的 VS Code 用户目录：* - MCP 服务器注册在 VS Code 用户设置中 - 智能体和提示词在所有项目中全局可用 然后在 VS Code 中打开**任意**项目 → Copilot Chat → 输入 `/audit`。 不会向你的项目中添加任何文件。 ### 选项 A′ — Claude Code 设置 ``` cd /path/to/my-project inspectra setup --claude ``` 此命令会在当前目录创建： - `.mcp.json` — Claude Code 自动连接到 Inspectra MCP 服务器 - `CLAUDE.md` — 包含审计说明、工具列表、评分模型的项目上下文 - `policies/` + `schemas/` — 评分规则和合约 然后使用 Claude Code 打开项目并请求运行审计。 详见 [docs/claude-code-setup.md](docs/claude-code-setup.md)。 ### 选项 A″ — OpenAI Codex 设置 ``` cd /path/to/my-project inspectra setup --codex ``` 此命令会在当前目录创建： - `AGENTS.md` — Codex 将其作为项目指令（审计工作流、工具、评分） - `.codex/config.toml` — MCP 服务器配置（Codex 自动连接） - `policies/` + `schemas/` — 评分规则和合约 然后运行 `codex "Run a full Inspectra audit on this project."` 详见 [docs/codex-setup.md](docs/codex-setup.md)。 ### 选项 B — 按项目设置（符号链接，gitignored） ``` inspectra init /path/to/my-project ``` 此命令在目标项目中创建符号链接的智能体（自动 gitignored）： - `.github/agents/` — 在 Copilot 下拉菜单中可见的智能体（符号链接，gitignored） - `.github/prompts/` — 审计提示词快捷方式（符号链接，gitignored） - `.vscode/mcp.json` — 项目打开时 MCP 服务器自动启动 - `policies/` + `schemas/` — 评分规则和合约（已复制） 在 Windows 上使用目录连接点（无需开发者模式或提权）。在 Unix 上使用文件符号链接。 ### 选项 C — 按项目设置（提交副本） ``` inspectra init /path/to/my-project --copy ``` 与选项 B 相同，但文件是与仓库一起提交的真实副本。适用于 CI 或团队成员未安装 Inspectra 的情况。 ### 运行审计 在 VS Code 中打开目标项目，打开 Copilot Chat，然后输入： - `/audit` ：完整审计（全部 12 个领域，自动选择智能体） - `/audit-pr` ：针对已更改文件的审计 ## 使用方法 ### 运行审计 **完整审计**（全部 12 个领域）： ``` /audit ``` **PR 审计**（仅已更改文件）： ``` /audit-pr ``` **特定领域审计**： ``` @audit-security Audit security vulnerabilities in this project @audit-tests Analyze test coverage and quality @audit-architecture Review project architecture and dependencies @audit-conventions Check code conventions and style @audit-performance Analyze bundle sizes and performance @audit-documentation Review documentation completeness @audit-tech-debt Identify technical debt hotspots @audit-accessibility Check WCAG compliance and ARIA attributes @audit-api-design Review REST API conventions @audit-observability Check logging, tracing, and health endpoints @audit-i18n Verify internationalization setup ``` ### 处理报告 **生成 HTML 报告**： ``` inspectra render report.json --html ``` **导出为 PDF**： ``` inspectra render report.json --pdf ``` **比较报告**： ``` inspectra compare baseline.json current.json ``` **查看趋势**： ``` inspectra trend report1.json report2.json report3.json ``` ### CLI 命令 | 命令 | 描述 | | --------- | ------------- | | `inspectra setup` | 全局设置（VS Code 用户设置） | | `inspectra setup --claude` | Claude Code 设置（当前目录） | | `inspectra setup --codex` | OpenAI Codex 设置（当前目录） | | `inspectra init ` | 使用符号链接的按项目设置 | | `inspectra init --copy` | 使用副本的按项目设置 | | `inspectra doctor` | 诊断安装问题 | ### 环境变量 | 变量 | 默认值 | 描述 | | ---------- | --------- | ------------- | | `INSPECTRA_LOG_LEVEL` | `info` | 日志详细程度（`debug`、`info`、`warn`、`error`） | | `INSPECTRA_PROFILE` | `generic` | 活动策略配置文件 | | `NODE_ENV` | `production` | 运行时环境 | ### 配置文件选择 配置文件基于 package.json 和 pom.xml 自动检测。显式覆盖： ``` { "inspectra": { "profile": "java-angular-playwright" } } ``` 或通过环境变量： ``` export INSPECTRA_PROFILE=java-backend ``` ## 项目结构 ``` inspectra/ ├─ .github/ │ ├─ agents/ # Copilot Custom Agent profiles │ │ ├─ audit-orchestrator.agent.md │ │ ├─ audit-security.agent.md │ │ ├─ audit-tests.agent.md │ │ ├─ audit-architecture.agent.md │ │ ├─ audit-conventions.agent.md │ │ ├─ audit-performance.agent.md │ │ ├─ audit-documentation.agent.md │ │ ├─ audit-tech-debt.agent.md │ │ ├─ audit-accessibility.agent.md │ │ ├─ audit-api-design.agent.md │ │ ├─ audit-observability.agent.md │ │ └─ audit-i18n.agent.md │ ├─ prompts/ # Reusable prompt files │ │ ├─ audit.prompt.md │ │ └─ audit-pr.prompt.md │ ├─ workflows/ # GitHub Actions CI/CD │ │ └─ validate-config.yml # Build, test & validate on push/PR │ └─ copilot-instructions.md │ ├─ mcp/ # MCP server (TypeScript) │ └─ src/ │ ├─ index.ts # Server entry point │ ├─ types.ts # Zod schemas & TypeScript types │ ├─ tools/ │ │ ├─ security.ts # inspectra_scan_secrets, inspectra_check_deps_vulns │ │ ├─ tests.ts # inspectra_parse_coverage, inspectra_parse_test_results, inspectra_detect_missing_tests │ │ ├─ architecture.ts # inspectra_check_layering, inspectra_analyze_dependencies │ │ ├─ conventions.ts # inspectra_check_naming, inspectra_check_file_lengths, inspectra_check_todos │ │ ├─ performance.ts # inspectra_analyze_bundle_size, inspectra_check_build_timings │ │ ├─ documentation.ts # inspectra_check_readme_completeness, inspectra_check_adr_presence │ │ ├─ tech-debt.ts # inspectra_analyze_complexity, inspectra_age_todos │ │ ├─ accessibility.ts # inspectra_check_a11y_templates │ │ ├─ api-design.ts # inspectra_check_rest_conventions │ │ ├─ observability.ts # inspectra_check_observability │ │ ├─ i18n.ts # inspectra_check_i18n │ │ └─ adapter.ts # inspectra_generate_claude_md │ ├─ merger/ │ │ ├─ merge-findings.ts # inspectra_merge_domain_reports tool │ │ ├─ deduplicate.ts # Deduplication logic │ │ └─ score.ts # Scoring engine │ ├─ register/ # Tool registration modules │ ├─ policies/ # Policy loader & scoring defaults │ └─ utils/ # Shared utilities (files, paths, project-config) │ ├─ schemas/ # JSON Schema contracts │ ├─ finding.schema.json │ ├─ domain-report.schema.json │ ├─ consolidated-report.schema.json │ └─ scoring.schema.json │ ├─ policies/ # Scoring rules & stack profiles │ ├─ severity-matrix.yml │ ├─ scoring-rules.yml │ ├─ deduplication-rules.yml │ ├─ confidence-rules.yml │ └─ profiles/ │ ├─ generic.yml │ ├─ java-angular-playwright.yml │ ├─ java-backend.yml │ ├─ angular-frontend.yml │ └─ typescript-node.yml │ ├─ scripts/ # Dev & CI utility scripts │ ├─ bootstrap.sh │ ├─ validate-schemas.sh │ ├─ lint-agents.sh │ └─ smoke-test-mcp.sh │ ├─ examples/ # Sample outputs │ ├─ findings/ │ └─ reports/ │ ├─ docs/ # Documentation │ ├─ architecture.md │ ├─ adding-a-tool.md │ ├─ adding-an-agent.md │ ├─ output-format.md │ ├─ scoring-model.md │ ├─ agent-governance.md │ └─ roadmap.md │ ├─ Makefile # Unified command runner └─ bin/init.mjs # Copy agents into a target project ``` ## Docker ### MCP 服务器 ``` docker compose up inspectra ``` ## 审计领域 | 领域 | 智能体 | MCP 工具 | 前缀 | | -------- | ------- | ----------- | -------- | | 安全 | `audit-security` | `inspectra_scan_secrets`, `inspectra_check_deps_vulns`, `inspectra_run_semgrep`, `inspectra_check_maven_deps` | `SEC-` | | 测试 | `audit-tests` | `inspectra_parse_coverage`, `inspectra_parse_test_results`, `inspectra_detect_missing_tests`, `inspectra_parse_playwright_report`, `inspectra_detect_flaky_tests` | `TST-` | | 架构 | `audit-architecture` | `inspectra_check_layering`, `inspectra_analyze_dependencies`, `inspectra_detect_circular_deps` | `ARC-` | | 规范 | `audit-conventions` | `inspectra_check_naming`, `inspectra_check_file_lengths`, `inspectra_check_todos`, `inspectra_parse_lint_output`, `inspectra_detect_dry_violations` | `CNV-` | | 性能 | `audit-performance` | `inspectra_analyze_bundle_size`, `inspectra_check_build_timings`, `inspectra_detect_runtime_metrics` | `PRF-` | | 文档 | `audit-documentation` | `inspectra_check_readme_completeness`, `inspectra_check_adr_presence`, `inspectra_detect_doc_code_drift` | `DOC-` | | 技术债务 | `audit-tech-debt` | `inspectra_analyze_complexity`, `inspectra_age_todos`, `inspectra_check_dependency_staleness` | `DEBT-` | | 无障碍 | `audit-accessibility` | `inspectra_check_a11y_templates` | `ACC-` | | API 设计 | `audit-api-design` | `inspectra_check_rest_conventions` | `API-` | | 可观测性 | `audit-observability` | `inspectra_check_observability` | `OBS-` | | i18n | `audit-i18n` | `inspectra_check_i18n` | `INT-` | ## 评分模型 - **领域分数**：0–100（100 = 无问题） - **总体分数**：所有审计领域的加权平均值（权重在 `policies/scoring-rules.yml` 中） - **等级**：A（90+）、B（75+）、C（60+）、D（40+）、F（<40） ## Make 命令 | 命令 | 描述 | | --------- | ------------- | | `make bootstrap` | 完整设置：安装、构建、测试 | | `make build` | 构建 MCP 服务器 | | `make test` | 运行单元测试 | | `make validate` | 验证 schema + lint 智能体 | | `make smoke` | MCP 服务器冒烟测试 | | `make init TARGET=/path` | 将智能体复制到项目中 | | `make help` | 列出所有命令 | ## npm 脚本 | 脚本 | 描述 | | -------- | ------------- | | `npm run build` | 编译 MCP 服务器（TypeScript → `mcp/dist/`） | | `npm test` | 运行 Vitest 测试套件 | | `npm run test:watch` | 以监视模式运行测试 | | `npm run test:coverage` | 运行测试并生成 V8 覆盖率报告 | | `npm run lint` | TypeScript 类型检查 + ESLint | | `npm run lint:fix` | 自动修复 ESLint 违规 | | `npm run format` | 使用 Prettier 格式化源代码 | | `npm run format:check` | 检查 Prettier 格式化（CI 安全） | | `npm run release:check` | 运行 npm 发布预检（`npm publish --dry-run`） | ## 发布清单 发布新版本前： 1. 在 [package.json](package.json) 中更新版本号并更新 [CHANGELOG.md](CHANGELOG.md) 2. 运行 `npm run release:check` 3. 创建与包版本匹配的 GitHub 发布标签，例如 `v0.7.0` 4. 确保已配置 `NPM_TOKEN` 仓库密钥 5. 通过 [.github/workflows/release.yml](.github/workflows/release.yml) 中的发布工作流进行发布 发布工作流会构建、测试、打包工件、使用 npm provenance 发布，并将 tarball 附加到 GitHub 发布中。 ## 测试 ``` # 运行完整测试套件 npm test # 开发模式 Watch npm run test:watch # 生成覆盖率报告 npm run test:coverage ``` 测试使用 [Vitest](https://vitest.dev/) 编写，与源文件一起存放在 `mcp/src/__tests__/` 中。 ## 扩展 - **贡献指南**：参见 [CONTRIBUTING.md](CONTRIBUTING.md) - **发布说明**：参见 [CHANGELOG.md](CHANGELOG.md) - **添加工具**：参见 [docs/adding-a-tool.md](docs/adding-a-tool.md) - **添加智能体**：参见 [docs/adding-an-agent.md](docs/adding-an-agent.md) - **架构指南**：参见 [docs/architecture.md](docs/architecture.md) - **输出格式**：参见 [docs/output-format.md](docs/output-format.md) - **评分模型**：参见 [docs/scoring-model.md](docs/scoring-model.md) - **路线图**：参见 [docs/roadmap.md](docs/roadmap.md) - **添加领域**：在 `.github/agents/` 中创建新智能体，在 `mcp/src/tools/` 中添加工具，更新评分权重 - **添加配置文件**：在 `policies/profiles/` 中创建 YAML 文件 ### 可用配置文件 | 配置文件 | 技术栈 | | | ------- | | `generic` | 任意项目（保守默认值） | | `java-angular-playwright` | Java + Angular + Playwright 全栈 | | `java-backend` | Java 后端（Quarkus / Spring Boot） | | `angular-frontend` | Angular SPA（TypeScript） | ## 技术栈 - **TypeScript**（ES2022，Node 20+）— MCP 服务器 - **Zod** — 运行时类型验证 - **JSON Schema 2020-12** — 输出合约 - **MCP SDK** — 工具注册和传输 - **YAML** — 策略和配置文件 ## 许可证 MIT

标签：AI编程, API设计, API集成, CMS安全, DLL 劫持, GitHub Copilot, Go, JavaScript, Kotlin, MCP, MITM代理, Model Context Protocol, PyRIT, Python, Ruby工具, SAST, SOC Prime, TypeScript, 代码审查, 可观测性, 可访问性, 国际化, 多智能体系统, 大语言模型, 安全插件, 开发工具, 性能优化, 技术债务, 数据管道, 无后门, 暗色界面, 架构分析, 检测绕过, 盲注攻击, 自动化攻击, 请求拦截, 软件工程, 错误基检测, 静态代码分析