harness

[hellokang]

本次 PR：为项目引入 AI Agent Harness 基础设施

让仓库本身成为 AI agent 的单一事实来源——agent 看不到的就不存在。本 PR 不改任何业务代码，只补文档、linter、运行时契约与构建入口。

导航与文档

• AGENTS.md — agent 入口导航地图（编号分节，每条论断 cite file:line）
• docs/ARCHITECTURE.md — 分层（entry: job/web → core: core/lib/trade）、边界调用统计、热点函数、入口点清单
• docs/DEVELOPMENT.md — 真实 run/build/lint 命令、cron 调度、配置文件
• docs/design-docs/ — data-pipeline / trade-engine / web-layer / strategy-system 四份设计文档
• USAGE.md — 面向用户的精简使用说明（配置 / 构建 / 运行），原 README 不动

机械执行的不变量（Linter，纯 stdlib）

• scripts/lint-deps.py — 包层级依赖检查：lib(layer 0) 不得 import 更高层，core/trade/job/web 逐层向下约束
• scripts/lint-quality.py — bare except、tab/空格混用缩进、print 当日志等基础质量规则

运行时契约

• harness/config/environment.json — DB / Web / supervisord / cron / env vars / config files 生态契约，密钥用 ${VAR} 占位
• harness/scripts/{setup-env,start-server,teardown-env,run-job}.sh — 自包含、已 chmod +x

构建入口

• Makefile — help / install-deps / lint / lint-arch / lint-quality / build / test / run / run-job / setup-env / teardown-env

关键发现（已在文档记录，本 PR 不修）

• 既有 lib→core 循环依赖：instock/lib/trade_time.py:5 → instock.core.singleton_trade_date。lib 本应为最底层。linter 检出并降级为 warning（exit 0），新增同类回归仍会 fail。
• execute_daily_job.py 中部分子作业默认被注释，仅跑建库 + 基础数据 + 选股。
• lint-quality 报 3 处 pre-existing bare-except（如 trade/robot/infrastructure/strategy_wrapper.py:37），属遗留代码问题，未在本次范围内处理。

使用

make help            # 看全部目标
make setup-env       # 起 MariaDB
make run             # 起 Web（9988）
make run-job ARGS="2023-03-01"
make lint-arch       # 层级依赖检查