@yottameta/yotta-workflow 0.2.5 → 0.3.0

package/README.md

@@ -50,7 +50,7 @@ It depends on no specific agent or platform: the state is just Markdown files un
 | **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 |
 | **Gradual adoption** | projects with an existing state mechanism keep it, only satisfying the two mandatory points; low migration cost |
-| **Ecosystem distribution** | GitHub + npm dual-source sync release; npx / install.sh / manual copy — three install methods covering 17+ agent directories |
+| **Ecosystem distribution** | GitHub + npm dual-source sync release; four install methods (npx / git clone / Download ZIP / install.sh) covering 17+ agent directories |
 
 ## Protocol details
 
@@ -134,56 +134,42 @@ It is not needed for one-off read-only questions (e.g. "what does this function
 
 ## Installation
 
-Pick any of the three methods; skill files are always fetched from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
+Pick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
 
-### Method 1: npm (recommended, one-liner)
-```bash
+### Method 1: npm one-liner (recommended)
+
+```text
 # Optional China mirror: npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-workflow -g
-npx -y @yottameta/yotta-workflow --dir <your skills dir>   # any agent: install to a custom directory
+npx -y @yottameta/yotta-workflow --agent <agent-name>      # install to the agent's default user-level skills dir
+npx -y @yottameta/yotta-workflow --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)
+```
+
+- `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
+- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
+- If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
+
+### Method 2: git clone (developers / git available)
+
+```text
+git clone https://github.com/YottaMeta/yotta-workflow.git <your-skills-dir>/yotta-workflow
 ```
-> Agent not in the preset list? Use `--dir` to point at its skills directory, or copy manually (Method 3). `--list` shows the default directory of each agent. To grab the files yourself, run `npm pack @yottameta/yotta-workflow` and unpack, then use Method 2 or 3.
-
-### Method 2: install.sh
-After obtaining the skill folder (`npm pack` unpack or `git clone`), enter the folder:
-```bash
-bash install.sh -g    # user-level; bash install.sh --list shows all directories
-bash install.sh --agent codex   # a specific agent (see --list)
-bash install.sh       # project-level: auto-detect existing skills directories
-bash install.sh --dir /path/to/skills
+
+### Method 3: GitHub Download ZIP (manual / no git)
+
+On the GitHub repository `YottaMeta/yotta-workflow`, click **Code → Download ZIP**, unzip it and put the `yotta-workflow` folder into the agent's skills directory.
+
+### Method 4: install.sh (multi-agent one-liner script)
+
+```text
+bash install.sh --agent <name>   # install to the agent's default user-level directory
+bash install.sh --dir <path>     # install to the given directory
+bash install.sh --list           # list agents -> default directories
 ```
-> Covers 17 agent families, including Trae / Qwen / Comate / CodeBuddy / Kimi.
-
-### Method 3: manual copy
-Copy the whole `yotta-workflow` folder into the target agent's skills directory. Common user-level locations (`%USERPROFILE%` on Windows, `~` on Linux/macOS):
-
-| Agent | User-level directory | Project-level directory |
-|---|---|---|
-| Codex | `%USERPROFILE%\.codex\skills\yotta-workflow\` | `.codex\skills\` |
-| Claude Code | `%USERPROFILE%\.claude\skills\yotta-workflow\` | `.claude\skills\` |
-| Cursor | `%USERPROFILE%\.cursor\skills\yotta-workflow\` | `.cursor\skills\` |
-| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-workflow\` | `.windsurf\skills\` |
-| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-workflow\` | `.opencode\skills\` |
-| Gemini | `%USERPROFILE%\.gemini\skills\yotta-workflow\` | `.gemini\skills\` |
-| Goose | `%USERPROFILE%\.config\goose\skills\yotta-workflow\` | `.goose\skills\` |
-| Amp | `%USERPROFILE%\.config\agents\skills\yotta-workflow\` | `.agents\skills\` |
-| Kiro | `%USERPROFILE%\.kiro\skills\yotta-workflow\` | `.kiro\skills\` |
-| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-workflow\` | `.workbuddy\skills\` |
-| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-workflow\` | `.traecli\skills\` |
-| Trae IDE (CN) | `%USERPROFILE%\.trae-cn\skills\yotta-workflow\` | `.trae\skills\` |
-| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-workflow\` | `.qwen\skills\` |
-| Comate | `%USERPROFILE%\.comate\skills\yotta-workflow\` | `.comate\skills\` |
-| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-workflow\` | `.codebuddy\skills\` |
-| Kimi | `%USERPROFILE%\.kimi\skills\yotta-workflow\` | `.kimi\skills\` |
-| Generic AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-workflow\` | `.agents\skills\` |
-
-> If Codex's `CODEX_HOME` is set, it overrides the default; the same applies to opencode's `XDG_CONFIG_HOME`. `.agents\skills` is not a universal directory — only OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot etc. read it; **Claude Code and Codex do not read it by default**. When unsure, use `--dir` or let the agent install it.
-
-> Project-level: run `npx -y @yottameta/yotta-workflow` or `bash install.sh` inside the project to install into the detected project-level directory.
 
+> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
 ## Upgrade / uninstall
 
-- **Upgrade**: reinstall the latest version to overwrite — `npx -y @yottameta/yotta-workflow -g` or rerun `bash install.sh -g`. Old files inside the skill directory are overwritten; the project state files (`.workflow\`) are unaffected.
+- **Upgrade**: reinstall the latest version to overwrite — rerun the install command you used (e.g. `npx -y @yottameta/yotta-workflow --agent <name>` or `bash install.sh --agent <name>`). Old files in the skill directory are replaced; the project state files (`.workflow\`) are unaffected.
 - **Uninstall**: delete the `yotta-workflow` folder under the target agent's skills directory (see the table above). Uninstalling does not affect state files already written into a project.
 
 ## FAQ
@@ -196,6 +182,12 @@ Copy the whole `yotta-workflow` folder into the target agent's skills directory.
 
 Run inside this project: `python tools/validate-skill.py yotta-workflow`.
 
+## References
+
+- references/faq.md
+- references/walkthroughs.md
+- references/exception-playbook.md
+
 ## License
 
 MIT © YottaMeta

package/README.zh-CN.md

@@ -50,7 +50,7 @@ yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协
 | **自包含交接锚点** | 固定模板 + 强制校验（内容必须与状态文件一致），下个会话无痛接续 |
 | **轻量零依赖** | 纯 Markdown 文件，无 daemon / 无数据库 / 无注入；任何平台可读可写 |
 | **渐进采用** | 已有状态机制的项目可沿用原机制，只需满足两个强制点，迁移成本低 |
-| **生态分发** | GitHub + npm 双源同步发布；npx / install.sh / 手动复制三种安装方式，覆盖 17+ 类智能体目录 |
+| **生态分发** | GitHub + npm 双源同步发布；npx / git clone / Download ZIP / install.sh 四种安装方式，覆盖 17+ 类智能体目录 |
 
 ## 协议详解
 
@@ -134,54 +134,42 @@ yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协
 
 ## 安装
 
-三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
 
-### 方式一：npm（推荐，一行安装）
-```bash
-# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
-npx -y @yottameta/yotta-workflow -g
-npx -y @yottameta/yotta-workflow --dir <你的技能目录>   # 任意智能体：指定目录安装
+### 方式一：npm 一行装（推荐）
+
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-workflow --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-workflow --dir <智能体的技能目录>  # 指到技能目录本身（如 ~/.codex/skills）
+```
+
+- `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
+- `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
+- npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
+
+### 方式二：git clone（开发者 / 有 git 环境）
+
+```text
+git clone https://github.com/YottaMeta/yotta-workflow.git <智能体的技能目录>/yotta-workflow
 ```
-> 智能体不在预置列表里？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。想手动拿文件也可 `npm pack @yottameta/yotta-workflow` 解包后按方式二/三安装。
-
-### 方式二：install.sh 一键安装
-获取技能文件夹后（`npm pack` 解包或 `git clone`），进入技能文件夹：
-```bash
-bash install.sh -g    # 用户级；bash install.sh --list 查看全部目录
-bash install.sh --agent codex   # 指定智能体（--list 可查看可用项）
-bash install.sh       # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
-bash install.sh --dir /path/to/skills
+
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
+
+在 GitHub 仓库 `YottaMeta/yotta-workflow` 点 **Code → Download ZIP**，解压后把 `yotta-workflow` 文件夹放进智能体技能目录。
+
+### 方式四：install.sh（多智能体一键脚本）
+
+```text
+bash install.sh --agent <name>   # 装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
 ```
-> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
-
-### 方式三：手动复制
-把整个 `yotta-workflow` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
-
-| 智能体 | 用户级目录 | 项目级目录 |
-|---|---|---|
-| Codex | `%USERPROFILE%\.codex\skills\yotta-workflow\` | `.codex\skills\` |
-| Claude Code | `%USERPROFILE%\.claude\skills\yotta-workflow\` | `.claude\skills\` |
-| Cursor | `%USERPROFILE%\.cursor\skills\yotta-workflow\` | `.cursor\skills\` |
-| Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-workflow\` | `.windsurf\skills\` |
-| opencode | `%USERPROFILE%\.config\opencode\skills\yotta-workflow\` | `.opencode\skills\` |
-| Gemini | `%USERPROFILE%\.gemini\skills\yotta-workflow\` | `.gemini\skills\` |
-| Goose | `%USERPROFILE%\.config\goose\skills\yotta-workflow\` | `.goose\skills\` |
-| Amp | `%USERPROFILE%\.config\agents\skills\yotta-workflow\` | `.agents\skills\` |
-| Kiro | `%USERPROFILE%\.kiro\skills\yotta-workflow\` | `.kiro\skills\` |
-| WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-workflow\` | `.workbuddy\skills\` |
-| Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-workflow\` | `.traecli\skills\` |
-| Trae IDE (CN) | `%USERPROFILE%\.trae-cn\skills\yotta-workflow\` | `.trae\skills\` |
-| Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-workflow\` | `.qwen\skills\` |
-| Comate | `%USERPROFILE%\.comate\skills\yotta-workflow\` | `.comate\skills\` |
-| CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-workflow\` | `.codebuddy\skills\` |
-| Kimi | `%USERPROFILE%\.kimi\skills\yotta-workflow\` | `.kimi\skills\` |
-| Generic AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-workflow\` | `.agents\skills\` |
-
-> 通用约定：`.agents/skills` 并非所有智能体都读取（Claude Code 与 Codex 默认不读），仅为 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI 等智能体识别。已修改默认目录的智能体，请用 `--dir` 指定实际路径。
 
+> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
 ## 升级 / 卸载
 
-- **升级**：重新安装最新版覆盖即可——`npx -y @yottameta/yotta-workflow -g` 或重跑 `bash install.sh -g`。技能目录内的旧文件会被覆盖；项目里的状态文件（`.workflow\`）不受影响。
+- **升级**：重新安装最新版覆盖即可——重跑你用的安装命令（如 `npx -y @yottameta/yotta-workflow --agent <name>` 或 `bash install.sh --agent <name>`）。技能目录内旧文件会被替换；项目里的状态文件（`.workflow\`）不受影响。
 - **卸载**：删除目标智能体 skills 目录下的 `yotta-workflow` 文件夹（各智能体目录见上表）。卸载不影响已写入项目的状态文件。
 
 ## 常见问题
@@ -194,6 +182,12 @@ bash install.sh --dir /path/to/skills
 
 本项目内运行：`python tools/validate-skill.py yotta-workflow`。
 
+## 参考文档
+
+- references/faq.md
+- references/walkthroughs.md
+- references/exception-playbook.md
+
 ## 许可证
 
 MIT © YottaMeta

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-workflow
-description: "跨会话/跨项目通用工作流标准：让任何 AI 智能体活过会话——开工必读状态、状态就近存 .workflow、进行中自动记流水/任务/决策、收工必留交接锚点。触发：开工/接手项目、续测、收工、跨会话恢复、要落盘、多步开发、项目状态变化、跨智能体协作。项目型会话自动初始化 .workflow 状态目录并按本协议全程执行；轻量一次性问答不强制初始化。所有 AI 智能体通用。"
-version: 0.2.5
+description: "跨会话/跨项目通用工作流标准：让任何 AI 智能体活过会话——开工必读状态、状态就近存 .workflow、进行中自动记流水/任务/决策、收工必留交接锚点。触发：开工/接手项目、续测、收工、跨会话恢复、要落盘、多步开发、项目状态变化、跨智能体协作。边界：只记录项目状态（进度/任务/决策/流水），不写 AI 人格、用户偏好、关系或跨项目通用知识；轻量一次性问答不强制初始化。所有 AI 智能体通用。"
+version: 0.3.0
 license: MIT
 agent_created: true
 metadata:
@@ -189,4 +189,10 @@ metadata:
 ## 七、与既有项目机制的协调
 
 - **项目已有自己的交接/状态机制**：沿用其机制，不必强制迁移到本标准结构，但必须满足两个强制点——开工先读状态再声称了解；收工更新状态并留锚点。
-- **新项目 / 无既有机制**：按「〇、判定规则」初始化状态目录，完整执行本协议。
+- **新项目 / 无既有机制**：按「〇、判定规则」初始化状态目录，完整执行本协议。
+
+## 八、参考文档
+
+- 常见问题：`references/faq.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.5",
-  "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.3.0",
+  "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. Boundaries: records project state only; no AI personality, user preferences, relationships, or cross-project general knowledge.",
   "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,31 @@
+# 元序异常恢复手册
+
+## 1. 状态文件缺失
+
+- 信号：项目存在但状态目录不存在。
+- 动作：按项目根初始化标准结构，不覆盖既有机制。
+- 恢复：读取项目文档与用户补充信息，重建最小状态。
+
+## 2. 并发写入冲突
+
+- 信号：两个会话同时更新同一状态文件。
+- 动作：停止整文件重写，改为读取后合并。
+- 恢复：保留双方有效信息，冲突处标注来源并请用户确认。
+
+## 3. 状态文件过大
+
+- 信号：单文件明显超过常规阅读量。
+- 动作：拆分历史内容，保留当前快照。
+- 恢复：STATE 只留当前进度，历史写入日志或专项文档。
+
+## 4. 既有机制冲突
+
+- 信号：项目已有自己的交接文件。
+- 动作：沿用原机制，只补足开工读取与收工锚点。
+- 恢复：把本协议必要字段映射到原机制，不重复建一套状态。
+
+## 5. 会话中断
+
+- 信号：用户直接开新会话，未走收工流程。
+- 动作：先读状态，再请用户补充缺失点。
+- 恢复：确认后从下一步继续，不假装记得对话内容。

package/references/faq.md

@@ -0,0 +1,50 @@
+# 元序常见问题
+
+## 速查索引
+
+- **适用**：什么任务用 · 一次性问答要不要用
+- **状态**：目录在哪 · 多智能体如何共享 · 文件太大怎么办
+- **协作**：并发写入 · 既有机制兼容 · 轻量会话简化
+- **收尾**：锚点格式 · 中断恢复
+
+---
+
+## 1. 什么任务应该使用元序？
+
+项目型、跨会话、多步骤、需要落盘状态的任务。一次性问答或纯查资料不需要初始化状态目录。
+
+## 2. 状态目录在哪里？
+
+按“当前目录 → 项目根 / 工作区根”判定。项目根下使用项目内状态目录；工作区根下按项目名分目录。不要写死绝对路径。
+
+## 3. 多个智能体能共享状态吗？
+
+可以。同一项目内的智能体读写同一份状态文件，形成单一事实源。若出现不同步，先确认它们的项目根是否一致。
+
+## 4. 状态文件太大怎么办？
+
+日志按天拆分；STATE 只保留当前进度，历史快照放 ROADMAP / DECISIONS。超过约 500 行时应拆分或归档，避免每次开工读入过多内容。
+
+## 5. 多个智能体同时写入怎么办？
+
+尽量由一个会话负责写入。若必须并发，先读取再小步追加，不要整文件重写；冲突时以文件内容为准，合并后写入。
+
+## 6. 项目已有交接机制怎么办？
+
+沿用原机制，但必须满足两点：开工先读状态，收工更新状态并留锚点。
+
+## 7. 轻量会话可以简化吗？
+
+可以。只做两件事：开工读状态，收工写一条简短锚点。不要为了小任务生成完整状态结构。
+
+## 8. 收工锚点必须固定格式吗？
+
+必须。固定结构保证下个会话能自动解析：项目、路径、上次结束时间、当前进度、已完成、下一步、关键决定、遗留问题、开工读取路径。
+
+## 9. 会话中断后怎么恢复？
+
+先读状态文件，再对照用户补充信息确认恢复点；没有状态时明说缺失，请用户给恢复点。
+
+## 10. 状态与对话记忆冲突怎么办？
+
+以状态文件为准，并在回复中说明冲突来源。

package/references/walkthroughs.md

@@ -0,0 +1,25 @@
+# 元序复杂场景走查
+
+## 走查 1：项目开工
+
+1. 读取当前目录，判定项目根。
+2. 读取 STATE / TASKS / ROADMAP / DECISIONS。
+3. 汇总当前进度与下一步。
+4. 执行前先确认本次会话目标与验收。
+
+## 走查 2：任务中主动落盘
+
+背景：一个功能已改完一半，后续还有测试和文档。
+
+1. 立刻更新 STATE 当前进度。
+2. 在 TASKS 勾选已完成项。
+3. 如有新决策，写入 DECISIONS。
+4. 当天日志追加一条简短记录。
+5. 继续执行剩余步骤。
+
+## 走查 3：收工锚点
+
+1. 更新 STATE / TASKS / ROADMAP。
+2. 追加当天日志。
+3. 输出固定格式锚点，包含项目、路径、时间、进度、已完成、下一步、关键决定、遗留问题、开工读取路径。
+4. 确认锚点与状态文件一致。