Metadata-Version: 2.5
Name: photon-skills
Version: 3.0.5.dev0
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">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-lockup-dark.png">
  <img src="assets/logo-lockup-light.png" width="520" alt="Photon — Hermes Agent 的學生研究插件">
</picture>

**學生的研究助理，不是<s>代筆</s>。**<br>
由真實生活問題出發，走到可以講出口的成果 —— 每一步都寫進一個導師讀得懂的 Git 專案資料夾。

<p>
  <a href="https://pypi.org/project/photon-skills/"><img src="https://img.shields.io/pypi/v/photon-skills?color=5B6FE0" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E.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 個學生技能">
  <img src="https://img.shields.io/badge/language-zh--Hant%20%2B%20EN-7C3AED.svg" alt="zh-Hant + English">
  <img src="https://img.shields.io/badge/telemetry-none-6B7280.svg" alt="無遙測">
</p>

<p>
  <a href="#這是什麼">這是什麼</a> ·
  <a href="#一個專案怎麼走">流程</a> ·
  <a href="#快速開始">快速開始</a> ·
  <a href="#技能">技能</a> ·
  <a href="#指令">指令</a> ·
  <a href="#導師怎麼用">導師</a> ·
  <a href="#疑難排解">疑難排解</a> ·
  <strong>繁體中文</strong> / <a href="README.en.md">English</a>
</p>

</div>

---

## 這是什麼

Photon 是一個 **Hermes Agent 插件**：八個雙語技能，加上一個 Git 追蹤的專案工作區，
陪中小學生完成 **腦力激盪 → 找資料 → 規劃方法 → 動手做 → Pitch / 辯論** 的整段旅程。

它不替學生寫功課。它問問題、整理結構、把關證據，並把「誰做了什麼」留下記錄 ——
讓導師或老師看得到進度，也看得到 AI 的參與程度。

| | |
|---|---|
| **學生是擁有者** | Photon 引導、草擬、提問；立場、結論與上台的話由學生決定。 |
| **一個專案一個資料夾** | `project-card.md`、`source-log.md`、`task-log.md`、`decisions.md`、`session-log/`、`mentor-feedback/`。 |
| **Session 有連續性** | 開始時載入專案脈絡，結束時寫紀錄並自動 commit —— 隔一星期再開也接得上。 |
| **導師零安裝** | 導師不需要裝任何東西，直接讀那個資料夾，或看學生跑一次 `mentor-summary`。 |
| **資料留在學生電腦** | 零遙測、零第三方依賴；只有主動 `sync` 才會上傳，而且預設 private。 |

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

## 一個專案怎麼走

<p align="center">
  <img src="assets/photon-flow.svg" alt="Photon 流程：一個專案、六道關口；photon-orchestrator 貫穿全程，所有產物寫進同一個 Git 專案資料夾" width="100%">
</p>

六道關口，每道都留下產物與決定。`photon-orchestrator` 在每次 session 開頭讀
`project-card.md` 與最近的 `session-log/`，再建議下一步；學生不同意就可以改方向。

## 快速開始

需求：Hermes Agent（有 `hermes plugins` 子命令）、Python 3.10+、Git 2.30+。
macOS、Linux、Windows PowerShell 都可以。

### A. 公開安裝（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

# 3) 啟用，並把技能同步到 profile
hermes plugins enable photon-skills
hermes photon-skills setup --yes
```

驗證：

```bash
hermes photon-skills status     # 版本 + Bundled skills: 8
hermes photon-skills doctor     # 4 check(s): 4 ok, 0 warning, 0 error
```

<details>
<summary>Windows PowerShell 的 venv 路徑</summary>

```powershell
& "$env:USERPROFILE\.hermes\hermes-agent\venv\Scripts\pip.exe" install --upgrade photon-skills
hermes plugins enable photon-skills
hermes photon-skills setup --yes
```

</details>

<details>
<summary>B. 學校 / 協作者：git，釘死某個 commit</summary>

有 repo 權限的話，一條指令完成，而且版本可以被釘住：

```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`。

</details>

## 第一個專案

```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）
```

## 技能

### 學生技能（8 個，隨插件安裝，中英雙語）

| 技能 | 甚麼時候用 |
|---|---|
| `photon-orchestrator` | 每次 session 的入口：讀 `project-card.md`，決定下一步 |
| `photon-session` | 開始 / 結束的紀錄與交接，寫 `session-log/` 並 commit |
| `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)

<details>
<summary>學術技能（23 個，選裝，manual mode）</summary>

研究編排、文獻搜尋、論文寫作、圖表、排版、期刊匹配、專利、軟著等 23 個進階技能
**不隨插件安裝**（它們的參考文件會令安裝掃描由 `safe` 變 `caution`）。它們以靜態
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 條引用），需要時按文件手動執行，
> 或到上游取得。這是刻意的取捨，不是缺漏 —— 對照表見
> [docs/design/legacy-parity.md](docs/design/legacy-parity.md)。

</details>

## 指令

<details>
<summary>全部指令（13 個）</summary>

| 指令 | 用途 |
|---|---|
| `setup [--profiles A,B] [--yes] [--soul-md\|--no-soul-md] [--force-soul-md]` | 把 8 個技能（可選 SOUL.md）同步到 profile |
| `status` | 每個 profile 的版本、技能數、SOUL.md |
| `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`） |
| `doctor [--dir ...] [--json]` | 診斷技能同步、state、extension、舊安裝與專案狀態（有 error 時 exit 1） |
| `repair [--profile ...] [--force]` | 套用安全修復；`--force` 才會覆蓋你改過的技能 |
| `feedback export [--dir ...] [--since ...] [--out ...]` | 匯出技能 diff + 專案證據供人審閱（不上傳） |
| `selftest` | 快速自測 workspace 邏輯（exit 0） |

`update` 已棄用：更新走 `pip install --upgrade photon-skills`（或
`hermes plugins update`，如果你是用 git 安裝）。

</details>

## 隱私與安全

- **不收集個資**：不要求、不儲存全名、地址、電話或聯絡方式。
- **零遙測**：不對外發送任何資料，沒有分析或追蹤碼。
- **不外傳**：只有明確執行 `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`。

## 成果示範

學術版技能的完整交付形態：合成數據 → 分析 → 程序化圖表 → 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="英語科學論文首頁" width="480">
  </a><br>
  <sub><a href="projects/photocatalytic-dye-kinetics-study/paper/main.pdf">閱讀 PDF</a></sub>
</p>

| <img src="projects/photocatalytic-dye-kinetics-study/figures/figure1_kinetics.png" alt="動力學擬合" width="420"> | <img src="projects/photocatalytic-dye-kinetics-study/figures/figure2_response_surface.png" alt="反應曲面" width="420"> |
|---|---|
| <sub>動力學擬合</sub> | <sub>反應曲面</sub> |
| <img src="projects/photocatalytic-dye-kinetics-study/figures/figure3_diagnostics.png" alt="模型診斷" width="420"> | <img src="projects/photocatalytic-dye-kinetics-study/figures/figure4_scavenger_effects.png" alt="捕獲劑效應" width="420"> |
| <sub>模型診斷</sub> | <sub>捕獲劑效應</sub> |

## 升級、遷移、移除

<details>
<summary>由舊版遷移</summary>

| 你之前裝過 | 要做什麼 |
|---|---|
| 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/skills/`。舊 `light-*` 技能可刪；23 個學術技能已改名 `photon-*`，改以 extension 提供 |
| 舊版留在 profile 的 `photon-*` 技能 | 換版本後跑一次 `hermes photon-skills setup --yes`，會按內容 hash 更新；你改過的副本會被保留並報告 |

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

</details>

<details>
<summary>升級與移除</summary>

```bash
# 升級（PyPI）
~/.hermes/hermes-agent/venv/bin/pip install --upgrade photon-skills
hermes photon-skills setup --yes

# 用 git 安裝的話
hermes plugins update photon-skills

# 移除插件（保留 profile 內的技能副本）
hermes plugins remove photon-skills

# 連技能一併移除（專案資料夾不受影響）
rm -rf ~/.hermes/skills/photon-* ~/.hermes/skills/.photon-skills.json
```

</details>

## 疑難排解

<details>
<summary>常見症狀</summary>

| 症狀 | 處理 |
|---|---|
| `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` |
| `doctor` 報 `skill sync` warning | 你的副本與官方版本不同：保留改動就繼續用，想交回上游就跑 `feedback export`，想還原官方版就跑 `repair --force` |
| 不確定哪裡壞了 | 先跑 `hermes photon-skills doctor`（加 `--json` 可貼給我）；安全修復用 `repair` |
| 完全載入不到 | `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`。
專案資料夾不受影響。

</details>

<details>
<summary>維護者：開發、契約檢查、發佈</summary>

```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)。

品牌素材的原始檔在 [`assets/brand/src/`](assets/brand/src/)：lockup 與 social card
是 HTML + 瀏覽器截圖，流程圖用 `python assets/brand/src/make_flow.py` 重新生成。

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

</details>

## 授權

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

Photon 是獨立衍生專案，與原作者的 `Light0305/Light-skills` repo 無隸屬或背書關係；
該 repo 未被本專案修改。MIT 要求保留上述版權聲明，授權檔亦隨 wheel 附上。
