npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (999) hide show

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

@@ -1,305 +0,0 @@
----
-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 DELETED Viewed

@@ -1,132 +0,0 @@
----
-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 DELETED Viewed

@@ -1,265 +0,0 @@
----
-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）——无需安装任何软件 |