Roog (顾新培)
8ca2f64f7e
变更内容： - 删除 `src` 子目录，将模块引用路径从 `src.functional_scaffold` 更新为 `functional_scaffold`。 - 修改相关代码、文档、测试用例及配置文件中的路径引用，包括 `README.md`、`Dockerfile`、`uvicorn` 启动命令等。 - 优化项目目录结构，提升代码维护性和可读性。
3.5 KiB
3.5 KiB
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 应用入口
关键设计约定
- 算法抽象层：所有算法继承
BaseAlgorithm，只实现process()；execute()负责埋点、日志和错误包装。 - 依赖注入：FastAPI
Depends()注入request_id，通过ContextVar透传。 - 配置管理：
pydantic-settings读取环境变量或.env，支持类型校验。 - 可观测性：JSON 结构化日志、Prometheus 指标、Request ID 追踪。
- Pydantic V2：使用
ConfigDict和model_config，不使用class Config。
常用命令
环境设置：
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
运行服务：
./scripts/run_dev.sh
uvicorn functional_scaffold.main:app --reload --port 8000
测试与质量：
pytest tests/ -v
black src/ tests/
ruff check src/ tests/
添加新算法（简版步骤）
- 在
src/functional_scaffold/algorithms/新建算法类，继承BaseAlgorithm并实现process()。 - 在
algorithms/__init__.py导出新算法类。 - 在
api/routes.py添加端点，在api/models.py添加请求/响应模型。 - 在
tests/编写对应测试。
交付标准
必须包含以下组件与规范：
/invoke,/jobs,/healthz,/readyz,/metrics端点- 统一的请求/响应 Schema 与错误格式
- 可观测性支持（日志、指标、追踪）
开发理念
算法同学只需关注 process() 的核心逻辑，其余基础设施能力由脚手架提供。