🧠OrKa onboarding: example suite, guided tour, and trace replay

工程师不需要更多炒作。我们需要可运行的流程、可见的状态和能在生产环境中存活的契约。本指南展示了OrKa如何通过具体示例套件、OrKa UI中的引导式导览和完整追踪回放来降低入门门槛，让您理解每一步操作。包含直接链接到实时文档和示例，方便您立即动手实践。

TLDR

使用示例套件在几分钟内运行您的第一个OrKa工作流。
在OrKa UI中启动引导式导览，使用真实追踪解释每个面板。
检查追踪、记忆写入、合并策略和解析后的提示。
所有内容都由契约和真实代码库支持。查看文档和示例：
- 文档文件夹：https://github.com/marcosomma/orka-reasoning/tree/master/docs
- 示例目录：https://github.com/marcosomma/orka-reasoning/tree/master/examples
- 苏格拉底示例：https://github.com/marcosomma/orka-reasoning/tree/master/examples/orka_soc

为什么这很重要

大多数AI项目从一个模型调用和一个聊天框开始。在演示中感觉良好，但一旦需要决策、并行工作、记忆或可观察性，就会崩溃。最终您会复制粘贴模式并拼接无人能读的日志。这是每个团队都要付出的代价。 OrKa旨在消除这种代价。您将认知定义为图。代理执行工作。节点引导控制。编排器执行图并发出追踪。OrKa UI读取追踪并让您回放运行、检查节点输出，并查看记忆随时间的变化。引导式导览现在位于UI顶部，新用户可以通过使用真实追踪（而非静态截图）的短路径学习。如果您是开发者，这种入门方式尊重您的时间。没有神秘感，没有繁文缛节。您运行一个小示例，观察其执行，并检查发生的真相。

一分钟内的心智模型

编排器执行YAML中定义的图。策略包括顺序流、条件路由、分叉组、故障转移和循环。
节点是图中的控制点。节点可能运行代理或在不运行模型的情况下路由执行。
代理是工作单元。构建器返回结构化输出。分类器返回标签和置信度。RAG代理在构建答案前检索上下文。
记忆是一等资源。条目存在于命名空间中并随时间衰减。重要性分数在限制内延长TTL。
追踪是结构化产物。它记录节点顺序、计时、令牌、成本、输入、输出和记忆副作用。OrKa UI回放追踪并从它们渲染面板。
您可以通过读取追踪或在UI中回放来理解任何运行。引导式导览只是按正确顺序指向正确的面板。

您可以实际运行的示例套件

示例套件涵盖常见的生产模式。每个文件夹包含一个orka.yaml、inputs/中的默认输入和traces/中的黄金追踪。您可以用单个命令运行流程，然后将追踪导入OrKa UI并启动引导式导览。

00. Hello flow

最小的流程证明您的环境正常工作。一个构建器代理返回问候语并写入记忆条目。您得到一个带有单个节点执行的干净追踪。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


type: sequential
id: hello_flow
nodes:
  - id: echo_builder
    type: builder
    prompt: |
      You return a JSON object with a single field "message" greeting {{ input.name | default("world") }}.
    output_schema:
      type: object
      properties:
        message: { type: string }
  - id: done
    type: join_node

运行它：

1

orka run examples/00-hello-flow -i '{"name":"OrKa"}' --export-trace 'examples/00-hello-flow/traces/latest.json'

打开OrKa UI并导入latest.json。这应该很简单。如果不是，请在继续之前修复基础问题。

01. Router cookbook

此示例演示了带有小而现实的规则集的条件路由。分类代理发出带有置信度的标签。路由器根据您可以读取和更改的规则选择下一个节点。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


type: conditional
id: router_cookbook
nodes:
  - id: classify
    type: classification
    labels: [tech, policy, other]
  - id: router
    type: router
    strategy: confidence_weighted
    routes:
      - when: label == 'tech' and confidence > 0.6
        next: tech_builder
      - when: label == 'policy'
        next: policy_builder
      - when: true
        next: fallback
  - id: tech_builder
    type: builder
    prompt: "Summarize technical aspects in 3 bullets."
  - id: policy_builder
    type: builder
    prompt: "Outline governance and risk implications in 3 bullets."
  - id: fallback
    type: builder
    prompt: "Say you are unsure and ask one clarifying question."
  - id: join
    type: join_node

在OrKa UI中，路由器节点显示标签和置信度的评估值、匹配的规则和选择的路径。这消除了猜测。您可以微调置信度阈值并观察路径翻转。

02. Fork and join

当您需要对同一输入进行独立视图时，并行路径是理想的。此示例并行运行提取器和批评器，然后合并结果。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


type: fork_group
id: fork_join
nodes:
  - id: fork
    type: fork_group
    agents: [extract, critique]
  - id: extract
    type: builder
    prompt: "Extract key facts as a JSON array of {fact, evidence}."
  - id: critique
    type: validation_and_structuring
    rules: ["no speculation", "include evidence"]
  - id: join
    type: join_node
    merge: concat

UI渲染带有两个子节点的分叉组。连接面板显示合并策略和来自子节点的原始输出。将concat交换为first_success并重新运行以查看故障处理。

03. RAG with memory decay

没有衰减的状态会变成阁楼。此示例展示了由具有命名空间、向量搜索和基于重要性的衰减的记忆存储支持的检索增强生成。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


type: sequential
id: rag_memory_decay
resources:
  memory:
    backend: redisstack
    vector_search_enabled: true
    memory_decay_config:
      enabled: true
      short_term_hours: 2
      long_term_hours: 168
nodes:
  - id: rag
    type: rag_node
    k: 5
    namespace: getting_started
  - id: memory_writer
    type: memory_writer
    importance_score: 0.7
    category: stored
  - id: answer
    type: builder
    prompt: |
      Using retrieved docs and short term context, answer succinctly.

观察记忆覆盖层。您将看到带有命名空间、重要性和计算过期时间的条目。重要条目设计上存活更久。这是您防止陈旧上下文主导的方式。

04. Failover and retry

代理和网络会失败。此示例使用短退避重试快速本地模型，然后回退到更稳健的模型。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type: failover
id: failover_retry
nodes:
  - id: primary
    type: local_llm_agent
    model: fast
    retry: { attempts: 2, backoff_ms: 250 }
  - id: secondary
    type: local_llm_agent
    model: robust
  - id: join
    type: join_node

在失败的运行中，您将看到多次尝试及其延迟。成本会计按尝试和总计进行。这使得性能和经济学可见。

05. Loop with a budget guard

细化循环强大但有风险。您需要循环、令牌和时间的上限。此示例运行一个小型辩论，评分协议，然后继续或总结。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


type: loop
id: loop_budget
limits: { max_loops: 3, max_tokens: 3000, max_ms: 15000 }
nodes:
  - id: debate
    type: loop_node
    inner: fork_group
    agents: [progressive, conservative, realist, purist]
  - id: score
    type: builder
    prompt: "Return agreement_score float in [0,1]."
  - id: stop_router
    type: router
    routes:
      - when: previous_outputs.score.agreement_score >= 0.65
        next: summarize
      - when: true
        next: debate
  - id: summarize
    type: builder
    prompt: "Synthesize common ground in one paragraph."

在追踪中，您可以观察循环的演变。这帮助您在扩展之前调整阈值和循环计数。

06. UI replay with a guided tour

用真实数据教学的引导式导览

OrKa UI导览不是工具提示列表。它是一个绑定到真实追踪的四步学习路径。从示例页面启动导览，它将加载匹配的追踪并高亮重要的部分。

执行路径和计时：导览聚焦于图和执行的节点。您看到顺序、状态和每个节点的延迟。您学习编排器如何推进。
记忆覆盖层：导览打开记忆并显示最近的写入、TTL、重要性和命名空间过滤器。您学习流程持久化了什么以及持续了多久。
解析后的提示：导览为当前节点打开模板查看器。您看到系统注入变量和先前输出后的确切提示。您学习数据如何在代理之间流动。
成本和令牌：导览打开计数器并解释总计与节点级别数字。您学习运行的经济学以及时间花费在哪里。

关键是将心智模型映射到数据。一旦您以这种方式运行几次导览，UI变得可预测，您将完全不需要导览。

保持名称诚实的契约

运行时发出具有严格形状的JSON。UI消费这些形状。这保持了跨层的名称诚实。

最小形状

TraceEvent

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
  "trace_id": "uuid",
  "engine_version": "0.8.0",
  "schema_version": "1.1",
  "events": [
    {
      "timestamp": "2025-08-05T18:22:11Z",
      "agent_id": "extract",
      "node_type": "builder",
      "input": {"text": "..." },
      "output": {"result": "...", "status": "ok"},
      "tokens": {"in": 123, "out": 456},
      "cost": {"usd": 0.0012},
      "latency_ms": 842,
      "memory_writes": [
        {"namespace":"getting_started","category":"stored","ttl_hours": 24,"importance":0.7}
      ]
    }
  ]
}

AgentOutput

1
2
3
4
5
6


{
  "result": "...",
  "status": "ok",
  "error": null,
  "metadata": { "schema": "v1" }
}

MemoryEntry

1
2
3
4
5
6
7
8
9


{
  "namespace": "getting_started",
  "category": "stored",
  "importance": 0.7,
  "vector": true,
  "created_at": "2025-08-05T18:22:12Z",
  "ttl_hours": 24,
  "expires_at": "2025-08-06T18:22:12Z"
}

ExecutionMetadata

1
2
3
4
5
6
7
8


{
  "run_id": "uuid",
  "engine_version": "0.8.0",
  "schema_version": "1.1",
  "memory_backend": "redisstack",
  "total_tokens": 579,
  "total_cost_usd": 0.0039
}

这些是骨架。完整契约存在于文档中。关键思想是，一旦字段名称出现在追踪中，UI必须要么渲染它，要么明确忽略它。没有静默不匹配。

稳定性经验法则

向每个追踪添加engine_version和schema_version。
将破坏性更改保留在新的模式版本后面，并为旧追踪提供映射。
将解析后的提示视为控制资金或风险的代理的测试夹具。
即使在运行时可选，也在追踪中包含记忆写入。可观察性在这里胜过极简主义。

五分钟内的分步入门

您可以调整命令以适应您的设置，但工作流的形状是一致的。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1. 克隆代码库
git clone https://github.com/marcosomma/orka-reasoning

# 2. 选择一个小示例
cd orka-reasoning/examples/00-hello-flow

# 3. 使用默认输入运行并导出追踪
orka run . -i '@inputs/default.json' --export-trace './traces/latest.json'

# 4. 打开OrKa UI并导入追踪
# 从示例页面启动引导式导览

您可以对路由器示例、分叉和连接示例以及带有预算保护的循环重复相同的模式。您运行和回放的越多，系统理解得越快。

故障排除清单

如果感觉不对劲，在浪费时间之前使用此短清单。

UI导入失败：确认您的追踪中的schema_version与UI版本匹配。如果超前，更新UI。如果落后，使用文档中的版本映射。
路由器不采取您期望的路径：检查路由器节点面板并读取评估的标签和置信度。如果模型嘈杂，提高阈值。
连接产生奇怪的形状：打开连接面板并将合并策略从concat切换到schema_merge或first_success。重新运行并比较。
记忆感觉粘滞：打开覆盖层并检查命名空间和衰减设置。也许您没有正确标记条目。
成本看起来高：打开计数器并查看哪个节点主导。检查该节点的解析后提示。您可能发送了比所需更多的上下文。

短反馈循环节省天数。

在现有代码库内的务实采用

您不需要迁移所有内容。从小开始并快速获胜。

包装一个受益于可见性的单个任务。带有路由器的分类器是完美的。
保持第一个YAML在30行以下。密度没有奖品。
将追踪导出为CI产物。回放失败的运行将多次支付设置成本。
每个产品区域使用命名空间。像对待值得模式和卫生的数据库一样对待记忆。
早期添加预算保护并将其结果连接到警报。无声运行永远的循环不是功能。
冻结涉及资金或安全的提示。将它们保留为夹具，并添加轻量级单元测试，渲染解析后的提示并验证结构。

这些习惯使OrKa感觉像是您堆栈的正常部分，而不是特殊实验。

社区笔记和协作文档

并非所有文档都由我编写。有社区贡献的文档解释了其他团队如何思考模块化认知、衰减的作用，以及为什么在某些情况下置信度分布比单一阈值更好。这是有意的。OrKa是基础设施，不是脚本。多个声音保持哲学诚实和契约清晰。上下文和更深层次阅读的最佳入口点在这里：

文档文件夹：https://github.com/marcosomma/orka-reasoning/tree/master/docs
示例目录：https://github.com/marcosomma/orka-reasoning/tree/master/examples
苏格拉底示例：https://github.com/marcosomma/orka-reasoning/tree/master/examples/orka_soc

如果感觉困惑或未指定，打开一个带有追踪片段和简短描述差距的问题。契约在锚定到真实运行时改进最快。

下一步走向哪里

入门是一段旅程，不是单个发布。基线已就位。下一组改进已经确定范围。

更多结合RAG、结构化输出和验证的示例文件夹。
发出完整置信度分布并在您想要探索时支持概率分支的路由器。
检查到代码库中的模式版本映射与测试。
OrKa UI中的追踪差异以比较运行并发现回归。
关于记忆的更深层次文档，包括为长期系统设置重要性和修剪策略的指导。
无需编辑YAML即可交换记忆和队列后端的简单配方。

如果您关心任何这些，加入代码库中的讨论。最好的想法往往来自每天依赖系统的人。

结语

入门不应该是迷宫。它应该是跑道。示例套件给您速度。OrKa UI中的引导式导览给您清晰度。追踪给您真相。一起使用它们，您将在一个下午理解OrKa，而不是一周。克隆代码库。运行一个示例。导入追踪。启动导览。然后决定您是否要路由、分叉、添加记忆或带有保护的循环。您处于控制之中，并且可以看到发生了什么。如果本指南节省了您的时间，将部分复制到您的内部wiki并调整YAML以适应您的用例。如果某些东西坏了，发送追踪，我们将修复契约或文档。快乐发布。

OrKa入门指南：示例套件、引导式导览与追踪回放

本文详细介绍了OrKa框架的入门流程，包括可运行的示例套件、UI引导导览和追踪回放功能，帮助开发者快速理解AI代理编排、记忆管理和执行追踪等技术实现。