@yottameta/yotta-code-quality 0.3.2 → 0.3.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +35 -0
- package/NOTICE +11 -0
- package/README.md +147 -162
- package/README.zh-CN.md +237 -0
- package/SKILL.md +1 -1
- package/package.json +5 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# 更新日志
|
|
2
|
+
|
|
3
|
+
## v0.3.4 (2026-08-29)
|
|
4
|
+
|
|
5
|
+
- 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-code-quality --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-code-quality.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
|
|
6
|
+
- 版本对齐：package.json / SKILL.md / CHANGELOG / 引擎 VERSION / 测试断言 / README 锚点 = 0.3.4。
|
|
7
|
+
- 无功能变更（仅文档与版本同步）。
|
|
8
|
+
|
|
9
|
+
## v0.3.3 (2026-08-28)
|
|
10
|
+
|
|
11
|
+
中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
|
|
12
|
+
|
|
13
|
+
- **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 工作流程 / 风险矩阵 / 目录结构 / 安装 / 使用 / 升级卸载 / FAQ / 来源与许可全流程）。
|
|
14
|
+
- **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
|
|
15
|
+
- **新增 NOTICE + .npmignore**：对齐 YottaMeta 技能家族标准（品牌声明 + npm 打包排除）。
|
|
16
|
+
- **package.json**：files 加 README.zh-CN.md；版本 0.3.2 → 0.3.3。
|
|
17
|
+
- 版本对齐：package.json / SKILL frontmatter / CHANGELOG / 文档。
|
|
18
|
+
- 边界（B 方案）：references / 测试注释不翻译；SKILL 触发描述保持中文。
|
|
19
|
+
|
|
20
|
+
## 历史版本
|
|
21
|
+
|
|
22
|
+
- **v0.3.2 (2026-08-27)**：banner 标题改「元质代码质量守护」对齐元字辈功能后缀。
|
|
23
|
+
- **v0.3.1 (2026-08-27)**：中文名定稿元质 + banner 统一。
|
|
24
|
+
- **v0.3.0 (2026-08-27)**：更名 yotta-code-quality（原 code-quality-guard 家族对齐）。
|
|
25
|
+
- **v0.2.5**：README risk matrix canonical 修正 + 做厚介绍 + 补 history 配置口径。
|
|
26
|
+
- **v0.2.4**：README 顶部加 hero banner + 可点击徽章行；banner 入 assets/。
|
|
27
|
+
- **v0.2.3**：install 自动检测/PROJECT_DIRS 兜底分支补齐 17 类规范目录。
|
|
28
|
+
- **v0.2.2**：--list 与 README 方式三一致；去除环境变量真实路径显示。
|
|
29
|
+
- **v0.2.1**：--list 不再解析本机真实路径，改显示通用默认目录。
|
|
30
|
+
- **v0.2.0**：扩充智能体表支持国内 Trae/Qwen/Comate/CodeBuddy/Kimi。
|
|
31
|
+
- **v0.1.7**：README 措辞规范（.agents 通用约定中性表述）。
|
|
32
|
+
- **v0.1.6**：方式三简化——不确定目录交给用户。
|
|
33
|
+
- **v0.1.5 / v0.1.4**：--dir 自定义目录安装说明。
|
|
34
|
+
- **v0.1.3**：新增 npx 一行安装（bin 跨平台安装器）。
|
|
35
|
+
- **v0.1.2**：安装说明重构为三种方式（npm 推荐 / install.sh / 手动复制）。
|
package/NOTICE
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# NOTICE — YottaMeta 品牌声明
|
|
2
|
+
|
|
3
|
+
「YottaMeta」「元质」「yotta-code-quality」以及本家族各技能名称（yotta-* 前缀）是 YottaMeta 的品牌与标识。
|
|
4
|
+
|
|
5
|
+
本软件以 MIT 许可证开源，任何人均可自由使用、修改与分发。若你在其基础上制作派生作品：
|
|
6
|
+
|
|
7
|
+
1. 不得继续使用 YottaMeta 或本家族名称（yotta-*、元质 等）作为派生作品的名称；
|
|
8
|
+
2. 不得暗示派生作品由 YottaMeta 官方维护、认可或与之存在关联；
|
|
9
|
+
3. 建议在派生作品中明确声明「与 YottaMeta 官方无关联」。
|
|
10
|
+
|
|
11
|
+
上游来源致谢：审查方法论蒸馏自 12 本经典软件工程著作及开源社区质量审查实践（原始方法论版权归 hyhmrright）；本技能在其基础上重写为单一自包含、跨智能体通用的版本，并增补 R7 / UX1 / 按需加载会话契约。
|
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
|
+
<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
|
|
2
|
+
|
|
1
3
|
<p align="center">
|
|
2
4
|
<img src="assets/banner.png" alt="yotta-code-quality banner" width="100%" />
|
|
3
5
|
</p>
|
|
4
6
|
|
|
5
|
-
<h1 align="center">yotta-code-quality ·
|
|
7
|
+
<h1 align="center">yotta-code-quality · 元质 (Yuanzhi)</h1>
|
|
6
8
|
|
|
7
|
-
<p align="center"
|
|
9
|
+
<p align="center">A pair-style code review skill for <b>Cursor / Codex / Claude Code / generic agents</b>. It turns "code quality review" into a reusable, configurable, methodology-backed skill: before delivery, the agent reads the code like a senior engineer, locates decay, and proposes evidence-based fixes.</p>
|
|
8
10
|
|
|
9
|
-
<p align="center">
|
|
10
|
-
一句话定位：**先诊断、再修复，只出报告不动代码。**
|
|
11
|
-
</p>
|
|
11
|
+
<p align="center">One-line positioning: <b>diagnose first, fix second — report only, never touch the code.</b></p>
|
|
12
12
|
|
|
13
13
|
<p align="center">
|
|
14
14
|
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
|
@@ -19,30 +19,30 @@
|
|
|
19
19
|
<a href="https://github.com/YottaMeta/yotta-code-quality"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
|
|
20
20
|
</p>
|
|
21
21
|
|
|
22
|
-
##
|
|
22
|
+
## Core value
|
|
23
23
|
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
24
|
+
- **Evidence-based, not gut feeling.** The methodology is distilled from 12 classic software-engineering books (Fowler's *Refactoring*, McConnell's *Code Complete*, Ousterhout's *A Philosophy of Software Design*, Evans's *Domain-Driven Design*, and more); every finding anchors to a concrete book principle or code smell.
|
|
25
|
+
- **Iron Law against noise.** Every finding must follow `Symptom → Source → Consequence → Remedy`; findings missing "Consequence" or "Remedy" are treated as noise and not reported.
|
|
26
|
+
- **Read-only by default, diagnose before fix.** Reports only, no code changes; unless you explicitly ask for `--fix` (apply Remedy).
|
|
27
|
+
- **Trackable Health Score.** Each review produces a 0–100 point-deduction index (deliberately defined as a *per-review deduction index*, not an absolute rating) supporting cross-review trend comparison.
|
|
28
|
+
- **On-demand loading, not bloated.** By mode (Quick / PR / architecture / tests / release) only the needed reference files are read, keeping the full methodology out of context.
|
|
29
|
+
- **Cross-agent + zero dependency.** A pure file-based skill, usable in Cursor / Codex / Claude Code / generic agents; no runtime dependencies.
|
|
30
30
|
|
|
31
|
-
##
|
|
31
|
+
## Why use it
|
|
32
32
|
|
|
33
|
-
|
|
|
34
|
-
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
33
|
+
| Dimension | yotta-code-quality | Note |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
| Methodology | 12 classic SE books + smells | Every finding traceable, not empirical talk |
|
|
36
|
+
| Finding structure | Iron Law four-part | Forces "consequence + remedy", avoids useless griping |
|
|
37
|
+
| Scoring | Per-review deduction index (0–100) | Explicitly "not an absolute rating", resists misreading, supports trends |
|
|
38
|
+
| Coverage | R1–R6 + T1–T6 + R7 + UX1 | Production, tests, release/supply-chain, first-paint UX |
|
|
39
|
+
| Config | `.code-quality.yaml` | Enable/disable/degrade/ignore/focus per risk, adapts to the project |
|
|
40
|
+
| Trigger | Conversational | "结对评审" / "发版前扫一眼" also hit |
|
|
41
|
+
| Extras | AGENTS-template / hooks.json | Optional; not required for the review core |
|
|
42
42
|
|
|
43
|
-
##
|
|
43
|
+
## Workflow (protocol in brief)
|
|
44
44
|
|
|
45
|
-
###
|
|
45
|
+
### Iron Law (non-negotiable)
|
|
46
46
|
|
|
47
47
|
```
|
|
48
48
|
NEVER suggest fixes before completing risk diagnosis.
|
|
@@ -50,49 +50,38 @@ EVERY finding must follow: Symptom → Source → Consequence → Remedy.
|
|
|
50
50
|
Default: report only — do NOT edit code unless the user asks to fix / passes --fix.
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
###
|
|
53
|
+
### Session contract
|
|
54
54
|
|
|
55
|
-
1.
|
|
56
|
-
2.
|
|
57
|
-
3.
|
|
58
|
-
4.
|
|
55
|
+
1. **Read-only by default** — report only, no opportunistic refactors.
|
|
56
|
+
2. **Scope discipline** — stay within the files / diff / "knife" the user names.
|
|
57
|
+
3. **Health Score is not a rating** — it is a *per-review deduction index*, not an objective score of the codebase.
|
|
58
|
+
4. **Language** — the report uses the user's language; Iron Law field names, book titles, smell names and fixed table headers (`Findings` / `Summary` / `Critical` / `Warning` / `Suggestion`) stay in English.
|
|
59
59
|
|
|
60
|
-
###
|
|
60
|
+
### On-demand loading (mode routing)
|
|
61
61
|
|
|
62
|
-
|
|
|
63
|
-
|
|
64
|
-
| **Quick** |
|
|
65
|
-
| **PR
|
|
66
|
-
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
62
|
+
| Mode | When | Read first | Read if needed |
|
|
63
|
+
|---|---|---|---|
|
|
64
|
+
| **Quick** | pasted function / < 50-line diff / quick look | `SKILL.md` + cheat sheet | `decay-risks.md` |
|
|
65
|
+
| **PR review** | PR / branch diff / ready to merge | `common.md` + `pr-review-guide.md` | `decay-risks.md` / `test-decay-risks.md` / `examples.md` |
|
|
66
|
+
| **Architecture / tech debt** | whole module / audit / `--full` | `common.md` + `decay-risks.md` + `source-coverage.md` | `editorial-extensions.md` |
|
|
67
|
+
| **Test quality** | tests / coverage / flaky | `common.md` + `test-decay-risks.md` | `examples.md` |
|
|
68
|
+
| **Release / publishing** | pre-release / updater / CSP / secrets | `common.md` + `editorial-extensions.md` | R1–R6 tables |
|
|
69
69
|
|
|
70
|
-
###
|
|
70
|
+
### Health Score
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
Base 100, deducted by `strictness`, floor 0. **Every finding is still reported**; the score is only a trend reference.
|
|
73
73
|
|
|
74
|
-
|
|
|
75
|
-
|
|
74
|
+
| Preset | Critical | Warning | Suggestion |
|
|
75
|
+
|---|---|---|---|
|
|
76
76
|
| `strict` | −20 | −8 | −2 |
|
|
77
|
-
| `balanced
|
|
77
|
+
| `balanced` (default) | −15 | −5 | −1 |
|
|
78
78
|
| `legacy-friendly` | −8 | −3 | −1 |
|
|
79
79
|
|
|
80
|
-
###
|
|
81
|
-
|
|
82
|
-
审查前会在仓库根尝试读取该文件，缺失则用默认值（全部风险开启，`balanced`）。
|
|
80
|
+
### Config (`.code-quality.yaml`)
|
|
83
81
|
|
|
84
|
-
|
|
85
|
-
|------|------|
|
|
86
|
-
| `disable` | 跳过指定风险（R1–R7 / T1–T6 / UX1） |
|
|
87
|
-
| `severity` | 强制某风险为 critical / warning / suggestion |
|
|
88
|
-
| `ignore` | 按 glob 排除（如 `**/*.generated.*`） |
|
|
89
|
-
| `focus` | 只审这些风险（不能与 `disable` 同时用） |
|
|
90
|
-
| `strictness` | strict / balanced（默认）/ legacy-friendly |
|
|
91
|
-
| `suppress` | 由 `--triage` 写入的忽略项 `{ id, reason, expires? }` |
|
|
92
|
-
| `history` | `true` 写入 `.code-quality-history.json` 趋势记录；默认关（见 History Tracking） |
|
|
82
|
+
Read from the repo root before review (single source of truth lives in references/common.md):
|
|
93
83
|
|
|
94
84
|
```yaml
|
|
95
|
-
version: 1
|
|
96
85
|
strictness: balanced
|
|
97
86
|
disable: []
|
|
98
87
|
severity: {}
|
|
@@ -103,145 +92,141 @@ suppress: []
|
|
|
103
92
|
history: false
|
|
104
93
|
```
|
|
105
94
|
|
|
106
|
-
###
|
|
107
|
-
|
|
108
|
-
- `--fix` / 「按 Remedy 修」→ 进入修复模式（按 Remedy 最小改动，并重审这些发现）
|
|
109
|
-
- `--triage` / 「逐条处理」→ 交互式忽略 / 延期（写入 `suppress`）
|
|
110
|
-
- `.code-quality.yaml` 设 `history: true` → 生成 `.code-quality-history.json` 趋势记录
|
|
95
|
+
### Optional flags
|
|
111
96
|
|
|
112
|
-
|
|
97
|
+
- `--fix` / "apply Remedy" → fix mode (minimal changes per Remedy, then re-review those findings)
|
|
98
|
+
- `--triage` / "handle one by one" → interactive ignore / defer (written to `suppress`)
|
|
99
|
+
- `.code-quality.yaml` with `history: true` → generates `.code-quality-history.json` trend records
|
|
113
100
|
|
|
114
|
-
|
|
101
|
+
> The optional extras `AGENTS-template.md` and `hooks.json` do not affect review when not installed.
|
|
115
102
|
|
|
116
|
-
|
|
117
|
-
|------|------|----------|
|
|
118
|
-
| R1 | 认知过载 Cognitive Overload | 读这段代码需要多少脑力 |
|
|
119
|
-
| R2 | 变更传播 Change Propagation | 改一处会连带坏多少无关处 |
|
|
120
|
-
| R3 | 知识重复 Knowledge Duplication | 同一决策是否散落多处 |
|
|
121
|
-
| R4 | 意外复杂度 Accidental Complexity | 是否比问题本身更复杂 |
|
|
122
|
-
| R5 | 依赖失序 Dependency Disorder | 依赖方向是否一致 |
|
|
123
|
-
| R6 | 领域模型失真 Domain Model Distortion | 是否忠实于领域语言 |
|
|
124
|
-
| T1 | 测试晦涩 Test Obscurity | 是否清楚在验证什么 |
|
|
125
|
-
| T2 | 测试脆弱 Test Brittleness | 是否被行为等价的重构打破 |
|
|
126
|
-
| T3 | 测试重复 Test Duplication | 同一场景是否无层价值地重复 |
|
|
127
|
-
| T4 | Mock 滥用 Mock Abuse | 测试是否比行为更复杂 |
|
|
128
|
-
| T5 | 覆盖幻觉 Coverage Illusion | 套件是否真保护了会出错的点 |
|
|
129
|
-
| T6 | 架构失配 Architecture Mismatch | 套件形状是否匹配风险画像 |
|
|
130
|
-
| R7 | 发布 / 供应链安全 | 明文密钥、跳过校验的 updater、产物开 DevTools |
|
|
131
|
-
| UX1 | 首屏 / 状态清晰度 | 空窗、splash 不居中、状态文案与门禁不符 |
|
|
103
|
+
## Risk matrix (canonical)
|
|
132
104
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
105
|
+
| Code | Name | Diagnosis focus |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| R1 | Cognitive Overload | How much brainpower does this code take to read |
|
|
108
|
+
| R2 | Change Propagation | How many unrelated places break when one thing changes |
|
|
109
|
+
| R3 | Knowledge Duplication | Is the same decision scattered across places |
|
|
110
|
+
| R4 | Accidental Complexity | Is it more complex than the problem itself |
|
|
111
|
+
| R5 | Dependency Disorder | Is the dependency direction consistent |
|
|
112
|
+
| R6 | Domain Model Distortion | Does it stay faithful to the domain language |
|
|
113
|
+
| T1 | Test Obscurity | Is it clear what is being verified |
|
|
114
|
+
| T2 | Test Brittleness | Broken by behavior-equivalent refactors |
|
|
115
|
+
| T3 | Test Duplication | Same scenario repeated without added value |
|
|
116
|
+
| T4 | Mock Abuse | Is the test more complex than the behavior |
|
|
117
|
+
| T5 | Coverage Illusion | Does the suite really protect the points that break |
|
|
118
|
+
| T6 | Architecture Mismatch | Does the suite shape match the risk profile |
|
|
119
|
+
| R7 | Release / supply-chain security | Plaintext secrets, updaters skipping verification, shipping with DevTools |
|
|
120
|
+
| UX1 | First-paint / state clarity | Blank windows, non-centered splash, state copy mismatching the gate |
|
|
121
|
+
|
|
122
|
+
> Detailed symptoms, book sources, severities and the "no-false-positive list" live in references/decay-risks.md, references/test-decay-risks.md and references/editorial-extensions.md. `anti-over-flag` suppresses noise warnings before reporting R1 etc., to avoid "crying wolf" fatigue.
|
|
123
|
+
|
|
124
|
+
## Directory structure
|
|
136
125
|
|
|
137
126
|
```
|
|
138
127
|
yotta-code-quality/
|
|
139
|
-
├── SKILL.md #
|
|
128
|
+
├── SKILL.md # entry + per-mode on-demand loading router
|
|
140
129
|
├── references/
|
|
141
|
-
│ ├── common.md #
|
|
142
|
-
│ ├── decay-risks.md # R1–R6
|
|
143
|
-
│ ├── test-decay-risks.md # T1–T6
|
|
144
|
-
│ ├── editorial-extensions.md # R7 / UX1 /
|
|
145
|
-
│ ├── source-coverage.md #
|
|
146
|
-
│ ├── pr-review-guide.md # 7
|
|
147
|
-
│ ├── examples.md #
|
|
148
|
-
│ ├── AGENTS-template.md #
|
|
149
|
-
│ └── hooks.json #
|
|
150
|
-
├── bin/install.js # npx
|
|
151
|
-
├── install.sh #
|
|
152
|
-
├── assets/banner.png #
|
|
130
|
+
│ ├── common.md # config / templates / scoring (single source of truth)
|
|
131
|
+
│ ├── decay-risks.md # R1–R6 production risks
|
|
132
|
+
│ ├── test-decay-risks.md # T1–T6 test risks
|
|
133
|
+
│ ├── editorial-extensions.md # R7 / UX1 / anti-over-flagging
|
|
134
|
+
│ ├── source-coverage.md # book matrix (deep mode)
|
|
135
|
+
│ ├── pr-review-guide.md # 7-step PR review
|
|
136
|
+
│ ├── examples.md # tone / scoring calibration
|
|
137
|
+
│ ├── AGENTS-template.md # optional: drop into a repo as AGENTS.md
|
|
138
|
+
│ └── hooks.json # optional: PreToolUse hooks for rm -rf / git push --force
|
|
139
|
+
├── bin/install.js # npx cross-platform installer
|
|
140
|
+
├── install.sh # one-shot install to 17 agent families
|
|
141
|
+
├── assets/banner.png # brand banner
|
|
153
142
|
└── LICENSE # MIT
|
|
154
143
|
```
|
|
155
144
|
|
|
156
|
-
##
|
|
145
|
+
## Install
|
|
157
146
|
|
|
158
|
-
|
|
147
|
+
Pick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
|
|
159
148
|
|
|
160
|
-
###
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
npx -y @yottameta/yotta-code-quality --
|
|
149
|
+
### Method 1: npm one-liner (recommended)
|
|
150
|
+
|
|
151
|
+
```text
|
|
152
|
+
# Optional China mirror: npm config set registry https://registry.npmmirror.com
|
|
153
|
+
npx -y @yottameta/yotta-code-quality --agent <agent-name> # install to the agent's default user-level skills dir
|
|
154
|
+
npx -y @yottameta/yotta-code-quality --dir <your-skills-dir> # point to the skills dir itself (e.g. ~/.codex/skills)
|
|
165
155
|
```
|
|
166
|
-
> 智能体不在预置列表？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。想手动拿文件也可 `npm pack @yottameta/yotta-code-quality` 解包后按方式二/三安装。
|
|
167
156
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
157
|
+
- `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
|
|
158
|
+
- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
|
|
159
|
+
- If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
|
|
160
|
+
|
|
161
|
+
### Method 2: git clone (developers / git available)
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
git clone https://github.com/YottaMeta/yotta-code-quality.git <your-skills-dir>/yotta-code-quality
|
|
175
165
|
```
|
|
176
|
-
> Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
|
|
177
166
|
|
|
178
|
-
###
|
|
179
|
-
把整个 `yotta-code-quality` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
|
|
167
|
+
### Method 3: GitHub Download ZIP (manual / no git)
|
|
180
168
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-code-quality\` | `.codebuddy\skills\` |
|
|
198
|
-
| Kimi | `%USERPROFILE%\.kimi\skills\yotta-code-quality\` | `.kimi\skills\` |
|
|
199
|
-
| 通用 AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-code-quality\` | `.agents\skills\` |
|
|
200
|
-
|
|
201
|
-
> Codex 默认目录若设置了环境变量 `CODEX_HOME`，以该变量为准；opencode 若设置 `XDG_CONFIG_HOME` 同理。`.agents\skills` 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，**Claude Code 与 Codex 默认不读**。不确定时用 `--dir` 指定，或让该智能体自行安装。
|
|
202
|
-
|
|
203
|
-
## 使用
|
|
204
|
-
|
|
205
|
-
对话中说「review this PR」「结对评审」「发版前扫一眼」，或直接调用 `/yotta-code-quality`。可选参数见上文「可选参数」。
|
|
206
|
-
|
|
207
|
-
### 示例：Quick 审查（粘贴一段函数）
|
|
169
|
+
On the GitHub repository `YottaMeta/yotta-code-quality`, click **Code → Download ZIP**, unzip it and put the `yotta-code-quality` folder into the agent's skills directory.
|
|
170
|
+
|
|
171
|
+
### Method 4: install.sh (multi-agent one-liner script)
|
|
172
|
+
|
|
173
|
+
```text
|
|
174
|
+
bash install.sh --agent <name> # install to the agent's default user-level directory
|
|
175
|
+
bash install.sh --dir <path> # install to the given directory
|
|
176
|
+
bash install.sh --list # list agents -> default directories
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
|
|
180
|
+
## Usage
|
|
181
|
+
|
|
182
|
+
Say "review this PR", "结对评审" or "发版前扫一眼" in conversation, or call `/yotta-code-quality` directly. Optional flags are listed above.
|
|
183
|
+
|
|
184
|
+
### Example: Quick review (pasted function)
|
|
208
185
|
|
|
209
186
|
```
|
|
210
|
-
|
|
211
|
-
|
|
187
|
+
User: 帮我看看这段函数有没有问题 / 结对评审
|
|
188
|
+
Agent: Quick mode → read SKILL + cheat sheet → output Findings + Health Score
|
|
212
189
|
```
|
|
213
190
|
|
|
214
|
-
###
|
|
191
|
+
### Example: PR review (7-step flow)
|
|
215
192
|
|
|
216
193
|
```
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
→
|
|
194
|
+
User: review this PR / ready to merge?
|
|
195
|
+
Agent: PR mode → .code-quality.yaml config → auto scope → 7 steps in pr-review-guide.md
|
|
196
|
+
→ output Findings (Critical/Warning/Suggestion sorted) + fix-order suggestion
|
|
220
197
|
```
|
|
221
198
|
|
|
222
|
-
###
|
|
199
|
+
### Example: wire into a project and configure
|
|
223
200
|
|
|
224
201
|
```bash
|
|
225
|
-
# 1.
|
|
226
|
-
# 2.
|
|
202
|
+
# 1. Put a .code-quality.yaml at the repo root (optional)
|
|
203
|
+
# 2. Trigger a review in conversation, or use --dir to install the skill into the target agent
|
|
227
204
|
```
|
|
228
205
|
|
|
229
|
-
##
|
|
206
|
+
## Upgrade / uninstall
|
|
207
|
+
|
|
208
|
+
- **Upgrade**: reinstall the latest version to overwrite — rerun the install command you used (e.g. `npx -y @yottameta/yotta-code-quality --agent <name>` or `bash install.sh --agent <name>`). Old files in the skill directory are replaced; other project files are untouched.
|
|
209
|
+
- **Uninstall**: delete the `yotta-code-quality/` folder under the target agent's skills directory.
|
|
210
|
+
- **No side effects**: the skill writes nothing outside the project; the optional trend file (`.code-quality-history.json`) is only generated when you enable `history: true`, at the repo root.
|
|
211
|
+
|
|
212
|
+
## FAQ
|
|
213
|
+
|
|
214
|
+
- **How is this different from generic code review or a linter?** Generic tools are mostly rule/style based; this skill provides "methodology grounding + Iron Law four-part + per-review deduction index", focusing on systemic decay (complexity, propagation, duplication, dependencies, domain modeling, test and release safety) rather than style nitpicking.
|
|
215
|
+
- **Does the Health Score judge code quality with a "grade"?** No. It is a *per-review deduction index*, explicitly not an absolute rating, used for cross-review trend comparison.
|
|
216
|
+
- **Will it change my code directly?** Report only by default; only with `--fix` / "apply Remedy" does it edit, and then in the smallest behavior-equivalent way.
|
|
217
|
+
- **Want to review only some risk classes?** Use `disable` / `focus` / `severity` in `.code-quality.yaml`.
|
|
218
|
+
- **Is `.agents/skills` universal?** No. Claude Code and Codex do not read it by default; use --dir when unsure.
|
|
219
|
+
- **Does it need network or dependencies?** No. It is a zero-dependency pure file skill; running only relies on the host agent's file-reading ability.
|
|
220
|
+
|
|
221
|
+
## Source & license
|
|
230
222
|
|
|
231
|
-
-
|
|
232
|
-
-
|
|
233
|
-
- **无副作用**：技能不写项目外文件；可选的历史/趋势文件（`.code-quality-history.json`）只在你开启 `history: true` 时生成，位于仓库根。
|
|
223
|
+
- **Methodology** distilled from 12 classic software-engineering books and open-source community quality-review practice (MIT). The original methodology copyright belongs to hyhmrright; this skill rewrites it into a single self-contained, cross-agent version, adding R7 / UX1 / the on-demand-loading session contract.
|
|
224
|
+
- **License:** MIT — see `LICENSE` (copyright: hyhmrright (original methodology) + YottaMeta (this packaging)).
|
|
234
225
|
|
|
235
|
-
##
|
|
226
|
+
## Changelog
|
|
236
227
|
|
|
237
|
-
|
|
238
|
-
- **健康分会算出一个"分数"来判断代码好坏吗？** 不会。它是**单次扣分指数**，且明确非绝对评级，用于横向比较趋势。
|
|
239
|
-
- **会直接改我的代码吗？** 默认只出报告；只有你要求 `--fix` 或「按 Remedy 修」才会改，且按最小行为等价方式修改。
|
|
240
|
-
- **想只审某几类风险怎么办？** 用 `.code-quality.yaml` 的 `disable` / `focus` / `severity` 即可。
|
|
241
|
-
- **`.agents/skills` 是通用目录吗？** 不是。Claude Code 与 Codex 默认不读它；不确定时用 `--dir` 指定目标目录。
|
|
242
|
-
- **需要联网或装依赖吗？** 不需要。技能是零依赖的纯文件，运行只依赖宿主智能体的读文件能力。
|
|
228
|
+
See [CHANGELOG.md](./CHANGELOG.md).
|
|
243
229
|
|
|
244
|
-
##
|
|
230
|
+
## License
|
|
245
231
|
|
|
246
|
-
|
|
247
|
-
- **许可：** MIT —— 详见 `LICENSE`（版权人：hyhmrright（原始方法论）+ YottaMeta（本打包））。
|
|
232
|
+
[MIT](./LICENSE) © hyhmrright (original methodology) + YottaMeta (this packaging). "Yuanzhi" / "yotta-code-quality" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
<p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="assets/banner.png" alt="yotta-code-quality banner" width="100%" />
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">yotta-code-quality · 元质</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">面向 **Cursor / Codex / Claude Code / 通用 Agent** 的结对代码审查技能。把「代码质量审查」沉淀为可复用、可配置、有方法论支撑的技能，让智能体在交付前像资深工程师一样通读代码、定位劣化，并给出带依据的修复方案。</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
一句话定位：**先诊断、再修复，只出报告不动代码。**
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
|
|
17
|
+
<a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
|
|
18
|
+
<a href="https://www.npmjs.com/package/@yottameta/yotta-code-quality"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-code-quality" /></a>
|
|
19
|
+
<a href="https://github.com/YottaMeta/yotta-code-quality"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-code-quality" /></a>
|
|
20
|
+
<a href="https://github.com/YottaMeta/yotta-code-quality/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-code-quality" /></a>
|
|
21
|
+
<a href="https://github.com/YottaMeta/yotta-code-quality"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
## 核心价值
|
|
25
|
+
|
|
26
|
+
- **有依据，不拍脑袋。** 方法论蒸馏自 12 本经典软件工程著作（Fowler《重构》、McConnell《代码大全》、Ousterhout《软件设计哲学》、Evans《领域驱动设计》等），每条发现都锚定到具体书籍原则或坏味道。
|
|
27
|
+
- **铁律（Iron Law）防灌水。** 每条发现必须走 `症状 → 根源 → 后果 → 修复`（Symptom → Source → Consequence → Remedy），缺「后果」或「修复」的发现一律视为噪声，不会报出来。
|
|
28
|
+
- **默认只读、先诊断后修复。** 只出审查报告，不动代码；除非你明确要求 `--fix`（按 Remedy 修）。
|
|
29
|
+
- **健康分（Health Score）可追踪。** 每次审查给出 0–100 扣分指数（刻意定义成**单次扣分指数**，而非绝对评级），支持跨次趋势比较。
|
|
30
|
+
- **按需加载，不臃肿。** 按模式（Quick / PR / 架构 / 测试 / 发布）只读需要的参考文件，避免把整套方法论塞进上下文。
|
|
31
|
+
- **跨智能体 + 零依赖。** 纯文件技能，Cursor / Codex / Claude Code / 通用 Agent 均可用；不引入任何运行时依赖。
|
|
32
|
+
|
|
33
|
+
## 核心优势
|
|
34
|
+
|
|
35
|
+
| 维度 | yotta-code-quality | 说明 |
|
|
36
|
+
|------|--------------------|------|
|
|
37
|
+
| 方法论 | 12 本经典 SE 著作 + 坏味道 | 每条发现可溯源，非经验主义空谈 |
|
|
38
|
+
| 发现结构 | Iron Law 四段式 | 强制带「后果 + 修复」，避免无效吐槽 |
|
|
39
|
+
| 评分 | 单次扣分指数（0–100） | 明确"非绝对评级"，防误读、支持趋势 |
|
|
40
|
+
| 覆盖面 | R1–R6 + T1–T6 + R7 + UX1 | 生产、测试、发布/供应链、首屏体验全覆盖 |
|
|
41
|
+
| 配置 | `.code-quality.yaml` | 按风险开关/降级/忽略/聚焦，自适应项目 |
|
|
42
|
+
| 触发 | 对话即触发 | 「结对评审」「发版前扫一眼」也能命中 |
|
|
43
|
+
| 附加件 | AGENTS-template / hooks.json | 可选，不装不影响审查核心 |
|
|
44
|
+
|
|
45
|
+
## 工作流程（协议详解）
|
|
46
|
+
|
|
47
|
+
### 铁律（不可协商）
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
NEVER suggest fixes before completing risk diagnosis.
|
|
51
|
+
EVERY finding must follow: Symptom → Source → Consequence → Remedy.
|
|
52
|
+
Default: report only — do NOT edit code unless the user asks to fix / passes --fix.
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### 会话契约
|
|
56
|
+
|
|
57
|
+
1. **默认只读**：只出报告，不做顺手重构。
|
|
58
|
+
2. **范围纪律**：用户点名文件 / diff /「刀子」，就留在该范围内。
|
|
59
|
+
3. **健康分不是评级**：它是**单次扣分指数**，不是对代码库的客观打分。
|
|
60
|
+
4. **语言**：报告用用户语言；Iron Law 字段名、书名、坏味道名、固定表头（`Findings` / `Summary` / `Critical` / `Warning` / `Suggestion`）保留英文。
|
|
61
|
+
|
|
62
|
+
### 按需加载（Mode 路由）
|
|
63
|
+
|
|
64
|
+
| 模式 | 何时使用 | 先读 | 需要时再读 |
|
|
65
|
+
|------|----------|------|-----------|
|
|
66
|
+
| **Quick** | 粘贴函数 / < 50 行 diff / 扫一眼 | `SKILL.md` + 速查 | `decay-risks.md` |
|
|
67
|
+
| **PR 审查** | PR / 分支 diff / ready to merge | `common.md` + `pr-review-guide.md` | `decay-risks.md` / `test-decay-risks.md` / `examples.md` |
|
|
68
|
+
| **架构 / 技术债** | 整模块 / 审计 / `--full` | `common.md` + `decay-risks.md` + `source-coverage.md` | `editorial-extensions.md` |
|
|
69
|
+
| **测试质量** | 测试 / 覆盖率 / flaky | `common.md` + `test-decay-risks.md` | `examples.md` |
|
|
70
|
+
| **发布 / 上架** | 发版前 / updater / CSP / 密钥 | `common.md` + `editorial-extensions.md` | R1–R6 表 |
|
|
71
|
+
|
|
72
|
+
### 评分（Health Score）
|
|
73
|
+
|
|
74
|
+
基础 100 分，按 `strictness` 扣分，下限 0。**仍会报告每一条发现**，评分只是趋势参考。
|
|
75
|
+
|
|
76
|
+
| 预设 | Critical | Warning | Suggestion |
|
|
77
|
+
|------|----------|---------|------------|
|
|
78
|
+
| `strict` | −20 | −8 | −2 |
|
|
79
|
+
| `balanced`（默认） | −15 | −5 | −1 |
|
|
80
|
+
| `legacy-friendly` | −8 | −3 | −1 |
|
|
81
|
+
|
|
82
|
+
### 配置（`.code-quality.yaml`）
|
|
83
|
+
|
|
84
|
+
审查前会在仓库根尝试读取该文件，缺失则用默认值（全部风险开启，`balanced`）。
|
|
85
|
+
|
|
86
|
+
| 字段 | 作用 |
|
|
87
|
+
|------|------|
|
|
88
|
+
| `disable` | 跳过指定风险（R1–R7 / T1–T6 / UX1） |
|
|
89
|
+
| `severity` | 强制某风险为 critical / warning / suggestion |
|
|
90
|
+
| `ignore` | 按 glob 排除（如 `**/*.generated.*`） |
|
|
91
|
+
| `focus` | 只审这些风险（不能与 `disable` 同时用） |
|
|
92
|
+
| `strictness` | strict / balanced（默认）/ legacy-friendly |
|
|
93
|
+
| `suppress` | 由 `--triage` 写入的忽略项 `{ id, reason, expires? }` |
|
|
94
|
+
| `history` | `true` 写入 `.code-quality-history.json` 趋势记录；默认关（见 History Tracking） |
|
|
95
|
+
|
|
96
|
+
```yaml
|
|
97
|
+
version: 1
|
|
98
|
+
strictness: balanced
|
|
99
|
+
disable: []
|
|
100
|
+
severity: {}
|
|
101
|
+
ignore:
|
|
102
|
+
- "**/*.generated.*"
|
|
103
|
+
- "**/node_modules/**"
|
|
104
|
+
suppress: []
|
|
105
|
+
history: false
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### 可选参数
|
|
109
|
+
|
|
110
|
+
- `--fix` / 「按 Remedy 修」→ 进入修复模式（按 Remedy 最小改动，并重审这些发现）
|
|
111
|
+
- `--triage` / 「逐条处理」→ 交互式忽略 / 延期（写入 `suppress`）
|
|
112
|
+
- `.code-quality.yaml` 设 `history: true` → 生成 `.code-quality-history.json` 趋势记录
|
|
113
|
+
|
|
114
|
+
> 附加件 `AGENTS-template.md` 与 `hooks.json` 不装也不影响审查。
|
|
115
|
+
|
|
116
|
+
## 风险矩阵（canonical）
|
|
117
|
+
|
|
118
|
+
| 代码 | 名称 | 诊断要点 |
|
|
119
|
+
|------|------|----------|
|
|
120
|
+
| R1 | 认知过载 Cognitive Overload | 读这段代码需要多少脑力 |
|
|
121
|
+
| R2 | 变更传播 Change Propagation | 改一处会连带坏多少无关处 |
|
|
122
|
+
| R3 | 知识重复 Knowledge Duplication | 同一决策是否散落多处 |
|
|
123
|
+
| R4 | 意外复杂度 Accidental Complexity | 是否比问题本身更复杂 |
|
|
124
|
+
| R5 | 依赖失序 Dependency Disorder | 依赖方向是否一致 |
|
|
125
|
+
| R6 | 领域模型失真 Domain Model Distortion | 是否忠实于领域语言 |
|
|
126
|
+
| T1 | 测试晦涩 Test Obscurity | 是否清楚在验证什么 |
|
|
127
|
+
| T2 | 测试脆弱 Test Brittleness | 是否被行为等价的重构打破 |
|
|
128
|
+
| T3 | 测试重复 Test Duplication | 同一场景是否无层价值地重复 |
|
|
129
|
+
| T4 | Mock 滥用 Mock Abuse | 测试是否比行为更复杂 |
|
|
130
|
+
| T5 | 覆盖幻觉 Coverage Illusion | 套件是否真保护了会出错的点 |
|
|
131
|
+
| T6 | 架构失配 Architecture Mismatch | 套件形状是否匹配风险画像 |
|
|
132
|
+
| R7 | 发布 / 供应链安全 | 明文密钥、跳过校验的 updater、产物开 DevTools |
|
|
133
|
+
| UX1 | 首屏 / 状态清晰度 | 空窗、splash 不居中、状态文案与门禁不符 |
|
|
134
|
+
|
|
135
|
+
> 详细症状、书源、严重度与「不误报清单」见 `references/decay-risks.md`、`references/test-decay-risks.md`、`references/editorial-extensions.md`。`anti-over-flag` 在报 R1 等前先抑制噪声告警，避免「狼来了」式疲劳。
|
|
136
|
+
|
|
137
|
+
## 目录结构
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
yotta-code-quality/
|
|
141
|
+
├── SKILL.md # 入口 + 按模式按需加载的路由
|
|
142
|
+
├── references/
|
|
143
|
+
│ ├── common.md # 配置 / 模板 / 评分（单一信息源）
|
|
144
|
+
│ ├── decay-risks.md # R1–R6 生产风险
|
|
145
|
+
│ ├── test-decay-risks.md # T1–T6 测试风险
|
|
146
|
+
│ ├── editorial-extensions.md # R7 / UX1 / 防过度告警
|
|
147
|
+
│ ├── source-coverage.md # 书籍矩阵（深度模式）
|
|
148
|
+
│ ├── pr-review-guide.md # 7 步 PR 审查
|
|
149
|
+
│ ├── examples.md # 语气 / 评分校准
|
|
150
|
+
│ ├── AGENTS-template.md # 可选：丢进仓库当 AGENTS.md 强制规范
|
|
151
|
+
│ └── hooks.json # 可选：PreToolUse 拦截 rm -rf / git push --force
|
|
152
|
+
├── bin/install.js # npx 跨平台安装器
|
|
153
|
+
├── install.sh # 一键安装到 17 类智能体（含国内 Trae/Qwen/Comate/CodeBuddy/Kimi）
|
|
154
|
+
├── assets/banner.png # 品牌头图
|
|
155
|
+
└── LICENSE # MIT
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## 安装
|
|
159
|
+
|
|
160
|
+
以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
|
|
161
|
+
|
|
162
|
+
### 方式一：npm 一行装（推荐）
|
|
163
|
+
|
|
164
|
+
```text
|
|
165
|
+
# 可选国内加速：npm config set registry https://registry.npmmirror.com
|
|
166
|
+
npx -y @yottameta/yotta-code-quality --agent <智能体名称> # 装到指定智能体默认用户级技能目录
|
|
167
|
+
npx -y @yottameta/yotta-code-quality --dir <智能体的技能目录> # 指到技能目录本身（如 ~/.codex/skills）
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
- `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
|
|
171
|
+
- `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
|
|
172
|
+
- npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
|
|
173
|
+
|
|
174
|
+
### 方式二：git clone（开发者 / 有 git 环境）
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
git clone https://github.com/YottaMeta/yotta-code-quality.git <智能体的技能目录>/yotta-code-quality
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
|
|
181
|
+
|
|
182
|
+
在 GitHub 仓库 `YottaMeta/yotta-code-quality` 点 **Code → Download ZIP**，解压后把 `yotta-code-quality` 文件夹放进智能体技能目录。
|
|
183
|
+
|
|
184
|
+
### 方式四：install.sh（多智能体一键脚本）
|
|
185
|
+
|
|
186
|
+
```text
|
|
187
|
+
bash install.sh --agent <name> # 装到指定智能体默认用户级目录
|
|
188
|
+
bash install.sh --dir <path> # 装到指定目录
|
|
189
|
+
bash install.sh --list # 列出智能体 -> 默认目录
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
|
|
193
|
+
## 使用
|
|
194
|
+
|
|
195
|
+
对话中说「review this PR」「结对评审」「发版前扫一眼」，或直接调用 `/yotta-code-quality`。可选参数见上文「可选参数」。
|
|
196
|
+
|
|
197
|
+
### 示例：Quick 审查（粘贴一段函数）
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
用户：帮我看看这段函数有没有问题 / 结对评审
|
|
201
|
+
智能体：按 Quick 模式 → 读 SKILL + 速查 → 输出 Findings + Health Score
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
### 示例：PR 审查（带 7 步流程）
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
用户：review this PR / ready to merge?
|
|
208
|
+
智能体：按 PR 模式 → .code-quality.yaml 配置 → 自动 scope → 走 pr-review-guide.md 7 步
|
|
209
|
+
→ 输出 Findings（Critical/Warning/Suggestion 排序）+ 修复顺序建议
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### 示例：接入项目并配置
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
# 1. 在仓库根放一个 .code-quality.yaml（可选）
|
|
216
|
+
# 2. 对话触发审查，或用 --dir 把技能装到目标智能体
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
## 升级与卸载
|
|
220
|
+
|
|
221
|
+
- **升级**：重新安装最新版覆盖即可——重跑你用的安装命令（如 `npx -y @yottameta/yotta-code-quality --agent <name>` 或 `bash install.sh --agent <name>`）。技能目录内旧文件会被替换；不影响项目中其他文件。
|
|
222
|
+
- **卸载**：删除目标智能体 skills 目录下的 `yotta-code-quality/` 文件夹即可。
|
|
223
|
+
- **无副作用**：技能不写项目外文件；可选的历史/趋势文件（`.code-quality-history.json`）只在你开启 `history: true` 时生成，位于仓库根。
|
|
224
|
+
|
|
225
|
+
## 常见问题（FAQ）
|
|
226
|
+
|
|
227
|
+
- **它和通用 code review 或 linter 有何区别？** 通用工具多基于规则/风格；本技能提供「方法论依据 + 铁律四段式 + 单次扣分指数」，聚焦系统性劣化（复杂度、传播、重复、依赖、领域建模、测试与发布安全），而非风格挑刺。
|
|
228
|
+
- **健康分会算出一个"分数"来判断代码好坏吗？** 不会。它是**单次扣分指数**，且明确非绝对评级，用于横向比较趋势。
|
|
229
|
+
- **会直接改我的代码吗？** 默认只出报告；只有你要求 `--fix` 或「按 Remedy 修」才会改，且按最小行为等价方式修改。
|
|
230
|
+
- **想只审某几类风险怎么办？** 用 `.code-quality.yaml` 的 `disable` / `focus` / `severity` 即可。
|
|
231
|
+
- **`.agents/skills` 是通用目录吗？** 不是。Claude Code 与 Codex 默认不读它；不确定时用 `--dir` 指定目标目录。
|
|
232
|
+
- **需要联网或装依赖吗？** 不需要。技能是零依赖的纯文件，运行只依赖宿主智能体的读文件能力。
|
|
233
|
+
|
|
234
|
+
## 来源与许可
|
|
235
|
+
|
|
236
|
+
- **方法论**蒸馏自 12 本经典软件工程著作及开源社区质量审查实践（MIT）；原始方法论版权归 hyhmrright，本技能在其基础上重写为单一自包含、跨智能体通用的版本，并增补 R7 / UX1 / 按需加载会话契约。
|
|
237
|
+
- **许可：** MIT —— 详见 `LICENSE`（版权人：hyhmrright（原始方法论）+ YottaMeta（本打包））。
|
package/SKILL.md
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yottameta/yotta-code-quality",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.4",
|
|
4
4
|
"description": "Pair-style code quality reviewer: twelve book-grounded decay risks (R1-R6, T1-T6) plus release-safety and first-paint UX checks; Iron Law findings (Symptom -> Source -> Consequence -> Remedy) and 0-100 Health Score.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"keywords": [
|
|
@@ -17,7 +17,10 @@
|
|
|
17
17
|
"install.sh",
|
|
18
18
|
"references",
|
|
19
19
|
"bin",
|
|
20
|
-
"assets"
|
|
20
|
+
"assets",
|
|
21
|
+
"README.zh-CN.md",
|
|
22
|
+
"NOTICE",
|
|
23
|
+
"CHANGELOG.md"
|
|
21
24
|
],
|
|
22
25
|
"repository": {
|
|
23
26
|
"type": "git",
|