diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5b44a56..18826cd 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.1.7", + "version": "0.1.8", "description": "技能組自我管理:新建、更新、刪除技能與技能準則", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 622260b..7cd28cf 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.1.7", + "version": "0.1.8", "description": "技能組自我管理:新建、更新、刪除技能與技能準則", "skills": "./skills", "jsc": { diff --git a/README.md b/README.md index bc5845e..4d08b0c 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,10 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安 同步上游 speak-human-tw 的語言規則:比對 `references/ste100.md` 釘住的上游版本,有新版就萃取適用的變更、逐項決策樹確認、更新 lint 樣式、全庫重掃、bump manifest,最後開 PR。適合列為本 repo 的維護方式。 +### `tooling-guide` + +盤點目前支援的 plugins、skills、hooks 管理與使用路徑,產出技能組基礎指引。適合建立技能組地圖、支援清單、hook 管理總覽與新人交接資料;安裝、更新、刪除、稽核與修復改用對應技能。 + ## 參考與工具 @@ -59,6 +63,7 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安 | `tools/ste100-lint.sh` | 語言規則的機檢工具:中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線;命中 exit 1 | | `tools/sync-domains.sh` | 依 Gitea 正本 marketplace 把所有 domain 存取庫 clone 或 pull 到本機,印出 `domainpath`;**只有 exit 0 代表全部到位且最新**,exit 3 代表有存取庫跳過或 pull 失敗(stderr 列路徑),exit 2 代表有 domain clone 失敗 | | `tools/list-skills.sh` | 列出正本 marketplace 上各 domain 存取庫的技能,印出 `domainnamedescription`;不在正本清單上的存取庫不列 | +| `tools/inventory-tooling.sh` | 盤點目前支援的 plugins、skills、tools、hooks,輸出技能組基礎指引 Markdown | | `tools/sync-marketplace.sh` | 寫入或更新兩份正本 marketplace 的 plugin 條目,再複製到每個 domain 存取庫(保證位元組一致)。**需要 python3**(json 模組改 JSON),缺 python3 不寫檔並 exit 1;存取庫不在本機 exit 3 | | `tools/sync-skill-manifest.sh` | 同步 domain README 的「Skills 目錄」,並 bump 三份 manifest 的 version;`minor` 與 `patch` 不得超過 `9`,`major` 可以超過 `9` | | `tools/find-skill-refs.sh` | 盤點一個技能在正本 marketplace 各 domain 存取庫裡的引用檔案(不掃非技能組存取庫與點開頭目錄);技能名稱為純子字串比對,命中要逐檔確認;零命中 exit 1,掃描失敗 exit 3 | diff --git a/plugin.json b/plugin.json index b66d34f..c12b955 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-meta", - "version": "0.1.7", + "version": "0.1.8", "description": "技能組自我管理:新建、更新、刪除技能與技能準則", "skills": "./skills/", "jsc": { diff --git a/skills/tooling-guide/SKILL.md b/skills/tooling-guide/SKILL.md new file mode 100644 index 0000000..c280966 --- /dev/null +++ b/skills/tooling-guide/SKILL.md @@ -0,0 +1,107 @@ +--- +name: tooling-guide +description: Inventory the current jsc plugins, skills, hook management, and usage paths as the baseline tooling guide. Use when the user asks for a skill-set guide, tooling map, supported plugin list, supported skill list, hook management overview, or onboarding reference. Do not use for installing, updating, deleting, auditing, or repairing the skill set; use jsc-cli:deploy, jsc-meta:skill-check, jsc-meta:skill-update, jsc-meta:skill-delete, or jsc-hooks:hooks-install instead. +--- + +# tooling-guide - build the baseline tooling guide + +Goal: produce a current guide for the jsc skill set from the local repos and the supported tooling scripts. + +Single source of guidelines: [`../../references/guidelines.md`](../../references/guidelines.md). + +## Rules + +- Keep the guide factual and current. +- Prefer script output over copied lists. +- Use `tools/inventory-tooling.sh` for the baseline inventory. +- Keep command syntax in the guide only when it comes from README files or tool output. +- Do not modify README files, manifests, marketplace files, hooks, tools, or other skills. +- Put generated guide text in the response or in the user-requested target only. +- Run detail synthesis as a sub agent when the guide needs explanations, grouping, or onboarding prose. + +Done when these rules are all checked before the final report. + +## Inputs + +- Optional user scope: plugin inventory, skill inventory, hook management, CLI usage, or all areas. +- Optional output target: chat response, wiki draft text, or a named file that the user explicitly requests. + +Done when the scope and output target are known. If the user gives no scope, use all areas. If the user gives no target, return the guide in chat. + +## Flow + +1. Confirm the working roots. Use `/root/plugins/meta` as the meta root. Use sibling repos under `/root/plugins` for current domain checkouts. Completion condition: the meta root exists and contains `references/guidelines.md`. + +2. Sync the domain inventory with `tools/sync-domains.sh` from the meta root. This script owns marketplace discovery and local repo synchronization. + - Exit 0: continue with the printed `domainpath` rows. + - Exit 3: keep the printed rows, report every skipped or dirty repo from stderr as stale input, and continue only after the user accepts a guide with stale rows. + - Exit 2: report the clone failure and stop. + - Exit 1: report the unreadable canonical marketplace and stop. + + Completion condition: each plugin row used by the guide has a domain and a local path, or the stale-input decision is recorded. + +3. Build the baseline guide with `tools/inventory-tooling.sh` from the meta root. Use its Markdown output as the base document. + - Exit 0: continue with the generated guide. + - Any other exit: report the command, exit code, and stderr, then stop. + + Completion condition: the generated guide contains `Source freshness`, `Supported plugins`, `Supported skills`, `Supported CLIs`, `Hook management`, `Plugin and skill management`, `Operational checks`, and `Use this when`. + +4. Build the skill catalog with `tools/list-skills.sh` from the meta root. Use its TSV rows as the skill list when the baseline guide needs verification or a smaller scope. + - Exit 0: continue with the printed `domainnamedescription` rows. + - Any other exit: report the command, exit code, and stderr, then stop. + + Completion condition: every skill row used by the guide comes from the script output. + +5. Detect supported CLIs with `/root/plugins/cli/tools/detect-clis.sh`. Use its TSV rows as the installed CLI list when the baseline guide needs verification or a smaller scope. + - Exit 0 with rows: continue with the printed `namepathversion` rows. + - Exit 0 with no rows: continue and mark CLI-specific checks as not available on this machine. + - Any other exit: report the command, exit code, and stderr, then stop. + + Completion condition: the guide states the detected CLI set, or states that no installed CLI was detected. + +6. Collect hook wiring facts for each detected CLI with `/root/plugins/hooks/tools/wire-cli.sh status {cli}`. Use `status` only when the baseline guide needs verification or a smaller scope. + - Exit 0, 1, or 5: keep the status and all `item` lines. + - Exit 3: mark that CLI as skipped. + - Exit 2: fix the CLI code from the detect output and rerun. + - Any other exit: report the command, exit code, and stderr, then mark the hook status as unknown. + + Completion condition: every detected CLI has one hook-wiring verdict, or the guide states why the verdict is unknown. + +7. Collect management-flow facts from the current docs and skills. Read only README files, `SKILL.md` files, and tool help or headers from `tools/` under the synced domain repos. Do not infer support from missing or stale files. Completion condition: each management flow in the guide points to one source file or one tool output. + +8. Synthesize the guide. This step MUST run as a sub agent when the output needs explanations, grouping, onboarding prose, or cross-domain comparison. Give the sub agent only the collected inventories, the relevant README and SKILL paths, and this required section list: + - Supported plugins + - Supported skills + - Supported CLIs and usage forms + - Hook management + - Plugin and skill management + - Health checks and repair paths + - Known coverage limits + + Completion condition: the sub agent returns a guide draft with every required section and with source paths for each factual claim. + +9. Verify the draft in the main agent. + - Check that each plugin comes from `sync-domains.sh`. + - Check that each skill comes from `list-skills.sh`. + - Check that each hook-wiring fact comes from `wire-cli.sh status`. + - Check that install, update, delete, audit, repair, and health-check actions point to the owning skill or tool. + - Check that the draft does not copy long implementation details from README files or scripts. + + Completion condition: every factual claim has a source path or tool output, and no required section is empty. + +10. Deliver the guide in the requested target. If the target is chat, keep it concise and include the source paths used. If the target is a file, write only that user-requested file and do not update manifests or README files. Completion condition: the guide is delivered and the final report names the target, source freshness, stale inputs if any, and any unknown hook verdicts. + +## Output Contract + +The guide must include these fields in this order: + +1. `Source freshness`: synced, stale accepted, or blocked. +2. `Supported plugins`: one row per domain. +3. `Supported skills`: one row per skill. +4. `Supported CLIs`: one row per detected CLI, or one sentence for none detected. +5. `Hook management`: wiring, smoke, error scan, repair owner, and coverage limits. +6. `Plugin and skill management`: install, update, delete, audit, and creation owners. +7. `Operational checks`: doctor, setup, version guard, restart gate, language guard, and comment-scope guard. +8. `Use this when`: short usage guidance for maintainers. + +Done when the output has all fields in order and each non-empty table has at least one source reference. diff --git a/tools/inventory-tooling.sh b/tools/inventory-tooling.sh new file mode 100755 index 0000000..631c1f5 --- /dev/null +++ b/tools/inventory-tooling.sh @@ -0,0 +1,273 @@ +#!/usr/bin/env sh +# inventory-tooling.sh — 盤點 jsc plugins、skills、tools、hooks,輸出技能組基礎指引。 +# +# 用法: inventory-tooling.sh [root] +# +# root: 預設取本腳本位置的上兩層(meta/tools -> meta -> 根)。 +# 也可用參數或 JSC_PLUGINS_ROOT 覆寫。 +# +# 輸出: Markdown。內容包含 domain、manifest、技能、工具、hooks 與管理入口。 +# 結束碼: 0=成功 1=根目錄、marketplace 或必要工具缺失 +set -eu + +HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +ROOT=${1:-${JSC_PLUGINS_ROOT:-$(CDPATH= cd -- "$HERE/../.." && pwd)}} +ROOT=${ROOT%/} + +[ -d "$ROOT" ] || { echo "找不到 plugins 根目錄:$ROOT" >&2; exit 1; } + +MARKETPLACE="" +for cand in "$ROOT/meta/.claude-plugin/marketplace.json" "$ROOT"/*/.claude-plugin/marketplace.json; do + [ -f "$cand" ] && { MARKETPLACE=$cand; break; } +done +[ -n "$MARKETPLACE" ] || { echo "找不到 marketplace.json,無法判定 domain 清單" >&2; exit 1; } + +LIST_SKILLS="$ROOT/meta/tools/list-skills.sh" +[ -x "$LIST_SKILLS" ] || { echo "找不到可執行的 list-skills.sh:$LIST_SKILLS" >&2; exit 1; } + +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT + +domains_file="$tmp/domains.tsv" +skills_file="$tmp/skills.tsv" +clis_file="$tmp/clis.tsv" +hook_status_file="$tmp/hook-status.tsv" + +sed -n 's/.*"name"[[:space:]]*:[[:space:]]*"jsc-\([a-z0-9-]*\)".*/\1/p' "$MARKETPLACE" | + sort -u | + while read -r domain; do + [ -n "$domain" ] || continue + path="$ROOT/$domain" + [ -d "$path" ] || path="$ROOT/jsc-$domain" + if [ -d "$path" ]; then + version=$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' "$path/plugin.json" 2>/dev/null | head -1) + [ -n "$version" ] || version="未知" + printf '%s\t%s\t%s\n' "$domain" "$version" "$path" + else + printf '%s\t%s\t%s\n' "$domain" "缺本機存取庫" "-" + fi + done > "$domains_file" + +JSC_PLUGINS_ROOT="$ROOT" "$LIST_SKILLS" > "$skills_file" 2>/dev/null || : > "$skills_file" + +DETECT_CLIS="$ROOT/cli/tools/detect-clis.sh" +if [ -x "$DETECT_CLIS" ]; then + "$DETECT_CLIS" > "$clis_file" 2>/dev/null || : > "$clis_file" +else + : > "$clis_file" +fi + +WIRE_CLI="$ROOT/hooks/tools/wire-cli.sh" +: > "$hook_status_file" +if [ -x "$WIRE_CLI" ] && [ -s "$clis_file" ]; then + while IFS="$(printf '\t')" read -r cli path version; do + [ -n "$cli" ] || continue + out="$tmp/wire-$cli.out" + err="$tmp/wire-$cli.err" + if "$WIRE_CLI" status "$cli" > "$out" 2> "$err"; then + rc=0 + else + rc=$? + fi + verdict=$(sed -n '1{s/[|]/-/g;p;}' "$out") + [ -n "$verdict" ] || verdict=$(sed -n '1{s/[|]/-/g;p;}' "$err") + [ -n "$verdict" ] || verdict="無狀態輸出" + case "$rc" in + 0|1|3|5) ;; + 2) verdict="CLI 代號不符合 wire-cli.sh 用法" ;; + *) verdict="未知狀態,結束碼 $rc" ;; + esac + printf '%s\t%s\t%s\n' "$cli" "$rc" "$verdict" >> "$hook_status_file" + done < "$clis_file" +fi + +count_lines() { + file=$1 + [ -s "$file" ] || { echo 0; return; } + wc -l < "$file" | tr -d ' ' +} + +domains_count=$(count_lines "$domains_file") +skills_count=$(count_lines "$skills_file") +clis_count=$(count_lines "$clis_file") + +cat </dev/null) + [ -n "$first" ] || first="工具腳本" + printf '| `%s` | `%s` | %s |\n' "$domain" "$base" "$first" + done +done < "$domains_file" + +cat <<'EOF' + +Tool 使用方式: + +- 先讀工具檔頭的用法與結束碼。 +- 用真實參數驗證新增或修改的工具。 +- 結束碼沒有文件化時,先補工具說明,再讓技能呼叫它。 + +## Hook management + +| hook | 用途 | +| --- | --- | +EOF + +HOOK_DIR="$ROOT/hooks/hooks" +if [ -d "$HOOK_DIR" ]; then + for hook in "$HOOK_DIR"/*.sh; do + [ -f "$hook" ] || continue + base=$(basename "$hook") + first=$(sed -n '2{s/^# *//;p;}' "$hook" 2>/dev/null) + [ -n "$first" ] || first="hook 腳本" + printf '| `%s` | %s |\n' "$base" "$first" + done +else + echo '| - | 找不到 `hooks/hooks`。請先執行 `meta/tools/sync-domains.sh`。 |' +fi + +cat <<'EOF' + +Hook 使用方式: + +- Hook 只放在 `jsc-hooks` domain。 +- `jsc-hooks:hooks-install` 負責接線到各 CLI。 +- hook 腳本要能接受 stdin JSON 與環境變數。 +- 缺欄位時安靜降級並 `exit 0`。 +- 版本閘門與重啟閘門要保留解除自己的路徑。 + +## Hook wiring status + +| CLI | 結束碼 | 狀態 | +| --- | ---: | --- | +EOF + +if [ -s "$hook_status_file" ]; then + while IFS="$(printf '\t')" read -r cli rc status; do + [ -n "$cli" ] || continue + printf '| `%s` | %s | %s |\n' "$cli" "$rc" "$status" + done < "$hook_status_file" +else + echo '| - | - | 未偵測到 CLI,或找不到 `hooks/tools/wire-cli.sh`。 |' +fi + +cat <<'EOF' + +## Plugin and skill management + +- 新增技能:使用 `jsc-meta:skill-new`。 +- 更新單一技能:使用 `jsc-meta:skill-update`。 +- 批次更新技能組:使用 `jsc-meta:skillset-update`。 +- 刪除技能:使用 `jsc-meta:skill-delete`。 +- 安裝、更新、移除整組 plugin:使用 `jsc-cli:deploy`。 +- 例行稽核:使用 `jsc-meta:skill-check`。 +- 重新接線 hooks:使用 `jsc-hooks:hooks-install`。 + +## Operational checks + +- 體檢目前環境:使用 `jsc-cli:doctor`。 +- 修復體檢項目:使用 `jsc-cli:setup`。 +- 版本前置檢查:由 `jsc-hooks/hooks/version-guard.sh` 管理。 +- 部署後重啟閘門:由 `jsc-hooks/hooks/restart-gate.sh` 管理。 +- 語言提示與掃描:由 `jsc-hooks/hooks/ste100-guard.sh` 與 `jsc-hooks/hooks/lang-guard.sh` 管理。 +- 註解範圍檢查:由 `jsc-hooks/hooks/comment-scope.sh` 管理。 + +## Use this when + +- 先執行 `meta/tools/sync-domains.sh`,同步 marketplace 上的 domain。 +- 再執行 `meta/tools/list-skills.sh`,確認技能清單。 +- 執行本工具,產出基礎指引。 +- 若新增或修改技能,執行 `meta/tools/sync-skill-manifest.sh {domain-path}`。 +- 執行 `meta/tools/ste100-lint.sh {domain-path}`。 +- 依 `jsc-git:pr` 開立 Push Request。 +EOF