昌敬零基础实操指南：从入门到独立完成全流程

读完本文，你将掌握昌敬从环境搭建、核心参数调整到任务输出的完整操作链路，并避开新手最常见的5个致命错误。

第一步：环境与依赖安装（10分钟）

昌敬并非独立软件，而是基于Python 3.9+的轻量框架。

- 打开终端，执行 `pip install changjing-core` 和 `pip install changjing-cli`。

- 验证安装：输入 `changjing --version`，若显示类似 `0.4.2` 的版本号则成功。

- 若遇到权限错误，在命令前加 `--user`，或使用虚拟环境：`python -m venv cj_env && source cj_env/bin/activate`（Windows为 `cj_env\Scripts\activate`）。

- 注意：昌敬依赖 `numpy` 和 `pandas`，若缺失会自动安装，但建议手动升级：`pip install --upgrade numpy pandas`。

第二步：创建首个昌敬项目

昌敬以“任务文件”为驱动，格式为 `.cj` 纯文本。

1. 新建文件夹 `my_cj_demo`，进入后创建 `task.cj`。

2. 用文本编辑器写入最小模板：

```

# 任务声明

project: demo

input: data.csv

steps:

- load

- clean

- output: result.json

```

3. 准备示例数据 `data.csv`（至少含两列：`id` 和 `value`）。

4. 执行 `changjing run task.cj`，终端会输出执行日志。若出现 `ERROR: step 'load' not found`，说明步骤名称需与昌敬内置模块名一致（见第三步）。

第三步：核心步骤配置与参数调整

昌敬的每个步骤都是可配置的模块，通过缩进和键值对控制。

- load 步骤：指定文件路径和编码。

```

steps:

- load:

file: data.csv

encoding: utf-8

sep: ","

```

- clean 步骤：常用参数 `dropna: true`（删除空行）、`fill_value: 0`（用0填充缺失）、`columns: ["value"]`（仅处理指定列）。

```

- clean:

dropna: true

fill_value: 0

```

- output 步骤：定义输出格式与路径。

```

- output:

format: json

path: result.json

indent: 2

```

- 调整顺序：步骤按列表顺序执行，可重复同名步骤（如先 `clean` 再 `clean`）。

- 查看所有可用模块：运行 `changjing list-steps`，会显示 `load_csv`, `drop_duplicates`, `normalize`, `aggregate` 等。

第四步：调试与查看中间结果

昌敬不提供图形界面，但支持断点式检查。

- 在 `task.cj` 的任意步骤后插入 `- debug: true`，执行时该步骤后的数据会打印到终端（最多前10行）。

- 或使用 `- save_intermediate: {path: step1.csv}` 将当前数据快照保存。

- 若报错 `TypeError: 'NoneType' object is not subscriptable`，通常是上一步输出为空，检查 `load` 的文件路径或 `clean` 是否误删了所有行。

第五步：批量任务与自动化

昌敬支持将多个 `.cj` 文件串联。

1. 创建 `master.cj`，内容为：

```

project: batch

include:

- task1.cj

- task2.cj

```

2. 执行 `changjing run master.cj`，会按顺序运行所有子任务，并共享同一内存上下文（即task1的输出可作为task2的输入，前提是步骤中定义 `output_key: shared_data`）。

3. 设置定时执行：Linux用 `crontab -e` 添加 `0 * * * * changjing run /path/master.cj`；Windows用“任务计划程序”。

第六步：常见坑与避坑指南

- 坑1：步骤名拼写错误。昌敬对大小写敏感，`Load` 和 `load` 是两回事。执行前用 `changjing list-steps` 核对。

- 坑2：忽略数据编码。CSV文件若含中文，未指定 `encoding: utf-8` 会出现乱码或 `UnicodeDecodeError`。

- 坑3：clean步骤的 `fill_value` 与 `dropna` 冲突。如果先 `dropna: true` 再 `fill_value`，后者不会生效，因为空行已被删除。顺序应为先填充再删空。

- 坑4：输出文件覆盖无提示。昌敬默认直接覆盖同名文件，若需保留历史，在 `output` 步骤加 `timestamp: true`，会自动追加时间戳。

- 坑5：内存溢出。处理超大文件（>1GB）时，默认会全部载入内存。此时应在 `load` 步骤加 `chunksize: 10000`，分块处理，但需确保后续步骤支持流式操作（多数支持，聚合类步骤除外）。

- 终极提醒：任何步骤修改后，务必重新执行 `changjing run task.cj`，昌敬不会自动检测文件变化。调试时用 `--verbose` 参数（`changjing run task.cj --verbose`）能看到每个步骤的详细执行时间和内存占用，这对定位性能瓶颈极有帮助。

现在，按上述步骤操作，你已能独立完成一个昌敬数据处理任务。若遇未知错误，先检查你的 `.cj` 文件缩进（必须用空格，不要用Tab），再查 `changjing --help` 的全局参数。祝你顺利。