photon-skills 2.0.0__tar.gz

photon_skills-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: publish
+
+# Hybrid PyPI publishing (Issue #42, option C):
+#   - push a `vX.Y.Z` tag  → stable release (version from the tag)
+#   - push to `main`       → dev pre-release `X.Y.Z.dev<N>` (next patch
+#     after the last tag, N = commits since; pip ignores pre-releases
+#     unless --pre, so stable installs are never shadowed)
+# Uploads via trusted publishing (OIDC) — no tokens stored.
+# First-time setup: register this repo as a trusted publisher on PyPI for
+# the `photon-skills` project.
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write  # required for PyPI trusted publishing
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # need tags + history for the dev version computation
+
+      # Tests commit in temp repos; the runner has no git identity by
+      # default. (workspace.git_commit also falls back when no identity is
+      # configured, so this is belt-and-suspenders.)
+      - name: Configure Git identity for CI
+        run: |
+          git config --global user.email "actions@users.noreply.github.com"
+          git config --global user.name "GitHub Actions"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build + test deps
+        run: |
+          pip install --upgrade pip
+          pip install hatchling
+          pip install -e ".[dev]"
+
+      - name: Run test suite
+        run: |
+          python -m pytest tests/ -q
+          photon-skills-selftest
+
+      - name: Set version (tag → stable, main → dev pre-release)
+        run: |
+          if [[ "${{ github.ref_type }}" == "tag" ]]; then
+            python scripts/release.py --ci-tag "${{ github.ref_name }}"
+          else
+            python scripts/release.py --ci-dev
+          fi
+
+      - name: Verify versions in sync
+        run: python scripts/release.py --selftest
+
+      - name: Build wheel + sdist
+        run: python -m hatchling build
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

photon_skills-2.0.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv*/
+
+# selftest / 临时副产物（脚本临时件用 .upgrade/_e2e，跑完即删）
+.upgrade/_e2e/
+*.tmp
+_synth_*.csv
+demo_*.png
+# figure color_palettes/figure_export selftest 渲染的 demo 图(可复现,不入库)
+_export_demo/
+
+# 本地客户端发现镜像（由 scripts/bootstrap_agent_skills.py 生成；canonical 仍是 skills/）
+.agents/
+.claude/
+.opencode/
+
+# LaTeX 编译产物
+build/
+*.aux
+*.log
+*.out
+*.toc
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+
+# R
+.Rhistory
+.RData
+.Rproj.user/
+
+# OS / 编辑器
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

photon_skills-2.0.0/AGENTS.md

@@ -0,0 +1,39 @@
+# Light-Skills 代理协作说明
+
+本仓库是公开科研全流程技能包，面向 Claude Code / Codex / OpenCode。请把 `skills/` 视为唯一 canonical 技能源；不要把维护者私人记忆、对话史、邮箱、未公开研究、db01-db09、MCP 配置或本地知识库内容写进仓库。
+
+## 客户端发现路径
+
+三类客户端默认发现路径不同。项目级使用前先运行：
+
+```powershell
+$env:PYTHONUTF8="1"
+python scripts\bootstrap_agent_skills.py --mode auto --force
+```
+
+该脚本把 `skills/` 安全映射到：
+
+- `.agents/skills`：Codex / OpenCode open-standard 项目技能路径。
+- `.claude/skills`：Claude Code 项目技能路径，也可被 OpenCode 读取。
+- `.opencode/skills`：OpenCode 原生项目技能路径。
+
+Windows 不能创建目录 symlink 时，脚本会回退为 copy，并写入 `.light_generated_link` 标记；修改 canonical `skills/` 后需重新运行 `--force` 刷新生成副本。脚本不会覆盖没有 Light 生成标记的用户目录。
+
+## 开发纪律
+
+- commit 只署作者本人；标题和正文写中文；不要添加 Co-Authored-By。
+- 不要 push，除非用户明确要求。
+- Python 命令前设置 `PYTHONUTF8=1`；临时产物放 `.upgrade/_e2e`。
+- 用户面向脚本必须亲手跑 `--selftest` 到 exit 0，不能相信“已完成”报告。
+- 动态事实、论文、DOI、star、链接、能力声明查不到就写 `unknown/待核查`。
+- 论文数据图必须程序化生成；禁止 AI 生图冒充数据图。
+- R/ggplot2 是增强路径，不是静默前提：缺 R 或缺包时，先给用户“继续 matplotlib 诚实降级 / 安装或配置 R / 提供 Rscript 路径”的选择；非交互自动流程默认降级并标 `degraded=True`，不得擅自安装。
+
+## 快速自测
+
+```powershell
+$env:PYTHONUTF8="1"
+python scripts\bootstrap_agent_skills.py --selftest
+python scripts\bootstrap_agent_skills.py --check-only
+python skills\light-figure\scripts\r_ggplot.py --selftest
+```

photon_skills-2.0.0/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+All notable changes to Light Skills are documented here.
+
+The project follows a pragmatic release-note style rather than claiming strict semantic-versioning compatibility for every skill prompt. User-facing skill behavior, installation paths, shared contracts, and generated examples should be treated as release-relevant changes.
+
+## [Unreleased]
+
+### Added
+
+- CLI namespace renamed to `photon-skills` to avoid collision with the
+  Hermes-bundled `photon` (Photon Spectrum / iMessage) platform plugin.
+  Commands: `hermes photon-skills <setup|status|update|start-project|session-start|session-end|audit-report|mentor-summary|sync>`.
+- Project workspace scaffolding (`start-project`): `project-card.md`
+  (current + next intended stage), `source-log.md`, `task-log.md`,
+  `decisions.md`, `session-log/`, `mentor-feedback/`, `.photon-project`
+  marker, `.gitignore`, git init. Example project under
+  `examples/demo-student-project/`.
+- Session lifecycle (`session-start` / `session-end`): loads project
+  context (project-card + recent session logs + pending tasks), writes
+  session entries, updates source/task logs, direction-change proposal with
+  confirmation, automatic git commit at session end.
+- Student skill set (Issue #18): `photon-orchestrator`, `photon-session`,
+  `photon-brainstorm`, `photon-source-filter`, `photon-method-planner`,
+  `photon-progress-tracker`, `photon-pitch-coach` (bilingual zh-Hant/en);
+  `setup --skillset student|full` selection; audit doc in
+  `docs/design/student-skill-audit.md`.
+- Safety & privacy (Issue #24): guardrails in every student skill, privacy
+  principles doc, academic-integrity disclaimer in generated outputs,
+  `audit-report` command, safety toggles in setup state.
+- Mentor workflow (Issue #22): `mentor-summary` generates a one-page
+  shareable review; `mentor-feedback/` capture format; orchestrator asks
+  the student to record mentor feedback.
+- Git persistence (Issue #23): `sync` commits and optionally creates +
+  pushes a GitHub remote (`--remote <name>`, private by default), with a
+  local-only offline fallback. Strategy in `docs/design/git-persistence.md`.
+
+### Fixed (PR #32 review follow-ups)
+
+- `propose_stage_update` no longer blanks the Current Stage checklist when a
+  free-text stage is passed (standard stages stay unchecked and the custom
+  stage is appended as a checked line) (Issue #33).
+- Multiple `session-end` runs on the same day no longer repeat the
+  `# Session Log:` H1 heading — later entries start at their `##` section so
+  the file stays one readable document (Issue #34).
+- `session-end --decision "DECISION|REASON|CHANGED"` (repeatable) now appends
+  rows to `decisions.md`, which was previously scaffolded but never written
+  (Issue #38).
+
+### Fixed (Issue #35)
+
+- `safety.audit_mode` is now **enforced**: `audit-report` refuses to run when
+  audit mode is disabled in setup, instead of generating reports regardless.
+- `safety.guardrails` is explicitly documented as **advisory** (every student
+  skill ships with its Safety section regardless); setup prompt text and
+  `docs/design/safety-privacy.md` updated to match.
+
+### Added (Issue #36)
+
+- Committed pytest suite: `tests/test_workspace.py` (scaffolding, card
+  parsing, session lifecycle, logs, stage updates, audit/mentor summaries,
+  git helpers — incl. #33/#34/#38 regressions) and `tests/test_cli.py`
+  (CLI handlers: `--decision`, `--task`, commit, audit-mode enforcement).
+- New `hermes photon-skills selftest` subcommand + `photon-skills-selftest`
+  console script (AGENTS.md discipline: user-facing scripts self-test to
+  exit 0); `dev` extra (`pytest>=8.0`) in pyproject.toml.
+
+### Docs
+
+- README.en.md gains the full Photon section (install / quick start /
+  command table / privacy / mentor guide), matching README.md; both badges
+  updated 23 → 30 skills; README.en.md language link fixed to 繁體中文
+  (Issue #37).
+- Install instructions (both READMEs) now include the required user-plugin
+  shim step for `hermes plugins enable` (entry-point plugins are not
+  scanned by the Hermes plugin CLI), plus an upgrade note for users of the
+  old `photon` 1.0.0 distribution.
+
+### Added (Issue #42)
+
+- Tag-driven PyPI publishing: `scripts/release.py` (single version source
+  in `pyproject.toml`, syncs `plugin.yaml`, bumps → commits → tags → pushes;
+  `--check` / `--selftest` per AGENTS.md) and
+  `.github/workflows/publish.yml` (pytest + selftest gate, hatchling build,
+  trusted-publishing OIDC upload with attestations).
+- Hybrid publishing (option C): main pushes publish dev pre-releases
+  (`X.Y.Z.dev<N>` via `release.py --ci-dev`, computed from the last tag +
+  commit count); `v*` tag pushes publish stable releases
+  (`release.py --ci-tag`). pip ignores pre-releases by default.
+- README (zh/en) "Publishing to PyPI" sections.
+
+### Fixed (CI robustness)
+
+- `workspace.git_commit` falls back to a neutral commit identity
+  (`Photon <photon@localhost>`) via env vars only when git has no
+  user.name/user.email configured anywhere — CI runners and fresh machines
+  can now commit without setup, while real student identities are never
+  overridden. Two regression tests added (fallback + identity preserved).
+- `publish.yml` configures a global git identity for the runner
+  (belt-and-suspenders on top of the code-level fallback).
+
+### Planned
+
+- Continue hardening cross-client compatibility for Codex, Claude Code, and OpenCode.
+- Add more runnable examples for research, competition, software, patent-disclosure, and software-copyright workflows.
+- Improve regression checks for skill installation, evidence handling, citation integrity, and reproducible figure generation.
+- Collect public user feedback through GitHub Issues and convert repeatable problems into documented tests.
+
+## [1.0.0] - 2026-07-05
+
+### Added
+
+- Public Light Skills repository for research, competitions, and innovation projects.
+- 23 domain-independent skills under `skills/`, each using `SKILL.md` as the entry point.
+- Cross-client installation support for:
+  - Codex via `.agents/skills`
+  - Claude Code via `.claude/skills`
+  - OpenCode via `.opencode/skills`
+- `scripts/bootstrap_agent_skills.py` for installing and checking supported agent-skill layouts.
+- Shared contracts under `_shared/` for evidence strength, consistency checks, workflow gates, visual review, and reusable research-process rules.
+- End-to-end research demo under `examples/e2e-research-demo/`.
+- Reproducible LaTeX paper demo under `projects/photocatalytic-dye-kinetics-study/`.
+- Research figure gallery demonstrating programmatic scientific figures.
+- Python and R figure workflow expectations.
+- LaTeX typesetting expectations for paper-oriented workflows.
+- MIT license.
+
+### Changed
+
+- Reworked the earlier Light project into a cleaner public skill package.
+- Consolidated overlapping paper-writing, polishing, figure-planning, and figure-drawing flows into stronger user-facing skills.
+- Replaced private-database framing with public, repository-local, inspectable workflow guidance.
+- Expanded the scope from research-only usage to research, competitions, innovation projects, patents, software copyright materials, and frontend/software demos.
+- Clarified that Light Skills supports innovation work by improving search, critique, evidence binding, and validation planning; it does not promise automatic discovery or guaranteed publication.
+
+### Integrity and safety boundaries
+
+- Unknown facts, DOI values, links, software versions, and venue rules must be marked `unknown` or verified at task time.
+- Paper figures, data figures, and experiment figures must be generated programmatically and remain reproducible.
+- AI-generated marketing visuals must never be presented as scientific evidence.
+- Citation authenticity is a standalone integrity requirement.
+- Private conversations, unpublished research, credentials, email tokens, and local project ledgers must not be committed to the public repository.
+- Patent and software-copyright skills help prepare materials and organize evidence; they do not provide legal advice.
+
+### Compatibility notes
+
+- Windows is the primary development environment for the initial release.
+- Python 3.10+ is expected for repository scripts.
+- Windows users should set `PYTHONUTF8=1` before running Python scripts.
+- LaTeX and R are optional environment layers for workflows that need paper compilation or R-based scientific figures.
+

photon_skills-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing to Light Skills
+
+Thank you for considering a contribution to Light Skills.
+
+Light Skills is a public, domain-independent AI workflow skill package for research, competitions, and innovation projects. Contributions are welcome when they make the package more useful, more reliable, more honest about its limits, or easier to install across Codex, Claude Code, and OpenCode.
+
+## What contributions are useful?
+
+Good contributions include:
+
+- fixing unclear skill instructions;
+- improving cross-client compatibility;
+- adding runnable self-tests for scripts;
+- improving examples, installation docs, or release notes;
+- reporting places where a skill overclaims what it can actually do;
+- strengthening citation, evidence, privacy, or reproducibility checks;
+- adding domain-neutral patterns that help many research areas;
+- improving Python, R, LaTeX, or frontend-demo workflows.
+
+Please avoid contributions that:
+
+- embed one person's private research context into public skills;
+- add unverifiable claims, fake DOI values, fake links, fake metrics, or fake citations;
+- turn generated images into scientific evidence;
+- require private MCP servers, local databases, credentials, or unpublished data for the public package to work;
+- make broad promises such as guaranteed acceptance, guaranteed patents, or automatic scientific innovation.
+
+## Repository structure
+
+```text
+Light-Skills/
+├─ skills/       # Canonical skill source; each skill uses SKILL.md as the entry
+├─ _shared/      # Shared contracts, evidence rules, gates, and helper guidance
+├─ scripts/      # Installation and maintenance scripts
+├─ docs/         # Compatibility notes, release gates, learning notes, and releases
+├─ examples/     # End-to-end user-facing examples
+├─ projects/     # Reproducible demo projects
+└─ assets/       # Public brand, README, QR-code, and preview assets
+```
+
+## Before opening a PR
+
+1. Fork the repository and create a focused branch.
+2. Keep each PR scoped to one change theme.
+3. Read the affected `SKILL.md` file before editing it.
+4. Make sure the change is useful across research fields, not only for one private project.
+5. Do not commit secrets, credentials, personal conversations, unpublished research, or local machine state.
+6. If you used AI assistance, review the output carefully and take responsibility for every claim and line changed.
+
+## Local checks
+
+On Windows PowerShell:
+
+```powershell
+$env:PYTHONUTF8="1"
+python scripts\bootstrap_agent_skills.py --check-only
+```
+
+If you modify a script, add or run the relevant self-test. A script that claims to support `--selftest` or an equivalent check should run successfully before the change is submitted.
+
+If you modify a skill, manually inspect the generated client layout when relevant:
+
+```powershell
+$env:PYTHONUTF8="1"
+python scripts\bootstrap_agent_skills.py --targets agents --mode auto --force
+python scripts\bootstrap_agent_skills.py --targets claude --mode auto --force
+python scripts\bootstrap_agent_skills.py --targets opencode --mode auto --force
+```
+
+## Skill quality rules
+
+Every skill should be:
+
+- **honest**: it must not claim abilities that the instructions or scripts cannot actually support;
+- **domain-neutral**: default behavior should work across fields unless a section is explicitly scoped;
+- **evidence-aware**: uncertain facts must be verified or marked `unknown`;
+- **user-centered**: it should ask the user at meaningful decision points instead of silently pretending to know the correct research direction;
+- **reproducible**: paper figures, data figures, and experiment figures should be generated programmatically;
+- **portable**: public workflows should not depend on a private database, private memory, or a specific user's local setup;
+- **reviewable**: important outputs should leave enough trace for a human to audit them.
+
+## Citation and evidence policy
+
+Light Skills treats citation integrity as a core trust boundary.
+
+- Do not invent papers, authors, DOI values, links, GitHub stars, metrics, or benchmark results.
+- If a fact cannot be verified in the current task context, mark it `unknown` or `待核查`.
+- Do not cite a source you have not actually inspected.
+- Distinguish evidence, inference, and recommendation.
+- Do not use popularity as proof of correctness.
+
+## Figure and media policy
+
+- Scientific figures, data charts, and experiment visuals must be generated from code or traceable source data.
+- AI-generated images may be used for marketing, illustration, or README branding, but must not be represented as paper figures, data figures, or experiment results.
+- Figure workflows should preserve source data, code, labels, units, and reproducibility notes where practical.
+
+## Privacy policy for contributions
+
+Do not include:
+
+- private chat logs;
+- unpublished research details;
+- user emails or credentials;
+- API keys or tokens;
+- local database dumps;
+- private MCP configuration;
+- local project ledgers that are not intended for public release.
+
+If you accidentally commit sensitive information, rotate the credential immediately and open a security report rather than a normal issue.
+
+## Issue reports
+
+When opening an issue, please include:
+
+- what you tried to do;
+- which agent client you used, if any;
+- your operating system;
+- the skill or script involved;
+- the expected behavior;
+- the actual behavior;
+- minimal reproduction steps;
+- relevant logs with secrets removed.
+
+## Pull request checklist
+
+Before submitting, confirm:
+
+- [ ] The change is public and domain-neutral, or clearly marked as domain-scoped.
+- [ ] No private data, credentials, or unpublished research were added.
+- [ ] No unverifiable claims, fake citations, fake DOI values, or fake metrics were added.
+- [ ] Any changed script has a relevant runnable check.
+- [ ] Any changed skill still matches what the repository can actually do.
+- [ ] Documentation was updated when user-facing behavior changed.
+
+## License
+
+By contributing, you agree that your contribution will be licensed under the repository's MIT License.
+

photon_skills-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Light0305
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.