CastClaw 用户文档
EN 返回主页

快速开始

安装与环境配置

CastClaw 通过 npm 安装，运行时同时依赖 Bun、Python 与 uv。建议先把运行时准备齐，再启动 CLI 做验证。

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

依赖 版本 用途
Bun ≥ 1.3.11 运行时与包管理器
Python ≥ 3.10 时序模型的 ML 后端
uv Latest Python 依赖管理
GPU（可选） CUDA 12.8 深度学习模型加速
Ascend NPU（可选）推荐试用 Atlas 800 A2/A3（Ascend HDK 25.5.1） 华为昇腾上的深度学习加速，鼓励优先体验国产计算算力。 
# 安装 CastClaw CLI
npm install -g castclaw

# 验证基础运行时
castclaw --version
python --version
uv --version

# 同步 Python 后端依赖
cd python && uv sync

LLM 可通过环境变量或 castclaw.json 配置，任选其一：

export ANTHROPIC_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here
export DEEPSEEK_API_KEY=your_key_here
建议

第一次上手只接一个熟悉的提供商，避免同时调试多套 API 配置。

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

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

1

准备工作目录

把 load.csv 放到独立实验目录，避免与其他任务共享 .forecast/ 状态。

2

启动 CLI

进入目录后运行 castclaw，首次进入确认模型和预算配置。

3

在 Planner 输入任务描述

明确目标列、时间粒度、预测步长和评估指标，描述越具体，Skill 草案越准。

4

审核 Skill 草案

确认模型族、搜索空间与风险提示无明显偏差后继续。

5

观察迭代与最终报告

Forecaster 执行实验循环，Critic 生成 final-report.md，留意是否出现人在回路暂停。

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

请用 load.csv 做未来 24 小时电力负荷预测；时间列为 TIMESTAMP，目标列为 LOAD，评估指标使用 MAE 与 MAPE，实验预算控制在 20 次以内。

CLI 基础操作

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

快捷键 / 区域 作用 应当关注什么
Ctrl+1 切换到 Planner 任务定义是否完整，分析报告与 Skill 草案是否合理。
Ctrl+2 切换到 Forecaster 实验是否停滞，是否持续改善，是否触发人在回路。
Ctrl+3 切换到 Critic 报告是否覆盖性能分解与下一步建议。
任务状态面板 查看当前阶段与预算 确认处于哪一阶段（Init / Analysis / Forecasting / Report）。
常见误区

CLI 是阶段驱动的任务工作台，不是单步问答界面。重点是"当前在哪个阶段，下一步由谁负责"。

CLI 命令参考

castclaw 启动选项

命令用途
castclaw 在当前目录启动 CLI，基于当前项目上下文接管预测任务。
castclaw --model anthropic/claude-sonnet-4-6 启动时显式指定主模型，临时覆盖默认配置。
castclaw --version 查看当前 CLI 版本，排查环境不一致时有用。

快捷键速查

快捷键功能
Ctrl+1切换到 Planner
Ctrl+2切换到 Forecaster
Ctrl+3切换到 Critic

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

forecast_state / forecast_task 工具

forecast_state

  • forecast_state init：初始化任务并创建 .forecast/ 目录。
  • 阶段转换强制执行，不可随意跳过，确保过程可追溯。

forecast_task

  • 面向 task.json 的任务定义辅助工具。
  • 适合在 Init 阶段确认目标列、时间列、步长与评估指标。

配置参考

CAST.md 约束文件

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

字段说明
banned_models禁用模型列表，直接排除低价值或资源不允许的模型族。
max_experiments最大实验次数，限制 Forecaster 的探索预算。
no_improve_threshold连续无改善阈值，到达后触发人在回路暂停。
eval_metric评估指标偏好，例如 MAE、MAPE 或 RMSE。
domain_notes领域背景说明，注入每个 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 风格接入兼容多家提供商，按网络环境、预算和偏好自由选择。

国际提供商

Anthropic Claude、OpenAI GPT、Google Gemini，适合有稳定海外 API 接入的环境。

国内提供商

DeepSeek、Qwen、GLM 等，适合国内网络环境和更灵活的接入策略。

部署方式

直接 API、自建推理服务或昇腾算力 API，便于企业内部统一部署。

核心概念

系统架构概览

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

User Task
  ↓
CastRuntime（执行循环、上下文管理）
  ↓
CastSkill（策略检索与选择）
  ↓
CastSense → CastFeat → CastZoo
  ↓
Reflection / Report
CastClaw 系统架构图
层级职责何时接触
CastRuntime 任务上下文管理、阶段推进、Agent Loop、文件状态同步。 启动任务、切换阶段、恢复暂停任务。
CastSkill 根据分析结果检索或生成策略，决定模型路线与搜索空间。 审核 Skill 草案、沉淀经验、复用历史策略。
Plugin Ecosystem 通过 CastSense / CastFeat / CastZoo 完成诊断、表示构建和模型编排。 分析结果解释、特征设计和模型选择。
TimeEmbed 跨任务表征、相似模式检索和经验对齐的能力底座。 通常不直接操作，影响 Skill 检索质量。

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

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

智能体核心职责关键行为
Planner 任务定义、数据诊断、阶段编排。 并发执行定性与定量分析，输出预测前报告，生成候选 Skill。
Forecaster 实验循环与策略试错。 读取历史、选配置、调用 CastFeat / CastZoo、记录反思、触发人在回路。
Critic 结果聚合与最终报告。 对比模型族表现、生成可视化与结构化结论，产出 final-report.md。

智能体运行流程

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

1

初始化（Init）

冻结 task.json，创建 .forecast/ 工作目录。后续所有实验都绑定在同一任务定义上。

2

预测前分析（Pre-forecast Analysis）

双轨并发：定性领域分析（WebSearch）+ 定量数据诊断（CastSense），融合为驱动 Skill 生成的预测前报告。

3

技能审核（Skill Audit）

Planner 生成 2–4 个 Skill 候选后暂停，等待人类审核模型路线、风险与搜索空间，再进入实验循环。

4

预测迭代（Forecasting）

读取历史最佳结果 → 选配置 → CastFeat 构建表示 → CastZoo 执行训练评估 → 反思记录 → 预算检查 → 循环。停滞时触发人在回路。

5

后置报告（Post-forecast Report）

Critic 汇总实验产物、性能分解与可视化说明，生成结构化的 final-report.md。

设计重点

CastClaw 的差异化不在"跑更多模型"，而在先分析、再审核、后迭代，并在关键节点允许人介入纠偏。

人在回路

什么是人在回路

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

节点一：任务设定确认

确认目标列、时间列、预测步长、评估指标与资源约束，防止错误任务定义被后续持续放大。

节点二：技能策略审核

确认模型族、参数搜索空间和风险提示是否合理，避免在错误方向上生成大规模实验。

节点三：实验停滞干预

注入领域先验、限制无效模型族或补充数据特征假设，再恢复迭代。

不要把人在回路理解成"重跑按钮"

有效的介入应当改变策略假设，例如限定模型族、缩窄搜索空间、说明异常日期，或补充外部约束。

技能审核：如何介入

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

审核关注点

  • 适用条件是否与数据特征匹配（强季节性、长序列、稳定频率等）。
  • 参数搜索空间是否过宽，会浪费预算在低价值区域。
  • 风险警告是否覆盖已知缺陷（小样本过拟合、分布漂移、夜间零值等）。

建议的介入方式

  • 直接删掉明显不合适的模型族，而不是让 Forecaster 用预算去证明它不合适。
  • 把已知的重要节假日、设备变更、政策事件写进领域说明。
  • 缩窄学习率、窗口长度或 patch 长度等关键搜索维度。

结果确认与干预时机

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

连续无改善 结果与领域常识冲突 最佳模型族切换 异常日期影响明显 预算即将耗尽
实用原则

如果你的介入无法改变下一轮策略，先不要介入。人在回路最有价值的地方是改变路径，而不是重复确认现状。

插件工具箱

CastSense：数据诊断

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

趋势与周期识别

检测长期趋势、日周期、周周期与多尺度周期，帮助判断优先走哪条模型路线。

异常与漂移定位

发现突变、离群点、非平稳性和分布漂移，为风险提示与人在回路干预提供依据。

结构化输出

把诊断结果沉淀为后续 Skill 检索、特征设计和模型编排都能消费的结构化 knowledge。

CastFeat：特征构建

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

lag / rolling 统计特征 频域与多尺度表示 patch / token embedding model-ready representation
理解方式

CastFeat 不是"再做一遍手工特征工程"，它把领域特征、统计特征和基础模型输入形式统一到同一条表示构建管线上。

CastZoo：模型编排

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

支持的模型族

统计模型（ARIMA、ETS、Theta）、机器学习、深度学习（Informer、PatchTST）、基础模型（Chronos、TimesFM、Moirai）。

支持的策略

单模型直接跑、多模型集成（ensemble）、先粗后细两阶段调度，或把基础模型输出作为先验信息。

Skill 技能库

Skill 是什么

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

承接历史经验

把实验中验证过的路线沉淀下来，不是每次从空白开始。

指导未来任务

为新任务缩小模型空间，让 Forecaster 从更合理的起点出发。

允许人类把关

先审核再使用，使系统进化建立在可信策略之上，而不是自动累积噪声。

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: ""
审核重点

先看 applicable_conditions 和 risks，这两部分最直接决定当前任务是否该用这份 Skill。

如何审核与沉淀 Skill

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

宁可保留少量高质量 Skill，也不要囤积大量低信号策略。Skill 库的价值在于可信，而不是数量。

/cast-creation 命令

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

适合什么时候用

你已经知道哪些模型不该用、实验预算不能超过多少次，或者有必须注入给所有 Agent 的领域说明时。

解决什么问题

避免每轮任务都口头重复约束条件，并降低 Agent 在后续阶段"忘掉限制"的概率。

使用示例

三个案例分别覆盖负荷、光伏和金融时序，帮助你建立"不同数据形态对应不同策略"的感觉。重点看数据特征、推荐 Skill 与人在回路介入点。

电力负荷预测（load.csv）

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

数据特征

小时频率，约 1.5 万条样本，强日周期（24h）与周周期（168h），夏冬峰值明显。

推荐策略

优先 deep_learning（PatchTST、iTransformer）加 foundation（Chronos）组合路线。

预期产物

看到 pre-forecast.md、实验目录与 final-report.md，说明主流程已打通。

光伏发电预测

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

数据特征与诊断重点

GEFCom2014 Solar Track 小时级数据。CastSense 应重点识别夜间零值、天气突变和季节性变化。

推荐策略与人在回路

从 statistical（Theta）+ foundation（TimesFM、Moirai）入手；人在回路重点在阴雨连续日与天气异常日的人类标注。

金融时序预测

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

推荐策略

statistical + foundation ensemble 的保守组合，避免把所有预算压在单一路线上。

人类介入重点

标注财报、政策发布或宏观冲击等重大事件日期，重点查看 CastSense 的分布漂移与结构断点提醒。

FAQ 与故障排查

常见问题

如何更换 LLM 提供商？

修改 castclaw.json 中的模型配置，或切换对应环境变量即可。

人在回路暂停后如何继续？

在 Forecaster 标签页输入反馈并提交，系统会在当前上下文中继续，不需要从头初始化。

Skill 文件在哪里管理？

默认位于 .forecast/skills/ 目录，建议把审核后的稳定 Skill 沉淀到团队共享资产库。

为什么结果不稳定？

先检查任务定义与预算是否过小，再查是否存在未标注的异常日期，最后才考虑模型优化。

环境问题排查

现象排查建议
Bun 版本不足 升级到 1.3.11 或更高版本后重新打开终端，检查 bun --version。
Python 后端报错 进入 Python 目录执行 uv sync，确认依赖被正确安装。
API Key 未生效 检查环境变量是否已 export 到当前 shell，或确认 castclaw.json 覆盖了模型设置。
阶段无法推进 检查 .forecast/ 是否缺失关键文件，尤其是 task.json 和阶段报告产物。
这份文档站按"先上手，再理解系统，再查细节"的顺序组织。第一次演示 CastClaw 建议直接从 第一个预测任务 和 智能体运行流程 开始。