# Knowledge Agent OS

**Repository Path**: CodingKeep/agent

## Basic Information

- **Project Name**: Knowledge Agent OS
- **Description**: 基于大模型的知识库问答与工具调用 Agent｜后端开发
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Knowledge Agent OS

> **企业级知识工作 Agent 基础设施** | Python · FastAPI · LangGraph · ChromaDB · SQLAlchemy

一个具备**规划、检索、执行、验证、持久化、审批、权限管控、可观测、评测**完整闭环的  
**知识工作 Agent Operating System** 后端。

不只是"能回答问题"——  
而是**能看见、能追踪、能审计、能衡量**每一次 Agent 执行的工程级基础设施。

---

## 项目定位

```
传统 RAG Demo          →   能回答问题
Knowledge Agent OS     →   能规划 · 检索 · 执行 · 验证 · 审批 · 追踪 · 评测
```

本项目覆盖企业知识 Agent 系统的**全生命周期工程能力**，包括：

- **任务生命周期管理**：每次请求作为结构化 TaskRun 持久化，含完整 StepRun / ToolCallLog
- **证据级别可追溯**：每条结论（Claim）绑定具体文档片段，非黑盒输出
- **人工介入（HITL）**：高风险工具调用自动暂停，等待人工审批后恢复执行
- **角色权限管控（RBAC）**：用户、工具、文档三层权限，支持 admin/analyst/viewer
- **混合检索（Hybrid Retrieval）**：向量 + BM25 关键词 + RRF 融合 + 版本过滤 + ACL 过滤
- **多来源异步摄入**：text/markdown/json/html/local_file，后台任务并行处理
- **MCP 就绪工具注册**：结构化 ToolDefinition，LocalExecutor + MCPReadyExecutor
- **成本与稳定性**：TTL 缓存 + 限流中间件 + LLM 超时/重试 + 预算 API
- **自动化测试体系**：unit / integration / api 三层 159 个测试用例
- **开箱即跑**：Makefile + Docker Compose + GitHub Actions CI + 一键 demo 脚本

---

## 能力矩阵（R1–R21 · RC1）

| 轮次 | 能力 | 核心模块 |
|------|------|----------|
| R1 | 状态持久化（TaskRun/StepRun/ToolCallLog） | `db/models`, `repositories/task_repository` |
| R2 | Trace 可观测（10 种结构化事件，JSON 日志） | `observability/`, `core/logging_config` |
| R3 | 证据绑定（Claim 级别引用追踪） | `evidence_service`, `models/evidence` |
| R4 | 验证层（pass/revise/insufficient/conflict） | `verifier_service`, `graph/evidence_graph` |
| R5 | 评测闭环（6 维评估器，JSONL 数据集） | `evals/` |
| R6 | 多轮对话持久化 | `chat_service`, `repositories/chat_repository` |
| R7 | 评测持久化（EvalRun/EvalCaseResult DB） | `repositories/eval_repository`, `api/evals` |
| R8 | HITL 人工审批流（高风险工具拦截/恢复） | `tools/risk_registry`, `api/approvals` |
| R9 | RBAC + 文档 ACL（三层权限） | `services/access_control_service`, `api/users` |
| R10 | 混合检索（向量+BM25+RRF+重排） | `services/hybrid_retrieval_service`, `db/fts` |
| R11 | 多来源异步摄入管线 | `services/ingestion/`, `api/sources` |
| R12 | MCP 就绪工具注册中心 | `tools/registry`, `api/tools` |
| R13 | 成本/稳定性（TTL 缓存+限流+LLM 重试+预算 API） | `core/cache`, `core/rate_limiter`, `middleware/` |
| R14 | 自动化测试体系（159 个用例） | `tests/` |
| R15 | 部署工程（Docker/CI/seed/demo） | `Dockerfile`, `.github/`, `scripts/`, `Makefile` |
| R16 | 发布前检查（15 项自动化 readiness check） | `app/release/readiness_check.py` |
| R17 | 压力回归（34 条用例，失败注入，mock/real 双模式） | `data/stress_dataset.jsonl`, `app/release/regression_runner.py` |
| R18 | 标准 Demo（3 场景 seed + 就绪检查 + 演示脚本） | `app/demo/`, `docs/demo-final-script.md` |
| R19 | 项目故事与架构文档体系 | `docs/project-story.md`, `docs/architecture.md` |
| R20 | 三种运行模式 + MCP 出口（demo/standalone/platform） | `app/mcp/`, `.env.demo`, `.env.platform` |
| R21 | Release Freeze（25 条基准 + 8 个指标 + gate 检查） | `data/freeze_benchmark.jsonl`, `app/release/freeze_benchmark.py` |

---

## 系统架构

```
HTTP Request
     │
     ▼
TraceMiddleware          ← 注入 trace_id / user_id / role (ContextVar)
AuthMiddleware           ← 从 X-User-Id 解析用户角色
RateLimitMiddleware      ← 滑动窗口限流（普通 20/min，重型 5/min）
     │
     ▼
FastAPI Router           ← /api/v1/{qa,agent,verified-qa,tasks,approvals,users,...}
     │
     ▼
AccessControlService     ← RBAC 工具权限 + 文档 ACL 过滤
     │
     ▼
Service Layer
  ├── VerifiedQAService  ← 完整验证链路（主流程）
  ├── AgentService       ← ReAct Tool Calling + HITL 拦截
  ├── QAService          ← 简单 RAG 问答
  └── ChatService        ← 多轮对话
          │
          ▼
   LangGraph StateGraph (evidence_graph)
     retrieve_evidence   ← HybridRetrievalService (向量+BM25+RRF+重排)
          │
     generate_with_evidence  ← LLMService (timeout=60s, retry=2)
          │
     verify_answer ──────┬── pass           → finalize_answer
                         ├── revise         → (retry, max 1 次)
                         ├── conflict       → conflict_answer
                         └── insufficient   → fallback_answer
          │
          ▼
   ToolRegistry (MCP-Ready)
     LocalToolExecutor   ← 本地工具（calculate/time/search）
     MCPReadyExecutor    ← MCP 协议扩展点
          │
     RiskRegistry        ← LOW/MEDIUM/HIGH 风险分级
     ApprovalRepository  ← HIGH 风险暂停，等待人工 approve
          │
          ▼
   Observability Layer
     emit_event() → TraceEvent DB + JSON 结构化日志
     TTLCache      → embedding(24h) / retrieval(5min) / tool(30min)
          │
          ▼
   Persistence Layer (SQLite / PostgreSQL)
     TaskRun / StepRun / ToolCallLog / EvidenceRecord
     FinalAnswerRecord / TraceEvent / ApprovalRequest
     User / DocumentACL / KnowledgeSourceRecord
```

---

## 目录结构

```
app/
├── api/                        # REST 路由层（16 个 router）
│   ├── qa.py                   # 简单 RAG 问答
│   ├── agent.py                # ReAct Tool Calling
│   ├── verified_qa.py          # 完整验证链路
│   ├── tasks.py                # 任务追踪 + trace + budget
│   ├── evals.py                # 评测历史
│   ├── knowledge.py            # 知识库 ingest/search
│   ├── approvals.py            # HITL 审批流
│   ├── users.py                # 用户管理 + ACL
│   ├── sources.py              # 多来源摄入管理
│   ├── tools.py                # 工具注册中心 API
│   ├── retrieval.py            # 混合检索 debug
│   ├── health.py               # /health + /health/detailed
│   └── evidence_qa.py          # 证据问答
│
├── services/                   # 业务逻辑层
│   ├── verified_qa_service.py  # 主 Agent 服务
│   ├── agent_service.py        # ReAct + HITL 拦截
│   ├── evidence_service.py     # 证据检索与绑定
│   ├── hybrid_retrieval_service.py  # 向量+BM25+RRF+重排
│   ├── verifier_service.py     # 4 状态验证规则引擎
│   ├── knowledge_service.py    # ChromaDB + embedding 缓存
│   ├── llm_service.py          # OpenAI 封装（timeout/retry/token统计）
│   ├── access_control_service.py  # RBAC + 文档 ACL
│   └── ingestion/              # 多来源摄入管线
│       ├── parsers.py          # text/md/json/html/local_file 解析+分块
│       └── pipeline.py         # 异步摄入 + FTS 索引 + ACL 持久化
│
├── graph/                      # LangGraph 工作流
│   ├── evidence_graph.py       # 图结构定义
│   ├── evidence_nodes.py       # 各节点实现（含 observability 埋点）
│   └── evidence_state.py       # TypedDict 状态定义
│
├── tools/                      # 工具层（MCP-Ready）
│   ├── registry.py             # ToolRegistry + LocalExecutor + MCPReadyExecutor
│   ├── definitions.py          # TOOLS / TOOL_NAMES（兼容旧接口）
│   ├── executor.py             # 工具分发 + tool_cache
│   └── risk_registry.py        # LOW/MEDIUM/HIGH 风险分级
│
├── db/                         # 数据库层
│   ├── models.py               # 全部 ORM 模型（15 张表）
│   ├── database.py             # SQLAlchemy 引擎 + SessionLocal
│   ├── fts.py                  # SQLite FTS5 全文索引
│   └── step_tracker.py         # LangGraph 节点仪表化
│
├── core/                       # 基础设施
│   ├── config.py               # pydantic-settings 配置
│   ├── cache.py                # TTLCache（embedding/retrieval/tool）
│   ├── rate_limiter.py         # 滑动窗口限流器
│   ├── logging_config.py       # JSON 结构化日志
│   └── exceptions.py           # AppError 基类
│
├── middleware/                 # ASGI 中间件
│   ├── trace_middleware.py     # trace_id 注入
│   ├── auth_middleware.py      # X-User-Id → user_id/role ContextVar
│   └── rate_limit_middleware.py# 429 + Retry-After
│
├── observability/              # 可观测性
│   ├── trace_context.py        # ContextVar: trace_id/task_id/user_id/role
│   └── events.py               # emit_event() + 事件类型常量
│
├── repositories/               # 数据访问层
│   ├── task_repository.py      # TaskRun/StepRun/ToolCallLog/Evidence/Answer/Event
│   ├── approval_repository.py  # ApprovalRequest CRUD
│   ├── user_repository.py      # User + DocumentACL
│   ├── source_repository.py    # KnowledgeSourceRecord
│   └── eval_repository.py      # EvalRun/EvalCaseResult
│
├── evals/                      # 评测闭环
│   ├── dataset.py              # EvalCase + JSONL 加载
│   ├── evaluators.py           # 6 个规则评估器
│   ├── runner.py               # 评测执行引擎
│   ├── reporter.py             # 文本/JSON 报告
│   └── __main__.py             # python -m app.evals 入口
│
└── models/                     # Pydantic 模型
    ├── evidence.py / verifier.py / approval.py
    ├── auth.py / source.py / retrieval.py
    └── task_models.py

tests/
├── conftest.py                 # 共享 fixture（test_db/mock_llm/client/mock_chroma）
├── unit/                       # 单元测试（access_control/verifier/cache/parsers/registry）
├── integration/                # 集成测试（evidence/approval/persistence）
└── api/                        # API 测试（health/trace/eval_runner）

scripts/
├── init_db.py                  # DB + FTS 初始化（幂等）
├── seed_demo.py                # 演示用户 + 知识文档 + 来源注册
├── demo_run.py                 # 向服务发起 2 个完整演示任务
└── ingest_sample.py            # 从 data/sample_docs/ 批量导入

data/
├── chroma/                     # ChromaDB 本地持久化
├── agent.db                    # SQLite 主数据库
└── eval_dataset.jsonl          # 12 条评测用例

Dockerfile                      # 双阶段构建（builder + runtime）
docker-compose.yml              # app + chromadb + seed profile
.github/workflows/ci.yml        # test / lint / docker-build 三 Job
Makefile                        # 14 个便捷命令
demo.sh / demo.ps1              # 一键演示启动（Linux/Windows）
```

---

## 三种运行模式

| 模式 | 命令 | 场景 |
|------|------|------|
| `standalone` | `make dev` | 标准后端服务（默认）|
| `demo` | `make dev-demo` | 自动 seed 演示数据 + 宽松限流 |
| `platform` | `make dev-platform` | 暴露 MCP 端点（`/api/v1/mcp/*`）|

---

## 快速启动

### 方式一：Makefile（推荐）

```bash
# 1. 安装依赖
make install

# 2. 配置（填写 OPENAI_API_KEY）
cp .env.example .env

# 3a. Demo 模式一键演示（auto-seed + 启动）
make dev-demo

# 3b. 或标准模式（手动 seed）
make demo
```

### 方式二：Docker Compose

```bash
cp .env.example .env          # 填写 OPENAI_API_KEY
docker compose up --build -d  # 启动 app + chromadb
docker compose --profile seed up seed  # 写入演示数据

# 验证
curl http://localhost:8000/api/v1/health
```

### 方式三：一键演示脚本

```powershell
# Windows PowerShell
$env:OPENAI_API_KEY = "sk-xxx"
.\demo.ps1
```

```bash
# Linux / macOS
OPENAI_API_KEY=sk-xxx ./demo.sh
```

### 方式四：手动启动

```bash
python scripts/init_db.py     # 初始化 DB + FTS
python scripts/seed_demo.py   # 写入演示数据
uvicorn main:app --reload     # 启动服务

# 验证
curl http://localhost:8000/api/v1/health/detailed
open http://localhost:8000/docs
```

---

## API 概览

### 核心任务

| Method | Path | 说明 |
|--------|------|------|
| `POST` | `/api/v1/verified-qa/ask` | 完整验证链路问答（推荐） |
| `POST` | `/api/v1/agent/run` | ReAct Tool Calling Agent |
| `POST` | `/api/v1/qa/answer` | 简单 RAG 问答 |
| `POST` | `/api/v1/chat/send` | 多轮对话 |

### 任务追踪 & 预算

| Method | Path | 说明 |
|--------|------|------|
| `GET` | `/api/v1/tasks/` | 列出最近任务（可按类型过滤） |
| `GET` | `/api/v1/tasks/{id}` | 任务详情 + StepRun |
| `GET` | `/api/v1/tasks/{id}/trace` | 完整 trace 时间线 |
| `GET` | `/api/v1/tasks/{id}/budget` | Token 用量 + 成本统计 |
| `GET` | `/api/v1/tasks/{id}/answer` | 最终结构化答案 |

### 知识库

| Method | Path | 说明 |
|--------|------|------|
| `POST` | `/api/v1/knowledge/ingest` | 写入文档（支持 ACL） |
| `POST` | `/api/v1/knowledge/search` | 向量语义检索 |
| `POST` | `/api/v1/retrieval/search` | 混合检索（向量+BM25+RRF） |
| `POST` | `/api/v1/retrieval/debug` | 检索 debug（含各阶段分数） |

### 来源摄入

| Method | Path | 说明 |
|--------|------|------|
| `POST` | `/api/v1/sources/register` | 注册知识来源 |
| `POST` | `/api/v1/sources/{id}/ingest` | 触发异步摄入 |
| `GET` | `/api/v1/sources/` | 列出所有来源 |
| `GET` | `/api/v1/sources/{id}` | 来源状态查询 |

### 工具管理

| Method | Path | 说明 |
|--------|------|------|
| `GET` | `/api/v1/tools/` | 列出当前角色可用工具 |
| `GET` | `/api/v1/tools/{name}` | 工具详情（schema/risk） |
| `POST` | `/api/v1/tools/{name}/dry-run` | 工具 dry-run（不执行） |

### 审批流（HITL）

| Method | Path | 说明 |
|--------|------|------|
| `GET` | `/api/v1/approvals/pending` | 待审批列表 |
| `POST` | `/api/v1/approvals/{id}/approve` | 批准并恢复执行 |
| `POST` | `/api/v1/approvals/{id}/reject` | 拒绝 |
| `POST` | `/api/v1/approvals/{id}/edit-and-approve` | 修改参数后批准 |

### 用户 & ACL

| Method | Path | 说明 |
|--------|------|------|
| `POST` | `/api/v1/users/` | 创建用户 |
| `GET` | `/api/v1/users/{id}` | 用户详情 |
| `PUT` | `/api/v1/users/{id}/role` | 更新角色 |
| `POST` | `/api/v1/users/{id}/acl` | 设置文档 ACL |

### 评测

| Method | Path | 说明 |
|--------|------|------|
| `GET` | `/api/v1/evals/` | 评测历史列表 |
| `GET` | `/api/v1/evals/{run_id}` | 逐 case 分数 |

### 系统

| Method | Path | 说明 |
|--------|------|------|
| `GET` | `/api/v1/health` | 简单健康检查 |
| `GET` | `/api/v1/health/detailed` | DB/ChromaDB/FTS/缓存详细状态 |

---

## Trace & 可观测

每次任务执行产生结构化 trace 时间线：

```bash
curl -H "X-User-Id: demo-admin-001" \
  http://localhost:8000/api/v1/tasks/{task_id}/trace
```

```json
{
  "task_id": "task-abc123",
  "trace_id": "a1b2c3d4",
  "task_type": "verified_qa",
  "total_duration_ms": 4821,
  "events": [
    {"event_type": "task_created",       "step_name": "-",                "duration_ms": null},
    {"event_type": "retrieval_completed","step_name": "retrieve_evidence","extra": {"candidate_count": 5}},
    {"event_type": "llm_called",         "step_name": "chat",             "duration_ms": 1820, "extra": {"total_tokens": 690}},
    {"event_type": "verification_passed","step_name": "verify_answer",    "extra": {"pass_rate": 0.8}},
    {"event_type": "answer_finalized",   "step_name": "-",                "duration_ms": 4821}
  ]
}
```

预算查询：

```bash
curl http://localhost:8000/api/v1/tasks/{task_id}/budget
# → {"llm_call_count":2, "total_tokens":1240, "retrieval_count":1, "tool_call_count":0}
```

---

## HITL 审批流

当 Agent 调用高风险工具（如 `delete_knowledge`）时：

```
1. AgentService 检测到 HIGH 风险工具
2. 创建 ApprovalRequest，暂停执行
3. 审批人调用 POST /approvals/{id}/approve
4. Agent 恢复执行，工具以审批后的参数实际运行
```

```bash
# 查看待审批
GET /api/v1/approvals/pending

# 修改参数后批准
POST /api/v1/approvals/{id}/edit-and-approve
{"updated_args": {"doc_id": "safe_doc"}, "reviewer": "admin"}
```

---

## RBAC 权限控制

| 角色 | 工具权限 | 文档可见性 |
|------|----------|------------|
| `admin` | 所有工具（含高风险） | 所有文档 |
| `analyst` | LOW + MEDIUM 风险工具 | public + restricted（在 ACL 内） |
| `viewer` | 仅 LOW 风险（时间/计算） | 仅 public_in_workspace |

通过请求头传递身份：
```
X-User-Id: demo-analyst-001
```

---

## 混合检索（Hybrid Retrieval）

```
Query
  ├── 向量搜索 (ChromaDB)  →  [候选A: 0.92, 候选B: 0.85, ...]
  ├── BM25 关键词 (FTS5)   →  [候选B: 0.78, 候选C: 0.71, ...]
  │
  └── RRF 融合              →  归一化排序
       │
       ├── 版本过滤          →  排除过期文档
       ├── ACL 过滤          →  按用户角色过滤
       └── 重排（rerank）    →  Cosine 精排
```

Debug API:
```bash
POST /api/v1/retrieval/debug
{"query": "什么是 RAG", "top_k": 5, "user_id": "user1", "role": "analyst"}
```

---

## Eval 说明

```bash
# 运行内置 12 条评测用例
python -m app.evals

# 保存 JSON 报告
python -m app.evals --dataset data/eval_dataset.jsonl --report reports/result.json
```

**6 个评估维度：**

| 指标 | 含义 |
|------|------|
| `task_type_accuracy` | 实际路由 vs 期望路由 |
| `retrieval_hit_rate` | 检索证据命中期望来源关键词率 |
| `citation_presence_rate` | Claims 中有 citations 的比例 |
| `supported_claim_rate` | `supported_count / total_count` |
| `tool_selection_accuracy` | 实际工具 vs 期望工具列表匹配 |
| `task_completion_rate` | 有回答 + 证据数达标 + 验证通过 |

---

## 数据库模型（15 张表）

```
run_records           任务运行记录（早期兼容）
chat_sessions         多轮对话会话
chat_messages         对话消息
task_runs             任务生命周期（绑定 trace_id）
step_runs             LangGraph 节点执行记录
tool_call_records     工具调用明细
evidence_records      证据条目（绑定 claim）
final_answer_records  最终结构化答案
trace_events          可观测性事件时间线
eval_runs             评测运行汇总
eval_case_results     单条评测用例结果
approval_requests     HITL 审批记录
users                 用户 + 角色
document_acl          文档访问控制列表
knowledge_sources     知识来源注册记录
```

---

## 测试 & 质量保障

```bash
make test              # unit + integration + api tests
make regression        # 压力回归 smoke（34 条用例，mock 模式）
make freeze            # Release Freeze（25 条基准 + 8 个 release 指标 + gate 检查）
make demo-check        # Demo 环境就绪检查（7 项）
python -m app.release check  # 发布前 15 项前置检查
```

测试分层：
- **unit**：ACL 权限、验证规则、TTL 缓存、解析器、工具注册
- **integration**：证据绑定、审批流、任务持久化
- **api**：health/detailed、trace 时间线、budget、eval 评估器
- **regression**：34 条压力用例（正常/失败/审批/权限/长任务），失败注入
- **freeze**：25 条冻结基准，8 个 release 指标（task_completion / permission_leak_rate=0 等）

---

## 技术栈

| 组件 | 版本 | 作用 |
|------|------|------|
| Python | 3.12 | 运行时 |
| FastAPI | 0.111 | REST API 框架 |
| LangGraph | 0.2.28 | Agent 状态机工作流 |
| ChromaDB | 0.6.3 | 向量数据库（本地持久） |
| SQLAlchemy | 2.0.30 | ORM（SQLite/PostgreSQL） |
| SQLite FTS5 | 内置 | BM25 全文检索 |
| OpenAI SDK | 1.30 | LLM & Embedding 调用 |
| Pydantic | v2 | 数据校验与序列化 |
| pytest | 8.2 | 自动化测试 |

---

## 参考文档

- [`docs/release-candidate.md`](docs/release-candidate.md) — **RC 指南**：审查报告、启动方式、验证步骤
- [`docs/design-deep-dive.md`](docs/design-deep-dive.md) — **技术深度设计**：RRF / Evidence Binding / HITL / ContextVar / ACL / 权衡分析
- [`docs/architecture.md`](docs/architecture.md) — 模块职责 + LangGraph 流 + 数据流设计
- [`docs/api.md`](docs/api.md) — 完整 API 参考（请求/响应示例）
- [`docs/demo-final-script.md`](docs/demo-final-script.md) — 标准演示脚本（3 场景，含解说词）
- [`docs/platform-extension.md`](docs/platform-extension.md) — 平台扩展指南（工具/来源/MCP/多租户）
- [`docs/project-story.md`](docs/project-story.md) — 项目设计理念与适用场景