xianren_studio/AGENTS.md

项目维护约定

项目简介

Xianren Studio（仙人工作室）：Tauri 2 + React 的 Windows 本地大模型桌面应用（对标 LM Studio）。功能与代码结构见：

• docs/FEATURES.md —— 功能记录（权威，含改动记录）
• docs/ARCHITECTURE.md —— 代码组织与布局、数据流、事件通道、数据库结构

强制约定

每次改动功能后，必须同步更新文档：

1. 功能新增 / 修改 / 删除 → 更新 docs/FEATURES.md 中对应章节，并在「改动记录」追加一条（日期 + 内容）。
2. 涉及代码结构、模块职责、数据流、事件通道、数据库表/字段 → 更新 docs/ARCHITECTURE.md 对应章节。
3. 涉及技术栈、目录结构、构建方式 → 同步更新 README.md。

每次代码改动后，必须提交并推送到远程仓库，且每次推送都打一个新的 tag：

1. 完成一轮代码改动（含文档同步）后，git add -A 并提交，提交信息用中文简要描述本次改动。
2. 推送到远程 origin/main。
3. 以现有最新 tag 为基准递增版本号（如 v1.0.0 → v1.1.0），创建带注释的新 tag 并推送 tag。

构建命令

# 开发模式
npm --prefix apps/desktop run dev

# 正式版（必须带 custom-protocol 特性，否则前端不内嵌）
npm run build --prefix ui
cargo build --release -p xianren-desktop --features custom-protocol

常见注意事项

• 数据库旧库迁移依赖 crates/core/src/app.rs 中 ensure_column 增量补列；新增列时同时更新 schema.sql 与 ensure_column 清单。
• 新增 Tauri 命令必须在 apps/desktop/src/lib.rs 的 invoke_handler 注册，并在 ui/src/api.ts 封装。
• 新增前后端事件必须成对：后端 emit 与前端 onEvent，并在 docs/ARCHITECTURE.md 事件通道表登记。
• 数据目录在 %APPDATA%\XianrenStudio（SQLite：xianren.db）。