第 5 章 Hermes 明星 Skill 解剖

skills/github/
├── DESCRIPTION.md              # 分类总说明
├── github-auth/                # 鉴权
├── github-repo-management/     # 仓库级操作
├── github-issues/              # issue 相关
├── github-pr-workflow/         # PR 相关
├── github-code-review/         # 代码审查
└── codebase-inspection/        # 代码库探索

---
name: github-issues
description: 在 GitHub 仓库中查询、创建、评论、关闭 issue,支持按标签/状态/作者筛选
category: github
trigger_keywords:
  - github issue
  - "issue 分诊"
  - "看看 bug"
  - "创建 issue"
  - "回复这个 issue"
depends_on:
  - github-auth
parameters:
  - name: repo
    type: string
    description: "仓库全名,例如 owner/repo"
    required: true
  - name: action
    type: enum
    values: [list, get, create, comment, close, reopen]
    required: true
  # ... 其他参数根据 action 而定
cost_estimate: low
risk_level: caution  # 写操作(create/comment/close)属 caution 级
requires_confirmation:
  - create
  - close
---

## 前置条件
 
- 已通过 `github-auth` skill 完成 GitHub token 配置
- 目标仓库是用户有访问权限的
 
## 执行流程
 
### action: list
 
1. 读取 `gh auth status` 确认 token 可用
2. 构造 query:`gh issue list --repo <repo> [筛选参数]`
3. 解析输出,格式化成表格返回
 
参考命令:
 
```bash
gh issue list \
  --repo "$REPO" \
  --state "${STATE:-open}" \
  --limit "${LIMIT:-30}" \
  --json number,title,author,labels,updatedAt
```
 
### action: create
 
1. 确认用户已经提供 title 和 body
2. **向用户展示一次将要创建的内容摘要,等待确认**
3. 确认后执行 `gh issue create`
4. 返回创建的 issue URL
 
### action: comment
 
1. 读取目标 issue 的当前状态
2. 如果 issue 已 close,警告用户并询问是否仍要 comment
3. 执行 `gh issue comment`
 
## 失败模式
 
- Token 过期 → 提示用户重新运行 `github-auth`
- 速率限制(rate limit)→ 从 error message 里解析 reset 时间,告知用户
- 仓库不存在或无权限 → 明确区分这两种错误,不要混为一谈
- 网络问题 → 最多重试 3 次,每次间隔 exponential backoff
 
## 相关技能
 
- `github-pr-workflow`: 如果 issue 实际是个 PR,应该路由到这个 skill
- `github-repo-management`: 如果用户的需求是仓库级别的(比如 release notes),应该路由到这个 skill

---
name: rss-watcher
category: feeds
description: 监听 RSS/Atom 订阅源,筛选与用户兴趣相关的新条目并推送
trigger_keywords:
  - "订阅"
  - "新文章"
  - "rss"
  - "关注一下"
parameters:
  - name: feed_urls
    type: list[string]
    description: RSS 源的 URL 列表
    required: true
  - name: interest_keywords
    type: list[string]
    description: 用户感兴趣的关键词,用来做初筛
    required: false
  - name: relevance_prompt
    type: string
    description: 自然语言描述的相关性判断标准
    required: false
state_file: memory/feeds/rss-watcher-state.json
cost_estimate: medium  # 会触发 LLM 做相关性判断
risk_level: safe
schedule: "0 */3 * * *"  # 默认每 3 小时跑一次
---

## 状态格式
 
state_file 的 JSON schema:
 
```json
{
  "last_run": "2026-04-05T12:00:00Z",
  "feeds": {
    "<feed_url>": {
      "last_seen_id": "...",
      "last_seen_published": "..."
    }
  },
  "seen_items": [   // 最近 1000 条的 item id,用来去重
    "hash1", "hash2", ...
  ]
}
```
 
## 执行流程
 
1. **加载状态**。读 `state_file`,如果不存在则初始化空状态。
 
2. **抓取**。对每个 feed_url 并发拉取。使用 conditional GET(带 `If-Modified-Since` 头)减少不必要的流量。
 
3. **增量过滤**。对拉回来的条目:
   - 如果 item id 在 `seen_items` 里,跳过
   - 如果 item 的发布时间早于 `last_seen_published`,跳过
   - 其余为"候选新条目"
 
4. **初筛**(便宜的一步)。用 `interest_keywords` 做简单的关键词匹配,
   筛掉明显无关的条目。这一步不花 LLM 调用。
 
5. **精判**(贵的一步)。对通过初筛的条目,用 LLM 根据 `relevance_prompt`
   判断是否真的相关。**这里用便宜模型**(在第 7 章会讲原因)。
 
6. **推送**。对判断为相关的条目,通过 gateway 发给用户(Telegram / Slack / 飞书 / 邮件)。
   推送格式:标题 + URL + 一句话摘要 + 相关性评分。
 
7. **更新状态**。把这次处理过的 item id 加入 `seen_items`,
   更新 `last_seen_*` 字段。`seen_items` 超过 1000 条时,裁剪到最近的 1000 条。
 
8. **持久化**。写回 state_file。
 
## 失败模式
 
- **单个 feed 失败**:不应该影响其他 feed,记录错误但继续
- **LLM 调用失败**:当前批次的精判跳过,等下一次调度再试;不影响状态推进
- **推送失败**:推送内容暂存到 `memory/feeds/pending-notifications/`,下次重试
- **状态文件损坏**:备份到 `.backup`,重建一份,会导致一次重复推送但不会丢数据
 
## 可调参数
 
- 初筛阈值:默认匹配至少 1 个关键词才进精判
- 精判阈值:默认相关性分 >= 0.7 才推送
- seen_items 容量:默认 1000,可以调高(占更多磁盘)或调低(增加重复风险)

---
name: deep-research
category: research
description: 对一个主题做多步调研,输出结构化研究报告
trigger_keywords:
  - "调研"
  - "研究一下"
  - "综述"
  - "深入了解"
parameters:
  - name: topic
    type: string
    description: 研究主题(自然语言描述)
    required: true
  - name: depth
    type: enum
    values: [quick, standard, deep]
    default: standard
    description: 研究深度影响调研耗时和成本
  - name: output_format
    type: enum
    values: [markdown_report, bullet_summary, flashcards]
    default: markdown_report
uses_skills:
  - web-search
  - url-fetch
  - pdf-reader
  - note-taking
cost_estimate: high  # LLM 调用密集
risk_level: safe
max_duration_seconds: 1800  # 最多 30 分钟
checkpoint_interval: 120  # 每 2 分钟保存一次进度
---

## 执行流程概览
 
```mermaid
flowchart TB
    A[分解问题] --> B[生成子查询]
    B --> C[并行检索]
    C --> D[来源质量评估]
    D --> E[冲突检测]
    E --> F{需要更深入?}
    F -->|是| B
    F -->|否| G[综合总结]
    G --> H[格式化输出]
    G --> I[写入 memory]
```
 
## 阶段 1:分解问题
 
根据 `depth` 参数决定分解粒度:
 
- `quick`:3–5 个子问题
- `standard`:5–10 个子问题
- `deep`:10–20 个子问题,且允许递归细化
 
分解由 LLM 完成,使用**强模型**(例如 claude-3-5-sonnet),
因为分解质量直接决定后续所有步骤的上限。
 
## 阶段 2:生成子查询
 
为每个子问题生成 1–3 个搜索查询字符串。此步用便宜模型即可。
 
## 阶段 3:并行检索
 
调用 `web-search` skill 对所有子查询并发执行。
注意:并发数有限制(默认 5),避免被目标服务限流。
 
## 阶段 4:内容抓取
 
对搜索结果的 top URL 调用 `url-fetch` / `pdf-reader` 拉取正文。
长文档做分段,超过 10K token 的部分做摘要。
 
## 阶段 5:来源质量评估
 
对每个来源打分:
- 权威性(机构、作者、出版物)
- 时效性(发布时间距今多远)
- 相关性(和子问题的匹配度)
 
低质量来源降权,不直接丢弃(因为它们可能包含反方观点,有参考价值)。
 
## 阶段 6:冲突检测
 
把不同来源对同一子问题的陈述摆在一起,用 LLM 识别"共识"和"分歧"。
分歧部分要被单独记录,写入最终报告时要明确标注。
 
## 阶段 7:需要更深入?
 
根据 depth 参数和当前已用预算决定是否触发新一轮查询。
如果 quick 模式,直接进入总结;如果 deep 模式,可能递归最多 3 层。
 
## 阶段 8:综合总结
 
按 `output_format` 组织最终输出:
- markdown_report:完整报告,有引言、分节、结论、参考文献
- bullet_summary:要点列表
- flashcards:问答对,用于后续复习
 
## 阶段 9:持久化
 
把研究结果的摘要写入 `memory/research/<topic-slug>.md`,
下次用户问相关问题时,可以快速召回。
 
## 断点续跑
 
每个阶段结束时保存一次 checkpoint 到 `state/research-<id>.json`,
包括:当前阶段、已完成的子问题、已抓取的 URL、已用的 token 数。
中断后重启时从最近的 checkpoint 恢复。
 
## 失败模式
 
- **单个 search 失败**:记录并继续,不中断整体
- **LLM 限流**:等待退避后重试
- **达到 max_duration**:强制终止,用当前已有的数据生成部分报告
- **达到预算上限**:同上,并向用户说明"数据不完整"

---
name: note-taking
category: productivity
description: 记录、整理、检索用户的笔记;和 memory 系统深度集成
trigger_keywords:
  - "记一下"
  - "加个笔记"
  - "这个我要记住"
  - "找一下我之前写的"
parameters:
  - name: action
    type: enum
    values: [add, search, list, organize, summarize]
    required: true
  - name: content
    type: string
    required: false  # 只有 add 需要
  - name: topic
    type: string
    required: false  # 用于分类
  - name: query
    type: string
    required: false  # 用于 search
writes_to: memory/notes/
reads_from: memory/notes/
cost_estimate: low
risk_level: safe
memory_policy:
  preserve_original: true   # 用户的原话要原样保留
  allow_agent_annotation: true  # Agent 可以加注释,但加在独立段落
  auto_tag: true  # 根据内容自动打标签
---

## 目录结构
 
```
memory/notes/
├── _index.md              # 索引文件(自动维护)
├── topics/
│   ├── work/
│   │   ├── 2026-04-05-standup.md
│   │   └── 2026-04-08-retro.md
│   ├── learning/
│   │   ├── rust-ownership.md
│   │   └── kafka-internals.md
│   └── personal/
│       └── reading-list.md
└── scratch/               # 未分类
    └── 2026-04-10.md
```
 
每个笔记文件的结构:
 
```markdown
---
created: 2026-04-08T14:32:00Z
last_modified: 2026-04-08T14:32:00Z
topic: work
tags: [standup, team-alpha]
source_session: <session-id>
---
 
# 原始笔记
 
> 用户的原话开始
>
> 今天早会上讨论了下一季度的 OKR,重点是把延迟从 200ms 降到 100ms。
> 张伟提到可以考虑把 redis 升级到 cluster 模式。
>
> 用户的原话结束
 
## Agent 附注(由 Agent 自动添加)
 
- 相关技术决策:redis cluster 升级(首次提及)
- 相关人:张伟
- 相关目标:Q2 延迟优化
 
## 关联
 
- 见 projects/latency-optimization.md
- 见之前的 2026-03-30 1:1 笔记
```
 
## action: add
 
1. 解析用户输入,识别 topic(如果用户没明说,用 LLM 分类)
2. 生成文件名(date + topic slug)
3. 构造 frontmatter
4. **把用户的原话原样写入"原始笔记"段落,不做任何修改**(包括口头语、错别字)
5. 让 LLM 生成"Agent 附注"段落,包括:相关实体、相关决策、可能的关联
6. 在 _index.md 里登记这条笔记
 
## action: search
 
1. 先在 _index.md 做关键词过滤
2. 对通过过滤的候选,用向量相似度排序
3. 返回 top-k 条笔记的标题 + 摘要,让用户选择是否展开
 
## action: organize
 
这是一个"维护类"action,定期触发(每周一次)。流程:
 
1. 扫描 scratch/ 下的笔记,用 LLM 判断它们应该进入哪个 topic
2. 扫描 topics/ 下的笔记,识别应该合并的(同一天、同一事件)
3. 扫描所有笔记,识别应该加关联的("这个笔记和那个笔记讨论的是同一件事")
4. 生成一份"维护建议"给用户,由用户确认后再执行
 
## action: summarize
 
1. 按 topic 或时间段选择一批笔记
2. 生成一份跨笔记的总结(例如 "本周关于 Rust 学习的笔记整理")
3. 总结被写入一个新文件 topics/<topic>/_summary_<date>.md
4. **原始笔记不被修改**,总结是独立的新文件
 
## 失败模式
 
- **用户输入里有敏感信息**(密码、API key)→ 触发 redact,把敏感部分替换为 `[REDACTED]`,并在 Agent 附注里提示用户
- **磁盘空间不足**:失败并告知用户
- **_index.md 损坏**:从文件系统重建
 
## 和 memory 系统的协作
 
note-taking 写的是 "user-authored notes",是分层记忆的第二层(持久化笔记)的一个子集。
Hermes 的 memory_manager 在做"反思"时,**不会**直接修改 notes/ 下的文件,但**会**把
 notes/ 的内容作为反思的输入。反过来,reflection 产出的"Agent 自己观察到的 user 事实"
 写在 memory/facts/ 下,和 notes/ 并列。两者在目录层面上隔离,确保用户笔记的原始性
 不被 agent 污染。

---
name: mcp-bridge
category: mcp
description: 动态加载 MCP server,把其 tools 桥接为 Hermes 可调用的操作
parameters:
  - name: server_url
    type: string
    required: true
  - name: operation
    type: string
    required: true
    description: MCP server 暴露的 tool name
  - name: arguments
    type: object
    required: false
cost_estimate: variable  # 取决于底层 MCP tool
risk_level: variable
mcp_metadata:
  auto_discover: true
  cache_schema: true
---

## 加载 MCP Server
 
1. 连接 server_url,获取 server 的 schema(通过 `mcp/list-tools`)
2. 缓存 schema 到 `cache/mcp/<server-hash>.json`
3. 对每个 MCP tool,生成一份"虚拟 skill 描述"注入 Prompt
 
## 执行 MCP Tool
 
1. 定位具体的 tool(按 operation name)
2. 对 arguments 做一次 schema 校验(类型、必填项)
3. **对危险操作先向用户确认**(根据 tool 的 name 和 description 做简单的启发式判断)
4. 通过 MCP 协议发起调用
5. 解析结果,转成 Hermes 内部的 tool_result 格式
 
## 失败模式
 
- **MCP server 断连**:重试 3 次,失败后退回
- **schema 不一致**(MCP server 升级了):重新 discover 并刷新缓存
- **参数校验失败**:返回清晰的错误,让 LLM 有机会修正参数后重试
- **tool 执行失败**:区分 "tool 本身的业务错误" 和 "协议层错误"
 
## MCP vs Skill 的边界
 
如果你在写一个 Hermes skill,问自己:
 
- 这件事已经有 MCP server 吗?如果有,优先用 mcp-bridge 调用,不要重复造轮子
- 这件事跨多个 MCP tool 吗?如果是,写一个 skill 编排它们(像 research 一样)
- 这件事涉及长期状态 / 用户画像?那应该是 skill,不是 MCP(MCP tool 是无状态的)