核心分析¶

问题核心：哪些环境/依赖最可能导致 Skill 部分失效？如何在工程实践中规避？

技术分析（问题点）¶

• 外部 CLI/库缺失：如 pdftotext、pdfplumber、pandas 等若未安装，会导致 PDF/Excel 解析失败。
• TTS/图像后端凭证缺失或不兼容：示例提供多个适配器（mmx-cli、OpenAI TTS、ElevenLabs），若未正确注入 API 密钥或网络不可达，合成将失败。
• Agent 能力限制：在不能运行代码、上传文件或执行外部进程的 Agent 中，某些 Skill 会退化为“仅提示顾问”模式，丧失自动化执行价值。

实用规避策略¶

1. 建立依赖清单与自动检查脚本：把必须的 CLI 和 Python 库列为安装步骤，并提供 check_env.sh 或 Node 脚本在 CI/本地验证。
2. 安全注入凭证：使用环境变量或秘密管理器注入 TTS/API 密钥，避免把凭证写入仓库。
3. 启用 mode-detection 并设计回退流程：允许 Skill 在无执行能力时输出可复制的实现片段或明确的手动步骤（避免 silent failure）。
4. 分阶段验证：先在受控小样本（短文档、低分辨率图像）上跑端到端，确认解析、节拍映射与 TTS 能正常工作。

重要提示：运行环境和凭证是让这些工程化 Skill 产生真实价值的前提。若不能确保外部依赖与 agent 能力，项目更多呈现为可读的设计与模板而非自动化交付工具。

总结：通过自动化环境检查、秘密管理、mode-detection 的回退策略和小规模端到端验证，可大幅降低 Skill 部分失效的风险，提升可用性。

核心分析¶

问题核心：怎样在 CI/CD 中验证 Skill 的视觉、音频与检索证据输出，确保交付可重现且可审计？

技术分析¶

• 视觉验证：使用无头浏览器（Puppeteer/Playwright）在 CI 中渲染 Scaffold 输出，做以下断言：截图像素比对（视觉回归）、重要 DOM/ARIA 元素存在性、舞台尺寸（1920×1080）与节拍对应行为。
• 音频验收：对合成音频做时长一致性检查、简单语音转文本（ASR）校验关键短语，或计算音频指纹/能量分布以检测空音或截断。
• 检索证据校验：验证 kb-retriever 的检索日志（检索轮次、文档 ID、页码/段落片段）与期望源一致；对相似度阈值做断言，避免盲目引用低置信度来源。

实践步骤（在 CI 中实现）¶

1. 版本化输入：保存 prompts、theme-token、脚本与模型版本到构建工件（artifact）。
2. 渲染测试：在 CI 中构建 Scaffold，使用 Puppeteer 拍摄关键帧并与基线截图做视觉回归测试。
3. 音频测试：合成短段音频并用 ASR 或关键字匹配验证内容与时长。
4. 检索测试：运行检索 Skill 的测试套件，断言返回来源的文档 ID 与片段并保存检索日志到 artifact。
5. 审计记录：把所有输出（截图、音频、检索日志）作为 CI artifact 保存用于回溯。

重要提示：测试应限定环境变量与外部服务调用（或使用 mock/stub）以保证 CI 的确定性与成本可控。

总结：把视觉渲染、音频合成与检索证据纳入 CI 流水线，并版本化 inputs/outputs，是实现 garden-skills 可重现、可审计交付的核心工程实践。

核心分析¶

问题核心：在面对大型或多格式文档时，如何既保持检索效率又确保答案可以被审计与溯源？

技术分析¶

• 分层索引（hierarchical indexing）：先建立高层索引（文档→章节→段落），通过粗筛快速定位候选区域，再对候选段落做精读或矢量索引查询，这减少了对模型上下文的冗余输入。
• “先读参考再处理”规则：在处理如 PDF/Excel 时先抽取摘要/表头结构，再据此决定是否要载入更详细内容，避免一次性加载整个原文。
• 受控多轮检索：限制检索轮数和每轮返回的候选段落数，减少检索膨胀与成本，同时在每轮明确记录来源（文档 ID、页码、段落片段）。

实用建议¶

1. 配置索引等级：为大型文档设置章节级与段落级索引，先在章节级做召回，再做段落级验证。
2. 记录检索元数据：在 Skill 执行中持久化检索日志（检索轮次、来源、相似度分数），以便审计与回溯。
3. 设置检索预算：限定每次查询的候选数与最大检索轮数（例如最多 3 轮、每轮最多 5 段），在准确率和成本之间做权衡。

重要提示：检索的可审计性依赖于你在 Skill 中显式保存检索元数据与版本化结果，否则模型回答虽可能正确但不可溯源。

总结：kb-retriever 通过分层索引与受控多轮策略在效率与证据审计之间提供了实用折中；为生产使用，务必实现检索日志与限定检索预算以保证可追溯性与成本可控。

核心分析¶

问题核心：为什么采用 Skill 单元化？它对交付、复用与可审计性带来了哪些实际益处与工程上的限制？

技术分析¶

• 模块化与职责分离：每个 Skill 封装具体交付（如 web-design-engineer、gpt-image-2），包含 scaffold、prompt 模板与适配器，便于独立开发、审查与替换单个能力。
• 可复用的工程样板：Scaffold（Vite+React+TS）降低从原型到交付的实现成本，使非零起点快速可运行。
• 运行时模式探测：三模式（本地/宿主/仅提示）允许 Skill 根据运行环境自动退化或切换执行策略，提高跨平台鲁棒性。

优势¶

• 测试与审计更容易：单个 Skill 的输入/输出、检查点、证据引用点清晰，可在 CI 中做视觉回归与检索一致性测试。
• 替换与扩展友好：TTS、图像后端或解析器作为适配器可插拔，便于集成不同第三方服务。

限制与注意事项¶

1. 跨 Skill 协调缺省：项目未内建队列或集中调度，跨 Skill 的状态与资源管理需要额外工程（例如任务队列或共享索引服务）。
2. 并发与规模化场景：默认更适合单次/开发者级使用，若需大规模并发处理需做水平扩展设计。
3. 环境依赖与运行能力：Skill 假定 agent 平台能运行代码或上传文件，否则会退化为仅提示文本。

重要提示：采用 Skill 架构能显著提升工程化交付速度与可审计性，但在部署成面向大量并发用户的服务时需补充作业调度、横向扩展和权限管理。

总结：Skill 为单元化工程实践提供了明确边界与复用价值，非常适合迭代开发与团队协作；对高并发或分布式协调的需求，则需要在 Skill 之上构建额外基础设施。

核心分析¶

问题核心：内容创作者（非工程背景）如何评估 web-video-presentation 的学习成本，并以最小阻力路径上手？

技术分析¶

• 学习门槛来源：主因在于 scaffold（Vite+React+TS）与外部依赖（TTS CLI、构建工具）需要一定工程能力来安装与运行。
• 可简化的路径：Skill 的核心价值在于节拍化脚本与主题 token。非工程用户可以先利用这些结构化产出（脚本、节拍时间线、主题配方）而不直接跑完整前端脚手架。

最佳上手流程（分步）¶

1. 阅读并复制脚本模板：打开 SKILL.md，使用 README 示例把原始文案转换为节拍驱动的脚本（chapter/step）。
2. 生成视觉大纲与主题选择：用内置 23 个主题中的一个来填充 theme-token，得到视觉风格建议与素材需求清单。
3. 先行手动预览：把脚本导出为静态 HTML 或 PPT（若有导出工具），进行屏幕录制测试，确认节拍与视觉节奏。
4. 逐步自动化：在获得工程支持后，运行 Scaffold（或请前端工程师拉取并构建），配置 TTS 以合成最终 narration。

重要提示：如果团队无法维护 Node/TS 环境，可以在第一阶段只使用脚本与主题产出，等到确认视觉方向后再做工程化实现。

总结：非工程背景用户建议采用“脚本化产出 → 主题化预览 → 手动导出 → 工程化交付”的渐进流程，以最小阻力验证创意并逐步接入完整的录制就绪流水线。