Merge pull request 'sync' (#46 ) from master into develop

Reviewed-on: #46
Merge pull request 'chore(plugin 版本): 升版 0.0.4 並更新 notifications' (#45 ) from agent/notifications-empty-review into master
2026-08-05 13:52:43 +00:00 · 2026-08-05 13:52:15 +00:00 · 2026-08-05 13:51:06 +00:00 · 2026-08-05 13:38:31 +00:00 · 2026-08-05 13:36:45 +00:00 · 2026-08-05 13:36:45 +00:00
25 changed files with 1549 additions and 164 deletions
@@ -2,7 +2,7 @@
  "name": "doc",
  "plugins": [
    {
-      "name": "jsc",
+      "name": "jsc-doc",
      "source": {
        "source": "url",
        "url": "https://gitea.jsc.idv.tw/plugins/doc.git"
@@ -1,14 +1,14 @@
 {
  "name": "doc",
-  "description": "JSC 文件化 skills 的 Claude Code marketplace，提供 docker-compose 註解整理與 function XML 文件補齊。",
+  "description": "JSC 文件化 skills 的 Claude Code marketplace，提供 docker-compose 註解整理、function XML 文件補齊、Gitea issue 文件流程、Gitea 通知處理與 worklog 工作紀錄。",
  "owner": {
    "name": "JSC"
  },
  "plugins": [
    {
-      "name": "jsc",
+      "name": "jsc-doc",
      "source": "./",
-      "description": "JSC 文件化 skills：整理 docker-compose 註解、補齊 function XML 文件並重建 README 功能列表與使用範例。"
+      "description": "JSC 文件化 skills：整理 docker-compose 註解、補齊 function XML 文件、同步 Gitea issue 文件流程、處理 Gitea 通知，並透過 worklog 記錄工作。"
    }
  ]
 }
@@ -1,12 +1,12 @@
 {
-  "name": "jsc",
+  "name": "jsc-doc",
-  "version": "0.1.8",
+  "version": "0.0.4",
-  "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：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 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
+  "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 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；notifications 會讀取 Gitea 通知、依通知類型分組並照 REVIEW.md 流程處理，沒有流程時詢問使用者並把缺少流程的類別附加到 REVIEW.md；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc-doc: 前綴呼叫。",
  "skills": "./skills",
  "author": {
    "name": "JSC"
  },
  "homepage": "https://gitea.jsc.idv.tw/plugins/doc",
  "repository": "https://gitea.jsc.idv.tw/plugins/doc.git",
-  "keywords": ["doc", "documentation", "docker-compose", "xml-doc", "skills", "cross-tool", "jsc"]
+  "keywords": ["doc", "documentation", "docker-compose", "xml-doc", "worklog", "skills", "cross-tool", "jsc"]
 }
@@ -1,6 +1,6 @@
 {
-  "name": "jsc",
+  "name": "jsc-doc",
-  "version": "0.1.8",
+  "version": "0.0.4",
-  "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 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）。所有 skills 以 SKILL.md 為共通標準。",
+  "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 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；notifications 會讀取 Gitea 通知、依通知類型分組並照 REVIEW.md 流程處理，沒有流程時詢問使用者並把缺少流程的類別附加到 REVIEW.md；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki（自動 Stop hook 僅相容 hook 環境支援）。所有 skills 以 SKILL.md 為共通標準。",
  "skills": "./skills"
 }
@@ -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/<name>/SKILL.md`。
 - 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。
- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc:` 前綴，不需強制加。
+- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc-doc:<name>` 呼叫；Codex 以 `$<name>`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc-doc:` 前綴，不需強制加。
 - 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。
 ## 慣例
@@ -1,57 +1,77 @@
-# jsc — 跨 AI 助理文件化 Skill 集合
+# jsc-doc — 跨 AI 助理文件化 Skill 集合
-一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的文件化 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` 用於把專案／議題／文件來源（議題連同留言與附件一起讀取）拆成小功能議題（母議題須待所有子議題關閉後才可關閉）、分析完成後把屬於專案看板的議題移到「待處理」欄位並依到期日實作；`doc-issues-sync` 用於讀取 Gitea 專案或議題，依工作目錄檔案勾稽並同步議題的 TODO 進度、標籤與專案看板進度欄位、產生進度留言；指定「關閉專案／專案完成」時改為批次把專案所有議題搬到「已完成」並關閉。
+目前內含七個實作型 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 進度、標籤與專案看板進度欄位、產生進度留言；指定「關閉專案／專案完成」時改為批次把專案所有議題搬到「已完成」並關閉；`notifications` 用於讀取 Gitea 通知、依通知類型分組並照 `REVIEW.md` 流程處理，若 `REVIEW.md` 不存在則視為空白流程檔並直接詢問使用者如何定義流程；`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:<name>` 或自動觸發 | ✅ |
+| Claude Code | `claude plugin`（marketplace） | `/jsc-doc:<name>` 或自動觸發 | ✅ |
 | Codex | `codex plugin`（marketplace） | `$<name>` 或 `/skills` 選單 | ❌（用 `$name`） |
-| Antigravity | `agy plugin install` | `/jsc:<name>` 或自動觸發 | ✅ |
+| Antigravity | `agy plugin install` | `/jsc-doc:<name>` 或自動觸發 | ✅ |
 | OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） |
 | GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc-doc:` 前綴） |
-> Codex 不支援自訂前綴（skill 以 `$name` 呼叫，例 `$doc-docker`）；OpenCode 由模型依描述自動呼叫。兩者皆**不強制**前綴。
+> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。
 ---
 ## 目錄結構
-同一個 repo 同時帶四種 manifest，彼此以路徑隔離、互不干擾；四家都讀同一份 `skills/`。
+同一個 repo 同時帶四種 manifest，彼此以路徑隔離、互不干擾；各助理都讀同一份 `skills/`。
 ```
 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/
 │   └── worklog/             # worklog 自動記錄的可執行元件（skill 與 hook 共用）
 │       ├── worklog.sh       # 主流程：抽本輪 → 濃縮成六欄 → 遮蔽 → 追加到 wiki
 │       ├── 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 → 實作草稿 → 交付留言
+│   ├── issues-analyze-to-file/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
-│   ├── doc-issues-analyze/SKILL.md         # 讀來源 → 保存議題 → 小功能議題（看板移待處理）→ 排程實作 → PR
+│   ├── issues-analyze/SKILL.md         # 讀來源 → 保存議題 → 小功能議題（看板移待處理）→ 排序留言（不實作）
-│   └── doc-issues-sync/SKILL.md            # 讀專案／議題 → 依工作目錄勾稽 TODO → 補 TODO／更新標籤／調整看板欄位 → 進度留言；關閉專案時批次搬「已完成」並關閉
+│   ├── issues-sync/SKILL.md            # 讀專案／議題 → 依工作目錄勾稽 TODO → 補 TODO／更新標籤／調整看板欄位 → 進度留言；關閉專案時批次搬「已完成」並關閉
 │   ├── notifications/SKILL.md          # 讀取 Gitea 通知並依 REVIEW.md／空白流程處理
 │   └── worklog/SKILL.md                # 工作證明自動記錄的操作與維護
 ├── AGENTS.md                # 跨助理共用指引
 └── README.md
 ```
 ### worklog 適用範圍
 | 功能 | Claude Code | Codex | Antigravity | OpenCode | GitHub Copilot |
 | --- | --- | --- | --- | --- | --- |
 | `Stop` hook 自動記錄 | ✅ | ✅ 需可讀 Codex session JSONL | ❌ | ❌ | ❌ |
 | `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-doc` 找已安裝的 worklog 腳本並解析 Codex session JSONL。摘要執行器可用 `WORKLOG_CLI=auto|claude|codex|agy|opencode|copilot` 指定；預設 `auto` 會先依目前 hook/session 環境判斷正在使用的 CLI，判斷不到或該 CLI 不可執行時才 fallback 到已安裝工具。
 ---
-## 安裝 / 更新 / 移除（各家原生 plugin CLI）
+## 安裝 / 更新 / 移除（各助理）
 > 指令中的 repo 網址：`https://gitea.jsc.idv.tw/plugins/doc.git`
 >
@@ -64,39 +84,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:<name>`（例 `/jsc:doc-docker`）。
+- **呼叫**：`/jsc-doc:<name>`（例 `/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。
- **呼叫**：`$<name>`（例 `$doc-docker`），或用 `/skills` 選單。
+- **呼叫**：`$<name>`（例 `$docker`），或用 `/skills` 選單。
 ### Antigravity（`agy`）
@@ -109,16 +129,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/<owner>/<repo>`。
- 其他：`agy plugin list`、`agy plugin enable jsc` / `disable jsc`、`agy plugin validate <path>`。安裝後重啟工作階段。
+- 其他：`agy plugin list`、`agy plugin enable jsc-doc` / `disable jsc-doc`、`agy plugin validate <path>`。安裝後重啟工作階段。
- **呼叫**：`/jsc:<name>`（例 `/jsc:doc-docker`）或依描述自動觸發。
+- **呼叫**：`/jsc-doc:<name>`（例 `/jsc-doc:docker`）或依描述自動觸發。
 ### OpenCode
@@ -127,39 +147,65 @@ 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
+git -C ~/plugins/doc pull
-cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/
+cp -r ~/plugins/doc/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
+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。
 > **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
 - **呼叫**：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。
 ### GitHub Copilot CLI
 Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令，可直接從 marketplace 安裝、更新與移除本 plugin。
 ```bash
 # 安裝
 copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/doc.git
 copilot plugin install jsc-doc@doc
 # 更新
 copilot plugin marketplace update doc
 copilot plugin update jsc-doc@doc
 # 移除
 copilot plugin uninstall jsc-doc@doc
 copilot plugin marketplace remove doc
 ```
 - 安裝 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 "請使用 docker 整理 docker-compose 註解"`。
 - `worklog` 的 `Stop` hook 自動記錄仍只有相容 hook 環境會實際執行；Copilot CLI 可作為 `WORKLOG_CLI=copilot` 摘要執行器，但不會執行 Claude Code hook。
 ---
 ## 用 CLI 直接執行 skill（headless / 一次性）
 安裝好之後，不必進互動介面，一行指令就能叫某個 skill 跑完並印出結果：
-| 助理 | headless 指令 | 執行 `doc-docker` skill |
+| 助理 | headless 指令 | 執行 `docker` skill |
 | --- | --- | --- |
-| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc:doc-docker"` |
+| Claude Code | `claude -p "<prompt>"` | `claude -p "/jsc-doc:docker"` |
-| Codex | `codex exec "<prompt>"` | `codex exec '$doc-docker'` |
+| Codex | `codex exec "<prompt>"` | `codex exec '$docker'` |
-| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc:doc-docker"` |
+| Antigravity | `agy -p "<prompt>"` | `agy -p "/jsc-doc:docker"` |
 | OpenCode | `opencode run "<message>"` | `opencode run "整理 docker-compose 註解"` |
 | GitHub Copilot CLI | `copilot -p "<message>"` | `copilot -p "整理 docker-compose 註解"` |
- Claude / Antigravity 支援 `/jsc:` 前綴，直接 `-p "/jsc:<name>"` 即可。
+- Claude / Antigravity 支援 `/jsc-doc:` 前綴，直接 `-p "/jsc-doc:<name>"` 即可。
- Codex 以 `$<name>` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$doc-docker'`。
+- Codex 以 `$<name>` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$docker'`。
- OpenCode 沒有前綴，用自然語言描述需求，模型會自動透過 skill 工具呼叫。
+- 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'`。
 ---
@@ -170,61 +216,78 @@ rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs
 <!-- JSC-SKILLS:START -->
-### `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`
+- **Claude Code / Antigravity**：`/jsc-doc:docker`
- **Codex**：`$doc-docker`，或用 `/skills` 選單
+- **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`
+- **Claude Code / Antigravity**：`/jsc-doc:funcs`
- **Codex**：`$doc-funcs`，或用 `/skills` 選單
+- **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、把需求拆成多階段 issue、依 issue 產生實作規劃或交付留言，或提到 doc-issues-analyze-to-file、issue 需求分析、issue 拆階段、tea issues、Gitea issue 留言時使用此 skill。
+讀取一或多筆 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`
+- **Claude Code / Antigravity**：`/jsc-doc:issues-analyze-to-file`
- **Codex**：`$doc-issues-analyze-to-file`，或用 `/skills` 選單
+- **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 介面不支援時改列建議清單請使用者手動拖曳）；再依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。所有中間成果都不落地成草稿檔，一律使用 `tea` 或 Gitea API 保存到議題描述或留言。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
+讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取——文字附件直接取內容、圖片等二進位附件唯讀暫存讀取後即刪、無法讀取的附件列出檔名標註需人工確認），先檢查 `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`
+- **Claude Code / Antigravity**：`/jsc-doc:issues-analyze`
- **Codex**：`$doc-issues-analyze`，或用 `/skills` 選單
+- **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`
+- **Claude Code / Antigravity**：`/jsc-doc:issues-sync`
- **Codex**：`$doc-issues-sync`，或用 `/skills` 選單
+- **Codex**：`$issues-sync`，或用 `/skills` 選單
 - **OpenCode**：描述需求自動觸發
 ### `notifications`
 讀取 Gitea 通知，依通知類型分組後逐組執行；若沒有通知就直接結束；先從目前工作目錄的 `REVIEW.md` 找對應流程，找不到或檔案不存在就視為空白流程檔並詢問使用者怎麼定義，之後把缺少流程的通知類型附加回 `REVIEW.md`。當使用者要整理 Gitea 通知、依通知類型批次處理、照 `REVIEW.md` 執行通知流程、或補齊 `REVIEW.md` 的通知類型說明時使用此 skill。
 - **Claude Code / Antigravity**：`/jsc-doc:notifications`
 - **Codex**：`$notifications`，或用 `/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-doc:worklog --diagnose`
 - **Codex**：`$worklog --diagnose`，或用 `/skills` 選單
 - **OpenCode / GitHub Copilot**：需完整 plugin 目錄保留 `scripts/`；可用 `WORKLOG_CLI=opencode` 或 `WORKLOG_CLI=copilot` 作為摘要 CLI
 <!-- JSC-SKILLS:END -->
 ---
 ## 新增一個 skill
-1. 建立目錄：`mkdir -p skills/<your-skill-name>`
+1. 複製既有 skill 作範本：`cp -r skills/docker skills/<your-skill-name>`
 2. 編輯 `skills/<your-skill-name>/SKILL.md` 的 frontmatter：
-   - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc:<name>`**。
+   - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc-doc:<name>`**。
   - `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。
+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 ~/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`
@@ -0,0 +1,15 @@
 {
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "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
          }
        ]
      }
    ]
  }
 }
@@ -1,6 +1,6 @@
 {
-  "name": "jsc",
+  "name": "jsc-doc",
-  "version": "0.1.8",
+  "version": "0.0.4",
-  "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 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
+  "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 進度、標籤與專案看板進度欄位並產生進度留言（指定關閉專案／專案完成時改為批次把專案所有議題搬到「已完成」並關閉）；notifications 會讀取 Gitea 通知、依通知類型分組並照 REVIEW.md 流程處理，沒有流程時詢問使用者並把缺少流程的類別附加到 REVIEW.md；worklog 會以 README 定義的 headless CLI 將每輪工作整理成六欄工作紀錄並追加到 Gitea wiki。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-doc: 前綴呼叫。",
  "skills": "./skills/"
 }
@@ -0,0 +1,314 @@
 #!/usr/bin/env python3
 # ==============================================================================
 # 用途：worklog 的 transcript 處理工具。負責 (1) 從 Claude Code／Codex
 #       JSONL 抽出「本輪」對話片段（最後一筆使用者訊息之後的全部內容），
 #       (2) 估算本輪花費時間，(3) 對文字做機密遮蔽（token／密碼／PII），
 #       作為寫入 wiki 前的第二道防線。
 # 更新時間：2026/07/27 22:16:00
 # 相依：Python 3 標準庫。全程僅走 stdin／stdout，不寫任何檔案。
 # ==============================================================================
 import json
 import re
 import sys
 from datetime import datetime, timezone
 # 單則工具結果／參數的擷取上限，避免整份 transcript 塞進摘要輸入
 TOOL_RESULT_LIMIT = 200
 TOOL_INPUT_LIMIT = 160
 TOTAL_LIMIT = 24000
 # ------------------------------------------------------------------------------
 # 機密遮蔽規則：命中一律換成 ***
 # ------------------------------------------------------------------------------
 REDACT_PATTERNS = [
    (r"[A-Za-z0-9_\-]*:[A-Za-z0-9_\-]{16,}@", "***@"),          # URL 內嵌憑證 user:token@
    (r"\b[0-9a-f]{40}\b", "***"),                                 # Gitea 40 字元 token
    (r"\bgh[pousr]_[A-Za-z0-9_]{16,}\b", "***"),                  # GitHub token
    (r"\bsk-[A-Za-z0-9\-_]{16,}\b", "***"),                       # API key
    (r"(?i)\b(token|password|passwd|pwd|secret|api[_-]?key)\b\s*[:=]\s*\S+", r"\1=***"),
    (r"(?i)Authorization:\s*(token|bearer)\s+\S+", r"Authorization: \1 ***"),
    (r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}", "***"),  # Email
    (r"\b09\d{2}[-\s]?\d{3}[-\s]?\d{3}\b", "***"),                 # 台灣手機
    (r"\b[A-Z][12]\d{8}\b", "***"),                                # 身分證字號
 ]
 def redact(text):
    """對文字套用全部機密遮蔽規則，回傳遮蔽後的結果。"""
    for pattern, replacement in REDACT_PATTERNS:
        text = re.sub(pattern, replacement, text)
    return text
 def _is_real_user_message(entry):
    """判斷 transcript 條目是否為真正的使用者輸入（排除工具回填與環境注入）。"""
    payload = entry.get("payload")
    if isinstance(payload, dict) and entry.get("type") == "event_msg":
        return payload.get("type") == "user_message" and bool(str(payload.get("message") or "").strip())
    if entry.get("type") != "user":
        return False
    content = entry.get("message", {}).get("content")
    if isinstance(content, str):
        return bool(content.strip())
    if isinstance(content, list):
        return any(b.get("type") == "text" for b in content if isinstance(b, dict))
    return False
 def _blocks(entry):
    """取出條目的 content blocks，統一為 list 形式。"""
    content = entry.get("message", {}).get("content")
    if isinstance(content, str):
        return [{"type": "text", "text": content}]
    return content if isinstance(content, list) else []
 def _payload_text_blocks(content):
    """把 Codex response_item 的 content blocks 轉成純文字片段。"""
    if isinstance(content, str):
        return [content]
    if not isinstance(content, list):
        return []
    texts = []
    for block in content:
        if not isinstance(block, dict):
            continue
        if block.get("type") in ("input_text", "output_text", "text"):
            text = (block.get("text") or "").strip()
            if text:
                texts.append(text)
    return texts
 def _render_codex_payload(entry):
    """將 Codex session JSONL 的 payload 格式轉為摘要輸入用純文字。"""
    payload = entry.get("payload")
    if not isinstance(payload, dict):
        return []
    lines = []
    entry_type = entry.get("type")
    payload_type = payload.get("type")
    if entry_type == "event_msg":
        if payload_type == "user_message":
            message = (payload.get("message") or "").strip()
            if message:
                lines.append(f"[user] {message}")
        elif payload_type == "agent_message":
            message = (payload.get("message") or "").strip()
            if message:
                phase = payload.get("phase") or "assistant"
                lines.append(f"[assistant:{phase}] {message}")
        return lines
    if entry_type != "response_item":
        return lines
    if payload_type == "message":
        role = payload.get("role") or "assistant"
        if role in ("system", "developer"):
            return lines
        for text in _payload_text_blocks(payload.get("content")):
            # Codex 會把 skill 內容以 user role 注入；避免把整份 SKILL.md 當成本輪工作。
            if role == "user" and text.lstrip().startswith("<skill>"):
                continue
            if role == "user" and text.lstrip().startswith("<environment_context>"):
                continue
            lines.append(f"[{role}] {text}")
    elif payload_type == "function_call":
        name = payload.get("name") or "?"
        raw = str(payload.get("arguments") or "").strip().replace("\n", " ")
        lines.append(f"[tool:{name}] {raw[:TOOL_INPUT_LIMIT]}")
    elif payload_type == "function_call_output":
        raw = str(payload.get("output") or "").strip().replace("\n", " ")
        if raw:
            lines.append(f"[result] {raw[:TOOL_RESULT_LIMIT]}")
    return lines
 def _render(entry):
    """將單一 transcript 條目轉為摘要輸入用的純文字行（工具結果僅取前段）。"""
    codex_lines = _render_codex_payload(entry)
    if codex_lines:
        return codex_lines
    role = entry.get("type")
    lines = []
    for block in _blocks(entry):
        if not isinstance(block, dict):
            continue
        kind = block.get("type")
        if kind == "text":
            text = (block.get("text") or "").strip()
            if text:
                lines.append(f"[{role}] {text}")
        elif kind == "tool_use":
            name = block.get("name", "?")
            raw = json.dumps(block.get("input", {}), ensure_ascii=False)
            lines.append(f"[tool:{name}] {raw[:TOOL_INPUT_LIMIT]}")
        elif kind == "tool_result":
            raw = block.get("content")
            if isinstance(raw, list):
                raw = " ".join(
                    b.get("text", "") for b in raw if isinstance(b, dict) and b.get("type") == "text"
                )
            raw = str(raw or "").strip().replace("\n", " ")
            if raw:
                lines.append(f"[result] {raw[:TOOL_RESULT_LIMIT]}")
    return lines
 def _read_entries(path):
    """讀取 transcript JSONL，忽略無法解析的列。"""
    try:
        with open(path, encoding="utf-8") as fh:
            entries = []
            for line in fh:
                line = line.strip()
                if not line:
                    continue
                try:
                    entries.append(json.loads(line))
                except ValueError:
                    continue
    except OSError:
        return []
    return entries
 def _turn_start_index(entries):
    """找出本輪起點：最後一筆真正使用者訊息的位置。"""
    start = 0
    for index in range(len(entries) - 1, -1, -1):
        if _is_real_user_message(entries[index]):
            start = index
            break
    return start
 def _parse_timestamp(value):
    """解析常見 transcript timestamp 格式，失敗回 None。"""
    if not isinstance(value, str) or not value.strip():
        return None
    raw = value.strip()
    if raw.endswith("Z"):
        raw = raw[:-1] + "+00:00"
    try:
        dt = datetime.fromisoformat(raw)
    except ValueError:
        return None
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=timezone.utc)
    return dt
 def _entry_timestamp(entry):
    """取出 transcript 條目的時間欄位。"""
    for key in ("timestamp", "created_at", "time"):
        dt = _parse_timestamp(entry.get(key))
        if dt:
            return dt
    message = entry.get("message")
    if isinstance(message, dict):
        for key in ("timestamp", "created_at", "time"):
            dt = _parse_timestamp(message.get(key))
            if dt:
                return dt
    return None
 def format_duration(seconds):
    """把秒數格式化為精簡中文耗時。"""
    if seconds < 0:
        return "未判定"
    minutes = int(round(seconds / 60))
    if minutes <= 0:
        return "1 分鐘內"
    hours, mins = divmod(minutes, 60)
    if hours and mins:
        return f"{hours} 小時 {mins} 分鐘"
    if hours:
        return f"{hours} 小時"
    return f"{mins} 分鐘"
 def turn_duration(path):
    """
    估算本輪花費時間：取本輪起點到最後一筆可解析 timestamp 的差距。
    transcript 無時間欄位或本輪少於兩個時間點時回「未判定」，避免臆測。
    """
    entries = _read_entries(path)
    if not entries:
        return "未判定"
    start = _turn_start_index(entries)
    stamps = [dt for dt in (_entry_timestamp(e) for e in entries[start:]) if dt]
    if len(stamps) < 2:
        return "未判定"
    return format_duration((max(stamps) - min(stamps)).total_seconds())
 def extract_turn(path):
    """
    從 transcript JSONL 抽出本輪內容：最後一筆真正使用者訊息（含該筆）之後的全部條目。
    不需任何狀態檔即可界定「本輪」，符合工作內容不落地的要求。
    回傳純文字字串；讀取失敗或無內容時回空字串。
    """
    entries = _read_entries(path)
    if not entries:
        return ""
    start = _turn_start_index(entries)
    lines = []
    for entry in entries[start:]:
        lines.extend(_render(entry))
    text = "\n".join(lines).strip()
    if len(text) > TOTAL_LIMIT:
        head = text[: TOTAL_LIMIT // 2]
        tail = text[-TOTAL_LIMIT // 2 :]
        text = f"{head}\n…（中段省略）…\n{tail}"
    return text
 USAGE = """用法：transcript.py <子命令> [參數]
  extract <transcript 路徑>   抽出本輪內容並遮蔽機密後輸出到 stdout
  duration <transcript 路徑>  估算本輪花費時間，無法判定時輸出「未判定」
  redact                      自 stdin 讀取文字，遮蔽機密後輸出到 stdout
 """
 def main(argv):
    """CLI 進入點：解析子命令並執行抽取或遮蔽。"""
    if not argv or argv[0] in ("-h", "--help"):
        print(USAGE)
        return 0
    if argv[0] == "extract":
        if len(argv) < 2:
            return 2
        text = extract_turn(argv[1])
        if not text:
            return 1
        sys.stdout.write(redact(text))
        return 0
    if argv[0] == "duration":
        if len(argv) < 2:
            return 2
        sys.stdout.write(turn_duration(argv[1]))
        return 0
    if argv[0] == "redact":
        sys.stdout.write(redact(sys.stdin.read()))
        return 0
    print(USAGE)
    return 2
 if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,483 @@
 #!/usr/bin/env python3
 # ==============================================================================
 # 用途：Gitea Wiki 讀寫工具（worklog 專用）。提供 token 解析、頁面讀取、
 #       建立、append 追加（read-modify-write + 寫後驗證重試），供 worklog.sh
 #       與 /jsc-doc:worklog skill 共用，避免兩份實作漂移。
 # 更新時間：2026/07/29 19:03:29
 # 相依：Python 3 標準庫（urllib、base64、json、re）。不需 requests、不需 jq。
 # 機密：token 一律從環境變數或本機憑證檔讀取，絕不輸出、絕不寫入任何檔案。
 # ==============================================================================
 import base64
 import json
 import os
 import re
 import sys
 import ssl
 import urllib.error
 import urllib.parse
 import urllib.request
 from datetime import datetime, timedelta, timezone
 TAIPEI = timezone(timedelta(hours=8))
 def _ssl_context():
    """
    建立 TLS 連線設定：維持完整憑證鏈驗證，僅關閉 VERIFY_X509_STRICT。
    Python 3.13 起預設啟用 X509 嚴格檢查，內部 CA 憑證若缺少 Subject Key
    Identifier 會被拒絕（curl 不做此檢查，故 curl 可連而 Python 不行）。
    此處只放寬擴充欄位的嚴格檢查，主機名稱與憑證鏈驗證仍完整保留。
    """
    ctx = ssl.create_default_context()
    ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT
    return ctx
 SSL_CONTEXT = _ssl_context()
 def now_str():
    """取得台灣時區的 yyyy/MM/dd HH:mm:ss 時間字串。"""
    return datetime.now(TAIPEI).strftime("%Y/%m/%d %H:%M:%S")
 def log(level, message, stage="wiki_api"):
    """輸出統一格式訊息（[時間][階段][等級]: 訊息，一行一則），一律走 stderr 不污染 stdout。"""
    print(f"[{now_str()}][{stage}][{level}]: {message}", file=sys.stderr)
 def mask(text, secret):
    """將字串中的 secret 遮蔽為 ***，避免 token 洩漏到輸出。"""
    if not secret:
        return text
    return text.replace(secret, "***")
 # ------------------------------------------------------------------------------
 # token 解析：GITEA_TOKEN → tea config → git-credentials
 # ------------------------------------------------------------------------------
 def _token_from_tea(host):
    """從 tea 設定檔取出指定 host 的 token（找不到回 None）。"""
    for path in ("~/.config/tea/config.yml", "~/.tea/config.yml"):
        f = os.path.expanduser(path)
        if not os.path.isfile(f):
            continue
        try:
            raw = open(f, encoding="utf-8").read()
        except OSError:
            continue
        for block in re.split(r"(?m)^\s*-\s+name:", raw):
            if host not in block:
                continue
            m = re.search(r"(?m)^\s*token:\s*[\"']?([A-Za-z0-9_\-]+)", block)
            if m:
                return m.group(1)
    return None
 def _token_from_git_credentials(host):
    """從 ~/.git-credentials（credential.helper=store）取出指定 host 的密碼作為 token。"""
    f = os.path.expanduser("~/.git-credentials")
    if not os.path.isfile(f):
        return None
    try:
        lines = open(f, encoding="utf-8").read().splitlines()
    except OSError:
        return None
    for line in lines:
        m = re.match(r"https?://([^:]+):([^@]+)@(.+)$", line.strip())
        if m and m.group(3) == host:
            return urllib.parse.unquote(m.group(2))
    return None
 def resolve_token(host, repo):
    """
    依固定優先序解析可用 token，並以 GET /repos/<repo> 實際驗證權限。
    優先序：GITEA_TOKEN → tea 設定檔該 host 的 token → ~/.git-credentials。
    回傳 (token, 來源說明)；全部失敗回 (None, 說明)。
    """
    candidates = []
    env = os.environ.get("GITEA_TOKEN")
    if env:
        candidates.append((env, "GITEA_TOKEN"))
    tea = _token_from_tea(host)
    if tea and tea != env:
        candidates.append((tea, "tea 設定檔"))
    cred = _token_from_git_credentials(host)
    if cred and cred not in (env, tea):
        candidates.append((cred, "git-credentials"))
    if not candidates:
        return None, "找不到任何可用憑證來源"
    for token, source in candidates:
        code, _ = _request("GET", f"https://{host}/api/v1/repos/{repo}", token, None)
        if code == 200:
            return token, source
        log("DBG", f"{source} 對 {host} 驗證失敗（HTTP {code}），改試下一個來源")
    return None, f"{len(candidates)} 個憑證來源全部驗證失敗"
 # ------------------------------------------------------------------------------
 # HTTP
 # ------------------------------------------------------------------------------
 def _request(method, url, token, payload):
    """發出 Gitea API 請求，回傳 (HTTP 狀態碼, 回應內文字串)。網路層錯誤以 0 表示。"""
    data = json.dumps(payload, ensure_ascii=False).encode("utf-8") if payload is not None else None
    req = urllib.request.Request(url, data=data, method=method)
    req.add_header("Authorization", f"token {token}")
    req.add_header("Accept", "application/json")
    if data:
        req.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(req, timeout=30, context=SSL_CONTEXT) as resp:
            return resp.status, resp.read().decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        return e.code, e.read().decode("utf-8", "replace")
    except Exception as e:  # 網路錯誤、逾時
        return 0, str(e)
 def _api_base(host, repo):
    """組出 repo 層級的 wiki API base URL。"""
    return f"https://{host}/api/v1/repos/{repo}/wiki"
 # ------------------------------------------------------------------------------
 # wiki 操作
 # ------------------------------------------------------------------------------
 def list_pages(host, repo, token):
    """
    列出 wiki 全部頁面（分頁完整讀取），回傳 (狀態, 頁面清單)。
    狀態為 'ok'／'missing'（wiki 尚未初始化）／'error'。清單元素含 title 與 sub_url。
    """
    pages = []
    page_no = 1
    limit = 50
    while True:
        url = f"{_api_base(host, repo)}/pages?page={page_no}&limit={limit}"
        code, body = _request("GET", url, token, None)
        if code == 404:
            return "missing", []
        if code != 200:
            return "error", []
        try:
            batch = json.loads(body)
        except ValueError:
            return "error", []
        if not isinstance(batch, list):
            return "error", []
        pages.extend(batch)
        if len(batch) < limit:
            return "ok", pages
        page_no += 1
 def resolve_sub_url(host, repo, token, title):
    """
    以 title 查出 Gitea 實際的 sub_url。
    Gitea wiki 會對 title 做轉義（`-` 代表空格，實際 dash 另有轉義形式，例如
    title `Worklog-2026-07-W4` 的 sub_url 為 `Worklog-2026-07-W4.-`），因此讀寫
    一律以查表得到的 sub_url 為準，不自行猜測轉義規則。
    找不到回 None。
    """
    status, pages = list_pages(host, repo, token)
    if status != "ok":
        return None
    for item in pages:
        if item.get("title") == title:
            return item.get("sub_url") or title
    return None
 def get_page(host, repo, token, page):
    """
    讀取 wiki 頁面內容（page 可傳 title 或 sub_url，內部會自動解析）。
    回傳 (狀態, 內容字串)；狀態為 'ok'（存在）、'missing'（404，頁面或 wiki 尚未建立）、
    'error'（其他失敗，內容為遮蔽後的錯誤訊息）。
    """
    sub_url = resolve_sub_url(host, repo, token, page) or page
    url = f"{_api_base(host, repo)}/page/{urllib.parse.quote(sub_url)}"
    code, body = _request("GET", url, token, None)
    if code == 404:
        return "missing", ""
    if code != 200:
        return "error", mask(f"HTTP {code} {body[:200]}", token)
    try:
        data = json.loads(body)
    except ValueError:
        return "error", "回應不是合法 JSON"
    raw = data.get("content_base64") or ""
    try:
        return "ok", base64.b64decode(raw).decode("utf-8", "replace")
    except Exception:
        return "error", "content_base64 解碼失敗"
 def create_page(host, repo, token, page, content, message):
    """建立新的 wiki 頁面（wiki 尚未初始化時亦由此初始化）。回傳 (是否成功, 訊息)。"""
    url = f"{_api_base(host, repo)}/new"
    payload = {
        "title": page,
        "content_base64": base64.b64encode(content.encode("utf-8")).decode("ascii"),
        "message": message,
    }
    code, body = _request("POST", url, token, payload)
    if code in (201, 200):
        return True, f"已建立頁面 {page}"
    return False, mask(f"建立頁面失敗 HTTP {code} {body[:200]}", token)
 def delete_page(host, repo, token, page):
    """刪除 wiki 頁面（page 可傳 title 或 sub_url）。回傳 (是否成功, 訊息)。"""
    sub_url = resolve_sub_url(host, repo, token, page) or page
    url = f"{_api_base(host, repo)}/page/{urllib.parse.quote(sub_url)}"
    code, body = _request("DELETE", url, token, None)
    if code in (204, 200):
        return True, f"已刪除頁面 {page}"
    return False, mask(f"刪除頁面失敗 HTTP {code} {body[:200]}", token)
 def update_page(host, repo, token, page, content, message):
    """整頁覆寫既有 wiki 頁面（append 由呼叫端先合併內容）。回傳 (是否成功, 訊息)。"""
    sub_url = resolve_sub_url(host, repo, token, page) or page
    url = f"{_api_base(host, repo)}/page/{urllib.parse.quote(sub_url)}"
    payload = {
        "title": page,
        "content_base64": base64.b64encode(content.encode("utf-8")).decode("ascii"),
        "message": message,
    }
    code, body = _request("PATCH", url, token, payload)
    if code in (200, 201):
        return True, f"已更新頁面 {page}"
    return False, mask(f"更新頁面失敗 HTTP {code} {body[:200]}", token)
 def append_entry(host, repo, token, page, header, entry, marker, retries=3):
    """
    將條目追加到週頁尾端：讀取現有內容 → 合併 → 寫回 → 寫後讀取驗證。
    marker 為條目內唯一字串（時間戳＋session 短碼），用於驗證自己的內容確實落地；
    多個 session 同時寫入時，驗證失敗會重讀最新內容重試，避免互相覆蓋。
    回傳 (是否成功, 訊息)。
    """
    for attempt in range(1, retries + 1):
        status, current = get_page(host, repo, token, page)
        if status == "error":
            return False, f"讀取頁面失敗：{current}"
        if status == "missing":
            content = f"{header}\n\n{entry}\n"
            ok, msg = create_page(host, repo, token, page, content, f"worklog: 建立 {page}")
            if not ok:
                # wiki 已存在但頁面不存在時，建立可能失敗；下一輪改走更新
                log("WRN", f"第 {attempt} 次建立失敗：{msg}")
                continue
        else:
            if marker in current:
                return True, "條目已存在，無需重複寫入"
            body = current.rstrip("\n")
            if not body:
                body = header
            content = f"{body}\n\n{entry}\n"
            ok, msg = update_page(host, repo, token, page, content, f"worklog: 追加 {marker}")
            if not ok:
                log("WRN", f"第 {attempt} 次寫入失敗：{msg}")
                continue
        verify_status, verify_content = get_page(host, repo, token, page)
        if verify_status == "ok" and marker in verify_content:
            return True, f"條目已寫入 {page}（第 {attempt} 次嘗試）"
        log("WRN", f"第 {attempt} 次寫後驗證未找到條目，準備重試")
    return False, f"重試 {retries} 次仍未成功寫入 {page}"
 # ------------------------------------------------------------------------------
 # 週頁命名
 # ------------------------------------------------------------------------------
 # 週的定義：星期六起算（六～五），週頁以該週起始的星期六為錨點命名。
 # 舊規則以 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)
    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>。
    週以星期六起算（六～五），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 週工作紀錄（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} 五）"
    )
 # ------------------------------------------------------------------------------
 # CLI
 # ------------------------------------------------------------------------------
 USAGE = """用法：wiki_api.py <子命令> [參數]
  probe                     檢查 host／repo／token／wiki API 可用性
  page-name                 印出當週頁面名稱
  pages                     列出全部頁面（title 與實際 sub_url）
  show [頁面]               印出指定頁面內容（預設當週頁）
  append <marker> [頁面]    自 stdin 讀取條目內容並追加（預設當週頁）
  init [頁面]               若當週頁不存在則建立（僅含標題）
  delete <頁面>             刪除指定頁面
 環境變數：WORKLOG_HOST（必要）、WORKLOG_REPO（必要）、GITEA_TOKEN（選用，會自動 fallback）
 """
 def _env():
    """讀取並檢查必要環境變數，回傳 (host, repo)；缺少時結束程式。"""
    host = os.environ.get("WORKLOG_HOST", "").strip()
    repo = os.environ.get("WORKLOG_REPO", "").strip()
    if not host or not repo:
        log("ERR", "缺少 WORKLOG_HOST 或 WORKLOG_REPO")
        sys.exit(2)
    return host, repo
 def main(argv):
    """CLI 進入點：解析子命令並執行對應 wiki 操作。"""
    if not argv or argv[0] in ("-h", "--help"):
        print(USAGE)
        return 0
    cmd = argv[0]
    if cmd == "page-name":
        print(week_page_name())
        return 0
    host, repo = _env()
    token, source = resolve_token(host, repo)
    if not token:
        log("ERR", f"無可用 token：{source}")
        return 2
    if cmd == "probe":
        log("INF", f"token 來源：{source}")
        code, body = _request("GET", f"https://{host}/api/v1/version", token, None)
        log("INF", f"Gitea 版本查詢 HTTP {code} {body[:80]}")
        status, _ = get_page(host, repo, token, week_page_name())
        log("INF", f"當週頁 {week_page_name()} 狀態：{status}")
        return 0
    if cmd == "pages":
        status, pages = list_pages(host, repo, token)
        if status != "ok":
            log("WRN" if status == "missing" else "ERR", f"頁面清單狀態：{status}")
            return 0 if status == "missing" else 1
        for item in pages:
            print(f"{item.get('title')}\t{item.get('sub_url')}")
        return 0
    if cmd == "delete":
        if len(argv) < 2:
            log("ERR", "delete 需要頁面名稱")
            return 2
        ok, msg = delete_page(host, repo, token, argv[1])
        log("INF" if ok else "ERR", msg)
        return 0 if ok else 1
    if cmd == "show":
        page = argv[1] if len(argv) > 1 else week_page_name()
        status, content = get_page(host, repo, token, page)
        if status == "ok":
            print(content)
            return 0
        log("WRN" if status == "missing" else "ERR", f"頁面 {page} 狀態：{status} {content}")
        return 0 if status == "missing" else 1
    if cmd == "init":
        page = argv[1] if len(argv) > 1 else week_page_name()
        status, _ = get_page(host, repo, token, page)
        if status == "ok":
            log("INF", f"頁面 {page} 已存在，不重建")
            return 0
        ok, msg = create_page(host, repo, token, page, week_page_header(page) + "\n", f"worklog: 初始化 {page}")
        log("INF" if ok else "ERR", msg)
        return 0 if ok else 1
    if cmd == "append":
        if len(argv) < 2:
            log("ERR", "append 需要 marker 參數")
            return 2
        marker = argv[1]
        page = argv[2] if len(argv) > 2 else week_page_name()
        entry = sys.stdin.read().strip()
        if not entry:
            log("WRN", "條目內容為空，不寫入")
            return 0
        ok, msg = append_entry(host, repo, token, page, week_page_header(page), entry, marker)
        log("INF" if ok else "ERR", msg)
        return 0 if ok else 1
    log("ERR", f"未知子命令：{cmd}")
    print(USAGE)
    return 2
 if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,284 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # 用途：工作證明自動記錄（worklog）。由支援 hook 的 CLI 觸發，
 #       抽出本輪工作內容 → 呼叫已安裝 CLI 濃縮成精簡條目 → 機密遮蔽 →
 #       追加到 Gitea wiki 的當週工作紀錄頁。工作內容全程不落地。
 # 更新時間：2026/07/27 17:27:54
 # 相依：python3、README 定義的任一 headless CLI、curl（wiki 走 Python urllib，不需 curl 亦可）。
 # 機密：token 僅由環境變數／本機憑證讀取，不 echo、不寫檔；輸出前套用遮蔽規則。
 # 退出碼：一律 0 —— hook 絕不可阻斷使用者的工作流程。
 # ==============================================================================
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 STAGE="worklog"
 SUPPORTED_CLIS="claude codex agy opencode copilot"
 FALLBACK_MODEL="claude-haiku-4-5-20251001"
 MODEL_CACHE="${HOME}/.claude/worklog/model"
 CACHE_MAX_AGE_DAYS=30
 # ------------------------------------------------------------------------------
 # 共用函式
 # ------------------------------------------------------------------------------
 log() {
  # 輸出統一格式訊息（[時間][階段][等級]: 訊息，一行一則），一律走 stderr
  local level="$1" message="$2" stamp
  stamp="$(TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S')"
  printf '[%s][%s][%s]: %s\n' "$stamp" "$STAGE" "$level" "$message" >&2
  if [ -n "${WORKLOG_ERRLOG:-}" ] && [ "$level" = "ERR" ]; then
    printf '[%s][%s][%s]: %s\n' "$stamp" "$STAGE" "$level" "$message" >> "${WORKLOG_ERRLOG}" 2>/dev/null
  fi
 }
 die_quiet() {
  # 記錄原因後以 0 結束：hook 不得阻斷使用者流程
  log "${2:-DBG}" "$1"
  exit 0
 }
 # ------------------------------------------------------------------------------
 # 遞迴防護：摘要用的子 CLI 行程可能再次觸發 Stop hook，必須在此擋掉
 # ------------------------------------------------------------------------------
 [ -n "${WORKLOG_CHILD:-}" ] && exit 0
 # ------------------------------------------------------------------------------
 # 啟用檢查：未設定 WORKLOG_* 的環境完全不動作（他人匯入 plugin 零影響）
 # ------------------------------------------------------------------------------
 [ "${WORKLOG_ENABLED:-}" = "1" ] || exit 0
 [ -n "${WORKLOG_HOST:-}" ] || die_quiet "未設定 WORKLOG_HOST，略過記錄" "WRN"
 [ -n "${WORKLOG_REPO:-}" ] || die_quiet "未設定 WORKLOG_REPO，略過記錄" "WRN"
 command -v python3 >/dev/null 2>&1 || die_quiet "找不到 python3，略過記錄" "WRN"
 select_worklog_cli() {
  # 依目前 hook/session 環境優先選擇摘要執行器；可用 WORKLOG_CLI 強制指定。
  local requested="${WORKLOG_CLI:-auto}" cli current_cli
  if [ "$requested" != "auto" ]; then
    case " ${SUPPORTED_CLIS} " in
      *" ${requested} "*) ;;
      *) die_quiet "WORKLOG_CLI 不支援：${requested}（可用：auto ${SUPPORTED_CLIS}）" "WRN" ;;
    esac
    command -v "$requested" >/dev/null 2>&1 || die_quiet "找不到 ${requested} CLI，略過記錄" "WRN"
    printf '%s' "$requested"
    return 0
  fi
  current_cli="$(detect_current_cli)"
  if [ -n "$current_cli" ]; then
    if command -v "$current_cli" >/dev/null 2>&1; then
      printf '%s' "$current_cli"
      return 0
    fi
    log "WRN" "目前環境判定為 ${current_cli}，但找不到 ${current_cli} CLI，改用可用摘要 CLI"
  fi
  for cli in $SUPPORTED_CLIS; do
    if command -v "$cli" >/dev/null 2>&1; then
      printf '%s' "$cli"
      return 0
    fi
  done
  die_quiet "找不到可用摘要 CLI（需要其一：${SUPPORTED_CLIS}）" "WRN"
 }
 detect_current_cli() {
  # 判斷實際觸發本輪 hook 的助理環境，避免 auto 因 PATH 順序誤顯其他 CLI。
  if [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_CI:-}" ] || [ -n "${CODEX_MANAGED_PACKAGE_ROOT:-}" ]; then
    printf 'codex'
    return 0
  fi
  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] || [ -n "${CLAUDE_CODE_SSE_PORT:-}" ]; then
    printf 'claude'
    return 0
  fi
  if [ -n "${AGY_SESSION_ID:-}" ] || [ -n "${AGY_WORKSPACE_ID:-}" ]; then
    printf 'agy'
    return 0
  fi
  if [ -n "${OPENCODE_SESSION_ID:-}" ] || [ -n "${OPENCODE_CONFIG:-}" ]; then
    printf 'opencode'
    return 0
  fi
  if [ -n "${COPILOT_AGENT_ID:-}" ] || [ -n "${GITHUB_COPILOT_TOKEN:-}" ]; then
    printf 'copilot'
    return 0
  fi
  return 0
 }
 run_summary_cli() {
  # 各 CLI 依 README 的 headless 指令呼叫；不把工作內容寫入檔案。
  local cli="$1" prompt="$2" model="$3"
  case "$cli" in
    claude)
      WORKLOG_CHILD=1 timeout 45 claude -p "$prompt" --model "$model" 2>/dev/null
      ;;
    codex)
      WORKLOG_CHILD=1 timeout 45 codex exec "$prompt" 2>/dev/null
      ;;
    agy)
      WORKLOG_CHILD=1 timeout 45 agy -p "$prompt" 2>/dev/null
      ;;
    opencode)
      WORKLOG_CHILD=1 timeout 45 opencode run "$prompt" 2>/dev/null
      ;;
    copilot)
      WORKLOG_CHILD=1 timeout 45 copilot -p "$prompt" 2>/dev/null
      ;;
  esac
 }
 SUMMARY_CLI="$(select_worklog_cli)"
 [ -n "$SUMMARY_CLI" ] || exit 0
 # ------------------------------------------------------------------------------
 # 讀取 hook 傳入的 JSON（session_id／transcript_path／cwd／stop_hook_active）
 # ------------------------------------------------------------------------------
 HOOK_INPUT="$(cat)"
 [ -n "$HOOK_INPUT" ] || die_quiet "hook 輸入為空，略過記錄" "WRN"
 read -r SESSION_ID TRANSCRIPT_PATH STOP_ACTIVE HOOK_CWD <<EOF_HOOK
 $(printf '%s' "$HOOK_INPUT" | python3 -c '
 import json, sys
 try:
    d = json.load(sys.stdin)
 except ValueError:
    d = {}
 print(
    d.get("session_id") or d.get("thread_id") or d.get("conversation_id") or "-",
    d.get("transcript_path") or d.get("session_path") or d.get("conversation_path") or d.get("path") or "-",
    "1" if d.get("stop_hook_active") else "0",
    d.get("cwd", "") or "-",
 )
 ')
 EOF_HOOK
 [ "$STOP_ACTIVE" = "1" ] && die_quiet "stop_hook_active 為 true，避免迴圈不重複記錄"
 if [ ! -f "$TRANSCRIPT_PATH" ] && [ -n "${CODEX_THREAD_ID:-}" ]; then
  TRANSCRIPT_PATH="$(find "${HOME}/.codex/sessions" -type f -name "*${CODEX_THREAD_ID}.jsonl" -print -quit 2>/dev/null)"
  [ -n "$TRANSCRIPT_PATH" ] || TRANSCRIPT_PATH="-"
 fi
 [ -f "$TRANSCRIPT_PATH" ] || die_quiet "找不到 transcript：${TRANSCRIPT_PATH}" "WRN"
 # ------------------------------------------------------------------------------
 # 記錄範圍：WORKLOG_SCOPE 以冒號分隔的路徑前綴，未設定則全部 session 都記
 # ------------------------------------------------------------------------------
 if [ -n "${WORKLOG_SCOPE:-}" ]; then
  in_scope=0
  IFS=':' read -r -a scopes <<< "${WORKLOG_SCOPE}"
  for scope in "${scopes[@]}"; do
    case "$HOOK_CWD" in "${scope%/}"*) in_scope=1 ;; esac
  done
  [ "$in_scope" = "1" ] || die_quiet "cwd 不在 WORKLOG_SCOPE 範圍內：${HOOK_CWD}"
 fi
 # ------------------------------------------------------------------------------
 # 專案判定：git remote 的 <owner>/<repo> 優先，其次目錄名
 # ------------------------------------------------------------------------------
 PROJECT="$(basename "$HOOK_CWD")"
 if git -C "$HOOK_CWD" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  origin="$(git -C "$HOOK_CWD" remote get-url origin 2>/dev/null)"
  if [ -n "$origin" ]; then
    cleaned="${origin%.git}"
    cleaned="${cleaned##*://}"
    cleaned="${cleaned#*@}"
    owner_repo="$(printf '%s' "$cleaned" | awk -F/ 'NF>=2 {print $(NF-1)"/"$NF}')"
    [ -n "$owner_repo" ] && PROJECT="$owner_repo"
  fi
 fi
 # ------------------------------------------------------------------------------
 # 抽出本輪內容（最後一筆使用者訊息之後），並先做一次機密遮蔽
 # ------------------------------------------------------------------------------
 TURN="$(python3 "${SCRIPT_DIR}/transcript.py" extract "$TRANSCRIPT_PATH" 2>/dev/null)"
 [ -n "$TURN" ] || die_quiet "本輪無可記錄內容"
 DURATION="$(python3 "${SCRIPT_DIR}/transcript.py" duration "$TRANSCRIPT_PATH" 2>/dev/null)"
 [ -n "$DURATION" ] || DURATION="未判定"
 # ------------------------------------------------------------------------------
 # 模型決定：只有 claude CLI 使用 WORKLOG_MODEL／快取檔；其他 CLI 使用各自預設模型
 # ------------------------------------------------------------------------------
 MODEL=""
 MODEL_NOTE=""
 if [ "$SUMMARY_CLI" = "claude" ]; then
  if [ -n "${WORKLOG_MODEL:-}" ]; then
    MODEL="${WORKLOG_MODEL}"
  elif [ -f "$MODEL_CACHE" ]; 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-doc:worklog --tune"
    else
      MODEL="$(grep -m1 -E '^model=' "$MODEL_CACHE" 2>/dev/null | cut -d= -f2- | tr -d '[:space:]')"
    fi
  fi
  if [ -z "$MODEL" ]; then
    MODEL="$FALLBACK_MODEL"
    MODEL_NOTE=" (cli: claude, model: fallback)"
    log "WRN" "無模型快取，改用保底模型，建議執行 /jsc-doc:worklog --tune"
  elif [ -z "$MODEL_NOTE" ]; then
    MODEL_NOTE=" (cli: claude)"
  fi
 else
  MODEL_NOTE=" (cli: ${SUMMARY_CLI})"
 fi
 # ------------------------------------------------------------------------------
 # 濃縮：交給選定 CLI 產出精簡條目（子行程帶 WORKLOG_CHILD=1 阻斷遞迴）
 # ------------------------------------------------------------------------------
 PROMPT="$(cat <<EOF_PROMPT
 你是工作紀錄濃縮器。輸入是一段 AI 助理與使用者的對話片段（含工具呼叫）。
 請濃縮成工作紀錄條目，規則：
 已判定專案：${PROJECT}
 已估算花費時間：${DURATION}
 1. 只輸出 6 個 markdown bullet（以「- 」開頭），不要標題、不要前言、不要結語。
 2. 六個 bullet 必須依序使用下列欄位名稱，格式固定為「- 欄位名稱：內容」：
   - 專案/任務名稱
   - 執行細節與產出
   - 花費時間
   - 任務狀態
   - 遇到的困難
   - 解決方式
 3. 使用繁體中文（台灣用語），每個 bullet 一行、不超過 90 字，聚焦「做了什麼、動到什麼、結果如何」。
 4. 保留關鍵事實：檔案／專案／指令／數量／分支／PR／議題編號；不要抄程式碼、不要貼指令全文。
 5. 花費時間優先使用「已估算花費時間」；無法判定時寫「未判定」。
 6. 若沒有遇到明確困難，遇到的困難寫「未遇到明確困難」，解決方式寫「不需額外處理」。
 7. 嚴禁輸出任何憑證與個資：token、密碼、API key、連線字串、Email、電話、姓名、身分證號。
 8. 若這段對話沒有實質工作產出（純閒聊、純提問、僅讀取資訊而未產生結論），只輸出一行：SKIP
 對話片段：
 ${TURN}
 EOF_PROMPT
 )"
 SUMMARY="$(run_summary_cli "$SUMMARY_CLI" "$PROMPT" "$MODEL")"
 if [ -z "$SUMMARY" ]; then
  log "WRN" "摘要產出為空（CLI ${SUMMARY_CLI}），略過本輪"
  exit 0
 fi
 printf '%s' "$SUMMARY" | grep -qiE '^\s*SKIP\s*$' && die_quiet "模型判定本輪無實質工作產出"
 # 第二道防線：對模型輸出再做一次機密遮蔽
 SUMMARY="$(printf '%s' "$SUMMARY" | python3 "${SCRIPT_DIR}/transcript.py" redact 2>/dev/null)"
 # 只保留 bullet 行，避免模型帶出多餘敘述
 SUMMARY="$(printf '%s\n' "$SUMMARY" | grep -E '^\s*[-*]\s+' | sed -E 's/^\s*[*]/-/' | head -6)"
 [ -n "$SUMMARY" ] || die_quiet "摘要不含合法條目，略過本輪" "WRN"
 # ------------------------------------------------------------------------------
 # 組條目並追加到當週 wiki 頁
 # ------------------------------------------------------------------------------
 STAMP="$(TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S')"
 MARKER="worklog:$(TZ='Asia/Taipei' date +'%Y%m%d%H%M%S')-${SESSION_ID:0:8}"
 ENTRY="$(printf '## %s — %s%s <!-- %s -->\n%s\n' "$STAMP" "$PROJECT" "$MODEL_NOTE" "$MARKER" "$SUMMARY")"
 export WORKLOG_HOST WORKLOG_REPO
 if printf '%s' "$ENTRY" | python3 "${SCRIPT_DIR}/wiki_api.py" append "$MARKER" 2>&1 | grep -q '\[ERR\]'; then
  log "ERR" "寫入 wiki 失敗（專案 ${PROJECT}）"
 else
  log "INF" "已記錄工作條目（專案 ${PROJECT}，CLI ${SUMMARY_CLI}）"
 fi
 exit 0
@@ -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/`。
 ## 全專案批次處理（未指定檔案時）
@@ -1,11 +1,19 @@
 ---
-name: doc-funcs
+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 草稿，或提到 doc-funcs、function 文件化、指令檔註解、workflow 文件化、XML documentation comments 時使用此 skill。
+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 與指令檔文件
-你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後優化被文件化原始碼的效能與排版，最後重建 README。請依下列階段依序完成。
+你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後保守優化被文件化原始碼的效能（排版依原本方式維持原樣，僅修正有誤處），最後重建 README。請依下列階段依序完成。
 ## 共用規範（shared plugin，必要前置）
 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
 - `/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 步：先判斷語言與生態
@@ -101,20 +109,15 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
 - workflow README 草稿：用草稿內容**覆蓋 `.gitea/workflows/readme.md`**，保留 workflow 實際設定不變，僅整理成說明文件。
 - 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。
 - 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。
- 輸出訊息格式：若該 function 或指令檔有輸出訊息（例如 log、console 輸出、echo、回傳給使用者的提示訊息），訊息格式必須統一為 `[{階段}?][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`。其中 `階段` 為選填（沿用該訊息所屬區塊的原始名稱、保留原文不翻譯，例如中文區塊名就用中文；無對應階段時省略整個 `[{階段}]` 區塊）；`等級` 必須是 `INF`/`WRN`/`ERR`/`TRC`/`DBG` 其中之一；`時間` 使用台灣時區（Asia/Taipei）。調整輸出訊息格式僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。
+- 輸出訊息格式：依 `/jsc-shared:spec-time-log` — 若該 function 或指令檔有輸出訊息，統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱不翻譯；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；時間 Asia/Taipei）；區塊階段命名（`#region`／橫幅段落名稱作為 `階段` 前綴並移除包裹／橫幅本身、僅移除標記保留指令與行為）、檔案標頭保留例外、一行一則規則皆依該 spec。調整僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。
 - 區塊內 log 的階段命名：若被調整格式的 log 被包在某個有名稱的區塊內，必須將該區塊名稱作為該 log 的 `階段` 名稱（沿用原始名稱、保留原文不翻譯），套用完成後移除標示該區塊的包裹／標題本身（僅移除標記與包裹，保留區塊內原有的指令與行為）。有名稱的區塊包含但不限於：
  - 原始碼：`#region 名稱`/`#endregion`、或其他帶名稱的包裹結構。
  - 指令檔：以「印出分隔線＋區塊標題＋分隔線」這種橫幅（banner）方式宣告的段落（例如先 echo `====`、再 echo 區塊名稱、再 echo `----`）。此時橫幅顯示的標題即為該段所有 log 的 `階段` 名稱，且必須移除這幾行印出橫幅的輸出指令，改成把 `階段` 名稱併進該段每一行訊息的前綴。
  - 例外：指令檔開頭「用途／更新日期」的檔案說明標頭（含其外框分隔線）屬於檔案標頭、不是階段區塊，必須原樣保留，不可被移除或轉成 `階段` 前綴。
 - 一行一則訊息：每一則輸出訊息（原始碼或指令檔皆適用）都必須是獨立的單行輸出指令，一則訊息對應一行；不得用任何區塊（例如多行字串、字串拼接累積成一坨、迴圈外層包住整段訊息的結構）把多則訊息包成一個輸出。原本被包成一坨輸出的多則訊息，必須拆成逐行、逐則的輸出，且每則仍套用上述統一訊息格式。
-## 第 7 步：實作註解後，優化被文件化原始碼的效能與排版
+## 第 7 步：實作註解後，保守優化效能並僅修正有誤的排版
-完成註解實作後，對「本次被文件化的原始碼」做保守的效能與排版優化：
+完成註解實作後，對「本次被文件化的原始碼」做保守的效能優化；排版**依照原本的排版方式維持原樣**，僅修正確實有誤之處：
 - 效能：在不改變對外行為與輸出的前提下，優化明顯可改善處（例如不必要的重複計算、可提前 return、低效集合操作）。任何不確定是否等價的改動一律不做，並以註解或回報標註建議人工評估。
- 排版：套用該語言/專案既有的格式化慣例（縮排、空白、括號風格、import/using 排序），不引入與專案風格衝突的格式。
+- 排版：**預設維持檔案原本的排版方式，不重排**。只有排版確實有誤時才修正，例如：縮排錯亂或與同檔明顯不一致、tab／空白混用造成語法或建置錯誤、括號／區塊對齊錯誤造成誤讀、編碼或行尾字元異常。修正僅限有誤之處並比照該檔既有慣例；不得順手重排其他正確區塊、不得對全檔套用 formatter、不得引入新的排版風格（含 import/using 重新排序）。
- 每次優化後必須執行可用的格式化/建置/測試驗證行為未被破壞；若無法執行，明確說明原因並標註風險。優化僅限本次被文件化的檔案，不擴及無關檔案。
+- 每次優化後必須執行可用的建置/測試（或至少語法檢查）驗證行為未被破壞；不得以套用全檔 formatter 作為驗證方式。若無法執行，明確說明原因並標註風險。優化僅限本次被文件化的檔案，不擴及無關檔案。
 ## 第 8 步：重建 README
@@ -167,7 +170,8 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do
 - 不要新增與文件無關的 helper、測試或重構。
 - 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。
 - function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。
 - 排版一律依照檔案原本的排版方式；只有排版確實有誤（縮排錯亂、tab／空白混用致錯、對齊錯誤造成誤讀、編碼／行尾異常）才修正該處，不得全檔重排、不得套用 formatter 改變原有風格。
 - 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內，且格式依本 skill 的 `templates/command-header.md` 範本。
- function 或指令檔若有輸出訊息，訊息格式必須統一為 `[{階段}?][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`（`階段` 選填、沿用所屬區塊原始名稱並保留原文不翻譯、`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`、`時間` 用 Asia/Taipei 時區），且不得藉此改變訊息反映的實際行為。若該 log 被包在有名稱的區塊內（含指令檔以分隔線＋標題＋分隔線宣告的橫幅段落），須將區塊名稱當作 `階段` 名稱後移除該包裹／橫幅，且僅移除包裹、保留區塊內原有指令與行為；但開頭用途/更新日期標頭不算階段區塊，必須保留。每則訊息必須一行一則、各自為獨立的單行輸出指令，不得用區塊或字串拼接把多則訊息包成一坨輸出。
+- function 或指令檔若有輸出訊息，訊息格式、區塊階段命名、檔案標頭保留與一行一則規則一律依 `/jsc-shared:spec-time-log`，且不得藉此改變訊息反映的實際行為。
 - 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
- 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。
+- 原始碼註解與 README 的語言依 `/jsc-shared:spec-output`（繁體中文為主；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文）。
@@ -1,6 +1,6 @@
 # 指令檔開頭「用途／更新時間」標頭範本
-本範本定義 doc-funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 `階段` 前綴。
+本範本定義 funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 `階段` 前綴。
 ## 佔位符
@@ -1,21 +1,29 @@
 ---
-name: doc-issues-analyze-to-file
+name: issues-analyze-to-file
-description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gitea API），彙整成一份完整需求文件，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑／專案，依需求性質填入標籤），再配合使用者指定的 repositories 或 issue 所在 repo 產生實作草稿，最後產出交付文件並依 issues 分組留言到對應 issue。當使用者要分析 issue、把需求拆成多階段 issue、依 issue 產生實作規劃或交付留言，或提到 doc-issues-analyze-to-file、issue 需求分析、issue 拆階段、tea issues、Gitea issue 留言時使用此 skill。
+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 並拆解為實作階段與交付留言
 你要讀取使用者提供的一或多筆 Gitea issue，彙整成完整需求文件，依功能拆成多個實作階段（每階段建立一個 issue），配合指定的 repositories 產生實作草稿，最後產出交付文件並依 issues 分組留言。**建立 issue 與留言屬於對外且不易復原的動作，必須先讓使用者確認過草稿再執行**。所有需求彙整、階段拆分與實作草稿一律先產生草稿檔，再詢問使用者是否實際建立 issue / 留言。請依下列階段依序完成。
 ## 共用規範（shared plugin，必要前置）
 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
 - `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。
 - `/jsc-shared:spec-execution`：不臆測／需人工確認、不擴及無關檔案。
 - `/jsc-shared:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（`Authorization: token`、分頁完整讀取）。
 ## 前置：輸入與工具
 - **輸入**：至少一筆 issue URL（可多筆）。可另外指定「repositories 位置」（本機含多個專案的資料夾）；若未指定，實作草稿以各 issue 所在的 repository 為準。
 - **工具優先序**：
  1. 若該 issue host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment` 等），並以 `--login <name> --repo <owner>/<repo>` 指定目標。
  2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定）。
- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
+- **不要依賴 `jq`**：依 `/jsc-shared:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。
 - **工作目錄**：所有草稿與文件放在 `.docs/doc-issues-analyze-to-file/`。
- **議題描述流程圖**：產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，若有助於理解，盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染），把該階段的處理流程、狀態轉移或與其他階段的相依關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。
+- **議題描述流程圖**：依 `/jsc-shared:spec-output` — 產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，有助理解就加入 Mermaid 流程圖（處理流程、狀態轉移、階段相依關係），忠實反映需求與拆分結果、不得杜撰。
 ## 第 0 步：解析 issue URL 與準備工具
@@ -122,7 +130,5 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite
 - 建立 issue 與留言是對外且不易復原的動作，**必須先經第 6 步使用者確認**；未確認前只產生本機草稿。
 - 新 issue 一律沿用來源 issue 的里程碑與專案；標籤只從既有標籤中依需求性質挑選，不自行新建（除非使用者要求）。
 - subagent 與各步驟只讀程式碼與 issue、只寫 `.docs/` 草稿，**不得修改任何原始碼**；本 skill 的產出是需求文件、階段 issue、實作草稿與交付留言，不含改動程式邏輯。
- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
+- JSON 解析（不依賴 `jq`）依 `/jsc-shared:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-shared:spec-output`。
 - 需求、階段與實作草稿若無法可靠推論，一律保守描述並標註「需人工確認」，不得編造 issue 未提及的內容。
 - 留言與交付文件不得洩漏個資（PII）；若 issue 內容含個資，於文件與留言中僅保留必要資訊或去識別化。
 - 文件、留言與草稿以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
@@ -1,15 +1,24 @@
 ---
-name: doc-issues-analyze
+name: issues-analyze
-description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取，附件內容一併納入需求分析），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時母議題必須所有子議題關閉後才可關閉，優先以 issue dependency 阻擋），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中/待處理/進行中/待測試/已完成），把議題移到「待處理」欄位（不往回移、介面不支援時改列建議清單請人工調整）；再依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
+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 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
+你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日與相依關係排序，並把排序結果留言到保存議題；**本 skill 不實作程式碼**——不修改原始碼、不 commit、不 push、不開 PR，後續實作交由 `/jsc-code:issues` 或使用者另行處理。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
 ## 共用規範（shared plugin，必要前置）
 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
 - `/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 不支援）、不往回移、不得新建欄位。
 ## 絕對準則（不可違反）
- **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、實作進度、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。例外只有兩個：（1）使用者確認實作某議題後、在該議題範圍內對**目標 repository 原始碼**進行的正常程式修改與 git commit；（2）為了讀取議題附件（圖片等二進位檔）而**唯讀暫存下載到系統暫存目錄**，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。
+- **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。例外只有一個：為了讀取議題附件（圖片等二進位檔）而**唯讀暫存下載到系統暫存目錄**，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。
 ## 前置：輸入與工具
@@ -18,9 +27,8 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
  - **議題編號**：Gitea issue 編號或 issue URL，可多筆。
  - **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。
 - **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。
- **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，實作參考以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
+- **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，程式碼分析參考（僅供研究、補充議題描述，不修改）以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
- **工具選擇**：在解析與讀取 Gitea 來源前，先檢查本機是否可用 `tea`、`tea login list` 是否有對應 login、以及環境變數 `GITEA_TOKEN` 是否已設定；接著詢問使用者要使用 `tea` 或 Gitea REST API + `curl` + token。使用者已明確指定工具時才可跳過詢問。
+- **工具選擇**：依 `/jsc-shared:spec-gitea` 的工具選擇流程（檢查 `tea`／`tea login list`／`GITEA_TOKEN` 後詢問使用者用 `tea` 或 `api`；已明確指定工具時才可跳過詢問；不依賴 `jq`，JSON 改用 tea 結構化輸出或交給 subagent 解析）。
 - **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
 - **議題必須連同留言與附件一起讀取**：處理任何議題（含專案底下展開的議題）時，除了 `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` 直接取得內容到對話中分析，不落地。
@@ -28,19 +36,11 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
  - 無法讀取的格式（或僅有 `tea` 而無 token 可下載附件）：在保存議題內容中列出附件檔名與 URL 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容。
 - **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。
 - **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
- **議題描述流程圖**：產生保存議題或小功能議題的描述時，若有助於理解，盡量在描述中加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染），把需求流程、狀態轉移或議題間的相依／阻擋關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。
+- **議題描述流程圖**：依 `/jsc-shared:spec-output` — 產生保存議題或小功能議題的描述時，有助理解就加入 Mermaid 流程圖（需求流程、狀態轉移、相依／阻擋關係），忠實反映需求與拆分結果、不得杜撰。
 ## 第 1 步：工具可用性檢查與使用方式選擇
-先檢查可用工具並選擇後續使用方式。除非使用者已明確指定 `tea` 或 `api`，否則不得自行決定。
+依 `/jsc-shared:spec-gitea` 的工具選擇流程執行：檢查 `tea`（`command -v tea`、`tea login list`，失敗記錄原因不中止）與 `GITEA_TOKEN`（只輸出「已設定／未設定」）→ 詢問使用者要用 `tea` 或 `api`（除非使用者已明確指定，不得自行決定；選 `tea` 後續仍需確認來源 host 有對應 login）→ 兩種方式都不可用則停止並回報缺少 `tea login` 或 `GITEA_TOKEN`（不要要求使用者把 token 貼進對話）。
 1. 檢查 `tea` 是否存在：`command -v tea`。
 2. 若 `tea` 存在，執行 `tea login list`，記錄可用 login 與其 host；若失敗，記錄失敗原因但不要中止。
 3. 檢查 `GITEA_TOKEN` 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容。
 4. 依檢查結果詢問使用者要使用哪一種方式：
   - `tea`：只有在 `tea` 可執行時才可選；後續解析來源後仍需確認來源 host 有對應 login。
   - `api`：只有在 `GITEA_TOKEN` 已設定時才可選；後續使用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`。
 5. 若兩種方式都不可用，停止並回報缺少 `tea login` 或 `GITEA_TOKEN`；不要要求使用者把 token 貼進對話。
 ## 第 2 步：選擇讀取來源、讀取內容並保存議題內容
@@ -90,14 +90,19 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
   - 標籤：`GET {base}/labels`（tea：`tea labels list`）
   - 里程碑：`GET {base}/milestones`（tea：`tea milestones list`）
   - 專案（若該 Gitea 版本有此 API）：`GET {base}/projects`；若不支援就記錄「此 Gitea 版本不支援 project API，需人工處理」。
-7. 把所有來源內容彙整成保存議題內容，使用 `tea` 或 Gitea API 建立或更新保存議題；不得寫入本機草稿檔。保存議題描述至少包含：
+7. **需求釐清（產生保存議題前的必要關卡）**：讀取完所有來源後、建立或更新保存議題前，必須先完整釐清需求才可以繼續：
   - 逐一盤點來源內容中所有不清楚、有歧義、互相矛盾、缺少上下文或無法確定的部分（包含：需求範圍不明、驗收條件缺漏、來源之間說法不一致、附件無法讀取造成的資訊缺口、名詞或系統指涉不明等）。
   - 只要有**任何**不清楚的部分，都必須以 AskUserQuestion 或對話詢問使用者，直到全部釐清；問題可分批詢問，但不得略過任何一項。
   - **絕對不可以幻想**：不得用臆測、腦補或「合理推測」填補資訊缺口來代替詢問；使用者明確表示某項「先保留、之後再確認」時，才可在保存議題中將該項標註「需人工確認」後繼續。
   - 所有不清楚的部分都已由使用者釐清（或明確指示保留標註）之前，不得進入下一項建立或更新保存議題。
 8. 把所有來源內容彙整成保存議題內容，使用 `tea` 或 Gitea API 建立或更新保存議題；不得寫入本機草稿檔。保存議題描述至少包含：
   - 來源清單：每筆專案／議題／檔案的來源資訊、標題或名稱、狀態、現有 labels／milestone／project（若適用），以及議題的留言數與附件清單（檔名；無法讀取的附件標註「需人工確認」）。
   - 完整需求描述：整合專案、議題（含留言與附件內容）、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
   - 驗收條件／預期結果：能從來源內容推得的，逐條列出；不能確定的標註「需人工確認」。
   - 保存議題分類：labels／milestone／project 掛載方式。
   - `## TODO`：根據保存議題描述內容產生 Markdown checklist，放在描述最後。
-需求彙整只做整理與歸納，不得編造來源內容未提及的需求；無法確定處保守描述並標註。
+需求彙整只做整理與歸納，不得編造來源內容未提及的需求；無法確定處必須依上方「需求釐清」關卡先詢問使用者，只有使用者明確指示保留的項目才可標註「需人工確認」後寫入。
 ## 第 3 步：拆分小功能議題
@@ -120,25 +125,15 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
 **分析完成後：把議題移到看板「待處理」欄位**。保存議題與所有小功能議題都建立／更新完成後（即分析階段結束），對其中**確實屬於某個專案看板（project board）**的議題調整進度欄位：
- 若看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，語意相近即可對應，不得假設看板一定有這五欄），把議題移動到「待處理」欄位，代表需求分析已完成、等待實作。
+- 依 `/jsc-shared:spec-project-board` 執行（欄位語意以看板實際名稱為準、不往回移、先 GET 探測端點且 404／501 視為不支援、不得對未確認端點寫入、不得新建欄位）：把議題移動到「待處理」欄位，代表需求分析已完成、等待實作；議題已在「待處理」或更後面的欄位時維持原欄位。
- **不往回移**：議題已在「待處理」或更後面的欄位（進行中／待測試／已完成）時維持原欄位，只有在「分析中」或未指定欄位時才移動。
+- 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳。
 - 移動前先探測可用介面：`tea` 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測端點是否存在（404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。
 - 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳；不得新建欄位。
-## 第 4 步：依到期日排序並逐議題實作
+## 第 4 步：依到期日排序並交棒實作
 將第 3 步產生的小功能議題依到期日由早到晚排序；若到期日相同，依相依關係排序，前置議題必須排在後置議題前。排序結果必須使用 `tea` 或 Gitea API 留言到保存議題或相關小功能議題，不得寫入本機檔案。
-開始實作前必須逐個議題詢問使用者，至少提供該議題的標題、URL（若已建立）、到期日、相依關係、預計修改範圍與驗證方式。未取得使用者確認前，不得修改任何原始碼、不得 commit、不得 push、不得開 PR。使用者確認開始實作某一議題後，即授權在該議題範圍內自行 commit、push 工作分支並開 PR，不需要對每個 git 動作再次詢問。
+**本 skill 的範圍到「議題拆分完成＋排序留言」為止，不實作程式碼**：不修改任何原始碼、不 commit、不 push、不開 PR、不關閉議題。排序留言完成後：
-使用者確認某一議題後，才可對該議題執行：
+- 回報整體結果：保存議題連結、小功能議題清單（標題／到期日／相依關係）、看板欄位調整狀況、標註「需人工確認」的項目。
-
+- 提示使用者後續可用 `/jsc-code:issues` 對這些小功能議題逐項實作（該 skill 會彙整 TODO、逐項實作並留言進度）；是否實作、何時實作由使用者另行決定，不在本 skill 範圍內。
- 建立或切換工作分支，分支名稱應包含議題編號或小功能識別。
+- **子母議題關閉規則的後續遵守**：提醒使用者（或後續實作流程）——子議題全部關閉前不得關閉母議題；有 dependency 阻擋時由 Gitea 強制，否則依母議題的「關閉前檢查」人工確認。
 - 依議題描述實作，過程中定期將進度留言到該議題；至少包含開始實作、主要變更完成、驗證結果、PR 連結。
 - 只修改該議題必要範圍；若發現需要擴大範圍或改動其他議題，先停止並詢問使用者。
 - 執行適合專案的測試／建置／驗證；失敗時留言說明失敗原因與下一步。
 - 完成後提交變更並推送工作分支，向 `develop` 開 PR；若遠端沒有 `develop`，改向 `master` 開 PR。不得直接 push 到 `develop` 或 `master`。
 - PR 內容必須連結對應小功能議題，並摘要變更、測試結果、風險與需人工確認項目。
 - **關閉順序（子母議題）**：實作完成只關閉（或由 PR 合併帶關鍵字自動關閉）該小功能**子議題**，並同步勾選母議題子議題清單中的對應項目（若有）；**母議題必須等所有子議題都關閉後才可關閉** — 有 dependency 阻擋時由 Gitea 強制，否則依母議題的「關閉前檢查」人工確認。所有子議題關閉後，回報母議題已可關閉並詢問使用者是否關閉，不得擅自關閉母議題。
 若小功能議題尚未實際建立到 Gitea，本步只能產生排序與實作計畫，不得開始實作；必須先回到建立小功能議題的確認流程。
@@ -1,12 +1,21 @@
 ---
-name: doc-issues-sync
+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、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。
+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 進度與標籤
 你要讀取使用者提供的一個 Gitea **專案（project）**或**單一議題**，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。例外：輸入為專案且使用者指定「關閉專案／專案完成」時，進入**專案完成模式**（見第 1 步之後的專節），跳過標籤分組與逐議題勾稽，改為批次搬移至「已完成」並關閉議題。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只回傳同步計畫（不落地任何檔案），實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。
 ## 共用規範（shared plugin，必要前置）
 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
 - `/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 視為不支援、不得新建欄位。
 ## 絕對準則（不可違反）
 - **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（議題清單、需求分析、追加後的正文、標籤異動、勾稽結果、留言內容）一律留在**對話內容**與 **subagent 的回傳值**裡。最終產物只透過 `tea` 或 Gitea API **寫回議題正文／標籤／留言**，除此之外不產生任何本機檔案。
@@ -18,10 +27,10 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 - **工具優先序**：
  1. 若該 host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment`、`tea labels` 等），並以 `--login <name> --repo <owner>/<repo>` 指定目標。
  2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定；未設定則停下請使用者提供）。
- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
+- **不要依賴 `jq`**：依 `/jsc-shared:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。
 - **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。
- **專案進度欄位（project column）**：若議題屬於某個專案看板（project board），且看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，不得假設看板一定有這五欄），本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整；對應規則見第 3.5 步。欄位語意對不上或介面不支援時不移動，只回報建議。
+- **專案進度欄位（project column）**：依 `/jsc-shared:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。
- **議題描述流程圖**：若要補進議題正文或進度留言的內容有助於理解（例如需求流程、TODO 之間的先後／相依），盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）以視覺化呈現；流程圖必須忠實反映議題需求與 TODO 現況，不得杜撰未提及的流程。
+- **議題描述流程圖**：依 `/jsc-shared:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。
 ## 第 0 步：解析輸入、判斷專案或議題、準備工具
@@ -81,12 +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 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則（欄位名稱以看板實際名稱為準，語意相近即可對應）：
+6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc-shared:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。
   - 需求仍不明確、TODO 明顯不足以追蹤需求而需大量補列 → 「分析中」。
   - 需求與 TODO 齊全，但工作目錄中尚無任何對應實作 → 「待處理」。
   - 部分 TODO 已勾稽為完成（已有部分實作）→ 「進行中」。
   - 所有 TODO 勾稽為已完成，但仍有「需人工確認」項目或尚待驗證 → 「待測試」。
   - 所有 TODO 已完成且無需人工確認 → 「已完成」。
   回傳內容需含：目前欄位、建議欄位、判斷依據。建議欄位與目前欄位相同時標明「欄位無異動」；看板欄位語意對不上（或取不到欄位資訊）時標明「無法對應、維持原欄位」並列出實際欄位名稱，不得硬套。議題不屬於任何專案看板時跳過本項。
 每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案**），至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言內容（或「無異動」）、專案進度欄位建議（目前欄位／建議欄位／判斷依據，或「不屬於專案看板」「無法對應」）、以及所有「需人工確認」項目。
@@ -123,11 +127,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
  - 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。
 - **標籤異動**：套用建議的新增／移除。
  - tea：`tea labels`／issue 編輯對應指令；API：`POST`/`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels`（用既有 label id）。
- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，把議題移到建議欄位。
+- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc-shared:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。
  - 先探測可用介面：`tea` 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測對應端點是否存在（回 404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。
  - 介面可用 → 呼叫對應端點把議題移至建議欄位，一次一個議題並確認回應成功。
  - 介面不可用 → 不視為錯誤：跳過移動，改在第 7 步回報中列出「議題 → 建議欄位」清單，請使用者到看板手動拖曳。
  - 只在建議欄位確實存在於看板且語意對應明確時移動；有疑慮就不動並回報。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。
 - **留言**：對有 TODO 異動的議題張貼留言。
  - tea：`tea comment --repo <owner>/<repo> --login <name> <index> "<留言內容>"`；API：`POST {base}/repos/{owner}/{repo}/issues/{index}/comments`，body `{"body":"<留言內容>"}`。
  - 無異動的議題不留言。
@@ -146,8 +146,6 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 - 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。
 - subagent 與各步驟只讀檔案與議題、只回傳結構化內容，**不得在磁碟寫任何檔案、不得修改任何工作目錄原始碼**。
 - 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。
- 進度欄位調整只在議題確實屬於專案看板、建議欄位存在於看板且語意對應明確、並經第 5 步使用者確認後執行；不得新建欄位、不得對未確認存在的 API 端點做寫入。介面不支援時只回報建議清單，不視為錯誤。
+- 進度欄位調整依 `/jsc-shared:spec-project-board`，且必須經第 5 步使用者確認後執行。
 - 專案完成模式只在輸入為專案且使用者**明確**指定關閉／完成時進入；語意不明就用 AskUserQuestion 確認，不得自行認定。批次關閉議題前必須經使用者確認；含未完成 TODO 的議題要在確認時明確標出。不得透過此模式關閉不屬於該專案的議題。
- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
+- JSON 解析（不依賴 `jq`）依 `/jsc-shared:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-shared:spec-output`。
 - 留言與回傳內容不得洩漏個資（PII）；若議題內容含個資，於回傳內容與留言中僅保留必要資訊或去識別化。
 - 回傳內容與留言以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
@@ -0,0 +1,46 @@
 ---
 name: notifications
 description: 讀取 Gitea 通知，依通知類型分組後逐組執行；若沒有通知就直接結束；先從目前工作區的 REVIEW.md 找對應流程，找不到就詢問使用者怎麼處理，並把缺少流程的通知類型附加回 REVIEW.md。當使用者要整理 Gitea 通知、依通知類型批次處理、照 REVIEW.md 執行通知流程、或補齊 REVIEW.md 的通知類型說明時使用此 skill。
 ---
 # 依 REVIEW.md 處理 Gitea 通知
 你要讀取目前使用者在目標 Gitea 主機上的通知，先依通知類型分組，再逐組套用 `REVIEW.md` 內定義的處理流程。若沒有通知，直接結束，不改任何檔案，也不寫回 Gitea。
 ## 第 0 步：先決條件
 1. 先依 `/jsc-shared:spec-gitea` 確認工具可用性，並決定使用 `tea` 或 Gitea REST API + `GITEA_TOKEN`。
 2. 決定 Gitea host 時，優先使用目前工作區 repo 的 `origin`，再看 `$GITEA_HOST`，都沒有才詢問使用者。
 3. 若 `tea` 可用且該 host 有對應 login，優先用 `tea`；否則用 API + `GITEA_TOKEN`。
 ## 第 1 步：讀取通知
 1. 以 `tea` 或 Gitea API 讀取目前使用者通知。
 2. 分頁要抓完整，直到沒有下一頁為止。
 3. 預設只處理 `unread` 與 `pinned` 通知；若實作環境或 `REVIEW.md` 明確要求納入其他狀態，再依需求擴充。
 4. 若沒有任何通知，直接結束。
 ## 第 2 步：依通知類型分組
 1. 以通知的 `subject.type` 分組。
 2. 同一組內依通知原始順序逐一處理。
 3. 每處理完一組才進下一組。
 ## 第 3 步：從 `REVIEW.md` 找處理流程
 1. 先讀目前工作目錄根目錄的 `REVIEW.md`。
 2. 以通知類型名稱尋找對應流程，優先找同名標題或清楚對應的段落。
 3. 找到流程就照流程執行。
 4. 找不到流程時，立刻詢問使用者這個通知類型要怎麼處理，不要自行猜。
 ## 第 4 步：處理缺流程的類別
 1. 找不到流程的通知類型要先暫存，等使用者回答後再處理。
 2. 把這個類型與使用者最後確認的處理方式附加到 `REVIEW.md`。
 3. 若 `REVIEW.md` 不存在，先詢問使用者要在 repo root 建立，還是改用其他 review 檔案。
 ## 第 5 步：執行與收尾
 1. 逐組完成後，回報本次讀到的通知總數、分組結果、已套用的流程，以及哪些通知類型沒有既有流程。
 2. 若有新增到 `REVIEW.md`，明確回報更新位置。
 3. 全程不要把通知內容寫成草稿檔或暫存檔。
@@ -0,0 +1,177 @@
 ---
 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 議題操作（用 issues-sync／issues）、專案文件化（用 funcs）。
 ---
 # worklog — 工作證明自動記錄
 把「每輪做了什麼」濃縮成一則條目，追加到 Gitea wiki 的當週工作紀錄頁。**自動記錄由相容的 `Stop` hook 完成，不需使用者同意、不需人工觸發**；本 skill 負責自動路徑之外的人工操作：初始化、模型判定、診斷、補寫、回顧。
 | 元件 | 觸發者 | 職責 |
 | --- | --- | --- |
 | `hooks/hooks.json` 的 `Stop` hook | harness 自動 | 每輪結束抽本輪內容 → 濃縮 → 遮蔽 → 追加到當週頁 |
 | 本 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` | 上述兩者共用 | 抽本輪片段、估算花費時間、機密遮蔽 |
 ### 各助理支援範圍
 | 功能 | Claude Code | Codex | Antigravity | OpenCode | GitHub Copilot |
 | --- | --- | --- | --- | --- | --- |
 | `Stop` hook 自動記錄 | ✅ | ✅ 需可讀 Codex session JSONL | ❌ | ❌ | ❌ |
 | `--init`／`--diagnose`／`--append`／`--show` | ✅ | ⚠️ 需 plugin 目錄保留 `scripts/`（安裝後請實測一次） | ⚠️ 同左 | ⚠️ 需完整 plugin 目錄 | ⚠️ 需 plugin 目錄保留 `scripts/` |
 | 摘要 CLI | `claude -p` | `codex exec` | `agy -p` | `opencode run` | `copilot -p` |
 | `--tune` | ✅ | ❌ 無 `claude-api` skill 可載入 | ❌ 同左 | ❌ | ❌ |
 兩個限制的來源：
 - **`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 行為。
 ### 腳本路徑解析（重要）
 skill 執行時的工作目錄是**使用者的專案目錄**，不是 plugin 根目錄，因此**絕不可用相對路徑呼叫腳本**。先解析出 plugin 根目錄再組絕對路徑：
 | 環境 | plugin 根目錄 |
 | --- | --- |
 | Claude Code | `${CLAUDE_PLUGIN_ROOT}` |
 | 其他助理 | 本 skill 載入時提示的 base directory（`.../skills/worklog`）往上兩層 |
 ```bash
 # Claude Code
 WORKLOG_DIR="${CLAUDE_PLUGIN_ROOT}/scripts/worklog"
 # 其他助理：以 skill base directory 推導（<base>/../.. 即 plugin 根）
 WORKLOG_DIR="<skill base directory>/../../scripts/worklog"
 ```
 以下各模式的指令一律以 `${WORKLOG_DIR}` 表示該目錄。若解析不到或該目錄不存在，回報「plugin 目錄未包含 scripts/worklog，本 skill 在此環境不可用」並停止，不要改用相對路徑重試。
 ---
 ## 共用規範（必要前置）
 執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到時先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），不安裝則中斷**：
 - `/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 特有補充：
 - **工作內容不落地**：transcript 片段只在程序記憶體與 stdin/stdout 間傳遞、wiki 走 API 不 clone，全程不產生暫存檔。唯一允許落地的是**模型快取檔** `~/.claude/worklog/model`（僅含模型 id 與判定時間，不含任何工作內容）。
 - **絕不阻斷**：hook 路徑任何失敗都以 exit 0 結束，只在 stderr 留訊息。
 ---
 ## 環境變數
 | 變數 | 必要 | 說明 | 未設定 |
 | --- | --- | --- | --- |
 | `WORKLOG_ENABLED` | ✅ | 總開關，設為 `1` 才啟用 | hook 立即結束，完全不動作 |
 | `WORKLOG_HOST` | ✅ | Gitea 主機，如 `gitea.housefun.com.tw` | 不啟用 |
 | `WORKLOG_REPO` | ✅ | wiki 所在 repo，如 `H3285/WorkLog` | 不啟用 |
 | `WORKLOG_MODEL` |  | 強制指定摘要模型 | 讀快取檔 → 保底 `claude-haiku-4-5-20251001` |
 | `WORKLOG_CLI` |  | 摘要執行器：`auto`／`claude`／`codex`／`agy`／`opencode`／`copilot` | `auto`，先依目前 hook/session 環境判斷正在使用的 CLI，判斷不到或該 CLI 不可執行時才 fallback 到已安裝工具 |
 | `WORKLOG_SCOPE` |  | 冒號分隔的路徑前綴，僅這些路徑下的 session 才記 | 全部 session 都記 |
 | `WORKLOG_ERRLOG` |  | 錯誤訊息額外寫入的檔案路徑（只記錯誤、不含工作內容） | 只走 stderr |
 **token 不需另設變數**，依固定優先序自動解析並實際驗證：
 ```
 GITEA_TOKEN →（對目標 host 驗證失敗時）→ tea 設定檔中該 host 的 token → ~/.git-credentials
 ```
 ---
 ## 模式
 ### `--init`
 1. 執行 `python3 "${WORKLOG_DIR}/wiki_api.py" probe`，回報 token 來源、Gitea 版本、當週頁狀態。
 2. 當週頁不存在 → 執行 `python3 "${WORKLOG_DIR}/wiki_api.py" init` 建立（wiki 尚未初始化時一併初始化）。
 3. 以表格印出應寫入 `~/.bashrc` 的 `WORKLOG_*` 變數清單；**不自動改使用者的 shell profile**（需人工確認的狀態變更）。
 ### `--tune`（Claude Code 專屬）
 決定「目前最適合的摘要模型」並快取，`Stop` hook 只讀快取、**絕不自行呼叫 AI 判斷**（否則就變成雞生蛋，還會拖慢使用者的等待路徑）。
 本模式需要 Claude Code 內建的 `claude-api` skill 與 `claude` CLI，**其他助理無法執行**：請改為手動設定 `WORKLOG_MODEL` 環境變數指定模型，或沿用保底模型。
 | 步驟 | 動作 |
 | --- | --- |
 | 1 | 以 Skill 工具載入 `claude-api` 取當下模型清單與定價，**不憑記憶** |
 | 2 | 依本任務條件評分：延遲敏感（在使用者等待路徑上）、輸出短篇六欄工作紀錄、需嚴守機密過濾指令、每輪都跑一次故成本敏感 |
 | 3 | Smoke test：`WORKLOG_CHILD=1 claude -p "回 OK" --model <選定 id>` 確認該模型在此帳號可用 |
 | 4 | 寫入 `~/.claude/worklog/model`（`model=<id>`、`tuned_at=<時間>`、`reason=<一行理由>`），並回報選擇與理由 |
 快取超過 **30 天** 視為過期：hook 改用保底模型，並在條目標記 `(model: fallback)`，`--diagnose` 會提醒重跑 `--tune`。
 ### `--diagnose`
 逐項檢查並以表格回報，用於「hook 沒有寫入 wiki」時定位：
 | 檢查項 | 判準 |
 | --- | --- |
 | `python3`／摘要 CLI | `python3` 與 `WORKLOG_CLI` 指定或 auto 選到的 CLI 是否找得到 |
 | `WORKLOG_*` 變數 | 必要三項是否齊全、`WORKLOG_SCOPE` 是否把當前路徑排除 |
 | `scripts/worklog` 目錄 | `${WORKLOG_DIR}` 是否解析成功且三支腳本存在（不存在＝此助理不支援） |
 | token | `python3 "${WORKLOG_DIR}/wiki_api.py" probe` 的 token 來源與驗證結果 |
 | wiki API | Gitea 版本、`repos/<repo>` 與當週頁狀態 |
 | 摘要設定 | `WORKLOG_CLI`、選到的 CLI、Claude 模型快取是否存在與是否過期 |
 | hook 註冊 | `hooks/hooks.json` 是否存在且 plugin 已啟用 |
 ### `--append "<內容>"`
 手動補寫一筆（hook 漏記、離線工作、或事後補充）。條目格式與自動路徑一致：
 ```
 ## <時間> — <專案> <!-- worklog:<時間戳>-manual -->
 - 專案/任務名稱：<專案或任務>
 - 執行細節與產出：<做了什麼、動到什麼、產出為何>
 - 花費時間：<實際耗時或未判定>
 - 任務狀態：<完成／進行中／待確認／受阻>
 - 遇到的困難：<困難或未遇到明確困難>
 - 解決方式：<處理方式或不需額外處理>
 ```
 專案取當前工作目錄的 `<owner>/<repo>`；內容仍會過 `python3 "${WORKLOG_DIR}/transcript.py" redact` 遮蔽後才寫入。
 ### `--show`
 讀當週頁（`python3 "${WORKLOG_DIR}/wiki_api.py" show`）並以表格摘要本週工作，用於回顧與週報。
 ---
 ## 條目與頁面格式
 - **週以星期六起算（六～五）**，因此換頁一律發生在星期六，與星期對齊。
 - 週頁名稱：`Worklog-<yyyy>-<MM>-W<n>`，`n` ＝該週起始的星期六是當月第幾個星期六（例：`2026/07/29 三` 屬於 `07/25 六` 那一週 → `Worklog-2026-07-W4`）。
 - 跨月的一週歸屬**起始星期六**所在的月份，確保同一週只有一頁（例：`2026/08/29 六 ～ 09/04 五` 全部寫入 `Worklog-2026-08-W5`）。
 - 頁首標題：`# <yyyy> 年 <MM> 月 第 <n> 週工作紀錄（<起始日> 六 ～ <結束日> 五）`，日期範圍讓人一眼看出這頁涵蓋哪幾天。
 - 每筆條目：`## <時間> — <專案>` ＋六個固定 bullet（專案/任務名稱、執行細節與產出、花費時間、任務狀態、遇到的困難、解決方式）；標題行尾帶 HTML 註解 marker（`<!-- worklog:… -->`）供寫後驗證與去重，wiki 渲染時不顯示。
 - 多 session 同時寫入：`append_entry` 採「讀取 → 合併 → 寫回 → 寫後讀取驗證 marker」，未落地則重讀最新內容重試，最多 3 次。
 ---
 ## 機密與 PII（兩道防線）
 | 防線 | 位置 | 內容 |
 | --- | --- | --- |
 | 1 | 濃縮提示詞 | 明令不得輸出 token／密碼／API key／連線字串／Email／電話／姓名／身分證號 |
 | 2 | `transcript.py` 的 `redact` | 正則遮蔽：URL 內嵌憑證、40 字元 hex token、`gh?_`／`sk-` token、`token=`／`password=`、`Authorization:`、Email、台灣手機、身分證號 |
 第二道防線不可移除 —— 模型有可能沒遵守指令，而 wiki 一旦寫入就留在 git 歷史裡。
 ---
 ## 呼叫方式
 | 助理 | 呼叫 |
 | --- | --- |
 | 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` |
Author	SHA1	Message	Date
admin	59426af440	Merge pull request 'sync' (#46 ) from master into develop Reviewed-on: #46	2026-08-05 13:52:43 +00:00
admin	9c55f5ae6d	Merge pull request 'chore(plugin 版本): 升版 0.0.4 並更新 notifications' (#45 ) from agent/notifications-empty-review into master Reviewed-on: #45 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-08-05 13:52:15 +00:00
jiantw83	ad3be35445	chore(plugin 版本): 升版 0.0.4 並更新 notifications	2026-08-05 13:51:06 +00:00
admin	48281c0985	Merge pull request '新增 notifications skill 與 manifest 對齊' (#44 ) from develop into master Reviewed-on: #44 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-08-05 13:38:31 +00:00
jiantw83	b4524011b3	feat(notifications): 新增 Gitea 通知處理流程	2026-08-05 13:36:45 +00:00
jiantw83	c42c4a8b09	chore(plugin 版本): 對齊通知 skill 的 manifest	2026-08-05 13:36:45 +00:00
admin	186f140860	Merge pull request 'docs(worklog): clarify Codex hook lookup order' (#43 ) from pr/doc-master-sync-20260731 into master Reviewed-on: #43 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-31 17:38:13 +00:00
jiantw83	7b2ab8bf38	refactor(shared): switch doc skills to jsc-shared	2026-07-31 17:36:08 +00:00
jiantw83	7ee80a87ee	docs(doc): fix stale install paths	2026-07-31 17:13:59 +00:00
jiantw83	55fa8e7bf4	docs(worklog): clarify Codex hook lookup order	2026-07-31 17:00:01 +00:00
JefferyandClaude Opus 5	bd4b9b7a51	chore(plugin 版本): 三家 manifest 升版 0.0.2 master 現行版本為 0.0.1，本次 patch +1。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-29 19:09:23 +08:00
JefferyandClaude Opus 5	975ac7886e	fix(worklog): 週頁改為星期六起算，換頁與星期對齊舊規則以 ceil(日/7) 分週，換頁點固定落在每月 8／15／22／29 號，會把同一個工作週切成兩頁（例：2026/07/28 二在 W4、07/29 三卻跳到 W5）。使用者開著舊頁時看不到新條目，會誤判成 worklog 停止記錄。 - 週以星期六起算（六～五），週頁以該週起始的星期六為錨點命名 - W<n> 的 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) <noreply@anthropic.com>	2026-07-29 19:09:18 +08:00
admin	e9c021adbe	Merge pull request 'refactor(plugin 命名空間): plugin 更名 jsc-doc、hooks 只註冊 worklog' (#42 ) from develop into master Reviewed-on: #42 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-28 09:17:29 +00:00
JefferyandClaude Opus 5	814e81e037	chore(plugin 版本): 更名視為新 plugin，版號重置 0.0.1 plugin 更名後，各助理以 <plugin 名>@<marketplace 名> 作為安裝識別鍵，新名與舊名是兩筆獨立條目：舊 plugin 會被移除、新 plugin 為首次安裝，兩者之間不存在版本比較，因此不會發生版本倒退，「版本單調遞增」不適用。依 spec-plugin-version「新 plugin 首發 0.0.1」，三份 manifest 版號一律重置為 0.0.1，不沿用舊名 jsc 的版本序列。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 17:15:23 +08:00
JefferyandClaude Opus 5	67106b22c3	refactor(plugin 命名空間): plugin 更名 jsc-doc、hooks 只註冊自己擁有的 worklog - 五份 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) <noreply@anthropic.com>	2026-07-28 17:07:14 +08:00
admin	cd2d38f0b8	Merge pull request 'fix(worklog): 修正 auto 模式的 CLI 判斷' (#41 ) from develop into master Reviewed-on: #41 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-28 08:14:33 +00:00
JefferyandClaude Opus 5	a1e68dafaf	chore(plugin 版本): 三家 manifest 升版 0.2.6 hooks/hooks.json 有變更，需升版才會重建版本化快取目錄並被載入。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 14:21:24 +08:00
JefferyandClaude Opus 5	7b04cc6be6	feat(hooks): hooks.json 統一為合併超集並改用跨 cache 解析器同名 plugin（三個 repo 都叫 jsc）只有一份 hooks.json 會生效，無法預期哪一份會贏，因此三家必須同步為同一份超集。本次補上 role 的 SessionStart 與 Stop hook，避免 doc 贏得註冊時角色載入與記憶記錄靜默消失。 worklog 的 Stop 指令同步改用新解析器：先驗證 CLAUDE_PLUGIN_ROOT 下腳本存在，再依「擁有者 marketplace 優先 → 全 cache 後援」搜尋 ~/.claude 與 ~/.codex 快取。舊版在 CLAUDE_PLUGIN_ROOT 為空時只搜 ~/.codex，非 Claude Code 的 CLI 會找不到腳本。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 14:21:24 +08:00
Jeffery	2a24910790	fix(worklog): 修正 auto 模式的 CLI 判斷	2026-07-27 17:30:50 +08:00
admin	4f76c40c1b	Merge pull request 'fix(worklog): 修正 Codex stop hook 執行路徑' (#40 ) from develop into master Reviewed-on: #40 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-27 09:19:15 +00:00
Jeffery	01b890c21e	feat(worklog): 支援 README 定義的摘要 CLI	2026-07-27 17:09:11 +08:00
Jeffery	2abe236c35	fix(worklog): 避免 Codex stop hook 執行 Claude 專用路徑	2026-07-27 16:44:57 +08:00
Jeffery	9fa1abbb6f	docs(README): 改用 Copilot CLI plugin 指令	2026-07-27 16:37:56 +08:00
admin	49be143c11	Merge pull request 'feat(worklog): 移入工作紀錄並補 Copilot 說明' (#39 ) from develop into master Reviewed-on: #39 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-27 08:31:29 +00:00
Jeffery	f2e6176921	feat(worklog): 移入工作紀錄並補 Copilot 說明	2026-07-27 16:24:54 +08:00
admin	8391d4330a	Merge pull request 'docs(README): 統一新增 skill 步驟與前綴說明措辭' (#38 ) from develop into master Reviewed-on: #38 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-17 05:56:57 +00:00
Jeffery	98c45c78d5	docs(README): 統一新增 skill 步驟與前綴說明措辭	2026-07-17 13:47:12 +08:00
admin	257f77ba68	Merge pull request 'docs(doc-issues-analyze): 更新說明為分析後排序留言、實作改由 code-issues 負責' (#37 ) from develop into master Reviewed-on: #37 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-17 05:35:37 +00:00
Jeffery	1015f80d70	docs(doc-issues-analyze): 更新說明為分析後排序留言、實作改由 code plugin 的 code-issues 負責	2026-07-17 11:56:16 +08:00
admin	0ad1a173fe	Merge pull request 'refactor(skills 共用規範): 抽出共用規範至 generic spec-* 並升版 0.2.2' (#36 ) from develop into master Reviewed-on: #36 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-17 03:27:18 +00:00
JefferyandClaude Fable 5	2dcc5f3ad0	chore(plugin 版本): 三家 manifest 升版 0.2.2 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-17 08:58:07 +08:00
JefferyandClaude Fable 5	847efa03b9	refactor(skills 共用規範): 抽出共用規範至 generic spec-*，以引用＋一行 fallback 摘要取代重複內容 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-17 08:58:07 +08:00
admin	4ef3c39030	Merge pull request 'docs(doc-issues-analyze): 產生保存議題前必須完整釐清需求（v0.2.1）' (#35 ) from develop into master Reviewed-on: #35 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-16 07:37:54 +00:00
JefferyandClaude Fable 5	46e6c0ca7d	chore(plugin 版本): bump 至 0.2.1 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-16 15:11:05 +08:00
JefferyandClaude Fable 5	1cff45bb1f	docs(doc-issues-analyze): 產生保存議題前必須完整釐清需求，不清楚處一律詢問、不得臆測 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-16 15:11:05 +08:00
admin	9034ac978e	Merge pull request '同步 doc-funcs 與 doc-issues skills 更新' (#34 ) from develop into master Reviewed-on: #34 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-16 04:44:36 +00:00
Jeffery	aa3a5bfb43	chore(plugin 版本): bump 至 0.2.0	2026-07-16 12:43:47 +08:00
Jeffery	6c5033579b	chore(plugin 版本): bump 至 0.1.10	2026-07-16 12:42:34 +08:00
Jeffery	110f5a078d	docs(doc-funcs): 調整訊息格式說明與規則	2026-07-16 12:37:33 +08:00
admin	e0df42c10f	Merge pull request 'doc-funcs 排版依原本方式維持原樣，僅修正有誤處' (#33 ) from develop into master Reviewed-on: #33 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-16 02:49:15 +00:00
Jeffery	eb0e84981a	chore(plugin 版本): bump 至 0.1.9	2026-07-16 10:45:48 +08:00
Jeffery	58b9c04e52	feat(doc-funcs skill): 排版依檔案原本方式維持原樣，僅修正有誤處	2026-07-16 10:45:48 +08:00
admin	82dfa3ebc7	Merge pull request 'doc-issues skills 加入看板進度欄位調整、附件讀取、子母議題關閉與專案完成模式' (#32 ) from develop into master Reviewed-on: #32 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-16 02:01:26 +00:00
admin	d048b2d9de	Merge pull request 'doc-funcs 加入 Dockerfile 與 README 檔名依專案命名慣例正規化規則' (#31 ) from develop into master Reviewed-on: #31 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-16 01:08:02 +00:00
admin	6ea9daea31	Merge pull request 'doc-funcs 新增指令檔「用途／更新時間」標頭範本並同步文件與版本' (#30 ) from develop into master Reviewed-on: #30 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-15 10:32:04 +00:00
admin	3b22ccfdac	Merge pull request 'doc-issues 系列 skill 加入不落地檔案絕對準則並調整 sync 專案查詢' (#29 ) from develop into master Reviewed-on: #29 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-14 07:09:10 +00:00
admin	eb79467a7f	Merge pull request '新增 doc-issues-sync skill 並重整 doc-issues 系列 skill' (#28 ) from develop into master Reviewed-on: #28 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-14 06:19:29 +00:00
admin	3a895690c0	Merge pull request '更新 doc-funcs 流程並同步版本號' (#27 ) from develop into master Reviewed-on: #27 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-11 09:43:29 +00:00
admin	c14b862488	Merge pull request '新增 doc-issues-breakdown 議題拆分流程 skill' (#26 ) from develop into master Reviewed-on: #26 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-09 12:41:23 +00:00
admin	9c94bca84e	Merge pull request '新增 doc-issues-analyze skill：讀 issue、拆解實作階段並交付留言' (#25 ) from develop into master Reviewed-on: #25 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-07-03 03:37:43 +00:00
admin	f8d02d228c	Merge pull request 'feat(doc-funcs): 區塊階段命名擴及指令檔並改沿用原始區塊名稱' (#24 ) from develop into master Reviewed-on: #24 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-30 09:56:43 +00:00
admin	07f04b513d	Merge pull request 'feat(doc-funcs): 新增區塊階段命名與一行一則訊息輸出規則並 bump 至 0.0.9' (#23 ) from develop into master Reviewed-on: #23 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-30 09:15:10 +00:00
admin	0de2854365	Merge pull request 'chore(plugin 版本): bump 至 0.0.8' (#22 ) from develop into master Reviewed-on: #22 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-30 03:13:19 +00:00
admin	d8d11bdc62	Merge pull request 'feat(doc-funcs): 新增用途日期同區塊與輸出訊息格式兩條規則' (#21 ) from develop into master Reviewed-on: #21 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-30 03:10:02 +00:00
admin	b8ac4bcb26	Merge pull request 'chore(plugin 版本): bump 至 0.0.7' (#20 ) from develop into master Reviewed-on: #20 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-26 02:08:19 +00:00
admin	c8477d5cdf	Merge pull request 'feat(doc-funcs): 先判斷語言並新增指令檔草稿、實作前詢問與實作後優化原始碼' (#19 ) from develop into master Reviewed-on: #19 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-26 02:04:40 +00:00
admin	f8da961328	Merge pull request '更新 README.md' (#18 ) from develop into master Reviewed-on: #18 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-22 14:56:51 +00:00
admin	bad9f6563e	Merge pull request 'docs(doc-funcs): 調整 README 專案列表輸出格式' (#17 ) from develop into master Reviewed-on: #17 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-22 07:32:28 +00:00
admin	14fb203290	Merge pull request 'docs(doc-funcs): 補充 README 專案列表輸出規格' (#16 ) from develop into master Reviewed-on: #16 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-22 07:09:28 +00:00
admin	72c26eb5fc	Merge pull request '補強 README 產生規則' (#15 ) from develop into master Reviewed-on: #15 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-22 06:00:28 +00:00
admin	91b95be2b0	Merge pull request '調整 doc-funcs README 重建流程' (#14 ) from develop into master Reviewed-on: #14 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-22 05:07:36 +00:00
admin	eeea6927db	Merge pull request 'docs(doc-funcs): 排除 README 功能目錄中的單元測試方法' (#13 ) from develop into master Reviewed-on: #13 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-22 04:45:37 +00:00
admin	b3ddc1fccb	Merge pull request 'chore(plugin 版本): 更新版本號至 0.0.2' (#12 ) from develop into master Reviewed-on: #12 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-21 13:33:24 +00:00
admin	d1c13d8391	Merge pull request 'docs(doc-funcs): 讓 README 連結依 origin 產生' (#11 ) from develop into master Reviewed-on: #11 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-21 13:29:31 +00:00
admin	9ee6cf8efc	Merge pull request 'docs(doc-funcs): 改用表格呈現 README 功能目錄' (#10 ) from develop into master Reviewed-on: #10 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-20 16:13:11 +00:00
admin	1ef41e2aff	Merge pull request 'docs(doc-funcs): 調整 README 方法目錄格式' (#9 ) from develop into master Reviewed-on: #9 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-20 15:52:41 +00:00
admin	a4028e4285	Merge pull request 'docs(doc-funcs): 補充 function 文件化輸出欄位' (#8 ) from develop into master Reviewed-on: #8 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-20 14:57:28 +00:00
admin	c191164f18	Merge pull request 'docs(doc-funcs): 補強草稿檢查與清理流程' (#7 ) from develop into master Reviewed-on: #7 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-18 08:28:50 +00:00
admin	bbd03b7900	Merge pull request 'docs(plugin marketplace): 將 marketplace 名稱改為 doc' (#5 ) from develop into master Reviewed-on: #5 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-17 04:01:55 +00:00
admin	5c9748815e	Merge pull request 'chore(plugin 設定): 更新 doc plugin marketplace 與 manifest 描述' (#4 ) from develop into master Reviewed-on: #4 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>	2026-06-17 03:52:45 +00:00