技术蓝图写作Skill：让系统内部逻辑不再口口相传，用标准化文档沉淀架构共识
- 专为开发者打造的“系统说明书”生成器：它专注于记录系统内部如何运作，而非面向用户的使用手册，能帮你把复杂的架构决策、API 合同和数据流讲清楚。
- 先搜索后动笔，告别重复造轮子：技能内置了“先查找现有蓝图”的强制流程，通过 Glob 和 Grep 工具避免文档冲突和内容冗余，维护单一可信来源。
- 强制结构化，拒绝流水账：从概述、架构、API 接口到边缘情况，有一套经过验证的 Markdown 模板驱动写作，确保关键信息不遗漏。
- 精确表达优于华丽辞藻：技能内置写作风格指南，引导你记录“行为”而非“实现”，用具体的错误类型和返回值替代模糊的“优雅处理”。
- 开箱即用的工程化思维：将技术写作从个人发挥转变为工程实践，适合需要维护长期项目、多人协作或频繁交接的开发团队。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：技术蓝图写作Skill 技能英文名：blueprints-writing 技能ID：13982
这个技能要解决的核心痛点是：代码能跑通，但没人说得清它内部到底怎么运转。当新成员加入项目，或者你需要回顾半年前写下的模块时，如果只有代码没有蓝图，理解成本会非常高。技术蓝图写作Skill 将“写内部技术文档”这件事从依赖个人习惯和记忆力，转变为可重复、可搜索、有固定标准的流程。它通过强制你先检索已有蓝图、再按结构化模板撰写，确保文档与代码同步演进，而不是成为过时的负担。
关于一键安装，该技能属于 AI 技能生态中的一员，安装思路通常如下（具体命令与入口请以你所在平台的官方说明为准）：
- 安装前提：确认你使用的 AI 客户端或开发环境支持技能（Skill）机制，并已登录相应的开发者账号。
- 获取技能：在技能市场或通过官方提供的技能 ID（13982）搜索“技术蓝图写作”或“blueprints-writing”，点击安装或启用按钮。
- 验证生效：安装后，在支持技能调用的对话界面或编辑器中，尝试输入与“编写技术蓝图”“更新架构文档”相关的指令，观察 AI 是否按照技能定义的流程（如先搜索现有蓝图）进行响应。若响应中体现了“先检查 blueprints 目录”的行为，即表示技能已生效。
- 权限确认：该技能声明了
Read, Write, Edit, Grep, Glob工具权限，确保你的运行环境允许 AI 读取和写入项目文件，以便技能正常执行搜索与创建蓝图的动作。
该技能的主要功能和特点
- 强制防重复机制：技能最显著的特点是“总是先搜索现有蓝图”。在创建新文档前，它会自动执行
Glob("blueprints/*.md")列出已有文件，并用Grep按关键词检索，从根本上避免了同一系统出现多份冲突文档的情况。 - 标准化文档骨架：提供了一套完整的 Markdown 蓝图模板，涵盖概述、架构（组件、数据流、依赖）、API/接口（函数签名、参数、返回值、异常）、行为（正常操作、错误处理、边缘情况）、关键文件索引以及相关系统链接。这确保了不同人写出的蓝图具有一致的可读性。
- 精确写作风格指南：技能内置了写作原则，引导用户区分“记录行为”与“记录实现”。例如，它建议用“无效输入返回带有字段名和原因的 ValidationError”代替“系统优雅地处理错误”，让文档更具指导价值而非模糊描述。
- 明确的生命周期管理：技能强调了“与代码变更一起更新蓝图”“删除已删除功能的文档”“明确标记已弃用功能”，将文档维护纳入开发流程，而非一次性任务。
- 聚焦内部逻辑：与 README（项目概述）和用户文档（如何使用）明确划清界限，它只关心“系统内部如何工作”，包括那些从代码中不易看出的设计决策和集成点。
和普通写作工具/文档工具比强在哪？ 普通工具只提供空白编辑器，而技术蓝图写作Skill 通过 AI 的推理能力，将“写文档”拆解为“搜索-读取-结构化输出”的智能工作流，并在过程中强制执行团队约定的规范，降低了技术写作的认知负担。
如何使用该技能？
该技能为“非用户直接调用”（user-invocable: false），意味着你通常不需要像使用普通命令那样刻意唤醒它，而是在进行与系统设计、API 变更、架构讨论相关的对话时，由 AI 根据上下文自动判断并调用。以下是基于技能定义梳理的典型使用步骤：
步骤 1：触发场景 当你向 AI 提出“帮我记录一下这个新模块的设计”“更新一下认证系统的 API 文档”或“梳理一下订单处理的数据流”时，技能即被激活。
步骤 2：检查现有蓝图（关键步骤）
技能会首先在项目 blueprints/ 目录下执行搜索：
- 列出所有现有蓝图：
Glob("blueprints/*.md") - 按你提到的功能关键词搜索：
Grep("认证", path: "blueprints/", output_mode: "files_with_matches")
步骤 3：读取并判断
如果找到相关文件（如 blueprints/authentication.md），技能会读取现有内容，决定是“更新”还是“新建”。若不存在，则进入创建流程。
步骤 4：按模板写入内容 技能会引导你按照结构化模板填充信息。例如，针对一个“消息推送服务”，它生成的内容可能包含：
---
name: message-push-service
summary: 负责向用户端推送实时通知和系统消息。
---
# 消息推送服务
## 概述
该服务解决了业务系统与用户终端之间实时通知的触达问题。它接收来自业务队列的消息，根据用户偏好进行过滤，并通过 WebSocket 或 APNs 投递。在整体架构中，它位于业务逻辑层与终端网关之间。
## 架构
### 组件
- **消息接收器** - 监听消息队列，拉取待推送消息。
- **偏好过滤引擎** - 根据用户设置过滤免打扰消息。
- **通道适配器** - 封装 APNs、WebSocket 等不同推送通道的差异。
### 数据流
1. 业务系统将消息体写入消息队列。
2. 消息接收器消费消息并交给偏好过滤引擎。
3. 过滤后的消息进入通道适配器。
4. 适配器调用底层推送服务完成投递。
### 依赖
- **消息队列** - 提供削峰填谷和解耦能力。
- **用户配置服务** - 查询用户的免打扰时段与推送开关。
## API / 接口
### 函数
#### `pushToUser(userId, payload)`
向指定用户推送一条消息。
**参数：**
- `userId`（字符串） - 目标用户的唯一标识。
- `payload`（对象） - 消息内容，包含 title、body 和可选跳转链接。
**返回：** 布尔值 - 表示是否成功提交至推送通道。
**抛出：** `UserNotFoundError` - 当 userId 不存在时抛出。
**示例：**
```typescript
const success = pushToUser('user_123', { title: '订单更新', body: '您的订单已发货' });
行为
正常操作
消息经过滤后，优先选择 WebSocket 通道；若用户离线，则降级为 APNs 投递。
错误处理
- 无效输入：payload 缺少必要字段时，记录错误日志并丢弃该消息。
- 缺少依赖：用户配置服务不可用时，默认允许推送（偏向送达率）。
边缘情况
- 空输入处理：payload 中 title 为空时，使用系统默认标题。
- 并发访问：同一用户短时间内多条消息按队列顺序串行投递，避免终端弹窗轰炸。
文件
src/receiver.ts- 消息队列监听与消费逻辑。src/filter.ts- 偏好过滤核心逻辑。src/adapters/- 各推送通道适配器实现。
相关系统
**步骤 5：校验与落盘**
确认内容符合“记录行为而非实现”的原则后，技能调用 `Write` 工具将内容写入 `blueprints/` 目录。
## 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **技术蓝图写作Skill** | AI 驱动的内部技术文档生成与维护流程 | 强制搜索防重复、结构化模板填充、写作风格引导、生命周期管理 | 低。安装技能后，在对话中描述系统需求即可触发。 | 需要维护长期项目、多人协作开发、频繁进行架构迭代的工程团队 | **优势**：将文档规范内化为 AI 行为，减少人为疏漏；自动关联代码与文档。**不足**：依赖 AI 对系统描述的理解准确度，复杂逻辑仍需人工复核。 |
| **手写 Markdown 文档** | 传统的纯人工文档编写方式 | 完全自由控制内容与格式 | 零门槛，有编辑器即可 | 临时记录、个人笔记、对格式要求不高的场景 | **优势**：灵活度最高。**不足**：容易格式混乱、内容过时、忘记更新；缺乏防重复机制，多人协作易冲突。 |
| **Confluence / Notion 等协作文档平台** | 团队知识库与文档协作空间 | 富文本编辑、评论、版本历史、模板库 | 中。需要团队购买并维护平台账号。 | 跨部门知识共享、产品需求文档、非技术文档 | **优势**：协作体验好，权限管理完善。**不足**：与代码库分离，容易出现文档代码不同步；缺乏针对技术蓝图的结构化约束，质量依赖作者水平。 |
| **JSDoc / TypeDoc 等代码注释生成工具** | 从源码注释自动生成 API 文档 | 解析代码注释生成 HTML 文档 | 中。需要开发者严格遵循注释规范。 | 对外暴露的 SDK、开源库 API 文档 | **优势**：与代码结合紧密，更新及时。**不足**：仅覆盖 API 签名，无法记录架构决策、数据流、边缘情况等蓝图核心内容；对注释规范要求极高。 |
## 该技能的典型应用场景与实际体验情况
**场景一：后端工程师接手复杂模块**
- **角色**：刚加入支付团队的后端工程师小李。
- **痛点**：面对数万行的支付路由和清算代码，只能靠阅读源码和询问同事来理解资金流转逻辑，效率低下且容易遗漏关键分支。
- **使用方式**：小李在 AI 对话中描述“帮我梳理一下支付路由模块的架构和主要数据流”。技能触发后，先在 `blueprints/` 目录搜索是否已有 `payment-routing.md`，若存在则直接读取并总结给小李；若不存在，则引导小李提供关键信息（组件、依赖、API），生成一份结构化蓝图入库。
- **实际体验**：上手难度低，只要会用自然语言描述系统即可。效果显著，一份好的蓝图能让新成员在半小时内建立对系统的全局认知。**注意事项**：AI 生成的蓝图需要小李核对代码中的实际逻辑，尤其是错误处理和边缘情况部分，不能完全依赖 AI 的推测。
**场景二：架构师推动 API 合同标准化**
- **角色**：负责中台架构的张工。
- **痛点**：各业务团队对公共 API 的返回值、错误码定义不一致，导致调用方频繁踩坑，沟通成本巨大。
- **使用方式**：张工在 AI 中要求“为用户中心服务的公共 API 编写技术蓝图，重点记录函数签名、参数类型、返回值和抛出的错误类型”。技能会按照模板中的“API / 接口”章节，引导张工逐个函数定义合同，并生成包含示例代码的文档。
- **实际体验**：相比口头宣讲或零散的会议纪要，蓝图文档成为可检索、可引用的权威依据。**注意事项**：API 变更后，必须同步更新蓝图。技能虽然提供了“更新”流程，但触发更新依赖于开发者主动发起对话。
**场景三：技术负责人进行架构决策记录**
- **角色**：创业公司技术负责人老王。
- **痛点**：团队讨论“为什么选择消息队列而不是直接 RPC 调用”时，决策过程只存在于会议记录和当事人的记忆里，新人常对此提出重复质疑。
- **使用方式**：老王在决策会后，要求 AI“记录一下订单服务选择异步消息队列的架构决策及理由”。技能会在蓝图的“概述”和“依赖”部分，引导老王补充决策背景、备选方案对比和最终理由，形成可追溯的决策档案。
- **实际体验**：有效减少了重复讨论，让团队精力聚焦于新问题。**注意事项**：决策理由的颗粒度需要老王自己把握，AI 只能基于输入信息进行结构化整理，无法凭空创造决策依据。
## 该技能能为用户带来的价值
- **效率提升：从“小时级”到“分钟级”的文档产出**：传统方式下，撰写一份合格的系统蓝图需要 1-2 小时甚至更久，涉及回忆、梳理、排版。技能通过模板和 AI 辅助填充，可将初稿产出时间压缩到几分钟内，开发者只需聚焦于核心逻辑的准确性审核。
- **质量兜底：降低技术文档的维护门槛**：写作风格指南和结构化模板强制要求记录“错误类型”“边缘情况”“依赖关系”等易遗漏点，让即使不擅长写作的工程师也能产出合格文档。长期来看，文档的标准化程度提升，团队知识传递的摩擦成本显著降低。
- **知识资产沉淀：告别“口口相传”的脆弱传承**：技术蓝图作为代码之外的“系统内部说明书”，将架构决策、设计约定、集成细节固化为可搜索、可版本管理的文件。当人员流动或项目交接时，蓝图成为最可靠的知识载体，降低对特定个人的依赖。
- **流程内化：让文档更新成为开发习惯**：技能将“先搜索、再更新”的流程内置于 AI 行为中，潜移默化地引导团队养成维护文档的习惯。配合代码变更同步更新蓝图的理念，有助于形成“代码与文档同源演进”的健康工程文化。
## 常见问题 FAQ
**Q1：这个技能怎么安装？需要付费吗？**
A：安装方式取决于你使用的 AI 平台或开发工具。通常你需要在技能市场或插件中心搜索技能名称“技术蓝图写作”或英文名“blueprints-writing”进行启用。关于收费情况，请以你所在平台的官方说明为准，不同平台定价策略不同。
**Q2：这个技能适合谁用？我是前端开发，需要写蓝图吗？**
A：适合所有需要维护系统内部逻辑的开发者，包括前后端工程师、架构师和技术负责人。只要你的项目存在多个组件交互、公共 API 或复杂业务逻辑，写蓝图就有价值。前端项目中的状态管理架构、组件通信机制、构建流程等同样属于蓝图范畴。
**Q3：技能生成的文档内容准确吗？我能直接信任吗？**
A：技能是一个文档生成辅助工具，它的准确性取决于你输入信息的质量和 AI 对系统描述的理解。建议将生成的内容视为“初稿”或“结构化整理”，必须由熟悉系统的开发者进行核对，尤其是涉及具体错误类型、返回值、边缘情况等细节时，应以代码实际行为为准。
**Q4：和直接用 ChatGPT 写文档有什么区别？**
A：普通对话中，AI 也会根据你的描述生成文档，但缺乏“先搜索现有文件防止重复”的强制流程，也缺少针对技术蓝图的专用模板和写作风格约束。技术蓝图写作Skill 将这些工程实践固化为可重复的流程，更适合在真实项目目录中使用，并与现有文档体系形成联动。
**Q5：如果我的项目里还没有 `blueprints` 目录，技能能工作吗？**
A：技能的逻辑是优先搜索 `blueprints/` 目录。如果目录不存在，搜索动作不会返回结果，技能会进入创建流程，并可能在写入时创建该目录（取决于运行环境权限）。建议你在项目根目录手动创建 `blueprints` 文件夹，以便统一管理蓝图文件。