feat: v0.2.0 多轮对话状态保持

- 新增 templates/state_template.md — _state.md 和 _timeline.jsonl 模板 - 8 条命令模板增加"第 0 步：加载项目状态"和"更新项目状态"规则 - install.sh 注入会话状态恢复逻辑（CODEBUDDY.md） - ROADMAP 调整为 v0.2.0=状态保持，v1.0.0=评测体系借鉴 gstack 的 Context Recovery + append-only JSONL 模式： _timeline.jsonl 只追加不修改作为事实来源，_state.md 做当前快照
2026-05-03 03:26:46 +08:00
parent 3bfe1a7cbe
commit ce844cdf51
11 changed files with 321 additions and 17 deletions
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -38,38 +38,47 @@
 ### 待完成
 - [ ] 知识冲突自动检测——新结论与历史矛盾时主动提醒
 - [ ] 指令执行时自动识别项目边界，找到对应 yxstack/ 目录
- [ ] YxStack 使用统计看板——哪个指令用得多、哪个领域踩坑多

-## v0.2.0 — 指令深度增强
+## v0.2.0 — 多轮对话状态保持 ← 当前
+
+- [ ] 跨会话上下文记忆——今天跑了 `/prd`，三天后跑 `/money` 时能回溯 PRD 的假设
+- [ ] 对话产出递进检测——同项目多轮对话之间，产出应递进而非重复
+- [ ] 项目级全局状态文件——`{项目根目录}/.yxstack/_state.md`，记录当前阶段、关键假设、决策链
+- [ ] 会话开始时自动读取 `_state.md`，结束会话前自动更新
+- [ ] 状态过期/矛盾标注——假设发生变化时，标记旧假设为 outdated 并记录变化原因
+
+## v0.3.0 — 指令深度增强（原 v0.2.0）

 - [ ] 为每条命令增加典型场景案例库
 - [ ] 细化各阶段追问权重与优先级
 - [ ] 增加"未完待续"处理策略（信息不足时怎么收口）

-## v0.3.0 — 命令组合模式
+## v0.4.0 — 命令组合模式（原 v0.3.0）

 - [ ] `/prd + /pfit` = 完整产品评审流程
 - [ ] `/pos + /comp` = 市场定位全景分析
 - [ ] `/uj + /metric` = 用户体验指标体系
 - [ ] 组合命令的输出融合规范

-## v0.4.0 — 场景自动识别
+## v0.5.0 — 场景自动识别（原 v0.4.0）

 - [ ] 模型无需用户显式使用 `/xxx`，自动识别当前场景
 - [ ] 自动匹配最相关的 1-2 条指令
 - [ ] 渐进式引导——先判断在哪个阶段，再切入对应清单

-## v0.5.0 — 扩展生态
+## v0.6.0 — 扩展生态（原 v0.5.0）

 - [ ] 支持行业定制模板（SaaS、电商、医疗、教育等）
 - [ ] 集成到 Hookify 体系——通过 prompt 钩子自动匹配场景
 - [ ] 社区贡献机制——开放命令模板 Pull Request 流程

-## v1.0.0 — 产品级可靠
+## v1.0.0 — 完整评测体系

- [ ] 完整评测体系（每个指令的一致性、准确性、覆盖度）
- [ ] 使用数据追踪与持续优化
- [ ] 多轮对话状态保持与上下文管理
+- [ ] 一致性评测——同一场景多轮输出是否自洽
+- [ ] 准确性评测——标准场景下输出是否命中关键点
+- [ ] 覆盖度评测——每条命令的 Checklist 是否覆盖边界情况
+- [ ] 评测集构建——10-20 个标准场景 + 期望输出标准
+- [ ] 发版前自动评测流程

 ---

--- a/commands/comp.md
+++ b/commands/comp.md
@@ -4,7 +4,16 @@
 从商业模式、价值主张、定价、获客、壁垒五个维度分析竞品，
 而不是比较功能列表。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（comp）或相关（pos）的历史记录：
@@ -72,3 +81,20 @@ tags: ["关键词1", "关键词2"]
 status: draft  # draft → validated → outdated
 ---
 ```
+
+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"comp","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
--- a/commands/gtm.md
+++ b/commands/gtm.md
@@ -4,7 +4,16 @@
 设计从 0 到 1 的冷启动策略和推广方案，核心问题是"第一批用户从哪来"
 和"怎么让他们留下来并帮你带人"。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（gtm）或相关（pos/comp）的历史记录：
@@ -67,3 +76,20 @@ tags: ["关键词1", "关键词2"]
 status: draft  # draft → validated → outdated
 ---
 ```
+
+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"gtm","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
--- a/commands/metric.md
+++ b/commands/metric.md
@@ -4,7 +4,16 @@
 搭建能真正指导决策的业务指标体系，而不是堆砌指标看板。
 含复盘框架，确保从数据中找到可行动的点。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（metric）或相关（prd）的历史记录：
@@ -71,3 +80,20 @@ tags: ["关键词1", "关键词2"]
 status: draft  # draft → validated → outdated
 ---
 ```
+
+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"metric","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
--- a/commands/money.md
+++ b/commands/money.md
@@ -3,7 +3,16 @@
 ## 命令定位
 设计可持续的商业模式和定价体系，打通付费转化链路。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（money）或相关（prd/comp）的历史记录：
@@ -67,3 +76,20 @@ tags: ["关键词1", "关键词2"]
 status: draft  # draft → validated → outdated
 ---
 ```
+
+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"money","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
--- a/commands/pfit.md
+++ b/commands/pfit.md
@@ -4,7 +4,16 @@
 在投入产品资源之前，验证用户所述「痛点」是否真实存在、
 是否足够痛、是否值得解决。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（pfit）的历史记录：
@@ -66,3 +75,20 @@ status: draft  # draft → validated → outdated
 ---
 ```
 **文件名示例**：`pfit-2026-05-03-药企科普合规路径.md`
+
+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"pfit","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
--- a/commands/pos.md
+++ b/commands/pos.md
@@ -3,7 +3,16 @@
 ## 命令定位
 明确产品在市场中的独特位置、核心价值主张、以及与竞品的差异点。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（pos）的历史记录：
@@ -61,3 +70,20 @@ status: draft  # draft → validated → outdated
 ---
 ```

+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"pos","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
+
--- a/commands/prd.md
+++ b/commands/prd.md
@@ -4,7 +4,16 @@
 从业务视角写一份可执行的 PRD，聚焦业务逻辑流、角色分工、
 数据流转，明确 MVP 的精确边界和功能优先级。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（prd）或相关（pfit/pos）的历史记录：
@@ -69,3 +78,20 @@ tags: ["关键词1", "关键词2"]
 status: draft  # draft → validated → outdated
 ---
 ```
+
+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"prd","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
--- a/commands/uj.md
+++ b/commands/uj.md
@@ -4,7 +4,16 @@
 还原用户从「第一次听说」到「成为忠实用户」到「可能流失」的完整
 行为路径，标注每个节点的情绪曲线、决策障碍和流失原因。

-## 第 0 步：回溯历史
+## 第 0 步：加载项目状态
+
+执行本指令前，先读取项目根目录下的 `.yxstack/_state.md`（如果项目 CODEBUDDY.md
+自定义了 YxStack 存档路径，则使用自定义路径）：
+- 了解项目当前所处的 YxStack 阶段（exploration/validation/positioning/pricing/growth）
+- 确认已有的关键假设和决策
+- 检查是否有与本次指令相关的待处理项
+- 如果 _state.md 不存在，说明这是项目首次使用 YxStack
+
+然后按原有规则检查历史记录：

 执行本指令前，先检查当前项目根目录下的 `.yxstack/` 目录（如果项目 CODEBUDDY.md
 自定义了 YxStack 存档路径，则使用自定义路径），查找近期同指令（uj）的历史记录：
@@ -61,3 +70,20 @@ tags: ["关键词1", "关键词2"]
 status: draft  # draft → validated → outdated
 ---
 ```
+
+## 更新项目状态
+
+### 追加事件日志
+向 `.yxstack/_timeline.jsonl` 追加一行：
+```json
+{"skill":"uj","event":"completed","ts":"当前时间","phase":"当前阶段","summary":"本次产出核心结论","assumption":"本次新增假设（有则填，无则留空）","decision":"本次关键决策（有则填，无则留空）"}
+```
+
+### 更新状态快照
+更新 `.yxstack/_state.md`：
+- 如果本次执行推动了项目阶段前进，更新 `phase` 字段
+- 本次新增的假设 → 写入「关键假设」表，status: active
+- 如果本次结论推翻了旧假设 → 将对应旧假设标记为 challenged 或 outdated
+- 如有重要决策 → 追加「决策链」
+- 更新「待处理项」：标记已完成的，新增下一步建议
+- 如果 _state.md 不存在，按模板创建（参考 templates/state_template.md）
--- a/install.sh
+++ b/install.sh
@@ -50,6 +50,17 @@ cd ~/.codebuddy/yxstack && \

 如果检测到新版本，提示用户：「YxStack 有新版本 vX.Y.Z，是否升级？」用户确认后执行 \`bash ~/.codebuddy/yxstack/install.sh\`。

+### 会话状态恢复
+
+每次会话开始时，自动执行以下流程：
+1. 查找当前项目是否存在 `.yxstack/_state.md`
+2. 如果存在，读取并给出「上次到这里了：当前在 {phase} 阶段，上次执行了 {last_command}」的 2 句欢迎摘要
+3. 如果「待处理项」中有明确的下一步指令，主动建议执行
+4. 如果 `_state.md` 不存在，跳过，正常开始会话
+
+项目状态文件 `.yxstack/_state.md` 和事件日志 `_timeline.jsonl` 由 YxStack 指令自动维护，
+参考模板见 `~/.codebuddy/yxstack/templates/state_template.md`。
+
 开源仓库：http://82.157.208.197:3000/qiukai/yxstack-skill
 维护方：筑基阁（开阳星）
 '
--- a/templates/state_template.md
+++ b/templates/state_template.md
@@ -0,0 +1,76 @@
+# YxStack 项目状态模板
+
+## _timeline.jsonl
+
+追加格式，每行一条指令执行记录：
+
+```json
+{"skill":"pfit","event":"completed","ts":"2026-05-03T10:02:22+08:00","phase":"exploration","summary":"XX痛点验证通过，Go","assumption":"用户对XX的需求是刚需","decision":""}
+```
+
+字段说明：
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `skill` | 是 | 指令名: pfit/pos/uj/prd/money/gtm/metric/comp |
+| `event` | 是 | `completed` |
+| `ts` | 是 | ISO 8601 时间戳，带时区 |
+| `phase` | 否 | 当前阶段: exploration/validation/positioning/pricing/growth |
+| `summary` | 否 | 本次产出的核心结论（一句话） |
+| `assumption` | 否 | 本次新增的关键假设 |
+| `decision` | 否 | 本次做出的关键决策 |
+
+特点：
+- 只追加不修改 — 不会因写入中断损坏历史
+- 可重建 — _state.md 丢失时从 timeline 重新推导
+- 零依赖 — `echo '{...}' >> file` 即可
+
+## _state.md
+
+从 timeline 推导的当前项目状态快照。首次使用时创建，每次指令执行完更新。
+
+```yaml
+---
+project: "{项目名称}"
+phase: "{当前阶段}"
+last_session: "2026-05-03"
+last_command: "pfit"
+---
+
+## 当前阶段
+{一句话描述当前在 YxStack 流程的哪个位置}
+
+## 关键假设
+| 假设 | 状态 | 来源指令 | 提出时间 |
+|------|------|----------|----------|
+| {假设内容} | active/challenged/outdated | /xxx | YYYY-MM-DD |
+
+## 决策链
+1. YYYY-MM-DD /xxx: {决策内容} — {理由}
+
+## 待处理项
+- [ ] {事项}
+```
+
+### 更新规则
+
+指令执行完后，更新 _state.md：
+
+| 字段 | 何时更新 |
+|------|----------|
+| `phase` | 本次指令推动了阶段前进时更新 |
+| `last_session` | 每次更新为当天 |
+| `last_command` | 每次更新为本次指令 |
+| `关键假设` | 新增假设（active）、推翻旧假设（challenged/outdated） |
+| `决策链` | 有重要决策时追加 |
+| `待处理项` | 标记完成 + 新增下一步 |
+
+### 阶段流转建议
+
+```
+exploration → validation → positioning → pricing → growth
+   (pfit)       (uj)          (pos)     (money)    (gtm/metric)
+                                   ↘    (comp)
+```
+
+不强制线性，但提供参考。阶段变化是状态更新的核心信号。