k-skill-setup

k-skill Setup

目的

在完成 k-skill 的全量安装后，执行通用的后续配置工作：

• 获取凭证（Credential）（存储于 Agent 密钥库或默认的 secrets.env 中）
• 检查运行时环境变量
• 可选：配置定期自动检查更新
• 可选：检查 GitHub Star 状态并在用户同意后自动点赞

本 Skill 的基本原则：

• 缺少密钥（Secret）时，明确提示用户所需的具体变量名
• 严格遵循凭证查找优先级（Credential resolution order）获取密钥
• 缺少所需软件包时，优先尝试全局安装，而不是寻找替代实现
• cron、launchd、schtasks、gh 等涉及系统持久化或修改外部状态的操作，绝不擅自动手，必须先征得用户同意
• 仅在用户明确授权后，才执行 GitHub Star 操作

凭证查找优先级

所有需要凭证的 Skill 均遵循以下优先级：

1. 若环境变量中已存在：直接使用。
2. 若 Agent 使用了自带的密钥库（如 1Password CLI、Bitwarden CLI、macOS Keychain 等）：可从中提取并注入为环境变量。
3. ~/.config/k-skill/secrets.env（默认保底方案）—— 纯文本 dotenv 文件，权限设置为 0600。
4. 若以上均未找到：询问用户并将输入的凭证保存至第 2 或第 3 种途径。

注：保存在默认路径仅作为保底方案（Fallback），并非强制要求。

标准文件路径

• 密钥文件（默认保底）：~/.config/k-skill/secrets.env

安装

本 Skill 默认在完成 k-skill 全量安装后运行。

示例：

npx --yes skills add <owner/repo> --all -g

安装完成后，调用本 Skill 继续完成后续配置步骤。

配置步骤

1. 创建默认密钥文件（未配置密钥库时）

若 Agent 未使用自带的密钥库，则创建默认保底文件：

mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env <<'EOF'
KSKILL_SRT_ID=replace-me
KSKILL_SRT_PASSWORD=replace-me
KSKILL_KTX_ID=replace-me
KSKILL_KTX_PASSWORD=replace-me
KSKILL_FORESTTRIP_ID=replace-me
KSKILL_FORESTTRIP_PASSWORD=replace-me
LAW_OC=replace-me
KIPRIS_PLUS_API_KEY=replace-me
AIR_KOREA_OPEN_API_KEY=replace-me
KSKILL_PROXY_BASE_URL=
EOF
chmod 0600 ~/.config/k-skill/secrets.env

提示并询问用户以填入实际值。

对于首尔地铁到站信息、首尔实时拥挤度查询、首尔 따릉이（叮铃铃公共自行车）实时租赁点查询、韩国天气、PM2.5/细颗粒物、汉江水位、加油站油价、生活垃圾排放信息查询、学校食堂食谱查询、药品安全检查、食品安全检查等功能，若将 KSKILL_PROXY_BASE_URL 留空，则默认使用托管代理路径（k-skill-proxy.nomadamas.org）。只有在使用自定义自建代理（self-host proxy）时才需要填写 KSKILL_PROXY_BASE_URL。

韩国法律法规搜索功能会通过默认托管代理（k-skill-proxy.nomadamas.org）的 /v1/korean-law/... 端点转发，因此用户侧无需填写 LAW_OC。仅自建代理运维人员需要在服务器环境变量中配置 LAW_OC（可在 https://open.law.go.kr 免费申请）。

韩国房地产实际成交价查询功能会通过默认托管代理（k-skill-proxy.nomadamas.org）转发，因此用户侧无需填写 DATA_GO_KR_API_KEY。

韩国股票信息查询功能会通过默认托管代理（k-skill-proxy.nomadamas.org）转发，因此用户侧无需填写 KRX_API_KEY。仅自建代理运维人员需要使用服务器环境变量 KRX_API_KEY。

图书馆图书查询功能会通过默认托管代理（k-skill-proxy.nomadamas.org）转发，因此用户侧无需填写 DATA4LIBRARY_AUTH_KEY。仅自建代理运维人员需要使用服务器环境变量 DATA4LIBRARY_AUTH_KEY。

生活垃圾排放信息查询会调用 k-skill-proxy 的 /v1/household-waste/info 路由，且 serviceKey（DATA_GO_KR_API_KEY）由代理服务器统一注入与管理，因此用户侧无需配置 DATA_GO_KR_API_KEY。

学校食堂食谱查询会调用 k-skill-proxy 的 /v1/neis/school-search 与 /v1/neis/school-meal，且 KEDU_INFO_KEY 仅存放在代理服务器端，用户侧无需配置。

图书馆图书查询会调用 k-skill-proxy 的 /v1/data4library/* 路由，且 DATA4LIBRARY_AUTH_KEY 仅存放在代理服务器端，用户侧无需配置。

查找附近最便宜加油站功能会通过默认托管代理转发，因此用户侧无需配置 OPINET_API_KEY。

药品安全检查会调用 k-skill-proxy 的 /v1/mfds/drug-safety/lookup 路由，且 DATA_GO_KR_API_KEY 仅由代理服务器统一注入与管理，用户侧无需配置。

食品安全检查会调用 k-skill-proxy 的 /v1/mfds/food-safety/search 路由，且 DATA_GO_KR_API_KEY 及可选的 FOODSAFETYKOREA_API_KEY 仅由代理服务器统一注入与管理，用户侧无需配置。

创业振兴院 K-Startup 查询会调用 k-skill-proxy 的 /v1/kstartup/* 路由，且 ServiceKey（DATA_GO_KR_API_KEY）仅由代理服务器统一注入与管理，普通查询时用户侧无需配置密钥。仅在进行 --direct 直连调用时才需要填写 KSKILL_KSTARTUP_API_KEY。

韩国专利信息搜索在使用 KIPRIS Plus Open API 路径时需填写 KIPRIS_PLUS_API_KEY。辅助脚本（Helper）会读取该值并在实际请求中作为 ServiceKey 查询参数发送。直接复制公共数据门户中百分号编码（percent-encoded）的密钥填入即可。

缺失密钥时的响应模板

当身份验证类 Skill 缺失密钥时，按照凭证查找优先级进行获取。

所需变量示例：

• SRT：KSKILL_SRT_ID、KSKILL_SRT_PASSWORD
• KTX：KSKILL_KTX_ID、KSKILL_KTX_PASSWORD
• 自然休养林空房查询：KSKILL_FORESTTRIP_ID、KSKILL_FORESTTRIP_PASSWORD
• 韩国法律法规搜索：用户侧无需密钥（使用默认托管代理，仅运维人员需 LAW_OC）
• 韩国房地产实际成交价查询：用户侧无需密钥（使用默认托管代理）
• 韩国专利信息搜索：KIPRIS_PLUS_API_KEY
• 韩国股票信息查询：用户侧无需密钥（使用默认托管代理，仅运维人员需 KRX_API_KEY）
• 生活垃圾排放信息查询：用户侧无需密钥（serviceKey 由代理服务器注入，请求时必须带 pageNo=1 与 numOfRows=100）
• 学校食堂食谱查询：用户侧无需密钥（KEDU_INFO_KEY 仅在代理服务器端配置）
• 图书馆图书查询：用户侧无需密钥（DATA4LIBRARY_AUTH_KEY 仅在代理服务器端配置）
• 药品安全检查：用户侧无需密钥（DATA_GO_KR_API_KEY 仅在代理服务器端配置）
• 食品安全检查：用户侧无需密钥（DATA_GO_KR_API_KEY 与可选的 FOODSAFETYKOREA_API_KEY 仅在代理服务器端配置）
• 创业振兴院 K-Startup 查询：用户侧无需密钥（DATA_GO_KR_API_KEY 仅在代理服务器端配置；仅使用 --direct 直连时需 KSKILL_KSTARTUP_API_KEY）
• 查找附近最便宜加油站：用户侧无需密钥（使用默认托管代理）
• 首尔地铁：用户侧无需密钥（使用默认托管代理，仅运维人员需 SEOUL_OPEN_API_KEY）
• 首尔实时拥挤度：用户侧无需密钥（使用默认托管代理，仅运维人员需 SEOUL_OPEN_API_KEY）
• 韩国天气：用户侧无需密钥（使用默认托管代理，仅运维人员需 KMA_OPEN_API_KEY）
• 用户位置空气质量/细颗粒物查询：KSKILL_PROXY_BASE_URL 或 AIR_KOREA_OPEN_API_KEY

绝不能因为密钥为空就自动选择其他服务或非官方绕行路径。

2. 验证运行时环境

bash scripts/check-setup.sh

3. 提供定时更新检查选项

完成初始化配置后，首先询问用户是否希望配置定期自动检查更新。若用户不需要，直接跳过。

基本原则：

• 默认仅建议配置“更新检查”，而非自动安装更新
• 切勿在未经授权的情况下更改持久化系统配置（如 crontab、launchd、schtasks）
• 默认的检查命令为 npx --yes skills check
• 仅当用户明确要求“自动更新”时，才单独推荐基于 npx --yes skills update 的定时任务方案

macOS / Linux 示例：

mkdir -p ~/.config/k-skill/bin ~/.config/k-skill/logs
cat > ~/.config/k-skill/bin/check-skill-updates.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
mkdir -p "$HOME/.config/k-skill/logs"
{
  date '+[%Y-%m-%d %H:%M:%S]'
  npx --yes skills check
  printf '\n'
} >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
EOF
chmod +x ~/.config/k-skill/bin/check-skill-updates.sh
(crontab -l 2>/dev/null; echo "0 9 * * * $HOME/.config/k-skill/bin/check-skill-updates.sh") | crontab -

Windows 示例：

New-Item -ItemType Directory -Force "$HOME/.config/k-skill/bin" | Out-Null
New-Item -ItemType Directory -Force "$HOME/.config/k-skill/logs" | Out-Null
@'
npx --yes skills check >> "$HOME/.config/k-skill/logs/skills-check.log" 2>&1
'@ | Set-Content "$HOME/.config/k-skill/bin/check-skill-updates.cmd"
schtasks /Create /SC DAILY /TN "k-skill-update-check" /TR "\"$HOME/.config/k-skill/bin/check-skill-updates.cmd\"" /ST 09:00 /F

配置完成后，简短告知用户日志文件的路径：

• ~/.config/k-skill/logs/skills-check.log

4. 征得明确同意后提供 GitHub Star 选项

在配置流程的最后，向用户发出如下简短询问：

是否需要为 k-skill 仓库 (NomaDamas/k-skill) 点一个 GitHub Star？
如果您同意，将通过 `gh` 自动完成操作；如不需要，直接跳过即可。

规则：

• 在用户做出明确同意之前，严禁调用 gh repo star
• 若未安装 gh 或未登录认证，仅提供安装/登录指引，不得自动使用绕行方案
• Star 的目标仓库为 NomaDamas/k-skill

若用户同意且 gh auth status 验证正常：

gh repo star NomaDamas/k-skill

执行成功后，输出简短的完成提示即可。

完成检查清单

• 已存在 ~/.config/k-skill/secrets.env 文件且权限为 0600（或 Agent 正通过自带密钥库管理凭证）
• 已正确配置所需的环境变量
• 仅在用户明确同意的情况下配置了自动更新检查或 GitHub Star

注意事项

• 核心标准流程为：“安装全量 Skill → 运行本 Setup Skill → 使用具体功能”
• 切勿将密钥文件提交或保留在仓库内