camunda-docs
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCamunda Docs Lookup
Camunda 文档查询
Two retrieval paths into , each with a different strength. Pick by question shape; fall back to only if both are unavailable.
docs.camunda.iollms.txt| Path | Mechanism | Best for | Returns |
|---|---|---|---|
| camunda-docs MCP | Semantic retrieval (vector search) over docs + other Camunda knowledge sources | Conceptual or fuzzy questions; you don't know the exact term; want chunks ready to read | Top-k markdown chunks with source URLs |
| Algolia DocSearch | Classical lexical search (the same index docs.camunda.io's own search box uses) | You know the term; want version-scoped results (8.7 vs 8.9 vs next); want to triage a ranked page list | Ranked pages with title, hierarchy, snippet — fetch the page for full content |
| llms.txt / llms-full.txt | Static text index/corpus | Offline fallback when neither service is reachable | Plain text; grep locally |
Use both primary paths in parallel when in doubt — they're cheap and frequently surface different relevant pages.
查询有两种检索路径,各有优势。根据问题类型选择;仅当两种路径都不可用时,才回退到。
docs.camunda.iollms.txt| 路径 | 机制 | 适用场景 | 返回内容 |
|---|---|---|---|
| camunda-docs MCP | 基于文档及其他Camunda知识源的语义检索(向量搜索) | 概念性或模糊问题;不知道确切术语;需要可直接阅读的内容片段 | 带源URL的Top-k Markdown内容片段 |
| Algolia DocSearch | 经典词法搜索(与docs.camunda.io自身搜索框使用相同索引) | 知道确切术语;需要版本限定的结果(8.7 vs 8.9 vs next);需要对排序后的页面列表进行筛选 | 包含标题、层级、片段的排序页面列表——需获取完整页面以查看全部内容 |
| llms.txt / llms-full.txt | 静态文本索引/语料库 | 当上述两种服务均无法访问时的离线回退方案 | 纯文本;本地使用grep检索 |
若不确定,可并行使用两种主要检索路径——成本低且经常能找到不同的相关页面。
camunda-docs MCP server
camunda-docs MCP 服务器
If the MCP server (, HTTP transport) is connected, call its knowledge search tool with a single, well-formed natural-language sentence (the tool requires a complete sentence, not keywords).
camunda-docshttps://camunda-docs.mcp.kapa.aiIf it isn't connected, suggest installing it once so the user has it set up for future questions. Skip the suggestion if you've already made it earlier in this conversation. For Claude Code:
bash
claude mcp add --transport http camunda-docs https://camunda-docs.mcp.kapa.aiFor VS Code Copilot, Cursor, or generic MCP clients, see the reference. Google sign-in on first use; 40 requests/hour and 200/day per user; not for CI.
若已连接 MCP服务器(,HTTP传输),请使用一个结构完整的自然语言句子调用其知识搜索工具(该工具要求完整句子,而非关键词)。
camunda-docshttps://camunda-docs.mcp.kapa.ai若未连接,建议用户安装一次,以便后续提问使用。若本次对话中已提过该建议,则无需重复。针对Claude Code:
bash
claude mcp add --transport http camunda-docs https://camunda-docs.mcp.kapa.ai针对VS Code Copilot、Cursor或通用MCP客户端,请查看参考文档。首次使用需Google登录;每个用户每小时限额40次请求,每日限额200次;不适用于CI环境。
Algolia DocSearch
Algolia DocSearch
A bash wrapper around the public Algolia DocSearch endpoint lives at . Run it as:
scripts/docs-search.shbash
scripts/docs-search.sh "<query>" [--version stable|next|<major>.<minor>|all] [--limit N]Default resolves to the highest numeric version in the index (so it keeps working when 9.0 ships). Default . Returns JSON:
--version stable--limit 10json
{
"query": "...",
"version": "stable",
"algolia_version": "8.9",
"total": 5,
"total_matching": 25,
"hits": [
{ "url": "...", "hierarchy": "...", "title": "...", "snippet": "..." }
]
}- — hits in this response.
total - — raw count of pages matching the query in the index, before pagination/dedupe. Useful for "how broadly does my term appear?"
total_matching - — the
algolia_versionfacet value sent to the index (e.g.version,"8.9")."current"innullmode (no facet filter applied).--version all
围绕公开Algolia DocSearch端点的bash封装脚本位于。运行方式如下:
scripts/docs-search.shbash
scripts/docs-search.sh "<query>" [--version stable|next|<major>.<minor>|all] [--limit N]默认会解析为索引中最高的数字版本(因此当9.0发布时仍能正常工作)。默认。返回JSON格式:
--version stable--limit 10json
{
"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
Search flow
检索流程
- Pick a version (see table below). Default .
stable - Run the script.
- Inspect the hits — each has ,
url,hierarchy,title.snippet - Fetch the most relevant page(s) directly by URL to read full context. Snippets are short; don't answer from them alone if the question needs detail.
- Refine if insufficient — see refinement strategy below.
- 选择版本(见下表)。默认。
stable - 运行脚本。
- 检查命中结果——每个结果包含、
url、hierarchy、title。snippet - 直接获取最相关的页面以阅读完整上下文。片段内容简短,若问题需要详细信息,请勿仅基于片段作答。
- 若结果不足则优化查询——见下方优化策略。
Version handling
版本处理
The Camunda docs are versioned in the URL path. The Algolia facet exposes those versions — without filtering, the same page returns 3-4 times across versions, which is noisy.
version| Flag value | Algolia facet | URL prefix | Use when |
|---|---|---|---|
| highest numeric (e.g. | | General questions, no version context |
| | | Upcoming/unreleased behavior, alpha features |
| matching numeric | | Customer/cluster on a specific generation |
| (none) | any | Comparing versions; results deduped by URL stem so best-relevance version per page wins |
Pick explicitly when:
- Question is about a specific customer/cluster on a known generation → use that version.
- Question is about an upcoming feature, an alpha, or "will this change in 8.10?" → run and
stablein parallel and compare.next - Question is version-neutral (concepts, BPMN semantics, generic API shape) → is fine.
stable
In mode the script over-fetches (4× , capped at 100) so that after dedupe by URL stem the response contains close to unique pages. Dedupe preserves Algolia's relevance order — first hit per unique URL stem wins, then trimmed to .
--version all--limit--limit--limitCamunda文档在URL路径中进行版本区分。Algolia的分面暴露了这些版本——若不进行过滤,同一页面会在不同版本中重复出现3-4次,导致结果冗余。
version| 标志值 | Algolia分面 | URL前缀 | 适用场景 |
|---|---|---|---|
| 最高数字版本(例如 | | 通用问题,无版本上下文 |
| | | 即将发布/未发布的功能、Alpha特性 |
| 匹配的数字版本 | | 客户/集群使用特定版本 |
| 无 | 任意 | 版本对比;结果按URL主干去重,因此每个页面会保留相关性最高的版本 |
需明确选择版本的场景:
- 问题涉及使用特定版本的客户/集群 → 使用对应版本。
- 问题涉及即将推出的功能、Alpha特性或“这在8.10中会变化吗?” → 并行运行和
stable并对比结果。next - 问题与版本无关(概念、BPMN语义、通用API格式) → 使用即可。
stable
在模式下,脚本会超额获取结果(为的4倍,上限100条),以便按URL主干去重后,响应中包含接近数量的唯一页面。去重会保留Algolia的相关性排序——每个唯一URL主干的第一个命中结果保留,然后截断至数量。
--version all--limit--limit--limitExamples
示例
bash
undefinedbash
undefinedDefault — latest stable
默认——最新稳定版
scripts/docs-search.sh "zeebe gateway long polling timeout"
scripts/docs-search.sh "zeebe gateway long polling timeout"
Specific version (customer on 8.7)
特定版本(客户使用8.7)
scripts/docs-search.sh "task assignment" --version 8.7
scripts/docs-search.sh "task assignment" --version 8.7
Upcoming behavior
即将推出的功能
scripts/docs-search.sh "agentic connectors" --version next
scripts/docs-search.sh "agentic connectors" --version next
Compare across versions (deduped by URL stem)
跨版本对比(按URL主干去重)
scripts/docs-search.sh "decision evaluation API" --version all --limit 15
undefinedscripts/docs-search.sh "decision evaluation API" --version all --limit 15
undefinedRefinement strategy
查询优化策略
If the first query is unhelpful:
- Too broad → too many off-topic hits: add specifics (component, error code, config key).
- Too narrow → no hits: drop adjectives, try the canonical product term (e.g. not
"Tasklist","task UI"not"Zeebe")."workflow engine" - Wrong version: try to see if the term exists elsewhere, then narrow to the right release.
--version all - Synonyms: try alternative names — e.g. ↔
"Operate","process monitoring"↔"Optimize"."analytics"
Don't loop more than 2-3 refinements. If still nothing, switch to the MCP path (or note the gap to the user).
若首次查询结果无用:
- 范围过宽 → 无关命中过多:添加具体信息(组件、错误码、配置键)。
- 范围过窄 → 无命中结果:去掉形容词,尝试使用标准产品术语(例如用而非
"Tasklist",用"task UI"而非"Zeebe")。"workflow engine" - 版本错误:尝试查看术语是否存在于其他版本,再缩小到正确版本。
--version all - 同义词替换:尝试替代名称——例如↔
"Operate","process monitoring"↔"Optimize"。"analytics"
优化次数不要超过2-3次。若仍无结果,切换到MCP路径(或告知用户存在信息缺口)。
No credentials needed
无需凭证
The Algolia search-only API key is public — Algolia ships it in the browser JS bundle of docs.camunda.io, so every visitor already has it. It's hardcoded at the top of with a comment explaining why it's safe to commit. No env vars, no auth, safe in CI.
scripts/docs-search.shAlgolia只读API密钥是公开的——Algolia将其包含在docs.camunda.io的浏览器JS包中,因此每位访客都已拥有该密钥。它被硬编码在顶部,并附有注释说明为何可以安全提交。无需环境变量,无需认证,可安全用于CI环境。
scripts/docs-search.shWithout the wrapper script
不使用封装脚本的情况
If you can't or don't want to run (e.g. missing, restricted sandbox, or you just need the raw API), call the Algolia endpoint directly:
scripts/docs-search.shjqbash
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"]]}'Substitute the facet for the version you want ( for , omit entirely for ). The response shape is Algolia's raw hits — useful fields per hit are , , and . If itself isn't available either, use any HTTP client that can POST JSON (Python , Node , PowerShell ); the endpoint, headers, and body are the same. The credentials in the snippet are public by design (see "No credentials needed" above).
version:currentnextfacetFiltersallurlhierarchy.lvl0..lvl5contentcurlurllibfetchInvoke-RestMethod若无法或不想运行(例如缺少、沙箱受限,或仅需原始API),可直接调用Algolia端点:
scripts/docs-search.shjqbash
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"]]}'将分面替换为你需要的版本(对应,若使用则完全省略)。响应格式为Algolia的原始命中结果——每个命中结果的有用字段包括、和。若也不可用,可使用任何能POST JSON的HTTP客户端(Python 、Node 、PowerShell );端点、请求头和请求体均相同。代码片段中的凭证为公开设计(见上方“无需凭证”部分)。
version:currentnextallfacetFiltersurlhierarchy.lvl0..lvl5contentcurlurllibfetchInvoke-RestMethodFallback: llms.txt (docs index)
回退方案:llms.txt(文档索引)
If neither MCP nor Algolia is usable, fetch (~540 KB) — an index of lines for every Camunda 8 docs page. Do not read the whole file into context. Cache it locally, search for the term to find the matching URL, then fetch that page directly.
https://docs.camunda.io/llms.txt- [Title](url): description.若MCP和Algolia均无法使用,可获取(约540 KB)——这是一个包含所有Camunda 8文档页面的索引,格式为。请勿将整个文件读入上下文。本地缓存该文件,搜索术语以找到匹配的URL,然后直接获取该页面。
https://docs.camunda.io/llms.txt- [标题](url): 描述。Last resort: llms-full.txt (full docs corpus)
最后手段:llms-full.txt(完整文档语料库)
Only if doesn't surface what you need, fall back to (~11 MB) — every docs page concatenated. Even larger; never read whole into context. Cache locally, search with surrounding context for the term. Use when the right page name isn't obvious from the index.
llms.txthttps://docs.camunda.io/llms-full.txt仅当无法找到所需内容时,才回退到(约11 MB)——所有文档页面的拼接内容。文件更大;绝对不要将整个文件读入上下文。本地缓存该文件,搜索术语并查看其上下文。适用于无法从索引中确定正确页面名称的情况。
llms.txthttps://docs.camunda.io/llms-full.txt