From 28278cd735d13c641c748ac3b7bc2cb375d0f560 Mon Sep 17 00:00:00 2001 From: weichen Date: Tue, 29 Sep 2026 17:20:52 +0000 Subject: [PATCH] R3: add ingest parsing pipeline (MinerU as optional fallback/cross-check) Details (original message): R3: add ingest parsing pipeline (MinerU as optional fallback/cross-check), RAG retrieval, memory system designs; expand context management with budgeting; add model routing kinds for embedding/rerank. --- ...6-09-29-system-skeleton-design-and-plan.md | 212 ++++++++++++------ 1 file changed, 143 insertions(+), 69 deletions(-) diff --git a/docs/proposals/2026-09-29-system-skeleton-design-and-plan.md b/docs/proposals/2026-09-29-system-skeleton-design-and-plan.md index d899cfa..8ecefbc 100644 --- a/docs/proposals/2026-09-29-system-skeleton-design-and-plan.md +++ b/docs/proposals/2026-09-29-system-skeleton-design-and-plan.md @@ -1,9 +1,11 @@ # Agent-System 对话系统骨架：设计、方案与实施计划 -状态：**待审（r2，按 2026-09-29 用户指示修订）**；owner：weichen；主任务：本文档自身（批准后拆分为各阶段主任务记录）。 +状态：**待审（r3，按 2026-09-29 用户两轮指示修订）**；owner：weichen；主任务：本文档自身（批准后拆分为各阶段主任务记录）。 授权与交付终点：本文档为设计 + 方案 + 计划，**不含实现**。批准后按第 7 节阶段逐项开工。 规范基线：Development-Guidelines（`development/guidelines` submodule，Dev 仓固定版本）。 -撰写日期：2026-09-29。r2 修订：领域插件（CDMO、法规知识库）移出本计划进远期路线，届时按新系统特性**全新设计**（不兼容、不迁移老系统）；骨架设计扩充扩展性与定制性章节（4.1、4.7–4.16）。 +撰写日期：2026-09-29。 +r2 修订：领域插件（CDMO、法规知识库）移出本计划进远期路线，届时按新系统特性全新设计（不兼容、不迁移老系统）；扩充扩展性与定制性章节。 +r3 修订：新增文档摄取与解析管线（4.11，MinerU 定位为备选/交叉验证）、RAG 检索管线（4.12）、记忆系统（4.13）设计；上下文管理扩充为预算化分层管线（4.10）；模型路由增加 embedding/rerank 类别（4.7）。 --- @@ -20,7 +22,9 @@ 系统必须提供**插件机制**：骨架保证一个通用智能体的使用与功能；领域能力（例：医疗器械 CDMO 工作流、法规知识库检索）**之后**通过插件接入。 -**2026-09-29 修订指示**：当前**先不实现**医疗器械 CDMO 等领域插件与功能，仅纳入之后的实现计划；届时实现**不需要兼容老系统**，要根据新系统的特性为新系统全新设计。先保证通用智能体系统的骨架，尽可能设计完善，多考虑可扩展性、可定制性等方向。 +**2026-09-29 修订指示（r2）**：当前**先不实现**医疗器械 CDMO 等领域插件与功能，仅纳入之后的实现计划；届时实现**不需要兼容老系统**，要根据新系统的特性为新系统全新设计。先保证通用智能体系统的骨架，尽可能设计完善，多考虑可扩展性、可定制性等方向。 + +**2026-09-29 修订指示（r3）**：老系统使用了 MinerU、Embedding、Reranker，新系统可以考虑使用。但 **MinerU 要尤其注意**——用户在老系统实际测试过，确实能解析文档但能力有限；现在很多智能体直接编写代码解析 docx/pdf/ppt，可借鉴该思路，MinerU 作为备选或交叉验证，或考虑弃用。系统还需考虑之后的 **RAG、记忆系统、上下文管理**等机制功能，考虑全面。以上为思路，按系统设计与需求实际情况落实。 核心诉求：**充分的可扩展性、可定制性**；新功能以插件接入，不破坏已有功能、不需要大规模重新开发、不与核心过度耦合。 @@ -28,7 +32,8 @@ | 事实 | 证据 | |---|---| -| `Agent-System` 是老系统仓库，新系统**不做迁移**，仅作领域业务知识参考（流程、术语、文档体系） | 远端默认分支 `dev`，内容为单体（Go 后端 + React 19 前端 `shuimu-workbench`）；本地 `Agent-System` 与 `agent-system-multi` 均指向它。用户记忆确认正确，r2 再确认：**不迁移、不兼容、不搬代码** | +| `Agent-System` 是老系统仓库，新系统**不做迁移**，仅作领域业务知识与机制参考 | 远端默认分支 `dev`，内容为单体（Go 后端 + React 19 前端 `shuimu-workbench`）；本地 `Agent-System` 与 `agent-system-multi` 均指向它。用户记忆确认正确，r2 再确认：不迁移、不兼容、不搬代码 | +| 老系统已实测：MinerU 可解析文档但**能力有限**；Embedding 与 Reranker 服务在用 | 用户实测结论（r3 输入）；老系统 `internal/mineru`、`internal/kb`、`internal/dataset` 等。处置：MinerU 降级为备选/交叉验证（4.11，D12）；Embedding/Reranker 的部署经验直接复用（4.7、4.12） | | CDMO 领域知识位置（仅参考） | 老系统 `internal/`（docgov、docrevision、workflowdef、bizdev、squad、kb 等）、`configs/agents/`；`~/projects/08-Regulations` 为法规资料 | | `Agent-System-Dev / Core / Frontend / Backend / Documents / Releases` 六仓在 Gitea 已建、**全部为空仓**（默认分支 main） | Gitea API 查询（2026-09-29） | | 可复用生态已建成 | `Agent-Native`（执行内核）、`Agent-Squad`（编排底座，含 HITL）、`Agent-Intent`（意图识别，入口闸门 + 能力目录，2026-09-29 完成两轮接入）、`Error-Code-System`、`Logging-System`，均有远端描述与固定 gitlink 关系 | @@ -48,17 +53,18 @@ 1. **完善的通用智能体骨架**：三栏 UI + 流式对话（正文/思考/工具区分与折叠）+ HITL 卡片 + sub-agent 追踪 + 文档工件 + 可定制的模型/智能体/工具/上下文/界面，端到端走通，且每个可定制点不改代码即可调整。 2. **插件机制完备并经示例验证**：五类注册能力（工具/工作流/意图/知识/UI）+ 声明资产热加载 + 装卸回退语义；用一个**最小示例插件**验证机制（装卸不破坏核心）。领域插件（CDMO、法规）**不在本计划实现**。 -3. **仓网组织**：所有 submodule 独立、通用、可复用、易维护、可扩展；`Agent-System-Dev` 为开发集成父仓，`Agent-System-Releases` 只做打包分发。 -4. **规范落地**：开发全程按 Development-Guidelines 执行（阶段方案、验证记录、pin 纪律、模块卡）。 +3. **重能力子系统契约完备**：文档摄取解析、RAG 检索、记忆系统、上下文管理的契约与数据位在本设计中定稿（4.10–4.13），骨架期落最小实现，增强能力按远期路线增量落地——扩展不等待，落地不破坏。 +4. **仓网组织**：所有 submodule 独立、通用、可复用、易维护、可扩展；`Agent-System-Dev` 为开发集成父仓，`Agent-System-Releases` 只做打包分发。 +5. **规范落地**：开发全程按 Development-Guidelines 执行（阶段方案、验证记录、pin 纪律、模块卡）。 ### 2.2 非目标 - **本计划不实现领域插件**：CDMO 工作流、法规知识库进入远期路线（7.2 节）；届时按新系统插件契约**全新设计**——不迁移老系统代码、不兼容老系统接口、不复用其数据格式；老系统仅作领域业务知识参考。 +- **重能力子系统只落契约与最小实现**：向量 RAG 管线、跨会话记忆、代码执行工具、历史滚动压缩进远期路线（7.2）；本计划交付其契约与数据位预留，保证届时接入不改核心。 - 骨架期不做多租户、计费、公开注册；单用户（个人部署）起步，但数据模型预留 owner 字段。 - 不追求移动端；桌面浏览器优先（布局用响应式组件，不为移动端专门优化）。 - 不自研 LLM 接入层——复用 Agent-Native。 - v1 不做插件市场 / 在线安装；插件以仓为单位、构建期组装（热加载仅限声明性资产，见 4.6）。 -- 跨会话长期记忆、MCP 外部工具适配、CLI 客户端：契约预留扩展位，实现进远期路线。 --- @@ -74,8 +80,8 @@ | 仓库 | 角色 | 职责一句话 | Gitea 描述（P0 写入） | |---|---|---|---| -| **Agent-System-Core** | 契约仓（build-required） | 系统核心契约：领域模型、流式事件协议、HITL 卡片协议、插件 API 与 manifest、设置 schema、UI 扩展词汇（JSON Schema / TS 类型） | 系统核心契约：领域模型、流式事件与 HITL 卡片协议、插件 API、设置与 UI 扩展词汇，供前后端与插件共同依赖；不含实现。 | -| **Agent-System-Backend** | 后端仓（build-required） | Go 模块化单体：会话/项目域、流式管道、Run 管理、sub-agent 管理、工具注册、智能体画像、上下文组装、设置、工件存储、插件宿主、持久化；组合 Agent-Native/Squad/Intent | 对话系统后端：会话与流式管道、智能体运行时与画像、工具/上下文/设置管理、插件宿主（组合 Agent-Native/Squad/Intent）；依赖 Agent-System-Core 契约。 | +| **Agent-System-Core** | 契约仓（build-required） | 系统核心契约：领域模型、流式事件协议、HITL 卡片协议、插件 API 与 manifest、设置 schema、UI 扩展词汇、文档解析与检索与记忆契约（JSON Schema / TS 类型） | 系统核心契约：领域模型、流式事件与 HITL 卡片协议、插件 API、设置与 UI 扩展词汇、文档解析/检索/记忆契约，供前后端与插件共同依赖；不含实现。 | +| **Agent-System-Backend** | 后端仓（build-required） | Go 模块化单体：会话/项目域、流式管道、Run 管理、sub-agent 管理、工具注册、智能体画像、上下文管理、文档摄取解析、检索管线、设置、工件存储、插件宿主、持久化；组合 Agent-Native/Squad/Intent | 对话系统后端：会话与流式管道、智能体运行时与画像、工具/上下文/文档解析/检索/设置管理、插件宿主（组合 Agent-Native/Squad/Intent）；依赖 Agent-System-Core 契约。 | | **Agent-System-Frontend** | 前端仓（build-required） | React 19 + Vite + TS：三栏布局、流式渲染、消息成分折叠、HITL 卡片、右栏面板、sub-agent 弹窗、schema 驱动的设置与扩展渲染器 | 对话系统前端：三栏工作台（项目会话 / 流式对话 / 计划与工件面板），含 HITL 卡片、sub-agent 追踪弹窗与 schema 驱动的设置/插件 UI 渲染；渲染协议由 Agent-System-Core 定义。 | | **Agent-System-Documents** | 文档/过程仓（development-only） | 系统级文档：架构、ADR、插件开发指南、跨仓过程记录（方案/验证/交接）；本方案文档即首篇 | 系统文档与过程记录仓：架构决策、方案与验证记录、插件开发指南；不含产品代码。 | | **Agent-System-Dev** | 开发集成父仓（development-only） | submodule 集成全部模块；顶层构建/测试编排、开发环境（compose）、跨仓任务记录入口；**非分发单元** | 开发集成仓：以 submodule 固定全部模块组合，承载跨仓构建、测试编排与开发环境；发布物在 Agent-System-Releases。 | @@ -83,7 +89,7 @@ | Agent-Native / Agent-Squad / Agent-Intent | 生态 submodule（build-required） | 执行内核 / 编排底座（含 HITL）/ 意图闸门与能力目录 | 已有描述，不变 | | Error-Code-System / Logging-System | 基础设施 submodule | 错误码 / 日志 | 已有描述，不变 | | Development-Guidelines | 规范 submodule（development-only） | 开发规范，路径 `development/guidelines` | 已有描述，不变 | -| Agent-System | **冻结参考仓** | 老系统，只读领域知识参考；不进 Dev 仓组合 | P0 补描述：老系统参考仓（冻结）：新系统不迁移、不兼容；仅作领域业务知识参考。 | +| Agent-System | **冻结参考仓** | 老系统，只读领域知识与机制参考；不进 Dev 仓组合 | P0 补描述：老系统参考仓（冻结）：新系统不迁移、不兼容；仅作领域业务知识与机制参考。 | | Agent-System-Plugin-CDMO（远期新建） | 领域插件仓 | 医疗器械 CDMO 工作流插件：基于新系统插件契约全新设计 | （远期建仓时写）CDMO 工作流插件：按新系统插件契约全新设计，注册工作流、意图、文档模板与面板。 | | Agent-System-Plugin-Regulations（远期新建） | 领域插件仓 | 法规知识库插件 | （远期建仓时写）法规知识库插件：注册法规检索工具与知识面板。 | | SMDF-Agent-System | 待澄清 | 空仓，用途不明 | 暂不使用，待用户澄清 | @@ -112,23 +118,24 @@ Releases ──(版本 manifest 引用)──→ Dev 固定组合的制品 ## 4. 系统架构 -### 4.1 设计总则：六条扩展性原则 +### 4.1 设计总则：七条扩展性原则 本系统的可扩展性不是事后补丁，而是由以下机制原则保证（每条都对应下文具体设计）： 1. **API-first**：后端全部能力走公开 HTTP + SSE API，前端只是第一个客户端。任何功能（面板、卡片、命令）先有 API 再有 UI；Core 同步发布 OpenAPI 规范与生成的 TS client。CLI、其他客户端、远程访问后接不改后端。 -2. **数据即能力**：工作流、意图、提示词、文档模板、命令、UI 面板、用户自定义工具尽量表达为**声明性数据**（JSON/MD），热加载，不触碰核心二进制（4.6、4.8、4.11）。 -3. **Schema 驱动 UI**：设置界面、插件面板、HITL 表单卡片共用一套**有限词汇的 UI schema 渲染器**（4.6、4.9、4.12）。新增配置项或插件面板不需要前端开发。 -4. **统一注册表 + 来源标记**：工具、命令、面板、意图、卡片全部经统一注册表注册并标记来源（builtin / plugin / user / profile）。运行时可枚举「当前生效的能力来自谁」，可按来源一键禁用——既是排障对照（Guidelines 故障定位），也是定制入口（4.8）。 -5. **一切可禁用，T0 永远可用**：工具可禁用、面板可隐藏、插件可卸载、意图目录可清空。全部扩展关闭后系统退化为纯通用对话骨架，作为永恒的回归对照基线。 -6. **契约版本化与前向兼容**：事件协议、插件 API、UI schema 各带版本；消费方对未知 `type`/词汇静默忽略；扩展走「新增字段/新增类型 → 双端兼容窗口 → 弃用」流程（5 节）。 +2. **数据即能力**：工作流、意图、提示词、文档模板、命令、UI 面板、用户自定义工具尽量表达为**声明性数据**（JSON/MD），热加载，不触碰核心二进制（4.6、4.8、4.14）。 +3. **Schema 驱动 UI**：设置界面、插件面板、HITL 表单卡片共用一套**有限词汇的 UI schema 渲染器**（4.6、4.9、4.15）。新增配置项或插件面板不需要前端开发。 +4. **统一注册表 + 来源标记**：工具、命令、面板、意图、卡片、**解析器**全部经统一注册表注册并标记来源（builtin / plugin / user / profile）。运行时可枚举「当前生效的能力来自谁」，可按来源一键禁用——既是排障对照（Guidelines 故障定位），也是定制入口（4.8）。 +5. **一切可禁用，T0 永远可用**：工具可禁用、面板可隐藏、插件可卸载、意图目录可清空、记忆默认关闭。全部扩展关闭后系统退化为纯通用对话骨架，作为永恒的回归对照基线。 +6. **契约版本化与前向兼容**：事件协议、插件 API、UI schema、**解析与检索与记忆契约**各带版本；消费方对未知 `type`/词汇静默忽略；扩展走「新增字段/新增类型 → 双端兼容窗口 → 弃用」流程（5 节）。 +7. **契约先行、增量落地**：每个重能力子系统（文档解析、RAG、记忆、上下文管理）都先定契约与数据位，骨架期落**最小可用实现**（能支撑端到端价值流），增强能力按远期路线落地——扩展需求不等待设计，落地不破坏契约。 **总体形态**： -- **后端**：Go 模块化单体（module-contracts L1 逻辑隔离起步），进程内模块以公开契约互调；重负载模块（知识索引等）预留 L2 sidecar 升级位。 +- **后端**：Go 模块化单体（module-contracts L1 逻辑隔离起步），进程内模块以公开契约互调；重负载模块（MinerU 深度解析、向量索引等）预留 L2 sidecar 升级位。 - **前端**：React 19 + Vite + TypeScript SPA（沿用老系统技术栈经验：虚拟滚动、docx 预览、mermaid、katex）。 - **传输**：REST（Query/Command）+ SSE（Stream）。SSE 事件 = Core 定义的统一事件信封。 -- **持久化**：PostgreSQL（会话、消息、Run、HITL、画像、设置、注册表、用量）+ 本地对象目录（上传文件与工件，预留 S3 适配位）。 +- **持久化**：PostgreSQL（会话、消息、Run、HITL、画像、设置、注册表、用量、记忆与索引 schema 预留）+ 本地对象目录（上传文件与工件，预留 S3 适配位）。向量检索默认 pgvector（D13），复用同一 PG 实例。 ### 4.2 核心抽象：一切运行皆 Run、一切增量皆事件 @@ -159,12 +166,12 @@ Run { "payload": { } } ``` -- `run.completed` payload 附 `usage`（token/时长/工具调用数），支撑用量统计（4.14）。 +- `run.completed` payload 附 `usage`（token/时长/工具调用数），支撑用量统计（4.17）。 - Stream 契约按规范补齐：游标 = `Last-Event-ID`（seq）；断连重连从游标续传；终态对账 = 会话详情 Query 返回权威消息树，前端以 Query 为准收敛（丢弃未确认的流式残片）。 - **并发策略**：v1 会话内串行（一个会话同时至多一个在途 run），但协议与事件路由按 run_id 设计为天然支持并行——未来开启并行子任务不破坏协议。 - **中断恢复策略**：后端重启时在途 run 标记 `interrupted` 并在 UI 提示，用户可一键重发；不做透明恢复（避免分布式续跑复杂度，远期再议）。 -**消息模型**：`Message { id, role, parts: [Part] }`，`Part` 多态（text / thinking / tool_call / tool_result / artifact_ref / hitl / plan / error / **card**——插件自定义卡片，4.6）。流式过程中 parts 逐个追加；**run 终态后前端将过程 parts（thinking/tool）折叠为摘要行**（如「思考了 12s · 调用 3 个工具」），点击展开回看——折叠是纯前端呈现策略，事件与数据不删；折叠默认行为可由用户偏好设置（4.12）。 +**消息模型**：`Message { id, role, parts: [Part] }`，`Part` 多态（text / thinking / tool_call / tool_result / artifact_ref / hitl / plan / error / **card**——插件自定义卡片，4.6）。流式过程中 parts 逐个追加；**run 终态后前端将过程 parts（thinking/tool）折叠为摘要行**（如「思考了 12s · 调用 3 个工具」），点击展开回看——折叠是纯前端呈现策略，事件与数据不删；折叠默认行为可由用户偏好设置（4.15）。 ### 4.3 后端模块划分（组合根装配，模块卡在 Backend 仓 `policy/modules/` 维护） @@ -174,25 +181,28 @@ Run { | runmgr | Run 生命周期、事件产生与持久化、游标、取消传播（父 run 取消 → 子 run 级联） | Command（幂等 run 创建）+ Event | | streamhub | SSE 通道、订阅、断线续传、终态对账数据 | Stream | | runtime | 智能体执行适配：Agent-Native（主对话 + 工具）、Agent-Squad（sub-agent 编排） | 进程内窄接口；失败映射稳定错误码 | -| intentgate | Agent-Intent 接入：入口闸门 + 能力目录注入规划 + `/`命令识别（4.11） | 可选装配，未配置 = 行为回退（T0 底线沿用其纪律） | +| intentgate | Agent-Intent 接入：入口闸门 + 能力目录注入规划 + `/`命令识别（4.14） | 可选装配，未配置 = 行为回退（T0 底线沿用其纪律） | | toolreg | 工具注册表：内置/插件/声明式 HTTP 工具统一注册、schema 校验、启用开关、调用审计、确认策略 | Query/Command | | profiles | 智能体画像 CRUD、导入导出（4.7） | Query/Command | -| ctxasm | 上下文组装：按 ContextPolicy 生成模型输入（4.10） | 内部服务 + Query | +| ctxasm | 上下文组装与预算管理：按 ContextPolicy 生成模型输入（4.10） | 内部服务 + Query | +| ingest | 文档摄取与解析：上传→ParsedDocument→各消费方；解析器注册表与策略（4.11） | Command + Event（索引进度） | +| retrieval | 检索管线：全文最小实现；RAG 契约与向量位预留（4.12） | Query | +| memory | 记忆存取与策略：schema 预留、契约先立，实现远期（4.13） | Query/Command | | settings | 分层设置存取、schema 校验、生效通知（4.9） | Query/Command + Event | -| registry | 统一注册表：工具/命令/面板/意图/卡片的注册、来源标记、按来源启停（4.1 原则 4） | Query/Command | +| registry | 统一注册表：工具/命令/面板/意图/卡片/解析器的注册、来源标记、按来源启停（4.1 原则 4） | Query/Command | | hitl | HITL 卡片生命周期：发起、挂起 run、响应路由（选中项 vs 自由输入再识别）、超时 | Command + Event | | artifacts | 上传文件、Agent 产出文档、版本与引用 | Query/Command | | planboard | 计划 / 步骤 / to-dos 状态（Agent 产出 + 用户可读） | Query/Command + Event | | pluginhost | 插件发现、manifest 校验、能力注册、声明资产热加载（4.6） | Command + Event | -| observability | Logging/Errcode 对齐、进度归属、事件重放、用量归集（4.14） | Event | +| observability | Logging/Errcode 对齐、进度归属、事件重放、用量归集（4.17） | Event | ### 4.4 前端结构 - **左栏 `ProjectNav`**：项目折叠组 → 会话列表；底部账户/设置入口；宽度拖拽（min 220 / max 420 px，可配置）；拖拽越过最小阈值并继续（约 40px 超调）→ 松手收起；收起态为图标窄栏；分隔条双击切换。宽度与收起态持久化（服务端偏好 + localStorage 双写）。 -- **中栏 `Conversation`**：虚拟滚动消息流；**Part 渲染器注册表**（按 part 类型查表 → 组件，插件卡片类型经 schema 渲染）；流式增量渲染；run 终态触发过程折叠（可展开）；输入区：文件上传（拖拽 + 粘贴 + 选择）、发送、中断、`@` 引用与 `/` 命令（4.11）。 -- **右栏 `Workbench`**：tab 化——内置 `Plan` / `Todos` / `Artifacts` / `Agents`，插件可注册更多 tab；tab 可配置显示/隐藏/排序（4.12）；文档查看器（markdown + docx 预览）；可收起。 +- **中栏 `Conversation`**：虚拟滚动消息流；**Part 渲染器注册表**（按 part 类型查表 → 组件，插件卡片类型经 schema 渲染）；流式增量渲染；run 终态触发过程折叠（可展开）；输入区：文件上传（拖拽 + 粘贴 + 选择）、发送、中断、`@` 引用与 `/` 命令（4.14）。 +- **右栏 `Workbench`**：tab 化——内置 `Plan` / `Todos` / `Artifacts` / `Agents`，插件可注册更多 tab（如知识面板）；tab 可配置显示/隐藏/排序（4.15）；文档查看器（markdown + docx 预览）；可收起。 - **弹窗 `AgentTracker`**：从右栏 `Agents` tab（或消息中的 agent 徽章）打开；任务树（spawn 关系 = Run 父子）、每个 sub-agent 的进度、中间过程（复用 Part 渲染器 + 事件重放）、结果工件链接。 -- **设置中心 `Settings`**：schema 驱动（4.9）——模型与密钥、画像管理、工具与扩展、界面偏好、插件管理，全部由后端设置 schema 渲染，加设置项零前端改动。 +- **设置中心 `Settings`**：schema 驱动（4.9）——模型与密钥、画像管理、工具与扩展、知识库与索引状态、界面偏好、插件管理，全部由后端设置 schema 渲染，加设置项零前端改动。 - **状态 owner**：服务端权威（事件 + Query 对账），前端 store 是投影；查询/命令/取消/过期结果处理按 module-contracts 前端条款明确（切换会话时取消在途请求、旧会话迟到事件按 conversation_id 分流丢弃）。 ### 4.5 HITL 卡片协议（Core 定稿，前后端与插件共用） @@ -240,7 +250,7 @@ Agent-System-Plugin-/ | 工具（Tool） | 声明（HTTP 模板）或代码（Go interface） | 进 toolreg，Agent 可调用；受启用开关与确认策略约束 | | 工作流（Workflow） | 声明（JSON 定义 + 意图绑定） | 进编排目录；命中意图即可启动；步骤可产 HITL 卡片 | | 意图（Intent specs） | 声明（agent-intent overlay） | 进 intentgate 目录；slots 自动成为 HITL 询问项 | -| 知识（Knowledge） | 代码（KnowledgeProvider）+ 索引数据 | 注册检索工具 + 右栏知识面板 | +| 知识（Knowledge） | 代码（KnowledgeProvider）+ 索引数据 | 注册检索工具 + 右栏知识面板；复用系统 RAG 基础设施（4.12） | | UI（面板/卡片） | 声明（UI schema） | 前端通用渲染器渲染；**插件不向主 bundle 注入组件** | **manifest 关键字段**：`id`、`version`、`apiVersion`（插件 API 语义版本，宿主检查兼容窗口）、`provides`（五类能力清单）、`requires`（声明的权限：网络访问域、工具执行、数据读取范围）、`settings`（设置声明）。权限清单在装载时展示并记录——插件能做什么一目了然（信任模型 v1：用户自装自审，权限清单用于可读性）。 @@ -259,7 +269,7 @@ Agent-System-Plugin-/ **模型接入（复用 Agent-Native，不自研）**： - Provider 配置：API 端点与密钥（openai 兼容 / anthropic / 本地模型，按 Agent-Native 所支持）；密钥存服务端（加密落库或本地文件，不进 git、不回显、设置页掩码显示）。 -- **模型路由**：主对话模型、sub-agent 模型、轻量任务模型（会话标题生成、意图澄清重排）可分别配置——不同任务用不同模型是常态定制点。 +- **模型路由按用途分类（kind）**：`chat`（主对话）、`lightweight`（轻量任务：标题生成、澄清改写、记忆候选提取）、`embedding`（向量化，RAG/记忆检索用）、`rerank`（重排，RAG 用）。每类可各自指定模型与参数——不同用途不同模型是常态定制点。Embedding/Reranker 的服务部署经验直接来自老系统实测（compose 编排放 Dev/Releases 环境，按需启用）。 - 运行参数：temperature、max tokens、超时、重试预算；按「系统默认 → 画像 → 会话」三层覆盖（4.9）。 - 预算与配额：per-run token/时长/工具调用次数上限（Guidelines 故障影响控制），超限按稳定错误码终止并在 UI 呈现原因。 @@ -285,6 +295,7 @@ Agent-System-Plugin-/ - **声明式 HTTP 工具**（无代码自定义）：manifest 描述端点、方法、参数 schema、鉴权引用、响应裁剪 → 注册为普通工具。个人自动化接 API（翻译、查询、企业内部服务）零开发。 - **确认策略**：每工具可标 `auto / confirm / deny`（画像三清单覆盖）；`confirm` 触发 HITL confirm 卡片展示调用参数后执行。 - **调用审计**：所有工具调用（含入参摘要、结果状态、时长）持久化，UI 可查（排障 + 合规基础）。 +- **代码执行工具**（远期，D14）：通用代码执行沙箱工具。它是「agent 直接写代码解析疑难文档」（4.11 第三档解析）与更多自动化能力的前提，因安全与沙箱复杂度单独立项。 - **MCP 适配位**（远期）：`ToolProvider` 是唯一工具接入接口，内置/声明式/插件工具皆走它。远期实现 `MCP Provider` 适配器即可接入整个 MCP 外部工具生态，核心零改动——接口按「动态发现工具清单 + schema 校验 + 调用」语义设计，天然覆盖 MCP client 语义。 ### 4.9 设置系统与配置分层 @@ -297,56 +308,107 @@ Agent-System-Plugin-/ - **设置变更事件**：`hot` 类设置变更经事件通道推送（多标签页/未来多客户端一致）。 - 插件与画像声明的设置项并入同一 schema 体系（来源标记），统一出现在设置中心对应分区。 -### 4.10 上下文组装策略（ContextPolicy） +### 4.10 上下文组装与上下文管理 -发送给模型的内容由策略组装，而非散落代码——这决定智能体「看到什么」，是行为定制的深层轴： +发送给模型的内容由**预算化分层管线**组装，而非散落代码——这决定智能体「看到什么」，是行为定制的深层轴，也是长会话质量的根基： -```json -{ "history": { "mode": "window", "maxMessages": 40, "summarizeBeyond": true }, - "attachments": "inline-or-ref", - "artifacts": "ref-with-outline", - "knowledge": { "inject": "on-demand" }, - "systemPromptExtra": [] } +``` +ModelInput = SystemPrompt(画像) + + 注入槽[memory] ← 记忆：相关性+新近度检索，预算内（4.13，默认关闭） + + 注入槽[knowledge] ← 知识：按需检索注入（4.12） + + History ← 窗口内原文；窗口外滚动摘要（远期压缩） + + CurrentTurn ← 用户消息 + 附件解析结果 + @引用 + + ToolResults ← 按截断策略 ``` -- 组装过程可观测：每次 run 记录实际组装的上下文构成（条目 + 估算 token），UI 可查——「模型为什么不知道 X」可定位。 -- 历史超窗摘要、知识按需注入等策略逐版本增强；远期记忆系统（跨会话）以新策略项接入，不改组装器接口。 +- **预算管理器**：总预算 = 模型窗口 − 保留余量（输出预留）；各槽位带优先级与份额上限（画像可调，如 memory ≤5%、knowledge ≤20%）；超预算按优先级裁剪。**每次裁剪记录进组装观测**（4.17）——「模型为什么不知道 X」可定位、可解释。 +- **历史策略**：`window`（最近 N 条原文）为基础；窗口外原文永不删除（存储完整），仅不进上下文；滚动摘要压缩（轻量模型生成 `summary` 段注入）为远期增强。 +- **工具结果截断**：每结果上限 + 头尾保留策略；溢出自动转工件引用（「结果过长已存为工件 @artifacts:x」，模型与用户都可再取）。 +- **附件与引用**：上传文档经 ingest 解析（4.11）后注入；`@artifacts/@knowledge` 引用显式挂载（4.14）。 +- **策略数据化**：ContextPolicy 为数据（画像引用、可被会话覆盖），逐版本增加策略项不动组装器接口。 -### 4.11 输入增强与命令 +### 4.11 文档摄取与解析管线（r3 新增） -- **`@` 引用**：`@artifacts:文档名`、`@files:`、`@knowledge:`——把对象显式挂进本轮上下文（映射到 ContextPolicy 的 attachments/artifacts/knowledge 条目）。 +``` +上传/工件 → ingest → ParsedDocument(中间表示) → 消费方：附件上下文(ctxasm) / 工件预览 / 检索索引(4.12) / 全文检索 +``` + +**ParsedDocument 中间表示**（Core 契约）：`blocks[]`（heading / para / list / table / code / image-ref）+ 文档元数据 + **解析溯源**（解析器 id、置信度、交叉验证结果）。所有下游只消费 IR，不关心解析器——这是解析器可替换、可组合、可交叉验证的关键。 + +**解析器三档**（ParserProvider 注册表，与工具注册表同纪律、带来源标记）： + +1. **内置代码解析器（主路线）**：确定性库解析——md/txt 直读；docx/pptx 解 OOXML；pdf 提取文本层。成本低、无外部依赖、可独立测试；这与「现代智能体直接写代码解析」思路一致：解析是**普通代码能力**，不是神秘服务。 +2. **MinerU 服务适配器（可选，备选与交叉验证）**：独立服务部署（L2 sidecar，compose 编排，**默认不部署**，设置启用）。定位依据用户老系统实测结论——能解析但能力有限：用于扫描件/图片型 PDF/复杂版式的**深度解析备选**；**交叉验证模式**：与内置解析结果逐块 diff，差异块标记低置信度并在工件视图提示，不静默取信单一来源。 +3. **Agent 驱动解析（远期，依赖代码执行工具 D14）**：对疑难文档由智能体现场写代码解析（现代智能体主流做法），产物回写 ParsedDocument 并可沉淀为新的解析器声明（资产化：一次解析、复用为模板）。 + +**解析策略**（数据可配，per project）：默认档位与回退链（如 `pdf: builtin → mineru`）、交叉验证开关、大文档分块解析预算、失败呈递（解析失败不是错误吞掉，而是生成「无法解析」占位与原因，Agent 与用户可见）。 + +**分期**：P2 落内置解析器（支撑附件上传对话闭环）；P4 契约定稿 + 解析策略配置；MinerU 适配器与交叉验证远期（法规插件立项时牵引，D12）。 + +### 4.12 RAG 检索管线（r3 新增） + +**定位**：RAG 引擎是**系统基础设施**（同 toolreg），知识库是**数据**（项目内建或插件提供）——法规插件远期只需带数据与配置，不自带引擎（「数据即能力」原则在检索侧的延续）。 + +**管线**： + +``` +Query → 改写(可选，lightweight 模型) → Embedding(kind=embedding 模型路由) + → 混合检索(pgvector 向量 + PG 全文) → Rerank(可选，kind=rerank 模型路由) + → TopK 组装 → 注入(工具结果 或 ctxasm knowledge 槽位) +``` + +**组件契约**（Core）：`Chunker`（切分策略：大小/重叠/结构感知，按 ParsedDocument blocks 切，表格不拦腰断）、`EmbeddingProvider`（模型路由）、`VectorIndex`（默认 pgvector——复用 PG、运维简单、个人部署规模内够用；接口可换独立向量库，D13）、`Retriever`（组合器与策略）。**Embedding/Reranker 复用老系统已验证的服务部署经验**，作为模型 provider 配置接入（4.7），不绑定特定实现。 + +**索引对象与知识库管理**：项目内文档（上传/工件，ingest 产物直接进索引）、插件知识库（法规等，来源标记）；设置中心展示每库索引状态（进度/失败重试/重建）。 + +**分期**：P4 契约定稿 + **全文检索最小实现**（PG tsvector，支撑 `@knowledge` 基础引用与命中）；向量管线（embedding + pgvector + rerank）远期，由法规插件立项牵引——骨架不背重负载，但插件落地时零核心改动。 + +### 4.13 记忆系统（r3 新增） + +**定位**：跨会话个性化机制；**默认关闭**（一切可禁用原则）；契约先立、实现远期。 + +- **记忆模型**：`{ id, scope: user|project, type: fact|preference|decision|episode|procedure, content, source: run|manual, confidence, created, lastAccessed, expiresAt? }`。 +- **写入路径**：① 显式——用户「记住这个」命令 / 设置页手填；② 策略写入——run 结束后由 lightweight 模型提议候选记忆，经 **HITL 卡片确认**入库（复用 HITL 机制）；敏感内容必须确认。**禁止无确认静默写入长期记忆**（信任原则）。 +- **读取路径**：ctxasm 的 memory 注入槽（预算内按相关性+新近度检索；记忆量小时全量注入）。 +- **可管理性**：记忆列表 UI（查看/编辑/删除/导出）、per-project 隔离、保留策略（TTL/容量上限/新近度淘汰）。记忆是用户数据，系统只做工具——可完全关闭、可清空、可迁移。 +- **分期**：P4 定契约与存储 schema 预留（不加逻辑）；实现（写入提取、检索注入、管理 UI）远期。 + +### 4.14 输入增强与命令 + +- **`@` 引用**：`@artifacts:文档名`、`@files:`、`@knowledge:`——把对象显式挂进本轮上下文（映射到 ctxasm 的注入槽）。 - **`/` 命令**：注册式命令（内置：/new /model /profile /export；插件与用户可加）。命令识别走 intentgate 的系统功能命令路径（复用生态能力，不另造解析器）。命令带参数 schema → 输入框内联表单补全。 - **用户命令宏**：`/模板名` 展开为预存提示词模板（数据文件）——高频操作的零代码定制。 - **模板片段库**：提示词片段管理（增删改查 + 导入导出），输入框快速插入。 -### 4.12 界面定制与主题 +### 4.15 界面定制与主题 - **布局偏好**：三栏宽度、收起态、右栏 tab 显隐与排序、中栏密度（舒适/紧凑）、字号。 - **主题**：CSS 设计令牌（色彩/圆角/间距/字体），内置亮/暗双主题；令牌层可被用户覆盖（自定义主题 = 数据）。所有组件只消费令牌，不写死颜色——插件 UI 同样经渲染器消费令牌，自动随主题。 - **行为偏好**：过程折叠默认态（自动折叠/保留展开）、流式动画开关、发送快捷键（Enter/Ctrl+Enter）。 - 全部偏好进设置系统（4.9），本地即时生效并同步服务端。 -### 4.13 数据可携带性与开放 API +### 4.16 数据可携带性与开放 API - **导出/导入**：项目/会话导出为 JSON（含消息树、run 与事件、工件引用清单）或 Markdown（可读归档）；导入恢复或迁移。工件本体支持批量导出。 -- **画像/设置/模板打包迁移**：个人配置整体搬家。 +- **画像/设置/模板/记忆打包迁移**：个人配置整体搬家（记忆实现后并入）。 - **开放 API**：OpenAPI 规范随 Core 发布；脚本与第三方客户端可用同一 API 完成全部操作（API-first 原则的落地物）。 -### 4.14 观测、调试与用量 +### 4.17 观测、调试与用量 - **事件重放**：事件已持久化（seq 有序）→ 任意 run/会话可离线重放进调试视图（前端复用渲染器），开发期排障与回归演示的基础。 - **用量统计**：per-run（token/时长/工具调用）→ 汇总 per-conversation/project/模型/天；设置页与项目页展示。 +- **上下文组装观测**：每次 run 记录各注入槽实际用量与裁剪记录（4.10）。 - **进度归属**：事件携带 run 归属链（Guidelines observability），任何卡顿可定位到具体 run/工具/子代理。 - 日志走 Logging-System 对齐（脱敏、追踪标识），错误走 Error-Code-System 稳定码（`intent` 域沿用，系统域新增种子域按追加式流程）。 -### 4.15 与生态库的接入点（沿用既有方案，不重造） +### 4.18 与生态库的接入点（沿用既有方案，不重造） - Agent-Native：主对话与工具执行的实际后端（runtime 模块窄接口适配）。 - Agent-Squad：sub-agent 编排（spawn/黑板/HITL 由 runmgr 映射为统一 Run + 事件）。 - Agent-Intent：入口闸门（守卫 + 命令识别）+ 编排目录（intent catalog 注入规划）；未配置意图 = 行为回退（T0）。 - Error-Code-System / Logging-System：常量对齐 + 鸭子接口。 -### 4.16 扩展点与定制点总览 +### 4.19 扩展点与定制点总览 **扩展轴**（系统如何长大）： @@ -355,26 +417,28 @@ Agent-System-Plugin-/ | 工具 | ToolProvider + 声明式 HTTP + MCP 适配位 | 声明/代码 | P2 内置最小集；P4 插件注册；MCP 远期 | | 工作流 | 声明定义 + 意图绑定 | 声明 | P4 机制（示例插件演示） | | 意图 | intent overlay，slots→HITL | 声明 | P3 接入，P4 插件注册 | -| 知识检索 | KnowledgeProvider 契约 | 代码+数据 | P4 契约；实现远期 | +| 知识/RAG | KnowledgeProvider + Retrieval 管线 + pgvector | 基础设施+数据 | P4 契约+全文最小；向量远期 | +| 解析器 | ParserProvider + ParsedDocument IR | 代码/服务 | P2 内置档；P4 契约；MinerU/agent 档远期 | +| 记忆 | MemoryStore + HITL 确认写入 | 数据+策略 | P4 契约预留；实现远期 | +| 上下文管理 | ContextPolicy + 预算管理器 | 数据 | P2 基础；压缩/精细预算远期 | | UI 面板/卡片 | UI schema + 通用渲染器 | 声明 | P1 渲染器基座，P4 插件注册 | -| 模型/Provider | Agent-Native + 路由配置 | 配置 | P2 | +| 模型/Provider | Agent-Native + 按 kind 路由（chat/lightweight/embedding/rerank） | 配置 | P2 | | 智能体画像 | AgentProfile 数据 + 画像模板 | 数据 | P2 默认，P4 自定义 UI | | 命令/宏 | 命令注册 + intentgate | 声明 | P3 | -| 上下文策略 | ContextPolicy | 数据 | P2 基础，逐版本增强 | | 客户端 | 开放 API + OpenAPI/TS client | 代码 | P1 API 基线；CLI 远期 | -| 存储 | 对象目录接口（S3 适配位） | 代码 | P1 本地，S3 远期 | +| 存储 | 对象目录接口（S3 适配位）+ VectorIndex 接口 | 代码 | P1 本地；S3/独立向量库远期 | -**定制轴**（用户不改代码可调）：模型与参数（分层覆盖）、智能体画像、工具开关与确认策略、上下文构成、命令宏与提示词模板、HITL 策略与预算、界面布局/主题/行为偏好、面板显隐排序、数据导出迁移。 +**定制轴**（用户不改代码可调）：模型与参数（分层覆盖）、智能体画像、工具开关与确认策略、上下文构成与预算、命令宏与提示词模板、HITL 策略与预算、知识库与解析策略、界面布局/主题/行为偏好、面板显隐排序、记忆开关与管理、数据导出迁移。 --- ## 5. 兼容、迁移与恢复 -- 老系统：冻结不动，仅作领域知识参考；远期领域插件按新系统契约**全新设计**，不迁移、不兼容、不搬代码。 +- 老系统：冻结不动，仅作领域知识与机制参考；远期领域插件按新系统契约**全新设计**，不迁移、不兼容、不搬代码。MinerU/Embedding/Reranker 复用的是**部署经验与服务形态**，不是老系统代码。 - 生态仓：本系统全部通过 submodule + gitlink 固定；接入时如需扩接口，走「提供方先扩展兼容契约 → 消费方适配 → 组合验证 → Dev 更新 gitlink」顺序（多仓规范）。 -- 事件协议兼容：字段只增不改语义；前端按未知 `type` 静默忽略 + 版本协商（信封 `v` 字段），保证骨架升级不破坏在途会话（终态对账兜底）。UI schema 词汇、插件 API 同规则。 +- 契约兼容：事件协议、插件 API、UI schema、ParsedDocument、Retrieval、Memory 契约统一版本化；字段只增不改语义；消费方对未知 `type`/词汇静默忽略 + 版本协商（信封 `v` 字段）；扩展走兼容窗口流程。 - 回退：Dev 仓恢复旧 gitlink 组合即可整体回退；数据库 schema 迁移显式设计（每阶段附回滚脚本；不假设可反向推导）。 -- 未安装任何插件、未启用任何扩展时，系统即纯通用智能体对话骨架（T0 行为基线，作为验收对照）。 +- 未安装任何插件、未启用任何扩展（含记忆、MinerU、向量检索）时，系统即纯通用智能体对话骨架（T0 行为基线，作为验收对照）。 --- @@ -385,10 +449,12 @@ Agent-System-Plugin-/ | 三栏布局：调宽/超调收起/展开/偏好持久化 | Frontend ProjectNav | 组件测试 + Playwright | 拖拽行为与持久化符合 4.4 | | 流式对话：区分正文/思考/工具，终态后过程折叠可回看、折叠默认可设置 | streamhub + Part 渲染器 | 集成测试（mock runner 事件序列）+ 浏览器验收 | 过程 parts 折叠为摘要，展开可见 | | 断线重连终态对账 | streamhub Stream 契约 | 故障注入（中断 SSE） | 恢复后消息树与权威 Query 一致 | -| 文件上传与工件查看 | artifacts + 右栏查看器 | 集成 + 浏览器验收 | 上传→引用→右栏渲染 | +| 文件上传→解析→注入→对话闭环；解析失败显式可见 | ingest + ctxasm | 集成测试（md/docx/pdf 样张 + 损坏文件） | ParsedDocument 注入正确；失败不静默 | +| 工件查看 | artifacts + 右栏查看器 | 集成 + 浏览器验收 | 产出→右栏渲染 | | HITL 卡片：选项/影响/建议/自由输入路由 | hitl + intentgate | 契约测试（选中 vs 自由输入 vs 命令三路径） | run 正确恢复或正确转轨 | | sub-agent 弹窗：任务树/中间过程/结果 | runmgr + AgentTracker | 多 agent 场景集成测试 | spawn 关系与进度完整展示 | | 模型路由与画像：换模型/参数/工具集生效 | profiles + settings + runtime | 集成测试（三层覆盖链各取一例） | 生效时机与 4.9 声明一致 | +| 上下文预算与裁剪可观测 | ctxasm 组装观测 | 构造超限场景单测 | 裁剪记录完整、行为符合策略 | | 声明式 HTTP 工具：注册即用 | toolreg | 契约测试（mock 端点） | 无代码新增可用工具 | | 设置 schema 驱动：新增设置项零前端改动 | settings + Settings UI | 加一个测试设置项走 schema | 设置页自动出现且生效语义正确 | | 示例插件装卸不破坏核心 | pluginhost + registry + CI 依赖检查 | 装/卸示例插件 → 核心全量回归 | 核心功能零回归；在途引用稳定报错 | @@ -402,7 +468,7 @@ Agent-System-Plugin-/ 每阶段一张主任务记录（Documents 仓）+ change-plan + 验证记录；Dev 仓组合推进。规模为单人开发粗估，按实际节奏调整。 -### 7.1 本计划（骨架 + 插件机制） +### 7.1 本计划（骨架 + 插件机制 + 重能力契约） **P0 仓网引导（半天–1 天）** - 六个空仓初始化：README、AGENTS.md/PROJECT.md（按模板）、`policy/`、`.gitignore`、gitea 描述（按 3.2 表）、默认分支 main。 @@ -418,42 +484,46 @@ Agent-System-Plugin-/ **P2 真实智能体接入与定制基座（4–6 天）** - runtime 接 Agent-Native：真实 LLM 对话、thinking/正文/工具调用事件映射；run 取消与中断恢复策略。 -- 模型接入：provider 配置、模型路由、密钥管理、运行参数三层覆盖。 -- profiles（默认画像 + 基础 CRUD）、toolreg（内置最小集 + 确认策略 + 审计）、ctxasm 基础策略、artifacts（上传/工件/右栏查看器）。 -- 出口：真实模型对话端到端；工具调用折叠正确；换模型/换参数即时生效；文件上传→工件→右栏查看闭环。 +- 模型接入：provider 配置、按 kind 路由（chat/lightweight/embedding/rerank 配置位）、密钥管理、运行参数三层覆盖。 +- profiles（默认画像 + 基础 CRUD）、toolreg（内置最小集 + 确认策略 + 审计）、ctxasm 基础（窗口/工具结果截断/注入槽骨架 + 组装观测）、**ingest 内置解析器**（md/txt/docx/pdf 文本层，ParsedDocument IR）+ artifacts（上传/工件/右栏查看器）。 +- 出口：真实模型对话端到端；上传文档→解析→注入对话闭环；工具调用折叠正确；换模型/换参数即时生效。 **P3 编排、sub-agent、HITL 与命令（4–6 天）** - runtime 接 Agent-Squad：sub-agent spawn/进度/结果 → 统一 Run 与事件；右栏 Plan/Todos/Agents tab；AgentTracker 弹窗（含事件重放）。 -- intentgate 接 Agent-Intent：入口闸门 + 目录注入 + `/`命令识别；`@` 引用。 +- intentgate 接 Agent-Intent：入口闸门 + 目录注入 + `/`命令识别；`@` 引用（含 @knowledge 全文最小实现）。 - hitl 完整落地（含自由输入三路径路由：选中/澄清回填/转轨）。 - 出口：多 agent 任务全链路可视化；HITL 三路径验收过；`/`命令与 `@` 引用可用。 -**P4 插件框架与机制验证（4–5 天，不含领域插件）** +**P4 插件框架、重能力契约定稿与机制验证（4–5 天，不含领域插件与向量实现）** - pluginhost：manifest、五类能力注册、声明资产热加载、fail-closed、卸载语义、权限清单。 - registry 统一注册表 + 来源标记 + 按来源启停；CI 依赖检查。 - 前端插件 tab/卡片经 schema 渲染器注册；插件设置并入设置中心。 +- **契约定稿**：ingest 解析策略与 MinerU 适配位、Retrieval（Chunker/EmbeddingProvider/VectorIndex/Retriever）+ 全文检索最小实现、Memory 契约与 schema 预留。 - **示例插件**（`example`，随 Documents 的插件开发指南一同发布）：一个声明式 HTTP 工具（指向 mock 端点）+ 一个 demo 面板 + 一个 demo 卡片 + 一个意图 spec + 一段设置声明——最小体量覆盖五类能力。 - 画像自定义 UI + 导入导出；命令宏与提示词模板库；声明式 HTTP 工具用户流程。 -- 出口：装卸示例插件核心零回归（第 6 节插件三行验收过）；插件开发指南可照做。 +- 出口：装卸示例插件核心零回归；插件开发指南可照做；重能力契约评审通过（后续远期实现按契约零核心改动接入）。 **P5 发布链路（1–2 天）** -- Releases 仓：版本 manifest 生成（从 Dev 固定提交导出）、制品构建（后端二进制 + 前端 dist + 示例插件包）、compose 部署编排、回退演练。 +- Releases 仓：版本 manifest 生成（从 Dev 固定提交导出）、制品构建（后端二进制 + 前端 dist + 示例插件包）、compose 部署编排（含可选 MinerU/Embedding/Reranker 服务 profile）、回退演练。 - 出口：全新环境按 Releases 一键部署成功；manifest↔gitlink 对应校验过。 -里程碑：P1 = 可演示骨架；P3 = 可日常使用的通用智能体系统；P4 = 扩展机制验证完成（「插件不破坏核心」主张成立）；P5 = 可分发产品。 +里程碑：P1 = 可演示骨架；P2 = 可真实对话的定制基座；P3 = 可日常使用的通用智能体系统；P4 = 扩展与重能力契约验证完成；P5 = 可分发产品。 ### 7.2 远期路线（骨架完成后另行立项，本计划不含） | 项 | 说明 | |---|---| | **CDMO 工作流插件** | 医疗器械 CDMO 工作流、意图、文档模板与面板，**基于新系统插件契约全新设计**：工作流即数据、意图 slots 驱动 HITL、文档产出走 artifacts、面板走 UI schema。老系统仅作领域业务知识参考（流程、术语、文档体系），不迁移代码、不兼容接口、不复用数据格式。立项时先写该插件的设计方案。 | -| **法规知识库插件** | KnowledgeProvider 契约实现 + 索引管线 + 知识面板与检索工具；素材基于 `08-Regulations`。 | +| **法规知识库插件** | KnowledgeProvider 契约实现 + 向量 RAG 管线落地（本插件为牵引方）+ 知识面板与检索工具；素材基于 `08-Regulations`。 | +| 向量 RAG 管线 | embedding + pgvector + rerank 全链路；MinerU 深度解析适配器与交叉验证（D12 保留时）。 | +| 代码执行工具 | 通用沙箱执行；解锁 agent 驱动解析（4.11 第三档）与更多自动化；单独立项（安全设计）。 | +| 跨会话记忆实现 | 4.13 契约的实现：提取、确认、注入、管理 UI。 | +| 上下文压缩增强 | 历史滚动摘要、精细预算管理器。 | | MCP 外部工具接入 | ToolProvider 的 MCP 适配器，接入外部工具生态，核心零改动。 | -| 跨会话记忆 | ContextPolicy 新策略项 + 记忆存取服务；先立设计小案。 | | 并行子任务、run 透明恢复 | 协议已预留（4.2），需要时开启。 | | CLI / headless 客户端 | 复用开放 API。 | | 多用户 | owner 字段已预留，认证与授权整体设计。 | -| 对象存储 S3 后端、知识向量化 | 按需。 | +| 对象存储 S3 后端、独立向量库 | 按需（VectorIndex 接口已预留）。 | --- @@ -472,5 +542,9 @@ Agent-System-Plugin-/ | D9 | 示例插件范围 | 随 P4 做一个最小 `example` 插件覆盖五类注册能力（验证机制的最小成本方式），领域插件一律远期 | ☐ | | D10 | 声明式 HTTP 工具进骨架期 | 进（P4，体量小、是「无代码扩展」主张的最有力证明） | ☐ | | D11 | MCP 适配时机 | 远期（v1 只做接口语义预留，4.8） | ☐ | +| D12 | MinerU 定位 | **备选 + 交叉验证**：主路线为内置代码解析器；MinerU 作为独立可选服务（默认不部署），用于扫描件/复杂版式与交叉验证；保留适配位（4.11）。若你倾向彻底弃用，则删除适配位仅留 ParserProvider 接口 | ☐ | +| D13 | 向量存储选型 | pgvector（复用 PG、个人部署规模内够用、VectorIndex 接口可换独立向量库） | ☐ | +| D14 | 代码执行工具（agent 驱动解析的前提） | 远期单独立项（沙箱安全设计复杂度高），v1 不做 | ☐ | +| D15 | 记忆默认状态 | 默认关闭，用户显式开启；写入必须 HITL 确认（4.13） | ☐ | -批准本方案（含 D1–D11 或批注修改）后，从 P0 开始执行。 +批准本方案（含 D1–D15 或批注修改）后，从 P0 开始执行。