flower-trellis 0.3.1-beta.4 → 0.3.1-beta.6

package/README.md

@@ -105,7 +105,7 @@ flower banner → 平台多选菜单 → Trellis 原生交互(模板 / monorepo
 
 - **统一品牌头部**:Trellis 子进程在伪终端(`node-pty`)中运行,其原生的模板 / monorepo / 冲突等交互完整保留,但重复打印的启动 banner 被过滤,全程只呈现一个 flower banner。
 - **按平台铺设技能**:Claude 铺到 `.claude/skills`,Codex / Gemini 等铺到 `.agents/skills`;并对 codex 做后处理(兼容清理旧 `config.toml` 的 `[features.multi_agent_v2]`,在保留上游 hooks 的基础上补全 `SessionStart`)。
-- **幂等执行**:`workflow.md` 注入前先按 `BEGIN/END` 标记清除旧块再重注入(块数恒定,不会翻倍,首次注入前备份 `.bak`);技能文件覆盖式铺设,并通过 `.trellis/.flower-manifest.json` 记录已铺路径,升级时删除已淘汰项。
+- **幂等执行**:`workflow.md` 注入前先按 `BEGIN/END` 标记清除旧块再重注入(块数恒定,不会翻倍,首次注入前备份到 `.trellis/.backup-flower/`);技能文件覆盖式铺设,并通过 `.trellis/.flower-manifest.json` 记录已铺路径,升级时删除已淘汰项。
 - **上线事项账本**:强化包通过 finish-work skill override 在归档前智能识别 SQL、配置、批处理 / 部署脚本 / 数据修复、外部系统 / 依赖平台等上线事项,必要时写入任务 `release.md`;`trellis-release` 可在正式上线前核对任务文档、`release.md` 和 git 证据,生成 `YYYY-MM-DD-<release-slug>.md` 格式的版本 / 批次操作单。
 - **安全中止**:`Ctrl+C` 取消后不会继续叠加。
 

package/enhancements/0.6/.agents/skills/trellis-create-command/SKILL.md

@@ -74,7 +74,7 @@ description: "Create a new trellis entry as command or skill; writes agents copy
 | 形态 | 何时选 | 触发方式 |
 |------|--------|---------|
 | **command** | 显式动作、高风险、需确认点（如 finish-work、continue） | `/trellis:<name>` |
-| **skill** | 自然语可触发、查询 / 分析 / 检查、低破坏性（如 check-all、extract-prd、draw-uml） | Claude 自动路由 + `/trellis-<name>` |
+| **skill** | 自然语可触发、查询 / 分析 / 检查、低破坏性（如 check-all、extract-prd、visualize） | Claude 自动路由 + `/trellis-<name>` |
 
 决定不了时**推荐 skill**：自然语路由更灵活，显式斜杠仍可用。反过来，后悔做成 skill 想改 command 比较费事。
 
@@ -253,7 +253,7 @@ cp -r <target>/.agents/skills/trellis-<X> <skill-garden>/.trellis/0.6/.agents/sk
 | Create / generate（从零创建） | `create-` | `create-command` |
 | Analyze | `analyze-` | `analyze-task` |
 | Sync / update | `sync-` / `update-` | `sync-prd` / `update-spec` |
-| 动作类 | 动词开头 | `push` / `draw-uml` |
+| 动作类 | 动词开头 | `push` / `visualize` |
 
 > **0.6 命名取舍**：「严格提取」类用 `extract-` 前缀（强调原文不动、禁止发挥）；「从零创建」类才用 `create-` 前缀（如 create-command）。区分这两者能让 AI 在触发时不混淆生成 vs 提取的语义。
 

package/enhancements/0.6/.agents/skills/trellis-route/SKILL.md

@@ -6,27 +6,30 @@ description: |
   trellis-check is hidden and only available when the user explicitly requests "light check" / "轻量检查".
   Invoked from Phase 2.1 target=implement and Phase 2.2 target=check/check-all of the routing-aware workflow.
   Current-task repair/recheck loops reuse the latest valid route decision instead of prompting again.
+  Compacted resumes recover same-session route choices from gitignored runtime state before prefs or prompting.
   Final re-checks return to Phase 2.2 before commit.
   Skip in non-trellis projects (no .trellis/). Not for other subagents (trellis-research / trellis-debug).
 ---
 
 # Trellis 路由器：implement / check 执行模式选择
 
-主 agent 进入 Phase 2.1 实现路由或 Phase 2.2 检查路由时调用本 skill。当前任务内已有合法来源的最近 route 决策时，后续实现、修复、重检默认复用该决策；没有合法决策时才进入本 skill 或同编号 fallback。提交前确实需要最终复查时，回到 Phase 2.2 并复用当前任务的合法 check route，除非用户明确要求重选。
+主 agent 进入 Phase 2.1 实现路由或 Phase 2.2 检查路由时调用本 skill。当前上下文或 session runtime state 内已有合法来源的最近 route 决策时，后续实现、修复、重检默认复用该决策；没有合法决策时才进入本 skill 或同编号 fallback。提交前确实需要最终复查时，回到 Phase 2.2 并复用当前任务的合法 check route，除非用户明确要求重选。
 
 个人配置只写入 `.trellis/.route-prefs.tmp`。该文件匹配 `.trellis/.gitignore` 的 `*.tmp` 规则，属于开发者本地偏好，不纳入 git，也不影响其他开发者。
 
+本轮 route 决策写入当前 session runtime 文件 `.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions` 字段。该文件匹配 `.trellis/.gitignore` 的 `.runtime/` 规则，只保存当前 AI session/window 的执行状态，用于压缩后恢复；它不是任务属性，不写入 `.trellis/tasks/**`，也不是长期团队配置。
+
 ---
 
 ## Step 0: 识别目标与用户意图
 
-个人 route 配置只决定“已获准执行后的模式”，不是开工授权。读取 `.trellis/.route-prefs.tmp` 前，必须确认当前 workflow 已允许进入对应 target：implement 需要任务已完成规划确认并处于 `in_progress`；check 用于 Phase 2.2 检查执行，或用户明确要求最终复查 / 轻量检查。最终复查只有在 Phase 2.2 结果缺失、风险较高或用户明确要求复查时才回到 Phase 2.2；回到 Phase 2.2 后优先复用当前任务的合法 check route，除非用户明确要求重选/临时改/清除默认。如果仍在 planning、等待用户确认，或用户表达“等一下 / 我再想想”，停止，不读取个人配置。
+个人 route 配置只决定“已获准执行后的模式”，不是开工授权。调用 helper 前，必须确认当前 workflow 已允许进入对应 target：implement 需要任务已完成规划确认并处于 `in_progress`；check 用于 Phase 2.2 检查执行，或用户明确要求最终复查 / 轻量检查。最终复查只有在 Phase 2.2 结果缺失、风险较高或用户明确要求复查时才回到 Phase 2.2；回到 Phase 2.2 后优先复用当前任务的合法 check route，除非用户明确要求重选/临时改/清除默认。如果仍在 planning、等待用户确认，或用户表达“等一下 / 我再想想”，停止，不读取 runtime/prefs。
 
-合法 route 决策必须能追溯到 `trellis-route`、同编号 fallback 选项，或由本 skill 读取到的有效 `.trellis/.route-prefs.tmp` 配置。用户自然语言说过“inline/subagent”、compact summary、SessionStart 摘要、`codex-mode`、空 `.route-prefs.tmp`、旧单值偏好，都不能单独作为有效 route 决策。
+合法 route 决策必须能追溯到 `trellis-route`、同编号 fallback 选项，或由本 skill 读取到的有效 `.trellis/.route-prefs.tmp` 配置。runtime state 只能保存和恢复这些原始合法来源，不能把 `.runtime` 自身当成新的 `route_decision.source`。用户自然语言说过“inline/subagent”、compact summary、SessionStart 摘要、`codex-mode`、空 `.route-prefs.tmp`、旧单值偏好，都不能单独作为有效 route 决策。
 
-当前任务内已有 target 匹配且来源合法的 route 决策时，后续实现、check 发现问题、用户指出刚检查过的实现有问题、修复后重检、提交前复查均默认复用最近 implement/check 路由；除非用户明确要求重选/临时改/清除默认，不再调用本 skill。
+当前上下文内已有 target 匹配且来源合法的 route 决策时，后续实现、check 发现问题、用户指出刚检查过的实现有问题、修复后重检、提交前复查均默认复用最近 implement/check 路由；除非用户明确要求重选/临时改/清除默认，不再调用本 skill。当前上下文没有 route 决策但 runtime state 命中时，本 skill 恢复该决策并输出同样的结构化 `route_decision`。
 
-Codex inline mode 只表示主会话默认直接执行，不是 route 选项过滤器。即使当前上下文出现 `<codex-mode>inline...do not dispatch...</codex-mode>` 或 `workflow-state:in_progress-inline`，也不能推断“只能 inline”或跳过 subagent 选项；仍必须读取 `.trellis/.route-prefs.tmp`，或在无有效配置时展示正常 inline/subagent 选项。若本 skill 的紧邻路由决定是 subagent，本步骤允许主 agent dispatch 对应 implement/check sub-agent；禁止的是绕过 `trellis-route` 直接 dispatch。
+Codex inline mode 只表示主会话默认直接执行，不是 route 选项过滤器。即使当前上下文出现 `<codex-mode>inline...do not dispatch...</codex-mode>` 或 `workflow-state:in_progress-inline`，也不能推断“只能 inline”或跳过 subagent 选项；仍必须通过 helper resolve runtime/prefs，或在无有效配置时展示正常 inline/subagent 选项。若本 skill 的紧邻路由决定是 subagent，本步骤允许主 agent dispatch 对应 implement/check sub-agent；禁止的是绕过 `trellis-route` 直接 dispatch。
 
 先判断本次路由目标：
 
@@ -45,45 +48,21 @@ Codex inline mode 只表示主会话默认直接执行，不是 route 选项过
 
 ---
 
-## Step 1: 读取个人路由配置
-
-仅在没有覆盖意图时读取 `.trellis/.route-prefs.tmp`。
-
-配置格式是简单 key-value 文本：
-
-```text
-implement=inline
-check=check-all-inline
-```
+## Step 0.5: 解析已有 route state
 
-允许值：
+仅在没有覆盖意图、当前上下文没有 target 匹配的合法 `route_decision` 时调用 helper 解析已有状态。helper 的解析顺序固定为：当前 session runtime 文件里的 `route_decisions` → `.trellis/.route-prefs.tmp`。命中 `.route-prefs.tmp` 时，helper 会自动把 `source=route-prefs` 的决策写回当前 session runtime，后续压缩恢复不需要再次读 prefs。
 
-- `implement`: `inline` / `subagent`
-- `check`: `check-all-inline` / `check-all-subagent`
-
-读取参考：
+调用随本 skill 分发的 helper；不要在对话中内嵌或改写 helper 逻辑：
 
 ```bash
-PREF_FILE=".trellis/.route-prefs.tmp"
-if [ -f "$PREF_FILE" ]; then
-  IMPLEMENT_PREF=$(awk -F= '$1=="implement"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
-  CHECK_PREF=$(awk -F= '$1=="check"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
-fi
+python3 .agents/skills/trellis-route/scripts/route_state.py resolve --target <implement|check>
+# Claude 平台若只有 .claude skill 副本，则使用：
+python3 .claude/skills/trellis-route/scripts/route_state.py resolve --target <implement|check>
 ```
 
-规则：
+helper 只接受当前 session 或唯一 session fallback 的 `.trellis/.runtime/sessions/<context-key>.json`，并只从 `route_decisions.<target>` 恢复决策。命中时输出 `{"status":"hit", ...}`，其中 `decision` 已经过 task/target/source/mode/scope 校验，可跳过 Step 2 并进入 Step 3 输出决策。`source=route-prefs` 且 `wrote_runtime=true` 时，输出模板同时写明来自个人 route 配置和已写入 session runtime state。
 
-- `target=implement` 且 `IMPLEMENT_PREF` 是 `inline` / `subagent`：跳过 Step 2，进入 Step 3。
-- `target=check` 且 `CHECK_PREF` 是 `check-all-inline` / `check-all-subagent`：跳过 Step 2，进入 Step 3。
-- 配置缺失、值不合法、目标 key 缺失：忽略配置，进入 Step 2。
-- 文件损坏严重时可删除 `.trellis/.route-prefs.tmp`，然后进入 Step 2。
-
-配置命中时，输出指令必须写明：
-
-```markdown
-来自个人 route 配置：`.trellis/.route-prefs.tmp` (<key>=<value>)。
-如需临时改或重新显示选项，说“route 重新选择”“这次用 subagent”“清除 route 默认”等。
-```
+输出 `status=miss`、文件缺失、JSON 损坏、任务不匹配、source/mode 不合法、prefs 缺失或 prefs 值不合法时，忽略已有状态并继续 Step 2。不要删除不匹配 runtime 文件，避免误伤其他窗口。
 
 ---
 
@@ -93,7 +72,7 @@ fi
 
 如果当前平台或模式没有 `AskUserQuestion` / `request_user_input`，不要自行选择 inline 或 subagent 继续。改用普通聊天消息原样呈现同一组编号选项，并停止等待用户回复；用户回复数字后再进入 Step 2.5 / 2.6 / 3。
 
-### target = implement，且无可用配置
+### target = implement，且 resolve 未命中
 
 - **question**: "本次 implement 走哪种模式？"
 - **header**: "Impl 模式"
@@ -114,7 +93,7 @@ fi
   4. label "4. 更新默认为 Subagent", description "本次使用 subagent，并写入个人配置"
   5. label "5. 清除默认", description "删除 implement 默认，然后重新显示无配置选项"
 
-### target = check，且无可用配置
+### target = check，且 resolve 未命中
 
 普通 check 路由不展示轻量 `trellis-check`。
 
@@ -172,35 +151,35 @@ fi
 
 ---
 
-## Step 2.6: 写入或清除个人配置
+## Step 2.6: 写入 route state / 默认配置
+
+用户选择本次模式后，调用 helper 写入当前 session runtime。选项含“保存默认”或“更新默认”时，加 `--save-pref`，helper 会同时更新 `.trellis/.route-prefs.tmp` 并保留另一个 target 的偏好。
+
+只影响本次：
 
-选项含“保存默认”或“更新默认”时，更新 `.trellis/.route-prefs.tmp`。写入时保留另一个 target 的偏好；没有另一个 target 时只写当前 key。
+```bash
+python3 .agents/skills/trellis-route/scripts/route_state.py write --target <implement|check> --mode <mode> --source <trellis-route|numbered-fallback>
+# Claude 平台若只有 .claude skill 副本，则使用：
+python3 .claude/skills/trellis-route/scripts/route_state.py write --target <implement|check> --mode <mode> --source <trellis-route|numbered-fallback>
+```
 
-推荐写法：
+保存 / 更新默认：
 
 ```bash
-PREF_FILE=".trellis/.route-prefs.tmp"
-mkdir -p .trellis
-OLD_IMPLEMENT=$(awk -F= '$1=="implement"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
-OLD_CHECK=$(awk -F= '$1=="check"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1)
-
-# 按用户选择覆盖其中一个值：
-# NEW_IMPLEMENT="inline" 或 "subagent" 或沿用 "$OLD_IMPLEMENT"
-# NEW_CHECK="check-all-inline" 或 "check-all-subagent" 或沿用 "$OLD_CHECK"
-
-{
-  [ -n "$NEW_IMPLEMENT" ] && printf 'implement=%s\n' "$NEW_IMPLEMENT"
-  [ -n "$NEW_CHECK" ] && printf 'check=%s\n' "$NEW_CHECK"
-} > "$PREF_FILE"
+python3 .agents/skills/trellis-route/scripts/route_state.py write --target <implement|check> --mode <mode> --source <trellis-route|numbered-fallback> --save-pref
+# Claude 平台若只有 .claude skill 副本，则使用：
+python3 .claude/skills/trellis-route/scripts/route_state.py write --target <implement|check> --mode <mode> --source <trellis-route|numbered-fallback> --save-pref
 ```
 
-清除默认时：
+清除默认：
 
-- 清除 implement 默认：只移除 `implement=...`，保留 `check=...`。
-- 清除 check 默认：只移除 `check=...`，保留 `implement=...`。
-- 如果文件最终为空，删除 `.trellis/.route-prefs.tmp`。
+```bash
+python3 .agents/skills/trellis-route/scripts/route_state.py clear-pref --target <implement|check>
+# Claude 平台若只有 .claude skill 副本，则使用：
+python3 .claude/skills/trellis-route/scripts/route_state.py clear-pref --target <implement|check>
+```
 
-不要把 `.trellis/.route-prefs.tmp` 纳入任何提交计划。
+helper 写入规则：保留另一个 target 的 runtime 决策和偏好；覆盖当前 target；`source` 保持原始合法来源，正常 skill 交互用 `trellis-route`，普通聊天编号 fallback 用 `numbered-fallback`，prefs 命中由 helper 写 `route-prefs`；保留 session runtime 文件中的 `platform`、`current_task`、`current_run` 等既有字段；内部 `task` 必须写当前 `task.py current --source` 的任务路径。写入失败不阻塞本次 route 输出，但要在回复中简短说明未持久化，压缩后可能再次询问。
 
 ---
 
@@ -224,6 +203,8 @@ OLD_CHECK=$(awk -F= '$1=="check"{print $2}' "$PREF_FILE" 2>/dev/null | tail -n 1
 ```markdown
 路由决定：<inline/subagent> <implement | check-all | check>
 [来自个人 route 配置：`.trellis/.route-prefs.tmp` (<key>=<value>)。]
+[来自 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
+[已写入 session runtime route state：`.trellis/.runtime/sessions/<context-key>.json` 的 `route_decisions`。]
 [说明：用户明确请求轻量检查，使用隐藏逃生口。]
 
 route_decision:
@@ -241,21 +222,23 @@ route_decision:
 - <要避免的工具调用>
 ```
 
-中括号内行为条件性出现：仅命中个人配置时显示配置行；仅轻量 check 时显示隐藏逃生口说明；仅 implement subagent + skip_compile=true 时附加“跳过编译”段。`route_decision` 必须保留在回复、交接摘要或 compact summary 中；没有 `source` 的自然语言偏好不能被后续 agent 复用为 route。
+中括号内行为条件性出现：仅命中个人配置时显示配置行；仅命中 runtime state 时显示“来自”行；写入 runtime state 成功时显示“已写入”行；仅轻量 check 时显示隐藏逃生口说明；仅 implement subagent + skip_compile=true 时附加“跳过编译”段。`route_decision` 必须保留在回复中；compact summary 若只有自然语言描述，后续 agent 仍应优先读取 runtime state，而不是把 summary 当证据。
 
 ---
 
 ## 核心原则
 
 1. **个人配置私有**：`.trellis/.route-prefs.tmp` 是本地偏好，gitignored，不能进入提交计划。
-2. **正常路由少打断**：命中个人配置时直接输出路由决定，不再重复询问。
-3. **显式覆盖优先于配置**：用户要求临时改、重新选择或清除默认时，必须重新展示选项，不能让配置优先。
-4. **当前任务复用路由**：当前任务内已有合法来源的最近 implement/check 路由时，后续实现、修复、重检和复查默认沿用，不再次询问模式。
-5. **check 默认全面检查**：普通 check 路由只展示 `check-all` inline/subagent，不推荐轻量 `trellis-check`。
-6. **轻量 check 是隐藏逃生口**：只有用户明确请求 `light check` / `轻量检查` 时才可走轻量 `trellis-check`。
-7. **决策与执行分离**：本 skill 只输出指令，下一轮由主 agent 调工具。
-8. **严格执行用户选择**：路由结论一旦输出，主 agent 必须按指令执行，不可“出于谨慎”再换路径。
-9. **Codex inline 不裁剪选项**：Codex inline 是默认执行模式，不是只能 inline 的强制模式；route 明确选中 subagent 时，本步骤可按 subagent 路径执行。
+2. **runtime state 私有**：`.trellis/.runtime/sessions/` 是 session/window 状态，gitignored，不能进入提交计划。
+3. **压缩恢复少打断**：当前上下文没有 route 决策时，先读 runtime state；命中当前任务/target 的合法决策就复用，不查 `trellis mem`，也不重问。
+4. **个人默认次于本轮决策**：runtime state 表示“本轮已选”，优先于 `.route-prefs.tmp`。
+5. **显式覆盖优先于一切**：用户要求临时改、重新选择或清除默认时，必须重新展示选项，不能让 runtime state 或配置优先。
+6. **当前任务复用路由**：当前任务内已有合法来源的最近 implement/check 路由时，后续实现、修复、重检和复查默认沿用，不再次询问模式。
+7. **check 默认全面检查**：普通 check 路由只展示 `check-all` inline/subagent，不推荐轻量 `trellis-check`。
+8. **轻量 check 是隐藏逃生口**：只有用户明确请求 `light check` / `轻量检查` 时才可走轻量 `trellis-check`。
+9. **决策与执行分离**：本 skill 只输出指令，下一轮由主 agent 调工具。
+10. **严格执行用户选择**：路由结论一旦输出，主 agent 必须按指令执行，不可“出于谨慎”再换路径。
+11. **Codex inline 不裁剪选项**：Codex inline 是默认执行模式，不是只能 inline 的强制模式；route 明确选中 subagent 时，本步骤可按 subagent 路径执行。
 
 ---
 
@@ -264,6 +247,8 @@ route_decision:
 - 在本 skill 内部直接调用 `Agent` / `Skill` 工具。
 - 用户要求临时改 / 重新选择时，仍直接使用 `.trellis/.route-prefs.tmp`。
 - 把 `.trellis/.route-prefs.tmp` 加入 git 暂存或提交计划。
+- 把 `.trellis/.runtime/sessions/` 加入 git 暂存或提交计划。
+- runtime state 的 task/target/source/mode 不匹配时仍复用。
 - 在普通 check 选项里展示 `Check inline` / `Check subagent`。
 - 没有用户明确请求时，把 check 降级到轻量 `trellis-check`。
 - `AskUserQuestion` / `request_user_input` 不可用时，记录为 inline 或 subagent 路径并继续。
@@ -280,5 +265,7 @@ route_decision:
 
 - **非 trellis 项目**（无 `.trellis/`）：输出“非 trellis 项目，跳过路由”，不阻断流程。
 - **config.yaml 缺失或字段缺失**：视为 false，不附加跳过编译指令。
+- **无法解析 session context key**：跳过 runtime state 读写，继续 `.route-prefs.tmp` 或展示选项。
+- **runtime state 损坏或不匹配**：忽略该文件，继续 `.route-prefs.tmp` 或展示选项；不要删除。
 - **.route-prefs.tmp 内容损坏**：忽略偏好；必要时删除该文件并重新展示选项。
 - **旧单值偏好**：文件内容只有 `inline` / `subagent` 时视为无效配置，按无配置处理并重新展示选项。