@yottameta/yotta-workflow 0.2.6 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@
 
 <h1 align="center">yotta-workflow · 元序 (Yuanxu)</h1>
 
-<p align="center">A universal workflow standard for all AI agents: <b>the process is set globally, the state is stored nearby; read the state on start, always leave a handoff anchor on finish</b>. Lets any AI conversation resume painlessly and avoids amnesia from overlong single sessions.</p>
+<p align="center">A universal workflow standard for all AI agents: <b>the process is set globally, state follows the project root; read the state on start, always leave a handoff anchor on finish</b>. Lets any AI conversation resume painlessly and avoids amnesia from overlong single sessions.</p>
 <p align="center">State directory is unified as <code>.workflow</code> — all agent sessions of the same project read and write the same state (one source of truth); on start, read the state to restore context; while working, actively persist logs / tasks / decisions; on finish, generate a self-contained handoff anchor.</p>
 <p align="center">Pure Markdown text, zero dependencies, no injection, no platform lock; install once, works across 78+ agents such as Claude Code / Codex / Cursor / OpenCode.</p>
 
@@ -29,12 +29,12 @@ yotta-workflow distills "cross-session collaboration" into an agent-agnostic pro
 - **When to read, when to write?** — read on start, write actively while working, always leave an anchor on finish.
 - **How to hand off?** — a fixed template generates a self-contained handoff anchor; the next session resumes painlessly from just that anchor.
 
-It depends on no specific agent or platform: the state is just Markdown files under the project directory, readable and writable by any agent or tool.
+It depends on no specific agent or platform: the state is just Markdown files under the project root, readable and writable by any agent or tool.
 
 ## Core value
 
 - **One source of truth** — all agent sessions of the same project read and write the same `.workflow\` state directory, instead of each building its own and keeping separate records.
-- **State stored nearby** — state location is decided from the session cwd, never a hard-coded default path; a project root stores nearby, a workspace root stores per-project by name.
+- **State follows the project root** — `.workflow` belongs to the project root, not to a source checkout or a workspace container; an existing `.workflow` is always reused in place and never auto-migrated.
 - **Proactive anti-amnesia** — every completed action is written to logs / tasks / decisions while working, not relied on in-conversation memory (context gets auto-compressed).
 - **Self-contained handoff** — on finish, generate a fixed-format handoff anchor; the next session restores full context from the anchor plus state files.
 - **Compatible with existing mechanisms** — if the project already has its own handoff / state mechanism, keep it, only satisfying two mandatory points: read state on start, update state and leave an anchor on finish.
@@ -45,7 +45,7 @@ It depends on no specific agent or platform: the state is just Markdown files un
 |---|---|
 | **Cross-agent unified** | follows the Agent Skills open standard (agentskills.io); install once, 78+ agents share one state protocol |
 | **One source of truth** | unified `.workflow` state directory; any agent of the same project reads/writes the same state, eliminating multiple sources of truth |
-| **Automated path detection** | take cwd → decide project root vs workspace → store nearby or separated by project name; never hard-code a path |
+| **Automated path detection** | explicit root → nearest existing `.workflow` → project root / source directory / workspace classification; never hard-code a path |
 | **Proactive persistence** | immediately write logs / tasks / decisions while working, so context compression never loses key state |
 | **Self-contained handoff anchor** | fixed template + enforced validation (content must match state files); next session resumes painlessly |
 | **Lightweight zero-dependency** | plain Markdown files, no daemon / database / injection; readable and writable on any platform |
@@ -54,16 +54,29 @@ It depends on no specific agent or platform: the state is just Markdown files un
 
 ## Protocol details
 
-### State file location rule (memo)
+### Path model and state file location rule
 
-**First take the cwd, then see whether it is a project root; if it is a project root, store nearby; if it is a workspace, store per project name; the state directory is always `.workflow`, independent of the agent used; never hard-code any default / fixed path.**
+**First distinguish three concepts: the project root owns the whole project state and is the only anchor for `.workflow`; the source directory is normally a code subdirectory under the project root; a workspace root is only a container for multiple project roots.**
 
-| base form | state directory |
-|---|---|
-| project root directory (contains `.git`, project config, or explicitly pointed-to single project) | `<base>\.workflow\` |
-| workspace root directory (multiple project subdirs side by side) | `<base>\<project name>\.workflow\` |
+| Directory | Definition | Where `.workflow` goes |
+|---|---|---|
+| **Project root** | Parent directory that owns the whole project state and normally contains both `.workflow` and the source directory | `<project root>\.workflow\` |
+| **Source directory** | Code directory under the project root; it may have its own `.git` | Not there, unless the user explicitly says it is also the project root |
+| **Workspace root** | Container holding multiple project roots; it owns no project state | Not there; choose the relevant project root first |
+
+```text
+<project root>\
+├── .workflow\         # state; directly under the project root
+└── <source dir>\      # source directory; under the project root
+```
 
-> A user-specified project directory / unified workspace root uses the user's convention as the base; if unspecified, use the session start cwd as the base.
+**Resolution order (two signals only):**
+
+1. The user explicitly specifies a project root → use it.
+2. Walk upward from the cwd and use the nearest existing `.workflow\STATE.md`; its parent is the project root. Keep it in place; **never auto-migrate it**.
+3. If neither signal exists, stop and ask: `What is this task's project root directory?` Do not infer it from `.git`, `package.json`, `src`, `README`, the cwd, or directory structure.
+
+> This skill defines only the standard layout and state location. How a real project names or layers its source directories is left to the user to adapt.
 
 ### Project state system (five file types)
 
@@ -174,14 +187,22 @@ bash install.sh --list           # list agents -> default directories
 
 ## FAQ
 
-- **Where is the state directory?** First check whether `.workflow\` exists under the project; if not, locate it by the "state file location rule" using the session cwd as the base.
+- **Where is the state directory?** Accept an explicitly specified project root first; otherwise walk upward from the cwd to find an existing `.workflow\`. If neither exists, ask. State always lives at `<project root>\.workflow\`, not in a source directory or workspace root.
 - **Multiple agents out of sync?** Confirm they point to the same project directory (the same `.workflow\`). This skill is designed to share one state; if each built its own `.workflow`, the project directory differs.
+- **The source directory has `.git`; should state live there?** Not by that signal alone. State belongs under the project-root `.workflow`; the user decides how source directories are organized.
 - **Project already has its own handoff mechanism?** Keep it, only satisfying the two mandatory points: read state on start, update state and leave an anchor on finish.
 
 ## Development & checks
 
 Run inside this project: `python tools/validate-skill.py yotta-workflow`.
 
+## References
+
+- references/faq.md
+- references/path-model.md
+- references/walkthroughs.md
+- references/exception-playbook.md
+
 ## License
 
 MIT © YottaMeta

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 <h1 align="center">yotta-workflow · 元序</h1>
 
-<p align="center">一套面向所有 AI 智能体的通用工作流标准：<b>流程全局定、状态就近存；开工必读状态，收工必留锚点</b>。让任何 AI 会话都能无痛接续，避免单会话拉长而失忆。</p>
+<p align="center">一套面向所有 AI 智能体的通用工作流标准：<b>流程全局定、状态跟项目根目录；开工必读状态，收工必留锚点</b>。让任何 AI 会话都能无痛接续，避免单会话拉长而失忆。</p>
 <p align="center">状态目录统一 <code>.workflow</code>——同一项目所有智能体会话读写同一份状态（一个真相源）；开工读状态恢复上下文、进行中主动落盘流水 / 任务 / 决策、收工生成自包含交接锚点。</p>
 <p align="center">纯 Markdown 文本，零依赖、不注入、不锁平台；安装一次，Claude Code / Codex / Cursor / OpenCode 等 78+ 智能体通用。</p>
 
@@ -34,7 +34,7 @@ yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协
 ## 核心价值
 
 - **一个真相源**：同一项目所有智能体会话读写同一份 `.workflow\` 状态目录，不再各建目录、各记各的。
-- **状态就近存**：以会话 cwd 为基准判定状态位置，不写死任何默认路径；项目根就近存、工作区按项目名分开存。
+- **状态跟着项目根目录走**：`.workflow` 只放项目根目录，不放源码目录，也不放工作区根；已有 `.workflow` 就近沿用、不自动迁移。
 - **主动防失忆**：进行中每完成一件事就落盘流水 / 任务 / 决策，不靠对话记忆（上下文会被自动压缩）。
 - **自包含交接**：收工生成固定格式交接锚点，下个会话只凭锚点 + 状态文件即可恢复全部上下文。
 - **与既有机制兼容**：项目已有自己的交接 / 状态机制时沿用原机制，只需满足两个强制点——开工先读状态、收工更新状态并留锚点。
@@ -45,7 +45,7 @@ yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协
 |---|---|
 | **跨智能体统一** | 符合 Agent Skills 开放标准（agentskills.io），安装一次，78+ 智能体共用同一套状态协议 |
 | **一个真相源** | 状态目录统一 `.workflow`，同一项目任何智能体读写同一份状态，杜绝多真相源 |
-| **路径判定自动化** | 先取 cwd → 判断是项目根还是工作区 → 就近存或按项目名分开存；全程不写死路径 |
+| **路径判定无歧义** | 只认用户明确指定或向上找到已有 `.workflow`；两种证据都没有就先问，不靠 `.git` / cwd 猜 |
 | **主动式落盘** | 进行中即时写流水 / 任务 / 决策，上下文压缩也不丢关键状态 |
 | **自包含交接锚点** | 固定模板 + 强制校验（内容必须与状态文件一致），下个会话无痛接续 |
 | **轻量零依赖** | 纯 Markdown 文件，无 daemon / 无数据库 / 无注入；任何平台可读可写 |
@@ -54,16 +54,29 @@ yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协
 
 ## 协议详解
 
-### 状态文件位置判定（口诀）
+### 路径模型与状态文件位置判定
 
-**先取 cwd，再看它是不是项目根；是项目根就就近存，是工作区就按项目名分开存；状态目录统一用 `.workflow`，与所用智能体无关；全程不写死任何默认 / 固定路径。**
+**先分清三个概念：项目根目录是拥有整个项目状态的目录，也是 `.workflow` 的唯一锚点；源码目录默认是项目根目录下的代码子目录；工作区根只是并列多个项目根目录的父目录。**
 
-| base 形态 | 状态目录 |
-|---|---|
-| 项目根目录（含 `.git`、项目配置，或用户明确指向的单一项目） | `<base>\.workflow\` |
-| 工作区根目录（下面并列多个项目子目录） | `<base>\<项目名>\.workflow\` |
+| 目录 | 定义 | `.workflow` 放哪 |
+|---|---|---|
+| **项目根目录** | 拥有整个项目状态的父目录；默认承载 `.workflow` 和源码目录 | `<项目根目录>\.workflow\` |
+| **源码目录** | 项目根目录下的代码目录；可以有独立 `.git` | 不放，除非用户明确说明它同时就是项目根目录 |
+| **工作区根目录** | 并列多个项目根目录的容器；不拥有某个项目的状态 | 不放；先选具体项目根目录 |
+
+```text
+<项目根目录>\
+├── .workflow\         # 工作流；直接放在项目根目录
+└── <源码目录>\        # 源码目录；位于项目根目录之下
+```
 
-> 用户指定的项目目录 / 统一工作区根目录按用户约定作为基准；未指定时以会话开始时的 cwd 为基准。
+**定位顺序（只认两种证据）：**
+
+1. 用户明确指定项目根目录 → 直接用。
+2. 从 cwd 向上查找已有的 `.workflow\STATE.md` → 找到最近的，其父目录就是项目根目录；**永不自动迁移**。
+3. 两种证据都没有 → 先问“项目根目录是哪一个？”，不得用 `.git`、`package.json`、`src`、`README`、cwd 或目录结构自行猜测。
+
+> 本技能只规定标准形态与状态位置；实际项目中源码目录怎么命名、怎么分层，由用户按项目情况调整。
 
 ### 项目状态体系（五类文件）
 
@@ -174,14 +187,22 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 
 ## 常见问题
 
-- **状态目录在哪？** 先看项目下是否存在 `.workflow\`；不存在时按「状态文件位置判定」规则以会话 cwd 为基准定位。
+- **状态目录在哪？** 先认用户明确指定的项目根目录，再从 cwd 向上找已有 `.workflow\`；两者都没有就先问。状态始终放 `<项目根目录>\.workflow\`，不放源码目录或工作区根。
 - **多个智能体状态不同步？** 确认它们指向同一项目目录（同一份 `.workflow\`）。本技能设计为共享一份状态；若各自建了 `.workflow`，说明项目目录不一致。
+- **源码目录里有 `.git`，状态应该放那里吗？** 不应只凭 `.git` 判断；状态只放项目根目录下的 `.workflow`。源码目录的具体组织由用户决定。
 - **项目已有自己的交接机制？** 沿用原机制即可，只需满足两个强制点：开工先读状态、收工更新状态并留锚点。
 
 ## 开发与校验
 
 本项目内运行：`python tools/validate-skill.py yotta-workflow`。
 
+## 参考文档
+
+- references/faq.md
+- references/path-model.md
+- references/walkthroughs.md
+- references/exception-playbook.md
+
 ## 许可证
 
-MIT © YottaMeta
+MIT © YottaMeta

package/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: yotta-workflow
-description: "跨会话/跨项目通用工作流标准：让任何 AI 智能体活过会话——开工必读状态、状态就近存 .workflow、进行中自动记流水/任务/决策、收工必留交接锚点。触发：开工/接手项目、续测、收工、跨会话恢复、要落盘、多步开发、项目状态变化、跨智能体协作。项目型会话自动初始化 .workflow 状态目录并按本协议全程执行；轻量一次性问答不强制初始化。所有 AI 智能体通用。"
-version: 0.2.6
+description: "跨会话/跨项目通用工作流标准：让任何 AI 智能体活过会话——开工必读状态、状态只存项目根目录的 .workflow、进行中自动记流水/任务/决策、收工必留交接锚点。项目根目录是状态锚点，源码目录可嵌套且 .git 不等于项目根目录。触发：开工/接手项目、续测、收工、跨会话恢复、要落盘、多步开发、项目状态变化、跨智能体协作。边界：只记录项目状态（进度/任务/决策/流水），不写 AI 人格、用户偏好、关系或跨项目通用知识；轻量一次性问答不强制初始化。所有 AI 智能体通用。"
+version: 0.4.0
 license: MIT
 agent_created: true
 metadata:
-  short-description: 跨会话/跨项目通用工作流：开工读状态、收工留锚点
+  short-description: 跨会话工作流：状态只认项目根目录，开工读、收工锚点
 ---
 
 # 元序（yotta-workflow）
 
 本文件是**全局层标准**：所有项目共享同一套工作流程。状态文件位置按规则判定（见下）。
 
-核心原则：**流程全局定，状态就近存。开工必读状态，收工必留锚点。**
+核心原则：**流程全局定，状态跟项目根目录。开工必读状态，收工必留锚点。**
 
 ---
 
@@ -24,8 +24,8 @@ metadata:
 | --- | --- |
 | **这是什么** | 跨会话 / 跨项目的工作流协议：开工读状态 → 进行中记流水/任务/决策 → 收工留锚点。状态统一存本项目 `.workflow`。 |
 | **何时触发** | 涉及「项目」「续测」「跨会话」「要落盘」「多步开发」「收工」即触发；一次性只读问答不触发。 |
-| **怎么用（三步）** | ① 按「〇」定状态目录 → ② 存在就读 STATE/TASKS/ROADMAP/DECISIONS + 近期 logs；不存在就初始化 → ③ 全程按「二/三/四」执行，收工输出「五」锚点。 |
-| **是否初始化 `.workflow`** | **项目型会话**（有项目根 / 要落盘 / 多步开发）→ 自动初始化并全程执行；**轻量临时会话**（纯问答 / 一次性）→ 不初始化，只按需提示。 |
+| **怎么用（三步）** | ① 先按「〇」定位项目根目录，再定状态目录 → ② 存在就读 STATE/TASKS/ROADMAP/DECISIONS + 近期 logs；不存在就初始化 → ③ 全程按「二/三/四」执行，收工输出「五」锚点。 |
+| **是否初始化 `.workflow`** | **项目型会话**（能确定项目根目录 / 要落盘 / 多步开发）→ 自动初始化并全程执行；**轻量临时会话**（纯问答 / 一次性）→ 不初始化，只按需提示。 |
 | **AI 该记住什么** | 只记「项目状态类」：进度 / 任务 / 决策 / 流水。**不记**：AI 人格 / 用户偏好 / 关系 / 跨项目通用知识（非项目状态，不写入本技能状态文件）。 |
 ---
 
@@ -49,40 +49,84 @@ metadata:
 - **不必单独用**：只用单一智能体、自带记忆够用、项目很轻 → 自带记忆即可，本技能是锦上添花。
 ---
 
-## 〇、状态文件位置判定规则
+## 〇、路径模型与状态目录判定
 
-> 说明：**状态目录**是项目内的共享隐藏目录，统一固定为 `.workflow\`（名称以 `.` 开头）。**对同一项目，任何智能体会话（无论 Codex / Cursor / Hermes / OpenCode…）都读写这一份共享状态目录**，以此保证"不同智能体协作共用一套状态"成立——而不是各智能体各建一份（那样会产生多个真相源，上一程记的状态下一程读不到）。技能可被安装分发到多个智能体，但状态目录命名与所用智能体无关，永远落在同一个 `.workflow\`。
+> 这一节解决一个高频混淆：**项目根目录不等于源码目录，`.git` 也不能单独决定项目根目录。** 状态跟着项目根目录走，不跟着某一个代码仓库走。
 
-**不要假设存在一个固定的"默认项目目录"。** 各个智能体/宿主给"未指定项目"的会话分配的默认工作目录并不相同（有的按会话自动建临时目录，有的叫 `projects` 等），因此必须以**本次会话开始时的当前工作目录（cwd）**为基准来定位状态，而不是写死某个路径。
+### 1. 三个概念（一句话分清）
 
-> 「统一工作区根目录」常为用户自己建的（如为了把项目数据集中到某个盘目录方便备份），那属于**用户的工作约定**，不是智能体默认；用户给了就用它做基准，但在通用技能里不要写成任何具体路径。
+| 概念 | 定义 | 是否放 `.workflow` |
+| --- | --- | --- |
+| **项目根目录** | 拥有这个项目全部状态的目录；源码、文档、素材、配置都可以放在它里面。它不要求有 Git。 | **放这里**：`<项目根目录>\.workflow\` |
+| **源码目录** | 存放代码、资源或某个 Git 仓库的目录；它只是项目内部的一个位置。 | 不放；除非用户明确说明“它同时就是项目根目录” |
+| **工作区根目录** | 下面并列放着多个项目根目录的父目录；它不拥有某一个项目的状态。 | 不放；先选具体项目根目录，再放到项目根目录下 |
 
-**第一步，确定基准目录（base）：**
-- **已指定 / 已锚定项目目录**（含用户自建的统一工作区根目录）→ `base` = 用户指定的项目根目录 / 工作区根目录。
-- **未指定项目目录**（临时会话 / 无固定工作目录）→ `base` = 会话开始时宿主给的**当前工作目录（cwd）**，AI 启动时读取即可，不要写死。
+一句话：**项目根目录 = 状态锚点；源码目录 = 实现位置；工作区根 = 项目容器。**
 
-**第二步，根据 base 的形态定状态目录：**
-- `base` **本身就是一个项目根目录**（含项目标识，如 `.git`、项目配置、或用户明确指向的单一项目）→ 状态文件放 `base` 下 `.workflow\`
-  ```
-  <base>\.workflow\
-  ├── STATE.md
-  ├── TASKS.md
-  ├── DECISIONS.md
-  ├── ROADMAP.md
-  └── logs\
-      └── YYYY-MM-DD.md
-  ```
-- `base` 是**工作区根目录**（下面并列多个项目子目录）→ 按项目名建子目录：`<base>\<项目名>\.workflow\`（结构同上）。
+标准形态（默认按这个理解）：
 
-判定口诀：**先取 cwd，再看它是不是项目根；是项目根就就近存，是工作区就按项目名分开存；状态目录统一用 `.workflow`，与所用智能体无关；全程不写死任何默认/固定路径。**
+```text
+<项目根目录>\
+├── .workflow\         # 工作流；始终直接放在项目根目录
+└── <源码目录>\        # 代码目录；位于项目根目录之下
+```
+
+标准只规定两件事：**`.workflow` 必须直接放在项目根目录下；源码目录属于项目根目录内部。** 实际项目里源码目录叫什么、放在哪一层、是否有特殊布局，由用户按项目情况调整，本技能不替用户改造项目结构。
+
+### 2. 唯一状态目录
+
+状态目录固定为 **项目根目录下的 `.workflow\`**：
+
+```text
+<项目根目录>\.workflow\
+├── STATE.md
+├── TASKS.md
+├── DECISIONS.md
+├── ROADMAP.md
+└── logs\
+    └── YYYY-MM-DD.md
+```
+
+**对同一项目，任何智能体会话（无论 Codex / Cursor / Hermes / OpenCode…）都读写这一份 `.workflow\`**，不得因为使用的智能体不同而另建一份。
+
+以下信号都**不能单独判定项目根目录**：`.git`、`package.json`、`src`、`app`、`README`、当前目录是不是 Git 仓库根。它们只能说明当前目录“像源码”，不能说明它“拥有整个项目”。
+
+### 3. 判定顺序（从强到弱）
+
+项目根目录只认两种证据，按顺序执行：
+
+1. **用户明确指定项目根目录**（直接说项目根目录、给出交接锚点的“路径”，或确认“当前目录就是项目根目录”）→ 这是项目根目录。
+2. **从 cwd 向上查找已有 `.workflow\STATE.md`** → 找到最近的一份；它所在的父目录就是项目根目录。**已有 `.workflow` 永不自动迁移、复制或重建。**
+3. **两种证据都没有** → **停止初始化，先问一个问题**：`这个任务的项目根目录是哪一个？` 不得用 `.git`、`package.json`、`src`、`README`、cwd 或目录结构自行猜测。
 
-项目名取项目根目录名（同名冲突时附加路径哈希）。
+如果用户明确说 cwd 就是项目根目录，则使用 cwd；如果用户说项目根目录在上层，则使用上层；如果用户给的是工作区根，则继续问具体项目根目录。判断依据永远来自用户或已有 `.workflow`，不来自目录里有什么文件。
+
+定位时只处理项目根目录；源码目录如何组织，不参与 `.workflow` 的位置判定。
+
+4. **不要写死任何默认路径。** 不同宿主给未指定项目的会话分配的 cwd 可能不同；不能把某个盘符或目录当通用默认。
+
+项目名取项目根目录名；同名冲突时附加路径哈希。
+
+> 兼容红线：本次规则只影响首次初始化和解释口径。任何已经存在的 `.workflow\` 保持原位，不因源码仓库嵌套、目录改名或规则升级而迁移。
+
+---
+
+## 〇·一、快速定位例子
+
+| 场景 | 项目根目录 | 状态目录 |
+| --- | --- | --- |
+| 标准形态 | `<项目根目录>` | `<项目根目录>\.workflow\` |
+| 用户明确指定项目根目录 | 用户指定的目录 | `<项目根目录>\.workflow\` |
+| 向上找到已有 `.workflow` | `.workflow` 的父目录 | 已有 `.workflow\`，原地沿用 |
+| 没有用户指定，也没有已有 `.workflow` | 先问 | 不创建 |
+
+更完整的路径走查见 `references/path-model.md`。
 
 ---
 
 ## 一、项目状态体系
 
-状态文件结构（两种位置下结构一致）。**所有状态文件与流水日志都存放在本项目自己的 `.workflow\` 状态目录下**（位置见「〇」），项目之间互不共享、互不读写：
+状态文件结构固定一致。**所有状态文件与流水日志都存放在本项目根目录的 `.workflow\` 状态目录下**（位置见「〇」），项目之间互不共享、互不读写：
 
 文件首行格式约定：
 - `STATE.md` 首行：`# 项目状态`，下面依次为 `## 当前进度`、`## 最近决定`、`## 遗留问题`、`## 下一步`
@@ -95,7 +139,7 @@ metadata:
 
 ## 二、开工协议（每次会话开始必做）
 
-1. 按「〇、状态文件位置判定规则」确定状态目录，检查 `.workflow\STATE.md` 是否存在。
+1. 按「〇、路径模型与状态目录判定」确定状态目录，检查 `.workflow\STATE.md` 是否存在。
 2. **存在** → 完整读取 `STATE.md`、`TASKS.md`、`ROADMAP.md`、`DECISIONS.md`，最近几天的 `logs/*.md` 首屏，恢复上下文。
 3. **不存在** → 视为新项目，按「一、项目状态体系」初始化全部文件，写入项目背景和首个目标，然后向用户确认定位是否准确。
 4. **一个会话一个里程碑**：根据 `ROADMAP.md` 确定本次只交付一个里程碑/目标，不散开做多件事；做完就收工开新会话，别让单个会话聊太长而失忆。
@@ -189,4 +233,11 @@ metadata:
 ## 七、与既有项目机制的协调
 
 - **项目已有自己的交接/状态机制**：沿用其机制，不必强制迁移到本标准结构，但必须满足两个强制点——开工先读状态再声称了解；收工更新状态并留锚点。
-- **新项目 / 无既有机制**：按「〇、判定规则」初始化状态目录，完整执行本协议。
+- **新项目 / 无既有机制**：按「〇、判定规则」初始化状态目录，完整执行本协议。
+
+## 八、参考文档
+
+- 常见问题：`references/faq.md`
+- 路径模型：`references/path-model.md`
+- 复杂场景走查：`references/walkthroughs.md`
+- 异常恢复手册：`references/exception-playbook.md`

package/bin/install.js

@@ -1,51 +1,97 @@
 #!/usr/bin/env node
 /**
- * yotta-workflow 跨平台安装器（YottaSkills）
- * 用法:
- *   npx -y @yottameta/yotta-workflow --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-workflow --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-workflow -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-workflow                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-workflow --list          # 列出智能体 -> 默认目录
+ * @yottameta/yotta-workflow cross-platform installer.
+ *
+ * Usage:
+ *   npx -y @yottameta/yotta-workflow --agent <name>
+ *   npx -y @yottameta/yotta-workflow --dir <path>
+ *   npx -y @yottameta/yotta-workflow -g
+ *   npx -y @yottameta/yotta-workflow
+ *   npx -y @yottameta/yotta-workflow --list
  */
 'use strict';
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
 const SKILL_NAME = 'yotta-workflow';
 const PKG_ROOT = path.join(__dirname, '..');
+const COPY_SKIP = new Set(['package.json', 'bin', 'node_modules', '.git', '.github', 'test']);
 
-// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
-// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
-// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
 const AGENT_DIRS = {
   claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
   cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
-  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] },
   gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
   goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
   amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
-  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] },
   windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
   workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
   kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
   trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
-  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
+  'trae-cn': { label: 'Trae IDE',         dirs: ['.trae-cn/skills'] },
   qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
-  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
+  comate:    { label: 'Comate',           dirs: ['.comate/skills'] },
   codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
   kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
-  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
+  agents:    { label: 'Generic AGENTS.md', dirs: ['.agents/skills'] },
 };
 
-// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
+class UsageError extends Error {}
+class TargetError extends Error {}
+class InstallError extends Error {}
+
+function usage() {
+  console.log('yotta-workflow installer');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx -y @yottameta/yotta-workflow --agent <name>  Install to an agent default directory');
+  console.log('  npx -y @yottameta/yotta-workflow --dir <path>     Install to a custom directory');
+  console.log('  npx -y @yottameta/yotta-workflow -g               Install to all known agent directories');
+  console.log('  npx -y @yottameta/yotta-workflow                  Auto-detect project-level directories');
+  console.log('  npx -y @yottameta/yotta-workflow --list           List supported agent directories');
+  console.log('');
+  console.log('Options:');
+  console.log('  --agent <name>  Agent key, see --list');
+  console.log('  --dir <path>    Custom skills directory');
+  console.log('  -g, --global    Install to all known user-level directories');
+  console.log('  --list, -l      List supported agents');
+  console.log('  -h, --help      Show this help');
+}
+
+function parseArgs(argv) {
+  const opts = { help: false, list: false, global: false, dir: null, agent: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--list' || arg === '-l') opts.list = true;
+    else if (arg === '--global' || arg === '-g') opts.global = true;
+    else if (arg === '--dir') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--dir requires a non-empty path');
+      opts.dir = value;
+    } else if (arg === '--agent') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--agent requires a non-empty name');
+      opts.agent = value.toLowerCase();
+    } else {
+      throw new UsageError('Unknown argument: ' + arg);
+    }
+  }
+  if (!opts.help) {
+    const selected = [opts.dir, opts.agent, opts.global].filter(Boolean).length;
+    if (selected > 1) throw new UsageError('Use only one of --dir, --agent, or -g');
+  }
+  return opts;
+}
+
 function codexUserDir() {
   const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
   return path.join(base, 'skills');
 }
 
-// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
 function opencodeUserDir() {
   const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
   return path.join(base, 'opencode', 'skills');
@@ -57,82 +103,65 @@ function resolveUserDir(rel) {
   return path.join(os.homedir(), rel);
 }
 
-function installTo(dest) {
-  const target = path.join(dest, SKILL_NAME);
-  fs.mkdirSync(target, { recursive: true });
-  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
-  console.log('installed -> ' + target);
-}
-
-function copyDir(src, dst, skip) {
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (skip.has(entry.name)) continue;
-    const s = path.join(src, entry.name);
-    const d = path.join(dst, entry.name);
-    if (entry.isDirectory()) {
-      fs.mkdirSync(d, { recursive: true });
-      copyDir(s, d, skip);
-    } else if (entry.isFile()) {
-      fs.copyFileSync(s, d);
-    }
-  }
-}
-
 function displayDir(rel) {
   if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
   return '~/' + rel;
 }
 
-function main() {
-  const args = process.argv.slice(2);
-  const isGlobal = args.includes('-g') || args.includes('--global');
-  const list = args.includes('--list') || args.includes('-l');
-  let explicitDir = null;
-  const di = args.indexOf('--dir');
-  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
-  let agent = null;
-  const ai = args.indexOf('--agent');
-  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
-
-  if (list) {
-    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
-    for (const [key, v] of Object.entries(AGENT_DIRS)) {
-      const resolved = v.dirs.map(displayDir);
-      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
-    }
-    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
-    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
-    return;
+function printList() {
+  console.log('Agent -> default skill directory:');
+  for (const [key, value] of Object.entries(AGENT_DIRS)) {
+    console.log('  ' + key.padEnd(12) + value.label.padEnd(20) + value.dirs.map(displayDir).join(', '));
   }
+  console.log('');
+  console.log('Use --dir <path> for agents not listed. CODEX_HOME and XDG_CONFIG_HOME are respected.');
+}
 
-  if (explicitDir) { installTo(explicitDir); return; }
+function assertSafeTarget(target) {
+  const rel = path.relative(PKG_ROOT, target);
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+    throw new UsageError('Target directory must be outside the skill source directory');
+  }
+}
 
-  if (agent) {
-    const info = AGENT_DIRS[agent];
-    if (!info) {
-      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
-      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
-      return;
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dst, entry.name);
+    try {
+      if (entry.isDirectory()) {
+        fs.mkdirSync(to, { recursive: true });
+        copyDir(from, to, skip);
+      } else if (entry.isFile()) {
+        fs.copyFileSync(from, to);
+      }
+    } catch (err) {
+      throw new InstallError('Failed to copy ' + from + ' -> ' + to + ': ' + err.message);
     }
-    installTo(resolveUserDir(info.dirs[0]));
-    console.log('完成。');
-    return;
   }
+}
 
-  if (isGlobal) {
-    const seen = new Set();
-    for (const v of Object.values(AGENT_DIRS)) {
-      for (const d of v.dirs) {
-        if (seen.has(d)) continue;
-        seen.add(d);
-        installTo(resolveUserDir(d));
-      }
+function installTo(dest) {
+  if (!dest || typeof dest !== 'string') throw new UsageError('Destination directory is required');
+  const target = path.resolve(dest, SKILL_NAME);
+  assertSafeTarget(target);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(PKG_ROOT, target, COPY_SKIP);
+    if (!fs.existsSync(path.join(target, 'SKILL.md'))) {
+      throw new InstallError('Installed directory is missing SKILL.md');
     }
-    console.log('完成。');
-    return;
+  } catch (err) {
+    if (err instanceof UsageError || err instanceof InstallError) throw err;
+    throw new InstallError('Cannot install to ' + target + ': ' + err.message);
   }
+  console.log('installed -> ' + target);
+  return target;
+}
 
-  const PROJECT_DIRS = [
+function projectDirs() {
+  return [
     '.claude/skills',
     '.cursor/skills',
     '.codex/skills',
@@ -150,14 +179,67 @@ function main() {
     '.codebuddy/skills',
     '.kimi/skills',
     '.agents/skills',
-  ];
-  let installedAny = false;
-  for (const d of PROJECT_DIRS) {
-    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  ].filter((dir) => fs.existsSync(dir));
+}
+
+function run() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { usage(); return; }
+  if (opts.list) { printList(); return; }
+
+  if (opts.dir) { installTo(opts.dir); return; }
+
+  if (opts.agent) {
+    const info = AGENT_DIRS[opts.agent];
+    if (!info) {
+      throw new UsageError('Unknown agent: ' + opts.agent + '. Available: ' + Object.keys(AGENT_DIRS).join(', ') + '. Use --dir for a custom directory.');
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    return;
   }
-  if (!installedAny) {
-    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+
+  if (opts.global) {
+    const seen = new Set();
+    let count = 0;
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const dir of value.dirs) {
+        if (seen.has(dir)) continue;
+        seen.add(dir);
+        installTo(resolveUserDir(dir));
+        count++;
+      }
+    }
+    console.log('Installed to ' + count + ' directories.');
+    return;
+  }
+
+  const dirs = projectDirs();
+  if (!dirs.length) {
+    throw new TargetError('No project-level agent directory detected. Use --agent <name> or --dir <path>.');
+  }
+  for (const dir of dirs) installTo(dir);
+}
+
+function main() {
+  try {
+    run();
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error('Usage error: ' + err.message);
+      usage();
+      process.exitCode = 2;
+    } else if (err instanceof TargetError) {
+      console.error('Target error: ' + err.message);
+      process.exitCode = 4;
+    } else if (err instanceof InstallError) {
+      console.error('Install failed: ' + err.message);
+      console.error('Fix: check directory permissions and free space, then retry. Use --dir to choose another directory.');
+      process.exitCode = 1;
+    } else {
+      console.error('Unexpected error: ' + (err && err.message ? err.message : String(err)));
+      process.exitCode = 1;
+    }
   }
 }
 
-main();
+main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yottameta/yotta-workflow",
-  "version": "0.2.6",
-  "description": "Cross-session / cross-project workflow standard for all AI agents: read the state on start, store state nearby in a unified .workflow directory, persist logs/tasks/decisions while working, and leave a self-contained handoff anchor on finish. Triggers when starting/handing over/resuming/shutting down a project or doing multi-step development. Works for all AI agents.",
+  "version": "0.4.0",
+  "description": "Cross-session / cross-project workflow standard for all AI agents: read the state on start, keep .workflow at the project root, persist logs/tasks/decisions while working, and leave a self-contained handoff anchor on finish. The project root is the state anchor; source directories may be nested and .git alone does not define the project root.",
   "license": "MIT",
   "keywords": [
     "agent-skills",
@@ -31,5 +31,8 @@
   },
   "bin": {
     "yotta-workflow": "bin/install.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
   }
 }

package/references/exception-playbook.md

@@ -0,0 +1,37 @@
+# 元序异常恢复手册
+
+## 1. 状态文件缺失
+
+- 信号：项目存在但状态目录不存在。
+- 动作：按项目根目录初始化标准结构，不覆盖既有机制。
+- 恢复：读取项目文档与用户补充信息，重建最小状态。
+
+## 2. 并发写入冲突
+
+- 信号：两个会话同时更新同一状态文件。
+- 动作：停止整文件重写，改为读取后合并。
+- 恢复：保留双方有效信息，冲突处标注来源并请用户确认。
+
+## 3. 状态文件过大
+
+- 信号：单文件明显超过常规阅读量。
+- 动作：拆分历史内容，保留当前快照。
+- 恢复：STATE 只留当前进度，历史写入日志或专项文档。
+
+## 4. 既有机制冲突
+
+- 信号：项目已有自己的交接文件。
+- 动作：沿用原机制，只补足开工读取与收工锚点。
+- 恢复：把本协议必要字段映射到原机制，不重复建一套状态。
+
+## 5. 会话中断
+
+- 信号：用户直接开新会话，未走收工流程。
+- 动作：先读状态，再请用户补充缺失点。
+- 恢复：确认后从下一步继续，不假装记得对话内容。
+
+## 6. 误把源码目录当项目根目录
+
+- 信号：某个子目录有 `.git`，AI 在它下面新建了 `.workflow`，但上层其实已有项目根目录或状态。
+- 动作：立即停止新增写入；先检查上层已有 `.workflow` 和用户指定的项目根目录；不要自动移动或合并文件。
+- 恢复：确认项目根目录后，由用户确认如何处理误建的 `.workflow`；后续状态只写入正确项目根目录，已有正确 `.workflow` 保持原位。

package/references/faq.md

@@ -0,0 +1,62 @@
+# 元序常见问题
+
+## 速查索引
+
+- **适用**：什么任务用 · 一次性问答要不要用
+- **状态**：目录在哪 · 项目根目录与源码目录的区别 · 多智能体如何共享 · 文件太大怎么办
+- **协作**：并发写入 · 既有机制兼容 · 轻量会话简化
+- **收尾**：锚点格式 · 中断恢复
+
+---
+
+## 1. 什么任务应该使用元序？
+
+项目型、跨会话、多步骤、需要落盘状态的任务。一次性问答或纯查资料不需要初始化状态目录。
+
+## 2. 状态目录在哪里？
+
+状态目录固定为 `<项目根目录>\.workflow\`。项目根目录只认两种证据：用户明确指定，或从 cwd 向上找到已有 `.workflow`。两种都没有时先问，不用 `.git`、`package.json`、`src`、`README`、cwd 或目录结构自行猜。已有 `.workflow` 永不自动迁移。
+
+`.git` 只是版本控制标记，不能单独决定项目根目录。源码目录可以是项目根目录的子目录，也可以有独立 `.git`。
+
+## 2.1 项目根目录、源码目录、工作区根有什么区别？
+
+| 名称 | 含义 | `.workflow` |
+| --- | --- | --- |
+| 项目根目录 | 拥有整个项目状态的目录 | 放这里 |
+| 源码目录 | 代码 / 资源 / 某个仓库所在位置 | 不放，除非用户明确说明它同时就是项目根目录 |
+| 工作区根目录 | 并列多个项目根目录的父目录 | 不放；先选具体项目根目录 |
+
+标准形态：项目根目录下直接放 `.workflow`，源码目录属于项目根目录内部。实际项目中源码目录怎么命名、怎么分层，由用户按项目情况调整。
+
+## 3. 多个智能体能共享状态吗？
+
+可以。同一项目内的智能体读写同一份状态文件，形成单一事实源。若出现不同步，先确认它们的项目根目录是否一致。
+
+## 4. 状态文件太大怎么办？
+
+日志按天拆分；STATE 只保留当前进度，历史快照放 ROADMAP / DECISIONS。超过约 500 行时应拆分或归档，避免每次开工读入过多内容。
+
+## 5. 多个智能体同时写入怎么办？
+
+尽量由一个会话负责写入。若必须并发，先读取再小步追加，不要整文件重写；冲突时以文件内容为准，合并后写入。
+
+## 6. 项目已有交接机制怎么办？
+
+沿用原机制，但必须满足两点：开工先读状态，收工更新状态并留锚点。
+
+## 7. 轻量会话可以简化吗？
+
+可以。只做两件事：开工读状态，收工写一条简短锚点。不要为了小任务生成完整状态结构。
+
+## 8. 收工锚点必须固定格式吗？
+
+必须。固定结构保证下个会话能自动解析：项目、路径、上次结束时间、当前进度、已完成、下一步、关键决定、遗留问题、开工读取路径。
+
+## 9. 会话中断后怎么恢复？
+
+先读状态文件，再对照用户补充信息确认恢复点；没有状态时明说缺失，请用户给恢复点。
+
+## 10. 状态与对话记忆冲突怎么办？
+
+以状态文件为准，并在回复中说明冲突来源。

package/references/path-model.md

@@ -0,0 +1,52 @@
+# 元序路径模型
+
+本文档只规定元序的标准形态和状态位置，不规定具体项目必须怎样组织源码目录。
+
+## 1. 标准形态
+
+```text
+<项目根目录>\
+├── .workflow\         # 工作流
+└── <源码目录>\        # 源码目录
+```
+
+它表达三件事：
+
+- **项目根目录**：整个项目的状态锚点。
+- **`.workflow\`**：直接放在项目根目录下，是唯一的工作流状态目录。
+- **源码目录**：位于项目根目录内部；实际叫什么、放在哪一层、是否嵌套多个仓库，由用户按项目情况自行调整。
+
+标准不要求项目根目录有 Git，也不要求源码目录一定叫 `src`。这些都属于具体项目的结构，不属于元序的控制范围。
+
+## 2. 状态位置
+
+状态目录固定为：
+
+```text
+<项目根目录>\.workflow\
+├── STATE.md
+├── TASKS.md
+├── DECISIONS.md
+├── ROADMAP.md
+└── logs\
+    └── YYYY-MM-DD.md
+```
+
+同一项目的所有智能体会话都读写这一份状态，不另建副本。
+
+## 3. 定位项目根目录
+
+只认两种证据，按顺序执行：
+
+1. **用户明确指定项目根目录**：直接使用用户指定或交接锚点“路径”指向的目录。
+2. **已有状态**：从 cwd 向上查找最近的 `.workflow\STATE.md`；其父目录就是项目根目录，原地沿用。
+3. **两者都没有**：停止初始化，先问：`这个任务的项目根目录是哪一个？`
+
+`.git`、`package.json`、`src`、`app`、`README`、cwd 或目录结构都不能单独判定项目根目录。
+
+## 4. 技能边界
+
+- 元序只规定 `.workflow` 必须位于项目根目录下。
+- 元序不替用户设计或改造源码目录结构。
+- 具体项目如何使用标准形态，由用户根据实际情况调整。
+- 已有 `.workflow` 永不自动迁移、复制或重建。

package/references/walkthroughs.md

@@ -0,0 +1,34 @@
+# 元序复杂场景走查
+
+## 走查 1：项目开工
+
+1. 先看用户是否明确指定项目根目录；再看 cwd 向上是否有已有 `.workflow\STATE.md`。
+2. 两者都没有时停止初始化，先问“项目根目录是哪一个？”；不得用 `.git`、`package.json`、`src`、`README` 或 cwd 猜。
+3. 读取项目根目录下 `.workflow\` 的 STATE / TASKS / ROADMAP / DECISIONS。
+4. 汇总当前进度与下一步。
+5. 执行前先确认本次会话目标与验收。
+
+## 走查 2：任务中主动落盘
+
+背景：一个功能已改完一半，后续还有测试和文档。
+
+1. 立刻更新 STATE 当前进度。
+2. 在 TASKS 勾选已完成项。
+3. 如有新决策，写入 DECISIONS。
+4. 当天日志追加一条简短记录。
+5. 继续执行剩余步骤。
+
+## 走查 3：收工锚点
+
+1. 更新 STATE / TASKS / ROADMAP。
+2. 追加当天日志。
+3. 输出固定格式锚点，包含项目、项目根目录绝对路径、时间、进度、已完成、下一步、关键决定、遗留问题、开工读取路径。
+4. 确认锚点与状态文件一致。
+
+## 走查 4：源码目录里有 `.git`，项目状态该放哪？
+
+背景：当前 cwd 位于项目根目录的源码子目录，源码目录有 `.git`；用户此前给的项目根目录是上层目录。
+
+1. 用户指定的项目根目录优先，不因 cwd 或 `.git` 改变。
+2. 检查项目根目录下的 `.workflow\`；存在则沿用，不存在则在项目根目录初始化。
+3. 源码目录只负责放代码，不在源码目录另建状态。