完善文档

AGENTS.md

@@ -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

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。