---
title: "YuiNijika 编码与文档规范"
description: "YuiNijika coding-style and docs-style rules inlined as an online Kasumi skill page."
---

> 编码、写技术文档或提交代码前必须执行 YuiNijika 编码规范与文档规范。

## 适用场景

- 写码或改码：执行下方「编码规范」
- 写技术文档 / README / API / MDX：执行下方「文档规范」

规则全部内联在本页，离线也可用。

## 硬性执行规则

- 不得编造礼貌寒暄、冗长解释或夸张动漫表演。
- 不得猜测未知网络用语或缩写，先查证，无法确认时明确说明。
- 编辑后如代码或说明发生变化，必须运行 typecheck 或 lint 验证；不得把 dev server、构建、安装包下载当普通验证。
- 编辑已有源码文件（读、改、删、移、重命名、覆盖）必须使用文件工具，禁止通过终端 shell 命令或脚本原地重写源码：不用 `sed`、`awk`、`Get-Content > file`、`Set-Content`、`echo >`、`Out-File`、单行正则替换，也不用 Python 原地重写已有源码文件。原因是 Windows shell 可能按系统代码页改写内容，导致 UTF-8 中文乱码。
- Python 脚本不在此禁令内当且仅当以下条件同时满足：目标不是已有源码文件、脚本只生成新的输出文件（报告、数据加工结果、脚手架初始文件等）、且生成后经 typecheck 或 lint 验证。AI 可根据任务复杂度和环境可用性自行选择是否用 Python，但不得用 Python 脚本原地修改或覆盖任何已有源码文件。
- 逐文件少量修改优先用文件工具完成；仅当需要批量处理 ≥3 个文件或单文件改动点 ≥5 处时，才考虑用 Python 脚本生成输出或做批量替换，且批量替换仅限非源码文件。
- 保持工作目录干净：不保留空目录，不生成冗余脚本，不做重复低效的重试。
- 不创造无用的临时文件。测试临时内容放 `.tmp/` 或系统临时目录，用完后删除。向 `.tmp/` 或系统临时目录写入非源码的测试输出文件，不视为违反“禁止终端写文件”规则。

# 编码规范

## 优先级

- 项目既有约定优先于本页；本页作为兜底。
- 代码风格跟随所在目录。未约定时按下方规则。

## 文件访问与脚本

- 自动化脚本优先使用 Python，不为小任务写 `.ps1`。
- 仅在真实批量场景使用脚本：数据加工、报告生成、脚手架等。不得用脚本读、改、删、移、重命名或覆盖已有源码文件。
- 严格执行文件工具读写，禁止终端写源文件。脚本的输出文件与源码文件必须区分；脚本不得以任何方式原地修改源码，包括但不限于字符串替换、格式化重写、编码转换。
- 文件工具与脚本的边界：文件工具负责源码编辑；脚本负责批量数据加工、报告生成、脚手架生成等“产出新文件”的任务。两者不得交叉越界。

## 格式

- 缩进跟随目录约定；无约定时使用 4 空格。禁止 Tab。
- 行尾 LF，禁止 CRLF。
- UTF-8 无 BOM。
- 文件结尾保留一个换行。

## 命名

| 元素 | PHP | C++ | TypeScript | Python | Rust |
|---|---|---|---|---|---|
| 类/接口/结构 | PascalCase | PascalCase | PascalCase | PascalCase | PascalCase |
| 方法/函数 | camelCase | camelCase | camelCase | snake_case | snake_case |
| 变量/属性 | camelCase | snake_case | camelCase | snake_case | snake_case |
| 常量 | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE |
| 文件名 | PascalCase | snake_case | kebab-case | snake_case | snake_case |
| 布尔前缀 | `is`/`has`/`should` | `is_`/`has_`/`should_` | `is`/`has`/`should` | `is_`/`has_`/`should_` | `is_`/`has_`/`should_` |

目录已表达语义时不得重复：`components/Button` 不要写成 `components/ButtonComponent`。

## 类型

- PHP：类型标注齐全，`strict_types=1`。
- C++：参数与返回值使用具体类型，`auto` 仅在能从初始化清晰推断时使用。
- TypeScript：`strict: true`，禁用无说明的 `any`，优先 `interface` 描述对象、`type` 描述联合或交叉。
- Python：公共函数必须有类型标注。
- Rust：优先 `Option` / `Result`，不随意 `unwrap()`。

## 代码结构

- 先处理错误或边界，主流程保持浅层。
- 不使用魔法数字；用命名常量或枚举。
- 单一职责：一个函数只做一件事。
- 依赖显式传递，不依赖隐藏全局状态。
- 不混合 UI、业务、数据访问在同一个文件。

## 复杂度守则

### 防过度防御

几乎不会发生的边界或并发问题，不得私自加分叉和防御代码。必须向用户讲清发生概率、触发条件和代价，经用户确认后再加。严禁为了理论上更稳提前膨胀代码。

### 入口单次校验

外部数据只在边界校验一次。内部函数依赖类型系统传递有效数据，禁止层层重复判断同一个字段。每多一层重复判断都是噪声，也会扩大改动面。

### 拒绝提前抽象

单次使用的逻辑就近内联，不提前拆无意义的 helper。只有出现第二个真实使用方，或函数长度确实影响阅读时才考虑抽取。抽象必须有真实复用理由。

### 控制复杂度

非必要不用 `try/catch`。能单函数清晰写清的逻辑不要硬拆成多层。优先让数据流直观、调用链短、失败点明确。

## 注释

注释解释 why，不解释 what。禁止把代码行为逐行翻译成注释。

差：
```ts
// Return the result
return result;
```

好：
```ts
// React batches state updates so two calls still render once
```

仅对复杂逻辑、公共 API 契约、特殊异常、不明显结构写文档注释。

## 语言重点

- PHP：新文件 `declare(strict_types=1)`，纯 PHP 省略 `?>`，Controller 保持薄层。
- C++：`#pragma once`，header 不写 `using namespace std;`，优先智能指针和 `enum class`。
- TypeScript：3 个以上参数用对象参数，异步只写 `Promise` 配 `async/await`。
- Python：PEP 8，公共函数标注类型，优先 f-string 和 pathlib。
- Rust：`rustfmt` / `clippy` 干净，优先借用避免克隆。

# 文档规范

## 页面结构

除用户另有指定外，技术文档按此骨架：

```md
# 页面标题

> 一句话说明本页覆盖什么、解决什么问题。

## 模块边界 / 适合谁阅读 / 入口
## 核心内容
## 代码示例
## 常见问题 / 常见风险 / 排查路径
```

必须包含：

1. 具体能力标题，不使用营销标语
2. 一句话范围说明
3. 先写边界：本页是什么、不是什么
4. 真实入口：文件、函数、Hook、配置键、加载顺序
5. 表格表示层级、字段、文件、优先级
6. 可运行示例：真实命名、真实调用形状、真实守卫
7. 反例：说明不该怎么做
8. 复杂主题必须有排查路径或症状表

## 内容纪律

- 文档必须回答：入口在哪、加载顺序、如何调用、读取、扩展、什么不该碰、失败如何排查。
- API、路径、Hook、配置键必须基于真实代码或已验证事实，禁止虚构。
- 不确定时给出验证方法，不编造细节。
- 默认简体中文，语气直接冷静，短段落。
- 不写“非常强大、灵活、易扩展”这种无机制的句子。
- 不把聊天式片段写进技术文档。

## 示例要求

- 代码示例必须符合本页编码规范。
- 涉及权限、付款、下载、库存等敏感场景必须包含守卫和幂等说明。
- 展示反例时注明错误点。

## 文档检查清单

收尾前逐条检查：

1. 开发者能否在 30 秒内找到入口文件？
2. 加载、读取、写入、扩展路径是否明确？
3. 结构重要的地方是否使用表格？
4. 示例是否真实、可直接复制、符合编码规范？
5. 是否明确列出不该做的路径？
6. 是否有失败排查路径？
7. 是否凭空发明了名称或路径？

若有任意一项不满足，先重写再交付。