NoteMeld: Instructions file for Codex

AGENTS.md

应用包由独立的 ../notemeld-applications/ 仓库维护；NoteMeld 只能消费其已构建的 manifest/UI 产物和 Application Protocol，不得把应用源码重新放回 desktop/frontend/src/。

本文件是 NoteMeld 项目中所有 AI Agent 和开发者的硬规则。任何新需求、方案、代码修改、Bug 修复、重构、接口变更、数据模型变更开始前，必须遵守。

产品范式

NoteMeld 的核心范式是：AI 编译知识，人验证和消费。对外定位是"你的 AI 研究助手"——后台运行，标记驱动，随时提供参考和来源。对内架构隐喻是"知识编译器"——Wiki-First Retrieval，管线思维，增量重建。所有改动应服务这个范式：AI 负责下载、转写、理解、抽取、构建图谱；人负责标记来源、验证结果、消费知识。详细战略调研见 docs/research/knowledge-compiler-paradigm.md。

必读文档

开始任何新需求前，必须先阅读：

• docs/system/current-architecture.md
• docs/system/product-rules.md
• docs/system/data-model.md
• docs/system/api-inventory.md
• docs/system/known-pitfalls.md

只读 README、只看用户描述、只根据记忆或猜测写方案，均不合格。

必须搜索现状

动手前必须搜索相关代码和测试：

• 相关前端页面、组件、服务调用。
• 相关后端 router、service、model、utils。
• 相关 SQLite 表、文件结构、状态文件、sidecar 文件。
• 相关契约测试、回归测试、打包脚本和文档测试。

如果找不到现状，必须继续查或向用户提问，不能猜。

禁止事项

• 不能直接生成孤立 PRD。
• 不能在不了解现状的情况下写实现方案。
• 不能凭猜测改数据库字段、接口语义或核心业务规则。
• 不能绕过 docs/system/change-spec-template.md。
• 不能只做理想化重构方案，必须基于当前真实系统。
• 不能为了局部改动删除已有能力。
• 不能做无关重构。
• 不能删除用户未明确要求删除的能力。
• 不能回滚用户或其他 Agent 的改动，除非用户明确要求。
• 不能暴露 Provider API Key、Cookie、token、用户本地路径或敏感 payload。
• 不能破坏源码启动、CLI、桌面、MCP、迁移、Wiki、上传、打包发布任一既有入口。

Change Spec 规则

所有新需求必须先产出增量 Change Spec。模板见：

docs/system/change-spec-template.md

Change Spec 必须回答：

• 当前系统现状是什么。
• 本次目标是什么。
• 明确不做什么。
• 和产品规则、数据模型、API、历史坑点是否冲突。
• 影响哪些模块、接口、数据、UI、测试和文档。
• 最小可行改动是什么。
• 如何测试和验收。
• 风险和回滚是什么。

用户明确要求“直接修 Bug”时，也必须至少在回复或提交说明中覆盖根因、影响范围和回归测试。

Bug 修复规则

Bug 修复必须说明：

• 根因。
• 影响范围。
• 复现方式或证据。
• 修复点。
• 回归测试。
• 未覆盖风险。

不能只说“已修复”。没有验证证据，不得声称通过。

文档同步规则

修改以下内容时，必须同步更新 docs/system/：

• 系统架构、运行入口、部署方式。
• 产品硬规则或 UX 行为。
• SQLite 表、字段、文件结构、状态流转、缓存和统计口径。
• API 路径、请求参数、返回结构、错误语义或调用方。
• MCP 工具。
• Wiki rebuild、任务状态、桌面 sidecar、迁移、上传、打包发布等核心链路。
• 新发现的坑点和回归防线。

最小改动规则

• 优先复用现有模块、helper、router、service、测试模式。
• 只做满足需求的最小可行改动。
• 保持已有数据兼容。
• 保持已有 API 调用方兼容，必要时提供兼容层。
• 保持旧数据、历史状态和已有文件结构可读取。
• 涉及并发、取消、超时、文件写入时，必须考虑 race condition 和脏状态。

新需求前 Agent 必答问题