soia-pkm-interpret-article-analysis

属 SOIA 个人知识管理域（soia-pkm-*）的"解读"环节：对 vault 里 clip 进来的长文/论文，AI 直接给出结构化解读，帮你在深挖（distill）前先判断这篇值不值得投入。

客户可读说明

这个技能可以做什么

对 vault 里 clip 进来的长文/论文，AI 直接给出解读：内容总览/核心要点/关键启发/批判视角/延伸阅读五段式。默认快读（各段 2-3 句），说"精读/深度解读"升级为逐节展开 + 论证链核查。产出独立 <原文件名>-AI解读.md，落原文件同目录并双链回原文，绝不碰原文、绝不写入原文的 ## 我的看法 段。

客户如何使用

1. 提供要解读的文章：说"这篇"（=当前对话涉及的文章）或给出文件名/标题，Agent 在 <vault-articles-dir>/ 下定位。
2. 单篇文章：Agent 直接执行，不需要额外确认。批量（同一请求涉及超过 3 篇）：Agent 先列出清单（文件名 + 大致主题），等待客户确认解读范围（全部 / 挑选几篇 / 暂停），再逐篇执行。
3. 深度默认快读（五段式，各段 2-3 句）；客户说"精读""深度解读""逐节核查"时升级为精读（逐节展开 + 论证链核查，见 [两档深度](#两档深度)）。
4. 解读永远先落盘、后汇报：产出 <原文件名>-AI解读.md 落在原文件同目录，正文双链回原文，绝不改动或覆盖原文件（含 ## 我的看法 段）。
5. 最终回复必须给客户完整回执：深度、篇数、产出文件路径、标注了几处"原文未明确/需核对"、剩余风险。

依赖与安装

安装（推荐：装整个领域插件，一次装好本仓全部技能）：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-interpret-article-analysis -y

配置约定：

~/.config/soia-skills/soia-pkm-interpret-article-analysis/config.yml
SOIA_PKM_INTERPRET_ARTICLE_ANALYSIS_CONFIG_FILE=<custom-config-path>

• 本技能是纯文档 / 纯 prompt 技能，不带脚本，通常不需要 config.yml；如果客户想固定"默认深度"或"批量确认阈值"等偏好，可以建这个文件，字段与本文一致。
• 不需要、也不应该读取任何 API key、cookie、session、账号凭据——本技能只读取客户提供的文本文件。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

日志与完成回执

每次执行都要让客户看见判定、深度、批量确认和产出全过程。最低回执格式：

完成：<一句话说明本次解读了什么文件、什么深度>。

日志摘要：
- 定位：<文件路径，如何找到的（客户直接给的 / 在 vault 内搜到的）>
- 深度：<快读 / 精读，以及判定依据（客户是否明确要求精读）>
- 批量确认：<单篇写"不适用"；批量则写是否先报清单、客户确认了什么范围>
- 待核对：<解读中标注"原文未明确/需核对"的条数，简述位置>

文件变化：
- 新建：<绝对路径，`<原文件名>-AI解读.md`>
- 未改动：<原文件路径，确认未被覆盖，`## 我的看法` 段未被触碰>

问题与下一步：
- <值不值得深挖的判断 / 建议客户回复"精读"升级 / 建议客户对这篇跑 soia-pkm-distill-article-opinion；没有则写"无，可直接使用产出">

与 soia-pkm-distill-article-opinion 的分界（必须遵守）

这是本技能最容易被混淆的地方——分界必须显著、每次执行前默认成立：

• 客户如果在解读过程中说"我怎么看这篇""帮我提炼观点""这篇我的看法是……"，一律提示"这是 soia-pkm-distill-article-opinion 的职责，要不要切过去？"，不在本技能内代答、代写。
• interpret 的产物是决策辅助：帮客户判断"这篇值不值得进 distill 深挖"；不是观点本身，也不应被误当成客户的观点。

两档深度

精读模式：论证链核查

精读时，在"批判视角"段之前先做一次逐节论证链核查，逐个论点确认：

1. 这一节的核心论点是什么？
2. 支撑这个论点的证据/数据/引用是什么，出自原文哪一段？
3. 论点到证据之间是否有跳跃——证据只能支持一个更弱的结论，但原文喊出了更强的结论？
4. 原文没有交代清楚的前提/定义/边界条件，标注"原文未明确/需核对"，不替原文补全。

核查结果作为"批判视角"段的依据，而不是另起一段罗列；避免精读产出变成"总览 + 核查清单"两张皮。

五段式解读结构（输出模板）

产出文件 <原文件名>-AI解读.md 正文结构固定为：

# AI 解读：《{文章标题}》

> 原文：[[<原文件名>]]
> 解读深度：{快读 / 精读}
> 解读时间：{YYYY-MM-DD}

---

## 内容总览

{快读 2-3 句 / 精读可展开到一小段：文章讲了什么、核心结论是什么}

## 核心要点

{分条目提炼文章主干信息，通常 4-8 条，每条给出处（如"见第 3 节"/"见引言部分"）}

- **要点 1**（出处：……）：……
- **要点 2**（出处：……）：……

## 关键启发

{至少 3 条，每条说明"是什么 → 为什么重要 → 对你可能怎么用"，不写"这个方法很有前景"式空话}

- **启发 1**：……
- **启发 2**：……
- **启发 3**：……

## 批判视角

{至少 1 条"这篇可能错在哪"——论证漏洞、证据不足、以偏概全、时效性问题等；精读模式基于上面的论证链核查填写；不确定处写"原文未明确/需核对"，不替作者圆场也不无端苛责}

- ……

## 延伸阅读

{2-4 条值得继续探索的方向或值得对照读的资料；如果 vault 内已有相关文章/MOC，用双链标出}

- ……

• 不确定内容一律显式标"原文未明确/需核对"，绝不编造原文没写的数据、实验、结论。
• 引用原文时给出处段落（章节标题、"引言"/"第 X 段"等），方便客户回原文核对。

定位文章

1. 客户说"这篇" = 当前对话涉及的文章；否则用文件名/标题在 <vault-articles-dir>/ 下 Glob/Grep 定位。
2. 读文章的 ## 原文 段（clip 家族统一正文结构：## 摘要 / 原文 / 我的看法 / 关联）；只有摘要没有全文时，解读前先告知客户"本次基于摘要而非全文，结论置信度较低"，并在解读文件的"内容总览"里注明。
3. 不读、不改客户已有的 ## 我的看法 段——那段内容与本技能无关。

落地规则

• 路径：与原文件同目录，文件名 <原文件名>-AI解读.md。
• frontmatter：新建独立 frontmatter（不是原文件 frontmatter 的复制），至少包含：

interpreted_from: <原文件名或相对路径>
interpret_depth: <quick 或 deep>
interpreted_at: <YYYY-MM-DD>

• 正文用 [[<原文件名>]] 双链回原文，方便双向跳转。
• 绝不覆盖、绝不编辑原文件——包括 frontmatter、## 摘要、## 原文、## 我的看法、## 关联任何一段；如果同名解读文件已存在，先告知客户，等待确认是否覆盖旧解读（覆盖类风险动作，必须先确认）。

批量策略

• 单篇（本次请求只涉及 1 篇）：直接执行，不额外确认。
• 批量（本次请求涉及超过 3 篇，如"把这个 MOC 下的文章都解读一下"）：先列出清单（文件名 + 一句话主题猜测），报告"共 N 篇，建议先解读哪几篇/全部解读？"，等待客户确认范围，再逐篇执行；每篇仍遵守"先落盘、后汇报"，全部完成后给一份合并回执（见 [日志与完成回执](#日志与完成回执)）。
• 2-3 篇：视为小批量，可以直接执行，但仍在开始前用一句话报告将处理哪几篇。

交付顺序

先落盘，后汇报：产出文件必须先写入磁盘并通过内容核对（文件确实存在、五段式齐全、批判视角至少一条），再向客户发出完成回执。不允许先描述"已完成"再补写文件。

边界与限制

• 不代替 soia-pkm-distill-article-opinion：本技能绝不写入原文件的 ## 我的看法 段，也不以第一人称冒充客户表态。
• 不编造：原文未提供的信息一律标"原文未明确/需核对"，不杜撰数据、实验、引用或结论。
• 不做外部检索核实：解读基于原文本身；如果批判视角依赖外部事实核查，只提示客户"这一点需要客户自行核实"，不擅自杜撰核实结果。
• 不做翻译/转换：外文文章先经 soia-pkm-translate-article-zh 或客户自行理解后再解读；本技能不覆盖 soia-pkm-transform 的产物转换（PPT/脑图等）职责。
• 本技能是纯文档 / 纯 prompt 技能，不带任何脚本，不读取账号、cookie、session 等凭据。

闭环位置

clip(收) → organize(整理) → ★interpret(AI 解读，辅助判断) → distill(点：你的观点) → compose(写) → publish(发)

• 上游：soia-pkm-organize-article-moc 整理好的文章库是主要输入来源；也可以直接对刚 clip 进来、还没整理的单篇文章解读。
• 下游：客户看完 AI 解读、决定"这篇值得深挖"后，转 soia-pkm-distill-article-opinion 炼自己的观点；soia-pkm-interpret-article-analysis 的产出不是 distill 或 compose 的必需输入，只是决策参考。

第三方 skill 关系

完成后回执

回执包含：

1. 做了什么 — 一句话总结本次解读了什么文件、什么深度、是否批量。
2. 文件变化 — 新建的解读文件完整路径；明确说明原文件（含 ## 我的看法）未被改动。
3. 下一步 — 提示客户"这篇值不值得深挖"的判断依据；快读模式提醒可回复"精读"升级；有"原文未明确/需核对"的点时一并列出，建议客户自行核实或用 soia-pkm-distill-article-opinion 表态。