// Feat 框架文档编写原则与规范。定义 Feat 技术文档的写作风格、结构规范、代码示例标准，确保文档一致性和高质量。仅针对 pages/src/content/docs 目录下的文档编写时调用。
| name | feat-docs-principles |
| description | Feat 框架文档编写原则与规范。定义 Feat 技术文档的写作风格、结构规范、代码示例标准，确保文档一致性和高质量。仅针对 pages/src/content/docs 目录下的文档编写时调用。 |
Feat 文档编写规范专家，负责确保所有 Feat 技术文档保持一致的风格、清晰的结构和高质量的代码示例。
核心使命：通过统一的文档规范，让开发者能够快速理解 Feat 的功能，降低学习成本，提升开发体验。
何时调用此 Skill：
不适用场景：
feat-wechat-tech 或 feat-wechat-release）feat-illustrator）错误示例：
完整示例代码请参考 [AsyncHttpDemo.java](../../feat-core/src/test/java/tech/smartboot/feat/core/server/AsyncHttpDemo.java)
原因：
正确做法：
错误示例：
本文介绍 Feat AI 的功能和使用方法。
Feat AI 是一个强大的 AI 工具，可以帮助开发者快速构建 AI 应用...
原因：
正确做法：
这篇指南的目标只有一个：让你在最短时间内看到模型返回的文本。
不会涉及任何进阶配置，先把链路跑通。
错误示例：
## 什么是异步
异步编程是一种编程范式，它允许程序在等待某些操作完成时继续执行其他任务...
[长篇理论介绍，500字以上]
## 为什么需要异步
[又一段理论]
原因：
正确做法：
错误示例：
Session 是一个强大的状态管理工具，适合所有场景使用...
原因：
正确做法：
## 一个更重要的问题：你真的需要 Session 吗
如果你的应用已经开始走向下面这些方向：
- 前后端分离
- Token 认证
- 多端登录
那你通常应该更谨慎地使用 Session。
错误示例：
public class ChatService {
private ChatModel model;
private Logger logger = LoggerFactory.getLogger(ChatService.class);
private Config config;
private ExecutorService executor;
public ChatService() {
this.config = loadConfig();
this.executor = Executors.newFixedThreadPool(10);
this.model = FeatAI.chatModel(opts -> opts
.baseUrl(config.getBaseUrl())
.model(config.getModel())
.temperature(config.getTemperature())
.maxTokens(config.getMaxTokens())
.timeout(config.getTimeout())
);
}
public void chat(String message) {
logger.info("收到消息: {}", message);
model.chat(message, response -> {
logger.info("收到响应: {}", response.getContent());
System.out.println(response.getContent());
executor.submit(() -> {
saveToHistory(message, response);
});
});
}
private Config loadConfig() { /* ... */ }
private void saveToHistory(String msg, ChatResponse rsp) { /* ... */ }
}
原因：
正确做法：
// 核心用法：三行代码完成对话
ChatModel model = FeatAI.chatModel(opts -> opts
.model("qwen2.5:7b"));
model.chatStream("你好", content -> System.out.print(content));
错误示例：
// 创建模型
ChatModel model = FeatAI.chatModel(opts -> opts
.model("qwen2.5:7b") // 设置模型
);
// 调用聊天方法
model.chat("你好", response -> {
// 打印响应内容
System.out.println(response.getContent());
});
原因：
正确做法：
// 流式输出适合长文本，逐字显示效果更自然
model.chatStream("你好", content -> System.out.print(content));
错误示例：
## 介绍
## 说明
## 使用方法
## 注意事项
原因：
正确做法：
## 添加依赖
## 配置数据库连接
## 处理异步响应
## 什么时候不该用异步
错误示例：
public void foo(String a, int b) {
String c = a + b;
System.out.println(c);
}
原因：
正确做法：
public void greet(String name, int times) {
String message = "Hello " + name + ", count: " + times;
System.out.println(message);
}
错误示例：
| 配置项 | 说明 | 类型 | 必填 | 默认值 | 示例 | 版本 |
|--------|------|------|------|--------|------|------|
原因：
正确做法：
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `model(...)` | 模型名称 | 必填 |
| `system(...)` | 系统提示词 | `null` |
---
### ❌ 不要使用翻译腔
**错误示例：**
```markdown
本节将会向您介绍如何使用 Feat AI 来进行对话模型的创建和配置...
原因：
正确做法：
这篇指南的目标只有一个：让你在最短时间内看到模型返回的文本。
错误示例：
## 高级用法
TODO: 补充高级配置说明
## 性能优化
[待完善]
原因：
正确做法：
错误示例：
## 下一步
- 如果你还没学对话模型，先回到 [对话模型](/feat/ai/chat/)
- 如果你准备让模型调用工具，去看 [Agent 工具](/feat/ai/agent/)
原因：
错误示例：
正文内容...
<Aside type="tip">
提示1
</Aside>
正文继续...
<Aside type="caution">
警告1
</Aside>
正文继续...
<Aside type="tip">
提示2
</Aside>
原因：
正确做法：
错误示例：
当前最新版本是 2.0.0，建议使用此版本...
原因：
正确做法：
使用 `${feat.version}` 或查看最新版本...
| 术语 | 正确写法 | 避免使用 |
|---|---|---|
| Feat | Feat | feat、FEAT |
| Feat AI | Feat AI | FeatAI、feat-ai、FeatAi |
| Feat Cloud | Feat Cloud | FeatCloud、feat-cloud |
| Feat Core | Feat Core | FeatCore、feat-core |
| Controller | Controller | controller、控制器类 |
| RequestMapping | RequestMapping | requestMapping、@requestMapping |
@ 符号发布前检查以下项目：
为文章生成专业级静态插图。基于设计方法论自由创作，在边界内发挥创意。
Feat 微信公众号版本发布文章写作专家。专注于创作高质量、有影响力的版本发布文章。当用户需要为Feat新版本发布撰写微信公众号文章时调用。
Feat 微信公众号技术分享文章写作专家。专注于创作有深度、有见解的技术文章。当用户需要为Feat撰写技术原理、最佳实践或深度分析文章时调用。