@mison/ag-kit-cn 2.0.1

package/.agent/skills/deployment-procedures/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: deployment-procedures
+description: 生产环境部署原则与决策（Deployment procedures）。安全部署工作流、回滚策略与验证。强调思考而非背脚本。
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# 部署规程
+
+> 生产环境发布的部署原则与决策逻辑。
+> **学习如何思考（THINK）**，而非死记硬背脚本。
+
+---
+
+## ⚠️ 如何使用此技能
+
+此技能传授的是**部署原则**，不是可盲目复制的脚本。
+
+- 每次部署都有差异
+- 理解每一步背后的原因
+- 根据平台实际情况调整流程
+
+---
+
+## 1. 平台选择
+
+### 决策树
+
+```
+What are you deploying?
+│
+├── Static site / JAMstack
+│   └── Vercel, Netlify, Cloudflare Pages
+│
+├── Simple web app
+│   ├── Managed → Railway, Render, Fly.io
+│   └── Control → VPS + PM2/Docker
+│
+├── Microservices
+│   └── Container orchestration
+│
+└── Serverless
+    └── Edge functions, Lambda
+```
+
+### 不同平台有不同规程
+
+| 平台 | 部署方式 |
+| ---- | -------- |
+| **Vercel/Netlify** | Git push（代码推送）自动部署 |
+| **Railway/Render** | Git push 或 CLI |
+| **VPS + PM2** | SSH + 手动步骤 |
+| **Docker** | 镜像推送 + 编排 |
+| **Kubernetes** | kubectl apply |
+
+---
+
+## 2. 部署前原则
+
+### 四大验证类别
+
+| 类别 | 检查项 |
+| ---- | ------ |
+| **代码质量** | 测试通过、Lint 清理完成、已评审 |
+| **构建（Build）** | 生产构建成功、无告警 |
+| **环境** | 环境变量已设置、凭据已更新 |
+| **安全性** | 已备份、回滚方案就绪 |
+
+### 部署前检查清单
+
+- [ ] 所有测试通过
+- [ ] 代码已评审并批准
+- [ ] 生产构建成功
+- [ ] 环境变量已核验
+- [ ] 数据库迁移已就绪（如有）
+- [ ] 回滚方案已记录
+- [ ] 已通知团队
+- [ ] 监控已就绪
+
+---
+
+## 3. 部署工作流原则
+
+### 5 阶段流程
+
+```
+1. PREPARE
+   └── Verify code, build, env vars
+
+2. BACKUP
+   └── Save current state before changing
+
+3. DEPLOY
+   └── Execute with monitoring open
+
+4. VERIFY
+   └── Health check, logs, key flows
+
+5. CONFIRM or ROLLBACK
+   └── All good? Confirm. Issues? Rollback.
+```
+
+### 阶段原则
+
+| 阶段 | 原则 |
+| ---- | ---- |
+| **准备** | 绝不部署未经测试的代码 |
+| **备份** | 没有备份就无法回滚 |
+| **部署** | 观察过程，不要中途走开 |
+| **验证** | 宁可怀疑，务必验证 |
+| **确认** | 随时准备触发回滚 |
+
+---
+
+## 4. 部署后验证
+
+### 验证内容
+
+| 检查项 | 为什么要查 |
+| ------ | ---------- |
+| **健康端点（Health）** | 确认服务正常运行 |
+| **错误日志** | 确认无新增错误 |
+| **核心业务流** | 确保关键功能正常 |
+| **性能** | 响应时间可接受 |
+
+### 验证时间窗口
+
+- **首个 5 分钟**：主动监控
+- **15 分钟**：确认稳定
+- **1 小时**：最终验证
+- **次日**：复审指标
+
+---
+
+## 5. 回滚原则
+
+### 何时回滚
+
+| 现象 | 行动建议 |
+| ---- | -------- |
+| 服务宕机 | 立即回滚 |
+| 严重错误 | 回滚 |
+| 性能下降超过 50% | 考虑回滚 |
+| 细微问题 | 可快速修复则向前修复 |
+
+### 不同平台的回滚策略
+
+| 平台 | 回滚方式 |
+| ---- | -------- |
+| **Vercel/Netlify** | 重新部署之前的提交 |
+| **Railway/Render** | 控制面板回滚 |
+| **VPS + PM2** | 还原备份并重启 |
+| **Docker** | 使用之前的镜像标签 |
+| **K8s** | kubectl rollout undo |
+
+### 回滚原则
+
+1. **速度优于完美**：先回滚，再调试
+2. **不要复合错误**：只做一次回滚，不叠加变更
+3. **沟通**：告知团队发生了什么
+4. **复盘（Post-mortem）**：稳定后再追因
+
+---
+
+## 6. 零停机部署
+
+### 核心策略
+
+| 策略 | 工作原理 |
+| ---- | -------- |
+| **滚动更新（Rolling）** | 逐个替换实例 |
+| **蓝绿部署（Blue-Green）** | 在不同环境间切换流量 |
+| **金丝雀发布（Canary）** | 逐步转移流量 |
+
+### 选择原则
+
+| 场景 | 对应策略 |
+| ---- | -------- |
+| 标准发布 | 滚动更新 |
+| 高风险变更 | 蓝绿部署（易回滚） |
+| 需要验证 | 金丝雀发布（真实流量验证） |
+
+---
+
+## 7. 应急响应程序
+
+### 服务宕机优先级
+
+1. **评估（Assess）**：现象是什么？
+2. **快速修复**：若原因不明，先重启
+3. **回滚**：重启无效则立即回滚
+4. **调查**：稳定后深入分析
+
+### 调查顺序
+
+| 检查项 | 常见问题 |
+| ------ | -------- |
+| **日志** | 错误、异常信息 |
+| **系统资源** | 磁盘空间满、内存不足 |
+| **网络** | DNS 问题、防火墙拦截 |
+| **依赖项** | 数据库异常、API 故障 |
+
+---
+
+## 8. 反模式
+
+| ❌ 禁止 | ✅ 推荐 |
+| -------------- | ------------ |
+| 周五部署 | 周初部署 |
+| 仓促部署 | 遵循流程 |
+| 跳过预发布环境（Staging） | 始终先测试 |
+| 部署前不备份 | 部署前必备份 |
+| 部署完立即走开 | 监控至少 15 分钟 |
+| 同时进行多项变更 | 每次只做一项 |
+
+---
+
+## 9. 决策检查清单
+
+在部署之前：
+
+- [ ] **是否选择了适用于该平台的规程？**
+- [ ] **备份策略是否就绪？**
+- [ ] **回滚计划是否记录？**
+- [ ] **监控是否已配置？**
+- [ ] **是否已通知团队？**
+- [ ] **是否预留了监控时间？**
+
+---
+
+## 10. 最佳实践
+
+1. **小步快跑**：高频小规模部署
+2. **功能开关（Feature flags）**：高风险变更用开关控制
+3. **自动化**：重复步骤自动化
+4. **记录**：记录每次部署过程
+5. **复审**：问题发生后复盘
+6. **演练回滚**：在需要前先验证回滚
+
+---
+
+> **谨记：** 部署本身有风险，降低风险靠充分准备而非速度。

package/.agent/skills/doc.md

@@ -0,0 +1,177 @@
+# Antigravity 技能
+
+> **Antigravity Kit 中 Skills（技能）的创建与使用指南**
+
+---
+
+## 📋 介绍
+
+虽然 Antigravity 的基础模型（如 Gemini）是强大的通用模型，但它们并不了解你的项目上下文或团队标准。把所有规则或工具都加载到智能体上下文会导致“工具膨胀”，成本上升、延迟增加并引发混淆。
+
+**Antigravity Skills（技能）** 通过 **Progressive Disclosure（渐进式披露）** 解决这一问题。技能是专门的知识包，默认处于非激活状态，只有在你的具体请求与技能描述匹配时，相关信息才会加载进智能体上下文。
+
+---
+
+## 📁 结构与范围
+
+技能以目录为单位组织，你可以按需求定义范围：
+
+| 范围 | 路径 | 说明 |
+|---------|-----------|-------|
+| **Workspace（工作区）** | `<workspace-root>/.agent/skills/` | 仅作用于当前项目 |
+
+### 技能目录结构
+
+```
+my-skill/
+├── SKILL.md      # (Required) Metadata & instructions
+├── scripts/      # (Optional) Python or Bash scripts
+├── references/   # (Optional) Text, documentation, templates
+└── assets/       # (Optional) Images or logos
+```
+
+---
+
+## 🔍 示例 1：代码审查技能（Code Review Skill）
+
+这是一个仅包含指令的技能，只需要创建 `SKILL.md`。
+
+### 步骤 1：创建目录
+
+```bash
+mkdir -p .agent/skills/code-review
+```
+
+### 步骤 2：创建 SKILL.md
+
+```markdown
+---
+name: code-review
+description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality.
+---
+
+# Code Review Skill
+
+When reviewing code, follow these steps:
+
+## Review checklist
+
+1. **Correctness**: Does the code do what it's supposed to?
+2. **Edge cases**: Are error conditions handled?
+3. **Style**: Does it follow project conventions?
+4. **Performance**: Are there obvious inefficiencies?
+
+## How to provide feedback
+
+- Be specific about what needs to change
+- Explain why, not just what
+- Suggest alternatives when possible
+```
+
+> **注意：** `SKILL.md` 顶部包含元数据（name、description），其后是指令内容。Agent（智能体）只会先读元数据，只有需要时才加载完整指令。
+
+### 试用
+
+创建文件 `demo_bad_code.py`：
+
+```python
+import time
+
+def get_user_data(users, id):
+    # Find user by ID
+    for u in users:
+        if u['id'] == id:
+            return u
+    return None
+
+def process_payments(items):
+    total = 0
+    for i in items:
+        # Calculate tax
+        tax = i['price'] * 0.1
+        total = total + i['price'] + tax
+        time.sleep(0.1)  # Simulate slow network call
+    return total
+
+def run_batch():
+    users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+    items = [{'price': 10}, {'price': 20}, {'price': 100}]
+    
+    u = get_user_data(users, 3)
+    print("User found: " + u['name'])  # Will crash if None
+    
+    print("Total: " + str(process_payments(items)))
+
+if __name__ == "__main__":
+    run_batch()
+```
+
+**提示词（Prompt）**：`审查 @demo_bad_code.py 文件`
+
+Agent（智能体）会自动识别 `code-review` 技能，加载信息并按指令执行。
+
+---
+
+## 📄 示例 2：许可证头技能（License Header Skill）
+
+此技能使用 `resources/`（或 `references/`）目录下的参考文件。
+
+### 步骤 1：创建目录
+
+```bash
+mkdir -p .agent/skills/license-header-adder/resources
+```
+
+### 步骤 2：创建模板文件
+
+**`.agent/skills/license-header-adder/resources/HEADER.txt`**：
+
+```
+/*
+ * Copyright (c) 2026 YOUR_COMPANY_NAME LLC.
+ * All rights reserved.
+ * This code is proprietary and confidential.
+ */
+```
+
+### 步骤 3：创建 SKILL.md
+
+**`.agent/skills/license-header-adder/SKILL.md`**：
+
+```markdown
+---
+name: license-header-adder
+description: Adds the standard corporate license header to new source files.
+---
+
+# License Header Adder
+
+This skill ensures that all new source files have the correct copyright header.
+
+## Instructions
+
+1. **Read the Template**: Read the content of `resources/HEADER.txt`.
+2. **Apply to File**: When creating a new file, prepend this exact content.
+3. **Adapt Syntax**: 
+   - For C-style languages (Java, TS), keep the `/* */` block.
+   - For Python/Shell, convert to `#` comments.
+```
+
+### 试用
+
+**提示词（Prompt）**：`创建一个名为 data_processor.py 的 Python 脚本，输出 'Hello World'.`
+
+Agent（智能体）将读取模板，将注释转换为 Python 格式，并自动添加到文件头部。
+
+---
+
+## 🎯 结论
+
+通过创建 Skills（技能），你已经把通用 AI 模型变成了面向项目的专家：
+
+- ✅ 体系化最佳实践（best practices）
+- ✅ 遵循代码评审规则
+- ✅ 自动添加许可证头
+- ✅ Agent（智能体）自动了解团队工作方式
+
+无需反复提醒 AI “记得加 license” 或 “修正提交格式”，现在 Agent 会自动执行。

package/.agent/skills/documentation-templates/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: documentation-templates
+description: 文档模板与结构指南（Documentation templates）。README、API 文档、代码注释与 AI 友好型文档。
+allowed-tools: Read, Glob, Grep
+---
+
+# 文档模板
+
+> 常见文档类型的模板与结构指南。
+
+---
+
+## 1. README 结构
+
+### 核心章节（优先级顺序）
+
+| 章节 | 用途 |
+|---------|---------|
+| **标题 + 单句描述** | 这是什么项目？ |
+| **快速开始** | 5 分钟内能跑起来 |
+| **功能特性** | 能做什么 |
+| **配置指南** | 如何自定义 |
+| **API 参考** | 指向详细文档 |
+| **贡献指南** | 如何参与 |
+| **开源协议** | 法律条款 |
+
+### README 模板
+
+```markdown
+# Project Name
+
+Brief one-line description.
+
+## Quick Start
+
+[Minimum steps to run]
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 3000 |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Architecture](./docs/architecture.md)
+
+## License
+
+MIT
+```
+
+---
+
+## 2. API 文档结构
+
+### 接口模板
+
+```markdown
+## GET /users/:id
+
+Get a user by ID.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | User ID |
+
+**Response:**
+- 200: User object
+- 404: User not found
+
+**Example:**
+[Request and response example]
+```
+
+---
+
+## 3. 代码注释指南
+
+### JSDoc/TSDoc 模板
+
+```typescript
+/**
+ * Brief description of what the function does.
+ * 
+ * @param paramName - Description of parameter
+ * @returns Description of return value
+ * @throws ErrorType - When this error occurs
+ * 
+ * @example
+ * const result = functionName(input);
+ */
+```
+
+### 何时编写注释
+
+| ✅ 应当注释 | ❌ 不应注释 |
+|-----------|-----------------|
+| 解释“为什么”（业务逻辑） | 解释“是什么”（显而易见的逻辑） |
+| 复杂算法 | 每一行 |
+| 非直观行为 | 自解释代码 |
+| API 契约 | 实现细节 |
+
+---
+
+## 4. 变更日志模板（Keep a Changelog）
+
+```markdown
+# Changelog
+
+## [Unreleased]
+### Added
+- New feature
+
+## [1.0.0] - 2025-01-01
+### Added
+- Initial release
+### Changed
+- Updated dependency
+### Fixed
+- Bug fix
+```
+
+---
+
+## 5. 架构决策记录（ADR）
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted / Deprecated / Superseded
+
+## Context
+Why are we making this decision?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+```
+
+---
+
+## 6. AI 友好型文档（2025）
+
+### llms.txt 模板
+
+面向 AI 爬虫与代理（agents）：
+
+```markdown
+# Project Name
+> One-line objective.
+
+## Core Files
+- [src/index.ts]: Main entry
+- [src/api/]: API routes
+- [docs/]: Documentation
+
+## Key Concepts
+- Concept 1: Brief explanation
+- Concept 2: Brief explanation
+```
+
+### 适配 MCP 的文档规范
+
+用于 RAG（检索增强生成）索引：
+- 清晰的 H1-H3 标题层级
+- 数据结构的 JSON/YAML 示例
+- 用 Mermaid 图表描述流程
+- 章节内容自包含
+
+---
+
+## 7. 结构原则
+
+| 原则 | 目的 |
+|-----------|-----|
+| **可扫描** | 使用标题、列表、表格 |
+| **示例优先** | 先展示，再解释 |
+| **渐进展开** | 简单 → 复杂 |
+| **保持更新** | 过期即误导 |
+
+---
+
+> **提醒：** 模板只是起点，请根据项目需求调整。