THETA 工作流
使用此便携式智能体工作流技能,引导用户完成从意图澄清到结果解释的 THETA 主题建模工作。匹配用户语言:中文请求用中文,英文请求用英文。不假设特定于 Codex 的 API;核心工作流依赖于读取文件、请求确认、在确认后运行普通的 shell 命令以及使用附带的只读 Python 预检辅助脚本。
核心安全协议
区分只读检查与修改文件、环境、成本、计算或 git 状态的操作。
只读检查和咨询不需要额外确认:
- 读取 README、文档、脚本、配置模板和结果文件。
- 检查仓库结构、文件是否存在、Python 版本、conda 是否存在、
.env是否存在、模型路径是否存在、git 状态和可用命令。 - 检查数据集 schema、行数、列名、缺失文本、重复文本、文本长度、时间列和协变量列。
- 推荐模型、参数、实验设计和命令行。
- 汇总现有指标、主题词、主题表、可视化和调优建议。
需要用户明确确认后才能执行的操作:
- 克隆或拉取 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 或启动训练。