ThumbAgent: Instructions file for Codex

ThumbAgent Agent Guide

本文件适用于整个仓库。子目录存在更具体的 AGENTS.md 时，子目录规则在其作用域内优先。

1. 开始工作前

必须依次阅读：

1. README.md
2. docs/product/positioning.md
3. docs/product/solution-v1.md
4. docs/architecture/technical-design-v1.md
5. docs/engineering/development.md
6. docs/iterations/README.md
7. docs/engineering/iteration-process.md
8. 与任务相关的迭代文档、目录级 AGENTS.md 和 ADR

修改 Contract、Skill、持久化、执行语义或错误体系时，还必须阅读对应专项规范：

• docs/engineering/contract-versioning.md
• docs/architecture/capability-model.md
• docs/engineering/skill-development.md
• docs/architecture/reliability-model.md
• docs/engineering/data-migrations.md
• docs/engineering/error-handling.md

开始修改前必须检查工作区状态。已有修改可能属于用户或其他 Agent，不得覆盖、回滚或顺手重构。

2. V1 边界

V1 目标是完成单台 Android 设备的本地 AI-to-Device 闭环：设备发现、Observation、基础动作、Skills、任务状态、安全策略、证据和报告。

未经明确任务授权，不实现：

• iOS 或鸿蒙真实 Adapter
• 多设备并行调度
• 任意 Shell 执行
• 支付、验证码或权限绕过
• 云端账号、团队空间或遥测上传
• 与当前任务无关的未来能力

3. 强制架构边界

依赖只能沿以下方向：

Clients / Interfaces
        ↓
Application / Skills / Task Engine
        ↓
Domain / Policy / Contracts
        ↓
Device Gateway
        ↓
Platform Adapters

• Desktop、CLI、MCP 不得直接执行 ADB 或修改任务存储。
• Skill 不得绕过 Tool Registry、Policy Engine 或 Device Gateway。
• Domain 不得依赖 FastAPI、Tauri、具体模型 SDK 或 Android 实现。
• Adapter 不得包含产品流程、Agent 决策或 UI 逻辑。
• MCP 是外部接口，不是内部模块总线。
• 模型输出一律视为不可信输入。

详见 docs/architecture/rules.md。

4. Contract-first

跨模块数据必须先在 contracts/schemas/ 定义 Schema，再生成或实现语言类型。

以下对象禁止由 Python 与 TypeScript 各自手写一份近似定义：

• Device
• Observation
• Task
• ToolCall
• Skill Manifest
• Error
• Event

修改 Contract 时必须：

1. 说明兼容性影响。
2. 更新生成类型或消费者。
3. 添加 Contract 测试。
4. 必要时增加 ADR。

5. 安全规则

• 禁止 shell=True。
• 禁止拼接模型文本形成命令。
• 系统进程必须使用固定可执行文件和参数数组。
• 所有设备动作必须绑定明确的 device_id。
• 所有动作必须经过 Schema、Capability 和 Policy 校验。
• 密钥、令牌、密码、验证码不得写入代码、数据库、日志或测试快照。
• 高风险动作不得以“开发方便”为理由绕过确认。
• 不得实现隐藏的任意命令逃生口。

详见 docs/engineering/security.md。

6. 代码要求

• Python 新代码必须有类型标注；公共接口必须有简洁 docstring。
• TypeScript 禁止无理由使用 any。
• 领域错误使用统一错误码，不以裸字符串跨层传播。
• I/O、时间、随机数、模型和设备依赖必须可替换，便于测试。
• 不为假想需求提前抽象；出现第二个真实实现需求时再提炼通用层。
• 不混入与当前任务无关的格式化、重命名或重构。
• 注释解释原因和约束，不重复代码表面含义。