iTi-Flask/docs/COPIER_TEMPLATE.md

Copier 模板

当前框架仓库根目录是 Copier 模板源。 copier.yml 通过 _subdirectory: copier-template 指向实际模板目录。 copier-template 生成 FastAPI 业务后端骨架。 模板只引用框架包，不复制框架源码。 模板会为生成项目渲染项目 skill。 生成后的路径是：

.codex/skills/<project-slug>-project/SKILL.md

模板源文件是：

copier-template/.codex/skills/{{ project_slug | lower | replace('_', '-') }}-project/SKILL.md.jinja

模板结构、脚本命令或模块约定变化时，同步更新该模板 skill。 现有模板生成项目需要按当前项目名刷新自己的 skill。

生成

./scripts/iti.sh make-app ../my-business-app my_business_app
cd ../my-business-app
./app.sh init
./app.sh serve 8000

Windows：

scripts\iti.cmd make-app ..\my-business-app my_business_app
cd ..\my-business-app
app.cmd init
app.cmd serve 8000

参数

参数	说明
project_name	业务项目显示名称
project_slug	业务项目 Python 包名
framework_git	iTi-Flask Git 地址
framework_tag	iTi-Flask Git tag
include_system	是否引入 iTi-System
system_git	iTi-System Git 地址
system_tag	iTi-System Git tag

默认推荐私有 Git tag。 允许改成 branch 或 file://，但多人协作项目不建议依赖本机路径。

生成内容

• app.py
• config.py
• pyproject.toml
• migrations/
• 示例 FastAPI 模块
• 示例 SQLAlchemy 模型
• 示例测试
• app.sh
• app.cmd

系统业务

选择 include_system=true 时，模板会注册 create_system_module()。 生成后执行：

./app.sh init-system

Windows：

app.cmd init-system

生成项目脚本

模板会生成两份脚本：

• app.sh：Linux / macOS / Git Bash。
• app.cmd：Windows CMD。

常用命令：

./app.sh help
./app.sh install
./app.sh test
./app.sh serve 8000
./app.sh migration "alice add order table"
./app.sh migrate

app.sh / app.cmd 内部使用项目自己的 migrations/alembic.ini。

带 iti-system 的项目还会有：

./app.sh system-sync
./app.sh system-seed
./app.sh init-system

同步更新

业务项目同步框架依赖：

./app.sh framework-sync

该命令执行 uv sync --upgrade-package iti-flask。 带 iti-system 的模板项目会同时升级 iti-system。

业务项目检查模板版本：

./app.sh template-check

该命令执行 uvx copier update --defaults --pretend --vcs-ref HEAD。

业务项目按模板更新项目骨架：

./app.sh template-update

该命令执行 uvx copier update --defaults --vcs-ref HEAD。 它依赖 .copier-answers.yml 里的 _src_path 和 _commit。 模板更新前，业务项目工作区必须干净。 执行后检查 diff，再运行测试。

模板拥有的文件包括 app.py、config.py、app.sh、app.cmd、pyproject.toml、migrations/、示例模块、示例测试、README 和项目 skill。 业务项目自己的模块、模型、API 文档和业务 README 由业务项目维护。