识策AI (Shice AI)

AI 人际策略军师 — 让普通人拥有专业人际决策能力。

仓库根目录另有简短 README.md（便于 GitHub 首页展示）；完整说明在本页。

项目结构

shice_dev/
├── frontend/               # 前端 Monorepo (pnpm + Turborepo)
│   ├── packages/
│   │   ├── shared/          # @shice/shared - 类型定义、常量、工具函数
│   │   ├── api/             # @shice/api - HTTP/WS 客户端
│   │   ├── stores/          # @shice/stores - Pinia 状态管理
│   │   └── composables/     # @shice/composables - 业务逻辑 Hook
│   └── apps/
│       ├── web/             # Vue 3 Web 应用 (Naive UI + UnoCSS)
│       └── desktop/         # Electron 桌面壳（可选，加载 web开发服或打包静态资源）
├── backend/                 # Go 后端 (Gin + GORM + Google ADK 多 Agent / OpenAI 兼容)
├── deploy/                  # Docker Compose 开发 & 生产部署
├── doc/                     # 产品文档与设计规范（本目录；本地站为 VitePress）
└── scripts/                 # 构建/部署脚本（含源码 zip打包 pack.sh）

快速开始

前置要求

• Node.js >= 22
• pnpm >= 9
• Go >= 1.26（以 backend/go.mod 为准）
• Docker & Docker Compose

启动开发环境

# 1. 启动基础设施 (MySQL, Redis, Qdrant, MinIO)
cd deploy && docker-compose up -d

# 2. 配置后端（复制示例并填写密钥）
cp backend/config.example.yaml backend/config.yaml
# 可选：在 backend/langfuse/.env 写入 LANGFUSE_*，启动时会自动加载（见下文）

# 3. 启动后端（工作目录需在 backend，以便读取 config.yaml）
cd backend && go run ./cmd/server

# 4. 启动前端
cd frontend && pnpm install && pnpm dev:web

前端开发默认 http://localhost:3000；Vite 将 /api 代理到本机 8080（见 apps/web/vite.config.ts）。生产构建时的 API 根路径由环境变量 VITE_API_BASE_URL 等在构建阶段注入。

配置要点（近期能力）

能力	说明
后端配置外置	不必把密钥写进仓库：SHICE_USE_ENV_ONLY=1 可仅用环境变量启动；或 SHICE_ENV_FILE / backend/.env（gitignore）在加载 YAML 前注入；CONFIG_PATH 指向挂载在机外的 YAML；缺失文件时 SHICE_CONFIG_OPTIONAL=1 则用默认值 + 环境变量。详见 backend/config.example.yaml 文首说明。
Langfuse 可观测	config.yaml 中 langfuse.enabled: true，密钥推荐用环境变量或 backend/langfuse/.env（已 gitignore）。启动时会依次尝试加载 $LANGFUSE_ENV_FILE、langfuse/.env、backend/langfuse/.env。
免费/付费额度	免费用户「每日首问」用 Redis 计数（新会话首条用户消息或策略线程首次调用）；同一会话/策略线程内追问：免费最多 3 次、付费最多 10 次。追问时模型带 max_tokens（subscription.free_followup_max_tokens / paid_followup_max_tokens）。
自我画像	用户可在设置页「我的画像」填写可选背景信息；GET/PUT /api/v1/auth/self-profile。Agent 系统提示词为英文，并按前端 locale（zh/en）约束回复语言。
对话后资料提案	流式对话正常结束后，若服务端返回 profileProposal，Web 端会引导用户勾选并确认后再写入画像或人脉档案（偏空场景先居中引导，再在弹窗中展开完整字段表）。详见 modules/sse.md、modules/frontend.md 与 qa_chat_profile_proposal.md（QA 要点）。
中英界面	Web 顶栏可切换中文/English，写入 localStorage（shice_locale），对话请求会携带 locale。

构建

# 前端 Web 构建（站点部署）
cd frontend && pnpm build:web

# Electron 桌面包（先打 web，再 electron-builder；详见 apps/desktop/package.json）
cd frontend && pnpm build:desktop
# 或仅解包调试：cd frontend/apps/desktop && pnpm pack → 打开 release/ 下对应目录中的 .app

# 后端二进制
cd backend && go build -ldflags="-s -w" -o shice-backend ./cmd/server

# 源码 zip（排除 node_modules、dist、Go 可执行文件等，见 scripts/pack.sh）
./scripts/pack.sh

桌面开发（Vite + 自动开 Electron）：cd frontend && pnpm dev:desktop（需占用 3000 端口；vite 已设 strictPort，避免与 Electron 固定 URL 不一致）。

技术栈

层级	技术
前端框架	Vue 3 + TypeScript
UI 组件库	Naive UI
国际化	vue-i18n（界面中/英；对话语言随 locale 传后端）
状态管理	Pinia
CSS	UnoCSS
构建工具	Vite + Turborepo
后端框架	Go + Gin
ORM	GORM
数据库	MySQL 8
缓存	Redis 7
向量数据库	Qdrant
AI Agent	Google ADK 情感计算多 Agent（LLM 意图路由 + Pipeline 串联 + 情绪追踪）；自定义 model.LLM 适配 OpenAI 兼容 API
可观测	Langfuse（可选）

文档

本地网页阅读 Markdown

在仓库根目录执行（需 Node；使用 VitePress，默认主题支持浅色 / 深色与侧栏全文搜索；侧栏在 doc/.vitepress/config.mts 配置，无需手写 HTML）：

./scripts/serve-docs.sh

浏览器打开 http://127.0.0.1:3301（默认端口，可用 PORT=3302 ./scripts/serve-docs.sh 修改）。首次会在 doc/ 下安装依赖。

部署文档站到服务器（静态）

VitePress 产出的是纯静态文件，无需 Node 常驻；与现有「宝塔 + Nginx」方式一致即可。

1. 本机或 CI 构建（与前端一样可用 Node 22 + pnpm）：

./scripts/build-docs.sh

产物目录：doc/.vitepress/dist/（将该目录里面的文件放到站点根，而不是把 dist 文件夹本身当根目录上传，除非你希望 URL 多一层 /dist/）。

2. 上传到服务器：用 rsync、scp、宝塔「文件」、或 CI scp/ssh 均可，例如：

rsync -avz --delete doc/.vitepress/dist/ user@your-server:/www/wwwroot/docs.yourdomain.com/

（把路径换成你的站点目录；--delete 会删掉服务器上已不存在于本地的文件，按需去掉。）

3. 宝塔：新建网站（如 docs.yourdomain.com）→ 网站根目录指向上传目录 → 申请 SSL。

4. Nginx（站点 location / 可参考；与 VitePress 静态路由兼容）：

location / {
    root /www/wwwroot/docs.yourdomain.com;
    index index.html;
    try_files $uri $uri.html $uri/ /index.html;
}

5. 挂在子路径（例如 https://www.example.com/docs/）：在 doc/.vitepress/config.mts 里设置 base: '/docs/'（注意首尾斜杠），重新 build 后再上传；此时站点必须只通过该前缀访问，否则资源路径会错。

6. 本地检查构建结果：cd doc && pnpm preview（默认预览生产构建）。

• 开发进度与里程碑
• 模块设计总览（含架构一览与各模块索引）
  • 前端 Monorepo
  • Go 后端
  • Agent 情感计算引擎
  • API 路由
  • SSE 流式对话
  • 基础设施
  • 第三方依赖清单
• 产品定义
• UI 设计规范

生产部署（宝塔面板 + Docker）

宝塔面板服务器 + Docker，SSL 和域名由宝塔管理，应用服务跑在 Docker 中。

宝塔 Nginx (SSL)
  ├── www.maumet-ai.com  → 前端静态文件（宝塔站点目录）
  └── api.maumet-ai.com  → 反向代理 → Go 后端容器 (127.0.0.1:8080)

Docker
  ├── backend  (Go API, 127.0.0.1:8080)
  ├── mysql    (Docker 内网)
  └── redis    (Docker 内网)

快速部署

# 1. 克隆项目到服务器
cd /www/wwwroot
git clone <repo-url> shice_dev && cd shice_dev

# 2. 配置环境变量
cd deploy
cp .env.example .env
# 编辑 .env：数据库密码、AI_API_KEY、JWT_SECRET、FRONTEND_DIST_PATH、VITE_API_BASE_URL
# 若宝塔已装 Node 22+ / pnpm，可设 FRONTEND_BUILD_WITH_DOCKER=0 用本机构建前端
# 弱服务器可不在机上编译后端：设置 BACKEND_IMAGE=你的镜像:tag 与 BACKEND_PULL_ONLY=1，并先 docker login；本地/CI 用 deploy/build-push-backend-image.sh 推送镜像

# 3. 一键构建 & 启动
chmod +x deploy.sh
./deploy.sh

# 4. 宝塔面板配置
#    - www.maumet-ai.com 站点根目录指向 FRONTEND_DIST_PATH，开启 try_files
#    - api.maumet-ai.com 反向代理到 http://127.0.0.1:8080
#    - 两个站点分别申请 SSL 证书

宝塔 Nginx 配置

www.maumet-ai.com（前端）— 在站点 location / 中配置：

location / {
    root /www/wwwroot/www.maumet-ai.com;
    index index.html;
    try_files $uri $uri/ /index.html;
}

api.maumet-ai.com（后端）— 在站点 location / 中配置：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
    chunked_transfer_encoding on;
}

部署文件说明

文件	用途
backend/Dockerfile	多阶段 Go 构建，最终镜像约 30MB
frontend/Dockerfile	可选；非 Turbo 的 tsc+vite 构建（旧流程若仍用 frontend-builder，请用此文件覆盖服务器）
deploy/build-frontend-inner.sh	deploy.sh 默认用官方 node 跑此脚本，产物写入 FRONTEND_DIST_PATH
deploy/docker-compose.prod.yml	生产编排（仅 backend + mysql + redis）
deploy/docker-compose.frontend-builder.yml	可选叠加文件，仅在你需要 compose 构建前端镜像时使用
deploy/config.prod.yaml	后端生产配置模板（Docker 内部网络地址）
deploy/.env.example	环境变量模板（密码、API Key 等）
deploy/deploy.sh	一键部署/更新脚本
deploy/build-push-backend-image.sh	本地/CI：docker buildx 构建并推送后端镜像（服务器配合 BACKEND_PULL_ONLY）
deploy/init.sql	数据库初始化脚本（首次启动自动执行）
scripts/pack.sh	打源码 zip（排除 node_modules、dist、后端 shice-* 二进制等）

安全要点

• MySQL / Redis 端口不暴露到公网（仅 Docker 内网通信）
• 后端仅监听 127.0.0.1:8080，外部无法直接访问
• .env 中数据库密码改为强密码，JWT_SECRET 使用随机字符串
• AI_API_KEY 通过环境变量注入，不写入 git
• config.prod.yaml 中 server.mode: release，allow_mock_purchase: false
• 建议开启防火墙，仅放行 22/80/443