1实现原理 · 为什么它能做到
它是「包装层」而非 fork：目录内不含上游 ima-skill 的任何内容，只提供安装/诊断/修复/检索编排，所以上游发新版时用户直接拿到新版，包装层不与之冲突。
ima-copilot/SKILL.md
- **Never vendor upstream files.** This skill directory does not contain any copy, fork, or excerpt of ima-skill's own content. When ima-skill ships a new release, users get the new release without any interference from this wrapper.
注：这里在做什么：把「不 vendor、不 pin、不静默改上游」写成 SKILL.md 的 do-not-violate 清单（'Architectural principles (do not violate)'），修复以运行期指令形式交付，属于架构约束而非营销话术——目录里确实只有 4 个自研文档 + 3 个脚本 + 1 个模板。
安装原理：从 IMA 官方分发域下载 zip → 落到 /tmp 暂存目录 → 解包后交给 vercel-labs/skills 的 npx CLI 分发，全部步骤幂等。
ima-copilot/scripts/install_ima_skill.sh
ZIP_URL="${BASE_URL}/ima-skills-${IMA_VERSION}.zip" ZIP_PATH="${STAGING_DIR}/ima-skills.zip" echo " Downloading ${ZIP_URL}" http_code=$(curl -sS -L --fail -o "$ZIP_PATH" -w "%{http_code}" "$ZIP_URL" || echo "000")
注：BASE_URL=https://app-dl.ima.qq.com/skills，版本默认 1.1.2 可由 IMA_VERSION 或 --version 覆写；下载只做 HTTP 200 与体积 >1000 字节两项粗校验，无 checksum/签名验证。
分发决策不靠程序化探测上游 zip 结构：优先取 <staging>/ima-skill/SKILL.md 这一约定布局，只有当布局变化时才递归找最浅的 SKILL.md，避免误取 notes/、knowledge-base/ 下的同名子模块文件。
ima-copilot/scripts/install_ima_skill.sh
SKILL_SRC="" if [ -f "$STAGING_DIR/ima-skill/SKILL.md" ]; then SKILL_SRC="$STAGING_DIR/ima-skill" else
注：注释里点明了动机：上游 1.1.2 的 zip 在根 / notes / knowledge-base 三处都有 SKILL.md（正是 ISSUE-001 的成因），『第一个找到的 SKILL.md』策略会非确定性装错。
目标 agent 靠目录存在性探测（~/.claude / ~/.agents / openclaw 命令），只对探测到的 agent 安装；一个都没探测到时兜底装到 claude-code。
ima-copilot/scripts/install_ima_skill.sh
AGENTS=() [ -d "$HOME/.claude" ] && AGENTS+=("claude-code") [ -d "$HOME/.agents" ] && AGENTS+=("codex") if [ -d "$HOME/.openclaw" ] || command -v openclaw >/dev/null 2>&1; then AGENTS+=("openclaw") fi
注：探测即「用户已选择用这个 agent」的代理指标；注释明确『absence means skip silently rather than install anywhere they haven't opted in』。
跨 agent 共享靠 vercel skills 的默认 symlink 模式：一次 npx 调用带多个 -a 目标，第一个成功安装的目录成为 canonical，其余软链过来；因此修复一次即三端同步。
ima-copilot/scripts/install_ima_skill.sh
if ! npx -y skills add "$SKILL_SRC" -g -y "${AGENT_FLAGS[@]}"; then
注：文档明说没传 --copy（'Notice what is **not** passed: `--copy`'）；installer 的 cleanup trap 会删掉 /tmp 暂存目录，且注释论证了删除不会破坏软链（canonical 与源路径解耦）。
凭证管理是 XDG 明文文件 + 环境变量优先：脚本先读 env，再读 ~/.config/ima/{client_id,api_key}，两者都缺就报错退出。
ima-copilot/scripts/search_fanout.py
client_id = os.environ.get("IMA_OPENAPI_CLIENTID", "").strip() api_key = os.environ.get("IMA_OPENAPI_APIKEY", "").strip() config_dir = Path.home() / ".config" / "ima"
注：诊断脚本用同一顺序（CLIENT_ID="${IMA_OPENAPI_CLIENTID:-}" 再回落到文件、tr -d '\n' 去换行）；凭证以 ima-openapi-clientid / ima-openapi-apikey 请求头发往 ima.qq.com。
诊断脚本声称严格只读：逐项打 ✅/⚠️/❌ 行并统计，退出码 0=全过 / 1=有需人工处理项 / 2=诊断自身失败（网络或工具缺失）。
ima-copilot/scripts/diagnose.sh
# This script is strictly read-only. It will never modify, create, or delete # any file outside its own stdout. Safe to run as many times as you want.
注：只读手段是：find_install 逐个候选路径测试 SKILL.md 是否存在、head -n 1 读首行、curl 打一次 liveness 接口——没有任何 > 重定向、sed -i 或 chmod。
对 symlink 共享做去重：先用 python3 os.path.realpath 把三个 agent 路径规范化，同一底层目录只扫描一次，避免同一问题被报多次。
ima-copilot/scripts/diagnose.sh
canonical() { python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1" 2>/dev/null || echo "$1" }
注：对应 SKILL.md『diagnose.sh detects this sharing and dedupes its reports』；去重靠 SCANNED_REALS 字符串匹配实现。
ISSUE-001 检测是「三态状态机」而非布尔判断：区分未修（首行不是 ---）、Strategy A 已改名 MODULE.md、Strategy B 已补 frontmatter，另有「SKILL.md 与 MODULE.md 同时存在」的冲突态。
ima-copilot/scripts/diagnose.sh
if [ -f "$skill_md" ]; then local first_line first_line=$(head -n 1 "$skill_md" 2>/dev/null || echo "") if [ "$first_line" = "---" ]; then return 0 fi return 1 fi
注：函数注释列出返回码 0/1/2/3/4 语义（OK / broken / 子模块不存在 / Strategy A 已应用 / 冲突），使『跑过修复』与『上游修好了』可区分。
修复动作不由脚本携带，而是写成文档里的 shell 命令、由 agent 在获得用户明确同意后运行：'we ship instructions, not patches'。
ima-copilot/references/known_issues.md
4. **Do not** add the fix commands into any shipped script — keep them in this file so the agent reads and executes them at runtime under user consent. This preserves the contract: we ship instructions, not patches.
注：配套纪律：多策略时强制 AskUserQuestion 让用户选、执行前 cp 备份到 /tmp/ima-copilot-backups/<时间戳>/、命令全部幂等（[ -f ] 守卫）、结尾给 rollback cp。
扇出检索绕开 API 缺陷：IMA OpenAPI 无跨库端点，脚本先分页枚举全部 KB，再对每个 KB 并发调用 search_knowledge（默认 12 worker），最后在客户端分组排序。
ima-copilot/scripts/search_fanout.py
with concurrent.futures.ThreadPoolExecutor(max_workers=args.workers) as pool:
注：文档把三条硬约束写在最前（No cross-KB endpoint / No relevance score / Silent 100-hit truncation），客户端排序只做分组与命中数排序，明确声明不做跨库相关度排名。
100 条静默截断靠特征反推：命中数正好达到 HARD_HIT_CAP(100) 且响应里既无 is_end 也无 next_cursor，才判定该 KB 被截断并在输出里单列 ⚠️ 提示。
ima-copilot/scripts/search_fanout.py
truncated = len(hits) >= HARD_HIT_CAP and not data.get("is_end") and not data.get("next_cursor")
注：权限被拒（code 220030，订阅型只读 KB）另走一条分桶，收进结果尾部的 ℹ️ 块而不淹没真实命中——分组函数 rank_groups 返回 priority/others/denied/empty 四桶。
个性化完全落在用户侧配置文件：~/.config/ima/copilot.json 的 priority_kbs / skip_kbs / fanout_strategy 三项；无配置文件即「中性默认」（全库扇出、按命中数排序、不提升）。
ima-copilot/SKILL.md
The personalization file is **per-user** and private. This skill ships only a template — see `config-template/copilot.json.example`. A user with no config file gets a neutral default: fan out all accessible KBs, sort groups by hit count, no boosting.
注：仓库只带 example 模板（占位值 your-curated-kb-name / your-subset-kb-name），SKILL.md 明文禁止硬编码用户 KB 名。
2核心能力
01一键把上游 ima-skill 安装到 Claude Code / Codex / OpenClaw（自动探测、未装者跳过、symlink 共享一份 canonical 副本）
02只读健康诊断：安装存在性（三 agent 三候选路径）、凭证存在性 + live liveness 校验、ISSUE-001 扫描，输出带退出码语义
03凭证配置走查：XDG 布局（目录 700 / 文件 600）+ printf 写入 + 调 search_knowledge_base 做一次空查询确认 code:0
04已知问题登记表 + 两套可选修复策略（A 改名 MODULE.md / B 补 frontmatter / skip 不修），命令幂等并附回滚
05个性化扇出检索：按 priority_kbs 声明顺序置顶、其余按命中数降序（KB 名做二级键保证同参可复现）、skip_kbs 整库排除
06截断与权限分桶告警：100 条饱和 KB 单列 ⚠️ 建议收窄查询；返回 220030 的订阅型 KB 单列 ℹ️ 不参与结果
07文本 / JSON 双渲染：默认人类可读分组（🥇/📚 + 摘要），--json 输出 {priority, others, denied, skipped_by_config} 供下游工具消费
08卸载与升级路径：文档给出 vercel skills remove 命令，并说明每次 Capability 1 升级后需重跑修复（修复不持久化是设计而非缺陷）
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | curl（下载官方 zip + 凭证 liveness 调用） |
| cli | unzip（解包官方发行 zip） |
| cli | npx（要求 Node.js 18+） |
| cli | python3（search_fanout.py 运行环境；diagnose.sh 用它做 realpath 规范化） |
| cli | sed / cp / mv / mktemp / head（修复命令链使用的系统工具，统一用 command 前缀绕过用户别名） |
| package | skills（vercel-labs/skills，npm 包名 skills；npx 按需现场拉取并执行） |
| network | 上游 ima-skill 官方发行包（zip） |
| api | IMA OpenAPI · search_knowledge_base（枚举 KB / 凭证 liveness） |
| api | IMA OpenAPI · search_knowledge（单库检索，扇出的基本调用） |
| network | 凭证发行页（用户手工创建 Client ID / API Key，非脚本请求） |
| network | 可达性探测/文档引用域（api_key_setup.md 建议用 curl 探 http 码） |
4风险提醒 风险提醒：橙色 · 评估后使用
风险提醒：橙色 · 评估后使用
- 凭证为明文文件且上游 API key 无设备绑定 — client_id/api_key 以 600 明文存在 ~/.config/ima/；api_key_setup.md 自述 'The IMA API currently does not scope credentials per-device — a leaked API key can be used from anywhere on the internet until it's rotated.'，并提醒备份工具可能把凭证同步出本机。
- 安装链路无完整性校验 + 运行未 pin 的远程包 — 官方 zip 只校验 HTTP 200 与体积 >1000 字节（无 checksum/签名）；`npx -y skills add` 每次现拉 npm 包 skills（实测 latest 1.5.26）。上游包或 npm 包被投毒，等同把未审计内容装成 agent 指令源。
- 修复动作直接改写上游安装目录，且 symlink 模式下影响三端 — Strategy A/B 会 mv/sed 改 ~/.claude/skills/ima-skill/**；在默认 symlink 共享下，一次改动瞬时传播到 Codex/OpenClaw。虽有备份与逐项用户同意，但仍要求用户看懂 ask 提示（agent 若解释不清就变成『盲目同意』）。
- 检索结果原文进入模型上下文（间接 prompt injection） — search_knowledge 返回的 title/highlight_content 被原样 print（仅截断 120 字符），知识库/公众号文章正文可夹带指令文本；脚本不做净化、不标来源信任级。
- 文档与实现存在三处表述出入 — 示例诊断输出格式、备份路径结构、零探测兜底安装 claude-code 三处与脚本实际行为不符（详见 verification.second_pass 的 discrepancy 项）；照字面照抄文档示例会困惑。
风险提醒：橙色，评估后使用。按六档范式第 4 档特征『涉及凭证/环境变量读取，或依赖第三方插件、镜像、远程包』，本例三项全中：(a) 明文凭证读取——diagnose.sh 与 search_fanout.py 都读 ~/.config/ima/client_id、~/.config/ima/api_key（600）与 IMA_OPENAPI_CLIENTID/IMA_OPENAPI_APIKEY，并以请求头发往 ima.qq.com；(b) 远程包 + 无校验安装——运行期执行 `npx -y skills add`（npm 包 skills，未 pin；实测 registry.npmjs.org/skills latest=1.5.26、repository=git+https://github.com/vercel-labs/skills.git），安装脚本还从 app-dl.ima.qq.com 拉 zip 解包落盘，仅校验 HTTP 200 与体积；(c) 受控改写上游目录——修复会 mv/sed 改 ~/.claude/skills/ima-skill/**，虽有时间戳备份、幂等守卫与逐项用户同意。之所以不是红色：无 TLS 校验降级、无反反爬/绕过、无任意代码执行面（无 eval/exec/os.system/subprocess、无管道执行远端内容）、无隐蔽外发，凭证只发往其发行方官方 OpenAPI，全目录未发现第三方埋点；之所以不是黄色：明文凭证接触与运行期远程包执行已越过『常规公开 API 调用』边界。另附 references/api_key_setup.md 自述提醒：『The IMA API currently does not scope credentials per-device — a leaked API key can be used from anywhere on the internet until it's rotated.』
5第二遍独立确认
- [ok] 外部依赖调用点存在性（curl / unzip / npx / node 版本 / python3 / sed） — install_ima_skill.sh 对 curl/unzip/npx 做 `command -v` 前置检查、对 node 校验 `-lt 18`、用 `unzip -q -o` 解包、用 `npx -y skills add "$SKILL_SRC" -g -y ...` 分发；diagnose.sh 用 python3 打 realpath；known_issues.md 用 `command sed -i.bak`。逐条在源码内命中，无凭空依赖。
- [ok] npx 运行时依赖的真实身份与版本策略 — 实测 GET https://registry.npmjs.org/skills/latest 返回 name=skills、version=1.5.26、repository=git+https://github.com/vercel-labs/skills.git、description='The open agent skills ecosystem'，与脚本 `npx -y skills add` 及文档 [vercel-labs/skills] 指向一致；未 pin 版本，每次按需现拉。
- [discrepancy] SKILL.md 示例诊断输出 vs diagnose.sh 实际输出 — SKILL.md 示例写 `✅ upstream ima-skill installed (claude-code)`、`❌ upstream ima-skill NOT installed (openclaw)`；脚本实际打印 `✅ ima-skill installed (claude-code) at $CLAUDE_PATH`（带路径、无 upstream 前缀）与 `⚠️ ima-skill NOT installed (openclaw) — run install_ima_skill.sh`（warn 而非 fail，退出码经汇总后仍为 1）。示例仅示意，功能无差异，但照字面比对会对不上。
- [discrepancy] 备份路径描述 vs known_issues.md 实际命令 — SKILL.md 说修复会把原文件拷到 `/tmp/ima-copilot-backups/<timestamp>/<relative-path>`；实际命令是 `BACKUP="/tmp/ima-copilot-backups/$(date +%Y%m%d-%H%M%S)"` 后以扁平重命名保存（`$BACKUP/notes-SKILL.md`、`$BACKUP/knowledge-base-SKILL.md`），并不保留相对目录结构；回滚命令与之一致，功能成立但文档描述不准。
- [discrepancy] 『未探测到 agent 就跳过、不写用户未选择的路径』的表述 — SKILL.md 与 installation_flow.md 都强调未探测到的 agent 静默跳过；但脚本在『零 agent 探测到』时的实际兜底是 `echo " Defaulting to claude-code as the most common case."` 并继续安装到 claude-code。SKILL.md 的概述未点明这条例外（references 里写了），属概括与实现的轻微出入。
- [ok] diagnose.sh『严格只读』声明复核 — 全文复读：输出只用 echo/printf，读取只用 head -n 1、[ -f ] 探测、tr -d、curl 一次 POST 读响应、python3 打印 realpath；无 > 重定向、无 sed -i、无 chmod、无 rm、无 mkdir。修正结论：『never modify, create, or delete any file』成立。
- [ok] 凭证读取点与去向（是否外发第三方） — 只有 diagnose.sh 与 search_fanout.py 读 env/文件；请求头统一 ima-openapi-clientid / ima-openapi-apikey，目标域名仅 ima.qq.com。全目录 URL 扫描命中集合 = ima.qq.com（含 /openapi 与 /agent-interface）、app-dl.ima.qq.com、github.com/vercel-labs/skills（文档引用）+ npm registry（npx 隐式）；无第三方回调、无埋点、无硬编码密钥常量。
- [unlocatable] 站外 API 行为断言的可验证性（100 截断 / 220030 无权限 / 无跨库端点） — 『恰好 100 条即静默截断且无 is_end/next_cursor』『订阅型 KB 返回 code 220030』『无跨库端点』均为 IMA OpenAPI 的站外行为断言，仓库内无测试/fixture 可证；只能确认实现与断言自洽（HARD_HIT_CAP = 100、PERMISSION_DENIED_MARKER = "220030"、truncated 判定式）。要坐实需真实凭证实测，本侦查不硬写。
6结论
适合：适合：①已在用腾讯 IMA（ima.qq.com）并持有 OpenAPI 凭证、同时在 Claude Code / Codex / OpenClaw 间切换的人——装一次三端共享、修一次三端生效；②被 ima-skill 子模块 frontmatter 报错（'Skipped loading skill(s) due to invalid SKILL.md'）卡住、想要有备份可回滚修复路径的人；③知识库多、想按 priority_kbs 置顶并 skip_kbs 去重的检索用户；④想参考『上游有已知 bug 时，包装层如何交付修复』这套架构写法的 skill 作者。
不适合：不适合：①没有 IMA 账号/凭证——installer 之外的两个脚本都以凭证为前提（缺则直接报错退出）；②不想让 agent 读 ~/.config/ima/ 凭证文件、或不想让 agent 改写已安装 skill 目录的人；③期待本 skill 自带检索后端/索引——它是纯客户端扇出，明确不做跨库相关度排名、不做语义去重、不做时间排序；④离线/内网环境（依赖 app-dl.ima.qq.com、npm registry、ima.qq.com OpenAPI）；⑤把本 skill 当作上游 ima-skill 的替代品（包装层不含任何上游能力实现）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 ima-copilot.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent9677c96e7b3f34a4…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库daymade / daymade/claude-code-skills
原始 GitHubdaymade/claude-code-skills ↗
Stars1392
最近推送2026-09-09
本 skill commit
d5c4678cb5许可MIT（仓库根 LICENSE 文件；GitHub API spdx MIT；Copyright (c) 2025 daymade）
本站信息
收录日期2026-09-06
分类基础工具与工作流
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。