docs(AGENTS): 新增AI行为准则规范

- 添加代码存放位置规则,强制代码存放于 src/ 或 tests/ 目录
- 添加 Tests 目录代码运行规则,强制使用 pytest 运行测试代码
- 更新 learn_to_rank 实验代码:调整因子列表和处理器配置
- 修复 schema_cache 表结构缓存逻辑
This commit is contained in:
2026-03-14 00:19:03 +08:00
parent 3f8ca2cebf
commit 282fe1fef5
5 changed files with 302 additions and 214 deletions

View File

@@ -297,6 +297,24 @@ storage = Storage(read_only=True) # 默认只读
storage = Storage(read_only=False)
```
### 财务数据表与 PIT 策略
**重要**: 并非所有财务数据表都支持 PITPoint-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 表情。**