完善文档

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`
+
+## 文档原则
+
+文档描述系统为什么这样设计、系统如何工作以及修改时需要遵守的边界。
+
+具体实现应以源码和测试为最终事实来源。
+
 ## 快速阅读
 
 ### 理解产品

docs/agent/README.md

@@ -0,0 +1,3 @@
+# Agent
+
+Agent Runtime 与认知架构文档目录。

docs/agent/execution.md

@@ -0,0 +1,24 @@
+# Agent Execution
+
+## 执行阶段
+
+1. 创建 Run
+2. 构建上下文
+3. 召回记忆
+4. 生成计划
+5. 执行步骤
+6. 获取观察
+7. 验证结果
+8. 重规划或完成
+9. 记录经验
+
+## 长任务
+
+长任务必须：
+
+- 持久化状态
+- 可查询
+- 可恢复
+- 可取消
+- 可超时
+- 可审计

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
+```
+
+## 原则
+
+- 事实和推断分离。
+- 推断必须标记来源和置信度。
+- 重要记忆应保留来源和时间。
+- 记忆更新必须可追踪。

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 及本地模型。

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 保持可扩展接口。

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
+
+## 原则
+
+计划不是不可变脚本；执行过程中的观察可以触发局部或全局重规划。

docs/agent/reasoning.md

@@ -0,0 +1,29 @@
+# Reasoning
+
+## 推理职责
+
+- 任务理解
+- 假设生成
+- 证据分析
+- 工具选择
+- 结果验证
+- 错误诊断
+
+## ReAct
+
+`Thought/Reasoning -> Action -> Observation`
+
+实际系统不要求暴露模型内部思维链。对外只输出必要的状态、依据和工具事件。
+
+## Reflection
+
+反思不是无条件重复推理，应在以下情况触发：
+
+- 工具失败
+- 结果与目标不一致
+- 关键约束未满足
+- 新信息推翻原假设
+
+## 验证
+
+最终结果应尽可能进行结构化验证，而不是只依赖 LLM 自评。

docs/agent/reflection.md

@@ -0,0 +1,24 @@
+# Reflection
+
+## 目标
+
+通过执行结果发现错误、总结经验并修正后续行为。
+
+## 类型
+
+- Step Reflection：单步骤反思
+- Run Reflection：一次任务结束后的反思
+- Experience Consolidation：把经验沉淀为长期记忆
+- Strategy Reflection：更新策略
+
+## 原则
+
+反思必须产生可执行结果，例如：
+
+- 修改计划
+- 更换工具
+- 调整参数
+- 增加验证
+- 写入经验
+
+避免“反思但不改变行为”。

docs/agent/runtime.md

@@ -0,0 +1,22 @@
+# Agent Runtime
+
+## 职责
+
+- Agent 生命周期
+- Session / Run 管理
+- 上下文组装
+- 模型调用
+- Tool 调度
+- 状态机
+- 事件发布
+- 错误恢复
+- 运行追踪
+
+## 不负责
+
+- 具体数据库实现
+- 具体向量数据库
+- 前端 UI
+- 外部服务业务逻辑
+
+Runtime 应通过接口调用这些能力。

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。

docs/api/README.md

@@ -0,0 +1,3 @@
+# API
+
+API 契约与协议文档目录。

docs/api/authentication.md

@@ -0,0 +1,7 @@
+# Authentication
+
+认证与授权分离。
+
+认证回答“你是谁”；授权回答“你能做什么”。
+
+支持的认证方式由部署环境决定，业务代码只依赖统一 Identity Context。

docs/api/conventions.md

@@ -0,0 +1,8 @@
+# API Conventions
+
+- REST 资源使用名词。
+- JSON 使用统一编码。
+- 时间使用 ISO 8601。
+- ID 使用稳定唯一标识。
+- API 版本必须可演进。
+- 分页、排序、过滤采用统一约定。

docs/api/errors.md

@@ -0,0 +1,11 @@
+# API Errors
+
+统一错误模型：
+
+- code
+- message
+- details
+- request_id
+- trace_id
+
+不要把内部异常堆栈直接返回给用户。

docs/api/overview.md

@@ -0,0 +1,16 @@
+# API
+
+API 使用 OpenAPI 3.1。
+
+核心领域：
+
+- Auth
+- Agent
+- Session
+- Run
+- Task
+- Memory
+- Knowledge
+- Tool
+- File
+- MCP

docs/api/streaming.md

@@ -0,0 +1,13 @@
+# Streaming
+
+SSE 是 Agent 流式输出默认方案。
+
+事件至少包含：
+
+- event_id
+- run_id
+- event_type
+- timestamp
+- payload
+
+客户端断线后通过 Last-Event-ID 请求恢复。

docs/architecture/README.md

@@ -0,0 +1,3 @@
+# Architecture
+
+总体架构文档目录。详见 `overview.md`、`system.md`、`data-flow.md`、`event-flow.md`、`runtime.md`、`security.md`。

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。

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

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。

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 --> [*]
+```

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 的服务能力。
+
+禁止把任何单一机制视为完整安全方案。

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
+```
+
+模块之间优先使用明确接口，不允许跨层直接访问内部实现。

docs/client/README.md

@@ -0,0 +1,3 @@
+# Client
+
+Web、BFF、Desktop 文档目录。

docs/client/bff.md

@@ -0,0 +1,13 @@
+# BFF
+
+BFF 是前端聚合与协议适配层。
+
+职责：
+
+- API 聚合
+- SSE / WebSocket 代理
+- 类型桥接
+- 响应裁剪
+- 前端专用数据转换
+
+BFF 不承载 Agent 核心业务逻辑。

docs/client/desktop.md

@@ -0,0 +1,16 @@
+# Desktop
+
+Rust + Tauri v2。
+
+能力：
+
+- 本地文件
+- 本地索引
+- 本地全文搜索
+- 本地工具
+- Sandbox
+- Offline
+
+Tantivy 用于本地全文检索。
+
+Tauri Capabilities 用于限制本地系统访问。

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

docs/data/README.md

@@ -0,0 +1,3 @@
+# Data
+
+数据层文档目录。

docs/data/database.md

@@ -0,0 +1,18 @@
+# PostgreSQL
+
+PostgreSQL 是主关系数据库。
+
+负责：
+
+- 业务数据
+- 用户
+- Session
+- Run
+- Task
+- 长期记忆
+- 审计
+- 元数据
+
+SQLAlchemy 2.0 + Alembic。
+
+数据库 Schema 是持久化契约，重大变化必须通过 migration。

docs/data/file-storage.md

@@ -0,0 +1,11 @@
+# FileStorage
+
+定义统一 `FileStorage` 接口。
+
+实现：
+
+- Local File System
+- MinIO
+- S3 / OSS / COS
+
+业务代码不得直接拼接具体对象存储 SDK。

docs/data/graph-store.md

@@ -0,0 +1,10 @@
+# GraphStore
+
+定义统一 `GraphStore` 接口。
+
+实现：
+
+- Neo4j：开发 / 测试
+- NebulaGraph：大规模生产
+
+主要用于知识图谱、实体关系、复杂多跳关系。

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 数据默认不作为核心业务数据唯一来源。

docs/data/vector-store.md

@@ -0,0 +1,11 @@
+# VectorStore
+
+定义统一 `VectorStore` 接口。
+
+实现：
+
+- ChromaDB：开发
+- PostgreSQL + pgvector：中小规模生产
+- Milvus：大规模生产
+
+上层 Memory 与 RAG 不依赖具体实现。

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 能力与具体编排框架解耦，但需要维护统一领域模型。

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 策略。

docs/decisions/ADR-003-vector-store.md

@@ -0,0 +1,17 @@
+# ADR-003: Vector Store
+
+## Status
+
+Accepted
+
+## Decision
+
+建立 VectorStore 抽象：
+
+- 开发：ChromaDB
+- 中小生产：PostgreSQL + pgvector
+- 大规模：Milvus
+
+## Rationale
+
+优先降低早期运维成本，同时保留大规模演进路径。

docs/decisions/ADR-004-graph-store.md

@@ -0,0 +1,16 @@
+# ADR-004: Graph Store
+
+## Status
+
+Accepted
+
+## Decision
+
+建立 GraphStore 抽象：
+
+- 开发：Neo4j
+- 大规模：NebulaGraph
+
+## Rationale
+
+知识图谱与复杂关系查询需要独立抽象。

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
+
+增加模型抽象层，但能够实现模型切换、能力路由和供应商解耦。

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
+
+相关文档。
+```

docs/infrastructure/README.md

@@ -0,0 +1,3 @@
+# Infrastructure
+
+基础设施文档目录。

docs/infrastructure/deployment.md

@@ -0,0 +1,7 @@
+# Deployment
+
+采用渐进式部署：
+
+`Docker Compose -> Container Platform -> Kubernetes`
+
+是否进入 Kubernetes 由服务数量、可用性、扩缩容和团队运维能力决定，而不是技术偏好。

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。

docs/infrastructure/docker.md

@@ -0,0 +1,10 @@
+# Docker
+
+Docker Compose 用于本地多服务编排。
+
+原则：
+
+- 服务配置环境化。
+- Secret 不提交 Git。
+- 数据卷用于开发持久化。
+- 每个服务保持单一职责。

docs/infrastructure/observability.md

@@ -0,0 +1,13 @@
+# Observability
+
+统一采用 OpenTelemetry 思路。
+
+三类信号：
+
+- Logs
+- Metrics
+- Traces
+
+Agent 特有 Trace：
+
+`Run -> Plan -> Model -> Memory -> Tool -> Observation -> Reflection`

docs/infrastructure/scaling.md

@@ -0,0 +1,13 @@
+# Scaling
+
+扩展顺序优先：
+
+1. 优化单体 Agent Runtime。
+2. 异步化长任务。
+3. 分离高并发 I/O。
+4. 增加缓存。
+5. 数据库读写优化。
+6. 按瓶颈拆分服务。
+7. 最后引入更复杂的分布式基础设施。
+
+避免过早微服务化。

docs/mcp/README.md

@@ -0,0 +1,3 @@
+# MCP
+
+MCP 集成文档目录。

docs/mcp/client.md

@@ -0,0 +1,16 @@
+# MCP Client
+
+支持：
+
+- stdio
+- SSE
+
+职责：
+
+- Server connection
+- Capability discovery
+- Tool discovery
+- Schema conversion
+- Invocation
+- Timeout
+- Error handling

docs/mcp/overview.md

@@ -0,0 +1,9 @@
+# MCP
+
+MCP 用于连接外部工具与上下文服务。
+
+内部架构：
+
+`MCP Client -> Transport -> MCP Server -> Tool Adapter -> Tool Runtime`
+
+MCP Server 提供的能力不能绕过内部权限和审计系统。

docs/mcp/security.md

@@ -0,0 +1,12 @@
+# MCP Security
+
+外部 MCP Server 默认视为不可信边界。
+
+必须：
+
+- 显式授权
+- 限制工具
+- 限制资源
+- 校验输入
+- 记录调用
+- 限制网络和文件权限

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 还是内部注册表。

docs/mcp/transport.md

@@ -0,0 +1,10 @@
+# MCP Transport
+
+Transport 只负责通信，不负责业务权限。
+
+支持：
+
+- stdio：本地进程
+- SSE：远程流式通信
+
+未来可根据 MCP 生态支持情况扩展其他传输方式。

docs/rag/README.md

@@ -0,0 +1,3 @@
+# RAG
+
+RAG 与知识系统文档目录。

docs/rag/chunking.md

@@ -0,0 +1,16 @@
+# Chunking
+
+## 原则
+
+优先保持语义完整性，而不是机械固定长度切分。
+
+考虑：
+
+- 标题层级
+- 段落
+- 代码块
+- 表格
+- 文档结构
+- Token 长度
+
+Chunk 必须携带可追溯 metadata。

docs/rag/embedding.md

@@ -0,0 +1,12 @@
+# Embedding
+
+Embedding 用于把文本、实体或其他内容映射到向量空间。
+
+要求：
+
+- 明确模型版本
+- 明确维度
+- 保存模型标识
+- 模型变更时考虑重建索引
+
+Embedding 与业务代码通过统一接口隔离。

docs/rag/evaluation.md

@@ -0,0 +1,13 @@
+# RAG Evaluation
+
+评估至少覆盖：
+
+- Recall
+- Precision
+- MRR
+- NDCG
+- Context Relevance
+- Answer Faithfulness
+- Citation / Source Accuracy
+
+评估集应版本化，模型、Embedding、Chunking 或检索策略发生重要变化时重新评估。

docs/rag/ingestion.md

@@ -0,0 +1,13 @@
+# RAG Ingestion
+
+流程：
+
+`File -> Parse -> Normalize -> Chunk -> Metadata -> Embedding -> Index`
+
+解析工具：
+
+- unstructured
+- PyMuPDF
+- MarkItDown
+
+每个 chunk 应保留来源、文档 ID、位置和版本信息。

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 提高上下文质量。

docs/rag/reranking.md

@@ -0,0 +1,9 @@
+# Reranking
+
+Reranker 用于对候选结果进行二次相关性排序。
+
+典型流程：
+
+`Recall -> Candidate Set -> Reranker -> Top K`
+
+Reranker 不是召回器，不能替代低成本高召回率的第一阶段检索。

docs/rag/retrieval.md

@@ -0,0 +1,12 @@
+# Retrieval
+
+支持：
+
+- BM25
+- Vector Search
+- Graph Search
+- Metadata Filter
+
+推荐采用多路召回后统一融合。
+
+检索必须保留 source metadata，确保最终上下文可追溯。

docs/security/README.md

@@ -0,0 +1,3 @@
+# Security
+
+安全体系文档目录。

docs/security/audit.md

@@ -0,0 +1,15 @@
+# Audit
+
+重要操作必须可审计：
+
+- user
+- run_id
+- tool
+- timestamp
+- input metadata
+- output metadata
+- permission decision
+- result
+- error
+
+敏感内容应脱敏。

docs/security/authentication.md

@@ -0,0 +1,7 @@
+# Authentication
+
+统一产生 Identity Context。
+
+业务层不应自己解析认证协议。
+
+认证方式由部署环境决定，核心系统依赖稳定的用户身份接口。

docs/security/authorization.md

@@ -0,0 +1,7 @@
+# Authorization
+
+采用 RBAC + Tool Permission + Resource Permission。
+
+权限检查应尽可能靠近实际资源访问点。
+
+默认拒绝，显式授权。

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

docs/security/prompt-injection.md

@@ -0,0 +1,11 @@
+# Prompt Injection
+
+防护采用多层策略：
+
+1. 外部内容标记为不可信数据。
+2. 工具调用不由文本指令直接决定权限。
+3. Tool Permission 独立于 LLM 输出。
+4. 高风险操作要求额外确认或策略。
+5. 对工具结果进行来源和内容分类。
+
+LLM Guard 等组件只是其中一层。

docs/security/sandbox.md

@@ -0,0 +1,19 @@
+# Sandbox
+
+高风险执行能力必须隔离。
+
+包括：
+
+- Code
+- Shell
+- Browser
+- File System
+
+限制：
+
+- CPU
+- Memory
+- Disk
+- Network
+- Process
+- Timeout

docs/services/README.md

@@ -0,0 +1,3 @@
+# Services
+
+Go 高并发服务文档目录。

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。

docs/testing/README.md

@@ -0,0 +1,3 @@
+# Testing
+
+测试与评估文档目录。

docs/testing/agent-evaluation.md

@@ -0,0 +1,13 @@
+# Agent Evaluation
+
+评估维度：
+
+- Task Success
+- Tool Selection
+- Plan Quality
+- Recovery
+- Hallucination
+- Cost
+- Latency
+
+评估数据集需要版本化。

docs/testing/integration.md

@@ -0,0 +1,13 @@
+# Integration Test
+
+覆盖：
+
+- PostgreSQL
+- Redis
+- VectorStore
+- GraphStore
+- FileStorage
+- MCP
+- Tool Runtime
+
+外部服务优先使用隔离测试环境或 Mock。

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 变化时应重新运行基准集。

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

docs/testing/unit.md

@@ -0,0 +1,12 @@
+# Unit Test
+
+单元测试重点：
+
+- Domain Logic
+- Planner
+- Memory Manager
+- Tool Schema
+- Permission
+- Data Transformation
+
+避免在单元测试中真实调用外部 LLM 或第三方 API。

docs/tools/README.md

@@ -0,0 +1,3 @@
+# Tools
+
+工具系统文档目录。

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 组合，而不是制作超大工具。

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

docs/tools/permissions.md

@@ -0,0 +1,12 @@
+# Tool Permissions
+
+权限至少区分：
+
+- User Permission
+- Agent Permission
+- Tool Permission
+- Resource Permission
+
+采用最小权限原则。
+
+权限检查必须发生在 Tool 执行之前。

docs/tools/registry.md

@@ -0,0 +1,14 @@
+# Tool Registry
+
+注册信息：
+
+- name
+- version
+- description
+- schema
+- permissions
+- timeout
+- retry
+- tags
+
+Registry 支持发现、版本控制和能力过滤。

docs/tools/sandbox.md

@@ -0,0 +1,14 @@
+# Tool Sandbox
+
+代码执行、Shell、文件系统等高风险工具必须运行在受控环境。
+
+安全目标：
+
+- 文件隔离
+- 网络限制
+- 资源限制
+- 超时
+- 进程隔离
+- 输出限制
+
+桌面端使用 Tauri Capabilities 控制本地系统能力；服务端使用独立 Sandbox。