Skip to content

Commit 3e3684c

Browse files
phodalphodal
committed
feat(docs): update AI-friendly documentation and styles
- Update section titles and content for better clarity - Improve color scheme and add utility classes - Fix code indentation and formatting - Add links to AutoDev components - Adjust ArchitectureFlow component colors for consistency
1 parent db5d039 commit 3e3684c

File tree

3 files changed

+110
-101
lines changed

3 files changed

+110
-101
lines changed

‎docs/ai-friendly/index.mdx‎

Lines changed: 80 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -20,23 +20,23 @@ export const AIFriendlyArchitecture = () => {
2020
const specPracticeRef = useRef(null);
2121

2222
const scrollToSection = (section) => {
23-
setActiveSection(section);
24-
setTimeout(() => {
25-
const refs = {
26-
'domain-language': domainLanguageRef,
27-
'planner': plannerRef,
28-
'semantic-code': semanticCodeRef,
29-
'refactor-tool': refactorToolRef,
30-
'retrieval-tool': retrievalToolRef,
31-
'refined-question': refinedQuestionRef,
32-
'spec-practice': specPracticeRef
33-
};
34-
35-
const ref = refs[section];
36-
if (ref && ref.current) {
37-
ref.current.scrollIntoView({ behavior: 'smooth' });
38-
}
39-
}, 100);
23+
setActiveSection(section);
24+
setTimeout(() => {
25+
const refs = {
26+
'domain-language': domainLanguageRef,
27+
'planner': plannerRef,
28+
'semantic-code': semanticCodeRef,
29+
'refactor-tool': refactorToolRef,
30+
'retrieval-tool': retrievalToolRef,
31+
'refined-question': refinedQuestionRef,
32+
'spec-practice': specPracticeRef
33+
};
34+
35+
const ref = refs[section];
36+
if (ref && ref.current) {
37+
ref.current.scrollIntoView({ behavior: 'smooth' });
38+
}
39+
}, 100);
4040
};
4141

4242
return (
@@ -50,10 +50,10 @@ export const AIFriendlyArchitecture = () => {
5050
<ArchitectureFlow onClickSection={scrollToSection}/>
5151
</div>
5252

53-
{/* 统一领域语言 */}
53+
{/* 领域语言/知识 */}
5454
<div ref={domainLanguageRef} className="mt-12">
5555
<div className="section-header">
56-
<h2 className="section-title bg-purple-700">统一领域语言</h2>
56+
<h2 className="section-title bg-purple-700">领域语言/知识</h2>
5757
<p className="text-slate-600">构建统一的语言，使团队和 AI 都能理解的标准术语</p>
5858
</div>
5959

@@ -84,11 +84,11 @@ export const AIFriendlyArchitecture = () => {
8484
<span>AgileBenefitController - 挑选重点</span>
8585
</li>
8686
<li className="flex items-start">
87-
<span className="text-green-500 mr-2">✓</span>
87+
<span className="text-green-600 mr-2">✓</span>
8888
<span>WenXiangLingDongHuiLi - 拼音全称</span>
8989
</li>
9090
<li className="flex items-start">
91-
<span className="text-green-500 mr-2">✓</span>
91+
<span className="text-green-600 mr-2">✓</span>
9292
<span>WXLDHL - 拼音首字母</span>
9393
</li>
9494
</ul>
@@ -103,26 +103,26 @@ export const AIFriendlyArchitecture = () => {
103103
<path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"></path>
104104
</svg>
105105
</div>
106-
<h3 className="text-xl font-semibold mb-2">领域驱动设计 (DDD)</h3>
107-
<p className="text-slate-600 mb-4">围绕业务领域概念构建代码，创建开发人员和利益相关者之间的共享语言</p>
106+
<h3 className="text-xl font-semibold mb-2">领域特定语言</h3>
107+
<p className="text-slate-600 mb-4">围绕业务领域概念构建代码，创建开发人员和利益相关者之间的共享语言（详细见：<a href="https://ide.unitmesh.cc/composer/workspace">AutoDev 工作区领域词典</a>）</p>
108108

109109
<div className="bg-slate-100 p-4 rounded-lg">
110110
<h4 className="font-medium mb-2">领域语言的好处</h4>
111111
<ul className="space-y-2">
112112
<li className="flex items-start">
113-
<span className="text-green-500 mr-2">•</span>
113+
<span className="text-green-600 mr-2">•</span>
114114
<span>减少翻译成本：业务人员和开发人员使用相同的术语</span>
115115
</li>
116116
<li className="flex items-start">
117-
<span className="text-green-500 mr-2">•</span>
117+
<span className="text-green-600 mr-2">•</span>
118118
<span>提高代码可读性：代码直接反映业务概念</span>
119119
</li>
120120
<li className="flex items-start">
121-
<span className="text-green-500 mr-2">•</span>
121+
<span className="text-green-600 mr-2">•</span>
122122
<span>增强 AI 理解：AI 能更好地理解领域特定的术语和概念</span>
123123
</li>
124124
<li className="flex items-start">
125-
<span className="text-green-500 mr-2">•</span>
125+
<span className="text-green-600 mr-2">•</span>
126126
<span>降低维护成本：新团队成员更容易理解代码</span>
127127
</li>
128128
</ul>
@@ -135,7 +135,7 @@ export const AIFriendlyArchitecture = () => {
135135
<div ref={plannerRef} className="mt-12">
136136
<div className="section-header">
137137
<h2 className="section-title bg-orange-500">智能任务规划</h2>
138-
<p className="text-slate-600">将需求转化为可执行任务的智能系统</p>
138+
<p className="text-slate-600">将需求转化为可执行任务的智能系统，（详细见：<a href="https://ide.unitmesh.cc/composer/planner">AutoDev Planner</a>）</p>
139139
</div>
140140

141141
<div className="card">
@@ -238,7 +238,7 @@ export const AIFriendlyArchitecture = () => {
238238
<div className="grid-2">
239239
<div className="card">
240240
<div className="flex items-center mb-4">
241-
<div className="bg-red-500 text-white p-2 rounded-full mr-3">
241+
<div className="bg-red-500 icon-circle mr-3">
242242
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none"
243243
stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
244244
<polyline points="16 18 22 12 16 6"></polyline>
@@ -250,7 +250,7 @@ export const AIFriendlyArchitecture = () => {
250250

251251
<div className="code-block">
252252
<CodeBlock language="java" title="传统代码风格示例">
253-
{`@RestController
253+
{`@RestController
254254
@RequestMapping("/api")
255255
public class Ctrl {
256256
@Autowired
@@ -278,8 +278,8 @@ public class Ctrl {
278278
</div>
279279

280280
<div className="card">
281-
<div className="flex items-center mb-4">
282-
<div className="bg-green-600 text-white p-2 rounded-full mr-3">
281+
<div className="flex items-center mb-2">
282+
<div className="bg-green-600 icon-circle mr-3">
283283
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none"
284284
stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
285285
<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path>
@@ -293,7 +293,7 @@ public class Ctrl {
293293
</div>
294294
<div className="code-block">
295295
<CodeBlock language="java" title="AI 友好代码风格示例">
296-
{`@RestController
296+
{`@RestController
297297
@RequestMapping("/api/users")
298298
public class UserController {
299299
private final UserService userService;
@@ -311,21 +311,11 @@ public class UserController {
311311
public UserResponse getUserById(@PathVariable Long id) {
312312
return userService.getUserById(id);
313313
}
314-
315-
/**
316-
* 创建新用户
317-
* @param request 用户创建请求
318-
* @return 创建的用户信息
319-
*/
320-
@PostMapping
321-
public UserResponse createUser(@RequestBody CreateUserRequest request) {
322-
return userService.createUser(request);
323-
}
324314
}`}
325315
</CodeBlock>
326316
</div>
327317

328-
<div className="mt-4 text-green-500">
318+
<div className="mt-4 text-green-600">
329319
<p className="text-sm">✓ 完整的类名和方法名</p>
330320
<p className="text-sm">✓ 清晰的注释说明功能</p>
331321
<p className="text-sm">✓ 语义化的 API 路径</p>
@@ -371,7 +361,7 @@ public class UserController {
371361
<h5 className="font-medium mb-2">已有代码</h5>
372362
<div className="code-block">
373363
<CodeBlock language="java" title="已有代码示例">
374-
{`@RestController
364+
{`@RestController
375365
@RequestMapping("/blog")
376366
public class BlogController {
377367
BlogService blogService;
@@ -394,14 +384,14 @@ public class BlogController {
394384
<h5 className="font-medium mb-2">AI 生成的代码</h5>
395385
<div className="code-block">
396386
<CodeBlock language="java" title="AI 生成的代码示例">
397-
{`@ApiOperation(value = "Delete Blog by id")
387+
{`@ApiOperation(value = "Delete Blog by id")
398388
@DeleteMapping("/{id}")
399389
public void deleteBlog(@PathVariable Long id) {
400390
blogService.deleteBlogById(id);
401391
}`}
402392
</CodeBlock>
403393

404-
<div className="mt-4 text-green-500">
394+
<div className="mt-4 text-green-600">
405395
<p className="text-sm">✓ 遵循已有的命名规范</p>
406396
<p className="text-sm">✓ 添加了适当的注解</p>
407397
<p className="text-sm">✓ 保持了一致的代码风格</p>
@@ -502,7 +492,7 @@ public void deleteBlog(@PathVariable Long id) {
502492
<h5 className="font-medium mb-2 text-red-500">重构前</h5>
503493
<div className="code-block">
504494
<CodeBlock language="java" title="重构前代码示例">
505-
{`public void prc(List<T> l, int f) {
495+
{`public void prc(List<T> l, int f) {
506496
for (int i = 0; i < l.size(); i++) {
507497
if (l.get(i).getF() > f) {
508498
l.get(i).setS(true);
@@ -522,7 +512,7 @@ public void deleteBlog(@PathVariable Long id) {
522512
<h5 className="font-medium mb-2 text-green-600">重构后</h5>
523513
<div className="code-block">
524514
<CodeBlock language="java" title="重构后代码示例">
525-
{`/**
515+
{`/**
526516
* 处理项目列表，根据阈值设置状态
527517
* @param items 要处理的项目列表
528518
* @param threshold 状态判断阈值
@@ -653,10 +643,10 @@ private void markItemAsNotSelected(Item item) {
653643
<div className="mt-2 p-3 bg-pink-100 rounded">
654644
<p className="text-sm font-medium mb-1">检索结果:</p>
655645
<ul className="text-sm space-y-1">
656-
<li>• AuthenticationService.java - 用户认证服务</li>
657-
<li>• SecurityConfig.java - 安全配置</li>
658-
<li>• UserController.java - 登录接口</li>
659-
<li>• AuthUtils.java - 认证工具类</li>
646+
<li>AuthenticationService.java - 用户认证服务</li>
647+
<li>SecurityConfig.java - 安全配置</li>
648+
<li>UserController.java - 登录接口</li>
649+
<li>AuthUtils.java - 认证工具类</li>
660650
</ul>
661651
</div>
662652
</div>
@@ -724,15 +714,15 @@ private void markItemAsNotSelected(Item item) {
724714
<h4 className="font-medium mb-2">精炼示例</h4>
725715
<ul className="space-y-2">
726716
<li className="flex items-start">
727-
<span className="text-green-500 mr-2">✓</span>
717+
<span className="text-green-600 mr-2">✓</span>
728718
<span>"实现用户注册功能，包含邮箱验证、密码强度检查，并与现有的用户认证系统集成"</span>
729719
</li>
730720
<li className="flex items-start">
731-
<span className="text-green-500 mr-2">✓</span>
721+
<span className="text-green-600 mr-2">✓</span>
732722
<span>"添加 JWT 基于的登录功能，使用现有的 UserService，并遵循 RESTful API 设计原则"</span>
733723
</li>
734724
<li className="flex items-start">
735-
<span className="text-green-500 mr-2">✓</span>
725+
<span className="text-green-600 mr-2">✓</span>
736726
<span>"优化数据库查询性能，当前查询耗时超过 2 秒，目标是降低到 500ms 以内"</span>
737727
</li>
738728
</ul>
@@ -741,21 +731,20 @@ private void markItemAsNotSelected(Item item) {
741731
</div>
742732

743733
<div className="mt-12 p-6 bg-blue-50 rounded-lg">
744-
<h4 className="font-semibold mb-4 text-center">结合 DDD 的问题精炼</h4>
734+
<h4 className="font-semibold mb-4 text-center">结合 DDD 的问题上下文丰富</h4>
745735
<p className="text-slate-700 mb-4">
746-
领域驱动设计（DDD）提供了一种强大的方法来精炼问题，通过使用统一的领域语言和明确的业务概念，
747-
使问题描述更加准确和有意义。
736+
通过使用统一的领域语言和明确的业务概念，使问题描述更加准确和有意义，详细见：<a href="https://ide.unitmesh.cc/composer/workspace">AutoDev 工作区领域词典</a>
748737
</p>
749738

750739
<div className="bg-white p-4 rounded-lg">
751-
<h5 className="font-medium mb-2">DDD 问题精炼示例</h5>
740+
<h5 className="font-medium mb-2">上下文丰富示例</h5>
752741
<div className="grid-2">
753742
<div>
754743
<p className="text-sm font-medium text-slate-700">原始问题:</p>
755744
<p className="p-2 bg-slate-100 rounded">"添加购物车功能"</p>
756745
</div>
757746
<div>
758-
<p className="text-sm font-medium text-slate-700">精炼后:</p>
747+
<p className="text-sm font-medium text-slate-700">丰富后:</p>
759748
<p className="p-2 bg-blue-100 rounded">
760749
"实现购物车聚合根，包含添加商品项、更新数量、计算总价等功能。
761750
购物车需要与用户和商品目录领域对象交互，并实现购物车持久化。"
@@ -767,7 +756,6 @@ private void markItemAsNotSelected(Item item) {
767756
</div>
768757
</div>
769758

770-
{/* 团队编码规范 */}
771759
<div ref={specPracticeRef} className="mt-12">
772760
<div className="section-header">
773761
<h2 className="section-title bg-purple-700">团队编码规范</h2>
@@ -840,55 +828,55 @@ private void markItemAsNotSelected(Item item) {
840828
<span className="text-purple-700 mr-2">•</span>
841829
<span>明确边界：定义清晰的模块边界和接口</span>
842830
</li>
831+
<li className="flex items-start">
832+
<span className="text-purple-700 mr-2">•</span>
833+
<span>概念一致：保持代码的一致性和可读性</span>
834+
</li>
843835
</ul>
844836
</div>
845837
</div>
846838
</div>
847839

848840
<div className="mt-12 p-6 bg-purple-50 rounded-lg">
849-
<h4 className="font-semibold mb-4 text-center">Project Rule 实践</h4>
841+
<h2 className="font-semibold mb-4 text-center">Project Rule 实践</h2>
850842
<p className="text-slate-700 mb-4">
851-
在 AI IDE 中添加自定义的 Project Rule，是一种非常有效的控制代码生成的方法。
843+
在 AI IDE 中添加自定义的 <a href="https://ide.unitmesh.cc/composer/project-rule">Project Rule</a>，是一种非常有效的控制代码生成的方法。
852844
通过明确定义项目的规范和约束，可以指导 AI 生成符合团队实践的代码。
853845
</p>
854846

855847
<div className="bg-white p-4 rounded-lg">
856-
<h5 className="font-medium mb-2">Project Rule 示例</h5>
857848
<div className="code-block">
858-
<CodeBlock language="json" title="Project Rule 示例">
859-
{`// Project Rules for AI Code Generation
860-
{
861-
"naming": {
862-
"classes": "PascalCase",
863-
"methods": "camelCase",
864-
"variables": "camelCase",
865-
"constants": "UPPER_SNAKE_CASE"
866-
},
867-
"architecture": {
868-
"layers": ["controller", "service", "repository"],
869-
"patterns": ["dependency-injection", "repository-pattern"]
870-
},
871-
"patterns": ["dependency-injection", "repository-pattern"]
872-
"documentation": {
873-
"methods": "required",
874-
"classes": "required",
875-
"publicApi": "detailed"
876-
},
877-
"testing": {
878-
"coverage": "minimum-80-percent",
879-
"unitTests": "required"
880-
}
881-
}`}
882-
</CodeBlock>
849+
<CodeBlock language="markdown" title="AutoDev Project Dir 示例">
850+
{`## Project Rule Dir
851+
prompts/rules/
852+
├── controller.md
853+
├── service.md
854+
├── repository.md
855+
├── rpc.md
856+
└── README.md # 该文件会被默认始终加载！！
857+
`}
858+
</CodeBlock>
859+
<CodeBlock language="markdown" title="AutoDev Project Rule 示例">
860+
{`# Spring Boot Controller 开发规范
861+
## 基本原则
862+
1. 保持Controller简洁，只处理HTTP请求和响应
863+
2. 业务逻辑应放在Service层
864+
3. 每个Controller方法应只做一件事
865+
866+
## 命名规范
867+
- 类名: \`XxxController\` (如 \`UserController\`)
868+
- 路径: 使用复数形式 (\`/api/users\`)
869+
`}
870+
</CodeBlock>
883871
</div>
884872
</div>
885873
</div>
886874
</div>
887875
</div>
888876
</div>
889877
);
890-
};
878+
};
891879

892880
<BrowserOnly>
893-
{() => <AIFriendlyArchitecture />}
881+
{() => <AIFriendlyArchitecture/>}
894882
</BrowserOnly>

0 commit comments

Comments
 (0)