Iris 是一个独立运行在 Windows 本机的 QQ C2C 私聊入口。它把可信 owner 的命令转为 HYPERION/SELENE 的最小本机操作，或直接启动官方 Codex CLI 在指定工作区推进项目。
QQ owner 私聊 -> Iris -> HYPERION / SELENE 本机接口
Iris -> Codex CLI -> 指定项目工作区
没有中转网关或公网控制面。Iris 不开放端口，不读取 HYPERION 的原始归档， 不会把 QQ 输入交给 PowerShell、cmd 或任意 shell。
- 写入日记和每日状态，查看或完成 HYPERION 任务。
- 查询人物、SELENE 时间线、AI 通道与 HYPERION 概览。
- 从 QQ 向 Codex 提交明确的项目指令，并在完成时收到最终文本结果。
- 选择后续指令要续接的 Codex CLI 会话。
Iris 只接受一个可信 C2C owner，群聊及陌生私聊全部忽略。
Iris 已支持接入本机 Hermes Agent。向 QQ 发送 hermes <指令>（或简写
hm <指令>）即可执行任务，完成结果会返回同一个私聊；发送
hermes status、hermes sessions、hermes use <序号> 或 hermes stop
可查看、切换和停止任务。Hermes 默认从系统 PATH 查找，也可以在 .env
中用 IRIS_HERMES_ENTRY 指定 hermes.exe 的完整路径。
在 PowerShell 中执行。首次安装 winget 包后请重新打开 PowerShell，再继续执行后续命令：
winget install Git.Git
winget install OpenJS.NodeJS.LTS
git clone https://github.com/bakahuiii/Iris.git
cd Iris
npm install
Copy-Item .env.example .env
npm start首次启动前仍需按下方说明填写 .env 中的 QQ Bot、owner、HYPERION 和 Codex 配置。
前置条件：
- Node.js
22.12或更高版本。 - QQ 开放平台 Bot，已开通 C2C 私聊消息能力。
- 正在运行的 HYPERION 本机服务，默认
http://127.0.0.1:8787。 - 已登录的官方 Codex CLI：在 PowerShell 运行
codex --version应有输出。
cd <IRIS_ROOT>
npm install
Copy-Item .env.example .env在本机 .env 填写自己的值：
QQBOT_APP_ID=你的AppID
QQBOT_APP_SECRET=你的AppSecret
QQBOT_OWNER_OPENID=你的OpenID
HYPERION_API=http://127.0.0.1:8787
# Iris 通过 Codex CLI 工作的唯一写入范围。
IRIS_CODEX_WORKSPACE=<项目根目录>
# 可选。指定后优先续接该 Codex CLI 会话；也可在 QQ 中选取。
IRIS_CODEX_SESSION_ID=
# 可选。仅当 Codex CLI 不在默认 npm 位置时填写 bin/codex.js 的绝对路径。
IRIS_CODEX_ENTRY=.env、.iris-state.json 和临时的 Codex 结果文件都被忽略，不能提交或发送给他人。
推荐填写 QQBOT_OWNER_OPENID。它是 QQ OpenID，不一定等于可见 QQ 号。
若留空，第一位向 Iris 发送 C2C 私聊的人会成为本机 owner，写入
.iris-state.json。之后其它 sender 一律被拒绝。只有在你能保证第一条私聊来自自己
时才使用此方式。
先启动 HYPERION，再运行：
cd <IRIS_ROOT>
npm start在 QQ 中发送 帮助、help 或 h。开发时可运行 npm run dev；同一台机器只能保留
一个 Iris 进程，避免重复接收 QQ 消息。
| 命令 | 作用 | 示例 |
|---|---|---|
帮助 / help / h |
显示命令 | h |
日记 / diary / d <内容> |
追加一条带当前时间的日记 | d 今天把导入整理完了 |
状态 / status / s <字段> |
保存当天状态快照 | `s 3 7.5 药:减 酒:少 |
任务 / task / t |
查看待完成任务 | task |
完成 / done / c <序号> |
完成任务 | done 1 |
人物 / people / p [名称] |
查看人物摘要 | p 张三 |
SELENE / se |
查看粗粒度 SELENE 摘要 | se |
通道 / channels / ai |
查看 AI 通道占用 | channels |
概览 / summary / o |
查看 HYPERION 概览 | summary |
codex / iris / cx <指令> |
让 Codex 推进工作区项目 | iris 读取日志并修复导入测试 |
codex status / sessions |
查看 Iris 任务和可续接会话 | codex sessions |
codex use <序号> |
切换续接会话 | codex use 2 |
codex stop |
终止 Iris 正在等待的 Codex 任务 | codex stop |
状态 的格式为：
状态 <心情1-5> [睡眠小时] [药:是/否/减/未知] [酒:无/少/多/未知] [做:主要事情] [| 一句话]
同一日重复发送 状态 会更新当天状态；日记 总是追加新记录。
发送 iris <指令> 时，Iris 使用没有 shell 的参数向量运行：
codex -C <IRIS_CODEX_WORKSPACE> -s workspace-write -a never exec ...
workspace-write 将模型的文件写入限制在你配置的项目工作区，never 的含义是：这条
owner 在 QQ 中明确发出的指令无需再等待终端确认。请把实际目标写清楚，例如：
iris 阅读最近日志，定位导入失败原因，修复并运行相关测试；不要提交或推送。
Iris 立即确认已提交，Codex 结束后再向同一 C2C 私聊发送最终可见文本。一次只运行一项 Iris 发起的 Codex 工作，以防多个任务同时修改同一项目。
codex sessions 读取本机 Codex CLI 的 session_index.jsonl，只显示会话编号、名称和
时间，不读取或发送任何聊天正文。codex use <序号> 会记住会话 id；后续指令使用
codex exec resume <id> 续接它。未显式选择会话时，Iris 创建新会话并在首次完成后记住它，
不会擅自把新指令投进历史对话。
这不是桌面 UI 自动化：Iris 不模拟点击、不抓取屏幕，也不插入到一个正打开的桌面标签页。 它直接调用 Codex CLI，以同一 Windows 用户的 Codex 登录态在指定项目目录完成工作。
Iris 可读取：
- HYPERION 的去敏任务、人物、SELENE、AI 调度摘要；
- Codex CLI 会话索引中的 id、名称和更新时间。
Iris 可写入：
- HYPERION 日记、当天状态、现有任务完成状态；
IRIS_CODEX_WORKSPACE内由你明确下达的 Codex 工作结果。
Iris 不会读取或传输：
- 原始聊天归档、完整 HYPERION 快照、人物证据、精确位置；
- QQ AppSecret、Codex 登录凭据、API Key、Codex 会话正文；
- 任何 shell 命令、PowerShell 脚本或未受控工作区路径。
不要把 HYPERION 的 8787 端口暴露到局域网或公网，也不要将 .env、.iris-state.json
或 Codex 配置目录上传到 Git。
在同一 Windows 用户的 PowerShell 执行：
codex --version
codex login确认 .env 中 IRIS_CODEX_WORKSPACE 指向实际存在的项目目录。若 CLI 是自定义位置，
填写 IRIS_CODEX_ENTRY，其值必须是 bin/codex.js 的绝对路径。
确认 Iris 进程仍在运行、消息为 C2C 私聊、QQ Bot 已开通 C2C 权限，并且 sender 是配置或 首次绑定的 owner。群聊不会触发任何操作。
发送 codex sessions 查看编号，再发送 codex use <序号>。若要完全重置本机选择，
关闭 Iris 后删除项目根目录中的 .iris-state.json；这只删除 owner/通知/会话选择，
不会删除 HYPERION 数据或 Codex 会话。
- 开发者指南：架构、命令路由、Codex 执行协议、状态文件、测试与扩展规则。
- English README 与 English developer guide。
- HYPERION 侧窄接口：QQ Bot 协议。
<IRIS_ROOT>
├─ src/
│ ├─ index.mjs # QQ 生命周期、owner 保护、异步结果回传
│ ├─ commands.mjs # 中英文/简写命令路由
│ ├─ codex.mjs # 官方 Codex CLI 直接桥接，无 shell
│ ├─ hyperion.mjs # HYPERION 回环 API 客户端
│ └─ state.mjs # 本机 owner、通知、会话选择
├─ tests/
├─ .env.example
└─ .iris-state.json # 本机私有状态，忽略