CONTRIBUTING.md

Rama main · réplica de lectura del repositorio original.

# 贡献

先按 [README](README.md) 准备本地开发环境，再按改动选择需要的构建和检查，不必每次运行全套。`pnpm check` 执行必要的编译、类型和语法检查，行为回归使用 `pnpm test`；CI 将两者分开运行。新增插件可复制 `plugins/builtin/dsh-example`，修改包名、插件 ID、Bundle、路由、权限及测试；通过 `plugins/builtin/*` 自动发现，不修改中央名单。独立作者参见[接入指南](doc/plugin-development.md)。

公共代码按包名引用。manager、kit、auth、example 使用根 `package.json` 的统一框架版本，定制插件独立版本管理；版本号在发版时统一确定，日常开发不自行修改。同步命令与文档模板规则见[版本管理](doc/versioning.md)。插件的运行与类型产物不得包含工作区绝对路径、`workspace:`、`file:` 或 `link:` 运行依赖。修改公共包时检查使用它的插件或项目，更新相应 README 模板并生成说明文档。

文档用自然、简单易懂的语言说明用途和操作。必要术语先解释，长段落按主题拆开；少用口号和模板套话，保留准确的命令、字段、限制与来源。表格、图表只在有助于理解时使用。

公开文档从[文档导航](doc/README.md)进入作者、部署、配置参考。能力变化需同步 example 随包 knowledge 的 FAQ/提示词；它们就是助手读取的知识，不另维护一份答案。校验来源、命令、知识大小及实际模型输入；真实模型问答与替身测试分别说明。`doc/` 仅保存当前产品的使用、开发、配置、部署、故障排查和版本资料。

设计文档、开发计划、评审报告、验收记录和临时实验存放在 `.local/{项目名}/docs/{文档类型}/`，按“设计、计划、评审、验收”等类型分类，文件使用 `YYYYMMDD-HHmmss-中文文档名称.md` 命名，由 Git 忽略，不强制加入提交；个人博客、推广与邀请材料仍放在仓库外。不要把待办或本次执行结果写入使用手册。必要的兼容条件、权限规则与数据保护要求写在对应操作处。维护者发布流程见 [.github/RELEASING.md](.github/RELEASING.md)。

逻辑变化应补充必要的行为测试；纯文档和文案修改检查内容即可。提交时说明实际验证了什么，以及哪些部分没有验证。不要提交模型密钥、`.env`、真实 `env.conf`、用户数据库或构建产物。提交的自有贡献按仓库 Apache-2.0 许可提供；引入第三方材料时保留其许可与来源。

Git 只保存可复现构建所需的输入。各级 `node_modules/` 是本机安装结果，由 `pnpm install --frozen-lockfile` 恢复；目录出现在资源管理器中不代表已提交，无需为整理 Git 删除它。

| 内容 | 提交规则 |
| --- | --- |
| 源码、静态源资源、`package.json`、`pnpm-lock.yaml`、构建配置、配置模板 | 保留，用于复现安装与构建 |
| `node_modules/`、`dist/`、`coverage/`、缓存、测试报告、`*.tsbuildinfo` | 忽略，由安装、构建或测试生成 |
| `.local/`、真实配置、日志、编辑器临时文件和系统元数据 | 忽略，保留本机所需文件；运行数据放 `.local/data/`，发布产物放 `.local/artifacts/` |
| `*.tgz` | 默认忽略；作为构建输入的 vendor 包须在插件 `devDependencies` 中声明 `file:vendor/<文件名>.tgz`，在插件 `.gitignore` 中显式放行并确认分发权限 |

提交前运行 `node scripts/check-repository.mjs`。CI 同样执行此检查，拒绝被强制加入索引的忽略文件，并核验 vendor 声明。可用 `git check-ignore -v <路径>` 查看忽略依据，用 `git ls-files -- <路径>` 确认是否已跟踪；新增忽略规则不会自动移除已跟踪文件。