cowork-flow 1.6.0 → 1.7.2

package/docs/architecture.md

@@ -0,0 +1,122 @@
+# 架构与扩展
+
+本文面向维护 cowork-flow 的开发者，说明项目文件如何分层、宿主差异放在哪里，以及新增能力时应遵守的边界。只想安装和使用时，看 [README](../README.md)；排查某个宿主时看 [宿主接入](hosts.md)。
+
+## 先记住三条边界
+
+1. `template/` 只放会写入用户项目的文件。
+2. `presets/` 只放由 `cwf host add` 安装到宿主配置目录的机器级载荷。
+3. 宿主差异由 `template/.cowork-flow/spec/runtime/host-assets.json` 声明，不写进通用运行时。
+
+## 仓库职责
+
+| 位置 | 职责 |
+|---|---|
+| `template/` | `project init` 和 `project sync` 的唯一分发源 |
+| `presets/` | 插件、预设和机器级 hook 的载荷源 |
+| `src/` | Node CLI：命令注册、安装器和文件同步计划 |
+| `scripts/` | 构建、测试、打包和发布脚本 |
+| `test/` | Node 测试及辅助模块 |
+| `tests/` | Python 仓库测试与 fixtures |
+| `docs/` | 用户、宿主、架构和维护文档 |
+| `.agents/`、`.claude/`、`.codex/`、`.cowork-flow/` | 当前源码仓库的运行副本，不作为分发源 |
+
+### 项目分发源
+
+`template/` 中与用户项目直接相关的内容包括：
+
+- `AGENTS.md`：项目协作入口。
+- `template/skills/`：项目技能的唯一源码，由 `init` / `sync` 按宿主分发。
+- `template/.cowork-flow/`：项目配置、Python 运行时、规范、计划和任务。
+- `template/.<host>/`：需要随项目落盘的宿主配置、hook 或 agents。
+
+`cwf project init` / `cwf project sync` 不应从源码仓库的运行副本读取内容。
+
+### 机器级载荷
+
+`presets/` 保存不属于单个项目的宿主组件：
+
+- Codex、Claude Code、OpenCode、ZCode、Qoder、Kimi Code 插件。
+- DeepSeek Harness 预设与 hook。
+- 插件品牌资产和引导技能。
+
+机器级安装器只能通过 `cwf host add` / `cwf host remove` 写入宿主配置目录，不应把用户主目录路径硬编码到 `template/`。
+
+## 运行时分层
+
+运行时代码位于 `template/.cowork-flow/scripts/`。仓库根的 `scripts/` 只负责构建和发布。
+
+| 层 | 位置 | 负责什么 |
+|---|---|---|
+| 命令适配 | `scripts/adapters/cli/` | 参数解析、命令输出和 CLI 返回码 |
+| 任务服务 | `scripts/services/` | 任务创建、生命周期、归档、上下文和任务树 |
+| 状态存储 | `scripts/infra/storage/` | UTF-8 读写、修订检查、操作日志和可恢复事务 |
+| 宿主适配 | `scripts/adapters/host/` | 宿主输入、策略差异和状态注入 |
+| Hook 共享核心 | `scripts/adapters/host/workflow_state_hook.py` | 各宿主共用的工作流状态解析 |
+| 宿主声明 | `spec/runtime/host-assets.json` | 平台、资产、同步策略、技能根和迁移清单 |
+
+流程内核保持窄职责：kernel 只解析状态事实和 action，Skill 所有权由 manifest loader 注入，硬门禁由 runtime gate 执行。仓库不再维护第二套流程中枢或独立的 Skill 注册控制面。
+
+单个 Skill 需要的脚本放在 `template/skills/<skill-id>/scripts/`，不进入运行时内核。
+
+## init 与 sync
+
+安装器和同步器不直接边读边写，而是按以下顺序执行：
+
+1. 读取 Host Asset Manifest 和同步策略。
+2. 构建不可变 Asset Plan。
+3. 在同一文件系统 staging，并校验文件 hash 与权限。
+4. 按备份清单提交；失败时逆序回滚。
+5. 最后更新 `.cowork-flow/.version`。
+
+`config.yaml`、`.developer`、规范、任务和计划按同步策略保护。`--force` 会扩大覆盖范围，因此已有项目应先用 `--dry-run` 查看变更。
+
+## 规范挂命令
+
+项目可以在 `.cowork-flow/spec/` 下的规范文件中声明检查命令。执行器只读取声明，不解析规范正文。
+
+```markdown
+---
+checks:
+  - cmd: npm run lint --silent
+    files: "src/"
+    timeout: 60
+    when: both
+---
+```
+
+可用字段：
+
+| 字段 | 含义 |
+|---|---|
+| `cmd` | 要执行的命令 |
+| `files` | 目录前缀或扩展名，如 `src/`、`*.ts`；多个值用逗号分隔 |
+| `timeout` | 秒数，默认 30，最长 120 |
+| `when` | `edit`、`lifecycle` 或 `both`，默认 `both` |
+
+唯一执行入口是 `./.cowork-flow/run spec-check`：
+
+| 结果 | 含义 | 是否阻断完成 |
+|---|---|---|
+| `pass` | 命令执行成功 | 否 |
+| `violation` | 命令执行失败且有违规 | 是 |
+| `unchecked` | 命令缺失、解释器缺失或超时 | 是，需显式放行 |
+
+`when: edit` 是编辑期提示，超时上限为 2.5 秒，不代替收口检查。收口阶段会执行全部声明，并把结果写入任务记录。
+
+模板不预置生效的项目检查命令，因为模板无法知道目标项目使用什么工具。需要检查时，在项目自己的 `spec/` 文件中声明。完整契约见 `.cowork-flow/spec/contracts/spec-checks.md`。
+
+## 扩展规则
+
+- 宿主特化只能放在 `spec/runtime/host-assets.json`、`scripts/adapters/`、`template/.<host>/` 或明确的宿主命令模块中。
+- `scripts/services|runtime|infra` 和 `src/lib/` 的通用计划、拷贝模块不能出现宿主分支。
+- 新宿主先更新 Host Asset Manifest 与 schema，再补安装器、doctor 和测试；不要在多个文件各写一份宿主清单。
+- 项目差异写入 `AGENTS.md`、`config.yaml`、`spec/` 或项目自有 Skill，不恢复第二套流程文档。
+- 修改 Skill 分发路径时，同时更新 `skillReadRoot`、`skillDiscovery` 和对应宿主证据。
+- 修改命令名时，一次更新命令注册表、README、doctor 提示、Skill 和相关测试。
+
+## 测试与字节码
+
+Node 测试位于 `test/`，Python 仓库测试位于 `tests/`。`node --test` 会加载 `test/` 下全部 `.js`，辅助模块也必须无副作用；Python 侧按 pytest 或 unittest 的默认发现规则收集。
+
+测试与技能脚本不得在 `template/`、`presets/` 下留下 `__pycache__` 或 `*.pyc`。Node 测试通过 `test/helpers/bytecode-isolation.js` 重定向缓存；技能脚本通过 `runtime_pythonpath_env(cache_bytecode=False)` 关闭字节码写入。`tests/test_no_legacy_template_paths.py` 负责守住这一边界。

package/docs/hosts.md

@@ -0,0 +1,290 @@
+# 宿主接入
+
+本文说明如何把 cowork-flow 接到 AI 编码宿主，以及安装后如何检查、升级和卸载。只想完成首次安装时，先看 [README](../README.md) 的“完成宿主设置”。
+
+## 先分清两类文件
+
+| 类型 | 写入位置 | 安装方式 |
+|---|---|---|
+| 项目级文件 | 当前项目的 `AGENTS.md`、`.cowork-flow/` 和宿主目录 | `cwf project init` / `cwf project sync` |
+| 机器级组件 | 宿主的用户配置目录，如插件、预设或 hook | `cwf host add` / `cwf host remove` |
+
+每个项目至少需要执行一次 `cwf project init`。是否需要 `cwf host add`，取决于宿主：
+
+| 宿主 | 初始化后是否需要机器级组件 | 建议命令 |
+|---|---|---|
+| Codex | 当前项目可运行；全局引导入口可选 | `cwf host add codex` |
+| Claude Code | 当前项目可运行；全局引导入口可选 | `cwf host add claude-code` |
+| OpenCode | 当前项目可运行；全局引导入口可选 | `cwf host add opencode` |
+| ZCode | 需要 | `cwf host add zcode` |
+| Qoder | 需要 | `cwf host add qoder` |
+| DeepSeek Harness | 需要 | `cwf host add dsh` |
+| Kimi Code | 工作流注入需要 hook；全局插件可选 | `cwf host add kimi-code --component hook` |
+
+## 通用命令
+
+先预览，再安装：
+
+```bash
+cwf host add <host> --dry-run
+cwf host add <host>
+```
+
+检查项目和 CLI 认识的宿主：
+
+```bash
+cwf host list .
+cwf host list . --json
+```
+
+升级或重装：
+
+```bash
+cwf host add <host> --force
+```
+
+卸载机器级组件：
+
+```bash
+cwf host remove <host>
+```
+
+`--force` 只在确认需要覆盖已有安装时使用。安装器遇到不属于自己的文件时默认拒绝覆盖或删除；`--dry-run` 会执行同样的归属检查。
+
+机器级 hook 与项目运行时各自升级，而它会在任何工作区触发——包括运行时比它旧的项目。三个机器级注入 shim（Qoder、ZCode、Kimi Code）因此是 **fail-open** 的：项目运行时失败时只在宿主运行日志留原因并返回 0，不注入，也不把「hook 失败」变成「拒绝你的输入」；保留非零退出的只有项目级 Edit 期规范门禁（Claude Code / Codex），它与所调用的运行时同源。旧项目上注入会静默不生效，跑一次 `cwf project sync .` 即可恢复。
+
+## Codex
+
+```bash
+cwf host add codex --dry-run
+cwf host add codex
+cwf host remove codex
+```
+
+安装器会：
+
+- 在 `$CODEX_HOME/plugins/marketplaces/cowork-flow-local/` 准备稳定插件源；未设置 `CODEX_HOME` 时使用 `~/.codex`。
+- 调用 Codex 官方 CLI 注册 marketplace 和插件，不手写 `config.toml`。
+- 找不到 `codex` 命令时仍准备源目录，并打印手动命令。
+
+插件只携带 `cowork-flow-bootstrap` 引导技能；项目 hook 和三个 fixed subagent 仍由项目级文件提供。安装或升级后新开会话。
+
+升级到新版本时运行：
+
+```bash
+cwf host add codex --force
+```
+
+## Claude Code
+
+```bash
+cwf host add claude-code --dry-run
+cwf host add claude-code
+cwf host remove claude-code
+```
+
+插件写入 `$CLAUDE_CONFIG_DIR/skills/cowork-flow`，未设置时为 `~/.claude/skills/cowork-flow`。Claude Code 会把带 `.claude-plugin/plugin.json` 的技能目录识别为插件，不需要额外 marketplace 命令。
+
+插件只提供引导技能。项目 hook 和 agents 已在 `.claude/` 中，避免多源 hook 重复执行。安装后新开会话。
+
+`~/.claude/skills/` 由用户维护：目标目录不是 cowork-flow 插件时，安装和卸载都会拒绝；确认要接管该目录后才使用 `--force`。
+
+## OpenCode
+
+```bash
+cwf host add opencode --dry-run
+cwf host add opencode
+cwf host remove opencode
+```
+
+安装位置是 `$XDG_CONFIG_HOME/opencode/`，未设置时为 `~/.config/opencode`。安装器只写 `plugins/cowork-flow.js` 和 `cowork-flow/`，不修改用户的 `opencode.json`。
+
+插件在 `config` hook 中注册随载荷提供的 `cowork-flow-bootstrap` 技能目录，因此没有初始化 cowork-flow 的仓库也能看到启动入口。安装后新开会话。
+
+OpenCode 可能在插件目录中生成 `package.json`、`bun.lock` 和 `node_modules/`。这些是宿主文件，安装器不会修改或清理。多插件加载顺序以及全局与项目同名技能的优先级尚未实测。
+
+## ZCode
+
+```bash
+cwf host add zcode --dry-run
+cwf host add zcode
+cwf host add zcode --force --prune-old
+cwf host remove zcode
+```
+
+安装器会维护稳定 marketplace 源和当前活动副本，插件缓存位于 `~/.zcode/cli/plugins/cache/`。插件提供 hook、三个 fixed subagent 和引导技能；项目技能仍由 `.agents/skills/` 提供。
+
+默认保留旧版本缓存，避免正在运行的会话突然失去插件。需要清理旧版本时使用 `--prune-old`。升级后重启 ZCode 或新开会话。
+
+## Qoder
+
+```bash
+cwf host add qoder --dry-run
+cwf host add qoder
+cwf host add qoder --force
+cwf host remove qoder
+```
+
+安装位置由 `QODER_CONFIG_DIR` 决定，未设置时为 `~/.qoder`。插件提供 hook、三个 fixed subagent 和引导技能；项目级 `init` / `sync` 只写适配声明和共享技能。
+
+## DeepSeek Harness
+
+默认安装 Cowork Flow 预设：
+
+```bash
+cwf host add dsh --component preset --dry-run
+cwf host add dsh
+cwf host remove dsh --component preset
+```
+
+预设同时写两条交付线，因为桌面版换了通道：
+
+| 位置 | 适用 | 启用方式 |
+| --- | --- | --- |
+| `~/.dsh/.agent-presets/cowork-flow/`（或 `$DSH_HOME` 对应目录） | DSH 0.1.x / CLI 线 | 直接出现在会话的预设列表里，重启后选择 **Cowork Flow** |
+| `~/.dsh/bundles/cowork-flow/` | DSH 0.2.0+（桌面版） | 在桌面版侧边栏的 Plugins 页里填入该目录的绝对路径安装（`plugin_manager` 工具行在桌面宿主组合里被禁用，会话中不可用），然后开新会话 |
+
+0.2.0 起宿主不再读取 `.agent-presets/` 目录（其自带技能原文："Nothing reads that directory any more"），预设改为 bundle patch 里 `@deepseek-ai/dsh-agent-preset` 的一条声明行。bundle 的安装动作由宿主完成——它会跑包安装并写 profile 清单——所以 `cwf` 只产出 bundle 与安装指令，不改写 `~/.dsh/profiles/**`。两条线的内容只差宿主 API 不同的两处：工作流行（0.1.x `dsh-workflow-worker-thread` / 0.2.0 `dsh-workflow-ptc`）与 persona 行的配置键（0.1.x `text` / 0.2.0 `prefix`），bundle 生成时替换；两处都必须与目标线一致，包解析不到或配置键不被接受会让宿主把**整个**预设判为不可用。不带 `--force` 的安装只补缺失的那条线，不会覆盖已存在的目录。
+
+预设已经包含 workflow-state hook，不需要再安装 hook 组件。只有调试组合层配置时才使用：
+
+```bash
+cwf host add dsh --component hook
+cwf host remove dsh --component hook
+```
+
+hook 行是否进入 agent 提示按版本分线：实测 DSH 0.1.1-rc.1 不收集 host 层 section，实时注入只能靠预设；0.2.0-rc.1（桌面版）的组装会把全局层 section 合并进每次 agent 提示（`dsh-scope` 的 `layers.merge()` 先取全局层、再由作用域链覆盖），因此该版本上 hook 组件本身即可提供注入。以上为代码与文档级取证，真实会话验证仍需在对应版本上跑一次。
+
+## Kimi Code
+
+工作流状态注入使用 hook 组件：
+
+```bash
+cwf host add kimi-code --component hook
+cwf host remove kimi-code --component hook
+```
+
+安装或更新后重载配置或新开会话。该组件总是重写自己的 hook 区块，不接受 `--force`。
+
+如果还需要在未初始化项目中提供全局引导技能，可以另外安装插件：
+
+```bash
+cwf host add kimi-code
+```
+
+Kimi Code 目前只能通过 TUI 安装插件。命令会把载荷放到稳定源目录 `$KIMI_CODE_HOME/plugins/sources/cowork-flow/`，然后打印需要在 Kimi 中执行的 `/plugins install <绝对路径>` 和 `/reload`。
+
+`cwf host remove kimi-code` 会删除源目录并提示宿主侧残留；托管副本和注册表记录需要在 Kimi 中执行 `/plugins remove cowork-flow`。
+
+## MCP 客户端接入
+
+需要让 MCP 客户端读取任务事实时，推荐全局注册一次：
+
+```bash
+cwf mcp serve
+```
+
+客户端从当前工作目录向上查找 `.cowork-flow/`，因此同一注册可服务多个项目。常用配置示例：
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.cowork-flow]
+command = "cwf"
+args = ["mcp", "serve"]
+```
+
+```json
+// OpenCode: ~/.config/opencode/opencode.json
+{
+  "mcp": {
+    "cowork-flow": {
+      "type": "local",
+      "command": ["cwf", "mcp", "serve"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Claude Code 可运行：
+
+```bash
+claude mcp add -s user cowork-flow -- cwf mcp serve
+```
+
+不全局安装 CLI 时，也可以直接配置项目内入口：
+
+```bash
+<project>/.cowork-flow/run mcp-state
+```
+
+## 技能发现
+
+项目技能的唯一源码是 `template/skills/`，`init` / `sync` 按下表分发。宿主插件不再携带项目技能的副本。
+
+| 宿主 | 项目技能读取根 | 宿主发现方式 |
+|---|---|---|
+| Codex | `.agents/skills/` | 原生扫描 `.agents/skills/` |
+| Claude Code | `.claude/skills/` | 原生扫描项目 `.claude/skills/` |
+| OpenCode | `.agents/skills/` | 扫描 `.agents/skills/` 和 `.opencode/skills/`；cowork-flow 只交付前者 |
+| ZCode | `.agents/skills/` | 扫描项目 `.zcode/skills/` 与 `.agents/skills/`；同名时前者优先 |
+| Qoder | `.agents/skills/` | `loadFromAgentsDirectory` 默认开启 |
+| Kimi Code | `.agents/skills/` | `PROJECT_GENERIC_DIRS` 包含 `.agents/skills` |
+| DeepSeek Harness | `.agents/skills/` | `skill-filesystem` 将其作为项目技能根 |
+
+这些通道在 Host Asset Manifest 中以 `verified:` 记录。宿主升级后，如果发现行为变化，应更新证据和测试，不要只改文档。
+
+## 诊断
+
+先运行：
+
+```bash
+./.cowork-flow/run doctor --all
+./.cowork-flow/run doctor --all --json
+```
+
+<details>
+<summary>常见诊断码</summary>
+
+| 范围 | 诊断码 | 含义 |
+|---|---|---|
+| 通用技能 | `SKILL-READROOT-MISSING` | 项目缺少声明的技能读取根 |
+| 通用技能 | `PLUGIN-SKILLS-LEGACY` | 旧插件仍携带项目技能副本，需要重装插件 |
+| 通用技能 | `SKILL-DISCOVERY-GATED` | 宿主需要信任目录或重启后才加载技能 |
+| Codex | `PLUGIN-NOT-INSTALLED` / `PLUGIN-PAYLOAD-MISSING` / `PLUGIN-DISABLED` | 插件未注册、载荷缺失或未启用 |
+| Claude Code / OpenCode | `PLUGIN-NOT-INSTALLED` / `PLUGIN-PAYLOAD-INCOMPLETE` / `PLUGIN-STALE` | 插件未安装、载荷不完整或版本落后 |
+| Qoder | `PLUGIN-NOT-INSTALLED` / `PLUGIN-PAYLOAD-MISSING` / `PLUGIN-PAYLOAD-INCOMPLETE` / `PLUGIN-DISABLED` / `PLUGIN-STALE` | 插件安装、启用、载荷或版本异常 |
+| DSH 预设 | `PRESET-UNKNOWN-VERSION` / `PRESET-STALE` | 预设缺少版本标记或版本落后 |
+| DSH / Kimi hook | `HOOK-NOT-INSTALLED` / `HOOK-SHIM-MISSING` / `HOOK-UNKNOWN-VERSION` / `HOOK-STALE` | hook 区块、脚本、版本标记或版本不匹配 |
+| Kimi 插件 | `PLUGIN-NOT-INSTALLED` / `PLUGIN-DISABLED` / `PLUGIN-PAYLOAD-INCOMPLETE` / `PLUGIN-STALE` / `PLUGIN-SOURCES-MISSING` | 尚未完成 TUI 安装、插件被禁用、载荷不完整、版本落后或源目录丢失 |
+
+Kimi Code 刚运行 `cwf host add kimi-code`、但还没在 TUI 执行 `/plugins install` 时，`PLUGIN-NOT-INSTALLED` 属于正常中间状态。
+
+</details>
+
+## 插件图标字段
+
+不同宿主支持的清单字段不同，不要给所有清单复制同一组字段。
+
+| 宿主 | 支持字段 | 要求 |
+|---|---|---|
+| Codex | `interface.logo`、`interface.brandColor` | logo 必须是载荷内相对路径 |
+| ZCode | marketplace 条目的 `icon` | 必须是 `https://` URL |
+| Claude Code、OpenCode、Qoder、DSH、Kimi Code | 无 | 不要写图标键 |
+
+`assets/icon.svg` 是品牌图标的唯一源，`presets/plugin-meta.json` 保存品牌色。发布时运行 `npm run icons:export` 重新导出栅格。
+
+## 环境变量
+
+| 变量 | 用途 |
+|---|---|
+| `COWORK_FLOW_HOOKS=0` / `COWORK_FLOW_DISABLE_HOOKS=1` | 关闭所有宿主的 hook 注入 |
+| `COWORK_FLOW_CONTEXT_ID` | 显式指定会话身份；宿主不提供会话变量时使用 |
+| `COWORK_FLOW_HOST` | 显式指定宿主 id |
+| `COWORK_FLOW_CODEX` | 指定 Codex CLI 可执行文件 |
+| `DSH_HOME` | 覆盖 DeepSeek Harness 配置根目录 |
+| `KIMI_CODE_HOME` | 覆盖 Kimi Code 配置根目录 |
+| `CODEX_HOME` | 覆盖 Codex 配置根目录 |
+| `QODER_CONFIG_DIR` | 覆盖 Qoder 配置根目录 |
+| `CLAUDE_CONFIG_DIR` | 覆盖 Claude Code 配置根目录 |
+| `COWORK_FLOW_BROWSER` | `icons:export` 使用的浏览器可执行文件 |

package/docs/index.md

@@ -0,0 +1,32 @@
+# cowork-flow 文档
+
+第一次安装和使用请先看 [README](../README.md)。需要了解宿主接入、工作原理或开发流程时，再从下面的入口选择文档。
+
+## 按问题查找
+
+| 你想做什么 | 看哪份文档 | 能找到什么 |
+|---|---|---|
+| 安装、初始化项目或开始一个任务 | [README](../README.md) | 最短使用路径、日常命令和常见问题 |
+| 把 cowork-flow 接到某个 AI 编码宿主 | [宿主接入](hosts.md) | 各宿主的安装组件、重启要求、升级、卸载和排障方式 |
+| 了解项目文件如何组织 | [工作原理与扩展点](architecture.md) | 运行时、`template/`、`presets/`、规范检查和扩展边界 |
+| 参与项目开发 | [贡献指南](../CONTRIBUTING.md) | 本地环境、代码约定、测试和 PR 检查 |
+| 了解测试与发布流程 | [开发与发布](release.md) | 测试分层、CI、版本发布和维护者命令 |
+| 查某个版本改了什么 | [更新日志](../CHANGELOG.md) | 按版本记录的功能变化、修复和迁移说明 |
+
+## 常见阅读路径
+
+- **第一次使用**：README → 宿主接入 → 开始一个任务。
+- **提交代码**：README → 贡献指南 → 工作原理与扩展点。
+- **排查安装或运行问题**：宿主接入 → README 的“遇到问题”。
+- **准备发布**：工作原理与扩展点 → 开发与发布 → 更新日志。
+
+## 文档与实际行为
+
+文档用于解释用法，具体命令和当前任务状态以运行结果为准：
+
+- 查看命令和参数：`cwf --help` 或 `cwf <group> <command> --help`
+- 查看任务下一步：`./.cowork-flow/run task next --json`
+- 查看宿主支持情况：`cwf host list`
+- 检查本机与项目状态：`./.cowork-flow/run doctor --all`
+
+如果命令输出与文档不一致，请以当前命令输出为准，并提交 [Issue](https://github.com/fishlikewater/cowork-flow/issues) 指出文档需要修正的位置。

package/docs/release.md

@@ -0,0 +1,104 @@
+# 发布与维护
+
+本文面向 cowork-flow 仓库维护者。普通用户只需要 [README](../README.md)；提交代码前先看 [贡献指南](../CONTRIBUTING.md)。
+
+## 发布前检查
+
+按改动范围选择测试，不必每次都从最重的命令开始。
+
+| 命令 | 什么时候运行 |
+|---|---|
+| `npm run test:fast` | 日常修改后的最低检查 |
+| `npm run test:smoke` | 验证 CLI 可加载，并从真实 npm tarball 安装后运行最小初始化 |
+| `npm run test:integration` | 改动 `project init` / `project sync` |
+| `npm run test:node:full` | 改动 Node CLI、安装器或共享模块 |
+| `npm run test:template` | 改动项目模板的核心路径 |
+| `npm run test:template:full` | 改动 Python 运行时、规范、hook 或宿主适配 |
+| `npm run test:windows:core` | 涉及 Windows、路径、换行或发布行为 |
+| `python -m pytest -q` | 改动 `template/.cowork-flow/`、`tests/` 或 Python 契约 |
+| `npm run test:all` | 准备发布时的完整 Node、模板和打包检查 |
+| `npm run release:check` | 发布信心门禁，当前等价于 `test:all` |
+
+平台前提不满足时，测试可能明确跳过。跳过项必须原样记录，不能当作通过。
+
+稳定性相关改动建议重复运行模板测试：
+
+```bash
+COWORK_TEMPLATE_TEST_REPEAT=3 \
+COWORK_TEMPLATE_TEST_SEED=<固定值> \
+npm run test:template:full
+```
+
+## 发布命令
+
+| 命令 | 行为 |
+|---|---|
+| `npm run release` | 发布 patch 版本 |
+| `npm run release -- minor` | 发布 minor 版本 |
+| `npm run release -- --version 0.1.0` | 使用指定版本号，跳过自动 bump |
+| `npm run release -- minor --no-publish` | 完成版本、提交和 tag，推送 commit 与 tag，但不执行 `npm publish`；由 CI 发布 |
+| `npm run release -- --dry-run` | 运行发布前检查，停在版本 bump 之前 |
+
+`--dry-run` 不是只读命令。它会先要求 Git 工作树和暂存区干净，再执行 `source:refresh` 和 `sync --force`，因此可能刷新仓库中被忽略的运行副本，并临时覆盖后恢复 `AGENTS.md`。它不会改版本文件、提交、打 tag 或发布；如果检查开始时已有本地修改，脚本会在任何刷新前停止。
+
+目标版本只有 bump 后才能确定，所以 `--dry-run` 不会运行 CHANGELOG 版本段落门禁。
+
+## 标准发布流程
+
+1. 确认工作树和更新日志符合预期。
+2. 运行 `npm run release:check` 和 `git diff --check`。
+3. 稳定性改动按上一节重复模板测试。
+4. 运行 `npm run release -- <release-type>`；CI 通道使用 `--no-publish`，它会把 tag 推给 CI。
+5. 脚本同步 `package.json`、lockfile、`template/.cowork-flow/.version` 和所有随包插件清单。
+6. 检查提交与 tag，再按下面的 CI 通道发布。
+
+`scripts/release.sh` 会在 bump 后检查 `CHANGELOG.md` 是否存在当前版本段落。这个检查发生在版本已经修改之后；如果失败，按脚本输出的撤销命令恢复 `package.json`、`package-lock.json`、`.version`，再运行 `npm run source:refresh`。
+
+## CI 发布通道
+
+推荐让 GitHub Actions 执行 `npm publish`：
+
+1. 在本地运行 `npm run release -- <release-type> --no-publish`。脚本完成检查、版本、提交和 tag，然后推送分支与 tag：
+
+   ```bash
+   git push
+   git push origin v<v>
+   ```
+
+2. 推送 tag 即触发 `.github/workflows/publish.yml`。工作流等待 Ubuntu 和 Windows 验证通过后，只从已存在的 `v<version>` tag 发布，并核对 tag、`package.json` 与 `template/.cowork-flow/.version` 的版本一致。
+
+3. 需要给这个 tag 写 Release 说明时，再手动创建（不是发布的必要步骤）：
+
+   ```bash
+   gh release create v<v>
+   ```
+
+不要在 tag 尚未存在于远端时运行 `gh release create`，否则 GitHub 可能从默认分支最新提交创建 tag，把发布指向错误提交。
+
+同一 tag 的重复触发会被 concurrency 锁串行化，不会并发抢发；如果该版本已经发到 npm，重复运行会在 `npm publish` 阶段被 npm 拒绝，这是预期行为。上一次 CI 失败需要重发时，用 `workflow_dispatch` 指定同一个 tag 重跑即可。
+
+PR 和发布使用同一套 core 门禁。
+
+发布凭据走 **Trusted Publishing**：publish job 声明 `id-token: write`，把 GitHub OIDC token 交给 npm 换取短期凭据，仓库里不保存长期 token。登记在 npm 包页面（Settings → Trusted Publishers），声明仓库 `fishlikewater/cowork-flow` 与 workflow 文件 `publish.yml`。
+
+该交换由 npm CLI 实现（11.5.1 起），而 Node 20 自带 npm 10，因此**只有 publish job 跑在 Node 24**；两个验证 job 仍用 Node 20，与 `package.json` 声明的 `engines` 保持一致。
+
+publish job 的 `setup-node` **保留 `registry-url`**，但不提供 `NODE_AUTH_TOKEN`。npm 需要在 `.npmrc` 里读到 registry 才会发起 OIDC 交换——去掉它，发布会在未接触令牌端点的情况下直接以 `ENEEDAUTH` 失败。`setup-node` 写入的 `${NODE_AUTH_TOKEN}` 占位符则**故意不解析**：npm 会带着这个空凭据先尝试交换，只有交换被拒时才回退到它。
+
+早期版本用 `NPM_TOKEN` secret。若账号开启双因素认证，classic token 无法完成交互式 OTP，CI 发布会以 `EOTP` 失败——这也是改用 Trusted Publishing 的原因。验证 job（Ubuntu / Windows）不接触任何发布凭据，只跑 `release:check`。
+
+## 维护者命令
+
+```bash
+npm run source:refresh:dry-run  # 预览源码仓库运行副本的刷新
+npm run source:refresh          # 刷新根 .cowork-flow、.agents/skills、.claude/skills
+npm run icons:export            # 从 assets/icon.svg 重新导出 PNG
+```
+
+`source:refresh` 以 `template/.cowork-flow/` 和 `template/skills/` 为唯一分发源，不覆盖任务、计划、开发者身份、项目配置或自定义 Skill。刷新后运行：
+
+```bash
+./.cowork-flow/run doctor --all --json
+```
+
+`icons:export` 需要本机存在 Edge 或 Chrome，可用 `COWORK_FLOW_BROWSER` 指定可执行文件。浏览器缺失时命令会失败，不会把旧图当作已更新。

package/package.json

@@ -1,36 +1,66 @@
 {
   "name": "cowork-flow",
-  "version": "1.6.0",
+  "version": "1.7.2",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
+  "keywords": [
+    "ai-agent",
+    "workflow",
+    "task-lifecycle",
+    "subagents",
+    "codex",
+    "claude-code",
+    "opencode",
+    "zcode",
+    "qoder",
+    "kimi-code",
+    "dsh"
+  ],
+  "homepage": "https://github.com/fishlikewater/cowork-flow#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fishlikewater/cowork-flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fishlikewater/cowork-flow/issues"
+  },
+  "author": {
+    "name": "fishlikewater",
+    "email": "fishlikewater@126.com",
+    "url": "https://github.com/fishlikewater"
+  },
   "type": "module",
   "bin": {
-    "cowork-flow": "./bin/cowork-flow.js"
+    "cwf": "bin/cowork-flow.js",
+    "cowork-flow": "bin/cowork-flow.js"
   },
   "files": [
     "bin",
     "src",
     "template",
-    "template/.zcode",
     "presets",
+    "docs",
     "README.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "!template/**/__pycache__/**",
     "!template/**/*.pyc"
   ],
   "scripts": {
     "test": "npm run test:fast",
-    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/host-assets.test.js test/kimi-hook.test.js test/opencode-plugin.test.js test/package.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
+    "test:smoke": "node --test test/smoke.test.js test/tarball-install.test.js",
+    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/cli-registry.test.js test/claude-code-plugin.test.js test/codex-plugin.test.js test/contract-fingerprint.test.js test/docs.test.js test/host-assets.test.js test/host-command.test.js test/kimi-hook.test.js test/kimi-plugin.test.js test/opencode-plugin-installer.test.js test/opencode-plugin.test.js test/package.test.js test/plugin-metadata.test.js test/plugin-payload.test.js test/qoder-plugin.test.js test/smoke.test.js test/stage-contract.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
     "test:integration": "node --test --test-name-pattern=\"^(init copies the template into a new target directory|sync updates safe template files and preserves protected files)$\" test/init.test.js test/sync.test.js",
     "test:node:full": "node --test",
     "test:template": "node scripts/run-template-tests.js --suite core",
     "test:template:full": "node scripts/run-template-tests.js --suite full",
     "pack:check": "node scripts/pack-check.js",
-    "source:refresh:dry-run": "node bin/cowork-flow.js source-refresh --dry-run",
-    "source:refresh": "node bin/cowork-flow.js source-refresh",
+    "icons:export": "node scripts/export-icons.mjs",
+    "source:refresh:dry-run": "node bin/cowork-flow.js dev refresh --dry-run",
+    "source:refresh": "node bin/cowork-flow.js dev refresh",
     "test:all": "npm run test:node:full && npm run test:template:full && npm run pack:check",
     "release:check": "npm run test:all",
     "release": "sh scripts/release.sh",
-    "test:windows:core": "npm run test:fast && npm run test:integration && npm run pack:check && npm run test:template"
+    "test:windows:core": "npm run test:fast && npm run test:integration && node --test test/dsh-home-patch.test.js test/dsh-hook.test.js test/dsh-preset.test.js test/dsh-preset-bundle.test.js test/mcp-client-matrix.test.js test/mcp-state-command.test.js test/tarball-install.test.js && npm run pack:check && npm run test:template"
   },
   "engines": {
     "node": ">=20"

package/presets/claude-code/.claude-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "cowork-flow",
+  "version": "1.7.2",
+  "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Claude Code。",
+  "displayName": "Cowork Flow",
+  "author": {
+    "name": "fishlikewater",
+    "email": "fishlikewater@126.com",
+    "url": "https://github.com/fishlikewater"
+  },
+  "homepage": "https://github.com/fishlikewater/cowork-flow",
+  "repository": "https://github.com/fishlikewater/cowork-flow",
+  "license": "MIT",
+  "keywords": [
+    "ai-agent",
+    "workflow",
+    "task-lifecycle",
+    "subagents",
+    "codex",
+    "claude-code",
+    "opencode",
+    "zcode",
+    "qoder",
+    "kimi-code",
+    "dsh"
+  ],
+  "skills": "./skills/"
+}