实现 AI Core 与 Agent Core 基础功能

- 更新 README 描述从后端壳子到 AI Core/Agent Core - 添加 ToolCall 和 ToolResult 数据结构定义 - 扩展 AgentRun 模型增加输出、错误码、工具调用结果等字段 - 添加 mock 提供商类型支持 - 实现聊天、代理运行、工具调用和提供商管理的核心路由逻辑 - 集成容器化依赖注入和错误处理机制 - 更新 API 接口契约和文档说明
2026-08-27 13:55:00 +08:00
parent ce155b27f4
commit b71984d951
18 changed files with 1369 additions and 40 deletions
@@ -0,0 +1,206 @@
+# AI Core 与 Agent Core 开发说明
+
+> 本文档用于团队开发和模块联调，记录当前已经落地的核心边界与使用方式。
+
+## 当前实现
+
+当前已经建立第一条可运行链路：
+
+```text
+FastAPI
+→ Provider Registry
+→ Agent Runtime
+→ Permission Manager
+→ Tool Registry
+→ Agent Trace / SSE
+```
+
+对应代码：
+
+```text
+backend/app/
+├── providers/
+│   ├── base.py          Provider Protocol 与统一 Turn
+│   ├── registry.py      Provider 注册、发现、模型列表和连接测试
+│   └── mock.py          离线开发 Provider
+├── agent/
+│   ├── runtime.py       Agent Loop、限制、取消、Trace 和 SSE
+│   ├── tools.py         Tool 注册、参数校验、隔离执行和结果转换
+│   ├── permissions.py   权限策略、确认请求和会话授权
+│   └── builtin_tools.py 无副作用的内置开发 Tool
+└── container.py         AI Core 依赖组装
+```
+
+Router 只负责 HTTP/SSE 与错误转换，不实现 Agent、Tool 或 Provider 业务逻辑。
+
+## 模块边界
+
+当前实现属于范涵宇负责的 AI Core / Agent Core：
+
+- Provider 抽象与注册；
+- Agent Run 生命周期；
+- Tool Registry；
+- Tool 参数校验与执行隔离；
+- Permission；
+- Step、Timeout、Token Budget、取消；
+- 内存 Trace 与 SSE；
+- 公共 Contract 和 API 接入。
+
+以下内容保持接口，不在本模块实现：
+
+- Note、NoteBlock、Markdown Parser：由 Knowledge Core 提供；
+- FTS5、Vector、RRF、Reranker、Citation：由 Retrieval Core 提供；
+- 文件系统和 API Key 明文读取：由 Rust Host 提供；
+- Skill、Plugin 生命周期：后续在 Extension Core 中实现。
+
+## 开发 Provider
+
+默认注册离线 Provider：
+
+```text
+provider_id = mock
+model       = mock-1
+```
+
+它支持：
+
+```text
+chat
+tool_calling
+streaming
+```
+
+普通 Chat 请求：
+
+```json
+{
+  "provider_id": "mock",
+  "model": "mock-1",
+  "messages": [
+    {"role": "user", "content": "hello"}
+  ]
+}
+```
+
+`POST /api/chat` 返回 ModelEvent SSE。
+
+## Agent Run
+
+创建普通 Agent Run：
+
+```json
+{
+  "input": "hello",
+  "provider_id": "mock",
+  "model": "mock-1",
+  "max_steps": 10
+}
+```
+
+请求：
+
+```text
+POST /api/agent/runs
+```
+
+创建后通过以下接口读取状态和事件：
+
+```text
+GET /api/agent/runs/{run_id}
+GET /api/agent/runs/{run_id}/events
+POST /api/agent/runs/{run_id}/cancel
+```
+
+当前 Run 与 Trace 保存在内存中，AI Core 重启后清空。后续数据库层接入时替换 Repository，不改变 API Contract。
+
+## Tool Calling
+
+当前注册两个无副作用开发 Tool：
+
+```text
+system.echo
+math.add
+```
+
+Mock Provider 使用下面的开发语法产生 Tool Call：
+
+```text
+/tool system.echo {"text":"hello tool"}
+/tool math.add {"left":1,"right":2}
+```
+
+Agent Run 需要显式声明 `allowed_tools`：
+
+```json
+{
+  "input": "/tool math.add {\"left\":1,\"right\":2}",
+  "provider_id": "mock",
+  "model": "mock-1",
+  "allowed_tools": ["math.add"]
+}
+```
+
+Tool 参数由独立 Pydantic Model 再次校验。Tool 的异常、非法参数、超时和权限拒绝统一转换为 `ToolResult`，不会直接打断 API 进程。
+
+## Permission
+
+Permission Policy 当前支持：
+
+```text
+allow
+confirm
+deny
+```
+
+需要确认时，Agent 状态进入 `waiting_permission`，并发出 `PermissionRequired` 事件。前端使用：
+
+```text
+POST /api/agent/runs/{run_id}/permissions/{request_id}
+```
+
+提交以下决策之一：
+
+```json
+{"decision":"allow_once"}
+{"decision":"allow_session"}
+{"decision":"deny"}
+```
+
+默认需要确认的高影响权限包括 `notes.write`、`notes.delete`、`network.request` 和 `secrets.use`。
+
+## Knowledge / Retrieval 接入约定
+
+其他成员完成服务后，通过注册 Tool 接入 Agent，不让 Agent Runtime 直接依赖具体实现：
+
+```python
+tool_registry.register(
+    definition=tool_definition,
+    arguments_model=arguments_model,
+    executor=executor,
+)
+```
+
+建议第一批接入：
+
+```text
+notes.search
+notes.read
+notes.create
+notes.update
+notes.list
+notes.move
+rag.search
+tasks.create
+tasks.update
+tasks.list
+```
+
+写操作 Executor 调用 Knowledge Core Service，不直接访问 SQLite；检索 Executor 调用 Retrieval Core Service，不直接拼接 FTS5 或 sqlite-vec SQL。
+
+## 当前限制与下一步
+
+- Provider 目前只有完全离线的 Mock 实现；下一步实现 OpenAI-Compatible 与 Ollama Adapter。
+- Run/Trace 暂存内存；下一步抽象 Repository 并接入 SQLite。
+- Permission 已有核心等待/恢复机制，前端确认 UI 尚未联调。
+- Note/RAG Tool 等待对应模块 Service 接入。
+- Skill/Plugin 将复用现有 Tool Registry 和 Permission Manager。
@@ -151,9 +151,10 @@ RunFailed
 RunCancelled
 ```

-## 当前壳子行为
+## 当前实现状态

- 列表、搜索、索引状态等只读接口返回符合 Contract 的空结果或 `idle` 状态。
- Chat 与 Agent Events 返回符合 SSE 格式的 `NOT_IMPLEMENTED` 事件。
- 需要数据库、文件、模型或 Runtime 的操作统一返回 `501`。
+- Chat、Agent Run、Agent Events、Tool 列表、Provider 列表、模型列表和连接测试已经接入 AI Core。
+- 默认提供 `mock/mock-1` 离线 Provider，以及 `system.echo`、`math.add` 开发 Tool。
+- Notes、Search、Skills、Plugins、Tasks、Media、Index 等尚未接入业务服务的接口继续返回空结果、`idle` 或 `501`。
+- 需要尚未接入的数据库、文件或扩展 Runtime 的操作统一返回 `501`。
 - 接入业务模块时保持当前路径和 Contract，不在 Router 中直接实现数据库、Provider 或 Agent 逻辑。