跨项目 Agent 框架（.agent-framework）

VibeCoding 多项目共享的 总约束 + 守卫 + 抽象经验 仓库。独立于各项目仓库，靠 git 跨设备同步；项目用相对路径 ../.agent-framework/... 引用，与盘符（G:/D:）无关。

目录结构

.agent-framework/
├── AGENTS.md                # 总约束主权层（A1–A6 常驻 + B 门表 P1–P23），最高优先级
├── README.md                # 本文件
└── shared/
    ├── guard/
    │   ├── guard.py         # 守卫引擎（被项目 hook 调用）
    │   └── lexicon.json      # 机器化规则库（单一来源，勿在项目另存副本）
    ├── experience/
    │   └── index.json        # 跨项目抽象经验池（软层，id 与 AGENTS/lexicon 互引）
    ├── hooks/
    │   └── pre-push          # 框架同步闸门（push 时询问是否一并同步）
    └── selfcheck.py          # 跨设备一致性自检

每台设备一次性搭建

1. clone 到固定相对位置（必须在 <VibeCoding>/ 下，名称固定为 .agent-framework）：

   cd <VibeCoding>
   git clone <框架remote> .agent-framework
   # 让框架库自身的 pull/checkout 也自动跑完整性自检
   git -C .agent-framework config core.hooksPath shared/hooks

2. 全局主权注入（必做，可靠通道）：opencode 必定自动加载全局 ~/.config/opencode/AGENTS.md。把它软链到框架 AGENTS，框架宪法即对所有项目生效（与盘符无关；每台设备各自建一次，用本机绝对路径）：
   • Windows (PowerShell)：

     New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\AGENTS.md" -Target "<本机 VibeCoding 绝对路径>\.agent-framework\AGENTS.md" -Force

   • Linux / Mac：

     ln -s "<本机 VibeCoding 绝对路径>/.agent-framework/AGENTS.md" ~/.config/opencode/AGENTS.md

3. 项目接线（hook 确定生效；instructions 尽力而为）：
   • opencode.json 的 UserPromptSubmit/PreToolUse hook 改指框架守卫（确定生效）：

     { "command": "python ../.agent-framework/shared/guard/guard.py" }

   • opencode.json 增加 instructions（父级 ../ 路径行为未实测，可能不加载；若加载则额外注入经验索引 index.json 软层）：

     { "instructions": ["../.agent-framework/AGENTS.md", "../.agent-framework/shared/experience/index.json"] }

   • 安装同步闸门（本地配置，不入库；项目已提交 .githooks/ bootstrap 钩子）：

     git config core.hooksPath .githooks

     .githooks/ 已随项目提交，首次 clone 项目后即可运行（不依赖框架已存在）。它会在每次 pull/checkout 后检测 ../.agent-framework：缺失则打印"请 clone 框架"的完整步骤；存在则跑 selfcheck.py 并顺带 pull 框架。新项目可直接从框架 shared/hooks/project-bootstrap/ 复制这三件到自身 .githooks/。

4. 会话启动自检（建议）：

   python ../.agent-framework/shared/selfcheck.py

注入通道说明：主权层依靠第 2 步的全局软链（文档保证必加载），这是可靠通道。第 3 步的 instructions 父级 ../ 路径是否生效取决于 opencode 版本（官方示例多为项目内路径），不作为可靠通道；即便生效也只是锦上添花（额外注入经验索引 index.json 软层）。两者并存无冲突，且全局软链优先保证宪法落地。

优先级与单一来源

• 约束优先级：框架 AGENTS.md（总约束） > 项目 AGENTS.md > skill/经验软层；冲突以框架为准。
• 规则源只有一份：shared/guard/lexicon.json。守卫与 compaction 插件都读它，项目不得另存副本。
• 经验升格：复习时由模型与用户共同决定是否把项目 docs/experience.md 的可抽象部分写回 shared/experience/index.json / 本文件；不自动晋升。

跨设备同步纪律

• 框架为独立 git 仓库；改框架后需自行 commit + push。
• 项目 git push 时，pre-push 闸门检查框架状态：脏→提示先提交；领先→询问一并推送；落后→提示先 pull。交互终端下询问，非交互下仅警告不阻塞。
• pull 后自动完整性自检：shared/hooks/post-merge 与 post-checkout 在每次 pull/clone/checkout 后自动运行 selfcheck.py。项目仓库的 core.hooksPath 同样指向该目录，故拉取项目时会顺带同步框架库并复检完整性——确保跨设备协作时框架始终最新且文件完整。自检报"必需文件缺失"即视为框架损坏，需从远端重新 clone/修复。
• 开工前建议先 cd .agent-framework && git pull，避免引用到旧状态。

自检

python ../.agent-framework/shared/selfcheck.py            # 框架内部
python ../.agent-framework/shared/selfcheck.py <项目目录>   # 额外校验项目接线

检查：框架仓库存在/干净/与远端同步、lexicon id ⊆ AGENTS id、项目 instructions 是否接入框架。