git:20260912.b9355eb to git:20260919.f8b0e85

8 added, 8 removed. Audit A to A.

---

name: verymath-install

- description: 从 GitHub 仓库或已有本地项目安装、配置并启动 VeryMath 智慧教材工作台，检查环境、接入内置课程 Skill 和 Coding Agent；用于用户提供 course-copilot 链接并要求安装 Skill、部署工作台或启动本地课程助手。

+ description: 从 GitHub 仓库或已有本地项目安装、配置并启动 VeryMath 智慧教材工作台，检查环境、配置内置课程 Skill 与模型服务；用于用户提供 VeryMath-textbook-copilot 链接并要求安装 Skill、部署工作台或启动本地课程助手。

---

# 安装 VeryMath 智慧教材

交付可访问的本机工作台，完成依赖安装、内置课程 Skill 配置和服务启动。默认只需按本说明完成部署即可；仅当用户明确要求把本 Skill 注册到个人 Skill 目录供以后复用时，才复制本 Skill，不要把注册当成部署的前提。

## 获取项目

- - 使用用户提供的仓库、分支、安装目录和数据目录。未指定仓库时使用 https://github.com/ConanXu-math/course-copilot；未指定目录时优先复用当前工作区中对应仓库，否则使用用户主目录下的 course-copilot。

+ - 使用用户提供的仓库、分支、安装目录和数据目录。未指定仓库时使用 https://github.com/VeryMath/VeryMath-textbook-copilot；未指定目录时优先复用当前工作区中对应仓库，否则使用用户主目录下的 VeryMath-textbook-copilot。

- 本 Skill 可能已被复制到个人 Skill 目录，不把它所在目录当成项目。检查目标仓库的 README、package.json 和 server/index.mjs，后续命令在实际项目根目录执行。

- 新目录用 git clone 下载；已有同一仓库先检查工作区，更新时仅快进，保留未提交修改。目标目录属于其他项目时另选空目录。私有仓库访问失败时说明需要的仓库访问权限，不反复重试。

- 注册本 Skill 时复制整个 verymath-install 目录及 references，使用当前 Agent 实际支持的位置；已有同名 Skill 先检查，保留用户修改。六个课程 Skill 由工作台加载，无需全部安装到 Agent 全局目录。

## 检查和安装

读取 [环境与启动说明](references/local-setup.md)，按实际平台执行。

1. 检查 Git、Node.js 和 npm，Node 版本以项目 package.json 的 engines 为准。缺少必需程序时使用本机已有的版本管理器或官方安装渠道补齐，避免改坏其他项目的环境；系统权限或交互登录无法代办时说明具体下一步。

2. 安装项目依赖并构建正式页面。保留可选依赖和构建依赖，PDF 图像读取需要画布支持。安装或构建失败就修复实际错误，不用旧 dist 冒充本次构建成功。

3. 检查端口和已有服务。默认本机地址 127.0.0.1:4173；端口被其他程序使用时另选空闲端口，不结束无关进程。已有同一工作台运行时先确认项目和数据目录并复用，运行中的学习任务不因部署被打断。

4. 启动正式服务，让它初始化个人课程目录；默认 ~/.course-copilot，自定义目录通过 COURSE_COPILOT_HOME 传给服务。使用当前 Agent 支持的持续运行终端，或按平台提供后台进程与日志；确认安装对话结束后服务仍有可用的运行方式，给出停止和再次启动方法。不默认配置开机启动或公网访问。

- ## 配置课程 Skill 与 Agent

+ ## 配置课程 Skill 与模型服务

- 通过本机 API 读取状态并配置，具体字段见环境说明；不要覆盖整份 settings.json。仓库内 server/skills 下的注册表是课程 Skill 的来源，路径按实际安装位置计算。

- 新安装自动使用注册表默认路径，逐项检查教材解析、内容讲解、知识点出题、思维导图、知识图谱、生成课件。修复指向不存在文件的旧路径；保留有效的用户自定义 Skill 和明确停用的配置。讲解视频没有内置实现，保持待接入，不创建空壳充数。

- - Agent 优先级：用户指定 → 已保存的选择 → 当前执行安装且工作台支持的 Agent → 唯一已安装的兼容 Agent。仍无法确定时只询问 Agent 选择，同时完成其他安装工作。新连接默认 ACP，保留已有可用连接方式与模型设置。

- - Codex 和 Claude 的 ACP 组件随项目依赖提供；其他 Agent 仅安装用户需要的那一种，入口以仓库 agent-providers.mjs 为准。连接后再读取模型列表，沿用 Agent 默认或已有模型，不硬编码模型名称。

- - 尝试连接已有账号。需要登录时通过实际返回的登录方式引导用户本人完成；不索取密码或把凭据写进仓库。缺账号不影响先启动页面，明确区分“工作台已启动”和“Agent 待登录”。

+ - 模型服务优先级：用户指定 → 已保存的设置 → 用户账号实际可用的服务商。无法确定时只询问服务商选择，同时完成其他安装工作。保留已有可用设置。

+ - API Key 由用户本人在工作区设置中填写，安装过程不索取、不代填。保存后读取模型列表，沿用用户已有选择，不硬编码模型名称。

+ - 未配置 API Key 不影响先启动页面，明确区分“工作台已启动”和“模型服务待配置”。不索取密码或把凭据写进仓库。

## 确认交付

- 实际访问首页和 API，确认页面资源可加载、个人目录正确、内置 Skill 文件可读，并检查 Agent 连接及课件编译环境。补齐 TeX 等可选环境后，重新读取 /api/agent/status 的 latex 字段，ready 为 true 且 missing 为空才说课件环境就绪，否则只列仍缺项。已有教材可用时验证读取，不生成假教材；账号未就绪或未提供教材时说明对应功能尚未实用验证。

+ 实际访问首页和 API，确认页面资源可加载、个人目录正确、内置 Skill 文件可读，并检查模型服务配置及课件编译环境。补齐 TeX 等可选环境后，重新读取 /api/agent/status 的 latex 字段，ready 为 true 且 missing 为空才说课件环境就绪，否则只列仍缺项。已有教材可用时验证读取，不生成假教材；模型服务未就绪或未提供教材时说明对应功能尚未实用验证。

- 返回简短结果：可点击的访问地址、安装与数据目录、Agent 状态、未就绪的功能，以及停止和再次启动命令。端口、路径和状态必须来自本次实际运行。无需把安装过程和所有环境检查逐条贴给用户。

+ 返回简短结果：可点击的访问地址、安装与数据目录、模型服务状态、未就绪的功能，以及停止和再次启动命令。端口、路径和状态必须来自本次实际运行。无需把安装过程和所有环境检查逐条贴给用户。