cowork-flow 1.7.1 → 1.7.3

package/CHANGELOG.md

@@ -5,6 +5,26 @@
 ### Added
 
 
+## [1.7.3] - 2026-10-06
+
+### Fixed
+
+- ZCode 插件 hook shim 由 `.js` 改为 **`.mjs`**，并修复项目根向上查找只覆盖两层的缺陷（1.7.2 遗留说明的收口）。修前两个缺陷叠加：shim 安装到宿主插件缓存目录后无 `package.json`，`.js` 按 CommonJS 解析，ESM `import` 只靠 Node ≥23 的语法探测兜住——仓库声明最低 Node 20，这些机器上 shim 直接语法错误，SessionStart / UserPromptSubmit / PostToolUse 注入从未发生；同时 `findWorkflowRoot` 在循环外缓存 `dirname(current)`，向上查找只覆盖起始目录与其父，hook 事件的 cwd 在项目根下两级及以上（例如从子目录打开会话）时定位不到项目运行时，注入同样为空。现在对齐 qoder / kimi 先例：`.mjs` 扩展名 + `resolve` 起步 + 逐级向上直到文件系统根，其余传输行为零变化。升级动作：升级 CLI 后运行 `cwf host add zcode --force` 刷新插件缓存，并重启 ZCode。
+
+
+## [1.7.2] - 2026-10-04
+
+### Added
+
+- GitHub 现在会在收到 `v*` tag 推送时自动发布 npm：`.github/workflows/publish.yml` 新增 `push: tags` 触发器与按 tag 归一的 `concurrency` 锁（同一 tag 的重复触发串行化而非并发抢发），`scripts/release.sh --no-publish` 改为推送分支与 tag 并把发布交给 CI，`gh release create` 降级为可选的 Release 说明入口。推送 tag 即发布，无需再手工建 Release。
+
+### Fixed
+
+- 修复 tag 推送通道的空转：`verify-ubuntu` / `verify-windows` / `publish` 三个 job 的触发条件此前只认 `release` 事件和 `inputs.ref`，`on: push: tags` 触发工作流后三个 job 会被全部跳过——运行显示绿色却不会发布任何内容。三个门禁现在都放行 push 事件；Ubuntu 与 Windows 双平台验证仍是发布的硬前置。新增 `test/package.test.js` 断言锁住这一行为。
+- npm 发布改用 **Trusted Publishing**（OIDC）：publish job 声明 `id-token: write`，用 GitHub OIDC token 换取短期 npm 凭据，仓库不再保存长期 token。OIDC 交换需要 npm ≥ 11.5.1，而 Node 20 自带 npm 10，因此仅 publish job 改跑 Node 24（两个验证 job 保持 Node 20，与 `engines` 声明一致）。`setup-node` 保留 `registry-url` 以便 npm 读到 registry 后发起交换，但不提供 `NODE_AUTH_TOKEN`——占位符保持未解析，npm 先试交换、失败才回退。此前用 `NPM_TOKEN` secret 时，账号开启双因素认证会导致 CI 发布以 `EOTP` 失败。
+- `package.json` 的 `bin` 路径去掉 `./` 前缀：npm 发布时会自动清理并告警，导致 tarball 里的 package.json 与源码不一致。
+- Qoder 插件 hook 不再由宿主解析 `python`：改为 **Node 传输 shim**（`command: "node"` + `hooks/inject-context.mjs`），与 ZCode 插件同形态。修前在没有 `python` 命令的机器上（macOS 12.3+、只装 `python3` 的发行版），hook 以 `spawn python ENOENT` 静默失败，SessionStart / UserPromptSubmit 注入从未发生，日志里只有 `Non-blocking hook error(s) … Continuing execution`；Windows 上则依赖 `python.exe` 恰好在 PATH，商店版 Python 等环境同样哑。新 shim 由宿主必备的 Node 运行，内置 `COWORK_FLOW_PYTHON → python3 → python → py -3` 探测链自行定位项目运行时解释器，探测不到时保持 fail-open（exit 0）。升级动作：`cwf host add qoder --force` 刷新插件缓存后重启 Qoder。ZCode 的 `.js` shim（ESM 语法）在安装目录无 `package.json` 时依赖 Node ≥23 的语法探测，仓库声明的最低 Node 20 上会崩溃，建议后续同样改 `.mjs`——本次未动 ZCode。
+
 ## [1.7.1] - 2026-09-30
 
 ### Fixed
@@ -269,7 +289,9 @@
 
 此版本未保留本地条目正文，详情见 [GitHub Release](https://github.com/fishlikewater/cowork-flow/releases/tag/v0.0.47)。
 
-[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.1...HEAD
+[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.3...HEAD
+[1.7.3]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.2...v1.7.3
+[1.7.2]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.1...v1.7.2
 [1.7.1]: https://github.com/fishlikewater/cowork-flow/compare/v1.7.0...v1.7.1
 [1.7.0]: https://github.com/fishlikewater/cowork-flow/compare/v1.6.0...v1.7.0
 [1.6.0]: https://github.com/fishlikewater/cowork-flow/compare/v1.5.0...v1.6.0

package/docs/direction.md

@@ -0,0 +1,167 @@
+# cowork-flow 方向规划：Agent 运行时上下文与协作事实层
+
+> 状态：**已批准（Approved）** · 创建：2026-08-27 · 决策记录：注入格式取舍选**方案 A**（结构化事实头 + 人读摘要体，分级降级）
+> 本文档是后续阶段立项的权威输入。任何方向的修订必须先更新本文档再立项。
+
+---
+
+## 0. 状态追踪（防遗忘，后续会话先看这里）
+
+| 阶段 | 状态 | 关联任务 / 提交 | 下一动作 |
+|---|---|---|---|
+| 阶段 0：定位与协议收敛 | ✅ 完成 | 08-27-stage0-positioning-protocol（0c7ae64） | — |
+| 阶段 1：事实层 API 化 + 注入结构化 | ✅ 完成 | 1a: 08-28-stage1a-state-fact-view（60753fa）；1b: 08-28-stage1b-structured-fact-header（5cb25ea） | — |
+| 阶段 2：多执行者语义 | ✅ 完成 | 08-28-stage2-multi-executor（fd4d6af）：executor 归属 / 冲突拦截 / --takeover / 无会话 start / evidence 证据位 | — |
+| 阶段 3：协议生态适配 | ✅ 完成（观察期持续） | 08-29-stage3-mcp-fact-access（a88474e）：`run mcp-state` 无依赖 MCP 只读服务 + `fact-layer-access.md` 接入契约 | 观察 AGNTCY 等协议收敛；写工具默认拒绝，需重开契约 |
+| 本规划文档落库 | ✅ 完成 | 08-27-direction-doc | — |
+| 1.5→1.7 宿主广度 + 发布链（七宿主） | ✅ 完成 | CHANGELOG 1.5.0-1.7.2 | — |
+| 1.7.3 维护：ZCode shim .mjs + 项目根查找修复 | ✅ 完成 | 10-04-zcode-shim-mjs（d0716a9） | — |
+| 1.8.0 立项：证据化完成 | 🔄 立项完成，待启动 | 10-05-direction-1-8-0 / 10-05-evidence-completion | 在宿主会话启动主线任务 |
+
+**当前结论**：方向路线图阶段 0-3 全部落地。项目当前形态：「多主机 Agent 协作的运行时上下文与协作事实层」——事实视图（CLI + MCP）、结构化注入、跨宿主一致性治理、执行者归属与证据位均已就绪并有测试锁定。后续演进见「不做什么」边界与观察期事项。
+
+---
+
+## 1. 定位（一句话）
+
+> **cowork-flow 不约束模型怎么想；它保证任何主机上的任何 agent，在任何会话、任何时刻，从同一份权威事实起步。**
+
+| | 旧定位 | 新定位 |
+|---|---|---|
+| 叙事 | 帮你建流程（流程模板） | 运行时上下文与协作事实层 |
+| 手段 | 任务流、门禁、规格文档 | 状态注入、事实一致性、跨宿主治理 |
+| 目的 | 让协作"守规矩" | 让协作"从正确状态起步" |
+| 模型能力上升时 | 约束类价值递减（模型自己会守规矩） | 事实类价值递增（状态是模型编不出来的） |
+
+**为什么必须现在调整**：项目的消费方正在从"人"变成"agent"。注入格式还停留在给人看的文本（`<workflow-state>` 的 label:value 行 + 散文，全五宿主一致；唯一严格机器可读的是 fingerprint 属性行）。事实层（task.json+revision、state-snapshot、operations 日志、implement.jsonl、contract-registry、host-assets）已经建起来，但散落成文件约定，没有统一机器出口；决策事实（decision-anchor）完全不在注入体系内。
+
+## 2. 背景：大模型发展对项目的五个冲击
+
+1. **模型能力上升** → "约束模型"价值递减（门禁、防呆、状态机防漂移——模型越强越不需要被管），"喂状态"价值递增（上下文质量成为 agent 质量的第一杠杆）。
+2. **人机对话 → agent 集群执行**（远程/后台/并行/批处理/CI 触发）→ 会话模型需支持无会话执行者、多执行者协作、委派与收归。
+3. **上下文工程成为学科**（token 预算、注入时机、摘要压缩、状态新鲜度）→ 项目已有的五宿主 hook 注入、digest 指纹、快照单源正是"运行时上下文中枢"，应提升为产品主线。
+4. **协议标准化**（MCP 成事实标准、hooks.json 类扩展点演化、agent 间协议涌现）→ 契约格式自持、host 适配保持薄层；不自创跨 agent 协议。
+5. **模型质量波动** → 门禁仍是安全网（每个新版本可能有行为回归），保留但不作为卖点投资。
+
+## 3. 现状资产盘点（2026-08-27 探查实录）
+
+### 3.1 注入层
+
+| Host | 注入机制 | 触发时机 | 格式 |
+|---|---|---|---|
+| zcode | 插件 process hook（JS，inject-context.js） | SessionStart 全量 / 每条消息单行指纹 / PostToolUse 生命周期命令刷新 | stdout JSON，内部文本块 |
+| codex | hooks.json 命令（Python） | 仅 UserPromptSubmit | 全量 digest（无 slim） |
+| claude-code | settings.json hook（Python） | SessionStart + 每条消息 | 全量 digest（无 slim） |
+| opencode | 插件（JS） | 每次 prompt 组装 + shell.env | 全量 digest（无 slim） |
+| dsh | 预设插件（内嵌 Python 协议） | session-start / inbox-claimed / 生命周期命令工具结果 | systemPrompt section 文本 |
+
+**已知债**：三线零代码共享（zcode JS / opencode JS / python 线）——指纹序列化策略不一致（`JSON.stringify` 不排序 vs `sort_keys` vs `stableStringify`，跨 host 指纹有分叉风险）；slim 指纹形态只有 zcode 有；codex 事件名硬编码丢弃事件维度；state-snapshot 只有 zcode 消费（Python 线仍 TAG_RE 解析 templates.md，是已确认的漂移面）。
+
+### 3.2 事实层（任务状态模型）
+
+- **权威事实（生命周期内不变）**：id/name、title、creator、assignee、createdAt、priority、description；决策事实 decision-anchor.md（目标/AC/被拒方案/假设/范围）；绑定事实 `task.json.meta.planFile`；写入痕迹 `_state.revision`+`operation_id` 与 operations/ 操作日志（追加式）。
+- **流程状态（有明确写者）**：status（planning→in_progress→review→completed，单向禁回退）、completedAt、children/parent、会话绑定（sessions/*.json、subagents/*.json）、state-snapshot.json、归档位置。
+- **死字段待清理**：`commit`（声明存在、无写入方）、`scope`、`relatedFiles`（已被 implement.jsonl 取代）、`subtasks`（无写入方）。
+- **模型**：单主人同步推进（start 必须会话身份；review/complete 已支持无会话）；子代理为受缚叶执行者（authority 五项全 false，证据生产不推进状态）；并发正确性靠 CAS+锁+UoW 恢复，已成熟。
+- **机器出口现状**：JSON 有 task.json、snapshot、implement.jsonl、sessions/subagents、operations、`task next --json`、contract-registry、host-assets；**仅人读无解析**：decision-anchor.md（只查章节字符串）、plans/*.md（v1 显式不解析）。
+
+### 3.3 治理层
+
+- 分层哲学已验证：**机器只裁决事实，判断交给 review 双人证**。
+- 硬契约：host-assets.json（能力矩阵，doctor 交叉校验）、contract-registry.json（指纹清单）、schemas/、lifecycle 文件范围白名单、plan-binding gate、发布链（release:check + CHANGELOG + 三处版本同步）。
+- 软规范：backend/frontend/game（review 强审查、非机器 gate）、references/（loadWhen 驱动）。
+- 模型能力上升时：纯防呆类（guides、error-output-as-data 类）价值递减；跨宿主一致性类（host-assets 校验、分布漂移检测、syncPolicy 保护、registry 指纹）价值递增。
+
+## 4. 为什么这是最优方向（候选否决）
+
+| 候选 | 否决理由 |
+|---|---|
+| AgentOps / 可观测性 | 无运行遥测资产，从头建等于换赛道，与工作流引擎定位断裂 |
+| 任务编排引擎 | 与主机自带编排重叠；状态模型翻成分布式系统复杂度爆炸 |
+| 纯治理合规层 | 纯门禁价值随模型自觉性上升递减；无独特性 |
+| ✅ 事实层 + 注入 | 全仓最厚资产都在这；跨主机一致性是任何单主机工具给不了的**结构性差异**；与上下文工程趋势同向且落在可执行的事实层 |
+
+## 5. 三支柱
+
+| 支柱 | 内涵 | 已有资产 | 缺口 |
+|---|---|---|---|
+| **事实层** | 权威状态与决策的可查询存储 | task.json+revision、snapshot、operations、implement.jsonl、registry、host-assets | 无统一机器出口；decision-anchor 无解析；死字段 |
+| **注入协议** | 按时机/角色/token 预算把事实注入任意 host | 五宿主注入齐备、digest 指纹、快照信任链、会话隔离 | 人读文本格式；三线拷贝；slim 不对称；决策事实不注入 |
+| **一致性治理** | 跨宿主/跨会话/跨模型的事实一致性 | doctor 交叉校验、同步保护、文件范围门禁、发布链 | 指纹序列化不一致；快照单宿主消费；无跨 host 注入行为断言 |
+
+## 6. 演进路线
+
+### 阶段 0：定位与协议收敛（低风险、高杠杆）
+- 交付：README 定位改写；新增 `spec/contracts/context-injection.md`（冻结块结构、事件时机矩阵、slim 策略、序列化规范，三线按规范对齐）；修一致性债（指纹序列化统一 sort_keys、Python 线补 slim、codex 补事件名）。
+- 验收：新增跨 host 注入行为测试——同一仓库五宿主指纹一致、slim 触发一致。
+
+### 阶段 1：事实层 API 化 + 注入结构化
+- 交付：`cowork-flow state <task> --json`（task.json+snapshot+sessions+plan 绑定+registry 汇总为一份事实视图）；workflow-state 块升级为**结构化事实头 + 紧凑人读体**（协议允许分级降级，纯文本通道退化为属性行）；决策事实条件注入（planning/in_progress 时注入 decision-anchor 要点，完成后收缩）。
+- 验收：任何 host 的 agent 可经上下文与 CLI 拿到"任务是什么、为什么、边界在哪"，且机器可解析。
+
+### 阶段 2：多执行者语义
+- 交付：owner/executor 归属字段；无会话推进放开（CLI/CI 触发）；多会话协作同一任务的协调（任务级锁/合并协议，复用 CAS+UoW）；子代理证据位独立于状态位。
+- 验收：两会话可显式接管同一任务不踩踏；子代理证据可独立推进"证据位"。
+
+### 阶段 3：协议生态适配（观察期，不承诺）
+- 交付：MCP 服务暴露事实层（只读查询先行，`state --json` 的薄壳）；观察 AGNTCY 等，不自创协议；保持 adapter 薄。
+- 验收：任何 MCP 客户端可查任务状态；生态协议出现时 2 天内可接入。
+
+## 7. 已拍板取舍
+
+- **注入格式（已决策：方案 A）**：结构化事实头 + 人读摘要体双格式，分级降级——结构化优先，通道不允许时退化为属性行/纯摘要。
+  - 否决 B（全 JSON 注入）：dsh/codex 纯文本通道浪费 token，破坏现有紧凑散文面包屑可读性。
+  - 否决 C（保持文本只加 --json 出口）：核心价值主张落不到注入本身。
+- **事实层出口（推荐）**：CLI + JSON 协议先行（零依赖），MCP 为阶段 3 的薄适配，不先建。
+- **三线收敛（推荐）**：先"协议规范单源 + 三线按规范实现"，代码级共享后议（成本高、收益在协议一致性先兑现）。
+
+## 8. 明确不做什么
+
+1. 不做"更聪明的提示词/AGENTS.md 写作术"——模型能力会追平，且无数据资产。
+2. 不自创跨 agent 通信标准——协议博弈期，等收敛。
+3. 不做任务执行引擎——不替代 agent 干活，只保证它从正确状态起步。
+4. 不深化纯流程门禁——保留为安全网，停止投资。
+
+## 9. 度量指标
+
+1. **跨宿主行为一致**：五宿主指纹/slim 触发有测试断言，0 漂移。
+2. **新 host 接入成本**：从数天降到小时级（协议规范完备度直接度量）。
+3. **注入 token 成本**：长会话注入体积不随消息数线性增长（slim 全覆盖）。
+4. **事实新鲜度事故**：多会话任务污染/踩踏事故率趋零。
+
+## 10. 2026-10 修订：1.8.0 方向（证据化完成）
+
+> 修订背景：阶段 0-3 之后，1.5→1.7 三条版本线投入宿主广度（七宿主）与发布链，广度路线边际收益递减；生态出现确定性信号，方向回到事实层纵深。本节为 1.8.0 立项的权威依据。
+
+### 10.1 生态输入（2026-10 复核）
+
+1. **spec-driven development 主流化**：GitHub Spec Kit、AWS Kiro、OpenSpec、Tessl 押同一注——spec 与代码作为可跟踪制品共同演化；市场口径是"builder 们正从自由式 vibe coding 走向结构化工作流"。cowork-flow 的 decision-anchor + plan-binding 在此赛道上，结构性差异是宿主中立、状态在仓库内——定位为这些 SDD 工具**之下的状态层**，不与其竞争。
+2. **agent 团队 / 后台 agent 兴起**：Claude Code Agent Teams 官方口径 teammates ephemeral by design，靠 git 与文件协调；"持久共享状态"成为公认缺口。cowork-flow 的任务状态在仓库、跨会话可续、executor 归属与冲突拦截（阶段 2 资产）正是该缺口的产品化。
+3. **质量与隐藏 bug 是 vibe coding 头号风险叙事**："验证证据"正在成为完成的定义。这与分层哲学（机器裁决事实、review 双人证）同向，但 AC 目前只是 decision-anchor 里的 markdown 勾选框，机器不解析。
+
+### 10.2 1.8.0 主线：证据化完成
+
+- **定义**：任务完成从"流程走完"升级为"证据齐全"——decision-anchor 的 AC 成为机器可查询事实，完成门禁校验每个 AC 关联到可验证证据（测试 / 命令输出 / evidence 记录），缺失时阻断或显式放行（对齐 spec-check 的 unchecked 语义）。
+- **最小设计立场**：不发明新格式——AC 沿用 decision-anchor 现有 `- [ ] AC-xxx:` checklist 形态做解析；证据落在任务目录 `evidence.jsonl`（每行 `{ac, kind, ref, recordedAt}`，追加式）；无 decision-anchor 或无 AC 的旧任务自动跳过（兼容路径，不产生虚假阻断）。
+- **注入面**：review / 完成阶段注入 AC 覆盖事实行（n/m 有证据）；contract digest 随之变化，需同步跨宿主一致性测试与 `spec/contracts/context-injection.md` 契约。
+- **为什么先做它**：自洽（不依赖宿主团队功能节奏）、直接回应"AI 生成代码怎么算完成"的行业焦虑、是候选 B 的前置（evidence 事实格式先定，团队协调才有可信的交接凭证）。
+
+### 10.3 候选与缓行
+
+- **候选 B（1.9.0 候选主线）：agent-teams 就绪**——把 executor / evidence / takeover 语义补成团队协调原语（任务认领、交接、依赖边），让多 agent 场景把 `.cowork-flow/tasks/` 当共享看板。延后理由：生态节奏不完全可控，且需要 1.8.0 的证据格式做地基。
+- **维持缓行**：MCP 写工具（重开 fact-layer-access 契约才可议）、新宿主接入、自创跨 agent 协议。
+- **新增待决项（维护者拍板，不并入 1.8.0）**：文档英文化 / 双语——npm 周下载约 273（2026-10-03 口径），英文社区是 SDD 讨论主场；与 AGENTS.md「文档语言：中文」约定冲突，单独立项时再议。
+
+### 10.4 度量补充
+
+5. **采用**：npm 周下载与激活项目数——1.8.0 之后用数字验证"深度路线"是否兑现。
+
+## 11. 修订记录
+
+- 2026-08-27：创建。基于三路只读探查（注入层/状态模型/治理层）+ 大模型趋势分析；用户拍板方案 A；落库任务 08-27-direction-doc。
+- 2026-08-27：阶段 0 完成并更新状态追踪。交付：README 定位改写、`spec/contracts/context-injection.md` 协议契约、指纹序列化三线统一（跨 host 一致性测试锁定）、Python 线/opencode/dsh slim、codex 事件名。任务 08-27-stage0-positioning-protocol（0c7ae64）。
+- 2026-08-28：阶段 1 完成并更新状态追踪。1a：`run state [task] --json` 事实视图（60753fa）。1b：`<workflow-state>` 属性事实头 + `<decision-anchor>` 决策要点注入，三线一致，协议契约同步（5cb25ea）。
+- 2026-08-28：阶段 2 完成并更新状态追踪。executor 归属（start 写入会话 key / 显式 `--executor`）、`LIFECYCLE-EXECUTOR-001` 冲突拦截（幂等重跑同样拦截）、`--takeover` 接管（含已激活任务）、无会话 CI start、`subagent evidence` 证据位、`run state` Executor 行（fd4d6af）。
+- 2026-08-29：阶段 3 完成并更新状态追踪——路线图阶段 0-3 全部落地。`run mcp-state` 无依赖 MCP stdio 只读服务（task_state / task_list）、`spec/contracts/fact-layer-access.md` 接入契约（只读保证 + 薄 adapter 立场）（a88474e）。观察期事项：AGNTCY 等跨 agent 协议收敛后按薄壳接入；MCP 写工具默认拒绝，提案须先重开 fact-layer-access 契约。
+- 2026-08-29：MCP 全局入口补充——npm CLI 新增 `cowork-flow mcp-state` 透传命令（cwd 向上定位项目运行时、stdio inherit、退出码透传），MCP 客户端全局注册一次即可服务所有项目，消除逐项目 `.mcp.json` 配置（9a1fa86）。
+- 2026-08-29：后续方向 P0-P3 执行完毕。**P0**：1.1.0 发布——dev→master 合并、CHANGELOG 1.1.0 段（含 1.0.0 载体错位注明）、tag v1.1.0 与 GitHub Release 创建；publish CI 首跑曝光 node:full 存量问题（dsh-hook 依赖 gitignored 运行时、Windows 无法 exec shebang 脚本、test runner IPC 崩溃）并全部修复——双平台门禁现已全绿。**发布确认：npm registry `cowork-flow@1.1.0` 已上线（dist-tag latest），AC-004 闭合，发版任务归档。** **P1**：`docs/mcp-client-setup.md`（codex/opencode/claude-code/zcode 真实注册格式）+ `test/mcp-client-matrix.test.js` 客户端等效启动验证。**P1'**：publish.yml 链路实测核对并写入 README 发布节。**P2**：flaky 组合复跑 5 轮未复现（记录为单次现象）；doctor 会话卫生无残留。**P3**：观察期边界维持——MCP 写工具默认拒绝，AGNTCY 等协议收敛后按薄壳接入。- 2026-10-05：2026-10 修订落库（任务 10-05-direction-1-8-0）。1.7.3 维护完成（10-04-zcode-shim-mjs，d0716a9：ZCode shim 改 .mjs、findWorkflowRoot off-by-one 修复）；1.8.0 主线定为**证据化完成**，主线任务 10-05-evidence-completion 立项（planning 就绪待启动）；候选 B（agent-teams 就绪）列为 1.9.0 候选主线；文档英文化列为待决项，待维护者拍板。方向文档自本次起恢复版本控制（087ef72 untrack 后首次入库）。

package/docs/index.md

@@ -11,6 +11,7 @@
 | 了解项目文件如何组织 | [工作原理与扩展点](architecture.md) | 运行时、`template/`、`presets/`、规范检查和扩展边界 |
 | 参与项目开发 | [贡献指南](../CONTRIBUTING.md) | 本地环境、代码约定、测试和 PR 检查 |
 | 了解测试与发布流程 | [开发与发布](release.md) | 测试分层、CI、版本发布和维护者命令 |
+| 了解项目方向与版本规划 | [方向规划](direction.md) | 定位声明、演进路线、已拍板取舍和版本主线 |
 | 查某个版本改了什么 | [更新日志](../CHANGELOG.md) | 按版本记录的功能变化、修复和迁移说明 |
 
 ## 常见阅读路径

package/docs/release.md

@@ -36,7 +36,7 @@ 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，但不执行 `npm publish` |
+| `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 或发布；如果检查开始时已有本地修改，脚本会在任何刷新前停止。
@@ -48,7 +48,7 @@ npm run test:template:full
 1. 确认工作树和更新日志符合预期。
 2. 运行 `npm run release:check` 和 `git diff --check`。
 3. 稳定性改动按上一节重复模板测试。
-4. 运行 `npm run release -- <release-type>`；CI 通道使用 `--no-publish`。
+4. 运行 `npm run release -- <release-type>`；CI 通道使用 `--no-publish`，它会把 tag 推给 CI。
 5. 脚本同步 `package.json`、lockfile、`template/.cowork-flow/.version` 和所有随包插件清单。
 6. 检查提交与 tag，再按下面的 CI 通道发布。
 
@@ -58,25 +58,34 @@ npm run test:template:full
 
 推荐让 GitHub Actions 执行 `npm publish`：
 
-1. 在本地运行 `npm run release -- <release-type> --no-publish`，完成检查、版本、提交和 tag。
-2. 先推送分支，再显式推送 tag：
+1. 在本地运行 `npm run release -- <release-type> --no-publish`。脚本完成检查、版本、提交和 tag，然后推送分支与 tag：
 
    ```bash
    git push
    git push origin v<v>
    ```
 
-3. 创建 GitHub Release：
+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>
    ```
 
-4. `.github/workflows/publish.yml` 等待 Ubuntu 和 Windows 验证通过后，只从已存在的 `v<version>` tag 发布，并核对 tag、`package.json` 与 `template/.cowork-flow/.version` 的版本一致。
-
 不要在 tag 尚未存在于远端时运行 `gh release create`，否则 GitHub 可能从默认分支最新提交创建 tag，把发布指向错误提交。
 
-PR 和发布使用同一套 core 门禁。只有 publish job 能读取 `NPM_TOKEN`，测试 job 不接触发布凭据。
+同一 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`。
 
 ## 维护者命令
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "keywords": [
     "ai-agent",
@@ -30,8 +30,8 @@
   },
   "type": "module",
   "bin": {
-    "cwf": "./bin/cowork-flow.js",
-    "cowork-flow": "./bin/cowork-flow.js"
+    "cwf": "bin/cowork-flow.js",
+    "cowork-flow": "bin/cowork-flow.js"
   },
   "files": [
     "bin",

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

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Claude Code。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Codex。",
   "author": {
     "name": "fishlikewater",

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

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Kimi Code。",
   "author": {
     "name": "fishlikewater",

package/presets/qoder/.qoder-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 Qoder。",
   "displayName": "Cowork Flow",
   "author": {

package/presets/qoder/hooks/hooks.json

@@ -5,9 +5,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python",
+            "command": "node",
             "args": [
-              "${QODER_PLUGIN_ROOT}/hooks/inject-context.py"
+              "${QODER_PLUGIN_ROOT}/hooks/inject-context.mjs"
             ],
             "timeout": 30,
             "statusMessage": "cowork-flow: 注入工作流状态"
@@ -20,9 +20,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python",
+            "command": "node",
             "args": [
-              "${QODER_PLUGIN_ROOT}/hooks/inject-context.py"
+              "${QODER_PLUGIN_ROOT}/hooks/inject-context.mjs"
             ],
             "timeout": 30,
             "statusMessage": "cowork-flow: 注入工作流状态"
@@ -36,9 +36,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python",
+            "command": "node",
             "args": [
-              "${QODER_PLUGIN_ROOT}/hooks/inject-context.py"
+              "${QODER_PLUGIN_ROOT}/hooks/inject-context.mjs"
             ],
             "timeout": 30,
             "statusMessage": "cowork-flow: 规范自查"

package/presets/qoder/hooks/inject-context.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * cowork-flow Qoder plugin hook — transport shim.
+ *
+ * Workflow facts (workflow-state, contract digest, decision
+ * anchor, stage contract, scope/spec edits) come from the
+ * Python source
+ * <scripts>/adapters/host/inject.py; this shim does
+ * transport only:
+ *   1. project resolution from the hook payload (`cwd`),
+ *      then QODER_PROJECT_DIR / QODER_WORKING_DIR;
+ *   2. interpreter location, COWORK_FLOW_PYTHON -> python3
+ *      -> python -> py -3 — the hook runs under the host's
+ *      process PATH, which is not the user's login shell;
+ *   3. stdin passthrough to inject.py --host qoder, with
+ *      stdout forwarded and a failing project runtime
+ *      absorbed (exit 0, reason on stderr) — Qoder refuses
+ *      the prompt on a non-zero hook exit, and the hook is
+ *      machine-level, so it may meet a project runtime
+ *      older than itself.
+ *
+ * Deliberately named .mjs: the installed plugin cache has
+ * no package.json, so a plain .js entry point is parsed as
+ * CommonJS there and an `import` file would only load on
+ * Node versions that auto-detect module syntax.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { spawnSync } from "child_process";
+
+const HOST = "qoder";
+const DIR_WORKFLOW = ".cowork-flow";
+// hooks.json grants 30s per event.
+const SPAWN_TIMEOUT_MS = 25000;
+
+function readHookInput() {
+  if (process.stdin.isTTY) return { raw: "", parsed: {} };
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf8");
+  } catch {
+    return { raw: "", parsed: {} };
+  }
+  try {
+    // Tolerate a UTF-8 BOM and surrounding whitespace: the payload is
+    // forwarded verbatim either way, only the parse needs it clean.
+    const parsed = JSON.parse(raw.replace(/^\uFEFF/, "").trim());
+    return { raw, parsed: parsed && typeof parsed === "object" ? parsed : {} };
+  } catch {
+    return { raw, parsed: {} };
+  }
+}
+
+function findWorkflowRoot(startDir) {
+  if (typeof startDir !== "string" || !startDir.trim()) return null;
+  let current;
+  try {
+    current = resolve(startDir);
+  } catch {
+    return null;
+  }
+  for (;;) {
+    if (existsSync(join(current, DIR_WORKFLOW))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function findProjectRoot(parsedInput) {
+  const candidates = [
+    parsedInput?.cwd,
+    process.env.QODER_PROJECT_DIR,
+    process.env.QODER_WORKING_DIR,
+    process.cwd(),
+  ];
+  for (const candidate of candidates) {
+    const root = findWorkflowRoot(candidate);
+    if (root) return root;
+  }
+  return null;
+}
+
+function pythonCandidates() {
+  const list = [];
+  const env = (process.env.COWORK_FLOW_PYTHON || "").trim();
+  if (env) list.push([env]);
+  list.push(["python3"], ["python"]);
+  if (process.platform === "win32") list.push(["py", "-3"]);
+  return list;
+}
+
+function main() {
+  if (
+    process.env.COWORK_FLOW_HOOKS === "0" ||
+    process.env.COWORK_FLOW_DISABLE_HOOKS === "1"
+  ) {
+    process.exit(0);
+  }
+
+  const { raw, parsed } = readHookInput();
+  const root = findProjectRoot(parsed);
+  if (!root) process.exit(0);
+  const injectScript = join(
+    root,
+    DIR_WORKFLOW,
+    "scripts",
+    "adapters",
+    "host",
+    "inject.py"
+  );
+  if (!existsSync(injectScript)) process.exit(0);
+
+  for (const candidate of pythonCandidates()) {
+    let result;
+    try {
+      result = spawnSync(
+        candidate[0],
+        [...candidate.slice(1), injectScript, "--host", HOST],
+        {
+          input: raw,
+          cwd: root,
+          timeout: SPAWN_TIMEOUT_MS,
+          encoding: "utf8",
+          windowsHide: true,
+        }
+      );
+    } catch {
+      continue;
+    }
+    if (result.error || result.status === null) continue;
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    // The interpreter ran; its exit status is the project runtime's verdict,
+    // not ours. Forwarding it would let a stale project copy fail the event
+    // this hook only decorates.
+    if (result.status !== 0) {
+      process.stderr.write(
+        `cowork-flow qoder hook: inject.py exited ${result.status}; skipping injection\n`
+      );
+    }
+    process.exit(0);
+  }
+  // No interpreter could run the entry: stay silent rather
+  // than break the host's event stream (fail-open).
+  process.exit(0);
+}
+
+main();

package/presets/zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fishlikewater",

package/presets/zcode/hooks/hooks.json

@@ -8,7 +8,7 @@
             "type": "process",
             "command": "node",
             "args": [
-              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.js"
+              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.mjs"
             ],
             "timeoutMs": 5000
           }
@@ -22,7 +22,7 @@
             "type": "process",
             "command": "node",
             "args": [
-              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.js"
+              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.mjs"
             ],
             "timeoutMs": 5000
           }
@@ -37,7 +37,7 @@
             "type": "process",
             "command": "node",
             "args": [
-              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.js"
+              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.mjs"
             ],
             "timeoutMs": 5000
           }

package/presets/zcode/hooks/{inject-context.js → inject-context.mjs}

@@ -25,7 +25,7 @@
  */
 
 import { existsSync, readFileSync } from "fs";
-import { dirname, join } from "path";
+import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { spawnSync } from "child_process";
 
@@ -54,13 +54,18 @@ function readHookInput() {
 
 function findWorkflowRoot(startDir) {
   if (typeof startDir !== "string" || !startDir.trim()) return null;
-  let current = startDir;
-  const root = dirname(current);
-  while (current !== root) {
+  let current;
+  try {
+    current = resolve(startDir);
+  } catch {
+    return null;
+  }
+  for (;;) {
     if (existsSync(join(current, DIR_WORKFLOW))) return current;
-    current = dirname(current);
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
   }
-  return existsSync(join(current, DIR_WORKFLOW)) ? current : null;
 }
 
 function findProjectRoot(parsedInput) {

package/template/.cowork-flow/.version

@@ -1 +1 @@
-1.7.1
+1.7.3

package/template/.cowork-flow/scripts/adapters/host/zcode_policy.py

@@ -33,7 +33,7 @@ ZCODE_DIGEST_POLICY = (
     "read full spec files only before listed actions."
 )
 
-# The zcode shim (hooks/inject-context.js) pre-filters Bash
+# The zcode shim (hooks/inject-context.mjs) pre-filters Bash
 # events with the same rule; this entry keeps the transport
 # contract correct standalone.
 LIFECYCLE_BASH_RE = re.compile(r"\brun(?:\.cmd)?\s+(?:task|subagent|resume)\b")

package/template/.cowork-flow/spec/contracts/context-injection.md

@@ -17,13 +17,13 @@ would make the digest self-referential).
 
 | Host | Transport | Shape |
 |---|---|---|
-| zcode | process hook shim (`inject-context.js`) → `inject.py --host zcode`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
+| zcode | process hook shim (`inject-context.mjs`) → `inject.py --host zcode`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
 | codex | thin wrapper (`inject-workflow-state.py`) → `inject.py --host codex`, stdout JSON | same shape |
 | claude-code | thin wrapper (`inject-workflow-state.py`) → `inject.py --host claude-code`, stdout JSON | same shape |
 | opencode | plugin `experimental.chat.system.transform` + `shell.env` | system-prompt section push / env object |
 | dsh | preset plugin system-prompt section | named section, replace semantics |
 | kimi-code | user-level `config.toml` (`$KIMI_CODE_HOME`, default `~/.kimi-code/`) `[[hooks]]` row on `UserPromptSubmit` → shim (`cowork-flow-inject.mjs`) → `inject.py --host kimi-code` | bare-text stdout appended to the prompt context, no `hookSpecificOutput` envelope |
-| qoder | machine-level plugin `hooks/hooks.json` (`${QODER_PLUGIN_ROOT}/hooks/inject-context.py`) → project `.cowork-flow/scripts/.../inject.py --host qoder`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` plus a top-level `systemMessage` (a CLI-visible trace; the model context is unchanged); `PostToolUse` is not blockable there, so the edit advisory rides `additionalContext` on exit 0 |
+| qoder | machine-level plugin `hooks/hooks.json` (node, `${QODER_PLUGIN_ROOT}/hooks/inject-context.mjs`) → project `.cowork-flow/scripts/.../inject.py --host qoder`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` plus a top-level `systemMessage` (a CLI-visible trace; the model context is unchanged); `PostToolUse` is not blockable there, so the edit advisory rides `additionalContext` on exit 0 |
 
 The qoder row carries one delta beyond the shared envelope: `systemMessage`,
 emitted only on the two injecting events (`SessionStart`, `UserPromptSubmit`)

package/template/skills/runtime-health/scripts/doctor.py

@@ -984,7 +984,7 @@ def check_qoder_plugin(repo_root: Path) -> list[dict[str, str]]:
             "manifest is on disk there; the host cannot load a missing payload",
             "cwf host add qoder --force",
         )
-    for relative in ("hooks/hooks.json", "hooks/inject-context.py"):
+    for relative in ("hooks/hooks.json", "hooks/inject-context.mjs"):
         if not (install_path / relative).is_file():
             return _qoder_warning(
                 "PLUGIN-PAYLOAD-INCOMPLETE",

package/presets/qoder/hooks/inject-context.py

@@ -1,122 +0,0 @@
-#!/usr/bin/env python3
-"""Qoder plugin hook entry: locate the project runtime and forward the payload.
-
-Installed into the Qoder plugin cache, so this file is never next to the
-project it serves. The project is therefore resolved from the hook payload
-(`cwd`) rather than from a module-relative path, and the renderers stay in the
-project's own `.cowork-flow/scripts` — one copy of the injection logic per
-repository, never a stale second copy in the plugin cache.
-
-Fail-open by design: outside a cowork-flow project, or when the project's own
-runtime fails, this exits 0 with no injection. The hook is machine-level, so it
-meets project runtimes older than itself; Qoder refuses the prompt on a
-non-zero hook exit, and a stale project copy must never do that.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-HOST = "qoder"
-WORKFLOW_DIR = ".cowork-flow"
-INJECT_RELPATH = ("scripts", "adapters", "host", "inject.py")
-
-
-def _payload_cwd(raw: bytes) -> str | None:
-    if not raw.strip():
-        return None
-    try:
-        payload = json.loads(raw.decode("utf-8-sig"))
-    except (UnicodeDecodeError, ValueError):
-        return None
-    if isinstance(payload, dict):
-        cwd = payload.get("cwd")
-        if isinstance(cwd, str) and cwd.strip():
-            return cwd
-    return None
-
-
-def find_workflow_root(start: str | None) -> Path | None:
-    if not start:
-        return None
-    try:
-        current = Path(start).resolve()
-    except OSError:
-        return None
-    while True:
-        if (current / WORKFLOW_DIR).is_dir():
-            return current
-        parent = current.parent
-        if parent == current:
-            return None
-        current = parent
-
-
-def resolve_root(raw: bytes) -> Path | None:
-    candidates = [
-        _payload_cwd(raw),
-        os.environ.get("QODER_PROJECT_DIR"),
-        os.environ.get("QODER_WORKING_DIR"),
-        os.getcwd(),
-    ]
-    for candidate in candidates:
-        root = find_workflow_root(candidate)
-        if root is not None:
-            return root
-    return None
-
-
-def resolve_inject(root: Path) -> Path | None:
-    inject = root.joinpath(WORKFLOW_DIR, *INJECT_RELPATH)
-    return inject if inject.is_file() else None
-
-
-def main() -> int:
-    if (
-        os.environ.get("COWORK_FLOW_HOOKS") == "0"
-        or os.environ.get("COWORK_FLOW_DISABLE_HOOKS") == "1"
-    ):
-        return 0
-
-    raw = sys.stdin.buffer.read()
-    root = resolve_root(raw)
-    if root is None:
-        return 0
-    inject = resolve_inject(root)
-    if inject is None:
-        return 0
-
-    # The hook is already running under a Python 3 interpreter, so the only
-    # reason to override it is an explicit COWORK_FLOW_PYTHON; sys.executable
-    # keeps the hook working where `python` is not on PATH at all.
-    interpreter = (os.environ.get("COWORK_FLOW_PYTHON") or "").strip() or sys.executable
-    try:
-        completed = subprocess.run(
-            [interpreter, str(inject), "--host", HOST],
-            input=raw,
-            cwd=str(root),
-            timeout=25,
-        )
-    except OSError as error:
-        print(f"cowork-flow qoder hook: {error}", file=sys.stderr)
-        return 0
-    except subprocess.TimeoutExpired:
-        print("cowork-flow qoder hook: inject timed out", file=sys.stderr)
-        return 0
-    if completed.returncode != 0:
-        # Never propagate: Qoder counts a non-zero exit on SessionStart and
-        # UserPromptSubmit as a blocking hook failure. Keep the reason in the
-        # run log and leave the event alone.
-        print(
-            f"cowork-flow qoder hook: inject.py exited {completed.returncode}; skipping injection",
-            file=sys.stderr,
-        )
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())