QRelay

Less context. Better coordination.

QRelay 是面向独立 Qoder Threads 的本地交接协议与邮箱。它让一个角色把最小且足够的上下文增量交给另一个角色，并保留明确的所有权、验收条件和验证证据。

Delta, not dump. 只传当前事实、已定决策、产物、未决项、验证结果和一个明确的下一步，不搬运整段对话。

作品入口

• 核心插件源码： https://github.com/Efan404/qrelay
• 中文互动 Demo： https://efan404.github.io/qrelay/index.html
• QHOP 协议： skills/qrelay/references/QHOP.md

比赛提交可直接使用核心插件仓库链接；互动 Demo 用于展示 Planner → Backend → Frontend、Semantic ACK 与 Handoff Quality Score 的完整产品故事。

QRelay 与 QHOP 的区别

• QRelay 是 Qoder 插件与本地 CLI 工作流，负责角色注册、邮箱投递、状态迁移、Hook 上下文和状态查询。
• QHOP 0.1 是 QRelay 传递的交接契约：八个语义字段，加上 ID、发送者、接收者、优先级、时间戳和生命周期状态。

QRelay 协调已经存在的 Threads；它不创建 Agent、不调度任务，也不是通用项目管理器。

工作方式

Planner  -- compact QHOP handoff -->  Backend  -- verified delta -->  Frontend
   |                                      |                            |
   +-- objective and decisions            +-- Semantic ACK             +-- acceptance checks
   +-- artifacts and open loops           +-- implementation           +-- final integration
   +-- exact verification                 +-- completion evidence       +-- status

典型流程是 Planner → Backend → Frontend：Planner 交付目标和已定决策；Backend 接收后明确执行边界并留下验证证据；Frontend 只接收与集成有关的新增事实。它是一条易懂的演示路径，不是固定流水线，任意已注册的小写角色都可以互相交接。

接收者在接受工作时必须给出 Semantic ACK（语义确认），记录：它理解的目标、会做什么、不会做什么，以及当前阻塞。ACK 证明接收者理解了范围，而不只是看见了文件。

不再手动粘贴上下文

QRelay 的 MVP 已经是 zero-copy handoff：发送者执行 /qrelay:handoff 后，QHOP 会直接进入接收角色的项目邮箱；接收 Thread 下一次提交任意 prompt 时，UserPromptSubmit Hook 会自动把未读 handoff 注入 Agent Context。用户不需要打开文件，也不需要把 A 的对话复制到 B。

当前公开的 Qoder 能力提供 session_id、resume、fork，以及 Agent SDK 对同一个仍由 SDK 持有的会话流追加异步消息；但截至本项目验证时，没有公开的 send(target_session_id, message) 原语可以向任意已打开的独立 Qoder Thread 安全推送消息。因此 QRelay 把传输分为两层：

Reliable delivery (MVP)
Agent A -> atomic QHOP mailbox -> UserPromptSubmit Hook -> Agent B context

Active wake-up (future adapter)
Agent A -> mailbox first -> idle-session resume/SDK bridge -> Agent B

邮箱永远是 source of truth。未来的主动唤醒只发送 handoff ID 和读取指令，不重新传完整上下文；目标 session 忙碌或唤醒失败时，消息仍会在下一次 prompt 自动送达。

质量分

每个 handoff 都有确定性的 100 分结构完整度评分：

QHOP section	分值
objective	15
state	15
decisions	15
artifacts	15
open_loops	10
verification	15
next_action	10
done_when	5

质量分只衡量结构是否完整，不保证陈述为真。缺少接收者、objective 或 next_action 会拒绝创建；疑似密钥的内容无论得分多少都会被拒绝。

安装与校验

QRelay 只需要 Python 3 和 Qoder CLI，不需要 Python 第三方包、数据库、云服务或 MCP server。

git clone https://github.com/Efan404/qrelay.git
cd qrelay

qoderclicn plugins validate "$(pwd)"
qoderclicn plugins install --scope local "$(pwd)"
qoderclicn plugins list --json

开发时可以不安装，直接从 checkout 加载：

qoderclicn --plugin-dir "$(pwd)"

插件在 .qoder-plugin/plugin.json 中显式声明 Skill、Commands 与 Hook。安装插件或修改 Hook 配置后请重启 Qoder，因为 Hook 目前不支持热重载。

Qoder Commands

始终使用带插件命名空间的命令，避免与其他插件的命令混淆：

/qrelay:register planner
/qrelay:handoff backend Implement the authentication API
/qrelay:inbox
/qrelay:accept QH-0001
/qrelay:done QH-0001
/qrelay:status

双角色演示

在同一项目中打开两个 Qoder sessions：一个运行 /qrelay:register planner，另一个运行 /qrelay:register backend，然后依次执行 handoff、inbox、accept、done 与 status。两个 session 共享项目邮箱，但不共享完整对话历史。完整的可交互产品流程可在中文 Demo中直接体验。

隐私与本地文件

所有 relay 状态都留在当前项目的 .qoder/relay/：

.qoder/relay/
  registry.json
  counter.json
  events.jsonl
  handoffs/QH-0001.md
  state/QH-0001.json
  inbox/backend/QH-0001.json

QRelay 不会上传这些数据。它们是普通本地文件，项目所有者可以自行决定备份、删除或是否提交到 Git。不要在 handoff 中放入 credentials、tokens、private keys 或无关个人数据。

Hook 行为与验证边界

打包的 UserPromptSubmit Hook 会运行：

python3 "${QODER_PLUGIN_ROOT}/scripts/qrelay.py" --project "$PWD" hook-context

Hook timeout 为 5 秒，并用 || true 保证失败非阻断：即使 Python 缺失、CLI 尚未兼容或 Hook 内部报错，用户 prompt 仍会继续。hook-context 从 standard input 读取 Hook JSON，只能注入有长度上限的上下文，不能自动 claim 工作或开始实现。

下面这些校验可以确定性地在本地运行：

qoderclicn plugins validate "$(pwd)"
python3 scripts/qrelay.py --help

QODER_PLUGIN_ROOT 是 Qoder 插件 Hook 的约定，也被本机已安装的 Qoder 官方插件使用。当前 checkout 已在真实 qoderclicn 1.1.17 session 完成一次 live verification：先注册 Backend session，再从 Planner 写入 QH-0001；接收 prompt 没有包含 handoff ID、目标或文件读取指令，并明确禁止检查项目文件，Agent 仍从 Hook 注入的 context 准确返回 QH-0001 及其完整 objective。

这证明当前版本的 UserPromptSubmit 自动注入路径可运行；它不等同于证明所有 Qoder Desktop 版本、操作系统或失败分支均已覆盖。发布前仍建议补测：故意让 Hook command 失败一次，确认 || true 会让普通 prompt 继续执行。

Competition blurb

报名名称： QRelay — Delta Handoffs for Qoder

精简功能描述： QRelay 让独立 Qoder Threads 通过私有的项目本地邮箱协作。Planner 发送带质量分的 QHOP 上下文增量，专业角色用 Semantic ACK 明确理解与边界，每次状态迁移都保留可检查的 artifacts 和 verification；全过程不复制完整对话，也不引入云端编排器。

灵感来源与原创性

QRelay 从通用 session handoff 与 multi-agent coordination 思路中得到问题意识，例如冷启动完整性、明确决策、artifact 引用、staleness check 与可验证验收。这些来源只用于启发要解决的问题。QHOP schema、具体措辞、生命周期、质量分、Semantic ACK、本地邮箱布局、示例和本文档均为本项目原创，没有复制外部模板或原文。

License

MIT