Upgrade¶

将 v1.5.0 项目迁移到 v2¶

v2 把 AGENTS.md 留在项目根目录，Memory Bank 文件则移到 tabilet/ 下，包括 GOAL.md、memory-bank/、evolution/、归档和已退役的历史。其他项目文档仍留在根目录。安装 v2 绝不会移动这些文件；v2 技能和 API 运行器一碰到旧版布局或混合布局就停下。 v2 的 DSH 侧边栏能以只读方式显示 v1.5.0 项目，并给出迁移警告。

用 Upgrade 技能随附的标准库命令，或者 v2 源码检出里的同一个文件。起点是已提交、干净的 Git 工作区：

python3 /path/to/skills/skills/memory-bank-upgrade/migrate-v1.5-to-v2.py /path/to/project
python3 /path/to/skills/skills/memory-bank-upgrade/migrate-v1.5-to-v2.py /path/to/project --apply

第一条命令只预览文件操作。--apply 才真正移动文件、更新需要维护的说明和索引，同时逐字节保留冻结归档和退役记录，最后把差异留着不提交，方便评审。其他项目文档里的路径引用它也会列出来，交给你人工核对。全部退役的项目、只做归档的预检、缺失或自定义的 goal 协议，以及本地策略，它一样支持。对于那些没改动过的 v1.5.0 GOAL.md，它会把唯一那处路径示例更新成 v2 的位置。自定义过的 GOAL.md 则逐字节保持原样，而且每次都会被标出来，要求人工核对路径。

中途被打断，就用 --resume 跑同一条命令。继续之前，它会检查三样东西：受跟踪项目文件之外的临时日志、Git HEAD，以及每个计划处理的文件哈希。遇到说不清的部分布局、符号链接或目标冲突，它会停下来等人工修复。全部完成之后，再跑一次不会产生任何改动。

评审完差异和项目检查之后，按你项目的常规策略提交。工作流规则如果也要更新，就用下面的 Upgrade，那是另一次独立的获批合并。

升级工作流规则¶

通过获批的合并升级现有记忆库的工作流规则，同时保留项目计划、本地策略和历史。

在你自己项目的会话里发送这个请求：

智能体	对话请求
Claude Code 插件	`/memory-bank:memory-bank-upgrade`
Codex 插件	`$memory-bank:memory-bank-upgrade`
DSH	`/memory-bank-upgrade`

可选参数：你想采用的工作流变更。

技能文件夹如果是直接安装的，请参见调用前缀。

何时使用它¶

装完新技能之后，你想让现有项目采用新的工作流规则，就用这个技能。

项目必须已经有一套里程碑/状态文件，已经全部退役但索引历史仍然有效的项目也算。应用获批的升级之前，先暂停同一账本上正在进行的其他执行。

光装上更新后的技能，没法安全地重写每一个用过旧版本的项目。这些项目有自己的命令、策略、计划和历史。安装永远不会迁移项目。 采用靠的是这个技能，而且必须你点头才会动手。

三个阶段¶

先检查对照。 Upgrade 会把项目已经采用的工作流，跟技能里随附的参考模板逐项对比。有了这个包，检查目标既不用检出，也不用联网。它会找出缺失的规则、可以沿用的本地写法、有意排除的项，以及需要你拍板的冲突。

再提方案等批准。 它给出具体的文件操作，是聚焦到章节的差异，而不是把整份文档重述一遍，然后就等你批准。

最后应用并验证。 批准之后它应用作用域内的合并，再验证保留是否真的生效。

一个有用的请求¶

Use memory-bank-upgrade to compare this project's workflow with the bundled
contract. Preserve our plans, local policies, task states, IDs, review counts,
and history. Show the complete proposed file changes before writing.

哪些内容会保留¶

任务状态、永久标识符、本地策略、评审计数器、自定义 goal 协议、已完成的证据，以及冻结历史。已经兼容的项目一处都不用改。

Upgrade 可以采用可选的阶段规则，而不创建阶段文件或移动现有工作。想引入阶段，或者撤回已获批的待处理任务以便以后重新规划，请用 Propose。

现有 goal 协议与启动参考¶

goal 协议现在随技能提供，项目不再保留副本。发现现有 tabilet/GOAL.md 时，Upgrade 会用自带的 goal-protocol.json 对它分类，并把结果写进完整方案。先解析明确的 GOAL_PROTOCOL；已被选作完整替代协议的文件会保留，不按附录删除或精简：

与已发布标准副本逐字节相同：建议删除；
带本地改动的完整协议副本：列出相对最接近发布版本的本地差异，建议精简为这些项目专有规则；在精简之前，goal 运行会停止；
其他（简短附录或项目记录）：保留为项目附录。

Upgrade 从不写出合并后的协议。它还会改写 AGENTS.md 和 milestone.md 中把 tabilet/GOAL.md 当作协议的指向，并把模板的“范围之外”清单作为可选采纳项提出。

删除或精简文件前，Upgrade 会检查整个项目中仍在维护的入站链接，并把修复列入方案。当前执行指向选择捆绑协议和可选附录。未冻结的历史引用保留记录的版本与路径，并明确标为历史来源，不用今天的协议替代以前的批准语义。冻结记录保持字节不变，其中的原始路径按来源提交的上下文解析。如果必要引用无法解析，就先保留文件，等待获批的解决方案；删除标准副本不能留下没有解释的断链。

如果也存在 tabilet/memory-bank/suggested.txt，Upgrade 会提议按整个当前已批准活动范围刷新它。加入 GOAL_IDENTITY 块，保留明确的顺序或优先级、提交、集成、外部修改和范围策略。始终写出 AUTHORIZATION_GRANTS，没有明确授予提议时用 {}；非空提议仍标为未批准。现有授予文字不能继承以前运行的批准。要求只保留在里程碑规格中；删除过时历史 ID 前先协调其处置。

更新前须批准完整文件操作方案。缺失的可选文件默认继续缺失；不兼容启动参考需要明确决定保留或删除。全部已退役的项目不会获得可执行 ID。这些更新不启动 goal，也不激活授予；已经兼容的文件保持不变。

升级不是什么¶

升级采用的是一套运行规则。它不会顺手帮你初始化项目、实现工作、提交或退役里程碑。

退役旧里程碑是另一件独立的工作，需要自己的作用域，也需要自己的关闭证据。单独安装的 API 运行器，也要自己再做一次兼容性检查或更新。

采用授权指导¶

可选的里程碑 AUTHORIZATION_REQUIREMENTS 和请求 AUTHORIZATION_GRANTS 须作为明确批准的合并来采用。保留项目限制，并在方案中协调冲突。声明只保留在里程碑规格中；状态前言只引用它。升级指导不会激活提议授予，也不授权执行。

缺少字段的现有项目保留原行为；安装不触发迁移或增加权限。不创建批准台账或审计依赖，不修改冻结历史。 Python API 授权边界仍由原合同约束。详见授权指南。

采用长期记忆¶

项目如果已经积累了好几个月的历史，这个技能就是最要紧的一个，因为 lessons.md 和里程碑退役正是靠它，才进得去一个比它们更早的项目。

现有项目得显式采用这两样能力。不存在自动的批量迁移，退役也遵守每一种提交策略。

如果 DSH 报告兼容性警告¶

就算仪表盘读不全记录，你照样可以准备 Upgrade 请求。Insert into empty draft 只是准备好文本；真正发送出去，才是让智能体检查并提出变更。它并不代表你批准了合并。

把警告一并放进对话：侧边栏是把警告和请求文本分开显示的。在提修正方案之前，先让智能体分清哪些是不受支持的旧语法、哪些才是真正的账本冲突。ID、状态、备注、评审证据和历史都要保留，不要为了消掉警告就批量重写它们。

保留协议与模型选择¶

目标运行已获准且所选主导协议可用、兼容时，可以刷新启动输入；不要求项目存在 tabilet/GOAL.md。保留明确的 GOAL_PROTOCOL 及实际路径、哈希、调用方式和包身份，只有选择标准协议时才使用捆绑元数据。切换协议需要明确批准；协议不可用时暂停刷新并保留现有输入。不能按标准附录的清理规则删除或精简已被选作替代完整协议的文件。

旧的暂停目标没有 GOAL_IDENTITY 时，展示旧的批准身份和新解析结果；变化或不确定时需要一次批准，保留授予、拒绝、评审计数、尝试用量与限制。保留明确的 MODEL_POLICY，只在用户要求时提出该策略；省略则沿用宿主设置。升级不会激活模型路由或恢复目标。