命令行

Perigon 提供命令行工具 perigon，用于创建解决方案、补充资源、生成代码、打包模块、安装模块，以及启动 Studio 或 Agent MCP 服务。

快速开始

查看命令总览：

perigon -h

查看某个命令的详细帮助：

perigon <command> -h

例如：

perigon add -h
perigon generate -h
perigon generate request -h

命令概览

当前 perigon -h 输出的主要命令如下：

new

new 命令用于创建新的解决方案，效果与通过 Studio 图形界面创建基本一致。

perigon new <name>

示例：

perigon new DemoApp

帮助信息：

DESCRIPTION:
Create new .NET solution
USAGE:
    perigon new <name> [OPTIONS]
EXAMPLES:
    perigon new name
ARGUMENTS:
    <name>    Solution Name
OPTIONS:
    -h, --help    Prints help information

执行后，CLI 会引导你完成解决方案初始化，例如：

1. 选择数据库类型，例如 SqlServer、PostgreSQL
2. 选择缓存类型
3. 选择官方模块(如 Perigon.SystemMod、Perigon.CMSMod、Perigon.ResourceMod)
4. 选择前端集成方式
5. 指定输出目录，默认使用当前目录
6. 确认配置并开始生成

说明：

• 官方模块列表来自 Perigon.Modules/modules.json。
• 选择的官方模块会在解决方案生成完成后自动安装到目标服务中。
• 如果读取官方模块列表失败，命令会给出警告，但仍然可以继续创建解决方案。

update

update 命令用于将已有项目与最新的 Perigon 项目模板进行对比，并按选择结果应用差异。必须在交互式终端中从解决方案根目录或其子目录执行：

perigon update

执行前 CLI 会提示模板更新可能覆盖本地修改，建议先创建并切换到新的 Git 分支。随后 CLI 会：

1. 直接执行 dotnet new install Perigon.templates，确保使用最新的 Perigon.templates 模板。
2. 使用当前项目的模板类型和前端模式，在临时目录生成一个项目副本。
3. 进入双栏差异选择器：左侧只显示模板中新增或发生变化的文件名及 (+新增行数 -删除行数)，右侧显示完整相对路径和当前文件的彩色差异。
4. 使用方向键移动文件，按空格选择或取消选择文件；可选择多个文件，按 PgUp/PgDn 滚动右侧当前文件差异，按回车将已选择的差异应用到当前项目，按 Esc 取消。左右面板会显示当前可视范围和上下滚动提示，移动文件时会自动保持当前文件可见。

只有按回车应用后才会修改当前项目；按 Esc 会保留当前项目不变，但模板安装已经在选择界面前完成。比较时会忽略换行差异、行首尾空白、连续空白差异和空白行差异，避免格式化差异干扰；应用前仍会进行严格快照校验。命令只处理模板中存在的文件，不会删除当前项目独有的文件，也不会处理以下范围之外的文件：

• src/Perigon 下的 .cs 文件；
• src/Definition/ServiceDefault 或 src/Definition/ServiceDefaults 下的 .cs 文件；
• src/Definition/Share 下的 .cs 文件；
• src/Definition/EntityFramework 下的 .cs 文件，但排除整个 Migrations 目录以及 DefaultDbContext.cs、AnalysisDbContext.cs 和 ReadonlyDbContext.cs；
• scripts 下的 .ps1 文件；
• .agent 和 .agents 目录下的所有文件。

此外，src/Perigon/Perigon.AspNetCore/Constants/WebConst.cs 不参与对比，以保留项目自己的 Web 常量配置。

项目文件在对比后被其他操作修改时，更新会被拒绝，以避免将过期差异覆盖到当前项目。选中文件写入完成后，CLI 会在解决方案根目录自动执行 dotnet build，并输出编译成功或错误信息；编译失败不会撤销已经应用的文件，应根据错误修复或从 Git 回滚。应用前仍建议先查看差异并确保工作区已提交或可回滚。

add

add 是新增命令，用于在当前解决方案中创建模块以及服务。

perigon add [OPTIONS] <COMMAND>

示例：

perigon add module FileManagerMod
perigon add service AdminService

帮助信息：

DESCRIPTION:
Add resources to the current solution
USAGE:
    perigon add [OPTIONS] <COMMAND>
EXAMPLES:
    perigon add module FileManagerMod
    perigon add service AdminService
OPTIONS:
    -h, --help    Prints help information
COMMANDS:
    module <ModuleName>      Create a new module in the current solution
    service <ServiceName>    Create a new service in the current solution

add module

创建一个新模块：

perigon add module <ModuleName>

示例：

perigon add module FileManagerMod

说明：

• ModuleName 为模块名称
• 可以省略 Mod 后缀，CLI 会自动处理

帮助信息：

DESCRIPTION:
Create a new module in the current solution
USAGE:
    perigon add module <ModuleName> [OPTIONS]
EXAMPLES:
    perigon add module FileManagerMod
ARGUMENTS:
    <ModuleName>    Module name, `Mod` suffix is optional / 模块名称，可省略 `Mod` 后缀
OPTIONS:
    -h, --help    Prints help information

add service

创建一个新服务：

perigon add service <ServiceName>

示例：

perigon add service AdminService

说明：

• ServiceName 为服务名称
• 新服务通过 Perigon.AspNetCore.SourceGeneration 1.1.1 NuGet 包启用统一的编译期源代码生成，不再引用模板中的源生成器项目。

帮助信息：

DESCRIPTION:
Create a new service in the current solution
USAGE:
    perigon add service <ServiceName> [OPTIONS]
EXAMPLES:
    perigon add service AdminService
ARGUMENTS:
    <ServiceName>    Service name / 服务名称
OPTIONS:
    -h, --help    Prints help information

studio

studio 命令用于启动 Perigon Studio。大多数可视化操作都可以在 Studio 中完成。

perigon studio

帮助信息：

DESCRIPTION:
start Perigon Studio
USAGE:
    perigon studio [OPTIONS] [COMMAND]
OPTIONS:
    -h, --help    Prints help information
COMMANDS:
    update    update studio

studio update

用于更新 Studio：

perigon studio update

帮助信息：

DESCRIPTION:
update studio
USAGE:
    perigon studio update [OPTIONS]
OPTIONS:
    -h, --help    Prints help information

generate

generate 命令用于执行代码生成。

perigon generate [OPTIONS] <COMMAND>

当前支持实体模型生成规则输出、DTO/Manager/Controller 生成，以及客户端请求服务和模型文件生成。

帮助信息：

DESCRIPTION:
Code generate
USAGE:
    perigon generate [OPTIONS] <COMMAND>
EXAMPLES:
    perigon generate request ./openapi.json ./src/services -t angular
OPTIONS:
    -h, --help    Prints help information
COMMANDS:
    entity                              输出实体模型生成规则
    dto <EntityPath>                    根据实体生成 DTO
    manager <EntityPath>                根据实体生成 Manager
    controller <EntityPath> <ServicePath|ServiceName>
                                       根据实体生成 Controller
    request <path|url> <outputPath>      Generate client request service and models

generate entity

输出实体模型创建规则，供 LLM 或其他代码生成流程参考；该命令本身不创建实体文件。

perigon generate entity

规则要求实体放在 src/Definition/Entity 项目中。指定模块时，在实体项目下使用“模块名 + Mod”作为目录名；目录不存在时创建。若模块尚不存在，应先创建模块。实体还应遵循 EntityBase、可空性、字符串长度、枚举说明、索引、关联关系和 DbSet 定义等约定。

generate dto

根据实体文件生成 DTO：

perigon generate dto <EntityPath> [-f|--force]

--force 用于覆盖已生成的文件。

generate manager

根据实体文件生成 Manager：

perigon generate manager <EntityPath> [-f|--force]

--force 用于覆盖已生成的文件。

generate controller

根据实体文件生成 Controller：

perigon generate controller <EntityPath> <ServicePath|ServiceName> [-f|--force]

ServicePath|ServiceName 可以是服务目录、.csproj 路径或服务名称；controller 也可以使用别名 api。--force 用于覆盖已生成的文件。

generate request

根据 OpenAPI 文档生成客户端请求服务和模型。

perigon generate request <path|url> <outputPath> [OPTIONS]

示例：

perigon generate request https://localhost:17001/swagger/v1/swagger.json ./src/services -t angular

帮助信息：

DESCRIPTION:
Generate client request service and models
USAGE:
    perigon generate request <path|url> <outputPath> [OPTIONS]
EXAMPLES:
    perigon generate request ./openapi.json ./src/services -t angular
ARGUMENTS:
    <path|url>      Local path or url, support json format
    <outputPath>    The output path
    OPTIONS:
                             DEFAULT
    -h, --help                     Prints help information
    -t, --type          angular    Support types: csharp/angular/axios, default: angular
    -m, --only-model    false      Only generate model files
    -c, --cover-base-service    false      Overwrite generated base.service.ts

参数说明：

• <path|url>：本地 OpenAPI 文件路径或远程 URL
• <outputPath>：生成代码的输出目录
• -t, --type：生成目标类型，支持 csharp、angular、axios
• -m, --only-model：仅生成模型文件
• -c, --cover-base-service：覆盖已有的 base.service.ts；默认保留用户自定义内容。该选项主要用于 Angular/Axios 前端请求客户端，Studio 默认也保留该文件；与 -m/--only-model 一起使用时不会生成或覆盖基础服务。C# 客户端生成的是 BaseService.cs。

当目标类型为 csharp 时，OpenAPI 中的 multipart/form-data 会生成 multipart 上传方法，并使用文档中声明的 HTTP 方法（例如 POST 或 PUT）。单个文件字段使用 MultipartFile（封装 Stream、文件名和可选 MIME 类型），多个文件字段使用 IEnumerable<MultipartFile>；普通字符串、数字、布尔值和数组字段也会作为表单字段提交。Angular 和 Axios 客户端分别使用 File/File[]，并按 schema 字段名写入 FormData，同时遵循 OpenAPI 声明的请求方法。C# 客户端生成不带 / 开头的相对 URI，并直接交给 HttpClient 与 BaseAddress 合并；配置 BaseAddress 时地址结尾必须带 /，例如 https://example.com/api/，这样才能正确保留多级基础路径。

当 OpenAPI 响应为 204、205、304 或请求方法为 HEAD 时，客户端生成无内容返回类型：C# 为 Task，Angular/Axios 为 void。C# 客户端收到非成功响应时，会将原始响应内容及状态信息放入 ResponseContent 的 Content、StatusCode 和 ReasonPhrase 字段，调用方可以在外层按实际错误格式处理。

当 OpenAPI 的 tag 包含空格或其他不能直接用于代码标识符的字符时，生成器会将其转换为 PascalCase 服务名。例如 User Management 会生成 UserManagementService 或 UserManagementRestService，服务文件名使用连字符格式。

agent

agent 命令用于初始化 Perigon Agent 集成，或启动供 IDE/代码 Agent 使用的 MCP 服务。

perigon agent [OPTIONS] <COMMAND>

主要子命令如下：

perigon agent init
perigon agent mcp

perigon agent mcp 会加载 Perigon 代码生成工具，并通过 MCP 客户端的 roots/list 获取当前项目根目录。工具能力和 IDE 配置示例请参阅 Perigon Agent MCP。旧版 perigon mcp config 和 perigon mcp start 不属于当前推荐命令。

module pack

module pack 命令用于将模块打包为 zip 文件。

perigon module pack <ModuleName> <ServiceName> [-v|--version <VERSION>] [--front-path <FRONT_PATH>]

示例：

perigon module pack FileManagerMod AdminService --version 1.2.0

帮助信息：

DESCRIPTION:
打包模块为zip文件
USAGE:
    perigon module pack <ModuleName> <ServiceName> [OPTIONS]
EXAMPLES:
    perigon module pack FileManagerMod AdminService --front-path src/ClientApp/WebApp/src/app/modules/file-manager
ARGUMENTS:
    <ModuleName>     Module name (with Mod suffix)
    <ServiceName>    Service name in Services directory
OPTIONS:
    -h, --help                       Prints help information
    -v, --version <VERSION>          Package version; defaults to 1.0.0 when omitted / 包版本号；省略时默认使用 1.0.0
        --front-path <FRONT_PATH>    Frontend module directory to include in the package

参数说明：

• ModuleName：模块名称，通常以 Mod 结尾
• ServiceName：服务名称，对应 Services 目录下的某个 API 服务目录
• -v/--version：可选。写入模块包元数据的版本号；省略时使用 1.0.0 并显示警告。
• --front-path：可选。要打包的单个前端模块目录，例如 src/ClientApp/WebApp/src/app/modules/file-manager

前端模块打包与限制

指定 --front-path 后，CLI 会将该目录和同级的 share 目录写入 zip：

Frontend/file-manager/...
Frontend/share/...

• file-manager 来自 --front-path 的最后一个目录名；share 必须与该模块目录同级。
• 未指定 --front-path 时，不会包含前端内容，后端模块仍可正常打包；指定的模块目录不存在时，打包会失败。若同级 share 不存在，则只打包模块目录。
• 仅包含指定模块目录及同级 share 下的文件，不包含前端应用外壳、全局路由、根 package.json、锁文件或其他模块目录。
• 该包不安装 npm/pnpm 依赖；目标项目必须自行具备兼容的前端工程与依赖。

module install

module install 命令用于将模块包安装到项目中，也支持直接使用官方包名安装模块。

perigon module install [PackagePath] [ServiceName] [--front-path <FRONT_PATH>]

示例：

perigon module install ./package_modules/FileManagerMod.zip AdminService

或直接安装官方模块：

perigon module install Perigon.SystemMod AdminService

帮助信息：

DESCRIPTION:
安装模块包到项目
USAGE:
    perigon module install [PackagePath] [ServiceName] [OPTIONS]
EXAMPLES:
    perigon module install ./package_modules/FileManagerMod.zip AdminService --front-path src/ClientApp/WebApp/src/app/modules
ARGUMENTS:
    <PackagePath>    Path to the module package zip file, or official package name like Perigon.SystemMod
    <ServiceName>    Service name in Services directory
OPTIONS:
    -h, --help                       Prints help information
        --front-path <FRONT_PATH>    Directory where bundled frontend code will be restored

参数说明：

• PackagePath：模块压缩包路径，或官方模块包名，例如 Perigon.SystemMod
• ServiceName：目标服务名称，对应 Services 目录下的某个 API 服务目录
• --front-path：可选。前端模块根目录，例如 src/ClientApp/WebApp/src/app/modules；它不是单个模块目录

前端恢复规则

当包内包含 Frontend 内容且提供 --front-path 时，安装会恢复为：

<FRONT_PATH>/file-manager/...
<FRONT_PATH>/share/...

• 模块目录中的同名文件会按模块安装行为覆盖。
• share 中已存在的同名文件不会覆盖，只会补充缺失文件。
• 未提供 --front-path 时，后端模块仍会安装，但前端文件不会恢复，并会显示提示。
• 模块包不再包含或处理 UseSelfServices；安装不会为了模块修改目标服务的 Program.cs 或默认中间件配置。

说明

• 命令说明以当前版本 CLI 的 perigon -h 及各子命令帮助输出为准。
• 如果后续版本新增命令或参数，建议重新执行 perigon -h 与 perigon <command> -h 后同步更新文档。