yoji: Instructions file for Claude Code

CLAUDE.md

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

项目概述

本地 AI Agent 桌面应用。技术栈：Electron + React + TypeScript + Vite，基于 electron-vite 脚手架创建，包管理器 pnpm。

常用命令

pnpm install              # 安装依赖
pnpm dev                  # 启动开发环境（支持 HMR 热更新）
pnpm build                # 类型检查 + 构建
pnpm build:mac            # 构建并打包 macOS 应用
pnpm build:win            # 构建并打包 Windows 应用
pnpm format               # Prettier 格式化代码
pnpm lint                 # ESLint 检查
pnpm typecheck            # 运行所有 TypeScript 类型检查

三进程架构

Electron 应用由三个独立进程组成，源码分别对应 src/ 下的三个目录：

1. 主进程 (src/main/)

Node.js 环境，负责窗口创建、系统交互、IPC 通信。LangChain Agent、模型调用、文件读写、工具执行等核心逻辑全部在这里。

src/main/
├── index.ts               # 入口：窗口创建 + 注册所有 IPC
├── config.ts              # 配置读写（getConfig/setConfig）
├── http.ts                # HTTP 请求工具
├── ipc/                   # IPC 处理器
│   ├── index.ts           # registerAll() 汇总注册
│   ├── agent.ts           # agent:chat / agent:chat:stream / wechat:toggle（微信连接切换）
│   ├── config.ts          # 配置 IPC（通用 config:getAll/set/delete）
│   ├── emotion.ts         # emotion:log（情绪日志查询）
│   ├── file.ts            # file:readAgentsMd / file:export / file:import
│   ├── http.ts            # HTTP IPC
│   ├── mcp.ts             # mcp:testConnection / mcp:updateMcpStoreVersion
│   ├── tts.ts             # tts:getEnabled / tts:setEnabled / tts:toggle
│   ├── broadcast.ts       # 通用广播工具（主→渲染主动推送）
│   └── browser-window.ts  # browserWindow:open（额外开无框窗口加载指定地址/应用内路由）
├── mcp/                   # MCP 客户端管理（预留）
└── agent/                 # AI Agent 核心
    ├── index.ts           # chat / chatStream（对话入口 + 流式处理）
    ├── create-agent.ts    # Agent 工厂（createAgent / getCheckpointer / companion 初始化，MCP 子 Agent 注入）
    ├── model.ts           # 模型工厂（DeepSeek / Qwen）
    ├── system-prompt.ts   # System Prompt 构建
    ├── children-agent/    # 子 Agent 定义
    │   └── mcp-execute-agent.ts  # MCP 工具执行子 Agent（SubAgent 定义 + getTools）
    ├── emotion/           # 激素情绪系统
    │   ├── schema.ts      # emotion_log 表操作（CRUD）
    │   ├── index.ts       # changeEmotion() 情绪变化引擎
    │   └── emotion_model.ts # LLM 情绪分析
    ├── tools/             # Agent 工具集（含 mcp-manage.ts MCP 管理工具）
    ├── skills/            # 内置 Skills
    ├── middleware/         # Agent 中间件
    │   ├── tool-error-handler.ts  # 工具调用容错
    │   ├── file-read-guard.ts     # 文件读取拦截：PDF→pdf-parse 提取文字、二进制拦截、兼容 DeepSeek/Qwen
    │   └── summarization.ts       # 摘要中间件
    ├── children-agent/    # 子 Agent：async/（异步任务队列 + 事件循环 executor）、sync/（同步子 Agent）、agent-list、mcp-execute-agent
    ├── task-monitor/      # 任务运行信息缓存（updateTaskRunningInfo 增量写入 / queryTaskQueue 查询；主对话与异步任务共用）
    ├── wechat-connect/    # 微信 iLink Bot 连接
    │   ├── index.ts       # toggleWechat / initWechatConnect 入口
    │   ├── request.ts     # HTTP 工具（get/post，统一 BASE_URL + 公共请求头）
    │   └── wechat-server.ts # 扫码登录、消息轮询、发送/回复、输入状态、AI 回复
    └── utils/             # checkpoint 清理（含 deleteMessageByIndex 精确删消息）、chat-history、TTS 播报、
                            # token-logger、embedding、speech（macOS 原生语音识别）、tem-file-manage（临时文件读写）