✅ 第一阶段 SPEC V0.1(执行侧拆分 · 信任模型 · 告警上云)- 修正版
文档版本:v2.4
编制日期:2026-07-08
架构方案:Electron + FastAPI + PyInstaller
核心原则:端侧黑盒专项(隐私) + 云端白盒专项(红线唯一执行者) + 主Agent信任Subagent + 告警报告强制上云
原则
说明
执行侧拆分
端侧 Subagent 仅执行黑盒专项 (隐私),云端 Agent 是白盒红线专项的唯一执行者 ,两者按 test_type 路由,无规模阈值判断
数据属地原则
隐私测试数据量小,可留存端侧;红线扫描涉及大规模代码分析,数据必须留存云端 ,端侧不落盘红线代码
信任边界
阶段四质量门禁融合到阶段三,由 Subagent 自检;主Agent 默认信任 Subagent 产出,不做二次校验
告警强制上云
所有告警必须同步至云端告警统一管理平台 ,端侧不维护告警库,仅做展示和标注采集
告警同步机制
告警同步失败时采用临时队列缓存 (内存+本地临时文件),仅用于重试,重试3次后丢弃并记录失败日志;端侧不提供告警查询、检索、管理功能 ,不视为"告警库"
云端容错策略
① 提交失败 :自动重试最多3次(指数退避),仍失败 → 标记任务为 ERROR,提示用户"云端服务不可用,请稍后重试";② 云端不可用 :直接报错,不降级到端侧执行红线(安全性考虑)
维度
端侧(客户端)
云端
测试类型
privacy(黑盒专项)
redline(白盒红线专项,唯一执行者)
代码处理
轻量:读取本地代码仓,函数签名提取
重量:Git 拉取 + AST 解析 + 调用图 + 污点追踪
数据留存
隐私测试结果可留存端侧(轻量)
红线扫描数据必须留存云端 ,端侧只读最终报告
告警库
不维护告警库,仅展示云端同步结果
维护统一告警库(指纹匹配+继承+知识库)
执行环境
用户本地桌面(资源受限)
云端服务器(弹性算力)
结果产出
result.json(标准化)
result.json(标准化,格式与端侧一致)
---
config:
layout: elk
elk:
mergeEdges: true
nodePlacementStrategy: LINEAR_SEGMENTS
look: handDrawn
theme: neutral
---
%%{init: {
'flowchart': {
'subGraphTitleMargin': {
'top': 15,
'bottom': 15
}
}
}}%%
flowchart TD
Start([用户启动客户端]) --> custom_input
subgraph custom_input[输入源]
custom_action_1[测试需求描述]
custom_action_2[测试对象输入]
end
custom_input --> S0
subgraph S0[阶段零:输入接入与预处理]
S0_1[0.1 OpenAPI 解析 → <br>Paths/Schemas ]
S0_2[0.2 需求文本解析 → <br>提取测试范围 ]
S0_3[0.3 Token 截断保护]
S0_1 --> S0_2 --> S0_3
end
S0 --> S1
subgraph S1[阶段一:主 Agent 规划与拆解]
S1_1[意图识别 & 测试类型分类]
S1_2[任务拆解与依赖分析(DAG)]
S1_3[规划结果固化 → plan.json<br>(含 test_type,<br>不含 execution_target)]
S1_1 --> S1_2 --> S1_3
end
S1 --> S2
subgraph S2[阶段二:路由决策层]
S2_1[输入:plan.json<br>(含 test_type)]
S2_2[路由表(配置驱动):<br>redline → cloud<br>privacy → local]
S2_3[输出:增强 plan.json<br>(含 execution_target)]
S2_1 --> S2_2 --> S2_3
end
S2 --> S3
S2 --> S4
subgraph Executor["阶段三:执行层"]
subgraph S3[execution_target = local<br>阶段三-A:端侧执行]
direction TB
S3_1[获取设备与应用]
S3_2[执行 SKILL]
S3_3[★Subagent 自检格式<br>校验字段<br>补全单次<br>重试]
S3_4[回写 result.json<br>★ 含 alarm_fingerprint]
S3_1-->S3_2-->S3_3-->S3_4
end
subgraph S4[execution_target = cloud<br>阶段三-B:云端执行]
direction TB
S4_1[提交云端任务<br>POST:/api/cloud/submit]
S4_2[获取代码仓]
S4_3[执行 SKILL]
S4_4[★Subagent 自检格式<br>校验字段<br>补全单次<br>重试]
S4_5[回写 result.json<br>★ 含 alarm_fingerprint]
S4_1 --> S4_2 --> S4_3 --> S4_4 --> S4_5
end
end
S4-->S5
subgraph S5[主Agent轮询器]
S5_1[每15~30秒查询]
end
S3-->S6
S5-->S6
subgraph S6[阶段四:主Agent汇聚结果]
direction TB
S6_1[读取所有 result.json<br>(本地+云端)]
S6_2[Pydantic 标准化]
S6_3[置信度标定]
end
S6-->S7
S6-->S10
subgraph Report["阶段五:报告生成与管理"]
subgraph S7[报告交付(端侧只读报告)]
S7_1[CSV/JSON 导出]
S7_2[LLM 三段式摘要]
end
subgraph S8[客户端报告展示]
S8_1[展示云端同步的告警库]
end
subgraph S9[用户标注动作]
S9_1[标记误报 / 确认漏洞]
end
subgraph S10[告警同步(异步并行)]
S10_1[批量上报告警至云端告警平台]
S10_2[所有报告必须上云]
end
subgraph S11[告警统一管理平台]
S11_1[告警指纹匹配 + 继承]
S11_2[误报白名单 + 知识库沉淀]
S11_3[告警大盘 + 工单联动]
end
S7 --> S8
S8 --> S9
S10 --> S11
end
S9-->S12
S11-->S12
subgraph S12[知识持续进化(闭环)]
direction TB
S12_1[需求自发现,注入阶段一]
S12_2[风险自发现,注入阶段四]
end
Loading
【横向支撑底座 —— 贯穿全流程】
① 模型智能路由(opencode-fusion)
② 上下文工程(opencode-contexty)
③ 隔离保障八重体系
④ 可观测性三支柱:Traces + Metrics + Logs
⑤ 配置与资源治理:opencode.json + $WORKSPACE + cleanup
★ ⑥ 路由配置表:config.yaml(test_type → execution_target 映射)
★ ⑦ 共享代码仓库:domain/(端云共用数据模型 + 指纹算法)
★ 信任边界说明:主Agent与Subagent之间的信任契约
主Agent职责: - 规划 → 拆解任务 - 委托 → 按 test_type 路由分发(端侧 or 云端) - 汇聚 → 收集结果,不做二次校验 - 呈现 → 展示报告
Subagent职责: - 执行 → 完成SKILL检查 - 自检 → 格式校验 + 字段补全 + 单次重试(原阶段四内容) - 回写 → 写出合规的 result.json
信任假设: ✅ 主Agent默认Subagent产出的result.json是合规的、可信的 ✅ Subagent自检失败时 → 自己标记status=FAILED,写入error.json ❌ 主Agent不替Subagent兜底
需求ID
需求描述
验收标准
变更类型
I-001
OpenAPI 3.0 解析:YAML/JSON → Paths/Schemas 抽取
同 V2.2
不变
I-002
需求文本解析:提取用户描述的测试范围和目标
① 支持自然语言提取;② 提取结果用于辅助测试类型分类
新增
I-003
Token 截断保护:cl100k_base 校验,超限渐进截断
同 V2.2
不变
需求ID
需求描述
验收标准
变更类型
P-001
意图识别 & 测试类型分类:识别用户需求 → 判定 test_type(redline / privacy)
① 分类准确率 ≥ 90%;② 输出 test_type 枚举值
增强
P-002
任务拆解与依赖分析:生成 Subtask DAG,depends_on ≤ 1
同 V2.2
不变
P-003
规划结果固化:→ plan.json,含 test_type,不含 execution_target
① 所有任务含 test_type;② 不含 execution_target(由路由层填充)
增强
需求ID
需求描述
验收标准
变更类型
R-001
读取 plan.json,按 test_type 匹配路由表,标记 execution_target
① 路由表可配置(config.yaml);② redline→cloud,privacy→local,其他→local(默认)
新增
R-002
输出增强 plan.json(含 execution_target)
① 每个任务均有 execution_target;② 路由决策记录在日志中
新增
需求ID
需求描述
验收标准
变更类型
L-001
工作区隔离:/workspaces/sess_{uuid}/task_{uuid}/
同 V2.2
不变
L-002
执行 SKILL:隐私专项
① 调用对应 SKILL 入口;② 不含红线 SKILL 逻辑
调整
L-003
★ Subagent 自检:格式校验 + 字段补全 + 单次重试(原阶段四)
① 自检失败→status=FAILED,写入error.json;② 主Agent不校验
新增融合
L-004
回写 result.json:含 alarm_fingerprint
① 字段完整;② 指纹使用 domain/ 统一算法
增强
阶段三-B:云端执行(红线白盒专项 + 任务轮询)
需求ID
需求描述
验收标准
变更类型
C-001
云端任务提交:POST /api/cloud/submit,含 repo_url + credential + openapi_context
① 返回 cloud_task_id;② 异步执行
新增
C-002
Git 拉取服务:clone / fetch / 增量更新
① 支持 HTTPS/SSH;② 凭证用完销毁
新增
C-003
代码图谱构建:AST 解析 + 调用图生成
① 支持 Python/Java/JS/Go;② 输出调用链
新增
C-004
污点追踪引擎:API 参数 → 敏感函数路径追踪
① 追踪跨文件数据流;② 输出威胁路径
新增
C-005
★ Subagent 自检:格式校验 + 字段补全 + 单次重试
① 同端侧自检标准;② 格式与端侧一致
新增融合
C-006
回写 result.json:★ 数据留存云端,端侧只读最终报告
① result.json 存云端;② 端侧通过HTTP拉取展示,不落盘代码
新增
C-007
★ 云端任务轮询:提交任务后异步轮询结果
① 轮询间隔 15~30 秒;② 任务完成时自动通过 HTTP GET /api/cloud/result/{cloud_task_id} 下载 result.json;③ 超时(30分钟)标记为 TIMEOUT
新增
需求ID
需求描述
验收标准
变更类型
M-001
读取所有 result.json(本地+云端),统一汇聚
① 本地读取工作区;② 云端通过 HTTP GET /api/cloud/result/{cloud_task_id} 拉取;③ 拉取成功后缓存在本地工作区用于展示
增强
M-002
Pydantic 标准化:UnifiedTestResult 模型
同 V2.2
不变
M-003
置信度标定:≥0.8 / ≤0.6
同 V2.2
不变
需求ID
需求描述
验收标准
变更类型
R-001
CSV/JSON 导出(结构化数据)
同 V2.2
不变
R-002
LLM 三段式摘要(结论/风险/建议)
同 V2.2
不变
R-003
★ 告警同步上云(异步并行):批量上报全部告警至云端告警平台
① 不阻塞报告展示;② 失败时缓存本地重试(最多3次,指数退避);③ 3次均失败 → 丢弃并记录失败日志,端侧不持久留存
新增
R-004
★ 所有报告必须上云:报告元数据 + 告警数据同步至云端
① 云端可查询历史报告;② 端侧仅展示,不维护告警库
新增
from pydantic import BaseModel , Field
from typing import Optional , List
from datetime import datetime
import uuid
from enum import Enum
# === 测试类型枚举 ===
class TestType (str , Enum ):
REDLINE = "redline"
PRIVACY = "privacy"
# PERFORMANCE = "performance" # V0.1 已删除
# === 执行模式枚举 ===
class ExecutionMode (str , Enum ):
LOCAL = "local"
CLOUD = "cloud"
# === 路由表条目 ===
class RoutingRule (BaseModel ):
test_type : TestType
execution_target : ExecutionMode
# === plan.json 模型 ===
class TestTask (BaseModel ):
task_uuid : str = Field (default_factory = lambda : str (uuid .uuid4 ()))
task_name : str
target_api : Optional [str ] = None
test_type : TestType # 必填
brief_description : str
depends_on : List [str ] = []
# ★ execution_target 由路由层填充
execution_target : Optional [ExecutionMode ] = None
class TestPlan (BaseModel ):
schema_version : str = "2.4"
session_id : str
generated_at : datetime
total_tasks : int
tasks : List [TestTask ]
# === result.json 模型(含自检状态) ===
class AlarmItem (BaseModel ):
fingerprint : str
file_path : str
line_start : int
line_end : int
rule_id : str
severity : str
description : str
code_snippet : Optional [str ] = None
inherited_from : Optional [str ] = None
inherited_conclusion : Optional [str ] = None
class TestResult (BaseModel ):
task_uuid : str
status : str # SUCCESS | FAILED | TIMEOUT | ERROR | SKIPPED | MISSING
summary : str = "No summary provided"
alarms : List [AlarmItem ] = []
alarm_fingerprints : List [str ] = [] # ★ Subagent 生成
execution_seconds : float = - 1.0
retry_count : int = 0
error_type : Optional [str ] = None
error_message : Optional [str ] = None
execution_mode : ExecutionMode
# ★ Subagent自检结果
self_check_passed : bool = Field (False , description = "Subagent自检是否通过,必须显式设置" )
self_check_details : Optional [str ] = Field (None , description = "自检失败时的详细错误信息" )
self_check_errors : Optional [List ['SelfCheckError' ]] = Field (default_factory = list )
# === error.json 模型(Subagent自检失败时写入) ===
class SelfCheckError (BaseModel ):
field_path : str # 如 "alarms[0].fingerprint" 或 "summary"
error_type : str # MISSING_FIELD | INVALID_TYPE | SCHEMA_MISMATCH | FORMAT_ERROR
error_message : str
actual_value : Optional [str ] = None
expected_format : Optional [str ] = None
class SubagentErrorReport (BaseModel ):
task_uuid : str
session_id : str
execution_mode : ExecutionMode
timestamp : datetime = Field (default_factory = datetime .now )
self_check_passed : bool = False
errors : List [SelfCheckError ] = []
retry_count : int = 0
max_retries : int = 1 # 单次重试
resolution : Optional [str ] = None # 如 "MANUAL_REQUIRED" | "RETRY_FAILED"
# === 汇聚后统一模型 ===
class UnifiedTestResult (TestResult ):
confidence_score : float = 0.5
review_required : bool = False
workspace_path : str
session_id : str
开发
主责模块
核心任务
预估工期
与 V2.3 对比
Dev-A
底座 + 调度 + FastAPI + 路由层 + 云端客户端
① 工作区/日志/超时;② 调度器(端侧+云端分支);③ FastAPI 应用入口;④ ★ 路由决策层(config.yaml 驱动);⑤ 云端任务提交+轮询封装;⑥ Electron 主进程 + 目录选择器
6.5 天
+0.5 天
Dev-B
输入预处理 + 主 Agent 规划 + 测试类型分类
① OpenAPI 解析;② 需求文本解析(辅助分类);③ ★ 意图识别 + test_type 分类(LLM Prompt);④ 规划输出(含 test_type,不含 execution_target);⑤ 初始化 pyproject.toml
4.5 天
+0.5 天
Dev-C
Subagent 适配 + 自检闭环
① ★ 端侧 Subagent 移除红线逻辑(仅隐私);② ★ Subagent 自检闭环(格式校验+字段补全+单次重试+error.json生成);③ 端侧 Subagent 结果回写;④ 提供云端 Agent 自检标准参考实现
3.5 天
+1.5 天
Dev-D
结果汇聚 + 报告 + 前端 + 告警同步
① 结果汇聚/置信度/导出/摘要;② ★ 告警指纹生成(domain/ 统一算法);③ ★ 告警同步客户端(强制上云+缓存重试);④ ★ React 界面适配(报告页告警标注+继承标记);⑤ ★ 端侧告警库不维护,仅展示云端数据
8.5 天
+0.5 天
总工期 :Dev-D 是瓶颈(8.5 天),并行开发后第 9~10 天联调,预留 3 天异常处理,总周期约 3 周(15 个工作日) 。
project-root/
├── domain/ # ★ 新增:端云共享代码仓库
│ ├── models/
│ │ ├── alarm.py # AlarmItem, AlarmFingerprint
│ │ ├── result.py # TestResult, UnifiedTestResult
│ │ ├── error.py # ★ SubagentErrorReport, SelfCheckError
│ │ └── common.py # 枚举(TestType, ExecutionMode)
│ ├── algorithms/
│ │ └── fingerprint.py # ★ 告警指纹算法(单点定义)
│ └── version.py # 版本号
│
├── frontend/
│ └── src/
│ └── renderer/
│ ├── pages/
│ │ ├── Dashboard.tsx # 测试类型选择(隐私/红线)
│ │ ├── Progress.tsx # 云端任务差异化展示
│ │ └── Report.tsx # ★ 告警标注 + 继承标记(数据来自云端)
│ └── components/
│ ├── TestTypeSelector.tsx # ★ 新增:测试类型选择组件
│ └── AlarmAnnotation.tsx # ★ 新增:告警标注组件
│
├── backend/
│ ├── config.yaml # ★ 新增:路由配置表
│ ├── core/
│ │ ├── input_parser/
│ │ │ └── intent_classifier.py # ★ 新增:测试类型分类
│ │ ├── planner/
│ │ │ └── plan_generator.py # 输出含 test_type(不含 execution_target)
│ │ ├── router/ # ★ 新增:路由决策层
│ │ │ └── task_router.py # 读取 config.yaml → 填充 execution_target
│ │ ├── scheduler/
│ │ │ ├── local_executor.py # 端侧 Subagent 调度
│ │ │ └── cloud_executor.py # 云端任务提交 + 轮询
│ │ └── reporter/
│ │ ├── alarm_fingerprint.py # 使用 domain/ 算法
│ │ ├── alarm_sync.py # ★ 强制上云 + 临时缓存重试
│ │ └── result_loader.py # 本地+云端统一汇聚
│ └── models.py # 使用 domain/ 模型
│
├── workspaces/
│ └── sess_{uuid}/
│ └── task_{uuid}/
│ ├── plan.json # 任务规划
│ ├── result.json # ★ 执行成功时输出
│ ├── error.json # ★ 自检失败时输出(替代 result.json)
│ ├── logs/ # 执行日志
│ └── workspace/ # 隔离工作区
│
└── ...
维度
验收条件
变更类型
端侧职责
端侧 Subagent 仅执行 privacy,无红线逻辑
新增
云端职责
红线任务全部走云端,端侧不执行红线轻量扫描
新增
路由逻辑
redline→cloud,privacy→local,配置驱动
新增
信任边界
主Agent不校验Subagent产出;Subagent自检后标记状态
新增
告警指纹
端云使用 domain/ 统一算法,指纹一致
新增
告警强制上云
所有告警同步云端;端侧不维护告警库;网络异常时临时缓存重试最多3次
新增
报告上云
所有报告元数据 + 告警数据同步云端
新增
交付物齐备
安装包正常运行,无需额外安装
不变
版本
日期
变更说明
v2.3
2026-07-07
新增:云端大规模执行集群 + 告警统一管理平台
v2.4
2026-07-08
执行侧拆分:端侧黑盒专项(隐私)+ 云端白盒红线专项(唯一执行者);阶段四融合到阶段三(Subagent自检);主Agent信任Subagent;路由决策层正式命名为阶段二并按test_type分流;告警强制上云;domain/ 领域层(端云统一数据契约 + 算法);删除性能测试;新增error.json模型;云端轮询作为阶段三-B实现细节;阶段编号整体顺延