安装与环境配置

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

灵活任务输入

除了常规比例切分，CastClaw 也支持在任务描述中用两个时间戳切分训练集、验证集和测试集。每个切分时间戳都是前一段可作为历史/预测起点的最后一行；后续评估窗口可以复用更早的真实历史作为上下文，并在跳过 forecast_gap 后开始计算目标窗口。

请使用时间戳切分，通过 2025-06-30 09:30:00 与 2025-09-30 09:30:00 划分数据集。
lookback_window = 711
predicted_window = 96
forecast_gap = 57
stride = 96

预测先验与生成式预测推理

当你已经有一份外部模型或人工系统给出的预测结果时，可以使用用户自主提交预测先验功能。预测先验文件必须是完整数据集，时间列、列名、列顺序、行数和外生变量与真实数据集一致；训练集目标值保持真实值，验证集和测试集目标列可替换为已有预测先验。

CLI 基础操作

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

苏格拉底式交互

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

认知伴随式交互

适用于你希望一边运行、一边审核经验、一边纠偏的场景。系统会把阶段推进、Skill 审核、候选经验冲突和关键证据暴露给你，你可以在关键节点介入经验沉淀。

castclaw 启动选项

快捷键速查

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

forecast 工具链

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 的核心不只是执行一次预测，而是学习一套可复用的预测工作流。完整链路由四个阶段构成：任务协商与价值感知交互、离线规律学习与经验沉淀、在线慢思考推理与工作流适配、结果评估与工作流发布。

User Task
  ↓
价值感知交互（任务规格化 / 约束偏好 / 人类反馈）
  ↓
规律-经验双层学习（预测规律 / 求解经验 / 工作流评分）
  ↓
在线慢思考适配（情境识别 / 工具调用 / 反思校正）
  ↓
结果评估与发布（性能评估 / Case 级解释 / 可部署工作流）

执行角色分工（Planner / Forecaster / Critic）

Planner、Forecaster、Critic 是 CLI 中的执行入口，用来承载工作流学习框架的不同阶段。把它们看成不同岗位，而不是可互相替代的聊天窗口。

预测工作流学习主线

CastClaw 把预测任务拆成可审查的学习链路：先明确价值目标，再离线学习规律和经验，随后在线适配工作流，最后评估、解释并发布可复用流程。CLI 内部仍通过阶段切换和文件协议保证流程可追溯、可审计。

什么是人在回路

当候选经验连续没有新增价值、结果解释异常，或经验结论与领域认知明显冲突时，系统会暂停在可恢复点等待人类反馈。这不是任务失败，而是经验积累的校正窗口。

技能审核：如何介入

审核 Skill 时，重点是判断"这条经验是否真的适用于当前任务"，而不是 YAML 写得是否漂亮。关注适用条件、证据来源、失败边界和风险提示。

结果确认与干预时机

最值得人类确认的是"经验是否值得沉淀"发生变化的时候，而不是每一轮结果。

CastSense：数据诊断

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

CastFeat：特征构建

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

CastZoo：模型编排

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

Skill 是什么

Skill 是"经过分析、验证与审核的策略模板"，描述某类情境在什么条件下适合什么模型族、工具组合、搜索空间、特征模板，以及有哪些已知风险。它既是可执行策略，也是 CastClaw 沉淀求解经验和发布可复用工作流的关键资产。

Skill 文件结构

Skill 使用 YAML 表示，核心是适用条件、模型族、搜索空间、特征模板、风险项和经验备注。你可以把它理解为“某类 Case 的可复用工作流片段”。

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 是最适合第一个示例的入门数据，包含小时级负荷序列，具有稳定的日周期和周周期。

光伏发电预测

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

金融时序预测

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

常见问题

环境问题排查