参与贡献

本页写给要改框架代码、测试或本站文档的人。只想编写扩展包的读者，先看四档扩展模型与分发包与包结构；只想把项目跑起来，先看快速开始。

开始之前

设计文稿是项目内部的最高设计约定，只在开发者本机保留，不进入仓库，也不随本站发布。接口、判据或名词的改动，必须先经开发者授权修改设计约定，再改代码；代码不得先于其所属阶段在设计约定中的登记而存在。

仓库与本地环境

事项	说明
代码仓库	https://cnb.cool/CyberNova2333/weftale
运行时	Node.js 24.x；Rust 稳定版 1.82 及以上
额外目标	rustup target add wasm32-unknown-unknown（acgcore 离线编译需要）
环境细节	见环境与依赖；安装与构建见安装、运行与构建
先跑通	提交前先在本机完成一次完整构建与测试，不要只看代码判断正确性

语言与措辞

对象	要求
文档、注释、提交正文、面向用户的报错	一律中文；句子骨架与叙述不得用中英混排替代
代码标识符	变量、函数、字段、类型、文件名保持英文
专有名词	统一用「输入源」「翻译层」「数据包」「资源包」「插件」「Mod」「大插件」「小插件」「机制插槽」「实现位」「写边」「policy」
实现状态	只用「已完成／测试中／实现中／未实现」；「已完成」指网页与宿主两端的契约测试都通过
外部内容	不写针对某个具体外部内容的说明；描述一律使用本表列出的中性术语

分支与提交

分支

• 直接推 main，不开长期特性分支，不走拉取请求流程。
• 不向以 Agent 名称命名的分支推送；本地开发使用仓库的正式分支。

粒度

• 一个功能一条提交：不要把无关修复、格式化或文档改动混进同一条提交。
• 提交时 npm test 必须全绿；动了 src-tauri/ 的提交还必须编译通过。
• 连带修掉的其他问题要在提交正文中说明，不要沉默夹带。

提交标题

类型(范围): 中文描述

类型	用途
feat	新功能
fix	缺陷修复
chore	构建、依赖、杂项维护
ci	流水线配置
test	测试与夹具
docs	文档
refactor	不改变外部行为的重构

提交正文

正文至少写清楚四件事：改了什么、为什么改、有没有连带修掉别的东西、还有什么需要人来做。没有依据的字段一律省略，不要用「这里大概该有个字段」式的猜值填充。

署名与签名

• 提交的作者是仓库主本人；AI 助手只以 Co-authored-by 尾注署名，只写通用名，不写具体模型档位、版本号或会话链接。
• 每条非初始提交必须使用 SSH 签名；未签名提交会被拒绝。
• 禁止使用 AI 助手的通用签名密钥；需要生成密钥对时，私钥只留本机，只把公钥交给仓库主登记。
• 不要改动既有提交的作者与署名。

红灯协议

仓库带有本机提交护栏（guardrails/），在提交信息、提交内容与推送三个环节做检查。出现以下情况视为红灯，必须停下来修根因，不得绕过：

红灯	正确处理
提交信息或内容被护栏拦截	按提示修改措辞、移除敏感信息或补全署名，再重新提交
未签名或使用通用密钥签名	配置并登记自己的 SSH 签名密钥，重新签名
推送被拒绝	检查是否推向了不允许的分支；整改后重推
测试未全绿	修复或撤回该提交，不带着红灯继续叠加改动

禁止使用 --no-verify、-n、--no-gpg-sign、改写 core.hooksPath 等方式跳过检查；也不要提交任何令牌、密钥或访问凭证。

测试门禁

改动范围	至少通过
任何提交	npm test、npm run typecheck
src-tauri/	cargo test --manifest-path src-tauri/Cargo.toml --features debug-channel，并确认编译通过
acgcore/	cargo test --manifest-path acgcore/Cargo.toml --offline
宿主行为、原生路由、文件写出	按 test/host/ 下各脚本开头的说明启动调试版宿主并执行冒烟脚本
仅网页端行为	npm run test:node 与 npm run test:web 可分别定位，但最终仍以 npm test 为准

• 契约测试必须在网页与宿主两端各跑一遍；单端通过不能记为「已完成」。
• 路径、参数、权限或写出规则改完必须实跑；编译通过、自测通过、契约测试与真机验证分别记录，不互相代替。
• 没有系统 Edge 的环境可用 ADV_TEST_BROWSER=webkit|chromium|firefox 选择 Playwright 自带浏览器；网络受限环境按 README 的测试说明处理代理与回环地址。

接口与名词变更

接口与名称是公开承诺，改动按以下顺序进行：

1. 先改设计约定：把新增接口、字段、错误码或名词变更报给开发者，经授权后在设计约定中登记；不得先写代码再补登记。
2. 再改契约：更新对应大插件的 contract.ts 与入口实现。
3. 同步文档：更新本站相应页面；接口命名规则见接口命名规范。
4. 补契约测试：两端都跑通，并覆盖拒绝路径与原因码。
5. 不预留空名字：不为「以后大概会有」预留空插件、空接口或空实现位；有真实实现时再加。

新增的「禁止／不得」类约定必须同时给出替代路径或理由，二者皆无视为未完成登记。

依赖与第三方内容

• 运行时依赖保持最少；新增依赖前先说明必要性并取得开发者同意，版本固定。
• 引入第三方组件时确认许可兼容，并把许可原文放到仓库约定的位置；详见许可协议。
• 仓库只放框架自己的东西：不提交任何第三方剧本、素材、音视频、安装包或派生数据包；测试夹具只用自己编写的最小数据。
• 发现版权内容误入仓库时，直接告知开发者，不要自行传播或继续加工。

文档贡献

• 本站使用 VitePress，页面放在 docs-site/；每页以一级标题开头，可用 frontmatter 写 title 与 description。
• 内部链接使用绝对路径且不带 .md，只链接站点地图中存在的路径；相关页面互相链接。
• 用表格、步骤与要点重写内容，不逐字照抄设计文稿；图示只用表格、列表或纯文本树。
• 修改后执行 npm run docs:build 验证构建；文档与代码不一致时，以代码与测试为准，并通过反馈渠道告知维护者。

提交前检查清单

• [ ] 本次改动只做一件事，提交粒度合适
• [ ] 文档、注释与提交正文为中文，标识符为英文
• [ ] npm test 与 npm run typecheck 全绿
• [ ] 涉及 src-tauri/ 或 acgcore/ 时对应 Rust 测试通过
• [ ] 接口或名词变更已在设计约定中登记，契约测试两端通过
• [ ] 本站相关页面已同步，内部链接可构建
• [ ] 没有第三方内容、密钥、内部端点或本机绝对路径
• [ ] 提交标题符合 类型(范围): 中文描述，提交已 SSH 签名
• [ ] 没有使用任何跳过检查的开关