refactor: 用 DocGit 替换自定义版本系统 + Arranger 模块化拆分

- 移除自定义的 VersionMismatchError / HistoryEntry / Snapshot 版本追踪，改用 git 管理文档变更（DocGit: status/commit/blame）
- Arranger 从单文件拆分为 agentFactory / graphStore / pipeline / promptBuilder / runtime 等独立模块
- 简化 MCP mutation tools，移除 baseVersion 参数
- 新增 DocGitPanel 前端组件，移除 ConflictDialog / DiffView / HistoryPanel
- 新增项目级文档锁 docLock.ts

Author: Haruhiko-Joe

AGENTS.md

@@ -17,7 +17,7 @@ pnpm monorepo with two packages: root (backend) and `web/` (frontend).
 
 ### Backend: 4-Agent Pipeline
 
-The system generates interactive documentation for any code repository using a pipeline of 4 Codex agents orchestrated by the **Arranger** state machine:
+The system generates interactive documentation for any code repository using a pipeline of 4 agent roles orchestrated by the **Arranger** state machine:
 
 ```
 Scaffold → Checker → [per-module loop: Decomposer → Checker → Writer] → done
@@ -28,7 +28,7 @@ Scaffold → Checker → [per-module loop: Decomposer → Checker → Writer] 
 - **Writer**: Generates Markdown documentation for leaf `page` nodes
 - **Checker**: Validates graph structures from Scaffold and Decomposer (not Writer output); failures trigger retry via `agent.continue()`
 
-Each agent has both a Codex and Codex backend implementation, located in `src/agents/tsukai/` (e.g. `claudescaffold.ts` / `codexscaffold.ts`). All share identical interface: `run(prompt, workpath)`, `continue(prompt)`, `restore(sessionId, workpath)`, `getSessionId()`. A barrel file `src/agents/tsukai/index.ts` re-exports all classes.
+Each agent has both a Claude Code and Codex backend implementation, located in `src/agents/tsukai/` (e.g. `claudescaffold.ts` / `codexscaffold.ts`). All share identical interface: `run(prompt, workpath)`, `continue(prompt)`, `restore(sessionId, workpath)`, `getSessionId()`. A barrel file `src/agents/tsukai/index.ts` re-exports all classes.
 
 ### Arranger (`src/workflow/arranger.ts`)
 
@@ -45,7 +45,7 @@ All data structures use Zod schemas. The `Graph` type includes `decomposerSessio
 
 ### Incremental Update Pipeline (`src/workflow/updateOrchestrator.ts`)
 
-After initial generation, per-PR documentation updates are handled by the **PrUpdater** agent (Codex or Codex backend, `src/agents/tsukai/claudeprupdater.ts` / `codexprupdater.ts`). The orchestrator:
+After initial generation, per-PR documentation updates are handled by the **PrUpdater** agent (Claude Code or Codex backend, `src/agents/tsukai/claudeprupdater.ts` / `codexprupdater.ts`). The orchestrator:
 
 1. Discovers new merged PRs via `gh pr list` (fallback: `git log --first-parent`), sorted oldest-first by `mergedAt`
 2. Queues them as `TaskItem`s and processes sequentially under a per-project lock
@@ -63,10 +63,10 @@ API endpoints: `POST /api/update/{start,continue,skip,cancel}`, `POST /api/updat
 
 The `autodoc` MCP server exposes tools for agents to read/write doc artifacts:
 
-- **Query tools** (`src/mcp/tools/query.ts`): `list_projects`, `get_top`, `get_graph`, `get_page`, `search_nodes`, `list_source_files`, `read_source_files`, `list_docs`, `read_docs`, `list_history`, `get_history`
-- **Mutation tools** (`src/mcp/tools/mutate.ts`): `patch_page` (string match + replace), `update_page`, `update_node`, `update_graph_meta`, `create_node`, `delete_node` (preserves `.history` via `.tombstones/`), `update_top`, `revert`
+- **Query tools** (`src/mcp/tools/query.ts`): `list_projects`, `get_top`, `get_graph`, `get_page`, `search_nodes`, `list_source_files`, `read_source_files`, `list_docs`, `read_docs`
+- **Mutation tools** (`src/mcp/tools/mutate.ts`): `patch_page` (string match + replace), `update_page`, `update_node`, `update_graph_meta`, `create_node`, `delete_node`, `update_top`
 
-All write tools enforce optimistic locking via `baseVersion` (must match current `version` from read tools). The doc-drill skill template at `src/skill-template/SKILL.md` documents these tools for agent consumption.
+All write tools share the project-level document lock and only dirty the documentation working tree. Users commit accumulated doc changes manually through `/api/doc-git/commit`; blame data comes from `/api/doc-git/blame`. The doc-drill skill template at `src/skill-template/SKILL.md` documents the MCP tools for agent consumption.
 
 ### Frontend: Vue 3 + TypeScript
 
@@ -101,4 +101,4 @@ Project matching: `path.basename(repoPath)` maps to `web/doc/{name}/`. Re-runnin
 - The `codeScope` field on graph nodes tracks which source files/directories each module covers; child scopes must be subsets of parent scopes
 - `CheckerIssueType` enum: `broken-target`, `empty-content`, `invalid-path`
 - Task status lifecycle: `idle → running → done` (auto) or `idle → running → awaiting-review → done` (manual, with optional follow-up loops back to running)
-- Runtime logs go to `log/{project}.txt` (gitignored); JSONL mutation history in `src/souko/updateLog.ts`
+- Runtime logs go to `log/{project}.txt` (gitignored); PR update reports are appended through `src/souko/updateLog.ts`

CLAUDE.md

@@ -63,10 +63,10 @@ API endpoints: `POST /api/update/{start,continue,skip,cancel}`, `POST /api/updat
 
 The `autodoc` MCP server exposes tools for agents to read/write doc artifacts:
 
-- **Query tools** (`src/mcp/tools/query.ts`): `list_projects`, `get_top`, `get_graph`, `get_page`, `search_nodes`, `list_source_files`, `read_source_files`, `list_docs`, `read_docs`, `list_history`, `get_history`
-- **Mutation tools** (`src/mcp/tools/mutate.ts`): `patch_page` (string match + replace), `update_page`, `update_node`, `update_graph_meta`, `create_node`, `delete_node` (preserves `.history` via `.tombstones/`), `update_top`, `revert`
+- **Query tools** (`src/mcp/tools/query.ts`): `list_projects`, `get_top`, `get_graph`, `get_page`, `search_nodes`, `list_source_files`, `read_source_files`, `list_docs`, `read_docs`
+- **Mutation tools** (`src/mcp/tools/mutate.ts`): `patch_page` (string match + replace), `update_page`, `update_node`, `update_graph_meta`, `create_node`, `delete_node`, `update_top`
 
-All write tools enforce optimistic locking via `baseVersion` (must match current `version` from read tools). The doc-drill skill template at `src/skill-template/SKILL.md` documents these tools for agent consumption.
+All write tools share the project-level document lock and only dirty the documentation working tree. Users commit accumulated doc changes manually through `/api/doc-git/commit`; blame data comes from `/api/doc-git/blame`. The doc-drill skill template at `src/skill-template/SKILL.md` documents the MCP tools for agent consumption.
 
 ### Frontend: Vue 3 + TypeScript
 
@@ -101,4 +101,4 @@ Project matching: `path.basename(repoPath)` maps to `web/doc/{name}/`. Re-runnin
 - The `codeScope` field on graph nodes tracks which source files/directories each module covers; child scopes must be subsets of parent scopes
 - `CheckerIssueType` enum: `broken-target`, `empty-content`, `invalid-path`
 - Task status lifecycle: `idle → running → done` (auto) or `idle → running → awaiting-review → done` (manual, with optional follow-up loops back to running)
-- Runtime logs go to `log/{project}.txt` (gitignored); JSONL mutation history in `src/souko/updateLog.ts`
+- Runtime logs go to `log/{project}.txt` (gitignored); PR update reports are appended through `src/souko/updateLog.ts`

README.en.md

@@ -73,7 +73,7 @@ Paste a git URL in the frontend and generation begins. **For the full onboarding
 
 ### Codex Profile Configuration
 
-The Codex backend uses [profiles](https://developers.openai.com/codex/config-reference) per Agent role to isolate model parameters. Add one profile per role to `~/.codex/config.toml`. Names must be exactly `scaffold`, `decomposer`, `writer`, `checker`, `flowanalyzer`, `updater`:
+The Codex backend uses [profiles](https://developers.openai.com/codex/config-reference) per Agent role to isolate model parameters. Add one profile per role to `~/.codex/config.toml`. Names must be exactly `scaffold`, `decomposer`, `writer`, `checker`, `flowanalyzer`, `prupdater`, `knowledge`:
 
 ```toml
 [profiles.scaffold]
@@ -96,9 +96,13 @@ model_reasoning_effort = "high"
 model = "gpt-5.4"
 model_reasoning_effort = "medium"
 
-[profiles.updater]
+[profiles.prupdater]
 model = "gpt-5.4"
 model_reasoning_effort = "high"
+
+[profiles.knowledge]
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
 ```
 
 Replace models or tweak `model_reasoning_effort` / `service_tier` as needed. See the official [Config Reference](https://developers.openai.com/codex/config-reference) for all keys.
@@ -185,7 +189,7 @@ Each Agent role independently uses **Claude** (Claude Agent SDK) or **Codex** (O
 - **🔗 One-step git URL ingestion** — paste an SSH/HTTPS git URL; backend auto-clones, tracks the main branch head, keeps everything under `src/souko/`
 - **🔁 Per-PR incremental updates** — discovers all newly merged PRs via `gh pr list` (or `git log` fallback) and PrUpdater Agent navigates docs via MCP tools for targeted edits. Auto mode runs hands-free; Manual mode adds a review gate with session continuation for iterative refinement
 - **🛰️ HTTP MCP server** — same-process `/mcp` endpoint (Streamable HTTP) exposes the full query + mutate toolset for direct Code Agent access
-- **📜 Document version control** — every write carries optimistic locking (`baseVersion`) and snapshots to `.history/{file}.v{n}`; `revert` restores any historical version
+- **📜 Manual Git commits and blame** — doc writes only create uncommitted changes; the Git panel shows dirty status, commits manually, and surfaces Git blame in preview/editing views
 - **🔗 Interactive directed graphs** — [AntV G6](https://g6.antv.antgroup.com/) with 6 semantic edge types (calls, depends, data-flow, event, extends, composes) and hover popovers
 - **🔍 Progressive disclosure** — start at the top-level overview, drill into nodes down to leaf Markdown
 - **🔄 Interaction flow diagrams** — cross-module business flows auto-extracted and rendered as sequence diagrams with participants, steps, and code references
@@ -199,7 +203,7 @@ Each Agent role independently uses **Claude** (Claude Agent SDK) or **Codex** (O
 
 The backend exposes an MCP server named `autodoc` at `http://localhost:3100/mcp` as a stateless Streamable HTTP transport. All tools operate on real files under `src/souko/doc/{project}/`.
 
-### Wire it up in Claude Code
+### Wire it up in Claude Code / Codex
 
 Drop an `.mcp.json` into the target repo root:
 
@@ -214,6 +218,14 @@ Drop an `.mcp.json` into the target repo root:
 }
 ```
 
+Codex uses project-scoped `.codex/config.toml`; autoDoc writes the equivalent config when assembling the skill:
+
+```toml
+[mcp_servers.autodoc]
+url = "http://localhost:3100/mcp"
+enabled_tools = ["list_projects", "get_top", "get_graph", "get_page", "search_nodes", "list_source_files", "read_source_files", "list_docs", "read_docs", "patch_page", "update_page", "update_node", "update_graph_meta", "create_node", "delete_node", "update_top"]
+```
+
 The matching [doc-drill skill](src/skill-template/SKILL.md) is a thin instruction set that only describes **how to call the MCP tools**, and ships with autoDoc.
 
 ### Tool list
@@ -222,15 +234,15 @@ The matching [doc-drill skill](src/skill-template/SKILL.md) is a thin instructio
 
 | Tool | Purpose |
 |---|---|
-| `list_projects` | List all registered projects (with sourceUrl / head / lastUpdated) |
-| `get_top` | Read a project's top.json (with `version`) |
-| `get_graph` | Read a sub-graph (with `version` and the `pageVersions` map) |
-| `get_page` | Read a leaf Markdown page (with its `version`) |
+| `list_projects` | List available doc projects (name / description) |
+| `get_top` | Read a project's top.json |
+| `get_graph` | Read a sub-graph with `codeScope`, `nodes`, and `description` |
+| `get_page` | Read a leaf Markdown page |
 | `search_nodes` | Search node names/descriptions across all levels |
-| `list_history` | List all historical versions of a file |
-| `get_history` | Read a specific historical version |
+| `list_source_files` / `read_source_files` | Locate and read source files by regex |
+| `list_docs` / `read_docs` | Batch-list/read raw docs by nodeId |
 
-#### Mutate (optimistic lock via `baseVersion`)
+#### Mutate (serialized by project lock)
 
 | Tool | Purpose |
 |---|---|
@@ -240,10 +252,9 @@ The matching [doc-drill skill](src/skill-template/SKILL.md) is a thin instructio
 | `update_node` | Update a node's name / description / codeScope / edges in its parent graph |
 | `delete_node` | Remove a node from its parent graph (page deletes the md; graph recursively deletes its subtree) |
 | `patch_page` | Targeted string-match-and-replace edits to a leaf md, more efficient and safer than update_page |
-| `update_page` | Overwrite a leaf md; uses `pageVersions[ref]` as baseVersion |
-| `revert` | Write a historical version back as a new version, keeping intermediate versions intact |
+| `update_page` | Overwrite a leaf md |
 
-Write flow: **read → obtain version → write with baseVersion → server snapshots the old version to `.history/` → version+1 → persist**. A version mismatch returns `VersionMismatch` so the client re-reads and retries.
+Write flow: **read → mutate tools dirty the working tree → review dirty status in the frontend Git panel → user commits manually**. Mutate tools no longer accept `baseVersion` and never auto-commit; concurrent writes are serialized by the project-level lock.
 
 > ⚠️ `/mcp` is unauthenticated and CORS-open by default. Add access control or bind to loopback before production use.
 
@@ -263,7 +274,6 @@ src/souko/
     │   ├── flows.json
     │   ├── {Module}/
     │   │   ├── {Module}.json
-    │   │   ├── .history/        # Historical snapshots
     │   │   ├── {Leaf}.md
     │   │   └── {SubModule}/...
     │   └── ...
@@ -274,19 +284,19 @@ src/souko/
 
 Each module's documentation is a self-contained unit. Three ways to edit it:
 
-- **Via MCP tools** (recommended): `update_node` / `update_page` / `create_node` / `delete_node` — automatic version tracking and history snapshots; ideal for Code Agents
-- **Direct file edits**: edit `.md` / `.json` under `src/souko/doc/{project}/`; restart the server to pick it up (bypasses version control)
+- **Via MCP tools** (recommended): `update_node` / `update_page` / `create_node` / `delete_node` — writes dirty the doc working tree and wait for a manual commit in the frontend Git panel
+- **Direct file edits**: edit `.md` / `.json` under `src/souko/doc/{project}/`; refresh to pick it up and show it as uncommitted
 - **Trigger an incremental update**: click the Update button on the home page; PrUpdater Agent automatically discovers all newly merged PRs and processes them one by one. Manual mode gates each PR behind a review confirmation
 
 ## doc-drill: Native Code Agent Integration
 
-autoDoc installs the thin [doc-drill](src/skill-template/SKILL.md) skill into the target repo's `.claude/skills/doc-drill/` and writes an `.mcp.json` pointing at the local MCP server. Any Code Agent can then:
+autoDoc installs the thin [doc-drill](src/skill-template/SKILL.md) skill into the target repo's `.claude/skills/doc-drill/`, then writes Claude Code's `.mcp.json` and Codex's `.codex/config.toml` to point at the local HTTP MCP server. Any Code Agent can then:
 
 - **Browse progressively** — `list_projects` → `get_top` → `get_graph` → `get_page`, lazy-loaded, context-efficient
 - **Trace relationships** — follow the 6 semantic edge types to trace call chains and data flows
 - **Keyword search** — `search_nodes` across all doc layers
 - **Navigate business flows** — understand end-to-end interactions via `flows.json`
-- **Maintain directly** — edit docs in place via mutate tools, and use `list_history` / `revert` to inspect or roll back
+- **Maintain directly** — edit docs in place via mutate tools, then let the user commit from autoDoc's frontend Git panel
 
 > This Agent-native integration is something DeepWiki (web chat only) and Google Code Wiki (web browsing only) do not offer.
 
@@ -316,8 +326,9 @@ autoDoc/
 │   │   └── projects.json         # gitignored: shared registry
 │   ├── mcp/                      # HTTP MCP server (same process as HTTP API)
 │   │   ├── server.ts             # buildMcpServer(store)
-│   │   ├── docStore.ts           # doc read/write + version + .history snapshots
-│   │   ├── schema.ts             # Zod schemas (with version / pageVersions)
+│   │   ├── docStore.ts           # doc read/write + project-level lock
+│   │   ├── docGit.ts             # doc Git status / commit / blame
+│   │   ├── schema.ts             # Zod schemas
 │   │   └── tools/{query,mutate}.ts
 │   ├── agents/                   # Agent implementations (Claude + Codex)
 │   │   ├── tsukai/               # All Agent classes (barrel: index.ts)