jarvis-ai-assistant 0.4.2__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.4.2"
+__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 (
@@ -249,8 +249,23 @@ class Agent:
     def clear_history(self):
         """
         Clears the current conversation history by delegating to the session manager.
+        Emits BEFORE_HISTORY_CLEAR/AFTER_HISTORY_CLEAR and reapplies system prompt to preserve constraints.
         """
+        # 广播清理历史前事件（不影响主流程）
+        try:
+            self.event_bus.emit(BEFORE_HISTORY_CLEAR, agent=self)
+        except Exception:
+            pass
+
+        # 清理会话历史并重置模型状态
         self.session.clear_history()
+
+        # 重置后重新设置系统提示词，确保系统约束仍然生效
+        try:
+            self._setup_system_prompt()
+        except Exception:
+            pass
+
         # 广播清理历史后的事件
         try:
             self.event_bus.emit(AFTER_HISTORY_CLEAR, agent=self)
@@ -270,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,
@@ -291,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实例
@@ -310,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 中统一解析）
         # 标识与描述
@@ -333,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
@@ -414,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()
@@ -786,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:
@@ -1003,7 +1059,6 @@ class Agent:
     {complete_prompt}
     如果没有完成，请进行下一步操作：
     - 仅包含一个操作
-    - 不要询问用户是否继续，直接继续执行直至完成
     - 如果信息不明确，请请求用户补充
     - 如果执行过程中连续失败5次，请使用ask_user询问用户操作
     - 操作列表：{action_handlers}{memory_prompts}
@@ -1043,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)
@@ -1150,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/share_manager.py

@@ -49,7 +49,14 @@ class ShareManager(ABC):
     def __init__(self, central_repo_url: str, repo_name: str):
         self.central_repo_url = central_repo_url
         self.repo_name = repo_name
-        self.repo_path = os.path.join(get_data_dir(), repo_name)
+        # 支持将中心仓库配置为本地目录（含git子路径）
+        expanded = os.path.expanduser(os.path.expandvars(central_repo_url))
+        if os.path.isdir(expanded):
+            # 直接使用本地目录作为中心仓库路径（支持git仓库子目录）
+            self.repo_path = expanded
+        else:
+            # 仍按原逻辑使用数据目录中的克隆路径
+            self.repo_path = os.path.join(get_data_dir(), repo_name)
 
     def update_central_repo(self) -> None:
         """克隆或更新中心仓库"""

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

@@ -25,6 +25,7 @@ from jarvis.jarvis_utils.config import (
     is_enable_static_analysis,
     get_git_check_mode,
     set_config,
+    get_data_dir,
 )
 from jarvis.jarvis_utils.git_utils import (
     confirm_add_new_files,
@@ -39,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 代码助手")
 
@@ -57,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
@@ -86,6 +89,22 @@ class CodeAgent:
 
         tool_registry.use_tools(base_tools)
         code_system_prompt = self._get_system_prompt()
+        # 先加载全局规则（数据目录 rules），再加载项目规则（.jarvis/rules），并拼接为单一规则块注入
+        global_rules = self._read_global_rules()
+        project_rules = self._read_project_rules()
+
+        combined_parts: List[str] = []
+        if global_rules:
+            combined_parts.append(global_rules)
+        if project_rules:
+            combined_parts.append(project_rules)
+
+        if combined_parts:
+            merged_rules = "\n\n".join(combined_parts)
+            code_system_prompt = (
+                f"{code_system_prompt}\n\n"
+                f"<rules>\n{merged_rules}\n</rules>"
+            )
         self.agent = Agent(
             system_prompt=code_system_prompt,
             name="CodeAgent",
@@ -95,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)
@@ -164,6 +184,32 @@ class CodeAgent:
 </say_to_llm>
 """
 
+    def _read_project_rules(self) -> Optional[str]:
+        """读取 .jarvis/rules 内容，如果存在则返回字符串，否则返回 None"""
+        try:
+            rules_path = os.path.join(self.root_dir, ".jarvis", "rules")
+            if os.path.exists(rules_path) and os.path.isfile(rules_path):
+                with open(rules_path, "r", encoding="utf-8", errors="replace") as f:
+                    content = f.read().strip()
+                return content if content else None
+        except Exception:
+            # 读取规则失败时忽略，不影响主流程
+            pass
+        return None
+
+    def _read_global_rules(self) -> Optional[str]:
+        """读取数据目录 rules 内容，如果存在则返回字符串，否则返回 None"""
+        try:
+            rules_path = os.path.join(get_data_dir(), "rules")
+            if os.path.exists(rules_path) and os.path.isfile(rules_path):
+                with open(rules_path, "r", encoding="utf-8", errors="replace") as f:
+                    content = f.read().strip()
+                return content if content else None
+        except Exception:
+            # 读取规则失败时忽略，不影响主流程
+            pass
+        return None
+
     def _check_git_config(self) -> None:
         """检查 git username 和 email 是否已设置，如果没有则提示并退出"""
         try:
@@ -672,12 +718,58 @@ class CodeAgent:
         def _build_per_file_patch_preview(modified_files: List[str]) -> str:
             status_map = _build_name_status_map()
             lines: List[str] = []
+
+            def _get_file_numstat(file_path: str) -> Tuple[int, int]:
+                """获取单文件的新增/删除行数，失败时返回(0,0)"""
+                head_exists = bool(get_latest_commit_hash())
+                try:
+                    # 让未跟踪文件也能统计到新增行数
+                    subprocess.run(["git", "add", "-N", "--", file_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                    cmd = ["git", "diff", "--numstat"] + (["HEAD"] if head_exists else []) + ["--", file_path]
+                    res = subprocess.run(
+                        cmd,
+                        capture_output=True,
+                        text=True,
+                        encoding="utf-8",
+                        errors="replace",
+                        check=False,
+                    )
+                    if res.returncode == 0 and res.stdout:
+                        for line in res.stdout.splitlines():
+                            parts = line.strip().split("\t")
+                            if len(parts) >= 3:
+                                add_s, del_s = parts[0], parts[1]
+
+                                def to_int(x: str) -> int:
+                                    try:
+                                        return int(x)
+                                    except Exception:
+                                        # 二进制或无法解析时显示为0
+                                        return 0
+
+                                return to_int(add_s), to_int(del_s)
+                finally:
+                    subprocess.run(["git", "reset", "--", file_path], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                return (0, 0)
+
             for f in modified_files:
                 status = status_map.get(f, "")
-                # 删除文件：不展示diff，仅提示
+                adds, dels = _get_file_numstat(f)
+                total_changes = adds + dels
+
+                # 删除文件：不展示diff，仅提示（附带删除行数信息如果可用）
                 if (status.startswith("D")) or (not os.path.exists(f)):
-                    lines.append(f"- {f} 文件被删除")
+                    if dels > 0:
+                        lines.append(f"- {f} 文件被删除（删除{dels}行）")
+                    else:
+                        lines.append(f"- {f} 文件被删除")
                     continue
+
+                # 变更过大：仅提示新增/删除行数，避免输出超长diff
+                if total_changes > 300:
+                    lines.append(f"- {f} 新增{adds}行/删除{dels}行（变更过大，预览已省略）")
+                    continue
+
                 # 其它情况：展示该文件的diff
                 file_diff = _get_file_diff(f)
                 if file_diff.strip():
@@ -805,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 标志：非交互模式（不依赖配置文件）
@@ -825,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:
@@ -884,6 +979,7 @@ def cli(
             append_tools=append_tools,
             tool_group=tool_group,
             non_interactive=non_interactive,
+            plan=plan,
         )
 
         # 尝试恢复会话