Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
51 lines (37 loc) · 4.28 KB

CONTRIBUTING.md

File metadata and controls

51 lines (37 loc) · 4.28 KB
Raw

参与言的开发

中文 · English

欢迎一起写言。动手前花几分钟读完这页，PR 会照这里的取舍来审。

流程

  1. 小修（错字、明显的 bug）直接提 PR；新功能或较大的改动，先开 issue 说想做什么、为什么，免得写完才发现方向不合。
  2. fork 仓库，从 main 拉分支，改完向 main 提 PR。
  3. CI 的「单测 · 类型 · 格式」与「端到端」两项须绿；macOS 测试目前只作参考。
  4. 维护者看过才合并，合并一律 squash，一个 PR 落成 main 上的一次提交。

本地跑起来

只需要 Node 22 及以上，没有 npm install 这一步。

npm start          # 起本机桥接并打开浏览器（http://127.0.0.1:8787）
npm run unit       # 单元测试，几秒跑完
npm run check      # 类型检查（tsc --checkJs，临时装进不入库的 node_modules）
npm run format     # Prettier 统一格式，提 PR 前跑一次
npm test           # 单测 + 端到端；端到端要本机有 Edge 或 Chrome，按 Windows 写

源码没有构建步骤：桥接按路径顺序把 prompts/、src/、styles/ 即时拼起来，改了刷新就生效。目录分工与拼接规则见 代码结构与开发。

项目的取舍

  • 轻，不做浪费性设计。 言是少数人自己用的 Agent 壳子，不为想象中的大众补功能。浏览器或系统已经给了的（分屏、窗口、标签页）不在言里再做一遍；手机端与触屏不做。
  • 一种能力只留一条路。 能被更通用的方案覆盖的，不另开一条并列的路；有了更通用的，旧路拆掉。
  • 先调结构，再加模块。 要一样新能力，先看放宽或调整哪条现成的约束能让它自然落出来；确实不行，才新增并列的模块。
  • 不做防御性限权。 不为「可能出错」多加一层确认、开关或上限：用户下令前就明白后果，兜底的是沙箱与审查。
  • 不为个别模型的毛病专设机制。 某个模型退化、不守格式，是模型的事；要兜底，就找对所有模型都成立的设计。
  • 零依赖、无构建。 不加 npm 运行时依赖，不引入打包或转译。确实要用的第三方库放进 vendor/，先在 issue 里商量。
  • Windows 为准。 macOS 只求能用：开网页、开文件、收进程树、找浏览器这类碰系统的事一律走 server/platform.js，别各处另写。Linux 不做。
  • 新功能先找登记表。 工具、模型接口、设置栏、文件种类、正文嵌件……扩展言的口子都是一张表，加一样东西只加一份登记；哪张表都不是，先立表再落第一份。各表在哪见 代码结构与开发。
  • 一段对话同一时刻只一页写。 几处页面同开，由租约定谁写，别处只看；多页同写的问题纳进这条规矩解决，不靠合并兜底。状态归页面，桥接只作裁判与转发，不托管对话。
  • 提示词只写必要的。 判据是「不写这句，模型就做不到吗」。性格训诫、结构已经解决的叮嘱都不写；改 prompts/ 前读 prompts/README.md。
  • 界面文字中英两份。 给人看的字写成 t("中文原文")，新加的字在 i18n/en.js 补译文（test/i18n.mjs 会列出漏翻的）；给模型看的提示词不译。
  • 界面文字文白相杂、产品化。 按钮用完整的词，不写「点击可…」这类教人用的句子；讲机制、教用法的放进「设置 → 文档」。同一样东西只用一个叫法，已有雅称的用雅称。
  • 文档中英两份一起改。 docs/ 与 docs/en/、README.md 与 README.en.md 对应着改。
  • 视觉要统一。 言是纸墨一路的风格，改界面的 PR 请附改前改后的截图。每一块只有一件自己的标志元素（听音的圆相、游目的一笔朱竖），其余照全局的语汇，不把一个意象铺满整块。

提交说明

中文、英文都可以。一次提交只做一件事，开头点明大类（如「修复：」「测试：」「文档：」或 fix: docs:），说清改了什么、为什么。

许可

言以 Apache-2.0 发布。按许可第 5 条，你提交的贡献同样以 Apache-2.0 授权，无需另签协议。