mommy-chaogu: Instructions file for Codex

AGENTS.md

给 AI agent（和人类开发者）的项目指南。开始工作前先读这份。

审查入口（所有 Agent 共用）

开展架构、正确性、数据、研究或发布审查，以及修改相应核心契约前，必须阅读 系统性审查指南。它服从本文件的产品定位与产品交付原则。 局部审查按影响范围选用相关检查，不要求每个小改动全面审计；系统性审查必须交代 Market Time、Data Quality、Quantitative Validation、Release Integrity 四个领域的覆盖与未验证项。

• 先写用户可观察的目标，记录版本、commit 与工作区差异，再沿实际调用链验证；旧报告只是线索。
• 按 Audit → Design → Implement → Validate 推进；区分已证实缺陷、条件性风险、待验证假设。 每项重要发现说明触发输入、用户后果、根因、证据、现有测试缺口与兼容性影响。
• 优先处理静默错误和误导性输出；将关键不变量映射到根因测试与用户验收。 测试通过不等于研究有效，更不等于策略可执行。
• 第一轮默认交付证据审查、必要的架构建议、分阶段计划和测试矩阵。 审查请求本身不授权修复、存量数据改写或迁移；已有明确实现授权时继续其授权范围内的工作。
• 只有证据说明局部修复不足，才提出共用抽象，并比较局部修复、复用与新增抽象的成本。 涉及存量金融数据、数据库迁移或重要研究口径变化时，先列影响、验证证据与恢复方案，再按授权实施。
• 未运行的检查、不可还原的历史信息与未覆盖路径必须明确列出；不得把规范落盘宣称为缺陷修复 或系统已通过审计。审查快照落在 docs/archive/，稳定原则更新本指南；不得另造产品方向。

快速上手

uv sync --extra dev      # 安装依赖
uv run pytest -m "not network"   # 跑测试（2,082 个离线用例，另有 14 个网络探针）
uv run ruff check .      # lint
uv run mypy --strict src # type check

密钥配置

推荐运行 uv run mommy setup，交互式选择 Provider / 模型、隐藏输入并验证 Key， 还可继续扫码连接微信。安装用户的配置默认保存到 ~/.config/mommy-chaogu/.env（0600，不入仓）；只有当前仓库的项目 .env 已包含 有效 Provider 或 API key 时才会就地更新。可用 --local / --user 显式选择作用域， 用 --check 脱敏检查生效来源：

cp .env.example .env       # 复制模板
# 编辑 .env，填入需要的 key

支持的 key（根据生效的 AGENT_PROVIDER 自动读取对应的一项）：

Provider	环境变量	说明
deepseek（默认）	DEEPSEEK_API_KEY	DeepSeek API
openai	OPENAI_API_KEY	OpenAI / 兼容接口（有 embedding 接口，向量检索可用）
kimi	MOONSHOT_API_KEY	Moonshot / Kimi
zai	ZAI_API_KEY	z.ai / GLM-4.7
minimax	MINIMAX_API_KEY	MiniMax 开放平台按量 API（M3，非 Coding Plan）
—	AGENT_PROVIDER	覆盖 provider（不重启改 .env）
—	AGENT_MODEL	覆盖聊天模型名

优先级：shell 环境变量 > 项目 .env > 用户级 .env > 代码默认值。Provider 与 model 按来源成组解析，禁止跨层拼接；config.toml 仅用于可选高级 Web 参数。provider 配置表 （base_url / 默认模型 / env key / 温度 / embedding 模型）的单一真相源是 src/mommy_chaogu/agent/llm.py——改 provider 只动它，不要另起表。

数据库布局（2026-07-03 重组）

⚠️ 如果你是从旧版本升级，请先跑迁移脚本：