写代码的规矩

这个仓库写代码的规矩：判断交给模型、护栏交给代码；提示词里不写示范句；一类东西只有一张登记表；修好一类 bug 留一道守卫；不为了新功能砍掉旧的。

判断交给模型，护栏交给代码

• 一句话是不是指令、急不急、是不是在叫它做事，由模型判断，不写关键词表、正则去触发执行。
• 确定性的代码只做护栏：权限、确认、限流、审计。模型没给判断（出错、超时、没额度），一律当成不是指令。
• 不可逆的操作照样要确认。

提示词里不写示范句

提示词里只写核验过的事实和原则，不写「比如可以说……」。示范句会被模型当台词，开头一字不差地照搬。规矩细节见 3.23。

一类东西只有一张登记表

产品名（product.json）、配置项的中文名（webui_frontend/src/lib/labels.ts）、动作目录（actions/catalog.py）、插件能力表……每一类只登记在一个地方，再配一条测试，让「漏登记」直接变红。

修好一类 bug，留一道守卫

• 修之前先拿到真实的失败输出；修的是根因，不是重试、sleep、放宽超时。
• 留一条测试（或者关卡脚本），在旧代码上红、在新代码上绿；先证明它真的会红。
• 改完跑整套测试，看退出码，不看过滤后的输出（3.4）。

测试

• 测试名用中文写出行为和预期，比如 test_他已经回了_不撤_补一条星号正字。
• 测试数据全部是合成的（tests/fixtures/personas/partner.toml），不碰任何真人的聊天和编号。

注释和模块

• 模块开头写「合同」：管什么、原则、边界、为什么这样。
• 注释写原因和吃过的亏，不复述代码；跟周边代码的语言、密度一致（这个仓库的注释是中文）。

给人看的字

• 界面上给用户看的字全部中文；不出现英文代码、原始的枚举值、配置键名。
• 页面上只放标签、数值、状态、按钮、错误；需要解释的，统一放进「使用指南」。
• 读不到就说读不到，不显示成 0；出错照实说，不吞掉。

隐私和身份

• 提交前跑 scripts/privacy_gate.py source、scripts/secret_gate.py source、scripts/brand_residue.py。
• 正式版只认编进程序里的东西（更新地址、公钥、构建信息）：磁盘上的文件和环境变量改不动它；开发用的开关只在开发版生效。
• 借鉴别的项目：先在对方源码里核实，只借做法、不拿外观，在工程笔记里写明出处，配上测试。

不为了新功能砍旧的

不为了让新功能好做，去掉已有的能力（服务器管理的广度、多服务器的隔离、安全检查、像真人的对话）。

没做到的

• 这些规矩大部分靠测试和关卡守着，还有一些（注释写原因、页面不放说明文字）只能靠评审。
• 代码格式只配了 ruff 的一部分规则（pyproject.toml 的 [tool.ruff]）；持续集成里会跑 ruff check，但仓库还没公开，持续集成还没跑过；本地没有提交前的钩子，要自己跑。