# Plan Report

> 帮助梳理一份"框架计划报告"(项目 v1.0 计划、版本路线、阶段方案等)。通过"摸现实 → 定文档类型 → 搭骨架 → 填内容 → 统一结构 → 语言精修 → 自检" 7 步引导,产出"讲为什么做 / 做到什么程度算完 / 分几步走"的框架计划,而不是功能清单或技术方案。当用户说"写计划报告"、"项目计划"、"框架计划"、"v1.0 计划"、"版本路线"、"阶段方案"、"plan-report"、"/plan-report"时触发。

- **Type:** Skill
- **Install:** `agentstack add skill-yunshu0909-yunshu-skillshub-plan-report`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yunshu0909](https://agentstack.voostack.com/s/yunshu0909)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yunshu0909](https://github.com/yunshu0909)
- **Source:** https://github.com/yunshu0909/yunshu_skillshub/tree/master/plan-report

## Install

```sh
agentstack add skill-yunshu0909-yunshu-skillshub-plan-report
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 框架计划报告助手

## 功能说明

帮助用户产出一份**框架计划报告**——位于"项目章程"和"详细设计"之间的文档类型。

它回答:**为什么做 / 做到什么程度算完 / 谁用它 / 不做什么 / 分几步走 / 每步停下时业务能问出什么**。

它**不回答**:字段、接口、技术栈、目录命名、cron 表达式——这些是后续"详细设计文档"的事。

核心价值:**让计划报告变成读者能看懂的故事,而不是作者给自己确认范围的工作清单**。通过 7 步引导跟用户对齐方向、骨架、内容,最后才落盘。

---

## 核心原则

### 1. 先实证再设计

不要凭空推演。先把现状摸清楚——能跑的先跑、能读的代码先读、已知约束先列。

**信号**:能回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费这份文档"。这四个问题答不上来,就不要进 Stage 2。

### 2. 文档类型决定一切

拿到诉求第一件事**不是动笔,是问自己:这是哪一类文档?**

| 类型 | 核心问题 | 写法特征 |
|---|---|---|
| 项目章程 | 为什么立项 | 偏战略,1-2 页 |
| **框架计划**(本 skill) | 为什么做 / 分几步 | 不掺字段,讲到阶段验收为止 |
| 业务说明 | 对外提供什么能力 | 功能视角,容易越列越多 |
| 详细设计 | 怎么实现 | 字段 / 接口 / 技术栈齐备 |
| PRD | 用户故事 / 验收 | 用户视角,需求场景化 |

**错配的代价**:把框架计划当业务说明写 → 变功能清单;当详细设计写 → 陷入字段细节。**类型错位让所有后续努力打折扣**。

### 3. 状态描述 > 动作描述

总体目标和验收都用"能 X"句式——"数据能稳定进来"、"客户名单可用"、"失败能被发现"。

**为什么**:状态描述本身就是验收标准;动作描述只是过程语言。"数据能稳定进来"明确了 done 的定义,"采集数据"只描述工作量。

### 4. 拆版本,不堆功能

每个版本只解决一个主问题。不要列"X / Y / Z 一堆功能"——看起来完整,实际无法推进,容易变无底洞。

**反例**:"v1.0 包含 Metabase / Grafana / SQLite / API / 告警 / 备份 / 模型归并 / 客户名单"
**正例**:"v0.1 底座能跑 / v0.2 业务主口径进来 / v0.3 监控视角补齐 / v0.4 上层业务能用"

### 5. 用验收反推交付

每个阶段**先问"怎样算这个阶段完成"**,再从验收倒推该交付什么。不要先问"要做哪些模块"。

验收最好用"系统已经可以回答 X / Y / Z"的句式——把技术验收和业务价值天然连起来。

### 6. 不做项必须配理由

"不做"不能只列出来。每条都要配"为什么不放进这个版本"。

**为什么**:防 scope creep 的关键武器。业务方质疑"为什么不做 X"时,可以直接指到这一行的理由——否则会反复重开讨论。

### 7. 始终为读者服务

整篇文档的隐含问题是:

> 一个**完全没接触过这个项目**的人,读完,能不能理解项目为什么成立、做到什么程度算完、是否对他有用?

**禁止**:在框架计划里写"为我们自己确认范围"的内容——目录骨架、技术栈选型、字段细节、并发模型,这些都是详细设计阶段的事。

---

## 工作流程

### Stage 1: 摸现实

**目标**:在动笔前把现状摸清楚,让后面所有设计判断都能指回事实。

---

#### Step 0: 规模快筛(进 Stage 1 前先做,防止小项目误用)

进 Stage 1 之前**先问两个判断题**,如果两个回答都触发"小",**直接退出 skill,不要继续**——这场景不该用 plan-report:

1. **预计耗时**:  6 周?
2. **能拆出几个独立交付的阶段**: 1 个 / 2-3 个 / 4+ 个?

**退出规则**:
- 预计  6 周 / 拆出 4+ 阶段 → 用**标准骨架**(10 节)

不做规模快筛 → AI 会用标准骨架硬套小项目,造成过度结构化。**这一步是这次 skill 改进的硬约束,不能跳**。

---

#### Step 1: 收集以下信息(已知填上,不知道标记待补)

1. **项目背景**:项目名称、当前阶段(立项 / 在做 / 改造) / 是否有上层架构基线
2. **现状**:已有代码 / 已有系统能跑成什么样 / 能拿到什么数据 / 输出形态是什么
3. **目标消费方**:这份计划是给谁看的 / 谁会基于它做事
4. **硬约束**:技术约束(API 限流、数据窗口、存储上限)、业务约束(规模、节奏、预算)、组织约束(谁负责、何时上线)

**追问模板**:
- "现在能跑通的部分是什么?能跑一下让我看到真实输出吗?"
- "有没有上层文档(架构基线、立项书、调研报告)我应该先读?"
- "这份计划是给谁看的——内部产研 / 跨团队 / 客户?"
- "有没有已知的硬约束?比如 API 限流、上线 deadline、客户量上限?"

---

#### Step 2: 硬门 + 信息深度自检

**硬门**:
- 不要进 Stage 2,除非你能用 3 行话回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费"
- 凭空设计是这个 skill 最容易踩的坑——**没摸现实就动笔 = 后面所有判断没根**

**信息深度自检**(防止 Stage 1 被空泛回答糊弄过去):
- 现状回答里**必须有具体数字 / 系统名 / 数据规模**(比如"50+ 业务线"、"12 个 bash 脚本"、"2000 万客户"),只有形容词("挺多的"、"不少")不算过门
- 硬约束回答里**必须有具体数值 / 时限 / 接口限制**(比如"飞书 API 100 QPS"、"Hive 查询 10-30 秒"),"听说有限制"不算过门
- 如果回答都是空泛形容词,**返回追问模板逐项问透**,不要硬过门

**立项前期的灰度通道**:如果项目处于真早期立项阶段,用户确实**还没有精确数字**,可以用 "**量级估算 + 1-2 个具体痛点场景**" 代替精确数字(例如"几十个业务线" + "上次某团队配错告警 3 个月才被发现")。但仅限立项早期——**已经在做的项目必须给具体数字**。

---

#### Step 3: 信息不全时的"卡住产出格式"

如果硬门没过(信息不足以进 Stage 2),**不要硬产出 plan**。这时正确的产出是**"卡住状态说明"**,固定格式如下:

```markdown
# {项目名} v1.0 计划 — Stage 1 卡住,待补信息

## 已收集信息

- 项目背景: {已知部分 / 待补}
- 现状: {已知部分 / 待补}
- 目标消费方: {已知部分 / 待补}
- 硬约束: {已知部分 / 待补}

## 还需要从用户追问的 X 个具体问题

1. {具体问题 1,例如"现在文档散在哪些系统里?多少篇?"}
2. {具体问题 2,例如"使用人数 30 / 300 / 3000?"}
3. {具体问题 3,例如"最近一次'用起来不爽'的具体场景是什么?"}
...

## 进 Stage 2 的最低标准

收到上面问题的回答后,要保证能用 3 行话回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费"。
```

**禁止**:用"据我理解你大概想做 X" / "我假设你的现状是 Y" 开头硬补。这是凭空补全的伪装,等价于 Stage 1 闯关。

---

### Stage 2: 定文档类型

**目标**:确认要写的是"框架计划",而不是别的类型;如果是别的类型,提示用户换 skill。

**操作要点**:

跟用户对齐这份文档的定位:
- 它**回答**:为什么做 / 做到什么程度算完 / 谁用 / 不做什么 / 分几步 / 每步验收
- 它**不回答**:字段、接口、技术栈、目录、cron 表达式、并发模型

如果用户说"我要把字段都写清楚"——这是详细设计,本 skill 不适用,建议另起一份。

如果用户说"我要列我们能提供的功能"——这是业务说明,本 skill 不适用,建议另起一份。

**追问模板**:
- "这份文档主要给谁看?给做事的人 → 偏详细设计;给理解事的人 → 框架计划"
- "你期望它解决什么问题?——'让团队对齐做什么 / 怎么算完'是框架计划;'让业务方知道能用什么'是业务说明"

**硬门**:
- 文档类型没明确前,不要搭骨架
- 错位的类型 = 整份文档作废,这一步必须卡住

---

### Stage 3: 搭骨架

**目标**:把框架计划的固定骨架定下来,让用户校验。

**框架计划的固定骨架(5 段)**:

```
定位 → 痛点 → 边界 → 阶段 → 验收
```

**展开成章节(标准版 10 节)**:

```
1. 项目定位          (是什么 / 不是什么)
2. 为什么要做         (核心痛点)
3. 服务/系统边界      (负责 / 不负责)
4. v1.0 总体目标      (做到什么程度算完)
5. 版本路线           (分几步,只一行流程图)
6. v0.1 阶段          (要解决的问题 / 主要交付 / 阶段验收)
7. v0.2 阶段          (同上三段式)
8. v0.3 阶段          (同上三段式)
9. v0.4 阶段          (同上三段式)
10. v1.0 之后再考虑   (后续不做,每条配理由)
11. (可选) 关联文档——如果上层文档全部为空,**整节删除**,不要留"待补"占位符
```

**项目规模自适应**(关键,避免小项目过度结构化):

| 项目规模 | 阶段数 | 总体目标行数 | 痛点表行数 | 总节数 |
|---|---|---|---|---|
| 小(1 人 3 月 / 多人协作) | 4-5 个 | 5-6 行 | 5-7 行 | 10-11 节 |

**核心纪律**:**按真实情况定行数,不要按模板默认值凑数**。凑出来的内容读者一眼能看出来。

**每个阶段必须用统一三段式**,无论项目规模——这一点不变。

**操作要点**:
- 骨架先**整体抛给用户**,让他增删章节、调整顺序
- **禁止**:边写边改骨架
- **禁止**:用户没确认就开始填内容

**追问模板**:
- "这个骨架对吗?有要加 / 减 / 调顺序的章节吗?"
- "阶段数定几个?——按'每阶段解决一个主问题'反推,通常 3-5 个合适"

**硬门**:骨架没确认 → 不进 Stage 4。

---

### Stage 4: 填每节内容(按 4 原则)

**目标**:逐节填内容,每节都按"内容判断 4 原则"落字。

**4 原则**:

#### 原则 1:先定是什么 / 不是什么

开篇用 "**它的目标不是 X,而是 Z**" 的句式。先排除常见误解,再立正确定位。

**误解数量按场景定**:1-3 个,**宁缺勿凑**。如果想不出第 2 个真实误解,**就不要硬塞**——硬凑的误解读者一眼能看出来。

**对内部工具类项目特别说明**:如果项目是面向内部团队的工具(告警平台、巡检工具、CI 平台等),读者可能不带"以为是 X"的误解——这时**改用对照式**:"它做 X / 不做 Y",而不是强行写"不是 A / 不是 B / 不是 C"。

**为什么**:读者常带错误预期来(以为是"数据平台"、"业务系统"、"分析工具")。先打掉误解,定位才立得住。**但误解不存在就不要造一个**。

#### 原则 2:找痛点,不说"要做 X"

第 2 节"为什么做"用 **"问题 | 影响"表格**——每行是名词性短语 + 一句具体后果。

**行数按真实痛点数,不要凑**:
- 小项目(6 周 / 4+ 阶段)→ 用**标准骨架**(10 节)

---

### 小项目骨架(8-9 节)

适用:1 人 1-6 周 / 工具类 / 单团队内部使用 / 不分多阶段没法独立交付。

````markdown
# {项目名} {版本} 框架计划

> 状态:框架计划版
> 日期:{YYYY-MM-DD}
> 项目规模:小(1 人 X 周 / Y 阶段)

---

## 1. 项目定位

{项目名} 是一个 **{核心定位 1 句话}**。

**它做**:{X 件具体能做的事,3 行内}
**它不做**:{Y 件明确不做的事,2 行内,跟"v1.0 之后"区别开}

> 内部工具类项目:用"它做 / 它不做"对照式,不强求"不是 A / B / C"误解

---

## 2. 为什么要做

| 问题 | 影响 |
|---|---|
| {真实痛点 1} | {具体后果} |
| {真实痛点 2} | {具体后果} |
| {真实痛点 3} | {具体后果,3-4 行够,不凑数} |

---

## 3. {版本} 总体目标

| 目标 | 说明 |
|---|---|
| {状态 1,"能 X" 句式} | {说明} |
| {状态 2} | {说明} |
| {状态 3,3-4 行够} | {说明} |

---

## 4. 版本路线

```text
v0.1 {阶段口号} → v0.2 {阶段口号} → v0.3 {阶段口号} → {版本} 可用
```

---

## 5. v0.1 {标题}

### 要解决的问题
{...}

### 主要交付
- {...}

### 阶段验收
{用工具型 / 平台型句式,见 Stage 5 三段式备选}

---

## 6. v0.2 {标题}
(同上三段式)

## 7. v0.3 {标题}
(同上三段式)

---

## 8. {版本} 之后再考虑什么

| 后续方向 | 为什么不放进 {版本} |
|---|---|
| {不做项 1} | {理由} |
| {不做项 2} | {理由,2-3 行够} |
````

**小项目骨架的核心约束**(对照标准骨架的差异):
- **没有第 3 节"服务边界"**——融化进第 1 节"它做 / 它不做"
- **没有"关联文档"节**——小项目通常没上层文档
- **总体目标 3-4 行**(不是 6 行)
- **痛点 3-4 行**(不是 5 行)
- **2-3 个阶段**(不是 4 个)

---

### 标准骨架(10 节)

适用:1 人 >6 周 / 多人协作 / 4+ 阶段 / 跨团队消费 / 有上层架构基线。

````markdown
# {项目名} {版本} 框架计划

> 状态:框架计划版,技术细节留待详细设计阶段
> 日期:{YYYY-MM-DD}
> 上层文档:{架构基线 / 立项书 路径,如有}

---

## 1. 项目定位

{项目名} 是一个 **{核心定位 1 句话}**。

它的目标**不是** {常见误解 1} {/ 误解 2 / 误解 3 — 按真实情况,1-3 个,宁缺勿凑},**而是** {正确定位}。

> **如果是内部工具类项目**且想不出真实误解,改用对照式:"它做 X / 不做 Y",不要硬凑误解。

一句话概括:

```text
{核心动作链路,如:统一采集 → 统一沉淀 → 统一口径 → 统一接口 → 给上层业务使用}
```

---

## 2. 为什么要做

现在 {一句话现状}。这样会带来几个长期问题:

| 问题 | 影响 |
|---|---|
| {痛点 1} | {具体后果 1} |
| {痛点 2} | {具体后果 2} |
| {痛点 3} | {具体后果 3} |
| ... | ... |

> **行数按真实痛点数,不要凑**:小项目 3-4 行 / 中型 4-5 行 / 大型 5-7 行。**3 秒判断法**:这条痛点能不能在生产事故复盘 / 业务方吐槽里被点名?能 → 留;不能 → 删。

{版本} 要解决的是这些基础问题,而不是一次性把所有 {业务/能力} 都做完。

---

## 3. 服务边界

{项目名} 只负责 **{核心职责}**。

```text
{上游 / 输入}
   ↓
{本项目}   ← 当前文档
   ↓
{下游 / 消费方}
```

本项目负责:

- {职责 1}
- {职责 2}
- {职责 3}

本项目不负责:

- {不做 1}
- {不做 2}
- {不做 3}

这些能力属于 {归属方}。

---

## 4. {版本} 总体目标

{版本} 的目标是做出 {状态描述},而不是 {容易被误解的更大目标}。

| 目标 | 说明 |
|---|---|
| {状态 1,"能 X" 句式,如"数据能稳定进来"} | {1 句说明} |
| {状态 2} | {1 句说明} |
| {状态 3} | {1 句说明} |
| ... | ... |

> **行数按真实状态数,不要凑**:小项目 3-4 行 / 中型 4-5 行 / 大型 5-6 行。
> **"老链路可兜底"是 customer-metrics-service 这个示例项目的具体一行(因为有 maas_bot 老链路)——不要把它当成模板必填项。新项目如果没有"老链路",这一行就不要有。**

{版本} 不追求 {显式排除的过度目标},只要 {核心目标} 即可。

---

## 5. 版本路线

{版本} 拆成 N 个内部阶段推进。每个阶段只解决一个主问题。

```text
v0.1 {阶段口号}
  ↓
v0.2 {阶段口号}
  ↓
v0.3 {阶段口号}
  ↓
v0.4 {阶段口号}
  ↓
{版本} 正式可用
```

---

## 6. v0.1 {阶段标题}:{一句话主线}

### 要解决的问题

{为什么需要这个阶段 / 不做会怎样}

### 主要交付

- {交付物 1}
- {交付物 2}
- {交付物 3}

### 阶段验收

{1-2 句状态描述 + "系统已经可以回答 X" 句式}

---

## 7. v0.2 {阶段标题}:{一句话主线}

### 要解决的问题

...

### 主要交付

...

### 阶段验收

这一阶段结束后,系统已经可以回答:

- {业务问句 1}
- {业务问句 2}
- {业务问句 3}

---

## 8. v0.3 ...

...

---

## 9. v0.4 ...

...

---

## 10. {版本} 之后再考虑什么

{版本} 只解决 "{核心目标}"。以下事项不放进 {版本} 主目标:

| 后续方向 | 为什么不放进 {版本} |
|---|---|
| {不做项 1} | {理由 1} |
| {不做项 2} | {理由 2} |
| {不做项 3} | {理由 3} |

{版本} 的核心原则是:

```text
{一句话原则,如"先把数据底座跑稳,再扩展计算和产品能力"}
```

---

## 关联文档

- 上层文档:{路径}
- 项目记忆:{路径}
- 旧代码参照:{路径}
````

**关键约束**:
- 所有阶段(v0.1-v0.4)必须用统一三段式,不要某个阶段加额外小节
- 不出现字段名、表名、接口路径、技术栈、目录路径、cron 表达式
- 不做项必须有"为什么不放进当前版本"列
- 标题朴素,不堆修饰

---

## 示例参考

### 实际案例(customer-metrics-service v1.0)

文件路径:`docs/plan/v1.0-框架-customer-metrics-service.md`

**关键设计决策**:
- 项目定位先用"不是 X / Y / Z,而是 Z"打掉误解——"不是做客户价值评分、ROI 分析或日报页面,而是把分散的数据统一收口"
- 第 4 节总体目标用 **6 行"能 X"句式**——数据能稳定进来 / 能稳定沉淀 / 口径能统一 / 能被程序读取 / 失败能被发现 / 老链路可兜底
- 4 个阶段都用统一三段式,验收都用"系统已经可以回答 X / Y / Z"句式
- 第 10 节不做项用 **"后续方向 | 为什么不放进 v1.0"** 表格,每条配理由
- 最后用一句口号收束:"先把数据底座跑稳,再扩展计算和产品能力"

**AI 写计划报告时常犯的 6 个反模式**(看到自己在写下面任一种,停下重想):

1. **按"输入资源"切版本**(数据源 / 客户类型 / 第三方依赖)→ 应该按**能力层**切(地基 → 业务接入 → 服务对外)。问自己:每个版本能不能独立交付一个"用户能感知的能力"?不能 → 切错了。

2. **把"业务计算 / 上层加工"塞进自己的服务边界** → 应该明确"我只到事实数据层,业务计算归独立模块"。问自己:这个职责被砍掉,我的服务还成立吗?成立就该砍。

3. **按未来最大规模做过度设计**(并发池 / 队列 / 聚合告警 / 多租户)→ 应该按**当前 1.0 真实规模**设计,留接口不实现。问自己:这个复杂度是 v1.0 真需要,还是"假如有 100x 用户"?

4. **把技术细节(目录骨架 / Docker / 技术栈 / cron 表达式 / 字段)写进框架计划** → 应该全部抽走,留到"详细设计文档"。问自己:这一段如果换个技术栈实现,还成立吗?成立 → 它是业务,不是技术,留下;不成立 → 删。

5. **把"框架计划"写成"业务能力清单"**(列"提供 X / Y / Z 功能") → 应该把能力**融化进"总体目标"的状态表**("X 能稳定 / Y 能被读 / Z 能被发现"),不要单独开"提供什么能力"章节。

6. **用"据我理解"开头硬补缺失信息**——这是最隐蔽的反模式。Stage 1 信息不足时,AI 会礼貌地写"据我理解你大概想做 X / 我假设现状是 Y / 你的客户量级应该是 Z"——**这等价于凭空补全**,会让 Stage 2 之后的所有判断悬空。正确反应是按 Stage 1 Step 3 的"卡住产出格式"输出待补问题,**不要硬开篇**。

实际案例里 customer-metrics-service 的 5 次校正:`按数据源切版本 / summary 层塞进底座 / 100 客户过度设计 / 技术细节塞进 plan / 功能清单视角`——是这 6 个反模式中前 5 个的具体表现。

### 抽象案例(虚构:客户标签平台 v1.0)

**场景**:为内部业务团队建一个客户标签管理平台,30 个业务线接入。

**关键设计决策的逻辑**(学逻辑,不抄措辞):

- **定位**:"不是 BI 工具 / 不是 CDP / 不是用户画像系统,而是**客户标签的统一登记和分发服务**"——先打掉 3 个常见误解
- **痛点**(虚构示例):
  - `标签定义散在各业务文档` | `同名标签语义不同,数据对账经常吵架`
  - `标签发布无审计` | `谁改了什么没记录,出问题查不到`
  - `下游消费方式单一` | `只能查 Excel,程序化集成难`
- **总体目标**(状态描述):标签能登记 / 定义能复用 / 变更能追溯 / 数据能被程序读取
- **版本路线**(每阶段一个主问题):
  ```
  v0.1 元数据底座 → v0.2 标签登记上线 → v0.3 审计与变更 → v0.4 分发 API → v1.0 正式可用
  ```
- **v0.2 验收用业务问句**:
  - "某个标签当前的定义是什么?"
  - "哪些业务线用了这个标签?"
  - "这个标签上次什么时候变过?"
- **不做项配理由**:
  - `画像计算 → 属于上层分析服务,不是登记平台职责`
  - `多租户隔离 → 30 业务线规模下不需要,过度设计`
  - `标签生效时间窗口管理 → 复杂度高,留到 v2.0`

**关键陷阱(同 customer-metrics-service 校正经验)**:
- 不要按"数据源"切版本(MySQL / Hive / 外部 API),按能力层切
- 不要在 plan 里写字段、表结构、API 路径
- 不要列"提供查询能力 / 提供登记能力 / 提供审计能力"这种功能清单——融化进"总体目标"的状态表

---

## 使用场景

**场景 1:新项目立项后第一份"做什么"文档**
→ 上层有架构基线 / 立项书,需要把"v1.0 做什么、分几步"摊开。本 skill 主战场。

**场景 2:已有项目的大版本规划**
→ 既有项目要做 v2.0 / v3.0,需要重新对齐"这一版的主问题是什么、跟前版有什么差异"。

**场景 3:多阶段迁移计划**
→ 老系统迁新系统,需要拆"几个阶段、每阶段迁什么、迁完什么算成功"。

**场景 4:内部工具的演进路线**
→ 内部脚本 / 工具想升级为正式服务,需要规划"从工具到服务的几步"。

---

## 不适用场景

### 文档类型不匹配

- **详细设计文档**(字段 / 接口 / 技术栈齐备)→ 另起 `detail-design` 类文档,本 skill 不涉及
- **PRD / 需求文档**(用户故事 / 验收标准)→ 用 `prd-doc-writer`
- **业务说明**(对外列功能清单)→ 业务说明视角不同,本 skill 不适用
- **拜访 / 分享大纲**(给外部听众讲一场)→ 用 `share-outline`
- **周报 / 工作汇总**(已发生事项的整理)→ 用 `weekly-report`
- **客户共识会准备**(多方对齐)→ 用 `meeting`

### 项目规模太小

- **1 周内的脚本改造 / bug 修复 / 小调整**——不需要框架计划,直接写 1 页"做什么 + 怎么验证"即可
- **不需要分阶段的"一次性交付"项目**——没有 v0.1 / v0.2 之分的项目,本 skill 会过度结构化
- **判断标准**:如果你想出来的"阶段"只有 1 个,或者每阶段做的事都互相依赖无法独立交付——说明这项目不需要框架计划

### 多人协作场景的注意事项

本 skill 默认"一个负责人主导写一份计划"。**多人协作场景**下(多个 owner、跨部门、需要先开会对齐):
- Stage 1-3 建议先开 1-2 次小会对齐"现状 / 文档类型 / 骨架",再让一个人主笔
- 不要 3 个人在 Stage 3 骨架上吵几天——硬门是用来卡 AI 跳步骤的,不是用来卡团队讨论的

---

## md → html 转换

本 skill 的 `tools/` 子目录下提供 `md2html.py` 脚本和 `style.css`,用于把产出的 `.md` 转成可视化 `.html`。

```
.claude/skills/plan-report/
├── SKILL.md          ← skill 本身,给 Claude 读
└── tools/
    ├── md2html.py    ← 转换脚本
    └── style.css     ← 输出 HTML 的样式表
```

**安装依赖**(一次性):

```bash
pip3 install markdown
```

**使用**:

```bash
python3 .claude/skills/plan-report/tools/md2html.py docs/plan/v1.0-框架-{项目名}.md
```

输出会在 md 同目录生成同名 `.html`。

样式由 `tools/style.css` 控制,可以按需修改(蓝色 accent / 表格 hover / ASCII 图块等)。脚本会自动找到同目录的 `style.css`,也可以用 `--css` 参数指定其他样式表。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yunshu0909](https://github.com/yunshu0909)
- **Source:** [yunshu0909/yunshu_skillshub](https://github.com/yunshu0909/yunshu_skillshub)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yunshu0909-yunshu-skillshub-plan-report
- Seller: https://agentstack.voostack.com/s/yunshu0909
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.