贡献

AISCouncil 欢迎在多个领域做出贡献：模型注册表、翻译、文档、小程序和核心代码。本指南涵盖每个贡献路径。

贡献领域

领域	难度	文件	验证
模型注册表	简单	`registry/models.json`	`python3 registry/validate.py`
翻译	简单	`registry/locale/{lang}.json`	`python3 registry/locale/validate_locale.py`
文档	简单	`doc.aiscouncil.net/site/docs/`	使用 `npm start` 本地预览
小程序	中等	`manifest.json` + `index.html`	`python3 registry/validate.py packages`
错误修复/功能	中等-困难	`src/.js`, `modules//index.ts`	`./build.sh && npm test`

模型注册表

模型注册表（registry/models.json）是社区维护的 LLM 提供商和模型列表。添加新模型是最简单的贡献方式。

添加模型

Fork 仓库
编辑 registry/models.json —— 在适当的提供商下添加您的模型
验证：

python3 registry/validate.py

提交拉取请求

模型条目格式

每个模型需要这些字段：

{
  "id": "model-id-from-provider",
  "name": "Human-Readable Name",
  "provider": "provider-id",
  "context": 128000,
  "maxOutput": 8192,
  "pricing": { "input": 3.0, "output": 15.0 },
  "capabilities": ["streaming", "vision", "tools"],
  "tier": "paid"
}

验证脚本检查：

有效的 JSON 结构
所有必需字段存在（id, name, provider, context, maxOutput, pricing, capabilities, tier）
无重复的模型 ID
能力来自允许的集合：vision, tools, streaming, json_mode, reasoning, code
层级来自允许的集合：free, paid, enterprise

提示

查看 models.json 中的现有条目作为示例。匹配格式样式（2 空格缩进，字段顺序相同）以获得干净的差异。

翻译

应用程序使用社区贡献的区域设置文件进行国际化。每个区域设置文件翻译向导和 UI 字符串。

添加或更新翻译

将 registry/locale/en.json 复制到 registry/locale/{lang}.json（使用 ISO 639-1 代码：es, zh, ar, fr 等）
翻译所有字符串值（每个键值对的右侧）
更新 _meta.lang 和 _meta.name
验证：

python3 registry/locale/validate_locale.py registry/locale/{lang}.json

提交拉取请求

翻译规则

要翻译： 所有字符串值和 _meta.name
不要更改： 键名、_meta.lang 代码、_meta.version、{花括号} 内的模板变量

像 {name}, {count}, 和 {error} 这样的模板变量在运行时被替换。保持它们与英文源中显示的完全一致。

{
  "_meta": {
    "lang": "es",
    "name": "Espanol",
    "version": 1,
    "module": "wizard"
  },
  "createProfile": "Crear Perfil de IA",
  "operator": "Operador: {name}",
  "modelsSelected": "{count} seleccionados:"
}

信息

请参阅 registry/locale/TRANSLATING.md 获取完整的翻译指南，包括字符编码规则和优先语言。

目前需要的语言

英语、西班牙语、中文、阿拉伯语、法语、葡萄牙语、日语、韩语、德语和俄语有完整翻译。仍需要以下语言的翻译：印地语、土耳其语、乌克兰语、泰语、波兰语、意大利语、荷兰语、印尼语和越南语。

文档

文档位于 doc.aiscouncil.net/site/docs/ 的 Docusaurus 站点中。

编辑文档

在 doc.aiscouncil.net/site/docs/ 中编辑或创建 Markdown 文件
本地预览：

cd doc.aiscouncil.net/site
npm install
npm start

如果添加新页面，在 doc.aiscouncil.net/site/sidebars.ts 中注册它
提交拉取请求

文档约定

使用带有 sidebar_position, title, 和 description 的前言
使用 :::tip, :::info, :::warning 标注作为提示框
使用表格进行结构化比较
在适用时包含命令示例
保持文字直接简洁

小程序

小程序是通过 iframe 在 AISCouncil 平台内运行的沙箱 Web 应用程序。

创建小程序

创建 manifest.json：

{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "My App",
  "description": "What my app does",
  "entry": "index.html",
  "base_url": "https://your-cdn.com/my-app/",
  "permissions": ["storage"]
}

使用 window.ais SDK 创建 index.html：

<!DOCTYPE html>
<html>
  <body>
    <h1>My App</h1>
    <script>
      ais.ready(() => {
        ais.ui.toast("Hello from my app!");
      });
    </script>
  </body>
</html>

在任何 CDN 上托管您的文件（GitHub Pages, Cloudflare Pages, Vercel）
通过清单 URL 本地安装测试：

AIS.MiniPrograms.install("https://your-cdn.com/my-app/manifest.json");

发布到注册表

将您的应用条目添加到 registry/packages.json
验证：

python3 registry/validate.py packages

提交拉取请求

请参阅 SDK 文档和 sdk/ais.d.ts 获取完整的小程序 API。

提示

examples/hello-world/ 目录包含一个完整的工作小程序，您可以将其作为起点使用。

代码贡献

开发设置

git clone https://github.com/nicholasgasior/bcz.git
cd bcz
npm install
./build.sh
npm test

编辑-构建-测试循环

在 src/ 中编辑源文件（永远不要直接编辑 index.html）
构建：./build.sh
测试：npm test
验证：./build.sh --check

对于 TypeScript 模块：

编辑：modules/{name}/index.ts
类型检查：npm run check
构建：./build.sh（自动编译 TypeScript）
测试：npm run test:modules

代码风格

代码库遵循严格的约定。在提交代码之前查看这些：

无外部依赖。 浏览器包仅包含原始 JS 和可选 WASM。运行时没有 React、没有 jQuery、没有 lodash、没有 npm 包。

语义 HTML。 使用 <dialog> 作为模态框、<details> 作为可折叠项、<output> 作为实时区域、hidden 属性作为可见性。在编写 JS 之前先使用原生 HTML 元素。

无类 CSS。 通过 ID、语义标签或 data-* 属性定位元素。仅对以下情况使用类：状态切换（.active, .collapsed）、动态 JS 组件（.council-member-row）和实用简写（.f1, .sc）。

/* 好：语义选择器 */
#messages > article[data-from="user"] { ... }
article menu button { ... }

/* 避免：重类选择器 */
.message-container .message--user .message__actions .btn { ... }

14px 最小字体大小。 所有文本必须至少为 14px。这确保与 UI 交互的视觉 LLM 的可读性。

VLM 友好的点击目标。 交互元素必须至少 48px 高度。切换开关为 44x24px。这使 AI 视觉模型能够通过坐标点击元素。

新模块使用 AIS.lazy()。 所有非核心模块必须使用延迟水化模式。工厂函数仅在首次访问时运行：

if (!AIS.MyModule)
  AIS.lazy("MyModule", function () {
    "use strict";
    // 模块代码
    return { publicMethod };
  });

事件委托。 在容器元素上附加单个监听器，而不是每个子元素上的单独监听器：

// 好：带委托的单个监听器
container.addEventListener("click", (e) => {
  const btn = e.target.closest("[data-action]");
  if (btn) handleAction(btn.dataset.action);
});

// 避免：每项监听器
items.forEach((item) => item.addEventListener("click", handler));

零轮询。 没有 setInterval，没有 requestAnimationFrame 循环用于非动画工作。使用事件驱动更新和页面可见性 API。

被动监听器。 所有不可取消的事件处理程序使用 { passive: true }：

window.addEventListener("resize", onResize, { passive: true });

Worker 测试

Worker 代码有自己的测试套件：

cd worker
npm install
npm test

Python 工具

Python 仅用于验证和构建脚本 —— 永远不会发送到浏览器：

# 验证模型注册表
python3 registry/validate.py

# 验证包注册表
python3 registry/validate.py packages

# 验证清单文件
python3 registry/validate.py manifest path/to/manifest.json

# 验证区域设置文件
python3 registry/locale/validate_locale.py registry/locale/es.json

拉取请求流程

Fork 仓库
为您的更改创建分支（例如 add-model-deepseek-v3, translate-hindi, fix-streaming-bug）
按照上述约定进行更改
运行验证和测试：

# 对于注册表更改
python3 registry/validate.py

# 对于代码更改
./build.sh
npm test
./build.sh --check

# 对于区域设置更改
python3 registry/locale/validate_locale.py registry/locale/{lang}.json

向 main 分支提交 PR，并清楚描述更改了什么以及为什么

信息

仅注册表更改（模型、包、翻译）不需要构建或运行完整测试套件。只需运行相关的验证脚本。

获取帮助

对于错误或功能请求，请打开 GitHub issue
查看现有文档 doc.aiscouncil.net
查看仓库根目录中的 CLAUDE.md 获取完整架构参考

贡献领域​

模型注册表​

添加模型​

模型条目格式​

翻译​

添加或更新翻译​

翻译规则​

目前需要的语言​

文档​

编辑文档​

文档约定​

小程序​

创建小程序​

发布到注册表​

代码贡献​

开发设置​

编辑-构建-测试循环​

代码风格​

Worker 测试​

Python 工具​

拉取请求流程​

获取帮助​