| name | insight-long-v1 |
| description | Use when writing in-depth technical articles, tutorials, industry analysis, or product/business model analysis (1000-3000 words) requiring structured bilingual content without personal narrative |
Insight Long Writing Skill v1
通用观点长文写作技巧(1000-3000字,适合技术博客)
核心定位
用于写作去个人化但有深度的技术/商业分析文章,保持Duanjl的思维方式但用更通用和结构化的视角。强制中英双语输出。适合技术博客、深度教程、行业分析。
适用场景
- 技术深度文章(如你的Protobuf、性能优化文章)
- 完整的技术教程
- 行业趋势深度分析
- 产品/商业模式解析
不适用场景
- 基于个人经历的反思(用personal-long-v1)
- 短推文(用insight-short-v1)
- 需要展示思考过程的探索性文章(用personal-long-v1)
写作流程
第一步:确认内容类型
用户提供的内容应该是:
- 技术方案、框架或模式的分析
- 可以复现的方法论
- 基于案例但非个人经历的洞察
第二步:规划文章结构
技术教程型:
- 问题背景/使用场景(200-400字)
- 核心原理/概念解释(400-800字)
- 实现方案/代码示例(600-1200字)
- 最佳实践/避坑指南(200-400字)
分析评论型:
- 现象描述/问题提出(200-400字)
- 原因分析/多角度拆解(600-1200字,可分3-4个维度)
- 解决方案/未来趋势(200-600字)
框架方法型:
- 为什么需要这个框架(200-400字)
- 框架的核心组成(600-1200字)
- 如何应用/案例说明(400-800字)
第三步:构建中文版本(主版本)
开头原则:
- 可以用具体场景引入,但不是个人经历
- 示例:"当团队规模增长到50人时,原有的沟通模式会失效。"(场景化但通用)
- 避免:"我在项目中遇到..."(改用"项目中常见的问题是...")
- 可以简短说明"为什么这个话题重要",但不要铺垫太长
主体展开策略:
-
结构化但不生硬
- 可以用小标题分段(如"## 核心问题"、"## 解决方案"),但标题要简洁
- 每个大段落300-600字
- 段落间要有过渡,不要突兀跳转
-
保持判断的存在
- 虽然去个人化,但要有明确观点
- 示例:"相比方案A,方案B更适合...因为..."
- 避免:"两种方案各有优劣"然后不给建议
-
案例和原理结合
- 先讲原理(WHY),再讲方法(HOW)
- 用假设性案例说明:"假设一个电商系统需要..."
- 技术细节要准确,但解释要通俗
-
代码/技术细节处理
- 代码示例要精简,只展示核心逻辑
- 复杂逻辑用文字解释,不要让代码块超过30行
- 技术术语第一次出现时简单解释
结尾原则:
- 总结核心要点(3-5条,每条1句话)
- 给出使用建议或注意事项
- 可以提延伸阅读,但不要只列链接
- 避免"希望本文对你有帮助"这种客套话
第四步:构建英文版本(非对称版本)
长文双语策略:
-
结构可以更规范
- 英文版可以用更标准的技术文档结构
- 小标题可以更直接(如"Implementation"而非"如何实现")
-
技术细节处理
- 代码注释用英文
- 技术解释可以引用英文官方文档
- 保持技术准确性一致
-
案例调整
- 中文可以用国内技术栈(如微信小程序、支付宝)
- 英文调整为国际常见技术(如React、AWS)
-
语气差异
- 中文可以稍微轻松,用一些口语化解释
- 英文更专业,但不要过于学术化
禁止事项(CRITICAL)
内容层面
❌ 只讲概念不给实现
❌ 堆砌技术名词不解释
❌ 没有明确观点,只陈述事实
❌ 用个人经历代替通用案例
表达层面
❌ 每段都用"首先...其次...最后"
❌ 过度使用"众所周知"、"显而易见"(如果真的众所周知就不用写了)
❌ 大段文字没有小标题或分段(超过800字不分段)
❌ 技术黑话堆砌(如"赋能"、"闭环"、"抓手")
技术层面
❌ 代码没有注释或解释
❌ 复杂概念没有类比或图示说明
❌ 只给结论不讲原理
❌ 技术细节错误或过时
双语层面
❌ 中英文技术栈不统一
❌ 代码示例在两个版本中不一致
❌ 英文版变成中文的机械翻译
去个人化但保持判断
主语替换:
- "我认为" → "更好的做法是"、"建议"
- "我的方案" → "推荐的方案"、"可行的方式"
- "我遇到的问题" → "常见的问题"、"典型场景"
判断表达:
- 即使去个人化,也要给明确建议
- 示例:"在选择数据库时,如果读写比超过10:1,Redis是更合适的选择"
- 避免:"这取决于具体情况"然后不给判断标准
经验转化:
- 个人踩坑 → "需要注意的陷阱"
- "我发现" → "实践中发现"、"测试表明"
技术写作最佳实践
代码示例:
async function fetchData(url) {
const response = await fetch(url);
return response.json();
}
❌ 避免:
- 几百行完整代码
- 没有注释的复杂逻辑
- 无法运行的伪代码
概念解释:
- 第一次出现:术语 + 简短解释
- 示例:"WebSocket(一种实时双向通信协议)允许..."
- 复杂概念用类比:"就像打电话和发短信的区别..."
结构层次:
- 最多三级标题(#、##、###)
- 每个小节有明确主题
- 避免标题嵌套过深
质量检查清单
发布前必须确认:
Markdown格式化要求
技术长文需要结构清晰、易于扫读、便于查找,同时保持专业性。
文本格式化规则
中英文混排规范:
- 中英文之间必须用空格隔开
- ✅ 正确: "我的 home 是北京"
- ❌ 错误: "我的home是北京"
- 中文和数字之间必须用空格隔开
- ✅ 正确: "我今年 30 岁"
- ❌ 错误: "我今年30岁"
- 数字和英文之间不要用空格隔开
- ✅ 正确: "下载速度约10Mbps"
- ❌ 错误: "下载速度约 10 Mbps"
- 英文专有名词、技术术语、代码片段前后都需要空格
- ✅ 正确: "使用 React 框架开发"
- ❌ 错误: "使用React框架开发"
标题层次
- 不使用一级标题(#),文章标题由发布平台处理
- 二级标题(##)划分主要章节,通常3-6个
- 示例:"性能优化的三个维度"、"资源加载的真实成本"、"常见陷阱"
- 标题要具体且有信息量,不要用"前言"、"正文"这种空标题
- 三级标题(###)用于章节内的细分,谨慎使用
- 不使用四级及以下标题
段落组织
- 每段4-7句话,主题明确
- 技术解释段落可以稍长,但不超过10句
- 概念定义段落要简短(2-4句)
- 段落间用空行分隔
强调技巧
加粗使用原则:
- 强调核心概念首次出现时的定义
- 示例:"关键路径优化是指优先处理影响首屏渲染的资源"
- 对比中的关键差异:"方案A适合X场景,方案B更适合Y场景"
- 每个章节最多3-4处加粗
列表使用原则:
✅ 适合列表的场景:
- 并列的技术要点(3-6项)
- 步骤说明
- 最佳实践总结
- 对比不同方案的优劣
❌ 不适合列表的场景:
- 每项超过3句话(应该用段落+小标题)
- 只有2项(直接写段落更自然)
- 嵌套超过2层
代码处理
代码块规范:
- 使用三个反引号包裹,标注语言:
javascript、python、bash
- 每个代码块不超过25行
- 必须有注释说明关键逻辑
- 代码块前后要有文字说明
代码示例:
const routes = [
{
path: '/',
component: () => import('./pages/Home')
}
]
行内代码:
- 技术术语用行内代码:
WebSocket、LCP、SSR
- 文件名、命令、配置项用行内代码:
package.json、npm install
- 不要过度使用(一句话里不超过3个行内代码)
结构化元素
何时使用列表总结:
- 每个大章节结束时,可以用3-5条列表总结要点
- 文章结尾的"核心要点"部分,用5-7条列表
- 每条列表项1-2句话,简明扼要
何时使用对比:
- 对比不同方案时,可以用表格(最多3列)
- 或用并列段落:"方案A的优势在于...方案B更适合..."
视觉节奏
每800-1000字插入呼吸点:
- 二级标题(新章节)
- 代码示例
- 列表总结
- 短段落(2-3句)
避免的模式:
- 连续5段以上都是长段落
- 连续3个代码块没有文字解释
- 整个章节只有一大段文字
- 一个章节里出现3个以上列表
格式示例
## 资源加载的真实成本
假设一个电商首页需要加载以下资源:HTML(15KB)、CSS(120KB)、JavaScript bundle(450KB)、首屏图片(总计800KB)。在4G网络(下行速度约10Mbps)下,理论上下载这些资源需要1.1秒。但实际的加载时间往往是3-5秒,为什么?
网络传输不是简单的下载速度计算。每个HTTP请求都有建立连接的开销(DNS查询、TCP握手、TLS协商),在移动网络下这个开销可能达到200-500ms。浏览器对同一域名的并发请求有限制(HTTP/1.1通常是6个),这意味着资源下载不是完全并行的。
更关键的是**JavaScript的执行成本**。一个450KB的bundle,压缩后可能是150KB,传输时间不长,但解析和执行可能需要2-3秒。
### 代码分割实现
使用动态import可以实现路由级别的代码分割:
\`\`\`javascript
// 路由配置中使用动态import
const routes = [
{
path: '/',
component: () => import('./pages/Home')
},
{
path: '/profile',
component: () => import('./pages/Profile')
}
]
\`\`\`
但代码分割也有成本:更多的网络请求和潜在的加载延迟。更好的策略是**预加载**(prefetch):当用户鼠标悬停在按钮上时,就开始加载对应的代码。
## 常见陷阱
性能优化中容易犯的错误包括:
- **过度优化**:在次要问题上投入大量时间
- **忽视缓存策略**:静态资源没有正确配置缓存头
- **第三方脚本失控**:每个脚本都可能引入额外开销
---
(其他章节省略)
---
## 核心要点
性能优化的关键在于:
- 建立测量体系,用真实用户数据而非实验室数据指导决策
- 优先优化关键路径,而非平均分配精力
- 代码分割需要配合预加载,避免引入新的延迟
- 资源加载的真实成本包括网络传输、解析和执行
- 建立性能预算和持续监控机制,防止性能退化
禁止的格式
❌ 使用emoji(除非图表说明需要)
❌ 使用引用块(>)强调观点(这不是引用)
❌ 过度使用加粗(每章节超过5处)
❌ 标题嵌套过深(超过三级)
❌ 表格超过4列(会难以阅读)
❌ 代码块超过30行(应该拆分或简化)
输出格式
封面图要求
每篇文章必须配两张5:2比例的封面图(1500x600px或同比例):
- 中文版封面: 基于技术主题或核心框架设计,风格专业简洁
- 英文版封面: 可以与中文版相同主题但调整技术栈示例
封面图设计原则:
- 避免过于抽象或商业化的stock photo风格
- 色调专业(技术类用科技感色调,蓝、灰、绿)
- 可以用架构图简化版、代码片段视觉化、或技术对比
- 不要在图片上添加文字(标题由平台处理)
- 技术长文封面可以暗示文章的核心框架或流程
- 5:2的宽幅比例适合展示技术架构流程图或多组件对比
文中配图要求
识别配图位置原则:
在以下位置插入配图可以提升阅读体验:
- 复杂概念首次解释后(帮助理解抽象概念)
- 架构图、流程图、对比图等结构化内容
- 每个主要章节(二级标题)开始前或结束后
- 连续文字超过 1000 字时插入呼吸点
- 代码示例的前后(视觉化代码逻辑或效果)
配图数量建议:
- 1000-1500 字文章: 1-2 张配图
- 1500-2500 字文章: 2-3 张配图
- 2500-3000 字文章: 3-4 张配图
- 不包括封面图
配图风格选择:
根据文章内容和段落主题智能选择配图风格:
- 科技感: 技术架构、系统设计、性能优化等技术主题
- 特征: 深色背景、蓝绿色调、电路板/网络节点元素、简洁几何
- 温暖/人文: 用户体验、产品思考、团队协作等人本主题
- 极简/抽象: 概念解释、原理说明、方法论等抽象主题
- 特征: 纯色背景、简单几何图形、图表化、信息图风格
- 对比/并列: 方案对比、优劣分析、before/after 等对比内容
- 流程/步骤: 操作步骤、流程说明、系统演进等序列内容
配图插入格式:
<!-- 在适当位置插入 -->
*图注: 简短说明图片内容或补充信息*
<!-- 继续正文 -->
配图描述(prompt)要求:
- 具体描述视觉元素,避免泛泛而谈
- 明确指定风格、色调、构图
- 与文章技术内容紧密相关
- 示例: "A minimalist tech illustration showing a data flow diagram with nodes and connections, dark blue background, modern geometric style, clean and professional"
最终输出结构
**中文版封面图**:
[生成中文版5:2封面图,描述具体的视觉元素和设计思路]
```markdown
[中文版本,1000-3000字,按上述格式要求排版]
<!-- 文中在合适位置插入2-4张配图,每张配图包括: -->
<!-- 1. 图片生成prompt(详细描述视觉元素、风格、色调) -->
<!-- 2. 图片占位符 -->
<!-- 3. 图注说明 -->
```
---
**英文版封面图**:
[生成英文版5:2封面图,描述具体的视觉元素和设计思路]
```markdown
[英文版本,1000-3000字,按上述格式要求排版]
<!-- 文中在合适位置插入2-4张配图,每张配图包括: -->
<!-- 1. 图片生成prompt(详细描述视觉元素、风格、色调) -->
<!-- 2. 图片占位符 -->
<!-- 3. 图注说明 -->
```
重要提醒:
- 文章内容必须用markdown代码块包裹(三个反引号)
- 严格遵守中英文、中文数字混排的空格规范
- 根据文章长度和内容合理安排配图数量和位置
- 配图风格要与段落主题匹配,提升而非干扰阅读
- 技术准确性 > 文学性
- 去个人化不等于没态度
- 结构化但不机械
- 让读者学到可复现的方法,而非只了解概念
- 格式服务于查找和理解:扫读能看到结构,细读能看到实现
- 封面图要体现技术架构或核心流程,不要用泛泛的技术图标
