weichen
5825cd35f2
Why: downstream parsers are unreachable through the Host handle and the base lacks xlsx/pptx parsers; MS1 needs both. The snapshot also missed interface methods, so adding one was undetectable. Evidence: request follows compat-policy sect.6 four elements; behavior contract and limits in the proposal body (documents has no CI; verified via git diff --check recorded on the Dev task card). Impact: docs only; compat-policy sect.3 gains one sentence, usage.md format list gains xlsx/pptx. Refs: docs/proposals/2026-10-06-ext-5-host-parse-document.md
236 lines
17 KiB
Markdown
236 lines
17 KiB
Markdown
# 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 [--config envs/dev.json] [--addr 127.0.0.1:8787] [--data ./data] [--plugins ./plugins] [--mock]
|
||
agent-system config explain [--config envs/prod.json] # 只读诊断：逐字段生效值与来源，DSN 脱敏
|
||
agent-system version
|
||
```
|
||
|
||
启动参数四源合并，优先级从低到高：**内置默认 → 配置文件（`--config`，显式 JSON，无自动发现）→ 环境变量（`AGENT_SYSTEM_ADDR/DATA/PLUGINS/DSN/ARTIFACTS/AUTH/MOCK`）→ 命令行**；未显式传入的命令行参数不参与覆盖，删除 override 恢复继承。字段：`addr`（监听）、`data`（工作区根目录）、`plugins`、`dsn`（空 = 嵌入式 SQLite 档，非空 = PostgreSQL 档）、`artifacts`、`auth`（auto/on/off）、`mock`；未知键与类型错误在启动时定位报错，不静默失效。
|
||
|
||
**多环境启动**——仓库自带隔离示例 `envs/{dev,test,prod}.json`（data 根与 DB 互不重叠）：
|
||
|
||
```bash
|
||
agent-system serve --config envs/dev.json # mock 开、./data-dev
|
||
agent-system serve --config envs/test.json # 127.0.0.1:8788、./data-test
|
||
agent-system serve --config envs/prod.json # PostgreSQL 档、auth on、独立卷
|
||
AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve # 环境变量定位文件
|
||
```
|
||
|
||
- `--config`：显式配置文件（平面 JSON，键同上）；单点覆盖仍可用 `--addr`/`--dsn` 等同名参数压过文件。
|
||
- `--data`：工作区根目录（SQLite 数据库与工件对象目录；默认 ./data）。
|
||
- `--plugins`：插件目录（声明资产热加载，见 §6）。
|
||
- `--mock`：演示模式——不调用任何模型，按脚本回放完整交互（首次体验推荐）。
|
||
- 模型、检索、限流等**运行时设置**在设置页（§2），属业务策略层，不进启动配置文件——设计边界与实例隔离约定见[配置面设计](../proposals/2026-09-30-configuration-surface.md)。
|
||
|
||
浏览器打开 `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 中栏对话
|
||
|
||
- **流式渲染**：正文逐字输出；思考过程（灰字竖线）与工具调用（芯片）实时展示；顶部状态点显示事件流连接。
|
||
- **过程折叠（Cursor 式）**：流式期间思考/工具/中间轮解说照常显示；**最终回复一开始流式，过程立即折叠**为「过程输出 · N 次工具调用」摘要行，只显式显示回复（工具恢复时重新展开）；任务终态后保持折叠，点击展开回看（设置 → 界面 → 可改默认行为）。
|
||
- **长回复折叠**：终态后超过 800 字的回复自动收成「📄 长回复 · N 字（点击展开）」摘要行——流式期间全文可见，历史消息同样适用。
|
||
- **长结果进右侧卡片（默认关）**：设置 → 界面 →「长结果进右侧卡片」开启后，报告/纪要/方案/对比/文档草稿等**产物型**长内容进右栏收件箱（result 卡，可置顶/收纳）；长正文优先流式三段式——`card_begin` 建卡（收件箱即时出现 active 卡）→ `card_append` 逐段追加（卡片实时刷新，事件按 250ms 窗口节流）→ `card_commit` 收尾（转 done 并锚定到对话）；一次性短产物走 `submit_card`。中栏保留结论摘要 + 锚点部件（`📄 标题 · N 字 ▸ 展开全文 · ↗ 收件箱`）——锚点可无跳转展开全文，右栏收起时阅读不残废；解释型长回答不进卡。下一轮对话上下文自动回填卡片全文（「🧩 上下文构成」可见 card(n) 条目）；run 异常终止时未收尾的流式卡自动置 done/failed 并标注「未正常收尾」，内容不丢。
|
||
- **上下文构成观测**：每条助手消息尾部「🧩 上下文构成」折叠芯片——该轮模型实际看到什么（系统提示/历史条数/附件/知识命中）与裁剪记录（历史超窗/工具结果超限），输入规模可解释。
|
||
- **附件**：📎 上传 md/txt/docx/pdf/xlsx/pptx/图片——文档经内置解析器（确定性代码解析：md/txt 直读、docx/xlsx/pptx 解 OOXML、pdf 提取文本层）转为中间表示注入对话；解析结果与警告显式可见（不静默）。
|
||
- **输入增强**：`/` 唤起命令菜单（/new /mock /model /profile /help）；`@knowledge` 在消息中触发知识检索注入。
|
||
|
||
### 3.3 mock 演示指令（无需模型）
|
||
|
||
| 指令 | 演示 |
|
||
|---|---|
|
||
| `#hitl` | HITL 卡片：选项 + 建议 + **影响** + 自由输入（自由输入 `/` 开头会转轨为新命令并取消挂起任务） |
|
||
| `#agents` | 多代理：计划/待办更新 + 派生两个子代理（任务树、进度、结果） |
|
||
| `#squad <目标>` | **Agent-Squad 引擎编排**：规则规划器四阶段计划（梳理→专项→成文→终审）→ 计划确认卡（批准/放弃，可自由输入修改指令）→ 每步一个子代理（任务树）→ 交付物工件 |
|
||
| `#doc` | 工件产出：生成文档 → 右栏 Artifacts → 点击查看（md 可在线编辑保存） |
|
||
| `#error` | 失败路径：错误部件 + 任务失败状态 |
|
||
|
||
## 4. 核心功能操作
|
||
|
||
### 4.1 HITL 卡片（人在环）
|
||
|
||
触发途径：mock `#hitl`；真实模型调用确认策略工具（画像 `confirm` 清单，如 `http.` 前缀族）。
|
||
|
||
- 选项卡：显示描述与**影响**（决策上下文契约：每个选项必须声明可能造成的影响）。
|
||
- 自由输入三分支路由：一般输入→澄清回答回填；`/` 开头→命令转轨；**命中已注册插件意图（agent-intent 闸门）→转轨为新任务**。示例插件注册了 `demo.show` 意图（命中「示例/演示」），HITL 挂起时输入「来个示例演示」即可观察转轨。
|
||
|
||
### 4.2 收件箱与任务卡（右栏终态，D25）
|
||
|
||
右栏 = **收件箱** + 「当前任务」常驻卡（计划/待办并入，随对话实时更新）：
|
||
|
||
- 任务卡七类（progress/confirm/compare/review-list/result/error/status）：状态灯**形状+色双编码**（◆ 待处理 ● 完成 ✓ 已确认 ✕ 失败 ◌ 已关闭——不只靠颜色）；置顶不随滚动；`#upload` 演示摄取→完成→冲突对比卡全周期。
|
||
- 卡上动作即命令（card 入口，见 §5）；确认结论以**回执消息**进对话时间线留痕。
|
||
- **收纳**：🧹 一键收纳完成卡（done→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数（本会话 + 项目未决合计）。
|
||
- **项目收件箱（CF3，跨会话待办不丢）**：收件箱内「本会话 / 项目」两级切换。会话卡点 🗂 **留档到项目**——复制为项目级卡（原卡关闭留痕，不移动时间线；HITL/命令确认卡不可留档），跨会话可见；`submit_card`/`card_begin` 也可带 `scope=project` 直产项目卡。项目视图聚合 = 项目级卡片 ∪ 其他会话未决卡（done 留在原会话防噪音），经独立项目事件流实时刷新。
|
||
- 卡片↔消息**互定位**（D32）：消息内 `card:` 链接点击定位收件箱卡片；HITL/确认卡锚定发起消息内联双现。
|
||
|
||
### 4.3 工作区弹层（深读与治理视图，⌘1–9）
|
||
|
||
工件/代理/插件面板不再占右栏 tab，统一为**工作区弹层**（Esc/遮罩关闭回对话现场；不承载唯一步骤）：
|
||
|
||
- ⌘1 工件 · ⌘2 代理 · ⌘3+ 插件面板/插件声明工作区（example 插件含「治理总览」示例，⌘9）。
|
||
- 左栏「工作区」快捷区同清单；会话头左侧为**项目徽章**（D26 不加全局顶栏）。
|
||
- Sub-agent 追踪：代理工作区任务树点击任意节点 → 追踪弹窗（状态/用量徽标/中间过程消息）。
|
||
- 真实模型模式下，模型可经 `delegate_task` 派生子代理、经 `squad_orchestrate` 发起引擎编排（多步骤目标建议后者：计划确认 + 交付物把关）。
|
||
|
||
### 4.4 计划 / 待办
|
||
|
||
并入右栏「当前任务」常驻卡（真实模型经 `update_plan` / `update_todos` 工具维护；mock `#agents` 演示）。
|
||
|
||
### 4.5 工件
|
||
|
||
- 上传与模型产出统一入 Artifacts；`write_artifact` 工具可被模型调用。
|
||
- 查看：markdown 在线渲染；文本类可**编辑保存**；二进制（docx/pdf）下载；图片内联预览。
|
||
- 文档工件与上传文本自动进**知识索引**（全文检索）。
|
||
- **工件门面卡（与产物卡统一呈现）**：工具结果被截断超限时自动在收件箱留一张 `result` 门面卡（摘要 + 来源工具 + `doc-ref` 引用，点击直开查看器）——字节权威仍在工件（可编辑/下载），卡只做门面与锚；下一轮对话上下文会自动回填工件文本（上限与产物卡同为 12000 字，超限在「🧩 上下文构成」可见 `artifact(n)` 与截断记录），模型不再对工具大结果失忆。
|
||
|
||
### 4.6 知识检索
|
||
|
||
- API：`GET /api/knowledge/search?q=临床评价&project=<id>`；对话内 `@knowledge` 注入；模型工具 `knowledge_search`。
|
||
- 中文检索：FTS5 分词对 CJK 无效时自动 LIKE 子串兜底（本版实测中文命中正常）。
|
||
|
||
### 4.7 智能体画像（核心定制机制）
|
||
|
||
设置 → 智能体画像：内置「通用助手」（只读 T0 基线）+ 新建/导入/导出/编辑：
|
||
|
||
- 系统提示、允许/确认/拒绝工具三清单（`*` 全部、`http.` 前缀族）、HITL 策略、预算（工具次数/轮次上限）。
|
||
- 导出为 JSON 迁移；会话头部下拉切换画像。
|
||
|
||
## 5. 命令总线（四入口同源，D27）
|
||
|
||
按钮、卡片 action、`/` 命令、对话意图四个入口命中同一命令产生**同一条执行与审计**（`POST /api/commands/{id}`；审计 `GET /api/commands/audit`）。注册表数据驱动（内置 + 插件 `provides.commands`）：
|
||
|
||
| `/` 命令 | 命令 id | 作用 |
|
||
|---|---|---|
|
||
| `/help` | builtin.help | 命令列表 |
|
||
| `/new` | conversation.create | 新建会话 |
|
||
| `/mock on\|off` | runtime.mock | 演示模式切换 |
|
||
| `/model <名称>` | models.set | 设置主模型 |
|
||
| `/profile <id>` | conversation.profile | 切换会话画像 |
|
||
|
||
`danger=high` 的命令（含插件命令）执行终点为**内联确认卡**：锚定发起消息、阻断待确认、已决折叠留痕（双现于收件箱）。
|
||
|
||
## 6. 插件
|
||
|
||
### 6.1 装载与热重载
|
||
|
||
插件目录（默认 `./plugins`，设置可改）下每子目录一个插件（`plugin.json` + 声明资产）。
|
||
设置 → 插件 → **⟳ 热重载**（或 `POST /api/plugins/reload`）：目录扫描，新插件装载、消失插件卸载。
|
||
**装卸不影响核心**：内置工具与功能零回归；坏资产整批拒绝（fail-closed），错误显式呈现。
|
||
|
||
### 6.2 示例插件（`example`）
|
||
|
||
随发布携带，覆盖七类注册能力：声明式 HTTP 工具（`http_echo`）、面板（工作区弹层呈现）、
|
||
卡片模板（`note`）、意图 spec（`demo_intent`）、提示词模板、插件设置项，以及 **命令声明**（`example.echo`，经命令总线四入口可调）与**工作区声明**（`example.governance`「治理总览」，⌘9）。
|
||
|
||
### 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}
|
||
任务卡 GET /api/conversations/{id}/cards · POST /api/cards/{id}/actions/{actionId} · POST /api/cards/{id}/pin|dismiss
|
||
命令总线 GET /api/commands（注册表）· POST /api/commands/{id} {params,entrance,conversationId} · GET /api/commands/audit
|
||
工作区 GET /api/workspaces（插件工作区声明）
|
||
上传/工件 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. 运维要点
|
||
|
||
### 8.1 存储双档（默认嵌入式；多用户切 PG）
|
||
|
||
- 默认档（不变）：`<data>/agent-system.db`（SQLite WAL）+ `<data>/artifacts/`（对象目录）；单二进制、零外部服务。
|
||
- PostgreSQL 档（多用户/多实例）：`agent-system serve --dsn "postgres://user:pass@host/db?sslmode=disable"`；原生安装，非容器。自动启用认证与事件扇出（NOTIFY/LISTEN）；多实例时工件目录指共享卷（`--artifacts`）。
|
||
- schema 迁移：随启动自动执行（版本表 `schema_migrations`，v1–v5，双方言可回滚：`MigrateDown` 为运维入口）。
|
||
|
||
### 8.2 认证与租户（API key）
|
||
|
||
- 嵌入式档默认无认证（本地单用户）；PG 档默认要求 API key（`--auth auto|on|off`）。
|
||
- 密钥管理（明文仅创建时显示一次）：
|
||
|
||
```bash
|
||
agent-system apikey create --owner alice --name dev # 嵌入式档
|
||
agent-system apikey create --dsn "postgres://…" --owner bob # PG 档
|
||
agent-system apikey list|revoke --owner alice [--name dev]
|
||
```
|
||
|
||
- 客户端：`Authorization: Bearer ask_…`；浏览器 SSE 用 `?key=` 兜底；前端设置登录门自动出现。
|
||
- 租户隔离：跨租户访问一律 404；共享知识（owner=''）对全体可见。
|
||
|
||
### 8.3 备份与限流
|
||
|
||
- 嵌入式档在线备份：`POST /api/admin/backup` → `<data>/artifacts/backups/agent-system-<ts>.db`（VACUUM INTO，一致性快照）。日常"拷目录"前建议先执行（活库 WAL 直接拷贝不安全）。
|
||
- PG 档：`pg_dump` + WAL 归档（标准 PG 运维；接口按设计返回指引）。
|
||
- 租户限流：设置 `runtime.rateLimitPerMin`（0=不限，多用户建议 300–1200；429 超限）。多实例共享限流设 `runtime.redisAddr`（原生 Redis，重启生效）。
|
||
|
||
### 8.4 其他
|
||
|
||
- 服务停机：SIGTERM 优雅关闭，在途任务标记 `interrupted`（界面提示，可一键重发）；事件缓冲停机前冲净。
|
||
- 会话内串行：一个会话同时至多一个在途 run（重复发送返回 409）。
|
||
- 向量 RAG：设置 `models.embedding.*`（OpenAI 兼容 `/embeddings`）后自动启用分块+向量+RRF 混合检索；`models.rerank.*` 可选重排；未配置 = 纯全文（默认）。
|
||
- 日志：标准输出（结构化程度为本版最小实现）。
|