From da41eb6d4540e50c82f5a325457ff117067ba9e5 Mon Sep 17 00:00:00 2001 From: V-LiuShuang Date: Tue, 22 Sep 2026 17:39:02 +0800 Subject: [PATCH] add --- harness-api.md | 151 ++++++++++++++++++++ msg.md | 365 +------------------------------------------------ sql.md | 70 ++++++++++ 3 files changed, 222 insertions(+), 364 deletions(-) diff --git a/harness-api.md b/harness-api.md index c284b99..cda517c 100644 --- a/harness-api.md +++ b/harness-api.md @@ -2,6 +2,157 @@ 以下是对应 `/harness` 路由前缀的 SE 智能体 HTTP 接口文档。 +## 根据用户意图选子智能体 + +### 基本信息 + +| 项目 | 说明 | +|------|------| +| 接口地址 | `/harness/choose/subagent` | +| 请求方式 | `POST` | +| Content-Type | `application/json` | +| 响应类型 | `text/event-stream` (SSE) | +| 接口描述 | 根据用户意图选择子智能体 | + +### 请求参数 (Request Body) + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| sessionId | Long | 是 | 会话ID | +| username | String | 是 | 用户名 | +| input | String | 是 | 用户输入内容 | + +#### 请求示例 + +```json +{ + "sessionId": 1001, + "username": "zhangsan", + "input": "帮我查看代码中的空指针异常" +} +``` + +### 响应参数 (Response Body) + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | int | 状态码 (200=成功, 500=失败) | +| msg | String | 消息内容 | +| data | Object | 响应数据对象 | +| data.sessionId | String | 会话ID | +| data.username | String | 用户名 | +| data.input | String | 用户输入 | +| data.output | String | 主智能体的输出 | +| data.subAgentId | String | 子智能体ID | + +#### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "sessionId": "1001", + "username": "zhangsan", + "input": "帮我查看代码中的空指针异常", + "output": "正在为您分配合适的子智能体...", + "subAgentId": "code-review-agent" + } +} +``` + +#### 失败响应示例 + +```json +{ + "code": 500, + "msg": "参数[sessionId]不能为空", + "data": null +} +``` + +--- + +## 保存子智能体回复 + +### 基本信息 + +| 项目 | 说明 | +|------|------| +| 接口地址 | `/harness/subagent/output` | +| 请求方式 | `POST` | +| Content-Type | `application/json` | +| 响应类型 | `text/event-stream` (SSE) | +| 接口描述 | 保存来自paw的子智能体回复内容 | + +### 请求参数 (Request Body) + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| sessionId | Long | 是 | 会话ID | +| username | String | 是 | 用户名 | +| subagentOutput | String | 是 | 子智能体回复内容 | + +#### 请求示例 + +```json +{ + "sessionId": 1001, + "username": "zhangsan", + "subagentOutput": "在第42行发现潜在的空指针异常，建议添加空值检查..." +} +``` + +### 响应参数 (Response Body) + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | int | 状态码 (200=成功, 500=失败) | +| msg | String | 消息内容 | +| data | Long | 保存的消息ID | + +#### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": 12345 +} +``` + +#### 失败响应示例 + +```json +{ + "code": 500, + "msg": "参数[username]不能为空", + "data": null +} +``` + +--- + +## 通用说明 + +### 状态码说明 + +| 状态码 | 说明 | +|--------|------| +| 200 | 操作成功 | +| 500 | 操作失败 | + +### 错误码说明 + +| 错误信息 | 说明 | +|----------|------| +| 参数[sessionId]不能为空 | sessionId为必填参数 | +| 参数[username]不能为空 | username为必填参数 | +| 参数[input]不能为空 | input为必填参数 | +| 参数[subagentOutput]不能为空 | subagentOutput为必填参数 | +| 操作失败 | 服务器内部错误 | + + ## 开启一个会话窗口 - 请求地址：{gateway}/harness/session diff --git a/msg.md b/msg.md index 99a8203..d57d09f 100644 --- a/msg.md +++ b/msg.md @@ -1,364 +1 @@ -# AgentProperties 配置文档 - -本文档描述 `AgentProperties` 类及其内部静态类的配置字段。每个字段都通过 `@Schema` 注解提供了描述信息。 - -## 主类：AgentProperties - -| 字段名 | 类型 | 描述 | -|--------|------|------| -| mainAgentSpec | MainAgentSpec | 主智能体规格 | -| workspace | Workspace | 工作区配置 | -| compaction | Compaction | 上下文压缩配置 | -| skillRepository | SkillRepository | SKILL相关配置 | -| a2sMcpProvider | McpProvider | AaaS的MCP供应商配置 | -| mcpServerConfigs | List\ | MCP服务配置列表 | -| permissionContext | PermissionContext | 权限上下文配置 | -| memoryConfig | MemoryConfig | 长期记忆配置 | -| subagentSpec | List\ | 子智能体清单 | - -## 内部类：MainAgentSpec - -主智能体规格配置。 - -| 字段名 | 类型 | 描述 | 默认值 | -|--------|------|------|--------| -| name | String | 智能体名字 | - | -| description | String | 智能体描述 | - | -| systemPrompt | String | 系统提示词 | - | -| chatModel | NewApiModelProperties | 聊天模型 | - | -| enablePlanMode | Boolean | 是否启用计划模式 | - | -| enableShell | Boolean | 是否启用SHELL | - | -| enableAgentTraceLog | Boolean | 是否打印TraceLog | - | -| asyncToolTimeout | int | 异步工具执行超时（单位：秒） | - | -| maxContextTokens | int | 最大上下文（默认：8000） | 8000 | -| maxIter | int | 最大迭代次数（默认：10） | 10 | -| maxRetries | int | 最大重试次数（默认：3） | 3 | - -## 内部类：Workspace - -工作区配置。 - -| 字段名 | 类型 | 描述 | -|--------|------|------| -| localRootPath | String | 本机根目录 | -| stateStoreType | String | 状态存储（mysql/redis） | -| isolationScope | String | 隔离级别 | -| anonymousUserId | String | 当上下文没有用户ID使用的默认值 | - -## 内部类：Compaction - -上下文压缩配置。 - -| 字段名 | 类型 | 描述 | 默认值 | -|--------|------|------|--------| -| triggerMessages | int | 触发压缩的消息数量阈值（0表示不按消息数触发） | 50 | -| triggerTokens | int | 触发压缩的token数量阈值（0表示动态模式：根据模型上下文窗口减去reserved计算） | 0 | -| reserved | int | 预留的token数量（仅动态模式使用） | 20000 | -| keepMessages | int | 压缩后保留的消息数量 | 20 | -| keepTokens | int | 压缩后保留的token数量（-1表示动态模式，0表示使用keepMessages） | -1 | -| keepTokensMin | int | 最小保留token数量（动态模式） | 2000 | -| keepTokensMax | int | 最大保留token数量（动态模式） | 8000 | -| keepTokensRatio | Double | 保留token的比例（动态模式） | 0.25 | -| summaryPrompt | String | 摘要提示词，'default'表示使用默认提示词 | - | -| flushBeforeCompact | Boolean | 压缩前是否刷新消息到存储 | true | -| offloadBeforeCompact | Boolean | 压缩前是否卸载消息到外部存储 | true | -| prune | PruneConfig | 剪枝配置 | - | -| truncate | TruncateArgs | 截断配置 | - | -| model | NewApiModelProperties | 压缩使用的模型，不设置则使用智能体主模型 | - | - -## 内部类：McpProvider - -AaaS的MCP供应商配置。 - -| 字段名 | 类型 | 描述 | 示例 | -|--------|------|------|------| -| apiGateway | String | API网关 | https://misdev.lcfuturecenter.com/prod-api | -| apiQueryMcpServerInfoUri | String | 查询MCP连接信息（批量） | /mcp/server/openapi/list | -| httpClient | HttpClientConfig | HTTP客户端配置 | - | - -## 内部类：McpServerConfig - -MCP服务配置。 - -| 字段名 | 类型 | 描述 | 默认值 | -|--------|------|------|--------| -| serverName | String | MCP服务名称 | - | -| transport | String | 协议(stdio/sse/http) | - | -| enableTools | List\ | 启用的工具列表 | - | -| initializationTimeout | int | 多少秒初始化超时（默认10秒） | 10 | -| timeout | int | 多少秒执行超时（默认600秒） | 600 | - -## 内部类：SkillRepository - -SKILL相关配置。 - -| 字段名 | 类型 | 描述 | -|--------|------|------| -| mysql | MysqlSkillRepository | 从MySQL加载 | -| classPath | ClassPathSkillRepository | 从classpath加载 | -| a2s | A2sSkillRepository | 从AaaS加载 | -| httpClient | HttpClientConfig | HTTP客户端配置 | - -## 内部类：HttpClientConfig - -HTTP客户端配置。 - -| 字段名 | 类型 | 描述 | 示例 | -|--------|------|------|------| -| version | String | HTTP协议版本，仅支持：HTTP/1.1、HTTP/2 | HTTP/1.1 | -| connectTimeout | int | 连接超时（单位：秒） | - | -| requestTimeout | int | 单个请求超时（单位：秒） | - | -| enableRequestLogger | Boolean | 是否开启请求日志打印 | - | -| enableResponseLogger | Boolean | 是否开启响应日志打印（下载或流式传输会忽略掉） | - | -| defaultHeaders | Map\ | 自定义的默认请求头 | - | - -## 内部类：A2sSkillRepository - -从AaaS加载SKILL的配置。 - -| 字段名 | 类型 | 描述 | 示例 | -|--------|------|------|------| -| enable | Boolean | 是否启用 | - | -| directory | String | 从A2s下载到服务器本地的目录 | - | -| apiGateway | String | API网关 | https://misdev.lcfuturecenter.com/prod-api | -| apiDebugSkillInfoUri | String | 查询调试版SKILL信息的URI | /mcp/skill/openapi/debug/{skill_name} | -| apiReleaseSkillInfoUri | String | 查询正式版SKILL信息的URI（支持占位符） | /mcp/skill/openapi/release/{skill_name} | -| apiDownloadSkillUri | String | 下载SKILL的地址（支持占位符） | /resource/oss/download/{oss_id} | -| availableSkills | Set\ | 可用SKILL名称列表 | - | - -## 内部类：ClassPathSkillRepository - -从classpath加载SKILL的配置。 - -| 字段名 | 类型 | 描述 | -|--------|------|------| -| enable | Boolean | 是否启用 | -| directory | String | 目录名称 | - -## 内部类：MysqlSkillRepository - -从MySQL加载SKILL的配置。 - -| 字段名 | 类型 | 描述 | -|--------|------|------| -| enable | Boolean | 是否启用 | -| databaseName | String | 数据库名称 | -| skillsTableName | String | SKILL表名称 | -| resourcesTableName | String | SKILL资源表名称 | -| createIfNotExist | Boolean | 没有表是否框架自行创建表 | -| writeable | Boolean | 平台统一管理 skill 时常用，设置为true后可以从 agent 侧写回，只读分发就设置为false | - -## 内部类：PruneConfig - -剪枝配置。 - -| 字段名 | 类型 | 描述 | 默认值 | -|--------|------|------|--------| -| protectTokens | int | 保护的token数量，剪枝时不会删除这些token | 40000 | -| minimumTokens | int | 最小token数量，剪枝后不会低于此值 | 20000 | -| maxOutputChars | int | 工具输出的最大字符数，超过则截断 | 2000 | -| excludedTools | Set\ | 排除的工具列表，这些工具的输出不会被剪枝 | ["read_file", "memory_search", "memory_get", "session_search"] | - -## 内部类：TruncateArgs - -截断配置。 - -| 字段名 | 类型 | 描述 | 默认值 | -|--------|------|------|--------| -| triggerMessages | int | 触发截断的消息数量阈值 | 25 | -| triggerTokens | int | 触发截断的token数量阈值 | 40000 | -| keepMessages | int | 截断后保留的消息数量 | 20 | -| keepTokens | int | 截断后保留的token数量 | 0 | -| maxArgLength | int | 工具参数的最大长度，超过则截断 | 2000 | -| truncationText | String | 截断时显示的提示文本 | ...(argument truncated) | - -## 内部类：PermissionContext - -权限上下文配置。 - -| 字段名 | 类型 | 描述 | 默认值 | 示例 | -|--------|------|------|--------|------| -| mode | String | 工作区权限上下文模式 | default | default/accept_edits/explore/bypass/dont_ask | -| allow | Set\ | 运行执行的工具列表 | - | - | -| deny | Set\ | 拒绝执行的工具列表 | - | - | -| ask | Set\ | 需要询问用户的工具列表 | - | - | - -## 内部类：MemoryConfig - -长期记忆配置。 - -| 字段名 | 类型 | 描述 | 默认值 | 示例 | -|--------|------|------|--------|------| -| model | NewApiModelProperties | 记忆操作（刷新 + 归纳）专用模型，不设置则使用智能体主模型 | - | - | -| flushPrompt | String | 刷新记忆的提示词，null表示使用默认值 | - | - | -| consolidationPrompt | String | 归纳记忆的提示词，必须包含两个%d占位符（max-tokens, max-chars），null表示使用默认值 | - | - | -| consolidationMaxTokens | int | 归纳时的最大token数 | 4000 | 4000 | -| consolidationMinGap | int | 归纳的最小间隔（单位：分钟） | 30 | 30 | -| dailyFileRetentionDays | int | 每日记忆文件保留天数 | 30 | 30 | -| sessionRetentionDays | int | 会话记忆JSONL日志保留天数 | 30 | 30 | -| flushTrigger | String | 每次调用后flush的触发策略（ALWAYS/NEVER） | ALWAYS | ALWAYS | - -## 内部类：SubagentSpec - -子智能体规格配置。 - -| 字段名 | 类型 | 描述 | 默认值 | -|--------|------|------|--------| -| name | String | 子智能体名称 | - | -| description | String | 子智能体描述 | - | -| systemPrompt | String | 子智能体的系统提示词 | - | -| workspaceMode | String | 工作区模式：SHARED=共享主智能体的工作区，ISOLATED=独立的工作区 | SHARED | -| model | NewApiModelProperties | 子智能体使用的模型，不设置则使用主智能体的模型 | - | -| steps | int | 这个子智能体单次最大迭代次数，不填或者设置0则使用主智能体最大迭代次数的1/2 | 0 | -| mode | String | 默认 subagent，可选：primary/subagent/all；primary 不允许被 spawn | subagent | -| hidden | Boolean | 默认false，设为 true 时不出现在 agent 可见列表（仍可程序化 spawn） | false | - ---- - -## 示例 JSON - -```json -{ - "mainAgentSpec": { - "name": "main-agent", - "description": "主智能体", - "systemPrompt": "你是一个有用的助手。", - "chatModel": { - "model": "gpt-4", - "apiKey": "your-api-key" - }, - "enablePlanMode": true, - "enableShell": false, - "enableAgentTraceLog": true, - "asyncToolTimeout": 30, - "maxContextTokens": 8000, - "maxIter": 10, - "maxRetries": 3 - }, - "workspace": { - "localRootPath": "/app/workspace", - "stateStoreType": "mysql", - "isolationScope": "USER", - "anonymousUserId": "anonymous" - }, - "compaction": { - "triggerMessages": 50, - "triggerTokens": 0, - "reserved": 20000, - "keepMessages": 20, - "keepTokens": -1, - "keepTokensMin": 2000, - "keepTokensMax": 8000, - "keepTokensRatio": 0.25, - "summaryPrompt": "default", - "flushBeforeCompact": true, - "offloadBeforeCompact": true, - "prune": { - "protectTokens": 40000, - "minimumTokens": 20000, - "maxOutputChars": 2000, - "excludedTools": ["read_file", "memory_search", "memory_get", "session_search"] - }, - "truncate": { - "triggerMessages": 25, - "triggerTokens": 40000, - "keepMessages": 20, - "keepTokens": 0, - "maxArgLength": 2000, - "truncationText": "...(argument truncated)" - }, - "model": { - "model": "gpt-4", - "apiKey": "your-api-key" - } - }, - "skillRepository": { - "mysql": { - "enable": true, - "databaseName": "skill_db", - "skillsTableName": "skills", - "resourcesTableName": "skill_resources", - "createIfNotExist": true, - "writeable": false - }, - "classPath": { - "enable": true, - "directory": "skills" - }, - "a2s": { - "enable": true, - "directory": "/app/skills", - "apiGateway": "https://misdev.lcfuturecenter.com/prod-api", - "apiDebugSkillInfoUri": "/mcp/skill/openapi/debug/{skill_name}", - "apiReleaseSkillInfoUri": "/mcp/skill/openapi/release/{skill_name}", - "apiDownloadSkillUri": "/resource/oss/download/{oss_id}", - "availableSkills": ["skill1|debug", "skill2|release"] - }, - "httpClient": { - "version": "HTTP/1.1", - "connectTimeout": 10, - "requestTimeout": 30, - "enableRequestLogger": true, - "enableResponseLogger": false, - "defaultHeaders": { - "Authorization": "Bearer token123" - } - } - }, - "a2sMcpProvider": { - "apiGateway": "https://misdev.lcfuturecenter.com/prod-api", - "apiQueryMcpServerInfoUri": "/mcp/server/openapi/list", - "httpClient": { - "version": "HTTP/1.1", - "connectTimeout": 10, - "requestTimeout": 30, - "enableRequestLogger": true, - "enableResponseLogger": false, - "defaultHeaders": {} - } - }, - "mcpServerConfigs": [ - { - "serverName": "weather-server", - "transport": "sse", - "enableTools": ["get_weather", "get_forecast"], - "initializationTimeout": 10, - "timeout": 600 - } - ], - "permissionContext": { - "mode": "default", - "allow": ["read_file", "list_files"], - "deny": ["delete_file"], - "ask": ["write_file"] - }, - "memoryConfig": { - "model": { - "model": "gpt-4", - "apiKey": "your-api-key" - }, - "flushPrompt": "刷新记忆提示词", - "consolidationPrompt": "归纳记忆提示词，最大token数：%d，最大字符数：%d", - "consolidationMaxTokens": 4000, - "consolidationMinGap": 30, - "dailyFileRetentionDays": 30, - "sessionRetentionDays": 30, - "flushTrigger": "ALWAYS" - }, - "subagentSpec": [ - { - "name": "research-agent", - "description": "研究智能体", - "systemPrompt": "你是一个研究助手。", - "workspaceMode": "SHARED", - "model": { - "model": "gpt-4", - "apiKey": "your-api-key" - }, - "steps": 5, - "mode": "subagent", - "hidden": false - } - ] -} -``` \ No newline at end of file +as \ No newline at end of file diff --git a/sql.md b/sql.md index 8ee187a..e5a5fc8 100644 --- a/sql.md +++ b/sql.md @@ -8,6 +8,7 @@ - [查项目统计数据](#查项目统计数据) - [新增devco账号](#新增devco账号) - [查paw-agent信息](#查paw-agent信息) +- [查工作流工单状态](#查工作流工单状态) ## 查智能体用户数 @@ -208,4 +209,73 @@ from `mis-paw-claw`.`agent` where create_by = < user_id >; +``` + +## 查工作流工单状态 + +```sql +CREATE DEFINER=`root`@`%` PROCEDURE `sp_flow_status_by_business_key`(IN p_business_key VARCHAR(64)) +BEGIN + -- 1) 流程实例摘要 + SELECT + h.BUSINESS_KEY_ AS business_key, + h.PROC_INST_ID_ AS process_instance_id, + SUBSTRING_INDEX(h.PROC_DEF_ID_, ':', 1) AS process_key, + h.BUSINESS_STATUS_ AS business_status, + CASE h.BUSINESS_STATUS_ + WHEN 'waiting' THEN '待审核' + WHEN 'finish' THEN '已完成' + WHEN 'back' THEN '已退回' + WHEN 'cancel' THEN '已撤销' + WHEN 'draft' THEN '草稿' + ELSE IFNULL(h.BUSINESS_STATUS_, '未知') + END AS business_status_name, + h.START_USER_ID_ AS start_user_id, + h.START_TIME_ AS start_time, + h.END_TIME_ AS end_time, + CASE WHEN h.END_TIME_ IS NULL THEN 'RUNNING' ELSE 'FINISHED' END AS flow_state, + (SELECT COUNT(1) + FROM ACT_RU_TASK t + INNER JOIN ACT_RU_EXECUTION e ON e.ID_ = t.PROC_INST_ID_ + WHERE e.BUSINESS_KEY_ = h.BUSINESS_KEY_ + AND e.PROC_INST_ID_ = h.PROC_INST_ID_) AS pending_task_count + FROM ACT_HI_PROCINST h + WHERE h.BUSINESS_KEY_ = p_business_key + ORDER BY h.START_TIME_ DESC; + + -- 2) 当前待办 + SELECT + t.ID_ AS task_id, + t.NAME_ AS task_name, + t.TASK_DEF_KEY_ AS task_definition_key, + t.ASSIGNEE_ AS assignee, + t.CREATE_TIME_ AS create_time, + t.PROC_INST_ID_ AS process_instance_id, + e.BUSINESS_KEY_ AS business_key + FROM ACT_RU_TASK t + INNER JOIN ACT_RU_EXECUTION e ON e.ID_ = t.PROC_INST_ID_ + WHERE e.BUSINESS_KEY_ = p_business_key + ORDER BY t.CREATE_TIME_ ASC; + + -- 3) 历史任务 + 意见 + SELECT + ht.ID_ AS task_id, + ht.NAME_ AS task_name, + ht.TASK_DEF_KEY_ AS task_definition_key, + ht.ASSIGNEE_ AS assignee, + ht.START_TIME_ AS start_time, + ht.END_TIME_ AS end_time, + c.TYPE_ AS comment_type, + c.MESSAGE_ AS comment_msg, + h.PROC_INST_ID_ AS process_instance_id, + h.BUSINESS_KEY_ AS business_key + FROM ACT_HI_TASKINST ht + INNER JOIN ACT_HI_PROCINST h ON h.PROC_INST_ID_ = ht.PROC_INST_ID_ + LEFT JOIN ACT_HI_COMMENT c + ON c.TASK_ID_ = ht.ID_ + AND c.TYPE_ IN ('pass', 'back') + WHERE h.BUSINESS_KEY_ = p_business_key + AND (ht.PARENT_TASK_ID_ IS NULL OR ht.PARENT_TASK_ID_ = '') + ORDER BY ht.START_TIME_ ASC, ht.ID_ ASC; +END ``` \ No newline at end of file