# 工具与效率功能映射草案

> 说明：本草案用于把“工具与效率”分类中的功能点，与当前源码中的用户可见行为建立对应关系，作为后续正式用户手册拆分的依据。
>
> 取证范围：
>
> - `src/jarvis/jarvis_tools/cli/main.py`
> - `src/jarvis/jarvis_git_utils/git_commiter.py`
> - `src/jarvis/jarvis_memory_organizer/memory_organizer.py`
> - `src/jarvis/jarvis_methodology/main.py`
> - `src/jarvis/jarvis_rules_index/cli.py`
> - `src/jarvis/jarvis_smart_shell/main.py`
>
> 编写约束：
>
> - 仅描述用户可见行为与使用方式。
> - 不暴露内部函数名、调用链、对象名等实现细节。
> - 只记录已从源码确认的能力与限制，不补充猜测。

## 分类范围

根据功能清单，本分类聚焦以下能力：

- 查看可用工具、查看单个工具详情、直接调用工具
- 自动生成 Git 提交信息，并支持前缀/后缀
- 长期记忆整理、导出、导入
- 方法论导入、导出、列出、从文本/URL 提取
- 查看规则索引
- 智能 Shell 安装/卸载与自然语言生成命令

---

## 1. 工具系统命令行

### 1.1 列出所有可用工具

- **用户可见行为**：可通过工具系统 CLI 查看当前所有可用工具列表。
- **展示方式**：支持普通列表模式，也支持 JSON 输出。
- **可选能力**：可切换为详细模式，同时显示每个工具的参数结构。
- **效果**：用户可以快速知道系统里有哪些工具可用，以及它们的大致用途。
- **源码依据摘要**：工具 CLI 提供 `list` 命令，可按普通/JSON/详细模式输出注册工具信息。

### 1.2 查看单个工具详情

- **用户可见行为**：可单独查看某个工具的说明、协议版本和完整参数定义。
- **展示方式**：支持可读格式和 JSON 格式。
- **效果**：适合在使用某个工具前先确认它的输入参数和用途。
- **注意事项**：如果工具不存在，会明确提示错误并退出。
- **源码依据摘要**：工具 CLI 提供 `show` 命令，按名称查找工具并输出完整说明。

### 1.3 通过命令行直接调用指定工具

- **用户可见行为**：可在命令行中直接执行某个工具，并传入 JSON 参数或参数文件。
- **支持方式**：
  - 直接用 `--args` 传 JSON
  - 用 `--args-file` 从文件读取 JSON
- **效果**：执行后会显示成功/失败状态，并输出标准输出或错误信息。
- **注意事项**：
  - 参数必须是合法 JSON
  - 缺少必填参数时，会直接提示缺少哪些参数并列出说明
  - 工具不存在时会立即报错
- **源码依据摘要**：工具 CLI 提供 `call` 命令，支持参数校验、文件加载和执行结果展示。

---

## 2. 自动生成 Git 提交信息

### 2.1 为当前变更自动生成提交信息并提交

- **用户可见行为**：可对当前 Git 工作区中的变更自动生成中文提交信息，并直接执行提交。
- **效果**：提交成功后会显示提交哈希和最终提交信息。
- **适用场景**：改动完成后，想快速生成规范化提交说明。
- **源码依据摘要**：Git 提交工具会检查未提交改动、整理暂存内容、调用模型生成提交信息并执行 `git commit`。

### 2.2 没有变更时直接结束

- **用户可见行为**：如果仓库没有未提交更改，工具会直接提示“没有未提交的更改”。
- **效果**：不会生成空提交，也不会继续后续步骤。
- **源码依据摘要**：工具在准备 Git 环境时会先检查是否存在未提交改动。

### 2.3 为提交信息添加前缀

- **用户可见行为**：可为自动生成的提交信息添加前缀。
- **效果**：适合团队约定、环境标记或统一格式化补充。
- **源码依据摘要**：CLI 提供 `--prefix` 参数，生成结果后自动拼接到主题前。

### 2.4 为提交信息添加后缀

- **用户可见行为**：可为自动生成的提交信息追加后缀内容。
- **效果**：适合补充说明、任务编号或额外上下文。
- **源码依据摘要**：CLI 提供 `--suffix` 参数，最终提交消息会在末尾追加后缀文本。

### 2.5 大改动时降级为“按文件列表生成提交信息”

- **用户可见行为**：当变更内容过大、无法直接完整分析时，工具仍会尝试根据修改文件列表生成提交说明。
- **效果**：即使 diff 很大，用户依然可以得到一条自动生成的提交信息，而不是直接失败。
- **注意事项**：在这种模式下，提交信息的细节可能更偏概括性。
- **源码依据摘要**：工具会检查上下文大小，必要时截断 diff 或退化为基于文件列表生成提交信息。

### 2.6 提交失败时恢复暂存区

- **用户可见行为**：如果最终提交失败，工具不会默默结束，而是报错并做一定程度的暂存恢复处理。
- **效果**：降低失败后工作区状态混乱的风险。
- **源码依据摘要**：提交失败时会重置暂存区并尝试恢复之前手动暂存的文件。

### 2.7 指定模型组生成提交信息

- **用户可见行为**：可通过命令行指定模型组，用于覆盖默认配置。
- **效果**：用户可以按自己的模型配置偏好生成提交信息。
- **源码依据摘要**：CLI 提供模型组参数，并在初始化时注入到环境配置中。

---

## 3. 长期记忆整理、导出与导入

### 3.1 整理并合并长期记忆

- **用户可见行为**：可对长期记忆进行整理，把标签高度重叠的记忆合并为更综合的一条新记忆。
- **支持范围**：
  - 项目长期记忆
  - 全局长期记忆
- **效果**：减少冗余记忆，提高长期信息的整洁度与可复用性。
- **源码依据摘要**：记忆整理工具会扫描指定类型记忆，识别标签重叠组，并生成新的合并记忆后删除原始记忆。

### 3.2 预演记忆整理（不实际修改）

- **用户可见行为**：可使用模拟模式，只查看将要合并哪些记忆，而不真正执行。
- **效果**：适合先确认整理结果，再决定是否正式执行。
- **源码依据摘要**：记忆整理命令支持 `--dry-run`，模拟显示待合并分组。

### 3.3 导出记忆到 JSON 文件

- **用户可见行为**：可将长期记忆导出为 JSON 文件，便于备份、迁移或分享。
- **支持范围**：默认可同时导出项目长期记忆和全局长期记忆，也可只导出其中一种。
- **效果**：输出文件中包含记忆内容、标签、类型等基础信息。
- **源码依据摘要**：导出命令支持多种记忆类型参数，并将结果统一写入 JSON 文件。

### 3.4 按标签过滤导出记忆

- **用户可见行为**：导出时可按标签过滤，只导出某些主题相关的记忆。
- **效果**：适合按专题做记忆迁移或清理。
- **源码依据摘要**：导出逻辑支持标签过滤，只保留包含任一指定标签的记忆。

### 3.5 从 JSON 文件导入记忆

- **用户可见行为**：可从导出的 JSON 文件重新导入记忆。
- **效果**：可恢复备份，或把记忆迁移到另一个环境。
- **注意事项**：导入文件必须是记忆列表格式；无法识别类型的记录会被跳过。
- **源码依据摘要**：导入命令读取 JSON 列表，并按记忆类型写回对应目录。

### 3.6 导入时覆盖已存在记忆

- **用户可见行为**：导入时可开启覆盖模式，用于覆盖同 ID 的已有记忆。
- **效果**：适合进行同步或恢复最新版本。
- **源码依据摘要**：导入命令支持 `--overwrite` 参数；未开启时遇到同名记忆会跳过。

### 3.7 处理无效记忆类型或错误文件

- **用户可见行为**：如果用户传入不支持的记忆类型，或导入文件不存在/格式错误，会明确提示失败原因。
- **效果**：用户可以根据提示修正输入，而不是无提示失败。
- **源码依据摘要**：记忆整理、导出、导入命令都包含参数校验和错误提示路径。

---

## 4. 方法论管理

### 4.1 导入方法论文件

- **用户可见行为**：可从 JSON 文件导入方法论。
- **支持作用域**：
  - 全局方法论
  - 项目级方法论
- **效果**：导入时会与现有方法论合并，新的同名内容覆盖旧内容。
- **注意事项**：项目级方法论要求当前处于 Git 仓库中，否则无法定位项目目录。
- **源码依据摘要**：方法论 CLI 的导入命令会根据作用域选择目标目录，并执行合并保存。

### 4.2 导出方法论到 JSON 文件

- **用户可见行为**：可将当前方法论导出为单个 JSON 文件。
- **支持范围**：支持导出全局、项目级或全部方法论。
- **效果**：便于备份、分享或跨环境迁移。
- **源码依据摘要**：导出命令按作用域加载方法论后统一写入目标文件。

### 4.3 列出全部可用方法论

- **用户可见行为**：可列出当前可用的方法论标题清单。
- **支持范围**：支持按全局、项目级或全部查看。
- **效果**：适合先浏览已有方法论，再决定是否调用或维护。
- **源码依据摘要**：列出命令支持多种作用域，并按序号输出问题类型列表。

### 4.4 从文本文件提取方法论

- **用户可见行为**：可把一份文本内容交给系统提炼成结构化方法论，并保存到指定作用域。
- **效果**：能把经验总结、文档、复盘材料转化为可复用方法论。
- **注意事项**：
  - 输出必须能被解析为指定格式
  - 提取失败、格式错误、YAML 解析失败都会明确提示
- **源码依据摘要**：提取命令读取文本后调用模型生成结构化结果，并在解析成功后合并保存。

### 4.5 从 URL 内容提取方法论

- **用户可见行为**：可直接从 URL 内容提取方法论并保存。
- **效果**：适合把网页文章、在线说明或外部经验沉淀为本地方法论。
- **注意事项**：若提取结果格式不符合要求，会提示响应格式无效或 YAML 解析失败。
- **源码依据摘要**：方法论 CLI 提供 `extract-url` 命令，流程与文本提取类似，但输入源为 URL。

### 4.6 项目级方法论依赖 Git 仓库上下文

- **用户可见行为**：当用户尝试使用项目级作用域但当前目录不在 Git 仓库中时，会直接报错。
- **效果**：避免把项目级方法论写入错误位置。
- **源码依据摘要**：方法论命令在 project 作用域下必须先成功定位项目目录。

---

## 5. 规则索引

### 5.1 查看全部可用规则索引

- **用户可见行为**：可通过规则索引 CLI 查看所有可用规则及其描述。
- **输出形式**：
  - 美化后的可读输出
  - JSON 输出
  - 原始输出
- **效果**：帮助用户快速了解系统中有哪些规则可用。
- **源码依据摘要**：规则索引 CLI 提供展示命令，并支持 JSON 与 raw 模式切换。

---

## 6. 智能 Shell（JSS）

### 6.1 为 fish 安装命令未找到处理器

- **用户可见行为**：可为 fish shell 安装“命令未找到”处理器。
- **效果**：当用户输入无法识别的较长命令时，系统会尝试把这段自然语言转换为可执行命令建议。
- **安装后提示**：会提醒用户执行 `source ~/.config/fish/config.fish` 使配置生效。
- **源码依据摘要**：智能 Shell 提供针对 fish 的安装逻辑，并写入配置文件中的标记区块。

### 6.2 为 bash 安装命令未找到处理器

- **用户可见行为**：可为 bash 安装同类处理器。
- **效果**：当出现“命令未找到”时，系统会生成建议命令；交互模式下允许用户先编辑再执行。
- **安装后提示**：会提醒用户执行 `source ~/.bashrc`。
- **源码依据摘要**：安装逻辑会向 `~/.bashrc` 写入专用处理函数，并区分交互/非交互模式。

### 6.3 为 zsh 安装命令未找到处理器

- **用户可见行为**：可为 zsh 安装同类处理器。
- **效果**：当出现“命令未找到”时，可生成建议命令；交互模式下还允许先在编辑器中修改，再决定执行。
- **安装后提示**：会提醒用户执行 `source ~/.zshrc`。
- **源码依据摘要**：安装逻辑会向 `~/.zshrc` 写入处理代码，并支持编辑器介入修改建议命令。

### 6.4 卸载智能 Shell 处理器

- **用户可见行为**：可从 fish、bash、zsh 中卸载之前安装的处理器。
- **效果**：恢复普通 shell 行为，不再自动拦截“命令未找到”。
- **注意事项**：卸载后同样需要重新 source 对应配置文件。
- **源码依据摘要**：卸载逻辑会删除配置文件中标记区块对应的内容，并给出重新加载配置提示。

### 6.5 用自然语言生成 Shell 命令

- **用户可见行为**：可通过命令行直接输入一句自然语言需求，让系统返回对应的 Shell 命令。
- **效果**：适合把“我想做什么”快速转成单行命令。
- **行为特点**：
  - 输出应只包含命令本身
  - 多个命令会用 `&&` 连接
  - 会结合当前路径和当前 shell 上下文进行生成
- **源码依据摘要**：`request` 命令会把用户描述、当前路径和 shell 类型一并交给模型生成命令。

### 6.6 交互式输入自然语言并直接执行命令

- **用户可见行为**：如果不在命令后直接提供请求内容，系统会提示用户输入需求；在这种模式下，生成命令后不仅会显示，还会立即执行。
- **效果**：适合把它当成一个半交互式命令助手使用。
- **注意事项**：直接执行命令意味着用户应确认输入内容和环境安全性。
- **源码依据摘要**：当请求参数为空时，命令会从交互输入读取内容，并在得到建议后执行系统命令。

### 6.7 不支持的 shell 类型会直接报错

- **用户可见行为**：如果安装/卸载时指定了 fish、bash、zsh 以外的 shell，会直接提示不支持。
- **效果**：避免误操作写入未知配置文件。
- **源码依据摘要**：智能 Shell 安装与卸载命令都显式限制 shell 类型范围。

---

## 7. 可直接拆分为正式文档的候选功能点

> 以下条目适合后续拆成独立用户文档（名称仍需与功能清单逐项精确对齐）：

1. 列出所有可用工具
2. 查看单个工具详情
3. 通过命令行直接调用指定工具
4. 自动生成 Git 提交信息
5. 为 Git 提交信息添加前缀
6. 为 Git 提交信息添加后缀
7. 整理并合并长期记忆
8. 导出记忆到 JSON 文件
9. 从 JSON 文件导入记忆
10. 导入方法论文件
11. 导出方法论到 JSON 文件
12. 列出全部方法论
13. 从文本文件提取方法论
14. 从 URL 内容提取方法论
15. 查看全部可用规则索引
16. 为 fish 安装智能 Shell 命令未找到处理器
17. 为 bash 安装智能 Shell 命令未找到处理器
18. 为 zsh 安装智能 Shell 命令未找到处理器
19. 卸载智能 Shell 命令未找到处理器
20. 用自然语言生成 Shell 命令

---

## 8. 正式文档阶段仍需二次核对的点

- Git 提交工具在大改动、超长 diff、空变更等边界场景下的用户文案，应在正式手册中进一步收敛成更容易理解的表述。
- “从 URL 提取方法论”目前源码中以 URL 字符串作为输入内容构造提示；正式文档需再结合实际运行表现核对最终用户体验描述。
- 智能 Shell 在不同 shell 中的交互差异（直接预填、编辑器修改、非交互只打印）适合拆成更细的正式文档。
- 记忆整理中的“标签重叠即自动合并”应在正式文档中用更用户化的表达替代内部判定细节。
