reactlynx-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ReactLynx Best Practices

ReactLynx最佳实践

ReactLynx best practices covering dual-thread architecture and React patterns. Provides rules reference for writing, static analysis for reviewing, and auto-fix for refactoring.

ReactLynx最佳实践，涵盖双线程架构与React模式。提供编写参考规则、代码审查静态分析以及重构自动修复功能。

When to Apply

适用场景

This skill should be used when:

Writing new ReactLynx components or application → Reference rules as guidelines
Reviewing existing ReactLynx code → Use scanner to detect issues
Refactoring ReactLynx code → Use auto-fix with user approval

本技能适用于以下场景：

编写新的ReactLynx组件或应用 → 参考规则作为指导方针
审查现有ReactLynx代码 → 使用扫描工具检测问题
重构ReactLynx代码 → 在用户确认后使用自动修复功能

Input

输入参数

This skill accepts the following inputs:

Input	Required	Description
`sourceCode`	No	The ReactLynx source code to analyze (string or file path)
`mode`	No	Workflow mode: `writing` , `review` , or `refactor` . Auto-detected if not specified

本技能接受以下输入：

输入项	是否必填	描述
`sourceCode`	否	待分析的ReactLynx源代码（字符串或文件路径）
`mode`	否	工作流模式： `writing` （编写）、 `review` （审查）或 `refactor` （重构）。未指定时将自动检测

Mode Auto-Detection

模式自动检测

When

mode

is not explicitly provided, the skill will determine the appropriate mode based on context:

Context	Auto-Selected Mode
User is asking for best practices or guidelines	`writing`
User wants to check/analyze existing code for issues	`review`
User wants to fix/refactor code with auto-fixes	`refactor`

当未明确指定

mode

时，技能会根据上下文确定合适的模式：

上下文	自动选择的模式
用户询问最佳实践或指导方针	`writing`
用户希望检查/分析现有代码中的问题	`review`
用户希望通过自动修复来修正/重构代码	`refactor`

Workflow Modes

工作流模式

📝 Writing Mode

📝 编写模式

When writing new ReactLynx code, reference the rules in

rules/*.md

as best practice guidelines. See also the Rules section below for a summary of all available rules.

Use this mode when:

User is creating new ReactLynx components or application
User asks "how should I write..." or "what's the best practice for..."
No existing code to analyze

编写新的ReactLynx代码时，可参考

rules/*.md

中的规则作为最佳实践指南。另请参阅下方规则部分，获取所有可用规则的摘要。

适用场景：

用户正在创建新的ReactLynx组件或应用
用户询问“我应该如何编写...”或“...的最佳实践是什么？”
无现有代码需要分析

🔍 Review Mode

🔍 审查模式

When reviewing code, do both:

Use the scanner (
```
scripts/index.mjs
```
) to analyze source code for issues
Combine findings with
```
rules/*.md
```
explanations to generate a rule-aware report

Use this mode when:

User provides code and asks to "check", "review", or "analyze" it
User wants to know if their code has any issues
User asks "is this code correct?" or "any problems with this?"

Report requirements (must include):

Scan summary from
```
workflow.reviewCode(sourceCode)
```
Rule interpretation for each hit
```
ruleId
```
from
```
rules/<ruleId>.md
```
Severity/impact context from rule metadata (
```
impact
```
,
```
impactDescription
```
)
Actionable suggestions based on rule guidance (not only raw diagnostics)

bash

node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatScanReport } from '<path_to_skill>/scripts/index.mjs';

// <sourceCode>: string (source code) or file path
const input = '<sourceCode>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;

const workflow = new ReactLynxWorkflow('review');
const summary = workflow.reviewCode(sourceCode);
console.log(formatScanReport(summary));
"

审查代码时，需完成以下两项操作：

使用扫描工具（
```
scripts/index.mjs
```
）分析源代码以发现问题
将扫描结果与
```
rules/*.md
```
中的解释相结合，生成规则感知报告

适用场景：

用户提供代码并要求“检查”、“审查”或“分析”
用户想了解其代码是否存在问题
用户询问“这段代码是否正确？”或“这里有什么问题吗？”

报告要求（必须包含）：

来自
```
workflow.reviewCode(sourceCode)
```
的扫描摘要
来自
```
rules/<ruleId>.md
```
中每个命中规则
```
ruleId
```
的规则解释
规则元数据中的严重性/影响上下文（
```
impact
```
、
```
impactDescription
```
）
基于规则指导的可操作建议（不仅是原始诊断信息）

bash

node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatScanReport } from '<path_to_skill>/scripts/index.mjs';

// <sourceCode>: string (source code) or file path
const input = '<sourceCode>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;

const workflow = new ReactLynxWorkflow('review');
const summary = workflow.reviewCode(sourceCode);
console.log(formatScanReport(summary));
"

🔧 Refactor Mode

🔧 重构模式

When refactoring, generate a fix plan and ask the user before applying.
In this mode, output must include both script results and a rules-aware report.

Use this mode when:

User explicitly asks to "fix", "refactor", or "auto-fix" code
User wants to apply suggested fixes from a previous review
User says "please fix these issues" or "apply the fixes"

Report requirements (must include):

Pre-fix scan summary and rule-aware interpretation
Fix plan summary (
```
fixableIssues
```
,
```
manualIssues
```
, per-file changes)
Post-fix outcome (
```
appliedFixes
```
) and remaining manual issues

TOOL CALL: AskUserQuestion(
  question: "🔧 Found {fixableIssues} auto-fixable issues. Would you like me to apply these fixes?",
  options: ["Yes, apply fixes", "No, show me the issues first", "Skip auto-fix"]
)

bash

node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatFixPlan } from '<path_to_skill>/scripts/index.mjs';

// <sourceCode>: string (source code) or file path
const input = '<sourceCode>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;

const workflow = new ReactLynxWorkflow('refactor');
workflow.reviewCode(sourceCode);
const plan = workflow.generateFixPlan();

if (plan && plan.fixableIssues > 0) {
  console.log(formatFixPlan(plan));
  // ASK USER: 'Would you like me to apply these auto-fixes?'
  // If yes:
  const { fixed, appliedFixes } = workflow.applyAutoFixes(sourceCode);
  console.log('Fixed code:', fixed);
}
"

重构时，需生成修复计划并在应用前询问用户。
在此模式下，输出必须同时包含脚本结果和规则感知报告。

适用场景：

用户明确要求“修复”、“重构”或“自动修复”代码
用户希望应用之前审查得出的建议修复方案
用户表示“请修复这些问题”或“应用修复方案”

报告要求（必须包含）：

修复前的扫描摘要和规则感知解释
修复计划摘要（
```
fixableIssues
```
、
```
manualIssues
```
、每个文件的变更内容）
修复后的结果（
```
appliedFixes
```
）以及剩余的手动修复问题

TOOL CALL: AskUserQuestion(
  question: "🔧 发现{fixableIssues}个可自动修复的问题。是否要应用这些修复？",
  options: ["是，应用修复", "否，先查看问题", "跳过自动修复"]
)

bash

node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatFixPlan } from '<path_to_skill>/scripts/index.mjs';

// <sourceCode>: string (source code) or file path
const input = '<sourceCode>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;

const workflow = new ReactLynxWorkflow('refactor');
workflow.reviewCode(sourceCode);
const plan = workflow.generateFixPlan();

if (plan && plan.fixableIssues > 0) {
  console.log(formatFixPlan(plan));
  // ASK USER: '是否要应用这些自动修复？'
  // 如果是:
  const { fixed, appliedFixes } = workflow.applyAutoFixes(sourceCode);
  console.log('修复后的代码:', fixed);
}
"

Rules

规则

All rules are documented in the

rules/

directory as Markdown files:

Rule	Impact	Description
detect-background-only	CRITICAL	Native APIs in background contexts, use `'background only'` directive
proper-event-handlers	MEDIUM	Correct event handler usage
main-thread-scripts-guide	MEDIUM	Main thread scripts guide
hoist-static-jsx	LOW	Performance optimization

所有规则都在

rules/

目录下以Markdown文件形式记录：

规则	影响级别	描述
detect-background-only	严重	后台上下文使用原生API，需添加 `'background only'` 指令
proper-event-handlers	中等	正确使用事件处理程序
main-thread-scripts-guide	中等	主线程脚本指南
hoist-static-jsx	低	性能优化建议

API Reference

API参考

For complete type definitions:

TOOL CALL: Read(<path_to_skill>/scripts/index.d.ts)

完整类型定义请查看：

TOOL CALL: Read(<path_to_skill>/scripts/index.d.ts)

Exported Functions

导出函数

typescript

function runSkill(source: string): Diagnostic[];
function runSkillWithFixes(source: string): DiagnosticWithFix[];
function analyzeBackgroundOnlyUsage(source: string): Diagnostic[];
function generateFixes(source: string, diagnostic: Diagnostic): Fix[];
function applyFix(source: string, fix: Fix): string;
function applyFixes(source: string, fixes: Fix[]): string;
function formatScanReport(summary: ScanSummary): string;
function formatFixPlan(plan: FixPlan): string;

typescript

function runSkill(source: string): Diagnostic[];
function runSkillWithFixes(source: string): DiagnosticWithFix[];
function analyzeBackgroundOnlyUsage(source: string): Diagnostic[];
function generateFixes(source: string, diagnostic: Diagnostic): Fix[];
function applyFix(source: string, fix: Fix): string;
function applyFixes(source: string, fixes: Fix[]): string;
function formatScanReport(summary: ScanSummary): string;
function formatFixPlan(plan: FixPlan): string;

Workflow Class

工作流类

typescript

class ReactLynxWorkflow {
  constructor(mode: WorkflowMode);
  reviewCode(source: string): ScanSummary;
  generateFixPlan(): FixPlan | null;
  applyAutoFixes(source: string): { fixed: string; appliedFixes: Fix[] };
}

typescript

class ReactLynxWorkflow {
  constructor(mode: WorkflowMode);
  reviewCode(source: string): ScanSummary;
  generateFixPlan(): FixPlan | null;
  applyAutoFixes(source: string): { fixed: string; appliedFixes: Fix[] };
}

Key Types

核心类型

typescript

type WorkflowMode = 'writing' | 'review' | 'refactor';

interface Diagnostic {
  ruleId: string;
  message: string;
  severity: 'error' | 'warning' | 'info';
  location: { start: { line: number; column: number }; end: { line: number; column: number } };
}

interface DiagnosticWithFix extends Diagnostic {
  fixes?: Fix[];
}

interface Fix {
  type: 'wrap-in-useEffect' | 'add-directive' | 'add-import' | 'move-to-event-handler';
  description: string;
  oldCode: string;
  newCode: string;
  location: { start: { line: number; column: number }; end: { line: number; column: number } };
}

interface ScanSummary {
  totalFiles: number;
  filesWithIssues: number;
  totalIssues: number;
  errorCount: number;
  warningCount: number;
  infoCount: number;
  results: ScanResult[];
}

interface FixPlan {
  totalIssues: number;
  fixableIssues: number;
  manualIssues: number;
  files: FilePlan[];
}

typescript

type WorkflowMode = 'writing' | 'review' | 'refactor';

interface Diagnostic {
  ruleId: string;
  message: string;
  severity: 'error' | 'warning' | 'info';
  location: { start: { line: number; column: number }; end: { line: number; column: number } };
}

interface DiagnosticWithFix extends Diagnostic {
  fixes?: Fix[];
}

interface Fix {
  type: 'wrap-in-useEffect' | 'add-directive' | 'add-import' | 'move-to-event-handler';
  description: string;
  oldCode: string;
  newCode: string;
  location: { start: { line: number; column: number }; end: { line: number; column: number } };
}

interface ScanSummary {
  totalFiles: number;
  filesWithIssues: number;
  totalIssues: number;
  errorCount: number;
  warningCount: number;
  infoCount: number;
  results: ScanResult[];
}

interface FixPlan {
  totalIssues: number;
  fixableIssues: number;
  manualIssues: number;
  files: FilePlan[];
}