审计副总裁

安全 社区 v0.3.2

技能解读

当前原文的自动摘译,尚未人工审校。

召唤横幅

将此横幅输出作为每次调用的第一件事 - 在问题、工作或任何其他输出之前:</greeting> <version_check>

版本更新检查 (ENH-072)

显示问候语横幅后,运行: 如果退出代码 = 1(可用更新 — 新版本打印到标准输出):在任何其他输出之前显示通知横幅:将 {latest_version} 替换为命令中的 stdout,将 {current} 替换为已安装的版本,将 {adapter_id} 替换为活动适配器(claude-code/cursor/antigravity/codex/copilot)。

角色上下文注入 (ENH-073)

在技能启动时,运行:在任何任务执行之前将输出作为## User Persona上下文注入。如果命令不可用或出现错误,则保持沉默。 </persona_context> <适配器id =“claude-code”>

A. 技能调用

技能 được gọi khi 用户提及 vp-audit、/vp-audit、“audit”、“kiểm tra”、“check docs” 将技能提及后的所有用户文本视为 {{VP_ARGS}}

B. 用户提示

清楚地显示审核结果以及按层分组的可行建议。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
安全
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
92 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@0-CODE · v0.3.2 · 未声明许可证
上下文用量评级
中等消耗
接入复杂程度
需手动接入
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
Node.js · Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

<greeting>
## Invocation Banner

Output this banner as the **first** thing on every invocation — before questions, work, or any other output:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 VIEPILOT ► VP-AUDIT  v0.3.2 (fw 2.19.0)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
</greeting>
<version_check>
## Version Update Check (ENH-072)

After displaying the greeting banner, run:
```bash
node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
```

**If exit code = 1** (update available — new version printed to stdout):
Display notice banner before any other output:
```
┌──────────────────────────────────────────────────────────────────┐
│ ✨ ViePilot {latest_version} available  (installed: {current})   │
│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
└──────────────────────────────────────────────────────────────────┘
```
Replace `{latest_version}` with stdout from the command, `{current}` with the installed
version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).

**If exit code = 0 or command unavailable**: silent, continue.

**Suppression rules:**
- `--no-update-check` flag on skill invocation → skip this step entirely
- `config.json` → `update.check: false` → skip this step entirely
- Show at most once per session (`update_check_done` session guard)
</version_check>
<persona_context>
## Persona Context Injection (ENH-073)
At skill start, run:
```bash
node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
```
Inject the output as `## User Persona` context before any task execution.
Silent if command unavailable or errors.
</persona_context>


<adapter id="claude-code">
## A. Skill Invocation
- Skill được gọi khi user mention `vp-audit`, `/vp-audit`, "audit", "kiểm tra", "check docs"
- Treat all user text after the skill mention as `{{VP_ARGS}}`

## B. User Prompting
Display audit results clearly with actionable suggestions grouped by tier.

## C. Tool Usage
Use Claude Code tools: `Bash` (shell), `Read` (file), `Edit` + `Write` (file write/patch),
`Grep` (search), `Glob` (file patterns), `LS`, `WebSearch`, `WebFetch`,
`Agent` (spawn subagent — multi-level nesting supported)
Interactive: `AskUserQuestion` (deferred — preload via ToolSearch before first call)
</adapter>

<adapter id="cursor-agent">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.

## C. Tool Usage
Use Cursor tools: `run_terminal_cmd` (shell), `read_file` (read), `edit_file` (write/edit),
`grep_search` (search), `web_search`, `codebase_search`, `list_dir`, `file_search`
Interactive: text list fallback (AskQuestion available in Plan Mode only; Agent Mode = text)
Subagent: `/multitask` (user command, single-level only — not a callable tool)
MCP limit: 40 tools
</adapter>

<adapter id="antigravity">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.
Skill discovery: LLM-driven (automatic, no slash command needed).

## C. Tool Usage
Use Antigravity tools: `shell` (cmd), `file_read`, `file_write`, MCP plugins
Interactive: text fallback (TUI-based; no formal AskUserQuestion)
Skill path: `.agents/skills/<skill>/SKILL.md` (project) or `~/.gemini/antigravity/skills/` (global)
Note: Gemini CLI deprecated June 18, 2026 — use Antigravity CLI.
</adapter>

<adapter id="codex">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.

## C. Tool Usage
Use Codex tools: `container.exec` (sandboxed shell), `apply_patch` (file write), `web_search`
Interactive: text fallback (TUI Tab/Enter injection)
Config: `~/.codex/config.toml`
</adapter>

<adapter id="copilot">
## A. Skill Invocation
Same trigger keywords as claude-code adapter.
Discovery: User-driven (`@agent-name` in GitHub Copilot Chat).

## C. Tool Usage
Use Copilot tools: `runCommands` (shell), `read`/`readfile` (read), `edit`/`editFiles` (write),
`code_search`, `find_references`
Interactive: `askQuestions` (main agent only — NOT available in subagents; VS Code issue #293745)
Skill path: `.github/agents/<name>.agent.md`
</adapter>
<scope_policy>
## ViePilot Namespace Guard (BUG-004)
- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
- If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
</scope_policy>

<implementation_routing_guard>
## Implementation routing guard (ENH-021)

- **Report / gap** — do **not** fix shipping by default; route **`/vp-request`** → **`/vp-evolve`** → **`/vp-auto`** or user explicit. See `workflows/request.md`.
</implementation_routing_guard>


<objective>
Audit ViePilot project state and documentation to detect drift.
Works on **any project** using ViePilot (Java, Node, Python, etc.).
Auto-detects if running inside the viepilot framework repo to enable framework-specific checks.

**Brownfield Import Compatibility (FEAT-018):**

When auditing a project bootstrapped via `vp-crystallize --brownfield`:

- If `docs/brainstorm/` exists and contains **only** `session-brownfield-import.md` (no `session-*.md` greenfield files):
  - **Valid brownfield import** — do NOT flag as missing brainstorm session.
  - Verify `session-brownfield-import.md` contains a `## Scan Report` section with a YAML block.
    - If YAML block absent → flag LOW severity: "Brownfield stub missing Scan Report content."
  - If `.viepilot/TRACKER.md` contains `## Brownfield Import` section → brownfield metadata confirmed; no further brainstorm check needed.
- If `docs/brainstorm/` is completely absent → flag MEDIUM severity: "No brainstorm session or brownfield stub found — run `/vp-crystallize` or `/vp-crystallize --brownfield`."

**Tier 1 — ViePilot State Consistency (all projects):**
- `.viepilot/TRACKER.md` current state vs `.viepilot/phases/*/PHASE-STATE.md`
- `.viepilot/ROADMAP.md` phase status vs PHASE-STATE.md
- `.viepilot/HANDOFF.json` vs TRACKER.md (resume-state consistency)
- Git tags `vp-p{N}-complete` vs completed phases in PHASE-STATE.md

**Tier 2 — Project Documentation Drift (all projects):**
- `README.md` version vs `package.json` / `pom.xml` / `pyproject.toml`
- `CHANGELOG.md` vs recent git commits
- Placeholder URLs in `docs/` (`your-org`, `YOUR_USERNAME`, etc.)
- New features (from recent phases) without documentation
- `ARCHITECTURE.md` diagram applicability matrix consistency:
  - `required` diagrams must have Mermaid content
  - `optional` diagrams may be omitted/merged with explicit note
  - `N/A` diagrams must have rationale line
- **ENH-022 (recommended check):** when a diagram type is `required` (or `optional` with a real Mermaid block) and crystallize policy applies, verify **`.viepilot/architecture/<type>.mermaid`** exists and that **Diagram source** lines in `ARCHITECTURE.md` match; for `N/A`, sidecar file should be absent (no empty stubs)

**Tier 3 — Stack Best Practices + Code Quality (all projects, for each detected stack):**
- Detect relevant stacks from context/project manifests
- Match code patterns against stack-specific Do/Don't + anti-patterns
- Severity findings: `critical` / `high` / `medium` / `low` with file/module mapping
- Fallback research using `WebSearch` + `WebFetch` when stack cache is missing/weak
- Generate guardrails/checklist output for `vp-auto` reuse during preflight

**Tier 4 — Framework Integrity (only when viepilot framework repo is detected):**
- Auto-detect: `skills/vp-*/SKILL.md` present → this is the viepilot framework repo
- `ARCHITECTURE.md` counts vs actual `skills/`, `workflows/`, CLI
- `README.md` viepilot-specific badges (version, skills-N, workflows-N)
- `docs/skills-reference.md` sections vs `skills/` directory
- **Silent by default (ENH-049):** Tier 4 output is suppressed when all checks pass (✅)
  or when the check is skipped (non-framework repo). Output only appears when issues (⚠️)
  are found. Non-framework repos: Tier 4 skipped silently with no message.

**Output:**
- Report by 4 tiers, each tier with its own status
- Auto-fix option per tier
- Suggestions for complex gaps
- `vp-auto`-compatible guardrails contract per stack
</objective>

<execution_context>
@$HOME/{envToolDir}/workflows/audit.md
</execution_context>

<context>
Optional flags:
- `--framework`  : Force Tier 3 framework checks (even if not auto-detected)
- `--project`    : Force project-only mode — skip Tier 3 framework checks
- `--fix`        : Auto-fix all detected issues
- `--report`     : Generate report file at `.viepilot/audit-report.md`
- `--silent`     : Only output if issues found
- `--tier1`      : Run Tier 1 (state consistency) only
- `--tier2`      : Run Tier 2 (docs drift) only
- `--tier3`      : Run Tier 3 (stack best-practice) only
- `--tier4`      : Run Tier 4 (framework integrity) only
- `--no-autolog` : Skip auto-logging of gaps to `.viepilot/requests/`; report-only mode
- `--visual`     : Run browser-based visual + functional audit of running dev server (ENH-091; requires agent-browser)
- `--browser <url>` : Specify base URL for browser audit (default: `http://localhost:3000`)

### Auto-Log Behavior (ENH-070)

By default, `vp-audit` automatically logs each detected gap as a request file after the audit report is shown — no manual `/vp-request` step needed:

| Tier | Issue category | Request type | Priority |
|------|----------------|-------------|----------|
| 1 | State inconsistency / HANDOFF drift / git tag missing | BUG | medium |
| 1 | Execute-first ordering risk | BUG | medium |
| 2 | Doc drift (README/CHANGELOG version) | BUG | low |
| 2 | Missing docs / placeholder URLs | ENH | low |
| 3 | Stack violation / correctness anti-pattern | BUG | high |
| 3 | Stack improvement / best-practice gap | ENH | medium |
| 4 | Framework integrity gap | ENH | high |

**Duplicate detection**: if a matching open request already exists (title ≥ 70% match or file overlap), the finding is appended to it as a "Re-detected" note rather than creating a duplicate file.

**Post-audit banner**: after auto-logging, shows all logged request IDs and recommends `/vp-evolve {IDs}` as the next action. AUQ prompt on Claude Code terminal.

**Disable**: use `vp-audit --no-autolog` for report-only mode (no `.viepilot/requests/` files created).
</context>

<process>
Execute workflow from `@$HOME/{envToolDir}/workflows/audit.md`

### Quick Summary

**Step 0**: Detect project type (viepilot framework vs user project)

**Step 1 — Tier 1**: ViePilot State Consistency

**Claude Code — invoke file-scanner-agent for state file discovery:**
```
Agent({ subagent_type: "file-scanner-agent",
  description: "file-scanner-agent: scan state files for stale phase refs",
  prompt: "patterns: [\".viepilot/phases/*/PHASE-STATE.md\"]. keywords: [\"in_progress\", \"planned\"]. context: Find phases with stale in_progress or planned status."
})
```
Non-Claude Code: run Glob/Grep inline.

Then cross-check results against:
```bash
# TRACKER.md vs PHASE-STATE.md
# ROADMAP.md vs PHASE-STATE.md
# HANDOFF.json vs TRACKER.md
# Git tags vs completed phases
```

**Step 2 — Tier 2**: Project Documentation Drift

**Claude Code — invoke file-scanner-agent for docs drift scan:**
```
Agent({ subagent_type: "file-scanner-agent",
  description: "file-scanner-agent: scan docs for stale refs and placeholder URLs",
  prompt: "patterns: [\"docs/**/*.md\", \"README.md\", \"CHANGELOG.md\"]. keywords: [\"your-org\", \"YOUR_USERNAME\", \"TODO\", \"placeholder\"]. context: Find stale placeholder refs and docs drift."
})
```
Non-Claude Code: run Glob/Grep inline.

Then check:
```bash
# Detect version: package.json / pom.xml / pyproject.toml
# README.md version mention
# CHANGELOG.md vs recent commits
# Placeholder URLs in docs/
# ARCHITECTURE.md diagram matrix consistency (required|optional|N/A)
```

**Step 3 — Tier 3**: Stack Best Practices + Code Quality
```bash
# detect stack(s), load cache summary first
# if missing/weak cache -> run WebSearch/WebFetch fallback
# emit severity findings + guardrails contract for vp-auto
```

**Step 4 — Tier 4**: Framework Integrity (conditional)

**Step 5**: Generate full report

**Step 5B**: Browser Audit (when `--visual` flag present, Claude Code adapter only)

```
When --visual is passed:
1. Resolve base URL: --browser <url> → config.json audit.baseUrl → http://localhost:3000
2. Dispatch browser-audit-agent:
   Agent({ subagent_type: "browser-audit-agent",
     description: "browser-audit-agent: audit running dev server",
     prompt: `op: audit_routes. baseUrl: ${baseUrl}. projectRoot: ${projectRoot}` })
3. On success: call writeAuditReport(result, projectRoot) → lib/audit/browser-runner.cjs
4. Report path shown to user: .viepilot/audit/visual-report-{timestamp}.md
5. On agent-browser not installed: show prerequisite message, skip browser audit (non-blocking)

After audit_routes: optionally run accessibility_check on same routes:
   Agent({ subagent_type: "browser-audit-agent",
     prompt: `op: accessibility_check. baseUrl: ${baseUrl}. routes: ${JSON.stringify(routes)}. projectRoot: ${projectRoot}` })

Baseline management:
- --visual first run: saves screenshots to .viepilot/audit/baselines/{slug}.png
- Subsequent runs: compares current vs baseline (visual_check op)
- --update-baseline: forces baseline refresh (passes updateBaseline: true to agent)
```

**Step 6**: Auto-fix (if requested)
</process>

<auto_hook>
## Integration with /vp-auto

After each phase complete, /vp-auto should:
1. Run quick audit (--silent mode, Tier 1 + Tier 2 only)
2. If issues found → warn user
3. Offer to fix before continuing

```
Phase 2 complete!

⚠️ Audit found 2 issues:
   Tier 1: ROADMAP.md phase 2 not marked ✅
   Tier 2: README.md version not updated

Fix now? (y/n)
```
</auto_hook>

<success_criteria>
- [ ] Runs on any project using ViePilot (Java, Node, Python, etc.) without errors
- [ ] Tier 1 state consistency checks work for all projects
- [ ] Tier 2 docs drift checks work for all project types (detects version from package.json/pom.xml/pyproject.toml)
- [ ] Tier 3 stack checks run for detected stacks with severity output
- [ ] Tier 3 supports research fallback when stack cache is missing/weak
- [ ] Tier 4 only runs when `skills/vp-*/SKILL.md` detected OR `--framework` flag used
- [ ] Results clearly labeled by tier
- [ ] `--framework` flag forces Tier 4 checks
- [ ] `--project` flag skips Tier 4 checks
- [ ] Auto-fix applies correct fixes per tier
- [ ] No mention of `skills/`, `workflows/`, `vp-tools.cjs` in Tier 1 or Tier 2 output for user projects
</success_criteria>

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。