From 8467b89a0957bdfc9dfd560286d0337b0b7ef1fb Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 1 Sep 2026 12:10:40 +0800 Subject: [PATCH] =?UTF-8?q?feat(wiki):=20=E9=A0=81=E5=9E=8B=E5=88=A5?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=20MONITOR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What： - resolve_wiki_repo 的型別白名單與檔頭註解加上 MONITOR，check-wiki-rules.sh 的 TYPES 一併加入。 - README 的兩處型別列舉加上 MONITOR，環境變數表補一列 JSC_WIKI_REPO_MONITOR。 - wiki 技能的 allowed types 與行為清單的呼叫端補上這個型別與它的擁有者。 - 三份 manifest 的版本一起提升。 Why： - 技能助理要把巡檢結果寫進 wiki，落點就是監控頁。型別不在白名單裡，wiki-repo 會直接回「unknown wiki type」而拒絕解析，助理連寫都寫不出去。 - 型別串散在五個檔案，只改一處會讓解析通過但檢核工具漏掉，或反過來。所以一次改齊。 How： - MONITOR 放在型別串尾端，接在 TOOLING 之後。既有順序是依用途分群，不是字母序，所以不重排。 - 環境變數的規則完全沿用既有型別：先讀 JSC_WIKI_REPO_MONITOR，再退回 JSC_WIKI_REPO，不得跨型別代用。這一條由 resolve_wiki_repo 統一處理，新型別自動繼承，不必另寫分支。 - 雜湊來源的規則不寫在這個存放庫。README 已載明雜湊規則的唯一來源是技能準則的命名總表，這裡不複述。 - wiki 技能的 description 原本逐一列舉呼叫端，已經接近長度上限。這次改成括號標注頁型的濃縮寫法，加了一個呼叫端之後整行反而變短，句數維持在上限內。 Who： 技能助理落地帶出來的頁型別需求，四個存放庫同一批改。 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- README.md | 5 +++-- plugin.json | 2 +- references/behaviors.md | 2 +- skills/wiki/SKILL.md | 4 ++-- tools/check-wiki-rules.sh | 2 +- tools/gitea.sh | 4 ++-- 8 files changed, 12 insertions(+), 11 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index f373b22..09331b6 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-gitea", - "version": "0.2.0", + "version": "0.2.1", "description": "Gitea API 工具、Wiki 讀寫、議題轉換、HTML 匯出與存取庫批次同步", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 18b391e..9b1a728 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-gitea", - "version": "0.2.0", + "version": "0.2.1", "description": "Gitea API 工具、Wiki 讀寫、議題轉換、HTML 匯出與存取庫批次同步", "skills": "./skills", "jsc": { diff --git a/README.md b/README.md index 576f419..2123d68 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ gitea.sh repos # 列出 owner 的 repo 全名 gitea.sh default-branch / gitea.sh clone-url / gitea.sh hash-id # 產生 8 碼大寫 SHA-1；首碼 0-9/A/B/C 時改成 Hxxxxxxx -gitea.sh wiki-repo # 解析頁面類型的 wiki 位置（TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING） +gitea.sh wiki-repo # 解析頁面類型的 wiki 位置（TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING / MONITOR） gitea.sh wiki-list / gitea.sh wiki-get / # 不存在 exit 4 gitea.sh wiki-put / # 自動判斷新建或更新；會先要求確認 @@ -122,7 +122,7 @@ html-render.sh --markdown <檔案> --title <標題> --out <輸出檔> [--layout] ### `wiki` -Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字每節最多三句。 +Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING / MONITOR）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字每節最多三句。 ### `repo-sync` @@ -151,6 +151,7 @@ Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZ | `JSC_WIKI_REPO_{TYPE}` | 各類型 wiki 頁的 `{owner}/{repo}`；TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT | 退回 `JSC_WIKI_REPO`，不做跨類型代用 | | `JSC_WIKI_REPO_SKILLSET` | `SKILLSET_CONTENTS`、`SKILLSET_{HASH}`（技能組異動報告）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 | | `JSC_WIKI_REPO_TOOLING` | `TOOLING_CONTENTS`、`TOOLING_{HASH}`（技能盤點）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 | +| `JSC_WIKI_REPO_MONITOR` | `MONITOR_CONTENTS`、`MONITOR_{HASH}`（助理巡檢監控）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 | | `JSC_WIKI_REPO` | 共用預設的 wiki `{owner}/{repo}` | 詢問使用者 | | `JSC_HOME` | `pr-watch.sh` 狀態檔的根目錄 | 預設 `~/.jsc` | | `JSC_PR_WATCH_INTERVAL` | `pr-watch.sh` 的輪詢間隔秒數（正整數） | 預設 60 | diff --git a/plugin.json b/plugin.json index 433c8f4..4a5f7d6 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-gitea", - "version": "0.2.0", + "version": "0.2.1", "description": "Gitea API 工具、Wiki 讀寫、議題轉換、HTML 匯出與存取庫批次同步", "skills": "./skills/", "jsc": { diff --git a/references/behaviors.md b/references/behaviors.md index 96443c3..e61e703 100644 --- a/references/behaviors.md +++ b/references/behaviors.md @@ -36,7 +36,7 @@ | 項目 | 內容 | | --- | --- | -| 觸發時機 | 技能組裡任何一次 wiki 頁的讀或寫，都經過這一支。呼叫端有 jsc-ask、jsc-sdlc、jsc-log、jsc-hooks 的 ERROR 頁、jsc-cli 的 CHECK 頁、jsc-meta 的 SKILLSET 與 TOOLING 頁。存放庫裡的程式碼檔案不歸這一支管。 | +| 觸發時機 | 技能組裡任何一次 wiki 頁的讀或寫，都經過這一支。呼叫端有 jsc-ask、jsc-sdlc、jsc-log、jsc-hooks 的 ERROR 頁、jsc-cli 的 CHECK 頁、jsc-meta 的 SKILLSET 與 TOOLING 頁、jsc-assist 的 MONITOR 頁。存放庫裡的程式碼檔案不歸這一支管。 | | 關鍵步驟 | 確認 GITEA_HOST 有值、用 tools/gitea.sh wiki-repo {TYPE} 依頁名前綴解出 {owner}/{repo}、用 tools/hash-id 算頁名要用的 HASH、再依動作跑 wiki-list、wiki-get、wiki-put 或 wiki-url、每一次呼叫都照結束碼表分流。存放庫的解法是先讀 JSC_WIKI_REPO_{TYPE}、再讀 JSC_WIKI_REPO、兩個都沒有才問使用者，而且不借用別的頁型的存放庫。寫入前一定先 wiki-get 讀回舊內容，把新內容接上去再整頁寫回；只有結束碼 4 才准用範本建新頁。 | | 外部呼叫 | tools/gitea.sh 的 wiki-repo、wiki-list、wiki-get、wiki-put、wiki-url、tools/hash-id、tools/write-confirm.sh、jsc-ask:ask、Gitea 的 wiki API。 | | 完成條件 | 讀取動作拿到頁面內容，或拿到一個講得清楚的結束碼。寫入動作通過人工確認、wiki-put 回結束碼 0，而且送出去的是舊內容加上這次的異動，不是整頁覆蓋。結束碼 7 與 8 一律中止整個動作，不建頁、不寫入、不用原參數重試。 | diff --git a/skills/wiki/SKILL.md b/skills/wiki/SKILL.md index ae3f03b..ee50929 100644 --- a/skills/wiki/SKILL.md +++ b/skills/wiki/SKILL.md @@ -1,6 +1,6 @@ --- name: wiki -description: Read or write a Gitea wiki page through tools/gitea.sh and tools/hash-id. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose. Callers are jsc-ask, jsc-sdlc, jsc-log, jsc-hooks for its ERROR pages, jsc-cli for its CHECK pages, and jsc-meta for its SKILLSET and TOOLING pages. Use for any wiki page in the skill set; not for repo code files. +description: Read or write a Gitea wiki page through tools/gitea.sh and tools/hash-id. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose. Callers are jsc-ask, jsc-sdlc, jsc-log, jsc-hooks (ERROR), jsc-cli (CHECK), jsc-meta (SKILLSET, TOOLING) and jsc-assist (MONITOR). Use for any wiki page in the skill set; not for repo code files. --- # wiki — read and write Gitea wiki pages @@ -12,7 +12,7 @@ Every wiki operation in the jsc skill set goes through this skill. One entry poi Different page types can live in different `{owner}/{repo}` repos, classified by the page-name prefix. 1. **Host gate.** Confirm `GITEA_HOST` holds a value in the current shell. When it is missing, ask for it per the `jsc-ask:ask` rules before any `tools/gitea.sh` call that reaches the API; otherwise the first thing the user sees is the script's `GITEA_HOST is required` line instead of a decision-tree question. `GITEA_TOKEN` needs no inventory here — the script resolves it, retries once with the tea CLI login token, and exits 7 when neither works. Done when `GITEA_HOST` holds a value. -2. Run `tools/gitea.sh wiki-repo {TYPE}` (TYPE = the page-name prefix). Allowed types are `QUESTION`, `PLAN`, `ANALYZE`, `DELIVER`, `MAINTAIN`, `REPO`, `LOG`, `LEARN`, `ERROR`, `CHECK`, `REPORT`, `SKILLSET`, and `TOOLING`. The script reads `JSC_WIKI_REPO_{TYPE}` first and `JSC_WIKI_REPO` second, straight from the inherited environment, so take no separate inventory of those two variables. Never borrow another type's repo. Done when the command has printed exactly one `{owner}/{repo}`, or exited 3 and sent this page type to step 3, or exited 2 on a type outside the list above and stopped the run. +2. Run `tools/gitea.sh wiki-repo {TYPE}` (TYPE = the page-name prefix). Allowed types are `QUESTION`, `PLAN`, `ANALYZE`, `DELIVER`, `MAINTAIN`, `REPO`, `LOG`, `LEARN`, `ERROR`, `CHECK`, `REPORT`, `SKILLSET`, `TOOLING`, and `MONITOR`. The script reads `JSC_WIKI_REPO_{TYPE}` first and `JSC_WIKI_REPO` second, straight from the inherited environment, so take no separate inventory of those two variables. Never borrow another type's repo. Done when the command has printed exactly one `{owner}/{repo}`, or exited 3 and sent this page type to step 3, or exited 2 on a type outside the list above and stopped the run. 3. On exit 3 (neither variable is set), ask the user for that page type's `{owner}/{repo}` per the `jsc-ask:ask` rules, and suggest setting `JSC_WIKI_REPO_{TYPE}` (can differ per type) or `JSC_WIKI_REPO` (shared default). Done when the user has supplied one `{owner}/{repo}` for that page type. ## Operations diff --git a/tools/check-wiki-rules.sh b/tools/check-wiki-rules.sh index 2e7bf0f..491a04e 100755 --- a/tools/check-wiki-rules.sh +++ b/tools/check-wiki-rules.sh @@ -11,7 +11,7 @@ dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) gitea="$dir/gitea.sh" hash_id="$dir/hash-id" -TYPES='QUESTION PLAN ANALYZE DELIVER MAINTAIN REPO LOG LEARN ERROR CHECK REPORT SKILLSET TOOLING' +TYPES='QUESTION PLAN ANALYZE DELIVER MAINTAIN REPO LOG LEARN ERROR CHECK REPORT SKILLSET TOOLING MONITOR' fail() { printf '%s\n' "$1" >&2 diff --git a/tools/gitea.sh b/tools/gitea.sh index 281cd69..5be1e95 100755 --- a/tools/gitea.sh +++ b/tools/gitea.sh @@ -7,7 +7,7 @@ # gitea.sh clone-url / # 印出 clone URL # gitea.sh hash-id # 產生 8 碼大寫 SHA-1 hash；首碼為 0-9/A/B/C 時改成 Hxxxxxxx # gitea.sh wiki-repo # 解析頁面類型的 wiki 位置： -# TYPE = QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT|SKILLSET|TOOLING（即頁名前綴） +# TYPE = QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT|SKILLSET|TOOLING|MONITOR（即頁名前綴） # 依序取 JSC_WIKI_REPO_{TYPE} > JSC_WIKI_REPO；不得跨類型代用；都未設定 exit 3 # gitea.sh wiki-list / # 列出 wiki 頁名 # gitea.sh wiki-get / # 印出 wiki 頁 markdown；不存在時 exit 4 @@ -59,7 +59,7 @@ confirm_write() { resolve_wiki_repo() { # TYPE -> JSC_WIKI_REPO_{TYPE} -> JSC_WIKI_REPO type=$(printf '%s' "${1:?TYPE required}" | tr a-z A-Z) case "$type" in - QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT|SKILLSET|TOOLING) ;; + QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT|SKILLSET|TOOLING|MONITOR) ;; *) echo "unknown wiki type: $type" >&2; exit 2 ;; esac eval "v=\${JSC_WIKI_REPO_${type}:-}"