emollick/codex-stream-deck
GitHub: emollick/codex-stream-deck
一个非官方的 Stream Deck 插件，将物理控制台变为 Codex 任务的实时监控和操作仪表盘。
Stars: 1 | Forks: 0
# Stream Deck 的 Codex Control
` 任务
- 长按可运行受 schema 约束的状态检查，无需写入项目文件或进行工具网络访问
- 刷新、新建任务、打开代码、审查、中断、健康、设置和技能操作
- 可选的完成更新，通过仅限 loopback 的通知桥接器支持 Codex 桌面端、CLI 和 IDE
- 原子化本地缓存、限制 payload 大小、对日志中的密钥进行脱敏处理，以及防御性的审批拒绝机制
## 安装
### 从打包发布版安装
1. 从仓库的 Releases 页面下载 `com.codexstreamdeck.control.streamDeckPlugin`。
2. 双击该文件，并在 Stream Deck 中批准安装。
3. 如果新操作未能立即显示，请重启 Stream Deck。
4. 将 **Recent Codex Project** 按键拖入配置文件中，然后添加 **Refresh** 和 **Health**。
5. 选择任意一个 Codex Control 按键，打开其 Property Inspector，然后按下 **Test Codex**。
### 从源码安装
要求：Node.js 24+、Stream Deck 7.1+，以及带有 app-server 支持且已完成身份验证的 Codex CLI。
```
npm ci
npm run check
npm run pack
```
打开生成的 `com.codexstreamdeck.control.streamDeckPlugin` 文件进行安装。
用于开发：
```
npx streamdeck link com.codexstreamdeck.control.sdPlugin
npm run dev
```
请参阅[完整设置](docs/SETUP.md)，了解 Codex 身份验证、按键布局、被动更新、故障排除和卸载步骤。
## 推荐的 15 键布局
```
[Project 1] [Project 2] [Project 3] [Project 4] [Project 5]
[Project 6] [Project 7] [Project 8] [Refresh ] [Health ]
[New Task ] [Open Code] [Review ] [Interrupt] [Settings ]
```
除非您在 Property Inspector 中分配了插槽编号或固定了任务，否则项目按键会自动跟随物理位置。
## 标签含义
| 标签 | 含义 |
| --- | --- |
| `WORKING` / `RUNNING` | Codex 或插件报告有正在进行的活动。 |
| `INPUT` / `APPROVAL` | 该任务需要在 Codex 中予以关注。 |
| `REVIEW` | 工作已准备好进行审查。 |
| `DONE` | 经过验证的工作流报告显示目标已完成。 |
| `BLOCKED` / `FAILED` | 报告指出了阻碍或失败。 |
| `NO STATUS` | 该任务尚未生成结构化的状态报告。 |
| `HOLD TO CHECK` | 长按该项目按键约一秒钟以请求最新状态。 |
| `UPDATED 20M` | 最新接收到的结构化状态是在 20 分钟前。 |
快速轻触可打开任务。长按至少 650 毫秒会启动只读状态回合。该检查可以更新 Codex 的 task-goal 元数据，但不能编辑项目文件、使用工具进行网络访问或批准操作。
## 可选的被动更新
这些按键可以在其他 Codex 客户端完成常规工作后进行更新：
1. 选择一个 Codex Control 操作，然后在 Property Inspector 中点击 **Install notify bridge**。安装程序会备份 `~/.codex/config.toml`，并通过在不调用 shell 的情况下进行链式调用，保留现有的常规通知器。
2. 将 [AGENTS.stream-deck-status.md](com.codexstreamdeck.control.sdPlugin/instructions/AGENTS.stream-deck-status.md) 的内容添加到 `~/.codex/AGENTS.md` 中。
3. 重启已打开的 Codex 客户端，以便它们重新加载用户配置和全局指令。
该桥接器仅在随机的 `127.0.0.1` 端口上监听，需要存储在本地应用程序数据目录中的 256 位 bearer token，并在 Stream Deck 不可用时在本地缓冲有限的事件。
## 安全与隐私
- 该插件不需要 API key；它使用本地已完成身份验证的 Codex CLI。
- 不会向此仓库提交任何个人姓名、本地用户路径、凭据或任务历史记录。
- 插件会在本地存储近期的任务元数据和状态摘要。它不提供自己的云服务。
- 按下状态或任务操作可通过用户的常规 Codex 会话发送相关的 prompt/context。
- 状态回合为只读模式，禁用了工具网络访问，且审批策略为 `never`。
- 通知服务器仅限 loopback 访问，需进行 token 身份验证，有大小限制，并且会拒绝未知的事件类型。
- 所有进程启动均使用带有 `shell: false` 的参数数组。
请阅读[安全政策](SECURITY.md)和[安全审计](docs/SECURITY-AUDIT.md)，以了解威胁模型、发现的问题、残余风险和报告流程。
## 开发
```
npm run typecheck
npm test
npm run test:integration
npm run build
npm run validate
npm run security
```
集成测试会启动真实的本地 `codex app-server`，完成 JSON-RPC 初始化握手，并在不启动模型回合的情况下列出线程。
请参阅[架构](docs/ARCHITECTURE.md)、[开发与发布](docs/DEVELOPMENT.md)、[协议说明](docs/PROTOCOL-NOTES.md)以及原始的 [v1.1 规范](spec/stream-deck-codex-integration-spec-v1.1.md)。
## 官方参考
- [Codex App Server](https://learn.chatgpt.com/docs/app-server)
- [Codex 身份验证](https://learn.chatgpt.com/docs/authentication)
- [Codex `AGENTS.md` 指令](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [Stream Deck SDK 入门](https://docs.elgato.com/streamdeck/sdk/v1/introduction/getting-started/)
- [Stream Deck 插件打包](https://docs.elgato.com/streamdeck/cli/commands/pack/)
## 许可证
[MIT](LICENSE)
标签：Codex, Elgato Stream Deck, MITM代理, Python安全, SOC Prime, 开发工具, 效率工具, 网络调试, 自动化, 自动化攻击, 集成