‹ 首页

formax-semantics-parity-workflow

@yusifeng · 收录于 5 天前 · 上游提交 3 周前

Use when implementing or modifying behavior that must stay consistent across TUI and Web (mode/input/tool/replay/order). Require canonical semantics first, then TUI/Web adapters, then renderer-specific UI.

场景双端开发行为对齐

适合你，如果需要在 TUI 和 Web 间同步交互逻辑

/ 下载安装
https://github.com/yusifeng/formax/tree/main/.codex/skills/formax-semantics-parity-workflow ↗
/ 通过 npx 安装 校验哈希
npx oh-my-skill add yusifeng/formax/formax-semantics-parity-workflow
/ 通过 bash 安装
curl -fsSL https://oh-my-skill.com/install.sh | bash -s -- yusifeng/formax/formax-semantics-parity-workflow
/ 已经装过?验证本机副本,不用重装
npx oh-my-skill verify yusifeng/formax/formax-semantics-parity-workflow
安装目标可用 --agent / --scope 或 --to 明确指定;省略时只会在唯一已存在的 agent 目录上自动选择,零命中或多命中会停止并提示。content_hash 缺失或不一致均拒装。
192GitHub stars
~952最小装载
~1.8K含声明引用
~1.8K文本包总量
索引托管

怎么用

商店整理自技能原文 · 版本 5a48573 · 表述以原文为准
它做什么

当修改需要在 TUI 和 Web 之间保持一致的行为（如模式、输入、工具、回放、排序）时，它会让你先定义规范语义，再更新两端适配器，最后处理特定 UI。

什么时候触发

当你需要实现或修改跨 TUI 和 Web 的行为，且涉及模式、输入、工具、回放或排序等方面时触发。

装好后可以这样说
技能将按语义优先流程执行。
确保工具行为在两端一致。
技能原文 SKILL.md作者撰写 · MIT · 5a48573

formax-semantics-parity-workflow

Goal

Use this skill when changing behavior that must stay consistent across TUI, app-server, and Web: mode, input lifecycle, tool sequencing, replay, or ordering.

Read First
  • docs/contracts/semantics-contract.md
  • docs/contracts/app-server-interaction-contract.md
  • docs/frontend/app-server-ui-spec.md
  • docs/contracts/interactive-input-contract.md when input lifecycle changes

These docs are canonical. If stable cross-surface behavior changes, update them before or with code.

Code Map
1) Semantic single source of truth
  • packages/core/src/features/semantics/*
  • canonicalEvents.ts
  • transcriptProjection.ts
  • modeSemantics.ts
  • replModeTransition.ts
  • turnInputBuilder.ts
  • inputStateMachine.ts
2) App-server contract emit / restore
  • packages/core/src/app-server/turnRunner.ts
  • packages/core/src/app-server/server.ts
  • packages/core/src/app-server/threadStore.ts
  • packages/core/src/app-server/store/sessionEventReader.ts
  • packages/core/src/app-server/turn/inputStore.ts
3) TUI adapter (renderer can differ, semantics cannot)
  • packages/core/src/features/repl/controller/send/send.ts
  • packages/core/src/features/repl/controller/streaming/streaming.ts
  • packages/core/src/features/repl/useReplController.ts
4) Web adapter (renderer can differ, semantics cannot)
  • packages/web-reference-react/src/eventAdapters.ts
  • packages/web-reference-react/src/App.tsx
  • packages/web-reference-react/src/store.ts
  • packages/web-reference-react/src/turnEventCursor.ts
5) Canonical docs to keep in sync
  • docs/contracts/semantics-contract.md
  • docs/contracts/app-server-interaction-contract.md
  • docs/frontend/app-server-ui-spec.md
  • docs/contracts/interactive-input-contract.md when input lifecycle changes
High-Signal Patterns
  • Semantic-first implementation order:
  • define contract / event shape / state transition
  • update shared semantics
  • update app-server emit / replay state
  • update TUI and Web adapters
  • update renderer-only UI last
  • Ordering discipline:
  • replaySeq is the primary ordering key
  • traceId/seq are diagnostics and turn-local hints, not global order
  • on replay gap, rebuild from semantic baseline; do not keep stitching stale tails
  • Tool semantics discipline:
  • keep toolUseId -> toolName sticky behavior in semantics / adapter path
  • never depend on UI copy to infer tool state
  • Mode/input discipline:
  • mode is a semantic transition, not just a visual toggle
  • input lifecycle remains a finite-state machine, not ad-hoc UI flags
Minimal Workflow
  1. Define the event / state transition in canonical docs and the shared semantics layer first.
  2. Update app-server emit / replay state so the semantics remain recoverable.
  3. Update TUI and Web adapters to consume the shared semantics; update renderer-only UI last.
  4. If packages/core/src/features/repl/** semantic-flow files move, run the REPL semantic gate before review.
  5. Run the minimum regression set below, then review via AGENTS.md.
Minimum Regression
  • bun run type-check
  • bun run test -- packages/core/src/features/semantics
  • bun run test -- packages/core/src/features/semantics/__tests__/projectionParity.test.ts
  • bun run test -- packages/core/src/app-server/turnRunner.test.ts packages/core/src/app-server/server.test.ts packages/core/src/app-server/turn/inputStore.test.ts
  • npm --prefix packages/web-reference-react run type-check
  • npm --prefix packages/web-reference-react run test -- src/App.test.tsx src/store.test.ts src/turnEventCursor.test.ts src/toolEventNormalizer.test.ts
  • bun run test:repl-semantic-gate when packages/core/src/features/repl/** semantic-flow files change

For fixture selection and parity assertions, use references/fixtures-checklist.md.

Guardrails
  • Do not patch one renderer in isolation when the bug belongs to shared semantics.
  • Do not add a second semantic state machine inside TUI or Web.
  • Do not use UI text or copy as semantic-state input.
  • Do not introduce new ordering rules outside the shared semantics layer.
  • Do not call a parity change done until app-server, TUI, and Web consume the same semantic rule.
按 MIT 许可原样转载,未经改动 · 在 GitHub 查看 →

评论

登录即可评论;带「已验证安装」的,是发布者名下有本店的安装或持有记录。
…