MeetMind: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

MeetMind 是一个多 Agent RAG 协作系统的 demo（TypeScript 项目，monorepo：apps/runtime 后端 + apps/desktop 前端）：5 个角色 Agent（架构师、后端、前端、测试、产品经理）围绕一个项目需求展开讨论。架构师作为入口和终止者，其他角色在 LangGraph 条件边的驱动下自由路由。每个 Agent 拥有独立的 PostgreSQL 表 + 私有 RAG 工具（PostgreSQL 混合检索：pgvector 向量 kNN + pg_trgm 关键字召回，再过 本地 cross-encoder rerank）。存储已从 Elasticsearch 迁移到 PostgreSQL（pgvector）。

LLM 通过 OpenAI 兼容协议调用（默认配置小米 MiMo），所以 new ChatOpenAI({...}) 里有一个 modelKwargs: { thinking: { type: "disabled" } }（给后端关掉 thinking 模式）不能改。

常用命令

包管理用 pnpm，不要用 npm / yarn。运行用 tsx 直接跑 .ts，开发期不需要预编译。

# 第一次（或换机）启动:
docker compose up -d                   # 起本地单节点 PostgreSQL+pgvector (pgvector/pgvector:pg17, 宿主机端口 5433)
pnpm install                           # 安装依赖（无 torch；主要是 onnxruntime + langchain + pg，首次较慢）
pnpm dev                               # tsx src/index.ts 启动 CLI
pnpm start                             # 同上

# 生产 / 编译:
pnpm build                             # tsc 编译到 dist/
pnpm start:prod                        # node dist/index.js
pnpm typecheck                         # tsc --noEmit，只做类型检查

# 重置某个 agent 的 PostgreSQL 表并重灌（开发时常用）
pnpm exec tsx -e "import('./src/database/ingestion/initializer.ts').then(m => m.resetAgentDb('backend'))"

# 完全抹库后重灌（删 docker volume，下次启动重新建表 + 灌种子）
docker compose down -v && docker compose up -d

环境变量在 .env（参考 .env.example）：LLM 三件套 API_KEY / BASE_URL / MODEL_NAME 是调用 LLM 的必需项；PG_URL 默认 postgresql://meetmind:meetmind@localhost:5433/meetmind（宿主机 5432 常被本地原生 postgres 占用，docker-compose 把容器映射到 5433 避让）。rerank 已改为本地 cross-encoder，不再需要 COHERE_API_KEY。 启动时唯一的硬退出是 pingDb() 失败（process.exit(1)）；LLM 的 key/baseUrl 缺失不会在启动时被拦截，会在第一次调用模型时抛错（zod 对这些字段给空字符串默认值，不报错）。

高层架构

调用链一句话

src/index.ts (load dotenv) → bootstrap() → buildGraph() → startServer(3002)   ← 默认入口（HTTP/SSE 服务）
                                              ↓
   POST /api → handleRpc → chat.send → runExecution(graph, …) → graph.stream(["custom","values"], thread_id)
                                              ↓
   START → rewrite_node → intent_node → route_node ──┬─► assistant_node → END      （右侧回答助手）
                                                     └─► architect_node → … 团队   （左侧 5 角色协作）
                                              ↓
              createNode(agent) 闭包 → agent.invoke()（Phase1 工具循环 + Phase2 结构化收尾）
                                              ↓
                                    routeToWhichAgent(state) → 下一个 _node 或 END