AgentLoop ContextStore 技能

场景说明

该技能在阿里云云监控服务（CMS）AgentLoop 下管理 ContextStore 资源。ContextStore 以两种存储类型持久化长期运行的智能体上下文：

• memory：用户偏好、事实、剧集摘要及对话生成的记忆。
• experience：从智能体执行轨迹中提炼出的故障排查或任务执行经验。

架构组成：Aliyun CLI + CMS AgentLoop + ContextStore + 可选的数据源 Log Service project/logstore + 存储级 API Key。

执行任何数据操作前，必须确认目标存储的 contextType。memory 和 experience 存储共用同一 CLI 产品及子命令，但其写入 Schema、过滤字段路径与格式化输出均不相同。

安装

前置检查：Aliyun CLI 版本需 ≥ 3.3.3

运行 aliyun version 验证版本是否 ≥ 3.3.3。若未安装或版本过低，请执行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 安装或升级，或参考 references/cli-installation-guide.md 获取完整安装说明。

aliyun version

前置检查：Aliyun CLI 插件需更新

[必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装功能。
[必须] 运行 aliyun plugin update 确保所有已安装插件均为最新版本。

aliyun configure set --auto-plugin-install true
aliyun plugin update

前置检查：CMS 插件版本需 ≥ 0.2.4

ContextStore 子命令及 experience / metadata / config.metadataField 中类型化值的正确处理，依赖 CMS 插件 ≥ 0.2.4。旧版本会静默地将嵌套数字、布尔值、数组和 null 值强制转为字符串。请验证并按需安装：

aliyun plugin show --name cms
# 若缺失或版本低于 0.2.4：
aliyun plugin install --names cms --version 0.2.4
# 或安装最新版：
aliyun plugin install --names cms

环境变量

ContextStore 不需要专用环境变量。Aliyun CLI 凭据与地域信息可来源于已配置的 CLI Profile、阿里云环境变量、STS、OAuth 或 ECS RAM 角色。

切勿读取、回显或打印密钥类环境变量值。仅可使用 aliyun configure list 检查是否存在有效 Profile 或身份凭证。

认证

前置检查：需提供阿里云凭据

安全规则：

• 严禁读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 属于禁止行为）
• 严禁要求用户在对话或命令行中直接输入 AK/SK
• 严禁使用带明文凭据值的 aliyun configure set
• 仅允许使用 aliyun configure list 检查凭据状态

aliyun configure list

检查输出中是否存在有效的 Profile（AK、STS 或 OAuth 身份）。

若不存在有效 Profile，请立即中止流程。

1. 从阿里云控制台获取凭据
2. 在当前会话之外完成凭据配置（通过终端中运行 aliyun configure，或在 Shell Profile 中设置环境变量）
3. 待 aliyun configure list 显示有效 Profile 后，返回并重新执行后续步骤

RAM 权限策略

ContextStore 操作需具备 CMS AgentLoop 对存储、上下文及 API Key 相关 API 的权限。详见 references/ram-policies.md 中的完整操作列表与策略模板。

[必须] 权限失败处理流程：当任意命令或 API 调用在执行过程中因权限错误而失败时，请遵循以下流程：

1. 查阅 references/ram-policies.md 获取本技能所需的全部权限清单。
2. 若当前环境中已安装 ram-permission-diagnose 技能，请调用该技能引导用户申请必要权限；否则，请向用户展示缺失的 RAM 操作项及 references/ram-policies.md 中提供的策略模板，并提示用户通过阿里云 RAM 控制台将该策略附加至当前 RAM 身份。
3. 暂停执行，等待用户确认所需权限已授予后，再重试操作。

参数确认

重要：参数确认 —— 在执行任何命令或 API 调用前，所有用户可自定义参数（如 RegionId、实例名称、CIDR 块、密码、域名、资源规格等）均须经用户明确确认。不得在未经用户批准的情况下假设或使用默认值。

核心工作流

[必须] 启用 AI 模式 —— Agent 技能执行需启用 AI 模式。请在执行任意 CLI 命令前运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agentloop-contextstore"

[必须] 在每个退出点禁用 AI 模式 —— 在返回最终响应前（无论成功、失败、异常、用户取消、会话结束或其他任何不再执行 CLI 命令的情形），均须首先禁用 AI 模式。

aliyun configure ai-mode disable

若上一次运行遗留 AI 模式处于启用状态（例如因崩溃、会话中断或遗漏退出），请先使用 aliyun configure ai-mode show 检查当前状态，并在新工作流启动前执行一次 aliyun configure ai-mode disable。

1. 识别意图类型：存储管理、内存数据、经验数据、API Key 管理、过滤器构建或验证。
2. 根据上方表格确认所有用户可自定义参数。
3. 执行 CLI 与凭据前置检查。若 CLI 版本或凭据无效，则立即中止。
4. 若存储类型未知，请先查询再选择对应数据 Schema：

aliyun cms --api-version 2024-03-30 get-context-store 
  --workspace  
  --context-store-name 

5. 对于不确定的 JSON 输入，在真实请求前先执行预演（dry run）：

aliyun cms --api-version 2024-03-30  
  --workspace  
  --context-store-name  
  --cli-dry-run

6. 执行对应操作：
   • 存储与 API Key 操作：参见 references/store-management.md。
   • 内存与经验数据操作：参见 references/context-data-operations.md。
   • 过滤器语法：参见 references/filter-syntax.md。
7. 依据 references/verification-method.md 中的命令特异性检查项验证执行结果。
8. 返回最终响应前，禁用 AI 模式。

成功验证方法

使用 references/verification-method.md 进行命令校验、非破坏性存储检查、数据写入/搜索校验、API Key 校验及清理验证。

清理

执行破坏性清理操作前，须确认相关参数。优先采用窄范围删除（单条记录），仅在用户明确确认需移除整个存储时才执行存储级删除。

单条记录删除：

aliyun cms --api-version 2024-03-30 delete-context 
  --workspace  
  --context-store-name  
  --context-id 

批量删除（互斥参数：--context-ids 或 --filter；不可同时使用，且不接受请求体）：

aliyun cms --api-version 2024-03-30 delete-contexts 
  --workspace  
  --context-store-name  
  --context-ids ","

aliyun cms --api-version 2024-03-30 delete-contexts 
  --workspace  
  --context-store-name  
  --filter ''

标记为 immutable: true（内存）或 metadata.immutable: true（经验）的记录将在服务端跳过，且不计入 deletedCount。

整存删除（不可逆；系统托管的数据集与内部 Logstore 将被移除；用户指定的源 Logstore 不受影响）：

aliyun cms --api-version 2024-03-30 delete-context-store 
  --workspace  
  --context-store-name 

API Key 删除：

aliyun cms --api-version 2024-03-30 delete-context-store-api-key 
  --workspace  
  --context-store-name  
  --name 

命令对照表

所有支持的 ContextStore 命令、参数规则及验证辅助工具均列于 references/related-commands.md 中。

最佳实践

1. 始终包含 --api-version 2024-03-30；否则 ContextStore 子命令可能不可用。
2. 执行写入、过滤、更新或解析格式化输出前，务必确认 contextType。
3. --memory-type short 或 --memory-type long 仅用于内存写入；经验写入时严禁传入该参数。
4. 内存数据的 categories、immutable 和 expirationDate 应置于条目顶层；经验数据的 categories 和 immutable 应置于 metadata 内部。
5. Shell 中对复杂 JSON 参数使用单引号包裹，JSON 内部使用双引号。
6. 将 API Key 创建输出视为机密材料。create-context-store-api-key 仅返回一次明文密钥；切勿将其粘贴至对话历史中，并提醒用户在会话外安全保存。
7. 执行破坏性操作或发送复杂 JSON 请求前，使用 --cli-dry-run 预演。
8. 不可变记录无法更新或删除；批量删除将跳过此类记录，且不计入 deletedCount。
9. delete-contexts 仅支持 --context-ids 或 --filter；不接受请求体，且两个参数互斥。
10. contextType、contextStoreName 和 config.source 在存储创建后不可变更。如需变更源 Logstore 或存储类型，请新建存储并迁移数据。
11. CMS 插件 ≥ 0.2.4 是前提条件：旧版插件会静默地将 experience / metadata / config.metadataField 中的类型化值转为字符串。请在任意写入操作前使用 aliyun plugin show --name cms 验证版本；如需升级，请执行 aliyun plugin install --names cms --version 0.2.4（或省略 --version 安装最新版）。
12. 新经验记录中请勿写入遗留字段 triggerCondition；v1 Schema 使用 experience（对象）加 metadata（对象）结构。

常见错误规避

参考链接