@yottameta/yotta-lesson 0.0.0 → 0.1.0

package/install.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# yotta-lesson 多智能体安装脚本（YottaSkills 模板）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-lesson"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
+main "$@"

package/package.json

@@ -1,19 +1,45 @@
 {
   "name": "@yottameta/yotta-lesson",
-  "version": "0.0.0",
-  "description": "Placeholder package for the YottaMeta yotta-lesson skill.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.1.0",
+  "description": "YuanAn (yotta-lesson) — a local, deterministic lesson-plan skeleton and coverage checker for AI agents: reads a curriculum map (lesson id, knowledge points, key points, difficulties, misconceptions, standard reference) plus an optional structure config, builds a lesson skeleton whose stage minutes always sum to periods x minutes-per-period and whose objectives each carry a curriculum-standard source, and checks an existing lesson text for missing knowledge points, missing required stages, missing citations, missing time annotations and total-time mismatches. Markdown and JSON output, configurable stages, and a CI gate are included. Triggers: drafting a lesson or study-plan skeleton, verifying a lesson against a curriculum map, checking that knowledge points and stages are covered, or wiring lesson-structure checks into automation. Boundaries: structural skeleton and gap list only — no exercise content, no student comments, no replacement for the teacher's instructional design; no network access, no model calls, no upload of lesson plans or school maps; no textbook, curriculum or exam text is bundled, and citations must be verified against official sources. Fully local, zero-dependency (Python 3.8+ standard library).",
   "license": "MIT",
-  "type": "commonjs",
+  "keywords": [
+    "agent-skills",
+    "yotta-lesson",
+    "yottaskills",
+    "lesson-plan",
+    "education"
+  ],
+  "files": [
+    "SKILL.md",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "install.sh",
+    "references",
+    "scripts",
+    "assets",
+    "bin",
+    "!scripts/test_*.py",
+    "!scripts/fixtures",
+    "!scripts/fixtures/**",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!**/*.pyo"
+  ],
   "repository": {
+    "type": "git",
     "url": "git+https://github.com/YottaMeta/yotta-lesson.git"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "yotta-lesson": "bin/install.js"
+  },
+  "scripts": {
+    "test": "python scripts/test_yotta_lesson.py"
   }
 }

package/references/copyright.md

@@ -0,0 +1,34 @@
+# 版权与使用边界（元案 yotta-lesson）
+
+## 一、不含教材与题目原文
+
+- 映射包只记录结构性元数据：课题 id / 名称、单元、知识点名称、重难点、易错点、课标条目标识；
+- 本技能不内置、不下载、不缓存教材课文、课标正文、教辅题目与考试真题；
+- 教案骨架中的环节要点为通用教学动作描述，不含具体题目内容；例题与练习的具体内容由教师自行编写或引用合法来源。
+
+## 二、课标与来源引用
+
+- `standard` 字段要求填写可核对的课标来源标识（如「义务教育数学课程标准（2022 年版）· 方程与不等式」）；
+- 引用标注用于**可追溯**，不代表本技能对课标内容作出解释；解读与适用以官方文本和教研判断为准；
+- 若学校对来源写法有规范（如校内编号），可在 `standard` 中按规范书写，`check` 会按该文本核对。
+
+## 三、教师责任与免责
+
+- 本技能输出的是教案骨架与结构性缺口清单，属于**备课辅助**；
+- 教学目标设定、环节设计、时间取舍、作业布置的最终决定由教师负责；
+- 发布或提交教案前，请教师自行核对知识点表述、来源标注与本校规范；
+- 固定免责声明：本文件由元案（yotta-lesson）基于本地映射包与结构配置的确定性计算生成，
+  仅作备课辅助；教学设计与时间安排的最终决定由教师负责，课标引用请以官方文本为准。
+
+## 四、数据边界
+
+- 本地运行：核心路径零网络、零模型调用；教案草稿、映射包与结构配置只在本机流转；
+- 不产生遥测、不上报、不建远程副本；
+- 若将教研组映射包用于共享，请确认其中不含不宜外传的校本信息（如班级、教师姓名）。
+
+## 五、与其他技能的分工
+
+- 题目内容生成 / 组卷：属元题（规划中）；
+- 学情数据分析：属元镜 yotta-mirror；
+- 含个人信息的材料合规审查：属元规 yotta-compliance；
+- 对外呈现与去 AI 味：属元呈 / 元真。

package/references/map-format.md

@@ -0,0 +1,88 @@
+# 映射包与结构配置（元案 yotta-lesson）
+
+## 一、课标映射包（JSON，必填）
+
+```json
+{
+  "schema_version": "1.0",
+  "subject": "数学",
+  "grade": "七年级上",
+  "lessons": [
+    {
+      "id": "L1",
+      "title": "认识一元一次方程",
+      "unit": "一元一次方程",
+      "periods": 1,
+      "knowledge": ["一元一次方程的定义", "方程的解"],
+      "key_points": ["一元一次方程的定义"],
+      "difficulties": ["由实际问题抽象出方程"],
+      "misconceptions": ["把含未知数的式子都当方程"],
+      "standard": "义务教育数学课程标准（2022 年版）· 方程与不等式"
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | string | 是 | 课题 id，不可重复；`plan` / `check` 用它定位课题 |
+| `title` | string | 是 | 课题名称（进入教案标题） |
+| `unit` | string | 否 | 所属单元 |
+| `periods` | int | 否 | 课时数，默认 1；可用 `--periods` 覆盖 |
+| `knowledge` | string[] | 是 | 知识点（进入学习目标，`check` 逐条核对是否出现在教案中） |
+| `key_points` | string[] | 否 | 教学重点 |
+| `difficulties` | string[] | 否 | 教学难点 |
+| `misconceptions` | string[] | 否 | 易错点（缺省会在备课时提示补充） |
+| `standard` | string | 是 | 课标来源标识（可追溯性必需；请填写可核对的条目标识） |
+
+顶层 `subject` / `grade` 会写入骨架信息区，便于同一映射包跨班复用。
+
+## 二、结构配置（JSON，可选）
+
+```json
+{
+  "schema_version": "1.0",
+  "minutes_per_period": 45,
+  "stages": [
+    {"id": "lead_in", "name": "导入", "ratio": 0.10},
+    {"id": "explore", "name": "新知探究", "ratio": 0.30},
+    {"id": "explain", "name": "例题精讲", "ratio": 0.25},
+    {"id": "practice", "name": "练习巩固", "ratio": 0.25},
+    {"id": "summary", "name": "小结与作业", "ratio": 0.10}
+  ],
+  "required_stages": ["lead_in", "explore", "practice", "summary"],
+  "check_keywords": {
+    "practice": ["练习", "巩固", "变式"],
+    "summary": ["小结", "作业", "总结"]
+  }
+}
+```
+
+| 字段 | 说明 |
+|---|---|
+| `minutes_per_period` | 每课时分钟数（不小于 5，默认 45） |
+| `stages` | 环节定义：`id` / `name` / `ratio`（比例为相对权重，不必和为 1） |
+| `required_stages` | 必填环节（`check` 会逐项核对关键词是否出现在教案中） |
+| `check_keywords` | 环节 → 关键词数组；命中任一即认为该环节存在 |
+
+时间分配采用**最大余数法**：按比例取整后，把剩余分钟按小数部分从大到小补齐，保证
+各环节分钟合计精确等于 `课时 × 每课时分钟`。
+
+## 三、常见报错对照
+
+| 提示 | 原因 | 处理 |
+|---|---|---|
+| `schema_version 必须是 1.0` | 版本不匹配 | 按模板修正 |
+| `课题 id 重复：L1` | 同一 id 出现两次 | 合并或改名 |
+| `缺少 standard` | 未填课标来源 | 补条目标识（可追溯性必需） |
+| `knowledge 必须是字符串数组` | 类型写错 | 改成数组 |
+| `periods 必须是不小于 1 的整数` | 课时数非法 | 填正整数 |
+| `环节 id 重复` | 结构配置里重复 | 合并环节 |
+| `required_stages 引用了未声明的环节` | 必填环节不在 `stages` 中 | 先声明再引用 |
+| `映射包中不存在课题：L9` | `--lesson` 写错 | 用 `map list` 查看可用 id |
+
+## 四、使用建议
+
+- 一个映射包对应一个学科一个学期；单元与课题按教材顺序排列；
+- 课标来源建议写「课标名称（版本）· 条目或主题」这种可核对的形式；
+- 结构配置按学校 / 教研组统一维护，教案口径才可比。

package/references/plan-format.md

@@ -0,0 +1,61 @@
+# 骨架与检查报告契约（元案 yotta-lesson）
+
+## 一、教案骨架（Markdown）
+
+1. 课题信息（学科 / 年级 / 课题 / 课时 × 每课时分钟 = 合计分钟）
+2. 学习目标（逐条带课标来源）
+3. 教学重难点与易错点
+4. 教学环节与时间分配（表格：环节 / 时间 / 要点）
+5. 板书与评价清单（可勾选）
+6. 备课提示（映射包层面需要教师补充的点）
+7. 来源与免责
+
+## 二、骨架 JSON 顶层字段（`schema_version = 1.0`）
+
+| 字段 | 说明 |
+|---|---|
+| `schema_version` | 契约版本 |
+| `tool` | 固定为 `yotta-lesson` |
+| `tool_version` | 引擎版本 |
+| `generated_at` | 生成时间（UTC，唯一随运行变化的字段） |
+| `lesson` | 课题信息：id / title / unit / subject / grade / periods / minutes_per_period / total_minutes |
+| `objectives` | 学习目标数组（`knowledge` + `source`） |
+| `key_points` | 教学重点 |
+| `difficulties` | 教学难点 |
+| `misconceptions` | 易错点 |
+| `stages` | 环节数组（`id` / `name` / `minutes` / `focus`） |
+| `checklist` | 评价清单（板书、反馈、作业等） |
+| `findings` | 备课提示（映射包层面的缺口，如无易错点、课时被覆盖） |
+| `sources` | 课标来源 |
+| `disclaimer` | 固定免责声明 |
+
+## 三、缺口检查报告
+
+`check` 子命令对已有教案文本做确定性核对，输出 `findings` 数组（按 `kind` + `detail` 排序）：
+
+| kind | 含义 | 处理建议 |
+|---|---|---|
+| `knowledge_missing` | 教案未出现映射包中的知识点原文 | 补知识点或改用映射包认可的名称 |
+| `stage_missing` | 必填环节的关键词都未出现 | 补该环节，或调整 `check_keywords` |
+| `source_missing` | 未标注课标来源 | 在教案中写明 `standard`（至少写明条目前半段） |
+| `time_missing` | 未出现任何「N 分钟」标注 | 给各环节补时间 |
+| `minutes_mismatch` | 标注的「合计 N 分钟」与 课时 × 每课时分钟 不一致 | 核对课时数或时间分配 |
+
+检查报告 JSON 顶层字段：`schema_version`、`tool`、`tool_version`、`lesson`、`checked`、
+`findings`、`summary`、`disclaimer`。
+
+## 四、退出码与闸门
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 正常（含未触发闸门） |
+| `1` | `--gate findings=<n>`：缺口数量 ≥ n |
+| `2` | 输入错误（文件缺失、教案文本缺失、非法输出路径） |
+| `3` | 映射或配置错误（schema、必填字段、课时数、环节定义） |
+| `4` | 运行时错误（文件系统等） |
+
+## 五、复算与归档建议
+
+- 归档四件：映射包、结构配置、教案骨架 JSON、教案正文；四件齐全才能复算同一结论；
+- 教研组比对教案时，固定同一映射包与结构配置，差异才归因于教案本身；
+- 骨架的 `findings` 与 `check` 的 `findings` 含义不同：前者是映射包层面的备课提示，后者是教案文本层面的缺口。