SuperAPI AI 工具集

ai-context-refresh

编程与开发

查看项目

更新于 11-06 10:09

技能介绍

用途 ai-context-refresh 用于维护项目可移植的 AI 上下文生命周期:从项目配置与模板生成或更新根目录 CLAUDE.md,通过智能合并或重构保留项目自有说明,并刷新由 CLAUDE.md 派生的 Codex 投影文件。生成的根文件只承载项目信息(tl;dr、文档查找、路径范围规则、开发命令、技能激活表),不写入框架通用规则;通用协议由通用钩子在会话首个提示及内容增长后注入。

主要能力

  • 模式检测:无 CLAUDE.md 或显式 --mode init 时新建;带标记文件走 update;无标记文件走智能合并;支持 --mode refactor 纯 AI 重构。
  • 生成器脚本:node .claude/skills/ai-context-refresh/scripts/generate-claude-md.cjs --mode <mode>,读取 docs/project-config.json 与模板,调用分段构建器,写文件前创建备份 .claude-md.backup,并报告已生成、跳过(无数据)和保留的段落。
  • 分段标记协议:<!-- SECTION:key --> 与 <!-- /SECTION:key --> 之间的内容在 update 时被替换,标记外内容不被触碰;无数据条件段整体省略而非留空。
  • 智能合并:对无标记的既有 CLAUDE.md,按 ## 标题匹配已知段落键,为匹配段落加标记并替换内容,未匹配的用户段落原样保留。
  • AI 填充与校验:补写项目简述、黄金规则(保留分组名、匹配器、排除项与规则范围)、决策速查与命名约定;校验 Markdown 合法、标记成对、无模板占位符、无实现路径自引用、无空条件段。
  • 旧版内容处理:--mode update --strip-legacy-universal 可移除旧版通用段落与管理块(先写备份),保留所有 SECTION 块与项目自有文本。
  • 路径规则内联与按需加载:当内联规则超出字节预算,可在配置设 portability.inlinePathRules: false,由文件约定钩子按需注入,并要求相关前置条件满足。
  • Codex 镜像同步:在最终编辑与校验后,直接运行 node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --skip=claude-md,重新生成 AGENTS.md、.agents/、.codex/ 等,并执行配置的验证阶段。

使用方式

  1. 确认存在 docs/project-config.json(缺失先运行 $project-config)。
  2. 运行检测:generate-claude-md.cjs --detect,或按需显式指定 --mode init/update/refactor。
  3. 执行生成器,随后由 AI 填充与校验。
  4. 内容变更后执行镜像同步运行器;若运行失败,报告失败阶段与恢复命令,不声称镜像已更新。
  5. 当配置中 portability.generateClaudeMd 为 false 时,CLAUDE.md 归项目所有,不生成、不合并、不改写,仅可执行镜像同步。

适用场景 使用 easy-claude 便携配置、需要以配置驱动方式统一维护 CLAUDE.md 与 Codex 镜像的项目;需要增量更新而不覆盖项目自有说明的仓库;需要压缩冗余、重构根上下文的场景。

限制 依赖 Node.js 与 docs/project-config.json;不运行钩子的主机不受支持;工作流路由与通用规则只经钩子注入,不写入受跟踪文件;自定义路由协议仅运行时生效,不得写入受跟踪文件;SECTION 块内的缺陷须在构建器、模板或配置中修复后重新生成,不可手改;重构与智能合并须保留 ## Project Rules & Context 段落内容,只可压缩不可删除。