# Winyunq Core

> Winyunq 项目核心规范，定义战略、战术、代码风格及工程自动化流程。

- Skill: `winyunq/winyunq-core` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add winyunq/winyunq-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/winyunq/winyunq-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: winyunq (https://skillmd.com/u/winyunq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/winyunq/winyunq-core

---


# WinyunqCore Skill

## 1. 核心原则 (Core Principles)

### 协作边界 (Strategic vs. Tactical)
- **战略由人**：开发者负责架构设计、模块划分、命名规范等核心决策。
- **战术由 AI**：AI 负责代码实现、细节优化、Bug 修复及性能调优。
- **扩产优先 (Maximize Output Efficiency)**：使用相同的 Token/上下文空间，通过结构化（Winyunq Style）产出更高信息密度的代码与文档。

### 临时文件规则 (Gemini Prefix)
- **Gemini 前缀**：所有实验性质的文件必须带有 `Gemini` 前缀。
- **沙盒机制**：实验成功后需由用户确认才可去掉前缀，正式文件严禁使用 V1, V2 等后缀。

## 2. 核心命名规范 (The Eternal Truths)

> [!IMPORTANT]
> **代码风格“永恒真理”**：
> - **PascalCase (大驼峰)**：所有文件夹、文件、类、函数、变量必须使用大驼峰命名。
> - **完整命名 (Full Naming)**：严禁缩写（如使用 `Accelerometer` 而非 `Accel`）。
> - **无下划线 (No Underscores)**：禁止在任何命名中使用 `_`。
> - **强制对齐**：块注释 `/** ... **/` 必须严格遵守 Col 3/15/35 基准对齐。

### 3. 代码锚定与锁定 (Anchoring & Locking)
- **正式注释锁定原则 (Formal Comment = Locked)**：
    - **锁定区**：凡是拥有 Winyunq 标准块注释（C++ 为 `/**`，Python 为 `##`）的代码块，视为“已确定的真理”。AI 默认禁止擅自修改锁定的逻辑。
    - **实验区**：带有 `Experimental` 标签或仅有简略注释的代码。AI 可自由覆盖、重构并改进其逻辑。
- **普通区域**：AI 根据需求读写，但应尊重已建立的锚定边界。

### 阶段一：协议先行 (Header First)
- 开发者与 AI 协商确定头文件（`.hpp`）及函数列表。
- AI 在头文件中预填充符合规范的 `/** ... **/` 块注释。

### 阶段二：骨架锚定 (Implementation Anchoring)
- 实现函数时，AI 应在 `.cpp` 中通过注释或工具锚定函数边界，在限定范围内填充逻辑，避免破坏架构。

### 阶段三：自动化质量监控 (Linting & Refreshing)
- AI 定期运行 Skill 内置脚本（见 `scripts/`），统计并修复格式违规点。

## 4. 工具集成 (Skill-MCP Synergy)
- **Skill 是大脑**：存储真理与流程逻辑。
- **Scripts 是手脚**：Skill 下的 `scripts/` 存放专用 Python 脚本。
- **核心工具**：
    - `WinyunqCommenter`: 自动化生成 Col 对齐注释。
    - `WinyunqLinter`: 自动检测并刷新格式（命名、空行、下划线）。

## 5. 上下文压缩读取

- Target 应指向具体函数或变量；设定一次后，后续读取省略名称。
- 调用某函数时优先使用 `Declaration`，只读取头文件声明与紧邻公开注释。
- 理解实现时使用 `Definition`，只返回当前 Target 的代码并剥离注释和兄弟对象。
- 检查注释时使用 `Comments`，缺省只返回函数体注释；按需选择 `declaration`、`definition` 或 `all`。
- 只有准备编辑且必须保留源码原貌时才使用 `ReadForEdit`；它仍然只返回当前 Target，不读取完整文件。
- Doxygen 仅作为可选范围探测器；缺少 Doxygen 时使用内置词法切片器，读取协议保持不变。

## 6. Target 级编辑

- 修改前调用 `EditCode.Prepare`；Target 已包含函数身份，因此它只返回无注释函数体，并在服务端记住文件版本和物理位置。
- 使用 `EditCode.Preview` 检查短代码片段替换，再使用 `EditCode.Replace` 原子应用。
- `Replace` 只允许修改当前函数体；函数签名、兄弟函数、Target 外源码均保持不变。
- 代码写入不得携带注释。若替换范围穿过既有注释，必须缩小代码片段，不能静默删除注释。
- Target、工作路径或过滤范围变化后，未完成的编辑事务立即失效。
- 文件在 `Prepare` 后发生变化时拒绝写入，重新读取后才能继续。

## 7. 用户锁定

- `TargetLock.Lock` 锁定的是当前逻辑 Target，不是整个文件；同一文件内未锁定的兄弟函数仍可维护。
- 锁定 Target 仍可执行所有读取和无副作用预览，但 `EditCode.Replace` 必须由服务端拒绝。
- 只有用户明确要求解锁时才可调用 `TargetLock.Unlock`，并必须提交 `UNLOCK <完整 Target 名>` 确认文本。
- 锁定或解锁都会清除旧编辑票据；解锁后必须重新 `EditCode.Prepare`，不能恢复锁定前的写入事务。
- AI 不得为了完成任务自行解锁，不得将“用户要求修改”推断为“用户要求解锁”。