codex-task 0.2.2 → 0.2.4

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-task",
-  "version": "0.2.2",
-  "description": "Delegate focused text, image, and workspace tasks to CodexTask",
+  "version": "0.2.4",
+  "description": "Delegate multimodal text, image, and workspace tasks to CodexTask",
   "author": {
     "name": "wang121ye",
     "url": "https://github.com/wangyendt"
@@ -18,8 +18,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "CodexTask",
-    "shortDescription": "Delegate text, image, and workspace tasks",
-    "longDescription": "A companion skill for routing focused text, image, and workspace tasks through the CodexTask CLI.",
+    "shortDescription": "Delegate multimodal text, image, and workspace tasks",
+    "longDescription": "A companion skill for routing composable text, image, and workspace inputs through the CodexTask CLI.",
     "developerName": "wang121ye",
     "category": "Developer Tools",
     "capabilities": [

package/README.md

@@ -1,273 +1,314 @@
 # CodexTask
 
-> Give another AI agent a focused errand—and get back text, images, or finished work. Powered by your existing Codex setup.
+> 把文本、图片和项目任务交给另一个 Codex worker，拿回结构化文本、生成图片或已经完成的工作区变更。
 
-[中文文档](./README.zh-CN.md) · [PRD](./docs/PRD.md) · [Common commands](./docs/常用命令.txt) · [Companion skill](./skills/codex-task/SKILL.md)
+[English](./README_EN.md) · [产品需求文档](./docs/PRD.md) · [远程部署与手机调用](./docs/knowhow/20260811_远程服务部署与移动端调用.md) · [常用命令](./docs/常用命令.txt) · [Companion Skill](./skills/codex-task/SKILL.md)
 
-CodexTask turns Codex into a small, composable worker for other agents. It ships one CLI, one TypeScript API, and one installable skill for three jobs:
+CodexTask 是一个轻量、可组合的跨 Agent 多模态任务运行器。它提供 CLI、TypeScript API、可安装给其他 Agent 的 Skill，以及可选的自托管 HTTP 服务；没有中心化托管平台，也不需要额外 API key。
 
-- focused text-to-text tasks;
-- text-to-image and image-to-image generation;
-- bounded workspace tasks through the official Codex SDK.
+你只需要按“想拿回什么”选择命令：
 
-No daemon. No hosted service. No extra API key. Results are stable JSON that another agent can consume.
+| 期望结果 | 命令 | 可组合输入 | 典型任务 |
+| --- | --- | --- | --- |
+| 文本 | `codex-task text` | 文本、多个 prompt 文件、最多 5 张图片、stdin | 文生文、图生文、图文生文 |
+| 图片 | `codex-task image` | 文本、多个 prompt 文件、最多 5 张参考图、stdin | 文生图、图生图、图文生图 |
+| 工作区变更 | `codex-task task` | 文本、多个 prompt 文件、最多 5 张图片、当前项目 | 写代码、改文件、运行命令 |
+| 恢复任务 | `codex-task resume` | task ID、补充文本/文件/图片 | 回答追问后继续同一个 Codex task |
 
 > [!IMPORTANT]
-> CodexTask is an independent, unofficial open-source project. It is not affiliated with, endorsed by, or sponsored by OpenAI. Codex and OpenAI are trademarks of OpenAI.
+> CodexTask 是独立的非官方开源项目，与 OpenAI 不存在隶属、认可或赞助关系。Codex 与 OpenAI 为 OpenAI 的商标。
 
-## Quick start
+## 30 秒上手
 
-Requirements: Node.js 20+ and an existing Codex login (`codex login`).
+需要 Node.js 20+，并已执行过 `codex login`。
 
 ```bash
 npm install -g codex-task
 codex-task doctor
 ```
 
-Delegate a text result:
+下面用同一份“健身营养餐”串起文生图、图生文、图生图、工作区任务和恢复。图片与 JSON 都来自真实模型请求，不是占位图或手写示意；由于生成模型具有随机性，重新执行会得到不同但同类的结果。
+
+### 1. 生成图片：一份健身营养餐
 
 ```bash
-codex-task text "Turn these notes into a crisp release announcement" \
-  --backend direct
+codex-task image "生成一份写实、干净的健身营养餐：香煎鸡胸肉、糙米、西兰花、牛油果；四种食物分区摆放，俯拍，完整餐盘，食材边界清晰；浅灰桌面，柔和自然光；不要文字、水印、餐具和其他食物。" -o ./docs/assets/fitness-meal.png --size 1024x1024 --quality high
 ```
 
-Generate an image that will not be removed by temporary-file cleanup:
+这个示例用 `--output` 保存到 README 资产目录；省略它时，最终图片默认保存在当前目录，而不是临时目录：
 
-```bash
-codex-task image "A precise exploded-view diagram of a compact robot joint" \
-  --backend direct \
-  --size 1536x1024 \
-  --quality high \
-  --output ./artifacts
+```json
+{
+  "status": "completed",
+  "taskId": "78cda394-e16f-4cac-9d0f-9b8a010e3879",
+  "backend": "direct",
+  "text": "Generated 1 image(s).",
+  "effectiveModel": "gpt-5.5",
+  "artifacts": [
+    { "path": "/your/project/docs/assets/fitness-meal.png", "kind": "image", "mimeType": "image/png" }
+  ]
+}
 ```
 
-Edit an image:
+真实生成结果：
 
-```bash
-codex-task image "Keep the object; replace the background with a clean workshop" \
-  --backend direct \
-  --image ./reference.png \
-  --output ./artifacts
-```
+![CodexTask 文生图生成的健身营养餐](./docs/assets/fitness-meal.png)
 
-Delegate repository work:
+### 2. 图片 + prompt → JSON 营养分析
 
 ```bash
-codex-task task "Implement the requested feature and run focused tests" \
-  --backend sdk \
-  --cwd /absolute/path/to/repo
+codex-task text "识别图片中的全部食物，估算每项可食部分重量和热量。重量和热量必须是数字；热量为基于视觉份量的近似值；note 用中文说明估算存在误差。" -i ./docs/assets/fitness-meal.png --schema ./docs/examples/nutrition.schema.json --model gpt-5.6-sol --reasoning medium
 ```
 
-Every command writes a machine-readable result:
+图生文输入就是上一步的真实图片：
+
+<img src="./docs/assets/fitness-meal.png" alt="CodexTask 图生文输入图片" width="520">
+
+`text` 不只是文生文，也支持图生文和图文生文。下面是该命令真实返回的结构化内容，完整文件见 [`fitness-meal-analysis.json`](./docs/examples/fitness-meal-analysis.json)：
 
 ```json
 {
-  "status": "completed",
-  "taskId": "e6fe7ed7-72de-4b27-8b6e-08152192d6cb",
-  "backend": "direct",
-  "text": "...",
-  "effectiveModel": "gpt-5.6-sol",
-  "reasoningEffort": "medium",
-  "artifacts": []
+  "foods": [
+    { "name": "煎烤鸡胸肉", "estimatedGrams": 220, "calories": 380 },
+    { "name": "熟糙米饭", "estimatedGrams": 250, "calories": 280 },
+    { "name": "西兰花", "estimatedGrams": 170, "calories": 60 },
+    { "name": "牛油果", "estimatedGrams": 100, "calories": 160 }
+  ],
+  "totalCalories": 880,
+  "note": "以上重量和热量根据图片中的视觉份量估算，实际数值会因食材品种、烹饪用油及熟制程度而存在误差。"
 }
 ```
 
-## Pick the backend
+这只是视觉估算，不应替代称重或专业营养建议。
 
-CodexTask never guesses. Direct is the CLI default, but workspace tasks require an explicit SDK backend.
+### 3. 图片 + prompt → 高蛋白版本图片
 
-| Capability | `direct` | `sdk` |
-| --- | --- | --- |
-| Focused text result | Yes | Yes |
-| Text-to-image / image-to-image | Yes, native result extraction | Yes, via the installed `$imagegen` skill |
-| Shell and file edits | No | Yes |
-| Project rules and local tools | No | Yes |
-| Local Codex skills | No | Normal Codex discovery |
-| Transport | Unofficial ChatGPT Codex Responses | Official `@openai/codex-sdk` |
-| Stability | Experimental | Supported SDK surface |
+```bash
+codex-task image "把这份餐食调整成高蛋白低碳版本：增加约 50% 的鸡胸肉，糙米减少约一半；只改变鸡胸肉和糙米的份量，保持餐盘、俯拍机位、光线、牛油果、西兰花和写实摄影风格不变；不要增加其他食物、文字或水印。" -i ./docs/assets/fitness-meal.png -o ./docs/assets/fitness-meal-high-protein.png --size 1024x1024 --quality high
+```
 
-Direct reuses `$CODEX_HOME/auth.json`, Codex installation metadata, TLS impersonation, and the private ChatGPT Codex Responses endpoint. Inputs are still sent to ChatGPT. The interface may change without notice.
+| 图生图输入 | 真实图生图输出 |
+| --- | --- |
+| <img src="./docs/assets/fitness-meal.png" alt="原始健身营养餐" width="420"> | <img src="./docs/assets/fitness-meal-high-protein.png" alt="高蛋白低碳版本健身营养餐" width="420"> |
+| 原始份量 | 增加鸡胸肉、减少糙米 |
 
-The SDK backend defaults to:
+### 4. 多份要求 + 参考图 → 完成项目
 
-```text
-sandbox: danger-full-access
-approval: never
-network: true
+```bash
+codex-task task "实现一个健身营养餐详情页，并运行相关测试" -f ./requirements.md -f ./api-contract.md -i ./docs/assets/fitness-meal.png --cwd ./meal-app
 ```
 
-That combination is intentionally powerful: it can read and write outside the workspace, execute commands, and use the network without asking for approval. Only delegate trusted prompts and repositories.
+`task` 固定使用官方 Codex SDK，不需要再写 `--backend sdk`。`--cwd ./meal-app` 表示：把该目录作为 worker 的当前项目；Codex 会从这里读取代码、项目规则与 skills，并在授权范围内修改文件、执行命令。
 
-## Agent follow-ups
+```json
+{
+  "status": "completed",
+  "taskId": "7dd7a7d7-...",
+  "backend": "sdk",
+  "threadId": "019...",
+  "text": "已实现营养餐详情页并通过相关测试。",
+  "changes": ["src/pages/MealDetail.tsx", "test/MealDetail.test.tsx"],
+  "commands": [{ "command": "npm test -- MealDetail", "exitCode": 0 }],
+  "artifacts": []
+}
+```
+
+### 5. 回答追问并继续
 
-SDK tasks are single-turn first. If the worker needs clarification, the result is not an error:
+如果任务存在关键歧义，`task` 可能返回：
 
 ```json
 {
   "status": "needs_input",
-  "taskId": "...",
-  "threadId": "...",
-  "questions": ["Should the API preserve the legacy response shape?"],
+  "taskId": "7dd7a7d7-...",
+  "questions": ["页面按单人份还是双人份展示热量？"],
   "artifacts": []
 }
 ```
 
-Ask the user, then resume the same Codex thread:
+取得答案后，用同一个 task ID 恢复；补充回答也可以同时带多个文件和图片：
 
 ```bash
-printf '%s' "Yes, preserve it." | codex-task resume <task-id>
+codex-task resume 7dd7a7d7-... "按单人份展示" -f ./copy-guidelines.md -i ./expected-layout.png
 ```
 
-Pass `--no-followup` to require reasonable assumptions and a completed/failed result in one caller turn. It does not guarantee the model succeeds.
-
-## Use from another agent
+```json
+{
+  "status": "completed",
+  "taskId": "7dd7a7d7-...",
+  "backend": "sdk",
+  "text": "已按单人份完成页面和测试。",
+  "changes": ["src/pages/MealDetail.tsx"],
+  "artifacts": []
+}
+```
 
-This repository ships `skills/codex-task/SKILL.md`. It teaches a calling agent when to choose text, image, task, or resume. It is a companion skill, not a skill injected into the Codex worker.
+## 组合输入，而不是四选一
 
-Install it with [SkillTruck](https://github.com/wangyendt/skilltruck):
+位置 prompt、重复的 `-f/--prompt-file`、非空 stdin 和重复的 `-i/--image` 可以同时出现：
 
 ```bash
-npm install -g skilltruck
-skilltruck install https://github.com/wangyendt/codex-task --global
+printf '%s' "总热量控制在 700 kcal 内" | codex-task text "制定调整建议" -f ./training-goal.md -f ./allergies.md -i ./meal-front.png -i ./meal-side.png
 ```
 
-Or locate the copy included in the npm package:
+CodexTask 按固定顺序组合输入：位置 prompt → prompt 文件（按命令行顺序）→ stdin；图片保持 `-i` 的顺序。文件内容会带绝对路径边界标记，避免多份长 prompt 混在一起。每张图片不超过 20 MiB，总和不超过 50 MiB。
 
-```bash
-codex-task skill path
-```
+## 两种后端
 
-The repository also includes `.codex-plugin/plugin.json` for plugin-compatible distribution.
+`text` 和 `image` 默认使用 Direct，可手动传 `--backend sdk`。`task` 和 `resume` 固定使用 SDK，不做自动猜测。
 
-## TypeScript API
-
-```ts
-import { generateImage, generateText, runTask } from "codex-task";
+| 能力 | `direct` | `sdk` |
+| --- | --- | --- |
+| 文本结果 | 支持文本与图片输入 | 支持文本与图片输入 |
+| 图片结果 | 原生提取生成图片 | 让 Codex 调用已安装的 `$imagegen` skill |
+| shell、文件修改、项目规则 | 不支持 | 支持 |
+| 本地 Codex skills | 不支持 | 按 Codex 正常发现 |
+| 底层 | 非官方 ChatGPT Codex Responses | 官方 `@openai/codex-sdk` |
 
-const copy = await generateText({
-  prompt: "Write a launch headline and three supporting bullets.",
-  backend: "direct",
-});
+Direct 复用 `$CODEX_HOME/auth.json`、Codex installation metadata、TLS impersonation 和 ChatGPT 私有 Codex Responses 接口。输入仍会发往 ChatGPT，接口可能随时变化。Direct 只返回生成结果，不能读项目、运行 shell、调用本地 MCP 或使用 worker skills。
 
-const image = await generateImage({
-  prompt: "A restrained isometric illustration of agent-to-agent delegation.",
-  backend: "direct",
-  output: "./artifacts",
-  quality: "high",
-});
+SDK task 默认权限为：
 
-const work = await runTask({
-  prompt: "Add the feature and run focused tests.",
-  backend: "sdk",
-  workingDirectory: "/absolute/path/to/repo",
-});
+```text
+sandbox: danger-full-access
+approval: never
+network: true
 ```
 
-For progress events:
+这意味着 worker 可以访问工作区外路径、执行命令并联网，而且不会等待权限确认。只委派可信 prompt 和可信项目；需要收窄时显式传 `--sandbox workspace-write` 或 `--no-network`。
 
-```ts
-import { streamTaskEvents } from "codex-task";
+## 图片输出与临时文件
 
-for await (const event of streamTaskEvents({
-  kind: "text",
-  options: { prompt: "Summarize this decision", backend: "direct" },
-})) {
-  console.log(event);
-}
+- 默认：在当前目录生成唯一文件名，例如 `./image-a1b2c3d4.png`；这是持久用户文件，`gc` 不会删除。
+- 指定位置：传 `-o ./artifacts` 或 `-o ./meal.png`。
+- 临时产物：显式传 `--temp`，写入 `os.tmpdir()/codex-task/<task-id>`，24 小时后可被清理。
+- `--temp` 与 `--output` 互斥；已有目标默认拒绝覆盖，只有 `--overwrite` 才允许替换。
+
+```bash
+codex-task image "生成三个便当配色方案" -n 3 -o ./artifacts
+codex-task image "仅供本轮分析的草图" --temp
+codex-task gc
 ```
 
-The event stream reports item and task progress; it is not guaranteed token streaming.
+图片参数：`size=auto|WIDTHxHEIGHT`（最长边 ≤ 3840）、`quality=auto|low|medium|high`、`background=auto|opaque|transparent`、`count=1–10`、`concurrency=1–3`。
 
-## Image controls
+## 安装给其他 Agent
 
-```text
-references   0–5 local PNG/JPEG/WebP/GIF files
-size         auto or WIDTHxHEIGHT; longest edge ≤ 3840
-quality      auto | low | medium | high
-background   auto | opaque | transparent
-count        1–10
-concurrency  1–3, default 1
+仓库内置 [`skills/codex-task/SKILL.md`](./skills/codex-task/SKILL.md)。它教调用方 Agent 何时运行 `text`、`image`、`task` 或 `resume`；它不是注入底层 Codex worker 的 skill。
+
+Skill 和 CLI 是两件事：SkillTruck 负责安装 Skill，npm 负责安装可执行命令。安装 Skill 不会自动全局安装 npm 包。
+
+```bash
+npm install -g skilltruck codex-task
+skilltruck install https://github.com/wangyendt/codex-task --global
 ```
 
-Each reference may be at most 20 MiB, with a 50 MiB combined limit. Existing outputs are rejected unless `--overwrite` is supplied. Completed images are atomically saved immediately, so a later batch failure does not discard earlier artifacts.
+如果不想全局安装 CLI，Agent 可回退到 `npx --yes codex-task@latest`。也可以运行 `codex-task skill path` 查看 npm 包内 Skill 的位置。
+
+## 手机远程调用与开机自启
 
-## Inputs and output
+`codex-task serve` 把四类任务开放为带 Bearer Token 的异步 HTTP API。手机提交后先拿到 `jobId`，再轮询状态；这样不会因为一次图片或工作区任务耗时几分钟而一直占住移动端请求。
+
+| 目标 | 接口 |
+| --- | --- |
+| 文本结果 | `POST /v1/text` |
+| 图片结果 | `POST /v1/image` |
+| 工作区变更 | `POST /v1/task` |
+| 回答追问 | `POST /v1/tasks/:taskId/resume` |
+| 查询进度 | `GET /v1/jobs/:jobId` |
+| 下载产物 | `GET /v1/jobs/:jobId/artifacts/:index` |
 
-Long prompts can come from a file or stdin:
+持久服务选择 `npm install -g codex-task@latest`，不使用 `npx`：开机启动不应依赖 npm 网络，启动程序路径也应稳定。三平台脚本会安装或升级全局包、生成随机 token、创建用户级自启动项并立即启动服务。
 
 ```bash
-codex-task text --prompt-file task.md --backend direct
-printf '%s' "$PROMPT" | codex-task task --backend sdk --cwd .
+# Ubuntu：systemd user service
+bash ./scripts/service/install-ubuntu.sh
+
+# macOS：LaunchAgent
+bash ./scripts/service/install-macos.sh
+
+# Windows PowerShell：Scheduled Task
+powershell -ExecutionPolicy Bypass -File .\scripts\service\Install-Windows.ps1
 ```
 
-The positional prompt, `--prompt-file`, and stdin are mutually exclusive.
+默认监听 `0.0.0.0:7777` 以便手机访问，安装完成会打印 token。手机地址应填写电脑的局域网/VPN 地址，例如 `http://192.168.1.50:7777`，不能填写 `0.0.0.0`。
 
-Default stdout is one JSON result. `--stream` switches stdout to JSONL events. Diagnostics go to stderr. Exit codes are:
+```bash
+curl -sS http://127.0.0.1:7777/healthz
+curl -sS -X POST http://127.0.0.1:7777/v1/text -H "Authorization: Bearer $CODEX_TASK_TOKEN" -H 'Content-Type: application/json' -d '{"prompt":"把这段需求整理成三条要点"}'
+curl -sS http://127.0.0.1:7777/v1/jobs/替换为jobId -H "Authorization: Bearer $CODEX_TASK_TOKEN"
+```
 
-| Code | Meaning |
-| --- | --- |
-| `0` | `completed` or `needs_input` |
-| `1` | execution failure |
-| `2` | invalid arguments or configuration |
-| `130` | cancellation or timeout |
+> [!CAUTION]
+> 服务不内置 TLS，不能直接暴露到公网。建议只在可信局域网、Tailscale/WireGuard 或 HTTPS 反向代理后使用。Token 持有者实际上拥有该电脑上 CodexTask 的执行权；远程 `task` 默认仍是 `danger-full-access`、可联网、`approval: never`。服务重启会丢失内存中的远程 job 查询记录，终态 job 和下载链接默认保留 24 小时；已返回的 SDK `taskId` 仍可按 CodexTask 自身状态恢复。
 
-## Models and configuration
+Android Kotlin 与 iOS Swift 的完整示例在 [`examples/mobile`](./examples/mobile/README.md)：流程会先调用 `image` 生成营养餐，下载图片后调用 `text` 做图生文，再调用 `task` 修改服务器上的项目，必要时通过 `resume` 回答追问。更完整的部署、升级、卸载、JSON 字段和安全说明见[远程服务部署与移动端调用](./docs/knowhow/20260811_远程服务部署与移动端调用.md)。
 
-The SDK backend leaves model and reasoning unset unless you override them, allowing normal Codex configuration discovery.
+## TypeScript API
 
-Direct resolves its model in this order:
+```ts
+import { generateImage, generateText, runTask } from "codex-task";
 
-1. `--model` / API option;
-2. Codex `config.toml`;
-3. the preferred visible model in `models_cache.json`;
-4. compatibility fallback.
+const meal = await generateImage({
+  prompt: "生成一份高蛋白健身营养餐",
+  output: ".",
+});
 
-It supports classic Responses and Responses Lite encoders. With a current Codex model catalog, text defaults to `gpt-5.6-sol` with `medium` reasoning. The private Responses Lite route rejects hosted `image_generation`, so Direct image requests are preflighted to the compatible classic `gpt-5.5` model before any request is sent. The final JSON always reports `effectiveModel` and `reasoningEffort`.
+const analysis = await generateText({
+  prompt: "识别食物并估算热量，只返回 JSON",
+  promptFiles: ["./nutrition-rules.md", "./allergies.md"],
+  imagePaths: [meal.artifacts[0]!.path],
+});
 
-Configuration precedence is API/CLI → `CODEX_TASK_*` environment variables → user config → Codex config → fallback. The user config is `config.json` under the standard platform config directory; run `codex-task doctor` to see the exact path.
+const work = await runTask({
+  prompt: "根据要求实现营养餐详情页并测试",
+  promptFiles: ["./requirements.md", "./api-contract.md"],
+  imagePaths: [meal.artifacts[0]!.path],
+  workingDirectory: "./meal-app",
+});
+```
 
-For migration, `CODEXERRAND_*` variables and the former CodexErrand config/task paths are recognized only when their `CODEX_TASK_*` or CodexTask equivalents are absent. New state is always written under CodexTask paths.
+`streamTaskEvents()` 可输出 JSONL 级别的 item/task 进度，但不保证逐 token 流式输出。
 
-Useful variables include:
+## 输出、状态与退出码
 
-```text
-CODEX_TASK_MODEL
-CODEX_TASK_REASONING
-CODEX_TASK_PROXY
-CODEX_TASK_CODEX_HOME
-CODEX_TASK_TEXT_TIMEOUT_MS
-CODEX_TASK_IMAGE_TIMEOUT_MS
-CODEX_TASK_SDK_TIMEOUT_MS
-CODEX_TASK_RETRIES
-```
+stdout 默认只有一个 JSON 结果；`--stream` 时为 JSONL。诊断写 stderr。
+
+| 状态/退出码 | 含义 |
+| --- | --- |
+| `completed` / `0` | 完成 |
+| `needs_input` / `0` | 等待调用方补充输入，可 `resume` |
+| `failed` / `1` | 执行失败 |
+| 参数错误 / `2` | 输入或配置无效 |
+| `cancelled` / `130` | 取消或超时 |
+
+`--no-followup` 会要求 SDK worker 采用合理假设并在当前 caller turn 内完成或失败，但不能保证模型一定成功。
+
+## 模型与配置
 
-## Temporary data
+SDK 默认不覆写 model/reasoning，继续读取正常的 Codex 用户与项目配置。
 
-- Images without `--output` live under the platform temporary directory and expire after 24 hours.
-- Pending `needs_input` metadata lives under the platform state directory and expires after 7 days.
-- Managed temporary artifacts are capped at 1 GiB.
-- Explicit output paths are user data and are never removed by `codex-task gc`.
-- Official SDK sessions remain managed by Codex under `$CODEX_HOME`; CodexTask does not delete them.
+Direct 按显式参数 → Codex `config.toml` → `models_cache.json` 首选模型 → 兼容 fallback 的顺序选择模型。当前文本可使用 `gpt-5.6-sol + medium/high`；私有 Responses Lite 路由不暴露托管 `image_generation`，所以 Direct 图片会在请求前选择兼容的 classic `gpt-5.5`。这不代表 `gpt-5.6-sol` 没有视觉能力，只是这条非官方 Direct 生图协议不兼容。最终 JSON 始终返回真实的 `effectiveModel` 和 `reasoningEffort`。
 
-## Development and releases
+运行 `codex-task doctor` 可查看本机 Direct transport、OAuth、模型解析、Codex CLI/SDK 与真实数据路径，不会发送模型请求。
+
+## 开发与发布
 
 ```bash
 npm install
 npm run verify
 ```
 
-`npm run verify` runs lint, type checking, unit tests, build, package inspection, and a clean install/import smoke test. Live Direct endpoint tests are opt-in and never run in CI:
+`verify` 会执行 lint、workflow 检查、类型检查、单元测试、构建、npm 包内容检查和干净安装/import smoke test。真实 Direct endpoint 测试只允许手动执行：
 
 ```bash
 RUN_DIRECT_E2E=1 npm run test:e2e
 ```
 
-Every push to `main` triggers an automatic patch bump. A second workflow verifies the package, publishes through npm Trusted Publishing, and creates a `vX.Y.Z` tag. Repository setup is documented in [Release setup](./docs/RELEASING.md).
-
-## Acknowledgements
+每次 push 到 `main` 都会自动发布 patch 版本，详见[发布配置](./docs/RELEASING.md)。
 
-The Direct backend is derived in part from the MIT-licensed [`lawrencewzen/imgen`](https://github.com/lawrencewzen/imgen). See [third-party notices](./THIRD_PARTY_NOTICES.md).
+## 致谢与许可
 
-## License
+Direct 后端部分技术与 MIT 代码源自 [`lawrencewzen/imgen`](https://github.com/lawrencewzen/imgen)，详见[第三方声明](./THIRD_PARTY_NOTICES.md)。
 
 MIT © 2026 ye.wang