安装与环境配置

CastClaw 的快速启动流程与主页使用指南保持一致：先全局安装 CLI，再验证版本，随后进入交互式 LLM 配置并在数据集目录中启动预测。

前置依赖：Bun ≥ 1.3.11、Python ≥ 3.10、uv、至少一个 LLM API Key。

安装

# npm 全局安装（推荐）
npm install -g castclaw

验证安装

castclaw --version

配置 LLM

# 在终端中输入 castclaw，即可进入交互式配置 API Key
castclaw

# 或在 castclaw 终端内部执行 /connect 来切换不同运营商
/connect

开始预测

# 进入数据集所在目录，启动 CLI
cd /path/to/your/dataset
castclaw

CLI 启动后，在 Planner 标签页（Ctrl+1）中输入任务描述：

# 示例：初始化一个能源消耗预测任务
为 data/etth1.csv 初始化预测会话。目标列：OT，时间列：date，
预测步长：96 步，回看长度：336。采用 70/20/10 分割，使用 MSE 和 MAE 评估。

第一个预测任务（5 分钟上手）

推荐直接用 load.csv（TIMESTAMP / LOAD 字段，小时频率）快速走通主流程。目标是理解系统节奏，不是调到最优。

mkdir my-run && cd my-run
# 将 load.csv 放入当前目录后
castclaw

CLI 基础操作

CLI 是与三个智能体协同工作的命令行工作台，核心是理解"当前在哪个阶段、由谁负责"。

苏格拉底式交互

适用于任务目标还不清晰、约束条件尚未冻结的场景。CastClaw 会先通过提问帮你明确预测目标、时间粒度、外生变量、评价指标和资源预算，再进入正式执行。

认知伴随式交互

适用于你希望一边运行、一边观察、一边纠偏的场景。系统会把阶段推进、Skill 审核、实验停滞和关键结果暴露给你，你可以在关键节点即时介入。

通专融合式交互

适用于把 CastClaw 接入更大开发链路的场景。通用 AI 负责代码、环境和外围编排，CastClaw 负责时间序列预测的专业能力输出，两者通过 Skill、CLI 或插件接口协同。

castclaw 启动选项

快捷键速查

熟练使用这三个快捷键后，你会自然形成节奏：在 Planner 定义与审核，在 Forecaster 看迭代，在 Critic 看结论。

forecast_state / forecast_task 工具

CAST.md 约束文件

项目级行为约束，自动注入到每个 Agent 上下文中。承载稳定、长期、所有阶段都应知道的规则。

castclaw.json 参数

任务级或项目级默认配置入口，适合团队共享默认模型配置和预算策略。

{
  "model": "anthropic/claude-sonnet-4-6",
  "light_model": "anthropic/claude-haiku-4-5",
  "max_experiments": 20,
  "no_improve_threshold": 5
}

模型接入（LLM 配置）

CastClaw 通过 Vercel AI SDK 风格接入兼容多家提供商，按网络环境、预算和偏好自由选择。

系统架构概览

CastClaw 是四层协同结构：CastRuntime 负责执行与状态，CastSkill 负责策略选择，插件生态承担具体能力，TimeEmbed 提供表征与经验对齐。

User Task
  ↓
CastRuntime（执行循环、上下文管理）
  ↓
CastSkill（策略检索与选择）
  ↓
CastSense → CastFeat → CastZoo
  ↓
Reflection / Report

多智能体协同（Planner / Forecaster / Critic）

三个智能体是严格分工的流水线，把它们看成不同岗位，而不是可互相替代的聊天窗口。

智能体运行流程

CastClaw 把预测任务拆成五个强约束阶段，阶段切换由工具和文件协议控制，不依赖 LLM 自律性，因此流程可追溯、可审计。

什么是人在回路

当 Forecaster 连续多轮无改善、出现异常结果，或策略与领域认知明显冲突时，系统会暂停在可恢复点等待人类反馈。这不是任务失败，而是强制校正窗口。

技能审核：如何介入

审核 Skill 时，重点是判断"这套策略是否真的适用于当前任务"，而不是 YAML 写得是否漂亮。关注适用条件、搜索空间和风险提示三部分。

结果确认与干预时机

最值得人类确认的是"方向性信息"发生变化的时候，而不是每一轮实验结果。

CastSense：数据诊断

CastSense 负责回答"这个序列现在是什么状态"。它把趋势、季节性、异常和分布变化整理成结构化知识，供 Planner 生成策略时使用。

CastFeat：特征构建

CastFeat 负责回答"应该怎样把数据变成模型可用的表示"。它把原始时序转成更适配下游模型的 representation。

CastZoo：模型编排

CastZoo 负责回答"用什么模型，以及怎么组合"。它不只是模型仓库，还负责策略化调度。

Skill 是什么

Skill 是"经过分析与审核的策略模板"，描述某类数据在什么条件下适合什么模型族、搜索空间、特征模板，以及有哪些已知风险。它是系统持续进化的关键资产层。

Skill 文件结构

Skill 使用 YAML 表示，核心是适用条件、模型族、搜索空间、特征模板和风险项。

name: deep_learning_periodic
applicable_conditions:
  - 强季节性数据
  - 序列长度 > 5000
model_family: deep_learning
models: [PatchTST, iTransformer]
search_space:
  learning_rate: [1e-4, 5e-4]
  patch_len: [16, 32, 64]
feature_template: patch_token
risks:
  - 数据量不足时过拟合风险高
domain_notes: ""

如何审核与沉淀 Skill

1. Planner 基于预测前分析草拟 2–4 个候选 Skill。
2. 人类审核模型路线、适用条件和风险提示，必要时直接编辑内容。
3. 通过审核的 Skill 进入 .forecast/skills/，供当前与相似任务复用。
4. 随积累持续演化，逐步形成团队级策略资产。

/cast-creation 命令

交互式生成 CAST.md 项目约束文件。适合在任务开始前明确禁用模型、预算上限、评估偏好和领域说明。

电力负荷预测（load.csv）

load.csv 是最适合第一个示例的入门数据，包含小时级负荷序列，具有稳定的日周期和周周期。

光伏发电预测

光伏序列同时具备强日周期、夜间恒零和天气敏感性，是"需要领域知识介入"的典型案例。

金融时序预测

金融数据高波动、非平稳，对突发事件敏感，不适合盲目依赖单一深度模型路线，更需要风险意识与外部事件注入。

常见问题

环境问题排查