@wwkit/harness 1.0.9 → 1.0.11

package/commands/resume.md

@@ -0,0 +1,104 @@
+---
+description: 基于导出的历史会话文件（ses_*.json/txt 等）确认任务状态并继续对话；路径支持 @workdir 简写
+---
+
+你是**会话续接助手**。用户因 TUI 崩溃/异常退出了历史会话，只能把会话导出成文件（JSON 或文本）并在新对话中继续。你的任务是：确认旧任务的**最终状态**（只读文件**结尾**），输出精炼简报，然后接着旧任务继续对话。
+
+## 铁律（违反即失败）
+
+1. **绝不读取会话文件全文**。导出文件可能极大（几十万~上百万行），整读会耗尽上下文甚至卡死会话。只允许**自底向上**读取：从**末尾**开始，向上扩展，**一旦识别到有效任务状态信息立即停止**，不再多读。
+2. **绝不把文件原始内容成段倒入上下文**。所有内容必须先提炼成 ≤几行的结论再输出。
+3. 文件可能不是 JSON（.txt、.log 或其他文本格式），按 Step 2 的格式判定处理，不要假定格式。
+4. **有效任务状态信息**（命中即停的信号）定义为：`status=done|partial|failed|blocked|escalate`、`## 结果摘要`、JSON 消息的 `finish` 字段（`stop`/`error`/`tool-calls` 等）、或明显的总结性结论句（含 完成/成功/失败/阻塞/错误/退出 等关键字）。
+
+## Step 1：解析路径参数
+
+输入为 `$ARGUMENTS`：**1..n 个路径**（空格分隔，可能是多个历史文件）。若为空，自动在 workdir 下找最新的 `ses_*` 文件（`ls -t ses_*` 取第一个），找不到则报告后停止。
+
+对每个路径按下表解析（**支持 @ 开头**——这是 opencode 对 workdir 的简写，参数可能已被 opencode 解析成绝对路径，也可能原样传入）：
+
+| 形式 | 处理 |
+|------|------|
+| `@foo.json`（@ 开头） | 去掉 `@`，视为相对 **workdir**（工程根目录 root_dir）→ `<root_dir>/foo.json` |
+| `/abs/path` 或 `~/...` | 原样使用（先展开 `~`） |
+| `rel/path`（相对） | 先相对当前 workdir 解析；不存在则相对 root_dir 再试 |
+
+校验存在性用 `ls -la <path>`；不存在时用 glob 找相近文件（如 `**/ses_*.json`、`**/ses_*`）并告知用户候选。**所有路径均无效** → 报告并停止。
+
+## Step 2：只读结尾（核心，每个文件）
+
+**统一原则：自底向上 + 命中即停。** 从文件**末尾**开始读取，向上扩展；一旦识别到"有效任务状态信息"（见铁律 4）**立即停止**，不再向上扩展。避免固定行数导致的漏读/多读。
+
+### 2a. JSON 会话文件（扩展名 .json，或内容以 `{` 开头）
+
+用 node 解析，**自底向上收集，命中即停**（内存解析整文件没问题，关键是控制打印量）：
+
+```bash
+node -e '
+const fs = require("fs");
+const p = process.argv[1];
+let d;
+try { d = JSON.parse(fs.readFileSync(p, "utf8")); }
+catch (e) { console.log("NOT_JSON"); process.exit(0); }
+const i = d.info || {};
+const msgs = Array.isArray(d.messages) ? d.messages : [];
+const text = (m) => (m.parts || []).filter(x => x.type === "text").map(x => x.text).join("\n");
+const lastTool = (m) => { const t = (m.parts || []).filter(x => x.type === "tool"); const g = t.pop(); return g ? { tool: g.tool, status: (g.state || {}).status } : null; };
+const HIT = /status=(done|partial|failed|blocked|escalate)|## 结果摘要|(完成|成功|失败|阻塞|错误|退出)/;
+// 从底部向上遍历，命中有效状态即停；兜底最多 3 条
+const collected = [];
+let hit = false, stop = false;
+for (let k = msgs.length - 1; k >= 0 && collected.length < 3 && !stop; k--) {
+  const m = msgs[k];
+  const t = text(m);
+  const finish = (m.info || {}).finish;
+  collected.unshift({ role: (m.info || {}).role, finish, lastTool: lastTool(m), textTail: t.slice(-1500) });
+  if (finish === "stop" || finish === "error" || finish === "tool-calls" || HIT.test(t)) { hit = true; stop = true; }
+}
+const out = {
+  title: i.title || null, agent: i.agent || null,
+  model: (i.model || {}).id || null, fileSummary: i.summary || null,
+  updated: i.time && i.time.updated ? new Date(i.time.updated).toISOString() : null,
+  msgCount: msgs.length,
+  readMode: hit ? "命中有效状态，停止" : "兜底：已达最大收集数(3)",
+  tail: collected
+};
+console.log(JSON.stringify(out, null, 2));
+' "$path"
+```
+
+> 行为：从最后一条消息**向上**逐条收集，遇到第一条 `finish=stop/error/tool-calls` 或文本含状态摘要/结论关键字的 assistant 消息即停（正常结束只读 1 条 `stop`；崩溃点即最后一条 `finish=tool-calls`，命中后停并报告"中断在执行中"；最后是 user 待回复会向前多读 1 条到上次 `stop`）。兜底上限 3 条、每条文本尾部 1500 字符。**不要**用 read 工具读这个文件，**不要**打印 `msgs` 数组。
+
+### 2b. 其他文本文件（.txt/.log 等）
+
+**自底向上阶梯式读取，命中即停**：
+
+1. 先 `wc -l <path>` 看总行数；总行数 ≤ 300 可直接整读（小文件安全）。
+2. 否则从尾部开始，按阶梯向上扩展（100 → 300 → 700 → 1500 → **上限 3000 行**）：
+   - 第 1 步：`tail -n 100 "$path"`，检查是否命中"有效状态信息"；
+   - 未命中：`tail -n 300`、`tail -n 700`、`tail -n 1500` 逐级扩大窗口再检查；
+   - **命中立即停止**，不再扩展。
+3. 命中判定同铁律 4（`status=`/`## 结果摘要`/完成/成功/失败/阻塞/错误/退出 等关键字，或末尾本身就是总结性结论句）。
+4. 到达上限 3000 行仍未命中：停止，报告"未在尾部 3000 行内找到明确状态，建议人工查看中段"。
+
+## Step 3：判定任务状态（对每个文件）
+
+依据 2a/2b 拿到的**尾部信息**判定，并给出结论：
+
+| 观测 | 判定 |
+|------|------|
+| 最后一条是 assistant 且 `finish: "stop"` | 会话**正常结束**；再查其文本是否含结果摘要（`## 结果摘要` / `status=done|partial|failed|blocked|escalate`），有则直接采用 |
+| 最后一条是 assistant 且 `finish: "tool-calls"` | 会话**中断在执行中**（很可能就是崩溃点）：最后一步是某工具调用（见 `lastTool`），任务未完成 |
+| 最后一条是 user | 上次停在**等待 agent 回复**，任务未完成 |
+| 文本文件 | 从尾部提取退出/状态关键字（如 完成/成功/失败/阻塞/错误/status=…），结合最后输出的结论句判断 |
+| 无任何可读内容 / 格式无法识别 | 报告 `无法解析`，跳过该文件继续处理其余文件 |
+
+对每个文件产出 ≤5 行的状态卡片：`文件路径 | 标题 | 消息数 | 最终状态 | 最后消息要点 | 未完成事项`。
+
+## Step 4：输出续聊简报并继续
+
+1. **简报**：先汇总所有文件的状态卡片（多文件时逐个列出，再综合）。总输出保持精炼。
+2. **续接方案**：基于状态给出下一步——
+   - 任务未完成且最后步骤明确 → 列出"从哪继续"的具体续接计划（参照最后工具调用/最后文本）。
+   - 任务已完成 → 简述结论与变更，提示如需继续新需求可直接提出。
+3. **征询后继续**：用一句话向用户确认续接方向（例如"按上述计划从 X 继续？"），**不要**未经确认就擅自执行重活（大规模改动/长流程）。用户确认后即按原任务上下文继续推进（沿用原任务的目标与验收标准）。

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@wwkit/harness",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "author": "bluesliu <langcai163@163.com>",
   "description": "WebWork abilities for opencode",
   "type": "module",
   "main": "plugin.js",
   "files": [
     "plugin.js",
+    "plugins",
+    "scripts",
     "skills",
     "agents",
     "commands",
@@ -38,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.18.27",
+    "@opencode-ai/plugin": "1.18.30",
     "ajv": "^8.17.0",
     "cheerio": "^1.0.0",
     "json5": "^2.2.3"

package/plugins/work-bootstrap.js

@@ -0,0 +1,77 @@
+import { randomUUID } from 'crypto'
+
+const BOOTSTRAP_MARKER = '__wwkit_work_bootstrap__'
+
+const BOOTSTRAP_TEXT = `[${BOOTSTRAP_MARKER}]
+
+你是 work（任务调度指挥官）。以下强约束优先级高于你的其他指令，必须遵守：
+
+## Red Flags（禁止行为）
+
+1. **禁止亲自逐行实现**：你的职责是拆解→派发→汇总，不是写代码。除非是单步 trivial 任务（≤1 文件、≤5 行），否则必须派发 subagent。
+2. **禁止先动手后规划**：多步骤任务必须先 todowrite 落单，再派发。
+3. **禁止上下文倾倒**：subagent prompt 必须自包含精炼上下文，不要把整个对话历史贴进去。
+4. **禁止串行派发**：独立任务必须在一条消息里并行发出多个 task 调用（≤5）。
+5. **禁止无限重试**：单个 worker failed/blocked 只记录不中断；全部失败才重规划；重规划 ≤3 轮。
+
+## 强制优先级
+
+- 能 single 绝不 parallel（先路由判断）。
+- 但如果任务涉及 ≥2 个独立子问题或 ≥3 个文件，必须 parallel。
+- subagent 类型：只读调研用 explore，可写改动用 general。
+- 每轮派发前必须确认 writable 白名单不重叠（文件所有权分区）。`
+
+export const WorkBootstrapPlugin = async () => {
+  return {
+    'experimental.chat.messages.transform': async (input, output) => {
+      const messages = output.messages
+      if (!Array.isArray(messages) || messages.length === 0) return
+
+      const users = messages.filter((m) => m?.info?.role === 'user')
+      const lastUser = users[users.length - 1]
+      if (!lastUser) return
+
+      const agent = lastUser.info?.agent
+      if (agent !== 'work') return
+
+      const alreadyInjected = messages.some((m) => {
+        const parts = m?.parts
+        if (!Array.isArray(parts)) return false
+        return parts.some(
+          (p) => p?.type === 'text' && typeof p.text === 'string' && p.text.includes(BOOTSTRAP_MARKER)
+        )
+      })
+      if (alreadyInjected) return
+
+      const sessionId = lastUser.info?.sessionID || lastUser.info?.id || ''
+      const messageId = lastUser.info?.id || ''
+
+      const bootstrapPart = {
+        id: `prt_${randomUUID()}`,
+        sessionID: sessionId,
+        messageID: messageId,
+        type: 'text',
+        text: BOOTSTRAP_TEXT,
+        synthetic: true,
+        time: { start: Date.now() }
+      }
+
+      messages.unshift({
+        info: {
+          id: `msg_${randomUUID()}`,
+          sessionID: sessionId,
+          role: 'assistant',
+          time: { created: Date.now() },
+          parentID: '',
+          modelID: '',
+          providerID: '',
+          mode: 'primary',
+          path: { cwd: '', root: '' },
+          cost: 0,
+          tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } }
+        },
+        parts: [bootstrapPart]
+      })
+    }
+  }
+}

package/scripts/work-review-package

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Generate a review package: commit list, stat summary, and the net
+# diff with extended context, written to a file the reviewer reads in one
+# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
+# tasks intact.
+#
+# Usage: work-review-package WORKSPACE_DIR TASK_NUMBER BASE HEAD [SUFFIX]
+#   Writes to: <WORKSPACE_DIR>/task-<N>-review-<base7>..<head7>.diff
+#   If SUFFIX is "final", writes to: <WORKSPACE_DIR>/final-review-<base7>..<head7>.diff
+set -euo pipefail
+
+if [ $# -lt 4 ] || [ $# -gt 5 ]; then
+  echo "usage: work-review-package WORKSPACE_DIR TASK_NUMBER BASE HEAD [SUFFIX]" >&2
+  exit 2
+fi
+
+ws="$1"
+n="$2"
+base="$3"
+head="$4"
+suffix="${5:-}"
+[ -d "$ws" ] || { echo "no such workspace directory: $ws" >&2; exit 2; }
+
+git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
+git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
+
+base7=$(git rev-parse --short "$base")
+head7=$(git rev-parse --short "$head")
+
+if [ "$suffix" = "final" ]; then
+  out="$ws/final-review-${base7}..${head7}.diff"
+else
+  out="$ws/task-${n}-review-${base7}..${head7}.diff"
+fi
+
+{
+  echo "# Review package: ${base}..${head}"
+  echo
+  echo "## Commits"
+  git log --oneline "${base}..${head}"
+  echo
+  echo "## Files changed"
+  git diff --stat "${base}..${head}"
+  echo
+  echo "## Diff"
+  git diff -U10 "${base}..${head}"
+} > "$out"
+
+commits=$(git rev-list --count "${base}..${head}")
+echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"

package/scripts/work-task-brief

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Write a task brief file from stdin, so the implementer reads its task
+# text in one call instead of receiving it through the controller's context.
+#
+# Usage: work-task-brief WORKSPACE_DIR TASK_NUMBER
+#   Reads task text from stdin, writes to <WORKSPACE_DIR>/task-<N>-brief.md
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+  echo "usage: work-task-brief WORKSPACE_DIR TASK_NUMBER" >&2
+  echo "  Reads task text from stdin." >&2
+  exit 2
+fi
+
+ws="$1"
+n="$2"
+[ -d "$ws" ] || { echo "no such workspace directory: $ws" >&2; exit 2; }
+
+out="$ws/task-${n}-brief.md"
+cat > "$out"
+
+if [ ! -s "$out" ]; then
+  echo "task brief is empty (stdin had no content)" >&2
+  exit 3
+fi
+
+echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"

package/scripts/work-workspace

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Resolve and ensure the working-tree directory for one work session's
+# short-lived artifacts: plan, task briefs, implementer reports, review
+# packages, and the progress ledger.
+#
+# Directory: <root_dir>/webwork/harness/work/<session-id>/
+# One directory per session so concurrent sessions never collide.
+#
+# Usage: work-workspace ROOT_DIR [SESSION_ID]
+# Prints the session directory's absolute path.
+set -euo pipefail
+
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  echo "usage: work-workspace ROOT_DIR [SESSION_ID]" >&2
+  exit 2
+fi
+
+root="$1"
+[ -d "$root" ] || { echo "no such directory: $root" >&2; exit 2; }
+
+if [ $# -eq 2 ]; then
+  sid="$2"
+else
+  sid="$(date +%s)"
+fi
+
+base="$root/webwork/harness/work"
+dir="$base/$sid"
+mkdir -p "$dir"
+printf '*\n' > "$base/.gitignore"
+cd "$dir" && pwd

package/skills/better-skill/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: better-skill
+description: |
+  基于 blame-skill 审计评分，自动迭代优化 Skill 定义文件直到达到优秀等级。
+  提供：迭代优化流程、自动改进策略、评分达标验证。
+  适用：新建 Skill 后自动优化、已有 Skill 质量提升、批量 Skill 质量治理。
+  不适用：非 SKILL.md 文件优化、Agent 定义优化、无需评分的简单修改。
+license: MIT
+---
+
+# Skill 自动优化器
+
+## 工作流模式
+
+本 Skill 采用 **迭代优化** 工作流：
+
+1. **评估**：调用 blame-skill 对目标 Skill 进行审计评分
+2. **判断**：检查分数是否 >= 90（A 级）或已达最大迭代次数
+3. **改进**：根据审计报告的改进建议，修改目标 SKILL.md
+4. **重评**：再次调用 blame-skill 重新评估
+5. **循环**：重复步骤 2-4 直到达标或累计迭代 5 次
+
+## 输入要求
+
+用户必须提供要优化的 **skill 名称**（如 `git-feat`、`clean-code`）。
+
+## 迭代流程
+
+### 第 1 步：初始评估
+
+调用 blame-skill 对目标 Skill 进行审计评分，使用 `--format=json` 结构化模式获取结果：
+
+- 读取 blame-skill 的评分规则
+- 按路径顺序查找目标 SKILL.md
+- 逐项评分并生成结构化审计报告
+
+### 第 2 步：达标判断
+
+从审计结果中提取 `total_score`：
+
+| 条件 | 动作 |
+|------|------|
+| `total_score >= 90` | 输出最终报告，流程结束 |
+| `total_score < 90` 且迭代次数 < 5 | 进入第 3 步改进 |
+| `total_score < 90` 且迭代次数 >= 5 | 输出最终报告（含未达标说明），流程结束 |
+
+### 第 3 步：改进 Skill
+
+根据审计报告中的 `issues` 和 `improvement_priority`，对目标 SKILL.md 进行修改：
+
+1. 按 `improvement_priority` 顺序逐项处理
+2. 对每个 issue，将 `suggestion` 转化为具体的文件修改操作
+3. 修改时遵循以下原则：
+   - **Frontmatter**：补充/修正 name、description 字段，确保 description 在 50-300 字符且包含具体能力、适用场景、不适用场景、提供资源
+   - **工作流声明**：在正文开头添加明确的工作流模式声明
+   - **失败处理**：补充失败处理机制（回滚、重试、降级、人工介入）
+   - **正文结构**：使用标题、列表、表格等结构化格式，补充代码示例和边界说明
+   - **渐进式加载**：当内容超过 200 行时，将详细数据拆分到 references/ 目录
+   - **Name 规范**：如 name 不符合 `^[a-z0-9]+(-[a-z0-9]+)*$` 格式，提示用户确认是否重命名
+
+### 第 4 步：重新评估
+
+修改完成后，再次调用 blame-skill 进行审计评分，回到第 2 步。
+
+## 迭代控制
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 目标分数 | 90 | A 级（优秀） |
+| 最大迭代次数 | 5 | 防止无限循环 |
+| 迭代计数起点 | 1 | 首次评估计为第 1 次 |
+
+## 输出格式
+
+迭代结束后，输出最终报告：
+
+```
+## Skill 优化报告：[skill-name]
+
+### 最终得分：XX / 100（等级：X）
+### 迭代次数：X / 5
+
+### 各轮得分变化
+
+| 轮次 | 得分 | 等级 | 主要改进项 |
+|------|------|------|-----------|
+| 1 | XX | X | 初始评估 |
+| 2 | XX | X | [改进项1], [改进项2] |
+| ... | ... | ... | ... |
+
+### 改进摘要
+
+- [改进项1]：[修改前] → [修改后]
+- [改进项2]：[修改前] → [修改后]
+
+### 未解决项（如有）
+
+- [ ] **[项目名]**：[原因说明]
+```
+
+## 一定要做
+
+1. 每次迭代前必须调用 blame-skill 获取最新评分
+2. 按改进优先级从高到低处理 issue
+3. 修改 SKILL.md 后立即重新评估
+4. 记录每轮迭代的得分变化
+5. 迭代结束时输出完整的优化报告
+
+## 一定不要做
+
+1. 不要跳过 blame-skill 评估直接修改
+2. 不要在一次迭代中修改后不重新评估就继续修改
+3. 不要修改 blame-skill 的评分规则
+4. 不要在未达到 90 分时提前终止（除非已达 5 次上限）
+5. 不要修改目标 Skill 的核心功能语义（只优化结构，不改意图）
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 目标 Skill 不存在 | 提示用户检查名称，终止流程 |
+| blame-skill 评估失败 | 终止流程，输出已完成的迭代结果 |
+| 5 次迭代仍未达标 | 输出当前最高分和未解决项，建议人工介入 |
+| 修改导致分数下降 | 回滚本次修改，跳过该项，继续下一优先级 |

package/skills/blame-skill/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: blame-skill
+description: |
+  审计和评分 OpenCode Skill 定义文件（SKILL.md），基于工作流模式和最佳实践规则进行量化评估。
+  提供：评分规则（满分100分）、工作流匹配分析、改进建议生成。
+  适用：审查已有 Skill 质量、改进 Skill 定义、新建 Skill 前参考评分标准。
+  不适用：审查 Agent 定义、审查 Command 定义、通用代码审查。
+---
+
+# Skill 审计评分器
+
+## 工作流模式
+
+本 Skill 采用 **迭代优化** 工作流：
+1. **读取**：加载目标 SKILL.md 及 references/ 目录
+2. **评分**：按评分规则逐项打分
+3. **诊断**：列出未满足项及改进建议
+4. **输出**：生成结构化审计报告
+
+## 评分规则（满分 100 分）
+
+### 一、工作流匹配（20 分）
+
+Skill 是否符合某种明确的工作流模式，是评分的第一标准。
+
+| 项目 | 分值 | 评分标准 |
+|------|------|---------|
+| 工作流识别 | 8 分 | 能明确识别属于以下模式之一：顺序工作流、多 MCP 协调、迭代优化、上下文感知、领域智能。无法识别得 0 分 |
+| 工作流完整性 | 5 分 | 工作流步骤完整，有清晰的阶段划分或步骤编号。步骤模糊或不完整扣 3-5 分 |
+| 指令可执行 | 3 分 | 每个步骤的指令具体、可操作，非泛泛而谈。模糊指令扣 2-3 分 |
+| 失败处理 | 4 分 | 包含失败处理机制（回滚、重试、降级、人工介入）。无任何失败处理扣 4 分 |
+
+### 二、Description 质量（20 分）
+
+Description 是唯一决定 Skill 是否被触发的因素。
+
+| 项目 | 分值 | 评分标准 |
+|------|------|---------|
+| 具体能力 | 5 分 | 一句话说明核心能力，模糊不得分 |
+| 适用场景 | 5 分 | 明确列出触发场景，缺失扣 5 分 |
+| 不适用场景 | 5 分 | 明确列出边界限制，缺失扣 5 分 |
+| 提供资源 | 5 分 | 说明 Skill 包含的资源（表结构、公式、模板等），缺失扣 5 分 |
+
+### 三、Name 规范（10 分）
+
+| 项目 | 分值 | 评分标准 |
+|------|------|---------|
+| 命名规范 | 5 分 | 符合 `^[a-z0-9]+(-[a-z0-9]+)*$` 格式。不符合得 0 分 |
+| 语义清晰 | 5 分 | 名称反映核心功能，无法从名称推断用途扣 3-5 分 |
+
+### 四、正文质量（25 分）
+
+| 项目 | 分值 | 评分标准 |
+|------|------|---------|
+| Markdown 结构 | 5 分 | 使用标题、列表、表格等结构化格式。纯文本无结构扣 5 分 |
+| 具体示例 | 5 分 | 包含代码块或使用示例。无示例扣 5 分 |
+| 边界说明 | 5 分 | 明确说明不能做什么或限制条件。缺失扣 5 分 |
+| 输入输出规范 | 5 分 | 明确定义 Skill 的输入要求和输出格式。若 Skill 无需输入输出（如纯执行类），自动得 5 分；需要但缺失扣 5 分，定义不完整扣 2-3 分 |
+| 渐进式加载 | 5 分 | 主文件精简，详细数据放 references/。主文件过长（>200 行）且无 references 扣 5 分 |
+
+### 五、Frontmatter 规范（15 分）
+
+| 项目 | 分值 | 评分标准 |
+|------|------|---------|
+| name 字段 | 3 分 | 存在且与目录名一致。缺失或不一致扣 3 分 |
+| description 字段 | 5 分 | 存在且 1-1024 字符。缺失扣 5 分 |
+| description 长度 | 4 分 | 描述充分但不冗长（建议 50-300 字符）。过短（<30 字符）扣 2 分，过长（>500 字符）扣 2 分 |
+| 可选字段 | 3 分 | 合理使用 license / compatibility / metadata 等可选字段。无可选字段不扣分，有则检查合理性 |
+
+### 六、目录结构（10 分）
+
+| 项目 | 分值 | 评分标准 |
+|------|------|---------|
+| SKILL.md 存在 | 5 分 | 文件名必须为 SKILL.md（大写）。不存在得 0 分 |
+| references/ 使用 | 5 分 | 当内容较多时使用 references/ 目录存放详细文档。内容多但未拆分扣 5 分，内容少不需要则不扣分 |
+
+## 评分等级
+
+| 分数 | 等级 | 说明 |
+|------|------|------|
+| 90-100 | A 优秀 | 完全符合最佳实践 |
+| 75-89 | B 良好 | 基本符合，有少量改进空间 |
+| 60-74 | C 合格 | 可用但需要改进 |
+| 40-59 | D 不足 | 存在明显问题 |
+| <40 | E 较差 | 需要重写 |
+
+## 输入要求
+
+用户必须提供要审计的 **skill 名称**（如 `git-feat`、`clean-code`）。
+
+## Skill 加载路径
+
+按以下顺序查找目标 Skill 的 SKILL.md 文件，找到即停止：
+
+1. **项目级**：`.opencode/skills/<name>/SKILL.md`（从当前目录向上遍历至 git worktree）
+2. **OPENCODE_CONFIG_DIR**：`$OPENCODE_CONFIG_DIR/skills/<name>/SKILL.md`
+3. **全局**：`~/.config/opencode/skills/<name>/SKILL.md`
+
+如果目录下存在 `references/` 子目录，也一并读取用于评估渐进式加载。
+
+## 审计流程
+
+### 步骤 1：定位并读取目标 Skill
+
+根据用户提供的 skill 名称，按上述路径顺序查找 SKILL.md。未找到则提示用户检查名称或路径。
+
+### 步骤 2：逐项评分
+
+按上述六大类评分规则，逐项评估并记录得分和扣分原因。
+
+### 步骤 3：生成审计报告
+
+按以下格式输出：
+
+```
+## Skill 审计报告：[skill-name]
+
+### 总分：XX / 100（等级：X）
+
+### 分项得分
+
+| 类别 | 得分 | 满分 |
+|------|------|------|
+| 工作流匹配 | XX | 20 |
+| Description 质量 | XX | 20 |
+| Name 规范 | XX | 10 |
+| 正文质量 | XX | 25 |
+| Frontmatter 规范 | XX | 15 |
+| 目录结构 | XX | 10 |
+
+### 未满足项及改进建议
+
+- [ ] **[项目名]** (扣 X 分)
+  - 现状：[当前情况]
+  - 建议：[具体改进方案]
+
+### 改进优先级
+
+1. [最应优先改进的项]
+2. [次优先改进的项]
+3. ...
+```
+
+### 步骤 4：输出格式
+
+支持两种输出模式，根据调用方式自动选择：
+
+#### 模式 A：人类阅读模式（默认）
+
+用户直接调用 blame-skill 时使用，输出完整的 Markdown 审计报告。
+
+#### 模式 B：结构化模式（程序化调用）
+
+当调用参数包含 `--format=json` 或由其他 Skill 程序化调用时，输出 JSON 结构化结果，便于自动化解析：
+
+```json
+{
+  "skill_name": "git-clear",
+  "total_score": 76,
+  "grade": "B",
+  "scores": {
+    "workflow_match": 14,
+    "description_quality": 9,
+    "name_convention": 9,
+    "content_quality": 21,
+    "frontmatter": 13,
+    "directory_structure": 10
+  },
+  "score_details": {
+    "workflow_match": {
+      "workflow_identification": 8,
+      "workflow_completeness": 5,
+      "instruction_executable": 3,
+      "failure_handling": 0
+    },
+    "content_quality": {
+      "markdown_structure": 5,
+      "concrete_examples": 5,
+      "boundary_description": 5,
+      "input_output_spec": 0,
+      "progressive_loading": 5
+    }
+  },
+  "issues": [
+    {
+      "item": "工作流识别",
+      "deduction": 2,
+      "current": "工作流隐含在步骤中，未显式声明工作流模式",
+      "suggestion": "在正文开头明确声明工作流模式（如'本 Skill 采用顺序工作流'）"
+    }
+  ],
+  "improvement_priority": [
+    "Description 补充不适用场景和提供资源",
+    "Description 长度扩展"
+  ]
+}
+```
+
+### 步骤 5：如果用户需要，提供改进后的 SKILL.md
+
+根据审计结果，重写一份符合最佳实践的 SKILL.md 供用户参考。