@netpilot/skills 0.8.0 → 0.9.0

package/skills/wizard/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: wizard
+description: 为必须由用户完成的控制台操作、凭证录入或一次性迁移生成交互式 Bash 向导；仅在存在人工步骤时使用，agent 能自行完成的操作不转交给用户。生成脚本不等于执行脚本或授权外部写入。
+---
+
+# Wizard
+
+**Wizard（交互式向导）** 是分阶段引导人完成手工流程的 Bash 脚本：打开 URL，说明点击和复制位置，接收输入，把值写到明确目标，在必要动作前确认，并显示剩余阶段。它可以帮助配置第三方服务、执行一次性迁移，或从一个已知状态转到另一个状态。
+
+[template.sh](template.sh) 已提供公共 library：阶段进度、清屏、确认、跨平台打开 URL（含 WSL）、隐藏秘密输入、`.env` 幂等 upsert、GitHub secret/variable 写入和结束摘要。**生成向导时，只确定流程并编写阶段，保持 `STAGES` 标记以上的 library 不变。**
+
+向导默认是一次性产物，保存在明确的 scratch 或 `scripts/` 路径。任务结束时说明哪些文件可清理；删除须有目标明确的授权。只有用户要求可重复运行的项目配置路径时才建议保留到仓库；commit、远程写入及不可逆动作分别遵守当前授权。
+
+## 1. 确定人工流程
+
+先读仓库，不把可以查明的事实交给用户：
+
+- 配置任务：`.env.example`、`.env*` 的键名和格式、README、`docker-compose*`、框架配置、`.github/workflows/*` 中的每个 `secrets.*` / `vars.*` 引用。只识别所需值与去向，不把已有秘密读入对话或日志。
+- 迁移任务：当前状态、目标状态、不可逆动作及哪些步骤可重复。配置 upsert 可重跑，不表示迁移命令也幂等。
+- 执行环境：Bash 与必要系统工具；Windows 使用已安装的 Git Bash 或 WSL，不能把存在 `bash.exe` 当成可运行证明。没有可用 Bash 时说明限制，协商等价交付形式，不自动安装运行环境。
+
+向用户展示按顺序排列的阶段、每阶段产生的值和写入位置，等待确认；用户可增删或重排阶段。既有授权可复用，但只授权生成脚本时不运行它。需要 GitHub 写入时，明确 `[host/]owner/repo`，由阶段代码设置 `GH_REPO`，不从运行时工作目录猜目标。
+
+完成条件：每个阶段已命名并排序；每个值的来源、目标（`.env`、GitHub、两者或不保存）和是否为秘密都已明确；没有凭证的纯操作阶段也已标出。
+
+## 2. 描述每个阶段的路径
+
+写清楚打开哪个 URL、点击什么、在哪里取得哪个值、填入哪个变量，例如“Dashboard → Developers → API keys → Reveal test key → 复制”。不知道当前 UI 或精确命令时查一手文档，必要时向用户确认；保留界面实际显示的英文名称，说明用中文。
+
+完成条件：每个阶段都有陌生人也能照做的具体路径，尚未核实的步骤明确列为阻塞。
+
+## 3. 编写向导
+
+把模板复制到不覆盖既有文件的目标路径，替换示例，按依赖顺序每步一个 `stage`。复用 `stage`、`say` / `step`、`open_url`、`ask` / `ask_secret`、`write_env`、`set_secret` / `set_var`、`pause` / `confirm`；`TOTAL_STAGES` 与真实阶段数一致。示例中的服务只是演示，不自动成为用户的选择。
+
+先打开 URL，再询问该页面上的值；秘密使用 `ask_secret`，认证留在用户浏览器中，URL 不携带秘密。持久化 `.env` 值使用 `write_env`，CI 只接收实际引用的值。`set_secret` / `set_var` 会确认明确仓库；不可逆操作也必须置于实际控制流门禁后，例如 `confirm "执行已说明的不可逆动作？" || exit 1`，不能只打印提醒然后继续执行。
+
+每个阶段只承载一个聚焦任务，清屏后仍能看见该任务所需说明。界面只有人能操作的部分交给人；能够安全调用的 API、CLI 或本地检查由 agent 在已授权范围完成。
+
+模板只处理单行 `KEY=value` 的 dotenv 文件：保留空行、整行注释与其他键；支持可准确往返的普通单引号或双引号值。复杂转义、行尾注释、多行值、混合引号组合或符号链接目标会拒绝写入。遇到这些格式，使用项目已认可的配置工具或把该阶段改为明确的人工配置；不得丢弃字符来“修复”凭证，也不得 `source` 不可信 `.env`。写入会以 `mktemp` 文件替换目标，不保证保留原 owner、mode 或 ACL；需要其他服务用户读取的共享配置，应使用项目认可的权限管理工具。运行前核对执行用户与实际读取者的权限，并确保没有其他进程同时编辑该配置；模板不提供多文件事务或并发写入保证。
+
+完成条件：阶段顺序、计数和每个值的去向与已确认流程一致；每个不可逆动作和 GitHub 写入都受实际确认门禁控制；重新运行不会盲目重复已完成的非幂等动作。
+
+## 4. 验证并交接
+
+- 执行 `bash -n <script>`；`shellcheck` 可用时运行，并如实记录缺失。
+- POSIX 环境执行 `chmod +x <script>`；也可以交付明确的 `bash <script>` 命令。
+- agent 不端到端运行生成的真实向导：它会打开浏览器、等待人输入并可能产生外部动作。静态追踪每个值是否到达步骤 1 指定的目标，每个 CI secret 名称是否精确对应 `secrets.*` 引用。
+- 用户要求可重复使用时，按现有授权保存并在项目 README 链接；未授权 commit 时只留下可审查改动。
+
+完成条件：返回脚本绝对路径、执行命令、已执行检查及结果、未验证的人工步骤；有 skipped 或未确认写入时明确列出，不能声称目标状态已全部达成。用户执行后返回结束摘要与脱敏观察结果，调用方据此恢复原任务；不索要原始凭证。

package/skills/wizard/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Wizard"
+  short_description: "生成供用户执行的分阶段人工操作向导，明确输入、写入目标和验证证据"
+  default_prompt: "请使用 $wizard 为必须由我操作的步骤生成可运行向导，并先列出阶段和数据去向。"
+policy:
+  allow_implicit_invocation: true

package/skills/wizard/template.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+#
+# Wizard 分阶段引导用户完成必须人工操作的流程。
+# 由 wizard skill 生成；用户执行，agent 只做静态检查。
+#
+# STAGES 标记以上是统一 library，生成向导时保持不变。
+# 只编写标记以下的具体阶段。
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library：每份向导复用相同的进度、输入、保存和确认行为。
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets this at the top of the stages section.
+TOTAL_STAGES=0
+
+_STAGE_INDEX=0
+ENV_FILE="${ENV_FILE:-.env}"
+GH_REPO="${GH_REPO:-}"  # 由阶段作者设置明确的 [host/]owner/repo，不从 cwd 推断。
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear wipes the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" shows the opening frame: what this wizard does.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  共 %s 个阶段%s\n\n' "$DIM" "$TOTAL_STAGES" "$RESET"
+  printf '%s  你操作浏览器，向导说明步骤并接收你复制回来的值。\n' "$DIM"
+  printf '  可随时按 Ctrl-C 停止；再次运行可保留已经保存的值。\n'
+  printf '  迁移等非幂等步骤仍须先检查当前状态，再决定是否执行。%s\n' "$RESET"
+  pause "准备开始？"
+}
+
+# stage "Name" clears the screen, then announces a stage and shows progress.
+# Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  printf '\n%s%s▸ 阶段 %s/%s · %s%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET"
+}
+
+# say "..." prints a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." is a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL opens it in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  [[ "$url" == https://* || "$url" == http://* ]] || { warn "只支持 HTTP/HTTPS 地址"; return 1; }
+  printf '  %s↗ 打开%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else false; fi
+  } >/dev/null 2>&1 || warn "无法打开浏览器，请手动访问：$url"
+}
+
+# pause "msg" waits for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-按 Enter 继续}" "$RESET"
+  read -r _ || { warn "输入中断，已停止"; return 1; }
+}
+
+# confirm "question" is a y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || return 1
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+_check_key() {
+  [[ "$1" =~ ^[A-Z_][A-Z0-9_]*$ ]] || { warn "键名须为大写字母、数字和下划线，且不以数字开头" >&2; return 1; }
+  case "$1" in
+    HOME|PATH|IFS|ENV|BASH_ENV|SHELLOPTS|BASHOPTS|CODEX_HOME|ENV_FILE|GH_REPO|TOTAL_STAGES|_STAGE_INDEX|WRITTEN_ENV|WRITTEN_SECRET|SKIPPED|BOLD|DIM|RESET|BLUE|GREEN|YELLOW|RED)
+      warn "该名称属于宿主或向导控制变量" >&2; return 1 ;;
+  esac
+}
+
+# 只接受单行 dotenv 值；不 source 文件或执行其中的 shell 表达式。
+_decode_env_value() {
+  local value="$1"
+  value="${value%$'\r'}"
+  if [[ "$value" == \'*\' && ${#value} -ge 2 ]]; then
+    value="${value:1:${#value}-2}"
+    [[ "$value" != *\'* ]] || return 1
+  elif [[ "$value" == \"*\" && ${#value} -ge 2 ]]; then
+    value="${value:1:${#value}-2}"
+    [[ "$value" != *\"* && "$value" != *\\* ]] || return 1
+  else
+    [[ "$value" =~ ^[a-zA-Z0-9_./:@+=,-]*$ ]] || return 1
+  fi
+  printf '%s' "$value"
+}
+
+_check_env_file() {
+  [[ ! -L "$ENV_FILE" ]] || { warn "不写入符号链接 env 文件" >&2; return 1; }
+  [[ ! -e "$ENV_FILE" || -f "$ENV_FILE" ]] || { warn "env 目标不是普通文件" >&2; return 1; }
+  [[ -f "$ENV_FILE" ]] || return 0
+  local line value
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%$'\r'}"
+    [[ "$line" =~ ^[[:space:]]*(#.*)?$ ]] && continue
+    [[ "$line" =~ ^[a-zA-Z_][a-zA-Z0-9_]*= ]] || { warn "env 格式超出单行模板能力；请使用项目认可的配置工具" >&2; return 1; }
+    value="${line#*=}"
+    _decode_env_value "$value" >/dev/null || { warn "env 含复杂引号、注释或多行值；请使用项目认可的配置工具" >&2; return 1; }
+  done < "$ENV_FILE"
+}
+
+# _existing KEY: current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  _decode_env_value "${line#*=}"
+}
+
+# ask KEY "Prompt" reads a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  _check_key "$key" || return 1
+  _check_env_file || return 1
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter 保留当前值]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || { warn "输入中断，未保存"; return 1; }
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" is like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  _check_key "$key" || return 1
+  _check_env_file || return 1
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter 保留当前值]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || { printf '\n'; warn "输入中断，未保存"; return 1; }
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  [[ -n "$input" ]] || { warn "秘密值不能为空，未保存"; return 1; }
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE upserts KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp encoded
+  _check_key "$key" || return 1
+  _check_env_file || return 1
+  [[ "$value" != *$'\n'* && "$value" != *$'\r'* ]] || { warn "模板不支持多行 env 值，未写入"; return 1; }
+  if [[ "$value" != *\'* ]]; then
+    encoded="'$value'"
+  elif [[ "$value" != *\"* && "$value" != *\\* ]]; then
+    encoded="\"$value\""
+  else
+    warn "值包含无法可靠往返的引号组合，请使用项目认可的配置工具"; return 1
+  fi
+  tmp=$(mktemp "${ENV_FILE}.tmp.XXXXXX") || return 1
+  if [[ -f "$ENV_FILE" ]]; then
+    # grep 的 1 表示没有保留行；其他状态是读取失败，不能当成空文件。
+    local filtered=0
+    grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || filtered=$?
+    if [[ $filtered -gt 1 ]]; then rm -f -- "$tmp"; return 1; fi
+  fi
+  if ! printf '%s=%s\n' "$key" "$encoded" >> "$tmp" || ! mv -- "$tmp" "$ENV_FILE"; then
+    rm -f -- "$tmp"; return 1
+  fi
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ 已写入%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+_confirm_repo_write() {
+  [[ "$GH_REPO" =~ ^([a-zA-Z0-9.-]+/)?[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$ ]] || return 1
+  confirm "写入 GitHub 仓库 $GH_REPO 的 $1 $2？"
+}
+
+# set_secret NAME VALUE sets a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  _check_key "$name" || return 1
+  [[ -n "$value" ]] || { warn "秘密值不能为空"; return 1; }
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 && _confirm_repo_write secret "$name"; then
+    if printf '%s' "$value" | gh secret set "$name" --repo "$GH_REPO" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ 已设置%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name：未确认写入成功；先核查目标仓库状态，再决定下一步")
+  warn "未确认 GitHub secret $name 写入成功：目标、授权或 gh 不可用，或写入失败；请核查"
+}
+
+# set_var NAME VALUE sets a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  _check_key "$name" || return 1
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 && _confirm_repo_write variable "$name"; then
+    if gh variable set "$name" --body "$value" --repo "$GH_REPO" >/dev/null 2>&1; then
+      printf '  %s✓ 已设置%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "未确认 GitHub variable $name 写入成功，请核查目标仓库状态"
+}
+
+# finish clears, then shows a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  向导执行结束%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "已写入 $ENV_FILE：${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "已设置 GitHub secrets：${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "仍需人工核查或完成："
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES: 只编写此部分；每个人工步骤对应一个 stage。
+# 替换以下示例，使 TOTAL_STAGES 与阶段数量一致。
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=1
+
+banner "Stripe 配置"
+
+# ── Example stage: replace with your real steps ───────────────────────────
+stage "Stripe：API keys"
+say "获取 Stripe 测试密钥，用于本地开发与 CI；CI 写入需要明确 GH_REPO 并由你确认。"
+open_url "https://dashboard.stripe.com/test/apikeys"
+step "在 API keys 页面复制 Publishable key（以 pk_test_ 开头）。"
+ask STRIPE_PUBLISHABLE_KEY "粘贴公开密钥："
+step "在 Secret key 行点击 'Reveal test key'，然后复制。"
+ask_secret STRIPE_SECRET_KEY "粘贴秘密密钥："
+write_env STRIPE_PUBLISHABLE_KEY "$STRIPE_PUBLISHABLE_KEY"
+write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
+set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"   # CI needs this one
+# ──────────────────────────────────────────────────────────────────────────
+
+finish

package/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -1,8 +1,8 @@
-# Skill Mechanics
+# Skill Mechanics（技能调用机制）
 
 这是 [`writing-for-agents`](SKILL.md) 的 skill-specific branch：当 agent-consumed document 是 skill 时，frontmatter、Invocation 选择与 Router Skills 会带来额外机制。其余写作规则都以 `SKILL.md` 的通用 reference 为唯一来源。
 
-## Invocation
+## Invocation（调用方式）
 
 Skill 有两种选择，用两种负载互换：
 
@@ -19,7 +19,7 @@ Invocation classification 只决定如何到达 skill，不授予文件、Git、
 
 Sequence cut 在 `SKILL.md`；Invocation cut 是 skill 特有的切法。只有出现一个应该独立触发的 Leading Word——而且用户 prompts 中真实使用这个词——或另一个 skill 必须到达该能力时，才拆成 model-invoked skill。新的 description 会永久支付 Context Load，因此 independent reach 必须值得这笔成本。
 
-## Router Skills
+## Router Skills（路由技能）
 
 当 user-invoked skills 多到人难以记住时，累积的 Cognitive Load 由 **Router Skill** 处理：只需记住一个入口，Router 点名其他入口以及何时选择每一个。
 
@@ -50,6 +50,14 @@ Router 只能提示，不能替用户启动 user-invoked skill。User-invoked sk
 
 AI 提出的“优化”必须说明它解决的真实问题，并通过场景或结构验证；更整齐、更短或更长都不是优先于上游的依据。
 
+### 中文与英文的选择
+
+中文承载完整指令，英文保留行为锚点。普通动作、解释、问题和导航标题译成自然中文；Leading Word、跨文件共享领域词首次出现时用英文加中文定义，之后复用同一主名称。命令、路径、代码标识符、协议字段、状态 label 与被其他文档引用的固定章节名保持原值；固定章节名需要解释时，在原值后加中文，不静默改名。
+
+逐句保持约束强度：`only` 是“仅当／只有”，`each / every` 是“每项／每个”，`before / after` 保留先后，`where possible / if available` 保留“尽可能／可用时”。不能把条件性要求译成绝对要求，也不能把强制要求译成建议。英文例句若以措辞本身演示行为锚定，保留原句并解释；若只是演示业务情境，翻译情境但保留角色、动作、结果和反例作用。
+
+不复制整份英文正文形成双语并排版本。文本契约和结构检查只能证明对应规则仍存在；声称中英文效果接近前，需要在相同模型、宿主、任务与权限下反复对照运行，分别检查触发、执行、停止和失败边界。未运行时明确标注“行为等效未验证”。
+
 ## NetPilot 宿主适配
 
 - Skill 目录与 frontmatter `name` 使用唯一的英文 kebab-case；`display_name` 由 canonical name 派生。普通说明、`description`、`short_description` 与 `default_prompt` 默认使用中文，稳定 Leading Words、协议字段、代码、路径和命令保留英文。

package/skills/writing-for-agents/SKILL.md

@@ -5,56 +5,58 @@ description: 为 agent 编写文档。当创建或编辑 skills、修改 AGENTS.
 
 # Writing for Agents
 
-这是为 agent 编写任何文档的 reference：skills、`AGENTS.md` / `CLAUDE.md`，以及由 Context Pointer 到达的文档。包装形式不同，写作方法相同：相同的杠杆让 agent 每次采用相同的 _process_，而不是每次产生相同的输出，从而获得 **Predictability**。
+这是为 agent 编写任何文档的参考：skills、`AGENTS.md` / `CLAUDE.md`，以及由 Context Pointer 到达的文档。包装形式不同，写作方法相同：相同的杠杆让 agent 每次采用相同的过程，而不是每次产生相同的输出，从而获得 **Predictability（可预测性）**。
 
 当正在编写的文档是 skill 时，必须读取 [SKILL-MECHANICS.md](SKILL-MECHANICS.md)，了解 frontmatter、Invocation 选择与 Router Skills。
 
-## Context Pointers
+当要比较中英文效果、修改触发与停止条件，或验证一项优化是否真的改变行为时，读取 [行为验证](references/behavioral-evaluation.md)。它提供独立场景运行与证据判断方法；检查结束后返回当前文档编辑，不把每次文字修订都变成完整评测。
 
-**Context Pointer** 是保留在 agent context 中的一条 reference：它命名 context 之外的材料，同时编码到达该材料的条件。Skill 的 description 是 Context Pointer；`AGENTS.md` 中点名另一份文档的一行也是同一种对象。决定 agent 何时、以及多可靠地到达材料的是 pointer 的 _措辞_，不是目标文件本身。必须读取的材料如果藏在措辞薄弱的 pointer 后面，就是 variance bug：先 sharpen pointer；只有 sharpen 仍失败时才把材料 inline。
+## Context Pointers（上下文指针）
 
-一个 pointer 同时完成两件事：说明材料是什么，并列出应该触发它的 **branches**。Branch 是文档处理的一种独立情形，因此不同 runs 会经过不同路径。始终加载的 pointer 中，每个词都会在每一轮支付成本，所以它比正文更需要 Pruning：
+**Context Pointer** 是保留在 agent context 中的一条引用：它命名 context 之外的材料，同时编码到达该材料的条件。Skill 的 description 是 Context Pointer；`AGENTS.md` 中点名另一份文档的一行也是同一种对象。决定 agent 何时、以及多可靠地到达材料的是 pointer 的 _措辞_，不是目标文件本身。必须读取的材料如果藏在措辞薄弱的 pointer 后面，就是 variance bug：先收紧 pointer 的措辞；只有收紧后仍失败时才把材料直接放进正文。
 
-- **Front-load the Leading Word**：pointer 正是在这里完成触发。
-- **One trigger per branch**：仅仅用同义词重命名同一个 branch，等于把同一 branch 写了两次；collapse 它们，只保留真正不同的 branches。
-- **Cut identity the body already carries**：删除正文已经承担的身份说明。
+一个 pointer 同时完成两件事：说明材料是什么，并列出应该触发它的 **branches（分支）**。Branch 是文档处理的一种独立情形，因此不同运行会经过不同路径。始终加载的 pointer 中，每个词都会在每一轮支付成本，所以它比正文更需要 Pruning：
+
+- **Front-load the Leading Word（把行为锚点放在前面）**：pointer 正是在这里完成触发。
+- **One trigger per branch（每个分支保留一个触发条件）**：仅仅用同义词重命名同一个 branch，等于把同一 branch 写了两次；合并它们，只保留真正不同的 branches。
+- **删除正文已经承担的身份说明**。
 
 ## 两种负载
 
 每增加一份文档或 pointer，都会花费下面两种预算之一：
 
-- **Context Load**：始终加载的材料占用 agent context window 的成本。`AGENTS.md` 中的一行、skill description，以及每轮都位于 context 中的内容，无论是否触发都消耗 tokens 与 attention。
-- **Cognitive Load**：由人承担的成本——记住有哪些文档，以及何时使用每一份。人是 index。它不是应该机械最小化的成本，而是 human agency 的代价；在人类判断重要时支付，在不重要时移除。
+- **Context Load（上下文负载）**：始终加载的材料占用 agent context window 的成本。`AGENTS.md` 中的一行、skill description，以及每轮都位于 context 中的内容，无论是否触发都消耗 tokens 与注意力。
+- **Cognitive Load（认知负载）**：由人承担的成本——记住有哪些文档，以及何时使用每一份。人是索引。它不是应该机械最小化的成本，而是人保有自主决定权的代价；在人类判断重要时支付，在不重要时移除。
 
 只通过 pointer 到达的材料可以避开正文的 Context Load，但要支付 pointer 自身一行的成本；完全没有 pointer 的材料则完全依赖 Cognitive Load。
 
-## Information Hierarchy
+## Information Hierarchy（信息层级）
 
 文档由两种内容自由组合：
 
-- **Steps**：agent 按顺序执行的动作；
-- **Reference**：按需查阅的定义、规则和事实。
+- **Steps（步骤）**：agent 按顺序执行的动作；
+- **Reference（参考资料）**：按需查阅的定义、规则和事实。
 
-文档可以全是 Steps（recipe）、全是 Reference（review rules 或本 skill），也可以二者兼有。核心判断是把每项内容放在 **Information Hierarchy** 的哪一级；这个阶梯按 agent 多快需要材料排序：
+文档可以全是 Steps（操作步骤）、全是 Reference（审查规则或本 skill），也可以二者兼有。核心判断是把每项内容放在 **Information Hierarchy** 的哪一级；这个阶梯按 agent 多快需要材料排序：
 
-1. **In-file Step**：主要层，agent 按顺序执行的动作。
-2. **In-file Reference**：按需查阅。它可以是合法的 flat peer-set，例如 review 的每条规则都在同一层；这不是结构缺陷。
-3. **Disclosed Reference**：移到独立文件中，由 Context Pointer 到达，只在 pointer 触发时加载。它可以是同一目录的 sibling file，也可以是任何文档都能指向的 External Reference。
+1. **In-file Step（文件内步骤）**：主要层，agent 按顺序执行的动作。
+2. **In-file Reference（文件内参考）**：按需查阅。它可以是合法的同层规则集合，例如 review 的每条规则都在同一层；这不是结构缺陷。
+3. **Disclosed Reference（按需展开的外部参考）**：移到独立文件中，由 Context Pointer 到达，只在 pointer 触发时加载。它可以是同一目录下的文件，也可以是任何文档都能指向的 External Reference。
 
 下推得太少会让顶部膨胀；下推得太多会藏起 agent 真正需要的材料。这股张力就是全部判断。
 
-**Progressive Disclosure** 是沿阶梯向下移动：把内容从主文件移到 pointer 后面，使顶部保持可辨认。它首先保护 Information Hierarchy，而不只是节省 tokens。Branching 是最清楚的 disclosure test：每个 branch 都需要的内容 inline；只有部分 branches 到达的内容放到 pointer 后面。文档存在 Steps 时，本应 disclosed 的 Reference 会埋住 Steps，使 agent 是否关注它近似 coin-flip；这是 variance lever，不只是可读性问题。
+**Progressive Disclosure（渐进披露）** 是沿阶梯向下移动：把内容从主文件移到 pointer 后面，使顶部保持可辨认。它首先保护 Information Hierarchy，而不只是节省 tokens。按分支判断是最清楚的披露检验：每个 branch 都需要的内容直接放在正文中；只有部分 branches 到达的内容放到 pointer 后面。文档存在 Steps 时，本应按需展开的 Reference 会埋住 Steps，使 agent 是否关注它近似抛硬币；这是影响运行差异的因素，不只是可读性问题。
 
-**Co-location** 是同一文件内的配套判断：阶梯决定内容放多深，Co-location 决定到达该层后哪些内容彼此相邻。把一个概念的定义、规则和 caveats 放在同一标题下，而不是散落各处，使 agent 读到一部分时也同时获得它的邻居。测试方式是：文档应像专门写给 agent 的 documentation；相关材料集中时通常如此。Co-location 不同于 Duplication：Duplication 重复同一 meaning，散落则把一个 meaning 的不同部分拆到多处。
+**Co-location（相关内容相邻放置）** 是同一文件内的配套判断：阶梯决定内容放多深，Co-location 决定到达该层后哪些内容彼此相邻。把一个概念的定义、规则和注意事项放在同一标题下，而不是散落各处，使 agent 读到一部分时也同时获得它的邻居。测试方式是：文档应像专门写给 agent 的文档；相关材料集中时通常如此。Co-location 不同于 Duplication：Duplication 重复同一含义，散落则把一个含义的不同部分拆到多处。
 
-**Sprawl** 是这里的 Failure Mode：即使每一行仍然有效且唯一，文档也可能只是太长。过量内容会稀释 attention，每增加一行也多一行需要持续保持 Relevant。处理方式是 Information Hierarchy：把 Reference disclosed 到 pointer 后面，并按 branch 或 sequence 拆分，使每条路径只携带它所需的内容。
+**Sprawl（无节制膨胀）** 是这里的 Failure Mode：即使每一行仍然有效且唯一，文档也可能只是太长。过量内容会分散注意力，每增加一行也多一行需要持续保持相关。处理方式是 Information Hierarchy：把 Reference 移到 pointer 后面按需展开，并按 branch 或 sequence 拆分，使每条路径只携带它所需的内容。
 
-## Steps 与 Completion Criteria
+## Steps 与 Completion Criteria（步骤与完成条件）
 
 每个 Step 都结束于 **Completion Criterion**：告诉 agent 这项工作何时完成的条件。两个属性让它成为行为杠杆：
 
-- **Clarity**：agent 能否区分 done 与 not-done？模糊边界（例如“已经形成理解”）会邀请 **Premature Completion**：当前 Step 尚未真正完成，attention 已滑向 _being done_。仍然可见的后续 Steps——**Post-Completion Steps**——提供向前的拉力，Criterion 的 Clarity 提供阻力。按顺序防守：**先 sharpen bound**，因为它局部且便宜；只有边界不可避免地模糊，且真实运行已经观察到 rush，才通过 sequence split 隐藏后续 Steps。隐藏只有跨越真实 context boundary 才生效，例如 handoff 或 subagent dispatch；inline 调用仍让后续 Steps 留在 context 中，什么也没有清除。
-- **Demand**：Criterion 要求多少工作。“每个修改过的 model 都已核对”会驱动比“生成改动列表”更充分的工作。Demand 驱动 **Legwork**——agent 在工作单元内部完成的挖掘；它潜伏在措辞里，不应另写成机械步骤。Demand 也不依赖 Steps：“每条规则都已应用”同样能约束一份 flat Reference，因此全 Reference 文档仍然可以拥有穷尽门槛。
+- **Clarity（清晰度）**：agent 能否区分完成与未完成？模糊边界（例如“已经形成理解”）会邀请 **Premature Completion（过早结束）**：当前 Step 尚未真正完成，注意力已经滑向“赶快结束”。仍然可见的后续 Steps——**Post-Completion Steps（当前步骤之后的步骤）**——提供向前的拉力，Criterion 的 Clarity 提供阻力。按顺序防守：**先把完成边界写明确**，因为它局部且便宜；只有边界不可避免地模糊，且真实运行已经观察到仓促跳步，才通过步骤序列拆分隐藏后续 Steps。隐藏只有跨越真实上下文边界才生效，例如 handoff 或 subagent dispatch；在当前上下文内调用仍让后续 Steps 留在 context 中，什么也没有清除。
+- **Demand（工作要求的强度）**：Criterion 要求多少工作。“每个修改过的 model 都已核对”会驱动比“生成改动列表”更充分的工作。Demand 驱动 **Legwork（深入调查）**——agent 在工作单元内部完成的挖掘；它潜伏在措辞里，不应另写成机械步骤。Demand 也不依赖 Steps：“每条规则都已应用”同样能约束一份同层规则组成的 Reference，因此全 Reference 文档仍然可以拥有穷尽门槛。
 
 最强的 Completion Criteria 同时可检查且穷尽。
 
@@ -62,30 +64,30 @@ description: 为 agent 编写文档。当创建或编辑 skills、修改 AGENTS.
 
 把一份文档拆成两份会花费两种负载之一，因此只在切分确实值得时进行：
 
-- **按 Sequence 拆分**：当 Post-Completion Steps 诱使 agent rush 当前 Step 时切分。把后续内容移出视野，可以驱动当前任务内更多 Legwork。反方向也要小心：合并 sequences 会让每个 Step 看到更多后续 Steps，从而邀请 Premature Completion。
+- **按步骤序列拆分**：当 Post-Completion Steps 诱使 agent 仓促结束当前 Step 时切分。把后续内容移出视野，可以驱动当前任务内更多 Legwork。反方向也要小心：合并 sequences 会让每个 Step 看到更多后续 Steps，从而邀请 Premature Completion。
 - **按 Invocation 拆分**：这是 skill 特有的切法；读取 [SKILL-MECHANICS.md](SKILL-MECHANICS.md)。
 
-## Leading Words
+## Leading Words（行为锚点）
 
-**Leading Word** 是模型预训练中已经存在、agent 运行文档时用来思考的紧凑概念，例如 _lesson_、_fog of war_、_tracer bullets_。它以 token 重复，而不是以句子重复；由此积累分布式定义，并用最少 tokens 调用已有 behavioural priors，锚定一整片行为。自造词只要定义清楚也能工作，但它没有预训练 priors：已有词免费提供的东西，自造词要用定义 tokens 偿还，因此先寻找已有词。
+**Leading Word** 是模型预训练中已经存在、agent 运行文档时用来思考的紧凑概念，例如 _lesson_、_fog of war_、_tracer bullets_。它以 token 重复，而不是以句子重复；由此积累分布式定义，并用最少 tokens 调用已有的行为先验，锚定一整片行为。自造词只要定义清楚也能工作，但它没有预训练先验：已有词免费提供的东西，自造词要用定义所需的 tokens 来偿还，因此先寻找已有词。
 
 Leading Word 有两次锚定作用：
 
-- 在正文中锚定 _execution_：agent 每次看到它都到达相同类型的行为；在 flat Reference 中，它把 attention 聚焦到要寻找的一类对象。
-- 在 pointer 中锚定 _invocation_：当同一个词也存在于 prompts、docs 与 codebase 中时，agent 会把共享语言连接到相应材料，并更可靠地到达它。
+- 在正文中锚定 _execution（执行）_：agent 每次看到它都到达相同类型的行为；在同层规则组成的 Reference 中，它把注意力聚焦到要寻找的一类对象。
+- 在 pointer 中锚定 _invocation（调用）_：当同一个词也存在于提示词、文档与代码库中时，agent 会把共享语言连接到相应材料，并更可靠地到达它。
 
-主动寻找可以用 Leading Words refactor 的表达：三处都展开的三元组、用整句含糊指向一个想法的 pointer，都应该 collapse 为一个 token。
+主动寻找可以用 Leading Words 改写的表达：三处都展开的三元组、用整句含糊指向一个想法的 pointer，都应该收拢为一个 token。
 
 - “快速、确定、低开销” → _tight_，形成 _tight feedback loop_。
 - “一个你相信的循环” → _red_：模糊门禁变为二元可观察状态——loop 能在 bug 上变 _red_，或不能。
 
 收益有两次：tokens 更少，同时为 agent 的思考提供更锋利的挂钩。默认假设每份文档都携带着可由 Leading Words 退役的复述，并主动寻找它们。
 
-**Negation** 是这个杠杆旁边的 Failure Mode：通过禁止来 steering，会把被禁止的行为拖进 context，反而提高它的可用性。_Don't think of an elephant_，此时 context 中只剩 elephant；negation 是弱 modifier，可能被刚刚强烈激活的概念压过，使禁令被半读成行动提示。Prompt the **positive**：直接描述目标行为，例如“comments 保持单行”，让被禁止对象不进入 frame。只有无法用正向目标表达的硬 guardrail 才值得保留 prohibition；即使如此，也要配对写出正向目标，使 attention 落到应该做什么。
+**Negation（否定表达）** 是这个杠杆旁边的 Failure Mode：通过禁止来引导，会把被禁止的行为拖进 context，反而提高它的可用性。_Don't think of an elephant_（不要想大象），此时 context 中只剩大象；negation 是弱修饰语，可能被刚刚强烈激活的概念压过，使禁令被半读成行动提示。使用 **positive（正向目标）**来提示：直接描述目标行为，例如“注释保持单行”，让被禁止对象不进入提示的关注范围。只有无法用正向目标表达的硬性防护边界才值得保留禁令；即使如此，也要配对写出正向目标，使注意力落到应该做什么。
 
-## Pruning
+## Pruning（删减）
 
-- 让每个 meaning 只有一个 **Single Source of Truth**：一个权威位置，使行为变化只需修改一处。**Duplication** 是同一 meaning 出现在多处；它增加维护与 tokens，并把该 meaning 在 Information Hierarchy 中的 prominence 抬得高于真实层级。它是 Leading Word 的意外反面：Leading Word 有意重复一个 token，从不重复完整 meaning。
-- **environment** 也是 source of truth：`package.json` scripts、config files、目录布局与 `--help` 输出都可以被 agent 直接查看。文档复述这些内容就是 **cache**，只有 lookup 本身昂贵时才值得支付 load。Cache agent 无法通过查看得到的内容：未写下的约定、选择背后的原因、config 不会承认的 gotcha。把一文件或一命令即可得到的事实留在 environment 中，那里不会因复制而 stale。
-- 逐行检查 **Relevance**：这行是否仍直接影响文档所做的事？一行可能从未与任务相关，例如纯 exposition 或本应 disclosed 的 branch；也可能随着行为或世界变化而 stale。更短的文档更容易保持 Relevant。没有 Pruning discipline 时，默认结局是 **Sediment**：旧层因为添加令人安心、删除令人不安而不断沉积，直到维护者必须向下取芯才能找到仍然有效的内容。
-- 逐句寻找 **No-Op**：模型默认已经会遵守的指令，只支付 load 却没有改变行为。测试问题是“相对默认值，它是否改变了行为？”这是 model-relative，而不是 reader-relative；两个人对 No-Op 有分歧，实质是在争论模型默认值，应通过运行文档解决，而不是辩论。句子失败时删除整句，不要靠删几个词保留它。Leading Word 也接受同一测试：如果 _be thorough_ 无法超过模型本来就有的“有点 thorough”，它就是 No-Op；修复方式是更有力的词，例如 _relentless_，而不是另造技巧。
+- 让每个含义只有一个 **Single Source of Truth（单一事实来源）**：一个权威位置，使行为变化只需修改一处。**Duplication（语义重复）** 是同一含义出现在多处；它增加维护与 tokens，并把该含义在 Information Hierarchy 中的显著程度抬得高于真实层级。它是 Leading Word 的意外反面：Leading Word 有意重复一个 token，从不重复完整含义。
+- **environment（运行环境）** 也是事实来源：`package.json` scripts、配置文件、目录布局与 `--help` 输出都可以被 agent 直接查看。文档复述这些内容就是 **cache（缓存）**，只有查找本身昂贵时才值得支付负载。缓存 agent 无法通过查看得到的内容：未写下的约定、选择背后的原因、配置中看不出的陷阱。把一文件或一命令即可得到的事实留在 environment 中，那里不会因复制而过时。
+- 逐行检查 **Relevance（相关性）**：这行是否仍直接影响文档所做的事？一行可能从未与任务相关，例如纯背景讲解或本应按需展开的 branch；也可能随着行为或世界变化而过时。更短的文档更容易保持相关。没有 Pruning 纪律时，默认结局是 **Sediment（失效内容沉积）**：旧层因为添加令人安心、删除令人不安而不断沉积，直到维护者必须向下取芯才能找到仍然有效的内容。
+- 逐句寻找 **No-Op（相对模型默认行为不起作用的指令）**：模型默认已经会遵守的指令，只支付负载却没有改变行为。测试问题是“相对默认值，它是否改变了行为？”这取决于具体模型，而不是读者个人感受；两个人对 No-Op 有分歧，实质是在争论模型默认值，应通过运行文档解决，而不是辩论。句子失败时删除整句，不要靠删几个词保留它。Leading Word 也接受同一测试：如果 _be thorough_ 无法超过模型本来就有的“有点 thorough”，它就是 No-Op；修复方式是更有力的词，例如 _relentless_，而不是另造技巧。

package/skills/writing-for-agents/references/behavioral-evaluation.md

@@ -0,0 +1,29 @@
+# 技能行为验证
+
+静态校验可以发现损坏的 metadata、引用和附件；固定关键词可以保护特定文本契约。它们都不能证明 agent 会在真实任务中作出正确决定。只有需要验证触发、执行、停止、失败边界或语言效果时才使用本参考。
+
+## 选择能区分行为的场景
+
+从真实请求、已观察到的失败或此次修改的假设出发，写下用户输入、必要原始材料、可用工具及权限。验收条件描述外部可观察行为，不抄 skill 的标题作为答案。
+
+根据本次变化选择正常、相邻不触发、边界或失败场景。例如：测试 `grilling` 时，提供两个已就绪决定和一个依赖问题，观察实际轮次；测试脱敏时，在假日志中放入虚构认证值，观察展示内容；测试工具不可用时，明确工具集，观察是否虚构执行。不要拿真实凭证或生产数据作样本。
+
+完成条件：每个场景都能说明要观察哪个决定或结果，以及什么证据能够推翻“修改有效”的假设。
+
+## 独立前向运行
+
+有可用且已获授权的子代理时，使用新上下文运行，每个评估者只看到：实际用户请求、待测 skill 及其必要附件、最低限度的原始材料、工具与写入边界。**不提供预期答案、怀疑的问题、修改理由、作者结论或其他运行结果。** 评判标准由调用方保留，不能在给执行者的提示中泄露答案。
+
+使用隔离临时工作区或纯只读场景；有外部副作用时使用受控工具桩。不要加载两个竞争版本，也不要让第二轮继承第一轮的推理。没有独立执行环境时，说明只完成静态分析，不把作者自己的复述当成前向运行。
+
+比较版本时保持任务、原始材料、模型、推理设置、宿主、工具和权限一致。中英文比较要区分“原始上游与本地适配”的综合差异和“仅改变语言”的差异；需要隔离语言因素时，两份材料的宿主及权限适配也必须相同。
+
+完成条件：每次运行都有可复核的输入与真实输出／工具轨迹，且执行者未收到答案提示；不能把一次只读推演描述成实际工具执行。
+
+## 判断结果并回到编辑
+
+调用方逐条对照事先定义的验收条件，记录结果、支持证据与未能观察的部分。区分规则缺失、调用不可达、宿主限制和模型运行差异。修正只针对有证据的问题；不要把单次场景的偶然细节扩成所有任务都必须遵守的规则。
+
+一次运行适合发现具体反例，不能证明总体等效。要比较可靠性，交错运行顺序并重复场景，报告实际次数与结果分布；高方差时增加样本，证据不足时保留不确定性。结构检查、盲测和人工判断分别报告。
+
+完成条件：结论对应实际证据，未执行与无法判定项明确；有回退则修订并重跑受影响场景，再返回当前编辑任务。没有行为运行证据时，不声称效果已提升或中英文等效。