docs(AGENTS): 新增AI行为准则规范
- 添加代码存放位置规则,强制代码存放于 src/ 或 tests/ 目录 - 添加 Tests 目录代码运行规则,强制使用 pytest 运行测试代码 - 更新 learn_to_rank 实验代码:调整因子列表和处理器配置 - 修复 schema_cache 表结构缓存逻辑
This commit is contained in:
68
AGENTS.md
68
AGENTS.md
@@ -297,6 +297,24 @@ storage = Storage(read_only=True) # 默认只读
|
||||
storage = Storage(read_only=False)
|
||||
```
|
||||
|
||||
### 财务数据表与 PIT 策略
|
||||
|
||||
**重要**: 并非所有财务数据表都支持 PIT(Point-In-Time)策略。
|
||||
|
||||
**支持 PIT 的财务表**(有 `f_ann_date` 列):
|
||||
- `financial_income` - 利润表
|
||||
- `financial_balance` - 资产负债表
|
||||
- `financial_cashflow` - 现金流量表
|
||||
|
||||
**不支持 PIT 的财务表**(只有 `ann_date` 列):
|
||||
- `financial_fina_indicator` - 财务指标表
|
||||
|
||||
**因子字段路由规则**:
|
||||
因子引擎在动态路由字段时会自动识别财务表。对于同时存在于多个表的字段(如 `ebit`):
|
||||
- 如果字段存在于 `fina_indicator` 表和其他财务表,会优先路由到支持 PIT 的表
|
||||
- `fina_indicator` 表由于缺少 `f_ann_date`,**被排除在动态字段路由之外**
|
||||
- 这确保了所有财务数据都能正确应用 PIT 策略,避免未来数据泄露
|
||||
|
||||
### 线程与并发
|
||||
- 对 I/O 密集型任务(API 调用)使用 `ThreadPoolExecutor`
|
||||
- 实现停止标志以实现优雅关闭:`threading.Event()`
|
||||
@@ -869,6 +887,56 @@ LSP 报错:Syntax error on line 45
|
||||
❌ 错误做法:删除文件重新写、或者忽略错误继续
|
||||
```
|
||||
|
||||
### 代码存放位置规则
|
||||
|
||||
**⚠️ 强制要求:所有代码必须存放在 `src/` 或 `tests/` 目录下。**
|
||||
|
||||
1. **源代码位置**
|
||||
- 所有正式功能代码必须放在 `src/` 目录下
|
||||
- 按照模块分类存放(`src/data/`、`src/factors/`、`src/training/` 等)
|
||||
|
||||
2. **测试代码位置**
|
||||
- 所有测试代码必须放在 `tests/` 目录下
|
||||
- **临时测试代码**:任何临时性、探索性的测试脚本也必须写在 `tests/` 目录下
|
||||
- 禁止在项目根目录或其他位置创建临时测试文件
|
||||
|
||||
3. **禁止事项**
|
||||
- ❌ 禁止在项目根目录创建 `.py` 文件
|
||||
- ❌ 禁止在 `docs/`、`config/`、`data/` 等目录存放代码文件
|
||||
- ❌ 禁止创建 `test_xxx.py`、`tmp_xxx.py`、`scratch_xxx.py` 等临时文件在项目根目录
|
||||
|
||||
4. **正确示例**
|
||||
```
|
||||
✅ src/data/new_feature.py # 新功能代码
|
||||
✅ tests/test_new_feature.py # 正式测试
|
||||
✅ tests/scratch/experiment.py # 临时实验代码(在 tests 下)
|
||||
```
|
||||
|
||||
### Tests 目录代码运行规则
|
||||
|
||||
**⚠️ 强制要求:`tests/` 目录下的代码必须使用 pytest 指令来运行。**
|
||||
|
||||
1. **运行方式**
|
||||
- ✅ **必须**:使用 `uv run pytest tests/xxx.py` 运行测试文件
|
||||
- ❌ **禁止**:直接使用 `uv run python tests/xxx.py` 或 `python tests/xxx.py`
|
||||
|
||||
2. **原因说明**
|
||||
- pytest 提供测试发现、断言重写、fixture 支持等测试专用功能
|
||||
- 统一使用 pytest 确保测试代码在标准测试框架下执行
|
||||
- 便于集成测试报告、覆盖率统计等功能
|
||||
|
||||
3. **正确示例**
|
||||
```bash
|
||||
# ✅ 正确:使用 pytest 运行
|
||||
uv run pytest tests/test_sync.py
|
||||
uv run pytest tests/test_sync.py::TestDataSync
|
||||
uv run pytest tests/ -v
|
||||
|
||||
# ❌ 错误:直接使用 python 运行
|
||||
uv run python tests/test_sync.py
|
||||
python tests/test_sync.py
|
||||
```
|
||||
|
||||
### Emoji 表情禁用规则
|
||||
|
||||
**⚠️ 强制要求:代码和测试文件中禁止出现 emoji 表情。**
|
||||
|
||||
Reference in New Issue
Block a user