Skip to content
Back to search

skills-constitution

"当 Agent 接到专业任务(编码/爬虫/文件操作/API调用/数据分析/文档/部署/推送等)时,强制先查记忆层和技能索引,有匹配必用、无匹配必搜、答复时自动推荐(排除已装)。用于防止 Agent 跳过技能直接硬扛通用能力。跨平台通用(WorkBuddy/Claude/ChatGPT/Cursor/Gemini 等 20+ 框架)。完整版本史见 CHANGELOG.md。"

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jiabaobei--skills-constitution/badge.svg)](/listings/jiabaobei--skills-constitution)

HTML

<a href="/listings/jiabaobei--skills-constitution"><img src="/api/listings/jiabaobei--skills-constitution/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 513 lines
  1. ---
  2. name: skills-constitution
  3. description: "当 Agent 接到专业任务(编码/爬虫/文件操作/API调用/数据分析/文档/部署/推送等)时,强制先查记忆层和技能索引,有匹配必用、无匹配必搜、答复时自动推荐(排除已装)。用于防止 Agent 跳过技能直接硬扛通用能力。跨平台通用(WorkBuddy/Claude/ChatGPT/Cursor/Gemini 等 20+ 框架)。完整版本史见 CHANGELOG.md。"
  4. version: 2.33.0
  5. license: MIT
  6. author: jiabaobei
  7. github: https://github.com/jiabaobei/skills-constitution
  8. display_name: "Skills 宪法"
  9. display_name_en: "Skills Constitution"
  10. description_zh: "Skills 宪法 —— 凌驾于全部技能之上的元规则:先查记忆、再查技能索引(按功能分类)、有匹配必用、无匹配必搜、答复时推荐(排除已装)。防止 Agent 跳过技能硬扛。版本史见 CHANGELOG.md。"
  11. description_en: "Skills Constitution — universal meta-rule: pre-check memory, lookup skill tree by category, mandatory use when matched, search when unmatched, recommend non-installed skills on answer. Cross-platform for 20+ agent frameworks. Changelog: CHANGELOG.md."
  12. visibility: "public"
  13. agent_created: true
  14. ---
  15. # Skills 宪法(Skills Constitution)
  16. > **一句话定位**:凌驾于全部技能/工具/插件之上的**元规则**。所有能力调用必须先过这一关。
  17. >
  18. > **v2.33.0(当前)** — 零号条款改为「默认简单」(用户钦定 2026-11-12):纯信息查询/简单问答直接作答,只有真会改动本机状态的动作型任务(动文件/跑脚本/安装/写代码)才触发三查。分类器 `ambiguous` 兜底由「按专业处理」改为「按简单处理」,专业词表收紧为 `ACTION_TASK_MARKERS`(移除查询/分析/启动等纯认知词),注入模板「首句输出三查」加限定为仅专业任务。新增 8 例分类自检。
  19. > **v2.31.0(当前)** — **抗崩溃层**(2026-09-21 事故:钩子超时 → 平台 `UserPromptSubmit operation blocked by hook: Hook timed out after 15000ms / 20000ms` → 用户整条消息被拦死,感知为"系统崩溃")。**实测根因**:热路径每轮跑 **2 个 python 钩子**,而本机 python 解释器启动本身 0.7~2.5s(Defender 首扫),固定成本 3~7s 直逼 15s/20s 上限;再叠加 ① Stop 分支三处早返回把"通过即清除"堵死 → 旧违规永不清除、每轮重播;② 时间窗与警告耦合 → 跨时段把几天前的旧账当新警告弹。**新增五条防灾死规则**:R1 拉闸优先(开关文件/环境变量,任何事件在任何逻辑之前放行)、R2 异常放行(门禁自身任何异常 → 退出码 0)、R3 自修复豁免(门禁不得拦截对门禁自身的修复,破"自锁死")、R4 写失败可见 + 自动拉闸(连续 3 次写失败自动断电)、R5 耗时预算(超预算记 slow / 自动拉闸)。**新增** `scripts/emergency-off.sh` / `emergency-on.sh`(纯 bash 一键断电/合闸,不依赖 python)、`scripts/constitution-doctor.py`(7 项体检:拉闸状态/状态文件可写/注入缓存/违规卡死/钩子注册与超时值/**耗时实测**/健康日志)、`scripts/tests/gate_failsafe.py`(**26 项抗崩溃验收,发布前置门禁**)。违规语义改为**合规即清零**(写 `cleared_ts`/`cleared_task`,可审计不销毁历史)。**v2.30.0 任务边界设计(同对话+2h、三查一次、有匹配必用每轮、Stop 每任务一次)一行未动**,验收 13→17 项全过。
  20. > **v2.30.0** — 任务边界重定义(用户钦定 2026-09-20:"任务开始三查一次,中途不再三查"):① 门禁 UserPromptSubmit 不再把"每条非追加式消息"当新任务 —— 新边界 = 同一对话(session_id 可用则校验,缺失退化为纯时间窗)+ 距最近活动 2 小时内;窗口内不重置状态、不重复要求三查。② 同对话另起新类型任务(新消息必需分类与当前任务完全不相交)→ 提示 Agent 询问用户是否重新三查,答复前按当前通行证放行。③ 「有匹配必用」不受"三查一次"限制:同任务每条消息凡有必需分类,提醒一行(约 40 字,省 token),相关技能必须调用。④ Stop 收尾校验每任务只做一次(针对首轮回复,保住 v2.27.5 防"零追责"目的),不再逐轮要求复述三查。新增验收脚本 `scripts/tests/gate_task_boundary.py`(13 项全过,可重复运行);既有回归 142/142 通过。
  21. > **v2.29.1** — `skill_doctor` 白名单修复:`_<name>-references` 是 E2 机制用来标记"该框架已装"的目录(`recommend_skills.py` 靠它判定),它不是技能、本就没有 SKILL.md;旧版 `scan()` 只按"有无 SKILL.md"判目录性质,把它判成 `missing_skill_md/broken` → 本机常年报 1 条假损坏,`--quarantine` 更会把它当损坏技能**移走**、直接破坏 E2 标记。现于 `scan()` 的跳过 guard 增加白名单正则 `^_.*-references$`(与"点开头目录"同等对待);报告与隔离共用同一份 findings,一处跳过即同时修好两条路径。实测本机损坏 1 → 0,新增回归断言 2 条。
  22. > **v2.29.0** — 技能路由与检索结论可靠性加固(2026-09-19 事故复盘):三查防线此前只验证"查没查",不验证"查得对不对、结论下得对不对",一日连犯三错。新增死规则「第一条补充 C」:① 用户口述的模糊技能指代**必须映射确认**(全量内容级检索 → 列候选请用户确认 → 执行前回显映射),禁止望文生义取"最像的那一个"——实锤:「github改版技能」被错配成 constitution-release,真身是 github-gitee-sync;② "**不存在/未安装**"结论需**双通道检索证据**——单次 Glob/Grep 零命中 ≠ 不存在(实锤:github-gitee-sync 在库内被误报未安装);③ **类故障必须先查专项技能再动手**——git 仓库损坏时库内现成的 git-repo-recovery 未被想起,徒手硬修。
  23. > **v2.28.0(当前检索架构)** — 技能检索质量重构(借鉴 zg「多路召回 + RRF + 配对评测」方法论):① 单一加权打分改**双路证据召回 + RRF 融合**(名称路 = 词面命中技能名;描述路 = BM25 词频×IDF×长度归一化),按排名融合、零调参 —— 实测 dev 集 hit@4 45%→100%、未调参的留出集 66.7%→100%;② 分词修噪(纯虚词表 / 弱义字表分离,二元组含纯虚词即丢),修"个转/价和/份汇"这类**跨词边界假词**与冗长描述误撞导致的"万能描述技能霸榜"(overlap_score 既无长度归一化也无停用词,这是根因);③ 新增**跨语言技术词桥**——技能库是双语的,任务说中文而相当一批技能的 description 是英文(browser-automation / code-review / ponytail / openai-whisper),纯词面检索在这道语言鸿沟前交集恒为空,用确定性词桥作"语义通道"的零依赖替代(只映射英文技术词,不动 Layer C 任务分类);④ 新增**评测纪律**:`scripts/tests/retrieval_eval.py` 配对 A/B(legacy vs hybrid)+ 12 条**开发期从未调参的留出集** —— 实测 dev 集被调到 100% 时留出集只有 66.7%,过拟合被当场抓出;评测已入回归门禁(run_tests 第 14 节,134→140 条)。
  24. > **v2.27.6** — 修"技能树查了等于没查":① 分类路由兜底原取字母序前 5 个分类(general/browser/search/file/data,与任务无关),改复用确定性路由,实测"推送到 github 和 gitee"能正确落到 code/meta;② 注入名录两处硬截断 `skills[:8]`/`cat_skills[:10]` 改为按任务相关度排序取前 N(复用现有 loose_retrieve_skills),行尾标注"未列全"——排在 code 类第 38 位的 github-gitee-publish 从此能露面;③ 新增死规则「第一条补充 A」:注入名录是预览不是清单,行尾标"未列全"时判"无匹配"前必须 grep 全量索引。
  25. > **v2.27.5** — Stop 追责拧紧:收尾免检区分强/弱证据(step1 真实 PASS 或真调过技能才免检;仅"注入即签"弱通行证且本任务有必需分类时,收尾回复仍须过三查文本校验),堵"无视注入提示、全程零举证零追责"漏洞;必需分类缓存进门禁状态零开销复用;GBK 输出崩溃根治(stdout/stderr 强制 UTF-8,收编自安装副本实战补丁)。
  26. > **v2.27.4** — 钩子注册补全:UserPromptSubmit 补注册注入保活钩子(pre-hook --hook-mode),修复"注入只在 SessionStart 做一次、长会话过期后 Agent 拿不到记忆+技能树 → 该调技能不调技能"的防线缺口;注册脚本全面直调 python(本机实测 bash 包装层单次 2.5~12.9s 是宿主 20s 超时元凶,pre-hook 本身仅 0.19s,直调后热路径门禁+注入合计 ≈3.5s);MARKERS 收编 pre-hook.py,幂等替换/卸载可识别手工添加的注入钩子。回归 +3 条(13.6 注册完整性)。
  27. > **v2.27.3** — 门禁状态文件写入健壮性修复(用户钦定"宪法不起作用"真因):① 并发 tmp 重名 —— 三个钩子进程共用固定名 `state.json.tmp`,互相截断后被 `os.replace` 换回主文件;改为 tmp 名带 pid。② Windows `os.replace` 遇 PermissionError 时 v2.27.0 兜底 open(w) 直写会截断主文件 → 改为只做短重试,仍失败放弃写入保留旧文件。③ 兜底语义纠偏 —— 损坏即静默放行导致门禁**永久失效**;改为降级放行(不阻断、打印提示、不签通行证),下次任务开始自动重置恢复。附陈旧 tmp 清理 + 5 条回归用例(并发压测 0 损坏)。
  28. > **v2.27.2** — 测试修正(零功能变更):过时断言对齐 v2.27.0 单进程架构——13.0c 改断言单进程委托在位+嵌套自愈已删除、13.3 阈值 10s→18s(慢机器+Defender 首扫实测 6~18s 波动,热路径均值 ~7s)、13.1/13.3 超时捕获记失败不崩套件。
  29. > **v2.27.1** — 技能图谱补全与降噪:① 自愈路径(refresh_injection)接入图谱候选(v2.27.0 曾漏传 [],导致 hook-mode 自愈产出的注入块缺「🕸️ 技能图谱」段);② cluster 候选降噪——超采样 3 倍后,同簇成员必须与任务有词面交集(名称/描述,overlap_score>0)才收录,结构边(chains_to/co_anchor)与 alternative 保持原样;实测"写爬虫"任务候选 8→1(adobe-* 无关同簇成员全灭),注入块 4199→3458 字符,无关任务宁缺毋滥(0 候选)。
  30. > **v2.27.0** — 钩子单进程化 + 门禁「任务开始拦一次、中途不再拦」真实生效:① 门禁状态文件改原子写入(修复 UserPromptSubmit/PreToolUse/Stop 三钩子并发写截断 → 通行证丢失 → 中途误拦,用户钦定 bug);② 注入上下文过期(>24h)时门禁进程内自动刷新(修复任务开始拿不到通行证);③ user-prompt-submit.sh 热路径进程启动 9 次→1 次、session-start.sh 6 次→1 次(解释器缓存 + builtin 读取 + exec 单次 python --hook-mode),慢机器实测 33~39s → 预期 <8s,不再触发宿主 20s 超时;④ bash 兜底注入块禁止引导 Agent 整读技能树文件(可达数十万字符),改为 pre-hook 按任务过滤约 3 千字符(省 token)。
  31. > **v2.26.0** — 一键更新脚本 `scripts/update.sh` / `scripts/update.ps1`:把「更新前先去 GitHub 下载最新版、更新完成后自动在本地安装最新版」固化为脚本——下载最新 main 包(codeload + api 双保险)→ 完整性校验(半残包保持旧版不毁旧装)→ 透传参数跑新版安装器自动安装。
  32. > **v2.25.1** — 钩子挂起修复:两条钩子的解释器检测加 3s 存活探针(修复 Windows 上 Microsoft Store 占位别名启动即挂起、被宿主 20s 强杀的卡死),stdin 读取限时 2s、自愈限时 10s,超时一律降级 fail-open,钩子永不卡任务。
  33. > **v2.25.0** — 第五条「答复推荐」极度省 token 改造:推荐来源从"每次全盘搜 GitHub"改为**读本地排行榜快照**(`data/skill_rankings.json` + `scripts/recommend_skills.py` —— 零网络、约 20KB、纯确定性规则匹配 + 自动排除已装);新增 `scripts/update_skill_rankings.py` 低频抓取权威排行榜(quemsah/awesome-claude-plugins,索引 3.6 万+ 仓库)重建快照,过期(>30 天)只提示不自动拉取;step5 新增推荐来源标注软校验(标注"本地排行榜快照"=省 token 最佳实践)。
  34. > **v2.24.0** — 隐形技能治理 + 门禁「一次三查全程放行」+ 轻量索引。实测修复五项:
  35. > ① `parse_frontmatter` 支持 YAML 块标量(`>`/`|` 及折叠变体)——旧版把 ponytail 全套等 137 个技能的 description 解析成单个 `>` 字符,检索永远命中不到(典型:用户装了 GitHub 116k★ 的 ponytail 却从未被调用);
  36. > ② 索引描述上限 200→2000——触发词(如 ponytail 的 lazy mode,位于第 400+ 字符)不再被截断丢弃;
  37. > ③ 门禁任务级通行证——任务开始时三查通过(平台注入或 step1 PASS)即全程放行,拦截前移为任务开始时的一次性提醒(用户明确要求:任务开始已三查,中途不得再拦);
  38. > ④ 新增 `scripts/skill_doctor.py`:隐形/损坏技能自动诊断(8 类检查)+ `--fix` 自动修复 + `--quarantine` 隔离损坏 + `--emit-min-index` 轻量索引(约完整索引 20% 体积,截断部分保留长尾触发词,冷门技能省 token 仍可命中);
  39. > ⑤ 图谱锚点抽取固定用前 200 字符 + 停用词三批扩容 + DF 上限 0.05→0.035——描述放宽后锚点暴增曾产生 752 节点巨簇,现恢复 ≤80 纪律(回归测试 106/106)。
  40. > **v2.23.0** — 技能图谱(借鉴 GitNexus 预计算关系智能):技能树之上叠加确定性关系图(`skill_graph.json`,随技能树重建自动产出)。三种边全部零依赖确定性抽取——`chains_to`(registry 的输出→输入 schema 交集)/ `co_anchor`(共享实体锚点,含停用词与文档频率过滤)/ `alternative`(同分类高重叠替代方案);确定性标签传播聚成功能簇。三处落地:① 注入块从“整分类清单”收窄到“锚点技能的任务线图谱”(带“为什么相关”溯源,更省 token);② 门禁 step3 新增 Layer F 图证据校验——引用的技能必须与任务锚点图谱连通,零连通带簇证据判 FAIL;③ 替代边不做放行凭证、不参与聚簇(纪律同 GitNexus 只对结构边做社区检测)。图缺失时全部链路行为与旧版一致(只加不删)。
  41. >
  42. > 完整版本史见 `CHANGELOG.md`。
  43. ---
  44. ## 🚨 门禁防灾条款(v2.31.0 起 · 最高优先级)
  45. > **事故背景**:2026-09-21 钩子超时 → 平台直接 block 用户整条消息
  46. > (`UserPromptSubmit operation blocked by hook: Hook timed out after 15000ms / 20000ms`)。
  47. > 用户发什么都进不来,只能靠改 `hooks.json` 文件名逃生。同类事故此前已多次发生
  48. > (v2.25.1 挂起被杀 / v2.27.0 / v2.27.2 慢机器 6~18s 波动 / v2.27.4 bash 包装层 2.5~12.9s)。
  49. > 结论:**门禁宁可放行,绝不阻塞用户;且必须随时能被一键断电。**
  50. **五条死规则(任何改动不得违反):**
  51. | 规则 | 内容 | 落地位置 |
  52. |---|---|---|
  53. | **R1 拉闸优先** | 拉闸开关存在(文件 `.constitution-off` 或环境变量 `CONSTITUTION_OFF`)→ **任何事件在任何逻辑之前直接放行** | `constitution-gate.py` → `main()` 首行 |
  54. | **R2 异常放行** | 门禁自身任何异常(异常 payload、状态不可读、JSON 损坏)→ **退出码 0**,永不因自身故障拦人 | `main()` 外层捕获 + `state_broken` 分支 |
  55. | **R3 自修复豁免** | 目标落在门禁项目内(`scripts/`、`hooks/`、`tests/` 及 SKILL/README/CHANGELOG)→ 一律放行;**门禁状态文件仍永久禁写**(防伪造通行证) | `self_repair_targeted()` |
  56. | **R4 写失败可见** | 状态写失败必须写 `.constitution-health.log`;**连续 3 次 → 自动拉闸** | `_atomic_write_json()` |
  57. | **R5 耗时预算** | 单次钩子超 9s 记 `slow` 并**自动拉闸**(平台上限 15s);所有子进程调用必须带短 timeout | `main()` 计时 + `subprocess.run(timeout=…)` |
  58. **30 秒拉闸(出任何异常,先做这一步,别去改配置文件):**
  59. ```bash
  60. bash scripts/emergency-off.sh "原因" # 拉闸:全部事件立即放行(纯 bash,不依赖 python)
  61. # …处理问题…
  62. bash scripts/emergency-on.sh # 合闸
  63. python scripts/constitution-doctor.py --fix # 体检 + 自动修复(清卡死违规/删损坏状态)
  64. ```
  65. > 为什么拉闸走文件开关而不是改 `settings.json`:WorkBuddy 平台的钩子是**会话启动时加载**的,
  66. > 改配置当轮不生效(2026-09-21 实测);而开关文件是门禁进程**每次运行都会读**的 → 立刻生效。
  67. **违规记录语义(用户钦定 2026-09-21)**:任务合规即**清零**,并写入 `cleared_ts` / `cleared_task` /
  68. `cleared_reason`。旧版"通过即清除"写在 Stop 分支最末尾,前面三处早返回永远走不到 →
  69. 2026-09-20 那条 `count=3` 挂了一整天,每轮重播。现在结清动作提到**所有早返回之前**。
  70. **发布前置门禁**:`scripts/tests/gate_failsafe.py`(26 项)不全绿 → **禁止发布**;
  71. `scripts/tests/gate_task_boundary.py`(17 项)与既有回归套件同样必须全绿。
  72. ---
  73. ## ⚠️ 前置过滤:任务类型判断(零号条款)
  74. **本宪法仅适用于"专业任务"**,不适用于简单问答。执行前先判断:
  75. | 任务类型 | 特征 | 是否查技能 |
  76. |---------|------|-----------|
  77. | **简单问答** | 翻译、润色、解释概念、一般知识问答 | ❌ 跳过 |
  78. | **纯信息查询** | 上网搜索、查最新版本号/参数、看列表、问「有没有/是多少」 | ❌ 跳过 |
  79. | **专业任务** | 编码、数据抓取、文件操作、API 调用、复杂分析 | ✅ 必须查 |
  80. | **模糊任务** | 未命中任何动作词 | ❌ 跳过(v2.33.0 默认简单) |
  81. **判断标准**:
  82. - 任务**真的会改动本机状态**(写/改/删文件、跑脚本、安装、写代码、部署推送) → 专业任务,必查
  83. - 任务只是**取信息 or 文字处理**(上网搜索、查版本/参数、看列表、问答、解释、翻译) → 简单任务,**直接作答,不查记忆/技能树、不汇报三查**
  84. - **默认简单**:判不准就按简单处理(v2.33.0)。「涉及网络请求」不再单独构成专业任务
  85. **自我豁免**:本宪法本身是元规则,执行宪法条款时**不需要再次查技能**(防止死循环)。
  86. **误判回退(零号条款-C)**:若 Agent 误判任务类型(如把专业任务当作简单问答跳过),用户有权指出("这是专业任务,你应该查技能")。此时 Agent 必须:
  87. 1. 道歉并承认误判
  88. 2. 立即回退到完整宪法流程(从查记忆开始)
  89. 3. 将此次误判记录到记忆层(`MISJUDGMENTS`),避免重复犯错
  90. ---
  91. ## 痛点
  92. Agent 生态最大浪费:装了一堆 Skill 却傻傻硬扛任务,或凭印象乱选、误判能力、从不去搜。本宪法把"查能力→匹配→必用→搜索→推荐"变成强制流程,并用门禁(constitution-check)把"靠自觉"变成"可校验、可拦截"。
  93. ---
  94. ## 核心概念(平台无关)
  95. 本宪法使用以下**通用术语**,各平台的具体对应物见【平台映射表】:
  96. | 通用术语 | 含义 | 各平台叫法举例 |
  97. |----------|------|----------------|
  98. | **能力注册表** | Agent 当前可用的全部技能/工具/插件清单 | available_skills / tools / plugins / extensions / Gems / MCP servers |
  99. | **技能描述** | 每个能力的触发条件说明 | description / trigger / when_to_use / system prompt |
  100. | **技能索引** | 按功能分类的技能树(预生成,加速匹配)。⚠️ 仓库内 `skill_tree.json` 为**作者快照/示例**,使用者应运行 `scripts/build_skill_tree.py` 生成**自己的**索引 | skill_tree.json(作者快照)/ 你生成的技能树 |
  101. | **技能发现** | 搜索可安装的新能力 | find-skills / GPT Store / SkillHub / MCP Registry / Extensions |
  102. | **记忆层** | 跨会话持久化的规则存储 | MEMORY.md / CLAUDE.md / AGENTS.md / Custom Instructions / .cursorrules |
  103. | **技能文件** | 定义能力的结构化文档 | SKILL.md / GPT Actions / MCP Config / Gem Instructions |
  104. ---
  105. ## 宪法条款
  106. ### 第零条:查记忆(Pre-Check Memory)
  107. **在执行任何任务前,必须先查阅该平台的记忆/规则层**,确认有无相关约定、历史上下文或待办事项。
  108. **各平台记忆层路径**:
  109. | 平台 | 记忆层路径 |
  110. |------|-----------|
  111. | WorkBuddy | `~/.workbuddy/MEMORY.md` + 项目 `.workbuddy/memory/` |
  112. | Claude Code | `CLAUDE.md` 或 `.claude/CLAUDE.md` |
  113. | Cursor | `.cursorrules` + `.cursor/rules/` |
  114. | Windsurf | `.windsurfrules` |
  115. | Cline | `.clinerules` |
  116. | ChatGPT | Custom Instructions |
  117. | Gemini | Gem Instructions |
  118. | Codex | AGENTS.md |
  119. | 通用规则 | 项目根目录 `RULES.md` 或 `.agent/rules.md` |
  120. **查记忆顺序**:
  121. 1. 用户级记忆(长期偏好、硬规则)
  122. 2. 项目记忆(当前项目约定、历史决策)
  123. 3. 今日流水(当天工作记录,避免重复)
  124. **记忆层必备内容**(自举前提:让"查记忆"真正发现技能,v2.3.0 新增):
  125. 为了让宪法自举执行,记忆层中应维护以下两类条目:
  126. | 条目 | 内容 | 示例 |
  127. |------|------|------|
  128. | `INSTALLED_SKILLS` | 已安装技能清单(名称 + 一句话描述) | `file-ops:文件读取/写入工具,用于读取技能索引` |
  129. | `SKILL_INDEX_PATH` | 技能索引文件路径(**你**的技能树,非作者快照) | `<你的平台技能目录>/skill_tree.json`(如 `~/.claude/skills/`) |
  130. 示例:
  131. ```markdown
  132. INSTALLED_SKILLS:
  133. - file-ops:文件读取/写入工具,用于读取技能索引
  134. - find-skills:技能搜索工具,用于发现新能力
  135. - agent-memory:记忆管理系统
  136. SKILL_INDEX_PATH: <你的技能目录>/skill_tree.json
  137. ```
  138. 只要按此格式维护记忆层,Agent 查记忆即可"回忆"出技能清单,无需实时扫描,冷启动问题就此解决。
  139. ---
  140. ### 第一条:先查(Pre-Check)
  141. **每次执行专业任务前,必须先查看能力注册表**,判断有没有能力与当前任务相关。
  142. **优化路径**(v2.2.0 新增;v2.7.0 修正指向):
  143. 1. 先查**你的平台能力注册表**(可用技能/工具/插件清单,如 Claude Code `~/.claude/skills`、Cursor `.cursor/rules`、WorkBuddy available_skills);有本地技能树则优先用它(运行 `scripts/build_skill_tree.py` 生成**你自己的**索引)
  144. 2. 按任务类型定位功能分支
  145. 3. 在分支内匹配描述
  146. 4. 未命中则全量扫描(兜底)
  147. **执行强化(v2.5.0 新增,无条件第一步;v2.11.0 强制命中清单)**:
  148. 「先查技能索引」必须是**无条件动作**,不是"我觉得需要才查":
  149. - **任何专业任务(含"查安装/查库"类,如确认某 Python 库是否安装)第一步必须读技能树索引**,禁止以"这不需要查技能"为由跳过——凭判断跳过正是本宪法要防的行为(教训:实际运行中查 cognee 时跳过技能树被用户抓包)
  150. - 技能树索引应包含**技能(独立 + 插件,v2.21.0)与已装 Python 库/工具**(🧩 分类),一个入口查全
  151. - **仅专业任务**开始需**显式汇报「宪法三查」结果**,让流程可见、可被用户监督(简单/信息查询任务豁免,不汇报)。**v2.11.0 强制:②技能树必须列出命中的技能名清单(名称+依据),禁止只写"已读技能树"**:
  152. ```
  153. 【宪法三查】
  154. ① 记忆 ✅ 已查(用户级/项目/今日流水)
  155. ② 技能树 ✅ 已读(命中技能清单:`git-workflow-and-versioning`(代码/部署)、`web-deploy-github`(GitHub 推送)…)
  156. ③ 匹配 ✅ 命中 X → 用它执行;无命中 → 说明"技能树无匹配"再走通用能力/文件系统
  157. ```
  158. - **v2.11.0 任务相关硬校验(Layer C)**:任务含「代码/编码/编程/开发/写一个/实现/git/github/push/commit/deploy/部署/爬虫/抓取/网页/前端/文档/数据/邮件/图片/视频」等关键词时,**输出必须引用 skill_tree.json 对应分类下的实际技能名**(如 `git-workflow-and-versioning`),仅写"已查 skills-constitution"或"已读技能树"而无具体技能名 → 门禁 FAIL
  159. - 简单问答豁免(翻译/润色/概念解释)
  160. **第一条补充 A:注入的技能名录是截断的,判"无匹配"前必须检索全量(v2.27.6 死规则)**
  161. 注入块里每个分类**只显示一小部分技能名**(v2.27.6 起按任务相关度排序取前 8/10 个,行尾会标"未列全")——分类里排第 38 位的技能从名录里是看不见的。2026-09-04 实锤事故:任务"推送到 github 和 gitee",`github-gitee-publish` 就在树里且分类正确,仅因排在 code 类第 38 位没被显示,Agent 便对着那 8 个名字判了"技能树无匹配",被用户抓包。
  162. - **禁止把注入片段里的几个名字当作该分类的全量** —— 那是预览,不是清单
  163. - 判定"技能树无匹配"前,**必须检索全量索引**(二选一,命中即算已查):
  164. ```bash
  165. grep -n "关键词" ~/.workbuddy/skills/skills-constitution/SKILL_TREE.md # 人读版
  166. python -c "import json;d=json.load(open(r'<索引>/skill_tree.json',encoding='utf-8'));print([e['name'] for c in d['categories'].values() for e in c if '关键词' in e['name']+e.get('description','')])"
  167. ```
  168. - 名录行尾标了"未列全"时,上面这一步是**强制**的,不是可选项
  169. - 分类路由也可能退化(任务关键词没命中映射表时会兜底取字母序前几个分类),此时名录里的分类本身就与任务无关 —— 更需要直接按关键词检索全量
  170. **第一条补充 B:检索质量不得凭感觉,必须配对 A/B + 留出集说话(v2.28.0 死规则)**
  171. 检索层(打分 / 分词 / 同义词表 / 分类路由 / 排序)是"该调技能不调技能"防线的上游 —— 上游漏检一次,下游门禁再严也拦不住(候选压根没出现在注入块里)。而检索改动最容易自我欺骗:"我觉得这样更准"。所以定死规矩:
  172. 1. **改任何检索逻辑后,必须跑评测并同时报告两套集**:
  173. ```bash
  174. python scripts/tests/retrieval_eval.py # dev + holdout 双集对照
  175. python scripts/tests/retrieval_eval.py --gate # 门禁:双集 hit@4 均不得跌破下限
  176. ```
  177. 只报 dev 集视为**未验证** —— 本版实测:dev 集被调到 hit@4 100% 时,12 条留出集只有 66.7%。
  178. 2. **留出集禁止用于调参**(`data/retrieval_eval_holdout.json`)。dev 集可据其迭代,留出集只用于验收;反复拿留出集调参 = 换一套用例继续过拟合。
  179. 3. **hit@4 下降即判退化**(`--gate` 会 exit 1),不得以"个别用例看起来更合理"为由放过;要用数字证明,或把该用例的期望值更新为**经人工核验确为同域**的技能(核验依据记在用例文件里)。
  180. 4. **期望值只允许"放宽到真同域",不允许"迁就到算法输出"**。放宽前必须读候选技能的 description 确认它真能干这事(本版对 7 条用例放宽时逐条核验过;例如"发票提金额"补入 `pdf-image-text-extractor__skillhub` 是因为它确实做 OCR 提取)。
  181. 5. **判"无匹配"前记住:用户说的是意图,不是技能名**。"把改好的东西传上去"对应的技能叫 `github-gitee-publish`;中文任务撞上英文 description 的技能是常态(`browser-automation` / `code-review` / `openai-whisper`),检索已内置中英双语技术词桥,但**禁止仅因字面不同就判无匹配**。
  182. ---
  183. **第一条补充 C:模糊指代必须映射确认,"不存在"结论需双通道证据(v2.29.0 死规则)**
  184. 三查防线只验证"查没查技能树",不验证"查得对不对、结论下得对不对"。2026-09-19 实锤事故链(本宪法作者亲历,任务为"更新 github,用 github改版技能"):
  185. 1. **模糊指代望文生义 → 用错技能**:Agent 把「github改版技能」直接配成 `constitution-release`(名字像、场景像)——但用户自建的真身是 `github-gitee-sync`。三查全程"通过",路由照样错。
  186. 2. **单次检索零命中 → 误报"不存在"**:Agent 用 Glob 查 `github-gitee-sync/SKILL.md` 得空,随即断言"该技能未安装";实际它就在库里,换个检索方式(目录名匹配 → description 内容匹配)一次命中。
  187. 3. **类故障不查专项技能 → 徒手硬修**:git 仓库 .git 损坏(refs 消失 + 对象丢失),Agent 手工重建救场——而库里现成的 `git-repo-recovery`(description 与此故障逐字同域)从头到尾没被想起。
  188. 死规则(四条,全部可校验):
  189. - **模糊指代三步映射,禁止望文生义**:用户口述的技能名/别称("github改版技能""推送那个""写文档那个")**禁止直接取"最像的那一个"开跑**。三步:① 在全量索引做**内容级**检索(name 与 description 都搜——目录名匹配漏扫率高,本事故即漏于目录名);② 命中多个或零个候选 → **列出候选(名称 + 一句话依据)请用户确认**;③ 映射不确定时宁可一句"你说的是 X 吗",不许猜。
  190. - **执行前映射回显**:选定技能后、开跑前,回显一行「你说的是「X」→ 我用 `Y`(依据:description 说……)」;用户纠偏即按零号条款-C 处理(回退 + 记 MISJUDGMENTS)。
  191. - **"不存在/未安装"结论需双通道证据**:任何检索(Glob/Grep/ls)零命中后,**必须换检索方式复核**(目录名 → description 内容;精确 pattern → 模糊 pattern;本目录 → 上级目录),两路都零命中才许下"不存在"结论。工具单次失败 ≠ 事实。
  192. - **类故障先查专项技能再动手**:遇到的故障与某技能 description 明确同域时(git 仓库损坏 → `git-repo-recovery`、Windows 文件占用 → `win-file-lock-release`),必须先加载该技能再动手,禁止徒手硬修——专项技能里的坑是前人踩过的,徒手重踩一遍是最贵的学费。
  193. ---
  194. **第一条补充:双机制平台覆盖(v2.21.0)**
  195. ZCode / Claude Code / DeepSeek Harness(dsh) 等平台的能力同时来自**两条平行机制**——独立技能(技能目录下的 SKILL.md)与**插件技能**(插件包内的 SKILL.md)。本宪法所称"能力注册表 / 技能库 / 技能树"**一律同时覆盖两者**:
  196. 1. **同权重**:插件技能与独立技能在"先查 → 匹配必用"流程中地位完全相同,**禁止以"它是插件不是技能"为由绕过匹配**
  197. 2. **完整调用名**:插件技能的调用名通常为 `插件名:技能名`(如 `document-skills:docx`、`computer-use:computer-use`),命中后必须按完整调用名调用(双机制平台上裸技能名可能无法被 Skill 机制加载)
  198. 3. **自动入树**:`build_skill_tree.py` 自动扫描插件缓存编入技能树并标注调用名(已知平台路径自动发现;其他平台用环境变量 `PLUGIN_CACHE_DIRS` 或仓库根 `plugin_roots.json` 指定缓存目录;停用的市场/插件自动排除)
  199. 4. **插件附带能力同规则**:插件提供的斜杠命令 / MCP 工具同样属于"能力注册表",有现成能力时禁止用通用能力重复造轮子
  200. ---
  201. ### 第二条:匹配必用(Mandatory Use)
  202. 只要任务与某个能力的**描述**相关或部分相关 → 无条件优先加载该能力、按其指令执行。
  203. **禁止行为**:
  204. - ❌ 绕开能力直接用通用能力
  205. - ❌ 凭印象选能力不看描述
  206. - ❌ 多个匹配时随机挑一个(应按相关度排序选最优)
  207. **凌驾条款**:即使某个能力说"我可以直接做",也必须先经本宪法确认没有更好匹配的能力。
  208. ---
  209. ### 第三条:无匹配 → 技能发现(Search First)
  210. 确认能力注册表无匹配后,先通过平台的**技能发现机制**搜索是否有可获取的相关能力。
  211. - 找到 → 提示用户安装/启用后使用
  212. - 没找到 → 进入第四条
  213. ---
  214. ### 第四条:能力边界(Honest Boundary)
  215. 感觉"我做不到 / 没权限 / 没工具"时 → **必须先通过技能发现机制确认**,确认无能力可用才能回复做不到。
  216. **禁止行为**:
  217. - ❌ 不搜索就直接说"做不到"
  218. - ❌ 用通用能力硬扛明明需要专业能力的任务
  219. - ❌ 假装做了但实际没调用能力
  220. ---
  221. ### 第五条:答复时自动推荐(Auto-Discovery)
  222. 任务完成后(答复阶段)→ **若本地已装技能未能完美解决任务,优先读本地排行榜快照推荐更优能力**,由用户自行决定是否安装。本地技能不足时"不推荐"是违规。**v2.15.0:推荐候选必须排除本地已装技能**(推荐的是"你没装过的更强能力",已装项一律不推)。**v2.25.0:推荐来源改为「本地排行榜快照优先」,极度省 token —— 每次答复不再全盘搜索 GitHub**。
  223. **触发场景**(满足其一即必须执行):
  224. - 本地技能树查了,但没有完全匹配的技能
  225. - 本地有匹配技能但执行效果不理想(如推送 GitHub 受阻、脚本报错)
  226. - 任务明显超出本地技能范围(如需要专用工具/agent/插件)
  227. **推荐来源(v2.25.0 优先级)**:
  228. 1. **本地排行榜快照(第一优先,零网络、零搜索)**:读 `data/skill_rankings.json`(仓库自带作者快照),跑 `python scripts/recommend_skills.py --task "<任务>"` —— 纯本地匹配关键词 + 按星数排序 + **自动排除本地已装技能**,输出 3 条(每条含 GitHub 链接 + star 数 + 获取方式,天然满足 step5 校验)。
  229. 2. **GitHub 搜索(仅快照无匹配时兜底)**:快照条目与任务零相关时,才用 WebSearch/WebFetch 搜 `github.com` 高 Star 仓库,**并在推荐板块标注"来源: GitHub 搜索"**。
  230. 3. **快照过期处理**:快照超过 `stale_days`(默认 30 天)未更新,推荐时顶部提示运行 `python scripts/update_skill_rankings.py` 刷新 —— **只提示不自动拉取**(省 token)。
  231. **推荐格式**:
  232. ```
  233. 🔍 本次相关技能推荐(来源: 本地排行榜快照 data/skill_rankings.json, 更新于 2026-09-01):
  234. - 名称:xxx — 一句话亮点 + GitHub 链接 + Star 数 + 获取方式(是否要安装由你决定)
  235. (最多 3 个,避免刷屏)
  236. ```
  237. **执行细则(v2.6.0 强化;v2.11.0 修正定位;v2.15.0 排除已装;v2.25.0 快照优先)**:
  238. - **推荐核心**:必须是 **GitHub 高 Star 数** skill/tool/agent 仓库(含 star 数 + 链接 + 获取方式)——这是用户决定是否安装的依据;数据来源优先本地排行榜快照(`recommend_skills.py` 输出),其次 GitHub 搜索
  239. - **省 token 铁律(v2.25.0)**:推荐环节**默认零网络**——只读本地 `data/skill_rankings.json`(约 20KB)跑确定性规则匹配;只有快照缺失或任务与快照零相关时,才允许发起 GitHub 搜索
  240. - **快照刷新(低频)**:`python scripts/update_skill_rankings.py` 从权威排行榜仓库(quemsah/awesome-claude-plugins 等)抓取 Top100 重建快照;建议每次发布会/每周跑一次,平时不跑
  241. - **允许**在推荐前简要说明"本地已查过哪些技能、为何不足"(如"本地已装 `git-workflow-and-versioning` 但网络受阻"),帮助用户理解为什么需要新技能
  242. - **禁止**以"本地已装技能清单"替代推荐(本地技能仅作背景说明)
  243. - **v2.15.0 排除已装(硬性动作)**:推荐前必须先核对本地已装清单(如 `ls ~/.workbuddy/skills/`),**候选仓库若与本地已装技能同名/同源,一律不推**——包括"搜索结果恰好命中已装仓库"的情况(如 addyosmani/agent-skills 已装时不得再推荐)。`recommend_skills.py` 已内置该排除(含 `_<name>-references` 框架标记);GitHub 搜索路径同样必须人工核对。仅可作背景说明("本地已有 X,若需更强可看 Y")。
  244. - 可配合门禁 `constitution-check --step 5` 自动校验推荐板块是否合规(含 `github.com/owner/repo` 链接 + star 数标记 + 获取方式 + **v2.15.0 Layer E 本地已装排除校验** + **v2.25.0 推荐来源标注**:标注"本地排行榜快照"为省 token 最佳实践)
  245. ---
  246. ## 执行闭环(五步)
  247. 任务 → ①判类型(简单问答豁免;专业任务必查)→ ②查记忆 → ③查技能树(按分支定位)→ ④匹配必用/无匹配必搜 → ⑤答复时推荐(排除已装)。
  248. ---
  249. ## 技能树(Skill Tree)
  250. 按功能分类,执行时**按分支定位**,减少扫描范围 80%+:
  251. ```
  252. 技能树/
  253. ├── 📜 元规则类(宪法/安全审计)
  254. ├── 🧠 记忆/知识管理类(个人记忆/项目知识图谱/会话持久化)
  255. ├── 🌐 网络/搜索类(网页自动化/数据抓取/API/搜索)
  256. ├── 💻 开发/编码类(代码生成/审查/测试/构建部署)
  257. ├── 📄 文档处理类(PDF/Word/Excel/PPT/格式转换)
  258. ├── 🖼️ 内容生成类(图像/视频/UI 设计)
  259. ├── 💰 业务专用类(金融/法律/电商营销)
  260. └── 🔧 通用工具类(文件操作/进程管理/环境配置)
  261. ```
  262. **完整索引**:`skill_tree.json` 为作者快照(示例);**使用者安装后必须重建自己的技能树**(完整命令/平台差异/自检见 → Load `reference/skill-tree-guide.md`)。**精选技能**:`registry.json`。
  263. **技能图谱(v2.23.0)**:树是"行政区划"(人为分类),图谱是"自然聚落"(关系驱动)。`build_skill_tree.py` 重建技能树时自动产出 `skill_graph.json`(也可单独跑 `scripts/build_skill_graph.py` 从现有树重建):节点=技能,边= `chains_to`(输出→输入 schema 衔接)/ `co_anchor`(共享实体锚点)/ `alternative`(替代方案),确定性标签传播聚成功能簇(如"代码发布"簇 = git 工作流 + 审查 + 部署)。用途:注入按任务线收窄、门禁 Layer F 图证据、推荐时说明技能间关系。
  264. ### 🧹 定期整理技能库(v2.32.1 · 强制节奏)
  265. **为什么这必须是条款,而不只是好习惯**:索引一旦落后于磁盘,宪法注入的候选就是错的——
  266. **索引不准,等于宪法在主动引导 Agent 犯错。**
  267. **真实事故(2026-10-18)**:用户说「用 GitHub 改版技能」。技能树注入的候选是
  268. `github-gitee-publish` —— **本机根本没有这个技能**(真名 `github-gitee-sync`)。
  269. Agent 加载失败后**静默退化**成通用 `git-workflow-and-versioning`,于是漏掉了改版技能
  270. 第四步「中英双档同步」整步,是用户追问才发现的。事后体检:
  271. | 体检项 | 实测 |
  272. |---|---|
  273. | `skill_tree.json` 内容生成时间 | **2026-09-01**(落后一个半月、8 个版本) |
  274. | 索引记录的 `skills_dir` | `C:\Users\user\.workbuddy\skills` —— **本机不存在的路径** |
  275. | 幽灵条目(索引有、磁盘无) | 893 个 |
  276. | 未收录(磁盘有、索引无) | 584 个 |
  277. | 评测用例外 | 20 条中 **5 条死用例**(expect 全是幽灵名,永远不可能通过) |
  278. | 技能库内混入的备份目录 | 4 个(`*.bak-*` / `*_git_backup`) |
  279. #### 三种触发(满足任一即执行)
  280. | 触发 | 说明 |
  281. |---|---|
  282. | **定期** | 每月一次(建议每月第一个周末) |
  283. | **事件式** | 单次会话内出现 ≥2 次「技能名不存在 / 索引指向失效 / 技能加载不到」→ 立即做 |
  284. | **变更式** | 安装或删除技能 ≥10 个后 |
  285. #### 八项体检(逐项给数字,"已检查"不算)
  286. | # | 检查项 | 判据 | 动作 |
  287. |---|---|---|---|
  288. | 1 | **索引新鲜度** | `skill_tree.json` 的 `generated_at` 距今 > 30 天 | 重建索引 |
  289. | 2 | **索引路径正确** | `skills_dir` 必须等于本机实际技能目录 | 显式设 `SKILLS_DIR` 后重建(曾把 `C:\Users\user\...` 写进索引) |
  290. | 3 | **幽灵条目** | 索引有、磁盘无 | 重建后仍残留 → 查 `skills_dir` 是否指错 |
  291. | 4 | **未收录** | 磁盘有、索引无 | 重建后应消失;仍在 → 该目录多半缺 `SKILL.md` |
  292. | 5 | **作废技能** | 缺 `SKILL.md` / frontmatter 无 `name` 或 `description` / 空目录 | 移出技能库(移到 `~/.workbuddy/backups/`,**不许删**) |
  293. | 6 | **备份目录污染** | `*.bak-*`、`*_git_backup`、`*broken*` 留在 skills 目录内 | 移出(它们会被当技能扫描,污染索引) |
  294. | 7 | **重名冲突** | 两个目录 frontmatter `name` 相同 | 保留新版,另一个改名归档,报告里列出 |
  295. | 8 | **评测用例有效性** | `data/retrieval_eval_cases.json` 的 `expect` 名字必须都在磁盘上 | 死用例换真名;库里确实没有的能力移入 `known_gaps`,**不许删用例掩盖缺口** |
  296. #### 命令
  297. ```bash
  298. cd ~/.workbuddy/skills/skills-constitution
  299. SKILLS_DIR="$HOME/.workbuddy/skills" python scripts/build_skill_tree.py # 重建(务必显式给路径)
  300. python -c "import json;d=json.load(open('skill_tree.json'));print(d['generated_at'],d['total'],d['skills_dir'])"
  301. ```
  302. #### 铁律
  303. - 整理只做**移动 / 归档 / 重建索引**,**不删用户技能**。真要删必须先列清单、用户逐条确认。
  304. - 报告必须带数字(幽灵几个、未收录几个、死用例几条),不许写"已整理完毕"了事。
  305. - 发现索引里出现不存在的技能名 → **同时回报给用户**,因为那正是下次 Agent 踩坑的地方。
  306. ---
  307. ## 快速注入模板
  308. 以下模板可直接复制到各平台的规则/指令/记忆层中:
  309. ```markdown
  310. ## Skills 宪法(Skills Constitution)v2.33.0
  311. 本规则优先级高于全部技能/工具/插件。任何能力调用必须先过这一关。
  312. 执行路径:
  313. 1. 先查记忆:查阅平台记忆层(MEMORY.md/CLAUDE.md 等)确认相关规则
  314. 2. 先查技能:查看技能索引,按任务类型定位功能分支,**输出必须列出命中的技能名清单**
  315. (技能索引含独立技能与插件技能(v2.21.0):命中插件技能按其完整调用名 `插件名:技能名` 调用)
  316. 3. 匹配必用:有匹配则无条件优先使用该能力
  317. 4. 无匹配必搜:先搜索可获取的能力,再考虑通用能力
  318. 5. 能力边界:说"做不到"前必须先搜索确认无能力可用
  319. 6. 答复推荐(v2.25.0 快照优先,极度省 token):本地技能未能完美解决任务时,**优先读本地排行榜快照** `python scripts/recommend_skills.py --task "<任务>"`(零网络、自动排除已装、出 3 条含链接+star+获取方式);快照无匹配时才去 GitHub 搜索;快照过期(>30 天)跑 `python scripts/update_skill_rankings.py` 刷新;**v2.15.0 推荐候选必须排除本地已装技能(先核对本地已装清单,已装项一律不推)**
  320. 违规判定:跳过查记忆/技能清单直接干 / 有匹配但不用 / 未搜索就拒绝 / 查技能树但未列出命中技能名(空头汇报)/ 本地技能不足却不去推荐(快照优先) / **推荐了本地已装技能(v2.15.0,Layer E 校验 FAIL)** / **命中插件技能却以"它是插件"为由绕过(v2.21.0)**
  321. ```
  322. ---
  323. ## 配套要求
  324. **对能力作者**:description 是唯一匹配依据,写准触发条件(何时用我),遵循平台格式,分类准确。
  325. **对框架开发者**:会话启动注入宪法;能力注册表任务前可访问;支持预生成技能索引(skill_tree.json)加速匹配。
  326. ---
  327. ## 与其他规则的关系
  328. ```
  329. 优先级从高到低:
  330. 1. 🔴 系统安全规则(不可违反)
  331. 2. 📜 Skills 宪法(本规则)—— 凌驾于全部技能/工具/插件之上
  332. 3. 🔧 具体能力的执行指令
  333. 4. 🤖 Agent 通用能力
  334. ```
  335. ---
  336. ## 违规判定
  337. 以下行为属于**严重违规**,用户有权要求重做并说明理由:
  338. | 违规行为 | 判定标准 |
  339. |----------|----------|
  340. | 跳过查记忆直接干 | 任务完成但未查阅平台记忆层 |
  341. | 跳过查技能清单直接干 | 任务完成但未加载任何相关能力 |
  342. | 有匹配但不用 | 能力注册表中有匹配能力但未加载 |
  343. | **空头查技能(v2.11.0)** | 只写"已读技能树/已查宪法"但未列出命中的具体技能名,且任务含代码/git/部署等关键词 |
  344. | **查错分支(v2.11.0)** | 任务要求编码/推送,却引用无关分类技能(如文档类) |
  345. | 未搜索就拒绝 | 说"做不到"但未通过技能发现机制确认 |
  346. | **无复盘推荐(v2.11.0;v2.25.0 快照优先)** | 本地技能未能完美解决任务,却未做推荐(优先读本地排行榜快照 `recommend_skills.py`) |
  347. ---
  348. ## 技术边界说明
  349. "无条件启用全部能力"不可行(撑爆上下文)。正确设计是**按描述匹配触发**,本宪法强制该匹配机制不被跳过。技能树索引将全量扫描缩小到目标分支(省 80%+ token);索引由 `build_skill_tree.py` 生成,**禁止手写**(v2.17.0:使用者应在本机运行 `SKILLS_DIR=<技能目录> python scripts/build_skill_tree.py` 生成自己的树,替换作者快照)。
  350. **门禁证据链(v2.22.0)**:门禁(constitution-gate)认两种"三查已完成"证据,满足其一即放行写操作、收尾不重复校验:① 本任务内 `constitution-check --step 1` 真实校验通过(手动路径);② 平台已注入记忆+技能树(注入上下文 ready)**且**本任务内实际调用过命中技能(Skill 调用由门禁自动记录)。同任务内的追加式消息不重置证据;门禁自身的状态/豁免/违规文件禁止被 Agent 篡改(篡改即拦截)。
  351. **插件技能扫描(v2.21.0)**:双机制平台(ZCode / Claude Code / DeepSeek Harness 等)上,技能树同时编入插件缓存里的插件技能——已知平台路径自动发现(ZCode 会进一步按其 config 的插件启用表排除停用项);其他平台用 `PLUGIN_CACHE_DIRS` 环境变量(多个目录用系统路径分隔符)或仓库根 `plugin_roots.json`(`{"cache_dirs": ["..."]}`)指定缓存目录;`PLUGIN_SCAN=0` 可整体关闭。插件条目带 `qualified_name`(完整调用名)字段,pre-hook 注入时自动标注。
  352. **可选增强(默认未启用)**:`scripts/semantic_index.py` 向量语义检索需 `pip install sentence-transformers faiss-cpu`(约 90MB)并 `python scripts/semantic_index.py build` 构建索引;SAD 宽松语义检索(零依赖)已覆盖日常检索,不启用不影响任何主链路功能。
  353. ---
  354. ## 参考文档(按需加载)
  355. - 跨平台适配 / 平台映射表 → Load `reference/platform-mapping.md`
  356. - 安装 / 钩子注册 / 验证 → Load `reference/installation.md`
  357. - 门禁校验机制(constitution-check 用法 / hooks / 设计要点)→ Load `reference/gate-details.md`
  358. - **使用者建技能树指南(完整命令 / 平台差异 / 自检 / FAQ)→ Load `reference/skill-tree-guide.md`**
  359. > 以上为**渐进式披露**:主文件只含核心条款,细节按需加载,控制 token。
  360. ---
  361. ## 贡献指南
  362. 欢迎提交 Issue 和 PR:
  363. - **功能增强**:扩展分类规则、增加平台映射
  364. - **文档优化**:修正表述、增加示例
  365. - **Bug 修复**:分类逻辑、脚本错误
  366. ---
  367. ## License
  368. MIT License — 随意使用、修改、分发。
  369. ---
  370. ## 作者
  371. **jiabaobei** — [GitHub](https://github.com/jiabaobei)
  372. *如果这个规则帮你解决了 Agent 不调用能力的问题,欢迎 ⭐ Star 收藏!*
README.md · README · 531 lines
  1. # Skills Constitution
  2. > **Skills 宪法** —— 凌驾于全部技能/工具之上的元规则,强制 Agent 先查后用、有匹配必用、无匹配必搜。跨平台通用(WorkBuddy / Claude / ChatGPT / Cursor / Gemini / ...)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  4. [![Version](https://img.shields.io/badge/version-2.33.0-blue.svg)](SKILL.md)
  5. [![Skills Indexed](https://img.shields.io/badge/skills__indexed-author__snapshot-green.svg)](SKILL_TREE.md)
  6. **English**: [README_EN.md](README_EN.md)
  7. ## 🚀 快速开始
  8. ### 一键安装(推荐,v2.21.0 全平台分流)
  9. ```bash
  10. git clone https://github.com/jiabaobei/skills-constitution.git
  11. bash skills-constitution/install.sh # 自动探测平台,装完自动重建技能树
  12. ```
  13. 脚本按平台机制自动分流(v2.21.0):
  14. | 平台形态 | 命令 | 效果 |
  15. |---------|------|------|
  16. | 技能目录型(WorkBuddy / Claude Code / ZCode) | `bash install.sh` | 复制 + **自动重建技能树(含插件技能)** + 自检 |
  17. | 同上 + 强制拦截 | `bash install.sh --register-hooks` | 装完自动注册四个宿主钩子(带备份/回滚/幂等) |
  18. | 规则文件型(Cursor / Windsurf / Cline) | `bash install.sh --platform cursor --target-dir <项目>` | 宪法写入规则文件(建议级) |
  19. | 纯注入型(ChatGPT / Gemini / 扣子等) | `bash install.sh --platform prompt` | 自动提取注入模板供粘贴 |
  20. | Windows | `powershell -File install.ps1` | 同技能目录型流程(需真机首验) |
  21. **双机制平台覆盖(v2.21.0)**:ZCode / Claude Code / DeepSeek Harness(dsh) 等平台的能力同时来自「独立技能 + 插件」两条平行通道。技能树重建会自动把**插件缓存里的插件技能**编入索引(ZCode / Claude Code 已知路径自动发现,停用插件自动排除;其他平台用 `PLUGIN_CACHE_DIRS` 环境变量或仓库根 `plugin_roots.json` 接入),插件技能在树中标注完整调用名(如 `document-skills:docx`),宪法条款同步覆盖:**命中插件技能与命中独立技能同权重,必须按完整调用名调用**。
  22. 钩子注册也可以单独跑:`python skills-constitution/scripts/register_hooks.py`(`--dry-run` 预览 / `--uninstall` 移除)。
  23. ### 一键注入(任何平台)
  24. 把下面这段复制到你的 Agent 的规则/指令/记忆层中:
  25. ````markdown
  26. ## Skills 宪法(Skills Constitution)v2.33.0
  27. 本规则优先级高于全部技能/工具/插件。任何能力调用必须先过这一关。
  28. 执行路径:
  29. 1. 先查记忆:查阅平台记忆层(MEMORY.md/CLAUDE.md 等)确认相关规则
  30. 2. 先查技能:查看技能索引,按任务类型定位功能分支,**输出必须列出命中的技能名清单**
  31. (技能索引含独立技能与插件技能(v2.21.0):命中插件技能按其完整调用名 `插件名:技能名` 调用)
  32. 3. 匹配必用:有匹配则无条件优先使用该能力
  33. 4. 无匹配必搜:先搜索可获取的能力,再考虑通用能力
  34. 5. 能力边界:说"做不到"前必须先搜索确认无能力可用
  35. 6. 答复推荐(v2.25.0 快照优先,极度省 token):本地技能未能完美解决任务时,**优先读本地排行榜快照** `python scripts/recommend_skills.py --task "<任务>"`(零网络、自动排除已装、出 3 条含链接+star+获取方式);快照无匹配时才去 GitHub 搜索;快照过期(>30 天)跑 `python scripts/update_skill_rankings.py` 刷新
  36. 双通道(v2.10.0):简单任务(翻译/润色/解释)→ 零号条款豁免直接通用能力;
  37. 专业任务(编码/爬虫/API)→ pre-hook 强制注入记忆+技能树,未汇报【宪法三查】即被拦截。
  38. 任务相关硬校验(v2.11.0):任务含"代码/git/部署"等关键词时,输出必须引用 skill_tree.json
  39. 对应分类的实际技能名(如 `git-workflow-and-versioning`),只写"已查宪法/已读技能树"而无技能名 → FAIL。
  40. 违规判定:跳过查记忆/技能清单直接干 / 有匹配但不用 / 未搜索就拒绝 / 查技能树未列出命中技能名(空头汇报)/ 本地技能不足却不去推荐(v2.25.0 快照优先) / **命中插件技能却以"它是插件"为由绕过(v2.21.0)**
  41. ````
  42. ### WorkBuddy / CodeBuddy
  43. ```bash
  44. # 克隆仓库
  45. git clone https://github.com/jiabaobei/skills-constitution.git
  46. # 安装技能
  47. cp -r skills-constitution ~/.workbuddy/skills/skills-constitution/
  48. # 重建技能树(必做:生成你自己的索引,替换作者快照;完整命令/平台差异见 reference/skill-tree-guide.md)
  49. SKILLS_DIR="$HOME/.workbuddy/skills" python scripts/build_skill_tree.py
  50. ```
  51. ### Claude Code
  52. ```bash
  53. # 用户级
  54. cp -r skills-constitution ~/.claude/skills/skills-constitution/
  55. ```
  56. ### Cursor / Windsurf / Cline
  57. ```bash
  58. # 将宪法写入规则目录
  59. cp SKILL.md .cursor/rules/skills-constitution.md
  60. # 或
  61. cp SKILL.md .windsurfrules
  62. # 或
  63. cp SKILL.md .clinerules
  64. ```
  65. ### ChatGPT / Gemini / 其他
  66. 将【快速注入模板】中的内容复制到:
  67. - ChatGPT → Custom Instructions 或 GPT 的 System Prompt
  68. - Gemini → Gem 的 Instructions
  69. - 其他 → 系统提示词 / 记忆层
  70. ---
  71. ## 📋 宪法条款(v2.18.0)
  72. ### 第零条:任务分类(零号条款)
  73. 前置过滤:简单问答(翻译/润色/解释)→ 跳过查技能;专业任务(编码/爬虫/API)→ 必须查;模糊任务 → 查一下(宁可不放过)。v2.10.0 由 `pre-hook.py --classify` 确定性分类器执行,不依赖 Agent 自觉。
  74. ### 第一条:先查(Pre-Check)
  75. 每次执行专业任务前,查看能力注册表,判断有没有匹配的能力。v2.10.0 由 `pre-hook.py` 任务开始前强制注入记忆+技能树;v2.11.0 强制输出**命中技能名清单**(名称+依据),且任务含代码/git/部署等关键词时硬校验必须命中对应分类技能(Layer C)。
  76. ### 第二条:匹配必用(Mandatory Use)
  77. 有匹配则无条件优先加载该能力,禁止绕开直接用通用能力。v2.11.0:匹配判定必须引用实际技能名(step3 Layer C 校验)。
  78. ### 第三条:无匹配必搜(Search First)
  79. 无匹配时先通过技能发现机制搜索,再考虑通用能力。
  80. ### 第四条:能力边界(Honest Boundary)
  81. 说"做不到"前必须通过技能发现机制确认无能力可用。
  82. ### 第五条:答复推荐(Auto-Discovery)
  83. 本地技能未能完美解决任务时,**优先读本地排行榜快照**(`data/skill_rankings.json`,`python scripts/recommend_skills.py --task "<任务>"` —— 零网络、自动排除已装、出 3 条含 GitHub 链接+star+获取方式);快照与任务零相关时才去 GitHub 搜索并标注来源;本地不足却不去推荐 → 违规(v2.11.0 修正定位;v2.25.0 快照优先省 token)。快照刷新(低频):`python scripts/update_skill_rankings.py`。
  84. ---
  85. ## 🌲 技能树(Skill Tree)
  86. 按功能类型分类全部技能,Agent 执行时**按分支定位**,减少 80% 扫描量:
  87. | 分类 | 说明 | 示例技能 |
  88. |------|------|---------|
  89. | 📜 元规则类 | 宪法、规则定义、安全审计 | `skills-constitution`, `skills-security-check` |
  90. | 🧠 记忆管理类 | 个人记忆、项目知识、会话持久化 | `aiweko-memory-reports`, `agent-memory` |
  91. | 🌐 网络/搜索类 | 网页自动化、数据抓取、API 调用 | `browser-skill`, `agent-browser`, `anysearch` |
  92. | 💻 开发/编码类 | 代码生成、审查、测试、构建 | `code-review`, `pr-review`, `git-ops` |
  93. | 📄 文档处理类 | PDF、Word、Excel、PowerPoint | `pdf`, `docx`, `xlsx`, `pptx` |
  94. | 🖼️ 内容生成类 | 图像、视频、UI 设计 | `agnes-video-generator`, `image-to-ui` |
  95. | 💰 业务专用类 | 金融、法律、电商、营销 | `配网规划评审器`, `wind-finance` |
  96. | 🔧 通用工具类 | 文件操作、进程管理、环境配置 | `file-ops`, `process-manager` |
  97. **完整索引**:仓库内 [SKILL_TREE.md](SKILL_TREE.md) / [skill_tree.json](skill_tree.json) 为**作者快照(示例)**;使用者在自己的环境运行 `scripts/build_skill_tree.py` 生成**自己的**技能树(或用平台自身能力清单)。**安装后必须重建**——完整命令(含 SKILLS_DIR)/平台差异/自检/FAQ 见 `reference/skill-tree-guide.md`
  98. ---
  99. ## 📦 技能注册表(registry.json)
  100. 精选开源技能/工具索引(作者整理),解决"装什么、从哪装"的问题。**按需安装,不打包全量**:
  101. ```bash
  102. # 方式 1:直接 clone 来源仓库,复制技能目录到你的平台技能目录
  103. git clone https://github.com/anthropics/skills.git
  104. cp -r skills/skills/docx ~/.claude/skills/
  105. # 方式 2:用包管理器(gh skill / sk 等)
  106. gh skill install anthropics/skills docx
  107. ```
  108. | 字段 | 说明 |
  109. |------|------|
  110. | `name` | 技能名 |
  111. | `repo` | 来源仓库(`owner/repo`) |
  112. | `path` | 技能在仓库内的目录(可选,以仓库 README 为准) |
  113. | `description` | 一句话功能 |
  114. | `category` | 分类(framework/documents/development/testing/security/discovery/ai-tools) |
  115. 条目均来自真实开源仓库,见 [registry.json](registry.json)。
  116. ---
  117. ## 🎯 解决的痛点
  118. | 痛点 | 表现 | 宪法解决 |
  119. |------|------|---------|
  120. | **不调用** | 装了 100 个技能只用了 3 个 | 强制先查能力清单 |
  121. | **调用幻觉** | 凭印象选技能,不看描述 | 必须匹配 description |
  122. | **调用混乱** | 多个技能都能做,随机挑 | 按相关度排序选最优 |
  123. | **能力误判** | 感觉"做不到"就直接拒绝 | 先搜索确认无能力 |
  124. | **无复盘** | 做完就走,不看有没有更好技能 | 答复时自动推荐 |
  125. | **扫描全量** | 每次任务扫全部技能 | 按技能树分支定位 |
  126. ---
  127. ## 📊 优先级规则
  128. ```
  129. 优先级从高到低:
  130. 1. 🔴 系统安全规则(不可违反)
  131. 2. 📜 Skills 宪法(本规则)—— 凌驾于全部技能/工具/插件之上
  132. 3. 🔧 具体能力的执行指令
  133. 4. 🤖 Agent 通用能力
  134. ```
  135. ---
  136. ## 🔍 执行流程
  137. ```
  138. 任务来了
  139. │
  140. ▼
  141. ┌─────────────────────┐
  142. │ ① 查记忆层 │── 读取平台规则/历史上下文
  143. │ (Pre-Check Memory) │
  144. └─────────────────────┘
  145. │
  146. ▼
  147. ┌─────────────────────┐
  148. │ ② 查技能索引 │── 按任务类型定位分支
  149. │ (Skill Tree Lookup) │
  150. └─────────────────────┘
  151. │
  152. ├── 命中分类 → ③ 加载该分支技能描述
  153. │
  154. └── 未命中 → ④ 全量扫描 description 匹配
  155. ```
  156. ---
  157. ## 📝 违规判定
  158. 以下行为属于**严重违规**,用户有权要求重做并说明理由:
  159. | 违规行为 | 判定标准 |
  160. |----------|----------|
  161. | 跳过查记忆直接干 | 任务完成但未查阅平台记忆层 |
  162. | 跳过查技能清单直接干 | 任务完成但未加载任何相关能力 |
  163. | 有匹配但不用 | 能力注册表中有匹配能力但未加载 |
  164. | 未搜索就拒绝 | 说"做不到"但未通过技能发现机制确认 |
  165. | 无复盘 | 答复时未搜索全网能力库(当任务与能力库明显相关时) |
  166. ---
  167. ## 🔒 门禁自检(v2.6.0 新增;v2.9.0 两层校验;v2.10.0 输入拦截+双通道;v2.11.0 任务相关硬校验;v2.22.0 三查证据链)
  168. 把「靠 Agent 自觉」变成「可校验、可拦截」。5 个 step 独立校验,状态文件链式依赖,默认软校验 + `--strict` 可选阻断。
  169. > ⚠️ **仅适用专业任务**:简单问答(翻译/润色/解释概念)按零号条款跳过,用 `--simple` 声明,不跑门禁。
  170. ### 双通道分流(v2.10.0)+ 任务相关硬校验(v2.11.0)
  171. ```
  172. 任务进入
  173. ├─ pre-hook.py --classify(零号条款确定性分类器)
  174. │ ├─ 简单关键词(翻译/润色/解释/概念)→ 【通道A】跳过门禁,直接通用能力
  175. │ └─ 专业关键词(编码/爬虫/API/文件/部署)→ 【通道B】强制注入校验
  176. │ ├─ v2.11.0: --task 提取任务必需分类(代码/git/部署→code 分类)
  177. │ ├─ 未输出【宪法三查】→ BLOCKED(任务开始前被拦截,exit 1)
  178. │ ├─ 未引用任务对应分类技能名(如 git-workflow-and-versioning)→ BLOCKED
  179. │ └─ 已输出三查 + 已命中任务分类技能 → 继续 step1-5 全量校验
  180. └─ 模糊任务 → 宁可不放过,按通道B处理(零号条款:模糊任务查一下)
  181. ```
  182. ### 用法
  183. ```bash
  184. # 双通道分流(推荐入口):自动判定任务类型
  185. python scripts/constitution-check --classify --input task.txt
  186. # 双通道 + 任务相关硬校验(v2.11.0:专业任务必须引用对应分类技能名)
  187. python scripts/constitution-check --classify --task "推送github代码" --input output.txt --strict
  188. # 输入拦截:先校验开场是否已注入三查,未注入即阻断
  189. python scripts/constitution-check --pre-hook --input output.txt --strict
  190. # 生成注入块(任务开始前喂给 Agent;v2.11.0 含任务必需技能清单)
  191. python scripts/pre-hook.py --task "推送github代码"
  192. # 全量软校验(FAIL 只警告)
  193. python scripts/constitution-check --input output.txt
  194. # 严格模式(FAIL 即阻断,exit 1)
  195. python scripts/constitution-check --input output.txt --strict
  196. # 简单任务豁免(零号条款)
  197. python scripts/constitution-check --simple
  198. # Post-hook 重试循环(v2.9.0:失败自动注入提示重试,最多3次)
  199. python scripts/retry-wrapper.py --input output.txt --max-retries 3
  200. # 单步校验(如推荐板块)
  201. python scripts/constitution-check --step 5 --input output.txt
  202. ```
  203. | Step | 校验内容 | 对应条款 | 版本 |
  204. |------|---------|---------|------|
  205. | classify | 双通道分流:简单/专业/模糊 | 零号条款 | v2.10.0 |
  206. | pre-hook | 输入拦截:开场已注入三查?任务必需技能命中? | 第零/一条 | v2.10.0 / v2.11.0 |
  207. | 1 | 宪法三查已汇报(软+硬+Layer C 任务相关) | 第零/一条 | v2.9.0 / v2.11.0 |
  208. | 2 | 技能树已读或无匹配声明(软+硬+Layer C) | 第一条 | v2.9.0 / v2.11.0 |
  209. | 3 | 命中技能已调用(软+硬+Layer C+Layer F 图证据) | 第二条 | v2.9.0 / v2.11.0 / v2.23.0 |
  210. | 4 | 交付自检(非版本类自动跳过) | 全文件核查 | v2.6.0 |
  211. | 5 | 推荐板块含 GitHub 链接+star 数(软+硬两层) | 第五条 | v2.9.0 |
  212. > ⚠️ 设计边界:脚本是"增强层",宪法正文永远是行为规则兜底。**禁止**把"必须先跑脚本"写进正文——在跑不了脚本的环境会被 Agent 判为"不可满足"而整体跳过宪法。
  213. ### 三查证据链(v2.22.0)
  214. 宿主钩子(`constitution-gate.py`)认两种"三查已完成"证据,满足其一即放行写操作、收尾不重复校验:① 本任务内 `constitution-check --step 1` 真实校验通过;② 平台已注入记忆+技能树(注入上下文 ready)且本任务内实际调用过命中技能(Skill 调用自动记录)。同任务追加式消息不重置证据;门禁自身状态/豁免/违规文件禁止被 Agent 篡改(篡改即拦截)。
  215. ---
  216. ## 📝 改版说明(CHANGELOG 摘要)
  217. ### v2.29.1(2026-09-20)— skill_doctor 白名单修复:框架标记目录不再被误报为损坏技能
  218. - **问题**:`_<name>-references` 是 E2 机制标记"该框架已装"的目录,本就不是技能、没有 `SKILL.md`;而 `skill_doctor.py` 的 `scan()` 只按"有无 SKILL.md"判目录性质 → 把它判成 `missing_skill_md/broken`,本机常年带 1 条假损坏,`--quarantine` 更会把它当损坏技能**移走**、直接破坏 E2 标记
  219. - **改法**:`scan()` 的跳过 guard 增加白名单正则 `^_.*-references$`(与"点开头目录"同等对待)。报告与 `--quarantine` 共用同一份 `findings`,故**单点修复**即同时覆盖「报告误报」与「误隔离」两条路径
  220. - **验证**:本机 `skill_doctor.py` 损坏 **1 → 0**(该目录仍在原位,未被移走);`run_tests.py` 新增 2 条断言(第 11b 节)——一条钉白名单生效,一条钉真损坏仍照常报(防白名单过宽)
  221. ### v2.29.0(2026-09-19)— 技能路由与检索结论可靠性加固:让 Agent 用对技能、下对结论
  222. - **起因**:一次真实任务连犯三错——①「github改版技能」被望文生义错配成 `constitution-release`(真身是 `github-gitee-sync`);② Glob 查 `github-gitee-sync` 零命中就断言"未安装"(实际在库,换 description 内容级检索一次命中);③ git 仓库损坏徒手硬修,库内现成的 `git-repo-recovery` 从未被想起。复盘发现:三查防线只验证"查没查",不验证"查得对不对、结论下得对不对"
  223. - **新增死规则(SKILL.md 第一条补充 C,四条)**:
  224. **① 模糊指代三步映射,禁止望文生义**——全量索引内容级检索(name+description 都搜)→ 命中多/零个候选列出来请用户确认 → 执行前回显「你说的是「X」→ 我用 `Y`(依据)」,映射不定宁可问,不许猜;
  225. **② "不存在/未安装"结论需双通道证据**——任何检索零命中后必须换方式复核(目录名 → description 内容、精确 → 模糊、本级 → 上级),两路皆空才许下结论;
  226. **③ 类故障先查专项技能再动手**——故障与某技能 description 同域时(git 损坏 → `git-repo-recovery`)必须先加载该技能,禁止徒手硬修
  227. - **零代码改动**,纯规则文本;回归 `run_tests.py` 本机 139/140(唯一 FAIL 为检索门禁,经干净克隆对照实测证为环境差异:门禁按作者池 1084 技能校准,本机池 625,非本版引入;干净克隆上门禁通过 holdout hit@4 100%)
  228. ### v2.28.1(2026-09-15)— 安装脚本真机修复:装不上 + 可能装丢数据
  229. - **① `install.ps1` 无 UTF-8 BOM** → Windows PowerShell 5.1 按系统 ANSI 码页(简中 GBK)读含中文/emoji 的脚本,多字节序列被误读成引号与花括号,报「表达式或语句中包含意外的标记"}"」,**一行都跑不完**。改为带 BOM 存盘;同仓库另两个 `.ps1`(`hooks/session-start.ps1`、`scripts/update.ps1`)同类问题一并补上
  230. - **② 覆盖安装用删除**:旧实现 `Remove-Item -Recurse -Force`(`install.sh` 里 `rm -rf`)先删目标目录再复制。删除一旦被宿主环境的安全护栏拦下(回收站保护 / 句柄占用 / 沙箱拦截),就变成「旧版已被移走、新版又没落盘」,**用户技能目录被清空**——真机实测复现,靠事先手动备份才没出事
  231. - **改法**:先**原地改名备份** `skills-constitution.bak-<时间戳>` 再复制新版。改名是原子操作、可回滚,失败只报错退出;末尾打印备份路径,确认新版可用后由用户自行清理
  232. - **固化为脚本硬约束**:安装脚本**绝不执行删除用户数据的动作**(要腾位置就改名);只搬运技能目录,**绝不触碰任何记忆文件**;零外部依赖
  233. ### v2.28.0(2026-09-10)— 技能检索质量重构:双路证据召回 + RRF 融合 + 配对评测纪律
  234. - **起因**:借鉴 zg「多路召回 + RRF + 配对评测」方法论回查检索层,拿配对 A/B 一量就露馅 —— 旧打分器在 20 条任务上 **hit@4 只有 45%**
  235. - **根因**:`overlap_score` 既无长度归一化也无停用词 → 描述"又长又万能"的技能霸榜(撞掉的正是 `browser-automation`/`code-review`/`ponytail` 这类描述简短或纯英文的技能);分词还会吐出"个转/份汇/价和"这类跨词边界假词
  236. - **改造**:① 单一打分 → **双路证据召回 + RRF 融合**(名称路 = 词面命中技能名;描述路 = BM25 词频×IDF×长度归一化;按排名融合、零调参);② 分词修噪(纯虚词表 / 弱义字表分离);③ 新增**跨语言技术词桥**(技能库双语,任务中文而大量技能描述是英文,词面交集恒为空 —— 用确定性词桥作"语义通道"的零依赖替代)
  237. - **评测纪律(最关键的一环)**:新增 `scripts/tests/retrieval_eval.py` 配对 A/B + **12 条开发期从未调参的留出集**;实测把 dev 集调到 hit@4 100% 后,留出集只剩 66.7% —— **过拟合被当场抓出**,据此再补词桥回到 100%。评测已入回归门禁(`run_tests` 第 14 节),测试 **134 → 140 条**
  238. - **实测(技能池 1084)**:dev hit@4 45% → **100%**、hit@1 25% → 50%;holdout hit@4 66.7% → **100%**、hit@1 41.7% → 66.7%;同时平均候选数保持 4.00、Top1 注入字符反而减少约 16%(命中率涨、token 不涨)
  239. - **明确未采纳**:向量/embedding 语义索引(违背零依赖 + 省 token 基调);把"分类路由"当一路召回(实测降分 —— 路由是**策略**不是**证据**)
  240. ### v2.26.0(2026-09-02)— 一键更新脚本:下载最新版 → 校验 → 自动安装
  241. - **新增 `scripts/update.sh` / `scripts/update.ps1`**:把「更新前先去 GitHub 下载最新版、更新完成后自动在本地安装最新版」固化为死规矩脚本
  242. - **流程**:下载最新 main 包(codeload 主 + api 备双保险)→ 完整性校验(必须可解压且含 SKILL.md,半残包保持旧版、不毁旧装)→ 透传参数跑**新版**安装器自动安装(`install.sh` / `install.ps1`,`--platform` / `--skills-dir` / `--register-hooks` 等原样透传)→ 成功自动清理临时目录
  243. - **实测**:`bash scripts/update.sh --platform claude --skills-dir <临时目录>` 全链路通过(下载 2.25.1 → 校验 → 安装产物齐全)
  244. ### v2.25.1(2026-09-02)— 钩子挂起修复:WorkBuddy 20s 强杀不再卡死任务
  245. - **起因**:Windows 上 `python`/`python3` 可能是 Microsoft Store 占位别名(启动即挂起);旧版钩子解释器检测只查存在不真跑,钩子里每次 python 调用都挂起,叠加数次超过宿主 20000ms 超时,`UserPromptSubmit` 被强杀、任务卡死
  246. - **解释器存活探针**:`user-prompt-submit.sh` / `session-start.sh` 探测 python3/python/py 时真跑 `timeout 3 <py> -c pass`,超时视为不可用并降级(走 bash 兜底/放行),不再使用挂起的解释器
  247. - **两处阻塞点加限**:stdin 读取加 `read -t 2`(宿主不关输入通道也不无限等);自愈重跑 SessionStart 加 `timeout 10`(嵌套钩子挂起不拖垮整体)
  248. - **fail-open 纪律不变**:全链路不可用时降级放行,钩子永不卡任务;实测最坏(三个解释器全挂)9s 降级放行,正常环境 0.2s
  249. ### v2.25.0(2026-09-01)— 第五条「答复推荐」极度省 token 改造:本地排行榜快照
  250. - **推荐来源改为「本地排行榜快照优先」**:新增 `data/skill_rankings.json`(作者快照)+ `scripts/recommend_skills.py` —— 推荐环节纯本地零网络(约 20KB 快照 + 确定性规则),任务关键词匹配 → 排除已装 → 星数排序 → 出 3 条(含 GitHub 链接 + star + 获取方式,天然满足 step5 校验)
  251. - **快照刷新(低频)**:新增 `scripts/update_skill_rankings.py`,从权威排行榜仓库 quemsah/awesome-claude-plugins(索引 3.6 万+ 仓库,2026-08-31 更新)抓取 Top100 重建快照;离线可用 `--input README.md` 解析;网络失败不覆盖旧快照
  252. - **快照过期只提示不自动拉取**:超过 `stale_days`(默认 30 天)推荐时顶部提示刷新命令,绝不自动发起网络请求
  253. - **step5 新增推荐来源标注软校验**:标注"本地排行榜快照"= 省 token 最佳实践;标注"GitHub 搜索"给出改用快照提示;未标注不判 FAIL(兼容旧 Agent)
  254. - **排除已装与 step5 Layer E 口径一致**:`recommend_skills.py` 内置 E1(目录同名)+ E2(`_<name>-references` 框架标记,如 `_agent-skills-references` → agent-skills 不推)
  255. - **实测**:`--task "帮我写 PPT"` → open-design/ppt-master/superpowers;`--task "code review"` → open-code-review 等;中文任务零命中 → 按星数回退 Top3
  256. ### v2.24.0(2026-09-01)— 隐形技能治理 + 门禁「一次三查全程放行」+ 轻量索引
  257. - **块标量解析修复**:`parse_frontmatter` 支持 YAML 块标量(`>`/`|` 及变体)——旧版把 ponytail 全套等 137 个技能描述解析成单个 `>`,检索永不命中;修复后 ponytail 描述 1→825 字符,code 分类 132→164
  258. - **索引描述上限 200→2000**:触发词(ponytail lazy mode 在第 400+ 字符)不再被截断
  259. - **门禁任务级通行证**:任务开始时三查通过(注入/step1 PASS)即全程放行,拦截前移为一次性提醒(用户要求:开始已三查,中途不得再拦)
  260. - **新增 `scripts/skill_doctor.py`**:隐形/损坏技能 8 类诊断 + `--fix` + `--quarantine` + `--emit-min-index` 轻量索引(约 20% 体积,冷门技能省 token 仍可命中)
  261. - **图谱巨簇回归**:锚点固定前 200 字符 + 停用词三批扩容 + DF 0.05→0.035,752 节点巨簇恢复 ≤80 纪律,回归测试 106/106
  262. ### v2.23.0(2026-09-01)— 技能图谱:技能树之上的确定性关系图(GitNexus 启发)
  263. - **技能图谱 `skill_graph.json`**:重建技能树时自动产出(也可单跑 `scripts/build_skill_graph.py`)。三种边全部零依赖确定性抽取:`chains_to`(registry 输出→输入 schema 交集,原 step4 临时数据固化成图)/ `co_anchor`(共享实体锚点——含套话停用词表 + 文档频率过滤,实测滤掉 268 节点巨簇)/ `alternative`(同分类高重叠替代方案)
  264. - **确定性标签传播聚类**(GitNexus 社区检测的零依赖简化形):技能聚成功能簇(如 code/browser/word/email/部署线);**纪律**:替代边不并簇、不做门禁放行凭证,只有结构边参与聚类和连通判断
  265. - **注入按任务线收窄(省 token)**:注入块新增「🕸️ 技能图谱」段——任务锚点技能(SAD 排名精选)的同簇+一跳邻居,每条带"为什么相关"的边证据;轮转填充防单簇吃光预算
  266. - **门禁 Layer F 图证据校验(step3)**:任务含必需关键词时,引用的技能必须与任务锚点图谱连通(同簇/结构边一跳),零连通带簇归属证据判 FAIL(溯源);图缺失/引用不在图中 → 降级放行不误杀
  267. - **作者快照图谱**:独立 457 节点 / 737 边 / 25 簇(最大簇 46)
  268. - **测试组 10**(22 条):锚点抽取/三种边/聚类纪律/确定性复现/门禁图证据/注入集成,全量 99 条零回归
  269. ### v2.22.0(2026-09-01)— 门禁双向修正:防绕过 + 防干扰 + 省 token
  270. - **防绕过(门禁被骗)**:门禁自身状态文件(三查记录 / 豁免旗标 / 违规记录 / 注入上下文)禁止被 Agent 经 Write/Edit/Bash(重定向/tee/rm/mv/sed -i)篡改——旧版写一个豁免旗标文件即可全局豁免;Bash 写文件检测补 `sed -i`;step1 只认 `level=PASS` 的真实校验结果
  271. - **防干扰(门禁误拦)**:门禁认可「平台已注入记忆+技能树 + 本任务内实际调用过技能」为完整三查证据链(Skill 调用自动记录),不再强求手动跑校验命令;同一任务的追加式消息(继续/好的/下一步…)不重置门禁;收尾阶段对已有证据链的任务不再重复文本校验、不再误记违规
  272. - **注入自愈**:`user-prompt-submit.sh` 注入上下文缺失/过期时现场重跑 SessionStart 注入(幂等),不再直接【宪法拦截】挡任务
  273. - **省 token**:注入块默认瘦身约 30%(SAD 候选 6→4、描述截断 60→40 字、每分类清单 12→8、记忆片段 1200→900 字、执行要求文案精简);`hooks.json` 约 8KB 关键词 matcher 精简为 `.*`(分类在 hook 脚本内做);SKILL.md 顶部多版本史压缩为一行移入 CHANGELOG
  274. - **测试组 9**(19 条):门禁文件保护 / 写检测 / 追加式消息 / 证据链放行 / 瘦身断言,全量 77 条零回归
  275. - 端到端实测:无证据写文件被拦、篡改豁免旗标被拦、注入+调用技能后放行、追加消息不重置、收尾不误记违规,全部符合预期
  276. ### v2.21.0(2026-08-30)— 双机制平台覆盖:技能 + 插件
  277. - **能力注册表 = 独立技能 ∪ 插件技能**:ZCode / Claude Code / DeepSeek Harness(dsh) 等平台的能力来自两条平行机制,宪法条款(第一条补充)明确插件技能与独立技能同权重、命中必按完整调用名(`插件名:技能名`)调用,禁止以"它是插件"为由绕过
  278. - **`build_skill_tree.py` 布局无关插件扫描**:已知平台路径自动发现(ZCode 含启用表过滤——config 里停用的插件不入树,`.DISABLED` 市场整棵跳过,打包层目录如 `payload/` 不干扰插件名推导);其他平台用 `PLUGIN_CACHE_DIRS` 环境变量或仓库根 `plugin_roots.json` 免改代码接入
  279. - **pre-hook 注入升级**:注入块与 SAD 候选展示插件技能完整调用名,`load_skill_aliases()` 输出调用名映射
  280. - **install.sh/ps1 技能目录型新增 ZCode**(自动探测顺序 WorkBuddy > ZCode > Claude Code),自检口径改"独立+插件"
  281. - **测试组 8**(18 条):布局无关扫描/版本去重/停用过滤/打包层/入树集成/调用名渲染/环境变量接入,全量 58 条零回归
  282. - 本机实测:ZCode 插件缓存扫描 15 个启用插件技能入树(`document-skills:docx` 等),沙箱安装 `--platform zcode` 全流程通过
  283. ### v2.20.0(2026-08-26)— 安装全平台分流 + 钩子自动注册
  284. - **install.sh 按平台机制分流**:技能目录型自动重建树 / 规则文件型(Cursor/Windsurf/Cline)写入规则文件 / 注入型自动提取模板;新增 Windows 版 `install.ps1`
  285. - **`register_hooks.py` 一条命令注册双平台钩子**:带备份/回滚/幂等/卸载,50 行手工配置成为历史
  286. ### v2.19.0(2026-08-26)— 校验层防伪造升级
  287. - **词边界匹配 + 废除分类名兜底 + 证据白名单**:一个 `"encoded"` 子串打穿 Layer C 的漏洞被堵死,糊弄向量固化进 CI 对抗测试
  288. - **修复新装用户死锁/崩溃**,gate 拦 Bash 写文件,retry-wrapper 废除无效自我重试
  289. ### v2.18.0(2026-08-24)— 使用者建技能树指南
  290. - **新增 `reference/skill-tree-guide.md`**:为什么必须重建 / 完整命令(SKILLS_DIR+BINARIES_DIR,四平台)/ 3 步自检 / 5 条 FAQ
  291. - **重建命令统一带 SKILLS_DIR**(README / installation 原裸命令会扫默认目录),SKILL.md 技能树章节改"安装后必须重建"
  292. ### v2.17.0(2026-08-24)— 技能树重建 + 注入记忆瘦身
  293. - **技能树重建**:本机跑 `build_skill_tree.py`,**402 → 757 技能全入库**(替换 HUAWEI 快照,`skills_dir` 指向本机),修"查树即无匹配"
  294. - **注入块记忆瘦身**:`extract_memory_relevant` 按任务相关性注入(铁律+top2 相关 section),**MEMORY.md 42KB → 注入 ~1KB**
  295. - **semantic_index 明确可选(默认未启用)**:三处文档标注启用方式(sentence-transformers + faiss-cpu,约 90MB)
  296. ### v2.16.0(2026-08-24)— Token 瘦身
  297. - **description 瘦身**:2069 字符 → ~415 字符,版本历史移出(放 CHANGELOG),只留触发条件——每次对话省 ~1.8K token
  298. - **SKILL.md 渐进式披露**:平台映射表/安装验证/门禁详解拆 `reference/` 三文件,主文件 682 行/42KB → 327 行/8.4KB(省 80%),契约式引用按需加载
  299. - **修复 injected-context.json JSON 转义**(heredoc 反斜杠导致钩子误报"宪法拦截"),改用 json.dump
  300. - 注入去重确认:SessionStart 注入一次,无重复
  301. ### v2.15.0(2026-08-24)— 推荐排除已装技能
  302. - **第五条补硬性条款**:"推荐候选必须排除本地已装技能"——推荐前先核对本地已装清单(`ls ~/.workbuddy/skills/`),已装项一律不推(含"搜索结果恰好命中已装仓库"场景),仅可作背景说明
  303. - **step5-check.py 新增 Layer E 本地已装排除校验**:推荐仓库名与本地技能目录同名(E1)或与本地 `_<name>-references` 已装框架标记匹配(E2)→ FAIL。修复真实案例:addyosmani/agent-skills 已装 24 技能仍被列入推荐
  304. - **违规判定新增**:"推荐了本地已装技能(Layer E 校验 FAIL)"
  305. - AGENTS.md / 快速注入模板 / README 模板同步
  306. ### v2.14.0(2026-08-24)— 假查漏洞修复 + 跨机器可用
  307. - **constitution-gate.py 回归**:作为 WorkBuddy settings.json 钩子的正式实现(UserPromptSubmit / PreToolUse / Stop 三事件),补齐 v2.13.x 缺的 WorkBuddy 宿主钩子
  308. - **PreToolUse 新鲜度校验**:step1 的 ts 必须 ≥ 本任务 UserPromptSubmit 写入的 reset_ts,旧任务 PASS 不再赦免任何 Write/Edit(修复"一次 PASS 永久放行")
  309. - **Stop 违规硬记录**:最终回复未含【宪法三查】+ 任务相关技能名(Layer C)→ 写入 `.constitution-violations.json` 累计计数 + stderr 警告
  310. - **UserPromptSubmit 违规警告注入**:有违规记录时输出到 stdout(平台注入 Agent 上下文),下个任务开头 Agent 即见警告,形成"事前拦 + 事后记 + 下次警"闭环
  311. - **去掉 HUAWEI 硬编码**:`hooks/session-start.sh`、`hooks/user-prompt-submit.sh`、SKILL.md frontmatter 三处改为环境变量 `CODEBUDDY_PLUGIN_ROOT` 优先 + 脚本自定位兜底(定位失败报错/放行),跨机器不再静默失效
  312. - **WorkBuddy 注册文档**:SKILL.md 安装章节新增 settings.json 三步注册示例(SessionStart / UserPromptSubmit / PreToolUse / Stop)
  313. ### v2.13.3(2026-08-21)— 失败可定位 + 兜底文案动态化
  314. - **python 分支 stderr 不再被丢弃**:捕获进 `debug.pre_hook_stderr`(injected-context.json),失败原因可定位
  315. - **兜底文案按真实原因动态化**:`fallback_reason` 区分「无 python」vs「python 分支失败」,bash 降级时给用户准确提示
  316. - **injected-context.json 新增字段**:`python_branch_ok` / `fallback_reason`,供 UserPromptSubmit 钩子诊断
  317. - 技能树索引重建:total=402
  318. ### v2.13.2(2026-08-21)— hooks 执行链路三大根因修复 + 版本号修正
  319. - **解释器检测修复**:`python3/python/py` 逐个尝试,不再硬编码 python3(hook 环境 PATH 无 python3 导致 skill_tree.json 计数归零)
  320. - **注入块输出到 stdout**:pre-hook.py 生成的完整注入块改为输出到 stdout,平台才能注入 Agent 上下文(此前只有统计行,无任何可执行内容)
  321. - **版本号修正**:SKILL.md frontmatter / description_zh / description_en 三处版本标注统一为 v2.13.2
  322. - 技能树索引重建:total=401
  323. ### v2.13.0(2026-08-21)— hooks 强制拦截上线
  324. - **hooks.json 注册钩子**:`SessionStart`(启动注入)+ `UserPromptSubmit`(提交校验),WorkBuddy settings.json 一键注册
  325. - **Ruler 跨平台分发**:一键将宪法安装到 10 个主流平台(Claude Code / Cursor / Windsurf / Cline / ChatGPT / Gemini / WorkBuddy / 扣子 / 文心 / 通义)
  326. - **pre-hook --task 参数修复**:`bash user-prompt-submit.sh "$USER_PROMPT"` 支持直接传参(不再依赖 stdin JSON)
  327. - **Windows 路径转换**:`to_win()` 函数将 Git Bash `/c/...` → `C:/...`,解决 python 在 Windows 下不认 `/c/` 路径的问题
  328. - 完整细节见 [CHANGELOG.md](CHANGELOG.md)
  329. ### v2.12.0(2026-08-19)— SkillWeaver 启发:语义增强 + 防蒙混升级
  330. - **任务同义词扩展**(`TASK_SYNONYM_MAP`):口语表达不再漏判——"我要把代码传上去"(无 git 关键词)也能命中 code 必需分类,Layer C 恢复生效
  331. - **SAD 宽松语义检索**:SkillWeaver 反馈循环的确定性实现——pre-hook 按 token 重叠度(零依赖)检索 top-K 候选技能注入,Agent 起草方案时带着候选完成用词对齐,token 再降一档
  332. - **Layer D 语义相关性校验**(step3):引用的技能必须与任务语义相关(overlap ≥ 0.10),杜绝"引用真实存在但与任务无关的技能"蒙混过关
  333. - **多技能编排兼容性检查**(step4 + registry.json schema):识别技能链 `A → B`,校验相邻技能 output→input 兼容
  334. - **可选语义向量索引**(`scripts/semantic_index.py`):sentence-transformers + FAISS 的完整实现作为可选增强层;缺依赖明确提示,主链路永远零依赖。**⚠️ v2.17.0 明确标注:默认未启用**——需要者自行 `pip install sentence-transformers faiss-cpu`(约 90MB)后运行 `python scripts/semantic_index.py build`;不启用不影响任何主链路功能(SAD 宽松语义检索为零依赖确定性实现,已覆盖检索需求)
  335. - **分类子串误杀修复**:英文关键词改词边界匹配,`code` 不再误杀 `encode`、`search` 不再误杀 `research`
  336. - 顺手修复 4 个已核实 Bug(正文版本号残留/CHANGELOG 链接/CI 死代码/badge 失真)
  337. - 完整细节见 [CHANGELOG.md](CHANGELOG.md)
  338. ### v2.11.0(2026-08-16)— 任务相关硬校验(Layer C)+ 命中清单强制 + 推荐定位修正
  339. - **新增 Layer C 任务相关硬校验**:任务含"代码/编码/编程/开发/写一个/实现/git/github/push/commit/deploy/部署/爬虫/抓取/网页/前端/文档/数据/邮件/图片/视频"等关键词时,输出必须引用 skill_tree.json 对应分类下的**实际技能名**(如 `git-workflow-and-versioning`)——彻底杜绝"查了 skills-constitution 就算查了技能"的空头汇报
  340. - **三查汇报强制命中清单**:②技能树必须列出命中的技能名(名称+依据),禁止只写"已读技能树"
  341. - **pre-hook.py 增强**:新增 `required_categories_for_task()` / `required_skills_for_task()` 确定性映射(任务关键词→必需分类→候选技能),注入块自动附加「任务必需技能」清单
  342. - **step1/2/3 增加 Layer C**:未引用任务对应分类技能名 → FAIL;constitution-check 新增 `--task` 参数
  343. - **第五条推荐定位修正**:本地技能未能完美解决任务时,必须去 GitHub 搜索高 Star 技能推荐给用户(含链接+star+获取方式),由用户自行决定是否安装;本地不足却不去搜索 → 违规
  344. - 完整细节见 [CHANGELOG.md](CHANGELOG.md)
  345. ### v2.10.0(2026-08-16)— 输入拦截 + 双通道执行
  346. - **新增 `pre-hook.py`**:任务开始前强制读取 MEMORY.md + skill_tree.json 生成注入块,Agent 上下文"被迫"已有记忆规则和技能树分类
  347. - **双通道分流**:`--classify` 确定性分类器(零号条款协调)——简单任务(翻译/润色/解释)→ 通道A 零号条款豁免直接通用能力;专业任务(编码/爬虫/API)→ 通道B 强制注入校验 + step1-5 全量校验;模糊任务 → 宁可不放过按通道B
  348. - **关键设计**:分类器是确定性代码,不依赖 Agent 自觉判断任务类型,杜绝"把专业任务误判为简单任务"逃逸
  349. - 完整细节见 [CHANGELOG.md](CHANGELOG.md)
  350. ### v2.9.0(2026-08-16)— 三明治架构两层校验
  351. - **Pre-hook 层**:Step1/2 硬校验,验证回复是否真实引用 MEMORY.md / skill_tree.json 内容(杜绝空头汇报)
  352. - **Post-hook 层**:`retry-wrapper.py` 重试循环,失败自动注入错误提示并重试(最多3次),超限转人工
  353. - **两层校验**:软校验(文本关键词)+ 硬校验(验证实际文件内容引用)
  354. ---
  355. ## 🏗️ 项目结构
  356. ```
  357. skills-constitution/
  358. ├── SKILL.md # 宪法文档(主文件)
  359. ├── README.md # 本文件
  360. ├── CHANGELOG.md # 版本日志
  361. ├── SKILL_TREE.md # 技能树索引(人类可读)
  362. ├── skill_tree.json # 技能树索引(机器可读)
  363. ├── skill_graph.json # 技能图谱(v2.23.0:边+簇,随技能树重建)
  364. ├── scripts/
  365. │ ├── build_skill_tree.py # 分类脚本(v2.12.0 词边界匹配修复子串误杀;v2.21.0 插件技能扫描;v2.23.0 顺带重建图谱)
  366. │ ├── build_skill_graph.py # 技能图谱重建(从现有树+registry,v2.23.0)
  367. │ ├── pre-hook.py # 输入拦截+任务分类器(v2.10.0);任务必需技能映射(v2.11.0);同义词扩展+SAD 宽松检索(v2.12.0);插件技能完整调用名注入(v2.21.0);图谱候选注入(v2.23.0)
  368. │ ├── semantic_index.py # 可选语义向量索引(v2.12.0,sentence-transformers 可选依赖)
  369. │ ├── constitution-check # 门禁校验主入口(v2.6.0;v2.10.0 支持 --classify/--pre-hook;v2.11.0 支持 --task)
  370. │ ├── retry-wrapper.py # Post-hook 重试循环(v2.9.0)
  371. │ ├── steps/ # 5 个 step 独立校验脚本
  372. │ │ ├── step1-check.py # 三查汇报(软+硬+Layer C 任务相关,v2.11.0)
  373. │ │ ├── step2-check.py # 技能树已读(软+硬+Layer C,v2.11.0)
  374. │ │ ├── step3-check.py # 技能调用(软+硬+Layer C+Layer D 语义相关+Layer F 图证据,v2.23.0)
  375. │ │ ├── step4-check.py # 交付自检+多技能编排兼容性(v2.12.0)
  376. │ │ └── step5-check.py # 推荐板块(软+硬两层)
  377. │ ├── tests/
  378. │ │ └── run_tests.py # 零依赖回归测试(v2.12.0,CI 可跑)
  379. │ └── lib/ # 状态文件 + 文本工具 + 图谱(v2.23.0 graph.py)
  380. └── .github/
  381. └── workflows/
  382. └── build-skill-tree.yml # 自动更新
  383. ```
  384. ---
  385. ## 📚 平台适配指南
  386. 详细适配指南见 [SKILL.md](SKILL.md) 中的【平台映射表】章节。
  387. ### 支持的框架
  388. - **国际**:ChatGPT, Claude, Codex, Gemini, Cursor, Windsurf, Cline, GitHub Copilot
  389. - **国内**:WorkBuddy, 扣子 (Coze), 文心一言, 通义千问, Kimi, 豆包, 智谱, 月之暗面, Dify
  390. - **双机制平台(技能 + 插件,v2.21.0 完整覆盖)**:ZCode, Claude Code, DeepSeek Harness (dsh)
  391. ---
  392. ## 🤝 贡献
  393. 欢迎提交 Issue 和 PR:
  394. - **功能增强**:扩展分类规则、增加平台映射
  395. - **文档优化**:修正表述、增加示例
  396. - **Bug 修复**:分类逻辑、脚本错误
  397. ---
  398. ## 📄 License
  399. [MIT License](LICENSE) — 随意使用、修改、分发。
  400. ---
  401. ## 👤 作者
  402. **jiabaobei** — [GitHub](https://github.com/jiabaobei)
  403. *如果这个规则帮你解决了 Agent 不调用能力的问题,欢迎 ⭐ Star 收藏,转发给身边被 Agent 气到的朋友!*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.