调度器代理管理指南
在一个界面中管理按项目（CSN）注册的自动化运行器（gissue 调度器等后台代理）：在线/离线状态、运行状态与历史、以及实时日志。
📋 概览
调度器代理管理 显示当前所选项目（CSN）下注册的所有自动化代理 —— 例如 gissue 的每小时调度器、交互式 Claude Code 会话等。与将 giip 问题 可视化为猫咪的 /admin/catquest 不同，本界面是用于管理 运行自动化任务的代理本身 的运维仪表盘：查看每个代理是否存活、当前运行是否健康、以及在哪里查看其日志。
🎨 状态颜色
每个代理会显示两个相互独立的状态信号——请勿混淆。
身份状态（代理名称旁的小圆点）
表示代理进程本身是否可达（tSchedulerAgent.status），与单次运行无关。
| 颜色 | 状态 | 含义 |
|---|---|---|
| 🟢 绿色 | online | 代理可达且正在正常上报 |
| 🔴 红色 | error | 代理上报了错误状态 |
| ⚪ 灰色（slate-400） | offline | 当前代理不可达 |
| ⚪ 浅灰色（slate-300） | unknown | 尚未上报任何状态 |
运行状态（Status 列徽章）
反映最近一次调度器 运行（run） 的状态（currentStatus），以及 stale（僵滞）检测结果。
| 颜色 | 显示标签 | 条件 | 含义 |
|---|---|---|---|
| 🟢 绿色 | RUNNING | currentStatus = RUNNING 且未 stale | 正在正常执行 |
| 🔴 红色 | STALE | currentStatus = RUNNING 且 isStale = true | 标记为运行中，但心跳长时间无响应 —— 看起来像卡死/僵死运行 |
| 🟠 橙色 | STALE | currentStatus = STALE（显式值） | 后端将该次运行本身标记为 stale |
| ⚪ 灰色 | ENDED | currentStatus = ENDED | 已结束（正常完成或受控停止） |
| ⚪ 灰色 | （原始值） | 其他情况 / 尚无运行记录 | 未知 / 无数据 |
在下方的运行历史弹窗中，已完成的运行还可能以红色的 FAILED 显示——这是以错误结束的运行，与 ENDED（正常结束）或 stale/超时不同。
🔍 界面结构
1. 顶部标题栏
- 返回
/admin/catquest的箭头（←）。 - Refresh：重新加载当前 CSN 的代理列表。
2. Open Interactive Sessions
仅当至少存在一个活跃的 claude_interactive_session 代理时（即当前在某主机上注册为运行中的交互式 Claude Code 会话），才会单独显示此卡片。每一行显示会话名称、主机、最后通信时间，以及当该代理的 capabilities 中注册了会话 URL 时显示的 "Open session" 链接。
3. 代理列表（表格）
每个调度器代理占一行，包含：
- Name —— 身份状态圆点、代理名称、操作系统/代理类型/版本徽章、
lssn（关联服务器）、截断显示的 capabilities 摘要，以及最近记录的错误（如有）。 - Host ——
hostIdentifier。 - Windows Task —— 若适用，运行该代理的 Windows 任务计划程序任务名称。
- Project —— 项目名称。
- Active —— ON/OFF 徽章（
isActive）。 - Last Comm —— 最后一次心跳/通信时间戳。
- Status —— 上述运行状态徽章，以及（如有上报）当前阶段（phase）文本。
底部统计栏汇总列表中所有代理的 已处理（Processed）/ 已跳过（Skipped）/ 失败（Failed） 计数。
4. 运行历史（Run History）
表格下方的 "View History" 卡片再次列出所有代理；点击某行的 History 按钮会打开弹窗，显示该代理最近的运行记录——执行模式、状态（含 FAILED）、开始/结束时间、耗时、已处理/已跳过/失败计数、阶段、以及摘要。
5. 实时日志查看器（Live Log Viewer）
双栏实时追踪界面：
- 左侧（代理 → 日志流树）：代理按分组显示，展开后可看到已知的日志流列表（日志流以
streamKey标识，具有streamType和轮转代数）。代理会根据最近通信时间显示 online/offline。 - 右侧（日志流卡片）：选中某个日志流后，会显示其最近的日志行，并持续刷新以实现实时追踪。
💡 注意事项
- 本界面为 管理员专属，需要
AdminGuard（uLevel ≥ 70）权限。 - 代理列表、运行历史和日志目录均按会话当前的 CSN 范围获取——如需查看其他项目的代理，请在顶部导航中切换项目。
- 加载数据需要已认证的会话（AK 令牌）；若请求开始因认证错误而失败，请重新登录后点击 Refresh。
- 本页面与
/admin/catquest是彼此独立的工具——通过 CatQuest 界面的导航到达本页，并不意味着共享 CatQuest 的猫咪可视化数据或受众。
故障排查
| 现象 | 原因 | 解决方法 |
|---|---|---|
| 出现 "Authentication required" 错误 | 未找到 AK/会话令牌 | 重新登录后刷新页面。 |
| 代理列表为空 | 该 CSN 下没有注册的调度器代理，或所选项目不正确 | 确认顶部导航中已选择正确的项目（CSN）。 |
| 明明任务已空闲，某行却显示红色 STALE | 代理在运行过程中停止发送心跳（isStale = true）且未转为 ENDED —— 可能是进程崩溃或被强制终止 | 直接检查代理所在主机；一旦其重启并重新上报，徽章会自动更新。 |
| Live Log Viewer 显示 "No streams yet." | 该代理尚未注册任何日志流，或自上次目录刷新以来没有新输出 | 等待代理下一次运行，或确认代理进程确实在写入日志。 |
| Open Interactive Sessions 中缺少 "Open session" 链接 | 该代理注册的 capabilities 中未包含 sessionUrl | 没有可打开的内容——该交互式会话未注册可访问的 URL。 |
版本：1.0
最后更新：2026-08-29
源文件：giipv3/public/help/catquest-schedulers.zh-CN.md