Agent Access API 技术设计
# Agent Access API 技术设计
修订记录
| 版本 | 日期 | 修订说明 |
|---|---|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 摘要
Agent Access API 是 kunora-wiki 面向 agent 和系统自动化的受控访问入口。它接收 AgentToolRequest，基于 AgentAccessConfig 和服务端 policy 解析 effective scope，执行受控工具：search、ask、get_page、get_context、create_feedback、create_improvement_task，并返回标准 AgentToolResult、ContextPack、反馈或任务创建结果。
Agent Access API 不允许 agent 直接写 publish/**，不绕过 ReviewBridge 或 AgentBridge 创建内容变更。所有写入类动作必须具备幂等键、去重键和审计记录；所有读取类动作必须受 scope、dataset、qaVisible 和 policy 约束。
2. 模块目标
- 提供稳定
AgentToolRequest/AgentToolResultPublic Contract。 - 对 agent tool、scope、dataset、path、version 做服务端授权。
- 为 agent 提供受控 search、ask、get_page、get_context 能力。
- 通过内部 FeedbackBridge 创建去重的 feedback 和 improvement task，作为后续 AgentBridge 输入。
- 生成完整 audit，记录 passed/failed/denied/partial。
- 防止 agent 越权访问 working docs、config、state 或不可见内容。
3. 非目标
- 不直接修改
publish/**。 - 不直接创建或合并内容 PR。
- 不执行 RAGFlow 迭代改写；这属于 AgentBridge。
- 不批准 agent 输出，也不判断事实正确性。
- 不把 IssueTracker、RAGFlow、Meilisearch 的私有结构透传给 agent。
- 不以 caller 声明的 scope 作为授权事实。
4. 上下文边界
Agent Access API 位于 L3 Access 层。它可以依赖 ConfigManager、WorkspaceStore read-only、Answer API、SearchIndexClient、IssueTracker 和 manifest reader；不能直接依赖 WorkspaceStore 写入能力写正式内容。
5. 输入与输出
5.1 输入
| 输入 | 来源 | 说明 |
|---|---|---|
AgentToolRequest | agent/system | 工具调用请求。 |
AgentAccessConfig | ConfigManager | agent policy、allowed tools、paths、datasets。 |
PageManifest / IndexManifest | state | 页面可见性和索引状态。 |
AnswerResult | Answer API | ask 工具结果。 |
SearchResult[] | SearchIndexClient | search 工具结果。 |
| IssueTracker result | GitHub Issues adapter | FeedbackBridge 创建或复用 feedback/task 的结果。 |
5.2 输出
| 输出 | 消费者 | 说明 |
|---|---|---|
AgentToolResult | agent/system | 标准工具响应。 |
ContextPack | agent/system、AgentBridge | 授权后的上下文包。 |
FeedbackRequest result | Answer API、前端、agent | 反馈创建/去重结果。 |
ImprovementTaskRequest result | AgentBridge、维护者 | 改进任务创建/去重结果。 |
AuditEvent | 审计系统 | 工具调用记录。 |
ErrorObject[] | agent/system | 标准错误。 |
6. 依赖的 common 契约
| 契约 | 用途 |
|---|---|
Caller | agent 或 system 调用者。 |
Scope | 请求范围和 effective scope 输出。 |
AgentToolRequest | 工具输入。 |
AgentToolResult | 工具输出。 |
ContextPack | get_context 输 出。 |
AnswerRequest / AnswerResult | ask 工具调用 Answer API。 |
SearchResult | search 工具输出。 |
FeedbackRequest | create_feedback 输入。 |
ImprovementTaskRequest | create_improvement_task 输入。 |
DedupeKey / IdempotencyKey | 去重和幂等。 |
AuditEvent / AuditRef | 审计。 |
ErrorObject | 错误输出。 |
FeedbackBridge 是 Agent Access API 内部能力，负责把 FeedbackRequest 和 ImprovementTaskRequest 转换为 IssueTracker payload、执行 dedupe/idempotency，并把结果返回为标准 AgentToolResult。GitHub Issues 的 API 差异仍由 IssueTracker adapter 隔离。
7. 工具集合
| Tool | 类型 | 说明 | 写入 |
|---|---|---|---|
search | read | 在授权索引中搜索页面。 | 否 |
ask | read | 调用 Answer API。 | 否 |
get_page | read | 获取单页授权内容或摘要。 | 否 |
get_context | read | 获取多页 ContextPack。 | 否 |
create_feedback | write-controlled | 创建或复用反馈。 | 是，写 Issue/反馈系统 |
create_improvement_task | write-controlled | 创建或复用改进任务。 | 是，写 Issue/任务系统 |
任何未在 allowedTools 中声明的工具都返回 access.forbidden_tool。
8. 授权与 effective scope
授权流程：
规则：
caller.type必须为agent或system。- requested scope 只能缩小 policy，不能扩大 policy。
includeWorkingDocs=true必须同时满足 request 和 policy，默认 false。allowedPaths与 request paths 取交集，空集则拒绝。- dataset 必须在 policy allowedDatasets 内。
config/**默认不可读，state/**只允许读取 manifest 摘要，不允许读取敏感状态。
9. 工具语义
9.1 search
- 输入：query、limit、scope、datasets。
- 输出：
SearchResult[]。 - 必须过滤 qaVisible=false、越权 path、未授权 dataset。
- 索引 partial 时返回
status=partial和错误/警告。
9.2 ask
- 将 request 转换为
AnswerRequest。 - effective scope 不得被 Answer API 扩大。
- 保留 AnswerResult 的 citation 和 noAnswerReason。
answer.no_answer作为 passed 业务结果返回，除非调用方要求严格答案。
9.3 get_page
- 输入：path 或 documentId。
- 只允许读取 effective scope 内页面。
- 默认返回内容摘要、frontmatter 和 citation，不返回未授权全文。
- working docs 需要显式授权。
9.4 get_context
- 输入：问题、paths、limit、context strategy。
- 输出：
ContextPack。 - ContextPack 中的
scope是 effective scope，不是 caller 原始请求。 - 必须包含 limits，避免 agent 获取过量内容。
9.5 create_feedback
- 输入：
FeedbackRequest。 - 必须有
dedupeKey。 idempotencyKey建议必填。- FeedbackBridge 负责查找或创建 GitHub Issue。
- 重复反馈返回已有记录和
access.feedback_dedupedinfo，不重复创建。
9.6 create_improvement_task
- 输入：
ImprovementTaskRequest。 - 必须有 goal、scope、dedupeKey。
- evidence 推荐必填；如果来自 no-answer，可包含问题和相关 citation。
- FeedbackBridge 负责查找或创建改进任务 Issue。
- 创建的任务是 AgentBridge 的候选输入，不代表自动执行。
10. 幂等与去重
| 场景 | 键 | 行为 |
|---|---|---|
| 同一写入请求重试 | idempotencyKey | 返回同一结果或 safe no-op。 |
| 同一 idempotencyKey 不同 payload | idempotencyKey | 返回 access.idempotency_conflict。 |
| 重复反馈 | dedupeKey | 返回已有反馈或追加计数。 |
| 重复改进任务 | dedupeKey | 返回已有 issue/task。 |
| 读取工具重试 | request payload hash | 可重新执行，但 audit requestId 不复用除非上游传入。 |
dedupeKey 不包含 caller id，idempotencyKey 包含 caller id；两者不能混用。
11. 状态与持久化
Agent Access API 不写正式内容，但会写审计和受控任务系统。
| 数据 | 位置 | owner |
|---|---|---|
| AuditEvent | audit log / service log | Agent Access API |
| feedback | IssueTracker / feedback store | Agent Access API FeedbackBridge via adapter |
| improvement task | IssueTracker | Agent Access API FeedbackBridge via adapter |
| idempotency record | API store/cache | Agent Access API |
| ContextPack | response only，可短期缓存 | Agent Access API |
MVP 可使用 GitHub Issues 作为 IssueTracker adapter，但 issue 私有结构不得进入公共契约。
12. 错误处理
| 错误码 | retryable | 场景 | 处理 |
|---|---|---|---|
access.unauthorized | false | caller 未认证 | HTTP 401。 |
access.forbidden_tool | false | tool 不在 allowedTools | HTTP 403，审计 denied。 |
access.forbidden_scope | false | path/version/scope 越权 | HTTP 403，审计 denied。 |
access.dataset_not_allowed | false | dataset 越权 | HTTP 403。 |
access.idempotency_conflict | false | 同 key 不同 payload | 拒绝写入。 |
access.feedback_deduped | false | 重复反馈 | 返回已有记录。 |
access.tool_failed | depends | 下游工具失败 | 包装底层错误。 |
answer.no_answer | false | ask 无答案 | passed 业务结果，可带 action。 |
HTTP partial result MVP 推荐 200 + status=partial，减少客户端兼容复杂度。
13. 安全与审计
必须审计：
- 所有 tool request。
- 所有 denied 请求。
- 所有写入类请求及其 idempotency/dedupe 结果。
- get_context 大范围读取。
- includeWorkingDocs 请求。
- 下游工具失败和 partial result。
安全规则：
- 默认拒绝未声明工具、路径和 dataset。
- 不允许 agent 读取
config/**。 - 不允许 agent 直接写
publish/**或 main。 - 返回内容必须经过 effective scope 过滤。
- 错误详情不得泄漏 token、secret、未授权文档内容。
14. 测试要求
| 测试 | Fixture | 预期 |
|---|---|---|
| forbidden scope | fixtures/common/access/forbidden-scope.json | 返回 access.forbidden_scope，不调用下游。 |
| feedback dedupe | fixtures/common/access/feedback-dedupe.json | 重复反馈返回 deduped。 |
| no answer ask | fixtures/common/answer/no-answer.json | ask 返回 passed + noAnswerReason/actions。 |
| citation result | fixtures/common/index/search-result-citation.json | search/get_context 返回授权 citation。 |
| idempotency conflict | future access idempotency fixture | 同 key 不同 payload 拒绝。 |
| unauthorized working docs | future access working docs fixture | includeWorkingDocs 未授权时拒绝。 |
模块验收标准：
- 所有 tool 都有 schema contract test。
- effective scope 不大于 requested scope 和 policy 交集。
- 写入工具必须测试 idempotency 和 dedupe。
- denied 请求必须产生 audit。
- SearchResult/ContextPack 不包含越权页面。
15. 设计决策
| 决策 | 说明 | 取舍 |
|---|---|---|
| Agent Access API 不直接写内容 | 所有内容变更必须经过 AgentBridge 和 ReviewBridge。 | agent 需要多一步任务流程。 |
| requested scope 只能缩小 policy | 防止 agent 自我授权。 | 配置需要提前声明可用范围。 |
| feedback/task 使用 dedupeKey | 减少无答案和低置信重复 issue。 | 需要设计稳定 canonical payload。 |
| ask 复用 Answer API | 保持人类和 agent 答案契约一致。 | Answer API 需支持系统/agent caller。 |
16. 待确认问题
- get_page 默认返回全文还是摘要，MVP 是否按 token limit 截断。
- IssueTracker 使用 GitHub Issues 时，label、assignee、milestone 是否属于 adapter contract。
- create_improvement_task 是否强制 evidence，还是允许 no-answer 场景无 citation。
- idempotency record 的持久化周期和清理策略。