mikemoi/MindScope
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7922bae44ee05e260f027703efa79f88f388746c
MindScope/README.md
T

15 KiB
Raw Blame History

MindScope

MindScope 是一个中文心理量表与自我探索测评项目。它专注于答题、浏览器本地计分、加密保存历史记录、导出完整测评档案，不包含广告、营销页、Web3、用户账号系统或内置 AI 分析模块。

测评结果仅用于自我了解、教育和研究参考，不构成医学诊断、心理诊断或治疗建议。遇到持续、严重或紧急的身心困扰时，请及时联系医生、心理健康专业人员或当地紧急援助服务。

当前版本

v0.6.0，更新于 2026-06-23。

本版本重点是“计分可信度升级”：

  • 32 个量表全部接入统一结构化计分摘要。
  • 每个量表记录明确保存：量表版本、计分版本、最低分、最高分、反向题、临界值。
  • 新记录不再依赖结果页面文字抓取，而是在提交时直接保存结构化分数。
  • 历史记录读取时会自动补齐缺失的结构化计分字段。
  • 趋势页会标明“高分代表改善、风险升高、能力更好，还是特质更明显”。
  • Markdown 导出会包含完整计分规则，方便交给 ChatGPT 或其他工具解读。
  • 敏感量表仍保持克制表达，不把筛查结果写成诊断结论。

版本记录

版本 日期 主要变化
v0.6.0 2026-06-23 32 个量表统一结构化计分，保存量表版本/计分版本/分数范围/反向题/临界值，趋势页显示高分方向，MD 导出补充计分规则
v0.5.0 2026-06-23 本地记录 AES-GCM 加密，旧记录自动迁移，匿名同步端到端加密，首页说明加密与匿名档案
v0.4.0 2026-06-23 匿名档案模式、服务器同步接口、远端记录同步、远端档案删除
v0.3.0 2026-06-23 iOS、手机和平板答题阅读、触控、折叠导航和安全区优化
v0.2.0 2026-06-23 多人档案、完整历史、趋势、统一画像、MD/JSON 导出、加密备份和自动测试
v0.1.0 2026-06-22 中文量表列表、浏览器答题、本地计分、草稿保存和单次结果导出

项目特点

  • 中文优先：界面、题目、结果说明和导出文本均面向中文用户。
  • 32 个测评：覆盖人格、认知、情绪、职业、价值观、幸福感、心理健康等方向。
  • 本地计分：答题和计分在浏览器中完成，不依赖外部分析服务。
  • 结构化结果：每条记录保存分数、版本、范围、反向题、阈值和高分含义。
  • 加密保存：本地历史记录写入 IndexedDB 前会先加密。
  • 匿名同步：可使用“代号 + 恢复口令”同步到服务器，服务器只保存密文。
  • 多档案：可为自己、家人或朋友分别保存独立记录。
  • 完整导出：支持单次记录或单人全部记录导出为 Markdown，也支持 JSON 备份。
  • 轻量部署：默认不需要 MySQL、PostgreSQL、Redis 等数据库。

已收录测评

当前共 32 个测评。

人格与价值观

测评 题数 主要内容
IPIP Big Five 50 五大人格快速版
IPIP Big Five 120 120 五大人格及细分侧面
IPIP Big Five 300 300 五大人格完整版及细分侧面
HEXACO 60 六因素人格结构
Fisher 气质量表 40 探索者、建设者、指挥者、协商者倾向
开放式九型人格量表 OEPS 54 九型人格倾向
Short Dark Triad 27 马基雅维利主义、自恋、精神病态倾向
NPI-16 自恋人格量表 16 自恋相关人格倾向
Rosenberg 自尊量表 10 整体自尊与自我价值感
Grit-S 坚毅量表 8 兴趣一致性与努力坚持
Brief Self-Control 13 自我控制、冲动控制和习惯管理
ECR-RS 依恋量表 9 依恋焦虑与依恋回避
IRI 共情量表 28 共情、观点采择和个人忧虑
Schwartz 价值观量表 30 十类基本价值观和高阶价值维度
VIA 性格优势量表 48 24 项性格优势

认知与职业

测评 题数 主要内容
CRT 认知反思测试 7 直觉反应与分析性反思
Need for Cognition 18 主动思考和享受认知活动的倾向
Maximizer 13 决策中的最大化倾向
RIASEC 霍兰德职业兴趣 48 现实型、研究型、艺术型、社会型、企业型、常规型
Career Anchors 职业锚 40 八类职业价值与职业定位
成人 ADHD 自评量表 ASRS-v1.1 18 注意力、冲动和执行功能相关表现

情绪、压力与心理健康

测评 题数 主要内容
DASS-21 21 抑郁、焦虑与压力
GAD-7 7 广泛性焦虑症状筛查
PHQ-9 9 抑郁症状筛查
PSS-10 10 主观感知压力
BDI-II 21 抑郁相关症状自评
SDS 20 抑郁相关症状自评
WHO-5 幸福感指数 5 近期主观幸福感
Yale-Brown 强迫症状量表 10 强迫观念与强迫行为严重程度
SCL-90 90 多维心理症状自评
ISI 失眠严重程度指数 7 失眠程度及日间影响
游戏障碍问卷 GD 9 游戏相关困扰
性别认知障碍问卷 GDQ 27 性别相关体验自评

数据与隐私

MindScope 默认没有传统服务端数据库，也不会主动把答案发送给第三方分析服务。

数据 保存位置 说明
未完成答题草稿 浏览器 localStorage 用户清除草稿或站点数据前保留
最近完成的答题答案 浏览器 sessionStorage 当前标签页会话结束前保留，用于结果页展示
档案与历史记录 浏览器 IndexedDB 写入前使用 AES-GCM 加密
匿名同步记录 data/anonymous-store.json 浏览器端加密后上传，服务器保存密文
Markdown 导出 用户主动下载的位置 由用户自行管理
JSON / 加密 JSON 备份 用户主动下载的位置 可用于迁移或恢复

结果页 URL 不携带答案，因此复制页面链接不会把测评记录放进浏览器历史、代理日志或服务器访问日志。需要保留或交给其他工具分析时，请使用“复制完整记录”或“下载 MD”。

结构化计分

结构化计分元数据位于 lib/scoring-metadata.ts。每个量表都会记录：

  • questionnaireVersion：量表题目版本
  • scoreVersion：计分逻辑版本
  • min / max：总分或主要维度分数范围
  • reverseItems：反向题编号
  • thresholds：临界值或分级阈值
  • direction：高分方向，区分风险、保护因素、能力表现、人格特质或混合含义
  • highScoreMeaning：人类可读的高分解释

新增量表时，除了题目和结果页，还必须补充结构化计分元数据，避免旧记录在题目或计分逻辑更新后被错误解释。

技术栈

  • Next.js 15 App Router
  • React 19
  • TypeScript 5
  • Tailwind CSS 4
  • next-international
  • Radix UI
  • Lucide React
  • pnpm

环境要求

  • Node.js 20 或更高版本
  • pnpm 9 或更高版本

建议开发和生产环境使用相同 Node.js 主版本，避免构建结果不一致。

获取与更新项目

推荐使用 SSH 克隆。如果 Gitea SSH 服务使用 2222 端口：

git clone ssh://git@git.polarisx.net:2222/mikemoi/MindScope.git
cd MindScope

也可以使用 HTTPS：

git clone https://git.polarisx.net/mikemoi/MindScope.git
cd MindScope

服务器已经部署过项目时，使用以下命令获取最新版本并重新构建：

cd /opt/mindscope
git pull --ff-only origin main
pnpm install --frozen-lockfile
pnpm build

mkdir -p .next/standalone/.next
rm -rf .next/standalone/.next/static
cp -r .next/static .next/standalone/.next/static

sudo systemctl restart mindscope
sudo systemctl status mindscope --no-pager

如果以后增加 public 目录，构建后还需要同步公开静态文件：

rm -rf .next/standalone/public
cp -r public .next/standalone/public

.env*、.next、node_modules、日志和本地压缩包已被 .gitignore 排除。更新前如有未提交的源码修改，先运行 git status 检查；git pull --ff-only 会在无法安全快进时停止，不会自动创建合并提交。

本地开发

pnpm install --frozen-lockfile
pnpm dev

浏览器打开：

http://localhost:3000

常用命令：

# 启动开发服务器
pnpm dev

# 代码检查
pnpm lint

# TypeScript 类型检查
pnpm exec tsc --noEmit

# 自动化测试
pnpm test

# 生产构建
pnpm build

# 启动 Next.js 生产服务器
pnpm start

生产部署

直接运行

适合先验证 VPS 环境：

pnpm install --frozen-lockfile
pnpm build
NODE_ENV=production PORT=3000 pnpm start

生产环境建议只监听本机地址，再用 Nginx 提供公网访问和 HTTPS。

Standalone 部署

项目在 next.config.ts 中启用了 output: 'standalone'。构建完成后，可部署更小的运行目录：

pnpm install --frozen-lockfile
pnpm build

cp -r public .next/standalone/public 2>/dev/null || true
cp -r .next/static .next/standalone/.next/static

cd .next/standalone
HOSTNAME=127.0.0.1 PORT=3000 NODE_ENV=production node server.js

当前项目没有 public 目录时，第一条复制命令可以忽略。.next/static 必须复制到 standalone 目录，否则静态资源会缺失。

systemd 示例

假设项目源码部署到 /opt/mindscope，Node.js 位于 /usr/bin/node：

[Unit]
Description=MindScope
After=network.target

[Service]
Type=simple
User=mindscope
Group=mindscope
WorkingDirectory=/opt/mindscope/.next/standalone
Environment=NODE_ENV=production
Environment=HOSTNAME=127.0.0.1
Environment=PORT=3000
ExecStart=/usr/bin/node /opt/mindscope/.next/standalone/server.js
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

保存为 /etc/systemd/system/mindscope.service 后：

sudo systemctl daemon-reload
sudo systemctl enable --now mindscope
sudo systemctl status mindscope

不要使用 root 用户运行应用。部署目录应只允许部署用户写入。

Nginx 反向代理示例

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

配置完成后使用 Certbot 或其他证书工具启用 HTTPS。防火墙通常只需要开放 SSH、HTTP 和 HTTPS，应用端口 3000 不应直接暴露到公网。

推荐 VPS 配置

  • 最低：1 核 CPU、1 GB 内存
  • 建议：1-2 核 CPU、2 GB 内存
  • 系统：Debian 或 Ubuntu LTS
  • 磁盘：预留至少 2 GB 给项目、依赖、构建和日志

内存较小的 VPS 可以在构建时临时启用 swap，也可以在本地或 CI 构建后只上传 standalone 运行文件。

项目结构

MindScope/
├── app/                         # Next.js 页面、布局和全局样式
├── components/
│   ├── questionnaire/
│   │   ├── test/                # 答题流程和部分量表计分器
│   │   └── result/              # 结果展示
│   └── ui/                      # 通用界面组件
├── hooks/                       # React Hooks
├── lib/                         # 存储、加密、导出、结构化计分等工具
├── locales/zh/                  # 中文界面文本
├── questionairies/              # 量表题目、说明和元数据
│   └── zh.ts                    # 全部量表注册表
├── types/                       # TypeScript 类型定义
├── middleware.ts                # 中文路由处理
└── next.config.ts               # Next.js 配置

目录名 questionairies 是项目当前使用的历史命名。新增代码应继续沿用，除非一次性完成全项目重命名，避免导入路径不一致。

测评流程

量表列表
  -> 量表详情
  -> 浏览器答题
  -> 提交时结构化计分
  -> 加密保存记录
  -> 结果展示
  -> 复制完整记录或下载 Markdown

每个量表主要由四部分组成：

  1. questionairies/<id>/zh.ts：题目、选项、说明、分类和参考资料。
  2. components/questionnaire/test/private/*Calculator.tsx：复杂量表的答案转换和计分。
  3. lib/scoring-metadata.ts：量表版本、计分版本、分数范围、反向题、阈值和高分方向。
  4. components/questionnaire/result/analysis/*Result.tsx：结果解释与展示。

新增量表

新增量表时建议按以下顺序进行：

  1. 在 questionairies/<id>/zh.ts 定义量表元数据、题目和选项。
  2. 在 questionairies/zh.ts 导入并注册量表。
  3. 创建或复用计分逻辑，处理正向题、反向题和维度得分。
  4. 在 lib/scoring-metadata.ts 增加结构化计分元数据。
  5. 创建结果组件，展示总分、维度和必要边界说明。
  6. 在 ResultAnalysis.tsx 注册结果组件。
  7. 补充或更新 lib/score-summary.test.ts。
  8. 运行 pnpm lint、pnpm exec tsc --noEmit、pnpm test 和 pnpm build。
  9. 手动完成一次答题，检查草稿恢复、结果计算、历史记录和 MD 导出。

量表数据至少应包含：

  • 稳定唯一的 id
  • 中文标题和简介
  • 一级分类与必要标签
  • 题数、预计时间和作答说明
  • 计分方法和维度说明
  • 最低分、最高分、反向题、临界值和高分含义
  • 学术认可度、是否适合重测和建议重测周期
  • 使用注意事项及参考资料

质量检查

提交代码前执行：

pnpm lint
pnpm exec tsc --noEmit
pnpm test
pnpm build

涉及计分逻辑时，还应人工核对：

  • 题目编号是否连续且唯一。
  • 正向题与反向题是否正确。
  • 选项值是否与计分器一致。
  • 维度题目数量是否符合预期。
  • 最低分、最高分和临界值是否可达。
  • 旧记录是否能通过版本号正确解释。
  • 趋势页是否正确解释“高分方向”。
  • 刷新结果页和关闭标签页后的行为是否符合隐私设计。

使用边界

  • 筛查量表只能提示风险或症状程度，不能单独用于诊断。
  • 不应根据一次测评结果自行停药、换药或改变治疗方案。
  • 不同翻译版本、计分版本和适用人群可能存在差异。
  • 用于正式研究、机构服务或商业场景前，应再次核实量表版本、常模、授权和当地法规。
  • 项目中的结果解释应保持克制，避免把分数描述为确定的人格或疾病结论。

授权

本仓库未附带通用开源许可证。项目代码、量表文本及相关材料的复制、修改、再发布和商业使用，应取得仓库权利人的明确许可。第三方量表仍受其各自适用的版权、商标、授权条款和使用规范约束。

Reference in New Issue View Git Blame Copy Permalink