@yottameta/yotta-workflow 0.2.5 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +30 -44
  2. package/README.zh-CN.md +31 -43
  3. package/SKILL.md +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -50,7 +50,7 @@ It depends on no specific agent or platform: the state is just Markdown files un
50
50
  | **Self-contained handoff anchor** | fixed template + enforced validation (content must match state files); next session resumes painlessly |
51
51
  | **Lightweight zero-dependency** | plain Markdown files, no daemon / database / injection; readable and writable on any platform |
52
52
  | **Gradual adoption** | projects with an existing state mechanism keep it, only satisfying the two mandatory points; low migration cost |
53
- | **Ecosystem distribution** | GitHub + npm dual-source sync release; npx / install.sh / manual copy — three install methods covering 17+ agent directories |
53
+ | **Ecosystem distribution** | GitHub + npm dual-source sync release; four install methods (npx / git clone / Download ZIP / install.sh) covering 17+ agent directories |
54
54
 
55
55
  ## Protocol details
56
56
 
@@ -134,56 +134,42 @@ It is not needed for one-off read-only questions (e.g. "what does this function
134
134
 
135
135
  ## Installation
136
136
 
137
- Pick any of the three methods; skill files are always fetched from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
137
+ 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).
138
138
 
139
- ### Method 1: npm (recommended, one-liner)
140
- ```bash
139
+ ### Method 1: npm one-liner (recommended)
140
+
141
+ ```text
141
142
  # Optional China mirror: npm config set registry https://registry.npmmirror.com
142
- npx -y @yottameta/yotta-workflow -g
143
- npx -y @yottameta/yotta-workflow --dir <your skills dir> # any agent: install to a custom directory
143
+ npx -y @yottameta/yotta-workflow --agent <agent-name> # install to the agent's default user-level skills dir
144
+ npx -y @yottameta/yotta-workflow --dir <your-skills-dir> # point to the skills dir itself (e.g. ~/.codex/skills)
145
+ ```
146
+
147
+ - `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
148
+ - `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
149
+ - 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.
150
+
151
+ ### Method 2: git clone (developers / git available)
152
+
153
+ ```text
154
+ git clone https://github.com/YottaMeta/yotta-workflow.git <your-skills-dir>/yotta-workflow
144
155
  ```
145
- > 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.
146
-
147
- ### Method 2: install.sh
148
- After obtaining the skill folder (`npm pack` unpack or `git clone`), enter the folder:
149
- ```bash
150
- bash install.sh -g # user-level; bash install.sh --list shows all directories
151
- bash install.sh --agent codex # a specific agent (see --list)
152
- bash install.sh # project-level: auto-detect existing skills directories
153
- bash install.sh --dir /path/to/skills
156
+
157
+ ### Method 3: GitHub Download ZIP (manual / no git)
158
+
159
+ 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.
160
+
161
+ ### Method 4: install.sh (multi-agent one-liner script)
162
+
163
+ ```text
164
+ bash install.sh --agent <name> # install to the agent's default user-level directory
165
+ bash install.sh --dir <path> # install to the given directory
166
+ bash install.sh --list # list agents -> default directories
154
167
  ```
155
- > Covers 17 agent families, including Trae / Qwen / Comate / CodeBuddy / Kimi.
156
-
157
- ### Method 3: manual copy
158
- Copy the whole `yotta-workflow` folder into the target agent's skills directory. Common user-level locations (`%USERPROFILE%` on Windows, `~` on Linux/macOS):
159
-
160
- | Agent | User-level directory | Project-level directory |
161
- |---|---|---|
162
- | Codex | `%USERPROFILE%\.codex\skills\yotta-workflow\` | `.codex\skills\` |
163
- | Claude Code | `%USERPROFILE%\.claude\skills\yotta-workflow\` | `.claude\skills\` |
164
- | Cursor | `%USERPROFILE%\.cursor\skills\yotta-workflow\` | `.cursor\skills\` |
165
- | Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-workflow\` | `.windsurf\skills\` |
166
- | opencode | `%USERPROFILE%\.config\opencode\skills\yotta-workflow\` | `.opencode\skills\` |
167
- | Gemini | `%USERPROFILE%\.gemini\skills\yotta-workflow\` | `.gemini\skills\` |
168
- | Goose | `%USERPROFILE%\.config\goose\skills\yotta-workflow\` | `.goose\skills\` |
169
- | Amp | `%USERPROFILE%\.config\agents\skills\yotta-workflow\` | `.agents\skills\` |
170
- | Kiro | `%USERPROFILE%\.kiro\skills\yotta-workflow\` | `.kiro\skills\` |
171
- | WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-workflow\` | `.workbuddy\skills\` |
172
- | Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-workflow\` | `.traecli\skills\` |
173
- | Trae IDE (CN) | `%USERPROFILE%\.trae-cn\skills\yotta-workflow\` | `.trae\skills\` |
174
- | Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-workflow\` | `.qwen\skills\` |
175
- | Comate | `%USERPROFILE%\.comate\skills\yotta-workflow\` | `.comate\skills\` |
176
- | CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-workflow\` | `.codebuddy\skills\` |
177
- | Kimi | `%USERPROFILE%\.kimi\skills\yotta-workflow\` | `.kimi\skills\` |
178
- | Generic AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-workflow\` | `.agents\skills\` |
179
-
180
- > 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.
181
-
182
- > Project-level: run `npx -y @yottameta/yotta-workflow` or `bash install.sh` inside the project to install into the detected project-level directory.
183
168
 
169
+ > 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.
184
170
  ## Upgrade / uninstall
185
171
 
186
- - **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.
172
+ - **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.
187
173
  - **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.
188
174
 
189
175
  ## FAQ
package/README.zh-CN.md CHANGED
@@ -50,7 +50,7 @@ yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协
50
50
  | **自包含交接锚点** | 固定模板 + 强制校验（内容必须与状态文件一致），下个会话无痛接续 |
51
51
  | **轻量零依赖** | 纯 Markdown 文件，无 daemon / 无数据库 / 无注入；任何平台可读可写 |
52
52
  | **渐进采用** | 已有状态机制的项目可沿用原机制，只需满足两个强制点，迁移成本低 |
53
- | **生态分发** | GitHub + npm 双源同步发布；npx / install.sh / 手动复制三种安装方式，覆盖 17+ 类智能体目录 |
53
+ | **生态分发** | GitHub + npm 双源同步发布；npx / git clone / Download ZIP / install.sh 四种安装方式，覆盖 17+ 类智能体目录 |
54
54
 
55
55
  ## 协议详解
56
56
 
@@ -134,54 +134,42 @@ yotta-workflow 把「跨会话协作」沉淀为一套与智能体无关的协
134
134
 
135
135
  ## 安装
136
136
 
137
- 三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
137
+ 以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
138
138
 
139
- ### 方式一：npm（推荐，一行安装）
140
- ```bash
141
- # 国内加速（可选）：npm config set registry https://registry.npmmirror.com
142
- npx -y @yottameta/yotta-workflow -g
143
- npx -y @yottameta/yotta-workflow --dir <你的技能目录> # 任意智能体：指定目录安装
139
+ ### 方式一：npm 一行装（推荐）
140
+
141
+ ```text
142
+ # 可选国内加速：npm config set registry https://registry.npmmirror.com
143
+ npx -y @yottameta/yotta-workflow --agent <智能体名称> # 装到指定智能体默认用户级技能目录
144
+ npx -y @yottameta/yotta-workflow --dir <智能体的技能目录> # 指到技能目录本身（如 ~/.codex/skills）
145
+ ```
146
+
147
+ - `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
148
+ - `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
149
+ - npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
150
+
151
+ ### 方式二：git clone（开发者 / 有 git 环境）
152
+
153
+ ```text
154
+ git clone https://github.com/YottaMeta/yotta-workflow.git <智能体的技能目录>/yotta-workflow
144
155
  ```
145
- > 智能体不在预置列表里？用 `--dir` 指定它的 skills 目录，或手动复制（方式三）。`--list` 可查看各智能体对应的默认目录。想手动拿文件也可 `npm pack @yottameta/yotta-workflow` 解包后按方式二/三安装。
146
-
147
- ### 方式二：install.sh 一键安装
148
- 获取技能文件夹后（`npm pack` 解包或 `git clone`），进入技能文件夹：
149
- ```bash
150
- bash install.sh -g # 用户级；bash install.sh --list 查看全部目录
151
- bash install.sh --agent codex # 指定智能体（--list 可查看可用项）
152
- bash install.sh # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
153
- bash install.sh --dir /path/to/skills
156
+
157
+ ### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
158
+
159
+ 在 GitHub 仓库 `YottaMeta/yotta-workflow` 点 **Code → Download ZIP**，解压后把 `yotta-workflow` 文件夹放进智能体技能目录。
160
+
161
+ ### 方式四：install.sh（多智能体一键脚本）
162
+
163
+ ```text
164
+ bash install.sh --agent <name> # 装到指定智能体默认用户级目录
165
+ bash install.sh --dir <path> # 装到指定目录
166
+ bash install.sh --list # 列出智能体 -> 默认目录
154
167
  ```
155
- > 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
156
-
157
- ### 方式三：手动复制
158
- 把整个 `yotta-workflow` 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 `%USERPROFILE%`，Linux/macOS 用 `~`）：
159
-
160
- | 智能体 | 用户级目录 | 项目级目录 |
161
- |---|---|---|
162
- | Codex | `%USERPROFILE%\.codex\skills\yotta-workflow\` | `.codex\skills\` |
163
- | Claude Code | `%USERPROFILE%\.claude\skills\yotta-workflow\` | `.claude\skills\` |
164
- | Cursor | `%USERPROFILE%\.cursor\skills\yotta-workflow\` | `.cursor\skills\` |
165
- | Windsurf | `%USERPROFILE%\.codeium\windsurf\skills\yotta-workflow\` | `.windsurf\skills\` |
166
- | opencode | `%USERPROFILE%\.config\opencode\skills\yotta-workflow\` | `.opencode\skills\` |
167
- | Gemini | `%USERPROFILE%\.gemini\skills\yotta-workflow\` | `.gemini\skills\` |
168
- | Goose | `%USERPROFILE%\.config\goose\skills\yotta-workflow\` | `.goose\skills\` |
169
- | Amp | `%USERPROFILE%\.config\agents\skills\yotta-workflow\` | `.agents\skills\` |
170
- | Kiro | `%USERPROFILE%\.kiro\skills\yotta-workflow\` | `.kiro\skills\` |
171
- | WorkBuddy | `%USERPROFILE%\.workbuddy\skills\yotta-workflow\` | `.workbuddy\skills\` |
172
- | Trae Code CLI | `%USERPROFILE%\.traecli\skills\yotta-workflow\` | `.traecli\skills\` |
173
- | Trae IDE (CN) | `%USERPROFILE%\.trae-cn\skills\yotta-workflow\` | `.trae\skills\` |
174
- | Qwen Code | `%USERPROFILE%\.qwen\skills\yotta-workflow\` | `.qwen\skills\` |
175
- | Comate | `%USERPROFILE%\.comate\skills\yotta-workflow\` | `.comate\skills\` |
176
- | CodeBuddy | `%USERPROFILE%\.codebuddy\skills\yotta-workflow\` | `.codebuddy\skills\` |
177
- | Kimi | `%USERPROFILE%\.kimi\skills\yotta-workflow\` | `.kimi\skills\` |
178
- | Generic AGENTS.md | `%USERPROFILE%\.agents\skills\yotta-workflow\` | `.agents\skills\` |
179
-
180
- > 通用约定：`.agents/skills` 并非所有智能体都读取（Claude Code 与 Codex 默认不读），仅为 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI 等智能体识别。已修改默认目录的智能体，请用 `--dir` 指定实际路径。
181
168
 
169
+ > 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
182
170
  ## 升级 / 卸载
183
171
 
184
- - **升级**：重新安装最新版覆盖即可——`npx -y @yottameta/yotta-workflow -g` 或重跑 `bash install.sh -g`。技能目录内的旧文件会被覆盖；项目里的状态文件（`.workflow\`）不受影响。
172
+ - **升级**：重新安装最新版覆盖即可——重跑你用的安装命令（如 `npx -y @yottameta/yotta-workflow --agent <name>` 或 `bash install.sh --agent <name>`）。技能目录内旧文件会被替换；项目里的状态文件（`.workflow\`）不受影响。
185
173
  - **卸载**：删除目标智能体 skills 目录下的 `yotta-workflow` 文件夹（各智能体目录见上表）。卸载不影响已写入项目的状态文件。
186
174
 
187
175
  ## 常见问题
package/SKILL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: yotta-workflow
3
3
  description: "跨会话/跨项目通用工作流标准：让任何 AI 智能体活过会话——开工必读状态、状态就近存 .workflow、进行中自动记流水/任务/决策、收工必留交接锚点。触发：开工/接手项目、续测、收工、跨会话恢复、要落盘、多步开发、项目状态变化、跨智能体协作。项目型会话自动初始化 .workflow 状态目录并按本协议全程执行；轻量一次性问答不强制初始化。所有 AI 智能体通用。"
4
- version: 0.2.5
4
+ version: 0.2.6
5
5
  license: MIT
6
6
  agent_created: true
7
7
  metadata:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yottameta/yotta-workflow",
3
- "version": "0.2.5",
3
+ "version": "0.2.6",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "keywords": [