Handouts Agent 架构与全链路排障 (Handouts Agent Architecture and Full-Chain Troubleshooting)

2026-09-08 暂无评论

1. 架构总览 (Architecture Overview)

讲义制作 Agent (Handouts Agent) 是一套基于 MCP 协议与 Claude Code 受控子进程构建的自动化 LaTeX 讲义生成系统。其核心工作流如下：

[MCP Client]
      │  POST /mcp (handouts_create)
      ▼
[Handouts Agent Server (:3180)]
      │  启动 Claude Code 受控进程 (沙箱工作区)
      ▼
[Claude CLI Runner] ──(读写/编译)──> [CloudTeX CLI (:xelatex)]
      │
      │  调用 Anthropic Messages 协议
      ▼
[Local LLM Proxy (:3180/claude/v1/messages)]
      │
      ├─► [DeepSeek Native Anthropic (推荐)] ──► https://api.deepseek.com/anthropic/v1
      │
      └─► [NewAPI (:3000) -> CPA (:8317)] ──► Google Antigravity OAuth (受限)

2. 关键排障与技术踩坑 (Troubleshooting & Pitfalls)

坑点 1：Google Antigravity OAuth 在 Agent 场景下的 429 信用熔断

现象 (Symptom)：
通过 curl 发送极简单轮对话（如 {"role": "user", "content": "hi"}）时，NewAPI 与 CPA 均能返回 200 OK；但在 Handouts Agent 启动后，第一次调用工具即遭遇：

upstream execution failed: provider=antigravity model=claude-sonnet-4-6 err={ "error": { "code": 429, "message": "Resource has been exhausted (e.g. check quota).", "status": "RESOURCE_EXHAUSTED" } } [credits]
All credentials for model claude-sonnet-4-6 are cooling down

根因 (Root Cause)：
1. Claude Code CLI 初始化时，会向模型注入完整的工具声明集合（28 个工具 Schema，约 15k tokens），并默认指定 max_tokens: 32000。
2. Google Cloud Code 后端（daily-cloudcode-pa.googleapis.com）对 Antigravity 免费 OAuth 凭据中的非 Google 自研模型（如 Claude Sonnet）实行了极严苛的单次 Token / 每日信用额度限制。一旦单次请求的上下文与最大预留 Token 超过门槛，Google 直接返回 RESOURCE_EXHAUSTED [credits]。
3. CPA 检测到 429 后将该凭据置入 30s~60s 的 model_cooldown，导致后续重试全部被拒。
解决方案 (Resolution)：
对于拥有庞大 System Prompt 和大量 Tool Schema 的自主 Agent 系统，避免依赖免费逆向/OAuth 渠道，推荐在 data/providers.json 中配置原生支持 Anthropic Messages API 的商业模型通道（如 DeepSeek）：
```
{
  "activeProviderId": "deepseek",
  "providers": {
    "deepseek": {
      "type": "anthropic",
      "baseUrl": "https://api.deepseek.com/anthropic/v1",
      "apiKey": "sk-***",
      "model": "deepseek-chat"
    }
  }
}
```
该通道具备完整的 Anthropic Messages 协议兼容性，无 OpenAI 函数转换损失，单次上下文容量大且无突发信用熔断风险。

坑点 2：编译链缺少 `cloudtex` 可执行二进制

现象 (Symptom)：
Agent 在生成 main.tex 后尝试执行编译，控制台显示：
```
cannot access '/home/ubuntu/workspace/ops/handouts-skill/tools/cloudtex/bin/cloudtex-linux-amd64': No such file or directory
```
导致 Agent 不断进行全局文件搜索并陷入重试。
根因 (Root Cause)：
handouts-skill/tools/ 目录下未安装 cloudtex 独立二进制包。

解决方案 (Resolution)：
从插件 bundle 中拷贝编译工具并赋予执行权限：

cp -r /home/ubuntu/workspace/ops/astrbot/data/plugins/astrbot_plugin_claude_fleet/bundled_server/examples/handout/skill/tools/cloudtex /home/ubuntu/workspace/ops/handouts-skill/tools/
chmod +x /home/ubuntu/workspace/ops/handouts-skill/tools/cloudtex/bin/cloudtex-linux-amd64

坑点 3：MCP 协议调用头约束 (`406 Not Acceptable`)

现象 (Symptom)：
直接 POST 调用 /mcp 端点返回：

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null}

解决方案 (Resolution)：
MCP Streamable HTTP 协议要求客户端请求头必须显式包含双重 MIME 类型：

POST /mcp HTTP/1.1
Authorization: Bearer <MCP_KEY>
Content-Type: application/json
Accept: application/json, text/event-stream

3. 单页精美讲义生成验证实录 (Verification Record)

测试主题：《快速傅里叶变换 (FFT) 简介》

任务 ID：1bdcdb58-61e9-4f69-ac0a-3a15180257cf
执行过程：
1. 自主探索与模板加载：读取 readex-vivid.cls 及排版规范。
2. 初次排版编译：基于 XeLaTeX 编译生成初版 PDF，检测到内容溢出至第 2 页（Pages: 2）。
3. 视觉闭环度量 (Visual QA Loop)：
  - 调用 pdftoppm -png 渲染第 1 页与第 2 页。
  - Agent 通过工具读取图片度量溢出高度，定位原因为蝴蝶图与算法对比表格占用纵向空间过大。
4. 动态微调排版：压缩 titlespacing、收紧表格内边距、调整蝴蝶图尺寸。
5. 终版重编译：成功压缩至单页 A4（Pages: 1），文件大小 114,505 bytes。
交付文件：
- 远端路径：/home/ubuntu/workspace/ops/handouts-skill/tasks/1bdcdb58-61e9-4f69-ac0a-3a15180257cf/output/output.pdf
- 本地镜像：C:\Users\18086\Downloads\FFT_Handout.pdf