Project Context Sync

# project-context-sync

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

## 功能说明

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

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

## 安装

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

或者如果该命令在你的 PATH 中： ```bash project-context-sync install ```

这将： 1. 在 `.git/hooks/` 中安装一个 post-commit 钩子 2. 使用默认配置创建 `.project-context.yml` 3. 创建初始的 `PROJECT_STATE.md` 4. 将 `PROJECT_STATE.md` 添加到 `.gitignore`

## 卸载

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

## 手动更新

无需提交即可触发更新：

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

## 配置

编辑仓库根目录下的 `.project-context.yml`：

```yaml 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`**（默认）： - 生成关于变更内容的智能摘要 - 根据最近的提交模式推断当前的关注点 - 建议下一步操作 - 会消耗 token 但提供丰富的上下文 - **要求：** 启用 Gateway HTTP API（见下文）

**关闭 `ai_summary: false`**： - 仅记录原始 git 信息 - 快速且免费 - 智能程度较低但仍有用处

### 启用 Gateway HTTP API

AI 模式使用 Clawdbot 的 OpenAI 兼容端点（`/v1/chat/completions`）。出于安全考虑，默认是**禁用**的。要启用它：

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

**安全提示：** - 该端点继承 gateway 的认证（需要 bearer token） - 使用 `bind: "loopback"`（默认），仅允许本地进程连接 - 脚本会自动从 `~/.clawdbot/clawdbot.json` 读取 token - 对于本地开发环境，风险极低

## 输出

`PROJECT_STATE.md` 将包含：

```markdown # 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` 默认被 gitignore（在本地重新生成） - AI 摘要功能需要 Clawdbot 正在运行 - 如果没有 Clawdbot，将回退到原始 git 信息模式