Skip to content

Latest commit

 

History

History
418 lines (362 loc) · 20.6 KB

SPEC.md

File metadata and controls

418 lines (362 loc) · 20.6 KB

✅ 第一阶段 SPEC V0.1(执行侧拆分 · 信任模型 · 告警上云)- 修正版

文档版本:v2.4 编制日期:2026-07-08 架构方案:Electron + FastAPI + PyInstaller 核心原则:端侧黑盒专项(隐私) + 云端白盒专项(红线唯一执行者) + 主Agent信任Subagent + 告警报告强制上云

一、核心架构原则(V0.1 总纲)

原则 说明
执行侧拆分 端侧 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 不变

阶段一:主 Agent 规划与拆解

需求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;② 路由决策记录在日志中 新增

阶段三-A:端侧执行(黑盒专项)

需求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 新增

阶段四:主 Agent 汇聚结果

需求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 ★ 所有报告必须上云:报告元数据 + 告警数据同步至云端 ① 云端可查询历史报告;② 端侧仅展示,不维护告警库 新增

五、数据模型(V0.1 修正版)

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

六、开发分工(4人,2.5~3周,修正版)

开发 主责模块 核心任务 预估工期 与 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 个工作日)。

七、目录结构(V0.1 修正版)

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/         # 隔离工作区
│
└── ...

八、验收标准(V0.1 修正版)

维度 验收条件 变更类型
端侧职责 端侧 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实现细节;阶段编号整体顺延