agent-sync Architecture Spec

一次定义，到处运行。AI Agent 的身份、记忆、知识的跨平台同步系统。

目标

构建一个 CLI 工具，将 AI Agent 的身份、记忆、指令、技能统一管理，通过适配器模式自动同步到各平台。

核心数据模型

1. 身份层 (Identity)

universal-agent/
├── soul.yaml          # 元人格：行为边界、核心信条、气质
├── identity.yaml      # 具体人格：名字、风格、价值观
└── user.yaml          # 用户画像：服务对象、偏好、时区

soul.yaml — 平台无关的元人格：

identity:
  name: string
  language: string
 
personality:
  - string  # 核心特质列表
 
boundaries:
  - string  # 行为边界
 
communication:
  style: string
  tone: string

identity.yaml — 可按平台微调：

name: string
emoji: string
values:
  - name: string
    principles: [string]
traits:
  - string
development_goals:
  short_term: [string]
  mid_term: [string]

user.yaml — 所有平台共享：

user:
  name: string
  timezone: string
  github: string
  occupation: string
 
interests: [string]
preferences: [string]

2. 记忆层 (Memory)

universal-agent/
├── memory/
│   ├── core.md           # 温记忆：核心画像 ~100 行
│   ├── daily/
│   │   └── YYYY-MM-DD.md # 热记忆：每日记录
│   └── observations/
│       └── YYYY-MM-DD.md # 自动采集的观察
└── knowledge/            # 冷记忆（外挂知识库）
    └── (symlink to Obsidian vault)

温记忆 (core.md) — 跨平台快速加载：

核心画像（3-5 句）
关键偏好（5-10 条）
风险提示（3-5 条）
目标状态（1-3 条）

晋升门槛（热→温）：跨项目通用 + 多次出现 + 有明确适用场景

GC 规则（温→删除）：30 天未引用 + 无活跃关联

3. 指令+技能层 (Directives + Skills)

universal-agent/
├── directives/
│   ├── INDEX.md              # 路由索引 + 关键词触发映射
│   ├── ai/                   # AI/Agentic 领域
│   ├── technical/            # 技术决策
│   └── cross-domain/         # 跨域隐喻
└── skills/
    └── <skill-name>/
        └── SKILL.md          # OpenClaw 格式，MCP 兼容

Directives — “我怎么思考”：价值观判断、决策偏好、认知沉淀 Skills — “我会做什么”：可复用的工具流程、标准操作、checklist

两者区别：directive 是判断标准（“不要 push main”），skill 是操作序列（“部署到生产的 5 个步骤”）。

5. 路由层 (Routing)

# routing.yaml
platforms:
  openclaw:
    type: chat-assistant
    strengths: [日常对话, 定时任务, 消息推送]
  claude-code:
    type: coding-agent
    strengths: [复杂编码, 代码审查, 重构]
  codex:
    type: research-agent
    strengths: [深度研究, 大规模代码生成]
  cursor:
    type: ide-agent
    strengths: [快速编码, 实时补全, UI开发]
 
defaults:
  chat: openclaw
  coding: claude-code
  research: codex
  ide: cursor

适配器接口

每个平台一个 adapter，实现以下接口：

class BaseAdapter(ABC):
    """所有平台适配器的基类"""
 
    platform_name: str
 
    @abstractmethod
    def detect(self) -> bool:
        """检测平台是否已安装"""
 
    @abstractmethod
    def sync(self, universal: UniversalAgent, dry_run: bool = False) -> SyncResult:
        """从通用格式同步到目标平台"""
 
    @abstractmethod
    def pull(self, universal: UniversalAgent) -> PullResult:
        """从目标平台反向同步回通用格式"""
 
    @abstractmethod
    def status(self) -> AdapterStatus:
        """报告同步状态"""

适配器映射表

通用格式	OpenClaw	Claude Code	Codex	Cursor	Windsurf	Copilot
soul.yaml	SOUL.md	→ CLAUDE.md 人格段	→ AGENTS.md 头部	→ .cursor/rules/soul.mdc	→ .windsurf/rules/soul.md	→ copilot-instructions.md 头部
identity.yaml	IDENTITY.md	→ CLAUDE.md 风格段	→ AGENTS.md 行为段	→ .cursor/rules/identity.mdc	→ .windsurf/rules/identity.md	→ instructions/*.md
user.yaml	USER.md	→ CLAUDE.md 偏好段	—	→ User Rules	→ Global Rules	→ Personal
memory/core.md	MEMORY.md	→ auto memory	—	→ Memory Bank	→ Memories	→ Agentic Memory
directives/	directives/	→ CLAUDE.md 规则段	→ AGENTS.md 规则段	→ .cursor/rules/*.mdc	→ .windsurf/rules/*.md	→ instructions/*.md
skills/	skills/	→ MCP config	→ MCP config	→ MCP config	→ MCP config	→ MCP config

Pipeline 架构

Observer (L1) — 自动采集

触发：每次对话结束 / 定时 cron
输入：对话历史、操作日志、文件变更
输出：memory/observations/YYYY-MM-DD.md
规则：幂等性（同一天不重复写入）

Reflector (L2) — 提炼晋升

触发：每日定时 / 手动 distill
输入：memory/observations/*.md
输出：
  - 晋升到 memory/core.md（温记忆）
  - 晋升到 directives/（新指令）
  - 晋升到 skills/（新技能脚手架，需用户确认）
  - GC 已晋升和过期的观察
门槛：跨项目通用 + 多次验证 + 有明确适用场景

Skill 发现逻辑：
  1. Reflector 对 warm entry 分类：insight / procedure / tool_pattern
  2. procedure 和 tool_pattern 类型的 entry → skill 候选
  3. 出现 >= 2 次 + 关键词启发式匹配
  4. 去重：已存在的 skill 自动跳过
  5. 输出候选列表，用户确认后用 skill-creator 生成脚手架

Writer (L3) — 输出文章（Phase 3+）

触发：用户调用 distill skill
输入：提炼后的洞察 + Socratic 反思记录
输出：
  - 公司内/敏感环境 → directives/（只沉淀为内部指令）
  - 公司外/个人环境 → knowledge/（Obsidian 知识库，洞察文/经验总结/知识图谱）
状态：尚未实现

双模式说明： Writer 的输出目标取决于部署环境。公司内部场景下，知识只能沉淀为 directives（不外传、不落地 Obsidian）。个人环境可以绑定 Obsidian 作为”外挂大脑”，洞察自动写入知识库。两种模式共享同一套 Reflector 管线，区别只在输出层。

CLI 设计

# 初始化和检测
agent-sync init                    # 创建 universal-agent/ 目录结构
agent-sync detect                  # 检测已安装的平台
agent-sync status                  # 各平台同步状态
 
# 同步
agent-sync sync                    # 全量同步到所有平台
agent-sync sync --target cursor    # 只同步到 Cursor
agent-sync sync --dry-run          # 预览变更
 
# 记忆管理
agent-sync memory today            # 查看近期热记忆
agent-sync memory consolidate      # 热→温：提炼晋升
agent-sync memory distill          # 温→冷：高置信度洞察→directives
agent-sync memory review           # 交互式回顾：显示所有层状态 + skill 候选
agent-sync memory push             # 推送到 Git
agent-sync memory pull             # 从 Git 拉取
 
# 技能管理
agent-sync skills scan             # 扫描 skills/ 目录
agent-sync skills discover         # 从温记忆中发现 skill 候选
agent-sync skills discover --confirm  # 确认后自动创建 skill 脚手架
agent-sync skills sync             # 同步 skills 到各平台

技术栈

语言: Python（与 OpenClaw 生态一致）
配置格式: YAML（通用 schema）→ Markdown（各平台输出）
同步机制: Git（去中心化，不依赖云服务）
CLI 框架: Typer
模板引擎: Jinja2（schema → 平台 Markdown）
包管理: PyPI / pip

实现路线

Phase 1：核心骨架 ✅

数据模型定义（soul.yaml, identity.yaml, user.yaml）
OpenClaw adapter（SOUL.md / IDENTITY.md / USER.md / MEMORY.md）
Claude Code adapter（CLAUDE.md Jinja2 模板）
Codex adapter（AGENTS.md Jinja2 模板）
agent-sync sync 基本功能
agent-sync detect 平台检测
Skills 数据模型 + load_skills()

Phase 2：记忆系统 ✅

Reflector 热记忆采集（claude-mem SQLite + OpenClaw 日志）
Reflector 提炼晋升（热→温）
Warm entry 自动分类（insight / procedure / tool_pattern / preference）
memory/core.md 自动整理
GC 过期条目清理
温→冷蒸馏（distill → directives/）
交互式 memory review
Skill 发现 pipeline（procedure/tool_pattern 类 → skill 候选 → 脚手架）
Git 同步（push / pull）

Phase 3：扩展平台（进行中）

Cursor adapter（.cursor/rules/ 输出）
Windsurf adapter
Copilot adapter
routing.yaml + agent-sync route
Writer (L3) — Obsidian 知识库输出

Phase 4：开源

文档和 README
PyPI 发布
GitHub 开源
社区反馈迭代

竞品对比

特性	agentinit	agent-sync
规则同步	✅	✅
人格/身份	❌	✅ soul.yaml + identity.yaml
记忆系统	❌ ✅	memory 三层
用户画像	❌	✅ user.yaml
任务路由	❌	✅ routing.yaml
知识管道	❌	✅ Obsidian 集成
指令系统	❌	✅ directives/
反向同步	✅	✅
Pipeline	❌	✅ Observer → Reflector → Writer
覆盖平台	4	6+

Jason's Blog

agent-sync Architecture Spec

agent-sync Architecture Spec

目标

核心数据模型

1. 身份层 (Identity)

2. 记忆层 (Memory)

3. 指令+技能层 (Directives + Skills)

5. 路由层 (Routing)

适配器接口

适配器映射表

Pipeline 架构

Observer (L1) — 自动采集

Reflector (L2) — 提炼晋升

Writer (L3) — 输出文章（Phase 3+）

CLI 设计

技术栈

实现路线

Phase 1：核心骨架 ✅

Phase 2：记忆系统 ✅

Phase 3：扩展平台（进行中）

Phase 4：开源

竞品对比

目录