项目上下文同步

在每次提交后，保持一份动态的项目状态文档的更新，以便任何代理（或未来的会话）都能立即了解项目进展。

功能描述

┌─────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│ Git Commit  │ ──▶ │ Post-commit Hook │ ──▶ │ PROJECT_STATE.md    │
│             │     │                  │     │ (auto-updated)      │
└─────────────┘     └──────────────────┘     └─────────────────────┘

每次提交后，该钩子会：

1. 收集 git 信息（最后一次提交、近期历史、分支、变更的文件）
2. 可选地调用 LLM 生成智能摘要
3. 更新PROJECT_STATE.md位于仓库根目录

安装

# From the repo you want to enable:
cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/install.sh

或者，如果您的路径中已有此技能：

project-context-sync install

这将：

1. 在.git/hooks/
2. 目录中安装一个提交后钩子创建.project-context.yml
3. 包含默认配置创建初始的
4. PROJECT_STATE.md将PROJECT_STATE.md.gitignore

卸载

cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/uninstall.sh

手动更新

触发更新但不提交：

cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/update-context.sh

配置

编辑.project-context.yml在您的仓库根目录：

project_context:
  # Use AI to generate smart summaries (default: true)
  ai_summary: true
  
  # How many recent commits to include
  recent_commits: 5
  
  # Include diff stats in context
  include_diff_stats: true
  
  # Sections to include
  sections:
    - last_commit
    - recent_changes
    - current_focus    # AI-generated
    - suggested_next   # AI-generated

AI 摘要模式

当ai_summary: true（默认）：

• 生成关于变更内容的智能摘要
• 根据最近的提交模式推断当前工作重点
• 建议后续步骤
• 消耗令牌但提供丰富上下文
• 要求：需启用 Gateway HTTP API（见下文）

当ai_summary: false时：

• 仅记录原始 git 信息
• 快速且免费
• 智能化程度较低但仍有帮助

启用网关HTTP API

AI模式使用Clawdbot的OpenAI兼容端点(/v1/chat/completions)。出于安全考虑，该功能默认处于禁用状态。启用方法：

// ~/.clawdbot/clawdbot.json
{
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": true }
      }
    }
  }
}

安全说明：

• 该端点继承网关认证（需要持有者令牌）
• 当使用bind: "loopback"（默认配置）时，仅限本地进程可连接
• 脚本会自动从~/.clawdbot/clawdbot.json读取令牌
• 对于本地开发环境风险极低

输出文件

PROJECT_STATE.md将包含：

# Project State
*Auto-updated by project-context-sync*

## Last Commit
- **Hash:** abc123
- **Message:** Implement isPro check for app blocking
- **Branch:** feature/subscription-gating
- **When:** 2026-01-29 12:34
- **Files changed:** 3

## Recent Changes
- abc123: Implement isPro check for app blocking
- def456: Add PaywallPrompt component
- ...

## Current Focus
[AI-generated summary of what's being worked on]

## Suggested Next Steps
[AI-suggested based on commit patterns]

注意事项

• PROJECT_STATE.md默认被git忽略（在本地重新生成）
• 该钩子功能需要Clawdbot处于运行状态才能生成AI摘要
• 没有Clawdbot，则回退到原始git信息模式