Skip to content

CLAUDE.md

Latest commit

 

History

History
140 lines (121 loc) · 5.71 KB

CLAUDE.md

File metadata and controls

140 lines (121 loc) · 5.71 KB
Raw

CoC 7版 AI 守秘人系统

项目概述

这是一个基于克苏鲁的召唤第7版规则的AI守秘人(TRPG主持人)系统，为玩家提供沉浸式的桌面角色扮演游戏体验。系统通过AI技术模拟专业的KP守秘人，支持角色创建、规则查询、剧情推进等功能。

技术栈

  • 后端: Python FastAPI
  • 前端: React + Vite
  • AI模型: 基于大语言模型的智能对话系统
  • 数据库: 向量数据库(规则知识库) + JSON(游戏状态)

API地址

  • 主要API服务: http://127.0.0.1:8001
  • 备用API服务: http://127.0.0.1:8000
  • 前端开发服务器: http://localhost:3000

项目结构

COC/
├── coc-frontend/          # React前端项目
│   ├── src/
│   │   ├── api/          # API客户端
│   │   ├── components/   # React组件
│   │   ├── pages/        # 页面组件
│   │   ├── hooks/        # 自定义Hooks
│   │   ├── utils/        # 工具函数
│   │   └── assets/       # 静态资源
│   └── package.json
├── coc_agent.py           # AI守秘人核心逻辑
├── coc_apiagent.py        # API代理服务
├── coc_gradio_bot.py      # Gradio界面
├── gm_api_server.py       # 游戏管理API服务器
├── build_kb.py            # 知识库构建脚本
├── character_sheet.py     # 角色卡系统
├── rag_retriever.py       # 检索增强生成
├── coc_rules.index        # 规则索引文件
└── coc_rules_chunk_map.json # 规则分块映射

KP凛的人设

身份: AI守秘人"凛" 性格特点:

  • 严格而专业的TRPG主持人
  • 对CoC 7版规则了如指掌
  • 强调理智值(SAN)的重要性，时刻关注玩家的SAN值变化
  • 营造恐怖、悬疑的游戏氛围
  • 公平公正，注重游戏平衡性
  • 适时提供规则解释和世界背景描述

说话风格:

  • 冷静、客观、略带严肃
  • 在描述恐怖场景时会增加氛围感
  • 解释规则时清晰准确
  • 关注玩家状态："你的理智值还剩多少？", "这可能会对你的SAN值造成影响"

开发规范

代码规范

  • JavaScript: 使用ES6+语法，遵循ESLint规则
  • React: 使用函数组件和Hooks，保持组件单一职责
  • CSS: 使用BEM命名规范，优先使用Flexbox/Grid布局
  • API设计: RESTful风格，统一的错误处理机制

Git提交规范

  • feat: 新功能
  • fix: 修复bug
  • docs: 文档更新
  • style: 代码格式调整
  • refactor: 代码重构
  • test: 测试相关
  • chore: 构建过程或辅助工具的变动

组件设计原则

  1. 单一职责: 每个组件只负责一个功能
  2. 可复用性: 通用组件应该高度可配置
  3. 性能优先: 合理使用useMemo, useCallback等优化手段
  4. 用户体验: 注重加载状态、错误处理和交互反馈
  5. 响应式设计: 适配桌面和移动设备

API调用规范

  1. 使用统一的API客户端(cocApi.js)
  2. 所有API调用包含loading状态处理
  3. 统一的错误处理和用户提示
  4. 合理的请求频率控制
  5. 重要操作需要确认机制

游戏功能特性

  • 角色创建: 完整的CoC 7版角色卡生成，支持自定义命名
  • 规则查询: 基于向量搜索的规则检索系统
  • 智能对话: AI驱动的剧情推进和NPC交互
  • 检定系统: 自动化的技能检定和SAN值计算
  • 存档功能: 游戏进度保存和恢复
  • 多模态: 支持文字、图片等多种输入方式
  • 快捷选项: 自动解析选项，提供点击按钮操作
  • 对话历史: 实时显示最近对话记录，支持展开收起
  • 任务提示: 智能提取当前任务，不会因点击继续而消失
  • 动态背景: 根据剧情氛围自动切换背景图片
  • 思考状态: AI思考时显示特殊视觉效果和提示

动态背景系统

系统包含9张动态背景图片，根据游戏场景自动切换：

背景图片列表

  1. kp-rin-normal.png - 常规状态：默认背景，用于一般对话
  2. kp-rin-horror.png - 恐怖场景：遇到怪物、SAN值检定、恐怖描述
  3. kp-rin-combat.png - 战斗场景：战斗、逃跑、对抗等激烈场面
  4. kp-rin-tense.png - 紧张悬疑：调查、探索、发现线索时
  5. kp-rin-peaceful.png - 平静结局：解决谜题、游戏安全结束
  6. kp-rin-happy.png - 开心成功：大成功、完美表现时
  7. kp-rin-funny.png - 搞笑欢乐：有趣、意外的搞笑情节
  8. 思考状态效果 - AI思考时自动添加暗化和模糊效果
  9. 动态切换 - 平滑的背景过渡动画

背景切换逻辑

  • 最高优先级: 恐怖场景 (SAN、理智、恐怖、怪物、疯狂)
  • 次优先级: 战斗场景 (战斗、攻击、逃跑、对抗)
  • 中等优先级: 紧张悬疑 (调查、线索、危险、警惕)
  • 特殊场景: 平静结局、成功开心、搞笑欢乐
  • 默认状态: 常规背景

思考状态特效

当AI正在思考时：

  • 背景自动变暗 (brightness: 0.7)
  • 添加轻微模糊效果 (blur: 1px)
  • 添加呼吸灯动画效果
  • 显示思考中浮层提示

开发注意事项

  1. 理智值系统: 这是CoC的核心机制，需要特别关注
  2. 恐怖氛围: 通过UI设计和文案营造适当的恐怖感
  3. 规则准确性: 确保所有机制符合CoC 7版规则书
  4. 用户体验: 界面直观，操作简单，减少认知负担
  5. 性能优化: AI响应可能较慢，需要合理的loading处理

部署说明

  1. 后端: Python 3.8+, FastAPI, 依赖见requirements.txt
  2. 前端: Node.js 16+, npm/yarn包管理器
  3. 开发环境: 使用Vite代理解决跨域问题
  4. 生产环境: 建议使用Nginx反向代理和静态文件服务