better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/daily-briefing-bot.md

@@ -1,268 +0,0 @@
----
-sidebar_position: 3
-title: "教程：每日简报机器人"
-description: "构建一个自动化每日简报机器人，研究主题、汇总发现，并每天早晨推送至 Telegram 或 Discord"
----
-
-# 教程：构建每日简报机器人
-
-在本教程中，你将构建一个个人简报机器人，它每天早晨自动启动，研究你关心的主题，汇总发现，并将简洁的简报直接推送到你的 Telegram 或 Discord。
-
-完成后，你将拥有一个完全自动化的工作流，结合了 **网页搜索**、**cron 调度**、**委托（delegation）** 和 **消息推送** — 无需编写代码。
-
-## 我们要构建什么
-
-流程如下：
-
-1. **上午 8:00** — cron 调度器触发任务
-2. **Hermes 启动**一个全新的 agent 会话，使用你的 prompt（提示词）
-3. **网页搜索**拉取你关注主题的最新新闻
-4. **汇总**将内容提炼为简洁的简报格式
-5. **推送**将简报发送到你的 Telegram 或 Discord
-
-整个流程无需人工干预。你只需在早晨喝咖啡时阅读简报即可。
-
-## 前提条件
-
-开始之前，请确保：
-
-- **已安装 Hermes Agent** — 参见[安装指南](/getting-started/installation)
-- **Gateway 正在运行** — gateway 守护进程负责处理 cron 执行：
-  ```bash
-  hermes gateway install   # Install as a user service
-  sudo hermes gateway install --system   # Linux servers: boot-time system service
-  # or
-  hermes gateway           # Run in foreground
-  ```
-- **Firecrawl API 密钥** — 在环境变量中设置 `FIRECRAWL_API_KEY` 以启用网页搜索
-- **已配置消息推送**（可选但推荐）— 已设置 [Telegram](/user-guide/messaging/telegram) 或 Discord 并配置了 home channel
-
-:::tip 没有消息推送？没关系
-你仍然可以使用 `deliver: "local"` 跟随本教程。简报将保存至 `~/.hermes/cron/output/`，你可以随时查阅。
-:::
-
-## 第一步：手动测试工作流
-
-在自动化之前，先确认简报功能正常。启动聊天会话：
-
-```bash
-hermes
-```
-
-然后输入以下 prompt：
-
-```
-Search for the latest news about AI agents and open source LLMs.
-Summarize the top 3 stories in a concise briefing format with links.
-```
-
-Hermes 将搜索网页、阅读结果，并生成类似以下内容：
-
-```
-☀️ Your AI Briefing — March 8, 2026
-
-1. Qwen 3 Released with 235B Parameters
-   Alibaba's latest open-weight model matches GPT-4.5 on several
-   benchmarks while remaining fully open source.
-   → https://qwenlm.github.io/blog/qwen3/
-
-2. LangChain Launches Agent Protocol Standard
-   A new open standard for agent-to-agent communication gains
-   adoption from 15 major frameworks in its first week.
-   → https://blog.langchain.dev/agent-protocol/
-
-3. EU AI Act Enforcement Begins for General-Purpose Models
-   The first compliance deadlines hit, with open source models
-   receiving exemptions under the 10M parameter threshold.
-   → https://artificialintelligenceact.eu/updates/
-
----
-3 stories • Sources searched: 8 • Generated by Hermes Agent
-```
-
-如果运行正常，你就可以开始自动化了。
-
-:::tip 反复调整格式
-尝试不同的 prompt，直到得到你满意的输出。可以添加诸如"使用 emoji 标题"或"每条摘要不超过 2 句话"之类的指令。最终确定的内容将写入 cron 任务。
-:::
-
-## 第二步：创建 Cron 任务
-
-现在让我们将其设置为每天早晨自动运行。有两种方式可以实现。
-
-在创建 cron 任务之前，请确保 Hermes 已全局配置了默认模型和 provider。如果你希望某个任务使用不同的值，可在创建时设置该任务专属的 model/provider 覆盖项。
-
-### 方式 A：自然语言（在聊天中）
-
-直接告诉 Hermes 你想要什么：
-
-```
-Every morning at 8am, search the web for the latest news about AI agents
-and open source LLMs. Summarize the top 3 stories in a concise briefing
-with links. Use a friendly, professional tone. Deliver to telegram.
-```
-
-Hermes 将使用统一的 `cronjob` 工具为你创建 cron 任务。
-
-### 方式 B：CLI 斜杠命令
-
-使用 `/cron` 命令进行更精细的控制：
-
-```
-/cron add "0 8 * * *" "Search the web for the latest news about AI agents and open source LLMs. Find at least 5 recent articles from the past 24 hours. Summarize the top 3 most important stories in a concise daily briefing format. For each story include: a clear headline, a 2-sentence summary, and the source URL. Use a friendly, professional tone. Format with emoji bullet points and end with a total story count."
-```
-
-### 黄金法则：自包含的 Prompt
-
-:::warning 关键概念
-Cron 任务在**全新会话**中运行 — 不保留之前对话的任何记忆，也不了解你"之前设置"的任何内容。你的 prompt 必须包含 agent 完成任务所需的**一切信息**。
-:::
-
-**糟糕的 prompt：**
-```
-Do my usual morning briefing.
-```
-
-**好的 prompt：**
-```
-Search the web for the latest news about AI agents and open source LLMs.
-Find at least 5 recent articles from the past 24 hours. Summarize the
-top 3 most important stories in a concise daily briefing format. For each
-story include: a clear headline, a 2-sentence summary, and the source URL.
-Use a friendly, professional tone. Format with emoji bullet points.
-```
-
-好的 prompt 明确说明了**搜索什么**、**多少篇文章**、**什么格式**以及**什么语气**。它在一次输入中包含了 agent 所需的全部信息。
-
-## 第三步：自定义简报
-
-基础简报运行正常后，你可以进一步发挥创意。
-
-### 多主题简报
-
-在一份简报中涵盖多个领域：
-
-```
-/cron add "0 8 * * *" "Create a morning briefing covering three topics. For each topic, search the web for recent news from the past 24 hours and summarize the top 2 stories with links.
-
-Topics:
-1. AI and machine learning — focus on open source models and agent frameworks
-2. Cryptocurrency — focus on Bitcoin, Ethereum, and regulatory news
-3. Space exploration — focus on SpaceX, NASA, and commercial space
-
-Format as a clean briefing with section headers and emoji. End with today's date and a motivational quote."
-```
-
-### 使用委托进行并行研究
-
-若要加快简报生成速度，可以告诉 Hermes 将每个主题委托给子 agent：
-
-```
-/cron add "0 8 * * *" "Create a morning briefing by delegating research to sub-agents. Delegate three parallel tasks:
-
-1. Delegate: Search for the top 2 AI/ML news stories from the past 24 hours with links
-2. Delegate: Search for the top 2 cryptocurrency news stories from the past 24 hours with links
-3. Delegate: Search for the top 2 space exploration news stories from the past 24 hours with links
-
-Collect all results and combine them into a single clean briefing with section headers, emoji formatting, and source links. Add today's date as a header."
-```
-
-每个子 agent 独立并行搜索，然后主 agent 将所有内容合并为一份精美的简报。详见[委托文档](/user-guide/features/delegation)了解其工作原理。
-
-### 仅工作日调度
-
-不需要周末简报？使用针对周一至周五的 cron 表达式：
-
-```
-/cron add "0 8 * * 1-5" "Search for the latest AI and tech news..."
-```
-
-### 每日两次简报
-
-获取早晨概览和傍晚回顾：
-
-```
-/cron add "0 8 * * *" "Morning briefing: search for AI news from the past 12 hours..."
-/cron add "0 18 * * *" "Evening recap: search for AI news from the past 12 hours..."
-```
-
-### 通过 Memory 添加个人上下文
-
-如果你启用了 [memory（记忆）](/user-guide/features/memory)，可以存储跨会话持久保留的偏好设置。但请记住 — cron 任务在全新会话中运行，不保留对话记忆。若要添加个人上下文，请直接将其写入 prompt：
-
-```
-/cron add "0 8 * * *" "You are creating a briefing for a senior ML engineer who cares about: PyTorch ecosystem, transformer architectures, open-weight models, and AI regulation in the EU. Skip stories about product launches or funding rounds unless they involve open source.
-
-Search for the latest news on these topics. Summarize the top 3 stories with links. Be concise and technical — this reader doesn't need basic explanations."
-```
-
-:::tip 定制受众角色
-在 prompt 中加入简报受众的详细信息，能显著提升内容相关性。告诉 agent 你的角色、兴趣以及需要跳过的内容。
-:::
-
-## 第四步：管理你的任务
-
-### 列出所有已调度任务
-
-在聊天中：
-```
-/cron list
-```
-
-或在终端中：
-```bash
-hermes cron list
-```
-
-你将看到类似以下的输出：
-
-```
-ID          | Name              | Schedule    | Next Run           | Deliver
-------------|-------------------|-------------|--------------------|--------
-a1b2c3d4    | Morning Briefing  | 0 8 * * *   | 2026-03-09 08:00   | telegram
-e5f6g7h8    | Evening Recap     | 0 18 * * *  | 2026-03-08 18:00   | telegram
-```
-
-### 删除任务
-
-在聊天中：
-```
-/cron remove a1b2c3d4
-```
-
-或通过对话方式：
-```
-Remove my morning briefing cron job.
-```
-
-Hermes 将使用 `cronjob(action="list")` 查找任务，并使用 `cronjob(action="remove")` 将其删除。
-
-### 检查 Gateway 状态
-
-确认调度器正在运行：
-
-```bash
-hermes cron status
-```
-
-如果 gateway 未运行，你的任务将不会执行。将其安装为后台服务以确保可靠性：
-
-```bash
-hermes gateway install
-# or on Linux servers
-sudo hermes gateway install --system
-```
-
-## 进一步探索
-
-你已经构建了一个可运行的每日简报机器人。以下是一些可以继续探索的方向：
-
-- **[定时任务（Cron）](/user-guide/features/cron)** — 调度格式、重复限制和推送选项的完整参考
-- **[委托](/user-guide/features/delegation)** — 深入了解并行子 agent 工作流
-- **[消息推送平台](/user-guide/messaging)** — 设置 Telegram、Discord 或其他推送目标
-- **[Memory](/user-guide/features/memory)** — 跨会话的持久上下文
-- **[技巧与最佳实践](/guides/tips)** — 更多 prompt 工程建议
-
-:::tip 还能调度什么？
-简报机器人的模式适用于任何场景：竞争对手监控、GitHub 仓库摘要、天气预报、投资组合追踪、服务器健康检查，甚至每日笑话。只要你能用 prompt 描述它，就能调度它。
-:::

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/delegation-patterns.md

@@ -1,239 +0,0 @@
----
-sidebar_position: 13
-title: "委托与并行工作"
-description: "何时以及如何使用子代理委托——并行研究、代码审查和多文件工作的模式"
----
-
-# 委托与并行工作
-
-Hermes 可以生成隔离的子代理来并行处理任务。每个子代理拥有独立的对话、终端会话和工具集。只有最终摘要会返回——中间工具调用不会进入你的上下文窗口。
-
-完整功能参考，请参阅[子代理委托](/user-guide/features/delegation)。
-
----
-
-## 何时委托
-
-**适合委托的场景：**
-- 推理密集型子任务（调试、代码审查、研究综合）
-- 会用中间数据淹没上下文的任务
-- 并行独立工作流（同时进行研究 A 和研究 B）
-- 需要代理以无偏见方式处理的全新上下文任务
-
-**使用其他方式的场景：**
-- 单次工具调用 → 直接使用工具
-- 步骤间有逻辑的机械性多步骤工作 → `execute_code`
-- 需要用户交互的任务 → 子代理无法使用 `clarify`
-- 快速文件编辑 → 直接操作
-- 必须在会话关闭或进程重启后继续运行的持久性长任务 → `cronjob` 或 `terminal(background=True, notify_on_complete=True)`。顶层委派是异步的，但仍依赖当前进程。
-
----
-
-## 模式：并行研究
-
-同时研究三个主题并获取结构化摘要：
-
-```
-并行研究以下三个主题：
-1. WebAssembly 在浏览器之外的现状
-2. 2025 年 RISC-V 服务器芯片的采用情况
-3. 量子计算的实际应用
-
-重点关注近期进展和关键参与者。
-```
-
-在后台，Hermes 使用：
-
-```python
-delegate_task(tasks=[
-    {
-        "goal": "Research WebAssembly outside the browser in 2025",
-        "context": "Focus on: runtimes (Wasmtime, Wasmer), cloud/edge use cases, WASI progress"
-    },
-    {
-        "goal": "Research RISC-V server chip adoption",
-        "context": "Focus on: server chips shipping, cloud providers adopting, software ecosystem"
-    },
-    {
-        "goal": "Research practical quantum computing applications",
-        "context": "Focus on: error correction breakthroughs, real-world use cases, key companies"
-    }
-])
-```
-
-三个任务并发运行。每个子代理独立搜索网络并返回摘要。父代理随后将它们综合成一份连贯的简报。
-
----
-
-## 模式：代码审查
-
-将安全审查委托给一个全新上下文的子代理，让它以无先入之见的方式审查代码：
-
-```
-审查 src/auth/ 中的认证模块，检查安全问题。
-检查 SQL 注入、JWT 验证问题、密码处理
-和会话管理。修复发现的问题并运行测试。
-```
-
-关键在于 `context` 字段——它必须包含子代理所需的一切信息：
-
-```python
-delegate_task(
-    goal="Review src/auth/ for security issues and fix any found",
-    context="""Project at /home/user/webapp. Python 3.11, Flask, PyJWT, bcrypt.
-    Auth files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py
-    Test command: pytest tests/auth/ -v
-    Focus on: SQL injection, JWT validation, password hashing, session management.
-    Fix issues found and verify tests pass."""
-)
-```
-
-:::warning 上下文问题
-子代理对你的对话**一无所知**。它们从完全空白的状态开始。如果你委托"修复我们讨论的那个 bug"，子代理根本不知道你指的是哪个 bug。务必明确传递文件路径、错误信息、项目结构和约束条件。
-:::
-
----
-
-## 模式：比较备选方案
-
-并行评估同一问题的多种解决方案，然后选出最佳方案：
-
-```
-我需要为 Django 应用添加全文搜索。并行评估三种方案：
-1. PostgreSQL tsvector（内置）
-2. 通过 django-elasticsearch-dsl 使用 Elasticsearch
-3. 通过 meilisearch-python 使用 Meilisearch
-
-对每种方案评估：配置复杂度、查询能力、资源需求
-和维护开销。比较后推荐一种。
-```
-
-每个子代理独立研究一个选项。由于它们相互隔离，不存在交叉干扰——每项评估都基于自身的优缺点。父代理获取全部三份摘要后进行比较。
-
----
-
-## 模式：多文件重构
-
-将大型重构任务拆分给并行子代理，每个子代理负责代码库的不同部分：
-
-```python
-delegate_task(tasks=[
-    {
-        "goal": "Refactor all API endpoint handlers to use the new response format",
-        "context": """Project at /home/user/api-server.
-        Files: src/handlers/users.py, src/handlers/auth.py, src/handlers/billing.py
-        Old format: return {"data": result, "status": "ok"}
-        New format: return APIResponse(data=result, status=200).to_dict()
-        Import: from src.responses import APIResponse
-        Run tests after: pytest tests/handlers/ -v"""
-    },
-    {
-        "goal": "Update all client SDK methods to handle the new response format",
-        "context": """Project at /home/user/api-server.
-        Files: sdk/python/client.py, sdk/python/models.py
-        Old parsing: result = response.json()["data"]
-        New parsing: result = response.json()["data"] (same key, but add status code checking)
-        Also update sdk/python/tests/test_client.py"""
-    },
-    {
-        "goal": "Update API documentation to reflect the new response format",
-        "context": """Project at /home/user/api-server.
-        Docs at: docs/api/. Format: Markdown with code examples.
-        Update all response examples from old format to new format.
-        Add a 'Response Format' section to docs/api/overview.md explaining the schema."""
-    }
-])
-```
-
-:::tip
-每个子代理拥有独立的终端会话。只要它们编辑不同的文件，就可以在同一项目目录中工作而互不干扰。如果两个子代理可能修改同一文件，请在并行工作完成后自行处理该文件。
-:::
-
----
-
-## 模式：先收集后分析
-
-使用 `execute_code` 进行机械性数据收集，然后委托推理密集型分析：
-
-```python
-# 第一步：机械性收集（此处 execute_code 更合适——无需推理）
-execute_code("""
-from hermes_tools import web_search, web_extract
-
-results = []
-for query in ["AI funding Q1 2026", "AI startup acquisitions 2026", "AI IPOs 2026"]:
-    r = web_search(query, limit=5)
-    for item in r["data"]["web"]:
-        results.append({"title": item["title"], "url": item["url"], "desc": item["description"]})
-
-# Extract full content from top 5 most relevant
-urls = [r["url"] for r in results[:5]]
-content = web_extract(urls)
-
-# Save for the analysis step
-import json
-with open("/tmp/ai-funding-data.json", "w") as f:
-    json.dump({"search_results": results, "extracted": content["results"]}, f)
-print(f"Collected {len(results)} results, extracted {len(content['results'])} pages")
-""")
-
-# 第二步：推理密集型分析（此处委托更合适）
-delegate_task(
-    goal="Analyze AI funding data and write a market report",
-    context="""Raw data at /tmp/ai-funding-data.json contains search results and
-    extracted web pages about AI funding, acquisitions, and IPOs in Q1 2026.
-    Write a structured market report: key deals, trends, notable players,
-    and outlook. Focus on deals over $100M."""
-)
-```
-
-这通常是最高效的模式：`execute_code` 以低成本处理 10 余次顺序工具调用，然后子代理在干净的上下文中完成单次高成本推理任务。
-
----
-
-## 继承的工具访问权限
-
-子代理会继承父代理已启用的工具集。`delegate_task` 不接受面向模型的 `toolsets` 参数，因此委派任务无法自行授予父代理没有的能力。如果委派任务需要网络、终端、文件或其他访问权限，请在开始对话前配置父代理的工具。Hermes 仍会移除 `clarify`、`memory` 和 `execute_code` 等对子代理屏蔽的工具。
-
----
-
-## 约束条件
-
-- **默认 3 个并行任务**：批次默认并发 3 个子代理（可通过 config.yaml 中的 `delegation.max_concurrent_children` 配置，无硬性上限，最低为 1）
-- **嵌套委托需显式启用**：叶子子代理（默认）无法调用 `delegate_task`、`clarify`、`memory`、`send_message` 或 `execute_code`。编排器子代理（`role="orchestrator"`）保留 `delegate_task` 以支持进一步委托，但仅在 `delegation.max_spawn_depth` 高于默认值 1 时生效（支持 1-3）；其余四项仍被禁用。可通过 `delegation.orchestrator_enabled: false` 全局禁用。
-
-### 调整并发数与深度
-
-| 配置项 | 默认值 | 范围 | 效果 |
-|--------|---------|-------|--------|
-| `max_concurrent_children` | 3 | >=1 | 每次 `delegate_task` 调用的并行批次大小 |
-| `max_spawn_depth` | 1 | 1-3 | 可进一步生成子代理的委托层级数 |
-
-示例：运行 30 个并行 worker 并启用嵌套子代理：
-
-```yaml
-delegation:
-  max_concurrent_children: 30
-  max_spawn_depth: 2
-```
-
-- **独立终端** — 每个子代理拥有独立的终端会话，具有独立的工作目录和状态
-- **无对话历史** — 子代理只能看到父代理调用 `delegate_task` 时传入的 `goal` 和 `context`
-- **默认 50 次迭代** — 对简单任务设置较低的 `max_iterations` 以节省成本
-- **非持久性** — 顶层委派会在后台运行并稍后发送结果，但仍依赖所属会话和 Hermes 进程。会话关闭、`/stop`、`/new` 或进程重启都可能取消或遗留正在执行的工作。对于必须跨越这些边界继续运行的任务，请使用 `cronjob` 或 `terminal(background=True, notify_on_complete=True)`。
-
----
-
-## 技巧
-
-**目标要具体。** "修复 bug"过于模糊。"修复 api/handlers.py 第 47 行的 TypeError，该错误由 parse_body() 向 process_request() 返回 None 引起"才能给子代理足够的信息。
-
-**包含文件路径。** 子代理不了解你的项目结构。务必提供相关文件的绝对路径、项目根目录和测试命令。
-
-**利用委托实现上下文隔离。** 有时你需要全新的视角。委托迫使你清晰地阐述问题，而子代理会在没有对话中积累的假设前提下处理它。
-
-**核验结果。** 子代理的摘要只是摘要。如果子代理说"修复了 bug 且测试通过"，请自行运行测试或查看 diff 来验证。
-
----
-
-*完整的委托参考——所有参数、ACP 集成和高级配置——请参阅[子代理委托](/user-guide/features/delegation)。*