Jyotisha/tools/agent-loop/README.md

双 agent 自动循环（agent loop）

Claude（开发机，Linux）负责规划与验收，Grok Build（产品负责人的 Windows 电脑）负责执行，两边靠 Gitea issue 标签交接。设计与红线见 docs/tasks/TASK-agent-loop-pilot-20261013.md，进度见 docs/tasks/PROGRESS-agent-loop-pilot-20261013.md。

本目录不在 deploy/gated-paths.txt 内：改这里不触发门禁、不部署。

状态流转

标签	谁处理	结束时
agent/待规划	Claude：诊断 → 任务书推 staging	agent/待执行 或 agent/需拍板
agent/待执行	Grok：按任务书在 codex/* 实现、自测、推分支	agent/待验收 或 agent/需拍板
agent/待验收	Claude：只验 Grok 回报的 SHA	通过 → 推 staging → agent/部署中；不通过 → 修复单 → agent/待执行（打回 2 次 → agent/需拍板）
agent/部署中	Claude 脚本（不用模型）：核对 /api/health	agent/待真机；3 小时未部署 → agent/需拍板
agent/待真机	产品负责人	关 issue，或评论问题并改回 agent/待规划
agent/需拍板	产品负责人	回复后改回原状态

锁标签：agent/规划中、agent/验收中（Claude）、agent/执行中（Grok）。试点期只处理同时带 agent/试点 的 issue。

安全设计

• 只认标签：只有有写权限的人能打标签。issue 正文与评论只读本人账号写的，其他人写的一律不交给模型。
• 两侧都不关权限检查：Claude 用 claude-settings.json 白名单 + dontAsk；Grok 用 grok-permissions.json 白名单 + dontAsk。白名单外的操作自动拒绝。
• 推送钩子（hooks/，只在循环进程内通过 GIT_CONFIG_* 生效，不写进共用的 .git/hooks）：Claude 不能推 main、不能删分支，每晚复盘只能推纯文档；Grok 只能推 codex/*、不能删分支。
• 脚本核对模型的每个声明：任务书真在 staging 上、回报的 SHA 真是远端分支 head、staging 真包含验收的 SHA；对不上就作废本轮并留言。
• 公开仓库：发评论前脚本扫一遍邮箱、JWT、私钥、password= 之类，命中就不发。
• 熔断：同一单连续 3 轮出错或被打回 2 次就停下 @产品负责人。

Claude 侧（这台 Linux 机器）：会话里跑 /loop

2026-10-13 产品负责人决定：Claude 侧照 yetone/magpie 的做法，在一个常开的 Claude Code 会话里跑 /loop，不用后台脚本。理由：每一步都在会话的权限检查之下，产品负责人随时能看、能插话；后台脚本被 Claude Code 安全检查判为「无人值守 agent」拦下。

循环里用 gitea.sh 改标签、发评论，规则与评论首行标记同下文。要粘贴的 /loop 提示词在 prompts/loop-claude.md。会话关掉或机器重启，循环就停，重开会话再粘贴一次即可。

备用：Claude 侧后台脚本（默认不用）

claude-tick.sh、nightly-review.sh、agentctl.sh 是同一流程的无人值守版本，未实跑。只有产品负责人明确要求不依赖会话时才启用。

需要：~/.config/jyotisha-agent/gitea-token（0600）、claude 已登录、jq、flock。

tools/agent-loop/agentctl.sh install   # 复制到 ~/.local/share/jyotisha-agent/bin
~/.local/share/jyotisha-agent/bin/agentctl.sh once     # 跑一轮看看
~/.local/share/jyotisha-agent/bin/agentctl.sh start    # 后台常驻：每 30 分钟一轮，23:30 每晚复盘
~/.local/share/jyotisha-agent/bin/agentctl.sh status
~/.local/share/jyotisha-agent/bin/agentctl.sh pause    # 暂停（STOP 文件）；resume 恢复；stop 停进程

本机没有 cron / systemd：机器重启后要再运行一次 start。日志在 ~/.local/state/jyotisha-agent/，每轮的上下文、模型输出、评论草稿在 runs/<时间>/。

Grok 侧（Windows）：会话里跑 /loop

Grok Build 同样支持 /loop，两侧对称：Windows 上开一个常开的 Grok 会话跑 /loop，提示词与开会话前的环境设置见 prompts/loop-grok.md。下面的计划任务方式降为备用（未实跑）。

备用：Grok 侧计划任务（默认不用）

需要：%USERPROFILE%\.config\jyotisha-agent\gitea-token、Grok 已登录、T1 建好的工作树 G:\Ferti\Jyotisha\.worktrees\agent-loop、Docker Desktop（跑 test:db 时）。路径不同就改 grok-config.json。

首次安装前，让 Grok 在交互模式里做两件事（见 PROGRESS「Grok 侧安装」）：核对 grok-permissions.json 的规则语法；把 13 条 Windows 已知失败的测试名填进 windows-known-failures.txt。

cd G:\Ferti\Jyotisha\.worktrees\agent-loop\tools\agent-loop
powershell -NoProfile -ExecutionPolicy Bypass -File install-grok.ps1 -RunOnce   # 先跑一轮
powershell -NoProfile -ExecutionPolicy Bypass -File install-grok.ps1            # 注册计划任务，每 15 分钟
powershell -NoProfile -ExecutionPolicy Bypass -File install-grok.ps1 -Uninstall # 移除

暂停：新建空文件 %USERPROFILE%\.config\jyotisha-agent\STOP。日志：%USERPROFILE%\.jyotisha-agent\state\grok-tick.log。

.ps1 文件只用 ASCII 字符（Windows PowerShell 5.1 按 ANSI 读无 BOM 的脚本），中文标签与留言都在 grok-strings.json。

交接评论的首行标记

<!-- agent:claude plan brief=<任务书> branch=<codex/...> base=<staging sha> -->
<!-- agent:grok report branch=<codex/...> sha=<head> -->
<!-- agent:claude review sha=<head> verdict=pass staging=<sha> checklist=<docs/testing/...|-> -->
<!-- agent:claude review sha=<head> verdict=fail brief=<修复单> branch=<codex/...> -->
<!-- agent:claude deployed sha=<部署 sha> -->
<!-- agent:claude|grok error ... -->  <!-- agent:claude|grok escalate -->