Agent-System-Documents/docs/proposals/2026-09-29-system-skeleton-design-and-plan.md

Agent-System 对话系统骨架：设计、方案与实施计划

状态：待审（r4，按 2026-09-29 用户三轮指示修订）；owner：weichen；主任务：本文档自身（批准后拆分为各阶段主任务记录）。 授权与交付终点：本文档为设计 + 方案 + 计划，不含实现。批准后按第 7 节阶段逐项开工。 规范基线：Development-Guidelines（development/guidelines submodule，Dev 仓固定版本）。 撰写日期：2026-09-29。 r2 修订：领域插件（CDMO、法规知识库）移出本计划进远期路线，届时按新系统特性全新设计（不兼容、不迁移老系统）；扩充扩展性与定制性章节。 r3 修订：新增文档摄取与解析管线（4.11，MinerU 定位为备选/交叉验证）、RAG 检索管线（4.12）、记忆系统（4.13）设计；上下文管理扩充为预算化分层管线（4.10）；模型路由增加 embedding/rerank 类别（4.7）。 r4 修订：新增全局部署约束（4.1 原则 8）：非容器化优先，单二进制最优先，必要时拆分多个原生二进制；存储改双档（嵌入式 SQLite 默认 / PostgreSQL 可选，D16）；前端嵌入二进制；Dev 开发环境与 Releases 分发物改为原生方案。

---

1. 问题与证据

1.1 用户目标

构建一个对话系统的骨架，界面形态仿 zcode / Kimi / Codex：

• 左栏：项目 → 会话两级组织；底部账户、设置入口；可拖拽调宽（有最小/最大宽度），压过最小宽度继续拖拽以手势触发收起；收起后保留窄栏。
• 中栏：对话区。支持文档、图片等文件上传；文字消息发送；流式回复；须区分回复正文、工具调用、思考过程等不同消息成分；最终回复整理输出后，之前的过程输出折叠或隐藏（可回看）。支持卡片交互：HITL 提问卡片（给出选项 + 建议 + 各选项可能造成的影响 + 自由输入；系统判断用户是选择了某项还是提出了别的问题）。
• 右栏：工具栏。计划、步骤、to-dos；Agent 在对话中产出的文档可在右栏查看；子标签（tab）设计按需规划。
• 弹出窗口：结合右栏，展示、追踪 sub-agent 的任务、结果、中间过程。

系统必须提供插件机制：骨架保证一个通用智能体的使用与功能；领域能力（例：医疗器械 CDMO 工作流、法规知识库检索）之后通过插件接入。

2026-09-29 修订指示（r2）：当前先不实现医疗器械 CDMO 等领域插件与功能，仅纳入之后的实现计划；届时实现不需要兼容老系统，要根据新系统的特性为新系统全新设计。先保证通用智能体系统的骨架，尽可能设计完善，多考虑可扩展性、可定制性等方向。

2026-09-29 修订指示（r3）：老系统使用了 MinerU、Embedding、Reranker，新系统可以考虑使用。但 MinerU 要尤其注意——用户在老系统实际测试过，确实能解析文档但能力有限；现在很多智能体直接编写代码解析 docx/pdf/ppt，可借鉴该思路，MinerU 作为备选或交叉验证，或考虑弃用。系统还需考虑之后的 RAG、记忆系统、上下文管理等机制功能，考虑全面。以上为思路，按系统设计与需求实际情况落实。

2026-09-29 修订指示（r4）：为系统和所有模块加入部署约束——尽可能不使用 Docker 容器化部署；最优先考虑单二进制文件的服务；必要时才拆分成多个二进制服务，但仍最优先非容器化方案。

核心诉求：充分的可扩展性、可定制性；新功能以插件接入，不破坏已有功能、不需要大规模重新开发、不与核心过度耦合。

1.2 现状与已证实事实

事实	证据
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 关系
未知仓	SMDF-Agent-System（空仓，用途不明，待澄清）；本地 Agent-System-Ensemble/（空目录，建议用作 Dev 仓工作副本）
Agent-Intent 远端此前缺描述	2026-09-29 已补全（Gitea API，HTTP 200）

1.3 重要经验命中

• Agent-Intent 记忆：意图注册表 = 能力目录（slots 声明 HITL 该问什么）；三触点 = 入口闸门 / 编排目录 / 执行防线；生态 pin 纪律（guidelines / errcode / logsys / agent-intent 的 gitlink 必须跨仓一致）；agent-intent 严禁依赖 agent-native/squad。
• Guidelines：父仓 gitlink 是子仓版本权威；模块从 L1 逻辑隔离起步；四类通信语义（Query/Command/Event/Stream）；Stream 契约必须定义游标、断连、终态对账；配置项须明确来源、生效时机、实例隔离；文档三层放置。

---

2. 目标与边界

2.1 目标

1. 完善的通用智能体骨架：三栏 UI + 流式对话（正文/思考/工具区分与折叠）+ HITL 卡片 + sub-agent 追踪 + 文档工件 + 可定制的模型/智能体/工具/上下文/界面，端到端走通，且每个可定制点不改代码即可调整。
2. 插件机制完备并经示例验证：五类注册能力（工具/工作流/意图/知识/UI）+ 声明资产热加载 + 装卸回退语义；用一个最小示例插件验证机制（装卸不破坏核心）。领域插件（CDMO、法规）不在本计划实现。
3. 重能力子系统契约完备：文档摄取解析、RAG 检索、记忆系统、上下文管理的契约与数据位在本设计中定稿（4.10–4.13），骨架期落最小实现，增强能力按远期路线增量落地——扩展不等待，落地不破坏。
4. 仓网组织：所有 submodule 独立、通用、可复用、易维护、可扩展；Agent-System-Dev 为开发集成父仓，Agent-System-Releases 只做打包分发。
5. 规范落地：开发全程按 Development-Guidelines 执行（阶段方案、验证记录、pin 纪律、模块卡）。

2.2 非目标

• 非容器化部署（全局约束，适用于系统与所有模块）：不依赖 Docker/容器编排；不发布容器镜像（远期确有需要再单独议）；默认形态为单二进制，必要时拆分多个原生二进制（拆分原则见 4.1 原则 8）。外部可选服务（MinerU、Embedding/Reranker 等）以原生服务形态接入（URL 配置），其自身部署方式由使用者自定，系统不假定容器。
• 本计划不实现领域插件：CDMO 工作流、法规知识库进入远期路线（7.2 节）；届时按新系统插件契约全新设计——不迁移老系统代码、不兼容老系统接口、不复用其数据格式；老系统仅作领域业务知识参考。
• 重能力子系统只落契约与最小实现：向量 RAG 管线、跨会话记忆、代码执行工具、历史滚动压缩进远期路线（7.2）；本计划交付其契约与数据位预留，保证届时接入不改核心。
• 骨架期不做多租户、计费、公开注册；单用户（个人部署）起步，但数据模型预留 owner 字段。
• 不追求移动端；桌面浏览器优先（布局用响应式组件，不为移动端专门优化）。
• 不自研 LLM 接入层——复用 Agent-Native。
• v1 不做插件市场 / 在线安装；插件以仓为单位、构建期组装（热加载仅限声明性资产，见 4.6）。

---

3. 仓库组织设计

3.1 命名规则（用户定义，本设计确认沿用）

• Agent-*：智能体能力库（与具体宿主系统无关）——Agent-Native、Agent-Squad、Agent-Intent。
• Agent-System-*：本系统相关。
• 插件仓：Agent-System-Plugin-<Name>（远期按需新建，本计划不建）。

3.2 仓库分配总表

仓库	角色	职责一句话	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；默认构建为单二进制（go:embed 内嵌前端与嵌入式存储）	对话系统后端：会话与流式管道、智能体运行时与画像、工具/上下文/文档解析/检索/设置管理、插件宿主（组合 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 集成全部模块；顶层构建/测试编排、原生开发环境脚本（make dev 直接本地起服务，不依赖容器）、跨仓任务记录入口；非分发单元	开发集成仓：以 submodule 固定全部模块组合，承载跨仓构建、测试编排与原生（非容器）开发环境；发布物在 Agent-System-Releases。
Agent-System-Releases	发布仓（可选分发）	版本 manifest（pin 全组合 SHA）+ 不可变制品（单二进制 + 校验和）+ 原生部署物料（systemd 单元、安装/升级/回退脚本）；只打包分发，不开发源码	发布仓：每个版本固定组件组合，分发单二进制制品与原生部署物料（systemd、安装回退脚本）；只做打包与分发，不做源码开发，不提供容器镜像。
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-Plugin-CDMO（远期新建）	领域插件仓	医疗器械 CDMO 工作流插件：基于新系统插件契约全新设计	（远期建仓时写）CDMO 工作流插件：按新系统插件契约全新设计，注册工作流、意图、文档模板与面板。
Agent-System-Plugin-Regulations（远期新建）	领域插件仓	法规知识库插件	（远期建仓时写）法规知识库插件：注册法规检索工具与知识面板。
SMDF-Agent-System	待澄清	空仓，用途不明	暂不使用，待用户澄清

3.3 依赖方向（无环）

Frontend ──→ Core ←── Backend ──→ {Agent-Native, Agent-Squad, Agent-Intent,
                                   Error-Code-System, Logging-System}
Plugin-* ──→ Core（只依赖契约，不依赖 Backend/Frontend 实现）
Dev ──(gitlink)──→ 以上全部
Releases ──(版本 manifest 引用)──→ Dev 固定组合的制品

• Backend 不 import Frontend；插件不 import Backend/Frontend 内部包（违者 CI 依赖检查拒绝）。
• 生态仓依赖方向沿用既有纪律（agent-intent 不依赖 native/squad 等）。
• Core 依赖：Go 标准库 + 错误码常量对齐用鸭子接口（同 agent-intent 模式）；Core 不依赖任何生态仓。

3.4 版本与组合纪律

• 父仓 gitlink 为版本权威（Guidelines 多仓规范）；Dev 仓每次推进组合时跑 CI 全量验证后提交 gitlink 更新。
• 各模块仓独立演进，未被 Dev 采用的新版本是合法状态。
• Releases 的版本 manifest 从 Dev 固定提交导出（不提交自引用循环锁文件）。

---

4. 系统架构

4.1 设计总则：八条扩展性原则

本系统的可扩展性不是事后补丁，而是由以下机制原则保证（每条都对应下文具体设计）：

1. API-first：后端全部能力走公开 HTTP + SSE API，前端只是第一个客户端。任何功能（面板、卡片、命令）先有 API 再有 UI；Core 同步发布 OpenAPI 规范与生成的 TS client。CLI、其他客户端、远程访问后接不改后端。
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、记忆、上下文管理）都先定契约与数据位，骨架期落最小可用实现（能支撑端到端价值流），增强能力按远期路线落地——扩展需求不等待设计，落地不破坏契约。
8. 原生部署、单二进制优先（全局部署约束）：默认产物是一个静态链接的二进制（agent-system：HTTP/SSE 服务 + go:embed 内嵌前端 + 嵌入式存储 + 全部内置模块），拷贝即运行，无容器、无外部依赖（模型 API 除外）。拆分多个二进制仅在必要时（判据：故障域隔离、资源预算冲突、异构技术栈，如 module-contracts L2/L3 场景——远期 sidecar 插件、重索引 worker 等），拆出的仍是原生二进制，同机以 Unix socket / localhost 通信。不使用 Docker/容器编排，不发布容器镜像；外部可选服务（MinerU、Embedding/Reranker）以原生服务形态部署、URL 配置接入（如 ollama 式本地推理服务），系统对其部署方式不做容器假定。

总体形态：

• 部署形态：默认单二进制 agent-system（子命令 serve / migrate / version 等），内嵌前端（go:embed dist）与嵌入式存储，一个进程一个端口对外提供全部 API 与 UI；CLI 子命令兼作运维入口（与 API-first 不冲突：CLI 走同一 API 或直接调用同库用例）。开发期前端走 Vite dev server + 代理，构建期才 embed。
• 后端：Go 模块化单体（module-contracts L1 逻辑隔离起步），进程内模块以公开契约互调；重负载模块（MinerU 深度解析、向量索引 worker 等）预留 L2 独立二进制拆分位（仍是原生进程）。
• 前端：React 19 + Vite + TypeScript SPA（沿用老系统技术栈经验：虚拟滚动、docx 预览、mermaid、katex）；Node 仅为构建期工具链，运行期不需要。
• 传输：REST（Query/Command）+ SSE（Stream）。SSE 事件 = Core 定义的统一事件信封。
• 持久化（双档，D16）：默认嵌入式档——SQLite（单文件数据库，配合本地对象目录存文件与工件，零外部服务）；可选 PostgreSQL 档——原生安装的 PG（非容器），DSN 配置接入，面向更大规模或多实例。迁移脚本双方言同源、两档都在 CI 验证；全文检索（SQLite FTS5 / PG tsvector）与向量索引（见 4.12）均在存储档接口后实现，业务模块不感知方言。

4.2 核心抽象：一切运行皆 Run、一切增量皆事件

系统最重要的统一抽象，中栏折叠、sub-agent 弹窗、工具调用展示、用量统计全部复用它：

// 概念示意（详细 schema 在 Core 定稿）
Run {
  ID, ParentRunID   // 顶层对话轮 = ParentRunID 空；sub-agent / 工具调用 = 子 Run
  ConversationID, ProjectID
  Kind              // conversation | subagent | tool
  ProfileID         // 使用的智能体画像（4.7）
  Status            // pending | running | waiting_hitl | completed | failed | cancelled | interrupted
  Phase             // thinking | acting | responding | done（run.phase 事件驱动 UI 主状态）
}

事件信封（后端 → 前端，持久化后转发，seq 单调）：

{ "seq": 42, "run_id": "...", "conversation_id": "...", "ts": "...", "v": 1,
  "type": "message.delta | thinking.delta | tool.call | tool.result |
           run.phase | hitl.request | hitl.resolved |
           plan.update | todo.update |
           agent.spawn | agent.progress | agent.result |
           artifact.created | artifact.updated |
           run.completed | run.failed | error",
  "payload": { } }

• 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.15）。

4.3 后端模块划分（组合根装配，模块卡在 Backend 仓 policy/modules/ 维护）

模块	职责	关键契约
project/session	项目、会话、消息 CRUD 与检索	Query/Command
runmgr	Run 生命周期、事件产生与持久化、游标、取消传播（父 run 取消 → 子 run 级联）	Command（幂等 run 创建）+ Event
streamhub	SSE 通道、订阅、断线续传、终态对账数据	Stream
runtime	智能体执行适配：Agent-Native（主对话 + 工具）、Agent-Squad（sub-agent 编排）	进程内窄接口；失败映射稳定错误码
intentgate	Agent-Intent 接入：入口闸门 + 能力目录注入规划 + /命令识别（4.14）	可选装配，未配置 = 行为回退（T0 底线沿用其纪律）
toolreg	工具注册表：内置/插件/声明式 HTTP 工具统一注册、schema 校验、启用开关、调用审计、确认策略	Query/Command
profiles	智能体画像 CRUD、导入导出（4.7）	Query/Command
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
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.17）	Event

4.4 前端结构

• 左栏 ProjectNav：项目折叠组 → 会话列表；底部账户/设置入口；宽度拖拽（min 220 / max 420 px，可配置）；拖拽越过最小阈值并继续（约 40px 超调）→ 松手收起；收起态为图标窄栏；分隔条双击切换。宽度与收起态持久化（服务端偏好 + localStorage 双写）。
• 中栏 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 渲染，加设置项零前端改动。
• 状态 owner：服务端权威（事件 + Query 对账），前端 store 是投影；查询/命令/取消/过期结果处理按 module-contracts 前端条款明确（切换会话时取消在途请求、旧会话迟到事件按 conversation_id 分流丢弃）。

4.5 HITL 卡片协议（Core 定稿，前后端与插件共用）

{ "id": "...", "run_id": "...", "question": "采用哪种输出格式？",
  "kind": "choice",                                  // choice | input | confirm | form
  "choices": [
    { "id": "md", "label": "Markdown 文档",
      "description": "生成可版本管理的轻量文档",
      "impact": "写入 artifacts 并可在右栏查看；后续修订走 diff", "recommended": true },
    { "id": "docx", "label": "Word 文档", "description": "...", "impact": "..." }
  ],
  "allowFreeInput": true,
  "freeInputHint": "也可以直接输入你的问题或别的格式要求",
  "timeoutSec": null }

响应路由：用户点选 → hitl.resolved(choice_id)；自由输入 → 先走 intentgate 识别（是否命中澄清问题/其他意图/命令），命中其他意图或命令则挂起当前 run 并进入新对话轮（或按 run 策略取消），否则作为澄清回答回填。form kind 的字段定义复用 UI schema 词汇（同一渲染器）。发起方（运行时、工作流或插件）必须提供 impact 字段——让用户在决策点获得足够上下文。

4.6 插件体系

原则：能数据化的都数据化，代码只留接口。

插件 = manifest + 声明资产 + 可选代码模块：

Agent-System-Plugin-<Name>/
  plugin.json          # id、版本、要求的 plugin API 版本、能力声明与权限清单
  workflows/*.json     # 工作流定义（步骤、触发、绑定的意图）
  intents/*.json       # 意图 specs（agent-intent overlay 格式，slots 即 HITL 问题）
  prompts/*.md         # 角色与任务提示词
  templates/           # 文档模板（md/docx）
  panels/*.json        # 右栏面板声明（UI schema）
  cards/*.json         # 对话卡片声明（含 HITL 卡片模板）
  tools/*.json         # 声明式工具（HTTP 请求模板等，无代码）
  tools/*.go           # 可选：代码实现 ToolProvider / KnowledgeProvider
  settings.json        # 插件自身设置声明（自动出现在设置中心）

五类注册能力：

能力	形态	注册效果
工具（Tool）	声明（HTTP 模板）或代码（Go interface）	进 toolreg，Agent 可调用；受启用开关与确认策略约束
工作流（Workflow）	声明（JSON 定义 + 意图绑定）	进编排目录；命中意图即可启动；步骤可产 HITL 卡片
意图（Intent specs）	声明（agent-intent overlay）	进 intentgate 目录；slots 自动成为 HITL 询问项
知识（Knowledge）	代码（KnowledgeProvider）+ 索引数据	注册检索工具 + 右栏知识面板；复用系统 RAG 基础设施（4.12）
UI（面板/卡片）	声明（UI schema）	前端通用渲染器渲染；插件不向主 bundle 注入组件

manifest 关键字段：id、version、apiVersion（插件 API 语义版本，宿主检查兼容窗口）、provides（五类能力清单）、requires（声明的权限：网络访问域、工具执行、数据读取范围）、settings（设置声明）。权限清单在装载时展示并记录——插件能做什么一目了然（信任模型 v1：用户自装自审，权限清单用于可读性）。

UI 扩展的边界：前端只实现「通用 schema 渲染器」（有限词汇：section / list / kv / form / markdown / doc-ref / actions / chart-lite）。表达不了的高级交互 → 在 Core 提案新词汇或新卡片类型（走契约扩展流程），而不是开洞让插件写 React。这保证前端不被插件破坏。

代码类插件的隔离档位演进：

• v1：进程内（构建期组装，Dev 仓组合构建）——单用户部署、插件同生态（Go），L1 足够；崩溃风险由工具调用超时/预算兜底。
• v2（需要时）：sidecar 独立进程（HTTP，L2；原生二进制，非容器）——插件按同一 port 协议实现，pluginhost 加 transport 适配器即可升级，插件代码不变。契约从 v1 就按跨进程语义定义（四类通信契约），使该升级只是换传输。

fail-closed 与回退：manifest 校验失败整批拒绝（沿用 agent-intent 纪律）；卸载插件 = 注销其注册项，在途 run 引用的工具/工作流按「定义缺失」稳定错误码失败并提示，不静默。本计划以最小示例插件验证机制（见 P4），领域插件远期另立项。

4.7 模型接入与智能体画像

模型接入（复用 Agent-Native，不自研）：

• Provider 配置：API 端点与密钥（openai 兼容 / anthropic / 本地模型，按 Agent-Native 所支持）；密钥存服务端（加密落库或本地文件，不进 git、不回显、设置页掩码显示）。
• 模型路由按用途分类（kind）：chat（主对话）、lightweight（轻量任务：标题生成、澄清改写、记忆候选提取）、embedding（向量化，RAG/记忆检索用）、rerank（重排，RAG 用）。每类可各自指定模型与参数——不同用途不同模型是常态定制点。Embedding/Reranker 的服务部署经验直接来自老系统实测；新系统中它们是外部原生服务（URL 配置接入，如 ollama 式本地推理服务），按需启用，系统不假定其部署方式。
• 运行参数：temperature、max tokens、超时、重试预算；按「系统默认 → 画像 → 会话」三层覆盖（4.9）。
• 预算与配额：per-run token/时长/工具调用次数上限（Guidelines 故障影响控制），超限按稳定错误码终止并在 UI 呈现原因。

智能体画像（AgentProfile）——核心定制机制：

{ "id": "...", "name": "通用助手", "builtin": true,
  "systemPrompt": "...",
  "model": { "router": "main" },
  "tools": { "allow": ["*"], "deny": [], "confirm": ["http.*"] },
  "context": { "policy": "default" },
  "hitl": { "askOnAmbiguity": true, "timeoutSec": null },
  "budget": { "maxTokens": null, "maxToolCalls": 40 } }

• 内置一个默认通用画像（T0 基线）；用户可创建自定义画像——系统提示 + 模型与参数 + 工具集（允许/拒绝/需确认三清单）+ 上下文策略 + HITL 策略 + 预算，全部数据化，可导入导出（JSON 文件），不写代码。
• 会话绑定画像；sub-agent 派生时可用画像作为模板（结合 Agent-Squad 角色注册）。
• 画像是插件与用户定制的主要载体：插件可注册「画像模板」（声明资产），用户在其上微调。

4.8 工具体系与外部工具生态

• 内置最小集（骨架期）：文件读取（限项目工作区与上传文件）、工件写入、会话历史检索、时间。不预置网络抓取等高风险工具——用户可后续以声明式 HTTP 工具或插件自加（一切可禁用原则）。
• 声明式 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 设置系统与配置分层

按 Guidelines 配置规范（来源、生效时机、启动依赖、实例隔离）设计：

• 覆盖链：system defaults → user → project → conversation（深合并；数组策略显式声明，不隐式拼接）。
• Schema 在 Core 定义：每个设置项带类型、默认值、范围、生效时机（hot立即 / new-run仅影响新 run / restart需重启）与说明文案。设置页按 schema 自动渲染并标注生效时机——「改了为什么不生效」不再靠猜。
• 密钥特殊处理：独立存储、写入不回显、API 响应脱敏、导出时不包含密钥。
• 设置变更事件：hot 类设置变更经事件通道推送（多标签页/未来多客户端一致）。
• 插件与画像声明的设置项并入同一 schema 体系（来源标记），统一出现在设置中心对应分区。

4.10 上下文组装与上下文管理

发送给模型的内容由预算化分层管线组装，而非散落代码——这决定智能体「看到什么」，是行为定制的深层轴，也是长会话质量的根基：

ModelInput = SystemPrompt(画像)
           + 注入槽[memory]        ← 记忆：相关性+新近度检索，预算内（4.13，默认关闭）
           + 注入槽[knowledge]     ← 知识：按需检索注入（4.12）
           + History               ← 窗口内原文；窗口外滚动摘要（远期压缩）
           + CurrentTurn           ← 用户消息 + 附件解析结果 + @引用
           + ToolResults           ← 按截断策略

• 预算管理器：总预算 = 模型窗口 − 保留余量（输出预留）；各槽位带优先级与份额上限（画像可调，如 memory ≤5%、knowledge ≤20%）；超预算按优先级裁剪。每次裁剪记录进组装观测（4.17）——「模型为什么不知道 X」可定位、可解释。
• 历史策略：window（最近 N 条原文）为基础；窗口外原文永不删除（存储完整），仅不进上下文；滚动摘要压缩（轻量模型生成 summary 段注入）为远期增强。
• 工具结果截断：每结果上限 + 头尾保留策略；溢出自动转工件引用（「结果过长已存为工件 @artifacts:x」，模型与用户都可再取）。
• 附件与引用：上传文档经 ingest 解析（4.11）后注入；@artifacts/@knowledge 引用显式挂载（4.14）。
• 策略数据化：ContextPolicy 为数据（画像引用、可被会话覆盖），逐版本增加策略项不动组装器接口。

4.11 文档摄取与解析管线（r3 新增）

上传/工件 → 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，进程隔离；系统侧只以 URL 配置接入，默认不部署，设置启用）。定位依据用户老系统实测结论——能解析但能力有限：用于扫描件/图片型 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 模型路由)
      → 混合检索(向量索引 + 全文，均按存储档) → Rerank(可选，kind=rerank 模型路由)
      → TopK 组装 → 注入(工具结果 或 ctxasm knowledge 槽位)

组件契约（Core）：Chunker（切分策略：大小/重叠/结构感知，按 ParsedDocument blocks 切，表格不拦腰断）、EmbeddingProvider（模型路由）、VectorIndex（按存储档双实现：嵌入式档用 sqlite-vec 扩展或进程内向量扫描——个人部署规模（数万级 chunk）内暴力扫描延迟可接受；PG 档用 pgvector。接口不绑定实现，可换独立向量库，D13）、Retriever（组合器与策略）。全文检索同样按档实现（SQLite FTS5 / PG tsvector），藏在 retrieval 模块接口后。Embedding/Reranker 复用老系统已验证的服务部署经验，以原生服务形态部署（URL 配置接入，非容器假定），作为模型 provider 配置（4.7），不绑定特定实现。

索引对象与知识库管理：项目内文档（上传/工件，ingest 产物直接进索引）、插件知识库（法规等，来源标记）；设置中心展示每库索引状态（进度/失败重试/重建）。

分期：P4 契约定稿 + 全文检索最小实现（按存储档：FTS5 / tsvector，支撑 @knowledge 基础引用与命中）；向量管线（embedding + 向量索引 + 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.15 界面定制与主题

• 布局偏好：三栏宽度、收起态、右栏 tab 显隐与排序、中栏密度（舒适/紧凑）、字号。
• 主题：CSS 设计令牌（色彩/圆角/间距/字体），内置亮/暗双主题；令牌层可被用户覆盖（自定义主题 = 数据）。所有组件只消费令牌，不写死颜色——插件 UI 同样经渲染器消费令牌，自动随主题。
• 行为偏好：过程折叠默认态（自动折叠/保留展开）、流式动画开关、发送快捷键（Enter/Ctrl+Enter）。
• 全部偏好进设置系统（4.9），本地即时生效并同步服务端。

4.16 数据可携带性与开放 API

• 导出/导入：项目/会话导出为 JSON（含消息树、run 与事件、工件引用清单）或 Markdown（可读归档）；导入恢复或迁移。工件本体支持批量导出。
• 画像/设置/模板/记忆打包迁移：个人配置整体搬家（记忆实现后并入）。
• 开放 API：OpenAPI 规范随 Core 发布；脚本与第三方客户端可用同一 API 完成全部操作（API-first 原则的落地物）。

4.17 观测、调试与用量

• 事件重放：事件已持久化（seq 有序）→ 任意 run/会话可离线重放进调试视图（前端复用渲染器），开发期排障与回归演示的基础。
• 用量统计：per-run（token/时长/工具调用）→ 汇总 per-conversation/project/模型/天；设置页与项目页展示。
• 上下文组装观测：每次 run 记录各注入槽实际用量与裁剪记录（4.10）。
• 进度归属：事件携带 run 归属链（Guidelines observability），任何卡顿可定位到具体 run/工具/子代理。
• 日志走 Logging-System 对齐（脱敏、追踪标识），错误走 Error-Code-System 稳定码（intent 域沿用，系统域新增种子域按追加式流程）。

4.18 与生态库的接入点（沿用既有方案，不重造）

• Agent-Native：主对话与工具执行的实际后端（runtime 模块窄接口适配）。
• Agent-Squad：sub-agent 编排（spawn/黑板/HITL 由 runmgr 映射为统一 Run + 事件）。
• Agent-Intent：入口闸门（守卫 + 命令识别）+ 编排目录（intent catalog 注入规划）；未配置意图 = 行为回退（T0）。
• Error-Code-System / Logging-System：常量对齐 + 鸭子接口。

4.19 扩展点与定制点总览

扩展轴（系统如何长大）：

扩展轴	机制	形态	落地
工具	ToolProvider + 声明式 HTTP + MCP 适配位	声明/代码	P2 内置最小集；P4 插件注册；MCP 远期
工作流	声明定义 + 意图绑定	声明	P4 机制（示例插件演示）
意图	intent overlay，slots→HITL	声明	P3 接入，P4 插件注册
知识/RAG	KnowledgeProvider + Retrieval 管线 + 向量索引双档	基础设施+数据	P4 契约+全文最小；向量远期
解析器	ParserProvider + ParsedDocument IR	代码/服务	P2 内置档；P4 契约；MinerU/agent 档远期
记忆	MemoryStore + HITL 确认写入	数据+策略	P4 契约预留；实现远期
上下文管理	ContextPolicy + 预算管理器	数据	P2 基础；压缩/精细预算远期
UI 面板/卡片	UI schema + 通用渲染器	声明	P1 渲染器基座，P4 插件注册
模型/Provider	Agent-Native + 按 kind 路由（chat/lightweight/embedding/rerank）	配置	P2
智能体画像	AgentProfile 数据 + 画像模板	数据	P2 默认，P4 自定义 UI
命令/宏	命令注册 + intentgate	声明	P3
客户端	开放 API + OpenAPI/TS client	代码	P1 API 基线；CLI 远期
存储	对象目录接口（S3 适配位）+ VectorIndex 接口	代码	P1 本地；S3/独立向量库远期

定制轴（用户不改代码可调）：模型与参数（分层覆盖）、智能体画像、工具开关与确认策略、上下文构成与预算、命令宏与提示词模板、HITL 策略与预算、知识库与解析策略、界面布局/主题/行为偏好、面板显隐排序、记忆开关与管理、数据导出迁移。

---

5. 兼容、迁移与恢复

• 老系统：冻结不动，仅作领域知识与机制参考；远期领域插件按新系统契约全新设计，不迁移、不兼容、不搬代码。MinerU/Embedding/Reranker 复用的是部署经验与服务形态，不是老系统代码。
• 生态仓：本系统全部通过 submodule + gitlink 固定；接入时如需扩接口，走「提供方先扩展兼容契约 → 消费方适配 → 组合验证 → Dev 更新 gitlink」顺序（多仓规范）。
• 契约兼容：事件协议、插件 API、UI schema、ParsedDocument、Retrieval、Memory 契约统一版本化；字段只增不改语义；消费方对未知 type/词汇静默忽略 + 版本协商（信封 v 字段）；扩展走兼容窗口流程。
• 回退：Dev 仓恢复旧 gitlink 组合即可整体回退；数据库 schema 迁移显式设计（每阶段附回滚脚本；不假设可反向推导）。
• 未安装任何插件、未启用任何扩展（含记忆、MinerU、向量检索）时，系统即纯通用智能体对话骨架（T0 行为基线，作为验收对照）。

---

6. 验收（设计期计划，实现后补证据）

需求/验收条件	负责模块/契约	验证方法	预期结果
三栏布局：调宽/超调收起/展开/偏好持久化	Frontend ProjectNav	组件测试 + Playwright	拖拽行为与持久化符合 4.4
流式对话：区分正文/思考/工具，终态后过程折叠可回看、折叠默认可设置	streamhub + Part 渲染器	集成测试（mock runner 事件序列）+ 浏览器验收	过程 parts 折叠为摘要，展开可见
断线重连终态对账	streamhub Stream 契约	故障注入（中断 SSE）	恢复后消息树与权威 Query 一致
文件上传→解析→注入→对话闭环；解析失败显式可见	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 依赖检查	装/卸示例插件 → 核心全量回归	核心功能零回归；在途引用稳定报错
未装插件 = 通用骨架（T0 基线）	全部	无插件全量回归	与装插件前行为一致
全新 clone → 构建运行	Dev 仓	干净环境验证	一条命令起完整系统
版本发布	Releases	manifest 校验	制品与 gitlink 组合一一对应

---

7. 实施计划

每阶段一张主任务记录（Documents 仓）+ change-plan + 验证记录；Dev 仓组合推进。规模为单人开发粗估，按实际节奏调整。

7.1 本计划（骨架 + 插件机制 + 重能力契约）

P0 仓网引导（半天–1 天）

• 六个空仓初始化：README、AGENTS.md/PROJECT.md（按模板）、policy/、.gitignore、gitea 描述（按 3.2 表）、默认分支 main。
• Dev 仓建 submodule 骨架（Core/Backend/Frontend/Documents + Guidelines + 生态五仓），顶层 Makefile（组合构建/测试入口）与原生开发环境（make dev：本地直接构建运行单二进制 + 嵌入式存储，前端 Vite dev server 代理；不依赖容器。PG 档测试用本机原生 PG 或 CI 服务，不作为默认路径）。
• 本方案文档入库并推送；老系统仓补「冻结参考」描述。
• 出口：全新 clone Dev 仓 → 子模块物化 + 空构建通过；各仓描述齐全。

P1 契约与骨架闭环（4–6 天）

• Core：领域模型 + 事件信封 + HITL 卡片协议 + UI schema 词汇 + 设置 schema 框架（Go 类型 + JSON Schema + TS 类型三态一致，代码生成防漂移）+ OpenAPI 基线。
• Backend：project/session、runmgr、streamhub、mock runner（按脚本回放事件序列，不接 LLM）、SSE 端点、settings 骨架、存储层双档（SQLite 默认 / PostgreSQL 可选）schema v1。
• Frontend：三栏布局 + 左栏交互（调宽/超调收起）+ 主题令牌基座 + 中栏流式渲染与折叠 + 右栏 tab 骨架 + SSE 客户端（游标/重连/对账）+ schema 渲染器基座。
• 出口：浏览器端到端走通一轮 mock 对话，覆盖流式、折叠、断线重连；布局偏好持久化。

P2 真实智能体接入与定制基座（4–6 天）

• runtime 接 Agent-Native：真实 LLM 对话、thinking/正文/工具调用事件映射；run 取消与中断恢复策略。
• 模型接入：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：入口闸门 + 目录注入 + /命令识别；@ 引用（含 @knowledge 全文最小实现）。
• hitl 完整落地（含自由输入三路径路由：选中/澄清回填/转轨）。
• 出口：多 agent 任务全链路可视化；HITL 三路径验收过；/命令与 @ 引用可用。

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 工具用户流程。
• 出口：装卸示例插件核心零回归；插件开发指南可照做；重能力契约评审通过（后续远期实现按契约零核心改动接入）。

P5 发布链路（1–2 天）

• Releases 仓：版本 manifest 生成（从 Dev 固定提交导出）、单二进制制品（linux amd64/arm64 优先，静态链接 + go:embed 前端 + 校验和）、原生部署物料（systemd 单元示例、安装/升级/回退脚本、备份恢复说明、可选外部服务 MinerU/Embedding/Reranker 的原生接入文档）、回退演练。
• 出口：全新裸机环境「下载二进制 → systemd 启动 → 浏览器可用」；manifest↔gitlink 对应校验过。

里程碑：P1 = 可演示骨架；P2 = 可真实对话的定制基座；P3 = 可日常使用的通用智能体系统；P4 = 扩展与重能力契约验证完成；P5 = 可分发产品。

7.2 远期路线（骨架完成后另行立项，本计划不含）

项	说明
CDMO 工作流插件	医疗器械 CDMO 工作流、意图、文档模板与面板，基于新系统插件契约全新设计：工作流即数据、意图 slots 驱动 HITL、文档产出走 artifacts、面板走 UI schema。老系统仅作领域业务知识参考（流程、术语、文档体系），不迁移代码、不兼容接口、不复用数据格式。立项时先写该插件的设计方案。
法规知识库插件	KnowledgeProvider 契约实现 + 向量 RAG 管线落地（本插件为牵引方）+ 知识面板与检索工具；素材基于 08-Regulations。
向量 RAG 管线	embedding + 向量索引（按存储档：sqlite-vec/进程内扫描 或 pgvector）+ rerank 全链路；MinerU 深度解析适配器与交叉验证（D12 保留时，原生服务形态接入）。
代码执行工具	通用沙箱执行；解锁 agent 驱动解析（4.11 第三档）与更多自动化；单独立项（安全设计）。
跨会话记忆实现	4.13 契约的实现：提取、确认、注入、管理 UI。
上下文压缩增强	历史滚动摘要、精细预算管理器。
MCP 外部工具接入	ToolProvider 的 MCP 适配器，接入外部工具生态，核心零改动。
并行子任务、run 透明恢复	协议已预留（4.2），需要时开启。
CLI / headless 客户端	复用开放 API。
多用户	owner 字段已预留，认证与授权整体设计。
对象存储 S3 后端、独立向量库	按需（VectorIndex 接口已预留）。

---

8. 决策与剩余项（需用户拍板）

#	决策点	推荐	待确认
D1	Agent-System-Documents 定位	系统文档 + 跨仓过程记录仓（本设计采用）	☐
D2	插件代码形态 v1	进程内 + 构建期组装；契约按跨进程定义，v2 可升 sidecar（4.6）	☐
D3	前端栈	React 19 + Vite + TS（复用老系统经验与依赖）	☐
D4	传输	REST + SSE（v1）；WebSocket 备选	☐
D5	持久化	双档存储：默认嵌入式 SQLite + 可选 PostgreSQL（详见 D16）；对象目录本地起步、预留 S3 适配位	☐
D6	SMDF-Agent-System 空仓用途	暂不使用，待澄清后决定（弃用 / 改名纳入）	☐
D7	本地 Agent-System-Ensemble/ 空目录	用作 Agent-System-Dev 的本地工作副本（clone 目标）	☐
D8	骨架期 HITL 自由输入路由复杂度	v1 三分支（选中→回填 / 澄清→回填 / 其他意图或命令→转轨），不引入完整 DST（沿用 agent-intent 边界结论）	☐
D9	示例插件范围	随 P4 做一个最小 example 插件覆盖五类注册能力（验证机制的最小成本方式），领域插件一律远期	☐
D10	声明式 HTTP 工具进骨架期	进（P4，体量小、是「无代码扩展」主张的最有力证明）	☐
D11	MCP 适配时机	远期（v1 只做接口语义预留，4.8）	☐
D12	MinerU 定位	备选 + 交叉验证：主路线为内置代码解析器；MinerU 作为独立可选服务（默认不部署），用于扫描件/复杂版式与交叉验证；保留适配位（4.11）。若你倾向彻底弃用，则删除适配位仅留 ParserProvider 接口	☐
D13	向量索引实现	按存储档双实现：嵌入式档 sqlite-vec 或进程内向量扫描（个人规模数万 chunk 内可接受）、PG 档 pgvector；VectorIndex 接口不绑定实现，可换独立向量库	☐
D14	代码执行工具（agent 驱动解析的前提）	远期单独立项（沙箱安全设计复杂度高），v1 不做	☐
D15	记忆默认状态	默认关闭，用户显式开启；写入必须 HITL 确认（4.13）	☐
D16	默认存储档（r4 部署约束的推论）	默认嵌入式 SQLite（单文件，零外部服务，支撑单二进制开箱即用）；PostgreSQL 为可选档（原生安装、DSN 接入，面向更大规模），迁移双方言同源、CI 双档验证。若你倾向默认 PG（接受运行前置一个原生 PG），请批注	☐

批准本方案（含 D1–D15 或批注修改）后，从 P0 开始执行。