Codex CLI 实战：从读项目到修复一个可复现的 bug

正确目录
  -> 干净的 Git 基线
  -> 可重复的失败
  -> 项目地图与根因
  -> 有边界的修复计划
  -> 最小 diff
  -> 同一条测试转绿
  -> /diff + /review

输入： [" Codex ", "AI", "codex", " "]
输出： ["ai", "codex"]

codex-cli-lab/
├─ package.json
├─ src/
│  └─ normalize-tags.js
└─ test/
   └─ normalize-tags.test.js

{
  "name": "codex-cli-lab",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test"
  }
}

export function normalizeTags(tags) {
  return [...new Set(tags.map((tag) => tag.trim().toLowerCase()))].sort();
}

import test from "node:test";
import assert from "node:assert/strict";

import { normalizeTags } from "../src/normalize-tags.js";

test("trims, normalizes, and deduplicates tags", () => {
  assert.deepEqual(
    normalizeTags([" Codex ", "AI", "codex"]),
    ["ai", "codex"],
  );
});

test("drops blank tags", () => {
  assert.deepEqual(normalizeTags(["AI", " ", ""]), ["ai"]);
});

test("returns an empty list when tags are missing", () => {
  assert.deepEqual(normalizeTags(null), []);
});

test("ignores non-string values", () => {
  assert.deepEqual(normalizeTags(["AI", null, 42, "Codex"]), ["ai", "codex"]);
});

cd codex-cli-lab
git init
git add package.json src test
git commit -m "add failing normalize tags fixture"

npm test

✔ trims, normalizes, and deduplicates tags
✖ drops blank tags
✖ returns an empty list when tags are missing
✖ ignores non-string values

tests 4
pass 1
fail 3

codex --cd ./codex-cli-lab --sandbox workspace-write --ask-for-approval on-request

codex --cd ./unknown-repo --sandbox read-only --ask-for-approval on-request

/status

先不要改文件。请运行 git status --short，确认当前工作树是否干净；
如果不干净，列出已有改动并停下来。

先不要修改文件。

请完成以下 Explore：
1. 读取 package.json、src/normalize-tags.js 和 test/normalize-tags.test.js；
2. 运行 npm test，记录失败测试名称和关键错误；
3. 说明输入如何流入 normalizeTags，逐条对应三个失败的根因；
4. 列出最小修改范围和不需要修改的文件；
5. 如果失败结果与任务描述不一致，停下来报告，不要猜。

输出格式：项目地图、复现证据、根因、修改边界、验证入口。

/mention src/normalize-tags.js
/mention test/normalize-tags.test.js

项目地图
- package.json：测试入口 npm test -> node --test
- src/normalize-tags.js：唯一实现文件
- test/normalize-tags.test.js：4 条行为测试

复现证据
- npm test：1 passed, 3 failed
- blank case：返回数组包含空字符串
- missing case：在 tags.map 处抛 TypeError
- mixed case：在 tag.trim 处抛 TypeError

根因
- 函数默认 tags 一定是数组
- 函数默认每个元素一定是字符串
- trim 后没有过滤空字符串

修改边界
- 修改 src/normalize-tags.js
- 如需锁定行为，可补测试，但不改 package.json 和项目结构

验证入口
- npm test

/plan

请基于刚才的证据给最小修复计划。

验收标准：
- 非数组输入返回 []；
- 只处理字符串元素，忽略 null、数字等非字符串值；
- 每个字符串 trim 后转小写；
- 丢弃空字符串；
- 去重并按现有行为排序；
- 不新增依赖，不改 package.json，不扩大公开 API；
- 最终 npm test 全部通过。

计划里写清：改哪些行、为什么、如何验证、还剩什么边界风险。
先不要实现。

1. 在 normalizeTags 开头检查 Array.isArray，非数组直接返回 []。
2. 过滤非字符串值，再 trim、lowercase、过滤空字符串。
3. 保留 Set 去重和 sort 排序，避免改变已有输出契约。
4. 运行 npm test；检查 diff 只包含目标函数。

按计划实现，只修改 src/normalize-tags.js。
完成后先不要继续重构，输出实际 diff 摘要，再运行 npm test。

 export function normalizeTags(tags) {
-  return [...new Set(tags.map((tag) => tag.trim().toLowerCase()))].sort();
+  if (!Array.isArray(tags)) {
+    return [];
+  }
+
+  const normalized = tags
+    .filter((tag) => typeof tag === "string")
+    .map((tag) => tag.trim().toLowerCase())
+    .filter(Boolean);
+
+  return [...new Set(normalized)].sort();
 }

npm test

✔ trims, normalizes, and deduplicates tags
✔ drops blank tags
✔ returns an empty list when tags are missing
✔ ignores non-string values

tests 4
pass 4
fail 0

请运行 git status --short 和 git diff --check，确认：
1. 只有 src/normalize-tags.js 被修改；
2. 没有空白错误；
3. 没有未跟踪的临时文件。

/diff

/review

请按 bug 风险优先 review 当前未提交改动，重点检查：
- 是否满足 4 条测试对应的行为；
- 是否意外改变排序、大小写或去重契约；
- 是否有无关重构；
- 测试是否遗漏关键边界；
- 如果没有阻塞问题，明确写“未发现阻塞问题”，并列出剩余风险。

未发现阻塞问题。

验证：4/4 tests passed；diff 仅修改 normalize-tags.js。

剩余风险：
- 当前函数会静默忽略对象、数字等非字符串输入；这是本文验收标准，
  但真实业务若要求暴露脏数据，应改为记录或抛错。
- sort() 使用 JavaScript 默认字符串排序；若未来需要中文或 locale-aware 排序，
  需要单独定义契约。

请给出最终交付摘要：
1. 根因；
2. 修改文件与行为变化；
3. 实际运行的验证命令和结果；
4. review 结论；
5. 剩余风险；
6. 明确说明是否执行了提交、推送或远端操作。

codex resume --last

codex resume <SESSION_ID>

codex exec resume --last "继续上次检查，只输出尚未解决的问题。"

/compact

/status -> Explore -> /plan -> Code -> /diff -> Verify -> /review

codex --ask-for-approval never exec \
  --cd ./your-repo \
  --sandbox read-only \
  "检查 Markdown 的本地图片引用和相对链接是否指向存在的文件，只输出失败项，不改文件。"

codex --ask-for-approval never exec \
  --cd ./your-repo \
  --sandbox read-only \
  --output-last-message review-summary.md \
  "只读 review 当前 diff，按严重程度输出问题、测试缺口和剩余风险。"

codex --ask-for-approval never exec \
  --cd ./your-repo \
  --sandbox read-only \
  --json \
  --output-last-message review-summary.md \
  "检查当前 diff，只读，不改文件。" > codex-events.jsonl

{
  "type": "object",
  "properties": {
    "status": { "enum": ["pass", "needs_changes"] },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": { "enum": ["P0", "P1", "P2"] },
          "file": { "type": "string" },
          "message": { "type": "string" }
        },
        "required": ["severity", "file", "message"],
        "additionalProperties": false
      }
    }
  },
  "required": ["status", "findings"],
  "additionalProperties": false
}

codex --ask-for-approval never exec \
  --cd ./your-repo \
  --sandbox read-only \
  --output-schema review.schema.json \
  --output-last-message review.json \
  "只读 review 当前 diff，按 schema 输出。"

codex exec --ephemeral "总结这个仓库的目录结构，不改文件。"

pwd
git rev-parse --show-toplevel
codex --cd <正确项目路径>

unexpected argument '--ask-for-approval'

codex --ask-for-approval never exec --cd ./repo --sandbox read-only "..."

codex --version
codex --help
codex exec --help

[启动]
codex --cd <repo> --sandbox workspace-write --ask-for-approval on-request

[基线]
/status
git status --short
先复现，不改文件。

[Explore]
输出入口、调用链、失败命令、根因、修改边界和验证入口。
必要时用 /mention 或 @ 附加关键文件。

[Plan]
/plan
写清验收标准、改什么、不改什么、如何验证。

[Code]
只做计划内最小 diff；计划不成立时停下来。

[Verify]
先重跑原始失败命令，再跑受影响范围的检查。
记录实际命令和结果。

[Review]
/diff
/review
检查回归、无关改动、测试缺口和剩余风险。

[交付]
总结根因、文件、行为变化、验证结果、剩余风险，
并说明是否执行了 commit、push、deploy 或其他远端操作。