alibabacloud-agentloop-contextstore

AgentLoop ContextStore 技能

场景说明

此技能用于操作 Alibaba Cloud CloudMonitor Service（CMS）AgentLoop 下的 ContextStore 资源。ContextStore 通过两种存储类型持久化 Agent 的长期上下文：

• memory：用户偏好、事实、情节摘要和从对话中提取的记忆。
• experience：根据 Agent 轨迹总结的故障排查或任务执行经验。

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

执行数据操作前，务必确认目标存储的 contextType。memory 和 experience 存储共用相同的 CLI 产品和子命令，但写入架构、筛选字段路径和格式化输出各不相同。

安装

预检查：需要 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 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动插件安装。 [MUST] 运行 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
# If missing or older than 0.2.4:
aliyun plugin install --names cms --version 0.2.4
# Or install the latest:
aliyun plugin install --names cms

环境变量

无需设置 ContextStore 专用环境变量。Aliyun CLI 凭据和区域可以来自已配置的 CLI 配置文件、Alibaba Cloud 环境变量、STS、OAuth 或 ECS RAM 角色。

切勿读取、回显或打印机密环境变量值。仅使用 aliyun configure list 检查是否存在有效的配置文件或身份。

身份验证

预检查：需要 Alibaba Cloud 凭据

安全规则：

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

aliyun configure list

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

如果不存在有效的配置文件，请在此处停止。

1. 从 Alibaba Cloud Console 获取凭据
2. 在本次会话之外配置凭据（通过终端中的 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并重新运行，直到 aliyun configure list 显示有效的配置文件

RAM 策略

ContextStore 操作需要 CMS AgentLoop 对存储、上下文和 API 密钥 API 的权限。完整操作列表和策略模板请参阅 references/ram-policies.md。

[MUST] 权限失败处理： 在执行期间的任何时候，如果命令或 API 调用因权限错误而失败，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需的完整权限列表。
2. 如果当前环境中已安装 ram-permission-diagnose 技能，请调用它来引导用户申请所需权限。否则，列出缺失的 RAM 操作和 references/ram-policies.md 中的策略模板，并请用户通过 Alibaba Cloud RAM 控制台 将策略附加到当前 RAM 身份。
3. 暂停操作，等待用户确认已授予所需权限后再重试。

参数确认

IMPORTANT：参数确认 -- 执行任何命令或 API 调用之前， 必须向用户确认所有可自定义参数（例如 RegionId、实例名称、CIDR 块、 密码、域名、资源规格等）。未经用户明确批准，切勿假定或使用默认值。

参数名称	必需/可选	说明	默认值
--region	可选	当前 CLI 命令的区域覆盖值。如果用户不想使用已配置的默认区域，请先确认。	CLI 配置的区域
--workspace	必需	AgentLoop 工作区 ID。	无
--context-store-name	除 list-context-stores 外必需	ContextStore 名称。	无
--context-type	创建/写入流程必需	存储类型：memory 或 experience。	无
--memory-type	仅写入 memory 时必需	memory 写入类型：short 或 long。切勿用于 experience 写入。	无
--context-id	获取/更新/删除单条记录时必需	上下文记录 ID。	无
--items	对 add-contexts 必需	要写入的记录 JSON 数组。其架构取决于 contextType。	无
--filter	可选	用于 search-context 或 delete-contexts 的 JSON 筛选条件。字段路径取决于 contextType。	无
--query	搜索时必需	语义搜索查询。	无
--limit	可选	最大搜索结果数。	服务默认值
--retrieval-option	可选	Experience 搜索选项：reranker、llm_rank，或以逗号分隔的两者。	无
--config	根据流程可选/必需	存储配置。对于 experience 存储以及数据源为现有 logstore 的 memory 存储，此项为必需。	无
--name	API 密钥命令必需	存储级 API 密钥名称。	无

核心工作流

[MUST] 启用 AI-Mode —— 执行 Agent Skill 前必须启用 AI-mode。在调用任何 CLI 命令前，运行以下命令：

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

[MUST] 在每个退出点禁用 AI-Mode —— 无论出于何种原因，在给出最终答复前，务必先禁用 AI-mode。这适用于工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不再执行 CLI 命令的其他情况。

aliyun configure ai-mode disable

如果上一次运行遗留了已启用的 AI-mode（例如因崩溃、会话中断或忘记退出所致），请使用 aliyun configure ai-mode show 检查当前状态，并在新工作流开始前运行一次 aliyun configure ai-mode disable。

1. 判断意图：存储管理、记忆数据、经验数据、API 密钥管理、筛选条件构建或验证。
2. 确认上表中的所有用户可自定义参数。
3. 执行 CLI 和凭证预检查。如果 CLI 版本或凭证无效，则停止。
4. 如果存储类型未知，请先查询类型，再选择数据架构：

aliyun cms --api-version 2024-03-30 get-context-store \
  --workspace <workspace> \
  --context-store-name <context_store_name>

5. 对于不确定的 JSON，在发起实际请求前先运行试运行：

aliyun cms --api-version 2024-03-30 <subcommand> \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --cli-dry-run

6. 执行对应操作：
   • 存储和 API 密钥操作：参见 references/store-management.md。
   • 记忆和经验数据操作：参见 references/context-data-operations.md。
   • 筛选语法：参见 references/filter-syntax.md。
7. 使用 references/verification-method.md 中针对具体命令的检查来验证是否成功。
8. 返回最终答复前禁用 AI-mode。

成功验证方法

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

清理

执行破坏性清理前，确认清理参数。优先执行范围较窄的删除（单条记录），而不是批量删除；只有在用户明确确认要删除整个存储时，才删除存储。

单条记录：

aliyun cms --api-version 2024-03-30 delete-context \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --context-id <context_id>

批量（互斥标志 --context-ids 或 --filter；绝不可同时使用，也不可使用请求正文）：

aliyun cms --api-version 2024-03-30 delete-contexts \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --context-ids "<context_id_1>,<context_id_2>"

aliyun cms --api-version 2024-03-30 delete-contexts \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --filter '<filter_json>'

具有 immutable: true（记忆）或 metadata.immutable: true（经验）的记录会在服务端跳过，且不会计入 deletedCount。

整个存储（不可逆；系统管理的数据集和内部 logstore 将被删除；用户提供的源 logstore 不会被删除）：

aliyun cms --api-version 2024-03-30 delete-context-store \
  --workspace <workspace> \
  --context-store-name <context_store_name>

API 密钥：

aliyun cms --api-version 2024-03-30 delete-context-store-api-key \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --name <api_key_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 密钥创建输出视为机密材料。明文密钥只会由 create-context-store-api-key 返回一次；切勿将其粘贴到对话历史中，并请用户在会话之外安全保存。
7. 在执行破坏性操作或复杂的 JSON 请求前，使用 --cli-dry-run。
8. 不可更新或删除不可变记录；批量删除会跳过这些记录，且它们不会计入 deletedCount。
9. 仅在使用 --context-ids 或 --filter 时使用 delete-contexts；它不接受请求正文，且这两个标志不能同时使用。
10. 创建存储后，contextType、contextStoreName 和 config.source 均不可更改。若要更改源日志库或存储类型，请创建新存储并迁移数据。
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 架构使用 experience（对象）和 metadata（对象）。

应避免的常见错误

错误写法	正确写法	原因
aliyun cms add-contexts ...（未指定 --api-version）	aliyun cms --api-version 2024-03-30 add-contexts ...	该子命令仅存在于此 API 版本中
写入记忆时未指定 --memory-type	--memory-type short 或 --memory-type long	写入记忆时必须指定
写入经验时使用 --memory-type long	写入经验时省略 --memory-type	写入经验时禁止使用
在条目顶层设置经验的 categories / immutable	将它们放在 metadata 中	记忆使用顶层字段；经验使用 metadata
经验筛选器 {"serviceName":"x"}	{"metadata.serviceName":"x"}	经验的 metadata 字段使用 metadata. 前缀
delete-contexts --body '{...}'	delete-contexts --context-ids "id1,id2" 或 --filter '{...}'	delete-contexts 不接受请求正文
metadata.traceStartNs: 1775799927869697848（数字）	"traceStartNs": "1775799927869697848"（字符串）	通过 Go float64 解析时，超过 2^53 的裸数字会丢失精度
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET	aliyun configure list	切勿读取或打印 AK/SK 密钥

参考链接

参考资料	内容
references/store-management.md	创建、获取、列出、更新和删除存储，以及管理存储 API 密钥。
references/context-data-operations.md	记忆和经验的写入、搜索、更新、删除架构及示例。
references/filter-syntax.md	通用筛选运算符，以及记忆与经验的字段路径。
references/related-commands.md	支持的 CLI 命令表和帮助验证命令。
references/verification-method.md	成功检查、试运行检查和命令验证工作流。
references/ram-policies.md	所需的 RAM 操作和策略模板。
references/cli-installation-guide.md	Aliyun CLI 安装和配置指南。