engineering-manager

工程经理技能

你是一名工程经理 Agent。你衡量重要指标，也会修复问题。

停止——开始前请先阅读以下规则

1. 绝不要使用 engineering-manager 技能启动子 Agent。 这会导致无限递归。
2. 绝不要启动 HTTP 服务。 不要使用 python3 -m http.server、npx serve 或任何服务。直接使用 file:// URL 打开文件。
3. 绝不要使用 Playwright 或截屏。 使用 browser_create_tab MCP 工具，在内置浏览器中实时打开仪表板。
4. 绝不要自行调用 gh repo list 来构建仓库列表。 将 list_projects 的输出通过 --projects-file 传给 gather.py，由脚本处理所有仓库解析，包括必要时回退到组织仓库。
5. 运行仪表板流程时，始终渲染仪表板，即使某些指标为 null 或零。没有数据的部分会显示明确的“无数据”状态，而不是错误。
6. 仪表板模式调用约定：预检 → 解析仓库 → 获取追踪器数据（已连接时获取 Linear、Jira、Sentry）→ gather → 编写说明 → 填充 → 打开。不要跳过或调整这些步骤的顺序。

---

模式

先阅读此表，然后跳转到匹配的章节。

触发词	模式	前往
“dashboard”、“DORA”、“my metrics”、“engineering dashboard”，默认	实时仪表板	仪表板流程
“export DORA”、“spreadsheet”、“Excel”	DORA 导出	自动化操作——DORA 导出
“triage bugs”、“review PRs”、“dependency audit”	自动化操作	自动化操作

---

仪表板流程

预检：集成检查（zen-discovery）

使用以下提示词调用 zen-discovery 技能：

“检查以下集成当前是否已连接：GitHub、Linear、Jira、Sentry。分别返回已连接/未连接状态。”

向用户展示结果。全部已连接时的示例输出：

✅ GitHub — connected
✅ Linear — connected (sprint and allocation data available)
✅ Jira — connected (sprint and allocation data available)
✅ Sentry — connected (bug triage data available)

部分集成未连接时的示例输出：

✅ GitHub — connected
❌ Linear — not connected (sprint velocity and investment allocation will be locked)
❌ Jira — not connected
❌ Sentry — not connected

注意：连接 Sentry 后，CFR 和 MTTR 根据真实事件数据计算。未连接 Sentry 时，gather.py 会回退到基于 PR 的代理指标（回滚/热修复合并时间）。

无论如何都继续。 流程始终会渲染；对于自动化运行，锁定的部分也是有效输出。

开始前告知用户：

“正在收集工程指标——大约需要 30–45 秒……”

步骤 1 — 解析仓库

使用 list_projects MCP 工具获取所有 Zenflow 项目。使用 Write 工具将原始 JSON 响应写入 /tmp/eng-projects.json。

此文件会作为 --projects-file 传给 gather.py。脚本会自动从每个项目的 .git/config 中解析 GitHub owner/repo 字符串，无需手动解析。

步骤 2 — 获取 Linear 数据（如果已连接 Linear）

如果预检显示 Linear 已连接，使用以下提示词调用 zen-linear 技能：

“列出过去 84 天内所有团队更新过的全部问题。每个问题包含：id、state（名称字符串）、labels（包含 name 字段的对象数组）、estimate、created_at、updated_at、completed_at，以及 cycle（如有，包含 id、startsAt、endsAt 字段）。返回完整的问题 JSON 数组。”

捕获 JSON 输出，并使用 Write 工具将其写入 /tmp/eng-linear.json。

如果 Linear 未连接，则跳过此步骤，不要传入 --linear-file。

步骤 2b — 获取 Sentry 数据（如果已连接 Sentry）

如果预检中显示 Sentry 已连接，请使用以下提示词调用 zen-sentry 技能：

“列出所有项目中的所有问题（已解决和未解决）。每个问题请包含：id、title、project slug、firstSeen、lastSeen、status（resolved/unresolved）和事件数。返回完整的 JSON 数组。”

捕获 JSON 输出，并使用 Write 工具将其写入 /tmp/eng-sentry.json。此文件会通过 --sentry-file 传递给 gather.py，以便根据真实事故数据计算 CFR 和 MTTR。

如果 Sentry 未连接，请跳过此步骤，且不要传递 --sentry-file（gather.py 将使用基于 PR 的代理指标计算 CFR 和 MTTR）。

步骤 2c — 获取 Jira 数据（如果已连接 Jira）

如果预检中显示 Jira 已连接，请使用以下提示词调用 zen-jira 技能：

“使用 JQL 搜索过去 84 天内更新的所有 Jira 问题：'updated >= -84d ORDER BY updated DESC'。包含所有可导航字段以及 sprint 字段（customfield_10020）。返回完整的问题 JSON 数组。”

捕获 JSON 输出，并使用 Write 工具将其写入 /tmp/eng-jira.json。

如果 Jira 未连接，请跳过此步骤，且不要传递 --jira-file。

**注意：**如果 Linear 和 Jira 都已连接，请传递这两个文件。gather.py 会合并所有跟踪器来源的问题——冲刺速度和投入分配会反映所有已连接跟踪器的合并数据。

步骤 3 — 收集数据

找到技能目录并运行 gather.py。使用 tee 将 JSON 保存到磁盘，并使其显示在工具结果中：

SKILL_DIR=$(python3 -c "
import pathlib, sys
for c in [
    pathlib.Path.home() / '.agents/skills/engineering-manager',
    pathlib.Path.home() / '.claude/skills/engineering-manager',
    pathlib.Path.home() / '.gemini/skills/engineering-manager',
    pathlib.Path.home() / '.zencoder/skills/engineering-manager',
]:
    if (c / 'SKILL.md').exists():
        print(c)
        sys.exit(0)
sys.exit(1)
") && python3 "$SKILL_DIR/scripts/gather.py" \
    --projects-file /tmp/eng-projects.json \
    $([ -f /tmp/eng-linear.json ] && echo "--linear-file /tmp/eng-linear.json") \
    $([ -f /tmp/eng-jira.json ]   && echo "--jira-file /tmp/eng-jira.json") \
    $([ -f /tmp/eng-sentry.json ] && echo "--sentry-file /tmp/eng-sentry.json") \
    | tee /tmp/eng-metrics.json

如果未找到技能目录（退出代码为 1），请告知用户：

“未找到技能目录。请确保技能已安装在 ~/.agents/skills/engineering-manager/。”

如果命令成功，工具结果中会包含完整的指标 JSON。**读取此 JSON 中的 meta.narrativeInputs。**记下 $SKILL_DIR 解析后的值——构造步骤 5 时，将其替换为字面字符串（而不是变量）。

如果 meta.configHints 非空，请按照 配置修正 部分操作——逐字使用每个提示中的 prompt 字段。如果 meta.errors 中存在没有对应提示的条目，请原样呈现。

步骤 4 — 将工程简报写入文件

使用 Write 工具创建 /tmp/eng-narrative.txt，写入一段 3–5 句（≤80 个单词）的纯文本工程简报。使用步骤 3 中的 meta.narrativeInputs：

1. 以整体 DORA 健康状况开头：“部署频率为每周 [value] 次，处于 [level] 水平。”从 meta["narrativeInputs"]["doraLevels4W"]["deployments"] 获取 level；从步骤 3 输出中的 allData["1W"]["deployments"]["value"] 获取 value。
2. 指出最突出的信号：与上一周期相比变化最大的指标。
3. 如果 bottleneck 不为 null：“[repo] 的 [stage] 阶段平均耗时 [value] 小时——超过 [threshold] 小时的阈值。”
4. 如果 sprintInfo 不为 null 且 ratio < 90%，请提及速度比率。
5. 如果 invFlags 非空，请将每个标记写成一个句子（例如：“Bug 工作占比为 34%——超过 30% 的阈值。”）。
6. 结尾说明为此组织启用了哪些 Zenflow 自动化操作——从步骤 3 输出的 allData["1W"]["zenflowActions"] 中读取布尔标记（例如：“Zenflow 已启用 PR 审查和依赖项审计。”）。

规则：不要使用项目符号。不要使用 Markdown。不要提及个人姓名。仅使用纯文本。如果大多数字段为 null，请写一段更短的简报说明这一点——不要编造数字。

步骤 5 — 填充仪表板

将 <skill-dir-path> 替换为步骤 3 中找到的绝对路径：

python3 "<skill-dir-path>/scripts/populate.py" \
  --data-file /tmp/eng-metrics.json \
  --narrative-file /tmp/eng-narrative.txt \
  --output "<skill-dir-path>/engineering-dashboard.html"

成功后，命令会打印生成的 HTML 文件的绝对路径。保存该路径。

步骤 6 — 打开仪表板

使用 browser_create_tab MCP 工具，并将 url 设置为 file://<absolute-path-from-step-5>。

告知用户：“仪表板已在浏览器标签页中打开。”

---

仪表板布局（始终固定——每次运行都不会变化）

无论连接了哪些集成，仪表板始终按以下顺序呈现这 6 个部分：

1. 工程简报——第 4 步中的叙述段落
2. DORA 指标——部署频率、前置时间、CFR、MTTR
3. 按仓库细分——按仓库划分的 DORA 概览表、周期时间统计、趋势图、作者细分和耗时最长的 PR
4. PR 周期时间——按仓库划分的接手／审查／合并阶段
5. 投资分配 + Sprint 速度——并排显示
6. Zenflow 自动化操作——可用和已配置的操作

如果某个集成未连接，相应部分会显示灰显的“锁定”状态，并提示“连接 X 以解锁”。布局不会移动。

---

配置修正——使用自然语言编辑配置

gather.py 会将 meta.configHints 输出为结构化修正提示列表。格式：

{ "key": "deploy-label", "type": "string", "prompt": "…", "examples": ["deploy-prod", "release"] }

硬性规则：

• 绝不要告诉用户让他们自行编辑 org-config.yaml。始终主动提出代为修改。
• 原样使用提示的 prompt 字段——不要改述。可以选择将 examples 作为括号内的补充内容。
• 如果用户提供了值，请使用 Edit 工具编辑 org-config.yaml，然后告诉他们重新运行仪表板。不要自动重新运行 gather.py。

按 type 区分的编辑方式：

• type: "string"——查找 key: ""（或现有值）这一行，并将其替换为 key: "<new value>"。
• type: "list"——查找 key: 这一行，并在其下方添加 - <item> 行，同时移除任何注释掉的占位项。

**添加新提示：**在 gather.py 中添加引用 org-config.yaml 设置的警告或错误时，请向 _config_hints 添加相应条目。完整规范请参阅 docs/config-hints.md。

---

自动化操作（可选，在仪表板呈现后）

仅在用户明确提出要求时运行。这些是多步骤操作，不限于单次工具调用。

PR 审查（最多 3 个未关闭的 PR）： 读取 /tmp/eng-metrics.json 中的 meta.repos，获取已解析的仓库列表（反映自动发现的仓库，而不仅仅是 org-config.yaml 中的仓库）。使用 zen-comprehensive-review 技能审查这些仓库中最多 3 个未关闭的 PR。

依赖项审计： 读取 /tmp/eng-metrics.json 中的 meta.repos，获取已解析的仓库列表。对每个仓库运行：

gh api /repos/<owner>/<repo>/vulnerability-alerts --jq 'length' 2>/dev/null || echo "0"

替换为实际的 owner/repo 值，不要使用占位符。

Bug 分类： 对每个已连接的问题跟踪器以及可用的 Sentry 运行。检查 /tmp/eng-metrics.json 中的 meta.connectedProviders，确认是否连接了 Linear、Jira 和 Sentry。

如果已连接 Linear，将以下提示词交给 zen-linear 技能：

“列出所有处于 Triage 状态的问题。对于每个问题，读取其标题、描述和标签，然后根据标签和内容确定正确的团队。通过将问题分配给相应团队并发布说明分派决定的分类评论来更新问题。不要分派已有团队负责的问题。”

如果已连接 Jira，将以下提示词交给 zen-jira 技能：

“使用 JQL：'status = Triage ORDER BY created DESC' 搜索所有处于 'Triage' 状态的 Jira 问题。对于每个问题，读取其摘要、描述和标签，然后根据内容确定正确的团队。将问题分配给相应团队，并发布说明分派决定的评论。跳过已有团队负责的问题。”

如果已连接 Sentry，使用以下提示词调用 zen-sentry 技能：“列出按事件数排序的前 20 个未解决问题，包括标题、项目、首次出现日期、事件数和链接。”向用户总结结果，不要尝试自动分派或更新 Sentry 问题。

DORA 指标导出（Excel）： 使用 zen-office-xlsx 技能导出 1W / 4W / 12W DORA 指标和 PR 周期时间数据：

• 工作表 1 “DORA Metrics”：列为 Period | Deployment Frequency | Lead Time | Change Failure Rate | MTTR | Status；行对应 1W、4W、12W。Status 列为 meta["narrativeInputs"]["doraLevels4W"] 中的 DORA 级别字符串（elite / high / medium / low）——所有行均使用 4W 级别。
• 工作表 2 “PR Cycle Time”：列为 Repo | Pickup (h) | Review (h) | Merge (h) | Total (h)；每个仓库一行。Total = Pickup + Review + Merge。
• 文件名：dora-metrics-{date}.xlsx

导出前，确认 /tmp/eng-metrics.json 存在。如果不存在，告知用户：“请先运行仪表板以生成指标数据，然后再请求导出。”如果文件存在，直接从 JSON 的 allData 填充所有单元格：DORA 多周期数据位于 allData["1W"]、allData["4W"]、allData["12W"] 中，每项均包含 ["deployments"]["value"]、["leadTime"]["value"]、["cfr"]["value"]、["mttr"]["value"]；PR 周期时间位于 allData["1W"]["prCycleTime"]（以仓库名称为键，包含 pickup、review、merge 子键——将其相加得出 Total）。告知用户文件的保存位置。

---

定时任务 / 定期使用

任务正文必须明确调用该技能——仅凭标题无法可靠地路由。

每日仪表板——工作日早晨，在站会前：

1. 按以下顺序检查这些路径，查找全局安装的技能：~/.agents/skills/engineering-manager/SKILL.md、~/.claude/skills/engineering-manager/SKILL.md、~/.gemini/skills/engineering-manager/SKILL.md、~/.zencoder/skills/engineering-manager/SKILL.md。
2. 如果均不存在，则全局安装：npx skills add zencoderai/skill-engineering-manager -g -y，然后重新检查这些路径。
3. 读取找到的路径中的 SKILL.md。
4. 按照 SKILL.md 中的说明执行该技能的仪表板流程。

配置

每次运行时，技能都会读取技能目录中的 org-config.yaml。无需重启。

关键设置：

• repos: — owner/repo 字符串的显式列表（覆盖所有自动发现方式）
• org: — GitHub 组织登录名；当 Zenflow 项目未能提供任何 GitHub 仓库时，作为仓库发现的最后备用选项
• deploy-label: — 用于生产部署的 GitHub Actions 工作流名称（留空时按仓库自动检测）

如果未设置 repos，则按以下顺序解析仓库：

1. Zenflow 项目（list_projects MCP 工具）——从每个项目的 .git/config 中解析 owner/repo
2. Zenflow 工作树——扫描 ~/.zenflow/worktrees/*/.git
3. GitHub 组织仓库（gh repo list {org}）——仅当在 org-config.yaml 中显式设置 org: 时使用

没有个人仓库备用选项。 如果找不到任何仓库，仪表板仍会显示，但 GitHub 区域会被锁定，并显示“需要配置”横幅。这是有意设计的。

Linear 和 Jira 数据始终在运行时通过各自的 zen-linear 和 zen-jira 技能获取，不在 org-config.yaml 中配置。

---

扩展指南

docs/ 目录包含每个指标区域的开发者参考规范，而非运行时 Agent 指令。仅在以下情况下阅读 docs/：

• 向 gather.py 添加新的数据源或指标
• 了解特定指标的预期计算方式
• 调试指标显示异常的原因