Communitygithub.com

CodeSoul-co/theta-skill

可攜帶的 THETA 代理工作流程技能

theta-skill 是什麼?

此技能(CodeSoul-co/theta-skill)為 AI 代理(如 Claude Code、Cursor、Codex)提供一個結構化的工作流程,用於執行 THETA 主題建模任務。它透過嚴格的檔案操作、環境設定、GPU 使用與 API 呼叫的確認協議,優先考量安全性。該技能支援所有主要平台,並引導使用者完成從意圖釐清到結果解讀的流程,步驟包含檢查儲存庫、以唯讀方式檢查資料集、推薦模型,並在執行任何可能造成變更或消耗資源的命令前要求明確同意。其核心運作邏輯仰賴檔案讀取、使用者提示、標準 Shell 命令,以及一個用於唯讀檢查的輔助 Python 腳本,而無需使用特定平台(如 Codex)的專有 API。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add CodeSoul-co/theta-skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

THETA 工作流程

使用這個可攜帶的代理工作流程技能,引導使用者進行從意圖釐清到結果解讀的 THETA 主題建模工作。配合使用者的語言:中文請求用中文回應,英文請求用英文回應。不假設 Codex 專用 API;核心工作流程依賴於讀取檔案、要求確認、在確認後執行一般 Shell 命令,以及使用附帶的唯讀 Python 輔助腳本。

核心安全協議

區分唯讀檢查與會修改檔案、環境、成本、運算或 git 狀態的操作。

唯讀檢查與建議不需要額外確認:

  • 讀取 README、文件、腳本、設定範本與結果檔案。
  • 檢查儲存庫結構、檔案是否存在、Python 版本、conda 是否存在、.env 是否存在、模型路徑是否存在、git 狀態以及可用的命令。
  • 檢查資料集結構、行數、欄位名稱、缺失文字、重複文字、文字長度、時間欄位與共變量欄位。
  • 建議模型、參數、實驗設計與命令列。
  • 彙整現有指標、主題詞彙、主題表、視覺化圖表與調優建議。

需要明確使用者確認後才能執行的操作:

  • 克隆或拉取 THETA 儲存庫、切換分支、提交、合併或推送。
  • 建立 conda 環境、安裝相依套件或執行 scripts/env_setup.sh。
  • 建立或編輯 .env;絕不在對話中列印、儲存或回顯 API 金鑰。
  • 設定或使用雲端嵌入提供者;雲端 API 呼叫可能產生費用並將文字暴露給外部服務。
  • 下載 Qwen、SBERT 或其他本機模型。
  • 修改、清理、轉換或寫入資料集;傾向於建立新的衍生檔案,且預設絕不修改原始資料。
  • 執行 THETA 或基線訓練、多模型比較、調優搜尋、大型本機模型、GPU 密集任務或會寫入結果的命令。
  • 產生報告檔案、覆蓋輸出結果、刪除快取、刪除模型、刪除資料或清理結果目錄。

當需要確認時,請使用此格式:

我準備執行以下操作:

操作:
<簡短動作>

命令:
<命令,如有>

影響的檔案或目錄:
<路徑>

可能的資源消耗:
<本機運算 / GPU / 儲存 / API 成本 / 無>

是否會覆蓋已有檔案:
<是 / 否>

請確認是否繼續。

對於英文使用者,請使用對應的英文格式:

I am preparing to perform the following action:

Action:
<brief action>

Command:
<command, if any>

Affected files or directories:
<paths>

Potential resource usage:
<local compute / GPU / storage / API cost / none>

Will this overwrite existing files:
<yes / no>

Please confirm whether to continue.

僅在收到明確確認(例如 確認、可以、繼續、執行、yes、proceed 或 run it)後才繼續。如果答案模稜兩可,請再次以使用者的語言提問。

如需完整的確認流程、範例與確認表格,中文請閱讀 references/confirmation-flow.zh.md,英文請閱讀 references/confirmation-flow.en.md。關於初始提問的問題,請閱讀 references/user-questions.md。

嵌入規則

僅在 zero_shot 工作流程中使用雲端嵌入,且必須在確認 API 成本、提供者、金鑰存在與資料外洩風險之後。

對於 supervised、unsupervised 或任何需要微調的工作流程,要求使用本機嵌入與本機 Qwen 相容模型路徑。如果使用者要求為可微調模式使用雲端嵌入,請解釋 THETA 在該路徑下需要本機模型,並建議改用本機設定。

建議工作流程

  1. 判斷請求是否屬於 THETA 主題建模。此路由判斷不需要確認。
  2. 在進行環境設定、資料轉換或訓練規劃之前,立即檢查是否存在可用的 THETA 儲存庫。檢查是否存在 README.md、.env.example、scripts/ 以及 src/models/run_pipeline.py。此唯讀檢查不需要確認。
  3. 如果沒有 THETA 儲存庫,第一個動作是請求確認,以克隆 https://github.com/CodeSoul-co/THETA.git。在儲存庫存在之前,請勿設定環境、安裝相依套件、建立 .env、檢查資料集或產生訓練命令。
  4. 儲存庫存在後,僅以使用者的語言詢問必要的任務問題:資料集路徑、文字欄位、語言、時間欄位、共變量、目標結果與資源限制。
  5. 唯讀檢查環境、.env 狀態與資料集。當確定性的前置檢查有用時,使用 scripts/inspect_theta_env.py。
  6. 根據資料與目標建議模型系列與參數。
  7. 產生命令供審查,但不執行。
  8. 在執行任何會造成變更、耗費成本、長時間運行、GPU 密集或寫入檔案的命令之前,使用標準格式取得明確確認。
  9. 執行後,讀取輸出並解釋主題品質、重疊度、連貫性、多樣性、獨特性以及下一步調優步驟。
  10. 在執行額外的調優實驗、寫入報告檔案、覆蓋輸出結果或刪除任何內容之前,再次確認。

呼叫行為

當代理使用此技能時,無論是透過讀取 SKILL.md、載入 skills/theta-workflow/ 目錄,還是透過命名調用(例如 $theta-workflow),都將當前工作區視為第一個候選的 THETA 儲存庫。如果當前工作區不是 THETA,則檢查使用者提供的任何路徑。如果找不到可用的儲存庫,則停在克隆確認步驟。在滿足儲存庫這個關卡之前,不要詢問資料集問題或提議環境設定。

良好的初始使用者提示:

Use the THETA Workflow skill in skills/theta-workflow to help me run THETA topic modeling on a policy-text dataset.
使用 skills/theta-workflow 里的 THETA Workflow skill 帮我跑一个政策文本主题建模流程。

如果執行環境支援命名技能語法,$theta-workflow 也是可接受的。

參考資料路由

  • 閱讀 references/workflow.md 以取得完整的端到端決策流程。
  • 在產生 THETA 命令之前閱讀 references/commands.md;它列出了當前儲存庫的進入點與確認要求。
  • 在解讀輸出檔案或建議調優時閱讀 references/result-analysis.md。
  • 在向使用者詢問資料集、語言、目標、資源或輸出偏好時閱讀 references/user-questions.md。
  • 當需要詳細的中文確認措辭或範例時,閱讀 references/confirmation-flow.zh.md。
  • 當需要詳細的英文確認措辭或範例時,閱讀 references/confirmation-flow.en.md。

前置檢查腳本

僅在進行唯讀檢查時執行此腳本:

python skills/theta-workflow/scripts/inspect_theta_env.py \
  --dataset path/to/data.csv \
  --text-column content \
  --mode zero_shot

當需要結構化輸出時,加上 --json。此腳本不得寫入檔案、安裝相依套件、呼叫 API 或開始訓練。

相關技能