ssci-subagent-skills 1.0.0

package/skills/performing-centrality-analysis/scripts/calculate_centrality.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+中心性计算工具
+
+功能：
+1. 计算度中心性（Degree Centrality）
+2. 计算接近中心性（Closeness Centrality）
+3. 计算中介中心性（Betweenness Centrality）
+4. 计算特征向量中心性（Eigenvector Centrality）
+5. 综合排序和分析
+
+标准化接口：argparse + 三层JSON输出
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Dict
+
+import networkx as nx
+
+
+def load_network(file_path: str) -> nx.Graph:
+    """加载网络数据"""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        
+        # 支持多种格式
+        if 'edges' in data:
+            edges = data['edges']
+        elif 'links' in data:
+            edges = data['links']
+        else:
+            edges = data
+        
+        G = nx.Graph()
+        for edge in edges:
+            source = edge.get('source') or edge.get('from')
+            target = edge.get('target') or edge.get('to')
+            weight = edge.get('weight', 1.0)
+            G.add_edge(source, target, weight=weight)
+        
+        return G
+    
+    except Exception as e:
+        print(f"错误：无法加载网络文件 - {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def calculate_all_centralities(G: nx.Graph) -> Dict:
+    """计算所有中心性指标"""
+    
+    # 度中心性
+    degree_cent = nx.degree_centrality(G)
+    
+    # 接近中心性
+    try:
+        closeness_cent = nx.closeness_centrality(G)
+    except:
+        closeness_cent = {node: 0.0 for node in G.nodes()}
+    
+    # 中介中心性
+    betweenness_cent = nx.betweenness_centrality(G)
+    
+    # 特征向量中心性
+    try:
+        eigenvector_cent = nx.eigenvector_centrality(G, max_iter=1000)
+    except:
+        eigenvector_cent = {node: 0.0 for node in G.nodes()}
+    
+    # 整合结果
+    centralities = {}
+    for node in G.nodes():
+        centralities[node] = {
+            'node': node,
+            'degree': round(degree_cent.get(node, 0), 4),
+            'closeness': round(closeness_cent.get(node, 0), 4),
+            'betweenness': round(betweenness_cent.get(node, 0), 4),
+            'eigenvector': round(eigenvector_cent.get(node, 0), 4)
+        }
+    
+    return centralities
+
+
+def rank_nodes(centralities: Dict, metric: str = 'degree', top_n: int = 10) -> list:
+    """按指定指标排序节点"""
+    sorted_nodes = sorted(
+        centralities.values(),
+        key=lambda x: x[metric],
+        reverse=True
+    )
+    return sorted_nodes[:top_n]
+
+
+def identify_key_nodes(centralities: Dict, thresholds: Dict = None) -> Dict:
+    """识别关键节点"""
+    if thresholds is None:
+        thresholds = {
+            'degree': 0.5,
+            'betweenness': 0.1,
+            'eigenvector': 0.3
+        }
+    
+    hubs = []  # 度中心性高的节点
+    bridges = []  # 中介中心性高的节点
+    influencers = []  # 特征向量中心性高的节点
+    
+    for node, scores in centralities.items():
+        if scores['degree'] >= thresholds['degree']:
+            hubs.append(node)
+        if scores['betweenness'] >= thresholds['betweenness']:
+            bridges.append(node)
+        if scores['eigenvector'] >= thresholds['eigenvector']:
+            influencers.append(node)
+    
+    return {
+        'hubs': hubs,
+        'bridges': bridges,
+        'influencers': influencers
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='中心性计算工具',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+示例用法:
+  python calculate_centrality.py --input network.json
+  python calculate_centrality.py -i network.json -m betweenness --top 20
+  python calculate_centrality.py -i network.json -o centrality.json
+        '''
+    )
+    
+    parser.add_argument('--input', '-i', required=True,
+                       help='输入的网络文件（JSON格式）')
+    parser.add_argument('--output', '-o', default='centrality.json',
+                       help='输出文件名（默认：centrality.json）')
+    parser.add_argument('--metric', '-m', default='degree',
+                       choices=['degree', 'closeness', 'betweenness', 'eigenvector'],
+                       help='排序指标（默认：degree）')
+    parser.add_argument('--top', '-t', type=int, default=10,
+                       help='输出前N个节点（默认：10）')
+    
+    args = parser.parse_args()
+    
+    start_time = datetime.now()
+    
+    # 加载网络
+    G = load_network(args.input)
+    
+    # 计算中心性
+    centralities = calculate_all_centralities(G)
+    
+    # 排序节点
+    top_nodes = rank_nodes(centralities, args.metric, args.top)
+    
+    # 识别关键节点
+    key_nodes = identify_key_nodes(centralities)
+    
+    end_time = datetime.now()
+    processing_time = (end_time - start_time).total_seconds()
+    
+    # 标准化输出
+    output = {
+        'summary': {
+            'total_nodes': G.number_of_nodes(),
+            'total_edges': G.number_of_edges(),
+            'network_density': round(nx.density(G), 4),
+            'top_node': top_nodes[0]['node'] if top_nodes else None,
+            'top_score': top_nodes[0][args.metric] if top_nodes else 0,
+            'hubs_count': len(key_nodes['hubs']),
+            'bridges_count': len(key_nodes['bridges']),
+            'influencers_count': len(key_nodes['influencers']),
+            'processing_time': round(processing_time, 2)
+        },
+        'details': {
+            'centralities': list(centralities.values()),
+            'top_nodes': top_nodes,
+            'key_nodes': key_nodes
+        },
+        'metadata': {
+            'input_file': args.input,
+            'output_file': args.output,
+            'metric_used': args.metric,
+            'timestamp': datetime.now().isoformat(),
+            'version': '1.0.0',
+            'skill': 'performing-centrality-analysis'
+        }
+    }
+    
+    # 写入输出文件
+    try:
+        with open(args.output, 'w', encoding='utf-8') as f:
+            json.dump(output, f, ensure_ascii=False, indent=2)
+        
+        print(f"✓ 中心性计算完成")
+        print(f"  - 节点数：{G.number_of_nodes()}")
+        print(f"  - 边数：{G.number_of_edges()}")
+        print(f"  - 网络密度：{output['summary']['network_density']:.4f}")
+        print(f"  - 最高{args.metric}节点：{output['summary']['top_node']}")
+        print(f"  - 输出文件：{args.output}")
+    
+    except Exception as e:
+        print(f"错误：无法写入输出文件 - {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/skills/performing-centrality-analysis/tests/test_calculate_centrality.py

@@ -0,0 +1,218 @@
+"""
+中心性计算工具的单元测试
+"""
+
+import sys
+from pathlib import Path
+
+# 添加scripts目录到路径
+sys.path.insert(0, str(Path(__file__).parent.parent / 'scripts'))
+
+import networkx as nx
+from calculate_centrality import (
+    calculate_all_centralities,
+    rank_nodes,
+    identify_key_nodes
+)
+
+
+class TestCalculateAllCentralities:
+    """测试中心性计算"""
+    
+    def test_basic_network(self):
+        """测试基本网络的中心性计算"""
+        # 创建简单网络：A-B-C-D（线性）
+        G = nx.Graph()
+        G.add_edges_from([('A', 'B'), ('B', 'C'), ('C', 'D')])
+        
+        centralities = calculate_all_centralities(G)
+        
+        # 验证所有节点都有中心性值
+        assert len(centralities) == 4
+        assert 'A' in centralities
+        
+        # 验证中心性类型
+        assert 'degree' in centralities['A']
+        assert 'closeness' in centralities['A']
+        assert 'betweenness' in centralities['A']
+        assert 'eigenvector' in centralities['A']
+        
+        # B和C应该有最高的介数中心性（在中间）
+        assert centralities['B']['betweenness'] > 0
+        assert centralities['C']['betweenness'] > 0
+    
+    def test_star_network(self):
+        """测试星形网络（中心节点连接所有其他节点）"""
+        G = nx.Graph()
+        G.add_edges_from([('Center', 'A'), ('Center', 'B'), 
+                         ('Center', 'C'), ('Center', 'D')])
+        
+        centralities = calculate_all_centralities(G)
+        
+        # 中心节点应该有最高的度中心性
+        assert centralities['Center']['degree'] == 1.0
+        
+        # 中心节点应该有最高的介数中心性
+        assert centralities['Center']['betweenness'] > centralities['A']['betweenness']
+    
+    def test_complete_network(self):
+        """测试完全网络（所有节点互相连接）"""
+        G = nx.complete_graph(5)
+        
+        centralities = calculate_all_centralities(G)
+        
+        # 在完全网络中，所有节点的中心性应该相等
+        degree_values = [c['degree'] for c in centralities.values()]
+        assert len(set(degree_values)) == 1  # 所有值相同
+        
+        # 度中心性应该是1.0（连接到所有其他节点）
+        assert degree_values[0] == 1.0
+
+
+class TestRankNodes:
+    """测试节点排序"""
+    
+    def test_rank_by_degree(self):
+        """测试按度中心性排序"""
+        centralities = {
+            'A': {'node': 'A', 'degree': 0.8, 'betweenness': 0.3},
+            'B': {'node': 'B', 'degree': 0.5, 'betweenness': 0.7},
+            'C': {'node': 'C', 'degree': 0.9, 'betweenness': 0.2}
+        }
+        
+        result = rank_nodes(centralities, metric='degree', top_n=2)
+        
+        assert len(result) == 2
+        assert result[0]['node'] == 'C'  # 最高度中心性
+        assert result[1]['node'] == 'A'
+    
+    def test_rank_by_betweenness(self):
+        """测试按介数中心性排序"""
+        centralities = {
+            'A': {'node': 'A', 'degree': 0.8, 'betweenness': 0.3},
+            'B': {'node': 'B', 'degree': 0.5, 'betweenness': 0.7},
+            'C': {'node': 'C', 'degree': 0.9, 'betweenness': 0.2}
+        }
+        
+        result = rank_nodes(centralities, metric='betweenness', top_n=3)
+        
+        assert result[0]['node'] == 'B'  # 最高介数中心性
+        assert result[1]['node'] == 'A'
+        assert result[2]['node'] == 'C'
+    
+    def test_top_n_limit(self):
+        """测试top_n限制"""
+        centralities = {
+            'A': {'node': 'A', 'degree': 0.8},
+            'B': {'node': 'B', 'degree': 0.5},
+            'C': {'node': 'C', 'degree': 0.9},
+            'D': {'node': 'D', 'degree': 0.7}
+        }
+        
+        result = rank_nodes(centralities, metric='degree', top_n=2)
+        
+        assert len(result) == 2
+
+
+class TestIdentifyKeyNodes:
+    """测试关键节点识别"""
+    
+    def test_identify_hubs(self):
+        """测试识别hubs（度中心性高的节点）"""
+        centralities = {
+            'A': {'degree': 0.6, 'betweenness': 0.1, 'eigenvector': 0.2},
+            'B': {'degree': 0.3, 'betweenness': 0.1, 'eigenvector': 0.2},
+            'C': {'degree': 0.8, 'betweenness': 0.1, 'eigenvector': 0.2}
+        }
+        
+        thresholds = {'degree': 0.5, 'betweenness': 0.1, 'eigenvector': 0.3}
+        result = identify_key_nodes(centralities, thresholds)
+        
+        # A和C的度中心性≥0.5，应该被识别为hubs
+        assert len(result['hubs']) == 2
+        assert 'A' in result['hubs']
+        assert 'C' in result['hubs']
+    
+    def test_identify_bridges(self):
+        """测试识别bridges（介数中心性高的节点）"""
+        centralities = {
+            'A': {'degree': 0.3, 'betweenness': 0.15, 'eigenvector': 0.2},
+            'B': {'degree': 0.3, 'betweenness': 0.05, 'eigenvector': 0.2},
+            'C': {'degree': 0.3, 'betweenness': 0.20, 'eigenvector': 0.2}
+        }
+        
+        thresholds = {'degree': 0.5, 'betweenness': 0.1, 'eigenvector': 0.3}
+        result = identify_key_nodes(centralities, thresholds)
+        
+        # A和C的介数中心性≥0.1，应该被识别为bridges
+        assert len(result['bridges']) == 2
+        assert 'A' in result['bridges']
+        assert 'C' in result['bridges']
+    
+    def test_identify_influencers(self):
+        """测试识别influencers（特征向量中心性高的节点）"""
+        centralities = {
+            'A': {'degree': 0.3, 'betweenness': 0.05, 'eigenvector': 0.4},
+            'B': {'degree': 0.3, 'betweenness': 0.05, 'eigenvector': 0.2},
+            'C': {'degree': 0.3, 'betweenness': 0.05, 'eigenvector': 0.5}
+        }
+        
+        thresholds = {'degree': 0.5, 'betweenness': 0.1, 'eigenvector': 0.3}
+        result = identify_key_nodes(centralities, thresholds)
+        
+        # A和C的特征向量中心性≥0.3，应该被识别为influencers
+        assert len(result['influencers']) == 2
+        assert 'A' in result['influencers']
+        assert 'C' in result['influencers']
+    
+    def test_default_thresholds(self):
+        """测试默认阈值"""
+        centralities = {
+            'A': {'degree': 0.6, 'betweenness': 0.15, 'eigenvector': 0.4}
+        }
+        
+        result = identify_key_nodes(centralities)  # 使用默认阈值
+        
+        # 使用默认阈值，A应该被识别为所有三种类型
+        assert 'A' in result['hubs']
+        assert 'A' in result['bridges']
+        assert 'A' in result['influencers']
+
+
+class TestNetworkProperties:
+    """测试网络属性计算"""
+    
+    def test_empty_network(self):
+        """测试空网络"""
+        G = nx.Graph()
+        
+        centralities = calculate_all_centralities(G)
+        
+        assert len(centralities) == 0
+    
+    def test_single_node(self):
+        """测试单节点网络"""
+        G = nx.Graph()
+        G.add_node('A')
+        
+        centralities = calculate_all_centralities(G)
+        
+        assert len(centralities) == 1
+        # networkx对单节点的度中心性定义为1.0
+        assert centralities['A']['degree'] == 1.0
+    
+    def test_disconnected_network(self):
+        """测试非连通网络"""
+        G = nx.Graph()
+        G.add_edges_from([('A', 'B'), ('C', 'D')])  # 两个独立的组件
+        
+        centralities = calculate_all_centralities(G)
+        
+        assert len(centralities) == 4
+        # 接近中心性可能为0（无法到达其他组件）
+        # 但不应该报错
+
+
+if __name__ == '__main__':
+    import pytest
+    pytest.main([__file__, '-v'])

package/skills/performing-network-computation/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: performing-network-computation
+description: 当用户需要执行社会网络计算分析，包括网络构建、基础指标计算、社区检测、网络可视化和高级网络分析时使用此技能
+version: 1.0.0
+author: socienceAI.com
+tags: [social-network-analysis, network-computation, graph-analysis, community-detection, network-visualization]
+---
+
+# 网络计算分析技能 (Performing Network Computation)
+
+## Overview
+为社会科学研究提供全面的社会网络计算分析支持，从网络构建到高级分析的全流程技术实现。
+
+## When to Use This Skill
+Use this skill when the user requests:
+- Complex social network analysis
+- Network model construction
+- Network statistical indicators calculation
+- Community detection and clustering
+- Network visualization and mapping
+- Graph-based analysis of social structures
+- Analysis of relational data in Chinese context
+- Computation of network metrics and indices
+
+## Quick Start
+When a user requests network computation:
+1. **Construct** network from provided data
+2. **Compute** basic network indicators
+3. **Analyze** centrality measures
+4. **Detect** communities and clusters
+5. **Visualize** network structure and patterns
+
+## 使用时机
+
+当用户提到以下需求时，使用此技能：
+- "网络计算" 或 "网络分析计算"
+- "构建社会网络" 或 "网络建模"
+- "网络指标计算" 或 "网络统计"
+- "社区检测" 或 "聚类分析"
+- "网络可视化" 或 "网络绘图"
+- 需要进行复杂的社会网络数学计算
+
+## 快速开始
+
+### 工具链（4个核心脚本）
+
+```bash
+# 1. 网络构建
+python scripts/build_network.py \
+  --input data.json \
+  --output network.graphml \
+  --type weighted
+
+# 2. 指标计算
+python scripts/calculate_metrics.py \
+  --input network.graphml \
+  --output metrics.json
+
+# 3. 社区检测
+python scripts/detect_communities.py \
+  --input network.graphml \
+  --output communities.json \
+  --method louvain
+
+# 4. 网络可视化
+python scripts/visualize_network.py \
+  --input network.graphml \
+  --metrics metrics.json \
+  --output network_visualization.png
+```
+
+## 核心流程
+
+### 第一步：网络构建
+
+使用工具自动构建网络：
+```bash
+python scripts/build_network.py --input raw_data.json --output network.graphml
+```
+
+**关键要点**：
+- 数据格式验证
+- 网络类型设置（有向/无向，加权/无权）
+- 节点边属性处理
+- 网络完整性验证
+
+详见：`references/network-construction/INDEX.md`
+
+---
+
+### 第二步：指标计算
+
+使用工具批量计算指标：
+```bash
+python scripts/calculate_metrics.py --input network.graphml --output metrics.json
+```
+
+**计算指标**：
+- 网络规模：节点数、边数、密度
+- 路径指标：平均路径长度、直径、半径
+- 聚类指标：聚类系数、传递性
+- 连通性指标：连通分量、割点、桥
+
+详见：`references/metric-calculations/INDEX.md`
+
+---
+
+### 第三步：社区检测
+
+使用工具识别社区：
+```bash
+python scripts/detect_communities.py --input network.graphml --output communities.json
+```
+
+**检测算法**：
+- Louvain模块度优化
+- 标签传播算法
+- 谱聚类方法
+- Girvan-Newman算法
+
+详见：`references/community-detection/INDEX.md`
+
+---
+
+### 第四步：网络可视化
+
+使用工具生成可视化：
+```bash
+python scripts/visualize_network.py \
+  --input network.graphml \
+  --metrics metrics.json \
+  --communities communities.json \
+  --output network.png
+```
+
+**可视化元素**：
+- 节点：大小编码中心性，颜色编码社区
+- 边：粗细编码权重
+- 布局：力导向、圆形、层次等
+
+详见：`references/visualization-methods/INDEX.md`
+
+## 输出格式
+
+统一的三层JSON格式：
+
+```json
+{
+  "summary": {
+    "total_nodes": 50,
+    "total_edges": 120,
+    "network_density": 0.098,
+    "components": 1,
+    "avg_path_length": 2.34,
+    "diameter": 6,
+    "modularity": 0.72
+  },
+  "details": {
+    "metrics": {
+      "clustering_coefficient": 0.45,
+      "transitivity": 0.42,
+      "centrality_measures": {...},
+      "community_stats": {...}
+    },
+    "communities": [...],
+    "visualization_data": {...}
+  }
+}
+```
+
+## 质量检查清单
+
+在完成网络计算分析后，请检查以下项目：
+
+### 数据质量
+- [ ] 原始数据格式正确
+- [ ] 网络构建无误
+- [ ] 缺失数据处理合理
+- [ ] 异常值识别准确
+
+### 计算准确性
+- [ ] 所有指标计算正确
+- [ ] 算法参数设置合理
+- [ ] 结果验证充分
+- [ ] 数值精度符合要求
+
+### 分析深度
+- [ ] 指标解释准确
+- [ ] 结果分析深入
+- [ ] 模式识别充分
+- [ ] 洞察提炼有价值
+
+### 可视化质量
+- [ ] 图形清晰可读
+- [ ] 颜色编码合理
+- [ ] 布局美观合理
+- [ ] 关键信息突出
+
+## 常见问题
+
+**快速诊断**：
+- 网络规模过大 → 见 `references/performance-optimization/INDEX.md`
+- 社区检测不稳定 → 使用 `detect_communities.py` 多次运行取平均
+- 计算结果异常 → 见 `references/troubleshooting/INDEX.md` - 数据验证
+- 可视化效果差 → 见 `references/visualization-methods/INDEX.md` - 布局调整
+
+## 深入学习
+
+- **网络构建理论**：`references/network-construction/INDEX.md` - 构建方法详解
+- **指标计算**：`references/metric-calculations/INDEX.md` - 算法和公式
+- **社区检测**：`references/community-detection/INDEX.md` - 算法比较
+- **可视化技术**：`references/visualization-methods/INDEX.md` - 技术和最佳实践
+
+## 完成标志
+
+完成高质量的网络计算分析应该：
+1. 生成准确完整的网络指标
+2. 识别清晰的社区结构
+3. 提供直观的可视化结果
+4. 给出深入的分析解释
+
+---
+
+*此技能为中文社会科学研究提供全面的网络计算支持，从数据处理到高级分析的技术实现，确保研究的科学性和严谨性。*

package/skills/performing-network-computation/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "performing-network-computation"
+version = "2.0.0"
+description = "鍩轰簬绀句細缃戠粶鍒嗘瀽鐞嗚锛屾墽琛岀綉缁滄瀯寤恒€佷腑蹇冩€ц绠椼€佺ぞ鍖烘娴嬨€佺綉缁滃彲瑙嗗寲绛夌綉缁滃垎鏋愪换鍔＄殑鎶€鑳斤紝杩愮敤鍥捐鍜岀綉缁滃垎鏋愭柟娉曪紝鍒嗘瀽鍏崇郴缁撴瀯鍜岀綉缁滅壒鎬?
+authors = [{name = "SSAI Team", email = "contact@agentpsy.com"}]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+
+dependencies = [
+    "networkx>=3.0",
+    "pandas>=2.0.0",
+    "numpy>=1.24.0",
+    "matplotlib>=3.7.0",
+    "seaborn>=0.12.0",
+    "scipy>=1.10.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[[tool.uv.index]]
+name = "tsinghua"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
+default = true