智能体访问技术方案
# 智能体访问技术方案
1. 覆盖范围
智能体访问产品是 LLM-WIKI 面向外部智能体的受控使用入口。
它不是新的 RAG 引擎，也不是新的文档仓库。它是 LLM-WIKI 控制面提供的一层 API/tool adapter，底层复用 RAGFlow、Meilisearch、GitHub 和发布工作目录元数据。
| 支撑产品 | 使用方式 |
|---|---|
| RAGFlow | 问答、RAG 召回、引用、文档迭代触发 |
| Meilisearch | 人和智能体共用的关键词搜索 |
| GitHub Issues | 反馈和改进任务事实源 |
| GitHub PR | 智能体改动的审批入口 |
| LLM-WIKI 控制面 | scope、权限、元数据、标准输出和审计 |
2. 为什么需要独立访问层
如果只提供网页和普通问答接口，智能体会缺少几个关键能力：
- 无法稳定声明任务 scope。
- 无法 获取结构化上下文包。
- 无法区分正式文档和工作区文档。
- 无法把无答案、冲突、引用不足转成改进任务。
- 无法保证工具调用有审计和权限边界。
因此，智能体访问层必须独立定义，但不独立承载知识事实源。
3. 如何购买或获取
不购买独立商业产品。MVP 自研轻量 API/tool adapter。
后续如果多个智能体系统接入、需要标准工具发现和跨团队治理，再评估 MCP server 或 Agent Gateway。
4. 如何开发
4.1 API 形态
MVP 先提供 HTTP API。后续可在同一能力之上增加 MCP server。
建议模块：
scripts/
agent_access_api.py
agent_tools.py
feedback_github.py
ragflow_adapter.py
search_meilisearch.py
4.2 工具集合
| 工具 | 输入 | 输出 | 底层依赖 |
|---|---|---|---|
search | query、scope、filters | 搜索结果、路径、片段、元数据 | Meilisearch |
ask | question、scope、requireCitations | answer、citations、confidence、noAnswerReason | RAGFlow |
get_page | path、version | 页面内容、frontmatter、来源信息 | Git / publish manifest |
get_context | task、scope、limits | ContextPack | RAGFlow + Meilisearch + metadata |
create_feedback | reason、question、citations、caller | GitHub Issue 或反馈记录 | GitHub Issues |
create_improvement_task | gap、scope、evidence | 改进任务 Issue | GitHub Issues + RAGFlow trigger |
4.3 标准请求
{
"caller": {
"type": "agent",
"id": "kunora-coding-agent",
"purpose": "implementation-support"
},
"scope": {
"projects": ["kunora-kgent"],
"paths": ["publish/system/components/kunora-kgent"],
"version": "main",
"includeWorkingDocs": false
},
"request": {
"tool": "get_context",
"input": {
"task": "实现 agent memory 配置功能",
"question": "需要参考哪些文档？"
}
}
}
4.4 标准响应
{
"status": "ok",
"result": {
"answer": "...",
"contextPack": [],
"citations": [],
"actions": []
},
"audit": {
"caller": "kunora-coding-agent",
"scope": "main:publish/system/components/kunora-kgent",
"requestId": "..."
}
}
5. 如何部署
MVP 可以先以轻量服务部署：
| 方式 | 适用场景 |
|---|---|
| Serverless/API route | 低流量、快速验证 |
| 容器服务 | 内网访问 RAGFlow、需要稳定运行 |
| GitHub Actions 手动工具 | 只给内部任务使用，非实时 |
如果 RAGFlow 在内网，Agent Access API 需要部署在能访问 RAGFlow 的网络内，外部智能体只访问 Agent Access API。
6. 如何配置
建议新增 config/agent-access.yaml：
agentAccess:
enabled: true
defaultDataset: approved
allowWorkingDocs: false
tools:
search: true
ask: true
getPage: true
getContext: true
createFeedback: true
createImprovementTask: true
scopes:
default:
includePaths:
- publish/**
includeWorkingDocs: false
agents:
kunora-coding-agent:
tokenEnv: AGENT_ACCESS_KUNORA_CODING_AGENT_TOKEN
allowedTools:
- search
- ask
- getPage
- getContext
- createFeedback
allowedPaths:
- publish/system/components/**
allowedDatasets:
- approved
allowWorkingDocs: false
writePermissions:
createFeedback: true
createImprovementTask: false
audit:
logRequests: true
createIssueOnNoAnswer: true
授权规则：
- 调用方提交的
caller和scope只作为请求声明。 - Agent Access API 必须先用 token 解析服务端 agent identity。
- 服务端 policy 决定该 agent 可用的 tools、paths、datasets 和写入动作。
- 请求 scope 必须是服务端授权 scope 的子集。
- 任何尝试访问 working docs、未授权 path 或未授权写入工具的请求都必须拒绝并记录审计。
7. 如何使用
7.1 智能体获取上下文
- 智能体携带 token，声明任务、项目和路径 scope。
- Agent Access API 根据服务端 policy 校验 scope。
- 调用
get_context。 - LLM-WIKI 返回 ContextPack，包括相关页面、片段、引用、版本和质量状态。
- 智能体在自己的任务中引用这些上下文。
7.2 智能体提问
- 智能体调用
ask。 - Agent Access API 调用 RAGFlow。
- 返回标准化答案、引用和不确定性。
- 无答案时可调用
create_feedback或create_improvement_task。
7.3 智能体触发改进
- 智能体提交缺口和证据。
- 系统创建 GitHub Issue。
- 被授权时触发 RAGFlow 文档迭代任务。
- RAGFlow 输出结构化建议或内容草稿。
- AgentBridge 校验输出并转成 Release PR。
8. 安全边界
- 智能体访问层默认只读已审批文档。
- 工作区文档必须显式授权。
- 写入类工具只能创建反馈、Issue 或 PR 草稿。
- 不能直接写
main。 - 不能直接发布到 Docusaurus 或其他展示后端。
- 所有调用必须带 caller、scope 和 requestId。
- caller/scope 不能作为授权事实，授权事实只能来自服务端 token policy。
9. 验收标准
| 验收项 | 标准 |
|---|---|
| search | 智能体能按 scope 搜索文档并获得路径和片段。 |
| ask | 智能体能获得带引用答案或明确无答案。 |
| get_page | 智能体能读取授权页面内容 和元数据。 |
| get_context | 智能体能获得任务上下文包。 |
| feedback | 智能体能把错误、无答案、引用不足转成 GitHub Issue。 |
| 权限 | 未授权 scope 被拒绝。 |
| 审计 | 每次调用可追踪 caller、scope、工具和结果。 |