northseadl/norix-skills/doc-sentinel

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Document-code change notification system: traceable doc-code binding via git tree hash, git-diff-driven reconciliation plans with confidence/risk metadata, and idempotent execution. Use when maintaining documentation freshness, detecting stale docs, or binding docs to source code.

Install

npx vskill@latest install northseadl/norix-skills/doc-sentinel

SKILL.md

Doc Sentinel — 文档-代码变更通知系统

核心概念

你负责守护一个仓库的文档健康度。三平面架构：

平面目标核心能力
Identity绑定真值文档 frontmatter 绑定 source paths + git tree hash
Reconciliation变更推理Git diff → ChangeEvent → Policy → ChangePlan (含 confidence/risk)
Capability可选能力索引生成（默认可用），矢量检索（未来独立技能）

核心价值：让 Agent 准确知道「哪些文档可能需要更新」，不承诺自动修复，不假装语义理解。

成功标准：

  • 零漏报：代码变更必须被检测到
  • 低误报：误报率 < 20%
  • 可解释：每个通知附带变更证据和 confidence

工具

bash
# 主入口
uv run <SKILLS_DIR>/doc-sentinel/scripts/sentinel.py <command> [options]
 
# --- 4 个核心命令 ---
 
# 1. 只读状态查询（无副作用）
status [--root <path>] [--doc <id>] [--source <path>] [--format json]
 
# 2. 建立/更新文档-代码绑定
bind <doc.md> [--source <path>...] [--auto-detect] [--root <path>]
 
# 3. 生成变更计划（不执行）
plan [--since <commit>] [--output plan.json] [--format json] [--root <path>]
 
# 4. 执行计划（幂等）
apply [--dry-run] [--root <path>]

工作流

Phase 1: 理解仓库
  1. 运行 status 查看文档健康状态
  2. 如无文档追踪，用 bind 为关键文档建立绑定
Phase 2: 绑定文档

为需要追踪的文档注入溯源 frontmatter：

bash
# 显式指定源码路径
sentinel.py bind docs/auth.md --source "src/auth/" "src/middleware/auth.py"
 
# 自动检测（使用文档所在目录）
sentinel.py bind docs/api/overview.md --auto-detect
Phase 3: 检测变更

代码变更后，生成变更计划：

bash
sentinel.py plan
# 输出：
#   📋 Stable actions (auto-executable):
#     📝 UPDATE → auth/overview
#        Reason: Source modified (42 lines): src/auth/handler.py
#   🔍 Review items (need confirmation):
#     ✨ CREATE → ?
#        Reason: New file in untracked area: src/billing/stripe.py
Phase 4: 执行计划
bash
# 预览
sentinel.py apply --dry-run
 
# 执行（仅执行 STABLE 级别的操作）
sentinel.py apply

溯源 Frontmatter 规范

每份受管文档头部嵌入：

yaml
---
doc_id: "module/feature"
source_paths: ["module/src/"]
source_tree_hash: "a3f2b8c4d5e6"
last_sync_commit: "e7d1c4a..."
sync_timestamp: "2026-03-05T14:00:00+08:00"
doc_version: 3
status: "synced"
---

变更计划 (ChangePlan) 结构

每个 PlanItem 附带 Agent 可消费的元数据：

json
{
  "action": "update",
  "risk": "stable",
  "doc_id": "auth/overview",
  "reason": "Source modified (42 lines): src/auth/handler.py",
  "confidence": 0.84,
  "details": {
    "modified_source": "src/auth/handler.py",
    "lines_changed": 42
  }
}

动作分类:

分类动作语义
STABLEUPDATE, RENAME, ARCHIVE可自动执行，风险低
REVIEWCREATE需 Agent/人工确认

显著性阈值

修改 (M) 状态使用阈值过滤噪声（默认 5 行）。可通过环境变量调整：

bash
DOC_SENTINEL_THRESHOLD=10 sentinel.py plan

数据目录

<repo_root>/.doc-sentinel/
├── registry.json          # 文档注册表（绑定关系）
├── last_sync_commit       # 上次同步 commit SHA
└── change_log.json        # 操作历史（保留最近 50 条）

参考文档

文档用途何时读取
decision-tree.md变更操作决策树详解处理 plan/apply 时
traceback-spec.md溯源标识详细规范维护 frontmatter 时

输出约定

  • 思考/规划/报告: 中文
  • 代码/命令/文件名: English
  • Frontmatter: YAML (English keys)

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

7-day trend score
0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/northseadl/norix-skills/doc-sentinel/badge)](https://verified-skill.com/skills/northseadl/norix-skills/doc-sentinel)

Something wrong with this skill or its page? Tell us.