feat: add bilingual support (zh/en) for research skills
- Rename skills/research to skills/research-en (English version) - Add skills/research-zh (Chinese version with SKILL.md structure) - Update README.md with bilingual documentation - Add web-search-agent.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
jilinchen
co-authored by
Claude Opus 4.5
Claude Opus 4.5
parent
92b47e006e
commit
10377e95e2
@@ -1,17 +1,23 @@
|
||||
# Deep Research Skill for Claude Code
|
||||
|
||||
[English](#english) | [中文](#中文)
|
||||
|
||||
---
|
||||
|
||||
## English
|
||||
|
||||
> Inspired by [RhinoInsight: Improving Deep Research through Control Mechanisms for Model Behavior and Context](https://arxiv.org/abs/2511.18743)
|
||||
|
||||
A structured research workflow skill for Claude Code, supporting two-phase research: outline generation (extensible) and deep investigation. Human-in-the-loop design ensures precise control at every stage.
|
||||
|
||||
## Use Cases
|
||||
### Use Cases
|
||||
|
||||
- **Academic Research**: Paper surveys, benchmark reviews, literature analysis
|
||||
- **Technical Research**: Technology comparison, framework evaluation, tool selection
|
||||
- **Market Research**: Competitor analysis, industry trends, product comparison
|
||||
- **Due Diligence**: Company research, investment analysis, risk assessment
|
||||
|
||||
## Commands
|
||||
### Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
@@ -21,85 +27,107 @@ A structured research workflow skill for Claude Code, supporting two-phase resea
|
||||
| `/research/deep` | Deep research each item with parallel agents |
|
||||
| `/research/report` | Generate markdown report from JSON results |
|
||||
|
||||
## Installation
|
||||
### Installation
|
||||
|
||||
Copy the `skills/` folder to your Claude Code directory:
|
||||
Choose your language version:
|
||||
|
||||
```bash
|
||||
cp -r skills/* ~/.claude/skills/
|
||||
# English version
|
||||
cp -r skills/research-en ~/.claude/skills/research
|
||||
|
||||
# Chinese version
|
||||
cp -r skills/research-zh ~/.claude/commands/research
|
||||
```
|
||||
|
||||
## Workflow
|
||||
### Workflow
|
||||
|
||||
### Phase 1: Generate Outline
|
||||
#### Phase 1: Generate Outline
|
||||
```
|
||||
/research <topic>
|
||||
```
|
||||
- Uses model knowledge + web search
|
||||
- Asks for existing field definitions
|
||||
- Creates `{topic}/` directory with separated files
|
||||
|
||||
### Phase 2: Deep Research
|
||||
#### Phase 2: Deep Research
|
||||
```
|
||||
/research/deep
|
||||
```
|
||||
- Reads outline and fields automatically from current directory
|
||||
- Launches parallel agents (5 per batch)
|
||||
- Agents read fields.yaml independently (not passed in prompt)
|
||||
- Outputs structured JSON per item
|
||||
- Supports resume from checkpoint
|
||||
|
||||
### Optional: Expand Outline
|
||||
#### Optional: Expand Outline
|
||||
```
|
||||
/research/add-items # Add more research targets
|
||||
/research/add-fields # Add more field definitions
|
||||
/research/add-items
|
||||
/research/add-fields
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
{topic}/
|
||||
├── outline.yaml # items + execution config
|
||||
├── fields.yaml # field definitions
|
||||
└── results/ # deep research outputs
|
||||
```
|
||||
|
||||
### outline.yaml
|
||||
```yaml
|
||||
topic: "your topic"
|
||||
items:
|
||||
- name: "Item1"
|
||||
source: "source info"
|
||||
execution:
|
||||
batch_size: 5 # parallel agents (default: 5)
|
||||
items_per_agent: 1 # items per agent (default: 1)
|
||||
output_dir: "./results" # output directory (default: ./results)
|
||||
```
|
||||
|
||||
### fields.yaml
|
||||
```yaml
|
||||
basic_info:
|
||||
- name: "field_name"
|
||||
description: "field description"
|
||||
detail_level: "detailed|brief"
|
||||
```
|
||||
|
||||
### Research Result (JSON)
|
||||
Each item outputs a structured JSON file with all defined fields.
|
||||
|
||||
### Phase 3: Generate Report
|
||||
#### Phase 3: Generate Report
|
||||
```
|
||||
/research/report
|
||||
```
|
||||
- Generates Python script to convert JSON to markdown
|
||||
- Creates report with table of contents and anchor links
|
||||
- Skips uncertain fields automatically
|
||||
|
||||
## References
|
||||
---
|
||||
|
||||
## 中文
|
||||
|
||||
> 灵感来源：[RhinoInsight: Improving Deep Research through Control Mechanisms for Model Behavior and Context](https://arxiv.org/abs/2511.18743)
|
||||
|
||||
Claude Code 的结构化调研工作流技能，支持两阶段调研：outline生成（可扩展）和深度调查。人在回路设计确保每个阶段的精确控制。
|
||||
|
||||
### 使用场景
|
||||
|
||||
- **学术研究**：论文综述、benchmark评测、文献分析
|
||||
- **技术研究**：技术对比、框架评估、工具选型
|
||||
- **市场研究**：竞品分析、行业趋势、产品比较
|
||||
- **尽职调查**：公司研究、投资分析、风险评估
|
||||
|
||||
### 命令
|
||||
|
||||
| 命令 | 描述 |
|
||||
|------|------|
|
||||
| `/research` | 生成包含items和fields的调研outline |
|
||||
| `/research/add-items` | 向现有outline添加更多items |
|
||||
| `/research/add-fields` | 向现有outline添加更多fields |
|
||||
| `/research/deep` | 使用并行agents对每个item进行深度调研 |
|
||||
| `/research/report` | 从JSON结果生成markdown报告 |
|
||||
|
||||
### 安装
|
||||
|
||||
选择语言版本：
|
||||
|
||||
```bash
|
||||
# 英文版
|
||||
cp -r skills/research-en ~/.claude/skills/research
|
||||
|
||||
# 中文版
|
||||
cp -r skills/research-zh ~/.claude/commands/research
|
||||
```
|
||||
|
||||
### 工作流
|
||||
|
||||
#### 阶段1：生成Outline
|
||||
```
|
||||
/research <topic>
|
||||
```
|
||||
|
||||
#### 阶段2：深度调研
|
||||
```
|
||||
/research/deep
|
||||
```
|
||||
|
||||
#### 可选：扩展Outline
|
||||
```
|
||||
/research/add-items
|
||||
/research/add-fields
|
||||
```
|
||||
|
||||
#### 阶段3：生成报告
|
||||
```
|
||||
/research/report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References / 参考文献
|
||||
|
||||
- RhinoInsight: Improving Deep Research through Control Mechanisms for Model Behavior and Context
|
||||
|
||||
## License
|
||||
## License / 许可证
|
||||
|
||||
MIT
|
||||
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
allowed-tools: Read, Write, Glob, WebSearch, Task, AskUserQuestion
|
||||
description: 对目标话题进行初步调研，生成调研outline。用于学术调研、benchmark调研、技术选型等场景。
|
||||
---
|
||||
|
||||
# Research Skill - 初步调研
|
||||
|
||||
## 触发方式
|
||||
`/research <topic>`
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Step 1: 模型内部知识生成初步框架
|
||||
基于topic，利用模型已有知识生成：
|
||||
- 该领域的主要研究对象/items列表
|
||||
- 建议的调研字段框架
|
||||
|
||||
输出{step1_output}，使用AskUserQuestion确认：
|
||||
- items列表是否需要增减？
|
||||
- 字段框架是否满足需求？
|
||||
|
||||
### Step 2: Web Search补充
|
||||
使用AskUserQuestion询问时间范围（如：最近6个月、2024年至今、不限）。
|
||||
|
||||
**参数获取**：
|
||||
- `{topic}`: 用户输入的调研话题
|
||||
- `{YYYY-MM-DD}`: 当前日期
|
||||
- `{step1_output}`: Step 1生成的完整输出内容
|
||||
- `{time_range}`: 用户指定的时间范围
|
||||
|
||||
**硬约束**：以下prompt必须严格复述，仅替换{xxx}中的变量，禁止改写结构或措辞。
|
||||
|
||||
启动1个web-search-agent（后台），**Prompt模板**：
|
||||
```python
|
||||
prompt = f"""## 任务
|
||||
调研话题: {topic}
|
||||
当前日期: {YYYY-MM-DD}
|
||||
|
||||
基于以下初步框架，补充最新items和推荐调研字段。
|
||||
|
||||
## 已有框架
|
||||
{step1_output}
|
||||
|
||||
## 目标
|
||||
1. 验证已有items是否遗漏重要对象
|
||||
2. 根据遗漏对象进行补充items
|
||||
3. 继续搜索{topic}相关且{time_range}内的items并补充
|
||||
4. 补充新fields
|
||||
|
||||
## 输出要求
|
||||
直接返回结构化结果（不写文件）：
|
||||
|
||||
### 补充Items
|
||||
- item_name: 简要说明（为什么应该加入）
|
||||
...
|
||||
|
||||
### 推荐补充字段
|
||||
- field_name: 字段描述（为什么需要这个维度）
|
||||
...
|
||||
|
||||
### 信息来源
|
||||
- [来源1](url1)
|
||||
- [来源2](url2)
|
||||
"""
|
||||
```
|
||||
|
||||
**One-shot示例**（假设调研AI Coding发展史）：
|
||||
```
|
||||
## 任务
|
||||
调研话题: AI Coding 发展史
|
||||
当前日期: 2025-12-30
|
||||
|
||||
基于以下初步框架，补充最新items和推荐调研字段。
|
||||
|
||||
## 已有框架
|
||||
### Items列表
|
||||
1. GitHub Copilot: Microsoft/GitHub开发，首个主流AI编程助手
|
||||
2. Cursor: AI-first IDE，基于VSCode
|
||||
...
|
||||
|
||||
### 字段框架
|
||||
- 基本信息: name, release_date, company
|
||||
- 技术特性: underlying_model, context_window
|
||||
...
|
||||
|
||||
## 目标
|
||||
1. 验证已有items是否遗漏重要对象
|
||||
2. 根据遗漏对象进行补充items
|
||||
3. 继续搜索AI Coding 发展史相关且2024年至今内的items并补充
|
||||
4. 补充新fields
|
||||
|
||||
## 输出要求
|
||||
直接返回结构化结果（不写文件）：
|
||||
|
||||
### 补充Items
|
||||
- item_name: 简要说明（为什么应该加入）
|
||||
...
|
||||
|
||||
### 推荐补充字段
|
||||
- field_name: 字段描述（为什么需要这个维度）
|
||||
...
|
||||
|
||||
### 信息来源
|
||||
- [来源1](url1)
|
||||
- [来源2](url2)
|
||||
```
|
||||
|
||||
### Step 3: 询问用户已有字段
|
||||
使用AskUserQuestion询问用户是否有已定义的字段文件，如有则读取并合并。
|
||||
|
||||
### Step 4: 生成Outline（分离文件）
|
||||
合并{step1_output}、{step2_output}和用户已有字段，生成两个文件：
|
||||
|
||||
**outline.yaml**（items + 配置）：
|
||||
- topic: 调研主题
|
||||
- items: 调研对象列表
|
||||
- execution:
|
||||
- batch_size: 并行agent数量（需AskUserQuestion确认）
|
||||
- items_per_agent: 每个agent调研项目数（需AskUserQuestion确认）
|
||||
- output_dir: 结果输出目录（默认./results）
|
||||
|
||||
**fields.yaml**（字段定义）：
|
||||
- 字段分类和定义
|
||||
- 每个字段的name、description、detail_level
|
||||
- detail_level分层：极简 → 简要 → 详细
|
||||
- uncertain: 不确定字段列表（保留字段，deep阶段自动填充）
|
||||
|
||||
### Step 5: 输出并确认
|
||||
- 创建目录: `./{topic_slug}/`
|
||||
- 保存: `outline.yaml` 和 `fields.yaml`
|
||||
- 展示给用户确认
|
||||
|
||||
## 输出路径
|
||||
```
|
||||
{当前工作目录}/{topic_slug}/
|
||||
├── outline.yaml # items列表 + execution配置
|
||||
└── fields.yaml # 字段定义
|
||||
```
|
||||
|
||||
## 后续命令
|
||||
- `/research-add-items` - 补充items
|
||||
- `/research-add-fields` - 补充字段
|
||||
- `/research-deep` - 开始深度调研
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
description: 向现有调研outline补充字段定义。
|
||||
allowed-tools: Bash, Read, Write, Glob, WebSearch, Task, AskUserQuestion
|
||||
---
|
||||
|
||||
# Research Add Fields - 补充调研字段
|
||||
|
||||
## 触发方式
|
||||
`/research-add-fields`
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Step 1: 自动定位Fields文件
|
||||
在当前工作目录查找 `*/fields.yaml` 文件，自动读取现有fields定义。
|
||||
|
||||
### Step 2: 获取补充来源
|
||||
询问用户选择：
|
||||
- **A. 用户直接输入**：用户提供字段名称和描述
|
||||
- **B. Web Search搜索**：启动web-search-agent搜索该领域常用字段
|
||||
|
||||
### Step 3: 展示并确认
|
||||
- 展示建议的新字段列表
|
||||
- 用户确认哪些字段需要添加
|
||||
- 用户指定字段分类和detail_level
|
||||
|
||||
### Step 4: 保存更新
|
||||
将确认的字段追加到fields.yaml，保存文件。
|
||||
|
||||
## 输出
|
||||
更新后的 `{topic}/fields.yaml` 文件（原地修改，需用户确认）
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
description: 向现有调研outline补充items（调研对象）。
|
||||
allowed-tools: Bash, Read, Write, Glob, WebSearch, Task, AskUserQuestion
|
||||
---
|
||||
|
||||
# Research Add Items - 补充调研对象
|
||||
|
||||
## 触发方式
|
||||
`/research-add-items`
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Step 1: 自动定位Outline
|
||||
在当前工作目录查找 `*/outline.yaml` 文件，自动读取。
|
||||
|
||||
### Step 2: 并行获取补充来源
|
||||
同时进行：
|
||||
- **A. 询问用户**：需要补充哪些items？有具体名称吗？
|
||||
- **B. 询问是否需要Web Search**：是否启动agent搜索更多items？
|
||||
|
||||
### Step 3: 合并更新
|
||||
- 将新items追加到outline.yaml
|
||||
- 展示给用户确认
|
||||
- 避免重复
|
||||
- 保存更新后的outline
|
||||
|
||||
## 输出
|
||||
更新后的 `{topic}/outline.yaml` 文件（原地修改）
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
description: 读取调研outline，为每个item启动独立agent进行深度调研。禁用task output。
|
||||
allowed-tools: Bash, Read, Write, Glob, WebSearch, Task
|
||||
---
|
||||
|
||||
# Research Deep - 深度调研
|
||||
|
||||
## 触发方式
|
||||
`/research-deep`
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Step 1: 自动定位Outline
|
||||
在当前工作目录查找 `*/outline.yaml` 文件，读取items列表、execution配置（含items_per_agent）。
|
||||
|
||||
### Step 2: 断点续传检查
|
||||
- 检查output_dir下已完成的JSON文件
|
||||
- 跳过已完成的items
|
||||
|
||||
### Step 3: 分批执行
|
||||
- 按batch_size分批（完成一批需要得到用户同意才可进行下一批）
|
||||
- 每个agent负责items_per_agent个项目
|
||||
- 启动web-search-agent（后台并行，禁用task output）
|
||||
|
||||
**参数获取**：
|
||||
- `{topic}`: outline.yaml中的topic字段
|
||||
- `{item_name}`: item的name字段
|
||||
- `{item_related_info}`: item的完整yaml内容（name + category + description等）
|
||||
- `{output_dir}`: outline.yaml中execution.output_dir（默认./results）
|
||||
- `{fields_path}`: {topic}/fields.yaml的绝对路径
|
||||
- `{output_path}`: {output_dir}/{item_name}.json的绝对路径
|
||||
|
||||
**硬约束**：以下prompt必须严格复述，仅替换{xxx}中的变量，禁止改写结构或措辞。
|
||||
|
||||
**Prompt模板**：
|
||||
```python
|
||||
prompt = f"""## 任务
|
||||
调研 {item_related_info}，输出结构化JSON到 {output_path}
|
||||
|
||||
## 字段定义
|
||||
读取 {fields_path} 获取所有字段定义
|
||||
|
||||
## 输出要求
|
||||
1. 按fields.yaml定义的字段输出JSON
|
||||
2. 不确定的字段值标注[不确定]
|
||||
3. JSON末尾添加uncertain数组，列出所有不确定的字段名
|
||||
4. 所有字段值必须使用中文输出（调研过程可用英文，但最终JSON值为中文）
|
||||
|
||||
## 输出路径
|
||||
{output_path}
|
||||
|
||||
## 验证
|
||||
完成JSON输出后，运行验证脚本确保字段完整覆盖：
|
||||
python ~/.claude/commands/research/validate_json.py -f {fields_path} -j {output_path}
|
||||
验证通过后才算完成任务。
|
||||
"""
|
||||
```
|
||||
|
||||
**One-shot示例**（假设调研GitHub Copilot）：
|
||||
```
|
||||
## 任务
|
||||
调研 name: GitHub Copilot
|
||||
category: 国际产品
|
||||
description: Microsoft/GitHub开发，首个主流AI编程助手，市场份额约40%，输出结构化JSON到 /home/weizhena/AIcoding/aicoding-history/results/GitHub_Copilot.json
|
||||
|
||||
## 字段定义
|
||||
读取 /home/weizhena/AIcoding/aicoding-history/fields.yaml 获取所有字段定义
|
||||
|
||||
## 输出要求
|
||||
1. 按fields.yaml定义的字段输出JSON
|
||||
2. 不确定的字段值标注[不确定]
|
||||
3. JSON末尾添加uncertain数组，列出所有不确定的字段名
|
||||
4. 所有字段值必须使用中文输出（调研过程可用英文，但最终JSON值为中文）
|
||||
|
||||
## 输出路径
|
||||
/home/weizhena/AIcoding/aicoding-history/results/GitHub_Copilot.json
|
||||
|
||||
## 验证
|
||||
完成JSON输出后，运行验证脚本确保字段完整覆盖：
|
||||
python ~/.claude/commands/research/validate_json.py -f /home/weizhena/AIcoding/aicoding-history/fields.yaml -j /home/weizhena/AIcoding/aicoding-history/results/GitHub_Copilot.json
|
||||
验证通过后才算完成任务。
|
||||
```
|
||||
|
||||
### Step 4: 等待与监控
|
||||
- 等待当前批次完成
|
||||
- 启动下一批
|
||||
- 显示进度
|
||||
|
||||
### Step 5: 汇总报告
|
||||
全部完成后输出：
|
||||
- 完成数量
|
||||
- 失败/不确定标记的items
|
||||
- 输出目录
|
||||
|
||||
## Agent配置
|
||||
- 后台执行: 是
|
||||
- Task Output: 禁用（agent完成时有明确输出文件）
|
||||
- 断点续传: 是
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
description: 将deep调研结果汇总为markdown报告，覆盖所有字段，跳过不确定值。
|
||||
allowed-tools: Read, Write, Glob, Bash
|
||||
---
|
||||
|
||||
# Research Report - 汇总报告
|
||||
|
||||
## 触发方式
|
||||
`/research-report`
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Step 1: 定位结果目录
|
||||
在当前工作目录查找 `*/outline.yaml`，读取topic和output_dir配置。
|
||||
|
||||
### Step 2: 扫描可选摘要字段
|
||||
读取所有JSON结果，提取适合在目录中显示的字段（数值型、简短指标），例如：
|
||||
- github_stars
|
||||
- google_scholar_cites
|
||||
- swe_bench_score
|
||||
- user_scale
|
||||
- valuation
|
||||
- release_date
|
||||
|
||||
使用AskUserQuestion询问用户：
|
||||
- 目录中除了item名称外，还需要显示哪些字段？
|
||||
- 提供动态选项列表（基于实际JSON中存在的字段）
|
||||
|
||||
### Step 3: 生成Python转换脚本
|
||||
在 `{topic}/` 目录下生成 `generate_report.py`，脚本要求：
|
||||
- 读取output_dir下所有JSON
|
||||
- 读取fields.yaml获取字段结构
|
||||
- 覆盖每个JSON的所有字段值
|
||||
- 跳过值包含[不确定]的字段
|
||||
- 跳过uncertain数组中列出的字段
|
||||
- 生成markdown报告格式：目录（带锚点跳转+用户选择的摘要字段）+ 详细内容（按字段分类）
|
||||
- 保存到 `{topic}/report.md`
|
||||
|
||||
**目录格式要求**：
|
||||
- 必须包含每一个item
|
||||
- 每个item显示：序号、名称（锚点链接）、用户选择的摘要字段
|
||||
- 示例：`1. [GitHub Copilot](#github-copilot) - Stars: 10k | Score: 85%`
|
||||
|
||||
#### 脚本技术要点（必须遵循）
|
||||
|
||||
**1. JSON结构兼容**
|
||||
支持两种JSON结构：
|
||||
- 扁平结构：字段直接在顶层 `{"name": "xxx", "release_date": "xxx"}`
|
||||
- 嵌套结构：字段在category子dict中 `{"basic_info": {"name": "xxx"}, "technical_features": {...}}`
|
||||
|
||||
字段查找顺序：顶层 -> category映射key -> 遍历所有嵌套dict
|
||||
|
||||
**2. Category多语言映射**
|
||||
fields.yaml的category名与JSON的key可能是任意组合（中中、中英、英中、英英）。必须建立双向映射：
|
||||
```python
|
||||
CATEGORY_MAPPING = {
|
||||
"基本信息": ["basic_info", "基本信息"],
|
||||
"技术特性": ["technical_features", "technical_characteristics", "技术特性"],
|
||||
"性能指标": ["performance_metrics", "performance", "性能指标"],
|
||||
"里程碑意义": ["milestone_significance", "milestones", "里程碑意义"],
|
||||
"商业信息": ["business_info", "commercial_info", "商业信息"],
|
||||
"竞争与生态": ["competition_ecosystem", "competition", "竞争与生态"],
|
||||
"历史沿革": ["history", "历史沿革"],
|
||||
"市场定位": ["market_positioning", "market", "市场定位"],
|
||||
}
|
||||
```
|
||||
|
||||
**3. 复杂值格式化**
|
||||
- list of dicts（如key_events, funding_history）：每个dict格式化为一行，用` | `分隔kv
|
||||
- 普通list：短列表用逗号连接，长列表换行显示
|
||||
- 嵌套dict：递归格式化，用分号或换行显示
|
||||
- 长文本字符串（超过100字符）：添加换行符`<br>`或使用blockquote格式，提高可读性
|
||||
|
||||
**4. 额外字段收集**
|
||||
收集JSON中有但fields.yaml中没定义的字段，放入"其他信息"分类。注意过滤：
|
||||
- 内部字段：`_source_file`, `uncertain`
|
||||
- 嵌套结构顶级key：`basic_info`, `technical_features`等
|
||||
- `uncertain_fields`列表：需要逐行显示每个字段名，不要压缩成一行
|
||||
|
||||
**5. 不确定值跳过**
|
||||
跳过条件：
|
||||
- 字段值包含`[不确定]`字符串
|
||||
- 字段名在`uncertain`数组中
|
||||
- 字段值为None或空字符串
|
||||
|
||||
### Step 4: 执行脚本
|
||||
运行 `python {topic}/generate_report.py`
|
||||
|
||||
## 输出
|
||||
- `{topic}/generate_report.py` - 转换脚本
|
||||
- `{topic}/report.md` - 汇总报告
|
||||
@@ -0,0 +1,219 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
JSON字段验证脚本
|
||||
验证JSON文件是否完整覆盖fields.yaml中定义的所有字段
|
||||
"""
|
||||
|
||||
import json
|
||||
import yaml
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Set, Any, Tuple
|
||||
|
||||
# Category中英文映射
|
||||
CATEGORY_MAPPING = {
|
||||
"基本信息": ["basic_info", "基本信息"],
|
||||
"技术特性": ["technical_features", "technical_characteristics", "技术特性"],
|
||||
"性能指标": ["performance_metrics", "performance", "性能指标"],
|
||||
"里程碑意义": ["milestone_significance", "milestones", "里程碑意义"],
|
||||
"商业信息": ["business_info", "commercial_info", "商业信息"],
|
||||
"竞争与生态": ["competition_ecosystem", "competition", "竞争与生态"],
|
||||
"历史沿革": ["history", "历史沿革"],
|
||||
"市场定位": ["market_positioning", "market", "市场定位"],
|
||||
}
|
||||
|
||||
|
||||
def load_fields_yaml(fields_path: Path) -> Tuple[Set[str], Set[str], Dict[str, str]]:
|
||||
"""
|
||||
加载fields.yaml，返回：
|
||||
- all_fields: 所有字段名集合
|
||||
- required_fields: required=true的字段名集合
|
||||
- field_categories: 字段名到类别的映射
|
||||
"""
|
||||
with open(fields_path, 'r', encoding='utf-8') as f:
|
||||
data = yaml.safe_load(f)
|
||||
|
||||
all_fields = set()
|
||||
required_fields = set()
|
||||
field_categories = {}
|
||||
|
||||
for category_info in data.get("field_categories", []):
|
||||
category_name = category_info["category"]
|
||||
for field in category_info.get("fields", []):
|
||||
field_name = field["name"]
|
||||
all_fields.add(field_name)
|
||||
field_categories[field_name] = category_name
|
||||
if field.get("required", False):
|
||||
required_fields.add(field_name)
|
||||
|
||||
return all_fields, required_fields, field_categories
|
||||
|
||||
|
||||
def extract_json_fields(data: Dict, category_mapping: Dict = None) -> Set[str]:
|
||||
"""
|
||||
从JSON中提取所有字段名（支持扁平和嵌套结构）
|
||||
"""
|
||||
if category_mapping is None:
|
||||
category_mapping = CATEGORY_MAPPING
|
||||
|
||||
# 获取所有可能的嵌套key
|
||||
nested_keys = set()
|
||||
for keys in category_mapping.values():
|
||||
nested_keys.update(keys)
|
||||
|
||||
fields = set()
|
||||
|
||||
def collect_fields(d: Dict, is_top_level: bool = True):
|
||||
for k, v in d.items():
|
||||
# 跳过内部字段
|
||||
if k in {"_source_file", "uncertain"}:
|
||||
continue
|
||||
# 如果是嵌套结构的顶级key，递归进入
|
||||
if is_top_level and k in nested_keys:
|
||||
if isinstance(v, dict):
|
||||
collect_fields(v, is_top_level=False)
|
||||
else:
|
||||
fields.add(k)
|
||||
if isinstance(v, dict):
|
||||
collect_fields(v, is_top_level=False)
|
||||
|
||||
collect_fields(data)
|
||||
return fields
|
||||
|
||||
|
||||
def validate_json(json_path: Path, all_fields: Set[str], required_fields: Set[str],
|
||||
field_categories: Dict[str, str]) -> Dict:
|
||||
"""
|
||||
验证单个JSON文件
|
||||
返回验证结果字典
|
||||
"""
|
||||
with open(json_path, 'r', encoding='utf-8') as f:
|
||||
data = json.load(f)
|
||||
|
||||
json_fields = extract_json_fields(data)
|
||||
|
||||
# 计算覆盖情况
|
||||
covered = all_fields & json_fields
|
||||
missing = all_fields - json_fields
|
||||
extra = json_fields - all_fields
|
||||
|
||||
# 分类缺失字段
|
||||
missing_required = missing & required_fields
|
||||
missing_optional = missing - required_fields
|
||||
|
||||
# 按类别分组缺失字段
|
||||
missing_by_category = {}
|
||||
for field in missing:
|
||||
cat = field_categories.get(field, "未知")
|
||||
if cat not in missing_by_category:
|
||||
missing_by_category[cat] = []
|
||||
missing_by_category[cat].append(field)
|
||||
|
||||
return {
|
||||
"file": json_path.name,
|
||||
"total_defined": len(all_fields),
|
||||
"covered": len(covered),
|
||||
"missing": len(missing),
|
||||
"extra": len(extra),
|
||||
"coverage_rate": len(covered) / len(all_fields) * 100 if all_fields else 100,
|
||||
"missing_required": list(missing_required),
|
||||
"missing_optional": list(missing_optional),
|
||||
"missing_by_category": missing_by_category,
|
||||
"extra_fields": list(extra),
|
||||
"valid": len(missing_required) == 0, # required字段全覆盖则valid
|
||||
}
|
||||
|
||||
|
||||
def print_result(result: Dict, verbose: bool = True):
|
||||
"""打印验证结果"""
|
||||
status = "PASS" if result["valid"] else "FAIL"
|
||||
print(f"\n{'='*60}")
|
||||
print(f"[{status}] {result['file']}")
|
||||
print(f"{'='*60}")
|
||||
print(f"覆盖率: {result['coverage_rate']:.1f}% ({result['covered']}/{result['total_defined']})")
|
||||
|
||||
if result["missing_required"]:
|
||||
print(f"\n[ERROR] 缺失必需字段 ({len(result['missing_required'])}):")
|
||||
for field in result["missing_required"]:
|
||||
print(f" - {field}")
|
||||
|
||||
if verbose and result["missing_optional"]:
|
||||
print(f"\n[WARN] 缺失可选字段 ({len(result['missing_optional'])}):")
|
||||
for cat, fields in result["missing_by_category"].items():
|
||||
optional_fields = [f for f in fields if f not in result["missing_required"]]
|
||||
if optional_fields:
|
||||
print(f" [{cat}]: {', '.join(optional_fields)}")
|
||||
|
||||
if verbose and result["extra_fields"]:
|
||||
print(f"\n[INFO] 额外字段 ({len(result['extra_fields'])}):")
|
||||
print(f" {', '.join(result['extra_fields'][:10])}")
|
||||
if len(result["extra_fields"]) > 10:
|
||||
print(f" ... 及 {len(result['extra_fields']) - 10} 个其他字段")
|
||||
|
||||
|
||||
def main():
|
||||
"""主函数"""
|
||||
import argparse
|
||||
parser = argparse.ArgumentParser(description="验证JSON文件是否覆盖fields.yaml定义的所有字段")
|
||||
parser.add_argument("--fields", "-f", type=str, help="fields.yaml路径", default="fields.yaml")
|
||||
parser.add_argument("--json", "-j", type=str, nargs="*", help="要验证的JSON文件路径")
|
||||
parser.add_argument("--dir", "-d", type=str, help="JSON文件目录", default="results")
|
||||
parser.add_argument("--quiet", "-q", action="store_true", help="只显示摘要")
|
||||
args = parser.parse_args()
|
||||
|
||||
# 定位fields.yaml
|
||||
fields_path = Path(args.fields)
|
||||
if not fields_path.exists():
|
||||
# 尝试在当前目录和父目录查找
|
||||
for p in [Path.cwd() / "fields.yaml", Path.cwd().parent / "fields.yaml"]:
|
||||
if p.exists():
|
||||
fields_path = p
|
||||
break
|
||||
|
||||
if not fields_path.exists():
|
||||
print(f"[ERROR] fields.yaml不存在: {fields_path}")
|
||||
sys.exit(1)
|
||||
|
||||
print(f"字段定义文件: {fields_path}")
|
||||
all_fields, required_fields, field_categories = load_fields_yaml(fields_path)
|
||||
print(f"总字段数: {len(all_fields)} (必需: {len(required_fields)}, 可选: {len(all_fields) - len(required_fields)})")
|
||||
|
||||
# 收集JSON文件
|
||||
json_files = []
|
||||
if args.json:
|
||||
json_files = [Path(p) for p in args.json]
|
||||
else:
|
||||
json_dir = Path(args.dir)
|
||||
if json_dir.exists():
|
||||
json_files = sorted(json_dir.glob("*.json"))
|
||||
|
||||
if not json_files:
|
||||
print(f"[WARN] 未找到JSON文件")
|
||||
sys.exit(0)
|
||||
|
||||
# 验证每个文件
|
||||
results = []
|
||||
for json_path in json_files:
|
||||
if not json_path.exists():
|
||||
print(f"[WARN] 文件不存在: {json_path}")
|
||||
continue
|
||||
result = validate_json(json_path, all_fields, required_fields, field_categories)
|
||||
results.append(result)
|
||||
print_result(result, verbose=not args.quiet)
|
||||
|
||||
# 汇总
|
||||
print(f"\n{'='*60}")
|
||||
print("汇总")
|
||||
print(f"{'='*60}")
|
||||
passed = sum(1 for r in results if r["valid"])
|
||||
avg_coverage = sum(r["coverage_rate"] for r in results) / len(results) if results else 0
|
||||
print(f"验证通过: {passed}/{len(results)}")
|
||||
print(f"平均覆盖率: {avg_coverage:.1f}%")
|
||||
|
||||
if passed < len(results):
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
name: web-search-agent
|
||||
description: Use this agent when you need to research information on the internet, particularly for debugging issues, finding solutions to technical problems, or gathering comprehensive information from multiple sources. This agent excels at finding relevant discussions. Use when you need creative search strategies, thorough investigation of a topic, or compilation of findings from diverse sources.
|
||||
model: opus
|
||||
---
|
||||
|
||||
You are an elite internet researcher specializing in finding relevant information across diverse online sources. Your expertise lies in creative search strategies, thorough investigation, and comprehensive compilation of findings.
|
||||
|
||||
**Core Capabilities:**
|
||||
- You excel at crafting multiple search query variations to uncover hidden gems of information
|
||||
- You systematically explore GitHub issues, Reddit threads, Stack Overflow, technical forums, blog posts, Google Scholar, academic databases, Chinese Technical Sites and documentation
|
||||
- You never settle for surface-level results - you dig deep to find the most relevant and helpful information
|
||||
- You are particularly skilled at debugging assistance, finding others who've encountered similar issues
|
||||
- You understand context and can identify patterns across disparate sources
|
||||
|
||||
**Research Methodology:**
|
||||
|
||||
1. **Query Generation Phase**: When given a topic or problem, you will:
|
||||
- Generate 5-10 different search query variations to maximize coverage
|
||||
- Include technical terms, error messages, library names, and common misspellings
|
||||
- Think of how different people might describe the same issue (novice vs. expert terminology)
|
||||
- Consider searching for both the problem AND potential solutions
|
||||
- Use exact phrases in quotes for error messages
|
||||
- Include version numbers and environment details when relevant
|
||||
- **For bilingual research**: Generate queries in both English and Chinese (中文)
|
||||
- Use Chinese technical terms and common translations (e.g., "报错" for errors, "解决方案" for solutions)
|
||||
- Search Chinese sites with Chinese keywords for better results from Chinese developer communities
|
||||
- **For academic paper discovery**: Use Google Scholar-specific search operators and research databases
|
||||
- Search using author names, paper titles, DOI numbers, and research keywords
|
||||
- Include year ranges to find seminal works and recent publications
|
||||
- Use quotation marks for exact titles and author name combinations
|
||||
- Search related papers and citations to build comprehensive research context
|
||||
|
||||
2. **Source Prioritization**: You will systematically search across:
|
||||
- **GitHub Issues** (both open and closed) - excellent for known bugs and workarounds
|
||||
- **Reddit** (r/programming, r/webdev, r/javascript, and topic-specific subreddits) - real-world experiences
|
||||
- **Stack Overflow** and other Stack Exchange sites - technical Q&A
|
||||
- **Technical forums** and discussion boards - community wisdom
|
||||
- **Official documentation** and changelogs - authoritative information
|
||||
- **Blog posts** and tutorials - detailed explanations
|
||||
- **Hacker News** discussions - high-quality technical discourse
|
||||
- **Chinese Technical Sites**:
|
||||
- **CSDN** (csdn.net) - China's largest IT community with extensive technical articles and solutions
|
||||
- **Juejin** (juejin.cn) - high-quality Chinese developer community with modern tech focus
|
||||
- **SegmentFault** (segmentfault.com) - Chinese Q&A platform similar to Stack Overflow
|
||||
- **Zhihu** (zhihu.com) - Chinese knowledge-sharing platform with technical discussions
|
||||
- **Cnblogs** (cnblogs.com) - Chinese blogging platform with deep technical content
|
||||
- **OSChina** (oschina.net) - Chinese open source community and technical news
|
||||
- **V2EX** (v2ex.com) - Chinese developer community with active discussions
|
||||
- **Tencent Cloud** and **Alibaba Cloud** developer communities - enterprise-level solutions
|
||||
|
||||
3. **Information Gathering Standards**: You will:
|
||||
- Read beyond the first few results - valuable information is often buried
|
||||
- Look for patterns in solutions across different sources
|
||||
- Pay attention to dates to ensure relevance (note if solutions are outdated)
|
||||
- Note different approaches to the same problem and their trade-offs
|
||||
- Identify authoritative sources and experienced contributors
|
||||
- Check for updated solutions or superseded approaches
|
||||
- Verify if issues have been resolved in newer versions
|
||||
|
||||
4. **Compilation Standards**: When presenting findings, you will:
|
||||
- Start with an Executive Summary (key findings in 2-3 sentences)
|
||||
- Organize information by relevance and reliability
|
||||
- Provide direct links to all sources
|
||||
- Include relevant code snippets or configuration examples
|
||||
- Note any conflicting information and explain the differences
|
||||
- Highlight the most promising solutions or approaches
|
||||
- Include timestamps, version numbers, and environment details when relevant
|
||||
- Clearly mark experimental or unverified solutions
|
||||
|
||||
**For Debugging Assistance:**
|
||||
- Search for exact error messages in quotes
|
||||
- Look for issue templates that match the problem pattern
|
||||
- Find workarounds, not just explanations
|
||||
- Check if it's a known bug with existing patches or PRs
|
||||
- Look for similar issues even if not exact matches
|
||||
- Identify if the issue is version-specific
|
||||
- Search for both the library name + error and more general descriptions
|
||||
- Check closed issues for resolution patterns
|
||||
|
||||
**For Comparative Research:**
|
||||
- Create structured comparisons with clear criteria
|
||||
- Find real-world usage examples and case studies
|
||||
- Look for performance benchmarks and user experiences
|
||||
- Identify trade-offs and decision factors
|
||||
- Include both popular opinions and contrarian views
|
||||
- Note adoption trends and community sentiment
|
||||
- Consider scalability, maintenance, and learning curve
|
||||
|
||||
**For Best Practices Research:**
|
||||
- Look for official recommendations first
|
||||
- Cross-reference with community consensus
|
||||
- Find examples from production codebases
|
||||
- Identify anti-patterns and common pitfalls
|
||||
- Note evolving best practices and deprecated approaches
|
||||
|
||||
**For Academic Paper Search:**
|
||||
- Use Google Scholar as primary source with advanced search operators
|
||||
- Search by author names, institutions, and publication years
|
||||
- Look for related papers and citation patterns to identify seminal works
|
||||
- Search for preprints on arXiv, bioRxiv, and institutional repositories
|
||||
- Check author profiles and ResearchGate for publications and PDFs
|
||||
- Identify open-access versions and legal paper download sources
|
||||
- Track citation networks to understand research evolution
|
||||
- Note impact factors, h-index, and citation counts for relevance assessment
|
||||
- Search for conference proceedings, journals, and workshop papers
|
||||
- Identify funding agencies and research grants for context
|
||||
|
||||
**Quality Assurance:**
|
||||
- Verify information across multiple sources when possible
|
||||
- Clearly indicate when information is speculative or unverified
|
||||
- Date-stamp findings to indicate currency
|
||||
- Distinguish between official solutions and community workarounds
|
||||
- Note the credibility of sources (official docs vs. random blog post vs. maintainer comment)
|
||||
- Flag deprecated or outdated information
|
||||
- Highlight security implications if relevant
|
||||
|
||||
**Standard Output Format:**
|
||||
|
||||
```
|
||||
## Executive Summary
|
||||
[Key findings in 2-3 sentences - what you found and the recommended path forward]
|
||||
|
||||
## Detailed Findings
|
||||
[Organized by relevance/approach, with clear headings]
|
||||
|
||||
### [Approach/Solution 1]
|
||||
- Description
|
||||
- Source links
|
||||
- Code examples if applicable
|
||||
- Pros/Cons
|
||||
- Version/environment requirements
|
||||
|
||||
### [Approach/Solution 2]
|
||||
[Same structure]
|
||||
|
||||
## Sources and References
|
||||
1. [Link with description]
|
||||
2. [Link with description]
|
||||
|
||||
## Recommendations
|
||||
[If applicable - your analysis of the best approach based on findings]
|
||||
|
||||
## Additional Notes
|
||||
[Caveats, warnings, areas needing more research, or conflicting information]
|
||||
```
|
||||
|
||||
**Self-Verification:**
|
||||
Before presenting findings, you will ask yourself:
|
||||
- Have I explored enough diverse sources?
|
||||
- Are there any obvious gaps in my research?
|
||||
- Have I verified claims across multiple sources?
|
||||
- Is my information current and relevant?
|
||||
- Have I provided actionable next steps?
|
||||
|
||||
**Escalation Strategy:**
|
||||
If you cannot find sufficient information:
|
||||
- Clearly state what you searched for and where
|
||||
- Explain why results may be limited
|
||||
- Suggest alternative search strategies or related topics
|
||||
- Recommend asking in specific communities if appropriate
|
||||
|
||||
Remember: You are not just a search engine - you are a research specialist who understands context, can identify patterns, and knows how to find information that others might miss. Your goal is to provide comprehensive, actionable intelligence that saves time and provides clarity. Every research task should leave the user better informed and with clear next steps.
|
||||
Reference in New Issue
Block a user