项目状态同步

在每次提交后，自动更新一份动态的项目状态文档，以便任何智能体（或未来的会话）都能立即了解项目当前状况。

功能概述

┌─────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│ Git 提交    │ ──▶ │ 提交后钩子       │ ──▶ │ 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

或者，如果该技能已在你的路径中：

project-context-sync install

安装脚本将：
1. 在 .git/hooks/ 目录下安装一个提交后钩子
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

  # 在上下文中包含差异统计信息
  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 }
      }
    }
  }
}

安全说明：
- 该端点继承网关的身份验证机制（需要持有者令牌）
- 当 bind: "loopback"（默认）时，只有本地进程可以连接
- 脚本会自动从 ~/.clawdbot/clawdbot.json 读取令牌
- 对于本地开发环境，风险极低

输出

PROJECT_STATE.md 文件将包含以下内容：

# 项目状态
*由 project-context-sync 自动更新*

## 最新提交
- **哈希值：** abc123
- **提交信息：** 为应用拦截实现 isPro 检查
- **分支：** feature/subscription-gating
- **时间：** 2026-01-29 12:34
- **变更文件数：** 3

## 近期变更
- abc123: 为应用拦截实现 isPro 检查
- def456: 添加 PaywallPrompt 组件
- ...

## 当前工作重点
[AI 生成的关于当前工作内容的摘要]

## 建议的后续步骤
[基于提交模式由 AI 建议]

注意事项

• PROJECT_STATE.md 默认被 .gitignore 忽略（在本地重新生成）
• 若需使用 AI 摘要功能，钩子需要 Clawdbot 正在运行
• 若 Clawdbot 未运行，将回退到原始 Git 信息模式