alibabacloud-loongcollector-ops

LoongCollector 运维

将自然语言请求转换为可执行、可验证、可回滚的工作流，供用户操作自己的 LoongCollector 和 SLS 资源——涵盖安装、采集到查询。

架构：Install (ECS/self-host/ACK/self-k8s) + SLS Project + Logstore + Index + MachineGroup + Pipeline (API or ClusterAliyunPipelineConfig) + binding + SLS Lens

**范围。**涵盖：

• 安装/升级 Linux 采集器：ECS aliyun ecs run-command、自托管 SSH、ACK 插件 loongcollector、self-k8s 自定义软件包。必须继续完成采集和查询；进程/插件就绪仅是一个阶段门槛。
• ACK 首次使用：open-ack-service --type propayasgo + CS 服务角色（scripts/ensure_ack_prereq.sh）。仅当用户要求创建集群时才运行 create-cluster。评估钩子可以预先创建测试集群；这不是生产环境的默认做法。
• 云端接入：Project / Logstore / Index / MachineGroup / Pipeline Config / 绑定。
• K8s 采集：默认使用 SLS Pipeline API（create-logtail-pipeline-config + 绑定官方组）。只有当用户要求使用 GitOps/CRD，且存在可访问的 kube-apiserver 时，才选择应用 CRD（references/crd-pipeline.md）。
• 配置管理：创建、修改、应用、移除、数据验收（U1-U6）。
• 机器组管理：IP / 自定义身份、成员、心跳、版本。
• SLS Lens：运行日志查询（get-logs-v2）、主题/字段约定、版本路由、降级。
• 基础故障排查：无数据、心跳异常。

语言和 HITL 交付规范

**语言硬性规则：**所有面向用户的消息都必须使用用户的主要语言。包括计划、澄清问题、确认问题及其选项、报告和错误指导。产品名称、标识符、CLI 命令、JSON 字段、错误代码和固定状态标签可以保留原文。周边文字不得切换为其他语言。

**面向用户消息和标记的规范目录：**以下每个值都必须按字面使用。输出所选值时必须逐字照用；不得翻译、转述，也不得与其他问题合并。

messages:
  missing_task_scope: "请补充要执行的具体操作目标、地域和 SLS Project。"
  missing_lens_parameters: "请补充业务 Project、地域和查询时间范围。"
  machine_group_identity: "请选择机器组标识类型：IP 或 userdefined。"
  r2_update: "是否确认执行上述变更计划？请选择：确认执行或取消。"
  r2_create_bind: "是否确认创建上述资源并完成绑定？请选择：确认执行或取消。"
  r3_unbind: "是否确认将上述旧配置从机器组解绑？请选择：确认解绑或取消。"
  permission_recovery: "是否已完成所需 RAM 授权并允许重试？请选择：已授权或未授权。"
  permission_recovery_short: "是否已完成所需 RAM 授权并允许重试？"
  lens_entry: "请提供 SLS Lens 服务日志的 Project 和 Logstore。"
  ecs_install: "是否确认在上述 ECS 上安装 LoongCollector？"
  self_host_install: "是否确认在上述主机上安装 LoongCollector？"
  ack_install: "是否确认在上述 ACK 集群安装 loongcollector 组件？"
  self_k8s_install: "是否确认在上述 Kubernetes 集群安装 LoongCollector？"
  kubeconfig: "请提供可用的 kubectl 与目标集群 context。"
  ssh: "请提供已配置的 SSH（alias 或主机），不要在对话中发送私钥。"
  collector_version: "请提供采集器版本（例如 3.3.9）。"
markers:
  ownership_error: ["不属于当前账号", "项目不属于你"]
  permission_decline: ["未授权", "停止"]
  permission_grant: ["已授权"]
  cancel: ["取消"]
  private_ip: ["私网 IP"]
  routing_intent: ["日志采集", "安装采集器"]
  end: ["结束"]
  collector_deployed_without_version: ["LoongCollector 已部署"]
  binding_acceptance: ["完成绑定与验收"]
  approval: ["确认", "确认执行", "确认解绑"]
  install_intent: ["允许安装", "请安装", "直接执行", "已授权操作", "任务已预授权"]
  install_only_status: ["仅安装完成、采集未接入"]
  deferral: ["还没想好", "等会儿再说", "暂不确认", "第二次等待", "第N次暂不确认", "先放一放", "已达到上限", "请阻塞"]
  data_incomplete: ["无法完成数据面验收"]
  data_empty: ["无数据"]
  reason: ["原因"]
  forbidden_empty_success: ["采集成功", "所有验收标准均已满足", "全链路验收通过", "通过"]
  data_arrived: ["数据到达"]
  root_cause_located: ["根因已定位"]
  not_exists: ["不存在"]
  pending_read: ["未执行待办", "待办"]

将 machine_group_identity 与 [AWAITING: MACHINE_GROUP_TYPE] 配对（绝不能使用 R2_CONFIRMATION）。将 permission_recovery 与 [AWAITING: PERMISSION_CONFIRMATION] 配对；将 lens_entry 与 [AWAITING: LENS_ENTRY] 配对；所有安装消息都与 [AWAITING: INSTALL_CONFIRMATION] 配对；将 kubeconfig 与 [AWAITING: KUBECONFIG] 配对；将 ssh 与 [AWAITING: SSH] 配对；将 collector_version 与 [AWAITING: COLLECTOR_VERSION] 配对。只有在真实的 SSH 探测成功后，才允许发送 self_host_install 消息。

不得将这些内容替换为冗长的英文说明、双语表格或新编造的状态标签。每次重新提问时，都必须在必需的 [AWAITING: ...] 标签之前逐字重复同一个简短中文问题。**末行硬性规则：**对应的标签必须紧接在问题后的下一行，并且是本轮的最后一行——问题和标签之间不得有空行，标签后不得有空行、标点或其他句子。输出 HITL 标签的轮次不得将任何 [AWAITING: ...] 字面值复制到工具调用、代码块、outputs/* 或 ran_scripts/* 中；重复标签会破坏自动匹配。安装确认必须以 [AWAITING: INSTALL_CONFIRMATION] 结束本轮——安装或机器组身份确认绝不能重复使用 R2_CONFIRMATION。采集/创建绑定确认标签的最后一行必须包含提问计数：首次提问使用 [AWAITING: R2_CONFIRMATION] ask=1；每次延期后重新提问时，计数递增。Lens 入口回退必须以 [AWAITING: LENS_ENTRY] 结束本轮。缺少 kubectl 时必须以 [AWAITING: KUBECONFIG] 结束本轮。缺少 SSH 时必须以 [AWAITING: SSH] 结束本轮。缺少 collector 版本时必须以 [AWAITING: COLLECTOR_VERSION] 结束本轮。机器组身份必须以 [AWAITING: MACHINE_GROUP_TYPE] 结束本轮。RAM 权限恢复必须以 [AWAITING: PERMISSION_CONFIRMATION] 结束本轮。

固定英文标记（必须逐字保留；周边文字使用中文）：[BLOCKED: …] / [CANCELLED: …] / [AWAITING: …] / ask=1 / ask=2 / ask=3 / [Error: permission|throttling|internal|parameter] / [RECOVERED: …] / resource_status: Resource not found / [Query: Incomplete] / INCOMPLETE。拒绝和确认超时轮次：该轮的唯一内容是简短标签——不得有英文长句、前缀或后缀。

**范围外内容。**Windows；Sidecar；卸载/回滚/作为生命周期操作的重启；创建 ECS；OOS/ChatOps；编写 AliyunLogConfig / NamespaceAliyunPipelineConfig；高级故障排查（延迟、重复、解析失败、容器过滤、数据丢失/截断）。禁止使用 kubectl exec 和 docker exec。如果用户要求执行范围外的生命周期操作，请说明该操作不在范围内，并停止该分支。

1. 前置条件

预检查：需要 Aliyun CLI >= 3.3.3

[必须] 验证：aliyun version — 必须 >= 3.3.3（建议 >= 3.3.5）。

• 首次安装或重大升级：/bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"
• 常规更新（CLI >= 3.3.5）：aliyun upgrade。
• 请参阅 references/cli-installation-guide.md。

预检查：需要 SLS 插件

[必须] 运行 aliyun configure set --auto-plugin-install true，然后运行 aliyun plugin install --names aliyun-cli-sls 和 aliyun plugin update。 集合子命令由 aliyun-cli-sls 插件提供（带连字符的子命令，例如 aliyun sls get-logs-v2）。请使用 aliyun sls --help 验证。

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止运行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不对凭证文件（例如 ~/.aliyun/config.json、~/.aws/credentials）使用 cat、less、head、tail、grep、open、json.load 或任何读取文件的命令。仅使用 ls 检查文件是否存在，绝不显示文件内容。打印明文机密会导致任务立即失败，并构成安全事件。
• 绝不安装或导入 aliyun-log-python-sdk / aliyun.log / LogClient 或任何其他 SLS SDK 来绕过 CLI。使用 pip install 安装云 SDK 会导致任务失败。
• 绝不在对话中打印、使用 cat 查看或粘贴 kubeconfig / 客户端证书 / 令牌。仅针对选择加入的 CRD：将 describe-cluster-user-kubeconfig 的输出写入权限为 0600 的临时文件。
• 绝不要求用户直接在对话或命令行中输入 AK/SK
• 绝不使用字面凭证值运行 aliyun configure set
• 仅使用 aliyun configure list 检查凭证状态。scripts/preflight.sh 已执行此操作。

aliyun configure list

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

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

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

运行 bash scripts/preflight.sh，一步检查 CLI 版本、插件、凭证是否存在以及范围。preflight.sh 内部已调用 aliyun configure list；运行该脚本本身就是有效的凭证检查——不要使用 cat 查看 CLI 配置文件，也不要仅为满足检查清单而单独运行 aliyun configure list。完整门禁详情：references/prerequisites.md。

环境变量

变量	必需	描述
（凭证无需设置）	—	凭证来自 aliyun configure 配置；切勿在会话中引入 AK/SK 环境变量
SKILL_SESSION_ID	脚本运行时注入	与 session/{session-id} UserAgent 令牌相同的 32 位十六进制会话 ID；调用捆绑脚本时内联设置（参见 §4）

---

2. RAM 策略

此技能使用用户自己的身份，且只操作其获准访问的资源。权限分为只读、运维和破坏性权限。各工作流对应的 RAM 操作见 references/ram-policies.md——不要默认使用广泛的 AliyunLogFullAccess。

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

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose 技能指导用户申请所需权限
3. 暂停并等待用户确认已授予所需权限

运行时细则（同一权限关卡，不要跳过上述三个步骤）：

1. 报告缺失的 RAM Action 和 requestID；输出 [Error: permission]。仅阅读 references/ram-policies.md 并不算成功的诊断调用。
2. 尝试使用缺失的 Actions 和 requestID 调用 ram-permission-diagnose。**回退方案：**如果该技能不可用，请手动输出 Action/requestID/RAM 控制台指南，然后询问目录消息 permission_recovery，并以 [AWAITING: PERMISSION_CONFIRMATION] 作为最后一行，然后暂停。
3. 确认前，不要重试受影响的写入（包括 --cli-dry-run）。
4. 读取路径的硬性停止条件： 对 get-project / get-machine-group / list-machines / get-log-store 返回 401/403/Unauthorized/AccessDenied 时，先阅读消息。如果属于所有权问题（英文所有权文本或任何目录 ownership_error 标记），则这不是 RAM 权限关卡：输出 [BLOCKED: RESOURCE_RESOLUTION_FAILED] 并停止；不要询问 permission_recovery_short，不要创建正式的 k8s-log-* 名称，也不要重试。否则，输出包含 Action/requestID 的 [Error: permission]，然后在同一轮中准确询问 permission_recovery，并以 [AWAITING: PERMISSION_CONFIRMATION] 作为最后一行；该轮中不得再发出任何 aliyun sls 调用——包括 get-machine-group、list-machines、get-applied-configs 和 get-log-store。这些尚未读取的调用应列为目录中的 pending_read 项，而不是已查询得出的结论。
5. 收到用户的权限答复后（读取路径与写入/试运行共用同一权限关卡）：
   • 若出现任何目录 permission_decline 标记或等同的拒绝 → 该轮不得调用任何工具（不得使用 write_file 或 aliyun sls）。明确说明执行已终止，按目录中的 pending_read 列出所有尚未运行的读取项及其 RAM Action，最后一行写 [BLOCKED: PERMISSION_REQUIRED]。如果任务要求查询机器组心跳，待处理项必须包含 get-machine-group → log:GetMachineGroup 和 list-machines → log:ListMachines（注明机器组名称）。绝不能把尚未运行的心跳查询说成已查询得出的结论。
   • 若出现目录 permission_grant 标记 → 在同一轮重试完全相同的失败命令（如果失败的是试运行，则先重试该试运行），并立即在面向用户的文本中输出 [RECOVERED: permission_granted]。明确说明处理方式为人工介入后重试，以清楚表明采取的恢复操作。

如果核心写入或其试运行返回 Unauthorized/AccessDenied：停止当前写入，进入 §6 权限恢复分支，绝不能切换账号/配置文件或扩大范围。

3. 参数确认

重要：参数确认 — 执行任何命令或 API 调用前， 必须先与用户确认所有可由用户自定义的参数（例如 RegionId、实例名称、CIDR 网段、 密码、域名、资源规格等）。未经用户明确同意，不得假设或使用默认值。

参数	必填/可选	描述	默认值
region	必填	SLS 区域 ID，例如 cn-hangzhou	无
project	必填	目标 SLS 项目	无
logstore	有条件必填	目标 logstore（创建/接入/查询）	无
machine_group	有条件必填	机器组名称（绑定/心跳）	无
config_name	有条件必填	Logtail 管道配置名称	无
machine_identify_type	有条件必填	ip 或 userdefined	无
machine_list	有条件必填	IP 列表或用户自定义标识符	无
scenario	有条件必填	host / docker / k8s / host_agentsight	无
environment	有条件必填	install.deploy 的 ecs / self_host / ack / self_k8s	无
instance_id	有条件必填	ECS 实例 ID（Workbench）	无
cluster_id	有条件必填	ACK / self-k8s 集群 ID	无
lens_project / lens_logstore	可选	无法自动发现时使用的 SLS Lens 入口	无

缺少真实资源时，切勿用占位符或示例值代替。缺少 region、project 或会改变操作范围的目标 → 停止并询问。

对于缺少 machine_identify_type 的中文请求，使用中文选项说明，准确询问目录消息 machine_group_identity，并以 [AWAITING: MACHINE_GROUP_TYPE] 作为最后一行结束本轮对话——绝不能使用 [AWAITING: R2_CONFIRMATION]。用户选择后，运行 scripts/normalize_diff.py，然后才询问创建并绑定的问题，并附上 [AWAITING: R2_CONFIRMATION] ask=1。不要输出自定义英文状态标签或英文选项表。**install.deploy 例外：**在确认采集创建-绑定关卡之前，不要询问机器组标识类型。如果该关卡收到目录 cancel 标记或等效拒绝，则绝不要询问。如果用户已指定 IP、userdefined 或目录 private_ip 标记，则绝不要询问。

---

4. 可观测性（每条 aliyun 命令都必须遵守）

加载此技能时，生成一个随机会话 ID（32 位小写十六进制字符串），并在整个会话中使用同一个 ID。将其用作下方的 {session-id}。

规则：每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。 这适用于此技能发出的 aliyun sls、aliyun cs、aliyun ecs 以及任何其他 aliyun <product> 云调用，包括 --cli-dry-run。本地实用程序命令（例如 configure、plugin、version）不支持此标志，应予以排除。kubectl / Workbench / SSH / 本地验证器不属于阿里云 API，不需要发送此标志。

使用两个以空格分隔的产品令牌（将整个值括在引号中；空格不可省略）：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-loongcollector-ops session/{session-id}"

令牌	示例	查询用途
技能标识	AlibabaCloud-Agent-Skills/alibabacloud-loongcollector-ops	此技能发出的所有流量
会话	session/{session-id}	一个会话

绝不要将会话 ID 拼接到技能令牌上（禁止使用 .../ops/{session-id}）。绝不要省略引号。绝不要跳过、更改或删除任一令牌。

示例（假设 session-id 为 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6）：

aliyun sls list-machines --project my-proj --machine-group my-group --region cn-hangzhou --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-loongcollector-ops session/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

引用中写作 --user-agent <ua> 时，均指这个带引号的双令牌字符串。

**脚本 / Terraform 执行：**运行 Python SDK 脚本、Terraform 命令或 bash 脚本时，通过内联环境变量注入 session-id，以便代码在运行时读取：

# Local validator (no cloud call)
SKILL_SESSION_ID={session-id} python3 scripts/validate_pipeline.py --file rendered.json

# Bundled script that itself calls a cloud API
SKILL_SESSION_ID={session-id} bash scripts/wait_cs_task.sh --cluster-id c-xxx --region cn-shanghai

# Terraform
SKILL_SESSION_ID={session-id} terraform apply

脚本和 Terraform 配置应从环境中读取 SKILL_SESSION_ID（若不存在，则默认为空字符串）。任何会自行调用 aliyun 访问云 API 的捆绑脚本，都必须发送相同的双令牌 UserAgent（目前为 scripts/wait_cs_task.sh）。

**领域扩展 — 云调用原子规则（强制）：**每次调用 SLS 的工具调用都必须恰好包含一条直接的 aliyun sls ... 命令，且参数值必须是字面量并已完整展开；命令必须以 aliyun sls 开头。不得通过 shell 变量、环境变量赋值、函数、别名、包装脚本、循环、命令替换、eval、管道、重定向（包括 2>&1）或复合命令（;、&&、||）隐藏云调用。只能使用小写且以连字符连接的 SLS 插件子命令，例如 get-project；绝不要使用 PascalCase OpenAPI 别名，因为这会绕过经过验证的命令 / 模拟契约。应在单独的本地步骤中计算时间戳或 JSON，然后将结果字面量填入云命令中。验证和验收读取也同样适用：不得使用循环、cd … 前缀、$VAR 或 $(…) 替换，包括 --from / --to 和 JSON 请求体中。绝不要将云调用写入 .sh 文件后再运行；命令记录是纯文本笔记，不是可运行的脚本。本地验证器必须接收命令实际返回的内容——将实际标准输出保存到文件并传入该文件；重新输入或通过 echo 输出预期响应属于伪造证据。使用 python3 -c 'import secrets; print(secrets.token_hex(16))' 生成会话 ID，并验证其符合 ^[0-9a-f]{32}$；绝不要将上方的示例 ID 复制到实际命令中。

5. 能力路由器

将请求归类为且仅归类为一种能力，然后在执行前加载其 references/navigation.md 条目。不要将整个知识库加载到上下文中。

能力	触发条件	必需输入	适配器	成功状态
install.deploy	安装/升级后收集并查询	区域、环境、实例或集群	ecs run-command / ssh / aliyun_cs / kubectl / aliyun_sls	安装门控 + U1-U6 + 查询
config.modify	修改现有配置 / 解析 / 字段	区域、项目、配置	aliyun_sls、本地验证器	配置 + 索引 + 数据均已验证
config.create	基础资源已存在，仅创建配置	区域、项目、logstore、machine_group、场景	aliyun_sls（默认）；仅当用户提出要求时使用 kubectl CRD	配置已存在、已绑定且有数据
onboarding.cloud	采集器正在运行，接通云端（API）	区域、项目、logstore、machine_group、来源	aliyun_sls、本地验证器	U1-U6 通过
machine_group.manage	创建/修改组、成员、绑定关系	区域、项目、组	aliyun_sls	对象 + 关系符合目标
lens.query	查询采集告警/状态/指标	业务项目、时间范围、lens 条目	aliyun_sls	查询完成且包含上下文
troubleshoot.basic	无数据 / 心跳异常	区域、项目、可选的 logstore/config/group	aliyun_sls、Lens	找到根因或单一阻碍项

完整路由器规范（when_to_use / out_of_scope / entry_signals / success|blocked|failure_state）：references/navigation.md。使用 references/task-model.yaml 中的统一任务对象跟踪多步骤工作。

---

6. 执行状态机

Classify → Preflight → Observe → Plan → Approve → Execute → Verify → (Rollback)

install.deploy 会在采集 Observe/Plan 之前插入额外的安装 Approve/Execute。不要在进程/Addon 阶段门控后结束。

• Classify：选择能力、场景（host/docker/k8s/host_agentsight）、环境（ecs|self_host|ack|self_k8s）、管理平面（api|crd）。对主机和 K8s 采集，默认使用 api。仅当用户明确要求 ClusterAliyunPipelineConfig / GitOps / kubectl apply CR 且已确认 kube-apiserver 可访问时，才设置 crd（references/crd-pipeline.md）。ACK 采集不得停留在 [AWAITING: KUBECONFIG]。对于会改变范围的输入，要向用户询问；绝不可猜测。如果用户提到 SLS、Log Service、LoongCollector、Logtail 或任何目录中的 routing_intent 标记，但没有提出具体操作，留在此技能中：在进行任何云端调用之前，先确认区域、项目/集群/主机以及预期操作；绝不可擅自执行超出范围的操作。

  Agentloop / AgentSight： Agentloop、AgentSight、input_agentsight、eBPF Runtime 或 ebpf-event → config.create（或在必须创建组时使用 onboarding.cloud），场景为 host_agentsight。加载 references/agentsight-agentloop.md 和 references/input-agentsight.md。名称由产品固定（runtime-ebpf-agentsight-config → ebpf-event）。锁禁止覆盖，不禁止 Plan：即使 get-logtail-pipeline-config 已返回该对象，仍要运行 scripts/render_pipeline.py + scripts/validate_pipeline.py + scripts/normalize_diff.py，并询问目录消息 r2_create_bind。确认后，仍要执行 create-logtail-pipeline-config（若未绑定，还要执行 apply-config-to-machine-group）。遇到 AlreadyExist / 已绑定时，记录锁 [Idempotent-Skip]，并且不得更新。主机 Linux，内核 >=5.10，采集器 >=3.3.9。不是 OBI/OTLP。 意图 / 参数澄清停止规则（强制）： 最多只问 一个 澄清问题，并用中文使用适用的精确目录消息：一般范围使用 missing_task_scope，Lens 使用 missing_lens_parameters。如果用户仍未提供具体值——尚未决定、只想要检查清单，或要求你不要运行命令——不要再次提问。在同一轮中输出一份精简的陈述式检查清单（区域、Project / 资源定位符、操作目标；仅针对 Lens 的请求：业务项目或 Lens 条目 + 时间范围），在最后一行写上 [BLOCKED: MISSING_REQUIRED_INPUT]，然后结束本轮——不得继续提问、使用问号、邀请用户提供数据、调用云服务、执行 Preflight 或 Observe。尤其不得在检查清单之后重复任何一个固定的澄清主题。只有在用户提供具体值后才继续。 项目定位：仅使用用户提供的前缀／交接信息；最多调用一次 list-project --project-name <prefix>，然后对解析出的完整名称调用 get-project；仅命中 list-project 不能证明目标存在，也不授权读取任何后续资源。只读配置视图和 Idempotent-Skip 检查也必须调用 get-project：绝不能从 EVAL_ACCOUNT_ID／名称解析直接跳到 get-log-store 或 get-logtail-pipeline-config。不得扩大或合成名称。零个匹配 → [BLOCKED: RESOURCE_RESOLUTION_FAILED] …；多个匹配 → 请用户选择。

• 预检：scripts/preflight.sh（CLI／插件／凭证／范围）。添加 --need-ecs（ECS）／--need-cs（ACK）／--need-kubectl（仅 self_k8s 安装，或选择启用 CRD）。仅硬门禁（CLI／SLS 插件／凭证／ACK --need-cs）：输出 [BLOCKED: PREFLIGHT_FAILED] gate=<gate>; <reason> 并停止。适配器不是硬门禁：

  • ECS：run-command 是唯一的主机通道。--need-ecs 只发出警告，不会导致硬失败。仍须运行 scripts/render_loongcollector_install_cmd.py，并且仍须询问目录消息 ecs_install，最后一行使用 [AWAITING: INSTALL_CONFIRMATION]。绝不能输出 [BLOCKED: PREFLIGHT_FAILED] gate=workbench／gate=ecs。确认后，必须使用 aliyun ecs run-command --biz-region-id <region> ... --instance-id <id>，并使用 aliyun ecs describe-invocation-results --biz-region-id <region> --invoke-id <id> 轮询；这些插件命令绝不能使用 --instance-id.1、--region-id 或 --region。不得使用 workbench exec／aliyun ecs-workbench／OOS。 **ECS 安装后的快速路径：**调用结果成功后，逐字复用用户提供的每个 Project、Logstore、机器组和配置名称。收集获批前，不得读取辅助程序源码、对映射命令调用 --help、重新安装／更新插件、重新运行预检，或写入 outputs/*／ran_scripts/*。只运行必要的 Observe 读取、渲染／验证／差异调用，然后立即提出收集确认问题。如果调用状态仍在运行，应将等待和轮询作为单独的工具调用；绝不能将 sleep 和轮询命令合并。
  • 缺少 self_k8s kubectl：这是第一个停止点——必须早于 Observe、Plan、值渲染或任何创建／绑定问题。准确询问目录消息 kubeconfig + [AWAITING: KUBECONFIG]，并结束本轮。绝不能输出 [BLOCKED: PREFLIGHT_FAILED] gate=kubectl。提供 kubectl 前，禁止云端写入／create-logtail-pipeline-config。用户拒绝或目录的 end 标记 → 停止；不得继续到 R2 创建／绑定。
  • self_host SSH：任何 create-*／apply-config-*／安装／INSTALL_CONFIRMATION 之前，必须恰好运行一次直接探测：ssh -o BatchMode=yes -o ConnectTimeout=8 <alias> -- true。使用用户现有的 SSH 配置；绝不能添加 StrictHostKeyChecking=no、UserKnownHostsFile=/dev/null 或任何会削弱主机密钥验证的选项。不得将探测封装在管道、tee、重定向、复合命令或可能掩盖其退出码的日志辅助程序中。如果别名缺失、无法解析或探测失败 → 立即准确询问目录消息 ssh，最后一行使用 [AWAITING: SSH]，然后停止；探测失败后，在输出这两行门禁前不得调用 write_file、更新计划或叙述报告。探测失败时不得询问安装确认句。不得创建／编辑 ~/.ssh/config、/etc/hosts、authorized_keys，也不得将别名改写为 127.0.0.1／localhost 来伪造可用通道。本轮不得进行任何云端写入。提示中提供的别名若无法使用，仍视为“无可用 SSH”。目录的 end 标记 → 仅输出 [CANCELLED: SSH_REQUIRED]；不得调用工具或继续安装。
  • ACK 收集使用 SLS API，不得询问 kubeconfig／--need-kubectl。
  • ACK 首次使用：--need-cs 仅在缺少 CS 插件时硬失败。未启用的 ACK（ErrorNotEnabled／cskpro）或缺少 AliyunCSDefaultRole，不属于 [BLOCKED: PREFLIGHT_FAILED]。安装确认后，运行 bash scripts/ensure_ack_prereq.sh --region <r>，然后对失败的 CS 写入重试一次。仅在用户要求时执行 create-cluster：使用 --biz-profile Default（绝不用 --profile），规格依次为 ack.standard、ack.pro.small。不得在生产环境臆造 sls-eval-loop-ack。

• Observe（只读）：获取当前对象、绑定和心跳；保存快照。选择插件前先读取采集器版本（list-machines 的 .binary）。如果用户消息已说明版本（例如 3.2.6／3.3.9／LoongCollector 3.2.6），使用该版本，不要询问。如果版本仍未知：准确询问目录消息 collector_version + [AWAITING: COLLECTOR_VERSION]，然后停止。不得假设是 3.x，不得默默选择 processor_json，也不得只为了解版本而询问 Lens。没有版本字符串的目录标记 collector_deployed_without_version 仍表示版本未知。 强制验证命令：只有 get-project、get-machine-group 和 get-log-store（对该 Logstore 执行任何创建／绑定操作前）才能证明对象存在。Observe 必须以 get-project --project <full-name> 开始（或先调用 list-project，再对解析出的名称调用 get-project）。对于 config.create／创建并绑定，必须在 Project 解析后、get-log-store 之前立即检查 get-machine-group（或 list-machines），以明确记录机器组预检查发生在配置规划之前。将前缀与 EVAL_ACCOUNT_ID 拼接不能证明对象存在，也不授权跳过 get-project 直接调用 get-log-store。get-project 的结果是后续调用中唯一可用的运行时项目名称。list-machines／get-applied-configs／list-log-stores 只能证明心跳或绑定，不能证明对象存在。只有在 get-* 返回 ResourceNotExist 后才可进入创建流程。即使遇到 ProjectNotExist，仍须将其余独立的 get 调用各执行一次（包括 get-applied-configs）。

• **Plan：**构建目标对象。从零开始的 onboarding.cloud 计划包含 Project、Logstore、Index、MachineGroup、PipelineConfig 和绑定，除非用户明确选择不建立索引；绝不能仅因提示中包含目录标记 binding_acceptance 就推断 Index 可选。强制检查点：每项计划中的 R2／R3／R4 资源或关系变更（包括 Project、Logstore、Index、MachineGroup、绑定和解绑）都必须有目标 JSON，并执行 scripts/normalize_diff.py，获得结果；非配置／索引对象使用 --kind auto。不得以原始 diff、目视检查或手写差异替代。退出码 3 表示“有效差异中包含变更”，不表示失败。配置／索引耦合必须按固定顺序处理：快照配置和索引 → 使用 scripts/validate_pipeline.py 验证完整目标配置 → 运行 scripts/normalize_diff.py --kind config → 运行 scripts/normalize_diff.py --kind index。验证退出码 1 会阻止写入。所有适用的强制脚本均成功执行前，不得进入 Approve。包含影响、风险、回滚和验证。mode=plan 不得调用写入命令。 **脚本执行证据必须可见：**每个必需的 Skill 脚本都必须作为独立的 shell／工具调用执行，并在该调用的 stdout 中保留其 JSON／状态。可以使用 tee 持久化相同的 stdout，但不得将所有脚本输出仅重定向到 outputs/*／ran_scripts/*，导致工具结果中只剩退出码。之后读取文件或手写执行记录，均不能替代可见的脚本调用证据。 **验证失败时必须立即停止：**如果 scripts/validate_pipeline.py 返回退出码 1 或 status=invalid，立即输出 [BLOCKED: VALIDATION_FAILED] 并结束本轮。不得运行 --cli-dry-run；不得执行任何 create／update／apply／remove／delete 命令；不得将实际写入返回的服务器端 4xx 错误当作验证证据。本规则优先于用户批准和所有后续 Execute 步骤。

• Approve：硬性门禁。对于每项 R2 操作（创建资源、更新配置、应用／绑定、创建／更新索引），在 Execute 之前必须明确输出规范化差异、询问用户确认，并结束本轮。每轮最多询问一个确认问题。对于中文请求，必须使用 Language and HITL Delivery Contract 中适用的精确主题，附带目录选项 approval 和 cancel，绝不能使用英文选项。只有明确的肯定答复才授权写入。R3：明确确认影响。R4：再次确认，并重述资源。 安装与采集审批门分开： 对于 install.deploy，首先仅询问环境专属的安装目录消息，并以 [AWAITING: INSTALL_CONFIRMATION] 结束本轮——绝不可使用 [AWAITING: R2_CONFIRMATION]。原始请求中的目录 install_intent 标记描述的是意图，不是单独的确认回复；只有在提出安装问题后收到的新用户消息，才能授权运行 run-command / SSH 安装 / 插件安装。安装成功后，如果需要新的 CR 或 API 配置/绑定，必须在新一轮询问目录消息 r2_create_bind，并以 [AWAITING: R2_CONFIRMATION] ask=1 作为最后一行，然后才能进行这些写入。两个审批门之间不要询问机器组标识或采集器版本。如果出现目录 cancel 标记或等效拒绝：输出 [CANCELLED: R2_CONFIRMATION_REJECTED]，报告目录 install_only_status，并且不得进行任何采集写入。如果 Observe 已与目标一致（通过 get 确认了 logstore/group/config/binding），则输出 [Idempotent-Skip]，且不要再次发起 create/apply。仅复用 ACK 默认采集配置也按同样方式跳过。

  第二审批门标记唯一性： 在安装后询问采集审批的那一轮中，完整的 [AWAITING: R2_CONFIRMATION] ask=1 标记只能出现一次，且必须作为最终回复行。在此之前，只能将待处理步骤称为“采集审批”；不得在 Plan/Todo 条目、工具描述、工具参数、代码块、输出文件、执行记录或叙述中写出该标记。完成最后一次验证/diff 调用后，不要写入执行记录或更新计划；立即输出固定问题和标记。

  解除绑定审批门独立： 创建并绑定与解除绑定需要分别确认。首先只询问目录消息 r2_create_bind。用户确认且相关写入（或完全一致时的 Idempotent-Skip）完成后，再于新一轮询问目录消息 r3_unbind。绝不可将解除绑定合并到创建并绑定的问题中，也绝不可在创建并绑定审批时运行 remove-config-from-machine-group（包括 --cli-dry-run）。

  不得跳过确认： 自动化、紧迫性、完整参数以及原始任务措辞都不能免除这一审批门。在等待回复期间，首次询问时输出中文问题和 [AWAITING: R2_CONFIRMATION] ask=1，结束本轮，并等待用户下一条消息。同轮写入属于审批门失败： 提出问题后，在下一条用户消息包含明确的目录 approval 标记之前，不得运行 --cli-dry-run、create-*、apply-config-* 或 update-*。

  严格审批门检查清单（批准 → 执行）： 0. 只有在计划确已准备就绪时才请求批准：scripts/validate_pipeline.py 已对任何配置载荷运行并通过，且每项计划写入都已运行 scripts/normalize_diff.py。未验证并生成 diff 就请求批准，属于审批门失败。

  1. 你自己生成的任何内容都不是答案。如果本轮结束时用户尚未表明决定，则输出 [AWAITING: R2_CONFIRMATION] ask=<n>，附上完全相同的问题并等待。
  2. 绝不可将原始任务措辞、“任务明确要求”、 “参数完整”或已呈现的计划表视为批准。
  3. 只有用户明确回复是/确认/批准，或给出等效的目录 approval 标记后，才能进入执行阶段。
  4. 对任何 R2/R3 写入执行 --cli-dry-run 都属于执行阶段：在获得明确批准之前禁止执行。展示计划但不询问批准就进行 dry-run，属于审批门失败。
  5. 违反此审批门即视为任务失败。 非回答规则（立即停止）： 空白回复、“稍后”、“还不确定”、任何目录中的 deferral 标记或任何等效的推迟答复，都不算批准。确认轮次开始时，将询问计数器 n 设为 1。每次收到推迟答复后，用一行重述仍在等待的资源和操作，以完全相同的中文确认主题重新询问恰好一次，并在最后一行写上 [AWAITING: R2_CONFIRMATION] ask=<n+1>（计数器按 1 → 2 → 3 递增）。不要重复输出问题或 AWAITING 标签。标签后不要添加空行。只重复问题而不带 ask=<n>，或不提问就用“慢慢来”之类的话委婉收尾，均违反此规则。用户在收到第三次询问后再次回复目录中的 deferral 标记时，下一轮回复只能包含 [BLOCKED: R2_CONFIRMATION_TIMEOUT]——不要进行第四次询问，不要写入，不要试运行。明确拒绝或取消 → 回复只能包含 [CANCELLED: R2_CONFIRMATION_REJECTED]。不要附加诸如 User rejected the proposed plan… 的英文说明。完整语义见：references/risk-and-approval.md。 **终止状态硬停止：**出现任何 [BLOCKED: …] / [CANCELLED: …] 标签后，不得再运行任何工具（包括 write_file）、试运行、写入或验证。安装成功后的集合门禁拒绝是唯一的报告例外：输出 [CANCELLED: R2_CONFIRMATION_REJECTED] 和确切的目录状态 install_only_status，然后立即结束本轮，不运行任何工具。权限拒绝时也可以列出 §2 中尚未运行的必需读取项，但必须明确说明执行已终止。所有其他终止轮次只能包含简短标签。只有用户重新开启工作后，才能通过新的计划 + 确认恢复。

• 执行：只运行已批准的命令，并带上 --user-agent，遵循 §4 原子规则。始终先单独调用 --cli-dry-run，再执行实际写入，确保请求被拒绝时不会更改状态。幂等性：创建/应用前先获取；如果状态匹配，则跳过试运行和写入，通过 get/list 验证，并在 Changes 中输出确切内容：[Idempotent-Skip] <create/apply-command> skipped; verified via <get/list-command> that state matches expectation.。如果 get 已证明目标 Project/Logstore 分片数/TTL 符合要求，则任何 create-project/create-log-store（包括试运行）都属于任务失败。遇到 AlreadyExist 时，执行 get 并比较 → 匹配则输出 Idempotent-Skip；不匹配则输出 [BLOCKED: EXISTING_RESOURCE_CONFLICT]。config.modify 例外：用户明确要求更改配置/索引（重命名字段、更改解析方式、同步索引）时，必须仍运行 scripts/normalize_diff.py，询问目录消息 r2_update，确认后执行 update-logtail-pipeline-config 和配套的 update-index（两者都必须先各自运行 --cli-dry-run）。即使快照已匹配，也不得跳过这两项写入，因为用户要求覆盖更新。创建/应用仍适用 Idempotent-Skip。**AgentSight 锁定规则：**仍需先制定计划并完成人机确认，然后运行 create-logtail-pipeline-config；遇到 AlreadyExist 时输出 [Idempotent-Skip]，不得更新。 **Logstore Idempotent-Skip 输出：**分片数/TTL 已匹配时，面向用户的最终回答必须包含跳过的命令名称，例如 [Idempotent-Skip] create-log-store skipped; verified via get-log-store that state matches expectation. **错误恢复（最多重试 3 次／共 4 次；保留 errorCode + requestID）：**优先使用 python3 scripts/classify_sls_error.py，并在叙述之前输出其 error_tag。映射规则：400/ParameterInvalid → [Error: parameter]，然后修正并重试相同 API → [RECOVERED: parameter_fixed]；429/WriteQuotaExceed → [Error: throttling]，退避后重试 → [RECOVERED: throttling_retry]；500 → [Error: internal]，重试相同命令 → [RECOVERED: internal_retry]；401/403 且消息表示所有权问题（does not belong to you）→ [BLOCKED: RESOURCE_RESOLUTION_FAILED]（不属于 RAM 人机确认流程）；其他 401/403 → [Error: permission]，然后按 §2 权限失败处理（询问目录消息 permission_recovery）→ 用户通过目录消息 permission_grant 授权时输出 [RECOVERED: permission_granted]（在同一轮重试完全相同的命令），用户通过目录消息 permission_decline 拒绝时仅输出 [BLOCKED: PERMISSION_REQUIRED]。试运行失败也使用相同分支；只有试运行成功后才能进行实际写入。

• 当 get-logs-v2 返回 meta.progress=Incomplete 时，表示查询未完成（不能将其视为传输成功并作为最终结果）：输出 [Query: Incomplete] attempt=<n>/4，然后按 §9 重试完全相同的请求。当 meta.progress=Complete 时，报告 Complete——不得输出 INCOMPLETE 或虚构未完成重试。

• 验证：执行后必须重新读取验收证据——每个已创建或更改的对象都必须通过其各自的 get-*（get-log-store、get-machine-group、get-logtail-pipeline-config、get-index）读取；读取两个绑定方向（get-applied-configs 和 get-applied-machine-groups）；并通过 list-machines 检查心跳。在适用的 get-index、两项绑定读取、list-machines 和业务 get-logs-v2 调用实际运行之前，不得宣布验证完成或开始编写最终报告。特别是，新建的机器组必须在创建后运行 get-machine-group；观察阶段的 404 不能作为验收证据。观察阶段读取反映的是旧状态，绝不能作为验收证据。针对 U1-U6 进行有界轮询（15 秒 × 最多 4 次）。每次创建/更新/绑定配置或执行接入流程后，必须在最终回答前运行业务 Logstore get-logs-v2 验收查询——不得以“配置已验证”“采集器无心跳”或“数据尚未到达”为由跳过，否则属于任务失败。报告观察到的数量/进度；如果没有返回行（count=0 / data=[]），必须说明目录消息 data_incomplete 和 data_empty，并提供 reason。U5 为空时，禁止使用任何目录标记 forbidden_empty_success。绝不能将零行等同于成功交付。最后一条面向用户的回答（包括后续解除绑定后的回答）必须包含目录消息 data_arrived 或 data_empty，并提供 reason。接入/验证后的用户最终摘要必须列出 Project 全名、Logstore、机器组和配置名称（不能只列出三个资源名称）。

• 回滚：只能依据执行前快照或已声明的逆向操作进行；绝不能凭记忆重建配置。 输入契约和停止条件：references/prerequisites.md。

范围与适配器规则

• 仅云端能力通过 aliyun sls 和本地验证器执行。现有仅云端评估仍禁止 SSH/kubectl。
• install.deploy 可使用 aliyun ecs run-command 和 aliyun ecs describe-invocation-results（ECS）、用户 SSH（已确认指纹，聊天中不得提供私钥）、aliyun cs（插件名称 loongcollector），以及用于 self_k8s package install 和选择性获取/应用 CR 的 kubectl。不得使用 workbench exec / OOS / kubectl exec / docker exec / 不受限的 root shell。 切勿打印 kubeconfig 或客户端证书；仅可写入权限为 0600 的临时文件。
• 安装后，主机路径必须调用 onboarding.cloud。K8s 路径必须复用官方 Project/机器组，默认通过 SLS API 创建流水线，然后执行 U1–U6 和 get-logs-v2。仅在用户明确请求时应用 CRD（references/crd-pipeline.md）。
• 单个请求内固定使用同一账号/profile、区域、项目、集群、组和配置。切换范围需要重新确认。
• 每个配置只能使用一个管理平面：API 或 CRD，绝不能同时使用。如果检测到双写，立即停止（references/pipeline-config.md、references/crd-pipeline.md）。由 CR 管理的配置不得通过 API 更新。默认使用 API 并不授权创建第二个管理平面。

---

7. 风险、审批与回滚

级别	示例	审批
R0 读取	list/get、状态、日志查询	自动
R1 本地	架构验证、渲染、差异比较	自动
R2 可逆写入	创建资源、更新配置、应用/绑定、创建/更新索引、安装采集器、kubectl apply CR	显示差异 + 一次确认
R3 高影响	移除/解绑、批量更改	说明影响后确认
R4 破坏性操作	删除项目/日志库/配置/组	二次确认，并重述涉及的资源

R2 确认是硬性门槛。 只有明确的肯定答复才授权执行；任务措辞绝不能视为隐式批准。创建并绑定与解绑是两个独立问题（参见 §6 SEPARATE UNBIND GATE）。拒绝和超时使用 §6 中的精确终态状态，回滚则是新的审批工作流。§6 TERMINAL-STATE HARD STOP 涵盖 [BLOCKED: PERMISSION_REQUIRED] 和所有其他终态标签：一旦发出，在完成新的计划 + 审批周期前，不得进行任何后续云端写入（包括 dry-run）。

详细信息、快照格式和回滚：references/risk-and-approval.md。更新前先获取（Update 采用覆盖语义——将未变更的字段一并带回）。创建前先获取（参见 §6 Execute — 对 AlreadyExist 的幂等处理）。新资源的回滚默认不采用删除方式。

---

8. 配置 / 索引耦合（硬性规则）

当处理器添加、删除或重命名字段时，你必须：1）同时生成配置差异和对应的索引差异；2）在一次合并审批中向用户展示两项差异，并请求一次确认；3）获批后，先依次运行两条直接的 dry-run 调用（config dry-run → index dry-run），再将两次实际写入作为两次连续、独立的调用执行（先 config write，紧接着 index write），中间不得运行其他命令、等待、检查状态或暂停。“紧接着执行”是指连续进行两次独立调用——绝不能用 &&、; 或任何其他 shell 链接方式将它们合并；§4 禁止这样做，而且链接调用失败会导致其中一项已应用、另一项未应用。绝不能“现在更新配置，之后再添加索引”，也绝不能将两项更改拆成两次确认。如果 dry-run 失败，则不得执行任何实际写入。如果索引写入在配置写入成功后失败，则此批次尚未完成：必须在同一轮中立即通过 §6 错误恢复分支重新发出完全相同的索引命令，保留原始 errorCode/requestID，并一并报告两项结果——不得猜测并重新设计负载，也不得在配置已更新而索引仍待处理时结束本轮。如果后端会自动同步索引，则应在计划和同一次确认中说明。

• status/status_code/http_status 默认使用 long；时间/延迟/字节类型根据语义选择。
• SLS 没有 float 字段索引类型。对于浮点数需求（例如 request_time float），映射为 double，并在索引差异中展示此映射。
• JSON 嵌套字段：明确声明父级 json 索引或扁平化字段索引。
• 前缀更改必须同时更新索引字段名和验收查询。
• processor_rename 仅支持扩展模式；JSON 重命名需使用全扩展模式的 processor_json → processor_rename，并使用复数 SourceKeys/DestKeys（绝不能使用 SourceKey/DestKey/processor_rename_native）。索引差异必须删除旧键并添加新键；http_status 默认使用 long。完整示例：references/index-coupling.md。
• 必须按以下顺序制定计划：配置/索引快照 → 对完整目标配置运行 scripts/validate_pipeline.py → scripts/normalize_diff.py --kind config → scripts/normalize_diff.py --kind index；不接受原始 diff。

强制命令映射：仅使用 Pipeline 名称（*-logtail-pipeline-config、get-applied-configs / get-applied-machine-groups、apply-config-to-machine-group / remove-config-from-machine-group）。创建标志：--project-name / --logstore-name / --group-name；读取/绑定：--project / --logstore / --machine-group。update-log-store 需要同时指定 --logstore 和 --logstore-name。绝不能使用经典的 get-config/get-logs/list-logstore 别名；经典 inputDetail 配置 → [BLOCKED: CLASSIC_CONFIG_UNSUPPORTED]。此映射中的命令均已验证，因此不要为它们运行 --help。索引：已存在→update-index，缺失→create-index；--line 使用 "chn": true；text 键的 token 必须是由分隔符字符串组成的 JSON 数组——拼接后的字符串会返回 IndexInfoInvalid: field token is of error format。出现 IndexInfoInvalid / token 格式错误时，只能通过 aliyun sls 修复（将 --keys 改写为由分隔符字符串组成的 JSON 数组，或传入任务工作区 JSON 文件中的键——绝不能使用 ~/.aliyun/config.json）。不要安装或调用 aliyun-log-python-sdk。如果 CLI 端修复在允许的重试后仍然失败，则输出 [BLOCKED: PARAMETER_UNRESOLVED] 并停止。完整规范：references/cli-contracts.yaml、references/index-coupling.md、references/field-conventions.md。

---

首次创建标志不变量：create-project 的首次试运行和实际调用都必须使用 --project-name；切勿用 --project 探测。create-log-store 使用 --logstore-name，create-machine-group 使用 --group-name。即使之后重试成功，失败的探索性写入调用也可能破坏有序评估。

9. SLS Lens（CloudLens for SLS）运行日志

Lens 是基本故障排查的主要数据源。运行日志查询本身使用公共命令 aliyun sls get-logs-v2。

入口发现。 先用 get-project 验证业务项目——业务项目不存在可以解释查询结果为空，不应报告为 Lens 故障。然后对其运行一次 get-logging（即使项目不存在），并运行 python3 scripts/parse_lens_logging.py。状态机：(1) 存在可用入口（loggingProject / 解析出的 Lens 项目和日志库）→ 验证并使用，不要询问 [AWAITING: LENS_ENTRY]；(2) 否则，若用户提供了 lens_project / lens_logstore → 验证并使用；(3) 否则，在所有独立的非 Lens 读取都已各发起一次后（包括即使遇到 ProjectNotExist 也要调用 get-applied-configs），精确询问一次目录消息 lens_entry，并将 [AWAITING: LENS_ENTRY] 作为最后一行输出——该轮面向用户的内容只能包含该问题和标签：不得给出结论、证据转储，也不得输出目录标记 root_cause_located。结束本轮并等待。绝不可复用业务 Project，也不可在其上虚构 internal-diagnostic_log；用户回答后，必须运行计划中的 logtail_alarm 和按版本路由的指标查询，然后撰写结论；(4) 若用户无法提供 → 继续独立的 MG/配置/业务检查，并设置 resource_status: Resource not found，绝不可捏造“没有告警”。最终 Lens/故障排查报告完成后，停止——不得再次询问 Lens 位置，也不得等待目录标记 end。

禁止事项：STAROps/JWT/控制台 Cookie；猜测 log-service-{uid}-{region}；发现失败后仍在业务 Project 上查询 Lens 主题；跳过仅询问一次的 HITL。[AWAITING: LENS_ENTRY] 仅适用于 troubleshoot.basic / lens.query。 接入/配置时缺少采集器版本应使用 [AWAITING: COLLECTOR_VERSION]，绝不可使用 Lens。

查询硬性约束（完整内容见：references/sls-lens-contracts.md、references/monitoring-queries.yaml）：不得使用 select *；按版本路由：>=3→loongcollector_metric，<3→logtail_profile/logtail_metric（即使失败也必须执行该 get-logs-v2）；logtail_alarm 按 project 过滤（where 中绝不可使用 config_name）；若为 Incomplete → 输出 [Query: Incomplete] attempt=<n>/4 并进行完全相同的重试，最多 4 次；若 4 次后仍不完整，则标记为 INCOMPLETE；若为 Complete → 报告 Complete，绝不可捏造 INCOMPLETE；报告 Lens 项目/日志库/主题/时间窗口/路由/完整性。

---

**强制版本路由调用：**对于每个已知采集器版本 >=3，包括 3.2.6，都必须执行单独的 aliyun sls get-logs-v2 查询，其中包含 __topic__: loongcollector_metric。logtail_status 查询是额外证据，不能替代指标查询。即使较早的 Lens 查询返回空结果或错误，也必须执行此调用。

10. 故障排查（无数据、心跳）

固定链路：classify → heartbeat & version → config & binding → alarm/metric → business data → minimal fix → re-verify。

• 硬性规则 — 诊断链路不得提前终止。 如果只读步骤返回 ResourceNotExist/ProjectNotExist/LogStoreNotExist/LoggingNotExist，则执行所有剩余的独立诊断步骤。get-applied-configs 独立于 Project 是否存在 — 即使 get-project/get-machine-group 已返回 404，也要执行一次；不得用 get-logtail-pipeline-config 替代绑定证据。业务 get-logs-v2 也相互独立 — 即使 Project 缺失，也要针对指定的业务 logstore 执行一次（预期返回 ProjectNotExist / LogStoreNotExist）。Lens 入口询问轮次只能包含目录消息 lens_entry 和 [AWAITING: LENS_ENTRY]；该轮次不得提供报告。最终报告之后不得追问。对于依赖 Lens 的步骤，发生任何入口发现失败后，都遵循 §9（询问一次 + [AWAITING: LENS_ENTRY] → 等待 → 再查询）— LoggingNotExist 和 ProjectNotExist 均适用，因为 Lens 入口位于不同的 Project 中，业务 Project 缺失并不能说明 Lens 的情况。未询问就报告未找到 Lens 入口，或在询问 Lens 的同一轮次撰写最终结论，都属于任务失败。每个对应的 get/query 命令都执行一次（或在 HITL 提供入口后执行），保留其准确命令和错误代码，在适用时记录 resource_status: Resource not found，然后继续。中途停止属于任务失败。此继续规则不授权写入，也不覆盖权限硬性停止规则。
• 云端可见性与采集器侧证据相互印证；不得互相替代。
• 无数据：get-logtail-pipeline-config --config-name + list-machines + §8 中的精确绑定查询 → 按 Project 查询 logtail_alarm → logtail_status → 与版本匹配的 pipeline topic → 业务 logstore。
• 心跳异常：list-machines → logtail_status；如果 Lens 不可用，则列出主机侧项目（采集器进程、上报区域、账户 ID、user_defined_id）。仅涉及云端的任务用文字说明。install.deploy 可复用 run-command/SSH/kubectl get 查询只读状态。
• 每项故障排查结论都必须输出 references/troubleshooting.md 中定义的字段完整证据行（Heartbeat / Alarm / Collection，以及在执行相应检查时的 Binding / Pipeline）。使用 N/A/unknown，不得省略字段；遗漏任何必填字段都属于任务失败。资源缺失时，resource_status: 必须为英文标记 Resource not found — 目录中的 not_exists 标记不能替代它。面向用户的最终答复（不只是 outputs/*.md）必须包含这些行。如果用户之后在已提供证据后发送目录 end 标记，则不要再写会成为最终答复的简短结束语，或者在该结束语中重复相同的证据标记（包括 resource_status: Resource not found）。

操作手册和告警处理卡：references/troubleshooting.md、references/alarm-catalog.yaml。

11. 输出约定

每次执行至少输出：结论（完成/部分完成/受阻/已回滚）· 范围（profile-id/region/项目全名/logstore/group）· 证据（关键结果；故障排查时，面向用户的答复必须复现 §10 中所有适用的证据行，包括 Binding/Pipeline）· 变更（规范化差异 + 实际操作，包括每条 Idempotent-Skip 说明）· 验收（U1-U6 结果；完成采集写入后，面向用户的最终答复（而不仅是 outputs/*.md）必须包含 catalog data_arrived 或 data_empty，以及 reason）· 回滚（是否需要？是否已执行？快照/逆向操作）· 下一步（单个阻塞项或最小下一步操作）。如果故障排查的下一步会创建、更新、绑定或修复资源，必须列出最小写入集，并明确说明需要新的规范化差异和用户的明确确认；诊断轮次本身不执行任何写入。仅列出 Logstore / 机器组 / 配置而遗漏项目全名的 Onboarding/Verify 摘要不符合此约定。仅提供文件报告不算最终答复。

不得输出密钥、完整命令历史或无关日志；如需审计，请输出脱敏后的命令 + 请求 ID（scripts/redact_output.py）。失败时保留原始错误代码 / 请求 ID / 脱敏上下文；绝不可伪造成功。

---

12. 全局规则

1. 优先使用 §8 和 references/cli-contracts.yaml 中经过验证的精确映射。SLS 命令已预先验证——不要用 --help 重新检查。仅对未记录的命令，在 Plan 之前使用 aliyun sls <cmd> --help。绝不探查更短的别名。ACK 使用 aliyun cs，插件名称为 loongcollector。首次启用时运行 scripts/ensure_ack_prereq.sh（open-ack-service 和 CS 角色）——用于测试夹具的 eval hook 也可能执行相同操作，但 Skill 仍必须了解这一点。K8s 采集默认使用 create-logtail-pipeline-config，并绑定 k8s-group-${cid}。仅在选择启用时才使用 kubectl apply 应用 ClusterAliyunPipelineConfig。
2. 使用 get-logs-v2（绝不使用已弃用的 get-logs）。get-logs-v2 的 --from/--to 参数使用 UNIX 秒数。
3. 获得批准后，每次实际写入之前都要单独运行一次 --cli-dry-run；dry-run 不等于业务批准。对于 §8 中相互关联的写入，必须先完成两次 dry-run，再连续执行两次实际写入。精确匹配的 Idempotent-Skip 不运行任何调用。
4. Update 之前先 Get；Update 会覆盖数据——保留所有未更改的字段。
5. Collector 版本为 >=3.x 时，优先使用原生插件。版本未知时，询问目录消息 collector_version——不要假定插件系列。原生插件无法满足需求时使用扩展插件（例如 processor_rename），并说明其中的权衡。
6. 不得使用 kubectl exec / docker exec；不得使用管理员项目、starops、内部 MCP 或私有控制台 API。仅按规定在 install.deploy（及其只读状态后续检查）中使用 SSH/run-command/kubectl。绝不使用 Workbench/OOS。
7. 未知告警代码：查阅官方文档或 references/alarm-catalog.yaml；绝不凭记忆解释。
8. 绝不要通过 sudo 运行 aliyun。以当前用户身份直接运行；绝不要切换用户、Shell、账号或凭据配置文件来绕过错误。
9. 绝不要修改或清除由你创建之外的环境变量或 CLI 配置。发生基础设施级故障（非 API 错误）时，使用完全相同的原子命令重试一次，然后报告原始输出并停止——绝不捏造预期响应。
10. 根据调用自身的响应——errorCode、requestID、消息——以及 references/ 中的资料，诊断调用失败。绝不要检查 CLI 二进制文件、其安装目录、本地配置文件或环境来解释调用行为；这不属于此 Skill 的范围，且可能泄露用户配置。
11. 原始请求和完整参数绝不能视为隐含的 R2+ 授权；只有明确的事后差异审批才有效。
12. 每次 SLS 云端调用都必须是一个带有字面参数的直接原子命令。
13. 只能使用随附的 scripts/ 辅助脚本：preflight.sh、render_pipeline.py、validate_pipeline.py、normalize_diff.py、redact_output.py、classify_sls_error.py、parse_lens_logging.py、render_loongcollector_install_cmd.py、wait_cs_task.sh、render_crd.py、ensure_ack_prereq.sh。在 §6/§8 工作流的指定节点必须使用 validate_pipeline.py/normalize_diff.py；对于非 2xx 响应，必须使用 classify_sls_error.py；运行 get-logging 后必须使用 parse_lens_logging.py。如果用户只要求在本地渲染/验证 ClusterAliyunPipelineConfig，则运行 render_crd.py + validate_pipeline.py 后停止——不得使用 aliyun cs、kubectl，也不得连接集群。绝不 pip install 云 SDK，也绝不导入 aliyun.log。
14. 每轮最多提一个问题，提问后立即结束该轮并等待用户的下一条消息；绝不自行回答自己的问题。

---

13. 成功验证

统一验收 U1-U6（配置对象 / 组绑定 / 应用状态 / 心跳与版本 / 数据到达 / 字段与索引）的通过条件和失败处理路径：references/acceptance-criteria.md。各步骤的验证命令：references/verification-method.md。

---

14. 清理

清理属于 R3/R4。删除前先解绑；删除时重述资源。此技能创建的配置应按以下顺序处理：remove-config-from-machine-group → delete-logtail-pipeline-config →（可选）仅在用户明确确认后执行 delete-index / delete-log-store。请参阅 references/risk-and-approval.md。

---

15. 最佳实践

1. 优先使用 CLI，并使用插件模式的连字符子命令（aliyun sls get-logs-v2），绝不使用经典的 RunXxx 风格或未记录的别名。
2. 进行任何云调用前，确认地域、项目和其他用户特定参数；绝不硬编码账户值。
3. 每次云调用都使用双令牌 --user-agent（AlibabaCloud-Agent-Skills/alibabacloud-loongcollector-ops + session/{session-id}）；对于会自行调用云 API 的脚本，注入 SKILL_SESSION_ID。
4. 任何 R2+ 写入前，先通过标准化差异进行审批；将试运行和写入作为单独的原子调用执行。
5. 遵循 references/ram-policies.md 中的最小权限 RAM 策略；权限错误通过 §2 的关卡处理。
6. 破坏性清理必须经过 R3/R4 确认；删除前先解绑。
7. 渐进式披露：仅加载与当前能力对应的 references/* 条目。
8. 决策待定期间，重复提出同一问题并等待；沉默和推迟都不代表同意。

---

参考资料

文件	内容
references/navigation.md	能力路由器规范（输入、适配器、状态）
references/prerequisites.md	预检关卡和输入契约
references/cli-installation-guide.md	Aliyun CLI + SLS 插件安装
references/cli-contracts.yaml	aliyun sls 命令契约 + 状态
references/related-commands.md	完整的 aliyun sls 命令表
references/ram-policies.md	各工作流的 RAM Actions + 权限关卡
references/risk-and-approval.md	R0-R4、快照、回滚
references/machine-group.md	机器组、身份、心跳、版本
references/pipeline-config.md	Pipeline 配置模型、先获取后更新
references/plugin-version-gates.yaml	1.x/2.x/3.x 插件关卡
references/index-coupling.md	配置/索引的同批次规则、反模式
references/field-conventions.md	字段命名、索引类型映射
references/task-model.yaml	统一任务对象
references/scenario-matrix.yaml	host/docker/k8s/host_agentsight 信号和输入
references/agentsight-agentloop.md	Agentloop AgentSight 固定 Pipeline、ProbeConfig、脱敏
references/input-agentsight.md	input_agentsight 架构、内置项、版本/内核、RawHttpsFallback
references/sls-lens-contracts.md	Lens 入口状态机、主题/字段
references/monitoring-queries.yaml	Lens SQL 库（get-logs-v2）
references/troubleshooting.md	无数据/心跳操作手册
references/alarm-catalog.yaml	告警代码处理卡片
references/acceptance-criteria.md	安装阶段关卡 + U1-U6 + CLI 验收模式
references/verification-method.md	各步骤的验证命令
references/install-ecs.md	ECS Workbench + loongcollector.sh
references/install-host.md	自托管 SSH + 相同脚本
references/install-ack.md	ACK 插件 loongcollector + 首次使用 open-ack-service / CS 角色
references/install-k8s.md	自托管 k8s 自定义软件包
references/crd-pipeline.md	可选的 ClusterAliyunPipelineConfig + 临时公共 KubeConfig
references/knowledge-sources.md	来源溯源、漂移跟踪