---

Photon — 學生專案助手(Hermes Plugin)🧑‍🔬

Photon 是面向中小學 STEAM 專案的 Hermes Agent 插件:幫學生從真實生活問題 出發,完成 腦力激盪 → 找資料 → 規劃方法 → 動手做 → 準備 pitch 的完整 專案旅程,同時讓導師/老師輕鬆掌握進度與 AI 分工。繁體中文 + 英文雙語。

• 學生是工作的主要擁有者:Photon 是研究助理,引導但不代勞。
• 每個專案一個資料夾,由 Git 追蹤:project-card.md、source-log.md、 task-log.md、session-log/、decisions.md、mentor-feedback/。
• Session 連續性:開始時自動載入專案脈絡,結束時記錄 + 自動 commit。
• 安全與誠信內建:內容護欄、隱私原則、AI/學生分工標示、 audit-report 給教育者透明審計。

安裝(在你的 Hermes 上)

pip install photon-skills            # distribution 名(或: pip install -e /path/to/Photon-skills)

Pip 安裝後,還需要一個 user-plugin shim 才能讓 hermes plugins enable 看到這個插件(entry-point 插件目前不會出現在 plugin CLI 的掃描範圍):

mkdir -p ~/.hermes/plugins/photon-skills
cat > ~/.hermes/plugins/photon-skills/plugin.yaml <<'EOF'
name: photon-skills
version: 2.0.0
description: "Photon — STEAM research, pitch competition, and innovation project companion for primary/secondary students"
author: Uniterra Solutions Ltd
EOF
cat > ~/.hermes/plugins/photon-skills/__init__.py <<'EOF'
"""photon-skills — re-exported from the pip-installed package."""
from photon import register, plugin

__all__ = ["register", "plugin"]
EOF

hermes plugins enable photon-skills   # 插件 ID(entrypoint 名)
hermes photon-skills setup --skillset student   # 學生技能套件(或 full 含學術版)

若曾安裝過舊版 photon 1.0.0(PR #26 時代的 distribution),請先 pip uninstall photon 並移除 ~/.hermes/plugins/photon/ shim,再安裝 新版本,避免新舊兩版共用同一 Python 模組 photon 造成衝突。

CLI 命名空間為 photon-skills,避免與 Hermes 內建 photon(iMessage 平台)插件衝突;插件 ID、distribution 與 CLI 統一為 photon-skills, Python 模組名為 photon。

快速開始

hermes photon-skills start-project "Water Filter Design" --steam SCIENCE
cd ~/Photon/"Water Filter Design"
hermes photon-skills session-start                      # 開始 session:載入脈絡
hermes photon-skills session-end --focus "做了什麼" \
  --work-done "完成了…" --next "下一步…" \
  --ai-notes "AI 協助…" --student-notes "我自己做了…"   # 結束:記錄 + commit
hermes photon-skills mentor-summary                     # 一頁導師摘要
hermes photon-skills sync --remote water-filter         # 發布到 GitHub(預設 private)

完整指令

指令	用途
setup [--skillset student|full]	安裝技能 + SOUL.md 到 profile;選擇學生/完整技能集
status	查看各 profile 安裝狀態
update [--check]	檢查/更新插件
start-project <名稱> [--steam ...] [--dir ...]	建立專案工作區(含 git init)
session-start [--dir ...]	載入專案脈絡(project-card + 最近 session)
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 遠端並 push / 離線模式

學生技能套件(7 個,雙語)

photon-orchestrator · photon-session · photon-brainstorm · photon-source-filter · photon-method-planner · photon-progress-tracker · photon-pitch-coach

詳細設計:學生技能審計 · 安全與隱私 · Git 持久化策略

隱私原則(簡版)

• 不收集個資:不要求、不儲存學生全名、地址、電話或聯絡方式。
• 零遙測:Photon 不向外發送任何資料;所有記錄都在學生的專案資料夾。
• 不外傳:專案資料只在明確同意後,才經 sync --remote 發布到 GitHub (預設 private)。
• 完整版見 docs/design/safety-privacy.md。

導師怎麼用(v0.1)

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

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/(AI 會主動提醒)。
4. 需要透明審計時,hermes photon-skills audit-report 呈現 AI vs 學生分工。

---

Light Skills — 科研全流程技能包(學術版)

以下是 Photon 的前身與學術版:一套公開、通用、領域無關的 AI skill 包,用來把 一個科研/競賽/創新項目從“模糊想法”推進到“可檢查的交付物”,供導師、 研究人員與進階使用者(hermes photon-skills setup --skillset full)。

它適合這些場景：

你現在的需求	Light Skills 會怎麼幫
我只有一個研究方向	追問目標、約束、數據來源和評價標準，再拆成階段計劃
我有一個 idea，但不知道新不新	檢索相似工作、拆 target/background、找最強反例和審稿人攻擊點
我要做實驗/數據分析	設計數據流、實驗矩陣、腳本、自測、結果解釋和魯棒性檢查
我要寫英文論文	組織故事線、圖表、引用核查、LaTeX 排版、投稿前檢查
我要畫科研圖	用 Python/R 程序化出圖，檢查尺寸、字號、色盲安全、視覺誠實
我要做競賽/項目展示界面	設計 frontend demo、系統結構、交互頁面和展示材料
我要準備專利/軟著材料	生成交底書草案、技術方案、實施例、軟著文檔清單
我要跨對話繼續項目	用項目台賬記錄目標、決策、產物、未驗證聲明和下一步

為什麼適合科研項目？

• 先讀再寫：先讀文件、數據、日志和論文源，再判斷下一步。
• 查不到就標 unknown：事實、DOI、鏈接、期刊規則和軟件版本不靠猜。
• 圖表必須可覆現：論文圖、數據圖、實驗圖走 Python/R 程序化生成。
• 關鍵節點問用戶：選題、創新性、證據強度、投稿目標和繼續投入都應有人確認。
• 不依賴私有知識庫：公開版不要求 MCP 或本地數據庫；最新信息在任務現場核查。

先安裝

先進入倉庫目錄：

git clone https://github.com/Light0305/Light-skills.git
cd Light-skills
$env:PYTHONUTF8="1"

Codex

# 項目級：$REPO\.agents\skills
$env:PYTHONUTF8="1"
python scripts\bootstrap_agent_skills.py --targets agents --mode auto --force

# 全局級：$HOME\.agents\skills
New-Item -ItemType Directory -Force "$HOME\.agents\skills" | Out-Null
Copy-Item -Recurse -Force .\skills\* "$HOME\.agents\skills\"

Claude Code

# 項目級：$REPO\.claude\skills\<skill>\SKILL.md
$env:PYTHONUTF8="1"
python scripts\bootstrap_agent_skills.py --targets claude --mode auto --force

# 全局級：$HOME\.claude\skills
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Copy-Item -Recurse -Force .\skills\* "$HOME\.claude\skills\"

OpenCode

# 項目級：$REPO\.opencode\skills\<skill>\SKILL.md
$env:PYTHONUTF8="1"
python scripts\bootstrap_agent_skills.py --targets opencode --mode auto --force

# 全局級：$HOME\.config\opencode\skills
New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills" | Out-Null
Copy-Item -Recurse -Force .\skills\* "$HOME\.config\opencode\skills\"

安裝後檢查：

$env:PYTHONUTF8="1"
python scripts\bootstrap_agent_skills.py --check-only

環境要求

基礎環境

• Git
• Python 3.10+
• Windows 上運行 Python 前建議設置：$env:PYTHONUTF8="1"

LaTeX 環境

winget install --id MiKTeX.MiKTeX --accept-package-agreements --accept-source-agreements
latexmk -v
pdflatex --version
xelatex --version
biber --version

用於論文排版、PDF 編譯、模板檢查。light-typesetting 支持 latexmk、pdfLaTeX、XeLaTeX、LuaLaTeX、BibTeX、Biber；如果本機缺工具，會標記 UNAVAILABLE，不會假裝已經排版成功。

R 環境

winget install --id RProject.R --accept-package-agreements --accept-source-agreements
Rscript -e "install.packages(c('ggplot2','scales'), repos='https://cloud.r-project.org')"
$env:PYTHONUTF8="1"
python skills\light-figure\scripts\r_ggplot.py --detect

用於 ggplot2 科研圖。沒有 R 時，圖表技能應先問你：繼續用 Python 誠實降級，還是安裝/配置 R。

從哪里開始？

你可以按當前狀態直接覆制下面的 prompt：

當前狀態	建議入口
只有方向	/light-orchestrator 我想把這個方向做成可投稿英文論文。請先問必要問題，再拆階段、產物、風險和用戶確認點。
已有 idea	$light-idea-critique 批判這個 idea：創新性、可證偽性、相似工作、最強反例、審稿人風險和驗證路線。
已有項目文件	$light-file-reading 先讀取這個項目目錄，列出關鍵文件、已完成內容、未驗證聲明、風險和下一步。
要查文獻	$light-literature-search 圍繞這個問題做檢索策略、關鍵詞擴展、證據地圖和相關工作邊界。
要做實驗	$light-research-plan 給出實驗矩陣、數據需求、評價指標、失敗條件和最小可行驗證。
要畫圖	$light-figure 基於這些數據規劃論文圖，要求程序化生成、可覆現、色盲安全、標注清楚。
要寫論文	$light-paper-writing 根據已有證據組織英文論文結構、貢獻、局限性和自審清單。
要排版投稿	$light-typesetting 基於當前 LaTeX 源、圖、BibTeX 和期刊模板做可覆現編譯與投稿前檢查。
要做界面	$light-frontend-design 為這個科研/競賽項目設計 demo 頁面、組件結構、交互和展示重點。

技能地圖

模塊	技能
總控與連續性	light-orchestrator、light-memory-pm、light-file-reading、light-project-structure
想法與文獻	light-literature-search、light-idea-generation、light-idea-critique、light-research-plan
數據與實驗	light-data-engineering、light-experiment-coding、light-result-analysis
論文交付	light-paper-writing、light-citation、light-consistency、light-typesetting、light-venue-matching、light-review-rebuttal
圖表與展示	light-figure、light-frontend-design、light-system-design
誠信與成果轉化	light-research-ethics、light-patent-disclosure、light-software-copyright

完整技能一覽

技能	主要用途	典型產出
light-orchestrator	總控入口：理解任務、追問必要信息、選擇技能鏈路、設置用戶確認點	階段計劃、技能路由、決策檢查點、工作流台賬
light-memory-pm	項目台賬與跨對話續接，不把私人記憶寫進公開倉庫	項目卡、交接卡、決策日志、續接提示
light-file-reading	讀取論文、PDF、Word、PPT、表格、圖片和項目文件	文件清單、理解筆記、抽取質量報告、未核查聲明列表
light-project-structure	搭建和治理科研/軟件項目目錄，讓產物可維護、可覆現	項目骨架、目錄規範、治理策略、結構檢查
light-literature-search	制定檢索策略、擴展關鍵詞、追蹤證據邊界和相關工作	檢索式、證據地圖、文獻表、PRISMA 式流程記錄
light-idea-generation	從文獻缺口、交叉領域和約束條件中生成候選研究 idea	idea 卡、缺口證據、譜系分析、候選排序
light-idea-critique	批判 idea 的創新性、可證偽性、可行性和致命缺陷	go/no-go 判定、反例清單、修訂路線、創新性證據門
light-research-plan	把問題轉成可執行研究計劃，包括假設、變量、對照和失敗樹	實驗矩陣、預注冊草案、樣本量/功效檢查、覆現計劃
light-research-ethics	檢查倫理、授權、同意、數據邊界和研究誠信風險	倫理風險表、授權生命周期檢查、撤稿/重疊/異常文本提示
light-data-engineering	評估數據身份、訪問權限、質量、劃分、泄漏和漂移風險	數據卡、質量門、泄漏檢查、可用性/可行性報告
light-experiment-coding	構建可覆現實驗代碼、配置、測試和運行記錄	實驗腳手架、配置 schema、seed 審計、run manifest
light-result-analysis	做統計分析、方法適配、過擬合/泄漏檢查和結果解釋	分析報告、統計檢驗、方法兼容性檢查、結果卡
light-figure	規劃並程序化生成論文圖和數據圖，支持 Python 與 R	圖表計劃卡、Python/R 圖、導出包、視覺誠實檢查
light-paper-writing	基於已有證據寫作論文結構、論證鏈、貢獻、局限和自審	IMRaD/會議稿草案、claim-evidence 綁定、自審清單、潤色稿
light-citation	核查引用真實性、DOI、鏈接、定位信息和聲明-引用綁定	引用注冊表、四門核查、可疑引用清單、修覆建議
light-consistency	檢查論文、圖表、PPT、代碼和補充材料之間的一致性	術語表、事實綁定、指標/方法鎖、跨材料一致性報告
light-typesetting	LaTeX 模板排版、編譯、日志預檢和投稿前格式檢查	可編譯 LaTeX/PDF、模板適配、編譯日志、投稿 readiness
light-venue-matching	根據主題、證據、風險和隱私約束匹配期刊/會議	venue 候選表、fit 排名、風險提示、用戶選擇記錄
light-review-rebuttal	分解審稿意見、規劃補實驗、管理承諾並撰寫回覆	回覆矩陣、承諾台賬、實驗請求門、response letter
light-frontend-design	為科研項目、競賽或軟件成果設計界面、組件和展示體驗	頁面結構、組件方案、動效建議、可訪問性/瀏覽器 QA
light-system-design	設計軟件系統架構、接口、數據模型、遷移和上線準備度	架構包、OpenAPI/schema、遷移策略、設計 readiness
light-patent-disclosure	整理發明點、現有技術差異和專利交底材料，不替代律師判斷	專利訪談表、檢索線索、交底書證據包
light-software-copyright	整理軟著申請所需的軟件說明、材料清單和源碼留存計劃	軟著材料包、源碼留存計劃、材料完整性檢查

科研主線

Light Skills 不是讓 AI 悶頭從頭跑到尾，而是把科研拆成可審計、可回退、可交給用戶決策的階段。

階段	Light 主要做什麼	常用技能
接收與理解	讀論文、表格、圖片、項目文件，建立任務邊界與項目台賬	file-reading、memory-pm、project-structure
查新與 idea	檢索文獻、生成候選 idea、做創新性/可行性/致命缺陷批判	literature-search、idea-generation、idea-critique
研究設計	明確假設、變量、對照、樣本量、失敗樹和覆現實驗計劃	research-plan、research-ethics
數據與實驗	整理數據、檢查泄漏和質量、寫實驗代碼、做結果分析	data-engineering、experiment-coding、result-analysis
論文交付	生成可覆現圖表、寫論文、核查引用、檢查全文一致性、LaTeX 排版	figure、paper-writing、citation、consistency、typesetting
投稿與轉化	匹配期刊/會議、準備回覆審稿、整理專利交底或軟著材料	venue-matching、review-rebuttal、patent-disclosure、software-copyright
展示與軟件	需要項目展示、競賽 demo 或軟件系統時，補前端和系統設計	frontend-design、system-design

論文 Demo 展示

一個論文Demo示例，方向是環境化學 / 光催化動力學，它展示了從合成數據、分析、程序化圖表到 LaTeX PDF 的完整交付形態。

_{閱讀 PDF}

圖表展示

下面的九宮格科研圖由 Python 與 R 生成。

許可證

本項目使用 MIT License。

發佈到 PyPI(Issue #42)

版本號以 pyproject.toml 為唯一來源,src/photon/plugin.yaml 由腳本同步:

python scripts/release.py            # patch bump: 2.0.0 → 2.0.1
python scripts/release.py minor      # minor: 2.0.0 → 2.1.0
python scripts/release.py check      # 只看目前版本
python scripts/release.py --selftest # 檢查兩處版本一致,exit 0

腳本會自動更新兩處版本 → commit release: vX.Y.Z → 打 vX.Y.Z tag → 詢問後 push。

Hybrid 發佈模式(tag 驅動 stable + main 自動 dev):

• push vX.Y.Z tag → GitHub Actions 建置並以 trusted publishing(OIDC) 上傳 stable 版本,全程不需手動改版本、不需存 PyPI token。
• push/merge 到 main → CI 自動計算並發佈 dev pre-release X.Y.Z.dev<N>(最後一個 tag 的下一個 patch + 之後的 commit 數)。pip 預設 忽略 pre-release,所以 pip install photon-skills 永遠拿到最新 stable, 只有 pip install --pre photon-skills 才會裝到 dev 版。

首次發佈需在 PyPI 設定頁把本 repo 註冊為 photon-skills 的 trusted publisher(一次性的),之後打 tag 即自動發佈。