shell-review

Shell 脚本审查

审查 Shell 脚本的正确性、安全性和可移植性。

验证

审查后，运行 shellcheck <script>，验证修复是否解决了已发现的问题。

测试

运行 pytest plugins/pensive/tests/skills/test_shell_review.py -v，验证审查模式。

快速开始

/shell-review path/to/script.sh

适用场景

• CI/CD 流水线脚本
• Git 钩子脚本
• 包装脚本（run-*.sh）
• 构建自动化脚本
• Pre-commit 钩子实现

不适用场景

• 非 Shell 脚本（Python、JS 等）
• 无需审查的单行命令

必需的 TodoWrite 项

1. shell-review:context-mapped
2. shell-review:exit-codes-checked
3. shell-review:portability-checked
4. shell-review:safety-patterns-verified
5. shell-review:structure-checked
6. shell-review:evidence-logged
7. shell-review:findings-verified

工作流

第 1 步：梳理上下文（shell-review:context-mapped）

识别 Shell 脚本：

# Find shell scripts
find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  -name "*.sh" -type f | head -20
# Check shebangs
rg -l "^#!/" scripts/ hooks/ 2>/dev/null | head -10
# fallback: grep -l "^#!/" scripts/ hooks/ 2>/dev/null | head -10

记录：

• 脚本用途和触发上下文
• 集成点（make、pre-commit、CI）
• 预期输入和输出

第 2 步：退出码审查（shell-review:exit-codes-checked）

@include modules/exit-codes.md

第 3 步：可移植性检查（shell-review:portability-checked）

@include modules/portability.md

第 4 步：安全模式（shell-review:safety-patterns-verified）

@include modules/safety-patterns.md

第 5 步：结构模式（shell-review:structure-checked）

@include modules/structure-patterns.md

第 6 步：证据记录（shell-review:evidence-logged）

使用 imbue:proof-of-work 记录发现，并附上文件:行号引用。

总结：

• 严重问题（被屏蔽的失败、安全风险）
• 主要问题（可移植性、可维护性）
• 次要问题（风格、文档）

输出格式

## Summary
Shell script review findings

## Scripts Reviewed
- [list with line counts]

## Exit Code Issues
### [E1] Pipeline masks failure
- Location: script.sh:42
- Anchor: `verbatim source text at file:line`
- Pattern: `cmd | grep` loses exit code
- Fix: Use pipefail or capture separately

## Portability Issues
[cross-platform concerns]

## Safety Issues
[unquoted variables, missing set flags]

## Recommendation
Approve / Approve with actions / Block

验证发现有据可依（shell-review:findings-verified）

将发现写入 .review/findings.json，运行引用验证器 （Skill(imbue:review-core) 第 5 步），并删除验证器拒绝的发现，或将其标记为 UNVERIFIED。

退出标准

• 已验证退出码传递（检查管道是否启用了 pipefail，或是否采用捕获并检查的方式）
• 已记录可移植性问题（标记 #!/bin/sh 脚本中的 Bash 特有语法）
• 已验证安全模式（不使用 echo、变量加花括号、:? 展开、在子 Shell 中使用 cd、不使用 basename/dirname）
• 已验证结构模式（区分库与可执行文件、main 调用、序言、depcheck、shfmt 格式化）
• 已通过 imbue:proof-of-work 记录证据，并附上文件:行号引用
• 每项报告的发现都包含经 citation_verifier.py 确认的 Location 和逐字引用的 Anchor（退出码为 0）；否则，应删除未经验证的发现，或将其标记为 UNVERIFIED