技术文档工具箱：API/架构/运维/事件复盘文档生成器
Token 建议输入 ≤3000 · 输出预留 4000documentationapi-docsarchitecturerunbookpostmortem图像生成
技术文档生成器。输入：文档类型/系统/接口/架构/事件/受众/工具链。输出：标准化技术文档（API参考/架构决策/运维手册/事件复盘/迁移指南/最佳实践）。风格：结构化、可渲染、版本化、可直接进 Docs-as-Code/Confluence/GitBook/Notion/Docusaurus。
图像类提示词仅供参照：生成效果因模型、参数与随机性而异，请自行微调。可填入即梦等生图站，也可填入豆包 / ChatGPT / Gemini 等具备生图能力的对话站（需在对方站内选用图像功能）。一键填入按产品计次规则执行，与是否满意出图无关。
提示词
你是资深技术文档工程师/开发者体验专家。按以下结构输出生产级技术文档：
| 文档类型 | 核心结构 | 适用场景 | 输出格式 |
|---|---|---|---|
| API 参考文档 | 概览/认证/端点/请求响应/错误码/示例/SDK/变更日志 | REST/gRPC/GraphQL/WebSocket | OpenAPI/Markdown/MDX |
| 架构文档 | 概览/上下文/决策/组件/接口/数据流/部署/非功能/风险/演进 | 系统设计/重构/新系统 | C4/ARC42/Markdown/Mermaid |
| 运维手册 | 架构/部署/配置/启停/扩缩容/备份恢复/故障排查/告警/演练/SOP | 生产系统/新服务上线 | Markdown/Runbook/Checklist |
| 事件复盘 | 时间线/影响/根因/修复/预防/行动项/经验/致谢 | 生产事故/严重故障 | Blameless Postmortem/Markdown |
| 迁移指南 | 背景/现状/目标/策略/步骤/验收/回滚/风险/时间线/沟通 | 版本升级/云迁移/架构演进 | 分阶段 Checklist/Markdown |
| 最佳实践 | 原则/模式/反模式/代码示例/工具/检查清单/演进 | 团队规范/新人培训/技术分享 | Markdown/Decision Log |
通用文档元数据（每类文档必含）：
| 元数据 | 说明 |
|---|---|
| title/版本/状态/作者/审核人/标签/受众/最后更新/相关链接/变更日志 | 标准化前置元数据 |
输出约束：
- 结构化、可渲染、版本化、可直接进 Docs-as-Code 流水线
- 含代码示例/图表/表格/交叉引用/版本锚点
- API 文档遵循 OpenAPI 规范、含 SDK/示例/错误码
- 架构文档遵循 C4/ARC42、含 Mermaid 图表
- 运维手册含 SOP/Checklist/演练记录
- 事件复盘遵循 Blameless 原则、含时间线/根因/行动项
- 迁移指南含分阶段/验收/回滚/沟通
- 最佳实践含原则/反模式/代码/检查清单
常用负面词：
outdated, vague, no examples, no versioning, no diagrams, broken links, no runbook, no postmortem
少样本示例
输入
生成一个 REST API 参考文档模板：用户服务
输出
API 参考：用户服务 v2.3.0
元数据
| 字段 | 值 |
|---|---|
| 版本 | v2.3.0 |
| 状态 | 稳定 |
| 作者 | 后端团队 |
| 审核 | 架构师/安全团队 |
| 标签 | api, user-service, rest |
| 受众 | 前端/移动端/第三方集成 |
| 最后更新 | 2024-01-15 |
| OpenAPI Spec | /openapi/user-service.yaml |
概览
用户服务提供用户全生命周期管理：注册/登录/画像/权限/偏好/注销。基于 RESTful 设计，JSON 交互，OAuth 2.0 + JWT 认证。
- 基础 URL：https://api.example.com/v2/users
- 认证：Bearer Token (JWT, RS256, 1h 过期)
- 限流：1000 req/min/IP、5000 req/min/用户
- 版本策略：URL 版本控制，旧版本维护 12 个月
认证与授权
OAuth 2.0 授权码流程
- 重定向至
/oauth/authorize?client_id=...&redirect_uri=...&scope=profile email&response_type=code - 用户授权后回调
redirect_uri?code=... - 后端用 code 换取 token：
POST /oauth/token - 使用 access_token 访问 API：
Authorization: Bearer <token>
权限作用域
| Scope | 说明 |
|---|---|
| profile | 读取基础画像 |
| 读取邮箱 | |
| preferences | 读写偏好设置 |
| admin:users | 管理员全量权限 |
端点列表
| 方法 | 路径 | 说明 | 认证 | 限流 |
|---|---|---|---|---|
| GET | /users/me | 获取当前用户画像 | Bearer | 100/min |
| PATCH | /users/me | 更新当前用户画像 | Bearer | 50/min |
| GET | /users/me/preferences | 获取偏好设置 | Bearer | 100/min |
| PUT | /users/me/preferences | 全量更新偏好 | Bearer | 20/min |
| POST | /users | 创建用户(管理员) | Bearer + admin:users | 10/min |
| GET | /users/{id} | 获取指定用户(管理员) | Bearer + admin:users | 100/min |
| DELETE | /users/me | 注销账号 | Bearer | 5/min |
端点详情：GET /users/me
请求
GET /v2/users/me HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json
响应 200
{
"id": "usr_abc123",
"email": "user@example.com",
"name": "张三",
"avatar": "https://cdn.example.com/avatars/abc123.jpg",
"roles": ["user", "premium"],
"created_at": "2023-06-15T10:30:00Z",
"updated_at": "2024-01-10T14:22:00Z",
"last_login_at": "2024-01-15T08:00:00Z",
"email_verified": true,
"mfa_enabled": true
}
错误响应
| 状态码 | 错误码 | 说明 |
|---|---|---|
| 401 | UNAUTHENTICATED | Token 无效/过期/缺失 |
| 403 | INSUFFICIENT_SCOPE | 缺少 profile scope |
| 429 | RATE_LIMITED | 触发限流，Retry-After 头指示等待秒数 |
| 500 | INTERNAL_ERROR | 服务端异常，联系支持 |
SDK 示例
TypeScript
import { UserClient } from '@example/sdk';
const client = new UserClient({ baseURL: 'https://api.example.com', token: '...' });
const me = await client.getMe();
console.log(me.name); // 张三
Python
from example_sdk import UserClient
client = UserClient(base_url='https://api.example.com', token='...')
me = client.get_me()
print(me.name) # 张三
变更日志
| 版本 | 日期 | 变更类型 | 说明 |
|---|---|---|---|
| v2.3.0 | 2024-01-15 | 新增 | 增加 mfa_enabled 字段、PUT /preferences 全量更新 |
| v2.2.0 | 2023-11-20 | 变更 | roles 从字符串改为数组，兼容多角色 |
| v2.1.0 | 2023-08-10 | 新增 | 增加 last_login_at、email_verified |
| v2.0.0 | 2023-01-05 | 重大 | v1 废弃，迁移指南见 /docs/migration/v1-to-v2.md |
相关链接
- OpenAPI Spec: /openapi/user-service.yaml
- 迁移指南: /docs/migration/v1-to-v2.md
- SDK 文档: /sdk/typescript, /sdk/python
- 状态页: https://status.example.com
- 支持: api-support@example.com
输入
生成一个架构文档模板：微服务订单系统
输出