jsharness 1.10.0 → 1.12.2

package/.harness/rules/project/frontend-coding-basics.md

@@ -0,0 +1,519 @@
+---
+name: frontend-coding-basics
+description: 通用前端基础编码规范 — CSS 编码规范（BEM/属性顺序/选择器/声明块/数值/字体/z-index）+ JS/TS 基础语法规范（对象/数组/字符串/函数/箭头函数/Switch/ES6/TypeScript）+ 模块化开发规范 + 通用禁止事项
+alwaysApply: false
+enabled: true
+globs:
+  - "src/**/*.{ts,tsx,js,jsx,vue,css,scss,less}"
+---
+
+# 通用前端基础编码规范 (frontend-coding-basics)
+
+> **级别**: 项目级强制 | **适用范围**: 所有前端项目（框架无关）
+> **来源**: `files/front-coding-rules.md` (v1.0.0) | **归档日期**: 2026-05-25
+> **定位**: 填补全局编码规范（`coding-standard.md`）与 Vue3 专属规范（`frontend-vue3.md`）之间的通用前端基础层
+
+---
+
+## 引用说明
+
+本文件与以下规则文件互补，重叠部分不重复写入：
+
+| 已覆盖内容 | 规则文件 | 章节 |
+|-----------|---------|------|
+| 命名约定（camelCase/UPPER_SNAKE/PascalCase/BEM/handle 前缀/is 前缀） | `coding-standard.md` | §2 命名约定 |
+| 注释规范（JSDoc、文件级注释、注释要点） | `coding-standard.md` | §5 注释规范 |
+| 导入顺序（第三方库 → 项目内部 → 相邻模块 → 类型导入） | `coding-standard.md` | §3.3 导入顺序 |
+| Vue3 组件规范（Composition API、defineProps、Pinia） | `frontend-vue3.md` | 全文 |
+| Element Plus 组件使用规范 | `frontend-vue3.md` | §5 |
+
+---
+
+## 一、CSS 编码规范
+
+### 1.1 BEM 命名规范
+
+class 命名使用 BEM（Block、Element、Modifier），使用 `__` 与 `--` 连接：
+
+```css
+.block {}                  /* 块 */
+.block__element {}         /* 元素 */
+.block--modifier {}        /* 修饰符 */
+```
+
+**为什么使用 BEM？** CSS 引擎查找样式表按从右到左顺序匹配，BEM 可减少嵌套层级，提升性能。
+
+```css
+/* ❌ 错误：深层嵌套 */
+.main .content .title .name { color: #fff; }
+
+/* ✅ 正确：BEM 扁平化 */
+.content-title__name { color: #fff; }
+```
+
+### 1.2 样式属性顺序
+
+按照以下顺序书写属性：
+
+1. **布局位置**（position, top, right, z-index, display, float 等）
+2. **尺寸大小**（width, height, padding, margin）
+3. **文字系列**（font, line-height, letter-spacing, color, text-align 等）
+4. **视觉效果**（background, border 等）
+5. **其他**（animation, transform 等）
+
+```css
+/* ❌ 错误：属性顺序混乱 */
+.header {
+    background: #CCC;
+    font-size: 20px;
+    height: 50px;
+    border: 1px solid #bbb;
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 100%;
+}
+
+/* ✅ 正确：按 布局→尺寸→文字→视觉→其他 排列 */
+.header {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 100%;
+    height: 50px;
+    font-size: 20px;
+    color: #f94000;
+    background: #CCC;
+    border: 1px solid #bbb;
+}
+```
+
+### 1.3 选择器规范
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| 嵌套层级 | 不大于 **3 级** | Code Review FAIL |
+| ID 选择器 | 避免使用 | Code Review WARNING |
+| 全局标签选择器 | 禁止使用（如 `div {}`, `button {}`） | Code Review FAIL |
+| 标签名选择器 | CSS 选择器中避免使用标签名 | Code Review WARNING |
+| @import | 尽量不要使用（与 `<link>` 相比速度较慢） | Code Review WARNING |
+
+```css
+/* ❌ 错误：全局标签选择器 */
+div { padding-bottom: 0; }
+button { border: 1px solid #ccc; }
+
+/* ✅ 正确：使用类名选择器 */
+.header { padding-bottom: 0; }
+.custom-form { margin: 20px; }
+```
+
+### 1.4 规则声明块格式规范
+
+1. 每条样式独占一行
+2. 列表属性用逗号分隔，逗号后必须跟空格
+3. 选择器与左大括号 `{` 之间必须加空格
+4. 属性名与冒号之间不允许包含空格，冒号与属性值之间必须包含空格
+5. 每条样式以分号 `;` 结尾
+6. 右大括号 `}` 独占一行
+7. 每个规则声明间用空行分隔
+
+```css
+/* ✅ 正确 */
+.selector {
+    position: absolute;
+    width: 100%;
+    font-family: 'Helvetica', 'Arial', sans-serif;
+}
+
+.another-selector {
+    margin: 0;
+}
+```
+
+### 1.5 数值与长度规范
+
+| 规则 | 要求 | 示例 |
+|------|------|------|
+| 0-1 小数 | 省略整数部分的 0 | `opacity: .8` 非 `0.8` |
+| 长度为 0 | 省略单位 | `padding: 0 5px` 非 `0px 5px` |
+| 颜色值 | 使用缩写格式 | `#f40` 非 `#ff4400` |
+| 命名色值 | 禁止使用 | 禁止 `lightgreen`，用 `#90ee90` |
+
+```css
+/* ✅ 正确 */
+.panel { opacity: .8; }
+.list { padding: 0 5px; }
+.header { color: #f40; }
+
+/* ❌ 错误：命名色值 */
+.button--success { color: lightgreen; }
+```
+
+### 1.6 字体排版规范
+
+| 规则 | 要求 | 原因 |
+|------|------|------|
+| 字号 | 不小于 **12px** | Windows 平台中文显示限制 |
+| font-weight | 使用数值方式 | `700` 而非 `bold`，精确控制 |
+| line-height | 使用数值而非像素值 | 浏览器基于 font-size 自动计算 |
+
+```css
+/* ❌ 错误 */
+.title { font-weight: bold; }
+.container { line-height: 15px; }
+
+/* ✅ 正确 */
+.title { font-weight: 700; }
+.container { line-height: 1.5; }
+```
+
+### 1.7 其他 CSS 规范
+
+| 规则 | 要求 |
+|------|------|
+| !important | 除公共样式外，业务代码中尽量不使用 |
+| z-index | 建议分层管理（如：dropdown 100、modal 200、toast 300） |
+| Media Query | 不得单独编排，须与相关规则一起定义 |
+| CSS 变量 | 集中配置在全局变量中，方便统一管理 |
+
+---
+
+## 二、JavaScript / TypeScript 基础语法规范
+
+> **命名约定**（camelCase/UPPER_SNAKE/handle 前缀/is 前缀）见 `coding-standard.md` §2。
+> **注释规范**（JSDoc、文件级注释、注释要点）见 `coding-standard.md` §5。
+
+### 2.1 对象规范
+
+#### 2.1.1 使用字面量创建对象
+
+```javascript
+// ❌ 错误
+const obj = new Object()
+
+// ✅ 正确
+const obj = {}
+```
+
+#### 2.1.2 对象属性简写
+
+属性名与变量名一致时必须使用简写：
+
+```javascript
+const job = 'FrontEnd'
+
+// ❌ 错误
+const item = { job: job }
+
+// ✅ 正确
+const item = { job }
+```
+
+#### 2.1.3 对象拷贝 — 优先使用展开运算符
+
+```javascript
+// ❌ 错误
+const copy = Object.assign({}, original, { c: 3 })
+
+// ✅ 正确
+const copy = { ...original, c: 3 }
+const { a, ...noA } = copy  // noA => { b: 2, c: 3 }
+```
+
+#### 2.1.4 非法标识符引号
+
+只对非法标识符的属性使用引号：
+
+```javascript
+// ❌ 错误
+const bad = { 'foo': 3, 'bar': 4, 'data-blah': 5 }
+
+// ✅ 正确
+const good = { foo: 3, bar: 4, 'data-blah': 5 }
+```
+
+#### 2.1.5 属性访问
+
+使用 `.` 来访问对象属性（动态键除外）：
+
+```javascript
+const joke = { name: 'haha', age: 28 }
+
+// ❌ 错误
+const name = joke['name']
+
+// ✅ 正确
+const name = joke.name
+
+// ✅ 正确：动态键
+const key = 'name'
+const val = joke[key]
+```
+
+### 2.2 数组规范
+
+| 场景 | 要求 | 违规后果 |
+|------|------|----------|
+| 创建数组 | 使用字面量 `[]` | Code Review WARNING |
+| 添加元素 | 使用 `push` | Code Review WARNING |
+| 复制数组 | 使用展开运算符 `[...arr]` | Code Review WARNING |
+| 类数组转数组 | 使用 `Array.from` | Code Review WARNING |
+| 取值 | 使用数组解构赋值 | Code Review WARNING |
+| map 方法 | 必须有 return | Code Review FAIL |
+
+```javascript
+// ❌ 错误
+const items = new Array()
+items[items.length] = 'test'
+const copy = arr.slice()
+
+// ✅ 正确
+const items = []
+items.push('test')
+const copy = [...items]
+const arrLike = { 0: 'foo', 1: 'bar', length: 2 }
+const arr = Array.from(arrLike)
+const [first, second] = arr
+```
+
+### 2.3 字符串规范
+
+| 规则 | 要求 | 示例 |
+|------|------|------|
+| 定义 | 统一使用单引号 | `'JDC'` 非 `"JDC"` |
+| 动态生成 | 使用模板字符串 | `` `ab${test}` `` 非 `'a' + 'b' + test` |
+| eval | 禁止使用 | 存在安全漏洞 |
+
+```javascript
+// ❌ 错误
+const department = "JDC"
+const str = 'a' + 'b' + test
+
+// ✅ 正确
+const department = 'JDC'
+const str = `ab${test}`
+```
+
+### 2.4 函数规范
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| 函数签名 | 函数签名与函数体之间有空格 | Code Review WARNING |
+| Function 构造函数 | 禁止使用 `new Function()` | Code Review FAIL |
+| 块中声明函数 | 禁止在非函数代码块中声明函数 | Code Review FAIL |
+| arguments | 禁止使用，改用剩余参数 `...args` | Code Review FAIL |
+| 参数默认值 | 使用参数默认值语法 | Code Review WARNING |
+| 默认值位置 | 有默认值的参数放在最后 | Code Review WARNING |
+| 参数重新赋值 | 禁止对参数重新赋值 | Code Review FAIL |
+
+```javascript
+// ❌ 错误
+const add = new Function('a', 'b', 'return a + b')
+if (isUse) { function test() {} }
+function test() { const args = Array.prototype.slice.call(arguments) }
+function handleThings(opts) { opts = opts || {} }
+function handleThings(opts = {}, name) {}
+const foo = function(bar) { bar = 13 }
+
+// ✅ 正确
+const add = (a, b) => a + b
+let test
+if (isUse) { test = () => {} }
+function test(...args) { return args.join('') }
+function handleThings(opts = {}) {}
+function handleThings(name, opts = {}) {}
+const foo = function(bar) { let baz = bar }
+```
+
+### 2.5 箭头函数规范
+
+| 规则 | 要求 |
+|------|------|
+| 匿名函数 | 传递匿名函数时优先使用箭头函数 |
+| 单表达式 | 函数体只包含一条无副作用的返回表达式 → 省略花括号，隐式 return |
+| 多语句 | 保留花括号并使用 return |
+| 返回对象 | 返回对象字面量必须加括号 |
+
+```javascript
+// ✅ 正确：单一表达式
+[1, 2, 3].map(number => `A string containing the ${number}.`)
+
+// ✅ 正确：多行语句
+[1, 2, 3].map((number) => {
+  const nextNumber = number + 1
+  return `A string containing the ${nextNumber}.`
+})
+
+// ✅ 正确：返回对象需加括号
+[1, 2, 3].map((number, index) => ({ index: number }))
+```
+
+### 2.6 Switch 规范
+
+- 每个 case 必须做好防穿透处理（break）
+- 最后必须有 default 默认出口
+
+```javascript
+// ❌ 错误：case 2 缺少 break，缺少 default
+switch (foo) {
+  case 1:
+    bar()
+    break
+  case 2:
+    quux()
+}
+
+// ✅ 正确
+switch (foo) {
+  case 1:
+    bar()
+    break
+  case 2:
+    quux()
+    break
+  default:
+    baz()
+    break
+}
+```
+
+### 2.7 ES6 语法优先
+
+| 场景 | ES6 写法 | 替代的 ES5 模式 |
+|------|---------|---------------|
+| 匿名函数 | 箭头函数 | `function() {}` |
+| 异步操作 | async/await | 回调地狱 |
+| 取值 | 解构赋值 | `const x = obj.x` |
+| 变量声明 | const 优先（必要时 let，**禁止 var**） | `var` |
+| 迭代 | for...of | 手动索引循环 |
+| 拷贝合并 | 展开运算符 `...` | `Object.assign` / 手动循环 |
+
+### 2.8 TypeScript 类型约束
+
+> **基础 TS 类型安全**（禁止裸 any、Props 使用 interface）见 `coding-standard.md` §1 和 `frontend-vue3.md` §2。
+
+| 规则 | 要求 | 违规后果 |
+|------|------|----------|
+| 禁止滥用 any | 不确定类型时使用 `unknown` 而非 `any` | Code Review WARNING |
+| interface vs type | interface 用于描述对象结构，type 用于联合类型/工具类型 | Code Review WARNING |
+| 公共 API 类型 | 入参/出参必须显式声明类型 | Code Review FAIL |
+
+```typescript
+// ❌ 错误
+function process(data: any): any { return data }
+
+// ✅ 正确
+interface UserData { id: string; name: string }
+function process(data: UserData): UserData { return data }
+
+// ✅ interface 用于对象结构
+interface UserProps { id: string; name: string }
+
+// ✅ type 用于联合类型/工具类型
+type Status = 'active' | 'inactive'
+type Nullable<T> = T | null
+```
+
+---
+
+## 三、模块化开发规范
+
+> **导入顺序**（第三方库 → 项目内部 → 相邻模块 → 类型导入）见 `coding-standard.md` §3.3。
+
+### 3.1 使用标准 ES6 模块语法
+
+```javascript
+// ❌ 错误
+const util = require('./util')
+module.exports = util
+
+// ✅ 正确
+import Util from './util'
+export default Util
+
+// ✅ 更好：具名导出
+import { Util } from './util'
+```
+
+### 3.2 同个文件每个模块只 import 一次
+
+```javascript
+// ❌ 错误
+import foo from 'foo'
+// ... 其他 imports ...
+import { named1, named2 } from 'foo'
+
+// ✅ 正确
+import foo, { named1, named2 } from 'foo'
+```
+
+### 3.3 禁止 import 后再添加 import
+
+import 语句必须置于文件顶部，业务代码之后不得再插入 import：
+
+```javascript
+// ❌ 错误
+import foo from 'foo'
+foo.init()
+import bar from 'bar'
+
+// ✅ 正确
+import foo from 'foo'
+import bar from 'bar'
+
+foo.init()
+```
+
+### 3.4 多行导入格式
+
+多行导入像多行数组和对象一样缩进：
+
+```javascript
+// ❌ 错误
+import { longNameA, longNameB, longNameC, longNameD, longNameE } from 'path'
+
+// ✅ 正确
+import {
+  longNameA,
+  longNameB,
+  longNameC,
+  longNameD,
+  longNameE
+} from 'path'
+```
+
+### 3.5 禁止在 import 声明中使用 Webpack loader 语法
+
+```javascript
+// ❌ 错误
+import fooSass from 'css!sass!foo.scss'
+
+// ✅ 正确
+import fooSass from 'foo.scss'
+```
+
+---
+
+## 四、通用禁止事项清单（MUST NOT）
+
+> 以下仅列出与 `coding-standard.md` 和 `frontend-vue3.md` **不重复**的禁止事项。重复条目见对应文件。
+
+| 编号 | 禁止事项 | 说明 | 违规后果 |
+|------|---------|------|----------|
+| CB-01 | 禁止使用 `eval()` | 存在安全漏洞 | Code Review FAIL |
+| CB-02 | 禁止 CSS 嵌套 > 3 层 | 使用 BEM 命名扁平化 | Code Review FAIL |
+| CB-03 | 禁止全局标签选择器修改样式 | 使用类名选择器 | Code Review FAIL |
+| CB-04 | 禁止在非函数块中声明函数 | 改用变量赋值箭头函数 | Code Review FAIL |
+| CB-05 | 禁止使用 `arguments` | 使用剩余参数 `...args` | Code Review FAIL |
+| CB-06 | 禁止重复 import 同一模块 | 合并为单条 import 语句 | Code Review WARNING |
+| CB-07 | 禁止 Switch 缺少 default 分支 | 必须包含 default 默认出口 | Code Review FAIL |
+| CB-08 | 禁止 import 后再添加 import | import 语句必须置于文件顶部 | Code Review WARNING |
+| CB-09 | 禁止使用 `new Object()` / `new Array()` | 使用字面量 `{}` / `[]` | Code Review WARNING |
+| CB-10 | 禁止使用双引号定义字符串 | 统一使用单引号，动态字符串使用模板字符串 | Code Review WARNING |
+
+> **与现有规则的对应关系**：
+> - C001（禁止 any）→ `coding-standard.md` §1 已覆盖
+> - C009（禁止 var）→ `coding-standard.md` §3.4 已覆盖
+> - C010（禁止双引号）→ 本表 CB-10
+> - FV-01~FV-07 → `frontend-vue3.md` §8 已覆盖

package/.harness/skills/design-context-reader/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: design-context-reader
+description: 研发设计上下文读取技能 — 根据任务编号自动加载需求阶段的 PRD 和 ttspec change 内容，作为架构设计/研发设计的强制前置步骤
+alwaysApply: false
+enabled: true
+outputPath: .harness/doc/
+---
+
+# 研发设计上下文读取技能 (design-context-reader)
+
+> **Skill 类型**: 开发设计辅助 Skill
+> **触发场景**: 架构设计或研发设计阶段开始前，作为强制前置步骤
+> **所属 Agent**: architect / developer
+> **作用**: 根据任务编号自动加载 PRD 和 ttspec change 内容
+
+---
+
+## 1. 核心职责
+
+作为研发设计上下文读取技能，核心职责是：
+
+1. **根据任务编号关联并读取 PRD 文档**
+2. **根据任务编号关联并读取 ttspec change 内容**
+3. **作为架构/研发设计的强制前置步骤**
+
+### 1.1 触发条件
+
+以下场景**必须**先执行本 Skill 读取上下文：
+
+- 执行架构设计（使用 `architecture-designer` Skill）
+- 执行研发设计（编写设计文档）
+- 执行代码审查时需要理解业务上下文
+
+### 1.2 输入
+
+| 输入项 | 来源 | 格式 | 必须 |
+|--------|------|------|------|
+| 任务编号 / change 名称 | tasks.md 或用户指定 | 字符串 | 是 |
+
+---
+
+## 2. 执行步骤
+
+### Step 1: 读取 PRD 文档
+
+按以下顺序查找 PRD 文件：
+
+1. **暂存区查找**：`.harness/doc/prd/requirements-{name}.md`
+   - 如果找到 → 读取并显示 "已加载 PRD：requirements-{name}.md"
+2. **归档区查找**：`.harness/doc/prd/prd-main/{module}/requirements-{name}.md`
+   - 遍历 prd-main/ 下所有模块子目录查找匹配文件
+   - 如果找到 → 读取并显示 "已加载 PRD（已归档）：prd-main/{module}/requirements-{name}.md"
+3. **未找到** → 记录 "未找到关联 PRD，基于 ttspec change 内容进行设计"
+
+### Step 2: 读取 ttspec change 内容
+
+按以下顺序查找 change 目录：
+
+1. **活跃区查找**：`.harness/doc/ttspec/change/{name}/`
+   - 如果找到 → 读取 proposal.md、design.md、specs/、tasks.md
+   - 显示 "已加载 change：{name}（活跃）"
+2. **归档区查找**：`.harness/doc/ttspec/change/archive/{date}-{name}/`
+   - 遍历 archive/ 下查找匹配目录
+   - 如果找到 → 读取相关文件并显示 "已加载 change：{name}（已归档）"
+3. **未找到** → 警告 "未找到 ttspec change 目录，设计可能缺少上下文"
+
+### Step 3: 上下文就绪确认
+
+- 如果 PRD 和 ttspec change 均未找到 → 警告用户但允许继续
+- 如果至少找到一个 → 在设计过程中引用已加载的上下文
+- 在设计产出中**必须**引用来源（PRD 文件路径或 change 目录路径）
+
+---
+
+## 3. 约束
+
+- **强制前置** — 设计任务开始前必须先执行本 Skill，未读取上下文禁止开始设计
+- **不阻塞** — 即使 PRD 和 ttspec change 都未找到，仅警告不阻断
+- **引用来源** — 设计产出中必须标注上下文来源
+- **所有输出使用中文**

package/.harness/skills/docker-build/SKILL.md

@@ -191,7 +191,7 @@ LICENSE
 
 # Harness（不需要进入镜像）
 .harness/
-openspec/
+jsspec/
 *.gate-report.json
 ```