evolcore 0.0.32 → 0.0.34

package/kits/skills/thread-ops/SKILL.md

@@ -0,0 +1,492 @@
+---
+name: thread-ops
+description: >-
+  话题链（Thread Chain）操作规程与**话题总结**。教会 agent 如何在跨会话协作中：
+  发起委托（选话题、发消息、按需创建 Trigger）、处理收到的委托（判断是否回复）、
+  以及汇报回来源话题。也负责维护话题自身——**总结话题**（用户说"总结一下话题"
+  "总结话题""给这个话题写个总结""summarize this topic"时：用 summary show 拿到
+  上次覆盖游标 coveredThroughTs，用 history --after 读增量，再 summary set 写入）、
+  必要时**重命名话题**（名称还是"你好""话题会话"等占位词时）。
+  核心是时序语义：发出即结束 turn、Trigger 是唤醒信号不是执行脚本、
+  决策权归 agent 自己、无等齐原语靠主动查询合并。
+  适用场景：需要另一个 agent 输入 / 收到任务委托需代为联系第三方（"你帮我问一下 X"、
+  "转告 Y"、"去查 Z 那边的情况"）/ 作为中间人需要向当前对端以外转发请求或查询 /
+  需要总结 / 整理当前话题的场景。
+license: MIT
+---
+
+# `thread-ops` 操作规程
+
+## 一、Skill 的定位
+
+本 skill 是**操作性 skill**，面向 agent 在跨会话协作中使用。
+
+**核心价值：教会 agent 话题链的时序语义，而非命令清单。**
+
+- `ec thread list --help` 告诉 agent"这条命令有哪些参数"
+- 本 skill 告诉 agent"什么时候用这条命令、用完后会发生什么、下一步该做什么"
+
+本 skill 不添加工具，不改变系统权限。
+
+---
+
+## 二、加载判据：何时必须加载本 skill
+
+### 必须加载（L2 跨 agent 委派）
+
+以下任一条件成立时加载：
+
+1. **收到话题链消息**：上下文注入了"当前任务来源 = 话题 X / 对端 Y"
+2. **收到任务委托、需要转去联系第三方**：对方（人或 agent）让你去问另一个人或 agent，完成任务的下一步需要联系当前对端以外的对象——先加载本 skill，再按流程 A 操作
+3. **需要给当前对端以外的对象发消息**：只凭当前会话直发会被拒绝，必须走话题
+4. **需要委托另一个 agent**：判断当前任务需要对方的输入
+5. **并发问多方**：同时向 C 和 D 发出委托，等两个都回后再汇总
+6. **要汇报回来源话题**：任务完成，需要回复到来源话题
+
+> 判据 2 和 3 不依赖是否已有话题链注入：只要任务需要联系当前对端/当前群以外的对象，就直接按下方流程 A 操作。
+
+**为什么必须加载 skill（反直觉的关键点）**：
+
+- **发出即结束**（反直觉）：`ec msg send --thread T2` 返回后，当前 turn 立刻终止，不阻塞等待
+- **Trigger 是唤醒信号，不是执行脚本**（新概念）：到期时提醒检查对端是否回复，不保证对端已回、不强制回复、不指示执行任何操作；收到 Trigger 通知后，agent 自主决定下一步
+- **决策权在自己**（与 handoff 完全相反）：要不要回、何时回、回什么，完全自主
+- **无"等齐"原语**（分支合并的核心）：想合并多方回复，就在各自 turn 里主动用 `ec thread history` 查另一话题
+
+### 不需要 skill（L0/L1 本地操作）
+
+**L0 — 本会话元数据管理**：改当前话题名/标签/状态，查看当前话题元数据。命令自解释，`--help` 足够。
+
+**L1 — 跨会话查询**：列出与某对端的话题，读某话题的历史，查看话题摘要。纯查询，无时序复杂度。
+
+---
+
+## 三、核心概念速查
+
+| 概念 | 定义 |
+|---|---|
+| 话题（topic/thread） | agent 与对端之间一条独立的讨论线 |
+| threadId | 话题的跨端统一标识符，格式 `thread-<ms>-<seq4>-<rand4>` |
+| 主会话 | threadId 为空的会话，每对 agent–对端关系各有一个 |
+| 话题的双端结构 | 同一个 threadId，在通信双方各有一个本地会话（S1A / S1B） |
+| 跨话题路由 | 在会话 A 上调用 `send --thread T`，消息实际从话题 T 的会话发出 |
+| 跨话题 Trigger | 发消息后可选创建，N 分钟后唤醒 agent 检查对端是否回复 |
+| 基础传播单元 | 四条消息：A 委托 B → B 问 C → C 回 B → B 回 A |
+
+---
+
+## 四、使用流程
+
+### 流程 0：发现对端和话题（标准起点）
+
+**场景**：需要查看某个 agent 的话题列表，或生成工作报告。
+
+```bash
+# 第一步：找到所有本机 agent
+ec agent list
+
+# 第二步：找到某 agent 的所有真实对端（过滤内部 daemon 话题）
+ec thread peers --self <selfAid>
+
+# 第三步：列出与某对端的所有话题（含消息统计和摘要）
+ec thread list <peer> --self <selfAid>
+# 输出包含：话题名、创建/活跃时间、消息(24h/总计)、最后消息截断、摘要
+
+# 第四步：翻页（页脚自动给出完整翻页命令）
+ec thread list <peer> --self <selfAid> --page 2 --limit 10 --sort recent
+
+# 第五步：查看某话题的近期消息
+ec thread history <peer>/<threadId> --self <selfAid> --limit 20
+
+# 按时间范围过滤（如查最近一周）
+SINCE=$(python3 -c "import time; print(int((time.time()-7*86400)*1000))")
+ec thread history <peer>/<threadId> --self <selfAid> --after $SINCE --limit 100
+```
+
+---
+
+### 流程 A：发起跨会话委托（核心）
+
+**场景**：B 在话题 T1（与 A 对话）中，判断需要问 C。
+
+```bash
+# 步骤 1：找到或新建与 C 的话题
+ec thread list <C的AID>
+# 如果有合适的话题（如 T2），记下 threadId
+# 如果没有，新建：
+ec thread create <C的AID> --name "项目进度查询"
+# 返回：{ threadId: "thread-xxx", ... }
+
+# 步骤 2：发消息（--check-every 一步搞定复查）
+ec msg send "项目当前进度如何？" --thread <T2的threadId> --check-every 5m
+# --check-every 跨话题时必填（如 5m / 30m / 2h），周期唤醒直到显式 cancel
+# 返回：{ message_id: "m-yyy", ... }
+# 副作用：本端写入 thread-inbox + 创建周期复查 Trigger（kind=thread-check）
+
+# 步骤 3：当前 turn 结束
+# B 在 T1 的这个 turn 到此为止，不阻塞等待 C 的回复
+```
+
+**关键时序**：
+- `ec msg send --thread T2 --check-every 5m` 返回后，当前 turn **立刻结束**
+- 消息从 B 与 C 的话题 T2 发出到达 C
+- 5 分钟后，Trigger 唤醒 T2 的新 turn（在 B 侧）
+- 如果 C 在此之前已回复，新 turn 的上下文里会包含 C 的回复
+
+---
+
+### 流程 B：处理收到的委托
+
+**场景**：C 收到 B 的消息，当前会话是 B 与 C 的话题 T2（C 侧）。
+
+上下文注入示例（由渲染层自动添加）：
+```
+当前任务来源：话题 thread-xxx，对端 b.agentid.cn
+```
+
+```bash
+# 步骤 1：处理任务（C 执行相应操作）
+
+# 步骤 2：决定是否回复
+# 情况 A：直接回复 B（在当前话题 T2 上）
+ec msg send "进度 70%，预计下周完成"
+# 不带 --thread，消息发在当前话题上
+# 托管会话中不需要指定 from 和 to，系统推断
+
+# 情况 B：不回复，什么都不做，turn 结束
+```
+
+**关键点**：要不要回复完全由 C 自己决定，系统不强制。
+
+---
+
+### 流程 C：Trigger 到期后的处理
+
+**场景**：5 分钟后，Trigger 唤醒 B 在 T2 的新 turn。
+
+```bash
+# 步骤 1：检查 C 是否已回复
+ec thread history current --limit 10
+# 或从上下文直接判断
+
+# 步骤 2A：C 已回复 → 处理回复，汇报回 A
+ec msg send "C 回复：进度 70%" --thread <T1的threadId> --check-every 30m
+# 汇报回 A 也是跨话题发送，同样必填 --check-every
+
+# 步骤 2B：C 还没回 → 决定下一步
+# 选项 1：继续等 → 什么都不做，原 Trigger 下个周期会再次唤醒
+#         （如需调整频率：ec trigger update <triggerId> --every 5m）
+# 选项 2：放弃等待，直接回 A
+ec msg send "C 暂无回复" --thread <T1的threadId> --check-every 30m
+
+# 选项 3：什么都不做，turn 结束
+```
+
+**关键点**：Trigger 只是唤醒信号，不携带执行指令，不保证 C 已回复。
+
+---
+
+### 流程 D：并发委托多方
+
+**场景**：B 需要同时问 C 和 D，等两个都回后再汇总。
+
+```bash
+# 步骤 1：同时发出两条委托，各自创建周期复查 Trigger（--check-every 一步搞定）
+ec msg send "技术评估" --thread <T2> --check-every 10m
+ec msg send "产品评估" --thread <T3> --check-every 10m
+# turn 结束
+
+# 10 分钟后，T2 和 T3 各自触发新 turn
+
+# 在 T2 的 turn 里（C 已回复）：
+# 检查 D 是否也回了
+ec thread history <D的AID>/<T3> --limit 5
+# 如果 D 还没回，turn 结束，等 T3 的 turn
+
+# 在 T3 的 turn 里（D 已回复）：
+# 检查 C 是否也回了
+ec thread history <C的AID>/<T2> --limit 5
+# C 也回了，合并结果
+ec msg send "综合评估：技术……产品……" --thread <T1> --check-every 30m
+```
+
+**关键点**：没有"等齐"原语。想合并就在后到的 turn 里主动读另一话题，手动判断是否齐全。
+
+---
+
+### 流程 E：追问（同话题多轮）
+
+**场景**：C 第一次回复不够详细，B 继续追问。
+
+```bash
+# S2B 收到 C 的第一次回复："卡在 Redis 并发问题"
+# B 判断需要更多细节
+
+ec msg send "Redis 并发问题影响范围多大？"
+# 不带 --thread，继续在当前话题上
+# 同话题追问无需 --check-every（不跨话题，不创建复查 Trigger）
+
+# C 再次回复后，触发新 turn
+# B 整合两轮对话，回 A
+ec msg send "C 反馈：Redis 问题影响……" --thread <T1>
+```
+
+---
+
+### 流程 F：话题历史查询
+
+```bash
+# 查看当前话题
+ec thread show current
+
+# 列出与某对端的所有话题
+ec thread list <peer-AID>
+
+# 读当前话题的历史
+ec thread history current --limit 20
+
+# 读另一个话题的历史（跨话题只读）
+ec thread history <peer>/<threadId> --limit 50
+
+# 按时间过滤（查看空洞期消息）
+ec thread history <peer>/<threadId> --after <timestamp>
+```
+
+---
+
+### 流程 G：修改话题属性
+
+```bash
+ec thread rename current "新名称"
+ec thread label current "开发"
+ec thread status current in_progress
+# 状态值：pending | in_progress | completed | archived
+```
+
+---
+
+### 流程 H：Trigger 操作（跨话题跟进场景）
+
+#### 场景一：对端回复时的 Trigger 决策
+
+当你在某个话题被对端唤醒，跨会话上下文注入里会带上关联的复查 Trigger：
+
+```
+‹跨会话上下文 · 来源话题:thread-T1 · 对端:alice.agentid.cn · 发送于:...›
+🔔 复查 Trigger:trig_1791765199642_5371c8ff（尚未触发/待处理）
+【原消息内容】
+```
+
+**操作流程**：
+
+1. **判断对端回复是否完整**：
+   - 如果对端已给最终答案 → 继续第 2 步
+   - 如果对端还在处理中 → 保留 trigger，本次不操作
+
+2. **检查来源话题是否有新指示**（如果系统提示有空洞期消息）：
+   ```bash
+   ec thread history <来源peer>/<来源threadId> --after <timestamp>
+   ```
+   - 如果来源话题有"取消任务"等新指示 → 处理后取消 trigger
+   - 如果来源话题无新消息 → 继续第 3 步
+
+3. **决定 Trigger 操作**：
+   - **任务完成** → 取消 trigger（用 **id**，即上面注入的 `trig_…`；用名称会报 trigger not found）：
+     ```bash
+     ec trigger cancel trig_1791765199642_5371c8ff
+     ```
+   
+   - **需要加快跟进** → 调整周期：
+     ```bash
+     ec trigger update trig_1791765199642_5371c8ff --every 30m
+     ```
+
+#### 场景二：Trigger 触发时的主动复查
+
+当 trigger 定期触发时，你会被唤醒并看到 trigger 的 prompt（信封头标注 `Trigger 复查 · 话题:... ← 来源:...`）：
+
+```
+【Trigger 复查】话题 thread-T2（对端 C）
+这是周期复查：每 5m 唤醒一次，直到你显式结束它。
+
+请检查该话题的最新进度，根据情况：继续等待、调整周期（ec trigger update trig_1791765199642_5371c8ff --every <时长>）或结束复查（ec trigger cancel trig_1791765199642_5371c8ff）。
+
+参考命令：
+  ec thread history <C的AID>/thread-T2 --limit 10
+  ec thread history <来源peer>/thread-T1 --after <timestamp>
+  ec trigger cancel trig_1791765199642_5371c8ff
+  ec trigger update trig_1791765199642_5371c8ff --every <时长>
+Trigger id：trig_1791765199642_5371c8ff
+Trigger 名称：check-<目标threadId>-from-<来源threadId>-<唯一后缀>
+```
+
+**操作流程**：
+
+1. **检查目标话题是否有新消息**：
+   ```bash
+   ec thread history <目标peer>/<目标threadId> --limit 10
+   ```
+
+2. **检查来源话题是否有新指示**：
+   ```bash
+   ec thread history <来源peer>/<来源threadId> --after <上次检查时间>
+   ```
+
+3. **根据检查结果决策**：
+   - **目标话题有回复** → 处理回复，判断是否取消 trigger（同场景一）
+   - **来源话题有新指示**（如"别管了"）→ 通知目标话题，取消 trigger
+   - **两边都无更新** → 保留 trigger 继续等待
+   - **发现会话不可用** → 回复来源话题说联系不上，取消 trigger
+
+4. **错误处理**：
+   - 发送消息失败（暂时性）→ 保留 trigger，下次再试
+   - 发送消息失败（永久性，如拉黑）→ 取消 trigger，回复来源话题
+
+---
+
+### 流程 I：总结话题（"总结一下话题"）
+
+**触发词**：用户说"总结一下话题""总结话题""给这个话题写个总结""这个话题总结一下"
+"更新一下摘要""summarize this topic" 时，**直接执行下面的序列**，不要反问"总结什么"。
+
+**核心两步**：① 拿到"上次总结覆盖到哪"→ ② 读那之后的增量 → ③ 写新摘要。
+`--name` **必填**：总结时往往正好把主题想清楚，一次命令同时写摘要 + 改标题；
+确实要保留原标题时显式传 `--name -`（显式表达意图，比省略更难被忽略）。
+`summary show` 会打印 `coveredThroughTs`（覆盖游标），它就是你读增量的起点。
+`summary set` 会自动把游标推进到当时话题的最新一条，你不用管。
+
+**情形 A：在当前话题内总结**（对话就在上下文里，不用读历史）
+
+```bash
+# 1. 看上次摘要内容和覆盖游标（没有摘要时输出"（暂无 summary）"）
+ec thread summary show current
+
+# 2. 自己写摘要（100 字以内，见下方规范）。
+#    增量就是本轮对话，无需再读历史；游标自动推进。
+#    --name 必填：一次写完摘要 + 标题。不想改名就显式传 `-`。
+ec thread summary set current "写好的摘要内容" --name "动词短语描述的核心动作"
+ec thread summary set current "写好的摘要内容" --name -            # 保持原话题名
+# 多人协作同一话题时带 CAS 防覆盖
+ec thread summary set current "写好的摘要内容" --name "标题" --if-rev <步骤1的rev>
+```
+
+**情形 B：从别的话题（或别处）总结某话题**（需要读增量）
+
+```bash
+# 1. 看上次摘要 + 覆盖游标
+ec thread summary show <peer>/<threadId>
+#    输出中 coveredThroughTs 是上次覆盖到的时间戳；没有该字段说明是首次/旧摘要，需全量读
+
+# 2. 读游标之后的增量（首次总结则省略 --after，全量读）
+ec thread history <peer>/<threadId> --after <coveredThroughTs> --limit 50
+
+# 3. 增量较多时往回翻页（history 支持 before 逆序分页）
+ec thread history <peer>/<threadId> --before <本页最早一条的ts> --limit 50
+#    翻到覆盖游标之前即可停；注意 before 是闭区间，用 <最早ts - 1> 避免边界重复
+
+# 4. 读完增量后写摘要（游标自动推进到现在）；--name 必填，不改名传 -
+ec thread summary set <peer>/<threadId> "写好的摘要内容" --name "新名称"
+```
+
+**关键约束**：`summary set` 把游标设为**当时话题的最新一条**，所以跨话题总结**必须先把增量读完再写**。
+若没读完就写，游标会越过未读的消息，它们下次不会被返回（永久跳过）。
+
+**首次总结**：`summary show` 没有 `coveredThroughTs`（本话题从未总结过，或是只带 `updatedAt` 的旧记录）。
+此时从最新往回翻，一直翻到你认为已覆盖的开头，再写摘要。
+
+**为什么用 `--after <coveredThroughTs>` 而不是拍脑袋定 `--limit`**：游标是上次真正覆盖到的位置，
+从它之后读既不多读（省 token）也不少读（不漏消息）。翻页用 `--before`，天然支持"往回看"。
+
+**话题名称命名规范**（由 `summary set --name` 一并写入，不必单独跑 rename）：
+- 名称应反映话题的核心主题，不超过20字
+- 避免使用创建时的随机短语（"你好"、"话题会话"），改为有意义的描述
+- 好的名称示例："skill 索引热更新 bug 修复"、"manifest 注入与 CLAUDE.md 冗余问题"
+- 名称是本端的，对端可能有不同名称，这是正常的
+
+**摘要写作规范**：
+- 摘要应在100字以内，概括话题的背景、进展和结果
+- 格式：[谁]做了[什么]，结果是[什么]，遗留[什么]（如有）
+- 摘要是给下次进入该话题时快速恢复上下文用的，不是给对端看的
+- 示例："leiliang 要求安装 fetch 技能，tl3 完成依赖下载和链路验证，技能安装完成。"
+
+#### 何时顺手做（不等用户开口）
+
+用户明确说"总结"时按上面序列执行。此外以下时机**主动**做，不要等对端问：
+
+| 时机 | 操作 |
+|---|---|
+| 话题名称仍是创建时的随机短语（"你好"、"话题会话"等）时 | 更新名称 |
+| 一个明确的任务或阶段完成时 | 写入/更新摘要 |
+| 话题方向发生重大转变（原来讨论A，现在转向B） | 更新名称 + 摘要 |
+| 即将离开话题去处理其他事（跨话题路由前） | 写入摘要，记录当前状态 |
+| 话题进入 completed 状态前 | 写入最终摘要，记录成果 |
+| 下次被唤醒时发现摘要是"未总结" | 回顾历史后补写摘要 |
+
+---
+
+### 流程 J：生成 agent 工作报告
+
+**场景**：需要总结某 agent 与某对端最近一段时间的工作内容。
+
+```bash
+SELF=<selfAid>
+PEER=<peer>
+# 最近一周的时间戳（毫秒）
+SINCE=$(python3 -c "import time; print(int((time.time()-7*86400)*1000))")
+
+# 第一步：列出所有话题（含消息统计）
+ec thread list $PEER --self $SELF --limit 100
+
+# 第二步：对24h消息数>0或总消息数较多的话题，读取最近消息
+ec thread history $PEER/<threadId> --self $SELF --after $SINCE --limit 50
+
+# 第三步：查看每个话题的 summary
+ec thread summary show $PEER/<threadId> --self $SELF
+```
+
+**报告结构建议**：
+1. **时间范围**：报告覆盖的时间段
+2. **话题总览**：共多少话题，活跃话题数（24h有消息）
+3. **逐话题摘要**：按活跃时间排序，每个话题一段，包含：
+   - 话题名称和时间范围
+   - 主要内容（从 summary 或消息读取）
+   - 完成状态
+4. **结论**：主要完成了什么，有什么遗留
+
+---
+
+## 五、常见错误
+
+| 错误码 | 含义 | 处理 |
+|---|---|---|
+| `TOPIC_NOT_FOUND` | `--thread` 指定的话题在本端不存在 | 先 `ec thread create` 新建 |
+| `TOPIC_CONFLICT` | 创建时名称与已有话题重名 | 换名字，或直接使用已有话题 |
+| `TOPIC_BUSY` | 话题有正在执行的任务，无法删除 | 等任务完成后再删除 |
+
+---
+
+## 六、不应该做的事
+
+1. **不要在发送消息后阻塞等待回复**：`send --thread T2` 返回后 turn 就结束了，回复会触发新 turn。
+
+2. **不要忘记创建 Trigger**：如果不创建，对端不回复时你永远不会知道。分支合并场景必须用 Trigger。
+
+3. **不要在托管会话中手动指定 from 和 to**：`ec msg send "文本" --thread T2` 就够了。
+
+4. **不要把 Trigger 当作"强制回复"或"执行脚本"**：Trigger 只是唤醒信号，到期后 agent 自主决定下一步。
+
+5. **不要期望话题名双端一致**：话题名是本端概念，threadId 才是跨端统一标识符。
+
+6. **不要在并发场景期望"等齐"原语**：想合并就在后到的 turn 里用 `ec thread history` 主动读。
+
+---
+
+## 七、加载本 skill 后 agent 应该明白的七条核心点
+
+1. **话题是路由单位**：消息必须发在某个话题上，不带 `--thread` 时发在当前话题。
+2. **跨话题路由不阻塞**：`send --thread T2` 返回后当前 turn 立刻结束，不等回复。
+3. **Trigger 是唤醒信号，不是执行脚本**：到期时提醒检查，不指示执行任何操作，不保证对端已回复。
+4. **决策权在自己**：收到委托要不要回、何时回、回什么，完全自主判断。
+5. **分支合并靠主动查询**：想等多个对端都回，就在各自 turn 里用 `ec thread history` 读另一话题。
+6. **from/to 托管会话中不需要**：会话唯一确定对端，命令简化为 `ec msg send "文本" --thread T`。
+7. **话题名是本端的**：对端可能改名，threadId 才是跨端统一标识。
+

package/kits/skills/wechat-article-media-download/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: wechat-article-media-download
+description: >-
+  从微信公众号文章链接下载视频和图片。当用户提供 mp.weixin.qq.com/s/... 格式的公众号文章
+  链接，并要求"下载视频""保存图片""抓取媒体""下载公众号文章里的视频/图片"时使用。
+  无需微信客户端、无需登录、零第三方依赖（纯 Python 3.7+ 标准库）。
+  不适用于视频号（Channels）来源的视频，也不适用于需要粉丝关注才可见的付费文章。
+license: MIT
+---
+
+# 微信公众号文章媒体下载
+
+从公众号文章页面提取并下载视频和图片，无需微信客户端或登录态。
+
+## 原理
+
+- **图片**：从 `data-src="https://mmbiz.qpic.cn/..."` 属性中提取，带 WeChat referer 头下载。
+- **视频**：签名直链已内嵌于文章页面末尾的 JS 数据块，解码 HTML 实体后用正则提取。
+  每个视频有多种清晰度（format_id），优先选 `10002`（超清 H.264），
+  依次回退 `10102 → 10004 → 10104`。
+- 签名 URL 约一周内有效，建议下载后立即使用。
+- 来自视频号（Channels）的视频不包含可提取的直链，此工具无法下载。
+
+## 用法
+
+```bash
+python3 "<技能目录>/scripts/download.py" "<文章URL>" "<输出目录>"
+```
+
+**示例：**
+
+```bash
+python3 "<技能目录>/scripts/download.py" \
+  "https://mp.weixin.qq.com/s/xxxxxx" \
+  "./wechat-output"
+```
+
+输出结构：
+
+```
+<输出目录>/
+├── videos/       # 按序号命名的 .mp4 文件
+├── images/       # 按序号命名的图片文件
+└── sources.json  # 原始链接清单，含格式、大小、下载状态
+```
+
+## 步骤
+
+1. 确认用户提供了有效的 `mp.weixin.qq.com/s/...` 链接。
+2. 确定输出目录（用户未指定时默认 `./wechat-output`）。
+3. 用绝对路径运行脚本：
+   ```bash
+   python3 "<技能目录绝对路径>/scripts/download.py" "<文章URL>" "<输出目录>"
+   ```
+4. 脚本打印每个文件的 OK/FAIL 状态和大小；结束后输出汇总。
+5. 下载完成后，告知用户各类文件数量及输出路径。
+
+## 边界与注意事项
+
+- **零依赖**：只用 Python 3.7+ 标准库，无需 `pip install`。
+- **并发下载**：每个文件一个线程，速度快。
+- **视频号视频**：无直链，无法下载，脚本会跳过并标注。
+- **付费/仅粉丝文章**：页面返回 403 或空内容，脚本会报错退出。
+- **链接有效期**：签名 URL 约 7 天，过期后需重新运行脚本。
+- **路径规则**：执行时必须用脚本的绝对路径，不可依赖 cwd。