From f48f951c50bf4df82caaa6a0f0c7bfd2c5c6cad7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=9B=A2=E5=AD=90?= Date: Sat, 9 May 2026 03:38:59 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20add=20cfg=20skill=20subcommand=20?= =?UTF-8?q?=E2=80=94=20built-in=20usage=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cfg skill outputs comprehensive documentation including architecture, all commands, API endpoints, and tips. Keeps docs in sync with code. --- packages/cfg/package.json | 2 +- packages/cfg/src/cli.ts | 4 ++ packages/cfg/src/commands.ts | 91 ++++++++++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+), 1 deletion(-) diff --git a/packages/cfg/package.json b/packages/cfg/package.json index f12bc75..5d64edf 100644 --- a/packages/cfg/package.json +++ b/packages/cfg/package.json @@ -1,6 +1,6 @@ { "name": "@shazhou/cfg", - "version": "1.1.0", + "version": "1.2.0", "type": "module", "bin": { "cfg": "./dist/cli.js" diff --git a/packages/cfg/src/cli.ts b/packages/cfg/src/cli.ts index 7e13c74..e6db535 100644 --- a/packages/cfg/src/cli.ts +++ b/packages/cfg/src/cli.ts @@ -16,6 +16,7 @@ import { cmdProfile, cmdProfileSet, cmdProfileUnset, + showSkill, showHelp, } from "./commands.js"; @@ -103,6 +104,9 @@ switch (cmd) { case undefined: showHelp(); break; + case "skill": + showSkill(); + break; default: console.error(`Unknown command: ${cmd}`); showHelp(); diff --git a/packages/cfg/src/commands.ts b/packages/cfg/src/commands.ts index 972e341..ccd4187 100644 --- a/packages/cfg/src/commands.ts +++ b/packages/cfg/src/commands.ts @@ -399,6 +399,97 @@ export async function cmdProfileUnset(args: string[]): Promise { console.log(`✓ ${key} deleted from public profile`); } +export function showSkill(): void { + console.log(`# cfg — Config Service CLI Skill + +## Overview +cfg is the CLI for config.shazhou.work, a centralized config/secret management service +for the 沙洲家族 agent network. Built on Cloudflare Workers + KV. + +## Architecture +- **Scopes**: shared (admin-only write, all read), personal (own agent read/write) +- **Resolution**: personal overrides shared (personal > shared fallback) +- **Caching**: local cache with auto-sync (fresh for 1 day, retry after 2h on failure) +- **Auth**: Bearer token per agent, stored via \`cfg token \` + +## Shell Setup +Add to .bashrc / .zshrc / .profile: + eval $(cfg env) + +This exports all config keys (where env=true) as environment variables. + +## Common Workflows + +### Read/Write Config + cfg get Read from cache (auto-syncs if stale) + cfg get --remote Read directly from server + cfg set Write to personal scope + cfg set --shared Write to shared scope (admin only) + cfg set --secret Mark as secret (masked in UI) + cfg set --no-env Won't be exported by cfg env + cfg unset Delete from personal scope + cfg unset --shared Delete from shared scope (admin only) + +### List & Sync + cfg list List all keys with scope/flags (from cache) + cfg sync Force sync from server + cfg env Output export statements for shell + +### Flags + cfg flags Show current flags (env, secret) + cfg flags --no-env Set no-env flag + cfg flags --secret Set secret flag + cfg flags --no-secret Remove secret flag + +### Public Profile +Public profile is visible to all authenticated agents. Each agent can only write their own. + cfg profile Show your own public profile + cfg profile Show another agent's public profile + cfg profile set Set a key in your public profile + cfg profile unset Delete a key from your public profile + cfg profiles List all agents with public profiles + +Example profile keys: contact, role, telegram_id, github, description + +### Admin (requires admin role) + cfg admin agents List all registered agents + cfg admin add [--admin] Create token for new agent + cfg admin remove Revoke all tokens for an agent + cfg admin refresh Revoke + recreate token + cfg admin inspect View an agent's resolved config + +### Token Management + cfg token Save auth token locally + +## Environment Variables + CFG_TOKEN Auth token (overrides saved token) + CFG_ENDPOINT API endpoint (default: https://config.shazhou.work) + +## API Endpoints (for direct HTTP access) + GET /config List all resolved keys + GET /config/:key Read key (personal > shared fallback) + PUT /config/:key?scope=... Write key (scope: personal|shared) + PATCH /config/:key?scope=... Update flags only + DELETE /config/:key?scope=... Delete key + POST /config/sync Full sync (all resolved key-values) + GET /profiles List agents with public profiles + GET /profile/:id Get agent's public profile + GET /profile/:id/:key Get single public profile key + PUT /profile/:id/:key Set own public profile key + DELETE /profile/:id/:key Delete own public profile key + GET /admin/agents List all agents (admin) + POST /admin/token Create agent token (admin) + DELETE /admin/token/:id Revoke agent tokens (admin) + GET /admin/agent/:id Inspect agent config (admin) + GET /health Health check (no auth) + +## Tips +- Use --secret for sensitive values (API keys, tokens) — they're masked in the web UI +- Use --no-env for config that shouldn't pollute the shell environment +- Profile is great for agent contact info, roles, and public metadata +- Cache is at ~/.config/cfg/cache.json, token at ~/.config/cfg/config.json`); +} + export function showHelp(): void { console.log(`cfg — config.shazhou.work CLI