文档-代码变更通知系统
通过 git tree hash 绑定文档与源码，自动检测代码变更并生成带 confidence/risk 元数据的结构化修复计划。让 Agent 准确知道「哪些文档需要更新」。
FEATURES
使用 git ls-tree 实现 O(1) 目录级变更检测。追踪目录时，任何深度的文件变化都会被捕获（Merkle tree 性质）。
解析 git diff --name-status 输出，为 M/R/A/D 四种状态映射对应的文档操作（UPDATE/RENAME/ARCHIVE/CREATE）。
每个 PlanItem 携带 action、risk（STABLE/REVIEW）、confidence、reason。Agent 可直接消费 JSON 输出决策。
status 命令零副作用。不修改任何文件、不更新 registry。安全地了解文档健康度。
apply 命令执行后自动更新 sync point。再次运行 plan 返回 0 items。安全重试，无重复操作。
修改低于阈值（默认 5 行）的变更自动标记为 NOOP。通过 DOC_SENTINEL_THRESHOLD 环境变量可调。
REFERENCE
只读状态查询，零副作用
| 命令 | 说明 | 示例 |
|---|---|---|
status | 全局健康报告 | sentinel.py status --root . |
--doc | 查询特定文档 | sentinel.py status --doc docs/auth/overview |
--source | 反查源码路径 | sentinel.py status --source src/auth/ |
--format json | 结构化 JSON 输出 | sentinel.py status --format json |
建立文档-代码溯源关系
| 命令 | 说明 | 示例 |
|---|---|---|
bind | 显式指定源码 | sentinel.py bind docs/auth.md --source "src/auth/" |
--auto-detect | 自动检测目录 | sentinel.py bind docs/api/overview.md --auto-detect |
生成变更计划，不执行
| 命令 | 说明 | 示例 |
|---|---|---|
plan | 分析 git diff | sentinel.py plan |
--since | 指定基准 commit | sentinel.py plan --since abc1234 |
--output | 输出计划文件 | sentinel.py plan --output plan.json |
--format json | JSON 格式输出 | sentinel.py plan --format json |
执行变更计划（幂等）
| 命令 | 说明 | 示例 |
|---|---|---|
apply | 执行 STABLE 级操作 | sentinel.py apply |
--dry-run | 预览不执行 | sentinel.py apply --dry-run |
Doc Sentinel 采用三平面架构：
| 平面 | 目标 | 核心能力 |
|---|---|---|
| Identity | 绑定真值 | frontmatter 绑定 source_paths + git tree hash |
| Reconciliation | 变更推理 | Git diff → ChangeEvent → Policy → ChangePlan |
| Capability | 可选能力 | 索引生成（内置） |
为仓库文档注入溯源 frontmatter，建立与源码的绑定关系：
# 显式指定源码路径
sentinel.py bind docs/auth.md --source "src/auth/" "src/middleware/auth.py"
# 自动检测（使用文档所在目录作为源码路径）
sentinel.py bind docs/api/overview.md --auto-detect绑定后文档头部会注入 YAML frontmatter：
---
doc_id: "docs/auth"
source_paths: ["src/auth/"]
source_tree_hash: "c91bf57ebf9a"
last_sync_commit: "e7d1c4a..."
sync_timestamp: "2026-03-05T14:00:00+08:00"
doc_version: 1
status: "synced"
---代码变更后，生成变更计划：
sentinel.py plan
# 📋 Stable actions (auto-executable):
# 📝 UPDATE → docs/auth/overview
# Reason: Source modified (42 lines): src/auth/handler.py
# 🔍 Review items (need confirmation):
# ⚠️ CREATE → src/notifications/email.py计划中的每个条目携带 Agent 可消费的元数据：
{
"action": "update",
"risk": "stable",
"confidence": 0.84,
"reason": "Source modified (42 lines): src/auth/handler.py"
}# 预览（不修改任何文件）
sentinel.py apply --dry-run
# 执行（仅执行 STABLE 级别的操作）
sentinel.py apply| Git 事件 | 条件 | 动作 | 风险级别 | 说明 |
|---|---|---|---|---|
| M (修改) | ≥ 阈值 | UPDATE | STABLE | 标记文档为 stale |
| M (修改) | < 阈值 | NOOP | — | 静默忽略微小变化 |
| R (重命名) | 有追踪文档 | RENAME | STABLE | 更新 source_paths |
| R (重命名) | 无追踪文档 | CREATE | REVIEW | 建议创建新文档 |
| D (删除) | 全部源码已删 | ARCHIVE | STABLE | 标记文档为 archived |
| D (删除) | 其他源码仍在 | UPDATE | STABLE | 标记文档需更新 |
| A (新增) | 在已追踪目录内 | UPDATE | STABLE | 通知父文档有新文件 |
| A (新增) | 在未追踪区域 | CREATE | REVIEW | 建议创建新文档 |
显著性阈值通过环境变量调整：
DOC_SENTINEL_THRESHOLD=10 sentinel.py plan<repo_root>/.doc-sentinel/
├── registry.json # 文档注册表（绑定关系）
├── last_sync_commit # 上次同步的 commit SHA
└── change_log.json # 操作历史（保留最近 50 条）doc-sentinel/
├── SKILL.md ← Agent 入口
├── references/
│ ├── decision-tree.md ← 变更决策树详解
│ └── traceback-spec.md ← 溯源标识详细规范
└── scripts/
├── sentinel.py ← CLI 入口 (4 commands)
└── lib/
├── __init__.py ← 包初始化
├── identity.py ← Identity Plane (frontmatter + hash)
├── registry.py ← 文档注册表 (scan/query/persist)
├── reconciler.py ← Reconciliation Plane (diff → plan)
└── indexer.py ← 索引文档生成器
零依赖: 纯 Python 3 stdlibINSTALL