AgentSkillsCN

zireael-platform-boundary

在核心/Unicode/实用工具层严格执行平台边界，使其完全不依赖操作系统头文件。

SKILL.md
--- frontmatter
name: zireael-platform-boundary
description: Enforce the strict platform boundary where core/unicode/util stay OS-header-free.
metadata:
  short-description: Platform interface + backend rules

When to use

Use this skill when working on:

  • •the platform interface header (src/platform/zr_platform.h)
  • •Win32 or POSIX backend implementation
  • •event loop blocking/wake strategy
  • •terminal raw mode lifecycle and restoration

Non-negotiable boundary rules

  • •src/core, src/unicode, src/util MUST NOT include OS headers (Win32 or POSIX).
  • •OS-specific code MUST be isolated to:
    • •src/platform/win32/
    • •src/platform/posix/
  • •Avoid #ifdef in core/unicode/util; allowed only in platform backends and minimal selection glue.

Platform interface design

Goal: a core-facing platform interface that is:

  • •POD-only (fixed-width integer types; no OS types)
  • •opaque handle based (plat_t*)
  • •allocation-free in hot paths
  • •supports a "wake" primitive to interrupt blocking waits

Interface categories:

  • •lifecycle: create/destroy, enter/leave raw (idempotent best-effort restore)
  • •I/O: read input bytes, write output bytes (single flush per present)
  • •wait/wake: block until input or wake event, wake from other threads
  • •caps/size: get terminal size, capabilities (color/mouse/paste)

Source of truth

  • •docs/REPO_LAYOUT.md — boundary rules and #ifdef policy
  • •docs/modules/PLATFORM_INTERFACE.md — core-facing interface spec
  • •src/platform/zr_platform.h — actual interface header

Backend notes

POSIX:

  • •raw mode: termios; restore on exit; best-effort restore on signals
  • •blocking: poll/select on stdin + wake fd (eventfd/self-pipe)
  • •resize: SIGWINCH + ioctl(TIOCGWINSZ) when flagged

Win32:

  • •enable VT output (ENABLE_VIRTUAL_TERMINAL_PROCESSING)
  • •prefer VT input bytes (ENABLE_VIRTUAL_TERMINAL_INPUT)
  • •blocking: wait on input handle + wake event handle
  • •restore modes on teardown; handle console close events

Testing

Platform correctness is validated via integration tests:

  • •POSIX: PTY-based tests (headless)
  • •Windows: ConPTY-based tests where possible