# Runtime 实施方案
修订记录
| 版本 | 日期 | 修订说明 |
|---|
| v0.1 | 2026-05-01 | 建立当前设计基线；延续 kunora-wiki 作为 llm-wiki 方案的既有产品封板和工程设计，不推倒重来。 |
1. 文档目标
本文定义 Answer API、Agent Access API 和 AgentBridge 的运行环境实施方案。runtime 负责承载自研服务入口、鉴权、日志、审计、外部 adapter 调用和 workflow 执行环境；具体业务契约以 docs/development 为准。
2. 核心部署单元
| 单元 | 形态 | 职责 |
|---|
| Answer API | HTTP service 或 serverless function | 标准问答、session、citation、no-answer action。 |
| Agent Access API | HTTP service 或 serverless function | 受控 agent tools、scope 校验、FeedbackBridge。 |
| AgentBridge | GitHub Actions job 或受控 worker | 从 Issue/task 生成 Release PR。 |
| Adapter clients | runtime library | GitHub、RAGFlow、Meilisearch 调用隔离。 |
3. 配置与密钥
| 输入 | 消费者 |
|---|
config/agent-access.yaml | Agent Access API、AgentBridge。 |
config/ragflow.yaml | Answer API、AgentBridge。 |
config/index.yaml | Answer API、Agent Access API。 |
config/model-policy.yaml | Answer API、AgentBridge。 |
state/page-manifest.json | Answer API、Agent Access API。 |
state/publish-manifest.json | Answer API、Agent Access API。 |
state/index-manifest.json | Answer API、Agent Access API。 |
Secrets：
| Secret | 用途 |
|---|
ANSWER_API_TOKEN | Answer API 调用保护。 |
AGENT_ACCESS_TOKEN | Agent Access API 调用保护。 |
RAGFLOW_API_KEY | RAGFlow 调用。 |
MEILI_MASTER_KEY | 搜索调用。 |
GH_DOCS_TOKEN | Issue/PR/branch 操作。 |
MODEL_API_KEY | 模型调用，如不由 RAGFlow 承载。 |
4. 运行规则
- 所有入口必须生成
requestId 或 runId。
- 所有写入类工具必须校验
idempotencyKey。
- scope 由服务端 policy 收敛，调用方声明不能扩大权限。
- Answer API 正式问答默认只使用 approved dataset。
- Agent Access API 写入只能通过 FeedbackBridge 或受控 PR 任务。
- AgentBridge 不得直接写
main，只能创建 Release PR。
- runtime 日志不得输出 token、secret、完整外部私有响应。
5. GitHub Actions 集成
| Workflow | runtime 角色 |
|---|
docs-publish.yml | 生成 manifest，供 Answer/API 读取。 |
docs-index.yml | 更新 RAGFlow/Meilisearch，并写 index manifest。 |
docs-agent.yml | 启动 AgentBridge，读取 Issue/task，创建 Release PR。 |
6. 失败处理
| 场景 | 响应 |
|---|
| manifest 缺失 | 返回标准错误，不调用外部问答。 |
| approved index failed | 返回索引不可用或使用上一版成功 manifest，并显式标记 stale。 |
| working dataset failed | AgentBridge 任务失败，不影响正式问答。 |
| scope 越权 | 返回 access.forbidden 并记录 AuditEvent。 |
| 外部服务超时 | 返回 retryable 错误，不暴露底层私有响应。 |
| session token 不匹配 | 拒绝请求并记录审计事件。 |
7. 完成定义
- Answer API 能读取 manifest 并调用 approved dataset。
- AnswerSession 校验
sessionTokenHash、turns、maxTurns 和 maxContextTokens。
- Agent Access API 能按 policy 限制 tools、paths、datasets。
- FeedbackBridge 能创建或复用 Issue，并使用 dedupeKey。
- AgentBridge 能从 Issue/task 创建 Release PR，不直写
main。
- 所有入口有 request/run audit。
- 所有密钥只来自 Secrets/Variables，不进入日志和 manifest。