# Jarvis系统目标保持机制分析

## 概述

本文档分析了Jarvis系统中Code Agent和Agent实现如何通过各种机制确保初始目标在执行过程中不偏离。重点分析了总结行为中的提示机制、记忆管理、代码审查等关键功能。

## 核心机制

### 1. 总结机制（Summary Mechanism）

#### 1.1 总结触发时机

Jarvis系统在以下两种情况下会触发总结生成：

- **Token限制触发**：当对话历史达到token限制时，自动生成总结进行上下文压缩
- **任务完成触发**：任务执行完成后生成完整的总结报告

#### 1.2 总结提示词设计

系统使用两种不同的总结提示词：

**DEFAULT_SUMMARY_PROMPT**（默认总结提示词）：

- 用于任务完成时的总结
- 提供完整的结构化报告格式
- 包含目标层次结构、任务状态矩阵、关键信息导航等

**SUMMARY_REQUEST_PROMPT**（Token限制触发提示词）：

- 专门用于上下文压缩场景
- 强调"无关键信息缺失"原则
- 特别针对代码开发任务，要求完整保留代码变更上下文

#### 1.3 总结验证机制

在代码审查阶段，系统会特别验证总结内容的准确性：

```python
# 审查要求（来自_build_review_prompts方法）
"""
- **对代码生成总结中的关键信息进行充分验证**：不能盲目信任总结，必须结合 git diff 和实际代码逐条核对
- 如需了解更多上下文，必须使用 read_code 工具读取相关文件以验证总结中提到的行为/位置/文件是否真实存在并符合描述
- 如果代码生成总结与实际代码不一致，应以实际代码为准，并将不一致情况作为问题记录
"""
```

### 2. 记忆管理系统

#### 2.1 记忆类型

系统支持三种记忆类型：

- **短期记忆（short_term）**：当前任务的临时数据、调试信息、中间结果
- **项目长期记忆（project_long_term）**：关键架构决策、配置方案、业务规则
- **全局长期记忆（global_long_term）**：通用解决方案、最佳实践、技术标准

#### 2.2 记忆提示机制

在任务开始时，系统会自动提示可用的记忆标签：

```python
def prepare_memory_tags_prompt(self) -> str:
    """准备记忆标签提示"""
    # 检查是否有memory工具
    if self._has_memory_tool():
        memory_tags_prompt = "\n\n💡 提示：在分析任务之前，建议使用 memory 工具（action=save）将关键信息记录下来，便于后续检索和复用。"
```

#### 2.3 自动记忆保存

系统会在任务完成时自动提示保存值得记忆的信息：

```python
def prompt_memory_save(self) -> None:
    """让大模型自动判断并保存值得记忆的信息"""
    prompt = """回顾本次任务，判断是否有值得记忆的信息。使用 memory 工具（action=save）保存：
- global_long_term: 新方法/技巧、用户偏好、技术知识
- project_long_term: 项目发现/配置、实现细节/约定
如无值得记忆的信息，直接说明。"""
```

### 3. 代码审查与修复循环

#### 3.1 审查流程

CodeAgent实现了多轮代码审查机制：

1. **获取代码变更**：通过git diff获取从任务开始到当前的所有修改
2. **构建审查提示**：结合用户需求、修改历史和代码变更构建审查提示
3. **独立审查Agent**：创建专门的CodeReview-Agent进行独立审查
4. **问题解析**：解析审查结果，识别需要修复的问题
5. **修复执行**：根据审查结果进行修复
6. **修复总结**：生成修复总结并追加到修改历史

#### 3.2 修改历史追踪

系统维护完整的修改历史记录：

```python
# 保存初始总结作为修改历史的第一部分
modification_history = code_generation_summary or ""

# 每轮修复后追加修复总结
fix_summary = self._generate_fix_summary()
if fix_summary:
    modification_history += f"\n\n【第 {iteration} 轮修复总结】\n{fix_summary}"
```

#### 3.3 审查验证要求

审查阶段特别强调对总结内容的验证：

- **不盲目信任总结**：将总结视为"待核实的说明"
- **逐条核对**：对总结中提到的每个关键修改点，都必须在git diff或实际代码中找到对应依据
- **不一致处理**：发现总结与实际代码不一致时，必须在审查结果中指出

### 4. 初始目标锚定机制

#### 4.1 Git Commit锚点

系统在任务开始时记录初始Git Commit作为安全回退点：

````python
# 将初始 commit 信息添加到 addon_prompt（安全回退点）
initial_commit_prompt = f"""
**🔖 初始 Git Commit（安全回退点）**：
本次任务开始时的初始 commit 是：`{start_commit}`

**⚠️ 安全回退命令**：
```bash
git reset --hard {start_commit}
````

这将丢弃所有未提交的更改，将工作区恢复到任务开始时的状态。
"""

````

#### 4.2 用户需求保持

在审查提示中明确要求尊重用户原始需求：

```python
"""**尊重用户原始需求**：如果用户在需求中明确支持某个方案或实现方式，不应将其判定为风险或问题，除非该方案存在明显的错误或违反安全原则"""
````

#### 4.3 非交互模式约束

在非交互模式下，系统自动执行计划，避免因等待用户确认而偏离目标：

```python
non_interactive_note = """
[系统说明]
本次会话处于**非交互模式**：
- 在 PLAN 模式中给出清晰、可执行的详细计划后，应**自动进入 EXECUTE 模式执行计划**，不要等待用户额外确认；
- 在 EXECUTE 模式中，保持一步一步的小步提交和可回退策略，但不需要向用户反复询问"是否继续"；
- 如遇信息严重不足，可以在 RESEARCH 模式中自行补充必要分析，而不是卡在等待用户输入。
"""
```

### 5. 代码变更上下文管理

#### 5.1 上下文管理器

CodeAgent使用ContextManager管理代码分析上下文：

```python
self.context_manager = ContextManager(self.root_dir)
```

#### 5.2 影响范围分析

通过ImpactManager分析代码修改的影响范围：

```python
self.impact_manager = ImpactManager(self.root_dir, self.context_manager)
```

#### 5.3 构建验证

通过BuildValidationManager验证代码修改后的构建状态：

```python
self.build_validation_manager = BuildValidationManager(self.root_dir)
```

## 关键设计原则

### 1. 验证优先原则

- 所有总结内容必须经过实际验证
- 不能仅凭代码存在就认为任务完成
- 必须提供具体的验证证据（编译结果、测试结果、运行日志等）

### 2. 上下文完整性原则

- 总结必须提供"无关键信息缺失"的上下文支撑
- 特别针对代码开发任务，要求完整保留代码变更的上下文
- 确保后续对话无需回溯原始历史即可顺畅推进

### 3. 实际代码为准原则

- 审查阶段必须以实际代码为准，不能盲目信任总结
- 发现总结与实际代码不一致时，必须指出并纠正
- 所有判断必须基于实际验证，不能凭空假设

### 4. 渐进式修复原则

- 支持多轮审查和修复循环
- 每轮修复后生成修复总结并更新修改历史
- 通过迭代方式逐步逼近目标实现

## 实现文件位置

### 核心实现文件

1. **CodeAgent主类**：`src/jarvis/jarvis_code_agent/code_agent.py`
   - `_review_and_fix()`：审查修复循环
   - `_build_review_prompts()`：构建审查提示
   - `generate_summary()`：总结生成

2. **Agent基类**：`src/jarvis/jarvis_agent/__init__.py`
   - `generate_summary()`：总结生成基础实现

3. **提示词定义**：`src/jarvis/jarvis_agent/prompts.py`
   - `DEFAULT_SUMMARY_PROMPT`：默认总结提示词
   - `SUMMARY_REQUEST_PROMPT`：Token限制触发提示词

4. **记忆管理**：`src/jarvis/jarvis_agent/memory_manager.py`
   - `prepare_memory_tags_prompt()`：记忆标签提示
   - `prompt_memory_save()`：自动记忆保存

### 相关管理器

- **Git管理器**：`src/jarvis/jarvis_code_agent/code_agent_git.py`
- **Diff管理器**：`src/jarvis/jarvis_code_agent/code_agent_diff.py`
- **影响分析管理器**：`src/jarvis/jarvis_code_agent/code_agent_impact.py`
- **构建验证管理器**：`src/jarvis/jarvis_code_agent/code_agent_build.py`

## 总结

Jarvis系统通过多层次的目标保持机制确保初始目标在执行过程中不偏离：

1. **结构化总结机制**：通过精心设计的总结提示词确保关键信息不丢失
2. **记忆管理系统**：通过记忆标签和自动保存机制保留重要上下文
3. **代码审查循环**：通过多轮独立审查确保代码修改符合原始需求
4. **验证优先原则**：所有结论必须基于实际验证，避免主观臆断
5. **渐进式修复**：通过迭代方式逐步逼近目标实现

这些机制共同构成了一个完整的闭环系统，能够在复杂的代码开发任务中有效保持目标一致性，避免在执行过程中偏离原始需求。
