NoteAI: Instructions file for Codex

AGENTS.md

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

---

1. 项目规则

1.1 模块化要求

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

1.2 技术架构

• 前端：Tauri v2 + TypeScript（webui/js/*.ts，esbuild 打包）。构建入口 scripts/build-webui.mjs（npm run build:webui），产物为 webui/dist/main.js（ESM + 分包）与经典 IIFE bundle（storage.bundle.js、error-handler.bundle.js，供 index.html 在模块前同步加载）；webui/dist/ 已 gitignore，Tauri beforeDevCommand/beforeBuildCommand 自动构建。
• 后端：Python sidecar，通过 stdin/stdout JSON-RPC 与前端通信。
• 前端调用后端：统一使用 window.api 对象（定义在 webui/js/api.ts），禁止使用其他兼容层。
• 模块契约：模块仍以 IIFE 挂载 window.*（如 window.SettingsComponents、window.I18nModule），无虚拟 DOM；webui/js/main.mjs 是打包入口，动态 import 控制加载顺序。TS 类型检查：webui/js/tsconfig.json + tsc --noEmit。
• 界面风格：整体对标 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）。