【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址https://gitcode.com/gh_mirrors/re/repowise点击查看免费下载Repowise 通过 MCP 与 CLI 为 AI 编程助手提供代码库智能而这份智能落地的载体是同时面向 Claude Code 与 Codex 两套 Agent 宿主分发的技能Skills与斜杠命令Slash Commands。plugins/shared/正是这两套插件内容的唯一事实源single source of truth所有技能正文、命令正文都在这里以「一个条目一个文件」的格式编写再由一个渲染器按宿主差异生成到各自的安装目录。本文以 plugins/shared/README.md 为核心骨架结合仓库中的生成器源码与黄金测试讲解这套单源渲染机制的格式约定、宿主差异处理、漂移防护与维护工作流读完你可以安全地新增、修改或下线任意一条技能或命令。为什么需要单源一次已经真实发生过的漂移plugins/shared/的存在源于一次具体事故。在引入共享源之前plugins/codex/skills/是plugins/claude-code/skills/的手抄副本而两侧已经悄悄分叉描述被逐条改写description 是面向各自宿主调度器的触发文本标题被重新命名例如 Dead Code CleanupWithRepowise 与 …withRepowise 的大小写差异一个目录被改名。最致命的是没有任何机制检测到这些差异——正如 README 所说两个用不同措辞表达大致相同内容的文件单独从任何一侧看都无可挑剔Two files that say roughly the same thing in different words look fine from either side alone.。这一洞察直接决定了当前架构把正文body收敛为一份共享副本让漂移从第二次手改变成重新生成regenerate。生成器 scripts/gen_plugin_content.py 的模块 docstring 完整记录了这段历史。目录结构共享源与四个生成目标共享源只包含两类条目plugins/shared/ ├── README.md # 本文所依托的机制说明 ├── commands/ # 18 个斜杠命令源文件 │ ├── ask.md context.md coverage.md dead-code.md decision.md │ ├── doctor.md export.md health.md impacted-tests.md init.md │ ├── reindex.md risk.md search.md security.md status.md │ ├── symbol.md update.md why.md └── skills/ # 6 个技能源文件 ├── architectural-decisions.md ├── change-review.md ├── code-health.md ├── codebase-exploration.md ├── dead-code-cleanup.md └── pre-modification.md每个源文件渲染为四个目标且全部是生成产物直接编辑会触发下一轮测试失败宿主技能产物命令产物Claude Codeplugins/claude-code/skills/dir/SKILL.mdplugins/claude-code/commands/id.mdCodexplugins/codex/skills/dir/SKILL.mdpackages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-id.md可以对照实际生成的目录验证plugins/claude-code/skills/与plugins/codex/skills/下各有 6 个SKILL.md其中pre-modification.md因两个宿主目录命名不一致pre-modification对pre-modification-check正是每宿主dir覆盖的典型实例。渲染器的宿主模型一处源码看懂全部差异生成器用Host数据类scripts/gen_plugin_content.py#L68-L104集中描述每个宿主把文件放哪、如何拼写自身特有语法所有差异都收敛在这两个常量表里宿主命令文件名命令引用语法命令 frontmatter 键claude-code{id}.md/repowise:{id}全部保留codexrepowise-{id}.md/prompts:repowise-{id}仅description、argument-hint三个设计要点值得展开Codex 命令文件名加repowise-前缀因为~/.codex/prompts是与用户安装的其他工具共享的扁平全局目录命名空间化避免冲突Claude Code 的命令目录是专属的无需前缀。命令引用占位符{{cmd:risk}}正文里写{{cmd:risk}}渲染时由command_reference格式化为/repowise:riskClaude Code或/prompts:repowise-riskCodex正则_TOKEN负责替换scripts/gen_plugin_content.py#L132-L133。command_frontmatter_keys键白名单Codex 的 prompt frontmatter 只定义description与argument-hint其余键如 Claude Code 的allowed-tools会被剔除而不是原样输出——向宿主输出它读不懂的键正是让两种格式重新变成分叉的那类事情测试 tests/unit/cli/test_plugin_content.py#L95-L107 的 docstring 原话。共享源文件格式一个条目一个文件以 plugins/shared/skills/code-health.md 为例共享源格式如下--- frontmatter: | # 供没有自有覆盖的宿主使用 description: ... claude-code: # 可选每宿主覆盖块 dir: code-health # 输出目录用于宿主命名不一致时 frontmatter: | # 整体替换共享 frontmatter 块 name: code-health description: ... user-invocable: false codex: dir: code-health frontmatter: | name: code-health description: ... --- # Code Health with Repowise 正文所有宿主共享且是黄金测试固定比对的对象关键约定frontmatter 以原文verbatim存储而非解析成键值对。这样渲染器按字节还原不会经由 YAML dumper 重新折叠 folded scalar避免每次渲染都产生一个 diff从而击碎黄金测试。这也是select_keys采用行级过滤按顶层键名逐行保留附带其缩进续行而非 parse-and-redump 的原因scripts/gen_plugin_content.py#L162-L181。技能按宿主携带各自的 frontmatter因为 description 是写给特定宿主调度器的触发文本Claude Code 侧还带user-invocable: false等专属字段。命令共享同一个 frontmatter 块再由select_keys按宿主键白名单裁剪见上文。正文被_FRONTMATTER正则从---\n…\n---\n之后切出是宿主无关的共享部分。渲染与写入可复现性纪律渲染器scripts/gen_plugin_content.py#L184-L204输出固定槽位顺序frontmatter、空行、body并强制三项纪律固定槽位顺序frontmatter、空行、body是黄金测试可行的前提统一 LF 换行与检出时的行尾风格无关——仓库在 Windows 上用core.autocrlf检出未改动的生成文件读回是 CRLFwrite_if_changed会先规范化再比较scripts/gen_plugin_content.py#L250-L263绝不输出时间戳、版本号或生成器横幅——没有变化却发生变化的文件不配当黄金a file that changes when nothing changed cannot be a golden。条目按id排序加载load_items用sorted(...glob(*.md))因为目录列举在不同文件系统上顺序不稳定排序保证了渲染的可复现性。两个入口命令写入与漂移检查python scripts/gen_plugin_content.py # 写入所有生成产物 python scripts/gen_plugin_content.py --check # 报告漂移不写任何文件--check模式逐文件与期望文本比对并额外检查孤儿文件有任一不一致即向 stderr 打印汇总并返回退出码 1scripts/gen_plugin_content.py#L266-L317。这使它可以作为 CI 门禁tests/unit/cli/test_plugin_content.py::test_rendering_is_idempotent断言GEN.main([--check]) 0即干净树上的 --check 必须零漂移。黄金测试防分叉的最终防线测试文件 tests/unit/cli/test_plugin_content.py 对磁盘上的生成文件而非生成器返回值做断言因为一个渲染器可以对自己从未写盘的内容完全正确——那正是本测试要消灭的失败模式。六项核心断言逐文件黄金比对参数化遍历rendered_files()磁盘文件必须与期望逐字节一致行尾规范化后否则报错并提示编辑共享源后运行生成器tests/unit/cli/test_plugin_content.py#L51-L63双宿主正文等价同一技能分别对两个宿主渲染、剥掉 frontmatter、把命令引用标记归一化后必须相等——直接陈述一个正文渲染两次这一核心属性tests/unit/cli/test_plugin_content.py#L66-L83每个技能必须渲染到两个宿主Codex prompt 只携带 Codex 读得懂的 frontmatter 键树上不得存在没有共享源支撑的生成文件孤儿检测清理不能误伤手维护文件——生成器写出的每个文件都以---开头因此以 frontmatter fence 作为所有权测试README 之类无 frontmatter 的手维护文件会被豁免tests/unit/cli/test_plugin_content.py#L128-L149。孤儿文件检测让下线的条目真正下线orphaned_files()scripts/gen_plugin_content.py#L207-L242解决的是只删共享源、不删产物的问题rendered_files()只说明应当存在什么没有人对比实际存在什么于是删除一个共享源会在磁盘上留下两份渲染副本而--check依然宣称干净。后果并非纯装饰性退役的命令会继续随 wheel 打包、每次安装仍被写入~/.codex/prompts技能目录被改名后旧SKILL.md会作为同名第二个技能被宿主加载。清理逻辑按内容而非位置划定范围并遵循两条安全规则只删除以---\n开头的文件生成物标志README 或手维护文件绝不自动删除只有技能SKILL.md拥有其目录删除命令产物不递归删除目录——否则最后一个命令退役时会连命令根目录一起删掉包括 Codex 的包数据目录进而让install中的bundled_prompts直接FileNotFoundErrortests/unit/cli/test_plugin_content.py#L152-L170 记录了这个真实回归。Codex 命令为何不进 plugins/codex/这是 README 中「Where the Codex commands go」一节回答的问题也是理解整套布局的关键Codex 插件清单没有命令槽位。一个 Codex 插件可以捆绑skills/、hooks/、assets/、.mcp.json、.app.json仅此而已能产生 Codex 斜杠命令的唯一表面是~/.codex/prompts/而它是仅本机有效、由 CLI 写入的目录生成器 docstring 原文local-only and written by the CLI。因此 Codex 命令以包数据形式随 CLI 分发包内置即packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/常量CODEX_PROMPT_DATA见 scripts/gen_plugin_content.py#L63-L65由repowise agents add --targetcodex在安装时写入用户本机~/.codex/prompts。测试test_retiring_every_command_does_not_delete_the_directory_itself还验证了该包数据目录下的bundled_prompts()恰好返回 18 个命令。共享源里装的是什么六项技能速览共享源承载的技能正文即黄金测试固定的部分覆盖 Agent 在编码全流程中的六类介入时机pre-modification.md改动前风险评估。调用get_risk(targets[...])读取hotspot_score、defect_profile含bug_magnet标志与近 6 个月fix_count、impact_surface、co_change_partners、bus_factor、test_gap等批改多个文件时把所有 target 合并为一次调用改前先get_context防违反架构决策重度重构再叠加get_health拿改造前后分数。change-review.md合并前变更评审。先用get_change_risk(revspec...)对整段变更commit 或base..head打分并读directive与health_delta再用get_risk(targets..., changed_files...)的 PR 模式逐文件读may_break、missing_cochanges、missing_tests、tests_to_run注意区分measured与inferred两种依据可加include[blast]取完整pr_blast_radius档案。code-health.md代码健康。get_health()无参为仪表盘fix_first 仓库级 KPI带targets为逐文件打分include可加biomarkers/refactoring/coverage/trendonly反向裁剪按weighted_deficit而非score排序并核对unresolved/not_indexed语义。codebase-exploration.md代码库探索。给出了问题 → 工具对照表首次上手用get_overview()具体问题用get_answer(question...)符号/路径/概念用search_codebasemode自动路由search_method区分embedding/bm25精确定位用get_context后接get_symbol取字节。architectural-decisions.md架构决策。get_why四种模式关键词语义搜索、按文件查询其治理决策与对齐度、target 锚定搜索、无参决策健康仪表盘决策来自 ADR、PR/squash 提交体、WHY:/DECISION:/TRADEOFF:/ADR:内联标记等五类来源逐条溯源到原文 span。dead-code-cleanup.md死代码清理。get_dead_code()按置信分层返回kind区分unreachable_file/unused_export/zombie_packagesafe_onlytrue、tier、min_confidence、group_by控制筛选只对safe_to_delete: true建议删除删除前用get_risk复查依赖并按不可达文件 → 未用内部符号 → 未用导出的安全顺序执行。共享命令内容示例risk 与 init命令同样在plugins/shared/commands/编写。以 risk.md 为例它演示了{{cmd:init}}占位符与allowed-tools键的实际用法repowise risk对变更而非文件打分权威字段是仓库相对百分位risk_percentile与classification支持无参未提交工作、sha、base..head三种 revspec提供--ext、-x/--exclude并尊重.riskignore、--format json、--baseline、-t/--target、--path等旗标。init.md 则是流程型命令的范例其 7 步序列检查安装 → 检查.repowise/→ 提供模式但绝不阻塞于密钥 → 判定仓库是否值得注册 → 选择 provider → 确认排除项 → 运行并收尾内嵌了完整的repowise init旗标参考涵盖--prose/--no-prose、--mode fast、--embedder、--concurrency、-x/--exclude、--commit-limit、--editor-setup/--no-editor-setup、--hook、--save-key/--no-save-key、--resume/--force、--dry-run等全部选项。维护工作流新增、修改与下线基于以上机制向plugins/shared/增改内容的完整流程为新增技能或命令在plugins/shared/skills/或plugins/shared/commands/新建一个.md文件必须从---frontmatter 块开始load_item的硬性校验正文中引用其他命令时写{{cmd:id}}占位符处理宿主差异技能用claude-code:/codex:块声明各自的dir与frontmatter命令依赖共享块 select_keys白名单无需手写差异重新生成运行python scripts/gen_plugin_content.py写入四个目标验证运行测试tests/unit/cli/test_plugin_content.py或整仓测试--check的幂等性也被测试断言下线条目删除共享源文件后必须重新运行生成器不带--check由orphaned_files清理两个宿主的遗留产物CI 会在下次运行时拦截任何漏删。不要直接编辑plugins/claude-code/、plugins/codex/skills/或codex_prompts中的生成文件——下一轮黄金测试必然失败所有修改一律落到plugins/shared/并重新生成。这正是这套架构的全部意义把双宿主内容一致性从需要人工自律的纪律变成一次渲染、一次测试即可机械保证的工程事实。赞分享【免费下载链接】repowiseCodebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.项目地址https://gitcode.com/gh_mirrors/re/repowise点击查看免费下载相关推荐Claude Code 插件命令实战指南十种插件斜杠命令模式与 CLAUDE_PLUGIN_ROOT 工程实践Claude Code 插件命令实战指南十种插件斜杠命令模式与 CLAUDE_PLUGIN_ROOT 工程实践 本篇技术指南以 claude pluginsAI 插件开发工具插件系统Claude Code 斜杠命令开发实战基于 claude-plugins-official 的 10 个基础命令示例与模式解析Claude Code 斜杠命令开发实战基于 claude plugins official 的 10 个基础命令示例与模式解析 本文是 Claude CodAI 插件开发工具插件系统idea-claude-code-gui 集成 Codex Custom Prompts 实战指南用 /prompts: 斜杠命令固化你的可复用指令idea claude code gui 集成 Codex Custom Prompts 实战指南用 /prompts: 斜杠命令固化你的可复用指令 本指南以开发工具AI 应用代码智能体上一篇终极指南用XiaoMusic让小爱音箱变身你的私人音乐管家下一篇MentraOS安全指南数据加密与隐私保护最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考