@rongyan/opensource-analyzer 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @rongyan/opensource-analyzer
+
+把 `opensource-analyzer` 技能作为 npm 包分发，并通过 `npx` 安装到不同 AI Agent 的技能目录。
+
+## 使用
+
+```bash
+npx @rongyan/opensource-analyzer install --target codex
+npx @rongyan/opensource-analyzer install --target claude-code
+npx @rongyan/opensource-analyzer install --target opencode
+```
+
+## 安装位置
+
+| Target | 默认安装目录 |
+| --- | --- |
+| `codex` | `$CODEX_HOME/skills/opensource-analyzer`，未设置时为 `~/.codex/skills/opensource-analyzer` |
+| `claude-code` | `~/.claude/skills/opensource-analyzer` |
+| `opencode` | `$XDG_CONFIG_HOME/opencode/skills/opensource-analyzer`，未设置时为 `~/.config/opencode/skills/opensource-analyzer` |
+
+## CLI 选项
+
+```bash
+npx @rongyan/opensource-analyzer install --target codex --dry-run
+npx @rongyan/opensource-analyzer install --target codex --force
+npx @rongyan/opensource-analyzer install --target codex --dest /custom/skill/path
+```
+
+- `--force`：覆盖已有但不是由本包安装的同名技能目录中的技能文件。
+- `--dry-run`：只展示目标路径，不写入文件。
+- `--dest`：覆盖默认安装目录，主要用于测试或自定义 Agent 配置。
+
+## 发布
+
+```bash
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+发布前请根据你的授权方式更新 `package.json` 的 `license` 字段；当前保守标记为 `UNLICENSED`。

package/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: opensource-analyzer
+description: 深度分析 GitHub 或本地开源项目，生成结构化介绍文章、选型报告或分享稿。Use when the user asks to analyze an open-source project, explain a GitHub repository, research a library, compare similar projects, write a technical article about a repo, or evaluate whether a project is production-ready. 中文请求默认输出中文，技术术语保留英文原文。
+---
+
+# 开源项目分析 SKILL
+
+## 目标
+基于用户提供的 GitHub 仓库、包名或本地仓库路径，按六层分析框架完成深度研究，最终生成可直接发布的介绍文章、选型报告或分享稿。
+
+---
+
+## 第一步：信息收集
+
+在分析前，使用可用的 Web、GitHub、包管理器或本地文件工具抓取以下数据。所有动态数据都要注明查询日期；如果无法获取，不要编造，直接标注"未查到"或"无法验证"。
+
+**来源优先级：**
+1. 官方仓库、README、文档站、Release notes、源码
+2. GitHub Issues/Discussions/PR、维护者博客
+3. 包管理器页面（npm/PyPI/crates.io 等）、基准测试、第三方测评
+4. Hacker News、Reddit、社交媒体讨论（仅作社区反馈，不当成事实来源）
+
+**必须获取：**
+- 仓库主页（README 全文）
+- Star 数、Fork 数、Watch 数
+- 最近 commit 时间、commit 频率（过去 30 天）
+- Issue 数量（open vs closed）、PR 状态
+- License 类型
+- 主要编程语言占比
+- 贡献者数量及核心贡献者背景
+
+**尽量获取：**
+- Releases 页面（最新版本、更新节奏）
+- 项目官网或文档站
+- 相关技术博客、论文或讨论（Hacker News、Reddit 等）
+- npm/PyPI/crates.io 等包管理器的下载量
+
+> 如果仓库是私有的或无法访问，告知用户并请求提供 README 文本或代码片段。
+> 如果用户提供本地路径或当前工作区，优先读取本地 README、源码、配置和测试；外部数据只用于补充维护状态、社区热度和生态采用情况。
+> 默认不要执行未知仓库的代码。确需运行示例或测试时，先说明风险，并尽量使用隔离环境。
+
+---
+
+## 第二步：六层分析框架
+
+按顺序完成每一层，每层都要形成明确结论，不要跳过。
+
+### 层1：定位分析
+回答三个问题：
+1. **诞生背景**：在什么时间点、什么技术背景下出现？有没有明确的"替代品"或"竞争对手"？
+2. **核心痛点**：它解决了什么已有方案解决不好的问题？（直接引用 README 中的原文定位）
+3. **目标用户**：个人开发者？企业用户？特定语言/框架生态的用户？
+
+### 层2：技术解剖
+1. **架构概览**：核心模块有哪些？整体数据流是什么？
+2. **关键设计决策**：有没有打破常规的实现方式？（例如：不用 ORM 而直接写 SQL、用 Rust 重写性能关键路径等）
+3. **代码亮点**：找到 1-2 个最能体现该项目价值的核心代码片段或 API 设计，并解释为什么巧妙
+4. **依赖分析**：主要依赖什么？有没有重量级依赖可能带来问题？
+
+### 层3：生态评估
+1. **维护健康度**：最近 commit 距今多久？Issue 响应速度如何？有无长期悬而未决的关键 bug？
+2. **社区活跃度**：贡献者多样性、Discord/Slack/论坛是否活跃
+3. **采用情况**：谁在用？有没有知名公司背书或 case study？
+4. **竞品对比**：列出 2-3 个同类方案，对比核心差异（见 references/competitor-matrix.md 获取对比维度模板）
+
+### 层4：实战评价
+1. **上手曲线**：安装配置需要几步？有无前置知识门槛？
+2. **典型使用场景**：最适合什么规模/场景的项目？
+3. **已知局限**：文档或 issue 中提到的主要限制、性能瓶颈、不支持的场景
+4. **生产就绪度**：是否有人在生产环境中大规模使用？稳定性如何？
+
+### 层5：风险与成本
+1. **技术风险**：API 稳定性、破坏性变更频率、性能边界、安全漏洞历史
+2. **维护风险**：bus factor、核心维护者是否活跃、关键 issue 是否长期未解决
+3. **迁移成本**：引入成本、替换成本、锁定效应、与现有技术栈的耦合
+4. **合规风险**：License 是否允许商业使用，有无依赖许可证冲突
+
+### 层6：综合判断
+给出明确观点，而不是"视情况而定"。
+- **适合谁**：列出最匹配的用户、团队规模和项目阶段
+- **不适合谁**：列出至少 2 类不建议采用的场景
+- **选型结论**：推荐/谨慎试用/暂不推荐，并说明关键理由
+- **评分（选型类文章必需）**：从易用性、文档质量、性能、社区活跃度、生产可靠性给 1-5 分
+
+---
+
+## 第三步：文章生成
+
+### 确认受众
+在写作前，先明确目标读者（如果用户没有说明，默认为"中级开发者"）：
+- **入门级**：少用技术术语，多用类比，重点放在"能做什么"
+- **中级开发者**：平衡原理与实践，给出可运行的代码示例
+- **高级/架构师**：深入设计决策与权衡，关注性能、可扩展性
+
+### 文章结构模板
+
+严格按以下结构写作，每个部分都不能省略：
+
+```
+# {项目名}：{一句话价值主张}
+
+## TL;DR
+（3-5 句话：是什么、解决什么问题、适合谁用）
+
+## 背景：为什么需要它
+（讲清楚现有方案的痛点，引出这个项目的出现）
+
+## 核心功能
+（2-4 个核心功能，每个配一个最小代码示例）
+
+## 它是怎么工作的
+（架构原理，用图表或伪代码辅助说明，重点讲设计亮点）
+
+## 谁在用它，怎么用的
+（真实案例或典型使用场景，避免空泛）
+
+## 优势与局限
+（客观列出，局限部分至少 2 条，这是文章可信度的关键）
+
+## 5 分钟上手
+（最精简的安装 + 运行步骤，确保读者能跑起来）
+
+## 与同类方案对比
+（对比表格，聚焦差异而非罗列所有特性）
+
+## 总结与展望
+（作者观点：适合场景、不适合场景、对未来的判断）
+```
+
+### 写作规范
+- **代码示例**：每个可演示的功能点至少一个可运行的最小示例；如果不是库项目，用 CLI、配置或伪代码展示核心工作流
+- **客观性**：不要只写优点，局限性部分要具体（避免"有些场景不适用"这种废话）
+- **引用来源**：技术描述尽量引用官方文档或源码，不要凭空描述
+- **不确定性**：对无法验证的采用案例、性能数据或维护状态，要明确写出不确定性
+- **长度控制**：技术博客文章目标 2000-4000 字，选型报告可到 5000 字
+
+---
+
+## 特殊场景处理
+
+### 场景：用户给了本地仓库路径
+读取本地 README、package/pyproject/Cargo 等配置、目录结构、核心源码和测试。再按需联网补充 Star、Release、Issue、包下载量等动态信息。
+
+### 场景：用户只给了一个库名，没有 URL
+先用 web_search 确认仓库地址，确认后再开始分析。如果有多个同名仓库，列出让用户选择。
+
+### 场景：用户要做选型对比
+参考 `references/competitor-matrix.md`，生成结构化的对比矩阵，最后给出明确建议（"推荐 A 用于 X 场景，推荐 B 用于 Y 场景"）。
+
+### 场景：仓库很新（< 6 个月）或 Star 数很少（< 500）
+在文章开头加风险提示："该项目尚处于早期阶段，API 可能不稳定，不建议直接用于生产环境。"
+
+### 场景：用户要求中文文章
+默认输出中文，技术术语保留英文原文（如：`middleware`、`tree-shaking`），不要强行翻译成生僻中文。
+
+### 场景：用户要生成 PPT/分享稿而非文章
+参考六层框架，但输出结构改为：背景（1页）→ 核心价值（1页）→ 工作原理（2页）→ Demo（1页）→ 适用场景（1页）→ Q&A。
+
+---
+
+## 质量检查清单
+
+文章写完后，逐项自检：
+
+- [ ] 有没有说清楚"它解决了什么问题"（不只是"它能做什么"）
+- [ ] 动态数据有没有标注查询日期？
+- [ ] 代码示例能直接复制运行吗？
+- [ ] 局限性部分有 2 条以上具体描述
+- [ ] 有竞品对比
+- [ ] 有上手指南（不依赖读者自己找文档）
+- [ ] 有对"适合谁"的明确定位
+- [ ] 对无法验证的信息有没有明确标注不确定性？
+
+---
+
+## 参考文件
+
+- `references/competitor-matrix.md`：用户要求选型对比或需要竞品矩阵时读取
+- `references/article-examples.md`：需要校准文章质量、开头写法、局限性表达或结论立场时读取

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Open Source Analyzer"
+  short_description: "Analyze open-source projects and repos"
+  default_prompt: "Use $opensource-analyzer to analyze this GitHub repository: https://github.com/owner/repo"

package/bin/opensource-analyzer.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const packageJson = require(path.join(packageRoot, "package.json"));
+
+const skillName = "opensource-analyzer";
+const manifestFile = ".opensource-analyzer-install.json";
+const installItems = ["SKILL.md", "references", "agents"];
+
+const targetAliases = {
+  claude: "claude-code",
+  claudecode: "claude-code",
+  "claude_code": "claude-code",
+  "open-code": "opencode",
+  open_code: "opencode"
+};
+
+const targets = {
+  codex: {
+    label: "Codex",
+    directory() {
+      const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+      return path.join(codexHome, "skills", skillName);
+    }
+  },
+  "claude-code": {
+    label: "Claude Code",
+    directory() {
+      return path.join(os.homedir(), ".claude", "skills", skillName);
+    }
+  },
+  opencode: {
+    label: "OpenCode",
+    directory() {
+      const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+      return path.join(configHome, "opencode", "skills", skillName);
+    }
+  }
+};
+
+function printHelp() {
+  console.log(`@rongyan/opensource-analyzer ${packageJson.version}
+
+Usage:
+  npx @rongyan/opensource-analyzer install --target codex
+  npx @rongyan/opensource-analyzer install --target claude-code
+  npx @rongyan/opensource-analyzer install --target opencode
+
+Commands:
+  install                 Install or update the skill for one agent.
+
+Options:
+  --target <agent>        codex, claude-code, or opencode.
+  --dest <path>           Override the final skill directory.
+  --force                 Overwrite an existing unmanaged skill directory.
+  --dry-run               Show what would be installed without writing files.
+  -h, --help              Show this help.
+  -v, --version           Show package version.
+`);
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exitCode = 1;
+}
+
+function parseArgs(argv) {
+  const options = {
+    command: argv[0],
+    target: undefined,
+    dest: undefined,
+    force: false,
+    dryRun: false,
+    help: false,
+    version: false
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "-v" || arg === "--version") {
+      options.version = true;
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--target") {
+      options.target = readOptionValue(argv, index, "--target");
+      index += 1;
+    } else if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+    } else if (arg === "--dest") {
+      options.dest = readOptionValue(argv, index, "--dest");
+      index += 1;
+    } else if (arg.startsWith("--dest=")) {
+      options.dest = arg.slice("--dest=".length);
+    } else if (index > 0 && !arg.startsWith("-")) {
+      fail(`Unknown argument: ${arg}`);
+      return null;
+    } else if (index > 0) {
+      fail(`Unknown option: ${arg}`);
+      return null;
+    }
+  }
+
+  return options;
+}
+
+function readOptionValue(argv, index, optionName) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) {
+    fail(`${optionName} requires a value.`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function normalizeTarget(rawTarget) {
+  if (!rawTarget) {
+    return undefined;
+  }
+
+  const normalized = rawTarget.toLowerCase();
+  return targetAliases[normalized] || normalized;
+}
+
+function readManifest(destination) {
+  const manifestPath = path.join(destination, manifestFile);
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function assertSkillSources() {
+  const missing = installItems.filter((item) => !fs.existsSync(path.join(packageRoot, item)));
+  if (missing.length > 0) {
+    fail(`Package is missing required skill file(s): ${missing.join(", ")}`);
+    process.exit(1);
+  }
+}
+
+function copyItem(source, destination) {
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.rmSync(destination, { recursive: true, force: true });
+    fs.cpSync(source, destination, { recursive: true });
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+}
+
+function writeManifest(destination, target) {
+  const manifest = {
+    packageName: packageJson.name,
+    packageVersion: packageJson.version,
+    skillName,
+    target,
+    installedAt: new Date().toISOString(),
+    managedFiles: installItems
+  };
+
+  fs.writeFileSync(
+    path.join(destination, manifestFile),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8"
+  );
+}
+
+function installSkill(options) {
+  const targetName = normalizeTarget(options.target);
+  if (!targetName || !targets[targetName]) {
+    fail("Missing or invalid --target. Use one of: codex, claude-code, opencode.");
+    process.exit(1);
+  }
+
+  assertSkillSources();
+
+  const destination = path.resolve(options.dest || targets[targetName].directory());
+  const existing = fs.existsSync(destination);
+  const manifest = existing ? readManifest(destination) : null;
+  const isManaged = Boolean(manifest && manifest.packageName === packageJson.name);
+
+  if (existing && !fs.statSync(destination).isDirectory()) {
+    fail(`Destination exists but is not a directory: ${destination}`);
+    process.exit(1);
+  }
+
+  if (existing && !isManaged && !options.force) {
+    fail(
+      `Destination already exists and was not installed by this package: ${destination}\n` +
+        "Use --force to overwrite the skill files there, or choose another --dest."
+    );
+    process.exit(1);
+  }
+
+  const action = existing ? "Update" : "Install";
+  const label = targets[targetName].label;
+  console.log(`${action} ${skillName} for ${label}`);
+  console.log(`Destination: ${destination}`);
+
+  if (options.dryRun) {
+    console.log("Dry run: no files written.");
+    return;
+  }
+
+  fs.mkdirSync(destination, { recursive: true });
+  for (const item of installItems) {
+    copyItem(path.join(packageRoot, item), path.join(destination, item));
+  }
+  writeManifest(destination, targetName);
+
+  console.log(`Done. Restart or reload ${label} if it does not pick up new skills immediately.`);
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options) {
+    return;
+  }
+
+  if (options.version) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  if (options.help || !options.command) {
+    printHelp();
+    return;
+  }
+
+  if (options.command !== "install") {
+    fail(`Unknown command: ${options.command}`);
+    process.exit(1);
+  }
+
+  installSkill(options);
+}
+
+main();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@rongyan/opensource-analyzer",
+  "version": "0.1.0",
+  "description": "Install the opensource-analyzer AI agent skill with npx.",
+  "type": "commonjs",
+  "bin": {
+    "opensource-analyzer": "./bin/opensource-analyzer.js"
+  },
+  "files": [
+    "SKILL.md",
+    "references",
+    "agents",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node scripts/smoke-test.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "ai-agent",
+    "codex-skill",
+    "claude-code-skill",
+    "opencode-skill",
+    "opensource"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/references/article-examples.md

@@ -0,0 +1,87 @@
+# 高质量开源库介绍文章的特征分析
+
+本文档总结了优秀技术文章的共同特征，供写作时参考对标。
+
+---
+
+## 什么让一篇开源库介绍文章变得出色
+
+### 1. 开篇立即抓住痛点
+**差的写法：** "今天介绍一个很棒的开源库叫做 Zod，它是一个 TypeScript 优先的模式验证库。"
+**好的写法：** "你有没有写过这样的代码：后端 API 定义了类型，前端 TypeScript 也定义了类型，但两边的类型完全独立，一旦后端改了字段，前端只能在运行时才发现？Zod 要解决的就是这个问题。"
+
+**原则：** 开篇应该让读者说"对！这就是我的问题"，而不是描述这个库是什么。
+
+---
+
+### 2. 最小可用示例要真正"最小"
+**差的写法：** 给出一个需要先配置 5 个文件才能运行的示例
+**好的写法：** 
+```typescript
+// 3 行代码展示核心价值
+import { z } from 'zod'
+const User = z.object({ name: z.string(), age: z.number() })
+User.parse({ name: "Alice", age: "25" }) // 抛出错误：age 应为 number
+```
+
+**原则：** 好的最小示例让读者在 30 秒内理解这个库"值在哪里"。
+
+---
+
+### 3. 原理解释要有"啊哈"时刻
+单纯列举 API 是文档的工作，不是文章的工作。好的原理解释应该让读者理解设计者"为什么这样设计"。
+
+**方法：**
+- 先展示"不用这个库，你会怎么做"——揭示繁琐之处
+- 再展示"用了之后"——对比落差产生啊哈时刻
+- 解释关键设计决策背后的权衡
+
+---
+
+### 4. 局限性要具体，不要模糊
+**差的写法：** "在某些复杂场景下可能存在性能问题。"
+**好的写法：** "当 schema 嵌套超过 5 层时，类型推导的 TypeScript 编译速度会明显下降。如果你的项目有大量深层嵌套的类型，需要考虑这个问题（issue #xxx 有详细讨论）。"
+
+---
+
+### 5. 结论要有立场
+**差的写法：** "总体来说，这是一个不错的库，适合需要验证的项目使用。"
+**好的写法：** "如果你在用 TypeScript 且有运行时数据验证需求（表单、API 返回值、环境变量），Zod 应该是你的默认选择，没有理由不用。如果你在 JavaScript 项目里，或者你的验证逻辑非常简单，可以考虑更轻量的 yup 或直接手写。"
+
+---
+
+## 不同类型文章的侧重点
+
+### 技术博客（个人/公司博客）
+- 语气：可以有个人观点，第一人称
+- 侧重：实际使用经验，踩过的坑
+- 长度：1500-3000 字
+- 代码比例：30-40%
+
+### 开源推荐（掘金/InfoQ/微信公众号）
+- 语气：中立客观，教程风格
+- 侧重：核心功能演示，上手路径
+- 长度：2000-4000 字
+- 代码比例：40-50%
+
+### 选型报告（内部决策文档）
+- 语气：正式，有数据支撑
+- 侧重：竞品对比，生产就绪度，风险
+- 长度：3000-6000 字
+- 代码比例：20-30%（更多表格和数据）
+
+### 团队分享/PPT
+- 语气：口语化，有故事性
+- 侧重：Demo 演示，Why Now
+- 长度：800-1500 字脚本
+- 代码比例：代码只在 Demo 部分
+
+---
+
+## 常见错误
+
+1. **把 README 翻译一遍**：这不是分析，只是搬运。文章价值在于作者视角的筛选和解读。
+2. **只写优点**：读者不信任只有优点的文章，会觉得是软文。
+3. **代码示例过长**：超过 30 行的示例应该放到 GitHub Gist，文章里只保留关键部分。
+4. **忽略版本信息**：技术文章要标注基于哪个版本，API 变化很快。
+5. **对比时贬低竞品**：应该客观陈述差异，不要说"A 比 B 差"，而是说"B 更适合 X 场景"。

package/references/competitor-matrix.md

@@ -0,0 +1,97 @@
+# 竞品对比维度模板
+
+当用户需要做开源库选型对比时，使用以下维度框架。
+
+---
+
+## 标准对比维度
+
+### 基础信息
+| 维度 | 说明 |
+|------|------|
+| 首次发布时间 | 项目成熟度参考 |
+| 最新版本 | 是否活跃迭代 |
+| License | 商业使用限制 |
+| 主要语言 | 技术栈匹配度 |
+| 包大小 | 对 bundle size 有影响的场景重要 |
+
+### 功能对比
+| 维度 | 说明 |
+|------|------|
+| 核心功能覆盖 | 解决同一问题的程度 |
+| 扩展/插件生态 | 能否满足定制需求 |
+| TypeScript 支持 | 类型安全 |
+| 框架集成 | React/Vue/Svelte 等 |
+| SSR 支持 | 服务端渲染场景 |
+
+### 性能
+| 维度 | 说明 |
+|------|------|
+| 基准测试结果 | 官方或第三方 benchmark |
+| 内存占用 | 长期运行场景 |
+| 冷启动时间 | Serverless 场景 |
+| 并发处理能力 | 高并发场景 |
+
+### 开发体验
+| 维度 | 说明 |
+|------|------|
+| 学习曲线 | 上手所需时间（小时/天） |
+| 文档质量 | 完整性、示例丰富度 |
+| 错误信息友好度 | 调试难易程度 |
+| DevTools 支持 | 有无调试工具 |
+| CLI 工具 | 脚手架、代码生成 |
+
+### 生态与社区
+| 维度 | 说明 |
+|------|------|
+| GitHub Stars | 社区认可度（注意：不代表质量） |
+| npm 周下载量 | 实际使用规模 |
+| 贡献者数量 | 社区健康度 |
+| Issue 响应速度 | 维护积极性 |
+| Stack Overflow 问题数 | 遇到问题时能否找到答案 |
+
+### 生产就绪度
+| 维度 | 说明 |
+|------|------|
+| 知名公司采用 | 背书可信度 |
+| 稳定性记录 | 有无重大安全漏洞历史 |
+| 版本兼容性 | 升级破坏性变更频率 |
+| 长期支持（LTS） | 企业采购关注点 |
+
+---
+
+## 对比表格模板
+
+```markdown
+|  | {库A} | {库B} | {库C} |
+|--|-------|-------|-------|
+| **定位** | | | |
+| **Star 数** | | | |
+| **包大小** | | | |
+| **学习曲线** | 低/中/高 | | |
+| **性能** | | | |
+| **TypeScript** | ✅/❌ | | |
+| **适合场景** | | | |
+| **不适合场景** | | | |
+| **推荐指数** | ⭐⭐⭐ | | |
+```
+
+---
+
+## 结论撰写规范
+
+不要写"各有优缺点，视情况而定"这种废话。
+必须给出明确的场景建议，格式如下：
+
+**选 A，如果：**
+- 你的项目是 XXX 场景
+- 你的团队更熟悉 XXX 技术栈
+- 性能是首要考虑因素
+
+**选 B，如果：**
+- 你需要更丰富的生态/插件
+- 项目规模较小，更看重上手速度
+- 已有 XXX 基础设施
+
+**都不选，如果：**
+- 你的场景是 XXX（推荐考虑 C 方案）