better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md

@@ -0,0 +1,237 @@
+---
+title: "Opencode — 将编码任务委托给 OpenCode CLI（功能开发、PR 审查）"
+sidebar_label: "Opencode"
+description: "将编码任务委托给 OpenCode CLI（功能开发、PR 审查）"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Opencode
+
+将编码任务委托给 OpenCode CLI（功能开发、PR 审查）。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/autonomous-ai-agents/opencode` |
+| 版本 | `1.2.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Coding-Agent`, `OpenCode`, `Autonomous`, `Refactoring`, `Code-Review` |
+| 相关 skill | [`claude-code`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# OpenCode CLI
+
+使用 [OpenCode](https://opencode.ai) 作为由 Hermes 终端/进程工具编排的自主编码工作器。OpenCode 是一个支持多 provider、开源的 AI 编码 agent，具备 TUI（终端用户界面）和 CLI。
+
+## 适用场景
+
+- 用户明确要求使用 OpenCode
+- 需要外部编码 agent 来实现/重构/审查代码
+- 需要长时间运行的编码会话并定期检查进度
+- 需要在隔离的工作目录/worktree 中并行执行任务
+
+## 前置条件
+
+- 已安装 OpenCode：`npm i -g opencode-ai@latest` 或 `brew install anomalyco/tap/opencode`
+- 已配置认证：`opencode auth login` 或设置 provider 环境变量（OPENROUTER_API_KEY 等）
+- 验证：`opencode auth list` 应显示至少一个 provider
+- 代码任务推荐使用 Git 仓库
+- 交互式 TUI 会话需要 `pty=true`
+
+## 二进制文件解析（重要）
+
+Shell 环境可能会解析到不同的 OpenCode 二进制文件。如果你的终端与 Hermes 的行为不一致，请检查：
+
+```
+terminal(command="which -a opencode")
+terminal(command="opencode --version")
+```
+
+如有需要，可固定使用明确的二进制路径：
+
+```
+terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)
+```
+
+## 单次任务
+
+使用 `opencode run` 执行有边界的非交互式任务：
+
+```
+terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")
+```
+
+使用 `-f` 附加上下文文件：
+
+```
+terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")
+```
+
+使用 `--thinking` 显示模型思考过程：
+
+```
+terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")
+```
+
+强制指定特定模型：
+
+```
+terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")
+```
+
+## 交互式会话（后台运行）
+
+对于需要多轮交互的迭代工作，在后台启动 TUI：
+
+```
+terminal(command="opencode", workdir="~/project", background=true, pty=true)
+# 返回 session_id
+
+# 发送 prompt（提示词）
+process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")
+
+# 监控进度
+process(action="poll", session_id="<id>")
+process(action="log", session_id="<id>")
+
+# 发送后续输入
+process(action="submit", session_id="<id>", data="Now add error handling for token expiry")
+
+# 干净退出 — Ctrl+C
+process(action="write", session_id="<id>", data="\x03")
+# 或直接终止进程
+process(action="kill", session_id="<id>")
+```
+
+**重要：** 不要使用 `/exit`——它不是有效的 OpenCode 命令，会打开 agent 选择器对话框。请使用 Ctrl+C（`\x03`）或 `process(action="kill")` 退出。
+
+### TUI 快捷键
+
+| 按键 | 操作 |
+|-----|--------|
+| `Enter` | 提交消息（如有需要可按两次） |
+| `Tab` | 在 agent 之间切换（build/plan） |
+| `Ctrl+P` | 打开命令面板 |
+| `Ctrl+X L` | 切换会话 |
+| `Ctrl+X M` | 切换模型 |
+| `Ctrl+X N` | 新建会话 |
+| `Ctrl+X E` | 打开编辑器 |
+| `Ctrl+C` | 退出 OpenCode |
+
+### 恢复会话
+
+退出后，OpenCode 会打印会话 ID。使用以下命令恢复：
+
+```
+terminal(command="opencode -c", workdir="~/project", background=true, pty=true)  # 继续上次会话
+terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # 指定会话
+```
+
+## 常用标志
+
+| 标志 | 用途 |
+|------|-----|
+| `run 'prompt'` | 单次执行后退出 |
+| `--continue` / `-c` | 继续上次 OpenCode 会话 |
+| `--session <id>` / `-s` | 继续指定会话 |
+| `--agent <name>` | 选择 OpenCode agent（build 或 plan） |
+| `--model provider/model` | 强制使用指定模型 |
+| `--format json` | 机器可读的输出/事件 |
+| `--file <path>` / `-f` | 向消息附加文件 |
+| `--thinking` | 显示模型思考块 |
+| `--variant <level>` | 推理强度（high、max、minimal） |
+| `--title <name>` | 为会话命名 |
+| `--attach <url>` | 连接到正在运行的 opencode 服务器 |
+
+## 操作流程
+
+1. 验证工具就绪状态：
+   - `terminal(command="opencode --version")`
+   - `terminal(command="opencode auth list")`
+2. 对于有边界的任务，使用 `opencode run '...'`（无需 pty）。
+3. 对于迭代任务，使用 `background=true, pty=true` 启动 `opencode`。
+4. 使用 `process(action="poll"|"log")` 监控长时间运行的任务。
+5. 如果 OpenCode 请求输入，通过 `process(action="submit", ...)` 响应。
+6. 使用 `process(action="write", data="\x03")` 或 `process(action="kill")` 退出，切勿使用 `/exit`。
+7. 向用户汇总文件变更、测试结果及后续步骤。
+
+## PR 审查工作流
+
+OpenCode 内置 PR 命令：
+
+```
+terminal(command="opencode pr 42", workdir="~/project", pty=true)
+```
+
+或在临时克隆中审查以实现隔离：
+
+```
+terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)
+```
+
+## 并行工作模式
+
+使用独立的工作目录/worktree 避免冲突：
+
+```
+terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
+terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
+process(action="list")
+```
+
+## 会话与成本管理
+
+列出历史会话：
+
+```
+terminal(command="opencode session list")
+```
+
+查看 token 用量和费用：
+
+```
+terminal(command="opencode stats")
+terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")
+```
+
+## 注意事项
+
+- 交互式 `opencode`（TUI）会话需要 `pty=true`。`opencode run` 命令**不需要** pty。
+- `/exit` **不是**有效命令——它会打开 agent 选择器。请使用 Ctrl+C 退出 TUI。
+- PATH 不匹配可能导致选择错误的 OpenCode 二进制文件/模型配置。
+- 如果 OpenCode 看起来卡住了，在终止前先检查日志：
+  - `process(action="log", session_id="<id>")`
+- 避免多个并行 OpenCode 会话共享同一工作目录。
+- 在 TUI 中可能需要按两次 Enter 才能提交（第一次确认文本，第二次发送）。
+
+## 验证
+
+冒烟测试：
+
+```
+terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")
+```
+
+成功标准：
+- 输出包含 `OPENCODE_SMOKE_OK`
+- 命令退出时无 provider/模型错误
+- 对于代码任务：预期文件已变更且测试通过
+
+## 规则
+
+1. 单次自动化任务优先使用 `opencode run`——更简单且无需 pty。
+2. 仅在需要迭代时使用交互式后台模式。
+3. 始终将 OpenCode 会话限定在单个仓库/工作目录内。
+4. 对于长时间任务，从 `process` 日志中提供进度更新。
+5. 报告具体结果（文件变更、测试情况、剩余风险）。
+6. 使用 Ctrl+C 或 kill 退出交互式会话，切勿使用 `/exit`。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-architecture-diagram.md

@@ -0,0 +1,165 @@
+---
+title: "Architecture Diagram — 深色主题 SVG 架构/云/基础设施图表（HTML 格式）"
+sidebar_label: "Architecture Diagram"
+description: "深色主题 SVG 架构/云/基础设施图表（HTML 格式）"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Architecture Diagram
+
+深色主题 SVG 架构/云/基础设施图表，以 HTML 格式输出。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/creative/architecture-diagram` |
+| 版本 | `1.0.0` |
+| 作者 | Cocoon AI (hello@cocoon-ai.com)，由 Hermes Agent 移植 |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `architecture`, `diagrams`, `SVG`, `HTML`, `visualization`, `infrastructure`, `cloud` |
+| 相关 skill | [`concept-diagrams`](/user-guide/skills/optional/creative/creative-concept-diagrams), [`excalidraw`](/user-guide/skills/bundled/creative/creative-excalidraw) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Architecture Diagram Skill
+
+生成专业的深色主题技术架构图，输出为包含内联 SVG 图形的独立 HTML 文件。无需外部工具、无需 API 密钥、无需渲染库——只需写入 HTML 文件并在浏览器中打开即可。
+
+## 适用范围
+
+**最适合：**
+- 软件系统架构（前端/后端/数据库层）
+- 云基础设施（VPC、区域、子网、托管服务）
+- 微服务/服务网格拓扑
+- 数据库 + API 映射、部署图
+- 任何具有技术基础设施主题、适合深色网格背景风格的内容
+
+**以下场景请优先考虑其他工具：**
+- 物理、化学、数学、生物或其他科学学科
+- 实物对象（车辆、硬件、解剖结构、截面图）
+- 平面图、叙事流程、教育/教科书风格的视觉内容
+- 手绘白板草图（建议使用 `excalidraw`）
+- 动画说明（建议使用动画相关 skill）
+
+如果有更专业的 skill 适用于该主题，请优先使用。如果没有合适的，本 skill 也可作为通用 SVG 图表的备选方案——输出内容将带有下述深色技术风格。
+
+基于 [Cocoon AI 的 architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator)（MIT 许可证）。
+
+## 工作流程
+
+1. 用户描述其系统架构（组件、连接关系、技术栈）
+2. 按照下方设计规范生成 HTML 文件
+3. 使用 `write_file` 保存为 `.html` 文件（例如 `~/architecture-diagram.html`）
+4. 用户在任意浏览器中打开——支持离线使用，无需任何依赖
+
+### 输出位置
+
+将图表保存到用户指定路径，或默认保存至当前工作目录：
+```
+./[project-name]-architecture.html
+```
+
+### 预览
+
+保存后，建议用户通过以下命令打开：
+```bash
+# macOS
+open ./my-architecture.html
+# Linux
+xdg-open ./my-architecture.html
+```
+
+## 设计规范与视觉语言
+
+### 颜色方案（语义映射）
+
+使用特定的 `rgba` 填充色和十六进制描边色对组件进行分类：
+
+| 组件类型 | 填充色（rgba） | 描边色（Hex） |
+| :--- | :--- | :--- |
+| **前端** | `rgba(8, 51, 68, 0.4)` | `#22d3ee`（cyan-400） |
+| **后端** | `rgba(6, 78, 59, 0.4)` | `#34d399`（emerald-400） |
+| **数据库** | `rgba(76, 29, 149, 0.4)` | `#a78bfa`（violet-400） |
+| **AWS/云** | `rgba(120, 53, 15, 0.3)` | `#fbbf24`（amber-400） |
+| **安全** | `rgba(136, 19, 55, 0.4)` | `#fb7185`（rose-400） |
+| **消息总线** | `rgba(251, 146, 60, 0.3)` | `#fb923c`（orange-400） |
+| **外部** | `rgba(30, 41, 59, 0.5)` | `#94a3b8`（slate-400） |
+
+### 字体与背景
+- **字体：** JetBrains Mono（等宽字体），从 Google Fonts 加载
+- **字号：** 12px（名称）、9px（副标签）、8px（注释）、7px（极小标签）
+- **背景：** Slate-950（`#020617`），带有细腻的 40px 网格图案
+
+```svg
+<!-- 背景网格图案 -->
+<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+  <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
+</pattern>
+```
+
+## 技术实现细节
+
+### 组件渲染
+组件为圆角矩形（`rx="6"`），描边宽度 1.5px。为防止箭头透过半透明填充色显现，使用**双矩形遮罩技术**：
+1. 绘制不透明背景矩形（`#0f172a`）
+2. 在其上方绘制半透明样式矩形
+
+### 连接规则
+- **Z 轴顺序：** 在 SVG 早期绘制箭头（在网格之后），使其渲染在组件框的下方
+- **箭头头部：** 通过 SVG marker 定义
+- **安全流：** 使用 rose 色（`#fb7185`）虚线
+- **边界：**
+  - *安全组：* 虚线（`4,4`），rose 色
+  - *区域：* 大虚线（`8,4`），amber 色，`rx="12"`
+
+### 间距与布局规则
+- **标准高度：** 60px（服务）；80–120px（大型组件）
+- **垂直间距：** 组件之间最小 40px
+- **消息总线：** 必须放置在服务之间的间隙中，不得与其重叠
+- **图例位置：** **关键。** 必须放置在所有边界框的外部。计算所有边界的最低 Y 坐标，并将图例放置在其下方至少 20px 处。
+
+## 文档结构
+
+生成的 HTML 文件遵循四段式布局：
+1. **页眉：** 带有脉冲点指示器的标题和副标题
+2. **主 SVG：** 包含在圆角边框卡片中的图表
+3. **摘要卡片：** 图表下方的三张卡片网格，用于展示高层次详情
+4. **页脚：** 简洁的元数据信息
+
+### 信息卡片模式
+```html
+<div class="card">
+  <div class="card-header">
+    <div class="card-dot cyan"></div>
+    <h3>Title</h3>
+  </div>
+  <ul>
+    <li>• Item one</li>
+    <li>• Item two</li>
+  </ul>
+</div>
+```
+
+## 输出要求
+- **单文件：** 一个自包含的 `.html` 文件
+- **无外部依赖：** 所有 CSS 和 SVG 必须内联（Google Fonts 除外）
+- **无 JavaScript：** 所有动画（如脉冲点）使用纯 CSS 实现
+- **兼容性：** 必须在任何现代浏览器中正确渲染
+
+## 模板参考
+
+加载完整 HTML 模板以获取精确的结构、CSS 和 SVG 组件示例：
+
+```
+skill_view(name="architecture-diagram", file_path="templates/template.html")
+```
+
+模板包含每种组件类型（前端、后端、数据库、云、安全）、箭头样式（标准、虚线、曲线）、安全组、区域边界和图例的完整示例——生成图表时请以此作为结构参考。