cli-blueprint 5.0.3 → 7.0.1

package/installer.mjs

@@ -0,0 +1,241 @@
+/**
+ * 五个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
+ * 禁止第二套超时、第二套版本来源、第二套 bin 名。
+ */
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { stdin, stdout } from 'node:process'
+import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+
+export const LOOKUP_TIMEOUT_MS = 8000
+export const CALL_TIMEOUT_MS = 120_000
+const INSTALL_META = 'install-meta.json'
+
+function asObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`)
+  }
+  return value
+}
+
+function requiredString(value, label) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) throw new Error(`${label} is required`)
+  return text
+}
+
+export function loadOfficialSkillContext(packageRoot) {
+  const pkg = asObject(JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')), 'package.json')
+  const skill = asObject(JSON.parse(readFileSync(join(packageRoot, 'skill/skill.json'), 'utf8')), 'skill.json')
+  const npmName = requiredString(pkg.name, 'package.json name')
+  const packageVersion = requiredString(pkg.version, 'package.json version')
+  const displayName = requiredString(skill.displayName, 'skill.json displayName')
+  const skillName = requiredString(skill.name, 'skill.json name')
+  const schemaVersion = requiredString(skill.schemaVersion, 'skill.json schemaVersion')
+  const endpoint = requiredString(skill.endpoint, 'skill.json endpoint')
+  const skillVersion = requiredString(skill.version, 'skill.json version')
+  const runtimeCode = requiredString(endpoint.replace(/^https:\/\/cli\.tax\//, ''), 'runtime code')
+  if (!/^[A-Za-z0-9]{10}$/.test(runtimeCode)) {
+    throw new Error(`skill.json endpoint must be https://cli.tax/{10-char-code}: ${endpoint}`)
+  }
+  if (skillVersion.replace(/^v/i, '') !== packageVersion.replace(/^v/i, '')) {
+    throw new Error(`skill.json ${skillVersion} must match package.json ${packageVersion}`)
+  }
+  return {
+    packageRoot,
+    npmName,
+    packageVersion,
+    displayName,
+    skillName,
+    schemaVersion,
+    endpoint,
+    skillVersion,
+    runtimeCode,
+    latestEndpoint: `https://cli.tax/api/public/skills/${runtimeCode}`,
+    skillDir: join(packageRoot, 'skill'),
+  }
+}
+
+export function readInstallMeta(target) {
+  const path = join(target, INSTALL_META)
+  if (!existsSync(path)) return null
+  return asObject(JSON.parse(readFileSync(path, 'utf8')), INSTALL_META)
+}
+
+export function installTarget(skillName, explicit) {
+  if (explicit) return resolve(explicit)
+  const codexHome = process.env.CODEX_HOME?.trim()
+  if (codexHome) return join(codexHome, 'skills', skillName)
+  return join(process.cwd(), '.codex', 'skills', skillName)
+}
+
+export async function fetchLatestVersion(context) {
+  const response = await fetch(context.latestEndpoint, { signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS) })
+  if (!response.ok) throw new Error(`cli.tax skill lookup failed: HTTP ${response.status}`)
+  const data = asObject(await response.json(), 'cli.tax skill lookup')
+  return {
+    version: requiredString(data.version, 'cli.tax skill lookup version'),
+    displayName: requiredString(data.displayName, 'cli.tax skill lookup displayName'),
+  }
+}
+
+export async function callOfficialSkill(context, operation, input) {
+  const requestId = `${context.npmName}-${Date.now()}`
+  const response = await fetch(context.endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      input: {
+        schemaVersion: context.schemaVersion,
+        requestId,
+        operation,
+        input,
+      },
+    }),
+    signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+  })
+  let payload
+  try {
+    payload = await response.json()
+  } catch {
+    throw new Error(`${context.displayName} ${operation} failed: non-JSON response (HTTP ${response.status}). Check ${context.endpoint}.`)
+  }
+  if (!response.ok || payload?.ok !== true) {
+    const message = payload?.error?.message
+    if (typeof message !== 'string' || !message.trim()) {
+      throw new Error(`${context.displayName} ${operation} failed: HTTP ${response.status}`)
+    }
+    throw new Error(`${context.displayName} ${operation} failed: ${message}`)
+  }
+  return payload
+}
+
+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'))
+  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({
+    source: context.runtimeCode,
+    slug: context.skillName,
+    version: installedVersion,
+    packageVersion: context.packageVersion,
+    endpoint: context.endpoint,
+    installedAt: new Date().toISOString(),
+  }, null, 2)}\n`)
+  if (previous?.version && previous.version !== installedVersion) {
+    console.log(`${context.displayName} skill updated: ${target}`)
+    console.log(`  ${previous.version} → ${installedVersion}`)
+  } else {
+    console.log(`${context.displayName} skill installed: ${target} (${installedVersion})`)
+  }
+  console.log('Next: return to your IDE and state the goal. The agent reads the installed SKILL.md.')
+}
+
+export async function checkOfficialSkill(context, explicit) {
+  const target = installTarget(context.skillName, explicit)
+  const current = readInstallMeta(target)
+  if (!current) {
+    console.log(`${context.displayName} skill is not installed. Run: npx ${context.npmName}@latest install`)
+    process.exitCode = 1
+    return
+  }
+  const installedVersion = requiredString(current.version, 'install-meta.json version')
+  const packageVersion = requiredString(current.packageVersion, 'install-meta.json packageVersion')
+  console.log(`Installed: ${installedVersion} (package ${packageVersion})`)
+  const latest = await fetchLatestVersion(context)
+  console.log(`Latest on cli.tax: ${latest.version}`)
+  if (installedVersion === latest.version) {
+    console.log('Up to date.')
+    return
+  }
+  console.log(`Update available: ${installedVersion} → ${latest.version}`)
+  console.log(`Run: npx ${context.npmName}@latest install`)
+  process.exitCode = 1
+}
+
+export function defaultUsage(context, extraLines) {
+  const lines = [
+    `${context.npmName} — install and run the ${context.displayName} skill from CLI.Tax`,
+    '',
+    'Usage:',
+    `  npx ${context.npmName}@latest install [directory]`,
+    `      Install the ${context.displayName} skill for the current IDE.`,
+    `  npx ${context.npmName}@latest check [directory]`,
+    '      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)
+  return lines.join('\n')
+}
+
+export async function runIntakeHandshake(context, spec) {
+  const capabilities = await callOfficialSkill(context, 'capabilities', {})
+  const output = capabilities.output && typeof capabilities.output === 'object' ? capabilities.output : {}
+  const skill = output.skill && typeof output.skill === 'object' ? output.skill : {}
+  const version = typeof skill.version === 'string' && skill.version.trim()
+    ? skill.version.trim()
+    : context.skillVersion
+  console.log(`${context.displayName} ${version}`)
+  if (typeof spec.afterCapabilities === 'function') spec.afterCapabilities(output)
+  const readline = createInterface({ input: stdin, output: stdout })
+  const answers = []
+  try {
+    for (const question of spec.questions) {
+      const requiredMark = question.required ? ' (required)' : ''
+      console.log(`\n${question.prompt}${requiredMark}`)
+      console.log(`Example: ${question.example}`)
+      for (;;) {
+        const answer = (await readline.question('> ')).trim()
+        if (answer) {
+          answers.push({ id: question.id, prompt: question.prompt, answer })
+          break
+        }
+        if (!question.required) break
+        console.log('This question is required. Please answer before continuing.')
+      }
+    }
+  } finally {
+    readline.close()
+  }
+  const target = join(process.cwd(), spec.outputFile)
+  await writeFile(target, `${JSON.stringify({
+    schemaVersion: context.schemaVersion,
+    endpoint: context.endpoint,
+    createdAt: new Date().toISOString(),
+    answers,
+  }, null, 2)}\n`)
+  console.log(`\nRequirements saved: ${target}`)
+  console.log('Next: continue in your IDE agent with this file.')
+}
+
+export async function dispatchOfficialSkillCli(options) {
+  const packageRoot = options.packageRoot ?? dirname(fileURLToPath(options.importMetaUrl))
+  const context = loadOfficialSkillContext(packageRoot)
+  const args = process.argv.slice(2)
+  const command = args[0] ?? 'help'
+  const argument = args[1]
+  try {
+    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 === 'help' || command === '--help' || command === '-h') {
+      console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))
+    } else {
+      console.error(`Unknown command: ${command}`)
+      console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))
+      process.exitCode = 1
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error)
+    process.exitCode = 1
+  }
+}

package/package.json

@@ -5,17 +5,17 @@
   "description": "Blueprint skill installer for CLI.Tax: compile one goal into an executable, verifiable engineering blueprint.",
   "files": [
     "cli.mjs",
+    "installer.mjs",
     "README.md",
     "skill/SKILL.md",
     "skill/skill.json"
   ],
   "license": "UNLICENSED",
   "name": "cli-blueprint",
-  "private": false,
   "repository": {
     "type": "git",
     "url": "https://github.com/88208555/blueprint-clitax.git"
   },
   "type": "module",
-  "version": "5.0.3"
+  "version": "7.0.1"
 }

package/skill/SKILL.md

@@ -5,6 +5,8 @@ description: '把一个目标编译为可执行、可验证、可追溯的工程
 
 # Blueprint Skill
 
+版本：v6.0.0
+
 Endpoint: https://cli.tax/wvz6zmRWmX
 Request schema: blueprint.skill.request/1.0
 Response schema: blueprint.skill.response/1.0
@@ -49,3 +51,261 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
 - Never send credentials, model keys, provider endpoints, or personal secrets inside the request envelope or `input`.
 - 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）
+
+### 顶层结构
+
+```json
+{
+  "schemaVersion": "blueprint.ir/1.0",  // 必填，必须是这个值
+  "blueprintId": "string",               // 必填，kebab-case
+  "title": "string",                     // 必填
+  "revision": 0,                         // 必填，非负整数（0, 1, 2...）
+  "entryNodeId": "string",              // 必填，指向 nodes 中 entry:true 的节点
+  "baseline": {
+    "summary": "string",                // 必填
+    "facts": [                           // 必填，对象数组
+      {
+        "id": "string",                  // 每个 fact 必须有 id
+        "statement": "string",           // 必填
+        "status": "confirmed"            // 必填枚举，见下方
+      }
+    ]
+  },
+  "domains": [                           // 必填
+    {
+      "id": "string",
+      "name": "string",
+      "summary": "string"                // 可选
+    }
+  ],
+  "modules": [                           // 必填
+    {
+      "id": "string",                    // 必填
+      "domainId": "string",              // 必填，引用 domains.id
+      "name": "string"
+    }
+  ],
+  "nodes": [                             // 必填，非空
+    {
+      "id": "string",                    // 注意：是 id 不是 nodeId
+      "entry": true,                     // true 标记入口节点（且仅一个）
+      "moduleId": "string",              // 引用 modules.id
+      "title": "string",                 // 必填
+      "inputs": [                        // 必须是命名对象数组，字符串数组被拒
+        { "name": "string" }
+      ],
+      "outputs": [                       // 同上
+        { "name": "string", "exposed": true }
+      ],
+      "requirementRefs": ["string"]      // 引用 baseline.facts.id
+    }
+  ],
+  "edges": [                             // 必填
+    {
+      "id": "string",
+      "fromNodeId": "string",            // 引用 nodes.id
+      "toNodeId": "string",              // 引用 nodes.id
+      "type": "data",                    // 必填枚举，见下方
+      "fromOutput": "string",            // 数据边必须精确到端口名
+      "toInput": "string",               // 数据边必须精确到端口名
+      "allowCycle": true,                // 环边必须 true
+      "loopGuard": "string",             // 环边必须有文字说明
+      "loopLimit": {                     // 环边必须有迭代上限
+        "maxIterations": 10
+      }
+    }
+  ],
+  "acceptanceCriteria": [                // 必填
+    {
+      "id": "string",
+      "statement": "string",
+      "nodeRefs": ["string"]             // 引用 nodes.id，无 nodeRefs 视为未链接（P1）
+    }
+  ]
+}
+```
+
+### 字段枚举值
+
+**fact.status**：`"confirmed"` | `"inferred"` | `"defaulted"` | `"unknown"` | `"conflicted"` | `"rejected"`
+
+**edge.type**：`"data"` | `"control"` | `"success"` | `"error"` | `"trace"` | `"event"` | `"approval"` | `"recovery"` | `"audit"` | `"optional"` | `"compensation"`
+
+> ⚠️ `"depends-on"` 不被接受，必须使用上述合法枚举值。
+
+### 校验规则
+
+- **节点覆盖**：每个节点必须被至少一条 acceptanceCriteria 覆盖（通过 `nodeRefs`）
+- **事实追溯**：每个 fact 必须追溯到节点（通过 `nodes.requirementRefs`）
+- **入口节点**：仅一个节点 `entry: true`，且必须是 `entryNodeId` 指向的节点
+- **数据边**：必须 `fromOutput` / `toInput` 精确匹配端口名
+- **控制边**：不需要端口级连线
+- **环边**：`type` 必须是 `"control"` 或 `"optional"`，必须同时包含 `allowCycle: true` + `loopGuard`（文字说明）+ `loopLimit`（含 `maxIterations` 数字）
+
+### 最小合法示例
+
+```json
+{
+  "schemaVersion": "blueprint.ir/1.0",
+  "blueprintId": "demo-pipeline",
+  "title": "Demo Pipeline",
+  "revision": 0,
+  "entryNodeId": "step-a",
+  "baseline": {
+    "summary": "A minimal 2-node linear pipeline",
+    "facts": [
+      {
+        "id": "f-input",
+        "statement": "System must accept user input",
+        "status": "confirmed"
+      }
+    ]
+  },
+  "domains": [
+    {
+      "id": "d-core",
+      "name": "Core"
+    }
+  ],
+  "modules": [
+    {
+      "id": "m-impl",
+      "domainId": "d-core",
+      "name": "Implementation"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "step-a",
+      "entry": true,
+      "moduleId": "m-impl",
+      "title": "Step A – Receive Input",
+      "inputs": [],
+      "outputs": [
+        { "name": "data" }
+      ],
+      "requirementRefs": ["f-input"]
+    },
+    {
+      "id": "step-b",
+      "moduleId": "m-impl",
+      "title": "Step B – Process",
+      "inputs": [
+        { "name": "data" }
+      ],
+      "outputs": []
+    }
+  ],
+  "edges": [
+    {
+      "id": "e-a-to-b",
+      "fromNodeId": "step-a",
+      "toNodeId": "step-b",
+      "type": "data",
+      "fromOutput": "data",
+      "toInput": "data"
+    }
+  ],
+  "acceptanceCriteria": [
+    {
+      "id": "ac-step-a",
+      "statement": "Input is received and forwarded",
+      "nodeRefs": ["step-a"]
+    },
+    {
+      "id": "ac-step-b",
+      "statement": "Processing completes successfully",
+      "nodeRefs": ["step-b"]
+    }
+  ]
+}
+```
+
+## 粗粒度模式（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`
+
+关闭 OPEN-QUESTIONS 循环，回答蓝图中的开放问题。
+
+**输入**：
+
+```json
+{
+  "blueprintId": "your-blueprint-id",
+  "answers": [
+    {
+      "questionId": "q-storage-backend",
+      "answer": "使用 PostgreSQL 作为持久化存储，因为团队已有运维经验"
+    }
+  ]
+}
+```
+
+- `blueprintId`：目标蓝图 ID
+- `answers`：数组，每项包含 `questionId`（问题标识）和 `answer`（回答内容）
+
+### IR 模板
+
+以下是系统提供的常用 IR 模板，可作为构建蓝图的起点：
+
+| 模板名称 | 说明 | 适用场景 |
+|---------|------|---------|
+| `linear-pipeline` | 线性流水线，节点依次执行 | 数据处理、ETL 任务 |
+| `fan-out-fan-in` | 分叉汇聚模式，多路并行后合并 | 批量处理、并行计算 |
+| `state-machine` | 状态机模式，带状态转移控制 | 流程审批、工作流引擎 |
+| `event-driven` | 事件驱动模式，基于事件触发节点 | 微服务、异步任务编排 |
+| `recursive-loop` | 递归循环模式，带环边与迭代守卫 | 迭代优化、爬虫、搜索 |
+
+使用模板时，在 `compile-inline` 的 `input` 中传入 `template: "linear-pipeline"` 即可自动填充基础结构。

package/skill/skill.json

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