完善文档
This commit is contained in:
chenxin committed
1 parent
192ea96eb4
commit
efc08dab5e
82 files changed
+1455
-109
No files matched your search
@@ -54,143 +54,206 @@ live-2d: <https://github.com/stevenjoezhang/live2d-widget>
|
||||
deepseek-herness：<https://github.com/deepseek-ai/deepseek-harness>
|
||||
模型网关设计：<https://github.com/xgpxg/aiway>,<https://github.com/bestruirui/octopus>,<https://github.com/QuantumNous/new-api>,<https://github.com/cita-777/metapi>,<https://github.com/looplj/axonhub>,<https://github.com/dyedd/lens>
|
||||
|
||||
## 完整技术栈
|
||||
## 项目定位
|
||||
|
||||
---
|
||||
本项目是一个面向长期运行与持续演化的 Agent 平台，核心目标是提供统一的 Agent Runtime、认知能力、工具执行、记忆、RAG、MCP、桌面端与基础设施。
|
||||
|
||||
### 前端（TypeScript 主力）
|
||||
核心认知闭环：
|
||||
|
||||
**定位**：浏览器端 UI、状态管理、实时交互
|
||||
**技术选型**：
|
||||
Next.js 16 + React 19 + TypeScript + Tailwind CSS v4 + Zustand/Jotai + shadcn/ui + pnpm
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["感知"] --> B["上下文"]
|
||||
B --> C["记忆"]
|
||||
C --> D["理解"]
|
||||
D --> E["规划与推理"]
|
||||
E --> F["决策"]
|
||||
F --> G["工具 / 行动"]
|
||||
G --> H["环境反馈"]
|
||||
H --> I["反思"]
|
||||
I --> C
|
||||
```
|
||||
|
||||
#### 核心依赖
|
||||
## 必读文档
|
||||
|
||||
- **实时通信**：SSE（主，接收流式文本/事件）/ WebSocket（双向协同场景）
|
||||
- **数据请求**：TanStack Query（服务端状态管理与缓存）+ openapi-fetch（类型安全请求，类型由后端 OpenAPI 生成）
|
||||
- **可视化**：Mermaid（图表/流程图渲染）+ React Flow（流程编排与交互）/ Cytoscape.js（知识图谱交互）
|
||||
- **Markdown 渲染**：react-markdown + remark/rehype 插件体系 + Shiki（代码高亮，支持流式增量解析）
|
||||
- **长列表虚拟滚动**：@tanstack/react-virtual（大量数据高性能渲染）
|
||||
- **表单校验**：React Hook Form + Zod（类型安全的表单验证）
|
||||
- **测试**：Vitest（单元测试）+ Testing Library（组件测试）+ Playwright（E2E 测试）
|
||||
- **代码质量**：ESLint（flat config 格式）+ Prettier + Husky + lint-staged + commitlint
|
||||
开始涉及架构修改前：
|
||||
|
||||
---
|
||||
1. `docs/architecture/overview.md`
|
||||
2. `docs/agent/overview.md`
|
||||
3. `docs/decisions/README.md`
|
||||
|
||||
### BFF（TypeScript + Node.js）
|
||||
涉及具体领域时，必须优先阅读对应领域文档。
|
||||
|
||||
**定位**：前端聚合层、鉴权透传、响应裁剪、SSE/WebSocket 代理、类型安全桥接
|
||||
**技术选型**：
|
||||
Node.js 22 LTS + NestJS / Fastify + TypeScript + Zod + openapi-fetch
|
||||
## 核心工程原则
|
||||
|
||||
#### 核心依赖
|
||||
- 能力与基础设施解耦。
|
||||
- Agent Runtime 不直接绑定具体数据库、向量库、图数据库或对象存储。
|
||||
- 外部能力通过 Tool Registry / MCP 接入。
|
||||
- 长期数据进入 PostgreSQL；Redis 不作为核心业务数据最终持久化层。
|
||||
- VectorStore、GraphStore、FileStorage 必须通过抽象接口访问。
|
||||
- API 以 OpenAPI 3.1 为契约。
|
||||
- 重要架构选择必须通过 ADR 记录。
|
||||
- 不为了技术复杂度而提前引入分布式基础设施。
|
||||
|
||||
- **HTTP 框架**：Fastify（高性能）或 NestJS（模块化结构化）
|
||||
- **聚合/代理**：http-proxy / undici（请求转发与合并）
|
||||
- **鉴权**：JWT + cookie 透传
|
||||
- **日志**：pino（高性能结构化日志）
|
||||
- **配置管理**：dotenv / convict（环境配置校验）
|
||||
- **测试**：Vitest + supertest（API 集成测试）
|
||||
- **代码质量**：ESLint + Prettier + Husky
|
||||
## Repository 结构
|
||||
|
||||
---
|
||||
- `apps/`：客户端与服务应用。
|
||||
- `packages/`：共享库与 SDK。
|
||||
- `services/`：独立基础服务。
|
||||
- `docs/`：架构、设计、规范与 ADR。
|
||||
- `tests/`：跨模块测试与评估。
|
||||
- `scripts/`：开发和运维脚本。
|
||||
|
||||
### 后端核心（Python + uv）
|
||||
## Agent Runtime 规则
|
||||
|
||||
**定位**：业务主力、AI Agent 编排、RAG 检索
|
||||
**技术选型**：
|
||||
Python 3.12+（uv 包管理）+ FastAPI + SQLAlchemy 2.0 + Alembic + Pydantic v2 + httpx + loguru + uvicorn
|
||||
Agent Runtime 是系统核心。
|
||||
|
||||
#### 核心依赖
|
||||
所有 Agent Run 应具有稳定的 `run_id`，并可追踪：
|
||||
|
||||
- **任务队列**：Celery（稳定分布式任务）/ ARQ（轻量级，基于 Redis）
|
||||
- **LLM 接入**：OpenAI SDK / LiteLLM（多厂商统一接口）
|
||||
- **文档解析**：unstructured（多格式文档解析）+ pymupdf（PDF 处理）+ markitdown（Markdown 转换）
|
||||
- **Agent 引擎**：LangGraph（有状态多 Agent 编排）或 自研轻量引擎
|
||||
- **MCP 协议**：自研 MCP Client（stdio/sse 传输，接入第三方 MCP Server）
|
||||
- **记忆系统**：自研三层记忆架构（Redis 短期记忆 + PostgreSQL 长期记忆 + VectorStore 向量记忆）
|
||||
- **规划与推理**：自研 ReAct 循环 + Plan-and-Execute 模式
|
||||
- **工具系统**：自研工具注册表（装饰器注册 + Pydantic 参数校验）+ 内置工具集（文件/网页/向量/图/代码沙箱/数据库/HTTP）
|
||||
- **工具权限控制**：基于 Tauri 能力模型 + RBAC 用户角色
|
||||
- **流式输出**：SSE 事件驱动（text_delta / tool_call / tool_result / agent_thought / finish）
|
||||
- **断点续传**：Redis 缓存中间状态（支持重连恢复）
|
||||
- **向量库抽象层**：自研 VectorStore 接口 → ChromaDB（开发） / PGVector（过渡） / Milvus（生产）
|
||||
- **图数据库抽象层**：自研 GraphStore 接口 → Neo4j（开发） / NebulaGraph（生产）
|
||||
- **文件存储抽象层**：自研 FileStorage 接口 → 本地（开发） / MinIO（自建） / S3（生产）
|
||||
- **安全防护**：LLM Guard（Prompt Injection 检测）+ 自研输出审核（敏感词/隐私脱敏）
|
||||
- **审计日志**：所有工具调用记录（用户 + 时间 + 工具 + 参数 + 结果）
|
||||
- **评测框架**：DeepEval / Ragas（RAG 质量评估）
|
||||
- **调试工具**：自研 Debug Panel（推理链可视化）/ LangSmith（可选）
|
||||
- **测试**：pytest + pytest-asyncio + respx（HTTP Mock）
|
||||
- **代码质量**：Ruff（lint + format）+ mypy + pre-commit
|
||||
`Run -> Plan -> Model Call -> Memory -> Tool Call -> Observation -> Reflection -> Result`
|
||||
|
||||
---
|
||||
Agent 不应把业务逻辑隐含在 Prompt 中；稳定规则、权限和状态应由代码或配置表达。
|
||||
|
||||
### 桌面端（Rust + Tauri）
|
||||
## Memory 规则
|
||||
|
||||
**定位**：桌面客户端外壳、本地文件索引、沙箱执行、本地向量检索、离线能力
|
||||
**技术选型**：
|
||||
Rust（cargo 管理）+ Tauri v2 + tokio + serde + specta（TypeScript 类型导出）
|
||||
采用六类逻辑记忆：
|
||||
|
||||
#### 核心依赖
|
||||
- Working Memory
|
||||
- Episodic Memory
|
||||
- Semantic Memory
|
||||
- Procedural Memory
|
||||
- Social Memory
|
||||
- Identity Memory
|
||||
|
||||
- **本地检索**：tantivy（全文检索）
|
||||
- **沙箱执行**：Tauri 进程隔离 + 权限模型（capabilities 映射为 Agent 工具授权）
|
||||
- **打包分发**：tauri-plugin-updater（自动更新）+ tauri-plugin-store（本地配置存储）
|
||||
- **前端通信**：Tauri commands（同步/异步调用）+ events（双向事件）+ specta（类型安全）
|
||||
- **代码质量**：clippy + rustfmt
|
||||
统一通过 `Memory Manager` 访问。
|
||||
|
||||
---
|
||||
业务代码不得直接依赖 Redis、VectorStore 等具体实现。
|
||||
|
||||
### 高并发 I/O 层（Go）
|
||||
详细设计：`docs/agent/memory.md`
|
||||
|
||||
**定位**：网页抓取集群、API 网关与限流、长连接转发、定时调度、轻量级数据聚合
|
||||
**技术选型**：
|
||||
Go 1.25+（go mod 管理）+ Gin / Echo + colly + goquery + zap + viper
|
||||
## Planning / Reasoning 规则
|
||||
|
||||
#### 核心依赖
|
||||
规划与推理采用多模式架构：
|
||||
|
||||
- **并发控制**：ants（协程池）+ golang.org/x/time/rate（限流器）
|
||||
- **无头浏览器**：chromedp / rod（动态页面渲染抓取）
|
||||
- **配置与服务发现**：viper（配置管理）+ etcd（服务注册与发现，可选）
|
||||
- **可观测性**：OpenTelemetry-Go + Prometheus client
|
||||
- **测试**：testing + testify + httptest
|
||||
- **代码质量**：golangci-lint + gofumpt
|
||||
- ReAct
|
||||
- Plan-and-Execute
|
||||
- Reflection
|
||||
- Self-Correction
|
||||
- Dynamic Replanning
|
||||
|
||||
---
|
||||
详细设计：`docs/agent/planning.md`、`docs/agent/reasoning.md`。
|
||||
|
||||
### 基础设施
|
||||
## Tool 规则
|
||||
|
||||
#### 数据库
|
||||
所有 Agent Tool 必须：
|
||||
|
||||
- **关系数据库**：PostgreSQL 16（主库，支持 pgvector 扩展）
|
||||
- **缓存/消息队列**：Redis 7+（Session / 任务队列 / 限流计数器 / 短期记忆存储）
|
||||
- 注册到 Tool Registry。
|
||||
- 使用结构化参数 Schema。
|
||||
- 经过权限检查。
|
||||
- 具有超时和错误处理。
|
||||
- 记录调用审计。
|
||||
- 返回统一结果结构。
|
||||
|
||||
#### 向量数据库
|
||||
详细设计：`docs/tools/overview.md`
|
||||
|
||||
- **开发/测试**：ChromaDB（轻量快速）
|
||||
- **生产过渡**：PostgreSQL + pgvector（减少运维复杂度）
|
||||
- **大规模生产**：Milvus（分布式向量检索）
|
||||
## MCP 规则
|
||||
|
||||
#### 图数据库
|
||||
MCP 是外部工具和上下文扩展协议。
|
||||
|
||||
- **开发/测试**：Neo4j（社区版，易于上手）
|
||||
- **大规模生产**：NebulaGraph（分布式图数据库，高性能）
|
||||
MCP Tool 必须经过内部 Tool Adapter 和 Permission Layer，不得绕过统一权限体系。
|
||||
|
||||
#### 文件/对象存储
|
||||
详细设计：`docs/mcp/overview.md`
|
||||
|
||||
- **开发环境**：本地文件系统
|
||||
- **自建生产**：MinIO（兼容 S3 协议）
|
||||
- **云生产**：AWS S3 / 阿里云 OSS / 腾讯云 COS
|
||||
## API 规则
|
||||
|
||||
#### 容器
|
||||
- API 使用 OpenAPI 3.1。
|
||||
- FastAPI 负责生成服务端 Schema。
|
||||
- 前端优先使用类型安全客户端。
|
||||
- SSE 用于 Agent 流式事件。
|
||||
- WebSocket 只用于确有双向实时通信需求的场景。
|
||||
- API 错误使用统一错误模型。
|
||||
|
||||
- **容器化**：Docker + Docker Compose（本地开发环境一键编排）
|
||||
详细设计：`docs/api/overview.md`
|
||||
|
||||
#### API 契约
|
||||
## 数据访问规则
|
||||
|
||||
- **规范**：OpenAPI 3.1（单一真源）
|
||||
- **客户端生成**：openapi-generator（生成 TypeScript / Go 客户端）
|
||||
- PostgreSQL：核心业务与长期结构化数据。
|
||||
- Redis：缓存、短期状态、运行态数据。
|
||||
- VectorStore：向量检索。
|
||||
- GraphStore：关系与知识图谱。
|
||||
- FileStorage：对象与文件。
|
||||
- 所有可替换基础设施通过接口隔离。
|
||||
|
||||
## 安全规则
|
||||
|
||||
安全采用纵深防御：
|
||||
|
||||
`Authentication -> RBAC -> Tool Permission -> Sandbox -> Audit`
|
||||
|
||||
Tauri Capabilities 与服务端 RBAC 属于不同安全边界，不得混为一谈。
|
||||
|
||||
必须考虑：
|
||||
|
||||
- Prompt Injection
|
||||
- Secret Leakage
|
||||
- Sensitive Data
|
||||
- Tool Abuse
|
||||
- Sandbox Escape
|
||||
- Auditability
|
||||
|
||||
## 测试规则
|
||||
|
||||
新增能力至少考虑：
|
||||
|
||||
- Unit Test
|
||||
- Integration Test
|
||||
- API Test
|
||||
- Tool Test
|
||||
- Agent Workflow Test
|
||||
|
||||
RAG / Agent 的关键能力必须增加 Evaluation，而不能只依赖普通单元测试。
|
||||
|
||||
## 常用技术约束
|
||||
|
||||
### Python
|
||||
|
||||
Python 3.12+，使用 `uv` 管理依赖；Ruff + mypy。
|
||||
|
||||
### TypeScript
|
||||
|
||||
Next.js + React + TypeScript；pnpm；ESLint + Prettier。
|
||||
|
||||
### Rust
|
||||
|
||||
Tauri v2 + Tokio；rustfmt + clippy。
|
||||
|
||||
### Go
|
||||
|
||||
Go 1.25+；gofumpt + golangci-lint。
|
||||
|
||||
## 文档规则
|
||||
|
||||
架构修改必须同步修改相关 `docs/`。
|
||||
|
||||
改变技术选择或重要架构决策时创建 ADR。
|
||||
|
||||
不要把完整设计复制到 `AGENTS.md`；`AGENTS.md` 只保留必须影响 Agent 行为的规则和导航。
|
||||
|
||||
## 文档导航
|
||||
|
||||
- 总体架构：`docs/architecture/overview.md`
|
||||
- Agent：`docs/agent/overview.md`
|
||||
- Memory：`docs/agent/memory.md`
|
||||
- Planning：`docs/agent/planning.md`
|
||||
- Reasoning：`docs/agent/reasoning.md`
|
||||
- RAG：`docs/rag/overview.md`
|
||||
- Tools：`docs/tools/overview.md`
|
||||
- MCP：`docs/mcp/overview.md`
|
||||
- API：`docs/api/overview.md`
|
||||
- 数据：`docs/data/database.md`
|
||||
- 安全：`docs/security/overview.md`
|
||||
- 基础设施：`docs/infrastructure/development.md`
|
||||
- 测试：`docs/testing/strategy.md`
|
||||
- ADR：`docs/decisions/README.md`
|
||||
|
||||
## 文档设计
|
||||
|
||||
@@ -204,7 +267,6 @@ Go 1.25+（go mod 管理）+ Gin / Echo + colly + goquery + zap + viper
|
||||
Docker 文件放在根目录 `docker/` 下。
|
||||
容器名称以 `hunjing` 开头。
|
||||
Compose 文件不使用顶部 `version` 字段。
|
||||
本地开发默认使用 SQLite 文件数据库，正式环境使用 PostgreSQL，并按需启用 Milvus、Neo4j / NebulaGraph、Redis 和对象存储。
|
||||
|
||||
## 项目目录
|
||||
|
||||
@@ -224,15 +286,7 @@ Compose 文件不使用顶部 `version` 字段。
|
||||
|
||||
### 本地开发（Makefile 统一入口）
|
||||
|
||||
所有本地服务的启动、测试与数据库迁移统一经根目录 Makefile（`make help` 查看全部）：
|
||||
|
||||
```bash
|
||||
make dev-core # 核心三服务并行：灵台 + 神识 + 照壁
|
||||
make dev-backend # 灵台（另有 dev-shenshi / dev-bff / dev-frontend / dev-sandbox / dev-tianmu / dev-yuanqi）
|
||||
make db-upgrade # Alembic 升级到 head（迁移编号 000/001/002…）
|
||||
make db-revision m="说明" # 生成下一号迁移（自动编号 + autogenerate，禁手写哈希 id）
|
||||
make test # 全部测试（backend / shenshi / bff / frontend）
|
||||
```
|
||||
所有本地服务的启动、测试与数据库迁移统一经根目录 Makefile（`make help` 查看全部）
|
||||
|
||||
### Docker
|
||||
|
||||
@@ -242,7 +296,6 @@ make test # 全部测试（backend / shenshi / bff / fronten
|
||||
```bash
|
||||
# 先准备配置（只需一次）
|
||||
cp .env.example .env # 填写 POSTGRES_PASSWORD 与各 *_API_KEY
|
||||
# 模型端点目录经 SHENSHI_ENDPOINTS 配置（见 .env.example 神识段），无需复制 yaml
|
||||
|
||||
# 1) 启动基础设施（首次创建 hunjing-net 网络；Milvus 会自动带起 hunjing-etcd / hunjing-minio）
|
||||
docker compose -f docker/docker-compose.infra.yml up -d
|
||||
|
||||
@@ -6,6 +6,36 @@
|
||||
|
||||
下层文档发现冲突时必须回报并修订，不能以现有代码或当前实现状态覆盖产品定义。
|
||||
|
||||
- `architecture/`：总体架构与系统数据流
|
||||
- `agent/`：Agent Runtime 与认知架构
|
||||
- `rag/`：RAG 与知识系统
|
||||
- `tools/`：工具系统
|
||||
- `mcp/`：MCP 集成
|
||||
- `api/`：API 与流式协议
|
||||
- `data/`：数据库、缓存、向量、图和文件存储
|
||||
- `client/`：Web、BFF、Desktop
|
||||
- `services/`：Go 高并发服务
|
||||
- `security/`：安全设计
|
||||
- `infrastructure/`：部署、容器、可观测性
|
||||
- `testing/`：测试与评估
|
||||
- `decisions/`：架构决策记录
|
||||
|
||||
## 阅读顺序
|
||||
|
||||
新开发者：
|
||||
|
||||
`architecture/overview.md -> agent/overview.md -> 对应领域文档`
|
||||
|
||||
AI Agent：
|
||||
|
||||
`AGENTS.md -> 本目录 -> 对应领域文档 -> ADR`
|
||||
|
||||
## 文档原则
|
||||
|
||||
文档描述系统为什么这样设计、系统如何工作以及修改时需要遵守的边界。
|
||||
|
||||
具体实现应以源码和测试为最终事实来源。
|
||||
|
||||
## 快速阅读
|
||||
|
||||
### 理解产品
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
# Agent
|
||||
|
||||
Agent Runtime 与认知架构文档目录。
|
||||
@@ -0,0 +1,24 @@
|
||||
# Agent Execution
|
||||
|
||||
## 执行阶段
|
||||
|
||||
1. 创建 Run
|
||||
2. 构建上下文
|
||||
3. 召回记忆
|
||||
4. 生成计划
|
||||
5. 执行步骤
|
||||
6. 获取观察
|
||||
7. 验证结果
|
||||
8. 重规划或完成
|
||||
9. 记录经验
|
||||
|
||||
## 长任务
|
||||
|
||||
长任务必须：
|
||||
|
||||
- 持久化状态
|
||||
- 可查询
|
||||
- 可恢复
|
||||
- 可取消
|
||||
- 可超时
|
||||
- 可审计
|
||||
@@ -0,0 +1,67 @@
|
||||
# Agent Memory Architecture
|
||||
|
||||
## 六层记忆
|
||||
|
||||
### Working Memory
|
||||
|
||||
当前上下文、任务状态、临时变量。
|
||||
|
||||
### Episodic Memory
|
||||
|
||||
历史事件、对话、任务经历、重要决策。
|
||||
|
||||
### Semantic Memory
|
||||
|
||||
事实、概念、实体、知识。
|
||||
|
||||
### Procedural Memory
|
||||
|
||||
技能、策略、流程和经验方法。
|
||||
|
||||
### Social Memory
|
||||
|
||||
用户、关系、偏好、交互模式。
|
||||
|
||||
### Identity Memory
|
||||
|
||||
Agent 身份、长期经历、目标、自我认知。
|
||||
|
||||
## Memory Manager
|
||||
|
||||
统一负责：
|
||||
|
||||
`write -> classify -> store -> retrieve -> consolidate -> update -> forget`
|
||||
|
||||
## 存储
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
MemoryManager --> Redis["Working / Runtime State"]
|
||||
MemoryManager --> PostgreSQL["Structured Long-term Memory"]
|
||||
MemoryManager --> VectorStore["Semantic Retrieval"]
|
||||
MemoryManager --> GraphStore["Relationship Memory"]
|
||||
```
|
||||
|
||||
## 重要性
|
||||
|
||||
不是所有对话都进入长期记忆。应结合重要性、稳定性、重复度、未来价值和用户明确意图进行判断。
|
||||
|
||||
## 记忆生命周期
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Experience --> Candidate
|
||||
Candidate --> Evaluate
|
||||
Evaluate --> Consolidate
|
||||
Consolidate --> LongTerm
|
||||
LongTerm --> Retrieve
|
||||
Retrieve --> Update
|
||||
Update --> Forget
|
||||
```
|
||||
|
||||
## 原则
|
||||
|
||||
- 事实和推断分离。
|
||||
- 推断必须标记来源和置信度。
|
||||
- 重要记忆应保留来源和时间。
|
||||
- 记忆更新必须可追踪。
|
||||
@@ -0,0 +1,22 @@
|
||||
# Model System
|
||||
|
||||
## 目标
|
||||
|
||||
统一管理：
|
||||
|
||||
- LLM
|
||||
- Embedding
|
||||
- Reranker
|
||||
- Vision
|
||||
- Speech-to-Text
|
||||
- Text-to-Speech
|
||||
|
||||
## Model Gateway
|
||||
|
||||
Agent Runtime 不直接绑定单一模型供应商。
|
||||
|
||||
统一抽象：
|
||||
|
||||
`Provider -> Model -> Capability -> Request -> Response`
|
||||
|
||||
支持 OpenAI SDK、LiteLLM 及本地模型。
|
||||
@@ -0,0 +1,32 @@
|
||||
# Agent 认知架构
|
||||
|
||||
## 核心闭环
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Perception["感知"] --> Context["上下文"]
|
||||
Context --> Memory["记忆"]
|
||||
Memory --> Understanding["理解"]
|
||||
Understanding --> Planning["规划"]
|
||||
Planning --> Decision["决策"]
|
||||
Decision --> Action["行动"]
|
||||
Action --> Observation["反馈"]
|
||||
Observation --> Reflection["反思"]
|
||||
Reflection --> Learning["学习"]
|
||||
Learning --> Memory
|
||||
```
|
||||
|
||||
## 主要能力
|
||||
|
||||
- Runtime
|
||||
- Memory
|
||||
- Planning
|
||||
- Reasoning
|
||||
- Reflection
|
||||
- Tool Use
|
||||
- Model Use
|
||||
- Learning
|
||||
- Self Model
|
||||
- World Model
|
||||
|
||||
当前阶段重点实现 Runtime、Memory、Planning、Tool、RAG；World Model 与 Self Model 保持可扩展接口。
|
||||
@@ -0,0 +1,51 @@
|
||||
# Planning
|
||||
|
||||
## 目标
|
||||
|
||||
将用户目标转换为可执行、可验证、可恢复的任务计划。
|
||||
|
||||
## 模式
|
||||
|
||||
### Plan-and-Execute
|
||||
|
||||
适合目标明确、步骤较稳定的复杂任务。
|
||||
|
||||
### ReAct
|
||||
|
||||
适合需要根据环境反馈动态决定下一步的任务。
|
||||
|
||||
### Dynamic Replanning
|
||||
|
||||
当计划假设失效、工具失败或新信息出现时重新规划。
|
||||
|
||||
## 闭环
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Goal --> Understand
|
||||
Understand --> Decompose
|
||||
Decompose --> Plan
|
||||
Plan --> Execute
|
||||
Execute --> Observe
|
||||
Observe --> Evaluate
|
||||
Evaluate -->|success| Finish
|
||||
Evaluate -->|failure| Reflect
|
||||
Reflect --> Replan
|
||||
Replan --> Execute
|
||||
```
|
||||
|
||||
## 计划对象
|
||||
|
||||
计划至少应包含：
|
||||
|
||||
- goal
|
||||
- steps
|
||||
- dependencies
|
||||
- expected_output
|
||||
- constraints
|
||||
- status
|
||||
- retry_policy
|
||||
|
||||
## 原则
|
||||
|
||||
计划不是不可变脚本；执行过程中的观察可以触发局部或全局重规划。
|
||||
@@ -0,0 +1,29 @@
|
||||
# Reasoning
|
||||
|
||||
## 推理职责
|
||||
|
||||
- 任务理解
|
||||
- 假设生成
|
||||
- 证据分析
|
||||
- 工具选择
|
||||
- 结果验证
|
||||
- 错误诊断
|
||||
|
||||
## ReAct
|
||||
|
||||
`Thought/Reasoning -> Action -> Observation`
|
||||
|
||||
实际系统不要求暴露模型内部思维链。对外只输出必要的状态、依据和工具事件。
|
||||
|
||||
## Reflection
|
||||
|
||||
反思不是无条件重复推理，应在以下情况触发：
|
||||
|
||||
- 工具失败
|
||||
- 结果与目标不一致
|
||||
- 关键约束未满足
|
||||
- 新信息推翻原假设
|
||||
|
||||
## 验证
|
||||
|
||||
最终结果应尽可能进行结构化验证，而不是只依赖 LLM 自评。
|
||||
@@ -0,0 +1,24 @@
|
||||
# Reflection
|
||||
|
||||
## 目标
|
||||
|
||||
通过执行结果发现错误、总结经验并修正后续行为。
|
||||
|
||||
## 类型
|
||||
|
||||
- Step Reflection：单步骤反思
|
||||
- Run Reflection：一次任务结束后的反思
|
||||
- Experience Consolidation：把经验沉淀为长期记忆
|
||||
- Strategy Reflection：更新策略
|
||||
|
||||
## 原则
|
||||
|
||||
反思必须产生可执行结果，例如：
|
||||
|
||||
- 修改计划
|
||||
- 更换工具
|
||||
- 调整参数
|
||||
- 增加验证
|
||||
- 写入经验
|
||||
|
||||
避免“反思但不改变行为”。
|
||||
@@ -0,0 +1,22 @@
|
||||
# Agent Runtime
|
||||
|
||||
## 职责
|
||||
|
||||
- Agent 生命周期
|
||||
- Session / Run 管理
|
||||
- 上下文组装
|
||||
- 模型调用
|
||||
- Tool 调度
|
||||
- 状态机
|
||||
- 事件发布
|
||||
- 错误恢复
|
||||
- 运行追踪
|
||||
|
||||
## 不负责
|
||||
|
||||
- 具体数据库实现
|
||||
- 具体向量数据库
|
||||
- 前端 UI
|
||||
- 外部服务业务逻辑
|
||||
|
||||
Runtime 应通过接口调用这些能力。
|
||||
@@ -0,0 +1,28 @@
|
||||
# Tool System
|
||||
|
||||
## 架构
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Registry["Tool Registry"] --> Discovery["Discovery"]
|
||||
Discovery --> Permission["Permission"]
|
||||
Permission --> Validation["Schema Validation"]
|
||||
Validation --> Runtime["Execution"]
|
||||
Runtime --> Normalize["Result Normalize"]
|
||||
Normalize --> Audit["Audit"]
|
||||
```
|
||||
|
||||
## Tool 必须具备
|
||||
|
||||
- name
|
||||
- description
|
||||
- input schema
|
||||
- output schema
|
||||
- permission
|
||||
- timeout
|
||||
- retry policy
|
||||
- version
|
||||
|
||||
## 统一原则
|
||||
|
||||
Agent 不直接执行任意外部能力。所有工具调用必须经过 Tool Runtime。
|
||||
@@ -0,0 +1,3 @@
|
||||
# API
|
||||
|
||||
API 契约与协议文档目录。
|
||||
@@ -0,0 +1,7 @@
|
||||
# Authentication
|
||||
|
||||
认证与授权分离。
|
||||
|
||||
认证回答“你是谁”；授权回答“你能做什么”。
|
||||
|
||||
支持的认证方式由部署环境决定，业务代码只依赖统一 Identity Context。
|
||||
@@ -0,0 +1,8 @@
|
||||
# API Conventions
|
||||
|
||||
- REST 资源使用名词。
|
||||
- JSON 使用统一编码。
|
||||
- 时间使用 ISO 8601。
|
||||
- ID 使用稳定唯一标识。
|
||||
- API 版本必须可演进。
|
||||
- 分页、排序、过滤采用统一约定。
|
||||
@@ -0,0 +1,11 @@
|
||||
# API Errors
|
||||
|
||||
统一错误模型：
|
||||
|
||||
- code
|
||||
- message
|
||||
- details
|
||||
- request_id
|
||||
- trace_id
|
||||
|
||||
不要把内部异常堆栈直接返回给用户。
|
||||
@@ -0,0 +1,16 @@
|
||||
# API
|
||||
|
||||
API 使用 OpenAPI 3.1。
|
||||
|
||||
核心领域：
|
||||
|
||||
- Auth
|
||||
- Agent
|
||||
- Session
|
||||
- Run
|
||||
- Task
|
||||
- Memory
|
||||
- Knowledge
|
||||
- Tool
|
||||
- File
|
||||
- MCP
|
||||
@@ -0,0 +1,13 @@
|
||||
# Streaming
|
||||
|
||||
SSE 是 Agent 流式输出默认方案。
|
||||
|
||||
事件至少包含：
|
||||
|
||||
- event_id
|
||||
- run_id
|
||||
- event_type
|
||||
- timestamp
|
||||
- payload
|
||||
|
||||
客户端断线后通过 Last-Event-ID 请求恢复。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Architecture
|
||||
|
||||
总体架构文档目录。详见 `overview.md`、`system.md`、`data-flow.md`、`event-flow.md`、`runtime.md`、`security.md`。
|
||||
@@ -0,0 +1,22 @@
|
||||
# 数据流
|
||||
|
||||
## Agent Run
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Request"] --> B["Create Run"]
|
||||
B --> C["Build Context"]
|
||||
C --> D["Memory Retrieval"]
|
||||
D --> E["Planning"]
|
||||
E --> F["Model"]
|
||||
F --> G["Tool"]
|
||||
G --> H["Observation"]
|
||||
H --> I["Evaluation"]
|
||||
I -->|continue| E
|
||||
I -->|finish| J["Result"]
|
||||
H --> K["Memory Consolidation"]
|
||||
```
|
||||
|
||||
## 数据原则
|
||||
|
||||
短期状态进入 Redis；需要长期保存的数据进入 PostgreSQL；语义检索数据进入 VectorStore；关系型知识进入 GraphStore；二进制内容进入 FileStorage。
|
||||
@@ -0,0 +1,29 @@
|
||||
# 事件流
|
||||
|
||||
## 事件模型
|
||||
|
||||
推荐事件：
|
||||
|
||||
- `run_start`
|
||||
- `run_status`
|
||||
- `text_delta`
|
||||
- `plan_created`
|
||||
- `plan_updated`
|
||||
- `memory_recall`
|
||||
- `tool_call`
|
||||
- `tool_result`
|
||||
- `reflection`
|
||||
- `error`
|
||||
- `finish`
|
||||
|
||||
## 传输
|
||||
|
||||
SSE 是默认 Agent 流式通道；WebSocket 用于双向实时场景。
|
||||
|
||||
事件必须包含：
|
||||
|
||||
- event_id
|
||||
- run_id
|
||||
- event_type
|
||||
- timestamp
|
||||
- payload
|
||||
@@ -0,0 +1,50 @@
|
||||
# 总体架构
|
||||
|
||||
## 目标
|
||||
|
||||
构建一个可长期运行、可扩展、可观测、可替换基础设施的 Agent 平台。
|
||||
|
||||
## 分层
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U["User / Environment"] --> C["Web / Desktop"]
|
||||
C --> B["BFF / API"]
|
||||
B --> A["Agent Runtime"]
|
||||
A --> M["Memory"]
|
||||
A --> P["Planning & Reasoning"]
|
||||
A --> T["Tool Runtime"]
|
||||
A --> R["RAG"]
|
||||
A --> L["Model Gateway"]
|
||||
T --> X["MCP / External Tools"]
|
||||
A --> E["Event System"]
|
||||
M --> D["Data Layer"]
|
||||
R --> D
|
||||
D --> PG["PostgreSQL"]
|
||||
D --> RD["Redis"]
|
||||
D --> VS["VectorStore"]
|
||||
D --> GS["GraphStore"]
|
||||
D --> FS["FileStorage"]
|
||||
```
|
||||
|
||||
## 核心原则
|
||||
|
||||
1. Agent 能力与基础设施解耦。
|
||||
2. 外部能力通过统一 Tool Runtime 接入。
|
||||
3. 长任务必须可观测、可恢复。
|
||||
4. 所有关键执行路径必须可审计。
|
||||
5. 采用渐进式基础设施。
|
||||
|
||||
## 技术栈
|
||||
|
||||
Web：Next.js 16 / React 19 / TypeScript。
|
||||
|
||||
BFF：Node.js / TypeScript。
|
||||
|
||||
Agent Runtime：Python 3.12+ / FastAPI。
|
||||
|
||||
Desktop：Rust / Tauri v2。
|
||||
|
||||
高并发 I/O：Go 1.25+。
|
||||
|
||||
数据：PostgreSQL / Redis / VectorStore / GraphStore / Object Storage。
|
||||
@@ -0,0 +1,31 @@
|
||||
# Runtime 架构
|
||||
|
||||
Agent Runtime 负责生命周期管理，不直接承担所有业务能力。
|
||||
|
||||
核心对象：
|
||||
|
||||
- Agent
|
||||
- Session
|
||||
- Run
|
||||
- Task
|
||||
- Plan
|
||||
- Step
|
||||
- ToolCall
|
||||
- Observation
|
||||
- Memory
|
||||
- Result
|
||||
|
||||
生命周期：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Created
|
||||
Created --> Running
|
||||
Running --> Waiting
|
||||
Waiting --> Running
|
||||
Running --> Completed
|
||||
Running --> Failed
|
||||
Failed --> Retrying
|
||||
Retrying --> Running
|
||||
Completed --> [*]
|
||||
```
|
||||
@@ -0,0 +1,17 @@
|
||||
# 架构安全边界
|
||||
|
||||
安全边界：
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
User --> Auth
|
||||
Auth --> RBAC
|
||||
RBAC --> ToolPermission
|
||||
ToolPermission --> Sandbox
|
||||
Sandbox --> Execution
|
||||
Execution --> Audit
|
||||
```
|
||||
|
||||
Tauri Capabilities 保护桌面本地能力；服务端 RBAC 和 Tool Permission 控制用户及 Agent 的服务能力。
|
||||
|
||||
禁止把任何单一机制视为完整安全方案。
|
||||
@@ -0,0 +1,32 @@
|
||||
# 系统架构
|
||||
|
||||
## 核心模块
|
||||
|
||||
- Client
|
||||
- BFF
|
||||
- Agent Runtime
|
||||
- Model Gateway
|
||||
- Memory Manager
|
||||
- Planning Engine
|
||||
- Tool Runtime
|
||||
- RAG
|
||||
- Event System
|
||||
- Data Layer
|
||||
- Observability
|
||||
|
||||
## 调用关系
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client --> BFF
|
||||
BFF --> Runtime
|
||||
Runtime --> Model
|
||||
Runtime --> Memory
|
||||
Runtime --> Planner
|
||||
Planner --> Tools
|
||||
Tools --> External
|
||||
Runtime --> Events
|
||||
Runtime --> Observability
|
||||
```
|
||||
|
||||
模块之间优先使用明确接口，不允许跨层直接访问内部实现。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Client
|
||||
|
||||
Web、BFF、Desktop 文档目录。
|
||||
@@ -0,0 +1,13 @@
|
||||
# BFF
|
||||
|
||||
BFF 是前端聚合与协议适配层。
|
||||
|
||||
职责：
|
||||
|
||||
- API 聚合
|
||||
- SSE / WebSocket 代理
|
||||
- 类型桥接
|
||||
- 响应裁剪
|
||||
- 前端专用数据转换
|
||||
|
||||
BFF 不承载 Agent 核心业务逻辑。
|
||||
@@ -0,0 +1,16 @@
|
||||
# Desktop
|
||||
|
||||
Rust + Tauri v2。
|
||||
|
||||
能力：
|
||||
|
||||
- 本地文件
|
||||
- 本地索引
|
||||
- 本地全文搜索
|
||||
- 本地工具
|
||||
- Sandbox
|
||||
- Offline
|
||||
|
||||
Tantivy 用于本地全文检索。
|
||||
|
||||
Tauri Capabilities 用于限制本地系统访问。
|
||||
@@ -0,0 +1,17 @@
|
||||
# Web Client
|
||||
|
||||
Next.js 16 + React 19 + TypeScript。
|
||||
|
||||
核心：
|
||||
|
||||
- TanStack Query
|
||||
- Zustand/Jotai
|
||||
- shadcn/ui
|
||||
- Tailwind CSS
|
||||
- Mermaid
|
||||
- React Flow
|
||||
- Cytoscape.js
|
||||
- react-markdown
|
||||
- Shiki
|
||||
- react-hook-form
|
||||
- Zod
|
||||
@@ -0,0 +1,3 @@
|
||||
# Data
|
||||
|
||||
数据层文档目录。
|
||||
@@ -0,0 +1,18 @@
|
||||
# PostgreSQL
|
||||
|
||||
PostgreSQL 是主关系数据库。
|
||||
|
||||
负责：
|
||||
|
||||
- 业务数据
|
||||
- 用户
|
||||
- Session
|
||||
- Run
|
||||
- Task
|
||||
- 长期记忆
|
||||
- 审计
|
||||
- 元数据
|
||||
|
||||
SQLAlchemy 2.0 + Alembic。
|
||||
|
||||
数据库 Schema 是持久化契约，重大变化必须通过 migration。
|
||||
@@ -0,0 +1,11 @@
|
||||
# FileStorage
|
||||
|
||||
定义统一 `FileStorage` 接口。
|
||||
|
||||
实现：
|
||||
|
||||
- Local File System
|
||||
- MinIO
|
||||
- S3 / OSS / COS
|
||||
|
||||
业务代码不得直接拼接具体对象存储 SDK。
|
||||
@@ -0,0 +1,10 @@
|
||||
# GraphStore
|
||||
|
||||
定义统一 `GraphStore` 接口。
|
||||
|
||||
实现：
|
||||
|
||||
- Neo4j：开发 / 测试
|
||||
- NebulaGraph：大规模生产
|
||||
|
||||
主要用于知识图谱、实体关系、复杂多跳关系。
|
||||
@@ -0,0 +1,13 @@
|
||||
# Redis
|
||||
|
||||
Redis 负责高频、短生命周期数据：
|
||||
|
||||
- Cache
|
||||
- Working Memory
|
||||
- Session State
|
||||
- Task Runtime State
|
||||
- Rate Limit
|
||||
- Distributed Lock
|
||||
- Event Buffer
|
||||
|
||||
Redis 数据默认不作为核心业务数据唯一来源。
|
||||
@@ -0,0 +1,11 @@
|
||||
# VectorStore
|
||||
|
||||
定义统一 `VectorStore` 接口。
|
||||
|
||||
实现：
|
||||
|
||||
- ChromaDB：开发
|
||||
- PostgreSQL + pgvector：中小规模生产
|
||||
- Milvus：大规模生产
|
||||
|
||||
上层 Memory 与 RAG 不依赖具体实现。
|
||||
@@ -0,0 +1,17 @@
|
||||
# ADR-001: Agent Runtime
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Agent 需要统一管理 Run、Plan、Tool、Memory、Model 和 Event。
|
||||
|
||||
## Decision
|
||||
|
||||
采用统一 Agent Runtime 抽象。复杂有状态工作流可使用 LangGraph；轻量执行路径保留自研 Runtime 的演进空间。
|
||||
|
||||
## Consequences
|
||||
|
||||
Agent 能力与具体编排框架解耦，但需要维护统一领域模型。
|
||||
@@ -0,0 +1,21 @@
|
||||
# ADR-002: Memory Architecture
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
长期 Agent 需要区分短期上下文、事件、知识、技能、关系和身份。
|
||||
|
||||
## Decision
|
||||
|
||||
采用六类逻辑记忆：
|
||||
|
||||
Working / Episodic / Semantic / Procedural / Social / Identity。
|
||||
|
||||
通过 Memory Manager 统一访问；底层采用 Redis、PostgreSQL、VectorStore 和 GraphStore。
|
||||
|
||||
## Consequences
|
||||
|
||||
记忆语义与存储实现解耦，但需要维护 Memory Consolidation 与 Retrieval 策略。
|
||||
@@ -0,0 +1,17 @@
|
||||
# ADR-003: Vector Store
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
建立 VectorStore 抽象：
|
||||
|
||||
- 开发：ChromaDB
|
||||
- 中小生产：PostgreSQL + pgvector
|
||||
- 大规模：Milvus
|
||||
|
||||
## Rationale
|
||||
|
||||
优先降低早期运维成本，同时保留大规模演进路径。
|
||||
@@ -0,0 +1,16 @@
|
||||
# ADR-004: Graph Store
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Decision
|
||||
|
||||
建立 GraphStore 抽象：
|
||||
|
||||
- 开发：Neo4j
|
||||
- 大规模：NebulaGraph
|
||||
|
||||
## Rationale
|
||||
|
||||
知识图谱与复杂关系查询需要独立抽象。
|
||||
@@ -0,0 +1,17 @@
|
||||
# ADR-005: Model Gateway
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Agent 不应绑定单一模型厂商。
|
||||
|
||||
## Decision
|
||||
|
||||
建立统一 Model Gateway，支持 OpenAI SDK、LiteLLM 及本地模型。
|
||||
|
||||
## Consequences
|
||||
|
||||
增加模型抽象层，但能够实现模型切换、能力路由和供应商解耦。
|
||||
@@ -0,0 +1,49 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
ADR 用于记录重要架构决策。
|
||||
|
||||
创建 ADR 的场景：
|
||||
|
||||
- 技术栈替换
|
||||
- 核心架构改变
|
||||
- 数据模型改变
|
||||
- Agent Runtime 机制改变
|
||||
- 安全边界改变
|
||||
- 基础设施选型改变
|
||||
|
||||
建议状态：
|
||||
|
||||
- Proposed
|
||||
- Accepted
|
||||
- Superseded
|
||||
- Deprecated
|
||||
|
||||
模板：
|
||||
|
||||
```text
|
||||
# ADR-XXX: Title
|
||||
|
||||
## Status
|
||||
|
||||
Proposed
|
||||
|
||||
## Context
|
||||
|
||||
为什么需要做这个决策？
|
||||
|
||||
## Decision
|
||||
|
||||
最终决定是什么？
|
||||
|
||||
## Alternatives
|
||||
|
||||
考虑过哪些方案？
|
||||
|
||||
## Consequences
|
||||
|
||||
优点、缺点、风险。
|
||||
|
||||
## Related Documents
|
||||
|
||||
相关文档。
|
||||
```
|
||||
@@ -0,0 +1,3 @@
|
||||
# Infrastructure
|
||||
|
||||
基础设施文档目录。
|
||||
@@ -0,0 +1,7 @@
|
||||
# Deployment
|
||||
|
||||
采用渐进式部署：
|
||||
|
||||
`Docker Compose -> Container Platform -> Kubernetes`
|
||||
|
||||
是否进入 Kubernetes 由服务数量、可用性、扩缩容和团队运维能力决定，而不是技术偏好。
|
||||
@@ -0,0 +1,12 @@
|
||||
# Development Environment
|
||||
|
||||
推荐：
|
||||
|
||||
- Docker Compose
|
||||
- PostgreSQL
|
||||
- Redis
|
||||
- MinIO
|
||||
- VectorStore
|
||||
- GraphStore
|
||||
|
||||
Python 使用 uv；Node 使用 pnpm；Rust 使用 Cargo；Go 使用 Go Modules。
|
||||
@@ -0,0 +1,10 @@
|
||||
# Docker
|
||||
|
||||
Docker Compose 用于本地多服务编排。
|
||||
|
||||
原则：
|
||||
|
||||
- 服务配置环境化。
|
||||
- Secret 不提交 Git。
|
||||
- 数据卷用于开发持久化。
|
||||
- 每个服务保持单一职责。
|
||||
@@ -0,0 +1,13 @@
|
||||
# Observability
|
||||
|
||||
统一采用 OpenTelemetry 思路。
|
||||
|
||||
三类信号：
|
||||
|
||||
- Logs
|
||||
- Metrics
|
||||
- Traces
|
||||
|
||||
Agent 特有 Trace：
|
||||
|
||||
`Run -> Plan -> Model -> Memory -> Tool -> Observation -> Reflection`
|
||||
@@ -0,0 +1,13 @@
|
||||
# Scaling
|
||||
|
||||
扩展顺序优先：
|
||||
|
||||
1. 优化单体 Agent Runtime。
|
||||
2. 异步化长任务。
|
||||
3. 分离高并发 I/O。
|
||||
4. 增加缓存。
|
||||
5. 数据库读写优化。
|
||||
6. 按瓶颈拆分服务。
|
||||
7. 最后引入更复杂的分布式基础设施。
|
||||
|
||||
避免过早微服务化。
|
||||
@@ -0,0 +1,3 @@
|
||||
# MCP
|
||||
|
||||
MCP 集成文档目录。
|
||||
@@ -0,0 +1,16 @@
|
||||
# MCP Client
|
||||
|
||||
支持：
|
||||
|
||||
- stdio
|
||||
- SSE
|
||||
|
||||
职责：
|
||||
|
||||
- Server connection
|
||||
- Capability discovery
|
||||
- Tool discovery
|
||||
- Schema conversion
|
||||
- Invocation
|
||||
- Timeout
|
||||
- Error handling
|
||||
@@ -0,0 +1,9 @@
|
||||
# MCP
|
||||
|
||||
MCP 用于连接外部工具与上下文服务。
|
||||
|
||||
内部架构：
|
||||
|
||||
`MCP Client -> Transport -> MCP Server -> Tool Adapter -> Tool Runtime`
|
||||
|
||||
MCP Server 提供的能力不能绕过内部权限和审计系统。
|
||||
@@ -0,0 +1,12 @@
|
||||
# MCP Security
|
||||
|
||||
外部 MCP Server 默认视为不可信边界。
|
||||
|
||||
必须：
|
||||
|
||||
- 显式授权
|
||||
- 限制工具
|
||||
- 限制资源
|
||||
- 校验输入
|
||||
- 记录调用
|
||||
- 限制网络和文件权限
|
||||
@@ -0,0 +1,9 @@
|
||||
# MCP Tool Adapter
|
||||
|
||||
MCP Tool 应转换为内部统一 Tool Model。
|
||||
|
||||
映射：
|
||||
|
||||
`MCP Tool Schema -> Internal Tool Schema -> Permission -> Runtime`
|
||||
|
||||
这样 Agent 无需知道工具来自 MCP 还是内部注册表。
|
||||
@@ -0,0 +1,10 @@
|
||||
# MCP Transport
|
||||
|
||||
Transport 只负责通信，不负责业务权限。
|
||||
|
||||
支持：
|
||||
|
||||
- stdio：本地进程
|
||||
- SSE：远程流式通信
|
||||
|
||||
未来可根据 MCP 生态支持情况扩展其他传输方式。
|
||||
@@ -0,0 +1,3 @@
|
||||
# RAG
|
||||
|
||||
RAG 与知识系统文档目录。
|
||||
@@ -0,0 +1,16 @@
|
||||
# Chunking
|
||||
|
||||
## 原则
|
||||
|
||||
优先保持语义完整性，而不是机械固定长度切分。
|
||||
|
||||
考虑：
|
||||
|
||||
- 标题层级
|
||||
- 段落
|
||||
- 代码块
|
||||
- 表格
|
||||
- 文档结构
|
||||
- Token 长度
|
||||
|
||||
Chunk 必须携带可追溯 metadata。
|
||||
@@ -0,0 +1,12 @@
|
||||
# Embedding
|
||||
|
||||
Embedding 用于把文本、实体或其他内容映射到向量空间。
|
||||
|
||||
要求：
|
||||
|
||||
- 明确模型版本
|
||||
- 明确维度
|
||||
- 保存模型标识
|
||||
- 模型变更时考虑重建索引
|
||||
|
||||
Embedding 与业务代码通过统一接口隔离。
|
||||
@@ -0,0 +1,13 @@
|
||||
# RAG Evaluation
|
||||
|
||||
评估至少覆盖：
|
||||
|
||||
- Recall
|
||||
- Precision
|
||||
- MRR
|
||||
- NDCG
|
||||
- Context Relevance
|
||||
- Answer Faithfulness
|
||||
- Citation / Source Accuracy
|
||||
|
||||
评估集应版本化，模型、Embedding、Chunking 或检索策略发生重要变化时重新评估。
|
||||
@@ -0,0 +1,13 @@
|
||||
# RAG Ingestion
|
||||
|
||||
流程：
|
||||
|
||||
`File -> Parse -> Normalize -> Chunk -> Metadata -> Embedding -> Index`
|
||||
|
||||
解析工具：
|
||||
|
||||
- unstructured
|
||||
- PyMuPDF
|
||||
- MarkItDown
|
||||
|
||||
每个 chunk 应保留来源、文档 ID、位置和版本信息。
|
||||
@@ -0,0 +1,29 @@
|
||||
# RAG
|
||||
|
||||
## 架构
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Query --> Understanding
|
||||
Understanding --> BM25
|
||||
Understanding --> Vector
|
||||
Understanding --> Graph
|
||||
BM25 --> Fusion
|
||||
Vector --> Fusion
|
||||
Graph --> Fusion
|
||||
Fusion --> Reranker
|
||||
Reranker --> Compression
|
||||
Compression --> LLM
|
||||
```
|
||||
|
||||
## 检索
|
||||
|
||||
采用 Hybrid Retrieval：
|
||||
|
||||
- Keyword
|
||||
- BM25
|
||||
- Vector
|
||||
- Graph
|
||||
- Metadata Filter
|
||||
|
||||
最终通过 Reranker 与 Context Compression 提高上下文质量。
|
||||
@@ -0,0 +1,9 @@
|
||||
# Reranking
|
||||
|
||||
Reranker 用于对候选结果进行二次相关性排序。
|
||||
|
||||
典型流程：
|
||||
|
||||
`Recall -> Candidate Set -> Reranker -> Top K`
|
||||
|
||||
Reranker 不是召回器，不能替代低成本高召回率的第一阶段检索。
|
||||
@@ -0,0 +1,12 @@
|
||||
# Retrieval
|
||||
|
||||
支持：
|
||||
|
||||
- BM25
|
||||
- Vector Search
|
||||
- Graph Search
|
||||
- Metadata Filter
|
||||
|
||||
推荐采用多路召回后统一融合。
|
||||
|
||||
检索必须保留 source metadata，确保最终上下文可追溯。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Security
|
||||
|
||||
安全体系文档目录。
|
||||
@@ -0,0 +1,15 @@
|
||||
# Audit
|
||||
|
||||
重要操作必须可审计：
|
||||
|
||||
- user
|
||||
- run_id
|
||||
- tool
|
||||
- timestamp
|
||||
- input metadata
|
||||
- output metadata
|
||||
- permission decision
|
||||
- result
|
||||
- error
|
||||
|
||||
敏感内容应脱敏。
|
||||
@@ -0,0 +1,7 @@
|
||||
# Authentication
|
||||
|
||||
统一产生 Identity Context。
|
||||
|
||||
业务层不应自己解析认证协议。
|
||||
|
||||
认证方式由部署环境决定，核心系统依赖稳定的用户身份接口。
|
||||
@@ -0,0 +1,7 @@
|
||||
# Authorization
|
||||
|
||||
采用 RBAC + Tool Permission + Resource Permission。
|
||||
|
||||
权限检查应尽可能靠近实际资源访问点。
|
||||
|
||||
默认拒绝，显式授权。
|
||||
@@ -0,0 +1,14 @@
|
||||
# Security
|
||||
|
||||
采用纵深防御：
|
||||
|
||||
`Identity -> Authentication -> Authorization -> Tool Permission -> Sandbox -> Audit`
|
||||
|
||||
重点防护：
|
||||
|
||||
- Prompt Injection
|
||||
- Tool Abuse
|
||||
- Secret Leakage
|
||||
- Sensitive Data
|
||||
- Sandbox Escape
|
||||
- Supply Chain Risk
|
||||
@@ -0,0 +1,11 @@
|
||||
# Prompt Injection
|
||||
|
||||
防护采用多层策略：
|
||||
|
||||
1. 外部内容标记为不可信数据。
|
||||
2. 工具调用不由文本指令直接决定权限。
|
||||
3. Tool Permission 独立于 LLM 输出。
|
||||
4. 高风险操作要求额外确认或策略。
|
||||
5. 对工具结果进行来源和内容分类。
|
||||
|
||||
LLM Guard 等组件只是其中一层。
|
||||
@@ -0,0 +1,19 @@
|
||||
# Sandbox
|
||||
|
||||
高风险执行能力必须隔离。
|
||||
|
||||
包括：
|
||||
|
||||
- Code
|
||||
- Shell
|
||||
- Browser
|
||||
- File System
|
||||
|
||||
限制：
|
||||
|
||||
- CPU
|
||||
- Memory
|
||||
- Disk
|
||||
- Network
|
||||
- Process
|
||||
- Timeout
|
||||
@@ -0,0 +1,3 @@
|
||||
# Services
|
||||
|
||||
Go 高并发服务文档目录。
|
||||
@@ -0,0 +1,15 @@
|
||||
# Go Services
|
||||
|
||||
Go 服务负责高并发 I/O，不承担核心 Agent 认知逻辑。
|
||||
|
||||
适用：
|
||||
|
||||
- Web Crawler
|
||||
- API Gateway
|
||||
- Rate Limiting
|
||||
- Long Connection Proxy
|
||||
- Data Aggregation
|
||||
|
||||
技术：
|
||||
|
||||
Go 1.25+、Gin/Echo、Colly、goquery、zap、Viper、OpenTelemetry。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Testing
|
||||
|
||||
测试与评估文档目录。
|
||||
@@ -0,0 +1,13 @@
|
||||
# Agent Evaluation
|
||||
|
||||
评估维度：
|
||||
|
||||
- Task Success
|
||||
- Tool Selection
|
||||
- Plan Quality
|
||||
- Recovery
|
||||
- Hallucination
|
||||
- Cost
|
||||
- Latency
|
||||
|
||||
评估数据集需要版本化。
|
||||
@@ -0,0 +1,13 @@
|
||||
# Integration Test
|
||||
|
||||
覆盖：
|
||||
|
||||
- PostgreSQL
|
||||
- Redis
|
||||
- VectorStore
|
||||
- GraphStore
|
||||
- FileStorage
|
||||
- MCP
|
||||
- Tool Runtime
|
||||
|
||||
外部服务优先使用隔离测试环境或 Mock。
|
||||
@@ -0,0 +1,13 @@
|
||||
# RAG Evaluation
|
||||
|
||||
评估：
|
||||
|
||||
- Retrieval Recall
|
||||
- MRR
|
||||
- NDCG
|
||||
- Context Relevance
|
||||
- Faithfulness
|
||||
- Answer Accuracy
|
||||
- Source Accuracy
|
||||
|
||||
模型、Embedding、Chunking、Retriever 变化时应重新运行基准集。
|
||||
@@ -0,0 +1,18 @@
|
||||
# Testing Strategy
|
||||
|
||||
测试层次：
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
Unit --> Integration
|
||||
Integration --> API
|
||||
API --> Workflow
|
||||
Workflow --> Evaluation
|
||||
Evaluation --> E2E
|
||||
```
|
||||
|
||||
Agent 系统除了传统测试，还必须建立：
|
||||
|
||||
- Agent Evaluation
|
||||
- RAG Evaluation
|
||||
- Tool Reliability Evaluation
|
||||
@@ -0,0 +1,12 @@
|
||||
# Unit Test
|
||||
|
||||
单元测试重点：
|
||||
|
||||
- Domain Logic
|
||||
- Planner
|
||||
- Memory Manager
|
||||
- Tool Schema
|
||||
- Permission
|
||||
- Data Transformation
|
||||
|
||||
避免在单元测试中真实调用外部 LLM 或第三方 API。
|
||||
@@ -0,0 +1,3 @@
|
||||
# Tools
|
||||
|
||||
工具系统文档目录。
|
||||
@@ -0,0 +1,15 @@
|
||||
# Built-in Tools
|
||||
|
||||
初始工具类别：
|
||||
|
||||
- File
|
||||
- HTTP
|
||||
- Web
|
||||
- Database
|
||||
- Vector
|
||||
- Graph
|
||||
- Code Sandbox
|
||||
- Shell
|
||||
- Search
|
||||
|
||||
工具必须保持单一职责，复杂业务流程应通过 Agent Workflow 组合，而不是制作超大工具。
|
||||
@@ -0,0 +1,19 @@
|
||||
# Tools
|
||||
|
||||
Tool System 是 Agent 与外部世界之间的执行边界。
|
||||
|
||||
核心组件：
|
||||
|
||||
- Registry
|
||||
- Discovery
|
||||
- Permission
|
||||
- Validation
|
||||
- Runtime
|
||||
- Audit
|
||||
|
||||
工具来源：
|
||||
|
||||
- Built-in
|
||||
- MCP
|
||||
- Local Desktop
|
||||
- External API
|
||||
@@ -0,0 +1,12 @@
|
||||
# Tool Permissions
|
||||
|
||||
权限至少区分：
|
||||
|
||||
- User Permission
|
||||
- Agent Permission
|
||||
- Tool Permission
|
||||
- Resource Permission
|
||||
|
||||
采用最小权限原则。
|
||||
|
||||
权限检查必须发生在 Tool 执行之前。
|
||||
@@ -0,0 +1,14 @@
|
||||
# Tool Registry
|
||||
|
||||
注册信息：
|
||||
|
||||
- name
|
||||
- version
|
||||
- description
|
||||
- schema
|
||||
- permissions
|
||||
- timeout
|
||||
- retry
|
||||
- tags
|
||||
|
||||
Registry 支持发现、版本控制和能力过滤。
|
||||
@@ -0,0 +1,14 @@
|
||||
# Tool Sandbox
|
||||
|
||||
代码执行、Shell、文件系统等高风险工具必须运行在受控环境。
|
||||
|
||||
安全目标：
|
||||
|
||||
- 文件隔离
|
||||
- 网络限制
|
||||
- 资源限制
|
||||
- 超时
|
||||
- 进程隔离
|
||||
- 输出限制
|
||||
|
||||
桌面端使用 Tauri Capabilities 控制本地系统能力；服务端使用独立 Sandbox。
|
||||
Reference in new issue
Block a user