Agent 项目文件统一管理器

要解决的问题

AI 辅助项目通常会在几个星期里长成一团乱麻：文件散落各处，AI 每次开会话都要重新猜项目结构；同一个错误反复出现，上次验证过的参数这次又被换回了错误版本；你问「哪个才是最终版」，没人能回答。换模型、换 Agent、换会话之后上下文全部丢失，AI 只能从零重新理解项目。

平台自带的项目记忆能缓解一部分，但它只是上下文来源，不是权威事实库。它记得你通常怎么工作，却分不清当前哪个文件才是权威版本。

这个技能做了什么

Project Governance 给项目加一层治理文件，把「这个项目现在必须怎么工作」写成可执行的规范。初始化时从 templates/ 生成 11 个文件：

• AGENTS.md：项目协议，含核心治理规则、权威等级、首次运行协议、权限分区、信任边界
• index.md + index_notes.json：权威目录地图，带可点击链接与简短备注
• VERSIONS.md：稳定版本索引，含人工判断
• LESSONS.md：AI 错误与纠正日志
• session_handoff.md：会话结束交接
• CHANGELOG.md：决策与版本历史
• whitelist.json / blacklist.json：已验证 / 已失败参数注册表
• ARCHITECTURE.md / PROJECT.md：架构与项目卡片

核心是一套冲突时的权威优先级：当前项目文件 / 冻结版本 → 治理文件 → 项目记忆 → 用户长期记忆 → AI 推测。记忆与治理文件冲突时，治理文件优先；从记忆中学到的持久约定，必须经人工确认后才能沉淀进治理文件。

日常使用分四步：初始化（除非传 --force，否则不覆盖已有文件）；定制 AGENTS.md 里的目录权限分区、自主权等级和项目专属规则，通用核心规则保持原样；每个会话开始时读 index.md、session_handoff.md、LESSONS.md，工作中通过索引找文件、新错误记入日志，会话结束时更新三个交接文件；最后用 scripts/governance.py 跑 init / validate / index / check 校验。

失败处理有一条硬规则：绝不伪造「通过」结果。init 失败就报告具体命令与原因，不做部分初始化；validate 报 schema 错误就修注册表条目，不绕过校验；check 失败先 index 再重跑，仍失败则报给人类。

适用边界

一次性问答或小改动不需要这套东西，项目级约定本身就是负担。已有成熟治理体系时，直接改现有文件即可，不必重新初始化。另外，治理文件是规范而非自动执行器，Agent 是否遵守取决于平台对 AGENTS.md 的支持程度；多团队多仓库项目可能需要自行扩展模板。

governance.py 仅依赖 Python 标准库，无网络、无第三方依赖，可跨平台运行，但自动发现机制因平台而异，Trae 之外可能需要手动接入。