sync-ai-context

面向 AI 工具上下文的配置驱动同步 CLI，支持单一源、多目标同步与一致性校验，当前范围为 skills 目录加一个可选的单文件记忆入口。

功能特性

• 支持 source.kind=canonical|tool 单一来源
• 支持可选 memoryPath，用于同步 AGENTS.md、CLAUDE.md 等单文件记忆上下文
• 支持 link 与 copy 两种目标模式
• 提供 sync、check、doctor 命令
• 支持 --dry-run 与 --force 冲突策略
• 支持 CI 自动发包、Release/Tag 与 provenance 证明

安装

npm install -g sync-ai-context

不全局安装也可直接运行：

npx sync-ai-context sync --dry-run

快速开始

在项目根目录创建 context-sync.config.json：

{
  "$schema": "https://raw.githubusercontent.com/bytedance/vibe-coder-manager/main/context-sync.schema.json",
  "source": {
    "kind": "tool",
    "tool": "claude",
    "skillsPath": ".claude/skills",
    "memoryPath": "CLAUDE.md"
  },
  "targets": {
    "codex": {
      "skillsPath": ".agents/skills",
      "memoryPath": "AGENTS.md",
      "mode": "link"
    },
    "cursor": {
      "skillsPath": ".cursor/skills",
      "memoryPath": ".cursor/rules/project.mdc",
      "mode": "copy"
    }
  }
}

执行同步：

context-sync sync

命令说明

# 同步所有目标
context-sync sync

# 同步单个目标
context-sync sync --target codex

# 仅预览，不写入
context-sync sync --dry-run

# 强制覆盖冲突
context-sync sync --force

# 校验目标一致性
context-sync check

# 基础健康检查
context-sync doctor

行为语义

source.kind

• canonical: 使用独立目录作为唯一来源
• tool: 直接使用工具目录作为唯一来源
• memoryPath: source 和 target 都配置时，sync/check/doctor 会额外处理该单个记忆文件

target mode

• link 模式：
  • 每个已配置目标路径都应为指向对应源路径的符号链接
  • check 发现目标不一致时返回 symlink mismatch
• copy 模式：
  • 将已配置的源目录或单文件复制到目标路径
  • check 发现漂移时返回 copy drift；目录报告 modified/missing/extra，单文件报告内容不一致

当前范围

• 当前版本支持 skillsPath 加一个可选的 memoryPath
• 暂不支持目录级 rules/ 映射或多文件规则分发

冲突策略

• --dry-run: 只输出计划动作，不写入文件系统
• --force: 冲突时允许覆盖目标状态

开发

pnpm install
pnpm run test
pnpm run build
pnpm run check:oss
pnpm run check:badges

发布与供应链证明

• 发版工作流：.github/workflows/release.yml
• npm 发包通过 CI 执行并使用 --provenance
• README 中 Provenance 徽章用于展示流水线构建发布状态

徽章维护

• 必需徽章：CI、npm version、npm downloads、License、Provenance
• 通过 pnpm run check:badges 做自动校验

协作与安全

• 贡献指南：CONTRIBUTING.md
• 行为准则：CODE_OF_CONDUCT.md
• 安全策略：SECURITY.md
• 变更记录：CHANGELOG.md

许可证

MIT，见 LICENSE。