project-context-sync

在每次提交后自动更新一份实时的项目状态文档，使任意智能体（或未来会话）能够即时了解当前项目进展。

功能说明

┌─────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│ Git Commit  │ ──▶ │ Post-commit Hook │ ──▶ │ PROJECT_STATE.md    │
│             │     │                  │     │ (自动更新)          │
└─────────────┘     └──────────────────┘     └─────────────────────┘

每次提交后，该钩子将执行以下操作：

1. 收集 Git 信息（最新提交、近期历史、当前分支、变更文件）
2. 可选：调用 LLM 生成智能化摘要
3. 更新仓库根目录下的 PROJECT_STATE.md

安装

# 进入你希望启用该功能的仓库：
cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/install.sh

或者，若该技能已加入系统 PATH：

project-context-sync install

执行后将完成以下操作：

1. 在 .git/hooks/ 中安装 post-commit 钩子
2. 创建默认配置文件 .project-context.yml
3. 生成初始 PROJECT_STATE.md
4. 将 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:
  # 是否使用 AI 生成智能摘要（默认：true）
  ai_summary: true
  
  # 包含最近多少次提交记录
  recent_commits: 5
  
  # 是否在上下文中包含 diff 统计信息
  include_diff_stats: true
  
  # 要包含的章节列表
  sections:
    - last_commit
    - recent_changes
    - current_focus    # AI 生成
    - suggested_next   # AI 生成

AI 摘要模式

启用 ai_summary: true（默认）时：

• 生成关于变更内容的智能摘要
• 基于近期提交模式推断当前开发重点
• 提出下一步建议
• 消耗 token，但提供更丰富的上下文信息
• 前提条件：需启用 Gateway HTTP API（见下文）

禁用 ai_summary: false 时：

• 仅记录原始 Git 信息
• 快速且免费
• 智能化程度较低，但仍具实用价值

启用 Gateway HTTP API

AI 模式依赖 Clawdbot 提供的 OpenAI 兼容接口（/v1/chat/completions）。出于安全考虑，该接口默认禁用。如需启用，请修改配置：

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

安全说明：

• 该接口继承 Gateway 的认证机制（需提供 Bearer Token）
• 当配置 bind: "loopback"（默认）时，仅允许本地进程连接
• 脚本会自动从 ~/.clawdbot/clawdbot.json 中读取 Token
• 对于本地开发环境，风险极低

输出内容

PROJECT_STATE.md 将包含如下结构：

# Project State
*由 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 生成的当前开发重点摘要]

## Suggested Next Steps
[AI 基于提交模式提出的下一步建议]

注意事项

• PROJECT_STATE.md 默认被加入 .gitignore（本地生成，不提交至版本库）
• AI 摘要功能依赖 Clawdbot 正在运行
• 若 Clawdbot 未运行，则自动降级为纯 Git 信息模式