From 67106b22c368872cc568868abce34313617b9dbd Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 28 Jul 2026 17:07:14 +0800 Subject: [PATCH 1/2] =?UTF-8?q?refactor(plugin=20=E5=91=BD=E5=90=8D?= =?UTF-8?q?=E7=A9=BA=E9=96=93):=20plugin=20=E6=9B=B4=E5=90=8D=20jsc-doc?= =?UTF-8?q?=E3=80=81hooks=20=E5=8F=AA=E8=A8=BB=E5=86=8A=E8=87=AA=E5=B7=B1?= =?UTF-8?q?=E6=93=81=E6=9C=89=E7=9A=84=20worklog?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 五份 manifest 的 name 由 jsc 改為 jsc-doc - skill 目錄去掉重複的 doc- 前綴共 5 個（doc-funcs → funcs 等），worklog 名稱不變，frontmatter name 同步 - hooks/hooks.json 由合併超集改為只註冊 Stop（worklog）：role 的 hook 交還 jsc-generic，避免改名後重複執行 - hook 腳本搜尋路徑與文件內 cache 路徑改指 jsc-doc - 指令引用改為 /jsc-doc: 前綴；跨 plugin 引用指向 /jsc-code:、/jsc-generic: - 保留 .docs/doc-funcs-index.md 等產物檔名不變（非 skill 識別名） - 版號 0.2.6 → 0.2.7 Co-Authored-By: Claude Opus 5 (1M context) --- .agents/plugins/marketplace.json | 2 +- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 6 +- .codex-plugin/plugin.json | 6 +- AGENTS.md | 4 +- README.md | 132 +++++++++--------- hooks/hooks.json | 18 +-- plugin.json | 6 +- scripts/worklog/wiki_api.py | 2 +- scripts/worklog/worklog.sh | 4 +- skills/{doc-docker => docker}/SKILL.md | 4 +- .../scripts/align_comments.sh | 0 .../scripts/awk/align_col.awk | 0 .../scripts/awk/find_col.awk | 0 .../scripts/awk/strip_col.awk | 0 .../scripts/awk/verify_col.awk | 0 .../scripts/fix_comments.sh | 0 skills/{doc-funcs => funcs}/SKILL.md | 16 +-- .../templates/command-header.md | 2 +- .../SKILL.md | 16 +-- .../SKILL.md | 24 ++-- .../{doc-issues-sync => issues-sync}/SKILL.md | 26 ++-- skills/worklog/SKILL.md | 16 +-- 23 files changed, 135 insertions(+), 151 deletions(-) rename skills/{doc-docker => docker}/SKILL.md (96%) rename skills/{doc-docker => docker}/scripts/align_comments.sh (100%) rename skills/{doc-docker => docker}/scripts/awk/align_col.awk (100%) rename skills/{doc-docker => docker}/scripts/awk/find_col.awk (100%) rename skills/{doc-docker => docker}/scripts/awk/strip_col.awk (100%) rename skills/{doc-docker => docker}/scripts/awk/verify_col.awk (100%) rename skills/{doc-docker => docker}/scripts/fix_comments.sh (100%) rename skills/{doc-funcs => funcs}/SKILL.md (94%) rename skills/{doc-funcs => funcs}/templates/command-header.md (86%) rename skills/{doc-issues-analyze-to-file => issues-analyze-to-file}/SKILL.md (88%) rename skills/{doc-issues-analyze => issues-analyze}/SKILL.md (87%) rename skills/{doc-issues-sync => issues-sync}/SKILL.md (88%) diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 443febb..85550bd 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -2,7 +2,7 @@ "name": "doc", "plugins": [ { - "name": "jsc", + "name": "jsc-doc", "source": { "source": "url", "url": "https://gitea.jsc.idv.tw/plugins/doc.git" diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 87183e3..87da6d2 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "plugins": [ { - "name": "jsc", + "name": "jsc-doc", "source": "./", "description": "JSC 文件化 skills：整理 docker-compose 註解、補齊 function XML 文件、同步 Gitea issue 文件流程，並透過 worklog 記錄工作。" } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ab62f1b..38dffe1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { - "name": "jsc", - "version": "0.2.6", - "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode / GitHub Copilot）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。", + "name": "jsc-doc", + "version": "0.2.7", + "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode / GitHub Copilot）：docker 會整理 docker-compose.yaml 的行內註解與標題日期；funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc-doc: 前綴呼叫。", "skills": "./skills", "author": { "name": "JSC" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 82bcf0a..befb0e4 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { - "name": "jsc", - "version": "0.2.6", - "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki（自動 Stop hook 僅相容 hook 環境支援）。所有 skills 以 SKILL.md 為共通標準。", + "name": "jsc-doc", + "version": "0.2.7", + "description": "JSC 文件化 skills：docker 會整理 docker-compose.yaml 的行內註解與標題日期；funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki（自動 Stop hook 僅相容 hook 環境支援）。所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/AGENTS.md b/AGENTS.md index d84fb8b..22abc1a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# jsc — 共用 Skills（跨 AI 助理） +# jsc-doc — 共用 Skills（跨 AI 助理） 本 repo 是一組以 **Agent Skills（`SKILL.md`）** 標準撰寫的共用 skills，可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。 @@ -6,7 +6,7 @@ - 所有可用的 skills 位於本 repo 的 `skills//SKILL.md`。 - 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。 -- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc:` 呼叫；Codex 以 `$`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc:` 前綴，不需強制加。 +- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc-doc:` 呼叫；Codex 以 `$`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc-doc:` 前綴，不需強制加。 - 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。 ## 慣例 diff --git a/README.md b/README.md index 7bcc947..a76aead 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,22 @@ -# jsc — 跨 AI 助理文件化 Skill 集合 +# jsc-doc — 跨 AI 助理文件化 Skill 集合 一個可同時被 **Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot** 使用的文件化 skill 集合。 -目前內含六個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；`doc-issues-analyze-to-file` 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言；`doc-issues-analyze` 用於把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日排序留言（不實作程式碼，實作交由 code plugin 的 code-issues）；`doc-issues-sync` 用於讀取 Gitea 專案或議題，依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位、產生進度留言；指定「關閉專案／專案完成」時改為批次把專案所有議題搬到「已完成」並關閉；`worklog` 用於把 session stop 的內容透過 README 定義的 headless CLI 整理成六欄工作紀錄並追加到 Gitea wiki。 +目前內含六個實作型 skills：`docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；`issues-analyze-to-file` 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言；`issues-analyze` 用於把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日排序留言（不實作程式碼，實作交由 code plugin 的 issues）；`issues-sync` 用於讀取 Gitea 專案或議題，依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位、產生進度留言；指定「關閉專案／專案完成」時改為批次把專案所有議題搬到「已完成」並關閉；`worklog` 用於把 session stop 的內容透過 README 定義的 headless CLI 整理成六欄工作紀錄並追加到 Gitea wiki。 核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`）， 搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。 -在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:doc-docker`）。 +在 Claude Code 與 Antigravity 中，skill 以 **`/jsc-doc:` 前綴**呼叫（例如 `/jsc-doc:docker`）。 --- ## 前綴與呼叫方式 -| 助理 | 安裝方式 | 呼叫 | `/jsc:` 前綴 | +| 助理 | 安裝方式 | 呼叫 | `/jsc-doc:` 前綴 | | --- | --- | --- | --- | -| Claude Code | `claude plugin`（marketplace） | `/jsc:` 或自動觸發 | ✅ | +| Claude Code | `claude plugin`（marketplace） | `/jsc-doc:` 或自動觸發 | ✅ | | Codex | `codex plugin`（marketplace） | `$` 或 `/skills` 選單 | ❌（用 `$name`） | -| Antigravity | `agy plugin install` | `/jsc:` 或自動觸發 | ✅ | +| Antigravity | `agy plugin install` | `/jsc-doc:` 或自動觸發 | ✅ | | OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） | -| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc:` 前綴） | +| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc-doc:` 前綴） | > Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。 @@ -29,13 +29,13 @@ ``` doc/ ├── .claude-plugin/ -│ ├── plugin.json # Claude 外掛定義（name: "jsc"） +│ ├── plugin.json # Claude 外掛定義（name: "jsc-doc"） │ └── marketplace.json # Claude marketplace（name: "doc"，source 指向本 repo） ├── .codex-plugin/ -│ └── plugin.json # Codex 外掛定義（name: "jsc"，skills: "./skills"） +│ └── plugin.json # Codex 外掛定義（name: "jsc-doc"，skills: "./skills"） ├── .agents/plugins/ │ └── marketplace.json # Codex marketplace（name: "doc"，url source 指向本 repo） -├── plugin.json # Antigravity 外掛定義（name: "jsc"，skills: "./skills/"） +├── plugin.json # Antigravity 外掛定義（name: "jsc-doc"，skills: "./skills/"） ├── hooks/ │ └── hooks.json # Stop → worklog；Claude 用 plugin root，Codex fallback 到安裝 cache ├── scripts/ @@ -44,15 +44,15 @@ doc/ │ ├── wiki_api.py # Gitea wiki 讀寫、token 解析、append 重試、週頁命名 │ └── transcript.py # transcript 本輪抽取、耗時估算與機密遮蔽 ├── skills/ # ★ 唯一真實來源：所有 skills -│ ├── doc-docker/ # 對齊 docker-compose 註解（含 scripts/） +│ ├── docker/ # 對齊 docker-compose 註解（含 scripts/） │ │ ├── SKILL.md │ │ └── scripts/ -│ ├── doc-funcs/ # 為 function 補齊 XML 文件、指令檔逐行註解（含 templates/） +│ ├── funcs/ # 為 function 補齊 XML 文件、指令檔逐行註解（含 templates/） │ │ ├── SKILL.md │ │ └── templates/ # 指令檔開頭「用途／更新時間」標頭範本（command-header.md） -│ ├── doc-issues-analyze-to-file/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言 -│ ├── doc-issues-analyze/SKILL.md # 讀來源 → 保存議題 → 小功能議題（看板移待處理）→ 排序留言（不實作） -│ ├── doc-issues-sync/SKILL.md # 讀專案／議題 → 依工作目錄勾稽 TODO → 補 TODO／更新標籤／調整看板欄位 → 進度留言；關閉專案時批次搬「已完成」並關閉 +│ ├── issues-analyze-to-file/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言 +│ ├── issues-analyze/SKILL.md # 讀來源 → 保存議題 → 小功能議題（看板移待處理）→ 排序留言（不實作） +│ ├── issues-sync/SKILL.md # 讀專案／議題 → 依工作目錄勾稽 TODO → 補 TODO／更新標籤／調整看板欄位 → 進度留言；關閉專案時批次搬「已完成」並關閉 │ └── worklog/SKILL.md # 工作證明自動記錄的操作與維護 ├── AGENTS.md # 跨助理共用指引 └── README.md @@ -66,7 +66,7 @@ doc/ | `worklog` 手動模式 | ✅ | ⚠️ 需安裝後保留 `scripts/` | ⚠️ 同左 | ⚠️ 需完整 plugin 目錄 | ⚠️ 需安裝後保留 `scripts/` | | 摘要 CLI | `claude -p` | `codex exec` | `agy -p` | `opencode run` | `copilot -p` | -`worklog` 自動記錄仍依賴相容的 Stop hook 與 transcript JSONL 結構；Claude Code 會用 `CLAUDE_PLUGIN_ROOT` 定位腳本，Codex 會從 `~/.codex/plugins/cache/doc/jsc` 找已安裝的 worklog 腳本並解析 Codex session JSONL。摘要執行器可用 `WORKLOG_CLI=auto|claude|codex|agy|opencode|copilot` 指定；預設 `auto` 會先依目前 hook/session 環境判斷正在使用的 CLI，判斷不到或該 CLI 不可執行時才 fallback 到已安裝工具。 +`worklog` 自動記錄仍依賴相容的 Stop hook 與 transcript JSONL 結構；Claude Code 會用 `CLAUDE_PLUGIN_ROOT` 定位腳本，Codex 會從 `~/.codex/plugins/cache/doc/jsc-doc` 找已安裝的 worklog 腳本並解析 Codex session JSONL。摘要執行器可用 `WORKLOG_CLI=auto|claude|codex|agy|opencode|copilot` 指定；預設 `auto` 會先依目前 hook/session 環境判斷正在使用的 CLI，判斷不到或該 CLI 不可執行時才 fallback 到已安裝工具。 --- @@ -83,39 +83,39 @@ doc/ ```bash # 安裝 claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/doc.git -claude plugin install jsc@doc +claude plugin install jsc-doc@doc # 更新 claude plugin marketplace update doc -claude plugin update jsc@doc +claude plugin update jsc-doc@doc # 移除 -claude plugin uninstall jsc@doc +claude plugin uninstall jsc-doc@doc claude plugin marketplace remove doc ``` - 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。 - 本機開發（免 push）：`claude plugin marketplace add C:\Users\h3285\source\repos.plugins\doc`（本地路徑）後再 install。 -- **呼叫**：`/jsc:`（例 `/jsc:doc-docker`）。 +- **呼叫**：`/jsc-doc:`（例 `/jsc-doc:docker`）。 ### Codex ```bash # 安裝 codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/doc.git -codex plugin add jsc@doc +codex plugin add jsc-doc@doc # 更新（重新抓取 marketplace 的 git 快照） codex plugin marketplace upgrade doc # 移除 -codex plugin remove jsc@doc +codex plugin remove jsc-doc@doc codex plugin marketplace remove doc ``` -- 安裝 token `jsc@doc` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。 +- 安裝 token `jsc-doc@doc` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。 - 本 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。 -- **呼叫**：`$`（例 `$doc-docker`），或用 `/skills` 選單。 +- **呼叫**：`$`（例 `$docker`），或用 `/skills` 選單。 ### Antigravity（`agy`） @@ -128,16 +128,16 @@ agy plugin install ~/plugins/doc # 更新（agy 無 update 子指令 → git pull 後重裝） git -C ~/plugins/doc pull -agy plugin uninstall jsc +agy plugin uninstall jsc-doc agy plugin install ~/plugins/doc # 移除 -agy plugin uninstall jsc +agy plugin uninstall jsc-doc ``` - 若把 skills 放到 GitHub，則可直接 `agy plugin install https://github.com//`。 -- 其他：`agy plugin list`、`agy plugin enable jsc` / `disable jsc`、`agy plugin validate `。安裝後重啟工作階段。 -- **呼叫**：`/jsc:`（例 `/jsc:doc-docker`）或依描述自動觸發。 +- 其他：`agy plugin list`、`agy plugin enable jsc-doc` / `disable jsc-doc`、`agy plugin validate `。安裝後重啟工作階段。 +- **呼叫**：`/jsc-doc:`（例 `/jsc-doc:docker`）或依描述自動觸發。 ### OpenCode @@ -155,7 +155,7 @@ git -C ~/jsc-plugin pull cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/ # 移除 -rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ~/.config/opencode/skills/doc-issues-analyze-to-file ~/.config/opencode/skills/doc-issues-analyze ~/.config/opencode/skills/doc-issues-sync ~/.config/opencode/skills/worklog +rm -rf ~/.config/opencode/skills/docker ~/.config/opencode/skills/funcs ~/.config/opencode/skills/issues-analyze-to-file ~/.config/opencode/skills/issues-analyze ~/.config/opencode/skills/issues-sync ~/.config/opencode/skills/worklog ``` > **worklog 在 OpenCode 的 skills 目錄安裝不可用**：上面的複製只帶 `skills/`，不含 `scripts/` 與 `hooks/`，worklog 的所有模式都會失敗；若以完整 plugin 目錄執行並能解析 `scripts/worklog`，可用 `WORKLOG_CLI=opencode` 作為摘要 CLI。 @@ -171,20 +171,20 @@ Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令， ```bash # 安裝 copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/doc.git -copilot plugin install jsc@doc +copilot plugin install jsc-doc@doc # 更新 copilot plugin marketplace update doc -copilot plugin update jsc@doc +copilot plugin update jsc-doc@doc # 移除 -copilot plugin uninstall jsc@doc +copilot plugin uninstall jsc-doc@doc copilot plugin marketplace remove doc ``` -- 安裝 token `jsc@doc` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。 +- 安裝 token `jsc-doc@doc` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。 - `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 可用上方 HTTPS URL。 -- **呼叫**：在 Copilot CLI 中用自然語言描述需求，例如 `copilot -i "請使用 doc-docker 整理 docker-compose 註解"`。 +- **呼叫**：在 Copilot CLI 中用自然語言描述需求，例如 `copilot -i "請使用 docker 整理 docker-compose 註解"`。 - `worklog` 的 `Stop` hook 自動記錄仍只有相容 hook 環境會實際執行；Copilot CLI 可作為 `WORKLOG_CLI=copilot` 摘要執行器，但不會執行 Claude Code hook。 --- @@ -193,18 +193,18 @@ copilot plugin marketplace remove doc 安裝好之後，不必進互動介面，一行指令就能叫某個 skill 跑完並印出結果： -| 助理 | headless 指令 | 執行 `doc-docker` skill | +| 助理 | headless 指令 | 執行 `docker` skill | | --- | --- | --- | -| Claude Code | `claude -p ""` | `claude -p "/jsc:doc-docker"` | -| Codex | `codex exec ""` | `codex exec '$doc-docker'` | -| Antigravity | `agy -p ""` | `agy -p "/jsc:doc-docker"` | +| Claude Code | `claude -p ""` | `claude -p "/jsc-doc:docker"` | +| Codex | `codex exec ""` | `codex exec '$docker'` | +| Antigravity | `agy -p ""` | `agy -p "/jsc-doc:docker"` | | OpenCode | `opencode run ""` | `opencode run "整理 docker-compose 註解"` | | GitHub Copilot CLI | `copilot -p ""` | `copilot -p "整理 docker-compose 註解"` | -- Claude / Antigravity 支援 `/jsc:` 前綴，直接 `-p "/jsc:"` 即可。 -- Codex 以 `$` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$doc-docker'`。 +- Claude / Antigravity 支援 `/jsc-doc:` 前綴，直接 `-p "/jsc-doc:"` 即可。 +- Codex 以 `$` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$docker'`。 - OpenCode 與 Copilot 沒有前綴，用自然語言描述需求；Copilot CLI 會讀取已安裝 plugin 提供的 skills。 -- 帶引數就接在後面，例如 `claude -p "/jsc:doc-docker docker-compose.yaml"`、`codex exec '$doc-docker docker-compose.yaml'`。 +- 帶引數就接在後面，例如 `claude -p "/jsc-doc:docker docker-compose.yaml"`、`codex exec '$docker docker-compose.yaml'`。 --- @@ -215,51 +215,51 @@ copilot plugin marketplace remove doc -### `doc-docker` +### `docker` 整理並對齊 `docker-compose.yaml` 的行內註解與標題區塊，優先透過內建 shell/awk 腳本批次處理或處理指定檔案。當使用者要對齊 docker-compose 註解、整理 compose 檔註解欄位、更新 compose 標題日期，或提到 docker-compose、dc-tidy、align_comments、註解對齊時使用此 skill。 -- **Claude Code / Antigravity**：`/jsc:doc-docker` -- **Codex**：`$doc-docker`，或用 `/skills` 選單 +- **Claude Code / Antigravity**：`/jsc-doc:docker` +- **Codex**：`$docker`，或用 `/skills` 選單 - **OpenCode**：描述需求自動觸發 -### `doc-funcs` +### `funcs` -掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments；指令檔（腳本／CI／部署設定檔）草稿開頭的「用途／更新時間」標頭固定依 `skills/doc-funcs/templates/command-header.md` 範本產生（依檔案類型選 `#` 或 `::`/`REM` 變體）；`Dockerfile` 與 README 的檔名會依專案內多數檔案的大小寫命名慣例正規化（無明顯多數則保留原檔名），改名時同步更新引用；同時整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿，最後重建 README 專案列表、功能列表與使用範例。README 更新時間固定使用台灣時區（Asia/Taipei）與 `yyyy/MM/dd HH:mm:ss` 格式，專案列表會拆成「專案名稱／專案描述」、「專案名稱／參考專案列表」、「專案名稱／NuGet 套件列表」三張表，且專案名稱會連到 Gitea/GitHub 遠端上的專案資料夾；遇到跨專案或跨命名空間的同名型別時會在功能名稱補上模組/專案前綴，並會跳脫 Markdown 表格、link text、heading 中的 C# 泛型角括號，檢查功能列表連結與使用範例 anchor 一致後執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、整理 workflow README、建立 .docs 草稿，或提到 doc-funcs、function 文件化、workflow 文件化、XML documentation comments 時使用此 skill。 +掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments；指令檔（腳本／CI／部署設定檔）草稿開頭的「用途／更新時間」標頭固定依 `skills/funcs/templates/command-header.md` 範本產生（依檔案類型選 `#` 或 `::`/`REM` 變體）；`Dockerfile` 與 README 的檔名會依專案內多數檔案的大小寫命名慣例正規化（無明顯多數則保留原檔名），改名時同步更新引用；同時整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿，最後重建 README 專案列表、功能列表與使用範例。README 更新時間固定使用台灣時區（Asia/Taipei）與 `yyyy/MM/dd HH:mm:ss` 格式，專案列表會拆成「專案名稱／專案描述」、「專案名稱／參考專案列表」、「專案名稱／NuGet 套件列表」三張表，且專案名稱會連到 Gitea/GitHub 遠端上的專案資料夾；遇到跨專案或跨命名空間的同名型別時會在功能名稱補上模組/專案前綴，並會跳脫 Markdown 表格、link text、heading 中的 C# 泛型角括號，檢查功能列表連結與使用範例 anchor 一致後執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、整理 workflow README、建立 .docs 草稿，或提到 funcs、function 文件化、workflow 文件化、XML documentation comments 時使用此 skill。 -- **Claude Code / Antigravity**：`/jsc:doc-funcs` -- **Codex**：`$doc-funcs`，或用 `/skills` 選單 +- **Claude Code / Antigravity**：`/jsc-doc:funcs` +- **Codex**：`$funcs`，或用 `/skills` 選單 - **OpenCode**：描述需求自動觸發 -### `doc-issues-analyze-to-file` +### `issues-analyze-to-file` -讀取一或多筆 Gitea issue URL（優先用 `tea`，否則用 Gitea REST API + `curl` + `GITEA_TOKEN`，不依賴 `jq`），把 issue 正文與留言彙整成一份完整需求文件，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑與專案、依需求性質從既有標籤挑選填入），再配合使用者指定的 repositories 或 issue 所在 repo，對每個階段派 subagent 產生實作草稿，最後產出交付文件並依 issues 分組留言到對應 issue。建立 issue 與留言前會先產生全部草稿並以 AskUserQuestion 讓使用者確認執行方式（全部執行／只建立 issue／只產文件不動 Gitea／逐階段確認）。當使用者明確要「產出需求文件／實作草稿／交付文件檔案」的 issue 分析，或提到 doc-issues-analyze-to-file、issue 需求分析文件、issue 拆階段交付文件時使用此 skill；全程不落地檔案、以議題描述與留言保存中間成果的拆分流程改用 doc-issues-analyze，兩者都可能符合時先詢問使用者要「檔案交付」還是「議題留言」。 +讀取一或多筆 Gitea issue URL（優先用 `tea`，否則用 Gitea REST API + `curl` + `GITEA_TOKEN`，不依賴 `jq`），把 issue 正文與留言彙整成一份完整需求文件，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑與專案、依需求性質從既有標籤挑選填入），再配合使用者指定的 repositories 或 issue 所在 repo，對每個階段派 subagent 產生實作草稿，最後產出交付文件並依 issues 分組留言到對應 issue。建立 issue 與留言前會先產生全部草稿並以 AskUserQuestion 讓使用者確認執行方式（全部執行／只建立 issue／只產文件不動 Gitea／逐階段確認）。當使用者明確要「產出需求文件／實作草稿／交付文件檔案」的 issue 分析，或提到 issues-analyze-to-file、issue 需求分析文件、issue 拆階段交付文件時使用此 skill；全程不落地檔案、以議題描述與留言保存中間成果的拆分流程改用 issues-analyze，兩者都可能符合時先詢問使用者要「檔案交付」還是「議題留言」。 -- **Claude Code / Antigravity**：`/jsc:doc-issues-analyze-to-file` -- **Codex**：`$doc-issues-analyze-to-file`，或用 `/skills` 選單 +- **Claude Code / Antigravity**：`/jsc-doc:issues-analyze-to-file` +- **Codex**：`$issues-analyze-to-file`，或用 `/skills` 選單 - **OpenCode**：描述需求自動觸發 -### `doc-issues-analyze` +### `issues-analyze` -讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取——文字附件直接取內容、圖片等二進位附件唯讀暫存讀取後即刪、無法讀取的附件列出檔名標註需人工確認），先檢查 `tea` 與 `GITEA_TOKEN` 並詢問使用者要用 `tea` 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時，母議題（保存議題）必須所有子議題都關閉後才可關閉——優先以 Gitea issue dependency 阻擋，不支援時在母議題描述加入子議題清單與關閉前檢查），每個小功能議題都會詢問使用者描述是否有補充內容，所有議題描述最後都會依描述內容產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），會把議題移到「待處理」欄位（不往回移、Gitea 介面不支援時改列建議清單請使用者手動拖曳）；最後依到期日與相依關係排序小功能議題並把排序結果留言到保存議題。本 skill 到「議題拆分完成＋排序留言」為止，**不實作程式碼**（不修改原始碼、不 commit、不 push、不開 PR），實作交由 `/jsc:code-issues`。所有中間成果都不落地成草稿檔，一律使用 `tea` 或 Gitea API 保存到議題描述或留言。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill；要產出需求／交付文件檔案時改用 doc-issues-analyze-to-file。 +讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取——文字附件直接取內容、圖片等二進位附件唯讀暫存讀取後即刪、無法讀取的附件列出檔名標註需人工確認），先檢查 `tea` 與 `GITEA_TOKEN` 並詢問使用者要用 `tea` 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時，母議題（保存議題）必須所有子議題都關閉後才可關閉——優先以 Gitea issue dependency 阻擋，不支援時在母議題描述加入子議題清單與關閉前檢查），每個小功能議題都會詢問使用者描述是否有補充內容，所有議題描述最後都會依描述內容產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），會把議題移到「待處理」欄位（不往回移、Gitea 介面不支援時改列建議清單請使用者手動拖曳）；最後依到期日與相依關係排序小功能議題並把排序結果留言到保存議題。本 skill 到「議題拆分完成＋排序留言」為止，**不實作程式碼**（不修改原始碼、不 commit、不 push、不開 PR），實作交由 `/jsc-code:issues`。所有中間成果都不落地成草稿檔，一律使用 `tea` 或 Gitea API 保存到議題描述或留言。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、或提到 issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill；要產出需求／交付文件檔案時改用 issues-analyze-to-file。 -- **Claude Code / Antigravity**：`/jsc:doc-issues-analyze` -- **Codex**：`$doc-issues-analyze`，或用 `/skills` 選單 +- **Claude Code / Antigravity**：`/jsc-doc:issues-analyze` +- **Codex**：`$issues-analyze`，或用 `/skills` 選單 - **OpenCode**：描述需求自動觸發 -### `doc-issues-sync` +### `issues-sync` -讀取一個 Gitea 專案（project）或單一議題（優先用 `tea`，否則用 Gitea REST API + `curl` + `GITEA_TOKEN`，不依賴 `jq`）；輸入是專案時因 tea／Gitea API 無法直接查詢專案，改先取得該 repo 所有開啟中的議題、再過濾掉與此專案無關的議題，輸入是議題就只同步該議題，找不到目標時以 AskUserQuestion 請使用者補齊。議題若有標籤就依標籤分組、以 AskUserQuestion（多選）讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，**以工作目錄下的所有檔案為依據**：判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補 TODO 追加到正文、依需求從既有標籤更新議題標籤、逐條勾稽未完成 TODO（含新增）是否已完成、有異動就整理成一則留言；若議題屬於專案看板且看板欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），依議題描述與勾稽結果建議議題應在的欄位，經確認後移動（Gitea 介面不支援 project 欄位操作時改列建議清單請使用者手動拖曳）。若輸入為專案且使用者明確指定「關閉專案／專案完成」，進入專案完成模式：只執行到取得專案議題清單，跳過其後所有同步步驟，列出議題清單（含仍有未完成 TODO 者）經使用者確認後，把專案擁有的所有議題搬到「已完成」欄位並關閉，單筆失敗不中斷整批並於回報列出。全程不落地任何檔案（不建立 `.docs/`、不寫草稿檔），所有中間成果只留在對話／subagent 回傳，最終只透過 tea 或 Gitea API 寫回議題正文／標籤／留言，且寫入前先以 AskUserQuestion 讓使用者確認執行方式。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、Gitea 專案議題時使用此 skill。 +讀取一個 Gitea 專案（project）或單一議題（優先用 `tea`，否則用 Gitea REST API + `curl` + `GITEA_TOKEN`，不依賴 `jq`）；輸入是專案時因 tea／Gitea API 無法直接查詢專案，改先取得該 repo 所有開啟中的議題、再過濾掉與此專案無關的議題，輸入是議題就只同步該議題，找不到目標時以 AskUserQuestion 請使用者補齊。議題若有標籤就依標籤分組、以 AskUserQuestion（多選）讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，**以工作目錄下的所有檔案為依據**：判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補 TODO 追加到正文、依需求從既有標籤更新議題標籤、逐條勾稽未完成 TODO（含新增）是否已完成、有異動就整理成一則留言；若議題屬於專案看板且看板欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），依議題描述與勾稽結果建議議題應在的欄位，經確認後移動（Gitea 介面不支援 project 欄位操作時改列建議清單請使用者手動拖曳）。若輸入為專案且使用者明確指定「關閉專案／專案完成」，進入專案完成模式：只執行到取得專案議題清單，跳過其後所有同步步驟，列出議題清單（含仍有未完成 TODO 者）經使用者確認後，把專案擁有的所有議題搬到「已完成」欄位並關閉，單筆失敗不中斷整批並於回報列出。全程不落地任何檔案（不建立 `.docs/`、不寫草稿檔），所有中間成果只留在對話／subagent 回傳，最終只透過 tea 或 Gitea API 寫回議題正文／標籤／留言，且寫入前先以 AskUserQuestion 讓使用者確認執行方式。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 issues-sync、issue sync、議題同步、TODO 勾稽、Gitea 專案議題時使用此 skill。 -- **Claude Code / Antigravity**：`/jsc:doc-issues-sync` -- **Codex**：`$doc-issues-sync`，或用 `/skills` 選單 +- **Claude Code / Antigravity**：`/jsc-doc:issues-sync` +- **Codex**：`$issues-sync`，或用 `/skills` 選單 - **OpenCode**：描述需求自動觸發 ### `worklog` 工作證明自動記錄與手動維護流程。相容的 `Stop` hook 會把每輪工作透過 `WORKLOG_CLI` 指定的 headless CLI 整理成六個固定欄位：專案/任務名稱、執行細節與產出、花費時間、任務狀態、遇到的困難、解決方式，並追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`）。手動模式提供 `--init`、`--tune`（Claude Code 專屬）、`--diagnose`、`--append`、`--show`。 -- **Claude Code / Antigravity**：`/jsc:worklog --diagnose` +- **Claude Code / Antigravity**：`/jsc-doc:worklog --diagnose` - **Codex**：`$worklog --diagnose`，或用 `/skills` 選單 - **OpenCode / GitHub Copilot**：需完整 plugin 目錄保留 `scripts/`；可用 `WORKLOG_CLI=opencode` 或 `WORKLOG_CLI=copilot` 作為摘要 CLI @@ -269,16 +269,16 @@ copilot plugin marketplace remove doc ## 新增一個 skill -1. 複製既有 skill 作範本：`cp -r skills/doc-docker skills/` +1. 複製既有 skill 作範本：`cp -r skills/docker skills/` 2. 編輯 `skills//SKILL.md` 的 frontmatter： - - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc:`**。 + - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc-doc:`**。 - `description`：第三人稱，寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。 3. 在內文寫下 skill 的具體步驟。 4. 手動把這個 skill 補進上方「Skills 目錄」區塊。 5. **bump 版本並 push**：各助理都以 git 內容/版本判斷更新，請把 `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` 三個 manifest 的 `version` 一起 bump，commit 後 push 到 gitea。 6. 讓各助理更新： - - Claude：`claude plugin update jsc@doc` + - Claude：`claude plugin update jsc-doc@doc` - Codex：`codex plugin marketplace upgrade doc` - - Antigravity：`git -C ~/jsc-plugin pull && agy plugin uninstall jsc && agy plugin install ~/jsc-plugin` + - Antigravity：`git -C ~/jsc-plugin pull && agy plugin uninstall jsc-doc && agy plugin install ~/jsc-plugin` - OpenCode：`git pull` 後重新複製 `skills/` - - Copilot：`copilot plugin marketplace update doc && copilot plugin update jsc@doc` + - Copilot：`copilot plugin marketplace update doc && copilot plugin update jsc-doc@doc` diff --git a/hooks/hooks.json b/hooks/hooks.json index 6eab4fe..c6140c0 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -1,27 +1,11 @@ { "hooks": { - "SessionStart": [ - { - "hooks": [ - { - "type": "command", - "command": "rel='scripts/role/role_load.sh'; own='generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", - "timeout": 20 - } - ] - } - ], "Stop": [ { "hooks": [ { "type": "command", - "command": "rel='scripts/worklog/worklog.sh'; own='doc'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", - "timeout": 60 - }, - { - "type": "command", - "command": "rel='scripts/role/role_capture.sh'; own='generic'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/jsc\" \"$base\"; do s=$(find \"$dir\" -path \"*/jsc/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", + "command": "rel='scripts/worklog/worklog.sh'; own='doc'; plug='jsc-doc'; root=\"${CLAUDE_PLUGIN_ROOT:-}\"; if [ -n \"$root\" ] && [ -f \"$root/$rel\" ]; then exec \"$root/$rel\"; fi; for base in \"$HOME/.claude/plugins/cache\" \"$HOME/.codex/plugins/cache\"; do for dir in \"$base/$own/$plug\" \"$base\"; do s=$(find \"$dir\" -path \"*/$plug/*/$rel\" -type f 2>/dev/null | sort -V | tail -n 1); if [ -n \"$s\" ]; then exec \"$s\"; fi; done; done; exit 0", "timeout": 60 } ] diff --git a/plugin.json b/plugin.json index aac913d..480bf41 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { - "name": "jsc", - "version": "0.2.6", - "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。", + "name": "jsc-doc", + "version": "0.2.7", + "description": "JSC 文件化 skills：docker 會整理 docker-compose.yaml 的行內註解與標題日期；funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-doc: 前綴呼叫。", "skills": "./skills/" } diff --git a/scripts/worklog/wiki_api.py b/scripts/worklog/wiki_api.py index 0b43b9b..61df289 100755 --- a/scripts/worklog/wiki_api.py +++ b/scripts/worklog/wiki_api.py @@ -2,7 +2,7 @@ # ============================================================================== # 用途：Gitea Wiki 讀寫工具（worklog 專用）。提供 token 解析、頁面讀取、 # 建立、append 追加（read-modify-write + 寫後驗證重試），供 worklog.sh -# 與 /jsc:worklog skill 共用，避免兩份實作漂移。 +# 與 /jsc-doc:worklog skill 共用，避免兩份實作漂移。 # 更新時間：2026/07/27 11:14:16 # 相依：Python 3 標準庫（urllib、base64、json、re）。不需 requests、不需 jq。 # 機密：token 一律從環境變數或本機憑證檔讀取，絕不輸出、絕不寫入任何檔案。 diff --git a/scripts/worklog/worklog.sh b/scripts/worklog/worklog.sh index 1b01cae..4362ec5 100755 --- a/scripts/worklog/worklog.sh +++ b/scripts/worklog/worklog.sh @@ -207,7 +207,7 @@ if [ "$SUMMARY_CLI" = "claude" ]; then if [ -n "$(find "$MODEL_CACHE" -mtime "+${CACHE_MAX_AGE_DAYS}" 2>/dev/null)" ]; then MODEL="$FALLBACK_MODEL" MODEL_NOTE=" (cli: claude, model: fallback)" - log "WRN" "模型快取已超過 ${CACHE_MAX_AGE_DAYS} 天，改用保底模型，建議重跑 /jsc:worklog --tune" + log "WRN" "模型快取已超過 ${CACHE_MAX_AGE_DAYS} 天，改用保底模型，建議重跑 /jsc-doc:worklog --tune" else MODEL="$(grep -m1 -E '^model=' "$MODEL_CACHE" 2>/dev/null | cut -d= -f2- | tr -d '[:space:]')" fi @@ -215,7 +215,7 @@ if [ "$SUMMARY_CLI" = "claude" ]; then if [ -z "$MODEL" ]; then MODEL="$FALLBACK_MODEL" MODEL_NOTE=" (cli: claude, model: fallback)" - log "WRN" "無模型快取，改用保底模型，建議執行 /jsc:worklog --tune" + log "WRN" "無模型快取，改用保底模型，建議執行 /jsc-doc:worklog --tune" elif [ -z "$MODEL_NOTE" ]; then MODEL_NOTE=" (cli: claude)" fi diff --git a/skills/doc-docker/SKILL.md b/skills/docker/SKILL.md similarity index 96% rename from skills/doc-docker/SKILL.md rename to skills/docker/SKILL.md index d588ef7..2a3c2a8 100644 --- a/skills/doc-docker/SKILL.md +++ b/skills/docker/SKILL.md @@ -1,5 +1,5 @@ --- -name: doc-docker +name: docker description: 整理並對齊 docker-compose.yaml 的行內註解與標題區塊。當使用者要對齊 docker-compose 註解、整理 compose 檔註解欄位、更新 compose 標題日期，或提到 docker-compose、dc-tidy、align_comments、註解對齊時使用此 skill。 --- @@ -7,7 +7,7 @@ description: 整理並對齊 docker-compose.yaml 的行內註解與標題區塊 整理並對齊 `docker-compose.yaml` 的行內註解與標題。請優先使用自動化腳本執行。 -以下範例中的 `skill_dir` 是本 skill 所在目錄，也就是包含此 `SKILL.md` 與 `scripts/` 的資料夾。不要假設目標專案內存在 `plugins/skills/doc-docker/`。 +以下範例中的 `skill_dir` 是本 skill 所在目錄，也就是包含此 `SKILL.md` 與 `scripts/` 的資料夾。不要假設目標專案內存在 `plugins/skills/docker/`。 ## 全專案批次處理（未指定檔案時） diff --git a/skills/doc-docker/scripts/align_comments.sh b/skills/docker/scripts/align_comments.sh similarity index 100% rename from skills/doc-docker/scripts/align_comments.sh rename to skills/docker/scripts/align_comments.sh diff --git a/skills/doc-docker/scripts/awk/align_col.awk b/skills/docker/scripts/awk/align_col.awk similarity index 100% rename from skills/doc-docker/scripts/awk/align_col.awk rename to skills/docker/scripts/awk/align_col.awk diff --git a/skills/doc-docker/scripts/awk/find_col.awk b/skills/docker/scripts/awk/find_col.awk similarity index 100% rename from skills/doc-docker/scripts/awk/find_col.awk rename to skills/docker/scripts/awk/find_col.awk diff --git a/skills/doc-docker/scripts/awk/strip_col.awk b/skills/docker/scripts/awk/strip_col.awk similarity index 100% rename from skills/doc-docker/scripts/awk/strip_col.awk rename to skills/docker/scripts/awk/strip_col.awk diff --git a/skills/doc-docker/scripts/awk/verify_col.awk b/skills/docker/scripts/awk/verify_col.awk similarity index 100% rename from skills/doc-docker/scripts/awk/verify_col.awk rename to skills/docker/scripts/awk/verify_col.awk diff --git a/skills/doc-docker/scripts/fix_comments.sh b/skills/docker/scripts/fix_comments.sh similarity index 100% rename from skills/doc-docker/scripts/fix_comments.sh rename to skills/docker/scripts/fix_comments.sh diff --git a/skills/doc-funcs/SKILL.md b/skills/funcs/SKILL.md similarity index 94% rename from skills/doc-funcs/SKILL.md rename to skills/funcs/SKILL.md index 1e9b7ca..59ef245 100644 --- a/skills/doc-funcs/SKILL.md +++ b/skills/funcs/SKILL.md @@ -1,6 +1,6 @@ --- -name: doc-funcs -description: 先判斷專案語言，再為每個 function 與每個指令檔（腳本／CI／部署設定檔）建立 .docs/ 草稿並補齊註解，並整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿；由使用者選擇實作方式後寫回原始碼／覆蓋指令檔／更新 workflow readme，並依專案內多數檔案的大小寫命名慣例正規化 Dockerfile 與 README 檔名（含同步更新引用），接著保守優化被文件化原始碼的效能（排版依原本方式維持原樣，僅修正有誤處），最後重建 README 專案列表、功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、為腳本或 CI/部署設定檔逐行加註解、整理 workflow README、建立 .docs 草稿，或提到 doc-funcs、function 文件化、指令檔註解、workflow 文件化、XML documentation comments 時使用此 skill。 +name: funcs +description: 先判斷專案語言，再為每個 function 與每個指令檔（腳本／CI／部署設定檔）建立 .docs/ 草稿並補齊註解，並整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿；由使用者選擇實作方式後寫回原始碼／覆蓋指令檔／更新 workflow readme，並依專案內多數檔案的大小寫命名慣例正規化 Dockerfile 與 README 檔名（含同步更新引用），接著保守優化被文件化原始碼的效能（排版依原本方式維持原樣，僅修正有誤處），最後重建 README 專案列表、功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、為腳本或 CI/部署設定檔逐行加註解、整理 workflow README、建立 .docs 草稿，或提到 funcs、function 文件化、指令檔註解、workflow 文件化、XML documentation comments 時使用此 skill。 --- # 補齊 function 與指令檔文件 @@ -11,9 +11,9 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、subagent 提示需帶入本規範。 -- `/jsc:spec-execution`：不臆測／需人工確認、不擴及無關檔案（generated/bin/obj/.git/.docs 與第三方依賴）。 -- `/jsc:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、輸出訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 +- `/jsc-generic:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、subagent 提示需帶入本規範。 +- `/jsc-generic:spec-execution`：不臆測／需人工確認、不擴及無關檔案（generated/bin/obj/.git/.docs 與第三方依賴）。 +- `/jsc-generic:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、輸出訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 ## 第 0 步：先判斷語言與生態 @@ -109,7 +109,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ - workflow README 草稿：用草稿內容**覆蓋 `.gitea/workflows/readme.md`**，保留 workflow 實際設定不變，僅整理成說明文件。 - 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。 - 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。 -- 輸出訊息格式：依 `/jsc:spec-time-log` — 若該 function 或指令檔有輸出訊息，統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱不翻譯；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；時間 Asia/Taipei）；區塊階段命名（`#region`／橫幅段落名稱作為 `階段` 前綴並移除包裹／橫幅本身、僅移除標記保留指令與行為）、檔案標頭保留例外、一行一則規則皆依該 spec。調整僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。 +- 輸出訊息格式：依 `/jsc-generic:spec-time-log` — 若該 function 或指令檔有輸出訊息，統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱不翻譯；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；時間 Asia/Taipei）；區塊階段命名（`#region`／橫幅段落名稱作為 `階段` 前綴並移除包裹／橫幅本身、僅移除標記保留指令與行為）、檔案標頭保留例外、一行一則規則皆依該 spec。調整僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。 ## 第 7 步：實作註解後，保守優化效能並僅修正有誤的排版 @@ -172,6 +172,6 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do - function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。 - 排版一律依照檔案原本的排版方式；只有排版確實有誤（縮排錯亂、tab／空白混用致錯、對齊錯誤造成誤讀、編碼／行尾異常）才修正該處，不得全檔重排、不得套用 formatter 改變原有風格。 - 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內，且格式依本 skill 的 `templates/command-header.md` 範本。 -- function 或指令檔若有輸出訊息，訊息格式、區塊階段命名、檔案標頭保留與一行一則規則一律依 `/jsc:spec-time-log`，且不得藉此改變訊息反映的實際行為。 +- function 或指令檔若有輸出訊息，訊息格式、區塊階段命名、檔案標頭保留與一行一則規則一律依 `/jsc-generic:spec-time-log`，且不得藉此改變訊息反映的實際行為。 - 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。 -- 原始碼註解與 README 的語言依 `/jsc:spec-output`（繁體中文為主；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文）。 +- 原始碼註解與 README 的語言依 `/jsc-generic:spec-output`（繁體中文為主；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文）。 diff --git a/skills/doc-funcs/templates/command-header.md b/skills/funcs/templates/command-header.md similarity index 86% rename from skills/doc-funcs/templates/command-header.md rename to skills/funcs/templates/command-header.md index 9d6e099..f3de219 100644 --- a/skills/doc-funcs/templates/command-header.md +++ b/skills/funcs/templates/command-header.md @@ -1,6 +1,6 @@ # 指令檔開頭「用途／更新時間」標頭範本 -本範本定義 doc-funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 `階段` 前綴。 +本範本定義 funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 `階段` 前綴。 ## 佔位符 diff --git a/skills/doc-issues-analyze-to-file/SKILL.md b/skills/issues-analyze-to-file/SKILL.md similarity index 88% rename from skills/doc-issues-analyze-to-file/SKILL.md rename to skills/issues-analyze-to-file/SKILL.md index 62d9e6a..1f7622b 100644 --- a/skills/doc-issues-analyze-to-file/SKILL.md +++ b/skills/issues-analyze-to-file/SKILL.md @@ -1,6 +1,6 @@ --- -name: doc-issues-analyze-to-file -description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gitea API），彙整成一份完整**需求文件檔案**，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑／專案，依需求性質填入標籤），再配合使用者指定的 repositories 或 issue 所在 repo 產生**實作草稿檔**，最後產出**交付文件檔**並依 issues 分組留言到對應 issue；本 skill 以「先落地草稿檔、經使用者確認再寫回 Gitea」為核心，適合需要保留需求文件與交付文件檔案的流程。當使用者明確要「產出需求文件／實作草稿／交付文件檔案」的 issue 分析、或提到 doc-issues-analyze-to-file、issue 需求分析文件、issue 拆階段交付文件時使用此 skill。不適用於：全程不落地檔案、以議題描述與留言保存中間成果的需求拆分（用 doc-issues-analyze）；實作議題程式碼（用 code-issues）。兩者都可能符合、使用者未指明時，先詢問要「檔案交付」還是「議題留言」再選擇。 +name: issues-analyze-to-file +description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gitea API），彙整成一份完整**需求文件檔案**，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑／專案，依需求性質填入標籤），再配合使用者指定的 repositories 或 issue 所在 repo 產生**實作草稿檔**，最後產出**交付文件檔**並依 issues 分組留言到對應 issue；本 skill 以「先落地草稿檔、經使用者確認再寫回 Gitea」為核心，適合需要保留需求文件與交付文件檔案的流程。當使用者明確要「產出需求文件／實作草稿／交付文件檔案」的 issue 分析、或提到 issues-analyze-to-file、issue 需求分析文件、issue 拆階段交付文件時使用此 skill。不適用於：全程不落地檔案、以議題描述與留言保存中間成果的需求拆分（用 issues-analyze）；實作議題程式碼（用 issues）。兩者都可能符合、使用者未指明時，先詢問要「檔案交付」還是「議題留言」再選擇。 --- # 分析 Issue 並拆解為實作階段與交付留言 @@ -11,9 +11,9 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 -- `/jsc:spec-execution`：不臆測／需人工確認、不擴及無關檔案。 -- `/jsc:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（`Authorization: token`、分頁完整讀取）。 +- `/jsc-generic:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 +- `/jsc-generic:spec-execution`：不臆測／需人工確認、不擴及無關檔案。 +- `/jsc-generic:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（`Authorization: token`、分頁完整讀取）。 ## 前置：輸入與工具 @@ -21,9 +21,9 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite - **工具優先序**： 1. 若該 issue host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment` 等），並以 `--login --repo /` 指定目標。 2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定）。 -- **不要依賴 `jq`**：依 `/jsc:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 +- **不要依賴 `jq`**：依 `/jsc-generic:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 - **工作目錄**：所有草稿與文件放在 `.docs/doc-issues-analyze-to-file/`。 -- **議題描述流程圖**：依 `/jsc:spec-output` — 產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，有助理解就加入 Mermaid 流程圖（處理流程、狀態轉移、階段相依關係），忠實反映需求與拆分結果、不得杜撰。 +- **議題描述流程圖**：依 `/jsc-generic:spec-output` — 產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，有助理解就加入 Mermaid 流程圖（處理流程、狀態轉移、階段相依關係），忠實反映需求與拆分結果、不得杜撰。 ## 第 0 步：解析 issue URL 與準備工具 @@ -130,5 +130,5 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite - 建立 issue 與留言是對外且不易復原的動作，**必須先經第 6 步使用者確認**；未確認前只產生本機草稿。 - 新 issue 一律沿用來源 issue 的里程碑與專案；標籤只從既有標籤中依需求性質挑選，不自行新建（除非使用者要求）。 - subagent 與各步驟只讀程式碼與 issue、只寫 `.docs/` 草稿，**不得修改任何原始碼**；本 skill 的產出是需求文件、階段 issue、實作草稿與交付留言，不含改動程式邏輯。 -- JSON 解析（不依賴 `jq`）依 `/jsc:spec-gitea`；個資保護（PII）與語言規範依 `/jsc:spec-output`。 +- JSON 解析（不依賴 `jq`）依 `/jsc-generic:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-generic:spec-output`。 - 需求、階段與實作草稿若無法可靠推論，一律保守描述並標註「需人工確認」，不得編造 issue 未提及的內容。 diff --git a/skills/doc-issues-analyze/SKILL.md b/skills/issues-analyze/SKILL.md similarity index 87% rename from skills/doc-issues-analyze/SKILL.md rename to skills/issues-analyze/SKILL.md index b355601..3291c78 100644 --- a/skills/doc-issues-analyze/SKILL.md +++ b/skills/issues-analyze/SKILL.md @@ -1,20 +1,20 @@ --- -name: doc-issues-analyze -description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取，附件內容一併納入需求分析），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，在產生保存議題前必須完整釐清需求、任何不清楚的部分都要詢問使用者、絕不臆測或編造，確認清楚後才將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時母議題必須所有子議題關閉後才可關閉，優先以 issue dependency 阻擋），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中/待處理/進行中/待測試/已完成），把議題移到「待處理」欄位（不往回移、介面不支援時改列建議清單請人工調整）；最後依到期日與相依關係排序小功能議題並把排序結果留言到保存議題。本 skill 到「議題拆分完成＋排序留言」為止，**不實作程式碼**（不修改原始碼、不 commit、不 push、不開 PR），實作交由 /jsc:code-issues。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。不適用於：實作議題程式碼（用 code-issues）、要把彙整結果與實作草稿落地成文件檔案交付的流程（用 doc-issues-analyze-to-file；本 skill 全程不落地任何檔案）。 +name: issues-analyze +description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取，附件內容一併納入需求分析），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，在產生保存議題前必須完整釐清需求、任何不清楚的部分都要詢問使用者、絕不臆測或編造，確認清楚後才將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時母議題必須所有子議題關閉後才可關閉，優先以 issue dependency 阻擋），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中/待處理/進行中/待測試/已完成），把議題移到「待處理」欄位（不往回移、介面不支援時改列建議清單請人工調整）；最後依到期日與相依關係排序小功能議題並把排序結果留言到保存議題。本 skill 到「議題拆分完成＋排序留言」為止，**不實作程式碼**（不修改原始碼、不 commit、不 push、不開 PR），實作交由 /jsc-code:issues。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、或提到 issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。不適用於：實作議題程式碼（用 issues）、要把彙整結果與實作草稿落地成文件檔案交付的流程（用 issues-analyze-to-file；本 skill 全程不落地任何檔案）。 --- # 分析多來源需求並保存為議題 -你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日與相依關係排序，並把排序結果留言到保存議題；**本 skill 不實作程式碼**——不修改原始碼、不 commit、不 push、不開 PR，後續實作交由 `/jsc:code-issues` 或使用者另行處理。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。 +你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日與相依關係排序，並把排序結果留言到保存議題；**本 skill 不實作程式碼**——不修改原始碼、不 commit、不 push、不開 PR，後續實作交由 `/jsc-code:issues` 或使用者另行處理。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。 ## 共用規範（generic plugin，必要前置） 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、表格／Mermaid 呈現、個資（PII）去識別化。 -- `/jsc:spec-execution`：不臆測／需人工確認、已知資訊跳過詢問。 -- `/jsc:spec-gitea`：tea／API 工具選擇與檢查、`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 分頁完整讀取。 -- `/jsc:spec-project-board`：看板欄位語意對應、GET 探測（404／501 不支援）、不往回移、不得新建欄位。 +- `/jsc-generic:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、表格／Mermaid 呈現、個資（PII）去識別化。 +- `/jsc-generic:spec-execution`：不臆測／需人工確認、已知資訊跳過詢問。 +- `/jsc-generic:spec-gitea`：tea／API 工具選擇與檢查、`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 分頁完整讀取。 +- `/jsc-generic:spec-project-board`：看板欄位語意對應、GET 探測（404／501 不支援）、不往回移、不得新建欄位。 ## 絕對準則（不可違反） @@ -28,7 +28,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 - **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。 - **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。 - **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，程式碼分析參考（僅供研究、補充議題描述，不修改）以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。 -- **工具選擇**：依 `/jsc:spec-gitea` 的工具選擇流程（檢查 `tea`／`tea login list`／`GITEA_TOKEN` 後詢問使用者用 `tea` 或 `api`；已明確指定工具時才可跳過詢問；不依賴 `jq`，JSON 改用 tea 結構化輸出或交給 subagent 解析）。 +- **工具選擇**：依 `/jsc-generic:spec-gitea` 的工具選擇流程（檢查 `tea`／`tea login list`／`GITEA_TOKEN` 後詢問使用者用 `tea` 或 `api`；已明確指定工具時才可跳過詢問；不依賴 `jq`，JSON 改用 tea 結構化輸出或交給 subagent 解析）。 - **議題必須連同留言與附件一起讀取**：處理任何議題（含專案底下展開的議題）時，除了 `title`／`body` 等欄位，必須一併讀取**所有留言（comments）**與**所有附件（attachments/assets，含議題本身與各留言的附件）**，其內容都是需求分析的依據： - 附件清單：`tea` 目前沒有附件指令，一律走 API — 議題附件 `GET {base}/repos/{owner}/{repo}/issues/{index}/assets`、留言附件 `GET {base}/repos/{owner}/{repo}/issues/comments/{id}/assets`，取得每個附件的檔名、類型與下載 URL。 - 文字類附件（Markdown、純文字、CSV、JSON 等）：以 `curl` 直接取得內容到對話中分析，不落地。 @@ -36,11 +36,11 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 - 無法讀取的格式（或僅有 `tea` 而無 token 可下載附件）：在保存議題內容中列出附件檔名與 URL 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容。 - **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。 - **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。 -- **議題描述流程圖**：依 `/jsc:spec-output` — 產生保存議題或小功能議題的描述時，有助理解就加入 Mermaid 流程圖（需求流程、狀態轉移、相依／阻擋關係），忠實反映需求與拆分結果、不得杜撰。 +- **議題描述流程圖**：依 `/jsc-generic:spec-output` — 產生保存議題或小功能議題的描述時，有助理解就加入 Mermaid 流程圖（需求流程、狀態轉移、相依／阻擋關係），忠實反映需求與拆分結果、不得杜撰。 ## 第 1 步：工具可用性檢查與使用方式選擇 -依 `/jsc:spec-gitea` 的工具選擇流程執行：檢查 `tea`（`command -v tea`、`tea login list`，失敗記錄原因不中止）與 `GITEA_TOKEN`（只輸出「已設定／未設定」）→ 詢問使用者要用 `tea` 或 `api`（除非使用者已明確指定，不得自行決定；選 `tea` 後續仍需確認來源 host 有對應 login）→ 兩種方式都不可用則停止並回報缺少 `tea login` 或 `GITEA_TOKEN`（不要要求使用者把 token 貼進對話）。 +依 `/jsc-generic:spec-gitea` 的工具選擇流程執行：檢查 `tea`（`command -v tea`、`tea login list`，失敗記錄原因不中止）與 `GITEA_TOKEN`（只輸出「已設定／未設定」）→ 詢問使用者要用 `tea` 或 `api`（除非使用者已明確指定，不得自行決定；選 `tea` 後續仍需確認來源 host 有對應 login）→ 兩種方式都不可用則停止並回報缺少 `tea login` 或 `GITEA_TOKEN`（不要要求使用者把 token 貼進對話）。 ## 第 2 步：選擇讀取來源、讀取內容並保存議題內容 @@ -125,7 +125,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 **分析完成後：把議題移到看板「待處理」欄位**。保存議題與所有小功能議題都建立／更新完成後（即分析階段結束），對其中**確實屬於某個專案看板（project board）**的議題調整進度欄位： -- 依 `/jsc:spec-project-board` 執行（欄位語意以看板實際名稱為準、不往回移、先 GET 探測端點且 404／501 視為不支援、不得對未確認端點寫入、不得新建欄位）：把議題移動到「待處理」欄位，代表需求分析已完成、等待實作；議題已在「待處理」或更後面的欄位時維持原欄位。 +- 依 `/jsc-generic:spec-project-board` 執行（欄位語意以看板實際名稱為準、不往回移、先 GET 探測端點且 404／501 視為不支援、不得對未確認端點寫入、不得新建欄位）：把議題移動到「待處理」欄位，代表需求分析已完成、等待實作；議題已在「待處理」或更後面的欄位時維持原欄位。 - 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳。 ## 第 4 步：依到期日排序並交棒實作 @@ -135,5 +135,5 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 **本 skill 的範圍到「議題拆分完成＋排序留言」為止，不實作程式碼**：不修改任何原始碼、不 commit、不 push、不開 PR、不關閉議題。排序留言完成後： - 回報整體結果：保存議題連結、小功能議題清單（標題／到期日／相依關係）、看板欄位調整狀況、標註「需人工確認」的項目。 -- 提示使用者後續可用 `/jsc:code-issues` 對這些小功能議題逐項實作（該 skill 會彙整 TODO、逐項實作並留言進度）；是否實作、何時實作由使用者另行決定，不在本 skill 範圍內。 +- 提示使用者後續可用 `/jsc-code:issues` 對這些小功能議題逐項實作（該 skill 會彙整 TODO、逐項實作並留言進度）；是否實作、何時實作由使用者另行決定，不在本 skill 範圍內。 - **子母議題關閉規則的後續遵守**：提醒使用者（或後續實作流程）——子議題全部關閉前不得關閉母議題；有 dependency 阻擋時由 Gitea 強制，否則依母議題的「關閉前檢查」人工確認。 diff --git a/skills/doc-issues-sync/SKILL.md b/skills/issues-sync/SKILL.md similarity index 88% rename from skills/doc-issues-sync/SKILL.md rename to skills/issues-sync/SKILL.md index 6c3daf2..5926bfe 100644 --- a/skills/doc-issues-sync/SKILL.md +++ b/skills/issues-sync/SKILL.md @@ -1,6 +1,6 @@ --- -name: doc-issues-sync -description: 讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；若給的是專案，因 tea／Gitea API 目前無法直接查詢專案，就先取得該 repo 底下所有開啟中的議題、再過濾掉與此專案無關的議題；若給的是議題就只同步該議題。議題若有標籤就依標籤分組並以 AskUserQuestion 讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，基於工作目錄下的所有檔案：分析議題描述的需求並判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補上 TODO 追加到議題正文、依需求從既有標籤更新議題標籤、逐條判斷未完成 TODO（含新增）是否已完成、有異動就整理成一則留言；若議題屬於專案看板且看板欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），依議題描述與勾稽結果建議並調整議題所在欄位，介面不支援時改列建議清單請使用者手動調整。若輸入為專案且使用者指定「關閉專案」或「專案完成」，則進入專案完成模式：只執行到取得專案議題清單，跳過其後所有同步步驟，經使用者確認後把專案擁有的所有議題搬到「已完成」欄位並關閉。全程不落地任何檔案：所有中間成果一律留在對話／subagent 回傳內容，最終只透過 tea 或 Gitea API 寫回議題正文／標籤／留言，且寫入前先經使用者確認。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。 +name: issues-sync +description: 讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；若給的是專案，因 tea／Gitea API 目前無法直接查詢專案，就先取得該 repo 底下所有開啟中的議題、再過濾掉與此專案無關的議題；若給的是議題就只同步該議題。議題若有標籤就依標籤分組並以 AskUserQuestion 讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，基於工作目錄下的所有檔案：分析議題描述的需求並判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補上 TODO 追加到議題正文、依需求從既有標籤更新議題標籤、逐條判斷未完成 TODO（含新增）是否已完成、有異動就整理成一則留言；若議題屬於專案看板且看板欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），依議題描述與勾稽結果建議並調整議題所在欄位，介面不支援時改列建議清單請使用者手動調整。若輸入為專案且使用者指定「關閉專案」或「專案完成」，則進入專案完成模式：只執行到取得專案議題清單，跳過其後所有同步步驟，經使用者確認後把專案擁有的所有議題搬到「已完成」欄位並關閉。全程不落地任何檔案：所有中間成果一律留在對話／subagent 回傳內容，最終只透過 tea 或 Gitea API 寫回議題正文／標籤／留言，且寫入前先經使用者確認。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。 --- # 依工作目錄同步 Gitea 專案／議題的 TODO 進度與標籤 @@ -11,10 +11,10 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 -- `/jsc:spec-execution`：不臆測／需人工確認。 -- `/jsc:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（分頁完整讀取、GET 探測版本相依端點）。 -- `/jsc:spec-project-board`：看板欄位語意對應與建議欄位規則、404／501 視為不支援、不得新建欄位。 +- `/jsc-generic:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 +- `/jsc-generic:spec-execution`：不臆測／需人工確認。 +- `/jsc-generic:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（分頁完整讀取、GET 探測版本相依端點）。 +- `/jsc-generic:spec-project-board`：看板欄位語意對應與建議欄位規則、404／501 視為不支援、不得新建欄位。 ## 絕對準則（不可違反） @@ -27,10 +27,10 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t - **工具優先序**： 1. 若該 host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment`、`tea labels` 等），並以 `--login --repo /` 指定目標。 2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定；未設定則停下請使用者提供）。 -- **不要依賴 `jq`**：依 `/jsc:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 +- **不要依賴 `jq`**：依 `/jsc-generic:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 - **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。 -- **專案進度欄位（project column）**：依 `/jsc:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。 -- **議題描述流程圖**：依 `/jsc:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。 +- **專案進度欄位（project column）**：依 `/jsc-generic:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。 +- **議題描述流程圖**：依 `/jsc-generic:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。 ## 第 0 步：解析輸入、判斷專案或議題、準備工具 @@ -90,7 +90,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t 3. **3.2 依需求更新可用標籤**：依議題需求性質，從該 repo **既有標籤**中挑選應掛上（或應移除）的標籤，回傳內容中列出「建議的標籤異動」（新增哪些、移除哪些、維持哪些）。**不自行新建標籤**，除非使用者要求；找不到合適標籤就維持原樣並標註。 4. **3.3 逐條勾稽未完成 TODO 是否已完成**：對所有**未完成**的 TODO（含 3.1 新增的），逐條依工作目錄下的檔案內容判斷是否已完成。已完成者標記為 `- [x]` 並在回傳內容記下判斷依據（以 `path:line` 指出對應實作位置）；無法從檔案可靠判斷者維持未完成並標註「需人工確認」。 5. **3.4 整理 TODO 異動留言**：若本議題有任何 TODO 異動（**新增**的 TODO，或**狀態變更**——由未完成改為完成），整理成一則留言內容，包含：本次新增了哪些 TODO、哪些 TODO 判定為完成（附對應實作位置）、哪些仍未完成（含原因／需人工確認）。若沒有任何 TODO 異動，回傳標明「無異動、不需留言」。 -6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。 +6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc-generic:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。 回傳內容需含：目前欄位、建議欄位、判斷依據。建議欄位與目前欄位相同時標明「欄位無異動」；看板欄位語意對不上（或取不到欄位資訊）時標明「無法對應、維持原欄位」並列出實際欄位名稱，不得硬套。議題不屬於任何專案看板時跳過本項。 每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案**），至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言內容（或「無異動」）、專案進度欄位建議（目前欄位／建議欄位／判斷依據，或「不屬於專案看板」「無法對應」）、以及所有「需人工確認」項目。 @@ -127,7 +127,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t - 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。 - **標籤異動**：套用建議的新增／移除。 - tea：`tea labels`／issue 編輯對應指令；API：`POST`/`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels`（用既有 label id）。 -- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。 +- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc-generic:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。 - **留言**：對有 TODO 異動的議題張貼留言。 - tea：`tea comment --repo / --login "<留言內容>"`；API：`POST {base}/repos/{owner}/{repo}/issues/{index}/comments`，body `{"body":"<留言內容>"}`。 - 無異動的議題不留言。 @@ -146,6 +146,6 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t - 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。 - subagent 與各步驟只讀檔案與議題、只回傳結構化內容，**不得在磁碟寫任何檔案、不得修改任何工作目錄原始碼**。 - 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。 -- 進度欄位調整依 `/jsc:spec-project-board`，且必須經第 5 步使用者確認後執行。 +- 進度欄位調整依 `/jsc-generic:spec-project-board`，且必須經第 5 步使用者確認後執行。 - 專案完成模式只在輸入為專案且使用者**明確**指定關閉／完成時進入；語意不明就用 AskUserQuestion 確認，不得自行認定。批次關閉議題前必須經使用者確認；含未完成 TODO 的議題要在確認時明確標出。不得透過此模式關閉不屬於該專案的議題。 -- JSON 解析（不依賴 `jq`）依 `/jsc:spec-gitea`；個資保護（PII）與語言規範依 `/jsc:spec-output`。 +- JSON 解析（不依賴 `jq`）依 `/jsc-generic:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-generic:spec-output`。 diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index a0282a7..a7bc13d 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -1,6 +1,6 @@ --- name: worklog -description: 工作證明自動記錄（worklog）的操作與維護 skill。搭配相容的 Stop hook，把每輪工作內容透過 README 定義的 headless CLI（claude/codex/agy/opencode/copilot）濃縮成精簡條目並追加到 Gitea wiki 的當週工作紀錄頁（Worklog-yyyy-MM-W<週>），工作內容全程不落地。提供 --init（初始化週頁與環境變數指引）、--tune（判定並快取最適合的 Claude 摘要模型）、--diagnose（診斷 hook 為何沒動作）、--append（手動補寫一筆）、--show（讀當週頁回顧）五個模式。當使用者說工作證明、工作紀錄、worklog、週報自動化、把工作內容寫到 wiki、記錄到 Gitea wiki、hook 沒有寫入 wiki、補寫工作紀錄、看本週做了什麼、重新判定摘要模型，或提到 WORKLOG_ENABLED／WORKLOG_HOST／WORKLOG_REPO／WORKLOG_MODEL／WORKLOG_CLI／WORKLOG_SCOPE 時觸發。不適用於：Gitea 議題操作（用 doc-issues-sync／code-issues）、專案文件化（用 doc-funcs）。 +description: 工作證明自動記錄（worklog）的操作與維護 skill。搭配相容的 Stop hook，把每輪工作內容透過 README 定義的 headless CLI（claude/codex/agy/opencode/copilot）濃縮成精簡條目並追加到 Gitea wiki 的當週工作紀錄頁（Worklog-yyyy-MM-W<週>），工作內容全程不落地。提供 --init（初始化週頁與環境變數指引）、--tune（判定並快取最適合的 Claude 摘要模型）、--diagnose（診斷 hook 為何沒動作）、--append（手動補寫一筆）、--show（讀當週頁回顧）五個模式。當使用者說工作證明、工作紀錄、worklog、週報自動化、把工作內容寫到 wiki、記錄到 Gitea wiki、hook 沒有寫入 wiki、補寫工作紀錄、看本週做了什麼、重新判定摘要模型，或提到 WORKLOG_ENABLED／WORKLOG_HOST／WORKLOG_REPO／WORKLOG_MODEL／WORKLOG_CLI／WORKLOG_SCOPE 時觸發。不適用於：Gitea 議題操作（用 issues-sync／issues）、專案文件化（用 funcs）。 --- # worklog — 工作證明自動記錄 @@ -10,7 +10,7 @@ description: 工作證明自動記錄（worklog）的操作與維護 skill。搭 | 元件 | 觸發者 | 職責 | | --- | --- | --- | | `hooks/hooks.json` 的 `Stop` hook | harness 自動 | 每輪結束抽本輪內容 → 濃縮 → 遮蔽 → 追加到當週頁 | -| 本 skill `/jsc:worklog` | 使用者／助理手動 | `--init`／`--tune`／`--diagnose`／`--append`／`--show` | +| 本 skill `/jsc-doc:worklog` | 使用者／助理手動 | `--init`／`--tune`／`--diagnose`／`--append`／`--show` | | `scripts/worklog/worklog.sh` | 上述兩者共用 | 主流程（單一實作，避免漂移）：依 `WORKLOG_CLI` 呼叫 headless CLI，每筆整理成六個固定欄位 | | `scripts/worklog/wiki_api.py` | 上述兩者共用 | token 解析、wiki 讀寫、append 重試、週頁命名 | | `scripts/worklog/transcript.py` | 上述兩者共用 | 抽本輪片段、估算花費時間、機密遮蔽 | @@ -26,7 +26,7 @@ description: 工作證明自動記錄（worklog）的操作與維護 skill。搭 兩個限制的來源： -- **`Stop` hook 只有相容 hook 環境實際執行**；Claude Code 會用 `CLAUDE_PLUGIN_ROOT` 定位腳本，Codex 會從 `~/.codex/plugins/cache/doc/jsc` 找已安裝的 worklog 腳本。`transcript.py` 目前支援 Claude Code transcript JSONL（`type` / `message.content` blocks）與 Codex session JSONL（`payload` events / response items），其他助理若提供等效 hook，必須先補對應 transcript 解析器。 +- **`Stop` hook 只有相容 hook 環境實際執行**；Claude Code 會用 `CLAUDE_PLUGIN_ROOT` 定位腳本，Codex 會從 `~/.codex/plugins/cache/doc/jsc-doc` 找已安裝的 worklog 腳本。`transcript.py` 目前支援 Claude Code transcript JSONL（`type` / `message.content` blocks）與 Codex session JSONL（`payload` events / response items），其他助理若提供等效 hook，必須先補對應 transcript 解析器。 - **OpenCode 以「複製 `skills/` 目錄」安裝**時不會帶入 `scripts/`，本 skill 的所有模式都無法執行；若以完整 plugin 目錄執行並能解析 `scripts/worklog`，可用 `WORKLOG_CLI=opencode` 作為摘要 CLI。 - 其他助理若要用 `--append`／`--show` 等純 wiki 操作，只需 `python3`；摘要路徑需要 README 定義的任一 headless CLI。`--tune` 仍是 Claude Code 專屬，其他 CLI 使用各自預設模型或手動設定其 CLI 行為。 @@ -55,10 +55,10 @@ WORKLOG_DIR="/../../scripts/worklog" 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），不安裝則中斷**： -- `/jsc:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先、**寫入外部系統不得洩漏 PII**。 -- `/jsc:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。 -- `/jsc:spec-gitea`：token 機密保護（不 echo、遮蔽、不落地）、API 分頁、host 決定順序。 -- `/jsc:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 +- `/jsc-generic:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先、**寫入外部系統不得洩漏 PII**。 +- `/jsc-generic:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。 +- `/jsc-generic:spec-gitea`：token 機密保護（不 echo、遮蔽、不落地）、API 分頁、host 決定順序。 +- `/jsc-generic:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 本 skill 特有補充： @@ -170,6 +170,6 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host | 助理 | 呼叫 | | --- | --- | -| Claude Code / Antigravity | `/jsc:worklog --init`、`/jsc:worklog --tune`、`/jsc:worklog --diagnose`、`/jsc:worklog --append "修正 X 的 Y 問題"`、`/jsc:worklog --show` | +| Claude Code / Antigravity | `/jsc-doc:worklog --init`、`/jsc-doc:worklog --tune`、`/jsc-doc:worklog --diagnose`、`/jsc-doc:worklog --append "修正 X 的 Y 問題"`、`/jsc-doc:worklog --show` | | Codex | `$worklog --diagnose`，或用 `/skills` 選單；可設 `WORKLOG_CLI=codex` | | OpenCode / GitHub Copilot | 需完整 plugin 目錄保留 `scripts/`；可設 `WORKLOG_CLI=opencode` 或 `WORKLOG_CLI=copilot` | From 814e81e037c2b162183cfd4269509d6b6f3b3bee Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 28 Jul 2026 17:15:23 +0800 Subject: [PATCH 2/2] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E6=9B=B4=E5=90=8D=E8=A6=96=E7=82=BA=E6=96=B0=20plugin=EF=BC=8C?= =?UTF-8?q?=E7=89=88=E8=99=9F=E9=87=8D=E7=BD=AE=200.0.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit plugin 更名後，各助理以 @ 作為安裝識別鍵， 新名與舊名是兩筆獨立條目：舊 plugin 會被移除、新 plugin 為首次安裝， 兩者之間不存在版本比較，因此不會發生版本倒退，「版本單調遞增」不適用。 依 spec-plugin-version「新 plugin 首發 0.0.1」，三份 manifest 版號一律重置為 0.0.1， 不沿用舊名 jsc 的版本序列。 Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 38dffe1..4984572 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-doc", - "version": "0.2.7", + "version": "0.0.1", "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode / GitHub Copilot）：docker 會整理 docker-compose.yaml 的行內註解與標題日期；funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc-doc: 前綴呼叫。", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index befb0e4..f7ba4ea 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-doc", - "version": "0.2.7", + "version": "0.0.1", "description": "JSC 文件化 skills：docker 會整理 docker-compose.yaml 的行內註解與標題日期；funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki（自動 Stop hook 僅相容 hook 環境支援）。所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 480bf41..8cba799 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-doc", - "version": "0.2.7", + "version": "0.0.1", "description": "JSC 文件化 skills：docker 會整理 docker-compose.yaml 的行內註解與標題日期；funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；issues-analyze 會把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-doc: 前綴呼叫。", "skills": "./skills/" }