@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/09-templates/08-component-knowledge.md

@@ -0,0 +1,272 @@
+# 组件知识：{组件名称}
+
+> **版本**: v1.0
+> **模板来源**: 组件开发最佳实践、API 设计标准、开发者文档规范
+> **适用范围**: 内部组件库、第三方组件集成、SDK 文档
+> **生成模式**: 组件识别 → 接口定义 → 使用示例 → 最佳实践
+
+---
+
+## 1. 组件概述
+
+### 1.1 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| 组件名称 | |
+| 组件类型 | UI 组件/工具库/SDK/服务组件 |
+| 版本 | v1.0.0 |
+| 维护团队 | |
+| 技术栈 | |
+
+### 1.2 组件描述
+
+> 用简洁的语言描述组件的功能和用途
+
+### 1.3 核心特性
+
+- [ ] 特性 1
+- [ ] 特性 2
+- [ ] 特性 3
+
+### 1.4 安装方式
+
+```bash
+# npm
+npm install @org/component-name
+
+# Maven
+<dependency>
+  <groupId>com.org</groupId>
+  <artifactId>component-name</artifactId>
+  <version>1.0.0</version>
+</dependency>
+
+# pip
+pip install component-name
+```
+
+---
+
+## 2. 快速开始
+
+### 2.1 最小示例
+
+```javascript
+// JavaScript/TypeScript
+import { Component } from '@org/component-name';
+
+const instance = new Component({
+  // 配置项
+});
+
+await instance.method();
+```
+
+### 2.2 基础用法
+
+```javascript
+// 更完整的使用示例
+```
+
+---
+
+## 3. 接口定义
+
+### 3.1 API 概览
+
+| 方法/类 | 类型 | 说明 |
+|--------|------|------|
+| `Component` | Class | 主组件类 |
+| `methodA` | Method | 方法 A |
+| `methodB` | Method | 方法 B |
+
+### 3.2 构造函数
+
+```typescript
+interface ComponentOptions {
+  /** 配置项 1 */
+  option1: string;
+  /** 配置项 2 */
+  option2?: number;  // 可选
+}
+
+constructor(options: ComponentOptions)
+```
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| options | ComponentOptions | 是 | - | 配置选项 |
+
+### 3.3 方法详情
+
+#### methodA(params)
+
+```typescript
+methodA(params: MethodAParams): Promise<MethodAResult>
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| param1 | string | 是 | 参数 1 |
+| param2 | number | 否 | 参数 2 |
+
+**返回值**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| result | string | 结果 |
+| success | boolean | 是否成功 |
+
+---
+
+## 4. 使用示例
+
+### 4.1 场景示例
+
+#### 场景 1: {场景名称}
+
+```javascript
+// 示例代码
+```
+
+#### 场景 2: {场景名称}
+
+```javascript
+// 示例代码
+```
+
+### 4.2 多语言示例
+
+**Node.js**:
+```javascript
+// Node.js 示例
+```
+
+**Python**:
+```python
+# Python 示例
+```
+
+**Java**:
+```java
+// Java 示例
+```
+
+---
+
+## 5. 配置项
+
+### 5.1 配置列表
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|-------|------|--------|------|
+| `timeout` | number | 30000 | 超时时间 (ms) |
+| `retry` | number | 3 | 重试次数 |
+| `debug` | boolean | false | 调试模式 |
+
+### 5.2 环境变量
+
+| 变量名 | 说明 | 示例 |
+|-------|------|------|
+| `COMPONENT_API_KEY` | API 密钥 | |
+| `COMPONENT_ENDPOINT` | 服务端点 | |
+
+---
+
+## 6. 错误处理
+
+### 6.1 错误类型
+
+```typescript
+enum ErrorCode {
+  INVALID_PARAMS = 'INVALID_PARAMS',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  TIMEOUT = 'TIMEOUT',
+  INTERNAL_ERROR = 'INTERNAL_ERROR'
+}
+```
+
+| 错误码 | 说明 | 处理方式 |
+|-------|------|---------|
+| INVALID_PARAMS | 参数无效 | 检查输入参数 |
+| NETWORK_ERROR | 网络错误 | 重试或检查网络 |
+| TIMEOUT | 请求超时 | 增加超时时间或重试 |
+
+### 6.2 错误示例
+
+```javascript
+try {
+  await component.method();
+} catch (error) {
+  if (error.code === 'TIMEOUT') {
+    // 处理超时
+  }
+}
+```
+
+---
+
+## 7. 最佳实践
+
+### 7.1 推荐用法
+
+```javascript
+// 推荐的使用方式
+```
+
+### 7.2 反模式
+
+```javascript
+// 不推荐的用法，说明原因
+```
+
+### 7.3 性能优化
+
+| 优化点 | 说明 | 效果 |
+|-------|------|------|
+| 连接池 | 复用连接 | 减少延迟 |
+| 缓存 | 缓存结果 | 减少调用 |
+
+---
+
+## 8. 测试
+
+### 8.1 单元测试
+
+```javascript
+describe('Component', () => {
+  it('should work', async () => {
+    // 测试代码
+  });
+});
+```
+
+### 8.2 集成测试
+
+```javascript
+// 集成测试代码
+```
+
+---
+
+## 9. 版本历史
+
+| 版本 | 日期 | 变更说明 |
+|------|------|---------|
+| v1.0.0 | | 初始版本 |
+| v1.1.0 | | 新增功能 |
+
+---
+
+## 10. 常见问题
+
+### Q: {问题}
+
+A: {回答}
+
+---
+
+**维护者**: 组件团队
+**进化分区**: 自由区
+**关联文档**: `knowledge/09-templates/02-api-design.md`, `knowledge/09-templates/11-best-practices.md`

package/knowledge/09-templates/09-best-practices.md

@@ -0,0 +1,218 @@
+# 最佳实践：{主题/领域}
+
+> **版本**: v1.0
+> **模板来源**: 业界最佳实践、团队经验总结、模式与方法论
+> **适用范围**: 开发实践、架构设计、运维规范、团队协作
+> **生成模式**: 实践收集 → 实践分类 → 实践定义 → 持续优化
+
+---
+
+## 1. 实践概述
+
+### 1.1 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| 实践主题 | |
+| 适用领域 | 开发/架构/运维/管理 |
+| 实践来源 | 团队总结/业界参考 |
+| 成熟度 | 探索中/验证中/已验证 |
+
+### 1.2 实践目标
+
+> 描述这些最佳实践要解决的问题或达成的目标
+
+### 1.3 适用场景
+
+- [ ] 场景 1
+- [ ] 场景 2
+
+### 1.4 不适用场景
+
+- [ ] 场景 1（原因）
+- [ ] 场景 2（原因）
+
+---
+
+## 2. 实践分类
+
+```
+最佳实践
+├── 设计实践
+│   ├── 架构设计
+│   ├── 接口设计
+│   └── 数据设计
+├── 开发实践
+│   ├── 编码规范
+│   ├── 代码审查
+│   └── 测试实践
+├── 运维实践
+│   ├── 部署实践
+│   ├── 监控实践
+│   └── 应急实践
+└── 协作实践
+    ├── 沟通实践
+    └── 文档实践
+```
+
+---
+
+## 3. 实践详情
+
+### 3.1 实践模板
+
+#### 实践 {编号}: {实践名称}
+
+| 属性 | 值 |
+|------|-----|
+| 实践 ID | PRACTICE-{编号} |
+| 实践名称 | |
+| 所属分类 | |
+| 优先级 | P0/P1/P2 |
+| 成熟度 | 探索中/验证中/已验证 |
+
+**实践描述**：
+> 详细描述实践内容
+
+**问题/痛点**：
+- 问题 1
+- 问题 2
+
+**解决方案**：
+1. 步骤 1
+2. 步骤 2
+3. 步骤 3
+
+**实施示例**：
+```code
+// 示例代码或配置
+```
+
+**效果收益**：
+| 指标 | 改进前 | 改进后 | 提升 |
+|------|-------|-------|------|
+| | | | |
+
+**注意事项**：
+- 注意 1
+- 注意 2
+
+**参考资料**：
+- [参考文档](url)
+
+---
+
+### 3.2 实践列表
+
+| 实践 ID | 实践名称 | 分类 | 优先级 | 成熟度 |
+|--------|---------|------|--------|-------|
+| PRACTICE-001 | | 设计 | P0 | 已验证 |
+| PRACTICE-002 | | 开发 | P1 | 验证中 |
+
+---
+
+## 4. 对比分析
+
+### 4.1 方案对比
+
+| 方案 | 优点 | 缺点 | 适用场景 |
+|------|------|------|---------|
+| 方案 A | | | |
+| 方案 B | | | |
+
+### 4.2 决策矩阵
+
+| 评估维度 | 权重 | 方案 A | 方案 B |
+|---------|------|-------|-------|
+| 性能 | 30% | | |
+| 可维护性 | 30% | | |
+| 成本 | 20% | | |
+| 风险 | 20% | | |
+
+---
+
+## 5. 实施指南
+
+### 5.1 实施步骤
+
+```mermaid
+flowchart LR
+    A[准备] --> B[试点]
+    B --> C[推广]
+    C --> D[优化]
+```
+
+### 5.2 检查清单
+
+**实施前检查**：
+- [ ] 条件 1 已满足
+- [ ] 条件 2 已满足
+
+**实施后检查**：
+- [ ] 结果 1 已验证
+- [ ] 结果 2 已验证
+
+### 5.3 工具支持
+
+| 工具 | 用途 | 配置说明 |
+|------|------|---------|
+| | | |
+
+---
+
+## 6. 案例研究
+
+### 6.1 成功案例
+
+**背景**：
+
+**挑战**：
+
+**解决方案**：
+
+**结果**：
+
+### 6.2 失败案例
+
+**背景**：
+
+**问题**：
+
+**教训**：
+
+---
+
+## 7. 实践演进
+
+### 7.1 版本历史
+
+| 版本 | 日期 | 变更内容 |
+|------|------|---------|
+| v1.0 | | 初始版本 |
+
+### 7.2 待优化项
+
+| 优化项 | 说明 | 优先级 |
+|-------|------|--------|
+| | | P0/P1/P2 |
+
+---
+
+## 8. 附录
+
+### 8.1 术语表
+
+| 术语 | 定义 |
+|------|------|
+| | |
+
+### 8.2 参考资料
+
+- [业界最佳实践](url)
+- [相关论文](url)
+
+---
+
+**维护者**: 实践总结团队
+**进化分区**: 自由区
+**关联文档**: `knowledge/09-templates/10-component-knowledge.md`, `knowledge/09-templates/12-domain-model.md`

package/knowledge/{environment/middleware-knowledge.md → 09-templates/10-middleware-knowledge.md}

@@ -31,6 +31,13 @@
 | search-engine | 搜索引擎 |
 | vector-store | 向量存储 |
 | object-storage | 对象存储 |
+| llm | 大语言模型服务 |
+| messaging | 消息服务 |
+| storage | 存储服务 |
+| payment | 支付服务 |
+| auth | 认证服务 |
+| notification | 通知服务 |
+| external-api | 外部 API 服务 |
 
 ---
 
@@ -101,6 +108,34 @@ Client client = Client.builder()
 
 ---
 
+## 接口定义（外部服务专用）
+
+> 本章节仅适用于 external-api、llm、auth、payment、notification 等外部服务类型。
+
+### Facade 接口
+
+```java
+// 接口定义
+public interface XxxFacade {
+    Result method(Request request);
+}
+```
+
+### 主要方法
+
+| 方法名 | 参数 | 返回值 | 说明 |
+|--------|------|--------|------|
+| {method} | {params} | {return} | {description} |
+
+### 服务端点配置
+
+| 配置项 | 说明 | 示例 |
+|--------|------|------|
+| {SERVICE}_ENDPOINT | 服务地址 | https://api.example.com |
+| {SERVICE}_TIMEOUT | 超时时间(ms) | 5000 |
+
+---
+
 ## 最佳实践
 
 1. 使用连接池管理连接，避免每次请求创建新连接
@@ -132,6 +167,73 @@ Client client = Client.builder()
 
 ---
 
+## 依赖信息
+
+### Maven 依赖
+
+| GroupId | ArtifactId | 版本 | 说明 |
+|---------|-----------|------|------|
+| {group} | {artifact} | {version} | {description} |
+
+### npm 依赖
+
+| 包名 | 版本 | 说明 |
+|------|------|------|
+| {package} | {version} | {description} |
+
+### pip 依赖
+
+| 包名 | 版本 | 说明 |
+|------|------|------|
+| {package} | {version} | {description} |
+
+---
+
+## 配置项详解
+
+| 配置项 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| {key} | {type} | 是/否 | {default} | {description} |
+
+### 配置示例
+
+```properties
+# application.properties
+{name}.host=${NAME}_HOST
+{name}.port=${NAME}_PORT
+{name}.database=${NAME}_DATABASE
+```
+
+```yaml
+# application.yml
+{name}:
+  host: ${NAME_HOST}
+  port: ${NAME_PORT}
+  database: ${NAME_DATABASE}
+```
+
+---
+
+## 实际使用代码
+
+### 项目中的使用示例
+
+**来源**: `{file_path}:{line_number}`
+
+```java
+// 实际项目代码示例
+{actual_code_snippet}
+```
+
+### 客户端类
+
+| 类名 | 路径 | 说明 |
+|------|------|------|
+| {ClientClass} | {path} | 客户端实现 |
+| {ConfigClass} | {path} | 配置类 |
+
+---
+
 ## 示例：MySQL 中间件知识
 
 ```markdown
@@ -227,6 +329,9 @@ mysqladmin ping -h ${MYSQL_HOST} -u ${MYSQL_USER} -p${MYSQL_PASSWORD}
 - [ ] 基本信息章节完整，包含名称、类型、知识版本
 - [ ] 环境变量章节包含必需变量和可选变量表格
 - [ ] 连接代码模板包含项目使用的主要语言
+- [ ] **依赖信息章节完整，包含 Maven/npm/pip 依赖**
+- [ ] **配置项详解章节包含配置项表格和示例**
+- [ ] **实际使用代码章节包含项目中的真实代码示例**
 - [ ] 最佳实践列表不为空
 - [ ] 反模式清单包含风险和替代方案
 
@@ -234,4 +339,4 @@ mysqladmin ping -h ${MYSQL_HOST} -u ${MYSQL_USER} -p${MYSQL_PASSWORD}
 
 **维护者**: AutoSpec 团队
 **进化分区**: 🟡 受控区
-**关联文档**: `knowledge/environment/template-registry.md`
+**关联文档**: `knowledge/06-environment/00-template-registry.md`