# 贡献指南（CONTRIB）

本文档面向 SDK 开发/维护者，内容以 `package.json` 的 scripts 为单一事实来源。

## 开发环境

- Node.js: 建议使用当前 LTS
- 包管理器: npm（项目脚本默认使用 `npm run ...`）

备注：本仓库当前没有提供 `.env.example`，因此默认不需要额外环境变量。

## 常用命令（Scripts）

| Script | 命令 | 说明 |
|---|---|---|
| `dev` | `vite` | 启动开发环境（通常用于 playground） |
| `build` | `tsc && vite build` | 构建 SDK（产物输出到 `dist/`） |
| `copy:demo` | `mkdir -p demo/lib && cp dist/iflow-engine.es.js dist/iflow-engine.umd.js dist/iflow-engine.umd.js.map demo/lib/` | 复制构建产物到 HTML demo 目录 |
| `copy:demo-draco` | `mkdir -p demo/static/js/draco && cp node_modules/iflow-engine-base/dist/draco/*.js node_modules/iflow-engine-base/dist/draco/*.wasm demo/static/js/draco/` | 复制 draco 解码器到 HTML demo 目录 |
| `copy:demo-all` | `npm run copy:demo && npm run copy:demo-draco` | 一次性准备 HTML demo 需要的全部静态资源 |
| `copy:demo-vue` | `mkdir -p demo-vue/public/lib && cp dist/iflow-engine.es.js dist/iflow-engine.umd.js dist/iflow-engine.umd.js.map demo-vue/public/lib/` | 复制构建产物到 Vue demo 目录 |
| `dev:demo` | `npm run build && npm run copy:demo-all && cd demo && npm run dev` | 构建并启动 HTML demo |
| `dev:demo-vue` | `npm run build && npm run copy:demo-vue && cd demo-vue && npm run dev` | 构建并启动 Vue demo |
| `dev:all` | `npm run dev:demo & npm run dev:demo-vue` | 同时启动两个 demo（并行） |
| `prepublishOnly` | `npm run build` | npm 发布前自动构建 |

## 开发流程（建议）

1. 本地开发：`npm run dev`
2. 修改代码后做一次构建验证：`npm run build`
3. 需要人工验证交互时：
   - HTML demo：`npm run dev:demo`
   - Vue demo：`npm run dev:demo-vue`

## 测试与验证

当前仓库未配置独立的单元测试脚本。

推荐的最小验证集：
- `npm run build`（保证 TypeScript 编译与 Vite 打包通过）
- 在 `demo/` 或 `demo-vue/` 中进行手动回归（与本次修改相关的功能点）

## 文档维护

- 代码变更后，务必同步更新 `AI_COLLABORATION.md` 的相关部分。
- 如果新增/修改了组件或管理器，建议同步更新 `docs/` 下对应模块文档。

## 过期文档检查（90 天）

按最近一次扫描结果：`docs/` 下没有发现 90 天未更新的文档。