Skip to content
Back to search

teacher-to-skills

Distill a teacher into a coaching Skill. Turn their courses, books, video, audio, PDFs, slides, transcripts, OCR, notes, and long-form materials into source-grounded learning Skills that teach unseen concepts progressively with reliable terminal ASCII or SVG visuals, ask two end-of-lesson questions together by default, give focused feedback, schedule review, test transfer, and support independent work. Also use for CoursePackage migration, teacher-method extraction, learning paths, practice and assessment libraries, private learner-state workflows, reusable personal methods, and graduation evaluation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/juneyaooo--lineage-skill/badge.svg)](/listings/juneyaooo--lineage-skill)

HTML

<a href="/listings/juneyaooo--lineage-skill"><img src="/api/listings/juneyaooo--lineage-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 244 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: teacher-to-skills
  3. description: Distill a teacher into a coaching Skill. Turn their courses, books, video, audio, PDFs, slides, transcripts, OCR, notes, and long-form materials into source-grounded learning Skills that teach unseen concepts progressively with reliable terminal ASCII or SVG visuals, ask two end-of-lesson questions together by default, give focused feedback, schedule review, test transfer, and support independent work. Also use for CoursePackage migration, teacher-method extraction, learning paths, practice and assessment libraries, private learner-state workflows, reusable personal methods, and graduation evaluation.
  4. ---
  5. # Teacher-to-Skills
  6. Distill a teacher's source material into a mentor Skill that can cite the source, demonstrate the teacher's method, guide practice, correct mistakes, and gradually reduce the learner's dependence on help.
  7. Use this method:
  8. **Capture → Cite → Compress → Connect → Codify → Coach → Practice → Consolidate → Transfer → Graduate**
  9. Preserve evidence before synthesis. Require observable learner work before mastery. Keep immutable teacher assets separate from private learner state.
  10. ## Read when needed
  11. - Pipeline, providers, schemas, recovery, and output layouts: [references/runtime.md](references/runtime.md)
  12. - Session routing, attempt-first assessment, feedback, and fading: [references/apprenticeship-protocol.md](references/apprenticeship-protocol.md)
  13. - Progressive concept teaching, SVG/ASCII explanation, and the two-question check: [references/micro-lesson-protocol.md](references/micro-lesson-protocol.md)
  14. - Claim and feedback provenance: [references/provenance-policy.md](references/provenance-policy.md)
  15. - Mastery transitions and review scheduling: [references/mastery-policy.md](references/mastery-policy.md)
  16. - Graduation evidence: [references/graduation-policy.md](references/graduation-policy.md)
  17. - External learner-state boundary: [references/external-learner-store-contract.md](references/external-learner-store-contract.md)
  18. ## Product invariants
  19. - Trace teacher claims to source, lesson, timestamp, chunk, card, keyframe, or page.
  20. - Distinguish `direct_source`, `source_grounded_synthesis`, `cross_source_synthesis`, `mentor_inference`, learner evidence, external knowledge, and unsupported content.
  21. - Preserve conflicting sources and their conditions; never flatten disagreement into false consensus.
  22. - Treat TeacherModel as source-supported domain behavior, not a personality or consciousness clone.
  23. - Treat recognition, fluency, lesson completion, and one success as insufficient mastery evidence.
  24. - Require an observable attempt before updating capability state.
  25. - Teach one unseen capability with a plain-language model, precise explanation, useful ASCII/SVG visual, example, counterexample, and exactly two end-of-lesson questions presented together by default.
  26. - Advance at most one mastery state per successful episode.
  27. - Require changed-context H0 performance for transfer and delayed parallel-form success for retention.
  28. - Keep PracticeEpisodes append-only and rebuild MasteryState from events.
  29. - Store real learner data only in a host-provided external private directory.
  30. - Require explicit learner approval before promoting or installing a Personal Skill.
  31. - Keep high-risk learning educational, source-bounded, and distinct from professional qualification.
  32. ## Detect source state
  33. Choose the smallest workflow that preserves the requested evidence:
  34. 1. Raw video/audio: run capture, visual analysis for video, model-selected keyframes, distillation, audit, compilation, generation, and validation.
  35. 2. Video plus PDFs: include document parsing or reuse existing OCR.
  36. 3. Markdown/TXT/books/notes/OCR: skip media capture; build text chunks and evidence cards before compilation.
  37. 4. Existing transcripts, analyses, documents, or distillation: resume from the narrowest missing stage.
  38. 5. Existing CoursePackage 0.x: migrate to 1.0 before building teacher/runtime assets.
  39. 6. Existing CoursePackage 1.0: compile missing TeacherModel, graph, banks, MentorPackage, and Skill.
  40. 7. Multiple CoursePackages: migrate each, merge with namespaced IDs, preserve conflicts, then compile.
  41. Do not rerun expensive capture when stable artifacts already exist and inputs have not changed.
  42. ## Configure providers
  43. Separate capability from configuration. Report missing configuration and the smallest viable fallback.
  44. - Audio transcription: `AUDIO_TRANSCRIBE_API_KEY`, `AUDIO_TRANSCRIBE_BASE_URL`, `AUDIO_TRANSCRIBE_MODEL`.
  45. - Video/vision: `TEACHER_TO_SKILLS_VISION_API_KEY`, `TEACHER_TO_SKILLS_VISION_BASE_URL`, `TEACHER_TO_SKILLS_VISION_MODEL`.
  46. - Text distillation: `TEACHER_TO_SKILLS_TEXT_API_KEY`, `TEACHER_TO_SKILLS_TEXT_BASE_URL`, `TEACHER_TO_SKILLS_TEXT_MODEL` when LLM distillation is enabled.
  47. - PDF/OCR submission: `MINERU_API_TOKEN`, unless existing OCR is reused.
  48. - Local media: `ffmpeg` and `ffprobe`.
  49. If raw media needs an unavailable provider, stop before that capture stage. If transcripts, OCR, notes, or packages already exist, continue from them and report excluded modalities. Never store secrets in the repository or commit `.env`.
  50. ## Run the full compiler
  51. For media and documents:
  52. ```bash
  53. python scripts/run_course_pipeline.py \
  54. --input-dir <course-media> \
  55. --documents-input <pdf-or-directory> \
  56. --notes-input <notes> \
  57. --course-name <course-name> \
  58. --skill-name <skill-name> \
  59. --mode mentor \
  60. --apprenticeship full \
  61. --practice-depth deep \
  62. --learner-state external \
  63. --output-dir ./dist
  64. ```
  65. For text or books:
  66. ```bash
  67. python scripts/run_course_pipeline.py \
  68. --text-input <markdown-txt-or-directory> \
  69. --course-name <course-name> \
  70. --mode mentor \
  71. --apprenticeship full \
  72. --output-dir ./dist
  73. ```
  74. Use `--text-no-llm` for deterministic explicit-label extraction. Treat implicit teacher cognition from ordinary exposition as medium/low confidence and require review.
  75. ## Compile existing materials
  76. Build or migrate CoursePackage:
  77. ```bash
  78. python scripts/build_course_package.py \
  79. --course-name <course-name> \
  80. --source-dir <course-workspace>
  81. python scripts/migrate_course_package.py \
  82. <legacy-course-package.json>
  83. ```
  84. Compile the apprenticeship assets in dependency order:
  85. ```bash
  86. python scripts/build_teacher_model.py --source-dir <course-workspace>
  87. python scripts/build_capability_graph.py --source-dir <course-workspace>
  88. python scripts/build_practice_bank.py --source-dir <course-workspace> --practice-depth deep
  89. python scripts/build_assessment_bank.py --source-dir <course-workspace>
  90. python scripts/build_mentor_package.py --source-dir <course-workspace> --apprenticeship full
  91. python scripts/build_mentor_readiness_audit.py --source-dir <course-workspace>
  92. ```
  93. Then generate and validate:
  94. ```bash
  95. python scripts/build_course_skill.py \
  96. --course-name <course-name> \
  97. --skill-name <skill-name> \
  98. --mode mentor \
  99. --apprenticeship full \
  100. --learner-state external \
  101. --source-dir <course-workspace> \
  102. --output-dir ./dist
  103. ```
  104. The builder uses a temporary directory and installs the target only after validation.
  105. ## Merge courses
  106. ```bash
  107. python scripts/build_multi_course_package.py \
  108. --course <course-a-package-or-dir> \
  109. --course <course-b-package-or-dir> \
  110. --combined-name <combined-name> \
  111. --output-dir <combined-workspace>
  112. ```
  113. Migrate each package to an in-memory 1.0 form, namespace colliding IDs, keep source-course identity, record semantic conflicts, and route those conflicts into comparison rather than consensus.
  114. ## Choose role and apprenticeship
  115. - Default to `mentor` when the user wants capability formation.
  116. - Use `expert` for source lookup, course Q&A, explanation, and citations.
  117. - Use `consultant` for course-grounded diagnosis, option comparison, and advice.
  118. - Use `practitioner` for playbooks, checklists, templates, workflows, and artifacts.
  119. - Use `custom` for a user-defined source-bounded role.
  120. Treat role, scope, evidence strategy, apprenticeship mode, and learner-state strategy as separate dimensions. Mentor requests default to full apprenticeship; downgrade to guided or none when readiness is insufficient and report every blocker.
  121. ## Validate readiness
  122. Require the following for full apprenticeship:
  123. - valid TeacherModel with source-supported cues, decisions, demonstrations, feedback, and graduation signals;
  124. - acyclic CapabilityGraph with complete references and prerequisites;
  125. - at least one practice task and one assessment for each target capability;
  126. - behaviorally anchored rubrics and ordered H0–H4 hints;
  127. - retrieval, transfer, boundary, production, and graduation assessment coverage;
  128. - a complete Mentor protocol and graduation policy;
  129. - source audit that does not block core capabilities;
  130. - no duplicate IDs, dangling references, private learner data, or empty runtime files.
  131. Use guided mode when useful training assets exist but full teacher evidence does not. Do not hide gaps.
  132. ## Run Mentor Runtime
  133. First route the request as source lookup, direct explanation, diagnostic learning, guided practice, artifact feedback, real-world application, retrieval review, transfer test, or graduation test.
  134. - Answer explicit lookup directly; do not update mastery.
  135. - Honor explicit quick answers but label them as non-mastery evidence.
  136. - For an unseen capability, teach one progressive micro-lesson first, then present exactly two numbered formative questions together and wait. Use one-at-a-time pacing only when requested or needed for cognitive load.
  137. - For retrieval, review, assessment, transfer, and graduation, collect a prediction or attempt first.
  138. - Evaluate criterion-level rubric evidence, name one primary bottleneck, give the minimum effective hint, and request a concrete revision when the task or critical gap calls for it.
  139. - Record prediction, confidence, attempts, hints, rubric results, source evidence, inference, errors, outcome, reflection, mastery events, and next actions.
  140. - Explain why the next task was selected.
  141. - Fade only one support dimension after repeated success.
  142. Read the detailed protocol and policies before operating a generated Mentor Skill.
  143. ## Keep learner state external
  144. Resolve the host-provided store as:
  145. ```text
  146. {learner_store_root}/apprenticeships/{mentor_package_id}/
  147. ```
  148. Initialize, append, rebuild, schedule, select, validate, and build candidates with the generated runtime scripts. If the host cannot write, return a complete state patch and say it was not persisted. Never generate real `learner_progress.json` or apprenticeship state under Skill `references/`.
  149. ## Build Personal Skills and graduate
  150. Generate a candidate only after:
  151. - three successful practices;
  152. - two distinct contexts;
  153. - one H0 execution;
  154. - one failure, error, or counterexample;
  155. - clear trigger, preconditions, procedure, output, evaluator, and failure modes;
  156. - separable teacher lineage and personal adaptation.
  157. Promote only after regression tests, a new-context success, no material capability regression, copyright/privacy review, Skill validation, and explicit learner approval.
  158. Graduate only with delayed retention, unseen-case diagnosis, independent production, changed-context transfer, boundary recognition, critical comparison, personal adaptation evidence, and Personal Skill regression. After graduation, reduce Mentor behavior to source consultant, counterexample provider, advanced sparring partner, and source-update notifier.
  159. ## Verify outputs
  160. Run:
  161. ```bash
  162. python scripts/validate_teacher_to_skills_package.py --package <course_package.json>
  163. python scripts/validate_mentor_package.py --package <mentor_package.json>
  164. python scripts/validate_generated_skill.py --skill-dir <generated-skill>
  165. python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" .
  166. git diff --check
  167. ```
  168. Report source state, workflow, generated path, visual evidence mode, source readiness, mentor readiness, runtime readiness, apprenticeship downgrade, human-review needs, validation results, and remaining risks.
  169. ## Complete the user handoff
  170. Generation is not complete while the learner still does not know how to use the new Skill.
  171. After validation:
  172. 1. Give a plain-language inventory of the material that was processed and anything that was missing or unreadable.
  173. 2. State whether the result supports full coaching, guided learning, or source lookup only, and explain any downgrade without internal jargon.
  174. 3. State whether raw source bodies or private learner records entered the generated Skill. Default to neither.
  175. 4. When the user asked to enable the generated Skill, place the validated Skill in the current host's active Skill location only after checking for an unrelated name collision. Do not overwrite an unrelated Skill. If the host cannot reload it immediately, tell the user that one restart is required.
  176. 5. End with one ready-to-send first-session request that collects the learner's goal, current level, available time, and real application before selecting one baseline task.
  177. 6. For later updates, preserve external learner history and rebuild only the stages affected by new or changed source material.
  178. Do not expose compiler commands, schema names, runtime object names, or validation internals in the normal user handoff unless the user explicitly asks for developer details.
  179. Do not commit private transcripts, images, OCR, learner state, or copyrighted bodies unless the user explicitly authorizes publication.
README.md · README · 150 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="./docs/img/hero-zh.svg" alt="Teacher-to-Skills:把老师蒸馏成 Skill。提炼老师怎么看、怎么判断、怎么纠错,变成一位会示范、会纠错、最终放手的 AI 老师" width="100%">
  3. # Teacher-to-Skills
  4. **蒸馏你的老师,变成一个随时能问、会带你练的 Skill**
  5. [![License](https://img.shields.io/badge/license-Apache%202.0-2F8F83?style=flat-square)](./LICENSE)
  6. [![Works with](https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20OpenClaw-4C6FB8?style=flat-square)](./docs/install.md)
  7. [![Stars](https://img.shields.io/github/stars/JuneYaooo/teacher-to-skills?style=flat-square&color=7B5BB5)](https://github.com/JuneYaooo/teacher-to-skills/stargazers)
  8. **中文** · [English](./README.en.md) · [三步上手](#三步上手) · [能蒸馏哪些材料](#能蒸馏哪些材料) · [工作原理](#工作原理) · [安装说明](./docs/install.md) · [更新记录](./CHANGELOG.md)
  9. </div>
  10. <br>
  11. 把老师的课程、书、录音、讲义和批注交给它,它会提炼老师**怎么看问题、怎么判断、怎么纠错**,打包成一位有出处的 AI 老师:先示范,再让你动手,按老师的标准给反馈,直到你不再需要它。
  12. | 你交给它 | 它蒸馏出 | 你得到 |
  13. | --- | --- | --- |
  14. | 老师的课程视频、书与讲义、录音访谈、文章笔记、批注反馈 | 出处、观察点、判断规则、示范、常见错误与纠偏、适用边界 | 一位随时能问、会出题、按老师标准点评、最终放手的 AI 老师 |
  15. ## 为什么是“蒸馏老师”,而不是“总结课程”
  16. 一位好老师最值钱的,往往不是讲义上的结论,而是没写下来的那部分:先看哪里、凭什么下判断、学生最常错在哪、什么情况下这套方法不能用。
  17. 普通摘要只留下“老师讲了什么”。Teacher-to-Skills 想留下的是“老师会怎么做”,并且把它变成你自己也能做到的能力。
  18. <img src="./docs/img/distill-zh.svg" alt="老师的课程视频、书与讲义、录音访谈、文章笔记和批注反馈,经过转录识别、标注出处、提炼方法,蒸馏出出处、观察点、判断规则、示范、常见错误与纠偏、适用边界六类内容" width="100%">
  19. | | 课程摘要 | 蒸馏出来的老师 Skill |
  20. | --- | --- | --- |
  21. | 留下什么 | 知识点和结论 | 老师的观察点、判断规则、示范和纠错方式 |
  22. | 怎么用 | 你自己去读 | 它出题、你先做,它按老师的标准点评 |
  23. | 可信度 | 难以分辨是原话还是改写 | 重要结论都能回查原文、原话或关键画面 |
  24. | 最终结果 | 读完就结束 | 隔一段时间、换个场景你也能独立做出来 |
  25. 它**不会**声称复制老师的人格、意识或全部经验。材料里没有的东西,它会标成“证据不足”,不会编造“老师大概会这么说”。
  26. ## 蒸馏出来的老师会怎样带你
  27. <img src="./docs/img/journey-zh.svg" alt="八个阶段:定目标、看示范、跟着做、被纠偏、独立做、换场景、出师检验、持续精进。老师的支持从完整示范加提示,逐步减少到只给最终反馈" width="100%">
  28. - **先摸底,再讲课**:了解你的目标、基础和真实应用场景,从你最需要的知识点开始。
  29. - **先让你做**:每个知识点讲完,一起给出两道题,一道检查理解,一道检查应用,回答后分别点评。
  30. - **按老师的标准纠错**:每轮只抓最关键的一个问题,给刚好够用的提示,并让你自己修订。
  31. - **记得你错过什么**:保存你的尝试、错误和修订,按你的薄弱点安排复习,不重复原题。
  32. - **逐步放手**:随着你进步减少模板和提示,最后用没见过的场景、不给提示地检验你。
  33. - **知道什么时候算出师**:只有隔一段时间还会做、换场景也能用、并且知道方法边界时,才认为你真正学会。
  34. <img src="./docs/img/lesson-zh.svg" alt="一节课:选一个知识点,讲清楚(直觉、准确定义、例子、反例、三点小结),用终端 ASCII 或 SVG 画出来,一起出两道题;之后分别点评两道题,记录错误与修订,进入下一个知识点" width="100%">
  35. 目标不是让你一直依赖这位 AI 老师,而是让你学到老师的方法,最后形成自己的方法。
  36. ## 三步上手
  37. 你不需要运行脚本,也不需要理解内部文件结构,全程用自然语言和你的 AI 助手说话即可。
  38. **① 安装**
  39. 把[安装说明](./docs/install.md)发给你的 AI 助手(Claude Code、Codex、OpenClaw 等),让它代你安装,装好后按提示重启。
  40. **② 交给它老师的材料,开始蒸馏**
  41. 上传文件或告诉它材料所在的文件夹,然后直接说:
  42. > 请使用 Teacher-to-Skills 蒸馏这位老师的材料,做成一个能带我真正学会的老师 Skill。我的目标是把老师的方法用到真实工作中。重要结论要能回查出处,原始材料和个人学习记录保持私有。请先告诉我识别到了哪些材料、还缺什么;如果没有需要我决定的风险,就继续完成蒸馏、检查并启用新 Skill,最后告诉我怎样开始第一课。
  43. 它会盘点材料,完成转录、识别、出处整理、老师方法提炼、练习设计和质量检查,中途中断了也能接着做。交付时它应该清楚告诉你:
  44. - 老师 Skill 是否已经生成并启用;
  45. - 哪些视频、文档、章节和笔记已经处理;
  46. - 哪些内容证据不足、识别不清或需要你确认;
  47. - 当前能做到完整带教、引导学习,还是只适合查资料;
  48. - 原始材料和个人学习记录保存在哪里,有没有被打包进 Skill。
  49. 如果这些没有交代清楚,直接让它补做交付检查。
  50. **③ 跟着老师学**
  51. > 用刚刚生成的老师 Skill 开始带我学习。先问清楚我的目标、基础、每周可投入时间和一个真实应用场景;做一次简短摸底后,从一个知识点开始深入浅出地讲。讲完一起给我两道题,等我回答后分别点评。
  52. 之后每次回来,一句话就够:
  53. | 你想做什么 | 可以直接说 |
  54. | --- | --- |
  55. | 继续学习 | “继续上次进度,给我今天最应该做的一项练习。” |
  56. | 问老师会怎么看 | “按老师的方法,这个问题应该先看什么?给出原话出处,这次不用练习。” |
  57. | 提交真实作品 | “这是我按老师方法完成的作品,先按老师的标准评价,再指出最关键的一个问题。” |
  58. | 复习巩固 | “根据我以前的错误安排一次复习,不要重复原题。” |
  59. | 检查迁移 | “换一个我没见过的场景,检查我能不能独立用这个方法。” |
  60. | 解决现实问题 | “先让我说明自己的判断和方案,再用老师的方法帮我纠偏。” |
  61. | 追加新材料 | “这是老师的新课,更新进老师 Skill,保留我原来的学习进度。” |
  62. | 申请出师 | “不要给提示,用新场景检验我是否真的掌握,并说明还缺什么证据。” |
  63. ## 能蒸馏哪些材料
  64. | 你手上的材料 | 它会怎么处理 |
  65. | --- | --- |
  66. | 🎬 课程视频、讲座录像 | 结合讲解声音、画面、幻灯片、板书和演示进行整理 |
  67. | 🎙️ 录音、播客、访谈 | 转成可检索的文字,并按章节和主题组织 |
  68. | 📚 书籍、PDF、扫描讲义 | 识别正文、结构、表格和重要页面 |
  69. | 📝 文章、笔记、批注、文字稿 | 保留原文位置,提炼方法、案例和练习 |
  70. | ♻️ 已有的转录或课程整理 | 跳过重复处理,在已有成果上继续 |
  71. | 👥 多位老师的材料 | 分别保留每位老师的观点、适用条件和分歧,不强行拼成一个答案 |
  72. 材料不完整也可以开始。它会标出缺失的证据和需要人工确认的地方。材料只够解释概念时,它会如实退回到资料查询或引导学习,不会假装已经具备完整的带教能力。
  73. ## 工作原理
  74. <img src="./docs/img/layers-zh.svg" alt="四个层次:证据层、老师层、练习层组成老师 Skill,生成后不改动、随时回查出处;个人层是你的学习记录,私有并保存在 Skill 之外" width="100%">
  75. 老师的材料和你的学习记录分开保存:老师那部分生成后不再改动,你的进度保存在 Skill 之外的私有目录,重新蒸馏或更新材料都不会丢失学习记录。
  76. <details>
  77. <summary>四个层次的文字说明</summary>
  78. | 层次 | 做什么 |
  79. | --- | --- |
  80. | 证据层 | 保存原文、原话、讲义和关键画面,每条结论都能回查 |
  81. | 老师层 | 提炼老师的观察点、判断规则、示范、纠错方式和边界 |
  82. | 练习层 | 按学习顺序设计练习、评分标准、复习和迁移检验 |
  83. | 个人层 | 保存你的尝试和真实结果,经你同意后沉淀成你自己的方法 |
  84. </details>
  85. ## 边界、隐私与版权
  86. - 只蒸馏有出处的方法和判断,不复制老师的人格、意识或全部经验。
  87. - 老师原意、基于材料的整理、AI 的推断和你自己的实践证据会明确区分。
  88. - 原始课程、转录、截图、扫描内容和个人学习记录默认不会打包进生成的 Skill。
  89. - 只有你明确同意后,经过多次实践验证的做法才会被建议为你的个人长期方法。
  90. - 医学、法律、金融、投资等高风险领域仅用于有来源的学习,不能替代专业资质或现实责任。
  91. - 请只蒸馏你有权使用的材料,并遵守课程版权和分发限制。
  92. ## 致谢
  93. - [Datawhale](https://github.com/datawhalechina) — AI 教育、开源课程与学习者社区实践。
  94. - [rfeng1016](https://github.com/rfeng1016) — 对渐进知识组织方向的建议。
  95. - [LINUX DO](https://linux.do/) — 中文开发者社区的讨论与反馈。
  96. ## License
  97. 本项目采用 [Apache License 2.0](./LICENSE)。
  98. <div align="center">
  99. <sub>插图由 <code>docs/img/src/build_images.py</code> 生成,修改文案后重新运行即可更新。</sub>
  100. </div>
scripts/llm_client.py · Bundled script · 220 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. # -*- coding: utf-8 -*-
  3. """Small OpenAI-compatible clients used by this repo."""
  4. from __future__ import annotations
  5. import base64
  6. import json
  7. import os
  8. from pathlib import Path
  9. from typing import Any
  10. from dotenv import load_dotenv
  11. from openai import OpenAI
  12. import requests
  13. load_dotenv()
  14. # Older installs (named lineage-skill) used LINEAGE_* variables; keep them working.
  15. for _key, _value in list(os.environ.items()):
    • Dismissed after review: Copies every environment variable, where API keys and tokens live, in a file that sends data
    • Line 20 on GitHub
  16. if _key.startswith("LINEAGE_"):
  17. os.environ.setdefault("TEACHER_TO_SKILLS_" + _key[len("LINEAGE_"):], _value)
  18. def _model_list(raw: str | None, default: str) -> list[str]:
  19. models = [m.strip() for m in (raw or "").split(",") if m.strip()]
  20. return models or [default]
  21. def _mime_type(path: str) -> str:
  22. ext = Path(path).suffix.lower()
  23. return {
  24. ".mp4": "video/mp4",
  25. ".mov": "video/quicktime",
  26. ".avi": "video/x-msvideo",
  27. ".webm": "video/webm",
  28. ".mkv": "video/x-matroska",
  29. }.get(ext, "video/mp4")
  30. def _timeout(env_name: str, default: str) -> float:
  31. try:
  32. return float(os.getenv(env_name, default))
  33. except ValueError:
  34. return float(default)
  35. def _parse_video_response(text: str, video_path: str) -> dict[str, Any]:
  36. """Return JSON responses when present; otherwise keep markdown content."""
  37. import re
  38. match = re.search(r"\{[\s\S]*\}", text)
  39. if match:
  40. try:
  41. parsed = json.loads(match.group(0))
  42. parsed["success"] = True
  43. parsed["video_path"] = video_path
  44. return parsed
  45. except json.JSONDecodeError:
  46. pass
  47. return {"success": True, "content": text, "video_path": video_path}
  48. def call_text_llm(messages: list[dict[str, Any]]) -> str:
  49. """Call the Stage 3 distillation model."""
  50. api_key = os.getenv("TEACHER_TO_SKILLS_TEXT_API_KEY")
  51. base_url = os.getenv("TEACHER_TO_SKILLS_TEXT_BASE_URL") or None
  52. models = _model_list(os.getenv("TEACHER_TO_SKILLS_TEXT_MODEL"), "gpt-4o")
  53. max_tokens = int(os.getenv("TEACHER_TO_SKILLS_TEXT_MAX_TOKENS", "4096"))
  54. timeout = _timeout("TEACHER_TO_SKILLS_TEXT_TIMEOUT", "300")
  55. if not api_key:
  56. raise ValueError("未设置 TEACHER_TO_SKILLS_TEXT_API_KEY")
  57. if base_url:
  58. url = base_url.rstrip("/") + "/chat/completions"
  59. else:
  60. url = "https://api.openai.com/v1/chat/completions"
  61. last_error: Exception | None = None
  62. for model in models:
  63. try:
  64. response = requests.post(
  65. url,
  66. headers={
  67. "Authorization": f"Bearer {api_key}",
  68. "Content-Type": "application/json",
  69. },
  70. json={
  71. "model": model,
  72. "messages": messages,
  73. "temperature": 0.8,
  74. "max_tokens": max_tokens,
  75. },
  76. timeout=(20, timeout),
  77. )
  78. response.raise_for_status()
  79. data = response.json()
  80. return data["choices"][0]["message"].get("content") or ""
  81. except Exception as exc:
  82. last_error = exc
  83. print(f" 模型 {model} 调用失败: {type(exc).__name__}: {exc}")
  84. raise last_error or RuntimeError("所有文本模型均失败")
  85. def analyze_video_with_vision_model(video_path: str, prompt: str) -> dict[str, Any]:
  86. """Analyze a video with the configured OpenAI-compatible vision endpoint."""
  87. api_key = os.getenv("TEACHER_TO_SKILLS_VISION_API_KEY")
  88. base_url = os.getenv("TEACHER_TO_SKILLS_VISION_BASE_URL") or None
  89. models = _model_list(os.getenv("TEACHER_TO_SKILLS_VISION_MODEL"), "gpt-4o")
  90. timeout = _timeout("TEACHER_TO_SKILLS_VISION_TIMEOUT", "600")
  91. if not api_key:
  92. raise ValueError("未设置 TEACHER_TO_SKILLS_VISION_API_KEY")
  93. if not Path(video_path).exists():
  94. raise FileNotFoundError(video_path)
  95. video_bytes = Path(video_path).read_bytes()
  96. video_base64 = base64.b64encode(video_bytes).decode("utf-8")
  97. mime_type = _mime_type(video_path)
  98. client = OpenAI(api_key=api_key, base_url=base_url, timeout=timeout)
  99. last_error: Exception | None = None
  100. for model in models:
  101. try:
  102. print(f" 🚀 视觉模型: {model}, base64={len(video_base64) / 1024 / 1024:.1f}MB")
  103. response = client.chat.completions.create(
  104. model=model,
  105. messages=[
  106. {
  107. "role": "user",
  108. "content": [
  109. {
  110. "type": "image_url",
  111. "image_url": {"url": f"data:{mime_type};base64,{video_base64}"},
  112. },
  113. {"type": "text", "text": prompt},
  114. ],
  115. }
  116. ],
  117. max_tokens=4096,
  118. )
  119. text = (response.choices[0].message.content or "").strip()
  120. if not text:
  121. raise ValueError("模型返回空内容")
  122. return _parse_video_response(text, video_path)
  123. except Exception as exc:
  124. last_error = exc
  125. print(f" ⚠️ 视觉模型 {model} 失败: {exc}")
  126. return {
  127. "success": False,
  128. "error": str(last_error or "所有视觉模型均失败"),
  129. "content": "",
  130. "video_path": video_path,
  131. }
  132. def analyze_images_with_vision_model(image_paths: list[str], prompt: str) -> dict[str, Any]:
  133. """Analyze one or more images with the configured OpenAI-compatible vision endpoint."""
  134. api_key = os.getenv("TEACHER_TO_SKILLS_VISION_API_KEY")
  135. base_url = os.getenv("TEACHER_TO_SKILLS_VISION_BASE_URL") or None
  136. models = _model_list(os.getenv("TEACHER_TO_SKILLS_VISION_MODEL"), "gpt-4o")
  137. timeout = _timeout("TEACHER_TO_SKILLS_VISION_TIMEOUT", "600")
  138. if not api_key:
  139. raise ValueError("未设置 TEACHER_TO_SKILLS_VISION_API_KEY")
  140. if not image_paths:
  141. raise ValueError("image_paths 不能为空")
  142. content: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
  143. for image_path in image_paths:
  144. path = Path(image_path)
  145. if not path.exists():
  146. raise FileNotFoundError(image_path)
  147. suffix = path.suffix.lower().lstrip(".") or "jpeg"
  148. mime = "image/png" if suffix == "png" else "image/jpeg"
  149. encoded = base64.b64encode(path.read_bytes()).decode("utf-8")
  150. content.append(
  151. {
  152. "type": "image_url",
  153. "image_url": {"url": f"data:{mime};base64,{encoded}"},
  154. }
  155. )
  156. url = (base_url.rstrip("/") if base_url else "https://api.openai.com/v1") + "/chat/completions"
  157. last_error: Exception | None = None
  158. for model in models:
  159. try:
  160. print(f" 🚀 图像模型: {model}, images={len(image_paths)}", flush=True)
  161. response = requests.post(
  162. url,
  163. headers={
  164. "Authorization": f"Bearer {api_key}",
  165. "Content-Type": "application/json",
  166. },
  167. json={
  168. "model": model,
  169. "messages": [{"role": "user", "content": content}],
  170. "max_tokens": 4096,
  171. },
  172. timeout=(20, timeout),
  173. )
  174. response.raise_for_status()
  175. data = response.json()
  176. text = (data["choices"][0]["message"].get("content") or "").strip()
  177. if not text:
  178. raise ValueError("模型返回空内容")
  179. return {"success": True, "content": text, "image_paths": image_paths}
  180. except Exception as exc:
  181. last_error = exc
  182. print(f" ⚠️ 图像模型 {model} 失败: {exc}", flush=True)
  183. return {
  184. "success": False,
  185. "error": str(last_error or "所有图像模型均失败"),
  186. "content": "",
  187. "image_paths": image_paths,
  188. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.