iac-code 0.1.0__py3-none-any.whl

iac_code/services/token_counter.py

@@ -0,0 +1,76 @@
+"""Token counting utilities with model-aware encoding selection."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from loguru import logger
+
+_MESSAGE_OVERHEAD = 4
+_TOOL_USE_OVERHEAD = 10
+
+# Map model name prefixes to tiktoken encoding names.
+_MODEL_ENCODING_MAP = {
+    "gpt-4o": "o200k_base",
+    "gpt-4": "cl100k_base",
+    "gpt-5": "o200k_base",
+    "claude": "cl100k_base",
+    "qwen": "cl100k_base",
+    "qwq": "cl100k_base",
+    "o3": "o200k_base",
+    "o4": "o200k_base",
+}
+_DEFAULT_ENCODING = "cl100k_base"
+
+
+def _select_encoding(model: str) -> str:
+    model_lower = model.lower()
+    for prefix, encoding in _MODEL_ENCODING_MAP.items():
+        if model_lower.startswith(prefix):
+            return encoding
+    return _DEFAULT_ENCODING
+
+
+class TokenCounter:
+    """Count tokens using tiktoken with model-aware encoding selection."""
+
+    def __init__(self, model: str = "") -> None:
+        self._encoder = None
+        encoding_name = _select_encoding(model)
+        try:
+            import tiktoken
+
+            self._encoder = tiktoken.get_encoding(encoding_name)
+        except Exception:
+            logger.debug("tiktoken not available, using estimation fallback")
+
+    def count_text(self, text: str) -> int:
+        if not text:
+            return 0
+        if self._encoder:
+            return len(self._encoder.encode(text))
+        return max(1, len(text) // 4)
+
+    def count_message(self, message: dict[str, Any]) -> int:
+        count = _MESSAGE_OVERHEAD
+        content = message.get("content", "")
+        if isinstance(content, str):
+            count += self.count_text(content)
+        elif isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict):
+                    block_type = block.get("type", "")
+                    if block_type == "text":
+                        count += self.count_text(block.get("text", ""))
+                    elif block_type == "tool_use":
+                        count += _TOOL_USE_OVERHEAD
+                        count += self.count_text(block.get("name", ""))
+                        count += self.count_text(json.dumps(block.get("input", {})))
+                    elif block_type == "tool_result":
+                        count += self.count_text(block.get("content", ""))
+                        count += _TOOL_USE_OVERHEAD
+        return count
+
+    def count_messages(self, messages: list[dict[str, Any]]) -> int:
+        return sum(self.count_message(m) for m in messages)

iac_code/skills/__init__.py

@@ -0,0 +1 @@
+"""Skill system — extensible prompt injection framework."""

iac_code/skills/bundled/__init__.py

@@ -0,0 +1,94 @@
+"""Built-in skill registration system."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from iac_code.skills.frontmatter import SkillFrontmatter
+from iac_code.skills.skill_definition import SkillContext, SkillDefinition
+from iac_code.types.skill_source import SkillSource
+
+# Global bundled skill list
+_bundled_skills: list[SkillDefinition] = []
+
+
+def register_bundled_skill(
+    *,
+    name: str,
+    description: str,
+    prompt: str | None = None,
+    get_prompt: Callable | None = None,
+    when_to_use: str = "",
+    argument_hint: str = "",
+    arguments: list[str] | None = None,
+    allowed_tools: list[str] | None = None,
+    model: str = "inherit",
+    effort: str = "",
+    user_invocable: bool = True,
+    context: str = "inline",
+    agent: str = "general-purpose",
+    skill_root: str = "",
+) -> None:
+    """Register a bundled skill."""
+    frontmatter = SkillFrontmatter(
+        name=name,
+        description=description,
+        when_to_use=when_to_use,
+        argument_hint=argument_hint,
+        arguments=arguments or [],
+        allowed_tools=allowed_tools or [],
+        model=model,
+        effort=effort,
+        user_invocable=user_invocable,
+        context=context,
+        agent=agent,
+    )
+
+    # Create prompt provider
+    # Only use a custom provider for get_prompt functions.
+    # Plain prompt strings go through the standard renderer so that
+    # skill_root injection and other pipeline steps apply automatically.
+    provider = _FunctionPromptProvider(get_prompt) if get_prompt is not None else None
+
+    skill = SkillDefinition(
+        name=name,
+        description=description,
+        frontmatter=frontmatter,
+        content=prompt or "",
+        source=SkillSource.BUNDLED,
+        skill_root=skill_root,
+        content_length=len(prompt or ""),
+        _prompt_provider=provider,
+    )
+
+    _bundled_skills.append(skill)
+
+
+def get_bundled_skills() -> list[SkillDefinition]:
+    """Return all registered bundled skills."""
+    return list(_bundled_skills)
+
+
+def init_bundled_skills() -> None:
+    """Initialize all bundled skills. Called once at startup."""
+    # Guard against double initialization
+    if _bundled_skills:
+        return
+
+    from iac_code.skills.bundled.simplify import register_simplify_skill
+
+    register_simplify_skill()
+
+    from iac_code.skills.bundled.iac_aliyun import register_iac_aliyun_skill
+
+    register_iac_aliyun_skill()
+
+
+class _FunctionPromptProvider:
+    """Prompt provider that delegates to an async function."""
+
+    def __init__(self, func: Callable) -> None:
+        self._func = func
+
+    async def get_prompt(self, args: str, context: SkillContext) -> str:
+        return await self._func(args, context)

iac_code/skills/bundled/iac_aliyun/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: iac-aliyun
+description: 阿里云 IaC 模板生成、解释、完善与部署
+when_to_use: 当用户涉及云资源创建、模板生成、模板解释、部署等 IaC 相关操作时
+user_invocable: false
+---
+
+# 阿里云 IaC 技能
+
+阿里云 IaC 模板生成、解释、完善与部署。帮助用户通过 ROS/Terraform 模板管理云资源。
+
+## 地域
+
+所有 API 调用都需要地域，按以下优先级确定：
+1. **用户指定**（如"在北京创建"）→ 使用用户指定的地域
+2. **工具默认地域**（用户未指定时）→ aliyun_api 工具的 region_id 参数描述中会显示默认地域（如 `Defaults to 'cn-hangzhou'`），使用该默认值并告知用户
+3. **均无**（工具参数无默认值且用户未指定）→ 请用户指定目标地域，或使用 /auth 命令设置默认地域
+
+确定后，所有 API 调用统一使用该地域。
+
+**注意**：ROS 的模板、资源类型、模块是全局资源，任意地域查询结果相同。用户说"查所有地域的模板"时，只需查一个地域即可，不要遍历地域列表。
+
+## 场景处理
+
+### 生成模板
+- **资源需求**（用户指定资源如"创建 VPC+ECS"）→ 直接生成模板
+- **应用部署**（用户想部署某个应用但不清楚该应用是什么）→ 先 aliyun_doc_search 搜索，搜不到再 web_fetch 搜索
+  - 如果部署地域属于中国，那么对 Docker、PyPI、npm、Maven、Go 等需配置国内镜像源，否则可能有网络问题等
+- **业务需求**（用户描述业务场景）→ 提供 1-3 个方案含优缺点，用户选择后生成
+- 默认 ROS 模板，用户指定 Terraform 时生成 Terraform 文件。**ROS 与 Terraform 共用同一套校验/部署链路（均通过 aliyun_api / ros_stack）**，不要建议用户用 `terraform init/apply` 等本地 CLI 替代
+- 对用户未指定的参数直接使用合理默认值，不反复询问
+- **库存相关属性必须参数化为 Parameters**，不写死具体值（见「参数化规则」）
+
+### 解释/完善模板
+- 分析用户提供的模板，解释结构和功能
+- 按用户需求在已有模板上迭代完善
+
+### 部署/更新/删除
+- 所有写操作必须先向用户确认，删除/更新操作使用 ⚠️ 警告措辞
+- 简洁询问是否部署，不展示工具调用细节
+
+### 询价
+- 查询部署的预估价格
+
+## 参数化规则
+
+生成模板时，以下属性**必须**定义为 Parameters（部署前通过 API 查询确定实际值）：
+
+| 产品 | 须参数化的属性 |
+|------|---------------|
+| ECS | ZoneId, InstanceType, ImageId, SystemDiskCategory, DataDiskCategory |
+| RDS | ZoneId, DBInstanceClass, DBInstanceStorageType |
+| Redis | ZoneId, InstanceClass |
+| SLB/ALB | ZoneId |
+
+以下属性**不需要**参数化，直接使用合理默认值：
+- 网络：VPC CIDR、VSwitch CIDR
+- 命名：实例名称、资源名称
+- 安全：安全组规则
+- 配置：备份策略、监控设置、标签
+
+## 资源命名
+
+资源名称应体现业务用途，**不要**包含工具名（如 terraform、ros）：
+- 好：`my-vpc`、`web-server`、`app-db`
+- 差：`vpc-terraform`、`ros-ecs`、`tf-vswitch`
+
+## 模板生成流程
+
+1. 分析需求，确定资源列表
+2. 查阅 [references/cloud-products/](references/cloud-products/) 下对应产品文件，了解选型策略和库存相关属性
+3. 生成模板（库存相关属性按「参数化规则」定义为 Parameters，所有 Parameters 必须添加 AssociationProperty）并写入文件
+   - **Terraform**：生成 `.tf` 等文件后，必须先用 `tf2ros.py` 打包为 ROS Terraform 类型模板（用法见 [references/terraform-template.md](references/terraform-template.md) 的「与 ROS 集成」节），后续步骤校验/部署的都是这份打包后的 `.yml`
+4. 调用 aliyun_api(product="ros", action="ValidateTemplate", params={"TemplateURL": <模板文件路径>}) 校验
+5. 校验失败 → 分析错误 → 修复 → 重试（最多 5 轮）
+6. 校验通过 → 展示模板 → 询问是否部署（**ROS 与 Terraform 一致**，禁止用 `terraform init/apply` 等本地 CLI 步骤替代部署确认）
+
+> **TemplateURL 支持本地文件路径**：aliyun_api（product=ros）和 ros_stack 中，TemplateURL 可传本地文件路径（如 `/tmp/template.yml`），工具会自动读取文件内容。避免将大模板内容直接作为参数传递。
+
+## 部署流程
+
+### 可用性查询
+
+当用户确认执行以下操作时，**必须先查询可用性**：
+
+| 操作 | 查询范围 |
+|------|----------|
+| CreateStack | 全量查询所有库存相关 Parameters |
+| ContinueCreateStack | 查询失败资源相关的 Parameters |
+| UpdateStack | 查询变更涉及的 Parameters |
+| CreateStackInstances | 按每个目标地域分别查询 |
+| UpdateStackInstances | 按每个目标地域查询变更涉及的 Parameters |
+
+查询步骤：
+1. 解析模板 Parameters，识别库存相关参数及对应产品
+2. 调用各产品可用性 API（具体 API 见 [references/cloud-products/](references/cloud-products/) 各产品文件的「可用性查询」节）
+3. 找出公共可用区（所有资源都有库存的可用区）
+4. 按 cloud-products 中的推荐规格优先匹配，不可用时选最接近的替代
+5. 得到选定参数。**若操作为 CreateStack 或 UpdateStack，接「部署前询价」；其他操作（ContinueCreateStack 等）直接展示选定结果并请求用户确认。**
+
+### 有模板的询价
+
+1. 如果没有查询可用性，按照「可用性查询」进行
+2. 调用 aliyun_api(product="ros", action="GetTemplateEstimateCost", params={...}) 询价。**模板参数必须按 `Parameters.<N>.ParameterKey` / `Parameters.<N>.ParameterValue` 平铺**（下标从 1 起），不要把参数名作为顶层 key 传入。**ROS 原生模板和 Terraform 类型模板调用同一 API，传参格式完全一致**——`ParameterKey` 即模板中的 Parameters 名（ROS）或 variable 名（Terraform，通常蛇形命名，如 `zone_id`）。示例（参数平铺通用规则见「aliyun_api 参数约定」）：
+   ```python
+   aliyun_api(
+       product="ros",
+       action="GetTemplateEstimateCost",
+       params={
+           "TemplateURL": "/tmp/ros-ecs-nginx-template.yml",
+           "Parameters.1.ParameterKey": "zone_id",
+           "Parameters.1.ParameterValue": "cn-hangzhou-k",
+           "Parameters.2.ParameterKey": "instance_type",
+           "Parameters.2.ParameterValue": "ecs.g7.large",
+           "Parameters.3.ParameterKey": "image_id",
+           "Parameters.3.ParameterValue": "centos_stream_9_x64_20G_alibase_20260414.vhd",
+           "Parameters.4.ParameterKey": "system_disk_category",
+           "Parameters.4.ParameterValue": "cloud_essd",
+       },
+       region_id="cn-hangzhou",
+   )
+   ```
+3. 合并展示「选定参数 + 预估费用」（格式见「询价展示格式」），一次性请求用户确认
+4. **UpdateStack 特别提示**：展示时附加 `此为更新后模板的总费用预估，而非变更前后价差`
+5. 用户确认 → 进入「执行部署」；用户拒绝 → 终止并告知已取消部署
+
+**询价失败**：不阻塞部署。按如下格式展示后继续征求部署确认：
+```
+为您选定以下参数：
+- 可用区：cn-beijing-h
+- ECS 实例规格：ecs.g7.large (2c8g)
+- ...
+
+预估费用（按量付费）：
+- web-server (ECS ecs.g7.large): ¥xx/h
+- app-db (RDS mysql.n4.large.1): ¥xx/h
+- 其他（VPC / 安全组 / 交换机 等）: 免费
+合计: ¥xx/h
+
+⚠️ 询价失败: <错误简述>
+  常见原因: 部分资源类型不支持询价 / 账号询价权限缺失 / API 暂时异常
+
+确认部署？
+```
+6. 用户确认 → 将选定值作为 Parameters 传入部署操作
+
+无法找到公共可用区时，告知用户冲突详情，建议换规格系列或换地域。
+
+### 执行部署
+
+- 使用 ros_stack 工具执行 CreateStack/UpdateStack/ContinueCreateStack/DeleteStack，禁止用 Bash
+- CreateStack 必须传 `DisableRollback: true`
+
+## 参考文件
+
+| 文件 | 内容 |
+|------|------|
+| [references/template-parameters.md](references/template-parameters.md) | 模板参数规范：AssociationProperty、Label、分组（ROS/Terraform 共用） |
+| [references/cloud-products/](references/cloud-products/) | 云产品选型文件（ecs.md、rds.md、redis.md、slb.md、vpc.md、oss.md） |
+| [references/ros-template.md](references/ros-template.md) | ROS 原生模板最佳实践：RunCommand、嵌套栈、条件部署 |
+| [references/terraform-template.md](references/terraform-template.md) | Terraform 最佳实践：文件组织、变量、Data Source、ROS 集成 |
+
+## 资源和文档搜索
+
+- 不确定的资源属性或Schema：
+  - ROS → aliyun_api(product="ros", action="GetResourceType", params={"ResourceType": "<类型>"})
+  - Terraform → aliyun_api(product="IaCService", action="GetResourceType", style="ROA", method="GET", pathname="/resourceType/<类型>")
+- 不熟悉的资源类型/属性 → aliyun_doc_search（ROS 传 category_id=28850，Terraform 传 category_id=95817）
+- 想要了解应用部署方案、解决方案、云产品相关知识 -> aliyun_doc_search
+- 摘要不够 → web_fetch 获取完整文档
+
+## aliyun_api 参数约定
+
+**以下规则仅适用于 RPC 风格 API**（`style` 未传或传 `"RPC"`；ROA 风格用 JSON body/query，不受此约束）。
+
+调用 RPC API 时，**array、object 类参数需平铺为带数字下标的键**，工具不会自动展开。规则：
+
+- 下标从 `1` 起，依次递增
+- `array[string]` → `<Name>.<N>`
+- `array[object]` → `<Name>.<N>.<SubKey>`
+- 嵌套列表按同样规则继续展开
+- `object` → `<Name>.<SubKey>`
+
+## 错误处理
+
+### 校验失败
+分析错误原因 → 查 GetResourceType Schema（如需）→ 修复 → 重试（最多 5 轮）
+
+### 部署失败
+分析错误原因：
+- 权限/配额 → 告知用户处理
+- 模板/参数 → 修复后 ContinueCreateStack（不重新 CreateStack）

iac_code/skills/bundled/iac_aliyun/__init__.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+from iac_code.skills.bundled import register_bundled_skill
+
+SKILL_DIR = Path(__file__).parent
+
+
+def register_iac_aliyun_skill() -> None:
+    register_bundled_skill(
+        name="iac-aliyun",
+        description="阿里云 IaC 模板生成、解释、完善与部署",
+        prompt=(SKILL_DIR / "SKILL.md").read_text(),
+        when_to_use="当用户涉及云资源创建、模板生成、模板解释、部署等 IaC 相关操作时",
+        user_invocable=False,
+        skill_root=str(SKILL_DIR),
+    )

iac_code/skills/bundled/iac_aliyun/references/cloud-products/ecs.md

@@ -0,0 +1,167 @@
+# 阿里云 ECS 选型指南
+
+## 实例规格推荐策略
+
+### 规格族选择
+
+个人场景：
+- 成本优先: e，如果e实例没库存，自动使用性价比优先配置
+- 性价比优先：u1-/u2a-/u2i-
+- 性能优先：g9i/c9i/r9i
+
+非个人场景：
+- 价格优先配置: u1-/u2a-/u2i-
+- 性价比优先配置：u1-/u2a-/u2i-
+- 性能优先配置：g9i/c9i/r9i
+
+### vCPU / 内存确定原则
+
+- 确定内存CPU比：1:1, 1:2, 1:4, 1:8（基于大模型和预置素材判断）
+- 确定规格族列表：非个人用户不推荐e实例
+- 多款规格策略：
+    - 性价比优先配置：，
+        - 规格族选择：选用中低价位的规格族：e，u1-/u2a-/u2i-，9代规格族 -> 选用u
+        - 基于场景确定标准的内存和CPU大小
+    - 价格优先配置：
+        - 规格族选择：如果有比性价比优先规格族低的规格，则选定低价格的规格族，CPU 内存 不变
+        - 如果没有比性价比优先的规格族低的规格族：则降低 vCPU内存配置：`vCPU = min(2, Standard_vCPU / 2)`, `Mem =  min(2, Standard_Mem / 2)`
+    - 性能优先配置：
+        - 规格族选择：如果有更高性能的规格族，则选择更高性能规格族，对应CPU、内存不变
+        - 如果没有更高配置规格族，规格族使用性价比优先规格族，但是内存CPU 要升级配置：`vCPU =  2 * Standard_vCPU`, `Mem =  Standard_Mem * 2`
+
+### 场景化推荐表
+
+下表为内置场景模板，可直接套用；未明确匹配的场景，由大模型基于最相近场景推理。
+
+| 场景 | 子场景 | CPU:内存 | 云盘（系统盘/数据盘一致） | 成本优先 | 性价比优先 | 性能优先 | 推荐理由 |
+|------|--------|----------|---------------------------|----------|------------|----------|----------|
+| Web 应用服务 | 个人网站 | 1:2 | ESSD PL0 | 2c2g | 2c4g | 4c8g | 轻量级应用，重视成本控制，内存用于页面缓存 |
+| Web 应用服务 | 小程序 | 1:2 | ESSD PL0 | 2c2g | 2c4g | 4c8g | 并发适中，内存缓存 API 响应数据 |
+| Web 应用服务 | 企业官网 | 1:2 | ESSD AutoPL | 2c4g | 4c8g | 8c16g | 稳定性要求高，需要处理适度并发访问 |
+| Web 应用服务 | 后端服务 | 1:2 | ESSD PL0 | 2c4g | 4c8g | 8c16g | API 处理密集，需要并发处理能力和内存缓存 |
+| Web 应用服务 | 开发测试环境 | 1:2 | ESSD PL0 | 1c2g | 2c4g | 4c8g | 开发调试使用，成本敏感，配置够用即可 |
+| AI 与智能应用 | 大模型 / 深度学习训练 | 1:8 | ESSD AutoPL | 16c128g | 32c256g | 64c512g | 训练需要大内存存储模型参数和训练数据 |
+| AI 与智能应用 | AI 模型推理服务 | 1:4 | ESSD AutoPL | 4c16g | 8c32g | 16c64g | 推理需要内存加载模型，CPU 处理推理请求 |
+| AI 与智能应用 | 智能体平台部署 | 1:4 | ESSD AutoPL | 8c32g | 16c64g | 32c128g | 多服务运行，内存需求大，支持并发智能体 |
+| AI 与智能应用 | 智能体应用部署 | 1:4 | ESSD AutoPL | 4c16g | 8c32g | 16c64g | 应用运行时需要充足内存加载 AI 模型 |
+| 数据库服务 | MySQL / PostgreSQL | 1:4 | ESSD AutoPL | 4c16g | 8c32g | 16c64g | 关系型数据库需要大内存缓存数据页和索引 |
+| 数据库服务 | MongoDB / Cassandra | 1:8 | ESSD AutoPL | 4c24g | 8c48g | 16c96g | NoSQL 需要更多内存存储文档和分布式数据 |
+| 数据库服务 | Redis / Memcached | 1:8 | ESSD AutoPL | 2c16g | 4c32g | 8c64g | 内存数据库，内存是核心资源，CPU 需求相对较低 |
+| 数据库服务 | 高并发 OLTP | 1:4 | ESSD AutoPL | 8c32g | 16c64g | 32c128g | 事务处理需要高并发能力和大内存缓存 |
+| 数据库服务 | 高性能分析型数据库 | 1:6 | ESSD AutoPL | 8c48g | 16c96g | 32c192g | 分析查询需要大内存缓存和复杂计算处理 |
+| 大数据与实时计算 | 实时日志采集与分析 | 1:4 | ESSD AutoPL | 4c16g | 8c32g | 16c64g | 实时处理需要内存缓冲和流式计算能力 |
+| 大数据与实时计算 | 用户行为与埋点数据分析 | 1:4 | ESSD AutoPL | 8c32g | 16c64g | 32c128g | 大数据量分析处理，需要内存存储中间结果 |
+| 大数据与实时计算 | 数据仓库 ETL 任务 | 1:4 | ESSD AutoPL | 8c32g | 16c64g | 32c128g | ETL 需要大内存处理数据转换和临时存储 |
+| 大数据与实时计算 | IoT 设备数据接入 | 1:4 | ESSD AutoPL | 4c12g | 8c24g | 16c48g | 高并发接入，适度内存缓冲设备数据 |
+| 游戏服务 | 轻量级网页游戏 | 1:2 | ESSD PL0 | 2c4g | 4c8g | 8c16g | 简单逻辑，重视响应速度和并发处理 |
+| 游戏服务 | 大型 PC 端游服务器 | 1:2 | ESSD AutoPL | 8c16g | 16c32g | 32c64g | 复杂游戏逻辑，高 CPU 需求处理游戏状态 |
+| 游戏服务 | 移动对战类手游 | 1:2 | ESSD AutoPL | 4c8g | 8c16g | 16c32g | 实时对战，低延迟要求，快速状态同步 |
+| 游戏服务 | 云游戏视频编码推流 | 1:3 | ESSD AutoPL | 8c24g | 16c48g | 32c96g | 视频编码处理需要更多内存缓存视频帧 |
+| 高性能计算 | 自动驾驶仿真测试 | 1:4 | ESSD AutoPL | 16c64g | 32c128g | 64c256g | 复杂仿真需要大内存存储场景数据和计算结果 |
+| 高性能计算 | 工业 CAE / CFD 仿真 | 1:4 | ESSD AutoPL | 16c64g | 32c128g | 64c256g | 科学计算内存密集，需要大量数值计算 |
+| 高性能计算 | 科学计算与数值模拟 | 1:4 | ESSD AutoPL | 16c64g | 32c128g | 64c256g | 大规模计算需要大内存存储矩阵和中间结果 |
+| 高性能计算 | 基因测序与生物信息 | 1:6 | ESSD AutoPL | 16c96g | 32c192g | 64c384g | 生物数据处理内存需求极大，序列比对算法复杂 |
+| 音视频与图形渲染 | 视频转码与格式转换 | 1:2 | ESSD AutoPL | 8c16g | 16c32g | 32c64g | CPU 密集型转码，适度内存缓存视频数据 |
+| 音视频与图形渲染 | 直播流接收与分发 | 1:3 | ESSD PL0 | 4c12g | 8c24g | 16c48g | 流处理需要内存缓冲，支持多路流并发 |
+| 音视频与图形渲染 | 3D 动画离线渲染 | 1:4 | ESSD AutoPL | 16c64g | 32c128g | 64c256g | 渲染需要大内存存储 3D 场景和纹理数据 |
+| 音视频与图形渲染 | 短视频合成与 AI 滤镜 | 1:4 | ESSD AutoPL | 8c32g | 16c64g | 32c128g | AI 处理需要内存加载滤镜模型和视频帧 |
+
+## 存储配置推荐
+
+数据盘和系统盘一视同仁，标准推荐策略如下：
+- e实例 固定推荐 ESSD Entry
+- 其他实例基于场景推荐策略（表格/Json文件）匹配ESSD 级别，未预定义的场景，请基于已有场景让大模型推理确定级别。
+
+多款配置推荐生成策略：以上是基于标准配置推荐的策略，默认可以衍生多款配置：
+- 如果标准配置是PL0，则高配版刻配置AutoPL，成本优先版刻配置PL0或者 ESSD Entry （E实例）
+- 如果标准配置是AutoPL，则高配版可以是AutoPL，成本优先版可以是ESSD PL0
+
+基于以上原则可以默认生成多款存储配置。
+1. 默认同一个业务场景，系统盘、数据盘规格一致，
+2. 以上云盘的配置可以适用于新加数据盘，性能级别一致，默认增加1块数据盘，大小为100GB。
+
+## 镜像选择
+
+- **Alibaba Cloud Linux 4**：推荐，针对阿里云优化，内核定制
+- **Ubuntu 24.04**：社区支持好，生态丰富
+- **CentOS Stream 9**：兼容 RHEL，适合企业场景
+- **Windows Server 2025**：Windows 工作负载
+
+调用 DescribeImages 可指定 ImageName 进行模糊搜索。比如 ImageName="aliyun_4_*
+
+## 网络带宽
+
+- 默认按流量计费：适合流量不稳定的业务
+- 按带宽计费：适合流量持续稳定、高带宽场景
+- 公网 IP 可选按量购买 EIP，支持弹性绑定/解绑
+
+## 安全组最佳实践
+
+**默认不开 22/3389**——用 RunCommand/Invocation 部署即可，业务只开必要端口（Web → 80/443，层间通信 → `SourceGroupId`）。
+
+**须开 22/3389 时**（用户明确要求 SSH 或含跳板机）：`SourceCidrIp` 必须限定来源，严禁 `0.0.0.0/0`：
+- 执行 `curl -s https://api.ipify.org` 取当前公网 IP，写成 `<ip>/32`
+- 获取失败 → 请用户提供白名单 IP，不得回退到 `0.0.0.0/0`
+
+## 登录凭证
+
+**默认不写入 Password 和 KeyPairName**——模板中保持二者均不设置，应用部署通过 RunCommand/Invocation 执行命令，无需登录凭证。
+
+## 在实例中执行 Shell 命令
+
+- ROS 模板：参见 [../ros-template.md](../ros-template.md)「在实例中执行命令」章节
+- Terraform：参见 [../terraform-template.md](../terraform-template.md)「在实例中执行命令」章节
+
+## 高可用架构建议
+
+- 生产环境：至少 2 台 ECS，分布在不同可用区
+- 结合 SLB 做负载均衡
+- 使用弹性伸缩（ESS）应对流量波动
+- 重要数据存 RDS/OSS，避免依赖本地磁盘
+
+## 库存相关属性（模板中须参数化为 Parameters）
+
+| 属性 | 说明 |
+|------|------|
+| ZoneId | 可用区 |
+| InstanceType | 实例规格 |
+| ImageId | 镜像 ID（可用镜像受 InstanceType 影响） |
+| SystemDiskCategory | 系统盘类型 |
+| DataDiskCategory | 数据盘类型（如有数据盘） |
+
+## 可用性查询
+
+### 1. 查询可用实例规格
+
+```
+aliyun_api(product="ecs", action="DescribeAvailableResource", params={
+    "DestinationResource": "InstanceType",
+    "IoOptimized": "optimized",
+    "InstanceChargeType": "PostPaid"
+})
+```
+
+> InstanceChargeType 也可传 "PrePaid"（包年包月）。
+
+返回结果按可用区分组，包含各可用区支持的实例规格列表。
+
+### 2. 查询可用磁盘类型
+
+```
+aliyun_api(product="ecs", action="DescribeAvailableResource", params={
+    "DestinationResource": "SystemDisk",
+    "ZoneId": "<选定的可用区>",
+    "InstanceType": "<选定的实例规格>",
+    "InstanceChargeType": "PostPaid"
+})
+```
+
+### 3. 筛选逻辑
+
+1. 从返回的可用区列表中，筛出同时满足实例规格族和磁盘类型的可用区
+2. 按「实例规格推荐策略」的档位顺序匹配规格族（成本/性价比/性能 三档分别选）
+3. 同档位规格族不可用时：
+   - **个人 `e` 实例缺货** → 按"性价比优先"档位重新选
+   - **其他规格族缺货** → 在同档位的备选规格族列表中按顺序回退（如 `u1` → `u2a` → `u2i`）
+   - 整档位都不可用时，选同实例族中最接近 vCPU/内存的可用规格
+4. 云盘类型按「存储配置推荐」生成，并以可用磁盘类型查询结果做最终校验

iac_code/skills/bundled/iac_aliyun/references/cloud-products/oss.md

@@ -0,0 +1,69 @@
+# 阿里云 OSS 对象存储指南
+
+## 存储类型
+
+| 类型 | 访问频率 | 最低存储时间 | 适用场景 |
+|------|----------|-------------|----------|
+| 标准（Standard） | 频繁 | 无 | 热数据、网站图片、视频 |
+| 低频访问（IA） | 不频繁（月均 1-2 次） | 30 天 | 备份、归档数据 |
+| 归档（Archive） | 极少 | 60 天 | 长期归档，读取需解冻 |
+| 冷归档（Cold Archive） | 极少 | 180 天 | 合规存档，成本最低 |
+
+**推荐**：业务数据用标准，日志/备份用低频访问，合规数据用归档。
+
+## Bucket 配置要点
+
+资源类型 `ALIYUN::OSS::Bucket`，关键属性：
+- `StorageClass`：Standard / IA / Archive / ColdArchive
+- `AccessControl`：private（推荐）/ public-read / public-read-write
+- `VersioningConfiguration.Status: Enabled`：开启版本控制，防误删
+- `ServerSideEncryptionRule.SSEAlgorithm: AES256`：服务端加密
+
+## 访问控制
+
+### 访问权限级别
+
+| 权限 | 说明 | 推荐场景 |
+|------|------|----------|
+| private | 所有访问需鉴权 | 生产数据、敏感文件 |
+| public-read | 公开可读，写入需鉴权 | 静态网站、CDN 资源 |
+| public-read-write | 完全公开 | 不推荐用于生产 |
+
+### RAM Policy 控制
+
+- 应用服务使用 RAM 角色（而非 AK）访问 OSS
+- 按最小权限原则：只授予必要的 `oss:PutObject`、`oss:GetObject` 等权限
+- 禁止应用服务使用 `oss:DeleteBucket` 等危险权限
+
+### 防盗链
+
+通过 `RefererConfiguration` 设置 Referer 白名单，`AllowEmptyReferer: false` 禁止空 Referer 访问。
+
+## 生命周期规则
+
+通过 `LifecycleConfiguration.Rules` 配置：
+- `Expiration.Days`：指定天数后自动删除
+- `Transitions`：指定天数后转为低频（IA）或归档（Archive）存储类型
+
+## 静态网站托管
+
+通过 `WebsiteConfiguration` 配置 `IndexDocument` 和 `ErrorDocument`。
+
+## CDN 加速
+
+- OSS Bucket 绑定 CDN 域名，加速静态资源访问
+- CDN 回源协议选 HTTPS，开启回源鉴权
+- 缓存规则：静态资源（图片/JS/CSS）TTL 7 天，HTML 文件 TTL 10 分钟
+
+## 跨区域复制（CRR）
+
+- 关键数据开启跨区域复制，实现容灾
+- 两端 Bucket 均需开启版本控制
+
+## 最佳实践
+
+- 生产 Bucket 禁止公网写入，通过 STS Token 临时授权
+- 重要数据开启版本控制，防止误覆盖或误删
+- 日志 Bucket 独立于业务 Bucket，避免权限混用
+- 大文件（> 1 GB）使用分片上传（Multipart Upload）
+- 定期审计 Bucket 权限，防止权限漂移