nite/video-edit-planner-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify Windows uv execution from WSL

Browse Source 
- Document that Windows uv should not run from WSL UNC paths
- Recommend cloning the skill repo on Windows or copying scripts/transcription to C:\...
- Add PowerShell setup examples for Windows-local transcription directory
- Update long-running operations and pitfalls to require Windows local paths
This commit is contained in:
nite
2026-07-14 13:59:20 +08:00
parent 8b353c99bc
commit 3c4a0de8a5
2 changed files with 159 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SKILL.md
+61 -12
View File
@@ -66,16 +66,28 @@ Ask the user for:
### Step 3 — Ask editing requirements
Before transcribing, ask the user what they want to do with the video. Examples:
Before transcribing, ask the user what they want to do with the video. User requirements are often vague in the first pass — that's expected. The plan is refined iteratively.
- "Trim out dead air and boring parts"
- "Make a highlight reel of funny moments"
- "Plan transitions between scenes"
- "Find the best 30-second clip for a short"
If the agent's runtime supports structured questioning (e.g., a `clarify` tool or a `grill-me` skill), use it to gather requirements systematically. Ask questions one at a time with multiple-choice options — this is much more effective than a free-text wall of questions.
User requirements are often vague in the first pass — that's expected. The plan is refined iteratively. If the agent's runtime supports loading additional skills and a skill for structured interviewing (e.g., `grill-me`) is available, the agent may load it to sharpen the user's requirements through targeted questions.
**The requirements questionnaire below covers the key axes for gameplay/creator video editing.** Not every question applies to every session — pick the relevant ones based on the user's initial request. See `references/editing-requirements-questionnaire.md` for the full questionnaire with choices.
**Completion criteria:** user has described at least a rough editing goal.
| Axis | Why it matters |
|---|---|
| Target platform (B站/抖音/YouTube/Shorts) | Determines aspect ratio, pacing, subtitle density, meme/热梗 density |
| Narrative style (搞笑集锦/故事线+搞笑/高光混剪) | Determines structure: pure clip reel vs. narrative arc with 起承转合 |
| Role distribution (主视角/平权联机/主持人) | Determines whose voice/reactions to prioritize in cuts |
| Effect density (少量/中等/高密度) | Determines how many 表情包/贴纸/特效 to search for and apply |
| Editor tool (Premiere Pro/剪映/DaVinci/必剪) | Determines how specific transition/effect instructions are phrased |
| First edit or existing draft | Determines whether to plan from scratch or optimize existing cuts |
| BGM style preference | Determines BGM search/recommendation direction |
| Number of participants | Determines how to handle multi-person interaction and voice allocation |
| Audio handling (保留原声+字幕/重新配音/混合) | Determines subtitle work, BGM vs voice balance, and narration needs |
| Privacy (露脸+声音/不露脸声音OK/需打码变声) | Determines face-cam handling and any masking needs |
| Output format (时间戳笔记/脚本表格/分镜方案) | Determines deliverable detail level |
| Target duration | Determines how aggressively to cut and pace the content |
**Completion criteria:** user has described at least a rough editing goal, and the agent has probed the relevant axes above.
### Step 4 — Transcribe audio
@@ -87,7 +99,16 @@ Use the bundled `funasr-script` in `scripts/transcription/`. **Prefer Fun-ASR-Na
**Transcription can be long-running.** The agent should generate the transcription command and **give it to the user to execute manually**, rather than running it in the agent's own environment. This avoids blocking the conversation and allows the user to run it on a more powerful machine if needed.
**If the agent detects it is running in WSL**, it should provide PowerShell commands for the user to run on the Windows host, not Linux commands. For example, convert the SKILL_DIR and VIDEO_PATH to their Windows equivalents (e.g., `C:\Users\...` instead of `/mnt/c/...`).
**Critical: when you tell the user you will provide a command, include it immediately in the same response.** Do not say "I'll give you the transcription command" and then move on to other topics without actually printing the command. The user should never have to ask "you said you'd give me the command but didn't."
**If the agent detects it is running in WSL**, it should provide PowerShell commands for the user to run on the Windows host, not Linux commands. For example, convert the SKILL_DIR and VIDEO_PATH to their Windows equivalents (e.g., `C:\Users\...` instead of `/mnt/c/...`). However, if the user is comfortable running commands directly in WSL (e.g., they use WSL as their primary terminal), Linux commands with `/mnt/...` paths are fine — assess the user's environment before deciding.
**WSL constraint: uv cannot run from WSL UNC paths.** If the skill is installed inside the WSL filesystem (e.g., `~/.hermes/skills/...`), the Windows `uv` command cannot operate on it directly via UNC paths like `\\wsl.localhost\...` — it will fail with directory errors. When the agent detects WSL and the skill lives in the WSL filesystem, it should give the user one of these options:
1. **Clone the repo on Windows** (recommended): `git clone https://git.nite07.com/nite/video-edit-planner-skill.git C:\Users\<user>\video-edit-planner` then run `uv` from `C:\Users\<user>\video-edit-planner\scripts\transcription`.
2. **Let the agent copy the scripts**: the agent copies `scripts/transcription/` to a Windows path (e.g., `/mnt/c/Users/<user>/AppData/Local/Temp/vedit-transcription/`) and gives the user a PowerShell command pointing there.
Either way, the transcription command the user receives should use a **Windows local path** (`C:\...`), never a UNC path.
Command templates (adjust paths for the user's environment):
@@ -104,8 +125,20 @@ uv run --directory SKILL_DIR/scripts/transcription funasr-nano VIDEO_PATH --list
Where `VIDEO_DIR` is the directory containing the video file, and `SKILL_DIR` is the skill installation directory.
**Common OBS multi-track audio layouts.** When the user says "multi-track" or mentions OBS recording, these are the typical stream layouts:
| Track | Typical content |
|---|---|
| Stream 1 (index 1) | Game audio (desktop/system sound) |
| Stream 2 (index 2) | Microphone (commentary/narration) |
| Stream 3 (index 3) | Discord/voice chat (other participants) |
Always verify with `ffprobe` before transcribing — the user may have a different layout. When the user says "transcribe the mic and Discord tracks", that typically means tracks 2 and 3.
**Multi-track transcription:** when the user provides multiple track indexes (e.g., track 1 = mic, track 2 = Discord), run the transcription command **once per track**. Each run produces a separate JSON file named `<video_stem>_track<INDEX>_<model>.json`. Record each transcription in the index (Step 5) with its corresponding track index. When answering user questions, the agent should cross-reference all available transcripts to understand the full conversation context.
**Note on Discord audio quality:** Discord tracks may contain noise, crosstalk, or non-participant chatter. This is normal — the ASR transcript will be noisier. When cross-referencing transcripts, treat Discord track content as supplementary context, not as the primary narrative source.
**Skip if cached:** check the index file (Step 5) for existing transcription entries. If a record exists for the same track index and the video file hasn't changed, reuse it.
**Completion criteria:** a transcription JSON exists for every requested track, and each is recorded in the index. Each JSON contains `segments` with timestamps and text.
@@ -336,8 +369,9 @@ Some material sites may block automated access (anti-bot, Cloudflare, CAPTCHA).
Before any operation expected to take >1 minute (first-time `uv sync`, transcription of long videos, large frame extraction):
1. **Generate the command and give it to the user to execute manually**, rather than running it in the agent's own environment. This avoids blocking the conversation and lets the user run it on a more powerful machine (e.g., a Windows host while the agent runs in WSL).
2. If the agent runs in WSL, provide PowerShell commands with Windows paths (e.g., `C:\Users\...` instead of `/mnt/c/...`) for the user to run on the Windows host.
3. After the user reports completion, the agent should verify the output exists before proceeding.
2. If the agent runs in WSL, provide PowerShell commands with Windows local paths (e.g., `C:\Users\...` instead of `/mnt/c/...`) for the user to run on the Windows host.
3. Do not point Windows `uv` at `\\wsl.localhost\...` or `\\wsl$\...` paths. Put/clone/copy the transcription project under a Windows local directory first, then run `uv` there.
4. After the user reports completion, the agent should verify the output exists before proceeding.
## Self-contained setup
@@ -349,7 +383,20 @@ cd SKILL_DIR/scripts/transcription && uv sync
This creates an isolated venv with `funasr`, `torch`, `torchaudio`. If the user has previously installed these packages via uv in other projects, uv's cache will reuse them — first-time cost is only the link step.
If the agent runs in WSL, it should provide the equivalent PowerShell command with Windows paths for the user to run on the Windows host.
If the agent runs in WSL and the skill is installed under the WSL filesystem, do **not** run Windows `uv` against the WSL path. Instead, tell the user to prepare a Windows-local copy of the transcription project first:
```powershell
# Option A: clone the full skill repo on Windows (recommended)
git clone https://git.nite07.com/nite/video-edit-planner-skill.git "$env:USERPROFILE\\video-edit-planner-skill"
Set-Location "$env:USERPROFILE\\video-edit-planner-skill\\scripts\\transcription"
uv sync
# Option B: after the agent copies scripts/transcription to a Windows-local directory
Set-Location "C:\\Users\\<user>\\AppData\\Local\\Temp\\vedit-transcription"
uv sync
```
Subsequent transcription commands should also use that same Windows-local transcription directory.
## Common pitfalls
@@ -364,7 +411,9 @@ If the agent runs in WSL, it should provide the equivalent PowerShell command wi
9. **Hardcoding output language.** The edit plan table and all user-facing text must follow the user's language, not a fixed language. The English table in Step 8 is a template — translate columns and content to match the user's language at runtime.
10. **Dropping audio tracks during clip extraction.** The default clip command maps only `0:v:0` (video-only) for fast frame extraction. If the user plans to import the clip into a video editor, use `--all-streams` (or `-map 0`) to preserve all audio tracks. Always ask the user which they need.
11. **Using `~/whisperx_output/` or other separate output directories.** All artifacts (transcription JSON, clips, frames, index file) must go in the same directory as the video file. The `--output-dir` flag should always point to the video's own directory. This keeps everything co-located and portable.
12. **Running transcription commands in the agent's own environment.** Transcription is long-running and resource-intensive. Generate the command and give it to the user to execute on their host machine. If the agent runs in WSL, provide PowerShell commands with Windows paths.
12. **Running transcription commands in the agent's own environment.** Transcription is long-running and resource-intensive. Generate the command and give it to the user to execute on their host machine. If the agent runs in WSL, provide PowerShell commands with Windows local paths. Never ask Windows `uv` to run from `\\wsl.localhost\...` / `\\wsl$\...`; clone or copy the transcription project to `C:\...` first.
13. **Saying you'll provide a command but not including it.** If you mention giving the user a transcription command, include it immediately in that same response. Do not move on to other content without printing the actual command. The user should never have to ask for it.
14. **Sending a wall of free-text questions.** When gathering editing requirements, use structured one-at-a-time multiple-choice questions via the runtime's clarify/prompt tool. This is far more effective than dumping 10 questions as a paragraph.
## Verification checklist
references/editing-requirements-questionnaire.md
+98
View File
@@ -0,0 +1,98 @@
# Editing Requirements Questionnaire
Structured questions for gathering video editing requirements. Ask one at a time with multiple-choice options via the runtime's clarify/prompt tool. Not all questions apply to every session — pick relevant ones based on the user's initial request.
## Questions
### 1. Target platform
Determines aspect ratio, pacing, subtitle density, meme/热梗 density.
- B站为主（横屏，节奏可稍快但要有内容铺垫，弹幕文化，表情包/热梗可多）
- B站+抖音/Shorts 双发（横屏原版+竖屏剪辑版，快节奏高密度）
- B站+YouTube（横屏，节奏偏中速，注意海外观众也能理解）
- 抖音/TikTok 为主（竖屏，极快节奏，高密度表情包）
### 2. Narrative style
Determines structure: pure clip reel vs. narrative arc.
- 搞笑集锦向：把最爆笑/混乱的瞬间拼在一起，重娱乐轻叙事
- 故事线+搞笑混搭：有一条简单主线，穿插搞笑片段，有起承转合
- 高光混剪向：以精彩操作/翻盘/团灭瞬间为主，偏燃向或反差搞笑
### 3. Role distribution
Determines whose voice/reactions to prioritize.
- 你是主视角/主要叙事者，其他人配合你推进进度
- 大家平权联机，谁有有趣发言/操作就突出谁，没有固定主角
- 你是主持人/吐槽担当，主要靠你的解说和反应推动节奏
### 4. Effect density
Determines how many 表情包/贴纸/特效 to search for.
- 少量点级，自然过渡就行，不需要加额外的表情包/贴纸素材
- 中等密度，关键笑点配表情包/热梗贴纸，转场要明显但不花哨
- 高密度，每个笑点都要有视觉强化（放大镜、抖动、表情包、弹幕特效等）
### 5. Editor tool
Determines how specific transition/effect instructions are phrased.
- Premiere Pro
- 剪映专业版（电脑端）
- DaVinci Resolve
- 必剪
### 6. First edit or existing draft
Determines whether to plan from scratch or optimize existing cuts.
- 是首次剪辑，从零开始规划结构
- 我已经有个粗剪/草稿，需要你帮我优化
- 我已经做过一些片段标注，需要你帮我串联
### 7. BGM style
Determines BGM search/recommendation direction.
- 让我根据内容自动推荐（轻松日常+搞笑节奏为主，战斗段落配燃向）
- 轻松日常类为主（轻松、愉快、休闲氛围）
- 搞笑节奏类为主（快节奏、夸张、踩点）
- 燃向战斗类为主（打僵尸/Boss时燃起来）
### 8. Number of participants
Determines how to handle multi-person interaction and voice allocation.
- 2-3人（小队联机）
- 4-5人（中型队伍）
- 6-8人（满编大队伍）
### 9. Audio handling
Determines subtitle work, BGM vs voice balance, and narration needs.
- 保留原声，加字幕即可（观众能听到对话和反应）
- 保留原声，不需要加字幕
- 需要重新配音/旁白，原声只保留精彩反应片段
- 混合：大部分加字幕保留原声，关键段落加旁白解说
### 10. Privacy
Determines face-cam handling and any masking needs.
- 可以公开露脸/出声音，正常剪辑就行
- 不要露脸，但声音无所谓
- 需要打码/变声处理（不方便露脸或露声）
### 11. Output format
Determines deliverable detail level.
- 简单文字标注（时间戳笔记，如「00:12:30 这里很好笑」）
- 详细剪辑脚本表格（时间码、片段描述、保留原因、转场建议、素材需求）
- 可执行分镜方案（每个片段的入点出点、转场方式、素材位置、BGM时间线）
### 12. Target duration
Determines how aggressively to cut and pace the content.
- User specifies a target (e.g., 7-8 minutes, 10 minutes, 3 minutes)
## Usage notes
- Ask one question at a time. The runtime's clarify tool with multiple-choice options works best.
- Not all 12 questions are needed every session. If the user's initial request already answers some axes, skip those.
- The questions can be asked in any order, but platform → narrative style → effect density → editor tool is a natural priority flow.
- If a `grill-me` skill is available, it can be loaded to add follow-up depth questions beyond this template.