From 975ac7886e3d6149df69a72bcb1a4f92be3ca5f2 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 29 Jul 2026 19:09:18 +0800 Subject: [PATCH 1/5] =?UTF-8?q?fix(worklog):=20=E9=80=B1=E9=A0=81=E6=94=B9?= =?UTF-8?q?=E7=82=BA=E6=98=9F=E6=9C=9F=E5=85=AD=E8=B5=B7=E7=AE=97=EF=BC=8C?= =?UTF-8?q?=E6=8F=9B=E9=A0=81=E8=88=87=E6=98=9F=E6=9C=9F=E5=B0=8D=E9=BD=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 舊規則以 ceil(日/7) 分週，換頁點固定落在每月 8／15／22／29 號，會把同一個 工作週切成兩頁（例：2026/07/28 二 在 W4、07/29 三 卻跳到 W5）。使用者開著 舊頁時看不到新條目，會誤判成 worklog 停止記錄。 - 週以星期六起算（六～五），週頁以該週起始的星期六為錨點命名 - W 的 n ＝該星期六是當月第幾個星期六，頁名格式不變，舊頁照樣可讀 - 跨月的一週歸屬起始星期六所在月份，確保同一週只有一頁 （2026/08/29 六 ～ 09/04 五 全部寫入 Worklog-2026-08-W5） - 頁首標題補上日期範圍，開頁即可看出涵蓋哪幾天，避免再次誤判 - week_page_header 原本收了 page 卻不使用，一律以當下時間算標題，手動補寫 舊頁時會寫錯週；改為從頁名反推所屬週 - 同步 SKILL.md 與 README.md 的分週說明 驗證：2026/01/01 ～ 2027/12/31 每日「頁名 → 反推週起始日」全部一致（0 筆不符）， 月初、月末與跨月邊界皆正確。 Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 2 +- scripts/worklog/wiki_api.py | 67 ++++++++++++++++++++++++++++++++----- skills/worklog/SKILL.md | 6 ++-- 3 files changed, 63 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a76aead..4a1d8de 100644 --- a/README.md +++ b/README.md @@ -257,7 +257,7 @@ copilot plugin marketplace remove doc ### `worklog` -工作證明自動記錄與手動維護流程。相容的 `Stop` hook 會把每輪工作透過 `WORKLOG_CLI` 指定的 headless CLI 整理成六個固定欄位：專案/任務名稱、執行細節與產出、花費時間、任務狀態、遇到的困難、解決方式，並追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`）。手動模式提供 `--init`、`--tune`（Claude Code 專屬）、`--diagnose`、`--append`、`--show`。 +工作證明自動記錄與手動維護流程。相容的 `Stop` hook 會把每輪工作透過 `WORKLOG_CLI` 指定的 headless CLI 整理成六個固定欄位：專案/任務名稱、執行細節與產出、花費時間、任務狀態、遇到的困難、解決方式，並追加到 Gitea wiki 當週頁（`Worklog-yyyy-MM-W<週>`，**週以星期六起算**，換頁固定發生在星期六）。手動模式提供 `--init`、`--tune`（Claude Code 專屬）、`--diagnose`、`--append`、`--show`。 - **Claude Code / Antigravity**：`/jsc-doc:worklog --diagnose` - **Codex**：`$worklog --diagnose`，或用 `/skills` 選單 diff --git a/scripts/worklog/wiki_api.py b/scripts/worklog/wiki_api.py index 61df289..98a020b 100755 --- a/scripts/worklog/wiki_api.py +++ b/scripts/worklog/wiki_api.py @@ -3,7 +3,7 @@ # 用途：Gitea Wiki 讀寫工具（worklog 專用）。提供 token 解析、頁面讀取、 # 建立、append 追加（read-modify-write + 寫後驗證重試），供 worklog.sh # 與 /jsc-doc:worklog skill 共用，避免兩份實作漂移。 -# 更新時間：2026/07/27 11:14:16 +# 更新時間：2026/07/29 19:03:29 # 相依：Python 3 標準庫（urllib、base64、json、re）。不需 requests、不需 jq。 # 機密：token 一律從環境變數或本機憑證檔讀取，絕不輸出、絕不寫入任何檔案。 # ============================================================================== @@ -307,18 +307,67 @@ def append_entry(host, repo, token, page, header, entry, marker, retries=3): # 週頁命名 # ------------------------------------------------------------------------------ -def week_page_name(when=None): - """依台灣時區產生週頁名稱 Worklog-yyyy-MM-W<該月第幾週>（第幾週＝ceil(日/7)）。""" +# 週的定義：星期六起算（六～五），週頁以該週起始的星期六為錨點命名。 +# 舊規則以 ceil(日/7) 分週，換頁點固定落在每月 8／15／22／29 號，會把同一個工作週 +# 切成兩頁（例：2026/07/28 二 在 W4、07/29 三 卻跳到 W5），使用者開著舊頁會誤判成 +# 「worklog 停止記錄」。改以星期六為界後，換頁一律發生在週六，與星期對齊。 +WEEK_START_WEEKDAY = 5 # Python weekday()：週一 0、週二 1 …… 週六 5、週日 6 + + +def week_start(when=None): + """取得指定時間所屬工作週的起始日（該週的星期六；當天就是星期六時回傳當天）。""" when = when or datetime.now(TAIPEI) - week = (when.day + 6) // 7 - return f"Worklog-{when.year:04d}-{when.month:02d}-W{week}" + return when - timedelta(days=(when.weekday() - WEEK_START_WEEKDAY) % 7) + + +def week_start_from_page(page): + """ + 從週頁名稱反推該週起始的星期六。 + + 供手動指定頁面時產生正確標題；格式不符或該月不存在第 n 個星期六時回傳 None。 + """ + if not page: + return None + matched = re.match(r"^Worklog-(\d{4})-(\d{2})-W(\d)$", page.strip()) + if not matched: + return None + year, month, week = (int(matched.group(i)) for i in (1, 2, 3)) + try: + first_day = datetime(year, month, 1, tzinfo=TAIPEI) + except ValueError: + return None + first_saturday = first_day + timedelta(days=(WEEK_START_WEEKDAY - first_day.weekday()) % 7) + start = first_saturday + timedelta(days=7 * (week - 1)) + return start if start.month == month else None + + +def week_page_name(when=None): + """ + 依台灣時區產生週頁名稱 Worklog-yyyy-MM-W。 + + 週以星期六起算（六～五），n ＝該週起始的星期六是當月第幾個星期六。 + 跨月的一週歸屬起始星期六所在的月份，確保同一週只會有一頁 + （例：2026/08/29 六 ～ 09/04 五 都寫入 Worklog-2026-08-W5）。 + """ + start = week_start(when) + week = (start.day - 1) // 7 + 1 + return f"Worklog-{start.year:04d}-{start.month:02d}-W{week}" def week_page_header(page=None, when=None): - """產生週頁首行標題（例：# 2026 年 07 月 第 4 週工作紀錄）。""" - when = when or datetime.now(TAIPEI) - week = (when.day + 6) // 7 - return f"# {when.year} 年 {when.month:02d} 月 第 {week} 週工作紀錄" + """ + 產生週頁首行標題（例：# 2026 年 07 月 第 4 週工作紀錄（07/25 六 ～ 07/31 五））。 + + 標題含日期範圍，讓開頁的人一眼看出這頁涵蓋哪幾天，不必回頭推算週次。 + 傳入 page 時以頁名反推所屬週，避免手動補寫舊頁時寫入當下這週的標題。 + """ + start = week_start_from_page(page) or week_start(when) + end = start + timedelta(days=6) + week = (start.day - 1) // 7 + 1 + return ( + f"# {start.year} 年 {start.month:02d} 月 第 {week} 週工作紀錄" + f"（{start.month:02d}/{start.day:02d} 六 ～ {end.month:02d}/{end.day:02d} 五）" + ) # ------------------------------------------------------------------------------ diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index a7bc13d..ff379f8 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -148,8 +148,10 @@ GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host ## 條目與頁面格式 -- 週頁名稱：`Worklog---W<該月第幾週>`，第幾週 ＝ `ceil(日/7)`（例：`2026/07/27` → `Worklog-2026-07-W4`）。 -- 頁首標題：`# 年 月 第 <週> 週工作紀錄`。 +- **週以星期六起算（六～五）**，因此換頁一律發生在星期六，與星期對齊。 +- 週頁名稱：`Worklog---W`，`n` ＝該週起始的星期六是當月第幾個星期六（例：`2026/07/29 三` 屬於 `07/25 六` 那一週 → `Worklog-2026-07-W4`）。 +- 跨月的一週歸屬**起始星期六**所在的月份，確保同一週只有一頁（例：`2026/08/29 六 ～ 09/04 五` 全部寫入 `Worklog-2026-08-W5`）。 +- 頁首標題：`# 年 月 第 週工作紀錄（<起始日> 六 ～ <結束日> 五）`，日期範圍讓人一眼看出這頁涵蓋哪幾天。 - 每筆條目：`## <時間> — <專案>` ＋六個固定 bullet（專案/任務名稱、執行細節與產出、花費時間、任務狀態、遇到的困難、解決方式）；標題行尾帶 HTML 註解 marker（``）供寫後驗證與去重，wiki 渲染時不顯示。 - 多 session 同時寫入：`append_entry` 採「讀取 → 合併 → 寫回 → 寫後讀取驗證 marker」，未落地則重讀最新內容重試，最多 3 次。 From bd4b9b7a517259d345290373e5bd45082a281a67 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 29 Jul 2026 19:09:23 +0800 Subject: [PATCH 2/5] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E4=B8=89=E5=AE=B6=20manifest=20=E5=8D=87=E7=89=88=200.0.2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit master 現行版本為 0.0.1，本次 patch +1。 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 4984572..3bd2468 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-doc", - "version": "0.0.1", + "version": "0.0.2", "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 f7ba4ea..8eb65d6 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-doc", - "version": "0.0.1", + "version": "0.0.2", "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 8cba799..21874f4 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-doc", - "version": "0.0.1", + "version": "0.0.2", "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/" } From 55fa8e7bf49fbcdd5d81dafa7e31848b4b31f9ae Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 31 Jul 2026 17:00:01 +0000 Subject: [PATCH 3/5] docs(worklog): clarify Codex hook lookup order --- skills/worklog/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index ff379f8..db92f27 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -26,7 +26,7 @@ description: 工作證明自動記錄（worklog）的操作與維護 skill。搭 兩個限制的來源： -- **`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 解析器。 +- **`Stop` hook 只有相容 hook 環境實際執行**；Claude Code 先用 `CLAUDE_PLUGIN_ROOT` 定位腳本，找不到時再掃 `~/.claude/plugins/cache` 與 `~/.codex/plugins/cache`，最後命中 `*/jsc-doc/*/scripts/worklog/worklog.sh`。`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 行為。 From 7ee80a87ee5f07e72e7642457e2bec49acee446c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 31 Jul 2026 17:13:59 +0000 Subject: [PATCH 4/5] docs(doc): fix stale install paths --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4a1d8de..760e3d6 100644 --- a/README.md +++ b/README.md @@ -146,13 +146,13 @@ OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、` ```bash # 安裝 -git clone https://gitea.jsc.idv.tw/plugins/doc.git ~/jsc-plugin +git clone https://gitea.jsc.idv.tw/plugins/doc.git ~/plugins/doc mkdir -p ~/.config/opencode/skills -cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/ +cp -r ~/plugins/doc/skills/* ~/.config/opencode/skills/ # 更新 -git -C ~/jsc-plugin pull -cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/ +git -C ~/plugins/doc pull +cp -r ~/plugins/doc/skills/* ~/.config/opencode/skills/ # 移除 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 @@ -279,6 +279,6 @@ copilot plugin marketplace remove doc 6. 讓各助理更新： - Claude：`claude plugin update jsc-doc@doc` - Codex：`codex plugin marketplace upgrade doc` - - Antigravity：`git -C ~/jsc-plugin pull && agy plugin uninstall jsc-doc && agy plugin install ~/jsc-plugin` + - Antigravity：`git -C ~/plugins/doc pull && agy plugin uninstall jsc-doc && agy plugin install ~/plugins/doc` - OpenCode：`git pull` 後重新複製 `skills/` - Copilot：`copilot plugin marketplace update doc && copilot plugin update jsc-doc@doc` From 7b2ab8bf38214c49b2237066eace564c7abc476b Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 31 Jul 2026 17:36:08 +0000 Subject: [PATCH 5/5] refactor(shared): switch doc skills to jsc-shared --- skills/funcs/SKILL.md | 16 ++++++++-------- skills/issues-analyze-to-file/SKILL.md | 16 ++++++++-------- skills/issues-analyze/SKILL.md | 20 ++++++++++---------- skills/issues-sync/SKILL.md | 26 +++++++++++++------------- skills/worklog/SKILL.md | 10 +++++----- 5 files changed, 44 insertions(+), 44 deletions(-) diff --git a/skills/funcs/SKILL.md b/skills/funcs/SKILL.md index 59ef245..288e370 100644 --- a/skills/funcs/SKILL.md +++ b/skills/funcs/SKILL.md @@ -7,13 +7,13 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ 你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後保守優化被文件化原始碼的效能（排版依原本方式維持原樣，僅修正有誤處），最後重建 README。請依下列階段依序完成。 -## 共用規範（generic plugin，必要前置） +## 共用規範（shared plugin，必要前置） -執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/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`、輸出訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 +- `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、subagent 提示需帶入本規範。 +- `/jsc-shared:spec-execution`：不臆測／需人工確認、不擴及無關檔案（generated/bin/obj/.git/.docs 與第三方依賴）。 +- `/jsc-shared: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-generic:spec-time-log` — 若該 function 或指令檔有輸出訊息，統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱不翻譯；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；時間 Asia/Taipei）；區塊階段命名（`#region`／橫幅段落名稱作為 `階段` 前綴並移除包裹／橫幅本身、僅移除標記保留指令與行為）、檔案標頭保留例外、一行一則規則皆依該 spec。調整僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。 +- 輸出訊息格式：依 `/jsc-shared: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-generic:spec-time-log`，且不得藉此改變訊息反映的實際行為。 +- function 或指令檔若有輸出訊息，訊息格式、區塊階段命名、檔案標頭保留與一行一則規則一律依 `/jsc-shared:spec-time-log`，且不得藉此改變訊息反映的實際行為。 - 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。 -- 原始碼註解與 README 的語言依 `/jsc-generic:spec-output`（繁體中文為主；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文）。 +- 原始碼註解與 README 的語言依 `/jsc-shared:spec-output`（繁體中文為主；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文）。 diff --git a/skills/issues-analyze-to-file/SKILL.md b/skills/issues-analyze-to-file/SKILL.md index 1f7622b..18d25d0 100644 --- a/skills/issues-analyze-to-file/SKILL.md +++ b/skills/issues-analyze-to-file/SKILL.md @@ -7,13 +7,13 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite 你要讀取使用者提供的一或多筆 Gitea issue，彙整成完整需求文件，依功能拆成多個實作階段（每階段建立一個 issue），配合指定的 repositories 產生實作草稿，最後產出交付文件並依 issues 分組留言。**建立 issue 與留言屬於對外且不易復原的動作，必須先讓使用者確認過草稿再執行**。所有需求彙整、階段拆分與實作草稿一律先產生草稿檔，再詢問使用者是否實際建立 issue / 留言。請依下列階段依序完成。 -## 共用規範（generic plugin，必要前置） +## 共用規範（shared plugin，必要前置） -執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/jsc-generic:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 -- `/jsc-generic:spec-execution`：不臆測／需人工確認、不擴及無關檔案。 -- `/jsc-generic:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（`Authorization: token`、分頁完整讀取）。 +- `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 +- `/jsc-shared:spec-execution`：不臆測／需人工確認、不擴及無關檔案。 +- `/jsc-shared: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-generic:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 +- **不要依賴 `jq`**：依 `/jsc-shared:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 - **工作目錄**：所有草稿與文件放在 `.docs/doc-issues-analyze-to-file/`。 -- **議題描述流程圖**：依 `/jsc-generic:spec-output` — 產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，有助理解就加入 Mermaid 流程圖（處理流程、狀態轉移、階段相依關係），忠實反映需求與拆分結果、不得杜撰。 +- **議題描述流程圖**：依 `/jsc-shared: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-generic:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-generic:spec-output`。 +- JSON 解析（不依賴 `jq`）依 `/jsc-shared:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-shared:spec-output`。 - 需求、階段與實作草稿若無法可靠推論，一律保守描述並標註「需人工確認」，不得編造 issue 未提及的內容。 diff --git a/skills/issues-analyze/SKILL.md b/skills/issues-analyze/SKILL.md index 3291c78..67d4146 100644 --- a/skills/issues-analyze/SKILL.md +++ b/skills/issues-analyze/SKILL.md @@ -7,14 +7,14 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日與相依關係排序，並把排序結果留言到保存議題；**本 skill 不實作程式碼**——不修改原始碼、不 commit、不 push、不開 PR，後續實作交由 `/jsc-code:issues` 或使用者另行處理。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。 -## 共用規範（generic plugin，必要前置） +## 共用規範（shared plugin，必要前置） -執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/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 不支援）、不往回移、不得新建欄位。 +- `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、表格／Mermaid 呈現、個資（PII）去識別化。 +- `/jsc-shared:spec-execution`：不臆測／需人工確認、已知資訊跳過詢問。 +- `/jsc-shared:spec-gitea`：tea／API 工具選擇與檢查、`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 分頁完整讀取。 +- `/jsc-shared:spec-project-board`：看板欄位語意對應、GET 探測（404／501 不支援）、不往回移、不得新建欄位。 ## 絕對準則（不可違反） @@ -28,7 +28,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題 - **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。 - **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。 - **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，程式碼分析參考（僅供研究、補充議題描述，不修改）以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。 -- **工具選擇**：依 `/jsc-generic:spec-gitea` 的工具選擇流程（檢查 `tea`／`tea login list`／`GITEA_TOKEN` 後詢問使用者用 `tea` 或 `api`；已明確指定工具時才可跳過詢問；不依賴 `jq`，JSON 改用 tea 結構化輸出或交給 subagent 解析）。 +- **工具選擇**：依 `/jsc-shared: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-generic:spec-output` — 產生保存議題或小功能議題的描述時，有助理解就加入 Mermaid 流程圖（需求流程、狀態轉移、相依／阻擋關係），忠實反映需求與拆分結果、不得杜撰。 +- **議題描述流程圖**：依 `/jsc-shared:spec-output` — 產生保存議題或小功能議題的描述時，有助理解就加入 Mermaid 流程圖（需求流程、狀態轉移、相依／阻擋關係），忠實反映需求與拆分結果、不得杜撰。 ## 第 1 步：工具可用性檢查與使用方式選擇 -依 `/jsc-generic:spec-gitea` 的工具選擇流程執行：檢查 `tea`（`command -v tea`、`tea login list`，失敗記錄原因不中止）與 `GITEA_TOKEN`（只輸出「已設定／未設定」）→ 詢問使用者要用 `tea` 或 `api`（除非使用者已明確指定，不得自行決定；選 `tea` 後續仍需確認來源 host 有對應 login）→ 兩種方式都不可用則停止並回報缺少 `tea login` 或 `GITEA_TOKEN`（不要要求使用者把 token 貼進對話）。 +依 `/jsc-shared: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-generic:spec-project-board` 執行（欄位語意以看板實際名稱為準、不往回移、先 GET 探測端點且 404／501 視為不支援、不得對未確認端點寫入、不得新建欄位）：把議題移動到「待處理」欄位，代表需求分析已完成、等待實作；議題已在「待處理」或更後面的欄位時維持原欄位。 +- 依 `/jsc-shared:spec-project-board` 執行（欄位語意以看板實際名稱為準、不往回移、先 GET 探測端點且 404／501 視為不支援、不得對未確認端點寫入、不得新建欄位）：把議題移動到「待處理」欄位，代表需求分析已完成、等待實作；議題已在「待處理」或更後面的欄位時維持原欄位。 - 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳。 ## 第 4 步：依到期日排序並交棒實作 diff --git a/skills/issues-sync/SKILL.md b/skills/issues-sync/SKILL.md index 5926bfe..501f3b2 100644 --- a/skills/issues-sync/SKILL.md +++ b/skills/issues-sync/SKILL.md @@ -7,14 +7,14 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t 你要讀取使用者提供的一個 Gitea **專案（project）**或**單一議題**，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。例外：輸入為專案且使用者指定「關閉專案／專案完成」時，進入**專案完成模式**（見第 1 步之後的專節），跳過標籤分組與逐議題勾稽，改為批次搬移至「已完成」並關閉議題。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只回傳同步計畫（不落地任何檔案），實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。 -## 共用規範（generic plugin，必要前置） +## 共用規範（shared plugin，必要前置） -執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行： -- `/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 視為不支援、不得新建欄位。 +- `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。 +- `/jsc-shared:spec-execution`：不臆測／需人工確認。 +- `/jsc-shared:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（分頁完整讀取、GET 探測版本相依端點）。 +- `/jsc-shared: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-generic:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 +- **不要依賴 `jq`**：依 `/jsc-shared:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。 - **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。 -- **專案進度欄位（project column）**：依 `/jsc-generic:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。 -- **議題描述流程圖**：依 `/jsc-generic:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。 +- **專案進度欄位（project column）**：依 `/jsc-shared:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。 +- **議題描述流程圖**：依 `/jsc-shared: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-generic:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。 +6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc-shared: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-generic:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。 +- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc-shared: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-generic:spec-project-board`，且必須經第 5 步使用者確認後執行。 +- 進度欄位調整依 `/jsc-shared:spec-project-board`，且必須經第 5 步使用者確認後執行。 - 專案完成模式只在輸入為專案且使用者**明確**指定關閉／完成時進入；語意不明就用 AskUserQuestion 確認，不得自行認定。批次關閉議題前必須經使用者確認；含未完成 TODO 的議題要在確認時明確標出。不得透過此模式關閉不屬於該專案的議題。 -- JSON 解析（不依賴 `jq`）依 `/jsc-generic:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-generic:spec-output`。 +- JSON 解析（不依賴 `jq`）依 `/jsc-shared:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-shared:spec-output`。 diff --git a/skills/worklog/SKILL.md b/skills/worklog/SKILL.md index db92f27..2c021bf 100644 --- a/skills/worklog/SKILL.md +++ b/skills/worklog/SKILL.md @@ -53,12 +53,12 @@ WORKLOG_DIR="/../../scripts/worklog" ## 共用規範（必要前置） -執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），不安裝則中斷**： +執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），不安裝則中斷**： -- `/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`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 +- `/jsc-shared:spec-output`：繁體中文（台灣用語）、UTF-8 無 BOM、表格與 Mermaid 優先、**寫入外部系統不得洩漏 PII**。 +- `/jsc-shared:spec-execution`：自動執行原則（必要決策才中斷）、不臆測。 +- `/jsc-shared:spec-gitea`：token 機密保護（不 echo、遮蔽、不落地）、API 分頁、host 決定順序。 +- `/jsc-shared:spec-time-log`：時間戳固定 Asia/Taipei `yyyy/MM/dd HH:mm:ss`；訊息格式 `[時間][階段][等級]: 訊息`、一行一則。 本 skill 特有補充：