Python Agent 开发规范
司册项目的 Python Agent 代码编写规范，基于 Deep Agents 框架。
背景参考: 技术选型和架构决策详见 Python-Agent-技术架构（待补充）
技术栈
| 组件 | 选择 | 版本 |
|---|---|---|
| Python | 3.12.x | >=3.12 |
| 包管理器 | uv | - |
| Web 框架 | FastAPI | >=0.100 |
| Agent 框架 | Deep Agents | >=0.5.0a2 |
| CLI 框架 | Typer | >=0.9.0 |
| 打包 | Nuitka | >=2.6 |
目录结构
agent/
├── pyproject.toml # Python 项目配置
├── langgraph.json # LangGraph 配置文件
├── uv.lock
│
├── scripts/ # 脚本目录
│ ├── run.sh # 开发启动脚本
│ └── build-bin.sh # Nuitka 打包脚本
│
└── app/ # 所有实现代码
├── __init__.py # 包版本、公共导出
├── __main__.py # CLI 入口: python -m app
├── agent.py # LangGraph 入口 (Deep Agents 初始化)
├── main.py # FastAPI 应用工厂 (含生命周期管理)
├── config.py # 配置管理
├── cli.py # CLI 命令 (Typer)
├── auth.py # 令牌验证
│
├── api/ # FastAPI 路由层
│ ├── __init__.py
│ ├── health.py # /health
│ ├── chat.py # /chat
│ └── sse.py # SSE 封装
│
├── service/ # 业务服务层（预留）
│
├── sice_agent/ # Agent 能力实现子包
│ ├── tools/ # 工具实现
│ ├── prompts/ # 提示词模板
│ └── utils/ # 工具函数
│
└── types/ # Pydantic 类型定义
├── __init__.py
└── schemas.py # Pydantic 模型关键文件职责
| 文件 | 职责 | 被谁调用 |
|---|---|---|
app/agent.py | Deep Agents 初始化 | LangGraph CLI、FastAPI、CLI |
app/main.py | FastAPI 应用工厂（含生命周期管理） | serve 命令、uvicorn |
app/cli.py | CLI 命令定义 | __main__.py、打包后的可执行文件 |
app/__main__.py | 入口转发 | python -m app |
代码编写规范
1. 配置管理 (config.py)
关键规则：
- 使用
pydantic-settings的BaseSettings - 环境变量前缀必须是
SICE_ - 数据目录默认
~/.sice/，可通过SICE_DATA_DIR覆盖 - 端口
0表示随机分配 - 状态文件路径
~/.sice/agent-state.json
2. FastAPI 生命周期 (main.py)
关键规则：
- 使用
@asynccontextmanager定义lifespan - Agent 初始化在 lifespan 的启动阶段完成
- 资源清理在 lifespan 的关闭阶段完成
- 使用
create_app()工厂函数创建应用 - 禁止单独创建
core.py或lifecycle.py
3. Agent 初始化 (agent.py)
关键规则：
- 使用
create_deep_agent()创建实例 - 文件路径必须是
app/agent.py - 导出
agent变量供 LangGraph CLI 使用 - 同时支持 LangGraph Dev 和 FastAPI 内嵌两种模式
- 模型配置通过环境变量读取，支持兼容 OpenAI 规范的第三方模型
4. SSE 流式响应 (api/sse.py)
关键规则：
- 使用
StreamingResponse返回 SSE 流 - 数据格式必须是
data: {json}\n\n - 结束标记必须是
data: [DONE]\n\n - 使用
json.dumps()序列化事件数据
5. 工具定义规范
关键规则：
- 使用
langchain_core.tools的@tool装饰器 - 必须编写详细的 docstring 描述工具功能
- 参数和返回值类型必须注解
- 工具函数保持纯函数特性（无副作用）
三种使用模式
模式 1: LangGraph Dev 模式（开发时使用）
开发阶段使用 LangGraph CLI 进行调试：
bash
langgraph dev --port 2026 --no-browser
# 或
./scripts/run.sh dev模式 2: FastAPI 服务模式（服务器部署时使用）
作为独立服务运行，内嵌 LangGraph runtime：
bash
# 开发模式
python -m app serve up
# 或
./scripts/run.sh serve
# 生产模式
sice-cli serve start模式 3: CLI 模式（终端用户主要使用模式）
打包为二进制命令行单文件，面向终端用户的完整方案，支持通过 Tauri 的 Sidecar 模式调用。
CLI 架构设计：
- 采用二级命令设计，同一业务类型的命令组合在一起
- 一级和二级命令都提供
--help帮助信息
状态文件位置: ~/.sice/
agent.pid- 进程IDagent.port- 监听端口agent.log- 运行日志config.json- 用户配置
开发命令
bash
# 进入目录
cd agent
# 激活虚拟环境
source .venv/bin/activate
# 同步依赖
uv sync
# 启动服务
./scripts/run.sh dev # LangGraph CLI
./scripts/run.sh serve # FastAPI Server
# 打包
./scripts/build-bin.sh关键检查点
| 阶段 | 检查项 |
|---|---|
| 配置 | 环境变量 SICE_* 能正确读取 |
| 目录 | 数据目录自动创建（权限 0o700） |
| 状态 | agent-state.json 写入正确 |
| 启动 | /health 返回 200 |
| 流式 | /chat 返回 SSE 流 |
| 认证 | 无效令牌返回 401 |
禁止事项
- ❌ 不要将敏感信息写入日志
- ❌ 不要提交
.env.*文件 - ❌ 不要在代码中硬编码 API 密钥
- ❌ 不要将
__pycache__提交到仓库 - ❌ 不要随意变更目录结构，任何设计变更需要先确认
测试用例规范
目录结构
测试文件按模块命名：test/test_模块名.py
编写原则
- 验证为主：每个测试验证一个特定行为或边界条件
- 不依赖外部服务：单元测试不访问网络、数据库或外部 API
- 快速运行：所有单元测试应能在几秒内完成
- 沉淀资产：实现新功能或修复 bug 时，同步添加对应测试用例
命名规范
- 测试文件：
test_模块名.py（例如test_config.py） - 测试函数：
test_功能名()（例如test_token_generation()）
安全设计测试要点
| 设计点 | 测试验证 |
|---|---|
| 令牌生成 | 每次重启必须生成不同的令牌 |
| 文件权限 | 状态文件权限必须是 0o600，目录 0o700 |
| 敏感信息 | 日志中不能输出完整令牌 |
E2E 测试验证要求
功能开发完成后必须进行端到端测试验证，不能仅依靠单元测试交付
必须验证：
- 启动验证：两种启动方式（LangGraph CLI、自定义 CLI）都能正常启动
- 端点验证：
/health返回 200，/chat能正常输出 SSE 流 - 环境变量验证：
.env文件加载和环境变量覆盖正常工作 - 流式验证：输出正常 SSE 流并以
data: [DONE]结束