Project Context Sync

核心用法

project-context-sync 是一个 Git 钩子工具，在每次提交后自动更新 PROJECT_STATE.md，作为项目的"活文档"。

安装流程：

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

安装后会自动：
1. 在 .git/hooks/ 创建 post-commit 钩子
2. 生成 .project-context.yml 配置文件
3. 创建初始 PROJECT_STATE.md
4. 将该文档加入 .gitignore

两种运行模式：

| 模式 | 配置 | 特点 |

|------|------|------|

| AI 摘要模式 | `ai_summary: true` | 调用 LLM 生成智能总结，推断当前工作焦点，建议下一步行动 |

| 原始模式 | `ai_summary: false` | 仅记录 Git 信息，快速免费 |

显著优点

• 团队上下文同步：新成员或切换会话的 Agent 可秒懂项目状态，无需翻查 commit 历史
• 无摩擦集成：完全自动化，提交即更新，零额外操作负担
• 灵活配置：可自定义包含的区块（最近提交、变更统计、AI 焦点分析等）
• 本地优先：文档 gitignored，不污染仓库，仅本地使用

潜在缺点与局限性

• AI 模式依赖外部服务：需 Clawdbot Gateway HTTP API 启用，且消耗 token
• 单点依赖：若 Clawdbot 未运行，AI 功能降级为原始模式
• 配置门槛：首次使用需手动启用 Gateway 端点（chatCompletions.enabled: true）
• 仅限本地：无法为远程协作者共享状态文档（设计意图，但限制了分布式团队场景）

适合人群

• AI 辅助开发者：频繁与 Agent 协作，需要快速上下文交接
• 多项目切换者：经常在不同代码库间跳转，容易遗忘进度
• 个人开发者：作为项目的"外部记忆"，减少认知负担

常规风险

• 信息泄露风险：PROJECT_STATE.md 虽被 gitignore，但包含最近提交信息，若被意外提交可能暴露敏感变更
• Token 成本：AI 摘要模式每次提交都消耗 API 调用，高频提交场景成本累积
• API 安全：Gateway 端点需 bearer token，虽默认绑定 loopback（仅限本地），但配置错误可能暴露接口

核心用法

project-context-sync 通过 Git post-commit hook 实现项目状态的自动同步。安装后，每次代码提交都会触发以下流程：收集git信息（提交哈希、分支、变更文件）→ 可选调用Clawdbot本地AI接口生成智能摘要 → 更新 PROJECT_STATE.md 文档。该文档可被团队任何成员或AI Agent即时读取，快速了解项目当前状态。

配置灵活：支持纯git模式（零成本、快速）和AI增强模式（消耗token但提供深度洞察）。AI模式可推断当前开发焦点、建议下一步行动，显著提升跨会话、跨Agent的上下文传递效率。

显著优点

1. 上下文零丢失：告别"上次做到哪了"的困扰，新会话或切换Agent时秒懂项目状态
2. 安装极简：单命令安装，自动处理hook部署、配置文件初始化、gitignore更新
3. 双模式运行：AI模式智能丰富，纯git模式轻量免费，按需切换
4. 安全可控：AI调用仅限本地API，不外发数据；Bearer Token认证；代码MIT开源可审计
5. 无依赖负担：零外部包依赖，仅使用bash/git/curl/jq系统工具

潜在缺点与局限性

• Clawdbot依赖：AI模式需本地运行Clawdbot服务，否则降级为纯git模式
• token消耗：AI模式持续消耗LLM token，高频提交场景成本需评估
• 单仓库局限：按仓库配置，多仓库管理需分别安装
• 摘要质量波动：AI推断的"当前焦点"和"建议下一步"准确性依赖提交信息质量
• Hook冲突风险：若仓库已有复杂post-commit hook，需手动合并

适合人群

• 使用AI Agent进行开发，需要跨会话保持上下文的开发者
• 团队协作项目，新成员需要快速理解代码库状态
• 频繁切换分支、并行多任务的开发者，需要外部记忆辅助
• 构建AI驱动的DevOps流程，需要结构化项目状态输入的技术团队

常规风险

| 风险点 | 等级 | 说明 |

|--------|------|------|

| 本地API调用 | 低 | 仅访问localhost，数据不出境，Token存储于用户主目录 |

| Git hook篡改 | 低 | 安装时未验证现有hook完整性，建议安装前手动备份 |

| 配置读取 | 信息级 | 读取~/.clawdbot/clawdbot.json获取认证信息，需确保该文件权限正确(建议0600) |

| AI摘要偏差 | 中 | 生成内容可能误解提交意图，关键决策仍需人工确认 |

建议：生产仓库启用前先在测试仓库验证；AI模式建议配合清晰的提交信息规范使用；敏感项目建议先用ai_summary: false模式运行。