ai-dev-analytics 1.1.5 → 1.1.6

package/README.md

@@ -2,516 +2,560 @@
 
 # AIDA
 
-### Make Vibe Coding Measurable.
+### 让 Vibe Coding 数据化。
 
-Every vibe coding session generates massive insights — deviations, patterns, quality signals.<br>
-*But you close the terminal, and all of it vanishes. Next session, you start blind again.*<br>
-**AIDA captures structured data at every development checkpoint, visualizes it in a live dashboard, and distills deviation patterns into rules that make your AI write better code — every single run.**
+每一次 Vibe Coding 都在产生大量信号 —— 偏差、模式、质量数据。<br>
+*但你关掉终端，这些全部消失。下次对话，继续盲写。*<br>
+**AIDA 在每个开发节点采集结构化数据，用看板可视化，再把偏差规律沉淀成规则 —— 让你的 AI 每次运行都写出更符合预期的代码。**
 
-One line to integrate. Zero workflow changes.
+一行配置接入，零工作流改变。
 
 ```json
-{ "mcpServers": { "aida": { "command": "npx", "args": ["-y", "ai-dev-analytics", "mcp"] } } }
+{ "mcpServers": { "aida": { "command": "npx", "args": ["--registry=https://registry.npmjs.org/", "-y", "ai-dev-analytics", "mcp"] } } }
 ```
 
-[![npm version](https://img.shields.io/badge/npm-v1.1.3-0066ff)](https://www.npmjs.com/package/ai-dev-analytics)
+[![npm version](https://img.shields.io/badge/npm-v1.1.6-0066ff)](https://www.npmjs.com/package/ai-dev-analytics)
 [![license](https://img.shields.io/github/license/LWTlong/ai-dev-analytics?color=%23333)](./LICENSE)
 [![node](https://img.shields.io/node/v/ai-dev-analytics?color=%23339933)](https://nodejs.org)
-[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#testing)
-[![Live Demo](https://img.shields.io/badge/🎯_Live_Demo-Interactive_Dashboard-FF4B4B)](https://lwtlong.github.io/ai-dev-analytics/)
+[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#测试)
+[![在线 Demo](https://img.shields.io/badge/🎯_在线Demo-交互式看板-FF4B4B)](https://lwtlong.github.io/ai-dev-analytics/)
 [![ai-dev-analytics MCP server](https://glama.ai/mcp/servers/LWTlong/ai-dev-analytics/badges/score.svg)](https://glama.ai/mcp/servers/LWTlong/ai-dev-analytics)
 
 [![ai-dev-analytics MCP server](https://glama.ai/mcp/servers/LWTlong/ai-dev-analytics/badges/card.svg)](https://glama.ai/mcp/servers/LWTlong/ai-dev-analytics)
 
-[One-Line Setup](#-30-second-setup) · [Data-Driven Loop](#-the-data-driven-loop) · [Dashboard](#-the-dashboard) · [SOP Workflow](#-standardized-ai-development-workflow) · [Data for Reports](#-data-sedimentation--performance-reports) · [Commands](./COMMANDS.md) · [Docs](./docs/INDEX.md) · [中文文档](./README.zh-CN.md)
+[一行接入](#-30-秒上手) · [场景操作指南](#-场景操作指南) · [数据驱动闭环](#-数据驱动闭环) · [命令速览](#-命令速览) · [重复执行与覆盖策略](#-重复执行与覆盖策略) · [规则去重与冲突判断](#-规则去重与冲突判断) · [命令文档](./COMMANDS.md) · [文档导航](./docs/INDEX.md) · [English](./README.en.md)
 
 </div>
 
 ---
 
-## The Insight
+## 一个洞察
 
-Vibe coding is powerful. But it's a black box.
+Vibe Coding 很强。但它是一个黑箱。
 
-You tell Claude to build a feature. It writes code. You ship it. But you have **zero visibility** into what actually happened:
+你让 Claude 写一个功能，它写了，你 ship 了。但你对过程**零可见性**：
 
-- How many tasks did AI complete? How long did each take?
-- Where did AI deviate from your project conventions? Why?
-- Which deviations keep recurring? What rules would prevent them?
-- What's the bug rate? Which phases produce the most bugs?
+- AI 完成了多少任务？每个任务花了多长时间？
+- AI 在哪里偏离了你的项目规范？为什么？
+- 哪些偏差反复出现？加什么规则能根治？
+- Bug 率多少？哪个阶段产出最多 Bug？
 
-Without data, you can't improve. You're just vibing — over and over, with the same blind spots.
+没有数据，你就无法改进。你只是在一遍又一遍地 vibe —— 带着同样的盲区。
 
-**AIDA makes the invisible visible.** It collects structured data from every vibe coding session, renders it in a real-time dashboard, and turns deviation patterns into project rules. Your AI doesn't just code — it **learns your project**.
+**AIDA 让不可见变可见。** 它在每次 vibe coding 过程中采集结构化数据，用实时看板渲染，再把偏差模式沉淀成项目规则。你的 AI 不再只是写代码 —— 它**学习你的项目**。
 
 ---
 
-## 🔄 The Data-Driven Loop
+## 🔄 数据驱动闭环
 
-This is the core of AIDA — **data in, rules out, better code next time.**
+这是 AIDA 的核心 —— **数据进来，规则出去，代码越来越好。**
 
 ```
-Vibe Coding Session
+Vibe Coding 过程
         ↓
-   AIDA silently collects structured data
-   (tasks, deviations, bugs, reviews, files, timeline)
+   AIDA 静默采集结构化数据
+   （任务、偏差、Bug、自检、文件变更、时间线）
         ↓
-   Dashboard visualizes patterns
-   "9 deviations → 56% hallucination, 44% rule-missing"
+   看板可视化呈现规律
+   "9 个偏差 → 56% 幻觉, 44% 规则缺失"
         ↓
-   Deviation patterns identified → AI suggests rules → user confirms → sedimented
-   .aida/rules.json ← your AI's growing knowledge base
+   发现偏差规律 → AI 建议沉淀规则 → 用户确认 → 写入规则库
+   .aida/rules.json ← 你的 AI 知识库在成长
         ↓
-   AI reads rules next session → same mistakes eliminated
+   AI 下次读取规则 → 同样的错误被消除
         ↓
-   Repeat — each cycle, AI output gets closer to your expectations
+   循环往复 —— 每一轮，AI 输出都更接近你的预期
 ```
 
-**Real data from a production project:**
+**来自真实生产项目的数据：**
 
-| Run | Deviations | What happened | Rules sedimented |
-|-----|-----------|---------------|-----------------|
-| #1 | 23 deviations across 47 tasks | AI misused components, wrong layouts, incorrect API patterns | 6 project-specific rules |
-| #2 | **0 repeat deviations** | AI read the rules. Same patterns — zero errors. | — |
+| 运行 | 偏差情况 | 发生了什么 | 沉淀的规则 |
+|------|---------|-----------|-----------|
+| 第 1 轮 | 47 个任务产生 23 个偏差 | AI 组件用错、布局写反、API 模式不对 | 沉淀 6 条项目专属规则 |
+| 第 2 轮 | **零重复偏差** | AI 读了规则，相同模式的错误归零 | — |
 
-**Step 1: See *why* AI deviates** — Root cause breakdown reveals whether issues stem from hallucination, missing rules, or insufficient context.
+**第一步：看清 AI *为什么*出错** —— 根因分布一目了然：是 AI 幻觉、规则缺失、还是上下文不足？
 
-![Deviation Root Cause](https://raw.githubusercontent.com/LWTlong/ai-dev-analytics/main/docs/deviation-root-cause.png)
+![偏差根因分布](https://raw.githubusercontent.com/LWTlong/ai-dev-analytics/main/docs/deviation-root-cause.png)
 
-**Step 2: See *where* AI deviates** — Category distribution pinpoints the exact areas: UI spacing, layout, component usage, API patterns.
+**第二步：看清 AI *在哪*出错** —— 类别分布精准定位：UI 间距、布局结构、组件使用、API 模式。
 
-![Deviation Category Distribution](https://raw.githubusercontent.com/LWTlong/ai-dev-analytics/main/docs/deviation-category.png)
+![偏差类别分布](https://raw.githubusercontent.com/LWTlong/ai-dev-analytics/main/docs/deviation-category.png)
 
-**Step 3: Watch rules compound** — As rules accumulate (green line), the same deviation patterns stop recurring.
+**第三步：看规则的复利效应** —— 随着规则积累，重复偏差会逐步下降。
 
-![Deviation & Rule Trend](https://raw.githubusercontent.com/LWTlong/ai-dev-analytics/main/docs/deviation-rule-trend.png)
+![偏差与规则趋势](https://raw.githubusercontent.com/LWTlong/ai-dev-analytics/main/docs/deviation-rule-trend.png)
 
-The `.aida/rules.json` file is your **project-specific AI knowledge base**. It grows with every run. The more you use AI, the smarter it gets at *your* project.
+`.aida/rules.json` 就是你的**项目专属 AI 知识库**。用 AI 写得越多，它对*你的项目*就越懂。
 
 ---
 
-## 📊 The Dashboard
+## 📊 数据看板
 
-**Your entire vibe coding process — structured, visualized, actionable.**
+**你的整个 Vibe Coding 过程 —— 结构化、可视化、可操作。**
 
 ![Dashboard](https://raw.githubusercontent.com/LWTlong/ai-dev-analytics/main/docs/dashboard.png)
 
-> **[Live Demo →](https://lwtlong.github.io/ai-dev-analytics/)** Real anonymized project data. No install needed.
+> **[在线 Demo →](https://lwtlong.github.io/ai-dev-analytics/)** 真实脱敏数据，无需安装。
 
-AIDA captures every dimension of AI-assisted development and turns it into interactive charts:
+AIDA 全方位采集 AI 辅助开发的每个维度，转化为交互式图表：
 
-| What you see | Why it matters |
+| 你能看到什么 | 为什么重要 |
 |---|---|
-| **Deviation root cause breakdown** | Know *why* AI fails — rule-missing? hallucination? context gap? |
-| **Deviation category distribution** | Know *where* AI fails — layout? components? API? |
-| **Deviation & rule trend over time** | Watch deviations drop as rules accumulate |
-| **Bug severity distribution** | Track quality — which phases produce critical bugs? |
-| **Self-review pass rate trend** | Is AI code getting better or worse over time? |
-| **Task completion by phase** | See progress across the full development lifecycle |
-| **File modification hotspots** | Which files keep getting changed? Where are the pain points? |
-| **Rules table with source mapping** | Every rule links back to the deviation that created it |
-| **Full development timeline** | Every task, bug, review, deviation — chronologically |
-| **Project overview (team view)** | Cross-branch stats, developer comparison, requirement status |
+| **偏差根因分布** | 知道 AI *为什么*出错 —— 规则缺失？幻觉？上下文不足？ |
+| **偏差类别分布** | 知道 AI *在哪*出错 —— 布局？组件？API？ |
+| **偏差 & 规则趋势图** | 看着偏差随规则积累而下降 |
+| **Bug 严重度分布** | 追踪质量 —— 哪个阶段产出严重 Bug？ |
+| **自检通过率趋势** | AI 代码质量是在变好还是变差？ |
+| **各阶段任务完成** | 看到完整开发生命周期的进度 |
+| **文件修改热点** | 哪些文件反复被改？痛点在哪？ |
+| **规则溯源表** | 每条规则都关联到产生它的偏差 |
+| **完整开发时间线** | 每个任务、Bug、审查、偏差 —— 按时间排列 |
+| **项目总览（团队视角）** | 跨分支统计、开发者对比、需求状态 |
 
-Every KPI card is clickable — drill down into task details, deviation root causes, review reports, and file changes.
+运行 `npx ai-dev-analytics dashboard`，几秒钟看到**你自己项目的数据**。
 
-Run `npx ai-dev-analytics dashboard` to see **your own project's data** in seconds.
+### 🔒 100% 本地。零外部请求。
 
-### 🔒 100% Local. Zero External Requests.
-
-AIDA stores JSON source data in `.aida/` and generates any required AI tool config or readable views inside the current project only. **The codebase contains zero HTTP calls to external services** — no telemetry, no cloud sync, no analytics, no tracking. Zero runtime dependencies. Your code and data never leave your machine. Period.
-
-## Command Reference
-
-Detailed CLI usage, command behavior, supported AI tools, merge/import/build flow, and migration notes are documented in [COMMANDS.md](./COMMANDS.md).
-
-## Documentation
-
-For public documentation navigation, schema references, workflow notes, and dashboard-related docs, see [docs/INDEX.md](./docs/INDEX.md).
+AIDA 只往项目里的 `.aida/` 目录写 JSON 文件。**整个代码库不包含任何外部 HTTP 请求** —— 不发遥测、不上传云端、不请求分析服务、不做任何追踪。你的代码和数据不会离开你的电脑。
 
 ---
 
-## ⚡ 30-Second Setup
-
-The Chinese README, [README.zh-CN.md](./README.zh-CN.md), is the primary documentation. This English file is kept as a reference.
+## ⚡ 30 秒上手
 
-### Add one MCP config inside the project — that's the entire integration.
+### 在 `.mcp.json` 里加一行
 
 ```json
-{ "mcpServers": { "aida": { "command": "npx", "args": ["-y", "ai-dev-analytics", "mcp"] } } }
+{ "mcpServers": { "aida": { "command": "npx", "args": ["--registry=https://registry.npmjs.org/", "-y", "ai-dev-analytics", "mcp"] } } }
 ```
 
-No SDK. No wrapper. No code changes. Add this to your project root `.mcp.json`, and AIDA starts collecting data the next time your AI writes code. It works silently — zero workflow changes.
-
-Current policy: **all tool configs, rules, skills, and MCP entry files stay inside the current project only**. AIDA no longer writes Codex or other tool config to global locations outside the project.
+不需要 SDK，不需要包装器，不需要改代码。把这行加到项目根目录的 `.mcp.json`，AI 下次写代码时 AIDA 就开始采集数据。
 
-> *Tip: If `npx` is slow, install globally first: `npm install -g ai-dev-analytics`, then change the command to `"aida"`. Global install also gives you the `aida` CLI command (e.g. `aida dashboard`, `aida init`).*
+> 如果 `npx` 较慢，可以先全局安装：`npm install -g ai-dev-analytics`，然后把 command 改成 `"aida"`。全局安装后也可以直接使用 `aida` 命令。
 
 <details>
-<summary>Cursor / VS Code Copilot / Windsurf / Lingma</summary>
+<summary>Cursor / VS Code Copilot / Windsurf / Lingma 配置</summary>
 
-**Cursor** `.cursor/mcp.json`:
+**Cursor** `.cursor/mcp.json`：
 ```json
 {
   "mcpServers": {
     "aida": {
       "command": "npx",
-      "args": ["-y", "ai-dev-analytics", "mcp"]
+      "args": ["--registry=https://registry.npmjs.org/", "-y", "ai-dev-analytics", "mcp"]
     }
   }
 }
 ```
 
-**VS Code Copilot** `.vscode/mcp.json`:
+**VS Code Copilot** `.vscode/mcp.json`：
 ```json
 {
   "servers": {
     "aida": {
       "command": "npx",
-      "args": ["-y", "ai-dev-analytics", "mcp"]
+      "args": ["--registry=https://registry.npmjs.org/", "-y", "ai-dev-analytics", "mcp"]
     }
   }
 }
 ```
 
-**Windsurf** project-local MCP config file:
+**Windsurf** `~/.codeium/windsurf/mcp_config.json`：
 ```json
 {
   "mcpServers": {
     "aida": {
       "command": "npx",
-      "args": ["-y", "ai-dev-analytics", "mcp"]
+      "args": ["--registry=https://registry.npmjs.org/", "-y", "ai-dev-analytics", "mcp"]
     }
   }
 }
 ```
 
-**Lingma (通义灵码)** `.lingma/mcp.json`:
+**Lingma（通义灵码）** `.lingma/mcp.json`：
 ```json
 {
   "mcpServers": {
     "aida": {
       "command": "npx",
-      "args": ["-y", "ai-dev-analytics", "mcp"]
+      "args": ["--registry=https://registry.npmjs.org/", "-y", "ai-dev-analytics", "mcp"]
     }
   }
 }
 ```
 </details>
 
-### See your data
+### 打开看板
 
 ```bash
 npx ai-dev-analytics dashboard
 ```
 
-Open `http://localhost:2375` — real-time updates via SSE, Chinese/English toggle built in.
+打开 `http://localhost:2375`，即可查看本地数据看板。
 
 ---
 
-## 🤔 Why Data Changes Everything
+## 🧭 场景操作指南
 
-**Without data, every vibe coding session starts from zero. With data, each one builds on the last.**
+下面这些是最常见的落地场景。想看详细行为、重复执行语义和边界说明，直接跳到 [COMMANDS.md](./COMMANDS.md)。
 
-| Vibing blind | Vibing with data |
-|---|---|
-| "AI keeps getting layouts wrong" | Dashboard shows: 9 layout deviations, root cause 56% hallucination + 44% rule-missing. 4 rules sedimented → zero repeats next run |
-| "I corrected this three times already" | AIDA recorded the deviation pattern. AI detected `rule-missing`, suggested a rule, you confirmed — AI reads it every session, you never correct it again |
-| "That feature had a lot of bugs" | 5 bugs, 3 critical — all concentrated in one phase. Now you know where to add guardrails |
-| "What did I even do this quarter?" | 47 tasks, 23 deviations fixed, 6 rules sedimented, 4064 lines. Export → H1 performance review done |
+### 1. 新项目初始化
 
-**Vibe coding without data is just vibing. Add data, and it becomes a compounding system.**
+详细步骤见：[COMMANDS.md / 场景 1：新项目初始化](./COMMANDS.md#场景-1新项目初始化)
 
----
+适用场景：
 
-## 🎯 Use Cases
+- 仓库里还没有 `.aida`
+- 想从零接入 AIDA
 
-**Vibe Coder — "I want my AI to actually learn my project"**
-> You've been using Claude Code for a week. AIDA's dashboard shows: 23 deviations, concentrated in `component-usage` and `layout` categories, root cause mostly `rule-missing`. AI detects the patterns and suggests rules — you confirm, 6 project rules sedimented. Next week, those categories show zero deviations. Your AI now knows your project conventions.
+操作：
 
-**Tech Lead — "I need to see what AI is actually doing across the team"**
-> Team of 4 uses Claude Code daily. Open the project overview: Developer A has 2 deviations + 5 sedimented rules (AI is learning). Developer B has 15 deviations + 0 rules (AI is not learning). The data tells you exactly where to intervene.
+```bash
+aida init
+```
 
-**Senior Engineer — "Show me the data for my performance review"**
-> End of H1. Open the dashboard: 150 tasks across 3 features, 89% first-pass review rate, 12 rules sedimented that now benefit the entire team. All structured data — export it, attach it to your review doc. Data beats "I think I did a lot."
+你会在交互里选择：
 
-**Team adopting vibe coding — "How do we go from chaotic to systematic?"**
-> Start collecting data. After 2 weeks, the dashboard shows clear patterns: which types of tasks AI handles well, where it consistently deviates, what rules are needed. You go from "AI sometimes works" to "AI works predictably because we've taught it our conventions."
+- `collect` 或 `full` 模式
+- 需要接入的 AI 工具
+- 是否导入现有工具的规则 / skills 作为 baseline
 
----
+初始化后建议立即检查：
+
+```bash
+aida build
+aida status
+```
+
+### 2. 老项目迁移到 AIDA
+
+详细步骤见：[COMMANDS.md / 场景 2：老项目迁移](./COMMANDS.md#场景-2老项目迁移)
 
-## 📁 Data Sedimentation & Performance Reports
+适用场景：
 
-AIDA doesn't just visualize — it **sediments**. Every run accumulates structured data that compounds over time.
+- 项目还在使用旧 `.aidevos`
+- 想把旧 rules / skills / run 数据迁进当前 AIDA 体系
 
+最省事的方式：
+
+```bash
+aida migrate-legacy
 ```
-Week 1:  47 tasks, 23 deviations, 5 bugs, 6 rules, 4064 lines
-Week 4:  180+ tasks, deviation rate dropping, 15 rules, full quality history
-Quarter: Complete development record — exportable, analyzable, presentable
+
+如果你想显式指定 baseline tool：
+
+```bash
+aida migrate-legacy cursor
+aida migrate-legacy codex
 ```
 
-**What you can do with sedimented data:**
+如果你想拆开执行：
 
-| Scenario | What you get |
-|----------|-------------|
-| **H1 / H2 Performance Review** | Tasks completed, quality metrics (pass rate, bug rate), code volume, rules contributed — all with numbers, not feelings |
-| **Annual Summary** | Cross-project trends, deviation patterns over time, rule growth curve, total output |
-| **Sprint Retrospective** | What went wrong, what rules were added, which phases improved, measurable quality delta |
-| **Team Leader Report** | Per-developer stats, deviation hotspots, which modules need better rules, team-wide AI maturity |
-| **Project Handover** | Full development history — someone new can see exactly what happened, what rules exist, and why |
+```bash
+aida migrate-dir
+aida import cursor
+aida migrate
+aida memory rebuild
+aida build
+```
 
-All data is structured JSON in `.aida/`. No vendor lock-in. Export it, query it, pipe it into any reporting tool. Run `aida report` to generate a summary at any time.
+### 3. 已经初始化过，但产物缺失或版本升级后想补齐
 
----
+详细步骤见：[COMMANDS.md / 场景 3：项目已初始化，但想补齐缺失产物](./COMMANDS.md#场景-3项目已初始化但想补齐缺失产物)
+
+适用场景：
 
-## ⚙️ How It Works
+- `AGENTS.md` / `CLAUDE.md` / `.codex/config.toml` 被删了
+- 旧版本包生成不完整
+- 发新包后想在老项目里补齐生成产物
 
-```mermaid
-flowchart LR
-    A["Your AI Tool\nClaude Code / Cursor"] -->|Vibe Coding| B{"AIDA MCP Server\n10 Tools"}
-    B -->|Silent Data Collection| C[".aida/run.json"]
-    C -->|Visualization| D["Dashboard\nlocalhost:2375"]
-    C -->|Pattern Analysis| E[".aida/rules.json"]
-    E -->|AI Reads Rules| A
+操作：
+
+```bash
+aida init
 ```
 
-Your AI tool calls AIDA's MCP tools automatically as it works. You don't invoke them manually. No prompts to write, no scripts to run — just vibe code as usual.
+然后在交互里选：
 
-<details>
-<summary>📋 10 MCP Tools (auto-collected)</summary>
-
-| Tool | What it captures |
-|------|-----------------|
-| `aida_task_start` | Task begins — ID, title, stage, PRD phase |
-| `aida_task_done` | Task completed — duration auto-calculated |
-| `aida_log_bug` | Bug found — severity, title, related files |
-| `aida_bug_fix` | Bug fixed — links fix to original bug |
-| `aida_log_review` | Code self-review — pass/fail, issue list |
-| `aida_log_deviation` | AI output ≠ expectation — root cause, category |
-| `aida_log_files` | File changes — auto-scans `git diff`, zero args needed |
-| `aida_highlight` | Notable achievement worth recording |
-| `aida_status` | Current run status snapshot |
-| `aida_log_rule` | Sediment project rule — user confirms, then AI calls this tool |
+- `Repair missing generated files`
 
-</details>
+或者直接跑：
+
+```bash
+aida build
+aida migrate-legacy
+```
 
-### Data Model
+其中：
 
-All data is local JSON. No database, no cloud.
+- `aida build` 适合“真源没问题，只想重建产物”
+- `aida migrate-legacy` 适合“历史项目想顺手补齐 memory / import / build 全链路”
 
-| Level | File | What it contains |
-|-------|------|-----------------|
-| **Run** | `.aida/runs/{branch}/{dev}/run.json` | Every task, bug, deviation, review, file change |
-| **Branch** | `.aida/runs/{branch}/requirement.json` | Requirement and branch-level aggregate data |
-| **Project** | `.aida/index.json` | Cross-branch overview for team leads |
-| **Rules** | `.aida/rules.json` | Sedimented project rules — your AI's growing knowledge base |
+### 4. 已有工具规则想回收进 `.aida/*.json`
 
-All structured JSON — ready for export, analysis, or feeding into reports.
+详细步骤见：[COMMANDS.md / 场景 4：import 和 build 怎么配合](./COMMANDS.md#场景-4import-和-build-怎么配合)
 
----
+适用场景：
 
-## 🚀 Standardized AI Development Workflow
+- 项目里已经有 `.cursor/`、`.claude/`、`.codex/` 本地规则
+- 想把分散资产统一回收到 `.aida/rules.json` / `.aida/skills.json`
 
-Beyond data collection, AIDA provides a **complete SOP for AI-assisted development** — a standardized workflow that turns chaotic vibe coding into a repeatable, measurable process.
+操作：
 
 ```bash
-aida init    # Select "Full workflow"
-aida start   # Create a development run
+aida import
+aida import cursor
+aida import codex
 ```
 
-This enables **14 AI Skills** orchestrated as a full development pipeline:
+经验上：
 
-```
-PRD Ingestion → Requirement Analysis → Task Decomposition
-        ↓
-Code Generation → Self-Review → Bug Fix → Deviation Fix
-        ↓
-Data Collection → Pattern Analysis → Rule Sedimentation
-        ↓
-Next Run: AI reads rules → better output → fewer deviations
+- 无参数 `import`：适合把当前项目里能发现的资产统一扫回 AIDA
+- 带 baseline tool：适合你明确知道“以某个工具的资产为准”
+
+回收后建议再跑一次：
+
+```bash
+aida build
 ```
 
-| Phase | What AI does | What AIDA records |
-|-------|-------------|-------------------|
-| **Requirement** | Parses PRD, extracts modules and phases | PRD phases, scope |
-| **Task Split** | Breaks requirements into atomic tasks | Task list, stages, estimates |
-| **Code Gen** | Generates code per task | Files changed, lines added, duration |
-| **Self-Review** | Reviews its own output against conventions | Pass/fail, issue list, quality score |
-| **Bug Fix** | Fixes bugs found during review | Bug severity, fix details, related files |
-| **Deviation Fix** | Corrects output that doesn't match expectations | Root cause, category, new rule (when root cause is rule-missing) |
+### 5. rules 冲突
 
-Every step produces structured data. Every deviation can become a rule. The SOP ensures nothing falls through the cracks — and the data makes the whole process visible and improvable.
+详细步骤见：[COMMANDS.md / 场景 5：rules 冲突](./COMMANDS.md#场景-5rules-冲突)
 
----
+适用场景：
 
-<details>
-<summary>🖥 CLI Reference</summary>
+- `git pull` / `git merge` 后 `.aida/rules.json` 出现 conflict marker
+
+操作：
 
 ```bash
-aida init              # Interactive project setup
-aida migrate-legacy    # Upgrade legacy .aidevos project in one command
-aida start             # Create a new development run
-aida status            # Show current run status
-aida dashboard         # Launch dashboard (default port 2375)
-aida dashboard --port 3000 # Custom port
-aida mcp               # Start MCP server (for AI tool config)
-aida log <subcommand>  # Write structured data (task, bug, review, etc.)
-aida memory <subcommand> # Rebuild/search/show project memory
-aida reindex           # Rebuild project-level index
-aida report            # Generate performance report
-aida rules build       # Generate rule view files from registry
-aida rules dedupe      # Find and remove near-duplicate rules
-aida rules merge       # Merge rules from parallel branches
-aida update            # Update skills to latest version
-aida migrate           # Migrate old data to current schema
-```
-
-`aida init` and `aida build` now use interactive multi-select prompts in TTY terminals, with automatic fallback to comma-separated numeric input in non-interactive environments.
+aida rules merge
+```
 
-</details>
+如果你想顺手把 `skills.json` 也一起处理：
 
-<details>
-<summary>🔌 MCP Integration Details</summary>
+```bash
+aida merge
+```
 
-AIDA uses [Model Context Protocol](https://modelcontextprotocol.io/) — the standard way for AI tools to interact with external systems. The MCP server runs over stdio with zero dependencies.
+然后建议检查：
 
-**What happens when you add the config:**
+```bash
+aida rules dedupe
+aida build
+```
 
-1. Your AI tool discovers AIDA's data + memory tools via MCP
-2. As the AI works, it naturally calls `aida_task_start`, `aida_log_files`, etc.
-3. Data flows into `run.json` silently
-4. Deviation patterns emerge → AI suggests rules → user confirms → sedimented
-5. AI reads rules next session → output quality improves
+### 6. skills 冲突
 
-**No prompts to write. No scripts to run. No workflow to learn.**
+详细步骤见：[COMMANDS.md / 场景 6：skills 冲突](./COMMANDS.md#场景-6skills-冲突)
 
-</details>
+适用场景：
 
----
+- `.aida/skills.json` 出现 conflict marker
 
-## 📐 Rules System — Team Workflow
+操作：
 
-Rules are the compounding asset of AIDA. Here's how they work in a team setting.
+```bash
+aida merge
+```
 
-### Architecture
+或者只处理 skills：
 
+```bash
+aida skills merge
 ```
-.aida/rules.json                ← rules source of truth, committed to git
-.aida/skills.json               ← skills source of truth, committed to git
-.aida/config.json               ← project config source of truth, committed to git
-.aida/memories/index.json       ← module memory index, committed to git
-.aida/memories/modules/*.json   ← module memory source, committed to git
-.aida/runs/*/requirement.json   ← requirement history source, committed to git
-.aida/runs/*/context.json       ← branch context source, committed to git
-        ↓
+
+处理完建议再跑：
+
+```bash
 aida build
-        ↓
-.aida/**/*.md and other non-JSON files   ← generated or local-only, gitignored
-.claude/.cursor/.codex/.lingma and peers ← project-local tool artifacts, gitignored
-.mcp.json / AGENTS.md / CLAUDE.md        ← project-local integration files, recommended to ignore
-        ↓
-AI reads its own tool files next session
 ```
 
-`aida build` writes generated rules, skills, memory views, and MCP config into AI tool directories inside the current project or AIDA view directories. Never edit generated `.md` files manually.
+### 7. 规则重复、相似、怀疑冲突
+
+相关操作见：[COMMANDS.md / 场景 5：rules 冲突](./COMMANDS.md#场景-5rules-冲突)
+
+适用场景：
+
+- 规则越积越多
+- 多分支合并后担心重复
+- 想清理 exact duplicate，再人工看 near duplicate
 
-Recommended Git strategy:
-- commit only JSON source files under `.aida`
-- keep AI tool directories and project integration files local-only
-- `aida init`, `aida migrate-dir`, and `aida migrate-legacy` print a manual reminder when ignored files were already tracked, but do not run destructive Git commands automatically
+操作：
 
-Legacy migration note:
-- `aida migrate-legacy` now also migrates historical `run.json`, `requirement.json`, and `analysis.md` into `.aida/runs/*/context.json` and `.aida/memories/modules/*.json`
-- when multiple baseline tools are detected, it auto-selects based on project config order and built-in priority instead of blocking on an interactive prompt
-- old `report` files remain derived output; new context recovery uses the migrated JSON memory source
+```bash
+aida rules dedupe
+```
 
-Runtime recovery note:
-- before coding, search module memory and prefer MCP `aida_memory_pack` or the JSON sources under `.aida/runs/*/requirement.json`, `.aida/runs/*/context.json`, and `.aida/memories/modules/*.json`
-- if the branch context is missing or stale, rebuild it with `aida memory rebuild` or MCP `aida_context_rebuild`
+它会：
 
-### Daily workflow
+- 自动移除 exact duplicate
+- 提示 near duplicate / potential conflict
 
-After pulling changes that include new rules:
+如果你手工改了 `.aida/rules.json`，记得再跑：
 
 ```bash
-git pull
-aida build   # regenerate local AI tool artifacts from updated JSON sources
+aida rules build
 ```
 
-### Merge conflict resolution
+### 8. 发布前自检建议
+
+详细步骤见：[COMMANDS.md / 场景 8：发布前自检](./COMMANDS.md#场景-8发布前自检)
+
+如果你准备发包，至少建议在当前项目里跑一遍：
+
+```bash
+npm run build
+npm test
+npm pack --dry-run
+aida build
+aida import codex
+aida migrate-legacy codex
+aida rules build
+aida rules dedupe
+```
 
-When two developers add rules on separate branches and merge, `rules.json` may get a standard git conflict. Resolve it in one command:
+如果仓库里还有冲突样本，建议再补：
 
 ```bash
-# After git merge produces a conflict in rules.json:
-aida rules merge   # fingerprint union — no duplicates, no lost rules
-aida build         # rebuild local AI tool artifacts
-git add .aida/rules.json
-git commit -m "merge: resolve rules conflict"
+aida rules merge
+aida merge
 ```
 
-`aida rules merge` uses fingerprint deduplication: if two rules have identical content, only one is kept. If they differ, both are kept and the incoming rule is renumbered to avoid ID collisions.
+---
+
+## 🧭 命令速览
 
-### Managing rules over time
+### 初始化与迁移
 
 ```bash
-aida rules list      # list all rules grouped by category
-aida rules dedupe    # surface rules with >40% keyword overlap for manual review
+aida init
+aida migrate-dir
+aida migrate-legacy
 ```
 
-Rules have a `status` field (`active` / `deprecated`). When project conventions evolve, deprecate old rules — they stop appearing in the `.md` files your AI reads, but remain in `rules.json` as an audit trail.
+- `aida init`：初始化新项目；如果项目已初始化，会进入“新增工具 / 修复缺失产物 / 退出”的分支。
+- `aida migrate-dir`：只做 `.aidevos -> .aida` 目录迁移与路径替换；已经迁过时会安全 no-op。
+- `aida migrate-legacy`：一键迁移老项目；即使项目已经是 `.aida`，也可以重跑，用于补建之前缺失的产物。
+
+### 构建与合并
+
+```bash
+aida build
+aida merge
+aida rules build
+aida rules dedupe
+```
+
+- `aida build`：从 `.aida/*.json` 真源重建规则视图、技能、工具侧产物、MCP 配置和 memory 视图。
+- `aida merge`：解决 `.aida/rules.json` / `.aida/skills.json` 的 git conflict 内容。
+- `aida rules build`：只重建规则相关产物。
+- `aida rules dedupe`：先移除完全重复的规则，再提示近似重复/潜在冲突的规则。
+
+详细说明见 [COMMANDS.md](./COMMANDS.md)。
 
 ---
 
-## Roadmap
+## 🧩 规则去重与冲突判断
+
+### 1. 完全重复如何判断
+
+AIDA 用 `fingerprint` 判断 exact duplicate。生成规则如下：
+
+1. 转小写
+2. 折叠空白字符：多个空格 / 换行 / tab 归一成一个空格
+3. 去掉常见中英文标点
+4. `trim`
+5. 对归一化后的内容做 `sha256`
+6. 取前 12 位作为 `fingerprint`
+
+这意味着以下内容会被视为同一条规则：
+
+- `禁止任何形式的臆想，不清楚必须询问`
+- ` 禁止任何形式的臆想，不清楚必须询问 `
+- `禁止任何形式的臆想，不清楚必须询问！`
+
+### 2. 近似重复 / 潜在冲突如何判断
+
+`aida rules dedupe` 不只看 `fingerprint`。对于**不同 fingerprint** 的规则，它会继续做近似判断：
+
+- 只比较同一 `category` 下的规则
+- 用和 `fingerprint` 一致的归一化规则做文本清洗
+- 按空格切词
+- 过滤长度小于等于 1 的 token
+- 计算 Jaccard 相似度
+- 相似度 `>= 0.4` 时，标记为 potential duplicate
+
+这类规则不会自动合并，只会提示人工处理。原因很简单：语义相近不代表可以安全替换。
+
+### 3. 当前行为
 
-- [ ] Export reports as PDF / HTML (H1/H2 performance reviews)
-- [ ] Historical trend analysis — deviation reduction curves over time
-- [ ] Team dashboard with multi-project aggregation
-- [ ] VS Code extension for inline deviation alerts
-- [ ] Cross-project rule sharing — team-wide AI knowledge base
+- `rules add`：按 `fingerprint` 阻止新增完全重复规则
+- `merge`：按 `fingerprint` 合并冲突两侧规则
+- `build`：分发规则视图时会过滤 exact duplicate，避免生成产物里重复出现
+- `rules dedupe`：会把 `rules.json` 里已经存在的 exact duplicate 清掉，并继续提示 near duplicate
 
 ---
 
-## Tech Stack
+## 🔁 重复执行与覆盖策略
 
-| | |
-|---|---|
-| **Runtime** | Node.js + TypeScript, zero dependencies |
-| **Dashboard** | React 19 + ECharts + Tailwind CSS 4 |
-| **Protocol** | MCP over stdio (JSON-RPC 2.0) |
-| **Data** | Local JSON files, no database |
-| **Real-time** | Server-Sent Events (SSE) |
-| **i18n** | Chinese / English, switchable in dashboard |
+重复执行的目标是**补全缺失，不破坏用户手工内容**。当前策略如下。
 
-## Testing
+### 安全重跑的命令
 
-```bash
-npm test    # 82 tests across 29 suites
-```
+- `aida init`
+  - 未初始化时：正常初始化
+  - 已初始化时：进入交互分支，可选择新增工具或修复缺失文件
+- `aida migrate-dir`
+  - 已经使用 `.aida` 时：直接 no-op
+- `aida migrate-legacy`
+  - 已迁移项目可重跑
+  - 适合“老版本包生成不完整，升级后再补建”的场景
 
-## Contributing
+### 不会直接冲掉用户内容的部分
 
-Issues, feature requests, and PRs are welcome.
+- `AGENTS.md` / `CLAUDE.md`
+  - 只维护 AIDA 注入区块
+  - 已有自定义内容会尽量保留
+- `.mcp.json` / `.cursor/mcp.json` / `.lingma/mcp.json`
+  - 走 JSON merge，把 `aida` MCP server 合进去
+- `.codex/config.toml`
+  - 只维护 `[mcp_servers.aida]` 片段，保留其他配置
+- `.gitignore`
+  - 只追加缺失条目，不清空现有内容
 
-```bash
-git clone https://github.com/LWTlong/ai-dev-analytics.git
-cd ai-dev-analytics
-npm install
-npm test
-```
+### 会被重建覆盖的部分
+
+以下属于 **AIDA 受管生成产物**，重复执行会按 `.aida/*.json` 真源重建：
 
-## License
+- `.aida/rules/*.md`
+- `.aida/memories/modules/*.md`
+- `.aida/runs/*/context.md`
+- `.cursor/rules/aida/*`
+- `.codex/rules/aida/*`
+- `.claude/rules/aida/*`
+- `.lingma/rules/*`
+- 工具侧由 AIDA 分发的 skill / command 文件
 
-[MIT](./LICENSE)
+这部分不建议手改。若手改，再次 `build` / `repair` / `migrate-legacy` 时会被覆盖，这是预期行为。
+
+### 推荐原则
+
+- 想长期保留的规则、技能、上下文：改 `.aida/*.json` 真源
+- 只想修复缺失产物：优先重跑 `aida init -> repair` 或 `aida migrate-legacy`
+- 不要把人工内容写进 AIDA 受管生成目录
 
 ---
 
-<div align="center">
+## 📁 数据沉淀与绩效汇报
 
-**Vibe coding without data is just vibing.**<br>
-**Add data, and your AI gets smarter every run.**
+AIDA 不只是可视化 —— 它**沉淀数据**。每次运行都积累结构化数据，时间越长价值越大。
 
-[Get Started in 30 Seconds →](#-30-second-setup)
+```
+第 1 周：47 个任务、23 个偏差、5 个 Bug、6 条规则、4064 行代码
+第 4 周：180+ 任务、偏差率持续下降、15 条规则、完整质量历史
+一个季度：完整的开发记录 —— 可导出、可分析、可汇报
+```
 
-</div>
+所有数据都在 `.aida/` 里，格式是结构化 JSON。没有厂商锁定，随时可以导出、查询或接入别的报表系统。