project-context-sync 是一个创新的 Git 工作流增强工具，通过在本地仓库安装 post-commit 钩子，实现每次代码提交后自动更新项目状态文档(PROJECT_STATE.md)。该工具巧妙地将版本控制历史转化为可读性强的项目上下文，解决了大型项目或长时间开发会话中"现在做到哪了"的常见问题。
核心用法
安装后，工具会在 .git/hooks/ 中植入钩子脚本。每次执行 git commit 后，自动触发以下流程：收集最近提交记录、变更文件统计、当前分支信息；若启用 AI 模式(需配置 Clawdbot Gateway)，则调用本地 LLM 生成智能摘要，推断当前开发焦点并建议下一步行动；最终将这些信息格式化写入 PROJECT_STATE.md。用户也可通过 update-context.sh 手动触发更新，无需为了生成文档而特意提交代码。
显著优点
首先，零侵入式集成是最大亮点，仅需一条命令安装，不修改现有代码结构或工作流，卸载即可完全还原。其次，智能上下文生成能力突出，AI 模式能解读提交模式，自动总结"当前正在做什么"和"建议接下来做什么"，比单纯的 git log 更具价值。第三，团队知识同步效果显著，新成员或切换回项目的开发者可通过阅读 PROJECT_STATE.md 快速建立上下文，大幅减少"热身时间"。最后，隐私优先设计值得称赞，所有数据处理均在本地完成，AI 模式也仅通过 localhost 调用本地网关，源代码不上传云端。
潜在局限
作为 T3 来源的个人项目，长期维护稳定性存在不确定性。配置解析采用简单的 grep/awk 而非完整 YAML 解析器，复杂配置可能导致解析错误。AI 模式依赖 Clawdbot 运行，若网关未启动或配置错误，虽会优雅降级为 Raw 模式，但智能摘要功能将不可用。此外，目前仅支持单仓库安装，跨仓库统一管理功能缺失。
适合的目标群体
特别适合采用AI 辅助开发的团队，AI Agent 可通过阅读 PROJECT_STATE.md 快速理解项目状态；适合大型项目或微服务架构，帮助开发者在多个服务间切换时保持上下文；适合异步协作的远程团队，作为非实时的项目状态广播机制；也适合个人开发者，用作开发日志或明日工作提醒。
使用风险
主要风险在于权限边界：安装脚本需要写入 .git/hooks/ 和仓库根目录，虽符合功能需求，但用户应审查脚本内容避免恶意 hook。Token 安全方面，脚本需读取 ~/.clawdbot/clawdbot.json 中的 API Token，虽为本地文件访问，但需确保该文件权限正确设置。配置风险包括 recent_commits 无上限设置可能导致大量 API 调用，以及 PROJECT_STATE.md 被意外提交到远程（尽管默认添加到 .gitignore，但手动修改仍可能误提交）。建议定期审查生成的文档内容，确保敏感信息未被意外记录。