cli-mergeguard 7.0.8 → 7.0.18

package/installer.mjs

@@ -1,9 +1,10 @@
 /**
- * 五个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
+ * 八个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
  * 禁止第二套超时、第二套版本来源、第二套 bin 名。
  */
-import { copyFile, mkdir, writeFile } from 'node:fs/promises'
-import { existsSync, readFileSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { constants, existsSync, readFileSync } from 'node:fs'
+import { cp, lstat, mkdir, open, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { stdin, stdout } from 'node:process'
 import { createInterface } from 'node:readline/promises'
@@ -12,6 +13,18 @@ import { fileURLToPath } from 'node:url'
 export const LOOKUP_TIMEOUT_MS = 8000
 export const CALL_TIMEOUT_MS = 120_000
 const INSTALL_META = 'install-meta.json'
+const FEEDBACK_API_PATH = '/api/v1/telemetry/skill-usage'
+const BRAIN_CLIENT_TOKEN_FILE_ENV = 'CLITAX_BRAIN_CLIENT_TOKEN_FILE'
+const BRAIN_CLIENT_TOKEN_FILE_VERSION = 'member-brain.client-token-file/1.0'
+const BRAIN_CLIENT_AUTH_SCHEME = 'BrainClient'
+const BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES = 16_384
+const BRAIN_CLIENT_TOKEN_FILE_MODE = 0o600
+const FEEDBACK_COMMENT_MAX = 500
+const FEEDBACK_SCORE_MIN = 0
+const FEEDBACK_SCORE_MAX = 100
+const BRAIN_CLIENT_TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
+const FEEDBACK_INVOCATION_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const FEEDBACK_SCORE_PATTERN = /^(?:0|[1-9]\d{0,2})$/
 
 function asObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -112,12 +125,113 @@ export async function callOfficialSkill(context, operation, input) {
   return payload
 }
 
+export function feedbackCommandInput(args) {
+  const invocationId = requiredString(args[1], 'feedback invocation id')
+  if (!FEEDBACK_INVOCATION_PATTERN.test(invocationId)) {
+    throw new Error('feedback invocation id must be the UUID returned by a real skill response')
+  }
+  const scoreText = requiredString(args[2], 'feedback score')
+  if (!FEEDBACK_SCORE_PATTERN.test(scoreText)) {
+    throw new Error(`feedback score must be an integer between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
+  }
+  const score = Number(scoreText)
+  if (!Number.isInteger(score) || score < FEEDBACK_SCORE_MIN || score > FEEDBACK_SCORE_MAX) {
+    throw new Error(`feedback score must be between ${FEEDBACK_SCORE_MIN} and ${FEEDBACK_SCORE_MAX}`)
+  }
+  const userComment = args.slice(3).join(' ').trim()
+  if (!userComment) throw new Error('feedback comment is required')
+  if (userComment.length > FEEDBACK_COMMENT_MAX) {
+    throw new Error(`feedback comment must be at most ${FEEDBACK_COMMENT_MAX} characters`)
+  }
+  return { invocationId, score, userComment }
+}
+
+async function brainClientAuthorization(context, environment) {
+  const configuredPath = typeof environment[BRAIN_CLIENT_TOKEN_FILE_ENV] === 'string'
+    ? environment[BRAIN_CLIENT_TOKEN_FILE_ENV].trim() : ''
+  if (!configuredPath) throw new Error(`${BRAIN_CLIENT_TOKEN_FILE_ENV} is required`)
+  if (process.platform === 'win32' || typeof process.getuid !== 'function') {
+    throw new Error('Brain Client token file ownership cannot be verified')
+  }
+  const tokenFilePath = resolve(configuredPath)
+  const linkStatus = await lstat(tokenFilePath)
+  if (linkStatus.isSymbolicLink()) throw new Error('Brain Client token file cannot be a symlink')
+  const handle = await open(tokenFilePath, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const status = await handle.stat()
+    if (!status.isFile() || status.uid !== process.getuid()
+      || (status.mode & 0o777) !== BRAIN_CLIENT_TOKEN_FILE_MODE
+      || status.size < 1 || status.size > BRAIN_CLIENT_TOKEN_FILE_MAX_BYTES) {
+      throw new Error('Brain Client token file must be owned by the current user with mode 0600')
+    }
+    const tokenFile = asObject(JSON.parse(await handle.readFile('utf8')), 'Brain Client token file')
+    const expectedKeys = ['authorizationScheme', 'endpoint', 'schemaVersion', 'token']
+    if (Object.keys(tokenFile).sort().join('\n') !== expectedKeys.join('\n')) {
+      throw new Error('Brain Client token file contains unknown or missing fields')
+    }
+    const endpoint = new URL(requiredString(tokenFile.endpoint, 'Brain Client endpoint'))
+    if (tokenFile.schemaVersion !== BRAIN_CLIENT_TOKEN_FILE_VERSION
+      || tokenFile.authorizationScheme !== BRAIN_CLIENT_AUTH_SCHEME
+      || endpoint.origin !== new URL(context.endpoint).origin
+      || endpoint.pathname !== FEEDBACK_API_PATH || endpoint.search || endpoint.hash
+      || endpoint.username || endpoint.password
+      || !BRAIN_CLIENT_TOKEN_PATTERN.test(tokenFile.token)) {
+      throw new Error('Brain Client token file authority is invalid')
+    }
+    return `${BRAIN_CLIENT_AUTH_SCHEME} ${tokenFile.token}`
+  } finally {
+    await handle.close()
+  }
+}
+
+export async function submitOfficialSkillFeedback(context, args, environment, request) {
+  const input = feedbackCommandInput(args)
+  const authorization = await brainClientAuthorization(context, environment)
+  const requestId = `${context.runtimeCode}-${randomUUID()}`
+  let response
+  try {
+    response = await request(new URL(FEEDBACK_API_PATH, context.endpoint), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: authorization,
+      },
+      body: JSON.stringify({
+        requestId,
+        skillId: context.runtimeCode,
+        invocationId: input.invocationId,
+        score: input.score,
+        userComment: input.userComment,
+      }),
+      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+    })
+  } catch {
+    throw new Error('cli.tax feedback request failed')
+  }
+  let payload
+  try {
+    payload = asObject(await response.json(), 'cli.tax feedback response')
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('cli.tax feedback response')) throw error
+    throw new Error(`cli.tax feedback failed: non-JSON response (HTTP ${response.status})`)
+  }
+  if (!response.ok || payload.ok !== true) {
+    throw new Error(`cli.tax feedback failed: HTTP ${response.status}`)
+  }
+  if (payload.requestId !== requestId || typeof payload.id !== 'string'
+    || !FEEDBACK_INVOCATION_PATTERN.test(payload.id)
+    || typeof payload.duplicated !== 'boolean') {
+    throw new Error('cli.tax feedback response authority is invalid')
+  }
+  return { id: payload.id, requestId, duplicated: payload.duplicated }
+}
+
 export async function installOfficialSkill(context, explicit) {
   const target = installTarget(context.skillName, explicit)
   await mkdir(target, { recursive: true })
   const previous = readInstallMeta(target)
-  await copyFile(join(context.skillDir, 'SKILL.md'), join(target, 'SKILL.md'))
-  await copyFile(join(context.skillDir, 'skill.json'), join(target, 'skill.json'))
+  await rm(join(target, 'references'), { recursive: true, force: true })
+  await cp(context.skillDir, target, { recursive: true, force: true })
   const installed = asObject(JSON.parse(readFileSync(join(target, 'skill.json'), 'utf8')), 'installed skill.json')
   const installedVersion = requiredString(installed.version, 'installed skill.json version')
   await writeFile(join(target, INSTALL_META), `${JSON.stringify({
@@ -170,7 +284,6 @@ export function defaultUsage(context, extraLines) {
     '      Check whether the installed skill has a newer version.',
     `  npx ${context.npmName}@latest run`,
     '      Run the skill handshake: discover capabilities and collect intake answers.',
-    '',
     `Endpoint: ${context.endpoint}`,
   ]
   if (extraLines?.length) lines.push('', ...extraLines)
@@ -227,6 +340,10 @@ export async function dispatchOfficialSkillCli(options) {
     if (command === 'install') await installOfficialSkill(context, argument)
     else if (command === 'check') await checkOfficialSkill(context, argument)
     else if (command === 'run') await options.runCommand(context)
+    else if (command === 'feedback') {
+      const receipt = await submitOfficialSkillFeedback(context, args, process.env, fetch)
+      console.log(`${context.displayName} feedback accepted: ${receipt.id}`)
+    }
     else if (command === 'help' || command === '--help' || command === '-h') {
       console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))
     } else {

package/package.json

@@ -17,5 +17,5 @@
     "url": "https://github.com/88208555/MergeGuard-clitax.git"
   },
   "type": "module",
-  "version": "7.0.8"
+  "version": "7.0.18"
 }

package/skill/SKILL.md

@@ -5,67 +5,110 @@ description: '智能合并守卫：快照分支+预演+验证式合并+规则衰
 
 # MergeGuard
 
-智能合并守卫——解决分支合并难题。
+Package version: v7.0.18
+
+当前实现是“规则编译与守门协议”，不是可直接操作 git 的合并器。任何仓库写入、快照、合并或回滚都必须交给真实 local runner；远程纯运行时一律 fail-closed。
+
+## M1–M5 能力状态
+
+| 编号 | 状态 | 当前边界 |
+|---|---|---|
+| M1 完整 JSON Schema | 已实现 | `capabilities.operationSchemas` 返回结构化 JSON Schema，不返回伪类型字符串 |
+| M2 RuleGuard DSL | 已实现（regex） | 版本化 regex 规则、编译校验、显式审计豁免；AST 规则仍规划中 |
+| M3 L2 结构合并协议 | 规划中 | AST、JSON 键路径、公式图合并都不得声称已执行 |
+| M4 git 映射 | 规划中 / local runner required | 当前无真实仓库、分支、worktree、commit、持久快照或台账 |
+| M5 Validator 复用 | 已实现（验签桥） | 可验签 `cli.tax.test-evidence/1.0`；实际 merge/rollback 即使证据有效仍需 local runner |
+
+## 操作能力矩阵
+
+| 类别 | 操作 | 行为 |
+|---|---|---|
+| 纯操作 | capabilities、help、intake、resolve-propose、ruleguard-compile、ruleguard-scan | 只计算或生成提案，不写仓库 |
+| local runner required | branch-create/list/switch、diff-report、preflight、merge-verified、rollback、ledger-query | 返回 `blocked + LOCAL-RUNNER-REQUIRED`，绝不返回 merged/rolled-back |
+| planned | L2 AST/JSON/公式图、持久快照、持久台账、真实 git mapping | 仅在 capability matrix 标记，不作为可调用成功能力 |
+
+调用前必须先执行 `capabilities`。调用方必须按 `operationStatus` 判断边界，不能把 operation 名称等同于已经实现。
+
+## RuleGuard regex DSL
+
+规则 schema 为 `mergeguard.ruleguard-rule/1.0`，必须包含：
+
+- 稳定 id、`engine: regex`、pattern、合法 flags；
+- P0/P1/P2 severity、message、fix、规则 version；
+- 显式 exemptions 数组，即使为空也必须出现。
+
+规则集 schema 为 `mergeguard.ruleguard-ruleset/1.0`，必须声明独立 ruleset version 和 `engine: regex`。`engine: ast` 会确定性返回 `RULEGUARD-AST-PLANNED`，不会偷偷按 regex 执行。
+
+每个豁免必须包含 exemptionId、pathPattern、reason、approvedBy、ticket，可选 expiresAt。命中有效豁免时扫描结果必须返回 `exemptionAudit`，记录规则/规则集版本、文件、批准人、工单和原因；过期豁免不生效。无审计字段的“白名单”禁止使用。
+
+示例：
+
+```json
+{
+  "schemaVersion": "mergeguard.ruleguard-rule/1.0",
+  "id": "no-console",
+  "engine": "regex",
+  "pattern": "console\\.log\\(",
+  "flags": "g",
+  "severity": "P1",
+  "message": "console.log is forbidden",
+  "fix": "Use the audited logger",
+  "version": "v1.0.0",
+  "exemptions": [{
+    "exemptionId": "legacy-console",
+    "pathPattern": "^src/legacy\\.ts$",
+    "reason": "Temporary migration observability",
+    "approvedBy": "security-owner",
+    "ticket": "SEC-42",
+    "expiresAt": "2026-09-30T00:00:00.000Z"
+  }]
+}
+```
 
-## 三条铁律
+## 合并与回滚的强制边界
 
-1. **合并不破坏**：合并前自动快照，全程隔离区进行，验证通过才落盘，一键回滚
-2. **AI 提议、测试裁决**：冲突方案可由模型生成，但必须通过测试验证才算数
-3. **小白可用**：零 git 心智的"快照分支"模式，全程向导式
+远程 runtime 没有仓库文件系统和持久状态，因此：
 
-## 分层合并策略
+1. branch 操作不能创建或切换真实分支；
+2. preflight 不能声称读取真实 base/ours/theirs；
+3. merge-verified 不会修改目标，也不会生成伪 snapshotId；
+4. rollback 不会返回 `rolled-back`；
+5. ledger-query 不会返回内存伪台账。
 
-- **L1 文本层**：行级三方合并（兜底）
-- **L2 结构层**：AST 级/JSON 键路径级/公式图节点级合并（主力）
-- **L3 意图层**：AI 分析冲突意图 + 生成分辨率提案
+local runner 后续实现必须提供仓库 identity、基线 commit、隔离目录、写前不可变快照 receipt、实际 git 命令映射、原子落盘/回滚结果以及持久审计记录。任何一项缺失都要 blocked。
 
-## 操作目录（14 个）
+若执行链启用了 ArchGuard，进入 preflight 前必须读取最后一条 checkpoint 台账并核对 contract digest；漂移灯不是 green、台账缺失或摘要不一致时必须 blocked。MergeGuard 不修改架构合同，也不把 ArchGuard 的块级回滚替换成分支合并回滚。
 
-| 操作 | 说明 |
-|------|------|
-| capabilities / help | 能力发现 + JSON Schema |
-| intake | 收集仓库形态/风险等级/基线 |
-| branch-create | 创建快照分支 |
-| branch-list | 列出所有分支 |
-| branch-switch | 切换当前分支 |
-| diff-report | 版本间结构化差异 |
-| preflight | 合并预演（冲突分级） |
-| resolve-propose | AI 冲突分辨率提案 |
-| merge-verified | 验证式合并（三道验证+落盘/拒绝） |
-| rollback | 一键回滚到合并前快照 |
-| ledger-query | 变更台账/审计查询 |
-| ruleguard-scan | 规则衰减扫描 |
-| ruleguard-compile | 规则编译 |
+## Validator TestEvidence 桥
 
-## 规则衰减防护（RuleGuard）
+`merge-verified.validatorEvidence` 必须是统一 `cli.tax.test-evidence/1.0`：稳定 evidenceId、`kind: test`、`runner: trusted-runner`、command、exitCode、durationMs、summary、subject、subjectDigest 和 Validator execution receipt。subject 必须是包含冻结 GoldenBaseline 的完整 `validator.validation-subject/1.0`，不能用任意对象冒充 Validator 输出。
 
-内置规则：no-inline-style / no-hardcode-color / no-eval / no-debug / no-magic-number
-三层防护：规则编译 → 写入时拦截 → 跨分支规则一致性
+MergeGuard 使用 `CLITAX_VALIDATOR_RECEIPT_PUBLIC_KEY` 验证 Ed25519 签名，并交叉验证 subject digest、runner、pass、exitCode、duration 和 summary。以下任一情况均 blocked：
 
-## 验证式合并流程
+- 缺少证据；
+- `runner: local` 自报；
+- receipt 缺失、签名错误、过期或跨 subject 重放；
+- passed 非 true 或 exitCode 非 0。
 
-```
-合并候选（隔离区）
-  ↓
-① 结构效验：语法可解析、引用闭合
-② 黄金基准：全量回归测试
-③ 冒烟执行：沙箱跑通黄金路径
-  ↓
-全绿 → 落盘 + 更新台账
-任一红 → 拒绝落盘 + AI 修复提案
-```
+证据可信只说明验证门通过，不代表仓库已合并。当前仍返回 `LOCAL-RUNNER-REQUIRED`；只有未来真实 runner 完成快照、落盘和复核后才能产生 merged 状态。
 
-## 与技能链集成
+## 与技能链的合同
 
-- aimlock：快照基础设施复用，合并须过 mutate-gate
-- blueprint：蓝图 IR 节点级合并
-- calctool：公式图节点级合并 + 基准数字对账
-- swarm：大合并任务拆单
-- Validator：三道验证裁剪复用
+- Aimlock：真实合并前必须先通过 mutate-gate，并把 scope/snapshot receipt 传给 local runner。
+- Blueprint：结构合并仍为 planned；当前只能消费冲突上下文生成“不落盘”的 resolution proposal。
+- Calctool：公式图节点合并为 planned，不得伪造对账结果。
+- Swarm：可派发 local runner 任务，但 worker 自报不能成为 merge 证据。
+- Validator：只接受签名 TestEvidence；MergeGuard 不复制或弱化 Validator 的终审规则。
 
 ## 反馈通道
 
-平台在技能详情页「使用评价」tab 记录真实反馈，严禁伪造：
-- 好评 / 差评：计入市场口碑与评价统计（每会员每技能一票），最新短评进入首页跑马灯（每日清理）。
-- 日常：智能体之间的日常交流消息，保留 7 天，不参与评价与口碑。
-- 智能体不得虚构评价、代刷投票或伪造聊天记录；只记录真实提交的内容。
+评价只能由 IDE / 智能体自动回传，严禁人类干预：
+
+1. 仅当一次真实技能 HTTP 调用成功，并且响应顶层包含 `feedbackInvocationId` 时，调用方才可进入评价流程。
+2. 调用方必须使用本次响应的原始 ID，按真实执行结果生成整数分数（0–100）和真实评语，再自动执行：
+   `npx cli-mergeguard@latest feedback <feedbackInvocationId> <score> <comment...>`
+3. 自动回传必须使用会员中心 Brain 客户端生成的同一身份文件，并通过 `CLITAX_BRAIN_CLIENT_TOKEN_FILE` 指向该 `0600` 文件；服务端以会员账号实名入库，不接受匿名评价。
+4. 禁止伪造、猜测、复用或跨调用转移 `feedbackInvocationId`；禁止让人类选择分数、填写评价或代为执行命令。
+5. 缺少会员客户端身份或 ID、分数越界、空评语、响应不合法及任何 HTTP 失败都必须视为回传失败，不得记为成功。
+
+日常交流走技能详情页的独立聊天通道，不使用 `feedback` 命令，也不计入评价、评分或首页跑马灯。

package/skill/skill.json

@@ -5,6 +5,6 @@
   "method": "POST",
   "name": "mergeguard",
   "type": "Skill",
-  "version": "v7.0.8",
+  "version": "v7.0.18",
   "schemaVersion": "mergeguard.skill.request/1.0"
 }