企业官网建设流程全解析

1. 这不是又一个“Agent Wrapper”，而是一套面向真实工程交付的控制中枢

你有没有遇到过这样的场景：写好一个 Pi Coding Agent，它能读代码、改配置、生成单元测试，甚至自动修复 CI 失败——但一旦跑进生产环境，就变成“黑盒幽灵”：任务卡在某一步没日志、重试三次后状态丢失、半夜告警说“Agent 死了”，你连它上一秒在改哪行代码都查不到。这不是能力问题，是工程控制层缺失。Pi-Harness 就是为解决这个痛点而生的——它不增强 Agent 的推理能力，也不替换它的 LLM 内核，而是像给高速行驶的自动驾驶汽车加装仪表盘、安全气囊和交通调度系统：可观测（你随时知道它在想什么、干了什么）、可恢复（断电/崩溃后能从断点续跑，不丢上下文、不漏变更）、可编排（把单次调用变成带条件分支、超时熔断、人工审核闸门的标准化工作流）。关键词里反复出现的“可观测、可恢复、可编排”，不是三个并列形容词，而是一个递进式工程能力三角：可观测是眼睛，可恢复是肌肉记忆，可编排是大脑决策。它面向的不是“能跑通 demo”的开发者，而是每天要为线上服务 SLA 负责的 SRE、需要审计变更链路的合规工程师、以及要批量管理上百个 Agent 实例的平台团队。我去年在一家中型金融科技公司落地 Pi Coding Agent 时，前两轮迭代全卡在“怎么让业务方信任它”——他们不怕 Agent 写错代码，怕的是出错后没人知道它为什么错、改了哪里、是否已回滚。Pi-Harness 的核心价值，正在于把 AI 编程行为，从“不可控的智能涌现”，拉回到“可度量、可追溯、可兜底”的工程实践轨道上。

2. 为什么必须重建控制层？——从 Pi Coding Agent 的原生缺陷说起

Pi Coding Agent 的设计哲学是轻量、专注、快速响应，这决定了它在工程化落地时存在三类结构性短板，而 Pi-Harness 正是针对这些短板做“外科手术式”补强。

2.1 原生可观测性：日志即黑洞，追踪靠猜

Pi Coding Agent 默认输出只有两层信息：用户输入 prompt 和最终生成的代码 diff。中间过程——比如它如何理解需求、调用了哪些工具、遇到冲突时做了什么决策、是否触发了 fallback 逻辑——全部被封装在 LLM 的 token 流中，无法结构化提取。更致命的是，它的执行是单线程同步阻塞的：一次调用要么成功返回，要么超时失败，没有中间态快照。我实测过，在处理一个含 12 个微服务依赖的重构任务时，Agent 卡在第 7 步长达 8 分钟，但 Prometheus 指标里只看到一个“duration=480s”的扁平化记录，没有任何线索指向它是卡在代码分析、API 调用，还是等待人工确认。Pi-Harness 的解决方案是引入分层可观测架构：在 Agent 执行引擎外挂一层“观测代理”，强制所有工具调用、状态变更、LLM 请求/响应都通过统一事件总线（Event Bus）广播。每个事件携带结构化元数据：task_id（全局唯一）、step_id（步骤序号）、tool_name（调用工具名）、status（success/failed/pending）、duration_ms（耗时）、error_code（错误码）。这些事件实时写入 OpenTelemetry 兼容的后端（如 Jaeger + Loki），再通过 Grafana 构建三层看板：① 全局任务热力图（按服务/模块聚合成功率与延迟）；② 单任务全链路追踪（点击任一 task_id，展开从 prompt 解析到代码提交的完整事件流）；③ 工具调用健康度（统计 git clone 失败率、API timeout 频次等）。关键在于，Pi-Harness 不要求修改 Agent 内核，而是通过 SDK 注入方式，在其execute_step()方法前后自动埋点——这意味着你现有的 Pi Coding Agent 代码一行不用改，只要引入pi-harness-sdk并初始化ObservabilityMiddleware，就能获得企业级可观测能力。

2.2 原生可恢复性：状态即瞬态，重启即归零

Pi Coding Agent 的状态管理极度简化：所有上下文（当前文件内容、已执行步骤、临时变量）都存于内存中。一旦进程崩溃、容器重启或网络中断，整个任务状态彻底丢失。更麻烦的是，它没有“事务边界”概念——比如一个“升级 Spring Boot 版本”的任务包含：修改 pom.xml → 更新依赖 → 运行测试 → 提交 PR。如果第三步测试失败，Agent 不会自动回滚前两步的变更，而是直接报错退出，留下一个半成品的代码库。Pi-Harness 的可恢复设计基于两个核心机制：状态快照（State Snapshot）和原子操作编排（Atomic Step Orchestration）。状态快照不是简单地序列化内存对象，而是将 Agent 的执行状态分解为可持久化的“事实单元”：workspace_hash（当前代码树的 SHA256）、step_history（已执行步骤 ID 列表）、tool_state（各工具最新状态，如 git branch 名、数据库连接池大小）。这些单元以 JSON Schema 格式写入分布式存储（默认支持 Redis + SQLite 双写，生产环境推荐 PostgreSQL）。当任务中断后，Pi-Harness 启动时会自动检查task_id对应的状态快照，若存在且未标记为 completed，则加载该快照并从step_history最后一项的下一步继续执行。原子操作编排则确保每一步都是“要么全成功，要么全回滚”。例如，git_commit步骤在执行前会先创建本地备份分支backup/<task_id>，提交成功后才删除备份；若失败，则自动git reset --hard并切换回备份分支。这种设计让恢复不再是“从头再来”，而是“精准续跑”，实测在模拟 Kubernetes Pod 频繁驱逐的场景下，任务平均恢复时间从 32 分钟（重跑）降至 1.7 分钟（续跑）。

2.3 原生可编排性：调用即孤岛，流程即硬编码

Pi Coding Agent 的典型用法是agent.run(prompt)，这是一个原子函数调用。但真实工程场景需要复杂流程：比如“紧急漏洞修复”任务需满足：① 自动扫描漏洞（Snyk）→ ② 若高危则立即触发修复（Agent）→ ③ 修复后强制运行安全测试（OWASP ZAP）→ ④ 测试通过才允许合并，否则通知安全团队人工介入。这种条件分支、超时控制、人工审批闸门，原生 Agent 无法表达。Pi-Harness 引入YAML 声明式工作流引擎，将任务定义从代码逻辑解耦为配置文件。一个典型 workflow 定义如下：

# workflow/vuln-fix.yaml name: "Critical Vulnerability Fix" timeout: 300 # 全局超时 5 分钟 steps: - id: scan tool: snyk_scan params: {target: "prod-service"} on_failure: - notify: security-team - escalate: manual-review - id: fix tool: pi-coding-agent params: {prompt: "Fix CVE-2023-XXXX in pom.xml", max_steps: 5} depends_on: [scan] retry: {max_attempts: 2, backoff: "exponential"} - id: test tool: owasp-zap params: {target_url: "https://prod-service.internal"} depends_on: [fix] timeout: 120 - id: merge tool: github-pr params: {title: "Auto-fix CVE-2023-XXXX", reviewers: ["security-team"]} depends_on: [test] condition: "{{ steps.test.output.passed == true }}"

Pi-Harness 的工作流引擎会解析此 YAML，构建有向无环图（DAG），并注入执行上下文（如steps.scan.output.vulnerabilities可被fix步骤引用）。关键创新在于condition 表达式支持 Jinja2 模板语法，且所有output字段均经过类型校验（如steps.test.output.passed必须是布尔值），避免运行时类型错误。这使得编排不再是脚本拼接，而是具备类型安全、可验证、可版本化的工程资产。我们团队已将 87% 的日常运维任务（部署回滚、配置巡检、日志分析）转化为此类 YAML 工作流，CI/CD 流水线中新增一个任务，只需提交一个 YAML 文件，无需改动任何 Go/Python 代码。

3. Pi-Harness 的核心组件与实操集成路径

Pi-Harness 不是一个黑盒二进制，而是一组可插拔、可定制的组件集合。它的设计哲学是“最小侵入，最大覆盖”——你不必一次性启用所有功能，可以根据团队成熟度分阶段落地。以下是四个核心组件及其集成要点，全部基于真实生产环境验证。

3.1 Observability Middleware：让每一次思考都留下足迹

这是 Pi-Harness 的“眼睛”，也是最容易上手的组件。它不依赖任何外部服务，开箱即用。

安装与初始化：

pip install pi-harness-sdk

在现有 Pi Coding Agent 项目中注入（以 Python SDK 为例）：

from pi_harness.sdk import ObservabilityMiddleware from pi_coding_agent.core import PiAgent # 初始化观测中间件（默认使用内存存储，适合开发） obsv_mw = ObservabilityMiddleware( backend="memory", # 可选: "loki", "otel-collector", "kafka" service_name="pi-coding-agent-prod", environment="production" ) # 创建 Agent 实例时注入中间件 agent = PiAgent( llm_model="gpt-4-turbo", tools=[GitTool(), HttpTool(), ShellTool()], middleware=[obsv_mw] # 关键：注册中间件 ) # 现有调用方式完全不变 result = agent.run("Refactor UserService to use dependency injection")

实操要点与避坑经验：

• 事件过滤策略：默认会捕获所有事件，但在高并发场景下可能产生海量日志。建议在初始化时配置event_filter参数，例如只记录status != "success"的事件，或对tool_name做白名单（["git_commit", "http_post"]）。我在线上环境曾因未过滤llm_request的原始 prompt（含敏感 API Key），导致 Loki 存储暴增，后来通过event_filter=lambda e: not e.tool_name.startswith("llm_")解决。
• 性能开销实测：在 16 核 CPU、64GB 内存的服务器上，启用 ObservabilityMiddleware 后，单次任务平均延迟增加 12ms（<0.5%），主要消耗在 JSON 序列化和内存写入。若使用远程后端（如 Loki），建议启用批量发送（batch_size=10,flush_interval=1s），可将网络 I/O 开销降低 70%。
• Grafana 看板配置：Pi-Harness 提供预置的 Grafana JSON 模板（grafana-dashboard.json），导入后即可使用。重点关注Task Duration by Status面板——它能直观暴露“失败任务是否普遍比成功任务慢”，这往往是工具调用阻塞（如 Git 仓库响应慢）的早期信号。我们曾通过此面板发现某私有 GitLab 实例的/api/v4/projects/{id}/repository/files接口平均延迟达 8.2s，针对性优化后，Agent 整体成功率提升 23%。

3.2 State Persistence Layer：给 Agent 装上“记忆芯片”

这是实现可恢复性的基石，选择存储后端需兼顾一致性与可用性。

存储后端选型对比：

集成步骤（以 Redis 为例）：

from pi_harness.persistence import RedisStateBackend from pi_harness.sdk import StatefulAgent # 初始化 Redis 后端（连接池自动管理） redis_backend = RedisStateBackend( host="redis.harness.svc.cluster.local", port=6379, db=0, password="your-redis-password", # 生产环境必设 key_prefix="pi-harness:" # 避免与其他服务 key 冲突 ) # 创建支持状态恢复的 Agent stateful_agent = StatefulAgent( base_agent=agent, # 复用原有 PiAgent 实例 state_backend=redis_backend, auto_recover=True # 启用自动恢复 ) # 现在 run() 调用具备可恢复性 result = stateful_agent.run("Update all dependencies to latest patch version")

关键参数调优：

• snapshot_interval: 控制快照频率。默认30s，但对长任务（>10min）建议设为120s，避免高频写入拖慢 Redis。我们曾将一个 45 分钟的“全库 schema 迁移”任务的间隔设为300s，Redis CPU 使用率下降 40%。
• cleanup_policy: 自动清理策略。生产环境强烈建议启用cleanup_after_success: true（成功后 24 小时自动删除快照）和cleanup_on_failure: false（失败快照永久保留，便于人工诊断）。某次线上事故中，正是通过保留的失败快照，我们定位到是ShellTool在特定内核版本下timeout命令失效，而非 Agent 逻辑问题。
• 灾难恢复演练：Pi-Harness 提供harness-cli recover --task-id <id>命令，可手动触发恢复。我们每月进行一次“混沌工程”演练：随机 kill 一个 Agent Pod，观察是否在 30 秒内由另一个 Pod 自动接管并续跑。实测成功率 99.98%，失败案例均因 Redis 连接超时（已通过增加socket_timeout=5参数修复）。

3.3 Workflow Engine：用 YAML 定义你的 AI 工程流水线

这是将 Pi Coding Agent 从“单兵作战”升级为“军团协同”的关键。

工作流文件组织规范：

• 所有.yaml文件存于workflows/目录下，按业务域分组（workflows/deploy/,workflows/security/,workflows/devops/）。
• 文件名即 workflow ID（如deploy-canary.yaml），ID 将作为 API 调用的路径参数。
• 每个 workflow 必须包含name（人类可读名）和version（语义化版本，如1.2.0），用于灰度发布。

一个生产级工作流示例（workflows/deploy-canary.yaml）：

name: "Canary Deployment Pipeline" version: "1.3.0" description: "Deploy new version to 5% of traffic, monitor metrics, auto-rollback on error" timeout: 1800 # 30 分钟全局超时 # 全局参数，可在 steps 中通过 {{ .params.env }} 引用 params: env: "staging" service_name: "user-service" canary_weight: 5 steps: - id: check_health tool: kubectl_check params: {namespace: "{{ .params.env }}", pod_selector: "app={{ .params.service_name }}"} timeout: 60 - id: deploy_canary tool: helm_upgrade params: release_name: "{{ .params.service_name }}-canary" chart_path: "./charts/{{ .params.service_name }}" values: replicaCount: 1 canaryWeight: "{{ .params.canary_weight }}" depends_on: [check_health] retry: {max_attempts: 3, backoff: "linear", delay: 10} - id: wait_metrics tool: prometheus_wait params: query: 'rate(http_requests_total{job="{{ .params.service_name }}", status=~"5.."}[5m]) > 0.1' timeout: 300 depends_on: [deploy_canary] - id: rollback tool: helm_rollback params: {release_name: "{{ .params.service_name }}-canary"} on_failure: - step: wait_metrics - step: deploy_canary condition: "{{ steps.wait_metrics.status == 'failed' }}" - id: approve_merge tool: github_approve_pr params: {pr_number: "{{ .context.pr_number }}"} depends_on: [wait_metrics] condition: "{{ steps.wait_metrics.status == 'success' }}"

实操心得：

• 参数注入安全：所有{{ .params.xxx }}和{{ .context.xxx }}都经过严格沙箱隔离，无法执行任意代码。但要注意params中的字符串仍可能被注入到下游工具命令中（如helm_upgrade的values）。我们强制要求所有params值通过validate_params()函数校验，例如canary_weight必须是 1-100 的整数，否则 workflow 加载失败。
• 调试技巧：工作流执行时，Pi-Harness 会生成execution_trace.json文件，记录每一步的输入、输出、耗时、错误堆栈。开发时用harness-cli run --workflow deploy-canary.yaml --debug可输出详细 trace。我们曾通过 trace 发现prometheus_wait步骤因 PromQL 语法错误返回空结果，导致condition判定为false，意外触发了 rollback——这提醒我们，所有condition表达式必须显式处理null或空值。
• 版本兼容性：当 workflowversion升级时，旧版本不会被自动删除。可通过harness-cli list-workflows --show-versions查看所有版本，并用--version 1.2.0指定调用。我们采用“金丝雀发布 workflow”策略：新版本先对 10% 的任务生效，监控 24 小时无异常后再全量。

3.4 Recovery Console：工程师的“AI 任务急救室”

当可观测性发现异常、可恢复性未能自动续跑、或可编排流程卡在人工审批时，你需要一个可视化界面进行干预。Pi-Harness 自带 Recovery Console，它不是一个花哨的 Dashboard，而是一个聚焦于“止血、诊断、修复”的终端式 Web UI。

核心功能与使用场景：

• 任务列表页：按status（running/pending/failed/completed）、created_at、service_name过滤。点击任一任务进入详情页。
• 详情页三栏布局：
  • 左栏（Execution Trace）：时间轴展示所有步骤，绿色为成功，红色为失败，灰色为 pending。点击任一步骤可查看原始输入、输出、错误日志（支持折叠大文本）。
  • 中栏（State Inspector）：以树形结构展示当前快照的所有字段（workspace_hash,step_history,tool_state.git.branch等），支持编辑并保存为新快照（用于手动修复状态）。
  • 右栏（Recovery Actions）：提供一键操作按钮：
    • Resume from Step X：从指定步骤重新执行（跳过之前所有步骤）。
    • Reset to Snapshot：回滚到某个历史快照（需提前手动创建）。
    • Inject Manual Input：为卡在human_approval步骤的任务，直接输入{"approved": true, "reason": "Security review passed"}。
    • Export Debug Bundle：打包当前任务的所有日志、快照、trace，生成.zip供 SRE 团队离线分析。

部署与权限控制：

• Console 默认监听:8080，通过--auth-mode=oidc启用企业级认证（支持 Okta、Azure AD）。
• 权限模型基于 RBAC：viewer（只读）、operator（可 resume/reset）、admin（可 inject input/export bundle）。我们为 SRE 团队分配operator角色，为安全团队分配viewer角色，避免权限过度集中。
• 一个真实案例：某天凌晨，一个database-migration任务因 MySQL 主从延迟导致wait_replication步骤超时失败。值班 SRE 通过 Console 查看State Inspector，发现tool_state.mysql.slave_lag_seconds为127（远超阈值 30），于是点击Resume from Step X，跳过等待步骤，直接执行run_migration。整个过程耗时 92 秒，比等待自动重试（3 次 × 300s）节省了 14 分钟，且避免了业务中断。

4. 从零到生产：Pi-Harness 的渐进式落地路线图

在真实企业环境中，强行一步到位部署全套 Pi-Harness 往往适得其反。我们总结了一套经过 7 家客户验证的四阶段落地法，每个阶段都有明确目标、交付物和成功指标。

4.1 阶段一：可观测先行（1-2 周）

目标：让团队第一次“看见”Pi Coding Agent 的真实行为，建立基础信任。

关键动作：

• 在所有非生产环境（dev/staging）的 Agent 实例中，启用ObservabilityMiddleware并连接 Loki。
• 部署预置 Grafana 看板，重点监控Task Success Rate和Avg Duration by Tool。
• 每日晨会选取 1 个失败任务，由工程师在 Console 中分析 trace，找出根因（如git_clone失败是因为 SSH Key 权限不足）。

交付物：

• 一份《Pi Agent 健康度周报》，包含成功率趋势、TOP 3 失败工具及原因。
• 一个observability-best-practices.md文档，记录常见问题解决方案（如“如何为 GitTool 配置 HTTPS 代理”）。

成功指标：

• 失败任务平均诊断时间从 45 分钟降至 8 分钟。
• 团队对 Agent 的“黑盒恐惧感”显著降低，开始主动提出优化建议（如“增加对 Maven 仓库镜像的配置支持”）。

4.2 阶段二：可恢复筑基（2-3 周）

目标：消除“任务中断即重来”的焦虑，保障关键任务的确定性交付。

关键动作：

• 在生产环境的高优先级任务（如emergency-hotfix）中，启用StatefulAgent并配置 PostgreSQL 后端。
• 编写 3 个核心工具的原子操作包装器（git_commit_atomic,helm_upgrade_atomic,kubectl_apply_atomic），确保每一步都具备回滚能力。
• 进行 3 次“计划性中断演练”：在任务执行中手动 kill Pod，验证自动恢复成功率。

交付物：

• 一份《State Backend 运维手册》，包含 PostgreSQL 表结构、备份策略（每日 pg_dump）、扩容指南。
• 一个atomic-tools-library代码库，封装所有已验证的原子工具。

成功指标：

• 关键任务（SLA > 99.9%）的平均恢复时间 ≤ 2 分钟。
• 因 Agent 中断导致的线上事故次数降为 0。

4.3 阶段三：可编排驱动（3-4 周）

目标：将重复性工程操作沉淀为可复用、可审计的工作流资产。

关键动作：

• 成立跨职能工作流小组（DevOps + SRE + Security），梳理 Top 10 高频运维场景。
• 为每个场景编写 YAML 工作流，并通过harness-cli validate进行静态检查（语法、schema、循环依赖）。
• 将工作流纳入 GitOps 管理：workflows/目录受 Argo CD 监控，任何 PR 合并自动同步到集群。

交付物：

• 一个版本化的workflowsGit 仓库，包含所有工作流文件及 README（说明用途、参数、权限要求）。
• 一份《Workflow 设计规范》，定义命名约定、参数粒度、错误处理模式。

成功指标：

• 80% 的日常运维任务通过工作流自动化执行。
• 新增一个运维任务的平均交付周期从 3 天缩短至 2 小时（主要节省在代码编写和测试上）。

4.4 阶段四：闭环治理（持续进行）

目标：让 Pi-Harness 成为企业 AI 工程能力的基础设施，而非临时项目。

关键动作：

• 建立harness-governance团队，负责：
  • 工作流的准入审核（所有新 workflow 必须通过安全扫描和性能压测）。
  • 观测数据的定期审计（每月检查是否有敏感信息泄露风险）。
  • 制定《Pi-Harness SLA 协议》，明确各组件的可用性承诺（如 State Backend ≥ 99.95%）。
• 将 Pi-Harness 的指标接入企业统一监控平台（如 Datadog），与业务指标（如订单创建成功率）关联分析。

交付物：

• 一份《Pi-Harness 治理白皮书》，涵盖合规要求、灾备方案、升级策略。
• 一个harness-cost-calculator工具，根据任务量、存储用量、计算资源估算月度成本。

成功指标：

• Pi-Harness 相关故障的 MTTR（平均修复时间） ≤ 15 分钟。
• 90% 的工程师能独立编写、调试、发布工作流。

5. 常见问题与实战排查速查表

在落地 Pi-Harness 的过程中，我们收集了超过 200 个真实问题。以下是最常遇到的 7 类问题，附带根因分析、排查路径和终极解决方案。这些问题都来自凌晨三点的 Slack 频道和 Jira ticket，绝非理论假设。

5.1 问题：任务在 Console 中显示 “Running”，但 Grafana 看板里Task Duration停滞不动

现象：任务卡在某一步超过 10 分钟，Console 的 Execution Trace 中该步骤状态为pending，但无任何日志输出。

根因分析：

• 最常见：下游工具（如git clone）因网络问题卡在 DNS 解析或 TCP 握手，而工具本身未设置超时，导致整个 Agent 线程阻塞。
• 次常见：ObservabilityMiddleware 的事件发送队列满（如 Loki 写入失败），中间件内部锁住主线程等待重试。

排查路径：

1. 登录执行该任务的 Pod，运行ps aux | grep pi-agent查看进程状态。若 PID 状态为D（uninterruptible sleep），基本确定是系统调用阻塞（如网络、磁盘）。
2. 检查kubectl logs <pod-name> -c observability，搜索queue full或send failed。
3. 在 Console 的 State Inspector 中，查看tool_state下对应工具的最新状态（如git.state是否为cloning）。

终极解决方案：

• 工具层：为所有外部调用添加硬超时。例如，在GitTool的clone()方法中，使用subprocess.run(..., timeout=120)而非os.system()。
• 中间件层：在ObservabilityMiddleware初始化时，设置event_queue_maxsize=1000和event_queue_timeout=5，避免队列阻塞主线程。
• 平台层：在 Kubernetes Deployment 中，为 Agent 容器添加readinessProbe，探测/healthz端点（Pi-Harness 内置），当队列积压超 500 时返回 503，触发流量驱逐。

5.2 问题：恢复任务时，Console 显示 “Snapshot not found”，但harness-cli list-snapshots能查到

现象：任务 IDtask-abc123的快照存在于数据库，但点击Resume时提示找不到。

根因分析：

• 几乎总是：快照的task_id字段与当前任务 ID 不匹配。常见于任务被重试时，Pi-Harness 为每次重试生成新task_id（如task-abc123-retry-1），但旧快照仍关联原 ID。
• 较少见：State Backend 的读取缓存（如 Redis 的hgetall结果）与数据库不一致。

排查路径：

1. 运行harness-cli get-snapshot --task-id task-abc123，确认快照是否存在。
2. 若存在，运行harness-cli get-snapshot --task-id task-abc123-retry-1，检查重试 ID 的快照。
3. 查看任务日志，搜索Generated new task_id:，确认重试时的新 ID。

终极解决方案：

• 预防：在工作流定义中，为可能重试的步骤显式设置retry_id: "stable-id"，确保所有重试共享同一快照。
• 修复：使用harness-cli copy-snapshot --from task-abc123 --to task-abc123-retry-1手动复制快照。
• 根治：升级到 Pi-Harness v2.3+，该版本引入task_id_stability模式，重试时默认复用原 ID。

5.3 问题：工作流中的condition表达式始终为false，即使输出看起来正确

现象：steps.scan.output.vulnerabilities返回[{"id": "CVE-2023-1234", "severity": "high"}]，但condition: "{{ steps.scan.output.vulnerabilities | length > 0 }}"却判定为false。

根因分析：

• Jinja2 沙箱限制：Pi-Harness 的模板引擎禁用了| length过滤器，仅允许白名单函数（upper,lower,bool,int,str）。
• JSON 类型混淆：vulnerabilities字段实际是字符串"[{\"id\":...}]"，而非 Python list，导致| length作用于字符串长度（如 56），而非数组元素数。

排查路径：

1. 在 Console 的 Execution Trace 中，点击scan步骤，查看output原始 JSON，确认其是字符串还是数组。
2. 运行harness-cli debug-template --template "{{ steps.scan.output.vulnerabilities | type }}" --context-file trace.json，检查实际类型。

终极解决方案：

• 正确写法：使用json_loads过滤器转换：{{ (steps.scan.output.vulnerabilities | json_loads) | length > 0 }}。
• 最佳实践：在工作流的on_success中，用tool: json_transform预处理输出，确保下游condition接收结构化数据。例如：

  - id: parse_vulns tool: json_transform params: {input: "{{ steps.scan.output.raw }}", template: "[{% for v in data %}{\"id\": \"{{ v.id }}\", \"severity\": \"{{ v.severity }}\"}{% endfor %}]"} depends_on: [scan]

• 长期方案：升级到 v2.4，该版本将output字段自动解析为 JSON 对象，不再需要手动json_loads。

5.4 问题：Recovery Console 无法加载，浏览器报 502 Bad Gateway

现象：Console 服务 Pod Running，但 Ingress 返回 502。

根因分析：

• 最常见：Console 的 readiness probe 失败。默认 probe 访问/healthz，该端点会检查 State Backend 连接（如SELECT 1 FROM harness_tasks LIMIT 1）。若 PostgreSQL 连接池耗尽，probe 返回 503，Ingress 将其视为不可用。
• 次常见：Console 的内存限制过低（<512Mi），在加载大型 trace（>10MB）时 OOMKilled。

排查路径：

1. kubectl get pods -l app=pi-harness-console，检查 Pod 状态是否为Running且READY为1/1。
2. kubectl logs <console-pod> -c console，搜索health check failed或OOMKilled。
3. kubectl describe pod <console-pod>，检查Events区域是否有BackOff或OOMKilled。

终极解决方案：

• probe 优化：在 Console Deployment 中，将 readiness probe 的initialDelaySeconds从 5 改为 30，periodSeconds从 10 改为 30，并添加failureThreshold: 3，避免因短暂 DB 延迟误判。
• 资源调优：将 Console 的resources.requests.memory设为1Gi，limits.memory设为2Gi。我们