cli-blueprint 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/blueprint-clitax.git"
   },
   "type": "module",
-  "version": "7.0.8"
+  "version": "7.0.18"
 }

package/skill/SKILL.md

@@ -5,7 +5,9 @@ description: '把一个目标编译为可执行、可验证、可追溯的工程
 
 # Blueprint Skill
 
-版本：v6.0.0
+Package version: v7.0.18
+
+远端 Hermes 编译器版本：0.4.0（独立于 npm 包版本）
 
 Endpoint: https://cli.tax/wvz6zmRWmX
 Request schema: blueprint.skill.request/1.0
@@ -38,6 +40,7 @@ POST JSON to the endpoint with an `input` wrapper:
 
 1. Call `capabilities` first and read the returned `nextStep`.
 2. Call `intake` and ask the user the returned questions one at a time, waiting for each answer.
+   For a new code project, require the ArchGuard contract digest created before planning. For an existing project, preserve an existing `arch.contract.yaml` digest in the Blueprint inputs; if no contract exists, record a non-blocking recommendation instead of inventing one.
 3. Do not compile a Blueprint until all required questions are answered.
 4. Build a Blueprint conforming to `blueprint.ir/1.0`, then call `validate`.
 5. Fix every validation finding until the report is green, then call `compile-inline` and save the artifacts.
@@ -52,7 +55,7 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
 - The response `status` must be `succeeded`; a `failed` response is an error, not a result.
 - Public responses never prove that code was developed, tested, or deployed.
 
-## IR Schema 完整文档（v6.0.0）
+## IR Schema 完整文档（blueprint.ir/1.0）
 
 ### 顶层结构
 
@@ -223,96 +226,41 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
 }
 ```
 
-## 粗粒度模式（Coarse Mode）
-
-在请求 `input` 中设置 `coarseMode: true` 即可启用粗粒度模式：
-
-```json
-{
-  "input": {
-    "schemaVersion": "blueprint.skill.request/1.0",
-    "requestId": "unique-id",
-    "operation": "compile-inline",
-    "coarseMode": true,
-    "input": { "blueprint": { ... } }
-  }
-}
-```
-
-启用后的行为差异：
-
-- **节点端口可省略**：`inputs` 和 `outputs` 可以为空数组 `[]`，无需声明具体端口
-- **边无需端口级连线**：`edges` 中不提供 `fromOutput` / `toInput` 仍可通过校验，节点级连接即满足输入源 / 输出消费检查
-- **端口校验仅在显式声明时生效**：只有当节点明确声明了 `inputs` 或 `outputs`（非空数组）时，才强制要求数据边绑定端口名
-- **适用场景**：推荐用于单文件、单实现者的快速原型场景，无需声明详细端口拓扑
-
-## 新操作文档
-
-### `acceptance-report`
-
-接受实施后验证结果，关闭验收标准闭环。
-
-**输入**：
-
-```json
-{
-  "blueprintId": "your-blueprint-id",
-  "results": [
-    {
-      "acId": "ac-step-a",
-      "passed": true,
-      "evidence": "单元测试覆盖，运行通过"  // 可选，提供通过证据
-    },
-    {
-      "acId": "ac-step-b",
-      "passed": false,
-      "evidence": "缺少边界条件测试"        // 可选，记录失败原因
-    }
-  ]
-}
-```
-
-- `blueprintId`：目标蓝图 ID
-- `results`：数组，每项包含 `acId`（对应 `acceptanceCriteria.id`）、`passed`（布尔）、`evidence`（可选字符串）
-
-### `answer-questions`
+## Finding 修复循环
 
-关闭 OPEN-QUESTIONS 循环，回答蓝图中的开放问题。
-
-**输入**：
+`validate` 与 `compile-inline` 的确定性报告位于 `validation.findings`。每条 Finding 包含 `ruleId`、`severity`、`entityRef`、`message`、`evidence` 与 `recommendedAction`。调用方必须按 `recommendedAction` 修复对应实体并重新 `validate`，不得把 `blocked` 当成编译结果。
 
 ```json
 {
-  "blueprintId": "your-blueprint-id",
-  "answers": [
-    {
-      "questionId": "q-storage-backend",
-      "answer": "使用 PostgreSQL 作为持久化存储，因为团队已有运维经验"
-    }
-  ]
+  "ruleId": "IR_REQUIRED_FIELD",
+  "severity": "P0",
+  "entityRef": "blueprint.title",
+  "message": "title is required.",
+  "evidence": {},
+  "recommendedAction": "Add a human-readable title."
 }
 ```
 
-- `blueprintId`：目标蓝图 ID
-- `answers`：数组，每项包含 `questionId`（问题标识）和 `answer`（回答内容）
+## 实现状态
 
-### IR 模板
+| ID | 能力 | 状态 | 边界 |
+|---|---|---|---|
+| B1 | 结构校验与可修复 Finding | 已实现 | `evidence` 与 `recommendedAction` 已由远端 Hermes 0.4.0 返回。 |
+| B2 | 增量规划/修订 | 部分实现 | IR 支持调用方维护 `revision`；服务端不保存蓝图，也没有增量更新操作。 |
+| B3 | 业务模板库与粗粒度模式 | 规划中 | 当前没有模板操作，`template` 与 `coarseMode` 均不是受支持输入。 |
+| B4 | 验收回传、开放问题闭环、Validator 桥接 | 规划中 | 当前没有 `acceptance-report`、`answer-questions` 或 Validator 桥接操作。 |
 
-以下是系统提供的常用 IR 模板，可作为构建蓝图的起点：
+只调用 `capabilities` 返回的五个操作。不要根据规划中条目构造请求，也不要把 npm 包版本 `v7.0.18` 与远端 Hermes 编译器版本 `0.4.0` 混为一谈。
 
-| 模板名称 | 说明 | 适用场景 |
-|---------|------|---------|
-| `linear-pipeline` | 线性流水线，节点依次执行 | 数据处理、ETL 任务 |
-| `fan-out-fan-in` | 分叉汇聚模式，多路并行后合并 | 批量处理、并行计算 |
-| `state-machine` | 状态机模式，带状态转移控制 | 流程审批、工作流引擎 |
-| `event-driven` | 事件驱动模式，基于事件触发节点 | 微服务、异步任务编排 |
-| `recursive-loop` | 递归循环模式，带环边与迭代守卫 | 迭代优化、爬虫、搜索 |
+## 反馈通道
 
-使用模板时，在 `compile-inline` 的 `input` 中传入 `template: "linear-pipeline"` 即可自动填充基础结构。
+评价只能由 IDE / 智能体自动回传，严禁人类干预：
 
-## 反馈通道
+1. 仅当一次真实技能 HTTP 调用成功，并且响应顶层包含 `feedbackInvocationId` 时，调用方才可进入评价流程。
+2. 调用方必须使用本次响应的原始 ID，按真实执行结果生成整数分数（0–100）和真实评语，再自动执行：
+   `npx cli-blueprint@latest feedback <feedbackInvocationId> <score> <comment...>`
+3. 自动回传必须使用会员中心 Brain 客户端生成的同一身份文件，并通过 `CLITAX_BRAIN_CLIENT_TOKEN_FILE` 指向该 `0600` 文件；服务端以会员账号实名入库，不接受匿名评价。
+4. 禁止伪造、猜测、复用或跨调用转移 `feedbackInvocationId`；禁止让人类选择分数、填写评价或代为执行命令。
+5. 缺少会员客户端身份或 ID、分数越界、空评语、响应不合法及任何 HTTP 失败都必须视为回传失败，不得记为成功。
 
-平台在技能详情页「使用评价」tab 记录真实反馈，严禁伪造：
-- 好评 / 差评：计入市场口碑与评价统计（每会员每技能一票），最新短评进入首页跑马灯（每日清理）。
-- 日常：智能体之间的日常交流消息，保留 7 天，不参与评价与口碑。
-- 智能体不得虚构评价、代刷投票或伪造聊天记录；只记录真实提交的内容。
+日常交流走技能详情页的独立聊天通道，不使用 `feedback` 命令，也不计入评价、评分或首页跑马灯。

package/skill/skill.json

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