photon-skills 3.0.4.dev0__tar.gz → 3.0.5.dev0__tar.gz

{photon_skills-3.0.4.dev0 → photon_skills-3.0.5.dev0}/CHANGELOG.md

@@ -6,6 +6,20 @@ The project follows a pragmatic release-note style rather than claiming strict s
 
 ## [Unreleased]
 
+### Changed
+
+- **New brand mark.** The inherited Light Skills icon (crescent + spire + network, blue/violet
+  gradients) is replaced by an original single-colour mark: a diamond — a packet of light —
+  cut by a slit and slid apart. Both masses are cut to equal area (a 6.6° slit through the
+  centre), so the step, not a weight difference, does the work. It ships as
+  `assets/photon-mark.svg` (transparent, `currentColor`), `photon-app-icon.svg` (full bleed,
+  no baked radius — the platform supplies the mask), `photon-mark-tile.svg` for inline
+  lockups, 16/32/64 favicons and a re-rendered `social-preview.png`; the flow diagram and
+  cards move to an ink + amber palette. On the social card the negation is drawn rather than
+  coloured: a two-pass red marker stroke (`assets/brand/src/marker-strike.svg`) crosses out 代筆. A separate `photon-mark-small.svg` is used at favicon
+  sizes: the same 6.6° construction with a 22-unit band, because a 13-unit slit antialiases
+  shut at 16px.
+
 ## [3.0.3] - 2026-10-30
 
 ### Added
@@ -35,6 +49,18 @@ The project follows a pragmatic release-note style rather than claiming strict s
 
 ### Documentation
 
+- **README re-laid-out around real media (both editions).** The page now opens with a
+  dark/light logo lockup, a one-line position, a PyPI version badge and anchor nav;
+  the product story is carried by `assets/photon-flow.svg` (one project, six gates,
+  one shared folder) instead of the retired "research workflow" diagram; the 13-command
+  table, migration table, troubleshooting and maintainer notes moved into `<details>`;
+  the paper demo gained a four-figure grid.
+- **Stale brand media replaced.** `assets/social-preview.png` still said "Light Skills"
+  and listed Claude Code / Codex / OpenCode; it is now a 1280×640 Photon card. The
+  simplified-Chinese `research-workflow.{zh,en}.svg` diagrams (old `light-*` skill
+  names) are removed. Brand sources live in `assets/brand/src/`: HTML for the lockups
+  and social card, `make_flow.py` for the diagram. `assets/logo.png` is downscaled
+  from 1.3 MB to 202 KB.
 - **README rewritten as a plugin-first guide** (zh + en): the two real install
   channels (PyPI into Hermes's own venv; git + pinned SHA for schools and
   collaborators), migration from pip+shim and from Light-skills, the actual

{photon_skills-3.0.4.dev0 → photon_skills-3.0.5.dev0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Light0305
+Copyright (c) 2026 Uniterra Solutions Limited
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

photon_skills-3.0.5.dev0/PKG-INFO

@@ -0,0 +1,343 @@
+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 附上。