pecto

通过静态分析从代码中提取行为规范。

你的代码有自己的行为。pecto 能让它们变得可见。

pecto.dev · 文档 · 安装

pecto 是一个开源的 CLI 工具，能够分析 Java、C#、Python 和 TypeScript 代码库，并生成人类可读的行为规范——无需 LLM、速度快、具有确定性且完全离线。

pecto serve — interactive dashboard with dependency graph, domain clusters, and flow tracing

``` $ pecto init ./my-spring-app pecto Analyzing ./my-spring-app... ✓ Analyzed 86 files → 29 capabilities 23 endpoints 8 entities 109 operations ``` ## 为什么选择 pecto - 76% 使用 AI 工具的开发者会生成他们并不完全理解的代码 - 遗留代码库的增长速度快于文档的更新速度 - 现有工具寻找的是*Bug* —— pecto 提取的是*行为* - 代码审查展示了*修改了什么* —— pecto 展示了*代码做了什么* ## 安装 ``` cargo install pecto ``` 或者从 [GitHub Releases](https://github.com/AliciaMartinelli/pecto/releases) 下载预编译的二进制文件。 ## 快速开始 ``` # 分析项目（自动检测语言） cd ./my-app pecto init # 启动交互式 dashboard pecto serve # 显式指定语言 pecto init --language java # 输出为 JSON 而非 YAML pecto init --format json # 保存到文件 pecto init --output specs.yaml # 显示详细的按 capability 细分 pecto init --verbose # Machine-readable 输出（无状态消息） pecto init ./my-app --quiet > specs.yaml # 查看 business domains 和 dependencies pecto domains ./my-app pecto graph ./my-app --format dot | dot -Tpng > graph.png # Impact analysis：如果更改此项会导致什么损坏？ pecto impact Owner # 交互式 web dashboard pecto serve ./my-app # AI-ready 的项目上下文 pecto context ./my-app ``` ## 命令 ### `pecto init` — 分析项目 ``` pecto init [path] [--format yaml|json] [--output file] [--verbose] [--quiet] ``` 扫描项目，提取行为规范，并输出到标准输出或文件中。 ### `pecto show` — 检查功能 ``` pecto show [--path .] ``` 显示特定功能的规范。支持子串匹配。 ### `pecto verify` — 检测行为漂移 ``` pecto verify [--path .] ``` 将现有规范与当前代码进行比较。如果检测到漂移，则以退出代码 1 退出。非常适合 CI 流水线。 ### `pecto diff` — 比较 git 引用 ``` pecto diff [head-ref] [--path .] ``` 显示两个 git 引用之间的行为变化。对代码审查非常有用。 ### `pecto flow` — 请求流追踪 ``` pecto flow "POST /api/users" # Mermaid sequence diagram pecto flow "GET /users" --format json # JSON output ``` 将 endpoint 的请求流追踪为 Mermaid 序列图。 ### `pecto check` — 架构规则 ``` pecto check # uses .pecto/rules.yaml or defaults pecto check --rules my-rules.yaml # custom rules file ``` 根据代码库验证架构适应度规则。 内置规则：`no-circular-dependencies`、`controllers-no-direct-db-access`、`all-endpoints-need-authentication`、`no-entity-without-validation`、`max-service-dependencies`。 在 `.pecto/rules.yaml` 中配置： ``` rules: no-circular-dependencies: true controllers-no-direct-db-access: true all-endpoints-need-authentication: true max-service-dependencies: 5 ``` ### `pecto pr-diff` — PR 行为差异 ``` pecto pr-diff main HEAD # outputs markdown to stdout ``` 生成两个 git 引用之间 GitHub 风格的 Markdown 差异。配合 `pecto-pr` GitHub Action 使用，可自动在 pull request 上发布行为差异。 ### `pecto domains` — 业务领域集群 ``` pecto domains [path] ``` 根据业务领域（命名规范 + 依赖分析）对功能进行分组。 ### `pecto graph` — 依赖图 ``` pecto graph [path] [--format text|dot|json] ``` 显示功能之间如何相互依赖。DOT 格式用于 Graphviz，JSON 格式用于工具链。 ### `pecto impact` — 变更影响分析 ``` pecto impact [--path .] ``` 追踪依赖图，以显示如果更改某项功能会导致什么破坏。 ### `pecto context` — AI/LLM 上下文导出 ``` pecto context [path] ``` 专为 LLM 上下文窗口（~4K token）优化的紧凑项目摘要。 ### `pecto report` — HTML 报告 ``` pecto report [path] [--output pecto-report.html] ``` 包含交互式 D3.js 依赖图的自包含 HTML。可在任何浏览器中打开。 ### `pecto serve` — Web 仪表盘 ``` pecto serve [path] [--port 4321] ``` 在 `http://localhost:4321` 提供实时交互式仪表盘，包含依赖图、领域集群和搜索功能。 ## 输出示例 ``` name: spring-petclinic-rest analyzed: '2026-03-25T14:30:00Z' files_analyzed: 86 capabilities: - name: owner-entity source: model/Owner.java entities: - name: Owner table: owners fields: - name: id type: Integer constraints: ["@Id", "@GeneratedValue"] - name: firstName type: String constraints: ["@NotBlank"] - name: lastName type: String constraints: ["@NotBlank"] - name: owner-repository source: repository/OwnerRepository.java operations: - name: save source_method: SpringDataOwnerRepository#save - name: findById source_method: SpringDataOwnerRepository#findById - name: Find by last name source_method: SpringDataOwnerRepository#findByLastName - name: clinic-service source: service/ClinicService.java operations: - name: findOwnerById source_method: ClinicServiceImpl#findOwnerById transaction: read-only ``` ## 语言支持 ### Java | 功能 | pecto 提取的内容 | |---------|-------------------| | **Spring Controllers** | `@RestController`、`@GetMapping`/`@PostMapping` 等、路径变量、请求参数、请求体 | | **JAX-RS Resources** | `@Path`、`@GET`/`@POST` 等、`@PathParam`、`@QueryParam`、`@RolesAllowed`、`@PermitAll` | | **JPA Entities** | `@Entity`、`@Table`、字段类型、`@Id`、`@Column`、关系 (`@OneToMany`、`@ManyToOne`) | | **Spring Data Repos** | `JpaRepository`、CRUD 操作、自定义查询方法、`@Query` | | **JPA Repositories** | `@PersistenceContext EntityManager`、自定义基础 repository 类 | | **Services** | `@Service`、`@Stateless`、`@RequestScoped`、`@Inject`、`@Transactional`、副作用 | | **Validation** | `@Valid` 结合跨文件 DTO 解析：`@NotBlank`、`@Email`、`@Size`、`@Min`、`@Max`、`@Pattern` | | **Security** | `@PreAuthorize`、`@Secured`、`@CrossOrigin`、`@RateLimiter`、`@RolesAllowed`、`@PermitAll` | | **Error Handling** | `throw ResponseStatusException`、`ResponseEntity.notFound()`、`@ExceptionHandler` | | **Scheduled Tasks** | `@Scheduled(cron=...)`、`@EventListener` | ### C# / .NET | 功能 | pecto 提取的内容 | |---------|-------------------| | **ASP.NET Controllers** | `[ApiController]`、`[HttpGet]`/`[HttpPost]` 等、带有 `[controller]` 替换的 `[Route]` | | **EF Core Entities** | DbContext 中的 `DbSet`、`[Table]`、`[Key]`、`[Required]`、`[MaxLength]`、`[ForeignKey]` | | **Services** | 命名约定 (*Service) 或接口 (I*Service)、公共方法、事务模式 | | **Validation** | `[FromBody]` 结合跨文件解析：`[Required]`、`[EmailAddress]`、`[Range]`、`[StringLength]` | | **Security** | `[Authorize]`、`[Authorize(Roles = "...")]`、`[AllowAnonymous]` | | **Error Handling** | `[ProducesResponseType(StatusCodes.Status404NotFound)]` | | **Background Tasks** | `BackgroundService`、`IHostedService`、`TimeSpan.From*` 定时器模式 | | **Parameters** | `[FromBody]`、`[FromRoute]`、`[FromQuery]`、async `Task>` 解包 | ### Python | 功能 | pecto 提取的内容 | |---------|-------------------| | **FastAPI** | `@router.get`/`@app.post` 等、来自类型提示的路径参数、`Depends()` 安全机制 | | **Flask** | `@app.route`/`@blueprint.route`、methods kwarg、路径参数 | | **Django REST** | `ModelViewSet` CRUD、`@api_view` 函数视图 | | **SQLAlchemy** | `Column()`、`relationship()`、`__tablename__`、约束 | | **Django Models** | `models.Model`、`CharField`、`ForeignKey`、`ManyToManyField` | | **Pydantic** | `BaseModel`、带有 min/max_length、gt/lt 约束的 `Field()` | | **Services** | `*Service`/`*Repository`/`*UseCase` 类、公共方法 | | **Celery Tasks** | `@shared_task`、`@app.task`、`@periodic_task` | ### TypeScript / JavaScript | 功能 | pecto 提取的内容 | |---------|-------------------| | **Express** | `router.get`/`app.post` 等、`:param` 路径参数、路由字符串 | | **NestJS** | `@Controller`、`@Get`/`@Post` 等、`@UseGuards` 安全机制 | | **Next.js** | App Router 在 route.ts 中的 `export function GET/POST`，来自文件结构的路径 | | **TypeORM** | `@Entity`、`@Column`、`@PrimaryGeneratedColumn`、关系 | | **Mongoose** | `new Schema({...})` 检测 | | **Services** | `@Injectable`、`*Service`/`*Repository` 类、公共方法 | ## 性能 | 项目 | 文件数 | 功能数 | 耗时 | |---------|-------|-------------|------| | Spring PetClinic REST (Java) | 86 | 18 | ~0.5s | | eShopOnWeb (C#/.NET) | 254 | 18 | ~1.6s | 使用 [rayon](https://github.com/rayon-rs/rayon) 进行并行文件解析。无网络调用。无 LLM。纯 tree-sitter 静态分析。 ## 工作原理 pecto 使用 [tree-sitter](https://tree-sitter.github.io/) 进行快速、准确的解析： 1. **解析 (Parse)** — 为每个源文件构建 AST（使用 rayon 并行处理） 2. **检测 (Detect)** — 识别框架、模式和注解/属性 3. **提取 (Extract)** — 提取出 endpoint、操作、实体、安全规则和副作用 4. **解析 (Resolve)** — 跨文件类型解析（DTO、实体、DbContext） 5. **生成 (Generate)** — 输出结构化的行为规范（YAML/JSON） ## CI 集成 在你的 CI 流水线中使用 `pecto verify` 来检测行为漂移： ``` # .github/workflows/pecto.yml - name: Check behavior spec run: | cargo install pecto pecto verify specs.yaml --path . ``` 退出代码 1 表示规范已与代码发生了漂移。 ### GitHub Action：`pecto-pr` 自动在 pull request 上发布行为差异： ``` # .github/workflows/pecto-pr.yml on: pull_request jobs: behavior-diff: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pecto/pecto-pr@v1 with: github-token: ${{ secrets.GITHUB_TOKEN }} ``` ## 贡献 ``` # Clone 并构建 git clone https://github.com/AliciaMartinelli/pecto cd pecto cargo build # 运行测试 cargo test # 运行 integration tests（需要连接互联网以执行 git clone） cargo test -- --ignored # 检查 formatting 和 lints cargo fmt --check cargo clippy --all-targets -- -D warnings ``` ## 许可证 MIT

标签：AST解析, Homebrew安装, Mutation, Python, Rust, tree-sitter, TypeScript, 云安全监控, 代码分析, 代码审查, 代码理解, 依赖图, 凭证管理, 可视化, 可视化界面, 安全插件, 开源, 无后门, 确定性分析, 离线分析, 网络流量审计, 行为提取, 跨语言支持, 软件文档生成, 逆向工程分析工具, 通知系统, 静态分析