| name | agent-toolbox |
| description | 用于 agent-toolbox（Android MCP 工具箱）项目的开发与调试。当用户要修改 McpServer / TaskManager / DeepSeekChatBridge / DeepSeekActivity / JavaScriptBridge 等 Java 后端，或 assets/test_client.html 前端（Markdown 渲染、KaTeX 数学公式、代码块复制），或涉及 JSON-RPC 计划/任务执行（plan、task、execute_task、tryExtractPlan、plan_update）、WebView 抓取 DeepSeek 回复、或用 git 推送该项目时触发本 skill。关键词：agent-toolbox、MCP 工具箱、DeepSeek、WebView、计划待办、execute_task、renderMarkdown、KaTeX。 |
| when_to_use | 修改 McpServer/TaskManager/DeepSeekChatBridge 等 Java 后端、前端 renderMarkdown、JSON-RPC 计划执行、或用 git 推送该项目时 |
agent-toolbox 开发技能
Overview
agent-toolbox 是一个用 WebView 包裹 DeepSeek 网页对话、作为 MCP 智能体工具箱的 Android 应用。它自带一个前端页面 assets/test_client.html（标题「MCP 工具箱」），由 McpServer 的内嵌 HTTP 服务器以 localhost 提供（安全上下文，navigator.clipboard 可用），用于展示智能体回复与工具结果，并支持 Markdown / 数学公式 / 代码块复制。
后端为 Java（src/main/java/com/example/agenttoolbox/）。本 skill 固化了该项目反复踩过的坑与协议约定，避免每次重新推理。
Project Map
src/main/java/com/example/agenttoolbox/
├── mcp/
│ ├── McpServer.java # 内嵌 HTTP/SSE 服务、JSON-RPC 处理、计划提取与执行、buildPlanMessage
│ ├── TaskManager.java # 计划加载/确认/选取/推进；loadPlan 归一化空字段
│ └── Task.java # 任务数据模型 + fromJson/toJson
├── DeepSeekChatBridge.java # 抓取 DeepSeek 页面回复（extractReply 取 p.ds-markdown-paragraph / pre）
├── DeepSeekActivity.java # WebView 宿主；onPageFinished 注入 observer 脚本
└── JavaScriptBridge.java # JS 桥（observer 注入）
assets/test_client.html # 真正的前端：marked + sanitizeHtml + KaTeX
Critical Conventions（务必遵守）
1. 计划/任务协议（JSON-RPC）— tryExtractPlan 判定
- LLM 回复：
{"jsonrpc":"2.0","result":{"type":"reply","content":"<文本或计划>"},"id":N}。
- 计划常以前言 + 换行 +
{"tasks":[...]} 形式出现在 result.content 中，不一定是纯 JSON。
- 提取计划必须用「平衡括号提取 + 占比阈值(≥1/3)」：在文本里找到完整
{"tasks":[...]} JSON 且它占 content 大部分才认作计划。
- ❌ 错误：用
content.indexOf('{') 直接 new JSONObject(sub) —— org.json 会忽略 } 后多余字符，会把讲解文字里举例的 {"tasks":[...]} 误当真计划（id:1007 误触发、id:1003 真实计划反被拒的教训）。
- ✅ 正确：遍历顶层
{，用 matchingBrace 取匹配 }，要求 candidate.length()*3 >= s.length()。
- 任务字段：
task_id、content、priority(1-5)、deps[]、tool_needs[]、checkpoint。
- 流程：
tryExtractPlan → loadPlan（空 task_id 自动补 T001…、空 content 回退填充）→ selectNextTask（置 IN_PROGRESS）→ buildPlanMessage("execute_task", task, planState, …) 发结构化系统消息，指令 LLM 调工具后用 plan_update 推进。
- LLM 推进：回复里带
plan_update（action: complete_task/mark_done/mark_failed/update_plan + task_id）。
2. 前端 renderMarkdown（test_client.html）
- 必须在
marked.parse 前用占位符保护：①围栏+行内代码块；②块级数学 $$…$$ / \[…\]。解析后还原代码为 HTML、还原数学为单行 $$ … $$（换行合并为空格，保留 \\）。
- 原因：KaTeX
$$ 定界符不跨多行；marked 会把 LaTeX 的 \\ 当转义吞掉。
- 复制按钮与数学公式渲染都在应用自己的前端 HTML 里做，绝不能注入到
chat.deepseek.com 页面（曾误注入 MathJax/复制按钮，已回退）。
- KaTeX 经 CDN
<script defer> 引入；MutationObserver 监听 chatMessages → enhanceContent → renderMathInContainer(KaTeX auto-render) + addCodeCopyButtons。
sanitizeHtml 用 DOMParser + 白名单（P/BR/STRONG/B/EM/I/U/CODE/PRE/H1-6/UL/OL/LI/BLOCKQUOTE/A/TABLE…），不含 BUTTON 也不含 KaTeX 输出 span → 数学与复制按钮必须在 sanitize 之后对真实 DOM 后处理。
3. 推送与构建约束
- ⚠️ 本沙箱无法编译 Android（无 SDK；gradle 指向 AIDE 的 JDK 路径）。改动用 node 复现核心逻辑验证（如
tryExtractPlan 平衡括号+占比、loadPlan 归一化），不要依赖 gradle build。
- 推送模式：把 remote 设为
https://<USER>:<TOKEN>@github.com/<USER>/agent-toolbox.git → git push origin main → 立刻把 remote 重置为公开 https://github.com/<USER>/agent-toolbox.git。不要长期保留带 token 的 remote。
- 不要把真实 token 写进会被提交的文件（含本 skill）。
References
references/conventions.md — 协议、前端、推送的完整细节与踩坑记录。
