feat(tools): IK8MWO #9 Zod v4 运行时 Schema 校验 + 自修重试上限 2 · Pull Request !12 · andershsueh/alice-cli

## 背景

issue IK8MWO #9 — alice-cli 工具系统当前走手写 JSONSchema + ajv 校验,对 LLM tool_call
的参数错误只能返回"参数验证失败: <ajv errorsText>"的扁平文本,LLM 看不到具体字段路径,
自修循环里经常瞎猜。本 PR 引入 zod v4 作为高频工具的 schema 定义层,新增字段路径级
错误回灌 + 自修重试上限 2。

## 真实增量(纠正 issue 标题的误导)

仓库已有 ajv 校验路径(`src/tools/registry.ts:89`、`src/tools/executor.ts:81`),**不是从
零建立校验**。本 PR 的增量是:

1. **Zod v4 作为 schema 定义层**(`src/tools/builtin/{readFile,writeFile,editFile,
   searchFiles,executeCommand}.ts`)— 替代高频工具的手写 JSONSchema
2. **Zod / JSONSchema 双形态 adapter**(`src/tools/zodAdapter.ts`)—  按 tool 是否
   有 `zodSchema` 路由。低风险工具继续走 ajv
3. **字段路径级错误回灌**(`src/runtime/tools/toolResultFormatter.ts::formatError`)
   — `edits.0.start` 这种嵌套路径直接给 LLM 看
4. **自修重试上限 2 次**(`src/core/llm.ts::ToolValidationRetryTracker`)— 同一工具
   连续 3 次失败即抛错给用户

## 改动文件

### 新增

- `src/tools/zodAdapter.ts` — 双形态校验入口(`parseZodSchema` / `parseJsonSchema`),
  共享 `ajvInstance`,registry.validateParams 路由(不再运行时 sniff)
- `src/tools/schemaFromZod.ts` — `zodToJsonSchema` (WeakMap 缓存) + `toPublicSchema`
  统一对外 schema 入口,toOpenAIFunctions() 走这里
- `src/tools/zodPrimitives.ts` — `requiredNonEmptyString` / `intOneBased` /
  `intNonNegative` / `encodingEnum` / `editFileEncodingEnum`,5 个 builtin 共享
- `test-case/test-issue-009.ts` — 96 断言

### 修改

- `src/tools/registry.ts` — 删除本地 Ajv 与 `ValidateParamsResult`,统一走 `ValidationResult`;
  register 时无论 zod/JSONSchema 都校验 toPublicSchema(避免 zod 工具的 hand-written
  parameters 块带 typo 时静默上线)
- `src/tools/executor.ts` — 静态 import formatError(替代 dynamic import),校验失败
  时调用 formatError 渲染字段路径
- `src/core/llm.ts` — 抽出 `ToolValidationRetryTracker`,chatWithTools 与
  chatStreamWithTools 复用同一段策略;`toOpenAIFunctions()` 提到 while 外
- `src/runtime/tools/toolResultFormatter.ts` — 新增 `formatError`,输入
  `ValidationIssue[]` + engine,渲染为字段路径列表
- `src/runtime/tools/toolRegistry.ts` — `validateParams` 签名升级为 `ValidationResult`,
  透传 `issues` / `engine`
- `src/types/tool.ts` — `AliceTool` 新增可选 `zodSchema` 字段,`ToolParameterSchema`
  调整为 zod v4 JSONSchema 兼容形态
- `src/tools/builtin/{readFile,writeFile,editFile,searchFiles,executeCommand}.ts`
  — 5 个高频工具迁移到 zod,经 `zodToJsonSchema` 生成对外 schema
- `src/services/{FileCommandLoader,markdown-command-parser}.ts` — zod v4 兼容
  (`required_error` + `invalid_type_error` 合并为单一 `error` 字段)
- `package.json` + `bun.lock` — zod `^3.23.8` → `^4`,实际 `zod@4.4.3`
- `test-case/test-list.md` — 登记 `test-issue-009.ts`

## zod v4 升级兼容

7 处既有 `import { z } from "zod"` 全部走 v3 默认入口(zod v4 包仍提供 v3 兼容),
无需改动。`FileCommandLoader.ts` / `markdown-command-parser.ts` 把
`required_error` + `invalid_type_error` 合并为 v4 单一 `error` 字段。新代码
全部用 `import { z } from "zod/v4"` 拿到 v4 API(`z.toJSONSchema`、
discriminated union `error` callback 等)。

## 校验设计

- **schema 来源**:工具定义层用 `zodSchema`(zod v4),对外暴露的
  `OpenAIFunction.parameters` 走 `toPublicSchema` 经 `zodToJSONSchema` 生成
  JSONSchema(WeakMap 缓存)
- **严格模式**:不再做运行时 duck-typing sniff,`registry.validateParams` 直接
  根据 `tool.zodSchema` 路由 zod / ajv;register 时校验 `toPublicSchema(tool)`
  避免 `parameters` 块与 `zodSchema` 双源飘移(剥离 zod v4 加的 `$schema`
  meta 字段后 ajv 接收)

## 风险点

- zod v4 的 `z.toJSONSchema` 输出 draft-2020-12,ajv 默认 draft-07;register 时
  剥离 `$schema` 字段。运行时 `parseJsonSchema` 主要处理 hand-written JSONSchema
  (无 `$schema`),暂未触动
- `ToolParameterSchema` 类型放宽为 zod v4 JSONSchema 兼容形态(`type?: string`,
  `enum?: unknown[]`),可能影响未来 UI 渲染;下游使用方请重新核对
- `MAX_TOOL_PARAM_RETRIES = 2` 仍为硬编码(未走 configManager);若要让用户
  调整,后续 PR 加 `getMaxToolParamRetries()` 即可

## 验证

| 脚本 | 断言数 | 结果 |
|------|--------|------|
| `test-issue-001.ts` | 27 | PASS |
| `test-issue-002.ts` | 36 | PASS |
| `test-issue-003.ts` | 34 | PASS |
| `test-issue-004.ts` | 25 | PASS |
| `test-issue-005.ts` |  9 | PASS |
| `test-issue-019.ts` | 37 | PASS |
| `test-issue-009.ts` | 96 | PASS |
| **合计** | **264** | **全绿** |

- `bun build.ts` 成功(`office=on / sandbox_workspace=off / acp_integration=off / non_interactive=off`)
- 重复实现 / 共享 Ajv / dynamic import / 死代码 已由 simplify 四 agent 合并清理

## 注意

- 本 PR 升级 `bun.lock` 的 zod 字段(`zod@3.25.76` → `zod@4.4.3`)。
  其余依赖未动。
- 与 main 合并时若 `bun.lock` 出现冲突,优先保 `zod@4.4.3` —— 其它 lock 是
  `bun add zod@^4` 自动生成的,语义等价。
- 不动 `node_modules` / `dist` / `wiki` / `raw` / `outputs` / `memory`。

Generated with [Claude Code](https://claude.com/claude-code)

类型	指派人员	状态
审查	andershsueh	进行中 (0/1人)
测试	andershsueh	进行中 (0/1人)

andershsueh / alice-cli .gitee-modal { width: 500px !important; }

搜索帮助

andershsueh / alice-cli