AI 项目的活文档管家

通过 Git 提交钩子自动维护项目状态文档，让任意 AI Agent 或未来会话快速理解项目进展，支持 AI 智能摘要生成。

基本信息

• 技能名称?Project Context Sync
• 中文名称?AI 项目的活文档管家
• 作者?joe3112
• 分类?专业技能
• 版本?1.0.0
• 标签?git, automation, context-management, agent-workflow, documentation, hooks

使用方法

使用说明
核心用法
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（仅限本地），但配置错误可能暴露接口