lobster0 AGENTS.md

Lobster0 Agent 工程规范

适用范围与优先级

• 本文件适用于整个仓库。
• 优先遵循系统、开发者和用户的直接指令；子目录更具体的 AGENTS.md 只覆盖对应目录。
• 只修改当前任务需要的文件，交付范围最小、行为正确且经过验证的变更。
• 不把 PRD 中的规划描述成已实现功能。

项目事实

• Python 最低版本为 3.12，使用 src 布局，主包位于 src/lobster0/。
• 项目、仓库、Python 导入包和 CLI 使用 lobster0，产品名写作 Lobster0。
• 构建和工具配置以 pyproject.toml 为准，包管理优先使用 uv。
• 测试位于 tests/，使用标准库 unittest；静态检查使用 Ruff，行宽为 100。
• 产品范围以 docs/product/20260807_产品需求文档.md 为准，架构边界以 docs/architecture/20260807_系统架构.md 为准。

常用命令

# 首次安装或依赖变化后
uv sync --extra dev

# 运行全部测试
uv run python -m unittest discover -s tests -v

# 静态检查
uv run ruff check .

# CLI 冒烟验证
uv run lobster0 --version

# 三平台 versioned Channel gate 与 20 轮稳定性门禁
uv run lobster0 eval run --suite channel --root evals/scenarios
uv run lobster0 eval run --suite channel --repeat 20 --json --root evals/scenarios

# Phase 6 Automation 15-case 与 20 轮稳定性门禁
uv run lobster0 eval run --suite automation --root evals/scenarios
uv run lobster0 eval run --suite automation --repeat 20 --json --root evals/scenarios

# Phase 6.5 Browser 18-case 与 20 轮稳定性门禁
uv run lobster0 eval run --suite browser --root evals/scenarios
uv run lobster0 eval run --suite browser --repeat 20 --json --root evals/scenarios

# 当前发布文档、链接、Mermaid 与 HTML 一致性
uv run python scripts/validate_docs.py

• 优先使用项目 .venv 或 uv run，不要假设系统 Python 的依赖状态。
• 单元测试必须离线、快速、可重复，不调用真实模型或飞书接口。
• 先运行与改动最相关的测试，再运行全部检查。

修改前要求

• 先运行 git status --short，识别并保护用户已有的未提交修改。
• 阅读相关实现、测试、pyproject.toml 和对应文档，沿用现有模式。
• 明确预期行为、边界条件和验证方式；修复缺陷时先写回归测试。
• 产品语义不明确时先从 PRD、测试和公开接口获取证据，仍会改变范围时再询问用户。

Python 代码规范

• 新增或修改的公共函数、方法、类属性和返回值必须有准确类型标注。
• 使用 Python 3.12 原生类型写法，避免无意义的 Any。
• 每个新增或修改的顶层函数、方法和类必须提供中文 docstring，说明用途、参数、返回值与实际异常。
• 一个函数只承担一个清晰职责；不要为单一实现创建接口、工厂或无用配置层。
• 优先使用标准库；新增第三方依赖前必须证明标准库和现有依赖无法满足需求。
• 模块导入时不得发起网络请求、创建运行目录、连接数据库或启动服务。
• 路径操作使用 pathlib.Path，文本文件显式使用 UTF-8，时间使用带时区的 UTC。
• 库代码使用日志而不是 print()；print() 仅用于明确的 CLI 输出。

架构边界

• channels：飞书、Telegram、Discord 等外部消息与内部消息互转，不包含 Agent 推理逻辑；三个平台共享一个 AgentRuntime，但 Transport、Delivery、Manager、queue 与运行期故障状态相互隔离。
• agent：管理模型与工具循环，不知道消息来自哪个渠道。
• providers：封装模型协议，v0.1 只实现一个 OpenAI-compatible Provider。
• tools：声明并执行文件、HTTP 和受限命令；不得绕过 Policy。
• policy：统一处理 Workspace、命令白名单、风险和审批。
• storage：SQLite 结构化记录以及 Markdown 记忆、Skills 的读写边界。
• evolution：反馈、评测和版本化提案；不得自动修改或部署 Python 源码。
• 这些目录只在对应里程碑实现时创建，不提前搭空抽象。