From e8982b8c865fbaec4c101f44ac257a94325471ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A8=8A=E7=83=A8=E9=9C=8F?= Date: Sat, 7 Mar 2026 15:59:00 +0800 Subject: [PATCH 1/5] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E7=AB=A0=E6=B7=B1=E5=BA=A6=E8=A7=A3=E8=AF=BB=E6=8A=80=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/kz-article-deep-analysis/SKILL.md | 76 +++++++++++++++++ .../assets/template.md | 49 +++++++++++ .../references/methodology.md | 40 +++++++++ .../scripts/verify.py | 83 +++++++++++++++++++ 4 files changed, 248 insertions(+) create mode 100644 skills/kz-article-deep-analysis/SKILL.md create mode 100644 skills/kz-article-deep-analysis/assets/template.md create mode 100644 skills/kz-article-deep-analysis/references/methodology.md create mode 100755 skills/kz-article-deep-analysis/scripts/verify.py diff --git a/skills/kz-article-deep-analysis/SKILL.md b/skills/kz-article-deep-analysis/SKILL.md new file mode 100644 index 0000000..aafd387 --- /dev/null +++ b/skills/kz-article-deep-analysis/SKILL.md @@ -0,0 +1,76 @@ +--- +name: kz-article-deep-analysis +description: 深度解读非学术类文章（博客、随笔、评论），抽取核心议题与核心主张，评估其对读者认知的增量与张力，输出结构化分析报告。 +version: 1.0.2 +metadata: + author: K叔 +--- + +# 文章深度解读 + +> **版本**: v1.0.2 +> **作者**: K叔 +> **用途**: 深度挖掘文章的核心逻辑与认知价值 +> **适用范围**: 博客、公众号文章、随笔、评论（不适用于学术论文或书籍） + +你是一个深度阅读者，你的任务是穿透文章的表面信息，抽取其**核心议题**、**核心主张**，并评估对读者的**认知增量**。 + +## 核心任务 + +1. **解构文章**：识别作者试图回应的核心议题与核心主张，梳理论证逻辑。 +2. **认知增量**：评估文章观点与读者既有认知的差异与张力，提炼可复用的洞见。 + +## @工作流: 深度解读 + + + + + + +### @步骤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.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() From c229a70d5f4c9c5a706a9331acaaea5be6cae93f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A8=8A=E7=83=A8=E9=9C=8F?= Date: Sat, 7 Mar 2026 16:39:13 +0800 Subject: [PATCH 2/5] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=85=B1=E5=88=9B=E6=8A=80=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/kz-doc-coauthoring/SKILL.md | 185 ++++++++++++++++++++ skills/kz-doc-coauthoring/scripts/verify.py | 165 +++++++++++++++++ 2 files changed, 350 insertions(+) create mode 100644 skills/kz-doc-coauthoring/SKILL.md create mode 100755 skills/kz-doc-coauthoring/scripts/verify.py diff --git a/skills/kz-doc-coauthoring/SKILL.md b/skills/kz-doc-coauthoring/SKILL.md new file mode 100644 index 0000000..c52eac1 --- /dev/null +++ b/skills/kz-doc-coauthoring/SKILL.md @@ -0,0 +1,185 @@ +--- +name: kz-doc-coauthoring +description: 文档共创工作流。用于用户要写文档/提案/技术规格/决策记录/RFC/README/操作手册等结构化内容时；也适用于把零散讨论与上下文整理成可被他人阅读、复用、再提问的文档。 +version: 1.0.3 +metadata: + author: K叔 +--- + +# Doc Coauthoring（文档共创） + + + + +> **版本**: v1.0.3 +> **作者**: K叔 +> **用途**: 以“收集上下文 → 搭骨架 → 逐段写作 → 读者测试”的流程共创文档 +> **适用范围**: 技术规格/设计文档/决策记录/RFC/提案/README/操作手册/项目说明 + +## 最小模板规范 + +为保证“可复用/可验证/可交付”，默认遵循以下最小输出规范（可按具体文档类型增删章节）： + +- 文档文件：统一用 `${DOC_PATH}` 指代最终文档文件路径；若用户未指定，默认建议 `rfc.md` / `design.md` / `decision.md` / `proposal.md` / `README.md` / `runbook.md` +- Stage 1 结束必须产出：写作契约（文档类型/受众/预期影响/约束/未知点） +- Stage 3 结束必须产出：目录骨架 + 每章一句“本章要回答的问题” +- 完稿必须包含（如适用）：结论/决策、范围与非目标、风险与权衡、下一步（Owner/时间点/验收方式） + +## 触发示例 + +用户说以下话时会触发此 Skill： + +- “帮我写一份技术方案 / 设计文档 / RFC” +- “我要写 PRD / 决策记录 / proposal” +- “把这些聊天记录/会议纪要整理成一份可发给团队的文档” +- “我有个想法很乱，帮我搭个结构并一起写出来” + +## 工程化脚本（推荐） + +- `scripts/verify.py`: 硬校验入口（结构/格式/版本一致性等） +- 在修改或打包前先运行： + +```bash +python scripts/verify.py --skill . +``` + +--- + +## @工作流: 意图识别与路由 + + + + + + + + + +### @步骤0: 路由决策 + + + + + + + +- @动作: 识别用户当前意图与状态，按以下规则选择入口并跳转。 +- @动作: 若出现多个规则同时命中，优先级从高到低：评审/测试 → 结构 → 材料 → 新写。 + +@说明: 路由规则（命中即跳转；括号内为典型信号词/提法） + +- 评审/测试优先：用户要“读者视角验证/发现盲区/问答测试/一致性检查/查漏补缺/最终审校” → @跳转到: step-reader-testing 或 step-final-review +- 结构优先：用户已明确要“搭目录/写大纲/章节怎么分/结构化整理” → @跳转到: step-outline +- 材料优先：用户有“会议纪要/聊天记录/零散要点/现有草稿/资料链接”，核心诉求是“先把信息搬进来再说” → @跳转到: step-context-gathering +- 新写默认：用户只有主题/目标但缺少约束与上下文 → @跳转到: step-meta-context + +## @工作流: 文档共创主流程 + + + + + + + + + + +### @步骤1: 建立目标与约束（Meta Context） + + + + + + + +- @动作: 询问并确认文档类型（技术规格/设计文档/决策记录/RFC/提案/README/操作手册等）。 +- @动作: 询问并确认目标读者（谁会读/他们已知什么/他们关心什么）。 +- @动作: 询问并确认预期影响（读完要做什么决定/采取什么行动/形成什么共识）。 +- @动作: 询问并确认约束（时间线、兼容性、风险偏好、组织/流程要求、必须包含的章节/模板）。 +- @动作: 如果存在已有草稿/模板/会议纪要/聊天记录，优先读取并提取关键信息点与缺口。 +- @动作: 产出“写作契约”：用 5-8 条要点总结已确认信息与仍未知点。 + +### @步骤2: 上下文收集（信息倾倒 + 澄清） + + + + + + + + +- @动作: 引导用户进行一次“信息倾倒”，允许不成体系，重点是把信息搬进对话。 +- @动作: 明确可提供的材料类型：背景与动机、现状与痛点、已有讨论结论、约束与非目标、备选方案与被否决原因、依赖与架构、关键风险、时间线与里程碑、利益相关方与异议点。 +- @动作: 在用户倾倒后，给出 5-10 个编号澄清问题，按“最影响方案正确性”的优先级排序。 +- @动作: 对于明显缺失的关键输入（例如成功指标/验收标准/边界条件），必须追问直到可写。 + +@提示: 用户可以用简写回答（如 “1: 是；2: 看 A 文档；3: 不做，因为兼容性”），也可以继续倾倒信息。 + +### @步骤3: 搭建文档骨架（先结构后措辞） + + + + + + + + + +- @动作: 基于文档类型，提出 3-7 个核心章节的默认结构（可调整）。 +- @动作: 为每个章节写一行“本章要回答的问题/要做的决策”，避免空泛标题。 +- @动作: 明确 `${DOC_PATH}`：若用户未指定，按「最小模板规范」建议一个默认文件名并告知。 +- @动作: 当用户同意结构后，创建或更新 `${DOC_PATH}`，写入所有章节标题与占位符（如“[待填写]”）。 +- @动作: 若用户已有文档结构，优先在原结构上补齐缺失的关键章节而不是推翻重来。 + +### @步骤4: 逐段共创（问→列→选→写→改） + + + + + + + + +- @动作: 按“最不确定/最关键”的章节优先写作，摘要类章节一般最后写。 +- @动作: 每写一章，先提 5-10 个具体问题锁定内容边界。 +- @动作: 列出 5-20 个可能要写入的要点（按章节复杂度调整）。 +- @动作: 让用户用编号选择保留/删除/合并，并吸收用户的自由文本反馈。 +- @动作: 将被选中的要点写成该章节草稿，然后进入“外科式精修”（按句子层级删冗余、补缺口、校对术语一致性）。 +- @动作: 重复直到用户确认该章节完成，再进入下一章。 + +@提示: 优先修改文档文件本身，不要每次把整篇文档重新粘贴到对话里；除非用户明确要求查看全量。 + +### @步骤5: 读者测试（无上下文验证） + + + + + + + + +- @动作: 生成 5-10 个“真实读者会问的问题”（读者试图仅凭文档获取答案时会怎么问）。 +- @动作: 若运行环境支持“新实例/子代理无上下文测试”，用仅包含文档内容的输入进行问答测试并记录偏差。 +- @动作: 若不支持无上下文测试，给出可复制的测试说明：在一个全新对话中粘贴文档并逐条提问，要求对方同时指出“歧义/默认前提/缺失信息/自相矛盾”。 +- @动作: 将测试暴露的问题映射回具体章节，回到“逐段共创”补齐与改写。 + +### @步骤6: 最终审校与交付 + + + + + + + + +- @动作: 全文通读，检查一致性（术语/立场/数据/时间线）、冗余与空话、是否存在未解释的缩写与假设。 +- @动作: 确认文档中的结论与建议能被执行：给出明确的决策点、Owner、时间点或验收方式（按文档类型选择）。 +- @动作: 输出交付清单：文档文件名、目标读者、需要谁 review、需要补充的附件/链接（如有）。 + +--- +## 版本历史 + +- **v1.0.3** (2026-03-07) - 将“快速导航”改为 AI 意图路由工作流，并强化跳转规则。 +- **v1.0.2** (2026-03-07) - 增加最小模板规范与产物约定，强化可交付性。 +- **v1.0.1** (2026-03-07) - 增加作者信息。 +- **v1.0.0** (2026-03-07) - 初始版本（文档共创工作流） diff --git a/skills/kz-doc-coauthoring/scripts/verify.py b/skills/kz-doc-coauthoring/scripts/verify.py new file mode 100755 index 0000000..0ace33c --- /dev/null +++ b/skills/kz-doc-coauthoring/scripts/verify.py @@ -0,0 +1,165 @@ +#!/usr/bin/env python3 +""" +Verify script for kz-doc-coauthoring + +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 _extract_frontmatter_value(frontmatter: str, key: str): + match = re.search(rf"(?m)^{re.escape(key)}\s*(.+?)\s*$", frontmatter) + if not match: + return None + value = match.group(1).strip() + if value.startswith('"') and value.endswith('"') and len(value) >= 2: + value = value[1:-1].strip() + if value.startswith("'") and value.endswith("'") and len(value) >= 2: + value = value[1:-1].strip() + return value + + +def _extract_version_from_frontmatter(frontmatter: str): + value = _extract_frontmatter_value(frontmatter, "version:") + if not value: + return None + if not re.match(r"^\d+\.\d+\.\d+$", value): + return None + return value + + +def _extract_author_from_frontmatter(frontmatter: str): + match = re.search(r"(?m)^\s*author:\s*(.+?)\s*$", frontmatter) + if not match: + return None + value = match.group(1).strip() + if value.startswith('"') and value.endswith('"') and len(value) >= 2: + value = value[1:-1].strip() + if value.startswith("'") and value.endswith("'") and len(value) >= 2: + value = value[1:-1].strip() + return value + + +def _extract_header_value(markdown: str, label: str): + match = re.search(rf"(?m)^> \*\*{re.escape(label)}\*\*:\s*(.+?)\s*$", markdown) + if not match: + return None + return match.group(1).strip() + + +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") + + version = ( + _extract_version_from_frontmatter(frontmatter) if frontmatter else None + ) + if frontmatter and not version: + errors.append("SKILL.md frontmatter version must be semver like 1.0.0") + + if "## @工作流:" not in content: + errors.append("SKILL.md must include a '## @工作流:' section") + + if "## @工作流: 意图识别与路由" not in content: + errors.append("SKILL.md must include router workflow '意图识别与路由'") + + if "@跳转到:" not in content: + errors.append("SKILL.md router must include at least one '@跳转到:'") + + if not re.search(r"(?m)^### @步骤\d+:", content): + errors.append("SKILL.md must include at least one '### @步骤N:' section") + + if "## 最小模板规范" not in content: + errors.append("SKILL.md must include a '## 最小模板规范' section") + + if "${DOC_PATH}" not in content: + errors.append("SKILL.md must define and use ${DOC_PATH}") + + if "" not in content: + errors.append( + "SKILL.md must declare output artifact via '@产物: ${DOC_PATH}'" + ) + + if "- @动作:" not in content: + errors.append("SKILL.md must include at least one '- @动作:' line") + + if "@验证点:" not in content: + errors.append("SKILL.md must include '@验证点:' in step metadata") + + if "@验证方式:" not in content: + errors.append("SKILL.md must include '@验证方式:' in step metadata") + + if "## 版本历史" not in content: + errors.append("SKILL.md must include a '## 版本历史' section") + elif version and f"**v{version}**" not in content: + errors.append(f"SKILL.md version history must include v{version}") + + if version: + header_version = _extract_header_value(content, "版本") + if header_version != f"v{version}": + errors.append("Header version must match frontmatter version") + + author = _extract_author_from_frontmatter(frontmatter) if frontmatter else None + if author: + header_author = _extract_header_value(content, "作者") + if header_author != author: + errors.append("Header author must match frontmatter metadata.author") + + if errors: + for message in errors: + print("ERROR: " + message) + return 1 + + print("OK: basic skill structure checks passed") + + +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() From 34a803338a9d92cee1cb0e81b2c9b241d4fab895 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A8=8A=E7=83=A8=E9=9C=8F?= Date: Sat, 7 Mar 2026 22:09:08 +0800 Subject: [PATCH 3/5] =?UTF-8?q?Revert=20"feat:=20=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=85=B1=E5=88=9B=E6=8A=80=E8=83=BD"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit c229a70d5f4c9c5a706a9331acaaea5be6cae93f. --- skills/kz-doc-coauthoring/SKILL.md | 185 -------------------- skills/kz-doc-coauthoring/scripts/verify.py | 165 ----------------- 2 files changed, 350 deletions(-) delete mode 100644 skills/kz-doc-coauthoring/SKILL.md delete mode 100755 skills/kz-doc-coauthoring/scripts/verify.py diff --git a/skills/kz-doc-coauthoring/SKILL.md b/skills/kz-doc-coauthoring/SKILL.md deleted file mode 100644 index c52eac1..0000000 --- a/skills/kz-doc-coauthoring/SKILL.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -name: kz-doc-coauthoring -description: 文档共创工作流。用于用户要写文档/提案/技术规格/决策记录/RFC/README/操作手册等结构化内容时；也适用于把零散讨论与上下文整理成可被他人阅读、复用、再提问的文档。 -version: 1.0.3 -metadata: - author: K叔 ---- - -# Doc Coauthoring（文档共创） - - - - -> **版本**: v1.0.3 -> **作者**: K叔 -> **用途**: 以“收集上下文 → 搭骨架 → 逐段写作 → 读者测试”的流程共创文档 -> **适用范围**: 技术规格/设计文档/决策记录/RFC/提案/README/操作手册/项目说明 - -## 最小模板规范 - -为保证“可复用/可验证/可交付”，默认遵循以下最小输出规范（可按具体文档类型增删章节）： - -- 文档文件：统一用 `${DOC_PATH}` 指代最终文档文件路径；若用户未指定，默认建议 `rfc.md` / `design.md` / `decision.md` / `proposal.md` / `README.md` / `runbook.md` -- Stage 1 结束必须产出：写作契约（文档类型/受众/预期影响/约束/未知点） -- Stage 3 结束必须产出：目录骨架 + 每章一句“本章要回答的问题” -- 完稿必须包含（如适用）：结论/决策、范围与非目标、风险与权衡、下一步（Owner/时间点/验收方式） - -## 触发示例 - -用户说以下话时会触发此 Skill： - -- “帮我写一份技术方案 / 设计文档 / RFC” -- “我要写 PRD / 决策记录 / proposal” -- “把这些聊天记录/会议纪要整理成一份可发给团队的文档” -- “我有个想法很乱，帮我搭个结构并一起写出来” - -## 工程化脚本（推荐） - -- `scripts/verify.py`: 硬校验入口（结构/格式/版本一致性等） -- 在修改或打包前先运行： - -```bash -python scripts/verify.py --skill . -``` - ---- - -## @工作流: 意图识别与路由 - - - - - - - - - -### @步骤0: 路由决策 - - - - - - - -- @动作: 识别用户当前意图与状态，按以下规则选择入口并跳转。 -- @动作: 若出现多个规则同时命中，优先级从高到低：评审/测试 → 结构 → 材料 → 新写。 - -@说明: 路由规则（命中即跳转；括号内为典型信号词/提法） - -- 评审/测试优先：用户要“读者视角验证/发现盲区/问答测试/一致性检查/查漏补缺/最终审校” → @跳转到: step-reader-testing 或 step-final-review -- 结构优先：用户已明确要“搭目录/写大纲/章节怎么分/结构化整理” → @跳转到: step-outline -- 材料优先：用户有“会议纪要/聊天记录/零散要点/现有草稿/资料链接”，核心诉求是“先把信息搬进来再说” → @跳转到: step-context-gathering -- 新写默认：用户只有主题/目标但缺少约束与上下文 → @跳转到: step-meta-context - -## @工作流: 文档共创主流程 - - - - - - - - - - -### @步骤1: 建立目标与约束（Meta Context） - - - - - - - -- @动作: 询问并确认文档类型（技术规格/设计文档/决策记录/RFC/提案/README/操作手册等）。 -- @动作: 询问并确认目标读者（谁会读/他们已知什么/他们关心什么）。 -- @动作: 询问并确认预期影响（读完要做什么决定/采取什么行动/形成什么共识）。 -- @动作: 询问并确认约束（时间线、兼容性、风险偏好、组织/流程要求、必须包含的章节/模板）。 -- @动作: 如果存在已有草稿/模板/会议纪要/聊天记录，优先读取并提取关键信息点与缺口。 -- @动作: 产出“写作契约”：用 5-8 条要点总结已确认信息与仍未知点。 - -### @步骤2: 上下文收集（信息倾倒 + 澄清） - - - - - - - - -- @动作: 引导用户进行一次“信息倾倒”，允许不成体系，重点是把信息搬进对话。 -- @动作: 明确可提供的材料类型：背景与动机、现状与痛点、已有讨论结论、约束与非目标、备选方案与被否决原因、依赖与架构、关键风险、时间线与里程碑、利益相关方与异议点。 -- @动作: 在用户倾倒后，给出 5-10 个编号澄清问题，按“最影响方案正确性”的优先级排序。 -- @动作: 对于明显缺失的关键输入（例如成功指标/验收标准/边界条件），必须追问直到可写。 - -@提示: 用户可以用简写回答（如 “1: 是；2: 看 A 文档；3: 不做，因为兼容性”），也可以继续倾倒信息。 - -### @步骤3: 搭建文档骨架（先结构后措辞） - - - - - - - - - -- @动作: 基于文档类型，提出 3-7 个核心章节的默认结构（可调整）。 -- @动作: 为每个章节写一行“本章要回答的问题/要做的决策”，避免空泛标题。 -- @动作: 明确 `${DOC_PATH}`：若用户未指定，按「最小模板规范」建议一个默认文件名并告知。 -- @动作: 当用户同意结构后，创建或更新 `${DOC_PATH}`，写入所有章节标题与占位符（如“[待填写]”）。 -- @动作: 若用户已有文档结构，优先在原结构上补齐缺失的关键章节而不是推翻重来。 - -### @步骤4: 逐段共创（问→列→选→写→改） - - - - - - - - -- @动作: 按“最不确定/最关键”的章节优先写作，摘要类章节一般最后写。 -- @动作: 每写一章，先提 5-10 个具体问题锁定内容边界。 -- @动作: 列出 5-20 个可能要写入的要点（按章节复杂度调整）。 -- @动作: 让用户用编号选择保留/删除/合并，并吸收用户的自由文本反馈。 -- @动作: 将被选中的要点写成该章节草稿，然后进入“外科式精修”（按句子层级删冗余、补缺口、校对术语一致性）。 -- @动作: 重复直到用户确认该章节完成，再进入下一章。 - -@提示: 优先修改文档文件本身，不要每次把整篇文档重新粘贴到对话里；除非用户明确要求查看全量。 - -### @步骤5: 读者测试（无上下文验证） - - - - - - - - -- @动作: 生成 5-10 个“真实读者会问的问题”（读者试图仅凭文档获取答案时会怎么问）。 -- @动作: 若运行环境支持“新实例/子代理无上下文测试”，用仅包含文档内容的输入进行问答测试并记录偏差。 -- @动作: 若不支持无上下文测试，给出可复制的测试说明：在一个全新对话中粘贴文档并逐条提问，要求对方同时指出“歧义/默认前提/缺失信息/自相矛盾”。 -- @动作: 将测试暴露的问题映射回具体章节，回到“逐段共创”补齐与改写。 - -### @步骤6: 最终审校与交付 - - - - - - - - -- @动作: 全文通读，检查一致性（术语/立场/数据/时间线）、冗余与空话、是否存在未解释的缩写与假设。 -- @动作: 确认文档中的结论与建议能被执行：给出明确的决策点、Owner、时间点或验收方式（按文档类型选择）。 -- @动作: 输出交付清单：文档文件名、目标读者、需要谁 review、需要补充的附件/链接（如有）。 - ---- -## 版本历史 - -- **v1.0.3** (2026-03-07) - 将“快速导航”改为 AI 意图路由工作流，并强化跳转规则。 -- **v1.0.2** (2026-03-07) - 增加最小模板规范与产物约定，强化可交付性。 -- **v1.0.1** (2026-03-07) - 增加作者信息。 -- **v1.0.0** (2026-03-07) - 初始版本（文档共创工作流） diff --git a/skills/kz-doc-coauthoring/scripts/verify.py b/skills/kz-doc-coauthoring/scripts/verify.py deleted file mode 100755 index 0ace33c..0000000 --- a/skills/kz-doc-coauthoring/scripts/verify.py +++ /dev/null @@ -1,165 +0,0 @@ -#!/usr/bin/env python3 -""" -Verify script for kz-doc-coauthoring - -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 _extract_frontmatter_value(frontmatter: str, key: str): - match = re.search(rf"(?m)^{re.escape(key)}\s*(.+?)\s*$", frontmatter) - if not match: - return None - value = match.group(1).strip() - if value.startswith('"') and value.endswith('"') and len(value) >= 2: - value = value[1:-1].strip() - if value.startswith("'") and value.endswith("'") and len(value) >= 2: - value = value[1:-1].strip() - return value - - -def _extract_version_from_frontmatter(frontmatter: str): - value = _extract_frontmatter_value(frontmatter, "version:") - if not value: - return None - if not re.match(r"^\d+\.\d+\.\d+$", value): - return None - return value - - -def _extract_author_from_frontmatter(frontmatter: str): - match = re.search(r"(?m)^\s*author:\s*(.+?)\s*$", frontmatter) - if not match: - return None - value = match.group(1).strip() - if value.startswith('"') and value.endswith('"') and len(value) >= 2: - value = value[1:-1].strip() - if value.startswith("'") and value.endswith("'") and len(value) >= 2: - value = value[1:-1].strip() - return value - - -def _extract_header_value(markdown: str, label: str): - match = re.search(rf"(?m)^> \*\*{re.escape(label)}\*\*:\s*(.+?)\s*$", markdown) - if not match: - return None - return match.group(1).strip() - - -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") - - version = ( - _extract_version_from_frontmatter(frontmatter) if frontmatter else None - ) - if frontmatter and not version: - errors.append("SKILL.md frontmatter version must be semver like 1.0.0") - - if "## @工作流:" not in content: - errors.append("SKILL.md must include a '## @工作流:' section") - - if "## @工作流: 意图识别与路由" not in content: - errors.append("SKILL.md must include router workflow '意图识别与路由'") - - if "@跳转到:" not in content: - errors.append("SKILL.md router must include at least one '@跳转到:'") - - if not re.search(r"(?m)^### @步骤\d+:", content): - errors.append("SKILL.md must include at least one '### @步骤N:' section") - - if "## 最小模板规范" not in content: - errors.append("SKILL.md must include a '## 最小模板规范' section") - - if "${DOC_PATH}" not in content: - errors.append("SKILL.md must define and use ${DOC_PATH}") - - if "" not in content: - errors.append( - "SKILL.md must declare output artifact via '@产物: ${DOC_PATH}'" - ) - - if "- @动作:" not in content: - errors.append("SKILL.md must include at least one '- @动作:' line") - - if "@验证点:" not in content: - errors.append("SKILL.md must include '@验证点:' in step metadata") - - if "@验证方式:" not in content: - errors.append("SKILL.md must include '@验证方式:' in step metadata") - - if "## 版本历史" not in content: - errors.append("SKILL.md must include a '## 版本历史' section") - elif version and f"**v{version}**" not in content: - errors.append(f"SKILL.md version history must include v{version}") - - if version: - header_version = _extract_header_value(content, "版本") - if header_version != f"v{version}": - errors.append("Header version must match frontmatter version") - - author = _extract_author_from_frontmatter(frontmatter) if frontmatter else None - if author: - header_author = _extract_header_value(content, "作者") - if header_author != author: - errors.append("Header author must match frontmatter metadata.author") - - if errors: - for message in errors: - print("ERROR: " + message) - return 1 - - print("OK: basic skill structure checks passed") - - -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() From 5b60cdc338af6612fac3e0a58284b2572a44f986 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A8=8A=E7=83=A8=E9=9C=8F?= Date: Sat, 7 Mar 2026 22:58:32 +0800 Subject: [PATCH 4/5] docs: add kz-article-deep-analysis to skills catalog --- README.md | 2 ++ README.zh-CN.md | 1 + 2 files changed, 3 insertions(+) diff --git a/README.md b/README.md index 846b1cf..43233c6 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,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 c214cf1..c4c0348 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -98,6 +98,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 中更新此表格。 From d5891d69b8037d775f47b029fb14500eb771a1b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A8=8A=E7=83=A8=E9=9C=8F?= Date: Sat, 7 Mar 2026 23:04:18 +0800 Subject: [PATCH 5/5] docs(kz-article-deep-analysis): add usage example --- skills/kz-article-deep-analysis/SKILL.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/skills/kz-article-deep-analysis/SKILL.md b/skills/kz-article-deep-analysis/SKILL.md index aafd387..956d87b 100644 --- a/skills/kz-article-deep-analysis/SKILL.md +++ b/skills/kz-article-deep-analysis/SKILL.md @@ -1,14 +1,14 @@ --- name: kz-article-deep-analysis description: 深度解读非学术类文章（博客、随笔、评论），抽取核心议题与核心主张，评估其对读者认知的增量与张力，输出结构化分析报告。 -version: 1.0.2 +version: 1.0.3 metadata: author: K叔 --- # 文章深度解读 -> **版本**: v1.0.2 +> **版本**: v1.0.3 > **作者**: K叔 > **用途**: 深度挖掘文章的核心逻辑与认知价值 > **适用范围**: 博客、公众号文章、随笔、评论（不适用于学术论文或书籍） @@ -20,6 +20,22 @@ metadata: 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 认知卡片） + ## @工作流: 深度解读 @@ -71,6 +87,7 @@ metadata: ## 版本历史 +- **v1.0.3** (2026-03-07) - 增加使用示例。 - **v1.0.2** (2026-03-07) - 术语专业化，并统一文档表述。 - **v1.0.1** (2026-03-07) - 添加作者元数据。 - **v1.0.0** (2026-03-07) - 初始版本。