mcpField
C
camunda-docs

camunda-docs

github.com/camunda开发26132 次安装1 天前更新
代码仓库

关于 camunda-docs

camunda-docs 是面向 Camunda 实施工作的文档查询技能，结合 MCP 服务语义检索、按版本筛选的 Algolia 搜索及静态文本备用方案，并将实施任务引导至专用技能。

主要功能

  1. 01语义检索 Camunda 文档
  2. 02按版本筛选 Algolia DocSearch
  3. 03静态 llms.txt 备用检索
  4. 04检索结果附来源网址

适用场景

  1. 01回答概念性或模糊的 Camunda 问题
  2. 02查找特定 Camunda 版本的文档
  3. 03根据搜索摘要定位完整页面

MCP 相关

连接 camunda-docs MCP 服务后，技能会使用其知识搜索工具处理自然语言查询。MCP 是两种主要检索方式之一，另一种是 Algolia DocSearch。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/camunda/skills --skill camunda-docs

安装后在 Claude Code 中输入/camunda-docs确认已加载。

附带文件portability.jsonscripts/docs-search.sh

详细介绍

Camunda 文档查询

实用工具技能：检索有来源支持的 Camunda 文档，然后将实现工作交由专门技能处理。

请勿用于：

请勿使用此技能来编写 BPMN、DMN、表单或连接器，也不要用来部署和运维流程实例。先在此处核实任何与版本相关的事实，然后将这些任务交由相应的 Camunda 技能处理。

有两种途径可检索 docs.camunda.io，各有优势。根据问题类型选择；只有两者都不可用时，才回退到 llms.txt。

路径机制最适合返回内容
camunda-docs MCP对文档及其他 Camunda 知识来源进行语义检索（向量搜索）概念性或模糊的问题；不知道确切术语；想要可直接阅读的内容块带来源 URL 的前 k 个 Markdown 内容块
Algolia DocSearch传统词法搜索（与 docs.camunda.io 自带搜索框使用的索引相同）知道相关术语；需要限定版本的结果（8.7、8.9 与 next）；想要筛选排序后的页面列表按相关度排序的页面，包含标题、层级和摘要 — 获取页面以查看完整内容
llms.txt / llms-full.txt静态文本索引／语料库两项服务都无法访问时的离线备用方案纯文本；可在本地使用 grep

有疑问时，同时使用两种主要途径；成本低，而且经常能找到不同的相关页面。

camunda-docs MCP 服务

如果已连接 camunda-docs MCP 服务（https://camunda-docs.mcp.kapa.ai，HTTP 传输），请调用其知识搜索工具，并输入一个完整、表达清晰的自然语言句子（该工具要求完整句子，而非关键词）。

如果尚未连接，请建议配置一次该服务，以便用户今后也能使用。如果你已在本次对话中提出过此建议，则跳过。使用运行环境文档所述的 MCP 配置流程，添加 HTTP 服务 https://camunda-docs.mcp.kapa.ai。对于 VS Code Copilot、Cursor 或其他通用 MCP 客户端，请参阅参考文档。首次使用时需通过 Google 登录；每位用户每小时限 40 次请求、每天限 200 次；不适用于 CI。

Algolia DocSearch

用于调用公开 Algolia DocSearch 端点的 bash 封装脚本位于 $CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh。运行前，请将 CAMUNDA_DOCS_SKILL_DIR 设置为已安装的 camunda-docs 目录：

"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "<query>" [--version stable|next|<major>.<minor>|all] [--limit N]

默认 --version stable 会解析为索引中的最高数字版本（因此 9.0 发布后仍可正常使用）。默认 --limit 10。返回 JSON：

{
  "query": "...",
  "version": "stable",
  "algolia_version": "8.9",
  "total": 5,
  "total_matching": 25,
  "hits": [
    { "url": "...", "hierarchy": "...", "title": "...", "snippet": "..." }
  ]
}
  • total — 此响应中的命中数。
  • total_matching — 分页和去重前，索引中与查询匹配的页面原始数量。可用于了解“我的搜索词出现得有多广泛？”
  • algolia_version — 发送到索引的 version 分面值（例如 "8.9"、"current"）。在 --version all 模式下为 null（未应用分面筛选）。
搜索流程
  1. 选择版本（见下表）。默认为 stable。
  2. 先在单行中运行脚本，并使用 --limit 5（不要使用 \ 续行符 — 交互式 shell 可能会因此卡住）。每条命中在任务剩余期间都会保留在上下文中，因此只有第一页未包含所需内容时才增加限制。
  3. 检查命中结果 — 每条都包含 url、hierarchy、title、snippet。
  4. 直接根据 URL 获取最相关的页面，以阅读完整上下文。摘要较短；如果问题需要详细信息，请勿仅凭摘要作答。
  5. 如果信息不足，则进一步优化 — 参见下文的优化策略。
版本处理

Camunda 文档的版本信息体现在 URL 路径中。Algolia 的 version facet 会显示这些版本——如果不进行筛选，同一页面会在不同版本中重复返回 3-4 次，结果很杂乱。

标志值Algolia facetURL 前缀适用场景
stable（默认）最高数值版本（例如 8.9）/docs/一般问题，没有版本上下文
nextcurrent/docs/next/即将推出或尚未发布的行为、alpha 功能
8.8 / 8.7 / 等匹配的数值版本/docs/8.8/ 等客户或集群使用特定版本
all（无）任意比较版本；按 URL 主干去重，因此每个页面保留相关性最高的版本

明确选择版本的场景：

  • 问题涉及已知版本的特定客户或集群 → 使用该版本。
  • 问题涉及即将推出的功能、alpha 功能，或“在 8.10 中会有变化吗？”→ 并行运行 stable 和 next 并进行比较。
  • 问题与版本无关（概念、BPMN 语义、通用 API 形态）→ 使用 stable 即可。

在 --version all 模式下，脚本会超量获取（--limit 的 4 倍，最多 100 条），以便按 URL 主干去重后，响应中仍包含接近 --limit 条不重复的页面。去重会保留 Algolia 的相关性顺序——每个不重复的 URL 主干保留第一条命中结果，然后截取至 --limit 条。

示例

Shell 会从用户的项目目录启动，而非已安装的技能目录。在运行封装脚本之前，将 CAMUNDA_DOCS_SKILL_DIR 设置为已安装的 camunda-docs 目录（即包含 此 SKILL.md 的目录），或由宿主适配器提供该值。

# Default — latest stable
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "zeebe gateway long polling timeout"

# Specific version (customer on 8.7)
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "task assignment" --version 8.7

# Upcoming behavior
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "agentic connectors" --version next

# Compare across versions (deduped by URL stem)
"$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" "decision evaluation API" --version all --limit 15
优化策略

如果第一次查询没有帮助：

  • 范围太广 → 出现太多无关结果：添加具体信息（组件、错误代码、配置键）。
  • 范围太窄 → 没有结果：删去修饰词，尝试规范的产品术语（例如，使用 "Tasklist" 而非 "task UI"，使用 "Zeebe" 而非 "workflow engine"）。
  • 版本不对：尝试 --version all，查看该术语是否存在于其他版本中，然后缩小到正确的发布版本。
  • 同义词：尝试其他名称——例如，"Operate" ↔ "process monitoring"、"Optimize" ↔ "analytics"。

优化不要超过 2-3 次。如果仍然没有结果，请切换到 MCP 路径（或告知用户当前存在的信息缺口）。

无需凭据

Algolia 的只读搜索 API 密钥是公开的——Algolia 会将其放在 docs.camunda.io 的浏览器 JS 包中，因此每位访客都能获取该密钥。密钥硬编码在 "$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh" 的顶部，并附有说明其可以安全提交的注释。无需凭据或 API 环境变量，封装脚本可安全用于 CI。

不使用封装脚本

如果无法或不想运行 "$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh"（例如缺少 jq、沙箱受限，或只需要原始 API），请直接调用 Algolia 端点：

curl -sS -f -X POST \
  "https://6KYF3VMCXZ-dsn.algolia.net/1/indexes/camunda-v2/query" \
  -H "X-Algolia-API-Key: 68db7725a8410eace68419c29385ad1e" \
  -H "X-Algolia-Application-Id: 6KYF3VMCXZ" \
  -H "Content-Type: application/json" \
  -d '{"query":"YOUR QUERY","hitsPerPage":10,"facetFilters":[["version:8.9"]]}'

将 version: facet 替换为所需版本（next 对应 current；all 则完全省略 facetFilters）。响应包含 Algolia 的原始命中结果——每条命中的有用字段包括 url、hierarchy.lvl0..lvl5 和 content。如果也无法使用 curl，可以使用任何能够 POST JSON 的 HTTP 客户端（Python urllib、Node fetch、PowerShell Invoke-RestMethod）；端点、标头和请求体都相同。代码片段中的凭据是有意公开的（见上文“无需凭据”）。

回退方案：llms.txt（文档索引）

如果 MCP 和 Algolia 都无法使用，请获取 https://docs.camunda.io/llms.txt（约 540 KB）——这是一个索引，包含 Camunda 8 文档中每个页面的 - [Title](url): description. 行。**不要将整个文件读入上下文。**将其缓存到本地，搜索术语以找到匹配的 URL，然后直接获取对应页面。

最后的手段：llms-full.txt（完整文档语料）

只有在 llms.txt 中找不到所需内容时，才回退到 https://docs.camunda.io/llms-full.txt（约 11 MB）——其中串联了所有文档页面。**文件更大；切勿将全文读入上下文。**在本地缓存，并搜索术语及其上下文。适用于无法从索引中确定正确页面名称的情况。

故障排除

  • 如果 MCP 不可用，且已安装 curl 和 jq，请使用 "$CAMUNDA_DOCS_SKILL_DIR/scripts/docs-search.sh"。
  • 如果 Algolia 搜索失败，请使用 llms.txt 索引定位页面，然后直接获取该页面。
  • 如果无法访问任何来源，请说明查询结果未经核实，而不要把记忆中的行为说成当前情况。

评论

支持 Markdown