98 lines
3.8 KiB
Markdown
98 lines
3.8 KiB
Markdown
# 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 等）
|
||
|
||
## 执行步骤
|
||
|
||
1. **确认命令名**：从用户输入中提取目标命令名（如 `ls`、`find`）。若用户未指定，可用 ask_user 询问。
|
||
2. **收集资料**（可选）：若对命令不熟悉，可运行 `man <命令> | col -b | head -200` 或 `info <命令>` 获取权威信息；也可用 `run_command` 执行 `命令 --help` 查看选项。
|
||
3. **生成手册内容**：按以下固定结构编写 Markdown 手册：
|
||
|
||
### 手册结构（8 个章节）
|
||
|
||
```
|
||
# <命令> 命令技术手册
|
||
|
||
## 1. 名称（NAME）
|
||
<命令> — 一句话功能说明
|
||
|
||
## 2. 语法（SYNOPSIS）
|
||
```bash
|
||
<命令> [选项]... [参数]...
|
||
```
|
||
给出标准调用形式，说明缺省参数时的行为。
|
||
|
||
## 3. 描述（DESCRIPTION）
|
||
命令的功能、工作原理、关键特性（3-6 条要点，可用列表）。
|
||
|
||
## 4. 选项（OPTIONS）
|
||
分类列出所有常用与关键选项（至少 20 个），每个选项格式：
|
||
#### `-x, --long-option`
|
||
作用说明（一句话）。
|
||
|
||
```bash
|
||
<命令> -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 手册并重点展示示例章节
|