4 Commits

Author	SHA1	Message	Date
不白	65fb2f8181	feat: server-beacon skill-update path for non-Bash clients (#39) ... ## Summary Fixes the silent-update-failure mode where Claude Desktop (and any MCP client without a Bash tool) gets stuck on whatever skill version shipped at first install. On this developer's Desktop the skill had been frozen at `0.1.2` since April — no upgrade ever fired. Root cause is structural: SKILL.md Step 0's update check uses an inline ` ```bash ``` ` block. Claude Code executes it; Desktop reads it as documentation. So the entire upgrade flow is dead code on Desktop. This PR routes the version check through the MCP server instead (always-on, available to every client), and tightens a couple of correctness bugs in the existing install/uninstall path while we're here. Companion PR: chainbase-labs/AgentKey-Server (server-side `agentkey_skill_meta` tool). ## What's in here 1. **Protocol** (`protocol/skill-meta-v1.md` + `skill-meta-v1.schema.json` + 4 fixtures) — versioned, additive-evolution wire format for an MCP meta tool that returns `{skill_version_latest, client_detected, update_command, update_doc_url, …}`. Spec lives in this repo (single source of truth); server vendors a copy and CI on both sides diffs them. 2. **SKILL.md** — Step 0 now has 0.A (beacon, cross-client) → 0.B (inline bash, Code-only compat) → 0.C (MCP tool sanity check). Step B branches every persistence option on whether Bash is available, with explicit no-Bash fallback text that tells the user what didn't get saved and the exact terminal command to persist it manually. Step C points the non-shell fallback at GitHub Releases (we don't have a docs site). 3. **install/uninstall scripts** — `npx skills remove chainbase-labs/agentkey` was the wrong invocation: the CLI takes the skill name (`agentkey`), exits 0 on no-match, and made the uninstaller falsely report success. Same class of silent-success bug in `install.sh` when `git clone` fails mid-run. Both fixed; added post-install filesystem verification. 4. **README / README_zh** — accurate per-client update story, including a one-time bootstrap command for users currently stuck on a pre-1.4.0 skill on Desktop. 5. **CI** (`protocol-validate.yml`) — every fixture validates against the schema, schema rejects 4 known-bad payloads (regression guard), spec doc references every fixture (forces docs ↔ artifact sync). 6. **`docs/SERVER-IMPLEMENTATION.md`** — handoff doc for the server PR. ## How verified - 4/4 fixtures pass schema; 4/4 bad payloads correctly rejected - All cross-references in spec doc resolve - `verify-version-sync` awk still extracts `1.3.0` from SKILL.md frontmatter - Companion server PR exercises the actual MCP handshake (initialize + tools/list + tools/call); response is valid v1 JSON - Real GitHub Releases fetch + ETag caching works on the server side ## Test plan - [ ] CI green (`protocol-validate.yml` and `verify-version-sync.yml` both pass) - [ ] Companion server PR merged + new `@agentkey/mcp` published - [ ] Release-please cuts `v1.4.0` from this branch - [ ] On Claude Code: existing inline-bash Step 0 still fires for users on `v1.3.x`; they get prompted to update normally - [ ] On Claude Desktop with a pre-1.4.0 skill: user runs the README bootstrap command once to land `v1.4.0`; from that point on, every subsequent version is auto-discovered via the meta tool - [ ] On Cursor / Codex: meta tool returns the `npx skills update -g agentkey` recipe; user upgrades via shell ## Notes for the reviewer - This is **additive**: Claude Code's existing inline-bash path is unchanged, so no regression risk there. The protocol's `protocol_version: 1` + immortal `update_doc_url` fallback make future v2 servers safely degradable for v1 skills. - Claude Desktop deliberately has no `update_command` recipe yet — Desktop installs skills into a sandboxed `~/Library/Application Support/Claude/local-agent-mode-sessions/skills-plugin/<UUID>/...` path that no external CLI can reach, and we don't have a first-party installer script. The skill rule's "no command → point at GitHub Releases" fallback handles this until one exists. Adding a Desktop recipe later is a non-breaking change (one row in the server's `RECIPES` map).	2026-05-12 17:46:55 +08:00
MOGU :\'-"/	f05e501e42	chore(install): remove fallback MCP snippet hint (#38) ... ## Summary - The post-install summary printed an `If your agent is NOT Claude Code / Claude Desktop / Cursor` block with a manual MCP JSON snippet. By the time the user sees it, `@agentkey/mcp --auth-login` has already either auto-written the supported configs or surfaced its own error — so this block is ambiguous noise for the supported path, and the canonical fallback for unsupported agents already lives in `SKILL.md`'s Fallback section. - Removed the same block from `install.ps1` to keep the Bash and PowerShell installers in sync. ## Test plan - [ ] `bash scripts/install.sh` ends with `Next steps` → `Docs` → `Uninstall` (no fallback snippet block in between). - [ ] `pwsh scripts/install.ps1` shows the same trimmed summary on Windows. - [ ] Confirm `skills/agentkey/SKILL.md` still documents the manual-paste fallback for non-auto-targeted agents (no doc regression). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-12 15:26:43 +08:00
不白	29176d1aae	feat(install): auto-detect agents, route MCP auth to QR mode for remote installs (#18) ... ## Summary Two end-to-end improvements to `install.sh` / `install.ps1`, mirrored across both: ### 1. Agent auto-detection Probe well-known config dirs and binaries for ~18 of [vercel-labs/skills](https://github.com/vercel-labs/skills)' 45 supported agents (`claude-code`, `cursor`, `codex`, `gemini-cli`, `opencode`, `openclaw`, `qwen-code`, `iflow-cli`, `windsurf`, `warp`, `amp`, `crush`, `goose`, `droid`, `kode`, `kilo`, `kimi-cli`, `kiro-cli`). When detection finds anything, the `skills add` step gets `-a id1,id2,…` instead of dumping the user into the multi-select. New flags: - `--list-agents` — preview what we'd auto-select (and exit) - `--all-agents` — skip our detection, let `skills` CLI scan everything - `--only` — manual override (unchanged) ### 2. Local-vs-remote MCP auth routing The current `--auth-login` always auto-opens a browser. On SSH sessions, Docker containers, and OpenClaw remote channels (where the user is on a phone), that silently launches a browser they can't see — leaving them stuck on "Waiting for authorization…". Detection (any signal fires ⇒ remote): | Signal | Notes | |---|---| | `$HOME/.openclaw` exists | OpenClaw runtime — most reliable single signal | | `$SSH_CONNECTION` / `$SSH_TTY` | Generic SSH session | | Linux without `$DISPLAY` / `$WAYLAND_DISPLAY` | Headless | When remote, pass `--no-browser` to the MCP CLI, which prints URL + ANSI QR for the user to scan with a phone. New flags: - `--remote` / `--local` — force either mode - `--force-mcp` — re-auth even if AgentKey is already configured Also adds an idempotency short-circuit: if any known MCP config already has an `agentkey` block with a valid-looking API key, skip the auth step entirely (`--force-mcp` to override). ### 3. Docs `README.md` + `docs/README_zh.md` updated to document the new flags and add a dedicated **"Installing over SSH / Docker / OpenClaw"** section. ## Companion PRs (server side) The MCP-server changes that this installer routes to ship in a chain of three PRs against `chainbase-labs/AgentKey-Server`: | PR | Status | What it adds | |---|---|---| | [#2](https://github.com/chainbase-labs/AgentKey-Server/pull/2) | merged | `--no-browser` / `--qr` / `--no-qr` flags + `qrcode-terminal` dep (v0.3.5 source bump) | | [#3](https://github.com/chainbase-labs/AgentKey-Server/pull/3) | merged | Bump to 0.3.6 — npm `0.3.5` had been published from a pre-merge commit and shipped stale `dist/` | | [#4](https://github.com/chainbase-labs/AgentKey-Server/pull/4) | open | Fix QR not rendering in `--no-browser` (CJS interop bug — `qrcode-terminal`'s `generate` lives on `.default` under NodeNext); bump to 0.3.7 | **This installer needs `@agentkey/mcp@0.3.7`** to be on npm for the QR flow to actually work. Sequence: 1. Merge #4 ✅ 2. Maintainer runs `cd mcp-server && npm publish` (no npm-publish CI workflow) ✅ 3. Merge this PR — `npx -y @agentkey/mcp` will then pull 0.3.7+ and the `--remote` path renders the QR This installer change is **forward-compatible**: it can land anytime — older `@agentkey/mcp` versions silently ignore the unknown `--no-browser` flag, so worst case a remote user gets the old browser-opens-on-the-wrong-host UX until the new mcp publishes. ## Test plan Verified end-to-end on macOS against a local build of `@agentkey/mcp@0.3.7` (server PR #4): - [x] Bash syntax check passes (`bash -n install.sh`) - [x] `install.sh --help` renders all 5 new flag rows - [x] `install.sh --list-agents` correctly prints detected agents on test host (10 agents incl. `openclaw`) - [x] `install.sh --remote --local` exits with code 1 (mutex) - [x] `install.sh --skip-skill` short-circuits with "AgentKey is already configured…" when configs have agentkey - [x] `install.sh --remote --skip-skill --force-mcp` end-to-end: prints `Detected remote install context — printing QR + URL instead of opening a browser here`, then `reason: $HOME/.openclaw exists (OpenClaw runtime)`, launches mcp CLI, renders 16-row ANSI QR, polls — no `open` process spawned - [x] All 4 mcp 0.3.7 flag combinations behave correctly (`--no-browser` / `--no-browser --no-qr` / `--qr` / no-flags back-compat) - [ ] `install.ps1` not lint-checked locally (no pwsh on test host); logic is a strict mirror of bash — needs Windows smoke before merge - [ ] Inside a real OpenClaw container — confirm `~/.openclaw` triggers as expected ## Why now Users running the installer via OpenClaw / Claude Code remote channels (on a phone) currently see a black-hole UX: the browser opens on the wrong machine and the install process appears to hang. The detection here removes the manual `--remote` flag for the common case. 🤖 Generated with [Claude Code](https://claude.com/claude-code)	2026-04-27 21:55:57 +08:00
lxcong	b3d806105b	chore: initial public release	2026-04-23 13:52:31 +08:00