plugins/shared
2
0
Fork 0
Code Pull Requests Activity

sync #5

Merged
admin merged 6 commits from master into develop 2026-08-14 08:56:21 +00:00
Conversation 0 Commits 6 Files Changed 5
+52 -37
5 changed files with 52 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 02e7cfe136 - Show all commits
.claude-plugin/plugin.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-shared",
"version": "0.1.2",
"version": "0.1.3",
"description": "JSC 跨 AI 助理共用規範 skills plugin（Claude Code / Codex / Antigravity / OpenCode / GitHub Copilot CLI），`skills/` 為唯一真實來源，並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準；於 Claude Code 以 /jsc-shared: 前綴呼叫。",
"skills": "./skills",
"author": {
.codex-plugin/plugin.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-shared",
"version": "0.1.2",
"version": "0.1.3",
"description": "JSC 跨 AI 助理共用規範 skills plugin，`skills/` 為唯一真實來源，並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準。",
"skills": "./skills"
}
plugin.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-shared",
"version": "0.1.2",
"version": "0.1.3",
"description": "JSC 跨 AI 助理共用規範 skills plugin，`skills/` 為唯一真實來源，並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-shared: 前綴呼叫。",
"skills": "./skills"
}
skills/plan-wiki/SKILL.md
+23 -17
View File
@@ -1,7 +1,7 @@
---
name: plan-wiki
description: 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁，全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone。使用者要建立計畫、把計畫加入 wiki 目錄、指定 Gitea wiki repo／目錄頁／計畫頁、要求邊問邊同步 wiki、要求計畫檔案不落地、或提到 plan-wiki、計畫 wiki、wiki 目錄頁時觸發。適用於：需求尚未完整、需要逐題釐清並保存到 wiki 的計畫文件。不適用於：產生本機 plan.md／todo.md、拆 Gitea issue（用 /jsc-doc:issues-analyze）、或非 Gitea wiki。
argument-hint: "[--wiki-repo <owner/repo>] [--index <目錄頁title>] [--project <計畫名稱>] [--page <計畫頁title>] [--host <gitea主機>] [--yes]"
argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN-<yyyyMMdd>-<HASH>] [--host <gitea主機>] [--yes]"
---
# plan-wiki — 逐步建立計畫並同步到 Gitea wiki
@@ -24,7 +24,11 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index <目錄頁title>] [--project
本 skill 特有補充：
- 本 skill 會寫入外部 Gitea wiki；目標 wiki repo、目錄頁、計畫頁不明時必須詢問，不得臆測。
- 本 skill 會寫入外部 Gitea wiki；目標 wiki repo 不明時必須詢問，不得臆測。
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--index` 時才覆蓋預設值。
- 計畫頁 title 預設固定為 `PLAN-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由已確認的計畫內容、計畫名稱或需求摘要產生穩定短雜湊並轉成全大寫。
- 加入目錄頁時，先從計畫內容尋找系統名稱；若無明確系統名稱，依計畫目標產生一個精簡系統名稱。目錄標題使用 `{系統名稱}-計畫`，並連結到計畫頁。
- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本計畫既有列或在既有表格附加新列。
- **不落地絕對規則**：不得建立本機 `plan.md`、`todo.md`、`.md` 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 `curl --data @file`。
- 使用者已用參數指定 `--wiki-repo`、`--index`、`--project`、`--page` 時跳過對應詢問。
- 每一輪使用者回答後都要同步 wiki。同步失敗時停止下一輪詢問，先回報錯誤與待使用者處理的點。
@@ -32,14 +36,14 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index <目錄頁title>] [--project
## 參數
`[--wiki-repo <owner/repo>] [--index <目錄頁title>] [--project <計畫名稱>] [--page <計畫頁title>] [--host <gitea主機>] [--yes]`
`[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN-<yyyyMMdd>-<HASH>] [--host <gitea主機>] [--yes]`
| 參數 | 說明 |
| --- | --- |
| `--wiki-repo` | Gitea wiki 所屬 repo，例如 `knowledges/Plan`。未帶且無法從目前 repo 推得時詢問使用者。 |
| `--index` | 目錄頁 title，預設可詢問使用者；若使用者明確說「目錄」可用 `目錄`。 |
| `--project` | 計畫名稱，用於目錄頁 H1、說明與預設頁名。 |
| `--page` | 計畫頁 title；未帶時用 `<project> 計畫`，但需先告知使用者。 |
| `--index` | 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
| `--project` | 計畫名稱；未帶時從計畫內容尋找或產生系統名稱，用於目錄列標題與摘要。 |
| `--page` | 計畫頁 title；未帶時固定使用 `PLAN-{yyyyMMdd}-{HASH}`，不詢問。 |
| `--host` | Gitea 主機，依 `spec-gitea` host 決定順序處理。 |
| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突或使用者尚未確認的計畫完成判斷。 |
@@ -47,33 +51,35 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index <目錄頁title>] [--project
1. 依 `spec-gitea` 決定 host 與 token，只輸出 token「已設定／未設定」。
2. 確認 `--wiki-repo` 是否為 `owner/repo` 格式；不符合時詢問使用者修正。
3. 確認目錄頁 title、計畫名稱、計畫頁 title。
4. 用 `GET /repos/<owner>/<repo>` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。
3. 確認目錄頁 title：未帶 `--index` 時固定使用 `CONTENTS`。
4. 確認計畫頁 title：未帶 `--page` 時固定使用 `PLAN-{yyyyMMdd}-{HASH}`。雜湊輸入優先使用已確認的計畫內容；內容不足時使用計畫名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。
5. 確認系統名稱：先從 `--project`、計畫內容、需求來源或使用者回答尋找明確系統名稱；找不到時產生精簡系統名稱，不為此單獨詢問。
6. 用 `GET /repos/<owner>/<repo>` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。
## 階段 B：讀取 wiki 現況
1. 依 `spec-gitea` 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`。
2. 以 title 查表取得目錄頁與計畫頁的 `sub_url`，不得自行猜測轉義規則。
3. 讀取頁面：`GET /repos/<owner>/<repo>/wiki/page/<sub_url>`，將 `content_base64` 解成 UTF-8 Markdown。
4. 目錄頁不存在時在記憶中組出符合「目錄頁格式」的內容；計畫頁不存在時在記憶中組出目前計畫草稿。不得先寫成本機檔案。
4. 目錄頁不存在時在記憶中組出符合「目錄頁格式」的新頁內容；目錄頁存在時不得用預設格式覆蓋整頁，只能保留原內容後修改或附加本計畫目錄列。計畫頁不存在時在記憶中組出目前計畫草稿。不得先寫成本機檔案。
## 目錄頁格式
目錄頁必須維持下列結構；更新時保留既有列，只新增或更新本計畫相關列：
目錄頁不存在時建立下列結構；更新既有目錄頁時禁止整頁覆蓋，必須保留既有標題、說明、表格與其他內容，只新增或更新本計畫相關列：
```markdown
# <project> 計畫
# CONTENTS
<一段計畫說明。>
計畫目錄。
| 頁面 | 內容 |
|------|------|
| [<page title>](<page title percent-encoded, 空白用 %20>) | <頁面內容摘要> |
| [<系統名稱>-計畫](<page title percent-encoded, 空白用 %20>) | plan wiki：<系統名稱> 計畫 |
產出日期：yyyy-MM-dd
```
若目錄頁已存在且不是單一計畫專用目錄，仍以同一張 `| 頁面 | 內容 |` 表格為準：保留原標題與說明，只在表格中 upsert 本計畫頁面列。連結文字用頁面 title；連結 target 用 `encodeURIComponent(title).replace(/%20/g, "%20")` 的結果，不使用 API `sub_url` 反推人工連結。
若目錄頁已存在且不是單一計畫專用目錄，仍以同一張 `| 頁面 | 內容 |` 表格為準：保留原標題與說明，只在表格中 upsert 本計畫頁面列。若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。連結文字固定為 `<系統名稱>-計畫`；連結 target 用 `encodeURIComponent(title).replace(/%20/g, "%20")` 的結果，不使用 API `sub_url` 反推人工連結。
## 計畫頁格式
@@ -122,7 +128,7 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index <目錄頁title>] [--project
每輪同步順序固定：
1. 更新計畫頁。
2. 更新目錄頁，確保表格中有本計畫頁連結與摘要。
2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<系統名稱>-計畫` 列，或在既有表格／頁末附加新列，確保有本計畫頁連結與摘要。
3. 再次讀回兩個頁面確認內容已更新。
API 寫入方式：
@@ -154,6 +160,6 @@ API 寫入方式：
| 助理 | 呼叫 |
| --- | --- |
| Claude Code / Antigravity | `/jsc-shared:plan-wiki --wiki-repo knowledges/Plan --index 目錄 --project Kokorone --page "Kokorone 系統架構計畫"` |
| Codex | `$plan-wiki --wiki-repo knowledges/Plan --index 目錄 --project Kokorone` |
| Claude Code / Antigravity | `/jsc-shared:plan-wiki --wiki-repo knowledges/Plan --project Kokorone` |
| Codex | `$plan-wiki --wiki-repo knowledges/Plan --project Kokorone` |
| OpenCode | 描述需求（如「逐步問我計畫內容，並同步到 Gitea wiki 目錄與頁面」）自動觸發 |
skills/todo-wiki/SKILL.md
+26 -17
View File
@@ -1,7 +1,7 @@
---
name: todo-wiki
description: 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程：先依 `/jsc-shared:spec-model` 的「需求分析」任務挑出分析模型，當前模型不符就停止；接著讀取來源（需求描述、本機檔案，或走 `/jsc-shared:spec-issue-read` 讀取的 Gitea 議題）並釐清需求，任何不清楚之處依 `/jsc-shared:spec-ask-user` 詢問；再依「依清單實作」任務挑出實作模型或採用使用者指定；最後把帶 `model`／`model_alias`／`model_reason`／`analyzed_by`／`analyzed_at`／`scope` frontmatter 與強制規則區塊的 TODO 內容直接同步到指定 Gitea wiki 目錄頁與 todo 頁。當使用者說要把需求整理成 wiki TODO、同步 todo 到 Gitea wiki、需求轉 todo-wiki、指定模型 todo wiki、或提到 todo-wiki skill 時觸發。不適用於：產生本機 todo.md、把需求拆分成多個 Gitea 議題（用 `/jsc-doc:issues-analyze`）、實作既有 Gitea 議題的 TODO（用 `/jsc-code:issues`）。
argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <目錄頁title>] [--wiki-project <計畫名稱>] [--wiki-page <todo頁title>] [--append|--overwrite] [--yes]"
argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO-<yyyyMMdd>-<HASH>] [--append|--overwrite] [--yes]"
---
# todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki
@@ -30,22 +30,27 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
- `--source` 指向本機檔案時可以唯讀讀取來源檔；這不是輸出落地。`--source` 指向 Gitea 議題附件時，僅可依 `spec-issue-read` 的附件唯讀暫存例外讀取，讀完立即刪除。
- 本 skill 產生的 wiki todo 頁就是 `spec-model` 第六節所述「帶 `model:` frontmatter 的清單檔」的源頭；本 skill 只負責產生與同步清單，不執行清單內容。
- 階段 1 的模型檢查針對「執行本 skill 分析工作的 agent 自己」；階段 3 選出的實作模型是寫進 wiki 頁給未來另一個 session 用。
- 目標 wiki repo、目錄頁、計畫名稱不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
- 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。
- TODO 頁 title 預設固定為 `TODO-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。
- 必須詢問使用者是否需要把本 TODO 連結到計畫；使用者回答不需要時，不更新目錄頁，也不要把 TODO 加到目錄。
- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。系統名稱優先從關聯計畫取得；若沒有關聯計畫，從需求內容尋找或產生系統名稱。
- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 TODO 既有列或在既有表格附加新列。
## 參數
`[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <目錄頁title>] [--wiki-project <計畫名稱>] [--wiki-page <todo頁title>] [--append|--overwrite] [--yes]`
`[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO-<yyyyMMdd>-<HASH>] [--append|--overwrite] [--yes]`
| 參數 | 說明 |
| --- | --- |
| `--source` | 需求來源。未帶時視為必要決策，詢問使用者要用描述／檔案路徑／議題編號哪一種，不得臆測。 |
| `--impl-model` | 直接指定實作模型（id 或 alias），跳過階段 3 的推薦流程；仍會在 `model_reason` 註明「使用者指定」。 |
| `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 |
| `--wiki-index` | wiki 目錄頁 title，例如 `目錄`。 |
| `--wiki-project` | 目錄頁中的計畫名稱，用於目錄頁標題、說明或 upsert 摘要。 |
| `--wiki-page` | todo 頁 title；未帶時用 `<wiki-project> 實作清單`，並在同步摘要中明確列出。 |
| `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
| `--wiki-project` | 關聯計畫或系統名稱；需要加入目錄頁時，用於產生 `{關聯計畫的系統名稱}-代辦`。 |
| `--wiki-page` | todo 頁 title；未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`，不詢問。 |
| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 |
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、或對外寫入目標不明等必要決策。 |
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否連結到計畫、或對外寫入目標不明等必要決策。 |
## 階段 1：選分析模型
@@ -102,6 +107,7 @@ scope: <階段 2 產出的 scope>
| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 |
| **附加不覆蓋** | 若之後要往本頁追加新需求：`model` 相同 → 附加到頁面末尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 |
| **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei）。不得留待多項一起補勾。 |
| **更新後才能繼續** | 每完成一項後，必須立即把勾選狀態寫回本 wiki 頁並讀回確認成功；若 wiki 更新或讀回確認失敗，**立刻停止，不得繼續執行下一項**。 |
[<yyyy/MM/dd HH:mm:ss>][模型檢查][ERR]: 本清單指定 <model>（<alias>），當前模型為 <current-model-id>。
請執行 /model <alias> 切換後重新載入本 wiki 頁，本次不進行任何修改。
@@ -117,10 +123,11 @@ scope: <階段 2 產出的 scope>
## 階段 5：讀取既有 wiki 頁並決定寫入策略
1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。
2. 確認 `--wiki-repo`、`--wiki-index`、`--wiki-project`；缺少就詢問。
3. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得目錄頁與 todo 頁 `sub_url`。
4. 讀取既有 todo 頁；若不存在，策略為「建立」。
5. 既有 todo 頁存在時解析 frontmatter：
2. 確認 `--wiki-repo`；缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`。
3. 詢問使用者是否需要把本 TODO 連結到計畫。若不需要，記錄為「不更新目錄頁」；若需要，確認或產生關聯計畫的系統名稱，用於目錄列標題。
4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若需要連結到計畫，也取得目錄頁 `sub_url`。目錄頁不存在時才建立；目錄頁存在時必須讀取原內容並保留，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。
5. 讀取既有 todo 頁；若不存在，策略為「建立」。
6. 既有 todo 頁存在時解析 frontmatter：
| 狀況 | 動作 |
| --- | --- |
@@ -136,15 +143,17 @@ scope: <階段 2 產出的 scope>
同步順序固定：
1. 寫入 todo 頁。
2. upsert 目錄頁表格列。
3. 讀回兩個頁面確認內容已更新。
2. 若使用者確認需要連結到計畫，upsert 目錄頁表格列：目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。若使用者回答不需要，跳過目錄頁更新。
3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。
目錄頁表格列格式：
```markdown
| [<todo page title>](<todo page title percent-encoded>) | todo wiki：<wiki-project> 實作清單——執行規則、需求彙整、分群任務與驗收條件 |
| [<關聯計畫的系統名稱>-代辦](<todo page title percent-encoded>) | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
```
若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。
API 寫入方式：
- 建立新頁：`POST /repos/<owner>/<repo>/wiki/new`，body 帶 `title`、`content`、`message`。
@@ -163,7 +172,7 @@ API 寫入方式：
| 實作模型 | `model` / `model_alias`，並註明推薦或使用者指定 |
| 項目數 | 本次新增的 checklist 項目數 |
| Wiki repo | `<owner/repo>` |
| 目錄頁 | URL |
| 目錄頁 | URL；若本次未連結到計畫，填「未更新（使用者選擇不加入目錄）」 |
| Todo 頁 | URL |
| 本次動作 | 建立／附加／覆蓋 |
@@ -177,6 +186,6 @@ API 寫入方式：
| 助理 | 呼叫 |
| --- | --- |
| Claude Code / Antigravity | `/jsc-shared:todo-wiki --source "把 X 模組改成非同步" --wiki-repo knowledges/Plan --wiki-index 目錄 --wiki-project Kokorone` |
| Codex | `$todo-wiki --source ./RFC.md --wiki-repo knowledges/Plan --wiki-index 目錄 --wiki-project Kokorone` |
| Claude Code / Antigravity | `/jsc-shared:todo-wiki --source "把 X 模組改成非同步" --wiki-repo knowledges/Plan --wiki-project Kokorone` |
| Codex | `$todo-wiki --source ./RFC.md --wiki-repo knowledges/Plan --wiki-project Kokorone` |
| OpenCode | 描述需求（如「幫我把這段需求分析清楚，直接同步成 Gitea wiki TODO，不要落地檔案」）自動觸發 |