用途
PopeBot Operations 技能用于管理、配置和排查 PopeBot（thepopebot）自主 AI 智能体部署。PopeBot 是一套自主 AI 智能体系统，部署在本地路径 d:\dev_aiwinsor\popebot_agent\，主要通过 GitHub Actions 实现完全自主运行。其代码仓库为 winsorllc/upgraded-carnival（公开仓库，目的是获得无限的免费 Actions 分钟数）。
架构
系统运行流程为：调度（CRONS.json）→ GitHub Actions（job/** 分支）→ 拉取 Docker 镜像 → 执行作业 → 打开 PR。
- GitHub Actions Runner：运行 stephengpope/thepopebot:job-1.2.71 容器。
- 本地事件处理器：一个本地 Docker 容器（thepopebot-event-handler），可用于运行 gh CLI 命令与仓库和作业交互。注意：其 Next.js 网页聊天部分在启动时会崩溃。
活跃智能体
系统运行 3 个不同的智能体，通过 CRONS.json 直接映射到 Ollama Cloud 模型：
- Kate：模型 kimi-k2.5，提供商 custom，角色为 The Architect（最擅长去重和全面文档）。
- Mimi：模型 minimax-m2.5，提供商 custom，角色为 The Heavy Engineer（最佳写作者，生产级）。
- Jackie：模型 glm-5，提供商 custom，角色为 The System Scripter（高产量，操作系统级工具）。
注：Gwen（qwen3.5:397b）因持续返回空响应而被搁置，重新启用前需要重新测试。
关键文件
- d:\dev_aiwinsor\popebot_agent\claude_mem\POPEBOT_IMPLEMENTATION_PLAN.md：主运维手册与交接文档。
- d:\dev_aiwinsor\popebot_agent\config\CRONS.json：智能体调度、作业描述和开关。
- d:\dev_aiwinsor\popebot_agent\config\AGENT.md：智能体身份映射。
- d:\dev_aiwinsor\popebot_agent.pi\skills\：智能体构建的 100 多个技能。
- d:\dev_aiwinsor\popebot_agent.github\workflows\run-job.yml：主 GitHub Actions 工作流。
LLM 配置（Ollama Cloud）
GitHub Secrets/Variables 目标配置：
LLM_PROVIDER=custom OPENAI_BASE_URL=https://ollama.com/v1
LLM_MODEL 在 CRONS.json 中按作业动态设置
AGENT_CUSTOM_API_KEY 存储在 GitHub Secrets 中
本地测试安全与清单：不要在本地测试脚本（.mjs、.cjs）中硬编码 CUSTOM_API_KEY，而应使用环境变量：
$env:OLLAMA_API_KEY = "<your-api-key>"
4 模型基准测试
node test_all_models.mjs
头对头评估
node test_kate_vs_jackie.mjs
通过 Docker 进行 GitHub 操作
由于本地事件处理器容器的 Next.js Web 应用当前会崩溃，应仅将其用作运行 gh CLI 命令的干净环境。始终使用持续运行的容器（docker exec）以保持状态一致性。
启动容器：
docker start thepopebot-event-handler
检查智能体运行状态：
docker exec -e GH_TOKEN=<token> thepopebot-event-handler gh run list -R winsorllc/upgraded-carnival -L 10
查看智能体日志：
docker exec -e GH_TOKEN=<token> thepopebot-event-handler gh run view <run-id> --log -R winsorllc/upgraded-carnival
合并 PR：
选项 1：通过 GitHub API
docker exec -e GH_TOKEN=<token> thepopebot-event-handler gh pr merge <pr-number> -R winsorllc/upgraded-carnival --merge
选项 2：本地操作（更适合解决冲突和防止合并降级）
cd d:\dev_aiwinsor\popebot_agent git fetch origin pull/<pr-number>/head:pr<number> git checkout main
警告：合并前务必审查 diff。不要盲目使用 "-X theirs"，因为它可能覆盖更优的技能。
git diff main...pr<number>
手动审查后：
git merge pr<number> -m "Merge PR <number>" git push origin main
密钥轮换流程
在令牌泄露的情况下（尤其是因为仓库是公开的），立即执行以下轮换：
- 轮换 GitHub PAT
访问 https://github.com/settings/tokens → 生成新令牌（classic）。 权限范围：repo、workflow、write:packages。 在 GitHub Secrets 中更新：仓库 → Settings → Secrets → GH_TOKEN。 更新本地 git remote：git remote set-url origin https://<new-pat>@github.com/winsorllc/upgraded-carnival.git。 如果 Docker 事件处理器正在运行，更新它（通过设置 GH_TOKEN 环境变量）。
- 轮换 Ollama Cloud API 密钥
访问 Ollama Cloud 仪表板 → API Keys → 重新生成。 在 GitHub Secrets 中更新：AGENT_CUSTOM_API_KEY。 更新本地环境变量：$env:OLLAMA_API_KEY = "<new-key>"。
灾难恢复
如果技能因错误合并而意外降级或丢失，可使用以下恢复命令：
恢复降级的技能：
找到具有更好版本的提交
git log --all --oneline -- ".pi/skills/<skill-name>/SKILL.md"
从特定提交恢复
git show <commit-hash>:.pi/skills/<skill-name>/SKILL.md > .pi/skills/<skill-name>/SKILL.md git add .pi/skills/<skill-name>/SKILL.md git commit -m "Restore best <skill-name> skill"
从已关闭的 PR 恢复技能：
git fetch origin pull/<pr-number>/head:recovery-<pr-number> git checkout recovery-<pr-number> -- .pi/skills/<skill-name>/ git add . git commit -m "Recover <skill-name> from PR #<number>"
修复“路径过长”符号链接：
如果运行失败并提示 File name too long，说明某个智能体将技能提交为路径字符串符号链接。使用以下 PowerShell 逻辑修复：
从 git 获取原始字符串内容（即文档文本）
$content = git show HEAD:.pi/skills/<skill-name>
移除损坏的链接
git rm -f .pi/skills/<skill-name>
重建为目录
New-Item -ItemType Directory -Force -Path .pi/skills/<skill-name>
将内容恢复到 SKILL.md
Set-Content -Path .pi/skills/<skill-name>/SKILL.md -Value $content -Encoding UTF8 git add .pi/skills/<skill-name>/SKILL.md
已知问题与注意事项
- 合并降级：合并多个智能体的 PR 时，盲目接受传入更改可能导致较差的技能版本覆盖较早 PR 中更优、更大的版本。务必验证文件差异（使用本地合并选项）。
- 事件处理器崩溃：thepopebot-event-handler 的 Next.js 进程在本地 Docker 容器内崩溃。应依赖 GitHub Actions 执行作业，并使用 docker exec 运行原始 gh CLI 进行管理。
- PAT / 密钥泄露：仓库是公开的。切勿将 API 密钥、.env 文件或 GitHub PAT 提交到代码库。
适用场景与限制
该技能适用于运维 PopeBot 自主智能体系统的开发者，涵盖 LLM 提供商配置、Docker 操作、GitHub Actions 作业派发、密钥轮换和灾难恢复等场景。限制包括：本地事件处理器的 Web 聊天功能不可用；部分模型（如 Gwen）因返回空响应被搁置；仓库公开带来的密钥泄露风险需要严格管理。