Communitygithub.com

CodeSoul-co/theta-skill

可移植的 THETA 智能体工作流技能,用于指导完成主题建模任务。

theta-skill 是什么?

这个技能为 AI 智能体(如 Claude Code、Cursor、Codex 等)提供了一个完整的、可移植的工作流,用于执行基于 THETA 仓库的主题建模任务。它引导智能体完成从意图澄清、环境检查、数据检查、模型选择、命令生成到结果解释和迭代调优的整个流程。该技能的核心设计理念是安全:它严格区分只读检查(如读取文件、检查目录结构)和需要显式用户确认的变更操作(如克隆仓库、安装依赖、运行训练、生成文件)。对于任何可能消耗资源、修改文件或调用云 API 的操作,技能都会要求用户通过标准化的确认格式进行确认,从而避免意外执行。技能支持多语言(中文和英文),并能根据用户的输入语言自动切换。它提供了详细的参考文档(如 workflow.md、commands.md)用于指导决策,并附带一个只读的预检脚本 inspect_theta_env.py 来帮助智能体在安全范围内了解环境状态。

兼容平台✓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 状态和可用命令。
  • 检查数据集 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 需要该路径的本地模型,并建议使用本地配置。

推荐工作流

  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 或启动训练。

相关技能