document-sync

name	document-sync
description	文档同步系统，持续检查学习项目文档，保持知识最新
trigger	每个阶段开始和结束时

Document Sync Skill

核心问题: 如何保持对项目文档的持续学习？ 解决方案: 周期性检查 + 变更检测 + 知识提取

---

🎯 核心功能

1. 周期性检查 — 每个阶段检查文档变化
2. 变更检测 — 识别文档更新
3. 知识提取 — 从文档中提取规则和约定
4. 同步更新 — 保持 AI 知识与文档同步

---

📁 监控文档列表

项目级文档

文档	内容	检查频率
README.md	项目说明	每阶段
CONTRIBUTING.md	贡献指南	每阶段
CHANGELOG.md	变更记录	每阶段
package.json	依赖配置	每阶段
tsconfig.json	TS配置	每阶段
.eslintrc	Lint规则	每阶段

AI 状态文档

文档	内容	检查频率
active_context.md	当前任务	每操作
kanban.md	进度看板	每任务
conventions.md	项目约定	每阶段
decisions.md	技术决策	每阶段
session.yaml	会话状态	每操作

---

🔄 检查流程

┌─────────────────────────────────────────────────────────────┐
│                    文档检查流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  阶段开始 / 阶段结束                                        │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Step 1: 扫描文档列表                                 │   │
│  │ - 检查文件是否存在                                   │   │
│  │ - 获取文件修改时间                                   │   │
│  └─────────────────────────────────────────────────────┘   │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Step 2: 检测变更                                     │   │
│  │ - 对比上次检查时间                                   │   │
│  │ - 标记变更的文档                                     │   │
│  └─────────────────────────────────────────────────────┘   │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Step 3: 读取变更内容                                 │   │
│  │ - 读取变更的文档                                     │   │
│  │ - 提取关键信息                                       │   │
│  └─────────────────────────────────────────────────────┘   │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Step 4: 更新知识                                     │   │
│  │ - 更新项目约定                                       │   │
│  │ - 更新禁止规则                                       │   │
│  │ - 记录到 Memory                                     │   │
│  └─────────────────────────────────────────────────────┘   │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Step 5: 记录检查时间                                 │   │
│  │ - 更新 last_check 时间戳                            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

📋 检查记录文件

project_document/.ai_state/doc_check.yaml:

# 文档检查记录
last_check: "2025-01-12T10:30:00Z"

# 文档状态
documents:
  README.md:
    last_modified: "2025-01-10T15:00:00Z"
    last_checked: "2025-01-12T10:30:00Z"
    hash: "abc123..."
    
  conventions.md:
    last_modified: "2025-01-12T09:00:00Z"
    last_checked: "2025-01-12T10:30:00Z"
    hash: "def456..."
    extracted_rules: 5
    
# 提取的知识
extracted:
  - source: "conventions.md"
    type: "rule"
    content: "所有API响应使用统一格式"
    added_at: "2025-01-12T10:30:00Z"

---

🧠 知识提取规则

从 conventions.md 提取

async function extractFromConventions(content) {
  const rules = [];
  
  // 提取命名规范
  const namingSection = extractSection(content, '命名规范');
  if (namingSection) {
    rules.push({
      type: 'naming',
      content: namingSection
    });
  }
  
  // 提取代码规范
  const codeSection = extractSection(content, '代码规范');
  if (codeSection) {
    rules.push({
      type: 'code_style',
      content: codeSection
    });
  }
  
  // 提取禁止规则
  const forbiddenSection = extractSection(content, '禁止');
  if (forbiddenSection) {
    for (const rule of parseForbiddenRules(forbiddenSection)) {
      await memory.add({
        category: 'forbidden_action',
        content: rule,
        source: 'conventions.md'
      });
    }
  }
  
  return rules;
}

从 decisions.md 提取

async function extractFromDecisions(content) {
  const decisions = parseADR(content);  // ADR格式
  
  for (const decision of decisions) {
    // 记录技术决策
    await memory.add({
      category: 'project_decision',
      content: `${decision.title}: ${decision.decision}`,
      context: decision.context,
      source: 'decisions.md'
    });
  }
}

从 package.json 提取

async function extractFromPackage(content) {
  const pkg = JSON.parse(content);
  
  // 提取依赖信息
  const deps = {
    ...pkg.dependencies,
    ...pkg.devDependencies
  };
  
  // 检查是否有禁用的依赖
  const forbidden = await memory.recall({ category: 'forbidden_action' });
  for (const dep of Object.keys(deps)) {
    for (const rule of forbidden) {
      if (rule.content.includes(dep)) {
        console.warn(`⚠️ 发现禁用依赖: ${dep}`);
      }
    }
  }
}

---

🔗 与工作流集成

阶段钩子集成

// 在 lifecycle 钩子中调用
async function onPhaseEnter(phase) {
  // 检查文档变化
  await documentSync.check();
  
  // 应用最新规则
  await applyLatestRules();
}

async function onPhaseExit(phase) {
  // 检查是否有需要更新的文档
  await documentSync.check();
  
  // 如果有新学到的知识，记录
  if (hasNewLearnings) {
    await documentSync.recordLearnings();
  }
}

任务执行时检查

async function beforeTaskExecute(task) {
  // 检查相关文档
  const relatedDocs = findRelatedDocs(task);
  
  for (const doc of relatedDocs) {
    if (await hasChanged(doc)) {
      // 重新读取并应用
      await applyDocRules(doc);
    }
  }
}

---

📊 变更报告

当检测到重要变更时，生成报告：

## 📄 文档变更检测

### 变更文件
- `conventions.md` (更新于 5分钟前)
- `decisions.md` (更新于 1小时前)

### 新增规则
1. **命名规范**: 组件使用 PascalCase
2. **API规范**: 响应格式统一为 { success, data, error }

### 新增禁止项
1. 禁止使用 moment.js
2. 禁止在循环中使用 await

### 已应用
这些规则已应用到当前会话。

---

⚠️ 强制规则

1. 每个阶段必须检查 — 不能跳过
2. 变更必须应用 — 保持同步
3. 禁止项必须记录到 Memory — 跨会话生效
4. 冲突必须报告 — 不能静默忽略

---

🛠️ 实现代码

class DocumentSync {
  constructor() {
    this.watchList = [
      'README.md',
      'conventions.md',
      'decisions.md',
      'package.json'
    ];
  }
  
  async check() {
    const changes = [];
    const checkRecord = await this.loadCheckRecord();
    
    for (const doc of this.watchList) {
      if (await this.hasChanged(doc, checkRecord)) {
        changes.push(doc);
        await this.processChange(doc);
      }
    }
    
    await this.saveCheckRecord();
    
    if (changes.length > 0) {
      await this.reportChanges(changes);
    }
  }
  
  async hasChanged(doc, record) {
    const stat = await fs.stat(doc);
    const lastMod = stat.mtime.toISOString();
     lastCheck = record.[doc]?.;
    
     !lastCheck || lastMod > lastCheck;
  }
  
   () {
     content =  fs.(doc, );
    
     (doc) {
       :
         .(content);
        ;
       :
         .(content);
        ;
       :
         .(content);
        ;
    }
  }
}

---

核心价值: 保持 AI 知识与项目文档同步 | 触发: 每阶段 | 输出: 知识更新