Back to Details

processes

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Processes - Complete API Reference

进程 - 完整API参考

Spawn and manage background processes, long-running jobs, and scheduled tasks.
生成并管理后台进程、长时间运行任务和定时任务。

Chat Commands

聊天命令

Spawn Jobs

生成任务

/job spawn "npm run backtest"               Start background job
/job spawn "python train.py" --name ml      Named job
/job spawn "node bot.js" --restart          Auto-restart on exit
/job spawn "npm run backtest"               启动后台任务
/job spawn "python train.py" --name ml      命名任务
/job spawn "node bot.js" --restart          退出时自动重启

Manage Jobs

管理任务

/jobs                                       List all jobs
/job status <id>                            Check job status
/job output <id>                            View job output
/job output <id> --follow                   Stream output
/job stop <id>                              Stop job
/job restart <id>                           Restart job
/jobs                                       列出所有任务
/job status <id>                            查看任务状态
/job output <id>                            查看任务输出
/job output <id> --follow                   流式输出
/job stop <id>                              停止任务
/job restart <id>                           重启任务

Logs

日志

/job logs <id>                              View logs
/job logs <id> --tail 100                   Last 100 lines
/job logs <id> --since 1h                   Last hour
/job logs <id>                              查看日志
/job logs <id> --tail 100                   最后100行
/job logs <id> --since 1h                   最近1小时

TypeScript API Reference

TypeScript API参考

Create Process Manager

创建进程管理器

typescript
import { createProcessManager } from 'clodds/processes';

const processes = createProcessManager({
  // Working directory
  cwd: process.cwd(),

  // Environment
  env: process.env,

  // Limits
  maxProcesses: 10,
  maxMemoryMB: 1024,

  // Logging
  logDir: './logs/jobs',
  maxLogSizeMB: 100,

  // Storage
  storage: 'sqlite',
  dbPath: './jobs.db',
});
typescript
import { createProcessManager } from 'clodds/processes';

const processes = createProcessManager({
  // 工作目录
  cwd: process.cwd(),

  // 环境变量
  env: process.env,

  // 限制配置
  maxProcesses: 10,
  maxMemoryMB: 1024,

  // 日志配置
  logDir: './logs/jobs',
  maxLogSizeMB: 100,

  // 存储配置
  storage: 'sqlite',
  dbPath: './jobs.db',
});

Spawn Process

生成进程

typescript
// Simple spawn
const job = await processes.spawn({
  command: 'npm',
  args: ['run', 'backtest'],
  name: 'backtest-btc',
});

console.log(`Job ID: ${job.id}`);
console.log(`PID: ${job.pid}`);

// With options
const job = await processes.spawn({
  command: 'python',
  args: ['train.py', '--epochs', '100'],
  name: 'ml-training',

  // Environment
  env: {
    ...process.env,
    CUDA_VISIBLE_DEVICES: '0',
  },

  // Working directory
  cwd: '/path/to/ml-project',

  // Auto-restart
  restart: true,
  maxRestarts: 3,
  restartDelayMs: 5000,

  // Resource limits
  maxMemoryMB: 4096,
  timeoutMs: 3600000,  // 1 hour
});
typescript
// 简单生成
const job = await processes.spawn({
  command: 'npm',
  args: ['run', 'backtest'],
  name: 'backtest-btc',
});

console.log(`任务ID: ${job.id}`);
console.log(`进程ID: ${job.pid}`);

// 带配置选项
const job = await processes.spawn({
  command: 'python',
  args: ['train.py', '--epochs', '100'],
  name: 'ml-training',

  // 环境变量
  env: {
    ...process.env,
    CUDA_VISIBLE_DEVICES: '0',
  },

  // 工作目录
  cwd: '/path/to/ml-project',

  // 自动重启
  restart: true,
  maxRestarts: 3,
  restartDelayMs: 5000,

  // 资源限制
  maxMemoryMB: 4096,
  timeoutMs: 3600000,  // 1小时
});

List Jobs

列出任务

typescript
const jobs = await processes.list();

for (const job of jobs) {
  console.log(`${job.id}: ${job.name}`);
  console.log(`  Status: ${job.status}`);  // 'running' | 'stopped' | 'failed' | 'completed'
  console.log(`  PID: ${job.pid}`);
  console.log(`  Started: ${job.startedAt}`);
  console.log(`  Memory: ${job.memoryMB}MB`);
  console.log(`  CPU: ${job.cpuPercent}%`);
}
typescript
const jobs = await processes.list();

for (const job of jobs) {
  console.log(`${job.id}: ${job.name}`);
  console.log(`  状态: ${job.status}`);  // 'running' | 'stopped' | 'failed' | 'completed'
  console.log(`  进程ID: ${job.pid}`);
  console.log(`  启动时间: ${job.startedAt}`);
  console.log(`  内存占用: ${job.memoryMB}MB`);
  console.log(`  CPU占用: ${job.cpuPercent}%`);
}

Get Status

获取状态

typescript
const status = await processes.getStatus(jobId);

console.log(`Status: ${status.status}`);
console.log(`Exit code: ${status.exitCode}`);
console.log(`Runtime: ${status.runtimeMs}ms`);
console.log(`Restarts: ${status.restarts}`);
console.log(`Memory: ${status.memoryMB}MB`);
console.log(`CPU: ${status.cpuPercent}%`);
typescript
const status = await processes.getStatus(jobId);

console.log(`状态: ${status.status}`);
console.log(`退出码: ${status.exitCode}`);
console.log(`运行时长: ${status.runtimeMs}ms`);
console.log(`重启次数: ${status.restarts}`);
console.log(`内存占用: ${status.memoryMB}MB`);
console.log(`CPU占用: ${status.cpuPercent}%`);

Get Output

获取输出

typescript
// Get all output
const output = await processes.getOutput(jobId);
console.log(output.stdout);
console.log(output.stderr);

// Get last N lines
const output = await processes.getOutput(jobId, { tail: 100 });

// Stream output
const stream = processes.streamOutput(jobId);
stream.on('stdout', (data) => console.log(data));
stream.on('stderr', (data) => console.error(data));
stream.on('exit', (code) => console.log(`Exit: ${code}`));
typescript
// 获取所有输出
const output = await processes.getOutput(jobId);
console.log(output.stdout);
console.log(output.stderr);

// 获取最后N行
const output = await processes.getOutput(jobId, { tail: 100 });

// 流式输出
const stream = processes.streamOutput(jobId);
stream.on('stdout', (data) => console.log(data));
stream.on('stderr', (data) => console.error(data));
stream.on('exit', (code) => console.log(`退出: ${code}`));

Stop Job

停止任务

typescript
// Graceful stop (SIGTERM)
await processes.stop(jobId);

// Force kill (SIGKILL)
await processes.stop(jobId, { force: true });

// Stop all
await processes.stopAll();
typescript
// 优雅停止（SIGTERM）
await processes.stop(jobId);

// 强制终止（SIGKILL）
await processes.stop(jobId, { force: true });

// 停止所有任务
await processes.stopAll();

Restart Job

重启任务

typescript
await processes.restart(jobId);
typescript
await processes.restart(jobId);

Event Handlers

事件处理器

typescript
processes.on('started', (job) => {
  console.log(`Job started: ${job.name}`);
});

processes.on('stopped', (job) => {
  console.log(`Job stopped: ${job.name} (code: ${job.exitCode})`);
});

processes.on('failed', (job, error) => {
  console.error(`Job failed: ${job.name}`, error);
});

processes.on('output', (job, type, data) => {
  console.log(`[${job.name}] ${type}: ${data}`);
});
typescript
processes.on('started', (job) => {
  console.log(`任务已启动: ${job.name}`);
});

processes.on('stopped', (job) => {
  console.log(`任务已停止: ${job.name} (退出码: ${job.exitCode})`);
});

processes.on('failed', (job, error) => {
  console.error(`任务失败: ${job.name}`, error);
});

processes.on('output', (job, type, data) => {
  console.log(`[${job.name}] ${type}: ${data}`);
});

Job Status

任务状态

StatusDescription
running
Currently executing
stopped
Stopped by user
completed
Finished successfully
failed
Exited with error
restarting
Auto-restarting
状态描述
running
正在执行
stopped
被用户停止
completed
成功完成
failed
异常退出
restarting
自动重启中

Use Cases

使用场景

Run Backtest

运行回测

typescript
const job = await processes.spawn({
  command: 'npm',
  args: ['run', 'backtest', '--', '--strategy', 'momentum'],
  name: 'backtest-momentum',
});

// Wait for completion
const result = await processes.wait(job.id);
console.log(`Backtest complete: ${result.exitCode === 0 ? 'success' : 'failed'}`);
typescript
const job = await processes.spawn({
  command: 'npm',
  args: ['run', 'backtest', '--', '--strategy', 'momentum'],
  name: 'backtest-momentum',
});

// 等待完成
const result = await processes.wait(job.id);
console.log(`回测完成: ${result.exitCode === 0 ? '成功' : '失败'}`);

Train ML Model

训练机器学习模型

typescript
const job = await processes.spawn({
  command: 'python',
  args: ['train.py'],
  name: 'ml-training',
  cwd: './ml',
  maxMemoryMB: 8192,
  timeoutMs: 86400000,  // 24 hours
});

// Monitor progress
processes.streamOutput(job.id).on('stdout', (line) => {
  if (line.includes('Epoch')) {
    console.log(line);
  }
});
typescript
const job = await processes.spawn({
  command: 'python',
  args: ['train.py'],
  name: 'ml-training',
  cwd: './ml',
  maxMemoryMB: 8192,
  timeoutMs: 86400000,  // 24小时
});

// 监控进度
processes.streamOutput(job.id).on('stdout', (line) => {
  if (line.includes('Epoch')) {
    console.log(line);
  }
});

Best Practices

最佳实践

  1. Name your jobs — Easier to identify
  2. Set timeouts — Prevent runaway processes
  3. Monitor memory — Prevent OOM kills
  4. Use restart sparingly — Debug failures first
  5. Check logs — Always review output
  1. 为任务命名 — 便于识别
  2. 设置超时时间 — 防止进程失控
  3. 监控内存占用 — 防止OOM终止
  4. 谨慎使用自动重启 — 先调试失败原因
  5. 查看日志 — 务必检查输出内容