luoome AGENTS.md

AGENTS.md — luoome 编码 Agent 开发规范

本文件面向在仓库内修改代码的 Claude Code、Codex、Cursor 等编码 Agent。 如果要让外部 Agent 调用 luoome，请安装 luoome Skill，不要把本文件当作 MCP 接入手册。

权威资料

主题	事实来源
项目入口与环境变量	README.md
文档导航	docs/README.md
领域语言	CONTEXT.md
模块边界、数据流、Tool/Workflow 契约	docs/ARCHITECTURE.md
开发环境、代码规范、扩展与 PR 流程	docs/CONTRIBUTING.md
副作用、鉴权与投资建议边界	docs/SECURITY.md
命令和测试入口	package.json

不要在本文件复制完整 tool 清单、测试数量或版本快照。运行时 tool 库存以 packages/tools/src/registry.ts、MCP discovery 和 luoome tools list --json 为准。

开始修改前

1. 查看当前分支和工作树，区分用户已有改动与本任务改动。
2. 读取目标文件及相邻测试，确认现有模式后再写代码。
3. 涉及领域概念时先读 CONTEXT.md；涉及跨包契约时读 docs/ARCHITECTURE.md 对应章节。
4. 只实现明确需求，不顺手加功能、兼容层、抽象或无关重构。
5. 优先编辑已有文件；除需求确实需要外，不新建文档、配置或 helper。

架构硬约束

cli / tui / mcp / web ──► tools ──► core
                          │
                          └─► { db, adapters } ──► core
workflows ──► tools ──► core

• packages/core 是纯领域层，零 IO，不反向依赖其它包。
• db 与 adapters 可依赖 core，不可依赖 tools、workflows 或 surface。
• CLI、TUI、MCP、Web 统一通过 tools 使用业务能力，不复制领域逻辑。
• Tool 的 input/output 由 Zod schema 定义，并派生 TypeScript、MCP 与 OpenAI schema。
• Tool 对调用方永远返回 ToolResult；失败使用既有 ToolError.kind，不把异常泄漏为调用协议。
• Workflow 只通过 ctx.tools.* 编排能力，不直接绕过 tool 调 repository 或 adapter。
• 新 repository 必须同时提供 drizzle 与 in-memory 实现，并复用 contract tests 验证一致性。
• Drizzle schema 与 ensureSchema 的 SQLite DDL 必须同步；存量库变更要保持启动迁移幂等。

实现约定

• 使用 Bun workspace、TypeScript strict、ESM 与 .js import 后缀；格式和 lint 以 Biome 为准。
• 信任内部类型和框架保证，只在用户输入、HTTP、MCP、外部 API 等系统边界校验。
• 不变量放在 core 的 schema/assertion 中，不在各 surface 重复实现。
• 不新增自动交易路径；Watchlist、AlertPlan、WatchTrigger 等产品语义以 CONTEXT.md 为准。
• Web 保持 Hono + 原生 HTML/CSS/JS 的现有技术栈；UI 改动除自动测试外必须实际启动并用浏览器验证。
• 默认不写解释代码“做什么”的注释；仅在隐藏约束、非显然原因或必要 workaround 处说明“为什么”。
• 不为无法发生的内部状态增加 fallback；外部依赖失败按已有错误模型处理。