docs(agents): 把 Schema Validation 清单第 3 条指向真实存在的 schema (#852)

[yinlianghui]

Fixes #852

⚠️ 这是 repo 指令文件（AGENTS.md）的改动,措辞会影响所有后续 agent,维护者可随时否决/回滚。 事实面（WorkflowRuleSchema 不存在、Flows 才是真实承载面）是实测的;具体怎么措辞不是。

1. 先测清单全貌,再定改法

PM 裁定给了二选一：若「🔒 Schema Validation Requirements」清单已有条目覆盖 Flows → 第 3 条是退休残留,删除;若没有 → 改写。

实测：清单共 7 条（AGENTS.md 第 118-124 行），逐条为 Objects / Pages·Views·Dashboards·Forms / Workflows / State Machines / Plugins / Permissions / AI Agents ——没有任何一条覆盖 Flows,而 src/flows/ 下有 21 个 *.flow.ts、pnpm validate 报 24 Flows。清单里唯一那条 automation 侧的记录变更类条目就是坏掉的第 3 条。

→ 因此走改写,不是删除。

2. 符号面证据（全部实测于当前 worktree,@objectstack/spec 17.0.0-rc.2）

零命中 + 反空跑对照，同一条 grep 打在真实存在的符号上：

符号	grep -rl 命中文件数
WorkflowRule	0
FlowSchema	63
JobSchema	46
StateMachineSchema	40
ApprovalNode	30

探针没坏,是符号真的没有。（本仓当前装了 52 个 @objectstack/* 包;#852 正文记的是 50,差额来自基线不同,零命中的结论不变。）

一次性 require() 实测（跑完即删,不留文件），逐条复核清单里每一个导出是否真实可 .parse()：

@objectstack/spec/data       :: ObjectSchema        -> function (has .parse)
@objectstack/spec/ui         :: PageSchema          -> function (has .parse)
@objectstack/spec/ui         :: ViewSchema          -> function (has .parse)
@objectstack/spec/ui         :: DashboardSchema     -> function (has .parse)
@objectstack/spec/ui         :: FormViewSchema      -> function (has .parse)
@objectstack/spec/automation :: FlowSchema          -> function (has .parse)
@objectstack/spec/automation :: StateMachineSchema  -> function (has .parse)
@objectstack/spec/automation :: WorkflowRuleSchema  -> UNDEFINED
@objectstack/spec/automation :: WorkflowSchema      -> UNDEFINED
@objectstack/spec/kernel     :: PluginSchema        -> function (has .parse)
@objectstack/spec/security   :: PermissionSetSchema -> function (has .parse)
@objectstack/spec/ai         :: AgentSchema         -> function (has .parse)

前提复核通过：第 3 条在最新 origin/main（9d2c787a）上仍在第 120 行,原样;其余 6 条确是真实导出、且都带 .parse。只有第 3 条不是。

选定的替换目标同样是实测的,不是照抄 issue：FlowSchema 由 @objectstack/spec/automation 导出（dist/automation/index.d.ts:2),且 defineFlow 的实现就是它本身——

// spec/src/automation/flow.zod.ts:571
export function defineFlow(config: z.input< typeof FlowSchema >): FlowParsed {
  return FlowSchema.parse(config);
}

所以第 3 条写 FlowSchema.parse() 与本仓 *.flow.ts 的实际作者路径是同一个调用,不是并列的第二条路。

3. 与 StateMachineSchema 条目（第 4 条）的关系

第 3 条从「Workflows」变成「Flows」后,"workflow" 这个词在清单里消失,读者的需求需要一条最短指路,否则最可能错投的就是隔壁第 4 条。实测三件事：

• 平台侧的具名拒绝（ObjectSchema.safeParse 实跑,非引述）：

  Unrecognized key(s) on this object: `workflows`.
    • `workflows` is not an ObjectSchema field. Object-level, record-triggered automation
      is authored as a lifecycle hook (`src/objects/{name}.hook.ts`, wrapped in
      `defineHook()`) or as a top-level `record_change` flow — not as `workflows[]`.
  

  workflow:（单数）同样被具名拒绝。本 PR 的指路语与平台自己这段拒绝话术一致。
• 承载面切分（spec/src/api/protocol.zod.ts:695-700,v17 删除 Workflow Operations 时写下的）：记录状态机 = state_machine 校验规则;审批 = flow 里的审批节点（plugin-approvals 认 type === 'approval'）;记录触发自动化 = lifecycle hooks + record_change flow（FlowSchema 的 type 枚举实测为 ['autolaunched','record_change','schedule','screen','api']）。
• 第 4 条不是同一个东西：本仓的记录状态机是对象 validations[] 里的 type: 'state_machine' 判别式（crm_contract / crm_lead / crm_case / crm_quote / crm_opportunity 五处),它由 ObjectSchema.parse() 校验,对应 StateMachineValidationSchema（object.zod 第 74-76 行,字段是 field / transitions / initialStates）。而第 4 条的 StateMachineSchema 是 id / initial / states / on 形状的顶层机器定义（state-machine.zod 第 67 行起）——两者形状不同,拿第 4 条去 parse 本仓的状态机不会通过。本仓 *.statemachine.ts 文件数为 0。

因此在清单下补了一段引用块（3 句）指路,没有重构清单、没有改第 4 条本身。第 4 条依然是真实导出,只是被点明它不管 validations[] 那条。

4. 改动面

只有两个文件：

• AGENTS.md：第 3 条一行改写 + 清单下方 8 行引用块。清单其余 6 条一字未动。
• .changeset/agents-md-schema-list.md：'hotcrm': patch,站内路径一律反引号（docs(guides): import-and-export 按实测改写——导入向导在列表视图而非 Setup → Data，Salesforce 迁移标注未落地 (#763) #797 教训：link-check 会扫 .changeset）。

src/**、content/**、content/docs/releases/、@objectstack/* 依赖版本均未触碰。

5. 验证（全量,共享锁 + NODE_OPTIONS=--max-old-space-size=4096）

AGENTS.md 不在多数闸门的扫描面内,全量跑是为了证明基线没被我破坏：

命令	退出码	关键行
pnpm validate	0	17 Objects 344 Fields · 24 Flows — 5 条 author-time warning 与本 PR 无关,为基线既有
pnpm typecheck	0	tsc --noEmit 无输出
pnpm build	0	✓ Build complete (1635ms) · dist/objectstack.json (1921.3 KB)
pnpm test -- --maxWorkers=2	0	Test Files 66 passed (66) · Tests 1587 passed | 1 skipped (1588)
pnpm lint	0	13 warning(s), 14 suggestion(s) — 基线既有
pnpm hygiene	0	✓ no raw control bytes in first-party files · ✓ source hygiene clean

控制字节自扫（超出闸门盲区）：grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' AGENTS.md .changeset/agents-md-schema-list.md → 零命中（exit 1）。

6. 顺带发现（已单独立 issue,本 PR 不改）

• AGENTS.md 的 ObjectQL 范例教的是 broker.find(name, { filters }) —— 本仓无此调用面,谓词键也不是 filters,且对象名没带 crm_ 前缀 #855：AGENTS.md 唯一的 ObjectQL 范例 broker.find('opportunity', { filters: … }) —— broker 在 src/ 零命中、谓词键实为 where（本仓 .changeset/hook-query-where-not-filter.md 记过这笔静默错读的账）、对象名还违反同文件第 59 行的 crm_ 强制前缀。与 AGENTS.md 第 120 行让 agent 用 WorkflowRuleSchema.parse() 校验「Workflows」—— 该导出在平台上不存在 #852 同类,且失败是静默的。
• AGENTS.md 里 action 文件后缀自相矛盾：目录图写 *.actions.ts,协议与流程写 *.action.ts,磁盘上 6:0 全是复数 #856（finding）：action 文件后缀在同一份 AGENTS.md 里 3 处写单数 *.action.ts、1 处写复数,磁盘实测 6:0 全是复数。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 12:15am