harveyz-skill 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.34.0] - 2026-09-16
+
+### Added
+- `hskill` 双来源安装与粘性更新：`hskill update --local <路径>` 从本地仓库 `npm pack` 出 tarball 再全局安装（真实拷贝，走 `prepack` 与 `files[]` 白名单，等于在发 npm 前预演一次真实发布），`hskill update --npm` 切回 registry，裸 `hskill update` 沿用当前来源不跨轨道。此前 `update` 是一行硬编码的 `npm install -g harveyz-skill@latest`，手工装的本地版会被它静默替换掉且事后无从察觉。来源痕迹（`.hskill-source.json` + 版本号后缀 `+local`）只写在全局安装目录内，因而任何一次 `npm install -g`——包括绕过 hskill 的手工安装——都会自动抹掉它，"记录的来源"与"实际的来源"不可能分叉。`hskill version` 展示来源与 branch/commit，`version --check` 在本地来源下比对 commit 而非版本号（开发分支上版本号常常不动）。设计见 `docs/superpowers/specs/2026-09-15-hskill-install-source-design.md`
+- `agent-canvas` bundle：新增 `agent-canvas-control`、`capture-requirement`、`close-node`、`describe-node`、`relate-node`、`relation-review` 六个 skill，在 Agent Canvas 画布节点里操控节点实体、摆放画布、梳理节点间语义关系
+
+### Fixed
+- `hskill <任意子命令> --json` 在输出走管道时被截断：Node 写管道是异步的，而每个子命令块以 `process.exit()` 结尾，不等缓冲区排空。`status --json` 的输出刚随 agent-canvas 六个 skill 涨到 66,739 字节、越过 64KiB 管道缓冲区，于是 `hskill status --json | jq` 拿到退出码 0 和一段从字符串中间断掉的 JSON——**静默失败**，退出码还宣称成功。16 处 `--json` 出口统一改走等待写入落地的 `emitJson()`；回归测试逐字节比对管道输出与直接重定向输出，且在负载跌回缓冲区以下时显式 skip 而非假绿
+- `hskill version` / `hskill --version` 在 npm 不在 PATH 上时抛原始堆栈崩溃（cron、受限 PATH、精简镜像）：来源追踪让 `readSource()` 每次都经 `globalRoot()` 打一次 `npm root -g`，而它只兜住了 JSON 解析失败。现在 `globalRoot()` 的失败并入同一个 `null`，即回落到缺省的 npm 来源
+- `compareVersions()` 遇到 semver build metadata（`0.33.0+local`）会解析出 `NaN` 导致比较结果无意义，现按规范在比较前截断 `+` 及其后内容
+
 ## [0.33.0] - 2026-09-15
 
 ### Added

package/bin/cli.js

@@ -2,7 +2,7 @@
 import { select, input, confirm } from '@inquirer/prompts'
 import chalk from 'chalk'
 import { execSync, spawnSync } from 'child_process'
-import { existsSync, writeFileSync, unlinkSync } from 'fs'
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdtempSync } from 'fs'
 import { createRequire } from 'module'
 import os from 'os'
 import path from 'path'
@@ -24,6 +24,16 @@ const args = process.argv.slice(2)
 const subcommand = args[0]
 const jsonFlag = args.includes('--json')
 
+// Writing to a pipe is asynchronous in Node, and process.exit() throws away
+// whatever is still buffered. Anything past the 64KiB pipe buffer was being cut
+// mid-string, so `hskill status --json | jq` got exit code 0 and unparseable
+// JSON. Every --json emitter goes through here, which resolves only once the
+// write has actually landed.
+async function emitJson(value) {
+  const text = JSON.stringify(value, null, 2) + '\n'
+  await new Promise(resolve => process.stdout.write(text, resolve))
+}
+
 // ── Help ─────────────────────────────────────────────────────────────────────
 function printHelp() {
   console.log(`
@@ -50,10 +60,12 @@ function printHelp() {
     hskill uninstall <tool>            uninstall a shell tool and clean up all files
     hskill uninstall <tool> --yes      skip all confirmations (incl. config files)
     hskill uninstall <skill> --scope <s> --target <t>  uninstall a skill
-    hskill update                  update hskill to the latest version
+    hskill update                  update hskill (sticky: refreshes from whichever source is installed)
+    hskill update --local <path>   switch to / refresh a local repo (npm pack + install)
+    hskill update --npm            switch back to npm registry
     hskill mcp                     start an MCP server (stdio) exposing hskill's tools to MCP-capable agent hosts
-    hskill version                 show version
-    hskill version --check         compare local version against npm registry (no install)
+    hskill version                 show version (adds source/branch/commit lines when installed from a local repo)
+    hskill version --check         compare against npm registry, or against the local source repo's HEAD
     hskill --help                  show this help
 
   ${chalk.cyan('Examples:')}
@@ -74,7 +86,7 @@ function printHelp() {
 
 if (args[0] === '--help' || args[0] === '-h') {
   if (jsonFlag || args.includes('--json')) {
-    console.log(JSON.stringify({
+    await emitJson({
       name: 'hskill',
       version,
       description: 'Skill manager for Claude Code, Cursor, Codex, OpenClaw, Hermes, OpenCode, and Pi',
@@ -138,7 +150,11 @@ if (args[0] === '--help' || args[0] === '-h') {
         },
         {
           name: 'update',
-          description: 'Update hskill to the latest version via npm',
+          description: 'Update hskill; sticky to whichever source (npm or local repo) is currently installed',
+          flags: [
+            { name: '--local', arg: '<path>', description: 'Switch to / refresh a local repo source (npm pack + install -g)' },
+            { name: '--npm',   description: 'Switch back to the npm registry source' },
+          ],
         },
         {
           name: 'mcp',
@@ -149,7 +165,7 @@ if (args[0] === '--help' || args[0] === '-h') {
           description: 'Print version and exit',
         },
       ],
-    }, null, 2))
+    })
     process.exit(0)
   }
   printHelp()
@@ -157,12 +173,37 @@ if (args[0] === '--help' || args[0] === '-h') {
 }
 
 if (args[0] === '--version' || args[0] === '-v' || subcommand === 'version') {
+  const { readSource, gitInfo } = await import('../lib/install-source.js')
+  const source = readSource()
+
   if (subcommand === 'version' && args.includes('--check')) {
+    if (source) {
+      let current
+      try {
+        current = gitInfo(source.repo)
+      } catch (err) {
+        console.error(chalk.red(`  ✗ Could not read local source repo: ${err.message}`))
+        process.exit(1)
+      }
+      const upToDate = current.commit === source.commit && !current.dirty
+      if (jsonFlag) {
+        await emitJson({ source: 'local', repo: source.repo, installedCommit: source.commit, currentCommit: current.commit, dirty: current.dirty, upToDate })
+      } else if (upToDate) {
+        console.log(chalk.green(`  ✔ hskill is up to date with local source (${source.repo}@${current.commit})`))
+      } else if (current.commit !== source.commit) {
+        console.log(chalk.yellow(`  ⚠ local source has new commits: ${source.commit} → ${current.commit}`))
+        console.log(chalk.dim('  Run: hskill update'))
+      } else {
+        console.log(chalk.yellow('  ⚠ local source has uncommitted changes not yet packed'))
+        console.log(chalk.dim('  Run: hskill update'))
+      }
+      process.exit(0)
+    }
     try {
       const { checkNpmVersion } = await import('../lib/version-check.js')
       const { current, latest, upToDate } = await checkNpmVersion('harveyz-skill', version)
       if (jsonFlag) {
-        console.log(JSON.stringify({ current, latest, upToDate }, null, 2))
+        await emitJson({ current, latest, upToDate })
       } else if (upToDate) {
         console.log(chalk.green(`  ✔ hskill v${current} is up to date`))
       } else {
@@ -176,6 +217,11 @@ if (args[0] === '--version' || args[0] === '-v' || subcommand === 'version') {
     process.exit(0)
   }
   console.log(version)
+  if (source) {
+    console.log('')
+    console.log(`source: local  ${source.repo}`)
+    console.log(`branch: ${source.branch}  commit: ${source.commit}${source.dirty ? ' (dirty)' : ''}`)
+  }
   process.exit(0)
 }
 
@@ -223,15 +269,112 @@ async function checkArchivedInstalls() {
 }
 
 // ── Update ───────────────────────────────────────────────────────────────────
-if (subcommand === 'update') {
+// Sticky: whichever source is currently installed (recorded in .hskill-source.json
+// inside the global install dir) is what a bare `update` refreshes from. `--local`
+// and `--npm` explicitly switch the source. See docs/superpowers/specs/2026-09-15-hskill-install-source-design.md
+async function updateToNpm(priorSource) {
   console.log(chalk.dim('  · Updating hskill…'))
   try {
     execSync('npm install -g harveyz-skill@latest', { stdio: 'inherit' })
-    console.log(chalk.green('  ✔ hskill updated'))
   } catch {
     console.error(chalk.red('  ✗ Update failed. Try: npm install -g harveyz-skill@latest'))
     process.exit(1)
   }
+  if (priorSource) {
+    const { globalRoot } = await import('../lib/install-source.js')
+    const newVersion = JSON.parse(readFileSync(path.join(globalRoot(), 'harveyz-skill', 'package.json'), 'utf8')).version
+    console.log(`  ${priorSource.version}+local (${priorSource.branch}@${priorSource.commit}) → ${newVersion} (npm)`)
+  }
+  console.log(chalk.green('  ✔ hskill updated'))
+}
+
+async function updateToLocal(repoPath, priorSource) {
+  if (!existsSync(repoPath)) {
+    console.error(chalk.red(`  ✗ 本地来源仓库不存在：${repoPath}`))
+    console.error(chalk.dim('    改用 npm：   hskill update --npm'))
+    console.error(chalk.dim(`    指向新路径： hskill update --local <新路径>`))
+    process.exit(1)
+  }
+
+  const { gitInfo, writeSource, globalRoot } = await import('../lib/install-source.js')
+  // git info must be collected before `npm pack` — its `prepack` hook rewrites
+  // the tracked .npmignore, which would otherwise poison the dirty check.
+  const info = gitInfo(repoPath)
+  const origVersion = JSON.parse(readFileSync(path.join(repoPath, 'package.json'), 'utf8')).version
+
+  console.log(chalk.dim('  · Packing local repo…'))
+  const tmpDir = mkdtempSync(path.join(os.tmpdir(), 'hskill-pack-'))
+  const packResult = spawnSync('npm', ['pack', '--pack-destination', tmpDir], { cwd: repoPath, encoding: 'utf8' })
+  if (packResult.status !== 0) {
+    console.error(chalk.red('  ✗ npm pack failed'))
+    process.exit(1)
+  }
+  const tarballName = packResult.stdout.trim().split('\n').pop()
+
+  console.log(chalk.dim('  · Installing packed tarball…'))
+  const installResult = spawnSync('npm', ['install', '-g', path.join(tmpDir, tarballName)], { stdio: 'inherit' })
+  if (installResult.status !== 0) {
+    console.error(chalk.red('  ✗ Install failed'))
+    process.exit(1)
+  }
+
+  const installedPkgPath = path.join(globalRoot(), 'harveyz-skill', 'package.json')
+  const installedPkg = JSON.parse(readFileSync(installedPkgPath, 'utf8'))
+  installedPkg.version = `${origVersion}+local`
+  writeFileSync(installedPkgPath, JSON.stringify(installedPkg, null, 2) + '\n')
+
+  writeSource({
+    repo: repoPath,
+    branch: info.branch,
+    commit: info.commit,
+    dirty: info.dirty,
+    version: origVersion,
+    installedAt: new Date().toISOString(),
+  })
+
+  if (priorSource === null) {
+    console.log(`  ${version} (npm) → ${origVersion}+local (${info.branch}@${info.commit})`)
+  } else if (priorSource.repo !== repoPath) {
+    console.log(`  ${priorSource.version}+local (${priorSource.branch}@${priorSource.commit}) → ${origVersion}+local (${info.branch}@${info.commit})`)
+  }
+
+  const npmignoreStatus = execSync('git status --porcelain -- .npmignore', { cwd: repoPath, encoding: 'utf8' }).trim()
+  if (npmignoreStatus) {
+    console.log(chalk.dim('  · .npmignore changed by prepack — left as-is, review with `git diff .npmignore`'))
+  }
+
+  console.log(chalk.green('  ✔ hskill updated'))
+}
+
+if (subcommand === 'update') {
+  const updateArgs = args.slice(1)
+  const localIdx   = updateArgs.indexOf('--local')
+  const npmFlag    = updateArgs.includes('--npm')
+  const localGiven = localIdx !== -1
+  const localPath  = localGiven ? updateArgs[localIdx + 1] : undefined
+
+  if (localGiven && npmFlag) {
+    console.error(chalk.red('  ✗ --local and --npm are mutually exclusive'))
+    process.exit(1)
+  }
+  if (localGiven && (!localPath || localPath.startsWith('--'))) {
+    console.error(chalk.red('  ✗ --local requires a path: hskill update --local <path>'))
+    process.exit(1)
+  }
+
+  const { readSource } = await import('../lib/install-source.js')
+  const priorSource = readSource()
+
+  if (npmFlag) {
+    await updateToNpm(priorSource)
+  } else if (localGiven) {
+    await updateToLocal(localPath, priorSource)
+  } else if (priorSource) {
+    await updateToLocal(priorSource.repo, priorSource)
+  } else {
+    await updateToNpm(priorSource)
+  }
+
   // Run skill rename migrations
   const { renames = [], skills: skillDefs = [] } = require('../skills-index.json')
   if (renames.length > 0) {
@@ -276,10 +419,10 @@ if (subcommand === 'list') {
   const { skills, tools = [] } = require('../skills-index.json')
   const sorted = [...skills].sort((a, b) => a.bundle.localeCompare(b.bundle) || a.path.split('/').pop().localeCompare(b.path.split('/').pop()))
   if (jsonFlag) {
-    console.log(JSON.stringify({
+    await emitJson({
       skills: sorted.map(s => ({ name: s.path.split('/').pop(), path: s.path, bundle: s.bundle, global: s.global ?? false })),
       tools: tools.map(t => t.name),
-    }, null, 2))
+    })
     process.exit(0)
   }
   const nw = Math.max(...sorted.map(s => s.path.split('/').pop().length), 4)
@@ -380,12 +523,12 @@ if (subcommand === 'status' || subcommand === 'outdated') {
       return { name: h.name, description: h.description, user: inst.user, project: inst.project }
     })
     if (outdatedOnly) {
-      console.log(JSON.stringify({
+      await emitJson({
         skills: jsonSkills.filter(s => Object.values(s.user).some(v => v.status === 'update') || Object.values(s.project).some(v => v.status === 'update')),
         tools:  jsonTools.filter(t => t.status === 'update'),
-      }, null, 2))
+      })
     } else {
-      console.log(JSON.stringify({ skills: jsonSkills, tools: jsonTools, hooks: jsonHooks }, null, 2))
+      await emitJson({ skills: jsonSkills, tools: jsonTools, hooks: jsonHooks })
     }
     process.exit(0)
   }
@@ -513,17 +656,17 @@ if (subcommand === 'info') {
   if (jsonFlag) {
     if (skill) {
       const inst = checkInstalled(skill.skillName, skill.version ?? '—')
-      console.log(JSON.stringify({
+      await emitJson({
         name: skill.skillName, type: 'skill', version: skill.version ?? '—',
         user:    Object.fromEntries(targets.map(t => [t, inst.user[t]])),
         project: Object.fromEntries(targets.map(t => [t, inst.project[t]])),
-      }, null, 2))
+      })
     } else {
       const inst = checkToolInstalled(tool.toolName, tool.srcPath)
-      console.log(JSON.stringify({
+      await emitJson({
         name: tool.toolName, type: 'tool', version: tool.version ?? '—',
         installed: inst,
-      }, null, 2))
+      })
     }
     process.exit(0)
   }
@@ -590,7 +733,7 @@ if (subcommand === 'uninstall') {
     const { removed, failed } = await uninstallTool(nameToRemove, { yes: yesFlag })
     if (jsonFlag) {
       console.error = originalError
-      console.log(JSON.stringify({ removed: removed.length > 0, failed: failed.length > 0 }, null, 2))
+      await emitJson({ removed: removed.length > 0, failed: failed.length > 0 })
     } else if (removed.length > 0) {
       console.error(chalk.green.bold(`✔ ${nameToRemove} uninstalled`))
     }
@@ -617,7 +760,7 @@ if (subcommand === 'uninstall') {
   }
   if (jsonFlag) {
     console.error = originalError2
-    console.log(JSON.stringify({ removed: anyRemoved, failed: anyFailed }, null, 2))
+    await emitJson({ removed: anyRemoved, failed: anyFailed })
   } else if (anyRemoved) {
     console.error(chalk.green.bold(`✔ ${nameToRemove} uninstalled`))
   }
@@ -663,7 +806,7 @@ if (subcommand === 'hooks') {
           codex: inst.codex,
         }
       })
-      console.log(JSON.stringify({ hooks: out }, null, 2))
+      await emitJson({ hooks: out })
       process.exit(0)
     }
     function hookIcon(s) {
@@ -724,7 +867,7 @@ if (subcommand === 'hooks') {
     const { installed, skipped, failed } = await installHooksForTarget(toInstall, hookTargetArg, hookScopeArg, hookProjectArg, hookForce)
 
     if (hookJsonFlag) {
-      console.log(JSON.stringify({ installed, skipped, failed }, null, 2))
+      await emitJson({ installed, skipped, failed })
       process.exit(failed.length ? 1 : 0)
     } else {
       if (installed.length) console.error(chalk.green.bold(`✔ Hooks installed (${hookScopeArg}):`), installed.join(', '))
@@ -746,7 +889,7 @@ if (subcommand === 'hooks') {
     }
     const { removed } = await uninstallHook(nameToRemove, hookScopeArg, hookProjectArg)
     if (hookJsonFlag) {
-      console.log(JSON.stringify({ removed }, null, 2))
+      await emitJson({ removed })
     } else if (!removed) {
       console.log(chalk.dim(`  · ${nameToRemove} was not installed in ${hookScopeArg} scope`))
     }
@@ -798,9 +941,9 @@ if (subcommand === 'upgrade') {
   const nothingUpgraded = Object.keys(summary).length === 0
   if (jsonFlag) {
     if (nothingUpgraded) {
-      console.log(JSON.stringify({ skills: {}, upToDate: true }, null, 2))
+      await emitJson({ skills: {}, upToDate: true })
     } else {
-      console.log(JSON.stringify({ skills: summary }, null, 2))
+      await emitJson({ skills: summary })
     }
   } else {
     if (nothingUpgraded) {
@@ -1512,7 +1655,7 @@ try {
     const out = {}
     if (skillSummary !== null) out.skills = skillSummary
     if (toolSummary  !== null) out.tools  = toolSummary
-    console.log(JSON.stringify(out, null, 2))
+    await emitJson(out)
   } else {
     printSummary(skillSummary, toolSummary)
   }

package/lib/install-source.js

@@ -0,0 +1,46 @@
+import { execSync } from 'child_process'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import path from 'path'
+
+let cachedGlobalRoot = null
+
+export function globalRoot() {
+  if (process.env.HSKILL_GLOBAL_ROOT) return process.env.HSKILL_GLOBAL_ROOT
+  // stdio 'pipe' keeps npm's own stderr off ours: callers that tolerate failure
+  // (readSource) would otherwise leak "npm: command not found" into clean output.
+  if (!cachedGlobalRoot) cachedGlobalRoot = execSync('npm root -g', { encoding: 'utf8', stdio: 'pipe' }).trim()
+  return cachedGlobalRoot
+}
+
+function sourceFilePath() {
+  return path.join(globalRoot(), 'harveyz-skill', '.hskill-source.json')
+}
+
+// null means "npm source" — the default. An unreadable trace file and an
+// unreachable npm both collapse into it: `version` must keep working where npm
+// is off PATH, and a source we cannot read is not a source we can update from.
+export function readSource() {
+  let file
+  try {
+    file = sourceFilePath()
+  } catch {
+    return null
+  }
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function writeSource(info) {
+  writeFileSync(sourceFilePath(), JSON.stringify(info, null, 2) + '\n')
+}
+
+export function gitInfo(repo) {
+  const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: repo, encoding: 'utf8' }).trim()
+  const commit = execSync('git rev-parse --short HEAD', { cwd: repo, encoding: 'utf8' }).trim()
+  const dirty = execSync('git status --porcelain', { cwd: repo, encoding: 'utf8' }).trim().length > 0
+  return { branch, commit, dirty }
+}

package/lib/version-check.js

@@ -2,8 +2,8 @@ const DEFAULT_REGISTRY = 'https://registry.npmjs.org'
 const REGISTRY_TIMEOUT_MS = 5000
 
 export function compareVersions(a, b) {
-  const pa = a.split('.').map(Number)
-  const pb = b.split('.').map(Number)
+  const pa = a.split('+')[0].split('.').map(Number)
+  const pb = b.split('+')[0].split('.').map(Number)
   for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
     const diff = (pa[i] || 0) - (pb[i] || 0)
     if (diff !== 0) return diff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Skill manager for Claude Code, Cursor, Codex, OpenClaw, Hermes, OpenCode, and Pi",
   "type": "module",
   "bin": {
@@ -62,6 +62,12 @@
     "skills/coding/handoff/",
     "skills/feed/manage-creators/",
     "skills/feed/capture-opinion/",
+    "skills/agent-canvas/agent-canvas-control/",
+    "skills/agent-canvas/describe-node/",
+    "skills/agent-canvas/relate-node/",
+    "skills/agent-canvas/capture-requirement/",
+    "skills/agent-canvas/relation-review/",
+    "skills/agent-canvas/close-node/",
     "tools/hub/",
     "tools/sync-agent/",
     "tools/browser-fetch/",

package/skills/agent-canvas/agent-canvas-control/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: agent-canvas-control
+description: 在 Agent Canvas 的 claude-code/codex/pi 节点里操控节点实体与画布摆放（创建/查询/修改/删除节点、把节点放上或收起画布）；也可在 shell/hermes-tui 节点内或画布外的终端里用 `--canvas`/`resolve-canvas`/`resolve` 操控
+version: "1.0.0"
+---
+
+# 操控节点与画布（agent-canvas-control）
+
+如果 `agent-canvas-ctl`/`agent-canvas-arrange` 命令都不存在，这个 skill 不适用，直接跳过，
+不要尝试执行下面的命令。命令存在时可以直接尝试子命令——即使没有 `AGENT_CANVAS_MCP_URL`，
+两个二进制也会按当前工作目录反查所在画布；如果解析不到目标画布，子命令会以非零退出码报错，
+此时同样说明当前不适用，跳过即可，不要重试。
+
+两个二进制分工**互不重叠**：`agent-canvas-ctl` 管节点实体与关系（建/查/改/删/连接），
+`agent-canvas-arrange` 管画布摆放（放上/收起/移动/分组的成员与配色）——**建的节点默认不
+放上画布**，节点存在但游离于画布之外，是正常状态，不是遗漏；想让它出现在画布上，建完之后
+再调一次 `agent-canvas-arrange put`。两者所有子命令成功时把结果 JSON 打印到 stdout、退出码
+0；失败时把错误信息打印到 stderr、退出码非 0。
+
+## agent-canvas-ctl：节点实体与关系
+
+- `agent-canvas-ctl list-nodes`
+  列出当前画布所有节点，返回 `[{id, title, description, kind, state}, ...]`（不含画布摆放
+  字段——查节点在不在画布上、在哪个坐标，用下面 `agent-canvas-arrange list/get`）。
+
+- `agent-canvas-ctl get-node <nodeId>`
+  获取单个节点详情（同样不含摆放字段）。
+
+- `agent-canvas-ctl search-nodes <query> [--limit <n>]`
+  按标题/描述模糊搜索当前所有非归档节点（编辑距离容错，不要求精确匹配，标题命中权重高于描述），
+  按相关度降序返回 `[{id, title, description, kind, state, createdAt, score}, ...]`。
+  `score` 不是归一化到 0~1 的置信度（标题命中会乘 1.5 倍权重），只用于本次结果内部排序。
+  `--limit` 缺省时不截断结果数量。收起的节点（`agent-canvas-arrange hide`）仍会被搜到；
+  已归档节点不在范围内，要搜归档节点用 `search-archived-nodes`。
+
+- `agent-canvas-ctl create-node --kind <markdown|html|text|browser> --title <标题> --file <文件路径或URL> [--description <描述>]`
+  创建一个静态节点，**不放上画布**（不接受 `--position`）。`--file` 对 `markdown`/`html`/`text`
+  指向一个文件：`markdown` 在文件不存在时会创建空文件，`html`/`text` 要求文件已存在（否则
+  报错，不创建节点）；对 `browser` 传入初始 URL（不做存在性校验）。成功返回 `{nodeId}`；
+  要放上画布用 `agent-canvas-arrange put <nodeId> [--position x,y]`。
+
+- `agent-canvas-ctl create-pty-node --node-type <claude-code|shell|hermes-tui|codex> --title <标题> [--cwd <路径>] [--task-type <execute|evaluate|analyze|plan>]`
+  创建并启动一个 pty 节点，使用该节点类型的默认启动命令（不支持自定义 command）；**不放上
+  画布**（不接受 `--position`，进程照常启动，与是否在画布上无关）。`--cwd` 缺省时用当前
+  shell 的工作目录。`claude-code` 类型总是新建会话，不支持 resume。`--task-type` 可选，
+  设置节点的初始任务类型分类。不支持 `customNodeTypes`。成功返回 `{nodeId}`。
+
+- `agent-canvas-ctl create-requirement-node --title <标题> [--description <描述>] [--priority low|medium|high] [--status open|in_progress|done] [--acceptance-criteria <验收标准>] [--links <a,b,c>]`
+  创建一个需求节点，**不放上画布**。`--priority`/`--status` 缺省时分别为 `medium`/`open`。
+  成功返回 `{nodeId, requirementId}`——`requirementId` 是自动生成的需求编号（`YYMMDD-XX`
+  格式），和其余 `create-*` 子命令（只返回 `{nodeId}`）不同。
+
+- `agent-canvas-ctl derive-pty-from-requirement <nodeId> [--cwd <路径>] [--node-type <claude-code|shell|hermes-tui|codex>] [--task-type <execute|evaluate|analyze|plan>]`
+  从一个需求节点派生出一个 pty 会话节点并立即启动进程。需求节点**原样保留**，派生出的
+  会话节点自动连一条 `implements` 关系指向它；同一条需求可以派生多个会话（分析、执行、
+  评估各一个）。派生出的节点**不放上画布**。
+  `--node-type` 缺省 `claude-code`，`--cwd` 缺省用当前 shell 的工作目录。
+  成功返回 `{nodeId, requirementNodeId, relationId}`。
+
+- `agent-canvas-ctl update-node-title <nodeId> <新标题>`
+  修改节点标题。
+
+- `agent-canvas-ctl update-node-description <nodeId> <新描述>`
+  修改节点描述。
+
+- `agent-canvas-ctl update-node-task-type <nodeId> <execute|evaluate|analyze|plan|none>`
+  修改 pty 节点的任务类型分类，`none` 清空为未设置。仅对 pty 节点生效。
+
+- `agent-canvas-ctl update-node-requirement <nodeId> [--status open|in_progress|verifying|done] [--deferred true|false] [--priority low|medium|high] [--acceptance-criteria <验收标准>] [--links a,b,c]`
+  修改一个已存在的需求节点的 requirement 字段，patch 语义：只有显式传了的字段才写，没传的
+  原样不动。`--deferred` 与 `--status` 正交，不是 status 的取值之一。仅对需求节点生效。
+  成功返回 `{success: true, requirement: <patch 后的完整 requirement 对象>}`。
+
+- `agent-canvas-ctl archive-node <nodeId>`
+  归档节点（从检索空间移出+停进程，可恢复，不影响 relation）。
+
+- `agent-canvas-ctl stop-node <nodeId>`
+  停止指定 pty 节点的底层进程。不归档、不删除、不改变它在画布上的摆放。对非 pty 节点
+  或进程已停止的节点是 no-op，如实回报 `stopped:false`，不报错。
+  成功返回 `{success: true, stopped: boolean, reason?: string}`。
+
+- `agent-canvas-ctl purge-node <nodeId> --yes`
+  彻底删除节点（不可恢复，相关 relation 转 stale）；`--yes` 必填，否则直接拒绝执行、
+  不发起任何画布请求。若在画布节点内调用，可能阻塞最长约 90 秒等待人工在该节点卡片上
+  审批；被拒绝时报错 `用户拒绝了该操作`。
+
+- `agent-canvas-ctl list-archived-nodes`
+  列出当前所有已归档节点的摘要，返回 `[{id, title, description, kind, archivedAt}, ...]`。
+
+- `agent-canvas-ctl search-archived-nodes <query>`
+  按关键字搜索已归档节点（大小写不敏感，匹配 title/description 子串），返回结构同上。
+
+- `agent-canvas-ctl restore-node <nodeId>`
+  把一个已归档节点恢复回画布。
+
+- `agent-canvas-ctl list-relations`
+  列出当前画布所有关系（含 stale），返回 `[{id, type, from, to, status, label}, ...]`。
+
+- `agent-canvas-ctl link-nodes --from <nodeId> --to <nodeId> --type <t> [--label <文字>]`
+  在两节点间创建一条关系。`--type` 按两端节点 kind 的注册表校验（不合法组合报错并
+  列出该端点对的合法 type；`spawns` 是系统专属，总是被拒；`unspecified` 不能显式传）。
+  类型不是固定 7 个——注册表可演进，实际合法列表以 `agent-canvas-ctl relation-guide`
+  当前返回的为准。成功返回 `{relationId}`。
+
+- `agent-canvas-ctl link-nodes --from <nodeId> --to <nodeId> --reading "<自然语言谓语>" --why "<为什么现有 type 都装不下>" [--despite <t>,<t>] [--label <文字>]`
+  **逃逸阀**：矩阵里这对端点确实没有一个合适的 type 时用这个，不传 `--type`。
+  `--reading`/`--why` 成对必填，缺一即拒。若该端点对已有现成的合法 type，还必须传
+  `--despite`，逐个点名已经看过、确认装不下的现有 type，漏一个即拒——这是留给治理循环的
+  "已排除记录"，也是为了不让逃逸阀变成偷懒的默认选项。落盘后 `type` 记为 `unspecified`，
+  `reading`/`why` 单独存在关系上，将来治理循环可能把它升格成正式 type（不影响你现在
+  已经建的这条关系的 `relationId`）。
+
+- `agent-canvas-ctl unlink-relation <relationId>`
+  删除一条关系（relationId 由 list-relations 获取）。若在画布节点内调用，可能阻塞
+  最长约 90 秒等待人工在该节点卡片上审批；被拒绝时报错 `用户拒绝了该操作`。
+
+- `agent-canvas-ctl node-relations <nodeId> [--direction in|out|both] [--type <t>] [--depth <n>]`
+  返回该节点的关系，每条带对端摘要（`id`/`title`/`kind`）。`direction` 缺省 `both`；
+  `depth` 缺省 1、上限 3（超过会被夹到 3，不报错），带环检测（A→B→A 不会无限展开）。
+
+- `agent-canvas-ctl update-relation <relationId> [--type <t>] [--label <文字>]`
+  修改一条已有关系的 type/label（不支持改 status/display）。`--type`/`--label` 至少传一个；
+  改 type 时同样按矩阵校验。
+
+- `agent-canvas-ctl relation-guide [<nodeId>]`
+  返回关系矩阵、判据、阶段建议，以及当前节点的上下文（既有关系/血缘链/需求节点候选/
+  文档节点候选）。不传 `nodeId` 时按祖先进程链反查调用者自己所在的节点（同
+  `whoami`/`summarize-self`）。「什么时候该调、该建哪些关系」见 `relate-node` skill。
+
+- `agent-canvas-ctl create-group [--title <标题>] [--description <描述>]`
+  只建分组容器实体，**不放上画布、不加成员、不配色**。成功返回 `{nodeId}`；接下来用
+  `agent-canvas-arrange put` 摆上画布，再用 `group-add`/`group-color` 加成员/配色
+  （加成员要求分组已经在画布上，是正当前置条件，不是限制）。
+
+- `agent-canvas-ctl whoami`
+  反查当前进程所属的画布节点，返回 `{id, title, description, kind, state}`。
+  只在画布节点的进程树内可用。
+
+- `agent-canvas-ctl summarize-self [--spec <规格文档路径>]`
+  为你所在的这个节点生成标题、描述与任务类型并写回画布，不需要传 nodeId。
+  `--spec` 指定据以撰写的规格文档；不传时会从本会话记录里自动发现
+  （`docs/superpowers/specs/` 下你写过或读过的 .md）。
+  返回 `{nodeId, title, description, taskType?, specUsed}`；
+  `specUsed` 为 null 表示没找到规格文档，如有需要可用 `--spec` 补传。
+  不再撰写需求——需求撰写是独立的 `draft-requirement`（下一条）。该命令要跑一次模型
+  调用，通常 5–15 秒。
+
+- `agent-canvas-ctl draft-requirement [--spec <规格文档路径>]`
+  为你正在实现的某个需求节点撰写标题/描述/优先级/状态/验收标准，纯撰写不落盘。
+  `--spec` 指定据以撰写的规格文档；不传时会从本会话记录里自动发现
+  （`docs/superpowers/specs/` 下你写过或读过的 .md）。
+  该命令只应被 `capture-requirement` skill 的三步流水线调用，不独立暴露给用户。
+  节点已 implements 某个需求节点、或未读到 spec 时以非零退出码报错（需求编号不重铸）。
+
+- `agent-canvas-ctl notify <text> [--title <标题>]`
+  往通知中心发一条消息（不经过画布工具体系，不是画布操控）。落一条项目 scope 的通知，
+  能反查到调用节点时通知会关联到该节点。`--title` 缺省为 "PTY"。
+
+- `agent-canvas-ctl list-profiles`
+  列出当前可见的全部 Agent Profile（含全局与项目两个 scope，project 覆盖同 id 的 global）。
+
+- `agent-canvas-ctl create-profile --json <文件路径>`
+  创建一个新的 Agent Profile。`--json` 指向一个 JSON 文件，内容需包含 `name`/`scope`
+  （`project`|`global`）等字段；`id` 缺省时自动生成，传了已存在的 `id` 会报错。
+
+- `agent-canvas-ctl update-profile --json <文件路径>`
+  更新一个已存在的 Agent Profile。`--json` 指向一个 JSON 文件，内容需包含 `id`；
+  `runtime`/`workingDir` 不可修改——传了不同值会报错。
+
+- `agent-canvas-ctl resolve-canvas`
+  只做目标画布解析、不连 MCP server。见下方「目标画布解析」。
+
+## agent-canvas-arrange：画布摆放
+
+节点建完默认不在画布上——这不是缺可见性，节点列表照常能看到它、能从那里一键放上画布；
+这里是给 agent 用的等价操作。
+
+- `agent-canvas-arrange list [--on-canvas | --off-canvas | --hidden]`
+  列出全部节点的摆放态（含不在画布上的），返回
+  `[{id, title, kind, onCanvas, hidden, position?, width?, height?, containerId?, color?}, ...]`。
+  三个过滤参数互斥，缺省返回全集；`--on-canvas`/`--off-canvas` 按有没有落在画布上筛，
+  `--hidden` 单独筛"放过又收起"的节点。
+
+- `agent-canvas-arrange search <query> [--limit <n>]`
+  与 `agent-canvas-ctl search-nodes` 同一套模糊匹配，返回摆放形状（带 `score`）。
+  含收起的节点，不含已归档节点。**这是「自足」的关键**：只用这一个二进制就能从
+  "标题里带某个词的节点"走到"把它摆上画布"，不需要回 `agent-canvas-ctl` 拿 id。
+
+- `agent-canvas-arrange get <nodeId>`
+  单个节点的摆放态，形状与 `list` 里的一条一致。
+
+- `agent-canvas-arrange put <nodeId1,nodeId2,...> [--position <x,y>]`
+  把节点放上画布。不带 `--position` 时用自动布局位（可以是逗号分隔的多个 id 一次放上）；
+  带 `--position` 时精确定位到该坐标（只能对单个 id 生效）。已经在画布上的节点是 no-op。
+
+- `agent-canvas-arrange hide <nodeId1,nodeId2,...>`
+  将指定节点从画布隐藏：仅影响呈现层，不影响该节点参与检索、图搜索的能力，可随时通过
+  `put` 恢复显示。对没有放上画布过的节点是 no-op。
+
+- `agent-canvas-arrange move <nodeId> <x> <y>`
+  把已在画布上的节点移动到指定坐标（等价于 `put <nodeId> --position <x,y>`，位置参数写法
+  不同：这里 x/y 是独立参数，`put` 是 `--position x,y`）。
+
+- `agent-canvas-arrange group-add <groupId> <nodeId1,nodeId2,...>`
+  把节点加入分组。**分组必须已经在画布上**（先对 groupId 调过 `put`），否则响亮报错、
+  非零退出——不是静默失败。
+
+- `agent-canvas-arrange group-remove <groupId> <nodeId1,nodeId2,...>`
+  把节点移出分组。若分组是网格布局，被移除节点在 `memberCells` 里占的格子一并清掉。
+
+- `agent-canvas-arrange group-color <groupId> <颜色>`
+  修改分组容器的配色。颜色取值：`red`/`orange`/`yellow`/`green`/`teal`/`blue`/
+  `indigo`/`purple`/`pink`/`black`/`gray`/`white`。
+
+- `agent-canvas-arrange whoami`
+  与 `agent-canvas-ctl whoami` 是同一个查询，两边都有（寻址前置，不专属任何一域）。
+
+- `agent-canvas-arrange resolve`
+  与 `agent-canvas-ctl resolve-canvas` 是同一套本地解析，只是名字更短。见下方
+  「目标画布解析」。
+
+## 目标画布解析
+
+上面所有子命令默认按以下优先级自动定位画布，通常不需要关心这一节：
+`--canvas <路径>`（放在子命令之前）> 环境变量 `AGENT_CANVAS_MCP_URL`（画布内节点自带）>
+当前工作目录向上匹配注册表里画布的绑定路径。
+
+`agent-canvas-ctl resolve-canvas` / `agent-canvas-arrange resolve` 只做目标画布解析、
+不连 MCP server。解析到时把 `{url, source, boundPath?, pid?}` 打印到 stdout、退出码 0；
+解析不到时把可用画布清单打印到 stderr、退出码 1。适合在执行别的子命令前先探测
+「现在有没有画布可连」。
+
+## 已知限制
+
+不支持触发节点的"功能按钮"（restart/branch/stop 等），只有增删改查与摆放。

package/skills/agent-canvas/capture-requirement/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: capture-requirement
+description: 把当前会话正在实现的需求立项成一个独立的需求节点，并挂一条 implements 关系到自己身上——闸门2定稿后调用一次；仅在画布节点里可用
+version: "1.0.0"
+---
+
+# 需求立项（capture-requirement）
+
+如果当前不在 Agent Canvas 的画布节点里（即环境变量 `AGENT_CANVAS_MCP_URL` 未设置，
+或 `agent-canvas-ctl` 命令不存在），这个 skill 不适用，直接跳过，不要尝试执行下面的命令。
+
+## 怎么做（三步，每步一个既有/新增的单一能力命令）
+
+```
+1. agent-canvas-ctl draft-requirement [--spec <绝对路径>]
+   → { callerNodeId, title, description, priority, status, acceptanceCriteria?, specUsed }
+
+2. agent-canvas-ctl create-requirement-node \
+     --title <上一步的 title> --description <上一步的 description> \
+     --priority <上一步的 priority> --status <上一步的 status> \
+     [--acceptance-criteria <上一步的 acceptanceCriteria>]
+   → { nodeId, requirementId }
+
+3. agent-canvas-ctl link-nodes \
+     --from <第 1 步的 callerNodeId> --to <第 2 步的 nodeId> --type implements
+```
+
+第 1 步**只撰写、不落盘**——`--spec` 不传时按本会话记录自动发现，必须是绝对路径。
+第 1 步以非零退出码报错时，说明这三种情况之一：没读到 spec、本节点已 implements 过某个
+需求节点（不重铸编号）、或本节点上一次调用还没返回；报错本身已说明是哪一种，直接把错误
+如实报出，不要重试或跳过。
+
+## 孤儿处置
+
+**第 3 步失败时，立刻执行 `agent-canvas-ctl purge-node <第 2 步的 nodeId> --yes`**，收掉
+第 2 步建出来的需求节点，并把失败原因如实报出。不要留着第 2 步建出来的孤儿节点不处理。
+
+## 什么时候调
+
+**只在闸门 2 定稿后调一次**，不在收尾时调——需求正文在 spec 定稿那一刻最准确，收尾时会话
+上下文已被实现细节填满，重写只会把需求拧回实现叙述。与 `implements` 关系"一次写入不可
+覆盖"的语义一致：本节点已 implements 某个需求节点时，第 1 步会直接拒绝。
+
+handoff 场景：交出方在闸门 2 调（需求已立项）；接手方**不调**——需求节点已经在画布上，
+重复立项没有意义。注意第 1 步的前置检查只认**本节点自己**的 implements 边，接手方是一个
+全新节点、没有这条边，检查不会自动拦下重复调用；不调纯粹是约定，不是系统会替你挡住。
+
+## 边界
+
+不是 `describe-node` 的替代——`describe-node` 管本节点自己的 title/description/taskType，
+本 skill 管"另一个"需求节点的立项。两者常常紧挨着调，但各自独立，互不覆盖对方的产物。

package/skills/agent-canvas/close-node/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: close-node
+description: 一轮工作做完时给当前画布节点收尾——推进需求状态、核对 handoff 收口、合并分支、停进程并从画布收起；仅在画布节点里可用
+disable-model-invocation: true
+version: "1.0.0"
+---
+
+# 节点收尾（close-node）
+
+如果当前不在 Agent Canvas 的画布节点里（即环境变量 `AGENT_CANVAS_MCP_URL` 未设置，
+或 `agent-canvas-ctl` 命令不存在），这个 skill 不适用，直接跳过，不要尝试执行下面的命令。
+
+**人工触发**，不自动触发。触发时机：你这一轮工作已经做完、已经汇报过、确认不再有后续动作。
+
+## 步骤
+
+### 1. 认清自己
+
+```
+agent-canvas-ctl whoami                       → 自己的 nodeId
+agent-canvas-ctl node-relations <自己的 nodeId>  → implements 边 / hands-off-to 边
+```
+
+### 2. 判角色
+
+在 `docs/commute/` 下找 frontmatter 的 `source_node` 或 `target_node` 等于自己 nodeId
+的交接文档：
+
+| 角色 | 判据 |
+|---|---|
+| **独立节点** | 没有 `hands-off-to` 边，也没有一份交接文档点名自己 |
+| **交出方** | 自己的 nodeId == 某份交接文档的 `source_node` |
+| **接手方** | 自己的 nodeId == 某份交接文档的 `target_node` |
+
+"验收方"不是第四类——`/handoff` 的 accept 阶段由原 session 做，验收方就是交出方本人。
+
+### 3. 推进需求状态
+
+沿 `implements` 边找到需求节点。判断它现在该是什么状态，然后：
+
+```
+agent-canvas-ctl update-node-requirement <需求节点id> --status <verifying|done>
+```
+
+- 活干完了、还没人验 → `verifying`
+- 已经验收通过 → `done`
+- 这条需求要搁置（`deferred` 与 `status` 正交，不是它的取值）→ `--deferred true`
+- **拿不准就别改**，如实报告"需求状态维持 X，因为 Y"。改错了比不改更难发现。
+
+没有 `implements` 边 → 跳过这一步，不要顺手立项一个需求。
+
+### 4. handoff 收口
+
+**独立节点**：跳过，直接进第 5 步。
+
+**接手方**：
+- 核对交接文档 frontmatter 的 `status` 是否已置 `待验收`，没置就置上。
+- 核对 `hands-off-to` 边两端是否都齐、`target_node` 是否已回填自己的 nodeId。
+- **不合并、不 `git worktree remove`。** 要离开用 `ExitWorktree(action: "keep")`。
+
+**交出方**：
+- 核对交接文档 `status` 是否已到 `已验收`。
+- **没到 `已验收` 就停在这里报告，不要继续往下走。** 收尾不等于验收通过。
+- 到了 `已验收` 之后，再核对本分支是否已经合并进 staging
+  （`git merge-base --is-ancestor HEAD staging` 成功即已合并）。
+  **未合并就停在这里报告，不要进第 7 步。** 合并是 `/handoff` accept 阶段由你自己跑
+  `scripts/merge-to-staging.sh` 的动作，本 skill 不代跑；把没合并的分支连同节点一起
+  关掉，等于把工作弄丢了。
+
+> **只有交出方能合并、能 `git worktree remove`。** 这是硬约束，不是建议。
+
+### 5. 合并（仅独立节点）
+
+先确认 `scripts/merge-to-staging.sh` 存在、且当前仓库确实采用本 skill 描述的这套流程。
+不存在就说明本仓库不适用这一步，**停下报告，不要自行换用别的合并手法**。
+
+```
+git rev-parse --abbrev-ref HEAD          # 先核对自己站在哪条分支上
+cd "$(git rev-parse --show-toplevel)"    # cwd 未必在仓库根，先切过去
+scripts/merge-to-staging.sh
+git worktree remove <本工作区>
+```
+
+脚本会拒绝在 staging/main 上执行，但它拦不住"你以为在工作区里、其实在主工作树上"。
+
+若 `git worktree remove` 提示有未提交改动，**停下报告，不要加 `--force`**。
+
+**合并失败就停在这里报告，不要进第 7 步。** 把没合并的分支连同节点一起关掉，等于把工作弄丢了。
+
+### 6. 汇报
+
+把上面每一步做了什么、跳过了什么、为什么，一次说完。
+
+> **第 7 步一执行就没有输出了。所有要给人看的东西必须在这里说完。**
+
+### 7. 关闭自己
+
+先自查：有没有 subagent 还在后台跑？有就等它们完成，不要现在关。
+
+```
+agent-canvas-arrange hide <自己的 nodeId>
+agent-canvas-ctl stop-node <自己的 nodeId>
+```
+
+**顺序不能反。** `stop-node` 一执行进程就没了，排在它后面的命令发不出去。
+
+这一步之后没有任何输出是**预期行为**，不是故障。
+
+## 边界
+
+- **不代跑 `describe-node`、`relate-node`。** 那两个的第二次调用仍按 CLAUDE.md 由你自己
+  在收尾前调，本 skill 与它们**并列**，不是它们的编排器。调本 skill 之前先把它们调完。
+- **不调 `capture-requirement`。** 需求立项只在闸门 2 发生一次，收尾不重复立项。
+- 不动 `implements` 边——只改需求节点自己的 `status`/`deferred`。
+- `stop-node` 不走 UI 那套阻断策略（busy / 有活跃 subagent / 绑着 worktree）。
+  那三条是防人手滑的护栏，你显式调用是有意图的动作。**代价是这个工具很锋利**——
+  第 7 步的自查是唯一的缓解，机制不会替你挡。

package/skills/agent-canvas/describe-node/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: describe-node
+description: 为 Agent Canvas 中你所在的这个画布节点自动生成标题与描述——总结/摘要当前会话在做什么、给节点起名、更新节点标题或描述时使用；仅在画布节点里可用
+version: "1.0.0"
+---
+
+# 为当前节点生成标题与描述（describe-node）
+
+如果当前不在 Agent Canvas 的画布节点里（即环境变量 `AGENT_CANVAS_MCP_URL` 未设置，
+或 `agent-canvas-ctl` 命令不存在），这个 skill 不适用，直接跳过，不要尝试执行下面的命令。
+
+## 怎么调
+
+```
+agent-canvas-ctl summarize-self [--spec <规格文档路径>]
+```
+
+**不需要传节点 id**——它按祖先进程链反查你所在的节点，"谁调用就摘要谁"。
+
+- `--spec` 指定据以撰写的规格文档。不传时会从本会话记录里自动发现你写过或读过的
+  `docs/superpowers/specs/*.md`；返回值里的 `specUsed` 为 null 就表示没找到，
+  如果你知道该用哪份，用 `--spec` 补传一次会明显更准。
+- 成功时 stdout 返回 `{nodeId, title, description, taskType?, specUsed}`，退出码 0；
+  失败时错误写 stderr、退出码非 0。
+- 要跑一次模型调用，通常 5–15 秒，属正常。
+
+## 什么时候值得调
+
+- **节点标题还是默认的类型名**（`Claude Code` / `Pi Agent` / `Shell`）时——这时画布上
+  同类节点长得一模一样，无法区分，最该起名。
+- 刚写完或刚确定一份 spec 之后。
+- 一个阶段性任务完成、会话主题已经明确之后。
+- 用户明确要求"给这个节点起个名 / 写个描述 / 总结一下这个节点在做什么"。
+
+## 什么时候不要调
+
+- 会话刚开始、还没有任何实质内容时——没东西可摘，只会得到空泛的标题。
+- 用户手动改过标题、而这一轮并没有要求重新生成时——**本命令会覆盖标题**。
+- 同一节点上一次调用还没返回时——会直接报"正在进行中"，等它完成即可。
+
+## 边界
+
+本命令**只产出 title/description/taskType**，不再撰写需求。若材料能清楚判断任务类型
+（执行/评估/分析/计划），也会一并写入并覆盖已有值——taskType 不做"仅未设置时写"的保护，
+即使是人工在面板下拉框里手动设置的值也会被覆盖。
+
+需要把当前会话在实现的需求立项成一个节点，用 `capture-requirement` skill，不是本命令。

package/skills/agent-canvas/relate-node/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: relate-node
+description: 在 Agent Canvas 里为当前节点梳理与其他节点的语义关系（依赖/交接/实现需求/产出或引用文档）——闸门2定稿后、收尾汇报前，判断要不要给已有节点连一条关系时使用；仅在画布节点里可用
+version: "1.0.0"
+---
+
+# 梳理节点关系（relate-node）
+
+如果当前不在 Agent Canvas 的画布节点里（即环境变量 `AGENT_CANVAS_MCP_URL` 未设置，
+或 `agent-canvas-ctl` 命令不存在），这个 skill 不适用，直接跳过，不要尝试执行下面的命令。
+
+## 怎么做
+
+1. 调 `agent-canvas-ctl relation-guide`（不需要传 nodeId，按祖先进程链反查自己），
+   拿到 `{ matrix, criterion, phase, context }`：
+   - `matrix`：`(fromKind, toKind)` 端点对允许的 type 全集，每项带 `reading`（怎么读，
+     type 名是谓语、from 是主语、to 是宾语）与 `agentAllowed`（false 的项——目前只有
+     `spawns`——是系统专属，不要尝试建）。
+   - `criterion`：判据原文，「不记它，将来某个具体动作会做错或做不了；写不出消费点就不记」。
+   - `phase.start` / `phase.finish`：当前所处阶段该核对哪些 type（见下方「两次调用」）。
+   - `context.node`：自己这个节点的 id/title/kind/cwd。
+   - `context.existingRelations`：自己已有的关系（含对端摘要）——**先看这个，避免重复主张**。
+   - `context.lineage`：spawns/hands-off-to 血缘链。
+   - `context.requirementNodes`：画布上的需求节点候选。
+   - `context.candidateDocs`：同 cwd 下的 markdown/html/text 节点候选。
+2. **按 `phase` 对应的 type 列表逐个比对**（不是自由联想）：对每个候选 type，问「`context`
+   里有没有一个具体的候选对象（需求节点/文档节点/血缘链上的节点），配得上这个 type 的读法」。
+   配不上就跳过，不要为了凑数硬建。
+3. 对通过判据的每一条，调 `agent-canvas-ctl link-nodes --from <id> --to <id> --type <t> [--label <s>]`。
+   传矩阵外的组合会报错并回传该端点对的合法 type 列表。**如果连报错列出的合法 type 都没有
+   一个装得下**（不是"选一个将就"，是确实没有语义相符的），改用
+   `agent-canvas-ctl link-nodes --from <id> --to <id> --reading "<谓语读法>" --why "<原因>" [--despite <已排除的type>,...]`
+   逃逸阀记下来，不要放弃这条主张也不要硬套一个不准确的现有 type。
+4. 简短报告建了哪些关系、跳过了哪些候选及原因。
+
+## 两次调用（对齐 describe-node 的两个时机，可紧挨着调）
+
+- **第一次（闸门 2 定稿后、建分支前）**：核对 `phase.start` 列出的 type——
+  `implements`（需求此刻最显眼，收尾时早被压缩出上下文）、`depends-on`（已知的阻塞）、
+  `hands-off-to`（**只核对，不在这里新建**——接手方要补走 `/handoff` verify，见下方归属规则）。
+- **第二次（收尾、汇报验收前）**：核对 `phase.finish` 列出的 type——
+  `produces`/`references`（文档要等到这时才成立）、`depends-on`（补漏）、
+  `hands-off-to`（这次要交出去、且已经能指认接手节点时才新建）。
+
+## hands-off-to 的归属
+
+**谁先能同时指认两端谁建**，另一方只核对、不重复主张（两边都建会出重复关系）：
+
+- 交出方在 `/handoff` author 阶段**已经能指认接手节点**（比如接手用的节点是它亲手创建的）
+  → 当场建，并在交接文档里注明已建。
+- 指认不到接手节点（常态：接手方是还不存在的下一个 session）→ 交出方只把自己的节点 id 写进
+  交接文档 frontmatter 的 `source_node`，由**接手方在 `/handoff` verify 阶段**读到它之后
+  建、并把自己的 id 回填 `target_node`。
+- 建之前先看 `context.existingRelations` / `node-relations`，已有就跳过。
+
+接手方补的只有这一条边：**不建 `implements`、不调 `capture-requirement`**——需求挂在交接源
+节点上，接手节点该不该关联需求是另一个问题。
+
+## 什么时候不要调
+
+- 会话刚开始、还没有任何候选对象（需求/文档/上游节点）时。
+- `context.existingRelations` 里已经有语义相同的关系时——不要重复主张。
+- 矩阵里没有对应格子的端点对（比如两个 group 节点之间）——这是显式的空格子，不是遗漏。

package/skills/agent-canvas/relation-review/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: relation-review
+description: 全局 Pilot 专用的 relation 类型治理循环——扫描待议区、按四道关卡审议是否升格新
+  type；由 cron 定时调起，不应在项目画布节点里手动调用
+version: "1.0.0"
+---
+
+# Relation 类型治理循环（relation-review）
+
+如果当前不是全局 Pilot 身份（`agent-canvas-ctl` 命令不存在，或明显运行在某个项目画布节点
+的上下文里），这个 skill 不适用，直接跳过。
+
+## 第一步：数待议区，决定要不要唤起完整审议
+
+调 `agent-canvas-ctl relation-review-queue`，拿到全部画布里
+`type='unspecified' && provenance='agent' && reading != null` 的关系列表，每条带
+`{relationId, cwd, fromNodeId, toNodeId, fromKind, toKind, reading, why, createdAt}`。
+
+**`WAKE_N = 5`**：本次列表长度**相比上次记录的基线**新增条目数 < 5 时，只记下这次的数量
+（可以简单回复"待议区当前 N 条，未达唤起阈值，不审议"），**不要往下做任何关卡判断**——
+空转成本压到这一次计数（spec §5.1）。达到阈值才继续。
+
+## 第二步：按语义聚类
+
+把待议区列表按"读法在说同一件事"聚类（不是按 `reading` 字面量分组——不同措辞可能是
+同一个模式）。每一簇是一个候选 type 提案。
+
+## 第三步：对每个候选簇过四道关卡
+
+**审议时不要看任何"这条提案本来该不该过"的暗示**——你只应该看到 `relation-review-queue`
+返回的原始数据，不要预设结论。每道关卡的产出必须引用真实 `relationId`，不能虚构案例；
+写不满结构化字段就是没过这道关，不能用"综合考虑认为合理"糊过去。
+
+### 关卡一 · 谓语关
+
+判据：**把 `to` 端换成另一种 kind 的节点，这个 type 还成立吗？** 成立才是谓语，不成立
+说明它描述的是宾语的种类（比如"这份文档是设计稿"这种，该由文档节点子类型承载，不是
+新 relation type——这条岔路必须堵死，见 spec §1.3）。
+
+打回时必须**明说是关卡一**，否则同一提案会反复被提上来。
+
+### 关卡二 · 聚类关（用例门槛）
+
+判据：同一语义在待议区累计 **≥ `PROMOTE_N`（3）条**，且 **来自 ≥2 个不同节点**
+（`fromNodeId` 不同，不是同一个节点连记了好几遍——那是一个案例复述多遍，不是一个模式）。
+
+不满足就打回，附上当前累计数量和涉及的节点数，方便下次审议时快速核对是否已经攒够。
+
+### 关卡三 · 可辨别性关
+
+判据：对该端点对上现有的**每一个** type（用 `agent-canvas-ctl relation-guide` 查该端点对
+当前合法的 type 列表），举出一个真实 `relationId`，说明在那条具体的关系上，新 type 与
+这个现有 type 会给出不同答案。写进最终提案的 `distinguishedFrom` 字段。
+
+**有一个现有 type 举不出区分案例，就不是新 type，是那个已有 type 的实例**——打回，
+并建议把这批关系改用 `agent-canvas-ctl update-relation <relationId> --type <已有type>`
+归到它名下（不要自己批量执行，写进审议报告让下一步的人工事后核查时看到）。
+
+每条候选自带的 `why` 字段（agent 走 `link-nodes` 逃逸阀建这条关系时就已经写明"为什么
+现有 type 装不下"）是关卡三最直接的原料，优先核对这些——**不是 `despite`**：`despite`
+只在写入那一刻用于校验"逐个点名已排除的现有 type"，校验完就丢弃，不落在 Relation 记录上、
+`relation-review-queue` 也不会把它吐出来，审议阶段读不到。
+
+### 关卡四 · 消费关（软）
+
+判据：写出至少一个"谁会读它"——一句具体的提问（例如"这个需求被哪个取代了"），
+允许答案是"agent 通过 `get_node_relations`/`relation-guide` 读回"（现有 7 个 type 里
+已有 4 个只有这个消费点，不是更高标准）。一句都写不出就打回。
+
+## 第四步：对通过全部四关的提案执行升格
+
+```
+agent-canvas-ctl relation-promote \
+  --name <新type名> \
+  --reading "<谓语读法>" \
+  --endpoints "<fromKind>:<toKind>,<fromKind>:<toKind>" \
+  --evidence "<cwd>::<relationId>,<cwd>::<relationId>,..." \
+  --gate-reasoning "<四道关卡论证全文，含每一关的判断依据>"
+```
+
+`--endpoints` 里的 `<fromKind>`/`<toKind>` 是节点 **kind**（比如 `pty`/
+`requirement`），不是节点 id——跟 `--evidence` 里的 `relationId` 是两种不同的标识符，
+不要混用。`--evidence` 列出的应该是这一簇里全部符合条件的 `relationId`（不止 3 条门槛
+数量，攒了多少条证据就列多少条——升格后这些关系的 `type` 会被原样改写成新 type 名）。
+
+对没通过的提案，**不调用任何写操作**，只在报告里说明打回在哪一关、原因是什么。
+
+## 第四步之后：审议中顺带发现的其他治理动作
+
+四道关卡只回答"这个候选该不该升格成新 type"。审议过程中如果顺带发现**已经是正式 type**
+的词条有下面三类问题，同一轮一并处理（不需要单独等下一轮）——这三个动作**不改任何存量
+relation 数据**，只改注册表条目的 `status`/`supersededBy`（spec §5.4）：
+
+- **发现两个现存 type 其实是同一件事**（例如关卡三的可辨别性检查显示不出真实差异）：
+  `agent-canvas-ctl relation-merge --from <旧type> --into <目标type> --gate-reasoning "<为什么判定等价>" [--evidence <relationId>,...]`
+  `from` 会被标记为 `deprecated`、`supersededBy` 指向 `into`；`into` 必须是当前存在的 type，
+  不存在会被拒绝。
+- **发现一个现存 type 已经没有意义**（比如从未被真实使用、或语义已被更好的 type 完全覆盖）：
+  `agent-canvas-ctl relation-deprecate --name <type> --gate-reasoning "<为什么判定过时>" [--evidence <relationId>,...]`
+  有代码消费点（`codePinned`，如 `spawns`/`implements`/`unspecified`）的 type 会被硬拒绝，
+  不要尝试废弃它们。
+- **发现一个现存 type 的名字本身有误导性**：
+  `agent-canvas-ctl relation-rename --from <旧名字> --to <新名字> --gate-reasoning "<为什么需要改名>" [--evidence <relationId>,...]`
+  等价于"新建 `to` + 合并 `from`→`to`"，`to` 必须已经存在（先用 `relation-promote`
+  建出新名字，再用这个命令把旧名字标记废弃）。
+
+这三个动作不是每轮都会用到——待议区常年空转、四道关卡常年不通过是预期状态（spec §9.1），
+这三个动作同样可能常年不触发。**不要为了"这次总得做点什么"而勉强套用它们**。
+
+## 第五步：简短报告
+
+列出：本轮待议区总数、本次新增数（是否达到唤起阈值）、审议的候选簇数、每簇的关卡结论
+（通过/打回及原因）、执行了哪些升格（附 changelogId）、顺带执行了哪些废弃/合并/改名
+（附 changelogId，没有就说明本轮没有）。
+
+## 什么时候不要往下走
+
+- 待议区新增 < `WAKE_N`：只报数量，不审议（见第一步）。
+- 候选簇 < `PROMOTE_N` 或 < 2 个不同节点：打回在关卡二，不进关卡三。
+- `agent-canvas-ctl` 命令不存在，或明显不是全局身份：整个 skill 不适用，跳过。

package/skills-index.json

@@ -35,7 +35,8 @@
     "writing": "写作工具（forge-doc + draw-diagram + manage-dir + migrate-spec）",
     "design": "设计工具（scout-brand + build-style + sync-design）",
     "mint": "Skill 生命周期工具（init-skill + publish-skill + archive-skill + dedup-skill + contribute-skill + fix-skill + runby-opencode + scout-philosophy + learn-skill）",
-    "devops": "项目运维工具（clean-git + release-project + sync-hotfix + sync-agent）"
+    "devops": "项目运维工具（clean-git + release-project + sync-hotfix + sync-agent）",
+    "agent-canvas": "Agent Canvas 内置 skill（agent-canvas-control — 节点与画布操控；describe-node/relate-node/capture-requirement/relation-review/close-node — 画布节点生命周期治理）"
   },
   "skills": [
     {
@@ -344,6 +345,30 @@
       "installScope": "project",
       "contentHash": "27a9cb1a55b0036a",
       "contentVersion": "0.2.0"
+    },
+    {
+      "path": "agent-canvas/agent-canvas-control",
+      "bundle": "agent-canvas"
+    },
+    {
+      "path": "agent-canvas/describe-node",
+      "bundle": "agent-canvas"
+    },
+    {
+      "path": "agent-canvas/relate-node",
+      "bundle": "agent-canvas"
+    },
+    {
+      "path": "agent-canvas/capture-requirement",
+      "bundle": "agent-canvas"
+    },
+    {
+      "path": "agent-canvas/relation-review",
+      "bundle": "agent-canvas"
+    },
+    {
+      "path": "agent-canvas/close-node",
+      "bundle": "agent-canvas"
     }
   ],
   "hooks": [