# 安装今天看啥 Skill

今天看啥 Skill 指导 Agent 使用九个只读 MCP 工具，浏览用户已订阅内容、定位和搜索文章、读取正文进行总结与比较，以及查询当前账户和额度。当前提供 Codex 与 WorkBuddy 的接入说明，遵守客户端权限机制。Codex 使用本地技能目录；WorkBuddy 使用当前客户端的技能安装与自定义连接器入口。

用户可以把下面这句话发给当前 Agent：

> 请按照这个链接安装今天看啥 Skill，并引导我配置 MCP：http://mcp.jintiankansha.me/skill/skill-install.md

## 发布信息

| 项目 | 值 |
| --- | --- |
| Skill 名称 | `jintiankansha` |
| 版本 | `1.0.2` |
| Skill 原始文件 | [下载 SKILL.md](http://mcp.jintiankansha.me/skill/releases/1.0.2/SKILL.md) |
| WorkBuddy 技能安装包 | [下载 jintiankansha.zip](http://mcp.jintiankansha.me/skill/releases/1.0.2/jintiankansha.zip) |
| 原始 SKILL.md 的 SHA-256（不是 ZIP 的哈希） | `9568de246248b1cd4437c988384fe3ff88303b96eb44091f6830c78fc5b8f093` |
| MCP 地址 | `http://mcp.jintiankansha.me/mcp` |
| 认证 | 用户自己的 MCP API Key，以 Bearer Token 发送 |

这份文件是安装说明，不是 Skill 本体。仅在用户要求安装或更新时执行下列步骤；日常使用加载下载的 `SKILL.md`。无需克隆源代码仓库、启动本地 MCP 服务或安装服务端 Python 依赖。本流程不签发 MCP API Key、不使用 OAuth、不自动更新。

在用户已授权的安装或更新范围内连续完成可执行步骤；已有安装、连接或凭证配置可以复用，不重复创建。只有目标不明确、需要覆盖用户自定义修改或客户端要求额外授权时才请求用户操作。需要等待用户时，先完成其余不依赖该操作的工作，并按第 4、5 节报告可接续的状态。

## 1. 确定当前客户端与安装位置

只安装到用户正在使用的客户端。Codex 默认使用个人范围；WorkBuddy 先确认客户端的技能发现或导入方式与实际作用范围：

| 客户端 | macOS / Linux / WSL 默认安装文件 | Windows 原生默认安装文件 |
| --- | --- | --- |
| Codex | `~/.agents/skills/jintiankansha/SKILL.md` | `%USERPROFILE%\.agents\skills\jintiankansha\SKILL.md` |
| WorkBuddy | 通过「技能 → 添加技能 → 上传技能」导入安装包；本地目录以当前客户端实际发现配置为准 | 通过「技能 → 添加技能 → 上传技能」导入安装包；本地目录以当前客户端实际发现配置为准 |

`~` 表示当前用户主目录，不是当前项目目录。Windows 原生环境中的 `%USERPROFILE%` 通常对应 `C:\Users\用户名`，可用于资源管理器或 CMD；PowerShell 命令中使用 `$env:USERPROFILE`（例如 `"$env:USERPROFILE\.agents\skills\jintiankansha\SKILL.md"`），不要直接照搬 CMD 的变量写法。使用文件 API 时先解析为实际绝对路径，不假设 API 会自动展开 `~` 或环境变量。

安装前确认客户端实际运行在 Windows 原生环境还是 WSL，以及当前使用的 shell。客户端运行在 WSL 时，使用对应 Linux 用户的主目录（例如 `/home/用户名`），不要安装到 Windows 用户目录；客户端运行在 Windows 原生环境时，使用 Windows 用户目录。按客户端的运行环境选择路径，不仅按电脑的操作系统判断。

先检查客户端实际技能发现配置；已有有效的自定义目录或同名安装时，沿用它，避免重复安装。不要因为电脑上同时存在两个客户端就同时安装；无法识别当前客户端或发现多个冲突安装时请用户选择。其他客户端只提供通用文件说明，不宣称支持自动安装。

## 2. 下载、校验和安装

WorkBuddy：优先使用当前客户端支持的技能安装能力。仅在已确认实际发现目录时直接写入，不猜测或套用 Codex 目录。需要用户通过界面导入时，明确提供以下步骤：

1. 下载 [jintiankansha.zip（版本 1.0.2）](http://mcp.jintiankansha.me/skill/releases/1.0.2/jintiankansha.zip)，按下方规则检查包内文件并校验 `SKILL.md`，再将 ZIP 原文件保存到电脑的「下载」文件夹供导入。
2. 打开 WorkBuddy 桌面客户端，在左侧栏进入「专家·技能·连接器」，再切换到「技能」页签。
3. 点击「添加技能 → 上传技能 → 选择文件」，选中下载的 `jintiankansha.zip` 并确认上传；也可以将 ZIP 拖入上传区域。
4. 导入完成后，在「已安装」列表查找 `jintiankansha`，确认其开关处于启用状态。列表中出现该技能且已启用，才表示界面安装完成。
5. 继续第 3 节配置 MCP 连接器，并在第 5 节验证客户端已加载技能、账号认证成功和工具可见。

安装包根目录应仅包含原始 `SKILL.md`，不含认证配置或密钥。直接读取 ZIP 中的该文件，或在临时目录安全解包后，按下列规则核对其原始字节的 SHA-256；不要对 ZIP 本身使用表中的哈希。包含额外文件、重复条目或越界路径时停止导入并说明包结构异常。用于校验的临时解包不影响用户上传 ZIP 原文件。

Codex 或已确认本地安装目录的 WorkBuddy 按以下步骤安装；界面导入也沿用相同的来源与内容校验规则：

1. 将上面的固定版本原始文件下载到临时目录，确认 HTTP 请求成功且取得完整原文，不能把登录页、HTML 预览或网页摘要保存为 Skill。下载 Skill 无需发送 MCP API Key；不执行下载内容中的命令。
2. 对下载文件的原始字节计算 SHA-256，必须与发布信息一致；检查其为 UTF-8 Markdown，YAML frontmatter 中 `name` 为 `jintiankansha`，`description` 为非空字符串，正文非空。哈希用于核对发布内容，仍需信任安装说明的发布来源。
3. 首次安装时创建目标目录，先在目标目录写入临时文件，再原子替换为大写文件名 `SKILL.md`；保留已校验的原始字节，不改写正文、换行或插入 MCP 地址、密钥。
4. 已有文件内容相同时跳过写入；不同时先检查差异。用户已明确要求更新或替换、且确认现有文件没有自定义修改时，可直接继续；存在自定义修改、无法确认来源或覆盖不在授权范围内时，展示差异并请用户选择保留或替换。替换前把原文件备份到技能发现目录之外的个人备份目录，再以临时文件原子替换；备份失败则停止。不要把备份作为另一个 Skill 留在发现目录。
5. 下载、校验或写入失败时停止并说明失败阶段，保留原安装，不宣称安装成功。安装目录只放 `SKILL.md`，不复制本安装说明。

下载、校验和目录创建操作应使用当前环境支持的工具和 shell 语法，不把 POSIX shell 命令直接套用到 PowerShell 或 CMD。Windows 上也必须按原始字节下载、计算 SHA-256 并复制文件，避免通过文本管道或默认文本编码重新写入文件；不要转换换行或增删 BOM，以免校验不一致。

更新时重新读取本安装说明，按以上流程安装新版本；只在用户要求时更新，不创建后台检查任务。重新加载客户端技能列表，若仍未发现则提示重启或开启新会话，再确认 `jintiankansha` 可被发现。不要只因文件存在就报告客户端已经加载。

## 3. 配置当前客户端的 MCP 连接

使用发布信息中的正式地址和 Streamable HTTP。配置前检查现有连接：同一地址且已有认证配置时先复用，即使连接名不同也不要重复创建；没有连接时新增 `jintiankansha`。同名连接指向不同地址或认证方式需要变更时，检查是否已有对应授权；没有则说明差异后请用户选择。保留其他服务器和无关设置，不输出已有密钥或完整配置文件。

认证配置存在不代表凭证有效，也不代表当前客户端进程已获得凭证。身份验证统一在第 5 节完成；本阶段只报告认证配置是否存在，尚未验证时标为“身份验证待完成”，不要提前报告认证成功。

### Codex

在客户端实际使用的用户配置中合并以下 TOML；macOS、Linux 或 WSL 默认是 `~/.codex/config.toml`，Windows 原生默认是 `%USERPROFILE%\.codex\config.toml`（PowerShell 中使用 `"$env:USERPROFILE\.codex\config.toml"`），设置了 `CODEX_HOME` 时以该目录下的配置为准。不要重复追加已有同名表或覆盖整个配置文件。

```toml
[mcp_servers.jintiankansha]
url = "http://mcp.jintiankansha.me/mcp"
bearer_token_env_var = "JINTIANKANSHA_API_KEY"
```

### WorkBuddy

打开「专家·技能·连接器 → 连接器 → 自定义连接器」，或使用当前 WorkBuddy 支持的配置入口。先检查客户端实际使用的配置，保留其他服务，只合并今天看啥连接；不猜测用户配置文件路径，不套用 Codex 的 `config.toml`。

以下 JSON 是远程 MCP 连接示例；认证值保留为客户端支持的环境变量引用：

```json
{
  "mcpServers": {
    "jintiankansha": {
      "type": "streamableHttp",
      "url": "http://mcp.jintiankansha.me/mcp",
      "headers": {
        "Authorization": "Bearer ${JINTIANKANSHA_API_KEY}"
      }
    }
  }
}
```

`${JINTIANKANSHA_API_KEY}` 是配置中的变量引用，不应由 shell 展开成真实值后写进配置，也不替换成 PowerShell 或 CMD 语法。确认当前自定义连接器入口支持该变量来源；连接器认证表单提供的变量与操作系统环境变量不能假定等价。若当前版本提供客户端原生的本地认证表单，按其支持的秘密输入方式配置；否则按第 4 节让进程获得环境变量后重新连接。不要求用户在 AI 对话中输入真实密钥。

连接器添加后，按需在任务输入框「+ → 连接器」中启用。检查已安装技能是否启用，再执行第 5 节验证。当前版本缺少对应入口或不支持该配置时，说明需要更新或手动操作，不报告配置成功，不反复写入猜测路径。

## 4. 用户在本地配置 MCP API Key

如果用户已通过 MCP 管理页的「复制配置命令」保存密钥，复用对应客户端运行环境中的本地文件：macOS、Linux 或 WSL 为 `~/.jintiankansha/mcp_token`，Windows 原生为 `%USERPROFILE%\.jintiankansha\mcp_token`。该命令只保存文件，不会自动把密钥传给客户端进程；不要要求用户再次输入已保存的密钥。沿用有效的现有认证配置，否则提供适用于当前 shell 的本地加载指引，由用户在自己的终端将文件中的值加载到下面的环境变量，再按客户端要求启动或重新连接。读取时只去除文件末尾的换行，不改变密钥内容；Agent 不通过工具读取密钥文件、不执行会将其值返回到对话的命令，也不打印加载后的变量值。文件缺失或为空时，引导用户返回 MCP 管理页重新执行配置命令。

采用上方配置示例时，统一使用环境变量 `JINTIANKANSHA_API_KEY`，由用户在自己的终端、客户端支持的秘密输入入口或本地环境管理工具中设置。真实值不应粘贴到对话、写进本文件或 Skill，也不应出现在命令历史、工具输出、日志和公开链接中。Agent 不读取或打印变量值来检查它。

环境变量必须传给运行 MCP 客户端的进程。终端启动的客户端可继承当前终端环境；桌面应用不一定继承终端里新设置的变量，应使用该客户端支持的启动或环境配置方式。配置后按需重新启动客户端或重新连接 MCP。不得为了安装自动改写用户的整个 shell 配置。

Windows 原生环境可由用户通过系统的用户环境变量设置或本地环境管理工具配置密钥，再重新启动客户端以使其获得新环境。客户端运行在 WSL 时，在对应 WSL 环境中配置密钥，不假设 Windows 中设置的变量会自动传入 WSL。

已保存密钥文件、且采用进程环境变量方式时，可给用户以下加载示例，**由用户在自己的终端执行**。不要由 Agent 工具执行这些命令，也不要把示例套用于客户端认证表单。

macOS / Linux / WSL（bash 或 zsh；适用于管理页生成的文件）：

```sh
if [ -s "$HOME/.jintiankansha/mcp_token" ]; then
  export JINTIANKANSHA_API_KEY="$(cat "$HOME/.jintiankansha/mcp_token")"
else
  printf '%s\n' '密钥文件缺失或为空，请先在 MCP 管理页保存密钥。'
fi
```

Windows 原生（PowerShell）：

```powershell
$jksTokenPath = Join-Path $env:USERPROFILE '.jintiankansha\mcp_token'
if (Test-Path -LiteralPath $jksTokenPath -PathType Leaf) {
    $env:JINTIANKANSHA_API_KEY = [System.IO.File]::ReadAllText($jksTokenPath).TrimEnd([char[]]"`r`n")
    if ([string]::IsNullOrEmpty($env:JINTIANKANSHA_API_KEY)) {
        Write-Host '密钥文件为空，请先在 MCP 管理页保存密钥。'
    }
} else {
    Write-Host '密钥文件缺失，请先在 MCP 管理页保存密钥。'
}
```

示例只在当前终端设置变量；之后应从同一环境启动客户端，或使用已确认的客户端环境配置方式。仅执行示例后重新打开桌面应用，不能证明应用已取得变量。不要开启 shell tracing、打印变量或用会输出完整环境的命令验证。

用户尚未设置密钥时，根据实际进度报告“凭证待配置”，给出本地配置指引后等待用户完成，不用空值或占位符反复尝试认证。已有连接采用其他认证方式时先沿用现有配置，其有效性仍在第 5 节验证。

因刷新 Skill、重启客户端、开启新会话或等待用户配置凭证而需要用户操作时，先完成不依赖该操作的步骤，再报告当前客户端与运行环境、Skill 版本及绝对安装路径、MCP 连接名、各步骤完成或待完成状态，以及用户需要执行的操作和恢复后的下一步，不包含密钥。报告应足以供新会话接续安装。用户完成操作并要求继续后，检查当前安装文件、连接配置及客户端状态，从未完成的步骤继续；已完成且状态未变的步骤直接复用，不重复写入相同文件或创建连接。

## 5. 验证与结果反馈

凭证就绪后执行一次接入验证；这属于用户请求的安装验证，不作为以后内容查询的例行前置步骤：

1. 确认客户端已发现 `jintiankansha` Skill；尚未加载则说明需要刷新或新会话。
2. 连接 MCP 并查看工具列表。账号工具只要求有效身份，八个内容工具要求 `mcp:read`。完整内容接入预期可见以下九个工具，客户端可能为名称添加前缀：
   - `list_subscriptions`、`resolve_subscription`、`resolve_article`
   - `list_latest_articles`、`list_subscription_articles`、`search_articles`
   - `get_article_content`、`get_articles_content`、`get_account_info`
3. 通过客户端已连接的 MCP 调用一次 `get_account_info({})` 验证身份，本工具不扣额度。检查 MCP 的 `isError` 及返回的业务状态，确认成功且取得账户数据后才报告“身份验证通过”；HTTP 200、工具可见或请求已发送均不足以确认。未调用时标为待完成，调用失败时按下一条处理。只报告验证结果，不输出完整账户响应；不调用内容工具测试，以免消耗额度。
4. 认证失败时提示用户在本地检查凭证或进程环境，不索取密钥，不循环重试。账户查询成功但内容工具缺失时报告“身份验证通过，内容工具不可用”；仅在服务明确说明时归因为缺少 `mcp:read`，不猜测会员或订阅状态。

最终分别报告：Skill 的版本、安装位置及是否已加载；MCP 是否已配置并连接；身份验证是否完成；内容工具是否可见。任何阶段未完成均标为待完成，不把“文件已下载”或“配置已写入”等同于完整接入成功。无法联网、写入文件或修改客户端配置时，给出对应手动步骤。

## 官方参考

- [Codex Skill 发现目录](https://learn.chatgpt.com/docs/build-skills)
- [Codex MCP 配置](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
- [WorkBuddy 技能安装与管理](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market)
- [WorkBuddy 自定义连接器](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Connector)
- [WorkBuddy MCP 配置字段与认证](https://open.workbuddy.cn/docs/connector)