Skip to content

Commit 034973a

Browse files
TryWorld2026TryWorld2026
committed
feat: open-source standardization + brand parameterization
- Add CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md - Add GitHub Issue templates and CI workflow (check_skills.py) - README: add environment-check step + community file links - Theme JSON: add publish_plan (title + platforms) for brand customization - notify_delivery.ps1: add -ThemeFile param, auto-discover default theme, graceful fallback on missing/corrupt theme file, fix DryRun ordering (theme parse + DryRun now work without qq-email installed) - koubo workflow.md: publish plan sourced from theme, fix stale email docs - topics selection-rules.md: channel positioning converted to editable template - theme-guide.md: document publish_plan fields
1 parent 71562eb commit 034973a

13 files changed

Lines changed: 279 additions & 30 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Bug report
2+
description: 报告一个问题
3+
title: "[Bug] "
4+
labels: ["bug"]
5+
body:
6+
- type: textarea
7+
id: what-happened
8+
attributes:
9+
label: 发生了什么
10+
description: 描述问题现象与预期行为的差异。
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: reproduce
15+
attributes:
16+
label: 复现步骤
17+
placeholder: |
18+
1. 执行了什么命令
19+
2. 看到了什么输出
20+
3. 期望看到什么
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: environment
25+
attributes:
26+
label: 环境
27+
description: 操作系统、Python/Node 版本、FFmpeg 是否可用。
28+
placeholder: "Windows 11, Python 3.12, Node 24, ffprobe MISSING"
29+
validations:
30+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Feature request
2+
description: 建议一个新功能或改进
3+
title: "[Feature] "
4+
labels: ["enhancement"]
5+
body:
6+
- type: textarea
7+
id: problem
8+
attributes:
9+
label: 你想解决什么问题
10+
description: 描述当前遇到的痛点或缺失的能力。
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: solution
15+
attributes:
16+
label: 你期望的解决方案
17+
description: 描述你希望实现的功能。
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: alternatives
22+
attributes:
23+
label: 备选方案
24+
description: 有没有其他实现方式。

‎.github/workflows/check.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: check
2+
on: [push, pull_request]
3+
jobs:
4+
check-skills:
5+
runs-on: ubuntu-latest
6+
steps:
7+
- uses: actions/checkout@v4
8+
- uses: actions/setup-python@v5
9+
with:
10+
python-version: "3.12"
11+
- run: python -X utf8 scripts/check_skills.py

‎CHANGELOG.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Changelog
2+
3+
所有显著改动记录在此文件中。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
4+
5+
## [Unreleased]
6+
7+
### Added
8+
9+
- `scripts/check_skills.py`：仓库级检查脚本，编译技能 Python 脚本并跑活人感门禁
10+
- `scripts/doctor.ps1`：环境自检脚本（Python / Node / FFmpeg / edge-tts / HyperFrames / 邮件凭证）
11+
- `CONTRIBUTING.md` 贡献指南
12+
- `CODE_OF_CONDUCT.md` 行为准则
13+
- GitHub Issue 模板与 CI workflow
14+
- 主题文件 `publish_plan` 字段：发布计划平台与时间可按品牌主题配置
15+
- 通知邮件脚本 `-ThemeFile` 参数：邮件主题与正文从主题文件读取品牌名与发布计划（可选参数，缺失时回退默认值）
16+
17+
### Changed
18+
19+
- `verify_output.py`：加固多 mp4 判 FAIL（`--video` 可指定主视频）、视频流检查、ffprobe 缺失兜底、`dur_f` 作用域修复
20+
- `verify_output.py`：兼容中文交付命名（`封面_横版4x3.png` / `封面_竖版3x4.png`）
21+
- `tts_yunxi.py`：`--theme` 参数从主题 JSON 读取默认音色
22+
- `check_prose.py`：冒号分级（引出原话放行、提示性冒号仍禁）、示例标题改为逗号 PASS
23+
- `README.md` / `README.zh-CN.md`：补入 `scripts/` 目录与检查脚本说明
24+
- `skills/tryworld-paper/README.md`：目录结构补入 `verify_output.py`、工作流图补入交付核验步骤
25+
- `skills/tryworld-paper/references/workflow.md`：发布计划.txt 补入交付清单、删重复 plan.json
26+
- `skills/tryworld-koubo/SKILL.md`：补品牌适配边界段
27+
- `examples/README.md`：披露 cursor-spacex 口播稿标点修正

‎CODE_OF_CONDUCT.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# 行为准则
2+
3+
## 我们的承诺
4+
5+
为了营造一个开放且欢迎的环境，我们作为贡献者和维护者承诺：无论年龄、体型、可见或不可见的残障、族裔、性征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、个人形象、种族、宗教或性取向如何，参与本项目的每个人都不受骚扰。
6+
7+
我们承诺以有助于开放、欢迎、多元、包容且健康的社区的方式行事和互动。
8+
9+
## 我们的标准
10+
11+
有助于营造积极环境的行为包括：
12+
13+
- 对他人表现出同理心和善意
14+
- 尊重不同的意见、观点和经历
15+
- 给予和优雅地接受建设性反馈
16+
- 承担责任、向受我们错误影响的人道歉、从中吸取教训
17+
- 关注不仅对我们个人有利、而且对整个社区有利的事情
18+
19+
不可接受的行为包括：
20+
21+
- 使用性化的语言或意象，以及任何形式的性骚扰
22+
- 恶意评论、贬低性评论或人身攻击
23+
- 公开或私下骚扰
24+
- 未经他人明确许可，发布他人的私人信息（如地址或电子邮箱）
25+
- 其他在专业环境下可合理视为不当的行为
26+
27+
## 执行责任
28+
29+
社区维护者有责任解释和执行本行为准则，并会对他们认为不当、威胁、冒犯或有害的行为采取适当且公正的纠正措施。
30+
31+
维护者有权删除与本行为准则不一致的评论、提交、代码、Issue 和其他贡献，或临时/永久封禁他们认为行为不当的任何贡献者。
32+
33+
## 范围
34+
35+
本行为准则适用于所有社区空间（Issue、PR、讨论等），也适用于个人在公共空间中正式代表社区时的行为。
36+
37+
## 执行
38+
39+
如遭遇滥用、骚扰或其他不可接受的行为，请通过仓库 owner 联系维护者。所有投诉都会得到及时和公正的审查和调查。
40+
41+
## 归因
42+
43+
本行为准则改编自 [Contributor Covenant](https://www.contributor-covenant.org) v2.1。

‎CONTRIBUTING.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# 贡献指南
2+
3+
感谢你对本项目感兴趣。在提交 PR 之前，请先阅读本指南。
4+
5+
## 行为准则
6+
7+
参与本项目即表示你同意遵守 [行为准则](CODE_OF_CONDUCT.md)。
8+
9+
## 项目结构
10+
11+
```text
12+
paper-algorithm/
13+
├── skills/ # 三个技能（口播工作流、出片、选题）
14+
│ ├── tryworld-koubo/ # 口播总入口（选题 → 写稿 → 出片路由）
15+
│ ├── tryworld-paper/ # 出片技能（视觉/配音/渲染/交付核验）
16+
│ └── tryworld-topics/ # 选题技能（AIHOT 数据 → 选题清单）
17+
├── scripts/ # 仓库级检查脚本
18+
│ ├── check_skills.py # 编译技能脚本 + 跑活人感门禁
19+
│ └── doctor.ps1 # 环境自检
20+
├── examples/ # 默认主题产出的示例
21+
└── README.md / README.zh-CN.md # 中英索引
22+
```
23+
24+
## 可以贡献什么
25+
26+
### 1. 新品牌主题
27+
28+
复制 `skills/tryworld-paper/themes/paper-algorithm.json` 为你的主题文件，按 [theme-guide.md](skills/tryworld-paper/references/theme-guide.md) 修改品牌值。PR 时：
29+
30+
- 附一版 720p 预览视频（放在 PR 描述的链接里即可，不进仓库）
31+
- 确认色板对比度 ≥ 4.5:1（大字 ≥ 3:1）
32+
- 确认新印章 SVG 右上角常驻且不遮挡内容
33+
34+
### 2. 流水线脚本改进
35+
36+
`skills/tryworld-paper/scripts/` 下的 Python 脚本（tts_yunxi / check_prose / verify_output）。PR 要求：
37+
38+
- 不破坏现有流水线契约（见 SKILL.md「流水线契约」章节）
39+
- 附加最小测试或验证步骤说明
40+
- 不引入新的第三方依赖（除非必要并在 PR 说明理由）
41+
42+
### 3. 文档改进
43+
44+
错字、表述不清、缺少说明的段落，直接改，不需要开 Issue 讨论。
45+
46+
### 4. 示例
47+
48+
欢迎提交用你自己的品牌主题产出的示例（口播稿 + 标题 + 截图链接）。示例视频本体不进仓库（体积大），PR 描述附预览链接。
49+
50+
## 不接受什么
51+
52+
- 违反流水线契约的改动（去掉用户确认闸门、去掉硬禁项检查、去掉交付核验等）
53+
- 在主题或示例中包含他人商标或未授权的音色克隆
54+
- 改变根目录 LICENSE（CC BY-SA 4.0）或 `skills/tryworld-paper/LICENSE-MIT` 的归属声明
55+
56+
## 提交流程
57+
58+
1. Fork → 新建分支 → 改动 → commit
59+
2. 本地跑通过再提交 PR：
60+
```powershell
61+
python -X utf8 scripts/check_skills.py # 应输出 All checks passed
62+
git diff --check # 应无输出
63+
```
64+
3. PR 描述写清楚：改了什么、为什么、验证方法
65+
66+
## 提问
67+
68+
Bug 或功能建议请开 [Issue](https://github.com/TryWorld2026/paper-algorithm/issues)，模板里有引导。

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ That's it. The request is recognized and routed through the whole pipeline autom
6969

7070
**3 · Receive** — the pipeline ends with the rendered video, horizontal/vertical covers, platform titles, captions, a four-platform publish plan, and an automatic email notice.
7171

72+
**Check your setup** — run `python -X utf8 scripts/check_skills.py` (should output `All checks passed`) and `powershell -File scripts/doctor.ps1` (lists missing tools) before producing your first video. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute, [CHANGELOG.md](CHANGELOG.md) for recent changes, and the [Code of Conduct](CODE_OF_CONDUCT.md).
73+
7274
---
7375

7476
## 📑 Contents

‎README.zh-CN.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ Copy-Item -Path .\skills\* -Destination "$env:USERPROFILE\.agents\skills" -Recur
6969

7070
**第 3 步 · 收货**——流水线末端交付：渲染成片、横竖封面、平台标题、字幕、四平台发布计划，外加一封自动邮件通知。
7171

72+
**检查环境**——出第一条视频前，先跑 `python -X utf8 scripts/check_skills.py`（应输出 `All checks passed`）和 `powershell -File scripts/doctor.ps1`（列出缺失工具）。参与贡献见 [CONTRIBUTING.md](CONTRIBUTING.md)，近期改动见 [CHANGELOG.md](CHANGELOG.md)，社区准则见 [行为准则](CODE_OF_CONDUCT.md)。
73+
7274
---
7375

7476
## 📑 目录

‎skills/tryworld-koubo/references/workflow.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -107,10 +107,9 @@ Get-ChildItem -LiteralPath "E:\Codex口播视频" -Directory | ForEach-Object {
107107
- cover_4x3.png / cover_3x4.png
108108
- titles.txt
109109
- narration.mp3、sentences.json（字幕时间轴）、plan.json
110-
- 发布计划.txt（固定内容）
111-
112-
发布计划.txt 内容模板：
110+
- 发布计划.txt（内容以当前主题文件的 `publish_plan` 为准，见下方模板）
113111

112+
发布计划.txt 内容以当前主题文件的 `publish_plan` 字段为准。自定义品牌主题时，在主题 JSON 的 `publish_plan.platforms` 数组中定义你的平台与时间，脚本与文档将自动使用。默认主题（试界TryWorld）的值如下：
114113
```
115114
试界TryWorld · 平台发布计划
116115
小红书：中午 12:30
@@ -127,7 +126,9 @@ B站：晚上 20:30
127126
powershell -File "$env:USERPROFILE\.agents\skills\tryworld-koubo\scripts\notify_delivery.ps1" -ProjectDir "E:\Codex口播视频\<项目slug>"
128127
```
129128

130-
- 邮件内容：主题 `✅ TryWorld 口播成片已交付 · <项目> · <日期>`；正文 = 完成提示 + 【平台标题】文字（读取 titles.txt 直接写入正文，不作为附件）+ 【四平台发布计划】。
129+
- 邮件主题与发布计划从主题文件（`paper-algorithm.json` 或 `-ThemeFile` 指定的文件）读取 `brand.platform_name` 与 `publish_plan`；文件缺失或字段不存在时回退到硬编码默认值。
130+
131+
- 邮件内容：主题 `✅ {品牌名} 口播成片已交付 · <项目> · <日期>`（品牌名取自主题文件 `brand.platform_name`）；正文 = 完成提示 + 【平台标题】文字（读取 titles.txt 直接写入正文，不作为附件）+ 【发布计划】（内容取自主题文件 `publish_plan`）。
131132
- 附件规则（QQ 邮箱附件上限约 50MB，含 base64 开销，单文件安全阈值 35MB）：
132133
- 横版封面 / 竖版封面：总是作为附件；
133134
- 平台标题：不附文件，文字写入正文；

‎skills/tryworld-koubo/scripts/notify_delivery.ps1‎

Lines changed: 33 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,31 @@
11
# tryworld-koubo · 成片交付邮件通知（Windows PowerShell）
2-
# 用法: powershell -File scripts/notify_delivery.ps1 -ProjectDir <项目目录> [-DryRun]
2+
# 用法: powershell -File scripts/notify_delivery.ps1 -ProjectDir <项目目录> [-ThemeFile <主题JSON路径>] [-DryRun]
33
param(
44
[string]$ProjectDir = (Get-Location).Path,
55
[string]$Recipient = "",
6+
[string]$ThemeFile = "",
67
[switch]$DryRun
78
)
89
$ErrorActionPreference = "Stop"
910

10-
$qqCandidates = @(
11-
(Join-Path $env:USERPROFILE ".agents\skills\qq-email"),
12-
(Join-Path $env:USERPROFILE ".codex\skills\qq-email")
13-
)
14-
$qqEmailSkill = $qqCandidates | Where-Object { Test-Path -LiteralPath (Join-Path $_ "scripts\send.js") } | Select-Object -First 1
15-
if (-not $qqEmailSkill) {
16-
Write-Warning "未找到 qq-email 技能(请安装到 ~/.agents/skills 或 ~/.codex/skills),跳过邮件通知(不阻塞交付)。"
17-
exit 0
11+
12+
# ---- 主题文件：品牌名与发布计划（可选；缺失时用硬编码默认值） ----
13+
if ($ThemeFile -and -not (Test-Path -LiteralPath $ThemeFile)) { Write-Warning ("指定的主题文件不存在: " + $ThemeFile + "，使用默认品牌值") }
14+
$defaultTheme = Join-Path $PSScriptRoot "..\..\tryworld-paper\themes\paper-algorithm.json"
15+
$themePath = if ($ThemeFile) { $ThemeFile } elseif (Test-Path -LiteralPath $defaultTheme) { $defaultTheme } else { "" }
16+
$brandName = "TryWorld"
17+
$planTitle = "试界TryWorld · 平台发布计划"
18+
$planLines = @("小红书：中午 12:30","抖音：晚上 19:30","B站：晚上 20:30","微信视频号：晚上 20:30")
19+
if ($themePath -and (Test-Path -LiteralPath $themePath)) {
20+
try {
21+
$cfg = Get-Content -LiteralPath $themePath -Raw -Encoding UTF8 | ConvertFrom-Json
22+
if ($cfg.brand.platform_name) { $brandName = $cfg.brand.platform_name }
23+
if ($cfg.publish_plan.title) { $planTitle = $cfg.publish_plan.title }
24+
if ($cfg.publish_plan.platforms) {
25+
$planLines = @($cfg.publish_plan.platforms | ForEach-Object { "{0}：{1}" -f $_.name, $_.time })
26+
}
27+
} catch { Write-Warning "主题文件解析失败，使用默认品牌值: $themePath" }
1828
}
19-
$sendJs = Join-Path $qqEmailSkill "scripts\send.js"
2029
$VideoAttachLimitMB = 35 # QQ 邮箱附件上限约 50MB,含 base64 开销,单文件安全阈值 35MB
2130

2231
# ---- 收集产物 ----
@@ -53,7 +62,7 @@ $attachments = @($videoAttach, $coverH.FullName, $coverV.FullName) | Where-Objec
5362

5463
$proj = Split-Path -Leaf $ProjectDir
5564
$date = Get-Date -Format "yyyy-MM-dd"
56-
$subject = "✅ TryWorld 口播成片已交付 · $proj · $date"
65+
$subject = "✅ $brandName 口播成片已交付 · $proj · $date"
5766
$body = @"
5867
成片已交付，产物已作为附件随邮件发送：
5968
@@ -62,11 +71,8 @@ $videoNote
6271
【平台标题】
6372
$titlesText
6473
65-
【四平台发布计划】
66-
小红书：中午 12:30
67-
抖音：晚上 19:30
68-
B站：晚上 20:30
69-
微信视频号：晚上 20:30
74+
【发布计划】
75+
$($planLines -join "`n")
7076
7177
—— tryworld-koubo 自动通知
7278
"@
@@ -82,6 +88,17 @@ if ($DryRun) {
8288
exit 0
8389
}
8490

91+
$qqCandidates = @(
92+
(Join-Path $env:USERPROFILE ".agents\skills\qq-email"),
93+
(Join-Path $env:USERPROFILE ".codex\skills\qq-email")
94+
)
95+
$qqEmailSkill = $qqCandidates | Where-Object { Test-Path -LiteralPath (Join-Path $_ "scripts\send.js") } | Select-Object -First 1
96+
if (-not $qqEmailSkill) {
97+
Write-Warning "未找到 qq-email 技能(请安装到 ~/.agents/skills 或 ~/.codex/skills),跳过邮件通知(不阻塞交付)。"
98+
exit 0
99+
}
100+
$sendJs = Join-Path $qqEmailSkill "scripts\send.js"
101+
85102
# ---- 凭证检查(进程环境变量 -> 注册表用户环境变量) ----
86103
if (-not $env:QQ_EMAIL_ACCOUNT) {
87104
try { $reg = Get-ItemProperty -Path "HKCU:\Environment" -Name QQ_EMAIL_ACCOUNT -ErrorAction Stop; $env:QQ_EMAIL_ACCOUNT = $reg.QQ_EMAIL_ACCOUNT } catch { }

0 commit comments

Comments
 (0)