Seeed-Jetson-DevelopTool: Instructions file for Codex

AGENTS.md — 项目规则

本文件是 AI 编码代理（Codex / Claude / 同类工具）在本仓库工作时的操作守则。先读它，再动手。

项目一句话

Seeed Jetson Develop Tool：PyQt6（qtpy）桌面客户端，面向 Seeed Jetson 开发者的上位机 —— 烧录、设备诊断、远程开发、应用市场、Skills、OTA、社区。深色科技风 UI。

规则优先级

1. 用户明确指令（本次会话中最高）
2. 本文档（AGENTS.md）
3. design.md（UI 设计规范，唯一权威）
4. CONTEXT.md（架构背景）
5. 既有代码里的既有模式（新代码遵循，不是照抄所有历史代码）

任何 UI 改动前必须先读 design.md，并严格遵守。UI 规范冲突时以 design.md 为准。

UI 改动铁律（违反即返工）

• 颜色 / 字体 / 圆角 / 阴影 token 只允许来自 gui/theme.py 常量；禁止在页面代码写字面量色值。
• 组件一律用工厂函数：make_button / make_label / make_card / make_input_card / make_section_header / make_log_view / make_input_field / make_tab_button / ShinyProgressBar / StepIndicator / StatusBadge / EmptyStateWidget / ToastNotification。
• 禁止原生 QMessageBox；用 theme.show_info_message / show_warning_message / show_error_message / ask_question_message。
• 字号必须经 pt()（Windows DPI 缩放）；font-family 走 build_app_font() / build_mono_font()，不硬编码。
• Emoji 必须彩色：含 emoji 的 QLabel 用 make_label() 或 set_emoji_font_for_label()。
• 新页面继承 widgets/page_base.PageBase；筛选列表页继承 widgets/list_page_base.ListPageBase。禁止脱离设计系统自建页面骨架。
• 操作反馈：Toast 通知 + StatusBadge；禁止用"日志追加一行"代替操作反馈。
• 空状态用 EmptyStateWidget，禁止裸 "No data"。
• 耗时操作必须 QThread + 信号回主线程，禁止阻塞 UI。
• QGraphicsDropShadowEffect 不与高频 QTimer 重绘叠加（Windows 崩溃史）；阴影对象销毁时 clear_shadow()。

国际化铁律

• 文案唯一入口：seeed_jetson_develop.gui.i18n.t(key, **kwargs)。
• **禁止使用 gui/runtime_i18n.py（已废弃）**及其 ZH_EN_EXACT 字典方式。
• 新文案必须同时写入 locales/en/<module>.json 与 locales/zh-CN/<module>.json。
• Key 命名：<module>.<区域>.<名称> 小写点分式，如 ai_chat.btn.send、skills.search.placeholder。
• 占位符用 {name}（str.format）；支持 t("…", lang=…) 与运行时 retranslate_ui() 切换。

代码地图

run_v2.py                        # 启动入口（python3 run_v2.py [--debug-console]）
seeed_jetson_develop/
  gui/
    theme.py                     # ★ 设计 token + 组件工厂（唯一权威）
    styles.py                    # 旧版浅色 QSS（历史兼容，新代码勿扩展）
    ai_chat.py                   # AI 悬浮球入口（点击进入 Agent 页，inject_* 转发）
    i18n.py                      # ★ 现代 key 式国际化
    runtime_i18n.py              # 已废弃，禁止使用
    main_window_v2.py            # 主窗口组装
    widgets/                     # ★ 组件库：page_base / list_page_base / empty_state /
                                 #   toast_notification / loading_spinner / breathing_* /
                                 #   animated_* / ripple_button / focus_ripple_edit / ...
  modules/<flash|devices|apps|skills|agent|remote|ota|community>/
    page.py                      # 各功能页（迁移目标：全部基于 PageBase）
    thread.py / *.py             # 后台线程与业务逻辑
  modules/agent/                 # ★ AI Agent 页：复用本机 claude/codex CLI 驱动 Jetson/
                                 #   Physical AI（backend.py 流式包装 / cli_tools.py CLI
                                 #   检测与 skills 目录约定 / agent_setup_dialog.py 本机补装）
  locales/en|zh-CN/*.json        # 双语文案
  skills/{openclaw,claude,codex}/<slug>/  # ★ 内置技能库（运行时读取此包内树）：
                                 #   openclaw→SKILL.md、claude→CLAUDE.md、codex→AGENTS.md，
                                 #   内容相同仅 marker 文件名不同；references/scripts 子目录原样。
                                 #   仓库顶层 skills/ 是同构副本，新增技能时两棵树都要同步。
  data/                          # BSP / 产品图 / Recovery 元数据
  core/                          # events(事件总线) / runner / config ...
design.md                        # ★ UI 设计规范（改动 UI 先读它）
AGENTS.md                        # 本文件
CONTEXT.md                       # 架构演进背景