---
name: neko-tail-project-preferences
description: 猫尾（Neko-tail）及 Memix 所属项目的开发偏好与规则。用于规划、实现、重构、性能优化、审查、验证和交付这些项目；以极限性能为首要要求，优先 Rust、htmx、TOML，并按项目加载授权、原生宿主、模型、数据和发布规则。
metadata:
  version: "1.2.0"
  baseline: "2026-10-26"
---

# 猫尾项目偏好

适用于猫尾以及 Memix 所属项目。它规定工程决策与交付方式；猫尾品牌界面同时使用 [neko-tail-style](https://neko-tail.wang/skills/neko-tail-style/SKILL.md)，Memix 的独立视觉体系保持其品牌约定。

公开原文：[neko-tail.wang/skills/neko-tail-project-preferences/SKILL.md](https://neko-tail.wang/skills/neko-tail-project-preferences/SKILL.md)。本版保留 2026-10-12 用户明确偏好，补入 2026-10-13 至 15 日 Sierokarte 开发基座、真实交互和跨设备回归中已验证的迭代经验；来源快照分别注明核对范围。

## 最高优先级的项目偏好

猫尾统筹任务采用任务包明确指定的猫尾主仓规则作为最高项目级规则，子仓约定补充主仓未规定事项，本技能提供通用方法与偏好。系统、开发者及当前用户明确指令始终优先。该统筹关系只适用于登记范围，不自动覆盖客户业务项目；源文件、安装副本和历史参考不会各自产生新的规则权威。

以下七项来自用户的直接要求，优先于本次收集的旧项目约定。后续任务中的明确用户要求继续优先；系统和开发者指令的层级不因技能改变。

1. **在任何情况下，都以极限性能为主要要求。** 架构、算法、运行时、I/O、部署和交互方案优先追求实际性能。功能正确、数据完整、权限正确与可恢复性是必须维持的约束；不得通过漏做工作或放宽这些约束制造更快的结果。
2. **尽可能以 Rust 为运行程序核心。** 新核心及需要更换的核心首先评估 Rust；跨平台复用领域逻辑和性能关键路径，宿主保留必要的系统接口、I/O 与 UI。语言选择须结合目标负载验证，不能把“使用 Rust”等同于性能已达标。
3. **允许小型、快速迭代的模型采用 Python 作为程序核心。** 这是有范围的例外，不扩大成所有小型服务都默认使用 Python。记录适用规模、迭代收益和性能预算；负载或规模超出预算时重新评估 Rust 核心。
4. **网页端优先 htmx。** 优先服务端渲染、语义化 HTML、普通链接与表单，再用 htmx 增强局部交互。确需客户端状态或原生 WebView 交互时使用适量 JavaScript，并以实际交互和性能需求说明例外。
5. **配置文件优先 TOML。** 新增面向人维护的应用配置首先使用 TOML。工具强制格式、交换协议和既有数据文件按实际合同处理；配置迁移保留校验、原子写入、旧值迁移和明确错误。
6. **尽量避免 Node.js、Electron 等 JavaScript 技术栈承担后端或运行核心。** 不因旧实现已经存在而将其固定为长期选型。必要的浏览器脚本、前端构建和开发工具按用途使用；保留运行时例外须说明平台依赖、实测代价和可行的替代路径。
7. **下拉菜单仅用于枚举场景；长列表通过查询专用弹窗搜索选取。** 状态、类型、模式、单位等固定枚举可以使用下拉菜单。用户、企业、组织、应用、合同等业务记录即使当前数量少，也不属于枚举，不使用下拉菜单或可搜索下拉框。查询弹窗提供关键词搜索、分页或分批加载、明确的选取与取消操作；表单显示已选名称，提交稳定标识。取消或查询失败保留原值，多选保留跨页选择；支持键盘、关闭后的焦点返回、空结果和错误提示。长列表由服务端按权限查询，不一次装入全部候选，也不将首批候选当作完整目录。

**任何项目都允许在必要时进行破坏性调整，前提是维持功能。** 可以重写、替换框架、改变目录或内部 API、清理兼容层和调整依赖，不因规模大或历史实现不同而另加确认门槛。先列明功能等价、数据迁移、调用方迁移与恢复办法；有用户数据或外部消费者时验证迁移后结果。代码结构的自由不等于删除用户原件、丢失工作区改动或扩大生产操作的授权。

## 开始工作

1. 明确用户要求的最终结果、所属工程、运行平台和已授权范围；已给出的授权持续有效，普通可逆开发与验证直接推进。提交源码、安装、部署、发布和对外通信按本次及仍有效的会话授权分别执行，历史规则中的某次授权不能搬到新任务。
2. 读取目标工程当前 `AGENTS.md`、相关开发入口及本技能适用段落；只加载任务需要的参考资料。查看当前源码、工作区差异、版本和实际运行物，避免把历史记录、迁移副本或未构建源码当作当前交付。
3. 依据下表选择专项规则。旧规则与上述直接要求冲突时以上述要求为准；专项业务限制在所属范围内继续有效。仍不能判断是否采纳的规则，列出来源、冲突和影响，询问用户，同时继续不依赖答案的工作。
4. 建立正确性与性能基线，完成实现、相关验证和已授权的交付链。必要重构直接推进，保留可检查的差异与证据。

| 所属工程或变更边界 | 继续读取 |
| --- | --- |
| SOUP / Memix、OutSystems 模型、SDK bridge | [专项规则](references/development-rules.md)中的 SOUP 段及工程当前模型/发布合同 |
| UM 或任一接入 UM 的产品 | 专项规则中的 UM 段及上游 SDK 开发文档 |
| Sierokarte、游戏辅助、原生浏览器宿主 | 专项规则中的 Sierokarte 段及客户端技能的运行/验收参考 |
| 主站、mEstimate、MegaMerge、Workspace Hub | 专项规则中对应工程段落 |
| 核对规则来源、覆盖与维护范围 | [来源记录](references/sources.toml)；其中路径相对于标明的工程根目录 |

## 性能决策与证据

- 先确定真实工作负载、输入规模、并发、硬件、运行模式和版本。按瓶颈测量延迟分布、吞吐、CPU、峰值及稳定内存、分配/复制、磁盘与网络 I/O、启动和包体；选择与任务相关的指标，不让无关指标淹没结论。
- 对同一输入和语义比较基线与候选；涉及缓存、启动或长时间运行时分别覆盖冷态、热态和稳定态。保留可复现命令、源码/构建身份、环境和原始结果，解释噪声与适用范围。
- 优先改进算法、数据布局、批处理、流式处理和不必要的跨进程/网络往返；按需要使用有界并发、背压、取消和及时释放。避免无界队列、把大文件整体装入内存、重复解析或为每一行启动昂贵调用。
- 缓存必须有失效和隔离合同；不得用过期权限、跨租户数据或跳过校验换取速度。交互优化保留已有行为、语言和无障碍支持。
- 性能收益以测量为依据。没有运行或目标环境不可用时如实报告该边界；不得声称“极限”“最优”已经证实。无法满足预算时继续定位，或明确说明尚未解决的约束及选择理由。

## 共同开发规则

**单一维护来源。** 公共领域规则放在所属核心，平台绑定尽量薄；生成物由源码与工具重建。修改接口时同步类型、schema、CLI/帮助、能力声明、示例及受影响文档，避免多个实现各自解释同一合同。

**大规模调整。** 用户要求先减后加时，先建立可维护的产品地图：分别记录功能归属、投入阶段、方向决定、实现状态与验收证据，再按可验证的场景接回能力。隐藏旧入口时检查后台启动、命令和恢复路径；保留旧源码或数据不代表仍需启动旧功能。已确定的方向不重新列为待决策，条目数量不当作完成率。客户端、业务云服务和账户/授权服务按实现及部署单元分别记账，即使同在一个仓库；功能归属、跨项目依赖与交付状态分别表达。

**快速开发基座。** 与日用安装并存的开发版分开应用身份、可写数据和更新通道。网页资源更新先核对原生基座身份，在签名包外原子替换，并从运行实例确认新页面代次、就绪状态与加载摘要；原生合同变化应重建。完整重装时归档旧热更新覆盖资源，并核对实例实际资源路径及摘要，防止新签名包继续加载同原生指纹的旧资源。共享资源的多个窗口须协调重载，避免同一进程运行不同代资源。测量工具完成与业务可用的耗时分别记录，暖构建样本不能当作冷启动性能。

**工作区与依赖。** 保留用户累计的暂存及未暂存改动，按本次范围检查和暂存；不重置无关文件。沿用工程已有组织；工作区共用工具、配置、文档、产物与素材分别归入 `.utils`、`.configs`、`.docs`、`.artifacts`、`.assets`，一次性文件使用临时目录。保留第三方许可与来源，不将私有样例、密钥、供应商二进制或临时构建产物当作普通源码提交。正式跨工程交付使用远端可取得的固定提交/版本和锁定依赖，记录实际产物摘要。

**提交与发布语言。** 猫尾和 Memix 所属全部项目的提交说明及 Release 说明使用中文。保留必要的代码标识、命令、版本号和产品原名；说明实际变化、影响及已完成的验证。

**数据与写入。** 维护稳定身份、用户原件、现有配置和迁移前恢复点。文件/配置更新采用校验后的原子替换或工程正式事务；并发修改使用版本或修订号，冲突保留用户输入。跨进程场景以真实进程、锁、崩溃及恢复验证，进程内锁不能替代这些证据。

**不确定结果。** 区分未开始、已拒绝、已提交、部分完成和状态未知。网络超时不证明未提交；先查询原请求、票据或持久化状态，保留已成功前缀，只在已证明安全且合同允许的边界重试。不重放一次性授权、消费动作或未知写入。

**延迟投递。** 长轮询、队列或其他异步等待结束后，按稳定标识重新读取当前目标与权限；等待前捕获的对象可能已被心跳或设置更新替换。持久设备登记、在线租约和通知接收许可分别建模；撤销后的旧心跳不能重新授予访问，普通续期也不能夺回已转移的凭据归属。

**授权与隔离。** 使用任务中已授权的身份和私有凭据来源，不重复索取有效授权，也不扩大到其他账号或系统。凭据、令牌、签名密钥和设备种子不写入 Git、公开文档、包或普通日志。服务端执行权限、租户隔离、CSRF/Origin 与输入约束；隐藏 UI 不能代替保护入口。接入 UM 时遵循专项规则，不能为优化另写本地成功缓存或第二套授权判定。

**入口校验。** 外部参数在入口集中校验，内部用已校验的类型或上下文传递，不逐层重校相同约束。对高概率不会触发、没有实际风险依据的假设性边界可以省略防御性代码，保留有依据的最佳实践。跨进程输入、授权有效期、可变持久状态和写入结果属于各自的边界，分别核验；不增加无实际场景的兜底、重试或错误吞并。

**诊断。** 机器接口采用稳定错误码和结构化阶段，保留原始失败而非被清理错误覆盖；跨进程证据可关联，但内容、数量与大小有界且去除敏感信息。缺失的原因或状态明确缺失，不从消息文本猜测。失败按“复现证据 → 原因 → 修复 → 相邻回归 → 剩余边界”闭环，历史失败保留为历史，不能改写成已验证成功。

桥接通道连通与业务接收器就绪是不同状态。等待就绪优先使用明确的生命周期信号；需要重试时只对明确未处理且可安全重试的调用设置次数/期限，不能把读取的重试策略套用到结果未知的写入。

**交互完成判定。** 跨页面、多步骤流程分别确认请求已受理、控件已选中、当前步骤完成和整轮完成。响应成功后仍可能出现延迟提示或必要确认，依据领域状态和实际完成控件推进，不用固定等待时间代替完成证据。消费流程确需跨文档接续时，使用绑定当前运行、身份及目标的有期限、单次交接凭据；凭据已用尽或普通手动刷新不能自动恢复消费。

控件可能在领取动作后、派发前改变。只有执行端在任何副作用前明确返回未派发，才允许按该动作合同撤销领取并重新观察；匹配当前运行、上下文和动作，不能从超时或文案推断未执行。跨页面等待从本次切换开始计时，旧步骤耗时不能挤占新加载的等待窗口。

游戏或服务明确拒绝的资源不足、次数耗尽等阻塞条件应及时结束当前执行并说明原因，保留已完成的前缀及计数；不能把已知拒绝当作未知加载持续等待。余额、消费量和消费后的预览须分别解释；本地余额预测是否拦截取决于当前产品的补充规则与用户偏好，不能把负的预览值直接当作实际拒绝。

**验证与交付。** 先运行能区分旧问题和预期结果的相关检查；文档改动检查格式、链接和发布内容，不机械运行无关平台或业务全套。源码、生成物、构建、夹具、真实渲染器、最终安装包、安装、部署、真实账号/设备及公开发布是不同证据层次。报告实际完成层次；目标环境暂不可用时完成独立工作并写明缺口。生产变更保留适用的备份、候选验证和回退手段，验收绑定最终版本。

**规则维护。** 通用教训进入本技能，业务限制留在专项参考，某次账号/环境/发布授权留在任务私有记录。当前事实只维护一个权威入口，历史与当前交接分开；引入的参考技能保留许可且按需使用，不批量覆盖业务工程的 `AGENTS.md`、全局配置或产品包。每 30 天首次维护时全目录重审的周期要求仅适用于 SOUP；其他工程按自身当前规则及任务受影响范围审查。

## 维护与分发

主站 `.agents/skills/neko-tail-project-preferences/` 是本技能唯一维护源。主文件与 `references/` 一起发布，公开索引为 [llms.txt](https://neko-tail.wang/llms.txt)；本地安装时保留同样的相对目录结构，远程读取时按主文件链接获取所需参考。

修改规则时更新版本、基准日期、受影响的专项段落和来源摘要。校验技能格式、TOML、引用链接以及构建和 HTTP 返回的原文字节；源文件更新不等于网站已经部署。新增项目先查现行规则，再按本技能的优先级协调冲突。