2. 快速开始

2.1 快速体验一轮 Agent 对话

FlowNex 最基础的使用入口是一轮 Agent 对话。

用户在客户端输入自然语言问题后，系统会完成以下动作：

  1. FlowNex 主站对话、任务中心、Skill、知识库和管理台交互通过 ai-claw-gateway 接入。
  2. AI 应用中心的应用请求通过 ai-app-runtime-gateway 的 application 前缀路由接入，例如行云 AI 算力专项学习服务、会议智能总结、智能项目管理、智能标书。
  3. AI 应用请求进入 ai-app-service，由它承接应用层交互、应用会话、业务语义接口和业务数据落库。
  4. 当请求需要 Agent 执行或原子 AI 能力时，ai-app-service 对接 control-center。
  5. control-center 根据当前用户、租户、角色和能力配置，计算本轮可用的 Capability、Tool、Skill 和知识库范围。
  6. agent-runtime-gateway 将任务路由到可用的 share-harness 实例。
  7. share-harness 重建本轮上下文，调用模型、工具和 Skill。
  8. 执行过程通过 SSE 实时返回给用户。
  9. 任务完成后，消息、任务状态、任务步骤、文件产物和运行指标被持久化。

一次最简单的对话可以不显式选择 Skill 或知识库。例如：

用户：帮我总结一下 FlowNex 当前的系统架构。
Agent：根据当前系统模块，FlowNex 可以分为接入层、编排层、领域层、运行时层和公共能力层……

如果本轮没有指定知识库或 Skill，系统会按默认能力范围执行。默认范围由租户、用户、角色和系统配置共同决定。

2.2 创建并运行一个任务

在 FlowNex 中，用户的一轮输入不仅是一条消息，也会被建模为一个任务。

任务用于承载可追踪的执行过程，包括：

  1. 本轮用户输入。
  2. 本轮附件。
  3. 本轮授权 Tool。
  4. 本轮授权 Skill。
  5. 本轮知识库范围。
  6. Agent 执行步骤。
  7. 工具调用结果。
  8. 生成文件。
  9. 最终回复。
  10. 成功、失败、取消等终态。

任务的典型生命周期如下：

flowchart LR
    A["用户发起消息"] --> B["创建 Message"]
    B --> C["创建 Task"]
    C --> D["下发 Runtime"]
    D --> E["执行 Task Step"]
    E --> F["生成回复 / 文件"]
    F --> G["Runtime Finish Callback"]
    G --> H["更新 Task 和 Message 状态"]

任务可以是普通聊天任务，也可以是定时任务、渠道入站任务或后续多 Agent 子任务。

用户通常不需要感知底层任务模型，但任务模型对企业场景非常重要，因为它支撑了：

  1. 执行过程可回放。
  2. 失败原因可排查。
  3. 文件产物可追踪。
  4. 用户反馈可关联。
  5. 后续经验可沉淀。

2.3 使用 Skill 完成专业任务

Skill 是 FlowNex 中面向专业任务的能力单元。

当用户的问题命中某个专业场景时，系统可以通过 Skill 提供更稳定的执行策略。例如：

用户：帮我根据这份会议记录生成一份项目周报。
系统选择：weekly-report Skill
Agent 行为：读取会议记录 -> 提取进展、风险、下周计划 -> 按周报模板生成结果。

Skill 可以来自：

  1. 平台预置 Skill。
  2. 租户管理员发布的企业 Skill。
  3. 团队维护的业务 Skill。
  4. 用户个人创建或安装的 Skill。

Skill 的使用方式可以分为两类：

  1. 用户显式选择 Skill。
  2. 系统根据用户输入和可用 Skill 自动推荐或命中。

运行时不会把 Skill 当成必须执行列表，而是把 Skill 作为本轮可用能力和上下文来源。最终是否使用某个 Skill，由 share-harness 根据用户意图、Skill 描述、任务证据和运行策略决定。

一个高质量 Skill 通常包括：

  1. 适用场景。
  2. 输入要求。
  3. 执行步骤。
  4. 输出格式。
  5. 可用工具。
  6. 依赖知识。
  7. 风险边界。
  8. 示例和反例。

2.4 使用知识库增强回答

知识库用于为 Agent 提供组织知识依据。

用户可以在前端选择知识库范围，也可以由系统根据当前业务场景和 Skill 绑定关系自动确定默认范围。

知识库增强的一般流程是：

flowchart LR
    A["用户问题"] --> B["计算用户授权知识范围"]
    B --> C["结合用户手选范围"]
    C --> D["结合 Skill 绑定范围"]
    D --> E["生成 knowledgeAccess"]
    E --> F["share-harness 调用 knowledge_search / knowledge_qa"]
    F --> G["装配引用证据"]
    G --> H["生成回答"]

知识库检索必须遵守权限边界。

OpenViking 负责“哪些内容能被检索到”，FlowNex 负责“当前用户是否有资格检索这些内容”。因此，每次运行时检索前，都需要由本地系统计算可信的授权范围。

知识库增强回答应尽量返回引用来源，帮助用户判断回答依据。例如：

根据《项目交付 SOP》第 3.2 节，交付验收前需要完成需求确认、测试报告、上线清单和风险备案。

如果知识库不可用，系统应允许主对话链路降级运行，并在需要时提示用户当前回答未使用组织知识依据。

2.5 查看任务过程、文件产物和执行结果

企业级 Agent 不能只展示最终回答，还需要展示执行过程。

FlowNex 应支持用户和管理员查看：

  1. 本轮任务状态。
  2. 执行步骤。
  3. 工具调用摘要。
  4. Skill 命中情况。
  5. 知识库命中情况。
  6. 引用证据。
  7. 输入附件。
  8. 输出文件。
  9. 错误原因。
  10. 用户反馈。

在 AGFS 接入后，文件产物会进一步具备：

  1. 文件版本。
  2. 文件血缘。
  3. 文件所属任务。
  4. 文件所属 Agent。
  5. 文件 checkpoint。
  6. 文件回滚能力。
  7. 知识候选状态。

这使得 FlowNex 可以从普通的“聊天记录系统”升级为“任务执行和知识资产沉淀系统”。