mikemoi/MindScope
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新 v0.6.0 项目说明

Browse Source
This commit is contained in:
mikemoi
2026-06-23 02:24:04 +02:00
parent ca77aa0896
commit 7922bae44e
2 changed files with 127 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+126 -142
View File
@@ -1,103 +1,82 @@
# MindScope
一个中文心理量表与自我探索测试项目。项目专注于答题、浏览器本地计分和完整记录导出，不包含 AI 分析、用户账户、数据库、广告、营销页面或 Web3 功能。
MindScope 是一个中文心理量表与自我探索测评项目。它专注于答题、浏览器本地计分、加密保存历史记录、导出完整测评档案，不包含广告、营销页、Web3、用户账号系统或内置 AI 分析模块。
> 测评结果仅用于自我了解、教育和研究参考，不构成医学诊断、心理诊断或治疗建议。遇到持续、严重或紧急的身心困扰时，请及时联系医生、心理健康专业人员或当地紧急援助服务。
## 当前版本
**v0.5.0**，发布于 2026-06-23。
**v0.6.0**，更新于 2026-06-23。
本次版本升级为加密存储：
本版本重点是“计分可信度升级”：
- 本地测评记录写入 IndexedDB 前会先使用 AES-GCM 加密
- 旧的本地明文记录会在读取后自动迁移为密文记录
- 匿名服务器同步改为浏览器端加密，服务器只保存密文记录
- 匿名档案仍使用“代号 + 恢复口令”，恢复口令不明文保存
- 首页重新设计，明确说明本地加密、匿名加密同步和 AI 解读用途
- 32 个量表全部接入统一结构化计分摘要。
- 每个量表记录明确保存：量表版本、计分版本、最低分、最高分、反向题、临界值。
- 新记录不再依赖结果页面文字抓取，而是在提交时直接保存结构化分数。
- 历史记录读取时会自动补齐缺失的结构化计分字段。
- 趋势页会标明“高分代表改善、风险升高、能力更好，还是特质更明显”。
- Markdown 导出会包含完整计分规则，方便交给 ChatGPT 或其他工具解读。
- 敏感量表仍保持克制表达，不把筛查结果写成诊断结论。
上一版本新增匿名档案模式，仍然保留本地优先：
本次版本新增匿名档案模式，仍然保留本地优先：
- 可使用“代号 + 恢复口令”进入匿名档案
- 恢复口令只保存哈希，不保存明文
- 可把当前本地档案的测评记录同步到服务器
- 已登录匿名档案时，新完成的测评会自动同步
- 支持删除服务器上的匿名档案与全部远端记录
- 服务端默认使用 `data/anonymous-store.json` 轻量存储，适合自用 VPS 起步
- 修复档案页、首页、导出 Markdown 和分数摘要中的部分中文显示问题
上一版本已优化 iPhone、Android 手机和 iPad 的答题体验，桌面端功能保持不变：
- 中文题目在手机端使用 17px 字号和更宽松行高
- 选项整行可点击，触控高度不低于 48px
- 手机和平板使用固定底部翻页栏，并适配 iOS 底部安全区
- 题号导航在窄屏下默认折叠，减少对正文的遮挡
- 档案选择框使用 16px 字号，避免 iPhone Safari 自动放大
- 页面使用动态视口高度并适配刘海屏左右安全区
- 保留双指缩放和系统字体回退，改善中文阅读与无障碍体验
- 已验证 320px、390px、768px 和 1280px 视口无横向溢出
### 版本记录
## 版本记录
| 版本 | 日期 | 主要变化 |
| --- | --- | --- |
| v0.5.0 | 2026-06-23 | 本地记录加密、旧记录自动迁移、匿名同步端到端加密、首页加密说明 |
| v0.4.0 | 2026-06-23 | 匿名档案模式、服务器同步接口、远端记录同步、远端档案删除和部分中文显示修复 |
| 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.2.0 | 2026-06-23 | 多人档案、完整历史、趋势、统一画像、MD/JSON 导出、加密备份和自动测试 |
| v0.1.0 | 2026-06-22 | 中文量表列表、浏览器答题、本地计分、草稿保存和单次结果导出 |
## 项目特点
- **仅中文内容**：界面、题目、结果说明均为中文
- **32 个测评**：覆盖人格、认知、情绪、睡眠、职业和心理健康
- **本地计算**：答题和计分在浏览器中完成，不依赖外部分析服务
- **无需账户**：没有注册、登录和个人资料系统
- **无需数据库**：默认部署不需要 MySQL、PostgreSQL、Redis 等服务
- **草稿保存**：未完成的答题记录保存在当前浏览器
- **多人档案**：可为自己、家人或朋友分别保存独立记录
- **长期记录**：同一量表每次测评都会新增历史，不覆盖旧结果
- **趋势与画像**：追踪适合重测的量表，并汇总透明的人格维度
- **完整导出**：支持单次或单人全部记录的 Markdown，以及全量 JSON 备份
- **加密备份**：可使用本地密码生成 AES-GCM 加密备份
- **适合轻量部署**：支持 Next.js standalone 构建，可运行在普通 Linux VPS
- **中文优先**：界面、题目、结果说明和导出文本均面向中文用户。
- **32 个测评**：覆盖人格、认知、情绪、职业、价值观、幸福感、心理健康等方向。
- **本地计分**：答题和计分在浏览器中完成，不依赖外部分析服务。
- **结构化结果**：每条记录保存分数、版本、范围、反向题、阈值和高分含义。
- **加密保存**：本地历史记录写入 IndexedDB 前会先加密。
- **匿名同步**：可使用“代号 + 恢复口令”同步到服务器，服务器只保存密文。
- **多档案**：可为自己、家人或朋友分别保存独立记录。
- **完整导出**：支持单次记录或单人全部记录导出为 Markdown，也支持 JSON 备份。
- **轻量部署**：默认不需要 MySQL、PostgreSQL、Redis 等数据库。
## 已收录测评
当前共收录 32 个测评。
当前共 32 个测评。
### 人格
### 人格与价值观
| 测评 | 题数 | 主要内容 |
| --- | ---: | --- |
| IPIP Big Five | 50 | 开放性、尽责性、外向性、宜人性、情绪稳定性 |
| IPIP Big Five 120 | 120 | 五大人格及更细分的人格侧面 |
| 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 | 共情、观点采择与个人忧虑 |
| Short Dark Triad | 27 | 马基雅维利主义、自恋与精神病态倾向 |
| HEXACO | 60 | 诚实谦逊及六因素人格结构 |
| Fisher 气质量表 | 40 | 探索者、建设者、指挥者与协商者倾向 |
| Schwartz 价值观量表 | 30 | 十类基本价值观及高阶价值维度 |
| VIA 性格优势量表 | 48 | 24 项性格优势与六类美德 |
| 开放式九型人格量表（OEPS） | 54 | 九型人格倾向 |
| NPI-16 自恋人格量表 | 16 | 自恋相关人格倾向 |
| Brief Self-Control | 13 | 自我控制、冲动控制和习惯管理 |
| ECR-RS 依恋量表 | 9 | 依恋焦虑与依恋回避 |
| IRI 共情量表 | 28 | 共情、观点采择和个人忧虑 |
| Schwartz 价值观量表 | 30 | 十类基本价值观和高阶价值维度 |
| VIA 性格优势量表 | 48 | 24 项性格优势 |
### 认知
### 认知与职业
| 测评 | 题数 | 主要内容 |
| --- | ---: | --- |
| CRT 认知反思测试 | 7 | 直觉反应与分析性思考 |
| CRT 认知反思测试 | 7 | 直觉反应与分析性反思 |
| Need for Cognition | 18 | 主动思考和享受认知活动的倾向 |
| Maximizer | 13 | 决策中的最大化倾向 |
| 成人 ADHD 自评量表（ASRS-v1.1） | 18 | 注意力、冲动和执行功能相关表现 |
| RIASEC 霍兰德职业兴趣 | 48 | 现实型、研究型、艺术型、社会型、企业型、常规型 |
| Career Anchors 职业锚 | 40 | 八类职业价值与职业定位 |
| 成人 ADHD 自评量表 ASRS-v1.1 | 18 | 注意力、冲动和执行功能相关表现 |
### 情绪
### 情绪、压力与心理健康
| 测评 | 题数 | 主要内容 |
| --- | ---: | --- |
@@ -107,43 +86,45 @@
| PSS-10 | 10 | 主观感知压力 |
| BDI-II | 21 | 抑郁相关症状自评 |
| SDS | 20 | 抑郁相关症状自评 |
### 心理健康与睡眠
| 测评 | 题数 | 主要内容 |
| --- | ---: | --- |
| WHO-5 幸福感指数 | 5 | 近期主观幸福感 |
| Yale-Brown 强迫症状量表 | 10 | 强迫观念与强迫行为严重程度 |
| SCL-90 | 90 | 多维度心理症状自评 |
| SCL-90 | 90 | 多维心理症状自评 |
| ISI 失眠严重程度指数 | 7 | 失眠程度及日间影响 |
| 性别认知障碍问卷（GDQ） | 27 | 性别相关体验自评 |
### 职业
| 测评 | 题数 | 主要内容 |
| --- | ---: | --- |
| RIASEC 霍兰德职业兴趣量表 | 48 | 现实型、研究型、艺术型、社会型、企业型、常规型 |
| Career Anchors 职业锚 | 40 | 八类职业价值与职业定位 |
| 游戏障碍问卷 GD | 9 | 游戏相关困扰 |
| 性别认知障碍问卷 GDQ | 27 | 性别相关体验自评 |
## 数据与隐私
项目默认没有服务端数据库，也不会主动把答案发送给第三方分析服务。
MindScope 默认没有传统服务端数据库，也不会主动把答案发送给第三方分析服务。
| 数据 | 保存位置 | 保存时间 |
| 数据 | 保存位置 | 说明 |
| --- | --- | --- |
| 未完成答题草稿 | 浏览器 `localStorage` | 用户清除草稿或浏览器站点数据前 |
| 最近完成的答题答案 | 浏览器 `sessionStorage` | 当前标签页会话结束前 |
| 人物档案与全部测评历史 | 浏览器 `IndexedDB` | 用户删除记录或浏览器站点数据前 |
| 测评结果 Markdown | 用户主动下载的位置 | 由用户自行管理 |
| JSON 或加密 JSON 备份 | 用户主动下载的位置 | 由用户自行管理 |
| 未完成答题草稿 | 浏览器 `localStorage` | 用户清除草稿或站点数据前保留 |
| 最近完成的答题答案 | 浏览器 `sessionStorage` | 当前标签页会话结束前保留，用于结果页展示 |
| 档案与历史记录 | 浏览器 `IndexedDB` | 写入前使用 AES-GCM 加密 |
| 匿名同步记录 | `data/anonymous-store.json` | 浏览器端加密后上传，服务器保存密文 |
| Markdown 导出 | 用户主动下载的位置 | 由用户自行管理 |
| JSON / 加密 JSON 备份 | 用户主动下载的位置 | 可用于迁移或恢复 |
结果页 URL 不携带答案，因此答案不会因为复制页面链接而进入浏览器历史、代理日志或服务器访问日志。复制结果链接只复制页面地址，不包含测评记录；如需保留或交给其他工具分析，请使用“复制完整记录”或“下载 MD”。
结果页 URL 不携带答案，因此复制页面链接不会把测评记录放进浏览器历史、代理日志或服务器访问日志。需要保留或交给其他工具分析时，请使用“复制完整记录”或“下载 MD”。
本地保存不等于绝对安全。使用公共电脑时，完成测评后应关闭标签页，并根据需要清除站点数据或已下载文件。
## 结构化计分
结构化计分元数据位于 `lib/scoring-metadata.ts`。每个量表都会记录：
- `questionnaireVersion`：量表题目版本
- `scoreVersion`：计分逻辑版本
- `min` / `max`：总分或主要维度分数范围
- `reverseItems`：反向题编号
- `thresholds`：临界值或分级阈值
- `direction`：高分方向，区分风险、保护因素、能力表现、人格特质或混合含义
- `highScoreMeaning`：人类可读的高分解释
新增量表时，除了题目和结果页，还必须补充结构化计分元数据，避免旧记录在题目或计分逻辑更新后被错误解释。
## 技术栈
- Next.js 15（App Router）
- Next.js 15 App Router
- React 19
- TypeScript 5
- Tailwind CSS 4
@@ -157,11 +138,11 @@
- Node.js 20 或更高版本
- pnpm 9 或更高版本
建议在开发和生产环境使用相同的 Node.js 主版本，避免依赖构建结果不一致。
建议开发和生产环境使用相同 Node.js 主版本，避免构建结果不一致。
## 获取与更新项目
推荐使用 SSH 克隆。Gitea 的 SSH 服务使用 `2222` 端口：
推荐使用 SSH 克隆。如果 Gitea SSH 服务使用 `2222` 端口：
```bash
git clone ssh://git@git.polarisx.net:2222/mikemoi/MindScope.git
@@ -175,8 +156,6 @@ git clone https://git.polarisx.net/mikemoi/MindScope.git
cd MindScope
```
私有仓库通过 HTTPS 克隆时，请使用 Gitea 用户名和访问令牌，不要把账户密码或访问令牌写进命令、脚本或仓库文件。
服务器已经部署过项目时，使用以下命令获取最新版本并重新构建：
```bash
@@ -193,14 +172,14 @@ sudo systemctl restart mindscope
sudo systemctl status mindscope --no-pager
```
如果以后增加了 `public` 目录，构建后还需要同步公开静态文件：
如果以后增加 `public` 目录，构建后还需要同步公开静态文件：
```bash
rm -rf .next/standalone/public
cp -r public .next/standalone/public
```
`.env*`、`.next`、`node_modules`、日志和本地压缩包已被 `.gitignore` 排除，执行 `git pull` 不会提交或下载这些本地运行文件。更新前如有未提交的源码修改，先运行 `git status` 检查；`git pull --ff-only` 会在分支无法安全快进时停止，而不会自动创建合并提交。
`.env*`、`.next`、`node_modules`、日志和本地压缩包已被 `.gitignore` 排除。更新前如有未提交的源码修改，先运行 `git status` 检查；`git pull --ff-only` 会在无法安全快进时停止，不会自动创建合并提交。
## 本地开发
@@ -209,7 +188,11 @@ pnpm install --frozen-lockfile
pnpm dev
```
浏览器打开：<http://localhost:3000>
浏览器打开：
```text
http://localhost:3000
```
常用命令：
@@ -223,18 +206,16 @@ pnpm lint
# TypeScript 类型检查
pnpm exec tsc --noEmit
# 自动化计分与加密测试
# 自动化测试
pnpm test
# 生产构建
pnpm build
# 使用 Next.js 生产服务器启动
# 启动 Next.js 生产服务器
pnpm start
```
项目目前不依赖环境变量。`.env*` 文件默认不会进入 Git。
## 生产部署
### 直接运行
@@ -247,7 +228,7 @@ pnpm build
NODE_ENV=production PORT=3000 pnpm start
```
生产环境建议只监听本机地址，再由 Nginx 提供公网访问和 HTTPS。
生产环境建议只监听本机地址，再用 Nginx 提供公网访问和 HTTPS。
### Standalone 部署
@@ -264,9 +245,9 @@ cd .next/standalone
HOSTNAME=127.0.0.1 PORT=3000 NODE_ENV=production node server.js
```
当前项目没有 `public` 目录时，第一条复制命令可忽略。`.next/static` 必须复制到 standalone 目录，否则静态资源会缺失。
当前项目没有 `public` 目录时，第一条复制命令可以忽略。`.next/static` 必须复制到 standalone 目录，否则静态资源会缺失。
### systemd 服务示例
### systemd 示例
假设项目源码部署到 `/opt/mindscope`，Node.js 位于 `/usr/bin/node`：
@@ -321,16 +302,16 @@ server {
}
```
配置完成后使用 Certbot 或其他证书工具启用 HTTPS。防火墙通常只需开放 SSH、HTTP 和 HTTPS 端口，应用端口 `3000` 不应直接暴露到公网。
配置完成后使用 Certbot 或其他证书工具启用 HTTPS。防火墙通常只需要开放 SSH、HTTP 和 HTTPS，应用端口 `3000` 不应直接暴露到公网。
### 推荐 VPS 配置
## 推荐 VPS 配置
- 最低：1 核 CPU、1 GB 内存
- 建议：1 核 CPU、2 GB 内存
- 系统：当前受支持的 Debian 或 Ubuntu LTS
- 磁盘：预留至少 2 GB 用于项目、依赖、构建和日志
- 建议：1-2 核 CPU、2 GB 内存
- 系统：Debian 或 Ubuntu LTS
- 磁盘：预留至少 2 GB 给项目、依赖、构建和日志
内存较小的 VPS 可在构建时临时启用 swap，也可以在本地或 CI 构建后只上传 standalone 运行文件。
内存较小的 VPS 可以在构建时临时启用 swap，也可以在本地或 CI 构建后只上传 standalone 运行文件。
## 项目结构
@@ -339,11 +320,11 @@ MindScope/
├── app/ # Next.js 页面、布局和全局样式
├── components/
│ ├── questionnaire/
│ │ ├── test/ # 答题流程和各量表计分器
│ │ └── result/ # 结果展示与 Markdown 导出
│ │ ├── test/ # 答题流程和部分量表计分器
│ │ └── result/ # 结果展示
│ └── ui/ # 通用界面组件
├── hooks/ # React Hooks
├── lib/ # 草稿与结果存储等工具
├── lib/ # 存储、加密、导出、结构化计分等工具
├── locales/zh/ # 中文界面文本
├── questionairies/ # 量表题目、说明和元数据
│ └── zh.ts # 全部量表注册表
@@ -360,40 +341,43 @@ MindScope/
量表列表
-> 量表详情
-> 浏览器答题
-> 本地计分
-> 提交时结构化计分
-> 加密保存记录
-> 结果展示
-> 复制完整记录或下载 Markdown
```
每个量表主要由三部分组成：
每个量表主要由四部分组成：
1. `questionairies/<id>/zh.ts`：题目、选项、说明、分类和参考资料
2. `components/questionnaire/test/private/*Calculator.tsx`：答案转换和计分
3. `components/questionnaire/result/analysis/*Result.tsx`：结果解释与展示
`questionairies/zh.ts` 负责把量表注册到列表，`ResultAnalysis.tsx` 负责将量表 ID 分发到对应的结果组件。
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. 创建结果组件，展示总分、维度和必要的边界说明
5. 在 `ResultAnalysis.tsx` 中注册结果组件
6. 运行 `pnpm lint`、`pnpm exec tsc --noEmit` 和 `pnpm build`
7. 手动完成一次答题，检查草稿恢复、结果计算和 MD 导出
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`
- 稳定唯一的 `id`
- 中文标题和简介
- 一级分类与必要标签
- 题数、预计时间和作答说明
- 计分方法和维度说明
- 最低分、最高分、反向题、临界值和高分含义
- 学术认可度、是否适合重测和建议重测周期
- 使用注意事项及参考资料
- 学术认可度、是否适合重测和建议重测周期（适用时）
## 质量检查
@@ -404,26 +388,26 @@ pnpm lint
pnpm exec tsc --noEmit
pnpm test
pnpm build
pnpm audit --audit-level moderate
```
涉及计分逻辑时，还应人工核对：
- 题目编号是否连续且唯一
- 正向题与反向题是否正确
- 选项值是否与计分器一致
- 维度题目数量是否符合预期
- 最低分、最高分和临界值是否可达
- 未答完时能否阻止生成错误结果
- 刷新结果页和关闭标签页后的行为是否符合隐私设计
- 题目编号是否连续且唯一。
- 正向题与反向题是否正确。
- 选项值是否与计分器一致。
- 维度题目数量是否符合预期。
- 最低分、最高分和临界值是否可达。
- 旧记录是否能通过版本号正确解释。
- 趋势页是否正确解释“高分方向”。
- 刷新结果页和关闭标签页后的行为是否符合隐私设计。
## 使用边界
- 筛查量表只能提示风险或症状程度，不能单独用于诊断
- 不应根据一次测评结果自行停药、换药或改变治疗方案
- 不同翻译版本、计分版本和适用人群可能存在差异
- 用于正式研究、机构服务或商业场景前，应再次核实量表版本、常模、授权和当地法规
- 项目中的结果解释应保持克制，避免把分数描述为确定的人格或疾病结论
- 筛查量表只能提示风险或症状程度，不能单独用于诊断。
- 不应根据一次测评结果自行停药、换药或改变治疗方案。
- 不同翻译版本、计分版本和适用人群可能存在差异。
- 用于正式研究、机构服务或商业场景前，应再次核实量表版本、常模、授权和当地法规。
- 项目中的结果解释应保持克制，避免把分数描述为确定的人格或疾病结论。
## 授权