这篇教程不以“Agent 回答得像不像专家”为通过标准。你要证明的是：它处理了正确的失败构建，只拿到完成任务所需的权限，缺少输入和越权时会失败，输出能被普通 Pipeline step 读取，触发运行也能追溯到明确身份，最后可以完整撤销。
本文使用固定金丝雀 WORKER-FAIL-743。它只用于确认输入、日志和输出没有串线，不是密码，也不要换成真实凭据。
**核验边界：**本站核读了 2026-09-10 可访问的 Harness 官方文档并静态检查下载材料，没有登录 Harness 账号或执行下列实验。界面、功能开放情况和内部步骤名称以你的租户与实际运行结果为准；验收表默认全部是“未验证”。
先下载三份材料
- W01–W14 空白验收表：逐步填写实际 execution、证据位置与状态。
- 失败构建运行卡：冻结输入、输出合同、权限和撤销记录。
- Worker Agent Pipeline 引用样例：只作字段对照，替换占位符并按当前 Schema 校验后再使用。
不要在下载材料里记录 PAT、模型密钥、完整客户日志、Secret 值或真实生产资源名称。
完成路线
| 阶段 | 步骤 | 必须留下的证据 |
|---|---|---|
| 选型与样本 | W01–W03 | 入口决策、冻结的失败样本、功能与运行基础设施 |
| Agent 合同 | W04–W07 | 模型连接、输入输出合同、Catalog 版本、Pipeline 引用 |
| 权限与运行 | W08–W10 | 最小权限、手动 execution、下游读取结果 |
| 负例与触发 | W11–W13 | 缺输入、资源不存在、越权、错误动词、触发身份 |
| 撤销 | W14 | 暂停、回滚、删除临时资源与权限收回 |
任何硬失败项不通过，都不能把试点记为完成。
W01：先选对入口，不要把所有 Harness AI 都叫 Worker Agent
同样是“构建失败后帮我定位”，实际可能是四类不同任务。
| 你真正需要的结果 | 先评估的入口 | 本次完成条件 |
|---|---|---|
| 在编辑器查看 execution、日志、审批或重新运行 | Harness VS Code Extension | 找到正确 execution、commit 与首个失败 step |
| 每次运行都产生结构化分析并交给后续 step | Worker Agent | Agent 作为 Pipeline step 执行，输出可被普通 step 读取 |
| 处理代码审查、覆盖率或候选修复 | 对应版本的 Harness Code Quality 能力 | 实际 diff、测试输出与候选提交 SHA 可以复查 |
| 让外部 AI 客户端读取 Harness 资源 | Harness MCP Server | 客户端发现工具，并通过资源正例与越界负例 |
VS Code Extension 当前文档强调 Pipeline 监控、日志、审批、重新运行、终止和 AI 调试入口。它可以帮助人工定位，但不会因为安装扩展就自动在每次 Pipeline 中生成结构化结果。
**W01 通过条件：**在运行卡写下唯一入口和不选择其他入口的原因。若需求只是查看日志，就在这里结束 Worker Agent 试点，避免为了“用了 AI”增加 Pipeline 复杂度。
W02：冻结一次可复查的失败构建
选择测试项目中已经发生、允许用于诊断的一次失败运行。不要为了教程破坏生产 Pipeline。冻结以下字段：
CANARY=WORKER-FAIL-743
ORG_ID=<测试组织>
PROJECT_ID=<测试项目>
PIPELINE_ID=<测试 Pipeline>
EXECUTION_ID=<失败运行 ID>
BRANCH=<分支>
COMMIT_SHA=<完整 SHA>
FAILED_STAGE=<首个相关失败 stage>
FAILED_STEP=<首个相关失败 step>
EXIT_CODE=<实际退出码>
FIRST_ERROR=<首个相关错误的脱敏摘要>
LOG_EVIDENCE=<受控证据位置>FIRST_ERROR 要保留预期值与实际值，不能只写“测试失败”。LOG_EVIDENCE 可以是受控日志位置或脱敏片段编号，不要复制整份私人日志。
**硬失败：**execution、commit、失败 step 或首个相关错误任一未知时，停止 Agent 配置，先补齐 Pipeline 可观测性。
W03：确认功能、Stage 和运行基础设施
官方文档将 Worker Agent 描述为可复用的 Pipeline AI 单元，由 Instructions、Model Connector 和可选 MCP 组成。它以容器运行在隔离 VM 中，可以使用 Harness Cloud，也可以使用自有 Kubernetes 基础设施。
在运行卡确认：
- 模块选择器中能否进入 AI → Worker Agents。
- 测试 Pipeline 使用 CI、CD、IaCM、STO、SCS 还是 Custom stage。
- CI、STO、SCS、IaCM 可以按对应文档加入 Agent step；CD 与 Custom stage 需要放在 Containerized Step Group 中。
- 实际执行基础设施、出网路径、日志保留和数据驻留是否符合团队要求。
- 若入口不可见，记录租户、模块和功能开放状态，停止实验；不要用截图猜测账号已经支持。
**W03 通过条件：**能够指出 Agent 在哪里运行、由哪个 stage 承载，以及连接模型和 Harness API 需要经过哪些网络边界。
W04：建立模型连接合同
Worker Agent 定义必须配置 Model Connector。先用测试用途、权限受控的连接器，不要复用无法说明 owner 和费用边界的个人密钥。
记录：
- connector identifier、scope 和 owner；
- 模型名称与可变参数；
- Secret 的存储位置和轮换责任人；
- 预算或调用上限；
- 网络失败、限流和模型不可用时的 Pipeline 处理方式。
若使用 Harness 托管 LLM connector，且 Agent 配置了权限块，官方权限文档要求把 ai_llm_gateway: access 纳入评估。若 Agent 要读取 connector，还要评估 connector: view|access。具体值以当前权限参考和你的任务为准。
**硬失败：**不要把 token 放入 Instructions、Pipeline YAML、运行卡或 CSV。Secret 无 owner、无 scope 或无法撤销时，不进入 W05。
W05：先写输入输出合同，再写 Instructions
本实验只做失败证据整理，不自动修复、提交、批准或部署。
必填输入
| 字段 | 来源 | 缺失时行为 |
|---|---|---|
ORG_ID / PROJECT_ID / PIPELINE_ID | Pipeline 或固定测试配置 | 返回 STATUS=input_missing |
EXECUTION_ID | 本次失败运行 | 返回缺失字段，不猜运行 ID |
COMMIT_SHA | SCM / Pipeline 表达式 | 不生成根因结论 |
FAILED_STEP / EXIT_CODE | execution 结果 | 标记未知并停止诊断 |
FIRST_ERROR / LOG_EVIDENCE | 受控日志证据 | 不补造错误内容 |
CANARY | 固定为 WORKER-FAIL-743 | 缺失或不同即失败 |
固定输出
| 键 | 允许值或格式 | 用途 |
|---|---|---|
STATUS | ok / input_missing / not_found / permission_denied / analysis_failed | 让下游以机器规则判断 |
FIRST_FAILED_STEP | 精确 step identifier 或 unknown | 防止把连带错误当首因 |
EXIT_CODE | 整数或 unknown | 保留原始状态 |
EVIDENCE_REF | 受控证据位置 | 从结论回到事实 |
SUMMARY | 不超过 500 字符 | 供 Pipeline 摘要使用 |
TASK_ID | 本次 execution + canary 的非秘密标识 | 防止跨运行串线 |
Instructions 至少明确：只处理指定 execution；事实、假设和未知项分开；每个判断引用证据；不读取其他项目；不修改代码、Pipeline、Secret 或部署；无法读取时返回对应状态。
**负例预期：**缺少 EXECUTION_ID 返回 input_missing；不存在的测试 ID 返回 not_found；两者都不能返回貌似合理的失败原因。
W06：在 Catalog 创建有版本的 Worker Agent
进入 AI → Worker Agents 创建自定义 Agent。依据当前 configuration 文档逐项核对，而不是从博客复制整段旧 YAML：
- Schema version 为当前支持版本；现行文档示例使用 version 1。
- 名称和 identifier 能区分测试与生产。
- Instructions 使用 W05 的合同。
- Model Connector 指向 W04 的测试连接器。
- inputs 的类型与来源明确；官方参考支持 string、connector 和 array 等输入类型。
- 在
with.output声明六个输出键。 - 如需 MCP，只连接本实验所需资源，并单独做 MCP 权限验收。
保存后记录 Agent 名称、版本、配置导出或受控截图位置。不要只写“创建成功”。
**W06 通过条件：**审阅者能从证据重建输入、Instructions、连接器、输出和版本，但看不到任何 Secret 值。
W07：在测试 Pipeline 固定引用版本
Pipeline 对 Catalog Agent 的引用使用 agentName: name@version 形式；完整定义仍保存在 Catalog。当前官方文档明确：Pipeline YAML 只引用 Agent，不在这里重复 Instructions、inputs、outputs、环境变量或容器镜像。动态上下文要在 Catalog Agent 定义中通过受控 Harness 表达式注入，并用 W09 的实际输入核对结果证明表达式正确。
下载样例展示的是审阅结构，不是可以直接执行的完整 Pipeline：
step:
type: Agent
name: Failure evidence worker
identifier: failure_evidence_worker
spec:
agentName: failure_evidence_worker@1.0.0
agentSettings: ""Agent 定义中的表达式名称、字段层级和 schema 会随租户能力变化。先在 Harness 编辑器中按当前 Schema 校验，再保存测试 Pipeline；不要为了把输入放进 Pipeline 而添加当前 Agent step 不支持的自定义字段。
**硬失败：**Agent 引用没有固定版本、Catalog 定义中的动态输入仍是占位符，或 CD / Custom stage 未使用所需 Containerized Step Group 时，不运行。
W08：声明最小权限，并理解“交集”规则
权限位置取决于 stage：CI、STO、SCS、IaCM 在 stage.spec.permissions；CD 与 Custom 在承载 Agent 的 Containerized Step Group permissions 中。权限是 YAML map，多个动词用 | 分隔。
下面只是失败分析任务的审阅起点：
permissions:
ai_llm_gateway: access
connector: view|access
pipeline: view
code_repository: view删除任务不需要的资源。若输入已经携带全部脱敏证据，就不应为了方便给出广泛项目写权限。
运行时有效权限是 声明权限与调用者 RBAC 权限的交集。Agent 声明 pipeline: view 不会让一个无权查看 Pipeline 的调用者越权。当前文档还提醒：未知 resource key 会被丢弃；verb 不做同等的枚举校验，拼错的 verb 可能静默地什么也没授权。
**W08 通过条件：**保存权限 YAML、触发者身份和 RBAC 对照。必须在 W12 专门验证权限拒绝与 verb 拼写错误。
W09：先手动运行一次，只观察 Agent 本身
用 W02 冻结样本手动运行测试 Pipeline：
- 运行前再次核对 commit 与 execution 输入。
- 保存新的 Pipeline execution ID、Agent 外层 step 名称和展开后的内部 step 名称。
- 确认任务中出现且只出现一次
WORKER-FAIL-743。 - 查看实际容器日志和 Agent 输出，不只读界面摘要。
- 核对六个输出键及
SUMMARY长度。 - 检查 Agent 没有写代码、修改 Pipeline、批准或触发部署。
Worker Agent 在运行时会展开为 step group。内部输出路径可能包含外层 Agent step 和展开后的内部 step；内部名称应从这次真实运行中取得，不能提前猜。
**硬失败：**输入 SHA 不一致、canary 缺失/重复、证据引用无法打开，或 Agent 做了合同外写操作，立即停止并进入 W14。
W10：用普通 Run step 读取并验证输出
输出必须在 Agent 定义的 with.output 中声明，并由任务以 KEY=value 写入 $HARNESS_OUTPUT 或 $DRONE_OUTPUT。仅在自然语言回答中打印 JSON，不等于发布了 Pipeline output。
在 Agent 后加入一个普通、无模型的 Run step，执行确定性检查：
test "$STATUS" = "ok"
test "$FIRST_FAILED_STEP" != "unknown"
test "$EXIT_CODE" != "unknown"
test -n "$EVIDENCE_REF"
test -n "$TASK_ID"
test "${#SUMMARY}" -le 500变量绑定应使用 W09 实际运行中发现的完整输出表达式。不要让模型自己判断“我的输出是否有效”。
**W10 通过条件：**保存普通 Run step 的命令、实际 stdout、exit code 和完整输出路径。Agent 成功但确定性检查失败，整体仍失败。
W11：验证缺输入与不存在资源
在测试分支各运行一次：
- 移除
EXECUTION_ID，预期STATUS=input_missing，并列出缺失字段。 - 传入确定不存在的测试 execution ID，预期
STATUS=not_found。
两次都不得生成具体根因、伪造日志引用或进入后续部署步骤。下游 Run step 应根据状态非零退出，或走专门的人工处理分支。
**W11 通过条件：**两条独立 execution、两个预期状态和实际下游行为都有证据。只测正常路径不算试点完成。
W12：验证权限拒绝和错误 verb
使用测试身份和测试 Pipeline，不能在生产资源上制造权限故障。
权限交集负例
让调用者缺少读取目标资源的 RBAC，即使 permissions 声明了 view，也应得到拒绝。预期输出为 permission_denied 或平台明确的权限失败，不得降级为编造分析。
verb 拼写负例
在临时版本中把一个必要动词故意写错，例如把 view 改成可识别的测试错拼。当前文档说明 verb 不会被完整枚举校验，因此配置可能保存但运行时没有有效授权。记录实际失败，再恢复正确版本。
未知 resource key 负例
只在可安全操作的临时版本验证未知 key 被忽略的行为，不把它当作安全控制。测试完成后删除临时版本。
**硬失败：**若越权读取成功，立即暂停 Pipeline、收回连接器和执行身份，并按安全事件流程处理。
W13：验证触发器使用明确执行身份
手动运行通过不代表 Webhook、计划任务或其他 Trigger 会使用相同身份。官方权限文档对触发运行列出额外条件：
- 相关账户需要具备
HARNESS_TOKEN_INJECT； - 触发身份执行还涉及
PIPE_ENFORCE_TRIGGER_EXECUTOR_IDENTITY； - Account setting 中 Enforce Executor Identity for Triggers 为 true；
- Pipeline 配置明确的 Run pipeline as identity。
feature flag 是否可见及由谁开启取决于租户，不能靠 YAML 假装已经生效。
在非生产 Trigger 上运行一次与 W09 相同的样本，记录 Trigger ID、执行身份、RBAC、Pipeline execution、Agent version、输入 SHA 和输出。然后用权限不足身份做一次受控负例。
**W13 通过条件：**人工运行与触发运行都能追溯身份，权限不足的触发不会借用更高权限继续执行。
W14：演练暂停、回滚与完整撤销
试点结束前完成一次真实撤销：
- 暂停或禁用测试 Trigger。
- 从 Pipeline 移除 Agent step，恢复经过验证的前一版本。
- 删除临时 Agent 版本、负例版本和测试分支。
- 收回测试连接器访问与临时 RBAC。
- 轮换试点专用 Secret；不要在记录中粘贴新旧值。
- 保留脱敏 execution、配置版本、输出与审计记录。
- 再运行一次 Pipeline，证明旧流程恢复且不会调用 Worker Agent。
**W14 通过条件：**没有活跃 Trigger、残留写权限或孤立测试连接器；恢复运行成功，并能从审计记录确认 Agent 没有再次执行。
常见故障按层定位
| 现象 | 先检查 | 不要直接归因于 |
|---|---|---|
| AI 菜单没有 Worker Agents | 租户功能开放、模块与角色权限 | 浏览器缓存 |
| Agent step 不能启动 | stage 类型、Containerized Step Group、基础设施、模型连接器 | Instructions 写得不好 |
| 模型调用被拒绝 | ai_llm_gateway、connector 权限、调用者 RBAC、Secret scope | 模型本身不可用 |
| Agent 显示成功但下游为空 | with.output、输出文件、KEY=value、完整内部路径 | 下游 shell 一定有问题 |
| 手动运行成功、Trigger 失败 | executor identity、账户设置、feature flag、Run pipeline as | Trigger 需要更大权限 |
| 权限 YAML 保存但运行拒绝 | resource key、verb 拼写、声明与 RBAC 交集 | 平台随机故障 |
| 输出很详细却无法复查 | 输入是否真的传入、证据位置、execution 与 SHA | 回答越长越可靠 |
最终发布门禁
只有同时满足以下条件，才能把状态从“文档核读”升级为你自己的“测试项目已验证”：
- W01–W14 全部有 execution 或配置证据，硬失败为零。
- 输入 execution、commit SHA、失败 step 和 canary 一致。
- Agent version、模型 connector、执行基础设施和触发身份明确。
- 实际权限不超过任务所需，权限拒绝和 verb 错拼负例成立。
- 六个输出由普通 Run step 验证，不依赖模型自评。
- 缺输入、不存在资源和权限不足时不会编造结果或继续部署。
- Trigger 使用明确执行身份，权限不足时停止。
- 暂停、恢复、权限收回和无 Agent 的恢复运行都有记录。
需要让外部 IDE 或桌面客户端读取 Harness 资源，继续做 Harness MCP Server M01–M14 实验。需要先判断哪个 DevOps 场景值得自动化，阅读 Harness AI DevOps 场景选择；不要为了展示 Agent 能力跳过可复查的工程门禁。