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。

## 构建命令

```powershell
# 开发模式
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`）。