denova: Instructions file for Codex

项目目标

面向创作者的 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 总运行时长限制。