NotesAgentic/docs/AI-Core与Agent-Core开发说明.md

AI Core 与 Agent Core 开发说明

本文档用于团队开发和模块联调，记录当前已经落地的核心边界与使用方式。

当前实现

当前已经建立第一条可运行链路：

FastAPI
→ Provider Registry
→ Agent Runtime
→ Permission Manager
→ Tool Registry
→ Agent Trace / SSE

对应代码：

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：

provider_id = mock
model       = mock-1

它支持：

chat
tool_calling
streaming

普通 Chat 请求：

{
  "provider_id": "mock",
  "model": "mock-1",
  "messages": [
    {"role": "user", "content": "hello"}
  ]
}

POST /api/chat 返回 ModelEvent SSE。

另外已经实现以下可配置 Adapter：

openai_chat / openai_compatible
ollama

创建 Ollama Provider：

{
  "provider_type": "ollama",
  "name": "Local Ollama",
  "base_url": "http://127.0.0.1:11434",
  "default_model": "qwen3:latest"
}

创建 OpenAI-Compatible Provider：

{
  "provider_type": "openai_compatible",
  "name": "OpenAI Compatible",
  "base_url": "https://api.openai.com/v1",
  "default_model": "<model>",
  "credential_id": "openai-main"
}

凭证 ID openai-main 对应 Sidecar 进程中的临时环境变量 AINOTE_CREDENTIAL_OPENAI_MAIN。环境变量由 Rust Host 从 Stronghold 读取后注入，不写入 Provider Config、日志或前端 Store。

Provider 配置生命周期接口已经可用：

GET    /api/providers
POST   /api/providers
GET    /api/providers/{provider_id}
PATCH  /api/providers/{provider_id}
DELETE /api/providers/{provider_id}
GET    /api/providers/{provider_id}/models
POST   /api/providers/test

Agent Run

创建普通 Agent Run：

{
  "input": "hello",
  "provider_id": "mock",
  "model": "mock-1",
  "max_steps": 10
}

请求：

POST /api/agent/runs

创建后通过以下接口读取状态和事件：

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：

system.echo
math.add

Mock Provider 使用下面的开发语法产生 Tool Call：

/tool system.echo {"text":"hello tool"}
/tool math.add {"left":1,"right":2}

Agent Run 需要显式声明 allowed_tools：

{
  "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 当前支持：

allow
confirm
deny

需要确认时，Agent 状态进入 waiting_permission，并发出 PermissionRequired 事件。前端使用：

POST /api/agent/runs/{run_id}/permissions/{request_id}

提交以下决策之一：

{"decision":"allow_once"}
{"decision":"allow_session"}
{"decision":"deny"}

默认需要确认的高影响权限包括 notes.write、notes.delete、network.request 和 secrets.use。

Knowledge / Retrieval 接入约定

其他成员完成服务后，通过注册 Tool 接入 Agent，不让 Agent Runtime 直接依赖具体实现：

tool_registry.register(
    definition=tool_definition,
    arguments_model=arguments_model,
    executor=executor,
)

建议第一批接入：

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。

当前限制与下一步

• 已实现 Mock、OpenAI-Compatible Chat Completions 与 Ollama Adapter；OpenAI Responses 和 Anthropic Messages 尚未实现。
• Provider 配置暂存内存，后续通过 Repository 接入 SQLite。
• Run/Trace 暂存内存；下一步抽象 Repository 并接入 SQLite。
• Permission 已有核心等待/恢复机制，前端确认 UI 尚未联调。
• Note/RAG Tool 等待对应模块 Service 接入。
• Skill/Plugin 将复用现有 Tool Registry 和 Permission Manager。