鉴微 INSIGHT · AI Agent 方向结构文档

基于项目实测（backend.py / insight-replica.html / data.json）梳理，所有接口均已在 2026-11-06 实际运行验证。
项目定位：漏洞管理平台的 AI 助手 —— LLM 只负责"组织语言"，事实全部来自平台结构化数据，每条结论可溯源，缺失数据明确标注"无法判断"。

#一、项目总体架构

┌─────────────────────────────────────────────────────────────┐
│                    insight-replica.html（前端，单文件）        │
│   AgentBridge（Agent 接入层）  ├─ local 模式：LocalActions     │
│                              └─ remote 模式：fetch /agent-api│
└───────────────┬─────────────────────────────────────────────┘
                │ HTTP（同源托管，无 CORS）
┌───────────────▼─────────────────────────────────────────────┐
│                    backend.py（纯标准库后端）                  │
│  ① 静态托管前端      ② 平台数据 CRUD（/api/*，读写 data.json） │
│  ③ Agent 契约接口（/agent-api/*）                              │
│  ④ DeepSeek 调用（OpenAI 兼容协议，纯 urllib）                  │
└───────────────┬─────────────────────────────────────────────┘
                │ HTTPS / chat/completions
┌───────────────▼─────────────────────────────────────────────┐
│         DeepSeek LLM（deepseek-flash，thinking=disabled）     │
│         失败自动降级为后端内置模板生成（generatedBy 标注来源）    │
└─────────────────────────────────────────────────────────────┘

三层降级设计（响应中 generatedBy 字段标明来源，前端据此显示"生成方式"）：

#二、AI Agent 核心设计思想

#2.1 事实与语言分离（防幻觉架构）

LLM 不接触任何"自由发挥"空间：

平台事实采集（确定性代码）──→ facts JSON ──→ LLM（仅组织语言）──→ 摘要/步骤
     ↑                                                          │
     └────── knowledge / intel / assets / software / tickets ────┘

• System Prompt 约束（backend.py:362-383）：
• 功能一："只允许使用【平台事实】中的信息组织语言，不得新增技术结论；事实缺失必须写"平台未采集，无法判断""
• 功能三："只允许使用平台事实中的信息（资产清单、版本情况、责任人、官方修复建议），不得编造版本号或资产"
• temperature=0.2，thinking=disabled（reasoning_tokens=0，省费用且正文稳定）
• max_tokens 上限：摘要 420 / 步骤 560

#2.2 结论可溯源（Citations 机制）

每次 AI 输出都附带 citations（依据清单）与 unknowns（缺失清单）：

置信度规则：资产已纳管 → high/较高；未纳管 → mid/中（资产未纳管，版本信息缺失）。

#2.3 AgentBridge：前端 Agent 动作总线（insight-replica.html:533-596）

统一入口 window.InsightAgentAPI.call(action, payload)，三级路由：

call(action) ─┬─ remote 模式且有映射 → POST /agent-api/<route>   （真实后端）
              ├─ register() 注册的 handler → 自定义接管           （扩展点）
              └─ 兜底 → window.LocalActions[action]()            （本地模拟）

• 模式持久化：localStorage['insight-agent-mode']，演示时切换一次即可
• 事件总线：on('before:action' / 'after:action' / '*')，可插桩监控

#2.4 LUI 任务拆解可视化（Agent 执行过程的透明化）

前端把 Agent 的执行链具象为"步骤逐条点亮"（真实调用工具，非纯动画）：

功能一 JUDGE_STEPS                      功能三 FIX_STEPS
──────────────────────                  ──────────────────────
1. getVuln            读取漏洞上下文      1. getVuln           读取漏洞上下文
2. getVptAttribution  计算 VPT 归因      2. getVptAttribution 计算 VPT 归因
3. searchKnowledge    检索知识库/情报库   3. searchKnowledge   检索知识库与处置记录
4. getDisposalRecords 处置记录时间线      4. getAssetProfile   拉取资产档案与责任人
5. organize           组织语言(溯源)     5. organize          组织语言(逐条溯源)

每步实时显示执行结果（如"100 分（P0）· 特殊规则未命中"、"命中 2 条"、"未纳管"）。

人工在环（Human-in-the-loop）：AI 输出仅供参考 → 人工核对 → 点"采纳"才真正建工单 → 写审计日志。UI 明确标注："AI 生成内容仅供参考，采纳前请人工核对。"

#三、Agent 契约接口（/agent-api/*）

统一响应契约：{ ok: bool, data: {...} }，出错返回 { ok: false, error: "..." }。

#3.1 功能一：漏洞研判摘要 POST /agent-api/judgement（读取类）

请求：{"kind": "ip" | "web", "id": 240}

响应 data 结构（实测值）：

{
  "vuln": {"id","name","level","vpt","type","cve","asset","status"},
  "attribution": {"score": 100.0, "key": "P0", "byRule": false},
  "summary": "【研判摘要】...(≤150字，由 DeepSeek 生成)",
  "citations": [{"label","from","detail"}, ...],      // 2~5 项
  "unknowns": ["平台未采集，无法判断...", ...],
  "confidence": {"level": "high", "text": "较高"},
  "generatedBy": "deepseek" | "template"
}

1. _get_vuln 取漏洞 → _facts 收集：VPT 计算 + 资产 + 软件 + 知识库 + 情报 + 同 CVE 已修复记录
2. 组装 facts JSON → llm_judgement_summary 调 DeepSeek（失败 → _template_judgement 降级）
3. 返回摘要 + 引用 + 缺失 + 置信度

执行链（backend.py handle_judgement，408-458 行）：

VPT 评分算法（calc_vpt，287-320 行，与前端同口径）：

总分 = 资产维度×权重% + 漏洞维度×权重% + 情报维度×权重%
漏洞维度 = 等级分(超危100/高危80/中危50/低危10/信息0) × 权重
P 级映射：>80→P0，>74→P1，>49→P2，>0→P3，else P4
特殊规则优先：如"外网资产+高危→81"直接赋值（byRule=true）
当前配置：资产 0% / 漏洞 100% / 情报 0%（演示配置）

#3.2 功能三：修复建议本地化 POST /agent-api/fix-advice（读取类）

请求：{"kind":"web","id":311}

响应 data 结构（实测）：

{
  "vuln": {"name","level","vpt","type","cve","asset","source"},
  "assets": [{"ip","name","org","owner","biz","from"}],   // 逐条标注 from 溯源
  "managed": false, "versionKnown": false, "versionText": "...",
  "kbFound": false, "kbText": "...",
  "sameClosed": [...],
  "officialFix": "官方修复建议原文",
  "coord": {"owner","coOwner","biz","assetOwner"},        // 协同处置人信息
  "steps": ["修复步骤1", "..."],                          // 3~5条，DeepSeek 生成
  "confidence": "中（该资产未纳管...）", "confLevel": "mid",
  "unknowns": ["平台资产台账中未收录...无法判断..."],
  "generatedBy": "deepseek"
}

实测 DeepSeek 输出严格遵循约束——版本缺失时输出"具体版本号需先确认，无法判断"，未编造任何版本号。

#3.3 功能三（状态变更）：采纳并建工单 POST /agent-api/fix-advice/adopt

请求：{"kind":"web","id":311} → 响应：{"ok":true,"data":{"ticketId":"T-20261106-7898"}}

执行链：生成工单号 T-YYYYMMDD-xxxx → 写入 tickets → 写审计日志（操作类型"修复建议助手"）。

#3.4 通用：由漏洞建工单 POST /agent-api/tickets

请求：{"vulnId":240,"kind":"ip","from":"detail"} → 响应：{"ok":true,"data":{"ticketId":"T-20261106-7253"}}

kind 可省（自动在 ip/web 两个集合中查找）；from 决定审计日志的操作来源标注。

#四、平台数据层（Agent 的事实源）

存储：data.json（零依赖，首次启动自动写入种子数据），线程锁保护读写。

#4.1 数据集合（REST：/api/<collection>，支持 ?q= 全文检索）

#4.2 漏洞对象关键字段（Agent 取数用）

事实八项：name / level / vpt / type / cve / asset / status / owner(+coOwner/biz)
情报四项：exp / poc / patch / wild          ← 全空时触发"评分依据需核实"判定
处置三文：desc（描述）/ danger（危害）/ fix（官方修复）← 240 等 5 条演示漏洞定制

#4.3 CRUD 完整可用（已实测）

GET    /api/<c>            列表（支持 ?q= 过滤）
GET    /api/<c>/<id>       单条
POST   /api/<c>            新建（漏洞自动建 ID / 工单自动补默认字段）
PUT    /api/<c>/<id>       整条更新（漏洞白名单 VULN_EDITABLE 26 字段）
PATCH  /api/<c>/<id>       局部更新（同 PUT）
DELETE /api/<c>/<id>       删除
GET    /api/health         健康检查（返回 LLM 状态）

所有写操作自动落审计日志（时间/用户/角色/IP/描述/结果）。

#五、前端 AI 功能落点（insight-replica.html，~2600 行单文件）

关键 UX 约定：citations 可点击弹出溯源 toast；unknowns 用"无法判断"高亮条；生成方式 attends 实时显示 DeepSeek 真实分析 / 模板降级 / 本地模拟。

#六、运行与验证记录（2026-11-06 实测全部通过）

启动：python backend.py      →  http://127.0.0.1:8000/insight-replica.html
依赖：零第三方库（Python 3.15.2 标准库）

#七、AI Agent 能力总结与演进方向

#7.1 当前已具备的 Agent 特征

#7.2 与"标准 AI Agent"的差距（当前形态 = 确定性工作流 Agent）

• 无自主规划：步骤链（JUDGE_STEPS/FIX_STEPS）是写死的固定顺序，非 LLM 动态决策下一步调什么工具
• 无记忆/多轮：每次调用独立，不保留会话上下文
• 单 LLM、单任务：一次调用一个功能点，无复杂任务分解（如"把全部 P0 排个处置优先级"这类跨实体任务做不到）
• 鉴权为演示级：读操作开放、写操作由环境变量 ADMIN_TOKEN 口令保护（请求头 X-Admin-Token），暂无用户体系与细粒度权限

#7.3 建议演进路线（按优先级）

1. 已完成：API Key 移出源码，改为「在线配置 > 环境变量 > 源码默认」三级优先；写操作由管理口令保护
2. 短期：接入正式鉴权（JWT + 操作白名单 + 角色体系），区分研究员 / 处置人 / 管理员
3. 中期：引入标准 Tool-Calling（OpenAI function calling）：把 _facts 拆分注册为独立 tools，由 LLM 决定调用顺序，从"固定管线"升级为"自主规划 Agent"
4. 中期：加会话记忆（工单处理上下文、用户偏好），支持多轮编排
5. 远期：跨实体长任务（批量研判、自动排期）、RAG 知识库检索、处置智能体与检测器联动闭环
6. 规范：data.json → SQLite/MySQL（现线程锁已在，切存储成本低）；补 pytest 自动化回归

#八、文件清单

#九、线上部署与在线大模型配置

#9.1 部署形态（Vercel 同源）

访客浏览器 ──HTTPS──▶ 自定义域名（Vercel）
                          │
    ┌─────────────────────┴──────────────────────┐
    │ /                  → index.html（静态封面页）│
    │ /insight-replica   → api/index.py（函数）   │
    │ /api/*、/agent-api/* → 同一函数（WSGI 包装） │
    └────────────────────────────────────────────┘

api/index.py 是薄适配层：用 _FakeTransport 模拟 BaseHTTPRequestHandler 的 I/O，与 backend.Handler 动态组合，业务逻辑零改动即可运行在 Serverless 环境。

#9.2 大模型在线配置（面向非技术使用者）

「配置中心 → 大模型配置」页允许分析师直接填写接入地址 / API Key / 模型名，无需接触代码：

生效优先级：本页保存的运行时配置  >  环境变量（DEEPSEEK_API_KEY 等）  >  源码默认值

• GET /api/llm-config：返回脱敏配置（Key 仅显示尾号）与当前生效来源
• PUT /api/llm-config：保存配置，立即替换服务端默认值
• POST /api/llm-config/test：用页面输入发 16 tokens 最小请求，返回延迟与错误原因
• 「恢复服务端默认 Key」：清除运行时覆盖，回落到环境变量配置

#9.3 鉴权与可观测