camunda-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Camunda Docs Lookup

Camunda 文档查询

Two retrieval paths into
docs.camunda.io
, each with a different strength. Pick by question shape; fall back to
llms.txt
only if both are unavailable.
PathMechanismBest forReturns
camunda-docs MCPSemantic retrieval (vector search) over docs + other Camunda knowledge sourcesConceptual or fuzzy questions; you don't know the exact term; want chunks ready to readTop-k markdown chunks with source URLs
Algolia DocSearchClassical 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 listRanked pages with title, hierarchy, snippet — fetch the page for full content
llms.txt / llms-full.txtStatic text index/corpusOffline fallback when neither service is reachablePlain text; grep locally
Use both primary paths in parallel when in doubt — they're cheap and frequently surface different relevant pages.
查询
docs.camunda.io
有两种检索路径,各有优势。根据问题类型选择;仅当两种路径都不可用时,才回退到
llms.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
camunda-docs
MCP server (
https://camunda-docs.mcp.kapa.ai
, 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).
If 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.ai
For 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.
若已连接
camunda-docs
MCP服务器(
https://camunda-docs.mcp.kapa.ai
,HTTP传输),请使用一个结构完整的自然语言句子调用其知识搜索工具(该工具要求完整句子,而非关键词)。
若未连接,建议用户安装一次,以便后续提问使用。若本次对话中已提过该建议,则无需重复。针对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
scripts/docs-search.sh
. Run it as:
bash
scripts/docs-search.sh "<query>" [--version stable|next|<major>.<minor>|all] [--limit N]
Default
--version stable
resolves to the highest numeric version in the index (so it keeps working when 9.0 ships). Default
--limit 10
. Returns JSON:
json
{
  "query": "...",
  "version": "stable",
  "algolia_version": "8.9",
  "total": 5,
  "total_matching": 25,
  "hits": [
    { "url": "...", "hierarchy": "...", "title": "...", "snippet": "..." }
  ]
}
  • total
    — hits in this response.
  • total_matching
    — raw count of pages matching the query in the index, before pagination/dedupe. Useful for "how broadly does my term appear?"
  • algolia_version
    — the
    version
    facet value sent to the index (e.g.
    "8.9"
    ,
    "current"
    ).
    null
    in
    --version all
    mode (no facet filter applied).
围绕公开Algolia DocSearch端点的bash封装脚本位于
scripts/docs-search.sh
。运行方式如下:
bash
scripts/docs-search.sh "<query>" [--version stable|next|<major>.<minor>|all] [--limit N]
默认
--version stable
会解析为索引中最高的数字版本(因此当9.0发布时仍能正常工作)。默认
--limit 10
。返回JSON格式:
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
    (未应用分面过滤)。

Search flow

检索流程

  1. Pick a version (see table below). Default
    stable
    .
  2. Run the script.
  3. Inspect the hits — each has
    url
    ,
    hierarchy
    ,
    title
    ,
    snippet
    .
  4. 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.
  5. Refine if insufficient — see refinement strategy below.
  1. 选择版本(见下表)。默认
    stable
    。
  2. 运行脚本。
  3. 检查命中结果——每个结果包含
    url
    、
    hierarchy
    、
    title
    、
    snippet
    。
  4. 直接获取最相关的页面以阅读完整上下文。片段内容简短,若问题需要详细信息,请勿仅基于片段作答。
  5. 若结果不足则优化查询——见下方优化策略。

Version handling

版本处理

The Camunda docs are versioned in the URL path. The Algolia
version
facet exposes those versions — without filtering, the same page returns 3-4 times across versions, which is noisy.
Flag valueAlgolia facetURL prefixUse when
stable
(default)
highest numeric (e.g.
8.9
)
/docs/
General questions, no version context
next
current
/docs/next/
Upcoming/unreleased behavior, alpha features
8.8
/
8.7
/ etc.
matching numeric
/docs/8.8/
etc.
Customer/cluster on a specific generation
all
(none)anyComparing 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
    stable
    and
    next
    in parallel and compare.
  • Question is version-neutral (concepts, BPMN semantics, generic API shape) →
    stable
    is fine.
In
--version all
mode the script over-fetches (4×
--limit
, capped at 100) so that after dedupe by URL stem the response contains close to
--limit
unique pages. Dedupe preserves Algolia's relevance order — first hit per unique URL stem wins, then trimmed to
--limit
.
Camunda文档在URL路径中进行版本区分。Algolia的
version
分面暴露了这些版本——若不进行过滤,同一页面会在不同版本中重复出现3-4次,导致结果冗余。
标志值Algolia分面URL前缀适用场景
stable
(默认)
最高数字版本(例如
8.9
)
/docs/
通用问题,无版本上下文
next
current
/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
数量。

Examples

示例

bash
undefined
bash
undefined

Default — 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
undefined
scripts/docs-search.sh "decision evaluation API" --version all --limit 15
undefined

Refinement 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.
    "Tasklist"
    not
    "task UI"
    ,
    "Zeebe"
    not
    "workflow engine"
    ).
  • Wrong version: try
    --version all
    to see if the term exists elsewhere, then narrow to the right release.
  • 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
scripts/docs-search.sh
with a comment explaining why it's safe to commit. No env vars, no auth, safe in CI.
Algolia只读API密钥是公开的——Algolia将其包含在docs.camunda.io的浏览器JS包中,因此每位访客都已拥有该密钥。它被硬编码在
scripts/docs-search.sh
顶部,并附有注释说明为何可以安全提交。无需环境变量,无需认证,可安全用于CI环境。

Without the wrapper script

不使用封装脚本的情况

If you can't or don't want to run
scripts/docs-search.sh
(e.g.
jq
missing, restricted sandbox, or you just need the raw API), call the Algolia endpoint directly:
bash
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
version:
facet for the version you want (
current
for
next
, omit
facetFilters
entirely for
all
). The response shape is Algolia's raw hits — useful fields per hit are
url
,
hierarchy.lvl0..lvl5
, and
content
. If
curl
itself isn't available either, use any HTTP client that can POST JSON (Python
urllib
, Node
fetch
, PowerShell
Invoke-RestMethod
); the endpoint, headers, and body are the same. The credentials in the snippet are public by design (see "No credentials needed" above).
若无法或不想运行
scripts/docs-search.sh
(例如缺少
jq
、沙箱受限,或仅需原始API),可直接调用Algolia端点:
bash
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:
分面替换为你需要的版本(
current
对应
next
,若使用
all
则完全省略
facetFilters
)。响应格式为Algolia的原始命中结果——每个命中结果的有用字段包括
url
、
hierarchy.lvl0..lvl5
和
content
。若
curl
也不可用,可使用任何能POST JSON的HTTP客户端(Python
urllib
、Node
fetch
、PowerShell
Invoke-RestMethod
);端点、请求头和请求体均相同。代码片段中的凭证为公开设计(见上方“无需凭证”部分)。

Fallback: llms.txt (docs index)

回退方案:llms.txt(文档索引)

If neither MCP nor Algolia is usable, fetch
https://docs.camunda.io/llms.txt
(~540 KB) — an index of
- [Title](url): description.
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.
若MCP和Algolia均无法使用,可获取
https://docs.camunda.io/llms.txt
(约540 KB)——这是一个包含所有Camunda 8文档页面的索引,格式为
- [标题](url): 描述。
。请勿将整个文件读入上下文。本地缓存该文件,搜索术语以找到匹配的URL,然后直接获取该页面。

Last resort: llms-full.txt (full docs corpus)

最后手段:llms-full.txt(完整文档语料库)

Only if
llms.txt
doesn't surface what you need, fall back to
https://docs.camunda.io/llms-full.txt
(~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.txt
无法找到所需内容时,才回退到
https://docs.camunda.io/llms-full.txt
(约11 MB)——所有文档页面的拼接内容。文件更大;绝对不要将整个文件读入上下文。本地缓存该文件,搜索术语并查看其上下文。适用于无法从索引中确定正确页面名称的情况。