draftgo-cli 4.0.23 → 4.0.24

package/resources/skill/story/SKILL.md

@@ -1,265 +1,265 @@
----
-name: draftgo-story
-description: "Use this skill to build, load, evolve, or conflict-check the project's Story file (.draftgo/story.yaml). Use it when the user requests product-story work, when an existing Story conflicts with a requested product decision, or when preserving a durable product decision is valuable."
----
-
-# DraftGo Story System
-
-> Story 记录产品身份、设计总述、长期决策和当前方向。项目已有 Story 且请求触及定位或既有决策时加载；用户要求或形成需要长期保留的产品决策时创建或更新。
-
----
-
-## 核心原则
-
-| 原则 | 含义 |
-|------|------|
-| Decision record | 记录会影响后续取舍的产品定位与决策 |
-| AI 维护，人确认 | 开发者只聊天，AI 负责提炼和写入 |
-| 三层结构 | 身份(稳) → 决策(只增) → 当前(频变) |
-| 决策日志最值钱 | 取舍依据是代码永远表达不了的信息 |
-| 工具无关 | 使用可移植的 YAML 文件 |
-
----
-
-## 文件位置与结构
-
-**路径：** `.draftgo/story.yaml`（项目根，进 git）
-
-```yaml
-# .draftgo/story.yaml
-meta:
-  version: 1
-  created: YYYY-MM-DD
-  last_touched: YYYY-MM-DD
-  maturity: seed   # seed | growing | stable
-
-# === 第一层：身份（极少变动）===
-identity:
-  what: "一句话讲清这是什么，不超过 30 字"
-  why: |
-    解决什么具体痛点，给谁用。
-    用两三句具体描述说明使用者和场景。
-  not:
-    - "不是 XX"
-    - "不变成 YY"
-
-# === 第二层：设计总述（随功能演进更新）===
-design:
-  overview: |
-    用一段话描述系统的核心流转逻辑。
-    用户从哪进来 → 经过什么 → 得到什么价值。
-    管理侧怎么运作。
-  modules:
-    - name: "模块名"
-      role: "这个模块在系统里的定位（核心/辅助/基座），一句话"
-
-# === 第三层：决策日志（只增不删）===
-decisions:
-  - id: D001
-    date: YYYY-MM-DD
-    chose: "选了什么"
-    over: "拒绝了什么"
-    because: "原因（短，能解释取舍依据）"
-    status: active   # active | superseded
-    # superseded_by: D00X  # 被覆盖时填
-
-# === 第四层：当前方向（频繁更新）===
-now:
-  focus: "当前阶段在做什么"
-  next: "下一步的大致方向"
-  open_questions:
-    - "还没想清楚的事"
-```
-
----
-
-## 触发协议
-
-```
-需要 Story 时：
-
-1. 静默检查 .draftgo/story.yaml
-2. 分流：
-   ├─ 不存在            → 用户要求创建或需要沉淀关键决策时，进入「构建流程」
-   ├─ maturity = seed   → 加载并把不确定项作为后续判断背景
-   └─ growing / stable  → 静默加载，直接开始
-3. 整个对话期间，Story 作为最高优先级上下文锚定
-```
-
----
-
-## 构建流程
-
-### 路径选择（先判断再走）
-
-```
-通过 MCP 实时摘要和项目内可保留的决策记录判断走哪条路径：
-
-├─ MCP 显示存在用户自建内容（非 tag="系统" 的页面、db_meta、custom_scripts）→ 路径 A
-├─ 用户提供了设计文档（PRD、原型图描述、需求文档等）→ 路径 A（以文档为分析素材）
-└─ 只有内置系统页面，无用户自建内容，无设计文档 → 路径 B（对话采集）
-```
-
-### 路径 A：已有系统或已有设计文档
-
-```
-输出：[ Story 文件生成中...正在分析项目 ]
-
-1. 查询项目结构（以及读取用户提供的设计文档，如有）：
-   - MCP project_overview/resource_list → 资源总览
-   - MCP resource_search/get_metadata → 页面与导航元数据（跳过 tag="系统" 的内置页）
-   - MCP api_search/api_describe/api_call → db_meta 与自定义服务结构
-   - 只有必须分析完整 pages/nav/docs 正文时才 checkout；不要要求 MCP 返回全文
+---
+name: draftgo-story
+description: "Use this skill to build, load, evolve, or conflict-check the project's Story file (.draftgo/story.yaml). Use it when the user requests product-story work, when an existing Story conflicts with a requested product decision, or when preserving a durable product decision is valuable."
+---
+
+# DraftGo Story System
+
+> Story 记录产品身份、设计总述、长期决策和当前方向。项目已有 Story 且请求触及定位或既有决策时加载；用户要求或形成需要长期保留的产品决策时创建或更新。
+
+---
+
+## 核心原则
+
+| 原则 | 含义 |
+|------|------|
+| Decision record | 记录会影响后续取舍的产品定位与决策 |
+| AI 维护，人确认 | 开发者只聊天，AI 负责提炼和写入 |
+| 三层结构 | 身份(稳) → 决策(只增) → 当前(频变) |
+| 决策日志最值钱 | 取舍依据是代码永远表达不了的信息 |
+| 工具无关 | 使用可移植的 YAML 文件 |
+
+---
+
+## 文件位置与结构
+
+**路径：** `.draftgo/story.yaml`（项目根，进 git）
+
+```yaml
+# .draftgo/story.yaml
+meta:
+  version: 1
+  created: YYYY-MM-DD
+  last_touched: YYYY-MM-DD
+  maturity: seed   # seed | growing | stable
+
+# === 第一层：身份（极少变动）===
+identity:
+  what: "一句话讲清这是什么，不超过 30 字"
+  why: |
+    解决什么具体痛点，给谁用。
+    用两三句具体描述说明使用者和场景。
+  not:
+    - "不是 XX"
+    - "不变成 YY"
+
+# === 第二层：设计总述（随功能演进更新）===
+design:
+  overview: |
+    用一段话描述系统的核心流转逻辑。
+    用户从哪进来 → 经过什么 → 得到什么价值。
+    管理侧怎么运作。
+  modules:
+    - name: "模块名"
+      role: "这个模块在系统里的定位（核心/辅助/基座），一句话"
+
+# === 第三层：决策日志（只增不删）===
+decisions:
+  - id: D001
+    date: YYYY-MM-DD
+    chose: "选了什么"
+    over: "拒绝了什么"
+    because: "原因（短，能解释取舍依据）"
+    status: active   # active | superseded
+    # superseded_by: D00X  # 被覆盖时填
+
+# === 第四层：当前方向（频繁更新）===
+now:
+  focus: "当前阶段在做什么"
+  next: "下一步的大致方向"
+  open_questions:
+    - "还没想清楚的事"
+```
+
+---
+
+## 触发协议
+
+```
+需要 Story 时：
+
+1. 静默检查 .draftgo/story.yaml
+2. 分流：
+   ├─ 不存在            → 用户要求创建或需要沉淀关键决策时，进入「构建流程」
+   ├─ maturity = seed   → 加载并把不确定项作为后续判断背景
+   └─ growing / stable  → 静默加载，直接开始
+3. 整个对话期间，Story 作为最高优先级上下文锚定
+```
+
+---
+
+## 构建流程
+
+### 路径选择（先判断再走）
+
+```
+通过 MCP 实时摘要和项目内可保留的决策记录判断走哪条路径：
+
+├─ MCP 显示存在用户自建内容（非 tag="系统" 的页面、db_meta、custom_scripts）→ 路径 A
+├─ 用户提供了设计文档（PRD、原型图描述、需求文档等）→ 路径 A（以文档为分析素材）
+└─ 只有内置系统页面，无用户自建内容，无设计文档 → 路径 B（对话采集）
+```
+
+### 路径 A：已有系统或已有设计文档
+
+```
+输出：[ Story 文件生成中...正在分析项目 ]
+
+1. 查询项目结构（以及读取用户提供的设计文档，如有）：
+   - MCP project_overview/resource_list → 资源总览
+   - MCP resource_search/get_metadata → 页面与导航元数据（跳过 tag="系统" 的内置页）
+   - MCP api_search/api_describe/api_call → db_meta 与自定义服务结构
+   - 只有必须分析完整 pages/nav/docs 正文时才 checkout；不要要求 MCP 返回全文
    - .draftgo/worklog.md → 工作进度与完成记录
-   - .draftgo/lessons/ → 开发经验记录
-   - 用户提供的设计文档（PRD / 原型说明 / 需求文档）→ 提取产品意图
-
-2. 从已有数据推断系统画像，生成推断版 Story（含 design.overview 和 modules）
-
-3. 向开发者复述（带 ❓ 标记不确定项）：
-   "我看下来这个系统是【X】，给【Y】用，主要解决【Z】。对吗？"
-
-4. 关键确认（最多 3-5 个问题，追问必带推测）：
-   - 身份是否准确
-   - 有没有重要的"不做什么"我漏了
-   - 核心流转和模块定位是否准确
-   - 当前最关心的方向是什么
-
-5. 落盘 .draftgo/story.yaml (maturity: growing)
-
-6. 回到开发者最初的请求
-```
-
-### 路径 B：全新系统（只有 DraftGo 脚手架和内置系统页面，无用户自建内容）
-
-```
-输出：[ 检测到全新项目，先聊一下你想做什么 ]
-
-通过简短对话采集，信息足够后即进入提炼：
-
-Q1: 这个系统的整体定位和存在理由是什么？
-Q2: 谁会用它？什么场景下用？
-Q3: 类似的东西可能有哪些？你想做出什么不同？
-Q4: 大致有哪些模块/功能块？它们之间怎么串起来？
-Q5: 第一版能用，最少要包含什么？
-
-→ 提炼 → 复述确认 → 落盘 (maturity: seed) → 开始开发
-```
-
-**克制原则**：问到够用就停，开发者回答很简短时不追问细节。
-
----
-
-## 加载策略
-
-每次新对话开头，AI 内部执行：
-
-```
-1. 读取 .draftgo/story.yaml 全文 → 作为最高优先级上下文
-2. 解析 design → 理解系统核心流转和模块定位
-3. 解析 decisions（status: active）→ 提取产品取舍依据
-4. 解析 identity.not → 建立硬边界
-5. 解析 now → 知道当前重点
-6. open_questions → 适时主动追问
-```
-
----
-
-## 冲突检测
-
-**触发条件：**
-- 请求触碰 `identity.not` 边界
-- 请求方向偏离 `now.focus` 过远
-- 请求与某个 active 状态的 decision 取舍相反
-
-**AI 行为：不直接拒绝，也不默默服从，明确摊牌。**
-
-示例输出格式：
-
-```
-这个请求和 Story 有冲突：
-
-  identity.not: "不是给业务运营人员用的低代码平台"
-  D001: "做后台脚手架" over "做完整 SaaS 框架"
-
-你想怎么处理：
-
-A) 想法变了 → 我更新 Story（旧决策标 superseded，新增决策记录转向原因）
-B) 双轨并行 → 扩展受众，保留原有定位
-C) 只是特例 → 这次按新方向做，Story 不动
-```
-
-用户选 A 时：把相关 decisions 标记 `status: superseded` + `superseded_by: D00X`，更新 identity，新增决策条目记录这次转向。
-
----
-
-## 主动沉淀
-
-AI 在开发过程中检测到"方向性决策"时，主动提议沉淀：
-
-**触发条件：**
-- 开发者明确拒绝了某个建议（"不要这样做"）
-- 开发者在两个方案中做了选择
-- 开发者表达了对系统定位、功能边界或文案语气的偏好
-
-**AI 行为：**
-
-```
-刚才你选了 X 而不是 Y，看起来是因为【...】。
-要记到 Story decisions 里吗？以后我做类似判断会用这个原则。
-
-→ [是] / [否] / [改改措辞]
-```
-
----
-
-## now 的更新
-
-每次对话结束时（或里程碑达成），AI 可以提议：
-
-```
-今天我们做了 X、Y、Z。要更新 story.yaml 的 now 部分吗？
-当前是【...】，看起来可以改成【...】
-```
-
-开发者确认后更新 `now.focus` / `now.next` / `now.open_questions`，同时更新 `meta.last_touched`。
-
----
-
-## 维护规则
-
-| 字段 | 更新频率 | 规则 |
-|------|---------|------|
-| `identity.*` | 极少 | 仅重大方向转向时（冲突检测中确认） |
-| `design.overview` | 里程碑级 | 核心流转发生结构性变化时更新 |
-| `design.modules` | 新增模块时 | 只增/改，不删已有模块（模块下线标注即可） |
-| `decisions` | 只增不删 | supersede 时不删旧的只标记 |
-| `now.focus` | 周/里程碑 | 对话结束时 AI 提议更新 |
-| `now.next` | 周 | 同上 |
-| `now.open_questions` | 随时 | 出现新的悬而未决事项 |
-| `meta.last_touched` | 每次更新 | 自动 |
-| `meta.maturity` | 手动 | seed→growing: 首次确认后; growing→stable: 决策≥5条且identity不再变 |
-
----
-
-## 操作流程汇总
-
-### 构建 Story
-
-1. 检查 `.draftgo/story.yaml` 是否存在
-2. 不存在 → 根据 MCP project_overview/resource_list 和用户提供的设计材料判断路径 A 还是 B
-3. 走对应构建流程
-4. 落盘 → 回到用户原始请求
-
-### 更新 Story（冲突 / 沉淀 / now 更新）
-
-1. Read `.draftgo/story.yaml`
-2. 修改对应字段
-3. 更新 `meta.last_touched`
-4. Write 回去
-
-### 加载 Story（每次对话）
-
-1. Read `.draftgo/story.yaml`
-2. 作为上下文锚定，不输出给用户（静默）
-3. 如果 `maturity: seed`，提示"Story 还在早期，开发中会持续补充"
+   - .draftgo/lessons/ → 开发经验记录
+   - 用户提供的设计文档（PRD / 原型说明 / 需求文档）→ 提取产品意图
+
+2. 从已有数据推断系统画像，生成推断版 Story（含 design.overview 和 modules）
+
+3. 向开发者复述（带 ❓ 标记不确定项）：
+   "我看下来这个系统是【X】，给【Y】用，主要解决【Z】。对吗？"
+
+4. 关键确认（最多 3-5 个问题，追问必带推测）：
+   - 身份是否准确
+   - 有没有重要的"不做什么"我漏了
+   - 核心流转和模块定位是否准确
+   - 当前最关心的方向是什么
+
+5. 落盘 .draftgo/story.yaml (maturity: growing)
+
+6. 回到开发者最初的请求
+```
+
+### 路径 B：全新系统（只有 DraftGo 脚手架和内置系统页面，无用户自建内容）
+
+```
+输出：[ 检测到全新项目，先聊一下你想做什么 ]
+
+通过简短对话采集，信息足够后即进入提炼：
+
+Q1: 这个系统的整体定位和存在理由是什么？
+Q2: 谁会用它？什么场景下用？
+Q3: 类似的东西可能有哪些？你想做出什么不同？
+Q4: 大致有哪些模块/功能块？它们之间怎么串起来？
+Q5: 第一版能用，最少要包含什么？
+
+→ 提炼 → 复述确认 → 落盘 (maturity: seed) → 开始开发
+```
+
+**克制原则**：问到够用就停，开发者回答很简短时不追问细节。
+
+---
+
+## 加载策略
+
+每次新对话开头，AI 内部执行：
+
+```
+1. 读取 .draftgo/story.yaml 全文 → 作为最高优先级上下文
+2. 解析 design → 理解系统核心流转和模块定位
+3. 解析 decisions（status: active）→ 提取产品取舍依据
+4. 解析 identity.not → 建立硬边界
+5. 解析 now → 知道当前重点
+6. open_questions → 适时主动追问
+```
+
+---
+
+## 冲突检测
+
+**触发条件：**
+- 请求触碰 `identity.not` 边界
+- 请求方向偏离 `now.focus` 过远
+- 请求与某个 active 状态的 decision 取舍相反
+
+**AI 行为：不直接拒绝，也不默默服从，明确摊牌。**
+
+示例输出格式：
+
+```
+这个请求和 Story 有冲突：
+
+  identity.not: "不是给业务运营人员用的低代码平台"
+  D001: "做后台脚手架" over "做完整 SaaS 框架"
+
+你想怎么处理：
+
+A) 想法变了 → 我更新 Story（旧决策标 superseded，新增决策记录转向原因）
+B) 双轨并行 → 扩展受众，保留原有定位
+C) 只是特例 → 这次按新方向做，Story 不动
+```
+
+用户选 A 时：把相关 decisions 标记 `status: superseded` + `superseded_by: D00X`，更新 identity，新增决策条目记录这次转向。
+
+---
+
+## 主动沉淀
+
+AI 在开发过程中检测到"方向性决策"时，主动提议沉淀：
+
+**触发条件：**
+- 开发者明确拒绝了某个建议（"不要这样做"）
+- 开发者在两个方案中做了选择
+- 开发者表达了对系统定位、功能边界或文案语气的偏好
+
+**AI 行为：**
+
+```
+刚才你选了 X 而不是 Y，看起来是因为【...】。
+要记到 Story decisions 里吗？以后我做类似判断会用这个原则。
+
+→ [是] / [否] / [改改措辞]
+```
+
+---
+
+## now 的更新
+
+每次对话结束时（或里程碑达成），AI 可以提议：
+
+```
+今天我们做了 X、Y、Z。要更新 story.yaml 的 now 部分吗？
+当前是【...】，看起来可以改成【...】
+```
+
+开发者确认后更新 `now.focus` / `now.next` / `now.open_questions`，同时更新 `meta.last_touched`。
+
+---
+
+## 维护规则
+
+| 字段 | 更新频率 | 规则 |
+|------|---------|------|
+| `identity.*` | 极少 | 仅重大方向转向时（冲突检测中确认） |
+| `design.overview` | 里程碑级 | 核心流转发生结构性变化时更新 |
+| `design.modules` | 新增模块时 | 只增/改，不删已有模块（模块下线标注即可） |
+| `decisions` | 只增不删 | supersede 时不删旧的只标记 |
+| `now.focus` | 周/里程碑 | 对话结束时 AI 提议更新 |
+| `now.next` | 周 | 同上 |
+| `now.open_questions` | 随时 | 出现新的悬而未决事项 |
+| `meta.last_touched` | 每次更新 | 自动 |
+| `meta.maturity` | 手动 | seed→growing: 首次确认后; growing→stable: 决策≥5条且identity不再变 |
+
+---
+
+## 操作流程汇总
+
+### 构建 Story
+
+1. 检查 `.draftgo/story.yaml` 是否存在
+2. 不存在 → 根据 MCP project_overview/resource_list 和用户提供的设计材料判断路径 A 还是 B
+3. 走对应构建流程
+4. 落盘 → 回到用户原始请求
+
+### 更新 Story（冲突 / 沉淀 / now 更新）
+
+1. Read `.draftgo/story.yaml`
+2. 修改对应字段
+3. 更新 `meta.last_touched`
+4. Write 回去
+
+### 加载 Story（每次对话）
+
+1. Read `.draftgo/story.yaml`
+2. 作为上下文锚定，不输出给用户（静默）
+3. 如果 `maturity: seed`，提示"Story 还在早期，开发中会持续补充"