4.8 KiB

Raw Blame History

维护者效率报告协议

五个维护类 Skill 统一遵循本协议。目标是让维护者在 30 秒内知道“先处理什么、为什么、下一步由谁做”，同时保留可追溯的证据。

默认输出层级

默认生成 executive 模式；用户明确要求细节时再生成 standard 或 full。

执行摘要：结论、阻断数、高风险数、安全门禁、验证状态和扫描范围。
今日动作：最多 5 项，按优先级排序；每项必须包含对象、责任方、下一动作和证据引用。
证据附录：完整发现、命令输出摘要、文件/行号、时间戳和未验证项。

不要在首屏输出原始 API 响应、完整 diff、所有通知或所有 PR 两两比较结果。需要保留时放入附录或 JSON。

统一决策字段

Markdown 和 JSON 的结论必须一致。推荐使用以下字段：

{
  "schema_version": "1.0",
  "mode": "executive",
  "decision": "action_required",
  "severity": "high",
  "counts": {"blocking": 1, "high": 2, "medium": 3, "low": 0},
  "security_gate": "fail",
  "verification": "partial",
  "scope": {"owner": "Gitlink", "repo": "gitlink-cli", "items": 12},
  "top_actions": [
    {"id": "CR-001", "owner": "maintainer", "action": "先处理安全阻断", "evidence": ["diff:shortcuts/x/y.go:42"]}
  ],
  "findings": [],
  "limitations": []
}

允许的 decision：merge、action_required、reorder、observe、blocked。没有足够证据时必须使用 observe 或 blocked，不能猜测为通过。

严重性和稳定编号

blocking：阻止合并、会泄露凭据、破坏兼容性或无法证明核心行为可用。
high：高概率影响真实用户、维护队列或安全边界，应进入本轮处理。
medium：需要补验证、文档或边界处理，但不立即阻断。
low：可延后处理的质量或可读性问题。

每条发现使用稳定前缀和递增编号：代码审查 CR-001、集成 IN-001、关系图谱 TP-001、维护雷达 MR-001、契约守卫 CG-001。复审时复用已有编号；新问题才新增编号。

醒目显示规则

Markdown 使用 HTML 颜色和粗体，同时必须提供纯 Markdown 回退，确保终端、网页和被清洗的渲染器都可读：

<span style="color:#B42318"><strong>阻断</strong></span> **[blocking]** #CR-001
<span style="color:#B54708"><strong>高风险</strong></span> **[high]** #CR-002
<span style="color:#067647"><strong>通过</strong></span> **[pass]**

颜色只用于结论、严重性、门禁和动作，不要给整段正文着色。JSON、CSV 和命令管道输出禁止包含 ANSI 转义、HTML 标签或 emoji；使用纯字段值。

在支持终端颜色时，可以根据 NO_COLOR 约定关闭 ANSI 颜色。报告落盘默认不写 ANSI。

验证门禁

每次报告都要分别记录 passed、failed、not_run、not_applicable，不能把未执行写成通过：

门禁	最低要求
数据完整性	目标、状态、更新时间和证据来源齐全
核心行为	使用仓库定义的构建/测试命令，或明确记录未找到命令
安全	扫描敏感文件、凭据、危险输入边界和权限变化
回归	至少覆盖本次改动的正常路径、失败路径和兼容路径
输出	Markdown 可读，JSON 可解析，中文无替换字符或乱码

关键门禁失败时，结论不得为 merge。只列最能改变决策的测试；完整命令和输出摘要放在附录。

队列效率约束

首屏最多展示 5 个动作；其余项目按 deferred_count 计数并放入附录。
同一对象的多个问题合并为一项动作，避免维护者重复阅读。
每项动作只写一个明确动词：修复、验证、复看、转派、合并、收口。
对“等待作者 / 等待 reviewer / 等待维护者 / 等待平台”的状态必须显式标注，避免错误催办。
无 open PR 或无可用数据时，明确输出“没有可分析的 open PR”或“数据不足”，不得用历史样例冒充实时结果。

质量自检

生成报告后，依次检查：

# JSON 可解析且无颜色控制符
$json | ConvertFrom-Json | Out-Null
if ($json -match "`e\[|<span|</span>") { throw "JSON 含展示层标记" }

# Markdown 使用 UTF-8 保存，并检查替换字符
$markdown | Set-Content .\maintenance-report.md -Encoding utf8
$bytes = [IO.File]::ReadAllBytes('.\maintenance-report.md')
$text = [Text.Encoding]::UTF8.GetString($bytes)
if ($text.Contains([char]0xfffd) -or $text.Contains('?')) { throw "报告存在编码风险" }

最后一条检查只针对报告中预期的中文文本；如果业务数据本身包含问号，应改为检查 UTF-8 替换字符和已知乱码片段，并记录例外。

4.8 KiB Raw Blame History Unescape Escape