Pi 是 Mario Zechner 发起的开源 Agent Harness。它不是一个大模型，而是一套把大模型、上下文、工具、会话和终端界面组合起来的运行框架。它既提供可以直接使用的编程 Agent，也提供 SDK、RPC、Skills 和 Extensions，适合继续封装成企业内部的 AI 助手。

本文以 2026 年 8 月 1 日的官方版本为基准，从安装和第一次对话开始，逐步讲到项目规则、模型配置、技能、扩展工具、SDK、Java 系统集成、安全控制和效果评估。业务示例统一使用供应链系统中的订单、库存、采购和补货场景。

Pi 已迁移到 earendil-works/pi，npm 包也已改为 @earendil-works/*。旧的 badlogic/pi-mono 和 @mariozechner/* 资料可能仍能搜索到，但新项目应使用当前名称。

一、先理解Pi解决什么问题

一个可执行的 AI Agent 至少需要五部分：

1. 模型：负责理解目标、推理和决定下一步动作。
2. 上下文：告诉模型项目结构、业务术语和工程约束。
3. 工具：让模型读取文件、执行命令或调用业务接口。
4. Agent 循环：重复执行“模型判断、调用工具、读取结果、继续判断”。
5. 会话：保存消息、工具结果、模型状态和上下文压缩结果。

Pi 把这些能力拆成多个包：

因此，Pi 有四种常见用法：

• 直接运行 pi，把它当作终端编程助手。
• 运行 pi -p，完成一次性、非交互任务。
• 运行 pi --mode rpc，通过 JSONL 接入 Java、Python 或桌面应用。
• 在 Node.js/TypeScript 服务中使用 AgentSession SDK。

二、安装Pi并完成第一次运行

1. 检查Node.js版本

当前 pi-coding-agent 要求 Node.js >=22.19.0：

1
2

node --version
npm --version

如果版本过低，先通过 Node.js 官方安装包、nvm 或 fnm 升级。

2. 全局安装

1
2

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

--ignore-scripts 会阻止依赖安装阶段执行生命周期脚本，Pi 的正常 npm 安装不依赖这些脚本。

Windows PowerShell、macOS 和 Linux 都可以使用相同的 npm 安装命令。如果安装成功但提示找不到 pi，应检查 npm 全局可执行目录是否已加入 PATH：

1

npm config get prefix

3. 登录模型提供商

进入任意项目目录后启动：

1
2

cd /path/to/supply-chain-system
pi

在 Pi 里执行：

1

/login

可以选择官方支持的订阅登录，也可以使用 API Key。以 PowerShell 为例，临时设置 OpenAI API Key：

1
2

$env:OPENAI_API_KEY="你的API Key"
pi

Linux 或 macOS：

1
2

export OPENAI_API_KEY="你的API Key"
pi

不要把 API Key 写入 Git 仓库、AGENTS.md、提示词或日志。也可以通过 /login 把凭证交给 Pi 管理，默认凭证文件位于 ~/.pi/agent/auth.json。

4. 第一次供应链任务

先让 Pi 理解项目，不要一上来就让它改代码：

1
2
3

请先读取 README.md、pom.xml 和订单、库存、采购模块的目录结构。
说明创建采购订单后，库存预占、补货计算和供应商下单分别在哪些模块完成。
只分析，不修改文件，也不要执行写数据库的命令。

Pi 默认给模型提供 read、write、edit、bash 四个工具。模型并不是直接操作电脑，而是在 Agent 循环中选择工具，Pi 执行工具后把结果返回给模型。

三、用AGENTS.md建立项目规则

AI 在供应链项目里最容易犯的错误，不是 Java 语法错误，而是误解库存口径、订单状态和事务边界。应在仓库根目录创建 AGENTS.md，把长期有效的规则放进去。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Supply Chain Project Instructions

## Modules
- order-service: 销售订单和状态流转
- inventory-service: 现存量、预占量、冻结量和库存流水
- procurement-service: 采购申请、采购订单和供应商协同
- replenishment-service: 安全库存与补货建议

## Business Rules
- 可用库存 = 现存量 - 预占量 - 冻结量。
- 库存扣减必须使用带数量条件的原子更新，并记录库存流水。
- 同一个 businessRequestId 重试时不得重复预占或释放库存。
- 采购订单状态只能按状态机流转，禁止直接覆盖状态。
- 跨服务一致性使用本地事务加 Outbox 事件，不创建分布式大事务。

## Safety
- 默认只允许查询本地开发库，不连接生产数据库。
- 未经明确确认，不执行 INSERT、UPDATE、DELETE、DDL 和消息重放。
- 不读取或输出 .env、密钥、Token、客户手机号和供应商银行信息。

## Verification
- Java 代码修改后运行 mvn -pl <module> test。
- 库存并发逻辑必须增加重复请求、库存不足和并发扣减测试。
- 数据库变更必须提供可回滚迁移脚本和索引影响说明。

Pi 启动时会加载全局 ~/.pi/agent/AGENTS.md，以及当前目录和父目录中的 AGENTS.md 或 CLAUDE.md。修改规则后执行 /reload，或者重新启动 Pi。

项目规则应该描述稳定事实，不要把某次临时需求全部塞进去。临时需求应放在单独的需求文档中，再通过 @文件名 引用。

四、掌握一套可靠的日常开发流程

以“订单创建时预占库存”为例，可以把一次任务拆成五个阶段。

阶段1：建立上下文

1
2

读取 @AGENTS.md、@docs/inventory-model.md，搜索现有的库存扣减、释放、流水和幂等实现。
列出相关文件、当前调用链、事务边界和测试入口。不要修改代码。

这一步要求 Pi 先找到项目里的真实模式，避免凭经验发明不存在的层次和组件。

阶段2：输出实施计划

1
2
3
4
5
6
7
8
9
10
11

需求：订单创建成功后预占库存；订单取消或支付超时后释放；重复消息不能重复处理。

请给出实施计划，必须包含：
1. 正常流程和异常流程。
2. 表字段、唯一键、版本号和条件更新SQL。
3. 本地事务与Outbox事件边界。
4. 幂等键定义和重复消费处理。
5. 需要修改的文件清单。
6. 单元测试、并发测试和集成测试用例。

只输出计划，等待确认后再编码。

阶段3：小步实现

确认计划后再执行：

1
2

按计划先完成库存预占的领域逻辑和仓储层，只修改 inventory-service。
不要修改公共依赖版本。完成后展示差异并运行该模块测试。

一次只改变一个业务闭环。订单、库存、采购三个服务同时大改，会让上下文迅速膨胀，也会增加错误定位成本。

阶段4：验证业务不变量

至少检查以下不变量：

• 可用库存不能为负数。
• 相同幂等键只能产生一次库存流水。
• 释放数量不能超过原预占数量。
• 数据库回滚时不能留下已发送但无法追踪的业务事件。
• 消息重复、乱序、延迟时，最终状态仍然正确。

可以让 Pi 主动补测试：

1

根据本次 diff 检查库存不变量。补充库存不足、相同幂等键重复请求、20线程并发预占、事务回滚四组测试，然后运行测试并解释失败原因。

阶段5：审查和提交

1
2

审查当前 git diff，优先寻找数据一致性、并发、幂等、空值、越权和日志泄密问题。
没有阻塞问题后，给出建议的提交信息，但不要自动推送。

这个流程的重点是把“理解、计划、实现、验证、审查”分开。模型能力再强，也不应该跳过业务确认和可重复验证。

五、模型、思考强度与会话管理

切换模型

在交互模式中：

1

/model

也可以使用 Ctrl+L 打开模型选择器，使用 Shift+Tab 切换思考强度。简单的格式调整不需要高强度推理；跨服务库存一致性、死锁分析和数据迁移则适合更高强度。

项目级 .pi/settings.json 可以保存团队约定，例如：

1
2
3
4
5
6
7
8
9

{
  "defaultProvider": "openai",
  "defaultModel": "你的模型ID",
  "defaultThinkingLevel": "medium",
  "enabledModels": [
    "openai/*",
    "anthropic/*"
  ]
}

模型 ID 会随提供商更新，先用 /model 或 pi --list-models 查看当前可用值，不要照抄过时文章里的模型名。

管理长任务

1
2
3

pi -c                  # 继续最近会话
pi -r                  # 浏览历史会话
pi --name "库存预占改造"

交互模式还提供 /new、/resume、/tree、/fork 和 /clone。建议一个会话只解决一个明确问题。需求方向发生变化时，通过 /fork 保留原分支，比在同一上下文里反复推翻更清晰。

接入本地模型

Pi 可以通过 ~/.pi/agent/models.json 接入 Ollama、LM Studio、vLLM 等 OpenAI 兼容服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "你的本地模型ID",
          "reasoning": false
        }
      ]
    }
  }
}

本地模型适合代码检索、摘要和低风险分类，但是否能处理复杂库存一致性问题，必须通过真实测试集评估，不能只看通用排行榜。

六、用Skill沉淀供应链知识

AGENTS.md 是所有任务都要遵守的项目规则，Skill 则是按需加载的专业流程。可以创建：

1

.pi/skills/supply-chain-review/SKILL.md

内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

---
name: supply-chain-review
description: 审查订单、库存、采购和补货代码。当任务涉及库存数量、状态机、幂等、消息或供应链数据一致性时使用。
---

# Supply Chain Review

1. 先识别业务实体、状态和数量口径。
2. 画出同步调用、事务提交和异步消息的先后顺序。
3. 检查幂等键来源、唯一约束和重复消息处理。
4. 检查库存更新是否包含 `available_qty >= request_qty` 条件。
5. 检查超时、取消、部分成功和补偿路径。
6. 检查日志是否泄露客户、供应商或凭证信息。
7. 输出按严重程度排序的问题，并给出文件位置和测试建议。

项目被信任后，Pi 会发现 .pi/skills/ 下的技能。重载后可以显式调用：

1

/skill:supply-chain-review 审查本次库存预占改动

Skill 可以附带 scripts/、references/ 和 assets/。例如把库存字段字典、订单状态机和消息规范放进 references/，只有任务需要时才加载，能减少固定上下文占用。

七、用Extension接入只读库存接口

Skill 只是告诉模型怎么工作，Extension 才能注册真正可调用的工具。下面创建一个项目级只读库存查询工具：

1

.pi/extensions/inventory-query.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "query_inventory",
    label: "Query Inventory",
    description: "按SKU和仓库查询只读库存快照，不执行预占、扣减或释放",
    parameters: Type.Object({
      sku: Type.String({ description: "SKU编码" }),
      warehouseCode: Type.String({ description: "仓库编码" }),
    }),
    async execute(_toolCallId, params, signal) {
      const baseUrl = process.env.SCM_API_BASE_URL;
      const token = process.env.SCM_API_TOKEN;

      if (!baseUrl) {
        throw new Error("SCM_API_BASE_URL is not configured");
      }

      const url = new URL("/api/v1/inventory/availability", baseUrl);
      url.searchParams.set("sku", params.sku);
      url.searchParams.set("warehouseCode", params.warehouseCode);

      const headers: Record<string, string> = {
        Accept: "application/json",
      };
      if (token) headers.Authorization = `Bearer ${token}`;

      const response = await fetch(url, { headers, signal });
      if (!response.ok) {
        throw new Error(`Inventory API failed: HTTP ${response.status}`);
      }

      const snapshot = await response.json();
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(snapshot, null, 2),
          },
        ],
        details: {
          sku: params.sku,
          warehouseCode: params.warehouseCode,
          status: response.status,
        },
      };
    },
  });
}

配置环境变量后启动 Pi：

1
2
3

$env:SCM_API_BASE_URL="https://scm-api.example.internal"
$env:SCM_API_TOKEN="短期只读Token"
pi

首次加载项目级 Extension 时，Pi 会要求确认是否信任项目。执行 /reload 后，可以输入：

1

查询 SKU-10001 在 WH-SZ-01 的库存快照，结合近30天日均销量和7天采购提前期判断是否需要补货。只生成建议，不创建采购单。

这个工具应使用专门的只读服务账号，并在 API 网关限制路径、仓库范围、频率和返回字段。不要为了方便给 Agent 一个可以调用任意内部接口的管理员 Token。

八、使用SDK构建补货建议服务

如果要把 Pi 嵌入 Node.js 服务，使用 SDK 比启动子进程更直接：

1

npm install @earendil-works/pi-coding-agent typebox

下面是一个最小的补货建议 Agent。真实项目应把 queryReplenishmentInputs 替换成经过鉴权的内部 API 客户端。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

import {
  createAgentSession,
  defineTool,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

const scmApiBaseUrl = process.env.SCM_API_BASE_URL;
const scmApiToken = process.env.SCM_API_TOKEN;
if (!scmApiBaseUrl || !scmApiToken) {
  throw new Error("SCM_API_BASE_URL and SCM_API_TOKEN must be configured");
}

const replenishmentInputs = defineTool({
  name: "get_replenishment_inputs",
  label: "Get Replenishment Inputs",
  description: "读取SKU补货计算所需的库存、销量、在途和提前期数据",
  parameters: Type.Object({
    sku: Type.String(),
    warehouseCode: Type.String(),
  }),
  async execute(_toolCallId, params, signal) {
    const query = new URLSearchParams({
      sku: params.sku,
      warehouseCode: params.warehouseCode,
    });
    const response = await fetch(
      `${scmApiBaseUrl}/api/v1/replenishment/inputs?${query}`,
      {
        headers: {
          Authorization: `Bearer ${scmApiToken}`,
        },
        signal,
      },
    );
    if (!response.ok) throw new Error(`SCM API returned ${response.status}`);
    const data = await response.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
      details: { sku: params.sku, warehouseCode: params.warehouseCode },
    };
  },
});

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  modelRuntime,
  sessionManager: SessionManager.inMemory(process.cwd()),
  tools: ["get_replenishment_inputs"],
  customTools: [replenishmentInputs],
});

session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt(`
分析 SKU-10001 在 WH-SZ-01 的缺货风险。
先调用工具获取事实，再按以下公式给出建议：
补货点 = 提前期日均需求 + 安全库存。
输出事实、计算过程、风险、建议数量和需要人工确认的假设。
禁止创建采购单。
`);

这段代码只开放了一个自定义工具，没有给 Agent bash、write 或 edit。服务端 Agent 应按场景建立工具白名单，不要照搬编程助手的默认权限。

九、Java系统通过RPC接入Pi

供应链后台通常是 Java 技术栈。此时可以单独部署一个 Pi Agent Sidecar，由 Java 服务通过 RPC 调用：

1

pi --mode rpc --no-session

RPC 使用标准输入和标准输出传输 JSONL，每行一个 JSON 对象。Java 服务发送：

1

{"id":"replenishment-10001","type":"prompt","message":"分析SKU-10001在WH-SZ-01的缺货风险，只输出补货建议"}

Pi 会先返回请求是否被接受，再持续输出 message_update、tool_execution_start、tool_execution_end 和 agent_end 等事件。

生产环境建议采用以下结构：

1. Java 业务服务负责登录态、租户、权限和参数校验。
2. Node.js Agent 服务或 Pi RPC Sidecar 负责会话和模型编排。
3. Agent 只能通过受控工具访问订单、库存和采购 API。
4. 工具层统一做超时、重试、熔断、脱敏和审计。
5. 采购单创建等写操作进入待审批队列，由业务服务执行。

不要为每个请求临时启动一个 Pi 进程。可以维护固定数量的 Sidecar，按租户和任务隔离会话；如果主系统本身可以部署 Node.js 服务，优先使用 SDK，类型和生命周期管理会更简单。

十、供应链补货Agent的完整技术方案

一个可上线的补货 Agent 可以分成四层。

1. 入口层

• Web、企业微信或 ERP 页面接收用户问题。
• Java 网关校验用户、租户、仓库和数据权限。
• 把自然语言转换为带 requestId 的 Agent 请求。

2. Agent编排层

• Pi AgentSession 保存一次分析任务的上下文。
• 系统提示词限定角色、公式、输出格式和禁止事项。
• Skill 提供补货分析步骤和业务术语。
• 模型决定先查询哪些事实，再形成结论。

3. 工具层

至少拆成这些只读工具：

• get_inventory_snapshot：现存、预占、冻结、可用和在途库存。
• get_sales_forecast：历史销量、预测量和促销修正。
• get_supplier_lead_time：供应商交期、最小起订量和包装倍数。
• get_open_purchase_orders：未关闭采购单和预计到货日期。
• calculate_replenishment：使用确定性代码计算补货点和建议量。

计算公式应该由确定性工具执行，而不是让模型心算。例如：

1
2
3
4

有效库存位置 = 可用库存 + 在途库存 - 已分配未出库数量
补货点 = 采购提前期内预测需求 + 安全库存
建议补货量 = max(0, 目标库存 - 有效库存位置)
最终采购量 = 按最小起订量和包装倍数向上取整

模型负责解释数据、识别异常和组织建议，确定性程序负责算数、状态校验和写入。

4. 审批与执行层

Agent 的结果先形成 ReplenishmentProposal：

1
2
3
4
5
6
7
8
9

{
  "requestId": "RP-20260801-0001",
  "sku": "SKU-10001",
  "warehouseCode": "WH-SZ-01",
  "suggestedQty": 240,
  "reasonCodes": ["BELOW_REORDER_POINT", "LEAD_TIME_RISK"],
  "evidenceVersion": "inventory-88921",
  "status": "PENDING_APPROVAL"
}

审批通过后，由采购服务重新读取库存版本、校验建议是否过期，再创建采购申请。不要让模型直接拼接 SQL 写数据库，也不要把“模型已经判断正确”当作越过业务校验的理由。

十一、生产安全与权限控制

Pi 默认没有内置沙箱。bash、Extension 和第三方 Package 都以 Pi 进程的系统权限运行。项目信任机制只能控制是否加载项目资源，不等于运行时安全边界。

生产环境至少落实以下措施：

1. 进程隔离：在容器、虚拟机或受限系统账号中运行 Agent。
2. 工具白名单：业务 Agent 不开放任意 bash、文件写入和通用 HTTP 工具。
3. 最小权限：库存工具只读，且限制租户、仓库、接口和字段。
4. 人工审批：采购下单、库存调整、价格修改必须经过确认。
5. 参数校验：服务端重新校验 SKU、数量、状态和数据版本。
6. 凭证隔离：Token 存在密钥系统或环境变量中，不进入模型上下文。
7. 防提示词注入：把接口返回的数据当作不可信数据，不执行其中夹带的指令。
8. 审计留痕：记录用户、模型、会话、工具、脱敏参数、耗时、结果版本和审批人。
9. 预算控制：限制单次任务轮数、上下文、Token、超时和并发数。
10. 降级策略：模型或工具不可用时回退到传统规则引擎和人工流程。

第三方 Skill、Extension 和 Pi Package 可能包含可执行代码，安装前必须审查源码并固定版本。

十二、评估Agent是否真的可用

不要用“回答看起来不错”作为上线标准。可以从历史供应链数据中构造一套脱敏测试集：

• 正常补货 SKU。
• 促销导致需求突增的 SKU。
• 有大量在途库存的 SKU。
• 供应商延迟交付的 SKU。
• 库存数据缺失或时间戳过期的 SKU。
• 多仓调拨比采购更合适的 SKU。
• 最小起订量和包装倍数冲突的 SKU。

关键指标包括：

每次升级模型、提示词、Skill 或 Extension，都应重放同一批测试集并比较结果。只有回归指标稳定，才能扩大业务范围。

十三、常见问题排查

pi命令不存在

检查 Node.js 版本、全局安装结果和 npm prefix：

1
2
3

node --version
npm list -g @earendil-works/pi-coding-agent
npm config get prefix

登录成功但找不到模型

先执行 pi --list-models，检查提供商凭证和 models.json。自定义无密钥本地服务也需要占位 apiKey，否则模型可能不会出现在可用列表中。

项目Skill或Extension没有加载

确认目录分别是 .pi/skills/ 和 .pi/extensions/，确认已经信任当前项目，然后执行 /reload。非交互模式不会显示信任对话框，需要预先保存信任决策，或者在明确理解风险时使用一次性的 --approve。

Agent修改范围越来越大

重新开会话，把任务缩小到一个模块；在提示词中列出允许修改的目录；先让 Pi 输出文件清单和计划，再允许编辑。

结果包含正确解释但数字算错

把公式和取整规则实现成确定性工具。模型只能传入参数、调用工具和解释结果，不能作为财务、库存或采购数量的唯一计算器。

十四、推荐的进阶路线

1. 第一天：完成安装、登录、文件引用、模型切换和会话恢复。
2. 第二天：为现有 Java 供应链项目编写 AGENTS.md。
3. 第三天：用 Pi 完成一个低风险代码审查和测试补充任务。
4. 第四天：创建供应链审查 Skill，沉淀团队检查清单。
5. 第五天：编写一个只读库存查询 Extension。
6. 第六天：使用 SDK 构建补货建议原型，并建立离线测试集。
7. 第七天以后：接入审批、审计、监控、限流和容器隔离，再考虑试点上线。

总结

Pi 的价值不在于预置了多少复杂流程，而在于它提供了一套小而清晰的 Agent 基础能力：统一模型接口、Agent 循环、会话、工具、TUI、Skills、Extensions、SDK 和 RPC。初学时可以直接使用 CLI，提高 Java 项目的检索、修改和测试效率；进阶后可以通过 Skill 固化供应链知识，通过 Extension 接入内部只读 API；真正上线时，则应使用 SDK 或 RPC，把 Pi 放在权限、审批和审计体系之内。

供应链 Agent 最可靠的职责是“查询事实、执行确定性计算、解释风险、生成建议”，而不是绕过业务服务直接修改库存和采购数据。把模型的推理能力与传统系统的规则、事务和权限结合起来，才是从能演示走向能生产的关键。

参考资料

• Pi官方仓库
• Pi Quickstart
• Pi SDK
• Pi Extensions
• Pi Skills
• Pi RPC Mode
• Pi Security

从一次性修复到持续治理

最近在整理 Codex 和 Agent 工作流时，我越来越觉得，AI 编程真正值得关注的地方，已经不只是“怎么写一个更好的提示词”，而是怎么把 AI agent 放进一个持续运转的工程循环里：自动发现问题、定位根因、生成修复、跑测试、部署预发，再由独立验证环节判断是否真的修好。

换句话说，AI 编程的瓶颈，已经不只是“写代码慢不慢”，而是“发现问题、修复问题、验证问题、沉淀经验”这条维护链路是不是还靠人手动推动。

如果人每天都要打开日志平台、复制错误、问 AI、改代码、跑测试、提合并、盯预发，那 AI 只是提高了某个环节的速度。Loop Engineering 要做的，是把整条链路设计成能自己转起来的闭环。

工程循环的五个必要环节

Loop Engineering 的重点不是让 AI “更会写代码”，而是把问题发现、任务隔离、修复执行、独立验证和经验沉淀组织成可重复运行的工程流程。自动化程度必须由风险等级决定，尤其不能默认把生产数据修改和生产发布交给 agent。

我把它总结成四个观点。

第一，维护循环才是真正瓶颈。

AI 已经能很快生成代码，但线上系统的问题不会自动消失。日志分散、错误类型多、排查链路长、测试和部署还要人工推动，才是工程效率真正卡住的地方。

第二，Loop 比一次性 Agent 多了“持续性”。

普通 Harness 是一次会话里给 AI 工具，比如 shell、git、日志查询、测试命令。Loop 在它之上增加了调度、状态、独立验证和跨轮记忆。也就是说，它不是“这次帮我修一下”，而是“每天自己巡检、自己修、自己验，必要时通知人”。

第三，Loop 需要五个动作。

1
2
3
4
5

发现：找出该处理的问题。
交付：把问题隔离给 agent 执行。
验证：让独立检查环节判断结果。
持久化：把结论、失败和修复经验记录下来。
调度：让这套流程定时或按事件反复运行。

第四，Loop 需要六类组件。

1
2
3
4
5
6

Connectors：连接日志、监控、发布、通知等系统。
Automations：定时巡检或事件触发。
Skills：把诊断、修复、发布流程写成 SOP。
Worktrees：隔离不同修复任务，避免互相污染。
Independent verifier：用独立上下文或独立检查程序验证，避免修复者自证。
State：在工单、数据库或版本化文档中记录历史结论、修复方案和巡检状态。

这里还有一个很重要的判断标准：不是所有任务都值得建 Loop。适合建 Loop 的任务，通常要满足四个条件：重复发生、验证能自动化、成本可控、agent 有足够工具。

放到供应链系统里怎么理解

供应链系统非常适合用 Loop Engineering 的思路，因为它的异常不是一次性的。

比如这些问题会反复出现：

1
2
3
4
5
6
7

订单履约超时。
采购到货数量和采购单不一致。
库存预占失败。
出库单状态卡住。
消息消费失败。
供应商回传状态延迟。
报表统计口径和业务事实不一致。

传统做法是：运营或研发发现异常，去查订单、查库存流水、查 MQ、查日志、查数据库，再手动判断是否要修代码或补数据。

Loop Engineering 的做法是把这条链路设计成系统：

1
2
3
4
5
6
7
8
9

每天自动扫描异常订单和错误日志。
按业务类型归类：库存、采购、发货、消息、报表。
让 Codex 读取相关代码、日志和数据样本。
生成根因报告和最小修复方案。
补测试或验证 SQL。
修复一个小切片。
跑测试和回归查询。
通过后提交变更，失败则进入调试循环。
超过重试次数就停止，并把问题交给人。

这样 Codex 不只是“写代码的人”，而是整个维护循环里的执行者。

Codex 供应链案例

假设供应链系统里有一个反复出现的问题：采购到货后，部分订单的库存流水已经写入，但采购到货单状态仍停留在“部分到货”，导致后续财务暂估和供应商履约报表都不准。

这个需求不要直接让 Codex 改代码。先把 loop 定义清楚。

第一步，用普通任务说明定义目标。不同 Codex 版本和使用界面支持的能力并不完全相同，因此不要假设 /goal 是所有环境都可用的通用命令。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

请把下面内容作为本次持续排查任务的目标：
持续排查并修复供应链系统里的采购到货状态异常问题。

目标：
1. 找出近 7 天库存流水已写入但到货单状态未正确更新的样本；
2. 定位是代码逻辑、消息消费、事务回滚还是历史数据导致；
3. 如果是代码问题，生成最小修复并补充测试；
4. 跑相关测试和验证 SQL；
5. 输出修复报告、风险点和人工验收清单。

停止条件：
- 找到明确根因并完成修复；或
- 连续两轮验证失败；或
- 需要真实数据库权限、生产凭证、业务口径确认。

第二步，让 Codex 先做发现。

1
2
3
4
5
6
7
8
9
10
11

请先不要改代码。
请读取项目规则、采购到货模块、库存流水模块、消息消费模块和相关测试。

同时整理需要验证的数据条件：
1. purchase_receipt 状态不是 COMPLETED；
2. stock_ledger 已存在对应 receipt_id；
3. receipt_item 的 received_qty 已等于 planned_qty；
4. 最近 7 天内出现；
5. 排除人工关闭或取消的单据。

输出异常样本查询 SQL、可能原因列表和下一步排查计划。

第三步，把诊断流程沉淀成 skill 思路。

1
2
3
4
5
6

请按 supply-chain-receipt-diagnosis skill 的方式执行：
1. 先确认业务状态机；
2. 再查库存流水和到货明细；
3. 再查消息消费日志；
4. 再看最近相关 git diff；
5. 最后输出事实、推理、结论，不要跳步。

如果还没有这个 skill，可以先把它当成提示词使用。等这类问题出现三次以上，就值得写成真正的 SKILL.md。

第四步，让 Codex 生成修复计划。

1
2
3
4
5
6
7
8

请基于上面的诊断结果，生成修复计划，不要直接改代码。

计划必须包含：
1. 要修改的 Service、Mapper、消息消费者或定时补偿任务；
2. 要新增的单元测试和集成测试；
3. 是否需要补偿历史数据；
4. 事务边界和幂等风险；
5. 回滚方案。

第五步，小步实现。

1
2
3
4
5
6
7
8
9

现在只实现第一步：补充一个失败测试。

测试场景：
库存流水写入成功，到货明细数量已满足完成条件，但到货单状态仍未更新。

要求：
- 先让测试失败；
- 不修改业务实现；
- 完成后展示测试名称和失败原因。

第六步，再让 Codex 做最小修复。

1
2
3
4
5
6
7
8

现在根据失败测试做最小修复。

要求：
- 不改接口协议；
- 不重构无关代码；
- 保持现有事务模型；
- 如果涉及消息重复消费，必须加幂等判断；
- 修复后运行相关测试。

第七步，独立验证。

1
2
3
4
5
6
7
8

请用 code review 的方式审查当前 diff。

重点检查：
1. 是否只是修复采购到货状态异常；
2. 是否会影响少到、多到、不合格品逻辑；
3. 是否有重复消费导致状态反复更新的问题；
4. 库存流水和到货状态是否在同一事务或有补偿机制；
5. 测试是否覆盖重复消息和事务失败。

第八步，持久化经验。

1
2
3
4
5
6
7
8

请把这次问题总结成一条可复用的排查规则：
- 触发条件；
- 相关表；
- 相关日志；
- 常见根因；
- 验证 SQL；
- 修复注意事项；
- 下次自动巡检建议。

这一步形成可审计的状态记录。记录应放在团队可维护的工单、runbook 或版本库中，不能只依赖某次对话的上下文。

完整闭环与质量门禁

对供应链系统来说，一个可落地的 Codex Loop 可以这样走：

1
2
3
4
5
6
7
8
9
10
11

定时巡检
-> 查询异常订单/到货单/库存流水
-> Codex 读取代码和日志
-> 生成根因报告
-> 写失败测试
-> 最小修复
-> 跑测试和验证 SQL
-> 独立 review
-> 预发验证
-> 人工确认生产发布
-> 记录经验和新规则

关键不是追求“全自动发布生产”，而是按风险设置质量门禁。涉及库存数量、金额、权限和生产数据修复时，应要求人工审批、双人复核、审计记录和可执行的回滚方案。

落地限制与治理措施

第一个限制，是验证器不够强。

如果只有单元测试，AI 可能把错误隐藏掉，比如把错误日志降级，或者只处理 happy path。解决办法是至少三层验证：单元测试、业务 SQL 校验、预发环境回归。

第二个限制，是成本容易失控。

每天全量扫日志、读代码、跑大模型诊断，很容易消耗大量 token。解决办法是分级：先用简单规则和小模型筛选高风险问题，再把少量问题交给 Codex 深度处理。

第三个限制，是工具链建设成本高。

Loop 不是只写提示词，它需要日志查询、测试命令、发布脚本、通知通道、状态记录。解决办法是先选一个窄场景，比如“采购到货状态异常”，不要一上来覆盖整个供应链。

第四个限制，是自动修复可能误伤。

供应链系统里状态机、库存、财务、报表互相影响，自动修复不能绕过人。解决办法是设置硬停止条件：涉及金额、库存数量、生产数据修复、权限变更时，必须人工审批。

第五个限制，是经验没有沉淀。

如果每次排查都停留在一次对话里，下一次还是从零开始。解决办法是把常见问题写入 skill、runbook、异常规则库或巡检配置，让 loop 越跑越聪明。

总结

Loop Engineering 最值得借鉴的地方，是它把 AI 编程从一次性任务推进到生产闭环。它不是让 AI 一次性写更多代码，而是设计一套能持续发现问题、修复问题、验证问题、沉淀经验的系统。

放到供应链系统里，我认为最适合先做的不是“让 Codex 自动开发大需求”，而是“让 Codex 自动巡检和修复高频异常”。比如采购到货状态异常、库存流水不一致、消息消费失败、订单履约超时。

真正稳的 AI 工程化，不是把人完全拿掉，而是让人从手动推动循环，变成设计循环、审查风险和批准关键节点。

参考资料

• Loop Engineering - Addy Osmani
• OpenAI Agents docs
• OpenAI Codex best practices

为什么需要配置管理

最近使用 Codex 做代码任务时，我越来越明显地感觉到，AI 编程工具本身已经不是唯一问题，真正容易乱的是账号、模型、API、MCP 和本地配置。

比如一台电脑上可能同时有个人 ChatGPT 账号、公司授权账号、测试账号；有时候想用官方 Codex 登录状态，有时候又想切到第三方 OpenAI 兼容 API；再加上 ~/.codex/auth.json、~/.codex/config.toml、MCP 配置和项目里的 AGENTS.md，时间一长就很容易不知道当前 Codex 到底在用哪个账号、哪个模型、哪个接口。

cc-switch 要解决的就是这个问题。它不是模型，也不是 Codex 的替代品，而是一个 AI 编程工具的配置管理面板。我的理解是：Codex 负责干活，cc-switch 负责把账号、供应商、模型和路由管理清楚。

适用场景与合规边界

先说结论：cc-switch 适合管理多套 AI 编程配置，但不要把它理解成“无限切账号绕过限制”的工具。

我觉得它最适合三类场景。

第一类，是个人账号和公司账号分开。比如个人项目用自己的 ChatGPT / Codex 账号，公司项目用公司授权账号，避免上下文、账单和权限混在一起。

第二类，是官方登录和第三方 API 分开。Codex App 或 Codex CLI 可能需要官方登录状态，但实际模型请求可以根据任务切到不同 provider，比如 OpenAI 官方、OpenAI 兼容网关、团队内部代理或其他模型服务。

第三类，是不同任务使用不同模型。轻量任务用便宜模型，复杂重构用更强模型，长上下文分析用支持更大上下文的 provider。

这里要注意一个边界：多个账号必须是你自己合法拥有或团队授权使用的账号，不要把多账号当成规避平台限额的手段。auth.json、API Key、refresh token 都属于敏感凭证，不要截图、不要提交到 Git、不要发给别人。

先理解 Codex 的两个关键配置

Codex 本地一般会涉及两个重要文件：

1
2

~/.codex/auth.json
~/.codex/config.toml

auth.json 更像登录态，保存官方 ChatGPT / Codex OAuth 登录缓存。它很敏感，不应该手工复制、上传或分享。

config.toml 是 Codex 的运行配置文件，可包含模型、模型供应商、接口地址和相关选项。认证信息如何保存取决于登录方式、Codex 版本以及 CC Switch 的配置模式，不应把某一种文件布局当成长期稳定的公开接口。

CC Switch 在管理 Codex 时，主要价值是减少手工修改配置文件的次数。尤其是在切换不同 provider 时，它会按当前版本支持的方式更新 Codex 配置。操作前仍应备份配置，并在升级后核对 CC Switch 的发布说明。

如果你不了解这两个文件，就很容易出现一个错觉：Codex 界面显示的是 A 账号，所以请求一定走 A 账号。实际不一定。官方登录状态、模型请求路由、账单来源可能是三件事，需要分别确认。

安装与变更前准备

Windows 上可以直接去 GitHub Releases 下载 .msi 安装包，或者使用 portable zip。

macOS 可以使用 Homebrew：

1
2

brew tap farion1231/ccswitch
brew install --cask cc-switch

Linux 可以下载 .deb 或 AppImage。服务器上如果没有桌面环境，也可以使用 Web 版本，默认端口是 17666。

安装后，先不要急着添加一堆账号。建议先做三件事：

1
2
3

1. 确认 Codex CLI 或 Codex App 可以正常启动；
2. 确认 cc-switch 能看到 Codex 这个应用入口；
3. 备份当前 ~/.codex 目录，避免误操作后不好恢复。

备份可以这样做：

1

cp -r ~/.codex ~/.codex.backup.$(date +%Y%m%d)

Windows PowerShell 可以用：

1

Copy-Item "$env:USERPROFILE\.codex" "$env:USERPROFILE\.codex.backup.20260705" -Recurse

方式一：保留官方登录并切换Provider

这是需要同时保留官方登录能力和第三方 provider 时的一种用法。官方认证保留在当前 CC Switch 版本中是可选设置，默认值和写入方式可能随版本变化，应以当前发布说明为准。

第一步，在 cc-switch 的 Codex 面板里选择 OpenAI Official。如果没有，就从 preset 里添加一个。

第二步，启动 Codex，完成一次官方 ChatGPT / Codex 登录。登录后，Codex 会把登录缓存写到 ~/.codex/auth.json。

第三步，回到 cc-switch，打开：

1

Settings -> General -> Codex App Enhancements

打开类似这样的选项：

1

Keep official login when switching third-party providers

这个开关的意思是：切换第三方 provider 时，尽量保留官方登录缓存，不要反复覆盖 auth.json。这样 Codex 仍然能识别官方账号，而模型请求可以走当前选中的 provider。

第四步，在 Codex 面板里新增 provider。比如你可以添加一个 OpenAI 兼容 API、团队代理网关，或者其他支持 Responses API / Chat Completions 的模型服务。

第五步，切换 provider 后重启 Codex。这个动作很重要，因为 Codex 通常在启动时读取 config.toml 和模型列表。你切换 provider 后不重启，可能还在用旧配置。

验证时不要只看 Codex 显示的账号。应该同时看三处：

1
2
3

1. cc-switch 当前启用的 Codex provider；
2. cc-switch routing / request log 是否有请求；
3. provider 后台余额或调用记录是否发生变化。

如果 Codex 仍显示官方账号，但 provider 后台出现调用记录，这是正常的：官方账号负责登录态，实际模型请求走当前 provider。

方式二：通过OAuth Auth Center隔离授权账号

CC Switch 的 OAuth Auth Center 可以管理多个经过本人或组织授权的 ChatGPT / Codex OAuth 账号。该能力仍带有版本和合规风险，适合做身份、权限和账单隔离，不应被用于共享凭证或规避平台限制。

需要区分两件事：在 Codex 中切换本人获授权的登录身份，与把 Codex OAuth 服务反向代理给其他工具并不是同一种操作。后者可能受到 OpenAI 与上游服务条款限制。启用任何 OAuth reverse proxy 或第三方转发功能前，应阅读当前版本的风险提示和相关服务条款；公司环境还需要经过安全与合规审批。

大致步骤是：

1
2
3
4
5
6
7
8

1. 打开 Settings -> OAuth Auth Center；
2. 在 ChatGPT / Codex OAuth 区域点击登录；
3. 按提示复制设备验证码；
4. 打开授权地址并登录第一个 ChatGPT 账号；
5. 授权成功后，账号会出现在 Logged-in Accounts；
6. 点击 Add Another Account，再登录第二个账号；
7. 每个 provider 选择对应账号保存；
8. 通过 provider 卡片或托盘菜单切换。

这里要特别小心：不要导出 token，也不要手工复制 refresh token。一个更好的习惯是只让 cc-switch 自己维护 OAuth 状态。账号过期就重新登录，不要把凭证文件拿来传来传去。

如果是多人共用一台开发机，更建议每个人使用自己的系统用户，或者至少明确命名 provider：

1
2
3

codex-personal-gpt
codex-company-gpt
codex-test-gpt

名字要能看出用途，不要只叫 account1、account2。半年后再看，自己也会忘。

方式三：协议不兼容时使用Local Routing

部分第三方 provider 只提供 Chat Completions 兼容协议，而 Codex 使用的工具调用和流式事件更接近 Responses API。直接修改接口地址可能出现模型目录、流式响应或工具调用不兼容，此时可评估使用 CC Switch Local Routing 做协议转换。

不同版本的菜单名称可能变化，当前版本可从 Routing 相关设置进入：

1

Settings -> Routing -> Local Routing

打开主开关后，默认本地服务一般是：

1

127.0.0.1:15721

然后只勾选 Codex 的 routing takeover。这样 Codex 请求会先到本地 cc-switch 路由，再由 cc-switch 转发给真正的 provider。

这个模式有两个好处。

第一，真实 API Key 不一定直接暴露在 Codex 当前配置里，可以由 cc-switch 的 provider 配置管理。

第二，可以处理协议不完全一致的问题，比如把 Codex 的请求转换成上游 provider 能接受的格式。

但本地路由也会多一层故障点。如果 Codex 返回 404、模型不存在、流式响应异常，要优先检查：

1
2
3
4
5

1. provider 是否需要 Local Routing；
2. Local Routing 主开关是否启动；
3. Codex routing takeover 是否打开；
4. model mapping 是否写对；
5. Codex 是否已经重启。

本地路由位于代码、提示词和模型服务之间，也扩大了敏感数据的处理边界。使用前应确认日志是否记录请求正文、凭证如何存储、上游是否保留数据，以及团队代码是否允许发送给该 provider。

日常使用与审计流程

我会把日常流程固定成这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

开始任务前：
1. 打开 cc-switch；
2. 确认当前 Codex provider；
3. 确认账号用途：个人、公司还是测试；
4. 确认模型和路由状态；
5. 再启动 Codex。

任务执行中：
1. 不在对话里粘贴 API Key；
2. 不让 Codex 输出 auth.json；
3. 大任务先让 Codex 计划，再执行；
4. 涉及敏感代码或生产数据时缩小上下文。

任务结束后：
1. 看 provider 调用记录；
2. 看本地 git diff；
3. 如果切过账号，回到默认 provider；
4. 必要时清理临时日志和敏感文件。

这个流程看上去啰嗦，但能避免很多麻烦。AI 工具越自动化，越需要把“当前是谁在用、用哪个模型、请求去哪儿了”这件事弄清楚。

常见故障与安全风险

第一个坑，是把多账号当成额度池。这个风险很高，也不稳定。账号切换应该服务于权限隔离、账单隔离和项目隔离，而不是绕限制。

第二个坑，是手动复制 auth.json。这个文件里可能包含敏感登录缓存，复制来复制去很容易泄露，也容易因为凭证轮换导致失效。

第三个坑，是切换 provider 后不重启 Codex。很多配置是在启动时加载的，特别是模型列表和 config.toml。

第四个坑，是只看 Codex 界面上的账号显示。实际请求走哪里，要看 cc-switch 当前 provider、routing log 和 provider 侧账单记录。

第五个坑，是 provider 名字乱。建议用用途命名，比如 personal-openai-official、company-openai-gateway、test-codex-oauth。

总结

cc-switch 对 Codex 最大的价值，不是“多一个工具”，而是让账号、模型、路由和配置变得可控。

如果只是偶尔用 Codex，一个官方登录就够了。但如果你同时维护个人项目、公司项目、测试环境，还要在官方账号和不同 provider 之间切换，那么 cc-switch 可以明显降低配置混乱。

我的建议是：先从一个官方账号加一个 provider 开始，跑通登录、切换、重启、验证这条链路；等流程稳定后，再添加第二个 GPT 账号。不要一开始就把所有账号和模型都塞进去，越复杂越容易排查困难。

真正好用的 AI 编程环境，不是账号越多越好，而是每一次启动 Codex 前，都清楚当前账号是谁、请求会去哪、出了问题该看哪里。

参考资料

• CC Switch 官方网站
• CC Switch GitHub
• CC Switch Codex 官方登录保留指南
• CC Switch Provider 管理文档

为什么单次 Agent 还不够

这两年大家使用 AI 编程助手的方式变化很快。最开始是 prompt engineering：想办法把一句提示词写得更清楚。后来是 context engineering：想办法把项目背景、代码结构、接口文档、错误日志都给到 AI。再往后是 skill：把重复的工作流沉淀成 SKILL.md，让 AI 在合适场景自动调用。

到了 2026 年，越来越多人开始讨论 Loop engineering。它不是一个单独的插件，也不是某个固定命令，而是一种新的 AI 协作方法论：不再由人一轮一轮地提示 AI，而是设计一个循环，让 AI 能围绕目标持续执行、观察结果、修正策略，直到达到停止条件。

一句话说，Loop engineering 就是把 AI 编程从“一次性生成代码”，变成“目标、执行、验证、反馈、修正、停止”的工程闭环。

Loop engineering 是什么

Loop engineering 可以理解为“设计 AI agent 的工作循环”。一个好的 loop 至少包含五个部分。

目标：明确这次循环要完成什么，什么情况下算完成。

上下文：告诉 AI 当前项目规则、代码结构、业务背景、历史决策和约束。

行动：让 AI 执行一个小步骤，比如读代码、写 spec、改一个切片、跑一个测试。

观察：把测试结果、错误日志、diff、接口响应、CI 状态反馈给 AI。

停止条件：测试通过、验收清单完成、连续失败、超出预算、需要人工确认时停止。

如果没有观察和停止条件，所谓 loop 只是“让 AI 一直跑”。这很危险。真正的 Loop engineering 强调的是可验证、可回滚、可暂停、可复盘。

它和几个相近概念的区别也很清楚：

1
2
3
4

Prompt engineering：优化单次输入。
Context engineering：准备更好的上下文。
Skill engineering：把重复动作沉淀成技能。
Loop engineering：把多个动作组织成持续运行的反馈闭环。

所以 Loop engineering 不是替代 prompt、context、skill，而是把它们组织起来。

Loop engineering 怎么用

一个最小可用的 loop 可以这样设计：

1
2
3
4
5
6
7

1. 明确目标：我要修复某个 bug，或者完成某个业务切片。
2. 准备上下文：项目规则、相关代码、测试命令、验收标准。
3. 执行一小步：只改一个模块或一个测试。
4. 运行验证：测试、构建、接口调用、diff review。
5. 反馈结果：把失败日志或 diff 交给 AI。
6. 修正策略：继续改、回滚、拆小、提问或停止。
7. 达成条件：所有验收通过后结束。

这里最重要的是“小步”。很多人用 AI 失败，不是因为模型不行，而是一次给了太大的任务。比如“重构库存系统”就太大了，应该拆成：

1
2
3
4
5
6
7

库存锁定模型
库存释放流程
库存流水表
订单幂等键
并发扣减测试
异常回滚测试
报表口径调整

每个小切片都能单独验证，loop 才不会失控。

我会把常用组件这样组合：

OpenSpec/OPSX：负责把需求变成可追踪的规格。

Superpowers skills：负责澄清、计划、TDD、调试、review。

Codex：负责读代码、改代码、跑命令、看 diff。

持续目标：在支持目标管理的 Codex 界面中使用对应能力；其他环境则用普通任务说明明确目标、预算和停止条件。

Automations：负责让某些 loop 定时运行，比如每天检查失败测试、未处理 issue、CI 错误。

Git worktree：负责隔离多个并行 loop，避免互相改乱。

状态文件：负责记录做过什么、失败过什么、下一步是什么。

用 Codex 实践 Loop engineering

用 Codex 做 Loop engineering，关键不是让它“无限执行”，而是把目标和停止条件写清楚。

一个比较实用的 Codex loop 可以长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

目标：
完成采购到货差异处理的第一阶段：差异可记录。

上下文：
- 读取 AGENTS.md、README.md、pom.xml；
- 读取采购、到货、质检、库存相关模块；
- 参考已有 Controller、Service、Mapper、DTO、测试写法；
- 严格遵守项目现有风格。

循环步骤：
1. 先用 /opsx:propose 生成 change artifacts；
2. 用 brainstorming skill 澄清差异类型；
3. 用 writing-plans skill 拆任务；
4. 用 test-driven-development skill 先写测试；
5. 实现一个切片；
6. 运行相关测试；
7. 用 requesting-code-review skill 审查 diff；
8. 失败时用 systematic-debugging skill 修复；
9. 全部验收后 /opsx:verify、/opsx:sync、/opsx:archive。

停止条件：
- 差异记录相关测试全部通过；
- diff 只包含计划内文件；
- 验收清单全部完成；
- 如果连续两轮同一测试失败，停止并输出阻塞原因。

如果当前 Codex 界面支持持续目标，可以把目标写成可验证条件；否则直接把同样的内容作为普通任务说明。不要假设 /goal 是所有 Codex 版本都支持的通用命令：

1
2
3
4
5
6
7
8
9

请持续推进下面的目标，并在满足停止条件时结束：
持续推进采购到货差异处理第一阶段，直到满足：
1. 已生成 OpenSpec change；
2. 已完成差异类型、差异记录表、差异登记逻辑；
3. 相关单元测试和集成测试通过；
4. 当前 diff 已通过 requesting-code-review skill 检查；
5. 没有无关重构和未说明的新依赖。

如果遇到业务口径不确定、测试连续失败或需要凭证访问外部系统，请停止并总结阻塞点。

这类目标说明的重点是“直到满足什么”，而不是“帮我一直做”。没有停止条件的 loop 容易造成成本失控，也容易让变更逐渐偏离原始范围。

供应链系统案例

假设供应链系统要做“采购到货差异处理”。业务背景是：采购单下了 100 件，实际只到了 80 件，或者到了 110 件，或者其中 10 件质检不合格。系统需要记录差异，并影响库存、财务暂估和报表。

这个需求如果一次性让 AI 实现，很容易失控。我们可以设计三层 loop。

第一层，规格 loop。

1
2
3
4
5
6
7
8
9
10

/opsx:propose purchase-receipt-discrepancy

请先生成 proposal、design、tasks、specs，不写业务代码。
必须覆盖：
少到、多到、不合格；
到货单、差异单、质检结果；
库存入库和待处理区；
财务暂估数量；
报表统计口径；
幂等、事务、并发、回滚。

这一层的 loop 不是写代码，而是让需求变清楚。它的停止条件是：spec 能回答接口、数据、状态、异常、验收。

第二层，计划 loop。

1
2
3
4

请使用 writing-plans skill 细化 tasks.md。
每个任务控制在 2 到 5 分钟可完成。
每个任务必须包含：
文件路径、修改内容、验证方式、回滚风险。

计划 loop 会把大需求拆成：

1
2
3
4
5
6
7
8
9
10

任务1：新增差异类型枚举。
任务2：新增差异记录表。
任务3：新增差异记录 Mapper。
任务4：补少到场景测试。
任务5：实现少到差异登记。
任务6：补多到场景测试。
任务7：实现多到差异登记。
任务8：补不合格品测试。
任务9：实现不合格品待处理逻辑。
任务10：审查财务暂估和报表影响。

第三层，实现 loop。

每个任务都走同样的循环：

1
2
3
4
5
6
7

取一个任务
-> 先写或确认测试
-> 最小实现
-> 跑测试
-> 看 diff
-> code review
-> 通过后进入下一个任务

以“少到差异登记”为例：

1
2
3
4

请使用 test-driven-development skill 实现少到差异登记。
先写测试：
采购单数量 100，实际到货 80，应生成少到差异 20。
测试先失败后，再写最小实现。

如果测试失败：

1
2
3

请使用 systematic-debugging skill 分析失败。
不要直接改代码。
先输出失败断言、实际值、相关 SQL、可能根因和最小修复方案。

实现后：

1
2
3
4
5
6
7

请使用 requesting-code-review skill 审查当前 diff。
重点看：
1. 是否只改了少到差异相关文件；
2. 是否影响多到和不合格逻辑；
3. 事务边界是否正确；
4. 重复请求是否会重复生成差异；
5. 测试是否覆盖异常场景。

这个过程看起来慢，但大需求最怕的不是慢，而是一路快到错误方向。Loop engineering 的价值，就是让每一轮都有证据。

Loop engineering 的局限性

第一，成本会变高。

loop 会反复读代码、跑测试、审 diff、修错误，token 和时间成本都比一次性生成高。解决办法是控制 loop 粒度：只让它处理一个切片；给出最大轮数；失败两次就停；不要把整个仓库都塞进上下文。

第二，停止条件很难写。

“把库存做好”不是停止条件，“库存预占相关 12 个测试通过，diff 不包含无关文件，review 没有 P0/P1 问题”才是停止条件。解决办法是把完成定义写成可检查清单，最好能对应测试、命令或具体文件。

第三，AI 会产生理解债。

loop 跑得越快，人越容易不看代码，最后系统变了但自己没理解。解决办法是每个 loop 结束必须输出变更摘要、设计决策、风险点和人工验收清单；关键业务代码必须人工 review。

第四，错误会被自动放大。

如果 spec 一开始错了，loop 会持续围绕错误目标努力。解决办法是把 propose、plan、apply 分开，在 spec 阶段用 requesting-code-review 审查，必要时先暂停。

第五，环境依赖会卡住。

外部系统、数据库权限、测试数据、接口凭证都可能让 loop 无法继续。解决办法是提前定义阻塞条件：缺凭证、缺数据、连续失败、外部系统不可达时停止，并输出需要人工补充的内容。

第六，并行 loop 会互相干扰。

多个 agent 同时改同一个模块，很容易冲突。解决办法是使用 git worktree 隔离，按业务边界拆任务，并限制每个 loop 的文件范围。

总结

Loop engineering 的本质，是把 AI 编程从“人不断提示 AI”，升级成“人设计一个可验证的循环系统”。这个系统会发现任务、执行任务、观察结果、修正错误，并在满足条件时停止。

对 Codex 来说，Loop engineering 可以落到很具体的实践：用 OpenSpec 写规格，用 Superpowers skills 管过程，用 /goal 维持目标，用测试和 diff 做反馈，用人工 review 控住业务风险。

但它不是银弹。loop 越自动，越需要明确目标、边界、验证和停止条件。真正可靠的 Loop engineering，不是让 AI 替你思考，而是让 AI 在你设计好的工程轨道里持续前进。

参考资料

• Loop Engineering - Addy Osmani
• What Is Loop Engineering? The New Meta for AI Coding Agents
• OpenSpec OPSX commands
• obra/superpowers
• OpenAI Codex best practices

效率提升来自流程而非单次生成

前面几篇文章里，我写了 AI 编程助手、AI Agent 工作流，以及普通开发者使用 AI 时需要守住的边界。写到 Codex 这一篇时，我更想把它写成一篇可以反复翻回来的实践笔记。

Codex 这类工具和普通聊天机器人不太一样。普通聊天机器人更像一个问答窗口，你问一句，它答一句；Codex 更像一个可以进入项目、阅读代码、修改文件、运行命令、解释结果的开发协作者。OpenAI 官方把 Codex 描述为用于软件开发的 coding agent，可以帮助写代码、理解陌生代码库、review 代码、调试问题和自动化开发任务。

但工具越强，越不能随便用。很多人第一次用 Codex，会把它当成“高级代码生成器”：给一句需求，期待它马上给出完美代码。这样当然偶尔能成功，但不稳定。真正稳定提升效率的方法，是把 Codex 放进一套清楚的工程流程里：准备上下文、明确任务、让它先计划、让它小步实现、跑测试、看 diff、复盘沉淀。

下面这 10 个技巧，是我理解里最适合普通开发者落地的用法。

技巧一：把需求写成一个小 issue，而不是一句口号

很多人对 Codex 的第一句提示是：“帮我优化一下代码。”这句话的问题不是太短，而是没有验收标准。什么叫优化？是性能变快、代码更短、结构更清楚，还是减少重复？如果没有边界，Codex 只能猜。

更好的写法，是把任务写成一个小 issue：

1
2
3
4
5

目标：给订单列表增加按状态筛选功能。
范围：只改订单列表页和相关查询参数，不调整全局路由。
验收：页面出现状态筛选框；选择状态后列表刷新；刷新页面后筛选条件保留。
验证：运行 npm test，并手动检查订单列表页。
限制：不要重构无关组件，不要修改接口返回结构。

这种写法看起来啰嗦，但它会显著降低返工。Codex 最怕的不是任务复杂，而是任务含糊。你越能把“想要什么”和“不要什么”说清楚，它越容易给出可 review 的结果。

我的经验是：凡是超过十分钟的开发任务，都值得先写成小 issue。即使最后不是交给 Codex 做，这个过程也能帮自己想清楚。

技巧二：为仓库准备 AGENTS.md，把长期规则沉淀下来

如果每次都在提示里重复“项目用 pnpm”“测试命令是 npm test”“不要改 public 目录”“提交前要跑 lint”，时间久了会很烦，而且容易漏。

Codex 支持通过 AGENTS.md 这类仓库说明文件获得项目规则。你可以把它理解成给 AI 看的 README：告诉它项目结构、常用命令、代码风格、测试方式、哪些目录不能动、遇到失败时如何处理。

一个简单的 AGENTS.md 可以这样写：

1
2
3
4
5
6
7

# 项目规则

- 文章源码在 source/_posts。
- 静态资源放在 source/images。
- public 是生成目录，非必要不要手写修改。
- 修改文章后需要运行生成命令，并检查 archives 页面。
- 保持 Markdown front matter 格式：title/date/tags。

这类规则越早沉淀，后面越省心。Codex 做得不稳定，很多时候不是模型能力问题，而是项目没有把“好结果长什么样”告诉它。

技巧三：先让 Codex 读代码和写计划，不要直接开改

面对一个真实项目，我不建议第一步就让 Codex 修改文件。更稳的方式是先让它做两件事：

第一，阅读相关代码并总结当前结构。

第二，给出准备修改的计划。

比如可以这样说：

1
2

先不要修改代码。请阅读和用户登录相关的文件，说明当前登录流程、
token 存储位置、错误处理方式，然后给出最小修改计划。

这一步的价值很大。它能让你提前发现 Codex 是否找对了入口、是否理解了业务、是否准备改错层级。如果计划已经偏了，就不要让它继续实现。

对复杂任务来说，“先计划再实现”比“直接生成代码”慢几分钟，但通常能省掉半小时返工。

技巧四：一个任务只聚焦一个目标，控制变更范围

人类开发也一样，一个 PR 同时做登录、样式、数据库迁移、依赖升级，review 会非常痛苦。Codex 更是如此。

好的任务应该是可切分、可验证、可回滚的。比如：

不太好的任务：

1

帮我把后台系统整体优化一下，顺便修几个 bug，再加点测试。

更好的拆法：

1
2
3

任务1：修复用户列表分页参数丢失问题。
任务2：给用户列表补充分页相关测试。
任务3：整理用户列表组件里重复的状态判断。

每个任务都有一个焦点，Codex 就不容易迷路。你也更容易 review 它的输出。

技巧五：让 Codex 小步实现，并要求解释关键取舍

Codex 能一次性生成很多代码，但“大量生成”不等于“高效”。我更喜欢让它小步推进：

1
2
3
4
5

先完成最小可运行版本，不要做额外抽象。
完成后说明：
1. 改了哪些文件；
2. 为什么这样改；
3. 哪些地方可能需要后续优化。

这样做有两个好处。

第一，你能快速看到方向是否正确。

第二，Codex 会被迫解释自己的取舍，而不是只给结果。

当它解释“为什么这样改”时，你很容易看出它有没有理解项目。如果解释含糊，就继续追问；如果解释清楚，再进入下一步。

技巧六：把测试命令写进任务，而不是事后才想起来

Codex 的一个重要价值，是它可以帮你运行测试、构建、类型检查、格式检查等命令。但前提是它知道应该跑什么。

所以在任务里直接写：

1
2
3
4
5
6

完成后请运行：
- npm test
- npm run lint
- npm run build

如果某个命令失败，请说明失败原因、是否和本次改动有关，以及你如何处理。

如果项目没有自动化测试，也可以写手工验证标准：

1
2
3
4

没有单元测试。请生成后检查：
1. archives 页面出现 2026 年分组；
2. 新文章页面能打开；
3. 中文标题和标签显示正常。

这比“你看着办”可靠得多。Codex 可以帮你执行验证，但验证标准应该由人来定。

技巧七：把 Codex 用在阅读和定位上，不只是写代码

很多人低估了 Codex 的阅读能力。实际工作里，最耗时间的不一定是写代码，而是弄清楚代码在哪里、数据怎么流、为什么这个 bug 会出现。

有些特别适合交给 Codex 的阅读任务：

1

请梳理这个接口从路由到数据库查询的调用链。

1

请找出用户头像上传失败可能经过的所有错误处理分支。

1

请比较这两个组件的重复逻辑，说明是否值得抽公共组件。

这类任务风险低，收益高。即使最后不让 Codex 改代码，它也能帮你节省大量翻文件的时间。

我的习惯是：先让 Codex 当“代码导游”，再决定要不要让它当“代码作者”。

技巧八：用 /review 或明确 review 指令，让它站到审查者角度

写代码和审代码是两种不同心态。让 Codex 生成代码之后，最好再让它切换角色：

1
2
3
4
5
6

请以 code review 的角度检查刚才的改动，重点看：
1. 是否有无关文件改动；
2. 是否有未处理的异常路径；
3. 是否有兼容性风险；
4. 是否缺少测试；
5. 是否引入了过度抽象。

OpenAI 的 Codex 最佳实践也强调，不要只让 Codex 改代码，还要让它创建测试、运行检查、确认结果并 review 工作。这个思路非常重要：Codex 不应该只是“生产代码”，还应该帮助发现代码里的风险。

当然，AI review 不能代替人类 review。它更像第一道自动筛查，可以提前发现低级问题、遗漏分支和不一致风格。最终是否接受，仍然要人判断。

技巧九：权限要克制，默认从安全配置开始

效率和权限不是一回事。给 Codex 越多权限，它能做的事越多，但风险也越高。

比较稳的原则是：

第一，默认使用沙箱和审批。

第二，不把生产密钥、真实用户数据、内部敏感信息交给它。

第三，危险命令必须先说明目的，再由人确认。

第四，部署、删除、迁移、批量替换这类任务要格外谨慎。

官方最佳实践里也提到，如果刚开始使用 coding agent，应该从默认权限开始，保持 approval 和 sandboxing 收紧，等你理解工作流之后，再对可信仓库或特定流程放宽。

这点我很赞同。AI 工具最容易制造一种错觉：既然它能做，就让它全做。但工程里真正可靠的方式，是最小权限、可观察、可回滚。

技巧十：每次用完都复盘，把经验写回项目

Codex 用得好不好，不只取决于一次提示词，还取决于你有没有把经验沉淀下来。

每次任务结束后，可以复盘几个问题：

第一，哪些上下文给得有效？

第二，Codex 哪一步误解了？

第三，哪些测试命令必须写进下次任务？

第四，哪些规则应该放进 AGENTS.md？

第五，有没有可以沉淀成固定提示模板？

比如你发现 Codex 总是忘记运行某个检查，就把它写进 AGENTS.md。你发现某类任务总要提醒“不要修改生成目录”，也写进去。你发现某种 review checklist 很有效，就整理成 code_review.md，以后让 Codex 引用。

这就是复利。第一次用 Codex，可能只是省一点时间；第十次之后，如果规则、模板、测试、权限都沉淀好了，它省下的就不只是写代码时间，而是整个工程流程的沟通成本。

一个完整的使用模板

下面是我比较推荐的一段 Codex 任务模板，可以按项目改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

请完成以下任务：

目标：
- ...

范围：
- 允许修改：
- 不要修改：

上下文：
- 相关文件：
- 当前现象：
- 期望行为：

实现要求：
- 先阅读相关代码并给出计划。
- 计划确认后再修改。
- 保持改动最小，不做无关重构。

验证要求：
- 运行：
- 如果无法运行，请说明原因。
- 最后总结改动、验证结果和剩余风险。

这个模板看起来很普通，但它能解决大部分“AI 写偏了”的问题。因为它把目标、范围、上下文、实现、验证都拆开了。

总结

Codex 提高效率的关键，不是让开发者少思考，而是把重复、明确、可验证的工作交出去，让开发者把精力放在判断、设计和质量把关上。

我认为最值得记住的是这 10 点：

1. 把需求写成小 issue。
2. 用 AGENTS.md 沉淀项目规则。
3. 先让 Codex 读代码和写计划。
4. 一个任务只做一个焦点。
5. 小步实现，并解释关键取舍。
6. 把测试命令写进任务。
7. 让 Codex 帮你阅读和定位。
8. 用 review 指令检查风险。
9. 默认收紧权限和沙箱。
10. 每次用完都复盘沉淀。

用 Codex 最好的状态，不是“我完全不管，它自动完成”，而是“我把任务定义清楚，它帮我推进，我负责判断和验收”。这样才是真正稳定的软件工程效率提升。

参考资料

• OpenAI Codex
• OpenAI Codex best practices
• OpenAI Codex announcement