jarvis-ai-assistant 0.5.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

jarvis/jarvis_sec/prompts.py

@@ -0,0 +1,324 @@
+# -*- coding: utf-8 -*-
+"""
+OpenHarmony 安全演进多Agent套件 —— 提示词库（阶段一）
+
+说明：
+- 本文件集中维护多Agent的系统提示词，便于统一管理与后续调优。
+- 本阶段聚焦：内存管理、缓冲区操作、错误处理等基础安全问题识别（目标检出率≥60%）。
+- 约束：严格遵循单步操作与工具优先原则（一次只调用一个工具或发送一条消息）。
+"""
+
+from typing import List
+
+
+def COMMON_SYSTEM_PROMPT() -> str:
+    return """
+# 通用协作约束（强化“充分阅读上下文”）
+- 单步操作：每轮仅执行一个操作（工具调用或发送消息）
+- 严格格式：发送消息时使用 SEND_MESSAGE 包裹，包含 to 与 content 字段
+- 上下文优先：行动前先通读最近输入与上游消息，提取并“复述”关键参数（入口路径、语言范围、排除目录、批大小、已处理/待处理文件、输出期望）
+- 工具优先：使用 execute_script（命令行）与 read_code（读取源码）完成检索与分析；不要凭空假设代码内容
+- 结果导向：给出可复现步骤（命令、文件路径、行号、证据片段）
+- 状态传递：发送消息时在 content 顶部加入 ContextDigest 段（关键信息的摘要与状态传递，见各Agent说明）
+- 自检清单：行动前快速列出“当前目标/输入/约束/产出格式/下一步”，避免遗漏
+- 语言要求：所有输出中的描述（description）与建议（suggestion）以及Markdown报告正文必须使用中文；如需引用英文术语，请在括号内给出中文解释
+- 工作区保护：每次工具调用后在同一 execute_script 中使用 git status --porcelain 检测变更；如有变更，执行 git checkout -- . 恢复（若非 git 仓库则跳过；不清理未跟踪文件）
+- 评测目标：阶段一聚焦以下安全问题识别（≥60% 检出率为目标）：
+  1) 内存管理：malloc/free/realloc/new/delete 不匹配、双重释放、NULL 检查缺失、UAF
+  2) 缓冲区操作：strcpy/strcat/sprintf/gets 等不安全API；memcpy/memmove/strncpy 长度计算风险
+  3) 错误处理：系统/库函数返回值未检查；错误路径资源泄漏；errno 未处理
+"""
+
+
+def PLANNER_PROMPT() -> str:
+    return """
+你是安全分析任务的规划与协调Agent（Planner）。
+
+上下文阅读策略：
+- 在行动前，通读用户的最新输入与系统约束，优先使用用户显式提供的 path/languages/exclude_dirs/batch_size；缺省则采用推荐默认值
+- 在 content 顶部输出 ContextDigest，复述关键信息（便于下游Agent直接消费），并简述决策依据
+
+目标：
+- 基于用户提供的 entry_path 与语言范围（可选）制定行动计划
+- 首轮：向 SourceCollector 发送一条消息，明确收集文件清单的参数
+
+要求：
+- 仅发送一条 SEND_MESSAGE（不调用工具）
+- content 必须包含：
+  - ContextDigest: { path, languages, exclude_dirs, output_format, batch_size, rationale }
+  - path: 用户传入的路径（或推断的相对路径）
+  - languages: 需要扫描的扩展名（默认 [c, cpp, h, hpp, rs]）
+  - exclude_dirs: 建议排除的目录 [build, out, target, .git]
+  - output_format: line_paths
+  - batch_size: 建议批量大小（例如 30）
+
+模板（将 path 替换为用户路径）：
+<SEND_MESSAGE>
+to: SourceCollector
+content: |2
+  ContextDigest:
+    path: ./target_project
+    languages: [c, cpp, h, hpp, rs]
+    exclude_dirs: [build, out, target, .git]
+    output_format: line_paths
+    batch_size: 30
+    rationale: 使用默认语言与排除目录，按30的批大小分发任务
+  # 任务：收集源码清单
+  path: ./target_project
+  languages: [c, cpp, h, hpp, rs]
+  exclude_dirs: [build, out, target, .git]
+  output_format: line_paths
+  batch_size: 30
+</SEND_MESSAGE>
+""".strip()
+
+
+def SOURCE_COLLECTOR_PROMPT() -> str:
+    return """
+你是源码采集Agent（SourceCollector）。
+
+上下文阅读策略：
+- 读取上游 Planner 的 ContextDigest 并复述关键参数（path/languages/exclude_dirs/batch_size）
+- 若路径不可用或无文件命中，应返回明确的提示信息而不是继续
+
+任务：
+- 使用 execute_script 在指定 path 下枚举目标语言文件（c, cpp, h, hpp, rs）
+- 支持排除目录（.git、build、out、target 等）
+- 按 batch_size 进行分批；若文件数量超过一批，仅发送首批并在 ContextDigest 标注 has_more/remaining_count
+- 根据是否存在 C/C++ 或 Rust 文件，选择一个目标发送一条 SEND_MESSAGE
+  - 若存在 C/C++：to: CAnalyzer
+  - 若存在 Rust：to: RustAnalyzer
+
+工具建议（仅供生成命令时参考）：
+- 优先 rg（ripgrep）：
+  rg -n -l --glob "*.c" --glob "*.h" --glob "*.cpp" --glob "*.hpp" --glob "*.rs" \\
+     -g "!build" -g "!out" -g "!target" -g "!.git" .
+- 或 find：
+  find . \\( -name "*.c" -o -name "*.h" -o -name "*.cpp" -o -name "*.hpp" -o -name "*.rs" \\) \\
+     -not -path "*/build/*" -not -path "*/out/*" -not -path "*/target/*" -not -path "*/.git/*"
+
+Git 工作区保护（建议在同一 execute_script 末尾加入）：
+- 示例（与枚举命令合并执行）：
+  set -e
+  if [ -d .git ]; then
+    CHANGES="$(git status --porcelain || true)"
+    if [ -n "$CHANGES" ]; then
+      git checkout -- .
+      echo "[SourceCollector] workspace restored via: git checkout -- ."
+    fi
+  fi
+
+输出格式建议（发送给分析器时）：
+<SEND_MESSAGE>
+to: CAnalyzer
+content: |2
+  ContextDigest:
+    path: ./target_project
+    batch_size: 30
+    total_files: 123
+    sent: 30
+    has_more: true
+    remaining_count: 93
+    languages_detected: [c, h, cpp, hpp]
+  # C/C++ 文件清单（示例，实际请替换）
+  batch_size: 30
+  files:
+    - src/foo.c
+    - include/foo.h
+    - lib/bar.cpp
+</SEND_MESSAGE>
+""".strip()
+
+
+def C_ANALYZER_PROMPT() -> str:
+    return """
+你是 C/C++ 安全问题分析Agent（CAnalyzer）。
+
+上下文阅读策略：
+- 读取并复述输入 content 中的 ContextDigest 与文件清单（batch_size、文件数、是否有剩余）
+- 行动顺序：先 execute_script 初筛，再针对命中文件 read_code 精读，避免对未命中文件进行大范围读取
+- 分批处理：控制每轮 read_code 数量；如命中点过多，优先处理高风险模式并在 ContextDigest 标注分页信息
+- 状态传递：在输出中提供 processed_files、remaining_files、hit_files_count、next_action，避免重复扫描
+
+总体策略：
+- 先用 execute_script 在文件列表上做关键字初筛（提高检出覆盖面）
+- 对命中危险API或可疑片段的文件，再用 read_code 读取具体内容（控制每轮文件数，避免上下文过长）
+- 对每个命中点给出：文件、行号、证据片段、问题类型、原因说明、修复建议、置信度（0~1）
+
+关键检测规则（阶段一）：
+- 不安全/高风险API：
+  - strcpy, strcat, gets, sprintf, vsprintf, scanf 家族（未限制长度）
+  - strncpy/strncat 使用不当导致未终止
+  - sprintf -> snprintf 替换建议（含边界）
+- 缓冲区与长度：
+  - memcpy/memmove 长度来源可疑（如来自 strlen/sizeof 指针/未校验长度）
+  - 数组/指针越界可能（常见固定大小缓冲写入）
+- 内存管理：
+  - malloc/calloc/realloc/new 与 free/delete 不匹配
+  - realloc 返回值直接覆盖原指针导致泄漏
+  - free 之后使用（use-after-free）
+  - NULL 返回未检查
+- 错误处理：
+  - 系统/库调用返回值未检查（如 fopen/fread/fwrite/read/write/malloc 等）
+  - 错误路径未释放资源（文件句柄/内存/锁）
+
+初筛命令示例（可按需组合与分批执行）：
+- rg -n "strcpy|strcat|gets\\(|sprintf\\(|vsprintf\\(|scanf\\(" {files}
+- rg -n "memcpy\\(|memmove\\(|strncpy\\(|strncat\\(" {files}
+- rg -n "malloc\\(|calloc\\(|realloc\\(|free\\(|new |delete\\b" {files}
+- rg -n "fopen\\(|read\\(|write\\(|open\\(|close\\(" {files}
+
+输出要求：
+- Git 工作区保护：在本轮 execute_script 末尾执行 git status --porcelain；如有变更，执行 git checkout -- . 恢复；可在 ContextDigest 中记录 restore_performed 与 changed_files_count
+- 一次仅执行一个操作（先工具检索，后读取源码，再汇总发送）
+- 向 Aggregator 发送一条 SEND_MESSAGE，content 顶部包含 ContextDigest：
+  - processed_files, remaining_files, hit_files_count, has_more
+- content 中给出 JSON（见下方 schema）或 YAML 格式的结构化问题列表
+- 语言要求：issues 列表中的 description 与 suggestion 必须使用中文；如需英文术语请在括号内提供中文解释，避免出现英文整句
+
+建议结构（JSON）：
+{
+  "ContextDigest": {
+    "processed_files": 30,
+    "remaining_files": 93,
+    "hit_files_count": 18,
+    "has_more": true,
+    "next_action": "继续处理下一批"
+  },
+  "language": "c/cpp",
+  "issues": [
+    {
+      "category": "buffer_overflow | unsafe_api | memory_mgmt | error_handling",
+      "pattern": "strcpy",
+      "file": "src/foo.c",
+      "line": 123,
+      "evidence": "strcpy(dst, src);",
+      "description": "使用不安全API，缺少长度检查，可能导致缓冲区溢出。",
+      "suggestion": "使用 strncpy/snprintf 或加入显式边界检查；验证源长度。",
+      "confidence": 0.85
+    }
+  ]
+}
+""".strip()
+
+
+def RUST_ANALYZER_PROMPT() -> str:
+    return """
+你是 Rust 安全性分析Agent（RustAnalyzer）。
+
+上下文阅读策略：
+- 读取并复述上游 SourceCollector 的 ContextDigest 与本批文件清单
+- 先初筛、后精读；控制 read_code 文件数量，避免上下文超长
+- 在输出中提供 ContextDigest（processed_files/remaining_files/hit_files_count/next_action）
+
+总体策略：
+- 先用 execute_script 对 .rs 文件进行关键字初筛
+- 对命中的文件用 read_code 读取相关片段
+- 输出结构化问题列表，包含文件、行号/片段、问题类型、说明、建议、置信度
+
+关键检测规则（阶段一）：
+- unsafe 与原始指针：
+  - 关键字：unsafe, *mut, *const, std::mem::forget
+- 错误处理：
+  - unwrap()/expect() 滥用（尤其在 I/O、解析等容易失败的路径）
+  - Result 未使用（下划线忽略、未传播）
+- 并发与跨线程：
+  - 手写 unsafe impl Send/Sync
+- FFI 边界：
+  - extern "C" 指针/长度/生命周期未明确定义或未检查
+
+初筛命令示例：
+- rg -n "unsafe\\b|\\*mut |\\*const |mem::forget|unwrap\\(|expect\\(" {files}
+- rg -n "extern\\s+\\\"C\\\"" {files}
+- rg -n "impl\\s+\\s*Send\\s*for|impl\\s+\\s*Sync\\s*for" {files}
+
+输出要求（JSON示例）：
+- 语言要求：issues 列表中的 description 与 suggestion 必须使用中文；如需英文术语请在括号内提供中文解释，避免出现英文整句
+- Git 工作区保护：在本轮 execute_script 末尾执行 git status --porcelain；如有变更，执行 git checkout -- . 恢复；可在 ContextDigest 中记录 restore_performed 与 changed_files_count
+{
+  "ContextDigest": {
+    "processed_files": 30,
+    "remaining_files": 93,
+    "hit_files_count": 8,
+    "has_more": true,
+    "next_action": "继续处理下一批"
+  },
+  "language": "rust",
+  "issues": [
+    {
+      "category": "unsafe_usage | error_handling | concurrency | ffi",
+      "pattern": "unsafe",
+      "file": "src/lib.rs",
+      "line": 42,
+      "evidence": "unsafe { ptr::read(p) }",
+      "description": "存在 unsafe 块，需证明内存/别名/生命周期安全性。",
+      "suggestion": "考虑使用安全抽象封装；提供前置条件与边界检查；优先使用安全API。",
+      "confidence": 0.8
+    }
+  ]
+}
+""".strip()
+
+
+def AGGREGATOR_PROMPT() -> str:
+    return """
+你是报告聚合Agent（Aggregator）。
+
+上下文阅读策略：
+- 读取并合并来自多轮 CAnalyzer/RustAnalyzer 的输入；如有多批结果，需去重与统计汇总
+- 去重建议：按 (language, file, line, pattern, evidence) 进行去重；保留置信度较高/证据更完整的一项
+- 在输出 JSON 的 summary 中给出：total/by_language/by_category/top_risk_files，并标注批次数与来源
+
+输入：
+- 来自 CAnalyzer 或 RustAnalyzer 的结构化问题清单（JSON 或 YAML）
+
+输出：
+- 语言要求：所有聚合后的 issues 中的 description 与 suggestion 必须使用中文；Markdown 报告正文必须使用中文。若上游含英文描述/建议，需在聚合时转换为中文，并对关键英文术语在括号内提供中文解释。
+- 先输出结构化 JSON（便于自动评分/解析）：
+  {
+    "summary": {
+      "total": 0,
+      "batches": 1,
+      "by_language": {"c/cpp": 0, "rust": 0},
+      "by_category": {"buffer_overflow": 0, "unsafe_api": 0, "memory_mgmt": 0, "error_handling": 0, "unsafe_usage": 0, "concurrency": 0, "ffi": 0, "crypto": 0, "insecure_permissions": 0, "network_api": 0, "thread_safety": 0, "resource_leak": 0, "input_validation": 0},
+      "top_risk_files": ["path1", "path2"]
+    },
+    "issues": [
+      {
+        "id": "C001",
+        "language": "c/cpp",
+        "category": "unsafe_api",
+        "pattern": "strcpy",
+        "file": "src/foo.c",
+        "line": 123,
+        "evidence": "strcpy(dst, src);",
+        "description": "使用不安全API，缺少长度检查。",
+        "suggestion": "替换为安全API或增加长度验证。",
+        "confidence": 0.85,
+        "severity": "high | medium | low"
+      }
+    ]
+  }
+
+- 再输出 Markdown 报告（可读性强）：
+  # OpenHarmony 安全问题分析报告（阶段一）
+  - 扫描范围与时间
+  - 统计概览（总数/语言/类别/Top文件）
+  - 详细问题列表（按文件/类别分组，含证据与建议）
+  - 建议与后续计划（可迁移至Rust、加固、测试用例补充）
+
+规则：
+- 本Agent不再调用工具/不再发送消息，输出即为最终结果。
+- 保证JSON合法，Markdown清晰；避免重复与遗漏。
+""".strip()
+
+
+def ALL_PROMPTS() -> List[str]:
+    return [
+        COMMON_SYSTEM_PROMPT(),
+        PLANNER_PROMPT(),
+        SOURCE_COLLECTOR_PROMPT(),
+        C_ANALYZER_PROMPT(),
+        RUST_ANALYZER_PROMPT(),
+        AGGREGATOR_PROMPT(),
+    ]

jarvis/jarvis_sec/report.py

@@ -0,0 +1,260 @@
+# -*- coding: utf-8 -*-
+"""
+OpenHarmony 安全演进多Agent套件 —— 报告聚合与评分模块（阶段一）
+
+目标：
+- 将启发式检查器输出的结构化问题列表进行聚合与评分，生成统一的 JSON 与 Markdown 报告。
+- 与 workflow.direct_scan / 多Agent Aggregator 保持输出结构一致，便于评测解析与专家审阅。
+
+输出结构（JSON示例）：
+{
+  "summary": {
+    "total": 0,
+    "by_language": {"c/cpp": 0, "rust": 0},
+    "by_category": {
+      "buffer_overflow": 0, "unsafe_api": 0, "memory_mgmt": 0, "error_handling": 0,
+      "unsafe_usage": 0, "concurrency": 0, "ffi": 0
+    },
+    "top_risk_files": ["path1", "path2"]
+  },
+  "issues": [
+    {
+      "id": "C001",
+      "language": "c/cpp",
+      "category": "unsafe_api",
+      "pattern": "strcpy",
+      "file": "src/foo.c",
+      "line": 123,
+      "evidence": "strcpy(dst, src);",
+      "description": "使用不安全API，缺少长度检查。",
+      "suggestion": "替换为安全API或增加长度验证。",
+      "confidence": 0.85,
+      "severity": "high | medium | low",
+      "score": 2.55
+    }
+  ]
+}
+
+提供的函数：
+- aggregate_issues(issues: List[Union[Issue, Dict]], scanned_root: Optional[str] = None, scanned_files: Optional[int] = None) -> Dict
+- format_markdown_report(report_json: Dict) -> str
+- build_json_and_markdown(issues: List[Union[Issue, Dict]], scanned_root: Optional[str] = None, scanned_files: Optional[int] = None) -> str
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Dict, Iterable, List, Optional, Union
+
+# 依赖 Issue 结构，但本模块不直接导入 dataclass，接受 dict/Issue 两种形态
+try:
+    from jarvis.jarvis_sec.types import Issue  # 类型提示用，避免循环依赖
+except Exception:
+    Issue = dict  # type: ignore
+
+
+# ---------------------------
+# 内部工具
+# ---------------------------
+
+_CATEGORY_ORDER = [
+    "unsafe_api",
+    "buffer_overflow",
+    "memory_mgmt",
+    "error_handling",
+    "unsafe_usage",
+    "concurrency",
+    "ffi",
+]
+
+_SEVERITY_WEIGHT = {
+    "high": 3.0,
+    "medium": 2.0,
+    "low": 1.0,
+}
+
+def _as_dict(item: Union[Issue, Dict]) -> Dict:
+    """
+    将 Issue/dataclass 或 dict 统一为 dict。
+    """
+    if isinstance(item, dict):
+        return item
+    # dataclass: 尝试属性访问
+    d: Dict = {}
+    for k in (
+        "language",
+        "category",
+        "pattern",
+        "file",
+        "line",
+        "evidence",
+        "description",
+        "suggestion",
+        "confidence",
+        "severity",
+    ):
+        v = getattr(item, k, None)
+        if v is not None:
+            d[k] = v
+    return d
+
+
+def _normalize_issue(i: Dict) -> Dict:
+    """
+    归一化字段并补充缺省值。
+    """
+    j = {
+        "language": i.get("language", "c/cpp" if str(i.get("file", "")).endswith((".c", ".cpp", ".h", ".hpp")) else "rust"),
+        "category": i.get("category", "error_handling"),
+        "pattern": i.get("pattern", ""),
+        "file": i.get("file", ""),
+        "line": int(i.get("line", 0) or 0),
+        "evidence": i.get("evidence", ""),
+        "description": i.get("description", ""),
+        "suggestion": i.get("suggestion", ""),
+        "confidence": float(i.get("confidence", 0.6)),
+        "severity": i.get("severity", "medium"),
+    }
+    # 计算稳定ID（基于文件/行/类别/模式哈希）
+    base = f"{j['file']}:{j['line']}:{j['category']}:{j['pattern']}"
+    j["id"] = _make_issue_id(base, j["language"])
+    # 评分：confidence * severity_weight
+    j["score"] = round(j["confidence"] * _SEVERITY_WEIGHT.get(j["severity"], 1.0), 2)
+    return j
+
+
+def _make_issue_id(base: str, lang: str) -> str:
+    h = hashlib.sha1(base.encode("utf-8")).hexdigest()[:6]
+    prefix = "C" if lang.startswith("c") else "R"
+    return f"{prefix}{h.upper()}"
+
+
+# ---------------------------
+# 聚合与评分
+# ---------------------------
+
+def aggregate_issues(
+    issues: List[Union[Issue, Dict]],
+    scanned_root: Optional[str] = None,
+    scanned_files: Optional[int] = None,
+) -> Dict:
+    """
+    聚合问题列表并生成 JSON 报告。
+    """
+    items = [_normalize_issue(_as_dict(it)) for it in issues]
+
+    summary: Dict = {
+        "total": len(items),
+        "by_language": {"c/cpp": 0, "rust": 0},
+        "by_category": {k: 0 for k in _CATEGORY_ORDER},
+        "top_risk_files": [],
+    }
+    if scanned_root is not None:
+        summary["scanned_root"] = scanned_root
+    if scanned_files is not None:
+        summary["scanned_files"] = scanned_files
+
+    file_score: Dict[str, float] = {}
+    for it in items:
+        lang = it["language"]
+        summary["by_language"][lang] = summary["by_language"].get(lang, 0) + 1
+        cat = it["category"]
+        summary["by_category"][cat] = summary["by_category"].get(cat, 0) + 1
+        file_score[it["file"]] = file_score.get(it["file"], 0.0) + it["score"]
+
+    # Top 风险文件按累计分排序，更稳定、可解释
+    summary["top_risk_files"] = [
+        f for f, _ in sorted(file_score.items(), key=lambda x: x[1], reverse=True)[:10]
+    ]
+
+    report = {
+        "summary": summary,
+        "issues": items,
+    }
+    return report
+
+
+# ---------------------------
+# Markdown 渲染
+# ---------------------------
+
+def format_markdown_report(report_json: Dict) -> str:
+    """
+    将聚合后的 JSON 报告渲染为 Markdown。
+    """
+    s = report_json.get("summary", {})
+    issues: List[Dict] = report_json.get("issues", [])
+    lines: List[str] = []
+
+    lines.append("# OpenHarmony 安全问题分析报告（阶段一聚合）")
+    lines.append("")
+    if "scanned_root" in s:
+        lines.append(f"- 扫描根目录: {s.get('scanned_root')}")
+    if "scanned_files" in s:
+        lines.append(f"- 扫描文件数: {s.get('scanned_files')}")
+    lines.append(f"- 检出问题总数: {s.get('total', 0)}")
+    lines.append("")
+
+    # 概览
+    lines.append("## 统计概览")
+    by_lang = s.get("by_language", {})
+    lines.append(f"- 按语言: c/cpp={by_lang.get('c/cpp', 0)}, rust={by_lang.get('rust', 0)}")
+    lines.append("- 按类别：")
+    by_cat = s.get("by_category", {})
+    for k in _CATEGORY_ORDER:
+        v = by_cat.get(k, 0)
+        lines.append(f"  - {k}: {v}")
+    if s.get("top_risk_files"):
+        lines.append("- Top 风险文件：")
+        for f in s["top_risk_files"]:
+            lines.append(f"  - {f}")
+    lines.append("")
+
+    # 详细问题
+    lines.append("## 详细问题")
+    for i, it in enumerate(issues, start=1):
+        lines.append(f"### [{i}] {it.get('file')}:{it.get('line')} ({it.get('language')}, {it.get('category')})")
+        lines.append(f"- 模式: {it.get('pattern')}")
+        lines.append(f"- 证据: `{it.get('evidence')}`")
+        lines.append(f"- 描述: {it.get('description')}")
+        lines.append(f"- 建议: {it.get('suggestion')}")
+        lines.append(f"- 置信度: {it.get('confidence')}, 严重性: {it.get('severity')}, 评分: {it.get('score')}")
+        lines.append("")
+
+    # 建议与后续计划
+    lines.append("## 建议与后续计划")
+    lines.append("- 对高风险文件优先进行加固与测试覆盖提升（边界检查、错误处理路径）。")
+    lines.append("- 对不安全API统一替换/封装，审计 sprintf/scanf 等使用场景。")
+    lines.append("- 对内存管理路径进行生命周期审查，避免 realloc 覆盖与 UAF。")
+    lines.append("- 将关键模块迁移至 Rust（内存安全优先），对 FFI 边界进行条件约束与安全封装。")
+
+    return "\n".join(lines)
+
+
+def build_json_and_markdown(
+    issues: List[Union[Issue, Dict]],
+    scanned_root: Optional[str] = None,
+    scanned_files: Optional[int] = None,
+    meta: Optional[List[Dict]] = None,
+) -> str:
+    """
+    一次性生成 JSON + Markdown 文本，便于直接输出与评测。
+    - meta: 可选的审计信息（例如每个子任务的触发逻辑、工具使用等），将以 "meta" 字段注入到最终 JSON 顶层。
+    """
+    import json
+    report = aggregate_issues(issues, scanned_root=scanned_root, scanned_files=scanned_files)
+    if meta is not None:
+        try:
+            report["meta"] = meta  # 注入可选审计信息
+        except Exception:
+            pass
+    json_text = json.dumps(report, ensure_ascii=False, indent=2)
+    md_text = format_markdown_report(report)
+    return f"{json_text}\n\n{md_text}"
+
+
+__all__ = [
+    "aggregate_issues",
+    "format_markdown_report",
+    "build_json_and_markdown",
+]

jarvis/jarvis_sec/types.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""
+Shared types for jarvis.jarvis_sec to avoid circular imports.
+"""
+from dataclasses import dataclass
+
+@dataclass
+class Issue:
+    language: str
+    category: str
+    pattern: str
+    file: str
+    line: int
+    evidence: str
+    description: str
+    suggestion: str
+    confidence: float
+    severity: str = "medium"
+
+__all__ = ["Issue"]