Ram AGENTS.md

Project Context

1. 技术栈

• 语言: Python
• 框架: FastAPI (Starlette)
• 构建工具: 无（直接运行）
• 测试框架: pytest + pytest-asyncio (asyncio_mode = "auto") + pytest-cov
• 静态分析: mypy（strict 模式 + pydantic.mypy 插件）
• Lint/Format: ruff（统一替代 flake8/isort/black）
• Git hooks: pre-commit（提交前自动运行 ruff check/format）
• 其他关键依赖: Pydantic v2, httpx, openai (OpenAI-compatible LLM 客户端), slack-sdk (Slack API 客户端), Alibaba Cloud OOS Python SDK, trafilatura (HTML 正文提取), markdownify (HTML→Markdown 兜底), Tavily CLI (tvly, web_search 工具的外部 CLI 依赖), SQLAlchemy (SQLite ORM，WAL 模式，trace 存储), structlog (JSON 结构化日志), aliyun CLI（部署脚本用于从 OOS 获取密钥，EcsRamRole 认证）
• Management 前端: React + Vite + TypeScript + Tailwind CSS + shadcn/ui

2. 质量检查命令

• 类型检查: mypy src/ tests/ management/api/ --no-incremental（strict 模式，tests.* 免除 disallow_untyped_defs）
• Lint: ruff check src/ tests/ management/api/
• Format: ruff format src/ tests/ management/api/
• 测试: .venv/bin/python -m pytest（含覆盖率，fail_under = 82）
• Management 前端构建: cd management/ui && npm run build（产物输出到 management/ui/dist/，由 Management API StaticFiles 提供）
• CI: GitHub Actions（.github/workflows/ci.yml），lint → (type-check ∥ test+coverage) 并行
• 构建: 未配置

3. 关键约束

• 入口仅通过 Slack Events API（app_mention、interactions、slash commands），所有外部入口必须经过签名校验与事件白名单。GitHub Webhook 端点已移除。
• 所有持久化数据统一存储在 SQLite（ram.db，WAL 模式）：trace 四表（conversations/agent_runs/llm_calls/tool_calls）+ Code Project 四表（projects/channel_bindings/thread_sessions/opencode_calls）。数据库路径通过 RAM_DB_PATH 环境变量配置（默认 data/ram.db）。
• SQLite 单写者原则：Ram 主服务负责所有写入（trace + Code Project），Management 以只读模式（?mode=ro）访问同一 ram.db 文件。SQLiteTraceRecorder 和 SQLiteCodeProjectStore 共享 SQLAlchemy engine。
• OpenCode 仅以本机 CLI 方式调用（非云端服务）。通过专用 Code Tool 调用（不在 Bash allowlist 中）。
• Bash Tool 命令受 allowlist 限制（~/.ram/config.json 的 bash_allowlist 字段），文件不存在时回退到内置默认列表。每次调用重新读取（无缓存），支持运行时修改。
• 生产密钥仅允许从阿里云 OOS 参数仓库读取。TAVILY_API_KEY 也已纳入 OOS 管理（ram_prod_tavily_api_key），由部署脚本通过 aliyun CLI 获取。
• LLM 配置通过 ~/.ram/models.json 管理（嵌套格式：provider → models），含 api_key_oos_param（OOS 参数名）、extra_body（provider-specific 扩展参数）、reasoning_field（思维链字段路径）等字段。load_model_config() 负责解析并从 OosSecretProvider 解析 API key，返回 ResolvedModelConfig。AppConfig 不再包含 LLM 字段。
• Management 仅供开发者通过 SSH 隧道访问（localhost:8001），不设应用层认证。
• opencode-config 以 Git submodule 引入（config/opencode-config/→ Hikaru518/opencode-config），/ram bind 时删除目标目录已有配置后重新拷贝，确保统一版本。