# CodeAgent 功能映射草案

## 说明

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

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

## 代码来源

### 主要源码文件

- `src/jarvis/jarvis_code_agent/code_agent.py`
- `src/jarvis/jarvis_code_agent/worktree_manager.py`
- `src/jarvis/jarvis_code_agent/code_agent_git.py`
- `src/jarvis/jarvis_code_agent/code_agent_build.py`
- `src/jarvis/jarvis_code_agent/code_agent_lint.py`
- `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_postprocess.py`
- `src/jarvis/jarvis_code_agent/after_change.py`
- `src/jarvis/jarvis_code_agent/jcad_cli.py`

## 功能映射草案

### 1. 如何使用代码代理执行代码分析、修改或生成任务

- 源码依据：`code_agent.py`
- 行为摘要：CodeAgent 作为面向代码任务的专用代理，负责处理代码分析、修改、生成、验证和后续收尾操作。

### 2. 如何让代码代理从任务文件读取任务

- 源码依据：`code_agent.py`
- 行为摘要：支持把任务写入文件后交给 CodeAgent 执行，适合较长或需要复用的任务说明。

### 3. 如何为代码代理临时切换模型组或工具组

- 源码依据：`code_agent.py`
- 行为摘要：支持临时切换模型分组和工具分组，以适配不同复杂度或不同权限范围的代码任务。

### 4. 如何为代码代理追加工具

- 源码依据：`code_agent.py`
- 行为摘要：可在默认工具集之外追加额外工具，让当前任务具备额外操作能力。

### 5. 如何恢复代码代理会话

- 源码依据：`code_agent.py`
- 行为摘要：支持恢复先前的代码任务会话，延续历史上下文与执行状态。

### 6. 如何关闭代码代理自动代码审查

- 源码依据：`code_agent.py`
- 行为摘要：用户可以关闭默认的自动审查流程，只保留修改和基础执行路径。

### 7. 如何设置代码代理审查最大迭代次数

- 源码依据：`code_agent.py`
- 行为摘要：支持控制审查-修复循环的最大轮数，避免任务无限扩展。

### 8. 如何让代码代理在 git worktree 中执行任务

- 源码依据：`code_agent.py`、`worktree_manager.py`
- 行为摘要：支持在独立 worktree 中执行代码任务，降低对主工作区的直接干扰。

### 9. 如何把代码代理任务派发到 tmux 窗口

- 源码依据：`code_agent.py`
- 行为摘要：支持把代码任务派发到 tmux 环境中异步执行，适合长任务或并行处理。

### 10. 如何启用代码代理的系统提示词自动优化

- 源码依据：`code_agent.py`
- 行为摘要：可根据任务场景自动优化系统提示词，使代理行为更贴近当前代码任务目标。

### 11. 如何通过代码代理启用 Web Gateway 服务

- 源码依据：`code_agent.py`
- 行为摘要：运行代码代理时可联动启用 Web Gateway，便于通过 Web 入口接入当前能力。

### 12. 如何使用极速模式快速执行任务

- 源码依据：`code_agent.py`
- 行为摘要：支持使用 `-q` 或 `--quick` 参数启用极速模式，跳过任务分类、规则自动加载、上下文推荐、方法论加载等耗时操作，直接执行用户任务。

### 12. 如何根据用户需求自动推荐相关代码上下文

- 源码依据：`code_agent.py`
- 行为摘要：系统会尝试根据用户任务推荐相关代码上下文，帮助模型更快聚焦关键文件。

### 13. 如何在代码修改后自动展示增强版 diff 预览和按文件补丁摘要

- 源码依据：`code_agent.py`、`code_agent_diff.py`
- 行为摘要：代码变更后可按文件展示差异预览，并根据变更规模选择更适合的展示方式。

### 14. 如何在检测到大量代码删除时自动请大模型判断风险并在必要时撤销修改

- 源码依据：`code_agent.py`
- 行为摘要：当检测到异常大量删除时，系统会触发风险判断，必要时回滚变更以避免误伤代码。

### 15. 如何在代码修改后自动更新代码上下文并生成影响范围分析报告

- 源码依据：`code_agent.py`、`code_agent_impact.py`
- 行为摘要：代码修改后会更新上下文信息，并生成影响范围报告，提示可能受波及的文件、接口与测试。

### 16. 如何在高风险编辑时自动追加风险提示

- 源码依据：`code_agent_impact.py`
- 行为摘要：当影响分析判断为高风险编辑时，系统会补充额外提醒，提示用户重点复核。

### 17. 如何在代码修改后自动执行检查点提交

- 源码依据：`code_agent.py`、`code_agent_git.py`
- 行为摘要：代码修改完成后支持自动形成检查点提交，便于回退和后续比对。

### 18. 如何在提交前确认是否接受自动生成的提交记录

- 源码依据：`code_agent_git.py`
- 行为摘要：系统生成提交记录后，用户仍可决定是否接受，不会强制直接采用。

### 19. 如何在接受提交记录后自动重放并生成规范提交信息

- 源码依据：`code_agent_git.py`
- 行为摘要：接受自动生成记录后，系统会进一步整理提交历史并生成更规范的提交信息。

### 20. 如何在拒绝提交记录后重置到初始提交

- 源码依据：`code_agent_git.py`
- 行为摘要：如果用户拒绝最终提交结果，系统支持回退到起始状态，避免保留不希望的中间改动。

### 21. 如何在代码修改后自动执行构建验证

- 源码依据：`code_agent.py`、`code_agent_build.py`
- 行为摘要：修改完成后可自动尝试构建验证，用于尽早发现编译或构建问题。

### 22. 如何在构建失败时选择禁用构建验证并改做基础静态检查

- 源码依据：`code_agent_build.py`
- 行为摘要：若构建环境不适配或构建持续失败，系统允许改为基础静态检查路线。

### 23. 如何在构建失败时把错误信息转成后续修复提示

- 源码依据：`code_agent_build.py`
- 行为摘要：构建失败后，错误信息会被转为后续修复参考，推动下一轮改动朝正确方向收敛。

### 24. 如何在代码修改后自动执行静态检查并查看自动修复建议

- 源码依据：`code_agent.py`、`code_agent_lint.py`
- 行为摘要：修改后可自动运行静态检查，并根据检查工具生成可能的自动修复建议。

### 25. 如何在代码修改后自动执行格式化或变更后处理

- 源码依据：`code_agent_postprocess.py`、`after_change.py`
- 行为摘要：系统支持在代码变更后自动执行格式化、自动修复或其他自定义后处理命令。

### 26. 如何通过全局或项目级 after_change_tools 配置自定义修改后处理命令

- 源码依据：`after_change.py`
- 行为摘要：用户可通过全局或项目级配置扩展变更后的自动处理规则，使其适应不同项目规范。

### 27. 如何执行多轮代码审查与修复循环

- 源码依据：`code_agent.py`
- 行为摘要：CodeAgent 支持在修改后进入审查-修复循环，逐步提高代码质量。

### 28. 如何在每轮代码审查前手动决定是否继续审查

- 源码依据：`code_agent.py`
- 行为摘要：在多轮审查过程中，用户可以逐轮决定是否继续，而不是被动跑完整个循环。

### 29. 如何在无限模式下持续进行代码审查

- 源码依据：`code_agent.py`
- 行为摘要：支持持续审查模式，让代理在满足条件前持续进行审查与修复。

### 30. 如何在代码审查时自动截断过大的 diff 以适配上下文窗口

- 源码依据：`code_agent.py`
- 行为摘要：对于过大的 diff，系统会自动做裁剪或紧凑展示，以避免超出上下文承载能力。

### 31. 如何在代码审查结果格式错误时自动修复 JSON 格式

- 源码依据：`code_agent.py`
- 行为摘要：审查结果若格式异常，系统会尝试自动修正，减少流程中断。

### 32. 如何在启用 worktree 时自动为主仓库未提交改动创建提交

- 源码依据：`worktree_manager.py`
- 行为摘要：在创建 worktree 前，若主仓库仍有未提交改动，系统会先尝试自动提交，确保主仓库状态干净。

### 33. 如何在启用 worktree 时为无提交仓库自动创建初始提交

- 源码依据：`worktree_manager.py`
- 行为摘要：若仓库尚无提交记录，系统会先补齐初始提交，再继续创建 worktree。

### 34. 如何在启用 worktree 时自动创建独立分支和工作目录

- 源码依据：`worktree_manager.py`
- 行为摘要：启用 worktree 时，系统会为任务生成独立分支名和独立工作目录。

### 35. 如何在 worktree 中共享运行时 .jarvis 数据但隔离规则文件

- 源码依据：`worktree_manager.py`
- 行为摘要：worktree 模式下会共享部分运行时数据，同时对规则等易冲突内容做隔离处理。

### 36. 如何自动更新 .gitignore 以补充默认忽略规则

- 源码依据：`code_agent_git.py`
- 行为摘要：进入 Git 环境初始化时，系统会补充默认忽略规则，减少无意义文件进入版本控制。

### 37. 如何自动调整 Git 换行符配置以减少无意义 diff

- 源码依据：`code_agent_git.py`
- 行为摘要：系统会调整换行符相关设置，降低因平台差异引发的大量无效 diff。

### 38. 如何在 Windows 上为代码仓库创建最小化 .gitattributes

- 源码依据：`code_agent_git.py`
- 行为摘要：在 Windows 环境中，系统可帮助生成最小化的 `.gitattributes` 配置，改善跨平台换行符行为。

### 39. 如何使用 jcad 直接派发代码任务

- 源码依据：`jcad_cli.py`
- 行为摘要：`jcad` 支持直接接收代码任务并快速派发执行，适合快速启动一次性任务。

### 40. 如何使用 jcad 交互输入多行代码任务并派发到 tmux

- 源码依据：`jcad_cli.py`
- 行为摘要：当任务较长时，`jcad` 支持交互输入多行内容，并将任务派发到 tmux 中运行。

## 风险与写作注意事项

- CodeAgent 功能数量应以 40 项为准，不能沿用之前错误的 39 项统计。
- `code_agent.py` 是多数能力的主入口，但正式文档不能只写“主入口文件”，而应补充用户侧前置条件与结果表现。
- 会话恢复、提交确认、构建验证、审查循环等功能都包含条件分支，正式文档要区分“默认情况”“关闭情况”“失败情况”。
- Web Gateway、worktree、tmux 派发等能力通常带有环境前提，正式文档需补充适用场景和准备条件。
- 本文件仅是第一轮映射草案，后续写正式用户手册前，仍需按功能补读更精确的代码片段与边界行为。
