signadot-plan

Signadot：编写和运行计划

此技能不用于概念性地解释计划。 如果用户询问“什么是 计划”“计划如何运作”，或想要教程或概述，请勿使用此 技能。请引导他们查看 Signadot 文档。此技能用于 生成、执行或迭代具体计划。

Signadot 计划是由操作调用构成的不可变编译型 DAG。每个步骤 都会调用组织目录中的一个操作，并将输入关联到计划参数、 字面值或上游步骤的输出。架构、操作可用性和操作契约可在运行时发现；编写计划前请先获取这些信息。

参考资料索引

只有在工作流涉及相应主题时，才加载以下单跳参考资料：

• references/schema-and-actions.md： 发现计划架构、操作目录、操作 ID、已禁用的操作， 以及操作主体契约。
• references/spec-authoring.md：编写 YAML 规范、refs 与 values、深入查看规则、条件、extraInputs、 extraOutputs、机密信息以及常见的验证器错误。
• references/routing-and-cluster.md： routingContext、路由键注入、自定义路由标头、查询参数 回退以及 spec.cluster。
• references/running-and-debugging.md： 创建和运行命令、执行 JSON、日志、输出制品、退出代码，以及 区分运行器故障和脚本故障。
• references/tagging.md：何时添加标签、重新添加标签的 安全性以及 selectionHint。
• references/worked-examples.md：关于基线流量、 沙盒路由流量、条件步骤和输出的简短计划片段。

核心工作流

1. 明确目标和副作用。 确定计划需要验证或自动化什么、将针对什么目标运行，以及是否需要创建、运行或打标签。只有在目标、集群／路由上下文或副作用风险不明确时才询问。
2. 发现架构和目录。 起草前获取 signadot plan schema 并检查已启用的操作。阅读 schema-and-actions.md。
3. 根据契约选择操作，而不只看名称。 对每个选定的操作，获取其主体和 ID。步骤规范使用 action.actionID，而不是操作名称。
4. 确定路由和集群形态。 如果计划针对沙箱、路由组、路由键或应命中隔离代码的 .svc URL，起草前阅读 routing-and-cluster.md。
5. 起草 YAML 规范。 直接编写 params、steps、output 以及可选的 cluster／runner。每个步骤的 action 中仅包含 actionID；服务器会在创建时保存其余操作契约的快照。阅读 spec-authoring.md。
6. 创建前自行检查。 确认 refs 仅使用路径表达式，每个参数都由操作或 extraInput 声明，钻取来源有架构，条件读取的是已解析参数，字面值中不包含机密，并且每个发起流量的步骤都有正确的路由上下文。
7. 创建，然后准确检查验证错误。 使用 signadot plan create -f <spec.yaml> -o json。服务器会在创建时进行验证，并在遇到第一个问题时失败；应修复具体问题，而不是大范围重写。
8. 按需运行并迭代。 使用计划 ID 或标签运行，并添加 -o json；显式获取失败步骤的日志或输出工件，然后使用修正后的参数或新的计划规范重新运行。阅读 running-and-debugging.md。
9. 仅在计划可复用时打标签。 默认不为一次性计划打标签。如果需要标签，请在应用前检查现有标签状态，并在创建计划时添加有用的 selectionHint。阅读 tagging.md。
10. 结束时提供持久标识符和证据。 报告创建或运行的内容、目标、使用的参数、检查过的输出，以及任何待执行的操作。

工具集成与 CLI 使用

如果集成的 Signadot 工具（MCP 服务、插件、IDE 扩展或类似工具）提供控制平面读取信息——集群、沙箱、路由组、工作负载、端点——优先使用其输出，而不是凭记忆填写。否则，使用 CLI 获取相同信息。

除非集成明确涵盖相同命令，否则计划相关操作请使用 Signadot CLI：

signadot plan schema
signadot plan action list -o json
signadot plan action get <name> -o json
signadot plan create -f <spec.yaml> -o json
signadot plan run <plan-id> --param k=v -o json
signadot plan x logs <exec-id> <step-id>
signadot plan x get-output <exec-id> <name>
signadot plan get <plan-id> -o json
signadot plan tag get <name> -o json
signadot plan tag apply <name> --plan <plan-id>

副作用策略

操作	默认行为
读取架构、操作、集群、标签、计划、执行记录、日志和输出	自主执行
为用户请求的任务创建未打标签的计划	规范和目标明确时自主执行
针对开发／测试沙箱或明确的非生产目标运行新创建的计划	参数和集群／路由目标明确时自主执行
针对生产环境、面向客户的共享目标或不明确的目标运行任何计划	先询问
应用用户请求的新标签	确认该标签尚未指向重要对象后执行
重新指向现有标签	使用 plan tag get 检查；除非用户明确要求进行该次重新标记，否则覆盖前先询问
在规范或聊天摘要中包含机密值	绝不；请使用计划参数和 --param-secret

基本规则

• 以 Schema 为准。 如果此技能与 signadot plan schema 冲突，请遵循 Schema。
• 操作按组织范围限定。 仅筛选 status.enabled == true；已禁用的操作无法被已创建的计划引用。
• 计划不可变。 后续更新操作不会影响现有计划。请编写新的规范并创建新计划，以应用操作更新。
• 步骤顺序由依赖关系决定。 数组顺序不等于执行顺序；引用关系决定 DAG。
• 引用是路径，不是表达式。 使用 params.<name> 或 steps.<id>.outputs.<name>，可选地深入访问；对于运算符、条件判断、字符串拼接或转换，请使用组合操作。
• 深入访问需要 Schema。 来源参数或输出必须声明 Schema，且运行时值必须是 JSON。
• 路由分为两部分。 routingContext 会设置 SIGNADOT_ROUTING_KEY 等环境变量；出站请求仍需在受支持的标头或查询参数中注入路由键。
• spec.cluster 不等于 routingContext。 Cluster 决定运行器的运行位置；路由上下文决定步骤如何定向流量。
• 标记是可选的。 标签是可复用计划的稳定指针，不是每个草稿的默认命名方式。
• 执行至少一次。 重试或重新运行时，步骤可能运行多次。操作代码应具备幂等性；不要编写假定只执行一次的计划。

快速参考

读取时使用 -o json；CLI 已会美化输出 JSON，因此仅在筛选时才通过管道传给 jq。 写入操作（plan create）使用 YAML 文件。

想要……	方法
扫描操作	signadot plan action list -o json | jq '.[] | {name, description: .status.description, enabled: .status.enabled}'
读取单个操作的正文	signadot plan action get <name> -o json | jq -r .spec.body
获取操作 ID	signadot plan action get <name> -o json | jq -r .id
获取计划 Schema	signadot plan schema
检查关键 Schema 字段	signadot plan schema | jq '.properties.params, .properties.output, .properties.steps.items'
创建计划	signadot plan create -f plan.yaml -o json
按 ID 运行	signadot plan run <plan-id> --param k=v -o json
按标签运行	signadot plan run --tag <name> --param k=v -o json
获取步骤日志	signadot plan x logs <exec-id> <step-id>
获取计划输出	signadot plan x get-output <exec-id> <name>
获取步骤输出	signadot plan x get-output <exec-id> <step>/<name>
批量获取所有输出	signadot plan x get-output <exec-id> --all --dir ./outputs/
获取计划详情	signadot plan get <plan-id> -o json
检查标签	signadot plan tag get <name> -o json
为计划添加标签	signadot plan tag apply <name> --plan <plan-id>

最终报告

根据任务情况，包含以下已有内容：

• 计划 ID、执行 ID，以及已创建或更新的标签名称。
• 集群、沙箱、路由组、路由键，或明确说明此次运行不依赖基线／集群。
• 使用的参数；隐去机密值，仅在安全时注明机密引用的名称。
• 所选操作的名称和 ID，尤其是在使用了相近替代项时。
• 检查的输出以及最终通过／失败信号。
• 尚未解决的步骤错误、日志位置或制品命令。
• 遗留的副作用：未添加标签的计划、重新指向的标签名称、生成的 YAML 文件，或需要操作员后续处理的事项。