forked from Gitlink/gitlink-cli
明确五个维护 Skill 的职责边界与协同协议
This commit is contained in:
parent
defbef7fe7
commit
23a5ed4841
|
|
@ -49,6 +49,10 @@ metadata:
|
|||
|
||||
关键验证至少包括：旧命令和默认值、`--help`、正常 JSON、错误 JSON、退出码、中文 UTF-8、`NO_COLOR`、敏感值脱敏和恶意边界输入。使用 golden/snapshot 或等价结构化断言，避免只检查命令返回 0。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只判断 CLI 用户契约是否保持兼容，不评价业务功能价值、通用代码质量或维护者队列优先级。组合运行时向 `gitlink-pr-integrator` 交接 `CG-xxx` 契约门禁；与 `gitlink-code-review` 同时命中安全问题时，保留 CLI 边界证据并通过 `related_ids` 关联代码层发现，避免重复催办。
|
||||
|
||||
## 不覆盖的内容
|
||||
|
||||
下面这些不属于这个 skill 的职责：
|
||||
|
|
|
|||
|
|
@ -45,6 +45,10 @@ metadata:
|
|||
|
||||
安全发现使用 `CR-xxx` 编号，疑似真实密钥只报告类型和位置，不复制内容。涉及写操作、权限或外连的验证使用脱敏 fixture、临时 worktree 和 `--dry-run`。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只评价单个 PR 的代码、测试、可维护性和代码级安全，不评价 reviewer SLA、PR 之间的重复关系或是否进入合并队列。组合运行时读取共享上下文，向 `gitlink-pr-integrator` 交接 `CR-xxx` 发现和验证门禁；如果发现涉及 CLI 参数、JSON 或错误边界，关联 `gitlink-cli-contract-guard` 的 `CG-xxx`，不要重复生成同一条泛化安全结论。
|
||||
|
||||
## 工作流概览
|
||||
|
||||
本 Skill 提供一套完整的 AI 驱动代码审查工作流，覆盖从获取 PR 变更到生成审查报告的全过程。不需要额外的 CLI Shortcuts——现有 `gitlink-cli` 命令 + AI Agent 的分析能力即可完成。
|
||||
|
|
|
|||
|
|
@ -49,6 +49,10 @@ metadata:
|
|||
|
||||
如果没有 open PR 或 open Issue，明确报告“没有可分析的 open PR/Issue”；如果消息接口失败，不得用通知列表代替协作队列，也不得伪造 SLA。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只分析响应时效、reviewer 负载、责任停滞和队列变化，不判断代码是否有漏洞、不评价 CLI 契约，也不决定 PR 是否可合并。组合运行时读取 `CR-xxx`、`CG-xxx`、`TP-xxx` 和 `IN-xxx` 的状态，只将它们转换为维护动作 `MR-xxx`；一个安全发现只提升优先级，不在本 Skill 中重新宣称漏洞成立。
|
||||
|
||||
## 核心能力
|
||||
|
||||
### 1. 响应时效雷达
|
||||
|
|
|
|||
|
|
@ -45,6 +45,10 @@ metadata:
|
|||
|
||||
只有六项门禁全部有充分证据且无 `blocking/high` 未解决项，才可使用 `merge`。大型 PR 先做文件/目录重叠和安全热点筛选，只有高风险候选才进入独立 worktree 的完整合并验证，避免批量扫描浪费维护者时间。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只判断一个 PR 是否具备进入合并队列的条件；它不重新做完整代码审查、不判断 PR 之间的替代关系，也不按 SLA 排维护者任务。组合运行时读取 `CR-xxx`、`CG-xxx` 和 `TP-xxx` 结果，使用 `IN-xxx` 记录集成阻断和门禁，不改写专项发现。安全专项未运行时，安全门禁必须保持 `not_run`，不能因构建通过而推断安全通过。
|
||||
|
||||
## Windows 前置
|
||||
|
||||
如果你在 Windows PowerShell 里运行或落盘报告，先执行：
|
||||
|
|
|
|||
|
|
@ -50,6 +50,10 @@ metadata:
|
|||
|
||||
先按标题、issue、改动文件和目录做低成本候选筛选，再对候选关系读取 diff、review 和测试证据；不要对所有 PR 做完整笛卡尔积分析。
|
||||
|
||||
## 职责边界与组合协同
|
||||
|
||||
独立运行时，本 Skill 只判断多个 open PR 之间的关系，不判断单条 PR 的代码缺陷、契约通过与否或维护者响应是否超时。组合运行时向 `gitlink-pr-integrator` 交接 `TP-xxx` 关系和建议顺序，向 `gitlink-maintainer-radar` 交接冲突热点和待处理簇；`security_hotspot` 只表示需要安全复查，不等同于已确认漏洞。
|
||||
|
||||
## 不覆盖的内容
|
||||
|
||||
下面这些不属于本 skill 的职责：
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ metadata:
|
|||
|
||||
# gitlink-cli 共享规则
|
||||
|
||||
维护者类 Skill 的报告协议见 [`references/maintenance-report-contract.md`](references/maintenance-report-contract.md)，安全检查见 [`references/security-review-matrix.md`](references/security-review-matrix.md)。生成报告时先给执行摘要，再提供可追溯的证据附录；JSON 不得混入展示层样式。
|
||||
维护者类 Skill 的报告协议见 [`references/maintenance-report-contract.md`](references/maintenance-report-contract.md)，安全检查见 [`references/security-review-matrix.md`](references/security-review-matrix.md)，五个维护 Skill 的边界和交接见 [`references/skill-scope-and-handoff.md`](references/skill-scope-and-handoff.md)。生成报告时先给执行摘要，再提供可追溯的证据附录；JSON 不得混入展示层样式。
|
||||
|
||||
本技能指导你如何通过 gitlink-cli 操作 GitLink 平台资源。
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,81 @@
|
|||
# 五个维护 Skill 的职责边界与交接协议
|
||||
|
||||
五个 Skill 可以单独运行，也可以由 Agent 编排成一条 PR 维护流水线。单独运行时只执行被请求的 Skill；组合运行时共享证据，但不互相越权替代判断。
|
||||
|
||||
## 职责矩阵
|
||||
|
||||
| Skill | 独占职责 | 明确不负责 | 主要输入 | 主要输出 |
|
||||
|------|----------|------------|----------|----------|
|
||||
| `gitlink-code-review` | 代码正确性、可维护性、测试充分性、代码级安全漏洞 | 不判断队列 SLA、PR 间关系或最终合并顺序 | 单个 PR 的 diff、文件、提交、review、测试证据 | `CR-xxx` 发现、修复建议和代码审查结论 |
|
||||
| `gitlink-cli-contract-guard` | flags、help、JSON、错误、退出码、文档和 CLI 边界安全 | 不评价业务设计价值、一般代码风格或 reviewer 负载 | CLI 改动、旧用法、golden 输出、错误路径测试 | `CG-xxx` 契约门禁和兼容性结论 |
|
||||
| `gitlink-pr-topology` | 多个 open PR 的依赖、重叠、替代、冲突和评审分组 | 不替代单 PR 代码审查或判断谁已满足合并条件 | PR 列表、文件集合、命令/API 面、diff 摘要 | `TP-xxx` 关系、证据、置信度和处理顺序 |
|
||||
| `gitlink-pr-integrator` | 合并态、rebase、构建、测试、契约、安全门禁和发布影响 | 不重新进行完整代码审查或维护者值班排序 | 单 PR 证据、其他 Skill 结论、主线和 CI 状态 | `IN-xxx` 集成门禁、决策和合并后动作 |
|
||||
| `gitlink-maintainer-radar` | 首响 SLA、reviewer 负载、责任停滞、等待方和队列变化 | 不判断代码漏洞、CLI 兼容性或 PR 功能优劣 | 队列快照、review 状态、评论时间、分配关系和安全优先级 | `MR-xxx` 维护动作、责任调整和催办建议 |
|
||||
|
||||
## 安全职责分层
|
||||
|
||||
安全可以在多个 Skill 中出现，但检查对象不同，不能重复输出同一条泛化结论：
|
||||
|
||||
- `gitlink-code-review`：检查代码数据流，例如注入、路径遍历、反序列化、权限绕过和资源耗尽。
|
||||
- `gitlink-cli-contract-guard`：检查用户输入进入 flag、header、path、query、JSON、错误输出和 token 脱敏的边界。
|
||||
- `gitlink-pr-topology`：只标记涉及认证、权限、命令执行、外联和依赖的 PR 之间的安全热点关系。
|
||||
- `gitlink-pr-integrator`：汇总安全门禁；只要存在未解决的 blocking 安全发现，就不能给出 `merge`。
|
||||
- `gitlink-maintainer-radar`：只负责安全事项的运营优先级、等待方和催办，不宣称漏洞成立。
|
||||
|
||||
## 独立运行模式
|
||||
|
||||
用户只请求一个 Skill 时：
|
||||
|
||||
1. 只读取该 Skill 需要的最小数据。
|
||||
2. 只使用该 Skill 的编号前缀和决策集合。
|
||||
3. 对其他维度写“未纳入本次检查”，而不是擅自调用其他 Skill。
|
||||
4. 仍然遵循统一报告协议，因此输出可以被后续组合流程消费。
|
||||
|
||||
## 组合运行模式
|
||||
|
||||
当用户要求“全方位审查”或维护者启动完整流水线时，按以下顺序执行：
|
||||
|
||||
1. **证据收集**：获取单 PR 上下文和 open PR 队列快照。
|
||||
2. **并行专项检查**：同时运行 `code-review`、`cli-contract-guard` 和 `pr-topology`。
|
||||
3. **集成决策**：`pr-integrator` 读取专项结论，执行独立 worktree、构建、测试和合并门禁。
|
||||
4. **维护排序**：`maintainer-radar` 读取队列变化和前述结论，生成最多五项维护动作。
|
||||
5. **合并报告**：只保留一个主结论；重复发现合并为一个动作，并保留所有来源编号。
|
||||
|
||||
一个专项 Skill 失败不会让整条流水线伪造通过。将该专项的状态设为 `not_run`，并让集成器按门禁规则降级结论。
|
||||
|
||||
## 交接字段
|
||||
|
||||
各 Skill 的 JSON 结果应包含以下字段；`findings` 可使用各自的编号前缀：
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"producer": "gitlink-code-review",
|
||||
"scope": "single_pr",
|
||||
"target": {"owner": "Gitlink", "repo": "gitlink-cli", "number": 123},
|
||||
"decision": "action_required",
|
||||
"status": "completed",
|
||||
"findings": [
|
||||
{
|
||||
"id": "CR-001",
|
||||
"severity": "high",
|
||||
"status": "open",
|
||||
"summary": "缺少恶意路径测试",
|
||||
"evidence": ["shortcuts/example/example_test.go:42"],
|
||||
"related_ids": []
|
||||
}
|
||||
],
|
||||
"gates": {"security": "passed", "verification": "partial"},
|
||||
"limitations": []
|
||||
}
|
||||
```
|
||||
|
||||
下游 Skill 不改写上游发现，只通过 `related_ids` 关联；同一根因的多个发现由最终报告合并展示，保留 `source_ids` 供维护者追溯。
|
||||
|
||||
## 组合去重规则
|
||||
|
||||
- 相同文件/行号、相同行为和相同修复动作：合并为一个动作。
|
||||
- 同一安全问题分别命中代码层和 CLI 边界：保留两条证据，但只显示一个主动作。
|
||||
- `TP-xxx` 关系不能直接变成代码缺陷；它只影响处理顺序。
|
||||
- `MR-xxx` 等待超时不能直接变成合并阻断；它只影响维护优先级。
|
||||
- `IN-xxx` 只能引用专项发现，不能重写专项发现的技术结论。
|
||||
Loading…
Reference in New Issue