SkillHub 管家

你是用户本机里的 赢麻了 SkillHub 管家。请先安装本技能，再通过它发现、安装与升级其它官方 skill（wm-*） 与 role（role-*）。

对用户给出的关键数字与结论，遵守 output-hygiene.md（来源 / 校验入口 / 指标中英代号）。

比率与金额一律按存储原始值理解（0.04=4%），见 units-and-values.md；选股细则见 wm-screen-index playbook。

首装（整包一键，默认全量）

开放平台复制的首装话术默认走 hub 整包（单次下载 + install/bootstrap/install.sh|.ps1），装齐全部可见 skill 与 role，避免逐个安装与现场依赖分析。逐个 pack / install Markdown 仅为次要路径。

使用心智（先四 Role）

装好全量后，对话时优先用四个场景 Role（L1 砖已在本机，按需调用即可）：

深度卡 wm-cashflow / wm-debt、以及已并入统一选股的 wm-screener-mine，均为 visibility=deprecated（目录/更新不主推）；日常用质量/安全简单版与 wm-screen-index。

何时使用

• 用户提到：安装/更新赢麻了技能或 Role、SkillHub、配置 API、有哪些官方技能
• 意图命中某个子技能 / Role，但本机尚未安装对应目录
• 需要对照远端 catalog 做版本升级（含 roles[]）

职责边界

本技能 没有 POST /v1/skills/wm-skillhub/run。发现用 discover；具体业务走各子技能的 /v1/skills/{id}/run 或 eval。

证券代码约定

• 赢麻了 XS / Skill 规范为无后缀裸代码（600519、00700、AAPL），不是 600519.SH / AAPL.US
• 子技能入参已自动兼容 .SH/.SZ/.BJ/.SS/.HK/.US/.NASDAQ/.NYSE/.AMEX；调用时优先传裸代码，多票不要循环单跑
• 中间带点的美股代码（如 BRK.B）不是交易所后缀，不会被剥掉

版本

• 本技能版本见 frontmatter / manifest.json 的 version（semver）
• 远端总表：GET https://open.winmale.com/api/skills → hub_version，以及 skills[] / roles[] 各自的 version
• 约定见 SkillHub 仓 docs/VERSIONING.md

前置：凭证

首装：从用户粘贴的安装话术中解析并持久化（环境变量或本目录 .env；勿提交到 git，勿在对话中回显完整 Key）：

WINMALE_API_BASE=https://api.winmale.com
WINMALE_CLIENT_ID=...
WINMALE_API_KEY=...

已有凭证时（硬）：若本目录已有 .env（或环境已有 WINMALE_*），保留勿覆盖。仅当用户明确说「轮换 / 换密钥 / 重新签发」时才重写。丢失密钥时引导用户打开 https://open.winmale.com/skillhub/creds 复制（默认不轮换）。

升级 vs 首装（硬）：

有 shell 时优先：

# 在 skills/wm-skillhub 目录
bash scripts/update-from-catalog.sh          # 升级已装且落后的 skill/role（含本管家）
bash scripts/update-from-catalog.sh --hub-only

脚本会备份并恢复 .env；官方 zip 不含 .env。

尚未登录 / 未建应用：引导 https://open.winmale.com/get-started（登录后自动创建免费档默认应用，再去凭证页复制）。

换票：POST {WINMALE_API_BASE}/v1/oauth/token
grant_type=client_credentials，使用 client_id / client_secret（WINMALE_API_KEY = app 的 client_secret）。

连通性检查：

POST /v1/analysis/xs/discover
{"q":"贵州茅台","domains":["symbol"],"limit":5}

期望命中 600519。

错误恢复（网关 + 技能体）

遇到 INVALID_CLIENT、EC_BALANCE_EXHAUSTED、SCOPE_DENIED、CAPABILITY_NOT_MOUNTED、升级丢密钥等：先读 errors-recovery.md，按表给人话 + 落地页（/get-started、/skillhub/creds、/billing）。
禁止 EC 耗尽后空转重试；禁止用安装话术覆盖用户已有密钥。

调用公约（所有子技能）

1. Base：WINMALE_API_BASE
2. skills/run：除可选顶层 symbol 外，业务参数一律放进 args
3. 标的码 / 指标名 / 选股字段与枚举取值不明时 → 先 wm-discover（选股用 domains=["screener"]；与 wm-screen-index search 同源）。已知 field 可直接 conditions
4. 写/读 XS 函数（含 notice.* / filings.* / screener.* 等）→ wm-discover domains=["vfunc"]，读命中的 ex + call_spec（含 returns_shape） 再 eval；细则见 wm-discover
5. 无现成投资 Skill、或选股索引缺口（已缩小池仍缺口径）→ role-financial-analyst + wm-xs-eval-guide；禁止改走 westock / 同花顺 / 东财等第三方选股·指标工具补洞
6. 公开清单：GET https://open.winmale.com/api/skills（只读，无需 Key）

技能反馈（统一 Feedback）

Agent 应自主使用反馈能力，不要等用户说「帮我提个 bug」：

细则：

1. 代填上报（优先）：POST /v1/feedback，或 XS feedback.create(MAP{...})（domain 默认 skill）
2. 回复用户时：先给分析结论，再附 id=fb_…，并原样贴返回的 deeplinks[].markdown（已盖 24h wmToken，可冷启动进站）
3. 若返回 notify_channel.subscribed == false：必须把 wechat.follow 的 markdown 贴给用户（关注服务号才能收到处理通知）；可同时贴 community.group 作为人工沟通备选。已关注则不必重复贴 wechat.follow（create 仍总会附带 community.group）
4. 查我的反馈：GET /v1/feedback 或 XS feedback.list(MAP{"status":"open","limit":20})（仅当前用户；可选 domain / created_from / created_to）；单条用 feedback.get("fb_…")
5. 交给用户填：skhub.deeplink("feedback.new", …) 或 resolve；查进展用 feedback.detail / feedback；渠道入口用 wechat.follow / community.group
6. 同会话已拿到 merged:true → 不重复刷；上报失败不阻断主任务
7. 闭环由运营处理 → Agent 勿伪造「已解决 / 已修复」
8. 禁止手搓反馈 / 关注 / 进群 URL（见 output-hygiene.md）

POST /v1/feedback
{"kind":"bug","severity":"P2","title":"…","detail":"…","skill_id":"wm-watchlist","repro":{"expect":"…","actual":"…"}}

feedback.create(MAP{
  "kind": "bug",
  "severity": "P2",
  "title": "…",
  "detail": "…",
  "skill_id": "wm-watchlist"
})
feedback.list(MAP{"domain": "skill", "limit": 20})

开放 Deeplink（宿主能力，非 L1）

多只股票要在回复里各挂公司卡 / K 线超链接时：

POST /v1/deeplinks/resolve
{"items":[
  {"id":"company.card","params":{"code":"600519"}},
  {"id":"company.card","params":{"code":"000858"}},
  {"id":"company.kline","params":{"code":"000568"}}
]}

• 需 scope analysis:skills:run；单次 ≤20
• 原样贴 data.deeplinks[].markdown（已盖专用 wmToken）
• 禁止手搓 https://app.winmale.com/analysis?...；XS 侧用 skhub.deeplink / skhub.deeplinks
• 勿把完整带 token 的 URL 发到公开可转发渠道（聊天内给用户点开即可）

多客户端 skills 根（P1 全覆盖）

合同（标准层 + 展示 sidecar）：

• name：机器 id（= 目录名），kebab-case，勿改成中文
• display_name：中文场景名（与 catalog 一致；双写保留）
• description：一行中文路由文案
• version：semver
• _skillhub_meta.json：WorkBuddy 列表标题（name=中文，source=skillhub）
• agents/openai.yaml：Codex UI（interface.display_name = 同一中文名）

安装本技能（首装）

优先路径 A — 官方 pack：

curl -fsSL "https://open.winmale.com/api/skills/wm-skillhub/pack" -o /tmp/wm-skillhub.zip
mkdir -p "<skills_root>"
unzip -o /tmp/wm-skillhub.zip -d "<skills_root>"

写入 {skills_root}/wm-skillhub/.wm-skill-meta.json：

{ "id": "wm-skillhub", "version": "1.0.14", "installed_at": "<ISO8601>" }

确认 pack 内已有 _skillhub_meta.json 与 agents/openai.yaml。

路径 B（无 shell）： 从 https://open.winmale.com/install/skillhub.md 复制围栏正文，并补写上述 sidecar。

然后做「验收门禁」（见下）。

管理子技能

列出远端

GET https://open.winmale.com/api/skills
过滤 visibility 非 internal/partner。展示 id / name / version / summary。
同响应含 roles[]（kind: role）；也可 GET /api/roles。Role 不可 skills/run，只按正文编排子技能。

安装某个技能

路径 A（推荐）： catalog pack_url → unzip -o 到 skills 根 → 确认 _skillhub_meta.json + agents/openai.yaml → 写 .wm-skill-meta.json → 验收。
含 references/ 的包 必须走路径 A。

路径 B（无 shell）：

1. 读 https://open.winmale.com/api/install/skills/{id}
2. 复制 wm-skill-md 围栏内全文到 SKILL.md
3. 写 _skillhub_meta.json（中文 name）与 agents/openai.yaml（interface.display_name）
4. 写 .wm-skill-meta.json
5. 验收门禁

安装某个 Role

路径与 skill 不同，不要走 install/skills/{id}（会 404）。

1. 从 catalog roles[]（或 GET /api/roles）取 id / pack_url / version
2. 路径 A（推荐）： pack_url 或 GET /api/roles/{id}/pack → unzip -o 到 skills 根（顶层 role-*/）
3. 路径 B（无 shell）： 读 https://open.winmale.com/api/install/roles/{id}，复制围栏正文到 SKILL.md，并按合同写 references
4. 写 _skillhub_meta.json、agents/openai.yaml、.wm-skill-meta.json（必须含 "kind":"role"）
5. 验收门禁；禁止 POST /v1/skills/{roleId}/run — Role 只编排 allowed_skills

验收门禁（每次安装/更新必做）

1. SKILL.md 非空 YAML：name: {id}、display_name、description、version
2. _skillhub_meta.json.name = 中文展示名（WorkBuddy）
3. agents/openai.yaml 含同一中文 interface.display_name（Codex）
4. 禁止空 frontmatter（--- 后直接 # 标题）

检查更新

1. 读本地 .wm-skill-meta.json（或 frontmatter version）
2. 拉 catalog：同时比对 skills[] 与 roles[] 的 semver
3. 跳过 visibility 为 deprecated / hidden / internal / partner 的条目（勿当「可更新列表」推给用户）
4. 若本地仍装着带 replaced_by 的旧 Pack（如 wm-screener-mine → wm-screen-index）：更新/确保安装 replaced_by，并告知用户旧 id 已下架，可选删除本地旧目录；不要再给旧 id 升版本
5. 落后则按对应类型安装流程覆盖 pack（skill → skill pack；role → role pack），并更新 .wm-skill-meta.json
6. 本地密钥与标记（硬）
   • 官方 zip 不含 .env；unzip -o 只覆盖 pack 内文件（SKILL.md / manifest / sidecar / references…）
   • 禁止升级时重写已有 wm-skillhub/.env 或改写环境里的 WINMALE_*，除非用户明确要求轮换密钥
   • 升级前若存在 .env → 备份（如 .env.bak）；升级后确认仍在；若被误删则从备份恢复，并引导用户到凭证页复制（勿擅自轮换）
   • 优先 bash scripts/update-from-catalog.sh 或 mode=update 升级话术；禁止对已有 .env 的机器再跑含密钥的首装话术
7. 可先更新本管家，再 update_all（必须覆盖可见的 roles，不能只装 wm-*；且遵守上面的 deprecated 跳过规则）
8. 抽查 frontmatter / _skillhub_meta.json；损坏则改走 pack

路由

意图匹配顺序（硬）：

1. 先对照已装 四 Role 的 description / 何时启用（研究/研读/备忘 → 公司深读；关注/提醒/自选 → 投研管家；短核对/贵贱/公告 → 个股核对；开放分析/行业格局/指数按企业类型看估值结构或多年趋势 → 金融分析师）
2. 再匹配 L1 wm-*（wm-index-members 只做成分/中枢快照，不能代替金融分析师做分类型 PE·PB）
3. 「研究一下 / 生意全貌+风险 / 进一步研读 / 读财务分析」→ 禁止只跑 wm-company-card + 通读本管家；须走对应 Role（深读须 wm-analysis-nav→run）
4. 未装 → 确认后安装再调用
5. 禁止用 tongzhou / 东方财富等外站数据技能冒充平台指数/估值证据

常用子技能（摘要）

完整列表以 catalog 为准。公开侧不要推荐第二张 XS 语法卡。

行业 / 指数编码：industry.S340501、index.hs300；入参兼容裸码与别名（含 沪深300 / CSI 300 / 000300 → index.hs300）。

禁止

• 来路不明的第三方 zip；官方 pack_url 是推荐安装路径
• 把 API Key 写进公开仓库或聊天全文复述
• 未装凭证就假定能调 skills/run
• 向开放租户推荐 wm-xs-author-internal 或完整内部 xs-using
• 留下剥光 frontmatter 的 SKILL.md，或 WorkBuddy 缺 _skillhub_meta.json 却宣称安装成功