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,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）。
+- 日志：标准输出（结构化程度为本版最小实现）。