docs(agent): 补全会话与对话设计

docs/STUDIO_PROTOTYPE_SCHEMA.sql

@@ -235,6 +235,12 @@ CREATE INDEX IF NOT EXISTS idx_workflow_version_workflow_id ON workflow_version
 CREATE INDEX IF NOT EXISTS idx_workflow_run_workflow_id ON workflow_run (workflow_id);
 CREATE INDEX IF NOT EXISTS idx_workflow_run_status ON workflow_run (status);
 CREATE INDEX IF NOT EXISTS idx_workflow_run_step_run_id ON workflow_run_step (run_id);
+CREATE INDEX IF NOT EXISTS idx_agent_session_agent_id ON agent_session (agent_id);
+CREATE INDEX IF NOT EXISTS idx_agent_session_status ON agent_session (status);
+CREATE INDEX IF NOT EXISTS idx_agent_message_session_id ON agent_message (session_id);
+CREATE INDEX IF NOT EXISTS idx_agent_message_role ON agent_message (role);
+CREATE INDEX IF NOT EXISTS idx_agent_capability_owner ON agent_capability_binding (owner_type, owner_id);
+CREATE INDEX IF NOT EXISTS idx_agent_capability_type ON agent_capability_binding (capability_type, capability_id);
 
 COMMENT ON TABLE studio_project IS 'Studio项目空间表';
 COMMENT ON TABLE workflow_definition IS 'Workflow定义表';

script/sql/agent_capability_binding.sql

@@ -0,0 +1,23 @@
+-- Agent 与 Workflow 能力绑定表。
+
+CREATE TABLE IF NOT EXISTS agent_capability_binding (
+    id BIGSERIAL PRIMARY KEY,
+    owner_type VARCHAR(50) NOT NULL,
+    owner_id BIGINT NOT NULL,
+    capability_type VARCHAR(50) NOT NULL,
+    capability_id BIGINT NOT NULL,
+    enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    config_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT uk_agent_capability_binding UNIQUE (owner_type, owner_id, capability_type, capability_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_capability_owner ON agent_capability_binding (owner_type, owner_id);
+CREATE INDEX IF NOT EXISTS idx_agent_capability_type ON agent_capability_binding (capability_type, capability_id);
+
+COMMENT ON TABLE agent_capability_binding IS 'Agent能力绑定表';

script/sql/agent_session.sql

@@ -0,0 +1,44 @@
+-- Agent 会话与消息表。
+
+CREATE TABLE IF NOT EXISTS agent_session (
+    id BIGSERIAL PRIMARY KEY,
+    session_code VARCHAR(100) NOT NULL,
+    agent_id BIGINT NOT NULL,
+    workflow_run_id BIGINT,
+    title VARCHAR(200),
+    status VARCHAR(50) NOT NULL DEFAULT 'ACTIVE',
+    metadata_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT uk_agent_session_code UNIQUE (session_code),
+    CONSTRAINT fk_agent_session_agent_id FOREIGN KEY (agent_id) REFERENCES agent_definition (id),
+    CONSTRAINT fk_agent_session_run_id FOREIGN KEY (workflow_run_id) REFERENCES workflow_run (id)
+);
+
+CREATE TABLE IF NOT EXISTS agent_message (
+    id BIGSERIAL PRIMARY KEY,
+    session_id BIGINT NOT NULL,
+    role VARCHAR(50) NOT NULL,
+    content TEXT NOT NULL,
+    citation_json JSONB NOT NULL DEFAULT '[]'::jsonb,
+    token_count INTEGER,
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT fk_agent_message_session_id FOREIGN KEY (session_id) REFERENCES agent_session (id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_session_agent_id ON agent_session (agent_id);
+CREATE INDEX IF NOT EXISTS idx_agent_session_status ON agent_session (status);
+CREATE INDEX IF NOT EXISTS idx_agent_message_session_id ON agent_message (session_id);
+CREATE INDEX IF NOT EXISTS idx_agent_message_role ON agent_message (role);
+
+COMMENT ON TABLE agent_session IS 'Agent会话表';
+COMMENT ON TABLE agent_message IS 'Agent消息表';

前端实现文档/5.Agent会话模块前端实现.md

@@ -0,0 +1,33 @@
+# Agent 会话模块前端实现
+
+## 1. 页面
+
+`AgentWorkspacePage.vue` 当前展示 Agent 对话调试、引用切片、运行追踪和成本延迟指标。
+
+## 2. ViewModel
+
+`AgentWorkspaceView` 建议包含：
+
+- 当前 Agent 基本信息。
+- 当前会话消息列表。
+- 输入框状态。
+- 引用切片列表。
+- 模型请求 ID。
+- 运行追踪步骤。
+- 成本、延迟和 Token 统计。
+
+## 3. 接口草案
+
+- `POST /api/agents/{agentId}/runs`
+- `GET /api/agents/{agentId}/sessions`
+- `GET /api/agent-sessions/{sessionId}`
+- `POST /api/agent-sessions/{sessionId}/messages`
+
+现有 `POST /api/agents/{agentId}/chat` 保留为兼容调试入口。
+
+## 4. 交互规则
+
+- RAG 开关关闭时不展示引用切片。
+- 未召回知识切片时给出明确提示。
+- 模型调用失败时展示 `request_id` 和错误摘要。
+- 会话保存失败不得清空用户输入。

后端实现文档/5.Agent会话模块后端实现.md

@@ -0,0 +1,29 @@
+# Agent 会话模块后端实现
+
+## 1. 当前实现落点
+
+当前 Agent 定义和调试入口位于 `com.bruce.agent`。后续会话能力建议继续放在该包下。
+
+## 2. Controller 草案
+
+- `AgentDefinitionController`：保留定义管理和兼容调试入口。
+- `AgentSessionController`：新增会话查询、详情和消息发送。
+- `AgentRunController`：新增运行入口，关联 Workflow 或模型调用。
+
+## 3. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IAgentDefinitionService` | Agent 定义管理 |
+| `IAgentSessionService` | 会话创建、关闭、查询 |
+| `IAgentMessageService` | 消息写入和引用保存 |
+| `IAgentRunService` | 对话编排、RAG 召回、模型调用 |
+| `IAgentCapabilityBindingService` | 能力绑定维护 |
+
+## 4. 校验规则
+
+- Agent 必须启用才允许发起对话。
+- RAG 对话必须绑定可用知识库和 Embedding 配置。
+- 消息内容不能为空。
+- `citation_json` 必须是数组结构。
+- 会话关闭后不允许继续写入消息。

数据库设计/5.Agent会话数据库设计.md

@@ -0,0 +1,32 @@
+# Agent 会话数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `agent_definition` | Agent 定义 |
+| `agent_session` | Agent 会话 |
+| `agent_message` | Agent 消息 |
+| `agent_capability_binding` | 能力绑定 |
+
+## 2. 关键约束
+
+- `agent_definition.agent_code` 唯一。
+- `agent_session.session_code` 唯一。
+- `agent_session.agent_id` 引用 `agent_definition`。
+- `agent_session.workflow_run_id` 可引用 `workflow_run`。
+- `agent_message.session_id` 引用 `agent_session`。
+- `agent_capability_binding` 使用 `(owner_type, owner_id, capability_type, capability_id)` 唯一。
+
+## 3. JSON 字段
+
+- `agent_session.metadata_json` 保存会话扩展信息。
+- `agent_message.citation_json` 保存引用切片摘要。
+- `agent_capability_binding.config_json` 保存能力绑定配置。
+
+## 4. 脚本
+
+- `script/sql/agent_definition.sql`
+- `script/sql/agent_session.sql`
+- `script/sql/agent_capability_binding.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`

设计文档/5.Agent会话模块设计.md

@@ -0,0 +1,50 @@
+# Agent 会话模块设计
+
+## 1. 核心模型
+
+| 对象 | 说明 |
+|------|------|
+| Agent 定义 | Agent 配置主数据 |
+| Agent 会话 | 一段连续对话上下文 |
+| Agent 消息 | 会话中的单条消息 |
+| 能力绑定 | Agent 或 Workflow 绑定知识库、MCP、Skill 等能力 |
+
+## 2. 对话模式
+
+- 普通对话：直接根据会话消息调用 Chat 模型。
+- RAG 对话：先向量化问题，再召回知识切片，再组装上下文调用 Chat 模型。
+- Workflow 对话：通过绑定的 Workflow 运行，消息与运行记录互相关联。
+
+## 3. 引用设计
+
+`agent_message.citation_json` 保存回答引用：
+
+- 文档 ID。
+- 切片 ID。
+- 分数。
+- 引用文本摘要。
+- 知识库 ID。
+
+引用只保存必要摘要，完整切片仍以 `rag_chunk` 为准。
+
+## 4. 状态设计
+
+会话状态建议包括：
+
+- ACTIVE：活跃。
+- CLOSED：已关闭。
+- FAILED：异常终止。
+
+消息角色建议包括：
+
+- USER。
+- ASSISTANT。
+- SYSTEM。
+- TOOL。
+
+## 5. 模块依赖
+
+- 依赖知识资产模块完成 RAG 召回。
+- 依赖模型与路由模块完成 Chat 调用。
+- 可依赖 Workflow 模块执行复杂流程。
+- 运行观测模块读取会话关联的运行记录。

需求分析/5.Agent会话模块需求.md

@@ -0,0 +1,29 @@
+# Agent 会话模块需求
+
+## 1. 模块目标
+
+Agent 会话模块负责 Agent 定义、对话调试、会话持久化、消息记录、引用切片和运行追踪，使一次调试或发布后的对话可以被复盘。
+
+## 2. 功能需求
+
+- 支持 Agent 定义管理，包含编码、名称、系统提示词、默认知识库和状态。
+- 支持普通对话和 RAG 对话。
+- 支持会话持久化，记录 `agent_session`。
+- 支持消息持久化，记录用户、Agent、系统等角色消息。
+- 支持保存引用切片 JSON，便于回答溯源。
+- 支持关联 Workflow 运行记录，形成端到端 Trace。
+
+## 3. 会话场景
+
+1. 用户选择 Agent 输入调试问题。
+2. 系统创建或复用会话。
+3. RAG 模式下执行检索召回。
+4. 调用 Chat 模型生成回答。
+5. 写入消息、引用、模型请求 ID 和运行追踪。
+
+## 4. 关联资料
+
+- 表：`agent_definition`、`agent_session`、`agent_message`、`agent_capability_binding`
+- 脚本：`script/sql/agent_definition.sql`、`script/sql/agent_session.sql`、`script/sql/agent_capability_binding.sql`
+- 前端原型：`AgentWorkspacePage.vue`
+- 后端入口：`AgentDefinitionController`、`AgentDefinitionServiceImpl`