docs(agent): 更新 Agent 与 Extension Core 开发说明

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

@@ -12,6 +12,7 @@ FastAPI
 → Agent Runtime
 → Permission Manager
 → Tool Registry
+→ Skill Runtime / Plugin Runtime
 → Agent Trace / SSE
 ```
 
@@ -28,7 +29,13 @@ backend/app/
 │   ├── tools.py         Tool 注册、参数校验、隔离执行和结果转换
 │   ├── permissions.py   权限策略、确认请求和会话授权
 │   └── builtin_tools.py 无副作用的内置开发 Tool
+├── extensions/
+│   └── runtime.py       Skill/Plugin Manifest、生命周期、依赖与 Tool Contribution
 └── container.py         AI Core 依赖组装
+
+backend/extensions/
+├── skills/knowledge-assistant/   内置知识库 Skill
+└── plugins/text-tools/           内置示例 Plugin
 ```
 
 Router 只负责 HTTP/SSE 与错误转换，不实现 Agent、Tool 或 Provider 业务逻辑。
@@ -43,7 +50,11 @@ Router 只负责 HTTP/SSE 与错误转换，不实现 Agent、Tool 或 Provider
 - Tool 参数校验与执行隔离；
 - Permission；
 - Step、Timeout、Token Budget、取消；
+- Tool 并发上限与 run 级网络权限；
 - 内存 Trace 与 SSE；
+- Skill Manifest、Prompt、Tool/Permission/模型能力解析；
+- Plugin Manifest、生命周期和 Tool Contribution；
+- Skill 调用内置 Tool 与 Plugin Tool；
 - 公共 Contract 和 API 接入。
 
 以下内容保持接口，不在本模块实现：
@@ -51,7 +62,7 @@ Router 只负责 HTTP/SSE 与错误转换，不实现 Agent、Tool 或 Provider
 - Note、NoteBlock、Markdown Parser：由 Knowledge Core 提供；
 - FTS5、Vector、RRF、Reranker、Citation：由 Retrieval Core 提供；
 - 文件系统和 API Key 明文读取：由 Rust Host 提供；
-- Skill、Plugin 生命周期：后续在 Extension Core 中实现。
+- MCP Plugin Host、Frontend Extension Slot：按技术基线放在第二阶段实现。
 
 ## Provider
 
@@ -159,11 +170,17 @@ POST /api/agent/runs/{run_id}/cancel
 
 ## Tool Calling
 
-当前注册两个无副作用开发 Tool：
+当前注册以下内置 Tool：
 
 ```text
 system.echo
 math.add
+notes.search
+rag.search
+notes.read
+notes.create
+notes.update
+notes.list
 ```
 
 Mock Provider 使用下面的开发语法产生 Tool Call：
@@ -186,6 +203,8 @@ Agent Run 需要显式声明 `allowed_tools`：
 
 Tool 参数由独立 Pydantic Model 再次校验。Tool 的异常、非法参数、超时和权限拒绝统一转换为 `ToolResult`，不会直接打断 API 进程。
 
+`notes.search` / `rag.search` 返回的 Citation 会由 Agent Runtime 收集到 `AgentRun.citations`，并产生 `Citation` Trace Event。Note 写操作调用 `note_service`，检索调用 Retrieval Engine，不直接访问 SQLite。
+
 ## Permission
 
 Permission Policy 当前支持：
@@ -212,9 +231,9 @@ POST /api/agent/runs/{run_id}/permissions/{request_id}
 
 默认需要确认的高影响权限包括 `notes.write`、`notes.delete`、`network.request` 和 `secrets.use`。
 
-## Knowledge / Retrieval 接入约定
+## Knowledge / Retrieval 接入
 
-其他成员完成服务后，通过注册 Tool 接入 Agent，不让 Agent Runtime 直接依赖具体实现：
+Knowledge Core 与 Retrieval Core 已通过 Tool Registry 接入 Agent。Agent Runtime 仍只依赖 Tool Contract，不直接依赖具体服务：
 
 ```python
 tool_registry.register(
@@ -224,7 +243,7 @@ tool_registry.register(
 )
 ```
 
-建议第一批接入：
+第一批已经接入：
 
 ```text
 notes.search
@@ -232,20 +251,71 @@ 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。
 
+## Extension Core
+
+### Skill Runtime
+
+Skill Package 由 `skill.yaml` 和可选 `prompt.md` 组成。安装时使用 Pydantic 校验 Manifest，并解析：
+
+```text
+permissions
+tools
+retrieval
+model.required_capabilities
+```
+
+Skill 启用前检查 Tool 是否已注册、Tool 所需权限是否已在 Manifest 声明。创建 Agent Run 时，Skill Runtime 生成 Agent Configuration，注入 System Prompt、允许的 Tool、权限和 Retrieval Config。模型缺少 `chat`、`tool_calling` 等必要 Capability 时拒绝启动。
+
+生命周期接口：
+
+```text
+GET    /api/skills
+POST   /api/skills/install
+GET    /api/skills/{skill_id}
+POST   /api/skills/{skill_id}/enable
+POST   /api/skills/{skill_id}/disable
+DELETE /api/skills/{skill_id}
+```
+
+### Plugin Runtime
+
+第一阶段 Plugin Runtime 完成 Manifest 校验、安装、启用、停用、卸载和 Tool Contribution。第三方代码不会直接 import 到 AI Core；当前 Declarative Plugin Host 只执行宿主实现的白名单 handler，MCP Host 留到第二阶段。
+
+启用 Plugin 时将 Tool 注册到统一 Tool Registry，并标记 `source=plugin`；停用或异常时注销 Tool。启用中的 Skill 依赖某 Plugin Tool 时，Plugin 不能直接卸载。
+
+生命周期接口：
+
+```text
+GET    /api/plugins
+POST   /api/plugins/install
+GET    /api/plugins/{plugin_id}
+POST   /api/plugins/{plugin_id}/enable
+POST   /api/plugins/{plugin_id}/disable
+DELETE /api/plugins/{plugin_id}
+```
+
+内置示例 `text-tools` 注册 `text.uppercase`。内置 `knowledge-assistant` Skill 同时声明 `notes.search` 和 `text.uppercase`，用于验证完整链路：
+
+```text
+Skill Manifest
+→ Agent Configuration
+→ Tool Registry
+→ Plugin Tool
+→ Tool Result
+→ Agent Loop
+```
+
 ## 当前限制与下一步
 
 - 已实现 Mock、OpenAI-Compatible Chat Completions 与 Ollama Adapter；OpenAI Responses 和 Anthropic Messages 尚未实现。
 - Provider 配置暂存内存，后续通过 Repository 接入 SQLite。
 - Run/Trace 暂存内存；下一步抽象 Repository 并接入 SQLite。
 - Permission 已有核心等待/恢复机制，前端确认 UI 尚未联调。
-- Note/RAG Tool 等待对应模块 Service 接入。
+- Task、Attachment、Audio Tool 尚未接入。
-- Skill/Plugin 将复用现有 Tool Registry 和 Permission Manager。
+- Extension 安装记录暂存内存；后续接入持久化 Registry 与版本升级流程。
+- 当前 Plugin Host 只支持内置声明式白名单 handler；MCP Bridge、独立进程健康检查与 UI Contribution 在第二阶段实现。