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

<div align="center">

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

# Photon Skills

**面向科研、競賽與創新項目的 AI 全流程技能包**

<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/skills-30-5B6FE0.svg" alt="30 skills">
  <img src="https://img.shields.io/badge/Claude%20Code-ready-8AA0FF.svg" alt="Claude Code ready">
  <img src="https://img.shields.io/badge/Codex-ready-FFA63D.svg" alt="Codex ready">
  <img src="https://img.shields.io/badge/OpenCode-ready-22C55E.svg" alt="OpenCode ready"><br/>
  <img src="https://img.shields.io/badge/LaTeX-typesetting-008080.svg" alt="LaTeX typesetting">
  <img src="https://img.shields.io/badge/Python%20%2B%20R-figures-7C3AED.svg" alt="Python and R figures">
</p>

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

</div>

---

## 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 上)

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

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

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

### 快速開始

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

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

### 隱私原則(簡版)

- **不收集個資**:不要求、不儲存學生全名、地址、電話或聯絡方式。
- **零遙測**:Photon 不向外發送任何資料;所有記錄都在學生的專案資料夾。
- **不外傳**:專案資料只在明確同意後,才經 `sync --remote` 發布到 GitHub
  (預設 private)。
- 完整版見 [docs/design/safety-privacy.md](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 或本地數據庫；最新信息在任務現場核查。

## 先安裝

先進入倉庫目錄：

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

### Codex

```powershell
# 項目級：$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

```powershell
# 項目級：$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

```powershell
# 項目級：$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\"
```

安裝後檢查：

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

## 環境要求

### 基礎環境

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

### LaTeX 環境

```powershell
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 環境

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

## 科研主線

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

<p align="center">
  <img src="assets/research-workflow.zh.svg" alt="Light Skills 科研主線：從問題到交付的七階段可審計流程" width="960">
</p>

| 階段 | 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 的完整交付形態。

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

## 圖表展示

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

<p align="center">
  <img src="examples/e2e-research-demo/figures/research_figure_gallery.png" alt="Light Skills research figure gallery" width="920">
</p>

## 許可證

本項目使用 [MIT License](LICENSE)。

## 發佈到 PyPI(Issue #42)

[![PyPI version](https://img.shields.io/pypi/v/photon-skills)](https://pypi.org/project/photon-skills/)

`photon-skills` 已在 PyPI 上線(2.0.0)。版本號以 `pyproject.toml` 為唯一來源,
`src/photon/plugin.yaml` 由腳本同步:

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

Trusted publisher 已在本 repo 的 `.github/workflows/publish.yml` 註冊
(`photon-skills` ← `Uniterra-Solutions/Photon-skills`,environment 留空);
以後打 tag 即自動發佈,無需任何手動步驟。
