# Python

> Python 协作开发工作流与 Winyunq 风格规范

- Skill: `winyunq/python` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add winyunq/python`
- Raw SKILL.md: https://api.skillmd.com/api/skills/winyunq/python/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/python

---


# Python Winyunq 协作开发 Skill

本 Skill 定义了 Python 项目的协作开发流程、权限管理以及编码风格。

## 1. 核心工作流 (The 3-Phase Workflow)

### Phase 1: 原型与草稿 (Prototyping)
*   **文件特征**: `Gemini_` 前缀 (e.g., `Gemini_data_loader.py`).
*   **权限**: 
    *   **AI**: 拥有完全控制权，可覆盖 (Overwrite)。
    *   **User**: 审查设计。
*   **操作**: 使用 `SetTarget` 快速生成 `.py` 文件骨架。

### Phase 2: 接口锁定 (API Locking)
*   **目标**: 确定 Class 和 Function 的签名。
*   **文件特征**: 正式文件名，Class/Function 下方包含完整的 `"""` 文档字符串 (Docstring)。
*   **权限**:
    *   **锁定标志**: `"""` 文档字符串存在，且内容**不含** "Gemini"。
    *   **AI**: 禁止修改函数签名和文档可。

### Phase 3: 实现锁定 (Implementation Locking)
*   **目标**: 完成内部逻辑。
*   **文件特征**: 正式文件名，代码行上方包含 `#` 注释。
*   **权限**:
    *   **锁定标志**: `#` 注释存在，且内容**不含** "Gemini"。
    *   **AI**: 禁止修改被 `#` 注释保护的逻辑代码块。

---

## 2. 编码风格 (Winyunq Style)

### 2.1 命名规范 (PEP8 + 强制)
*   **Class**: `UpperCamelCase` (e.g., `DataManager`).
*   **Function/Variable**: `lower_snake_case` (e.g., `load_data`, `user_id`).
*   **Constant**: `SCREAMING_SNAKE_CASE` (e.g., `MAX_RETRY`).
*   **File**: `lower_snake_case` (e.g., `data_manager.py`).

### 2.2 注释与锁定规范

#### API 文档 (Docstring) - 对应 C++ `/**`
每个 Class 和 Function 必须有文档字符串。
*   **锁定**: `""" ... """` 意味着 API 已定稿。
*   **格式**: Google Style 或 NumPy Style 均可，必须清晰描述 Args 和 Returns。
    ```python
    class DataProcessor:
        """
        核心数据处理类 [LOCKED]
        
        Args:
            capacity (int): 初始容量
        """
        def process(self, data):
            """
            处理输入数据 [LOCKED]
            
            Args:
                data (list): 输入列表
            Returns:
                bool: 处理成功状态
            """
            pass
    ```

#### 实现注释 (Hash Comment) - 对应 C++ `///`
关键逻辑步骤必须使用 `#` 注释。
*   **锁定**: `#` 意味着该行/该块逻辑已定稿。
*   **格式**: `#` 后接空格，位于代码上方。
    ```python
    def calculate(x):
        # 检查边界条件 [LOCKED]
        if x < 0:
            return 0
            
        # 应用核心公式 [LOCKED]
        result = x * 2.5
        return result
    ```

---

## 3. 脚本工具 (Automation Tools)

> **CRITICAL**: You MUST use these tools for all code modifications. Do not use generic file tools.

- **SetTarget.py**: 上下文管理 (Call First)。
- **CheckStyle.py**: 状态检查 (Check) 与 晋升 (Promote)。
- **WriteCode.py**: 唯一允许的代码写入工具 (支持 Declare/Define/Enable/Disable)。
- **ReadCode.py**: 代码读取 (Declaration/Definition/Reference)。
- **AutomaticDocument.py**: 文档生成与格式化 (Format)。

## 4. MCP调用协议 (WinyunqCoding Protocol)

为避免命令行字符转义与编码问题，**强烈推荐**使用以下协议执行复杂操作：

### 4.1 协议流程
1.  **构造指令**: AI 将操作指令封装为 JSON 格式，写入工作区根目录下的 `WinyunqCoding.md`。
2.  **执行**: AI 调用 `python .agent/skills/Python/scripts/RunSkill.py` (无参数)。
3.  **清理**: 脚本执行后虽然不会自动删除 `WinyunqCoding.md`，但在下一次操作时不仅会覆盖它，而且推荐AI在任务完成后主动清理。

### 4.2 文件格式 (WinyunqCoding.md)
文件应包含一个 `json` 代码块：
```markdown
# Winyunq Coding Task
```json
{
    "target": "WriteCode",           // 目标工具: WriteCode, ReadCode, CheckStyle
    "command": "Define",             // 操作指令
    "params": {                      // 参数字典
        "name": "MyClass.process",
        "code": "Gemini_TEMP_FILE.py", // 推荐传递文件路径，或者直接传递代码字符串
        "mode": "overwrite"
    }
}
```
```

### 4.3 支持的指令集
*   **WriteCode**:
    *   `Declare`: `{ "code": "..." }`
    *   `Define`: `{ "name": "...", "code": "...", "mode": "overwrite" }`
*   **ReadCode**:
    *   `Declaration`: `{ "name": "..." }`
    *   `Definition`: `{ "name": "...", "mode": "code" }`