项目目标

面向创作者的 AI 创作工具，支持完整创作流程与游戏交互。

设计与代码

• 一步完成功能性需求与必要验证，选择最简单完整、长期可维护的方案；到位不要求消除所有无关瑕疵。鼓励在相关职责内扩大改动以降低总代码量或复杂度，明确收益和边界；收益不成立时保持局部，不无限扩大重构。避免投机抽象、配置和临时方案，不以未完成的复杂改造破坏现有流程。
• 优先复用已有组件、抽象和依赖，先查文档与类型；成熟依赖能降低复杂度时优先采用。提示词需求优先评估 Skills，工具需求优先评估已有 Tools / Bash Execute。
• 模块按职责和变化原因组织，保持高内聚、低耦合，避免杂项包和过度拆分。高频变更文件接近 500 行、超过 800 行时分别加强职责与复杂度审查；行数是提醒，不是先拆分才能修复的门槛。在原职责内的小修复可直接完成，新增独立职责应拆分。
• 不为缩短代码新增一次性 helper；仅在澄清概念、隔离复杂逻辑、复用边界或改善测试时抽取。模块默认私有，仅暴露调用方需要的 API。
• 避免含义不清的布尔值或 nil 参数，使用具名配置、枚举或语义明确的方法。穷尽处理有限状态、事件和消息类型，不用默认分支吞掉新增状态。
• 新接口、状态类型、Agent 能力和跨模块抽象需说明职责与调用约束；涉及用户参与的设计决策，保留清楚的原因注释。
• goroutine 必须有 recover 边界，优先复用已有执行封装；恢复后记录错误并完成必要清理，不静默吞掉 panic。
• 前后端的关键操作、状态变化和失败应有可定位日志，说明操作与原因，文件和行号由日志机制提供。注释、日志、内部错误和终端固定输出使用英文。
• 遇到不熟悉的功能，不要立即从零实现。先检索 GitHub 上维护活跃、许可证明确的同类开源项目，比较实现思路、依赖和已知问题。优先借鉴经过验证的设计，不要直接复制不兼容或来源不明的代码。

产品与交互

• 写作、游戏与共通能力是并列一级菜单；点击只进入对应目的地，不维护额外全局模式，不提供模式切换器，任何时候只有一个一级菜单高亮。
• 共通能力的设计和验证必须覆盖写作与游戏，尤其是布局、导航、会话、设置和版本管理。
• 所有用户可见交互、文案、错误和空状态提供独立中英文资源，按当前语言单语展示；用户错误通过本地化 message / error key 呈现。
• UI 优先使用 shadcn/ui 和已有组件、编辑器依赖。主题以暗色黑、浅色白为底，少量红黄绿点缀；检查两种主题，使用自适应布局，避免固定宽度。
• Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.
• 列表通过点击整个父项展开或收起，不只允许点击左侧箭头。

Agent 与模型上下文

• agent/ 是独立的 Native Agent Runtime，不感知外部 runtime、产品运行时选择或多 runtime 调度。Native、Codex、Claude 等运行时的选择、适配、能力差异和共通产品控制由 Denova 应用层承担；不得通过给 agent.Definition、Session 或其执行循环注入外部 runtime 来实现切换。共通 UI 和产品 journal 可以复用，但不能因此把应用层编排职责下沉到 agent/。
• 应用层的多 runtime 能力聚合在 internal/agents/runtime 独立 package 中，不新增 Go module，也不以搬进 internal/app 代替抽象分层。产品层通过绑定会话的统一接口使用控制和状态；Native 执行与外部协议适配保持隔离，产品上下文准备和领域提交仍由产品层负责。运行时已有的 Plan/Todo 由运行时执行，应用只保存已确认的快照并复用展示组件，不提供第二套可写 Todo 工具。原生能力优先，但应权衡协议适配成本，不能为了统一表面行为扩大实现范围。
• 游戏不支持 Goal，UI、API 与执行层均不得开启 Goal。写作和通用对话可统一 Goal 的产品入口与状态展示，但 Native Goal 的执行和验收由独立 Native runtime 负责，不能与外部 runtime 的执行实现混合。
• Denova 内置的提示词、上下文片段、工具与 schema 描述、模型可见工具反馈统一使用英文，不重复注入双语；保持产品中立，不提及或类比其他 Agent 产品、CLI 或品牌。对照研究仅放在审计文档中。
• Skill 文档及其参考资料允许使用中文，不受内置提示词的英文限制。
• 上下文改动优先保护缓存前缀匹配；每个注入片段必须有明确来源、用途和容量上限，上限应覆盖合理使用规模，并明确超限处理，避免随意截断。
• 模型输出与工具输入 schema 应容忍可修正的错误；列表操作尽量支持逐项成功或失败，避免局部错误导致整批昂贵重试。
• LLM 任务默认不限总运行时间和迭代次数，不写死强制中断上限；确有安全或循环控制需求时提供可配置限制，并保留用户取消能力。连接建立、测试等待等基础设施边界不属于 LLM 总运行时长限制。

API、配置与用户数据

• 受管素材目录按使用场景和归属组织，一个目录不混放不同场景：书籍封面、资料库、写作素材分别维护，游戏素材按稳定故事线 ID 再分一层。文件名只负责文件存储，不编码业务关系，也不用于推导素材身份；属性和关联优先沿用业务记录，仅缺少承载位置的额外信息按需保存目录元数据。
• Beta 只保护最近一个 Release 的用户数据，必要时做小而明确的前向迁移；不支持程序降级，不保留降级转换、双写、内部 API、代码契约或未发布中间格式的兼容性。迁移备份用于失败恢复。
• 新功能或较大变更需评估用户是否需要配置；仅在有实际控制需求时增加，并明确默认值、作用域和持久化位置，区分用户配置、工作区配置和运行时状态。
• 修改 API、配置加载、工作区结构、会话或版本恢复、文件命名时，检查前后端调用点与数据迁移风险。API 边界结构保持稳定、字段一致，重命名同步修改调用方，不暴露后端内部结构。
• 用户内容的自动迁移、重命名、删除和覆盖必须有可回滚路径或明确备份。

.denova 数据可移动性不变量

• .denova 内的受管 Project 必须以稳定 ProjectID 作为身份；显示名、DataRoot 和运行时绝对路径不得参与持久化 identity、key 或恢复定位。
• 受管 Project 的 location 及 .denova 内文件引用必须持久化为使用 / 的规范相对路径；宿主绝对路径只能在运行时投影，不得写入 Registry、Session、metadata、automation、receipt 或其他恢复事实源。External Project 路径保持不透明，不承诺跨系统可用。
• stores/<store_dir> 中的 store_dir 创建后不可变；Project 改名、DataRoot 搬迁或 External Project relink 不得移动或重新分配已有 Project Store。
• Denova 创建的 .denova 内文件名必须符合 Windows、WSL、Linux、macOS 的共同规则；业务数据不得包含符号链接、特殊文件或大小写折叠后冲突的路径。
• 宿主专属 shell 或工具路径在当前系统不可用时，应回退到当前宿主默认值，不能阻止数据目录加载。
• .denova 格式变更只为最近一个 Release 提供小而明确、可重试且先备份的迁移；不要为此增加 dual-write、旧根目录 rebasing 或通用 VFS / StorageRef 抽象。
• 一个逻辑 Agent Session 只能有一份 canonical journal：Writing/Chat/Image/Automation 使用其 Product Session JSONL，Game 使用其 Story JSONL，持久子 Agent 在同一 Project Store 下各自使用一份自包含 journal。Goal、Todo、Clear、Cleanup、Compaction 等恢复状态必须以版本化记录写入该 journal；.idx.json 和 runs 只能是可重建索引与诊断数据，不能成为恢复事实源。

开发环境与进程

• 首次执行时识别当前仓库、Shell、工具链和目标平台；环境变化时重新核对，启动、重启服务或占用端口前检查对应进程与端口。macOS、Windows 原生和 WSL 分别处理；WSL 使用 Linux 工具链，Git Bash 不等于 WSL。命令、路径和环境变量语法必须匹配当前环境。
• 人工验证复用已有前端热更新；更新后端只操作当前仓库的后端。使用下列入口或等价的可见前台命令，不以 launchd、nohup、后台守护或自动重拉方式管理服务，不另起重复开发实例。

• restart-dev.ps1 会停止前后端进程树，仅在确需整体重启时使用，不作为仅重启后端的替代。操作进程前确认其归属，不干扰其他仓库或环境的实例。
• 仓库自动化测试入口可管理隔离测试服务：使用独立数据与端口，负责退出清理，不复用开发后端或真实 DENOVA_DIR。人工验证允许使用用户默认模型配置。

测试与构建

• 按行为影响选择必要检查；通过后仅因新改动、失败或未解决风险扩大或重复验证。纯文档调整做相应静态检查，不运行程序测试或构建；发布和大范围集成改动需完整构建。
• 修复 bug 先写复现测试或最小验证步骤。Agent 主流程、工具调用、上下文裁剪、会话与版本恢复、工作区状态变更优先集成测试；纯函数、解析器和小型状态转换用单元测试。
• 测试放在既有结构或独立测试文件，比较完整结构或关键行为；不为静态常量、已删除逻辑或复述实现增加测试，不暴露生产代码专用测试入口。单项单元测试不得因低效实现超过 3 秒，计时不含编译和依赖下载。
• 前端可见变更必须打开页面验证；布局变化时检查窄屏、宽屏、长文本和空数据。核心重构或较大前端改动需回归写作与游戏核心链路。开发优先应用内浏览器，系统验证用 Playwright，需要真实登录态用 Chrome；工具不可用时使用等价能力并说明未验证项。
• Go 有根目录与 agent/ 两个 module：小改动先对受影响 package 运行 go test、go vet；跨 package、持久化或核心流程变更扩大到相关 module 的 go test ./...、go vet ./...，全量与发布验证覆盖两者。仅依赖变更时在相关 module 执行 go mod tidy 并检查 diff；清单核验用 go mod tidy -diff，不作为每次编译前的固定修改步骤。
• 前端入口为 pnpm --dir web test:unit、test:browser、test:e2e，全量用 pnpm --dir web test；本地化检查用 pnpm --dir web check:i18n。命令定义以 web/package.json 为准。
• 编译检查不等于完整打包；完整构建需包含主程序、updater、前端与内嵌资源、Skills 和 ripgrep。路径、文件锁、进程、PTY、安装和更新等平台相关改动需目标环境验证；交叉编译或 WSL 通过不代表 Windows 原生运行通过。
• 最终简明说明改动、结果和实际验证的平台、检查项；无法自动化或缺少目标环境时说明手动范围、未验证项与风险。

文档与发布

• 除非用户指定，文档默认放 docs/。代码、测试和本文件的长期不变量是事实源；旧文档不得覆盖本文件的不变量。只保留仍有独立阅读价值的文档，及时删除已被实现覆盖的设计稿。
• CHANGELOG.md 的 Unreleased 以最近 Release 为基线，只记录重大用户功能、已发布核心流程的重要修复和已发布用户数据的不兼容变化；不记录内部重构、测试、文案、细节 UI 或未发布格式变化。遵循 Keep a Changelog，保留简短中英文摘要，发布前压缩。
• 发布时同步 web/package.json 与 desktop/package.json 版本号、CHANGELOG.md、README.md、README.en.md 并创建对应 Git tag；GitHub Release notes 简述用户可感知变化，不复制完整 changelog。Desktop 仅构建 macOS arm64 与 Windows x64，原生构建和签名要求见 docs/desktop-distribution.md。
• PR 标题与 Commit Message 使用英文。

LESSONS

从实际开发和用户纠正中更新本节，只保留反复出现的问题模式或有依据、可迁移的判断原则；不记故障与修复流水账，不重复已有规范。

按主题用二级标题分组，每条用一行列表写明原则及行动或理由，总计最多 30 条；合并重复、淘汰过时或低价值内容，满额先精简再新增。

业务流程与状态

• 新增入口复用完整业务流程：接入已有功能前，先找齐前置检查、状态提交和收尾副作用；只复用底层调用容易绕过业务约束。
• 状态变化要追踪到所有读取方：沿缓存、索引和界面投影检查失效与重算，用重新读取的结果确认变更已经生效。
• 默认配置只是初始建议：仅补齐未选择项，不用推荐资源搭配限制创建或覆盖用户明确选择、禁用与清空的配置。

性能与并发

• 性能按累积成本判断：把数据量、单项大小和重复次数一起估算，再用长会话与冷启动验证，避免局部优化掩盖整体退化。
• 生命周期要按交错顺序推演：检查取消、切换、恢复与退出相互穿插时的操作归属和资源释放，顺序执行成功无法证明并发正确。

外部协议

• 协议兼容以真实往返为准：用真实报文贯通流式响应、工具续轮与恢复，确认语义和必要元数据在适配前后保持一致。