@chongyan/autospec 1.0.1

package/plugins/commands/env-template.md

@@ -0,0 +1,223 @@
+---
+description: 查看和管理环境知识模板
+---
+
+# AutoSpec Env Template — 模板管理
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 执行指令
+
+### 无参数：显示模板列表
+
+**【强制】** 读取模板注册表，显示可用模板：
+
+```
+📋 环境知识模板列表
+
+名称           来源文件                                    输出位置
+----           ----                                        ----
+middleware     middleware-knowledge.md                     env-knowledge/middleware/{name}.md
+component      component-knowledge.md                      component-lib/components/{name}/component.md
+infrastructure middleware-knowledge.md                     env-knowledge/infrastructure/{name}.md
+
+使用 /autospec:env-template --show <name> 查看模板详情
+```
+
+### 参数 --show <name>：显示模板详情
+
+**【强制】** 读取并展示指定模板的详细信息：
+
+```
+📋 模板详情: middleware
+
+来源: knowledge/environment/middleware-knowledge.md
+输出: .autospec/environment/env-knowledge/middleware/{name}.md
+
+必填章节:
+  - 基本信息
+  - 环境变量
+  - 连接代码模板
+
+可选章节:
+  - 最佳实践
+  - 反模式清单
+  - 健康检查
+
+类型枚举:
+  - relational-database: 关系型数据库
+  - document-database: 文档数据库
+  - cache: 缓存
+  - message-queue: 消息队列
+  - search-engine: 搜索引擎
+  - vector-store: 向量存储
+  - object-storage: 对象存储
+
+示例:
+  查看 middleware-knowledge.md 中的 MySQL 示例
+```
+
+### 参数 --validate：校验知识文件模板合规
+
+**【强制】** 校验现有知识文件是否符合模板规范：
+
+```
+🔍 校验知识文件模板合规
+
+模板加载:
+  ✅ template-registry.md
+  ✅ middleware-knowledge.md
+  ✅ component-knowledge.md
+
+中间件知识:
+  ✅ mysql.md
+     - 必填章节完整
+     - 类型有效: relational-database
+     - 环境变量表格完整
+  ✅ redis.md
+     - 必填章节完整
+     - 类型有效: cache
+  ⚠️  kafka.md
+     - 缺少可选章节: 连接代码模板
+     - 类型有效: message-queue
+
+组件知识:
+  ✅ auth/component.md
+     - 必填章节完整
+     - 类型有效: service-component
+  ✅ payment/component.md
+     - 必填章节完整
+     - 类型有效: service-component
+
+总计: 5 文件, 4 完全合规, 1 有警告
+```
+
+### 参数 --sync：同步模板注册表
+
+**【强制】** 将框架模板同步到本地：
+
+```
+🔄 同步模板注册表
+
+复制: knowledge/environment/template-registry.md
+      → .autospec/environment/template-registry.md
+
+缓存模板:
+  - middleware-knowledge.md
+  - component-knowledge.md
+  - detection-patterns.yaml
+
+✅ 同步完成
+```
+
+### 参数 --example <name>：显示模板示例
+
+**【强制】** 显示指定模板的完整示例：
+
+```
+📝 模板示例: middleware (MySQL)
+
+# MySQL 中间件知识
+
+## 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| 名称 | mysql |
+| 类型 | relational-database |
+| 默认端口 | 3306 |
+| 知识版本 | v1.0 |
+
+## 环境变量
+
+### 必需变量
+
+| 变量名 | 说明 | 示例 |
+|--------|------|------|
+| MYSQL_HOST | 数据库主机地址 | db.example.com |
+| MYSQL_DATABASE | 数据库名称 | myapp_db |
+| MYSQL_USER | 用户名 | app_user |
+| MYSQL_PASSWORD | 密码 | - |
+
+### 可选变量
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| MYSQL_PORT | 3306 | 数据库端口 |
+| MYSQL_POOL_SIZE | 10 | 连接池大小 |
+
+## 连接代码模板
+
+### Node.js
+
+```javascript
+const mysql = require('mysql2/promise');
+const pool = mysql.createPool({
+  host: process.env.MYSQL_HOST,
+  port: process.env.MYSQL_PORT || 3306,
+  database: process.env.MYSQL_DATABASE,
+  user: process.env.MYSQL_USER,
+  password: process.env.MYSQL_PASSWORD,
+});
+```
+
+### Python
+
+```python
+import pymysql
+pool = pymysql.connect(
+    host=os.environ['MYSQL_HOST'],
+    port=int(os.environ.get('MYSQL_PORT', 3306)),
+    database=os.environ['MYSQL_DATABASE'],
+    user=os.environ['MYSQL_USER'],
+    password=os.environ['MYSQL_PASSWORD'],
+)
+```
+
+## 最佳实践
+
+1. 使用连接池，不要在每次请求时创建新连接
+2. 设置合理的超时时间，避免连接泄漏
+3. 敏感信息使用环境变量，不要硬编码
+
+## 反模式清单
+
+| 反模式 | 风险 | 替代方案 |
+|--------|------|----------|
+| 直接拼接SQL字符串 | SQL注入风险 | 使用参数化查询 |
+| 在代码中硬编码密码 | 安全风险 | 使用环境变量 |
+
+## 健康检查
+
+```bash
+mysqladmin ping -h ${MYSQL_HOST} -u ${MYSQL_USER} -p${MYSQL_PASSWORD}
+```
+```
+
+---
+
+## 产出物
+
+- 模板列表展示
+- 模板详情展示
+- 模板合规校验报告
+- 同步后的模板缓存
+- 模板示例展示
+
+---
+
+## 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| 无参数 | 显示模板列表 |
+| `--show <name>` | 显示指定模板详情 |
+| `--validate` | 校验知识文件模板合规 |
+| `--sync` | 同步模板注册表到本地 |
+| `--example <name>` | 显示模板示例 |

package/plugins/commands/env-update.md

@@ -0,0 +1,264 @@
+---
+description: 将本地环境知识变更提交到知识源（Git/在线文档平台/本地文件）
+---
+
+# AutoSpec Env Update — 知识更新提交
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 用法
+
+```
+/autospec:env-update [options]
+```
+
+### Options
+
+| 参数 | 说明 |
+|------|------|
+| `--dry-run` | 仅预览变更，不执行提交 |
+| `--source <id>` | 指定更新的知识源（默认：全部） |
+| `--push` | 同时推送到远程（git/在线文档） |
+| `--message <msg>` | 提交消息 |
+| `--force` | 跳过确认（危险操作仍需确认） |
+
+---
+
+## 前置检查
+
+**【强制】** 读取知识来源配置：
+
+1. 读取 `.autospec/environment/knowledge-source.json`
+2. 如不存在，提示用户先执行 `/autospec:env-sync` 导入知识库
+3. 解析配置的知识源列表
+
+---
+
+## 执行指令
+
+### Step 1: 检测变更
+
+对比本地知识与知识源：
+
+1. **遍历知识源配置**
+   - Git 源：对比 commit hash
+   - 在线文档源：对比文档更新时间
+   - 本地源：对比文件 hash
+
+2. **识别变更类型**
+   - 新增：本地有，源中无
+   - 修改：内容不一致
+   - 删除：本地无，源中有
+
+3. **生成变更列表**
+
+### Step 2: 分类变更
+
+**自动变更（无需确认）**：
+- 新增知识文件
+- 非核心知识修改（测试用例、最佳实践等）
+
+**需确认变更（重要操作）**：
+- 架构设计文档修改
+- 数据库设计（表结构、索引）修改
+- 接口契约修改
+- 规范文档修改
+- 指南文档修改
+
+**危险变更（强制确认）**：
+- 删除操作
+
+### Step 3: 生成变更报告
+
+展示变更详情：
+
+```
+📝 变更报告
+
+知识源: org-design-templates (Git)
+================================
+
+自动变更:
+  + design-knowledge/product/order-system.md (新增)
+  ~ test-knowledge/test-designs/order-test.md (修改)
+
+需确认变更:
+  ⚠️  design-knowledge/architecture/order-service.md (修改)
+      - 新增订单取消接口
+      - 修改订单状态流转图
+  ⚠️  design-knowledge/database/order-db.md (修改)
+      - 新增 order_cancel_log 表
+      - 修改 order 表索引
+
+危险变更:
+  ❌ business-knowledge/rules.md (删除规则 BR-05)
+
+知识源: org-docs (在线文档)
+================================
+  ~ standards/coding-style.md (修改)
+
+总计: 6 项变更, 2 项需确认, 1 项危险操作
+```
+
+### Step 4: 确认变更
+
+**自动变更**：直接执行
+
+**需确认变更**：
+```
+⚠️  以下变更需要确认：
+
+1. design-knowledge/architecture/order-service.md
+   是否提交？[Y/n]
+
+2. design-knowledge/database/order-db.md
+   是否提交？[Y/n]
+```
+
+**危险变更**：
+```
+❌ 危险操作，必须确认：
+
+1. 删除 business-knowledge/rules.md 中的 BR-05
+   此操作不可逆，是否继续？[y/N]
+```
+
+### Step 5: 执行更新
+
+根据知识源类型执行更新：
+
+#### Git 源
+
+```bash
+# 克隆临时目录
+git clone --depth 1 {url} /tmp/autospec-update-{id}
+
+# 复制变更文件
+cp -r .autospec/environment/{path}/* /tmp/autospec-update-{id}/{target}/
+
+# 提交变更
+cd /tmp/autospec-update-{id}
+git add .
+git commit -m "{message}
+
+Co-Authored-By: AutoSpec <autospec@autospec.dev>"
+git push origin {branch}
+
+# 记录 commit hash
+```
+
+#### 在线文档源
+
+```bash
+# 使用在线文档 MCP 工具更新文档
+# skylark_doc_update
+```
+
+#### 本地源
+
+```bash
+# 直接复制文件
+cp -r .autospec/environment/{path}/* {target}/
+```
+
+### Step 6: 更新 knowledge-source.json
+
+更新同步时间和版本信息：
+
+```json
+{
+  "sources": [
+    {
+      "id": "org-design-templates",
+      "lastSync": "2026-03-26T12:00:00Z",
+      "commitHash": "def456"
+    }
+  ]
+}
+```
+
+---
+
+## 产出物
+
+- 更新后的知识源文件
+- 更新的 `knowledge-source.json`
+- 变更报告 `.autospec/runtime/env-update-report.json`
+
+---
+
+## 输出结果
+
+```
+✅ 知识更新提交完成
+
+知识源: org-design-templates
+  推送: git@github.com:org/design-templates.git
+  分支: main
+  提交: def456
+
+变更统计:
+  新增: 2 文件
+  修改: 3 文件
+  删除: 1 文件
+
+知识源: org-yuque-docs
+  更新: standards/coding-style.md (doc_id: 12345)
+
+下一步:
+  1. 检查远程仓库确认变更
+  2. 通知团队成员拉取最新知识
+```
+
+---
+
+## 错误处理
+
+### 推送失败
+
+```
+❌ Git 推送失败
+
+原因: 远程有新的提交
+解决:
+  1. 先拉取远程变更: git pull
+  2. 解决冲突后重新执行: /autospec:env-update --push
+```
+
+### 权限不足
+
+```
+❌ 权限不足
+
+原因: 无写入权限
+解决:
+  1. 检查 Git SSH Key 配置
+  2. 检查在线文档 API Token 权限
+```
+
+### 冲突处理
+
+```
+⚠️  检测到冲突
+
+文件: design-knowledge/architecture/order-service.md
+本地版本: 新增订单取消接口
+远程版本: 新增订单退款接口
+
+选择处理方式:
+  1. 保留本地版本
+  2. 保留远程版本
+  3. 手动合并
+```
+
+---
+
+**维护者**: AutoSpec 团队
+**进化分区**: 受控区
+**关联文档**: `knowledge/environment/README.md`, `plugins/commands/autospec:env-sync.md`

package/plugins/commands/env-validate.md

@@ -0,0 +1,176 @@
+---
+description: 验证环境知识配置的完整性和有效性
+---
+
+# AutoSpec Env Validate — 配置校验
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 执行指令
+
+### Step 1: 加载模板规范
+
+**【强制】** 读取模板注册表和模板文件：
+
+1. **读取模板注册表**
+   - 读取 `knowledge/environment/template-registry.md`
+   - 获取模板清单、类型枚举、必填章节定义
+
+2. **加载模板文件**
+   - 中间件模板：`knowledge/environment/middleware-knowledge.md`
+   - 组件模板：`knowledge/environment/component-knowledge.md`
+
+### Step 2: 扫描知识文件
+
+扫描 `.autospec/environment/` 下所有 Markdown 文件：
+
+- `env-knowledge/middleware/*.md`
+- `env-knowledge/infrastructure/*.md`
+- `component-lib/components/*/component.md`
+
+### Step 3: 执行校验
+
+**【强制】** 对每个文件执行以下校验：
+
+#### 3.1 基础校验
+
+- Markdown 格式校验
+- 章节标题格式检查
+- 表格格式检查
+
+#### 3.2 模板规范校验
+
+**中间件文件校验**（参考 middleware-knowledge.md）：
+
+| 检查项 | 说明 |
+|--------|------|
+| 章节完整性 | 必须包含：基本信息、环境变量、连接代码模板 |
+| 基本信息表格 | 必须包含：名称、类型 |
+| 类型枚举 | 类型必须在预定义枚举中 |
+| 环境变量表格 | 必须包含变量名、说明列 |
+
+**组件文件校验**（参考 component-knowledge.md）：
+
+| 检查项 | 说明 |
+|--------|------|
+| 章节完整性 | 必须包含：基本信息、接口定义、使用示例 |
+| 基本信息表格 | 必须包含：名称、类型、版本 |
+| 类型枚举 | 类型必须在预定义枚举中 |
+| 接口定义 | 必须包含方法名和说明 |
+
+#### 3.3 跨文件一致性校验
+
+- 环境变量引用一致性
+- 组件依赖完整性
+- 最佳实践引用有效性
+
+### Step 4: 输出结果
+
+```
+🔍 验证环境知识配置...
+
+模板加载:
+  ✅ template-registry.md
+  ✅ middleware-knowledge.md
+  ✅ component-knowledge.md
+
+总计: {total} 个文件
+通过: {passed} ✅
+失败: {failed} ❌
+警告: {warnings} ⚠️
+
+详细结果:
+
+中间件知识:
+  ✅ env-knowledge/middleware/mysql.md
+     - 章节完整
+     - 类型有效: relational-database
+  ✅ env-knowledge/middleware/redis.md
+     - 章节完整
+     - 类型有效: cache
+  ❌ env-knowledge/middleware/kafka.md
+     - 缺少必填章节「连接代码模板」
+     - 类型无效: queue (应为 message-queue)
+
+组件知识:
+  ✅ component-lib/components/auth/component.md
+     - 章节完整
+     - 类型有效: service-component
+  ⚠️  component-lib/components/axios/component.md
+     - 缺少可选章节「使用检查清单」
+     - 缺少可选章节「最佳实践」
+```
+
+### Step 5: AI 修复建议（可选）
+
+对校验失败的项目，提供修复建议：
+
+1. **分析错误原因**
+   - 章节缺失原因
+   - 类型不匹配原因
+
+2. **提供具体修复方案**
+   - 补全缺失章节
+   - 修正类型值
+
+3. **执行修复**
+   - 如用户确认，AI 执行修复
+
+---
+
+## 校验规则参考
+
+### 错误级别（必须修复）
+
+| 错误码 | 说明 |
+|--------|------|
+| MISSING_REQUIRED_SECTION | 缺少必填章节 |
+| MISSING_REQUIRED_FIELD | 缺少必填字段 |
+| INVALID_TYPE | 类型不在预定义枚举中 |
+| INVALID_TABLE_FORMAT | 表格格式错误 |
+
+### 警告级别（建议修复）
+
+| 警告码 | 说明 |
+|--------|------|
+| MISSING_OPTIONAL_SECTION | 缺少可选章节 |
+| MISSING_OPTIONAL_FIELD | 缺少可选字段 |
+| EMPTY_TABLE | 表格为空 |
+| INCONSISTENT_NAMING | 命名不一致 |
+
+---
+
+## 产出物
+
+- 校验报告
+- 修复建议（如有错误）
+- 修复后的文件（如用户确认）
+
+---
+
+## 输出结果示例
+
+```
+✅ 环境知识校验完成
+
+校验统计:
+  中间件: 5 文件
+    ✅ 合规: 4
+    ❌ 不合规: 1
+  组件: 3 文件
+    ✅ 合规: 2
+    ⚠️  有警告: 1
+
+修复建议:
+  kafka.md:
+    1. 添加「连接代码模板」章节
+    2. 修改类型: queue → message-queue
+
+是否执行修复？[Y/n]
+```