# Release Announcement

> 发版公告自动生成：从 PRD 飞书文档提取更新内容，生成三个版本的发版公告（简略版、详细中文版、详细英文版），并创建为飞书云文档（用户名下）。当用户需要生成发版公告、版本发布说明、release notes、发版简报时使用。

- **Type:** Skill
- **Install:** `agentstack add skill-cookieshaha-ash-claude-skills-release-announcement`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CookiesHaha](https://agentstack.voostack.com/s/cookieshaha)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CookiesHaha](https://github.com/CookiesHaha)
- **Source:** https://github.com/CookiesHaha/ash-claude-skills/tree/main/plugins/lark-prd-workflow/skills/release-announcement

## Install

```sh
agentstack add skill-cookieshaha-ash-claude-skills-release-announcement
```

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

## About

# 发版公告自动生成工作流

**CRITICAL — 开始前 MUST 用 Read 工具读取以下文件：**

1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — lark-cli 认证与权限处理

---

## 适用场景

- "生成发版公告"
- "从 PRD 生成 release notes"
- "发版简报 / 发版说明"
- "release-announcement {PRD链接} {版本号}"

## 输入

| 参数 | 示例 | 说明 |
|------|------|------|
| **PRD 来源** | 飞书 wiki URL 或 doc_token | PRD 文档地址（必填） |
| **版本号** | `v26.4.1.0` | 发版版本号（必填） |
| **发版日期** | `2026年5月13日` | 可选，默认取当天 |
| **产品名** | `PST` | 可选，默认 `PST` |
| **产品全称** | `海柔售前工具（PST）` | 可选，默认 `海柔售前工具（PST）` |

**输入示例：**

```
/release-announcement
PRD: https://hairobotics.feishu.cn/wiki/G36owOYXNiIDG9k7XlOc6vXlnob
版本号: v26.4.1.0
```

## 前置条件

```bash
# 飞书云文档（user 身份）— 用于读取 PRD 和创建公告文档
lark-cli auth login --domain docs,drive,wiki
```

## 工作流

```
{PRD 来源, 版本号, [发版日期], [产品名]}
        │
        ▼
Step 0  认证检查 ──► 确认 lark-cli user 身份可用
        │
        ▼
Step 1  获取 PRD 内容
        ├─ wiki URL → lark-cli wiki +get-node → doc_token
        ├─ lark-cli docs +fetch --as user --doc-format markdown → PRD 正文
        ▼
Step 2  分析 PRD ──► 提取更新内容
        ├─ 识别功能模块（选型/货架/布局/CAD/检测等）
        ├─ 按模块分组，P0 需求优先
        ├─ 提取核心价值方向（3个）
        ▼
Step 3  生成三版公告
        ├─ 简略版（日期 + 版本号 + 3要点摘要）
        ├─ 详细中文版（价值总览 + 分模块详述）
        ├─ 详细英文版（对应英文翻译）
        ├─ 输出预览，用户确认后进入 Step 4
        ▼
Step 4  创建飞书文档（×3）
        ├─ lark-cli docs +create --as user（关键：用户名下）
        ├─ 记录每个文档的 URL 和 doc_token
        ▼
Step 5  输出结果 + [HANDOFF] 块
```

---

## Step 0：认证检查

确认 lark-cli user 身份可用于读写飞书文档：

```bash
lark-cli auth status
```

若未认证或 scope 不足，按 `lark-shared/SKILL.md` 引导用户完成授权：

```bash
lark-cli auth login --domain docs,drive,wiki
```

## Step 1：获取 PRD 内容

### 1a. 从 wiki URL 解析 doc_token

若用户提供的是飞书 wiki URL（如 `https://hairobotics.feishu.cn/wiki/XXXXX`）：

```bash
lark-cli wiki +get-node --as user --node-token {wiki_token}
```

从返回中提取 `obj_token`（即 doc_token）。

### 1b. 拉取 PRD 正文

```bash
lark-cli docs +fetch --as user \
  --api-version v2 \
  --doc "{doc_token}" \
  --doc-format markdown
```

返回 PRD 的 Markdown 全文。若内容过长，重点关注：
- **§4 需求详细设计** — 各功能模块的详细描述
- **§5 功能清单** — P0 功能条目列表
- **§3 整体说明** — 整体变更概要

## Step 2：分析 PRD 内容

从 PRD 中提取以下信息：

1. **核心价值方向**（3个）— 用于价值总览段落
2. **功能模块分组** — 按产品模块（选型优化、货架计算、布局优化、CAD 导入导出、一键检测等）归类
3. **每个功能点的详细描述** — 从 §4 需求详细设计提取
4. **新增功能标记** — 全新功能标注「新增」
5. **Bug 修复** — 单独归类
6. **进行中的功能** — 标注「正在努力中」

**提取原则：**
- P0 需求全部纳入
- 按用户可感知的功能价值组织，而非按开发任务
- 技术细节转化为用户可理解的功能描述
- 保留关键参数和规则（如消防标准编号、高度阈值、默认值等）

## Step 3：生成三版公告

### 3.1 简略版模板

```
{发版日期} 版本号{版本号}

中文：{产品全称}{月份}版本发布公告 - {解决方案名}
EN：{产品缩写} {年}-{月} {解决方案名} Version Release Notes
【{产品缩写} {月份}版本发布 / {产品缩写} {Month} Release】{版本号}

{月份}{产品缩写}版本聚焦{核心方向概述}：
{核心方向1}：{一句话描述，≤50字}
{核心方向2}：{一句话描述，≤50字}
{核心方向3}：{一句话描述，≤50字}

```

**简略版规则：**
- 日期格式：`YYYY年M月D日`
- 总结不超过 3 条核心要点
- 每条要点 ≤ 50 字，以冒号分隔标题与描述
- 中英文标题都要包含
- 核心要点摘要使用飞书高亮块（``）包裹

### 3.2 详细中文版模板

```
{产品全称}{月份}版本发布公告 - {解决方案名}

价值总览

{月份}{产品缩写}版本聚焦{核心方向概述}，围绕{方向1}、{方向2}、{方向3}三大核心方向持续升级：
{方向1}：{详细描述}
{方向2}：{详细描述}
{方向3}：{详细描述}

更新内容
大家好！{产品全称}{产品缩写}于{发版日期}已发布新版本，针对新版本信息做如下公告说明：
版本号：{版本号}
系统地址：{系统地址}

{模块1标题}
{功能点1标题}
  - {功能点详细描述}
  - {功能点详细描述}
{功能点2标题}
  - {功能点详细描述}

{模块2标题}
...

Bug修复
  - {修复项1}
  - {修复项2}

🚧 正在努力中
{进行中的功能}
  - {描述}
```

**详细中文版规则：**
- 「价值总览」只写 3 个核心方向，每个 1-2 句话
- 「更新内容」按功能模块组织，每个模块下列具体功能点
- 功能点用缩进 bullet list，保留关键参数和数值
- 新增功能在模块标题后标注（新增）
- Bug 修复单独归类
- 末尾固定包含「🚧 正在努力中」段落

### 3.3 详细英文版模板

```
{产品缩写} {年}-{月} {解决方案名} Version Release Notes

Overview
The {Month} {产品缩写} release focuses on {核心方向概述}:
{Direction 1}: {description}
{Direction 2}: {description}
{Direction 3}: {description}

Release Note
Hello everyone! The {产品缩写} released a new version on {release date}, ...
Version Number: {版本号}
System Address: {系统地址}

{Module 1 Title}
{Feature Title}
  - {Feature description}
  - {Feature description}

...

Bug Fixes
  - {fix 1}
  - {fix 2}

🚧 In Progress
{Feature}
  - {description}
```

**详细英文版规则：**
- 结构与中文版完全对应
- 专业术语使用行业标准英文（如 FM-8-34 standard、sprinkler tier）
- 产品专有名词保持一致翻译（在 PRD 中查找已有英文表述）
- 表格化展示效果更好的内容（如阈值规则）用 Markdown 表格

### 用户确认门

**必须输出三版公告预览，等用户确认后才进入 Step 4。不允许跳过这一步直接创建文档。**

```
[CHECKPOINT: release-announcement Step 3 → Step 4]

PRD 来源：{PRD URL}
产品：{产品名}  版本号：{版本号}  发版日期：{日期}

已生成三版公告：
1. 简略版 — {核心要点数}条要点，{字数}字
2. 详细中文版 — {模块数}个功能模块，{功能点数}个功能点
3. 详细英文版 — 与中文版结构对齐

请审阅以上内容，确认后回复「继续」创建飞书文档；需要调整请指出具体位置。
```

## Step 4：创建飞书文档

**CRITICAL：必须使用 `--as user` 确保文档创建在用户名下，而非 bot 名下。**

### 文件命名规范

飞书文件名 ≤ 27 字符：

| 版本 | 命名模板 | 示例 |
|------|---------|------|
| 简略版 | `{产品缩写} {版本号} 发版简报` | `PST v26.4.1.0 发版简报` |
| 详细中文版 | `{产品缩写} {版本号} 发版公告` | `PST v26.4.1.0 发版公告` |
| 详细英文版 | `{产品缩写} {版本号} Release` | `PST v26.4.1.0 Release` |

若版本号较长导致超过 27 字符，缩短为 `{产品缩写} {短版本号} 发版简报`（如 `PST v4.1.0 发版简报`）。

### 创建命令

将公告内容写入临时文件，然后调用 lark-cli 创建：

```bash
# 简略版
lark-cli docs +create --as user \
  --api-version v2 \
  --doc-format markdown \
  --file-name "{简略版文件名}" \
  --content "$(cat /tmp/release_brief.md)"

# 详细中文版
lark-cli docs +create --as user \
  --api-version v2 \
  --doc-format markdown \
  --file-name "{中文版文件名}" \
  --content "$(cat /tmp/release_cn.md)"

# 详细英文版
lark-cli docs +create --as user \
  --api-version v2 \
  --doc-format markdown \
  --file-name "{英文版文件名}" \
  --content "$(cat /tmp/release_en.md)"
```

**注意事项：**
- 内容中的特殊字符需转义（引号、反引号等）
- 若内容过长导致命令行参数超限，先 Write 到临时文件再用 `$(cat ...)` 读取
- 每次创建后记录返回的 `url` 和 `document_id`

## Step 5：输出结果

```
✅ 发版公告已生成

📋 简略版：{简略版飞书URL}
📄 详细中文版：{中文版飞书URL}
📄 详细英文版：{英文版飞书URL}

版本：{版本号}
发版日期：{日期}
PRD 来源：{PRD URL}

[HANDOFF: release-announcement]
- product: {产品名}
- version: {版本号}
- release_date: {发版日期}
- prd_source: {PRD URL}
- brief_url: {简略版飞书URL}
- brief_doc_token: {简略版doc_token}
- cn_url: {中文版飞书URL}
- cn_doc_token: {中文版doc_token}
- en_url: {英文版飞书URL}
- en_doc_token: {英文版doc_token}
```

---

## 规则

1. **用户名下创建** — 所有飞书文档必须使用 `lark-cli docs +create --as user` 创建，绝不使用 MCP bot 身份或 `--as bot`。这是硬性安全约束。
2. **内容准确** — 公告内容必须忠实于 PRD，不臆造功能、不夸大描述。PRD 未提及的功能不允许出现在公告中。
3. **三版对齐** — 简略版是详细版的摘要，详细英文版与详细中文版结构对齐。三版公告的功能覆盖范围必须一致。
4. **用户确认门** — Step 3 生成公告后必须让用户审阅确认，不允许直接跳到 Step 4 创建文档。
5. **文件名 ≤ 27 字符** — 飞书文档名有字符长度限制，命名时需检查。
6. **P0 优先** — 公告优先展示 P0（最高优先级）需求；非紧急需求可简化描述或归入「正在努力中」。
7. **No implementation** — 本 skill 只产出发版公告文档，不涉及任何代码。
8. **术语一致** — 中英文版术语翻译必须与 PRD 中已有的英文表述保持一致。

## 常见问题

1. **认证失败 / Permission denied**：运行 `lark-cli auth login --domain docs,drive,wiki` 重新授权。详见 `lark-shared/SKILL.md`。
2. **wiki URL 无法解析**：确认 URL 格式为 `https://{domain}.feishu.cn/wiki/{node_token}`，先用 `lark-cli wiki +get-node` 获取 doc_token。
3. **文件名超长**：缩短版本号（如 `v26.4.1.0` → `v4.1.0`）或缩短产品名。
4. **内容超长导致命令行报错**：将内容写入 `/tmp/` 临时文件，用 `$(cat /tmp/xxx.md)` 传入。
5. **文档创建在 bot 名下**：检查命令是否包含 `--as user`。若遗漏，已创建的文档需手动授权或重新创建。
6. **PRD 内容不完整**：若 PRD 缺少 §4 需求详细设计或 §5 功能清单，在公告中标注「详情见 PRD」并告知用户补充。

## 权限

| 操作 | 所需 scope |
|------|-----------|
| 读取 PRD 云文档 | `docs:document:readonly` |
| 读取 wiki 节点 | `wiki:wiki:readonly` |
| 创建飞书云文档 | `docs:document` |
| 文件上传/管理 | `drive:drive` |

## 参考

- [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — lark-cli 认证与权限
- [`../write-a-prd/SKILL.md`](../write-a-prd/SKILL.md) — PRD 结构参考（§4 需求详细设计 / §5 功能清单）
- [`../lark-doc/SKILL.md`](../lark-doc/SKILL.md)（若存在）— docs +create / +fetch

## Source & license

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

- **Author:** [CookiesHaha](https://github.com/CookiesHaha)
- **Source:** [CookiesHaha/ash-claude-skills](https://github.com/CookiesHaha/ash-claude-skills)
- **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-cookieshaha-ash-claude-skills-release-announcement
- Seller: https://agentstack.voostack.com/s/cookieshaha
- 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%.