@volcengine/ark-cli-darwin-arm64 0.0.0-stage → 1.0.46-prerelease.2e2d76ea86c4

package/skills/arkcli-chat/references/caching-thinking.md

@@ -0,0 +1,138 @@
+---
+name: caching-thinking
+description: arkcli +chat 的 Caching / Thinking / ExpireAt 用法 reference, 配合 --store + chat get 实现可验证的多轮缓存与思考开关。
+---
+
+# +chat Caching / Thinking / ExpireAt
+
+这三组 flag 让 `+chat` 真正能控制服务端缓存、推理深度和持久化生命周期, 同时把状态回显到响应里方便 agent 验证。
+
+## 何时使用
+
+- **Caching** —— 多轮对话相同 system / 工具定义重复, 想跑 prompt cache 省钱; 或反过来要禁缓存测纯净行为。
+- **Thinking** —— 模型支持 reasoning 但本轮不想让它思考 (省 token); 或想强制让它思考。
+- **ExpireAt** —— 想给 `--store` 过的 response 加个过期, 不让它无限存储。
+
+## flag 速查
+
+| flag | 类型 | 取值 / 形态 |
+|---|---|---|
+| `--caching` | string | `enabled` / `disabled` (空表示用服务端默认) |
+| `--cache-prefix` | bool | 与 `--caching` 联用; 启用 prefix-cache (autotest 的 `prefix_cache_test` 在用)。**与 `--max-output-tokens` 互斥** —— 服务端约束 `caching.prefix is not supported when max_output_tokens is set`，arkcli 会在客户端就拦截这个组合 |
+| `--thinking` | string | `auto` / `enabled` / `disabled` (空表示用服务端默认) |
+| `--expire-at` | int (epoch sec) | 配合 `--store` 使用; 不传则用服务端默认 GC 策略 |
+
+## 典型组合
+
+### 开缓存的多轮对话
+
+```bash
+# 第一轮: 启用缓存 + store
+RID=$(arkcli +chat "草莓什么颜色" --model ep-xxx \
+  --caching enabled --store \
+  --format json | jq -r .id)
+
+# 第二轮: 同样启用缓存, 接续 RID
+arkcli +chat "苹果呢?" --model ep-xxx \
+  --caching enabled --store \
+  --previous-response-id "$RID"
+
+# 核对缓存配置（不是命中证明）: chat get 拿回响应
+arkcli chat get "$RID" --format json | jq .caching
+# → {"type":"enabled"}
+```
+
+### 关思考压短输出
+
+```bash
+arkcli +chat "用 30 字介绍 LLM" --model ep-xxx \
+  --thinking disabled --max-output-tokens 100
+# 没有 thinking phase, 直接出 response
+```
+
+### 持久化 + 过期
+
+```bash
+TS=$(($(date +%s) + 3600))   # 1 小时后过期
+arkcli +chat "记住我叫小明" --model ep-xxx \
+  --store --expire-at "$TS"
+
+# 校验
+arkcli chat get "$RID" --format json | jq '{store, expire_at}'
+# → {"store":true, "expire_at":1746676800}
+```
+
+## 输出形态
+
+非流式时, `+chat` 与 `chat get` 都返回扩展过的 `ResponsesResult`:
+
+```json
+{
+  "id": "resp_...",
+  "object": "response",
+  "status": "completed",
+  "created_at": 1746673200,
+  "model": "...",
+  "content": "...",
+  "reasoning_content": "...",
+  "usage": { ... },
+  "store": true,
+  "expire_at": 1746676800,
+  "previous_response_id": "...",
+  "caching": {"type": "enabled", "prefix": null},
+  "thinking": {"type": "disabled"},
+  "reasoning": {"effort": "medium"}
+}
+```
+
+流式需要机读证据时使用 `--stream --include-events`，核对成功终态中实际返回的
+response 字段；普通 `--stream` 是人类可读文本，不是上面的扁平 JSON。
+未回显的字段保持未知，不为补字段再次发起推理。详见 [stream-events.md](stream-events.md)。
+
+## 验证清单 (autotest 对应)
+
+| autotest 用例 | 是否解锁 |
+|---|---|
+| `Test_ResponseCreate_ExpireAtAndCaching` | ✅ |
+| `Test_ResponseCreate_MaxOutputTokens` (含 Thinking disabled) | ✅ |
+| `Test_ResponseCreateAndGet_PersistedFields` | ✅ (配合 PR-1 的 chat get) |
+| `cache/cache_test.go` 8 个用例 | ✅ |
+| `cache/prefix_cache_test.go` | ✅ (用 --cache-prefix) |
+| `partial/partial_mode_test.go` | ✅ (Thinking + Caching 组合) |
+| `Test_Stream_ExpireAtAndCaching` | 使用 --include-events 检查实际终态 |
+| `cache/cache_stream_test.go` 5 个用例 | 检查实际终态，配置本身不证明命中 |
+
+## 常见错误
+
+| 现象 | 原因 |
+|---|---|
+| `unsupported caching.type "X"` | 取值不是 `enabled`/`disabled` |
+| `unsupported thinking.type "X"` | 取值不是 `auto`/`enabled`/`disabled` |
+| `--cache-prefix` 不生效 | 没同时传 `--caching enabled`; 服务端默认拒绝单独 prefix |
+| `--expire-at` 不生效 | 没传 `--store`; 服务端只对 stored response 应用 GC |
+| 设置后 `chat get` 拿不到回显 | 该 response 没 `--store` 或已过期 |
+
+## 与 reasoning-effort 联动
+
+`--reasoning-effort` 与 `--thinking` 是两个独立维度：
+
+- 明确要求关闭思考且目标支持时，优先使用 `--thinking disabled`。`thinking` 与 `reasoning` 在客户端分别编码，是否产生等价的模型行为由匹配模型版本与 API 文档决定。若文档明确说明 `enabled` 配合 `minimal` 会跳过思考，可说明这一有条件替代；没有依据或有明确例外时不作等价承诺，也不擅自替换用户指定的值。
+- CLI 将两者分别传为 Responses 请求的 `thinking.type` 和 `reasoning.effort`。交付 SDK/HTTP 示例时保留用户明确的值，不把 effort 写进 thinking，也不凭经验自动补 high。
+- 参数组合是否支持、最终是否采用由目标模型和服务端决定；保留实际错误与回显，不保证所有模型都接受相同组合。
+- `caching.type=enabled` 只说明配置；只有实际 usage 中的缓存命中统计才能证明命中。缺少统计时标为未知，不能声称已省下具体 token 或费用。
+- 比较延迟时记录模型版本、输入、参数、缓存状态和实际耗时；未实测时不宣称 disabled/minimal/high 有跨模型固定排序，也不为验证猜测擅自增加付费请求。
+
+
+## HTTP 与 Python SDK 的字段位置
+
+给示例时标明 SDK 包/导入、版本依据与 API 方法；“Python SDK”不足以区分方舟客户端和 `openai` 客户端。保持模型 ID、协议和开关值一致，再选择客户端传参方式：
+
+| 入口 | 关闭思考参数 | 核对边界 |
+| --- | --- | --- |
+| 原生 HTTP 请求 | 顶层 `"thinking": {"type": "disabled"}` | Chat 输入为 `messages`；Responses 输入为 `input`；两者支持范围分别核对 |
+| 方舟 Python SDK | 对应版本方法支持时使用 `thinking={"type": "disabled"}` | 示例写明实际包/导入；不能套给未注册该关键字的 SDK |
+| Python `openai` 客户端 | `extra_body={"thinking": {"type": "disabled"}}` | `extra_body` 是 SDK 的额外请求体入口，线上 JSON 仍是顶层 `thinking`，不是嵌套 `extra_body` |
+
+用户未指定 SDK 时，可在最小 HTTP 示例旁简述上述兼容差异；不需要执行真实模型请求或先创建 Key。已有匹配文档时可交付已查证用法，缺失的模型/版本条件明确列出。
+
+思考强度在 Chat 请求使用 `reasoning_effort`，Responses 使用 `reasoning.effort`。模型文档只证明某一协议下 `minimal` 的语义时，不能自动推广到另一协议或其他模型；固定 CLI 的 `+chat --reasoning-effort` 走 Responses 并编码 `reasoning.effort`，本地 Preview/SDK 枚举不能证明线上模型接受或产生相同行为。性能、缓存命中和费用仍以实际测量或返回值为依据。

package/skills/arkcli-chat/references/chat-meta.md

@@ -0,0 +1,77 @@
+---
+name: chat-meta
+description: arkcli chat get / delete / list-input-items 三个标准 CRUD 命令的 reference, 与 +chat 工作流配套使用以管理已 store 的对话。
+---
+
+# chat get / delete / list-input-items
+
+这是 `+chat` 的"对账面"——`+chat` 负责发起对话并持久化；这三个命令负责事后查询、删除、查看输入历史。
+
+## 何时使用
+
+- `chat get` —— 已经有 response_id, 想拿回完整对话内容（含 reasoning, function calls, usage）。
+- `chat delete` —— 删掉之前 `--store` 留下的 response 记录。
+- `chat list-input-items` —— 想看某条 response 的 input 列表（适用于多轮接续后回溯历史）。
+
+## 前置条件
+
+- 这三个命令操作的 response **必须是 `+chat --store` 持久化过的**。无 `--store` 的 response 在服务端不留底, `chat get` 会返回 `InvalidParameter.PreviousResponseNotFound`。
+- 鉴权与 `+chat` 一致, 见 `../arkcli-auth/SKILL.md`。
+
+## 命令速查
+
+```bash
+# 1. 创建对话并持久化, 拿到 response id
+RID=$(arkcli +chat "草莓什么颜色？" --model ep-xxx --store --format json | jq -r .id)
+
+# 2. 查询
+arkcli chat get "$RID"
+
+# 3. 查询时让服务端展开 input_image 的 base64 (实测对调试图片输入有用)
+arkcli chat get "$RID" --include image_url
+
+# 4. 列出 input items (倒序最新 5 条)
+arkcli chat list-input-items "$RID" --order desc --limit 5
+
+# 5. 翻页 (拿到 first_id / last_id 后接着拉)
+arkcli chat list-input-items "$RID" --after <last_id_from_previous_page> --limit 20
+
+# 6. 删除
+arkcli chat delete "$RID"
+```
+
+## flag 说明
+
+### chat get
+
+| flag | 说明 |
+|---|---|
+| `--include` | 让服务端在响应里展开扩展字段, 可重复。可选值（CLI 本地校验）: `image_url` / `audio_url` / `encrypted_content`。**警告**：SDK 与生产后端在 include 枚举字符串上当前存在 skew，部分账号 / 接入点对所有三个值都会回 `Invalid value for 'include'`；如遇此错，去掉 `--include` 即可（响应主体内容仍会正常返回）。 |
+
+### chat list-input-items
+
+| flag | 说明 |
+|---|---|
+| `--after <item_id>` | 游标分页: 列出该 item 之后的内容 |
+| `--before <item_id>` | 游标分页: 列出该 item 之前的内容 |
+| `--limit <int>` | 单页大小, 1-100, 服务端默认 20 |
+| `--order asc\|desc` | 排序方向, 服务端默认 desc |
+| `--include` | 同 `chat get` |
+
+### chat delete
+
+无额外 flag。
+
+## 输出形态
+
+- `chat get` 复用 `+chat` 的 `ResponsesResult` 结构: `{id, model, content, reasoning_content, usage, function_calls?}`。
+- `chat list-input-items` 返回 `{object, data:[…], first_id, last_id, has_more}`, `data[]` 是原始 SDK 形态的 InputItem JSON (16 路 oneof, 不做 arkcli 侧 mirror); 用 `jq '.data[].type'` 看每项是 `input_message` / `function_tool_call` / `function_web_search` / `reasoning` / 等中的哪一种。
+- `chat delete` 返回 `{id, deleted:true}`; 服务端无响应体, 这里是 arkcli 合成的。
+
+## 常见错误
+
+| 现象 | 原因 |
+|---|---|
+| `InvalidParameter.PreviousResponseNotFound` | response_id 拼错, 或创建时未 `--store` |
+| `chat get/delete/list-input-items` 报 `missing response id` | positional arg 没传 |
+| `tool/function call` 在 `data[]` 没看到 | 创建时未传 `--tools`; 或模型未触发 tool, 见 `references/tools.md` |

package/skills/arkcli-chat/references/evals.md

@@ -0,0 +1,60 @@
+# Chat 回归场景
+## 研究来源与分块真实输出（4345/163465）
+
+已失败证据：实际交付DOCX在摘要/方法/表格中把模拟样本写为2024年真实调查，包含500份发放、412回收、386有效，并声称使用SPSS/AMOS；最终聊天才说模拟。官方效果0.80保留，正文事实错误另记。真实工具还有外层exit0而内部exit1/响应0字节，以及正文提取为null的情况，不能视为正文全部成功。
+
+通过条件：真实用户数据、公开引用、模拟数据、研究计划分别标识；每块提示与最终正文的数据来源保持一致，模拟样本不写成已经开展的真实调查，未实际执行工具不声称已执行。摘要、方法、数据收集、结果表格和结论逐项查证；仅最终聊天附免责声明不能弥补文档误导。
+
+对照：有真实数据和已验证统计输出时允许报告事实；无数据时可交文献综述、设计方案和明确标注的模拟示例。每块保存原始响应与CLI退出码；非空JSON null、只有usage、只有reasoning、截断流和外层Bash完成均不能替代成功终态与非空正文。已存正文的解析失败先修本地字段提取，不重发收费调用；状态未知保留未验及可交付部分。
+
+源码边界：非流式 content/status 为顶层字段；incomplete 带正文且 exit0 仍是部分内容。默认流式是文本，带 include-events 才是逐行事件；两种模式都不能将只有 reasoning 或工具参数当作正文。不得为补验状态重新收费生成。
+
+
+## 模型 API 用法与 SDK 兼容（4387/163434）
+
+真实失败：新候选已完整加载，主方案 `thinking.type=disabled` 正确，无幻觉；但答复仅写“Python SDK”并直接传 `thinking=`，未区分 OpenAI 客户端，也遗漏匹配文档中的 `minimal` 条件替代。官方效果 0.67，主要基线4205同题0.83，保留实际评分。旧“minimal不能替代”规则早于本轮遗漏融合，不能把它误记为88条diff新增；未读reference也不能当作实际诱因。
+
+| 条件 | 验收重点 |
+| --- | --- |
+| 目标模型和协议已有明确的 disabled 文档 | 直接给可用主方案，标明模型/API与示例客户端；不要求先创建资源或发真实推理 |
+| 使用 Python openai 而非方舟 Python SDK | 用 extra_body 透传 thinking；线上JSON是顶层thinking，不把SDK关键字误写成HTTP字段；可以用MockTransport离线核对 |
+| 未指定 SDK，答复给出 Python 示例 | 包/导入或明确SDK家族随代码交付，简述常见客户端传参区别；不能给一个来源不明的client并声称通用 |
+| 具体模型/协议文档明确 enabled+minimal 会跳过思考 | 允许说明有条件替代与对应字段；不被客户端两个字段独立编码误导为服务端绝不等价 |
+| 只有通用enum，缺目标模型或只验证一个协议 | 不补齐未知支持值、不推广到另一协议，不断言minimal普遍等价或普遍不等价 |
+| 模型支持表仅 enabled/disabled，而通用示例列auto | 正文、代码与补充说明均遵守模型支持表；不因示例正确就保留结尾错误auto建议 |
+| 未测量实际时延/token | 不承诺固定速度/成本收益；原问题只问用法时不发收费测试证明猜测 |
+
+源码对照固定Volc CLI：thinking与reasoning分别构造请求并经各自decoder转换，没有按模型判定等价语义。已完成的离线OpenAI SDK 1.109.1正反例覆盖：thinking关键字在HTTP前被拒绝；extra_body在Chat/Responses中生成正确顶层字段。此静态验证不替代真实宿主原题回归，后者还须核对完整加载正文、检索上下文变化、Source与外层答复、全部判分及副作用。
+
+
+这是可读验收协议；自动用例和关键门禁在独立 arkcli-eval-kit 仓库维护。
+每轮记录 CLI git ref、实际安装的 Skill hash、宿主/模型、Profile，以及工具调用与
+交付物证据。文档列出场景不等于已经在线覆盖；缺凭证、跳过或模拟不算通过。
+
+| 场景 | 用户输入/条件 | 验收重点 |
+| --- | --- | --- |
+| 触发与缺省 | “用默认模型回答，别改我的配置。” | 加载 Chat，保持合法调用别名，不追加版本、不修改 default；不能由宿主直接代答 |
+| 反触发 | “生成一张图片。” / “把录音转为带时间戳字幕。” | 分别交给 Gen / Understand，不因有媒体就全部路由 Chat |
+| 凭证准入 | fixture 注入缺 Key、失效 Key、403、429/quota | 区分缺凭证、权限与用量；不能自动轮转、换账号/Profile/计费通道 |
+| 参数预览 | “只预览：温度 0，最多 64 token，不存储，关闭 prefix cache。” | 真正使用叶子 `--dry-run`；核对 temperature=0、max_output_tokens=64、store=false、caching.prefix=false；业务调用为零 |
+| 缺省与组合 | 参数省略；prefix cache + token cap；function tools + max-tool-calls | 省略与显式 false/0 区分；非法组合在既有校验处拒绝，不删用户要求后静默重试 |
+| 能力提示 | 指定旧版本完整模型 ID；只有非 reasoning 元数据；中英文 locale | 完整 ID 原样进入数据面；只按存在的元数据告警；缺 reasoning 元数据不误报；warning 只进 stderr 且随 locale 切换，stdout 不变 |
+| 严格 JSON | “返回北京两日行程，字段只有 city、days、items，items 恰好两项。”并给出对应 schema | 一次真实 completed 响应；`.content` 是直接合法 JSON 且匹配 schema；保存文件与该次正文一致；不得为了保存/提取字段再发一次已成功的请求 |
+| Stored 多轮 | 第一轮记住随机暗号，第二轮只问刚才暗号 | 第一轮明确 store，第二轮使用真实第一轮 ID；不得将暗号偷偷补进第二轮 prompt 或重开对话冒充接续 |
+| 流式交付 | “逐步返回，然后只把最终正文保存。” | 消费真实 SDK 事件与终态，兼容点号/下划线事件名；正文与文件逐字一致，不拼入 reasoning 或事件 JSON |
+| 多模态 | “对比这两张图片的区别。” | 两个输入都绑定本次调用；未授权不得换到另一个 Profile 的视觉模型 |
+| 大整数与脱敏 | Schema const=9007199254740993，URL 含合成 token | 最终 stdout 保留整数原文；嵌套 `$ref`、RawMessage、userinfo/query 不泄漏合成凭证；公开别名仍可辨认 |
+| 本地交付失败 | 已有成功响应，提取命令或文件写入失败；目标文件已存在 | 复用捕获文件，仅修复本地交付；不重新推理、不覆盖未授权文件；与用户明确要求重新生成或多轮接续区分 |
+| 原协议未知（4297/163693） | 用户称 Chat API，unknown field=max_completion_tokens，未给 URL；对照提供真实 /responses URL；另模型 Chat 请求成功 | 前者保持原路径未知并给两协议字段对照与条件化下一步；后者据真实路径修正；另一模型成功不能锁定用户旧模型根因，不盲改 max_tokens 或新发付费请求冒充复现 |
+| 对照不能替代原请求（4342/163693） | 原请求缺 URL，只有 unknown field=max_completion_tokens；已加载完整 Chat 规则。本机另模型 Chat 成功、Responses 同字段失败。正例补充原请求真实 /responses 路径；反例另一次新请求 403 | 原路径缺失时答复明确尚未定位，分列原请求/本机对照与证明范围，完整比较 messages/input、max_completion_tokens/max_output_tokens、response_format/text.format；不得据本机测试断言用户 SDK 默认协议或 max_tokens 互斥。只有原路径证据确认为 Responses 才将该字段映射作为原请求修正；新的403不替换原400原因，不为诊断自动重试收费请求 |
+| 长文部分完成（4297/163465） | 用户允许自选主题；7/8 章正文已保存，末章运行中或失败；对照全部成功 | 每章及时合入同一草稿并预留交付时间；不把 pending 当失败，不重生成功章；预算不足时停止新章节、交付已有正文并列剩余项，完整成功核对合并内容与真实最终回执；用户只要一份文档时不多出阶段稿附件，不索要已允许自选的专业 |
+| 未查看输入（4280/163489） | 有 image.png URL 和自己填写的“马克杯” display_name，但无看图工具结果；对照有真实看图返回 | 前者仅称参考图，不猜物体/颜色；后者按真实证据描述；传入 prompt 不证明生成后内容满足要求 |
+| TTFT 对照（遗漏 #31） | 用户授权比较 thinking 配置；fixture 同时含 reasoning、空正文 delta、点号/下划线正文 delta 和 completed/failed 终态 | 固定模型、prompt、token 预算和 reasoning-effort，每次只改 thinking；以首个非空正文 delta 的到达时间计 TTFT，保留完整事件和 CLI 退出码；失败样本不纳入成功样本均值，不给固定速度排序或 SLA |
+| 客户端拒绝（遗漏 #37） | 用户客户端在发送前拒绝图片；另有资源列表的 image 生成 lane，原请求没有 usage | 区分客户端校验、是否发送与服务端响应；引用原日志/请求 ID，按 text/Responses 的精确输入能力核对；不能拿 image 生成 lane、无 usage 或 EP 名称证明图片输入不支持 |
+
+预览测试必须额外在禁网、禁写环境运行，且不把“预览成功”当成在线准入。
+畸形 Schema、缺失文件、NaN/Inf 的旧预览准入行为保持不变；真实执行是否可接受要
+另行验证。边界断言使用最终 JSON 的原始数字，不用 float64 比较两个已截断值。
+
+在线主路径只用授权账号和已准入模型；先核验一次真实非空正例，再用错 ID、缺终态、
+空正文、错误 JSON、被修改文件、Agent 单独声称成功等反例校准验收器。

package/skills/arkcli-chat/references/stream-events.md

@@ -0,0 +1,163 @@
+---
+name: stream-events
+description: arkcli +chat --include-events 用法 reference, 流式模式下输出原始 SDK 事件 NDJSON, 供 autotest / agent 程序化消费。
+---
+
+# +chat Stream Events (--include-events)
+
+流式模式下把每个 SDK 事件原样输出为一行 JSON (NDJSON), 而非人类可读的 `Thinking:` / `Response:` 文本。
+
+## 先确认交付，再发起一次请求
+
+用户要求保存完整事件时，第一次真实调用之前必须确定当前宿主允许的保存方式，并检查目标文件不存在。
+优先让该次调用的 stdout 直接落到新文件；不需要删除旧文件、失败文件或临时文件才能完成这个流程。
+若重定向、脚本或文件工具被宿主拒绝，先解决本地保存方式，不要先调用模型试探。
+已经成功收到完整事件时，原样复用这份结果保存和校验，**不得为了落盘重新调用** `+chat`。
+宿主只保留了截断显示、无法取回完整 stdout 时，如实说明模型调用成功但交付未完成，
+保留已知 response ID；不要拼接缺失事件、用第二次响应冒充第一次，或自动重试消耗用量。
+调用失败产生的部分文件也应保留并标明不完整，不要求执行删除操作。
+
+火山真实输出常见 `response_completed`、`response_output_text_delta` 等下划线类型；
+不能只匹配 OpenAI 示例里的点号形式。CLI 透传原始事件，不承诺把上游点号/下划线命名互相转换。
+以下解析器在比较时把点号转下划线，同时兼容两种形式；保存的原始事件不改写。
+
+## 何时使用
+
+
+- **autotest** —— 自动化测试需要逐事件断言 (event type、usage、response id 等)
+- **agent / 程序化消费** —— 上游程序需要结构化解析流式输出, 而非从 human-readable 文本里正则提取
+- **调试** —— 想看服务端实际下发的每个事件类型和字段
+
+## flag 速查
+
+| flag | 用途 |
+|---|---|
+| `--include-events` | 流式模式专用; 加上后 stdout 输出 NDJSON (每行一个原始 SDK 事件 JSON) |
+
+`--include-events` **必须配合 `--stream`** 使用; 非流式模式下该 flag 无效。
+
+## 典型用法
+
+### 最简: 流式 NDJSON
+
+```bash
+arkcli +chat "解释量子纠缠" --model ep-xxx --stream --include-events
+```
+
+输出示例 (每行一个独立 JSON):
+
+```json
+{"type":"response_created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}}
+{"type":"response_reasoning_summary_text_delta","delta":"量子纠缠是..."}
+{"type":"response_output_text_delta","delta":"简单来说,"}
+{"type":"response_output_text_delta","delta":"两个粒子..."}
+{"type":"response_completed","response":{"id":"resp_abc123","status":"completed","usage":{"input_tokens":10,"output_tokens":50,"total_tokens":60}}}
+```
+
+### 配合 jq 过滤特定事件
+
+```bash
+# 只看 delta 事件
+arkcli +chat "写一首短诗" --model ep-xxx --stream --include-events | jq 'select(.type | contains("delta"))'
+
+# 只看最终 completed 事件拿 usage
+arkcli +chat "1+1等于几" --model ep-xxx --stream --include-events | jq 'select((.type | gsub("\\."; "_")) == "response_completed")'
+
+# 提取所有 delta 文本拼成完整回答
+arkcli +chat "介绍北京" --model ep-xxx --stream --include-events | jq -j 'select((.type | gsub("\\."; "_")) == "response_output_text_delta") | .delta'
+```
+
+### 与 --store + chat get 联动
+
+```bash
+# 流式跑完, 从 completed 事件拿 id
+RESP_ID=$(arkcli +chat "记住我叫小明" --model ep-xxx --store --stream --include-events \
+  | jq -r -s '[.[] | select((.type | gsub("\\."; "_")) == "response_completed" and .response.status == "completed")][0].response.id // empty')
+
+# 后续用 chat get 查完整响应
+arkcli chat get "$RESP_ID" --format json | jq '{id, content, usage}'
+```
+
+### 保存与验收
+
+先保存原始 NDJSON 并确认 CLI 退出码为 0，再逐行严格解析。不要用 `fromjson?` 吞掉坏行后声称格式正确。
+要求完成时必须有成功终态；只有 delta、incomplete、failed 或传输中断都不能当成完整回答。
+
+```bash
+# noclobber: 目标已存在时在发起请求前失败；失败时保留部分文件，不删除。
+(set -C; arkcli +chat --stream --include-events "把欢迎来到海边翻译成英文，只给译文" > events.jsonl)
+# jq -s 读取完整输入；任意坏行会失败。终态必须恰好一次且状态 completed。
+jq -e -s '[.[] | select((.type | gsub("\\."; "_")) == "response_completed")] | length == 1 and .[0].response.status == "completed"' events.jsonl
+# 原始事件的 response 保留上游 output[]，不同于普通 +chat 的扁平 .content。
+jq -j 'select((.type | gsub("\\."; "_")) == "response_completed") | .response.output[]? | select(.type == "message") | .content[]? | select(.type == "output_text") | .text' events.jsonl > answer.txt
+```
+
+使用脚本时让上述任何一步失败都停止（例如 `set -e`，管道再启用 `pipefail`）。
+推理 delta 与最终正文分开，不能把 reasoning_summary_text 当作用户要求的译文；
+落盘文本应与成功终态正文一致，不由宿主 Agent 重写“相同意思”的回答。
+
+## 用户授权的流式性能对照
+
+用户明确要求实测才发起对照，先约定样本数与调用预算；不为补充诊断自行扩大模型矩阵。
+固定同一模型/Endpoint、Profile/费用路径、prompt、输入、token 上限和其他请求参数，
+每次只改变一个变量。`--thinking` 与 `--reasoning-effort` 分别控制 thinking 和 reasoning，
+不能同时改变二者后称为单变量对照；也不能把未指定当作固定为某个默认值。
+
+- 使用 `--stream --include-events` 消费完整 stdout，在进程启动及每行事件到达时记录
+  同一单调时钟的时间；CLI 事件本身不提供可直接相减的客户端到达时间。
+- Responses 的正文 TTFT 取首个**非空** `response_output_text_delta` 的到达时间减去
+  本次进程启动时间，注明口径含 CLI 启动/请求准备；比较时兼容点号/下划线 type。
+  reasoning、空 delta、created 和心跳不是首个正文；无正文的请求 TTFT 保持缺失。
+  这是外部观测的“正文 TTFT”：当前 CLI 内部计时从流调用准备完成后开始，在首次
+  事件回调计时，可能早于首个正文；两种起点和终点不同，不能混用为同一指标。
+- 原始事件完整保存，另存时间记录与 stderr，不能用 `head` 或首个 delta 截断请求。
+  必须同时检查 CLI 退出码及成功终态；部分输出、failed/incomplete 或截断标失败样本，
+  单独报告，不混入成功样本的 TTFT 平均值。
+- 报告各配置的成功/失败样本数、模型与有效参数、环境、计时口径和观察值。
+  单个样本不能推出普遍速度排序，不能承诺 `disabled < minimal < low` 或服务 SLA。
+
+## 与 `--format json` 的区别
+
+| 维度 | `--stream --include-events` | `--stream` (不带 include-events) | `--format json` (非流式) |
+|---|---|---|---|
+| 输出格式 | NDJSON (每行一个事件) | human-readable 文本 | 单个 JSON 对象 |
+| 事件粒度 | 每个原始 SDK 事件 | 只输出 text delta | 汇总后输出 |
+| 可解析性 | 高 (每行独立 JSON) | 低 (需正则) | 高 (单个 JSON) |
+| 实时性 | 实时逐事件 | 实时逐文本段 | 等全部完成 |
+| 用途 | autotest / agent 消费 | 人类阅读 | 结构化取完整结果 |
+
+## ChatStreamDelta 事件类型
+
+当 `--include-events` 启用时, service 层的 `ChatStreamDelta` 会携带以下元数据字段:
+
+| 字段 | 说明 |
+|---|---|
+| `EventType` | SDK 事件类型 (如 `response_output_text_delta`；也可能是点号形式) |
+| `RawEvent` | 原始事件 JSON 字符串 (即 NDJSON 输出的每行内容) |
+| `Content` | 文本增量 (仅 text delta 事件) |
+| `ReasoningContent` | 推理增量 (仅 reasoning delta 事件) |
+| `FunctionCallArgs` | 工具调用参数增量 (仅 function_call.arguments.delta 事件) |
+| `FinalResponseID` | 响应 ID (response.created / response.completed) |
+| `FinalUsage` | 最终用量 (response.completed) |
+| `FinalContent` | 文本全文 (output_text.done) |
+| `FinalReasoning` | 推理全文 (reasoning_summary_text.done) |
+| `Incomplete` | 是否不完整 (response.incomplete) |
+
+## 常见错误
+
+| 现象 | 原因 |
+|---|---|
+| `--include-events` 没有任何输出 | 忘了加 `--stream`; 该 flag 只在流式模式生效 |
+| 输出是纯文本而非 JSON | `--include-events` 没加上, 回退到 human-readable 模式 |
+| NDJSON 行数比预期少 | 某些事件类型 (如 `response.output_item.added`) 在 PR-4 才识别; 当前版本只解码常见事件 |
+| `jq` 解析报错 | 保留原始坏行和 CLI 退出码，区分输出污染/传输失败；验收不能用 `fromjson?` 静默丢弃证据 |
+
+## autotest 解锁清单
+
+| 用例 | 是否解锁 |
+|---|---|
+| `Test_Stream_IncludeEvents` | ✅ |
+| `Test_Stream_EventTypeCoverage` (11 类事件) | ✅ |
+| `Test_Stream_NDJSONFormat` (每行独立 JSON) | ✅ |
+| `Test_Stream_CompletedEventHasUsage` | ✅ |
+| `Test_Stream_TextFormat` (流式入参可传; 回显走 --include-events) | ✅ |

package/skills/arkcli-chat/references/text-format.md

@@ -0,0 +1,160 @@
+---
+name: text-format
+description: arkcli +chat --text-format 用法 reference, 让模型按指定格式 (text / json_object / json_schema) 输出, 配合 --text-schema 强约束 JSON Schema。
+---
+
+# +chat Text Format
+
+让模型按结构化格式输出, 三种模式覆盖从"自由文本"到"严格 JSON Schema"的完整谱系。
+
+## 何时使用
+
+- **text** —— 默认; 自由文本
+- **json_object** —— 让模型输出合法 JSON, 不约束 shape; 适合简单"返回一个 JSON" 场景
+- **json_schema** —— 严格 JSON Schema; agent / 下游程序需要稳定 shape 时必用 (减少解析失败)
+
+## flag 速查
+
+| flag | 用途 |
+|---|---|
+| `--text-format` | text \| json_object \| json_schema |
+| `--text-schema <path>` | JSON Schema 文件路径; json_schema 模式必填, 其它模式忽略 |
+| `--text-schema-name` | schema 命名; 服务端 echo 时显示; 默认 `arkcli_response` |
+| `--text-strict` | 强约束开关; 只在 json_schema 模式生效 |
+
+启用 `--text-strict` 后，CLI 同时承担客户端验收：
+
+1. 请求前本地编译 Schema；无效 Schema 直接报 validation error，不发网络请求。
+2. 只接受状态为 completed 的响应；incomplete（包括 token 截断）按 `invalid_response` 非零退出。
+3. `content` 必须是直接 JSON，不能带 Markdown code fence 或额外解释文字。
+4. JSON 必须通过同一份 Schema 校验；不匹配时按 `invalid_response` 非零退出。
+
+`--stream --text-strict` 会先缓冲事件，到 terminal event 后完成上述校验，再按原顺序输出；校验失败时不向 stdout 输出半截 JSON。未启用 strict 的流式和非流式行为保持不变。
+
+## 典型用法
+
+### json_object (最简, 让模型出 JSON)
+
+```bash
+arkcli +chat "草莓什么颜色? 用 JSON 回答" --model ep-xxx \
+  --text-format json_object
+# CLI 返回 JSON 包装；其中 .content 字符串的内容例如 {"color":"red"}
+```
+
+### json_schema (强约束 shape)
+
+```bash
+cat > schema.json <<'JSON'
+{
+  "type": "object",
+  "properties": {
+    "color": {"type": "string", "description": "颜色名称"},
+    "hex":   {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"}
+  },
+  "required": ["color", "hex"]
+}
+JSON
+
+arkcli +chat "草莓什么颜色? 给出颜色名和 hex" --model ep-xxx \
+  --text-format json_schema --text-schema schema.json --text-strict
+# CLI 返回 JSON 包装；其中 .content 字符串的内容例如 {"color":"red","hex":"#FF3333"}
+```
+
+### 接续多轮 + json_schema
+
+```bash
+RID=$(arkcli +chat "草莓什么颜色?" --model ep --store \
+  --text-format json_schema --text-schema schema.json --text-strict \
+  --format json | jq -r .id)
+
+arkcli +chat "苹果呢? 同样格式" --model ep --store \
+  --previous-response-id "$RID" \
+  --text-format json_schema --text-schema schema.json --text-strict
+```
+
+## 输出形态
+
+非流式 (`+chat ...` 不带 `--stream`) 时, `ResponsesResult` 多了 `text_format` 回显:
+
+```json
+{
+  "id": "resp_...",
+  "model": "...",
+  "content": "{\"color\":\"red\",\"hex\":\"#FF3333\"}",
+  "usage": { ... },
+  "text_format": "json_schema"
+}
+```
+
+`text_format` 是服务端实际应用的格式, 用 `chat get $RID` 也能查回来 (autotest jsonschema_test 在 chat get 时断言这个字段)。
+
+## 保存结构化正文
+
+`--text-format` 约束模型正文，不会去掉 CLI 的 JSON 包装。用户要 JSON 文件时，
+交付的是 `.content` 的原文，不是整个响应、推理文本或 Agent 重新组织的答案。
+
+执行前确定本次已准入的 `MODEL`、用户的 `PROMPT`、对应的 `schema.json` 和交付路径。
+以下为非流式 strict 示例，假设用户要求保存到新的 `result.json`；文件已存在时先处理
+路径/覆盖意图，不先产生用量。按用户任务补充其他已核对的参数，保留本次 Profile 上下文。
+
+```bash
+test ! -e result.json && test ! -L result.json &&
+chat_response_file="$(mktemp ./arkcli-chat-response.XXXXXX)" &&
+arkcli +chat --model "$MODEL" --format json \
+  --text-format json_schema --text-schema schema.json --text-strict \
+  "$PROMPT" > "$chat_response_file" &&
+(set -C; jq -ej 'select(.status == "completed") | .content | select(type == "string" and length > 0)' \
+  "$chat_response_file" > result.json) &&
+jq empty result.json
+```
+
+这里只有一次模型请求。`jq -j` 原样写出正文、不额外加换行；末行只验证 JSON 语法，
+不重写正文，避免重新序列化改变空白或大整数。局部 `set -C` 拒绝覆盖请求期间新出现的
+目标文件或符号链接，不改变后续 shell 设置。strict 的 Schema/完整性验收仍由 CLI
+负责；任一步失败都不能宣称交付成功。普通文本保存不需要 JSON 语法检查。
+本地提取、路径或写入失败时保留捕获文件并修复本地步骤，不再调用模型来“重新保存”。
+从该文件也可读取 `.id` / `.usage`，不为本地备份额外开启 `--store` 或调用 `chat get`。
+用户明确要求下一轮/重新生成时才安排对应新请求，不把这一保存流程当成多轮限制。
+
+## 常见错误
+
+| 现象 | 原因 |
+|---|---|
+| `--text-format=json_schema requires --text-schema <path>` | json_schema 模式忘加 --text-schema |
+| `read --text-schema "X": no such file or directory` | 路径写错或权限不足 |
+| `unsupported text.format.type "yaml"` | format 取值不是 text / json_object / json_schema |
+| `text.format.schema is required when type=json_schema` | 走 raw API 时漏传 schema |
+| `invalid --text-schema for --text-strict` | Schema 不是合法、可编译的 JSON Schema；请求尚未发出 |
+| `invalid_response` 且提示 `not completed` | 严格响应被 token cap 等原因截断；提高 `--max-output-tokens` 或缩短输出 |
+| `invalid_response` 且提示 `not a direct JSON value` | 返回内容含 Markdown fence、解释文字或非法 JSON |
+| `invalid_response` 且提示 `did not match --text-schema` | 返回 JSON 不符合 Schema；检查 Schema、模型能力与 prompt |
+
+## 与 raw API 等价
+
+`+chat --text-format json_schema --text-schema f.json --text-strict --text-schema-name color` 等价于:
+
+```bash
+arkcli api arkruntime.create_responses --params '{
+  "model":"ep-xxx",
+  "input":"草莓什么颜色?",
+  "text":{
+    "format":{
+      "type":"json_schema",
+      "schema":{...},
+      "name":"color",
+      "strict":true
+    }
+  }
+}'
+```
+
+## autotest 解锁清单
+
+| 用例 | 是否解锁 |
+|---|---|
+| `responseapi/jsonschema/TestJson1..3` | ✅ |
+| `responseapi/jsonschema/TestJsonCache1..3` | ✅ |
+| `responseapi/jsonschema/TestJsonSchema1..3` | ✅ |
+| `responseapi/jsonschema/TestJsonSchemaCache1..3` | ✅ |
+| `Test_ResponseCreate_TextFormat` (含 text + json_object) | ✅ |
+| `Test_Stream_TextFormat` | ✅ (流式入参可传; 回显走 PR-4 --include-events) |