AI Work Review

AI Work Review

Review and approve AI's work on your markdown vault — right inside Obsidian.

AI coding assistants (ZCode, Claude Code, Cursor, …) edit your notes fast, but you are the one who decides what ships. This plugin gives every AI-touched markdown file a clear verdict — ✅ pass / ⚠️ needs work / ❌ rejected — shows exactly where the problems are, and lets the AI propose full replacements that you confirm via a diff before anything is written.

Chinese UI documentation: 中文说明 · Interface language: Chinese / English (auto-detected, configurable).

Why

Vibe-editing a knowledge vault fails in a predictable way: small inconsistencies accumulate until nobody knows which files are trustworthy. This plugin closes the loop:

1. Deterministic rule checks (free, instant, in Obsidian) catch the mechanical failure modes.
2. Deep AI review (runs in your terminal with your AI agent) catches semantic issues, writes structured reports the plugin imports.
3. Human approval — nothing the AI writes ever reaches your files until you accept it in a diff view.

Two modes

The panel header has a mode switch (persisted per vault):

• Novel mode — per-file review: every markdown file in scope gets a verdict, grouped by folder. Best for reviewing knowledge/setting files one by one.
• Dev mode — task-pipeline review. Each change lives in one 开发文档 under docs/开发文档/<module>/. The author can Adjust or Approve; templates live in the agent skill, not the vault. Fixed bugs are distilled into the module card's 缺陷史 (symptom → root cause), which the AI reads before start/change/deliver as a regression checklist. Shared concepts (e.g. a local currency) live as concept cards under docs/公用配置/ (distilled via /dev-review 建卡 from the chat or from code), referenced from docs via [[wikilinks]] — the card is authoritative and the AI never guesses; variant terms in docs are unified to the canonical name. External API material (web pages / tables / txt / word) is normalized via /dev-review 接口摄取 into one per-service summary under docs/接口文档/; 接口变动 produces field-level change lists and can hand off adaptation requirements; 接口比对 diffs the doc against code call sites to find drift. Reusable components are registered into docs/组件文档/ via /dev-review 组件解析, with dual-dimension tags (#能力/#场景, controlled vocabulary, searchable in Obsidian, index grouped by capability); before writing UI, 组件查 locates candidates tag-first and recommends what to reuse; before changing a component or page, 组件影响 reverse-maps every consumer from code into an impact list; [[page]]/[[component]] wikilinks in business docs form a business→page→component impact chain (changes graded along the chain, code search as the fallback). Legacy 开发需求/ + 开发交付/ pairs still show until migrated.

Pair Dev mode with a small agent skill (see the skills/ folder in this repo) so the AI writes requirement docs & delivery notes there and consumes your adjustments — a full "AI works → you approve in Obsidian → AI continues" loop.

Features

Rule checks (run instantly, no AI needed)

• Template completeness — map any folder to a template file; the plugin checks that sections (## …) and fields (- **name**:) exist and aren't left empty or still containing the template placeholder. Values written in sub-bullets are recognized.
• Draft/pending markers — configurable regex (defaults: 草案， 待定， TODO, …) with per-line locations.
• Reference integrity — `path/to/file.md` backtick references and [[wikilinks]] that point nowhere.
• Index consistency — an index file's table is cross-checked against the folder it indexes (missing listings / dead links, both directions).
• Status field checks — configurable per folder (folder|field|final values), e.g. flag chapters not yet final.

AI bridge (.ai-review/ folder in your vault root, hidden from search)

• reports/<mirrored path>/<file>.json — structured AI review reports, auto-imported (20s polling) and archived.
• proposals/<mirrored path>/<file>.md — full proposed replacements; shown as a unified diff ("changes only" toggle), applied only on your click.
• adjustments/<mirrored path>/<file>.md.json — your adjustment notes written from the panel; the AI reads these and has to follow them. Cleared automatically once a proposal is applied.

Review panel (ribbon icon)

• Per-file status with counts, grouped by folder, "issues only" filter, click an issue to jump to the line.
• Verdicts: rules + AI combined; your manual verdict (approve / adjust) always wins.
• One click exports ready-to-paste prompts: "review these files" and "fix according to my adjustment notes".

The workflow

Obsidian                              your terminal (AI agent)
┌──────────────────────────┐          ┌──────────────────────────────┐
│ 1. Re-check (rules)      │          │                              │
│ 2. Copy AI review prompt ─┼─ paste ─→│ 3. deep review, writes       │
│                          │          │    .ai-review/reports/*.json │
│ 4. auto-import (20s)  ←──┼──────────┤                              │
│ 5. read issues, jump to  │          │                              │
│    lines                 │          │                              │
│ 6. "Adjust" + write what │─paste ──→│ 7. /fix command reads        │
│    is wrong              │          │    adjustments/, writes      │
│                          │          │    .ai-review/proposals/*.md │
│ 8. diff → Apply&replace  │←─────────┤                              │
│ 9. approve manually      │          │                              │
└──────────────────────────┘          └──────────────────────────────┘

Nothing is written to your notes by the AI directly. Ever.

Report schema

{
  "schema": "novel-review/report@1",
  "file": "notes/some-file.md",
  "reviewer": "zcode",
  "timestamp": "2026-09-05T12:00:00+08:00",
  "verdict": "pass | warn | fail",
  "summary": "one-line summary",
  "issues": [
    {
      "severity": "error | warn | info",
      "dimension": "consistency | quality | plot | character | template",
      "section": "Section heading",
      "line": 42,
      "problem": "what is wrong (required)",
      "suggestion": "how to fix it"
    }
  ]
}

Adjustment notes (novel-review/adjustment@1): { "schema", "file", "timestamp", "note" }.

The field names keep their historic novel-review prefix for backward compatibility with existing bridges.

Settings

• Scope: folders and root files to scan; folder→template mapping; index files; status field checks; draft-marker regex.
• AI bridge: folder name (default .ai-review), auto-import toggle, archive toggle.
• General: interface language (auto / 中文 / English).
• Maintenance: clear all review data.

Pairing with an AI agent

Any agent that can read/write files works. For ZCode / Claude Code, drop a small skill file into the vault (.zcode/skills/novel-review/SKILL.md — ready-made copies live in this repo's skills/ folder) that teaches the agent the protocol: load context files first, write reports to reports/, write full replacements to proposals/, never touch originals.

Manual install

Build (npm install && npm run build:only) and copy main.js, manifest.json, styles.css into <vault>/.obsidian/plugins/ai-work-review/, then enable it in Obsidian settings. Or use node scripts/install-to-vault.mjs <vault…>.

For local development, create vaults.local.json in the repo root (git-ignored) listing your vault paths — ["/path/to/vault", …]. All entries are the default install targets of npm run build; the first entry doubles as the dev vault for npm run test. Machine-specific, never committed.

Development

npm install
npm run test        # unit tests (rule checker, report parser, diff) + full integration test
npm run build       # typecheck + bundle + install into the vaults listed in vaults.local.json
npm run dev         # watch mode

vaults.local.json (git-ignored) holds your local vault paths; without it, pass explicit vault paths to node scripts/install-to-vault.mjs <vault…> instead.

Source layout: rules (pure checker functions) · store (verdict state) · ingest (bridge protocol) · diff (LCS diff) · view (side panel) · fixmodal / adjustmodal · settings · i18n · main.

License

MIT

---

中文说明

AI 工作审核：在 Obsidian 里审核并批准 AI 对你笔记库的修改。面板顶部可在两种模式间切换（按 vault 记忆）：小说模式逐文件审核设定档案；开发模式扫描 docs/开发文档/<模块>/ 下的统一开发文档，需求阶段可点 通过 / 调整，对过代码以后可点 完结 / 缺陷 / 需求变更，变更合入文档后用 定稿 确认进入 变更中（该状态不能直接完结，避免跳过代码落地）。已修复的缺陷由 AI 汇入模块卡 缺陷史（症状 → 根因），开工 / 变更 / 交付前先读它做回归检查，防止旧缺陷复发；任务行与面板顶部会显示缺陷计数。公用概念（如本地货币）用 /dev-review 建卡 沉淀到 docs/公用配置/ 概念卡（定义可从对话或代码提炼），开发文档用 [[双链]] 引用，AI 以卡为准、不猜测；建卡时会把文档里的变体叫法统一成规范词。外部接口资料（网页 / 表格 / txt / word）用 /dev-review 接口摄取 规范化成 docs/接口文档/ 每服务一份总汇，接口变动 出字段级变动清单并可联动生成适配需求，接口比对 对照代码调用点找漂移。可复用组件用 /dev-review 组件解析 登记进 docs/组件文档/（双维标签 #能力/#场景，受控词表，Obsidian 可全局搜索，索引按能力分组），写 UI 前 组件查 标签优先定位、优先复用，避免重复造轮子；改组件或页面前 组件影响 代码反查受影响方出影响清单；业务文档的 [[页面]]/[[组件]] 双链构成 业务→页面→组件 分级影响链（改动可沿链定级，代码反查兜底）。代码项目的模板写在技能里，不往仓库落模板文件；未合并的旧 开发需求/ / 开发交付/ 仍可配对显示。

规则检查（模板完整性、草案标记、引用完整性、索引一致性、状态字段）在本地即时完成；AI 深度审核由终端里的智能体完成并把结构化报告写入 vault 根下的 .ai-review/ 桥接目录（对 Obsidian 检索隐藏）；修改稿必须经 diff 对照、你点击「应用替换」后才会写入原文件。你还可以在面板里对文件点「调整」写明不足点，意见同步给 AI 生成针对性修改稿——文件只有在你人工标记「通过」后才算定稿。

完整工作流、协议 schema、技能接入方式见上方英文文档；界面语言可在设置中切换（自动 / 中文 / English）。

本机开发：在仓库根建 vaults.local.json（不入库）列出你的 vault 路径，npm run build 会自动安装到其中全部 vault，首项兼作 npm run test 的开发 vault；临时目标用 node scripts/install-to-vault.mjs <vault…> 指定。