gcc

Git 上下文控制器（GCC）v2

概述

GCC 将 Agent 记忆从冗长的 Markdown 转换为精简的 Git 支持索引。GCC 不会重复存储 Git 已经记录的信息，而是仅保存 哈希 + 意图 + 可选的决策备注（每条约 50 个 token，而非约 500 个）。需要时，通过 git show 重建完整上下文。

两种模式：

• git 模式：真实提交、精简的 index.yaml、工作树隔离、aiyoucli 桥接
• 独立模式：为没有 Git 的项目提供 Markdown 回退方案（兼容 v1）

初始化

首次使用时，检查 .GCC/ 是否存在。如果不存在，运行初始化脚本：

scripts/gcc_init.sh          # auto-detects git/standalone
scripts/gcc_init.sh --upgrade # migrate v1 → v2

Git 模式结构

.GCC/
├── index.yaml       # Single source of truth (timeline, worktrees, decisions)
├── branches/        # Branch-specific notes (only when needed)
├── worktrees/       # Worktree tracking
└── .bridge-log      # Tracks what's been synced to aiyoucli

独立模式结构

.GCC/
├── index.yaml       # Timeline in standalone mode
├── main.md          # Global roadmap (v1 compat)
├── log.md           # OTA execution log (v1 compat)
└── branches/

index.yaml 格式

version: 2
mode: git              # or "standalone"
created: "2026-03-28T00:00:00Z"
config:
  proactive_commits: true
  worktree_ttl: 24h
  bridge_to_aiyoucli: auto   # auto | off | manual

current_branch: main

timeline:
  - id: C001
    hash: 85c8539
    intent: "release prep"
    branch: main
    date: "2026-02-25T21:40:00Z"

  - id: C002
    hash: a3f1b22
    intent: "auth middleware rewrite"
    note: "descartamos passport.js — too opinionated for our use case"
    branch: main
    date: "2026-02-26T10:00:00Z"

worktrees:
  - name: refactor-auth
    path: ../gcc-wt-refactor-auth
    branch: refactor-auth
    created: "2026-03-28T10:00:00Z"
    ttl: 24h
    status: active

decisions: []

核心原则：hash 是指向 Git 事实的指针。intent 说明原因。note 仅用于记录 Git 无法捕获的决策（被否决的备选方案、权衡）。

脚本

gcc_init.sh

初始化 GCC v2。自动检测 Git 仓库。

scripts/gcc_init.sh              # new project
scripts/gcc_init.sh --upgrade    # migrate v1 → v2 (backs up old files)

gcc_commit.sh

执行真实的 Git 提交，并向索引追加精简条目。

scripts/gcc_commit.sh "implement retry logic"
scripts/gcc_commit.sh "release prep" "descartamos semantic-release por overhead"
scripts/gcc_commit.sh --staged "hotfix: null check"   # only staged files

gcc_context.sh

根据索引中的哈希重建上下文。

scripts/gcc_context.sh                    # last 5 entries with git details
scripts/gcc_context.sh --last 10          # last 10
scripts/gcc_context.sh --hash abc123      # full details for specific commit
scripts/gcc_context.sh --summary          # one-line per entry (cheap, no git calls)
scripts/gcc_context.sh --decisions        # only entries with notes
scripts/gcc_context.sh --full             # everything

gcc_bridge.sh

将提交数据提供给 aiyoucli 向量记忆。若 aiyoucli 不可用，则静默跳过。

scripts/gcc_bridge.sh --status            # check bridge connectivity
scripts/gcc_bridge.sh --sync              # sync all unsynced entries
# Called automatically by gcc_commit.sh when bridge_to_aiyoucli: auto

gcc_cleanup.sh

基于 TTL 清理工作树并修剪索引。

scripts/gcc_cleanup.sh                    # interactive cleanup
scripts/gcc_cleanup.sh --dry-run          # show what would be cleaned
scripts/gcc_cleanup.sh --force            # clean without asking
scripts/gcc_cleanup.sh --prune-index 50   # keep last 50 timeline entries

命令

COMMIT

持久化一个里程碑。在 git 模式下，会执行真实提交。

触发条件：/gcc commit <summary>、“提交这部分进展”、“检查点”

流程（git 模式）：

1. 运行 scripts/gcc_commit.sh "<intent>" ["<note>"]
2. 此操作会暂存更改、提交、捕获哈希并追加到 index.yaml
3. 如果 bridge_to_aiyoucli: auto，则将内容提供给 aiyoucli 记忆

流程（独立模式）：

1. 运行 scripts/gcc_commit.sh "<intent>"
2. 向 log.md 追加 OTA 条目

主动行为：当 proactive_commits: true 时，在以下情况后建议提交：

• 完成一个函数、模块或完整的工作单元
• 修复 Bug 并验证修复结果
• 完成研究／探索阶段并得出结论

BRANCH

创建隔离的工作区。在 git 模式下，使用真实的 Git 工作树。

触发条件：/gcc branch <name>、“尝试不同的方法”、“试验……”

流程（git 模式）：

1. git worktree add ../gcc-wt-<name> -b <name>
2. 在 index.yaml 的 worktrees: 下注册，并设置 TTL
3. Agent 在工作树目录中工作

流程（独立模式）：

1. 创建 .GCC/branches/<name>/，其中包含 summary.md 和 log.md
2. 在 index.yaml 时间线中注册

MERGE

将分支合并回来。在 git 模式下，执行真实的 Git 合并。

触发条件：/gcc merge <branch>、“整合这次试验”、“分支 X 已完成”

流程（git 模式）：

1. cd 到主工作树
2. git merge <branch>
3. 向时间线追加综合条目，包含意图，并将经验写入 note
4. git worktree remove ../gcc-wt-<name>
5. 将工作树状态更新为 merged

流程（独立模式）：

1. 阅读分支摘要和提交记录
2. 向主时间线追加综合内容
3. 更新分支状态

CONTEXT

检索历史记忆。根据 Git 重建，而非逐字存储。

触发条件：/gcc context、“我们之前做到哪了？”、“目前状态如何？”

标志：

• --summary — 每条记录显示一行。开销最低（额外约 0 个 token）。用于快速了解情况。
• --last N — 获取最近 N 条记录，并完整地从 Git 重建。用于会话恢复时的默认选项。
• --hash <hash> — 深入查看特定提交（差异、消息、文件）。
• --decisions — 仅显示包含备注的条目（被否决的备选方案、权衡）。
• --full — 显示所有内容。请谨慎使用。

CLEANUP

维护索引和工作树。

触发条件：/gcc cleanup、“清理旧工作树”

流程：

1. 运行 scripts/gcc_cleanup.sh 处理过期的工作树
2. 运行 scripts/gcc_cleanup.sh --prune-index 50 精简旧条目

跨会话恢复

在包含 .GCC/ 的项目中启动新会话时：

1. 运行 scripts/gcc_context.sh --summary 快速了解情况
2. 如果需要更多详情，运行 scripts/gcc_context.sh --last 5
3. 运行 scripts/gcc_cleanup.sh --dry-run 检查已过期的工作树
4. 根据 git 重建完整上下文后继续工作

成本：摘要约需 50 个 token，而加载所有 v1 markdown 文件约需 2500 个 token。

aiyoucli 集成

当配置中的 bridge_to_aiyoucli: auto 启用时：

• 每次提交都会通过 gcc_bridge.sh 自动写入 aiyoucli 向量记忆
• 使用命名空间 gcc 存储，并按分支添加标签
• 支持跨提交语义搜索：“我什么时候做过类似的事？”
• 如果未安装 aiyoucli，则会静默跳过桥接

手动同步：scripts/gcc_bridge.sh --sync

自然语言映射

用户说	命令
“保存／创建检查点／持久化这个”	COMMIT
“试试不同的方法”	BRANCH
“这个实验奏效了，把它整合进去”	MERGE
“我们进行到哪了？”／“当前状态如何？”	CONTEXT --summary
“显示最近的活动”	CONTEXT --last 10
“我们对 X 做了什么决定？”	CONTEXT --decisions
“深入查看提交 abc”	CONTEXT --hash abc
“清理旧内容”	CLEANUP
“同步到记忆”	bridge --sync