diff --git a/README.md b/README.md index 74201d5..b7b50de 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,8 @@ This section will list available skills as they are added. | [git-commit-generator](skills/git-commit-generator/SKILL.md) | Generate standardized git commit messages based on code changes (diffs), following Conventional Commits specification. | Git Operations, Code Review | Stable | | [cn-punctuation-checker](skills/cn-punctuation-checker/SKILL.md) | Checks Chinese text for incorrect English punctuation marks and supports batch fixing. | Chinese Copy Editing, Punctuation Correction | Stable | | [wechat-mini-program-development](skills/wechat-mini-program-development/SKILL.md) | WeChat mini-program development skill with standard project structure, request wrapper, and API management. | WeChat Mini-Program Development, Project Scaffolding | Stable | +| [kz-article-deep-analysis](skills/kz-article-deep-analysis/SKILL.md) | Deeply interpret non-academic articles (blogs, essays, commentary) and output a structured analysis report (core issue, thesis, argument map, cognitive gains). | Reading, Article Analysis | Stable | + > Tip: To add your skill to this catalog, update this table in your PR. diff --git a/README.zh-CN.md b/README.zh-CN.md index 708615e..7761c25 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -99,6 +99,7 @@ description: 简要描述这个技能的功能和使用场景 | [git-commit-generator](skills/git-commit-generator/SKILL.md) | 根据代码变更（diffs）生成标准化、符合 Conventional Commits 规范的 git 提交信息。 | Git 操作, 代码评审 | Stable | | [cn-punctuation-checker](skills/cn-punctuation-checker/SKILL.md) | 检查中文文案中错误使用的英文标点符号，并支持批量修复。 | 中文文案润色, 标点纠错 | Stable | | [wechat-mini-program-development](skills/wechat-mini-program-development/SKILL.md) | 微信小程序开发专用技能，提供标准项目结构、请求封装和 API 管理。 | 微信小程序开发, 项目脚手架 | Stable | +| [kz-article-deep-analysis](skills/kz-article-deep-analysis/SKILL.md) | 深度解读非学术类文章（博客、随笔、评论），输出结构化分析报告（核心议题、核心主张、论证拓扑、认知增量）。 | 深度阅读, 文章分析 | Stable | > 提示：要把你的技能加入此目录，请在 PR 中更新此表格。 diff --git a/skills/kz-article-deep-analysis/SKILL.md b/skills/kz-article-deep-analysis/SKILL.md new file mode 100644 index 0000000..956d87b --- /dev/null +++ b/skills/kz-article-deep-analysis/SKILL.md @@ -0,0 +1,93 @@ +--- +name: kz-article-deep-analysis +description: 深度解读非学术类文章（博客、随笔、评论），抽取核心议题与核心主张，评估其对读者认知的增量与张力，输出结构化分析报告。 +version: 1.0.3 +metadata: + author: K叔 +--- + +# 文章深度解读 + +> **版本**: v1.0.3 +> **作者**: K叔 +> **用途**: 深度挖掘文章的核心逻辑与认知价值 +> **适用范围**: 博客、公众号文章、随笔、评论（不适用于学术论文或书籍） + +你是一个深度阅读者，你的任务是穿透文章的表面信息，抽取其**核心议题**、**核心主张**，并评估对读者的**认知增量**。 + +## 核心任务 + +1. **解构文章**：识别作者试图回应的核心议题与核心主张，梳理论证逻辑。 +2. **认知增量**：评估文章观点与读者既有认知的差异与张力，提炼可复用的洞见。 + +## 使用示例 + +**示例 1：URL 输入** + +用户： +> 帮我深度解读这篇文章：https://docs.trae.ai/ide/best-practice-for-how-to-write-a-good-skill?_lang=zh + +你： +- @动作: 使用 WebFetch 抓取文章正文并提取标题/作者。 +- @动作: 按 [template.md](assets/template.md) 输出完整解读报告，至少包含： + - 核心议题（下探到更本质的矛盾/约束/利益冲突） + - 核心主张（一句话中心命题） + - 论证骨架（≤3 个关键论据 + 隐含假设 + 边界条件） + - 推理拓扑图（ASCII） + - 认知增量点（带 ASCII Art 认知卡片） + +## @工作流: 深度解读 + + + + + + +### @步骤1: 获取与预处理 + + + + + + +- @动作: 如果用户提供 URL，使用 WebFetch 获取内容。 +- @动作: 如果用户提供文本，直接使用。 +- @动作: 提取文章的标题和作者（如果有）。 + +### @步骤2: 深度解构（文章说了什么） + + + + + + +- @动作: 抽取核心议题：作者真正试图回应的是什么？将标题/引子中的表层问题下探为更本质的矛盾、约束或利益冲突。（参考 [methodology.md](references/methodology.md)） +- @动作: 提炼核心主张：用一句话概括作者的中心命题；缺失该命题则全文论证失去支点。 +- @动作: 梳理论证骨架：提取关键论据（3个以内）、隐含假设和边界条件。 +- @动作: 绘制推理拓扑图：使用 ASCII 拓扑图展示从核心议题到核心主张的推理路径。 + +### @步骤3: 认知增量（对我意味着什么） + + + + + + +- @动作: 定位增量点：基于理性批判视角（或用户提供的背景），找出文章改变判断、揭示盲区或补充框架的关键位置。（参考 [methodology.md](references/methodology.md)） +- @动作: 绘制认知卡片：为每个重要增量点绘制 ASCII Art 卡片，直观展示结构关系（分叉、汇聚、层级、对比）。 + +### @步骤4: 生成报告 + + + + + + +- @动作: 按照 [template.md](assets/template.md) 的结构生成最终报告。 + +## 版本历史 + +- **v1.0.3** (2026-03-07) - 增加使用示例。 +- **v1.0.2** (2026-03-07) - 术语专业化，并统一文档表述。 +- **v1.0.1** (2026-03-07) - 添加作者元数据。 +- **v1.0.0** (2026-03-07) - 初始版本。 diff --git a/skills/kz-article-deep-analysis/assets/template.md b/skills/kz-article-deep-analysis/assets/template.md new file mode 100644 index 0000000..69dee0d --- /dev/null +++ b/skills/kz-article-deep-analysis/assets/template.md @@ -0,0 +1,49 @@ +# 深度解读：{文章标题} + +> **日期**: {YYYY-MM-DD} +> **来源**: {URL} + +## 1. 文章说了什么 + +**核心议题**: {表层问题之下，作者真正试图回应的更本质议题} + +**核心主张**: {一句话中心命题——缺失该命题则论证失去支点} + +**论证骨架**: +- {关键论据1} +- {关键论据2} +- {关键论据3} + +**隐含假设**: {被默认为真的前提} + +**边界**: {什么条件下失效} + +``` +{论证拓扑图：从核心议题到核心主张的 ASCII 推理路径} +``` + +## 2. 对我意味着什么 + +*{若认知增量≈0，则写“认知增量为 0：文章未显著改变或补充我的判断。”；若有增量，则每个要点单列一个小节。}* + +### {认知增量点1} + +``` +{ASCII art 认知卡片——结构关系本身表达含义} +``` + +> {一句话启发——脱离文章上下文单独成立} + +### {认知增量点2} + +``` +{ASCII art 认知卡片} +``` + +> {一句话启发} + +## 3. 迁移 + +*{仅当洞见的生成机制在另一领域同构时撰写；不预设领域；不满足条件则删除本节。}* + +**{领域}**: {如何应用——可操作的新视角} diff --git a/skills/kz-article-deep-analysis/references/methodology.md b/skills/kz-article-deep-analysis/references/methodology.md new file mode 100644 index 0000000..af74895 --- /dev/null +++ b/skills/kz-article-deep-analysis/references/methodology.md @@ -0,0 +1,40 @@ +# 文章解读方法论 + +## 核心议题抽取 + +多数文章的标题与开头呈现的是“表层问题”。作者实际回应的往往是更深层的议题。 + +三条线索： +1. **看反对**：作者在反驳什么——被反驳的对象往往暴露核心议题 +2. **看重复**：作者反复回到哪里——重复往往指向其核心关注与关键约束 +3. **看情绪**：作者在哪里情绪最重——情绪强度常指向利益冲突或心理动因 + +示例： +- 表面问题："如何高效阅读" +- 核心议题可能是："读了那么多为什么没用"（焦虑驱动） +- 也可能是："为什么别人读得比我快"（比较驱动） + +核心议题不同，同一篇文章的价值判断往往会发生明显偏移。 + +## 认知张力评估 + +认知张力 = 文章观点与既有认知的交互所形成的差异与更新。三种常见形态： + +| 类型 | 信号 | 价值 | +|------|------|------| +| 强化 | "对，我也这么想" | 低（确认偏误风险） | +| 补充 | "这个角度我没想过" | 中 | +| 冲突 | "不对，我认为相反" | 高（需要细看） | + +认知增量≈0 的判断标准：上述三种形态都没有实质发生。这是正常结果，大部分文章不会产生明显增量；避免为了“有洞见”而强行制造差异。 + +## 迁移判断 + +迁移不是“把文章观点套到别的领域”。迁移是识别文章的核心机制在另一个领域同样成立，但未被显性命名或系统化表达。 + +判断标准： +- 两个领域的**生成规则**同构（不只是表面类比） +- 迁移后能产生**可操作**的新视角（不只是"有趣"） +- 去掉原文上下文，迁移仍然成立 + +不满足以上三条，不写迁移；宁可省略该部分。 diff --git a/skills/kz-article-deep-analysis/scripts/verify.py b/skills/kz-article-deep-analysis/scripts/verify.py new file mode 100755 index 0000000..42fb303 --- /dev/null +++ b/skills/kz-article-deep-analysis/scripts/verify.py @@ -0,0 +1,83 @@ +#!/usr/bin/env python3 +""" +Verify script for article-deep-analysis + +This script provides deterministic checks that complement SKILL.md instructions. +""" + +import argparse +import re +import sys +from pathlib import Path + + +def _read_text(path: Path): + return path.read_text(encoding="utf-8") + + +def _extract_frontmatter(markdown: str): + match = re.match(r"\A---\s*\n([\s\S]*?)\n---\s*\n", markdown) + if not match: + return None + return match.group(1) + + +def _has_required_frontmatter(frontmatter: str): + required_keys = ["name:", "description:", "version:"] + return all(key in frontmatter for key in required_keys) + + +def verify(skill_dir: Path): + errors = [] + + skill_md = skill_dir / "SKILL.md" + if not skill_md.exists(): + errors.append("Missing SKILL.md: " + str(skill_md)) + else: + try: + content = _read_text(skill_md) + except Exception as e: + errors.append("Failed to read SKILL.md: " + str(e)) + content = "" + + frontmatter = _extract_frontmatter(content) if content else None + if not frontmatter: + errors.append("SKILL.md missing YAML frontmatter (--- ... ---)") + elif not _has_required_frontmatter(frontmatter): + errors.append("SKILL.md frontmatter must include name/description/version") + + if "## @工作流:" not in content: + errors.append("SKILL.md must include a '## @工作流:' section") + + if "## 版本历史" not in content: + errors.append("SKILL.md must include a '## 版本历史' section") + + if not (skill_dir / "references" / "methodology.md").exists(): + errors.append("Missing references/methodology.md") + + if not (skill_dir / "assets" / "template.md").exists(): + errors.append("Missing assets/template.md") + + if errors: + for message in errors: + print("ERROR: " + message) + return 1 + + print("OK: basic skill structure checks passed") + return 0 + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument("--skill", required=True, help="Skill folder path") + args = parser.parse_args() + + skill_dir = Path(args.skill).resolve() + if not skill_dir.exists(): + print("ERROR: skill folder not found: " + str(skill_dir)) + sys.exit(1) + + sys.exit(verify(skill_dir)) + +if __name__ == "__main__": + main()