moluoxixi-ai-rules 0.1.0

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.
Files changed (49) hide show
  1. package/LICENSE +21 -0
  2. package/README-zh.md +246 -0
  3. package/README.md +246 -0
  4. package/dist/constants/hosts.d.ts +34 -0
  5. package/dist/constants/hosts.js +71 -0
  6. package/dist/constants/skills.d.ts +91 -0
  7. package/dist/constants/skills.js +156 -0
  8. package/dist/scripts/cli.d.ts +2 -0
  9. package/dist/scripts/cli.js +145 -0
  10. package/dist/scripts/host-setup.d.ts +2 -0
  11. package/dist/scripts/host-setup.js +147 -0
  12. package/dist/scripts/lib/install.d.ts +78 -0
  13. package/dist/scripts/lib/install.js +367 -0
  14. package/dist/scripts/lib/links.d.ts +8 -0
  15. package/dist/scripts/lib/links.js +18 -0
  16. package/dist/scripts/lib/skill-projection.d.ts +14 -0
  17. package/dist/scripts/lib/skill-projection.js +54 -0
  18. package/dist/scripts/lib/tool.d.ts +40 -0
  19. package/dist/scripts/lib/tool.js +125 -0
  20. package/dist/scripts/lib/vendor-sync.d.ts +3 -0
  21. package/dist/scripts/lib/vendor-sync.js +129 -0
  22. package/dist/scripts/lib/vendors.d.ts +29 -0
  23. package/dist/scripts/lib/vendors.js +155 -0
  24. package/dist/scripts/lib/verify.d.ts +7 -0
  25. package/dist/scripts/lib/verify.js +84 -0
  26. package/dist/scripts/sync-vendors.d.ts +1 -0
  27. package/dist/scripts/sync-vendors.js +173 -0
  28. package/dist/scripts/verify-host.d.ts +2 -0
  29. package/dist/scripts/verify-host.js +42 -0
  30. package/package.json +60 -0
  31. package/rules/AGENTS.md +30 -0
  32. package/skills/skill-validation-standard/SKILL.md +45 -0
  33. package/skills/skill-validation-standard/__test__/verify-rules.test.ts +108 -0
  34. package/skills/skill-validation-standard/scripts/verify-rules.mjs +186 -0
  35. package/skills/workflow/frontend-code-standard/SKILL.md +58 -0
  36. package/skills/workflow/frontend-code-standard/__test__/verify-rules.test.ts +227 -0
  37. package/skills/workflow/frontend-code-standard/scripts/verify-rules.mjs +537 -0
  38. package/skills/workflow/java-code-standard/SKILL.md +58 -0
  39. package/skills/workflow/java-code-standard/__test__/verify-rules.test.ts +48 -0
  40. package/skills/workflow/java-code-standard/scripts/verify-rules.mjs +215 -0
  41. package/skills/workflow/nestjs-code-standard/SKILL.md +61 -0
  42. package/skills/workflow/nestjs-code-standard/__test__/verify-rules.test.ts +48 -0
  43. package/skills/workflow/nestjs-code-standard/scripts/verify-rules.mjs +219 -0
  44. package/skills/workflow/node-code-standard/SKILL.md +62 -0
  45. package/skills/workflow/node-code-standard/__test__/verify-rules.test.ts +48 -0
  46. package/skills/workflow/node-code-standard/scripts/verify-rules.mjs +213 -0
  47. package/skills/workflow/project-knowledge-read-workflow/SKILL.md +102 -0
  48. package/skills/workflow/project-knowledge-refresh-workflow/SKILL.md +149 -0
  49. package/skills/workflow/software-development-workflow/SKILL.md +85 -0
package/package.json ADDED
@@ -0,0 +1,60 @@
1
+ {
2
+ "name": "moluoxixi-ai-rules",
3
+ "type": "module",
4
+ "version": "0.1.0",
5
+ "description": "Personal AI workflow distribution built on top of superpowers.",
6
+ "license": "MIT",
7
+ "repository": "https://github.com/moluoxixi/AIRules",
8
+ "bin": {
9
+ "airules": "./dist/scripts/cli.js"
10
+ },
11
+ "publishConfig": {
12
+ "registry": "https://registry.npmjs.org/"
13
+ },
14
+ "files": [
15
+ "LICENSE",
16
+ "README-zh.md",
17
+ "README.md",
18
+ "dist",
19
+ "rules",
20
+ "skills"
21
+ ],
22
+ "scripts": {
23
+ "airules": "tsx scripts/cli.ts",
24
+ "build": "tsc -p tsconfig.build.json",
25
+ "prepare": "husky",
26
+ "prepack": "npm run build",
27
+ "lint": "eslint --fix",
28
+ "lint:check": "eslint .",
29
+ "setup": "tsx scripts/cli.ts sync",
30
+ "sync": "tsx scripts/cli.ts sync --host all",
31
+ "rules:install": "tsx scripts/cli.ts sync",
32
+ "pretest": "npx tsx scripts/sync-vendors.ts",
33
+ "test": "vitest run",
34
+ "typecheck": "tsc --noEmit",
35
+ "coverage": "vitest run --coverage"
36
+ },
37
+ "dependencies": {
38
+ "kleur": "^4.1.5"
39
+ },
40
+ "devDependencies": {
41
+ "@antfu/eslint-config": "^8.2.0",
42
+ "@commitlint/cli": "^21.0.1",
43
+ "@commitlint/config-conventional": "^21.0.1",
44
+ "@types/node": "^25.9.1",
45
+ "@vitest/coverage-v8": "4.1.4",
46
+ "eslint": "^10.2.1",
47
+ "eslint-plugin-format": "^2.0.1",
48
+ "husky": "^9.1.7",
49
+ "jiti": "^2.6.1",
50
+ "lint-staged": "^16.4.0",
51
+ "tsx": "^4.21.0",
52
+ "typescript": "^6.0.2",
53
+ "vitest": "^4.1.4"
54
+ },
55
+ "lint-staged": {
56
+ "*.{vue,jsx,tsx,js,ts,mjs}": [
57
+ "eslint --fix"
58
+ ]
59
+ }
60
+ }
@@ -0,0 +1,30 @@
1
+ # AIRules
2
+
3
+ ## 核心规则
4
+
5
+ - 禁止冗余校验:内部已由类型、调用契约或上游边界校验保证的数据,不再重复写 `typeof`、`instanceof`、正则格式检查、`.trim()`、空值判断、`readText` 包装等防御式运行时校验。
6
+ - 允许边界校验:CLI 参数、用户输入、环境变量、配置文件、外部接口和文件系统读取结果进入系统边界时,必须对必需字段做显式校验;校验失败应抛出带上下文的错误。
7
+ - 禁止错误绕行式空值处理:不得用空值判断把缺失的必需数据静默跳过、替换为默认值、降级为警告或伪装为成功。
8
+ - 禁止错误绕行:不得以任何方式绕过、隐藏、降级或静默处理错误,包括但不限于:将错误转为警告、用默认值替代失败结果、捕获后不重新抛出、用条件判断跳过出错路径、将异常状态标记为正常状态。错误必须显式暴露给调用方或用户。
9
+ - 禁止错误回退:不得通过缓存结果、降级路径、伪造成功响应、自动跳过步骤或吞掉异常掩盖真实失败;如需捕获错误,只能补充上下文、清理资源或转换为等价失败语义,并重新抛出或显式返回错误。
10
+ - 禁止 lint 绕行:不得通过 `--no-verify`、关闭或弱化 lint 规则、扩大 ignore、跳过 lint 脚本、改跑不覆盖目标文件的命令、删除断言或伪造检查结果来绕过 lint 失败;失败必须暴露并修复,确认为无关历史债务时只能明确标记状态和范围。
11
+ - 优先使用成熟库:遇到解析、校验、日期、加密、图表、编辑器、状态机、测试工具等通用能力时,优先使用项目已有依赖或成熟库;若手写实现成本或风险更高,必须向用户推荐成熟方案并说明取舍。
12
+ - 回复、中间说明、计划、代码注释和文档默认使用用户本次消息的主要语言;命令、代码标识符、日志原文、错误原文、API/库名、专有名词和现有文件引用可保留原语言。
13
+ - 生成的代码必须包含清晰、专业的注释,确保开发者能零成本理解代码的设计意图、API 契约和业务逻辑。
14
+
15
+ ## 交付验证
16
+
17
+ - AI 代理完成修改后,质量检查必须按任务场景和风险分级执行;最终回复必须说明实际命令、结果、未执行项和原因。
18
+ - Superpowers、并行子代理、系统化调试、TDD、全量测试、coverage 和构建不得默认触发;只有任务复杂度、风险或用户明确要求匹配时启用。
19
+ - 优先使用项目现有脚本和配置;缺少脚本、配置、依赖或测试入口时必须标记为 `MISSING`,不得伪造成已通过。
20
+ - 覆盖率优先采用项目阈值;无阈值时参考 statements、branches、functions、lines 均不低于 80%,新增或修改逻辑尽量达到 90%+ 有意义覆盖。
21
+ - 覆盖率不足时必须补充有效测试或报告原因;不得降低阈值、排除关键文件、删除断言或编写无意义测试来通过检查。
22
+ - 检查状态统一使用 `PASS`、`FAIL`、`MISSING`、`NOT RUN`、`N/A`,不得把失败、缺失、不相关或未运行转写成通过。
23
+
24
+ ## 并行子代理
25
+
26
+ - 当任务包含两个或更多相互独立的问题域、模块、测试失败、文件范围或研究方向时,先评估是否并行;适合并行时拆成写入范围不重叠、可独立验证的子任务。
27
+ - 复杂任务中,负责生产代码生成、Bug 修复、重构、迁移或自动修改文件的子代理,必须使用当前可用的高质量 coding 模型,默认不低于 `gpt-5.5` + `high` reasoning。
28
+ - 只读研究、日志收集、测试执行或失败复现类子任务可使用更低成本模型,但不得产出未经主代理复核的代码修改。
29
+ - 主代理保留协调职责:判断依赖关系、分配所有权、整合结果、处理冲突,并在最终交付前运行必要质量检查。
30
+ - 若不启用多子代理,必须能说明原因,例如强顺序依赖、共享状态、同一文件强耦合或拆分成本高于收益。
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: skill-validation-standard
3
+ description: 校验 Claude/Codex skill 的 YAML frontmatter。用于创建、修改或评审 skill 后确认 SKILL.md 元数据格式正确。
4
+ ---
5
+
6
+ # Skill 校验流程
7
+
8
+ ## 校验范围
9
+
10
+ 本 Skill 只检查 `SKILL.md` 文件本身的 YAML frontmatter、目录命名契约和文件长度。Markdown 标题、正文结构、外部文件、目录和辅助脚本不在本规范范围内。
11
+
12
+ ## 执行步骤
13
+
14
+ 1. 读取目标 skill 根目录下的 `SKILL.md`。
15
+ 2. 检查文件是否以 YAML frontmatter 开始,并使用 `---` 正确闭合。
16
+ 3. 检查 frontmatter 至少包含非空 `name`。
17
+ 4. 检查 `name` 与 skill 文件夹名称一致。
18
+ 5. 若存在 `description`,检查它必须说明触发时机或触发场景。
19
+ 6. 检查 `SKILL.md` 不超过 500 行。
20
+ 7. 汇总 `PASS` / `FAIL` 结果,`FAIL` 项必须修复。
21
+
22
+ ## 判定标准
23
+
24
+ ### YAML frontmatter
25
+
26
+ | # | 检查项 | FAIL 条件 |
27
+ |---|--------|-----------|
28
+ | Y1 | `SKILL.md` 以 YAML frontmatter 开头 | 文件不是以 `---` 开头 |
29
+ | Y2 | frontmatter 正确闭合 | 找不到第二个 `---` 分隔符 |
30
+ | Y3 | frontmatter 行是 `key: value` 结构 | 非空行缺少 key、冒号或 value |
31
+ | Y4 | `name` 存在 | `name` 缺失或为空 |
32
+ | Y5 | `name` 与 skill 文件夹名称一致 | `name` 不等于当前目录名 |
33
+ | Y6 | 若存在 `description`,必须描述触发时机或触发场景 | `description` 泛泛描述能力而不说明何时触发 |
34
+
35
+ ### 文件长度
36
+
37
+ | # | 检查项 | FAIL 条件 |
38
+ |---|--------|-----------|
39
+ | L1 | `SKILL.md` 不超过 500 行 | 行数大于 500 |
40
+
41
+ ## 命令
42
+
43
+ ```bash
44
+ node skills/skill-validation-standard/scripts/verify-rules.mjs --root path/to/skill
45
+ ```
@@ -0,0 +1,108 @@
1
+ import assert from 'node:assert/strict'
2
+ import { execFileSync, spawnSync } from 'node:child_process'
3
+ import fs from 'node:fs'
4
+ import os from 'node:os'
5
+ import path from 'node:path'
6
+ import process from 'node:process'
7
+ import { fileURLToPath } from 'node:url'
8
+ import { it } from 'vitest'
9
+
10
+ const __dirname = path.dirname(fileURLToPath(import.meta.url))
11
+ const skillRoot = path.resolve(__dirname, '..')
12
+ const projectRoot = path.resolve(skillRoot, '..', '..')
13
+ const scriptPath = path.join(skillRoot, 'scripts', 'verify-rules.mjs')
14
+
15
+ function runScript(...args: string[]) {
16
+ return execFileSync(process.execPath, [scriptPath, ...args], {
17
+ cwd: projectRoot,
18
+ encoding: 'utf8',
19
+ })
20
+ }
21
+
22
+ function writeSkill(root: string, lines: string[]) {
23
+ fs.mkdirSync(root, { recursive: true })
24
+ fs.writeFileSync(path.join(root, 'SKILL.md'), lines.join('\n'))
25
+ }
26
+
27
+ it('verify-rules 只校验 YAML、目录名和长度', () => {
28
+ assert.match(runScript(), /PASS skill YAML frontmatter is valid/)
29
+
30
+ const validSkillRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'airules-valid-skill-')), 'minimal-skill')
31
+ writeSkill(validSkillRoot, [
32
+ '---',
33
+ 'name: minimal-skill',
34
+ '---',
35
+ ])
36
+ assert.match(runScript('--root', validSkillRoot), /PASS skill YAML frontmatter is valid/)
37
+
38
+ const validDescribedSkillRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'airules-valid-described-skill-')), 'described-skill')
39
+ writeSkill(validDescribedSkillRoot, [
40
+ '---',
41
+ 'name: described-skill',
42
+ 'description: 用于创建、修改或评审 skill 时校验 YAML。',
43
+ '---',
44
+ ])
45
+ assert.match(runScript('--root', validDescribedSkillRoot), /PASS skill YAML frontmatter is valid/)
46
+
47
+ const invalidSkillRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'airules-invalid-skill-')), 'broken-skill')
48
+ writeSkill(invalidSkillRoot, [
49
+ '---',
50
+ 'name: broken-skill',
51
+ 'description: 缺少结束分隔符。',
52
+ '',
53
+ '# Broken Skill',
54
+ ])
55
+ const invalidResult = spawnSync(process.execPath, [
56
+ scriptPath,
57
+ '--root',
58
+ invalidSkillRoot,
59
+ ], { cwd: projectRoot, encoding: 'utf8' })
60
+ assert.notEqual(invalidResult.status, 0)
61
+ assert.match(invalidResult.stdout, /缺少 YAML frontmatter 结束标记/)
62
+
63
+ const mismatchedNameRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'airules-mismatched-skill-')), 'folder-name')
64
+ writeSkill(mismatchedNameRoot, [
65
+ '---',
66
+ 'name: frontmatter-name',
67
+ 'description: 名称与文件夹不一致。',
68
+ '---',
69
+ ])
70
+ const mismatchedNameResult = spawnSync(process.execPath, [
71
+ scriptPath,
72
+ '--root',
73
+ mismatchedNameRoot,
74
+ ], { cwd: projectRoot, encoding: 'utf8' })
75
+ assert.notEqual(mismatchedNameResult.status, 0)
76
+ assert.match(mismatchedNameResult.stdout, /frontmatter name 必须等于目录名:folder-name/)
77
+
78
+ const vagueDescriptionRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'airules-vague-description-skill-')), 'vague-description-skill')
79
+ writeSkill(vagueDescriptionRoot, [
80
+ '---',
81
+ 'name: vague-description-skill',
82
+ 'description: 这是一个很有用的 skill。',
83
+ '---',
84
+ ])
85
+ const vagueDescriptionResult = spawnSync(process.execPath, [
86
+ scriptPath,
87
+ '--root',
88
+ vagueDescriptionRoot,
89
+ ], { cwd: projectRoot, encoding: 'utf8' })
90
+ assert.notEqual(vagueDescriptionResult.status, 0)
91
+ assert.match(vagueDescriptionResult.stdout, /frontmatter description 必须说明触发时机或触发场景/)
92
+
93
+ const oversizedSkillRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'airules-oversized-skill-')), 'oversized-skill')
94
+ writeSkill(oversizedSkillRoot, [
95
+ '---',
96
+ 'name: oversized-skill',
97
+ 'description: 用于校验超过 500 行的 skill。',
98
+ '---',
99
+ ...Array.from({ length: 501 }, (_, index) => `line ${index + 1}`),
100
+ ])
101
+ const oversizedSkillResult = spawnSync(process.execPath, [
102
+ scriptPath,
103
+ '--root',
104
+ oversizedSkillRoot,
105
+ ], { cwd: projectRoot, encoding: 'utf8' })
106
+ assert.notEqual(oversizedSkillResult.status, 0)
107
+ assert.match(oversizedSkillResult.stdout, /SKILL\.md 超过 500 行/)
108
+ })
@@ -0,0 +1,186 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Skill 最小校验脚本:只检查 SKILL.md 的 YAML frontmatter。
4
+ */
5
+ import fs from 'node:fs'
6
+ import path from 'node:path'
7
+ import { fileURLToPath } from 'node:url'
8
+
9
+ const ownRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
10
+ const MAX_SKILL_LINES = 500
11
+ const DESCRIPTION_TRIGGER_PATTERN = /(用于|适用于|当|在.+时|开始前|完成后|明确要求|Use when|Triggers? on|when)/i
12
+ const errors = []
13
+
14
+ function fail(message) {
15
+ errors.push(message)
16
+ console.log(`FAIL ${message}`)
17
+ }
18
+
19
+ function pass(message) {
20
+ console.log(`PASS ${message}`)
21
+ }
22
+
23
+ function parseArgs(args) {
24
+ for (let index = 0; index < args.length; index++) {
25
+ if (args[index] === '--root') {
26
+ index++
27
+ continue
28
+ }
29
+
30
+ fail(`未知参数:${args[index]}`)
31
+ }
32
+
33
+ const rootIndex = args.indexOf('--root')
34
+ const rootValue = args[rootIndex + 1]
35
+ if (rootIndex !== -1 && (!rootValue || rootValue.startsWith('--'))) {
36
+ fail('参数 --root 必须提供值')
37
+ return { root: ownRoot }
38
+ }
39
+
40
+ const root = rootIndex === -1
41
+ ? ownRoot
42
+ : path.resolve(process.cwd(), rootValue)
43
+
44
+ return { root }
45
+ }
46
+
47
+ function readSkillFile(root) {
48
+ const skillPath = path.join(root, 'SKILL.md')
49
+ if (!fs.existsSync(skillPath)) {
50
+ fail('缺少 SKILL.md')
51
+ return ''
52
+ }
53
+
54
+ pass('SKILL.md exists')
55
+ return fs.readFileSync(skillPath, 'utf8').replace(/\r\n/g, '\n')
56
+ }
57
+
58
+ function checkLineCount(content) {
59
+ const lineCount = content.endsWith('\n')
60
+ ? content.split('\n').length - 1
61
+ : content.split('\n').length
62
+
63
+ if (lineCount > MAX_SKILL_LINES) {
64
+ fail(`SKILL.md 超过 ${MAX_SKILL_LINES} 行:${lineCount}`)
65
+ return
66
+ }
67
+
68
+ pass('SKILL.md line count valid')
69
+ }
70
+
71
+ function splitFrontmatter(content) {
72
+ if (!content.startsWith('---\n')) {
73
+ fail('SKILL.md 必须以 YAML frontmatter 开头')
74
+ return undefined
75
+ }
76
+
77
+ const closedBeforeContent = content.indexOf('\n---\n', 4)
78
+ const closedAtEnd = content.endsWith('\n---') ? content.length - 4 : -1
79
+ const end = closedBeforeContent === -1 ? closedAtEnd : closedBeforeContent
80
+ if (end === -1) {
81
+ fail('SKILL.md 缺少 YAML frontmatter 结束标记')
82
+ return undefined
83
+ }
84
+
85
+ pass('frontmatter markers valid')
86
+ return {
87
+ yaml: content.slice(4, end),
88
+ }
89
+ }
90
+
91
+ function normalizeYamlScalar(value) {
92
+ const hasSingleQuotes = value.startsWith('\'') && value.endsWith('\'')
93
+ const hasDoubleQuotes = value.startsWith('"') && value.endsWith('"')
94
+
95
+ return hasSingleQuotes || hasDoubleQuotes ? value.slice(1, -1) : value
96
+ }
97
+
98
+ function parseFrontmatter(yaml) {
99
+ const fields = new Map()
100
+
101
+ for (const rawLine of yaml.split('\n')) {
102
+ if (rawLine.startsWith(' ') || rawLine.startsWith('\t')) {
103
+ continue
104
+ }
105
+
106
+ const line = rawLine.trim()
107
+ if (!line || line.startsWith('#')) {
108
+ continue
109
+ }
110
+
111
+ const separator = line.indexOf(':')
112
+ if (separator === -1) {
113
+ fail(`YAML 行缺少冒号:${rawLine}`)
114
+ continue
115
+ }
116
+
117
+ const key = line.slice(0, separator).trim()
118
+ const value = line.slice(separator + 1).trim()
119
+
120
+ if (!key || !value) {
121
+ fail(`YAML 行缺少 key 或 value:${rawLine}`)
122
+ continue
123
+ }
124
+
125
+ fields.set(key, normalizeYamlScalar(value))
126
+ }
127
+
128
+ return fields
129
+ }
130
+
131
+ function checkFrontmatterFields(fields, root) {
132
+ const actualName = fields.get('name')
133
+ if (!actualName) {
134
+ fail('frontmatter 缺少 name')
135
+ }
136
+
137
+ const expectedName = path.basename(root)
138
+ if (actualName && actualName !== expectedName) {
139
+ fail(`frontmatter name 必须等于目录名:${expectedName}`)
140
+ }
141
+
142
+ const description = fields.get('description')
143
+ if (description && !DESCRIPTION_TRIGGER_PATTERN.test(description)) {
144
+ fail('frontmatter description 必须说明触发时机或触发场景')
145
+ }
146
+
147
+ if (actualName && actualName === expectedName) {
148
+ pass('frontmatter required fields present')
149
+ pass('frontmatter name matches folder')
150
+ if (description) {
151
+ pass('frontmatter description trigger contract valid')
152
+ }
153
+ else {
154
+ pass('frontmatter description omitted')
155
+ }
156
+ }
157
+ }
158
+
159
+ function finish(fields, root) {
160
+ console.log('────────────────────────────')
161
+ if (errors.length > 0) {
162
+ console.log(`FAIL ${errors.length} errors`)
163
+ process.exitCode = 1
164
+ return
165
+ }
166
+
167
+ console.log('PASS skill YAML frontmatter is valid')
168
+ console.log(` name: ${fields.get('name')}`)
169
+ console.log(` root: ${root}`)
170
+ }
171
+
172
+ function verify(root) {
173
+ const content = readSkillFile(root)
174
+ if (content) {
175
+ checkLineCount(content)
176
+ }
177
+
178
+ const parsed = content ? splitFrontmatter(content) : undefined
179
+ const fields = parsed ? parseFrontmatter(parsed.yaml) : new Map()
180
+
181
+ checkFrontmatterFields(fields, root)
182
+
183
+ finish(fields, root)
184
+ }
185
+
186
+ verify(parseArgs(process.argv.slice(2)).root)
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: frontend-code-standard
3
+ description: 触发时机:当用户要求新建、编写、重构、拆分前端组件、业务模块、工具函数或类型声明时触发。用于强制执行目录门面模式(Facade)、禁止深度导入、规范 src/ 隔离边界、强制同步交付测试用例,并应用 Vue 3.5+ 现代语法。
4
+ ---
5
+
6
+ # 前端工程架构与代码规范 (Frontend Architecture & Code Standards)
7
+
8
+ 在执行任何前端代码生成、重构或结构化任务时,必须没有例外地遵守以下物理架构与代码交付红线。
9
+
10
+ ## 0. 适用边界
11
+
12
+ - **项目事实优先**:先读取当前项目的框架版本、构建配置、测试入口和既有目录约定;不得为了套用本规范擅自升级依赖、改写项目架构或伪造验证入口。
13
+ - **Vue 3.5+ 约束范围**:第 4 节只强制适用于已确认支持 Vue 3.5+ 与相关宏的 Vue 代码。React、非 Vue 代码或旧版 Vue 项目只适用目录、门面、测试和交付规则;若版本不匹配,必须在交付中说明约束。
14
+ - **业务路由模块例外**:`views/`、`pages/`、`app/`、`routes/` 等框架路由扫描目录下的页面聚合模块不属于独立包根目录,严禁为了制造层级再包一层 `src/`;其内部的 `components/`、`utils/`、`types/` 等职责目录仍递归遵守门面规则。
15
+
16
+ ## 1. 门面模式与统一入口 (Facade Pattern & Export Rules)
17
+
18
+ 所有代码职责集合目录(如 `components/`、`utils/`、`types/`、`composables/`、`hooks/`)必须对外部调用者表现为一个黑盒。
19
+
20
+ - **强制入口**:职责目录下必须存在 `index.ts` 作为统一转发出口。
21
+ - **禁止深度导入**:包外、模块外和跨职责目录调用方绝对禁止使用 Deep Import 路径穿透(如禁止 `import { format } from '@/utils/string/format'`)。必须通过门面引入(如 `import { format } from '@/utils'`)。
22
+ - **内部私有实现**:同一职责目录内部允许通过相对路径引用私有实现文件;禁止让内部实现反向依赖自身公共 `index.ts`,避免循环依赖和伪公共 API。
23
+ - **类型聚合**:类型定义必须在类型目录的 `index.ts` 中通过 `export type * from './xxx'` 统一暴露。
24
+ - **值导出约束**:值导出优先使用显式命名导出;禁止用无差别 `export *` 暴露内部实现。
25
+ - **门面例外**:框架扫描目录、测试目录(`__test__/`、`__e2e__/`、`__mocks__/` 等)、样例目录、资产目录、样式目录、构建产物目录和 generated 目录不强制提供 `index.ts`。
26
+
27
+ ## 2. 独立模块与组件目录骨架 (Module & Package Structure)
28
+
29
+ 具有独立复用价值的组件包、工具包或业务模块,必须严格遵守内外隔离的物理骨架。
30
+
31
+ - **公共契约层(根目录)**:根目录只承载对外契约和工程配置。对外生产 API 只能通过唯一的根 `index.ts` 暴露;允许存在 `package.json`、`README.md`、构建配置、测试配置、类型配置、许可证和包管理元数据。
32
+ - **私有实现层 (`src/`)**:所有具体逻辑、组件、样式代码必须收敛在 `src/` 内部。在 `src/` 内部按需拆分 `components/`、`utils/`、`types/` 等目录,并递归遵守第 1 条门面规则。
33
+ - **类型契约层**:存在可复用或可依赖的 Props、Emits、Expose、Slots、Model、Ref、工具函数参数或返回类型时,必须收敛到 `src/types/`,由 `src/types/index.ts` 聚合,并由根 `index.ts` 通过 `export type * from './src/types'` 暴露。
34
+ - **越界调用拦截**:外部应用或其他模块只能引入该包的根 `index.ts`,绝对禁止任何直接读取其 `src/` 内部文件的行为。
35
+ - **私有叶子例外**:只有私有、叶子、无 props/emits/expose/slot/model/ref API、无导出类型、无跨目录复用、无生产职责拆分的展示组件,才允许保持单个 `.vue` 或 `.tsx` 文件。一旦出现 `types/`、`constants/`、`utils/`、`hooks/`、`composables/`、`components/` 等职责目录,必须立即升级为独立目录骨架。
36
+
37
+ ## 3. 强制测试交付要求 (Mandatory Testing Deliverables)
38
+
39
+ 每次生成或修改组件、核心工具逻辑、公共类型契约或可复用业务模块时,必须同步交付高质量测试代码,不得留作后续任务。
40
+
41
+ - **同步交付**:业务代码、结构调整和测试必须在同一轮交付中完成;若项目缺少必要测试依赖、配置或脚本入口,验证状态必须标记为 `MISSING`,不得伪造成已通过。
42
+ - **就近隔离**:测试文件必须放置在目标代码同级的 `__test__/` 目录下;跨多个业务模块的全局 E2E 才允许放在项目根级 `__e2e__/`。
43
+ - **测试技术栈**:单元、工具函数、类型契约和组件基础挂载测试优先使用 Vitest;真实浏览器交互、焦点、弹层、路由跳转和网络时序必须使用 Playwright 或项目既有真实浏览器测试工具。
44
+ - **禁止占位断言**:测试用例禁止只写“能渲染/能跑通”的烟雾测试。必须按目标实际存在的契约显式验证 Props、Events/Emits、Slots/Children、Model、Expose/Ref、用户交互和核心边界条件;不得为不存在的契约硬造测试。
45
+
46
+ ## 4. 现代 Vue 语法强制红线 (Modern Vue 3.5+ Syntax)
47
+
48
+ 除遵循 Vue 官方规范外,Vue 3.5+ 代码必须强制使用以下现代组合式 API 特性,严禁降级使用旧版写法。
49
+
50
+ - **双向绑定**:声明 `v-model` 双向绑定契约时,强制使用 `defineModel` 宏。严禁用手写 `emit('update:xxx')` 替代 model 契约;非 model 事件仍使用 `defineEmits`。
51
+ - **模板引用**:模板 DOM 或组件实例引用强制使用 Vue 3.5+ 的 `useTemplateRef` 绑定。严禁使用普通 `ref` 声明模板引用,以避免命名与常规响应式数据混淆。
52
+ - **Props 声明**:强制使用基于类型的 `defineProps`;需要默认值时必须配合 `withDefaults` 提供默认值,确保类型系统严谨完备。
53
+
54
+ ## 5. 交付状态
55
+
56
+ - **执行验证**:按任务风险执行项目已有的 `lint`、`typecheck`、`test`、`build` 或浏览器验证;缺少入口时标记为 `MISSING`,不得伪造成已通过。
57
+ - **状态优先级**:最终总结论按最高风险状态输出:`FAIL > MISSING > NOT RUN > PASS`。
58
+ - **状态语义**:`FAIL` 表示目标范围内存在违规或验证失败;`MISSING` 表示缺少必要工具、依赖、配置或脚本入口;`NOT RUN` 表示存在入口但未实际执行,必须说明原因;`PASS` 只能用于已通过目标范围内必要检查的场景。