better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/cron-internals.md

@@ -0,0 +1,236 @@
+---
+sidebar_position: 11
+title: "Cron 内部机制"
+description: "Hermes 如何存储、调度、编辑、暂停、加载技能以及投递 cron 任务"
+---
+
+# Cron 内部机制
+
+cron 子系统提供定时任务执行能力——从简单的单次延迟到带技能注入和跨平台投递的周期性 cron 表达式任务。
+
+## 关键文件
+
+| 文件 | 用途 |
+|------|---------|
+| `cron/jobs.py` | 任务模型、存储、对 `jobs.json` 的原子读写 |
+| `cron/scheduler.py` | 调度器循环——到期任务检测、执行、重复计数跟踪 |
+| `tools/cronjob_tools.py` | 面向模型的 `cronjob` 工具注册与处理器 |
+| `gateway/run.py` | Gateway 集成——在长运行循环中触发 cron tick |
+| `hermes_cli/cron.py` | CLI `hermes cron` 子命令 |
+
+## 调度模型
+
+支持四种调度格式：
+
+| 格式 | 示例 | 行为 |
+|--------|---------|----------|
+| **相对延迟** | `30m`、`2h`、`1d` | 单次触发，在指定时长后执行 |
+| **间隔** | `every 2h`、`every 30m` | 周期触发，按固定间隔执行 |
+| **Cron 表达式** | `0 9 * * *` | 标准 5 字段 cron 语法（分钟、小时、日、月、星期） |
+| **ISO 时间戳** | `2025-01-15T09:00:00` | 单次触发，在精确时间点执行 |
+
+面向模型的接口是单个 `cronjob` 工具，支持以下操作：`create`、`list`、`update`、`pause`、`resume`、`run`、`remove`。
+
+## 任务存储
+
+任务存储在 `~/.hermes/cron/jobs.json` 中，采用原子写入语义（先写入临时文件，再重命名）。每条任务记录包含：
+
+```json
+{
+  "id": "a1b2c3d4e5f6",
+  "name": "Daily briefing",
+  "prompt": "Summarize today's AI news and funding rounds",
+  "schedule": {
+    "kind": "cron",
+    "expr": "0 9 * * *",
+    "display": "0 9 * * *"
+  },
+  "skills": ["ai-funding-daily-report"],
+  "deliver": "telegram:-1001234567890",
+  "repeat": {
+    "times": null,
+    "completed": 42
+  },
+  "state": "scheduled",
+  "enabled": true,
+  "next_run_at": "2025-01-16T09:00:00Z",
+  "last_run_at": "2025-01-15T09:00:00Z",
+  "last_status": "ok",
+  "created_at": "2025-01-01T00:00:00Z",
+  "model": null,
+  "provider": null,
+  "script": null
+}
+```
+
+### 任务生命周期状态
+
+| 状态 | 含义 |
+|-------|---------|
+| `scheduled` | 活跃，将在下次计划时间触发 |
+| `paused` | 已暂停——恢复前不会触发 |
+| `completed` | 重复次数已耗尽，或单次任务已执行 |
+| `running` | 正在执行（瞬态状态） |
+
+### 向后兼容性
+
+旧版任务可能使用单个 `skill` 字段而非 `skills` 数组。调度器在加载时会对此进行规范化——单个 `skill` 会被提升为 `skills: [skill]`。
+
+## 调度器运行时
+
+### Tick 周期
+
+调度器按周期性 tick 运行（默认：每 60 秒）：
+
+```text
+tick()
+  1. 获取调度器锁（防止 tick 重叠）
+  2. 从 jobs.json 加载所有任务
+  3. 筛选到期任务（next_run <= now 且 state == "scheduled"）
+  4. 对每个到期任务：
+     a. 将状态设为 "running"
+     b. 创建全新的 AIAgent 会话（无对话历史）
+     c. 按顺序加载附加技能（以用户消息形式注入）
+     d. 通过 agent 执行任务 prompt（提示词）
+     e. 将响应投递到配置的目标
+     f. 更新 run_count，计算下次运行时间
+     g. 若重复次数耗尽 → state = "completed"
+     h. 否则 → state = "scheduled"
+  5. 将更新后的任务写回 jobs.json
+  6. 释放调度器锁
+```
+
+### Gateway 集成
+
+在 gateway 模式下，调度器运行在专用后台线程中（`gateway/run.py` 中的 `_start_cron_ticker`），每 60 秒调用一次 `scheduler.tick()`，与消息处理并行运行。
+
+在 CLI 模式下，cron 任务仅在运行 `hermes cron` 命令或活跃 CLI 会话期间触发。
+
+### 全新会话隔离
+
+每个 cron 任务在完全全新的 agent 会话中运行：
+
+- 无前次运行的对话历史
+- 无前次 cron 执行的记忆（除非已持久化到内存/文件）
+- prompt 必须自包含——cron 任务无法提出澄清性问题
+- `cronjob` 工具集已禁用（递归防护）
+
+## 技能支持的任务
+
+cron 任务可通过 `skills` 字段附加一个或多个技能。执行时：
+
+1. 按指定顺序加载技能
+2. 每个技能的 SKILL.md 内容作为上下文注入
+3. 任务的 prompt 作为任务指令追加
+4. Agent 处理技能上下文与 prompt 的组合内容
+
+这使得可复用、经过测试的工作流无需将完整指令粘贴到 cron prompt 中。例如：
+
+```
+创建每日融资报告 → 附加 "ai-funding-daily-report" 技能
+```
+
+### 脚本支持的任务
+
+任务还可通过 `script` 字段附加 Python 脚本。该脚本在每次 agent 轮次*之前*运行，其 stdout 作为上下文注入到 prompt 中。这支持数据采集和变更检测模式：
+
+```python
+# ~/.hermes/scripts/check_competitors.py
+import requests, json
+# 获取竞争对手发布说明，与上次运行结果进行差异比对
+# 将摘要打印到 stdout——agent 进行分析并报告
+```
+
+脚本超时默认为 120 秒。`_get_script_timeout()` 通过三层链路解析限制：
+
+1. **模块级覆盖** — `_SCRIPT_TIMEOUT`（用于测试/monkeypatching）。仅在与默认值不同时使用。
+2. **环境变量** — `HERMES_CRON_SCRIPT_TIMEOUT`
+3. **配置** — `config.yaml` 中的 `cron.script_timeout_seconds`（通过 `load_config()` 读取）
+4. **默认值** — 120 秒
+
+### Provider 恢复
+
+`run_job()` 将用户配置的备用 provider 和凭证池传入 `AIAgent` 实例：
+
+- **备用 provider** — 从 `config.yaml` 读取 `fallback_providers`（列表）或 `fallback_model`（旧版字典），与 gateway 的 `_load_fallback_model()` 模式一致。以 `fallback_model=` 形式传入 `AIAgent.__init__`，后者将两种格式规范化为备用链。
+- **凭证池** — 通过 `agent.credential_pool` 中的 `load_pool(provider)` 使用解析后的运行时 provider 名称加载。仅在池中有凭证时传入（`pool.has_credentials()`）。在遭遇 429/限速错误时启用同 provider 的密钥轮换。
+
+这与 gateway 的行为保持一致——否则 cron agent 在遭遇限速时将直接失败而不尝试恢复。
+
+## 投递模型
+
+Cron 任务结果可投递到任何受支持的平台。
+
+裸平台名（`slack`、`telegram` 等）会投递到该平台配置的**主频道**。若要投递到**特定**目标，请在冒号后追加目标：`platform:<target>`。目标在任务触发时解析（而非创建时），因此任务可以指定一个尚未连接的平台目标，待其上线后即开始投递。
+
+大多数平台还支持以第三段指定可选的话题/线程：`platform:<chat_id>:<thread_id>`。
+
+| 目标 | 语法 | 示例 |
+|--------|--------|---------|
+| 来源聊天 | `origin` | 投递到创建该任务的聊天 |
+| 本地文件 | `local` | 保存到 `~/.hermes/cron/output/` |
+| Telegram | `telegram`、`telegram:<chat_id>`、`telegram:<chat_id>:<thread_id>`、`telegram:@username` | `telegram:-1001234567890:17585` |
+| Discord | `discord`、`discord:#channel`、`discord:<channel_id>`、`discord:<channel_id>:<thread_id>` | `discord:#engineering` |
+| Slack | `slack`、`slack:#channel`、`slack:<channel_id>`、`slack:<channel_id>:<thread_ts>` | `slack:#engineering` |
+| Matrix | `matrix`、`matrix:<!room_id:server>`、`matrix:<@user:server>` | `matrix:!abc123:example.org` |
+| Feishu | `feishu`、`feishu:<chat_id>`、`feishu:<chat_id>:<thread_id>` | `feishu:oc_abc123def` |
+| WhatsApp | `whatsapp`、`whatsapp:<jid>`、`whatsapp:+<E.164>` | `whatsapp:123456@g.us` |
+| Signal | `signal`、`signal:group:<id>`、`signal:+<E.164>` | `signal:group:aBcD==` |
+| SMS | `sms`、`sms:+<E.164>` | `sms:+<E.164 号码>` |
+| Email | `email`、`email:<address>` | `email:alerts@example.com` |
+| Weixin | `weixin`、`weixin:<wxid>` | `weixin:wxid_abc123` |
+| Mattermost | `mattermost` 或 `mattermost:<channel_id>` | 裸名投递到 Mattermost 主频道 |
+| Home Assistant | `homeassistant` 或 `homeassistant:<conversation>` | 裸名投递到 HA 对话 |
+| DingTalk | `dingtalk` 或 `dingtalk:<chat_id>` | 裸名投递到钉钉 |
+| WeCom | `wecom` 或 `wecom:<chat_id>` | 裸名投递到企业微信 |
+| BlueBubbles | `bluebubbles` 或 `bluebubbles:<chat_guid>` | 裸名通过 BlueBubbles 投递到 iMessage |
+| QQ Bot | `qqbot` 或 `qqbot:<chat_id>` | 裸名通过官方 API v2 投递到 QQ（腾讯） |
+
+第一组平台具有显式、经校验的目标语法——具名频道（`#channel`）、话题/线程、房间/用户 ID、群组 ID 或电话号码。其余平台接受通用的 `platform:<chat_id>` 形式（冒号后的值原样用作目标 ID）；裸平台名始终投递到主频道。
+
+**具名频道**（`slack:#engineering`、`discord:#engineering`，或像 `slack:engineering` 这样的友好名称）会根据 gateway 从已连接适配器构建的频道目录进行解析，因此 gateway 必须已发现该频道，名称解析才能成功；原始 ID（`slack:C0123ABCD45`）则始终可用。
+
+对于 **Telegram 话题**，使用 `telegram:<chat_id>:<thread_id>`（例如 `telegram:-1001234567890:17585`）。对于 **Slack 线程**，第三段是父消息的 `thread_ts`（例如 `slack:C0123ABCD45:1700000000.000100`），因此仅在回复某条已有消息下方时适用。
+
+### 响应包装
+
+默认情况下（`cron.wrap_response: true`），cron 投递内容会被包装：
+- 头部标识 cron 任务名称和任务内容
+- 尾部说明 agent 无法在对话中看到已投递的消息
+
+cron 响应中的 `[SILENT]` 前缀会完全抑制投递——适用于只需写入文件或执行副作用的任务。
+
+### 会话隔离
+
+Cron 投递**不会**镜像到 gateway 会话的对话历史中。它们仅存在于 cron 任务自身的会话中。这可防止目标聊天对话中出现消息交替违规。
+
+## 递归防护
+
+Cron 运行的会话已禁用 `cronjob` 工具集。这可防止：
+- 定时任务创建新的 cron 任务
+- 可能导致 token 用量爆炸的递归调度
+- 在任务内部意外修改任务调度
+
+## 锁机制
+
+调度器使用跨进程文件锁（Unix 上的 `fcntl.flock`，Windows 上的 `msvcrt.locking`）防止重叠的 tick 对同一批到期任务执行两次——即使在 gateway 的进程内 ticker 与独立的 `hermes cron` / 手动 `tick()` 调用之间也如此。若无法获取锁，`tick()` 立即返回 0。
+
+## CLI 接口
+
+`hermes cron` CLI 提供直接的任务管理功能：
+
+```bash
+hermes cron list                    # 显示所有任务
+hermes cron create                  # 交互式创建任务（别名：add）
+hermes cron edit <job_id>           # 编辑任务配置
+hermes cron pause <job_id>          # 暂停运行中的任务
+hermes cron resume <job_id>         # 恢复已暂停的任务
+hermes cron run <job_id>            # 触发立即执行
+hermes cron remove <job_id>         # 删除任务
+```
+
+## 相关文档
+
+- [Cron 功能指南](/user-guide/features/cron)
+- [Gateway 内部机制](./gateway-internals.md)
+- [Agent 循环内部机制](./agent-loop.md)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/extending-the-cli.md

@@ -0,0 +1,192 @@
+---
+sidebar_position: 8
+title: "扩展 CLI"
+description: "构建包装 CLI，通过自定义 widget、快捷键和布局变更来扩展 Hermes TUI"
+---
+
+# 扩展 CLI
+
+Hermes 在 `HermesCLI` 上暴露了受保护的扩展 hook（钩子），使包装 CLI 可以添加 widget、快捷键和布局自定义，而无需覆盖超过 1000 行的 `run()` 方法。这样可以让你的扩展与内部变更解耦。
+
+## 扩展点
+
+共有五个扩展接缝可用：
+
+| Hook | 用途 | 何时覆盖 |
+|------|---------|------------------|
+| `_get_extra_tui_widgets()` | 向布局注入 widget | 需要持久 UI 元素（面板、状态栏、迷你播放器）时 |
+| `_register_extra_tui_keybindings(kb, *, input_area)` | 添加键盘快捷键 | 需要热键（切换面板、传输控制、模态快捷键）时 |
+| `_build_tui_layout_children(**widgets)` | 完全控制 widget 排序 | 需要重新排序或包装现有 widget 时（少见） |
+| `process_command()` | 添加自定义斜杠命令 | 需要处理 `/mycommand` 时（已有 hook） |
+| `_build_tui_style_dict()` | 自定义 prompt_toolkit 样式 | 需要自定义颜色或样式时（已有 hook） |
+
+前三个是新增的受保护 hook，后两个已存在。
+
+## 快速开始：包装 CLI
+
+```python
+#!/usr/bin/env python3
+"""my_cli.py — Example wrapper CLI that extends Hermes."""
+
+from cli import HermesCLI
+from prompt_toolkit.layout import FormattedTextControl, Window
+from prompt_toolkit.filters import Condition
+
+
+class MyCLI(HermesCLI):
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._panel_visible = False
+
+    def _get_extra_tui_widgets(self):
+        """Add a toggleable info panel above the status bar."""
+        cli_ref = self
+        return [
+            Window(
+                FormattedTextControl(lambda: "📊 My custom panel content"),
+                height=1,
+                filter=Condition(lambda: cli_ref._panel_visible),
+            ),
+        ]
+
+    def _register_extra_tui_keybindings(self, kb, *, input_area):
+        """F2 toggles the custom panel."""
+        cli_ref = self
+
+        @kb.add("f2")
+        def _toggle_panel(event):
+            cli_ref._panel_visible = not cli_ref._panel_visible
+
+    def process_command(self, cmd: str) -> bool:
+        """Add a /panel slash command."""
+        if cmd.strip().lower() == "/panel":
+            self._panel_visible = not self._panel_visible
+            state = "visible" if self._panel_visible else "hidden"
+            print(f"Panel is now {state}")
+            return True
+        return super().process_command(cmd)
+
+
+if __name__ == "__main__":
+    cli = MyCLI()
+    cli.run()
+```
+
+运行：
+
+```bash
+cd ~/.hermes/hermes-agent
+source .venv/bin/activate
+python my_cli.py
+```
+
+## Hook 参考
+
+### `_get_extra_tui_widgets()`
+
+返回要插入 TUI 布局的 prompt_toolkit widget 列表。Widget 出现在**间隔区与状态栏之间**——位于输入区上方、主输出区下方。
+
+```python
+def _get_extra_tui_widgets(self) -> list:
+    return []  # default: no extra widgets
+```
+
+每个 widget 应为 prompt_toolkit 容器（如 `Window`、`ConditionalContainer`、`HSplit`）。使用 `ConditionalContainer` 或 `filter=Condition(...)` 可使 widget 支持切换显示。
+
+```python
+from prompt_toolkit.layout import ConditionalContainer, Window, FormattedTextControl
+from prompt_toolkit.filters import Condition
+
+def _get_extra_tui_widgets(self):
+    return [
+        ConditionalContainer(
+            Window(FormattedTextControl("Status: connected"), height=1),
+            filter=Condition(lambda: self._show_status),
+        ),
+    ]
+```
+
+### `_register_extra_tui_keybindings(kb, *, input_area)`
+
+在 Hermes 注册自身快捷键之后、布局构建之前调用。将你的快捷键添加到 `kb`。
+
+```python
+def _register_extra_tui_keybindings(self, kb, *, input_area):
+    pass  # default: no extra keybindings
+```
+
+参数：
+- **`kb`** — prompt_toolkit 应用的 `KeyBindings` 实例
+- **`input_area`** — 主 `TextArea` widget，用于读取或操作用户输入
+
+```python
+def _register_extra_tui_keybindings(self, kb, *, input_area):
+    cli_ref = self
+
+    @kb.add("f3")
+    def _clear_input(event):
+        input_area.text = ""
+
+    @kb.add("f4")
+    def _insert_template(event):
+        input_area.text = "/search "
+```
+
+**避免与内置快捷键冲突**：`Enter`（提交）、`Escape Enter`（换行）、`Ctrl-C`（中断）、`Ctrl-D`（退出）、`Tab`（接受自动建议）。F2 及以上的功能键和 Ctrl 组合键通常是安全的。
+
+### `_build_tui_layout_children(**widgets)`
+
+仅在需要完全控制 widget 排序时才覆盖此方法。大多数扩展应使用 `_get_extra_tui_widgets()` 代替。
+
+```python
+def _build_tui_layout_children(self, *, sudo_widget, secret_widget,
+    approval_widget, clarify_widget, model_picker_widget=None,
+    spinner_widget=None, spacer, status_bar, input_rule_top,
+    image_bar, input_area, input_rule_bot, voice_status_bar,
+    completions_menu) -> list:
+```
+
+默认实现返回（值为 `None` 的 widget 会被过滤掉）：
+
+```python
+[
+    Window(height=0),       # anchor
+    sudo_widget,            # sudo password prompt (conditional)
+    secret_widget,          # secret input prompt (conditional)
+    approval_widget,        # dangerous command approval (conditional)
+    clarify_widget,         # clarify question UI (conditional)
+    model_picker_widget,    # model picker overlay (conditional)
+    spinner_widget,         # thinking spinner (conditional)
+    spacer,                 # fills remaining vertical space
+    *self._get_extra_tui_widgets(),  # YOUR WIDGETS GO HERE
+    status_bar,             # model/token/context status line
+    input_rule_top,         # ─── border above input
+    image_bar,              # attached images indicator
+    input_area,             # user text input
+    input_rule_bot,         # ─── border below input
+    voice_status_bar,       # voice mode status (conditional)
+    completions_menu,       # autocomplete dropdown
+]
+```
+
+## 布局示意图
+
+默认布局从上到下：
+
+1. **输出区** — 滚动的对话历史
+2. **间隔区**
+3. **额外 widget** — 来自 `_get_extra_tui_widgets()`
+4. **状态栏** — 模型、上下文占比、已用时间
+5. **图片栏** — 已附加图片数量
+6. **输入区** — 用户 prompt（提示词）
+7. **语音状态** — 录音指示器
+8. **补全菜单** — 自动补全建议
+
+## 使用技巧
+
+- **状态变更后刷新显示**：调用 `self._invalidate()` 触发 prompt_toolkit 重绘。
+- **访问 agent 状态**：`self.agent`、`self.model`、`self.conversation_history` 均可直接使用。
+- **自定义样式**：覆盖 `_build_tui_style_dict()` 并为自定义样式类添加条目。
+- **斜杠命令**：覆盖 `process_command()`，处理自己的命令，其余一律调用 `super().process_command(cmd)`。
+- **不要覆盖 `run()`**，除非绝对必要——扩展 hook 的存在正是为了避免这种耦合。