tech-manual - 生成Linux命令中文技术手册的技能（输入命令名，输出完整Markdown手册）

用途

当用户需要了解某个 Linux 命令的用法时，本技能指导智能体生成该命令的完整中文技术手册（Markdown 格式），涵盖语法、全部常用选项、环境变量、退出状态、实战示例和相关命令，内容基于 GNU coreutils / man pages 官方文档，准确实用。

适用场景

用户问："帮我看看 xx 命令怎么用"
用户说："生成 xx 命令的技术手册"
用户问："xx 命令有哪些选项/参数"
用户想深入学习某个命令（ls、find、grep、tar、awk、sed、du、df、ps、top、netstat、ss 等）

执行步骤

确认命令名：从用户输入中提取目标命令名（如 ls、find）。若用户未指定，可用 ask_user 询问。
收集资料（可选）：若对命令不熟悉，可运行 man <命令> | col -b | head -200 或 info <命令> 获取权威信息；也可用 run_command 执行 命令 --help 查看选项。
生成手册内容：按以下固定结构编写 Markdown 手册：

手册结构（8 个章节）

# <命令> 命令技术手册

## 1. 名称（NAME）
<命令> — 一句话功能说明

## 2. 语法（SYNOPSIS）
```bash
<命令> [选项]... [参数]...

给出标准调用形式，说明缺省参数时的行为。

3. 描述（DESCRIPTION）

命令的功能、工作原理、关键特性（3-6 条要点，可用列表）。

4. 选项（OPTIONS）

分类列出所有常用与关键选项（至少 20 个），每个选项格式：

`-x, --long-option`

作用说明（一句话）。

<命令> -x

可选：典型输出示例。

分类建议（按命令特点调整）：

基础选项
排序/过滤选项
输出格式选项
时间/状态选项
长格式字段说明（如 ls -l、ps -ef 的列含义）
权限/特殊位解析（如适用）

5. 环境变量（ENVIRONMENT）

影响该命令行为的环境变量，如 LS_COLORS、COLUMNS、TZ、LANG/LC_* 等。

6. 退出状态（EXIT STATUS）

状态码	含义
0	成功
1	轻微错误（如文件不存在）
2	严重错误（如参数错误）

7. 示例（EXAMPLES）

至少 15 个真实场景示例，按类别分组（日常使用/排序查找/递归/时间/格式/管道脚本/实用技巧），每个示例用 ```bash 代码块并附注释。

8. 相关命令（SEE ALSO）

以表格列出相关命令及其用途。

本文档基于 GNU coreutils/man pages 编写，适用于大多数 Linux 发行版。BSD/macOS 部分选项有差异，以 man 手册为准。


4. **写入文件**：将手册写入工作区文件 `~/.aibox/workspace/<命令名>_manual.md`。
   - 内容较长时**分多次追加写入**（每次 200-400 行），避免 heredoc 超限。
   - 写入后校验：`wc -l <文件>` 和 `grep -E "^#{1,3} " <文件>` 检查行数和章节完整性。
5. **汇报结果**：告知用户文件路径、总行数、章节概览，并询问是否需要进一步操作（如安装为技能、补充其他命令）。

## 注意事项

- 内容必须**准确**，基于 GNU coreutils / 官方 man pages，不要臆造选项。
- 代码示例统一用 ` ```bash ` 代码块。
- 若命令是 shell 内建（如 cd、echo）或非 coreutils 命令，结构可适当调整，但保持 8 章节框架。
- 写入工作区使用 `~/.aibox/workspace/` 目录，遵守工作目录规范。

## 典型示例

用户："帮我生成 find 命令的技术手册"
→ 执行本技能，输出 `~/.aibox/workspace/find_manual.md`

用户："grep 有哪些常用选项？"
→ 执行本技能，生成 grep 手册并重点展示选项章节

用户："看看 tar 命令怎么打包解压"
→ 执行本技能，生成 tar 手册并重点展示示例章节

3.8 KiB Raw Permalink Blame History Unescape Escape