ssci-subagent-skills 1.0.0

package/skills/pubscholar-auto-search/scripts/test_pubscholar_search.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+PubScholar自动搜索技能 - 测试脚本
+
+测试场景：
+1. 基本搜索功能
+2. 精准搜索模式
+3. 智能扩展功能
+4. 结果导出功能
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+# 添加技能路径
+skill_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(skill_dir))
+
+from scripts.pubscholar_searcher import PubScholarSearcher, SynchronousPubScholarSearcher
+
+
+def print_section(title: str):
+    """打印分隔线"""
+    print(f"\n{'='*60}")
+    print(f"  {title}")
+    print('='*60)
+
+
+async def test_basic_search():
+    """测试1: 基本搜索功能"""
+    print_section("测试1: 基本搜索功能")
+
+    async with PubScholarSearcher(debug=True, headless=False) as searcher:
+        keyword = "数字鸿沟"
+        print(f"\n搜索关键词: '{keyword}'")
+
+        results = await searcher.search(keyword)
+
+        print(f"\n✓ 搜索完成，找到 {len(results)} 篇文献")
+
+        # 显示前3篇
+        print("\n前3篇文献:")
+        for i, paper in enumerate(results[:3], 1):
+            print(f"\n{i}. {paper['title']}")
+            print(f"   作者: socienceAI.com
+            print(f"   期刊: {paper['journal']} ({paper['year']})")
+
+        return len(results) > 0
+
+
+async def test_precise_search():
+    """测试2: 精准搜索（不扩展）"""
+    print_section("测试2: 精准搜索模式")
+
+    async with PubScholarSearcher(debug=True) as searcher:
+        keyword = "社会网络分析 在线社区"
+        print(f"\n搜索关键词: '{keyword}'")
+        print("模式: 精准搜索（禁用扩展）")
+
+        results = await searcher.search(keyword, auto_expand=False)
+
+        print(f"\n✓ 精准搜索返回 {len(results)} 篇文献")
+        print("✓ 未执行扩展搜索")
+
+        return True
+
+
+async def test_smart_expansion():
+    """测试3: 智能扩展功能"""
+    print_section("测试3: 智能扩展功能")
+
+    async with PubScholarSearcher(debug=True) as searcher:
+        # 使用可能结果较少的关键词
+        keyword = "元宇宙 社会学理论"
+        print(f"\n搜索关键词: '{keyword}'")
+        print("模式: 智能扩展（结果<5篇时自动扩展）")
+
+        results = await searcher.search(keyword, min_results=5)
+
+        print(f"\n✓ 智能扩展完成，共获得 {len(results)} 篇文献")
+        print("✓ 自动添加了相关关键词扩展搜索")
+
+        return len(results) >= 5
+
+
+def test_sync_mode():
+    """测试4: 同步模式"""
+    print_section("测试4: 同步模式")
+
+    searcher = SynchronousPubScholarSearcher(debug=True)
+
+    keyword = "机器学习 应用"
+    print(f"\n搜索关键词: '{keyword}'")
+    print("模式: 同步调用")
+
+    results = searcher.search(keyword, max_results=10)
+
+    print(f"\n✓ 同步搜索完成，找到 {len(results)} 篇文献")
+
+    return len(results) > 0
+
+
+async def test_export():
+    """测试5: 结果导出功能"""
+    print_section("测试5: 结果导出")
+
+    async with PubScholarSearcher(debug=False) as searcher:
+        keyword = "人工智能 伦理"
+        print(f"\n搜索关键词: '{keyword}'")
+
+        results = await searcher.search(keyword, max_results=5)
+
+        if not results:
+            print("⚠ 没有搜索结果，跳过导出测试")
+            return False
+
+        # 导出JSON
+        json_file = f"test_results_{keyword.replace(' ', '_')}.json"
+        searcher.export_to_json(results, json_file)
+
+        # 导出CSV
+        csv_file = f"test_results_{keyword.replace(' ', '_')}.csv"
+        searcher.export_to_csv(results, csv_file)
+
+        print(f"\n✓ 结果已导出:")
+        print(f"  - JSON: {json_file}")
+        print(f"  - CSV: {csv_file}")
+
+        return Path(json_file).exists() and Path(csv_file).exists()
+
+
+def test_mock_mode():
+    """测试6: 模拟模式"""
+    print_section("测试6: 模拟模式（无Playwright）")
+
+    # 不启动浏览器，直接使用模拟数据
+    searcher = SynchronousPubScholarSearcher(debug=True)
+
+    keyword = "测试关键词"
+    print(f"\n搜索关键词: '{keyword}'")
+    print("模式: 模拟模式（返回测试数据）")
+
+    results = searcher.search(keyword)
+
+    print(f"\n✓ 模拟模式返回 {len(results)} 篇文献")
+    print("\n模拟数据:")
+    for paper in results:
+        print(f"  - {paper['title']}")
+
+    return True
+
+
+async def run_all_tests():
+    """运行所有测试"""
+    print("\n" + "="*60)
+    print("  PubScholar自动搜索技能 - 测试套件")
+    print("="*60)
+
+    tests = [
+        ("基本搜索功能", test_basic_search),
+        ("精准搜索模式", test_precise_search),
+        ("智能扩展功能", test_smart_expansion),
+        ("同步模式", test_sync_mode),
+        ("结果导出功能", test_export),
+        ("模拟模式", test_mock_mode),
+    ]
+
+    results = {}
+
+    for test_name, test_func in tests:
+        try:
+            if asyncio.iscoroutinefunction(test_func):
+                result = await test_func()
+            else:
+                result = test_func()
+            results[test_name] = "✓ 通过" if result else "✗ 失败"
+        except Exception as e:
+            results[test_name] = f"✗ 错误: {e}"
+            print(f"\n⚠ 测试失败: {e}")
+
+    # 测试总结
+    print_section("测试总结")
+    for test_name, result in results.items():
+        print(f"{test_name:20s} {result}")
+
+    passed = sum(1 for r in results.values() if "✓" in r)
+    total = len(results)
+
+    print(f"\n总计: {passed}/{total} 测试通过")
+
+    return passed == total
+
+
+if __name__ == "__main__":
+    # 运行测试
+    success = asyncio.run(run_all_tests())
+
+    if success:
+        print("\n✓ 所有测试通过！")
+        sys.exit(0)
+    else:
+        print("\n⚠ 部分测试失败，请检查")
+        sys.exit(1)

package/skills/research-design/DEPENDENCY_MANAGEMENT.md

@@ -0,0 +1,112 @@
+# 研究设计技能 - 依赖管理文档
+
+## 依赖管理策略
+
+本技能使用 `uv` 作为首选依赖管理工具，以确保依赖管理的一致性和效率。
+
+## 核心依赖
+
+### 必需依赖
+- `pandas>=1.5.0,<3.0.0`
+  - 用途：数据处理和分析
+  - 版本范围：确保与Python 3.8+兼容
+- `numpy>=1.21.0,<2.0.0`
+  - 用途：数值计算
+  - 版本范围：确保与pandas兼容
+
+### 可选依赖 (开发用)
+- `pytest>=7.0.0`
+  - 用途：测试框架
+- `black>=22.0.0`
+  - 用途：代码格式化
+- `mypy>=0.950`
+  - 用途：类型检查
+
+## 依赖管理命令
+
+### 安装依赖
+```bash
+# 安装所有依赖（包括可选依赖）
+uv sync
+
+# 仅安装运行时依赖
+uv sync --no-dev
+
+# 安装特定依赖
+uv add package_name
+```
+
+### 更新依赖
+```bash
+# 更新所有依赖到兼容版本
+uv sync --upgrade
+
+# 更新特定依赖
+uv add --upgrade package_name
+```
+
+### 虚拟环境管理
+```bash
+# 创建虚拟环境
+uv venv
+
+# 激活虚拟环境
+source .venv/bin/activate  # Unix/macOS
+.venv\Scripts\Activate.ps1  # Windows
+
+# 在虚拟环境中运行脚本
+uv run python script.py
+```
+
+## 依赖策略说明
+
+### 最小依赖原则
+我们遵循最小依赖原则，只包含必要的库：
+- 使用标准库尽可能多地实现功能
+- 仅在需要高级数据处理时才引入pandas和numpy
+- 避免不必要的依赖以减少安全风险
+
+### 版本控制
+- 使用保守的版本范围（如 `<3.0.0`）
+- 定期检查依赖更新
+- 确保向前兼容性
+
+### 替代方案考虑
+对于每个依赖，我们都考虑了是否有标准库的替代方案：
+- pandas/numpy：对于复杂的数据处理和数值计算，标准库无法完全替代
+- 因此，这些依赖被认为是必需的
+
+## 依赖验证
+
+所有依赖都经过验证，确保：
+- 功能必要性：依赖提供的功能无法通过标准库有效实现
+- 安全性：依赖库维护活跃，无已知严重安全漏洞
+- 兼容性：与Python 3.8+和其他依赖兼容
+- 许可证：符合MIT许可证要求
+
+## 依赖更新策略
+
+- 定期（每月）检查依赖更新
+- 在更新前进行完整测试
+- 记录更新原因和影响
+- 保持版本范围的合理性
+
+## 疑难解答
+
+### 常见问题
+1. **依赖冲突**：使用 `uv pip compile` 检查依赖冲突
+2. **安装失败**：检查Python版本是否符合要求
+3. **版本不兼容**：调整版本范围或更新代码
+
+### 性能优化
+- 使用 `.gitignore` 排除不必要的依赖文件
+- 定期清理未使用的依赖
+- 使用 `--no-dev` 标志在生产环境中安装
+
+## 与 agentskills.io 规范的符合性
+
+我们的依赖管理策略完全符合 agentskills.io 规范：
+- 明确定义了必需和可选依赖
+- 使用行业标准的依赖管理工具
+- 遵循最小依赖原则
+- 提供了清晰的安装和使用说明

package/skills/research-design/README.md

@@ -0,0 +1,158 @@
+# 研究设计技能 (Research Design Skill)
+
+## 概述
+
+研究设计技能是一个综合性的研究方法论工具，旨在帮助研究人员从问题定义到设计评估的整个研究设计过程中提供专业指导。该技能结合了定性理论分析与定量计算，确保研究设计的科学性、可行性和伦理性。
+
+## 功能特性
+
+### 1. 文献分析
+- 分析出版趋势和研究主题
+- 识别知识缺口和研究机会
+- 生成文献分析报告
+
+### 2. 方法匹配
+- 基于研究目的匹配最适合的研究方法
+- 评估不同设计的适用性
+- 提供方法选择建议
+
+### 3. 设计评估
+- 评估研究设计的各个方面（科学严谨性、可行性、伦理完整性等）
+- 识别设计中的优势和劣势
+- 提供改进建议
+
+### 4. 综合分析
+- 集成所有分析结果
+- 提供完整的研究设计建议
+- 生成详细的实施计划
+
+## 依赖管理
+
+本技能使用uv进行依赖管理。所有依赖都已在pyproject.toml中明确定义。
+
+### 安装依赖
+```bash
+# 使用uv安装依赖
+uv sync
+```
+
+### 依赖说明
+- **必需依赖**: pandas, numpy (用于数据处理和数值计算)
+- **可选依赖**: pytest, black, mypy (用于开发和测试)
+
+## 使用方法
+
+### 基本用法
+```python
+from scripts.integrated_analysis import IntegratedResearchDesigner
+
+# 创建设计师实例
+designer = IntegratedResearchDesigner()
+
+# 准备文献数据
+literature_data = pd.DataFrame({...})
+
+# 定义研究上下文
+research_context = {
+    'research_topic': '研究主题',
+    'research_purpose': '探索和解释',
+    'target_population': '目标人群',
+    'target_sample_size': 300,
+    'time_constraint': 'medium',
+    'resource_level': 'adequate',
+    'ethical_sensitivity': True,
+    'research_questions': ['研究问题1', '研究问题2']
+}
+
+# 定义设计元素
+design_elements = {
+    'theoretical_framework': '理论框架',
+    'research_hypotheses': ['假设1', '假设2'],
+    'sampling_strategy': '抽样策略',
+    # ... 更多设计元素
+}
+
+# 执行完整分析
+results = designer.execute_complete_analysis(
+    literature_data,
+    research_context,
+    design_elements
+)
+
+# 获取最终推荐
+recommendation = results['final_recommendation']
+```
+
+## 模块说明
+
+### scripts/
+- `literature_analysis.py`: 文献分析模块
+- `method_matching.py`: 方法匹配模块
+- `design_evaluation.py`: 设计评估模块
+- `integrated_analysis.py`: 集成分析模块
+
+### prompts/ - 专业提示词（按需加载）
+- `problem-definition.md`: [问题定义专家提示](./prompts/problem-definition.md) | [详纲](./prompts/problem-definition-outline.md)
+- `method-selection.md`: [方法选择专家提示](./prompts/method-selection.md) | [详纲](./prompts/method-selection-outline.md)
+- `data-planning.md`: [数据计划专家提示](./prompts/data-planning.md) | [详纲](./prompts/data-planning-outline.md)
+- `analysis-strategy.md`: [分析策略专家提示](./prompts/analysis-strategy.md) | [详纲](./prompts/analysis-strategy-outline.md)
+- `ethics-review.md`: [伦理审查专家提示](./prompts/ethics-review.md) | [详纲](./prompts/ethics-review-outline.md)
+
+### references/
+- `methodology.md`: [研究方法论详解](./references/methodology.md) | [详纲](./references/methodology-outline.md)
+- `best-practices.md`: [研究设计最佳实践](./references/best-practices.md) | [详纲](./references/best-practices-outline.md)
+
+### assets/templates/
+- `research_design_template.md`: 研究设计模板
+
+## 渐进式披露架构
+
+### Level 1: 核心元数据 (~100 tokens)
+- **技能**: 研究设计能力
+- **触发**: 需要系统化研究设计时
+- **方法**: 混合方法研究设计
+
+### Level 2: 操作框架 (~500 tokens)
+- **六阶段流程**: 问题定义→文献综述→方法选择→数据计划→分析策略→伦理审查
+- **AI协作**: 定性思考 + 定量计算
+- **智能决策**: 自动调用适当工具
+
+### Level 3: 专业提示词 (按需加载)
+- [问题定义](./prompts/problem-definition.md) | [方法选择](./prompts/method-selection.md) | [数据计划](./prompts/data-planning.md) | [分析策略](./prompts/analysis-strategy.md) | [伦理审查](./prompts/ethics-review.md)
+
+### Level 4: 计算脚本 (直接调用)
+- [文献分析](./scripts/literature_analysis.py) | [方法匹配](./scripts/method_matching.py) | [设计评估](./scripts/design_evaluation.py) | [集成分析](./scripts/integrated_analysis.py)
+
+## 定性定量结合机制
+
+### 定性分析 (AI职责)
+1. **问题构建** - 研究问题定义 [→ 问题定义提示](./prompts/problem-definition.md)
+2. **方法选择** - 研究方法匹配 [→ 方法选择提示](./prompts/method-selection.md)
+3. **数据计划** - 数据收集策略 [→ 数据计划提示](./prompts/data-planning.md)
+4. **分析策略** - 分析计划制定 [→ 分析策略提示](./prompts/analysis-strategy.md)
+5. **伦理审查** - 伦理风险评估 [→ 伦理审查提示](./prompts/ethics-review.md)
+
+### 定量计算 (脚本职责)
+1. **文献分析** - 趋势、主题、知识缺口分析 (`literature_analysis.py`)
+2. **方法匹配** - 研究目的与设计匹配 (`method_matching.py`)
+3. **设计评估** - 质量、可行性、伦理评估 (`design_evaluation.py`)
+4. **集成分析** - 综合分析与推荐 (`integrated_analysis.py`)
+
+## 应用场景
+
+1. **学术研究**: 为学者提供系统的研究设计指导
+2. **政策分析**: 为政策制定者提供实证研究设计
+3. **商业调研**: 为企业提供市场研究设计
+4. **社会调查**: 为社会科学研究提供方法论支持
+
+## 技术特点
+
+- **渐进式披露**: 四层架构，按需加载最小上下文
+- **定性定量结合**: AI负责定性分析，脚本负责定量计算
+- **模块化设计**: 各模块功能独立，便于维护和扩展
+- **健壮性**: 处理各种边界情况和错误，避免运行时警告
+- **依赖管理**: 使用uv进行依赖管理，明确依赖范围
+
+## 许可证
+
+MIT License

package/skills/research-design/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: research-design
+description: 执行研究设计，包括问题定义、方法选择、数据收集计划、分析策略和伦理考虑等
+license: MIT
+compatibility: Python 3.8+
+dependencies:
+  required:
+    - pandas>=1.5.0,<3.0.0
+    - numpy>=1.21.0,<2.0.0
+  optional:
+    - pytest>=7.0.0 (for testing)
+    - black>=22.0.0 (for formatting)
+    - mypy>=0.950 (for type checking)
+dependency-manager: uv
+metadata:
+  domain: research-methodology
+  methodology: mixed-methods
+  complexity: advanced
+  version: 1.0.0
+  integration_type: qualitative_quantitative
+  author: socienceAI.com
+  website: http://agentpsy.com
+allowed-tools: python bash read_file write_file task
+---
+
+# 研究设计技能
+
+## 🧠 渐进式披露架构
+
+### Level 1: 核心元数据 (Token: ~100)
+- **技能**: 研究设计能力
+- **触发**: 需要系统化研究设计时自动激活
+- **方法**: 混合方法研究设计
+
+### Level 2: 操作框架 (Token: ~500)
+- **六阶段流程**: 问题定义→文献综述→方法选择→数据计划→分析策略→伦理审查
+- **AI协作**: 定性思考 + 定量规划
+- **智能决策**: 自动调用适当工具
+
+### Level 3: 专业提示词 (按需加载)
+- [问题定义](./prompts/problem-definition.md) | [方法选择](./prompts/method-selection.md) | [数据计划](./prompts/data-planning.md) | [分析策略](./prompts/analysis-strategy.md) | [伦理审查](./prompts/ethics-review.md)
+
+### Level 4: 计算脚本 (直接调用)
+- [文献分析](./scripts/literature_analysis.py) | [方法匹配](./scripts/method_matching.py) | [设计评估](./scripts/design_evaluation.py) | [集成分析](./scripts/integrated_analysis.py)
+
+## 🔄 定性定量结合机制
+
+### 定性分析 (AI职责)
+1. **问题定义** - 研究问题构建 [→ 问题定义提示](./prompts/problem-definition.md)
+2. **方法选择** - 研究方法匹配 [→ 方法选择提示](./prompts/method-selection.md)
+3. **伦理审查** - 伦理风险评估 [→ 伦理审查提示](./prompts/ethics-review.md)
+
+### 定量规划 (脚本职责)
+1. **样本计算** - 样本量确定 (`sample_size_calculation.py`)
+2. **统计功效** - 效力分析 (`power_analysis.py`)
+3. **设计评估** - 设计质量评估 (`design_evaluation.py`)
+
+## 📋 六阶段分析流程
+
+1. **问题定义** → AI加载[问题定义提示](./prompts/problem-definition.md)进行研究问题构建
+2. **文献综述** → AI结合[文献分析脚本](./scripts/literature_analysis.py)进行理论基础构建
+3. **方法选择** → AI基于研究问题与[方法选择提示](./prompts/method-selection.md)匹配合适方法
+4. **数据计划** → AI使用[数据计划提示](./prompts/data-planning.md)制定数据收集策略
+5. **分析策略** → AI根据数据特征与[分析策略提示](./prompts/analysis-strategy.md)制定分析计划
+6. **伦理审查** → AI基于[伦理审查提示](./prompts/ethics-review.md)进行伦理风险评估
+
+## 📚 参考资源
+
+- [方法论详解](./references/methodology.md) - 研究设计核心概念与步骤
+- [最佳实践](./references/best-practices.md) - 研究设计要点
+- [报告模板](./assets/templates/research_design_template.md) - 设计文档格式
+
+## 🚀 快速开始
+
+```bash
+cd research-design/
+python scripts/integrated_analysis.py
+```
+
+---
+
+**AI职责**: 研究问题构建与方法选择（定性分析） | **脚本职责**: 统计计算与设计评估（定量规划） | **协作机制**: 智能决策引擎