Frontend Tech Doc Guide

规范 AI 生成飞书技术文档结构，确保 Markdown 层级正确、章节顺序稳定、可读性高。

Security Scan

This is an instruction-only skill that provides strict rules for generating Feishu frontend technical docs; it requests no credentials, has no install step, and its requirements match its described purpose.

Purpose & Capability

Name and description claim a doc-generation/style guide for Feishu frontend tech docs; the SKILL.md contains only rules and templates for that task. There are no unrelated required binaries, env vars, or install actions.

Instruction Scope

Instructions are narrowly focused on generating Markdown with specific structure, layout, and Mermaid usage and do not instruct the agent to read files, access credentials, or transmit data externally. Minor oddities: very strict formatting rules (e.g., 'Mermaid only once', 'use <br/> instead of \n', 'no explanatory text, only Markdown') could cause generation failures or hide contextual output, but they are within the documented purpose.

Install Mechanism

No install spec and no code files — lowest-risk instruction-only skill. Nothing will be written to disk or fetched during install.

Credentials

The skill requires no environment variables, credentials, or config paths; requested access is proportional (none) to the stated purpose.

Persistence & Privilege

Skill metadata contains an 'auto':true field (in SKILL.md metadata), and the platform defaults permit autonomous invocation. The registry flags show always:false, so it is not force-included in every agent run. Consider whether you want a skill that can be auto-invoked by agents.

Assessment

This skill appears internally consistent and low-risk: it only contains formatting rules for producing frontend tech docs and does not request credentials or install code. Before installing: (1) Confirm you want an instruction-only skill that enforces 'only output Markdown' and suppresses explanatory text — this can make debugging harder. (2) If you do not want automatic runs, check how your agent platform handles the SKILL.md metadata ('auto':true) and disable autonomous invocation if needed. (3) Test the skill with non-sensitive sample prompts to ensure its strict rules don't produce broken output (especially the Mermaid/<br/> requirement). Request the publisher/source if you need provenance or updates. If any code files, network endpoints, or credential requests appear later, re-evaluate immediately.

---

前端活动技术文档生成规范（AI 专用）

本文件用于指导 AI 自动生成 飞书技术文档。重点解决：

1. Markdown 标题层级错误
2. 章节顺序混乱 / 内容重复
3. 文本堆叠导致可读性差

AI 在生成文档时 必须严格遵守以下结构与格式规则。

---

一、文档结构规则（必须严格遵守）

1. 标题层级规则

文档标题层级 必须严格按以下结构生成，不允许跳级：

# 文档标题

# 一、需求认知
需求 PRD：xx
飞书项目：xx
后端文档：xx
UI 设计稿：xx

- 需求背景
- 需求目标
- 核心/特殊改动点

# 二、项目排期
<!-- 评估需求开发内容量，根据复杂度和时间成本，合理分配项目排期。 -->

# 三、功能流程
<!-- 全部使用 mermaid 流程图 表示 -->
## 1. 页面流程
## 2. 功能流程
## ...其他流程

# 四、需求拆分
<!-- 详细描述需求功能模块，包括前端需求点以及所对应的后端接口。 -->
<!-- 需要考虑到边界情况以及异常处理。 -->

# 五、业务埋点 & Sentry 监控
<!-- 埋点信息从需求 PRD 中获得，关注参数，触发时机 -->
<!-- 埋点需要生成 mermaid 操作路径 -->
<!-- 特殊报错需要使用 Sentry 监控输出 -->

# 六、数据链路
<!-- 使用 mermaid 绘制用户在页面的活动链路 -->


# 七、提测信息
<!-- 使用表格格式，表头：模块、内容、备注 -->
<!-- 第一列：提测项目，提测环境 -->

# 八、验收与上线
<!-- 使用表格格式，表头：项目，上线 TAG -->


# 九、待确认问题
<!-- 使用表格格式，表头：问题，结论 -->

二、章节生成顺序（防止内容错位）

AI 必须严格按以下顺序生成内容：

1. 需求认知
2. 项目排期
3. 功能流程
4. 需求拆分
5. 业务埋点 & Sentry 监控
6. 数据链路
7. 提测信息
8. 验收上线
9. 待确认问题

关键约束

生成时必须遵守：

• 不得提前生成后续章节内容
• 不得回写前文
• 不得复制后文内容到前文

例如禁止出现：

开头出现：
第7章内容
第8章内容

若模型生成时出现重复章节，必须：

• 删除重复段
• 保留第一次出现的位置

---

三、段落排版规则（提升可读性）

AI 生成内容时 禁止连续长文本块。

每段说明 必须拆分为以下结构之一：

1 优先使用列表

错误示例：

系统需要完成登录、鉴权、资格校验、任务获取、抽奖逻辑等功能。

正确示例：

系统主要流程包括：

- 登录
- 身份鉴权
- 资格校验
- 任务获取
- 抽奖执行

---

2 技术描述必须结构化

统一使用 模块结构：

模块名称

- 功能说明
- 接口
- 关键逻辑
- 依赖

示例：

### 积分活动模块

功能：

- 展示用户积分
- 提供抽奖入口

接口：

- getUserPoints
- drawLottery

关键逻辑：

- 未登录先触发登录
- 积分不足提示

---

四、流程章节规范（必须包含 Mermaid）

流程章节 必须包含 Mermaid 图。

示例：

flowchart TD
  Entry[活动入口] --> Login{是否登录}
  Login -- 否 --> Auth[手机号授权]
  Login -- 是 --> Check[资格校验]
  Check --> Task[任务列表]
  Task --> Draw[抽奖]
  Draw --> Result[结果弹窗]

生成规则：

• Mermaid 只允许出现一次代码块
• 使用 <br/> 换行
• 不允许使用 \n

---

五、模块拆分规则

模块章节必须按以下格式生成：

## 模块名称

功能：

- xxx
- xxx

核心逻辑：

- xxx
- xxx

接口：

| 接口 | 说明 |
|----|----|
| getTask | 获取任务 |
| drawLottery | 抽奖 |

依赖：

- 风控接口
- 奖品接口

禁止生成 长段技术说明文字。

---

六、埋点章节格式

必须使用表格。

示例：

事件	code	触发时机	参数
页面曝光	page_view	页面加载	...
抽奖点击	draw_click	点击抽奖	...
抽奖成功	draw_success	返回中奖	中奖结果

---

七、提测信息格式

表格结构

八、AI 生成质量规则（重点）

AI 在生成文档前必须执行：

1 章节检查

确认存在以下章节：

• 需求认知
• 项目排期
• 功能流程
• 需求拆分
• 业务埋点 & Sentry 监控
• 数据链路
• 提测信息
• 验收上线
• 待确认问题

缺一不可。

---

2 排版检查

确保：

• 无连续超过 5 行纯文本段落

• 必须包含

  • 列表
  • 表格
  • Mermaid

---

九、AI 输出限制

AI 输出文档时必须遵守：

1 不输出解释

只输出 Markdown 文档

2 不输出多版本

只输出最终版本

3 不输出空章节

无内容时写：

待补充

---

十、推荐文档标题格式

【YYMMDD】活动简称-前端技术方案

示例：

【260320】春季直播活动-前端技术方案

---

十一、生成目标

AI 生成的文档必须达到：

• Markdown 层级正确
• 飞书渲染结构稳定
• 章节顺序正确
• 信息结构化
• 可读性高

否则视为生成失败。