Files

T

weichen 196baf7c8c 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

8.9 KiB

Raw Blame History

Agent-System 使用报告（v0.1.0）

日期：2026-09-29；对象：Agent-System 0.1.0（Dev 组合 6a70d1a，Releases 制品 sha256 6cdcc30f…）。配套：测试报告 · 插件开发指南 · 设计方案

1. 获取与安装

1.1 发布制品（推荐）

# 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 仓）

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 启动

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 或设置密钥路径。详见插件开发指南。

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

8.9 KiB Raw Blame History Unescape Escape