Squashed 'docs/standards/playbook/' changes from 8b75747..c3f8137
c3f8137 📦 deps(skills): sync superpowers 35e827d 📦 deps(skills): sync superpowers e546ffb 📦 deps(skills): sync superpowers f7f2c57 🔧 chore(ci): use ci-bot identity for superpowers sync commits fa247a7 📦 deps(skills): sync superpowers a97c333 🔧 chore(ci): add resilient upstream fetch fallback for superpowers update 484f9d3 🔧 chore(ci): automate thirdparty superpowers refresh and sync base c19e53e 📝 docs(playbook): refresh guidance and examples 52046b4 📝 docs(prompts): add code-review template and align docs flow 9ac8a4c 📝 docs(typescript): clarify ts and js support boundaries 1f46203 ✨ feat(typescript): add standards docs and sync rewrite coverage 872c1af 🔧 feat(skills): install to agents home git-subtree-dir: docs/standards/playbook git-subtree-split: c3f81371e24d63b603de9b6eb92bf7e4c453a2b4
This commit is contained in:
@@ -0,0 +1,37 @@
|
||||
# TypeScript/JavaScript 代码风格
|
||||
|
||||
本 Playbook 的 TypeScript/JavaScript 代码风格以 Google TypeScript Style Guide 为基线：
|
||||
|
||||
- Google TypeScript Style Guide: https://google.github.io/styleguide/tsguide.html
|
||||
- TypeScript 官方手册: https://www.typescriptlang.org/docs/handbook/
|
||||
|
||||
## 项目约定
|
||||
|
||||
- 适用范围：业务代码默认使用 `.ts/.tsx`；`.js/.mjs/.cjs` 仅用于脚本、工具链或配置
|
||||
- 行宽：100（与 Prettier 配置保持一致）
|
||||
- 缩进：2 空格
|
||||
- 引号：单引号（Prettier `singleQuote: true`）
|
||||
- 分号：不加（Prettier `semi: false`）；如仓库已有配置则以仓库为准
|
||||
- 尾随逗号：`all`（ES5+）
|
||||
|
||||
## 类型约定
|
||||
|
||||
- TypeScript 禁止 `any`；需要宽泛类型时用 `unknown` 并做类型收窄
|
||||
- 优先使用 `interface` 描述对象结构；`type` 用于联合/交叉/工具类型
|
||||
- 函数返回类型：公共 API 必须显式标注；内部实现可依赖推断
|
||||
- 泛型参数名：单字母（`T`、`K`、`V`）或描述性名称（`TItem`）
|
||||
- JavaScript 文件建议启用 `// @ts-check` 与 JSDoc 进行静态检查
|
||||
|
||||
## 模块约定
|
||||
|
||||
- 使用 ES Module（`import`/`export`）；禁止 `require()`（除 `.cjs` 文件）
|
||||
- 每文件一个主要导出；避免桶文件（`index.ts`/`index.js` re-export 过多）
|
||||
- 路径别名：以 `tsconfig.json` 的 `paths` 为准
|
||||
|
||||
## 异步约定
|
||||
|
||||
- 优先 `async/await`；避免裸 `.then()/.catch()` 链
|
||||
- `async` 函数必须处理错误（`try/catch` 或调用方捕获）
|
||||
- 不得忽略 Promise（使用 `void` 操作符显式标记有意忽略）
|
||||
|
||||
当既有代码与本约定冲突时，优先保持局部一致性，逐步迁移。
|
||||
@@ -0,0 +1,88 @@
|
||||
# TypeScript 配置清单
|
||||
|
||||
本文件汇总 TypeScript 项目常用配置文件说明。
|
||||
|
||||
## 1) `tsconfig.json`
|
||||
|
||||
关键编译选项：
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"strict": true,
|
||||
"noUncheckedIndexedAccess": true,
|
||||
"noImplicitOverride": true,
|
||||
"exactOptionalPropertyTypes": true,
|
||||
"skipLibCheck": true,
|
||||
"outDir": "dist",
|
||||
"rootDir": "src"
|
||||
},
|
||||
"include": ["src"]
|
||||
}
|
||||
```
|
||||
|
||||
- `strict: true`：启用全部严格检查（必须）
|
||||
- `noUncheckedIndexedAccess`：数组/对象索引访问返回 `T | undefined`（推荐）
|
||||
- `skipLibCheck`：跳过 `.d.ts` 检查，加快编译
|
||||
|
||||
## 2) `.prettierrc`
|
||||
|
||||
```json
|
||||
{
|
||||
"semi": false,
|
||||
"singleQuote": true,
|
||||
"printWidth": 100,
|
||||
"trailingComma": "all",
|
||||
"tabWidth": 2
|
||||
}
|
||||
```
|
||||
|
||||
## 3) `eslint.config.js`（Flat Config）
|
||||
|
||||
```js
|
||||
import tseslint from 'typescript-eslint'
|
||||
|
||||
export default tseslint.config(
|
||||
...tseslint.configs.recommendedTypeChecked,
|
||||
{
|
||||
languageOptions: {
|
||||
parserOptions: { projectService: true },
|
||||
},
|
||||
rules: {
|
||||
'@typescript-eslint/no-explicit-any': 'error',
|
||||
'@typescript-eslint/no-floating-promises': 'error',
|
||||
},
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
## 4) `.editorconfig`
|
||||
|
||||
```ini
|
||||
root = true
|
||||
|
||||
[*]
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
|
||||
[*.{ts,tsx,js,jsx,json}]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
max_line_length = 100
|
||||
```
|
||||
|
||||
## 5) `.vscode/settings.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"editor.formatOnSave": true,
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.rulers": [100],
|
||||
"typescript.tsdk": "node_modules/typescript/lib"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
# TypeScript 命名规范
|
||||
|
||||
## 文件与目录
|
||||
|
||||
- 文件名：`kebab-case.ts` / `kebab-case.tsx` / `kebab-case.js` / `kebab-case.jsx`
|
||||
- 脚本/配置文件：`kebab-case.mjs` / `kebab-case.cjs`
|
||||
- 测试文件：`kebab-case.test.ts` / `kebab-case.spec.ts` / `kebab-case.test.js` / `kebab-case.spec.js`
|
||||
- 类型声明文件：`kebab-case.d.ts`
|
||||
- 目录名：`kebab-case/`
|
||||
|
||||
## 标识符
|
||||
|
||||
| 类别 | 风格 | 示例 |
|
||||
| ----------------- | -------------------------- | ------------------------------ |
|
||||
| 类（Class） | `PascalCase` | `UserService` |
|
||||
| 接口（Interface） | `PascalCase` | `UserProfile`（不加 `I` 前缀） |
|
||||
| 类型别名（Type） | `PascalCase` | `ApiResponse<T>` |
|
||||
| 枚举（Enum） | `PascalCase` | `HttpStatus` |
|
||||
| 枚举成员 | `UPPER_WITH_UNDER` | `NOT_FOUND` |
|
||||
| 函数/方法 | `camelCase` | `getUserById` |
|
||||
| 变量/参数 | `camelCase` | `userId` |
|
||||
| 常量（模块级） | `UPPER_WITH_UNDER` | `MAX_RETRY_COUNT` |
|
||||
| 私有成员 | `_camelCase` | `_cache` |
|
||||
| 泛型参数 | 单字母或 `T` 前缀 | `T`、`TItem`、`K`、`V` |
|
||||
| React 组件 | `PascalCase` | `UserCard` |
|
||||
| React Hook | `camelCase`，以 `use` 开头 | `useUserData` |
|
||||
|
||||
## 布尔值命名
|
||||
|
||||
布尔变量/属性以 `is`、`has`、`can`、`should` 开头：
|
||||
|
||||
```ts
|
||||
const isLoading = true
|
||||
const hasPermission = false
|
||||
```
|
||||
|
||||
## 避免
|
||||
|
||||
- 单字母变量（循环索引 `i`/`j` 除外）
|
||||
- 缩写（`usr`、`btn`）；优先完整单词
|
||||
- 匈牙利命名法（`strName`、`nCount`）
|
||||
- 接口名加 `I` 前缀（`IUserService`）
|
||||
@@ -0,0 +1,54 @@
|
||||
# TypeScript/JavaScript 工具链
|
||||
|
||||
本 Playbook 推荐以下工具保证代码一致性与质量：
|
||||
|
||||
- `typescript`：编译器（`tsc`）
|
||||
- `prettier`：格式化
|
||||
- `eslint`：风格检查与静态分析（配合 `@typescript-eslint`）
|
||||
- `vitest` / `jest`：测试（按项目选择）
|
||||
- `tsx` / `ts-node`：直接运行 `.ts` 文件（开发/脚本场景）
|
||||
- `node`：运行 `.js/.mjs/.cjs` 脚本
|
||||
|
||||
## 常用命令（示例）
|
||||
|
||||
安装工具（按项目实际包管理器调整）：
|
||||
|
||||
```bash
|
||||
pnpm add -D typescript prettier eslint typescript-eslint
|
||||
```
|
||||
|
||||
类型检查：
|
||||
|
||||
```bash
|
||||
tsc --noEmit
|
||||
```
|
||||
|
||||
JavaScript 检查（可选，启用 `allowJs` + `checkJs`）：
|
||||
|
||||
```bash
|
||||
tsc --noEmit --allowJs --checkJs
|
||||
```
|
||||
|
||||
格式化：
|
||||
|
||||
```bash
|
||||
prettier --write .
|
||||
```
|
||||
|
||||
Lint 检查：
|
||||
|
||||
```bash
|
||||
eslint .
|
||||
```
|
||||
|
||||
运行测试：
|
||||
|
||||
```bash
|
||||
vitest run
|
||||
# 或
|
||||
jest --ci
|
||||
```
|
||||
|
||||
## 包管理器
|
||||
|
||||
优先使用仓库已有的包管理器（`pnpm` / `npm` / `yarn`）；未经沟通不切换。
|
||||
Reference in New Issue
Block a user