工作原理

整体流程

1. 1
   群里提交反馈

   项目群成员 @机器人或用反馈命令提交问题，平台登记成单并排队。

2. 2
   平台唤醒你的电脑

   本机调度程序与平台保持长连接，只看「哪些项目有活」，不领单、不改任何状态。

3. 3
   按项目拉起会话

   在该项目登记的仓库与分支里，用你设置的 AI 工具启动一次会话；分支不对就不启动并上报原因。

4. 4
   会话处理并回复

   会话用本项目的令牌领单、分析、回复或修复提交；敏感内容自动转人工审批。

5. 5
   审批上线

   修复需要上线时申请审批，项目负责人批准后会话被再次唤醒完成部署并登记更新日志。

三个角色的分工

会话的生命周期

• 按需启动：只有有活时才启动，处理到「已回复 / 已申请上线 / 转人工 / 等补充」后结束。
• 固定命名、接着上下文：每个项目固定一个会话，名称统一为「【值守】项目名」；下次被唤醒时续用这个会话，超过 24 小时或用满 20 次后自动换新，并带上上一次的处理摘要。
• 互斥与并发：同一项目同一时间只运行一个会话；整台电脑同时运行的会话数有上限（默认 3 个），超出排队。
• 超时保护：单次会话超过时限（默认 45 分钟）会被结束并上报，项目负责人会收到提醒。
• 不等审批：申请上线后会话直接结束；批准后平台会再次唤醒它来部署。

单子交给哪个会话

• 一个项目只有一个处理端：处理端绑定在执行 yqpj-agent attach 的那台电脑、那个仓库与分支上。平台按项目找到唯一的处理端，只唤醒那台电脑，不会随机分配。
• 会话由调度程序自己启动：调度程序在该仓库里启动一个后台会话，会话编号记在本机（~/.yqpj-agent/watch-dispatch/）。下次续用的就是这个会话（续用只有 Claude Code 支持，其它工具每次新开），不会接管你自己打开的 AI 窗口，你在同一仓库里开几个窗口都不影响。
• 同一项目同时只有一个会话在处理：本机锁保证同一项目不会并行拉起第二个会话；平台的领单租约保证同一张单只会被一个会话领走，即使你同时还开着常驻值守会话，也不会重复处理。
• 一个项目一台处理电脑：优先用项目处理端设置里单独指定的「处理电脑」；没指定就用你在「我的 → 接入本机值守」设的默认处理电脑；都没设则你任一在线电脑都可处理。改成另一台后，原来的电脑不再被唤醒。
• 换电脑处理：在新电脑的项目仓库里重新执行 yqpj-agent attach，或直接在 H5 把处理电脑改成新电脑。

代码仓库自动导入

在 H5 项目详情「处理端 → 代码仓库」登记仓库地址和分支后，处理电脑上没有这个项目也能处理：调度程序先在本机找同一仓库的目录（当前分支对得上就直接用，否则用已检出该分支的 worktree，再不行就新建一个 worktree，不动你的主目录）；本机没有该仓库就自动克隆，然后自动绑定。没登记仓库或克隆失败时会私聊负责人一次，不反复重试。

与开发共用目录时的分支规则

• 值守会话直接在项目目录里运行，和你的开发共用同一份代码；
• 目录当前在别的分支：不启动，上报原因；
• 目录临时处于游离 HEAD（比如正在 rebase）：2 分钟后自动重试，不算失败；
• 值守只提交自己改的文件，不会带上你未提交的改动。

怎么看处理过程

• H5 单子详情：「处理过程」时间线显示会话每一步的摘要（读了哪个文件、执行了什么、说了什么），处理中每 5 秒自动刷新；只推摘要，不含命令原始输出。
• 处理电脑本机：yqpj-agent watch-tail <项目> 实时跟随完整过程；会话结束后用 yqpj-agent watch-open <项目> 打开该会话接着聊或人工接管。

三种运行方式

常驻值守、后台调度（推荐）、中转唤醒，在 H5 项目处理端设置的「运行方式」里切换。区别、前提与切换步骤见 运行方式。

唤醒的原因

• 有可领取的新单，或之前领了没处理完、租约已过期的单；
• 有已批准、待部署的上线；
• 等待补充信息的单收到了反馈人的回复；
• 送审的回复被驳回并附了改写说明。