把本机 AI Agent 的运行状态、订阅额度、任务宠物与可控操作，带到妙联宝 N4 Pro 的硬件表面。
Agent Deck 是一个运行在本机的 AI Agent 硬件控制台桥接项目。它将 Agent 的状态、用量、任务宠物和经过明确配置的操作映射到妙联宝设备，并提供浏览器中的本地配置界面。当前版本 0.2.0 支持 macOS + MiraBox N4 Pro + Codex；其他操作系统、硬件型号与 Agent 平台暂不作兼容性承诺。
agent-deck-readme-preview-720p.mp4
前往介绍页面
当多个 AI Agent 同时运行时，状态、等待输入和用量信息容易散落在终端、桌面 App 和不同窗口中。Agent Deck 将这些本机信号归约为统一状态，并投影到有按键、触屏和旋钮的硬件表面：你可以一眼查看状态，切换面板或聚焦上下文，同时保持高风险动作默认关闭。
项目的核心边界始终保持为：
Agent ingress -> NormalizedEvent -> AgentStateStore -> DeckMode/LayoutPlan
-> HardwareSurface -> InteractionIntent/ActionExecutor
当前已验证的组合是 Codex 与 N4 Pro；核心架构仍为其他 Agent 与硬件保留扩展空间。
本地配置页以 N4 Pro 预览为操作入口。选择按键或旋钮后，修改会先反映在 GUI 预览中；只有点击“保存并应用”才会下发到已连接的设备。可以配置：
- 10 个 LCD 主按键的本地 App、网址、键盘快捷键、订阅/额度、Token/金额用量、Agent 状态与 Codex 宠物；ChatGPT/Codex App 启动键还可在任务活跃时临时显示宠物状态。
- 底部逻辑面板的品牌图、Codex quota、用量趋势和 PETS 多任务宠物巡游；其中用量趋势来自本地 缓存，切换时不阻塞硬件交互。
- 4 个旋钮的轮转动作，例如切换面板或周期、调整系统输入/输出音量、显示器亮度与控制台屏幕亮度。
- 旋钮灯圈组的颜色与可选呼吸效果，并在保存前预览。
键盘快捷键可以是一个物理键、一个带 Command / Control / Option / Shift 的组合键，
也可以是最多 16 步的有序序列。配置页支持一次开始后连续录制多个步骤；录制完成时点击“停止并应用”
会调用与顶部“保存并应用”相同的整机配置保存动作，也可以手动添加纯修饰键、调整步骤间隔，以及
自动生成或上传默认图标。Web 自动图标直接使用硬件 renderer 的同一张 PNG，避免预览与 N4 Pro
显示不一致。执行时会固定“开始执行那一刻”的前台 App；同一时间只执行一个
序列，执行中再次按下会立即返回忙碌而不会排队。首次使用需在配置页显式请求 macOS 辅助功能权限。
浏览器只负责配置，不需要这项权限；配置页默认只显示紧凑状态，悬停或点击“详情”后才显示实际发起
请求的 Agent 后台进程和系统设置入口。通过 tmux 启动属于开发模式，macOS 可能按启动链把
该进程显示为 Codex、Terminal 或 Python。
未连接真实设备时，配置页和核心服务仍可通过 fake hardware 运行，便于体验、开发和排障。
Agent Deck 在运行时只读复用 Codex/ChatGPT 已有的宠物资源，不在仓库中维护或重新分发第二套素材。 本机宠物默认跟随 Codex 全局选择；PETS 角色需要的内置宠物按需从已安装 ChatGPT/Codex App 读取，自定义宠物从本机 Codex 目录安全加载。
当前有三种互不替代的展示方式：
- Codex 宠物键：占用一个主按键持续展示全局 Codex 活动，按下不执行动作。
- App 键任务态覆盖：可在 ChatGPT/Codex 启动键上启用；任务运行、等待输入、错误或刚完成时 临时覆盖用户原图标，空闲后自动恢复，按键仍只负责打开或聚焦 App。
- PETS 虚拟面板：把本机与已启用 SSH Remote Connection 中处于活动或完成反馈状态的顶层 ChatGPT 任务显示为独立宠物，在 N4 Pro 底部长条区域内共同巡游。远端角色会用稳定的低饱和 光环区分执行主机。
在 Web 配置页点击 N4 Pro 预览中的 PETS touch bar，可选择远端宠物跟随本机、只读远端配置或 稳定随机内置宠物，并调整慢/中/快三档巡游速度。宠物始终只是展示层：不会参与审批、执行任务或 替代 Agent 状态键；child/subagent、v2 gaze 和鼠标跟踪也不在当前范围内。完整配置、远端素材 安全边界和诊断方式见使用指南的 Codex 宠物章节。
| 维度 | 当前状态 |
|---|---|
| 项目版本 | 0.2.0 |
| 操作系统 | macOS 为已验证目标。Windows 和 Linux 暂未正式支持。 |
| 真实硬件 | MiraBox N4 Pro。架构为其他 StreamDock/MiraBox 型号留有扩展空间，但尚未作为可用目标发布。 |
| Agent | Codex 本地 App/CLI 状态、ChatGPT SSH 远端任务观察、quota、hook 与宠物展示。 |
| Python | Python 3.11 或更高版本。 |
| 用量趋势 | 可选依赖 Bun 的 bunx 与 ccusage；缺失时，其他功能可继续运行，但 Token/金额趋势不可用。 |
完整安装、硬件接管与排障说明请阅读使用指南。下面是以 fake hardware 启动本地配置页的最短路径：
git clone https://github.com/breakstring/agent-deck.git
cd agent-deck
uv sync --all-groups
# 读取本机环境与设备线索；该命令不会写屏或接管设备。
uv run agent-deckctl doctor
# 不接管真实硬件地启动本地服务。
scripts/agent-deckd-tmux.sh start --disable-hardware-renderer然后打开 http://127.0.0.1:8765/。停止服务：
scripts/agent-deckd-tmux.sh stop若要接管 N4 Pro，请先退出官方 MiraBox/StreamDock 应用，并在启动前通过 doctor 检查设备线索。macOS 上 SDK 动态库不兼容时，需要将 AGENT_DECK_STREAMDOCK_SDK_PATH 指向官方 Python SDK；具体做法见真实硬件运行。
Agent Deck 可读取 Codex 的本地状态、quota 和 ccusage 数据，并可选安装 Codex hook 集成。安装器始终先输出 dry-run，只有显式传入 --apply 才会写入本机 Codex 配置：
# 检查当前 Codex 环境，并生成接入建议。
uv run agent-deckctl codex-detect --enable-integration
# 预览将要写入的 notify 与 hook 配置。
uv run agent-deckctl codex-install
# 确认预览无误后才实际写入。
uv run agent-deckctl codex-install --apply默认审批模式保留 Codex 原生审批界面，不会自动把审批控制权交给硬件。键盘快捷键只允许受限的
物理键/组合键/时序，不提供文本、鼠标、shell、媒体键或 Fn 注入。涉及文本输入、批准或拒绝等
高风险操作时，必须由用户显式配置；daemon 不可用、响应非法或等待超时时，审批链路按
fail-closed 策略处理。
| 命令 | 用途 |
|---|---|
uv run agent-deckd |
启动核心 daemon，接收 Agent 事件并驱动硬件渲染。 |
uv run agent-deckctl |
执行环境诊断、运行状态查看、硬件检查与事件模拟。 |
uv run agent-deck-codex-hook |
供 Codex notify/command hook 调用的桥接工具。 |
scripts/agent-deckd-tmux.sh [start|stop|status|logs|attach|restart] |
以 tmux 管理常驻服务；推荐用于日常运行。 |
./run.sh [start|stop|status|logs|restart] |
没有 tmux 时使用的普通后台管理脚本。 |
常驻 daemon 默认只记录 WARNING 及以上并关闭 HTTP access log；文件达到 5 MiB 后自动轮转，
保留 2 份历史记录。级别、access log、文件路径和轮转上限均可在 agent-deck.toml 的
[logging] 中调整，详见使用指南。
前台调试时可以直接运行：
uv run agent-deckd --host 127.0.0.1 --port 8765- 使用指南（中文）：面向普通用户的安装、启动、配置与排障步骤。
- Usage guide (English)
- 开发者 Q&A：运行结构、N4 Pro 重连/握手、macOS 权限、状态字段与真机验证。
- 贡献指南（中文）
- Contributing guide (English)
- 项目路线图：长期方向、阶段边界与待验证事项。
uv run pytest -q
uv run agent-deckctl version
git diff --check真实设备验证属于显式手动 smoke，不纳入自动化测试。提交 issue 时，请避免粘贴 API key、token、完整 prompt 或私有应用路径；详见贡献指南。
核心代码采用 MIT 许可证。vendor/streamdock-python-sdk 是用于与妙联宝/StreamDock 控制台设备通信的第三方 Python SDK，来源于 MiraboxSpace/StreamDock-Plugin-SDK，同样采用 MIT 许可证。