Add the 0.1.0 usage report

Details (original message): Add the 0.1.0 usage report, test report, plugin development guide, and P0-P5 implementation record; index the docs tree.
2026-09-29 18:07:44 +00:00
parent e13eb5c38e
commit 196baf7c8c
5 changed files with 483 additions and 0 deletions
@@ -0,0 +1,20 @@
+# Agent-System-Documents
+
+系统文档与过程记录仓：架构决策、方案与验证记录、使用与插件开发指南；不含产品代码。
+
+## 目录
+
+```text
+docs/
+  proposals/   设计方案（骨架设计/方案/计划，含 D1–D16 决策）
+  guides/      使用报告 · 插件开发指南
+  reports/     测试报告
+  records/     实施记录（阶段、决策、偏差）
+```
+
+## 当前版本
+
+0.1.0（2026-09-29）：[使用报告](docs/guides/usage.md) · [测试报告](docs/reports/2026-09-29-test-report.md) ·
+[实施记录](docs/records/2026-09-29-implementation.md) · [设计方案](docs/proposals/2026-09-29-system-skeleton-design-and-plan.md)
+
+规范基线：Development-Guidelines（Dev 仓 `deps/development-guidelines`）。
@@ -0,0 +1,136 @@
+# 插件开发指南
+
+面向 Agent-System v0.1.0（plugin API `1.0`）。原则：**能数据化的都数据化，代码只留接口**——
+插件 = manifest + 声明资产 + 可选代码；声明资产热加载，装卸不触碰核心二进制。
+
+参考实现：Dev 仓 `plugins/example`（覆盖全部五类能力，可直接复制改造）。
+
+## 1. 目录结构
+
+```
+my-plugin/
+  plugin.json          # 必需：manifest
+  tools/*.json         # 声明式 HTTP 工具（v1 代码工具走远期 sidecar 档）
+  workflows/*.json     # 工作流定义（步骤：prompt/tool/hitl/artifact）
+  intents/*.json       # 意图 specs（agent-intent overlay 形态；slots 即 HITL 询问项）
+  prompts/*.md         # 提示词/画像模板
+  panels/*.json        # 右栏面板（UI schema）
+  cards/*.json         # 对话卡片模板（UI schema）
+  settings.json        # 插件自身设置声明（自动出现在设置中心）
+```
+
+## 2. Manifest
+
+```json
+{
+  "id": "my-plugin",                  // 唯一；即目录名
+  "name": "我的插件",
+  "version": "0.1.0",
+  "apiVersion": "1.0",                // 宿主兼容窗口检查（不匹配整批拒绝）
+  "requires": { "network": ["api.example.com"] },   // 权限清单（装载时可见）
+  "provides": {                        // 声明各目录下的资产名（不含扩展名）
+    "tools": ["http_fetch"], "intents": ["ask"],
+    "panels": ["main"], "cards": ["note"], "prompts": ["writer"], "settings": ["apikey"]
+  }
+}
+```
+
+**fail-closed**：任一资产缺失/非法 JSON/manifest 不合法 → 该插件整批拒绝，错误在启动日志与
+`POST /api/plugins/reload` 响应中显式呈现；既有注册不受影响。
+
+## 3. 五类能力
+
+### 3.1 声明式 HTTP 工具（tools/*.json）
+
+```json
+{
+  "name": "http_fetch",
+  "description": "获取 URL 内容",
+  "parameters": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] },
+  "http": {
+    "method": "GET",
+    "url": "{{param.url}}",
+    "headers": { "Accept": "application/json" },
+    "authRef": "models.chat.apiKey",      // 或 env:MY_TOKEN；引用设置密钥/环境变量
+    "resultPath": "data.items",            // jq 点路径裁剪（支持数组索引）；空取整个响应
+    "timeoutMs": 10000
+  }
+}
+```
+
+- 模板变量 `{{param.x}}` 从模型调用参数注入；无脚本语义（防注入）。
+- 注册后受画像三清单约束（默认画像对 `http.` 前缀族要求执行前 HITL 确认）。
+- 调用审计自动记录（入参摘要/状态/时长）。
+
+### 3.2 工作流（workflows/*.json）
+
+步骤四类：`prompt`（发指令模板）/ `tool`（调工具）/ `hitl`（产卡片）/ `artifact`（产出工件）。
+`intentId` 绑定意图后，命中即可启动（意图→工作流的联动消费在编排侧持续增强，v1 为目录数据）。
+
+### 3.3 意图（intents/*.json）
+
+agent-intent overlay 形态（数组）：
+
+```json
+[ { "id": "ask", "domain": "demo", "description": "…", "includes_any": ["示例"], "slots": [] } ]
+```
+
+slots 声明即 HITL 该问什么（能力目录理念）；宿主识别闸门接入后自动成为命令/分流入口。
+
+### 3.4 面板与卡片（UI schema 有限词汇）
+
+panels/main.json：
+
+```json
+{ "id": "main", "title": "我的面板",
+  "body": [
+    { "type": "markdown", "markdown": "## 说明\n…" },
+    { "type": "kv", "title": "状态", "kv": [["版本", "0.1.0"]] },
+    { "type": "list", "items": ["要点一", "要点二"] },
+    { "type": "doc-ref", "docId": "art_xxx" },
+    { "type": "actions", "actions": [{ "id": "refresh", "label": "刷新" }] },
+    { "type": "chart-lite", "chart": { "kind": "bar", "labels": ["A","B"], "series": [3, 5] } },
+    { "type": "section", "title": "分组", "children": [ … ] }
+  ] }
+```
+
+cards/note.json：`{ "kind": "note", "data": [ …UINode ] }`。
+
+**词汇边界**：section / list / kv / form / markdown / doc-ref / actions / chart-lite。
+表达不了的高级交互 → 向 Core 提案新词汇（契约扩展流程），**不要**期望注入 React 组件——前端不开放此口子，这是插件不破坏前端的机制保证。
+
+### 3.5 提示词模板（prompts/*.md）
+
+内容即模板正文；用户可复制为自有画像后微调。
+
+### 3.6 插件设置（settings.json）
+
+```json
+[ { "key": "apikey", "group": "plugin:my-plugin", "label": "服务密钥", "type": "secret", "effect": "hot" } ]
+```
+
+自动出现在设置中心 `plugin:my-plugin` 分区；`type: secret` 掩码显示不回显。
+
+## 4. 装载、热重载与卸载
+
+- 启动装载：`agent-system serve --plugins <dir>`。
+- 热重载：设置 → 插件 → ⟳（或 `POST /api/plugins/reload`）——重扫目录：新增装载、同 ID 重载（先注销旧注册再装新）、消失卸载。
+- 卸载语义：注册项注销；在途任务对已卸载工具的引用按「定义缺失」稳定报错，不静默；内置能力零影响（测试断言覆盖）。
+
+## 5. 验证清单（发布前自测）
+
+```bash
+# 1) manifest 与资产合法性（重载结果应无错误）
+curl -s -X POST localhost:8787/api/plugins/reload
+# 2) 注册结果
+curl -s localhost:8787/api/tools | jq '.[] | select(.pluginId=="my-plugin")'
+curl -s localhost:8787/api/plugins | jq '.[] | select(.manifest.id=="my-plugin")'
+# 3) 装卸回退（移走目录→reload→内置功能应完全正常）
+mv plugins/my-plugin /tmp/ && curl -X POST localhost:8787/api/plugins/reload
+```
+
+## 6. 领域插件立项提示（CDMO 等）
+
+按既定决策（设计 r2/r3）：领域插件基于本契约**全新设计**——工作流即数据、意图 slots 驱动 HITL、
+文档产出走 artifacts、面板走 UI schema；不迁移老系统代码/接口/数据格式，老系统仅作领域业务知识参考。
+立项时先写该插件的设计方案（建议放本仓 docs/proposals/）。
@@ -0,0 +1,168 @@
+# Agent-System 使用报告（v0.1.0）
+
+日期：2026-09-29；对象：Agent-System 0.1.0（Dev 组合 `6a70d1a`，Releases 制品 sha256 `6cdcc30f…`）。
+配套：[测试报告](../reports/2026-09-29-test-report.md) · [插件开发指南](plugin-development.md) · [设计方案](../proposals/2026-09-29-system-skeleton-design-and-plan.md)
+
+## 1. 获取与安装
+
+### 1.1 发布制品（推荐）
+
+```bash
+# Releases 仓构建（或直接取 build/0.1.0/agent-system-0.1.0.tar.gz）
+cd Agent-System-Releases && scripts/build-release.sh 0.1.0
+tar xzf build/0.1.0/agent-system-0.1.0.tar.gz -C /tmp/rel && cd /tmp/rel
+./install.sh verify                 # manifest↔制品 sha256 校验：一致 ✓
+sudo ./install.sh install           # systemd 部署 → http://127.0.0.1:8787
+sudo ./install.sh rollback          # 回退上一版本
+```
+
+产物为**单二进制**（约 13MB，静态链接，内嵌前端与嵌入式 SQLite）+ 示例插件目录 + 部署物料。
+无容器、无运行时依赖；任意 Linux x86_64/arm64 可运行。**注意：本版本未发布容器镜像，也不需要。**
+
+### 1.2 源码构建（Dev 仓）
+
+```bash
+git clone --recurse-submodules <dev-url> Agent-System-Dev && cd Agent-System-Dev
+make build    # 契约同步 → 前端构建 → embed → CGO_ENABLED=0 静态链接 → bin/agent-system
+make test     # 全量测试
+make demo     # 一键演示（构建 + mock 模式启动）
+```
+
+### 1.3 启动
+
+```bash
+agent-system serve [--addr 127.0.0.1:8787] [--data ./data] [--plugins ./plugins] [--mock]
+agent-system version
+```
+
+- `--data`：SQLite 数据库与工件对象目录（默认 ./data）。
+- `--plugins`：插件目录（声明资产热加载，见 §6）。
+- `--mock`：演示模式——不调用任何模型，按脚本回放完整交互（首次体验推荐）。
+
+浏览器打开 `http://127.0.0.1:8787` 即三栏工作台（开发期前端热更新：Dev 仓 `make dev`）。
+
+## 2. 模型接入（真实对话）
+
+设置（右下 ⚙ 或收起栏齿轮）→ **模型与密钥**：
+
+| 设置项 | 说明 | 生效 |
+|---|---|---|
+| 主模型 Base URL / API Key / 名称 | OpenAI 兼容端点（如 `https://api.openai.com/v1`） | 立即 / 新任务 |
+| 轻量模型 | 子代理与轻任务；空则回落主模型 | 立即 / 新任务 |
+| Embedding / Reranker | 检索管线预留（向量档远期启用） | 预留 |
+
+密钥掩码显示、不回显；生效时机在每项设置右侧标注（立即/新任务/需重启）。
+
+**未配置模型时**：开启 设置 → 运行时 → 演示模式（或 `--mock` 启动），全部交互可离线体验。
+
+## 3. 界面与交互
+
+### 3.1 三栏布局
+
+- **左栏**（项目/会话）：项目折叠组 → 会话列表；✚ 建项目；底部「新会话 / 设置」。
+- **拖拽调宽**：拖动左右分隔条（左栏 220–420px）。**超调收起**：继续向左拖过最小宽度约 40px 后松开即收起；分隔条**双击**也可切换；收起后为图标窄栏。
+- **右栏**（工作台）：计划 / 待办 / 工件 / 代理 + 插件面板 tab；可调宽（280–560px）、双击收起。
+- 布局偏好（宽度/收起/主题/折叠行为）本地持久化。
+
+### 3.2 中栏对话
+
+- **流式渲染**：正文逐字输出；思考过程（灰字竖线）与工具调用（芯片）实时展示；顶部状态点显示事件流连接。
+- **过程折叠**：任务完成后，思考与工具调用折叠为「⚙ 过程输出 · N 次工具调用」摘要行，点击展开回看（设置 → 界面 → 可改默认行为）。
+- **附件**：📎 上传 md/txt/docx/pdf/图片——文档经内置解析器（确定性代码解析：md/txt 直读、docx 解 OOXML、pdf 提取文本层）转为中间表示注入对话；解析结果与警告显式可见（不静默）。
+- **输入增强**：`/` 唤起命令菜单（/new /mock /model /profile /help）；`@knowledge` 在消息中触发知识检索注入。
+
+### 3.3 mock 演示指令（无需模型）
+
+| 指令 | 演示 |
+|---|---|
+| `#hitl` | HITL 卡片：选项 + 建议 + **影响** + 自由输入（自由输入 `/` 开头会转轨为新命令并取消挂起任务） |
+| `#agents` | 多代理：计划/待办更新 + 派生两个子代理（任务树、进度、结果） |
+| `#doc` | 工件产出：生成文档 → 右栏 Artifacts → 点击查看（md 可在线编辑保存） |
+| `#error` | 失败路径：错误部件 + 任务失败状态 |
+
+## 4. 核心功能操作
+
+### 4.1 HITL 卡片（人在环）
+
+触发途径：mock `#hitl`；真实模型调用确认策略工具（画像 `confirm` 清单，如 `http.` 前缀族）。
+
+- 选项卡：显示描述与**影响**（决策上下文契约：每个选项必须声明可能造成的影响）。
+- 自由输入：作为澄清回答回填；`/` 开头识别为命令→取消挂起任务并转轨（三分支路由）。
+
+### 4.2 Sub-agent 追踪
+
+- 右栏「代理」tab：任务树（对话任务 + 子代理，状态点动画）。
+- 点击任意节点 → **追踪弹窗**：状态、token/时长/工具用量徽标、**中间过程消息**（子代理产出已持久化）。
+- 真实模型模式下，模型可经 `delegate_task` 工具自主派生子代理。
+
+### 4.3 计划 / 待办
+
+右栏「计划 / 待办」实时更新（真实模型经 `update_plan` / `update_todos` 工具维护；mock `#agents` 演示）。
+
+### 4.4 工件
+
+- 上传与模型产出统一入 Artifacts；`write_artifact` 工具可被模型调用。
+- 查看：markdown 在线渲染；文本类可**编辑保存**；二进制（docx/pdf）下载；图片内联预览。
+- 文档工件与上传文本自动进**知识索引**（全文检索）。
+
+### 4.5 知识检索
+
+- API：`GET /api/knowledge/search?q=临床评价&project=<id>`；对话内 `@knowledge` 注入；模型工具 `knowledge_search`。
+- 中文检索：FTS5 分词对 CJK 无效时自动 LIKE 子串兜底（本版实测中文命中正常）。
+
+### 4.6 智能体画像（核心定制机制）
+
+设置 → 智能体画像：内置「通用助手」（只读 T0 基线）+ 新建/导入/导出/编辑：
+
+- 系统提示、允许/确认/拒绝工具三清单（`*` 全部、`http.` 前缀族）、HITL 策略、预算（工具次数/轮次上限）。
+- 导出为 JSON 迁移；会话头部下拉切换画像。
+
+## 5. 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/help` | 命令列表 |
+| `/new` | 新建会话 |
+| `/mock on\|off` | 演示模式切换 |
+| `/model <名称>` | 设置主模型 |
+| `/profile <id>` | 切换会话画像 |
+
+## 6. 插件
+
+### 6.1 装载与热重载
+
+插件目录（默认 `./plugins`，设置可改）下每子目录一个插件（`plugin.json` + 声明资产）。
+设置 → 插件 → **⟳ 热重载**（或 `POST /api/plugins/reload`）：目录扫描，新插件装载、消失插件卸载。
+**装卸不影响核心**：内置工具与功能零回归；坏资产整批拒绝（fail-closed），错误显式呈现。
+
+### 6.2 示例插件（`example`）
+
+随发布携带，覆盖五类注册能力：声明式 HTTP 工具（`http_echo`）、右栏面板（「示例面板」tab）、
+卡片模板（`note`）、意图 spec（`demo_intent`）、提示词模板、插件设置项（出现在设置中心）。
+
+### 6.3 无代码自定义工具（声明式 HTTP）
+
+`POST /api/tools`（body 为 ToolDesc，含 `http` 段：method/url/bodyTemplate/resultPath/authRef）→ 注册即用，
+受画像确认策略约束。模板变量 `{{param.x}}`；`authRef` 支持 `env:VAR` 或设置密钥路径。详见[插件开发指南](plugin-development.md)。
+
+## 7. API 一览（API-first：UI 之外的自动化入口）
+
+```
+项目/会话   POST/GET /api/projects · POST/GET …/conversations · GET /api/conversations/{id}（终态对账）
+消息与运行  POST /api/conversations/{id}/messages（含命令路由）· POST /api/runs/{id}/cancel · GET /api/runs/{id}（含子任务树）
+事件流      GET /api/events?conversationId=&since=（SSE；Last-Event-ID 游标续传；心跳 15s）
+HITL       POST /api/hitl/{id}/resolve {choiceId|freeText}
+上传/工件   POST /api/projects/{id}/uploads（multipart，返回解析结果）· GET/PUT /api/artifacts/{id}/content
+画像/设置   GET/POST /api/profiles · GET /api/settings · PUT /api/settings/user|project/{id}（schema 驱动）
+工具/插件   GET/POST/DELETE /api/tools · GET /api/plugins · POST /api/plugins/reload · GET /api/registry（来源标记）
+计划/检索   GET /api/conversations/{id}/plan|todos · POST /api/projects/{id}/knowledge · GET /api/knowledge/search
+```
+
+示例：`curl -N "http://127.0.0.1:8787/api/events?conversationId=<id>&since=0"` 可直接观察事件流。
+
+## 8. 运维要点
+
+- 数据：`<data>/agent-system.db`（SQLite WAL）+ `<data>/artifacts/`（对象目录）；备份即拷目录。
+- 服务停机：SIGTERM 优雅关闭，在途任务标记 `interrupted`（界面提示，可一键重发）。
+- 升级/回退：`install.sh install/rollback`；数据库迁移随启动自动执行（本版为初始 schema）。
+- 日志：标准输出（结构化程度为本版最小实现）。
@@ -0,0 +1,28 @@
+# 实施记录：P0–P5（2026-09-29）
+
+按[设计方案](../proposals/2026-09-29-system-skeleton-design-and-plan.md)（r4，D1–D16 按推荐执行）完成骨架全量实施。
+验证证据见[测试报告](../reports/2026-09-29-test-report.md)；使用说明见[使用报告](../guides/usage.md)。
+
+## 阶段记录
+
+| 阶段 | 内容 | 出口达成 | 关键提交 |
+|---|---|---|---|
+| P0 仓网 | 六仓初始化推送、gitea 描述（含老系统「冻结参考」）、Dev submodule 组合（10 组件，生态 pin 与既有纪律一致） | ✓ 全新 clone 物化+组合构建通过 | Dev `286fdaa` |
+| P1 契约+骨架 | Core 契约（Go+黄金样本+TS 三态，conformance 测试）；Backend 存储层/SSE/事件信封；Frontend 三栏+流式+折叠 | ✓ mock 对话端到端 | Core `992d601` 起 |
+| P2 真实智能体 | agent-native `runtime/llm` 客户端复用（多轮工具循环、reasoning→thinking 映射、usage 归集、预算执行）；模型路由按 kind；画像/设置/上下文组装/摄取（md/txt/docx OOXML/pdf 文本层） | ✓（真实模型路径代码+单测就位；live smoke 以 mock 验证协议，模型联调待用户密钥） | Backend `8aa5e8d` |
+| P3 编排/HITL | sub-agent 统一 Run 任务树（spawn/progress/result 事件+子代理消息持久化）、AgentTracker 弹窗、计划/待办、HITL 三分支路由、`/` 命令与 `@knowledge` | ✓（Agent-Squad 引擎适配为偏差项 #1，见测试报告 §6） | 同上 |
+| P4 插件机制 | pluginhost（manifest 校验/五类能力/fail-closed/热重载/卸载语义）、统一注册表+来源标记、声明式 HTTP 工具、示例插件、schema 驱动设置中心、插件开发指南 | ✓ | Backend + Dev `plugins/example` |
+| P5 发布 | Dev Makefile（契约同步→前端→embed→静态单二进制）；Releases 构建管线（manifest sha256 + systemd + 安装/回退）；0.1.0 发布 | ✓ 13MB 单二进制；12 项制品 smoke 全过 | Releases `6c40909` |
+
+## 关键实现决策（实施期新增）
+
+1. **存储**：modernc.org/sqlite（纯 Go → CGO_ENABLED=0 静态链接的前提）；`values` 为 SQLite 保留字需引号；FTS5 unicode61 对 CJK 无效 → LIKE 子串兜底（中文检索实测可用）。
+2. **RunCtx 端口**：Runner 只见受控环境接口（Emit/AskHITL/SpawnSubagent/ExecuteTool/…），编排全在 runmgr——mock 与 LLM 两种 runner、会话与子代理两种 run 共用同一套生命周期与事件语义。
+3. **编排型工具**：`delegate_task` / `update_plan` / `update_todos` 作为模型可调用工具实现多代理与计划维护（LLM runner 内建，不走注册表）。
+4. **子代理中间过程**：子 run 的助手消息持久化（带 run_id 归属），弹窗「中间过程」直接消费消息树（权威数据源），在线态另有 agent.progress 事件。
+5. **SSE**：先订阅后重放+seq 去重消除间隙丢事件；心跳 15s；终态对账走 conversationDetail Query。
+6. **前端零 UI 框架**：react+marked 仅两项运行时依赖；设计令牌手写（亮/暗主题 data-theme 切换）；契约 TS 镜像由 `make contracts` 从 Core 生成（单一来源）。
+
+## 偏差与后续（详见测试报告 §6）
+
+Agent-Squad 引擎适配、Agent-Intt 闸门接入、向量 RAG、记忆实现、MinerU 深度档、docx 在线预览、PG 存储档、裁剪观测 UI、Playwright 套件、多用户——均已在契约/数据位层面预留，落地不改核心。
@@ -0,0 +1,131 @@
+# Agent-System 测试报告（v0.1.0）
+
+日期：2026-09-29；对象：Dev 组合 `6a70d1a`（core `992d601` / backend `97b90ad` / frontend `5b6b52d` / documents `d7ce944` + 生态五仓 pin）。
+范围：设计方案第 6 节验收表的逐项验证 + 单元/集成/端到端/真实运行四层证据。
+复现环境：go1.27.1 linux/amd64、node v26.10.0；命令见 §5。
+
+## 1. 测试总览
+
+| 层 | 位置 | 数量 | 结果 |
+|---|---|---|---|
+| 契约一致性（Core 黄金样本） | Agent-System-Core `go test ./...` | 9 | 全部通过 |
+| 后端单元+端到端 | Agent-System-Backend `go test ./...`（server/ingest/tools/plugins 四包） | 19 | 全部通过 |
+| 前端契约形状（vitest，黄金样本驱动） | Agent-System-Frontend `npm test` | 5 | 全部通过 |
+| 真实运行验证（发布制品 smoke） | 本报告 §3 | 12 项检查 | 全部通过 |
+| 组合构建验证 | Dev `make build` / Releases `build-release.sh 0.1.0` | — | 通过（单二进制 13MB 静态链接；sha256 校验一致） |
+
+合计 33 项自动化测试 + 12 项 live 检查，全绿。
+
+## 2. 自动化测试明细
+
+### 2.1 Core（契约仓）
+
+| 用例 | 验证点 |
+|---|---|
+| TestGoldenDomain/Events/HITL/ProfileAndTools/Ingest/Plugin | 领域模型/事件信封/HITL 卡片/画像/HTTP 工具/ParsedDocument/插件 manifest 的线格式与黄金样本逐字节一致（三态契约的权威侧） |
+| TestToolPolicy | 三清单语义：`*` 允许、`http.admin.` 前缀拒绝优先于 `*`、`http.` 前缀需确认 |
+| TestPlainText | ParsedDocument → 纯文本（标题/段落/表格） |
+| TestSettingsMergeAndPath | 覆盖链深合并与点路径读取（含数值默认） |
+
+### 2.2 Backend
+
+| 用例 | 验证点（对照设计验收表） |
+|---|---|
+| server.TestMockConversationFlow | mock 全链路：run 完成；助手消息含 text/thinking/tool_call/tool_result 四类部件；**过程部件带 process 标记（终态折叠依据）**；lastSeq 游标为正 |
+| server.TestHITLChoiceFlow | 卡片出现；**每个选项必含 impact（决策上下文契约断言）**；选项解析→run 完成；消息树含 HITL 摘要部件 |
+| server.TestHITLFreeTextPivot | 自由输入 `/new` → pivoted=true；挂起 run 转为 cancelled（**三分支路由之转轨**） |
+| server.TestSubagentFlow | 两个子代理 run：kind=subagent、父子关系正确、全部 completed（**任务树**） |
+| server.TestArtifactFlow | 工件创建（kind=document）+ 内容可取 |
+| server.TestUploadParseAndKnowledge | md 上传→multipart→解析结果返回；**中文全文检索命中**（FTS5→LIKE 兜底路径） |
+| server.TestSSEStreamAndReplay | 真实 SSE 连接：在线收到 message.delta 与 run.completed；事件 id 单调；since 游标重放端点 200 |
+| server.TestCommandsRoute | `/help` 命令路由返回；未知命令 400 |
+| server.TestStaticServed | SPA 路由不异常（空 embed 下行为受控） |
+| ingest.TestParseMarkdown / TestParseDocx / TestParsePDFInvalid / TestParseUnknownBinary | md 结构化（标题/段落/列表）；**docx 构造样张（OOXML 解析：标题级别/段落/表格）**；非法 pdf 低置信度+显式警告；二进制未知类型不产生假块（**解析失败可见不静默**） |
+| tools.TestHTTPExecutorTemplateAndPath / TestExpandTemplate | 声明式 HTTP 工具：模板变量注入、ResultPath 裁剪、路径缺失显式错误、404 状态映射 |
+| plugins.TestLoadAndRegister / TestUnloadRemovesRegistrations / TestFailClosedOnBadAsset / TestAPIVersionGuard | 五类能力注册；**卸载后内置工具零回归**；**坏资产整批拒绝（fail-closed，不部分注册）**；apiVersion 兼容窗口守卫 |
+
+### 2.3 Frontend
+
+| 用例 | 验证点 |
+|---|---|
+| contracts.message 判别联合 | 黄金样本按 type 解析（toolCall/toolResult/text/process 标记） |
+| contracts.stream event 信封 | seq/v/type/payload 字段 |
+| contracts.hitl impact 契约 | 选项 impact 必有（与后端断言镜像） |
+| contracts.profile 三清单 | allow/deny/confirm 形状 |
+| SSE 帧解析 | data 帧解析与游标推进逻辑 |
+
+## 3. 真实运行验证（发布制品 smoke，12 项）
+
+制品：Releases `build/0.1.0/agent-system-0.1.0.tar.gz`（sha256 `6cdcc30f…`，manifest↔制品校验一致 ✓）。
+
+| # | 检查 | 结果 | 证据摘录 |
+|---|---|---|---|
+| 1 | 单二进制静态链接 | ✓ | `ELF 64-bit … statically linked`，13MB |
+| 2 | 健康检查 | ✓ | `GET /api/health → {"ok":true,…}` |
+| 3 | 内嵌 SPA | ✓ | `GET / → <title>Agent-System</title>` |
+| 4 | 插件装载（example） | ✓ | `/api/plugins → [('example', panels 1, intents 1)]` |
+| 5 | 项目/会话创建 | ✓ | prj_32f7…/cnv_476b… |
+| 6 | mock 消息→run | ✓ | run pending→… |
+| 7 | SSE 在线流 | ✓ | 单轮对话 **101 帧**（run.phase/thinking.delta/tool.call/tool.result/message.delta…），id 单调 |
+| 8 | HITL 卡片→选项解析→完成 | ✓ | resolve→`resolved:true`；终态 runs=[('run…','conversation','completed')]；消息树 [hitl,text] 部件 |
+| 9 | 上传解析 | ✓ | md → `parser: builtin:md, blocks: 2` |
+| 10 | 中文知识检索 | ✓ | `q=临床评价 → hits: [('reg.md','fulltext')]` |
+| 11 | 游标重放端点 | ✓ | `since=0` 重放 200（TestSSEStreamAndReplay 同源验证） |
+| 12 | 发布包自包含运行 | ✓ | 解包独立目录启动→health/SPA/插件全部正常 |
+
+## 4. 验收表对照（设计方案第 6 节）
+
+| 验收条件 | 状态 | 证据 |
+|---|---|---|
+| 三栏布局：调宽/超调收起/展开/持久化 | ✅ 实现 | App.tsx 拖拽+超调 40px 判定+双击+localStorage（组件级逻辑；浏览器手工验证路径在用例中覆盖逻辑分支，Playwright 套件列为后续项） |
+| 流式对话：区分正文/思考/工具，终态折叠可回看、默认可设置 | ✅ 实现+测试 | TestMockConversationFlow（process 标记）+ smoke #7 + 设置 autoCollapseProcess |
+| 断线重连终态对账 | ✅ 实现+测试 | SSE Last-Event-ID/since 游标 + TestSSEStreamAndReplay + 前端 reconcile() 以 Query 收敛 |
+| 文件上传→解析→注入→对话闭环；失败显式 | ✅ 实现+测试 | TestUploadParseAndKnowledge + ingest 四用例（含失败可见性） |
+| 工件查看 | ✅ 实现+测试 | TestArtifactFlow + DocViewer（md 渲染/编辑保存/图片/下载） |
+| HITL 三路径 | ✅ 实现+测试 | 选中回填（Choice）/自由回填（FreeText→澄清）/命令转轨（Pivot→cancel+新消息） |
+| sub-agent 弹窗：任务树/中间过程/结果 | ✅ 实现+测试 | TestSubagentFlow + AgentTracker（子代理消息持久化 `06478c2`） |
+| 模型路由与画像生效 | ⚠️ 部分 | 画像 CRUD/导入导出/三清单与会话绑定实现并有单测（Core TestToolPolicy + profiles）；「三层覆盖链各取一例」的集成测试与轻量模型回落实测**未写自动化用例**（设置生效时机已 schema 标注；待真实模型联调时补） |
+| 上下文预算与裁剪可观测 | ⚠️ 部分 | 截断+超长转工件已实现（runmgr.ExecuteTool / ctxasm 窗口）；**裁剪记录的组装观测 UI 未做**（ctxasm Report 已产出数据位） |
+| 声明式 HTTP 工具注册即用 | ✅ 实现+测试 | tools.TestHTTPExecutorTemplateAndPath + POST /api/tools |
+| 设置 schema 驱动零前端改动 | ✅ 实现 | SettingsModal 全 schema 渲染 + 插件设置项自动并入（plugin:example 分区实测出现） |
+| 示例插件装卸不破坏核心 | ✅ 实现+测试 | plugins 四用例（含卸载后内置工具存活、fail-closed、apiVersion 守卫） |
+| 未装插件 = 通用骨架（T0） | ✅ 实现+测试 | 空插件目录全链路 e2e 通过（newTestServer 即空目录） |
+| 全新 clone → 构建运行 | ✅ 实现 | Releases build-release.sh 从零 clone→make build→运行 smoke（#12） |
+| 版本发布 | ✅ 实现 | 0.1.0 manifest（10 组件 gitlink+sha256）+ verify 校验一致 |
+
+**结论：15 项验收中 13 项达成、2 项部分达成（偏差与处置见 §6）。**
+
+## 5. 复现命令
+
+```bash
+# 全量测试
+cd Agent-System-Dev && make test          # core 9 + backend 19 + frontend 5，全绿
+# 单二进制构建与演示
+make build && make demo                   # http://127.0.0.1:8787（mock）
+# 发布构建与校验
+cd ../Agent-System-Releases && scripts/build-release.sh 0.1.0
+cd build/0.1.0 && ./install.sh verify     # sha256 一致
+# 后端单包
+cd Agent-System-Backend && go test ./internal/server/ -v
+```
+
+## 6. 已知边界与偏差（诚实清单）
+
+| # | 项 | 现状 | 计划 |
+|---|---|---|---|
+| 1 | **Agent-Squad 编排适配** | 未接入（设计 P3 计划项）。sub-agent 经统一 Run 模型以 LLM 轻任务（delegate_task）与 mock 脚本实现，任务树/事件/弹窗全链路可用 | 按 squad 引擎接口补 adapter（契约已就位，runmgr SpawnSubagent 即挂点） |
+| 2 | **Agent-Intent 闸门** | 未接入 agent-intent 识别器；HITL 自由输入路由为两分支（选项/命令转轨+默认回填），未做「命中其他意图→转轨」识别 | 接入 deps/agent-intent（后端已具备 submodule 接线模式）；插件 intents 资产目前仅目录透出 |
+| 3 | 向量 RAG | 未实现（契约/模型路由类别/全文最小实现已交付，中文检索可用） | 远期：pgvector/sqlite-vec + rerank（设计 4.12） |
+| 4 | 记忆系统 | 契约与开关位预留，无实现 | 远期（设计 4.13） |
+| 5 | MinerU 深度解析/交叉验证 | 未接（解析器注册位与失败可见性已具备；扫描件 pdf 显式低置信度+提示） | 远期（D12） |
+| 6 | docx 在线预览 | 下载查看（md/txt 在线渲染编辑）；docx OOXML 解析为上下文注入已实现 | 前端预览器增强（老系统有 docx-preview 经验可鉴） |
+| 7 | PostgreSQL 存储档 | 仅 SQLite 档（D16 默认档）；存储层经独立 store 包隔离 | 需要时按接口补 PG 方言 |
+| 8 | ctxasm 裁剪观测 UI | 数据位有（AssembleReport），界面未呈现 | 后续小项 |
+| 9 | 前端 Playwright E2E | 未建立（组件逻辑经 store 纯函数 + 契约测试覆盖主干） | P4/P5 后补浏览器套件 |
+| 10 | 多用户/鉴权 | 无（单用户本地部署，owner 字段预留） | 远期整体设计 |
+
+## 7. 质量注记
+
+- **提交与组合**：六仓全部推送 gitea；Dev gitlink 权威（`6a70d1a` 固定 10 组件）；生态 pin 与 Agent-Intent 记忆的纪律一致（guidelines `26b562d2` / errcode `dbeed2f` / logsys `2c5716f` / intent `7d9d505`）。
+- **部署约束符合性**：无 Dockerfile/compose；产物为静态单二进制 + systemd 原生物料；构建链（make/npm/go）全原生。
+- **fail-closed 纪律**：插件坏资产整批拒绝（测试覆盖）；解析失败显式呈现；未配置模型/插件时系统仍完整可用（T0 基线）。