第 11 章 · 从 CLI 到生产——非交互模式与 CI/CD

# 直接传 query
ling -p "分析这个项目的技术栈"
 
# 管道输入 + query
cat error.log | ling -p "分析这些错误，找出根因"
 
# 指定模型
ling -p "总结这段代码" --model claude-sonnet-4-20250514

// src/cli/parser.ts
 
import { parseArgs } from "node:util";
 
export interface CliOptions {
  print?: string;           // -p "query"
  format: "text" | "json" | "stream";
  schema?: string;          // JSON Schema 文件路径
  provider: string;
  model: string;
  maxTurns: number;
  continue: boolean;
  resume?: string;
  name?: string;
  help: boolean;
  version: boolean;
}
 
export function parseCli(argv: string[]): CliOptions {
  const { values } = parseArgs({
    args: argv.slice(2),  // 跳过 node 和脚本路径
    options: {
      print:    { type: "string",  short: "p" },
      format:   { type: "string",  short: "f", default: "text" },
      schema:   { type: "string" },
      provider: { type: "string",  default: "openai" },
      model:    { type: "string",  short: "m", default: "gpt-4o" },
      "max-turns": { type: "string", default: "10" },
      continue: { type: "boolean", short: "c", default: false },
      resume:   { type: "string",  short: "r" },
      name:     { type: "string",  short: "n" },
      help:     { type: "boolean", short: "h", default: false },
      version:  { type: "boolean", short: "v", default: false },
    },
    strict: true,
  });
 
  return {
    print:    values.print as string | undefined,
    format:   (values.format as "text" | "json" | "stream") ?? "text",
    schema:   values.schema as string | undefined,
    provider: (values.provider as string) ?? "openai",
    model:    (values.model as string) ?? "gpt-4o",
    maxTurns: parseInt(values["max-turns"] as string, 10) || 10,
    continue: values.continue as boolean,
    resume:   values.resume as string | undefined,
    name:     values.name as string | undefined,
    help:     values.help as boolean,
    version:  values.version as boolean,
  };
}

// src/cli/parser.ts（续）
 
export async function readStdin(): Promise<string | null> {
  if (process.stdin.isTTY) return null;
 
  const chunks: Buffer[] = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }
  const text = Buffer.concat(chunks).toString("utf-8").trim();
  return text || null;
}

// src/cli/print-mode.ts
 
import OpenAI from "openai";
import type { CliOptions } from "./parser.js";
import { writeOutput, writeStreamEvent } from "./output.js";
import { loadSchema, extractJson, validateAgainstSchema } from "./schema-validator.js";
 
export async function runPrintMode(
  query: string,
  options: CliOptions
): Promise<void> {
  const client = new OpenAI();
 
  let systemPrompt = "You are Ling, a coding assistant.";
 
  // 如果指定了 schema，注入约束
  let schemaConstraint: ReturnType<typeof loadSchema> | null = null;
  if (options.schema) {
    schemaConstraint = loadSchema(options.schema);
    systemPrompt += "\n\n" + schemaConstraint.promptInstructions;
  }
 
  const messages: OpenAI.ChatCompletionMessageParam[] = [
    { role: "system", content: systemPrompt },
    { role: "user", content: query },
  ];
 
  if (options.format === "stream") {
    writeStreamEvent({ type: "start", model: options.model });
  }
 
  let turns = 0;
  let finalContent = "";
 
  while (turns < options.maxTurns) {
    turns++;
 
    const response = await client.chat.completions.create({
      model: options.model,
      messages,
    });
 
    const message = response.choices[0].message;
    finalContent = message.content ?? "";
 
    if (options.format === "stream" && finalContent) {
      writeStreamEvent({ type: "text_delta", content: finalContent });
    }
 
    if (!message.tool_calls || message.tool_calls.length === 0) {
      break;
    }
 
    messages.push(message as OpenAI.ChatCompletionMessageParam);
 
    for (const toolCall of message.tool_calls) {
      if (options.format === "stream") {
        writeStreamEvent({
          type: "tool_use",
          tool: toolCall.function.name,
          args: JSON.parse(toolCall.function.arguments),
        });
      }
 
      const result = `Tool ${toolCall.function.name} executed`;
 
      messages.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: result,
      });
    }
  }
 
  // schema 约束验证
  let structuredOutput: unknown = undefined;
  if (schemaConstraint) {
    try {
      const parsed = extractJson(finalContent);
      const { valid, errors } = validateAgainstSchema(
        parsed, schemaConstraint.schema
      );
      if (!valid) {
        process.stderr.write(
          `Schema validation failed: ${errors.join(", ")}\n`
        );
        process.exit(1);
      }
      structuredOutput = parsed;
      finalContent = JSON.stringify(parsed, null, 2);
    } catch (err) {
      process.stderr.write(
        `Failed to parse structured output: ${(err as Error).message}\n`
      );
      process.exit(1);
    }
  }
 
  writeOutput(options.format, {
    content: finalContent,
    model: options.model,
    turns,
    structured_output: structuredOutput,
  });
}

// src/cli/output.ts
 
export type OutputFormat = "text" | "json" | "stream";
 
export function writeStreamEvent(event: StreamEvent): void {
  process.stdout.write(JSON.stringify(event) + "\n");
}
 
export interface StreamEvent {
  type: "start" | "text_delta" | "tool_use" | "tool_result" | "end" | "error";
  content?: string;
  tool?: string;
  args?: Record<string, unknown>;
  result?: string;
  model?: string;
  turns?: number;
}
 
export function writeOutput(
  format: OutputFormat,
  result: {
    content: string;
    model: string;
    turns: number;
    structured_output?: unknown;
  }
): void {
  switch (format) {
    case "text":
      process.stdout.write(result.content + "\n");
      break;
    case "json":
      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
      break;
    case "stream":
      writeStreamEvent({
        type: "end",
        content: result.content,
        model: result.model,
        turns: result.turns,
      });
      break;
  }
}

# text——默认，就是纯文本
$ ling -p "1+1等于几"
2
 
# json——整个结果包成 JSON
$ ling -p "1+1等于几" --format json
{
  "content": "2",
  "model": "gpt-4o",
  "turns": 1
}
 
# stream——每行一个事件，NDJSON 格式
$ ling -p "分析这个文件" --format stream
{"type":"start","model":"gpt-4o"}
{"type":"tool_use","tool":"read_file","args":{"path":"src/index.ts"}}
{"type":"tool_result","tool":"read_file","result":"..."}
{"type":"text_delta","content":"这个文件是..."}
{"type":"end","content":"这个文件是项目的入口...","model":"gpt-4o","turns":2}

{
  "summary": "这个 PR 修复了登录页面的 XSS 漏洞",
  "issues": [
    { "file": "src/auth.ts", "line": 42, "severity": "high", "message": "未转义用户输入" }
  ],
  "approved": false
}

ling -p "Review this PR" --schema review-schema.json --format json

{
  "type": "object",
  "properties": {
    "summary": { "type": "string", "description": "一句话总结" },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "line": { "type": "number" },
          "severity": { "type": "string", "enum": ["low", "medium", "high"] },
          "message": { "type": "string" }
        },
        "required": ["file", "severity", "message"]
      }
    },
    "approved": { "type": "boolean" }
  },
  "required": ["summary", "issues", "approved"]
}

// src/cli/schema-validator.ts
 
import { readFileSync } from "node:fs";
 
export interface SchemaConstraint {
  schema: Record<string, unknown>;
  promptInstructions: string;
}
 
export function loadSchema(schemaPath: string): SchemaConstraint {
  const raw = readFileSync(schemaPath, "utf-8");
  const schema = JSON.parse(raw);
 
  const promptInstructions = [
    "IMPORTANT: Your final response MUST be a valid JSON object conforming to this schema:",
    "```json",
    JSON.stringify(schema, null, 2),
    "```",
    "Do NOT include any text before or after the JSON.",
    "Do NOT wrap the JSON in markdown code fences.",
    "Output ONLY the raw JSON object.",
  ].join("\n");
 
  return { schema, promptInstructions };
}

// src/cli/schema-validator.ts（续）
 
/** 从 LLM 输出中提取 JSON */
export function extractJson(text: string): unknown {
  // 尝试直接解析
  try {
    return JSON.parse(text);
  } catch {
    // 可能被包在 ```json ... ``` 里
  }
 
  // 正则提取 code fence
  const fenceMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
  if (fenceMatch) {
    try {
      return JSON.parse(fenceMatch[1]);
    } catch { /* 继续 */ }
  }
 
  // 找第一个 { 到最后一个 }
  const start = text.indexOf("{");
  const end = text.lastIndexOf("}");
  if (start !== -1 && end > start) {
    try {
      return JSON.parse(text.slice(start, end + 1));
    } catch { /* 放弃 */ }
  }
 
  throw new Error("Failed to extract JSON from LLM output");
}
 
/** 简易 Schema 验证 */
export function validateAgainstSchema(
  data: unknown,
  schema: Record<string, unknown>
): { valid: boolean; errors: string[] } {
  const errors: string[] = [];
 
  if (schema.type === "object") {
    if (typeof data !== "object" || data === null || Array.isArray(data)) {
      errors.push(`Expected object, got ${typeof data}`);
      return { valid: false, errors };
    }
    const required = (schema.required as string[]) ?? [];
    for (const key of required) {
      if (!(key in (data as Record<string, unknown>))) {
        errors.push(`Missing required field: "${key}"`);
      }
    }
  }
 
  if (schema.type === "array" && !Array.isArray(data)) {
    errors.push(`Expected array, got ${typeof data}`);
  }
 
  return { valid: errors.length === 0, errors };
}

// src/ling.ts
 
import * as readline from "readline";
import { parseCli, readStdin, runPrintMode } from "./cli/index.js";
 
const VERSION = "0.10.0";
 
const HELP = `
Ling - AI Coding Agent
 
Usage:
  ling [options]                  Start interactive REPL
  ling -p "query"                 Non-interactive mode
  cat file | ling -p "analyze"    Pipe input + query
 
Options:
  -p, --print <query>    Non-interactive mode, print result and exit
  -f, --format <fmt>     Output format: text (default), json, stream
      --schema <file>    Constrain output with JSON Schema
      --provider <name>  LLM provider (default: openai)
  -m, --model <name>     Model name (default: gpt-4o)
      --max-turns <n>    Max agent loop turns (default: 10)
  -c, --continue         Resume last session
  -r, --resume <id>      Resume specific session
  -n, --name <name>      Name the session
  -h, --help             Show this help
  -v, --version          Show version
`;
 
async function main() {
  const options = parseCli(process.argv);
 
  if (options.help) {
    console.log(HELP);
    process.exit(0);
  }
 
  if (options.version) {
    console.log(`ling v${VERSION}`);
    process.exit(0);
  }
 
  // ---- 非交互模式 ----
  if (options.print) {
    const stdinContent = await readStdin();
    let query = options.print;
 
    if (stdinContent) {
      query = `${stdinContent}\n\n---\n\n${query}`;
    }
 
    await runPrintMode(query, options);
    process.exit(0);
  }
 
  // ---- 交互模式 ----
  console.log(`Ling Agent v${VERSION}\n`);
 
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });
 
  const prompt = () => {
    rl.question("You: ", async (input) => {
      if (!input.trim()) return prompt();
      if (input.trim() === "/exit") {
        rl.close();
        return;
      }
      console.log(`\nLing: [response]\n`);
      prompt();
    });
  };
  prompt();
}
 
main().catch((err) => {
  console.error(err);
  process.exit(1);
});

# .github/workflows/pr-review.yml
 
name: PR Review with Ling
 
on:
  pull_request:
    types: [opened, synchronize]
 
permissions:
  contents: read
  pull-requests: write
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
 
      - name: Install Ling
        run: npm install -g ling-agent
 
      - name: Get PR diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > /tmp/pr-diff.txt
 
      - name: Run Ling Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          cat /tmp/pr-diff.txt | ling -p "Review this PR diff. Focus on bugs, security issues, and code style problems. Be concise." \
            --format json \
            --schema review-schema.json \
            --max-turns 1 \
            > /tmp/review.json
 
      - name: Post Review Comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          BODY=$(cat /tmp/review.json | jq -r '.content')
          gh pr comment ${{ github.event.pull_request.number }} --body "$BODY"

# .github/workflows/issue-triage.yml
 
name: Issue Triage
 
on:
  issues:
    types: [opened]
 
permissions:
  issues: write
 
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Classify Issue
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          BODY='${{ github.event.issue.body }}'
          TITLE='${{ github.event.issue.title }}'
 
          echo "$TITLE\n\n$BODY" | ling -p "Classify this issue. Return a JSON with a 'labels' array containing applicable labels from: bug, feature, docs, question, good-first-issue" \
            --format json \
            --max-turns 1 \
            > /tmp/triage.json
 
      - name: Apply Labels
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          LABELS=$(cat /tmp/triage.json | jq -r '.structured_output.labels | join(",")')
          gh issue edit ${{ github.event.issue.number }} --add-label "$LABELS"

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 2,
  baseDelay = 1000
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: unknown) {
      const error = err as { status?: number; message: string };
 
      // 不可重试的错误，直接抛出
      if (error.status && error.status >= 400 && error.status < 429) {
        throw err;
      }
 
      // 最后一次重试也失败了
      if (attempt === maxRetries) throw err;
 
      // 指数退避
      const delay = baseDelay * Math.pow(2, attempt);
      console.error(
        `[retry] attempt ${attempt + 1}/${maxRetries}, waiting ${delay}ms...`
      );
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("unreachable");
}

const response = await withRetry(() =>
  client.chat.completions.create({
    model,
    messages,
    tools: registry.toOpenAITools(),
  })
);

{
  "name": "ling-agent",
  "version": "0.10.0",
  "type": "module",
  "bin": {
    "ling": "./bin/ling"
  },
  "files": [
    "bin/",
    "dist/"
  ],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  },
  "dependencies": {
    "openai": "^4.78.0"
  },
  "devDependencies": {
    "tsx": "^4.19.0",
    "typescript": "^5.7.0",
    "@types/node": "^22.0.0"
  }
}

#!/usr/bin/env node
 
// bin/ling
import("../dist/ling.js");

# 1. 编译
npm run build
 
# 2. 本地测试
npm link
ling --help
ling -p "hello" --format json
 
# 3. 发布
npm login
npm publish
 
# 用户安装
npm install -g ling-agent
ling -p "分析这个项目"

# Claude Code 的 -p 模式，和我们的一样
claude -p "分析这个项目的技术栈"
 
# 管道输入
cat error.log | claude -p "分析这些错误"

# 纯文本（默认）
claude -p "query" --output-format text
 
# JSON，包含完整的结果对象
claude -p "query" --output-format json
 
# 流式 JSON，每行一个事件
claude -p "query" --output-format stream-json

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}