Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: clarify project layout and runtime selection

kashorinb8a937af970f
diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.md
index 0a78dbac..d1f99bee 100644
--- a/.agents/skills/hypit/references/runtime.md
+++ b/.agents/skills/hypit/references/runtime.md
@@ -90,6 +90,11 @@ hypit get <build-id> \
--output final.video --to output/final.mp4
```
+Resolve the project before selecting its Runtime. `--workspace` is explicit; otherwise run from the
+project directory (or one of its package-bounded descendants). `runtime use` writes one exact
+project-local pointer. Never infer a Profile from its filename or let a parent project's selection
+stand in for this project's choice.
+
The paid-build handoff is defined in `studio-confirmation.md`: show the complete preview-mock Run in
Studio and obtain acceptance before `hypit build`; after acceptance, Studio for the accepted Run and
the HyperFrames/final render may start concurrently. The render must not be blocked on the author's
@@ -107,7 +112,8 @@ After Runtime package selection changes, run `runtime up`: this is the explicit
boundary for machine npm dependencies, Managed Programs and the detached Worker. Use `doctor` for
an active full-profile diagnosis and `runtime status` to observe the deployment. `build` repeats the
cheap preflight and fails before durable submission when deployment is not ready; it never installs
-or starts a Managed Program.
+or starts a Managed Program. If provisioning is already complete and only the Worker is stopped,
+`build` starts that Worker before it submits the Build.
Use `runtime logs` to diagnose the Worker. Use `runtime down` to stop it from advancing active Builds.
External programs are intentionally independent; stop them only with `programs down`. Saved Build
diff --git a/docs/guide/runtime.md b/docs/guide/runtime.md
index d4ac6b7b..16e83eae 100644
--- a/docs/guide/runtime.md
+++ b/docs/guide/runtime.md
@@ -203,6 +203,12 @@ hypit runtime logs
hypit runtime down
```
+`runtime use` binds one explicit Profile to one already resolved project. The project comes from
+`--workspace`, or from the current directory's declared package boundary; the selection never
+defines that boundary. Commands read only `<project>/.hypit/runtime`: they do not scan for a
+conventionally named Profile and do not inherit a selection from a parent project. Separate projects
+therefore select separately, even when their Profiles declare equivalent external Endpoints.
+
`runtime up` asks npm to prepare the selected adapters' exact upstream packages in the shared
machine home, prepares declared Managed Programs, then starts the local Worker. `build` performs no
provisioning: it runs cheap read-only preflight, submits work only when ready, and ensures the Worker
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 58e6ff31..901856aa 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -116,6 +116,10 @@ project. By default, Build Results live under the project's `.hypit/results`; a
temporary Resources always live under the selected Profile's `dataRoot`.
`runtime use` stores only a local pointer at `.hypit/runtime`. Source imports select author
packages; the Profile independently selects Credential Stores and Endpoints through their own `use` entries.
+Project resolution happens first. `--workspace` selects it explicitly; otherwise the current
+directory's nearest `package.json` is its boundary, or the current directory itself for a plain
+creative folder. Only that exact project's `.hypit/runtime` is read—Profile filenames are never
+guessed and parent-project selections are never inherited.
Start from [`examples/talking-film-live`](https://github.com/hypit-ai/hypit/tree/main/examples/talking-film-live) when you need a
complete Runtime Profile. Copy the source structure, then replace its assets, Script, model choices
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index fa66e091..e7fc0db7 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -30,22 +30,37 @@ from any independent video project.
Only `build` submits work. `plan` is the normal preview. `check` is an editing aid; `doctor` is a
deployment diagnostic. They are safe to run, but not mandatory ceremony before every Build.
-One convenient project layout is:
+One convenient layout for a project with several Author, Recipe and Run Sources is:
```text
my-video/
- main.svml author meaning
- styles.svs optional authored styles
- build.svrun this Run's Targets and Candidate choices
- assets/ project-owned input media
- output/ explicit exports for people and other tools
- hypit.runtime.json execution environment
+ package.json project boundary
+ authors/
+ main.svml one Author entry
+ alternate.svml another Author entry, when genuinely needed
+ recipes/
+ visual.svs authored visual Recipes
+ generation.svs authored generation Recipes
+ runs/
+ images.svrun one executable intention
+ takes.svrun another executable intention
+ final.svrun final delivery intention
+ assets/ project-owned input media
+ kits/ optional vendored Recipe Kits
+ packages/ optional project-local Author packages
+ output/ explicit exports for people and other tools
+ hypit.runtime.json execution environment
+ hypit.results.json optional Result repository selection
+ .hypit/ generated local Runtime and Result data
```
-This is a convention, not a schema. Hypit uses the paths written in Source imports, `<author
-source="…">`, CLI arguments and `get --to`; it does not require these names or recognize `assets/`
-or `output/` specially. The managed Result repository remains separate under `.hypit/results` by
-default.
+This layout is only a human-facing recommendation, never a required project schema. A small project
+may keep several `.svml`, `.svs` and `.svrun` files flat at its root, and another project may group
+them differently. Hypit uses only the paths written in Source imports, `<author source="…">`, CLI
+arguments and `get --to`; it does not require these names or recognize `authors/`, `recipes/`,
+`runs/`, `assets/` or `output/` specially. Each Run selects one Author entry, while that Author
+Source closure may explicitly import multiple Author or Recipe Sources. The managed Result repository
+remains separate under `.hypit/results` by default.
Run Source and Runtime Profile do not silently rewrite the video. Creative model choices remain in
the Author Source or in packages that it explicitly imports.
@@ -220,6 +235,10 @@ hypit paths
`runtime use` writes only `.hypit/runtime`. It does not start a Worker, create Runtime data or
change installed packages. See [Runtime](../guide/runtime.md) for the Profile schema and boundaries.
+The CLI resolves the project first: `--workspace` is an explicit boundary; otherwise the nearest
+`package.json` above the current directory is the boundary, falling back to the current directory
+for a plain creative folder. It then reads only that project's `.hypit/runtime`. It never discovers
+a Profile from a conventional filename or inherits another project's selection from a parent directory.
## Configure selected credentials
@@ -265,8 +284,8 @@ cd /work/my-film
hypit runtime use hypit.runtime.json
```
-The Workspace is the selected project or entry Source directory. Override it
-only with `--workspace`. `--package-root` locates installed packages and never widens Source access.
+The Workspace is resolved before the Runtime Profile. Override it explicitly with `--workspace`;
+the entry Source path and Runtime selection never choose it. `--package-root` locates installed packages and never widens Source access.
`--asset-root` grants read access to additional asset bytes without permitting Source imports there.
```text
@@ -327,9 +346,11 @@ external-program diagnostics. It never starts external work.
`plan` may run without a Runtime at all. Both `plan` and `build` may omit `--runtime` after
`hypit runtime use`; `build` requires either that selection or an explicit Profile.
-Use `runtime up` to install selected upstream packages, prepare Managed Programs and start the
-Worker before submission. `build` repeats only the cheap read-only preflight and refuses before
-submission when anything is missing; it never provisions dependencies. `runtime status` observes
+Use `runtime up` after selecting or changing a deployment to install selected upstream packages,
+prepare Managed Programs and start the Worker. `build` repeats only the cheap read-only preflight
+and refuses before submission when a required package or Program is missing; it never provisions
+dependencies. When the deployment is already prepared and only its Worker is stopped, `build`
+starts that Worker before durable submission. `runtime status` observes
the deployment, while `programs up|status|down` is the narrower lifecycle view for long-lived
processes declared by Endpoints.
diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.md
index 63fa6465..43f8bafb 100644
--- a/docs/zh/guide/runtime.md
+++ b/docs/zh/guide/runtime.md
@@ -188,6 +188,11 @@ hypit runtime logs
hypit runtime down
```
+`runtime use` 把一份显式 Profile 绑定到一个已经解析完成的项目。项目来自 `--workspace`,
+或当前目录声明的 package 边界;Runtime 选择不能反过来定义项目。命令只读取
+`<project>/.hypit/runtime`,不会扫描约定文件名,也不会继承父项目的选择。即使几个项目声明
+了等价的外部 Endpoint,它们也必须分别完成选择。
+
`runtime up` 先让 npm 把所选 Adapter 的精确上游包准备到机器共享目录,再准备 Managed
Program 并启动本地 Worker。`build` 不做部署:它执行便宜只读预检,只在就绪后提交,并确保
Worker 可用。`activity`、`cancel` 用来观察和控制活跃工作;`status` 分别读取 Runtime 与 Result,一边失败
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index 4a08f418..9af7f90c 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -111,6 +111,9 @@ Distribution 里的官方包。默认情况下,完整 Build Result 位于项
不管理 Result,项目根的 `hypit.results.json` 可以把同一套 Result 模型指向 S3。Runtime 活跃状态与临时
Resource 始终位于所选 Profile 的 `dataRoot`。`runtime use` 只在 `.hypit/runtime` 保存一个本地指针。Source import 选择作者包,
Profile 则通过 Credential Store 与 Endpoint 各自的 `use` 独立选择环境包。
+项目必须先确定:显式 `--workspace` 直接选择项目,否则以当前目录向上的最近 `package.json`
+为边界;普通创作目录没有该文件时使用当前目录。CLI 只读取该项目自己的 `.hypit/runtime`,
+不会猜测 Profile 文件名,也不会继承父项目的选择。
需要完整 Runtime Profile 时,从
[`examples/talking-film-live`](https://github.com/hypit-ai/hypit/tree/main/examples/talking-film-live) 的结构开始:复制文件结构,
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index 91ce2e12..9196044a 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -26,21 +26,36 @@ hypit get <build-id> --output final.video --to output/final.mp4
只有 `build` 会真正提交工作。`plan` 是普通预览;`check` 用于编辑源码,`doctor` 用于配置和排查部署。它们都安全,但不是每次 Build 前必须重复的仪式。
-一种顺手的项目目录约定是:
+当项目包含多份 Author、Recipe 和 Run Source 时,一种顺手的目录约定是:
```text
my-video/
- main.svml 作者意图
- styles.svs 可选的作者样式
- build.svrun 本次 Run 的 Target 与 Candidate 选择
- assets/ 项目自己的输入素材
- output/ 显式导出给人或其他工具的副本
- hypit.runtime.json 执行环境
+ package.json 项目边界
+ authors/
+ main.svml 一份 Author 入口
+ alternate.svml 确有需要时的另一份 Author 入口
+ recipes/
+ visual.svs 视觉 Recipe
+ generation.svs 生成 Recipe
+ runs/
+ images.svrun 一种执行意图
+ takes.svrun 另一种执行意图
+ final.svrun 最终交付意图
+ assets/ 项目自己的输入素材
+ kits/ 可选的项目内 Recipe Kit
+ packages/ 可选的项目本地 Author 包
+ output/ 显式导出给人或其他工具的副本
+ hypit.runtime.json 执行环境
+ hypit.results.json 可选的 Result 仓库选择
+ .hypit/ 自动产生的本地 Runtime 与 Result 数据
```
-这只是推荐,不是项目格式。Hypit 只服从 Source import、`<author source="…">`、CLI 参数和
-`get --to` 中明确写出的路径,不要求这些名字,也不会特殊识别 `assets/` 或 `output/`。受管理的
-Result 仓库与它们分开,零配置时仍位于 `.hypit/results`。
+这只是方便人整理内容的推荐,绝不是强制的项目格式。小项目可以把多份 `.svml`、`.svs` 和
+`.svrun` 直接平铺在根目录,其他项目也可以采用不同分组。Hypit 只服从 Source import、
+`<author source="…">`、CLI 参数和 `get --to` 中明确写出的路径,不要求这些名字,也不会特殊识别
+`authors/`、`recipes/`、`runs/`、`assets/` 或 `output/`。每份 Run 选择一份 Author 入口,而这份
+Author Source 的闭包可以显式导入多份 Author 或 Recipe Source。受管理的 Result 仓库与它们分开,
+零配置时仍位于 `.hypit/results`。
Run Source 与 Runtime Profile 不会悄悄改写视频。创作性的模型选择仍然留在 Author Source,或它显式导入的包里。
@@ -186,6 +201,9 @@ hypit paths
`runtime use` 只写入 `.hypit/runtime`,不会启动 Worker、创建 Runtime 数据或修改已安装
包。Profile 结构和完整边界见 [Runtime](../guide/runtime.md)。
+CLI 必须先确定项目:显式 `--workspace` 直接给出边界;否则使用当前目录向上的最近
+`package.json`,普通创作目录没有该文件时就以当前目录为边界。随后只读取这个项目自己的
+`.hypit/runtime`。它不会按约定文件名猜 Profile,也不会从父目录继承另一个项目的选择。
## 配置所选凭据
`check` 与 `plan` 不会请求在线 Provider。没有所选 Runtime 的 `plan` 只看图,不需要部署
@@ -249,8 +267,8 @@ hypit runtime use hypit.runtime.json
hypit plan build.svrun
```
-Workspace 依次取显式 `--workspace`、所选 `.hypit/runtime` 所在项目和入口 Source 目录。
-Runtime Profile 无权改变这条源码边界。`--package-root` 只定位已经安装的
+Workspace 在 Runtime Profile 之前确定;显式 `--workspace` 可以覆盖它,入口 Source 路径和
+Runtime 选择都无权改变这条源码边界。`--package-root` 只定位已经安装的
`node_modules`;`--asset-root` 只额外授权读取素材字节。
外部项目通常应提交如下 `.gitignore`:
@@ -320,9 +338,10 @@ Runtime 后只预检这次计划真正需要的 Endpoint、凭据和外部程序
`plan` 可以完全不带 Runtime;执行过 `hypit runtime use` 后,`plan` 和 `build` 都不必再写
`--runtime`。`build` 必须能找到所选或显式 Profile。
-提交前用 `runtime up` 安装所选上游依赖、准备 Managed Program 并启动 Worker。`build` 只重跑
-便宜的只读预检;任何依赖未就绪都会在提交前失败,绝不在 Build 中安装或启动它。`runtime
-status` 用于观察,`programs up|status|down` 只管理外部程序。
+选择或改变部署后,用 `runtime up` 安装所选上游依赖、准备 Managed Program 并启动 Worker。
+`build` 只重跑便宜的只读预检;任何依赖或 Program 未就绪都会在提交前失败,绝不在 Build
+中准备它们。若部署已经准备完毕而只有 Worker 停止,`build` 会在耐久提交前启动该 Worker。
+`runtime status` 用于观察,`programs up|status|down` 只管理外部程序。
### 4. 提交 Build