# 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 中栏对话

- **流式渲染**：正文逐字输出；思考过程（灰字竖线）与工具调用（芯片）实时展示；顶部状态点显示事件流连接。
- **过程折叠**：任务完成后，思考与工具调用折叠为「⚙ 过程输出 · N 次工具调用」摘要行，点击展开回看（设置 → 界面 → 可改默认行为）。
- **上下文构成观测**：每条助手消息尾部「🧩 上下文构成」折叠芯片——该轮模型实际看到什么（系统提示/历史条数/附件/知识命中）与裁剪记录（历史超窗/工具结果超限），输入规模可解释。
- **附件**：📎 上传 md/txt/docx/pdf/图片——文档经内置解析器（确定性代码解析：md/txt 直读、docx 解 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→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数。
- 卡片↔消息**互定位**（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）下载；图片内联预览。
- 文档工件与上传文本自动进**知识索引**（全文检索）。

### 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.*` 可选重排；未配置 = 纯全文（默认）。
- 日志：标准输出（结构化程度为本版最小实现）。