chongming/chongming-skills

Fork 0

Files

T

chakcy 9ecf3176b5 modify: 说明文档

2026-08-05 18:23:12 +08:00

12 KiB

Raw Permalink Blame History

name, description, keywords

name

description

keywords

chongming

用于 chongming-zenoh 项目的开发指导。当用户需要在此项目中添加新 Worker 插件、新增 RPC 端点、修改配置驱动路由、开发前端页面、修改工具包、或进行构建部署时，使用此 skill 获取项目架构知识和开发规范。

chongming

worker

plugin

rpc_method

zenoh

fastapi

路由

配置

端点

插件开发

前端

Vue

Chongming-Zenoh 项目开发指导

项目总览

Chongming-Zenoh 是一个基于 FastAPI + Zenoh + Vue 3 的配置驱动微服务网关平台。核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型和 FastAPI 路由，底层通过 Zenoh 分布式消息协议进行 RPC 通信。

项目五大部分

部分	路径	说明
chongming-core	`src/chongming/`	核心应用：FastAPI 工厂、Zenoh 集成、动态路由生成、Worker 管理
chongming-web	`src/chongming-web/`	Vue 3 前端：Element Plus UI、Pinia 状态管理、自动生成的 API 客户端
chongming-utils	`utils/`	7 个子工具包：config, database, jwt(Rust), lock, password(Rust), request, worker
chongming-plugins	`src/plugins/`	Worker 插件：auth, doubao, example，每个插件独立封装业务逻辑
chongming-config	`config/`	配置文件：Zenoh 配置、Worker 路由 TOML 定义

核心架构与数据流

用户请求 → FastAPI 路由（自动生成）→ WorkerManager.call(subject, params)
  → Zenoh Query → Worker Queryable 回调 → 插件业务逻辑 → 响应

启动流程

serve() → FastAPI lifespan:
  1. setup_nanio()      — 本地 S3 子进程
  2. setup_s3()         — boto3 S3 客户端
  3. setup_zenoh()      — Zenoh peer 会话
  4. setup_worker_manager() — WorkerManager + 定期刷新
  5. load_workers()     — 动态 import 插件
  6. register_routes()  — 扫描 config/workers/ 生成路由

关键组件

WorkerManager (src/chongming/app/core/worker_manager.py): Zenoh liveliness 发现 + 本地注册，负载均衡、超时重试、diskcache 缓存
RouteGenerator (src/chongming/app/core/route_generator.py): 扫描 config/workers/<type>/*.toml，自动生成 FastAPI 端点
chongming-worker (utils/worker/): Worker 框架，提供 @rpc_method 装饰器、create_worker() 运行时

开发工作流

一、添加新的 Worker 插件

创建新插件时需要以下步骤：

1. 创建插件目录结构

src/plugins/<新插件名>/
├── __init__.py       # create_workers() 工厂 + cleanup()
├── global_var.py     # 模块级全局变量
├── router/           # RPC 端点实现
│   ├── __init__.py   # 从各文件导入，__all__ 导出
│   └── <操作名>.py   # 每个操作一个文件
└── models/           # 数据模型
    ├── __init__.py   # 模型导出
    ├── pydantic.py   # 自动生成（由 gen_models.py）
    └── <表名>.py     # SQLModel ORM 模型（如需要）

2. 添加 Worker 注册配置

在 config/workers/config.toml 的 [[workers]] 中添加：

[[workers]]
type = "<新插件名>"
module = "plugins.<新插件名>"
factory = "create_workers"
cleanup = "cleanup"
count = 3

3. 创建端点 TOML 配置文件

config/workers/<新插件名>/config.toml:

[worker]
defaults.timeout = 30
defaults.cacheable = false

[worker.registration]
router_prefix = "/<prefix>"

config/workers/<新插件名>/<operation>.toml:

[GET]                    # 或 [POST]
cacheable = true
summary = "操作描述"
params = ["param1: str", "param2: int"]  # 仅 GET
auth_required = false

[GET.response_model]     # 或 [POST.response_model]
field_name = { type = "str", required = true }
another_field = { type = "int", default = 0 }

4. 生成 Pydantic 模型

uv run python -m chongming.scripts.gen_models

这会根据 TOML 配置自动生成 src/plugins/<新插件名>/models/pydantic.py，包含请求和响应的 Pydantic 模型类。

5. 编写 RPC 端点实现 (`router/<操作>.py`)

# src/plugins/<name>/router/<operation>.py
from chongming_worker.decorators import rpc_method
from ..models.pydantic import SomeRequest, SomeResponse

@rpc_method(subject="<name>.<operation>", method="GET",
            response_model=SomeResponse)
async def my_operation(request: SomeRequest) -> SomeResponse:
    """业务逻辑实现"""
    # 使用 global_var 中的资源
    result = await do_something(request)
    return SomeResponse(result=result)

注意: 此处的 SomeRequest / SomeResponse 等 Pydantic 模型必须来自步骤 4 生成的 models/pydantic.py。编写端点代码前必须先完成模型生成。

6. 编写 `router/init.py`

# src/plugins/<name>/router/__init__.py
from . import operation1, operation2
__all__ = ["operation1", "operation2"]

7. 编写 `init.py` 工厂函数

# src/plugins/<name>/__init__.py
from chongming_worker.runtime import create_workers as _create_workers

def create_workers(session, config, count, worker_manager):
    """插件入口：初始化全局资源，创建 Worker 副本"""
    from . import router  # 触发 @rpc_method 注册
    from .global_var import set_db, set_client  # 设置全局变量
    # 初始化数据库、客户端等...
    _create_workers(session, config, count, worker_manager)

async def cleanup(worker_manager):
    """清理资源"""
    # 关闭连接、清理缓存等...

二、为现有插件添加新 RPC 端点

在 config/workers/<插件名>/ 下创建 <新操作>.toml，定义端点参数和响应模型
运行 uv run python -m chongming.scripts.gen_models 生成 Pydantic 模型
在 src/plugins/<插件名>/router/ 下创建 <新操作>.py，引用生成的模型编写业务逻辑
更新 src/plugins/<插件名>/router/__init__.py，添加 import
重启服务

三、修改配置驱动路由

修改路由前缀: 编辑 config/workers/<插件名>/config.toml 的 router_prefix
添加/修改端点参数: 编辑 <操作>.toml，然后重新生成模型
调整 Worker 副本数: 编辑 config/workers/config.toml 的 count

四、前端开发 (`chongming-web`)

位于 src/chongming-web/：

UI 框架: Element Plus
状态管理: Pinia
路由: Vue Router (Hash History)
API 调用: src/api/generated/ 中由 @hey-api/openapi-ts 自动生成的类型安全客户端

添加新页面流程：

在 src/views/ 创建 Vue 组件
在 src/router/index.ts 添加路由
在 src/App.vue 导航菜单添加入口
如需要，在 src/api/generated/sdk.gen.ts 添加或重新生成 API 调用函数

五、工具包开发 (`chongming-utils`)

每个 utils/<name>/ 下的子包是独立的 Python 包，有各自的 pyproject.toml：

config: 加载 config.toml，TypedDict 配置结构
database: 异步 SQLite (aiosqlite + SQLModel)
jwt: Rust 实现的 JWT 编码/验证 (maturin + jsonwebtoken)
lock: 基于 diskcache 的跨进程分布式锁
password: Rust 实现的 Argon2id 密码哈希
request: Zenoh 客户端封装
worker: Worker 框架核心（@rpc_method 装饰器、create_worker 运行时）

修改工具包后需要重新安装：

uv pip install -e utils/<name>

六、编写或更新项目文档 (README.md)

项目根目录的 README.md 是项目的主要入口文档，涵盖项目简介、核心特性、快速上手、构建部署等关键信息。当出现以下情况时，应及时同步更新 README：

新增或移除 Worker 插件
修改项目目录结构或核心配置文件
添加新的环境变量或配置项（如 config.toml 新增字段）
构建流程或打包方式发生变化
快速启动命令或依赖安装方式改变
新增或更新外部依赖（特别是工具包）

推荐结构（可参考当前 README 模板）：

项目名称与描述 – 一句话概括项目定位。
核心特性 – 列表展示主要功能亮点（如 FastAPI、Zenoh、动态路由、Worker 框架等）。
项目结构 – 使用树形图展示关键目录与文件的作用。
快速开始 – 包含依赖安装（推荐 uv sync）和启动服务（uv run serve）命令。
构建指南 – 说明 PyInstaller / Nuitka 的打包方式（uv run build pyinstaller 等）。
配置说明 – 指向 config/ 目录或详细配置文档的链接。
开发指南 – 可链接到此 Skill（如 ./.agents/skills/chongming/SKILL.md）供开发者深入阅读。

更新流程：

直接在根目录编辑 README.md，保持 Markdown 语法规范。
验证所有代码示例和命令路径是否正确（可实际执行一次）。
若新增插件或工具包，在“项目结构”和“核心特性”中体现。
提交前使用本地预览工具（如 VS Code 的 Markdown 预览）检查排版与链接。
确保 README 与 pyproject.toml 中定义的脚本（serve、gen_models、build）保持一致。

注意：README 是项目对外展示的第一窗口，务必保持内容准确、清晰、与代码库同步更新。

核心约定与规范

命名约定

插件名: 小写下划线，如 doubao, auth, example
操作名: 小写下划线，如 analyze, add, count
Zenoh subject: <插件名>.<操作名>，如 example.add, doubao.analyze
TOML 文件名: 与操作名一致，如 analyze.toml, add.toml
Python 文件名: 与操作名一致，如 analyze.py, add.py

装饰器使用

@rpc_method(
    subject="plugin.operation",  # Zenoh 主题 (必需)
    method="GET",                # HTTP 方法: GET 或 POST
    response_model=ResponseCls,  # Pydantic 响应模型
)
async def handler(request: RequestCls) -> ResponseCls:
    ...

GET 端点：参数通过 URL query string 传递，在 TOML 中用 params 定义
POST 端点：参数通过 JSON body 传递，自动绑定到 Pydantic 请求模型

全局变量模式

每个插件通过 global_var.py 管理模块级共享资源：

# global_var.py
db: Database = None

def set_db(database: Database):
    global db
    db = database

TOML 配置字段说明

字段	位置	说明
`count`	`workers/config.toml`	Worker 副本数
`router_prefix`	`<插件>/config.toml`	API 路由前缀
`defaults.timeout`	`<插件>/config.toml`	默认超时 (秒)
`defaults.cacheable`	`<插件>/config.toml`	是否缓存 RPC 结果
`params`	`<操作>.toml` `[GET]`	GET 参数列表 (`"name: type"` 格式)
`auth_required`	`<操作>.toml`	是否需要 JWT 鉴权
`cacheable`	`<操作>.toml`	端点是否可缓存
`summary`	`<操作>.toml`	端点描述 (用于 OpenAPI docs)

常用命令

# 开发启动
uv run serve

# 生成 Pydantic 模型
uv run python -m chongming.scripts.gen_models

# 构建
uv run python -m chongming.scripts.build

# 安装/更新工具包子包
uv pip install -e utils/<name>

# 前端开发
cd src/chongming-web && npm run dev

注意事项

修改 TOML 配置后必须重新生成模型: uv run python -m chongming.scripts.gen_models
新增插件后需要在 config/workers/config.toml 注册: 否则插件不会被加载
Rust 工具包 (jwt, password) 需要 maturin: 通过 uv run maturin develop --release -m utils/<name>/Cargo.toml 编译
插件间隔离: 每个插件有独立的全局变量，不要跨插件直接引用
数据库路径约定: SQLite 数据库文件放在 data/storage/chongming/ 下
日志: 使用标准 logging.getLogger(__name__)，核心已配置 ANSI 颜色格式化器

12 KiB Raw Permalink Blame History Unescape Escape