# 开发指南 (https://hypit.ai/zh/guide/develop/)

> 开始 Hypit 开发工作。

## 前置条件 [#前置条件]

| 工具                | 版本               | 用于                                      |
| ----------------- | ---------------- | --------------------------------------- |
| Node.js           | 22.12+           | 所有工作                                    |
| pnpm              | 10.33.x          | workspace 管理；由根目录 `packageManager` 字段选择 |
| Python            | 3.10–3.13        | 本地 WhisperX 与 OpenCV Managed Program    |
| uv                | latest           | Python 环境管理                             |
| ffmpeg / ffprobe  | 较新的稳定版           | 媒体处理                                    |
| Chrome / Chromium | 由 HyperFrames 管理 | 本地 HyperFrames 渲染                       |

只有 Node.js 与 pnpm 是硬性要求。其余都只在跑真实 Builds 时才需要。

## 日常工作流 [#日常工作流]

```bash
corepack enable
pnpm install --frozen-lockfile # 拉取代码或改动依赖之后
pnpm check            # TypeScript 类型检查
pnpm test             # 完整测试套件
```

| 命令           | 实际执行什么                                                 |
| ------------ | ------------------------------------------------------ |
| `pnpm check` | `tsc -p tsconfig.json --noEmit`                        |
| `pnpm test`  | 通过 Node test runner 运行 package、service-adapter 与仓库边界测试 |

关于受环境开关控制的测试与测试写法，参见 [测试](/zh/guide/testing)。

## 仓库结构 [#仓库结构]

```text
hypit/
├── packages/              workspace packages
├── docs/                  VitePress documentation site
├── examples/              runnable example sources
├── services/              本地媒体与转写服务
├── test/                  repository boundary tests and shared fixtures
├── package.json           root workspace manifest
├── pnpm-workspace.yaml    package, service and example-component workspaces
└── tsconfig.json          TypeScript config
```

## 指南目录 [#指南目录]

| 指南                                       | 主题                                  |
| ---------------------------------------- | ----------------------------------- |
| [与 Agent 一起制作视频](/zh/guide/skill)        | 创作方向、服务选择与可编辑项目                     |
| [包与扩展](/zh/guide/packages)               | 组件、模型与服务的职责，安装与分享                   |
| [添加 Author 包](/zh/guide/author-packages) | 分步说明：新增组件、Surface、词表与预览图、activation |
| [模型与 Provider](/zh/guide/providers)      | 选择账户与 API，开发 Model 或 Provider 包     |
| [Runtime](/zh/guide/runtime)             | Profile、Workspace、执行与生命周期边界         |
| [测试](/zh/guide/testing)                  | 测试运行器、写法、示例、boundary tests          |
| [代码规范](/zh/guide/conventions)            | 命名、模块边界、wire 数据、TypeScript 配置       |