briefloop: Instructions file for Codex

BriefLoop 开发约定

这是本地研究与报告工具，产出企业内部可读、可核查的报告。界面上的主 Agent 叫 BriefLoop：负责对话、研究规划、写稿与修订，模型用主链配置；Evaluator、Wiki Maintainer、Skill Proposer 三者独立运行，可分别指定模型。目标：重要结论可追溯，草稿持续可编辑，正式交付与独立审阅和证据版本绑定，通过既有 WikiSkill 学习已核实的修订。

• 若存在 private_planning/PLAN.md，以其中的最新用户决定为准；普通 clone 以本文件和 README 为准。旧项目的阶段、审批和测试约定不自动继承。
• 实现真实可操作的网页和后台 agent 执行，不把手动 JSON 或 mock 当成完成。
• 前端新增功能直接写进 frontend/ 下的新模块（工厂函数注入依赖，参考 schedules.js、app-updates.js 的写法）；app.js 只保留全局状态、启动与组装，不再整块增长。
• 保留精简 SQLite ControlStore、来源、稿件版本、评分绑定和恢复；不复制旧 mandatory Auditor/Editor/Claim Ledger 流程。
• BriefLoop（主 Agent，代码中也叫 Orchestrator）和实际 agent 负责规划、研究、写作、评分；Python 负责工具、进程、存储、确定计算及既定选择规则。
• 用户原稿/修订可见；低分不隐藏稿件，普通工作稿始终可下载。正式交付不能豁免确定重大错误、核心证据缺口或未决重要冲突。Wiki 是经验，不是当期事实来源。
• Reviewer 独立只读核对实际产物、原件与本任务历史，不自行重跑分析、补搜或改稿；权限由选定宿主实际落实，缺能力不得用提示词冒充隔离。
• 复用现有 jobs/events/Store 和一次自动修订；来源正常更新与原稿错误分开。审计包由用户单独选择导出，不含凭据和隐藏推理，含各材料的定位与校验结果。
• 默认 Scout/Analyst 可演化，但角色/技能/评价接口可扩展。K 在报告反馈页调整，默认 1。
• 只保留必要测试，不追求覆盖率、千级旧回归或状态组合矩阵；细则见下方“测试”。
• 哈希只用在内容会在别处变化、且变化要被发现的地方：来源与稿件版本绑定、下载与发行工件、导出输入、交给 agent 可写目录的文件、审计包和缓存键。不给只由 BriefLoop 写入 SQLite 的记录再存一份自身哈希并在读取时核对；那只能防住不会发生的事，也拦不住真正能改库的人。
• 不覆盖旧仓库和用户改动；外部代码保留许可证与来源说明。
• 凭据/运行数据/详细计划不进 Git。公共安装不能依赖个人绝对源码路径。
• 普通本地实现及必要修复已获授权，不逐步请求批准；外发、发布和新付费服务另计。

代码与文案

• 同一限制只在最相关的位置写一次。README、文档和界面只写用户必须知道的限制，不逐段追加“不代表/不等于/不证明”。
• 提示词写角色目的、判断标准和交付物。工具参数、字段格式和取值范围写在工具定义或 schema 里，由程序校验，不在提示词里重复；能用肯定句说清的不写成禁止句。
• 兼容只针对已发布版本写入过的数据（以发布标签为准）。开发中、未发布的格式直接改，不留 legacy 分支、版本常量或对应测试。
• 代码单行不超过约 160 字符（提示词和界面文案的正文段落除外），不用分号把一长串语句塞进一行；SQL 分行写。新增函数超过约 150 行时拆开。frontend/app.js 不再加功能，见上文。前端测试取函数用 tests/source_section.mjs 的 section/statement，不要假设一个函数只占一行。

测试

测试数量不是交付证据。2026-10 已删除约 1,500 个只复述实现的测试，不要再写回来。

• 写测试前先问：实现改错了，这个测试会失败吗？ 如果只在改措辞、改常量、改写法时才失败，就不写。
• 不写：
  • 断言提示词、方法卡、文档、界面文案里含某句话；
  • 把代码里的常量、映射、默认值原样抄进测试再比一遍；
  • 读 app.js、index.html、CSS 或 Python 源码做字符串或正则匹配；
  • 给 experiments/、native-engine/experiment_* 和一次性脚本写测试；
  • 同一保证换几种并发、旧格式或取消时机各写一个；只留最能复现问题的那一个。
• 只为这些行为写测试：保存与版本绑定、失败恢复、选择与回退、权限与沙箱边界、凭据脱敏、引用与来源完整性、确定计算的边界情况、导出往返、Windows 等平台路径。前端测试要真正执行模块函数，不读源码文本。
• 改提示词、方法卡、文档或界面文案不需要新测试；用一次实际运行或生成结果检查。
• 新增测试前先找现有测试，能扩一个断言就不另起一个。一个 PR 新增测试通常不超过 2 个；超过时在 PR 说明里写清每个测试防的是什么错误。
• 修 review 意见时，只有问题能用真实输入复现，才补回归测试；“防止以后有人改回去”不是理由。
• 跑相关测试文件即可，不必每次跑全量；最终做一次小型真实闭环。