volcengine-tls

Volcengine TLS（volclog）

改编自 volcengine-tls/ve-tls-cli 中的 volclog-core（Apache-2.0）。命令示例保留上游原生的 volclog ... 格式；运行时请使用 ve volclog ...（需要 ve >= 1.1.11），后续参数保持不变。

概述

仅将此技能用于 Agent 专用的增量知识。

将此文件视为 volclog 的主要通用操作模型，而非特定环境的引导说明或 API 参考。本文件是行为摘要；详细信息以参考资料为准。如果 volclog tool describe ... 或 volclog workflow describe ... 已能回答问题，请停止并遵循其约定，而不要在此处重复添加指导。

操作原则

• 将 tool describe 或 workflow describe 视为契约的事实来源。首先阅读 tool describe 或 workflow describe。
• 将配置文件配置视为运行时选择器问题，而非区域发现流程。
• 从运行时选择器的角度思考：活动配置文件、显式的 --profile <name>、单次使用的 --secrets-file、context.secrets_file，或进程范围内的环境凭据。
• 已发布的公共 API 使用 tool，由 CLI 管理的编排使用 workflow，仅在方法和路径已知时使用 raw。
• 单次调用的 App、LogApp、Trace 和 TraceScore 功能使用 tool；仅在需要由 CLI 管理的跨调用扩展时，使用 workflow app.resolve-resources 或 app.resolve-topic-ids。
• 当 tool exec 或 workflow exec 已支持时，优先使用 --input '{...}' 等结构化 JSON 输入。

运行时选择器模型

• 在确认可用的运行时选择器之前，将执行环境视为未知。
• 不要假设活动或默认配置文件就是适用于当前任务的选择器。
• 仅当确实需要发现本地配置文件时，才运行 volclog configure list。
• 仅当契约或任务明确要求覆盖时，才使用 region。不要从端点或域名推断。
• --profile/context.profile 和 --secrets-file/context.secrets_file 是运行时选择器，不是业务输入字段。
• 切勿在提示词、记忆、请求产物或技能内容中读取、打印、导出或持久化 AK/SK 或令牌值。

标准 Agent 循环

发现 -> 描述 -> 执行 -> 读取结果

1. 确定运行时选择器。
   • 确定本次运行使用配置文件、密钥文件还是环境凭据
   • 如果需要发现本地配置文件，运行 volclog configure list
   • 在命令或上下文中明确指定所选的选择器
2. 发现可调用的功能。
   • volclog tool list
   • volclog tool list <group>
   • volclog workflow list <group>
3. 阅读契约。
   • volclog tool describe <group.action>
   • 在编写嵌套请求时，或紧凑输出未包含预期的可选字段时，使用 volclog tool describe <group.action> --view full
   • 将紧凑视图视为发现摘要，将完整视图视为请求编写契约
   • volclog workflow describe <group.command>
4. 使用结构化输入执行。
   • volclog tool exec <group.action> --input '{...}'
   • volclog workflow exec <group.command> --input '{...}'
   • volclog raw --method <METHOD> --path <PATH> --body '{...}'
5. 按以下顺序读取结果。
   • status（"success" 或 "failed"）
   • summary.deliveryMode
   • 扁平的 error 对象（当 status 为 "failed" 时）
   • data 下的业务字段（当 status 为 "success" 时）

参考资料查阅

• 默认不要阅读每个参考文件。
• 先阅读 tool describe 或 workflow describe。
• 只有在执行 describe 或 list 后仍不清楚操作界面时，才阅读 references/routing.md。
• 只有在任务明确涉及多次调用且需要了解停止条件时，才阅读 references/sops.md。
• 只有在明确了契约后，运行时语义、交付模式或恢复策略仍不清楚时，才阅读 references/best-practices.md。
• contract_cache_hint 和 contract_digest 来自 tool describe 或 workflow describe 的输出。阅读 contract_cache_hint.safe_scope 和 contract_cache_hint.refresh_when；只有在相同 CLI 版本仍报告相同的 contract_digest 时，才复用缓存结果。
• 一旦某份参考资料解决了当前疑问，就停止查阅；不要为了“以防万一”而继续浏览其他参考资料。

关键规则

• 不要猜测命令名称、工具 ID、工作流 ID、JSON 字段或输出结构。
• 如果仍不清楚操作 ID，先运行 volclog tool list <group> 或 volclog workflow list <group>，再做判断。
• 具体操作的 risk、recovery 和 usage_constraints 优先于下方的通用恢复映射。
• 将 high-risk-retry 视为重试风险很高的警告。结果不明确时，只能通过契约指定的 get/describe/list 操作进行核实；否则应停止并升级处理，而不是自动重试。
• 不要将人类使用的快捷命令作为 Agent 的主要操作流程。
• 不要重复 tool describe 或 workflow describe 中已有的架构细节。
• 不要仅仅因为 shell 命令更短，就把有效的 tool exec 或 workflow exec 请求改写为包含大量标志的快捷命令形式。
• 不要将 volclog 输出传递给 jq 或 grep，仅仅为了重新查找架构或字段路径。
• 首先阅读完整的 JSON 信封；只有在已知所需信封路径时，才使用 --jmes-filter。
• 任何写入或破坏性更改之前，优先使用 --dry-run，但仅限 raw、tool exec 或 workflow exec。
• 将 --dry-run 视为契约或计划验证，而不是业务查询正确的证明。
• 如果字段名称唯一，优先使用扁平 JSON 输入，而不是手动嵌套。

错误恢复速查表

仅在阅读操作的 risk、recovery 和 usage_constraints 后，才将此表作为信封执行失败后的默认首要响应。操作契约优先。只有在需要了解下方快速操作之外的运行时特定细节时，才阅读 references/best-practices.md。

信号	下一步操作
error.kind=validation	返回 describe，先修正结构或选择器问题。
error.kind=auth 或 401	重新检查运行时选择器，然后检查凭据，最后检查端点或区域覆盖设置。
403 Forbidden	在扩大权限排查范围前，重新检查租户或配置文件是否匹配。
error.kind=usage	重新运行 tool list 或 workflow list；不要臆造别名。
error.kind=unsupported_feature	阅读 error.hint，然后移除不受支持的标志或切换到指定接口；对于非 LogApp Topic 解析，应切换到 app.resolve-resources。
error.kind=incompatible_flags	移除一个冲突标志，然后重新运行。
error.kind=filesystem	重试前修正 --output-dir、本地路径或权限。
error.kind=decode	阅读 error.hint，如果存在错误的筛选条件或投影，则将其移除，然后不带筛选条件重新运行，或使用 --trace-dir。
error.kind=server	阅读 error.code 和 error.requestId；仅当操作契约允许且故障明显是暂时性的，才使用退避策略重试。
error.kind=config	运行 volclog doctor 检查主机端配置，然后查看报告中的运行时问题。
error.kind=unknown	先阅读 error.hint，再阅读 error.message 或 error.details；只有在仍需更多细节时，才使用 --dry-run 或 --trace-dir 重新运行。
ResultStatus=incomplete	缩短时间窗口并重新运行，然后再依据计数或空结果作出判断。

volclog doctor 会检查凭据、端点和本地设置等主机/运行时配置。它不能取代 describe，也不会验证业务查询语义。

大结果处理

• 将接口选择与交付方式分开考虑。
• 结果可能较大时，提供可写入的 --output-dir。
• 根据 summary.deliveryMode 确认运行时实际采用的方式。
• 如需了解 outputMode、deliveryMode、文件交付和 --jmes-filter 的确切语义，请阅读 references/best-practices.md，而不是在此重复说明。

速查表

需求	优先使用
已选定公共 API 契约	volclog tool describe <group.action> / volclog tool exec <group.action>
已选定 CLI 工作流	volclog workflow describe <group.command> / volclog workflow exec <group.command>
需要发现操作或工作流 ID	volclog tool list <group> / volclog workflow list <group>
需要帮助选择接口	阅读 references/routing.md
需要多步执行顺序	阅读 references/sops.md
解析 App 资源图	volclog workflow describe app.resolve-resources / volclog workflow exec app.resolve-resources
解析 LogApp App 的 Topic ID	volclog workflow describe app.resolve-topic-ids / volclog workflow exec app.resolve-topic-ids
需要运行时、错误或恢复语义	阅读 references/best-practices.md
使用确切的方法/路径	volclog raw --method ... --path ...
对无状态运行进行身份验证	主机选定的本地配置文件 -> 单次使用的 --secrets-file 或 context.secrets_file
需要确保安全地复用契约	仅当同一 CLI 构建版本仍报告相同的 contract_digest 时，才复用缓存结果