一句话结论：AI 编程真正的分水岭，不是模型能不能写代码，而是你能不能把需求变成“有边界、有依赖、有验收、有证据”的开发合同。

“把后台文章管理页优化一下，支持搜索、批量下架，并且别让人误操作。”

缺口

必须回答的问题

不回答的后果

目标

“优化”具体指什么？搜索速度、操作效率、界面结构还是减少误操作？

Codex 可能顺手重构样式，扩大改动范围

范围

搜索哪些字段？批量下架只处理当前页还是跨页选中？

前端交互与后端接口语义可能不一致

权限

谁可以批量下架？普通编辑是否可见按钮？

功能能用，但产生越权风险

失败语义

100 篇里 3 篇失败怎么办？全部回滚还是部分成功？

上线后才发现异常路径没有产品定义

完成标准

怎样证明“别让人误操作”已经满足？

只做确认弹窗，却漏掉不可下架状态、重复提交等情况

开发任务的最小结构 = 目标 + 范围 + 约束 + 依赖 + 验收标准 + 验证方式。

入口

用途

适合场景

`codex`

交互式会话

持续探索仓库、讨论方案、逐步实施

`codex exec`

非交互执行

脚本化任务、明确输入输出、CI 风格运行

`codex review`

审查代码变更

针对未提交变更、提交或分支做独立审查

`codex resume`

继续历史会话

延续之前上下文，适合分阶段开发

`codex doctor`

诊断环境

安装、配置、认证或运行时异常时优先检查

策略

示例

建议

只读分析

`--sandbox read-only`

需求澄清、架构理解、风险扫描；不应产生代码改动

工作区写入

`--sandbox workspace-write`

允许在仓库内修改和运行常规开发命令

按需审批

`--ask-for-approval on-request`

需要离开沙箱边界、访问网络或执行更敏感动作时再询问

无提示自动化

`--ask-for-approval never`

只适合边界已经被外部环境严格限制的自动化场景

完全绕过

`--dangerously-bypass-approvals-and-sandbox`

高风险，不应作为日常开发默认配置

# 需求分析：只读，不修改仓库
codex exec --sandbox read-only --ask-for-approval never   "分析下面的需求和当前仓库，输出待澄清问题、任务拆解和验收标准，不要修改任何文件。"

# 实施：允许写工作区，但越界动作需要审批
codex exec --sandbox workspace-write --ask-for-approval on-request   "按已确认的任务卡实现 T03，并运行相关测试。不要扩大范围。

# AGENTS.md

## 项目约束
- 使用 pnpm，不要生成 package-lock.json。
- 后端接口保持现有错误响应结构，不引入新的全局封装。
- 前端新交互必须覆盖 loading / empty / error 状态。
- 修改业务行为时补充对应测试。
- 不要修改与当前任务无关的格式和命名。

## 验证命令
- pnpm test --filter article
- pnpm lint
- pnpm typecheck

## 完成定义
- 相关测试通过。
- 无无关文件改动。
- 最终说明列出修改文件、验证结果和未执行项。

你现在只做需求分析，不修改任何文件。

需求：
“把后台文章管理页优化一下，支持搜索、批量下架，并且别让人误操作。”

请先阅读当前仓库中与文章列表、权限、文章状态、接口测试相关的实现。

输出必须包含：
1. 已从代码确认的事实；
2. 需求中存在的歧义；
3. 可以安全采用的默认假设；
4. 必须由产品/开发者确认的问题；
5. 明确的非目标；
6. 初步验收标准；
7. 建议拆成的最小可交付任务，以及任务依赖关系。

规则：
- 不要修改代码；
- 不要把猜测写成事实；
- 如果仓库已有相同模式，优先复用；
- 对每个高风险假设说明“如果猜错会造成什么后果”。

字段

确认后的约定

业务目标

减少内容运营在文章列表中的重复操作，同时降低批量下架误操作风险

搜索范围

按标题关键字搜索；作者搜索不在本次范围

选择范围

仅允许批量操作当前页已勾选项；翻页后清空选择

可操作状态

仅“已发布”文章可下架；草稿、已下架项不进入可操作集合

权限

沿用现有 `article:publish` 权限；无权限用户不显示入口，接口仍强制校验

批量上限

一次最多 100 篇，超过直接拒绝

确认机制

确认弹窗显示实际可下架数量，并明确不可操作项会被忽略

失败语义

采用部分成功：返回成功项与失败项，前端明确展示失败原因

非目标

不做跨页全选、不新增撤销功能、不重构列表 UI 框架

ID

任务

任务边界

依赖

完成标准

T01

确认现有文章列表与下架链路

只读分析，记录复用点、权限与状态模型

无

分析结果能指出相关文件、现有接口和测试入口

T02

增加标题搜索参数

列表查询支持 `q`，空字符串等价于未搜索

T01

接口测试覆盖命中、无结果、空值

T03

增加批量下架服务能力

一次 1~100 个 ID；只处理已发布；返回成功/失败明细

T01

服务层/接口测试覆盖边界、权限、部分失败与重复提交

T04

列表搜索交互

输入关键字后更新查询；清空恢复；翻页沿用当前搜索

T02

前端测试覆盖输入、清空、加载和空结果

T05

当前页批量选择

只选择当前页可下架项；翻页清空

T03

选择行为与禁用状态可被组件测试复现

T06

二次确认与批量提交

弹窗展示数量；防重复提交；展示部分失败

T03,T05

提交中按钮禁用；成功刷新；失败项有明确反馈

T07

权限与可见性复验

无权限不展示入口；后端越权返回 403

T03,T06

前后端双重权限测试通过

T08

全链路验收与审查

运行定向测试、规范检查、构建、差异审查

T02~T07

无阻断问题；若有未执行验证必须写明原因

场景

Given

When

Then

搜索命中

Given 列表存在标题“Codex CLI 实战”

When 输入“Codex”并提交搜索

Then 结果仅包含标题匹配项，分页总数同步变化

空搜索

Given 当前处于搜索结果

When 清空关键字

Then 恢复默认列表，并重置到第一页

批量确认

Given 当前页勾选 3 篇已发布文章

When 点击“批量下架”

Then 弹窗明确显示“将下架 3 篇文章”

越权

Given 用户无 `article:publish` 权限

When 直接调用批量下架接口

Then 返回 403，数据不变化

部分失败

Given 3 个 ID 中 1 个已被其他用户提前下架

When 提交批量下架

Then 返回 2 成功 + 1 失败，前端展示失败项并刷新列表

重复提交

Given 第一次请求仍在处理中

When 用户再次点击确认

Then 不发起第二个请求，按钮保持禁用/加载状态

# Task T03：批量下架服务能力

## 目标
在复用现有单篇下架规则的前提下，提供批量下架能力。

## 范围
- 接受 1~100 个 article_id。
- 仅允许处理“已发布”文章。
- 复用现有 article:publish 权限校验。
- 返回成功项和失败项，不采用全量事务回滚。

## 非目标
- 不实现跨页选择。
- 不增加撤销/恢复入口。
- 不重构文章状态模型。

## 验收标准
1. 空 ID 列表返回 400。
2. 超过 100 个 ID 返回 400。
3. 无权限返回 403，且没有任何文章状态被修改。
4. 已发布文章被成功下架。
5. 草稿/已下架/不存在 ID 进入 failed 列表，并返回可读原因。
6. 同一请求重复执行不会把已下架项误报为新成功。
7. 相关服务层与接口测试通过。

## 验证
- 运行文章模块定向测试。
- 运行类型检查/静态检查（若项目有）。
- 检查 git diff，确保没有无关改动。

## 停止条件
若发现现有单篇下架逻辑与以上规则冲突，不要自行改产品语义；先报告冲突和最小决策问题。

实现任务 T03。

要求：
- 先阅读相关现有实现和 AGENTS.md；
- 优先复用现有单篇下架的权限、状态转换和错误结构；
- 只修改完成 T03 必需的文件；
- 不顺手重构、改名或格式化无关代码；
- 完成后运行最相关的测试、类型检查和静态检查；
- 检查 git diff；
- 如果测试不能运行，明确写出原因和下一步可执行的替代验证；
- 如果产品语义存在冲突，只提出最小决策问题，不自行扩大范围。

最终输出：
1. 修改摘要；
2. 修改文件；
3. 验收标准逐条结果；
4. 实际执行的验证命令与结果；
5. 仍存在的风险或未执行项。

# 审查当前工作区未提交改动
codex review --uncommitted

# 或针对基准分支检查当前分支变化
codex review --base main

“把后台文章管理页优化一下，支持搜索、批量下架，并且别让人误操作。”

POST /api/articles/batch-offline
Content-Type: application/json

{
  "ids": [101, 102, 103]
}

# 成功 / 部分成功响应示意
{
  "succeeded": [101, 102],
  "failed": [
    {
      "id": 103,
      "reason": "ARTICLE_NOT_PUBLISHED"
    }
  ]
}

场景

输入

预期结果

正常

3 个已发布 ID

200；3 个进入 succeeded；状态全部变为已下架

混合状态

2 已发布 + 1 草稿

200；2 成功，草稿进入 failed

空输入

[]

400；数据库无写入

超过上限

101 个 ID

400；数据库无写入

越权

无权限用户

403；数据库无写入

重复请求

同一组 ID 连续请求两次

第二次不产生新的状态副作用；返回结果语义一致

不存在 ID

包含不存在 ID

存在项按规则处理；不存在项进入 failed

T03 验收结果

修改摘要：
- 新增批量下架服务与接口。
- 复用现有 article:publish 权限与单篇状态转换规则。
- 支持部分成功响应。

验收标准：
[通过] 1~100 个 ID。
[通过] 空列表 / 超上限返回 400。
[通过] 越权返回 403 且无写入。
[通过] 草稿 / 已下架 / 不存在 ID 进入 failed。
[通过] 重复提交无额外副作用。

验证：
- article service tests: 18 passed
- article API tests: 12 passed
- typecheck: passed
- lint: passed
- git diff: 无无关文件改动
- code review: 无阻断问题

未执行项：
- 全仓库 E2E 未运行；本任务未修改浏览器流程，已由 T08 统一执行。

失败模式

典型表现

纠正方法

任务太大

“把文章管理模块整体优化完”

拆到每项都有独立行为和独立验证命令

把猜测当事实

默认权限名、状态值、接口风格

先读仓库；输出中把事实与假设分开

验收标准写实现

“新增 BatchOfflineService”

改写成用户/系统可观察行为

只测 Happy Path

正常数据能通过就结束

强制列空值、越权、部分失败、重复提交、并发边界

顺手重构

实现功能同时清理大量旧代码

把“无关改动为零”写入任务卡与差异检查

测试放到最后

几个任务做完才一起跑

每个垂直切片完成就运行最窄相关测试

权限开太大

为了省事直接完全访问

需求分析只读；实现工作区写；越界按需审批

只信最终总结

看到“tests passed”就接受

要求列出实际命令、结果；必要时由你或 CI 再跑一遍

只做分析，不修改文件。

需求：<粘贴原始需求>

请结合当前仓库输出：
- 已确认事实；
- 需求歧义；
- 安全默认假设；
- 必须确认的问题；
- 非目标；
- 风险与依赖；
- 可验证的验收标准；
- 最小可交付任务清单和依赖关系。

不要把猜测写成事实。高风险假设必须说明猜错的后果。

实现任务 <ID>：<任务名称>。

目标：<用户/系统最终获得的行为>
范围：<允许修改的边界>
非目标：<明确不做的事>
约束：<权限、兼容、数据、依赖、项目规则>
验收标准：<逐条可执行检查>
验证命令：<相关测试 / lint / typecheck / build>
停止条件：<遇到什么冲突时必须询问，而不是猜>

实施要求：
- 先检查现有实现并复用仓库模式；
- 只做本任务必要改动；
- 完成后运行验证并检查差异；
- 最终逐条报告验收结果与未执行项。

审查当前变更是否满足任务卡，不修改代码。

重点检查：
1. 是否遗漏任何验收标准；
2. 是否存在权限绕过、状态不一致、重复提交或并发问题；
3. 是否扩大了改动范围；
4. 测试是否真的覆盖新行为和失败路径；
5. 错误处理是否与现有项目约定一致；
6. 是否存在“看起来通过但实际上没有验证”的结论。

输出按严重度排序：
- 阻断：必须修复后才能验收；
- 应修：有明确缺陷或回归风险；
- 建议：不影响本任务验收的改进。

每个问题给出文件/位置、触发条件、影响和最小修复方向。

给代理更多执行时间之前，先给它更清楚的完成定义。自主性的前提不是“信任模型”，而是“限制问题空间 + 提供验证工具”。

codex exec --sandbox read-only   --output-last-message task-analysis.md   "分析当前分支的实现风险，并输出可执行修复任务，不要修改文件。

阶段

检查问题

需求进入开发前

目标是否是可观察结果，而不是“优化一下”？

需求进入开发前

非目标是否写清，防止顺手扩范围？

需求进入开发前

高风险假设是否已经确认？

任务拆分后

每个任务能否独立验证？依赖是否明确？

任务拆分后

验收是否覆盖正常、边界、权限、异常与恢复？

实施开始前

当前沙箱与审批权限是否只给到本阶段所需？

实施结束后

是否运行了最相关测试，并记录实际结果？

实施结束后

是否检查差异，确认没有无关改动？

实施结束后

是否做了独立审查，而不是只相信实现者总结？

最终交付前

是否明确列出未执行验证和剩余风险？

真正高效的 AI 开发，不是让 Codex 一次写更多代码，而是让每次修改都更接近可验收状态。需求越清楚，任务越小，证据越完整，代理就越像可靠的工程协作者，而不是一个高速度的猜测器。