# chongming 项目模板

以 **chongming 网关宿主项目**（chongming-core / chongming-zenoh）为蓝本的项目模板：
初始化出一个开箱可跑的网关项目——宿主骨架（`public/`）+ 内置插件最小示例
（`src/plugins/example/`）+ 配置（`config/`）+ 构建配置，**不含 `utils/`**：网关与全部
`chongming-*` 工具包都通过 uv 从私有源安装。

## 初始化新项目

```bash
python init.py <目标目录> [--name 项目名] [--app-name 应用名] [--no-sync]

# 例：目录名即项目名
python init.py ~/proj/my-gateway

# 例：指定项目名与应用显示名
python init.py ../demo-gateway --name demo-gateway --app-name "演示网关"
```

脚本会：拒绝覆盖非空目录 → 复制模板（`README.project.md` → `README.md`）→ 替换
`{{project_name}}` / `{{app_name}}` 占位符 → 执行 `uv sync`。

生成后：

```bash
cd <目标目录>
uv run serve                                          # http://localhost:8000/docs
curl 'http://localhost:8000/api/v1/example/hello?name=world'
```

## 模板内容

```text
pyproject.toml          # 宿主依赖（chongming-gateway + 骨架依赖）与 dev 工具
config.toml             # 应用主配置：环境/服务器/缓存/MQTT/打包收集清单/module_system
plugins_deps.toml       # 内置插件专属依赖（打包收集用，空模板）
.python-version         # 解释器版本（uv 用）
init.py                 # 本初始化脚本（不复制进目标项目）
README.project.md       # 生成项目里的 README（初始化时重命名为 README.md）
public/                 # 可执行文件打包骨架：main.py / server.py / utils / ico / 运行时 config.toml
config/                 # 项目配置：zenoh_config.json5 + workers/example（示例插件注册与端点）
src/plugins/example/    # 内置插件最小示例：Plugin 生命周期 + @rpc_method + gen_models 产物
```

## 生成项目的常用命令

```bash
uv run serve                                   # 启动（热重载）
uv run gen_plugin <name> [operation ...]       # 生成内置插件骨架（--process 生成进程插件项目）
uv run gen_models config/workers/<name> src/plugins/<name>   # 按 TOML 生成 Pydantic 模型
uv run build pyinstaller                       # 打包可执行文件（Nuitka 用 uv run build nuitka）
uv run build_plugin <name>                     # 进程插件打包 → dist/<name>.zip
```

## 维护模板

- 骨架（`public/`）、示例插件与配置结构源自 chongming-core 仓库，改动时从那边同步；
  同步后建议用 `init.py` 生成一个临时项目验证 `uv run serve` 可启动。
- 占位符只有两个：`{{project_name}}`（pyproject 的 name）、`{{app_name}}`
  （config.toml 与 public/config.toml 的 `app.name` / `app.description`）。
- 依赖版本不写死：网关与工具包按私有源最新发布版解析；需要锁定时在生成的项目里
  `uv lock` 提交 `uv.lock` 即可。