# dsh-scale-assessment

**Repository Path**: openminds/dsh-scale-assessment

## Basic Information

- **Project Name**: dsh-scale-assessment
- **Description**: DSH 心理量表测评插件 —— 为 DSH Agent 提供状态化的心理量表测评能力：选择量表、逐题作答、自动计分、风险预警与 Markdown 报告生成。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: dsh, TypeScript, scale, Assessment

## README

# dsh-scale-assessment

DSH 心理量表测评插件 —— 为 DSH Agent 提供状态化的心理量表测评能力：选择量表、逐题作答、自动计分、风险预警与 Markdown 报告生成。

## 特性

- **无需传递会话 ID**：会话键取自 `exec.agent.session.id`，一个 Agent 对话自动对应一份测评状态。
- **自动计分**：按 `score_rules` 映射选项分值，支持反向题（`min + max - raw`）、维度分聚合，以及 SDS/SAS 标准分 `int(1.25 × 总分)`。
- **BSRAT 专用规则**：第 1 题子项（1a–1f）取最大值而非求和；全部为 0 时终止评估（总分强制为 0）并同步替换 `max_score` 与「自杀意念与行为」维度分。
- **风险与安全提示**：命中高风险条目（PHQ-9 第 9 题选 D、SDS 第 19 题选 D、SCL-90 第 15 题选 E、BSRAT 1a–1f 或第 4 题选 B）或 BSRAT 总分 ≥10 时，自动附加提示。
- **标准化报告**：输出包含基本信息、分数统计、结果解释、重要提示、答题明细、量表说明与临床建议的 Markdown 报告。
- **会话治理**：TTL 淘汰（默认 1 小时）+ 容量上限（默认 1000），每分钟扫描一次。

## 环境要求

- Node.js >= 20
- pnpm

## 安装与构建

```bash
pnpm install
pnpm build        # tsdown 构建，产物在 lib/
pnpm test         # vitest run
pnpm typecheck    # tsc --noEmit
```

构建产物为 ESM：`lib/index.js` 与 `lib/index.d.ts`（`package.json` 的 `main` / `types` / `exports` 均指向 `lib/`）。

## 插件契约

```ts
export const name = 'dsh-scale-assessment';
export const inject = ['tools'];
export function apply(ctx: Context, config: PluginConfig = {}): void;
```

`apply` 会依次完成：创建日志器 → 加载并校验全部量表 → 创建会话存储 → 通过 `ctx.effect` 注册 TTL 清理定时器 → 注册全部工具。

## 项目地址

- **Gitee**: https://gitee.com/openminds/dsh-scale-assessment

## 使用 DSH CLI 部署插件

### 1. 安装 DSH CLI
```bash
npm install -g @deepseek-ai/dsh
```

### 2. 添加插件到 DSH Profile
```bash
# 添加插件到 web profile
dsh plugin --profile web add https://gitee.com/openminds/dsh-scale-assessment

# 或者从本地目录添加
dsh plugin --profile web add /path/to/dsh-scale-assessment
```

### 3. 验证插件配置
```bash
# 查看当前 profile 配置
# Windows PowerShell:
dsh --profile web --dump-config | Select-String "dsh-scale-assessment"

# 或者使用 findstr (Windows CMD):
dsh --profile web --dump-config | findstr "dsh-scale-assessment"

# 或者使用 grep (Git Bash / WSL):
dsh --profile web --dump-config | grep dsh-scale-assessment

# 预期输出应包含：
# # == dsh-scale-assessment
# - id: dsh-scale-assessment
#   name: dsh-scale-assessment
```

### 4. 启动 DSH 服务
```bash
# 启动 Web 界面
dsh web --port 3081

# 或者启动 CLI 模式
dsh cli
```

### 5. 验证插件功能
在 DSH Web 界面或 CLI 中测试以下工具：

```bash
# 列出所有可用量表
list_scales

# 开始一个 SDS 量表测评
start_assessment --abbreviation SDS

# 提交答案（示例）
submit_answer --item_id 1 --answer B

# 计算结果
calculate_results

# 生成报告
generate_report
```

### 6. 配置插件
插件支持通过 profile 配置覆盖默认设置：

```yaml
# 在 ~/.dsh/profiles/web/config.yml 中添加：
plugins:
  dsh-scale-assessment:
    config:
      sessionTtlMs: 7200000  # 2小时
      maxSessions: 500
      logLevel: debug
```

### 常见问题排查

**权限问题**：
- 如果遇到文件权限错误，尝试使用管理员权限运行命令
- 确保 Node.js 版本 >= 20

**网络问题**：
- 如果从 Gitee 下载失败，可以先将项目克隆到本地再添加
- 检查网络连接和代理设置

**配置问题**：
- 使用 `--dump-config` 检查配置是否正确加载
- 查看 DSH 日志文件（通常在 ~/.dsh/logs/）获取详细错误信息

### 卸载插件
```bash
dsh plugin --profile web remove dsh-scale-assessment
```

`package.json` 中已声明 `dsh.bundle.patch` 指向 `cordis.patch.yml`：

```yaml
- insert:
    - id: dsh-scale-assessment
      name: 'dsh-scale-assessment'
      # config:
      #   sessionTtlMs: 3600000
      #   maxSessions: 1000
      #   logLevel: info
```

## 配置项

| 配置 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `sessionTtlMs` | `number` | `3600000` | 会话空闲淘汰时间（毫秒） |
| `maxSessions` | `number` | `1000` | 最大会话数，超限时淘汰最久未访问的会话 |
| `logLevel` | `'debug' \| 'info' \| 'warn' \| 'error'` | `'info'` | 日志级别 |

## 工具清单

共 24 个工具：测评流程 5 个、量表查询 2 个、量表专用 17 个。

### 测评流程

| 工具 | 参数 | 说明 |
|---|---|---|
| `start_assessment` | `abbreviation` | 开始测评，返回题目总数与首题（题号、题干、选项） |
| `submit_answer` | `item_id`、`answer` | 提交单题答案，返回进度与下一题；答完最后一题时直接返回完整结果 |
| `cancel_assessment` | — | 取消当前对话的测评并清空答案，之后可重新 `start_assessment` |
| `calculate_results` | — | 计算当前测评结果，未答完则报错 |
| `generate_report` | — | 生成 Markdown 测评报告，未答完则报错 |

### 量表查询

| 工具 | 参数 | 说明 |
|---|---|---|
| `list_scales` | — | 列出可用量表（缩写、名称、简介、题量、预计用时） |
| `get_scale_guide` | `abbreviation` | 获取量表背景、目的、适用人群、计分方式、结果解释与注意事项 |

### 量表专用工具

按量表定制的速评工具，直接从传入的分数给出分级与解释；`scales/*.json` 中的每一份量表都有对应工具。

| 工具 | 对应量表 | 参数 |
|---|---|---|
| `sds_depression_scale` | SDS 抑郁自评量表 | `score` |
| `sas_anxiety_scale` | SAS 焦虑自评量表 | `score` |
| `scl_90_symptom_checklist` | SCL-90 症状自评量表 | `total_score`、`positive_items` |
| `phq_9_depression_screening` | PHQ-9 抑郁筛查 | `score` |
| `gad_7_anxiety_screening` | GAD-7 焦虑筛查 | `score` |
| `bsrat_behavior_risk_assessment` | BSRAT 简明自杀风险评估工具 | `score` |
| `aaq_ii_acceptance_action` | AAQ-II 接纳与行动问卷 | `score` |
| `cabs_autism_screening` | CABS 克氏孤独症行为量表 | `total_score` |
| `cbf_pi_b_personality_assessment` | CBF_PI_B 中国大五人格问卷（简式版） | `neuroticism`、`conscientiousness`、`agreeableness`、`openness`、`extraversion` |
| `cmqi_marital_quality` | CMQI 中国人婚姻质量问卷 | `total_score` |
| `epds_postnatal_depression` | EPDS 爱丁堡产后抑郁量表 | `score` |
| `fne_r_negativity_evaluation` | FNE_R 惧怕否定评价量表（修订） | `score` |
| `gds_geriatric_depression` | GDS 老年抑郁量表 | `score` |
| `pcl_ptsd_checklist` | PCL 创伤后应激障碍检查表 | `total_score` |
| `tai_test_anxiety_inventory` | TAI 考试焦虑调查表 | `total_score` |
| `tas_test_anxiety_scale` | TAS 考试焦虑量表 | `score` |
| `znpq_negative_perfectionism` | ZNPQ 消极完美主义问卷 | `total_score` |

## 典型流程

```
start_assessment(SDS)  →  submit_answer("1", "B")  →  …  →  submit_answer("20", "A")
                                                          ↓
                                          （最后一题返回完整 results）
calculate_results()    →  校验是否答完并返回结构化结果
generate_report()      →  返回 Markdown 报告
```

## 量表数据

量表定义存放在 `scales/*.json`，字段结构如下：

```jsonc
{
  "chinese_name": "抑郁自评量表",
  "english_name": "Self-Rating Depression Scale",
  "abbreviation": "SDS",
  "category": "精神病学临床量表",
  "outline": "…量表背景…",
  "contents": {
    "instruction": "…指导语…",
    "items": { "1": "题干…" },                       // 题号 → 题干
    "reverse_items": ["2", "5"],                     // 反向计分题
    "scales": ["维度名"],                            // 维度
    "scales_items": { "维度名": ["1", "2"] },        // 维度 → 题号
    "factors": [],                                   // 因子（预留）
    "factors_scales": {},
    "rating": { "1": { "A": "没有或很少时间" } },     // 题号 → 选项
    "score_rules": { "1": [1, 2, 3, 4] }             // 题号 → 各选项分值
  },
  "implementation": "…",
  "measurements": {},
  "interpretation": "…结果解释…",
  "applications": "…适用范围…"
}
```

当前随包提供的 17 份量表数据：

| 缩写 | 中文名 | 类别 |
|---|---|---|
| AAQ_II | 接纳与行动问卷 | 行为方式量表 |
| BSRAT | 简明自杀风险评估工具 | 精神病学临床量表 |
| CABS | 克氏孤独症行为量表 | 精神病学临床量表 |
| CBF_PI_B | 中国大五人格问卷（简式版） | 人格评估量表 |
| CMQI | 中国人婚姻质量问卷 | 生活质量与满意度量表 |
| EPDS | 爱丁堡产后抑郁量表 | 精神病学临床量表 |
| FNE_R | 惧怕否定评价量表（修订） | 精神病学临床量表 |
| GAD_7 | 广泛性焦虑障碍量表 | 精神病学临床量表 |
| GDS | 老年抑郁量表 | 精神病学临床量表 |
| PCL | 创伤后应激障碍检查表 | 应激及相关行为量表 |
| PHQ_9 | 患者健康问卷抑郁症状群量表 | 精神病学临床量表 |
| SAS | 焦虑自评量表 | 精神病学临床量表 |
| SCL_90 | 90 项症状清单 | 一般心理健康与行为问题量表 |
| SDS | 抑郁自评量表 | 精神病学临床量表 |
| TAI | 考试焦虑调查表 | 学习与教育量表 |
| TAS | 考试焦虑量表 | 学习与教育量表 |
| ZNPQ | 消极完美主义问卷 | 人生价值、态度量表 |

> 会话式测评由 `ScaleRepository` 动态扫描 `scales/*.json` 驱动，实际可用的量表取决于该目录中的 JSON 文件。上述 17 份均已加载，并各自注册了对应的速评工具。

## 计分要点

- 单题：按 `rating` 的键序定位答案下标，取 `score_rules` 对应值；命中 `reverse_items` 时按 `min + max - raw` 翻转。
- 聚合：`item_scores` → 维度分（`scales_items` 求和）→ 因子分（`factors` 非空时才构建）；未作答题目跳过。
- 标准分：仅 SDS / SAS，`Math.trunc(1.25 × 总分)`；其他量表返回 `null`。
- BSRAT：见上文「特性」。

## 项目结构

```
src/
├── index.ts          # 插件入口：apply / name / inject
├── config.ts         # 配置默认值
├── logger.ts         # 日志器
├── errors.ts         # 业务错误工厂（中文提示，与黄金样例逐字对齐）
├── session.ts        # SessionStore（Map + TTL + 容量淘汰）
├── scale-data.ts     # 量表加载、自然排序、数据校验
├── service.ts        # ScaleRepository
├── scoring.ts        # 计分引擎（含 BSRAT 规则隔离）
├── report.ts         # Markdown 报告生成
├── types.ts          # 共享类型
└── tools/            # 工具注册（scales / session / assessment / results / prompts）
scales/               # 17 份量表 JSON
tests/                # vitest 用例 + tests/fixtures 黄金样例
scripts/              # 环境核对与部署校验脚本
```

## 开发与测试

```bash
node scripts/verify-env.mjs   # 依赖/数据/构建环境核对
pnpm typecheck && pnpm test && pnpm build
```

`tests/fixtures/` 中保存了由原 Python 服务真实产出、与 TS 实现逐字比对的黄金样例，评分测试会逐一校验 `results` 与 `partial_results`。

测试共 86 个用例（3 个文件）：

| 文件 | 覆盖内容 |
|---|---|
| `tests/scoring.spec.ts` | 26 份黄金样例的分数逐项比对 |
| `tests/session.spec.ts` | 会话生命周期、TTL 淘汰与容量上限 |
| `tests/all-scales.spec.ts` | 17 份量表的端到端流程（开始 → 逐题作答 → 结果 → 报告）、17 个速评工具、查询工具与错误路径 |

## 错误提示

业务错误统一抛原生 `Error`（框架归一化为 `isError` 结果），文案面向模型、可直接指导下一步操作，例如：

- `量表 'XXX' 不存在。可用量表：SDS, SAS, …`
- `该会话尚未开始测评。请先调用 start_assessment 并传入此 session_id。`
- `测评尚未完成：已作答 3/9 题。请先答完全部题目。`
- `题目 1 的答案 'Z' 无效。可选值：A, B, C, D`



## 许可证

MIT