kld-sdd 2.6.17 → 2.7.3

package/templates/skills/kld-sdd/opsx-consistency-check/reference.md

@@ -0,0 +1,129 @@
+# 判定标准参考
+
+## 一、问题分类
+
+首先将每个差异归类为以下四种类型之一：
+
+| 问题类型 | 说明 | 示例 |
+|---------|------|------|
+| **代码有 spec 没有（业务）** | 代码实现了业务功能但 spec 未描述 | 代码有 `/api/export` 接口但 spec 未记录 |
+| **代码有 spec 没有（技术）** | 代码实现了纯技术支撑逻辑，不涉及业务契约 | 工具方法、防御性校验、日志打印、框架样板代码、DTO 转换 |
+| **spec 有代码没有** | spec 定义了但代码未实现 | spec 定义了权限校验但代码未实现 |
+| **不一致** | 代码和 spec 都有但不匹配 | spec 定义字段 `token`，代码返回 `accessToken` |
+
+> **技术实现 vs 业务实现的区分标准**：
+>
+> 以下类别属于**纯技术实现**，不要求 spec 覆盖：
+>
+> | 类别 | 说明 | 示例 |
+> |------|------|------|
+> | 工具/基础设施代码 | 通用工具方法、辅助函数 | `DateUtils.format()`, `StringUtils.isBlank()` |
+> | 防御性代码 | 空值检查、边界保护、异常兜底 | `if (param == null) throw ...` |
+> | 日志/监控代码 | 日志打印、埋点、健康检查 | `log.info("request: {}", param)` |
+> | 框架样板代码 | 框架要求的固定结构 | Spring `@Configuration`、序列化配置 |
+> | DTO/VO 转换 | 对象拷贝、字段映射 | `BeanUtils.copyProperties()` |
+> | 配置类 | 技术配置、环境配置 | 数据库连接池、线程池配置 |
+>
+> **判断原则**：若代码行为不影响外部可观测的业务契约（接口路径、请求/响应字段、业务规则、错误码），则视为纯技术实现。
+
+## 二、置信度判定规则
+
+按以下顺序依次判定（最终置信度取最严重的结果）：
+
+**步骤 1：判断 spec 相关的问题（spec 有代码没有 / 不一致）**
+
+| 关键性 | 置信度 | 说明 |
+|--------|--------|------|
+| 关键 | **low** | 影响核心业务流程、安全、前端决策 |
+| 非关键 | **medium** | 辅助功能、非核心字段、提示性信息 |
+
+```
+示例：
+- spec 定义了核心接口 /api/orders 但代码未实现 → low（关键）
+- spec 定义了权限校验但代码未实现 → low（关键）
+- 缺少提示性错误码 → medium（非关键）
+- 前端非核心字段名与后端不一致 → medium（非关键）
+```
+
+**步骤 2：判断代码多出来的内容（代码有 spec 没有）→ 分级兜底规则**
+
+根据代码多出来的内容性质，分级处理：
+
+| 代码多出的内容 | 置信度 | 说明 |
+|--------------|--------|------|
+| **业务功能**（接口、业务逻辑、业务错误码） | **low** | 核心业务行为必须有 spec 记录 |
+| **辅助业务功能**（导出、审计、非核心扩展） | **medium** | 辅助功能建议记录但不强制 |
+| **纯技术实现**（工具方法、防御性代码、日志、框架样板、DTO 转换、配置类） | **不降级** | 技术支撑代码不要求 spec 覆盖 |
+
+此步骤用于确保业务代码实现都有对应的 spec 记录，同时避免对纯技术细节的过度管控。如果步骤 1 已判定为 low，此步骤结果也是 low，最终结果不变。如果步骤 1 是 medium，此步骤发现代码有**业务功能** spec 没有，则升级为 low。
+
+```
+示例：
+- 代码有业务接口 /api/export 但 spec 未记录 → low（业务功能）
+- 代码有权限校验逻辑但 spec 未记录 → low（业务功能）
+- 代码有错误码 400 但 spec 未记录 → low（业务功能）
+- 代码有 DateUtils.format() 工具方法但 spec 未记录 → 不降级（纯技术实现）
+- 代码有 if (param == null) throw 防御性校验但 spec 未记录 → 不降级（纯技术实现）
+- 代码有 log.info() 日志打印但 spec 未记录 → 不降级（纯技术实现）
+```
+
+**最终置信度**：取步骤 1 和步骤 2 中最严重的结果（low > medium > high）。
+
+## 三、关键性判断标准
+
+步骤 1 中需要判断差异是否"关键"，按以下标准执行（满足任一即为关键）：
+
+**关键（→ low）：**
+
+| 类别 | 说明 | 示例 |
+|------|------|------|
+| 核心业务流程 | 影响主流程的接口/逻辑 | 登录、注册、下单、支付、审批 |
+| 数据写入操作 | POST / PUT / DELETE / PATCH 操作 | 创建、编辑、删除接口 |
+| 认证与授权 | 决定用户身份和权限的逻辑 | 401→登录页、403→权限页、角色校验 |
+| 安全相关 | 防注入、防越权、敏感数据处理 | 密码加密、SQL 注入防护、数据脱敏 |
+| 前端核心决策字段 | 决定页面跳转、功能开关的字段 | token、userId、status、role |
+| 核心展示字段 | 用户可见的主要数据 | 订单金额、用户名、商品名称 |
+
+**非关键（→ medium）：**
+
+同时满足以下全部条件即为非关键：
+
+| 条件 | 说明 |
+|------|------|
+| 不影响核心业务流程 | 非主流程接口 |
+| 不影响前端核心决策 | 不决定页面跳转或功能开关 |
+| 非安全相关 | 不涉及认证、授权、数据校验 |
+| 辅助功能 | 导出、日志、审计、健康检查、监控 |
+
+**判断优先级**：当无法明确判断时，**默认视为关键**（宁可误报，不可漏报）。
+
+## 四、维度判定参考
+
+各维度的 pass/warning/fail 判定参考：
+
+| 维度 | pass | warning（→ medium） | fail（→ low） |
+|------|------|------------------|-------------------|
+| **接口契约** | 所有检查项 ✅ | 辅助接口未记录 | 接口差异；代码有**业务接口**但 spec 未记录 |
+| **业务规则** | 所有规则一致 | 非关键规则不一致 | 规则不一致；代码有**业务逻辑**但 spec 未记录 |
+| **校验规则** | 所有约束一致 | 非关键约束不一致 | 必填字段无校验；代码有**业务校验逻辑**但 spec 未记录 |
+| **错误码** | 所有错误码一致 | 非关键错误码缺失 | 错误码不一致；代码有**业务错误码**但 spec 未记录 |
+| **前后端一致性** | 所有字段匹配 | 非核心字段不匹配 | 核心字段不匹配 |
+
+> **注意**：纯技术实现（工具方法、防御性代码、日志、框架样板、DTO 转换、配置类）不影响维度判定，各维度均为 pass。
+
+## 五、示例
+
+| 场景 | 问题类型 | 关键性 | 置信度 |
+|------|---------|--------|--------|
+| 响应字段名错误（token → accessToken） | 不一致 | 关键 | **low** |
+| 缺少密码复杂度校验 | spec 有代码没有 | 关键 | **low** |
+| 代码有业务接口 /api/orders 但 spec 未记录 | 代码有 spec 没有（业务） | — | **low** |
+| 代码有权限校验逻辑但 spec 未记录 | 代码有 spec 没有（业务） | — | **low** |
+| 代码有辅助导出接口但 spec 未记录 | 代码有 spec 没有（业务） | 非关键 | **medium** |
+| spec 定义了核心接口 /api/orders 但代码未实现 | spec 有代码没有 | 关键 | **low** |
+| 缺少提示性错误码 | spec 有代码没有 | 非关键 | **medium** |
+| 前端非核心字段名与后端不一致 | 不一致 | 非关键 | **medium** |
+| 代码有 DateUtils 工具方法但 spec 未记录 | 代码有 spec 没有（技术） | — | **不降级** |
+| 代码有防御性空值校验但 spec 未记录 | 代码有 spec 没有（技术） | — | **不降级** |
+| 代码有日志打印但 spec 未记录 | 代码有 spec 没有（技术） | — | **不降级** |
+| 所有维度完美匹配 | — | — | **high** |

package/templates/skills/kld-sdd/opsx-kb-config/SKILL.md

@@ -35,10 +35,11 @@ allowed-tools:
 
 | 场景 | 说明 |
 |------|------|
-| 首次配置 | 输入 API Key → 选择 Space/KB → 创建 project-identity.json |
-| 更换 API Key | 清空 apiKey，重新输入 |
+| 首次配置 | 输入 API Key → 绑定监控项目（可留空）→ 选择 Space/KB → 创建 project-identity.json |
+| 更换 API Key | 清空 apiKey，重新输入；随后需重新校验监控项目绑定 |
 | 更换知识库 | 清空 targets，重新选择 Space/KB |
-| 查看当前配置 | 展示已配置的 Space/KB 列表 |
+| 绑定/更换监控项目 | 写入或清除 `projectName`（Step 2.5） |
+| 查看当前配置 | 展示已配置的 Space/KB 列表与项目绑定 |
 | 校验配置 | 探活 API + 校验 project_id 与 spaceKey 一致 |
 
 ## 配置步骤
@@ -62,7 +63,7 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
 
 若 `state.apiKey` 为空或用户要求换密钥：
 
-1. 请用户提供 API Key（控制台「API 密钥」创建，scope 建议同时勾选 `context:read` + `archive:ingest`，使查询和入库都能复用）。
+1. 请用户提供 API Key（控制台「API 密钥」创建，scope 建议同时勾选 `context:read` + `archive:ingest`，使查询与入库都能复用）。
 2. 可选：请用户确认 `api`（默认 `http://10.29.213.80:8080/api`）与 `tenantKey`（默认 `default`）。
 3. 写入 `kb-state.json`（spec 仓根目录，已 gitignore）。
 4. 用 `GET $API/health` 探活；再用 `GET $API/v1/spaces?tenantKey=…` + Bearer 校验 key。
@@ -72,6 +73,24 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
 - 401/403 → 清掉 apiKey 请用户重贴，勿循环重试。
 - **不要** `POST /auth/login`。
 
+### 2.5. 监控项目绑定（`projectName`，可留空）
+
+实时监控按"用户 / 项目"维度展示 Run：上传事件时服务端会根据 API 密钥解析上传用户，并按此处绑定的项目名称写入投影（服务端校验该用户必须是项目成员，否则项目留空、不阻断上传）。
+
+1. 询问用户项目名称；**留空** → 写 `projectName: null`（不绑定），跳到 Step 3。
+2. 非空 → 用共享库做成员预校验（Bearer = 当前 apiKey）：
+   ```js
+   // 临时 .cjs 脚本（遵循本文件头部跨平台规则）：
+   const shared = require('<SPEC_ROOT>/skywalk-sdd/lib/shared.cjs');
+   const r = await shared.verifyProjectMembershipViaServer(SPEC_ROOT, '<项目名称>');
+   ```
+   - `member === true` → `shared.setKbProjectName(SPEC_ROOT, '<项目名称>')` 写入，提示绑定生效。
+   - `member === false` → 提示"绑定不会生效，上传记录的项目将留空"，让用户选择**重填**或**留空**（`setKbProjectName(SPEC_ROOT, null)`）；不要直接保存非成员名称。
+   - `ok === false`（`reason: 'endpoint_unavailable'`，服务端未上线该端点或不可达）→ 软警告"平台暂不支持项目成员校验，绑定将在上传时由服务端裁决"，允许用户选择保存或留空。
+3. 换密钥后原 `projectName` 可能对新密钥用户失效 → 换密钥流程完成后重走本步校验。
+
+> 写入位置：`kb-state.json` 的 `projectName` 键（与 api/apiKey 同文件，已 gitignore）。同步代理每次上报批次时重读该配置，改绑/解绑后新事件即按新配置上报，无需重启或迁移。
+
 ### 3. 选择空间与知识库（支持多选）
 
 若 `state.targets` 为空，或用户要求重新选择：
@@ -139,6 +158,7 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
 - API 地址：{api}
 - 租户：{tenantKey}
 - API Key：{前缀}****（已配置 / 未配置）
+- 项目绑定：{projectName 或 未绑定}
 - 目标 Space/KB：
   1. {spaceName}（spaceKey: {spaceKey}）→ {kbName}
   2. ...
@@ -149,8 +169,9 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
 
 | 用户说 | Agent 做 |
 |--------|----------|
-| 配置知识库 / 首次使用 | 走完 Step 1→2→3→4 |
-| 换密钥 / 重置 API Key | 清 apiKey，重走 Step 2 |
+| 配置知识库 / 首次使用 | 走完 Step 1→2→2.5→3→4 |
+| 换密钥 / 重置 API Key | 清 apiKey，重走 Step 2，再重走 Step 2.5 校验项目绑定 |
+| 换项目 / 重新绑定项目 / 解绑项目 | 重走 Step 2.5（保留 apiKey 与 targets） |
 | 换空间 / 换知识库 / 重新选择 | 清 targets，重走 Step 3→4 |
 | 看配置 / 当前配置 | 读取 kb-state.json + project-identity.json 并展示 |
 | 校验配置 | 探活 + 校验 project_id === spaceKey |

package/templates/skills/kld-sdd/opsx-kb-config/reference.md

@@ -11,6 +11,7 @@
   "api": "http://10.29.213.80:8080/api",
   "tenantKey": "default",
   "apiKey": "sk_sdd_…",
+  "projectName": "支付网关重构",
   "updatedAt": "2026-07-19T12:00:00Z",
   "targets": [
     {
@@ -29,9 +30,18 @@
 | `api` | 是 | API 根，含 `/api` |
 | `tenantKey` | 是 | 列空间用；默认 `default` |
 | `apiKey` | 是 | 控制台创建的 `sk_sdd_…`，scope 建议 `context:read` + `archive:ingest` |
+| `projectName` | 否 | 监控项目绑定名；`null`/缺失/空白 = 未绑定，上传批次不携带 `project_name` |
+| `scopes` | 建议 | API Client scope 列表 |
 | `targets` | 操作前必填 | 多选；可为空仅当尚未完成选择 |
 | `updatedAt` | 建议 | ISO-8601 |
 
+## 监控项目绑定与上传
+
+- 配置期预校验：`GET {api}/v1/sdd-runs/dimensions`（Bearer），返回当前密钥用户可见的 `projects[]`；条目名称匹配即视为成员。端点 404/不可达表示服务端尚未上线该能力 → 软警告后可保存，服务端在上传时做权威裁决（非成员项目置空、不阻断）。
+- 客户端辅助函数：`verifyProjectMembershipViaServer(specRoot, projectName)`（预校验，软返回）、`setKbProjectName(specRoot, projectName|null)`（原子写入/清除），均在 `skywalk-sdd/lib/shared.cjs`。
+- 上传行为：同步代理每次组 batch 时重读 `kb-state.json`；`projectName` 非空 → batch 请求体顶层附带可选 `project_name` 字段（`sdd-progress-batch-v1.schema.json`，1-128 字符）；未配置 → 请求体与历史版本完全一致。
+- 环境变量兜底：`ENGINEERING_KB_PROJECT_NAME`（kb-state 无 `projectName` 时生效）。
+
 ## `project-identity.json`
 
 路径：`<spec-root>/skywalk-sdd/project-identity.json`（**提交到 Git，团队共享**）。
@@ -61,7 +71,8 @@ Authorization: Bearer sk_sdd_…
 ```
 
 - **不要** `POST /auth/login`。
-- Key 在控制台「API 密钥」创建；创建时建议勾选 **读取上下文 / context:read** + **入库 / archive:ingest**（查询和入库都需要）。
+- Key 在控制台「API 密钥」创建；创建时建议勾选 **读取上下文 / context:read** + **入库 / archive:ingest**（查询与入库都需要）。
+- 如需查看 API Client 当前 scopes，可调用 `GET {api}/v1/spaces/{spaceId}/api-clients/me`，响应字段：`data.name`、`data.scopes`（string[]）。
 - 401/403：清掉 state 里的 `apiKey`，请用户重贴；勿循环重试。
 
 探活与校验（PowerShell 用 `Invoke-RestMethod`，**禁止** `curl`）：