plugins/meta
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): 新增技能盤點頁與共用部署驗證流程，並把技能驗證移到新行程

Browse Source 
技能盤點以前只回到對話裡，換一台機器就得重跑才知道裝了什麼。
現在新增技能盤點這個 wiki 頁類型，雜湊取「主機、工具名稱、登入帳號」三段。
每支 CLI 各有自己的 plugin 集合，也各有自己的 hook 接線，那是互相獨立的事實。
少了工具名稱那一段，同一台機器上五支 CLI 會算出同一個雜湊，五份盤點互相覆蓋，
讀的人還看不出被蓋掉。技能盤點新增寫入這兩頁的步驟，整步規定必須開 sub agent。
兩份樣板刻意分開：內容頁每次盤點覆寫整頁，目錄頁只更新自己那一列，
兩者的寫入語意剛好相反，合成一份遲早有人把別台機器的紀錄刪掉。

四支異動技能原本在部署完的同一個工作階段，就叫用剛做好的技能。
部署收尾自己立起重啟閘門，那支技能必被擋下，驗證做不完。
解法不是把它加進豁免清單。豁免擋得住閘門，擋不住「行程還載著舊版」這件事，
硬過關驗到的是舊版行為，等於假通過。所以把判路線、部署、驗證、失敗分流
抽成一份共用說明，驗證一律另開 CLI 行程執行，四支技能只留一行指標指過去。

新增腳本檢查工具，一次做完語法、執行權限與結束碼宣告三項檢查，
只被 source 的函式庫豁免後兩項，而且逐支記在錯誤輸出，不靜默略過。
新增部署路線判定工具，判定改動有沒有進存取庫的預設分支，
取代四支技能各抄一段、各自漂移的散文；判不出來就回報停下，不自己挑路線走。

同時把四支技能裡的中文段落抽到共用說明、指標改回英文，
修正六處相對路徑，把技能盤點的模糊描述改成查得出來的條件，
並讓 manifest 同步的每一個呼叫端逐碼分流。

七支技能改為併行執行：例行稽核從九步併成七步，技能盤點併成六步。
技能盤點不再重跑盤點腳本內部已經跑過的三支腳本，
而那三支原本兼作獨立交叉檢查，拿掉就少一層保護，
所以把少掉的是什麼、風險由誰擋住，明白寫進 Notes，不當作沒發生。
This commit is contained in:
jiantw83
2026-08-31 11:11:12 +08:00
parent 7dc5c32de3
commit 5aa4a3da57
12 changed files with 571 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/tooling-guide/SKILL.md
+50 -37
View File
@@ -1,6 +1,6 @@
---
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.
description: Inventory the current jsc plugins, skills, hook management, and usage paths as the baseline tooling guide, taking the skill, CLI, and hook-wiring facts from one inventory-tooling.sh run rather than re-running the scripts it already called. On request, publish that inventory through jsc-gitea:wiki to TOOLING_{HASH}, hashed from {hostname}/{tool}/{account}, and register it in TOOLING_CONTENTS. 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
@@ -11,65 +11,55 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
## Rules
- Keep the guide factual and current.
- Every factual claim in the guide carries the source path or the tool output line it came from.
- 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.
- Route every wiki read and write through `jsc-gitea:wiki`, and every `{HASH}` through `jsc-gitea/tools/hash-id`.
Done when these rules are all checked before the final report.
Done when each rule above has a recorded pass, or a recorded exception naming the claim and the reason, 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.
- Optional output target: chat response, wiki draft text, a named file that the user explicitly requests, or the wiki pages `TOOLING_{HASH}` and `TOOLING_CONTENTS`.
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.
Done when the scope and the output target are each written down as one of the values listed above. With no scope given, write down `all areas`. With no target given, write down `chat response`. Only the `wiki page` target runs step 7.
## 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`.
1. Confirm the working roots. Run `tools/plugins-root.sh` — it prints the workspace root that holds the domain checkouts, and it is the same derivation every other tool here uses. Exit 1 means the root could not be derived: read stderr, set `JSC_PLUGINS_ROOT` to the directory that holds the domain repos, and rerun. Under a plugin install the tools sit in the CLI's plugin cache, so the built-in guess lands in that cache instead of the workspace. The meta root is `{root}/meta`, or `{root}/jsc-meta` when that is the checkout name; the sibling directories under `{root}` are the domain checkouts. Completion condition: the script exits 0, and the meta root it names 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.
2. Sync the domain inventory with `tools/sync-domains.sh`. This script owns marketplace discovery and local repo synchronization.
- Exit 0: continue with the printed `domain<TAB>path` 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.
- Exit 1: report which cause stderr names — the root could not be derived, `gitea.sh` was not found, or the canonical marketplace was unreadable — then stop. For the root case, fix it the same way as step 1 and rerun.
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.
3. Collect the baseline inventory and the management-flow facts. The two halves are independent — one reads tool output, the other reads files — so run them **at the same time**.
**Baseline inventory.** Build it with `tools/inventory-tooling.sh` and use its Markdown output as the base document.
- Exit 0: continue with the generated guide.
- Exit 1: report which cause stderr names — the root could not be derived, the root does not exist, or the marketplace or `list-skills.sh` is missing — then stop.
- 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`.
**This one run already covers the skill catalog, the CLI detection and the hook wiring status.** Internally it runs `meta/tools/list-skills.sh`, `cli/tools/detect-clis.sh` and `hooks/tools/wire-cli.sh status {cli}` and writes each result into its own section, so read those sections instead of calling the three scripts again:
- `Supported skills` — one row per skill, from `list-skills.sh`. An empty table means no skill was scanned; return to step 2.
- `Supported CLIs` — one row per detected CLI with its path and version, from `detect-clis.sh`. The single placeholder row means no CLI is installed here, or `detect-clis.sh` is missing; mark CLI-specific checks as not available on this machine.
- `Hook wiring status` — one row per detected CLI with the `wire-cli.sh status` exit code and verdict, `CLI 代號不符合 wire-cli.sh 用法` for exit 2 and `未知狀態，結束碼 {rc}` for anything outside 0, 1, 3 and 5. The single placeholder row means no CLI was detected or `wire-cli.sh` is missing; state the hook verdict as unknown and say why.
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 `domain<TAB>name<TAB>description` rows.
- Any other exit: report the command, exit code, and stderr, then stop.
Re-running those three scripts on top of this buys nothing and can disagree with the base document — the second run sees a different machine state, and the guide then carries two answers for one fact. What that costs is written down under `Notes`.
Completion condition: every skill row used by the guide comes from the script output.
**Management-flow facts.** Collect them from the current docs and skills. Read only README files, `SKILL.md` files, and tool help or headers from `tools/` under the domain repo paths that step 2 printed — never a hardcoded absolute path, because the workspace root differs per machine and per install form. Do not infer support from missing or stale files.
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 `name<TAB>path<TAB>version` 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 generated guide contains `Source freshness`, `Supported plugins`, `Supported skills`, `Supported CLIs`, `Hook wiring status`, `Hook management`, `Plugin and skill management`, `Operational checks` and `Use this when`; the skill, CLI and hook facts used by the guide are quoted from those sections; and each management flow in the guide points to one source file or one tool output.
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:
4. 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
@@ -80,16 +70,37 @@ Done when the scope and output target are known. If the user gives no scope, use
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`.
5. Verify the draft in the main agent.
- Check that each plugin comes from the step 2 `sync-domains.sh` rows.
- Check that each skill comes from the step 3 `Supported skills` section.
- Check that each CLI fact comes from the step 3 `Supported CLIs` section, and each hook-wiring fact from the step 3 `Hook wiring status` section.
- 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.
6. 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. If the target is the wiki page, step 7 performs the delivery — keep the chat summary short here and let step 7 report the page names and URLs. Completion condition: the guide is delivered and the final report names the target, source freshness, stale inputs if any, and any unknown hook verdicts.
7. Publish the inventory to the wiki. Run this step only when the recorded output target is the wiki page; for any other target, record `wiki publish skipped — target is {target}` and go to the final report. **This whole step MUST run as a sub agent.** Every wiki read and write goes through `jsc-gitea:wiki`; never assemble a Gitea API call here.
7.1 **Build one page name per detected CLI.** Take the CLI code names from the step 3 `Supported CLIs` section — that section already carries the first column of `jsc-cli/tools/detect-clis.sh`, one of `claude`, `codex`, `copilot`, `antigravity`, `kiro`. Pair each code name with this machine's host name and the current login account, then hand `{hostname}/{tool}/{account}` to `jsc-gitea/tools/hash-id`. The hash rules live in `../../references/guidelines.md` and are not restated here; compute nothing by hand. One page per host, CLI, and account: every CLI carries its own installed plugin set and its own hook wiring, and the tool segment is what keeps five CLIs off one page. A missing host name, tool name, or account stops the step — name the missing segment and substitute no default value. `hash-id` exit 1 means this machine has neither `sha1sum` nor `shasum`: stop and report that one of them has to be installed. Completion condition: every detected CLI has one `TOOLING_{HASH}` name built from three non-empty segments, all of them produced by `hash-id`.
7.2 **Resolve the wiki repo** for type `TOOLING` through `jsc-gitea:wiki`, which reads `JSC_WIKI_REPO_TOOLING` first and `JSC_WIKI_REPO` second. Exit 3 — neither variable is set: ask for that type's `{owner}/{repo}` per the `jsc-ask:ask` rules. Exit 2 — the installed `jsc-gitea` does not accept the `TOOLING` type yet: stop and report that the type has to be registered there first. Completion condition: exactly one `{owner}/{repo}` is recorded, and every write in this step targets it.
7.3 **Write the content pages first.** Render `templates/tooling-page.md` for each `TOOLING_{HASH}` from the step 3 inventory, keeping only that page's own CLI row in the `Supported CLIs` and `Hook wiring status` tables. Each run overwrites the whole page: it records what this machine looks like right now, so keeping earlier runs buys nothing. Content pages go before the contents page for the same reason as every other jsc skill — a contents row must never point at a page whose write failed. Completion condition: every `TOOLING_{HASH}` write returned exit 0, or its failure went to step 7.5.
7.4 **Register the pages in `TOOLING_CONTENTS` second.** Read that page first, then route the read exit code:
- 0 — the page is there. Find the row whose host, tool, and account all match this run, refresh that one row per `templates/tooling-contents.md`, leave every other row exactly as it was, and write the whole page back.
- 4 — the page does not exist yet. **This is the only code that allows creating it.** Build it from the template with this run's rows.
- 7 or 8 — the key was rejected, or the API failed, so the old content is unknown. Stop. Create nothing and overwrite nothing: a page built on top of unknown content deletes rows that nobody can get back. Report the exit code and the page name.
Completion condition: `TOOLING_CONTENTS` holds one row per page written in step 7.3, every row belonging to another machine or CLI is unchanged, or the step stopped with the read exit code and the page name reported.
7.5 **Route a failed write.** Retry the failed `jsc-gitea:wiki` write once. When it fails again, stop the publish and report the page name together with the content that never reached the wiki, so the user can place it by hand. Report a page as written only after its write returned exit 0. Completion condition: every page named in this step is either confirmed written with its page name, or listed as unwritten with its exit code and its full content.
## Notes
- **Removed protection, on purpose.** The flow used to carry three more steps that re-ran `list-skills.sh`, `detect-clis.sh` and `wire-cli.sh status {cli}` after `inventory-tooling.sh` had already called all three. That second pass doubled as an independent cross-check: it read the same three facts straight from the source scripts, so a wrong skill row, a missing CLI, or a stale hook verdict produced by `inventory-tooling.sh` surfaced as a disagreement between the two sets. That cross-check is gone. The guide now takes the skill catalog, the CLI list and the hook wiring status from one `inventory-tooling.sh` run, with no second raw output to compare against, so a bug in that script's own scanning, parsing, or section writing reaches the guide unnoticed and reads as fact. Two things bound the risk: step 5 still rejects any claim with no source section behind it, and `Hook wiring status` carries the per-CLI exit code, so a nonsense verdict stays visible. When a decision rests on the guide's skill, CLI, or hook facts, get the second opinion elsewhere — run the three scripts by hand and compare, or run `jsc-cli:doctor` for an independent wiring verdict.
## Output Contract
@@ -99,9 +110,11 @@ The guide must include these fields in this order:
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.
5. `Hook management`: wiring, smoke, error scan, repair owner, and coverage limits, with the per-CLI wiring verdicts from `Hook wiring status`.
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.
For the wiki-page target, the same fields go to `TOOLING_{HASH}` in the section order of `templates/tooling-page.md`, and the row registered in `TOOLING_CONTENTS` follows `templates/tooling-contents.md`. Both templates own their own field lists; do not restate them here.