功能：基于内置模板创建新项目，或在已有 go.mod 的项目内进行就地初始化
参数：
- [module]：可选。在空目录中创建项目时必填（例如 github.com/acme/myapp）；在已有项目内可省略
选项：
- --force：当目标目录存在时强制覆盖
行为说明：
- 识别模板中的隐藏文件占位（模板以 - 开头的文件名会渲染为 . 前缀，例如 -.gitignore -> .gitignore）
- 支持 .tpl 渲染与 .raw 直写；也支持文件内通过 atomctl:mode=tpl|raw 指示
- 在当前模块内执行时会跳过覆盖已有的 go.mod
- 生成后提示后续步骤（cd 与 go mod tidy）

示例：

atomctl new project github.com/acme/demo
atomctl new -f --dir ./playground project github.com/acme/demo
atomctl new project        # 在已有 go.mod 的项目中就地初始化

new provider

功能：创建 Provider 脚手架到 providers/<name>
参数：
- <name>：可选。省略名称时会列出可用的内置预置 providers 供选择
选项：继承 --dry-run、--dir
行为：
- 若 <name> 与内置 templates/providers/<name> 目录同名，则渲染该目录
- 否则回退渲染 templates/providers/default 到 providers/<name>

示例：

atomctl new provider              # 列出可用预置 providers
atomctl new provider redis        # 渲染 providers/redis 预置
atomctl new provider email        # 未命中预置，回退 default 渲染到 providers/email
atomctl new --dry-run --dir ./demo provider cache

new event (别名：e)

功能：生成事件发布者与订阅者模板
参数：
- <name>：必填，事件名（驼峰自动转换为 snake 作为 topic）
选项：
- --only：仅生成某一侧，publisher 或 subscriber
- 继承 --dry-run、--dir
行为说明：
- 生成 publisher 到 app/events/publishers/<snake>.go
- 生成 subscriber 到 app/events/subscribers/<snake>.go
- 追加常量到 app/events/topics.go：const Topic{Name} = "event:<snake>"（避免重复）

示例：

atomctl new event UserCreated
atomctl new event UserCreated --only=publisher

new job

功能：生成任务模板文件；支持可选的定时任务模板
参数：
- <name>：必填，任务名
选项：
- 继承 --dry-run、--dir
- --cron：除生成 app/jobs/<snake>.go 外，额外生成 app/jobs/cron_<snake>.go

示例：

atomctl new job SendDailyReport               # 生成 app/jobs/send_daily_report.go
atomctl new job SendDailyReport --cron        # 同时生成 cron 版本 app/jobs/cron_send_daily_report.go

说明：代码中已存在 new module 实现，但当前未注册到 new 子命令中（处于弃用状态）。

gen 代码生成

命令组持久化参数：

-c, --config：数据库配置文件路径（默认 config.toml），用于 gen model
执行完成后自动调用 atomctl fmt 格式化生成代码

子命令：

gen model (别名：m)

功能：连接 PostgreSQL，基于配置生成 GORM 模型与相关文件（委托 go.ipao.vip/gen）到 ./database，并读取 ./database/.transform.yaml 做类型/命名转换
配置文件 [Database] 字段：
- Username、Password、Database、Host、Port、Schema、SslMode、TimeZone
示例 config.toml：

[Database]
Host = "127.0.0.1"
Port = 5432
Username = "postgres"
Password = "secret"
Database = "app"
Schema = "public"
SslMode = "disable"
TimeZone = "Asia/Shanghai"

示例：

atomctl gen -c config.toml model

gen route

功能：扫描项目 app/http 目录的控制器，解析注释生成 routes.gen.go
参数：
- --path：扫描根目录（默认当前工作目录）；也可作为位置参数传入项目根路径
注释规则：
- @Router <path> [<method>] 指定路由与方法，如 @Router /users/:id [get]
- @Bind <name> (<position>) key(<key>) [model(<field[:field_type]>)]
  - position 枚举：path|query|body|header|cookie|local|file
  - model() 定义形式：
    1. model() 默认字段 id，类型 int
    2. model(id) 指定字段 id，类型默认 int
    3. model(id:int) 指定字段 id，类型 int
  - 示例：
    - @Bind id path key(id)（PathParam 绑定）
    - @Bind page query key(page)（QueryParam 绑定）
    - @Bind auth header key(Authorization)
    - @Bind file file key(upload)（文件）
    - @Bind user path key(id) model(id:int)（从路径 id 加载模型，按 id:int 查询）

示例：

// UserController
// @Router /users/:id [get]
// @Bind id path key(id) model(id:int)
func (c *UserController) Show(ctx context.Context, id int) (*User, error) { /* ... */ }

执行：

atomctl gen route --path .

注意：生成完成后会自动触发 gen provider 以补全依赖注入。

Bind 参数类型与位置支持

标量类型（scalar）：string、bool、int|int8|int16|int32|int64、uint|uint8|uint16|uint32|uint64、float32|float64
位置与类型支持：
- path：支持标量；也支持通过 model() 从路径值加载模型记录（推荐标量或 model 查找）。
  - 示例：@Bind id path key(id)、@Bind user path key(id) model(id:int)
- query：支持标量或结构体（结构体将按字段名/标签聚合解析查询参数）。
  - 示例：@Bind page query key(page)、@Bind filter query key(q) 或 @Bind opts query key(_)
- header：支持标量或结构体（按字段名/标签解析请求头）。
  - 示例：@Bind auth header key(Authorization)
- cookie：支持标量；string 有快捷写法（CookieParam）。
  - 示例：@Bind sid cookie key(session_id)
- body：支持结构体或标量（通常用于 JSON 体，推荐结构体）。
  - 示例：@Bind input body key(_)
- file：固定类型为 multipart.FileHeader，用于文件上传。
  - 示例：@Bind file file key(upload)
- local：任意类型（从上下文本地存取，而非请求来源）。
  - 示例：@Bind user local key(currentUser)

gen provider (别名：p)

功能：扫描 Go 源码查找带 @provider 注释的结构体，生成 provider.gen.go 实现依赖注入与分组注册
注释语法：@provider(<mode>):[except|only] [returnType] [group]
- mode：grpc|event|job|cronjob|model（留空为默认）
- :only：仅注入标注了结构体字段 tag inject:"true" 的依赖
- :except：注入全部非标量字段，除非字段 tag inject:"false"
- returnType：Provide 返回类型（如 contracts.Initial）
- group：归属分组（如 atom.GroupInitial）
行为特性：
- 自动分析字段类型与 import，忽略标量类型
- grpc：注入 providers/grpc.Grpc，设置 GrpcRegisterFunc
- event：注入 providers/event.PubSub
- job|cronjob：注入 providers/job.Job 并引入 github.com/riverqueue/river
- model：标记需要 Prepare 钩子

示例：

// @provider(job):only contracts.Initial atom.GroupInitial
type UserJob struct {
    // 仅在 only 模式下注入
    Repo *repo.UserRepo `inject:"true"`
    Log  *log.Logger    `inject:"true"`
}

执行：atomctl gen provider（支持在任意子目录执行，自动写入对应包下的 provider.gen.go）

gen enum (别名：e)

功能：在工程内扫描包含 ENUM(...) 且带 swagger:enum 的类型定义文件，为每个文件生成 *.gen.go
选项：
- -f, --flag：生成 flag.Value 支持（默认 true）
- -m, --marshal：生成 JSON 编解码支持
- -s, --sql：生成 database/sql 相关驱动与 Null 支持（默认 true）

示例：atomctl gen enum -m -s

gen service

功能：根据 app/services 下的服务文件聚合生成 services.gen.go
选项：
- --path：服务目录（默认 ./app/services）

示例：atomctl gen service --path ./app/services

migrate 数据库迁移（goose）

用法：atomctl migrate [action] [args...]
支持 action：up|up-by-one|up-to|create|down|down-to|fix|redo|reset|status|version
选项：
- -c, --config：数据库配置文件（默认 config.toml，读取 [Database]）
- --dir：迁移目录（默认 database/migrations）
- --table：迁移版本表名（默认 migrations）
说明：
- 执行 create 时若未指定脚本类型，会自动追加 sql 类型
- 连接配置同上 gen model 的 [Database] 字段

示例：

atomctl migrate status
atomctl migrate up
atomctl migrate create add_users_table

swag 文档

swag init (别名：i)

功能：生成 Swagger 文档（go/json/yaml）
选项：
- --dir：项目根目录（默认 .）
- --out：输出目录（默认 docs）
- --main：主入口文件（默认 main.go）

示例：atomctl swag init --dir . --out docs --main cmd/server/main.go

swag fmt (别名：f)

功能：格式化接口注释与路由
选项：
- --dir：扫描目录（默认 ./app/http）
- --main：主入口文件（默认 main.go）

示例：atomctl swag fmt --dir ./app/http --main main.go

fmt 代码格式化

功能：调用 gofumpt -extra 格式化全项目；若未安装将自动 go install mvdan.cc/gofumpt@latest
选项：
- --check：仅检查不写入，输出未格式化文件列表
- --path：格式化范围（默认 .）

示例：

atomctl fmt                 # 写入格式化
atomctl fmt --check --path ./pkg

buf Proto 生成

功能：检查/安装 buf 并执行 buf generate（在指定目录）
选项：
- --dir：执行目录（默认 .）
- --dry-run：仅预览不执行
说明：若找不到 buf.yaml 会给出提示但仍尝试生成

示例：atomctl buf --dir ./proto

配置与约定

Go 版本：1.23+
数据库配置段落：[Database]（被 gen model 与 migrate 读取）
代码生成默认位置：
- 路由：app/http/**/routes.gen.go
- Provider：每个包内的 provider.gen.go
- 模型：./database（含 .transform.yaml）
- Enum：原文件同目录生成 *.gen.go
- Services：app/services/services.gen.go

常见问题

路由未生成？确保控制器方法注释包含 @Router，且形参通过 @Bind 标注位置/键名。
Provider 未注入期望字段？检查 @provider:only|:except 与字段 tag inject:"true|false" 的组合是否正确。
执行 fmt 报 gofumpt 不存在？工具会自动安装，如仍失败请检查网络与 GOBIN/PATH。
buf generate 找不到命令？工具会自动安装 buf，若仍失败请手动安装或检查网络代理。

README.md Unescape Escape

atomctl v2 命令行工具

安装与使用

顶级命令

new 脚手架

new project (别名：p)