# 在 Google Antigravity 中使用 StudyMate

**支持范围：只有 `v1.0.0`。** 1.1.0 起的版本不再保证在这一侧可用——构建时用 `v1.0.0` 那棵树（`git checkout v1.0.0`），不要用 `main`。

StudyMate 的 Google Antigravity 版本是面向 Antigravity 架构的原生多智能体插件包。它将 StudyMate 的学习工作流、HTML 课件引擎与 Antigravity 原生能力（子智能体机制 `invoke_subagent`、结构化交互模态 `ask_question`、安全沙箱 `run_command` 以及伴学 Artifacts）深度融合。

---

## 1. 架构总览

StudyMate 在 Antigravity 中采用 **主智能体（学习总控）+ 5 个专属后台子智能体** 的多智能体协同设计：

```mermaid
flowchart TD
    User["学生 (用户)"] <-->|"独占交互 / ask_question"| LS["学习总控 (learning-system)"]
    
    subgraph Subagents ["Antigravity 原生子代理 (agents/*.md)"]
        RS["资料收集 (resource-scout)"]
        IS["采图角色 (image-scout)"]
        CD["课程设计 (curriculum-designer)"]
        LC["课件讲解 (learning-coach)"]
        PE["出题与评估 (practice-evaluator)"]
    end
    
    LS -->|"1. 收集权威资料"| RS
    RS -->|"RESOURCES.md"| LS
    LS -->|"2. 并发派发 (invoke_subagent)"| IS
    LS -->|"2. 并发派发 (invoke_subagent)"| CD
    IS -->|"图片库与索引 pool.md"| LS
    CD -->|"课程大纲 curriculum.yaml"| LS
    LS -->|"3. 撰写课件正文与锚点"| LC
    LC -->|"课件 Markdown"| LS
    LS -->|"4. 配套四层题库与 Lab"| PE
    PE -->|"quiz.json & lab/"| LS
    LS -->|"5. 交接门禁 + 逐项自查"| Check["按 schemas/*.schema.json 与格式规范自查"]
    Check -->|"导出：npx -y @yunmiao/studymate export"| User["<工作区>/export/index.html"]
```

- **主智能体（`learning-system`）**：全局学习规划、用户对话通道、调度子代理、档案管理、staged 交接门禁、逐项自查与导出。
- **5 个专属子智能体（`agents/`）**：
  - `resource-scout`：检索权威教材、官方文档与行业标准，产出资源清单与 `## Gaps`。
  - `image-scout`：抓取高质量概念图与流程图，校验尺寸格式，维护 7 列表头索引。
  - `curriculum-designer`：构建知识依赖拓扑有向无环图（DAG），制定标准大纲与实验课里程碑。
  - `learning-coach`：撰写教材级深度课件正文、配图与题目锚点。
  - `practice-evaluator`：全系统题目与评估的唯一 Owner，设计四层练习、整套 Lab 任务，基于真实运行证据核验与批改。
- **12 个完整 Skill 规范（`skills/`）**：全部采用标准规范 Frontmatter，在 Antigravity 中 100% 完整可见与常驻。

---

## 2. 安装、部署与更新

### 方式一：本地一键构建并安装（推荐）

在 StudyMate 项目根目录下运行：

```bash
node bin/studymate.mjs build-antigravity --install
```

该命令会自动：
1. 编译适配 Antigravity 的 5 个 Subagent、12 个 Skill 规范与交互协议。
2. 打包 schema、工作区数据骨架、文档与 logo——**没有引擎脚本**（Python 引擎随 #83 退役，校验按自查清单做）。
3. 原子替换安装到 Antigravity 插件目录：`~/.gemini/config/plugins/studymate`。

目标目录里已有非 StudyMate 文件时会拒绝安装（不会清空已有内容）；空目录或上一次构建的产物可以直接覆盖。要装到别处用 `--output <目录>`。

### 方式二：构建分发 ZIP 包手动导入

在项目根目录下运行：

```bash
npm run build:antigravity
```

构建产物位于：
- `dist/antigravity/studymate/`（完整插件解压目录）
- `dist/antigravity/studymate-antigravity.zip`（分发安装包）

通过 Antigravity IDE 的插件管理器选择导入该 ZIP 即可。

### 依赖环境准备

**什么都不用装**：这个插件只有技能、schema、工作区数据骨架与文档，没有引擎脚本，也没有原生工具
（Python 引擎随 #83 退役）。校验按技能里的自查清单逐项核对；要一份能离线看的，在 `run_command`
里跑 `npx -y @yunmiao/studymate@latest export`——那条命令要 Node 与一份 React
（`npm i -g react react-dom`，或设 `STUDYMATE_REACT_DIR`）。

---

## 3. 使用说明与学习流程

### 1. 意图自动激活
得益于内置的 `rules/AGENTS.md` 规则，你在 Antigravity 对话中只要表达学习意愿：
- *“我想学计算机网络”*
- *“我想学 C++ 打竞赛”*
- *“我不知道学什么，帮我选方向”*

系统会自动激活 `learning-system` 进入学习工作流；日常写代码、修 Bug、代码审查或普通开发请求**绝不会误打扰**。

### 2. 交互式开课盘问（`ask_question`）
总控会调用 Antigravity 原生的交互式卡片逐步确认核心信息：
1. **现实目标与期望深度**：了解 / 能独立做项目 (Recommended) / 精通。
2. **前置知识自评**：核心数学/编程前置能力核验。
3. **主线项目选择**：给出 3 个以上有明确差异的实践项目供学生挑选。
4. **实操实验载体**：按项目性质选定 Jupyter Notebook、源码与测试或命令行等。

整个过程一次一个决策，收到回答直接向下推进，不反复发送“是否开始”等冗余确认。

### 3. 多智能体协同推进
- **并发调度**：资料收集就绪后，总控通过 `invoke_subagent` 数组同时并发派发 `image-scout`（采图建池）与 `curriculum-designer`（设计大纲 DAG）。
- **串行制作**：讲解角色完成课件正文后，出题评估角色进场配套练习题库与 Lab 任务包。
- **事件驱动**：子代理在独立后台上下文中执行，宿主在完成后自动通知总控，全程零轮询、零卡顿。

### 4. 课件呈现与伴读 Artifact
- **HTML 课件交付**：课件渲染完成后，总控在回复中提供可点击的本地绝对超链接：`[打开第 N 课：<标题>](file://<绝对路径>)`。提示在现代浏览器中直接打开，畅享 Sayo UI 侧边栏大纲、平滑滚动、代码高亮与离线 KaTeX 排版。
- **伴学 Artifact**：总控会在 `<appDataDir>/brain/<conversation-id>/` 写入 Mermaid 知识依赖路线图或本课导读 Artifact，提供结构化伴学视图。

### 5. 局部答疑与打扰控制（`local-qa`）
在阅读课件或做题过程中遇到疑惑时，直接将看不懂的段落或代码贴回对话并提问（如 *“这里没懂”*）。总控会在 200 字内精准解答，在后台静默记录误解（`misconceptions`），并引导你返回课件原位置继续学习，不打断主线流程。

### 6. 离线导出（课完默认导一份）

这一侧没有 DSH 的阅读端，**学生的阅读体验就是导出**（[ADR-0003](../../docs/adr/0003-阅读端只嵌DSH.md)）。
所以流程约定：**一课做完（内容与题库都校验通过）就导一份**，命令没有参数也能跑：

```sh
npx -y @yunmiao/studymate export
```

工作区按 `--workspace` → `$LEARN_WORKSPACE` → `~/.dsh/studymate-config.yaml` → 当前目录 的顺序定位，
所以通常什么都不用带。产物落在 `<学习工作区>/export/`：

- `index.html`：双击就能离线看（也可以在浏览器里用 `file://` 打开）。样式、公式、图片、题目都在这个目录里，
  **不联网、不需要 DSH**——页面跑的就是 DSH 阅读端那一份渲染代码；
- 想只导一门科目：`--subject <slug>`；想换落点：`--out <目录>`；技能里要产物清单：`--json`。

导出需要一份 React（离线页面要它才能渲染）：`npm i -g react react-dom`，或把
`STUDYMATE_REACT_DIR` 指到装着 react 的目录。缺了会明确告诉你装什么，不会产出一份打不开的页面。

---

## 4. 工作区与免授权暂存机制

- **默认学习工作区**：位于独立的 `~/StudyMate`，所有生成的科目、大纲路线图、课件、做题记录与跨科目共享记忆均保存在此处。可通过环境变量 `STUDYMATE_WORKSPACE` 自定义。
- **会话级免授权暂存**：如果对话是在某个具体代码仓中开启，新科目一律先在当前工作目录的 `.studymate-stage/<slug>` 暂存建课。全流程在会话当前目录内完成，全程零提权；制作完成后，由学生选定落点（默认工作区、桌面、文档目录或就地保留），单次安全搬移。
- **角色级隔离暂存**：子代理产物统一写入 `<subject_path>/.stage/<角色名>-<节点id>/deliver/<相对路径>`，严格隔离中间产物，杜绝并发冲突。

---

## 5. 常见问题排查

- **安装后技能未加载**：确认插件已正确部署在 `~/.gemini/config/plugins/studymate`，重启 Antigravity IDE 即可重新扫描并注册所有 12 个 Skill 与 5 个 Agent。
- **看不到课件页**：阅读端只嵌在 DSH 里；Antigravity 侧的学生阅读体验靠**导出**——课完跑一次 `npx -y @yunmiao/studymate@latest export`，产物在 `<工作区>/export/`，`file://` 打开即可（样式、公式、图片、题目都在里面）。
- **子代理运行报错**：走 `.stage/.../deliver/` 的交付先按 `deliver/` 清单自查（manifest 与文件一一对应、角色与节点对得上、路径不越界），再按对应领域的自查清单核对（大纲按 schema、图片库按七列索引、课件按内容格式与锚点）；任一阻断项未过都不合盘并打回重试。

---

## 6. 开发者维护与测试

修改插件或适配逻辑后，先跑 `npm run test:antigravity`（Antigravity 专用回归：ZIP 导出、Agent 准则、12 技能 frontmatter 校验），再跑门禁。

门禁是哪条、静态层与全量回归什么关系，见 [CONTRIBUTING.md §本地验证](../../CONTRIBUTING.md#本地验证)与[测试说明](../../scripts/tests/README.md)。