update-claude-code-schema

name	update-claude-code-schema
description	同步 Code Manager 的 Claude Code settings schema。当需要拉取 SchemaStore 最新定义、跟进 hooks/env/worktree/permissionRule 等新字段、排查 Rust 配置校验（`validate_settings_document` / `config::tests`）变红，或复盘 schema 变化对前端编辑器/表单/类型契约的影响时使用；凡改动 `src/schemas/claude-settings.schema.json` 都走本技能。

Update Claude Code Schema

为 Code Manager 同步 Claude Code settings 的 SchemaStore 定义。事实源永远是当前下载的完整 https://www.schemastore.org/claude-code-settings.json：整体替换本地文件，再证明语义等同。字段级拼补会漏掉上游的“删除字段”变更、让本地 schema 越积越脏——只做整体替换。

1. 前置检查

读 CLAUDE.md 与 .claude/rules/config-system.md。git status --short 看工作区，只叠加本任务改动，不回退别人或上一条工作线的改动。确认 curl、jq、node、pnpm、cargo 可用。

2. 下载官方 schema 到临时文件

curl -fsSL https://www.schemastore.org/claude-code-settings.json \
  -o /private/tmp/claude-code-settings.latest.json

• 下载到临时文件，是为后续语义比对留一份未经格式化的原始字节基线——直接覆盖本地文件会丢掉对照基线。
• sandbox 会挡掉这条 curl（读 /etc 证书或写 /private/tmp 被拒，报 curl: (77) 或 operation not permitted）。提权重跑同一条命令，不要改命令绕过。

3. 整体替换 + 单文件格式化

cp /private/tmp/claude-code-settings.latest.json src/schemas/claude-settings.schema.json
pnpm exec biome format --write src/schemas/claude-settings.schema.json

只格式化这一个文件：pnpm check / make fmt 会顺手改写无关文件，污染本次改动的 blast radius。

4. 语义比对

先验 JSON 完整，再证明本地与下载文件深度排序后字节相同——格式差异（缩进、键顺序）允许，内容漂移不允许：

jq empty src/schemas/claude-settings.schema.json
node -e '
const fs = require("fs");
const sort = v =>
  Array.isArray(v) ? v.map(sort)
  : v && typeof v === "object"
    ? Object.fromEntries(
        Object.entries(v)
          .sort(([a],[b]) => a.localeCompare(b))
          .map(([k,x]) => [k, sort(x)])
      )
    : v;
const local = sort(JSON.parse(fs.readFileSync("src/schemas/claude-settings.schema.json","utf8")));
const upstream = sort(JSON.parse(fs.readFileSync("/private/tmp/claude-code-settings.latest.json","utf8")));
if (JSON.stringify(local) !== JSON.stringify(upstream)) {
  console.error("schema differs semantically");
  process.exit(1);
}
console.log("schema matches SchemaStore semantically");
'

完成标准：打印 schema matches SchemaStore semantically。 失败说明 biome format 改写了内容而非仅格式——回查 biome 配置或 schema 中的特殊字符（unicode escape、JSON pointer）。

5. 审查关键变化

深度排序比对只证明“和上游一致”，不告诉你“上游改了什么”。用 git show HEAD 取旧版、和下载文件对比顶层 properties 键，抓出增删：

diff <(git show HEAD:src/schemas/claude-settings.schema.json | jq -r '.properties|keys[]' | sort) \
     <(jq -r '.properties|keys[]' /private/tmp/claude-code-settings.latest.json | sort)

再按下列高频位置扫嵌套结构——这是历史踩过的点，不是穷举，以实际 diff 为准：

• env：从宽泛 pattern 收紧成显式 properties，或新增大量环境变量枚举。
• hooks：新事件类型、新字段（如 continueOnBlock、args exec form）、嵌套结构调整。
• worktree：新字段或 enum 值。
• permissionRule 正则：是否影响 Read(*)、Skill(*)、mcp__* 等通配规则的合法性。
• 标量字段的 enum 收紧/放宽：如顶层 effortLevel 去掉 max。step 5 的 .properties|keys[] 顶层键 diff 只能发现键增删，抓不到枚举收紧；这类变化会让前端表单选项与 Rust validate_settings_document 校验失配，必须单独核对。
• 区分同名概念的两套枚举：env.CLAUDE_CODE_EFFORT_LEVEL（env 键）与顶层 effortLevel 是不同字段、不同枚举、不同约束，收紧一个不影响另一个；排查前后端影响时不要混用。

审查只为把高风险变化告诉用户，确认是否需要后续动作（编辑器 UI、Rust 校验、表单字段、类型同步）。除非用户明确要求，本任务范围只到 schema 文件。

6. 验证

改动范围	命令
JSON 完整性	jq empty src/schemas/claude-settings.schema.json
Rust 配置校验	cd src-tauri && cargo test config::tests
格式	make fmt-check
Diff whitespace	git diff --check

• 测试过滤是子串匹配：cargo test validate_settings_document 会命中 4 个 validate_settings_document_* 单测（均在 config::tests 内），并非"0 个用例"。验证以更全的 cargo test config::tests（68 passed 量级）为准即可，二者不矛盾。
• validate_settings_document() 的性质：未知顶层键放行，已知字段的嵌套结构严格校验。推论：上游删除顶层字段 → 老配置作为未知键仍通过，Rust 一般不炸；上游改已知字段的嵌套结构 → Rust 可能挂，需更新断言或修校验代码。
• 前端门禁：Stop 钩子会通用地提示 make lint/build/test-frontend；schema-only 改动由上表覆盖，无需前端构建。

没有本次会话的新鲜命令输出，不声称通过。

7. 收口输出

## Schema 同步结果

下载源：https://www.schemastore.org/claude-code-settings.json
下载时间：<UTC 时间>

语义比对：<pass/fail>
JSON 完整性：<pass/fail>
Rust 配置校验（config::tests）：<pass/fail，附关键输出>
格式与 diff 检查：<pass/fail>

关键 schema 变化：
- 顶层字段：<新增 / 移除条目>
- hooks：<新字段 / 新事件 / 结构调整>
- env / worktree / permissionRule：<具体点>

需要人工后续（不在本任务范围）：
- <编辑器 UI / 表单字段 / 前端类型是否需要同步>
- <Rust 校验是否需要补断言>