写给下一个 AI 助手： 这是项目的完整状态快照。请先阅读本文了解项目全貌，再开始工作。 不要依赖对话历史来推断状态——以本文为准。
- 名称: Kernelsoul / Kernelsoul 角色引擎
- 版本: v2.5
- 类型: AI 角色扮演后端引擎 + Web 前端
- 技术栈: Python 3.11+ (FastAPI 后端) + React/TypeScript (Vite 前端)
- API 协议: OpenAI 兼容（DeepSeek / OpenAI 双后端）
- 运行端口: 后端 8001，前端开发服 5173，生产构建 4173
以下功能已全部实现并验证通过，不要重复开发：
- GameState 强类型状态系统（HP/Energy/Goodwill/Money/Emotion/Scene/Inventory）
- 状态持久化（StateManager），JSON 读写
- 角色卡片加载器（V1-V4 格式兼容，character_data.json + 独立文件）
- AI 响应解析器（ParserEngine，JSON + 自然语言双模式）
- 语义叙事渲染引擎（SemanticEngine + SemanticRenderer，三模式：direct/semantic/hybrid）
- KNN 短语语料库（PhraseLibrary）
- 三层分级压缩记忆（MemoryManager：轻量10轮 → 深度50轮 → 史诗200轮）
- DSL 剧本语言编译器（SLL 递归下降解析器，WHEN/IF/THEN/CHANGE/SET 语法）
- 规则编译器（RuleCompiler，AI 协作规则生成）
- 规则进化触发器（EvolutionTrigger）
- 世界书三维检索（WorldBookRetriever）
- 上下文组装（Context + ContextWrappers）
- 会话元数据管理（SessionMeta）
- 路径解析器（PathResolver，41 条路径方法）
- 草稿与版本管理（DraftManager）
- 变量管理系统（VariableManager，多 scope：global/character/session/temporary）
- 随机事件管理器（RandomEventManager）
- 沙箱插件系统（PluginManager，12 个钩子）
- 原子写入（utils/atomic_write.py）
- 快照管理（utils/snapshot.py）
- 左右侧边栏拖拽调整宽度（ResizableHandle，200-500px 左 / 240-480px 右）
- 状态栏从 variables 系统读取并自动推断显示格式（VariableBasedStatusBar）
- 状态栏模板渲染（TemplatedStatusBar，支持纯文本/JSON/HTML 三种格式）
- 角色变量调试面板（DebugModePanel，实时修改角色状态）
- 调试面板与 variables 系统双向同步
- 角色关系图（RelationshipGraphPanel，含缩放、气泡、AI 自动生成）
- 位置地图（LocationMapPanel）
- 语义轴可视化（SemanticAxes）
- 规则追踪（RuleTrace）
- 库存列表（InventoryList）
- 聊天窗口（ChatWindow，SSE 流式 + Typewriter 打字效果）
- 预设编辑器（PresetEditor + ChatPresetsPanel）
- 会话管理（SessionCreator，多会话切换）
- 草稿预览/提交/丢弃（DraftPreview + DraftManager）
- 角色编辑面板（CharacterEditPanel + PlayerPersonaPanel）
- 世界书编辑面板（WorldbookPanel）
- 记忆锚点面板（MemoryAnchorPanel）
- 设置栏（SettingsBar，位于左侧边栏底部）
- API 配置面板（ApiConfigPanel）
- 备份面板（BackupPanel）
- 主题切换（亮/暗，完整生效）
- 预设模块系统（preset-modules，含版本管理）
- 开场管理（多开场切换）
- 图片发送与 AI 解析（多模态）
- 发布门禁系统（check.bat 一键验收：pytest → lint → build → 健康检查）
- 原子写入（draft_manager、variable_manager、snapshot、recent_log 均使用）
- 前缀缓存优化（Prompt 分层消息列表，system/context/history/current 四层结构）
- 插件回调超时保护（5 秒超时，ThreadPoolExecutor）
- stop_flag 跨会话隔离（per-generation 停止标志，多数会话互不干扰）
- 布尔值类型转换规范化（支持 true/false/1/0/yes/no 字符串）
- str(None) → "" 修复（变量 STRING 类型 None 值不再输出字面 "None"）
- auto-save 线程异常保护（崩溃不再静默退出）
- 路径遍历防护（文件上传/删除使用 _safe_name 校验）
- test_phase1.py — 48 用例
- test_memory.py — 27 用例
- test_parser.py — 41 用例
- test_dsl_compiler.py — 11 用例
- test_rule_compiler.py — 10 用例
- test_evolution_trigger.py — 通过
- test_character_loader.py — 通过
- test_worldbook.py — 通过
- test_plugin.py — 11 用例
- test_saved_drafts.py — 12 用例
- test_semantic.py — 17 用例
- test_prompt_system.py — 35 用例（含前缀缓存验证）
- test_variable_manager.py — 40 用例
- 总计：321+ 用例，全部通过
- night_hunter — 夜城猎魔人·林霜（完整示例，含语义渲染）
- 我的萝莉魅魔妈妈 — 14 变量 + 状态栏（完整 V4 卡）
- cyber_test — CyberSprite-7（轻量示例）
- demon_test — 堕魔公主 Lucy（轻量示例）
以下问题在对抗式审查中已识别，但尚未实现：
| 严重度 | 问题 | 说明 |
|---|---|---|
| 关键 | API Key 暴露 | /api/config 端点返回明文 Key |
| 关键 | CORS 全开放 + 无默认认证 | _ADMIN_TOKEN 为空时所有请求通过 |
| 高 | SSE 流无请求体大小限制 | /api/chat/stream 无 body 大小限制 |
| 高 | _safe_name 正则黑名单 |
路径遍历防护依赖正则而非白名单 |
| 高 | _dirty 标志非线程安全 |
bool 赋值在 Python 中非原子操作 |
| 中 | _sanitize_filename 允许路径分隔符 |
zip 上传流程中可能允许子目录穿越 |
Kernelsoul/
├── README.md ← 本文
├── check.bat ← 发布门禁一键验收
├── 启动.bat ← 启动脚本（Dev/Prod/后端/构建四种模式）
├── 待办/ ← 文件系统待办（进行中/已完成/待规划）
├── docs/
│ ├── 参考资料/
│ │ ├── CODE_WIKI.md ← 代码百科（API 端点、架构、版本演进）
│ │ ├── workflow.md ← 开发工作流
│ │ ├── V3升级V4模板说明.md ← 角色卡模板升级指南
│ │ └── v4_card_template/ ← V4 角色卡模板文件
│ └── 开发手册/ ← 历史开发手册（已归档）
├── in-dev/ ← 主开发目录
│ ├── api_server.py ← FastAPI 后端入口
│ ├── core_engine.py ← 核心引擎
│ ├── ai_bridge.py ← AI API 桥接
│ ├── variable_manager.py ← 变量管理系统
│ ├── plugin_manager.py ← 插件管理器
│ ├── draft_manager.py ← 草稿管理
│ ├── state_manager.py ← 状态持久化
│ ├── memory_manager.py ← 三层记忆
│ ├── parser_engine.py ← 响应解析器
│ ├── dsl_compiler.py ← DSL 编译器
│ ├── rule_compiler.py ← 规则编译器
│ ├── evolution_trigger.py ← 进化触发器
│ ├── semantic_engine.py ← 语义引擎
│ ├── semantic_renderer.py ← 语义渲染器
│ ├── phrase_library.py ← 短语库
│ ├── worldbook_retriever.py ← 世界书检索
│ ├── character_card_loader.py ← 角色卡加载
│ ├── character_state_manager.py ← 角色状态管理
│ ├── context.py ← 上下文组装
│ ├── context_wrappers.py ← 上下文包装器
│ ├── session_meta.py ← 会话元数据
│ ├── path_resolver.py ← 路径解析
│ ├── random_event_manager.py ← 随机事件
│ ├── utils/
│ │ ├── atomic_write.py ← 原子写入
│ │ └── snapshot.py ← 快照
│ ├── configs/
│ │ ├── system.json ← API 配置
│ │ ├── rules.json ← 全局规则
│ │ └── presets/ ← 预设文件
│ ├── characters/ ← 角色卡片
│ ├── plugins/ ← 插件示例
│ ├── frontend/ ← React 前端
│ │ └── src/
│ │ ├── features/chat/ ← 聊天功能
│ │ ├── features/assistant/← AI 助手
│ │ ├── state-panel/ ← 状态栏
│ │ ├── settings/ ← 设置面板
│ │ ├── sidebar/ ← 侧边栏
│ │ ├── debug/ ← 调试面板
│ │ ├── stores/ ← Zustand 状态管理
│ │ └── api/ ← API 客户端
│ ├── requirements.txt
│ └── *.py ← 测试文件
└── .trae/specs/ ← 已完成的 spec 文档
cd in-dev
pip install -r requirements.txt
cd frontend && npm install && cd ..编辑 in-dev/configs/system.json，填入 api_key。
# 方式一：启动脚本（推荐）
.\启动.bat # 选择模式 1/2/3/4
# 方式二：手动
cd in-dev
python api_server.py # 后端 http://127.0.0.1:8001
cd frontend && npm run dev # 前端 http://localhost:5173.\check.bat # 一键测试 + lint + build + 健康检查- Prompt 分层消息列表：
build_prompt返回list[dict]，顺序固定 system → context → history → current。这是前缀缓存优化的核心，不要改为拼接字符串。 - 变量系统：
character_state.variables与VariableManager双向同步。状态栏从 variables 系统读取。 - 原子写入：所有 JSON 持久化必须使用
utils/atomic_write，不能直接open()+json.dump()。 - SettingsBar 位置：仅在左侧边栏打开时渲染，位于侧边栏底部，使用 flex 布局。
- recent_log 格式：新格式为结构化 JSON 消息对
[{role, content}]，_build_history_messages兼容旧纯文本格式。 - DSL 语法：
WHEN condition KEYWORDS k1,k2 IF condition THEN action，USE/ELSE/BECAUSE 均在 DSL 编译器中实现。 - 渲染模式：direct（数值）/ semantic（语义叙事）/ hybrid（混合），可运行时切换。
- 不要重新实现已存在的功能——上面所有的 ✅ 项均已实现
- 不要修改 prompt 分层消息结构——前缀缓存优化依赖固定顺序
- 不要删除
in-dev/README.md——那是开发级文档，本文是项目级状态文档 - 不要修改
docs/参考资料/中的文件——除非用户明确要求 - 不要创建新的待办文件夹——已有
待办/目录 - 不要引入 Gradio——已完全迁移到 FastAPI + React
最后更新：2026-07-31 当前版本：v2.5