SuperAPI AI 工具集

ai-context-refresh

编程与开发

查看项目

更新于 11-04 19:58

技能介绍

用途

ai-context-refresh 用于管理项目根级 AI 上下文文件(CLAUDE.md、AGENTS.md)的生命周期,包括生成、智能合并、重构以及刷新 Codex 投影镜像。它面向需要让 AI 代理在项目中稳定获得项目级上下文、同时避免人工维护重复内容的工作流。

主要能力

  • 生成与更新根上下文:读取 docs/project-config.json 和模板,按分段标记生成 CLAUDE.md;更新模式仅替换标记之间的内容,保留标记外的项目自有文本。
  • 智能合并:当 CLAUDE.md 存在但没有分段标记时,按 ## 标题匹配已知分段键,将匹配段落包裹标记并替换内容,未匹配的用户段落原样保留。
  • 纯 AI 重构:AI 读取整份 CLAUDE.md,去除冗余、合并表格、缩短冗长解释,在保留所有分段标记的前提下提升 token 效率。
  • Codex 镜像同步:在最终 AI 编辑与验证完成后,直接运行共享同步运行器并传 --skip=claude-md,从完成后的 CLAUDE.md 重新生成 AGENTS.md、.agents/、.codex/ 等镜像,并验证各镜像。
  • 条件分段:仅当配置中存在对应数据时才生成某分段,无数据则省略而非留空占位。
  • 旧内容清理:更新模式可报告 LEGACY_UNIVERSAL_CONTENT,并支持通过 --strip-legacy-universal 在备份后移除旧版写入的通用分段与受管块。
  • 路径规则内联与按需注入:当 contextGroups[].rules 使根文件超出字节预算时,可设置 portability.inlinePathRules 为 false,由文件约定钩子在匹配文件被触及时注入完整规则,并提供 --lookup CLI 作为非自动读取途径。

使用方式

该技能依赖 Node.js 与 docs/project-config.json。先通过 --detect 检测模式(缺失 CLAUDE.md 为 init、带标记为 update、无标记为智能合并、显式 --mode 可覆盖)。随后运行生成脚本,例如:

node .claude/skills/ai-context-refresh/scripts/generate-claude-md.cjs --mode init
node .claude/skills/ai-context-refresh/scripts/generate-claude-md.cjs --mode update
node .claude/skills/ai-context-refresh/scripts/generate-claude-md.cjs --mode update --strip-legacy-universal

脚本先生成机械部分,随后由 AI 填写项目描述、黄金规则、决策速查、命名约定等创造性内容,并进行验证。最终 CLAUDE.md 编辑完成后,直接运行:

node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --skip=claude-md

若运行器失败,应报告失败阶段并保持任务未完成,不得声称 Codex 镜像已更新。

适用场景

  • 新项目首次建立根级 AI 上下文。
  • 已有带标记的 CLAUDE.md 需要增量同步配置变更。
  • 已有无标记文档需要智能合并生成分段。
  • 需要优化 CLAUDE.md 的 token 效率与结构。
  • 根上下文更新后需要刷新 Codex 镜像。

限制

  • 依赖 docs/project-config.json 作为主要数据源。
  • 依赖 Node.js 运行生成脚本。
  • 不运行钩子的宿主环境不受支持;工作流路由仅由钩子投递,不写入受跟踪文件。
  • 无标记根文件视为项目自有,预检不会覆盖,需显式运行更新模式进行智能合并。
  • 自定义路由协议仅运行时生效,不得写入受跟踪的 CLAUDE.md/AGENTS.md。
  • 生成的分段内容不应手工编辑,应在构建器、模板或配置中修复后重新生成。
  • 本技能与 sync-codex 为两个独立面向用户的技能,但共享同一执行流水线;交接直接调用运行器,不嵌套调用技能以避免递归。