Roog (顾新培)
8ca2f64f7e
变更内容： - 删除 `src` 子目录，将模块引用路径从 `src.functional_scaffold` 更新为 `functional_scaffold`。 - 修改相关代码、文档、测试用例及配置文件中的路径引用，包括 `README.md`、`Dockerfile`、`uvicorn` 启动命令等。 - 优化项目目录结构，提升代码维护性和可读性。
103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# Agent.md
|
||
|
||
本文件为本仓库内各类智能体/助手提供工作指导，内容参考 `CLAUDE.md`，并针对日常开发与协作做了简化归纳。
|
||
|
||
## 项目概述
|
||
|
||
**FunctionalScaffold（函数式脚手架）** 是一个算法工程化 Serverless 解决方案的脚手架生成器。
|
||
|
||
- 为了方便团队交流，项目自然语言使用中文，包括代码注释和文档
|
||
- 核心目标：解决算力弹性、算法工程化门槛与后端集成复杂度问题
|
||
|
||
## 技术与架构
|
||
|
||
采用 **Docker 封装的 Serverless API 服务**方案：
|
||
|
||
- 算法代码 + 运行环境打包为 Docker 镜像
|
||
- 部署到云厂商 Serverless 平台实现自动扩缩容
|
||
- FastAPI 作为 HTTP 接口层
|
||
- 算法逻辑保持独立和专注
|
||
|
||
架构流程概览：
|
||
|
||
```
|
||
用户请求 → API网关 → 容器实例（冷/热启动）→ FastAPI → 算法程序 → 返回结果
|
||
↓
|
||
外部服务（OSS/数据库）
|
||
```
|
||
|
||
## 代码结构（src layout）
|
||
|
||
```
|
||
src/functional_scaffold/
|
||
├── algorithms/ # 算法层 - 所有算法必须继承 BaseAlgorithm
|
||
│ ├── base.py # execute() 包装器（埋点、错误处理）
|
||
│ └── prime_checker.py # 示例：质数判断算法
|
||
├── api/ # API 层 - FastAPI 路由和模型
|
||
│ ├── models.py # Pydantic 数据模型（ConfigDict）
|
||
│ ├── routes.py # 路由定义（/invoke, /healthz, /readyz, /jobs）
|
||
│ └── dependencies.py # 依赖注入（request_id 生成）
|
||
├── core/ # 核心功能 - 横切关注点
|
||
│ ├── errors.py # 异常类层次结构
|
||
│ ├── logging.py # 结构化日志（JSON）
|
||
│ ├── metrics.py # Prometheus 指标和装饰器
|
||
│ └── tracing.py # 分布式追踪（ContextVar）
|
||
├── utils/ # 工具函数
|
||
│ └── validators.py # 输入验证
|
||
├── config.py # 配置管理（pydantic-settings）
|
||
└── main.py # FastAPI 应用入口
|
||
```
|
||
|
||
## 关键设计约定
|
||
|
||
1. **算法抽象层**：所有算法继承 `BaseAlgorithm`，只实现 `process()`；`execute()` 负责埋点、日志和错误包装。
|
||
2. **依赖注入**：FastAPI `Depends()` 注入 `request_id`，通过 `ContextVar` 透传。
|
||
3. **配置管理**：`pydantic-settings` 读取环境变量或 `.env`，支持类型校验。
|
||
4. **可观测性**：JSON 结构化日志、Prometheus 指标、Request ID 追踪。
|
||
5. **Pydantic V2**：使用 `ConfigDict` 和 `model_config`，不使用 `class Config`。
|
||
|
||
## 常用命令
|
||
|
||
环境设置：
|
||
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
运行服务：
|
||
|
||
```bash
|
||
./scripts/run_dev.sh
|
||
uvicorn functional_scaffold.main:app --reload --port 8000
|
||
```
|
||
|
||
测试与质量：
|
||
|
||
```bash
|
||
pytest tests/ -v
|
||
black src/ tests/
|
||
ruff check src/ tests/
|
||
```
|
||
|
||
## 添加新算法（简版步骤）
|
||
|
||
1. 在 `src/functional_scaffold/algorithms/` 新建算法类，继承 `BaseAlgorithm` 并实现 `process()`。
|
||
2. 在 `algorithms/__init__.py` 导出新算法类。
|
||
3. 在 `api/routes.py` 添加端点，在 `api/models.py` 添加请求/响应模型。
|
||
4. 在 `tests/` 编写对应测试。
|
||
|
||
## 交付标准
|
||
|
||
必须包含以下组件与规范：
|
||
|
||
- `/invoke`, `/jobs`, `/healthz`, `/readyz`, `/metrics` 端点
|
||
- 统一的请求/响应 Schema 与错误格式
|
||
- 可观测性支持（日志、指标、追踪）
|
||
|
||
## 开发理念
|
||
|
||
算法同学只需关注 `process()` 的核心逻辑，其余基础设施能力由脚手架提供。
|
||
|