English

把本机 AI Agent 的运行状态、订阅额度、任务宠物与可控操作，带到妙联宝 N4 Pro 的硬件表面。

Agent Deck 是一个运行在本机的 AI Agent 硬件控制台桥接项目。它将 Agent 的状态、用量、任务宠物和经过明确配置的操作映射到妙联宝设备，并提供浏览器中的本地配置界面。当前版本 0.2.0 支持 macOS + MiraBox N4 Pro + Codex；其他操作系统、硬件型号与 Agent 平台暂不作兼容性承诺。

前往介绍页面

当多个 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 宠物章节。

完整安装、硬件接管与排障说明请阅读使用指南。下面是以 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 策略处理。

常驻 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 许可证。