# 通用 Agent 功能映射草案

## 说明

本文档用于沉淀 `功能清单_分类版.md` 中“通用 Agent”分类的源码取证结果，作为后续拆分为单功能用户手册文档的基线。

- 文档范围：`/home/skyfire/code/Jarvis/功能清单_分类版.md` 第 3-39 行
- 当前确认功能数：37
- 文档目标：记录“功能点 → 源码依据 → 用户可见行为”，避免后续重复分析
- 注意：本文件是分析草案，不直接面向最终用户；正式用户手册需进一步改写为使用场景、操作步骤、效果与注意事项

## 代码来源

### 主要源码文件

- `src/jarvis/jarvis_agent/main.py`
- `src/jarvis/jarvis_agent/__init__.py`
- `src/jarvis/jarvis_agent/builtin_input_handler.py`
- `src/jarvis/jarvis_agent/session_manager.py`
- `src/jarvis/jarvis_agent/rules_manager.py`
- `src/jarvis/jarvis_agent/file_context_handler.py`
- `src/jarvis/jarvis_agent/shell_input_handler.py`
- `src/jarvis/jarvis_agent/tool_executor.py`
- `src/jarvis/jarvis_agent/run_loop.py`
- `src/jarvis/jarvis_agent/memory_manager.py`
- `src/jarvis/jarvis_agent/file_methodology_manager.py`
- `src/jarvis/jarvis_agent/user_interaction.py`
- `src/jarvis/jarvis_agent/task_manager.py`
- `src/jarvis/jarvis_agent/agent_manager.py`
- `src/jarvis/jarvis_agent/jvsd_cli.py`

## 功能映射草案

### 1. 如何使用通用代理交互式执行任务

- 源码依据：`main.py`、`__init__.py`
- 行为摘要：直接启动后进入交互式输入流程，用户可输入任务并立即交给 Agent 执行。

### 2. 如何让通用代理直接执行命令行传入的任务

- 源码依据：`main.py`
- 行为摘要：支持通过命令行参数直接传入任务内容，启动后无需再次输入，立即执行该任务。

### 3. 如何为通用代理指定自定义配置文件

- 源码依据：`main.py`
- 行为摘要：支持在启动时指定额外配置来源，用于覆盖默认行为或加载特定代理定义。

### 4. 如何为通用代理切换模型组

- 源码依据：`main.py`、`builtin_input_handler.py`
- 行为摘要：既可在启动时指定模型组，也存在运行中切换当前模型组的入口。

### 5. 如何以非交互模式运行通用代理

- 源码依据：`main.py`、`__init__.py`
- 行为摘要：非交互模式下必须直接提供任务内容，运行期间不依赖多轮人工输入。

### 6. 如何让通用 Agent 自动加载当前激活的规则内容

- 源码依据：`__init__.py`、`rules_manager.py`
- 行为摘要：Agent 初始化后会合并当前激活规则，并把规则内容纳入后续任务上下文。

### 7. 如何在启动时加载并选择预定义任务

- 源码依据：`task_manager.py`、`agent_manager.py`
- 行为摘要：首次运行且满足条件时，系统会读取预定义任务列表，允许用户先选任务再执行。

### 8. 如何为预定义任务追加补充信息

- 源码依据：`task_manager.py`
- 行为摘要：选定预定义任务后，用户还可以继续输入补充说明，与原任务一起提交。

### 9. 如何通过内置标记执行总结、清空历史、重载配置、查看工具说明和规则状态

- 源码依据：`builtin_input_handler.py`、`__init__.py`
- 行为摘要：输入特定内置标记后，可直接触发总结、清空、重载、工具说明展示、规则列表展示等系统操作。

### 10. 如何在对话中固定长期有效的补充要求

- 源码依据：`builtin_input_handler.py`、`__init__.py`
- 行为摘要：支持把一段补充要求固定到后续对话中，减少重复输入。

### 11. 如何在输入中引用文件并自动附加文件符号信息

- 源码依据：`file_context_handler.py`
- 行为摘要：当输入中包含文件路径引用时，系统会尝试追加文件中的结构化符号信息，帮助模型快速理解文件内容。

### 12. 如何在对话中直接执行以 ! 开头的 Shell 脚本并决定是否回传结果

- 源码依据：`shell_input_handler.py`
- 行为摘要：支持在输入中直接写 shell 脚本；执行前可确认，执行后还可选择是否把结果继续反馈给 Agent。

### 13. 如何在工具调用前查看将执行的工具和参数摘要

- 源码依据：`tool_executor.py`
- 行为摘要：当开启确认流程时，系统会先展示准备执行的工具名称和参数摘要，便于用户审查。

### 14. 如何在开启确认后手动决定是否执行工具调用

- 源码依据：`tool_executor.py`、`__init__.py`
- 行为摘要：在工具实际执行前，用户可以明确选择继续或取消。

### 15. 如何在运行中中断模型输出并输入人工干预信息

- 源码依据：`__init__.py`、`run_loop.py`
- 行为摘要：模型运行过程中支持中断，之后用户可以补充新的要求或纠正方向。

### 16. 如何在中断后决定是否继续执行即将发生的工具调用

- 源码依据：`__init__.py`、`run_loop.py`
- 行为摘要：在中断发生后，系统会给用户介入机会，避免未经确认继续执行后续动作。

### 17. 如何在上下文过长或轮次过多时自动压缩历史、生成摘要并清理上下文

- 源码依据：`run_loop.py`、`__init__.py`
- 行为摘要：当对话过长或输入窗口接近限制时，系统会自动进行摘要压缩，减少上下文膨胀。

### 18. 如何在摘要后保留原始任务目标、固定内容和最近记忆

- 源码依据：`__init__.py`
- 行为摘要：在执行摘要压缩后，系统会尽量保留任务主线、固定提示和记忆相关信息，避免上下文断裂。

### 19. 如何自动保存会话到项目下的 .jarvis/sessions 目录

- 源码依据：`session_manager.py`、`__init__.py`
- 行为摘要：会话支持保存到项目目录下的专用位置，便于后续恢复继续。

### 20. 如何按会话名称保存并自动清理旧会话

- 源码依据：`session_manager.py`
- 行为摘要：会话保存时会生成主题化名称，并按既定格式落盘管理。

### 21. 如何恢复历史会话

- 源码依据：`session_manager.py`、`__init__.py`
- 行为摘要：用户可查看并恢复历史会话，继续之前的任务上下文。

### 22. 如何在恢复会话前检查 Git commit 是否一致

- 源码依据：`session_manager.py`
- 行为摘要：恢复前会检查当前仓库状态与历史会话记录是否匹配，降低上下文错位风险。

### 23. 如何在恢复会话时选择 reset 到旧 commit 或继续恢复

- 源码依据：`session_manager.py`
- 行为摘要：当检测到版本不一致时，系统提供进一步处理选择，而不是直接强行恢复。

### 24. 如何在恢复会话前检查历史消息是否超出当前模型 token 限制

- 源码依据：`session_manager.py`
- 行为摘要：恢复前会评估当前模型是否还能承载原有上下文，避免恢复后立即超限。

### 25. 如何在任务完成后自动触发任务分析

- 源码依据：`__init__.py`
- 行为摘要：任务结束后可自动进入总结分析流程，帮助提炼后续可复用信息。

### 26. 如何手动直接执行任务分析

- 源码依据：`__init__.py`
- 行为摘要：除自动触发外，也支持在需要时主动发起任务分析。

### 27. 如何在任务结束时让系统自动判断是否保存长期记忆

- 源码依据：`memory_manager.py`
- 行为摘要：任务完成后，系统会判断本次过程是否值得沉淀为长期记忆。

### 28. 如何在开启强制记忆时在清理历史或任务完成前自动触发记忆保存

- 源码依据：`memory_manager.py`
- 行为摘要：启用强制记忆后，在清理历史前或任务结束时会自动尝试执行记忆保存。

### 29. 如何从项目、全局、中心仓库和内置目录加载规则

- 源码依据：`rules_manager.py`
- 行为摘要：规则支持来自多个来源，并会按既定优先级统一纳入可用范围。

### 30. 如何使用带前缀的规则名精确加载 project/global/central/builtin 规则

- 源码依据：`rules_manager.py`
- 行为摘要：规则系统支持通过带来源前缀的名称精确定位并加载指定规则。

### 31. 如何查看规则文件路径、内容预览以及激活状态

- 源码依据：`rules_manager.py`、`builtin_input_handler.py`
- 行为摘要：系统能够展示规则列表、预览内容、来源路径以及是否已激活。

### 32. 如何激活和停用规则

- 源码依据：`rules_manager.py`
- 行为摘要：规则并非只能被动加载，用户还可以在运行过程中调整激活状态。

### 33. 如何在首次运行时自动加载历史类似问题的方法论

- 源码依据：`file_methodology_manager.py`
- 行为摘要：当启用方法论能力时，系统会尝试加载与当前问题相近的历史经验。

### 34. 如何在启用方法论时把历史经验自动追加到当前任务上下文

- 源码依据：`file_methodology_manager.py`
- 行为摘要：加载到的方法论会被附加到当前任务提示中，作为参考执行经验。

### 35. 如何通过统一的用户交互封装切换多行输入与确认实现

- 源码依据：`user_interaction.py`、`__init__.py`
- 行为摘要：系统对多行输入和确认流程做了统一封装，便于在不同交互界面下复用。

### 36. 如何使用 jvsd 直接派发单行任务

- 源码依据：`jvsd_cli.py`
- 行为摘要：`jvsd` 支持直接接收单行任务并快速派发执行，无需进入完整交互流程。

### 37. 如何使用 jvsd 交互输入多行任务并派发到 tmux

- 源码依据：`jvsd_cli.py`
- 行为摘要：当任务内容较长时，`jvsd` 支持交互输入、多行整理，并将任务派发到 tmux 环境执行。

## 风险与写作注意事项

- “模型组切换”不仅有启动参数入口，运行中也可能由内置标记触发，正式文档需区分场景。
- “内置标记”在功能清单中是合并描述，但实际对应多个独立动作，正式文档应拆分清楚。
- “会话恢复”在交互模式与非交互模式下的体验可能不同，正式文档要明确前提条件。
- 本文件仅是第一轮映射草案，后续写正式用户手册前，仍需按功能补读更精确的代码片段与边界行为。
