@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/autonomous-ai-agents/honcho/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: honcho
+description: 配置和使用 Hermes 的 Honcho 记忆功能 —— 包括跨会话用户建模、多配置文件 peer 隔离、observation 配置、dialectic 推理、会话摘要以及上下文预算限制。适用于设置 Honcho、排查记忆故障、使用 Honcho peers 管理配置文件，或调整 observation、recall 和 dialectic 设置。
+version: 2.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Honcho, Memory, Profiles, Observation, Dialectic, User-Modeling, Session-Summary]
+    homepage: https://docs.honcho.dev
+    related_skills: [hermes-agent]
+prerequisites:
+  pip: [honcho-ai]
+---
+
+# Hermes 的 Honcho 记忆
+
+Honcho 提供了 AI 原生的跨会话用户建模。它能在多次对话中了解用户是谁，并为每个 Hermes profile 提供独立的 peer 身份，同时共享统一的用户视图。
+
+## 何时使用
+
+- 设置 Honcho（云端或自托管）
+- 故障排查 memory 无法工作 / peers 不同步
+- 创建多 profile 设置，其中每个 agent 都有自己的 Honcho peer
+- 调整 observation、recall、dialectic 深度或写入频率设置
+- 了解 5 个 Honcho 工具的作用及其使用时机
+- 配置上下文预算和会话摘要注入
+
+## 配置
+
+### 云端
+
+```bash
+hermes memory setup honcho
+# select "cloud", paste API key from https://app.honcho.dev
+```
+
+### 自托管
+
+```bash
+hermes memory setup honcho
+# select "local", enter base URL (e.g. http://localhost:8000)
+```
+
+参见：https://docs.honcho.dev/v3/guides/integrations/hermes#running-honcho-locally-with-hermes
+
+### 验证
+
+```bash
+hermes honcho status    # shows resolved config, connection test, peer info
+```
+
+## 架构
+
+### 基础上下文注入
+
+当 Honcho 将上下文注入系统提示词时（在 `hybrid` 或 `context` recall 模式下），它会按以下顺序组装基础上下文块：
+
+1. **会话摘要** —— 当前会话到目前为止的简短摘要（放在最前面，以便模型立即获得对话连贯性）
+2. **用户表示** —— Honcho 积累的关于用户的模型（偏好、事实、模式）
+3. **AI peer 卡片** —— 此 Hermes profile 的 AI peer 身份卡
+
+会话摘要由 Honcho 在每一轮对话开始时自动生成（当存在之前的会话时）。它为模型提供了一个热启动，而无需重放完整的历史记录。
+
+### 冷/热提示词选择
+
+Honcho 会在两种提示词策略之间自动进行选择：
+
+| 条件 | 策略 | 发生的行为 |
+|-----------|----------|--------------|
+| 没有之前的会话或表示为空 | **冷启动** | 轻量级介绍提示词；跳过摘要注入；鼓励模型去了解用户 |
+| 存在表示和/或会话历史记录 | **热启动** | 完整的基础上下文注入（摘要 → 表示 → 卡片）；更丰富的系统提示词 |
+
+你不需要配置此项 —— 它会根据会话状态自动执行。
+
+### Peers
+
+Honcho 将对话建模为 **peers** 之间的互动。Hermes 为每个会话创建两个 peers：
+
+- **User peer** (`peerName`)：代表人类。Honcho 从观察到的消息中构建用户表示。
+- **AI peer** (`aiPeer`)：代表此 Hermes 实例。每个 profile 都有自己的 AI peer，以便 agents 形成独立的观点。
+
+### Observation
+
+每个 peer 都有两个 observation 开关，用于控制 Honcho 从中学习哪些内容：
+
+| 开关 | 作用 |
+|--------|-------------|
+| `observeMe` | 观察该 peer 自己的消息（构建自我表示） |
+| `observeOthers` | 观察其他 peers 的消息（构建跨 peer 的理解） |
+
+默认：所有四个开关都**开启**（完全双向 observation）。
+
+在 `honcho.json` 中为每个 peer 进行配置：
+
+```json
+{
+  "observation": {
+    "user": { "observeMe": true, "observeOthers": true },
+    "ai":   { "observeMe": true, "observeOthers": true }
+  }
+}
+```
+
+或者使用简写预设：
+
+| 预设 | User | AI | 用例 |
+|--------|------|----|----------|
+| `"directional"` (默认) | me:on, others:on | me:on, others:on | 多 agent，完整记忆 |
+| `"unified"` | me:on, others:off | me:off, others:on | 单 agent，仅针对用户建模 |
+
+在 [Honcho dashboard](https://app.honcho.dev) 中更改的设置会在会话初始化时同步回来 —— 服务器端配置优先于本地默认值。
+
+### 会话
+
+Honcho 会话限定了消息和 observation 的存放位置。策略选项：
+
+| 策略 | 行为 |
+|----------|----------|
+| `per-directory` (默认) | 每个工作目录一个会话 |
+| `per-repo` | 每个 git 仓库根目录一个会话 |
+| `per-session` | 每次 Hermes 运行一个新的 Honcho 会话 |
+| `global` | 所有目录共享一个单一会话 |
+
+手动覆盖：`hermes honcho map my-project-name`
+
+### Recall 模式
+
+Agent 如何访问 Honcho 记忆：
+
+| 模式 | 自动注入上下文？ | 工具可用？ | 用例 |
+|------|---------------------|-----------------|----------|
+| `hybrid` (默认) | 是 | 是 | Agent 决定何时使用工具还是自动上下文 |
+| `context` | 是 | 否（隐藏） | 最小 token 开销，无工具调用 |
+| `tools` | 否 | 是 | Agent 显式控制所有记忆访问 |
+
+## 三个正交的调节旋钮
+
+Honcho 的 dialectic 行为由三个独立的维度控制。每个维度都可以在不影响其他维度的情况下进行调优：
+
+### Cadence（何时）
+
+控制 dialectic 和上下文调用发生的**频率**。
+
+| 键 | 默认值 | 说明 |
+|-----|---------|-------------|
+| `contextCadence` | `1` | 上下文 API 调用之间的最小轮数 |
+| `dialecticCadence` | `2` | dialectic API 调用之间的最小轮数。建议 1–5 |
+| `injectionFrequency` | `every-turn` | 基础上下文注入使用 `every-turn` 或 `first-turn` |
+
+较高的 Cadence 值会降低 dialectic LLM 的触发频率。`dialecticCadence: 2` 表示引擎每隔一轮触发一次。设置为 `1` 则每轮都会触发。
+
+### Depth（多少次）
+
+控制 Honcho 每次查询执行**多少轮** dialectic 推理。
+
+| 键 | 默认值 | 范围 | 说明 |
+|-----|---------|-------|-------------|
+| `dialecticDepth` | `1` | 1-3 | 每次查询的 dialectic 推理轮数 |
+| `dialecticDepthLevels` | -- | array | 可选的每轮级别覆盖（见下文） |
+
+`dialecticDepth: 2` 表示 Honcho 运行两轮 dialectic 综合。第一轮产生初始答案；第二轮对其进行细化。
+
+`dialecticDepthLevels` 允许你为每一轮独立设置推理级别：
+
+```json
+{
+  "dialecticDepth": 3,
+  "dialecticDepthLevels": ["low", "medium", "high"]
+}
+```
+
+如果省略了 `dialecticDepthLevels`，则使用基于 `dialecticReasoningLevel`（基础级别）推导出的**比例级别**：
+
+| 深度 | 轮次级别 |
+|-------|-------------|
+| 1 | [base] |
+| 2 | [minimal, base] |
+| 3 | [minimal, base, low] |
+
+这使得早期的处理保持较低开销，同时在最终合成时使用完整的深度。
+
+**会话开始时的 Depth。** 会话开始的预热会在第 1 轮之前在后台运行完全配置的 `dialecticDepth`。在冷启动的 peer 上进行单次预热通常只会返回单薄的结果 —— 多轮深度处理会在用户发言之前运行审计/协调周期。第 1 轮直接消耗预热结果；如果预热未能及时完成，第 1 轮将回退到具有有限超时的同步调用。
+
+### Level（难度）
+
+控制每轮 dialectic 推理的**强度**。
+
+| 键 | 默认值 | 说明 |
+|-----|---------|-------------|
+| `dialecticReasoningLevel` | `low` | `minimal`, `low`, `medium`, `high`, `max` |
+| `dialecticDynamic` | `true` | 当为 `true` 时，模型可以传递 `reasoning_level` 给 `honcho_reasoning` 以按次覆盖默认值。`false` = 始终使用 `dialecticReasoningLevel`，忽略模型覆盖 |
+
+较高的级别会产生更丰富的综合结果，但会在 Honcho 的后端消耗更多的 tokens。
+
+## 多 Profile 配置
+
+每个 Hermes profile 都会获得自己的 Honcho AI peer，同时共享相同的工作区（用户上下文）。这意味着：
+
+- 所有 profile 看到相同的用户表示
+- 每个 profile 建立自己的 AI 身份和 observation
+- 一个 profile 写入的结论通过共享工作区对其他 profile 可见
+
+### 创建带有 Honcho peer 的 profile
+
+```bash
+hermes profile create coder --clone
+# creates host block hermes.coder, AI peer "coder", inherits config from default
+```
+
+`--clone` 对 Honcho 的作用：
+1. 在 `honcho.json` 中创建一个 `hermes.coder` host block
+2. 设置 `aiPeer: "coder"`（即 profile 名称）
+3. 从默认配置继承 `workspace`、`peerName`、`writeFrequency`、`recallMode` 等
+4. 提前在 Honcho 中创建该 peer，使其在第一条消息之前就已存在
+
+### 回填现有 profiles
+
+```bash
+hermes honcho sync    # creates host blocks for all profiles that don't have one yet
+```
+
+### 单个 profile 配置
+
+在 host block 中覆盖任何设置：
+
+```json
+{
+  "hosts": {
+    "hermes.coder": {
+      "aiPeer": "coder",
+      "recallMode": "tools",
+      "dialecticDepth": 2,
+      "observation": {
+        "user": { "observeMe": true, "observeOthers": false },
+        "ai": { "observeMe": true, "observeOthers": true }
+      }
+    }
+  }
+}
+```
+
+## 工具
+
+Agent 拥有 5 个双向的 Honcho 工具（在 `context` recall 模式下隐藏）：
+
+| 工具 | LLM 调用？ | 开销 | 何时使用 |
+|------|-----------|------|----------|
+| `honcho_profile` | 否 | 极小 | 在对话开始时获取快速的事实快照，或用于快速查找名称/角色/偏好 |
+| `honcho_search` | 否 | 低 | 获取特定的过往事实以进行自行推理 —— 原始摘录，无综合 |
+| `honcho_context` | 否 | 低 | 完整的会话上下文快照：摘要、表示、卡片、近期消息 |
+| `honcho_reasoning` | 是 | 中-高 | 由 Honcho 的 dialectic 引擎合成的自然语言问题解答 |
+| `honcho_conclude` | 否 | 极小 | 写入或删除持久性事实；传递 `peer: "ai"` 用于 AI 自我认知 |
+
+### `honcho_profile`
+读取或更新 peer 卡片 —— 精选的关键事实（姓名、角色、偏好、沟通风格）。传递 `card: [...]` 进行更新；省略则以读取模式运行。无 LLM 调用。
+
+### `honcho_search`
+针对存储的特定 peer 上下文进行语义搜索。返回按相关性排序的原始摘录，无综合。默认 800 个 tokens，最大 2000 个。适用于你需要特定的过往事实进行自行推理，而不是得到一个合成的答案时。
+
+### `honcho_context`
+来自 Honcho 的完整会话上下文快照 —— 会话摘要、peer 表示、peer 卡片和近期消息。无 LLM 调用。适用于你希望一次性查看 Honcho 知道的关于当前会话和 peer 的所有信息。
+
+### `honcho_reasoning`
+由 Honcho 的 dialectic 推理引擎（在 Honcho 后端进行 LLM 调用）回答的自然语言问题。开销较高，质量较高。传递 `reasoning_level` 以控制深度：`minimal`（快速/廉价）→ `low` → `medium` → `high` → `max`（彻底）。省略则使用配置的默认值 (`low`)。用于对用户的模式、目标或当前状态进行综合理解。
+
+### `honcho_conclude`
+写入或删除关于某个 peer 的持久性结论。传递 `conclusion: "..."` 进行创建。传递 `delete_id: "..."` 删除结论（用于移除 PII —— Honcho 会随着时间自我修复错误的结论，因此只有处理 PII 时才需要删除）。你 MUST 准确传递这两个参数中的一个。
+
+### 双向 peer 定位
+
+所有 5 个工具都接受一个可选的 `peer` 参数：
+- `peer: "user"` (默认) —— 针对 user peer 进行操作
+- `peer: "ai"` —— 针对此 profile 的 AI peer 进行操作
+- `peer: "<explicit-id>"` —— 工作区内的任意 peer ID
+
+示例：
+```
+honcho_profile                        # read user's card
+honcho_profile peer="ai"              # read AI peer's card
+honcho_reasoning query="What does this user care about most?"
+honcho_reasoning query="What are my interaction patterns?" peer="ai" reasoning_level="medium"
+honcho_conclude conclusion="Prefers terse answers"
+honcho_conclude conclusion="I tend to over-explain code" peer="ai"
+honcho_conclude delete_id="abc123"    # PII removal
+```
+
+## Agent 用法模式
+
+Honcho 记忆激活时 Hermes 的指导原则。
+
+### 对话开始时
+
+```
+1. honcho_profile                  → fast warmup, no LLM cost
+2. If context looks thin → honcho_context  (full snapshot, still no LLM)
+3. If deep synthesis needed → honcho_reasoning  (LLM call, use sparingly)
+```
+
+不要在每一轮都调用 `honcho_reasoning`。自动注入已经处理了持续的上下文刷新。仅在你确实需要基础上下文无法提供的合成洞察时，才使用推理工具。
+
+### 当用户分享需要记住的内容时
+
+```
+honcho_conclude conclusion="<specific, actionable fact>"
+```
+
+良好的结论：“偏好代码示例而不是文字解释”、“在 2026 年 4 月之前致力于 Rust 异步项目”
+糟糕的结论：“用户说了一些关于 Rust 的事情”（太模糊）、“用户看起来很技术化”（已在表示中存在）
+
+### 当用户询问过去的上下文 / 你需要回忆具体细节时
+
+```
+honcho_search query="<topic>"       → fast, no LLM, good for specific facts
+honcho_context                       → full snapshot with summary + messages
+honcho_reasoning query="<question>"  → synthesized answer, use when search isn't enough
+```
+
+### 何时使用 `peer: "ai"`
+
+使用 AI peer 定位来构建和查询 agent 自身的认知：
+- `honcho_conclude conclusion="I tend to be verbose when explaining architecture" peer="ai"` —— 自我纠正
+- `honcho_reasoning query="How do I typically handle ambiguous requests?" peer="ai"` —— 自我审计
+- `honcho_profile peer="ai"` —— 审查自己的身份卡片
+
+### 何时不调用工具
+
+在 `hybrid` 和 `context` 模式下，基础上下文（用户表示 + 卡片 + 会话摘要）会在每一轮之前自动注入。不要重复获取已经注入的内容。仅在以下情况调用工具：
+- 你需要注入上下文中没有的内容
+- 用户明确要求你回忆或检查记忆
+- 你正在写下关于某些新内容的结论
+
+### Cadence 意识
+
+工具端的 `honcho_reasoning` 与自动注入 dialectic 的开销相同。在显式调用工具后，自动注入的 cadence 将重置 —— 避免了同一轮的重复计费。
+
+## 配置参考
+
+配置文件：`$HERMES_HOME/honcho.json`（针对特定 profile）或 `~/.honcho/config.json`（全局）。
+
+### 核心设置
+
+| 键 | 默认值 | 说明 |
+|-----|---------|-------------|
+| `apiKey` | -- | API 密钥（[获取一个](https://app.honcho.dev)） |
+| `baseUrl` | -- | 自托管 Honcho 的基础 URL |
+| `peerName` | -- | User peer 身份 |
+| `aiPeer` | host key | AI peer 身份 |
+| `workspace` | host key | 共享工作区 ID |
+| `recallMode` | `hybrid` | `hybrid`、`context` 或 `tools` |
+| `observation` | all on | 每个 peer 的 `observeMe` / `observeOthers` 布尔值 |
+| `writeFrequency` | `async` | `async`、`turn`、`session` 或整数 N |
+| `sessionStrategy` | `per-directory` | `per-directory`、`per-repo`、`per-session`、`global` |
+| `messageMaxChars` | `25000` | 每条消息的最大字符数（超出则分块） |
+
+### Dialectic 设置
+
+| 键 | 默认值 | 说明 |
+|-----|---------|-------------|
+| `dialecticReasoningLevel` | `low` | `minimal`, `low`, `medium`, `high`, `max` |
+| `dialecticDynamic` | `true` | 根据查询复杂度自动提升推理级别。`false` = 固定级别 |
+| `dialecticDepth` | `1` | 每次查询的 dialectic 轮数 (1-3) |
+| `dialecticDepthLevels` | -- | 可选的每轮级别数组，例如 `["low", "high"]` |
+| `dialecticMaxInputChars` | `10000` | dialectic 查询输入的最大字符数 |
+
+### 上下文预算和注入
+
+| 键 | 默认值 | 说明 |
+|-----|---------|-------------|
+| `contextTokens` | uncapped | 组合基础上下文注入（摘要 + 表示 + 卡片）的最大 token 数。可选上限 —— 省略则不限制，设置为整数以限制注入大小。 |
+| `injectionFrequency` | `every-turn` | `every-turn` 或 `first-turn` |
+| `contextCadence` | `1` | 上下文 API 调用之间的最小轮数 |
+| `dialecticCadence` | `2` | dialectic LLM 调用之间的最小轮数（建议 1–5） |
+
+`contextTokens` 预算在注入时强制执行。如果会话摘要 + 表示 + 卡片超出预算，Honcho 会首先修剪摘要，然后修剪表示，并保留卡片。这可以防止长会话中的上下文膨胀。
+
+### 记忆上下文清理
+
+Honcho 会在注入之前清理 `memory-context` 块，以防止提示词注入和格式错误的内容：
+
+- 从用户编写的结论中剥离 XML/HTML 标签
+- 规范化空格和控制字符
+- 截断超过 `messageMaxChars` 的单个结论
+- 转义可能破坏系统提示词结构的分隔符序列
+
+此修复解决了因包含标记或特殊字符的原始用户结论可能破坏注入上下文块的边缘情况。
+
+## 故障排查
+
+### "Honcho not configured"
+运行 `hermes honcho setup`。确保 `~/.hermes/config.yaml` 中包含 `memory.provider: honcho`。
+
+### 记忆未在跨会话时保留
+检查 `hermes honcho status` —— 验证 `saveMessages: true` 且 `writeFrequency` 不是 `session`（后者仅在退出时写入）。
+
+### Profile 没有获得自己的 peer
+创建时请使用 `--clone`：`hermes profile create <name> --clone`。对于现有的 profiles：`hermes honcho sync`。
+
+### Dashboard 中的 observation 更改未生效
+observation 配置在每次会话初始化时从服务器同步。在 Honcho UI 中更改设置后，请启动一个新会话。
+
+### 消息被截断
+超过 `messageMaxChars`（默认 25k）的消息会自动使用 `[continued]` 标记进行分块。如果你经常遇到这种情况，请检查是否是工具结果或技能内容增加了消息大小。
+
+### 上下文注入过大
+如果你看到有关超出上下文预算的警告，请降低 `contextTokens` 或减少 `dialecticDepth`。当预算紧张时，会话摘要会首先被修剪。
+
+### 缺少会话摘要
+会话摘要要求当前 Honcho 会话中至少有一轮先前的对话。在冷启动（新会话，无历史记录）时，将省略摘要，并且 Honcho 会改用冷启动提示词策略。
+
+## CLI 命令
+
+| 命令 | 说明 |
+|---------|-------------|
+| `hermes honcho setup` | 交互式设置向导（云端/本地、身份、observation、recall、会话） |
+| `hermes honcho status` | 显示当前活跃 profile 的已解析配置、连接测试和 peer 信息 |
+| `hermes honcho enable` | 为当前活跃的 profile 启用 Honcho（如有需要会创建 host block） |
+| `hermes honcho disable` | 为当前活跃的 profile 禁用 Honcho |
+| `hermes honcho peer` | 显示或更新 peer 名称 (`--user <name>`, `--ai <name>`, `--reasoning <level>`) |
+| `hermes honcho peers` | 显示所有 profile 的 peer 身份 |
+| `hermes honcho mode` | 显示或设置 recall 模式 (`hybrid`, `context`, `tools`) |
+| `hermes honcho tokens` | 显示或设置 token 预算 (`--context <N>`, `--dialectic <N>`) |
+| `hermes honcho sessions` | 列出已知的“目录到会话名称”映射 |
+| `hermes honcho map <name>` | 将当前工作目录映射到 Honcho 会话名称 |
+| `hermes honcho identity` | 初始化 AI peer 身份或显示双方的 peer 表示 |
+| `hermes honcho sync` | 为所有尚未包含 host block 的 Hermes profiles 创建 host block |
+| `hermes honcho migrate` | 从 OpenClaw 原生记忆迁移到 Hermes + Honcho 的分步指南 |
+| `hermes memory setup` | 通用记忆提供商选择器（选择 "honcho" 会运行相同的向导） |
+| `hermes memory status` | 显示当前活跃的记忆提供商和配置 |
+| `hermes memory off` | 禁用外部记忆提供商 |

package/extensions/skills/optional/autonomous-ai-agents/openhands/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: openhands
+description: 将编码任务委托给 OpenHands CLI（模型无关，基于 LiteLLM）。
+version: 0.1.0
+author: Tim Koepsel (xzessmedia), Hermes Agent
+license: MIT
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags: [Coding-Agent, OpenHands, Model-Agnostic, LiteLLM]
+    related_skills: [claude-code, codex, opencode, hermes-agent]
+---
+
+# OpenHands CLI
+
+通过 `terminal` 工具将编码任务委托给 [OpenHands CLI](https://github.com/All-Hands-AI/OpenHands)。OpenHands 是模型无关的：支持任何兼容 LiteLLM 的提供商（OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM 等）。
+
+此 skill 是用于批处理/一次性委托的无头模式（headless-mode）封装器。Hermes 不使用交互式的文本 UI。
+
+## 何时使用
+
+- 用户希望专门将编码任务委托给 OpenHands。
+- 用户希望运行在非 Anthropic / 非 OpenAI 提供商（DeepSeek, Qwen, Ollama, vLLM, Nous 等）上的编码 Agent —— 同类的 skill `claude-code` 和 `codex` 绑定了单一供应商。
+- 工作区内的多步骤文件编辑 + shell 命令。
+
+对于原生的 Claude，首选 `claude-code`。对于原生的 OpenAI，首选 `codex`。对于原生的 Hermes 子 Agent，请使用 `delegate_task`。
+
+## 前置条件
+
+1. 安装上游版本（需要 Python 3.12+ 和 `uv`）：
+
+   ```
+   terminal(command="uv tool install openhands --python 3.12")
+   ```
+
+   验证：`openhands --version`（撰写本文时为 `OpenHands CLI 1.16.0` / `SDK v1.21.0`）。
+
+2. 选择一个模型并为 `--override-with-envs` 设置环境变量：
+
+   ```
+   export LLM_MODEL=openrouter/openai/gpt-4o-mini       # 或任何 LiteLLM slug
+   export LLM_API_KEY=$OPENROUTER_API_KEY
+   export LLM_BASE_URL=https://openrouter.ai/api/v1     # 如果是原生 OpenAI 则省略
+   ```
+
+   `LLM_MODEL` 使用 LiteLLM 的完整 slug。当提供商为 OpenRouter 时，slug 带有双重前缀：`openrouter/<vendor>/<model>`（例如 `openrouter/anthropic/claude-sonnet-4.5`）。对于原生 Anthropic：`anthropic/claude-sonnet-4-5`。对于原生 OpenAI：`openai/gpt-4o-mini`。
+
+3. 抑制启动横幅，以确保 JSON 输出前不会出现 ASCII 艺术字：
+
+   ```
+   export OPENHANDS_SUPPRESS_BANNER=1
+   ```
+
+## 如何运行
+
+始终通过 `terminal` 工具调用。为了实现自动化，始终传递 `--headless --json --override-with-envs --exit-without-confirmation`。
+
+### 一次性任务
+
+```
+terminal(
+  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Add error handling to all API calls in src/'",
+  workdir="/path/to/project",
+  timeout=600
+)
+```
+
+### 针对长任务的后台运行
+
+```
+terminal(command="<same as above>", workdir="/path/to/project", background=true, notify_on_complete=true)
+process(action="poll", session_id="<id>")
+process(action="log", session_id="<id>")
+```
+
+### 恢复先前的对话
+
+OpenHands 在每次运行结束时打印 `Conversation ID: <32-hex>` 和一行 `Hint: openhands --resume <dashed-uuid>`。使用带连字符的形式来恢复：
+
+```
+terminal(
+  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=... openhands --headless --json --override-with-envs --exit-without-confirmation --resume <dashed-uuid> -t 'Now fix the bug you found'",
+  workdir="/path/to/project"
+)
+```
+
+## 实际的标志列表
+
+通过 `openhands --help`（CLI 1.16.0）验证。不在此表中的任何内容都不是标志 —— 请通过环境变量或设置文件传递。
+
+| 标志 | 作用 |
+| ------ | -------- |
+| `--headless` | 无 UI，需要 `-t` 或 `-f`。自动批准所有操作（在此模式下没有 `--llm-approve`）。 |
+| `--json` | JSONL 事件流（需要 `--headless`）。 |
+| `-t TEXT` | 任务提示词。 |
+| `-f PATH` | 从文件读取任务。 |
+| `--resume [ID]` | 恢复对话。无 ID → 列出最近的对话。 |
+| `--last` | 恢复最近的一次（与 `--resume` 一起使用）。 |
+| `--override-with-envs` | 应用 `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` 环境变量。若不添加此参数，OpenHands 将使用 `~/.openhands/settings.json` 并忽略环境变量。 |
+| `--exit-without-confirmation` | 不显示“确定要退出吗”的对话框。 |
+| `--always-approve` / `--yolo` | 自动批准每个操作（在 `--headless` 中为默认）。 |
+| `--llm-approve` | 基于 LLM 的安全网关（仅限交互模式 —— 在无头模式下不起作用）。 |
+| `--version` / `-v` | 打印版本并退出。 |
+
+**没有 `--model`, `--max-iterations`, `--workspace`, `--sandbox`, `--sandbox-type` 标志。**模型是 `LLM_MODEL`。工作区是您传递给 `terminal` 工具的 `workdir`。沙箱 / 运行时是 `RUNTIME` 和 `SANDBOX_VOLUMES` 环境变量。
+
+## JSON 事件 Schema
+
+使用 `--json --headless` 时，OpenHands 会输出 JSONL —— 每行一个 JSON 对象，外加少量非 JSON 状态行（`Initializing agent...`, `Agent is working`, `Agent finished`, 最后的摘要框, `Goodbye!`, `Conversation ID:`, `Hint:`）。请过滤出以 `{` 开头的行。
+
+顶层的 `kind` 字段用于区分事件：
+
+- `MessageEvent` —— 用户/Agent 的文本回合。`source` 为 `user` 或 `agent`。
+- `ActionEvent` —— Agent 选择了工具。读取 `tool_name`（`file_editor`, `terminal`, `finish`）和 `action.kind`（`FileEditorAction`, `TerminalAction`, `FinishAction`）。
+- `ObservationEvent` —— 工具结果。`observation.is_error` 是成功标志。`source` 为 `environment`。
+- `ActionEvent` 内部的 `FinishAction` 在 `action.message` 中携带 Agent 的最终消息。
+
+CLI 会先打印所有来自 LiteLLM/Authlib 的 stderr —— 请参阅注意事项。仅解析 stdout，逐行处理，忽略不以 `{` 开头的行。
+
+## 注意事项
+
+- **每次调用都会出现 LiteLLM 警告。**CLI 会向 stderr 打印 `bedrock-runtime` 和 `sagemaker-runtime` 警告，因为未安装 `botocore`。此外还有一个 Authlib 弃用警告。这些是噪音，不是故障。在展示给用户之前，请将 stderr 导向 `/dev/null` 或将其过滤掉。
+- **横幅垃圾信息。**如果不设置 `OPENHANDS_SUPPRESS_BANNER=1`，每次运行都会以一个多行的 `+--+` ASCII 框开始，用于宣传该 SDK。请务必导出它。
+- **`--override-with-envs` 对于自动化是强制性的。**没有它，OpenHands 将忽略 `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` 并回退到 `~/.openhands/settings.json`。在全新安装时，此文件不存在，CLI 会挂起等待首次运行设置。
+- **模型 slug 属于 LiteLLM，而不是提供商的。**`openrouter/openai/gpt-4o-mini` 有效；在指向 OpenRouter 时使用 `openai/gpt-4o-mini` 无效。`anthropic/claude-sonnet-4-5`（连字符）是原生 Anthropic；`openrouter/anthropic/claude-sonnet-4.5`（点）是通过 OpenRouter。弄错了 → 会得到令人费解的 LiteLLM 400 错误。
+- **`pip install openhands-ai` 是错误的包。**那是旧版 V0 SDK。新的 CLI 是 `uv tool install openhands --python 3.12`。没有维护的 conda 包。
+- **恢复 ID 格式很挑剔。**CLI 结束时是 `Conversation ID: f46573d9cfdb45e492ca189bde40019b`（无连字符），然后是一个 `Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b`（带连字符）。请使用带连字符的形式。
+- **无头模式忽略 `--llm-approve`。**如果传递此参数，将会收到 argparse 错误。无头模式硬编码为始终批准。
+- **上游不支持 Windows。**OpenHands 文档在 Windows 上需要 WSL。因此，此 skill 被限制在 `[linux, macos]`。
+- **`~/.openhands/conversations/<id>/` 会累积。**每次运行都会保存一个轨迹。如果进行批处理，请对其进行清理。
+- **安装体积庞大（约 200 个包）。**使用 `uv tool install`（隔离的 venv）以避免与当前活动的项目产生依赖冲突。
+
+## 验证
+
+```
+terminal(
+  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Print the string OPENHANDS_OK to stdout via the terminal tool.'",
+  workdir="/tmp",
+  timeout=120
+)
+```
+
+如果 JSONL 流以 `FinishAction` 结束，并且其 `action.message` 提到了 `OPENHANDS_OK`，则说明安装正常工作。
+
+## 相关内容
+
+- [OpenHands GitHub](https://github.com/All-Hands-AI/OpenHands)
+- [OpenHands CLI 命令参考](https://docs.openhands.dev/openhands/usage/cli/command-reference)
+- 同类的 skill：`claude-code`（仅限 Anthropic），`codex`（仅限 OpenAI），`opencode`（通过 OpenCode 的多提供商），`hermes-agent`（通过 `delegate_task` 的 Hermes 子 Agent）。

package/extensions/skills/optional/creative/baoyu-article-illustrator/PORT_NOTES.md

@@ -0,0 +1,48 @@
+# 移植说明 — baoyu-article-illustrator
+
+移植自 [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.57.0。
+
+## 相比上游的变动
+
+对 `SKILL.md`、`references/workflow.md`、`references/usage.md`、`references/style-presets.md`、`references/styles.md`、`references/prompt-construction.md` 和 `prompts/system.md` 进行了适配。23 个 style 文件和 4 个 palette 文件为原样副本。`references/config/` 目录已被完全移除。
+
+### 适配详情
+
+| 变动 | 上游 | Hermes |
+| -------- | ---------- | -------- |
+| Metadata 命名空间 | `openclaw` | `hermes` |
+| 触发方式 | `/baoyu-article-illustrator` slash 命令 + CLI 参数 | 自然语言 skill 匹配 |
+| 用户配置 | EXTEND.md（project/user/XDG 路径）+ 首次设置 | 已移除 — 不属于 Hermes infra |
+| 用户提示 | `AskUserQuestion`（批量、多问题） | `clarify` 工具（每次仅限一个问题） |
+| 图像生成 | `baoyu-imagine`（Bun/TypeScript，多 provider，接受 `--ref`，写入本地路径） | `image_generate`（仅返回 URL；agent 通过 `terminal`/`curl` 下载） |
+| 后端选择 | 用户通过 CLI 参数选择 provider | 不可由 agent 选择 — `image_generate` 使用用户配置的 FAL model。从 `prompts/system.md` 中移除了硬编码的 "nano banana pro" 行。 |
+| 参考图像 | 通过 `--ref` 传递给后端，通过 shell 复制 | `vision_analyze` 提取文本描述（二进制文件从不经由 `write_file`/`read_file` 处理）；描述被嵌入到 prompts 中。可选使用 `terminal cp` 保存本地记录。 |
+| 平台支持 | Linux/macOS/Windows/WSL/PowerShell | 仅限 Linux/macOS |
+| 文件操作 | Bash 命令 | Hermes 文件工具：使用 `write_file`/`read_file` 处理文本，`terminal` 处理二进制文件和 URL 下载，`vision_analyze` 读取图像 |
+| 水印 | 由 EXTEND.md 中的 `watermark.enabled` 控制 | 可选 — 用户按文章提出需求 |
+| 输出目录 | EXTEND.md `default_output_dir`（imgs-subdir / same-dir / illustrations-subdir / independent） | 基于输入类型的默认值；用户在请求时覆盖 |
+
+### 保留的内容
+
+- Type × Style × Palette 三维框架
+- 所有 style 定义（23 个文件，原样保留）
+- 所有 palette 定义（4 个文件，原样保留）
+- Core 参考文件（workflow、prompt-construction、styles、style-presets）— 已针对 Hermes 工具进行适配
+- Core 原则与 workflow 结构（analyze → confirm → outline → prompts → generate）
+- 将 prompt 文件作为可复现记录的原则
+| 作者、版本、主页归属信息
+
+## 与上游同步
+
+拉取上游更新：
+
+```bash
+# 对比版本
+curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/SKILL.md | head -5
+# 查找 version: 行
+
+# Diff style/palette 文件（可安全覆盖 — 与上游一致）
+diff <(curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/references/styles/blueprint.md) references/styles/blueprint.md
+```
+
+`references/styles/*` 和 `references/palettes/*` 可以直接覆盖。`SKILL.md`、`references/workflow.md`、`references/usage.md`、`references/style-presets.md`、`references/styles.md`、`references/prompt-construction.md` 和 `prompts/system.md` 必须手动合并，因为它们包含了针对 Hermes 的特定适配（工具连接、后端中立性、移除的 EXTEND.md 引用）。