main
2 次代码提交
| 作者 | SHA1 | 备注 | 提交日期 | |
|---|---|---|---|---|
 Seth Hobson
|
2d3f6a8527 |
chore: move toolchain to uv-native (no pip, no requirements.txt) (#543)
* chore: move toolchain to uv-native (no pip, no requirements.txt)
The repo previously mixed uv (for plugin-eval) with pip + requirements.txt
(for yt-design-extractor) and raw `python3` invocations in the Makefile and
CI workflows. This makes the toolchain uniformly uv-managed.
## yt-design-extractor
Moved `tools/yt-design-extractor.py` into `tools/yt-design-extractor/` with its
own `pyproject.toml` + `uv.lock`. EasyOCR (and its ~2 GB torch dependency)
becomes an optional extra (`uv sync --extra easyocr`). Deleted
`tools/requirements.txt`.
## Makefile
All targets now route through uv:
- `make install` / `make install-easyocr` / `make deps` / `make check` / `make run*`:
`cd tools/yt-design-extractor && uv run/uv sync`
- `make generate` / `make validate` / `make garden` / `make clean-generated`:
`uv run --project plugins/plugin-eval python tools/...` (reuses plugin-eval's
venv — it already has pyyaml and `extra-paths = ["../.."]` for tools/adapters)
- `make test` / `make smoke-test`: `uv run --project plugins/plugin-eval pytest`
## CI
- `.github/workflows/validate.yml`:
- `multi-harness-generate` swapped from `actions/setup-python@v5` to
`astral-sh/setup-uv@v5` + `uv sync` of plugin-eval before `make generate-all`
- Workflow-level `permissions: contents: read` + `persist-credentials: false`
on every checkout (carrying the security hardening forward consistently)
- `.github/workflows/code-quality.yml`:
- `json-lint` job swapped from `setup-python` to `setup-uv`
- YAML validator now uses `uv run --with pyyaml python` (no pre-step install)
- JSON/TOML validators use `uv run python` (stdlib `json.tool`, `tomllib`)
- Dropped the standalone `pip install pyyaml --quiet` line
## Inline hints
- `plugins/plugin-eval/src/plugin_eval/layers/judge.py`: error message
recommends `uv sync --extra llm` instead of `pip install plugin-eval[llm]`
- `tools/yt-design-extractor/yt-design-extractor.py`: usage docstring and
install hints now reference `make install` / `make install-easyocr` / `uv run`
The pip refs inside plugin-authored commands (deps-audit.md, doc-generate.md,
error-trace.md) describe scanning **user** Python projects — those legitimately
use pip and are out of scope.
Local gates green: make test (385 pass), make garden (0 errors), make validate
clean, ruff + format + ty all pass, markdownlint clean.
* chore: address PR #543 review feedback
- checkmake (Makefile): consolidate the multi-line `.PHONY:` declaration
onto a single line. The previous backslash-continued form was readable
but checkmake couldn't parse it, falsely flagging `validate` and
`clean-generated` as missing from .PHONY. They were already declared —
just invisible to the linter.
Other CodeRabbit feedback declined:
- pyproject.toml dep version constraints (CodeRabbit self-tagged "Low value"):
uv.lock pins exact versions for reproducibility; upper bounds on yt-dlp,
Pillow, etc. would invite stale-pin churn without changing the locked
installation. Tracking upstream aggressively is the right default for a
utility tool.
- SHA-pinning for GitHub Actions (CodeRabbit "Major" but defensible):
Workflow has no write scope (permissions: contents: read on both files),
no secrets are exposed, and the actions involved are first-party Anthropic
(astral-sh, actions/*, DavidAnson). Same policy decision as PR #542 —
blanket SHA pinning is a bigger commitment than this PR's scope warrants.
* chore: pin all GitHub Actions to commit SHAs
Addresses CodeRabbit's Major finding (zizmor `unpinned-uses`). Reverses the
earlier policy decision now that the workflow scope has grown — pins both
workflows consistently in one pass:
- actions/checkout v4 → 34e114876b0b11c390a56381ad16ebd13914f8d5
- actions/setup-node v4 → 49933ea5288caeca8642d1e84afbd3f7d6820020
- actions/upload-artifact v4 → ea165f8d65b6e75b540449e92b4886f43607fa02
- astral-sh/setup-uv v5 → e58605a9b6da7c637471fab8847a5e5a6b8df081
- DavidAnson/markdownlint-cli2-action v18 → eb5ca3ab411449c66620fe7f1b3c9e10547144b0
- oven-sh/setup-bun v2 → 0c5077e51419868618aeaa5fe8019c62421857d6
Each pin keeps the version tag in a trailing comment for human readability
and dependabot/renovate compatibility.
Both workflows YAML-validated locally; functionality unchanged.
|
||
|
Seth Hobson
|
98862b56d8 |
feat: AGENTS.md canonical context + OpenAI harness-engineering layout (#542)
* feat: AGENTS.md canonical context + OpenAI harness-engineering layout Promote AGENTS.md to the committed cross-harness context file (per the agents.md convention and OpenAI's harness-engineering blog). Harness- specific files become thin redirects: - AGENTS.md — canonical, committed (~74 lines, table-of-contents) - CLAUDE.md — `@AGENTS.md` import + Claude-specific addenda - GEMINI.md — Gemini-specific setup only - .gemini/settings.json — redirects Gemini CLI's context to read AGENTS.md - ARCHITECTURE.md — new at root, top-level architectural map - gemini-extension.json — bumps version to 1.7.0, sets contextFileName: AGENTS.md - .gitignore — drops the AGENTS.md entry (file is now committed) Harness support verified: - Codex CLI reads AGENTS.md natively (root → cwd walk, 32 KiB cap) - Cursor 2.5+ reads AGENTS.md natively - OpenCode reads AGENTS.md natively (wins over CLAUDE.md if both exist) - Claude Code: `CLAUDE.md` first line is `@AGENTS.md` (Anthropic's documented interop pattern) - Gemini CLI: `.gemini/settings.json` context.fileName redirect (Gemini doesn't support @-imports) Codex adapter no longer generates AGENTS.md — `emit_global` instead validates the committed file fits Codex's 32 KiB cap and the 150-line table-of-contents convention. Tests updated. Clean-output target no longer touches AGENTS.md. ## Auxiliary files updated for multi-harness reality - `.github/ISSUE_TEMPLATE/bug_report.yml` — dropdown for harness + component path; renames "subagent" → "plugin/agent/skill/command" - `.github/ISSUE_TEMPLATE/feature_request.yml` — scope dropdown covers framework / harness / tooling / docs / CI in addition to components - `.github/ISSUE_TEMPLATE/new_subagent.yml` — relabeled "New Component Proposal" with component-type dropdown (plugin/agent/skill/command/ harness adapter) and cross-harness portability field - `.github/ISSUE_TEMPLATE/config.yml` — links to AGENTS.md, authoring guide, per-harness docs; updated Contributing link to root - `.github/CONTRIBUTING.md` — thin pointer to canonical root CONTRIBUTING.md - `.github/PULL_REQUEST_TEMPLATE.md` — new; scope + affected-harness checklists, test-plan checklist, portability-notes section - CONTRIBUTING.md (root) — updated to reference AGENTS.md / ARCHITECTURE.md - gemini-extension.json — version 1.6.0 → 1.7.0, count fixes, redirects to AGENTS.md as contextFileName ## Code-quality CI New `.github/workflows/code-quality.yml` with three jobs: - `python-lint` — `ruff check`, `ruff format --check`, `ty check` on the adapter framework + plugin-eval. yt-design-extractor.py legacy code excluded. - `markdown-lint` — markdownlint-cli2 against README, AGENTS, ARCHITECTURE, CLAUDE, top-level guides, and docs/. Config in `.markdownlint.json`. - `json-lint` — validates every JSON / TOML / YAML in the repo (excluding generated trees). Required ty environment config added to plugin-eval/pyproject.toml so `tools.adapters.*` resolves from outside the package. Fixed one ty error in `tools/adapters/base.py:HarnessAdapter.capabilities` (return-type annotation didn't match the `Capability` dataclass returned). Fixed two ruff SIM108 ternary suggestions in codex.py and doc_gardener.py. ruff format applied across all in-scope files (formatting-only diffs). ## Tests + verification - 387 pytest tests pass (1 new test for the AGENTS.md validate-don't-overwrite behavior) - `make validate STRICT=1` clean - `make garden` 0 errors (10 warnings — remaining oversize source skills) - `make smoke-test` clean against locally installed OpenCode/Gemini/Codex/Claude Code - Real-CLI round-trip: `opencode agent list` discovers 193 subagents, `gemini extensions validate .` succeeds, all 191 Codex agent TOMLs parse ## Tag recommendations (separate task — for repo About panel) Top 20 by reach + relevance (from `gh api search/repositories?q=topic:<tag>`): automation mcp ai-agents developer-tools claude-code anthropic agentic-ai agents prompt-engineering cursor multi-agent agent-skills orchestration opencode workflows gemini-cli codex-cli claude-code-skills cursor-rules claude-code-plugins * fix(ci): YAML multi-doc + markdownlint scope/rules Two CI failures on PR #542, both fixed: ## JSON/TOML/YAML syntax job (3 false-positive YAML errors) The job's YAML validation used `yaml.safe_load` which only reads the first document in a multi-document YAML stream. Three Kubernetes manifest templates use the standard `---` document separator (valid YAML) and were mis-flagged: plugins/kubernetes-operations/skills/k8s-manifest-generator/assets/configmap-template.yaml plugins/kubernetes-operations/skills/k8s-manifest-generator/assets/service-template.yaml plugins/kubernetes-operations/skills/k8s-security-policies/assets/network-policy-template.yaml Switched to `list(yaml.safe_load_all(...))` so multi-doc YAML is accepted. ## Markdown lint job (lots of pre-existing plugin-README violations) Two changes: 1. **Narrow the lint glob** — markdownlint now runs against top-level guides (README, AGENTS, ARCHITECTURE, CLAUDE, per-harness setup, CONTRIBUTING) and our authored `docs/` only. Per-plugin READMEs (`plugins/*/README.md`) are owned by their plugin authors and not lint-gated as part of this framework PR. Lint enforcement for those belongs at the plugin-author layer, not the framework PR layer. 2. **Tighten `.markdownlint.json`** — disable two rules that produce noise without catching real defects: - MD040 (fenced-code-language) — terminal output / shell command blocks frequently omit a language by convention - MD060 (table-column-style) — cosmetic table-pipe spacing; doesn't affect rendering Genuine formatting rules kept: MD029 (ol-prefix), MD031 (blanks- around-fences), MD032 (blanks-around-lists), MD056 (table-column- count), MD058 (blanks-around-tables). ## Real defects caught and fixed The narrower scope still caught 5 real issues: - `docs/agent-skills.md:397` — code fence inside an ordered list item needed a blank line before the fence - `docs/authoring.md:90` — bulleted list needed a blank line above - `docs/plugin-eval.md:87` — table needed a blank line above - `OPENCODE.md:39` — table-column-count error caused by literal `|` inside backticks: ``mode: primary|subagent|all`` (3 cells reads as 5) Rewrote as ``mode:` one of `primary` / `subagent` / `all`` ## Verification - `npx markdownlint-cli2 "*.md" "docs/*.md"` → 0 errors - `yaml.safe_load_all` accepts all multi-doc YAMLs (0 errors) - All other CI jobs already passing (Python ruff/ty, multi-harness generate, CLI smoke test, plugin-eval pytest, tools pytest) * fix: address PR #542 bot feedback - Codex P2 (chatgpt-codex-connector): emit_global now reads AGENTS.md from the repo root (WORKTREE), not output_root. Previously `--output-root <scratch>` produced a false "missing" warning even when AGENTS.md was committed at the real root, breaking --strict generation outside the repo. Added a constructor arg `repo_root` so tests can stage a fake AGENTS.md without touching the committed file, plus a regression test that proves the two paths are decoupled. - CodeRabbit nitpick (code-quality.yml): added workflow-level `permissions: contents: read` and `persist-credentials: false` on every checkout. Skipped the SHA-pinning recommendation — it's a heavier blanket-policy decision and the workflow has no write scope to abuse. - CodeRabbit nitpick (pyproject.toml): consolidated the duplicate `dev` groups by moving `ty` into `[project.optional-dependencies].dev` and removing the now-empty `[dependency-groups]` block. Dropped `--group dev` from `code-quality.yml`'s `uv sync` since `--all-extras` now covers it. - Verified gemini-extension.json counts (82/191/155/102) against the actual source-of-truth: 81 local plugins + 1 external = 82 in marketplace.json, 191 agent .md files, 155 SKILL.md files, 102 command .md files. Counts are correct as-is — CodeRabbit's quick-win was a regex miscount. |