# 贡献者 本页面旨在为有兴趣为Jupyter AI构建新功能或修改功能的人员提供信息。 如果您想构建增强Jupyter AI的应用程序，请参阅{doc}`开发者指南 `。 ## 设计原则 Jupyter AI的维护者已经采纳了一些原则，贡献者也应遵循这些原则。这些原则建立在[Python之禅](https://peps.python.org/pep-0020/)的基础上，旨在通过让用户控制其数据来赢得用户的信任。以下列表并不详尽；维护者有权解释和修订这些原则。 1. Jupyter AI是**与供应商无关**的。Jupyter AI不区分可用模型，并为用户提供选择模型提供商的选项。如果某个功能无法与其他模型或提供商一起使用，则该功能可能特定于一个模型或模型提供商。 2. Jupyter AI**仅响应明确的提示**；它不会监视文件，也不会自动发送提示。任何监视用户文件的更改必须是可选的。 3. Jupyter AI**对聊天提示是透明的**。聊天界面和魔法命令使用开源的系统消息和提示模板，以便用户知道发送到语言模型的内容。 4. Jupyter AI是**可追溯的**；用户知道何时使用它生成了内容。当Jupyter AI生成笔记本时，笔记本会说明它是由Jupyter AI生成的。当用户在笔记本中运行Jupyter AI魔法命令时，输出单元格会在其元数据中说明它们是由Jupyter AI生成的。 5. Jupyter AI采用**以人为中心的设计**。聊天界面应看起来和感觉像通常可用的聊天应用程序。魔法命令应看起来并像其他IPython魔法命令一样工作。设置屏幕应尽量少用，并且在使用时，即使对于不精通用户界面语言的用户，也应易于阅读和理解。 违反上述原则的问题和拉取请求可能会被拒绝。如果您不确定您的想法是否适合Jupyter AI，请[提出问题](https://github.com/jupyterlab/jupyter-ai/issues/new/choose)，以便我们的维护者与您讨论。 ## 先决条件 您可以在任何可以运行支持的Python版本（包括3.12）的系统上开发Jupyter AI，包括最新的Windows、macOS和Linux版本。 每个Jupyter AI主要版本仅与一个JupyterLab主要版本兼容。Jupyter AI 1.x支持JupyterLab 3.x，而Jupyter AI 2.x支持JupyterLab 4.x。 我们强烈建议您安装[conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html)以开始在Jupyter AI上进行开发，特别是在基于Apple Silicon的Mac（M1、M1 Pro、M2等）上进行开发时。 您需要Node.js 18才能使用Jupyter AI。已知Node.js 18.16.0可以正常工作。 :::{warning} :name: node-18-15 由于与Webpack的兼容性问题，Node.js 18.15.0无法与Jupyter AI一起使用。 ::: ## 开发安装 在安装了先决条件后，创建一个新的conda环境并激活它。 ``` conda create -n jupyter-ai -c conda-forge python=3.12 nodejs=20 conda activate jupyter-ai ``` 此命令必须在monorepo的根目录（``）中运行。 ``` # 移动到仓库包的根目录 cd # 安装所有依赖项并设置开发环境 ./scripts/install.sh ``` 在默认浏览器中启动并启动JupyterLab： ``` jlpm dev ``` 您可以打开一个新的终端，并使用它来构建和推送对仓库的更改。在做出任何更改后，进入`conda`环境并构建项目。 ``` cd conda activate jupyter-ai jlpm build ``` 要更改在开发环境中安装的Jupyter AI包，请使用`dev-uninstall`脚本： ``` # 卸载所有Jupyter AI包 jlpm dev-uninstall ``` 要重新安装Jupyter AI包到开发环境中，请使用`dev-install`脚本： ``` # 安装所有Jupyter AI包 jlpm dev-install ``` 要仅安装/卸载Jupyter AI包的子集，请使用传递给Lerna的`--scope`参数： ``` # 安装jupyter_ai_magics及其依赖项 jlpm dev-install --scope "@jupyter-ai/magics" ``` ## 在服务器运行时进行更改 如果您更改、添加或删除了**魔法命令**，在重新构建后，请重新启动内核或服务器。 如果您对**用户界面**或**实验室扩展**进行了更改，请运行`jlpm build`，然后刷新浏览器标签。 ## 构建文档 `./scripts/install.sh`应自动安装文档依赖项。您还需要安装[pandoc](https://pandoc.org/)。您可以从[conda-forge频道安装pandoc](https://anaconda.org/conda-forge/pandoc)： ``` conda install -c conda-forge pandoc ``` 否则，请查看 pandoc 的[安装说明](https://pandoc.org/installing.html)。 要在本地构建文档，请运行 ``` cd docs/ make html ``` 并打开 `file:///docs/build/html/index.html`，其中 `` 是 Jupyter AI 单体仓库在你本地文件系统中的绝对路径。将此路径添加到你选择的浏览器书签中会很有帮助，以便轻松查看本地文档构建。 在做出任何更改后，请确保通过 `make html` 重新构建本地文档，然后刷新浏览器以验证更改的视觉效果。 ## 开发卸载 要卸载你的 Jupyter AI 开发环境，请停用并移除 Conda 环境： ``` conda deactivate conda env remove -n jupyter-ai ``` ## 测试 ### 集成/端到端测试 此扩展使用 Playwright 进行集成/端到端测试（用户级测试）。更具体地说，JupyterLab 助手 [Galata](https://github.com/jupyterlab/jupyterlab/tree/master/galata) 用于在 JupyterLab 中测试扩展。 安装测试依赖项（仅需一次）： ```sh cd ./packages/jupyter-ai/ui-tests/ jlpm install jlpm playwright install ``` 测试涉及与由 Github CI 生成的参考快照进行快照比较。如果你使用的操作系统不是 Linux，你需要在首次本地运行测试之前生成本地快照。为此，请执行以下命令： ```sh cd ./packages/jupyter-ai/ui-tests/ jlpm test:update ``` 要执行测试，请运行： ```sh cd ./packages/jupyter-ai/ui-tests/ jlpm test ``` 你可以在 [ui-tests](https://github.com/jupyterlab/jupyter-ai/tree/main/packages/jupyter-ai/ui-tests) README 中找到更多信息。