NoteAI AGENTS.md

AGENTS.md

本文件为 AI 编码助手（Claude Code、Codex、Jcode、Trae Agent 等）提供 NoteAI 仓库的工作指南。它合并了原 AGENTS.md 与 .trae/rules/project_rules.md，以当前代码实际为准。

---

1. 项目规则

1.1 模块化要求

• 项目必须模块化：每个功能模块独立成文件/目录，职责单一，禁止在单文件中混合多个不相关功能。
• 前端模块化：JS/CSS 按功能拆分文件，通过统一入口加载，禁止所有代码堆在一个文件中。
• 后端模块化：Python 按功能拆分模块（如 note_integration.py、web_download.py），通过 __init__.py 统一导出。
• 模块间通信：通过明确的接口/函数调用交互，禁止模块间直接操作彼此内部状态。

1.2 技术架构

• 前端：Tauri v2 + 原生 HTML/CSS/JS。
• 后端：Python sidecar，通过 stdin/stdout JSON-RPC 与前端通信。
• 前端调用后端：统一使用 window.api 对象（定义在 webui/js/api.js），禁止使用其他兼容层。
• 界面风格：整体对标 Obsidian 应用。

1.3 Prompt 管理

所有传递给大模型的系统提示词必须放在 prompts/ 目录下，禁止在业务代码中直接内联定义系统提示词。

• prompts/yaml/*.yaml 是单一事实来源；prompts/__init__.py 通过 prompts/loader.py 在导入时解析为常量。
• 提示词中可包含占位变量（如 {topic_name}、{content}），业务代码使用 .format() 填充。
• 新增提示词：先在 prompts/yaml/ 添加 YAML，再在 prompts/__init__.py 导出对应常量。

1.4 应用启动

桌面 App 本身就是 Tauri 应用：Tauri 壳加载 webui/ 并拉起 Python sidecar。启动方式：

uv run python run.py     # 开发者启动器（推荐）：检查 Python 依赖 + Tauri CLI 后执行 cargo tauri dev
cargo tauri dev          # 等效命令：依赖已就绪时直接启动 Tauri 开发模式

禁止直接用浏览器打开 webui/index.html 或用 python -m http.server 等方式启动（前端必须经由 Tauri IPC 调 sidecar）。

不要与 python/main.py（sidecar 进程入口，由 Tauri 壳拉起）混淆。

1.5 依赖管理

使用 uv 管理 Python 依赖，禁止直接使用系统 pip install：

uv sync --extra dev --extra rag --extra ingest   # 安装依赖（RAG 与采集转换链默认包含）
uv run pytest                     # 运行测试

依赖声明于 pyproject.toml；uv.lock 提交入库。前端依赖走 npm（package.json）。

1.6 Git 仓库配置

• 远程仓库名：NoteAI（不是 origin），SSH 地址 [email protected]:Miles128/NoteAI.git，禁止 HTTPS 推送。
• 推送：git push NoteAI <branch-name>。
• PR 流程：推送后使用 gh pr create --base main 创建 PR，再 gh pr checks 确认 CI，形成"推送 → 建 PR → 确认 CI"闭环。

---

2. 构建与测试

uv sync --extra dev --extra rag --extra ingest   # 安装依赖
uv run pytest                     # 运行全部测试（~69 单元 + 3 集成测试模块）
uv run python run.py              # 启动 Tauri dev 模式（检查依赖 + cargo tauri dev）