Metadata-Version: 2.5
Name: photon-skills
Version: 3.0.3.dev3
Summary: Photon — STEAM research, debate, and pitch competition companion for primary/secondary students
Author-email: Uniterra Solutions Limited <harryw07801@uniterra-solutions.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<img src="assets/logo.png" alt="Photon Skills logo" width="170">

# Photon Skills

**Hermes Agent 的 STEAM 專案助手:8 個雙語學生技能 + Git 專案工作區**

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
  <img src="https://img.shields.io/badge/Hermes-plugin-5B6FE0.svg" alt="Hermes plugin">
  <img src="https://img.shields.io/badge/student%20skills-8-22C55E.svg" alt="8 student skills">
  <img src="https://img.shields.io/badge/language-zh--Hant%20%2B%20EN-7C3AED.svg" alt="zh-Hant and English">
  <img src="https://img.shields.io/badge/telemetry-none-6B7280.svg" alt="No telemetry">
</p>

<p><strong>繁體中文</strong> · <a href="README.en.md">English</a></p>

</div>

---

## 這是什麼

Photon 是一個 **Hermes Agent 插件**。它幫中小學生由真實生活問題出發,完成
**腦力激盪 → 找資料 → 規劃方法 → 動手做 → 準備 pitch** 的專案旅程,
並把整個過程寫入一個由 Git 追蹤的專案資料夾,讓導師/老師看得到進度與 AI 分工。

- **學生是工作的擁有者**:Photon 是研究助理,引導但不代勞。
- **一個專案一個資料夾**:`project-card.md`、`source-log.md`、`task-log.md`、
  `session-log/`、`decisions.md`、`mentor-feedback/`。
- **Session 連續性**:開始時載入專案脈絡,結束時寫紀錄並自動 commit。
- **安全與誠信內建**:內容護欄、AI/學生分工標示、`audit-report` 給教育者審查。
- **零遙測、零第三方依賴**:資料留在學生的電腦,只有主動 `sync` 才會上傳。

> 這份 README 是唯一的安裝說明。舊版的多客戶端安裝(Codex / Claude Code /
> OpenCode + `bootstrap_agent_skills.py`)已退役,見
> [docs/legacy-multi-client.md](docs/legacy-multi-client.md)。

## 需求

| 項目 | 要求 |
|---|---|
| Hermes Agent | 需要 `hermes plugins` 子命令(2026-09 之後的版本) |
| Python | 3.10+(Hermes 自帶的 venv 已滿足) |
| Git | 2.30+(專案資料夾用 Git 追蹤) |
| 系統 | macOS、Linux、Windows PowerShell |

## 安裝

### A. 公開安裝(PyPI)— 個人/學生

這個 repo 是 private,公開渠道是 PyPI。**必須裝進 Hermes 自己的 venv**,
否則 `import photon` 找不到。

```bash
# 1) 確認 Hermes 的 venv 位置(通常是 ~/.hermes/hermes-agent/venv)
dirname "$(dirname "$(which hermes)")"

# 2) 裝進去(macOS / Linux)
~/.hermes/hermes-agent/venv/bin/pip install --upgrade photon-skills

# Windows PowerShell:
# & "$env:USERPROFILE\.hermes\hermes-agent\venv\Scripts\pip.exe" install --upgrade photon-skills

# 3) 啟用
hermes plugins enable photon-skills
```

驗證:

```bash
hermes plugins list --user --plain | grep photon-skills
hermes photon-skills status          # 應顯示目前版本與 Bundled skills: 8
```

### B. 學校/協作者(git,釘 SHA)

有 repo 權限的話,一條指令完成,而且可以釘死某個 commit:

```bash
hermes plugins install Uniterra-Solutions/Photon-skills/src/photon \
  --ref <40 位 commit SHA> --enable
```

`src/photon` 是插件目錄;subdir 安裝只會複製該目錄,技能已放在裡面。
釘 SHA 之後 `hermes plugins update` 會拒絕移動版本,要換版本就再跑一次
`plugins install ... --ref <新 SHA> --force`。

### C. 由舊版遷移

| 你之前裝過 | 要做什麼 |
|---|---|
| pip `photon-skills` + 手寫 `~/.hermes/plugins/photon-skills/` shim | `hermes plugins remove photon-skills` → `rm -rf ~/.hermes/plugins/photon-skills` → `pip uninstall photon-skills` → 用上面 A 或 B 重裝 |
| `photon` 1.0.0(PR #26 時代) | `pip uninstall photon`,並移除 `~/.hermes/plugins/photon/` |
| `Light0305/Light-skills` 的本機 clone + `.agents/skills`、`.claude/skills`、`.opencode/skills` | 刪掉**你本機**的 clone 與鏡像目錄(上游 repo 不屬本專案,不受影響);Photon 只用 Hermes profile 的 `~/.hermes/skills/`。舊 `light-*` 技能可直接刪;23 個學術技能已改名 `photon-*` 並改以 extension 提供 |
| 舊版留在 profile 的 `photon-*` 技能 | 換版本後跑一次 `hermes photon-skills setup --yes`,會按內容 hash 更新;你改過的副本會被保留並報告 |

**專案資料夾(`~/Photon/...`、`session-log/`、`source-log.md`)在任何安裝/
升級/移除過程中都不會被觸碰。**

## 第一個專案

```bash
hermes photon-skills start-project "Water Filter Design" --steam SCIENCE
cd ~/Photon/"Water Filter Design"

hermes photon-skills session-start        # 載入 project-card 與最近 session
# … 與 Photon 一起工作 …

hermes photon-skills session-end \
  --focus "測試三種濾材" \
  --work-done "完成第一輪過濾實驗" \
  --next "量測濁度" \
  --ai-notes "AI 協助整理變因" \
  --student-notes "我自己設計裝置"

hermes photon-skills mentor-summary       # 一頁導師摘要
hermes photon-skills sync --remote water-filter   # 發佈到 GitHub(預設 private)
```

## 指令

| 指令 | 用途 |
|---|---|
| `setup [--profiles A,B] [--yes] [--soul-md\|--no-soul-md] [--force-soul-md]` | 把 8 個技能(可選 SOUL.md)同步到 profile |
| `status` | 每個 profile 的版本、技能數、SOUL.md |
| `update` | **已棄用**;更新走 `hermes plugins update` 或重新 `pip install --upgrade` |
| `start-project <名稱> [--steam ...] [--dir ...]` | 建立專案工作區(含 `git init`) |
| `session-start [--dir ...]` | 載入專案脈絡 |
| `session-end --focus ... [--source ...] [--decision ...] [--task ...] [--stage ...]` | 寫 session-log、更新來源/決策/任務、自動 commit |
| `audit-report [--dir ...]` | 教育者審計(AI vs 學生分工) |
| `mentor-summary [--dir ...]` | 一頁導師摘要 |
| `sync [--message ...] [--remote <repo>] [--public]` | 本地 commit / 建 GitHub remote 並 push / 離線模式 |
| `extensions list\|install\|remove <name> [--profiles A,B]` | 選裝技能包(目前:`academic-skills`) |
| `selftest` | 快速自測 workspace 邏輯(exit 0) |

## 技能

### 學生技能(8 個,隨插件安裝,雙語)

| 技能 | 作用 |
|---|---|
| `photon-orchestrator` | Session 入口:讀 `project-card.md`,決定下一步 |
| `photon-session` | Session 開始/結束的紀錄與交接 |
| `photon-brainstorm` | 引導式腦力激盪,產出衝刺/穩妥/保底點子 |
| `photon-source-filter` | 判斷來源可不可信、有沒有用 |
| `photon-method-planner` | 把點子變成可執行方法:步驟、材料、變因、對照、安全 |
| `photon-progress-tracker` | 管理 `task-log.md`,依狀態建議下一步 |
| `photon-pitch-coach` | Pitch 敘事弧線與排練 |
| `photon-debate-coach` | 辯論/研討會:雙邊論點地圖、反駁路線、計時大綱 |

詳細設計:[學生技能審計](docs/design/student-skill-audit.md) ·
[安全與隱私](docs/design/safety-privacy.md) · [Git 持久化](docs/design/git-persistence.md)

### 學術技能(23 個,選裝,manual mode)

研究編排、文獻搜尋、論文寫作、圖表、排版、期刊匹配、專利、軟著等 23 個進階
技能**不隨插件安裝**(它們的參考文件會令安裝掃描由 `safe` 變 `caution`,
非 catalog 來源會被拒絕)。它們以靜態 zip 隨插件出貨,按需解壓:

```bash
hermes photon-skills extensions list
hermes photon-skills extensions install academic-skills
hermes photon-skills extensions remove  academic-skills
```

> **Manual mode**:這 23 個技能只附 `SKILL.md` 與 `references/`。文中引用的
> `scripts/`、`assets/` 不隨此建置發佈(共 240 條引用),需要時按文件手動
> 執行步驟,或到上游 repo 取得。這是刻意的取捨,不是缺漏。完整清單與技能地圖見
> [skills-academic/README.md](skills-academic/README.md)。

<p align="center">
  <img src="assets/research-workflow.zh.svg" alt="Photon 學術版:從問題到交付的七階段可審計流程" width="900">
</p>

## 隱私與安全

- **不收集個資**:不要求、不儲存全名、地址、電話或聯絡方式。
- **零遙測**:Photon 不對外發送任何資料,亦無任何分析/追蹤碼。
- **不外傳**:只有明確執行 `sync` 才會 commit/push,而且預設 private。
- **AI 分工透明**:`session-log` 分開記錄 `ai-notes` 與 `student-notes`;
  `audit-report` 給老師核對 AI 參與程度。
- 完整版:[docs/design/safety-privacy.md](docs/design/safety-privacy.md)

## 導師怎麼用

導師不需要安裝任何東西:

1. 學生把專案資料夾(或 GitHub repo 網址)給你。
2. 直接讀 `project-card.md`、`session-log/`、`source-log.md`、`task-log.md`、
   `mentor-feedback/`。
3. 學生用 `hermes photon-skills mentor-summary` 產生一頁摘要;你的回饋由學生
   記錄進 `mentor-feedback/`。
4. 需要核對 AI 參與時,請學生跑 `hermes photon-skills audit-report`。

## 疑難排解

| 症狀 | 處理 |
|---|---|
| `hermes photon-skills: not a hermes command` | 插件未啟用:先 `hermes plugins list`,再 `hermes plugins enable photon-skills` |
| `status` 顯示 `0 tracked` | 技能未同步:跑 `hermes photon-skills setup --yes` |
| 版本顯示舊版 | 裝的是舊 wheel 或舊 pin:`pip install --upgrade photon-skills`,或 `plugins install ... --ref <新 SHA> --force` |
| 你改過的技能沒有更新 | `setup` 會保留你的副本並報告(`kept your edited copy of …`),這是設計;要取回官方版就備份後刪掉該技能目錄再 `setup` |
| 完全載入不到 | `HERMES_PLUGINS_DEBUG=1 hermes plugins list` 看發現/載入日誌;`hermes logs --level WARNING \| grep -i plugin` |

**手動 fallback**(插件連載入都失敗時):刪 `~/.hermes/plugins/photon-skills/`
→ `pip uninstall photon-skills` → 用上面 A 或 B 重裝 → `hermes plugins enable
photon-skills`。專案資料夾不受影響。

## 開發與發佈(維護者)

```bash
python scripts/check_plugin_contract.py   # 契約檢查(本機有 hermes 會順便跑 validate)
python scripts/release.py --selftest
python -m pytest tests/ -q
hermes plugins validate src/photon
```

發佈流程:先在 default branch 寫入版本(`python scripts/release.py --set
X.Y.Z`),commit,再 tag `vX.Y.Z`。CI 會驗證 tag = tree 才發佈,CI 不會改寫版本。
詳見 [CONTRIBUTING.md](CONTRIBUTING.md) 與
[docs/design/plugin-distribution.md](docs/design/plugin-distribution.md)。

> catalog 上架暫不可行:curated catalog 要求公開 repo,本 repo 是 private。
> 現時渠道是 PyPI(公開)與 git + SHA(學校/協作者)。

## 論文與圖表示範

學術版技能的完整交付形態:從合成數據、分析、程序化圖表到 LaTeX PDF。

<p align="center">
  <a href="projects/photocatalytic-dye-kinetics-study/paper/main.pdf">
    <img src="projects/photocatalytic-dye-kinetics-study/paper/main-preview.png" alt="English science paper preview" width="540">
  </a><br>
  <sub><a href="projects/photocatalytic-dye-kinetics-study/paper/main.pdf">閱讀 PDF</a></sub>
</p>

## 授權

MIT — 見 [LICENSE](LICENSE)。作者:Uniterra Solutions Ltd;原始 Light-skills
作者:Light0305。
