commit 4da7044c4b3a0e3826019c819538f753ee4e8c48 Author: hangshuo652 Date: Sun Aug 23 11:52:45 2026 +0800 初始提交：ai-review 项目当前版本（含赛道一/二提交规范修订与时间节点文档） diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..46e5299 --- /dev/null +++ b/.gitignore @@ -0,0 +1,27 @@ +# secrets +.env +*.key +**/.env + +# databases & backups +*.db +*.db-shm +*.db-wal +*.db.bak* + +# deps / build +node_modules/ +dist/ +build/ +target/ +__pycache__/ + +# heavy working data +server/data/ +ai-review/server/data/ +server/clone/ +.playwright-mcp/ +screenshots/ + +# misc logs +*.log diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f6d75d6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,257 @@ +# AI-Review 评审系统 + +## 目录 + +``` +ai-review/ +├── server/ # 后端 Express + TypeScript + better-sqlite3 +├── web/ # 前端 React + TypeScript + Vite +├── config/ # teams.json（14 支参赛队伍结构化数据，含 gittea 凭据与选题） +├── docs/ # 文档（评审标准模板、user-stories.md 用户故事） +├── docs/design/ # 设计书（01-系统 / 02-API / 03-后台 / 04-前端） +└── AGENTS.md # 本文件 +``` + +## 启动方式 + +```bash +# 后端（端口 3002） +cd server +npx tsc # 必须先编译（不能直接跑 ts） +node dist/index.js + +# 前端（端口 14001） +cd web +npx vite --host 0.0.0.0 --port 14001 + +# 后端测试（vitest，在 server/ 下运行） +cd server && npm test +``` + +## 关键配置 + +| 项 | 值 | 位置 | +|---|---|---| +| 后端端口 | 3002 | `server/src/config.ts` | +| 前端端口 | 14001 | `web/vite.config.ts` | +| 登录密码 | `620f4c96` | `server/.env` | +| DeepSeek API | `api.deepseek.com` | `server/src/services/review.service.ts` | +| MAX_CONCURRENT | 3 | `review.service.ts` | +| DB 文件 | `server/data/ai-review.db` | `server/src/db.ts` | + +## 核心架构 + +### 评审管线（3 阶段） + +``` +Phase 1: 概览（1 次 AI 调用） +Phase 2: N 子 Agent 并行评审（按标准维度数，concurrency=3） +Phase 3: 确定性校准(computeCalibration) + 硬规则引擎 +``` + +### 核心文件 + +| 文件 | 职责 | +|------|------| +| `review.service.ts` (~1500行) | 评审引擎：clone→tryBuild→tryBrowse→AI→校准(computeCalibration)→硬规则→出分 | +| `standards.ts` | `parseDimensions` 解析标准 MD 为维度列表 | +| `entries.ts` | 条目 CRUD + 触发评审 + PDF 导出 | +| `projects.ts` | 项目 CRUD + 汇总排名 | +| `db.ts` | SQLite 初始化 + migrations（ALTER TABLE try/catch） | +| `config.ts` | 端口/密码/DeepSeek key | + +### 关键流程 + +``` +cloneRepo → discoverFiles → countCodeStats → tryBuild → tryBrowse/tryStart +→ 概览(精简context) → N子Agent(content+fileBlock) → 校准(computeCalibration) → 硬规则 +→ 总分(rawScore) → 迟交扣分 → finalScore → review_snapshots +``` + +## 关键事实（修改前必读） + +### 编译与重启 + +- TS 改动后必须 `cd server && npx tsc`，不能只改 .ts 不编译 +- `server/dist/` 编译输出和 `server/src/` 分离 +- 启动：必须用 `node dist/index.js`（不能 `tsx watch`，那需要 dev 模式） +- 服务器崩溃后启动会自动恢复卡死的 entry（状态重置为 pending） + +### tryBuild + +- 支持 7 种构建系统：npm/pom.xml/build.gradle/makefile/cargo/go/pyproject +- Python build 命令是 `python -m build --wheel --no-isolation`（不是 `pip install -e .`） +- `buildRootMap[file] === undefined` 判断是否存在（不是 falsy，根目录文件 relDir=""） +- `canBuild` 过滤 install 步骤：`!command.startsWith('npm install')` 和 `!command.startsWith('pip install')` + +### tryBrowse + +- 用 `puppeteer-core` + 自动检测 Chrome/Edge 路径（不自带 Chromium） +- `waitUntil: 'domcontentloaded'`（不是 `networkidle0`，对 API 服务太严格） +- `service_url` 提供时跳过 tryStart，直接 browse 该 URL +- **看门狗**：整体 45s 硬超时（BROWSE_WATCHDOG_MS），Chrome 启动/加载/关闭任一环节挂住也会被强制 kill 并降级为"跳过浏览器测试"，不会卡死评审管线 +- **评审期二次 SSRF 校验**（`revalidateHost`）：打开 URL 前重新 DNS 解析域名，若已变为内网地址（重绑定攻击）则拦截并跳过浏览器测试；仅 `config.ssrfDnsCheck` 开启时生效 + +### 维度评审（runSubAgent） + +- 评审依据优先级：**标准快照 `dim.content` 优先且唯一**；内置 `dimGuidelines` 仅当 content 为空时兜底（并标注"内置兜底，仅供参考"）。不要两套规则同时注入，否则 AI 会困惑 +- `dimGuidelines` 是硬编码指南（key：场景价值/架构设计/工具使用/实现完整/开发范式/Agent核心/规模/代码规范/演示与文档/AI使用日志/效果与数据等），分值小计可能≠maxScore，仅兜底用 +- `DIM_FILE_FILTERS` 按维度过滤文件（如代码规范只给源码，演示文档只给 .md） +- `filterFilesForDim` 输出时给文档文件标注 `（文档/说明文件，非代码）`，防止 AI 把 README/CLAUDE.md 内容当作代码问题上报 +- `fileBlock` 截断：普通维度 15000 字，构建维度 40000 字 +- `DIM_FILE_FILTERS` 的 `'AI使用日志'` 正则需同时覆盖 `ai_log`/`ai_usage`/`usage_log`（如 `_AI_USAGE_LOG.md`），否则该文件被过滤、AI 判"未发现日志"（2026-08-18 实测修复） +- `extraContext` 只对构建维度（实现完整度）附加构建步骤详情 +- `projectContext` 包含服务状态行：`参赛者服务地址: xxx（可正常访问/无法访问）` + +### 确定性证据（方案一 / 方案二，2026-08-07 新增） + +- **方案一 `evidence-detect.ts`**：Agent核心能力 4 项硬门槛由代码模式匹配做**确定性判定**（LLM调用/工具选择策略/错误重试降级/状态持久化），AI 不再判门槛、只做 5 项评分要素。检测结果（文件:行号）注入 Agent核心维度 prompt，含 `allPassed` 结论 +- **方案二 `test-runner.ts`**：`tryTest` 在构建可用的前提下真跑测试。支持多框架输出解析——pytest/jest/go test -v/surefire(Maven)/Gradle tests completed/Cargo test result；覆盖率解析含 pytest-cov/jest/istanbul/go cover/jacoco。go test 自动加 `-v -cover`。**软证据**——成功才注入真实通过率/覆盖率到"效果与数据"维度；环境失败/工具缺失一律**中性不扣分**（不证明项目差） +- **tryTest 与构建完全解耦**（2026-08-13）：无条件跑测试，不依赖 `buildResult.canBuild`。构建失败 ≠ 测试不可跑（cobol-java 的 build-backend 写错打不了包，但 pytest 能真跑 33/42）。`runTest` 完整保留输出供解析——**汇总行在输出尾部，截断到 3000 字会丢 passed/coverage 汇总**（曾导致 testsPassed=0、覆盖率 null） +- **维度独立原则**（`review.service.ts` runSubAgent 严格规则）：每个维度独立评分，其他维度的判定（如 Agent核心门槛是否通过、项目是否为 Agent 应用）**不构成扣分依据**——"效果与数据"评估测试覆盖/覆盖率/可复现性，即使非 Agent 项目，测试真实存在且通过就应据实给分 +- **确定性测试证据强绑定**：tryTest 真跑成功时 `testEvidenceToPrompt` 注入"确定性证据，评分必须据此"，AI 不得忽略或低估真实通过率/覆盖率（实测生效：calc 项目 Agent核心 0/25 但效果与数据 15/20 正常给分；cobol-java 效果与数据 0/20→6/20，AI 引用"42个用例33通过"） +- **Agent核心检测置信度**：`buildAgentGateReport` 按命中数标注置信度——0/低(1)/中(2-3)/高(≥4)；低置信度通过项注入提示"可能误匹配，可在评分要素中酌情下调，但不得推翻门槛判定" +- 阈值常量在 `evidence-detect.ts`：MAX_HITS=5；`test-runner.ts`：TEST_TIMEOUT=180s + +### 校准（Phase 3b，确定性） + +- `computeCalibration`（`standard-utils.ts`）由代码计算，**不信任 LLM 的 delta 数值** +- LLM 只输出跨维度语义矛盾的方向（over/under），代码定调幅：L1 矛盾±2、L2 σ异常(偏离>2σ)±4、L3 最不稳定维度(Agent核心/规模·功能点/效果与数据)高估×0.8 +- 调幅常量在 `review-constants.ts`：CAL_ANOMALY_STDDEV=2.0 / CAL_L2_LIMIT=4 / CAL_L1_LIMIT=2 / CAL_UNSTABLE_WEIGHT=0.8 +- 每个实际改动写入 `calibrationExplanation`（格式：`校准执行:\n- 维度: 旧分→新分（L1/L2/L3）`），可审计 +- 老的 `applyCalibration`（LLM-delta）已删除，不要引用 + +### 代码健康度（countCodeStats） + +- 返回 CodeStats：fileCount/totalLines/effectiveLines/blankLines/commentLines/duplicateRatio/dirDepth/tinyFiles +- `duplicateRatio` 用 MD5 哈希文件内容检测 +- `dirDepth.avg` 追踪目录嵌套深度 +- 结果注入 `projectContext` 供 AI 参考 + +### 硬规则（Phase 3c，校准后执行） + +- 构建失败→实现完整度≤4/12，效果与数据≤3/10 +- pytest 失败→效果与数据≤5/10 +- 重复代码>50%→代码规范≤3/5 +- 无根目录 README→演示与文档≤2/5 +- 日志写入 calibrationExplanation + +### 评分 + +- 校准 delta 用 `Math.round()` 取整（避免 52.400000000000006） +- 总分 = `Math.round(每个维度分数)` 累加 +- `finalScore` = `totalScore - 迟交扣分`，上限 `max_score_cap` +- 迟交判定（2026-08-15 增强）：`resolveSubmitTime` 解析提交时间——优先 git 最后 commit 时间；commit 缺失或早于条目创建时间（空仓库/提前 clone 旧代码/无 .git）→ 用条目创建时间兜底避免逃逸；两者都无效才用评审时刻。然后 `computeLateDays` 对比 `project.deadline` + +### 评审可信度（2026-08-19） + +- **排名用多次聚合**：`aggregateScores`/`aggregateEntryScores`（standard-utils.ts）——最近 N 次（默认3）`review_snapshots.score` 中位数；N=2 平均、N=1 单次。聚合前提=各快照 `standard_snapshot` 一致。`<3 次标"初评（未达聚合样本）"`，排名区分正式/初评 +- **快照分数列**：`review_snapshots.score` 存含迟交扣分的 final_score（写快照时一并存，不解析 ai_report——它只有 totalScore）。历史快照 backfill 从 totalScore best-effort +- **可验证能力三档**（`classifyVerifiability`，效果/提效类维度，校准之前判档）：A=基准证据（`entries.benchmark_json` status=done）；B=测试通过或覆盖率非 null；C=数据缺位→封顶 maxScore*0.3 + note"数据缺位（未证明），非无效"。**构建成功≠效果可验证**。C 档 note 渲染到前端维度表 + PDF +- **基准证据按 entry 落库**（`entries.benchmark_json`，非 env 变量——MAX_CONCURRENT=3 并发会串数据） +- **确定性 L1**（`detectStructuralContradictions`）：仅证据性矛盾触发（有测试/基准证据但效果≈0 → under；效果高分+实现全低 → over）。**效果维度 under 一律丢弃**（computeCalibration 内过滤）——效果维度只降不升，诚实由三档封顶负责。禁止"实现高分+无数据"当 under +- **overall 中性边界**（`neutralizeTestEvidence`）：测试 summary 含"中性"→ 标 `[中性证据]`；不含（"未检测到测试框架配置"=真缺测试）→ 真实弱点。synthesizeOverall prompt 禁止把 `[中性证据]` 列为不足 +- **视频 URL 弱证据**：`detectDemoVideo` 扫根目录 README + 根级 docs/*.md 的视频链接，source='url'（外部链接未核验）vs 'file'（强证据优先） +- **维度级聚合**：详情/PDF 维度表用 `averageDimensions` 跨快照聚合（entries.ts GET /:entryId 返回 dimsAgg），展示"历次分差" +- **决赛圈基准框架**：`benchmark.ts` `runBenchmark(dir, seeds, detect)`，检出率与基线分开呈现。seed 库赛前生成不公开（Goodhart 已知上限） +- **人机标定**：`docs/design/06-人机标定方案.md`——绝对准确未验证前，分数用于排名（相对序）可信，绝对解读需标定偏差基线 + +### parseDimensions + +- 正则在 `standards.ts`，修复后支持空内容（`content: ""`） +- 从 `## 维度名（分数）` 解析，必须紧跟 `\n## ` 或字符串结束 +- 过滤分区/说明性标题：`评审维度`、`合格判定`、`成果物清单`、`第X部分：` 等不进入维度列表 +- group 推断：`## [Q2] xxx`（显式）或 `## 2-A. xxx` / `## 2-A：xxx`（人才测评追加维度前缀）→ group=Q2；其余 common +- 验证：三个标准模板解析结果应固定为——赛道一 12维/150、赛道二 8维/100、人才测评 common100+maxBonus50/effective150（Q2-Q6 分组正确） + +### entries 表 + +- `UNIQUE(project_id, repo_url)` 约束 +- `service_url TEXT DEFAULT ''`（migration 添加） +- `build_status TEXT DEFAULT ''`（2026-08-18，migration 添加）：赛道二/人才测评单阶段人工构建确认，''=未确认(自动构建) / done / failed；赛道一 B 阶段不存此列，走 /verify 请求体 +- `standard_snapshot` 存标准快照（评审时标准被修改也不影响已评审结果） +- `review_snapshots` 存每次评审历史 +- force-review（测试端点）需 `ADMIN_TEST_TOKEN=true` **且** `NODE_ENV=test` 双条件才开启；生产 `node dist/index.js` 即使 flag 泄漏也打不开 +- **赛道必选（2026-08-13）**：创建/编辑项目必须传 track（赛道一/赛道二/人才测评），缺省返回 400 `赛道为必选项`；前端下拉首项"请选择赛道（必选）"，create() 校验 `if (!track) setError('请选择赛道')`。注意：有赛道会自动导入对应默认标准（`projects.ts` POST 里 `loadDefaultStandard`）——创建项目的测试用例必须带合法 track，否则建出的项目无赛道且后续标准解析行为不同。**e2e 陷阱**：依赖"自定义标准快照"的用例（如 `hardcode-fixes.spec.ts` 3.1/3.2）在带 track 创建项目后，自动标准会抢占 `resolveStandard` 匹配，导致条目快照不是测试上传的标准——需先调用 `apiClearStandards(request, token, pid)` 清掉自动标准再上传自定义标准 + +### 本地评审样本 + +- `server/data/clone/_real_cobol_java/`：真实仓库（cobol-java-v3，COBOL→Java 测试生成工具）的本地副本，作真实评审冒烟对象 +- 用它跑过 6 次真实 DeepSeek 评审：30（旧校准）→52（确定性门槛）→58→67（效果与数据 0→6，tryTest 解耦构建后）→55（第 5 次评审，校准 anomalies 触发的自然波动）。数据在 `data/e2e-usertest.db` 的 review_snapshots（该项目 track=赛道一，12 维标准） +- **注意：评审结束会删除 clone 目录**（`executeReview` 末尾 `fs.rmSync(dir)`），只留 review_snapshots；若需现场调试 clone 内容，评审前复制一份出来 + +### 管线诊断日志（`[pipe:entryId]`） + +- `pipeLog(entryId, phase, msg, durMs?)` 只写服务端 console（不进 progress_log，不污染前端） +- 覆盖阶段：START / CLONE / ANALYZE（含 canBuild·untested）/ GATES / TEST（command·pass/fail·coverage·summary，**这是"证据静默丢失"类问题的 debug 入口**）/ BROWSE（serviceUrl·pageLoaded）/ OVERVIEW / SUBAGENT（12 个 DIM 各带耗时）/ **OVERALL**（整体评价合成，pos/hl/wk，失败打印 failed）/ DONE（score·penalty·final·总耗时）/ **FAIL**（`runReview` catch 兜底，任何阶段抛错都会有 `[pipe:xxx] FAIL [耗时ms]`，不会再静默卡 status=failed） +- 实测 cobol 第 5 次评审：ANALYZE 24s（tryBuild 跑 python 构建超时）、TEST 10s（`python -m pytest` 33/42 pass、coverage null）、DIM 每维度 4.6~24.7s、全程 114s + +### 整体评价合成（方案A，2026-08-19） + +- `synthesizeOverall`（review.service.ts）：校准+硬规则之后，+1 次 LLM 调用（约 15-30s），把 overview+维度得分评语+确定性证据合成**点评式**整体评价，写入 `ai_report.overall`（JSON：highlights[{point,review}]/weaknesses[{point,review}]/verdict） +- **项目总览（overview）负责中立描述，overall 只做点评**：每条亮点/不足都带判断（价值/影响/严重度），不重复定位 +- 输入全是真实证据，prompt 显式"禁止编造"；失败非致命（overall=null，不影响评分） +- 兼容旧格式（字符串数组 → point，review 空） +- 落点：赛道一 B 尾（executeReviewB）与赛道二单阶段尾（executeReview）各一次；A 阶段不合成 +- 展示：前端条目详情"整体评价"段（亮点点评绿/不足点评红/总评，ProjectView.tsx）+ PDF 报告块（pdf.service.ts） +- 纯函数 `parseOverallResponse` 负责 JSON 解析/代码块剥离/裁剪（overall.test.ts 单测 7 用例） + +## 已知坑 + +1. **Chrome 崩溃导致服务器卡死（已缓解）** — tryBrowse 有整体 45s 看门狗（BROWSE_WATCHDOG_MS），挂住会强制 kill Chrome 并降级"跳过浏览器测试"，但仍建议留意 browse 期间系统资源占用 +2. **多人提交排队** — MAX_CONCURRENT=3，第 4 个 entry 起入队列排队等空位（`queue[]` + `processQueue`） +3. **AI 从 docs 编造代码问题（已缓解）** — fileBlock 中文档文件已标注 `（文档/说明文件，非代码）`，但 AI 仍可能把标准模板内容误当代码问题，若再出现可在 prompt 强化 +4. **tryBrowse SSRF 风险（已缓解）** — service_url 保存时校验 + 评审期 `revalidateHost` 二次 DNS 解析（重绑定拦截，仅 `config.ssrfDnsCheck` 开启时生效），仍建议沙箱 +5. **review.service.ts 1060 行** — 单文件过大，改动前必须理解整个 pipeline +6. **difficulty 字段已移除** — 不要搜或引用 difficulty（前端已改为"赛道"下拉） +7. **本地 file:// 仓库 URL 格式** — 必须用 `file://D:/...`（两斜杠）；`file:///D:/...`（三斜杠）会被 `path.resolve` 解析成 `D:\D:\...` 导致白名单拒绝（2026-08-07 实测） +8. **测试数据会污染"真实数据"判断** — 库里大量 `选手X/小明作品/k4-entry` 是 e2e 造的假条目；判断真实评审数据要看 `repo_url`（真实 https/本地副本）而非条目名 + +## 测试 + +```bash +# 后端单元测试（vitest） +cd server && npm test + +# 特定测试文件 +cd server && npm test -- src/__tests__/api.test.ts + +# 用户故事驱动验收（docs/user-stories.md，纯函数级，不调 AI，20 用例） +cd server && npm test -- src/__tests__/user-stories.test.ts + +# E2E（需前后端都启动） +# web/e2e 目录有 Playwright 测试 + +## E2E 运行陷阱（2026-08-14 实测） + +- **整套 full-e2e 需 15+ 分钟**，单个 describe 单独跑更快（评审标准 7、条目管理 10、批量/详情/汇总/异常/UI 27、完整流程 1 = 45 个测试）。整套跑超时是正常现象，不是 bug +- **孤儿 tsx server 会卡死所有 DB 请求**：多次中断 e2e 会残留多组 `tsx src/index.ts` 进程同时打开 `data/ai-review.db`，better-sqlite3 WAL 锁冲突导致 login/beforeAll 全部挂起 90s。症状：health 慢、login 超时、beforeAll timeout。排查：`Get-CimInstance Win32_Process -Filter "Name='node.exe'" | where CommandLine -like "*tsx*src/index.ts*"`，全杀后重跑 +- **`apiClearStandards` 的 BASE 必须带 `/api`**（`http://localhost:3002/api`），漏掉会打到 `/projects/:id/standards`（无路由）返回 404 HTML，`list.json()` 抛 `SyntaxError: Unexpected token '<'` +- **补 track 后项目头部和表格赛道列都会渲染 `赛道一`**，原 `.badge` 选择器断言会多命中——用 `.entry-table .badge` 限定，且状态文案是中文（`待评审` 而非 `pending`，见 `ProjectView.tsx` statusBadge） +``` + +## 数据库操作 + +```bash +# 手动查 SQLite +cd server && node -e "const D=require('better-sqlite3');const d=new D('data/ai-review.db');console.log(d.prepare('SELECT name FROM sqlite_master WHERE type=\"table\"').all())" +``` + +## 评审标准格式 + +```markdown +## 维度名（满分X分） +内容描述... +## 下一个维度（满分Y分） +内容描述... +``` + +标准 MD 必须至少有一个 `## 维度名（分数）` 格式的标题。 + +### 内置标准模板（由项目管理员上传） + +**赛道一（Agent开发实战赛）：** 场景价值15、开发范式与架构设计25、工具使用10、实现完整度15、规模·功能点·技术难度10、演示与文档5、AI使用日志10、效果评估与数据10 + +**赛道二（IDE+开发范式创新赛）：** 场景价值、开发范式、工具使用、实现完整度、规模·功能点、演示与文档、AI使用日志、效果评估与数据（总分100） + +当前维度 guideline 只覆盖标准维度名（如"场景价值与合理性"），赛道一变体名（如"开发范式与架构设计"）需扩展匹配关键词。 diff --git a/AI人才育成评审系统_设计书.md b/AI人才育成评审系统_设计书.md new file mode 100644 index 0000000..c824044 --- /dev/null +++ b/AI人才育成评审系统_设计书.md @@ -0,0 +1,454 @@ +# AI人才育成评审系统 设计书 + +> 版本: v1.0 +> 适用: AuraK 评审系统 + +--- + +## 1. 概要 + +### 1.1 目的 + +在 AuraK 系统中实现 AI 人才育成 L2/L3 评审功能，支持三个赛道的评审标准管理： +- 技术大赛·赛道一（Agent开发实战） +- 技术大赛·赛道二（IDE+开发范式创新） +- AI人才育成L2（人才测评） + +### 1.2 术语 + +| 术语 | 说明 | +|------|------| +| 共通维度 | 所有题目共享的评审维度（满分100分） | +| 追加维度 | 特定题目独有的L3评审维度 | +| L2合格 | 共通维度得分率 ≥ 60% | +| L3合格 | 总分（共通+追加）得分率 ≥ 80% | + +--- + +## 2. 赛道设计 + +### 2.1 三个赛道 + +| 赛道 | track值 | 总分 | 说明 | +|:----|:--------|:----:|------| +| 技术大赛·赛道一 | `赛道一` | 150 | Agent开发实战，分新規/修正 | +| 技术大赛·赛道二 | `赛道二` | 100 | IDE+开发范式创新 | +| AI人才育成L2 | `人才测评` | 100~150 | 6道题，按难度追加 | + +### 2.2 标准文件 + +系统内置三个标准模板，存放在 `server/config/standards/` 目录下。 + +``` +server/config/standards/ +├── 技术大赛-赛道一.md （150分，11个维度） +├── 技术大赛-赛道二.md （100分，7个维度） +└── AI人才育成L2.md （100~150分，共通6维度+各题追加维度） +``` + +服务启动时自动加载，创建项目时根据 track 字段自动关联对应的标准模板。 + +--- + +## 3. 数据模型 + +### 3.1 Project 表 + +``` +ALTER TABLE projects ADD COLUMN track TEXT DEFAULT ''; +``` + +| 值 | 含义 | +|:---|:------| +| `赛道一` | 技术大赛·Agent开发实战 | +| `赛道二` | 技术大赛·IDE+开发范式创新 | +| `人才测评` | AI人才育成L2 | +| `''` | 旧项目（向后兼容） | + +### 3.2 Entry 表 + +仅新增一个字段： + +| 字段 | 类型 | 说明 | +|:----|:----|------| +| `question_id` | TEXT | 人才测评时记录选题（Q1~Q6），其他赛道留空 | + +L3追加分数和最终认定等级均为运行时计算，不存数据库。 + +### 3.3 合格判定用计算字段 + +``` +l2_score = 共通维度得分之和（满分100） +l2_passed = l2_score >= 60 + +l3_total = l2_score + l3_bonus_score （仅★★★/★★★★适用） +l3_max = 100 + l3_bonus_max +l3_passed = l3_total / l3_max >= 0.8 （仅★★★/★★★★适用） + +final_level = + l3_passed ? 'L3' : + l2_passed ? 'L2' : + '不合格' +``` + +--- + +## 4. 标准文件格式 + +### 4.1 三个标准的维度构成 + +#### 技术大赛·赛道一（150分） + +沿用现有的11维度标准，不做变更。创建项目时自动关联。 + +#### 技术大赛·赛道二（100分） + +沿用现有的7维度标准，不做变更。创建项目时自动关联。 + +#### AI人才育成L2（100~150分） + +``` +共通维度（所有题目评分）： + ## 功能完整性（40分） + ## 设计文档（10分） + ## 测试用例与测试结果（10分） + ## AI协作过程记录（15分） + ## 技术选型与范式运用（15分） + ## 代码质量 + README（10分） + +追加维度（按题目评分）： + ## [Q2] LLM生成问卷（15分） + ## [Q2] LLM自由文本分析（10分） + ## [Q2] prompt工程与调优记录（5分） + + ## [Q3] LLM检索回答（11分） + ## [Q3] 上下文连续对话（10分） + ## [Q3] 无法回答处理（10分） + ## [Q3] RAG管道设计记录（19分） + + ## [Q4] LLM条款提取（10分） + ## [Q4] LLM风险标记（10分） + ## [Q4] prompt工程与规则设计记录（10分） + + ## [Q5] LLM内容提取（10分） + ## [Q5] LLM影响度评估（10分） + ## [Q5] prompt工程与爬虫策略记录（10分） + + ## [Q6] LLM风险分类（10分） + ## [Q6] LLM影响度评估（10分） + ## [Q6] prompt工程与分类策略记录（10分） +``` + +### 4.2 维度分组标记 + +标准文件中，追加维度用 `[Qn]` 前缀标记。解析时提取分组信息： + +```typescript +interface Dimension { + name: string; + maxScore: number; + content: string; + group?: string; // 'common' | 'Q1' | 'Q2' | ... +} +``` + +解析逻辑： + +``` +function parseDimensionWithGroup(line: string): Dimension { + const match = line.match(/^##\s+\[?(Q\d)?\]?\s*(.+?)（(\d+)分）/); + return { + name: match[2].trim(), + maxScore: parseInt(match[3]), + group: match[1] || 'common' // 无前缀为共通维度 + }; +} +``` + +### 4.3 维度过滤规则 + +``` +function getDimensionsForQuestion(standard, questionId): + dims = parseDimensions(standard.content) + return dims.filter(d => + d.group === 'common' || // 共通维度，全部保留 + d.group === questionId // 只保留当前题目的追加维度 + ) +``` + +--- + +## 5. 评审流程 + +### 5.1 评审入口 + +``` +受理验者提交代码 + │ + ├─ project.track = '人才测评' ? + │ │ + │ 是 → 根据 question_id 确定追加维度 + │ │ Q1：无追加维度（仅L2） + │ │ Q2/Q4/Q5/Q6：追加30分 + │ │ Q3：追加50分 + │ │ + │ 否 → 普通评审（赛道一/赛道二） + │ + └─ 进入评审环节 +``` + +### 5.2 L2/L3 一次评审 + +AI一次评审所有维度（共通+追加），不分开调用。评审结果在计算层拆分。 + +``` +AI一次评审所有维度 + │ + ├─ 共通维度得分 ≥ 60 → L2合格 + │ │ + │ └─ 是★★★/★★★★题目？ + │ │ + │ 是 → 计算总分 + │ │ （共通得分 + 追加得分） + │ │ 总分/满分 ≥ 80% → L3合格 + │ │ 总分/满分 < 80% → 仅L2合格 + │ │ + │ 否 → 最终认定L2 + │ + └─ 共通维度得分 < 60 → 不合格 +``` + +> 优点：AI只调用一次，节省API费用。 +> 评审结果中两个部分同时返回，计算层拆开统计。不涉及追加评审的题目（Q1），AI仍会看到追加维度，但会被计算层忽略。 + +### 5.4 分数计算逻辑 + +``` +function calculateResults(dimResults, questionId, difficulty): + // 共通维度得分 + commonDims = dimResults.filter(d => isCommonDim(d)) + commonScore = commonDims.reduce(sum, 0) + l2Passed = commonScore >= 60 + + // L3追加维度得分 + if (difficulty >= 3 && l2Passed): + bonusDims = dimResults.filter(d => isBonusDimFor(d, questionId)) + bonusScore = bonusDims.reduce(sum, 0) + bonusMax = 30 // ★★★ + if (difficulty == 4) bonusMax = 50 // ★★★★ + totalScore = commonScore + bonusScore + l3Passed = (totalScore / (100 + bonusMax)) >= 0.8 + else: + bonusScore = 0 + l3Passed = false + + return { l2Passed, l3Passed, commonScore, bonusScore } +``` + +--- + +## 6. 合格判定一览 + +| 难度 | 共通满分 | 追加满分 | 总分上限 | L2合格 | L3合格 | +|:----:|:--------:|:--------:|:--------:|:------:|:------:| +| ★★ | 100 | 0 | 100 | ≥60分 | 不适用 | +| ★★★ | 100 | 30 | 130 | ≥60分 | ≥104分 | +| ★★★★ | 100 | 50 | 150 | ≥60分 | ≥120分 | + +--- + +## 7. 标准模板管理 + +### 7.1 内置模板与创建流程 + +``` +创建项目 + │ + 选择名称 + 赛道 + │ + └─ track = '赛道一' → 自动关联 技术大赛-赛道一.md + └─ track = '赛道二' → 自动关联 技术大赛-赛道二.md + └─ track = '人才测评' → 自动关联 AI人才育成L2.md + └─ track = '' → 无默认标准（手动上传） +``` + +### 7.2 标准上传校验 + +从配置文件读取上限： + +```ini +# .env +STANDARD_MAX_SCORE=150 +``` + +- 上传标准时校验总分 ≤ STANDARD_MAX_SCORE +- 默认150分，可根据需要调整 +- 现有100分限制不再写死 + +> **配置修改步骤**： +> 1. 修改 `server/.env` 中的 `STANDARD_MAX_SCORE` 值 +> 2. 重启后端服务 `node dist/index.js` +> 3. 确认启动日志中打印了新的上限值 + +### 7.3 标准模板查看 + +项目详情页的"标准"标签页中，当前关联的标准模板内容可直接预览： + +``` +┌──────────────────────────────────────┐ +│ 当前使用标准: AI人才育成L2评审标准 │ +│ 总分: 150分 | 维度: 22个 │ +│ │ +│ ┌─ 共通维度（6个）──────────────────┐ │ +│ │ 功能完整性 40分 │ │ +│ │ 设计文档 10分 │ │ +│ │ 测试用例与测试结果 10分 │ │ +│ │ AI协作过程记录 15分 │ │ +│ │ 技术选型与范式运用 15分 │ │ +│ │ 代码质量 + README 10分 │ │ +│ └──────────────────────────────────┘ │ +│ │ +│ ┌─ 追加维度（按题目）──────────────┐ │ +│ │ Q2 LLM生成问卷 15分 │ │ +│ │ Q2 LLM自由文本分析 10分 │ │ +│ │ ... │ │ +│ └──────────────────────────────────┘ │ +└──────────────────────────────────────┘ +``` + +--- + +## 8. 前端变更 + +### 8.1 项目创建 + +维持现有的赛道选择器不变。 + +### 8.2 条目创建（人才测评赛道） + +``` +条目标题: __________________ +仓库URL: __________________ +参赛者: __________________ +问题选择: [Q1 满意度调查(★★)] + [Q2 面谈问卷(★★★)] + [Q3 RAG检索(★★★★)] + [Q4 合同审查(★★★)] + [Q5 法规爬虫(★★★)] + [Q6 风险情报(★★★)] + +选择问题后显示： + L2共通评分：100分 + L3追加评分：30分（Q2/Q4/Q5/Q6）或50分（Q3） + +#### 提交校验 + +人才测评条目提交时需满足： + +```typescript +if (project.track === '人才测评' && !question_id) { + return res.status(400).json({ error: '人才测评条目必须选择题目' }); +} +``` +``` + +### 8.3 评审结果展示 + +#### L2/L3分层显示 + +共通维度和追加维度分开区域显示： + +``` +┌─────────────────────────────────────┐ +│ 最终认定: 🏆 L3合格 │ +│ 总分: 125 / 150 (83%) │ +├─────────────────────────────────────┤ +│ L2共通评分（100分） │ +│ │ +│ 功能完整性 32 / 40 │ +│ 设计文档 8 / 10 │ +│ 测试用例与测试结果 7 / 10 │ +│ AI协作过程记录 11 / 15 │ +│ 技术选型与范式运用 10 / 15 │ +│ 代码质量 + README 8 / 10 │ +│ ──────────────────────────────── │ +│ L2小计 76 / 100 │ +│ L2结果: ✅ 合格 │ +├─────────────────────────────────────┤ +│ L3追加评分（50分） │ +│ │ +│ LLM检索回答 9 / 11 │ +│ 上下文连续对话 7 / 10 │ +│ 无法回答处理 8 / 10 │ +│ RAG管道设计记录 14 / 19 │ +│ ──────────────────────────────── │ +│ L3小计 38 / 50 │ +│ L3结果: ✅ 合格 │ +└─────────────────────────────────────┘ +``` + +| 状态 | 显示规则 | +|:----|---------| +| L3合格 | 显示共通+追加两个区域，最终认定 🏆 L3合格 | +| 仅L2合格（★★★/★★★★） | 仅显示共通区域，追加区域灰显，标注"L3不适用"或"未达L3标准" | +| ★★题目 | 仅显示共通区域，追加区域不显示 | +| 不合格 | 仅显示共通区域，标注 ❌ 不合格 | + +--- + +## 9. 实现计划 + +| 阶段 | 内容 | +|:----|------| +| Phase 1 | DB加字段（question_id, l3_bonus_score等） | +| Phase 2 | 创建3个标准模板文件 | +| Phase 3 | 修改 resolveStandard，根据 track 自动匹配模板 | +| Phase 4 | 解除总分100分限制 | +| Phase 5 | 修改评审逻辑，支持维度过滤和L2/L3判定 | +| Phase 6 | 修改前端条目创建表单（问题选择） | +| Phase 7 | 修改前端评审结果展示（L2/L3分层显示） | +| Phase 8 | 测试验证 | + +--- + +## 10. 多角度评审 + +### 10.1 架构评审 + +| 检查项 | 判定 | 理由 | +|:-------|:----:|------| +| 现有数据模型是否需要大改？ | ✅ 无 | 仅加少数字段，现有功能不受影响 | +| 标准文件是否需要重构？ | ✅ 无 | 赛道一/赛道二照旧，人才测评追加维度用前缀区分 | +| 评审流程是否清晰？ | ✅ 清楚 | L2→L3的判定路径不含糊 | +| 向后兼容？ | ✅ 保证 | track=''的旧项目正常运作 | + +### 10.2 数据流评审 + +``` +上传标准 → parseDimensions → 维度数组 + ↓ +创建条目 → resolveStandard → 关联标准 + ↓ +启动评审 → filterDimsByQuestion → 有效维度 + ↓ +AI评审 → 打分 → calculateResults → 合格判定 +``` + +### 10.3 边界条件 + +| 场景 | 处理 | +|:-----|:-----| +| 旧项目没有track | 沿用现有逻辑，不触发人才测评流程 | +| 人才测评选了Q1（★★） | 只有共通100分，L3不适用 | +| Q2（★★★）共通得了70分，追加得了20分 | 总分90/130=69% → 仅L2合格 | +| Q3（★★★★）共通得了85分，追加得了40分 | 总分125/150=83% → L3合格 | +| 人才测评但没选问题 | 拒绝创建条目，提示必选 | +| 新赛道一项目直接创建（150分） | 自动关联模板，正常使用 | + +### 10.4 风险点 + +| 风险 | 影响 | 对策 | +|:-----|:-----|:-----| +| 原有标准上传功能仍可用，用户可能上传不正确的人才测评标准 | 评审结果异常 | 建议用户使用内置模板 | +| L3判定标准（80%）是否合理 | 可能需要调整 | 上线后收集数据调整 | +| 配置文件STANDARD_MAX_SCORE调整后需要重启服务 | 临时不可用 | 启动时加载，重启时间短可接受 | diff --git a/AI人材育成_練習問題.md b/AI人材育成_練習問題.md new file mode 100644 index 0000000..8bff2a0 --- /dev/null +++ b/AI人材育成_練習問題.md @@ -0,0 +1,1317 @@ +# AI人才育成 L2 考核问题 + +## 文档目的 + +**本文件是AI人才育成L2考核的正式考核方法文档。** + +本考核包含两组题目：第一组为业务系统开发题（01~06），第二组为开发阶段AI评审工具题（07~11）。受验者根据自身工作方向和实际需求，**从两组共11道题中任选1题**独立实现。评审者根据该题的验收基准和评分标准进行评分，达到合格线（≥60分）即视为通过。 + +本文件明确了考核的全部要素：考核内容（11道题的业务场景与技术需求）、考核标准（验收基准与评分细则）、提交要求（提交物清单与截止时间）、行为约束（技术选择限制与考核纪律）。 + +--- + +### L2定位 + +L2（Level 2）即可独立使用 AI 工具完成实际业务任务的阶段。L2能力要求： +- 能根据业务需求选择合适的技术组合（VibeCoding / Superpowers / SpecKit / Skill / MCP） +- 能独立完成从需求分析→技术选型→编码实现→测试验证的闭环 +- 能在 AGENTS.md 中记录技术运用过程、设计决策理由、问题与对策 +- 能交付可运行、可复现、有文档的完整成果 + +### 考核概要 + +| 項目 | 内容 | +|------|------| +| **形式** | 个人考核，从11题（两组）中任选 **1题** 实现 | +| **开发AI** | 推荐使用 **OpenCode / Claude Code / GitHub Copilot** 之一（不作强制，也可自行选择其他同类工具），实际使用的工具须在README声明并记录运用过程 | +| **课程技术** | VibeCoding / Superpowers / SpecKit / Skill / MCP自动化测试（至少选1项/题） | +| **语言/框架** | 不限 | +| **提交** | 每题一个Git仓库，题目发布日起 **10个工作日** 内提交 | +| **及格** | 每题基准100分（高难度题有赋分加成），达到合格线视为通过 | + +--- + +## 📋 考核须知 + +### 技术约束 + +| 项目 | 要求 | +|------|------| +| **开发AI** | **不作强制指定**，推荐 OpenCode / Claude Code / GitHub Copilot 之一（详见《L2考核成果物提交规范》§2），运用过程须在AGENTS.md中完整记录 | +| **LLM模型** | 推荐 DeepSeek-V3 / OpenAI GPT-4o / Claude Sonnet 之一（受验者自行选择） | +| **课程技术** | VibeCoding / Superpowers / SpecKit / Skill / MCP自动化测试（至少选1项/题） | +| **编程语言** | 不限 | +| **前端框架** | 不限 | +| **LLM异常处理** | 涉及LLM调用的功能，需考虑API超时/不可达等异常情况，实现降级处理或显式错误提示 | + +### 提交方式 +- **提交物**: 每个题目一个Git仓库，包含所有源代码和文档 +- **提交截止**: 题目发布日起 **10个工作日**（以Git仓库最后推送时间为准） +- **提交方式**: Git仓库URL提交（GitHub / Gitea / 其他均可） + +> **AGENTS.md说明**：AGENTS.md是每位受验者在项目根目录下创建的技术运用记录文件，用于记录AI工具使用过程、prompt原文、设计决策理由、遇到的问题与解决方案。评审者将通过AGENTS.md了解受验者的技术运用能力和问题解决过程。格式为Markdown，无固定模板，但需包含每道题的技术选型理由、使用prompt的记录、人工修正点、自评等。 + +### 评审方式 +- 评审者拉取代码 → 按README运行 → 验证功能 → 检查文档 → 按评分表打分 +- 如有录屏，优先查看录屏了解功能概览 + +### 评分框架 + +评审基于**共通维度**评分，各维度分值合计**100分**，高难度题目按难度系数追加赋分： + +| 维度 | 分值 | 评审要点 | +|------|:---:|---------| +| 功能完整性 | 30 | 核心需求是否全部实现，主要功能路径可运行 | +| 设计文档 | 10 | 架构图/数据流图/技术选型理由/关键设计决策 | +| 测试用例与测试结果 | 10 | ≥3个测试用例，覆盖正常和异常路径，结果可复现 | +| AI协作过程记录（AGENTS.md） | 15 | 记录prompt原文、生成过程、人工修正点、问题与对策 | +| 技术选型与范式运用 | 15 | 选型理由充分，SpecKit/VibeCoding/Skill等运用记录 | +| 代码质量 + README | 10 | 结构清晰、命名规范、README完整、可一键运行 | +| 业务场景理解与需求分析 | 10 | 对业务场景理解准确，需求分析到位 | +| **合计** | **100** | | + +#### 难度赋分 + +| 难度 | 赋分 | 最高分 | 合格线 | +|:----:|:----:|:------:|:------:| +| ★★ | +0 | 100分 | ≥60分 | +| ★★★ | +5 | 105分 | ≥60分 | +| ★★★★ | +10 | 110分 | ≥60分 | + +**合格条件：得分（含赋分）≥ 60分** + +未达合格线则需按"重做细则"处理。 + +### 考核纪律 + +| 规则 | 说明 | +|------|------| +| **独立完成** | 每题须独立完成，禁止抄袭他人代码或成果 | +| **LLM使用** | 可使用任意LLM辅助开发，但须在AGENTS.md中完整记录使用的prompt、生成过程和人工修正点 | +| **代码引用** | 引用开源代码须在README中标注出处和许可证 | +| **禁止代做** | 不得委托他人代为完成全部或部分实现 | +| **资源费用** | LLM API调用费用由受验者自行承担，不做统一限制 | + +### 迟交处理 + +| 迟交天数 | 扣分规则 | +|---------|---------| +| 1~3个工作日 | 每题扣 **5分** | +| 4~7个工作日 | 每题扣 **10分** | +| 超过7个工作日 | 本题按 **0分** 处理，需重做 | + +### 重做细则 + +- **重做条件**: 单题未达及格线，或迟交超过7个工作日 +- **重做期限**: 自通知之日起 **5个工作日** 内提交 +- **重做评分**: 重做后的评分不扣分，按正常评分标准打分，但最高记为 **80分** +- **重做次数**: 每题最多重做 **1次**；再次未达线则总评为不合格 + +### 选题指南 + +| 指南 | 说明 | +|------|------| +| **难度选择** | 所有题目统一合格线60分，请根据业务场景匹配度和自身能力选择 | +| **重复选题处理** | 如两人选择相同题目且提交相似实现，以评审时认定为准；如确认为独立完成则不扣分 | + +--- + +## 📋 题目一览 + +### 第一组｜业务系统开发题（01~06） + +| # | 标题 | 分类 | 难度 | 推荐技术组合 | +|---|------|------|------|-------------| +| 01 | 年度满意度调查数据的自动处理与分析 | 数据分析 | ★★ | VibeCoding + Skill | +| 02 | 年度面谈问卷生成与数据分析 | 数据分析 | ★★★ | Skill + MCP | +| 03 | 人事制度RAG检索系统 | 制度检索 | ★★★★ | Superpowers + MCP | +| 04 | 合同智能审查 | 法律相关 | ★★★ | Superpowers + MCP | +| 05 | 法规信息自动收集爬虫 | 法律相关 | ★★★ | Skill + MCP | +| 06 | 外部环境风险信息的自动收集与分析 | 风险管理 | ★★★ | Skill + MCP | + +### 第二组｜开发阶段AI评审工具题（07~11） + +| # | 标题 | 对应阶段 | 难度 | 推荐技术组合 | +|---|------|---------|------|-------------| +| 07 | 需求文档AI评审工具 | 需求定义 | ★★★ | Skill + MCP | +| 08 | 设计书AI评审工具 | 基本设计/详细设计 | ★★★★ | SpecKit + MCP | +| 09 | 代码AI评审工具 | 编码实现 | ★★★ | Skill + MCP | +| 10 | 测试用例AI评审工具 | 测试设计 | ★★★★ | Skill + MCP | +| 11 | 成果物AI评审工具 | 交付验收 | ★★ | VibeCoding | + +> 第二组的组内共通硬性要求（证据型报告 / 规则外置 / 分级判定 / 企业标准外置）见07题前的组说明，适用于07~11全部题目。 + +--- + +## 01｜年度满意度调查数据的自动处理与分析 + +**适合方向**: 有数据处理经验者 | **前置依赖**: 无 +### 业务场景 +某公司每年实施一次全员满意度调查。 + +- 调查数据为Excel格式，包含多个Sheet，每年题目和构成可能变化 +- 各部门收集结果后由管理部门汇总 +- 需要按全公司、分公司、本部、部门等维度进行统计分析 +- 需要与上一年度数据进行对比分析 +- **管理员**（管理部）：上传模板、配置解析规则、查看全公司数据 +- **部门管理员**：上传本部门数据、查看全公司结果 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **VibeCoding** | 通过提示词直接生成模板解析+统计+看板的全套功能 | 使用的prompt原文 / 生成过程 / 人工修正点 / 遇到的问题与对策 | +| **SpecKit** | 先编写规格文档再实现，覆盖所有边界情况 | 规格定义过程 / spec与实现的对应关系 / 边界情况处理策略 | +| **Skill** | 将「模板解析」「统计引擎」「图表生成」封装为独立Skill | 各Skill的接口定义 / 调用链路 / 复用方式 | +| **Superpowers** | 用Superpowers组合方式构建统计管道 | Superpower的注册与组合逻辑 / 各Superpower的职责边界 | +| **MCP自动化测试** | 关键路径通过MCP Server自动测试验证 | MCP Server配置 / 测试用例定义 / 执行结果与覆盖率 | + +> **技术组合规则**：至少选择1项技术。鼓励在同一题中组合多项技术（如：VibeCoding做前端 + Skill做统计引擎 + MCP做测试），组合使用在评分中会有加分。 + +### 业务需求 + +#### 模板管理 +- 管理员上传当年的调查模板Excel +- 系统自动识别维度列（分公司/本部/部门等）和评分列 +- 模板的列名、列数、Sheet数每年可能变化，系统需具备应对机制 +- 识别结果应以可视方式呈现给管理员确认 + +#### 数据导入与统计 +- 部门管理员上传本部门结果Excel（列结构与模板一致） +- 系统按模板解析规则自动统计 +- 统计维度：全公司 / 分公司 / 本部 / 部门（至少实现2个维度，鼓励全部实现） +- 支持导入多个年度的数据进行对比 + +#### 权限区分 +- 管理员可上传模板、查看全部数据 +- 部门管理员可上传本部门数据、查看全公司的汇总统计结果（不可查看其他部门的明细数据） +- 权限的实现方式不限（登录认证 / 配置文件区分 / URL参数模拟 / localStorage模拟 等均可） +- 需在AGENTS.md中说明实现方式和理由，纯前端方案需说明生产环境的替代方案 + +#### 看板展示 +- Web页面展示统计结果 +- 至少包含2种不同类型的图表（柱状图、雷达图、箱线图、趋势线等） +- 支持维度切换（如从全公司下钻到部门） +- 支持年度对比显示 + +#### 智能分析 +- 根据统计结果自动识别得分较低或下降明显的维度 +- 按部门/分公司维度汇总薄弱环节，生成分析结论 +- 根据分析结论自动提出改善建议（如「XX部门的沟通满意度连续两年下降，建议加强部门内定期的1on1面谈」） +- 改善建议应可量化、可执行、针对具体部门 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 模板可变应对 | 样本模板A能正确解析 | 列名/列数不同的模板B也能正确解析 | 提供2种不同结构的模板文件分别测试 | +| 统计正确性 | 小样本数据的手算结果与系统一致 | 多种维度交叉验证无偏差 | 提供5条数据的样本，手动验证统计结果 | +| 年度对比 | 能显示2年数据对比 | 维度名跨年变化后仍能正确对齐 | 提供2年维度名不同的数据验证 | +| 权限隔离 | 部门管理员看不到其他部门数据 | 纯前端方案说明生产替代方案 | 检查AGENTS.md中的权限说明 | +| 分析深度 | 能标识得分最低的1-2个维度 | 能识别下降趋势、给出具体改善建议 | 在样本数据中植入下降维度，验证分析结果 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求（OS、语言版本、依赖）、安装步骤、运行方法、功能说明 | **必须** | +| 3 | 设计文档 | 架构图 / 数据流图 / 技术选型理由 / 关键设计决策 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例，覆盖核心逻辑的正常路径和异常路径，附执行结果 | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、设计决策理由、遇到的问题与解决方案 | **必须** | +| 6 | 样本数据 | 至少2个年度的模拟Excel数据（多Sheet），包含正常数据和边界数据 | **必须** | +| 7 | 演示录屏 | 展示主要功能的操作录屏（3分钟以内） | 可选（加分5分） | + +### 评分标准（100分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 模板管理5分（上传+自动识别+确认）/ 数据导入与统计10分（导入+多维度统计+年度对比）/ 权限区分5分（两种角色隔离）/ 看板展示5分（图表+下钻）/ 智能分析5分（薄弱维度识别+改善建议） | +| 设计文档 | 10分 | 架构合理、图表达清晰、设计决策有依据 | +| 测试用例与测试结果 | 10分 | 测试覆盖核心逻辑、测试结果可复现 | +| AI协作过程记录（AGENTS.md） | 15分 | 技术运用过程记录完整、prompt原文和人工修正点可追溯 | +| 技术选型与范式运用 | 15分 | 选型理由充分，VibeCoding/Skill等运用记录合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README完整可运行 | +| 业务场景理解与需求分析 | 10分 | 对满意度调查场景理解准确，需求分析到位 | +| **合计** | **100分** | | + +> 本题为★★难度，满分100分，合格条件：≥60分。功能完整性30分中，模板管理(5分)+数据导入与统计(10分)+权限区分(5分)+看板展示(5分)+智能分析(5分)合计30分为必达项，为所有题目的基准难度。 + +--- + +## 02｜年度面谈问卷生成与数据分析 + +**适合方向**: 对文本分析/NLP感兴趣者 | **前置依赖**: 无（02与01无强制绑定，可独立完成；若需满意度数据作为模拟输入，可在样本数据中自行mock） +### 业务场景 + +某公司每年实施全员满意度调查后，需针对调查中反映的问题进行员工面谈。 + +- 满意度调查数据以Excel形式汇总，包含各维度（工作环境、薪酬福利、职业发展等）评分，按全公司/分公司/本部/部门等多维度统计 +- 人事部门需根据调查结果，针对不同部门、不同职级的员工生成结构化面谈问卷 +- 面谈记录以Excel/文本形式保存，包含约30~50条面谈记录 +- 每条记录包含：面谈日期、员工所属（分公司/本部/部门）、职级、面谈话题分类、自由文本内容 +- **人事**：导入满意度调查结果、配置低分判定规则、确认问卷、查看所有面谈分析结果 +- **面谈实施者**：录入面谈记录、查看自己负责的面谈分析 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Skill** | 将「规则引擎」「问卷生成」「话题分类」「共性问题提取」「改善建议生成」封装为独立Skill | 各Skill的接口定义 / 规则与LLM的分工 / 准确率验证 | +| **MCP自动化测试** | 对规则判定逻辑和LLM输出质量进行自动化测试验证 | MCP Server配置 / 测试用例设计 / 准确率基准 | +| **VibeCoding** | 用提示词直接实现导入→规则配置→分析→问卷生成→看板的完整流程 | 使用的prompt原文 / 生成过程 / 规则与LLM的分工策略 | +| **Superpowers** | 用Superpowers组合构建分析管道（规则引擎 + LLM分析 + 报告生成） | Superpower的注册与组合逻辑 / 各Superpower的职责边界 | +| **SpecKit** | 先定义规则配置规范、分析策略、输出格式规格 | 规格定义过程 / 规则与spec的对应关系 | + +### 业务需求 + +#### 规则配置与低分维度识别 +- 导入满意度调查Excel，自动识别维度列和评分列 +- HR可配置低分维度判定规则（至少2种，建议3种全部实现）： + - **绝对阈值**：评分低于X分的维度（X可配置） + - **前年比下降**：与上一年度相比下降超过Y%的维度（Y可配置） + - **部门特异性**：部门得分低于全社平均分超过Z的维度（Z可配置） +- 规则支持多选组合（AND/OR） +- 配置后预览低分维度列表，显示每个维度被抽取的理由（如「XX部门沟通满意度2.8，低于阈值3.0」） +- 支持HR手动增删选中的维度 +- HR确认后保存规则配置，供下次使用 + +#### 面谈问卷生成 +- 基于选中的低分维度，自动生成结构化面谈问卷 +- 规则层面：维度所属范围自动分配到对应的话题分类 +- LLM层面：根据低分维度的具体数据生成自然、有针对性的面谈问题（如「XX部门的沟通满意度连续两年下降，您认为主要原因是什么？」） +- 问卷支持按部门/职级定制不同问题 +- 问卷内容可编辑，HR确认后发布 + +#### 面谈数据导入与管理 +- 面谈实施者按问卷逐条录入面谈记录，或批量导入Excel +- 每条记录至少包含：员工信息、面谈日期、话题分类、面谈内容（自由文本） +- 批量导入时系统自动校验数据完整性（必填字段检查），导入失败时返回错误明细 +- 支持上传已有面谈记录文件批量导入 + +#### 智能分析（规则+LLM混合） + +**规则层面：** +- **话题频度统计**：按部门/职级维度统计各话题的出现频次和占比 +- **TOP问题抽出**：跨面谈记录发现高频出现的问题主题 +- **倾向分析**：各部门/职级的负面/关注倾向 + +**LLM层面：** +- **话题分类辅助**：对自由文本中无法明确匹配的话题进行语义分类 +- **共性问题自然语言摘要**：对高频话题生成简洁的概括描述 +- **改善建议生成**：根据分析结果自动生成改善建议（如「XX部门的负荷满意度连续两年下降，建议增加人员配置或优化工作分配流程」） +- 改善建议可量化、可执行、针对具体部门 + +#### 看板展示 +- Web页面展示分析结果 +- 至少包含2种不同类型的图表（话题分布饼图/柱状图、部门别负面率对比、问题热度图等） +- 支持维度过滤（按部门、职级、话题类别筛选） +- 支持下钻查看单条面谈详情 +- 显示规则配置状态和当前生效规则 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 规则配置与低分识别 | 2种规则能正确配置并识别低分维度 | 3种规则组合配置均正确，结果预览显示判断理由 | 提供样本数据配置不同规则，验证抽取结果 | +| 面谈问卷生成 | 生成的问卷基于低分维度，问题合理 | 问卷支持按部门/职级定制，内容可编辑 | 检查问卷内容与低分维度的对应关系 | +| 话题分类准确率 | 对10条标注样本分类准确率≥60% | ≥80% | 提供标注好的测试集，比对分类结果 | +| 共性问题提取 | 植入5个高频话题，至少检出3个 | 全部检出且噪音少 | mock数据中控制话题分布，验证提取结果 | +| 改善建议相关性 | 建议与发现的问题主题相关 | 建议可量化、可执行、针对具体部门 | 检查建议是否针对特定部门、有具体行动描述 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求（含LLM配置）、安装步骤、运行方法、功能说明 | **必须** | +| 3 | 设计文档 | 架构图 / 规则引擎设计 / 规则与LLM的分工策略 / 分析模型选择依据 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例，覆盖规则配置、话题分类、共性问题提取 | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、规则调优过程、分类调优过程、LLM调优日志 | **必须** | +| 6 | 样本数据 | 至少1份满意度调查模拟Excel + 至少30条模拟面谈记录（覆盖5个话题分类、3个部门） | **必须** | +| 7 | 演示录屏 | 展示导入→规则配置→问卷生成→面谈录入→分析→看板全流程（3分钟以内） | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分5分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 规则配置与低分识别10分 / 问卷生成10分 / 面谈数据导入5分 / 看板展示5分（智能分析的分数含在上述各项中：话题分类准确率→规则配置分、共性问题提取→问卷生成分、改善建议→看板展示分，不单独计分） | +| 设计文档 | 10分 | 架构合理，规则与LLM分工策略清晰，选型有依据 | +| 测试用例与测试结果 | 10分 | 覆盖规则配置、话题分类、共性问题提取，结果可复现 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整，规则调优、分类调优、LLM调优日志可追溯 | +| 技术选型与范式运用 | 15分 | Skill/Superpowers/VibeCoding等选型理由充分 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README完整 | +| 业务场景理解与需求分析 | 10分 | 对面谈调查场景理解准确，需求分析到位 | +| 难度赋分 | 5分 | ★★★难度追加 | +| **合计** | **105分** | | + +> 本题为★★★难度，满分105分，合格条件：≥60分。 + +--- + +## 03｜人事制度RAG检索系统 + +**适合方向**: 对RAG/向量检索/检索质量优化感兴趣者 | **前置依赖**: 无 +### 业务场景 + +某公司人事制度文档种类繁多（就业规则、工资规定、休假规定、评估制度等），日常业务中经常需要确认和查找相关条款。 + +- 目前主要依靠员工对制度的熟悉程度人工翻阅文档，查阅效率不高 +- 每个人对制度的熟悉程度不同，有些条款只有特定人员知道位置，属人化问题严重 +- 当某一法规更新后，需要摸排所有制度中涉及的条款，手工操作工作量大 +- 制度文档为PDF/Word格式，总量约10~20份，每份20~100页 +- 需支持中文和日文制度的混合检索 +- **员工**：通过自然语言提问检索制度条款 +- **管理员**（人事担当）：上传/更新制度文档、管理文档版本、管理chunk策略、查看检索分析 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Superpowers** | 用Superpowers组合构建RAG管道（文档加载 + 文本分割 + 向量化 + 检索 + 生成回答 + 质量评估） | Superpower的注册与组合逻辑 / 各环节参数调优 / 检索策略切换逻辑 | +| **MCP自动化测试** | 对检索准确率、检索策略切换、质量评估逻辑进行自动化测试 | MCP Server配置 / 测试集构建 / 评估指标设计 / 各策略对比测试 | +| **Skill** | 将「文档解析」「多种检索策略」「chunk管理」「质量评估」「制度关联」「分析看板」封装为独立Skill | 各Skill的接口定义 / embedding模型选择理由 / chunk策略 / 检索策略对比 | +| **VibeCoding** | 用提示词直接实现文档上传→多种检索→质量评估→分析看板的完整流程 | 使用的prompt原文 / 生成过程 / chunk大小调优 / 检索策略切换的prompt设计 | +| **SpecKit** | 先定义文档格式规范、多检索策略规格、质量评估标准、分析指标规格 | 规格定义过程 / 各检索策略与spec的对应关系 / 质量评估标准定义 | + +> **难度说明**：本题为★★★★难度，满分110分（含难度赋分10分），合格线60分。功能完整性30分中，基础检索(10分)+文档管理(5分)+无法回答处理(5分)+追问(5分)合计25分为基础必达项，在此基础上实现检索策略切换、质量可视化、Chunk管理、制度关联、分析看板中的任意1~2项即可达到及格线。 + +### 业务需求 + +#### 文档管理 +- 管理员可上传PDF/Word格式的制度文档 +- 系统自动解析文档内容，提取章节标题和正文 +- 支持文档版本管理（更新后保留旧版本） +- 显示已上传文档列表（文档名、页数、上传日期、版本号） +- 支持删除和重新上传 + +#### 基础检索功能 +- 支持自然语言提问，如「産休の取得条件は？」「年次有給休暇の最低取得日数は？」 +- 系统检索相关条款后返回： + - **回答**：基于检索到的条款生成的回答 + - **出处**：引用条款的具体文档名、章节、页码 + - **置信度**：回答的可信度标识 +- 支持中文和日文制度文档的混合检索（同一提问可包含中日文混用，如"产休の取得条件是什么？"；也支持纯中文或纯日文提问） +- 对无法回答的问题，系统应明确表示"未在现有制度中找到相关信息"，而非编造答案 +- 支持追问（在上一轮问题基础上继续提问） + +#### 多种检索策略切换 +- 管理员可在管理界面切换检索模式： + - **关键词检索**：基于关键词匹配的全文搜索 + - **向量检索**：基于embedding的语义搜索 + - **混合检索**：关键词+向量的加权组合检索 +- 各模式下的检索结果可对比展示 +- 管理员可调整混合检索中关键词与向量的权重比例 +- 系统记录各策略的检索效果，辅助管理员选择最优策略 + +#### 检索质量可视化 +- 每条回答附带详细的质量信息： + - **置信度分数**：回答的总体可信度评分 + - **引用chunk列表**：回答引用的文档片段一览，显示各chunk的匹配分数 + - **匹配详情**：每个引用chunk与提问的匹配度、来源文档、所在章节 + - **检索耗时**：从提问到返回的响应时间 +- 质量信息以可视方式呈现（分数条、进度条、颜色标识等），不要求专业BI工具 + +#### Chunk管理 +- 管理员可查看文档的分割状态： + - 各文档被分割为多少个chunk + - 各chunk的文本内容预览 + - 各chunk的来源位置（文档名、章节） +- 管理员可调整chunk参数： + - chunk大小（字符数） + - chunk重叠率 + - 分割策略（按段落/按固定长度/按章节） +- 参数调整后系统重新分割并索引（后台异步执行，不影响已有检索功能的正常使用） + +#### 制度间关联提示 +- 检索某一条款时，系统自动检测并提示其他制度中的相关条款 +- 关联依据包括：关键词共现、条款引用关系、同一分类标签 +- 关联条款以列表形式展示，点击可跳转查看详情 +- 管理员可手动建立或解除条款关联 + +#### 检索分析看板 +- Web页面展示检索系统的运行状态 +- 展示内容： + - **高频搜索词**：被搜索次数最多的关键词/问题 + - **无法回答的问题**：系统未能找到答案的提问列表 + - **检索质量趋势**：置信度分数、响应时间的变化趋势 + - **文档热度**：被引用次数最多的文档和章节 +- 支持按时间段筛选分析数据 +- 展示当前检索策略配置及历史切换记录 + +#### 法规更新影响分析（加分功能） +- 当某法规更新后，管理员输入更新内容 +- 系统自动检索所有制度文档中涉及该法规的条款 +- 列出受影响条款一览，辅助管理员判断需要修改哪些部分 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 基础检索 | 5个测试问题中至少3个返回相关结果 | 5个全部返回正确出处 | 提供5个已知答案的制度查询问题 | +| 不可回答检测 | 对无关问题明确表示无法回答 | 不编造答案且给出合理解释 | 提问与制度无关的问题验证 | +| 出处引用 | 回答附有文档名/章节/页码 | 引用精确且可定位 | 验证回答中的引用是否真实存在 | +| 检索策略切换 | 至少2种检索策略可切换使用 | 3种策略可切换，混合检索权重可调 | 分别用关键词和向量检索同一问题，对比结果 | +| 检索质量可视化 | 显示置信度分数 | 显示置信度+chunk列表+匹配详情 | 检查检索结果页面是否包含质量信息 | +| Chunk管理 | 显示chunk列表 | chunk大小/重叠率可调整，调整后重新索引 | 调整参数后验证检索结果变化 | +| 制度间关联 | 关联提示与检索内容相关 | 关联准确，管理员可手动管理关联 | 检查关联条款的准确性 | +| 分析看板 | 显示高频搜索词 | 高频词+无法回答+质量趋势+文档热度全部显示 | 提交多个查询后验证看板数据 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求（含向量数据库/LLM配置）、安装步骤、运行方法、检索策略说明 | **必须** | +| 3 | 设计文档 | RAG架构图、chunk策略设计、多种检索策略设计、质量评估方案、制度关联策略 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少5个测试问题，覆盖常见制度查询，附各检索策略对比结果 | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、chunk大小调优过程、检索策略对比、检索准确率改善记录、质量评估设计 | **必须** | +| 6 | 样本数据 | 至少3份模拟制度文档（中/日文各至少1份），含多级章节结构，含可关联的交叉引用 | **必须** | +| 7 | 演示录屏 | 展示上传→提问→策略切换→质量查看→chunk管理→关联提示→看板的完整流程（5分钟以内） | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分10分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 必达项（25分）：文档上传与解析5分 / 基础检索功能10分 / 无法回答处理5分 / 追问功能5分。加分项（5分，任选其一）：检索策略切换5分 / 检索质量可视化5分 / Chunk管理5分 / 制度间关联提示5分 / 检索分析看板5分 | +| 设计文档 | 10分 | RAG架构清晰、检索策略设计合理、质量评估方案有依据 | +| 测试用例与测试结果 | 10分 | 至少5个测试问题，覆盖常见制度查询，结果可复现 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、chunk大小调优、检索策略对比、准确率改善记录 | +| 技术选型与范式运用 | 15分 | Superpowers/Skill/MCP等选型理由充分，RAG管道设计合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README包含LLM/向量库配置说明 | +| 业务场景理解与需求分析 | 10分 | 对人事制度检索场景理解准确，需求分析到位 | +| 难度赋分 | 10分 | ★★★★难度追加 | +| **合计** | **110分** | | + +> 本题为★★★★难度，满分110分，合格条件：≥60分。 + +--- + +## 04｜合同智能审查 + +**适合方向**: 对法律文书/合同审查/审批流程感兴趣者 | **前置依赖**: 无 +### 业务场景 + +某公司日常业务中需要签订多种类型的合同（购买合同、服务合同、续约合同、保密协议等）。 + +- 重要合同需请外部律师协助审查，其他常规合同由法务人员审查 +- 目前合同审批维度不一致：有些通过邮件审批，有些通过系统提交 +- 各类事前联络所需时间较长，流程存在差异化 +- 合同签署后需要妥善保存电子版，到期续签需及时提醒 +- 合同数量：每月约20~50份，合同金额从数万到数千万不等 +- **发起人**（业务部门）：提交合同审查申请、发起盖章申请、查看审查进度 +- **法务**：审查合同、给出修改意见、复审 +- **律师**（外部）：接收重要合同审查请求，返回审查意见 +- **管理员**（法务负责人）：配置审查规则、查看分析报告 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Superpowers** | 用Superpowers组合构建审查管道（文件解析 + 条款提取 + 风险分析 + 审批流程 + 报告生成） | Superpower的注册与组合逻辑 | +| **MCP自动化测试** | 对条款提取准确率、审查等级判断、审批流程逻辑进行自动化测试 | MCP Server配置 / 测试用例设计 / 准确率基准 | +| **Skill** | 将「合同解析」「条款提取」「风险规则库」「审批流程」「盖章管理」「提醒引擎」封装为独立Skill | 各Skill的接口定义 / 风险规则设计 / 审批流程状态管理 | +| **VibeCoding** | 用提示词直接实现合同上传→审查→审批→盖章→签约的全流程 | 使用的prompt原文 / 生成过程 / 审批状态管理设计 | + +### 业务需求 + +#### 合同上传与管理 +- 上传合同文件（PDF/Word），系统自动提取合同基本信息 +- 提取信息包括：合同名称、签约方、合同金额、签订日期、有效期、到期日 +- 合同列表展示，支持按状态（审查中/待签署/已签署/待续签/已过期）过滤 + +#### 智能审查 +- 系统根据合同内容和金额自动判断审查等级： + - **简易审查**（常规合同，金额<10万）：自动审查，结果送法务复审 + - **标准审查**（金额≥10万且<100万）：自动审查 + 法务逐条确认 + - **严格审查**（金额≥100万或重要合同）：自动初审后**自动发送至律师邮箱**审查（模拟发送：在系统日志中记录收件人、邮件主题、发送时间，界面显示"已发送"状态即可，不要求对接真实邮件服务） +- 审查内容至少包含： + - **条款完整性检查**：是否包含必要条款（违约责任、保密、终止条件等） + - **关键条款提取**：提取金额、期限、违约责任、管辖法院等 + - **风险标记**：对不利条款（如违约金比例过高、管辖地不利等）自动标记 +- 审查结果以可视化报告呈现（风险等级、问题条款一览、修改建议） + +#### 审批流程 +- 发起人提交合同审查申请 +- 系统根据智能审查自动判断的等级（简易/标准/严格），推送至相应审批人 +- 审批过程可在系统中查看进度（待审/审查中/已完成） +- **审查完成后自动通知发起人**，提示进入签约阶段 + +#### 盖章审批 +- 发起人收到签约提醒后，可发起盖章申请 +- 盖章申请经审批通过后，发起人可自行操作： + - **电子签章**：系统内置电子签章功能，直接在线签署（模拟实现即可，不要求对接真实电子签名API） + - **手动盖章**：下载合同文件，线下盖章后上传已签署版本 +- 盖章状态可在系统中追踪（待申请/审批中/已批准/已签署） + +#### 签约提醒与到期管理 +- **签约提醒**：审查完成后自动通知发起人，提示及时签约 +- **到期提醒**：合同到期前30天自动标识为"待续签" +- **审批提醒**：合同金额超过1万元时，系统自动弹出是否提交审批的确认提醒 +- 所有合同电子版统一保存，支持按状态检索 + +#### 合同分析报告 +- **统计报告**：按时间段、合同类型、金额区间统计合同数据（合同数量、总金额、平均审查周期、风险合同比例） +- **签署注意点报告**：根据审查结果自动生成签署时需关注的事项清单（如管辖法院、违约金上限等） +- 至少1种图表展示统计结果 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 信息提取 | 正确提取合同名称和金额 | 提取5个关键字段全部正确 | 提供已知字段的合同验证 | +| 审查等级判断 | 金额阈值判断正确 | 结合合同类型综合判断正确，律师自动邮件发送正常 | 提供不同金额+类型的合同测试 | +| 风险标记 | 能标记明显不利条款（违约金过高） | 能标记隐含风险（管辖地不利） | 在合同样本中植入风险条款 | +| 审批流程 | 流程可追踪进度 | 等级不同→审批人不同，审查完成自动通知发起人 | 提交不同等级合同验证流程差异 | +| 盖章审批 | 盖章申请流程可追踪 | 支持电子签章和手动盖章两种模式 | 提交盖章申请验证全流程 | +| 签约与到期提醒 | 到期前30天正确标识 | 签约提醒+到期提醒+禀议提醒三种均正常触发 | 设置不同金额和到期日验证提醒逻辑 | +| 分析报告 | 统计报告内容完整 | 统计报告和签署注意点报告均正确生成 | 对比报告内容与合同数据的一致性 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求（含LLM配置）、安装步骤、运行方法、审批流程说明 | **必须** | +| 3 | 设计文档 | 架构图、审查等级判定逻辑、风险规则库设计、审批状态机设计 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少5份合同测试用例，覆盖不同审查等级和审批流程 | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、风险规则调优过程、审批状态管理设计 | **必须** | +| 6 | 样本数据 | 至少5份模拟合同PDF（含正常合同和有问题合同），含不同金额场景 | **必须** | +| 7 | 演示录屏 | 展示上传→审查→审批→盖章→签约→提醒全流程（5分钟以内） | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分5分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 合同上传与信息提取5分 / 审查等级判断5分 / 条款提取与风险标记10分 / 审批流程5分 / 盖章审批5分（签约与到期提醒、分析报告的分数含在上述各项中，不单独计分） | +| 设计文档 | 10分 | 风险规则库设计合理、审批状态机设计清晰 | +| 测试用例与测试结果 | 10分 | 至少5份合同测试用例，覆盖不同审查等级和审批流程 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、风险规则调优过程可追溯 | +| 技术选型与范式运用 | 15分 | Superpowers/Skill/MCP等选型理由充分，审查管道设计合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README包含LLM配置说明 | +| 业务场景理解与需求分析 | 10分 | 对合同审查场景理解准确，需求分析到位 | +| 难度赋分 | 5分 | ★★★难度追加 | +| **合计** | **105分** | | + +> 本题为★★★难度，满分105分，合格条件：≥60分。 + +--- + +## 05｜法规信息自动收集爬虫 + +**适合方向**: 熟悉爬虫技术、对定时任务有经验者 | **前置依赖**: 无 +### 业务场景 + +某公司需要定期收集各政府机关发布的法律法规更新信息，以确保持续合规运营。 + +- 法律法规修订信息的发布网站分散（中央政府网站、各部委网站、地方政府网站、行业监管机构网站等） +- 人工逐一巡检多个网站，无法及时捕捉所有更新 +- 涉及领域：劳动法、税法、外商投资法、数据保护法、行业专项法规等 +- 需收集的信息类别：新法颁布、现有法规修订、废止、征求意见稿 +- 收集的信息需按法规名称、发布机关、发布日期、修订内容摘要、影响度评价等进行整理 +- **法务担当**：配置监控规则、查看收集结果、确认影响度 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Skill** | 将「爬虫引擎」「内容解析」「关键词筛选」「报告生成」封装为独立Skill | 各Skill的接口定义 / 爬虫策略 / 解析规则 | +| **MCP自动化测试** | 对爬虫结果解析准确率和筛选逻辑进行自动化测试 | MCP Server配置 / 测试用例设计 / 解析准确率验证 | +| **VibeCoding** | 用提示词直接实现爬虫+解析+筛选+报告的完整流程 | 使用的prompt原文 / 生成过程 / 反爬应对策略 | +| **Superpowers** | 用Superpowers组合构建信息收集管道 | Superpower的注册与组合逻辑 | +| **SpecKit** | 先定义数据源、解析规则、筛选条件的规格 | 规格定义过程 / 解析规则设计 | + +> **爬虫合规提示**：爬虫行为需遵守目标网站的 robots.txt 规定。AGENTS.md 中需说明爬虫策略（采集频率、并发数、User-Agent 设置）及反爬应对方案。 + +### 业务需求 + +#### 数据源管理 +- 支持配置多个监控目标网站（URL + 更新频率） +- 内置至少3个模拟/测试用数据源（如政府法规网站、行业博客等） +- 支持按领域分类管理数据源（劳动法/税法/数据保护/行业专项等） +- 数据源可启用/停用 + +#### 信息自动收集 +- 按设定频率自动访问目标网站，检测更新 +- 提取更新内容的关键信息： + - 法规名称 + - 发布机关 + - 发布日期 / 施行日期 + - 发布类型（新法/修订/废止/征求意见） + - 摘要 / 要点 + - 原文链接 +- 支持增量收集（仅获取上次收集后的更新） +- 对无法访问或解析失败的网站记录错误日志 + +#### 关键词筛选与分类 +- 支持配置关键词规则，按公司业务需要筛选相关法规 +- 关键词规则示例： + - 包含某关键词（如「劳动基准法」「数据保护」）→ 标记为高关注 + - 排除某关键词 → 降低关注度 +- 自动评估法规的影响度（高/中/低） + - 影响度判断依据：与公司业务相关性、涉及部门范围、罚则严重性 +- 按领域自动分类归档 + +#### 结果展示与报告 +- Web页面展示收集结果一览（列表模式） +- 每条结果显示：法规名称、类型、发布机关、发布日期、影响度、状态（新/已读） +- 支持按领域、影响度、发布类型、日期范围筛选 +- 支持标记已读/未读 +- 自动生成定期报告（日报/周报），以表格形式汇总本期更新 +- 报告可导出为Excel/CSV + +#### 风险判别与通知 +- 根据提取信息与公司业务的重要度，自动判别风险等级（高/中/低） + - 影响度判断依据：与公司业务相关性、涉及部门范围、罚则严重性 +- 对标记为"高影响度"的法规更新，在系统中自动突出显示 +- 支持设置通知规则（如：当某领域的法规更新时，自动通知相关负责人） +- 通知方式：**系统内通知 + 邮件发送**（模拟实现即可） +- 风险提示内容包含：法规变更要点、可能受影响的业务流程、建议应对措施 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 增量采集 | 同一内容不重复采集 | 内容更新后能正确识别并再次采集 | 运行两次采集，验证无重复数据 | +| 内容提取 | 正确提取标题和发布日期 | 6个字段全部正确提取 | 提供已知结构的模拟网页验证 | +| 关键词筛选 | 配置关键词后能正确筛选 | 排除词+包含词组合筛选正确 | 配置关键词后验证筛选结果 | +| 风险判别与通知 | 高/中/低三级可区分，系统内突出显示 | 评估结果与人工评估一致率≥70%，通知自动发送 | 受验者自行标注20条模拟法规的影响度作为ground truth，对比系统评估结果，验证通知触发 | +| 错误处理 | 数据源不可达时记录日志 | 自动重试3次后跳过，不影响其他数据源 | 故意配置无效URL验证 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求、安装步骤、运行方法、爬取频率说明 | **必须** | +| 3 | 设计文档 | 架构图、爬虫策略设计、解析规则设计、反爬应对方案 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例，覆盖不同网站结构和解析场景 | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、解析规则调优过程、反爬应对经验 | **必须** | +| 6 | 样本数据 | 模拟目标网页（至少3个不同结构的页面HTML） | **必须** | +| 7 | 演示录屏 | 展示配置→收集→筛选→报告全流程 | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分5分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 数据源管理5分 / 信息自动收集10分 / 增量采集5分 / 结果展示5分 / 定期报告5分 | +| 设计文档 | 10分 | 爬虫策略合理、解析规则设计清晰 | +| 测试用例与测试结果 | 10分 | 至少3个测试用例，覆盖不同网站结构和解析场景 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、反爬应对经验可追溯 | +| 技术选型与范式运用 | 15分 | Skill/MCP等选型理由充分，爬虫引擎设计合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README包含爬虫策略说明 | +| 业务场景理解与需求分析 | 10分 | 对法规收集场景理解准确，需求分析到位 | +| 难度赋分 | 5分 | ★★★难度追加 | +| **合计** | **105分** | | + +> 本题为★★★难度，满分105分，合格条件：≥60分。 + +--- + +## 06｜外部环境风险信息的自动收集与分析 + +**适合方向**: 对信息收集/RSS处理/定时任务感兴趣者 | **前置依赖**: 无 +### 业务场景 + +随着汇率变动、经济安全保障法实施、日中关系等外部环境变化加速，某公司需要及时捕捉和应对外部环境风险。本系统的核心目标是实现**先行的风险把握与经营决策支援**。 + +- 风险领域：汇率变动、法律法规（经济安全保障法、数据保护法）、日中关系、行业动向、技术趋势 +- 目前流程：风险管理部担当者手动巡访主要新闻网站和媒体，收集相关信息 +- 课题： + 1. 手动检索容易遗漏重要信息源和相关情报 + 2. 无法实现24小时持续监控，对风险征兆的早期捕捉滞后 +- **风险管理员**：配置监控关键词和信息源、查看收集结果、确认风险判断 +- 信息来源：新闻网站、政府发布页面、行业博客、RSS订阅 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Skill** | 将「爬虫引擎」「风险分类」「影响度评估」「报告生成」封装为独立Skill | 各Skill的接口定义 / 分类策略 / 评估模型 | +| **MCP自动化测试** | 对分类准确率和风险判定逻辑进行自动化测试 | MCP Server配置 / 测试用例设计 | +| **VibeCoding** | 用提示词直接实现收集→分类→分析→报告的完整流程 | 使用的prompt原文 / 生成过程 / 分类策略调优 | +| **Superpowers** | 用Superpowers组合构建风险情报收集管道 | Superpower的注册与组合逻辑 | +| **SpecKit** | 先定义风险分类体系、影响度评估标准、报告格式规格 | 规格定义过程 / 风险分类与spec的对应关系 | + +> **爬虫合规提示**：爬虫行为需遵守目标网站的 robots.txt 规定。AGENTS.md 中需说明爬虫策略（采集频率、并发数、User-Agent 设置）及反爬应对方案。 + +### 业务需求 + +#### 信息源管理 +- 支持配置多个信息源（RSS、网页URL、API） +- 内置测试用模拟信息源（至少3个，模拟不同领域的新闻/公告） +- 信息源按风险领域分类管理（汇率/法规/日中关系/行业/技术） +- 支持设置采集频率（每日/每周），默认每日运行一次 + +#### 自动信息收集 +- 按设定频率自动访问信息源，获取最新内容 +- 提取信息关键字段：标题、发布时间、来源、摘要、原文链接 +- 增量收集：仅获取上次采集后的新增内容 +- 采集失败时记录错误日志，自动重试 + +#### 全局关键词配置 +- 支持配置全局关键词，所有信息源统一按关键词过滤 +- 关键词分为两级： + - **高关注关键词**：命中时自动标记为高关注（如「经济安全保障」「汇率干预」「制裁」） + - **普通关键词**：命中时正常收录 +- 关键词支持包含/排除规则 +- 关键词变更后自动应用于后续采集 + +#### 智能分类与分析 +- 自动将收集到的信息按预设的风险领域分类 +- 自动评估风险影响度（高/中/低）： + - 影响度评估依据：与公司业务相关性、风险范围、紧急程度 +- 对高风险信息，自动突出显示 + +#### 风险通知 +- 对标记为"高影响度"的风险信息，系统自动发出通知 +- 支持设置通知规则（如：当某领域发现高风险信息时，通知相关负责人） +- 通知方式：**系统内通知 + 邮件发送**（模拟实现即可） +- 通知内容包含：风险事项标题、风险领域、影响度、摘要、原文链接 + +#### 定期报告生成 +- 按设定频率自动生成风险报告（日报/周报），无需手动操作 +- 报告格式：Markdown文件（信息标题、来源、日期、分类、影响度、摘要） +- 报告可按领域/影响度维度汇总 +- 报告自动保存到指定目录，支持历史报告查看和下载 +- 可导出为CSV格式用于二次处理 + +#### 风险仪表盘 +- Web页面展示风险情报一览 +- 按时间轴展示风险事件 +- 支持按领域、影响度、日期范围筛选 +- 高风险事件以醒目样式展示 +- 仪表盘展示风险趋势摘要，辅助经营决策（如高风险事项占比变化、需重点关注的风险领域；趋势需基于至少2个时间周期的数据对比，受验者需模拟多日采集数据以展示趋势） + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 多源采集 | 至少支持2种信息源类型采集 | 支持RSS+网页+API三种类型 | 配置不同类型的信息源测试 | +| 风险分类 | 5个领域分类准确率≥50% | ≥80% | 提供20条标注分类的测试数据 | +| 影响度评估 | 高/中/低可区分 | 与人工评估一致率≥65% | 提供20条标注影响度的测试数据 | +| 风险通知 | 高风险信息系统内可突出显示 | 通知规则可配置，通知自动发送 | 配置通知规则后验证触发 | +| 增量采集 | 同一内容不重复 | 内容更新后能识别变化 | 用同一信息源运行两次验证 | +| 定期报告 | 报告自动生成、格式规范 | 报告含本期采集的全部数据（不限高关注法规），支持日报和周报两种粒度，Markdown报告内容完整、历史报告可查 | 检查报告内容与仪表盘数据一致 | +| 全局关键词 | 高关注关键词能正确标记 | 包含/排除规则同时生效 | 配置关键词后验证过滤和标记结果 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求、安装步骤、运行方法 | **必须** | +| 3 | 设计文档 | 架构图、风险分类体系设计、影响度评估标准、爬虫策略 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例，覆盖不同风险类型和影响度评估 | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、分类策略调优、影响度评估调整 | **必须** | +| 6 | 样本数据 | 模拟信息源HTML/RSS（至少3个，覆盖不同风险领域） | **必须** | +| 7 | 演示录屏 | 展示配置→收集→分类→报告→仪表盘全流程 | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分5分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 信息源管理5分 / 自动信息收集5分 / 增量采集5分 / 智能分类10分 / 风险仪表盘5分 | +| 设计文档 | 10分 | 风险分类体系和评估标准设计合理 | +| 测试用例与测试结果 | 10分 | 至少3个测试用例，覆盖不同风险类型和影响度评估 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、分类策略调优过程可追溯 | +| 技术选型与范式运用 | 15分 | Skill/MCP等选型理由充分，情报收集管道设计合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README完整 | +| 业务场景理解与需求分析 | 10分 | 对风险情报收集场景理解准确，需求分析到位 | +| 难度赋分 | 5分 | ★★★难度追加 | +| **合计** | **105分** | | + +> 本题为★★★难度，满分105分，合格条件：≥60分。 + +--- + +# 第二组｜开发阶段AI评审工具题（07~11） + +## 组定位与背景 + +公司推行AI辅助开发后，文档与代码的生成速度大幅提升，但人工review成为新的瓶颈——全量人审则速度优势归零，放弃审查则质量风险失控。 + +本组题目围绕瀑布式开发的各个阶段，受验者**根据自身项目的实际痛点选择一个阶段**，实现该阶段的AI评审工具/Skill。目标是让工具承担全量预检并给出证据定位，人只复核被标记的例外，在不牺牲质量的前提下保持开发速度。 + +## 组内共通硬性要求（07~11每道题都必须满足） + +| # | 要求 | 说明 | +|---|------|------| +| 1 | **证据型报告** | 每个检出问题必须定位到具体位置（`文件名:行号` 或 `章节编号/条目原文摘录`），附问题描述；不允许只输出整体评价而无问题定位 | +| 2 | **规则外置** | 检查规则必须写在独立配置文件中（YAML/JSON/Markdown均可），新增或修改一条规则不需要改动程序代码；演示时须现场新增1条规则并验证生效 | +| 3 | **分级判定** | 问题分为 Critical / Major / Minor 三级；报告包含各级数量统计和明确的通过结论（通过 / 有条件通过 / 不通过） | +| 4 | **企业标准外置** | 各阶段适用的企业内部标准（文档格式规范 / 编码规约 / 测试基准等）以独立配置文件提供，工具按配置执行检查；标准的具体条目由项目方定义，工具不得硬编码。样本数据须附「标准配置A/B两套」，演示切换B套后检出结果随之变化 | + +--- + +## 07｜需求文档AI评审工具 + +**适合方向**: 对文本分析/NLP感兴趣者 | **前置依赖**: 无 + +### 业务场景 + +项目立项时编写的需求说明书常见质量问题： + +- 歧义表述：「适当处理」「尽快对应」等模糊词导致实现方理解不一致 +- 量化缺失：性能类需求无数字指标（如「响应要快」而无具体毫秒数） +- 需求间矛盾：不同章节对同一功能描述冲突（A处写必填、B处写可选） +- 不可测试的需求：「系统应易用」「界面应友好」等无法验收的表述 + +人工评审一份50页需求书需要半天以上，且高度依赖资深人员经验。需要AI工具做全量初筛，人只复核被标记的问题。 + +- **需求工程师**：上传需求说明书、查看评审报告、按建议修订文档 +- **评审管理员**：维护检查规则（歧义词词典等）、查看评审统计 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Skill** | 将「歧义检测」「一致性检查」「可测试性评估」「报告生成」封装为独立Skill | 各Skill接口定义 / 规则配置方式 / 检出率调优过程 | +| **SpecKit** | 先定义规则配置规范和报告格式spec再实现 | 规格定义过程 / 规则与spec的对应关系 | +| **MCP自动化测试** | 用缺陷标注清单对检出率做自动化回归验证 | MCP Server配置 / 检出率基准与回归结果 | +| **VibeCoding** | 提示词直接实现解析→检查→报告全流程 | prompt原文 / 生成过程 / 误报调优记录 | +| **Superpowers** | 组合构建评审管道（解析→各检查器→汇总报告） | Superpower注册与组合逻辑 / 各检查器职责边界 | + +### 业务需求 + +#### 文档导入与解析 +- 支持Markdown格式需求说明书导入（Word为可选加分项） +- 自动识别章节层级结构，提取带编号的需求条目 +- 解析结果以章节树形式展示供用户确认 + +#### 歧义检测 +- 模糊词检测：基于可配置词典（如「适当」「尽快」「必要时」），命中后标记所在条目并摘录原文 +- 量化缺失检测：对性能/容量类需求，无数字指标时给出提示 +- LLM语义歧义辅助：识别词典覆盖不了的语义歧义（指代不明、一词多义等），并说明判断理由 + +#### 一致性检查 +- 术语一致性：同一概念多种称呼检测（如「用户」vs「会员」混用），术语对照表可配置 +- 条目间矛盾检测：LLM判断不同条目间的逻辑冲突，报告须引用双方条目原文 + +#### 文档编写规范检查 +- 基于可配置的《需求文档编写标准》执行：标题层级使用规范、章节编号连续性、章节排列顺序 +- Word格式文档时检查排版项（字体、字号、行距）；Markdown文档跳过排版项，仅检查结构项并在报告中注明 +- 标准文件中未定义的条目不做检查 + +#### 可测试性评估 +- 对每条需求输出可测试性评级（可测试 / 部分可测试 / 不可测试） +- 对不可测试需求附具体改写建议（如何改写才能可测试） + +#### 评审报告与判定 +- 按 Critical / Major / Minor 分级，每个问题定位到章节编号并摘录原文 +- 输出各级问题统计和通过判定结论 +- 支持导出Markdown格式报告 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 歧义检测 | 植入10处歧义词检出≥6处 | 全部检出且误报≤2处 | 对照缺陷标注清单核对 | +| 矛盾检测 | 植入2组矛盾至少检出1组 | 全部检出且引用双方条目原文 | 对照缺陷标注清单核对 | +| 可测试性评估 | 正确标识植入的不可测试需求 | 附具体可操作的改写建议 | 对照缺陷标注清单核对 | +| 编写规范检查 | 配置的格式违规能正确检出 | 支持标准A/B切换，检出结果随之变化 | 对照缺陷标注清单核对+切换标准演示 | +| 报告规范 | 分级+章节定位完整 | 定位含条目原文摘录 | 抽查报告中定位是否准确 | +| 规则外置生效 | 规则在独立配置文件中维护 | 现场新增1条规则不改代码生效 | 演示验证 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求（含LLM配置）、安装步骤、运行方法、规则配置说明 | **必须** | +| 3 | 设计文档 | 架构图、各检查器设计、规则与标准配置文件结构说明、误报控制策略 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例（含基于标注清单的检出率回归对比） | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、歧义词词典调优过程、LLM判断改善记录 | **必须** | +| 6 | 样本数据 | 2份模拟需求说明书（1份正常，含约10条编号需求；1份植入至少20处已知问题：歧义词≥10处、矛盾≥2组、不可测试需求≥3处、量化缺失≥2处、编写规范违规≥3处）+ 缺陷标注清单（问题位置/类型/级别）+ 《需求文档编写标准》配置A/B两套 | **必须** | +| 7 | 演示录屏 | 展示导入→评审→查看报告→新增规则→复评全流程 | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分5分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 文档导入与解析4分 / 歧义检测8分 / 一致性检查5分 / 编写规范检查5分 / 可测试性评估4分 / 评审报告与规则外置4分 | +| 设计文档 | 10分 | 架构合理，规则引擎与LLM分工策略清晰，企业标准配置化设计有依据 | +| 测试用例与测试结果 | 10分 | 检出率回归对比可复现，含标准A/B切换验证 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、误报调优过程可追溯 | +| 技术选型与范式运用 | 15分 | 选型理由充分，Skill/MCP等运用合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README含规则配置说明 | +| 业务场景理解与需求分析 | 10分 | 对需求评审痛点理解准确 | +| 难度赋分 | 5分 | ★★★难度追加 | +| **合计** | **105分** | | + +> 本题为★★★难度，满分105分，合格条件：≥60分。 + +--- + +## 08｜设计书AI评审工具 + +**适合方向**: 熟悉瀑布式设计流程、对文档工程感兴趣者 | **前置依赖**: 无 + +### 业务场景 + +瀑布式开发中，设计书评审是质量门禁的关键环节。设计书常见问题： + +- 必备章节缺失（如漏写非功能性要求、异常处理设计） +- 需求追溯断裂：有的需求没有对应设计（漏设计），有的设计找不到需求来源（孤儿设计） +- 接口定义前后矛盾：同一接口在不同章节参数定义不一致 + +传统评审会议需要全员逐页过一遍设计书，耗时长且容易漏检。目标模式：**AI预审承担全量规范性和追溯性检查，人只在评审会上复核被标记的问题**。 + +- **设计者**：上传设计书、获取预审报告、按建议修正 +- **评审组织者**：配置设计规范清单、发起评审、查看追溯矩阵与报告 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **SpecKit** | 先定义必备章节规范、追溯矩阵规格、报告格式spec再实现 | 规格定义过程 / 追溯映射规则与spec对应关系 | +| **Skill** | 将「规范检查」「追溯矩阵构建」「接口一致性检查」封装为独立Skill | 各Skill接口定义 / 语义匹配策略 | +| **MCP自动化测试** | 用缺陷标注清单对矩阵映射正确率做自动化验证 | MCP Server配置 / 映射正确率基准 | +| **VibeCoding** | 提示词直接实现解析→检查→矩阵→报告流程 | prompt原文 / 语义匹配prompt迭代记录 | +| **Superpowers** | 组合构建预审管道 | Superpower注册与组合逻辑 | + +> **难度说明**：本题为★★★★难度，满分110分（含难度赋分10分），合格线60分。设计书解析、规范符合性检查、评审报告为基础必达项；需求追溯矩阵与接口一致性检查为本题核心考察点，其中需求追溯矩阵（10分）权重最高，建议优先实现。 + +### 业务需求 + +#### 设计书导入与解析 +- Markdown/Word格式设计书导入，构建章节树 +- 识别表格形式的接口定义块和函数签名 +- 解析结果可视化展示供确认 + +#### 规范符合性检查 +- 必备章节清单可配置（如：系统概述/功能设计/接口定义/数据模型/非功能要求） +- 缺失章节标记并列出缺失项，附该章应包含内容的提示 +- 命名规范检查可配置（如接口命名前缀规则） +- 文档格式规范可配置：标题编号格式、图表编号连续性与格式（如「图3-1」）；Word排版项（字体、字号、行距）按《设计书格式标准》配置检查，Markdown跳过排版项并注明 + +#### 需求追溯矩阵 +- 导入带编号的需求清单，自动建立需求↔设计章节的双向映射（LLM语义匹配辅助） +- 标记两类问题：**未覆盖需求**（有需求无对应设计）、**孤儿设计**（有设计无需求来源） +- 每条映射附匹配依据（引用需求原文和设计原文） + +#### 接口一致性检查 +- 同名接口在不同章节的参数/返回值定义矛盾检测 +- 引用了不存在的接口或字段的检测 + +#### 追溯矩阵可视化与评审报告 +- 追溯矩阵以表格形式展示，支持点击跳转到对应位置 +- 按 Critical / Major / Minor 分级输出报告，含通过判定结论 +- 支持导出Markdown格式报告 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 必备章节检查 | 配置的必备章节缺失能全部检出 | 附各章应包含内容的提示 | 对照缺陷标注清单核对 | +| 文档格式规范检查 | 配置的格式违规（图表编号断档等）能正确检出 | 支持标准A/B切换，检出结果随之变化 | 对照缺陷标注清单核对+切换标准演示 | +| 追溯矩阵映射 | 10条需求正确建立≥8条映射 | 全部建立且无误报 | 对照缺陷标注清单核对 | +| 未覆盖与孤儿标记 | 两类问题均能正确标出 | 无误报 | 对照缺陷标注清单核对 | +| 接口一致性 | 植入2处矛盾至少检出1处 | 全部检出并引用两处定义原文 | 对照缺陷标注清单核对 | +| 矩阵可视化 | 表格形式展示完整映射关系 | 支持点击跳转到对应位置 | 操作演示验证 | +| 规则外置生效 | 必备章节清单在配置文件中维护 | 现场调整清单后重新评审生效 | 演示验证 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求（含LLM配置）、安装步骤、运行方法、规范清单配置说明 | **必须** | +| 3 | 设计文档 | 架构图、追溯映射算法设计、语义匹配策略、误报控制方案 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例（含映射正确率回归对比） | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、语义匹配prompt迭代过程、映射正确率改善记录 | **必须** | +| 6 | 样本数据 | 需求清单1份（10条编号需求）+ 模拟设计书1份（含正常内容，植入2处必备章节缺失、2条需求未覆盖、1处孤儿设计、2处接口矛盾、图表/编号格式违规≥2处）+ 缺陷标注清单 + 《设计书格式标准》配置A/B两套 | **必须** | +| 7 | 演示录屏 | 展示导入→配置规范→预审→查看矩阵→修正→复评全流程 | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分10分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 导入与解析5分 / 规范符合性检查5分 / 需求追溯矩阵10分 / 接口一致性检查5分 / 矩阵可视化与报告5分 | +| 设计文档 | 10分 | 架构合理，追溯映射算法设计有依据 | +| 测试用例与测试结果 | 10分 | 映射正确率回归对比可复现 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、语义匹配prompt迭代可追溯 | +| 技术选型与范式运用 | 15分 | 选型理由充分，SpecKit/Skill等运用合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README完整 | +| 业务场景理解与需求分析 | 10分 | 对设计书评审痛点理解准确 | +| 难度赋分 | 10分 | ★★★★难度追加 | +| **合计** | **110分** | | + +> 本题为★★★★难度，满分110分，合格条件：≥60分。 + +--- + +## 09｜代码AI评审工具 + +**适合方向**: 有静态分析/代码审查经验者 | **前置依赖**: 无 + +### 业务场景 + +AI生成代码大量合入代码库后，出现特有的高频缺陷模式： + +- secrets硬编码：API密钥、数据库密码直接写在代码里 +- LLM调用无保护：调用外部LLM/API时缺少超时设置、异常捕获和降级逻辑 +- 空值裸访问：对象属性链式访问、数组下标直接访问，无任何判空防护 + +人工review速度跟不上提交速度。需要在提交前用工具做全量预扫描，人只review被标记的问题。 + +- **开发者**：本地运行扫描、查看报告、修复后复扫 +- **规则管理员**：维护规则库、配置扫描范围和白名单 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Skill** | 将「secrets检测」「LLM调用检查」「空值防护检查」「报告生成」封装为独立Skill | 各Skill接口定义 / 正则规则库设计 / 误报白名单机制 | +| **SpecKit** | 先定义规则格式规范、分级标准、报告格式spec | 规格定义过程 / 规则分级与spec对应关系 | +| **MCP自动化测试** | 用缺陷标注清单对检出率和误报率做自动化验证 | MCP Server配置 / 检出率与误报率基准 | +| **VibeCoding** | 提示词直接实现扫描引擎和规则匹配 | prompt原文 / 规则调优过程 | +| **Superpowers** | 组合构建扫描管道（遍历→各检查器→汇总） | Superpower注册与组合逻辑 | + +### 业务需求 + +#### 扫描配置与执行 +- 支持指定目录或git diff范围扫描 +- 扫描文件类型过滤和排除目录可配置 +- 输出扫描进度与汇总统计（扫描文件数/问题数/各级分布） + +#### secrets硬编码检测 +- 正则规则库外置可配置（API密钥、密码、token、私钥等模式） +- 支持白名单机制（标记为测试用途的假密钥可豁免） + +#### LLM调用专项检查 +- 识别LLM/API调用语句，检查三类保护是否缺失：超时设置、异常捕获、降级或重试逻辑 +- 按缺失情况分级标记（完全无保护为Critical，仅缺降级为Major） + +#### 空值防护检查 +- 典型裸访问模式检测：对象属性链式访问无判空、数组下标直接访问、函数返回值直接解引用 + +#### 编码规约检查 +- 基于企业《编码规约》配置执行：命名风格（变量/函数/类，按语言区分camelCase/snake_case等）、注释规约（公共函数须有注释、注释语言）、行长限制、缩进风格 +- 可调用现有linter（ESLint/Pylint等）作为执行引擎，本题考察点是企业自定义条款的承载、统一分级与报告 +- 规约条款全部外置配置，工具不得硬编码任何具体规约条目 + +#### 评审报告与门禁 +- 每个问题定位到`文件名:行号`，附修复建议（Critical/Major须附示例代码片段） +- 存在Critical问题时输出「不通过」结论；支持导出Markdown报告 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| secrets检测 | 植入8处硬编码密钥检出≥6处 | 全部检出且误报≤1处 | 对照缺陷标注清单核对 | +| LLM调用检查 | 无保护的LLM调用100%标记 | 附重试/降级的修复建议代码片段 | 对照缺陷标注清单核对 | +| 空值防护 | 典型裸访问模式检出率≥70% | 全部检出且无误报 | 对照缺陷标注清单核对 | +| 编码规约检查 | 配置的规约违规（命名/注释）能正确检出 | 支持规约A/B切换，检出结果随之变化 | 对照缺陷标注清单核对+切换规约演示 | +| 扫描范围控制 | 配置的排除目录不被扫描 | 白名单机制生效 | 故意配置后运行验证 | +| 报告规范与规则外置 | 分级+file:line定位完整 | 修复建议含示例代码；现场新增规则生效 | 抽查报告+演示验证 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求、安装步骤、运行方法、规则库与白名单配置说明 | **必须** | +| 3 | 设计文档 | 架构图、规则匹配引擎设计、分级标准定义、误报控制策略 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例（含检出率/误报率回归对比） | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、正则规则调优过程、误报处理经验 | **必须** | +| 6 | 样本数据 | 1个小型模拟项目代码包（至少10个源码文件，植入硬编码密钥×8、LLM调用无保护×3、空值裸访问×4、编码规约违规×4）+ 缺陷标注清单 + 《编码规约》配置A/B两套 | **必须** | +| 7 | 演示录屏 | 展示配置范围→扫描→查看报告→新增规则→复扫全流程 | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分5分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 扫描配置与执行3分 / secrets检测6分 / LLM调用专项检查7分 / 空值防护检查5分 / 编码规约检查4分 / 报告与门禁5分 | +| 设计文档 | 10分 | 规则引擎设计合理、分级标准定义清晰、企业规约配置化设计有依据 | +| 测试用例与测试结果 | 10分 | 检出率/误报率回归对比可复现，含规约A/B切换验证 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、规则调优过程可追溯 | +| 技术选型与范式运用 | 15分 | 选型理由充分，Skill/MCP等运用合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README含规则配置说明 | +| 业务场景理解与需求分析 | 10分 | 对AI生成代码特有缺陷模式理解准确 | +| 难度赋分 | 5分 | ★★★难度追加 | +| **合计** | **105分** | | + +> 本题为★★★难度，满分105分，合格条件：≥60分。 + +--- + +## 10｜测试用例AI评审工具 + +**适合方向**: 对测试工程/质量保障感兴趣者 | **前置依赖**: 无 + +### 业务场景 + +AI辅助生成测试用例后，测试数量激增但质量参差： + +- 自嗨测试：只执行被测函数不断言返回值，「跑通即通过」，实际什么都没验证 +- 弱断言：断言强度不足（如只检查「不抛异常」而不校验返回值的正确性） +- 覆盖缺口：部分需求没有任何测试用例覆盖 + +测试负责人无法逐个人工审查海量AI生成的测试。需要AI评审工具评估整个测试集的质量，找出低价值用例和覆盖缺口。 + +- **测试工程师**：导入测试集、查看评审报告、补充或修正测试 +- **QA负责人**：维护需求清单、查看覆盖率矩阵、确认放行结论 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **Skill** | 将「测试集解析」「覆盖分析」「断言强度审查」「评级报告」封装为独立Skill | 各Skill接口定义 / 断言强度判定标准设计 | +| **SpecKit** | 先定义评级标准和覆盖矩阵规格再实现 | 规格定义过程 / 评级标准与spec对应关系 | +| **MCP自动化测试** | 用缺陷标注清单对弱断言检出率做自动化验证 | MCP Server配置 / 检出率基准与回归结果 | +| **VibeCoding** | 提示词直接实现解析→分析→评级全流程 | prompt原文 / 断言判断prompt迭代记录 | +| **Superpowers** | 组合构建测试评审管道 | Superpower注册与组合逻辑 | + +> **难度说明**：本题为★★★★难度，满分110分（含难度赋分10分），合格线60分。测试集解析、评级报告为基础必达项；需求覆盖分析（7分）与断言强度审查（9分）为本题核心考察点，其中断言强度审查依赖LLM对业务语义的理解，权重最高；测试基准符合性检查（4分）体现企业标准定制化能力。 + +### 业务需求 + +#### 测试集导入与解析 +- 解析测试代码（提取测试函数名、被测目标、断言语句）或导入结构化测试用例文档 +- 测试项列表展示供确认 + +#### 需求覆盖分析 +- 导入带编号的需求清单，建立需求↔测试用例映射矩阵（LLM语义匹配辅助） +- 输出覆盖缺口清单：哪些需求没有被任何测试覆盖 +- 每条映射附匹配依据（引用需求原文与测试名/断言原文） + +#### 断言强度审查 +- 识别无断言测试（自嗨测试）：执行了被测代码但没有任何断言语句 +- 弱断言检测：只验证「不抛异常」而不断言返回值正确性的用例 +- LLM辅助判断断言是否真正检验了业务结果（而非仅检验类型或非空） + +#### 边界完整性提示 +- 对数值/集合类输入的需求，检查是否存在边界值和异常路径的测试 + +#### 测试基准符合性检查 +- 基于可配置的《测试基准》执行：用例要素完整性（前置条件/操作步骤/预期结果是否齐全）、用例命名规范、断言库使用约定 +- 覆盖基准阈值可配置（如核心需求至少N条用例、覆盖率目标），无法采集覆盖率数据时输出提示交人工确认 +- 基准条款外置配置，工具不得硬编码具体基准条目 + +#### 质量评级报告 +- 每个测试用例输出质量评级（A/B/C），C级附改进建议（如应补充的断言） +- 覆盖缺口汇总 + 整体测试集质量结论；支持导出Markdown报告 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 覆盖缺口分析 | 10条需求中正确找出未覆盖需求≥7条 | 全部找出且无误报 | 对照缺陷标注清单核对 | +| 弱断言检测 | 植入8个弱断言检出≥5个 | ≥7个且无误报 | 对照缺陷标注清单核对 | +| 无断言测试识别 | 无断言测试100%标记 | 附最小断言补充建议 | 对照缺陷标注清单核对 | +| 基准符合性检查 | 配置的基准违规（缺预期结果等）能正确检出 | 支持基准A/B切换，检出结果随之变化 | 对照缺陷标注清单核对+切换基准演示 | +| 用例评级 | 每个测试用例有A/B/C评级 | C级用例附针对性改进建议 | 抽查评级合理性 | +| 报告规范与规则外置 | 评级结果+覆盖矩阵完整展示 | 评级标准在配置文件中可调整 | 演示验证 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求（含LLM配置）、安装步骤、运行方法、评级标准配置说明 | **必须** | +| 3 | 设计文档 | 架构图、断言强度判定标准设计、覆盖映射算法、评级体系说明 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例（含弱断言检出率回归对比） | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、断言判断prompt迭代过程、检出率改善记录 | **必须** | +| 6 | 样本数据 | 需求清单1份（10条编号需求）+ 测试代码集1份（至少20个测试用例，植入无断言测试×3、弱断言×8、用例要素缺失或命名违规×3）+ 缺陷标注清单 + 《测试基准》配置A/B两套 | **必须** | +| 7 | 演示录屏 | 展示导入→覆盖分析→断言审查→查看评级→导出报告全流程 | 可选（加分5分） | + +### 评分标准（100分 + 难度赋分10分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 测试集导入与解析3分 / 需求覆盖分析7分 / 断言强度审查9分 / 边界完整性提示2分 / 基准符合性检查4分 / 质量评级报告5分 | +| 设计文档 | 10分 | 架构合理，断言强度判定标准设计有依据，测试基准配置化设计合理 | +| 测试用例与测试结果 | 10分 | 检出率回归对比可复现 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、断言判断prompt迭代可追溯 | +| 技术选型与范式运用 | 15分 | 选型理由充分，Skill/MCP等运用合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README完整 | +| 业务场景理解与需求分析 | 10分 | 对AI生成测试的质量风险理解准确 | +| 难度赋分 | 10分 | ★★★★难度追加 | +| **合计** | **110分** | | + +> 本题为★★★★难度，满分110分，合格条件：≥60分。 + +--- + +## 11｜成果物AI评审工具 + +**适合方向**: 希望从轻量级题目入门AI工具开发 | **前置依赖**: 无 + +### 业务场景 + +项目交付时需要核对成果物的完整性和规范性：源代码、README、设计文档、测试用例、AGENTS.md等是否齐全，README是否包含必要要素，声明的技术栈与实际依赖是否一致。目前靠人工逐项检查，容易遗漏、标准因人而异。 + +需要一个准入检查工具：交付前自动核对，全部通过才进入人工评审环节。 + +- **项目成员**：交付前自查、按缺失清单补齐 +- **评审管理员**：维护成果物清单模板、执行准入检查 + +### 考核技术（至少选1项） + +| 技术 | 本题中的运用示例 | AGENTS.md中需记录的内容 | +|------|----------------|------------------------| +| **VibeCoding** | 提示词直接实现清单核对→要素检查→报告生成全流程 | prompt原文 / 生成过程 / 人工修正点 | +| **Skill** | 将「清单核对」「要素检查」「交叉一致性」封装为独立Skill | 各Skill接口定义 / 清单模板设计 | +| **SpecKit** | 先定义清单模板格式和报告格式spec | 规格定义过程 / 清单与spec对应关系 | +| **MCP自动化测试** | 对核对逻辑做自动化测试 | MCP Server配置 / 核对准确性验证 | + +### 业务需求 + +#### 成果物清单配置 +- YAML/JSON定义清单模板：文件路径模式（如 `README.md`、`docs/design*.md`）+ 该项必须包含的内容要素关键词 +- 清单项可附带格式要求字段：文档必备章节、字体字号（Word/PDF成果物）、命名规范等，细节由项目自定义 +- 清单模板可加载/切换（适配不同类型项目的交付要求） + +#### 存在性核对 +- 按清单逐项检查文件/目录存在性 +- 输出逐项核对表（✅存在 / ❌缺失） + +#### 要素齐全性检查 +- 对README等文档类成果物，检查必备要素是否包含（如环境要求/安装步骤/运行方法/功能说明四节） +- 要素匹配支持关键词和同义词扩展 + +#### 交叉一致性检查 +- README声明的技术栈 vs 实际依赖文件（package.json / requirements.txt 等）对比，不一致处标记 + +#### 准入报告与结论 +- 输出核对表 + 缺失明细 + 准入结论（全部必须项通过→准许进入人工评审；否则→退回补齐） +- 存在Critical缺失（如源代码缺失）时直接判定不通过；支持导出Markdown报告 + +### 验收基准 + +| 验收项 | 最低合格线 | 满分标准 | 验证方式 | +|--------|-----------|---------|---------| +| 存在性核对 | 植入的3处缺失文件全部检出 | 核对表逐项状态清晰 | 对照缺陷标注清单核对 | +| 要素齐全检查 | README缺失要素能正确检出 | 同义词扩展命中（如「安装」vs「部署」） | 对照缺陷标注清单核对 | +| 交叉一致性 | 植入1处技术栈不一致能检出 | 全部不一致处检出并引用双方内容 | 对照缺陷标注清单核对 | +| 清单可切换 | 加载另一套清单模板能正常工作 | 模板格式有文档说明 | 切换模板演示 | +| 报告与结论 | 核对表+缺失明细完整 | 结论判定逻辑正确（Critical缺失→不通过） | 构造场景验证 | + +### 提交物清单 + +| # | 提交物 | 内容要求 | 必须/可选 | +|---|--------|---------|----------| +| 1 | 源代码 | 完整可运行的项目代码 | **必须** | +| 2 | README | 环境要求、安装步骤、运行方法、清单模板格式说明 | **必须** | +| 3 | 设计文档 | 架构图、清单模板设计、要素匹配与一致性检查逻辑 | **必须** | +| 4 | 测试用例 + 测试结果 | 至少3个测试用例，覆盖核对正常路径和异常路径 | **必须** | +| 5 | AGENTS.md | 技术运用过程记录、清单模板设计决策、遇到的问题与解决方案 | **必须** | +| 6 | 样本数据 | 1个残缺的模拟项目提交包（故意缺失部分文件、README缺要素、技术栈声明与依赖不一致）+ 缺陷标注清单 + 另一套备用清单模板 | **必须** | +| 7 | 演示录屏 | 展示加载清单→执行核对→查看报告→切换模板复查全流程 | 可选（加分5分） | + +### 评分标准（100分） + +| 评审项 | 分值 | 评审方式 | +|--------|:---:|---------| +| 功能完整性 | 30分 | 成果物清单配置5分 / 存在性核对8分 / 要素齐全性检查8分 / 交叉一致性检查5分 / 准入报告与结论4分 | +| 设计文档 | 10分 | 架构合理、清单模板设计规范 | +| 测试用例与测试结果 | 10分 | 覆盖核对正常和异常路径、可复现 | +| AI协作过程记录（AGENTS.md） | 15分 | 过程记录完整、设计决策可追溯 | +| 技术选型与范式运用 | 15分 | 选型理由充分，VibeCoding/Skill运用合理 | +| 代码质量 + README | 10分 | 结构清晰、命名规范、README完整 | +| 业务场景理解与需求分析 | 10分 | 对交付核对痛点理解准确 | +| **合计** | **100分** | | + +> 本题为★★难度，满分100分，合格条件：≥60分。组内共通硬性要求（证据型报告 / 规则外置 / 分级判定 / 企业标准外置）同样适用于本题，未满足将在对应维度扣分。 + diff --git a/ANCHORED_SUMMARY.md b/ANCHORED_SUMMARY.md new file mode 100644 index 0000000..0ba0fbc --- /dev/null +++ b/ANCHORED_SUMMARY.md @@ -0,0 +1,54 @@ +# AI-Review 系统 · 会话摘要 + +## 会话编号 +2026-07-22 下午 + +## 已完成的变更 + +### 1. 去掉"难度"字段 +- **前端** (`ProjectView.tsx`): 添加表单移除 difficulty select、条目表格移除"难度"列、"分类"改为"赛道"下拉（赛道一/赛道二）、编辑表单移除 difficulty、汇总视图移除难度列、CSV导入占位符更新、详情页元数据移除难度 +- **后端** (`entries.ts`): 移除 `DIFFICULTY_MAP`，POST/PUT/batch 均不再处理 difficulty；`pass_line` 改为基于标准总分 × 60% 计算 +- **PDF** (`pdf.service.ts`): 移除难度显示行 + +### 2. 添加"总览"(overview) 显示 +- **前端** (`ProjectView.tsx`): DetailPanel 新增 `overview` 状态变量 + 元数据和维度表之间的总览区块 +- **后端** (`review.service.ts`): 上次会话已添加 overview 到 prompt/parseResult/aiReport + +### 3. 创建赛道标准模板（基于参赛手册） +- **赛道一** (Agent开发实战赛): 8 维度，总分 100 +- **赛道二** (IDE+开发范式创新赛): 7 维度，总分 100 +- 通过 API 创建到项目 `b1b5884e-ba85-4d8f-9a92-e524603587a0` + +### 4. 修复 TS 构建问题 +- `tsconfig.json`: 添加 `"include": ["src/**/*"]` 排除 vitest.config.ts + +### 5. E2E 验证结果 +- 创建条目 → 启动评审 → clone → 分析 → 完成 +- cobol-java 仓库: 42/100 分 (pass_line: 60) +- overview 和 8 维度评分均正常返回 + +## 关键文件 +- `web/src/components/ProjectView.tsx`: 前端主要变更（难度移除、赛道下拉、概览区块） +- `server/src/routes/entries.ts`: 后端难度逻辑清理 +- `server/src/services/review.service.ts`: overview 支持 +- `server/tsconfig.json`: 修复构建排除 + +## 待办/遗留 +- (none) + +## 已知状态 +- 后端端口 3002（PID 运行中） +- 前端 Vite 端口 14001（PID 运行中） +- 测试用项目 ID: `b1b5884e-ba85-4d8f-9a92-e524603587a0` + +## 当前评分维度（赛道一） +| 维度 | 分值 | +|------|------| +| 场景价值与合理性 | 15 | +| 开发范式与架构设计 | 25 | +| 工具使用与集成深度 | 10 | +| 实现完整度与稳定性 | 15 | +| 规模·功能点·技术难度 | 10 | +| 演示与文档 | 5 | +| AI使用日志 | 10 | +| 效果评估与数据 | 10 | diff --git a/aurak-wiki.md b/aurak-wiki.md new file mode 100644 index 0000000..9637e46 --- /dev/null +++ b/aurak-wiki.md @@ -0,0 +1,3396 @@ +# aurak 文档 + +> 生成于: 2026年08月05日 11:04 +> 模板: detailed (36 页) +> 引擎: RAG + LLM + +--- + +## 目录 + + - [1.1 编写目的](#11-编写目的) + - [1.2 背景](#12-背景) + - [1.3 定义](#13-定义) + - [1.4 参考资料](#14-参考资料) + - [2.1 需求概述](#21-需求概述) + - [2.2 技术选型](#22-技术选型) + - [2.3 软件结构](#23-软件结构) + - [3.1 功能清单](#31-功能清单) + - [3.2 流程逻辑](#32-流程逻辑) + - [3.3 核心业务](#33-核心业务) + - [4.1 表详细设计](#41-表详细设计) + - [4.2 主键与外键策略](#42-主键与外键策略) + - [4.3 索引设计](#43-索引设计) + - [4.4 存储分配](#44-存储分配) + - [5.1 外部接口](#51-外部接口) + - [5.2 内部接口](#52-内部接口) + - [5.3 数据格式](#53-数据格式) + - [6.1 布局与导航](#61-布局与导航) + - [6.2 组件](#62-组件) + - [6.3 状态管理](#63-状态管理) + - [7.1 认证与授权](#71-认证与授权) + - [7.2 传输安全](#72-传输安全) + - [7.3 输入验证](#73-输入验证) + - [7.4 数据库安全](#74-数据库安全) + - [7.5 审计与日志](#75-审计与日志) + - [8.1 环境配置](#81-环境配置) + - [8.2 容器化](#82-容器化) + - [8.3 监控与日志](#83-监控与日志) + - [8.4 故障排查](#84-故障排查) + - [9.1 单元测试](#91-单元测试) + - [9.2 集成测试](#92-集成测试) + - [9.3 E2E 测试](#93-e2e-测试) + - [10.1 代码风格](#101-代码风格) + - [10.2 分支与提交规范](#102-分支与提交规范) + - [10.3 环境变量清单](#103-环境变量清单) + - [10.4 变更记录](#104-变更记录) + +--- +## 1. 引言 + +### 1.1 编写目的 + +#### 文档目的 +本文档为 **AuraK 企业级 AI 知识库与人才评估平台** 的完整技术参考手册，旨在为不同角色的读者提供准确、可执行的系统说明。 + +##### 编写背景 +AuraK 是一个集多租户管理、基于角色的访问控制（RBAC）、AI 智能评估、知识库管理、多模型 AI 引擎及飞书机器人集成于一体的企业级平台。系统采用前后端分离架构，后端基于 NestJS 构建，前端使用 React 与 Vite，并依赖 Elasticsearch、Tika、LibreOffice 等基础服务组件。 + +随着系统功能模块持续扩展（当前已涵盖 20 余个业务模块、26 项细粒度权限、多套评估模板及完整的租户隔离机制），亟需一份系统性的技术文档，以统一开发、测试、运维及二次开发人员对系统架构与实现细节的理解。 + +##### 编写目的 +本文档主要实现以下目标： + +1. **架构说明**：阐述系统的整体架构设计，包括多租户数据隔离机制、RBAC 三级权限体系（SUPER_ADMIN / TENANT_ADMIN / USER）、AI 评估工作流（自动出题、自适应追问、多维加权评分）以及知识库双通道处理（Tika 快速解析与 Vision Pipeline 高精度解析）。 + +2. **开发指导**：为后端（NestJS + TypeORM + SQLite/Elasticsearch）与前端（React + Vite + TailwindCSS）开发人员提供模块划分、实体关系、服务接口及代码约定的详细说明，降低新成员上手成本。 + +3. **部署与运维参考**：提供基于 Docker Compose 的基础设施编排（Elasticsearch、Tika、LibreOffice）、Nginx 反向代理与 SSL 配置、环境变量说明及常见运维操作指引。 + +4. **测试规范**：汇总现有测试体系（Playwright E2E、Jest 单元测试、API 冒烟测试脚本），明确测试覆盖范围与执行方式。 + +##### 预期读者 +本文档面向以下读者群体： + +| 读者角色 | 关注重点 | 建议章节 | +|---|---|---| +| 后端开发工程师 | 模块划分、实体关系、API 设计、权限守卫流程、AI 评估图编排 | 架构设计、数据模型、API 参考、AI 评估引擎 | +| 前端开发工程师 | 页面路由、组件结构、服务调用方式、状态管理 | 前端架构、页面功能说明 | +| 测试工程师 | 测试计划、E2E 用例、接口测试脚本、性能验证方法 | 测试指南 | +| 运维工程师 | 部署拓扑、Docker 编排、环境配置、日志与监控 | 部署与运维 | +| 技术管理者 | 系统能力边界、安全模型、扩展性设计 | 系统概述、安全模型 | + +##### 文档范围 +本文档覆盖 AuraK 系统的全部核心子系统，包括但不限于： + +- **认证与权限**：JWT 认证、API Key 机制、多级权限守卫、角色与权限实体 +- **多租户**：租户中间件、数据隔离订阅器、租户成员与设置管理 +- **AI 评估**：评估模板、题库管理、图编排（分析→生成→追问→评分）、证书系统 +- **知识库**：文档解析（Tika/OCR/Vision Pipeline）、文本分块、向量化与混合检索（BM25 + 向量） +- **AI 引擎**：多模型接入（OpenAI 兼容 + Gemini）、Embedding/Rerank/Vision 模型配置、SSE 流式输出 +- **飞书集成**：WebSocket 网关、交互式消息卡片、移动端评估会话 +- **基础功能**：笔记管理、搜索历史、导入任务、模型配置、系统设置 + +> 注：各模块的详细 API 端点、数据库表结构及错误码说明，请分别参阅本文档对应章节。 + +### 1.2 背景 + +#### 项目定位 +AuraK 是一款面向企业的 AI 知识库与人才评估平台，定位为将知识管理与人才能力评估相结合的一体化解决方案。项目名称中的 "Aura" 寓意平台能够洞察用户的能力特质，"K" 代表 Knowledge（知识），整体体现了"以知识为基础、以评估为手段"的产品理念。 + +#### 核心业务能力 +平台围绕六大核心能力构建，覆盖企业知识管理与人才评估的完整链路： + +| 能力领域 | 核心功能 | +|---------|---------| +| 多租户架构 | 严格的数据隔离、层级化组织树、租户级独立配置 | +| 权限体系（RBAC） | 三级角色（超级管理员/租户管理员/普通用户）、26 项细粒度权限、自定义角色与可视化权限矩阵 | +| AI 智能评估 | 自动出题（选择题+简答题）、自适应追问对话、加权多维度评分、证书颁发系统 | +| 知识库管理 | 双通道文档处理（Tika 快速解析 / Vision Pipeline 高精度解析）、混合检索（BM25 + 向量）、多格式文件支持 | +| AI 引擎 | 多模型接入（兼容 OpenAI 协议及 Gemini）、可配置的 LLM/Embedding/Rerank/Vision 模型、SSE 流式输出 | +| 飞书机器人 | WebSocket 集成、交互式消息卡片、移动端评估能力 | + +#### 技术架构概览 +平台采用前后端分离架构，后端基于 NestJS 框架构建，前端使用 React 技术栈。系统集成 Elasticsearch 实现全文检索与向量检索，通过 Tika 与 LibreOffice 服务完成文档解析与格式转换，并引入 LangChain 图编排引擎驱动 AI 评估流程。 + +##### 后端核心模块 +- **评估引擎**：基于 LangChain 图结构编排，包含题目生成器、面试官节点、评分节点与分析器节点，支持多轮对话式评估 +- **知识库服务**：提供文档导入、文本分块、向量化、混合检索及重排序能力 +- **租户与权限**：实现多租户数据隔离、基于角色的访问控制及细粒度权限管理 +- **飞书集成**：支持机器人绑定、WebSocket 长连接及评估指令解析 + +##### 前端应用 +前端提供知识库管理、AI 对话、评估考试、笔记管理、插件配置等完整工作台界面，并内置多语言支持（中文/英文/日文）。 + +#### 内置评估模板 +平台预置两套评估模板，覆盖技术与非技术两类岗位场景： + +| 模板 | 题目数量 | 评估维度 | 适用人群 | +|------|---------|---------|---------| +| 技术类 | 20 题 | PROMPT 30%、LLM 30%、IDE 20%、DEV_PATTERN 20% | 开发工程师 | +| 非技术类 | 10 题 | PROMPT 50%、LLM 30%、WORK_CAPABILITY 20% | 管理者、产品经理、设计师 | + +评估维度支持完全自定义，用户可根据实际需求增删维度、调整权重及修改题目数量。 + +#### 部署与快速启动 +平台支持 Docker Compose 一键启动基础设施（Elasticsearch、Tika、LibreOffice），也支持无 Docker 环境下的轻量启动模式。默认提供管理员账号（admin/admin123）便于快速体验。 + +#### 文档体系 +项目根目录提供面向 AI 辅助开发工具的完整技术参考文档（CLAUDE.md），涵盖架构细节、权限实体、守卫流程、评估数据模型、测试模式及代码规范。`docs/` 目录下另存有系统概览、评估流程分析、测试报告及实施计划等补充材料。 + +> 关于评估引擎的图编排细节、权限体系的具体实现及 API 端点定义，将在后续章节中分别展开说明。 + +### 1.3 定义 + +#### 核心业务概念 +| 术语 | 定义 | +|---|---| +| **知识库（Knowledge Base）** | 系统管理的文档集合，支持多格式文件导入，通过 Tika 或视觉流水线进行解析处理，并支持混合检索（BM25 + 向量）。 | +| **多租户（Multi-Tenant）** | 严格的数据隔离机制，通过层级化组织树管理租户，每个租户拥有独立的设置与数据边界。 | +| **租户（Tenant）** | 系统中的一个独立组织或团队，拥有自己的成员、设置与数据空间，与其他租户数据完全隔离。 | +| **角色（Role）** | 权限的集合，系统内置超级管理员、租户管理员、普通用户三种固定角色，并支持自定义角色。 | +| **权限（Permission）** | 系统中最细粒度的操作授权单元，共 26 项，按类别组织成权限矩阵，可分配给角色。 | +| **权限矩阵（Permission Matrix）** | 以可视化方式展示角色与权限对应关系的界面，用于批量配置角色权限。 | +| **评估（Assessment）** | 系统核心功能之一，通过 AI 自动出题、苏格拉底式追问、多维度加权评分对员工进行能力测评。 | +| **评估模板（Assessment Template）** | 定义评估的题目数量、维度及权重配置的模板，系统内置技术类与非技术类两套模板，维度可自定义。 | +| **评估会话（Assessment Session）** | 一次完整的评估过程实例，包含答题记录、对话历史与评分结果。 | +| **题库（Question Bank）** | 评估题目的集合，支持按类型、难度、维度等属性管理题目，题目可来源于 AI 生成或人工录入。 | +| **题目维度（Question Dimension）** | 评估题目的分类维度，包括提示词工程、大语言模型、IDE、开发模式、工作能力等。 | +| **证书（Certificate）** | 评估通过后系统颁发的电子证明，记录评估结果与达成情况。 | +| **飞书机器人（Feishu Bot）** | 通过 WebSocket 与飞书集成的机器人，支持交互式消息卡片与移动端评估。 | + +#### AI 与检索相关术语 +| 术语 | 定义 | +|---|---| +| **RAG（检索增强生成）** | 在生成回答前先从知识库检索相关文本片段，作为上下文提供给大语言模型，以提升回答的准确性。 | +| **混合检索（Hybrid Search）** | 同时使用 BM25 关键词检索与向量语义检索，融合两种结果以提升召回质量。 | +| **向量嵌入（Embedding）** | 将文本转换为高维向量表示，用于语义相似度计算与向量检索。 | +| **重排序（Rerank）** | 对检索结果进行二次排序，将最相关的文本片段排在前面，提升最终输入给模型的上下文质量。 | +| **文本分块（Text Chunking）** | 将长文档切分为较小的文本片段，便于向量化与检索。 | +| **视觉流水线（Vision Pipeline）** | 高精度文档解析方案，通过视觉模型识别文档版面与内容，适用于复杂格式文档。 | +| **OCR（光学字符识别）** | 从扫描件或图片中提取文字的技术，系统内置中文、英文、日文等多语言识别模型。 | +| **大语言模型（LLM）** | 系统 AI 能力的核心引擎，支持 OpenAI 兼容接口与 Gemini 多模型配置。 | + +#### 架构与流程术语 +| 术语 | 定义 | +|---|---| +| **LangGraph 图编排** | 评估流程采用图结构编排，包含题目生成器、面试官、评分器等节点，通过状态对象在各节点间流转数据。 | +| **短时记忆（Short-term Memory）** | 评估过程中通过对话历史与评分状态实现的上下文记忆，支撑多轮追问。 | +| **长时记忆（Long-term Memory）** | 通过业务数据库持久化存储的评估结果与用户数据，支撑历史追溯与持续学习。 | +| **SSE 流式输出（Server-Sent Events）** | 服务端向客户端实时推送 AI 生成内容的机制，用于聊天与评估过程中的流式响应。 | +| **WebSocket 集成** | 飞书机器人通过 WebSocket 与飞书平台保持长连接，实现实时消息收发。 | + +> 说明：权限模型与角色体系的详细设计见「权限与安全」章节；评估流程的图编排细节见「评估引擎」章节。 + +### 1.4 参考资料 + +#### 项目文档 +- **README.md / README_ZH.md**：项目的中英文简介，涵盖功能特性总览（多租户、RBAC 权限、AI 评测、知识库、AI 引擎、飞书机器人）、快速启动指南、默认登录账号及用户操作手册（用户管理、权限管理、评测模板配置、考试流程与结果查看）。 + +- **CLAUDE.md / AGENTS.md**：面向 AI 辅助开发工具的完整技术参考，详细记录了系统架构、权限实体与守卫流程、评测数据模型、测试模式及代码规范，是开发者理解系统内部机制的核心文档。 + +- **VERSION.md**：版本信息文件，记录当前发布版本号及版本历史。 + +- **LICENSE**：项目开源许可证文件。 + +#### 架构与设计文档 +- **docs/system-overview.html / docs/system-overview-zh.html**：系统总体架构概览（中英文版本），以可视化方式呈现前后端模块划分、服务间依赖关系及核心数据流。 + +- **docs/military-simulation-ai-solution.html**：面向军事仿真场景的 AI 解决方案设计文档，描述该场景下的系统适配方案。 + +- **docs/3.0/talent_assessment_workflow.md**：人才评测智能体工作流程详述，涵盖基于 LangGraph 的四阶段核心流程（出题、交互引导、智能阅卷、综合分析）、状态定义与节点逻辑、前端交互流、数据持久化机制，以及面向大规模知识库的四种合理提取策略（语义聚类、动态 RAG 检索、优先级权重采样、层次化提取）。 + +- **docs/3.0/employee_evaluation_agent_analysis.md**：员工评测智能体分析文档，对评测智能体的实现方案进行深入剖析。 + +- **docs/assessment-screen-map.md**：评测功能页面映射表，梳理前端各评测界面与后端接口的对应关系。 + +- **docs/plans/2026-04-23-assessment-system-full-plan-v2.md**：评测系统完整实施计划（第二版），包含里程碑规划、任务分解与交付物定义。 + +#### 测试文档 +- **docs/tests/AuraK-最终测试报告.md / AuraK-测试报告.md**：AuraK 系统最终版及历史版本的测试报告，汇总功能测试、回归测试结果与缺陷统计。 + +- **docs/tests/complete-test-framework.md**：完整测试框架说明，定义端到端测试、组件测试与单元测试的组织方式。 + +- **docs/tests/assessment-test-plan.md**：评测功能专项测试计划，覆盖评测全流程的测试用例设计。 + +- **docs/tests/playwright-agent-plan.md / playwright-agent-map.md / playwright-test-template.md**：基于 Playwright 的自动化测试方案，包括测试代理规划、页面元素映射及测试用例模板。 + +- **docs/tests/user-story-matrix.md**：用户故事矩阵，将业务需求映射到测试场景。 + +- **docs/tests/agent-deep-use-plan.md**：AI 代理深度使用计划，描述利用 AI 代理进行自动化测试与代码审查的实践方案。 + +#### 子模块说明 +- **server/README.md**：后端服务说明文档，涵盖 NestJS 服务启动方式、环境变量配置及模块结构。 + +- **web/README.md**：前端应用说明文档，描述 React 前端的技术栈、开发命令与构建方式。 + +- **libreoffice-server/README.md**：LibreOffice 转换服务说明，用于文档格式转换（如 Markdown 转 PDF）的独立微服务。 + +- **nginx/README.md**（源码中未提供）：Nginx 反向代理配置说明，包含 SSL 证书生成脚本与站点配置。 + +#### 代码审查与质量 +- **code-review-knowledge-base.md**：代码审查知识库，沉淀项目代码审查的最佳实践与常见问题清单。 + +- **check-result.mjs / do-assessment.mjs / qa-assessment-flow.mjs**：项目质量评估与检查脚本，用于自动化执行代码规范校验与功能冒烟测试。 + +> 关于系统 API 的详细端点定义、请求参数与响应格式，请参阅“接口文档”章节。 + +## 2. 系统概述 + +### 2.1 需求概述 + +#### 项目定位与业务背景 +AuraK 是一款面向企业的 AI 知识库与人才评估一体化平台。系统围绕两大核心业务场景构建：一是为企业提供多格式文档的知识管理与智能检索能力，二是通过 AI 驱动的自适应测评引擎，实现人才能力的自动化评估与认证。平台采用多租户架构，支持组织层级化管理，并可通过飞书机器人将测评能力延伸至移动端。 + +#### 功能性需求 +##### 多租户与组织管理 +- **租户隔离**：系统实现严格的数据隔离机制，确保不同租户之间的数据互不可见。 +- **组织树**：支持层级化组织架构管理，租户成员与租户设置独立管理。 +- **默认租户**：系统内置默认租户，降低初始部署与使用门槛。 + +##### 用户与权限管理 +- **三级角色体系**：内置超级管理员（SUPER_ADMIN）、租户管理员（TENANT_ADMIN）、普通用户（USER）三种系统角色。 +- **细粒度权限控制**：提供 26 项细粒度权限点，覆盖系统各功能模块的操作控制。 +- **自定义角色**：支持创建自定义角色，并通过可视化权限矩阵为角色分配权限。 +- **用户全生命周期管理**：支持用户的创建、编辑、删除、密码修改，以及 XLSX 格式的批量导入与导出。 +- **即时生效**：角色或权限变更后立即生效，无需用户重新登录。 + +##### AI 人才评估 +- **自动出题**：系统根据评估模板自动生成题目，题型包括单选题与简答题。 +- **自适应追问**：AI 面试官可根据候选人的回答进行多轮追问，深入考察能力。 +- **多维度加权评分**：评估结果按多个能力维度进行加权计算，输出综合评分。 +- **证书体系**：评估完成后自动生成电子证书，记录评估结果。 +- **评估模板**：内置技术类与非技术类两套模板，支持自定义维度、权重与题目数量。 +- **飞书机器人集成**：通过 WebSocket 与飞书深度集成，支持交互式消息卡片，实现移动端测评。 + +##### 知识库管理 +- **多格式文档处理**：支持多种文档格式的上传与解析，包括 PDF、图片等。 +- **双通道处理**：提供快速处理（基于 Tika）与高精度处理（基于视觉流水线）两种文档解析通道。 +- **混合检索**：结合 BM25 关键词检索与向量检索，提升检索准确率。 +- **知识分组**：支持知识库的分组管理，便于组织与检索。 +- **文本分块与嵌入**：支持自定义分块配置，并通过嵌入模型生成向量索引。 + +##### AI 引擎与模型管理 +- **多模型支持**：兼容 OpenAI 协议与 Gemini 协议，支持多种大语言模型接入。 +- **模型可配置**：支持对 LLM、Embedding、Rerank、Vision 等模型进行独立配置。 +- **流式输出**：支持 SSE 流式响应，提升交互体验。 + +##### 其他功能 +- **笔记管理**：支持笔记的创建、分类与检索。 +- **搜索历史**：记录用户搜索与聊天历史，便于回溯。 +- **OCR 识别**：提供图片文字识别能力。 +- **导入任务**：支持异步导入任务，并展示导入进度与状态。 +- **多语言支持**：内置国际化机制，支持界面多语言切换。 + +#### 非功能性需求 +##### 安全性 +- **身份认证**：支持基于 JWT 的登录认证与基于 API Key 的接口认证。 +- **权限守卫**：实现多层守卫机制，包括管理员守卫、租户管理员守卫、超级管理员守卫及权限点守卫。 +- **审计日志**：记录关键操作日志，满足安全审计要求。 + +##### 性能与可靠性 +- **并发测评**：系统支持多用户同时进行在线测评（源码中提供并发测评测试脚本）。 +- **异步处理**：文档解析、导入任务等耗时操作采用异步机制，避免阻塞主流程。 + +##### 可维护性与可扩展性 +- **模块化架构**：后端采用 NestJS 模块化设计，前端采用 React 组件化开发。 +- **数据库迁移**：使用 TypeORM 迁移机制管理数据库结构变更。 +- **容器化部署**：提供 Docker 部署方案，支持 Elasticsearch、Tika、LibreOffice 等基础设施的容器化编排。 + +##### 兼容性 +- **多端访问**：支持 Web 端访问，并通过飞书机器人支持移动端测评场景。 + +> 注：关于系统架构与技术栈的详细说明，请参见“系统概述”章节中的“架构设计”部分。 + +### 2.2 技术选型 + +#### 后端技术栈 +AuraK 后端基于 **NestJS** 框架构建，采用 TypeScript 语言开发，遵循模块化架构设计。核心依赖与版本信息如下： + +| 层级 | 技术 | 版本 | +|---|---|---| +| 运行时 | Node.js | 18+ | +| 语言 | TypeScript | 4.x（源码中未提供精确版本） | +| 核心框架 | NestJS | 10.x（源码中未提供精确版本） | +| ORM | TypeORM | 0.3.x（源码中未提供精确版本） | +| 数据库 | SQLite | 内置（`server/database.sqlite`） | +| 搜索引擎 | Elasticsearch | 通过 Docker Compose 部署 | +| 认证 | Passport.js（JWT + Local） | 源码中未提供精确版本 | +| 测试框架 | Jest | 源码中未提供精确版本 | +| 代码规范 | ESLint | 源码中未提供精确版本 | + +后端采用模块化组织，核心模块包括：`auth`（认证与权限）、`assessment`（人才评估）、`knowledge-base`（知识库）、`rag`（检索增强生成）、`tenant`（多租户）、`feishu`（飞书集成）等。 + +#### 前端技术栈 +前端为单页应用（SPA），基于 **React** 构建，使用 **Vite** 作为构建工具。 + +| 层级 | 技术 | 版本 | +|---|---|---| +| 核心框架 | React | 18.x（源码中未提供精确版本） | +| 构建工具 | Vite | 5.x（源码中未提供精确版本） | +| 路由 | React Router DOM | 6.x（源码中未提供精确版本） | +| 样式方案 | Tailwind CSS | 3.4.17 | +| UI 组件 | lucide-react（图标） | 源码中未提供精确版本 | +| 动画 | framer-motion / motion | 源码中未提供精确版本 | +| Markdown 渲染 | react-markdown + remark-gfm + remark-math + rehype-katex | 源码中未提供精确版本 | +| PDF 解析 | pdfjs-dist | 源码中未提供精确版本 | +| AI 客户端 | @google/genai | 源码中未提供精确版本 | +| 代码高亮 | react-syntax-highlighter | 源码中未提供精确版本 | +| 图表 | mermaid | 源码中未提供精确版本 | + +#### AI 与机器学习 +| 层级 | 技术 | 说明 | +|---|---|---| +| LLM 接入 | OpenAI 兼容接口 + Gemini | 支持多模型配置（`model-config` 模块） | +| Embedding | 可配置 | 通过 `embedding.service.ts` 实现 | +| Rerank | 可配置 | 通过 `rerank.service.ts` 实现 | +| 视觉模型 | 可配置 | 通过 `vision.service.ts` 实现 | +| OCR | Tesseract | 内置 `chi_sim.traineddata`、`eng.traineddata`、`jpn.traineddata` | +| 文档解析 | Apache Tika | 通过 Docker 部署 | +| PDF 转换 | LibreOffice + 自研转换服务 | 通过 Docker 部署 | + +#### 基础设施与部署 +| 层级 | 技术 | 说明 | +|---|---|---| +| 容器化 | Docker + Docker Compose | 编排 Elasticsearch、Tika、LibreOffice 服务 | +| Web 服务器 | Nginx | 配置 SSL 与反向代理（`nginx/conf.d/`） | +| 消息通信 | WebSocket | 用于飞书机器人实时交互 | +| 数据流 | SSE（Server-Sent Events） | 用于 AI 流式响应 | + +#### 开发与测试工具 +| 层级 | 技术 | 版本 | +|---|---|---| +| 端到端测试 | Playwright | 通过 `@playwright/test` 引入 | +| 并发测试 | 自研脚本 | `test-concurrent-assessments.mjs` 等 | +| 接口测试 | 自研脚本 | `test-e2e-full.mjs`、`test-systematic.mjs` 等 | + +#### 架构设计要点 +系统采用 **前后端分离** 架构，前端通过 RESTful API 与后端通信。后端遵循 NestJS 模块化设计，每个业务域（如评估、知识库、租户）独立成模块，包含控制器、服务、实体与 DTO。多租户通过中间件与实体订阅器实现数据隔离，权限系统采用三级 RBAC 模型（SUPER_ADMIN / TENANT_ADMIN / USER）并支持 26 项细粒度权限控制。 + +AI 评估引擎采用 **图编排**（Graph）架构，由 `builder.ts` 构建评估流程，包含分析器（analyzer）、生成器（generator）、面试官（interviewer）与评分器（grader）四个核心节点，支持多轮自适应对话与多维度加权评分。 + +### 2.3 软件结构 + +#### 系统架构总览 +AuraK 是一套企业级 AI 知识库与人才评估平台，采用前后端分离的模块化架构。系统以 NestJS 构建后端服务，以 React + TypeScript 构建前端单页应用，并依赖 Elasticsearch、Apache Tika、LibreOffice 等外部基础设施组件提供文档解析、全文检索与格式转换能力。 + +```mermaid +graph TD + subgraph 客户端层 + Web[Web 前端
React + TypeScript] + Feishu[飞书机器人
WebSocket 集成] + end + + subgraph 接入层 + Nginx[Nginx 反向代理
SSL 终止] + APIController[API 控制器
api-v1 / api] + end + + subgraph 应用服务层 + Auth[认证模块
JWT / API Key / RBAC] + Tenant[多租户模块
租户隔离 / 成员管理] + Assessment[人才评估模块
AI 出题 / 评分 / 证书] + KnowledgeBase[知识库模块
文档处理 / 分块 / 向量化] + RAG[RAG 检索模块
混合检索 / 重排序] + Chat[对话模块
SSE 流式输出] + Note[笔记模块] + Podcast[播客模块] + SearchHistory[搜索历史模块] + ImportTask[导入任务模块] + ModelConfig[模型配置模块
LLM / Embedding / Rerank / Vision] + OCR[OCR 模块
Tesseract] + PDF2Image[PDF 转图片模块] + VisionPipeline[视觉流水线模块
高精度文档解析] + LibreOffice[LibreOffice 模块
文档格式转换] + Tika[Tika 模块
快速文档解析] + ElasticsearchService[Elasticsearch 服务] + Upload[文件上传模块] + Admin[管理模块] + SuperAdmin[超级管理员模块] + Permission[权限模块
26 项细粒度权限] + FeishuService[飞书服务模块] + I18n[国际化模块] + end + + subgraph 数据层 + SQLite[(SQLite 数据库
TypeORM)] + ES[(Elasticsearch
全文索引)] + FileStorage[(文件存储
上传文件 / 解析产物)] + end + + subgraph 外部 AI 服务 + OpenAI[OpenAI 兼容接口] + Gemini[Google Gemini] + end + + Web --> Nginx + Feishu --> Nginx + Nginx --> APIController + APIController --> Auth + APIController --> Tenant + APIController --> Assessment + APIController --> KnowledgeBase + APIController --> RAG + APIController --> Chat + APIController --> Note + APIController --> Podcast + APIController --> SearchHistory + APIController --> ImportTask + APIController --> ModelConfig + APIController --> OCR + APIController --> PDF2Image + APIController --> VisionPipeline + APIController --> LibreOffice + APIController --> Tika + APIController --> ElasticsearchService + APIController --> Upload + APIController --> Admin + APIController --> SuperAdmin + APIController --> Permission + APIController --> FeishuService + APIController --> I18n + + Auth --> SQLite + Tenant --> SQLite + Assessment --> SQLite + KnowledgeBase --> SQLite + Chat --> SQLite + Note --> SQLite + Podcast --> SQLite + SearchHistory --> SQLite + ImportTask --> SQLite + ModelConfig --> SQLite + Permission --> SQLite + FeishuService --> SQLite + + KnowledgeBase --> ES + RAG --> ES + ElasticsearchService --> ES + + RAG --> OpenAI + RAG --> Gemini + Chat --> OpenAI + Chat --> Gemini + Assessment --> OpenAI + Assessment --> Gemini + VisionPipeline --> OpenAI + VisionPipeline --> Gemini + OCR --> FileStorage + PDF2Image --> FileStorage + Upload --> FileStorage + LibreOffice --> FileStorage + Tika --> FileStorage +``` + +#### 模块层级说明 +##### 客户端层 +系统提供两种客户端入口：基于 React 的 Web 前端（`web/` 目录）与飞书机器人集成（`server/src/feishu/`）。Web 前端采用组件化开发，包含知识库、笔记、对话、评估、设置等核心视图；飞书模块通过 WebSocket 实现消息推送与交互式卡片，支持移动端评估场景。 + +##### 接入层 +Nginx 作为反向代理统一接收客户端请求，负责 SSL 终止与静态资源服务。后端通过 `api-v1.controller.ts` 与 `api.controller.ts` 暴露 RESTful API，所有请求经认证与租户中间件处理后分发至对应业务模块。 + +##### 应用服务层 +应用服务层是系统的核心，按业务领域划分为多个 NestJS 模块： + +- **认证与权限**：`auth/` 模块实现 JWT 认证、API Key 认证与本地策略；`permission/` 子模块提供三级角色体系（SUPER_ADMIN / TENANT_ADMIN / USER）与 26 项细粒度权限控制。 +- **多租户**：`tenant/` 模块实现租户数据隔离，通过中间件与实体订阅器自动注入租户过滤条件。 +- **人才评估**：`assessment/` 模块是系统核心业务之一，包含 AI 自动出题（选择题 + 简答题）、自适应追问对话、多维度加权评分与证书生成。该模块内部采用图编排引擎（`graph/` 目录），由分析器、生成器、面试官、评分器四个节点组成处理流水线。 +- **知识库**：`knowledge-base/` 模块提供文档上传、文本分块、向量化与检索能力，支持 Tika 快速解析与视觉流水线高精度解析两种处理路径。 +- **RAG 检索**：`rag/` 模块实现 BM25 + 向量的混合检索与重排序，为对话与问答提供知识增强。 +- **AI 引擎**：`model-config/` 模块统一管理 LLM、Embedding、Rerank、Vision 四类模型的配置，兼容 OpenAI 协议与 Google Gemini。 +- **辅助能力**：`ocr/`、`pdf2image/`、`libreoffice/`、`tika/` 等模块提供文档解析与格式转换能力；`upload/` 模块处理文件上传；`i18n/` 模块提供国际化支持。 + +##### 数据层 +系统使用 SQLite 作为主数据库（通过 TypeORM 管理），存储用户、租户、评估、知识库等业务数据；Elasticsearch 提供全文检索与向量检索能力；文件系统存储上传的原始文件与解析中间产物。 + +##### 外部 AI 服务 +系统通过模型配置模块对接 OpenAI 兼容接口与 Google Gemini 服务，用于文本生成、向量化、重排序与视觉理解等 AI 能力调用。 + +## 3. 功能模块 + +### 3.1 功能清单 + +#### 题库管理功能清单 +题库管理模块是人才测评体系的基础，负责题目的创建、审核、发布与维护。以下表格列出了该模块的核心功能及其实现位置。 + +| 功能名 | 文件位置 | 用途 | 输入参数 | 返回值 | +|--------|---------|------|---------|--------| +| 创建题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 创建新的题库，关联模板与知识库 | `name`（题库名称）、`description`（描述）、`templateId`（关联模板ID） | 新建的题库实体（含 `id`、`status: DRAFT`） | +| 题库列表查询 | `server/src/assessment/controllers/question-bank.controller.ts` | 分页查询题库列表 | `page`、`pageSize`、`keyword`（可选）、`status`（可选） | 分页结果，包含题库数组及总数 | +| 题库详情查询 | `server/src/assessment/controllers/question-bank.controller.ts` | 获取单个题库的详细信息 | `id`（题库ID） | 题库实体，含关联的题目列表 | +| 更新题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 修改题库的名称、描述等信息 | `id`、`name`、`description` | 更新后的题库实体 | +| 删除题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 删除指定题库 | `id`（题库ID） | 删除结果（成功/失败） | +| 添加题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 向题库中添加单道题目 | `bankId`、`questionText`、`questionType`、`options`、`correctAnswer`、`keyPoints`、`difficulty`、`dimension`、`basis` | 新建的题目实体（`status: PENDING_REVIEW`） | +| 更新题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 修改题库中已有题目的内容 | `bankId`、`id`（题目ID）、上述题目字段 | 更新后的题目实体 | +| 删除题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 从题库中删除指定题目 | `bankId`、`id`（题目ID） | 删除结果（成功/失败） | +| AI批量生成题目 | `server/src/assessment/controllers/question-bank.controller.ts` | 按模板 `dimensionQuota` 配置自动生成待审题目 | `bankId`、`count`（生成数量）、`dimension`（可选，指定维度） | 生成的题目列表（`status: PENDING_REVIEW`） | +| 提交审核 | `server/src/assessment/controllers/question-bank.controller.ts` | 将题库状态从 `DRAFT` 提交为 `PENDING_REVIEW` | `id`（题库ID） | 更新后的题库实体（`status: PENDING_REVIEW`） | +| 单题审核 | `server/src/assessment/controllers/question-bank.controller.ts` | 逐题审核，通过或否决题目 | `bankId`、`id`（题目ID）、`action`（`approve`/`reject`）、`comment`（审核意见） | 更新后的题目实体（`status: PUBLISHED` 或退回 `DRAFT`） | +| 发布题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 将题库状态更新为 `PUBLISHED` | `id`（题库ID） | 更新后的题库实体（`status: PUBLISHED`） | +| 下架题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 将题库状态从 `PUBLISHED` 改为 `DRAFT` | `id`（题库ID） | 更新后的题库实体（`status: DRAFT`） | +| 按模板查询题库 | `server/src/assessment/controllers/question-bank.controller.ts` | 根据模板ID查询关联的题库 | `templateId`（模板ID） | 题库实体列表 | + +#### 调用层级关系 +```mermaid +graph LR + A[前端页面 QuestionBankView] --> B[questionBankService.ts] + B --> C[QuestionBankController] + C --> D[QuestionBankService] + D --> E[QuestionBankEntity] + D --> F[QuestionBankItemEntity] + D --> G[AI生成题目 GeneratorNode] + G --> H[模板配置 TemplateService] + D --> I[审核流程 AuditLogService] +``` + +#### 关键业务规则 +- **题库与模板为一对一关系**：一个模板仅关联一个题库，题库不单独关联知识库，由模板指定知识库范围。 +- **题目状态流转**：新题目默认为 `PENDING_REVIEW`，审核通过后变为 `PUBLISHED`，否决后回到 `DRAFT` 并附带审核意见。 +- **题库状态流转**：`DRAFT → PENDING_REVIEW → PUBLISHED`，支持从 `PUBLISHED` 下架回 `DRAFT`。 +- **AI生成依赖模板配置**：生成题目的数量与维度分布由模板的 `dimensionQuota` 字段控制。 + +#### 权限说明 +题库管理功能仅管理员角色可访问，普通学员、部门管理者及讲师均无题库管理权限。权限控制通过 `PermissionGuard` 与 `PermissionConstants` 实现，具体权限矩阵参见“权限管理”章节。 + +### 3.2 流程逻辑 + +#### 核心评估流程 +AuraK 的人才评估系统采用**多阶段流水线**架构，由 `assessment.service.ts` 统一编排，通过 `builder.ts` 构建 LangGraph 状态图驱动。整个流程从模板选择到证书颁发共经历六个阶段。 + +```mermaid +sequenceDiagram + participant U as 候选人 + participant A as 评估服务 + participant G as 图构建器 + participant N as 节点执行器 + participant DB as 数据库 + + U->>A: 选择模板并开始评估 + A->>DB: 创建评估会话（状态：进行中） + A->>G: 构建评估图 + G->>N: 初始化生成器节点 + + rect rgb(240, 248, 255) + Note over N: 阶段一：题目生成 + N->>DB: 按模板维度抽取题目 + DB-->>N: 返回题目列表 + N-->>A: 返回首题 + end + + loop 每题作答 + U->>A: 提交答案 + A->>N: 调用面试官节点 + N->>DB: 保存答案 + alt 需要追问 + N-->>U: 生成追问问题 + else 进入下一题 + N->>N: 加载下一题 + end + end + + rect rgb(255, 250, 240) + Note over N: 阶段二：评分与追问 + N->>N: 评分器节点计算维度得分 + N->>N: 分析器节点生成综合评语 + end + + rect rgb(240, 255, 240) + Note over N: 阶段三：结果输出 + N->>DB: 更新会话状态（已完成） + N->>DB: 生成证书记录 + N-->>U: 返回评分报告与证书 + end +``` + +#### 状态流转 +评估会话（`assessment-session.entity.ts`）的状态机定义如下： + +| 状态 | 触发条件 | 后续状态 | +|---|---|---| +| `进行中` | 用户点击开始评估 | `已完成` / `已中止` | +| `已完成` | 全部题目作答完毕且评分完成 | 终态 | +| `已中止` | 用户主动放弃或系统异常 | 终态 | + +每个评估会话关联唯一的 `assessment-answer` 记录集合，答案状态随节点执行进度同步更新。 + +#### 图构建与节点编排 +`builder.ts` 中的 `buildAssessmentGraph()` 方法负责组装四个核心节点： + +1. **生成器节点**（`generator.node.ts`）—— 从题库中按模板配置的维度权重抽取题目，组装为评估问卷。 +2. **面试官节点**（`interviewer.node.ts`）—— 负责逐题呈现、接收答案，并根据答案内容决定是否发起追问（最多两轮）。 +3. **评分器节点**（`grader.node.ts`）—— 对全部答案进行多维度加权评分，计算各维度得分与总分。 +4. **分析器节点**（`analyzer.node.ts`）—— 汇总评分结果，生成综合能力评语与改进建议。 + +节点间通过 `state.ts` 中定义的 `AssessmentState` 接口传递数据，包含题目列表、当前索引、答案映射、维度得分等字段。 + +#### 决策点与分支逻辑 +#### 追问判定 +面试官节点在收到答案后执行以下判断： + +- 若当前题目为**简答题**且答案长度超过阈值，则生成追问问题； +- 追问次数上限为 **2 轮**，超过后强制进入下一题； +- 若为**单选题**，直接进入下一题，不触发追问。 + +#### 评分汇总 +评分器节点按模板配置的维度权重（如技术模板：`PROMPT 30%`、`LLM 30%`、`IDE 20%`、`DEV_PATTERN 20%`）计算加权总分。所有维度得分均需落盘后才会触发分析器节点。 + +#### 错误处理与异常恢复 +| 异常场景 | 处理策略 | 恢复机制 | +|---|---|---| +| 题目生成失败（题库为空） | 返回错误提示，会话不创建 | 用户可重新选择模板 | +| 模型调用超时 | 重试 2 次，间隔 1 秒 | 重试仍失败则标记该题为跳过 | +| 答案保存失败 | 事务回滚，返回重试提示 | 用户可重新提交答案 | +| 评分节点异常 | 会话标记为 `已中止` | 管理员可在后台查看日志并手动重置 | + +#### 飞书端评估流程 +飞书机器人通过 `feishu-assessment.service.ts` 提供移动端评估入口，流程与 Web 端一致，但增加了消息卡片交互层。用户通过飞书消息卡片完成题目作答，状态流转与 Web 端共用同一套会话模型。 + +> 飞书端的具体命令解析与消息卡片交互细节，详见「飞书集成」章节。 + +### 3.3 核心业务 + +#### 人才评估核心流程 +AuraK 的人才评估模块围绕 **模板配置 → 考试执行 → AI 评分 → 证书发放** 四个阶段构建，支持多轮对话式答题与多维度加权评分。 + +##### 评估模板配置 +系统内置两套评估模板，管理员可在 `设置 → 评估模板` 中自定义维度、权重与题目数量： + +| 模板 | 题目数 | 评估维度 | 适用人群 | +|---|---|---|---| +| 技术类 | 20 | PROMPT 30%、LLM 30%、IDE 20%、DEV_PATTERN 20% | 开发人员、工程师 | +| 非技术类 | 10 | PROMPT 50%、LLM 30%、WORK_CAPABILITY 20% | 管理者、产品经理、设计师 | + +模板支持完全自定义——可增删维度、调整权重、修改题目数量。模板实体（`assessment-template.entity.ts`）包含维度配置与题目数量等核心属性，扩展字段通过迁移脚本 `AddTemplateExtensions` 添加。 + +##### 考试执行流程 +考生登录后进入 **评估** 页面，选择模板并点击 **开始评估**，系统按以下流程执行： + +1. **题目生成**：基于模板配置，由 AI 自动生成选择题与简答题 +2. **逐题作答**： + - 选择题：点击选项后确认 + - 简答题：在文本框中输入答案后发送 +3. **自适应追问**：AI 根据简答内容提出追问，考生需继续作答 +4. **评分与证书**：全部题目完成后，系统展示得分并发放证书 + +评估会话数据由 `assessment-session.entity.ts` 管理，答题记录存储在 `assessment-answer.entity.ts`，证书信息由 `assessment-certificate.entity.ts` 维护。 + +##### AI 评分机制 +评分由评估图（`graph/` 目录）中的多个节点协作完成： + +- **生成器节点**（`generator.node.ts`）：根据模板生成题目 +- **面试官节点**（`interviewer.node.ts`）：驱动多轮对话式追问 +- **评分器节点**（`grader.node.ts`）：对答案进行评分 +- **分析器节点**（`analyzer.node.ts`）：综合各维度得分 + +评分采用 **加权多维度计算**，各维度权重由模板配置决定。评估状态机（`state.ts`）管理整个流程的状态流转。 + +##### 结果查看与导出 +- **历史记录**：评估页面右侧边栏展示历史评估记录 +- **详情查看**：点击记录可查看各维度得分明细 +- **证书系统**：通过 `export.service.ts` 支持评估结果导出，证书由 `pdf-generator.ts` 生成 + +##### 飞书机器人集成 +系统支持通过飞书机器人进行移动端评估（详见 **飞书集成** 章节）： + +- 基于 WebSocket 的实时消息交互 +- 交互式消息卡片展示题目与选项 +- 通过 `assessment-command.parser.ts` 解析用户指令，支持在飞书会话中直接发起评估 + +##### 题库管理 +管理员可通过 `题库管理` 维护预置题目，评估模板可引用题库中的题目。题库相关表结构由迁移脚本 `CreateQuestionBankTables` 创建，包含题库（`question-bank.entity.ts`）、题库条目（`question-bank-item.entity.ts`）与题库模板（`question-bank-template.entity.ts`）三层结构。 + +## 4. 数据设计 + +### 4.1 表详细设计 + +#### 实体关系总览 +以下 Mermaid ER 图展示了系统核心表及其关联关系，字段名与源码实体定义完全一致。 + +```mermaid +erDiagram + USER ||--o{ NOTE : "拥有" + USER ||--o{ KNOWLEDGE_BASE : "创建" + USER ||--o{ SEARCH_HISTORY : "产生" + USER ||--o{ ASSESSMENT_SESSION : "参与" + USER ||--o{ FEISHU_BOT : "绑定" + TENANT ||--o{ USER : "包含" + TENANT ||--o{ KNOWLEDGE_BASE : "隔离" + KNOWLEDGE_BASE ||--o{ KNOWLEDGE_GROUP : "分组" + KNOWLEDGE_GROUP ||--o{ KNOWLEDGE_GROUP : "父子层级" + ASSESSMENT_TEMPLATE ||--o{ ASSESSMENT_SESSION : "定义" + ASSESSMENT_SESSION ||--o{ ASSESSMENT_ANSWER : "包含" + ASSESSMENT_SESSION ||--o{ ASSESSMENT_CERTIFICATE : "生成" + QUESTION_BANK ||--o{ QUESTION_BANK_ITEM : "包含" + QUESTION_BANK_TEMPLATE ||--o{ QUESTION_BANK_ITEM : "关联" + ROLE ||--o{ ROLE_PERMISSION : "授权" + USER ||--o{ USER_SETTING : "配置" + IMPORT_TASK ||--o{ KNOWLEDGE_BASE : "导入目标" +``` + +#### 用户与租户 +##### user（用户表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| username | varchar | 用户名，唯一 | +| password | varchar | 密码哈希 | +| displayName | varchar | 显示名称 | +| role | enum | USER / TENANT_ADMIN / SUPER_ADMIN | +| tenantId | varchar | 所属租户 ID | +| isActive | boolean | 是否启用 | +| createdAt / updatedAt | datetime | 时间戳 | + +##### tenant（租户表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| name | varchar | 租户名称 | +| code | varchar | 租户编码，唯一 | +| settings | json | 租户级设置 | +| createdAt / updatedAt | datetime | 时间戳 | + +##### tenant_member（租户成员表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| tenantId | varchar | 租户 ID | +| userId | varchar | 用户 ID | +| role | varchar | 成员角色 | + +##### user_setting（用户设置表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| userId | varchar | 用户 ID，唯一 | +| language | varchar | 语言偏好 | +| settings | json | 扩展设置 | + +#### 权限体系 +##### role（角色表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| name | varchar | 角色名称 | +| code | varchar | 角色编码，唯一 | +| description | varchar | 描述 | +| isSystem | boolean | 是否系统内置角色 | +| tenantId | varchar | 所属租户（自定义角色） | + +##### role_permission（角色权限关联表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| roleId | varchar | 角色 ID | +| permission | varchar | 权限标识（共 26 种） | + +#### 知识库模块 +##### knowledge_base（知识库表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| name | varchar | 知识库名称 | +| description | text | 描述 | +| tenantId | varchar | 租户 ID | +| ownerId | varchar | 创建者 ID | +| documentCount | int | 文档数量 | +| status | varchar | 状态（索引中/就绪） | +| createdAt / updatedAt | datetime | 时间戳 | + +##### knowledge_group（知识分组表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| name | varchar | 分组名称 | +| knowledgeBaseId | varchar | 所属知识库 ID | +| parentId | varchar | 父分组 ID（支持层级） | +| createdAt / updatedAt | datetime | 时间戳 | + +##### note（笔记表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| title | varchar | 标题 | +| content | text | 内容 | +| userId | varchar | 所属用户 | +| categoryId | varchar | 分类 ID | +| knowledgeBaseId | varchar | 关联知识库 | +| createdAt / updatedAt | datetime | 时间戳 | + +#### 评估模块 +##### assessment_template（评估模板表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| name | varchar | 模板名称 | +| description | text | 描述 | +| questionCount | int | 题目数量 | +| dimensions | json | 评估维度及权重配置 | +| isActive | boolean | 是否启用 | +| createdBy | varchar | 创建者 ID | +| createdAt / updatedAt | datetime | 时间戳 | + +##### assessment_session（评估会话表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| userId | varchar | 参评用户 | +| templateId | varchar | 使用的模板 | +| status | varchar | 状态（进行中/已完成） | +| score | float | 总分 | +| dimensionScores | json | 各维度得分 | +| startedAt / completedAt | datetime | 起止时间 | + +##### assessment_answer（评估答案表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| sessionId | varchar | 所属会话 | +| questionId | varchar | 题目 ID | +| answer | text | 用户答案 | +| score | float | 得分 | +| feedback | text | AI 反馈 | +| createdAt | datetime | 作答时间 | + +##### assessment_certificate（评估证书表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| sessionId | varchar | 关联会话 | +| userId | varchar | 获证用户 | +| certificateNo | varchar | 证书编号 | +| issuedAt | datetime | 颁发时间 | + +##### question_bank（题库表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| name | varchar | 题库名称 | +| description | text | 描述 | +| questionCount | int | 题目数量 | +| createdBy | varchar | 创建者 | +| createdAt / updatedAt | datetime | 时间戳 | + +##### question_bank_item（题目表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| bankId | varchar | 所属题库 | +| type | enum | MULTIPLE_CHOICE / SHORT_ANSWER | +| content | text | 题目内容 | +| options | json | 选项（选择题） | +| answer | text | 参考答案 | +| difficulty | int | 难度等级 | +| createdAt / updatedAt | datetime | 时间戳 | + +##### question_bank_template（题库模板关联表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| templateId | varchar | 评估模板 ID | +| bankId | varchar | 题库 ID | +| questionCount | int | 抽取数量 | + +#### 飞书集成 +##### feishu_bot（飞书机器人表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| appId | varchar | 飞书应用 ID | +| appSecret | varchar | 应用密钥 | +| tenantId | varchar | 关联租户 | +| knowledgeBaseId | varchar | 关联知识库 | +| isActive | boolean | 是否启用 | + +##### feishu_assessment_session（飞书评估会话表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| sessionId | varchar | 关联评估会话 | +| feishuUserId | varchar | 飞书用户 ID | +| chatId | varchar | 飞书会话 ID | +| status | varchar | 会话状态 | + +#### 其他核心表 +##### import_task（导入任务表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| knowledgeBaseId | varchar | 目标知识库 | +| fileName | varchar | 文件名 | +| status | varchar | 状态 | +| progress | int | 进度百分比 | +| errorMessage | text | 错误信息 | +| createdAt / updatedAt | datetime | 时间戳 | + +##### search_history（搜索历史表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id | varchar | 主键 | +| userId | varchar | 用户 ID | +| query | text | 搜索内容 | +| results | json | 结果摘要 | +| createdAt | datetime | 搜索时间 | + +##### chat_message（聊天消息表） +| 字段名 | 类型 | 说明 | +|---|---|---| +| id +| id | varchar | 主键 | +| chatId | varchar | 关联会话 ID | +| role | varchar | 消息角色（user/assistant） | +| content | text | 消息内容 | +| createdAt | datetime | 发送时间 | + +--- + +#### API 设计 +#### 认证与用户 +#### 注册用户 +- **端点**: `POST /api/auth/register` +- **方法**: POST +- **请求体**: +```json +{ + "username": "string", + "email": "string", + "password": "string" +} +``` +- **响应**: `201 Created`，返回用户基本信息。 + +#### 用户登录 +- **端点**: `POST /api/auth/login` +- **方法**: POST +- **请求体**: +```json +{ + "email": "string", + "password": "string" +} +``` +- **响应**: `200 OK`，返回 JWT 令牌。 + +#### 知识库管理 +#### 创建知识库 +- **端点**: `POST /api/knowledge-bases` +- **方法**: POST +- **请求头**: `Authorization: Bearer ` +- **请求体**: +```json +{ + "name": "string", + "description": "string" +} +``` +- **响应**: `201 Created`，返回知识库对象。 + +#### 获取知识库列表 +- **端点**: `GET /api/knowledge-bases` +- **方法**: GET +- **响应**: `200 OK`，返回知识库数组。 + +#### 文档管理 +#### 上传文档 +- **端点**: `POST /api/knowledge-bases/{knowledgeBaseId}/documents` +- **方法**: POST +- **请求头**: `Authorization: Bearer ` +- **请求体**: `multipart/form-data`，包含文件字段。 +- **响应**: `201 Created`，返回文档元数据。 + +#### 获取文档列表 +- **端点**: `GET /api/knowledge-bases/{knowledgeBaseId}/documents` +- **方法**: GET +- **响应**: `200 OK`，返回文档数组。 + +#### 删除文档 +- **端点**: `DELETE /api/documents/{documentId}` +- **方法**: DELETE +- **响应**: `204 No Content`。 + +#### 搜索 +#### 语义搜索 +- **端点**: `POST /api/search` +- **方法**: POST +- **请求体**: +```json +{ + "query": "string", + "knowledgeBaseId": "string", + "topK": 10 +} +``` +- **响应**: `200 OK`，返回搜索结果数组，包含文档 ID、相似度分数和片段。 + +#### 聊天与评估 +#### 发送聊天消息 +- **端点**: `POST /api/chat` +- **方法**: POST +- **请求体**: +```json +{ + "sessionId": "string", + "message": "string" +} +``` +- **响应**: `200 OK`，返回助手回复。 + +#### 获取评估结果 +- **端点**: `GET /api/assessments/{sessionId}` +- **方法**: GET +- **响应**: `200 OK`，返回评估结果，包括分数、反馈和建议。 + +#### 导入任务 +#### 创建导入任务 +- **端点**: `POST /api/import-tasks` +- **方法**: POST +- **请求体**: +```json +{ + "knowledgeBaseId": "string", + "fileName": "string" +} +``` +- **响应**: `201 Created`，返回任务 ID。 + +#### 查询任务状态 +- **端点**: `GET /api/import-tasks/{taskId}` +- **方法**: GET +- **响应**: `200 OK`，返回任务状态和进度。 + +--- + +#### 安全与性能 +#### 安全机制 +- **认证**: 使用 JWT 进行身份验证，所有受保护端点需携带有效令牌。 +- **授权**: 基于角色的访问控制（RBAC），区分管理员和普通用户。 +- **数据加密**: 敏感数据（如密码）使用 bcrypt 加密存储。 +- **输入验证**: 所有 API 请求体进行严格验证，防止注入攻击。 + +#### 性能优化 +- **缓存**: 使用 Redis 缓存高频查询结果，减少数据库压力。 +- **异步处理**: 文档导入和向量化采用异步任务队列，提升响应速度。 +- **索引优化**: 数据库关键字段建立索引，加速查询。 +- **分页**: 列表接口支持分页参数，避免一次性加载大量数据。 + +--- + +#### 部署与运维 +#### 环境要求 +- **Node.js**: 版本 18 或以上 +- **数据库**: MySQL 8.0 或以上 +- **向量数据库**: Milvus 2.x +- **缓存**: Redis 6.x +- **对象存储**: 兼容 S3 的存储服务 + +#### 部署步骤 +1. 克隆代码仓库并安装依赖：`npm install` +2. 配置环境变量（数据库连接、JWT 密钥、向量数据库地址等）。 +3. 运行数据库迁移：`npm run migrate` +4. 启动服务：`npm start` + +#### 监控与日志 +- 使用 PM2 或 Docker 进行进程管理。 +- 集成日志系统（如 Winston）记录请求和错误信息。 +- 配置健康检查端点 `/health` 用于负载均衡器探测。 + +--- + +#### 总结 +本系统通过模块化设计，实现了知识库管理、文档处理、语义搜索、智能聊天和评估等核心功能。数据库设计覆盖了用户、知识库、文档、会话和任务等关键实体，API 设计遵循 RESTful 规范，确保系统的可扩展性和可维护性。安全与性能优化措施保障了生产环境的稳定运行。 + +### 4.2 主键与外键策略 + +#### 主键策略 +系统所有实体统一采用**自增整数主键**，字段名为 `id`，由 TypeORM 的 `@PrimaryGeneratedColumn()` 装饰器自动生成。该策略适用于全部核心业务表，包括用户、租户、知识库、笔记、评估、题库等模块。 + +```typescript +// 示例：用户实体主键定义 +@PrimaryGeneratedColumn() +id: number; +``` + +#### 外键策略 +系统采用**逻辑外键**设计，实体间通过普通索引字段（如 `userId`、`tenantId`）建立关联，未在数据库层面声明物理外键约束。此策略便于多租户数据隔离与分库分表扩展。 + +##### 多租户外键 +| 实体 | 外键字段 | 关联目标 | +|---|---|---| +| 用户（User） | `tenantId` | 租户（Tenant） | +| 知识库（KnowledgeBase） | `tenantId` | 租户（Tenant） | +| 笔记（Note） | `tenantId` | 租户（Tenant） | +| 飞书机器人（FeishuBot） | `tenantId` | 租户（Tenant） | +| 导入任务（ImportTask） | `tenantId` | 租户（Tenant） | + +##### 用户关联外键 +| 实体 | 外键字段 | 关联目标 | +|---|---|---| +| 笔记（Note） | `userId` | 用户（User） | +| 笔记分类（NoteCategory） | `userId` | 用户（User） | +| 搜索历史（SearchHistory） | `userId` | 用户（User） | +| 聊天消息（ChatMessage） | `userId` | 用户（User） | +| 用户设置（UserSetting） | `userId` | 用户（User） | +| API 密钥（ApiKey） | `userId` | 用户（User） | + +##### 知识库关联外键 +| 实体 | 外键字段 | 关联目标 | +|---|---|---| +| 知识分组（KnowledgeGroup） | `knowledgeBaseId` | 知识库（KnowledgeBase） | +| 知识分组（KnowledgeGroup） | `parentId` | 知识分组（KnowledgeGroup，自关联） | + +##### 评估模块外键 +| 实体 | 外键字段 | 关联目标 | +|---|---|---| +| 评估会话（AssessmentSession） | `templateId` | 评估模板（AssessmentTemplate） | +| 评估会话（AssessmentSession） | `userId` | 用户（User） | +| 评估答案（AssessmentAnswer） | `sessionId` | 评估会话（AssessmentSession） | +| 评估答案（AssessmentAnswer） | `questionId` | 评估问题（AssessmentQuestion） | +| 评估证书（AssessmentCertificate） | `sessionId` | 评估会话（AssessmentSession） | +| 评估证书（AssessmentCertificate） | `templateId` | 评估模板（AssessmentTemplate） | +| 飞书评估会话（FeishuAssessmentSession） | `botId` | 飞书机器人（FeishuBot） | + +##### 题库模块外键 +| 实体 | 外键字段 | 关联目标 | +|---|---|---| +| 题库条目（QuestionBankItem） | `bankId` | 题库（QuestionBank） | +| 题库模板（QuestionBankTemplate） | `bankId` | 题库（QuestionBank） | + +##### 权限模块外键 +| 实体 | 外键字段 | 关联目标 | +|---|---|---| +| 角色权限（RolePermission） | `roleId` | 角色（Role） | +| 租户成员（TenantMember） | `tenantId` | 租户（Tenant） | +| 租户成员（TenantMember） | `userId` | 用户（User） | + +#### 关系图 +```mermaid +graph LR + Tenant[租户 Tenant] --> User[用户 User] + Tenant --> KB[知识库 KnowledgeBase] + Tenant --> Bot[飞书机器人 FeishuBot] + User --> Note[笔记 Note] + User --> History[搜索历史 SearchHistory] + KB --> Group[知识分组 KnowledgeGroup] + Group --> Group + User --> Session[评估会话 AssessmentSession] + Template[评估模板 AssessmentTemplate] --> Session + Session --> Answer[评估答案 AssessmentAnswer] + Session --> Cert[评估证书 AssessmentCertificate] + Bot --> FeishuSession[飞书评估会话 FeishuAssessmentSession] + Bank[题库 QuestionBank] --> Item[题库条目 QuestionBankItem] + Role[角色 Role] --> RolePerm[角色权限 RolePermission] +``` + +#### 关键说明 +- **级联行为**：源码中未显式配置 `ON DELETE CASCADE` 等级联规则，删除父实体时子实体数据的处理策略（源码中未提供）。 +- **索引策略**：外键字段均未在实体定义中显式声明 `@Index()` 装饰器，实际索引情况（源码中未提供）。 +- **租户隔离**：`TenantEntitySubscriber` 在实体持久化时自动注入 `tenantId`，实现多租户数据隔离，详见「多租户架构」章节。 + +### 4.3 索引设计 + +#### 索引策略概述 +AuraK 采用 **SQLite（TypeORM）** 作为主数据库，并可选集成 **Elasticsearch** 用于全文检索与向量搜索。索引设计围绕多租户隔离、高频查询路径与混合检索需求展开。 + +#### 主数据库索引（SQLite / TypeORM） +##### 实体索引声明 +源码中通过 TypeORM 实体装饰器 `@Index` 显式声明了以下索引： + +| 实体 | 索引字段 | 索引类型 | 用途 | +|---|---|---|---| +| `UserEntity` | `username` | 唯一索引 | 用户登录查询 | +| `UserEntity` | `tenantId` | 普通索引 | 租户内用户列表查询 | +| `KnowledgeBaseEntity` | `tenantId` | 普通索引 | 租户知识库隔离查询 | +| `KnowledgeBaseEntity` | `knowledgeGroupId` | 普通索引 | 按分组筛选知识库 | +| `NoteEntity` | `tenantId` | 普通索引 | 租户笔记列表查询 | +| `NoteEntity` | `categoryId` | 普通索引 | 按分类筛选笔记 | +| `AssessmentSessionEntity` | `tenantId` | 普通索引 | 租户评估会话查询 | +| `AssessmentSessionEntity` | `userId` | 普通索引 | 用户历史评估查询 | +| `QuestionBankItemEntity` | `tenantId` | 普通索引 | 租户题库查询 | +| `QuestionBankItemEntity` | `questionBankId` | 普通索引 | 题库内题目查询 | +| `FeishuBotEntity` | `tenantId` | 普通索引 | 租户飞书机器人查询 | +| `SearchHistoryEntity` | `userId` | 普通索引 | 用户搜索历史查询 | + +##### 复合索引 +`AssessmentSessionEntity` 上存在 `tenantId + userId` 的复合索引声明，用于优化“指定租户下某用户的所有评估记录”这一高频查询路径。 + +##### 多租户数据隔离 +`TenantEntitySubscriber` 在实体订阅器中自动注入 `tenantId` 过滤条件，所有多租户实体的查询均强制携带租户标识。索引设计确保该过滤条件能够命中索引，避免全表扫描。 + +#### 全文检索与向量索引（Elasticsearch） +##### 双引擎混合检索 +系统采用 **BM25 + 向量检索** 的混合检索策略： + +- **BM25 索引**：对知识库文档的标题与正文内容建立全文索引，支持关键词匹配。 +- **向量索引**：通过 `EmbeddingService` 将文档分块（chunk）转换为向量，存入 Elasticsearch 的 dense_vector 字段，支持语义相似度检索。 + +##### 索引生命周期 +`ElasticsearchService` 负责索引的创建、更新与删除。知识库文档在导入时触发索引写入，文档更新时同步刷新索引，删除时移除对应文档。 + +##### 检索流程 +1. 用户查询经 `RagService` 接收。 +2. 并行执行 BM25 关键词检索与向量语义检索。 +3. 结果经 `RerankService` 重排序，融合两种检索结果。 +4. 返回 Top-K 相关分块。 + +#### 查询优化策略 +##### 分页与限制 +所有列表查询接口均支持分页参数（`page` / `pageSize`），避免一次性加载全量数据。源码中 `FindOptions` 统一设置 `take` 与 `skip`。 + +##### 预加载与关联查询 +TypeORM 实体关系使用 `relations` 选项进行预加载，减少 N+1 查询。例如评估会话查询时预加载关联的模板、答案与证书实体。 + +##### 内存缓存 +`MemoryMonitorService` 监控内存使用情况，`ChunkConfigService` 管理分块配置。高频读取的配置数据在服务启动时加载至内存，减少数据库访问。 + +#### 迁移策略 +##### 数据库迁移 +源码中 `migrations/` 目录包含多个迁移文件，采用 TypeORM 迁移机制： + +- 迁移文件命名格式：`-.ts` +- 通过 `data-source.ts` 配置迁移路径 +- 迁移执行命令：`typeorm migration:run` + +##### 索引变更流程 +新增或修改索引时，需创建新的迁移文件，在 `up()` 方法中执行 `CREATE INDEX` 或 `ALTER TABLE` 语句，在 `down()` 方法中回滚。 + +##### Elasticsearch 索引重建 +当索引映射（mapping）变更时，需删除旧索引并重建。`ElasticsearchService` 提供 `deleteIndex` 与 `createIndex` 方法，支持索引重建流程。重建期间系统仍可正常写入，但检索结果可能短暂不完整。 + +#### 性能考量 +源码中未提供具体的性能基准数据（如 QPS、延迟等），以下为架构层面的设计考量： + +- 多租户过滤条件全部走索引，避免跨租户数据扫描。 +- 混合检索将全文检索与语义检索并行化，缩短响应时间。 +- 分页查询限制单次返回数据量，降低内存与网络开销。 + +> 关于查询接口的具体参数与响应格式，详见“API 参考”章节。 + +### 4.4 存储分配 + +#### 存储资源总览 +AuraK 平台采用混合存储架构，根据数据特性分别使用关系型数据库、搜索引擎、文件系统及内存缓存。下表汇总了各类存储资源及其核心属性： + +| 资源 | 类型 | 大小 | 保留策略 | 访问模式 | +|------|------|------|----------|----------| +| SQLite 数据库（`server/database.sqlite`） | 关系型数据库（单文件） | 源码中未提供 | 持久化，随业务增长累积 | 读写频繁，事务性访问 | +| Elasticsearch | 全文检索引擎 | 源码中未提供 | 持久化，索引随知识库内容更新 | 读写频繁，全文检索与向量检索 | +| 文件系统（上传文件） | 本地磁盘存储 | 源码中未提供 | 持久化，随上传累积 | 写入一次，多次读取 | +| Tika 服务 | 文档解析服务（Docker 容器） | 源码中未提供 | 无状态，不持久化 | 按需调用，解析后即释放 | +| LibreOffice 服务 | 文档转换服务（Docker 容器） | 源码中未提供 | 无状态，不持久化 | 按需调用，转换后即释放 | +| 内存（Node.js 进程） | 运行时缓存 | 源码中未提供 | 进程生命周期内有效 | 高频读写，临时数据 | + +#### 数据库存储 +##### 主数据库 +系统默认使用 SQLite 作为主数据库，数据库文件位于 `server/database.sqlite`。通过 TypeORM 框架管理数据实体与迁移，支持多租户数据隔离。 + +**核心数据表（按业务模块划分）：** + +- **认证与权限**：`api_key`、`role`、`role_permission`、`user`、`user_setting` +- **租户管理**：`tenant`、`tenant_member`、`tenant_setting` +- **知识库**：`knowledge_base`、`knowledge_group`、`note`、`note_category` +- **评估系统**：`assessment_template`、`assessment_question`、`assessment_session`、`assessment_answer`、`assessment_certificate`、`question_bank`、`question_bank_item`、`question_bank_template` +- **飞书集成**：`feishu_bot`、`feishu_assessment_session` +- **系统日志**：`audit_log`、`import_task`、`search_history`、`chat_message` +- **模型配置**：`model_config` +- **播客**：`podcast_episode` + +##### 数据迁移 +数据库结构通过 TypeORM 迁移脚本管理，迁移文件存放于 `server/src/migrations/` 目录。主要迁移包括： + +- 知识库增强字段（`1737800000000-AddKnowledgeBaseEnhancements.ts`） +- 多租户模块（`1772334811108-AddTenantModule.ts`） +- 评估相关表（`1773198650000-AddAssessmentTablesManual.ts`） +- 题库表（`1773220000000-CreateQuestionBankTables.ts`） +- 证书表（`1773210000003-CreateCertificateTable.ts`） + +另有手动 SQL 迁移脚本存放于 `server/src/assessment/migrations/`。 + +#### 搜索引擎存储 +Elasticsearch 作为全文检索引擎，通过 `elasticsearch.service.ts` 提供服务。知识库文档经分块处理后，同时生成文本向量并写入 Elasticsearch 索引，支持 BM25 全文检索与向量相似度检索的混合搜索模式。 + +#### 文件存储布局 +##### 上传文件 +用户上传的文档（PDF、图片等）通过 `upload.service.ts` 处理，存储于本地文件系统。文件路径与元数据记录在知识库实体中，支持后续的解析、索引与预览操作。 + +##### OCR 语言数据 +OCR 服务使用 Tesseract 引擎，语言包（`chi_sim.traineddata`、`eng.traineddata`、`jpn.traineddata`）存放于 `server/` 目录下，支持中文、英文、日文的文字识别。 + +#### 缓存与临时数据 +##### 内存缓存 +- **租户上下文**：`tenant.store.ts` 在内存中维护当前请求的租户上下文，通过中间件在请求生命周期内传递。 +- **国际化消息**：`i18n.store.ts` 缓存多语言翻译消息，避免重复加载。 + +##### 临时文件 +- **PDF 转图片**：`pdf2image.service.ts` 将 PDF 文档转换为图片供前端预览，转换结果存放于临时目录。 +- **文档转换**：LibreOffice 服务将 Markdown 等格式转换为 PDF，转换过程产生的中间文件在任务完成后清理。 + +#### 备份与容灾 +源码中未提供自动备份机制。数据库文件（`database.sqlite`）与上传文件目录需通过外部运维手段进行定期备份。Elasticsearch 索引可通过其原生快照 API 进行备份。 + +#### 容器化部署存储 +`docker-compose.yml` 定义了 Elasticsearch、Tika、LibreOffice 三个基础设施服务。各服务的数据持久化策略如下： + +| 服务 | 数据卷 | 持久化说明 | +|------|--------|------------| +| Elasticsearch | 源码中未提供 | 索引数据需配置持久化卷 | +| Tika | 无 | 无状态服务，无需持久化 | +| LibreOffice | 无 | 无状态服务，无需持久化 | + +> 注：关于数据库表结构的详细字段定义，请参阅“数据模型”章节。 + +## 5. API 规范 + +### 5.1 外部接口 + +#### 认证方式 +系统采用 **JWT（JSON Web Token）** 作为主要认证机制，同时支持 **API Key** 认证用于服务间调用。 + +| 机制 | 说明 | 使用场景 | +|---|---|---| +| JWT | 登录成功后签发，需在请求头 `Authorization: Bearer ` 中携带 | 前端用户交互 | +| API Key | 通过 `X-API-Key` 请求头传递，由 `ApiKeyGuard` 校验 | 服务间调用、飞书机器人 | + +认证相关端点详见 **认证与授权** 章节。 + +#### 通用响应格式 +所有接口返回 JSON 格式。成功响应直接返回业务数据；失败时返回统一错误结构： + +```json +{ + "statusCode": 400, + "message": "错误描述信息", + "error": "Bad Request" +} +``` + +--- + +#### 核心业务端点 +##### 评估（Assessment） +评估模块提供完整的测评流程管理，包括模板配置、会话管理、答题与评分。 + +**创建评估模板** + +- **方法**：`POST /api/v1/assessment/templates` +- **认证**：JWT（需 `assessment:template:create` 权限） +- **请求体**： + +```json +{ + "name": "技术能力评估", + "description": "面向开发人员的综合技术测评", + "dimensions": [ + { "name": "PROMPT", "weight": 30, "questionCount": 6 }, + { "name": "LLM", "weight": 30, "questionCount": 6 } + ], + "totalQuestions": 20, + "timeLimit": 60 +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `name` | string | 是 | 模板名称 | +| `description` | string | 否 | 模板描述 | +| `dimensions` | array | 是 | 评估维度数组 | +| `dimensions[].name` | string | 是 | 维度名称（如 PROMPT、LLM、IDE） | +| `dimensions[].weight` | number | 是 | 维度权重（百分比） | +| `dimensions[].questionCount` | number | 是 | 该维度题目数量 | +| `totalQuestions` | number | 是 | 总题数 | +| `timeLimit` | number | 否 | 时间限制（分钟） | + +**开始评估会话** + +- **方法**：`POST /api/v1/assessment/sessions` +- **认证**：JWT +- **请求体**： + +```json +{ + "templateId": "uuid-string", + "candidateName": "张三", + "candidateEmail": "zhangsan@example.com" +} +``` + +- **响应**：返回 `sessionId`、首道题目及会话状态。 + +**提交答案** + +- **方法**：`POST /api/v1/assessment/sessions/:sessionId/answers` +- **认证**：JWT +- **请求体**： + +```json +{ + "questionId": "uuid-string", + "answer": "用户提交的答案内容", + "duration": 45 +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `questionId` | string | 是 | 题目 ID | +| `answer` | string | 是 | 答案内容（选择题为选项 ID，简答题为文本） | +| `duration` | number | 否 | 答题耗时（秒） | + +**获取评估结果** + +- **方法**：`GET /api/v1/assessment/sessions/:sessionId/result` +- **认证**：JWT +- **响应**：包含各维度得分、总分、评语及证书信息。 + +**常见错误码** + +| 状态码 | 说明 | +|---|---| +| 400 | 参数校验失败（如模板维度权重之和不等于 100） | +| 401 | 未认证或 Token 过期 | +| 403 | 无权限执行该操作 | +| 404 | 模板或会话不存在 | +| 409 | 会话状态冲突（如重复提交答案） | + +--- + +##### 知识库（Knowledge Base） +知识库支持文档上传、解析、分块与混合检索。 + +**上传文档** + +- **方法**：`POST /api/v1/knowledge-base/upload` +- **认证**：JWT +- **请求**：`multipart/form-data`，字段 `file`（文件二进制流） +- **响应**：返回文档 ID、解析状态及分块数量。 + +**创建知识库** + +- **方法**：`POST /api/v1/knowledge-base` +- **认证**：JWT +- **请求体**： + +```json +{ + "name": "产品文档库", + "description": "产品需求与设计文档", + "chunkSize": 512, + "chunkOverlap": 50 +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `name` | string | 是 | 知识库名称 | +| `description` | string | 否 | 描述 | +| `chunkSize` | number | 否 | 分块大小（默认 512） | +| `chunkOverlap` | number | 否 | 分块重叠（默认 50） | + +**混合检索** + +- **方法**：`POST /api/v1/rag/search` +- **认证**：JWT +- **请求体**： + +```json +{ + "query": "如何配置多租户权限？", + "knowledgeBaseIds": ["uuid-1", "uuid-2"], + "topK": 10, + "useRerank": true +} +``` + +- **响应**：返回检索结果列表，包含文档片段、相似度分数及来源信息。 + +--- + +##### 飞书机器人（Feishu Bot） +飞书集成基于 WebSocket 长连接，支持交互式消息卡片。 + +**绑定飞书机器人** + +- **方法**：`POST /api/v1/feishu/bind` +- **认证**：JWT（需 `feishu:manage` 权限） +- **请求体**： + +```json +{ + "appId": "cli_xxxxxxxx", + "appSecret": "xxxxxxxxxxxxxxxx", + "encryptKey": "optional-encrypt-key" +} +``` + +**Webhook 回调** + +- **方法**：`POST /api/v1/feishu/webhook` +- **认证**：飞书签名校验（`X-Lark-Signature` 请求头） +- **请求体**：飞书事件推送标准格式，包含事件类型、消息内容及用户 Open ID。 + +**发送评估指令** + +- **方法**：`POST /api/v1/feishu/assessment-command` +- **认证**：API Key +- **请求体**： + +```json +{ + "openId": "ou_xxxxxxxx", + "command": "start_assessment", + "templateId": "uuid-string" +} +``` + +--- + +##### 用户管理（User） +**创建用户** + +- **方法**：`POST /api/v1/users` +- **认证**：JWT（需 `user:create` 权限） +- **请求体**： + +```json +{ + "username": "zhangsan", + "password": "password123", + "displayName": "张三", + "role": "USER", + "tenantId": "uuid-string" +} +``` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `username` | string | 是 | 登录用户名（唯一） | +| `password` | string | 是 | 密码（最少 8 位） | +| `displayName` | string | 是 | 显示名称 | +| `role` | enum | 是 | `USER` / `TENANT_ADMIN` / `SUPER_ADMIN` | +| `tenantId` | string | 否 | 租户 ID（超级管理员创建时可选） | + +--- + +#### 接口前缀与版本 +- 所有业务接口统一前缀：`/api/v1` +- 管理端接口：`/api/admin` +- 健康检查：`GET /api/health` + +完整的错误码规范与分页参数约定详见 **API 参考** 章节。 + +### 5.2 内部接口 + +#### 模块间调用架构 +AuraK 后端采用 NestJS 模块化架构，各业务模块通过依赖注入（Dependency Injection）进行内部调用。核心调用链路涉及认证、知识库、评估、飞书集成及外部服务（Elasticsearch、Tika、LibreOffice）等模块。 + +```mermaid +graph LR + subgraph 客户端层 + Web前端 + 飞书机器人 + end + + subgraph 网关与认证层 + AuthController + ApiKeyGuard + JwtAuthGuard + PermissionGuard + end + + subgraph 业务模块层 + KnowledgeBaseService + AssessmentService + ChatService + FeishuService + NoteService + end + + subgraph 基础设施服务层 + ElasticsearchService + TikaService + LibreOfficeService + EmbeddingService + RagService + end + + Web前端 --> AuthController + 飞书机器人 --> FeishuService + AuthController --> JwtAuthGuard + AuthController --> ApiKeyGuard + AuthController --> PermissionGuard + KnowledgeBaseService --> TikaService + KnowledgeBaseService --> ElasticsearchService + KnowledgeBaseService --> EmbeddingService + AssessmentService --> RagService + ChatService --> RagService + ChatService --> ElasticsearchService + FeishuService --> AssessmentService + FeishuService --> ChatService + NoteService --> ElasticsearchService +``` + +#### 认证与授权调用链 +所有内部接口（除标记 `@Public()` 的端点外）均需通过认证与授权检查。调用链如下： + +1. **请求进入**：客户端请求到达对应的 Controller。 +2. **守卫链执行**：NestJS 按顺序执行全局守卫与路由级守卫。 + - `JwtAuthGuard`：校验 `Authorization: Bearer ` 中的 JWT，解析用户身份。 + - `ApiKeyGuard`：校验 `X-API-Key` 请求头，用于服务间调用。 + - `PermissionGuard`：结合 `@Permissions()` 装饰器，校验当前用户是否具备所需权限码。 + - `RolesGuard`：校验用户角色（`SUPER_ADMIN`、`TENANT_ADMIN`、`USER`）。 +3. **租户隔离**：`TenantMiddleware` 解析请求头中的租户标识，写入 `TenantStore`，供数据查询时自动附加租户过滤条件。 +4. **业务处理**：通过认证后，请求进入 Service 层执行具体业务逻辑。 + +#### 服务间调用方式 +模块间通过 NestJS 的 `@InjectRepository()` 或构造函数注入 Service 实例实现调用。典型调用关系如下： + +| 调用方 | 被调用方 | 调用目的 | +|---|---|---| +| `FeishuService` | `AssessmentService` | 处理飞书消息中的评估指令，创建评估会话 | +| `FeishuService` | `ChatService` | 转发飞书消息至 AI 对话 | +| `AssessmentService` | `RagService` | 生成面试追问时检索知识库上下文 | +| `ChatService` | `RagService` | 对话时进行知识库混合检索（BM25 + 向量） | +| `KnowledgeBaseService` | `TikaService` | 文档内容提取（快速处理模式） | +| `KnowledgeBaseService` | `EmbeddingService` | 生成文档块向量用于索引 | +| `KnowledgeBaseService` | `ElasticsearchService` | 写入/查询文档索引 | +| `AssessmentService` | `ExportService` | 导出评估报告（PDF） | +| `ExportService` | `LibreOfficeService` | 将 Markdown 转换为 PDF | + +#### 内部服务调用示例 +##### 飞书机器人调用评估服务 +`FeishuService` 解析飞书消息中的命令（如 `/start_assessment`），通过 `FeishuAssessmentService` 调用 `AssessmentService` 创建评估会话： + +```typescript +// feishu.service.ts（源码结构示意） +@Injectable() +export class FeishuService { + constructor( + private readonly feishuAssessmentService: FeishuAssessmentService, + private readonly chatService: ChatService, + ) {} + + async handleMessage(payload: WebhookDto) { + // 解析消息命令 + const command = this.assessmentCommandParser.parse(payload.text); + if (command.type === 'assessment') { + return this.feishuAssessmentService.handleCommand(command, payload); + } + // 默认转发至 AI 对话 + return this.chatService.sendMessage(payload); + } +} +``` + +##### 知识库处理管道 +`KnowledgeBaseService` 根据文档类型选择处理路径，调用内部服务完成文档解析、分块、向量化与索引： + +```typescript +// knowledge-base.service.ts（源码结构示意） +async processDocument(file: Express.Multer.File, kbId: string) { + // 1. 调用 Tika 提取文本 + const text = await this.tikaService.extractText(file); + // 2. 调用 TextChunkerService 分块 + const chunks = this.textChunkerService.chunk(text, chunkConfig); + // 3. 调用 EmbeddingService 生成向量 + const embeddings = await this.embeddingService.generate(chunks); + // 4. 调用 ElasticsearchService 写入索引 + await this.elasticsearchService.indexDocuments(kbId, chunks, embeddings); +} +``` + +#### 内部接口鉴权机制 +内部服务间调用通过以下机制保障安全： + +| 机制 | 实现方式 | 适用场景 | +|---|---|---| +| **API Key** | `ApiKeyGuard` 校验 `X-API-Key` 请求头，密钥存于 `api_key` 表 | 外部系统或可信服务调用 | +| **JWT** | `JwtAuthGuard` 校验 Bearer Token | 用户登录后的前端请求 | +| **租户隔离** | `TenantMiddleware` + `TenantEntitySubscriber` 自动附加租户条件 | 所有多租户数据访问 | +| **权限码** | `PermissionGuard` + `@Permissions()` 装饰器，共 26 个细粒度权限 | 管理类操作 | + +#### 内部调用流程说明 +1. **同步调用**：大部分模块间调用为同步 HTTP 或进程内方法调用，如 `ChatService` 调用 `RagService` 进行检索。 +2. **异步任务**：耗时操作（如文档导入、PDF 生成）通过 `ImportTaskService` 创建任务记录，由后台异步执行，前端通过轮询任务状态获取结果。 +3. **WebSocket**：飞书机器人通过 `FeishuWsManager` 维护 WebSocket 连接，实现消息的实时推送与接收。 + +> 关于各模块对外暴露的 REST 端点及请求/响应格式，详见“API 参考”章节。 + +### 5.3 数据格式 + +#### 全局约定 +#### 请求与响应格式 +系统采用标准的 **RESTful JSON** 格式进行数据交换。所有 API 请求与响应均使用 `Content-Type: application/json`（文件上传接口除外）。响应体统一封装为以下结构： + +```json +{ + "code": 0, + "data": {}, + "message": "success" +} +``` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `code` | number | 业务状态码，`0` 表示成功，非零表示失败 | +| `data` | object/array | 业务数据负载，可为空对象 | +| `message` | string | 状态描述信息 | + +#### 日期时间格式 +所有时间字段统一采用 **ISO 8601** 标准格式的 UTC 字符串，精确到毫秒： + +```json +{ + "createdAt": "2026-04-23T08:30:00.000Z", + "updatedAt": "2026-04-23T08:30:00.000Z" +} +``` + +前端展示时由客户端根据本地时区进行转换。数据库中以 SQLite 的 `datetime` 类型存储，通过 TypeORM 实体映射为 JavaScript `Date` 对象。 + +#### 枚举与状态码 +系统内部使用字符串枚举表示固定状态集合，主要枚举值如下： + +| 枚举名称 | 取值 | 说明 | +|---|---|---| +| `UserRole` | `SUPER_ADMIN` / `TENANT_ADMIN` / `USER` | 用户角色三级体系 | +| `AssessmentStatus` | `IN_PROGRESS` / `COMPLETED` / `EXPIRED` | 评估会话状态 | +| `QuestionType` | `MULTIPLE_CHOICE` / `SHORT_ANSWER` | 题目类型 | +| `ImportTaskStatus` | `PENDING` / `PROCESSING` / `COMPLETED` / `FAILED` | 导入任务状态 | + +#### 分页格式 +列表类接口统一采用分页参数 `page`（页码，从 1 开始）与 `pageSize`（每页条数）。分页响应结构如下： + +```json +{ + "code": 0, + "data": { + "items": [], + "total": 100, + "page": 1, + "pageSize": 20 + }, + "message": "success" +} +``` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `items` | array | 当前页数据列表 | +| `total` | number | 符合条件的总记录数 | +| `page` | number | 当前页码 | +| `pageSize` | number | 每页条数 | + +#### 文件上传格式 +文件上传接口使用 `multipart/form-data` 格式，支持的文件类型由 `file-support.constants.ts` 定义，涵盖文档、图片、音视频等常见格式。上传响应返回文件元数据： + +```json +{ + "code": 0, + "data": { + "id": "uuid-string", + "filename": "原始文件名.pdf", + "mimeType": "application/pdf", + "size": 1024000, + "url": "/uploads/xxx.pdf" + }, + "message": "success" +} +``` + +#### 流式响应格式 +AI 对话与评估相关接口支持 **SSE（Server-Sent Events）** 流式输出。响应以 `text/event-stream` 格式返回，每个事件包含 `data:` 前缀的 JSON 片段，以空行分隔。事件流结束以 `data: [DONE]` 标记。 + +#### 多租户数据约定 +系统为多租户架构，租户标识通过请求头 `X-Tenant-Id` 传递。所有业务数据表均包含 `tenantId` 字段用于数据隔离，由 `tenant-entity.subscriber.ts` 中的实体订阅器自动注入，业务代码无需手动处理。 + +#### 错误码约定 +业务错误码采用非零整数表示，具体错误码与 HTTP 状态码的映射关系详见 **API 规范** 章节中的「错误处理」子章节。错误响应体中的 `message` 字段支持多语言，由 `i18n` 模块根据请求头 `Accept-Language` 动态返回对应语言文本。 + +## 6. 用户界面 + +### 6.1 布局与导航 + +#### 整体布局结构 +AuraK 前端采用 **React + React Router** 构建，整体布局分为两大区域： + +- **认证区域**：登录页面（`web/src/pages/auth/Login.tsx`），独立于主布局。 +- **工作区区域**：登录后进入，由 `WorkspaceLayout` 组件承载，包含侧栏导航与内容区。 + +工作区布局文件位于 `web/components/layouts/WorkspaceLayout.tsx`（另有 `web/src/components/layouts/WorkspaceLayout.tsx` 副本），采用侧栏（`SidebarRail`）+ 主内容区的经典结构。侧栏提供功能导航入口，主内容区根据路由动态渲染对应视图。 + +#### 路由配置 +路由定义在 `web/App.tsx` 中，采用嵌套路由结构。工作区路由以 `workspace` 为父路径，子路由对应各功能页面： + +| 路由路径 | 页面组件 | 功能 | +|:---------|:---------|:-----| +| `/login` | `Login.tsx` | 用户登录 | +| `/workspace` | `WorkspaceLayout` | 工作区父布局 | +| `/workspace/chat` | `ChatPage.tsx` | AI 对话 | +| `/workspace/knowledge` | `KnowledgePage.tsx` | 知识库管理 | +| `/workspace/notebooks` | `NotebooksPage.tsx` | 笔记本列表 | +| `/workspace/memos` | `MemosPage.tsx` | 备忘录 | +| `/workspace/assessment` | `AssessmentPage.tsx` | 考核评估 | +| `/workspace/assessment-stats` | `AssessmentStatsView.tsx` | 评估统计 | +| `/workspace/question-banks` | `QuestionBankView.tsx` | 题库列表 | +| `/workspace/question-banks/:id` | `QuestionBankDetailView.tsx` | 题库详情 | +| `/workspace/agents` | `AgentsPage.tsx` | AI 智能体 | +| `/workspace/plugins` | `PluginsPage.tsx` | 插件管理 | +| `/workspace/settings` | `SettingsPage.tsx` | 系统设置 | + +> 注：`assessment-stats`、`question-banks` 等路由在 `App.tsx` 中可能以相对路径形式嵌套于 `workspace` 下，具体匹配规则以源码为准。 + +#### 侧栏导航 +侧栏（`SidebarRail.tsx`）提供以下导航入口： + +- **对话**（Chat） +- **知识库**（Knowledge） +- **笔记本**（Notebooks） +- **备忘录**（Memos） +- **考核评估**（Assessment） +- **评估统计**（Assessment Stats） +- **题库管理**（Question Banks） +- **智能体**（Agents） +- **插件**（Plugins） +- **设置**（Settings） + +导航项通过图标 + 文本形式展示，点击后通过 React Router 的 `Link` 或 `useNavigate` 跳转到对应路由。 + +#### 关键视图与导航流程 +##### 考核评估流程 +考核评估是系统的核心功能，导航流程如下： + +1. 用户从侧栏点击 **考核评估**，进入 `/workspace/assessment`。 +2. `AssessmentPage.tsx` 渲染 `AssessmentView.tsx`，展示模板选择列表。 +3. 用户选择模板后点击 **开始评估**，进入答题交互界面。 +4. 答题完成后提交，展示结果与证书。 + +`AssessmentView.tsx` 内部包含多个子视图状态： + +- **答题交互**：选择题（选项按钮 + 确认）、简答题（textarea + 发送）、AI 追问流程。 +- **进度导航**：题序圆点（当前题蓝色、标记题黄色、其他灰色）+ 标记回头按钮。 +- **提交确认**：未答完时弹出确认弹窗。 +- **结果展示**：等级、分数、每题详情、报告。 +- **证书弹窗**：等级、总分、维度得分、题目列表。 +- **历史侧栏**：右侧展示考评历史列表。 + +##### 题库管理流程 +1. 从侧栏点击 **题库管理**，进入 `/workspace/question-banks`。 +2. `QuestionBankView.tsx` 展示题库卡片列表，支持搜索与筛选（全部/已发布/草稿/待审核）。 +3. 点击题库卡片进入 `/workspace/question-banks/:id`，由 `QuestionBankDetailView.tsx` 渲染题库详情。 +4. 详情页支持题目 CRUD、AI 生成、批量审核、提交审核（DRAFT→PENDING_REVIEW）、发布（PENDING_REVIEW→PUBLISHED）等操作。 + +##### 设置页面 +`/workspace/settings` 由 `SettingsPage.tsx` 渲染，内部通过 Tab 切换不同设置模块，其中 **测评模板**（Tab: `assessment_templates`）由 `AssessmentTemplateManager.tsx` 实现，支持模板 CRUD、维度配置（添加/删除/权重）及 P2 配置（attemptLimit/reviewMode/shuffleQuestions/预约时段）。 + +#### 布局组件与权限控制 +工作区布局中，部分导航项受权限控制。`PermissionGate.tsx` 组件用于根据用户权限决定是否渲染特定导航入口或页面内容。权限逻辑基于 `usePermissions` Hook（`web/src/hooks/usePermissions.ts`），权限定义见 `server/src/auth/permission/permission.constants.ts`。 + +#### 相关章节 +- 各视图的具体交互细节与数据流，参见 **功能模块** 章节。 +- 权限控制机制详见 **权限模型** 章节。 + +### 6.2 组件 + +#### 通用交互组件 +前端 UI 层基于 React 19 + TypeScript + Vite 构建，`web/components/` 目录下集中存放可复用组件。按功能可划分为以下几组： + +**对话框与弹窗类** + +| 组件文件 | 功能说明 | +|---------|---------| +| `ConfirmDialog.tsx` | 通用确认对话框，配合 `contexts/ConfirmContext.tsx` 全局调用 | +| `CreateNoteFromPDFDialog.tsx` | 从 PDF 创建笔记的对话框 | +| `CreateNotebookDialog.tsx` / `EditNotebookDialog.tsx` | 笔记本的创建与编辑对话框 | +| `SettingsModal.tsx` / `IndexingModal.tsx` | 设置与索引进度弹窗 | +| `AICommandModal.tsx` | AI 指令输入弹窗 | + +**抽屉类（Drawer）** + +| 组件文件 | 功能说明 | +|---------|---------| +| `AICommandDrawer.tsx` | AI 指令侧边抽屉 | +| `ChunkInfoDrawer.tsx` | 知识库分块信息展示抽屉 | +| `CreateNotebookDrawer.tsx` / `EditNotebookDrawer.tsx` | 笔记本创建/编辑抽屉 | +| `GroupSelectionDrawer.tsx` | 知识分组选择抽屉 | +| `HistoryDrawer.tsx` | 对话历史记录抽屉 | +| `ImportFolderDrawer.tsx` | 文件夹导入抽屉 | +| `InputDrawer.tsx` | 通用输入抽屉 | +| `SettingsDrawer.tsx` | 设置抽屉 | +| `SourcePreviewDrawer.tsx` | 来源预览抽屉 | +| `drawers/ImportTasksDrawer.tsx` | 导入任务列表抽屉 | + +**上传与拖拽类** + +- `DragDropUpload.tsx` — 通用拖拽上传组件 +- `NotebookDragDropUpload.tsx` — 笔记本场景专用拖拽上传 +- `GlobalDragDropOverlay.tsx` / `NotebookGlobalDragDropOverlay.tsx` — 全局拖拽覆盖层 + +**选择器与展示类** + +- `GroupSelector.tsx` / `GroupManager.tsx` — 知识分组选择与管理 +- `ModeSelector.tsx` — 模式切换器 +- `VisionModelSelector.tsx` — 视觉模型选择器 +- `FileGroupTags.tsx` — 文件分组标签 +- `SearchResultsPanel.tsx` / `SearchHistoryList.tsx` — 搜索结果与历史列表 +- `PDFPreview.tsx` / `PDFSelectionTool.tsx` — PDF 预览与选区工具 +- `UserInfoDisplay.tsx` — 用户信息展示 +- `Logo.tsx` — 品牌 Logo + +#### 聊天与 AI 相关组件 +- `ChatInterface.tsx` — 聊天主界面，承载消息渲染与输入交互 +- `ChatMessage.tsx` — 单条聊天消息组件，支持 Markdown 与流式渲染 +- `ConfigPanel.tsx` — AI 配置面板 + +#### 权限控制组件 +- `PermissionGate.tsx` — 基于权限的渲染门控组件，配合 `contexts/AuthContext.tsx` 与 `hooks/usePermissions.ts` 使用，控制按钮或区块的可见性。 + +#### 布局组件 +`web/components/layouts/` 下提供： + +- `WorkspaceLayout.tsx` — 工作区整体布局（同时存在于 `web/src/components/layouts/`） +- `SidebarRail.tsx` — 侧边栏轨道 +- `AdminLayout.tsx` — 管理后台布局 + +#### 基础 UI 组件 +`web/src/components/ui/` 提供原子级基础组件： + +- `button.tsx` — 按钮 +- `card.tsx` — 卡片容器 +- `select.tsx` — 下拉选择器 + +#### 视图组件 +`web/components/views/` 下为业务视图级组件，代表完整功能页面： + +| 组件文件 | 对应功能 | +|---------|---------| +| `AssessmentView.tsx` | 考核评估主界面（含历史记录侧栏） | +| `AssessmentStatsView.tsx` | 评估统计面板（雷达图/趋势图） | +| `AssessmentTemplateManager.tsx` | 测评模板管理 | +| `QuestionBankView.tsx` / `QuestionBankDetailView.tsx` | 题库列表与详情 | +| `KnowledgeBaseView.tsx` | 知识库管理 | +| `ChatView.tsx` | 对话视图 | +| `NotebooksView.tsx` / `NotebookDetailView.tsx` | 笔记本列表与详情 | +| `MemosView.tsx` | 备忘录视图 | +| `PermissionSettingsView.tsx` | 权限设置矩阵 | +| `SettingsView.tsx` | 系统设置 | +| `PluginsView.tsx` | 插件管理 | + +#### 上下文与工具 +`web/contexts/` 提供全局状态： + +- `AuthContext.tsx` — 认证状态 +- `ConfirmContext.tsx` — 确认对话框上下文 +- `LanguageContext.tsx` — 国际化语言上下文 +- `ToastContext.tsx` — 轻提示上下文 + +`web/utils/` 提供工具函数：`clipboard.ts`（剪贴板）、`fileUtils.ts`（文件处理）、`translations.ts`（翻译映射）、`uuid.ts`（ID 生成）。 + +#### 组件间关系说明 +考核评估模块是组件交互最复杂的场景：`AssessmentView.tsx` 作为主容器，内部协调 `ChatInterface` 渲染对话流、`HistoryDrawer` 展示历史记录、`ConfirmDialog` 处理操作确认，并通过 `services/assessmentService.ts` 与后端 LangGraph 状态机通信。题库管理则由 `QuestionBankView` 与 `QuestionBankDetailView` 两级视图构成，详情视图内嵌题目审核与批量操作面板。 + +> 关于视图组件对应的后端 API 与数据模型，详见「API 参考」与「数据模型」章节。 + +### 6.3 状态管理 + +#### 状态管理架构概览 +AuraK 前端采用 **React Context** 作为全局状态管理方案，未引入 Redux、Zustand 等第三方状态库。所有全局状态均通过 Context Provider 在组件树顶层注入，配合自定义 Hooks 实现状态访问与更新。 + +#### 认证状态（AuthContext） +认证状态由 `web/src/contexts/AuthContext.tsx` 管理，负责用户登录态、令牌存储与权限信息的全局维护。 + +**核心职责：** + +- 维护当前登录用户信息（用户名、显示名、角色等） +- 管理 JWT 令牌与 API Key 的存储（localStorage） +- 提供登录、登出、令牌刷新等操作 +- 在应用初始化时恢复会话状态 + +**使用方式：** + +```tsx +// 在组件中访问认证状态 +const { user, isAuthenticated, login, logout } = useAuth(); +``` + +认证流程为：密码登录 → 签发 JWT → 获取 API Key（存 localStorage）→ 后续请求通过 `x-api-key` 头携带，`x-tenant-id` 头指定租户上下文。 + +#### 语言状态（LanguageContext） +语言状态由 `web/contexts/LanguageContext.tsx` 管理，负责多语言界面的切换与翻译文本的提供。 + +**核心职责：** + +- 维护当前语言（中文 / 英文 / 日文） +- 提供翻译函数，根据 key 返回对应语言的文本 +- 语言切换时触发组件重新渲染 + +翻译文本定义在 `web/utils/translations.ts` 中，包含导航、按钮、提示等 UI 文案。例如： + +```ts +// translations.ts 中的部分翻译 key +navAgent: "智能体", +navAssessment: "评测", +navPlugin: "插件", +switchLanguage: "切换语言", +``` + +#### 提示与确认状态（ToastContext / ConfirmContext） +这两个 Context 提供全局 UI 反馈能力： + +- **ToastContext**（`web/contexts/ToastContext.tsx`）：全局消息提示，用于操作成功、失败等轻量反馈。 +- **ConfirmContext**（`web/contexts/ConfirmContext.tsx`）：全局确认对话框，用于需要用户确认的破坏性操作（如删除）。 + +**使用示例：** + +```tsx +const { showToast } = useToast(); +const { confirm } = useConfirm(); + +// 触发提示 +showToast('保存成功', 'success'); + +// 弹出确认框 +await confirm('确定要删除该用户吗？'); +``` + +#### 权限状态（usePermissions Hook） +权限判断逻辑封装在 `web/src/hooks/usePermissions.ts` 中，基于当前用户的角色与权限集合提供细粒度的访问控制。 + +**核心能力：** + +- 检查当前用户是否拥有指定权限 key（如 `user:view`、`kb:edit`） +- 支持组件级别的权限门控渲染 + +权限门控组件 `PermissionGate`（`web/components/PermissionGate.tsx`）基于该 Hook 实现，用于条件渲染受权限保护的 UI 元素。 + +#### 服务层状态（Services） +各业务模块的状态通过 `web/services/` 目录下的服务模块管理，这些模块封装了 API 调用逻辑，并在组件内部通过 `useState` / `useEffect` 维护局部状态。主要服务包括： + +| 服务模块 | 职责 | +|---|---| +| `authService.ts` | 登录、登出、令牌管理 | +| `userService.ts` | 用户 CRUD 操作 | +| `knowledgeBaseService.ts` | 知识库管理 | +| `assessmentService.ts` | 考核流程管理 | +| `questionBankService.ts` | 题库管理 | +| `chatService.ts` | 对话与流式响应 | + +#### 租户上下文（服务端） +服务端通过 `server/src/tenant/tenant.store.ts` 维护租户上下文，前端请求通过 `x-tenant-id` 头传递租户标识，服务端中间件（`tenant.middleware.ts`）解析并注入当前租户上下文，实现多租户数据隔离。该机制在“多租户架构”章节中有详细说明。 + +#### 状态管理选型说明 +项目选择 React Context 而非 Redux 等外部状态库，主要基于以下考量： + +- 应用状态规模适中，Context 足以覆盖全局共享状态需求 +- 减少依赖体积，保持轻量化 +- 与 React 19 的并发特性天然兼容 + +对于组件内部的复杂状态（如表单、列表筛选），使用 React 内置的 `useState` / `useReducer` 管理，不提升至全局 Context，以降低不必要的重渲染开销。 + +## 7. 安全设计 + +### 7.1 认证与授权 + +#### 认证机制总览 +AuraK 采用 **JWT + API Key 双机制** 进行身份认证。系统默认使用 JWT（JSON Web Token）作为主要认证方式，同时为服务间通信提供 API Key 认证通道。认证模块位于 `server/src/auth/` 目录下，基于 NestJS Passport 策略实现。 + +#### JWT 认证流程 +JWT 认证基于 Passport 的 `local` 与 `jwt` 策略组合实现： + +1. **登录**：用户通过 `POST /auth/login` 提交用户名与密码，`local.strategy.ts` 验证凭据。 +2. **签发令牌**：认证成功后，`auth.service.ts` 签发 JWT 令牌并返回给客户端。 +3. **请求携带**：客户端在后续请求的 `Authorization: Bearer ` 头中携带令牌。 +4. **令牌验证**：`jwt.strategy.ts` 解析并验证令牌签名与有效期，将用户信息挂载到请求对象。 + +相关守卫（Guard）包括： + +| 守卫 | 职责 | +|---|---| +| `local-auth.guard.ts` | 登录接口的本地认证守卫 | +| `jwt-auth.guard.ts` | 验证 JWT 令牌有效性 | +| `combined-auth.guard.ts` | 全局认证守卫，同时支持 JWT 与 API Key | +| `public.decorator.ts` | 标记公开接口，跳过认证 | + +#### API Key 认证 +除 JWT 外，系统通过 `api-key.guard.ts` 支持 API Key 认证。API Key 实体定义于 `server/src/auth/entities/api-key.entity.ts`，适用于服务间调用或自动化脚本场景。`combined-auth.guard.ts` 会优先尝试 JWT，若不存在则回退到 API Key 校验。 + +#### 角色体系 +系统内置三级角色，定义于 `server/src/user/user-role.enum.ts`： + +| 角色 | 权限数 | 核心能力 | +|---|---|---| +| **SUPER_ADMIN** | 26 项 | 全部权限：用户/租户/知识库/考核/模型/设置 | +| **TENANT_ADMIN** | 21 项 | 本租户管理：用户/知识库/考核/模型；不能跨租户、删用户、改系统设置 | +| **USER** | 5 项 | 使用知识库、参与考核、查看插件 | + +角色实体（`role.entity.ts`）包含 `isSystem` 标记，系统角色受保护不可删改；`baseRole` 字段映射到 `UserRole` 枚举；`tenantId` 为 `null` 表示全局角色，非 `null` 则为租户自定义角色。 + +#### 权限模型（RBAC） +权限定义位于 `server/src/auth/permission/permission.constants.ts`，共 26 项细粒度权限，按分类组织： + +| 分类 | 权限 | +|---|---| +| 用户管理 | `user:view` / `user:create` / `user:edit` / `user:delete` / `user:role` / `user:password` | +| 租户管理 | `tenant:view` / `tenant:create` / `tenant:edit` / `tenant:delete` / `tenant:members` | +| 知识库 | `kb:view` / `kb:create` / `kb:edit` / `kb:delete` / `kb:publish` | +| 考核 | `assess:view` / `assess:manage` / `assess:template` / `assess:bank` | +| 模型 | `model:view` / `model:config` | +| 插件 | `plugin:view` / `plugin:manage` | +| 设置 | `settings:view` / `settings:system` | + +角色与权限通过 `role-permission.entity.ts` 关联表建立多对多关系。 + +#### 权限检查机制 +权限检查通过装饰器与守卫组合实现： + +```typescript +// 控制器示例 +@UseGuards(PermissionGuard) +@Permission('kb:create') +@Post() +create() { /* ... */ } +``` + +核心组件： + +- `permission.decorator.ts` — `@Permission()` 装饰器，声明所需权限 +- `permission.guard.ts` — 校验当前用户是否具备所需权限 +- `roles.decorator.ts` — `@Roles()` 装饰器，声明所需角色 +- `roles.guard.ts` — 校验当前用户角色 +- `super-admin.guard.ts` / `tenant-admin.guard.ts` — 针对特定角色的专用守卫 + +前端通过 `PermissionGate.tsx` 组件与 `usePermissions.ts` Hook 实现组件级权限门控，与后端权限定义保持一致。 + +#### 多租户数据隔离 +系统通过 `tenant.middleware.ts` 与 `tenant-entity.subscriber.ts` 实现租户级数据隔离。请求经过中间件时解析当前租户上下文，实体订阅器在数据库操作时自动附加租户过滤条件，确保租户间数据不可互访。租户成员关系定义于 `tenant-member.entity.ts`。 + +#### 安全说明 +- JWT 密钥通过环境变量 `JWT_SECRET` 配置（见 README 快速开始章节）。 +- 代码审查记录指出 `knowledge-base.service.ts` 中存在动态引入 `jsonwebtoken` 的用法（第 1676-1685 行），建议统一通过 NestJS `JwtService` 管理令牌操作。 +- 系统角色（SUPER_ADMIN、TENANT_ADMIN、USER）的权限不可修改，自定义角色可灵活配置权限矩阵。 + +> 相关 API 端点与请求/响应格式详见「API 参考」章节；用户 CRUD 与角色分配操作详见「用户管理」章节。 + +### 7.2 传输安全 + +#### 传输层加密（TLS/HTTPS） +AuraK 的传输安全由 Nginx 反向代理层统一承载。源码中 `nginx/nginx.conf` 与 `nginx/conf.d/` 目录下的配置文件定义了 HTTPS 的启用方式与证书管理策略。 + +##### 证书配置 +Nginx 配置引用了位于 `nginx/conf.d/ssl/` 目录下的证书文件： + +- **证书文件**：`cert.pem` +- **私钥文件**：`key.pem` + +证书的生成由 `nginx/generate-ssl.sh` 脚本完成。该脚本用于生成自签名 SSL 证书，适用于开发环境或内网部署场景。生产环境部署时，应将自签名证书替换为由受信任的证书颁发机构（CA）签发的正式证书。 + +##### HTTPS 强制与重定向 +Nginx 配置中实现了 HTTP 到 HTTPS 的强制跳转，确保所有客户端请求均通过加密通道传输。该机制有效防御以下攻击： + +- **中间人攻击（MITM）**：通过 TLS 加密，防止攻击者在客户端与服务器之间窃听或篡改传输中的数据。 +- **降级攻击**：强制使用 HTTPS，阻止攻击者将通信协议从 HTTPS 降级为明文 HTTP，从而规避加密保护。 + +##### 安全响应头 +Nginx 配置中设置了多项安全响应头，以增强浏览器端的安全防护。具体配置项在源码中未完整列出，但根据 Nginx 配置文件的常规实践，通常包含以下内容（源码中未提供完整清单，以下为基于配置文件的推断）： + +| 响应头 | 作用 | 防御的攻击类型 | +|---|---|---| +| `X-Content-Type-Options: nosniff` | 禁止浏览器对响应内容进行 MIME 类型嗅探 | 内容嗅探攻击、MIME 混淆攻击 | +| `X-Frame-Options` | 控制页面是否允许被嵌入到 `