元序 yotta-workflow

元序（yotta-workflow）

本文件是全局层标准：所有项目共享同一套工作流程。状态文件位置按规则判定（见下）。

核心原则：流程全局定，状态就近存。开工必读状态，收工必留锚点。

---

快速判定（先看这节，30 秒决定要不要用）

这是全局层工作流标准，装上它就是为了让 AI 自动按此执行，不需要用户每次提醒。

---

这个技能与智能体自带记忆的关系（本质）

它不取代任何智能体的记忆，而是补足"自带记忆做不到"的那部分：跨智能体共享、跨会话续接、统一的项目状态真相源 + 强制流程。

智能体自带的记忆（如 AGENTS.md、CLAUDE.md、rules、memory/、会话内上下文）通常是单机、单智能体、无统一结构的，有几个局限：

• 只在"这一个智能体"里生效，别的智能体不读。
• 各产品各写各的，项目状态会碎成多份、产生多个真相源。
• 只提供"能存"，不规定"何时读、何时写、写什么"，靠 AI 自觉，容易漏。

本技能单独存在的价值：

• 跨智能体共用一套 .workflow 状态：任何智能体读同一份 → 单一真相源。
• 跨会话持久 + 无缝续接：进度/任务/决策/流水落成文件，下个会话一读即续。
• 强制流程纪律：开工必读 → 进行中必记 → 收工必留锚点，不依赖 AI 自觉。
• 状态结构统一：STATE / TASKS / DECISIONS / ROADMAP / logs，AI 一读即知项目在哪、下一步做什么。

适用判断：

• 值得单独用：多智能体协作同一项目、项目要长远跨会话做、或希望项目状态不碎成 N 份。
• 不必单独用：只用单一智能体、自带记忆够用、项目很轻 → 自带记忆即可，本技能是锦上添花。

---

〇、状态文件位置判定规则

说明：状态目录是项目内的共享隐藏目录，统一固定为 .workflow\（名称以 . 开头）。对同一项目，任何智能体会话（无论 Codex / Cursor / Hermes / OpenCode…）都读写这一份共享状态目录，以此保证"不同智能体协作共用一套状态"成立——而不是各智能体各建一份（那样会产生多个真相源，上一程记的状态下一程读不到）。技能可被安装分发到多个智能体，但状态目录命名与所用智能体无关，永远落在同一个 .workflow\。

不要假设存在一个固定的"默认项目目录"。 各个智能体/宿主给"未指定项目"的会话分配的默认工作目录并不相同（有的按会话自动建临时目录，有的叫 projects 等），因此必须以**本次会话开始时的当前工作目录（cwd）**为基准来定位状态，而不是写死某个路径。

「统一工作区根目录」常为用户自己建的（如为了把项目数据集中到某个盘目录方便备份），那属于用户的工作约定，不是智能体默认；用户给了就用它做基准，但在通用技能里不要写成任何具体路径。

第一步，确定基准目录（base）：

• 已指定 / 已锚定项目目录（含用户自建的统一工作区根目录）→ base = 用户指定的项目根目录 / 工作区根目录。
• 未指定项目目录（临时会话 / 无固定工作目录）→ base = 会话开始时宿主给的当前工作目录（cwd），AI 启动时读取即可，不要写死。

第二步，根据 base 的形态定状态目录：

• base 本身就是一个项目根目录（含项目标识，如 .git、项目配置、或用户明确指向的单一项目）→ 状态文件放 base 下 .workflow\

  \.workflow\
  ├── STATE.md
  ├── TASKS.md
  ├── DECISIONS.md
  ├── ROADMAP.md
  └── logs\
      └── YYYY-MM-DD.md
  

• base 是工作区根目录（下面并列多个项目子目录）→ 按项目名建子目录：\<项目名>\.workflow\（结构同上）。

判定口诀：先取 cwd，再看它是不是项目根；是项目根就就近存，是工作区就按项目名分开存；状态目录统一用 .workflow，与所用智能体无关；全程不写死任何默认/固定路径。

项目名取项目根目录名（同名冲突时附加路径哈希）。

---

一、项目状态体系

状态文件结构（两种位置下结构一致）。所有状态文件与流水日志都存放在本项目自己的 .workflow\ 状态目录下（位置见「〇」），项目之间互不共享、互不读写：

文件首行格式约定：

• STATE.md 首行：# 项目状态，下面依次为 ## 当前进度、## 最近决定、## 遗留问题、## 下一步
• TASKS.md 首行：# 任务清单，用 - [ ] 待办 / - [x] 已完成 / - [~] 进行中
• logs/：每天一个文件，文件名用日期 YYYY-MM-DD.md（如 2026-08-05.md）。首行 # 流水日志 YYYY-MM-DD，同一天内按时间先后顺序追加；跨天则新建当天文件。短期回顾读当天文件，长期回顾用目录按需翻查
• DECISIONS.md 首行：# 决策记录，每条 ### 决策：一句话 | 日期，含背景、决定、理由、备选
• ROADMAP.md 首行：# 路线图，分 ## 长期目标、## 下一步计划

---

二、开工协议（每次会话开始必做）

1. 按「〇、状态文件位置判定规则」确定状态目录，检查 .workflow\STATE.md 是否存在。
2. 存在 → 完整读取 STATE.md、TASKS.md、ROADMAP.md、DECISIONS.md，最近几天的 logs/*.md 首屏，恢复上下文。
3. 不存在 → 视为新项目，按「一、项目状态体系」初始化全部文件，写入项目背景和首个目标，然后向用户确认定位是否准确。
4. 一个会话一个里程碑：根据 ROADMAP.md 确定本次只交付一个里程碑/目标，不散开做多件事；做完就收工开新会话，别让单个会话聊太长而失忆。
5. 若用户给了交接话术（收工锚点），优先按锚点内容恢复上下文，再与状态文件交叉核对。

---

三、进行中协议（主动及时写，不靠记忆）

整个会话过程中主动维护状态，不靠对话记忆（上下文会被自动压缩）：

1. 任务推进：每开始/完成一项任务，同步更新 TASKS.md（勾选、移状态），用 todo 工具辅助跟踪。
2. 主动及时写流水：每做完一件事就追加到当天的 logs/YYYY-MM-DD.md（不存在则新建），不攒到收工。流水记"做了什么、产出什么、踩了什么坑"。
3. 决策落盘：做出影响项目方向的决定（技术选型、命名、放弃某方案）时，当场写入 DECISIONS.md，写明背景和理由。
4. 进度快照：STATE.md 的"当前进度"保持最新，这是下个会话恢复的关键，不能滞后。
5. 记忆分层（该记什么 / 不记什么）：
   • 要记（写入本项目 .workflow）：
     • 项目进度快照（当前做到哪、下步是什么）→ STATE.md
     • 任务清单与状态（待办/进行中/完成）→ TASKS.md
     • 影响方向的决策（技术选型/命名/放弃方案 + 背景理由）→ DECISIONS.md
     • 长期目标与下一步计划 → ROADMAP.md
     • 每天做了什么、产出、踩坑 → logs/YYYY-MM-DD.md
   • 不记 / 不写：
     • 一次性闲聊、纯礼貌话、无长期价值的临时话
     • AI 人格 / 用户偏好 / 称呼 / 关系 / 跨项目通用知识（非项目状态，不写入本技能状态文件）
6. 防上下文压缩失忆：凡是"下一个会话需要记得"的关键信息，必须已经写进上面的文件，不能只留在对话里；发现上下文变长/将被压缩时，先把关键状态落盘再继续。

---

四、收工协议（每次会话结束必做）

用户说 "收工" 或接近收尾的表述时，依次执行；完成一个里程碑/一个任务后，也主动抛出下个会话的交接锚点，引导用户开新会话，避免单会话聊太长失忆。

1. 更新 STATE.md：重写"当前进度""最近决定""遗留问题""下一步"。
2. 更新 TASKS.md：核对所有任务状态。
3. 追加 logs/YYYY-MM-DD.md：写一条本次会话流水（做了什么、产出什么、遗留什么），跨天则新建当天文件。
4. 更新 ROADMAP.md：勾掉已完成项，调整下一步。
5. 生成 交接话术（下文的锚点），原样输出给用户复制。

---

五、交接话术模板（收工锚点）

收工时给用户原样输出下面这段，用户直接复制发给下一个会话。锚点必须自包含——新会话只凭这段文字就能无痛接续。

全局统一格式（必须遵守，所有项目/会话完全一致）：

• 先输出一行标题：给你的下个会话锚点。
• 再用 markdown 语言围栏把锚点正文包起来（三层反引号：开头 markdown、结尾 ）。
• 禁止用普通段落、非围栏代码块或其它语言标签；确保可一键复制、格式统一。

给你的下个会话锚点

【会话交接锚点】
项目：<项目名>（<一句话定位>）
路径：<项目根目录绝对路径>

上次会话结束于：<日期>

当前进度：
- <要点 1>
- <要点 2>

已完成：
- <要点 1>
- <要点 2>

下一步（按优先级）：
1. <事项>
2. <事项>

关键决定（详情见 DECISIONS.md）：
- <决定 1 及理由>

遗留问题 / 注意：
- <风险、坑、待确认事项>

开工请先读取：`.workflow\STATE.md`、TASKS.md、ROADMAP.md（状态目录位置见「〇、判定规则」）

收工时锚点里的内容必须与状态文件一致，不得凭空编写。

六、强制执行条款

• 任何项目会话，未读状态文件前不得声称"了解项目情况"。
• 任何会话结束，未更新状态文件前不得声称"已保存进度"。
• 交接锚点未生成，不得说"下次继续也行"。
• 状态文件是唯一真相源，与对话记忆冲突时以状态文件为准。

---

七、与既有项目机制的协调

• 项目已有自己的交接/状态机制：沿用其机制，不必强制迁移到本标准结构，但必须满足两个强制点——开工先读状态再声称了解；收工更新状态并留锚点。
• 新项目 / 无既有机制：按「〇、判定规则」初始化状态目录，完整执行本协议。