cq的5大MCP工具全解析:query/propose/confirm/flag/status 让AI越用越聪明
cq的5大MCP工具全解析:query/propose/confirm/flag/status 让AI越用越聪明
cq 是一个面向 AI Agent 的共享学习开源标准:让智能体把踩过的坑、发现的坑点沉淀下来,持久化保存并共享给其他 Agent,从而停止重复犯同一个错误。它通过 5 个 MCP 工具——query、propose、confirm、flag、status——接入 Claude、Cursor、Codex 等 AI 编程助手,让 AI 越用越聪明。本文带你快速看懂这 5 大 cq MCP 工具各自的作用、调用时机和背后的置信度机制。
cq 是什么:为什么 AI 需要"集体记忆"
想象一下:你的 AI 助手刚花 1 小时排查了 webpack 5 移除 Node.js polyfills 导致构建失败的问题,但下次换个项目、换个 Agent,它又从零开始踩一遍同样的坑。🕳️
cq 解决的就是这个问题。它在工作流中形成闭环:
动手前查询 → 用对知识就加分 → 发现新知识就提交 → 发现错误知识就标记
5 个 MCP 工具就挂在这个闭环上。工具定义统一注册在 MCP 服务器中,源码见 cli/mcpserver/server.go;完整知识流转架构可查看 docs/architecture.md。
5大MCP工具速览表
| 工具 | 调用时机 | 一句话作用 |
|---|---|---|
query |
动手之前 | 检索已知的坑点、规避方案、版本特性 |
propose |
发现新知之后 | 提交一条新的知识单元(Knowledge Unit) |
confirm |
验证正确之后 | 为被证实有效的知识加分,提升置信度 |
flag |
发现错误时 | 标记知识过时、错误或重复,降低其置信度 |
status |
按需查看 | 展示知识库的层级数量、领域覆盖与置信度分布 |
这套"什么时候该调哪个工具"的行为规范,由 Agent 端加载的技能文件 plugins/cq/skills/cq/SKILL.md 指导执行。
工具一:query —— 动手前先查知识
query 是整个工作流的第一站。当 Agent 开始不熟悉的任务、遇到报错、或要配置 CI/CD 时,它会被要求先查询再重试。
核心参数:
domains(必填):主题标签,如"api"、"payments"、"connection-pooling",建议 2~3 个languages/frameworks:编程语言与框架,如"python"、"webpack"pattern:跨技术的通用关注点,如"shell-quoting"limit:返回条数上限,默认 5,最大 50
返回内容: 带置信度分数和推荐操作(action 字段)的知识单元列表。检索结果按 相关度 × 置信度 排序,排序逻辑实现在 sdk/go/scoring.go 的 RankCandidates 中。
💡 小技巧:查询门槛刻意设得很低——只要任务涉及版本差异、工具配置或跨系统集成,都值得查一次,因为查询成本很低,而漏掉已知坑点的代价很高。
工具定义与参数校验源码:cli/mcpserver/query.go。
工具二:propose —— 发现新坑立刻分享
propose 是知识的增长入口。当 Agent 解决了一个不明显报错、发现了未文档化的 API 行为、或找到了非显而易见的规避方案时,应立即(而不是攒到任务结束)提交一条知识单元。
必填三要素:
| 字段 | 说明 |
|---|---|
summary |
一句话描述发现(上限 500 字符) |
detail |
完整解释,含验证时间与依据(上限 8000 字符) |
action |
以祈使动词开头的具体操作建议(上限 2000 字符) |
另外还可附 domains、languages、frameworks、pattern 标签和 extensions 扩展字段。
质量要求: 必须剥离项目特定细节,保证知识可泛化。比如应写"GitHub GraphQL API 即使出错也返回 HTTP 200,需检查响应体的 errors 字段",而不是"我们 staging 环境的支付服务会返回 500"。新提交的知识单元初始置信度为 0.5。
源码实现:cli/mcpserver/propose.go。
工具三:confirm —— 为正确知识投票加分
当 Agent 使用了某条知识且它确实解决了问题(或独立验证了描述的行为依然存在),就调用 confirm,只需传入 unit_id(由 query 返回)。
效果:置信度 +0.1。置信度本质是一个社交信号——代表有多少个 Agent 验证过这条知识,而非新鲜度保证,所以高置信度也要结合当前版本再核实。
源码实现:cli/mcpserver/confirm.go。
工具四:flag —— 标记错误或过时的知识
flag 是知识库的"纠错机制"。当查到的知识被证明是错的、描述的行为已不存在、或与另一条知识重复时,应主动标记,而不是默默忽略——这能保护其他 Agent 不被误导。
reason 参数三选一:
stale:描述的行为已不存在(如新版本已修复)incorrect:指引本身是错的duplicate:与另一条知识重复,需附duplicate_of指明原单元 ID
效果:置信度 −0.15(惩罚力度比加分大,宁严勿松)。可选 detail 参数解释具体变化。
源码实现:cli/mcpserver/flag.go。
工具五:status —— 按需查看知识库统计
status 不参与日常 query/propose/confirm/flag 循环,而是按需使用的"仪表盘",无参数,直接返回:
- Tier Counts:本地(local)/ 私有(private)/ 公共(public)各层级的知识数量
- Domains:各领域标签的覆盖情况
- Confidence Distribution:置信度分布直方图(不含公共池)
- Recent Additions:最近添加的知识单元
适合在接入后验证是否生效、或想看看"知识库里都有什么"时使用。新手可以直接运行 /cq:status,首次运行时的典型输出见快速上手文档 docs/quickstart.md。
源码实现:cli/mcpserver/status.go。
置信度机制:confirm 和 flag 背后的数学
cq 的"聪明"靠一套简单的信任积分制驱动,常量定义在 schema/values.go 与 schema/scoring.values.json:
| 事件 | 置信度变化 | 结果 |
|---|---|---|
| 新提交(propose) | 初始值 | 0.5 |
| 一次 confirm | +0.1 | 越多人验证越可信 |
| 一次 flag | −0.15 | 被纠错快速贬值 |
解读经验(来自 SKILL.md):
- > 0.7:多个 Agent 已验证,仍是"先核实再用"
- 0.5–0.7:验证较少,当作强提示
- < 0.5:可能已过时或有争议,注意查看是否被 flag
快速上手:三步接入 cq MCP
第 1 步:安装 cq CLI(支持 Homebrew、Scoop、go install 等,详见 cli/README.md):
brew install --cask mozilla-ai/tap/cq
第 2 步:把插件安装到你的 AI 助手,一条命令即可,支持 Claude、Codex、Copilot、Cursor、Devin Desktop、OpenCode、Pi 等:
cq install --target claude
第 3 步:启动 MCP 服务器。安装器已自动写入 MCP server 条目(指向 cq mcp,通过 stdio 通信,服务器启动逻辑见 cli/cmd/mcp.go)。之后在 AI 助手中运行 /cq:status 验证,再用自然语言让它提交第一条知识单元即可。
更多接入细节(各宿主配置文件位置、连接远程服务器)参见安装指南 docs/install.md。
总结与源码索引
| 内容 | 文件位置 |
|---|---|
| 5 个工具注册入口 | cli/mcpserver/server.go |
| query 工具 | cli/mcpserver/query.go |
| propose 工具 | cli/mcpserver/propose.go |
| confirm 工具 | cli/mcpserver/confirm.go |
| flag 工具 | cli/mcpserver/flag.go |
| status 工具 | cli/mcpserver/status.go |
| Agent 端行为协议 | plugins/cq/skills/cq/SKILL.md |
| 架构与知识流转 | docs/architecture.md |
| 新手快速上手 | docs/quickstart.md |
掌握这 5 个工具后,你的 AI 助手就不再是"一次性记忆"的个体,而是接入了一张持续进化的集体知识网络:查得越多,避坑越快;贡献越多,整个团队的所有 Agent 都受益。🚀