aaihubhub
← 文章库
Claude Code 小白进阶课：从第一次对话到可靠协作 · 第 17 课 / 共 20 课 ↗ AI 教程

17｜CLI 自动化：打印模式、结构化输出与脚本

把 Claude Code 接入管道、JSON 输出和可重复脚本。

kimi
LESSON BRIEFING17 / 20

把 Claude Code 接入管道、JSON 输出和可重复脚本。

验证像验房：图纸正确不代表水龙头真的出水。单元测试回答局部逻辑，构建回答能否组装，浏览器检查回答用户真正看到了什么。

本课交付物

为一个 UI 改动写证据矩阵：需求对应哪项自动测试、哪个构建结果、哪个浏览器操作与截图；至少加入一个失败路径。

会话管理

参数 说明 示例
--session 指定会话名称 claude --session feature-auth
--new-session 强制开启新会话 claude --new-session
--resume-last 恢复最近一次会话 claude --resume-last
--fork-session 从当前会话分叉 claude --fork-session

会话示例

# 继续上一次对话
claude --continue

# 恢复命名会话
claude --resume feature-auth

# 为实验分叉会话
claude --fork-session

# 指定会话 ID
claude --resume 123456789

会话分叉

# 分叉会话尝试不同方案
claude --fork-session "尝试另一种实现"

# 带自定义消息分叉
claude --fork-session --session "experiment-a"

高级特性

参数 说明 示例
--disable-auto-checkpoints 禁用自动 checkpoint claude --disable-auto-checkpoints
--enable-auto-checkpoints 启用自动 checkpoint claude --enable-auto-checkpoints
--interactive 强制交互模式 claude --interactive
--dry-run 仅模拟执行 claude --dry-run "review code"
--unsafe 允许更多自动化操作 claude --unsafe

高级示例

# 限制自主操作
claude --permission-mode plan --model opus "设计并实现认证系统"

# 调试 API 调用
claude --verbose -p "diagnose this issue"

# 启用 IDE 集成
claude --ide "review this diff"

Subagents 配置

参数 说明 示例
--agents 通过 JSON 定义自定义 subagents claude --agents ./agents.json
--agent 指定当前会话使用的 agent claude --agent reviewer

Subagents JSON 格式

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

必填字段：

  • description - 何时使用这个 agent 的自然语言说明
  • prompt - 定义 agent 角色和行为的系统提示词

可选字段：

  • tools - 可用工具数组（如果省略则继承全部工具）
    • 格式：["Read", "Grep", "Glob", "Bash"]
  • model - 使用的模型：sonnet、opus 或 haiku

完整 Agents 示例

{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",
    "tools": ["Read", "Edit", "Bash", "Grep"],
    "model": "opus"
  },
  "documenter": {
    "description": "Documentation specialist for generating guides.",
    "prompt": "You are a technical writer. Create clear, comprehensive documentation.",
    "tools": ["Read", "Write"],
    "model": "haiku"
  }
}

Agents 命令示例

# 直接定义自定义 agent
claude --agents '{
  "security-auditor": {
    "description": "Security specialist for vulnerability analysis",
    "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "opus"
  }
}' "audit this codebase for security issues"

# 从文件加载 agents
claude --agents ./configs/agents.json

# 与其他参数组合
claude --agents ./configs/agents.json --model opus

Subagent 优先级

当同时存在多种 agent 定义时，加载优先级如下：

  1. CLI 定义（--agents 参数）- 当前会话专用
  2. 用户级（~/.claude/agents/）- 所有项目可用
  3. 项目级（.claude/agents/）- 当前项目可用

命令行定义的 agents 会覆盖本次会话里的用户级和项目级 agents。

高价值使用场景

1. CI/CD 集成

claude -p --output-format json "run tests and summarize failures"

2. 管道式脚本处理

# 分析错误日志
cat error.log | claude -p "解释这些错误并给出修复建议"

# 查找访问日志中的模式
cat access.log | claude -p "找出异常流量"

# 分析 git 历史
git log --oneline -20 | claude -p "总结最近的开发方向"

# 审查某个文件
claude -p "review src/app.ts and suggest improvements"

# 生成文档
claude -p "根据 README 生成 API 文档"

# 查找 TODO 并排优先级
rg -n "TODO|FIXME" . | claude -p "按优先级分类这些待办"

3. 多会话工作流

# 启动特性分支会话
claude --session feature-auth

# 之后继续该会话
claude --resume feature-auth

# 分叉尝试另一种方案
claude --fork-session

# 在不同特性会话之间切换
claude --resume feature-auth
claude --resume feature-payment

4. 自定义 agent 配置

# 将 agents 配置保存到文件
cat > agents.json <<'JSON'
{
  "agents": [
    {"name":"reviewer","description":"review code"},
    {"name":"tester","description":"write tests"}
  ]
}
JSON

# 在会话中使用这些 agent
claude --agents ./agents.json --agent reviewer

5. 批处理

# 处理多个文件
find src -name "*.ts" | xargs -I{} claude -p "review {}"

# 批量代码审查
claude -p "review all changes in this branch"

# 为所有模块生成测试
claude -p "generate tests for the modified modules"

6. 安全敏感开发

# 只读安全审计
claude --permission-mode plan -p "audit this repository"

# 阻止危险命令
claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"

# 限制自动化
claude --tools "Read,Grep,Glob" -p "inspect the codebase"

7. JSON API 集成

# 获取结构化分析结果
claude -p --output-format json "analyze this code and return findings"

# 配合 jq 处理
claude -p --output-format json "list functions" | jq '.functions[]'

# 在脚本中使用
result=$(claude -p --output-format json "summarize changes")

jq 解析示例

# 提取特定字段
claude -p --output-format json "analyze repo" | jq '.summary'

# 过滤数组元素
claude -p --output-format json "find bugs" | jq '.bugs[] | select(.severity=="high")'

# 提取多个字段
claude -p --output-format json "analyze" | jq '{summary, risk, recommendations}'

# 转成 CSV
claude -p --output-format json "list files" | jq -r '.files[] | [.name, .size] | @csv'

# 条件处理
claude -p --output-format json "check status" | jq 'if .ok then "pass" else "fail" end'

# 提取嵌套值
claude -p --output-format json "inspect" | jq '.details.metrics.coverage'

# 处理整个数组
claude -p --output-format json "find todos" | jq '.todos | length'

# 转换输出
claude -p --output-format json "review" | jq '{issues: [.issues[] | {file, line, message}]}'

模型

模型选择

# 使用短名称
claude --model sonnet
claude --model opus
claude --model haiku

# 使用 opusplan 别名（Opus 负责规划，Sonnet 负责执行）
claude --model opusplan "design and implement the caching layer"

# 会话中切换快速模式
claude --model haiku --effort low

Effort 级别（Opus 4.6）

# 通过 CLI 参数设置 effort
claude --model opus --effort high "design the architecture"

# 通过 slash command 设置 effort
/effort max

# 通过环境变量设置 effort
CLAUDE_EFFORT=medium claude --model opus

常用环境变量

环境变量 说明
ANTHROPIC_API_KEY API key
CLAUDE_MODEL 默认模型
CLAUDE_EFFORT 默认推理强度
CLAUDE_WORKING_DIRECTORY 默认工作目录
CLAUDE_OUTPUT_FORMAT 默认输出格式
CLAUDE_MCP_CONFIG 默认 MCP 配置

快速参考

最常用命令

# 交互式会话
claude

# 快速提问
claude -p "explain this repo"

# 继续上次对话
claude -c

# 处理某个文件
claude -p "review README.md"

# 为脚本输出 JSON
claude -p --output-format json "list all classes"

参数组合

# 只读审查
claude --permission-mode plan -p "review this codebase"

# 高级模型 + JSON 输出
claude --model opus -p --output-format json "analyze architecture"

# 自定义工作目录 + MCP
claude --working-directory ./backend --mcp-config ./mcp.json

故障排查

找不到命令

  • 确认 claude 已安装并在 PATH 中
  • 重新打开终端
  • 检查是否需要重新登录或更新版本

API Key 问题

  • 检查 ANTHROPIC_API_KEY
  • 确认 key 未过期
  • 检查网络是否可访问 API

找不到会话

  • 确认会话名称或 ID 正确
  • 先运行 claude --list-sessions（如果你的版本支持）
  • 检查当前账号是否一致

输出格式问题

  • 使用 --output-format json 时确保输出可被解析
  • 如果是流式输出，加入 --include-partial-messages

权限被拒绝

  • 检查 --permission-mode
  • 检查 --allowedTools 和 --disallowedTools
  • 如有必要，明确允许所需工具

更多资源

示例 4：安全实现

用户：/plan 为我们的 Web 应用实现完整安全方案

Claude：我来制定一份全面的安全实施计划。

## Web 应用安全实施计划

### 阶段 1：安全审计（第 1 天）
1. 运行自动化安全扫描器（npm audit、Snyk）
2. 检查依赖中的漏洞
3. 核对 OWASP Top 10 合规性
4. 审查认证流程
5. 审查数据处理方式
6. 记录当前的安全缺口

### 阶段 2：认证加固（第 2-3 天）
7. 实现强密码要求
8. 添加密码强度检测器
9. 对登录接口实施限流
10. 在多次失败后锁定账户
11. 实现 2FA（TOTP）
12. 改进会话管理
13. 实现安全的密码重置流程

### 阶段 3：授权与访问控制（第 3-4 天）
14. 实现 RBAC（基于角色的访问控制）
15. 为所有端点添加权限检查
16. 实现最小权限原则
17. 为敏感操作添加审计日志
18. 实现资源级权限

### 阶段 4：数据保护（第 4-5 天）
19. 对敏感字段实施静态加密
20. 确保所有通信都使用 TLS/SSL
21. 实现安全的会话存储
22. 在日志中对 PII 数据做脱敏
23. 实现数据保留策略
24. 添加安全的文件上传处理

### 阶段 5：输入验证与清洗（第 5-6 天）
25. 为所有端点实现输入校验
26. 添加 XSS 防护（Content Security Policy）
27. 实现 SQL 注入防护（参数化查询）
28. 添加 CSRF 防护
29. 实现请求大小限制
30. 添加文件上传类型校验

### 阶段 6：安全头与配置（第 6 天）
31. 添加安全响应头：
    - Strict-Transport-Security
    - X-Content-Type-Options
    - X-Frame-Options
    - X-XSS-Protection
    - Content-Security-Policy
32. 正确配置 CORS
33. 禁用不必要的 HTTP 方法
34. 移除服务器版本头

### 阶段 7：监控与日志（第 7 天）
35. 实现安全事件日志
36. 添加异常检测
37. 搭建入侵检测
38. 实现实时告警
39. 创建安全仪表盘

### 阶段 8：测试与文档（第 8-9 天）
40. 执行渗透测试
41. 运行安全扫描器
42. 测试所有安全功能
43. 编写安全文档
44. 培训团队的安全实践
45. 编写事件响应计划

### 阶段 9：合规与政策（第 10 天）
46. 检查 GDPR 合规性
47. 创建隐私政策
48. 实现数据主体权利支持
49. 添加 cookie 同意机制
50. 编写安全政策文档

**预估时间**：10 天
**风险等级**：严重
**优先级**：高

**安全改进摘要**：
- 认证：7 项增强
- 授权：5 项增强
- 数据保护：6 项增强
- 输入校验：6 项增强
- 基础设施：9 项增强
- 监控：5 项增强

**合规性**：OWASP Top 10、GDPR

**成功标准**：
- 零严重漏洞
- 所有 OWASP Top 10 风险都得到缓解
- 安全评分高于 90/100
- 所有渗透测试问题都已解决

继续吗？（yes/no/modify）

示例 5：性能优化

用户：/plan 优化我们这个很慢的电商网站

Claude：我来制定一份完整的性能优化计划。

## 电商网站性能优化计划

### 阶段 1：性能审计（4 小时）
1. 运行 Lighthouse 审计
2. 分析 Chrome DevTools 性能剖析结果
3. 测量 Core Web Vitals：
   - LCP（Largest Contentful Paint）
   - FID（First Input Delay）
   - CLS（Cumulative Layout Shift）
4. 找出性能瓶颈
5. 创建基线性能指标

**当前指标**：
- LCP：4.2s（目标：<2.5s）
- FID：280ms（目标：<100ms）
- CLS：0.25（目标：<0.1）
- 页面加载：8.3s（目标：<3s）

### 阶段 2：图片优化（6 小时）
6. 将图片转换为 WebP 格式
7. 实现响应式图片
8. 为图片添加懒加载
9. 优化图片大小（压缩）
10. 为图片接入 CDN
11. 添加图片占位符

**预期影响**：加载时间减少 40%

### 阶段 3：代码拆分与懒加载（8 小时）
12. 实现基于路由的代码拆分
13. 懒加载非关键组件
14. 拆分第三方依赖包
15. 优化 chunk 大小
16. 实现动态导入
17. 为关键资源添加预加载

**预期影响**：初始 bundle 体积减少 30%

### 阶段 4：缓存策略（6 小时）
18. 实现浏览器缓存（Cache-Control）
19. 为离线支持添加 service worker
20. 实现 API 响应缓存
21. 为数据库查询添加 Redis 缓存
22. 实现 stale-while-revalidate
23. 配置 CDN 缓存

**预期影响**：API 响应时间减少 50%

### 阶段 5：数据库优化（8 小时）
24. 添加数据库索引
25. 优化慢查询（>100ms）
26. 实现查询结果缓存
27. 添加连接池
28. 在合适地方做反规范化
29. 实现数据库只读副本

**预期影响**：数据库查询时间减少 60%

### 阶段 6：前端优化（10 小时）
30. 最小化并压缩 JavaScript
31. 最小化并压缩 CSS
32. 移除未使用的 CSS（PurgeCSS）
33. 实现关键 CSS
34. 延迟加载非关键 JavaScript
35. 减少 DOM 规模
36. 优化 React 渲染（`memo`、`useMemo`）
37. 为长列表实现虚拟滚动

**预期影响**：JavaScript 执行时间减少 35%

### 阶段 7：网络优化（4 小时）
38. 启用 HTTP/2
39. 实现资源提示（preconnect、prefetch）
40. 减少 HTTP 请求数量
41. 启用 Brotli 压缩
42. 优化第三方脚本

**预期影响**：网络耗时减少 25%

### 阶段 8：监控与测试（4 小时）
43. 搭建性能监控（Datadog/New Relic）
44. 添加真实用户监控（RUM）
45. 制定性能预算
46. 搭建自动化 Lighthouse CI
47. 在真实设备上测试

**预估时间**：50 小时（2 周）

**目标指标**（90 分位）：
- LCP：<2.0s（从 4.2s 降低）✅
- FID：<50ms（从 280ms 降低）✅
- CLS：<0.05（从 0.25 降低）✅
- 页面加载：<2.5s（从 8.3s 降低）✅

**预期收入影响**：
- 每快 100ms，转化率提升 1%
- 目标：缩短 5.8s，约带来 58% 的转化率提升
- 预估额外收入：显著

**优先级顺序**：
1. 图片优化（快速收益）
2. 代码拆分（高影响）
3. 缓存（高影响）
4. 数据库优化（关键）
5. 前端优化（打磨）

是否按此计划继续？（yes/no/modify）

关键要点

计划模式的优势

  1. 清晰：开始前就有明确路线图
  2. 可估算：能给出时间和工作量预估
  3. 风险评估：能尽早发现潜在问题
  4. 优先级排序：任务按合理顺序推进
  5. 可审批：执行前先审阅并确认
  6. 可调整：根据反馈及时修改计划

什么时候使用计划模式

✅ 建议始终使用于：

  • 多日项目
  • 团队协作
  • 关键系统变更
  • 学习新概念
  • 复杂重构

❌ 不建议使用于：

  • 修 bug
  • 小改动
  • 简单查询
  • 快速实验

最佳实践

  1. 审批前仔细审查 计划
  2. 发现问题就修改 计划
  3. 把复杂任务拆细
  4. 给出现实的时间估算
  5. 包含回滚策略
  6. 写明成功标准
  7. 为每个阶段安排测试

本站实战工作台

“代码写完”只是验证的起点

可靠验证有四层：静态检查发现结构错误，测试验证可重复行为，构建验证真实打包，浏览器或运行环境验证用户路径。任何一层都不能代表全部。

先把验收句映射到证据。比如“语言切换保持文章 ID 与查询参数”：单元测试检查 helper，路由集成测试检查 URL，浏览器实际点击确认 SSR、Cookie 与登录状态。截图只能证明当时画面，不能证明刷新后状态。

正常、边界与失败

每个功能至少选择一条成功路径、一个边界和一个失败。文章 Markdown 要验证 H1-H6、列表、引用、表格、代码、图片和链接；同时测试恶意 HTML 不执行、超长代码可横向滚动、空内容显示本地化状态。

避免只测实现

如果测试断言某个内部函数被调用，它可能在重构后失效却没有保护用户行为。优先断言契约：响应 locale、事务回滚、页面可见文本、键盘焦点和路径保持。内部单元测试用于快速定位，不替代契约测试。

记录真正运行的命令

不要写“所有测试通过”，写命令、退出码、数量和时间。构建警告若与本次变化相关，也要处理或解释。浏览器验证记录 URL、视口、操作与观察；不要只保存一张裁掉地址栏的图。

反证练习

暂时破坏实现中一个关键条件，确认对应测试变红；恢复后再变绿。始终为绿但无法抓住故障的测试只是装饰。对缓存、事务和权限这类高风险路径，反证尤其重要。

最终 verification.md 用验收条目作为行，用自动测试、构建、浏览器和限制作为列。缺证据的格子明确写未验证。诚实的证据矩阵比一句“没问题”更接近工程完成。

阅读一次失败报告

选择一条红色测试，不要立刻让 Agent 修复。先要求它说明失败发生在准备、执行还是断言阶段，列出预期值、实际值和最小复现命令。测试环境启动失败与产品行为失败需要不同处理；快照变化也不等于功能错误。只有能把失败定位到被验证的契约，修复才不会变成随机改代码直到变绿。

交付前再运行一次干净环境检查，确认成功不依赖上一次会话留下的进程、缓存或生成文件。可重复性是证据的一部分。