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