better-dsh 0.2.4 → 0.2.5-a

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

@@ -0,0 +1,305 @@
+---
+title: "Himalaya — Himalaya CLI: IMAP/SMTP email from terminal"
+sidebar_label: "Himalaya"
+description: "Himalaya CLI：从终端收发 IMAP/SMTP 邮件"
+---
+
+{/* 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. */}
+
+# Himalaya
+
+Himalaya CLI：从终端收发 IMAP/SMTP 邮件。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/email/himalaya` |
+| 版本 | `1.1.0` |
+| 作者 | community |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Email`, `IMAP`, `SMTP`, `CLI`, `Communication` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Himalaya 邮件 CLI
+
+Himalaya 是一个 CLI 邮件客户端，支持通过 IMAP、SMTP、Notmuch 或 Sendmail 后端从终端管理邮件。
+
+## 参考资料
+
+- `references/configuration.md`（配置文件设置 + IMAP/SMTP 认证）
+- `references/message-composition.md`（用于撰写邮件的 MML 语法）
+
+## 前置条件
+
+1. 已安装 Himalaya CLI（运行 `himalaya --version` 验证）
+2. 配置文件位于 `~/.config/himalaya/config.toml`
+3. 已配置 IMAP/SMTP 凭据（密码安全存储）
+
+### 安装
+
+```bash
+# 预编译二进制（Linux/macOS — 推荐）
+curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh
+
+# macOS 通过 Homebrew
+brew install himalaya
+
+# 或通过 cargo（任何支持 Rust 的平台）
+cargo install himalaya --locked
+```
+
+## 配置设置
+
+运行交互式向导以设置账户：
+
+```bash
+himalaya account configure
+```
+
+或手动创建 `~/.config/himalaya/config.toml`：
+
+```toml
+[accounts.personal]
+email = "you@example.com"
+display-name = "Your Name"
+default = true
+
+backend.type = "imap"
+backend.host = "imap.example.com"
+backend.port = 993
+backend.encryption.type = "tls"
+backend.login = "you@example.com"
+backend.auth.type = "password"
+backend.auth.cmd = "pass show email/imap"  # or use keyring
+
+message.send.backend.type = "smtp"
+message.send.backend.host = "smtp.example.com"
+message.send.backend.port = 587
+message.send.backend.encryption.type = "start-tls"
+message.send.backend.login = "you@example.com"
+message.send.backend.auth.type = "password"
+message.send.backend.auth.cmd = "pass show email/smtp"
+
+# Folder aliases (himalaya v1.2.0+ syntax). Required whenever the
+# server's folder names don't match himalaya's canonical names
+# (inbox/sent/drafts/trash). Gmail is the common case — see
+# `references/configuration.md` for the `[Gmail]/Sent Mail` mapping.
+folder.aliases.inbox = "INBOX"
+folder.aliases.sent = "Sent"
+folder.aliases.drafts = "Drafts"
+folder.aliases.trash = "Trash"
+```
+
+> **关于别名语法的注意事项。** v1.2.0 之前的文档使用 `[accounts.NAME.folder.alias]` 子节（单数 `alias`）。v1.2.0 会静默忽略该形式——TOML 解析正常，但别名解析器从不读取它，因此每次查找都会回退到规范名称。在 Gmail 上，这意味着 SMTP 投递成功*之后*保存到已发送文件夹会失败，且 `himalaya message send` 以非零状态退出。任何在该退出码上重试的调用方（agent、脚本、用户）都会重新执行整个发送流程——包括 SMTP——从而向收件人产生重复邮件。请始终使用 `folder.aliases.X`（复数、点分键，直接位于 `[accounts.NAME]` 下）。
+
+## Hermes 集成说明
+
+- **读取、列出、搜索、移动、删除**均可直接通过终端工具完成
+- **撰写/回复/转发**——推荐使用管道输入（`cat << EOF | himalaya template send`）以确保可靠性。交互式 `$EDITOR` 模式可配合 `pty=true` + 后台 + 进程工具使用，但需要了解编辑器及其命令
+- 使用 `--output json` 获取结构化输出，便于程序化解析
+- `himalaya account configure` 向导需要交互式输入——请使用 PTY 模式：`terminal(command="himalaya account configure", pty=true)`
+
+## 常用操作
+
+### 列出文件夹
+
+```bash
+himalaya folder list
+```
+
+### 列出邮件
+
+列出 INBOX 中的邮件（默认）：
+
+```bash
+himalaya envelope list
+```
+
+列出指定文件夹中的邮件：
+
+```bash
+himalaya envelope list --folder "Sent"
+```
+
+分页列出：
+
+```bash
+himalaya envelope list --page 1 --page-size 20
+```
+
+### 搜索邮件
+
+```bash
+himalaya envelope list from john@example.com subject meeting
+```
+
+### 阅读邮件
+
+按 ID 阅读邮件（显示纯文本）：
+
+```bash
+himalaya message read 42
+```
+
+导出原始 MIME：
+
+```bash
+himalaya message export 42 --full
+```
+
+### 回复邮件
+
+在 Hermes 中非交互式回复，请读取原始邮件、撰写回复并通过管道发送：
+
+```bash
+# 获取回复模板，编辑后发送
+himalaya template reply 42 | sed 's/^$/\nYour reply text here\n/' | himalaya template send
+```
+
+或手动构建回复：
+
+```bash
+cat << 'EOF' | himalaya template send
+From: you@example.com
+To: sender@example.com
+Subject: Re: Original Subject
+In-Reply-To: <original-message-id>
+
+Your reply here.
+EOF
+```
+
+全部回复（交互式——需要 $EDITOR，建议改用上述模板方式）：
+
+```bash
+himalaya message reply 42 --all
+```
+
+### 转发邮件
+
+```bash
+# 获取转发模板并通过管道修改后发送
+himalaya template forward 42 | sed 's/^To:.*/To: newrecipient@example.com/' | himalaya template send
+```
+
+### 撰写新邮件
+
+**非交互式（在 Hermes 中使用此方式）**——通过 stdin 管道传入邮件：
+
+```bash
+cat << 'EOF' | himalaya template send
+From: you@example.com
+To: recipient@example.com
+Subject: Test Message
+
+Hello from Himalaya!
+EOF
+```
+
+或使用 headers 标志：
+
+```bash
+himalaya message write -H "To:recipient@example.com" -H "Subject:Test" "Message body here"
+```
+
+注意：不带管道输入的 `himalaya message write` 会打开 `$EDITOR`。配合 `pty=true` + 后台模式可以使用，但管道方式更简单可靠。
+
+### 移动/复制邮件
+
+移动到文件夹：
+
+```bash
+himalaya message move "Archive" 42
+```
+
+复制到文件夹：
+
+```bash
+himalaya message copy "Important" 42
+```
+
+### 删除邮件
+
+```bash
+himalaya message delete 42
+```
+
+### 管理标志
+
+添加标志：
+
+```bash
+himalaya flag add 42 --flag seen
+```
+
+移除标志：
+
+```bash
+himalaya flag remove 42 --flag seen
+```
+
+## 多账户
+
+列出账户：
+
+```bash
+himalaya account list
+```
+
+使用指定账户：
+
+```bash
+himalaya --account work envelope list
+```
+
+## 附件
+
+保存邮件附件：
+
+```bash
+himalaya attachment download 42
+```
+
+保存到指定目录：
+
+```bash
+himalaya attachment download 42 --downloads-dir ~/Downloads
+```
+
+## 输出格式
+
+大多数命令支持 `--output` 以获取结构化输出：
+
+```bash
+himalaya envelope list --output json
+himalaya envelope list --output plain
+```
+
+## 调试
+
+启用调试日志：
+
+```bash
+RUST_LOG=debug himalaya envelope list
+```
+
+完整追踪与回溯：
+
+```bash
+RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list
+```
+
+## 提示
+
+- 使用 `himalaya --help` 或 `himalaya <command> --help` 查看详细用法。
+- 消息 ID 相对于当前文件夹；切换文件夹后请重新列出。
+- 如需撰写带附件的富文本邮件，请使用 MML 语法（参见 `references/message-composition.md`）。
+- 使用 `pass`、系统密钥环或输出密码的命令安全存储密码。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/github/github-codebase-inspection.md

@@ -0,0 +1,132 @@
+---
+title: "代码库检查 — 使用 pygount 检查代码库：代码行数、语言、占比"
+sidebar_label: "代码库检查"
+description: "使用 pygount 检查代码库：代码行数、语言、占比"
+---
+
+{/* 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. */}
+
+# 代码库检查
+
+使用 pygount 检查代码库：代码行数、语言、占比。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/github/codebase-inspection` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `LOC`, `Code Analysis`, `pygount`, `Codebase`, `Metrics`, `Repository` |
+| 相关 skill | [`github-repo-management`](/user-guide/skills/bundled/github/github-github-repo-management) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# 使用 pygount 进行代码库检查
+
+使用 `pygount` 分析仓库的代码行数、语言分布、文件数量及代码与注释的比例。
+
+## 使用场景
+
+- 用户请求统计 LOC（lines of code，代码行数）
+- 用户需要仓库的语言分布情况
+- 用户询问代码库的规模或组成
+- 用户需要代码与注释的比例
+- 一般性的"这个仓库有多大"问题
+
+## 前置条件
+
+```bash
+pip install --break-system-packages pygount 2>/dev/null || pip install pygount
+```
+
+## 1. 基本摘要（最常用）
+
+获取包含文件数量、代码行数和注释行数的完整语言分布：
+
+```bash
+cd /path/to/repo
+pygount --format=summary \
+  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info" \
+  .
+```
+
+**重要：** 始终使用 `--folders-to-skip` 排除依赖/构建目录，否则 pygount 会遍历这些目录，导致运行时间极长甚至卡死。
+
+## 2. 常用目录排除项
+
+根据项目类型进行调整：
+
+```bash
+# Python 项目
+--folders-to-skip=".git,venv,.venv,__pycache__,.cache,dist,build,.tox,.eggs,.mypy_cache"
+
+# JavaScript/TypeScript 项目
+--folders-to-skip=".git,node_modules,dist,build,.next,.cache,.turbo,coverage"
+
+# 通用兜底
+--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,vendor,third_party"
+```
+
+## 3. 按特定语言过滤
+
+```bash
+# 仅统计 Python 文件
+pygount --suffix=py --format=summary .
+
+# 仅统计 Python 和 YAML
+pygount --suffix=py,yaml,yml --format=summary .
+```
+
+## 4. 逐文件详细输出
+
+```bash
+# 默认格式显示每个文件的详细信息
+pygount --folders-to-skip=".git,node_modules,venv" .
+
+# 按代码行数排序（通过管道传给 sort）
+pygount --folders-to-skip=".git,node_modules,venv" . | sort -t$'\t' -k1 -nr | head -20
+```
+
+## 5. 输出格式
+
+```bash
+# 摘要表格（默认推荐）
+pygount --format=summary .
+
+# JSON 输出，适合程序化处理
+pygount --format=json .
+
+# 管道友好：语言、文件数、代码行、文档行、空行、字符串行
+pygount --format=summary . 2>/dev/null
+```
+
+## 6. 结果解读
+
+摘要表格各列说明：
+- **Language** — 检测到的编程语言
+- **Files** — 该语言的文件数量
+- **Code** — 实际代码行数（可执行/声明性语句）
+- **Comment** — 注释或文档行数
+- **%** — 占总量的百分比
+
+特殊伪语言：
+- `__empty__` — 空文件
+- `__binary__` — 二进制文件（图片、编译产物等）
+- `__generated__` — 自动生成的文件（启发式检测）
+- `__duplicate__` — 内容完全相同的文件
+- `__unknown__` — 无法识别的文件类型
+
+## 注意事项
+
+1. **始终排除 .git、node_modules、venv** — 不使用 `--folders-to-skip` 时，pygount 会遍历所有内容，在大型依赖树上可能耗时数分钟甚至卡死。
+2. **Markdown 显示 0 代码行** — pygount 将所有 Markdown 内容归类为注释而非代码，这是预期行为。
+3. **JSON 文件代码行数偏低** — pygount 统计 JSON 行数时可能较为保守，如需精确统计 JSON 行数，请直接使用 `wc -l`。
+4. **大型 monorepo** — 对于非常大的仓库，建议使用 `--suffix` 指定目标语言，而非扫描全部内容。

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

@@ -0,0 +1,265 @@
+---
+title: "Github Auth — GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login"
+sidebar_label: "Github Auth"
+description: "GitHub auth 设置：HTTPS 令牌、SSH 密钥、gh CLI 登录"
+---
+
+{/* 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. */}
+
+# Github Auth
+
+GitHub auth 设置：HTTPS 令牌、SSH 密钥、gh CLI 登录。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/github/github-auth` |
+| 版本 | `1.1.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `GitHub`, `Authentication`, `Git`, `gh-cli`, `SSH`, `Setup` |
+| 相关 skill | [`github-pr-workflow`](/user-guide/skills/bundled/github/github-github-pr-workflow), [`github-code-review`](/user-guide/skills/bundled/github/github-github-code-review), [`github-issues`](/user-guide/skills/bundled/github/github-github-issues), [`github-repo-management`](/user-guide/skills/bundled/github/github-github-repo-management) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# GitHub 认证设置
+
+此 skill 用于配置认证，使 agent 能够操作 GitHub 仓库、PR、issue 和 CI。涵盖两条路径：
+
+- **`git`（始终可用）** — 使用 HTTPS 个人访问令牌（personal access token）或 SSH 密钥
+- **`gh` CLI（如已安装）** — 更丰富的 GitHub API 访问，认证流程更简单
+
+## 检测流程
+
+当用户要求你操作 GitHub 时，首先执行以下检查：
+
+```bash
+# Check what's available
+git --version
+gh --version 2>/dev/null || echo "gh not installed"
+
+# Check if already authenticated
+gh auth status 2>/dev/null || echo "gh not authenticated"
+git config --global credential.helper 2>/dev/null || echo "no git credential helper"
+```
+
+**决策树：**
+1. 若 `gh auth status` 显示已认证 → 直接使用 `gh` 处理所有操作
+2. 若 `gh` 已安装但未认证 → 使用下方"gh auth"方法
+3. 若 `gh` 未安装 → 使用下方"仅 git"方法（无需 sudo）
+
+---
+
+## 方法一：仅 Git 认证（无 gh，无 sudo）
+
+适用于任何已安装 `git` 的机器，无需 root 权限。
+
+### 选项 A：HTTPS 配合个人访问令牌（推荐）
+
+最通用的方法——适用于所有环境，无需 SSH 配置。
+
+**第一步：创建个人访问令牌**
+
+告知用户访问：**https://github.com/settings/tokens**
+
+- 点击"Generate new token (classic)"
+- 填写名称，如"hermes-agent"
+- 选择权限范围（scope）：
+  - `repo`（完整仓库访问——读、写、推送、PR）
+  - `workflow`（触发和管理 GitHub Actions）
+  - `read:org`（如需操作组织仓库）
+- 设置有效期（90 天是合理的默认值）
+- 复制令牌——此后不会再次显示
+
+**第二步：配置 git 存储令牌**
+
+```bash
+# Set up the credential helper to cache credentials
+# "store" saves to ~/.git-credentials in plaintext (simple, persistent)
+git config --global credential.helper store
+
+# Now do a test operation that triggers auth — git will prompt for credentials
+# Username: <their-github-username>
+# Password: <paste the personal access token, NOT their GitHub password>
+git ls-remote https://github.com/<their-username>/<any-repo>.git
+```
+
+首次输入凭据后，将被保存并在后续所有操作中复用。
+
+**替代方案：cache helper（凭据在内存中过期）**
+
+```bash
+# Cache in memory for 8 hours (28800 seconds) instead of saving to disk
+git config --global credential.helper 'cache --timeout=28800'
+```
+
+**替代方案：直接将令牌写入远程 URL（按仓库设置）**
+
+```bash
+# Embed token in the remote URL (avoids credential prompts entirely)
+git remote set-url origin https://<username>:<token>@github.com/<owner>/<repo>.git
+```
+
+**第三步：配置 git 身份信息**
+
+```bash
+# Required for commits — set name and email
+git config --global user.name "Their Name"
+git config --global user.email "their-email@example.com"
+```
+
+**第四步：验证**
+
+```bash
+# Test push access (this should work without any prompts now)
+git ls-remote https://github.com/<their-username>/<any-repo>.git
+
+# Verify identity
+git config --global user.name
+git config --global user.email
+```
+
+### 选项 B：SSH 密钥认证
+
+适合偏好 SSH 或已有密钥的用户。
+
+**第一步：检查现有 SSH 密钥**
+
+```bash
+ls -la ~/.ssh/id_*.pub 2>/dev/null || echo "No SSH keys found"
+```
+
+**第二步：如需则生成密钥**
+
+```bash
+# Generate an ed25519 key (modern, secure, fast)
+ssh-keygen -t ed25519 -C "their-email@example.com" -f ~/.ssh/id_ed25519 -N ""
+
+# Display the public key for them to add to GitHub
+cat ~/.ssh/id_ed25519.pub
+```
+
+告知用户在以下地址添加公钥：**https://github.com/settings/keys**
+- 点击"New SSH key"
+- 粘贴公钥内容
+- 填写标题，如"hermes-agent-&lt;machine-name>"
+
+**第三步：测试连接**
+
+```bash
+ssh -T git@github.com
+# Expected: "Hi <username>! You've successfully authenticated..."
+```
+
+**第四步：配置 git 使用 SSH 访问 GitHub**
+
+```bash
+# Rewrite HTTPS GitHub URLs to SSH automatically
+git config --global url."git@github.com:".insteadOf "https://github.com/"
+```
+
+**第五步：配置 git 身份信息**
+
+```bash
+git config --global user.name "Their Name"
+git config --global user.email "their-email@example.com"
+```
+
+---
+
+## 方法二：gh CLI 认证
+
+若已安装 `gh`，一步即可完成 API 访问和 git 凭据配置。
+
+### 浏览器交互登录（桌面环境）
+
+```bash
+gh auth login
+# Select: GitHub.com
+# Select: HTTPS
+# Authenticate via browser
+```
+
+### 基于令牌登录（无头环境 / SSH 服务器）
+
+```bash
+echo "<THEIR_TOKEN>" | gh auth login --with-token
+
+# Set up git credentials through gh
+gh auth setup-git
+```
+
+### 验证
+
+```bash
+gh auth status
+```
+
+---
+
+## 不使用 gh 调用 GitHub API
+
+当 `gh` 不可用时，仍可使用 `curl` 配合个人访问令牌访问完整的 GitHub API。其他 GitHub skill 的降级方案均采用此方式。
+
+### 为 API 调用设置令牌
+
+```bash
+# Option 1: Export as env var (preferred — keeps it out of commands)
+export GITHUB_TOKEN="<token>"
+
+# Then use in curl calls:
+curl -s -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/user
+```
+
+### 从 Git 凭据中提取令牌
+
+若已通过 `credential.helper store` 配置 git 凭据，可提取令牌：
+
+```bash
+# Read from git credential store
+uv run python3 "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/git-credential-token.py"
+```
+
+### 辅助函数：检测认证方式
+
+在任何 GitHub 工作流开始时使用此模式：
+
+```bash
+# Try gh first, fall back to git + curl
+if command -v gh &>/dev/null && gh auth status &>/dev/null; then
+  echo "AUTH_METHOD=gh"
+elif [ -n "$GITHUB_TOKEN" ]; then
+  echo "AUTH_METHOD=curl"
+elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
+  export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+  echo "AUTH_METHOD=curl"
+elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
+  export GITHUB_TOKEN=$(uv run python3 "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/git-credential-token.py")
+  echo "AUTH_METHOD=curl"
+else
+  echo "AUTH_METHOD=none"
+  echo "Need to set up authentication first"
+fi
+```
+
+---
+
+## 故障排查
+
+| 问题 | 解决方案 |
+|---------|----------|
+| `git push` 要求输入密码 | GitHub 已禁用密码认证。请使用个人访问令牌作为密码，或切换至 SSH |
+| `remote: Permission to X denied` | 令牌可能缺少 `repo` scope——请重新生成并选择正确的 scope |
+| `fatal: Authentication failed` | 缓存的凭据可能已过期——运行 `git credential reject` 后重新认证 |
+| `ssh: connect to host github.com port 22: Connection refused` | 尝试通过 HTTPS 端口使用 SSH：在 `~/.ssh/config` 中为 `Host github.com` 添加 `Port 443` 和 `Hostname ssh.github.com` |
+| 凭据不持久 | 检查 `git config --global credential.helper`——必须为 `store` 或 `cache` |
+| 多个 GitHub 账号 | 在 `~/.ssh/config` 中为不同主机别名配置不同 SSH 密钥，或使用按仓库设置的凭据 URL |
+| `gh: command not found` 且无 sudo | 使用上方方法一（仅 git）——无需安装任何软件 |