init: chongming 项目模板（init.py 初始化骨架 + 内置插件最小示例）

2026-10-13 17:29:29 +08:00
commit 042ac0e8d5
24 changed files with 1314 additions and 0 deletions
@@ -0,0 +1,62 @@
+# 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` 即可。