# Cognition Compass

**Repository Path**: faiz-rlw/cognitive-compass

## Basic Information

- **Project Name**: Cognition Compass
- **Description**: 局域网 AI 八维认知功能测评系统：管理员在 Electron 管理端一键生成测评链接与二维码，局域网用户用手机/电脑浏览器匿名作答；系统采集行为遥测、执行确定性评分定型（概率择优 + 三层置信度），并由独立封装的 AI Agent 模块生成结构化复盘、动态追问与三类报告。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: vite, Electron, Nestjs, Vue, vibecoding

## README

# 认知罗盘（Cognition Compass）

**局域网 AI 八维认知功能测评系统**：管理员在 Electron 管理端一键生成测评链接与二维码，局域网用户用手机/电脑浏览器匿名作答；系统采集行为遥测、执行确定性评分定型（概率择优 + 三层置信度），并由独立封装的 AI Agent 模块生成结构化复盘、动态追问与三类报告。

基于 [fast-vite-nestjs-electron](https://github.com/ArcherGu/fast-vite-nestjs-electron) 模板（Vite + Vue 3 + NestJS 11 + Electron 43 + Doubleshot）构建。业务规则以 `docs/` 目录终审文档为唯一事实来源。

## 功能特性

- **双题库**：标准版 22 题（初始测评）/ 全域精测版 120 题（亚型高分辨），用户在知情同意页自行选定，算法参数完全同源
- **行为遥测**：逐题计时、选项修改次数、极性逆转次数、指针混乱度；"上一题"回看修改、末题二次确认防误交
- **确定性评分引擎**：冲突双阈值检测、证据等级隔离（稳态定型 / 冲突入阴影层）、双场景一致性、能量守恒反作弊、样本兜底、三层置信度分层——纯函数实现，vitest 全量覆盖
- **伦理机制**：知情同意、情绪熔断（连续冲突自动终止且数据不作运算）、危机转介横幅、负面措辞自动改写、结论强制题号溯源
- **AI Agent 大模块**：任意 OpenAI 兼容接口（智谱 / DeepSeek / Qwen / OpenAI…），任务快照制、429/超时自动重试、进程崩溃自愈、失败模板降级（用户流程永不中断）
- **管理端**：实时进度监控（IPC 推送，零网络暴露）、二维码分发、会话筛选分页、复制/续答操作、逐题遥测表与人工复核、事件时间轴、恢复续答/强制完成 SOP
- **数据生命周期**：保留期可配（默认 24 个月，覆盖一年期复测基线），启动自动清理；DB 体积巡检告警

## 架构

```
Electron 主进程 = NestJS hybrid 应用（HTTP 0.0.0.0:3210，可切 127.0.0.1）
├─ Electron IPC ←→ Vue3 管理端（仪表盘/会话详情/题库/AI 设置/设置）
│    └─ 实时监控走 win.webContents.send()（不走网络，无 Socket.IO）
├─ HTTP REST/静态 ←→ 局域网用户浏览器（/api/s/:token 答题→遥测→AI追问→报告，唯一暴露面）
├─ assessment 业务群（题库/会话/答题/评分定型引擎/报告）
├─ ai-agent 独立大模块（provider + context-builder + 三 agent + 护栏 + 异步自愈）
└─ Prisma 7 + SQLite（libsql driver adapter，ABI 稳定）
```

**安全边界**：管理能力只走 IPC；HTTP 仅 `/api/s/:token*`；token 带过期并可作废；匿名作答不收集任何身份信息。**本服务仅限可信局域网，请勿暴露公网。**

## 环境要求

- Node.js ≥ 22（推荐 24），pnpm ≥ 10（仓库锁定 `pnpm@11.5.0`）
- Windows / macOS / Linux 均可开发；打包脚本目前面向 Windows（`pack:dir` / `dist:win`）
- AI 功能需自备任一 OpenAI 兼容接口的 API Key（不配置也能完整跑通，报告走本地模板）

## 快速开始

```bash
pnpm install        # postinstall 自动 prisma generate + git hooks + 原生依赖处理
pnpm dev            # 开发（vite HMR + Electron，自动建库/种子双题库）
pnpm test           # 评分引擎 + DI 防护 vitest 用例
pnpm lint           # eslint
pnpm build          # 构建产物（dist/{main,preload,render}）
pnpm pack:dir       # electron-builder 打包（win-unpacked 免安装目录，镜像已内置）
pnpm dist:win       # 完整 Windows 安装包
pnpm db:studio      # Prisma Studio 浏览数据库
pnpm gen:ddl        # schema 变更后重新生成内置 DDL（随包分发，首启建库用）
```

数据位置：开发期在项目 `data/app.db`；打包版首启在 `%APPDATA%/cognition-compass/` 自动建库（按 `PRAGMA user_version` 幂等建表 + 增量迁移，不依赖 prisma CLI）。

## 使用流程

**管理员**

1. 仪表盘 → 创建测评链接（备注标签 + 有效期）→ 展示局域网 URL 与二维码，发给被测者
2. 实时观察每个会话的逐题进度与冲突标记；链接未开始可复制地址、本机可一键续答
3. 会话详情：逐题遥测表（时长/修改/冲突/权重）、人工复核打标、评分可视化、AI 复盘与三报告、事件时间轴
4. 异常处置 SOP：断崖弃测可「恢复续答」（重开 token）；非情绪熔断可「强制完成」（结果强制低置信且不入全局基线）；情绪熔断受伦理墙保护不可人工越过计算
5. 配置 AI：AI 设置页填 baseUrl / apiKey / 模型名 → 连通性测试 → **勾选启用并保存**（保存校验防"启用但空配置"）

**被测者（局域网浏览器，手机自适应）**

1. 扫码/打开链接 → 阅读知情同意（可随时中止且数据不保存）
2. 选定题库版本 → 22/120 题逐题作答（凭第一直觉，可回看修改）
3. 完成后自动评分；AI 启用时可选做 ≤3 轮深度追问（极限高压零社交情境，优先级阶梯选题）
4. 查看报告：定型结论、八维分布、裂谷归档；每条 AI 结论可**点击溯源**到原始题目与自己当时的作答

## AI 能力说明

| 能力       | 行为                                                                                               |
| ---------- | -------------------------------------------------------------------------------------------------- |
| 结构化复盘 | 综合作答+遥测+评分，输出矛盾/盲区/潜意识冲突，每条结论绑定题号，主动标注误差                       |
| 动态追问   | 优先级：潜意识冲突 ＞ 高低压矛盾 ＞ 模糊维度 ＞ 误判 ＞ 深化；≤3 轮，实时携带历史                  |
| 三类报告   | 核心定型 / 阴影人格（仅冲突数据）/ 潜能发展（负面措辞改写为待发展潜能区域）                        |
| 可靠性     | 任务开始配置快照；鉴权失败立即模板降级；429/超时重试≤2 + 30s 自调度；启动扫描僵尸任务 + 读时懒恢复 |
| 审计       | 每次调用记录请求/响应快照、token 用量与耗时（保留最近 200 条）；月度限额与 80% 预警                |

未配置或调用失败时，全部 AI 产物自动降级为本地确定性模板（标注"模板生成"及原因），测评主流程永不中断。

## 目录结构

```
docs/                     业务终审文档（题库×2、设计手册、速查表——规则唯一事实来源）
prisma/schema.prisma      数据模型（10 表）
scripts/                  gen-ddl / mock-llm / e2e 辅助脚本
src/main/                 NestJS 后端（Electron 主进程）
├── ai-agent/             ★ AI Agent 独立大模块（provider/agents/prompts/guardrails/context-builder/ai-config）
├── answering/            用户答题 REST（唯一 HTTP 暴露面：遥测/熔断/追问）
├── scoring/              评分定型引擎（纯函数 + 单测）
├── session/ audit/ monitor/ admin/ settings/ retention/ database/
src/preload/              contextBridge（adminInvoke / onMonitor）
src/render/               Vue3 前端（views/admin 管理端、views/user 用户答题端）
```

## 数据与隐私

- 全部数据仅存本地 SQLite，不上传互联网；不收集姓名、手机号等身份信息（仅凭随机链接匿名访问）
- 保留期设置页可调（12-36 个月，默认 24），超期终态会话及级联数据启动时清理，**不可恢复**
- API Key v1 以明文存于本地数据库（已知限制，二期接入系统密钥链）
- Windows 首次启动监听局域网端口会弹出防火墙授权，请允许

## 已知限制与二期规划

- 他评互证（≥2 人评价链接）、时间轴复测对比（3 个月/1 年）——数据模型已预留
- API Key 明文 → 系统密钥链
- 打包脚本目前仅 Windows 目标；图标沿用默认（`electron-builder.config.js` 可配）

## 致谢

- 模板：[ArcherGu/fast-vite-nestjs-electron](https://github.com/ArcherGu/fast-vite-nestjs-electron)
- 业务规格：本仓库 `docs/` 终审文档