From efc08dab5e74c14606c8d570a38c942708c52c28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E6=AD=86?= <2685475410@qq.com> Date: Tue, 22 Sep 2026 10:58:39 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 271 +++++++++++------- docs/README.md | 30 ++ docs/agent/README.md | 3 + docs/agent/execution.md | 24 ++ docs/agent/memory.md | 67 +++++ docs/agent/model-system.md | 22 ++ docs/agent/overview.md | 32 +++ docs/agent/planning.md | 51 ++++ docs/agent/reasoning.md | 29 ++ docs/agent/reflection.md | 24 ++ docs/agent/runtime.md | 22 ++ docs/agent/tool-system.md | 28 ++ docs/api/README.md | 3 + docs/api/authentication.md | 7 + docs/api/conventions.md | 8 + docs/api/errors.md | 11 + docs/api/overview.md | 16 ++ docs/api/streaming.md | 13 + docs/architecture/README.md | 3 + docs/architecture/data-flow.md | 22 ++ docs/architecture/event-flow.md | 29 ++ docs/architecture/overview.md | 50 ++++ docs/architecture/runtime.md | 31 ++ docs/architecture/security.md | 17 ++ docs/architecture/system.md | 32 +++ docs/client/README.md | 3 + docs/client/bff.md | 13 + docs/client/desktop.md | 16 ++ docs/client/web.md | 17 ++ docs/data/README.md | 3 + docs/data/database.md | 18 ++ docs/data/file-storage.md | 11 + docs/data/graph-store.md | 10 + docs/data/redis.md | 13 + docs/data/vector-store.md | 11 + docs/decisions/ADR-001-agent-runtime.md | 17 ++ docs/decisions/ADR-002-memory-architecture.md | 21 ++ docs/decisions/ADR-003-vector-store.md | 17 ++ docs/decisions/ADR-004-graph-store.md | 16 ++ docs/decisions/ADR-005-model-gateway.md | 17 ++ docs/decisions/README.md | 49 ++++ docs/infrastructure/README.md | 3 + docs/infrastructure/deployment.md | 7 + docs/infrastructure/development.md | 12 + docs/infrastructure/docker.md | 10 + docs/infrastructure/observability.md | 13 + docs/infrastructure/scaling.md | 13 + docs/mcp/README.md | 3 + docs/mcp/client.md | 16 ++ docs/mcp/overview.md | 9 + docs/mcp/security.md | 12 + docs/mcp/tool-adapter.md | 9 + docs/mcp/transport.md | 10 + docs/rag/README.md | 3 + docs/rag/chunking.md | 16 ++ docs/rag/embedding.md | 12 + docs/rag/evaluation.md | 13 + docs/rag/ingestion.md | 13 + docs/rag/overview.md | 29 ++ docs/rag/reranking.md | 9 + docs/rag/retrieval.md | 12 + docs/security/README.md | 3 + docs/security/audit.md | 15 + docs/security/authentication.md | 7 + docs/security/authorization.md | 7 + docs/security/overview.md | 14 + docs/security/prompt-injection.md | 11 + docs/security/sandbox.md | 19 ++ docs/services/README.md | 3 + docs/services/go-services.md | 15 + docs/testing/README.md | 3 + docs/testing/agent-evaluation.md | 13 + docs/testing/integration.md | 13 + docs/testing/rag-evaluation.md | 13 + docs/testing/strategy.md | 18 ++ docs/testing/unit.md | 12 + docs/tools/README.md | 3 + docs/tools/built-in-tools.md | 15 + docs/tools/overview.md | 19 ++ docs/tools/permissions.md | 12 + docs/tools/registry.md | 14 + docs/tools/sandbox.md | 14 + 82 files changed, 1455 insertions(+), 109 deletions(-) create mode 100644 docs/agent/README.md create mode 100644 docs/agent/execution.md create mode 100644 docs/agent/memory.md create mode 100644 docs/agent/model-system.md create mode 100644 docs/agent/overview.md create mode 100644 docs/agent/planning.md create mode 100644 docs/agent/reasoning.md create mode 100644 docs/agent/reflection.md create mode 100644 docs/agent/runtime.md create mode 100644 docs/agent/tool-system.md create mode 100644 docs/api/README.md create mode 100644 docs/api/authentication.md create mode 100644 docs/api/conventions.md create mode 100644 docs/api/errors.md create mode 100644 docs/api/overview.md create mode 100644 docs/api/streaming.md create mode 100644 docs/architecture/README.md create mode 100644 docs/architecture/data-flow.md create mode 100644 docs/architecture/event-flow.md create mode 100644 docs/architecture/overview.md create mode 100644 docs/architecture/runtime.md create mode 100644 docs/architecture/security.md create mode 100644 docs/architecture/system.md create mode 100644 docs/client/README.md create mode 100644 docs/client/bff.md create mode 100644 docs/client/desktop.md create mode 100644 docs/client/web.md create mode 100644 docs/data/README.md create mode 100644 docs/data/database.md create mode 100644 docs/data/file-storage.md create mode 100644 docs/data/graph-store.md create mode 100644 docs/data/redis.md create mode 100644 docs/data/vector-store.md create mode 100644 docs/decisions/ADR-001-agent-runtime.md create mode 100644 docs/decisions/ADR-002-memory-architecture.md create mode 100644 docs/decisions/ADR-003-vector-store.md create mode 100644 docs/decisions/ADR-004-graph-store.md create mode 100644 docs/decisions/ADR-005-model-gateway.md create mode 100644 docs/decisions/README.md create mode 100644 docs/infrastructure/README.md create mode 100644 docs/infrastructure/deployment.md create mode 100644 docs/infrastructure/development.md create mode 100644 docs/infrastructure/docker.md create mode 100644 docs/infrastructure/observability.md create mode 100644 docs/infrastructure/scaling.md create mode 100644 docs/mcp/README.md create mode 100644 docs/mcp/client.md create mode 100644 docs/mcp/overview.md create mode 100644 docs/mcp/security.md create mode 100644 docs/mcp/tool-adapter.md create mode 100644 docs/mcp/transport.md create mode 100644 docs/rag/README.md create mode 100644 docs/rag/chunking.md create mode 100644 docs/rag/embedding.md create mode 100644 docs/rag/evaluation.md create mode 100644 docs/rag/ingestion.md create mode 100644 docs/rag/overview.md create mode 100644 docs/rag/reranking.md create mode 100644 docs/rag/retrieval.md create mode 100644 docs/security/README.md create mode 100644 docs/security/audit.md create mode 100644 docs/security/authentication.md create mode 100644 docs/security/authorization.md create mode 100644 docs/security/overview.md create mode 100644 docs/security/prompt-injection.md create mode 100644 docs/security/sandbox.md create mode 100644 docs/services/README.md create mode 100644 docs/services/go-services.md create mode 100644 docs/testing/README.md create mode 100644 docs/testing/agent-evaluation.md create mode 100644 docs/testing/integration.md create mode 100644 docs/testing/rag-evaluation.md create mode 100644 docs/testing/strategy.md create mode 100644 docs/testing/unit.md create mode 100644 docs/tools/README.md create mode 100644 docs/tools/built-in-tools.md create mode 100644 docs/tools/overview.md create mode 100644 docs/tools/permissions.md create mode 100644 docs/tools/registry.md create mode 100644 docs/tools/sandbox.md diff --git a/AGENTS.md b/AGENTS.md index 82405f6..8d37f8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,143 +54,206 @@ live-2d: deepseek-herness： 模型网关设计：,,,,, -## 完整技术栈 +## 项目定位 ---- +本项目是一个面向长期运行与持续演化的 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 diff --git a/docs/README.md b/docs/README.md index c54f1d3..3452029 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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` + +## 文档原则 + +文档描述系统为什么这样设计、系统如何工作以及修改时需要遵守的边界。 + +具体实现应以源码和测试为最终事实来源。 + ## 快速阅读 ### 理解产品 diff --git a/docs/agent/README.md b/docs/agent/README.md new file mode 100644 index 0000000..ff56b40 --- /dev/null +++ b/docs/agent/README.md @@ -0,0 +1,3 @@ +# Agent + +Agent Runtime 与认知架构文档目录。 diff --git a/docs/agent/execution.md b/docs/agent/execution.md new file mode 100644 index 0000000..9529aea --- /dev/null +++ b/docs/agent/execution.md @@ -0,0 +1,24 @@ +# Agent Execution + +## 执行阶段 + +1. 创建 Run +2. 构建上下文 +3. 召回记忆 +4. 生成计划 +5. 执行步骤 +6. 获取观察 +7. 验证结果 +8. 重规划或完成 +9. 记录经验 + +## 长任务 + +长任务必须： + +- 持久化状态 +- 可查询 +- 可恢复 +- 可取消 +- 可超时 +- 可审计 diff --git a/docs/agent/memory.md b/docs/agent/memory.md new file mode 100644 index 0000000..0c3e8d8 --- /dev/null +++ b/docs/agent/memory.md @@ -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 +``` + +## 原则 + +- 事实和推断分离。 +- 推断必须标记来源和置信度。 +- 重要记忆应保留来源和时间。 +- 记忆更新必须可追踪。 diff --git a/docs/agent/model-system.md b/docs/agent/model-system.md new file mode 100644 index 0000000..020af16 --- /dev/null +++ b/docs/agent/model-system.md @@ -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 及本地模型。 diff --git a/docs/agent/overview.md b/docs/agent/overview.md new file mode 100644 index 0000000..636d0ec --- /dev/null +++ b/docs/agent/overview.md @@ -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 保持可扩展接口。 diff --git a/docs/agent/planning.md b/docs/agent/planning.md new file mode 100644 index 0000000..01ee223 --- /dev/null +++ b/docs/agent/planning.md @@ -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 + +## 原则 + +计划不是不可变脚本；执行过程中的观察可以触发局部或全局重规划。 diff --git a/docs/agent/reasoning.md b/docs/agent/reasoning.md new file mode 100644 index 0000000..778330c --- /dev/null +++ b/docs/agent/reasoning.md @@ -0,0 +1,29 @@ +# Reasoning + +## 推理职责 + +- 任务理解 +- 假设生成 +- 证据分析 +- 工具选择 +- 结果验证 +- 错误诊断 + +## ReAct + +`Thought/Reasoning -> Action -> Observation` + +实际系统不要求暴露模型内部思维链。对外只输出必要的状态、依据和工具事件。 + +## Reflection + +反思不是无条件重复推理，应在以下情况触发： + +- 工具失败 +- 结果与目标不一致 +- 关键约束未满足 +- 新信息推翻原假设 + +## 验证 + +最终结果应尽可能进行结构化验证，而不是只依赖 LLM 自评。 diff --git a/docs/agent/reflection.md b/docs/agent/reflection.md new file mode 100644 index 0000000..4e5debb --- /dev/null +++ b/docs/agent/reflection.md @@ -0,0 +1,24 @@ +# Reflection + +## 目标 + +通过执行结果发现错误、总结经验并修正后续行为。 + +## 类型 + +- Step Reflection：单步骤反思 +- Run Reflection：一次任务结束后的反思 +- Experience Consolidation：把经验沉淀为长期记忆 +- Strategy Reflection：更新策略 + +## 原则 + +反思必须产生可执行结果，例如： + +- 修改计划 +- 更换工具 +- 调整参数 +- 增加验证 +- 写入经验 + +避免“反思但不改变行为”。 diff --git a/docs/agent/runtime.md b/docs/agent/runtime.md new file mode 100644 index 0000000..6fca4cc --- /dev/null +++ b/docs/agent/runtime.md @@ -0,0 +1,22 @@ +# Agent Runtime + +## 职责 + +- Agent 生命周期 +- Session / Run 管理 +- 上下文组装 +- 模型调用 +- Tool 调度 +- 状态机 +- 事件发布 +- 错误恢复 +- 运行追踪 + +## 不负责 + +- 具体数据库实现 +- 具体向量数据库 +- 前端 UI +- 外部服务业务逻辑 + +Runtime 应通过接口调用这些能力。 diff --git a/docs/agent/tool-system.md b/docs/agent/tool-system.md new file mode 100644 index 0000000..8ca8dc2 --- /dev/null +++ b/docs/agent/tool-system.md @@ -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。 diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 0000000..e7b5eef --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,3 @@ +# API + +API 契约与协议文档目录。 diff --git a/docs/api/authentication.md b/docs/api/authentication.md new file mode 100644 index 0000000..62b52da --- /dev/null +++ b/docs/api/authentication.md @@ -0,0 +1,7 @@ +# Authentication + +认证与授权分离。 + +认证回答“你是谁”；授权回答“你能做什么”。 + +支持的认证方式由部署环境决定，业务代码只依赖统一 Identity Context。 diff --git a/docs/api/conventions.md b/docs/api/conventions.md new file mode 100644 index 0000000..e5c8da2 --- /dev/null +++ b/docs/api/conventions.md @@ -0,0 +1,8 @@ +# API Conventions + +- REST 资源使用名词。 +- JSON 使用统一编码。 +- 时间使用 ISO 8601。 +- ID 使用稳定唯一标识。 +- API 版本必须可演进。 +- 分页、排序、过滤采用统一约定。 diff --git a/docs/api/errors.md b/docs/api/errors.md new file mode 100644 index 0000000..934714b --- /dev/null +++ b/docs/api/errors.md @@ -0,0 +1,11 @@ +# API Errors + +统一错误模型： + +- code +- message +- details +- request_id +- trace_id + +不要把内部异常堆栈直接返回给用户。 diff --git a/docs/api/overview.md b/docs/api/overview.md new file mode 100644 index 0000000..d7c250a --- /dev/null +++ b/docs/api/overview.md @@ -0,0 +1,16 @@ +# API + +API 使用 OpenAPI 3.1。 + +核心领域： + +- Auth +- Agent +- Session +- Run +- Task +- Memory +- Knowledge +- Tool +- File +- MCP diff --git a/docs/api/streaming.md b/docs/api/streaming.md new file mode 100644 index 0000000..4d97d20 --- /dev/null +++ b/docs/api/streaming.md @@ -0,0 +1,13 @@ +# Streaming + +SSE 是 Agent 流式输出默认方案。 + +事件至少包含： + +- event_id +- run_id +- event_type +- timestamp +- payload + +客户端断线后通过 Last-Event-ID 请求恢复。 diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..3f07810 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,3 @@ +# Architecture + +总体架构文档目录。详见 `overview.md`、`system.md`、`data-flow.md`、`event-flow.md`、`runtime.md`、`security.md`。 diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md new file mode 100644 index 0000000..9ee4f92 --- /dev/null +++ b/docs/architecture/data-flow.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。 diff --git a/docs/architecture/event-flow.md b/docs/architecture/event-flow.md new file mode 100644 index 0000000..63e7258 --- /dev/null +++ b/docs/architecture/event-flow.md @@ -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 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 0000000..b2a83b6 --- /dev/null +++ b/docs/architecture/overview.md @@ -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。 diff --git a/docs/architecture/runtime.md b/docs/architecture/runtime.md new file mode 100644 index 0000000..f1b0d1f --- /dev/null +++ b/docs/architecture/runtime.md @@ -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 --> [*] +``` diff --git a/docs/architecture/security.md b/docs/architecture/security.md new file mode 100644 index 0000000..2b0b4ad --- /dev/null +++ b/docs/architecture/security.md @@ -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 的服务能力。 + +禁止把任何单一机制视为完整安全方案。 diff --git a/docs/architecture/system.md b/docs/architecture/system.md new file mode 100644 index 0000000..94b046b --- /dev/null +++ b/docs/architecture/system.md @@ -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 +``` + +模块之间优先使用明确接口，不允许跨层直接访问内部实现。 diff --git a/docs/client/README.md b/docs/client/README.md new file mode 100644 index 0000000..09fc87f --- /dev/null +++ b/docs/client/README.md @@ -0,0 +1,3 @@ +# Client + +Web、BFF、Desktop 文档目录。 diff --git a/docs/client/bff.md b/docs/client/bff.md new file mode 100644 index 0000000..5a3ee44 --- /dev/null +++ b/docs/client/bff.md @@ -0,0 +1,13 @@ +# BFF + +BFF 是前端聚合与协议适配层。 + +职责： + +- API 聚合 +- SSE / WebSocket 代理 +- 类型桥接 +- 响应裁剪 +- 前端专用数据转换 + +BFF 不承载 Agent 核心业务逻辑。 diff --git a/docs/client/desktop.md b/docs/client/desktop.md new file mode 100644 index 0000000..0576738 --- /dev/null +++ b/docs/client/desktop.md @@ -0,0 +1,16 @@ +# Desktop + +Rust + Tauri v2。 + +能力： + +- 本地文件 +- 本地索引 +- 本地全文搜索 +- 本地工具 +- Sandbox +- Offline + +Tantivy 用于本地全文检索。 + +Tauri Capabilities 用于限制本地系统访问。 diff --git a/docs/client/web.md b/docs/client/web.md new file mode 100644 index 0000000..606adfc --- /dev/null +++ b/docs/client/web.md @@ -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 diff --git a/docs/data/README.md b/docs/data/README.md new file mode 100644 index 0000000..0b218a0 --- /dev/null +++ b/docs/data/README.md @@ -0,0 +1,3 @@ +# Data + +数据层文档目录。 diff --git a/docs/data/database.md b/docs/data/database.md new file mode 100644 index 0000000..6a410be --- /dev/null +++ b/docs/data/database.md @@ -0,0 +1,18 @@ +# PostgreSQL + +PostgreSQL 是主关系数据库。 + +负责： + +- 业务数据 +- 用户 +- Session +- Run +- Task +- 长期记忆 +- 审计 +- 元数据 + +SQLAlchemy 2.0 + Alembic。 + +数据库 Schema 是持久化契约，重大变化必须通过 migration。 diff --git a/docs/data/file-storage.md b/docs/data/file-storage.md new file mode 100644 index 0000000..f9675f3 --- /dev/null +++ b/docs/data/file-storage.md @@ -0,0 +1,11 @@ +# FileStorage + +定义统一 `FileStorage` 接口。 + +实现： + +- Local File System +- MinIO +- S3 / OSS / COS + +业务代码不得直接拼接具体对象存储 SDK。 diff --git a/docs/data/graph-store.md b/docs/data/graph-store.md new file mode 100644 index 0000000..519291b --- /dev/null +++ b/docs/data/graph-store.md @@ -0,0 +1,10 @@ +# GraphStore + +定义统一 `GraphStore` 接口。 + +实现： + +- Neo4j：开发 / 测试 +- NebulaGraph：大规模生产 + +主要用于知识图谱、实体关系、复杂多跳关系。 diff --git a/docs/data/redis.md b/docs/data/redis.md new file mode 100644 index 0000000..47cbf9e --- /dev/null +++ b/docs/data/redis.md @@ -0,0 +1,13 @@ +# Redis + +Redis 负责高频、短生命周期数据： + +- Cache +- Working Memory +- Session State +- Task Runtime State +- Rate Limit +- Distributed Lock +- Event Buffer + +Redis 数据默认不作为核心业务数据唯一来源。 diff --git a/docs/data/vector-store.md b/docs/data/vector-store.md new file mode 100644 index 0000000..5ddb44e --- /dev/null +++ b/docs/data/vector-store.md @@ -0,0 +1,11 @@ +# VectorStore + +定义统一 `VectorStore` 接口。 + +实现： + +- ChromaDB：开发 +- PostgreSQL + pgvector：中小规模生产 +- Milvus：大规模生产 + +上层 Memory 与 RAG 不依赖具体实现。 diff --git a/docs/decisions/ADR-001-agent-runtime.md b/docs/decisions/ADR-001-agent-runtime.md new file mode 100644 index 0000000..1c01378 --- /dev/null +++ b/docs/decisions/ADR-001-agent-runtime.md @@ -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 能力与具体编排框架解耦，但需要维护统一领域模型。 diff --git a/docs/decisions/ADR-002-memory-architecture.md b/docs/decisions/ADR-002-memory-architecture.md new file mode 100644 index 0000000..b95725e --- /dev/null +++ b/docs/decisions/ADR-002-memory-architecture.md @@ -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 策略。 diff --git a/docs/decisions/ADR-003-vector-store.md b/docs/decisions/ADR-003-vector-store.md new file mode 100644 index 0000000..1f2eefb --- /dev/null +++ b/docs/decisions/ADR-003-vector-store.md @@ -0,0 +1,17 @@ +# ADR-003: Vector Store + +## Status + +Accepted + +## Decision + +建立 VectorStore 抽象： + +- 开发：ChromaDB +- 中小生产：PostgreSQL + pgvector +- 大规模：Milvus + +## Rationale + +优先降低早期运维成本，同时保留大规模演进路径。 diff --git a/docs/decisions/ADR-004-graph-store.md b/docs/decisions/ADR-004-graph-store.md new file mode 100644 index 0000000..68c916a --- /dev/null +++ b/docs/decisions/ADR-004-graph-store.md @@ -0,0 +1,16 @@ +# ADR-004: Graph Store + +## Status + +Accepted + +## Decision + +建立 GraphStore 抽象： + +- 开发：Neo4j +- 大规模：NebulaGraph + +## Rationale + +知识图谱与复杂关系查询需要独立抽象。 diff --git a/docs/decisions/ADR-005-model-gateway.md b/docs/decisions/ADR-005-model-gateway.md new file mode 100644 index 0000000..f24e240 --- /dev/null +++ b/docs/decisions/ADR-005-model-gateway.md @@ -0,0 +1,17 @@ +# ADR-005: Model Gateway + +## Status + +Accepted + +## Context + +Agent 不应绑定单一模型厂商。 + +## Decision + +建立统一 Model Gateway，支持 OpenAI SDK、LiteLLM 及本地模型。 + +## Consequences + +增加模型抽象层，但能够实现模型切换、能力路由和供应商解耦。 diff --git a/docs/decisions/README.md b/docs/decisions/README.md new file mode 100644 index 0000000..05fc25a --- /dev/null +++ b/docs/decisions/README.md @@ -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 + +相关文档。 +``` diff --git a/docs/infrastructure/README.md b/docs/infrastructure/README.md new file mode 100644 index 0000000..8182550 --- /dev/null +++ b/docs/infrastructure/README.md @@ -0,0 +1,3 @@ +# Infrastructure + +基础设施文档目录。 diff --git a/docs/infrastructure/deployment.md b/docs/infrastructure/deployment.md new file mode 100644 index 0000000..674c4d9 --- /dev/null +++ b/docs/infrastructure/deployment.md @@ -0,0 +1,7 @@ +# Deployment + +采用渐进式部署： + +`Docker Compose -> Container Platform -> Kubernetes` + +是否进入 Kubernetes 由服务数量、可用性、扩缩容和团队运维能力决定，而不是技术偏好。 diff --git a/docs/infrastructure/development.md b/docs/infrastructure/development.md new file mode 100644 index 0000000..302d98c --- /dev/null +++ b/docs/infrastructure/development.md @@ -0,0 +1,12 @@ +# Development Environment + +推荐： + +- Docker Compose +- PostgreSQL +- Redis +- MinIO +- VectorStore +- GraphStore + +Python 使用 uv；Node 使用 pnpm；Rust 使用 Cargo；Go 使用 Go Modules。 diff --git a/docs/infrastructure/docker.md b/docs/infrastructure/docker.md new file mode 100644 index 0000000..013a714 --- /dev/null +++ b/docs/infrastructure/docker.md @@ -0,0 +1,10 @@ +# Docker + +Docker Compose 用于本地多服务编排。 + +原则： + +- 服务配置环境化。 +- Secret 不提交 Git。 +- 数据卷用于开发持久化。 +- 每个服务保持单一职责。 diff --git a/docs/infrastructure/observability.md b/docs/infrastructure/observability.md new file mode 100644 index 0000000..bb3f4d4 --- /dev/null +++ b/docs/infrastructure/observability.md @@ -0,0 +1,13 @@ +# Observability + +统一采用 OpenTelemetry 思路。 + +三类信号： + +- Logs +- Metrics +- Traces + +Agent 特有 Trace： + +`Run -> Plan -> Model -> Memory -> Tool -> Observation -> Reflection` diff --git a/docs/infrastructure/scaling.md b/docs/infrastructure/scaling.md new file mode 100644 index 0000000..a9bc683 --- /dev/null +++ b/docs/infrastructure/scaling.md @@ -0,0 +1,13 @@ +# Scaling + +扩展顺序优先： + +1. 优化单体 Agent Runtime。 +2. 异步化长任务。 +3. 分离高并发 I/O。 +4. 增加缓存。 +5. 数据库读写优化。 +6. 按瓶颈拆分服务。 +7. 最后引入更复杂的分布式基础设施。 + +避免过早微服务化。 diff --git a/docs/mcp/README.md b/docs/mcp/README.md new file mode 100644 index 0000000..0b63e8a --- /dev/null +++ b/docs/mcp/README.md @@ -0,0 +1,3 @@ +# MCP + +MCP 集成文档目录。 diff --git a/docs/mcp/client.md b/docs/mcp/client.md new file mode 100644 index 0000000..056e6e7 --- /dev/null +++ b/docs/mcp/client.md @@ -0,0 +1,16 @@ +# MCP Client + +支持： + +- stdio +- SSE + +职责： + +- Server connection +- Capability discovery +- Tool discovery +- Schema conversion +- Invocation +- Timeout +- Error handling diff --git a/docs/mcp/overview.md b/docs/mcp/overview.md new file mode 100644 index 0000000..ff3b3e8 --- /dev/null +++ b/docs/mcp/overview.md @@ -0,0 +1,9 @@ +# MCP + +MCP 用于连接外部工具与上下文服务。 + +内部架构： + +`MCP Client -> Transport -> MCP Server -> Tool Adapter -> Tool Runtime` + +MCP Server 提供的能力不能绕过内部权限和审计系统。 diff --git a/docs/mcp/security.md b/docs/mcp/security.md new file mode 100644 index 0000000..d2dd1b8 --- /dev/null +++ b/docs/mcp/security.md @@ -0,0 +1,12 @@ +# MCP Security + +外部 MCP Server 默认视为不可信边界。 + +必须： + +- 显式授权 +- 限制工具 +- 限制资源 +- 校验输入 +- 记录调用 +- 限制网络和文件权限 diff --git a/docs/mcp/tool-adapter.md b/docs/mcp/tool-adapter.md new file mode 100644 index 0000000..006a90e --- /dev/null +++ b/docs/mcp/tool-adapter.md @@ -0,0 +1,9 @@ +# MCP Tool Adapter + +MCP Tool 应转换为内部统一 Tool Model。 + +映射： + +`MCP Tool Schema -> Internal Tool Schema -> Permission -> Runtime` + +这样 Agent 无需知道工具来自 MCP 还是内部注册表。 diff --git a/docs/mcp/transport.md b/docs/mcp/transport.md new file mode 100644 index 0000000..d9d2f80 --- /dev/null +++ b/docs/mcp/transport.md @@ -0,0 +1,10 @@ +# MCP Transport + +Transport 只负责通信，不负责业务权限。 + +支持： + +- stdio：本地进程 +- SSE：远程流式通信 + +未来可根据 MCP 生态支持情况扩展其他传输方式。 diff --git a/docs/rag/README.md b/docs/rag/README.md new file mode 100644 index 0000000..1f5eb3c --- /dev/null +++ b/docs/rag/README.md @@ -0,0 +1,3 @@ +# RAG + +RAG 与知识系统文档目录。 diff --git a/docs/rag/chunking.md b/docs/rag/chunking.md new file mode 100644 index 0000000..efa79c4 --- /dev/null +++ b/docs/rag/chunking.md @@ -0,0 +1,16 @@ +# Chunking + +## 原则 + +优先保持语义完整性，而不是机械固定长度切分。 + +考虑： + +- 标题层级 +- 段落 +- 代码块 +- 表格 +- 文档结构 +- Token 长度 + +Chunk 必须携带可追溯 metadata。 diff --git a/docs/rag/embedding.md b/docs/rag/embedding.md new file mode 100644 index 0000000..1675eea --- /dev/null +++ b/docs/rag/embedding.md @@ -0,0 +1,12 @@ +# Embedding + +Embedding 用于把文本、实体或其他内容映射到向量空间。 + +要求： + +- 明确模型版本 +- 明确维度 +- 保存模型标识 +- 模型变更时考虑重建索引 + +Embedding 与业务代码通过统一接口隔离。 diff --git a/docs/rag/evaluation.md b/docs/rag/evaluation.md new file mode 100644 index 0000000..208fde0 --- /dev/null +++ b/docs/rag/evaluation.md @@ -0,0 +1,13 @@ +# RAG Evaluation + +评估至少覆盖： + +- Recall +- Precision +- MRR +- NDCG +- Context Relevance +- Answer Faithfulness +- Citation / Source Accuracy + +评估集应版本化，模型、Embedding、Chunking 或检索策略发生重要变化时重新评估。 diff --git a/docs/rag/ingestion.md b/docs/rag/ingestion.md new file mode 100644 index 0000000..3219146 --- /dev/null +++ b/docs/rag/ingestion.md @@ -0,0 +1,13 @@ +# RAG Ingestion + +流程： + +`File -> Parse -> Normalize -> Chunk -> Metadata -> Embedding -> Index` + +解析工具： + +- unstructured +- PyMuPDF +- MarkItDown + +每个 chunk 应保留来源、文档 ID、位置和版本信息。 diff --git a/docs/rag/overview.md b/docs/rag/overview.md new file mode 100644 index 0000000..a130442 --- /dev/null +++ b/docs/rag/overview.md @@ -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 提高上下文质量。 diff --git a/docs/rag/reranking.md b/docs/rag/reranking.md new file mode 100644 index 0000000..ca58215 --- /dev/null +++ b/docs/rag/reranking.md @@ -0,0 +1,9 @@ +# Reranking + +Reranker 用于对候选结果进行二次相关性排序。 + +典型流程： + +`Recall -> Candidate Set -> Reranker -> Top K` + +Reranker 不是召回器，不能替代低成本高召回率的第一阶段检索。 diff --git a/docs/rag/retrieval.md b/docs/rag/retrieval.md new file mode 100644 index 0000000..b121176 --- /dev/null +++ b/docs/rag/retrieval.md @@ -0,0 +1,12 @@ +# Retrieval + +支持： + +- BM25 +- Vector Search +- Graph Search +- Metadata Filter + +推荐采用多路召回后统一融合。 + +检索必须保留 source metadata，确保最终上下文可追溯。 diff --git a/docs/security/README.md b/docs/security/README.md new file mode 100644 index 0000000..7133ede --- /dev/null +++ b/docs/security/README.md @@ -0,0 +1,3 @@ +# Security + +安全体系文档目录。 diff --git a/docs/security/audit.md b/docs/security/audit.md new file mode 100644 index 0000000..b84896c --- /dev/null +++ b/docs/security/audit.md @@ -0,0 +1,15 @@ +# Audit + +重要操作必须可审计： + +- user +- run_id +- tool +- timestamp +- input metadata +- output metadata +- permission decision +- result +- error + +敏感内容应脱敏。 diff --git a/docs/security/authentication.md b/docs/security/authentication.md new file mode 100644 index 0000000..155f021 --- /dev/null +++ b/docs/security/authentication.md @@ -0,0 +1,7 @@ +# Authentication + +统一产生 Identity Context。 + +业务层不应自己解析认证协议。 + +认证方式由部署环境决定，核心系统依赖稳定的用户身份接口。 diff --git a/docs/security/authorization.md b/docs/security/authorization.md new file mode 100644 index 0000000..8519917 --- /dev/null +++ b/docs/security/authorization.md @@ -0,0 +1,7 @@ +# Authorization + +采用 RBAC + Tool Permission + Resource Permission。 + +权限检查应尽可能靠近实际资源访问点。 + +默认拒绝，显式授权。 diff --git a/docs/security/overview.md b/docs/security/overview.md new file mode 100644 index 0000000..c53124b --- /dev/null +++ b/docs/security/overview.md @@ -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 diff --git a/docs/security/prompt-injection.md b/docs/security/prompt-injection.md new file mode 100644 index 0000000..ef7344b --- /dev/null +++ b/docs/security/prompt-injection.md @@ -0,0 +1,11 @@ +# Prompt Injection + +防护采用多层策略： + +1. 外部内容标记为不可信数据。 +2. 工具调用不由文本指令直接决定权限。 +3. Tool Permission 独立于 LLM 输出。 +4. 高风险操作要求额外确认或策略。 +5. 对工具结果进行来源和内容分类。 + +LLM Guard 等组件只是其中一层。 diff --git a/docs/security/sandbox.md b/docs/security/sandbox.md new file mode 100644 index 0000000..fe260a7 --- /dev/null +++ b/docs/security/sandbox.md @@ -0,0 +1,19 @@ +# Sandbox + +高风险执行能力必须隔离。 + +包括： + +- Code +- Shell +- Browser +- File System + +限制： + +- CPU +- Memory +- Disk +- Network +- Process +- Timeout diff --git a/docs/services/README.md b/docs/services/README.md new file mode 100644 index 0000000..a41caa6 --- /dev/null +++ b/docs/services/README.md @@ -0,0 +1,3 @@ +# Services + +Go 高并发服务文档目录。 diff --git a/docs/services/go-services.md b/docs/services/go-services.md new file mode 100644 index 0000000..f344a0b --- /dev/null +++ b/docs/services/go-services.md @@ -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。 diff --git a/docs/testing/README.md b/docs/testing/README.md new file mode 100644 index 0000000..6c96061 --- /dev/null +++ b/docs/testing/README.md @@ -0,0 +1,3 @@ +# Testing + +测试与评估文档目录。 diff --git a/docs/testing/agent-evaluation.md b/docs/testing/agent-evaluation.md new file mode 100644 index 0000000..b8df567 --- /dev/null +++ b/docs/testing/agent-evaluation.md @@ -0,0 +1,13 @@ +# Agent Evaluation + +评估维度： + +- Task Success +- Tool Selection +- Plan Quality +- Recovery +- Hallucination +- Cost +- Latency + +评估数据集需要版本化。 diff --git a/docs/testing/integration.md b/docs/testing/integration.md new file mode 100644 index 0000000..eae5571 --- /dev/null +++ b/docs/testing/integration.md @@ -0,0 +1,13 @@ +# Integration Test + +覆盖： + +- PostgreSQL +- Redis +- VectorStore +- GraphStore +- FileStorage +- MCP +- Tool Runtime + +外部服务优先使用隔离测试环境或 Mock。 diff --git a/docs/testing/rag-evaluation.md b/docs/testing/rag-evaluation.md new file mode 100644 index 0000000..cef6344 --- /dev/null +++ b/docs/testing/rag-evaluation.md @@ -0,0 +1,13 @@ +# RAG Evaluation + +评估： + +- Retrieval Recall +- MRR +- NDCG +- Context Relevance +- Faithfulness +- Answer Accuracy +- Source Accuracy + +模型、Embedding、Chunking、Retriever 变化时应重新运行基准集。 diff --git a/docs/testing/strategy.md b/docs/testing/strategy.md new file mode 100644 index 0000000..f9940fe --- /dev/null +++ b/docs/testing/strategy.md @@ -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 diff --git a/docs/testing/unit.md b/docs/testing/unit.md new file mode 100644 index 0000000..9c05be8 --- /dev/null +++ b/docs/testing/unit.md @@ -0,0 +1,12 @@ +# Unit Test + +单元测试重点： + +- Domain Logic +- Planner +- Memory Manager +- Tool Schema +- Permission +- Data Transformation + +避免在单元测试中真实调用外部 LLM 或第三方 API。 diff --git a/docs/tools/README.md b/docs/tools/README.md new file mode 100644 index 0000000..8dc4bd7 --- /dev/null +++ b/docs/tools/README.md @@ -0,0 +1,3 @@ +# Tools + +工具系统文档目录。 diff --git a/docs/tools/built-in-tools.md b/docs/tools/built-in-tools.md new file mode 100644 index 0000000..5285afa --- /dev/null +++ b/docs/tools/built-in-tools.md @@ -0,0 +1,15 @@ +# Built-in Tools + +初始工具类别： + +- File +- HTTP +- Web +- Database +- Vector +- Graph +- Code Sandbox +- Shell +- Search + +工具必须保持单一职责，复杂业务流程应通过 Agent Workflow 组合，而不是制作超大工具。 diff --git a/docs/tools/overview.md b/docs/tools/overview.md new file mode 100644 index 0000000..a0d8b09 --- /dev/null +++ b/docs/tools/overview.md @@ -0,0 +1,19 @@ +# Tools + +Tool System 是 Agent 与外部世界之间的执行边界。 + +核心组件： + +- Registry +- Discovery +- Permission +- Validation +- Runtime +- Audit + +工具来源： + +- Built-in +- MCP +- Local Desktop +- External API diff --git a/docs/tools/permissions.md b/docs/tools/permissions.md new file mode 100644 index 0000000..343c3ee --- /dev/null +++ b/docs/tools/permissions.md @@ -0,0 +1,12 @@ +# Tool Permissions + +权限至少区分： + +- User Permission +- Agent Permission +- Tool Permission +- Resource Permission + +采用最小权限原则。 + +权限检查必须发生在 Tool 执行之前。 diff --git a/docs/tools/registry.md b/docs/tools/registry.md new file mode 100644 index 0000000..562deb6 --- /dev/null +++ b/docs/tools/registry.md @@ -0,0 +1,14 @@ +# Tool Registry + +注册信息： + +- name +- version +- description +- schema +- permissions +- timeout +- retry +- tags + +Registry 支持发现、版本控制和能力过滤。 diff --git a/docs/tools/sandbox.md b/docs/tools/sandbox.md new file mode 100644 index 0000000..064bf9d --- /dev/null +++ b/docs/tools/sandbox.md @@ -0,0 +1,14 @@ +# Tool Sandbox + +代码执行、Shell、文件系统等高风险工具必须运行在受控环境。 + +安全目标： + +- 文件隔离 +- 网络限制 +- 资源限制 +- 超时 +- 进程隔离 +- 输出限制 + +桌面端使用 Tauri Capabilities 控制本地系统能力；服务端使用独立 Sandbox。