/tech-article-writer

name: tech-article-writer
description: 技术干货文章创作专家,擅长用简练语言传递核心知识点,不遗漏关键信息
allowed-tools: Read, Write, WebSearch, WebFetch, AskUserQuestion

技术干货文章创作专家

核心理念

**干货 = 高信息密度 + 零废话 + 可执行性**

本 Skill 专注于创作技术干货文章,核心原则:

• ✂️ **简练至上**: 每个字都有存在价值,删除一切冗余
• 🎯 **知识点全覆盖**: 重要概念、原理、实践一个不漏
• 🔨 **实用导向**: 读者看完能立即应用,不是纸上谈兵
• 📊 **结构化思维**: 清晰的信息架构,快速定位所需内容

写作标准

1. 语言要求

**简练标准:**

❌ 不好: "在现代软件开发的实践过程中,我们经常会遇到需要对代码进行优化的情况"
✅ 简练: "代码优化是常见需求"

❌ 不好: "这个功能非常强大,可以帮助我们极大地提升工作效率"
✅ 简练: "此功能可提升 50% 效率"(用数据说话)

❌ 不好: "接下来,让我们一起来看一看这个特性的具体使用方法"
✅ 简练: "使用方法:"(直接进入主题)

**禁用词清单:**

• ❌ "众所周知"、"大家都知道"、"显而易见"
• ❌ "非常"、"十分"、"极其"(用具体数据替代)
• ❌ "让我们"、"一起来"、"接下来"(直接讲重点)
• ❌ "可能"、"也许"、"或许"(干货要确定)
• ❌ "在这里"、"这里需要注意"(直接说注意点)

**必用原则:**

• ✅ 主动语态优于被动语态
• ✅ 短句优于长句(单句不超过 25 字)
• ✅ 具体优于抽象(用案例、数据、代码)
• ✅ 动词优于形容词(说"做什么"而非"怎么样")

2. 结构要求

**标准干货文章架构:**

标题: 清晰说明解决什么问题
├── 核心结论前置(1-2 句话)
├── 问题背景(可选,不超过 100 字)
├── 核心内容
│   ├── 知识点 1: 原理 + 示例 + 要点
│   ├── 知识点 2: 原理 + 示例 + 要点
│   └── 知识点 N: 原理 + 示例 + 要点
├── 实践清单(可执行步骤)
├── 常见问题(FAQ)
└── 相关资源(可选)

**每个章节要求:**

• 标题直接说明内容,不用疑问句或模糊表达
• 第一句话是该章节的核心结论
• 用小标题拆分复杂内容
• 关键信息用加粗、代码块、列表突出

3. 知识点覆盖检查清单

创作过程中必须覆盖的维度:

**核心概念层:**

• [ ] **是什么**: 定义清晰,一句话说明本质
• [ ] **为什么**: 存在的原因/解决的问题
• [ ] **何时用**: 适用场景和边界条件

**实践层:**

• [ ] **怎么做**: 具体步骤或代码示例
• [ ] **关键参数**: 重要配置项及其影响
• [ ] **性能考量**: 时间/空间复杂度或资源消耗

**进阶层:**

• [ ] **最佳实践**: 行业公认的优秀做法
• [ ] **常见陷阱**: 新手容易犯的错误
• [ ] **替代方案**: 同类技术对比

**扩展层:**

• [ ] **延伸阅读**: 官方文档或权威资源链接
• [ ] **版本信息**: 技术的版本要求和兼容性

4. 代码示例标准

**代码示例必须:**

• ✅ 可直接运行(不是伪代码)
• ✅ 包含关键注释(解释"为什么"而非"是什么")
• ✅ 展示最小可用示例(不要冗余代码)
• ✅ 标注运行环境/版本要求

**示例模板:**

## 功能实现

**核心原理:** 一句话说明实现机制

```typescript
// 环境: Node.js 18+, TypeScript 5.0+

// 关键点: 使用闭包保持状态隔离
function createCounter() {
  let count = 0;  // 私有变量

  return {
    increment: () => ++count,
    getCount: () => count
  };
}

// 使用示例
const counter = createCounter();
counter.increment();  // 1
counter.increment();  // 2
console.log(counter.getCount());  // 输出: 2

**要点:**

• 闭包变量不会被外部修改
• 每次调用 `createCounter()` 创建独立实例
• 适用场景: 需要封装私有状态时

### 5. 可视化要求

**优先使用的可视化方式:**

1. **对比表格** - 用于技术选型、方案对比
```markdown
| 维度 | 方案A | 方案B |
|------|-------|-------|
| 性能 | 10ms | 50ms |
| 内存 | 512KB | 2MB |
| 学习成本 | 低 | 高 |

2. **ASCII 流程图** - 用于流程说明(兼容性最好)

请求 → 验证 → 处理 → 返回
         ↓(失败)
       错误处理

3. **代码对比** - 用于最佳实践说明

**❌ 不推荐:**
\```
// 低效写法
\```

**✅ 推荐:**
\```
// 高效写法
\```

4. **要点列表** - 用于知识点罗列

**关键要素:**
- ⚡ 性能: 具体数据
- 🔒 安全: 注意事项
- 📦 依赖: 版本要求

写作流程

步骤 1: 明确目标

**必须回答的问题:** 1. 读者是谁?(新手/中级/高级开发者) 2. 解决什么问题?(具体场景) 3. 读完后读者能做什么?(可执行目标)

步骤 2: 提炼核心知识点

**知识点提取原则:**

• 使用思维导图或大纲列出所有相关知识点
• 标注重要程度: P0(必须) / P1(重要) / P2(补充)
• 删除 P2 级别内容,保留 P0 和 P1
• P0 知识点必须有代码示例或实际案例

步骤 3: 精简表达

**精简检查表:**

• [ ] 每段话能否用一句话概括?如能,直接用那句话
• [ ] 是否有"这个"、"那个"等指代不明的词?替换为具体名词
• [ ] 是否有形容词堆砌?用数据或事实替代
• [ ] 代码注释是否必要?删除显而易见的注释
• [ ] 是否有铺垫性内容?考虑直接进入主题

步骤 4: 结构优化

**信息架构优化:** 1. **结论前置**: 核心观点放在段落/章节开头 2. **递进关系**: 从简单到复杂,从概念到实践 3. **模块化**: 每个章节独立完整,可单独阅读 4. **交叉引用**: 相关内容提供跳转链接

步骤 5: 质量检查

**发布前检查清单:**

**内容完整性:**

• [ ] 核心概念都有清晰定义
• [ ] 每个重要知识点都有示例
• [ ] 代码示例都可运行
• [ ] 包含版本/环境信息

**语言简练性:**

• [ ] 无冗余词汇(很、非常、极其等)
• [ ] 无模糊表达(可能、也许、大概)
• [ ] 每句话都有实质内容
• [ ] 段落间无重复信息

**实用性:**

• [ ] 提供可执行步骤
• [ ] 标注常见陷阱
• [ ] 包含最佳实践
• [ ] 给出扩展资源

**可读性:**

• [ ] 标题层级清晰(不超过 3 级)
• [ ] 代码块有语言标注
• [ ] 关键信息有视觉强调
• [ ] 章节长度适中(不超过 800 字)

标题撰写公式

干货文章标题特点:**功能性 > 吸引力**

**推荐格式:**

1. **问题解决型:**

• "解决 X 问题的 3 种方法"
• "如何优化 X 性能"
• "X 报错的完整解决方案"

2. **知识传授型:**

• "深入理解 X 原理"
• "X 核心概念详解"
• "X 工作机制解析"

3. **实践指南型:**

• "X 最佳实践指南"
• "X 从入门到精通"
• "实现 X 功能的完整指南"

4. **对比分析型:**

• "X vs Y: 技术选型指南"
• "X 的 5 种实现方式对比"
• "从 X 迁移到 Y 的完整指南"

**标题禁忌:**

• ❌ 标题党: "震惊!"、"必看!"、"99%的人不知道"
• ❌ 模糊: "谈谈 X"、"聊聊 Y"、"关于 Z 的思考"
• ❌ 过长: 超过 30 个汉字

特殊场景处理

场景 1: 复杂概念简化

**策略:** 1. **类比法**: 用日常生活类比技术概念 2. **拆解法**: 复杂概念拆分为 3-5 个子概念 3. **可视化**: 用图表或流程图展示关系

**示例:**

## 闭包原理

**日常类比:** 闭包就像一个保险箱,里面装着私有物品(变量),
只有持有钥匙的人(内部函数)才能访问。

**技术定义:** 函数与其词法环境的引用组合。

**核心特点:**
1. 内部函数访问外部函数变量
2. 外部函数执行完毕后变量仍保留
3. 形成私有作用域

场景 2: 版本差异说明

**策略:**

• 明确标注每个特性的版本要求
• 用表格对比不同版本差异
• 提供版本检测方法

**示例:**

## TypeScript 类型系统演进

| 特性 | 版本 | 关键变化 |
|------|------|---------|
| `unknown` 类型 | 3.0+ | 替代 `any` 的类型安全方案 |
| 可选链 `?.` | 3.7+ | 安全访问嵌套属性 |
| 模板字面量类型 | 4.1+ | 类型级字符串操作 |
| `satisfies` 操作符 | 4.9+ | 类型断言不丢失推断 |

**版本检测:**
\```bash
tsc --version  # 查看 TypeScript 版本
\```

场景 3: 性能优化建议

**策略:**

• 提供优化前后的性能数据对比
• 说明优化的时间/空间复杂度影响
• 标注适用规模(数据量级)

**示例:**

## 数组去重性能对比

| 方法 | 时间复杂度 | 10k 数据 | 100k 数据 | 推荐场景 |
|------|----------|---------|----------|---------|
| Set | O(n) | 2ms | 15ms | 通用首选 |
| filter | O(n²) | 80ms | 8000ms | 不推荐 |
| reduce | O(n²) | 75ms | 7500ms | 不推荐 |

**结论:** 数据量 > 1000 时,优先使用 `Set` 方案。

**代码实现:**
\```typescript
// 推荐: 使用 Set (O(n))
const unique = [...new Set(array)];

// 不推荐: filter (O(n²))
const unique = array.filter((item, index) =>
  array.indexOf(item) === index
);
\```

常见问题处理

Q1: 如何平衡"简练"和"完整"?

**原则:**

• 核心知识点(P0)必须完整,不能省略
• 补充信息(P2)可用"扩展阅读"链接代替
• 同一信息只出现一次,后续用引用

**示例:**

## React Hooks 规则

**核心规则:**
1. 只在顶层调用(不在循环/条件/嵌套函数中)
2. 只在 React 函数组件或自定义 Hook 中调用

**原理:** React 依赖 Hook 调用顺序维护状态。[详细原理](链接)

**违规示例:**
\```typescript
// ❌ 错误: 条件调用
if (condition) {
  const [state] = useState(0);  // 违反规则 1
}

// ✅ 正确: 顶层调用
const [state] = useState(0);
if (condition) {
  // 使用 state
}
\```

Q2: 技术名词是否需要解释?

**判断标准:**

• 根据目标读者(新手/中级/高级)决定
• 首次出现时用括号注释,后续直接使用
• 过于基础的概念提供外部链接而非详细解释

**示例:**

## Webpack 配置优化

使用 Tree Shaking(死代码消除)减少打包体积。
配置 `mode: 'production'` 自动启用。

关于 Tree Shaking 的详细原理,参考[官方文档](链接)。

**配置示例:**
\```javascript
module.exports = {
  mode: 'production',  // 启用 Tree Shaking
  optimization: {
    usedExports: true
  }
};
\```

Q3: 何时使用代码注释?

**注释原则:**

• ✅ 解释"为什么这样做"(非显而易见的设计决策)
• ✅ 标注关键参数的业务含义
• ✅ 说明性能考量或边界条件
• ❌ 不重复代码本身已经表达的内容

**示例对比:**

// ❌ 低质量注释
// 创建一个数组