shell/README.md

# Shell Utilities

本模块旨在提供一套极致精简、高性能且符合 POSIX 语义的终端与 Shell 基础设施。它不仅是简单的命令执行包装，更提供了流式实时回调、上下文管理及命令链式执行能力。

## 核心设计哲学

- **语义对齐**: 针对 Shell 交互行为（如 `|` 管道，`&&` 短路逻辑）进行语义一致性实现。
- **安全优先**: 默认支持进程组管理 (`pgid`)，确保中断信号能精准传播至整个命令链条，避免产生僵尸进程。
- **内存透明**: 通过 `bytes.Buffer` 和流式 IO 接口管理大规模输出，避免内存溢出风险。

## API 指南

### 终端渲染 (Color)

用于生成符合终端 ANSI 标准的样式字符串。

- **`Style(a ...any) string`**: 核心渲染引擎。自动合并样式常量与内容，并处理 Windows 系统下的兼容性（剥离样式）。
- **颜色定义**:
  - 前景色: `TextBlack`, `TextRed`, `TextGreen`, `TextYellow`, `TextBlue`, `TextMagenta`, `TextCyan`, `TextWhite`
  - 背景色: `BgBlack`, `BgRed`, `BgGreen`, `BgYellow`, `BgBlue`, `BgMagenta`, `BgCyan`, `BgWhite`
  - 属性: `Reset`, `Bold`, `Dim`, `Italic`, `Underline`, `Blink`, `Reverse`, `Hidden`
- **高阶快捷函数**: 
  - 颜色快捷调用: `Red("error")`, `Green("success")` 等。
  - 背景色快捷调用（B开头）: `BRed("fatal")` (带白色前景色)。

### 命令执行 (Run)

#### 数据结构
- **`Options`**: 配置执行行为
  - `Env []string`: 环境变量增量
  - `Stdin io.Reader`: 自定义输入源
  - `CatchSignal bool`: 是否开启信号捕获，确保进程树生命周期一致
  - `Timeout time.Duration`: 执行超时限制
  - `Dir string`: 设置工作目录
  - `Verbose bool`: 是否开启详细执行日志（终端高亮输出）
  - `OnStdout func([]byte)`: 实时 stdout 捕获回调
  - `OnStderr func([]byte)`: 实时 stderr 捕获回调

- **`CommandResult`**: 命令执行反馈
  - `Stdout []byte`: 标准输出内容
  - `Stderr []byte`: 标准错误输出内容
  - `ExitCode int`: 进程退出码（0 成功，非 0 失败）
  - `ProcessErr error`: 执行层面的错误信息

#### 函数接口
- **`Run(name string, args []string, opts *Options) (*CommandResult, error)`**: 基础执行。
- **`RunCommand(command string, opts *Options) (*CommandResult, error)`**: 支持解析 `|` 管道与 `&&` 短路逻辑的复合命令执行。
- **`Pipeline(commands [][]string, opts *Options) (*CommandResult, error)`**: 执行多命令并行管道，高性能 IO 传输。

## 使用示例

```go
// 1. 带超时和实时回调的执行
res, err := shell.Run("grep", []string{"pattern", "file.log"}, &shell.Options{
    Timeout: 5 * time.Second,
    OnStdout: func(data []byte) { fmt.Printf("Output: %s", data) },
})

// 2. 管道与短路逻辑组合
res, err := shell.RunCommand("cat file.txt | grep 'foo' && echo 'found'", nil)
```

## 测试与质量保证
请参考 [TEST.md](./TEST.md) 获取覆盖率与 Benchmark 数据。