# 专项能力功能映射草案

> 说明：本文档用于把“功能清单\_分类版”中的专项能力条目，映射到源码中可确认的用户可见行为，作为后续正式用户手册拆分的依据。
>
> 取证原则：仅记录能从源码、内置专家定义或规则文件中直接确认的行为；避免暴露实现细节、内部函数名和调用链；后续正式文档需改写为纯用户视角。

## 本分类范围

- 安全扫描配置与执行
- C→Rust 迁移配置、流水线与验证
- 内置专家：架构图生成、代码反向设计、开源部署、脚本生成、重构检查、安全漏洞分析
- 内置人格规则切换

## 取证来源

- `src/jarvis/jarvis_sec/cli.py`
- `src/jarvis/jarvis_c2rust/cli.py`
- `src/jarvis/jarvis_agent/rules_manager.py`
- `builtin/agent/architecture-diagram-generator.yaml`
- `builtin/rules/architecture_design/architecture-diagram-generation.md`
- `builtin/agent/code-reverse-design-expert.yaml`
- `builtin/rules/architecture_design/reverse_engineering.md`
- `builtin/agent/opensource-deployment-expert.yaml`
- `builtin/rules/deployment/opensource-deployment.md`
- `builtin/agent/script-generator.yaml`
- `builtin/rules/development_tools/script-generation.md`
- `builtin/agent/refactor_checker.yaml`
- `builtin/rules/code_quality/refactor-checker.md`
- `builtin/agent/security_vulnerability_analyst.yaml`
- `builtin/rules/security/vulnerability-analysis.md`
- `builtin/rules/agent_personality/jarvis.md`
- `builtin/rules/agent_personality/professional.md`

## 功能映射

### 1. 如何配置、查看或清空安全扫描配置

- 对应清单：`如何配置、查看或清空安全扫描配置`
- 用户入口：`jsec config`
- 可确认的用户可见能力：
  - 可设置扫描目标，支持文件路径或目录路径。
  - 可设置语言过滤、排除目录、输出格式、输出文件。
  - 可设置分析参数，如聚类限制、是否启用二次验证、是否启用强制记忆。
  - 可设置运行时模型组。
  - 可查看当前配置文件内容。
  - 可将配置清空并恢复为默认值。
- 用户侧关键输入：
  - `--target`
  - `--languages`
  - `--exclude-dirs`
  - `--output-format`
  - `--output-file`
  - `--cluster-limit`
  - `--enable-verification/--no-verification`
  - `--force-save-memory/--no-force-save-memory`
  - `--llm-group`
  - `--show`
  - `--clear`
- 可预期结果：
  - 配置写入 `.jarvis/jsec/config.json`。
  - 修改后会回显当前配置内容。
  - 清空后会输出默认配置。
- 注意事项：
  - 未提供有效修改参数时，只会提示用户补充参数。
  - 输出格式仅支持 `csv` 或 `markdown`。

### 2. 如何从外部 JSON 文件分析安全问题

- 对应清单：`如何从外部 JSON 文件分析安全问题`
- 用户入口：`jsec analyze <input>`
- 可确认的用户可见能力：
  - 支持从外部 JSON 文件读取安全问题列表并进行分析。
  - 兼容标准问题格式，也支持对非标准格式进行自动转换后分析。
  - 可指定输出格式、输出文件、聚类限制、是否启用二次验证、是否强制记忆。
- 用户侧关键输入：
  - 位置参数：输入 JSON 文件
  - `--output-format`
  - `--output-file`
  - `--cluster-limit`
  - `--enable-verification/--no-verification`
  - `--force-save-memory/--no-force-save-memory`
- 可预期结果：
  - 成功时直接输出分析结果，或将报告保存到指定文件。
  - 输入文件不存在、分析失败或出现未知错误时，会给出明确错误提示并退出。
- 注意事项：
  - 如果未指定输出文件，结果会直接显示在终端。
  - 二次验证默认启用。

### 3. 如何执行基于配置文件的安全扫描

- 对应清单：`如何执行基于配置文件的安全扫描`
- 用户入口：`jsec scan`
- 可确认的用户可见能力：
  - 从 `.jarvis/jsec/config.json` 读取完整扫描配置后执行扫描。
  - 支持扫描目录，也支持只针对单个文件输出该文件的问题结果。
  - 可根据配置自动切换 Markdown 或 CSV 输出。
  - 当主扫描流程无法产出结果时，会回退到直接扫描模式继续生成报告。
  - 可将报告写入指定输出文件，同时在终端输出内容。
- 用户侧关键输入：
  - 无额外参数，完全依赖已保存配置。
- 可预期结果：
  - 若配置文件不存在，会提示先执行配置命令。
  - 若目标是文件，会先扫描所在目录，再过滤为该文件的问题。
  - 输出文件后缀会按输出格式自动调整。
- 注意事项：
  - 首次使用前需要先执行 `jsec config`。
  - 文件目标不存在时会退回按当前目录扫描。

### 4. 如何配置、查看或清空 C→Rust 迁移设置

- 对应清单：`如何配置、查看或清空 C→Rust 迁移设置`
- 用户入口：`jarvis-c2rust config`
- 可确认的用户可见能力：
  - 可维护根符号列表、禁用库列表、附加说明、FFI 导出验证开关。
  - 可从头文件、源文件中自动提取函数名作为根符号。
  - 可从文本文件按行导入根符号。
  - 可直接在命令行中以逗号分隔方式录入根符号。
  - 可查看当前配置内容，或清空配置恢复默认值。
- 用户侧关键输入：
  - `--files`
  - `--root-list-syms`
  - `--disabled-libs`
  - `--additional-notes`
  - `--enable-ffi-export-validation/--disable-ffi-export-validation`
  - `--show`
  - `--clear`
- 可预期结果：
  - 配置写入 `.jarvis/c2rust/config.json`。
  - 从头文件提取成功时会提示提取数量。
  - 根符号列表会自动去重。
- 注意事项：
  - 非源码/头文件输入只接受 `.txt` 作为符号列表文件。
  - 附加说明支持清空。

### 5. 如何执行 C→Rust 迁移流水线

- 对应清单：`如何执行 C→Rust 迁移流水线`
- 用户入口：`jarvis-c2rust run`
- 可确认的用户可见能力：
  - 以固定顺序执行迁移流水线：扫描、库替换、准备、转译、优化。
  - 支持断点续跑：已完成阶段会被识别并跳过。
  - 可指定模型组，用于涉及智能分析的阶段。
  - 可指定最大重试次数，用于转译后的构建修复与审查循环。
  - 可切换交互或非交互模式。
  - 优化阶段会输出结果摘要，如扫描文件数、清理情况、文档补充和检查次数。
- 用户侧关键输入：
  - `--llm-group`
  - `--max-retries`
  - `--interactive`
- 可预期结果：
  - 每个阶段都会输出开始、完成或跳过状态。
  - 流水线状态会写入 `.jarvis/c2rust/run_state.json`，用于后续续跑。
  - 全部阶段完成后会给出整体完成提示。
- 注意事项：
  - 根符号、禁用库和附加说明来自配置文件，不在 `run` 命令中直接录入。
  - 优化阶段只有在判定真正完成后才会被标记为已完成。

### 6. 如何重置并从头执行 C→Rust 迁移流水线

- 对应清单：`如何重置并从头执行 C→Rust 迁移流水线`
- 用户入口：`jarvis-c2rust run --reset`
- 可确认的用户可见能力：
  - 可清除已有流水线阶段状态，从头重新执行整个迁移流程。
  - 重置后不会复用原有阶段完成标记。
- 用户侧关键输入：
  - `--reset`
- 可预期结果：
  - 旧的阶段状态文件会被删除。
  - 后续阶段从扫描开始重新执行。
- 注意事项：
  - 重置针对的是阶段进度，不等于自动恢复用户代码或外部产物。

### 7. 如何验证转译后的 Rust 与原 C 的功能对齐

- 对应清单：`如何验证转译后的 Rust 与原 C 的功能对齐`
- 用户入口：`jarvis-c2rust verify`
- 可确认的用户可见能力：
  - 在迁移完成后，对转译结果与原始代码进行功能对齐验证。
  - 验证内容包括接口、类型、逻辑、边界情况、错误处理和内存安全等方面。
  - 若验证发现不一致，可进入迭代优化，直到没有问题或达到最大迭代次数。
  - 支持交互或非交互模式。
- 用户侧关键输入：
  - `--llm-group`
  - `--max-iterations`
  - `--interactive`
- 可预期结果：
  - 成功时输出验证过程结果。
  - 出错时会显示明确错误提示并退出。
- 注意事项：
  - 必须先完成 `jarvis-c2rust run` 才适合执行验证。
  - 验证过程强调完整性，会对差异进行持续迭代检查。

### 8. 如何使用内置架构图生成专家阅读代码并输出 Graphviz 架构图

- 对应清单：`如何使用内置架构图生成专家阅读代码并输出 Graphviz 架构图`
- 用户入口：通过加载内置专家“架构图生成器”执行相关任务。
- 可确认的用户可见能力：
  - 专家会先明确需要生成的视图类型，例如逻辑视图、实现视图、进程视图、部署视图、用例视图。
  - 会要求完整阅读相关代码后，识别核心组件和关系。
  - 会输出可直接渲染的 Graphviz DOT 图文件。
  - 图中强调抽象职责命名，而不是源码路径或实现细节。
- 可预期结果：
  - 产出 `.dot` 架构图文件。
  - 图表遵循统一布局、配色和分组规范。
- 注意事项：
  - 若需求未说明视图类型，专家会优先澄清。
  - 图中不应直接暴露函数名、文件路径等具体实现名称。

### 9. 如何将架构图渲染为 PNG 图片

- 对应清单：`如何将架构图渲染为 PNG 图片`
- 用户入口：由架构图生成专家配合架构图规则执行渲染。
- 可确认的用户可见能力：
  - 在生成 `.dot` 文件后，会调用 Graphviz `dot` 命令将其渲染为 `.png` 图片。
  - 会向用户反馈生成图片的保存路径。
- 可预期结果：
  - 同时拥有 `.dot` 源文件和 `.png` 图片文件。
- 注意事项：
  - 前提是本地环境可用 `dot` 命令。
  - 渲染失败时通常需要先检查 Graphviz 环境是否安装完整。

### 10. 如何使用内置代码反向设计专家从现有代码提取设计方案

- 对应清单：`如何使用内置代码反向设计专家从现有代码提取设计方案`
- 用户入口：通过加载内置专家“代码反向设计专家”执行相关任务。
- 可确认的用户可见能力：
  - 专家会阅读指定代码，提取架构、模块、数据流、功能点和异常处理方式。
  - 输出内容为详细的设计方案文档，帮助用户理解现有实现并据此开展新实现。
  - 强调功能完整覆盖和语言无关表达。
- 可预期结果：
  - 输出 Markdown 格式设计方案。
  - 可按不同功能拆分到不同文件。
- 注意事项：
  - 输出重点是设计抽象与对齐，不是代码逐行讲解。
  - 方案要求覆盖原有功能，不得遗漏关键能力。

### 11. 如何通过反向工程规则生成项目级架构分析和语言无关设计文档

- 对应清单：`如何通过反向工程规则生成项目级架构分析和语言无关设计文档`
- 用户入口：通过反向工程规则执行项目反构或代码反向设计任务。
- 可确认的用户可见能力：
  - 支持对整个项目进行系统化反构，形成模块清单、依赖关系、数据流和控制流分析。
  - 支持对单个文件或片段提取语言无关的设计方案。
  - 强调完整性、可追溯性、层次化和模块化。
  - 结果可整理为独立模块文档和整体设计文档。
- 可预期结果：
  - 生成架构设计方案、模块说明和整体结构文档。
  - 能为新成员理解项目或跨语言重实现提供依据。
- 注意事项：
  - 需要先明确是“项目反构”还是“代码反向设计”场景。
  - 输出要求尽量避免语言绑定表达。

### 12. 如何使用内置开源部署专家研究官方文档并生成部署步骤

- 对应清单：`如何使用内置开源部署专家研究官方文档并生成部署步骤`
- 用户入口：通过加载内置专家“开源部署专家”执行部署任务。
- 可确认的用户可见能力：
  - 会先了解项目、版本、环境和特殊要求。
  - 会检索官方仓库、README、官方部署文档和社区最佳实践。
  - 会输出清晰、结构化、可执行的部署步骤。
  - 会解释关键配置、验证方式和注意事项。
- 可预期结果：
  - 用户获得面向目标环境的部署方案与执行步骤。
- 注意事项：
  - 强调优先参考官方文档，而不是凭经验直接部署。
  - 若部署中出现问题，会结合社区资料继续排查。

### 13. 如何在部署前自动检查目标环境与依赖要求

- 对应清单：`如何在部署前自动检查目标环境与依赖要求`
- 用户入口：通过开源部署规则执行部署任务时的环境检测阶段。
- 可确认的用户可见能力：
  - 在正式部署前，会检查 Python、Node.js、Go、Rust 等运行环境版本。
  - 会检查是否处于合适的虚拟环境或工具环境中。
  - 会检查操作系统信息、系统依赖、磁盘空间和网络连接。
  - 若环境不满足要求，会给出明确的安装、升级或替代建议。
- 可预期结果：
  - 用户在部署前获得一份环境适配判断和整改建议。
- 注意事项：
  - 规则明确把环境检测作为正式部署前的必要步骤。
  - 对 Python 项目会特别检查 uv 与虚拟环境状态。

### 14. 如何使用内置脚本生成专家生成并保存可执行脚本

- 对应清单：`如何使用内置脚本生成专家生成并保存可执行脚本`
- 用户入口：通过加载内置专家“脚本生成专家”执行脚本任务。
- 可确认的用户可见能力：
  - 会先明确需求、运行环境、输入输出和保存路径。
  - 会选择合适的脚本语言并设计脚本结构。
  - 会生成完整、可运行的脚本并保存到指定文件。
  - 支持根据反馈继续优化脚本。
- 可预期结果：
  - 生成脚本代码文件。
  - 同时输出脚本内容和说明文档摘要。
- 注意事项：
  - 需求不清晰时会先澄清。
  - 强调脚本应可维护、可执行，并包含错误处理。

### 15. 如何为生成的脚本附带使用说明、参数说明和测试方法

- 对应清单：`如何为生成的脚本附带使用说明、参数说明和测试方法`
- 用户入口：通过脚本生成专家和脚本生成规则共同约束输出。
- 可确认的用户可见能力：
  - 脚本交付时要求附带使用说明、参数说明、调用示例和测试方法。
  - 要求解释关键代码段的功能和可能出现的错误及处理方式。
  - 支持生成面向交付的完整脚本文档。
- 可预期结果：
  - 用户不仅获得脚本文件，也获得配套说明材料。
- 注意事项：
  - 文档完整性被规则明确要求，不能只交付脚本不交付说明。

### 16. 如何使用内置重构检查专家验证重构前后逻辑是否一致

- 对应清单：`如何使用内置重构检查专家验证重构前后逻辑是否一致`
- 用户入口：通过加载内置专家“重构检查专家”执行检查任务。
- 可确认的用户可见能力：
  - 用户提供仓库中的提交号后，专家会基于该版本内容检查重构后逻辑。
  - 如有需要，还会读取代码上下文辅助判断。
  - 最终给出“逻辑一致”或“不一致”的分析结论。
- 可预期结果：
  - 输出一致性检查结果和分析依据。
- 注意事项：
  - 输入的关键前提是可访问的提交号。
  - 目标是校验逻辑一致性，不仅仅是比较文本差异。

### 17. 如何通过 commit 对比检查重构后的代码逻辑一致性

- 对应清单：`如何通过 commit 对比检查重构后的代码逻辑一致性`
- 用户入口：重构检查规则或专家执行时，基于提交号读取代码变更。
- 可确认的用户可见能力：
  - 支持通过指定 commit 查看重构后的代码内容。
  - 在对比后给出是否与原逻辑一致的结论。
- 可预期结果：
  - 形成基于提交版本的重构检查结论。
- 注意事项：
  - 这类能力依赖仓库历史可访问。
  - 结果关注功能与逻辑，而非单纯代码风格变化。

### 18. 如何使用内置安全漏洞分析师进行代码漏洞分析并生成报告

- 对应清单：`如何使用内置安全漏洞分析师进行代码漏洞分析并生成报告`
- 用户入口：通过加载内置专家“安全漏洞分析师”执行任务。
- 可确认的用户可见能力：
  - 会先阅读代码并理解整体架构、模块和数据流。
  - 会从输入处理、认证授权、会话管理、不安全 API 使用、逻辑缺陷等角度分析问题。
  - 会输出完整漏洞分析报告。
  - 报告包含问题位置、问题描述、严重程度、触发场景、影响和修复建议。
- 可预期结果：
  - 生成清晰的安全分析报告文件，推荐使用 Markdown。
- 注意事项：
  - 分析要求基于证据，不允许无依据猜测。
  - 对复杂任务，规则要求合理拆分分析任务。

### 19. 如何结合代码阅读与 Web 搜索查询已知漏洞或 CVE 信息

- 对应清单：`如何结合代码阅读与 Web 搜索查询已知漏洞或 CVE 信息`
- 用户入口：通过安全漏洞分析师和漏洞分析规则执行任务。
- 可确认的用户可见能力：
  - 在完成代码阅读后，会结合 Web 搜索查询已知库漏洞或 CVE 信息。
  - 可将第三方依赖风险纳入整体安全评估。
- 可预期结果：
  - 报告不仅覆盖本地代码问题，也覆盖已知安全情报相关风险。
- 注意事项：
  - Web 搜索是辅助验证手段，前提仍是先理解代码与依赖关系。

### 20. 如何通过内置人格规则切换不同的对话风格

- 对应清单：`如何通过内置人格规则切换不同的对话风格`
- 用户入口：通过规则系统加载人格规则，如 `jarvis` 或 `professional`。
- 可确认的用户可见能力：
  - 支持切换到“Jarvis 风格”，表现为英式绅士、专业高效、强调数据和风险提醒。
  - 支持切换到“专业严谨”风格，表现为正式、结构化、强调规范、风险和可验证性。
  - 人格规则会改变回复语气、表达方式、风险提示方式和建议呈现方式。
- 可预期结果：
  - 同一任务在不同人格规则下，会以不同风格输出分析与建议。
- 注意事项：
  - 这是对交互风格的切换，不等同于改变底层功能能力。

## 可拆分为正式文档的建议文件名

- `安全扫描/配置安全扫描.md`
- `安全扫描/分析外部安全问题_json.md`
- `安全扫描/执行安全扫描.md`
- `c2rust/配置迁移设置.md`
- `c2rust/执行迁移流水线.md`
- `c2rust/重置并重跑迁移流水线.md`
- `c2rust/验证功能对齐.md`
- `架构与设计/生成_graphviz_架构图.md`
- `架构与设计/渲染架构图_png.md`
- `架构与设计/从代码提取设计方案.md`
- `架构与设计/生成项目级反向工程文档.md`
- `部署与脚本/研究官方文档并生成部署步骤.md`
- `部署与脚本/部署前环境与依赖检查.md`
- `部署与脚本/生成并保存脚本.md`
- `部署与脚本/脚本使用说明与测试方法.md`
- `质量与安全/验证重构逻辑一致性.md`
- `质量与安全/通过_commit_检查重构一致性.md`
- `质量与安全/代码漏洞分析并生成报告.md`
- `质量与安全/查询已知漏洞与_cve.md`
- `交互风格/切换不同对话风格.md`

## 草案阶段复核结论

- 本分类功能点已覆盖功能清单中的专项能力条目。
- 目前内容是“源码到用户能力”的映射草案，不是最终用户手册正文。
- 正式文档阶段仍需统一改写为：使用场景、操作步骤、效果、注意事项四段式结构，并去除源码路径呈现。
