内容
# 阿里云 Agent 工具包
[](LICENSE)
[](https://github.com/aliyun/alibabacloud-agent-toolkit/actions/workflows/build.yml)
[](#当前状态)
帮助 AI 编码代理在阿里云上构建、部署和运维应用。
本仓库提供阿里云代理插件、技能、MCP 配置和验证工具。
## 当前状态
本仓库当前提供：
- 市场清单、验证、CI、规则和共享技能的顶级项目脚手架。
- 两个活跃的插件：[`alibabacloud-core`](plugins/alibabacloud-core/) 和 [`alibabacloud-spec-ops`](plugins/alibabacloud-spec-ops/)。
- 为未来代理和数据分析插件预留的占位符目录。
`alibabacloud-core` 包括一个 SDK 使用技能，通过受限的 MCP 服务器生成阿里云 OpenAPI 交互代码。`alibabacloud-spec-ops` 提供由 Terraform 和 IaC 服务驱动的阿里云基础设施运维的规划到执行工作流。
## 仓库布局
```text
.
├── plugins/
│ ├── alibabacloud-core/
│ ├── alibabacloud-spec-ops/
│ ├── alibabacloud-agent/
│ └── alibabacloud-data-analytics/
├── rules/
├── skills/
└── tools/
```
### Hook 实现约定
`alibabacloud-core` 是 **钩子实现的真实来源**。钩子位于 `plugins/alibabacloud-core/hooks/` 目录下，钩子实现应与 `alibabacloud-core` 保持一致。
## 插件
| 插件 | 状态 | 描述 |
|--------|--------|-------------|
| [alibabacloud-core](plugins/alibabacloud-core/) | 活跃 | 使用本地 `alibabacloud-core` MCP 服务器的阿里云 OpenAPI SDK 代码生成。 |
| [alibabacloud-spec-ops](plugins/alibabacloud-spec-ops/) | 活跃 | 由 Terraform 和 IaC 服务驱动的阿里云基础设施运维工作流：规划 → Terraform 代码生成 → 验证 → 执行。 |
| `alibabacloud-agent` | 占位符 | 为未来代理功能预留。 |
| `alibabacloud-data-analytics` | 占位符 | 为未来数据分析和工作流功能预留。 |
## 先决条件
**Python 3.10+** — 钩子处理程序（大多数系统已预安装）。
**[uv](https://docs.astral.sh/uv/)** （提供 `uvx`）— 遥测跟踪查看器和 MCP 服务器：
```bash
# macOS
brew install uv
```
```bash
# Linux / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
```
**[阿里云 CLI](https://help.aliyun.com/document_detail/139508.html)** （`aliyun`）— 云运维：
```bash
# Linux amd64
curl -fsSL https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz | tar xz
# macOS
brew install aliyun-cli
```
## 安装插件
### 一键安装（推荐）
```bash
npx openplugin aliyun/alibabacloud-agent-toolkit
```
自动检测已安装的客户端（Claude Code、Codex、QoderWork），让您选择要安装的插件，并配置所有内容。
### 手动安装
#### Codex
```text
codex plugin marketplace add aliyun/alibabacloud-agent-toolkit
```
然后打开 Codex `/plugins` 并安装 `alibabacloud-core` 和/或 `alibabacloud-spec-ops`。
#### Claude Code
```text
/plugin marketplace add aliyun/alibabacloud-agent-toolkit
/plugin install alibabacloud-core@alibabacloud-agent-toolkit
/plugin install alibabacloud-spec-ops@alibabacloud-agent-toolkit
/reload-plugins
```
#### QoderWork
使用上述一键安装（`npx openplugin`），它会自动处理 QoderWork 钩子注册。
安装程序会修补 `~/.qoderwork/settings.json`，使用与 Codex 相同的 4 个事件钩子集（`PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop`），并且是幂等的 — 重新运行只会刷新此插件的条目。
## 使用 Spec-Ops：规范驱动的工作流
想要一个专家引导的、规范驱动的流程，从“我需要一个阿里云上的 Web 应用”到基础设施上线？只需一条命令：
```text
/alibabacloud-spec-ops:alibabacloud-planning 我需要一个阿里云上的 Web 应用
```
4 个阶段，自动链接，**一个用户关口**（在部署前）：
1. **规划** — 专家对话涵盖 **安全 / 成本 / 效率 / 稳定性**；将模糊需求转化为精确的 `design.md` + 架构图
2. **代码** — Terraform HCL 根据实时 `alicloud_*` 架构生成（IaCService 验证）
3. **验证** — 规范 + 代码质量审查器并行运行 → “部署？”
4. **执行** — `terraform plan` + `apply` 通过 IaC 服务远程运行；远程状态持久化
**Day-2 就绪。** 再说一句“升配 RDS / 加 Redis / 缩容”，原始 `design.md` 自动加载，在已有 `state_id` 上进行增量规划/执行，不重建已有资源。所有产物保存在 `.aliyun-ai-ops-spec/{name}/`，跨会话可审阅、可迭代。
## 数据采集
[English](#english) | [中文](#中文)
### 中文
#### 数据采集
本工具包在运行过程中可能会收集与您使用情况相关的必要信息，并发送至阿里云。阿里云将仅用于提供、维护和持续改进相关服务。
默认情况下，我们仅采集与阿里云插件活动相关的基础运行信息（详见 **[默认采集内容](#默认采集内容)**），您可随时按照下方说明关闭此类数据采集。除默认采集信息外，如问题排查等需要，在获得您授权后，本工具包将额外采集必要的补充信息（详见 **[额外授权字段](#额外授权字段)**）。
此外，本工具包中的某些功能可能会使您和阿里云能够收集您应用程序用户的数据。如果您使用这些功能，则必须遵守适用法律，包括向您的应用程序用户提供适当通知并取得必要同意。您使用本工具包即表示您同意这些做法。
##### 默认采集内容
以下字段仅描述阿里云插件行为。
| 字段 | 说明 |
|---|---|
| startTimestamp / endTimestamp | 阿里云工具调用的开始和结束时间（ISO 8601 UTC） |
| clientName | Agent 客户端类型（`claude-code`、`codex`、`copilot-cli`、`qoderwork`、`vscode`） |
| eventType | 阿里云事件类别（`skill_invocation`、`mcp_tool_use`、`cli_command_use`、`subagent_dispatch`、`reference_file_read`、`user_prompt_turn_start`、`llm_call`） |
| sessionId / mcpSessionId | 用于关联的会话标识；本工具包不会将其关联到阿里云账号 |
| skillName / pluginName / skillTag | 阿里云 skill 和插件标识 |
| mcpTool / toolName | 阿里云 MCP 工具名称和原始工具入口 |
| eventTag | 固定的阿里云事件标记 |
| status | 阿里云工具调用结果（`success` / `failure`） |
| toolRequestId | 用于服务端日志关联的阿里云 OpenAPI RequestId |
##### 额外授权字段
以下字段包含清洗后的阿里云操作上下文，仅在您明确授权后采集。
| 字段 | 说明 |
|---|---|
| cliCommand | 清洗后的 `aliyun` CLI 命令或阿里云 MCP 工具输入 JSON；凭证会被移除；长度限制为 2000-4000 字符 |
| errorMessage | 仅包含阿里云 API 错误类别或错误码，例如 `NoPermission` 或 `Throttling`；不包含自由文本 |
| inputUncachedTokens | 涉及阿里云工具的回合中的 LLM 未缓存输入 token 数 |
| inputCachedTokens | 涉及阿里云工具的回合中的 LLM 已缓存输入 token 数 |
| inputCreationTokens | 涉及阿里云工具的回合中的 LLM 缓存创建 token 数 |
| outputTokens | 涉及阿里云工具的回合中的 LLM 输出 token 数 |
| reasoningTokens | 涉及阿里云工具的回合中的 LLM reasoning token 数 |
#### 遥测配置
远程遥测默认开启。禁用远程遥测：
```bash
export ALIBABACLOUD_TELEMETRY=false
```
#### 本地审计追踪
插件会以 JSONL 格式记录透明的本地 trace。本地 trace 存储在您的机器上，默认不会上传，用于自审计、问题排查和本地可视化。
本地 trace 可能包括：
- 调用阿里云工具的回合中的用户 prompt
- 完整工具输入和响应，最大截断到 64 KB
- Skill 调用、耗时和 span 层级
- 回合生命周期事件
trace 文件按 session 存储：
```text
~/.cache/alibabacloud-agent-toolkit/telemetry/<client>/traces/<session-id>.jsonl
```
即使是本地 trace，也会做轻量清洗。超过 90 天的 trace 文件会在每次 session stop 时自动清理，避免磁盘无限增长。
禁用本地 trace：
```bash
export ALIBABACLOUD_TRACE=false
```
#### 本地遥测可视化
`telemetry-view` 会启动本地 Web Server，用于浏览和分析 trace 数据。它支持多客户端 session 浏览、span 层级树、Gantt 时间线、图形链路视图和实时更新。
启动：
```bash
uvx alibabacloud.mcp-proxy@latest telemetry-view
```
它会自动在浏览器中打开 `http://localhost:18321`。
参数：
| 参数 | 默认值 | 说明 |
|------|---------|-------------|
| `--port` | `18321` | 本地服务端口 |
| `--no-open` | - | 不自动打开浏览器 |
自动扫描的数据来源：
1. `$ALIBABACLOUD_TELEMETRY_STATE_DIR`，如果已设置
2. `~/.cache/alibabacloud-agent-toolkit/telemetry/`
3. `/tmp/alibabacloud-agent-toolkit-telemetry-<uid>/`
## 技能
顶级 [`skills/`](skills/) 目录为未来共享的阿里云技能初始化。类别目录作为占位符存在。
## 规则
推荐的代理指南位于 [`rules/`](rules/) 目录下。初始规则文件面向阿里云，并故意设计得非常通用，直到添加第一个具体工作流。
## 验证
本仓库保留来自参考工具包结构的验证和 CI 骨架。
```bash
mise run lint
mise run validate
```
## License
本项目根据 Apache-2.0 许可证授权。详情请参见 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器