# 📊 dsh-econ-tools — 计量经济学研究助手

[English](README.md) | 中文

> 为 DeepSeek Harness 提供 **6 个开箱即用的计量经济学工具**，覆盖从方法选择、数据预处理、模型设定、实证分析、稳健性检验到结果报告的全流程研究需求。

[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
![DSH Plugin](https://img.shields.io/badge/DSH-Web%20profile-5B4CF0?style=flat-square)
[![Changelog](https://img.shields.io/badge/changelog-Keep%20a%20Changelog-2EA44F)](CHANGELOG.md)

---

## 功能一览

| 工具 | 功能 | 适用场景 |
|------|------|----------|
| 🎯 `econ_method_guide` | **方法指南** — 根据研究问题和数据类型，推荐合适的计量经济学模型与方法 | 研究设计阶段，不确定该用什么模型 |
| 🧹 `econ_data_prep` | **数据预处理** — 缺失值处理、异常值检测、变量变换、分类变量编码，附带 Python 代码模板 | 拿到原始数据后，开始清洗整理 |
| ⚙️ `econ_model_spec` | **模型设定与变量选择** — 理论驱动、数据驱动、混合方法、机器学习法（LASSO/Ridge/ElasticNet）四种策略，附带模型诊断检查清单 | 确定核心变量、选择控制变量 |
| 🔬 `econ_run_analysis` | **实证分析执行** — 支持 OLS、IV/2SLS、Logit、Probit、面板固定效应、DID、RDD，自动生成 Python/R/Stata 代码模板，含回归结果解读指引 | 运行回归、解读结果 |
| 🛡️ `econ_robustness` | **稳健性分析** — 遗漏变量、测量误差、样本选择、模型设定、异常值影响、平行趋势、安慰剂检验，七大维度全覆盖 | 验证核心结论是否可靠 |
| 📝 `econ_report` | **结果报告与输出** — 生成描述性统计表、基准回归结果表、稳健性检验汇总表，支持 Markdown / LaTeX / HTML 格式，中英文双语 | 写论文、整理结果表格 |

---

## 快速开始

### 安装

#### 方式一：从 GitHub 安装（推荐）

通过 `dsh` 命令行直接安装：

```bash
dsh plugin --profile web add github:Chaos-Hyper/dsh-econ-tools
```

#### 方式二：本地文件安装

如果你已有插件源码目录，可直接通过路径安装：

```bash
dsh plugin --profile web add /path/to/dsh-econ-tools
```

或者手动添加到 web profile 的依赖中（编辑 `~/.dsh/profiles/web/package.json`）：

```json
"dependencies": {
    "dsh-econ-tools": "link:/path/to/dsh-econ-tools"
}
```

然后在 `dsh.profile.bundles` 数组中添加 `"dsh-econ-tools"`，最后运行：

```bash
cd ~/.dsh/profiles/web
pnpm install
```

重启 DSH 后生效。

### 使用

在对话中，Agent 会自动根据你的研究需求调用合适的工具。例如：

> *"我想研究教育水平对收入的影响，用截面数据，应该用什么模型？"*
> → Agent 调用 `econ_method_guide`，推荐 OLS、工具变量法等方法

> *"帮我做一下稳健性检验，看看遗漏变量问题"*
> → Agent 调用 `econ_robustness`，给出 Oster 系数稳定性检验等方案

---

## 工具详细说明

### 1. econ_method_guide — 方法指南

**输入参数：**
- `research_goal`：研究目标（因果推断 / 预测 / 政策评估）
- `dependent_type`：被解释变量类型（连续型 / 二元选择 / 面板数据）
- `data_structure`：数据结构（横截面 / 时间序列 / 面板数据）
- `endogeneity_concern`：是否存在内生性（可选）

**输出示例：**
```json
{
  "recommended_models": ["OLS 普通最小二乘法", "DID 双重差分法"],
  "methodology_notes": ["进行模型诊断", "使用稳健标准误"],
  "next_tools": ["econ_data_prep", "econ_model_spec", "econ_run_analysis"]
}
```

### 2. econ_data_prep — 数据预处理

**输入参数：**
- `missing_rate`：缺失比例（无缺失 / 少量 / 中等 / 大量）
- `outlier_concern`：是否关注异常值
- `variable_types`：变量类型（连续型 / 分类变量 / 虚拟变量）
- `need_transformation`：是否需要变量变换

**输出含 Python 代码模板：** 使用 KNNImputer 处理缺失值、Winsorize 处理异常值。

### 3. econ_model_spec — 模型设定与变量选择

**四种策略选择：**
| 策略 | 方法 | 适用场景 |
|------|------|----------|
| 理论驱动 | 基于经济理论设定核心模型，逐步添加控制变量 | 经典问题的复现研究 |
| 数据驱动 | 逐步回归 + AIC/BIC 准则 | 变量较多、理论不明确时 |
| 混合方法 | 理论筛选 → 数据驱动 → LASSO 复审 | 大部分实证研究推荐 |
| 机器学习法 | LASSO / Ridge / Elastic Net / 随机森林 | 高维变量、预测导向 |

**自动输出模型诊断检查清单**（按模型类型区分）。

### 4. econ_run_analysis — 实证分析执行

**支持模型类型：** OLS、IV/2SLS、Logit、Probit、面板固定效应、DID、RDD

**自动生成代码模板：**
- Python：`statsmodels` + 稳健标准误
- R：`fixest` + `lmtest` + `sandwich`
- Stata：`reg` + `robust`

**输出包含：** 模型公式、回归结果解读指引、需要运行的诊断检验列表。

### 5. econ_robustness — 稳健性分析

**七大维度：**
| 维度 | 核心方法 |
|------|----------|
| 遗漏变量 | Oster 2019 系数稳定性检验、Altonji-Elder-Taber 比率 |
| 测量误差 | 替代变量估计、工具变量校正 |
| 样本选择 | Heckman 两阶段、倾向得分匹配 PSM |
| 模型设定 | 改变函数形式、分位数回归、Bootstrap |
| 异常值影响 | Winsorize 1%/5%、剔除极端值、M-estimation |
| 平行趋势 | 事件研究图、虚构处理时间、排列检验 |
| 安慰剂检验 | 随机分配处理变量、虚构处理时间 |

### 6. econ_report — 结果报告与输出

**支持的报告类型：**
- 描述性统计表（表 1）
- 基准回归结果表（表 2，含星号标注、控制变量、固定效应、R² 等脚注行）
- 稳健性检验汇总表（表 3）
- 完整研究摘要（三表合一）

**输出格式：** Markdown、LaTeX、HTML

**语言：** 中文、English

---

## 工作流程建议

典型的计量经济学研究可遵循以下工具链：

```
econ_method_guide    → 确定研究方法和模型
       ↓
econ_data_prep       → 清洗和预处理数据
       ↓
econ_model_spec      → 设定模型、选择变量
       ↓
econ_run_analysis    → 执行回归分析
       ↓
econ_robustness      → 验证结果稳健性
       ↓
econ_report          → 生成结果报告
```

---

## 许可

MIT License