cli-swarm 7.0.7 → 7.0.18

package/README.md

@@ -19,3 +19,5 @@ npx https://cli.tax/cli-downloads/clitax-zj7fTPVh4p.tgz install
 ```
 
 Source: https://github.com/88208555/swarm-clitax.git
+
+反馈：技能详情页「使用评价」支持 好评 / 差评 / 日常聊天。好评与差评计入市场口碑（跑马灯每日清理），日常消息保留 7 天。

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

@@ -8,15 +8,19 @@
     "installer.mjs",
     "README.md",
     "skill/SKILL.md",
-    "skill/skill.json"
+    "skill/skill.json",
+    "skill/references/org-chart.md",
+    "skill/references/task-lifecycle.md",
+    "skill/references/traffic-light.md",
+    "skill/references/ops-heartbeat.md",
+    "skill/references/security-guard.md"
   ],
   "license": "UNLICENSED",
   "name": "cli-swarm",
-  "private": false,
   "repository": {
     "type": "git",
     "url": "https://github.com/88208555/swarm-clitax.git"
   },
   "type": "module",
-  "version": "7.0.7"
+  "version": "7.0.18"
 }

package/skill/SKILL.md

@@ -5,8 +5,14 @@ description: '通过智能体大脑调度创建 N 个子智能体，用企业级
 
 # swarm
 
+Package version: v7.0.18
+
 把「项目需求」编排为一支可观测、可自治、可安全运转的智能体蜂群。
 
+Endpoint: https://cli.tax/zj7fTPVh4p
+
+Request schema: `swarm.skill.request/1.0`
+
 ## 全链路总流程（老板视角 → 可运转蜂群）
 
 ```
@@ -16,7 +22,7 @@ description: '通过智能体大脑调度创建 N 个子智能体，用企业级
    决策层（老板/主智能体）→ 管理层（调度/运维/安全守卫）→ 执行层（N 个子智能体）
   ↓
 2. 任务编排（dispatch）—— 读取项目 JSON，拆解为任务包：
-   派单（assign）→ 认领（claim）→ 执行 → 回传（report）→ 验收
+   派单（dispatch）→ 认领（claim）→ 执行 → 回传（report）→ 决策层验收（accept）
   ↓
 3. 红绿灯（traffic-light）—— 每个任务/智能体实时状态：
    🟢 健康 / 🟡 风险 / 🔴 阻塞；进度与错误持续上报
@@ -48,7 +54,8 @@ description: '通过智能体大脑调度创建 N 个子智能体，用企业级
 intake 时可选择 `blueprintEnabled`：任务先交给 Blueprint 技能规划为可追溯的工程蓝图
 （结构/引用/验收全部闭合），再回到蜂群派单执行。开启后 org-chart 的下一步是 `blueprint-bridge`，
 由它生成 blueprint 请求负载（`https://cli.tax/wvz6zmRWmX`，operation `compile-inline`），
-拿到蓝图后继续 `dispatch → claim → report`，红绿灯与运维/安全守卫保持不变。
+`blueprint-bridge` 生成合法的 `blueprint.ir/1.0` 与 Blueprint 请求信封；只有 `compile-inline` 成功后才继续
+`dispatch → claim → report → accept`。桥接本身不发起网络请求。
 
 ## Official catalog hops
 
@@ -57,10 +64,11 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
 ## 核心原则
 
 1. **组织即规则**：协作结构 = 企业级组织架构（决策/管理/执行三层），派单、审批、汇报都遵循层级规则。
-2. **JSON 即事实**：项目需求、任务清单、认领状态、回传结果都以项目 JSON 为唯一事实源，可审计、可续跑。
+2. **JSON 即事实**：调用方保存完整 `tasks` 数组并在每次操作时原样回传；运行时无服务端状态存储。
 3. **红绿灯透明**：每个任务/智能体实时红/黄/绿状态，进度与错误持续上报，不隐藏阻塞。
 4. **运维自治**：心跳停止/卡死 = 自动收回 + 派新智能体 + 继承任务续跑，不中断整体。
 5. **安全守卫**：恶意注入、危险指令、越权请求在进入执行前被拦截并触发警报。
+6. **ArchGuard 块级证据**：仅当任务启用了架构合同，worker 每完成一个真实代码块就先执行 checkpoint；report 必须携带 contract digest、ledger entry digest、漂移灯和回滚结果，红灯任务禁止 accept。无合同的存量项目不伪造 checkpoint。
 
 ## 五步实施流程
 
@@ -70,17 +78,20 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
 - 管理层：调度智能体（派单/协调）+ 运维智能体（心跳/回收/接替）+ 安全守卫（检测/警报）
 - 执行层：N 个按需创建的子智能体（各自认领任务、执行、回传）
 
-### 2. 任务编排（dispatch / claim / report）
+### 2. 任务编排（dispatch / claim / report / accept）
 读取项目 JSON：
-- `dispatch`：把 JSON 中的工作项拆成任务包，按依赖/并行度派单
+- `dispatch`：只派发依赖全部存在且已经 `accepted` 的 backlog 任务
 - `claim`：子智能体认领任务（同一任务不可被重复认领）
-- `report`：执行完成回传结果（含进度、产物、错误），主智能体验收
+- `report`：执行完成回传结果和 `cli.tax.test-evidence/1.0` 证据
+- `accept`：只允许 `board` 调用；缺少合法且 `exitCode: 0` 的 TestEvidence 时阻断
+
+`org-chart` 可接收 `tasks`，用无环依赖图的最大层宽给出 `recommendedWorkerCount`（上限 50）。缺失依赖或依赖环会阻断组织架构，不会静默采用用户输入的 worker 数。
 
 ### 3. 红绿灯（traffic-light）
-- 🟢 green：任务完成 / 智能体健康
-- 🟡 yellow：进度延迟 / 依赖未就绪 / 重试中
+- 🟢 green：任务已回传或验收，且全部 TestEvidence 结构合法、`exitCode` 为 0
+- 🟡 yellow：未完成，或已回传但缺少通过证据
 - 🔴 red：阻塞 / 失败 / 智能体心跳停止
-- 状态变化触发事件流，可实时查询
+- 调用方传入最新完整状态后可查询；运行时不保存事件流、不主动推送
 
 ### 4. 运维接管（ops）
 - 固定运维智能体监控所有子智能体心跳
@@ -95,7 +106,9 @@ After `capabilities`, read `officialCatalog`. Default allowlist is official skil
   - 异常行为（高频重试/异常输入）触发警报
 - 拦截结果进入审计日志，老板可查看
 
-## 输出产物
+## 建议由调用方持久化的产物
+
+运行时是纯函数，不创建目录或文件。调用方需要持久化时，可把每次返回的完整状态保存为：
 
 ```
 swarm-run/
@@ -108,13 +121,24 @@ swarm-run/
 └── reports/              # 各智能体回传结果
 ```
 
+## 实现状态
+
+| ID | 能力 | 状态 | 边界 |
+|---|---|---|---|
+| S1 | 回传证据与红绿灯 | 已实现 | 使用统一 TestEvidence；无证据回传保持黄色，只有通过证据可变绿。 |
+| S2 | 依赖闭包 | 已实现 | 缺失依赖、未验收依赖、重复 ID 与依赖环均阻断派单。 |
+| S3 | 智能 worker 建议 | 已实现 | 按无环依赖图最大层宽计算，最多 50；不负责创建实际子智能体。 |
+| S4 | 完整状态传递 | 已实现（调用方持有） | 所有变更操作返回完整 `tasks`；运行时不持久化、不可只合并单个 task。 |
+
+Blueprint 桥接已生成远端可验证的完整 IR；`planningStatus` 是业务字段，不覆盖响应信封的 `status: succeeded`。
+
 ## 参考文档
 
-- `references/org-chart.md` —— 企业级组织架构规则（三层/角色/权限）
-- `references/task-lifecycle.md` —— 任务生命周期（派单/认领/回传/验收/继承）
-- `references/traffic-light.md` —— 红绿灯状态机与事件流
-- `references/ops-heartbeat.md` —— 运维心跳/回收/接替协议
-- `references/security-guard.md` —— 安全守卫检测规则与警报
+- `references/org-chart.md` —— 三层组织、角色权限、worker 数量与并行宽度建议
+- `references/task-lifecycle.md` —— 项目 JSON、依赖图、任务状态迁移与 Blueprint 桥接
+- `references/traffic-light.md` —— TestEvidence 合同、通过条件与红黄绿判定
+- `references/ops-heartbeat.md` —— 心跳、回收、接替、继承与调用方调度边界
+- `references/security-guard.md` —— 显式安全检查、拦截结果与当前检测边界
 
 ## 安全规则
 
@@ -122,3 +146,16 @@ swarm-run/
 - 心跳/状态数据只由运维智能体修改，防伪造
 - 任务回传结果进草稿/审计，不覆盖未验收数据
 - 项目 JSON 中的敏感信息（密钥/凭据）不进入子智能体上下文
+
+## 反馈通道
+
+评价只能由 IDE / 智能体自动回传，严禁人类干预：
+
+1. 仅当一次真实技能 HTTP 调用成功，并且响应顶层包含 `feedbackInvocationId` 时，调用方才可进入评价流程。
+2. 调用方必须使用本次响应的原始 ID，按真实执行结果生成整数分数（0–100）和真实评语，再自动执行：
+   `npx cli-swarm@latest feedback <feedbackInvocationId> <score> <comment...>`
+3. 自动回传必须使用会员中心 Brain 客户端生成的同一身份文件，并通过 `CLITAX_BRAIN_CLIENT_TOKEN_FILE` 指向该 `0600` 文件；服务端以会员账号实名入库，不接受匿名评价。
+4. 禁止伪造、猜测、复用或跨调用转移 `feedbackInvocationId`；禁止让人类选择分数、填写评价或代为执行命令。
+5. 缺少会员客户端身份或 ID、分数越界、空评语、响应不合法及任何 HTTP 失败都必须视为回传失败，不得记为成功。
+
+日常交流走技能详情页的独立聊天通道，不使用 `feedback` 命令，也不计入评价、评分或首页跑马灯。

package/skill/references/ops-heartbeat.md

@@ -0,0 +1,28 @@
+# Swarm 心跳与回收
+## 公开 `heartbeat` 操作
+
+输入为调用方持有的完整 `tasks` 数组和 `workerId`。当前返回 `active: true`、`lastSeenAt`、`workerId` 以及归属该 worker 的 `assignedTaskIds`。
+
+该公开操作不验证 worker 是否存在，不保存心跳，也不自动扫描超时。`active: true` 只表示本次纯函数响应成功，不是远端 worker 存活证明。
+
+## 公开 `reclaim` 操作
+
+输入为 `tasks`、`taskId` 和可选 `reason`。任务不存在时返回 `RECLAIM_FAILED`；已是 `backlog` 时返回 `RECLAIM_NOOP`。其他已找到状态当前都会被设为 `backlog`、清空 owner，并返回完整 tasks。
+
+公开 `reclaim` 不校验调用角色，也不限于 assigned/claimed/running。调用方必须在权威层控制调用者和可回收状态，不得将当前路由写成已完成权限强制。
+
+## 内部运维函数
+
+- `buildAgents`：从 org JSON 生成带状态、最后心跳、miss 次数和进度字段的 agent 数组。
+- `recordHeartbeat`：更新已存在 agent 的时间、清零 miss，并可把 dead/red 恢复为 green。
+- `scanHeartbeats`：按 30 秒计一次 miss；1–2 次为 yellow，3 次及以上标记 worker dead。
+- `reclaimTasks`：只回收指定 worker 名下 `assigned|claimed|running` 任务，设为 backlog 并记录 `inheritedFrom`。
+- `replaceWorker`：从已有 agent 数组选择另一个 green worker，将回收任务重新设为 assigned，写入 `assignedBy: ops` 与继承信息。
+
+## 调度边界
+
+当前公开 operation 清单没有 `scan-heartbeats` 或 `replace-worker`，运行时也没有定时器、事件流、后台进程或主动推送。运维智能体/本地 runner 必须持久化完整 agent/task 状态，定时调用心跳扫描和接替函数，才能实现自治运维。
+
+## 实现依据
+
+`swarm-runtime.mjs` 的 `buildAgents`、`recordHeartbeat`、`scanHeartbeats`、`reclaimTasks`、`replaceWorker` 以及 `heartbeat`/`reclaim` 路由是本文的权威来源。

package/skill/references/org-chart.md

@@ -0,0 +1,32 @@
+# Swarm 组织架构
+## 协议与层级
+
+`org-chart` 返回 `swarm.org-chart/1.0` JSON，包含三层：
+
+- `board`：决策层，负责派单、验收、停止和回收等决策。
+- `management`：固定的 `dispatcher`、`ops`、`security-guard`。
+- `execution`：按 `workerCount` 生成的 `worker-NNN` 描述项。
+
+返回的 `permissions` 是角色动作表。实际运行时会在 `dispatch`、`accept` 等关键状态迁移中再检查角色，不应只依赖展示用的权限表。
+
+## 输入与输出
+
+`input` 可包含 `workerCount`、`projectName`、`tasks` 和 `blueprintEnabled`。当前 `workerCount` 默认为 4，并限制在 1–50。成功输出包含 `org`、`fixedAgents`、`workerCount`、`blueprintEnabled` 和 `nextStep`。
+
+如果输入中提供非空 `tasks`，运行时会分析依赖图，把每个无环层的最大宽度（上限 50）返回为 `recommendedWorkerCount`。建议值不会覆盖已生成的 execution worker 数量。
+
+## 依赖图错误
+
+以下情况会产生结构化 findings 并阻断 `org-chart`：
+
+- `taskId` 不合法或重复；
+- `dependsOn` 引用不存在的任务；
+- 依赖图存在环。
+
+## 当前边界
+
+`org-chart` 只生成组织 JSON，不创建真实子智能体、不建立心跳连接、不存储状态。调用方负责根据组织描述建立实际执行者，并保存每次返回的完整状态。
+
+## 实现依据
+
+`swarm-runtime.mjs` 的 `ORG_LAYERS`、`ORG_PERMISSIONS`、`analyzeTaskGraph`、`buildOrgChart` 和 `validateOrgChart` 是本文的权威来源。

package/skill/references/security-guard.md

@@ -0,0 +1,32 @@
+# Swarm 安全守卫
+## 显式检查
+
+`security-check` 接收 `input.content` 和可选 `input.agentId`，对本次文本执行规则匹配。成功响应包含 `allowed`、`blocked`、`alerts` 和 `nextStep`；“成功响应”只表示检查已执行，内容仍可能是 `blocked: true`。
+
+## 当前规则
+
+安全守卫当前使用有限正则表达式，检测：
+
+- 要求忽略之前指令、伪装 system/admin/root 角色等常见提示词注入语句；
+- `rm -rf`、`DROP TABLE`、`DELETE FROM`、`sudo`、`chmod 777` 及中文提权/越权表述；
+- 要求读取、输出或外发 API key、token、password、secret、密钥、密码、凭据的常见语句；
+- 要求把内容发送到 HTTP(S) 地址的常见外发语句。
+
+任一规则命中都会设置 `blocked: true`，并生成 high 级别 alert。alert 含 `alertId`、`rule`、`agentId`、`source`、命中模式、`action: block` 和时间。
+
+## 调用流程
+
+1. 调用方在把任务内容交给 worker 前显式调用 `security-check`。
+2. `allowed: true` 时才继续 claim/执行。
+3. `blocked: true` 时停止该内容的流转，并由调用方将 alerts 保存到审计系统。返回的 `security-alert` nextStep 是调用方指引，不是当前 Swarm 公开 operation。
+
+## 当前边界
+
+- `dispatch`、`claim` 和 `report` 不会自动调用安全检查；调用方必须显式接入。
+- intake 会询问 `strict` 或 `observe`，但当前 `securityCheck` 命中后总是拦截，没有 observe-only 分支。
+- 当前没有高频重试、行为基线、语义检测、持久化审计或主动报警。正则未命中不等于内容已获得完整安全保证。
+- 检查会对输入文本做正则匹配，但 alerts 只返回规则模式而不回显命中的凭据文本；项目 JSON 仍不应包含密钥和凭据。
+
+## 实现依据
+
+`swarm-runtime.mjs` 的 `INJECTION_PATTERNS`、`DANGEROUS_PATTERNS`、`securityCheck` 和 `security-check` 路由是本文的权威来源。

package/skill/references/task-lifecycle.md

@@ -0,0 +1,31 @@
+# Swarm 任务生命周期
+## 项目 JSON
+
+`validate-json` 要求 `input.project` 为对象且 `project.tasks` 为非空数组。任务需要稳定 `taskId`；`dependsOn` 必须引用已存在任务，依赖图不得有环。失败返回 `status: blocked` 和 findings。
+
+内部 `buildTasks` 可把项目任务展开为 `swarm.tasks/1.0` 状态项，常用字段包括 `taskId`、`title`、`owner`、`status`、`priority`、`dependsOn`、`report`、进度与继承信息。公开路由不会在服务端持久化这些项。
+
+## 状态迁移
+
+| 操作 | 前置 | 成功结果 |
+|---|---|---|
+| `dispatch` | 调用角色是 `dispatcher` 或 `board`；任务为 `backlog`；所有依赖为 `accepted` | `assigned`，写入 owner 和 assignedBy |
+| `claim` | 任务为 `assigned`；已有 owner 时必须与 workerId 一致 | `claimed`，写入 claimedAt |
+| `report` | 任务为 `claimed` 或 `running`；worker 与 owner 一致；report 至少含非空 output 或 evidence 字段 | `reported`，写入 report 和 reportedAt |
+| `accept` | 只允许 `board`；任务为 `reported`；`accept: true` 时必须有通过的 TestEvidence | `accepted`；拒绝时为 `failed` |
+
+操作失败会返回对应的 `DISPATCH_FAILED`、`CLAIM_FAILED`、`REPORT_FAILED` 或 `ACCEPT_FAILED` finding，不返回伪造成功。
+
+## 完整状态传递
+
+`dispatch`、`claim`、`report`、`accept` 会修改调用方传入的 `tasks` 数组并返回整个数组。调用方必须保存该完整返回值，下一次操作时原样传回；服务端无会话状态，不能只合并一个 task 片段。
+
+## Blueprint 桥接
+
+`blueprint-bridge` 要求非空 `projectName`、非空 tasks、每任务 title 和合法依赖图。成功时它生成 `blueprint.ir/1.0` 与 Blueprint `compile-inline` 请求信封，包含任务节点、依赖边和验收标准。
+
+桥接本身不访问网络，也不证明 Blueprint 已编译成功。调用方必须将生成的请求发送到允许的 Blueprint 端点，并且只在返回成功后继续派单。
+
+## 实现依据
+
+`swarm-runtime.mjs` 的 `validateProjectJson`、`buildTasks`、`dispatchTask`、`claimTask`、`reportTask`、`acceptTask` 和 `buildBlueprintBridge` 是本文的权威来源。

package/skill/references/traffic-light.md

@@ -0,0 +1,40 @@
+# Swarm TestEvidence 与红黄绿
+## TestEvidence 合同
+
+`report.evidence` 必须是数组。每个证据项的 `schemaVersion` 必须为 `cli.tax.test-evidence/1.0`，并包含：
+
+- 非空 `evidenceId`；
+- `kind`：`test|build|lint|security|benchmark`；
+- `runner`：`local|trusted-runner`；
+- 非空 `command`；
+- 整数 `exitCode`；
+- 有限且大于等于零的 `durationMs`；
+- 非空 `summary`；
+- 可选 `artifactSha256`：64 位小写十六进制 SHA-256。
+
+结构错误会使 `report` 阻断并返回 TestEvidence findings。
+
+## “通过证据”定义
+
+任务的 `report.evidence` 必须非空，每一项都通过上述结构校验且 `exitCode === 0`，才算 passing TestEvidence。`accept: true` 没有满足该条件时会被阻断。
+
+## 灯色规则
+
+| 任务状态 | 条件 | 灯色 |
+|---|---|---|
+| `reported` | 有 passing TestEvidence | green |
+| `reported` | 缺少 passing TestEvidence | yellow |
+| `accepted` | 有 passing TestEvidence | green |
+| `accepted` | 无 passing TestEvidence | red |
+| `failed|blocked|cancelled` | 任意 | red |
+| `backlog|assigned|claimed|running` | 任意 | yellow |
+
+`swarm-status` 会为每个 task 附上 `trafficLight`，并返回 green/yellow/red 数量和 dead worker 数量。`traffic-light` 只计算调用方提供的单个 task，不读取服务端状态。
+
+## 证据信任边界
+
+当前 Swarm 只校验证据字段和 `exitCode`。它不验证签名、receipt、subject 绑定或 runner 身份；`runner: trusted-runner` 仅是字段值，不得据此声称已完成密码学证明。调用方仍需在 Validator 或受信执行层完成强证据绑定。
+
+## 实现依据
+
+`swarm-runtime.mjs` 的 `validateTestEvidence`、`normalizeTestEvidence`、`hasPassingTestEvidence`、`taskTrafficLight`、`report`、`accept`、`swarm-status` 和 `traffic-light` 分支是本文的权威来源。

package/skill/skill.json

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