---
name: learning-map-upload
description: Upload and persist ITTOView 一图流 learning-map images. Use when the user provides an image path or asks to 上传/传一下/放一下/删除/隐藏 a learning-map image in this project; requires copying into /home/ittoview/src/data/image, choosing a stable numbered Chinese filename, verifying local and /learning-images/ visibility, then committing and pushing the image changes to Git so they are not lost.
---

# Learning Map Upload

## 核心原则

一图流图片目录属于 Git 项目，同时被 Docker 运行时挂载：

- Git/宿主机真实目录：`/home/ittoview/src/data/image`
- 线上静态目录：`https://itto.topwind.top/learning-images/`
- 内网静态目录：`http://11.144.144.9:8035/learning-images/`
- 页面路径：`https://itto.topwind.top/learning-maps`

新增、覆盖或删除图片时，只操作真实目录。新增图片**不需要重启 Docker**；但因为目录属于 Git 仓库，所有图片变更必须提交并推送，避免后续拉取/重置/部署导致图片丢失。

## 必须执行的闭环流程

1. 读取用户给出的图片路径，必要时用 `view_image` 查看内容。
2. 根据图片主题命名，格式为：`NN-主题.png/jpg` 或 `NN-主题一图流.png/jpg`。
3. 复制到 `/home/ittoview/src/data/image/`，不要复制到其他目录。
4. 用 `ls -lh` 确认本地文件真实存在。
5. 用 `curl https://itto.topwind.top/learning-images/ | grep 'NN-'` 确认公网线上挂载目录可见。
6. 用 `git status --short` 确认图片变更已出现。
7. 执行 `git add src/data/image ...`，提交并推送。
8. 用 `git status --short` 确认工作区干净或只剩无关改动。
9. 回复用户时必须包含：本地文件、线上可见、Git 提交号。

如果第 5 步失败，不要说已上传成功；如果第 7 步失败，不要说流程完成。要明确说明卡在哪一步。

## 编号规则

- 默认使用当前最大编号 + 1。
- 如果用户要求覆盖某张图，保持原编号和文件名。
- 如果用户要求删除或隐藏，删除对应文件，也要提交推送。
- 文件名优先使用图片标题中的业务主题，去掉冗余词。
- 尽量保留“找问题”“一图流”“绩效域”“管理”等识别关键词。
- 保留源文件格式；如果源文件是 JPG，可以使用 `.jpg`。

示例：

- `变更管理找问题` → `15-变更管理找问题一图流.png`
- `常见分解结构一图流` → `16-常见分解结构一图流.png`
- `项目可行性研究关键文档` → `25-项目可行性研究关键文档一图流.png`

## 推荐脚本

上传时优先用：

```bash
.codex/skills/learning-map-upload/scripts/upload_learning_image.sh <source-image> <target-filename>
```

脚本只负责复制和线上校验；脚本成功后仍必须 Git 提交推送。

示例：

```bash
.codex/skills/learning-map-upload/scripts/upload_learning_image.sh \
  /tmp/hapi-blobs/example/image.png \
  26-示例主题一图流.png

git add src/data/image/26-示例主题一图流.png
git commit -m "feat: add learning map image"
git push origin main
```

## 回复模板

成功时：

```txt
已上传、线上确认可见，并已提交推送。

本地文件：
/home/ittoview/src/data/image/NN-主题.png

线上 /learning-images/ 已确认存在：
NN-主题.png

提交：
<commit-sha> <commit-message>
```

失败时：

```txt
流程未完成，卡在：<本地复制 / 线上校验 / Git 提交 / Git 推送>。

已完成：...
失败原因：...
```

## 禁止事项

- 不要只复制文件后回复“已放好”。
- 不要跳过公网 `/learning-images/` 校验。
- 不要因为新增图片而重启 Docker。
- 不要把图片放到 `dist/`、`public/`、临时目录或非真实映射目录。
- 不要忘记 Git 提交推送；未提交图片等同于未完成。