Formerly KrillinAI, VideoTranslation and Dubbing Tool for 120+ Languages. Open-source AI workspace for creators, powered by Codex. Video downloader, video translation, create videos, images, audios, and edits with Agents in one place. For your Social Media like YouTube, TikTok, Instagram, etc.
TypeScript agent-skillscodex-clideskop-appdubbingimage-generationlocalizationskillsttsvideo-editingvideo-generationvideo-transcriptionvideo-translation
docs: add contributing guides and PR template
Joshua Yin Junxi3b1915da46a3
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdnew file mode 100644index 00000000..fbcccbb2--- /dev/null+++ b/.github/pull_request_template.md@@ -0,0 +1,45 @@+## Summary++<!-- What does this PR change, and why? Link the related issue if one exists. -->++## Change risk level++<!-- Pick the level that matches this change. Verification must match the risk and actual blast radius — do not escalate a small, local, low-risk change to full test suites, production builds, or Desktop packaging by default. See AGENTS.md for the full policy. -->++- [ ] **P0 — Low risk**: copy, style tweaks, defaults, local display conditions, test assertions. No Runtime/API/persistence contract changes.+- [ ] **P1 — Medium risk**: shared state, business logic, persistence, cross-component interaction, Runtime request parameters, shared components.+- [ ] **P2 — High risk**: Daemon/Runtime, protocol, database migration, process management, service configuration, build/packaging, release pipeline, or Web/Desktop parity changes.++## Verification++<!-- List what you actually ran. Report only the verification you performed — do not imply overall regression safety from checks you skipped. -->++- [ ] Targeted checks for the changed files / closest tests+- [ ] `pnpm typecheck` for affected packages (TypeScript changes)+- [ ] Module tests for affected areas (P1+)+- [ ] Production build (only when touching compile boundaries, lazy loading, assets, or build config)+- [ ] Service restart + health check (P2 daemon/runtime changes)+- [ ] Web/Desktop parity checks (shared UI, Bridge, or packaging changes)++**Actually ran:**++<!-- e.g. `pnpm --filter @opencreator/web typecheck`, `pnpm test -- skills` -->++**Intentionally skipped, and why:**++<!-- e.g. Desktop packaging — no Desktop-facing changes -->++## Web / Desktop parity++<!-- Required when touching apps/web pages, state, services, Host Bridge, daemon project logic, Desktop preload, window logic, protocol proxy, or packaging scripts. -->++- [ ] This change does not affect Web/Desktop parity+- [ ] General capability implemented once in shared Web/Daemon code (no per-bridge forks)+- [ ] Platform-specific entries are hidden when the capability is unavailable (no silent no-op buttons)+- [ ] The same flow was checked on the other platform, not only the one where the issue was reported++## Checklist++- [ ] Focused change — no unrelated refactors or fixes mixed in+- [ ] Docs updated in the same PR if user-visible behavior changed+- [ ] No `.runtime/`, credentials, Codex sessions, build caches, or user data committeddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 00000000..e7846554--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,67 @@+# Contributing to OpenCreator++> English | [简体中文](./CONTRIBUTING.zh-CN.md)++Thanks for thinking about contributing. OpenCreator is a local-first creator workspace built on the Codex agent loop, and most of its value lives in focused additions: one Skill folder, one creation template, one well-scoped fix. This guide tells you where each type of contribution lives and what bar a PR has to clear before we merge it.++---++## Contribution map++| If you want to… | You're really adding | Where it lives | Ship size |+|---|---|---|---|+| Fix a bug or improve a workflow | code | `apps/web/`, `apps/daemon/` | one focused PR with tests |+| Add a reusable Agent workflow | a **Skill** | [`skills/<your-skill>/`](skills/) | one folder with `SKILL.md` and optional references → [guide](docs/contributing/skills-contributing.md) |+| Add a reusable image, video, or cover preset | a **Creation template** | [`template/<module>/<id>/<version>/`](template/) | one folder with `template.json` plus assets → [guide](docs/contributing/templates-contributing.md) |+| Contribute illustrations, icons, or UI designs | design assets | agreed asset location | one PR with previews, source files, and license |+| Add an AI or media provider | a **service integration** | relevant Web or Daemon module | one PR with error handling, credential safety, and tests |+| Improve docs or translations | docs | `README.md`, `docs/`, `docs/<locale>/README.md` | one PR |++If you're not sure which bucket your idea is in, [open an issue first](https://github.com/krillinai/OpenCreator/issues/new) and we'll point you at the right surface.++---++## Local setup++The full setup lives in the [README Quick Start](./README.md#quick-start). The TL;DR for contributors:++```bash+git clone https://github.com/krillinai/OpenCreator.git+cd OpenCreator+corepack enable # selects the pinned pnpm from packageManager+pnpm install+pnpm web:dev # web + local daemon on demand+pnpm typecheck # TypeScript checks across the repository+pnpm test # workspace unit and integration tests+```++Node.js 22+ and a Codex CLI executable are required. Open `http://127.0.0.1:19861/` after `pnpm web:dev`; the Runtime prepares a default project on first launch and the composer is ready as soon as the connection completes.++---++## How to contribute++1. Describe the problem, use case, and expected behavior in an [issue](https://github.com/krillinai/OpenCreator/issues).+2. Create a focused feature or fix branch from the latest development branch.+3. Follow the existing architecture: implement general product capabilities **once** in Web and Daemon, and isolate native Desktop differences behind explicit capabilities (for example `canSelectDirectory`).+4. Add appropriate unit, integration, or E2E coverage for behavior changes, and list both completed and skipped verification in the PR.+5. Never commit `.runtime/`, local credentials, Codex sessions, build caches, or other user data.++## What reviewers check++- **Single implementation for shared behavior.** The same feature must not be implemented separately for Browser Bridge and Desktop Bridge.+- **Capability gating, not silent stubs.** A platform-specific entry must be hidden when the capability is unavailable — never show a button that silently does nothing.+- **Tests match the change risk.** Small copy or style tweaks need only targeted checks; shared state, persistence, or Runtime contract changes need module tests and typecheck at minimum.+- **Docs updated with behavior.** If your change alters a user-visible workflow, update the README or the relevant doc in `docs/` in the same PR.++## Common reasons PRs get sent back++- The same logic was added separately to Web and Desktop paths instead of the shared service layer.+- A platform-unsupported button is visible but its handler silently returns.+- Behavior changed without any test or verification note.+- The PR mixes an unrelated refactor or fix into a feature change.+- Generated files, `.runtime/` data, or credentials were committed.++---++OpenCreator · Create locally, work continuously.diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.mdnew file mode 100644index 00000000..ab18e3c3--- /dev/null+++ b/CONTRIBUTING.zh-CN.md@@ -0,0 +1,67 @@+# 贡献指南(简体中文)++> [English](./CONTRIBUTING.md) | 简体中文++感谢你愿意为 OpenCreator 做贡献。OpenCreator 是一个基于 Codex Agent 循环的本地优先创作工作区,项目的大部分价值来自小而聚焦的补充:一个 Skill 文件夹、一个创作模板、一个边界清晰的修复。本指南说明每类贡献应该放在哪里,以及 PR 需要达到什么标准才能合并。++---++## 贡献地图++| 如果你想…… | 你实际在添加的是 | 位置 | 交付规模 |+|---|---|---|---|+| 修复 Bug 或改进工作流 | 代码 | `apps/web/`、`apps/daemon/` | 一个聚焦的 PR,附测试 |+| 添加可复用的 Agent 工作流 | **Skill** | [`skills/<your-skill>/`](skills/) | 一个文件夹,含 `SKILL.md` 和可选的 references → [指南](docs/contributing/skills-contributing.zh-CN.md) |+| 添加可复用的图像、视频或封面预设 | **创作模板** | [`template/<module>/<id>/<version>/`](template/) | 一个文件夹,含 `template.json` 和素材 → [指南](docs/contributing/templates-contributing.zh-CN.md) |+| 贡献插画、图标或 UI 设计 | 设计资产 | 约定的资产位置 | 一个 PR,附预览、源文件和授权说明 |+| 接入 AI 或媒体服务 | **服务集成** | 相关 Web 或 Daemon 模块 | 一个 PR,含错误处理、凭证安全和测试 |+| 改进文档或翻译 | 文档 | `README.md`、`docs/`、`docs/<locale>/README.md` | 一个 PR |++如果你不确定自己的想法属于哪一类,先[提一个 Issue](https://github.com/krillinai/OpenCreator/issues/new),我们会告诉你应该从哪个入口入手。++---++## 本地开发环境++完整的环境准备见 [README 快速开始](./README.md#quick-start)。贡献者只需要记住:++```bash+git clone https://github.com/krillinai/OpenCreator.git+cd OpenCreator+corepack enable # 使用 packageManager 字段锁定的 pnpm+pnpm install+pnpm web:dev # Web + 按需启动本地 daemon+pnpm typecheck # 全仓库 TypeScript 检查+pnpm test # 工作区单元与集成测试+```++需要 Node.js 22+ 和可用的 Codex CLI。`pnpm web:dev` 后打开 `http://127.0.0.1:19861/`;首次启动时 Runtime 会自动准备默认项目,连接完成后即可直接输入。++---++## 贡献流程++1. 在 [Issue](https://github.com/krillinai/OpenCreator/issues) 中描述问题、使用场景和预期行为。+2. 从最新的开发分支切出一个聚焦的功能或修复分支。+3. 遵循现有架构:通用产品能力在 Web 和 Daemon 中**只实现一次**,Desktop 原生差异必须通过显式 capability(例如 `canSelectDirectory`)隔离。+4. 为行为变化添加合适的单元、集成或 E2E 测试,并在 PR 中同时列出已执行和已跳过的验证。+5. 绝不提交 `.runtime/`、本地凭证、Codex 会话、构建缓存或其他用户数据。++## Reviewer 会检查什么++- **共享行为只有一份实现。** 同一功能不得在 Browser Bridge 和 Desktop Bridge 各写一套。+- **能力判断,而不是静默空实现。** 平台能力不可用时必须隐藏入口,绝不允许显示一个点击后静默无反应的按钮。+- **测试与改动风险匹配。** 文案、样式微调只需定向检查;共享状态、持久化或 Runtime 契约变更至少需要模块测试和 typecheck。+- **文档随行为更新。** 如果改动影响用户可见的工作流,在同一个 PR 中更新 README 或 `docs/` 下的相关文档。++## PR 常见被退回原因++- 同一逻辑在 Web 和 Desktop 路径各写了一份,而不是放在共享服务层。+- 平台不支持的按钮仍然可见,但处理函数静默 return。+- 行为发生变化,但没有任何测试或验证说明。+- PR 混入了与本次目标无关的重构或修复。+- 提交了生成产物、`.runtime/` 数据或凭证。++---++OpenCreator · Create locally, work continuously.diff --git a/README.md b/README.mdindex 580bcfbc..40d0cd04 100644--- a/README.md+++ b/README.md@@ -525,6 +525,7 @@ pnpm --filter @opencreator/daemon test -- test/smoke/real-codex-smoke.test.ts## Documentation+- [Contributing guide](./CONTRIBUTING.md) · [Contributing a Skill](./docs/contributing/skills-contributing.md) · [Contributing a creation template](./docs/contributing/templates-contributing.md)- [User guide and troubleshooting](./docs/opencreator-user-guide-and-troubleshooting.md)- [Runtime API v1](./docs/runtime-api-for-ui-v1.md)- [Codex-native Runtime design](./docs/2026-07-03-codex-native-agent-runtime-design.md)@@ -538,28 +539,7 @@ The root `README.md` is the canonical English document. Maintained translations## Contributing-Contributions are welcome in these areas:--| Type | What to contribute | How to prepare | Where to contribute |-| --- | --- | --- | --- |-| Code | Bug fixes, creator workflows, shared features | A focused change, demo or reproduction, and relevant tests | [Issue][contribute-issue] → [PR][contribute-pr]; `apps/web/` or `apps/daemon/` |-| Skills | Reusable Agent workflows | `SKILL.md`, prerequisites, and usage examples | [Issue][contribute-issue] → [PR][contribute-pr] in `skills/` |-| Creation templates | Reusable image, video, or cover templates | `template.json`, cover and example assets, prompts, settings, attribution, and usage rights | [PR][contribute-pr] in [`template/`](./template/); discuss new formats in an [Issue][contribute-issue] |-| Illustration and design | Original illustrations, icons, or UI designs | Preview, editable source files, and license or permission | [Issue][contribute-issue] → [PR][contribute-pr] in an agreed asset location |-| Third-party service integrations | AI or media provider support | Use case, setup, error handling, credential safety, and tests | [Issue][contribute-issue] → [PR][contribute-pr] in relevant Web or Daemon modules |--Place each creation template at `template/<module>/<id>/<version>/template.json` with its local assets. The current modules are `image-generation`, `video-generation`, and `cover-generator`. Include Chinese and English titles and descriptions, and run `pnpm templates:validate` before submitting a PR.--How to contribute:--1. Describe the problem, use case, and expected behavior in [Issues](https://github.com/krillinai/OpenCreator/issues).-2. Create a focused feature or fix branch from the latest development branch.-3. Follow the existing architecture: implement general product capabilities once in Web and Daemon, and isolate native differences behind explicit capabilities.-4. Add appropriate unit, integration, or E2E coverage for behavior changes, and list both completed and skipped verification in the Pull Request.-5. Never commit `.runtime/`, local credentials, Codex sessions, build caches, or other user data.--[contribute-issue]: https://github.com/krillinai/OpenCreator/issues-[contribute-pr]: https://github.com/krillinai/OpenCreator/pulls+Contributions are welcome across code, Skills, creation templates, design, third-party integrations, and docs. The full guide — including the contribution map, local setup, review criteria, and common rejection patterns — lives in [CONTRIBUTING.md](./CONTRIBUTING.md), with deep-dive guides for [Skills](./docs/contributing/skills-contributing.md) and [creation templates](./docs/contributing/templates-contributing.md).## Contributorsdiff --git a/docs/contributing/skills-contributing.md b/docs/contributing/skills-contributing.mdnew file mode 100644index 00000000..6fae113e--- /dev/null+++ b/docs/contributing/skills-contributing.md@@ -0,0 +1,96 @@+# Contributing a Skill++> English | [简体中文](./skills-contributing.zh-CN.md)++A Skill is a folder under [`skills/`](../../skills/) with a `SKILL.md` at its root, following the [`SKILL.md` convention](https://agentskills.io). It packages a reusable Agent workflow: when to use it, what commands or tools to call, and how to interpret outputs. This guide walks through adding one.++---++## What a Skill IS / IS NOT++**A Skill IS:**+- A repeatable workflow the Agent can follow, described in natural language plus commands.+- Domain knowledge that doesn't belong in core code: how to invoke a CLI stage, how to structure a prompt for a media provider, how to validate a plan.+- Small. One folder, one `SKILL.md`, optional `references/` for longer material the Agent reads on demand.++**A Skill IS NOT:**+- A product feature. UI changes, new Runtime endpoints, and new workspace behavior are code contributions (`apps/web/`, `apps/daemon/`).+- A copy of an existing Skill with tweaked wording. If your change improves an existing workflow, edit that Skill instead.+- A wrapper around credentials or a specific user's local paths. Skills must work from a clean checkout.++## Quick start++```bash+git clone https://github.com/krillinai/OpenCreator.git+cd OpenCreator+corepack enable && pnpm install+cp -r skills/krillinai-tts skills/<your-skill> # start from the closest existing Skill+# edit skills/<your-skill>/SKILL.md+pnpm web:dev # verify the Agent picks it up in a conversation+```++The fastest path is copying the Skill closest to your idea and rewriting it — the existing `krillinai-*` Skills show the expected structure and tone.++## Skill anatomy++```+skills/<your-skill>/+├── SKILL.md # required: frontmatter + instructions+└── references/ # optional: long docs the SKILL.md points to+ └── cli-contract.md+```++`SKILL.md` starts with YAML frontmatter:++```yaml+---+name: your-skill+description: Use when <trigger condition>, including <main capabilities>.+---+```++Two rules reviewers enforce:++- **`name` must match the folder name.** Lowercase, hyphenated.+- **`description` is the discovery surface.** It is what the Agent reads to decide whether this Skill applies. Write it as "Use when …", name the trigger and the outcome, and keep it to one or two sentences. Vague descriptions ("helps with video") get sent back.++The body should cover, in order:++1. **When to use** — one paragraph.+2. **Commands** — fenced code blocks with the exact invocation, including required environment variables or working directories.+3. **Inputs and flags** — a table for anything non-obvious; mark required vs optional.+4. **Outputs** — where results land and how to read them (for example, "read paths from the manifest").+5. **Failure modes** — known errors and what to do about them.++Keep `SKILL.md` scannable. Move long contracts, full flag lists, or background material into `references/` and link to them with a relative path — the Agent reads references only when needed.++## Running locally++After `pnpm web:dev`, start a conversation and describe a task that should trigger your Skill. Verify:++- The Agent selects the Skill for the right requests — and does not select it for unrelated ones.+- Commands in the Skill run from a clean checkout without manual fixes.+- Output paths and error handling match what the Skill documents.++## Merge bar++A reviewer will check every item below — paste this into your PR and tick them off:++- [ ] Folder name and `name` frontmatter match; lowercase-hyphenated.+- [ ] `description` names the trigger condition and the outcome ("Use when …").+- [ ] Commands run from a clean checkout; no absolute local paths or credentials.+- [ ] Inputs, outputs, and failure modes are documented.+- [ ] Long reference material lives in `references/`, not inline.+- [ ] Verified in a real conversation: the Skill triggers when it should and only then.+- [ ] If the Skill overlaps an existing one, the PR explains why a separate Skill is warranted.++## Common rejection patterns++- **Duplicate of an existing Skill** with only cosmetic wording changes — improve the existing one instead.+- **A feature in disguise** — the Skill only works if paired with code changes to the Runtime or UI; submit the code change as its own PR.+- **Untested commands** — flags that don't exist, outputs that don't match the documented paths.+- **Undocumented prerequisites** — the Skill silently assumes a provider config, a binary, or a network service.++---++Questions? [Open an issue](https://github.com/krillinai/OpenCreator/issues/new) with the `skill` topic and we'll help you scope it.diff --git a/docs/contributing/skills-contributing.zh-CN.md b/docs/contributing/skills-contributing.zh-CN.mdnew file mode 100644index 00000000..c2001036--- /dev/null+++ b/docs/contributing/skills-contributing.zh-CN.md@@ -0,0 +1,96 @@+# 贡献一个 Skill(简体中文)++> [English](./skills-contributing.md) | 简体中文++Skill 是 [`skills/`](../../skills/) 下的一个文件夹,根目录包含一个 `SKILL.md`,遵循 [`SKILL.md` 约定](https://agentskills.io)。它封装一个可复用的 Agent 工作流:何时使用、调用什么命令或工具、如何解读输出。本指南说明如何新增一个 Skill。++---++## Skill 是什么 / 不是什么++**Skill 是:**+- Agent 可以遵循的可重复工作流,用自然语言加命令描述。+- 不属于核心代码的领域知识:如何调用某个 CLI 阶段、如何为媒体服务组织 prompt、如何校验计划。+- 小。一个文件夹、一个 `SKILL.md`,可选的 `references/` 存放 Agent 按需阅读的长文档。++**Skill 不是:**+- 产品功能。UI 改动、新的 Runtime 接口、新的工作区行为都属于代码贡献(`apps/web/`、`apps/daemon/`)。+- 某个现有 Skill 的措辞改写版。如果你的改动能改进现有工作流,直接修改那个 Skill。+- 对凭证或特定用户本地路径的封装。Skill 必须能在干净检出上运行。++## 快速开始++```bash+git clone https://github.com/krillinai/OpenCreator.git+cd OpenCreator+corepack enable && pnpm install+cp -r skills/krillinai-tts skills/<your-skill> # 从最接近的现有 Skill 开始+# 编辑 skills/<your-skill>/SKILL.md+pnpm web:dev # 在会话中验证 Agent 能识别它+```++最快的路径是复制与你想法最接近的 Skill 然后改写——现有的 `krillinai-*` Skills 展示了期望的结构和语气。++## Skill 结构++```+skills/<your-skill>/+├── SKILL.md # 必需:frontmatter + 说明+└── references/ # 可选:SKILL.md 引用的长文档+ └── cli-contract.md+```++`SKILL.md` 以 YAML frontmatter 开头:++```yaml+---+name: your-skill+description: Use when <触发条件>, including <主要能力>。+---+```++Reviewer 会强制执行两条规则:++- **`name` 必须与文件夹名一致。** 小写,连字符分隔。+- **`description` 是发现入口。** Agent 靠它判断这个 Skill 是否适用。用 "Use when …" 的写法,点明触发条件和结果,控制在一两句话。含糊的描述("帮助处理视频")会被退回。++正文按以下顺序组织:++1. **何时使用** —— 一段话。+2. **命令** —— 代码块给出完整调用,包括必需的环境变量和工作目录。+3. **输入与参数** —— 不直观的参数用表格说明,标注必填/可选。+4. **输出** —— 结果落在哪里、如何读取(例如"从 manifest 读取路径")。+5. **失败模式** —— 已知错误及应对方式。++保持 `SKILL.md` 可扫读。长契约、完整参数列表或背景材料放进 `references/`,用相对路径链接——Agent 只在需要时才读取 references。++## 本地验证++`pnpm web:dev` 后,发起一个会话,描述一个应该触发该 Skill 的任务。验证:++- Agent 对正确的请求选择该 Skill——并且不会对无关请求误选。+- Skill 中的命令在干净检出上无需手工修补即可运行。+- 输出路径和错误处理与文档一致。++## 合并门槛++Reviewer 会逐项检查以下内容——把它贴进你的 PR 并逐项勾选:++- [ ] 文件夹名与 `name` frontmatter 一致;小写连字符。+- [ ] `description` 点明触发条件和结果("Use when …")。+- [ ] 命令在干净检出上可运行;无绝对本地路径或凭证。+- [ ] 输入、输出和失败模式均有文档。+- [ ] 长参考材料放在 `references/`,而不是内联。+- [ ] 已在真实会话中验证:该触发时触发,不该触发时不触发。+- [ ] 如果与现有 Skill 有重叠,PR 说明了为什么需要独立 Skill。++## 常见被拒原因++- **与现有 Skill 重复**,只做措辞上的表面改动——请改为改进现有 Skill。+- **伪装成 Skill 的功能** —— 必须配合 Runtime 或 UI 代码改动才能工作;代码改动应单独提 PR。+- **未测试的命令** —— 参数不存在,或输出与文档描述的路径不符。+- **未文档化的前置条件** —— 默默假设了某个服务配置、二进制或网络服务。++---++有问题?[提一个 Issue](https://github.com/krillinai/OpenCreator/issues/new) 并标注 skill 主题,我们会帮你明确范围。diff --git a/docs/contributing/templates-contributing.md b/docs/contributing/templates-contributing.mdnew file mode 100644index 00000000..92fc83f8--- /dev/null+++ b/docs/contributing/templates-contributing.md@@ -0,0 +1,102 @@+# Contributing a Creation Template++> English | [简体中文](./templates-contributing.zh-CN.md)++A creation template is a folder under [`template/<module>/<id>/<version>/`](../../template/) with a `template.json` and its local assets. Templates power the visual pickers for image generation, video generation, and cover generation — users start from your preset instead of a blank prompt. This guide walks through adding one.++---++## What a creation template IS / IS NOT++**A template IS:**+- A tuned preset: prompt defaults, style hints, ratio/duration/quality settings, plus a cover and preview that show the result.+- Self-contained. Everything the picker shows lives in the template folder.++**A template IS NOT:**+- A new template *type*. The current modules are `image-generation`, `video-generation`, and `cover-generator`. If you need a new module, open an issue to discuss it first — that's a product change, not a template.+- A prompt dump. Templates with an empty or generic prompt and no localized defaults will be sent back; the value is in the tuning.+- Someone else's work without rights. See [Attribution and rights](#attribution-and-rights).++## Quick start++```bash+corepack enable && pnpm install+cp -r template/cover-generator/images-go-hard-thumbnail template/<module>/<your-template-id>+# edit template.json, replace cover/preview assets+pnpm templates:validate # must pass before opening a PR+```++Template IDs are lowercase-hyphenated and unique within the module. Version starts at `1` — one folder per version, so updates create `<id>/2/` rather than editing `<id>/1/`.++## Folder anatomy++```+template/<module>/<id>/1/+├── template.json # required: metadata, defaults, localized content+├── cover.jpg # required: shown in the template picker+├── preview.jpg # image/cover modules: larger result preview+├── previewVideo # video module: example clip, e.g. example.mp4+└── author-avatar.jpg # optional: credited author's avatar+```++## template.json field guide++| Field | Required | Notes |+|---|---|---|+| `schemaVersion` | yes | Currently `1`. |+| `id`, `version`, `module` | yes | Must match the folder path `<module>/<id>/<version>/`. |+| `runtimeTemplate` | yes | Maps to the runtime executor, e.g. `{"id": "cover", "version": 2}`. Copy from a template in the same module. |+| `status` | yes | `published` to ship; use `draft` while iterating. |+| `title`, `description` | yes | Both `zh-CN` and `en-US` are required. Other locales are optional. |+| `cover` | yes | Relative path to the picker thumbnail. |+| `preview` / `previewVideo` | module-dependent | `preview` for image and cover modules, `previewVideo` for video. |+| `defaults` | yes | The baseline settings users start from (prompt, ratio, duration, quality…). |+| `defaultsByLocale` | strongly recommended | Localized prompt and style overrides per locale. This is where the real tuning lives — see below. |+| `tags` | recommended | Searchable labels; keep them factual. |+| `author` | if applicable | `name`, `url`, `avatar` for credited external sources. |+| `featured`, `sortOrder` | no | Leave `featured: false`; maintainers decide featuring. |++## The prompt is the product++Reviewers spend most of their time on `defaults` and `defaultsByLocale`:++- **Both locales must be real prompts**, not translations that lost the tuning. The `zh-CN` and `en-US` prompts should produce equivalent results with their respective phrasing strengths.+- **Parametrize what's meant to change.** If the headline text or subject is user-editable, say so explicitly in the prompt (existing templates use markers like "Customizable text: …").+- **State constraints.** "No watermark, no extra text, no extra people" — negative constraints matter as much as the description for reproducible output.+- **Match the module's defaults shape.** Image templates carry ratio/candidateCount/quality; video templates carry size/duration; cover templates carry headline, text language, and style fields. Copy the shape from an existing template in your module.++## Assets++- Generate the `cover.jpg` and preview **with the template itself** — a stock image or unrelated artwork will be rejected.+- Keep file sizes reasonable; these ship with the app and load in the picker.+- The preview should represent a *typical* result, not a best-of-fifty cherry-pick.++## Attribution and rights++If your template adapts someone else's published prompt or style:++- You must have the right to redistribute it.+- Fill in the `author` field with `name` and `url` (and `author-avatar.jpg` if available), as existing templates do.+- When in doubt, open an issue and ask before doing the work.++## Merge bar++- [ ] Folder path matches `id`/`version`/`module`; ID is unique within the module.+- [ ] `pnpm templates:validate` passes.+- [ ] `title` and `description` provided in both `zh-CN` and `en-US`.+- [ ] `defaultsByLocale` contains tuned prompts for both locales.+- [ ] Cover and preview assets were generated by the template itself.+- [ ] `author` attribution included when adapting external work.+- [ ] `featured: false`, `status: "published"` (or `draft` with a note in the PR).++## Common rejection patterns++- **Generic prompt** — the template adds nothing over a blank prompt; the picker doesn't need it.+- **Missing locale** — only one language tuned, or a machine-translated prompt that lost the style constraints.+- **Mismatched assets** — cover doesn't match what the prompt actually generates.+- **Rights unclear** — adapted from someone's work without attribution or permission.+- **New version edited in place** — bump the version folder instead of rewriting history on `<id>/1/`.++---++Questions? [Open an issue](https://github.com/krillinai/OpenCreator/issues/new) with your template idea and a sample output, and we'll help you scope it.diff --git a/docs/contributing/templates-contributing.zh-CN.md b/docs/contributing/templates-contributing.zh-CN.mdnew file mode 100644index 00000000..e2453d01--- /dev/null+++ b/docs/contributing/templates-contributing.zh-CN.md@@ -0,0 +1,102 @@+# 贡献一个创作模板(简体中文)++> [English](./templates-contributing.md) | 简体中文++创作模板是 [`template/<module>/<id>/<version>/`](../../template/) 下的一个文件夹,包含 `template.json` 和本地素材。模板为图像生成、视频生成和封面生成的可视化选择器提供预设——用户从你的预设开始创作,而不是面对空白 prompt。本指南说明如何新增一个模板。++---++## 创作模板是什么 / 不是什么++**模板是:**+- 一套调好的预设:prompt 默认值、风格提示、比例/时长/质量设置,加上展示效果的封面和预览。+- 自包含。选择器展示的所有内容都在模板文件夹内。++**模板不是:**+- 新的模板*类型*。当前模块为 `image-generation`、`video-generation` 和 `cover-generator`。如果需要新模块,先提 Issue 讨论——那是产品变更,不是模板。+- prompt 堆砌。prompt 为空或过于通用、没有本地化默认值的模板会被退回;模板的价值在于调优。+- 没有授权的他人作品。见[署名与版权](#署名与版权)。++## 快速开始++```bash+corepack enable && pnpm install+cp -r template/cover-generator/images-go-hard-thumbnail template/<module>/<your-template-id>+# 编辑 template.json,替换封面/预览素材+pnpm templates:validate # 提 PR 前必须通过+```++模板 ID 使用小写连字符,在模块内唯一。版本从 `1` 开始——一个版本一个文件夹,更新时新建 `<id>/2/` 而不是修改 `<id>/1/`。++## 目录结构++```+template/<module>/<id>/1/+├── template.json # 必需:元数据、默认值、本地化内容+├── cover.jpg # 必需:模板选择器中展示的封面+├── preview.jpg # 图像/封面模块:更大尺寸的结果预览+├── previewVideo # 视频模块:示例片段,如 example.mp4+└── author-avatar.jpg # 可选:署名作者头像+```++## template.json 字段说明++| 字段 | 是否必需 | 说明 |+|---|---|---|+| `schemaVersion` | 是 | 当前为 `1`。 |+| `id`、`version`、`module` | 是 | 必须与文件夹路径 `<module>/<id>/<version>/` 一致。 |+| `runtimeTemplate` | 是 | 映射到 Runtime 执行器,如 `{"id": "cover", "version": 2}`。从同模块模板复制。 |+| `status` | 是 | 发布用 `published`;迭代期间用 `draft`。 |+| `title`、`description` | 是 | `zh-CN` 和 `en-US` 都必填,其他语言可选。 |+| `cover` | 是 | 选择器缩略图的相对路径。 |+| `preview` / `previewVideo` | 视模块而定 | 图像和封面模块用 `preview`,视频模块用 `previewVideo`。 |+| `defaults` | 是 | 用户开始的基线设置(prompt、比例、时长、质量等)。 |+| `defaultsByLocale` | 强烈建议 | 按语言的 prompt 和风格覆盖。真正的调优都在这里——见下文。 |+| `tags` | 建议 | 可搜索的标签;保持客观。 |+| `author` | 如适用 | 署名外部来源的 `name`、`url`、`avatar`。 |+| `featured`、`sortOrder` | 否 | 保持 `featured: false`;是否精选由维护者决定。 |++## prompt 就是产品++Reviewer 的大部分时间会花在 `defaults` 和 `defaultsByLocale` 上:++- **两种语言都必须是真实调优过的 prompt**,而不是丢失调优信息的直译。`zh-CN` 和 `en-US` 的 prompt 应各自发挥语言优势,产出等价结果。+- **明确哪些内容是让用户改的。** 如果标题文字或主体应由用户编辑,在 prompt 中明确说明(现有模板使用 "Customizable text: …" 这类标记)。+- **写清约束。** "无水印、无额外文字、无额外人物"——负向约束对可复现的输出和描述同样重要。+- **匹配模块的 defaults 结构。** 图像模板带 ratio/candidateCount/quality;视频模板带 size/duration;封面模板带 headline、文字语言和风格字段。从同模块现有模板复制结构。++## 素材++- `cover.jpg` 和预览必须**用模板本身生成**——使用库存图片或无关作品会被拒绝。+- 文件大小保持合理;这些文件随应用分发并在选择器中加载。+- 预览应代表*典型*结果,而不是五十选一的最佳样本。++## 署名与版权++如果你的模板改编自他人已发布的 prompt 或风格:++- 你必须拥有再分发的权利。+- 按现有模板的做法填写 `author` 字段,包括 `name` 和 `url`(如有头像则附 `author-avatar.jpg`)。+- 不确定时,先提 Issue 询问,再开始动手。++## 合并门槛++- [ ] 文件夹路径与 `id`/`version`/`module` 一致;ID 在模块内唯一。+- [ ] `pnpm templates:validate` 通过。+- [ ] `title` 和 `description` 同时提供 `zh-CN` 和 `en-US`。+- [ ] `defaultsByLocale` 包含两种语言调优过的 prompt。+- [ ] 封面和预览素材由模板本身生成。+- [ ] 改编外部作品时包含 `author` 署名。+- [ ] `featured: false`,`status: "published"`(或 `draft` 并在 PR 中说明)。++## 常见被拒原因++- **prompt 过于通用** —— 相比空白 prompt 没有增量价值;选择器不需要它。+- **缺少语言** —— 只调了一种语言,或机器翻译导致风格约束丢失。+- **素材不符** —— 封面与 prompt 实际生成的效果对不上。+- **版权不明** —— 改编他人作品但没有署名或授权。+- **原地修改旧版本** —— 应新建版本文件夹,而不是改写 `<id>/1/` 的历史。++---++有问题?[提一个 Issue](https://github.com/krillinai/OpenCreator/issues/new),附上你的模板想法和一个示例输出,我们会帮你明确范围。