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 弹窗、工具调用展示、用量统计全部复用它：

```go
// 概念示意（详细 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 单调）：

```json
{ "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 定稿，前后端与插件共用）

```json
{ "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）——核心定制机制**：

```json
{ "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 开始执行。