Files

T

weichen 1b1489203d Document project inbox dual view and archive flow (CF3)

Why: D48-D51 add the project inbox (archive-to-project, aggregated
project view, project stream); guide needs the user-facing story.
Evidence: usage.md 4.2 gains project inbox bullet; badge note updated.
Impact: docs-only.
Refs: 2026-09-30-card-stream-artifact-unify-project-inbox.md (D48-D52).

2026-09-30 19:18:12 +00:00

17 KiB

Raw Permalink 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 [--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 互不重叠）：

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），属业务策略层，不进启动配置文件——设计边界与实例隔离约定见配置面设计。

浏览器打开 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/图片——文档经内置解析器（确定性代码解析：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→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数（本会话 + 项目未决合计）。
项目收件箱（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 或设置密钥路径。详见插件开发指南。

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）。
密钥管理（明文仅创建时显示一次）：

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

17 KiB Raw Permalink Blame History Unescape Escape