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

jarvis/__init__.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 """Jarvis AI Assistant"""
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"

jarvis/jarvis_agent/__init__.py

@@ -25,6 +25,7 @@ from jarvis.jarvis_agent.tool_executor import execute_tool_call
 from jarvis.jarvis_agent.memory_manager import MemoryManager
 from jarvis.jarvis_memory_organizer.memory_organizer import MemoryOrganizer
 from jarvis.jarvis_agent.task_analyzer import TaskAnalyzer
+from jarvis.jarvis_agent.task_planner import TaskPlanner
 from jarvis.jarvis_agent.file_methodology_manager import FileMethodologyManager
 from jarvis.jarvis_agent.prompts import (
     DEFAULT_SUMMARY_PROMPT,
@@ -75,8 +76,7 @@ from jarvis.jarvis_utils.config import (
     is_use_methodology,
     get_tool_filter_threshold,
     get_after_tool_call_cb_dirs,
-
-
+    get_plan_max_depth,
 )
 from jarvis.jarvis_utils.embedding import get_context_token_count
 from jarvis.jarvis_utils.globals import (
@@ -285,6 +285,21 @@ class Agent:
         """获取工具使用提示"""
         return build_action_prompt(self.output_handler)  # type: ignore
 
+    def __new__(cls, *args, **kwargs):
+        if kwargs.get("agent_type") == "code":
+            try:
+                from jarvis.jarvis_code_agent.code_agent import CodeAgent
+            except ImportError as e:
+                raise RuntimeError(
+                    "CodeAgent could not be imported. Please ensure jarvis_code_agent is installed correctly."
+                ) from e
+
+            # 移除 agent_type 避免无限循环，并传递所有其他参数
+            kwargs.pop("agent_type", None)
+            return CodeAgent(**kwargs)
+        else:
+            return super().__new__(cls)
+
     def __init__(
         self,
         system_prompt: str,
@@ -306,6 +321,10 @@ class Agent:
         confirm_callback: Optional[Callable[[str, bool], bool]] = None,
         non_interactive: Optional[bool] = None,
         in_multi_agent: Optional[bool] = None,
+        plan: bool = False,
+        plan_max_depth: Optional[int] = None,
+        plan_depth: int = 0,
+        agent_type: str = "normal",
         **kwargs,
     ):
         """初始化Jarvis Agent实例
@@ -325,6 +344,9 @@ class Agent:
             force_save_memory: 是否强制保存记忆
             confirm_callback: 用户确认回调函数，签名为 (tip: str, default: bool) -> bool；默认使用CLI的user_confirm
             non_interactive: 是否以非交互模式运行（优先级最高，覆盖环境变量与配置）
+            plan: 是否启用任务规划与子任务拆分（默认 False；启用后在进入主循环前评估是否需要将任务拆分为 <SUB_TASK> 列表，逐一由子Agent执行并汇总结果）
+            plan_max_depth: 任务规划的最大层数（默认3，可通过配置 JARVIS_PLAN_MAX_DEPTH 或入参覆盖）
+            plan_depth: 当前规划层数（内部用于递归控制，子Agent会在父基础上+1）
         """
         # 基础属性初始化（仅根据入参设置原始值；实际生效的默认回退在 _init_config 中统一解析）
         # 标识与描述
@@ -348,6 +370,18 @@ class Agent:
         self.non_interactive = non_interactive
         # 多智能体运行标志：用于控制非交互模式下的自动完成行为
         self.in_multi_agent = bool(in_multi_agent)
+        self.plan = bool(plan)
+        # 规划深度与上限
+        try:
+            self.plan_max_depth = (
+                int(plan_max_depth) if plan_max_depth is not None else int(get_plan_max_depth())
+            )
+        except Exception:
+            self.plan_max_depth = 2
+        try:
+            self.plan_depth = int(plan_depth)
+        except Exception:
+            self.plan_depth = 0
         # 运行时状态
         self.first = True
         self.run_input_handlers_next_turn = False
@@ -429,6 +463,8 @@ class Agent:
         self.task_analyzer = TaskAnalyzer(self)
         self.file_methodology_manager = FileMethodologyManager(self)
         self.prompt_manager = PromptManager(self)
+        # 任务规划器：封装规划与子任务调度逻辑
+        self.task_planner = TaskPlanner(self, plan_depth=self.plan_depth, plan_max_depth=self.plan_max_depth)
 
         # 设置系统提示词
         self._setup_system_prompt()
@@ -801,9 +837,14 @@ class Agent:
         try:
             if not self.model:
                 raise RuntimeError("Model not initialized")
-            summary = self.model.chat_until_success(
-                self.session.prompt + "\n" + SUMMARY_REQUEST_PROMPT
-            )  # type: ignore
+            # 优先使用外部传入的 summary_prompt；如为空则回退到默认的会话摘要请求
+            safe_summary_prompt = self.summary_prompt or ""
+            if isinstance(safe_summary_prompt, str) and safe_summary_prompt.strip() != "":
+                prompt_to_use = safe_summary_prompt
+            else:
+                prompt_to_use = self.session.prompt + "\n" + SUMMARY_REQUEST_PROMPT
+
+            summary = self.model.chat_until_success(prompt_to_use)  # type: ignore
             # 防御: 可能返回空响应(None或空字符串)，统一为空字符串并告警
             if not summary:
                 try:
@@ -1057,6 +1098,13 @@ class Agent:
                 )
             except Exception:
                 pass
+            # 如启用规划模式，先判断是否需要拆分并调度子任务
+            if self.plan:
+                try:
+                    self._maybe_plan_and_dispatch(self.session.prompt)
+                except Exception:
+                    # 防御式处理，规划失败不影响主流程
+                    pass
             return self._main_loop()
         except Exception as e:
             PrettyOutput.print(f"任务失败: {str(e)}", OutputType.ERROR)
@@ -1164,6 +1212,55 @@ class Agent:
         temp_model.set_system_prompt(system_prompt)
         return temp_model
 
+    def _build_child_agent_params(self, name: str, description: str) -> Dict[str, Any]:
+        """构建子Agent参数，尽量继承父Agent配置，并确保子Agent非交互自动完成。"""
+        use_tools_param: Optional[List[str]] = None
+        try:
+            tr = self.get_tool_registry()
+            if isinstance(tr, ToolRegistry):
+                selected_tools = tr.get_all_tools()
+                use_tools_param = [t["name"] for t in selected_tools]
+        except Exception:
+            use_tools_param = None
+
+        return {
+            "system_prompt": origin_agent_system_prompt,
+            "name": name,
+            "description": description,
+            "model_group": self.model_group,
+            "summary_prompt": self.summary_prompt,
+            "auto_complete": True,
+            "use_tools": use_tools_param,
+            "execute_tool_confirm": self.execute_tool_confirm,
+            "need_summary": self.need_summary,
+            "auto_summary_rounds": self.auto_summary_rounds,
+            "multiline_inputer": self.multiline_inputer,
+            "use_methodology": self.use_methodology,
+            "use_analysis": self.use_analysis,
+            "force_save_memory": self.force_save_memory,
+            "files": self.files,
+            "confirm_callback": self.confirm_callback,
+            "non_interactive": True,
+            "in_multi_agent": True,
+            "plan": self.plan,  # 继承父Agent的规划开关
+            "plan_depth": self.plan_depth + 1,  # 子Agent层数+1
+            "plan_max_depth": self.plan_max_depth,  # 继承上限
+        }
+
+    def _maybe_plan_and_dispatch(self, task_text: str) -> None:
+        """委托给 TaskPlanner 执行任务规划与子任务调度，保持向后兼容。"""
+        try:
+            if hasattr(self, "task_planner") and self.task_planner:
+                # 优先使用初始化时注入的规划器
+                self.task_planner.maybe_plan_and_dispatch(task_text)  # type: ignore[attr-defined]
+            else:
+                # 防御式回退：临时创建规划器以避免因未初始化导致的崩溃
+                from jarvis.jarvis_agent.task_planner import TaskPlanner
+                TaskPlanner(self, plan_depth=self.plan_depth, plan_max_depth=self.plan_max_depth).maybe_plan_and_dispatch(task_text)
+        except Exception:
+            # 规划失败不影响主流程
+            pass
+
     def _filter_tools_if_needed(self, task: str):
         """如果工具数量超过阈值，使用大模型筛选相关工具"""
         tool_registry = self.get_tool_registry()

jarvis/jarvis_agent/jarvis.py

@@ -681,6 +681,7 @@ def run_cli(
     non_interactive: bool = typer.Option(
         False, "-n", "--non-interactive", help="启用非交互模式：用户无法与命令交互，脚本执行超时限制为5分钟"
     ),
+    plan: bool = typer.Option(False, "--plan/--no-plan", help="启用或禁用任务规划（拆分子任务并汇总执行结果）"),
     web: bool = typer.Option(False, "--web", help="以 Web 模式启动，通过浏览器 WebSocket 交互"),
     web_host: str = typer.Option("127.0.0.1", "--web-host", help="Web 服务主机"),
     web_port: int = typer.Option(8765, "--web-port", help="Web 服务端口"),
@@ -1022,6 +1023,11 @@ def run_cli(
             **extra_kwargs,
         )
         agent = agent_manager.initialize()
+        # CLI 开关：启用/禁用规划（不依赖 AgentManager 支持，直接设置 Agent 属性）
+        try:
+            agent.plan = bool(plan)
+        except Exception:
+            pass
 
         if web:
             try:

jarvis/jarvis_agent/task_planner.py

@@ -0,0 +1,218 @@
+# -*- coding: utf-8 -*-
+"""
+TaskPlanner: 任务规划与子任务调度器
+
+职责：
+- 判断是否需要拆分任务
+- 解析 <PLAN> YAML 列表
+- 为每个子任务创建子Agent并执行
+- 汇总所有子任务执行结果并写回父Agent上下文（包含 <PLAN>/<SUB_TASK_RESULTS>/<RESULT_SUMMARY>）
+"""
+
+from typing import Any, List
+import re
+
+import yaml  # type: ignore
+
+from jarvis.jarvis_agent.utils import join_prompts
+from jarvis.jarvis_utils.output import OutputType, PrettyOutput
+
+
+class TaskPlanner:
+    """将 Agent 的任务规划逻辑封装为独立类，便于维护与复用。"""
+
+    def __init__(self, agent: Any, plan_depth: int = 0, plan_max_depth: int = 2) -> None:
+        """
+        参数:
+            agent: 父Agent实例（须提供以下能力）
+              - _create_temp_model(system_prompt: str) -> BasePlatform
+              - _build_child_agent_params(name: str, description: str) -> dict
+              - name, session, plan 等属性
+            plan_depth: 当前规划深度（由外部在构造时传入）
+            plan_max_depth: 规划最大深度（由外部在构造时传入）
+        """
+        self.agent = agent
+        try:
+            self.plan_depth = int(plan_depth)
+        except Exception:
+            self.plan_depth = 0
+        try:
+            self.plan_max_depth = int(plan_max_depth)
+        except Exception:
+            self.plan_max_depth = 2
+
+    def maybe_plan_and_dispatch(self, task_text: str) -> None:
+        """
+        当启用 agent.plan 时，调用临时模型评估是否需要拆分任务并执行子任务。
+        - 若模型返回 <DONT_NEED/>，则直接返回不做任何修改；
+        - 若返回 <SUB_TASK> 块，则解析每行以“- ”开头的子任务，逐个创建子Agent执行；
+        - 将子任务与结果以结构化块写回到 agent.session.prompt，随后由主循环继续处理。
+        """
+        if not getattr(self.agent, "plan", False):
+            return
+
+        # 深度限制检查：当当前规划深度已达到或超过上限时，禁止继续规划
+        try:
+            current_depth = int(self.plan_depth)
+        except Exception:
+            current_depth = 0
+        try:
+            max_depth = int(self.plan_max_depth)
+        except Exception:
+            max_depth = 2
+
+        if current_depth >= max_depth:
+            PrettyOutput.print(
+                f"已达到任务规划最大深度({max_depth})，本层不再进行规划。", OutputType.INFO
+            )
+            return
+
+        try:
+            PrettyOutput.print("任务规划启动，评估是否需要拆分...", OutputType.INFO)
+            planning_sys = (
+                "你是一个任务规划助手。请判断是否需要拆分任务。\n"
+                "当需要拆分时，仅按以下结构输出：\n"
+                "<PLAN>\n- 子任务1\n- 子任务2\n</PLAN>\n"
+                "示例：\n"
+                "<PLAN>\n- 分析当前任务，提取需要修改的文件列表\n- 修改配置默认值并更新相关 schema\n- 更新文档中对该默认值的描述\n</PLAN>\n"
+                "要求：<PLAN> 内必须是有效 YAML 列表，仅包含字符串项；禁止输出任何额外解释。\n"
+                "当不需要拆分时，仅输出：\n<DONT_NEED/>\n"
+                "禁止输出任何额外解释。"
+            )
+            temp_model = self.agent._create_temp_model(planning_sys)
+            plan_prompt = f"任务：\n{task_text}\n\n请严格按要求只输出结构化标签块。"
+            plan_resp = temp_model.chat_until_success(plan_prompt)  # type: ignore
+            if not plan_resp:
+                PrettyOutput.print("任务规划模型未返回有效响应。", OutputType.WARNING)
+                return
+        except Exception as e:
+            # 规划失败不影响主流程
+            PrettyOutput.print(f"任务规划失败: {e}", OutputType.ERROR)
+            return
+
+        text = str(plan_resp).strip()
+        # 不需要拆分
+        if re.search(r"<\s*DONT_NEED\s*/\s*>", text, re.IGNORECASE):
+            PrettyOutput.print("任务规划完成：无需拆分。", OutputType.SUCCESS)
+            return
+
+        # 解析 <SUB_TASK> 块
+        m = re.search(
+            r"<\s*PLAN\s*>\s*(.*?)\s*<\s*/\s*PLAN\s*>",
+            text,
+            re.IGNORECASE | re.DOTALL,
+        )
+        subtasks: List[str] = []
+        if m:
+            block = m.group(1)
+            try:
+                data = yaml.safe_load(block)
+                if isinstance(data, list):
+                    for item in data:
+                        if isinstance(item, str):
+                            s = item.strip()
+                            if s:
+                                subtasks.append(s)
+                else:
+                    PrettyOutput.print("任务规划提示：无需拆分。", OutputType.INFO)
+            except Exception as e:
+                PrettyOutput.print("任务规划提示：无需拆分。", OutputType.INFO)
+        else:
+            PrettyOutput.print("任务规划提示：无需拆分。", OutputType.INFO)
+
+        if not subtasks:
+            # 无有效子任务，直接返回
+            PrettyOutput.print("任务规划提示：无需拆分。", OutputType.INFO)
+            return
+
+        PrettyOutput.print(f"任务已拆分为 {len(subtasks)} 个子任务:", OutputType.SUCCESS)
+        for i, st in enumerate(subtasks, 1):
+            PrettyOutput.print(f"  {i}. {st}", OutputType.INFO)
+
+        # 执行子任务
+        executed_subtask_block_lines: List[str] = ["<PLAN>"]
+        executed_subtask_block_lines += [f"- {t}" for t in subtasks]
+        executed_subtask_block_lines.append("</PLAN>")
+
+        results_lines: List[str] = []
+        for i, st in enumerate(subtasks, 1):
+            try:
+                PrettyOutput.print(f"开始执行子任务 {i}/{len(subtasks)}: {st}", OutputType.INFO)
+                child_kwargs = self.agent._build_child_agent_params(
+                    name=f"{self.agent.name}-child-{i}",
+                    description=f"子任务执行器: {st}",
+                )
+                # 使用父Agent的类创建子Agent，避免循环依赖
+                child = self.agent.__class__(**child_kwargs)
+                # 构造子任务执行提示，包含父任务与前置子任务结果，避免背景缺失
+                subtask_block_text = "\n".join(executed_subtask_block_lines)
+                if results_lines:
+                    prev_results_block = "<PREVIOUS_SUB_TASK_RESULTS>\n" + "\n".join(results_lines) + "\n</PREVIOUS_SUB_TASK_RESULTS>"
+                else:
+                    prev_results_block = "<PREVIOUS_SUB_TASK_RESULTS />"
+                child_prompt = join_prompts([
+                    f"原始任务：\n{task_text}",
+                    f"子任务规划：\n{subtask_block_text}",
+                    f"前置子任务执行结果：\n{prev_results_block}",
+                    f"当前子任务：{st}",
+                    "请基于原始任务背景与前置结果执行当前子任务，避免重复工作；如需依赖前置产物请直接复用；如需为后续子任务提供数据，请妥善保存（可使用工具保存文件或记忆）。"
+                ])
+                child_result = child.run(child_prompt)
+                result_text = "" if child_result is None else str(child_result)
+                # 防止极端长输出导致污染，这里不做截断，交由上层摘要策略控制
+                results_lines.append(f"- 子任务{i}: {st}\n  结果: {result_text}")
+                PrettyOutput.print(f"子任务 {i}/{len(subtasks)} 执行完成。", OutputType.SUCCESS)
+            except Exception as e:
+                results_lines.append(f"- 子任务{i}: {st}\n  结果: 执行失败，原因: {e}")
+                PrettyOutput.print(f"子任务 {i}/{len(subtasks)} 执行失败: {e}", OutputType.ERROR)
+
+        subtask_block = "\n".join(executed_subtask_block_lines)
+        results_block = "<SUB_TASK_RESULTS>\n" + "\n".join(results_lines) + "\n</SUB_TASK_RESULTS>"
+
+        PrettyOutput.print("所有子任务执行完毕，正在整合结果...", OutputType.INFO)
+        # 先对所有子任务结果进行简要自动汇总，便于父Agent继续整合
+        summary_block = "<RESULT_SUMMARY>\n无摘要（将直接使用结果详情继续）\n</RESULT_SUMMARY>"
+        try:
+            summarizing_sys = (
+                "你是一个任务结果整合助手。请根据提供的原始任务、子任务清单与子任务执行结果，"
+                "生成简明扼要的汇总与关键结论，突出已完成项、遗留风险与下一步建议。"
+                "严格仅输出以下结构：\n"
+                "<RESULT_SUMMARY>\n"
+                "…你的简要汇总…\n"
+                "</RESULT_SUMMARY>\n"
+                "不要输出其他任何解释。"
+            )
+            temp_model2 = self.agent._create_temp_model(summarizing_sys)
+            sum_prompt = (
+                f"原始任务：\n{task_text}\n\n"
+                f"子任务规划：\n{subtask_block}\n\n"
+                f"子任务执行结果：\n{results_block}\n\n"
+                "请按要求仅输出汇总块。"
+            )
+            sum_resp = temp_model2.chat_until_success(sum_prompt)  # type: ignore
+            if isinstance(sum_resp, str) and sum_resp.strip():
+                s = sum_resp.strip()
+                if not re.search(r"<\s*RESULT_SUMMARY\s*>", s, re.IGNORECASE):
+                    s = f"<RESULT_SUMMARY>\n{s}\n</RESULT_SUMMARY>"
+                summary_block = s
+        except Exception:
+            # 汇总失败不影响主流程，继续使用默认占位
+            pass
+
+        # 合并回父Agent的 prompt，父Agent将基于汇总与详情继续执行
+        try:
+            self.agent.session.prompt = join_prompts(
+                [
+                    f"原始任务：\n{task_text}",
+                    f"子任务规划：\n{subtask_block}",
+                    f"子任务结果汇总：\n{summary_block}",
+                    f"子任务执行结果：\n{results_block}",
+                    "请基于上述子任务结果整合并完成最终输出。",
+                ]
+            )
+        except Exception:
+            # 回退拼接
+            self.agent.session.prompt = (
+                f"{task_text}\n\n{subtask_block}\n\n{summary_block}\n\n{results_block}\n\n"
+                "请基于上述子任务结果整合并完成最终输出。"
+            )

jarvis/jarvis_code_agent/code_agent.py

@@ -40,7 +40,7 @@ from jarvis.jarvis_utils.git_utils import (
 )
 from jarvis.jarvis_utils.input import get_multiline_input, user_confirm
 from jarvis.jarvis_utils.output import OutputType, PrettyOutput
-from jarvis.jarvis_utils.utils import get_loc_stats, init_env
+from jarvis.jarvis_utils.utils import get_loc_stats, init_env, _acquire_single_instance_lock
 
 app = typer.Typer(help="Jarvis 代码助手")
 
@@ -58,6 +58,8 @@ class CodeAgent:
         append_tools: Optional[str] = None,
         tool_group: Optional[str] = None,
         non_interactive: Optional[bool] = None,
+        plan: Optional[bool] = None,
+        **kwargs,
     ):
         self.root_dir = os.getcwd()
         self.tool_group = tool_group
@@ -112,6 +114,7 @@ class CodeAgent:
             use_methodology=False,  # 禁用方法论
             use_analysis=False,  # 禁用分析
             non_interactive=self.non_interactive,
+            plan=bool(plan) if plan is not None else False,
         )
 
         self.agent.event_bus.subscribe(AFTER_TOOL_CALL, self._on_after_tool_call)
@@ -894,6 +897,7 @@ def cli(
     non_interactive: bool = typer.Option(
         False, "-n", "--non-interactive", help="启用非交互模式：用户无法与命令交互，脚本执行超时限制为5分钟"
     ),
+    plan: bool = typer.Option(False, "--plan/--no-plan", help="启用或禁用任务规划（子任务拆分与汇总执行）"),
 ) -> None:
     """Jarvis主入口点。"""
     # CLI 标志：非交互模式（不依赖配置文件）
@@ -914,6 +918,8 @@ def cli(
         "欢迎使用 Jarvis-CodeAgent，您的代码工程助手已准备就绪！",
         config_file=config_file,
     )
+    # CodeAgent 单实例互斥：仅代码助手入口加锁，其他入口不受影响
+    _acquire_single_instance_lock(lock_name="code_agent.lock")
 
     # 在初始化环境后同步 CLI 选项到全局配置，避免被 init_env 覆盖
     try:
@@ -973,6 +979,7 @@ def cli(
             append_tools=append_tools,
             tool_group=tool_group,
             non_interactive=non_interactive,
+            plan=plan,
         )
 
         # 尝试恢复会话

jarvis/jarvis_data/config_schema.json

@@ -188,6 +188,11 @@
       "description": "AI工具筛选阈值：当可用工具数量超过此值时触发AI筛选",
       "default": 30
     },
+    "JARVIS_PLAN_MAX_DEPTH": {
+      "type": "number",
+      "description": "任务规划的最大层数。用于限制 plan 模式的递归拆分深度。仅在启用规划时生效（通过 CLI --plan/--no-plan 控制），默认 3。",
+      "default": 2
+    },
     "JARVIS_SCRIPT_EXECUTION_TIMEOUT": {
       "type": "number",
       "description": "脚本执行的超时时间（秒），仅在非交互模式下生效。",
@@ -196,7 +201,7 @@
     "JARVIS_AUTO_SUMMARY_ROUNDS": {
       "type": "number",
       "description": "基于对话轮次的自动总结阈值（达到该轮次后自动总结并清理历史）",
-      "default": 20
+      "default": 50
     },
     "JARVIS_CONFIRM_BEFORE_APPLY_PATCH": {
       "type": "boolean",

jarvis/jarvis_sec/README.md

@@ -0,0 +1,180 @@
+OpenHarmony 安全演进套件（jarvis_sec）
+================================
+
+概览
+- 模式：单 Agent 逐条子任务分析（先直扫拆分候选，再由 Agent 精核）
+- 目标：在不破坏现有功能的前提下，增强稳定性与可追溯性，减少“全部解析失败”的概率
+- 关键特性：
+  - 禁用方法论与分析（use_methodology=False, use_analysis=False），降低不确定性
+  - 按次指定模型组（--llm-group / llm_group 参数），不修改全局配置
+  - 启用摘要 need_summary=True，通过 <REPORT>…</REPORT> 输出结构化结果
+  - 进度与过程日志输出（Progress / parse-fail / no-issue / issues-found）
+  - 增量写入 JSONL 报告，长任务中可实时查看
+  - 只读约束：禁止任何写文件或破坏性命令（rm/mv/cp/echo >/sed -i/git/patch/chmod/chown 等）
+
+CLI 使用
+- 入口：python -m jarvis.jarvis_sec.cli agent --path ./target_project
+- 可选参数：
+  - --languages/-l：逗号分隔的扩展名列表，例如 "c,cpp,h,hpp,rs"
+  - --llm-group/-g：本次运行使用的模型组（仅透传，不改全局）
+  - --report-file/-r：JSONL 报告输出路径（默认写入 path/.jarvis/sec/agent_issues.jsonl）
+
+示例
+- 最简运行：
+  python -m jarvis.jarvis_sec.cli agent -p ./path/to/project
+
+- 指定语言与临时模型组：
+  python -m jarvis.jarvis_sec.cli agent -p ./proj -l c,cpp,h,hpp,rs -g my_llm_group
+
+- 指定增量报告文件：
+  python -m jarvis.jarvis_sec.cli agent -p ./proj -r ./out/agent_issues.jsonl
+
+工作流要点
+1) 直扫（direct_scan）
+- 使用正则/命令行辅助在本地生成候选问题（issues）与统计信息（summary）
+- 可在无外部服务时复现与回退，保障可用性
+
+2) 子任务拆分与单 Agent 精核
+- 将每个候选压缩为精简上下文（language、category、pattern、file、line、evidence 等）
+- 单 Agent 周期内：
+  - need_summary=True
+  - summary_prompt 为 _build_summary_prompt(...) 返回的提示，要求在 <REPORT>…</REPORT> 内输出 JSON 或 YAML
+  - 系统提示包含只读约束与“一次仅执行一个工具”规则
+  - 推荐工具：read_code（读取目标文件附近源码）、execute_script（只读检索，如 rg/find）
+
+3) 解析策略
+- 优先解析摘要（agent.generate_summary()）中的 <REPORT>…</REPORT>：
+  - _try_parse_summary_report 支持 JSON 优先，失败回退 YAML（safe_load）
+- 摘要不可解析时，直接判定 parse-fail（不会回退解析主输出）
+
+4) 增量写入 JSONL
+- 每个子任务如检测到 issues，立即将记录 append 到 JSONL（默认 path/.jarvis/sec/agent_issues.jsonl）
+- 支持通过 --report-file/-r 指定其他路径
+- 失败不会影响主流程
+
+JSONL 记录结构
+- 每行一个 JSON 对象，格式如下：
+  {
+    "task_id": "JARVIS-SEC-Analyzer-3",
+    "candidate": {
+      "language": "c/cpp",
+      "category": "unsafe_api",
+      "pattern": "strcpy",
+      "file": "src/foo.c",
+      "line": 120,
+      "evidence": "strcpy(dst, src);",
+      "confidence": 0.9,
+      "severity": "high"
+    },
+    "issues": [
+      {
+        "language": "c/cpp",
+        "category": "unsafe_api",
+        "pattern": "strcpy",
+        "file": "src/foo.c",
+        "line": 120,
+        "evidence": "strcpy(dst, src);",
+        "description": "使用不安全/高风险字符串API，可能导致缓冲区溢出或格式化风险。",
+        "suggestion": "替换为带边界的安全API（如 snprintf/strlcpy 等）或加入显式长度检查。",
+        "confidence": 0.9,
+        "severity": "high"
+      }
+    ],
+    "meta": {
+      "entry_path": "/abs/path/to/project",
+      "languages": ["c","cpp","h","hpp","rs"],
+      "source": "summary"
+      "timestamp": "2025-10-19T03:00:00Z"
+    }
+  }
+
+摘要 <REPORT> 结构
+- Agent 在摘要中必须只输出以下内容（推荐 JSON，支持 YAML）：
+  <REPORT>
+  {
+    "issues": [
+      {
+        "language": "c/cpp|rust",
+        "category": "unsafe_api|buffer_overflow|memory_mgmt|error_handling|unsafe_usage|concurrency|ffi",
+        "pattern": "命中的模式/关键字",
+        "file": "相对或绝对路径",
+        "line": 0,
+        "evidence": "证据代码片段（单行简化）",
+        "description": "问题说明",
+        "suggestion": "修复建议",
+        "confidence": 0.0,
+        "severity": "high|medium|low"
+      }
+    ],
+    "meta": {
+      "task_id": "JARVIS-SEC-Analyzer-1",
+      "entry_path": "/abs/path",
+      "languages": ["c","cpp","h","hpp","rs"],
+      "candidate": { "...": "子任务精简信息" }
+    }
+  }
+  </REPORT>
+
+- 要求：
+  - 仅在 <REPORT> 与 </REPORT> 中输出报告，不得出现其他文本
+  - 若确认误报，返回空数组 issues: []
+  - 字段值需与实际分析一致
+
+只读约束（强制）
+- Agent 被要求仅做只读分析：禁止修改任何文件或执行写操作命令
+- 禁止命令包含但不限于：rm/mv/cp/echo >、sed -i、git、patch、chmod、chown 等
+- 推荐工具：
+  - read_code：按文件路径与行号范围读取源码（建议围绕候选行上下 50 行）
+  - execute_script：只读检索（如 rg/find/grep），避免任何写操作
+
+日志与可观测性
+- 进度日志：
+  - [JARVIS-SEC] Progress i/N: file:line (lang)
+  - [JARVIS-SEC] no-issue i/N: ...
+  - [JARVIS-SEC] issues-found i/N: count=k -> append report (summary)
+  - [JARVIS-SEC] parse-fail i/N: ...
+- JSONL 写入：
+  - [JARVIS-SEC] write K issue(s) to <path>
+
+模型组（llm_group）
+- 通过 CLI 的 --llm-group 或 API 的 llm_group 参数传入，仅对本次调用链生效
+- 不会覆盖全局配置（不调用 set_config）
+
+常见问题排查
+- 解析失败（parse-fail）：
+  - 确认模型已在摘要中输出 <REPORT>…</REPORT>
+  - 优先使用 JSON；YAML 解析依赖 PyYAML（safe_load），若环境无此库将忽略 YAML 回退
+  - 注意：不会回退解析主输出；若摘要缺失或格式不合规，将直接跳过该候选
+- JSONL 未写入：
+  - 仅当 issues 非空时追加写入
+  - 确认 --report-file 或默认目录 path/.jarvis/sec/ 可写
+- Agent 输出为空：
+  - CLI 会回退到直扫基线（run_security_analysis_fast），仍可得到 JSON+Markdown 报告
+
+API 概览
+- run_with_multi_agent(entry_path, languages=None, llm_group=None, report_file=None) -> str
+  - 透传到 run_security_analysis(...)，实现“直扫 + 单 Agent 逐条验证 + 聚合”
+- run_security_analysis_fast(entry_path, languages=None, exclude_dirs=None) -> str
+  - 纯直扫基线，返回 JSON + Markdown
+- direct_scan(entry_path, languages=None, exclude_dirs=None) -> Dict
+  - 返回结构化 issues 与 summary
+- run_with_multi_agent(entry_path, languages=None, llm_group=None, report_file=None) -> str
+  - 透传到 run_security_analysis(...)，实现“直扫 + 单 Agent 逐条验证 + 聚合”
+- run_security_analysis_fast(entry_path, languages=None, exclude_dirs=None) -> str
+  - 纯直扫基线，返回 JSON + Markdown
+- direct_scan(entry_path, languages=None, exclude_dirs=None) -> Dict
+  - 返回结构化 issues 与 summary
+
+建议测试（可选）
+- 摘要解析：
+  - _try_parse_summary_report 对 JSON/YAML/无 REPORT 的输入解析正确
+- CLI 参数链路：
+  - --llm-group 仅透传，不改全局
+  - --report-file 写入指定路径
+- 只读约束：
+  - 模拟 Agent 工具调用，确保拒绝写操作命令（可在提示词层面校验）
+
+版本兼容与注意事项
+- 本模块不修改全局模型组配置
+- 摘要使用 JSON 优先，YAML 为回退路径（需 PyYAML）
+- 直扫基线可在无外部服务时独立运行，便于复现与回退