# 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()` 的核心逻辑，其余基础设施能力由脚手架提供。