📖 技能介绍

name: code-standards description: 代码规范检查清单。当用户要求写代码、创建新文件、实现功能、添加模块、修改代码结构、创建 temporal 工作流、或进行任何代码开发工作时，必须先调用此 skill 确保遵循规范。

代码规范 Skill

触发时机

用户要求写代码、实现功能、创建模块
创建或修改 temporal 工作流
添加新的 service、activities、models
任何代码开发工作开始前

写代码前必做

第一步：更新 item.md 文档 - 记录项目流程 - 记录主要类和函数（含输入输出） - 记录 temporal/api 调用链路 - 这里面只记录主要函数的调用

第二步（仅新建文件时）：查阅目录结构 - 当需要新建文件时，先阅读 directory-structure.md（同目录下） - 根据目录结构确定文件应该放置的位置

代码规范清单

1. 依赖注入

✅ 所有依赖注入必须在文件开头注入

2. 日志规范

✅ 必须使用 src/infrastructure 中的日志格式

3. 组件管理

✅ 常用组件（数据库连接等）在 src/infrastructure 中创建类统一管理

3.1 基础组件示例

数据库连接 位于 database_examples/ 目录：

数据库	示例文件	使用场景
MySQL	`mysql_example.py`	关系型数据存储、事务性操作
PostgreSQL	`postgresql_example.py`	关系型数据、JSONB 字段支持
MongoDB	`mongodb_example.py`	文档型数据、灵活 Schema、Decimal 编解码
Redis	`redis_example.py`	缓存、分布式锁、消息队列
Presto/Trino	`presto_example.py`	大数据查询、OLAP、流式查询

Temporal/日志 位于 examples/ 目录：

示例文件	使用场景
`temporal_client_example.py`	客户端单例管理、工作流启动/查询/取消
`logger_example.py`	Loguru 日志配置（控制台+文件、轮转、压缩）

使用步骤： 1. 复制对应示例文件到目标目录 2. 调整参数（从 config 读取）

4. Temporal/Modules 目录结构

✅ temporal/ 和 modules/ 必须包含：

temporal/
├── workflow/
├── activities/
├── service/
└── models/

每个workflow的activitie和service都要定义成类。

5. 环境变量与全局变量

✅ 必须在 config/ 文件夹中注入
环境变量中的常量和哪些放进.env文件的每次新增都得询问我

6. 函数命名

✅ 次要函数命名加 _ 前缀（如 _helper_function）
✅ 次要函数不记录在 item.md 中

7. 数据结构pydata的校验

✅ 不要每一种数据都定义数据结构，只有主要函数的需要定义，减少该部分代码量

item.md 文档格式

文档结构

# 项目名称

## 目录结构
[项目目录树，作为第一章]

---

## 项目流程
[整体流程图]

### Step 1: 步骤名称
[步骤说明表格]

### Step 2: 步骤名称
[步骤说明表格]

#### 子流程/节点执行顺序
[子流程表格]

#### 内部服务调用
[服务调用表格]

---

## 数据模型
[模型索引表]

---

## 代码位置索引
[代码位置索引表]

流程步骤表格格式

每个流程步骤使用表格标注类/方法/输入输出/文件位置/错误处理：

### Step N: 步骤名称

| 项目 | 说明 |
|------|------|
| **Workflow** | `WorkflowClass` - src/temporal/workflow.py |
| **Activity** | `activity_name()` - src/temporal/activities.py |
| **Agent** | `AgentClass` - src/langgraph/agent.py |
| **Graph** | src/langgraph/graph.py |
| **输入** | `InputModel` - src/temporal/models.py |
| **输出** | `OutputModel` - src/temporal/models.py |
| **功能** | 功能描述 |
| **错误处理** | 错误类型 → 处理策略 (最大重试次数) |
| **执行条件** | 条件说明（可选） |

执行检查

在开始编码前，按以下顺序确认： 1. [ ] item.md 已更新 2. [ ] item.md 目录结构作为第一章 3. [ ] item.md 项目流程每步标注类/方法/输入输出/文件位置/错误处理 4. [ ] 依赖注入位置正确 5. [ ] 日志使用正确格式 6. [ ] 目录结构符合规范 7. [ ] 环境变量在 config 中 8. [ ] 函数命名符合规范 9. [ ] 类型标注符合规范（固定类型指向 models 文件，非固定类型在 item.md 定义） 10. [ ] 错误处理策略已在 item.md 标注 11. [ ] 代码位置索引已更新