requirement-checker（需求检查员）

🎯 定位

需求文档规范自动检查技能 - AI 驱动 + 智能引导 + 温柔话术 + 建议分级

🚀 快速开始

30 秒开始使用

# 1. 安装技能
clawhub install requirement-checker

# 2. 使用
请检查需求文档

# 3. 查看报告
~/Downloads/requirementReports/

基础用法

⚠️ 重要规则（必须遵守）

🤖 执行方式：默认使用子代理

当用户要求检查需求文档时，必须：

1. ✅ 使用子代理执行（sessions_spawn with runtime="subagent"）
2. ✅ 不要直接用 exec 命令执行
3. ✅ 执行完毕后自动关闭子代理（cleanup: "delete"）

正确示例：

sessions_spawn({
  runtime: "subagent",
  task: """请使用 requirement-checker 技能检查需求文档：
  目录：/Users/lifan/Downloads/requirementDocs/
  请执行：python3 ~/.openclaw/workspace/skills/requirement-checker/scripts/batch_check_ai.py
  """,
  timeoutSeconds: 600,
  cleanup: "delete"
})

错误示例：

# ❌ 不要这样做
python3 check_requirement.py

为什么：

• ✅ 子代理隔离执行环境，不占用主会话资源
• ❌ exec 命令会阻塞主会话，不适合长时间运行

📋 检查内容

13 项规范检查【v2.6 优化】

核心建议（影响理解的关键项）

1. 流程描述

检查点：

• [ ] 是否有业务流程图或流程说明
• [ ] 流程步骤是否清晰
• [ ] 分支流程是否完整

✅ 通过示例：

业务流程：
1. 用户提交订单
2. 系统验证库存
   - 有库存 → 生成订单
   - 无库存 → 提示用户
3. 发送确认邮件

❌ 失败示例：

业务流程：
- 用户下单，然后系统处理

*缺少具体步骤和分支流程*

2. 异常处理

检查点：

• [ ] 异常场景和错误提示是否说明
• [ ] 是否有异常恢复机制

✅ 通过示例：

异常情况：
1. 网络异常：显示"网络连接失败，请检查网络设置"，支持重试
2. 数据异常：显示"数据加载失败，请稍后重试"，记录日志

❌ 失败示例：

异常情况：
- 出错了请联系管理员

*未说明具体错误和处理方式*

完善建议（提升文档质量）

3-8. 其他检查项

9. 系统对接描述 ⭐新增

检查点：

• [ ] 对接方（哪个系统/部门）
• [ ] 对接数据内容（具体字段、数据类型）
• [ ] 对接数据应用（用途、业务场景）
• [ ] 对接频率（实时/定时/批量）
• [ ] 对接方式（API/文件/MQ/数据库）
• [ ] 数据时效性（T+0/T+1/延迟要求）

✅ 通过示例：

系统对接：
- 对接方：核心银行系统（科技部门）
- 对接数据：客户信息（客户号、姓名、身份证号）
- 对接应用：客户身份验证
- 对接频率：实时（T+0）
- 对接方式：REST API

❌ 失败示例：

系统对接：
- 需要和核心系统对接

*缺少具体对接细节*

优化建议（锦上添花）

10-13. 优化检查项

输出内容

• ✅ 具体问题说明（引用原文）
• ✅ 针对性优化建议（温柔话术："如果能...会更完整"）
• ✅ 建议优先级分级（核心/完善/优化）
• ✅ GWT 验收标准自动生成
• ✅ 结论（🌟 质量优秀 / ✅ 通过 / 💡 建议自检 / 🔧 建议完善）
• ✅ 检查概览（按优先级分类显示）
• ✅ 汇总报告（可选）

评分机制【v2.5 更新】

建议分级扣分：

• 核心建议：15 分/项（影响理解的关键内容）
• 完善建议：10 分/项（提升文档质量）
• 优化建议：5 分/项（锦上添花）

质量等级：

• 🌟 质量优秀（≥85 分）：文档完整清晰
• ✅ 通过（70-84 分）：整体不错，有优化空间
• 💡 建议自检（50-69 分）：有核心建议需要确认
• 🔧 建议完善（<50 分）：需要补充核心内容

📚 使用场景

场景 1：检查单个文件

✅ 推荐：

请检查需求文档

*自动使用配置的目录，快速检查*

❌ 不推荐：

请检查 /Users/lifan/Downloads/requirementDocs/product_prd.md

*需要指定完整路径，效率低*

场景 2：批量检查

✅ 推荐：

请检查需求文档，并生成汇总报告

*批量检查 + 汇总报告，一次性完成*

❌ 不推荐：

请检查需求文档
...（等待完成）
请生成汇总报告

*分两步执行，效率低*

场景 3：重新配置

✅ 推荐：

请重新设置检查目录

*智能体引导你重新配置*

❌ 不推荐：

修改 config.json，把 input_dir 改成...

*直接修改配置文件，容易出错*

📁 输出位置

报告默认生成在配置的输出目录：

~/Downloads/requirementReports/
├── 2026-04-08_10-30-00_product_prd.md  # 单个文件检查报告
├── 2026-04-08_10-35-00_order_system.md # 单个文件检查报告
└── 00_汇总报告.md                       # 汇总报告（可选）

⚙️ 配置管理

首次使用

智能体会主动引导你设置：

1. 输入目录 - 需求文档所在目录
2. 输出目录 - 检查报告保存目录

配置后

• ✅ 配置保存到 config.json
• ✅ 下次使用无需重复设置
• ✅ 可随时修改配置

修改配置

请修改 requirement-checker 的输入目录

🔧 API 配置（v2.4 优化）

✨ 自动检测（推荐）

首次运行时自动检测并保存：

检测顺序：

1. 本地缓存（config.json）→ 最快
2. 环境变量 → 通用方案
3. OpenClaw 配置 → 自动扫描所有 provider
4. 引导用户配置 → 简化交互

支持的 Provider（按优先级）：

1. bailian（阿里云百炼，性价比高）⭐
2. moonshot（Kimi，长文本）
3. openai（通用）
4. zhipu（智谱）
5. 其他自定义 provider

手动配置（可选）

如果自动检测失败，可选择：

方式 1：OpenClaw 配置（~/.openclaw/openclaw.json） 方式 2：环境变量（OPENAI_API_KEY, OPENAI_BASE_URL） 方式 3：运行时输入（保存到 config.json）

❓ 常见问题

Q1: 首次使用需要配置什么？

A: 只需配置一次目录：

1. 输入目录（需求文档所在目录）
2. 输出目录（检查报告保存目录）
3. API 配置（自动检测 OpenClaw 配置）

Q2: 检查一个文件需要多久？

A: 通常 30-60 秒，取决于：

• 文档大小（建议 <10MB）
• 网络速度（调用 LLM API）
• 文档复杂度

Q3: 检查报告保存在哪里？

A: 默认保存在：

~/Downloads/requirementReports/
├── 2026-04-08_10-30-00_product_prd.md
├── 2026-04-08_10-35-00_order_system.md
└── 00_汇总报告.md（汇总报告）

Q4: 如何重新配置目录？

A: 说"请重新设置检查目录"，智能体会引导你重新配置。

Q5: 支持哪些文档格式？

A: 支持：

• ✅ Markdown (.md)
• ✅ Word (.docx) - 使用 MarkItDown 优先解析，格式保留更好
• ✅ PDF (.pdf) - 使用 MarkItDown 优先解析，格式保留更好
• ✅ 图片 (.jpg/.png) - OCR 识别
• ✅ HTML (.html/.htm)
• ❌ 不支持：Excel、PPT（可以用 MarkItDown 先转 Markdown）

💡 提示：已集成 MarkItDown，Word/PDF 文档转换质量更高，表格/列表格式保留更好。

Q6: 批量检查最多支持多少个文件？

A: 建议每次 ≤50 个文件，过多会导致：

• 检查时间过长（>30 分钟）
• API 调用次数过多
• 汇总报告生成困难

Q7: 温柔话术是什么？

A: 从"挑毛病"变成"建议式"：

• ❌ "这里缺少流程图"
• ✅ "如果能添加业务流程图，会更清晰完整"

Q8: 如何查看历史检查报告？

A: 直接查看输出目录：

cd ~/Downloads/requirementReports/
ls -lt  # 按时间排序

📊 版本历史

🔧 技术实现

环境要求

• Python: >= 3.7（必需）
• requests: >= 2.28.0（必需，HTTP 请求库）

安装

自动安装（推荐）

技能安装后会自动检测并安装依赖：

# ClawHub 安装
clawhub install requirement-checker

# 或手动安装
tar -xzf requirement-checker.tar.gz -C ~/.openclaw/skills/
cd ~/.openclaw/skills/requirement-checker
npm run postinstall  # 触发依赖安装

手动安装

如果自动安装失败，可手动安装依赖：

# 安装 Python 依赖
pip3 install --break-system-packages requests

# 或使用 requirements.txt
pip3 install -r requirements.txt

验证安装

# 验证 requests 库
python3 -c "import requests; print(requests.__version__)"

# 环境检测
cd ~/.openclaw/skills/requirement-checker/scripts
python3 check_environment.py

依赖说明

💡 推荐安装 MarkItDown：

pipx install markitdown  # 全局安装
# 或
pip install 'markitdown[all]'  # 带所有依赖

安装 MarkItDown 后，Word/PDF 文档转换质量更高，表格/列表格式保留更好。

*Last Updated: 2026-04-22 15:01 (v2.8.0 已发布)*