Answer API 与 Agent Access 技术协议

1. 协议目标

本协议定义人和智能体如何通过受控接口使用 LLM-WIKI 的搜索、问答、上下文和反馈能力。

核心原则：

• Answer API 是 RAGFlow 问答能力的薄封装。
• Agent Access API 是智能体工具入口，不生成第二套答案。
• 每次调用必须有 scope、身份、权限和审计。
• 答案必须有引用或明确无答案。

2. 覆盖产品特性

产品特性	覆盖方式
页面内问答入口	前端调用 Answer API
面向人的问答	Answer API 标准化 RAGFlow 结果
面向智能体的问答接口	Agent Access ask 工具
引用来源 / 引用回跳	citations 标准结构
不确定性表达	confidence、grounding、noAnswerReason
答案结构化呈现	AnswerResult schema
多轮追问	AnswerSession
无答案处理	创建反馈或改进任务
智能体知识访问 API	Agent Access tools
任务上下文包	get_context 返回 ContextPack
智能体访问 scope	服务端 policy 校验
智能体反馈与改进任务提交	create_feedback / create_improvement_task

3. API 入口

API / Tool	使用者	说明
POST /answer/ask	人 / 前端	单轮问答
POST /answer/sessions	人 / 前端	创建多轮会话
POST /answer/sessions/{sessionId}/turns	人 / 前端	多轮追问
POST /agent/tools/search	智能体	搜索
POST /agent/tools/ask	智能体	问答
POST /agent/tools/get_page	智能体	读取页面
POST /agent/tools/get_context	智能体	获取上下文包
POST /agent/tools/create_feedback	智能体	创建反馈
POST /agent/tools/create_improvement_task	智能体	创建改进任务

4. 标准请求

{
  "caller": {
    "type": "human|agent",
    "id": "kunora-coding-agent",
    "purpose": "implementation-support"
  },
  "scope": {
    "projects": ["kunora-kgent"],
    "paths": ["publish/system/components/kunora-kgent"],
    "version": "main",
    "includeWorkingDocs": false
  },
  "question": "kunora-kgent 如何配置 agent memory?",
  "requireCitations": true
}

5. 标准响应

{
  "answer": "...",
  "summary": "...",
  "citations": [
    {
      "path": "publish/system/components/kunora-kgent/index.md",
      "url": "/system/components/kunora-kgent/",
      "title": "...",
      "anchor": "...",
      "chunkId": "...",
      "sourceProject": "kunora-kgent",
      "version": "main"
    }
  ],
  "confidence": "high|medium|low",
  "noAnswerReason": null,
  "relatedPages": [],
  "actions": [
    {
      "type": "create_feedback",
      "enabled": true,
      "dedupeKey": "..."
    }
  ],
  "audit": {
    "requestId": "...",
    "caller": "kunora-coding-agent",
    "scope": "main:publish/system/components/kunora-kgent"
  }
}

6. 授权规则

Answer API 和 Agent Access 的调用者不同，授权规则必须拆开。

6.1 人类调用者授权

人类调用者主要来自 Docusaurus 页面或 Web UI。

MVP 允许两种模式：

模式	说明
public-read	已发布文档公开可问答，调用者可以是匿名用户
authenticated-read	调用者必须通过 GitHub OAuth、SSO 或内部登录识别身份

校验顺序：

1. 判断站点访问模式。
2. authenticated-read 模式下校验用户登录态。
3. 根据页面路径和发布状态生成默认 scope。
4. 禁止人类前端请求 includeWorkingDocs=true，除非用户具备维护者权限。
5. 调用 Answer API。

6.2 智能体调用者授权

Agent Access 必须使用服务端 policy，而不是信任调用方自报 scope。

校验顺序：

1. 校验 agent token。
2. 解析 agent identity。
3. 加载服务端 policy。
4. 校验 tool 是否允许。
5. 校验请求 scope 是否是授权 scope 子集。
6. 校验 dataset 是否允许。
7. 校验写入类动作是否允许。
8. 调用底层 RAGFlow、Meilisearch 或 GitHub。

6.3 共享约束

• 无论人类还是智能体，正式问答默认只能访问 approved dataset。
• 调用方声明的 scope 只是请求，不是授权事实。
• working docs 只能在显式授权后访问。
• 所有问答调用都必须生成 requestId 和审计记录。

7. 多轮会话

AnswerSession 结构：

{
  "sessionId": "...",
  "sessionTokenHash": "...",
  "owner": {
    "type": "human|agent",
    "id": "..."
  },
  "scope": {
    "paths": ["publish/system/components/kunora-kgent"],
    "version": "main"
  },
  "turns": [],
  "limits": {
    "maxTurns": 8,
    "maxContextTokens": 12000
  },
  "createdAt": "...",
  "expiresAt": "..."
}

约束：

• 创建 session 时必须绑定 owner 和 session token。
• 调用 /answer/sessions/{sessionId}/turns 时必须同时校验 session token、owner、scope 和 expiresAt。
• 后续追问默认继承初始 scope。
• 追问不能扩大 scope，除非重新授权。
• 每轮回答必须保留引用或明确无答案。
• 超过限制时裁剪旧轮次，但保留引用摘要。
• MVP 可使用短期会话存储，不要求长期保存。
• sessionId 不能作为唯一授权凭据。

8. 无答案处理

当 RAGFlow 无法给出有证据答案时：

• answer 可以为空或包含简短说明。
• confidence 必须为 low。
• noAnswerReason 必须有值。
• 响应必须提供 create_feedback 或 create_improvement_task action。
• 不允许编造无引用答案。

8.1 反馈与改进任务幂等

create_feedback 和 create_improvement_task 必须支持幂等。

建议字段：

{
  "eventType": "qa_no_answer",
  "dedupeKey": "sha256(eventType + normalizedQuestion + normalizedScope + citationPaths)",
  "idempotencyKey": "...",
  "question": "...",
  "scope": {
    "paths": ["publish/system/components/kunora-kgent"],
    "version": "main"
  },
  "citations": [],
  "caller": {
    "type": "human|agent",
    "id": "..."
  }
}

规则：

• dedupeKey 用于识别同一类知识缺口或反馈。
• idempotencyKey 用于防止同一次客户端重试创建重复记录。
• 同一 dedupeKey 已有开放 Issue 时，应追加评论、计数或最近发生时间，不创建重复 Issue。
• 不同 caller 对同一问题的反馈可以合并计数，但必须保留 caller 类型和时间。
• dedupeKey 不能包含明文敏感信息；应使用规范化后 hash。

9. 错误码

错误码	含义
unauthorized	token 无效
session_forbidden	调用者不拥有该 session
session_expired	session 已过期
forbidden_scope	scope 超出授权范围
forbidden_tool	tool 未授权
dataset_not_allowed	dataset 未授权
ragflow_unavailable	RAGFlow 不可达
search_unavailable	Meilisearch 不可达
no_answer	知识库无法回答
invalid_request	请求 schema 不合法

10. 验收用例

用例	预期
人在页面提问	返回 answer、citations、confidence
智能体越权访问路径	返回 forbidden_scope
智能体调用未授权工具	返回 forbidden_tool
知识库无答案	返回 noAnswerReason 和反馈 action
重复提交同一无答案反馈	复用已有 Issue 或反馈记录，不创建重复 Issue
多轮追问	session 保留 scope 和引用上下文
非 owner 使用 sessionId 追问	返回 session_forbidden
session 过期后追问	返回 session_expired
RAGFlow 不可达	返回错误，不创建虚假答案