From 3c63989f80fbf9c95d656d1aebeb03885e93f01c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 16:53:17 +0000 Subject: [PATCH] =?UTF-8?q?fix(skill-check):=20=E8=A3=9C=E5=BC=B7=E5=B7=A5?= =?UTF-8?q?=E5=85=B7=E5=8C=96=E8=88=87=E7=92=B0=E5=A2=83=E5=84=AA=E5=85=88?= =?UTF-8?q?=E5=AF=A9=E6=A0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- references/guidelines.md | 41 ++++++++++++++++++++------------- skills/skill-delete/SKILL.md | 2 +- skills/skillset-update/SKILL.md | 2 +- 4 files changed, 28 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 201aa0d..182f2da 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 ### `skillset-update` -批次更新——把一份變更需求套用到整個技能組的多個技能／domain，逐 repo 開 PR；單一技能改用 skill-update。 +批次更新——把一份變更需求套用到整個技能組的多個技能／domain，先檢查工具化、sub agent 與環境變數優先規則，再逐 repo 開 PR；單一技能改用 skill-update。 ### `skill-check` diff --git a/references/guidelines.md b/references/guidelines.md index 9b9b8ae..0bff4f5 100644 --- a/references/guidelines.md +++ b/references/guidelines.md @@ -59,27 +59,35 @@ | --- | --- | --- | | `GITEA_HOST` | Gitea 站台（例：`https://gitea.jsc.idv.tw`） | 詢問使用者 | | `GITEA_TOKEN` | Gitea API token | 改用 tea 登入金鑰（`tea login list`）；tea 也沒有才詢問使用者 | -| `JSC_WIKI_REPO_{TYPE}` | 各類型 wiki 頁所在的 `{owner}/{repo}`；TYPE = `QUESTION` / `PLAN` / `ANALYZE` / `MAINTAIN` / `REPO` / `LOG` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_QUESTION` | `QUESTION_CONTENTS`、`QUESTION_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_PLAN` | `PLAN_CONTENTS`、`PLAN_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_ANALYZE` | `ANALYZE_CONTENTS`、`ANALYZE_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_MAINTAIN` | `MAINTAIN_CONTENTS`、`MAINTAIN_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_REPO` | `REPO_CONTENTS`、`REPO_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_LOG` | `LOG_CONTENTS`、`LOG_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | +| `JSC_WIKI_REPO_ERROR` | `ERROR_CONTENTS`、`ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` | | `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | 詢問使用者 | | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` | +頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時，才退回 `JSC_WIKI_REPO`。不得跨類型代用。 + ## Wiki 頁命名總表 -| 頁面 | 用途 | 擁有者 | -| --- | --- | --- | -| `QUESTION_CONTENTS` | 問詢目錄（存取庫名稱 → 問詢紀錄） | jsc-ask | -| `QUESTION_{HASH}` | 單一存取庫的問詢紀錄 | jsc-ask | -| `PLAN_CONTENTS` | 計畫目錄 | jsc-sdlc | -| `PLAN_{yyyyMMdd}_{HHmmss}_{HASH}` | 計畫頁 | jsc-sdlc | -| `ANALYZE_CONTENTS` | 分析目錄 | jsc-sdlc | -| `ANALYZE_{yyyyMMdd}_{HHmmss}_{HASH}` | 分析頁 | jsc-sdlc | -| `MAINTAIN_CONTENTS` | 維護目錄 | jsc-sdlc | -| `REPO_CONTENTS` | 盤點目錄 | jsc-sdlc | -| `REPO_{HASH}` | 存取庫盤點頁（功能與端點 + commit sha） | jsc-sdlc | -| `LOG_CONTENTS` | 日誌目錄 | jsc-log | -| `LOG_{yyyyMM}_W{週數}` | 工作日誌（週數基於週五日期計算） | jsc-log | +所有 wiki 頁面一律採雙層命名： -`{HASH}` 一律為 `{owner}/{repo}`（必要時加上主題字串）的 SHA-1 前 8 碼、大寫。 +| 類型 | 目錄頁 | 內容頁 | 用途 | 擁有者 | +| --- | --- | --- | --- | --- | +| `QUESTION` | `QUESTION_CONTENTS` | `QUESTION_{HASH}` | 問詢目錄、單一存取庫的問詢紀錄 | jsc-ask | +| `PLAN` | `PLAN_CONTENTS` | `PLAN_{HASH}` | 計畫目錄、計畫頁 | jsc-sdlc | +| `ANALYZE` | `ANALYZE_CONTENTS` | `ANALYZE_{HASH}` | 分析目錄、分析頁 | jsc-sdlc | +| `MAINTAIN` | `MAINTAIN_CONTENTS` | `MAINTAIN_{HASH}` | 維護目錄、維護頁 | jsc-sdlc | +| `REPO` | `REPO_CONTENTS` | `REPO_{HASH}` | 盤點目錄、存取庫盤點頁 | jsc-sdlc | +| `LOG` | `LOG_CONTENTS` | `LOG_{HASH}` | 日誌目錄、工作日誌頁 | jsc-log | +| `ERROR` | `ERROR_CONTENTS` | `ERROR_{HASH}` | 異常目錄、異常頁 | jsc-hooks | + +`{HASH}` 一律為 `{owner}/{repo}`（必要時加上主題字串）的 SHA-1 前 8 碼，大寫。 +若第一碼是 `0-9`、`A`、`B`、`C`，就改成 `H` 加上原 SHA-1 前 7 碼，總長仍維持 8 碼。 +同一規則套用到所有目錄頁與內容頁。 ## 審核檢查清單 @@ -87,9 +95,10 @@ - [ ] 名稱符合命名規則，且與既有技能目標不重複 - [ ] description 為英文、≤ 5 句或 5 步驟、含觸發時機 -- [ ] 可 hook 的規則已下放 jsc-hooks；可工具化的流程已下放 tools/ +- [ ] 可 hook 的規則已下放 jsc-hooks；可工具化的流程已下放 tools/；SKILL.md 沒有保留可由標準輸入輸出執行的細節流程 - [ ] 細節流程已標示 MUST run as a sub agent - [ ] gitea 操作透過 gitea.sh 或 tea +- [ ] wiki repo 與 Gitea 認證先讀目前 shell 繼承的環境變數；只有缺值或無法解析時才詢問；頁面類型不得跨用其他 `JSC_WIKI_REPO_{TYPE}` - [ ] 問詢透過 jsc-ask 決策樹規則 - [ ] SKILL.md 整份為英文（要原樣輸出的繁中字面除外）；README、AGENTS、templates、references 為 STE100 繁中；UTF-8 無亂碼 - [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version diff --git a/skills/skill-delete/SKILL.md b/skills/skill-delete/SKILL.md index bdd9b09..ab6a344 100644 --- a/skills/skill-delete/SKILL.md +++ b/skills/skill-delete/SKILL.md @@ -17,7 +17,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references - References in other SKILL.md files, the domain README's 「Skills 目錄」 section, the two marketplace.json files in `plugins/jsc` plus their synced copies in every domain repo, `tools/`, and the `jsc-hooks` wiring 5. For each affected file: 1. Decide whether the file needs a fix to keep its current behavior after the deletion. If no fix is needed, **skip the rest of this loop**. - 2. Ask for fix details via the `jsc-ask:ask` decision tree (call a replacement skill? inline the flow? drop the feature too?). Every option states its impact scope. + 2. Ask for fix details via the `jsc-ask:ask` decision tree (call a replacement skill? move a deterministic input/output flow to `tools/`? run the detailed flow as a sub agent? drop the feature too?). If the fix touches wiki or Gitea access, confirm it reads inherited environment variables before asking the user. Every option states its impact scope. 3. After fixing, check the guidelines.md audit checklist. On failure, return to step 5.2. 6. Delete the skill directory `skills/{name}/`, then sync the domain README and bump the version in all three manifests. 7. Deep-delete verification — this step MUST run as a sub agent: after deleting via each CLI's native plugin commands, physically inspect every installed CLI's on-disk skill and hook storage. Detect CLIs via `jsc-cli/tools/detect-clis.sh`; check Claude's `~/.claude/plugins/cache/` and hook entries in settings, plus the equivalent locations for codex / copilot / antigravity / kiro. Confirm no file or hook wiring for the deleted skill remains. Completion condition: every location checked and clean; remove any leftover by hand and recheck. diff --git a/skills/skillset-update/SKILL.md b/skills/skillset-update/SKILL.md index d29999c..8113a9f 100644 --- a/skills/skillset-update/SKILL.md +++ b/skills/skillset-update/SKILL.md @@ -9,7 +9,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references ## Flow -1. Ask for the change details via the `jsc-ask:ask` decision tree: what rule or behavior changes, which skills and which domains are affected. Every option states its impact scope (example: changing a shared flow step touches every skill that calls it). Completion condition: the affected-skill list is agreed with the user. +1. Ask for the change details via the `jsc-ask:ask` decision tree: what rule or behavior changes, which skills and which domains are affected. Include three required checks before the affected-skill list is final: whether any deterministic input/output flow must move to `tools/`, whether any detailed flow must run as a sub agent, and whether any wiki or Gitea flow must read inherited environment variables before asking the user. Every option states its impact scope (example: changing a shared flow step touches every skill that calls it). Completion condition: the affected-skill list and the three checks are agreed with the user. 2. Query the Gitea canonical marketplace for the authoritative domain list: run `jsc-gitea/tools/gitea.sh api GET /repos/plugins/jsc/raw/.claude-plugin/marketplace.json`. Clone any domain repo missing from the working directory (`gitea.sh clone-url plugins/{domain}`) and pull the rest. Completion condition: every domain repo exists locally and is current. 3. Apply the change to every affected skill — this step MUST run as a sub agent, one sub agent per affected domain repo: modify SKILL.md and related files and tools, sync that domain README's 「Skills 目錄」 section, and bump the version in all three manifests. Completion condition: every affected domain repo carries the change, the README sync, and the manifest bump. 4. Check every item of the guidelines.md audit checklist for each touched skill. On any failure, **return to step 1**: ask again and fix, until all items pass.