From 60808af9b5b746398d67f78a270b89416c6e3885 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 22 Jun 2026 07:29:18 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(doc-funcs):=20=E8=AA=BF=E6=95=B4=20REA?= =?UTF-8?q?DME=20=E5=B0=88=E6=A1=88=E5=88=97=E8=A1=A8=E8=BC=B8=E5=87=BA?= =?UTF-8?q?=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- skills/doc-funcs/SKILL.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 69bc271..0a33e9a 100644 --- a/README.md +++ b/README.md @@ -175,7 +175,7 @@ rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ### `doc-funcs` -掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments，最後重建 README 專案列表、功能列表與使用範例；README 更新時間固定使用台灣時區（Asia/Taipei）與 `yyyy/MM/dd HH:mm:ss` 格式，專案列表會彙整專案描述、參考專案與 NuGet 套件；遇到跨專案或跨命名空間的同名型別時會在功能名稱補上模組/專案前綴，並會跳脫 Markdown 表格、link text、heading 中的 C# 泛型角括號，檢查功能列表連結與使用範例 anchor 一致後執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。 +掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments，最後重建 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、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。 - **Claude Code / Antigravity**：`/jsc:doc-funcs` - **Codex**：`$doc-funcs`，或用 `/skills` 選單 diff --git a/skills/doc-funcs/SKILL.md b/skills/doc-funcs/SKILL.md index 8b4a851..ea5dc69 100644 --- a/skills/doc-funcs/SKILL.md +++ b/skills/doc-funcs/SKILL.md @@ -28,12 +28,16 @@ description: 為目前專案的每個 function 建立 .docs/ 草稿並補齊 XML - 最終功能名稱、使用範例標題、功能描述與任何會輸出到 Markdown 表格、Markdown link text 或 heading 的文字，若包含 C# 泛型角括號，輸出前必須先做 Markdown/HTML 安全跳脫：`<` 轉為 `<`，`>` 轉為 `>`。例如 `ResponseModelExtension.WithData` 必須輸出為 `ResponseModelExtension.WithData<TData>`，`ResponseModelExtension.WithData(ResponseModel)` 必須輸出為 `ResponseModelExtension.WithData(ResponseModel<object>)`。不得在表格、link text 或 heading 中輸出裸 `WithData`、`ResponseModel`、`Dictionary` 這類泛型片段。 - README 內部 anchor id 必須用未跳脫的最終功能名稱產生安全 slug，再移除或正規化泛型標點；anchor id 不使用 `<` 或 `>`。例如 `ResponseModelExtension.WithData` 的 anchor 可為 `responsemodelextensionwithdatatdata`，`ResponseModelExtension.WithData(ResponseModel)` 的 anchor 可為 `responsemodelextensionwithdataresponsemodelobject`。同一個功能在功能列表與使用範例中必須共用同一個 anchor。 README 內容拆成三個主要區塊： - - 專案列表：必須放在功能列表前；依專案名稱列出每個非測試專案，使用 Markdown 表格呈現，欄位固定為「專案名稱」、「專案描述」、「參考專案列表」、「NuGet 套件列表」。專案描述要根據該專案公開功能列表推測總結，不要只複製專案名稱；若專案沒有可列出的公開功能，保守描述為「此專案未公開可列入 README 的功能」。參考專案列表列出該專案的 ProjectReference，格式為 `名稱 版本`，版本優先讀取被參考專案檔中的 `Version`、`PackageVersion`、`AssemblyVersion`，都沒有時寫 `未指定`；沒有參考專案時寫 `無`。NuGet 套件列表列出該專案的 PackageReference，格式為 `名稱 版本`，版本優先讀取 PackageReference 的 `Version` 屬性或子節點，其次讀取中央套件管理檔（例如 `Directory.Packages.props`）的對應版本，仍無法取得時寫 `未指定`；沒有 NuGet 套件時寫 `無`。多個項目以 `
` 分隔。 + - 專案列表：必須放在功能列表前；依專案名稱列出每個非測試專案，並在此區塊內拆成三張 Markdown 表格： + - 專案描述表：欄位固定為「專案名稱」、「專案描述」。專案描述要根據該專案公開功能列表推測總結，不要只複製專案名稱；若專案沒有可列出的公開功能，保守描述為「此專案未公開可列入 README 的功能」。 + - 參考專案表：欄位固定為「專案名稱」、「參考專案列表」。參考專案列表列出該專案的 ProjectReference，格式為 `名稱 版本`，版本優先讀取被參考專案檔中的 `Version`、`PackageVersion`、`AssemblyVersion`，都沒有時寫 `未指定`；沒有參考專案時寫 `無`。多個項目以 `
` 分隔。 + - NuGet 套件表：欄位固定為「專案名稱」、「NuGet 套件列表」。NuGet 套件列表列出該專案的 PackageReference，格式為 `名稱 版本`，版本優先讀取 PackageReference 的 `Version` 屬性或子節點，其次讀取中央套件管理檔（例如 `Directory.Packages.props`）的對應版本，仍無法取得時寫 `未指定`；沒有 NuGet 套件時寫 `無`。多個項目以 `
` 分隔。 + 三張表中的「專案名稱」都必須做成 Markdown 連結，導向目標專案 git `origin` 遠端上的該專案資料夾；連結文字使用專案名稱，連結目標使用專案檔（例如 `.csproj`）相對於目標專案根目錄的所在資料夾。若專案檔位於 repo 根目錄，連到 repo 根目錄。Gitea 類網址使用 `/src/branch//`，GitHub 類網址使用 `/tree//`；無法可靠判斷平台時，優先採 Gitea 格式。若無法可靠解析目標專案的 `origin` 遠端、目前分支或專案資料夾路徑，才退回純文字專案名稱。 - 功能列表：放在專案列表後並依專案名稱分組；每個專案使用一張 Markdown 表格呈現公開方法，欄位固定為「功能名稱」、「功能描述」。功能名稱顯示已跳脫的最終功能名稱，並需做成 Markdown 連結，導向目標專案 git `origin` 遠端上的對應檔案 function 起始行；功能描述使用已跳脫的簡單版描述，並做成 Markdown 連結，導向同一份 README 內「使用範例」區塊中該功能的標題錨點。 - 使用範例：每個功能各有一個標題，標題文字使用同一個已跳脫的最終功能名稱；標題前必須放置 ``。`id` 必須由未跳脫的最終功能名稱產生安全 slug，且功能列表中功能描述連結的 `#anchor` 必須與對應使用範例標題前的 `` 完全一致。完整版功能描述可依草稿的行為分析、``、``、`` 整理並完成必要跳脫；使用範例需展示典型呼叫方式、重要前置條件與預期結果。若無法可靠產生可執行範例，提供保守的情境式範例並標註需人工確認。 功能名稱連結必須以執行此 skill 的目標專案為準，先用 `git remote get-url origin` 取得遠端，再搭配目前分支、檔案相對於目標專案根目錄的路徑與 function 起始行號產生，不得使用本 skill repo、工作區外 repo 或硬編碼的外部 repo 座標。若 origin 是 SSH 格式（例如 `git@gitea.example.com:owner/repo.git`），需轉為對應 HTTPS 瀏覽 URL；若 origin 已是 HTTPS，沿用同一個 host 與 repo path，並移除尾端 `.git`。Gitea 類網址使用 `/src/branch//#L123`，GitHub 類網址使用 `/blob//#L123`；無法可靠判斷平台時，優先採 Gitea 格式。若無法可靠解析目標專案的 `origin` 遠端、目前分支、檔案路徑或行號，才退回純文字功能名稱；README 不必列出內部呼叫方法。 8. README 重建完成後，必須自動檢查 README 內部錨點一致性；檢查未通過時要先修正 README 再清理草稿。至少確認： - - 專案列表必須存在於功能列表之前，且欄位必須包含「專案名稱」、「專案描述」、「參考專案列表」、「NuGet 套件列表」。 + - 專案列表必須存在於功能列表之前，且必須拆成三張表：欄位為「專案名稱」、「專案描述」的專案描述表；欄位為「專案名稱」、「參考專案列表」的參考專案表；欄位為「專案名稱」、「NuGet 套件列表」的 NuGet 套件表。若能解析遠端、分支與專案資料夾，三張表的專案名稱都必須是連到遠端專案資料夾的 Markdown 連結。 - 功能列表中的每個功能描述連結 `#anchor` 都存在完全相同的 ``。 - 使用範例區塊中沒有重複的 ``。 - 使用範例區塊中沒有未被功能列表引用的 anchor。 From 53487ab5d72930f0b9d9af2ab21cf28908182cf8 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 22 Jun 2026 07:31:10 +0000 Subject: [PATCH 2/2] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20bump?= =?UTF-8?q?=20=E8=87=B3=200.0.6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 03cb382..c233f51 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.0.5", + "version": "0.0.6", "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 6ab4eb4..f2ac339 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.0.5", + "version": "0.0.6", "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 927ff59..39286e3 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.0.5", + "version": "0.0.6", "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。", "skills": "./skills/" }