petrezhu/ARK

Fork 0

[SPEC] ARK MVP - 知识方舟跃迁游戏化学习引擎 #1

New issue

Closed

opened 2026-09-01 16:45:38 +08:00 by petrezhu · 0 comments

petrezhu commented

2026-09-01 16:45:38 +08:00

Owner

ARK MVP — 知识方舟跃迁（软考架构师游戏化学习引擎）

Problem Statement

老己正在备考2026年11月2日的软考系统架构设计师考试（剩余约60天，每天4-6小时）。现有的学习方式（看希赛视频 + Obsidian记笔记 + senior-software-architect-review仓库的私教Agent）功能完备但缺乏动力和节奏感。

"氛围编程"的核心体验——可视化反馈、创造乐趣、沉浸心流——在纯CLI/文本的学习工具中缺失。需要一个游戏化前端层包裹现有知识仓库，将学习过程转化为太空建造游戏：学一个知识点 = 开采一颗星球的矿石 = 为飞船装配一个零件。

核心矛盾：考试时间紧迫（60天），但开发这个工具本身不能挤占学习时间。因此采用"AI开发MVP，用户驱动迭代"策略，7天内交付可用版本。

Solution

构建 ARK（知识方舟跃迁）—— 一个包裹 senior-software-architect-review 仓库的游戏化Web应用。

玩家作为"方舟总工程师"，在太空星图上勘探星域（知识大类）、扫描矿点（考点，2分钟概览，阅后即焚）、自学后提交手打笔记、AI模糊校验覆盖完整度、开采完成获得零件装配到飞船。虚空蛀虫（记忆遗忘）持续侵蚀已装配组件，需要定期巡检维修。距离考试的每一天都是"跃迁倒计时"。

技术栈：Python FastAPI + SQLite 后端，Vanilla HTML/CSS/JS + D3.js + Cytoscape.js 前端，部署到 g.petrezhu.cn。

User Stories

作为方舟总工程师，我想打开ARK就看到"舰桥日报"（昨日战果+今日任务+侵蚀预警+聚能斗领取），以便每天学习有明确起点
作为方舟总工程师，我想在星图上看到22个程序化生成的形态各异的星球（每个星球有独特的颜色、地形纹理、晨昏线、大气光晕），以便我对探索产生好奇心
作为方舟总工程师，我想点击一个未勘探的星域看到"未知信号"变为完整星球（勘探解锁动画），以便获得探索发现的快感
作为方舟总工程师，我想浏览一个矿点的2分钟知识概览（AI从cheatsheets压缩生成），以便快速判断这个考点的内容和难度
作为方舟总工程师，我想在看完概览后它自动标记为"已焚"（阅后即焚机制），以便获得"已扫描过这片区域"的进度感
作为方舟总工程师，我想重新扫描已焚的概览时消耗少量燃料，以便有轻度的资源管理挑战但不被阻碍学习
作为方舟总工程师，我想自行学习（看希赛视频/读教材/任何方式）后，在ARK中粘贴我手打的笔记
作为方舟总工程师，我想提交笔记后AI批量校验它对当前矿点mandatory要素的覆盖完整度（模糊语义匹配，非关键词匹配），以便知道还需要补充什么
作为方舟总工程师，我想在校验失败时先看到"你已覆盖的要素✓"（回显我的笔记要点）再看到缺失要素，以便先获得成就感再看到差距
作为方舟总工程师，我想在校验失败时请求AI的2分钟微讲解（消耗10燃料），以便获得定向的补全指引
作为方舟总工程师，我想在笔记校验通过时看到"开采仪式感"页面（矿石→零件分解图+自己的笔记要点逐条回显✓+燃料飘字+星球光晕脉冲+飞船组件槽位从虚线变实线），以便获得最高浓度的正反馈
作为方舟总工程师，我想在开采完成时有5%概率触发"稀有矿脉"双倍奖励（考频≥12且跨科值≥0.8的考点标记为金色稀有矿脉），以便游戏机制直接服务考试策略
作为方舟总工程师，我想在星图上看到已勘探星域的星球光晕强度随开采完成度增长，以便宏观进度一目了然
作为方舟总工程师，我想在飞船视图中看到方舟的剪影式外观（船头机翼=导航系统/船身货舱=载荷系统/尾部引擎=反应堆），以便获得"我在建造一艘飞船"的具象成就感
作为方舟总工程师，我想看到已装配的零件点亮飞船对应槽位、受损组件显示腐蚀蒙版（暗丝纹理），以便直观感知知识掌握状态
作为方舟总工程师，我想每天首次登录时领取聚能斗燃料（45-60随机×连击系数），以便有每日仪式感
作为方舟总工程师，我想看到连续登录天数和连击系数（3天×1.1/7天×1.25/14天×1.5），以便维持每日打开的习惯
作为方舟总工程师，我想在顶部栏始终看到"距离基点跃迁 N 天"的DSEG7字体倒计时，以便对真实考试时间有具象感知
作为方舟总工程师，我想在倒计时≤30天时数字转琥珀色、≤14天转红并轻微脉动，以便在不被催促的前提下自然感受到紧迫
作为方舟总工程师，我想点击倒计时时看到AI对"以当前航速，跃迁窗口预计达成度X%"的评估（每日刷新一次），以便了解自己的备考是否在正轨上
作为方舟总工程师，我想在压力测试（从exam-bank出题）完成后获得5-15随机燃料（按正确率浮动），以便测试本身成为资源获取途径
作为方舟总工程师，我想在巡检时看到所有组件的耐久度仪表盘弧线（复用svg-gauge模式，低于30%转红），以便快速识别需要维修的知识点
作为方舟总工程师，我想在维修受损组件时选择主动回忆（免费）、求AI提示（10燃料）、直接复原（15燃料），以便根据自己的状态选择复习策略
作为方舟总工程师，我想在虚空中看到蛀虫侵蚀的威胁可视化（受损组件暗丝纹理+仪表盘红色），以便对"遗忘"有具象感知而非抽象数字
作为方舟总工程师，我想打开ARK时看到"每日航海日志"（昨夜电报：昨日战果+今夜侵蚀预警+轮换舰长语录），以便每天都有新内容锚定"船在航行"的世界观
作为方舟总工程师，我想在"史官"视图中看到成就徽章墙（20-30枚，获得的发光，未获得的剪影），以便有长线收集目标
作为方舟总工程师，我想在获得成就时顶部栏图标亮起+一条日志（不弹窗打断），以便保持心流不被中断
作为方舟总工程师，我想看到背景星云（3团3-5%透明度径向渐变斑块），以便星图不再是纯黑死寂
作为方舟总工程师，我想在三个仪表盘式导航按钮（星图/飞船/测试）之间切换视图，每个按钮本身显示对应维度的进度环，以便导航本身也在展示进度
作为方舟总工程师，我想在NPC对话面板中向遗迹向导提问（启发式，不直接给答案），以便在困惑时获得引导而非答案
作为方舟总工程师，我想在NPC对话面板中向材料检验官查询笔记覆盖度、向测试官获取测试题、向史官查看进度报告，以便每个NPC有明确分工
作为方舟总工程师，我想让ARK读取我的Obsidian笔记自动预填已学过的矿点进度，以便第一天打开就看到"已建造了一部分的飞船"
作为方舟总工程师，我想在ARK中提交笔记时可选"同步到Obsidian"，以便笔记在两边都能看到
作为方舟总工程师，我想在星图上看到稀有矿脉（金色光点）与普通矿点（蓝白色）的视觉区分，以便优先关注高价值考点
作为方舟总工程师，我想在首次打开ARK（Obsidian预填后）看到已装配组件按序点亮的"觉醒序列"（约10s），以便获得"方舟正在苏醒"的首印象
作为方舟总工程师，我想在完成完整模考时将其视为"跃迁模拟"，三科全过线时播放模拟跃迁成功动画，以便模考有仪式感
作为方舟总工程师，我想看到燃料仓的液面可视化（反应堆发光液位随燃料增减变化），以便燃料不只是数字
作为方舟总工程师，我想在ARK中看到我的笔记要点以Obsidian兼容Markdown格式回显，以便确认AI理解了我的笔记内容
作为方舟总工程师，我想看到矿点的难度标识（来自curriculum.json的difficulty字段），以便自行选择匹配当前状态的挑战
作为方舟总工程师，我想在ARK中使用键盘快捷键（如领取聚能斗、开始巡检），以便提高高频操作效率

Implementation Decisions

测试接缝（Testing Seam）

主接缝：REST API 层。所有游戏逻辑通过 /api/* 端点暴露，前端仅消费API。测试策略：

后端逻辑可以脱离FastAPI独立测试（纯Python函数）
API层通过 httpx/TestClient 测试端到端行为
前端不包含业务逻辑（文档v1.1红线：视图层禁止把业务逻辑写在前端）

理想测试数量：1个主接缝（API层），辅以后端纯函数单元测试。

模块划分

模块	职责	对外接口
`golden_kg`	读取senior-software-architect-review仓库，拆分矿点，提供只读知识图谱	`get_sectors()`, `get_ores(sector_id)`, `get_overview(ore_id)`
`ark_state`	SQLite读写方舟状态（玩家/星图/飞船/蛀虫/燃料/成就）	`get_state()`, `update_state(patch)`
`fuel_economy`	变量奖励计算、连击系数、燃料收支	`calc_daily_collect(streak)`, `calc_mining_reward(ore_id, rare)`, `calc_test_reward(score)`
`borer_engine`	SM-2改良侵蚀计时、耐久衰减、维修恢复	`check_erosion()`, `repair(component_id, method)`
`note_validator`	AI模糊匹配笔记与mandatory要素，返回覆盖度报告	`validate(notes_text, ore_id) -> CoverageReport`
`overview_generator`	从cheatsheets压缩生成2分钟概览，缓存	`generate(ore_id) -> markdown`
`npc_engine`	6个NPC角色的prompt管理+LLM调用+输出约束	`chat(npc_role, message, context) -> response`
`achievement_engine`	成就条件判定、徽章状态管理	`check_achievements(state) -> new_badges[]`
`obsidian_sync`	扫描Obsidian Vault、AI匹配笔记到矿点、双向同步	`scan_vault()`, `sync_to_obsidian(note, ore_id)`
`planet_gen`	程序化星球参数生成（种子哈希→半径/颜色/噪声/环/大气）	`generate(sector_id) -> PlanetParams`
`daily_briefing`	每日航海日志模板生成、舰长语录轮换	`generate(player_state) -> Briefing`

API 端点设计

GET  /api/briefing                 → 每日航海日志（首次打开时调用）
GET  /api/star-map                 → 星图数据（Cytoscape elements格式，含planet_params）
GET  /api/ship                     → 飞船状态（D3数据，含durability/erosion）
GET  /api/sector/{id}              → 星域详情+矿点列表
GET  /api/ore/{id}/overview        → 矿点概览（2分钟，阅后即焚标记）
POST /api/ore/{id}/scan            → 标记已扫描（阅后即焚，消耗燃料若重扫）
POST /api/notes/validate           → 批量笔记校验（返回CoverageReport）
POST /api/notes/validate/explain   → 请求AI微讲解（消耗10燃料）
POST /api/notes/validate/accept    → 接受校验结果，开采完成（触发奖励+装配）
POST /api/test/start               → 开始压力测试（从exam-bank出题）
POST /api/test/submit              → 提交测试答案（返回判分+燃料奖励）
POST /api/fuel/collect             → 每日聚能斗领取（含连击系数）
POST /api/repair/{component_id}    → 维修组件（method: recall/hint/restore）
GET  /api/npc/{role}/chat          → NPC对话
GET  /api/achievements             → 成就徽章列表
GET  /api/countdown                → 跃迁倒计时+每日评估
POST /api/sync/obsidian            → 触发Obsidian同步

数据层决策

Golden KG 直接读取 senior-software-architect-review/ 目录（curriculum.json + cheatsheets/ + exam-bank/ + knowledge-index/），不做数据迁移
Ark State 用 SQLite（WAL模式），fuel_log append-only，每日自动备份
矿点拆分：每个K主题按raw_tags拆3-8个矿点，矿点id格式 {topic_id}#{序号}
稀有矿脉：frequency_count ≥ 12 && cross_subject_value ≥ 0.8 的矿点标记 rare: true
概览缓存：首次生成后存SQLite，永久复用

程序化星球生成

用 sector_id 哈希作为种子，Simplex noise生成地形纹理，SVG渲染：

噪声地形着色（2-4色色带）
固定45°光源的晨昏线+大气边缘光
30%概率星环（虚线dash椭圆碎带）
进度映射：glow_intensity = 开采完成度

燃料经济数值

获取	数量	条件
每日聚能斗	45-60随机 × 连击系数	每日首次，连续3/7/14天×1.1/1.25/1.5
开采完成	7-13随机	笔记校验通过
稀有矿脉	开采×2	5%概率（考频≥12且跨科≥0.8）
压力测试	5-15	按正确率浮动

消耗	数量	说明
重读已焚概览	5/次	阅后已焚再次扫描
求AI提示	10/次	校验失败时微讲解
复原遗忘内容	15/次	直接恢复耐久

设计约束：每日净收益 > 消耗，燃料为0仍可学习。

前端视图结构

┌───────────────────────────────────────────────┐
│ 顶部栏: [聚能斗] | 燃料数 | DSEG7倒计时 | [星图][飞船][测试]仪表盘导航 │
├────────────────────┬──────────────────────────┤
│                    │                          │
│   星图/飞船主视图   │   主内容区               │
│   (Cytoscape/D3)   │   (矿点概览/笔记提交/    │
│                    │    测试/NPC对话/维修)     │
│                    │                          │
├────────────────────┴──────────────────────────┤
│ 底部栏: 三系统进度条 [导航████░░][载荷██░░░░][反应堆██░░] │
└───────────────────────────────────────────────┘

首次打开 → 舰桥日报（briefing面板）
星图视图 → Cytoscape全景，节点=星球，连线=知识依赖
飞船视图 → D3剪影装配图
学习视图 → 矿点概览+笔记提交+校验结果
测试视图 → 答题界面
NPC视图 → 对话面板
进度视图 → 统计图表+成就墙

视觉规范

风格：写实太空（深空#0a0e1a背景，星球纹理，能量连线）
字体：DSEG7（jsdelivr CDN）用于仪表数字，系统字体用于正文
星云背景：3团3-5%透明度径向渐变SVG
状态变化：仅允许一次性CSS transition（scale/opacity/glow），无循环动画
耐久仪表盘：svg-gauge弧线，<30%转红
开采仪式：矿石→零件分解图 + 笔记要点回显✓ + 燃料飘字 + 星球脉冲 + 组件实线

Obsidian双向同步

读取方向：ARK启动时扫描Obsidian Vault软考目录，AI匹配笔记到矿点，预填进度
写入方向：用户在ARK提交笔记时可选"同步到Obsidian"，格式化为Markdown写入
冲突处理：以Obsidian版本为主，ARK仅在用户触发时写入

Testing Decisions

测试原则

只测外部行为（API输入→输出），不测实现细节
每个测试用例独立（不依赖其他用例的副作用）
状态变更通过API验证，不直接查数据库

测试模块

模块	测试类型	说明
`golden_kg`	单元测试	矿点拆分正确性、概览生成、稀有矿脉标记
`fuel_economy`	单元测试	变量奖励范围、连击系数、收支平衡
`borer_engine`	单元测试	侵蚀计时、耐久衰减、维修恢复
`note_validator`	集成测试	笔记→覆盖度报告（需mock LLM）
`achievement_engine`	单元测试	成就条件判定
`daily_briefing`	单元测试	模板生成、语录轮换
API层	E2E测试	完整学习循环（勘探→扫描→笔记→校验→开采→装配）

测试先例

参考 senior-software-architect-review/tutor/ 中的进度协议测试模式：append-only事件日志、幂等性验证、状态重建。

Out of Scope

精细动画/音效：不开发循环动画、粒子系统、音效。仅允许一次性CSS transition。
Three.js 3D模式：保留设计接口，暂不开发。
多用户支持：单用户架构，SQLite。
移动端适配：MVP仅桌面端。后续可加响应式。
论文写作系统：论文燃料仓仅做进度展示，不实现完整论文写作流程。
领域复用：MVP仅软考架构师，不做领域无关抽象。
自动题库扩充：禁止AI自动扩充考点，所有矿点需人工确认。
考前3天策略切换：考前3天自动停止低频新课、只看保命卡——作为后续迭代。

Further Notes

开发节奏（7天MVP）

Day 1-2：基础框架（FastAPI + SQLite + golden_kg读取 + 矿点拆分）
Day 2-3：星图+飞船（Cytoscape + D3 + 程序化星球 + 进度映射）
Day 3-4：学习核心（概览生成 + 阅后即焚 + 笔记校验 + 开采仪式）
Day 4-5：游戏系统（燃料经济 + 聚能斗 + 蛀虫侵蚀 + 压力测试）
Day 5-6：NPC+同步（LLM对话 + Obsidian同步 + 进度报告）
Day 6：游戏性增强包（变量奖励+连击+稀有矿脉+航海日志+成就+倒计时）
Day 6-7：部署打磨（Nginx + systemd + g.petrezhu.cn）

与现有仓库的关系

ARK是"壳"，senior-software-architect-review是"核"。不重新实现知识图谱和进度管理。ARK读取现有仓库的curriculum.json、cheatsheets、exam-bank、knowledge-index，适配其数据格式。

设计文档

完整设计见 /root/git/ARK/docs/DESIGN.md（v2.1），领域词汇表见 docs/CONTEXT.md，架构决策见 docs/adr/。

关键设计约束

鼓励式学习：燃料是轻度挑战，不是硬瓶颈
所有LLM输出基于Golden KG，禁止生成图谱外知识点
Obsidian笔记以用户版本为主
单次前端开发 ≤30分钟，每日累计 ≤45分钟
视图层禁止包含业务逻辑

# ARK MVP — 知识方舟跃迁（软考架构师游戏化学习引擎） ## Problem Statement 老己正在备考2026年11月2日的软考系统架构设计师考试（剩余约60天，每天4-6小时）。现有的学习方式（看希赛视频 + Obsidian记笔记 + senior-software-architect-review仓库的私教Agent）功能完备但缺乏**动力和节奏感**。 "氛围编程"的核心体验——可视化反馈、创造乐趣、沉浸心流——在纯CLI/文本的学习工具中缺失。需要一个游戏化前端层包裹现有知识仓库，将学习过程转化为太空建造游戏：学一个知识点 = 开采一颗星球的矿石 = 为飞船装配一个零件。核心矛盾：**考试时间紧迫（60天），但开发这个工具本身不能挤占学习时间**。因此采用"AI开发MVP，用户驱动迭代"策略，7天内交付可用版本。 ## Solution 构建 ARK（知识方舟跃迁）—— 一个包裹 `senior-software-architect-review` 仓库的游戏化Web应用。玩家作为"方舟总工程师"，在太空星图上勘探星域（知识大类）、扫描矿点（考点，2分钟概览，阅后即焚）、自学后提交手打笔记、AI模糊校验覆盖完整度、开采完成获得零件装配到飞船。虚空蛀虫（记忆遗忘）持续侵蚀已装配组件，需要定期巡检维修。距离考试的每一天都是"跃迁倒计时"。技术栈：Python FastAPI + SQLite 后端，Vanilla HTML/CSS/JS + D3.js + Cytoscape.js 前端，部署到 g.petrezhu.cn。 ## User Stories 1. 作为方舟总工程师，我想打开ARK就看到"舰桥日报"（昨日战果+今日任务+侵蚀预警+聚能斗领取），以便每天学习有明确起点 2. 作为方舟总工程师，我想在星图上看到22个程序化生成的形态各异的星球（每个星球有独特的颜色、地形纹理、晨昏线、大气光晕），以便我对探索产生好奇心 3. 作为方舟总工程师，我想点击一个未勘探的星域看到"未知信号"变为完整星球（勘探解锁动画），以便获得探索发现的快感 4. 作为方舟总工程师，我想浏览一个矿点的2分钟知识概览（AI从cheatsheets压缩生成），以便快速判断这个考点的内容和难度 5. 作为方舟总工程师，我想在看完概览后它自动标记为"已焚"（阅后即焚机制），以便获得"已扫描过这片区域"的进度感 6. 作为方舟总工程师，我想重新扫描已焚的概览时消耗少量燃料，以便有轻度的资源管理挑战但不被阻碍学习 7. 作为方舟总工程师，我想自行学习（看希赛视频/读教材/任何方式）后，在ARK中粘贴我手打的笔记 8. 作为方舟总工程师，我想提交笔记后AI批量校验它对当前矿点mandatory要素的覆盖完整度（模糊语义匹配，非关键词匹配），以便知道还需要补充什么 9. 作为方舟总工程师，我想在校验失败时先看到"你已覆盖的要素✓"（回显我的笔记要点）再看到缺失要素，以便先获得成就感再看到差距 10. 作为方舟总工程师，我想在校验失败时请求AI的2分钟微讲解（消耗10燃料），以便获得定向的补全指引 11. 作为方舟总工程师，我想在笔记校验通过时看到"开采仪式感"页面（矿石→零件分解图+自己的笔记要点逐条回显✓+燃料飘字+星球光晕脉冲+飞船组件槽位从虚线变实线），以便获得最高浓度的正反馈 12. 作为方舟总工程师，我想在开采完成时有5%概率触发"稀有矿脉"双倍奖励（考频≥12且跨科值≥0.8的考点标记为金色稀有矿脉），以便游戏机制直接服务考试策略 13. 作为方舟总工程师，我想在星图上看到已勘探星域的星球光晕强度随开采完成度增长，以便宏观进度一目了然 14. 作为方舟总工程师，我想在飞船视图中看到方舟的剪影式外观（船头机翼=导航系统/船身货舱=载荷系统/尾部引擎=反应堆），以便获得"我在建造一艘飞船"的具象成就感 15. 作为方舟总工程师，我想看到已装配的零件点亮飞船对应槽位、受损组件显示腐蚀蒙版（暗丝纹理），以便直观感知知识掌握状态 16. 作为方舟总工程师，我想每天首次登录时领取聚能斗燃料（45-60随机×连击系数），以便有每日仪式感 17. 作为方舟总工程师，我想看到连续登录天数和连击系数（3天×1.1/7天×1.25/14天×1.5），以便维持每日打开的习惯 18. 作为方舟总工程师，我想在顶部栏始终看到"距离基点跃迁 N 天"的DSEG7字体倒计时，以便对真实考试时间有具象感知 19. 作为方舟总工程师，我想在倒计时≤30天时数字转琥珀色、≤14天转红并轻微脉动，以便在不被催促的前提下自然感受到紧迫 20. 作为方舟总工程师，我想点击倒计时时看到AI对"以当前航速，跃迁窗口预计达成度X%"的评估（每日刷新一次），以便了解自己的备考是否在正轨上 21. 作为方舟总工程师，我想在压力测试（从exam-bank出题）完成后获得5-15随机燃料（按正确率浮动），以便测试本身成为资源获取途径 22. 作为方舟总工程师，我想在巡检时看到所有组件的耐久度仪表盘弧线（复用svg-gauge模式，低于30%转红），以便快速识别需要维修的知识点 23. 作为方舟总工程师，我想在维修受损组件时选择主动回忆（免费）、求AI提示（10燃料）、直接复原（15燃料），以便根据自己的状态选择复习策略 24. 作为方舟总工程师，我想在虚空中看到蛀虫侵蚀的威胁可视化（受损组件暗丝纹理+仪表盘红色），以便对"遗忘"有具象感知而非抽象数字 25. 作为方舟总工程师，我想打开ARK时看到"每日航海日志"（昨夜电报：昨日战果+今夜侵蚀预警+轮换舰长语录），以便每天都有新内容锚定"船在航行"的世界观 26. 作为方舟总工程师，我想在"史官"视图中看到成就徽章墙（20-30枚，获得的发光，未获得的剪影），以便有长线收集目标 27. 作为方舟总工程师，我想在获得成就时顶部栏图标亮起+一条日志（不弹窗打断），以便保持心流不被中断 28. 作为方舟总工程师，我想看到背景星云（3团3-5%透明度径向渐变斑块），以便星图不再是纯黑死寂 29. 作为方舟总工程师，我想在三个仪表盘式导航按钮（星图/飞船/测试）之间切换视图，每个按钮本身显示对应维度的进度环，以便导航本身也在展示进度 30. 作为方舟总工程师，我想在NPC对话面板中向遗迹向导提问（启发式，不直接给答案），以便在困惑时获得引导而非答案 31. 作为方舟总工程师，我想在NPC对话面板中向材料检验官查询笔记覆盖度、向测试官获取测试题、向史官查看进度报告，以便每个NPC有明确分工 32. 作为方舟总工程师，我想让ARK读取我的Obsidian笔记自动预填已学过的矿点进度，以便第一天打开就看到"已建造了一部分的飞船" 33. 作为方舟总工程师，我想在ARK中提交笔记时可选"同步到Obsidian"，以便笔记在两边都能看到 34. 作为方舟总工程师，我想在星图上看到稀有矿脉（金色光点）与普通矿点（蓝白色）的视觉区分，以便优先关注高价值考点 35. 作为方舟总工程师，我想在首次打开ARK（Obsidian预填后）看到已装配组件按序点亮的"觉醒序列"（约10s），以便获得"方舟正在苏醒"的首印象 36. 作为方舟总工程师，我想在完成完整模考时将其视为"跃迁模拟"，三科全过线时播放模拟跃迁成功动画，以便模考有仪式感 37. 作为方舟总工程师，我想看到燃料仓的液面可视化（反应堆发光液位随燃料增减变化），以便燃料不只是数字 38. 作为方舟总工程师，我想在ARK中看到我的笔记要点以Obsidian兼容Markdown格式回显，以便确认AI理解了我的笔记内容 39. 作为方舟总工程师，我想看到矿点的难度标识（来自curriculum.json的difficulty字段），以便自行选择匹配当前状态的挑战 40. 作为方舟总工程师，我想在ARK中使用键盘快捷键（如领取聚能斗、开始巡检），以便提高高频操作效率 ## Implementation Decisions ### 测试接缝（Testing Seam）主接缝：**REST API 层**。所有游戏逻辑通过 `/api/*` 端点暴露，前端仅消费API。测试策略： - 后端逻辑可以脱离FastAPI独立测试（纯Python函数） - API层通过 httpx/TestClient 测试端到端行为 - 前端不包含业务逻辑（文档v1.1红线：视图层禁止把业务逻辑写在前端）理想测试数量：1个主接缝（API层），辅以后端纯函数单元测试。 ### 模块划分 | 模块 | 职责 | 对外接口 | |---|---|---| | `golden_kg` | 读取senior-software-architect-review仓库，拆分矿点，提供只读知识图谱 | `get_sectors()`, `get_ores(sector_id)`, `get_overview(ore_id)` | | `ark_state` | SQLite读写方舟状态（玩家/星图/飞船/蛀虫/燃料/成就） | `get_state()`, `update_state(patch)` | | `fuel_economy` | 变量奖励计算、连击系数、燃料收支 | `calc_daily_collect(streak)`, `calc_mining_reward(ore_id, rare)`, `calc_test_reward(score)` | | `borer_engine` | SM-2改良侵蚀计时、耐久衰减、维修恢复 | `check_erosion()`, `repair(component_id, method)` | | `note_validator` | AI模糊匹配笔记与mandatory要素，返回覆盖度报告 | `validate(notes_text, ore_id) -> CoverageReport` | | `overview_generator` | 从cheatsheets压缩生成2分钟概览，缓存 | `generate(ore_id) -> markdown` | | `npc_engine` | 6个NPC角色的prompt管理+LLM调用+输出约束 | `chat(npc_role, message, context) -> response` | | `achievement_engine` | 成就条件判定、徽章状态管理 | `check_achievements(state) -> new_badges[]` | | `obsidian_sync` | 扫描Obsidian Vault、AI匹配笔记到矿点、双向同步 | `scan_vault()`, `sync_to_obsidian(note, ore_id)` | | `planet_gen` | 程序化星球参数生成（种子哈希→半径/颜色/噪声/环/大气） | `generate(sector_id) -> PlanetParams` | | `daily_briefing` | 每日航海日志模板生成、舰长语录轮换 | `generate(player_state) -> Briefing` | ### API 端点设计 ``` GET /api/briefing → 每日航海日志（首次打开时调用） GET /api/star-map → 星图数据（Cytoscape elements格式，含planet_params） GET /api/ship → 飞船状态（D3数据，含durability/erosion） GET /api/sector/{id} → 星域详情+矿点列表 GET /api/ore/{id}/overview → 矿点概览（2分钟，阅后即焚标记） POST /api/ore/{id}/scan → 标记已扫描（阅后即焚，消耗燃料若重扫） POST /api/notes/validate → 批量笔记校验（返回CoverageReport） POST /api/notes/validate/explain → 请求AI微讲解（消耗10燃料） POST /api/notes/validate/accept → 接受校验结果，开采完成（触发奖励+装配） POST /api/test/start → 开始压力测试（从exam-bank出题） POST /api/test/submit → 提交测试答案（返回判分+燃料奖励） POST /api/fuel/collect → 每日聚能斗领取（含连击系数） POST /api/repair/{component_id} → 维修组件（method: recall/hint/restore） GET /api/npc/{role}/chat → NPC对话 GET /api/achievements → 成就徽章列表 GET /api/countdown → 跃迁倒计时+每日评估 POST /api/sync/obsidian → 触发Obsidian同步 ``` ### 数据层决策 - Golden KG 直接读取 `senior-software-architect-review/` 目录（curriculum.json + cheatsheets/ + exam-bank/ + knowledge-index/），不做数据迁移 - Ark State 用 SQLite（WAL模式），fuel_log append-only，每日自动备份 - 矿点拆分：每个K主题按raw_tags拆3-8个矿点，矿点id格式 `{topic_id}#{序号}` - 稀有矿脉：`frequency_count ≥ 12 && cross_subject_value ≥ 0.8` 的矿点标记 `rare: true` - 概览缓存：首次生成后存SQLite，永久复用 ### 程序化星球生成用 sector_id 哈希作为种子，Simplex noise生成地形纹理，SVG渲染： - 噪声地形着色（2-4色色带） - 固定45°光源的晨昏线+大气边缘光 - 30%概率星环（虚线dash椭圆碎带） - 进度映射：glow_intensity = 开采完成度 ### 燃料经济数值 | 获取 | 数量 | 条件 | |---|---|---| | 每日聚能斗 | 45-60随机 × 连击系数 | 每日首次，连续3/7/14天×1.1/1.25/1.5 | | 开采完成 | 7-13随机 | 笔记校验通过 | | 稀有矿脉 | 开采×2 | 5%概率（考频≥12且跨科≥0.8） | | 压力测试 | 5-15 | 按正确率浮动 | | 消耗 | 数量 | 说明 | |---|---|---| | 重读已焚概览 | 5/次 | 阅后已焚再次扫描 | | 求AI提示 | 10/次 | 校验失败时微讲解 | | 复原遗忘内容 | 15/次 | 直接恢复耐久 | 设计约束：每日净收益 > 消耗，燃料为0仍可学习。 ### 前端视图结构 ``` ┌───────────────────────────────────────────────┐ │ 顶部栏: [聚能斗] | 燃料数 | DSEG7倒计时 | [星图][飞船][测试]仪表盘导航 │ ├────────────────────┬──────────────────────────┤ │ │ │ │ 星图/飞船主视图 │ 主内容区 │ │ (Cytoscape/D3) │ (矿点概览/笔记提交/ │ │ │ 测试/NPC对话/维修) │ │ │ │ ├────────────────────┴──────────────────────────┤ │ 底部栏: 三系统进度条 [导航████░░][载荷██░░░░][反应堆██░░] │ └───────────────────────────────────────────────┘ ``` - 首次打开 → 舰桥日报（briefing面板） - 星图视图 → Cytoscape全景，节点=星球，连线=知识依赖 - 飞船视图 → D3剪影装配图 - 学习视图 → 矿点概览+笔记提交+校验结果 - 测试视图 → 答题界面 - NPC视图 → 对话面板 - 进度视图 → 统计图表+成就墙 ### 视觉规范 - 风格：写实太空（深空#0a0e1a背景，星球纹理，能量连线） - 字体：DSEG7（jsdelivr CDN）用于仪表数字，系统字体用于正文 - 星云背景：3团3-5%透明度径向渐变SVG - 状态变化：仅允许一次性CSS transition（scale/opacity/glow），无循环动画 - 耐久仪表盘：svg-gauge弧线，<30%转红 - 开采仪式：矿石→零件分解图 + 笔记要点回显✓ + 燃料飘字 + 星球脉冲 + 组件实线 ### Obsidian双向同步 - 读取方向：ARK启动时扫描Obsidian Vault软考目录，AI匹配笔记到矿点，预填进度 - 写入方向：用户在ARK提交笔记时可选"同步到Obsidian"，格式化为Markdown写入 - 冲突处理：以Obsidian版本为主，ARK仅在用户触发时写入 ## Testing Decisions ### 测试原则 - 只测外部行为（API输入→输出），不测实现细节 - 每个测试用例独立（不依赖其他用例的副作用） - 状态变更通过API验证，不直接查数据库 ### 测试模块 | 模块 | 测试类型 | 说明 | |---|---|---| | `golden_kg` | 单元测试 | 矿点拆分正确性、概览生成、稀有矿脉标记 | | `fuel_economy` | 单元测试 | 变量奖励范围、连击系数、收支平衡 | | `borer_engine` | 单元测试 | 侵蚀计时、耐久衰减、维修恢复 | | `note_validator` | 集成测试 | 笔记→覆盖度报告（需mock LLM） | | `achievement_engine` | 单元测试 | 成就条件判定 | | `daily_briefing` | 单元测试 | 模板生成、语录轮换 | | API层 | E2E测试 | 完整学习循环（勘探→扫描→笔记→校验→开采→装配） | ### 测试先例参考 `senior-software-architect-review/tutor/` 中的进度协议测试模式：append-only事件日志、幂等性验证、状态重建。 ## Out of Scope - **精细动画/音效**：不开发循环动画、粒子系统、音效。仅允许一次性CSS transition。 - **Three.js 3D模式**：保留设计接口，暂不开发。 - **多用户支持**：单用户架构，SQLite。 - **移动端适配**：MVP仅桌面端。后续可加响应式。 - **论文写作系统**：论文燃料仓仅做进度展示，不实现完整论文写作流程。 - **领域复用**：MVP仅软考架构师，不做领域无关抽象。 - **自动题库扩充**：禁止AI自动扩充考点，所有矿点需人工确认。 - **考前3天策略切换**：考前3天自动停止低频新课、只看保命卡——作为后续迭代。 ## Further Notes ### 开发节奏（7天MVP） - Day 1-2：基础框架（FastAPI + SQLite + golden_kg读取 + 矿点拆分） - Day 2-3：星图+飞船（Cytoscape + D3 + 程序化星球 + 进度映射） - Day 3-4：学习核心（概览生成 + 阅后即焚 + 笔记校验 + 开采仪式） - Day 4-5：游戏系统（燃料经济 + 聚能斗 + 蛀虫侵蚀 + 压力测试） - Day 5-6：NPC+同步（LLM对话 + Obsidian同步 + 进度报告） - Day 6：游戏性增强包（变量奖励+连击+稀有矿脉+航海日志+成就+倒计时） - Day 6-7：部署打磨（Nginx + systemd + g.petrezhu.cn） ### 与现有仓库的关系 ARK是"壳"，senior-software-architect-review是"核"。不重新实现知识图谱和进度管理。ARK读取现有仓库的curriculum.json、cheatsheets、exam-bank、knowledge-index，适配其数据格式。 ### 设计文档完整设计见 `/root/git/ARK/docs/DESIGN.md`（v2.1），领域词汇表见 `docs/CONTEXT.md`，架构决策见 `docs/adr/`。 ### 关键设计约束 - 鼓励式学习：燃料是轻度挑战，不是硬瓶颈 - 所有LLM输出基于Golden KG，禁止生成图谱外知识点 - Obsidian笔记以用户版本为主 - 单次前端开发 ≤30分钟，每日累计 ≤45分钟 - 视图层禁止包含业务逻辑