{ "canonical_name": "cristian1991/AIDOCS", "compilation_id": "pack_6ddfb758c3344193a3705dfe6b8dcb93", "created_at": "2026-05-24T14:13:37.248894+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install aidocs-mcp` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install aidocs-mcp", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_939b175a76954e9087129cc3ecfd40ef" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_da3259dae5a2093c9e71f2ce179cbd98", "canonical_name": "cristian1991/AIDOCS", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/cristian1991/AIDOCS", "slug": "aidocs", "source_packet_id": "phit_ab702486819248c886e92db5d96e9121", "source_validation_id": "dval_6aec93c020bd4eafb797b5925239ca92" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 mcp_host的用户", "github_forks": 0, "github_stars": 5, "one_liner_en": "The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.", "one_liner_zh": "The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.", "primary_category": { "category_id": "software-development", "confidence": "high", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, coding, git" }, "target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户", "title_en": "AIDOCS", "title_zh": "AIDOCS 能力包", "visible_tags": [ { "label_en": "Security & Permissions", "label_zh": "安全审查与权限治理", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-security-permissions", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Multi-agent Collaboration", "label_zh": "多 Agent 协作", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-multi-agent-collaboration", "type": "core_capability" }, { "label_en": "Checkpoint Resume", "label_zh": "断点恢复流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-checkpoint-resume", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_ab702486819248c886e92db5d96e9121", "page_model": { "artifacts": { "artifact_slug": "aidocs", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install aidocs-mcp", "label": "Python / pip · 官方安装入口", "source": "https://github.com/cristian1991/AIDOCS", "verified": true } ], "display_tags": [ "安全审查与权限治理", "知识库问答", "多 Agent 协作", "断点恢复流程", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host, claude, claude_code, cursor", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | host_targets=mcp_host, claude, claude_code, cursor" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.0 — Unified AccessGate & Agent Enforcement", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_2ef38d1286d44ae9b266a98267a2d782 | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.0.0 — Unified AccessGate & Agent Enforcement", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.3 — Token Tracking & Dashboard Fixes", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_5428bd20316b4bfa987b009350fc138b | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v2.0.3 — Token Tracking & Dashboard Fixes", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。", "title": "踩坑日志" }, "snapshot": { "contributors": 1, "forks": 0, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 5 }, "source_url": "https://github.com/cristian1991/AIDOCS", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.", "title": "AIDOCS 能力包", "trial_prompt": "# AIDOCS - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for cristian1991/AIDOCS.\n\nProject:\n- Name: AIDOCS\n- Repository: https://github.com/cristian1991/AIDOCS\n- Summary: The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.\n- Host target: mcp_host, claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to AIDOCS. Produce one small intermediate artifact and wait for confirmation.\n2. architecture-overview: System Architecture Overview. Produce one small intermediate artifact and wait for confirmation.\n3. mcp-server: MCP Server Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. memory-system: Memory System. Produce one small intermediate artifact and wait for confirmation.\n5. conductor-orchestration: Conductor & Orchestration. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/cristian1991/AIDOCS\n- https://github.com/cristian1991/AIDOCS#readme\n- README.md\n- mcp/README.md\n- core/AGENTS.md\n- mcp/server/ARCHITECTURE.md\n- mcp/server/METHODS.md\n- core/.commands/aidocs.md\n- mcp/server/aidocs_mcp/types.py\n- mcp/server/aidocs_mcp/mcp_server.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github。github/github_release: v2.0.3 — Token Tracking & Dashboard Fixes（https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3）；github/github_release: v2.0.0 — Unified AccessGate & Agent Enforcement（https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_release", "source": "github", "title": "v2.0.3 — Token Tracking & Dashboard Fixes", "url": "https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3" }, { "kind": "github_release", "source": "github", "title": "v2.0.0 — Unified AccessGate & Agent Enforcement", "url": "https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0" } ], "status": "已收录 2 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.", "effort": "安装已验证", "forks": 0, "icon": "code", "name": "AIDOCS 能力包", "risk": "需复核", "slug": "aidocs", "stars": 5, "tags": [ "安全审查与权限治理", "知识库问答", "多 Agent 协作", "断点恢复流程", "评测体系" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/cristian1991/AIDOCS 项目说明书\n\n生成时间：2026-05-16 05:31:31 UTC\n\n## 目录\n\n- [Introduction to AIDOCS](#introduction)\n- [Installation Guide](#installation)\n- [System Architecture Overview](#architecture-overview)\n- [MCP Server Architecture](#mcp-server)\n- [Dashboard Architecture](#dashboard)\n- [Memory System](#memory-system)\n- [Conductor & Orchestration](#conductor-orchestration)\n- [Security & Access Control](#security-gates)\n- [Indexing & Retrieval System](#indexing-retrieval)\n- [Configuration Management](#configuration)\n\n\n\n## Introduction to AIDOCS\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [System Architecture Overview](#architecture-overview)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n- [mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n- [apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n- [mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n- [mcp/server/aidocs_mcp/data/opencode_plugin.js](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/data/opencode_plugin.js)\n
\n\n# Introduction to AIDOCS\n\n## Overview\n\nAIDOCS is an intelligent development system that provides AI coding agents with **persistent memory**, **indexed retrieval**, and **orchestration capabilities**. The platform enables AI agents to resume work efficiently instead of rediscovering repository context on every session. 资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n## Purpose and Scope\n\nAIDOCS addresses a fundamental challenge in AI-assisted development: **context loss between sessions**. When an AI coding agent completes a task or reconnects after a break, it traditionally must re-analyze the entire codebase to understand the project structure, recent changes, and development context. AIDOCS eliminates this inefficiency by maintaining persistent context that survives across sessions.\n\nThe system provides:\n\n- **Persistent Memory**: Store and retrieve development context across agent sessions\n- **Indexed Retrieval**: Fast lookup of relevant code, documentation, and project artifacts\n- **Orchestration**: Coordinate multiple AI agents and their activities\n- **Security Guards**: Built-in prompt injection detection and content filtering\n- **RBAC**: Role-Based Access Control for multi-tenant environments\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"AIDOCS Core\"\n A[AI Coding Agent] --> B[MCP Server]\n B --> C[Memory System]\n B --> D[Index Engine]\n B --> E[Session Manager]\n end\n \n subgraph \"Dashboard Layer\"\n C --> F[CastleShell Dashboard]\n D --> F\n E --> F\n F --> G[OverviewPage]\n F --> H[ExecutionPage]\n F --> I[ConductorPage]\n F --> J[RBACPage]\n end\n \n subgraph \"Security Layer\"\n B --> K[output_guard.py]\n K --> L[Prompt Injection Detection]\n K --> M[Sensitive Content Filtering]\n end\n \n subgraph \"External Integrations\"\n N[MCP Registry] --> B\n B --> O[Claude.ai]\n B --> P[OpenAI API]\n end\n```\n\n## Core Components\n\n### MCP Server (Model Context Protocol)\n\nThe AIDOCS MCP server acts as the central communication hub between AI agents and the AIDOCS backend. It handles tool routing, session management, and context retrieval.\n\n**Key Tools Provided:**\n\n| Tool Category | Tools | Purpose |\n|---------------|-------|---------|\n| Classification | `classify_prompt`, `route_prompt` | Advisory routing for prompts |\n| Investigation | `ai_investigate`, `ai_bundle` | Broad context exploration |\n| Search | `ai_find`, `ai_trace` | Symbol and reference search |\n| Database | `schema_query` | Database schema operations |\n| Sessions | `ai_session` | List, create, connect, update, resume sessions |\n| Tasks | `ai_task` | Begin, update, complete, status tasks |\n| Memory | `memory_read`, `memory_capture`, `memory_search` | Memory operations |\n| Project | `project_init`, `project_sync_indexes` | Project initialization |\n| Code Operations | `ai_get_lines`, `ai_text_search`, `ai_search` | Read operations |\n| Edit Operations | `ai_replace`, `ai_edit_lines`, `ai_batch_edit` | Write operations |\n\n资料来源：[mcp/README.md]()\n\n### Memory System\n\nThe memory system provides persistent storage for agent context:\n\n```mermaid\ngraph LR\n A[Capture Event] --> B[memory_capture]\n B --> C[Memory Index]\n C --> D[memory_search]\n D --> E[Relevant Context]\n E --> F[Agent Context]\n```\n\n**Memory Operations:**\n\n- `memory_read`: Retrieve stored memory entries\n- `memory_capture`: Store new context from agent activities\n- `memory_search`: Search across stored memories using natural language\n\n### Session Management\n\nSessions enable agents to resume work without context loss:\n\n```mermaid\nstateDiagram-v2\n [*] --> List: ai_session list\n List --> Create: ai_session create\n Create --> Connect: ai_session connect\n Connect --> Update: ai_session update\n Connect --> Resume: ai_session resume\n Update --> Release: ai_session release\n Resume --> Release\n Release --> [*]\n```\n\nSessions maintain:\n- Current status and goal\n- Owner information\n- Context budget (token estimates, journal entries)\n- Recent execution history\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx]()\n\n### Execution Tracking (Conductor)\n\nThe Conductor system tracks all tool calls and agent actions:\n\n| Field | Description |\n|-------|-------------|\n| `session_id` | Associated session identifier |\n| `capability_name` | Tool or capability invoked |\n| `action_kind` | Type of action performed |\n| `observed_at` | Timestamp of observation |\n| `lane` | Execution lane (execution context) |\n| `logicalMode` | Logical routing mode |\n| `nativeMode` | Native routing mode |\n| `fallbackUsed` | Whether fallback routing was used |\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](), [apps/aidocs-dashboard/src/ExecutionPage.tsx]()\n\n### Security Layer (output_guard.py)\n\nAIDOCS includes robust security features to protect against prompt injection attacks:\n\n**Prompt Injection Patterns Detected:**\n\n| Pattern ID | Regex Pattern | Description |\n|------------|---------------|-------------|\n| `system_override` | `(?:ignore\\|forget\\|disregard) all (?:previous\\|prior\\|above)` | System override attempts |\n| `role_hijack` | `you are now (?:a )?(?:different\\|new\\|my) (?:ai\\|assistant\\|agent\\|bot)` | Role hijacking attempts |\n| `instruction_inject` | `<\\s*(?:system\\|instructions?\\|prompt)\\s*>` | XML tag injection |\n| `delimiter_escape` | `\\`\\`\\`\\s*(?:system\\|instructions?)\\n` | Code block injection |\n| `hidden_instruction` | `(?:IMPORTANT\\|CRITICAL\\|URGENT)\\s*:\\s*(?:ignore\\|override\\|forget\\|disregard)` | Hidden instruction attempts |\n\n**Sensitive Content Patterns:**\n\n| Pattern ID | Regex Pattern | Description |\n|------------|---------------|-------------|\n| `env_file_content` | `^[A-Z_]{3,}=\\S{8,}$` | Potential .env file leaks |\n| `ssh_config` | `(?:Host\\s+\\S+\\|IdentityFile\\s+~/)` | SSH configuration content |\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py]()\n\n### RBAC (Role-Based Access Control)\n\nAIDOCS implements comprehensive role-based access control:\n\n**Key Features:**\n- Permission management with descriptions\n- Escalation paths for elevated privileges\n- Sticky escalations for persistent elevated access\n- Session/task-scoped permission grants\n\n**Escalation Fields:**\n\n| Field | Description |\n|-------|-------------|\n| `requester` | User or agent requesting escalation |\n| `permission` | Permission being escalated |\n| `phrase` | Trigger phrase for escalation |\n| `session / task` | Associated session or task |\n| `sticky` | Whether escalation persists |\n| `created · expires` | Temporal bounds |\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx]()\n\n### Dashboard Interface (CastleShell)\n\nThe AIDOCS Dashboard provides a web-based interface for monitoring and managing the system:\n\n```mermaid\ngraph TD\n subgraph \"CastleShell Components\"\n A[CastleShell] --> B[Navigation]\n A --> C[StatusBar]\n A --> D[ContextRail]\n A --> E[TopStrip]\n end\n \n subgraph \"Dashboard Pages\"\n B --> O[OverviewPage]\n B --> P[ExecutionPage]\n B --> Q[ConductorPage]\n B --> R[RBACPage]\n B --> S[SkillsPage]\n B --> T[MonitoringPage]\n B --> U[RegistryPage]\n B --> V[TomlConfigsPage]\n end\n \n subgraph \"Navigation Counts\"\n C --> W[CastleNavCounts]\n W --> X[executions]\n W --> Y[sessions]\n W --> Z[escalations]\n end\n```\n\n**CastleShell Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `active` | `NavKey` | Currently active navigation item |\n| `onSelect` | `(key: NavKey) => void` | Navigation callback |\n| `counts` | `CastleNavCounts` | Badge counts for navigation |\n| `managedMode` | `boolean` | Whether managed mode is active |\n| `version` | `string` | AIDOCS version |\n| `mcpConnected` | `boolean` | MCP server connection status |\n| `activeLayer` | `string` | Current execution layer |\n| `saveState` | `string` | Current save state indicator |\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx]()\n\n## Setup and Installation\n\n### Initial Setup Wizard\n\nThe setup wizard guides users through project configuration:\n\n```mermaid\ngraph LR\n A[Welcome] --> B[Project Selection]\n B --> C[Environment Check]\n C --> D[Host Configuration]\n D --> E[Configure]\n E --> F[Done]\n```\n\n**Setup Steps:**\n\n1. **Welcome**: Introduction and feature overview\n2. **Project Selection**: Choose project folder path\n3. **Environment Check**: Verify Node.js and other dependencies\n4. **Host Configuration**: Configure Claude.ai, OpenAI API access\n5. **Configure**: Set up MCP, hooks, and project structure\n6. **Done**: Confirmation of successful setup\n\n**Setup Wizard Features:**\n\n- Progress indicator showing current step\n- Environment detection with status checks\n- Host authentication status display\n- Automatic installation option for missing tools\n- Sign-in buttons for external services\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n### Environment Detection\n\nThe setup wizard detects:\n\n| Component | Detection | Installable |\n|-----------|-----------|-------------|\n| Node.js | Checks for CLI agent support | No |\n| Claude | Checks `claude.ai` authentication | Yes |\n| OpenAI | Checks API key configuration | Yes |\n| Custom Hosts | Configurable external services | Yes |\n\n### MCP Registry Integration\n\nAIDOCS supports discovering and installing MCP servers from a registry:\n\n- Search functionality for MCP servers\n- Install commands extraction\n- Transport and command information display\n- Website URL tracking\n\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx]()\n\n## Workflow Patterns\n\n### Agent Workflow with AIDOCS\n\n```mermaid\ngraph TD\n A[Start Task] --> B[ai_session create]\n B --> C[Define Goal]\n C --> D[ai_investigate]\n D --> E[ai_find / ai_trace]\n E --> F[ai_get_symbol_info]\n F --> G[Edit Code]\n G --> H[memory_capture]\n H --> I[ai_session update]\n I --> J{More Work?}\n J -->|Yes| E\n J -->|No| K[ai_task complete]\n K --> L[ai_session release]\n L --> M[End]\n```\n\n### Code Editing Workflow\n\nRecommended sequence for code modifications:\n\n1. `ai_get_lines` — Read file content\n2. `ai_get_symbol_info(kind=\"signature\"|\"constructor\")` — Confirm target signatures\n3. `ai_edit_lines` or `ai_batch_edit` — Apply changes\n4. `ai_task_complete` — Mark task complete\n\n**Important:** Do not mix different edit methods within the same task.\n\n### Investigation Workflow\n\nFor understanding unfamiliar code:\n\n1. `session_resume_bundle` — Get project/session/skills/plan overview\n2. `action_surface_current_session_bundle` — Identify likely next tools\n3. `ai_find(query, mode=\"symbols\")` — Locate relevant symbols\n4. `ai_get_symbol_snippet` — Retrieve code snippets\n5. `ai_bundle(concept, mode=\"subsystem\")` — Get subsystem context\n\n资料来源：[mcp/server/aidocs_mcp/data/opencode_plugin.js]()\n\n## Context Budget Management\n\nSessions track context budget usage:\n\n| Metric | Description |\n|--------|-------------|\n| `status` | Budget status (available, exhausted, etc.) |\n| `reason` | Reason for budget state |\n| `estimated_tokens` | Current token count estimate |\n| `journal_entries` | Number of journal entries |\n| `available` | Whether compaction is possible |\n\n**Compaction:** When context budget is running low, use the compact function to reduce token usage while preserving critical context.\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx]()\n\n## Monitoring and Analytics\n\n### Execution Monitoring\n\nTrack agent activities across dimensions:\n\n- **By Event Kind**: Categorize by tool type or action\n- **By Source**: Track which agent or integration triggered events\n- **Recent Execution**: View recent events with timestamps\n\n### Lane Management\n\nLanes provide execution isolation and context grouping:\n\n- Events can be tagged with `lane_id`\n- Related events are grouped together\n- Status tracking (applied, refused, blocked)\n\n资料来源：[apps/aidocs-dashboard/src/MonitoringPage.tsx](), [apps/aidocs-dashboard/src/LaneDetailPanel.tsx]()\n\n## Skills System\n\nAIDOCS supports dynamic skill registration:\n\n| Property | Description |\n|----------|-------------|\n| `name` | Skill identifier |\n| `description` | Human-readable description |\n| `skill_kind` | Type of skill |\n| `provider` | Skill provider name |\n| `source` | Skill source location |\n| `selected` | Whether skill is selected for use |\n| `active` | Whether skill is currently active |\n| `activation_tags` | Tags triggering skill activation |\n| `provider_status` | Current provider state |\n\n资料来源：[apps/aidocs-dashboard/src/SkillsPage.tsx]()\n\n## TOML Configuration\n\nAIDOCS uses TOML for project and system configuration:\n\n- Configuration document browsing by category\n- Syntax-highlighted editor with save functionality\n- Support for multiple TOML files per category\n\n资料来源：[apps/aidocs-dashboard/src/TomlConfigsPage.tsx]()\n\n## Command Line Interface\n\n### Basic Commands\n\n```bash\npip install aidocs-mcp\naidocs --version\naidocs-mcp # start MCP server\n```\n\n## Summary\n\nAIDOCS provides a comprehensive platform for enhancing AI coding agents with persistent memory and intelligent context management. Its modular architecture includes:\n\n- **MCP Server**: Central communication hub with 20+ specialized tools\n- **Memory System**: Persistent storage and retrieval of development context\n- **Session Management**: Seamless task resumption across agent sessions\n- **Security Layer**: Prompt injection detection and sensitive content filtering\n- **RBAC**: Fine-grained access control for enterprise environments\n- **Dashboard**: Web-based monitoring and management interface\n\nBy integrating AIDOCS into AI-assisted development workflows, teams can significantly reduce the time agents spend re-establishing context, leading to faster development cycles and more consistent code quality.\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Introduction to AIDOCS](#introduction), [MCP Server Architecture](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n- [core/scripts/install.sh](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.sh)\n- [core/scripts/install.ps1](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.ps1)\n- [mcp/server/aidocs_mcp/cli.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/cli.py)\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n
\n\n# Installation Guide\n\nAIDOCS is an AI-powered documentation and coding assistant platform that provides persistent memory, indexed retrieval, and orchestration for AI coding agents. This guide covers all installation methods, prerequisites, and configuration steps required to deploy AIDOCS in your development environment.\n\n## Prerequisites\n\nBefore installing AIDOCS, ensure your system meets the following requirements.\n\n### System Requirements\n\n| Requirement | Minimum | Recommended |\n|-------------|---------|-------------|\n| Node.js | 18.x | 20.x LTS |\n| Python | 3.10+ | 3.11+ |\n| Disk Space | 500 MB | 2 GB |\n| RAM | 4 GB | 8 GB |\n| OS | macOS, Linux, Windows (WSL2) | macOS, Linux |\n\n### Supported AI Host Platforms\n\nAIDOCS integrates with multiple AI coding assistants. The installation process detects available platforms.\n\n| Platform | Status Detection | Authentication |\n|----------|-----------------|----------------|\n| Claude (claude.ai) | Auto-detected | Requires sign-in |\n| OpenAI (ChatGPT) | Auto-detected | Requires API key |\n| Cursor | Supported | Via MCP |\n| Windsurf | Supported | Via MCP |\n\n资料来源：[SetupWizardPage.tsx:42-56](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n## Installation Methods\n\nAIDOCS supports multiple installation methods across different platforms.\n\n### Automated Installation\n\n#### macOS and Linux\n\nUse the shell installer script for POSIX-compliant systems:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cristian1991/AIDOCS/main/core/scripts/install.sh | bash\n```\n\nThe script performs the following operations:\n1. Checks for required dependencies (Node.js, Python)\n2. Creates necessary directory structure\n3. Installs the AIDOCS CLI globally\n4. Sets up MCP server configurations\n5. Initializes the project workspace\n\n资料来源：[core/scripts/install.sh](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.sh)\n\n#### Windows\n\nFor Windows systems, use PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/cristian1991/AIDOCS/main/core/scripts/install.ps1 | iex\n```\n\nThe PowerShell installer:\n1. Validates PowerShell version (5.1+ required)\n2. Installs dependencies via winget or chocolatey\n3. Configures Windows-specific paths\n4. Registers AIDOCS in the system PATH\n\n资料来源：[core/scripts/install.ps1](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.ps1)\n\n### Manual Installation\n\nFor custom deployments, install the CLI directly:\n\n```bash\n# Clone the repository\ngit clone https://github.com/cristian1991/AIDOCS.git\ncd AIDOCS\n\n# Install Python dependencies\npip install -e .\n\n# Install Node.js dependencies\ncd apps/aidocs-dashboard\nnpm install\nnpm run build\n```\n\n## Setup Wizard\n\nThe first time you launch AIDOCS, a setup wizard guides you through the configuration process.\n\n### Workflow Overview\n\n```mermaid\ngraph TD\n A[Welcome] --> B[Project Selection]\n B --> C[Prerequisites Check]\n C --> D[AI Host Configuration]\n D --> E[Configuring]\n E --> F[Done]\n \n C -->|Missing dependencies| G[Install Required Tools]\n G --> C\n \n D -->|Not authenticated| H[Sign In Required]\n H --> D\n```\n\n### Step 1: Welcome\n\nThe welcome screen introduces AIDOCS capabilities:\n\n> AIDOCS gives your AI coding agents persistent memory, indexed retrieval, and orchestration — so they resume work instead of rediscovering your repo every time.\n\n资料来源：[SetupWizardPage.tsx:25-31](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 2: Project Selection\n\nSpecify the project folder where AIDOCS will operate:\n\n| Field | Description |\n|-------|-------------|\n| Project Path | Absolute path to your project folder (leave empty for current directory) |\n| Auto-detect | Attempts to find an existing AIDOCS configuration |\n\n```typescript\n setProjectPath(e.target.value)}\n placeholder=\"Project folder path (or leave empty for current directory)\"\n/>\n```\n\n资料来源：[SetupWizardPage.tsx:50-55](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 3: Prerequisites Check\n\nThe installer validates the presence of required tools:\n\n| Tool | Required | Optional |\n|------|----------|----------|\n| Node.js | Yes | For CLI agents |\n| Claude | If using Claude | — |\n| OpenAI | If using GPT | — |\n\nDetection results display with status indicators:\n\n| Status | Icon | Meaning |\n|--------|------|---------|\n| Pass | `+` | Installed and authenticated |\n| Warning | `!` | Installed but not signed in |\n| Missing | `-` | Not installed (can be auto-installed) |\n\nFor hosts requiring authentication:\n\n```typescript\n\n```\n\n资料来源：[SetupWizardPage.tsx:58-72](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 4: Configuration\n\nThe installer configures MCP servers, hooks, and project structure:\n\n| Configuration Item | Output Path | Description |\n|-------------------|-------------|-------------|\n| MCP Configuration | `{project}/.aidocs/mcp.json` | MCP server endpoints |\n| Hooks Registration | `{project}/.aidocs/hooks.json` | Pre/post execution hooks |\n| Project Initialization | `{project}/.aidocs/` | Working directory for AIDOCS |\n\n```typescript\n{step === \"configure\" && (\n
\n

Configuring

\n

Setting up MCP, hooks, and project structure...

\n
\n
\n)}\n```\n\n资料来源：[SetupWizardPage.tsx:95-102](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 5: Completion\n\nUpon successful installation, the wizard displays:\n\n| Checklist Item | Status |\n|----------------|--------|\n| MCP configured | ✅ With path shown |\n| Hooks registered | ✅ With path shown |\n| Project initialized | ✅ |\n| MCP servers installed | ✅ (if any selected) |\n\n资料来源：[SetupWizardPage.tsx:104-130](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n## MCP Server Installation\n\nAIDOCS supports Model Context Protocol (MCP) servers for extended functionality.\n\n### Server Registry\n\nThe dashboard includes a searchable registry of MCP servers:\n\n```typescript\n
\n {results.map((server: RegistrySearchResult) => (\n // Server card rendering\n ))}\n
\n```\n\n资料来源：[RegistryPage.tsx:25-28](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n### Installing MCP Servers\n\nEach server in the registry provides installation commands:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `install_commands` | Array | Available installation methods |\n| `transport` | String | Protocol (stdio, sse, http) |\n| `command` | String | Execution command |\n| `website_url` | String | Official documentation |\n\n```typescript\nconst installText = typeof firstCmd === \"string\" \n ? firstCmd \n : String((firstCmd as Record).command ?? \"\");\n```\n\n资料来源：[RegistryPage.tsx:30-36](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n## CLI Commands\n\nThe AIDOCS CLI provides command-line access to installation and management functions.\n\n### Primary Commands\n\n| Command | Description |\n|---------|-------------|\n| `aidocs init` | Initialize AIDOCS in the current project |\n| `aidocs start` | Launch the dashboard |\n| `aidocs status` | Check MCP and service status |\n| `aidocs config` | Manage configuration |\n\n资料来源：[mcp/server/aidocs_mcp/cli.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/cli.py)\n\n### Post-Installation Steps\n\nAfter successful installation:\n\n1. **Open your project** in your preferred IDE\n2. **Start a new agent session**\n3. **Type `/aidocs`** to begin\n\n```html\n
\n

Next Steps

\n
    \n
  1. Open {projectPath || \"your project\"} in your IDE
    2. \n
  2. Start a new agent session
    3. \n
  3. Type /aidocs to begin
    4. \n
\n
\n```\n\n资料来源：[SetupWizardPage.tsx:131-139](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n## Dashboard Access\n\nAfter installation, access the AIDOCS dashboard:\n\n```bash\n# Start the dashboard server\naidocs start\n\n# Or open the dashboard directly\nopen http://localhost:3000\n```\n\nThe dashboard is served from `apps/aidocs-dashboard/` and provides:\n\n- **Overview**: Session status, context budget, recent execution\n- **Registry**: Browse and install MCP servers\n- **RBAC**: Manage roles and permissions\n- **Execution**: View tool call history\n- **Settings**: Configure project options\n\n资料来源：[apps/aidocs-dashboard/index.html](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/index.html)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Node.js not found | Install via `nvm install 20` or download from nodejs.org |\n| Authentication failed | Sign in via the setup wizard \"Sign in\" button |\n| MCP connection failed | Check firewall settings and MCP endpoint configuration |\n| Dashboard won't load | Ensure port 3000 is available, or configure alternative port |\n\n### Verification\n\nConfirm successful installation:\n\n```bash\n# Check AIDOCS version\naidocs --version\n\n# Verify MCP connection\naidocs status\n\n# Test configuration\naidocs config --validate\n```\n\n## Upgrade Instructions\n\nTo upgrade AIDOCS to the latest version:\n\n```bash\n# Update via npm (if installed globally)\nnpm update -g aidocs\n\n# Or use the built-in update command\naidocs update\n```\n\nAfter upgrading, run the setup wizard again to apply configuration changes:\n\n```bash\naidocs setup --wizard\n```\n\n## Uninstallation\n\nTo remove AIDOCS from a project:\n\n```bash\n# Remove AIDOCS files (keeps data)\naidocs uninstall\n\n# Complete removal including data\naidocs uninstall --clean\n```\n\nThis removes:\n- `.aidocs/` directory\n- MCP configurations\n- Hook registrations\n\nGlobal CLI tools remain installed unless explicitly removed with `npm uninstall -g aidocs`.\n\n---\n\n\n\n## System Architecture Overview\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server), [Dashboard Architecture](#dashboard), [Memory System](#memory-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cistian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n- [apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n- [mcp/server/aidocs_mcp/data/opencode_plugin.js](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/data/opencode_plugin.js)\n- [apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n- [apps/aidocs-dashboard/src/LivePage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/LivePage.tsx)\n- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n- [apps/aidocs-dashboard/src/BashPolicyPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/BashPolicyPanel.tsx)\n
\n\n# System Architecture Overview\n\nAIDOCS is a persistent memory and orchestration framework designed for AI coding agents. It provides indexed retrieval, session persistence, and policy-based control to enable AI agents to resume work efficiently without repeatedly rediscovering repository context. The system consists of a frontend dashboard application and a backend MCP (Model Context Protocol) server that communicates with AI coding agents.\n\n## Core Architecture Layers\n\nAIDOCS operates through three primary architectural layers that work together to provide persistent context and control for AI agents.\n\n### Layer 1: MCP Server (`mcp/server/`)\n\nThe MCP server acts as the bridge between AI coding agents and the AIDOCS persistent storage system. It exposes tools and resources that agents can invoke during their sessions. The server handles context retrieval, session management, and policy enforcement through a standardized MCP interface.\n\nThe server provides several categories of tools including context management tools (`ai_find`, `ai_get_symbol_snippet`, `ai_bundle`), session tools (`session_resume_bundle`, `action_surface_current_session_bundle`), and investigation tools (`ai_investigate`). These tools enable agents to query indexed project knowledge, retrieve symbol information, and understand codebase structure.\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n资料来源：[mcp/server/aidocs_mcp/data/opencode_plugin.js]()\n\n### Layer 2: Dashboard Application (`apps/aidocs-dashboard/`)\n\nThe dashboard is a React-based web application that provides a visual interface for managing AIDOCS configuration, monitoring agent sessions, and administering security policies. The dashboard communicates with the MCP server through IPC (Inter-Process Communication) to retrieve and display session data.\n\nThe dashboard uses a modular component architecture built around the `CastleShell` wrapper, which provides consistent navigation, status indicators, and layout structure across all pages.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx]()\n\n### Layer 3: Persistent Storage and Indexing\n\nAIDOCS maintains indexed knowledge of the project codebase, session state, and configuration policies. This indexing enables fast retrieval of relevant context when agents resume sessions or need to understand unfamiliar parts of the codebase.\n\n## Dashboard Component Architecture\n\nThe AIDOCS dashboard is structured as a single-page application with multiple views accessible through a navigation sidebar. Each view addresses a specific aspect of agent management and monitoring.\n\n```mermaid\ngraph TD\n A[CastleShell] --> B[OverviewPage]\n A --> C[LivePage]\n A --> D[ConductorPage]\n A --> E[ExecutionPage]\n A --> F[RBACPage]\n A --> G[SettingsPage]\n A --> H[RegistryPage]\n A --> I[CommandPalette]\n \n B --> J[Snapshot Data]\n C --> K[Real-time Events]\n D --> L[Tool Routing]\n E --> M[Event Details]\n \n N[MCP Server] --> J\n N --> K\n N --> L\n N --> M\n```\n\n### CastleShell — Main Application Wrapper\n\nThe `CastleShell` component serves as the root layout container for the entire dashboard. It manages navigation state, renders the sidebar, and displays the status bar showing connection status and project information.\n\n**Key Properties:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `active` | `NavKey` | Currently selected navigation item |\n| `onSelect` | `(key: NavKey) => void` | Callback when navigation changes |\n| `counts` | `CastleNavCounts` | Badge counts for navigation items |\n| `managedMode` | `boolean` | Whether restricted mode is enabled |\n| `mcpConnected` | `boolean` | MCP server connection status |\n| `version` | `string` | AIDOCS version display |\n\nThe status bar component within CastleShell indicates MCP connection state with a color-coded indicator (green for connected, red for disconnected) and displays the current session ID and active layer.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx]()\n\n### SetupWizardPage — Initial Configuration\n\nThe `SetupWizardPage` guides users through initial AIDOCS setup with a multi-step wizard interface. It handles project selection, dependency detection, MCP configuration, and hook registration.\n\n**Setup Steps Flow:**\n\n```mermaid\ngraph LR\n A[welcome] --> B[project]\n B --> C[detection]\n C --> D[configure]\n D --> E[done]\n \n A -->|Get Started| B\n B -->|Select Folder| C\n C -->|Dependencies OK| D\n D -->|Configuration Complete| E\n```\n\nThe wizard validates system requirements including Node.js presence and AI platform authentication status (Claude, OpenAI). It can detect missing components and offer installation options directly within the interface.\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n## Session and Execution Monitoring\n\n### OverviewPage — Session Snapshot\n\nThe `OverviewPage` displays a consolidated snapshot of the current session including session metadata, capability usage statistics, and recent execution events. It provides at-a-glance monitoring of agent activity through a dashboard-style layout with panels for different data categories.\n\nThe page renders execution data in a tabular format showing capability names, action kinds, and timestamps for recent events. This allows operators to quickly assess agent behavior without drilling into detailed logs.\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx]()\n\n### LivePage — Real-time Event Stream\n\nThe `LivePage` provides a real-time view of agent execution events with support for lane-based isolation and policy enforcement. It displays a scrollable event feed with status indicators and allows operators to approve or reject escalated permission requests.\n\n**LivePage Features:**\n\n| Feature | Description |\n|---------|-------------|\n| Event Feed | Real-time scrolling list of agent actions |\n| Lane Indicators | Visual identification of execution lanes |\n| Approval Queue | Pending permission escalation requests |\n| Quick Actions | Controls for stopping lanes or pausing execution |\n\nThe control panel on the right side of the page contains pending approvals with approve/reject buttons, quick action buttons for lane management, and lane detail expanders showing related events.\n\n资料来源：[apps/aidocs-dashboard/src/LivePage.tsx]()\n\n### ExecutionPage — Detailed Event Analysis\n\nThe `ExecutionPage` provides deep-dive analysis of individual execution events. It displays full payload data, result summaries, and audit information for each recorded event. The page supports filtering and searching through execution history to locate specific agent actions.\n\n### LaneDetailPanel — Lane Event Context\n\nThe `LaneDetailPanel` component renders detailed information about specific execution lanes including related events, lane status, and execution history. Events are displayed with timestamps and status indicators that reflect whether actions were allowed, refused, or blocked.\n\nLane events show a color-coded status pill: green for `applied` or `allowed`, red for `refused` or `blocked`, and muted gray for other states.\n\n资料来源：[apps/aidocs-dashboard/src/LaneDetailPanel.tsx]()\n\n## Policy Management\n\n### BashPolicyPanel — Shell Command Control\n\nThe `BashPolicyPanel` provides a visual interface for managing shell command execution policies. It displays a summary of allow/deny/bubble counts and allows filtering by policy type.\n\n**Policy Controls:**\n\n| Control | Description |\n|---------|-------------|\n| Search Filter | Filter commands by name match |\n| Type Chips | Filter by all/allow/deny/bubble/modified |\n| Collapse Toggle | Show/hide policy details |\n\nEach policy entry shows the effective counts for allow, deny, and bubble policies, along with the active layer where modifications were made and the default fallback policy.\n\n资料来源：[apps/aidocs-dashboard/src/BashPolicyPanel.tsx]()\n\n### RBACPage — Role-Based Access Control\n\nThe `RBACPage` manages permissions, escalations, and custom policy configurations. It provides three tabbed views:\n\n1. **Policies Tab** — Lists configured policies with their states (system/custom)\n2. **Permissions Tab** — Shows available permission definitions\n3. **Escalations Tab** — Displays pending or active permission escalations\n\nThe escalations table tracks requesters, requested permissions, session/task context, sticky status, and expiration timestamps.\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx]()\n\n## MCP Server Integration\n\n### RegistryPage — MCP Server Discovery\n\nThe `RegistryPage` enables browsing and installing MCP servers from a remote registry. It supports searching for servers by name and displays installation commands, transport types, and website URLs for each available server.\n\n**Server Card Information:**\n\n| Field | Description |\n|-------|-------------|\n| Name | Server identifier |\n| Transport | Communication protocol |\n| Command | Installation command |\n| Website | Documentation URL |\n\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx]()\n\n### ConductorPage — Tool Routing Configuration\n\nThe `ConductorPage` manages the conductor tool routing system, which controls how different AI backends (Claude, Codex, OpenCode) are used for various tasks. It displays recent tool calls with routing audit information and allows configuration of routing rules.\n\n**Conductor Configuration Options:**\n\n| Setting | Options | Default |\n|---------|---------|---------|\n| Backend | claude, codex, opencode | claude |\n| Claude Model | Model identifier | — |\n| Codex Model | Model identifier | — |\n| OpenCode Model | Model identifier | — |\n\nThe page shows a diff viewer for edit operations, displaying old and new content side-by-side for easy comparison of changes made by the agent.\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx]()\n\n## User Interface Components\n\n### CommandPalette — Quick Action Interface\n\nThe `CommandPalette` provides keyboard-driven access to common actions. It supports fuzzy search, keyboard navigation (arrow keys), execution (Enter), and quick filtering (Tab).\n\n**Keyboard Shortcuts:**\n\n| Key | Action |\n|-----|--------|\n| ↑/↓ | Navigate commands |\n| Enter | Execute selected command |\n| Tab | Switch to filter mode |\n| Esc | Close palette |\n\nThe palette displays commands with status indicators showing whether they are allowed, denied, or require escalation.\n\n资料来源：[apps/aidocs-dashboard/src/CommandPalette.tsx]()\n\n### SettingDetailPanel — Configuration Editor\n\nThe `SettingDetailPanel` displays detailed information about individual configuration entries including current values, origins, and layer assignments. It supports editing configuration values directly within the panel.\n\nThe panel includes a per-leaf origin view that shows which layers contributed to each configuration value, useful for understanding inheritance and override behavior in multi-layered configurations.\n\n资料来源：[apps/aidocs-dashboard/src/SettingDetailPanel.tsx]()\n\n## Data Flow Architecture\n\n```mermaid\ngraph TD\n subgraph Agents[\"AI Coding Agents\"]\n Claude[Claude AI]\n Codex[Codex]\n OpenCode[OpenCode]\n end\n \n subgraph MCP[\"MCP Protocol Layer\"]\n Tools[MCP Tools]\n Resources[MCP Resources]\n Notifications[Notifications]\n end\n \n subgraph Server[\"AIDOCS Backend\"]\n Context[Context Engine]\n Index[Indexing Service]\n Policy[Policy Engine]\n Session[Session Manager]\n end\n \n subgraph Dashboard[\"Dashboard Frontend\"]\n UI[React Components]\n IPC[IPC Bridge]\n end\n \n Claude -->|MCP| Tools\n Codex -->|MCP| Tools\n OpenCode -->|MCP| Tools\n \n Tools --> Context\n Context --> Index\n Index --> Policy\n Policy --> Session\n \n Session -->|Events| Dashboard\n UI -->|Config| Session\n IPC -->|Status| UI\n```\n\n## Security Architecture\n\nAIDOCS implements a multi-layered security model through the following mechanisms:\n\n**Permission Escalation:** Agents can request elevated permissions for specific operations. These requests appear in the LivePage approval queue for operator review before execution proceeds.\n\n**Policy Layers:** Configuration policies are organized into layers with inheritance. The SettingDetailPanel shows which layer contributed each configuration value, enabling audit and rollback.\n\n**Bash Command Policies:** Shell execution is controlled through allow/deny/bubble policies. The BashPolicyPanel provides visibility into these rules and supports runtime modification.\n\n**Connection Verification:** The status bar in CastleShell continuously monitors MCP connection status. Loss of connection triggers visual indicators and can be configured to halt agent execution.\n\n## Summary\n\nThe AIDOCS architecture provides a complete framework for persistent AI agent context management. The MCP server layer exposes tools for agents to query indexed knowledge and manage sessions. The dashboard provides comprehensive monitoring, configuration, and policy management capabilities. Together, these components enable AI coding agents to maintain context across sessions, operate within defined security boundaries, and provide operators with full visibility into agent activities.\n\n---\n\n\n\n## MCP Server Architecture\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Conductor & Orchestration](#conductor-orchestration), [Security & Access Control](#security-gates)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/mcp_server.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_server.py)\n- [mcp/server/aidocs_mcp/service_hub.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/service_hub.py)\n- [mcp/server/aidocs_mcp/tool_discovery.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_discovery.py)\n- [mcp/server/aidocs_mcp/mcp_registry.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_registry.py)\n- [mcp/server/aidocs_mcp/runtime_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n
\n\n# MCP Server Architecture\n\nThe AIDOCS MCP Server is a Python-based Model Context Protocol implementation that provides persistent memory, indexed retrieval, and orchestration capabilities for AI coding agents. It acts as an intermediary layer between AI coding assistants (like Claude Code or OpenCode) and project-specific context, enabling agents to maintain memory across sessions and resume work without re-discovering repository structures.\n\n## Core Architecture Overview\n\nThe MCP Server follows a modular architecture with distinct layers for tool management, security enforcement, and runtime orchestration.\n\n```mermaid\ngraph TD\n subgraph \"MCP Server Core\"\n MS[mcp_server.py
FastMCP Entry Point]\n SH[service_hub.py
Service Hub]\n end\n \n subgraph \"Tool Layer\"\n TD[tool_discovery.py
Tool Discovery]\n CE[server_code_edit_tools.py
Edit Tools]\n CT[server_code_tools.py
Code Tools]\n end\n \n subgraph \"Security Layer\"\n GATE[Gate Architecture
6-Level Cascade]\n end\n \n subgraph \"Runtime Services\"\n RS[runtime_service.py
Runtime Service]\n REG[mcp_registry.py
Registry]\n end\n \n subgraph \"External Integrations\"\n CC[Claude Hook]\n OC[OpenCode Plugin]\n end\n \n MS --> SH\n SH --> TD\n SH --> CE\n SH --> CT\n SH --> RS\n MS --> REG\n CC --> MS\n OC --> MS\n```\n\n资料来源：[mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n\n## Server Entry Point\n\nThe `mcp_server.py` file serves as the primary entry point for the MCP server, initializing FastMCP and registering all available tools and resources.\n\n### Server Initialization\n\nThe server follows this initialization sequence:\n\n1. **Configuration Loading** - Loads `aidocs.toml` from the project root\n2. **Service Hub Initialization** - Establishes the central service coordinator\n3. **Tool Registration** - Discovers and registers all available MCP tools\n4. **Registry Setup** - Configures the MCP server registry for host integrations\n5. **Security Gate Bootstrap** - Initializes the gate architecture\n\n资料来源：[mcp/server/aidocs_mcp/mcp_server.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_server.py)\n\n## Service Hub\n\nThe `service_hub.py` module acts as the central coordinator for all MCP services, providing a unified interface for tool execution, state management, and service discovery.\n\n### Hub Components\n\n| Component | Purpose | File |\n|-----------|---------|------|\n| `hub.code` | Code analysis and symbol operations | server_code_tools.py |\n| `hub.edit` | File editing operations | server_code_edit_tools.py |\n| `hub.runtime` | Session and task management | runtime_service.py |\n| `hub.managed_mode` | Managed/unmanaged mode state | service_hub.py |\n| `hub.session` | Session state management | service_hub.py |\n\n### Managed Mode System\n\nThe Service Hub maintains a managed mode state that controls whether the MCP server operates in supervised or unsupervised mode.\n\n```python\nmanaged = hub.managed_mode.get_mode(project_root)\nif managed.get(\"active\"):\n # Enforce gate architecture\n # Block raw file tools\n # Route through workflow system\n```\n\n资料来源：[mcp/server/aidocs_mcp/service_hub.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/service_hub.py)\n资料来源：[mcp/server/aidocs_mcp/server_code_edit_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_edit_tools.py)\n\n## Tool Discovery\n\nThe `tool_discovery.py` module implements dynamic tool discovery, enabling the MCP server to expose capabilities based on runtime context and project configuration.\n\n### Discovery Process\n\n```mermaid\ngraph LR\n A[Project Root] --> B[Scan aidocs.toml]\n B --> C[Check .MEMORY/ Structure]\n C --> D[Validate Configuration]\n D --> E[Register Available Tools]\n E --> F[Expose via MCP Protocol]\n```\n\n### Available Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| **Code Analysis** | `ai_find`, `ai_get_symbol_snippet`, `ai_get_symbol_info`, `ai_bundle`, `ai_schema_query` | Symbol search and code understanding |\n| **Code Editing** | `ai_create_file`, `ai_edit_lines`, `ai_batch_edit`, `ai_str_replace`, `ai_delete_lines` | File modification operations |\n| **Session Management** | `session_resume_bundle`, `task_begin`, `task_update`, `task_complete` | Workflow orchestration |\n| **Project Operations** | `project_init`, `project_bootstrap_or_resume`, `project_status` | Project lifecycle management |\n\n资料来源：[mcp/server/aidocs_mcp/tool_discovery.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_discovery.py)\n\n## Code Analysis Tools\n\nThe code analysis tools provide AI agents with capabilities to navigate, understand, and investigate codebases.\n\n### Symbol Information Modes\n\nThe `ai_get_symbol_info` tool supports multiple query modes for different levels of symbol detail:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `signature` | Single method signature | Verify function parameters |\n| `signatures` | Multiple method signatures | Compare overloaded methods |\n| `constructor` | Constructor parameters for a type | Understand object instantiation |\n| `constructors` | Batch constructor queries | Analyze multiple types |\n| `enum` | Enum values and members | List state options |\n| `properties` | Entity properties | Understand data structures |\n| `api` | Service API surface | Map service endpoints |\n\n资料来源：[mcp/server/aidocs_mcp/server_code_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_tools.py)\n\n### Investigation Patterns\n\nThe `ai_investigate` tool provides guided navigation with depth and focus parameters:\n\n```python\nai_investigate(concept, depth=..., focus=...)\n# depth: exploration depth\n# focus: symbol-ranked, favors types/classes/structs\n```\n\nInvestigation alternatives:\n- Known symbol name → `ai_find(name, mode=\"symbols\")`\n- Concept/type search → `ai_investigate(concept, depth=..., focus=...)`\n- Architecture mapping → `ai_bundle(path, mode=\"file\"|\"subsystem\")`\n\n## Gate Architecture\n\nThe security layer implements a 6-level cascade gate system that controls tool execution based on context and permissions.\n\n### Gate Levels\n\n| Level | Gate | Action | Condition |\n|-------|------|--------|-----------|\n| 1 | Managed Mode | Block raw file tools when managed | `managed.active == true` |\n| 2 | Infrastructure | Block writes to aidocs.toml, aidocs_mcp/* | Project config files |\n| 3 | Sensitive Files | Block .env, credentials, keys | File extension/name match |\n| 4 | Memory Path | .MEMORY/ reads free, workflow writes intent-gated | Path-based rules |\n| 5 | Read Gate | Per-file discovery, `known_exact_path` bypass | File visibility rules |\n| 6 | Edit Gate | Requires prior read/discovery | Edit sequence validation |\n\n资料来源：[mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n\n### Gate Flow\n\n```mermaid\ngraph TD\n A[Tool Request] --> B{Level 1: Managed Mode?}\n B -->|Unmanaged| C[Execute Tool]\n B -->|Managed| D{Level 2: Infrastructure?}\n D -->|No| E{Level 3: Sensitive Files?}\n D -->|Yes| X[Block + Log]\n E -->|No| F{Level 4: Memory Path?}\n E -->|Yes| X\n F -->|Check| G{Level 5: Read Gate?}\n G -->|No| H{Level 6: Edit Gate?}\n G -->|Yes| C\n H -->|Valid| C\n H -->|Invalid| X\n```\n\n### Configuration Settings\n\nSecurity gates can be configured via the dashboard:\n\n| Setting | Purpose | Risk |\n|---------|---------|------|\n| `dev.dev_mode` | Enables editing AIDOCS MCP server source files | Development only |\n| `security.allow_config_edit` | Allows agents to modify AIDOCS config via tool calls | High - can change gate settings |\n| `security.enforce` | Enables/disables all tool gates | Critical - removes bash allowlist, raw tool blocking |\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n## Runtime Service\n\nThe `runtime_service.py` module manages session lifecycle, task orchestration, and state persistence.\n\n### Session Management\n\n```python\nresult = self.task_begin(\n project_root=project_root,\n session_id=session_id,\n goal=None,\n state=state,\n upcoming=upcoming,\n partial_goals=partial_goals,\n end_goal=end_goal,\n blockers=blockers,\n relevant_files=effective_relevant_files,\n relevant_commands=relevant_commands,\n relevant_snippets=relevant_snippets,\n session_facts=session_facts,\n constraints=constraints,\n include_code_bundle=include_code_bundle,\n include_tests=include_tests,\n)\n```\n\n资料来源：[mcp/server/aidocs_mcp/runtime_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n### State Tracking\n\nThe runtime service maintains:\n\n- **Session State** - Current session identifier and metadata\n- **Task State** - Active tasks, goals, and blockers\n- **Relevant Files** - Files relevant to current task\n- **Relevant Commands** - Commands needed for task completion\n- **Relevant Snippets** - Code snippets for reference\n- **Session Facts** - Accumulated knowledge about the session\n\n### Summary-Only Updates\n\nWhen `summary_only=True`, the runtime service tracks which fields were updated:\n\n```python\nupdated_fields: list[str] = []\nif state is not None:\n updated_fields.append(\"state\")\nif upcoming is not None:\n updated_fields.append(\"upcoming\")\n# ... additional field tracking\n```\n\n## MCP Registry\n\nThe `mcp_registry.py` module provides registry functionality for MCP server discovery and management.\n\n### Registry Capabilities\n\n- **Server Discovery** - Find available MCP servers in the system\n- **Transport Detection** - Identify server transport protocols (stdio, SSE, etc.)\n- **Command Extraction** - Parse install commands for server setup\n- **Server Management** - Track installed and available servers\n\n### Registry UI Components\n\nThe dashboard displays registered servers with:\n\n```tsx\n{srv.name} · {srv.transport} · {srv.command}\n```\n\nSearch results show installation commands and website URLs for discovered servers.\n\n资料来源：[mcp/server/aidocs_mcp/mcp_registry.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_registry.py)\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n## Host Integrations\n\nThe MCP server supports multiple AI coding assistant hosts through platform-specific integrations.\n\n### Claude Code Integration\n\nThe Claude hook (`claude_hook.py`) provides:\n- Prompt injection with action directives\n- Interaction text rendering\n- Workflow summary compilation\n- Tool preamble generation\n\n```python\n_ACTION_DIRECTIVES = {\n \"write_code\": '`ai_create_file` → `ai_get_lines` (read) → `ai_edit_lines` or `ai_batch_edit` (write) → `task_complete`',\n \"trace\": '`ai_find(query, mode=\"references\")` → `ai_trace(query, mode=\"field_flow\"|\"css_class\"|\"api_to_ui\")`',\n \"understand\": '`session_resume_bundle` → `action_surface_current_session_bundle` → `ai_find(query, mode=\"symbols\")` → `ai_get_symbol_snippet`',\n}\n```\n\n### OpenCode Integration\n\nThe OpenCode plugin (`opencode_plugin.js`) provides:\n- Startup state detection\n- Project initialization checks\n- Execution prompt building\n- Interaction text handling\n\n资料来源：[mcp/server/aidocs_mcp/claude_hook.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/claude_hook.py)\n资料来源：[mcp/server/aidocs_mcp/data/opencode_plugin.js](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/data/opencode_plugin.js)\n\n## Memory Model\n\nThe MCP server maintains a hierarchical memory structure within project directories:\n\n```\n/.MEMORY/\n .aidocs/index.aidocs # Session-start router\n sessions/ # Session-specific state\n skills/ # Skill definitions\n plans/ # Task plans\n```\n\n### Memory Path Gate Rules\n\n| Path Type | Read Access | Write Access |\n|-----------|-------------|--------------|\n| `.MEMORY/` | Free (Level 4) | Intent-gated |\n| `aidocs.toml` | Free | Blocked (Level 2) |\n| `aidocs_mcp/*` | Free | Blocked (Level 2) |\n| Project Files | Discovery required | Prior read required |\n\n## Edit Tool Sequencing\n\nSequential line-based edits to the same file can corrupt line numbers. The MCP server enforces:\n\n1. **Single-file line edits** trigger a rejection if the file was already edited this turn\n2. **Batch alternatives** (`ai_batch_edit`, `ai_str_replace`, `ai_batch_str_replace`) handle ordering internally\n3. **Line-independent matching** bypasses the sequential edit check\n\n```python\ndef _check_turn_edited(project_root, path, tool_name):\n \"\"\"Return rejection if file already edited this turn\"\"\"\n managed = hub.managed_mode.get_mode(project_root)\n if not managed.get(\"active\"):\n return None\n # Check session_id and file edit history\n```\n\n资料来源：[mcp/server/aidocs_mcp/server_code_edit_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_edit_tools.py)\n\n## Installation and Setup\n\n### Package Installation\n\n```bash\npip install aidocs-mcp # from PyPI\npip install aidocs-mcp[dev] # with pytest\npip install aidocs-mcp[ast] # with tree-sitter for JS/TS AST parsing\n```\n\n### Setup Command\n\n```bash\naidocs setup # Configures MCP, hooks, project init\naidocs doctor # Verify the install\n```\n\n### Setup Wizard\n\nThe dashboard includes a setup wizard (`SetupWizardPage.tsx`) that guides users through:\n\n1. **Welcome** - Introduction to AIDOCS capabilities\n2. **Project Selection** - Choose project folder\n3. **Configuring** - MCP, hooks, and project structure setup\n4. **Done** - Confirmation with checklist\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n资料来源：[README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n\n## Dashboard Status Indicators\n\nThe CastleShell UI component displays MCP connection status:\n\n```tsx\n\n \n {mcpConnected ? \"MCP connected\" : \"MCP disconnected\"}\n\n```\n\n### Status Bar Components\n\n| Component | Purpose |\n|-----------|---------|\n| `mcpConnected` | Boolean indicating MCP server connection |\n| `projectName` | Current project identifier |\n| `sessionId` | Active session identifier |\n| `activeLayer` | Current execution layer |\n| `saveState` | Persistence state indicator |\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n\n---\n\n\n\n## Dashboard Architecture\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Conductor & Orchestration](#conductor-orchestration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n- [apps/aidocs-dashboard/index.html](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/index.html)\n- [apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n- [apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n- [apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n- [apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)\n- [apps/aidocs-dashboard/src/dashboardCharts.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardCharts.tsx)\n- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n- [apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n- [mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n- [README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n- [README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n- [mcp/server/aidocs_mcp/config_schema.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_schema.py)\n
\n\n# Dashboard Architecture\n\nThe AIDOCS Dashboard is a Tauri-based desktop application that provides a comprehensive user interface for monitoring, managing, and configuring the AIDOCS AI coding assistant infrastructure. It serves as the central control plane for all AIDOCS operations, from initial project setup to ongoing session monitoring and security configuration.\n\n## Overview\n\nThe dashboard functions as a bridge between the user and the underlying MCP (Model Context Protocol) server infrastructure. It enables users to visualize project state, manage AI backends, configure security policies, and monitor token usage across sessions. The architecture follows a clean separation between the Rust-based Tauri backend and the React/TypeScript frontend, providing native desktop performance while maintaining rapid development iteration cycles.\n\nThe dashboard is designed to work in conjunction with the `aidocs-mcp` Python package, which runs as a separate MCP server process. The dashboard communicates with this server via IPC commands to retrieve runtime state and push configuration changes. This decoupled design allows the MCP server to operate independently of the dashboard GUI, enabling headless operation in CI/CD environments or remote servers.\n\n## Technology Stack\n\n### Frontend Layer\n\nThe frontend is built with React 18 and TypeScript, providing type-safe component development and modern hooks-based state management. Vite serves as the build tool and development server, offering fast hot module replacement during development and optimized production builds.\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| UI Framework | React 18 | Component rendering and state management |\n| Language | TypeScript | Type safety and IDE support |\n| Build Tool | Vite | Fast builds and HMR |\n| Styling | CSS Variables + Tailwind | Custom theming with Castle design system |\n| Charts | Custom implementation | Token usage visualization |\n\n资料来源：[apps/aidocs-dashboard/index.html:1-10]()\n\n### Backend Layer\n\nThe Tauri backend is implemented in Rust, providing native system integration capabilities including window management, file system access, and process spawning. The backend exposes a command API that the React frontend invokes via Tauri's invoke mechanism.\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| Runtime | Tauri 2.x | Desktop app framework |\n| Language | Rust | Backend command implementation |\n| IPC | Tauri Commands | Frontend-backend communication |\n| Window | WebView2/WebKit | Render React frontend |\n\n资料来源：[README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n\n## Architecture Components\n\n### Component Hierarchy\n\n```mermaid\ngraph TD\n A[Tauri Backend
main.rs] --> B[React App
App.tsx]\n B --> C[CastleShell
Navigation Framework]\n C --> D[OverviewPage
Project Overview]\n C --> E[RegistryPage
MCP Server Registry]\n C --> F[ConductorPage
Backend Routing]\n C --> G[RBACPage
Access Control]\n C --> H[TomlConfigsPage
TOML Editor]\n C --> I[UsagePage
Token Analytics]\n C --> J[SetupWizardPage
Initial Setup]\n C --> K[dashboardModals
Confirmation Dialogs]\n \n L[StatusBar
MCP Status] -.-> C\n M[ContextRail
Sidebar Info] -.-> C\n N[CommandPalette] -.-> C\n```\n\n### CastleShell Navigation Framework\n\nThe `CastleShell` component serves as the primary layout container, providing consistent navigation, status indication, and context management across all dashboard pages. It implements a tab-based navigation system with optional managed mode indicators.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n\n#### Navigation Types\n\n```typescript\ntype NavKey = \"overview\" | \"registry\" | \"conductor\" | \"rbac\" | \n \"configs\" | \"usage\" | \"wizard\";\n```\n\n#### Shell Props Interface\n\n| Prop | Type | Required | Description |\n|------|------|----------|-------------|\n| `active` | `NavKey` | Yes | Currently selected navigation tab |\n| `onSelect` | `(key: NavKey) => void` | Yes | Callback when navigation changes |\n| `counts` | `CastleNavCounts` | No | Badge counts for each section |\n| `managedMode` | `boolean` | No | Visual indicator for managed mode state |\n| `version` | `string` | No | AIDOCS version display |\n| `mcpConnected` | `boolean` | Yes | MCP server connection status |\n| `activeLayer` | `string` | No | Current active layer indicator |\n| `saveState` | `string` | No | Auto-save state indicator |\n| `contextRail` | `ReactNode` | No | Optional sidebar content |\n\n### Status Bar\n\nThe status bar component provides real-time connection status and contextual information at the bottom of the application window. It displays MCP connection state with visual indicators and supports tooltip-based detailed status views.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx:32-54]()\n\n```typescript\ntype CastleStatusBarProps = {\n mcpConnected: boolean;\n projectName?: string;\n sessionId?: string;\n activeLayer?: string;\n saveState?: string;\n};\n```\n\n## Dashboard Pages\n\n### Overview Page\n\nThe Overview page provides a snapshot of the current project state, including recent execution events, active sessions, and capability utilization. It renders a runtime snapshot retrieved from the MCP server via the dashboard API.\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n\n```mermaid\ngraph LR\n A[MCP Server] -->|Runtime Snapshot| B[OverviewPage]\n B --> C[Project Info Panel]\n B --> D[Recent Execution Table]\n B --> E[Capability Stats]\n```\n\n### Registry Page\n\nThe Registry page enables browsing and searching the MCP server registry. Users can view installed servers, search for available servers by name, and initiate installations directly from the interface.\n\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n#### Registry Search Result Structure\n\n```typescript\ninterface RegistrySearchResult {\n name: string;\n install_commands?: Array<{\n command?: string;\n type?: string;\n }>;\n website_url?: string;\n}\n```\n\n### Conductor Page\n\nThe Conductor page manages backend routing configuration, allowing users to select between different AI backends (Claude, Codex, OpenCode) and configure per-backend model settings. It provides a visual representation of the routing lanes and their blocked/run states.\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n\n#### Conductor Configuration Model\n\n```typescript\ninterface ConductorConfig {\n backend: \"claude\" | \"codex\" | \"opencode\";\n models: {\n claude: string;\n codex: string;\n opencode: string;\n };\n lanes: ConductorLane[];\n}\n```\n\n### RBAC Page\n\nThe Role-Based Access Control page displays and manages permission grants, showing which sessions and tasks have been granted specific capabilities. It supports both sticky (persistent) and once (single-use) grant types with expiration tracking.\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n#### RBAC Entry Display\n\n| Field | Description |\n|-------|-------------|\n| `session_id` | Session identifier with optional task ID |\n| `sticky` | Sticky grants persist across sessions |\n| `created_at` | Grant creation timestamp |\n| `expires_at` | Optional expiration timestamp |\n\n### TOML Configuration Page\n\nThe TOML Configuration page provides a visual editor for AIDOCS TOML documents, organized by category. Users can view and manage configuration entries for Action Tokens, Action Hooks, and Language Descriptors.\n\n资料来源：[apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)\n\n#### Configuration Categories\n\n| Category | Purpose |\n|----------|---------|\n| `intent_tokens` | Action token definitions for prompt classification |\n| `gate_messages` | Action hook message templates |\n| `language_descriptors` | Language-specific behavior descriptors |\n\n### Usage Page\n\nThe Usage page visualizes token consumption across sessions, providing charts for input/output token ratios, session breakdowns, and tool-specific usage. It supports both bar and pie chart modes for different visualization preferences.\n\n资料来源：[apps/aidocs-dashboard/src/dashboardCharts.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardCharts.tsx)\n\n#### Usage Data Model\n\n```typescript\ninterface TokenEstimates {\n tokens_in: number;\n tokens_out: number;\n tokens_in_calls?: number;\n tokens_out_calls?: number;\n}\n\ninterface SessionBreakdown {\n session_id: string;\n total: number;\n events: number;\n}\n```\n\n### Setup Wizard\n\nThe Setup Wizard guides users through initial AIDOCS configuration with a multi-step flow. It handles project path selection, environment detection, and host authentication verification.\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n#### Wizard Steps\n\n```mermaid\ngraph LR\n A[welcome] --> B[project]\n B --> C[environment]\n C --> D[configure]\n D --> E[done]\n \n A -->|Get Started| B\n B -->|Configure| D\n E -->|Open Dashboard| F[Dashboard]\n```\n\n#### Setup Step Configuration\n\n| Step | Purpose |\n|------|---------|\n| `welcome` | Introduction and value proposition |\n| `project` | Project folder selection |\n| `environment` | Runtime detection (Node.js, CLI agents) |\n| `configure` | MCP, hooks, and project structure setup |\n| `done` | Confirmation and next steps |\n\n#### Environment Detection\n\nThe wizard detects available AI hosts and their authentication status:\n\n```typescript\ninterface HostDetection {\n name: string;\n found: boolean;\n authenticated: boolean;\n path?: string;\n installable?: boolean;\n}\n```\n\nSupported hosts include Claude and OpenAI platforms, with sign-in buttons linking to respective authentication pages.\n\n### Modal Components\n\nSecurity-sensitive operations require explicit user confirmation through modal dialogs. The dashboard provides dedicated confirmation modals for dangerous configuration changes.\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n#### Protected Settings\n\n| Setting | Risk Description |\n|---------|------------------|\n| `dev.dev_mode` | Enables editing AIDOCS MCP server source files |\n| `security.allow_config_edit` | Allows agents to modify AIDOCS config via tool calls |\n| `security.enforce` | Disabling removes tool gates and destructive command protection |\n\n#### Loading Overlay\n\nThe `LoadingOverlay` component displays during snapshot refresh operations:\n\n```typescript\nexport function LoadingOverlay() {\n return (\n
\n
\n
\n Loading runtime snapshot\n Refreshing project, session, and settings state.\n
\n
\n );\n}\n```\n\n## MCP Integration\n\nThe dashboard communicates with the AIDOCS MCP server through Tauri's IPC mechanism. The MCP server exposes tools for project management, session control, memory operations, and code analysis.\n\n### Core MCP Tools\n\n| Category | Tools |\n|----------|-------|\n| **Session** | `ai_session` (list, create, connect, update, release, resume) |\n| **Memory** | `memory_read`, `memory_capture`, `memory_search` |\n| **Project** | `project_init`, `project_bootstrap_or_resume`, `project_sync_indexes` |\n| **Code** | `ai_find`, `ai_get_lines`, `ai_edit_lines`, `ai_batch_edit` |\n| **Analysis** | `ai_trace`, `ai_bundle`, `schema_query` |\n\n资料来源：[mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n\n### Configuration Schema\n\nThe MCP server maintains configuration entries with support for various scopes and security classifications:\n\n资料来源：[mcp/server/aidocs_mcp/config_schema.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_schema.py)\n\n#### Security-Sensitive Settings\n\n```python\n\"dev.dev_mode\": _setting(\n type=\"boolean\",\n default=False,\n description=\"[T0 DASHBOARD-ONLY] Unlocks AIDOCS infrastructure source editing.\",\n security_sensitive=True,\n dashboard_only=True,\n scope=[\"project\"],\n)\n```\n\n#### Tool Output Configuration\n\n| Setting | Default | Purpose |\n|---------|---------|---------|\n| `tool_output.pretty` | `false` | Dual-channel pretty rendering |\n| `tool_output.show_tool_name` | `false` | Inline debug markers |\n| `tool_output.show_duration` | `false` | Per-call duration display |\n| `tool_output.show_tokens` | `false` | Token count estimation |\n\n## Build and Deployment\n\n### Development Mode\n\n```bash\ncd apps/aidocs-dashboard\nnpm install\nnpm run tauri dev\n```\n\n### Production Build\n\n```bash\nnpm run tauri build\n```\n\nThe build process compiles the Rust backend and bundles the React frontend into a native executable.\n\n### Launch Scripts\n\n| Platform | Script |\n|----------|--------|\n| Windows | `core\\scripts\\launch-dashboard.cmd` |\n| Linux/macOS | `bash core/scripts/launch-dashboard.sh` |\n\n资料来源：[README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard as React UI\n participant Tauri as Tauri Backend\n participant MCP as MCP Server\n participant Project as Project Files\n \n User->>Dashboard: Navigate to page\n Dashboard->>Tauri: invoke(\"command\", args)\n Tauri->>MCP: IPC / Tool Calls\n MCP->>Project: File System Operations\n Project-->>MCP: State / Config\n MCP-->>Tauri: Response\n Tauri-->>Dashboard: Serialized Data\n Dashboard-->>User: Rendered UI\n```\n\n## Security Architecture\n\nThe dashboard implements several security measures:\n\n1. **T0 Dashboard-Only Settings**: Certain configuration changes are restricted to the dashboard and cannot be modified by agents through NLP or tool calls.\n\n2. **Confirmation Modals**: Security-sensitive operations require explicit user confirmation before execution.\n\n3. **Output Guard**: The MCP server includes output filtering to detect and redact sensitive content patterns.\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n\n#### Sensitive Content Patterns\n\n| Pattern | Detection |\n|---------|-----------|\n| `env_file_content` | Environment variables with 8+ character values |\n| `ssh_config` | SSH host configurations and identity files |\n\n## Design System\n\nThe dashboard uses the \"Castle\" design system with a dark theme and muted accent colors:\n\n| Token | Value | Usage |\n|-------|-------|-------|\n| `--castle-line` | Border color | Panel separators |\n| `--castle-mute` | Muted text | Secondary labels |\n| `--castle-allow` | Green | Success states |\n| `--castle-deny` | Red | Error states |\n\nThe design system is implemented via CSS custom properties, enabling consistent theming across all components.\n\n---\n\n\n\n## Memory System\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Indexing & Retrieval System](#indexing-retrieval)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/.MEMORY/.aidocs/memory-system.aidocs](https://github.com/cristian1991/AIDOCS/blob/main/core/.MEMORY/.aidocs/memory-system.aidocs)\n- [mcp/server/aidocs_mcp/memory_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/memory_store.py)\n- [mcp/server/aidocs_mcp/session_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/session_store.py)\n- [mcp/server/aidocs_mcp/memory_discovery.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/memory_discovery.py)\n- [mcp/server/aidocs_mcp/aidocs_nlp/consumers/memory_surfacer.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/aidocs_nlp/consumers/memory_surfacer.py)\n- [mcp/server/aidocs_mcp/runtime_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n
\n\n# Memory System\n\n## Overview\n\nThe AIDOCS Memory System provides persistent memory infrastructure for AI coding agents, enabling them to resume work across sessions without rediscovering repositories from scratch. The system organizes agent-generated knowledge into structured directories, validates memory file placement, detects stale content, and surfaces relevant memories during task execution.\n\nMemory is stored in a `.MEMORY` directory at the project root, containing structured subdirectories for sessions, archived work, rules, standards, lessons, and roadmaps.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Memory Storage Layer\"\n MEM[.MEMORY/]\n SESS[.MEMORY/sessions/]\n ARCH[.MEMORY/archive/]\n RULES[.MEMORY/rules/]\n STD[.MEMORY/standards/]\n LESS[.MEMORY/lessons/]\n ROAD[.MEMORY/roadmaps/]\n end\n \n subgraph \"MCP Tools\"\n MS[memory_store.py]\n SS[session_store.py]\n MD[memory_discovery.py]\n MF[memory_surfacer.py]\n end\n \n subgraph \"Validation & Scanning\"\n RS[runtime_service.py
memory_validator]\n SF[stale_finder]\n GP[pattern_scanner]\n end\n \n MEM --> SESS\n MEM --> ARCH\n MEM --> RULES\n MEM --> STD\n MEM --> LESS\n MEM --> ROAD\n \n SESS --> MS\n ARCH --> SS\n MS --> MD\n MD --> MF\n RS --> GP\n```\n\n## Directory Structure\n\nThe Memory System enforces a specific directory structure to maintain organized, retrievable knowledge:\n\n| Directory | Purpose |\n|-----------|---------|\n| `.MEMORY/sessions//` | Active session files |\n| `.MEMORY/archive/sessions//` | Archived session data |\n| `.MEMORY/rules/` | Coding rules and guidelines |\n| `.MEMORY/standards/` | Project standards documentation |\n| `.MEMORY/lessons/` | Learned lessons and post-mortems |\n| `.MEMORY/roadmaps/` | Future plans and milestones |\n\n资料来源：[runtime_service.py:24-28](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Memory File Naming Rules\n\nThe system enforces strict placement rules for memory files. These rules ensure consistent organization and enable reliable retrieval.\n\n### File Location Rules\n\n| File Name | Valid Location | Path Segments |\n|-----------|---------------|---------------|\n| `SESSION.md` | `.MEMORY/sessions//` | 3 segments |\n| `CONTEXT.md` | `.MEMORY/sessions//` | 3 segments |\n| `TODO.md` | `.MEMORY/sessions//` | 3 segments |\n| `NOTES.md` | `.MEMORY/sessions//` | 3 segments |\n| `PLAN.md` | `.MEMORY/sessions//plans/` | 4 segments |\n\n资料来源：[runtime_service.py:47-67](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n### Validation Logic\n\n```python\n# For session files (SESSION.md, CONTEXT.md, TODO.md, NOTES.md)\nok = (\n (len(parts) == 3 and parts[0] == \"sessions\")\n or (len(parts) == 4 and parts[:2] == (\"archive\", \"sessions\"))\n)\n\n# For PLAN.md\nok = (\n (len(parts) == 4 and parts[0] == \"sessions\" and parts[2] == \"plans\")\n or (len(parts) == 5 and parts[:2] == (\"archive\", \"sessions\") and parts[3] == \"plans\")\n)\n```\n\n资料来源：[runtime_service.py:58-67](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Header Pattern Detection\n\nThe system scans memory files for header patterns that indicate the type of content and its organization. These patterns help categorize and prioritize memory retrieval.\n\n### G2 Patterns (Work-in-Progress Headers)\n\nFiles with these header patterns indicate ongoing investigation or active work:\n\n| Pattern | Keywords |\n|---------|----------|\n| `re.IGNORECASE` | `investigating`, `reading`, `trying`, `exploring`, `debugging`, `checking`, `figuring`, `attempting`, `wip`, `todo:`, `notes:` |\n\n```python\ng2_pattern = re.compile(\n r\"^#+\\s+(investigating|reading|trying|exploring|debugging|\"\n r\"checking|figuring|attempting|wip|todo:|notes?:)\\b\",\n re.IGNORECASE,\n)\n```\n\n### G3 Patterns (Planning Headers)\n\nFiles with these headers indicate structured planning or backlog items:\n\n| Pattern | Keywords |\n|---------|----------|\n| `re.IGNORECASE` | `plan`, `phase`, `step`, `tasks`, `backlog`, `roadmap`, `milestone` |\n\n```python\ng3_pattern = re.compile(\n r\"^#+\\s+(plan|phase\\s*\\d|step\\s*\\d|steps|tasks|backlog|\"\n r\"roadmap|milestone)\\b\",\n re.IGNORECASE,\n)\n```\n\n### Skipped Directories\n\nCertain directories are excluded from pattern validation as they are expected to contain these patterns:\n\n| Pattern Type | Skipped Directories |\n|--------------|---------------------|\n| G2 | `sessions`, `archive`, `.aidocs`, `.index` |\n| G3 | `sessions`, `archive`, `.aidocs`, `.index`, `roadmaps` |\n\n资料来源：[runtime_service.py:29-35](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Memory Validation API\n\n### `memory_structure_checker`\n\nValidates the entire memory directory structure for compliance with naming and placement rules.\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `project_root` | `Path` | — | Project root path |\n| `memory_root` | `str` | `\".MEMORY\"` | Memory directory name |\n\n**Returns:**\n\n```python\n{\n \"ok\": bool,\n \"memory_root\": str,\n \"violations\": [\n {\n \"path\": str,\n \"name\": str,\n \"expected_location\": str\n }\n ],\n \"count\": int,\n \"error\": Optional[str]\n}\n```\n\n**Error States:**\n\n| Error Code | Description |\n|------------|-------------|\n| `memory_root_not_found` | The `.MEMORY` directory does not exist in the project |\n\n资料来源：[runtime_service.py:12-21](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Stale Memory Detection\n\n### `memory_stale_finder`\n\nIdentifies memory files that have not been modified in a configurable time period. This helps maintain memory freshness and prevents outdated information from being surfaced.\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `project_root` | `Path` | — | Project root path |\n| `stale_after_days` | `int` | `90` | Days after which memory is considered stale |\n| `memory_root` | `str` | `\".MEMORY\"` | Memory directory name |\n\n**Rationale:**\n\n> \"Memory drifts: rules written months ago for a now-dead workflow are worse than no rules at all.\"\n\n资料来源：[runtime_service.py:106-108](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Memory Surfacing\n\nThe `memory_surfacer` module provides retrieval capabilities for surfacing relevant memories based on context. It consumes NLP-processed data to match current task context with stored memories.\n\n### Key Responsibilities\n\n- Match query context against stored memory content\n- Rank memories by relevance\n- Filter memories by type, age, and source\n- Handle deduplication across sessions\n\n```python\n# Conceptual flow\nuser_query → context_extraction → memory_search → relevance_ranking → filtered_results\n```\n\n资料来源：[memory_surfacer.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/aidocs_nlp/consumers/memory_surfacer.py)\n\n## Memory Discovery\n\nThe discovery module (`memory_discovery.py`) provides mechanisms to locate and index memory files across the project.\n\n### Discovery Capabilities\n\n- Recursive traversal of `.MEMORY` directory tree\n- Filtering by memory type (sessions, rules, standards, lessons)\n- Metadata extraction from memory file headers\n- Cross-reference identification between memories\n\n## Session Store\n\nSession storage maintains the state of agent sessions across the memory hierarchy.\n\n### Session File Types\n\n| File | Purpose | Location |\n|------|---------|----------|\n| `SESSION.md` | Session metadata and context | `.MEMORY/sessions//` |\n| `CONTEXT.md` | Current working context | `.MEMORY/sessions//` |\n| `TODO.md` | Task backlog | `.MEMORY/sessions//` |\n| `NOTES.md` | Session observations | `.MEMORY/sessions//` |\n| `PLAN.md` | Session plan | `.MEMORY/sessions//plans/` |\n\n资料来源：[session_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/session_store.py)\n\n## Security Considerations\n\nThe Memory System integrates with the security guard infrastructure to protect against prompt injection and sensitive data leakage.\n\n### Pattern Scanning Integration\n\nMemory files are scanned for:\n\n- **Prompt injection patterns** (role hijack, instruction injection, delimiter escape)\n- **Sensitive content** (env file patterns, SSH config)\n- **Capability declarations** (file operations, command execution, database access)\n\nSee [Security Gates](Security-Gates) for detailed pattern definitions.\n\n## Workflow\n\n```mermaid\ngraph LR\n A[Agent Session Start] --> B[Create/Load Session]\n B --> C[Memory Discovery]\n C --> D[Relevant Memories Surfaced]\n D --> E[Agent Work]\n E --> F[Update Memory Files]\n F --> G[Structure Validation]\n G --> H[Archive or Keep Active]\n H --> I[Session End]\n```\n\n## Configuration\n\n### Memory Root Location\n\nDefault: `.MEMORY` (relative to project root)\n\n### Validation Strictness\n\nThe system performs validation on:\n- File naming conventions\n- Directory placement\n- Path segment counts\n- Header pattern compliance\n\n### Staleness Threshold\n\nDefault: 90 days\nConfigurable via `stale_after_days` parameter\n\n## Related Components\n\n| Component | Relationship |\n|-----------|--------------|\n| [MCP Runtime](MCP-Runtime) | Provides tools for memory operations |\n| [Security Gates](Security-Gates) | Scans memory content for risks |\n| [Conductor](Conductor) | Uses memory for task orchestration |\n| [Dashboard](Dashboard) | Visualizes memory state and health |\n\n---\n\n\n\n## Conductor & Orchestration\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server), [Security & Access Control](#security-gates), [Dashboard Architecture](#dashboard)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/conductor_comms.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/conductor_comms.py)\n- [mcp/server/aidocs_mcp/runtime_orchestration_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_orchestration_service.py)\n- [mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py)\n- [mcp/server/aidocs_mcp/plan_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/plan_conductor.py)\n- [mcp/server/aidocs_mcp/co_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/co_conductor.py)\n- [mcp/server/aidocs_mcp/agent_orchestrator.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/agent_orchestrator.py)\n- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n- [apps/aidocs-dashboard/src-tauri/src/main.rs](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src-tauri/src/main.rs)\n
\n\n# Conductor & Orchestration\n\nThe Conductor & Orchestration system is the central coordination layer in AIDOCS, providing persistent, long-lived agent orchestration across coding sessions. Rather than spawning isolated one-off agent calls, the Conductor acts as a supervisory intelligence that plans, delegates, monitors, and resolves conflicts among multiple lane-based worker agents.\n\n## Overview\n\nThe Conductor orchestrates AI coding work by:\n\n- Maintaining persistent memory across sessions\n- Creating and managing execution **lanes** (isolated task pipelines)\n- Routing tasks to appropriate backend models (Claude, Codex, OpenCode)\n- Resolving inter-lane conflicts and blocking conditions\n- Providing a real-time chat interface for human-in-the-loop oversight\n\n资料来源：[README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n\n## Architecture\n\nThe orchestration system is composed of multiple layers:\n\n```mermaid\ngraph TD\n subgraph \"Frontend (Dashboard)\"\n CP[ConductorPage]\n CH[ConductorChat]\n LP[Lanes Panel]\n TCP[ToolCallsPanel]\n end\n \n subgraph \"Backend (Rust/Tauri)\"\n MS[Main State]\n CS[ConductorState]\n end\n \n subgraph \"MCP Server (Python)\"\n ROS[RuntimeOrchestrationService]\n RCDS[RuntimeConductorDispatchService]\n PC[PlanConductor]\n CC[CoConductor]\n AC[AgentOrchestrator]\n CCM[ConductorComms]\n end\n \n CP -->|Tauri Commands| MS\n CH -->|conductor_start/send| CS\n CS -->|MCP Tools| ROS\n ROS --> RCDS\n RCDS --> PC\n RCDS --> CC\n PC --> AC\n CC --> AC\n AC --> CCM\n```\n\n## Core Components\n\n### PlanConductor\n\nThe `PlanConductor` is responsible for high-level task planning. It receives goals and breaks them into discrete execution lanes, establishing dependencies and ordering constraints.\n\n**Key Responsibilities:**\n\n- Parse incoming task descriptions\n- Generate execution plans with lane definitions\n- Set lane blocking conditions\n- Track plan progress through completion\n\n资料来源：[mcp/server/aidocs_mcp/plan_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/plan_conductor.py)\n\n### CoConductor\n\nThe `CoConductor` operates as a parallel supervisory agent that assists the primary conductor. It handles secondary routing decisions and provides fallback reasoning when the main conductor encounters ambiguous situations.\n\n**Key Responsibilities:**\n\n- Parallel task assessment\n- Fallback routing decisions\n- Conflict resolution between lanes\n- Escalation handling\n\n资料来源：[mcp/server/aidocs_mcp/co_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/co_conductor.py)\n\n### RuntimeOrchestrationService\n\nThe `RuntimeOrchestrationService` serves as the central service entry point for all orchestration operations. It manages session state and dispatches requests to appropriate conductor components.\n\n**Key Responsibilities:**\n\n- Session lifecycle management\n- Service initialization and teardown\n- Request routing to PlanConductor/CoConductor\n- State synchronization with dashboard\n\n资料来源：[mcp/server/aidocs_mcp/runtime_orchestration_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_orchestration_service.py)\n\n### RuntimeConductorDispatchService\n\nThe `RuntimeConductorDispatchService` handles the low-level dispatch of tasks to specific backends. It manages connection pooling, request queuing, and response aggregation.\n\n**Key Responsibilities:**\n\n- Backend selection (claude/codex/opencode)\n- Request dispatch and retry logic\n- Response aggregation\n- Connection state management\n\n资料来源：[mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py)\n\n### AgentOrchestrator\n\nThe `AgentOrchestrator` coordinates the actual execution of tasks within each lane. It manages tool calls, maintains execution context, and handles error recovery.\n\n**Key Responsibilities:**\n\n- Lane-level task execution\n- Tool call management and policy enforcement\n- Execution state persistence\n- Error recovery and retry\n\n资料来源：[mcp/server/aidocs_mcp/agent_orchestrator.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/agent_orchestrator.py)\n\n### ConductorComms\n\nThe `ConductorComms` module handles inter-process and inter-service communication. It provides the messaging substrate for conductor components and the dashboard.\n\n**Key Responsibilities:**\n\n- Message formatting and serialization\n- Transport abstraction\n- Session message routing\n- Event broadcasting\n\n资料来源：[mcp/server/aidocs_mcp/conductor_comms.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/conductor_comms.py)\n\n## State Management (Rust Backend)\n\nThe Tauri backend maintains conductor state across sessions using a global state map.\n\n```mermaid\ngraph TD\n subgraph \"ConductorState\"\n PID[process: Option Child]\n OUT[output: Vec f64, String, String]\n BE[backend: Option String]\n MD[model: Option String]\n PORT[opencode_port: Option u16]\n CSID[claude_session_id: Option String]\n COXSID[codex_session_id: Option String]\n SIF[codex_send_in_flight: bool]\n end\n \n subgraph \"Global State\"\n CONDUCTORS[HashMap ConductorKey ConductorState]\n end\n \n CONDUCTORS -->|key: (root, session_id)| PID\n CONDUCTORS -->|key: (root, session_id)| BE\n```\n\n### ConductorKey Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `root` | `PathBuf` | Project root directory |\n| `session_id` | `String` | Unique session identifier |\n\n### ConductorState Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `process` | `Option` | Active child process handle |\n| `output` | `Vec<(f64, String, String)>` | Execution output with timing |\n| `backend` | `Option` | Current backend (claude/codex/opencode) |\n| `model` | `Option` | Selected model identifier |\n| `opencode_port` | `Option` | OpenCode server port |\n| `claude_session_id` | `Option` | Claude session identifier |\n| `codex_session_id` | `Option` | Codex session identifier |\n| `codex_send_in_flight` | `bool` | Request in-flight flag |\n\n资料来源：[apps/aidocs-dashboard/src-tauri/src/main.rs:1-50](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src-tauri/src/main.rs)\n\n## Lanes System\n\nLanes are the fundamental execution unit in the orchestration system. Each lane represents an isolated task pipeline that can run independently or with dependencies on other lanes.\n\n### Lane States\n\n| State | Description |\n|-------|-------------|\n| `runnable` | Lane can execute immediately |\n| `blocked` | Lane waiting on dependencies or conditions |\n| `running` | Lane actively executing |\n| `completed` | Lane finished successfully |\n| `failed` | Lane encountered an error |\n\n### Blocking Reasons\n\nLanes can be blocked by:\n\n- Unmet dependency lanes\n- Resource constraints\n- Security policy gates\n- External input waiting\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n\n## Dashboard Integration\n\n### ConductorPage\n\nThe `ConductorPage` component provides the main dashboard interface for conductor operations.\n\n```typescript\ninterface ConductorPageProps {\n progressPercent: number;\n conductorLanes: Lane[];\n runnableLaneIds: string[];\n blockedReasons: Record;\n recentExecution: ExecutionEvent[];\n configEntries: ConfigEntry[];\n selectedSessionId: string;\n projectRoot: string;\n sessionId: string;\n}\n```\n\n**Components:**\n\n| Component | Purpose |\n|-----------|---------|\n| `Lanes Panel` | Visual display of lane states and progress |\n| `ConductorChat` | Real-time chat interface with conductor |\n| `ToolCallsPanel` | View recent tool execution events |\n| `ConductorSummary` | Progress statistics |\n\n### ConductorChat\n\nThe chat interface supports multiple message recipients:\n\n| Recipient | Description |\n|-----------|-------------|\n| `conductor` | Direct to primary conductor |\n| `co-conductor` | Direct to co-conductor assistant |\n| `both` | Broadcast to both conductors |\n\nMessage roles displayed:\n\n| Role | Color | Usage |\n|------|-------|-------|\n| `king` | `#f5c518` | High-priority directive |\n| `conductor` | `var(--accent-bright)` | Standard conductor messages |\n| `co-conductor` | `#78aaff` | Co-conductor responses |\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n\n## Multi-Backend Routing\n\nThe orchestration system supports routing to different AI backends:\n\n### Supported Backends\n\n| Backend | Configuration Key | Model Key |\n|---------|-------------------|-----------|\n| Claude | `conductor.backend` | `conductor.claude_model` |\n| Codex | `conductor.backend` | `conductor.codex_model` |\n| OpenCode | `conductor.backend` | N/A (uses port) |\n\n### Routing Configuration\n\n```typescript\ninterface RouteConfig {\n backend: \"claude\" | \"codex\" | \"opencode\";\n models: {\n claude: string;\n codex: string;\n opencode: string;\n };\n}\n```\n\n### Backend Selection Logic\n\n1. Check `conductor.backend` config for default\n2. Evaluate task requirements\n3. Consider model capabilities\n4. Apply routing policies\n\n## Execution Events\n\nExecution events track all conductor activity:\n\n### Event Structure\n\n```typescript\ninterface ExecutionEvent {\n event_id: string;\n event_kind: string;\n capability_name?: string;\n action_kind?: string;\n session_id: string;\n observed_at: string;\n lane?: string;\n audit?: {\n logicalMode?: string;\n nativeMode?: string;\n fallbackUsed?: boolean;\n };\n payload?: {\n args_preview?: string;\n result_preview?: string;\n result_summary?: string;\n };\n}\n```\n\n### Audit Trail\n\n| Mode | Description |\n|------|-------------|\n| `logicalMode` | Logical routing layer used |\n| `nativeMode` | Native tool selection |\n| `fallbackUsed` | Whether fallback was triggered |\n\n资料来源：[apps/aidocs-dashboard/src/ExecutionPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ExecutionPage.tsx)\n\n## Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard\n participant Conductor\n participant PlanConductor\n participant CoConductor\n participant AgentOrchestrator\n participant Backend\n\n User->>Dashboard: Send message/goal\n Dashboard->>Conductor: route_prompt(goal)\n Conductor->>PlanConductor: create_plan(goal)\n PlanConductor-->>Conductor: lanes[], dependencies[]\n Conductor->>CoConductor: validate_plan(lanes)\n CoConductor-->>Conductor: validation_result\n \n loop For each runnable lane\n Conductor->>AgentOrchestrator: execute_lane(lane)\n AgentOrchestrator->>Backend: dispatch(task)\n Backend-->>AgentOrchestrator: result\n AgentOrchestrator-->>Conductor: lane_status\n end\n \n Conductor-->>Dashboard: progress_update\n Dashboard->>User: Display results\n```\n\n## Message Flow\n\nMessages flow through the system with role-based routing:\n\n```mermaid\ngraph LR\n subgraph \"Dashboard\"\n CH[ConductorChat]\n end\n \n subgraph \"Backend\"\n CCM[ConductorComms]\n PC[PlanConductor]\n CC[CoConductor]\n end\n \n CH-->|Message| CCM\n CCM-->|Route| PC\n CCM-->|Route| CC\n \n PC-->|Plan| CCM\n CC-->|Response| CCM\n CCM-->|Aggregated| CH\n```\n\n## Configuration\n\n### Conductor Settings\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `conductor.backend` | string | `claude` | Default execution backend |\n| `conductor.claude_model` | string | - | Claude model identifier |\n| `conductor.codex_model` | string | - | Codex model identifier |\n\n### Lane Configuration\n\nLanes are configured via the plan conductor with:\n\n- **Dependencies**: Ordered constraint list\n- **Blocking conditions**: Runtime predicates\n- **Resource requirements**: CPU, memory, tool access\n- **Timeout settings**: Per-lane execution limits\n\n## Best Practices\n\n### Session Management\n\n1. **Use persistent sessions** - Resume work instead of restarting\n2. **Monitor lane states** - Watch for blocking conditions\n3. **Review execution events** - Track capability usage\n\n### Error Handling\n\n1. **Check blocked reasons** - First step in debugging stuck lanes\n2. **Review fallback usage** - Indicates routing issues\n3. **Examine audit trails** - Understand routing decisions\n\n### Security\n\n- Security gates apply to all conductor operations\n- Lane isolation prevents cross-task contamination\n- RBAC controls conductor access\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n---\n\n\n\n## Security & Access Control\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server), [Conductor & Orchestration](#conductor-orchestration), [Configuration Management](#configuration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/access_gate.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/access_gate.py)\n- [mcp/server/aidocs_mcp/heuristic_judge.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/heuristic_judge.py)\n- [mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n- [mcp/server/aidocs_mcp/rbac.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/rbac.py)\n- [mcp/server/aidocs_mcp/enforcement_pkg/controller.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/enforcement_pkg/controller.py)\n- [mcp/server/aidocs_mcp/tool_policy.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_policy.py)\n- [mcp/server/aidocs_mcp/permission_catalog.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/permission_catalog.py)\n
\n\n# Security & Access Control\n\nAIDOCS implements a layered security architecture designed to govern AI agent behavior within development environments. The system provides fine-grained control over tool usage, bash command execution, prompt integrity, and permission escalation through multiple enforcement mechanisms working in concert.\n\n## Overview\n\nThe Security & Access Control subsystem in AIDOCS operates as a multi-stage guard system that intercepts and evaluates agent requests before they reach system resources. It combines heuristic analysis, role-based access control (RBAC), tool policy enforcement, and output sanitization to create a defense-in-depth approach for AI-assisted development.\n\n### Core Security Components\n\n| Component | File | Primary Responsibility |\n|-----------|------|------------------------|\n| Access Gate | `access_gate.py` | Central entry point for permission checks |\n| Heuristic Judge | `heuristic_judge.py` | Risk scoring based on request patterns |\n| Output Guard | `output_guard.py` | Content filtering and redaction |\n| RBAC Engine | `rbac.py` | Role and permission management |\n| Enforcement Controller | `controller.py` | Orchestrates policy enforcement |\n| Tool Policy | `tool_policy.py` | Bash command allowlist/denylist |\n| Permission Catalog | `permission_catalog.py` | Defines available permissions |\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Agent Request] --> B[Access Gate]\n B --> C{Security Enabled?}\n C -->|No| Z[Allow]\n C -->|Yes| D[Heuristic Judge]\n D --> E{Risk Score}\n E -->|Low| F[RBAC Check]\n E -->|Medium| G[Gate Permission Required]\n E -->|High| H[Block]\n F --> I{Has Permission?}\n I -->|Yes| J[Tool Policy Check]\n I -->|No| H\n J --> K{Command Allowed?}\n K -->|Yes| L[Execute]\n K -->|No| H\n G --> M[Request Approval]\n M -->|Approved| L\n M -->|Denied| H\n L --> N[Output Guard]\n N --> O[Filtered Response]\n```\n\n## Access Gate\n\nThe Access Gate serves as the central authorization checkpoint for all agent requests. It evaluates incoming requests against the current security posture and determines whether additional verification is needed.\n\n### Configuration Paths\n\nThe system exposes security settings through configurable paths that control different aspects of enforcement:\n\n| Setting Path | Purpose | Risk Level |\n|--------------|---------|------------|\n| `dev.dev_mode` | Enables editing of AIDOCS MCP server source files | High |\n| `security.allow_config_edit` | Allows agents to modify AIDOCS config via tool calls | High |\n| `security.enforce` | Master toggle for tool gates and policy enforcement | Critical |\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n### Security Toggle Behavior\n\nWhen `security.enforce` is disabled, the following protections are removed:\n- Bash allowlist enforcement\n- Raw tool blocking\n- Destructive command protection\n\nAgents gain the ability to use any tool freely when enforcement is disabled. This setting should only be modified with explicit user confirmation through the security change confirmation modal.\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n## Heuristic Judge\n\nThe Heuristic Judge performs real-time risk assessment on agent requests by analyzing patterns and content characteristics. It assigns risk scores that determine the level of scrutiny a request receives.\n\n### Risk Categories\n\nThe system categorizes risks into several domains:\n\n| Category | Description | Examples |\n|----------|-------------|----------|\n| `supply_chain` | Package installation and remote code execution | `npm install`, `npx`, `uvx` |\n| `capability` | Declared capabilities indicating system access | File operations, command execution |\n| `vulnerability` | Code patterns that may indicate security issues | `eval()`, `__import__`, `os.system` |\n\n资料来源：[mcp/server/aidocs_mcp/skill_scanner.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/skill_scanner.py)\n\n### Risk Severity Levels\n\n| Severity | Interpretation | Action |\n|----------|----------------|--------|\n| `critical` | Highly dangerous operation | Immediate blocking or strict gate |\n| `high` | Significant risk requiring scrutiny | Gate permission or enhanced monitoring |\n| `medium` | Moderate risk | Standard RBAC check |\n| `low` | Minor concern | Allow with logging |\n\n## Output Guard\n\nThe Output Guard monitors and sanitizes content flowing from agent responses. It detects potential security issues including prompt injection attempts and sensitive data leakage.\n\n### Prompt Injection Detection\n\nThe system recognizes multiple categories of prompt injection patterns:\n\n```python\n_PROMPT_INJECTION_PATTERNS = [\n (\"system_override\", \"ignore/forget previous instructions\"),\n (\"role_hijack\", \"you are now a different AI\"),\n (\"instruction_inject\", \"XML tag instruction injection\"),\n (\"delimiter_escape\", \"code block instruction injection\"),\n (\"hidden_instruction\", \"URGENT: ignore/override\"),\n]\n```\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n\n### Sensitive Content Detection\n\n| Pattern | Description |\n|---------|-------------|\n| `env_file_content` | Environment variables with values 8+ characters |\n| `ssh_config` | SSH configuration content |\n\nThe Output Guard applies redaction markers in the format `[REDACTED:{category}]` when sensitive content is detected and redaction is enabled.\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n\n## Role-Based Access Control (RBAC)\n\nThe RBAC system provides granular permission management for agent capabilities. It defines roles, permissions, and escalation paths that govern what actions agents can perform.\n\n### Permission States\n\nPermissions can exist in three states:\n\n| State | Description |\n|-------|-------------|\n| `system` | Built-in permissions that cannot be modified |\n| `custom` | User-defined permissions for specific use cases |\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n### RBAC Table Structure\n\nThe RBAC page displays permissions in a structured table format:\n\n| Column | Description |\n|--------|-------------|\n| permission name | Unique identifier for the permission |\n| description | Human-readable explanation of the permission |\n| state | Whether the permission is system or custom |\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n### Escalation Management\n\nThe RBAC system supports permission escalation with the following attributes:\n\n| Attribute | Description |\n|-----------|-------------|\n| requester | Entity requesting escalation |\n| permission | Target permission being escalated |\n| phrase | Trigger phrase for automatic escalation |\n| session/task | Associated session or task context |\n| sticky | Whether escalation persists beyond current session |\n| created/expires | Temporal bounds for the escalation |\n\n## Tool Policy\n\nTool Policy manages bash command execution through an allowlist/denylist mechanism. It provides fine-grained control over shell commands that agents can execute.\n\n### Policy Structure\n\n```mermaid\ngraph LR\n A[Command] --> B{Policy Check}\n B -->|allow| C[Execute]\n B -->|deny| D[Block]\n B -->|bubble| E[Request Approval]\n B -->|modified| F[Execute with Modification]\n```\n\n### Bash Policy Panel\n\nThe Dashboard provides a visual interface for managing shell policies:\n\n| Count Type | Description |\n|------------|-------------|\n| `allowEff` | Effective allow count |\n| `denyEff` | Effective deny count |\n| `bubbleEff` | Effective bubble (approval required) count |\n| `modifiedAtActive` | Number of rules modified at active layer |\n\n资料来源：[apps/aidocs-dashboard/src/BashPolicyPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/BashPolicyPanel.tsx)\n\n### Policy Layer System\n\nBash policies support layered configuration with the following characteristics:\n- Policies can be defined at different layers\n- Active layer determines which policy configuration is currently in effect\n- Changes made at the active layer are tracked separately\n- Fallback default behavior is configurable\n\n## Enforcement Controller\n\nThe Enforcement Controller orchestrates all security mechanisms and ensures consistent policy application across the system.\n\n### Enforcement Actions\n\n| Action | Trigger | Result |\n|--------|---------|--------|\n| Allow | All checks pass | Execute requested operation |\n| Block | Any check fails | Deny operation, log reason |\n| Bubble | Medium risk detected | Request user approval |\n| Redact | Sensitive content in output | Replace with redaction marker |\n\n### Live Monitoring\n\nThe Live Page in the Dashboard provides real-time visibility into enforcement events:\n\n```mermaid\ngraph TD\n A[Agent Request] --> B[Gate Permission Check]\n B --> C{Permission Status}\n C -->|Required| D[Display in UI]\n C -->|Approved| E[Continue Execution]\n C -->|Rejected| F[Block and Log]\n D --> G{User Action}\n G -->|Approve| E\n G -->|Reject| F\n```\n\nThe gate permission requests appear in the Live Page with:\n- Permission name being requested\n- Requester label\n- Approve/Reject buttons for user response\n\n资料来源：[apps/aidocs-dashboard/src/LivePage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/LivePage.tsx)\n\n## Quick Actions\n\nThe Dashboard provides administrative quick actions for security management:\n\n| Action | Description |\n|--------|-------------|\n| Stop All Lanes | Terminates all active agent sessions |\n| Deactivate AIDOCS | Toggles security posture (not a runtime stop) |\n\n资料来源：[apps/aidocs-dashboard/src/LivePage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/LivePage.tsx)\n\n## Statistics Dashboard\n\nThe Live Page includes a stat tile strip showing real-time security metrics:\n\n| Metric | Description |\n|--------|-------------|\n| Events (last 1h) | Total security events in the past hour |\n| Tool Calls | Number of tool invocation attempts |\n| Blocked | Count of blocked operations |\n| Failed | Count of failed operations |\n| Tokens (in/out) | Token consumption for audit purposes |\n\nBlocked and Failed counts display with danger tone styling when greater than zero, providing immediate visual feedback for security administrators.\n\n## Configuration Management\n\n### Setting Origin Tracking\n\nIndividual settings can be traced to their origin layer through the Setting Detail Panel:\n\n```mermaid\ngraph TD\n A[Setting Path] --> B{Origin Count}\n B -->|Single| C[Display Source Layer]\n B -->|Multiple| D[Per-Leaf Origin Table]\n D --> E[List of Leaf Paths]\n D --> F[Layer per Leaf]\n```\n\nSettings with multiple origins display a collapsible table showing which layer each configuration leaf originated from.\n\n资料来源：[apps/aidocs-dashboard/src/SettingDetailPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SettingDetailPanel.tsx)\n\n### Layer Tone Indicators\n\n| Layer Type | Visual Tone |\n|------------|-------------|\n| Default | Standard styling |\n| Active | Highlighted indicator |\n| Modified | Distinct color for changed values |\n\n## Connection Status\n\nThe Castle Shell status bar displays MCP connection state:\n\n| State | Indicator | Meaning |\n|-------|-----------|---------|\n| Connected | Green dot + \"MCP connected\" | Security enforcement active |\n| Disconnected | Red dot + \"MCP disconnected\" | Fallback mode or misconfiguration |\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n\n## Security Workflow Summary\n\n```mermaid\ngraph LR\n A[Request] --> B{Dev Mode?}\n B -->|Yes| C[Additional Access]\n B -->|No| D{Normal Checks}\n D --> E{Security Enforce?}\n E -->|No| F[Minimal Security]\n E -->|Yes| G[Full Enforcement]\n G --> H[Heuristic Analysis]\n H --> I{Risk Level}\n I -->|Low| J[RBAC]\n I -->|Medium| K[Gate Permission]\n I -->|High| L[Block]\n J --> M{Has Permission?}\n M -->|Yes| N[Tool Policy]\n M -->|No| L\n N --> O{Allowed?}\n O -->|Yes| P[Execute + Output Guard]\n O -->|No| L\n K --> Q{Approved?}\n Q -->|Yes| P\n Q -->|No| L\n```\n\n## Summary\n\nAIDOCS Security & Access Control provides comprehensive protection for AI-assisted development through:\n\n1. **Centralized Access Gate** - Single entry point for all authorization decisions\n2. **Heuristic Analysis** - Automated risk scoring based on request patterns\n3. **RBAC Engine** - Fine-grained permission management with escalation support\n4. **Tool Policy** - Command allowlisting with layered configuration\n5. **Output Guard** - Prompt injection detection and sensitive data redaction\n6. **Real-time Monitoring** - Dashboard visibility into security events and statistics\n\nThe system is designed with defense-in-depth principles, ensuring that multiple independent checks must pass before potentially risky operations are executed.\n\n---\n\n\n\n## Indexing & Retrieval System\n\n### 相关页面\n\n相关主题：[Memory System](#memory-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/code_index_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/code_index_store.py)\n- [mcp/server/aidocs_mcp/code_index_symbol_search_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/code_index_symbol_search_service.py)\n- [mcp/server/aidocs_mcp/semantic_search.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/semantic_search.py)\n- [mcp/server/aidocs_mcp/index_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/index_store.py)\n- [mcp/server/aidocs_mcp/outline_extractors/__init__.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/outline_extractors/__init__.py)\n
\n\n# Indexing & Retrieval System\n\n## Overview\n\nThe Indexing & Retrieval System is the core backbone of AIDOCS, enabling AI coding agents to efficiently locate, analyze, and retrieve code symbols, semantic concepts, and structural information across a codebase. It transforms a raw repository into a queryable, memory-augmented context that allows agents to resume work without re-discovering the codebase on every session.\n\nThe system operates as a layered pipeline that:\n\n1. **Discovers** code files based on language descriptors\n2. **Parses** files to extract symbols, outlines, and semantic metadata\n3. **Indexes** extracted data into structured storage\n4. **Serves** retrieval queries through MCP tools (`ai_find`, `ai_bundle`, `ai_investigate`, `ai_trace`)\n\nThis architecture is designed for persistent memory across sessions, fast targeted lookups, and multi-language support with configurable heuristics.\n\n资料来源：[mcp/server/README.md]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Codebase Files] --> B[Language Descriptors]\n B --> C[File Discovery]\n C --> D[Outline Extractors]\n D --> E[Symbol Parsers]\n E --> F[Index Storage Layer]\n F --> G[index_store.py]\n F --> H[code_index_store.py]\n G --> I[Retrieval Query Pipeline]\n H --> I\n I --> J[semantic_search.py]\n J --> K[code_index_symbol_search_service.py]\n K --> L[MCP Tools: ai_find, ai_bundle, ai_investigate]\n```\n\n## Language Descriptor System\n\n### Purpose\n\nLanguage descriptors inform the indexer which files belong to a project, what support tier applies, and what heuristic semantics influence indexing behavior. They act as the discovery and classification layer for the entire indexing pipeline.\n\n资料来源：[mcp/INDEX_LANGUAGE_DESCRIPTORS.md]()\n\n### Descriptor Locations\n\n| Location | Path | Purpose |\n|----------|------|---------|\n| Built-in | `mcp/server/aidocs_mcp/index_languages/` | Ships with AIDOCS |\n| Project-local | `/index_languages/*.toml` | Extends or overrides built-in |\n\nProject-local descriptors can extend or override built-in behavior, allowing teams to define custom language support or refine heuristics for their specific codebase.\n\n资料来源：[mcp/INDEX_LANGUAGE_DESCRIPTORS.md]()\n\n### Supported Keys\n\n**Discovery Keys** (at least one required):\n\n- `extensions` — file extensions (e.g., `.py`, `.ts`)\n- `suffixes` — alternative naming patterns\n- `include_globs` — glob patterns for discovery\n\n**Core Keys**:\n\n| Key | Type | Description |\n|-----|------|-------------|\n| `name` | string | Language identifier |\n| `tier` | string | Support tier: `full`, `heuristic`, `minimal` |\n| `extensions` | list | File extensions |\n| `suffixes` | list | Alternative file suffixes |\n| `include_globs` | list | Glob patterns |\n\n**Semantics Keys** (influence indexing behavior):\n\n| Key | Description |\n|-----|-------------|\n| `semantic_tags` | Tags for semantic classification |\n| `outline_family` | Family name for outline patterns |\n| `outline_patterns` | Patterns for structural extraction |\n| `role_hint` | Default role hint (e.g., `analysis-script`) |\n| `role_patterns` | Patterns to detect role classifications |\n| `module_hints` | Directory names that hint at modules |\n\n资料来源：[mcp/INDEX_LANGUAGE_DESCRIPTORS.md]()\n资料来源：[mcp/server/aidocs_mcp/language_descriptors.py]()\n\n### Loading Descriptors\n\nDescriptors are loaded through `load_language_descriptors()` which implements a caching strategy:\n\n```mermaid\ngraph TD\n A[load_language_descriptors] --> B{Cache Hit?}\n B -->|Yes, schema version match| C[Return cached]\n B -->|No| D[Compute fingerprint]\n D --> E{Fingerprint match?}\n E -->|Yes| F[Return cached]\n E -->|No| G[Scan descriptor directories]\n G --> H[Load TOML files]\n H --> I[Filter by enabled languages]\n I --> J[Return descriptors]\n```\n\nThe function checks the schema version first, then compares file fingerprints to avoid unnecessary I/O. Only descriptors matching the enabled language set are loaded.\n\n资料来源：[mcp/server/aidocs_mcp/language_descriptors.py]()\n\n## Outline Extraction\n\n### Role of Outline Extractors\n\nOutline extractors parse source files to identify structural elements—classes, functions, methods, interfaces, and other symbols—and produce a lightweight outline representation. This is the primary mechanism for symbol discovery during indexing.\n\n资料来源：[mcp/server/aidocs_mcp/outline_extractors/__init__.py]()\n\n### Architecture\n\nThe outline extractor system uses a modular design with language-specific implementations. Each extractor conforms to a common interface that:\n\n1. Accepts a file path and content\n2. Returns structured symbol data with line numbers, kinds, and containers\n3. Handles language-specific parsing nuances\n\nThe `__init__.py` module exports the extractor registry and common data structures used across all language extractors.\n\n资料来源：[mcp/server/aidocs_mcp/outline_extractors/__init__.py]()\n\n## Index Storage Layer\n\n### Two-Store Architecture\n\nThe indexing system maintains two complementary storage mechanisms:\n\n```mermaid\ngraph LR\n A[index_store.py] --> B[General Index]\n A --> C[File-level metadata]\n A --> D[Language classification]\n E[code_index_store.py] --> F[Symbol Index]\n E --> G[Symbol definitions]\n E --> H[Reference mappings]\n E --> I[Container relationships]\n```\n\n**index_store.py** handles:\n\n- File-level metadata and indexing state\n- Language classification per file\n- Index-wide configuration and statistics\n\n**code_index_store.py** handles:\n\n- Symbol definitions extracted from source\n- Reference relationships between symbols\n- Container hierarchies (e.g., class → method relationships)\n\n资料来源：[mcp/server/aidocs_mcp/index_store.py]()\n资料来源：[mcp/server/aidocs_mcp/code_index_store.py]()\n\n### Symbol Index Structure\n\nThe symbol index maintains structured records for each extracted symbol:\n\n| Field | Description |\n|-------|-------------|\n| `symbol` | Symbol name |\n| `kind` | Type (function, class, method, interface, etc.) |\n| `path` | File path |\n| `line_number` | Definition line |\n| `container` | Parent symbol (class containing method, etc.) |\n| `language` | Source language |\n| `is_partial` | Partial definition flag (for C#, etc.) |\n\nThis structure enables efficient filtering by kind, container, and location during retrieval queries.\n\n资料来源：[mcp/server/METHODS.md]()\n\n## Retrieval Services\n\n### Semantic Search\n\n`semantic_search.py` implements concept-level search capabilities that go beyond exact symbol matching. It enables:\n\n- **Concept queries** — searching by semantic meaning rather than exact names\n- **Fuzzy matching** — handling typos and partial matches\n- **Ranking** — scoring results by relevance\n\nThe semantic search layer bridges the gap between natural language queries and structured symbol data, enabling agents to find code using descriptive terms.\n\n资料来源：[mcp/server/aidocs_mcp/semantic_search.py]()\n\n### Symbol Search Service\n\n`code_index_symbol_search_service.py` provides the core symbol-level search functionality:\n\n- **Symbol lookup** — find symbols by exact or partial name match\n- **Reference tracing** — locate all usages of a symbol\n- **Kind filtering** — search within specific symbol types\n- **Scope resolution** — navigate symbol containers\n\nThis service is the primary engine behind the `ai_find` MCP tool, which supports multiple search modes:\n\n| Mode | Purpose |\n|------|---------|\n| `symbols` | Find symbol definitions |\n| `references` | Find symbol usages |\n| `mutations` | Find code modifying a concept |\n| `validation` | Find validation logic |\n| `policy` | Find policy enforcement points |\n\n资料来源：[mcp/server/aidocs_mcp/code_index_symbol_search_service.py]()\n资料来源：[mcp/server/aidocs_mcp/claude_hook.py]()\n\n## MCP Tool Interface\n\n### Core Retrieval Tools\n\nThe indexing system exposes retrieval capabilities through these MCP tools:\n\n**ai_find** — Unified symbol and reference search across indexed code.\n\n**ai_investigate** — Broad concept investigation with ranked results across layers.\n\n**ai_bundle** — Retrieve comprehensive context for a file, path, or concept.\n\n**ai_trace** — Cross-layer relationship tracing for fields, settings, or services.\n\n**ai_get_symbol_snippet** — Retrieve exact symbol body with container context.\n\n**ai_get_symbol_info** — Retrieve symbol metadata (signature, constructor, enum, API).\n\n资料来源：[mcp/README.md]()\n\n### Read Pipeline\n\nLine-based reading flows through a shared read pipeline with strict mode enforcement:\n\n```mermaid\ngraph TD\n A[ai_get_lines] --> B[gate: strict mode]\n B --> C{Path valid?}\n C -->|No| D[Refusal]\n C -->|Yes| E[Check managed mode]\n E --> F[indexed_read_block]\n F --> G[Return lines]\n```\n\nStrict mode enforces:\n- No absolute path inputs\n- No `..` traversal\n- Zone restrictions (PROJECT_INTERNAL, MEMORY_INTERNAL only)\n\n资料来源：[mcp/server/aidocs_mcp/server_code_edit_tools.py]()\n\n## Configuration Options\n\n### Index Settings\n\nConfiguration options in `config_schema.py` control indexing behavior:\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `index.max_file_size` | integer | 100_000 | Max file size in bytes |\n| `index.max_json_size` | integer | 100_000 | Max JSON file size |\n| `index.enabled_languages` | string | \"all\" | Language set for filtering |\n| `index.include_tests` | boolean | false | Include test directories |\n| `index.extra_module_hints` | string_list | [] | Extra module directory names |\n| `languages.enabled` | string | \"all\" | Loaded language descriptors |\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `tools.sync_functions_timeout` | integer | 60 | Timeout for sync/indexer operations |\n| `tools.tool_call_timeout` | integer | 10 | Default tool call timeout |\n\n资料来源：[mcp/server/aidocs_mcp/config_schema.py]()\n\n## Layer Inference\n\nThe retrieval system infers architectural layers for search results, enabling context-aware queries:\n\n| Layer | Description |\n|-------|-------------|\n| `data` | Data access, models, DTOs |\n| `logic` | Business logic, services |\n| `api` | API endpoints, controllers |\n| `ui` | User interface components |\n| `code` | General code files |\n\nLayer inference helps agents understand where discovered code fits in the system architecture and find code at appropriate abstraction levels.\n\n资料来源：[mcp/server/METHODS.md]()\n\n## Session Persistence\n\nThe indexing system supports persistent sessions that maintain index state across agent invocations:\n\n- **Session-based indexing** — indexes can be tied to session IDs\n- **Project sync** — `project_sync_indexes` keeps indexes current with codebase\n- **Managed mode** — enforces controlled editing with session tracking\n\nThis persistence enables the \"resume work instead of rediscovering\" core value proposition of AIDOCS.\n\n资料来源：[mcp/README.md]()\n资料来源：[mcp/server/aidocs_mcp/claude_hook.py]()\n\n## Workflow Summary\n\n```mermaid\ngraph LR\n A[Initialize Project] --> B[Load Language Descriptors]\n B --> C[Discover Files]\n C --> D[Extract Outlines]\n D --> E[Parse Symbols]\n E --> F[Store in Index]\n F --> G[Ready for Retrieval]\n G --> H[ai_find / ai_investigate]\n G --> I[ai_bundle / ai_trace]\n H --> J[Symbol Search Service]\n I --> K[Semantic Search]\n J --> L[Agent Context]\n K --> L\n```\n\n## Related Documentation\n\n- [METHODS.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/METHODS.md) — Complete MCP tool reference\n- [INDEX_LANGUAGE_DESCRIPTORS.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/INDEX_LANGUAGE_DESCRIPTORS.md) — Language descriptor specification\n- [config_schema.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_schema.py) — Configuration reference\n\n---\n\n\n\n## Configuration Management\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Security & Access Control](#security-gates)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)\n- [apps/aidocs-dashboard/src/BashPolicyPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/BashPolicyPanel.tsx)\n- [apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n
\n\n# Configuration Management\n\n## Overview\n\nAIDOCS provides a layered, hierarchical configuration system that enables persistent memory, indexed retrieval, and orchestration for AI coding agents. The configuration architecture supports multiple levels of override, from system defaults down to per-project and per-session settings.\n\n资料来源：[README.md]()\n\n## Configuration Architecture\n\nAIDOCS uses a **layered configuration model** where settings cascade from base defaults through environment-specific overrides to project-specific customizations.\n\n```mermaid\ngraph TD\n A[System Defaults] --> B[Environment Variables]\n B --> C[aidocs.toml Base]\n C --> D[Project .aidocs/]\n D --> E[Session Overrides]\n E --> F[Runtime Resolution]\n \n A -->|Low Priority| F\n E -->|High Priority| F\n```\n\n### Configuration Files\n\n| File | Location | Purpose | Format |\n|------|----------|---------|--------|\n| `aidocs.toml` | Project root | Runtime configuration with static definitions | TOML |\n| `hooks.json` | `core/hooks/` | Hook definitions for event-driven behavior | JSON |\n| Action Tokens | `action_tokens/` | Prompt-classification language files | YAML |\n| Language Descriptors | `index_languages/` | Per-language configuration | TOML |\n| Gate Messages | `gate_messages/` | Action hooks and permission definitions | TOML |\n\n资料来源：[README.md]()\n\n## Core Configuration: aidocs.toml\n\nThe primary runtime configuration file defines system-wide and per-project settings.\n\n### Configuration Sections\n\n```toml\n# aidocs.toml structure (conceptual)\n[dev]\ndev_mode = false # Enable editing MCP server source files\n\n[security]\nallow_config_edit = false # Allow agents to modify config via tool calls\nenforce = true # Enable tool gates and bash allowlist\n\n[memory]\n# Memory and indexing settings\nretention_days = 30\nindex_on_startup = true\n\n[mcp]\n# MCP server connection settings\ntransport = \"stdio\"\ncommand = \"aidocs-mcp\"\n```\n\n### Security Configuration\n\nThe security section controls agent capabilities and tool access:\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `security.allow_config_edit` | boolean | `false` | Allows agents to modify AIDOCS config via tool calls |\n| `security.enforce` | boolean | `true` | Enables tool gates, bash allowlist, and destructive command protection |\n| `dev.dev_mode` | boolean | `false` | Enables editing of MCP server source files |\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](), [apps/aidocs-dashboard/src/TomlConfigsPage.tsx]()\n\n**Warning Messages for Security Changes:**\n\n```typescript\n// From dashboardModals.tsx\n{settingPath === \"dev.dev_mode\" && \"Enables editing AIDOCS MCP server source files. Only use when actively developing AIDOCS.\"}\n{settingPath === \"security.allow_config_edit\" && \"Allows agents to modify AIDOCS config via tool calls. The agent can change gate settings, conductor config, and other project settings.\"}\n{settingPath === \"security.enforce\" && \"Disabling tool gates removes bash allowlist, raw tool blocking, and destructive command protection. Agents can use any tool freely.\"}\n```\n\n## Shell Policy Configuration\n\nThe bash policy system provides fine-grained control over shell command execution with a three-tier decision model.\n\n### Policy Actions\n\n| Action | Description |\n|--------|-------------|\n| `allow` | Command is permitted to execute |\n| `deny` | Command is blocked regardless of context |\n| `bubble` | Command requires explicit user approval |\n\n### Policy Display\n\nThe dashboard visualizes policy counts per layer:\n\n```typescript\n{counts.allowEff} allow\n{counts.denyEff} deny\n{counts.bubbleEff} bubble\n{counts.modifiedAtActive} set at {activeLayer}\n```\n\n资料来源：[apps/aidocs-dashboard/src/BashPolicyPanel.tsx]()\n\n### Filter Controls\n\nPolicy entries can be filtered using the search and category chips:\n\n```typescript\nconst filters = [\"all\", \"allow\", \"deny\", \"bubble\", \"modified\"] as const;\n```\n\n| Filter | Function |\n|--------|----------|\n| `all` | Show all policy entries |\n| `allow` | Show only allowed commands |\n| `deny` | Show only denied commands |\n| `bubble` | Show only commands requiring approval |\n| `modified` | Show only modified entries |\n\n## Action Tokens (Prompt Classification)\n\nAction Tokens are YAML-based language files that define how user prompts are classified and routed.\n\n### Structure\n\n```yaml\n# action_tokens/en.yaml (conceptual structure)\nintent_tokens:\n - name: \"implement\"\n pattern: \"implement|create|build|add\"\n action: \"code_generation\"\n \n - name: \"investigate\"\n pattern: \"investigate|analyze|trace\"\n action: \"code_analysis\"\n```\n\n### Configuration Categories\n\nThe TOML configuration page in the dashboard provides tabs for different configuration domains:\n\n| Tab | Purpose |\n|-----|---------|\n| Action Tokens | Prompt-classification language files (en, it, ...) |\n| Action Hooks | Gate messages and hook definitions |\n| Language Descriptors | Per-language configuration specifications |\n\n资料来源：[apps/aidocs-dashboard/src/TomlConfigsPage.tsx](), [mcp/README.md]()\n\n## Setup Wizard Configuration Flow\n\nThe setup wizard guides users through initial project configuration:\n\n```mermaid\ngraph TD\n A[Welcome] --> B[Project Selection]\n B --> C[Environment Detection]\n C --> D[Configuration]\n D --> E[Done]\n \n B -->|Select folder| B\n C -->|Missing deps| F[Install Dependencies]\n F --> C\n```\n\n### Setup Steps\n\n| Step | Description |\n|------|-------------|\n| `welcome` | Introduction and feature overview |\n| `project` | Project folder selection |\n| `detect` | Environment and tool detection |\n| `configure` | MCP, hooks, and project structure setup |\n| `done` | Configuration summary and next steps |\n\n### Configuration Results\n\nAfter setup, the wizard displays:\n\n```typescript\n
\n
\n MCP configured\n {configResult.mcp_path}\n
\n
\n Hooks registered\n {configResult.hooks_path}\n
\n
\n Project initialized\n
\n
\n```\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n### Environment Detection\n\nThe wizard detects installed tools and authentication status:\n\n| Component | Detection |\n|-----------|-----------|\n| Node.js | Check for CLI agent support |\n| Claude | Check for `claude.ai` authentication |\n| OpenAI | Check for API key configuration |\n\n```typescript\n{/* Sign-in button for detected but unauthenticated hosts */}\n{h.authenticated === false && (\n \n)}\n```\n\n## Configuration Resolution\n\nSettings follow a precedence hierarchy where higher layers override lower ones:\n\n```mermaid\ngraph LR\n A[Base Defaults] --> B[Project Config]\n B --> C[Session State]\n C --> D[Runtime Values]\n \n style A fill:#e1e1e1\n style D fill:#90EE90\n```\n\n### Layer Model\n\n| Layer | Scope | Override Priority |\n|-------|-------|-------------------|\n| System Defaults | Global | 1 (lowest) |\n| Environment Variables | Process-level | 2 |\n| `aidocs.toml` | Project root | 3 |\n| `.aidocs/` directory | Project-specific | 4 |\n| Session State | Per-session runtime | 5 (highest) |\n\n## TOML Document Management\n\nThe dashboard provides a unified interface for managing TOML configuration documents:\n\n```typescript\n// Document filtering by category\nconst categoryPrefix = \"mcp/server/aidocs_mcp/index_languages/\";\nconst filteredDocuments = tomlDocuments.filter((d) => d.path.startsWith(categoryPrefix));\n```\n\n### Document Table Columns\n\n| Column | Description |\n|--------|-------------|\n| Target | Configuration target identifier |\n| Active | Whether the config is currently active |\n| Context | Brief description of the configuration scope |\n\n## Command-Line Configuration\n\nAIDOCS provides CLI commands for configuration management:\n\n```bash\naidocs setup # Configures MCP, hooks, and project init\naidocs doctor # Verifies installation and configuration\n```\n\n| Command | Function |\n|---------|----------|\n| `aidocs setup` | Run the setup wizard to configure everything |\n| `aidocs doctor` | Validate the installation and configuration |\n\n资料来源：[README.md]()\n\n## Summary\n\nThe AIDOCS configuration management system provides:\n\n1. **Hierarchical Override**: Settings cascade from system defaults through project-specific configurations\n2. **Security Controls**: Fine-grained control over agent capabilities and tool access\n3. **Shell Policy**: Three-tier command execution model (allow/deny/bubble)\n4. **Language Support**: Extensible action token system for prompt classification\n5. **Dashboard Integration**: Visual configuration management through the Tauri-based dashboard\n6. **CLI Tools**: Command-line utilities for setup and validation\n\nAll configuration is designed to support the core goal of giving AI coding agents **persistent memory, indexed retrieval, and orchestration** while maintaining security and operational safety.\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: cristian1991/AIDOCS\n\nSummary: Found 9 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | host_targets=mcp_host, claude, claude_code, cursor\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | README/documentation is current enough for a first validation pass.\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n\n## 6. security_permissions · 来源证据：v2.0.0 — Unified AccessGate & Agent Enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.0 — Unified AccessGate & Agent Enforcement\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2ef38d1286d44ae9b266a98267a2d782 | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. security_permissions · 来源证据：v2.0.3 — Token Tracking & Dashboard Fixes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.3 — Token Tracking & Dashboard Fixes\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5428bd20316b4bfa987b009350fc138b | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | issue_or_pr_quality=unknown\n\n## 9. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | release_recency=unknown\n\n\n", "markdown_key": "aidocs", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:1153124183", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/cristian1991/AIDOCS" }, { "evidence_id": "art_46829c914f86419cab768d5acb9e69a1", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/cristian1991/AIDOCS#readme" } ], "summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.", "title": "AIDOCS 说明书", "toc": [ "https://github.com/cristian1991/AIDOCS 项目说明书", "目录", "Introduction to AIDOCS", "Overview", "Purpose and Scope", "Architecture Overview", "Core Components", "Setup and Installation", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "388d7bd19358d1c5bd17d669b9cc06e6df78078b", "repo_inspection_error": null, "repo_inspection_files": [ "README.md" ], "repo_inspection_verified": true, "review_reasons": [ "community_discussion_evidence_below_public_threshold" ], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# aidocs-dashboard - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 aidocs-dashboard 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`core/.cursor-plugin/plugin.json`, `aidocs-plugin.json` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `curl -fsSL https://raw.githubusercontent.com/cristian1991/AIDOCS/main/core/scripts/install.sh | bash` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install aidocs-mcp # install the package` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`core/.cursor-plugin/plugin.json`, `aidocs-plugin.json` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`, `CLAUDE.md`, `aidocs-plugin.json`, `core/.cursor-plugin/plugin.json`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`core/.cursor-plugin/plugin.json`, `aidocs-plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `CLAUDE.md`, `aidocs-plugin.json`, `core/.cursor-plugin/plugin.json`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `aidocs-plugin.json`, `core/.cursor-plugin/plugin.json`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`core/.cursor-plugin/plugin.json`, `aidocs-plugin.json` Claim：`clm_0007` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`core/.cursor-plugin/plugin.json`, `aidocs-plugin.json` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：452\n- 重要文件覆盖：40/452\n- 证据索引条目：60\n- 角色 / Skill 条目：34\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 aidocs-dashboard 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 aidocs-dashboard 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 aidocs-dashboard 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 34 个角色 / Skill / 项目文档条目。\n\n- **AGENTS**（project_doc）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **CLAUDE**（project_doc）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **What It Does**（project_doc）：The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Agents**（project_doc）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/AGENTS.md`\n- **Claude**（project_doc）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/CLAUDE.md`\n- **AGENTS**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/AGENTS.md`\n- **CLAUDE**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/CLAUDE.md`\n- **AIDOCS MCP**（project_doc）：v2.3.0b2 — The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/README.md`\n- **Built-in Skills**（project_doc）：Built-in AIDOCS skills live in this directory. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.skills/README.md`\n- **AIDOCS MCP Server**（project_doc）：This folder is the implementation scaffold for the optional AIDOCS MCP layer. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/server/README.md`\n- **Index Language Descriptors**（project_doc）：This directory contains the built-in TOML language descriptors used by AIDOCS indexing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/server/aidocs_mcp/index_languages/README.md`\n- **Contributing to AIDOCS**（project_doc）：AIDOCS is built to be extended. Here's where community contributions make the biggest impact. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **AIDOCS Public Roadmap**（project_doc）：v2.3.0b1 — Enforcement Parity & Plugin Rewrite 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`PUBLIC_ROADMAP.md`\n- **AIDOCS Install Guide**（project_doc）：After aidocs setup completes, open the project in your IDE and type /aidocs to bootstrap a session. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README_INSTALL.md`\n- **AIDOCS User README**（project_doc）：README.md is the canonical user-facing README. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README_USER.md`\n- **Benchmarks**（project_doc）：This document defines the public benchmark contract for AIDOCS v1.2.0 work. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/BENCHMARKS.md`\n- **Docs Site Structure Proposal**（project_doc）：This document proposes the AIDOCS docs information architecture for the future hosted docs surface at: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/DOCS_SITE_STRUCTURE.md`\n- **Host Integration Contract**（project_doc）：This document defines how a host/client such as OpenCode should integrate with the AIDOCS MCP layer. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/HOST_INTEGRATION.md`\n- **Index Language Descriptors**（project_doc）：This document describes the current TOML-based language descriptor system used by AIDOCS indexing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/INDEX_LANGUAGE_DESCRIPTORS.md`\n- **Intent**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.commands/COMMAND_SPEC_TEMPLATE.md`\n- **Intent**（project_doc）：Enter or bootstrap AIDOCS for this project 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.commands/aidocs.md`\n- **Intent**（project_doc）：Update changelog and archive completed work 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.commands/archive.md`\n- **Intent**（project_doc）：Cleanup project by user-selected scope 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.commands/clean.md`\n- **Intent**（project_doc）：Pick an agent personality for user-facing messages 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.commands/personality.md`\n- **Intent**（project_doc）：Reingest project knowledge by user-selected scope 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.commands/reingest.md`\n- **brainstorming**（project_doc）：Clarify ambiguous or architectural work before implementation by comparing options and tradeoffs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.skills/brainstorming.md`\n- **caveman**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.skills/caveman.md`\n- **deep-retrieval**（project_doc）：Prefer deeper retrieval and precision tools before editing or concluding behavior. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.skills/deep-retrieval.md`\n- **empire-doctrine**（project_doc）：General-portable kingdom principles — KISS=Simply Smart, bounded co-deliberation, kind law, plans-vs-experts. Activates when the operator references \"castle doctrine\", \"kingdom law\", or the kingdom's general principles. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.skills/empire-doctrine.md`\n- **systematic-debugging**（project_doc）：Investigate root cause before fixing bugs, regressions, failing tests, or unexpected behavior. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.skills/systematic-debugging.md`\n- **MCP Server Architecture**（project_doc）：- Canonical source of truth: - core/ for AIDOCS contracts/templates - project-local /.MEMORY/ for runtime and durable memory - MCP server: - validates and enforces lifecycle rules - performs structured file-backed reads/writes - Future index: - SQLite only - derived only - rebuildable from files and code 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/server/ARCHITECTURE.md`\n- **Initial MCP Methods**（project_doc）：Purpose - Run the AIDOCS bootstrap, session, and first-retrieval flow as one high-level entrypoint. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/server/METHODS.md`\n- **File-Backed Service Interfaces**（project_doc）：Responsibilities - enumerate session folders - parse SESSION.md - create session folder from templates - update structured sections in SESSION.md - resolve linked session-local files context.md , plans/ , agents/ , artifacts/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`mcp/server/interfaces.md`\n- **test-driven-validation**（project_doc）：Prioritize validation evidence, edge cases, and feedback from test runs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/.skills/test-driven-validation.md`\n\n## 证据索引\n\n- 共索引 60 条证据。\n\n- **AGENTS**（documentation）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 证据：`AGENTS.md`\n- **CLAUDE**（documentation）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 证据：`CLAUDE.md`\n- **What It Does**（documentation）：The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. 证据：`README.md`\n- **Agents**（documentation）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 证据：`core/AGENTS.md`\n- **Claude**（documentation）：AIDOCS project. Routing lives at /.MEMORY/.aidocs/index.aidocs . 证据：`core/CLAUDE.md`\n- **AGENTS**（documentation）：AGENTS AIDOCS-managed project. 证据：`mcp/AGENTS.md`\n- **CLAUDE**（documentation）：CLAUDE AIDOCS-managed project. 证据：`mcp/CLAUDE.md`\n- **AIDOCS MCP**（documentation）：v2.3.0b2 — The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. 证据：`mcp/README.md`\n- **Built-in Skills**（documentation）：Built-in AIDOCS skills live in this directory. 证据：`core/.skills/README.md`\n- **AIDOCS MCP Server**（documentation）：This folder is the implementation scaffold for the optional AIDOCS MCP layer. 证据：`mcp/server/README.md`\n- **Index Language Descriptors**（documentation）：This directory contains the built-in TOML language descriptors used by AIDOCS indexing. 证据：`mcp/server/aidocs_mcp/index_languages/README.md`\n- **Contributing to AIDOCS**（documentation）：AIDOCS is built to be extended. Here's where community contributions make the biggest impact. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"aidocs-dashboard\", \"private\": true, \"version\": \"2.1.0-beta.1\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite --host 127.0.0.1 --port 1420\", \"build\": \"tsc && vite build\", \"typecheck\": \"tsc --noEmit\", \"preview\": \"vite preview --host 127.0.0.1 --port 4173\", \"tauri\": \"tauri\" }, \"dependencies\": { \"@codemirror/commands\": \"^6.10.3\", \"@codemirror/lang-json\": \"^6.0.2\", \"@codemirror/language\": \"^6.12.3\", \"@codemirror/legacy-modes\": \"^6.5.2\", \"@codemirror/merge\": \"^6.12.1\", \"@codemirror/state\": \"^6.6.0\", \"@codemirror/view\": \"^6.41.0\", \"@tauri-apps/api\": \"^2.0.0\", \"codemirror\": \"^6.0.2\", \"lucide-react\": \"^0.460.0\", \"react\": \"^18.3.1\", \"react-dom\": \"^18.3.1\", \"recharts\": \"^3.8.1\" }, \"devDepende… 证据：`apps/aidocs-dashboard/package.json`\n- **Plugin**（structured_config）：{ \"name\": \"aidocs\", \"displayName\": \"AIDOCS\", \"description\": \"Structured session routing, persistent memory, and MCP-first agent workflows\", \"version\": \"1.3.0\", \"author\": { \"name\": \"CodeNexus\", \"email\": \"hello@codenexus.cloud\" }, \"homepage\": \"https://github.com/cristian1991/AIDOCS\", \"repository\": \"https://github.com/cristian1991/AIDOCS\", \"license\": \"Apache-2.0\", \"hooks\": \"./hooks/hooks-cursor.json\" } 证据：`core/.cursor-plugin/plugin.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **AIDOCS Public Roadmap**（documentation）：v2.3.0b1 — Enforcement Parity & Plugin Rewrite 证据：`PUBLIC_ROADMAP.md`\n- **AIDOCS Install Guide**（documentation）：After aidocs setup completes, open the project in your IDE and type /aidocs to bootstrap a session. 证据：`README_INSTALL.md`\n- **AIDOCS User README**（documentation）：README.md is the canonical user-facing README. 证据：`README_USER.md`\n- **Benchmarks**（documentation）：This document defines the public benchmark contract for AIDOCS v1.2.0 work. 证据：`mcp/BENCHMARKS.md`\n- **Docs Site Structure Proposal**（documentation）：This document proposes the AIDOCS docs information architecture for the future hosted docs surface at: 证据：`mcp/DOCS_SITE_STRUCTURE.md`\n- **Host Integration Contract**（documentation）：This document defines how a host/client such as OpenCode should integrate with the AIDOCS MCP layer. 证据：`mcp/HOST_INTEGRATION.md`\n- **Index Language Descriptors**（documentation）：This document describes the current TOML-based language descriptor system used by AIDOCS indexing. 证据：`mcp/INDEX_LANGUAGE_DESCRIPTORS.md`\n- **Intent**（documentation）：Intent - State the command goal in one sentence. 证据：`core/.commands/COMMAND_SPEC_TEMPLATE.md`\n- **Intent**（documentation）：Intent - Activate or bootstrap AIDOCS for the target project. 证据：`core/.commands/aidocs.md`\n- **Intent**（documentation）：Intent - Archive completed work into canonical memory and /.MEMORY/CHANGELOG.md . 证据：`core/.commands/archive.md`\n- **Intent**（documentation）：Intent - Run cleanup using a user-selected scope. 证据：`core/.commands/clean.md`\n- **Intent**（documentation）：Intent - Set conversational style for user-facing messages only. 证据：`core/.commands/personality.md`\n- **Intent**（documentation）：Intent - Refresh project memory using a user-selected reingest scope. 证据：`core/.commands/reingest.md`\n- **brainstorming**（documentation）：Use when the task is ambiguous, architectural, risky, or has multiple plausible designs. 证据：`core/.skills/brainstorming.md`\n- **Persistence**（documentation）：Respond terse like smart caveman. All technical substance stay. Only fluff die. 证据：`core/.skills/caveman.md`\n- **deep-retrieval**（documentation）：Use when the task needs exact signatures, constructors, enum values, service APIs, ownership boundaries, or workflow tracing before making changes. 证据：`core/.skills/deep-retrieval.md`\n- **empire-doctrine**（documentation）：The kingdom's portable law. AIDOCS-implementation specifics live in emperor-doctrine . 证据：`core/.skills/empire-doctrine.md`\n- **systematic-debugging**（documentation）：Use when debugging a bug, regression, error, failing test, or unexpected runtime behavior. 证据：`core/.skills/systematic-debugging.md`\n- **MCP Server Architecture**（documentation）：- Canonical source of truth: - core/ for AIDOCS contracts/templates - project-local /.MEMORY/ for runtime and durable memory - MCP server: - validates and enforces lifecycle rules - performs structured file-backed reads/writes - Future index: - SQLite only - derived only - rebuildable from files and code 证据：`mcp/server/ARCHITECTURE.md`\n- **Initial MCP Methods**（documentation）：Purpose - Run the AIDOCS bootstrap, session, and first-retrieval flow as one high-level entrypoint. 证据：`mcp/server/METHODS.md`\n- **File-Backed Service Interfaces**（documentation）：Responsibilities - enumerate session folders - parse SESSION.md - create session folder from templates - update structured sections in SESSION.md - resolve linked session-local files context.md , plans/ , agents/ , artifacts/ 证据：`mcp/server/interfaces.md`\n- **Aidocs Plugin**（structured_config）：{ \"inject message directives\": true, \"directive style\": \"short\", \"languages enabled\": \"all\", \"disregard compaction\": false, \"startup context once\": true } 证据：`aidocs-plugin.json`\n- **Default**（structured_config）：{ \"$schema\": \"../gen/schemas/desktop-schema.json\", \"identifier\": \"default\", \"description\": \"Default desktop capability for the AIDOCS Dashboard window.\", \"windows\": \"main\" , \"permissions\": \"core:default\" } 证据：`apps/aidocs-dashboard/src-tauri/capabilities/default.json`\n- **Acl Manifests**（structured_config）：{\"core\":{\"default permission\":{\"identifier\":\"default\",\"description\":\"Default core plugins set.\",\"permissions\": \"core:path:default\",\"core:event:default\",\"core:window:default\",\"core:webview:default\",\"core:app:default\",\"core:image:default\",\"core:resources:default\",\"core:menu:default\",\"core:tray:default\" },\"permissions\":{},\"permission sets\":{},\"global scope schema\":null},\"core:app\":{\"default permission\":{\"identifier\":\"default\",\"description\":\"Default permissions for the plugin.\",\"permissions\": \"allow-version\",\"allow-name\",\"allow-tauri-version\",\"allow-identifier\",\"allow-bundle-type\",\"allow-register-listener\",\"allow-remove-listener\" },\"permissions\":{\"allow-app-hide\":{\"identifier\":\"allow-app-hide\",… 证据：`apps/aidocs-dashboard/src-tauri/gen/schemas/acl-manifests.json`\n- **Capabilities**（structured_config）：{\"default\":{\"identifier\":\"default\",\"description\":\"Default desktop capability for the AIDOCS Dashboard window.\",\"local\":true,\"windows\": \"main\" ,\"permissions\": \"core:default\" }} 证据：`apps/aidocs-dashboard/src-tauri/gen/schemas/capabilities.json`\n- **Desktop Schema**（structured_config）：{ \"$schema\": \"http://json-schema.org/draft-07/schema \", \"title\": \"CapabilityFile\", \"description\": \"Capability formats accepted in a capability file.\", \"anyOf\": { \"description\": \"A single capability.\", \"allOf\": { \"$ref\": \" /definitions/Capability\" } }, { \"description\": \"A list of capabilities.\", \"type\": \"array\", \"items\": { \"$ref\": \" /definitions/Capability\" } }, { \"description\": \"A list of capabilities.\", \"type\": \"object\", \"required\": \"capabilities\" , \"properties\": { \"capabilities\": { \"description\": \"The list of capabilities.\", \"type\": \"array\", \"items\": { \"$ref\": \" /definitions/Capability\" } } } } , \"definitions\": { \"Capability\": { \"description\": \"A grouping and boundary mechanism developers… 证据：`apps/aidocs-dashboard/src-tauri/gen/schemas/desktop-schema.json`\n- **Windows Schema**（structured_config）：{ \"$schema\": \"http://json-schema.org/draft-07/schema \", \"title\": \"CapabilityFile\", \"description\": \"Capability formats accepted in a capability file.\", \"anyOf\": { \"description\": \"A single capability.\", \"allOf\": { \"$ref\": \" /definitions/Capability\" } }, { \"description\": \"A list of capabilities.\", \"type\": \"array\", \"items\": { \"$ref\": \" /definitions/Capability\" } }, { \"description\": \"A list of capabilities.\", \"type\": \"object\", \"required\": \"capabilities\" , \"properties\": { \"capabilities\": { \"description\": \"The list of capabilities.\", \"type\": \"array\", \"items\": { \"$ref\": \" /definitions/Capability\" } } } } , \"definitions\": { \"Capability\": { \"description\": \"A grouping and boundary mechanism developers… 证据：`apps/aidocs-dashboard/src-tauri/gen/schemas/windows-schema.json`\n- **Tauri.Conf**（structured_config）：{ \"$schema\": \"https://schema.tauri.app/config/2\", \"productName\": \"AIDOCS Dashboard\", \"version\": \"2.0.0\", \"identifier\": \"cloud.codenexus.aidocs.dashboard\", \"build\": { \"beforeDevCommand\": \"npm run dev\", \"beforeBuildCommand\": \"npm run build\", \"devUrl\": \"http://127.0.0.1:1420\", \"frontendDist\": \"../dist\" }, \"app\": { \"windows\": { \"title\": \"AIDOCS Dashboard\", \"width\": 1440, \"height\": 960, \"minWidth\": 1180, \"minHeight\": 900, \"resizable\": true, \"fullscreen\": false } , \"security\": { \"csp\": \"default-src 'self'; img-src 'self' asset: data: https://img.shields.io; style-src 'self' 'unsafe-inline'\" } }, \"bundle\": { \"active\": true, \"targets\": \"all\", \"icon\": \"icons/32x32.png\", \"icons/128x128.png\", \"icons/1… 证据：`apps/aidocs-dashboard/src-tauri/tauri.conf.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2020\", \"useDefineForClassFields\": true, \"lib\": \"ES2020\", \"DOM\", \"DOM.Iterable\" , \"allowJs\": false, \"skipLibCheck\": true, \"esModuleInterop\": true, \"allowSyntheticDefaultImports\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"module\": \"ESNext\", \"moduleResolution\": \"Node\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"noEmit\": true, \"jsx\": \"react-jsx\" }, \"include\": \"src\" , \"references\": } 证据：`apps/aidocs-dashboard/tsconfig.json`\n- **Hooks**（structured_config）：{ \"hooks\": { \"SessionStart\": { \"matcher\": \"startup resume\", \"hooks\": { \"type\": \"command\", \"command\": \"bash \\\"$ git rev-parse --show-toplevel /core/hooks/session-start\\\"\", \"timeout\": 30, \"statusMessage\": \"AIDOCS startup routing\" } } , \"UserPromptSubmit\": { \"hooks\": { \"type\": \"command\", \"command\": \"bash \\\"$ git rev-parse --show-toplevel /core/scripts/claude-hook.sh\\\"\", \"timeout\": 30, \"statusMessage\": \"AIDOCS prompt routing\" } } } } 证据：`core/.codex/hooks.json`\n- **Hooks Cursor**（structured_config）：{ \"version\": 1, \"hooks\": { \"sessionStart\": { \"command\": \"./hooks/session-start\" } } } 证据：`core/.cursor-plugin/hooks/hooks-cursor.json`\n- **Hooks Cursor**（structured_config）：{ \"version\": 1, \"hooks\": { \"sessionStart\": { \"command\": \"./hooks/session-start\" } } } 证据：`core/hooks/hooks-cursor.json`\n- **Hooks**（structured_config）：{ \"hooks\": { \"SessionStart\": { \"hooks\": { \"type\": \"command\", \"command\": \"python -m aidocs mcp.claude hook\", \"timeout\": 30, \"statusMessage\": \"AIDOCS startup routing\" } } , \"UserPromptSubmit\": { \"hooks\": { \"type\": \"command\", \"command\": \"python -m aidocs mcp.claude hook\", \"timeout\": 30, \"statusMessage\": \"AIDOCS prompt routing\" } } , \"PreToolUse\": { \"matcher\": \"Read Edit Write Glob Grep Bash MultiEdit Patch ApplyPatch Search ListDir Task NotebookEdit ScheduleWakeup PowerShell pwsh Pwsh cmd wsl Monitor\", \"hooks\": { \"type\": \"command\", \"command\": \"python -m aidocs mcp.claude hook\", \"timeout\": 30, \"statusMessage\": \"AIDOCS tool guardrails\" } } , \"PostToolUse\": { \"matcher\": \"TodoWrite\", \"hooks\": { \"t… 证据：`core/hooks/hooks.json`\n- **Claude Hooks Settings**（structured_config）：{ \"hooks\": { \"PreToolUse\": { \"matcher\": \"Read \", \"hooks\": { \"type\": \"command\", \"command\": \"node \\\" \\\" pre-tool-use\" } } , \"PostToolUse\": { \"matcher\": \"TodoWrite\", \"hooks\": { \"type\": \"command\", \"command\": \"node \\\" \\\" post-tool-use\" } } } } 证据：`core/templates/claude-hooks-settings.json`\n- **Settings.Local**（structured_config）：{ \"autoMemoryEnabled\": false } 证据：`mcp/.claude/settings.local.json`\n- **.gitattributes**（source_file）：.aidocs linguist-language=Markdown .sh text eol=lf .bash text eol=lf install.sh text eol=lf 证据：`.gitattributes`\n- **Project memory IS tracked in the private repo — it's the migration**（source_file）：Project memory IS tracked in the private repo — it's the migration payload between conductors across machines / branches. The public sync step sync-to-public.yml strips /.MEMORY/ before publishing, so the public repo never sees project memory. Ignored anyway: /.MEMORY/.index/ — derived index rebuildable, noisy diffs . /.MEMORY/ except /.MEMORY/ — stray dirs created by the MCP server when launched with CWD inside a subpackage. Only the project-root .MEMORY/ is canonical. /.MEMORY/.index/ / /.MEMORY/ !/.MEMORY/ Host-local overrides not committed . The tracked /AGENTS.md and /CLAUDE.md at project root are minimal routers pointing at /.MEMORY/.aidocs/index.aidocs — those ARE tracked. Only openc… 证据：`.gitignore`\n- **Codeowners**（source_file）：.github/workflows/ @cristian1991 core/scripts/ @cristian1991 mcp/server/aidocs mcp/ @cristian1991 证据：`CODEOWNERS`\n- **Notice**（source_file）：Originally created and maintained by Cristian cristian1991 . 证据：`NOTICE`\n- **Cn Logo**（source_file）： 证据：`cn-logo.svg`\n- **test-driven-validation**（documentation）：Use when behavior changes need proof through tests or verification commands. 证据：`core/.skills/test-driven-validation.md`\n- **AIDOCS local MCP config contains absolute paths**（source_file）：AIDOCS local MCP config contains absolute paths .mcp.json 证据：`mcp/.gitignore`\n- **DTmpkilltests**（source_file）：ERROR: usage: python.exe -m pytest options file or dir file or dir ... python.exe -m pytest: error: unrecognized arguments: -n --dist=loadgroup inifile: D:\\Projects\\Active\\AIDOCS\\mcp\\pyproject.toml rootdir: D:\\Projects\\Active\\AIDOCS\\mcp 证据：`mcp/Dtmpkilltests.txt`\n- **Manifest**（source_file）：recursive-exclude tests recursive-exclude .MEMORY exclude ROADMAP.md exclude ROADMAP .md exclude INDEXING .md exclude RELEASE SUMMARY .md exclude BENCHMARKS.md exclude DOCS SITE STRUCTURE.md prune tests prune benchmarks prune .MEMORY prune docs 证据：`mcp/MANIFEST.in`\n- **tree-sitter core is required by the C AST validator 52,**（source_file）：project name = \"aidocs-mcp\" version = \"2.3.0b2\" description = \"Portable AI coding-agent toolkit — MCP server with indexed code retrieval, session management, and persistent memory\" readme = \"README.md\" license = {text = \"Apache-2.0\"} requires-python = \" =3.11\" authors = {name = \"CodeNexus\", email = \"hello@codenexus.cloud\"} keywords = \"ai\", \"mcp\", \"coding-agent\", \"memory\", \"session\", \"code-index\", \"claude\", \"opencode\" classifiers = \"Development Status :: 4 - Beta\", \"Intended Audience :: Developers\", \"License :: OSI Approved :: Apache Software License\", \"Programming Language :: Python :: 3.11\", \"Programming Language :: Python :: 3.12\", \"Programming Language :: Python :: 3.13\", \"Topic :: Softw… 证据：`mcp/pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Introduction to AIDOCS**：importance `high`\n - source_paths: README.md, mcp/README.md, core/AGENTS.md\n- **Installation Guide**：importance `high`\n - source_paths: README_INSTALL.md, core/scripts/install.sh, core/scripts/install.ps1, mcp/server/aidocs_mcp/cli.py\n- **System Architecture Overview**：importance `high`\n - source_paths: mcp/server/ARCHITECTURE.md, mcp/server/METHODS.md, core/.commands/aidocs.md, mcp/server/aidocs_mcp/types.py\n- **MCP Server Architecture**：importance `high`\n - source_paths: mcp/server/aidocs_mcp/mcp_server.py, mcp/server/aidocs_mcp/service_hub.py, mcp/server/aidocs_mcp/tool_discovery.py, mcp/server/aidocs_mcp/mcp_registry.py, mcp/server/aidocs_mcp/runtime_service.py\n- **Dashboard Architecture**：importance `medium`\n - source_paths: apps/aidocs-dashboard/src/App.tsx, apps/aidocs-dashboard/src/dashboardApi.ts, apps/aidocs-dashboard/src-tauri/src/main.rs, apps/aidocs-dashboard/src-tauri/tauri.conf.json\n- **Memory System**：importance `high`\n - source_paths: core/.MEMORY/.aidocs/memory-system.aidocs, mcp/server/aidocs_mcp/memory_store.py, mcp/server/aidocs_mcp/session_store.py, mcp/server/aidocs_mcp/memory_discovery.py, mcp/server/aidocs_mcp/aidocs_nlp/consumers/memory_surfacer.py\n- **Conductor & Orchestration**：importance `high`\n - source_paths: mcp/server/aidocs_mcp/conductor_comms.py, mcp/server/aidocs_mcp/runtime_orchestration_service.py, mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py, mcp/server/aidocs_mcp/plan_conductor.py, mcp/server/aidocs_mcp/co_conductor.py\n- **Security & Access Control**：importance `high`\n - source_paths: mcp/server/aidocs_mcp/access_gate.py, mcp/server/aidocs_mcp/heuristic_judge.py, mcp/server/aidocs_mcp/output_guard.py, mcp/server/aidocs_mcp/rbac.py, mcp/server/aidocs_mcp/enforcement_pkg/controller.py\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `388d7bd19358d1c5bd17d669b9cc06e6df78078b`\n- inspected_files: `README.md`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | host_targets=mcp_host, claude, claude_code, cursor\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | README/documentation is current enough for a first validation pass.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | last_activity_observed missing\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: 来源证据：v2.0.0 — Unified AccessGate & Agent Enforcement\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.0 — Unified AccessGate & Agent Enforcement\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_2ef38d1286d44ae9b266a98267a2d782 | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 来源证据：v2.0.3 — Token Tracking & Dashboard Fixes\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.3 — Token Tracking & Dashboard Fixes\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_5428bd20316b4bfa987b009350fc138b | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 8: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | issue_or_pr_quality=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 9: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | release_recency=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n", "summary": "Context and operating boundaries for host AI agents.", "title": "AI Context Pack" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card\n\nProject: cristian1991/AIDOCS\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host, claude, claude_code, cursor\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## Project-Specific Pitfalls\n\n- 可能修改宿主 AI 配置 (medium): 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项 (medium): 下游已经要求复核，不能在页面中弱化。 Suggested check: 进入安全/权限治理复核队列。\n- 存在评分风险 (medium): 风险会影响是否适合普通用户安装。 Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n", "summary": "Installation, permission, validation, and pre-recommendation risks.", "title": "Boundary & Risk Card" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/cristian1991/AIDOCS 项目说明书\n\n生成时间：2026-05-16 05:31:31 UTC\n\n## 目录\n\n- [Introduction to AIDOCS](#introduction)\n- [Installation Guide](#installation)\n- [System Architecture Overview](#architecture-overview)\n- [MCP Server Architecture](#mcp-server)\n- [Dashboard Architecture](#dashboard)\n- [Memory System](#memory-system)\n- [Conductor & Orchestration](#conductor-orchestration)\n- [Security & Access Control](#security-gates)\n- [Indexing & Retrieval System](#indexing-retrieval)\n- [Configuration Management](#configuration)\n\n\n\n## Introduction to AIDOCS\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation), [System Architecture Overview](#architecture-overview)\n\n
\nRelated Source Files\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n- [mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n- [apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n- [mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n- [mcp/server/aidocs_mcp/data/opencode_plugin.js](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/data/opencode_plugin.js)\n
\n\n# Introduction to AIDOCS\n\n## Overview\n\nAIDOCS is an intelligent development system that provides AI coding agents with **persistent memory**, **indexed retrieval**, and **orchestration capabilities**. The platform enables AI agents to resume work efficiently instead of rediscovering repository context on every session. 资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n## Purpose and Scope\n\nAIDOCS addresses a fundamental challenge in AI-assisted development: **context loss between sessions**. When an AI coding agent completes a task or reconnects after a break, it traditionally must re-analyze the entire codebase to understand the project structure, recent changes, and development context. AIDOCS eliminates this inefficiency by maintaining persistent context that survives across sessions.\n\nThe system provides:\n\n- **Persistent Memory**: Store and retrieve development context across agent sessions\n- **Indexed Retrieval**: Fast lookup of relevant code, documentation, and project artifacts\n- **Orchestration**: Coordinate multiple AI agents and their activities\n- **Security Guards**: Built-in prompt injection detection and content filtering\n- **RBAC**: Role-Based Access Control for multi-tenant environments\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"AIDOCS Core\"\n A[AI Coding Agent] --> B[MCP Server]\n B --> C[Memory System]\n B --> D[Index Engine]\n B --> E[Session Manager]\n end\n \n subgraph \"Dashboard Layer\"\n C --> F[CastleShell Dashboard]\n D --> F\n E --> F\n F --> G[OverviewPage]\n F --> H[ExecutionPage]\n F --> I[ConductorPage]\n F --> J[RBACPage]\n end\n \n subgraph \"Security Layer\"\n B --> K[output_guard.py]\n K --> L[Prompt Injection Detection]\n K --> M[Sensitive Content Filtering]\n end\n \n subgraph \"External Integrations\"\n N[MCP Registry] --> B\n B --> O[Claude.ai]\n B --> P[OpenAI API]\n end\n```\n\n## Core Components\n\n### MCP Server (Model Context Protocol)\n\nThe AIDOCS MCP server acts as the central communication hub between AI agents and the AIDOCS backend. It handles tool routing, session management, and context retrieval.\n\n**Key Tools Provided:**\n\n| Tool Category | Tools | Purpose |\n|---------------|-------|---------|\n| Classification | `classify_prompt`, `route_prompt` | Advisory routing for prompts |\n| Investigation | `ai_investigate`, `ai_bundle` | Broad context exploration |\n| Search | `ai_find`, `ai_trace` | Symbol and reference search |\n| Database | `schema_query` | Database schema operations |\n| Sessions | `ai_session` | List, create, connect, update, resume sessions |\n| Tasks | `ai_task` | Begin, update, complete, status tasks |\n| Memory | `memory_read`, `memory_capture`, `memory_search` | Memory operations |\n| Project | `project_init`, `project_sync_indexes` | Project initialization |\n| Code Operations | `ai_get_lines`, `ai_text_search`, `ai_search` | Read operations |\n| Edit Operations | `ai_replace`, `ai_edit_lines`, `ai_batch_edit` | Write operations |\n\n资料来源：[mcp/README.md]()\n\n### Memory System\n\nThe memory system provides persistent storage for agent context:\n\n```mermaid\ngraph LR\n A[Capture Event] --> B[memory_capture]\n B --> C[Memory Index]\n C --> D[memory_search]\n D --> E[Relevant Context]\n E --> F[Agent Context]\n```\n\n**Memory Operations:**\n\n- `memory_read`: Retrieve stored memory entries\n- `memory_capture`: Store new context from agent activities\n- `memory_search`: Search across stored memories using natural language\n\n### Session Management\n\nSessions enable agents to resume work without context loss:\n\n```mermaid\nstateDiagram-v2\n [*] --> List: ai_session list\n List --> Create: ai_session create\n Create --> Connect: ai_session connect\n Connect --> Update: ai_session update\n Connect --> Resume: ai_session resume\n Update --> Release: ai_session release\n Resume --> Release\n Release --> [*]\n```\n\nSessions maintain:\n- Current status and goal\n- Owner information\n- Context budget (token estimates, journal entries)\n- Recent execution history\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx]()\n\n### Execution Tracking (Conductor)\n\nThe Conductor system tracks all tool calls and agent actions:\n\n| Field | Description |\n|-------|-------------|\n| `session_id` | Associated session identifier |\n| `capability_name` | Tool or capability invoked |\n| `action_kind` | Type of action performed |\n| `observed_at` | Timestamp of observation |\n| `lane` | Execution lane (execution context) |\n| `logicalMode` | Logical routing mode |\n| `nativeMode` | Native routing mode |\n| `fallbackUsed` | Whether fallback routing was used |\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](), [apps/aidocs-dashboard/src/ExecutionPage.tsx]()\n\n### Security Layer (output_guard.py)\n\nAIDOCS includes robust security features to protect against prompt injection attacks:\n\n**Prompt Injection Patterns Detected:**\n\n| Pattern ID | Regex Pattern | Description |\n|------------|---------------|-------------|\n| `system_override` | `(?:ignore\\|forget\\|disregard) all (?:previous\\|prior\\|above)` | System override attempts |\n| `role_hijack` | `you are now (?:a )?(?:different\\|new\\|my) (?:ai\\|assistant\\|agent\\|bot)` | Role hijacking attempts |\n| `instruction_inject` | `<\\s*(?:system\\|instructions?\\|prompt)\\s*>` | XML tag injection |\n| `delimiter_escape` | `\\`\\`\\`\\s*(?:system\\|instructions?)\\n` | Code block injection |\n| `hidden_instruction` | `(?:IMPORTANT\\|CRITICAL\\|URGENT)\\s*:\\s*(?:ignore\\|override\\|forget\\|disregard)` | Hidden instruction attempts |\n\n**Sensitive Content Patterns:**\n\n| Pattern ID | Regex Pattern | Description |\n|------------|---------------|-------------|\n| `env_file_content` | `^[A-Z_]{3,}=\\S{8,}$` | Potential .env file leaks |\n| `ssh_config` | `(?:Host\\s+\\S+\\|IdentityFile\\s+~/)` | SSH configuration content |\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py]()\n\n### RBAC (Role-Based Access Control)\n\nAIDOCS implements comprehensive role-based access control:\n\n**Key Features:**\n- Permission management with descriptions\n- Escalation paths for elevated privileges\n- Sticky escalations for persistent elevated access\n- Session/task-scoped permission grants\n\n**Escalation Fields:**\n\n| Field | Description |\n|-------|-------------|\n| `requester` | User or agent requesting escalation |\n| `permission` | Permission being escalated |\n| `phrase` | Trigger phrase for escalation |\n| `session / task` | Associated session or task |\n| `sticky` | Whether escalation persists |\n| `created · expires` | Temporal bounds |\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx]()\n\n### Dashboard Interface (CastleShell)\n\nThe AIDOCS Dashboard provides a web-based interface for monitoring and managing the system:\n\n```mermaid\ngraph TD\n subgraph \"CastleShell Components\"\n A[CastleShell] --> B[Navigation]\n A --> C[StatusBar]\n A --> D[ContextRail]\n A --> E[TopStrip]\n end\n \n subgraph \"Dashboard Pages\"\n B --> O[OverviewPage]\n B --> P[ExecutionPage]\n B --> Q[ConductorPage]\n B --> R[RBACPage]\n B --> S[SkillsPage]\n B --> T[MonitoringPage]\n B --> U[RegistryPage]\n B --> V[TomlConfigsPage]\n end\n \n subgraph \"Navigation Counts\"\n C --> W[CastleNavCounts]\n W --> X[executions]\n W --> Y[sessions]\n W --> Z[escalations]\n end\n```\n\n**CastleShell Props:**\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `active` | `NavKey` | Currently active navigation item |\n| `onSelect` | `(key: NavKey) => void` | Navigation callback |\n| `counts` | `CastleNavCounts` | Badge counts for navigation |\n| `managedMode` | `boolean` | Whether managed mode is active |\n| `version` | `string` | AIDOCS version |\n| `mcpConnected` | `boolean` | MCP server connection status |\n| `activeLayer` | `string` | Current execution layer |\n| `saveState` | `string` | Current save state indicator |\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx]()\n\n## Setup and Installation\n\n### Initial Setup Wizard\n\nThe setup wizard guides users through project configuration:\n\n```mermaid\ngraph LR\n A[Welcome] --> B[Project Selection]\n B --> C[Environment Check]\n C --> D[Host Configuration]\n D --> E[Configure]\n E --> F[Done]\n```\n\n**Setup Steps:**\n\n1. **Welcome**: Introduction and feature overview\n2. **Project Selection**: Choose project folder path\n3. **Environment Check**: Verify Node.js and other dependencies\n4. **Host Configuration**: Configure Claude.ai, OpenAI API access\n5. **Configure**: Set up MCP, hooks, and project structure\n6. **Done**: Confirmation of successful setup\n\n**Setup Wizard Features:**\n\n- Progress indicator showing current step\n- Environment detection with status checks\n- Host authentication status display\n- Automatic installation option for missing tools\n- Sign-in buttons for external services\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n### Environment Detection\n\nThe setup wizard detects:\n\n| Component | Detection | Installable |\n|-----------|-----------|-------------|\n| Node.js | Checks for CLI agent support | No |\n| Claude | Checks `claude.ai` authentication | Yes |\n| OpenAI | Checks API key configuration | Yes |\n| Custom Hosts | Configurable external services | Yes |\n\n### MCP Registry Integration\n\nAIDOCS supports discovering and installing MCP servers from a registry:\n\n- Search functionality for MCP servers\n- Install commands extraction\n- Transport and command information display\n- Website URL tracking\n\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx]()\n\n## Workflow Patterns\n\n### Agent Workflow with AIDOCS\n\n```mermaid\ngraph TD\n A[Start Task] --> B[ai_session create]\n B --> C[Define Goal]\n C --> D[ai_investigate]\n D --> E[ai_find / ai_trace]\n E --> F[ai_get_symbol_info]\n F --> G[Edit Code]\n G --> H[memory_capture]\n H --> I[ai_session update]\n I --> J{More Work?}\n J -->|Yes| E\n J -->|No| K[ai_task complete]\n K --> L[ai_session release]\n L --> M[End]\n```\n\n### Code Editing Workflow\n\nRecommended sequence for code modifications:\n\n1. `ai_get_lines` — Read file content\n2. `ai_get_symbol_info(kind=\"signature\"|\"constructor\")` — Confirm target signatures\n3. `ai_edit_lines` or `ai_batch_edit` — Apply changes\n4. `ai_task_complete` — Mark task complete\n\n**Important:** Do not mix different edit methods within the same task.\n\n### Investigation Workflow\n\nFor understanding unfamiliar code:\n\n1. `session_resume_bundle` — Get project/session/skills/plan overview\n2. `action_surface_current_session_bundle` — Identify likely next tools\n3. `ai_find(query, mode=\"symbols\")` — Locate relevant symbols\n4. `ai_get_symbol_snippet` — Retrieve code snippets\n5. `ai_bundle(concept, mode=\"subsystem\")` — Get subsystem context\n\n资料来源：[mcp/server/aidocs_mcp/data/opencode_plugin.js]()\n\n## Context Budget Management\n\nSessions track context budget usage:\n\n| Metric | Description |\n|--------|-------------|\n| `status` | Budget status (available, exhausted, etc.) |\n| `reason` | Reason for budget state |\n| `estimated_tokens` | Current token count estimate |\n| `journal_entries` | Number of journal entries |\n| `available` | Whether compaction is possible |\n\n**Compaction:** When context budget is running low, use the compact function to reduce token usage while preserving critical context.\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx]()\n\n## Monitoring and Analytics\n\n### Execution Monitoring\n\nTrack agent activities across dimensions:\n\n- **By Event Kind**: Categorize by tool type or action\n- **By Source**: Track which agent or integration triggered events\n- **Recent Execution**: View recent events with timestamps\n\n### Lane Management\n\nLanes provide execution isolation and context grouping:\n\n- Events can be tagged with `lane_id`\n- Related events are grouped together\n- Status tracking (applied, refused, blocked)\n\n资料来源：[apps/aidocs-dashboard/src/MonitoringPage.tsx](), [apps/aidocs-dashboard/src/LaneDetailPanel.tsx]()\n\n## Skills System\n\nAIDOCS supports dynamic skill registration:\n\n| Property | Description |\n|----------|-------------|\n| `name` | Skill identifier |\n| `description` | Human-readable description |\n| `skill_kind` | Type of skill |\n| `provider` | Skill provider name |\n| `source` | Skill source location |\n| `selected` | Whether skill is selected for use |\n| `active` | Whether skill is currently active |\n| `activation_tags` | Tags triggering skill activation |\n| `provider_status` | Current provider state |\n\n资料来源：[apps/aidocs-dashboard/src/SkillsPage.tsx]()\n\n## TOML Configuration\n\nAIDOCS uses TOML for project and system configuration:\n\n- Configuration document browsing by category\n- Syntax-highlighted editor with save functionality\n- Support for multiple TOML files per category\n\n资料来源：[apps/aidocs-dashboard/src/TomlConfigsPage.tsx]()\n\n## Command Line Interface\n\n### Basic Commands\n\n```bash\npip install aidocs-mcp\naidocs --version\naidocs-mcp # start MCP server\n```\n\n## Summary\n\nAIDOCS provides a comprehensive platform for enhancing AI coding agents with persistent memory and intelligent context management. Its modular architecture includes:\n\n- **MCP Server**: Central communication hub with 20+ specialized tools\n- **Memory System**: Persistent storage and retrieval of development context\n- **Session Management**: Seamless task resumption across agent sessions\n- **Security Layer**: Prompt injection detection and sensitive content filtering\n- **RBAC**: Fine-grained access control for enterprise environments\n- **Dashboard**: Web-based monitoring and management interface\n\nBy integrating AIDOCS into AI-assisted development workflows, teams can significantly reduce the time agents spend re-establishing context, leading to faster development cycles and more consistent code quality.\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Introduction to AIDOCS](#introduction), [MCP Server Architecture](#mcp-server)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n- [core/scripts/install.sh](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.sh)\n- [core/scripts/install.ps1](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.ps1)\n- [mcp/server/aidocs_mcp/cli.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/cli.py)\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n
\n\n# Installation Guide\n\nAIDOCS is an AI-powered documentation and coding assistant platform that provides persistent memory, indexed retrieval, and orchestration for AI coding agents. This guide covers all installation methods, prerequisites, and configuration steps required to deploy AIDOCS in your development environment.\n\n## Prerequisites\n\nBefore installing AIDOCS, ensure your system meets the following requirements.\n\n### System Requirements\n\n| Requirement | Minimum | Recommended |\n|-------------|---------|-------------|\n| Node.js | 18.x | 20.x LTS |\n| Python | 3.10+ | 3.11+ |\n| Disk Space | 500 MB | 2 GB |\n| RAM | 4 GB | 8 GB |\n| OS | macOS, Linux, Windows (WSL2) | macOS, Linux |\n\n### Supported AI Host Platforms\n\nAIDOCS integrates with multiple AI coding assistants. The installation process detects available platforms.\n\n| Platform | Status Detection | Authentication |\n|----------|-----------------|----------------|\n| Claude (claude.ai) | Auto-detected | Requires sign-in |\n| OpenAI (ChatGPT) | Auto-detected | Requires API key |\n| Cursor | Supported | Via MCP |\n| Windsurf | Supported | Via MCP |\n\n资料来源：[SetupWizardPage.tsx:42-56](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n## Installation Methods\n\nAIDOCS supports multiple installation methods across different platforms.\n\n### Automated Installation\n\n#### macOS and Linux\n\nUse the shell installer script for POSIX-compliant systems:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cristian1991/AIDOCS/main/core/scripts/install.sh | bash\n```\n\nThe script performs the following operations:\n1. Checks for required dependencies (Node.js, Python)\n2. Creates necessary directory structure\n3. Installs the AIDOCS CLI globally\n4. Sets up MCP server configurations\n5. Initializes the project workspace\n\n资料来源：[core/scripts/install.sh](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.sh)\n\n#### Windows\n\nFor Windows systems, use PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/cristian1991/AIDOCS/main/core/scripts/install.ps1 | iex\n```\n\nThe PowerShell installer:\n1. Validates PowerShell version (5.1+ required)\n2. Installs dependencies via winget or chocolatey\n3. Configures Windows-specific paths\n4. Registers AIDOCS in the system PATH\n\n资料来源：[core/scripts/install.ps1](https://github.com/cristian1991/AIDOCS/blob/main/core/scripts/install.ps1)\n\n### Manual Installation\n\nFor custom deployments, install the CLI directly:\n\n```bash\n# Clone the repository\ngit clone https://github.com/cristian1991/AIDOCS.git\ncd AIDOCS\n\n# Install Python dependencies\npip install -e .\n\n# Install Node.js dependencies\ncd apps/aidocs-dashboard\nnpm install\nnpm run build\n```\n\n## Setup Wizard\n\nThe first time you launch AIDOCS, a setup wizard guides you through the configuration process.\n\n### Workflow Overview\n\n```mermaid\ngraph TD\n A[Welcome] --> B[Project Selection]\n B --> C[Prerequisites Check]\n C --> D[AI Host Configuration]\n D --> E[Configuring]\n E --> F[Done]\n \n C -->|Missing dependencies| G[Install Required Tools]\n G --> C\n \n D -->|Not authenticated| H[Sign In Required]\n H --> D\n```\n\n### Step 1: Welcome\n\nThe welcome screen introduces AIDOCS capabilities:\n\n> AIDOCS gives your AI coding agents persistent memory, indexed retrieval, and orchestration — so they resume work instead of rediscovering your repo every time.\n\n资料来源：[SetupWizardPage.tsx:25-31](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 2: Project Selection\n\nSpecify the project folder where AIDOCS will operate:\n\n| Field | Description |\n|-------|-------------|\n| Project Path | Absolute path to your project folder (leave empty for current directory) |\n| Auto-detect | Attempts to find an existing AIDOCS configuration |\n\n```typescript\n setProjectPath(e.target.value)}\n placeholder=\"Project folder path (or leave empty for current directory)\"\n/>\n```\n\n资料来源：[SetupWizardPage.tsx:50-55](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 3: Prerequisites Check\n\nThe installer validates the presence of required tools:\n\n| Tool | Required | Optional |\n|------|----------|----------|\n| Node.js | Yes | For CLI agents |\n| Claude | If using Claude | — |\n| OpenAI | If using GPT | — |\n\nDetection results display with status indicators:\n\n| Status | Icon | Meaning |\n|--------|------|---------|\n| Pass | `+` | Installed and authenticated |\n| Warning | `!` | Installed but not signed in |\n| Missing | `-` | Not installed (can be auto-installed) |\n\nFor hosts requiring authentication:\n\n```typescript\n\n```\n\n资料来源：[SetupWizardPage.tsx:58-72](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 4: Configuration\n\nThe installer configures MCP servers, hooks, and project structure:\n\n| Configuration Item | Output Path | Description |\n|-------------------|-------------|-------------|\n| MCP Configuration | `{project}/.aidocs/mcp.json` | MCP server endpoints |\n| Hooks Registration | `{project}/.aidocs/hooks.json` | Pre/post execution hooks |\n| Project Initialization | `{project}/.aidocs/` | Working directory for AIDOCS |\n\n```typescript\n{step === \"configure\" && (\n
\n

Configuring

\n

Setting up MCP, hooks, and project structure...

\n
\n
\n)}\n```\n\n资料来源：[SetupWizardPage.tsx:95-102](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n### Step 5: Completion\n\nUpon successful installation, the wizard displays:\n\n| Checklist Item | Status |\n|----------------|--------|\n| MCP configured | ✅ With path shown |\n| Hooks registered | ✅ With path shown |\n| Project initialized | ✅ |\n| MCP servers installed | ✅ (if any selected) |\n\n资料来源：[SetupWizardPage.tsx:104-130](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n## MCP Server Installation\n\nAIDOCS supports Model Context Protocol (MCP) servers for extended functionality.\n\n### Server Registry\n\nThe dashboard includes a searchable registry of MCP servers:\n\n```typescript\n
\n {results.map((server: RegistrySearchResult) => (\n // Server card rendering\n ))}\n
\n```\n\n资料来源：[RegistryPage.tsx:25-28](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n### Installing MCP Servers\n\nEach server in the registry provides installation commands:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `install_commands` | Array | Available installation methods |\n| `transport` | String | Protocol (stdio, sse, http) |\n| `command` | String | Execution command |\n| `website_url` | String | Official documentation |\n\n```typescript\nconst installText = typeof firstCmd === \"string\" \n ? firstCmd \n : String((firstCmd as Record).command ?? \"\");\n```\n\n资料来源：[RegistryPage.tsx:30-36](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n## CLI Commands\n\nThe AIDOCS CLI provides command-line access to installation and management functions.\n\n### Primary Commands\n\n| Command | Description |\n|---------|-------------|\n| `aidocs init` | Initialize AIDOCS in the current project |\n| `aidocs start` | Launch the dashboard |\n| `aidocs status` | Check MCP and service status |\n| `aidocs config` | Manage configuration |\n\n资料来源：[mcp/server/aidocs_mcp/cli.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/cli.py)\n\n### Post-Installation Steps\n\nAfter successful installation:\n\n1. **Open your project** in your preferred IDE\n2. **Start a new agent session**\n3. **Type `/aidocs`** to begin\n\n```html\n
\n

Next Steps

\n
    \n
  1. Open {projectPath || \"your project\"} in your IDE
    2. \n
  2. Start a new agent session
    3. \n
  3. Type /aidocs to begin
    4. \n
\n
\n```\n\n资料来源：[SetupWizardPage.tsx:131-139](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n## Dashboard Access\n\nAfter installation, access the AIDOCS dashboard:\n\n```bash\n# Start the dashboard server\naidocs start\n\n# Or open the dashboard directly\nopen http://localhost:3000\n```\n\nThe dashboard is served from `apps/aidocs-dashboard/` and provides:\n\n- **Overview**: Session status, context budget, recent execution\n- **Registry**: Browse and install MCP servers\n- **RBAC**: Manage roles and permissions\n- **Execution**: View tool call history\n- **Settings**: Configure project options\n\n资料来源：[apps/aidocs-dashboard/index.html](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/index.html)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Node.js not found | Install via `nvm install 20` or download from nodejs.org |\n| Authentication failed | Sign in via the setup wizard \"Sign in\" button |\n| MCP connection failed | Check firewall settings and MCP endpoint configuration |\n| Dashboard won't load | Ensure port 3000 is available, or configure alternative port |\n\n### Verification\n\nConfirm successful installation:\n\n```bash\n# Check AIDOCS version\naidocs --version\n\n# Verify MCP connection\naidocs status\n\n# Test configuration\naidocs config --validate\n```\n\n## Upgrade Instructions\n\nTo upgrade AIDOCS to the latest version:\n\n```bash\n# Update via npm (if installed globally)\nnpm update -g aidocs\n\n# Or use the built-in update command\naidocs update\n```\n\nAfter upgrading, run the setup wizard again to apply configuration changes:\n\n```bash\naidocs setup --wizard\n```\n\n## Uninstallation\n\nTo remove AIDOCS from a project:\n\n```bash\n# Remove AIDOCS files (keeps data)\naidocs uninstall\n\n# Complete removal including data\naidocs uninstall --clean\n```\n\nThis removes:\n- `.aidocs/` directory\n- MCP configurations\n- Hook registrations\n\nGlobal CLI tools remain installed unless explicitly removed with `npm uninstall -g aidocs`.\n\n---\n\n\n\n## System Architecture Overview\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server), [Dashboard Architecture](#dashboard), [Memory System](#memory-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cistian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n- [apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n- [mcp/server/aidocs_mcp/data/opencode_plugin.js](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/data/opencode_plugin.js)\n- [apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n- [apps/aidocs-dashboard/src/LivePage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/LivePage.tsx)\n- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n- [apps/aidocs-dashboard/src/BashPolicyPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/BashPolicyPanel.tsx)\n
\n\n# System Architecture Overview\n\nAIDOCS is a persistent memory and orchestration framework designed for AI coding agents. It provides indexed retrieval, session persistence, and policy-based control to enable AI agents to resume work efficiently without repeatedly rediscovering repository context. The system consists of a frontend dashboard application and a backend MCP (Model Context Protocol) server that communicates with AI coding agents.\n\n## Core Architecture Layers\n\nAIDOCS operates through three primary architectural layers that work together to provide persistent context and control for AI agents.\n\n### Layer 1: MCP Server (`mcp/server/`)\n\nThe MCP server acts as the bridge between AI coding agents and the AIDOCS persistent storage system. It exposes tools and resources that agents can invoke during their sessions. The server handles context retrieval, session management, and policy enforcement through a standardized MCP interface.\n\nThe server provides several categories of tools including context management tools (`ai_find`, `ai_get_symbol_snippet`, `ai_bundle`), session tools (`session_resume_bundle`, `action_surface_current_session_bundle`), and investigation tools (`ai_investigate`). These tools enable agents to query indexed project knowledge, retrieve symbol information, and understand codebase structure.\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n资料来源：[mcp/server/aidocs_mcp/data/opencode_plugin.js]()\n\n### Layer 2: Dashboard Application (`apps/aidocs-dashboard/`)\n\nThe dashboard is a React-based web application that provides a visual interface for managing AIDOCS configuration, monitoring agent sessions, and administering security policies. The dashboard communicates with the MCP server through IPC (Inter-Process Communication) to retrieve and display session data.\n\nThe dashboard uses a modular component architecture built around the `CastleShell` wrapper, which provides consistent navigation, status indicators, and layout structure across all pages.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx]()\n\n### Layer 3: Persistent Storage and Indexing\n\nAIDOCS maintains indexed knowledge of the project codebase, session state, and configuration policies. This indexing enables fast retrieval of relevant context when agents resume sessions or need to understand unfamiliar parts of the codebase.\n\n## Dashboard Component Architecture\n\nThe AIDOCS dashboard is structured as a single-page application with multiple views accessible through a navigation sidebar. Each view addresses a specific aspect of agent management and monitoring.\n\n```mermaid\ngraph TD\n A[CastleShell] --> B[OverviewPage]\n A --> C[LivePage]\n A --> D[ConductorPage]\n A --> E[ExecutionPage]\n A --> F[RBACPage]\n A --> G[SettingsPage]\n A --> H[RegistryPage]\n A --> I[CommandPalette]\n \n B --> J[Snapshot Data]\n C --> K[Real-time Events]\n D --> L[Tool Routing]\n E --> M[Event Details]\n \n N[MCP Server] --> J\n N --> K\n N --> L\n N --> M\n```\n\n### CastleShell — Main Application Wrapper\n\nThe `CastleShell` component serves as the root layout container for the entire dashboard. It manages navigation state, renders the sidebar, and displays the status bar showing connection status and project information.\n\n**Key Properties:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `active` | `NavKey` | Currently selected navigation item |\n| `onSelect` | `(key: NavKey) => void` | Callback when navigation changes |\n| `counts` | `CastleNavCounts` | Badge counts for navigation items |\n| `managedMode` | `boolean` | Whether restricted mode is enabled |\n| `mcpConnected` | `boolean` | MCP server connection status |\n| `version` | `string` | AIDOCS version display |\n\nThe status bar component within CastleShell indicates MCP connection state with a color-coded indicator (green for connected, red for disconnected) and displays the current session ID and active layer.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx]()\n\n### SetupWizardPage — Initial Configuration\n\nThe `SetupWizardPage` guides users through initial AIDOCS setup with a multi-step wizard interface. It handles project selection, dependency detection, MCP configuration, and hook registration.\n\n**Setup Steps Flow:**\n\n```mermaid\ngraph LR\n A[welcome] --> B[project]\n B --> C[detection]\n C --> D[configure]\n D --> E[done]\n \n A -->|Get Started| B\n B -->|Select Folder| C\n C -->|Dependencies OK| D\n D -->|Configuration Complete| E\n```\n\nThe wizard validates system requirements including Node.js presence and AI platform authentication status (Claude, OpenAI). It can detect missing components and offer installation options directly within the interface.\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n## Session and Execution Monitoring\n\n### OverviewPage — Session Snapshot\n\nThe `OverviewPage` displays a consolidated snapshot of the current session including session metadata, capability usage statistics, and recent execution events. It provides at-a-glance monitoring of agent activity through a dashboard-style layout with panels for different data categories.\n\nThe page renders execution data in a tabular format showing capability names, action kinds, and timestamps for recent events. This allows operators to quickly assess agent behavior without drilling into detailed logs.\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx]()\n\n### LivePage — Real-time Event Stream\n\nThe `LivePage` provides a real-time view of agent execution events with support for lane-based isolation and policy enforcement. It displays a scrollable event feed with status indicators and allows operators to approve or reject escalated permission requests.\n\n**LivePage Features:**\n\n| Feature | Description |\n|---------|-------------|\n| Event Feed | Real-time scrolling list of agent actions |\n| Lane Indicators | Visual identification of execution lanes |\n| Approval Queue | Pending permission escalation requests |\n| Quick Actions | Controls for stopping lanes or pausing execution |\n\nThe control panel on the right side of the page contains pending approvals with approve/reject buttons, quick action buttons for lane management, and lane detail expanders showing related events.\n\n资料来源：[apps/aidocs-dashboard/src/LivePage.tsx]()\n\n### ExecutionPage — Detailed Event Analysis\n\nThe `ExecutionPage` provides deep-dive analysis of individual execution events. It displays full payload data, result summaries, and audit information for each recorded event. The page supports filtering and searching through execution history to locate specific agent actions.\n\n### LaneDetailPanel — Lane Event Context\n\nThe `LaneDetailPanel` component renders detailed information about specific execution lanes including related events, lane status, and execution history. Events are displayed with timestamps and status indicators that reflect whether actions were allowed, refused, or blocked.\n\nLane events show a color-coded status pill: green for `applied` or `allowed`, red for `refused` or `blocked`, and muted gray for other states.\n\n资料来源：[apps/aidocs-dashboard/src/LaneDetailPanel.tsx]()\n\n## Policy Management\n\n### BashPolicyPanel — Shell Command Control\n\nThe `BashPolicyPanel` provides a visual interface for managing shell command execution policies. It displays a summary of allow/deny/bubble counts and allows filtering by policy type.\n\n**Policy Controls:**\n\n| Control | Description |\n|---------|-------------|\n| Search Filter | Filter commands by name match |\n| Type Chips | Filter by all/allow/deny/bubble/modified |\n| Collapse Toggle | Show/hide policy details |\n\nEach policy entry shows the effective counts for allow, deny, and bubble policies, along with the active layer where modifications were made and the default fallback policy.\n\n资料来源：[apps/aidocs-dashboard/src/BashPolicyPanel.tsx]()\n\n### RBACPage — Role-Based Access Control\n\nThe `RBACPage` manages permissions, escalations, and custom policy configurations. It provides three tabbed views:\n\n1. **Policies Tab** — Lists configured policies with their states (system/custom)\n2. **Permissions Tab** — Shows available permission definitions\n3. **Escalations Tab** — Displays pending or active permission escalations\n\nThe escalations table tracks requesters, requested permissions, session/task context, sticky status, and expiration timestamps.\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx]()\n\n## MCP Server Integration\n\n### RegistryPage — MCP Server Discovery\n\nThe `RegistryPage` enables browsing and installing MCP servers from a remote registry. It supports searching for servers by name and displays installation commands, transport types, and website URLs for each available server.\n\n**Server Card Information:**\n\n| Field | Description |\n|-------|-------------|\n| Name | Server identifier |\n| Transport | Communication protocol |\n| Command | Installation command |\n| Website | Documentation URL |\n\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx]()\n\n### ConductorPage — Tool Routing Configuration\n\nThe `ConductorPage` manages the conductor tool routing system, which controls how different AI backends (Claude, Codex, OpenCode) are used for various tasks. It displays recent tool calls with routing audit information and allows configuration of routing rules.\n\n**Conductor Configuration Options:**\n\n| Setting | Options | Default |\n|---------|---------|---------|\n| Backend | claude, codex, opencode | claude |\n| Claude Model | Model identifier | — |\n| Codex Model | Model identifier | — |\n| OpenCode Model | Model identifier | — |\n\nThe page shows a diff viewer for edit operations, displaying old and new content side-by-side for easy comparison of changes made by the agent.\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx]()\n\n## User Interface Components\n\n### CommandPalette — Quick Action Interface\n\nThe `CommandPalette` provides keyboard-driven access to common actions. It supports fuzzy search, keyboard navigation (arrow keys), execution (Enter), and quick filtering (Tab).\n\n**Keyboard Shortcuts:**\n\n| Key | Action |\n|-----|--------|\n| ↑/↓ | Navigate commands |\n| Enter | Execute selected command |\n| Tab | Switch to filter mode |\n| Esc | Close palette |\n\nThe palette displays commands with status indicators showing whether they are allowed, denied, or require escalation.\n\n资料来源：[apps/aidocs-dashboard/src/CommandPalette.tsx]()\n\n### SettingDetailPanel — Configuration Editor\n\nThe `SettingDetailPanel` displays detailed information about individual configuration entries including current values, origins, and layer assignments. It supports editing configuration values directly within the panel.\n\nThe panel includes a per-leaf origin view that shows which layers contributed to each configuration value, useful for understanding inheritance and override behavior in multi-layered configurations.\n\n资料来源：[apps/aidocs-dashboard/src/SettingDetailPanel.tsx]()\n\n## Data Flow Architecture\n\n```mermaid\ngraph TD\n subgraph Agents[\"AI Coding Agents\"]\n Claude[Claude AI]\n Codex[Codex]\n OpenCode[OpenCode]\n end\n \n subgraph MCP[\"MCP Protocol Layer\"]\n Tools[MCP Tools]\n Resources[MCP Resources]\n Notifications[Notifications]\n end\n \n subgraph Server[\"AIDOCS Backend\"]\n Context[Context Engine]\n Index[Indexing Service]\n Policy[Policy Engine]\n Session[Session Manager]\n end\n \n subgraph Dashboard[\"Dashboard Frontend\"]\n UI[React Components]\n IPC[IPC Bridge]\n end\n \n Claude -->|MCP| Tools\n Codex -->|MCP| Tools\n OpenCode -->|MCP| Tools\n \n Tools --> Context\n Context --> Index\n Index --> Policy\n Policy --> Session\n \n Session -->|Events| Dashboard\n UI -->|Config| Session\n IPC -->|Status| UI\n```\n\n## Security Architecture\n\nAIDOCS implements a multi-layered security model through the following mechanisms:\n\n**Permission Escalation:** Agents can request elevated permissions for specific operations. These requests appear in the LivePage approval queue for operator review before execution proceeds.\n\n**Policy Layers:** Configuration policies are organized into layers with inheritance. The SettingDetailPanel shows which layer contributed each configuration value, enabling audit and rollback.\n\n**Bash Command Policies:** Shell execution is controlled through allow/deny/bubble policies. The BashPolicyPanel provides visibility into these rules and supports runtime modification.\n\n**Connection Verification:** The status bar in CastleShell continuously monitors MCP connection status. Loss of connection triggers visual indicators and can be configured to halt agent execution.\n\n## Summary\n\nThe AIDOCS architecture provides a complete framework for persistent AI agent context management. The MCP server layer exposes tools for agents to query indexed knowledge and manage sessions. The dashboard provides comprehensive monitoring, configuration, and policy management capabilities. Together, these components enable AI coding agents to maintain context across sessions, operate within defined security boundaries, and provide operators with full visibility into agent activities.\n\n---\n\n\n\n## MCP Server Architecture\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Conductor & Orchestration](#conductor-orchestration), [Security & Access Control](#security-gates)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/mcp_server.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_server.py)\n- [mcp/server/aidocs_mcp/service_hub.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/service_hub.py)\n- [mcp/server/aidocs_mcp/tool_discovery.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_discovery.py)\n- [mcp/server/aidocs_mcp/mcp_registry.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_registry.py)\n- [mcp/server/aidocs_mcp/runtime_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n
\n\n# MCP Server Architecture\n\nThe AIDOCS MCP Server is a Python-based Model Context Protocol implementation that provides persistent memory, indexed retrieval, and orchestration capabilities for AI coding agents. It acts as an intermediary layer between AI coding assistants (like Claude Code or OpenCode) and project-specific context, enabling agents to maintain memory across sessions and resume work without re-discovering repository structures.\n\n## Core Architecture Overview\n\nThe MCP Server follows a modular architecture with distinct layers for tool management, security enforcement, and runtime orchestration.\n\n```mermaid\ngraph TD\n subgraph \"MCP Server Core\"\n MS[mcp_server.py
FastMCP Entry Point]\n SH[service_hub.py
Service Hub]\n end\n \n subgraph \"Tool Layer\"\n TD[tool_discovery.py
Tool Discovery]\n CE[server_code_edit_tools.py
Edit Tools]\n CT[server_code_tools.py
Code Tools]\n end\n \n subgraph \"Security Layer\"\n GATE[Gate Architecture
6-Level Cascade]\n end\n \n subgraph \"Runtime Services\"\n RS[runtime_service.py
Runtime Service]\n REG[mcp_registry.py
Registry]\n end\n \n subgraph \"External Integrations\"\n CC[Claude Hook]\n OC[OpenCode Plugin]\n end\n \n MS --> SH\n SH --> TD\n SH --> CE\n SH --> CT\n SH --> RS\n MS --> REG\n CC --> MS\n OC --> MS\n```\n\n资料来源：[mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n\n## Server Entry Point\n\nThe `mcp_server.py` file serves as the primary entry point for the MCP server, initializing FastMCP and registering all available tools and resources.\n\n### Server Initialization\n\nThe server follows this initialization sequence:\n\n1. **Configuration Loading** - Loads `aidocs.toml` from the project root\n2. **Service Hub Initialization** - Establishes the central service coordinator\n3. **Tool Registration** - Discovers and registers all available MCP tools\n4. **Registry Setup** - Configures the MCP server registry for host integrations\n5. **Security Gate Bootstrap** - Initializes the gate architecture\n\n资料来源：[mcp/server/aidocs_mcp/mcp_server.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_server.py)\n\n## Service Hub\n\nThe `service_hub.py` module acts as the central coordinator for all MCP services, providing a unified interface for tool execution, state management, and service discovery.\n\n### Hub Components\n\n| Component | Purpose | File |\n|-----------|---------|------|\n| `hub.code` | Code analysis and symbol operations | server_code_tools.py |\n| `hub.edit` | File editing operations | server_code_edit_tools.py |\n| `hub.runtime` | Session and task management | runtime_service.py |\n| `hub.managed_mode` | Managed/unmanaged mode state | service_hub.py |\n| `hub.session` | Session state management | service_hub.py |\n\n### Managed Mode System\n\nThe Service Hub maintains a managed mode state that controls whether the MCP server operates in supervised or unsupervised mode.\n\n```python\nmanaged = hub.managed_mode.get_mode(project_root)\nif managed.get(\"active\"):\n # Enforce gate architecture\n # Block raw file tools\n # Route through workflow system\n```\n\n资料来源：[mcp/server/aidocs_mcp/service_hub.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/service_hub.py)\n资料来源：[mcp/server/aidocs_mcp/server_code_edit_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_edit_tools.py)\n\n## Tool Discovery\n\nThe `tool_discovery.py` module implements dynamic tool discovery, enabling the MCP server to expose capabilities based on runtime context and project configuration.\n\n### Discovery Process\n\n```mermaid\ngraph LR\n A[Project Root] --> B[Scan aidocs.toml]\n B --> C[Check .MEMORY/ Structure]\n C --> D[Validate Configuration]\n D --> E[Register Available Tools]\n E --> F[Expose via MCP Protocol]\n```\n\n### Available Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| **Code Analysis** | `ai_find`, `ai_get_symbol_snippet`, `ai_get_symbol_info`, `ai_bundle`, `ai_schema_query` | Symbol search and code understanding |\n| **Code Editing** | `ai_create_file`, `ai_edit_lines`, `ai_batch_edit`, `ai_str_replace`, `ai_delete_lines` | File modification operations |\n| **Session Management** | `session_resume_bundle`, `task_begin`, `task_update`, `task_complete` | Workflow orchestration |\n| **Project Operations** | `project_init`, `project_bootstrap_or_resume`, `project_status` | Project lifecycle management |\n\n资料来源：[mcp/server/aidocs_mcp/tool_discovery.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_discovery.py)\n\n## Code Analysis Tools\n\nThe code analysis tools provide AI agents with capabilities to navigate, understand, and investigate codebases.\n\n### Symbol Information Modes\n\nThe `ai_get_symbol_info` tool supports multiple query modes for different levels of symbol detail:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `signature` | Single method signature | Verify function parameters |\n| `signatures` | Multiple method signatures | Compare overloaded methods |\n| `constructor` | Constructor parameters for a type | Understand object instantiation |\n| `constructors` | Batch constructor queries | Analyze multiple types |\n| `enum` | Enum values and members | List state options |\n| `properties` | Entity properties | Understand data structures |\n| `api` | Service API surface | Map service endpoints |\n\n资料来源：[mcp/server/aidocs_mcp/server_code_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_tools.py)\n\n### Investigation Patterns\n\nThe `ai_investigate` tool provides guided navigation with depth and focus parameters:\n\n```python\nai_investigate(concept, depth=..., focus=...)\n# depth: exploration depth\n# focus: symbol-ranked, favors types/classes/structs\n```\n\nInvestigation alternatives:\n- Known symbol name → `ai_find(name, mode=\"symbols\")`\n- Concept/type search → `ai_investigate(concept, depth=..., focus=...)`\n- Architecture mapping → `ai_bundle(path, mode=\"file\"|\"subsystem\")`\n\n## Gate Architecture\n\nThe security layer implements a 6-level cascade gate system that controls tool execution based on context and permissions.\n\n### Gate Levels\n\n| Level | Gate | Action | Condition |\n|-------|------|--------|-----------|\n| 1 | Managed Mode | Block raw file tools when managed | `managed.active == true` |\n| 2 | Infrastructure | Block writes to aidocs.toml, aidocs_mcp/* | Project config files |\n| 3 | Sensitive Files | Block .env, credentials, keys | File extension/name match |\n| 4 | Memory Path | .MEMORY/ reads free, workflow writes intent-gated | Path-based rules |\n| 5 | Read Gate | Per-file discovery, `known_exact_path` bypass | File visibility rules |\n| 6 | Edit Gate | Requires prior read/discovery | Edit sequence validation |\n\n资料来源：[mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n\n### Gate Flow\n\n```mermaid\ngraph TD\n A[Tool Request] --> B{Level 1: Managed Mode?}\n B -->|Unmanaged| C[Execute Tool]\n B -->|Managed| D{Level 2: Infrastructure?}\n D -->|No| E{Level 3: Sensitive Files?}\n D -->|Yes| X[Block + Log]\n E -->|No| F{Level 4: Memory Path?}\n E -->|Yes| X\n F -->|Check| G{Level 5: Read Gate?}\n G -->|No| H{Level 6: Edit Gate?}\n G -->|Yes| C\n H -->|Valid| C\n H -->|Invalid| X\n```\n\n### Configuration Settings\n\nSecurity gates can be configured via the dashboard:\n\n| Setting | Purpose | Risk |\n|---------|---------|------|\n| `dev.dev_mode` | Enables editing AIDOCS MCP server source files | Development only |\n| `security.allow_config_edit` | Allows agents to modify AIDOCS config via tool calls | High - can change gate settings |\n| `security.enforce` | Enables/disables all tool gates | Critical - removes bash allowlist, raw tool blocking |\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n## Runtime Service\n\nThe `runtime_service.py` module manages session lifecycle, task orchestration, and state persistence.\n\n### Session Management\n\n```python\nresult = self.task_begin(\n project_root=project_root,\n session_id=session_id,\n goal=None,\n state=state,\n upcoming=upcoming,\n partial_goals=partial_goals,\n end_goal=end_goal,\n blockers=blockers,\n relevant_files=effective_relevant_files,\n relevant_commands=relevant_commands,\n relevant_snippets=relevant_snippets,\n session_facts=session_facts,\n constraints=constraints,\n include_code_bundle=include_code_bundle,\n include_tests=include_tests,\n)\n```\n\n资料来源：[mcp/server/aidocs_mcp/runtime_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n### State Tracking\n\nThe runtime service maintains:\n\n- **Session State** - Current session identifier and metadata\n- **Task State** - Active tasks, goals, and blockers\n- **Relevant Files** - Files relevant to current task\n- **Relevant Commands** - Commands needed for task completion\n- **Relevant Snippets** - Code snippets for reference\n- **Session Facts** - Accumulated knowledge about the session\n\n### Summary-Only Updates\n\nWhen `summary_only=True`, the runtime service tracks which fields were updated:\n\n```python\nupdated_fields: list[str] = []\nif state is not None:\n updated_fields.append(\"state\")\nif upcoming is not None:\n updated_fields.append(\"upcoming\")\n# ... additional field tracking\n```\n\n## MCP Registry\n\nThe `mcp_registry.py` module provides registry functionality for MCP server discovery and management.\n\n### Registry Capabilities\n\n- **Server Discovery** - Find available MCP servers in the system\n- **Transport Detection** - Identify server transport protocols (stdio, SSE, etc.)\n- **Command Extraction** - Parse install commands for server setup\n- **Server Management** - Track installed and available servers\n\n### Registry UI Components\n\nThe dashboard displays registered servers with:\n\n```tsx\n{srv.name} · {srv.transport} · {srv.command}\n```\n\nSearch results show installation commands and website URLs for discovered servers.\n\n资料来源：[mcp/server/aidocs_mcp/mcp_registry.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_registry.py)\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n## Host Integrations\n\nThe MCP server supports multiple AI coding assistant hosts through platform-specific integrations.\n\n### Claude Code Integration\n\nThe Claude hook (`claude_hook.py`) provides:\n- Prompt injection with action directives\n- Interaction text rendering\n- Workflow summary compilation\n- Tool preamble generation\n\n```python\n_ACTION_DIRECTIVES = {\n \"write_code\": '`ai_create_file` → `ai_get_lines` (read) → `ai_edit_lines` or `ai_batch_edit` (write) → `task_complete`',\n \"trace\": '`ai_find(query, mode=\"references\")` → `ai_trace(query, mode=\"field_flow\"|\"css_class\"|\"api_to_ui\")`',\n \"understand\": '`session_resume_bundle` → `action_surface_current_session_bundle` → `ai_find(query, mode=\"symbols\")` → `ai_get_symbol_snippet`',\n}\n```\n\n### OpenCode Integration\n\nThe OpenCode plugin (`opencode_plugin.js`) provides:\n- Startup state detection\n- Project initialization checks\n- Execution prompt building\n- Interaction text handling\n\n资料来源：[mcp/server/aidocs_mcp/claude_hook.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/claude_hook.py)\n资料来源：[mcp/server/aidocs_mcp/data/opencode_plugin.js](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/data/opencode_plugin.js)\n\n## Memory Model\n\nThe MCP server maintains a hierarchical memory structure within project directories:\n\n```\n/.MEMORY/\n .aidocs/index.aidocs # Session-start router\n sessions/ # Session-specific state\n skills/ # Skill definitions\n plans/ # Task plans\n```\n\n### Memory Path Gate Rules\n\n| Path Type | Read Access | Write Access |\n|-----------|-------------|--------------|\n| `.MEMORY/` | Free (Level 4) | Intent-gated |\n| `aidocs.toml` | Free | Blocked (Level 2) |\n| `aidocs_mcp/*` | Free | Blocked (Level 2) |\n| Project Files | Discovery required | Prior read required |\n\n## Edit Tool Sequencing\n\nSequential line-based edits to the same file can corrupt line numbers. The MCP server enforces:\n\n1. **Single-file line edits** trigger a rejection if the file was already edited this turn\n2. **Batch alternatives** (`ai_batch_edit`, `ai_str_replace`, `ai_batch_str_replace`) handle ordering internally\n3. **Line-independent matching** bypasses the sequential edit check\n\n```python\ndef _check_turn_edited(project_root, path, tool_name):\n \"\"\"Return rejection if file already edited this turn\"\"\"\n managed = hub.managed_mode.get_mode(project_root)\n if not managed.get(\"active\"):\n return None\n # Check session_id and file edit history\n```\n\n资料来源：[mcp/server/aidocs_mcp/server_code_edit_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_edit_tools.py)\n\n## Installation and Setup\n\n### Package Installation\n\n```bash\npip install aidocs-mcp # from PyPI\npip install aidocs-mcp[dev] # with pytest\npip install aidocs-mcp[ast] # with tree-sitter for JS/TS AST parsing\n```\n\n### Setup Command\n\n```bash\naidocs setup # Configures MCP, hooks, project init\naidocs doctor # Verify the install\n```\n\n### Setup Wizard\n\nThe dashboard includes a setup wizard (`SetupWizardPage.tsx`) that guides users through:\n\n1. **Welcome** - Introduction to AIDOCS capabilities\n2. **Project Selection** - Choose project folder\n3. **Configuring** - MCP, hooks, and project structure setup\n4. **Done** - Confirmation with checklist\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n资料来源：[README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n\n## Dashboard Status Indicators\n\nThe CastleShell UI component displays MCP connection status:\n\n```tsx\n\n \n {mcpConnected ? \"MCP connected\" : \"MCP disconnected\"}\n\n```\n\n### Status Bar Components\n\n| Component | Purpose |\n|-----------|---------|\n| `mcpConnected` | Boolean indicating MCP server connection |\n| `projectName` | Current project identifier |\n| `sessionId` | Active session identifier |\n| `activeLayer` | Current execution layer |\n| `saveState` | Persistence state indicator |\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n\n---\n\n\n\n## Dashboard Architecture\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Conductor & Orchestration](#conductor-orchestration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n- [apps/aidocs-dashboard/index.html](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/index.html)\n- [apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n- [apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n- [apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n- [apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)\n- [apps/aidocs-dashboard/src/dashboardCharts.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardCharts.tsx)\n- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n- [apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n- [mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n- [README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n- [README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n- [mcp/server/aidocs_mcp/config_schema.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_schema.py)\n
\n\n# Dashboard Architecture\n\nThe AIDOCS Dashboard is a Tauri-based desktop application that provides a comprehensive user interface for monitoring, managing, and configuring the AIDOCS AI coding assistant infrastructure. It serves as the central control plane for all AIDOCS operations, from initial project setup to ongoing session monitoring and security configuration.\n\n## Overview\n\nThe dashboard functions as a bridge between the user and the underlying MCP (Model Context Protocol) server infrastructure. It enables users to visualize project state, manage AI backends, configure security policies, and monitor token usage across sessions. The architecture follows a clean separation between the Rust-based Tauri backend and the React/TypeScript frontend, providing native desktop performance while maintaining rapid development iteration cycles.\n\nThe dashboard is designed to work in conjunction with the `aidocs-mcp` Python package, which runs as a separate MCP server process. The dashboard communicates with this server via IPC commands to retrieve runtime state and push configuration changes. This decoupled design allows the MCP server to operate independently of the dashboard GUI, enabling headless operation in CI/CD environments or remote servers.\n\n## Technology Stack\n\n### Frontend Layer\n\nThe frontend is built with React 18 and TypeScript, providing type-safe component development and modern hooks-based state management. Vite serves as the build tool and development server, offering fast hot module replacement during development and optimized production builds.\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| UI Framework | React 18 | Component rendering and state management |\n| Language | TypeScript | Type safety and IDE support |\n| Build Tool | Vite | Fast builds and HMR |\n| Styling | CSS Variables + Tailwind | Custom theming with Castle design system |\n| Charts | Custom implementation | Token usage visualization |\n\n资料来源：[apps/aidocs-dashboard/index.html:1-10]()\n\n### Backend Layer\n\nThe Tauri backend is implemented in Rust, providing native system integration capabilities including window management, file system access, and process spawning. The backend exposes a command API that the React frontend invokes via Tauri's invoke mechanism.\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| Runtime | Tauri 2.x | Desktop app framework |\n| Language | Rust | Backend command implementation |\n| IPC | Tauri Commands | Frontend-backend communication |\n| Window | WebView2/WebKit | Render React frontend |\n\n资料来源：[README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n\n## Architecture Components\n\n### Component Hierarchy\n\n```mermaid\ngraph TD\n A[Tauri Backend
main.rs] --> B[React App
App.tsx]\n B --> C[CastleShell
Navigation Framework]\n C --> D[OverviewPage
Project Overview]\n C --> E[RegistryPage
MCP Server Registry]\n C --> F[ConductorPage
Backend Routing]\n C --> G[RBACPage
Access Control]\n C --> H[TomlConfigsPage
TOML Editor]\n C --> I[UsagePage
Token Analytics]\n C --> J[SetupWizardPage
Initial Setup]\n C --> K[dashboardModals
Confirmation Dialogs]\n \n L[StatusBar
MCP Status] -.-> C\n M[ContextRail
Sidebar Info] -.-> C\n N[CommandPalette] -.-> C\n```\n\n### CastleShell Navigation Framework\n\nThe `CastleShell` component serves as the primary layout container, providing consistent navigation, status indication, and context management across all dashboard pages. It implements a tab-based navigation system with optional managed mode indicators.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n\n#### Navigation Types\n\n```typescript\ntype NavKey = \"overview\" | \"registry\" | \"conductor\" | \"rbac\" | \n \"configs\" | \"usage\" | \"wizard\";\n```\n\n#### Shell Props Interface\n\n| Prop | Type | Required | Description |\n|------|------|----------|-------------|\n| `active` | `NavKey` | Yes | Currently selected navigation tab |\n| `onSelect` | `(key: NavKey) => void` | Yes | Callback when navigation changes |\n| `counts` | `CastleNavCounts` | No | Badge counts for each section |\n| `managedMode` | `boolean` | No | Visual indicator for managed mode state |\n| `version` | `string` | No | AIDOCS version display |\n| `mcpConnected` | `boolean` | Yes | MCP server connection status |\n| `activeLayer` | `string` | No | Current active layer indicator |\n| `saveState` | `string` | No | Auto-save state indicator |\n| `contextRail` | `ReactNode` | No | Optional sidebar content |\n\n### Status Bar\n\nThe status bar component provides real-time connection status and contextual information at the bottom of the application window. It displays MCP connection state with visual indicators and supports tooltip-based detailed status views.\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx:32-54]()\n\n```typescript\ntype CastleStatusBarProps = {\n mcpConnected: boolean;\n projectName?: string;\n sessionId?: string;\n activeLayer?: string;\n saveState?: string;\n};\n```\n\n## Dashboard Pages\n\n### Overview Page\n\nThe Overview page provides a snapshot of the current project state, including recent execution events, active sessions, and capability utilization. It renders a runtime snapshot retrieved from the MCP server via the dashboard API.\n\n资料来源：[apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)\n\n```mermaid\ngraph LR\n A[MCP Server] -->|Runtime Snapshot| B[OverviewPage]\n B --> C[Project Info Panel]\n B --> D[Recent Execution Table]\n B --> E[Capability Stats]\n```\n\n### Registry Page\n\nThe Registry page enables browsing and searching the MCP server registry. Users can view installed servers, search for available servers by name, and initiate installations directly from the interface.\n\n资料来源：[apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)\n\n#### Registry Search Result Structure\n\n```typescript\ninterface RegistrySearchResult {\n name: string;\n install_commands?: Array<{\n command?: string;\n type?: string;\n }>;\n website_url?: string;\n}\n```\n\n### Conductor Page\n\nThe Conductor page manages backend routing configuration, allowing users to select between different AI backends (Claude, Codex, OpenCode) and configure per-backend model settings. It provides a visual representation of the routing lanes and their blocked/run states.\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n\n#### Conductor Configuration Model\n\n```typescript\ninterface ConductorConfig {\n backend: \"claude\" | \"codex\" | \"opencode\";\n models: {\n claude: string;\n codex: string;\n opencode: string;\n };\n lanes: ConductorLane[];\n}\n```\n\n### RBAC Page\n\nThe Role-Based Access Control page displays and manages permission grants, showing which sessions and tasks have been granted specific capabilities. It supports both sticky (persistent) and once (single-use) grant types with expiration tracking.\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n#### RBAC Entry Display\n\n| Field | Description |\n|-------|-------------|\n| `session_id` | Session identifier with optional task ID |\n| `sticky` | Sticky grants persist across sessions |\n| `created_at` | Grant creation timestamp |\n| `expires_at` | Optional expiration timestamp |\n\n### TOML Configuration Page\n\nThe TOML Configuration page provides a visual editor for AIDOCS TOML documents, organized by category. Users can view and manage configuration entries for Action Tokens, Action Hooks, and Language Descriptors.\n\n资料来源：[apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)\n\n#### Configuration Categories\n\n| Category | Purpose |\n|----------|---------|\n| `intent_tokens` | Action token definitions for prompt classification |\n| `gate_messages` | Action hook message templates |\n| `language_descriptors` | Language-specific behavior descriptors |\n\n### Usage Page\n\nThe Usage page visualizes token consumption across sessions, providing charts for input/output token ratios, session breakdowns, and tool-specific usage. It supports both bar and pie chart modes for different visualization preferences.\n\n资料来源：[apps/aidocs-dashboard/src/dashboardCharts.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardCharts.tsx)\n\n#### Usage Data Model\n\n```typescript\ninterface TokenEstimates {\n tokens_in: number;\n tokens_out: number;\n tokens_in_calls?: number;\n tokens_out_calls?: number;\n}\n\ninterface SessionBreakdown {\n session_id: string;\n total: number;\n events: number;\n}\n```\n\n### Setup Wizard\n\nThe Setup Wizard guides users through initial AIDOCS configuration with a multi-step flow. It handles project path selection, environment detection, and host authentication verification.\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n\n#### Wizard Steps\n\n```mermaid\ngraph LR\n A[welcome] --> B[project]\n B --> C[environment]\n C --> D[configure]\n D --> E[done]\n \n A -->|Get Started| B\n B -->|Configure| D\n E -->|Open Dashboard| F[Dashboard]\n```\n\n#### Setup Step Configuration\n\n| Step | Purpose |\n|------|---------|\n| `welcome` | Introduction and value proposition |\n| `project` | Project folder selection |\n| `environment` | Runtime detection (Node.js, CLI agents) |\n| `configure` | MCP, hooks, and project structure setup |\n| `done` | Confirmation and next steps |\n\n#### Environment Detection\n\nThe wizard detects available AI hosts and their authentication status:\n\n```typescript\ninterface HostDetection {\n name: string;\n found: boolean;\n authenticated: boolean;\n path?: string;\n installable?: boolean;\n}\n```\n\nSupported hosts include Claude and OpenAI platforms, with sign-in buttons linking to respective authentication pages.\n\n### Modal Components\n\nSecurity-sensitive operations require explicit user confirmation through modal dialogs. The dashboard provides dedicated confirmation modals for dangerous configuration changes.\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n#### Protected Settings\n\n| Setting | Risk Description |\n|---------|------------------|\n| `dev.dev_mode` | Enables editing AIDOCS MCP server source files |\n| `security.allow_config_edit` | Allows agents to modify AIDOCS config via tool calls |\n| `security.enforce` | Disabling removes tool gates and destructive command protection |\n\n#### Loading Overlay\n\nThe `LoadingOverlay` component displays during snapshot refresh operations:\n\n```typescript\nexport function LoadingOverlay() {\n return (\n
\n
\n
\n Loading runtime snapshot\n Refreshing project, session, and settings state.\n
\n
\n );\n}\n```\n\n## MCP Integration\n\nThe dashboard communicates with the AIDOCS MCP server through Tauri's IPC mechanism. The MCP server exposes tools for project management, session control, memory operations, and code analysis.\n\n### Core MCP Tools\n\n| Category | Tools |\n|----------|-------|\n| **Session** | `ai_session` (list, create, connect, update, release, resume) |\n| **Memory** | `memory_read`, `memory_capture`, `memory_search` |\n| **Project** | `project_init`, `project_bootstrap_or_resume`, `project_sync_indexes` |\n| **Code** | `ai_find`, `ai_get_lines`, `ai_edit_lines`, `ai_batch_edit` |\n| **Analysis** | `ai_trace`, `ai_bundle`, `schema_query` |\n\n资料来源：[mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)\n\n### Configuration Schema\n\nThe MCP server maintains configuration entries with support for various scopes and security classifications:\n\n资料来源：[mcp/server/aidocs_mcp/config_schema.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_schema.py)\n\n#### Security-Sensitive Settings\n\n```python\n\"dev.dev_mode\": _setting(\n type=\"boolean\",\n default=False,\n description=\"[T0 DASHBOARD-ONLY] Unlocks AIDOCS infrastructure source editing.\",\n security_sensitive=True,\n dashboard_only=True,\n scope=[\"project\"],\n)\n```\n\n#### Tool Output Configuration\n\n| Setting | Default | Purpose |\n|---------|---------|---------|\n| `tool_output.pretty` | `false` | Dual-channel pretty rendering |\n| `tool_output.show_tool_name` | `false` | Inline debug markers |\n| `tool_output.show_duration` | `false` | Per-call duration display |\n| `tool_output.show_tokens` | `false` | Token count estimation |\n\n## Build and Deployment\n\n### Development Mode\n\n```bash\ncd apps/aidocs-dashboard\nnpm install\nnpm run tauri dev\n```\n\n### Production Build\n\n```bash\nnpm run tauri build\n```\n\nThe build process compiles the Rust backend and bundles the React frontend into a native executable.\n\n### Launch Scripts\n\n| Platform | Script |\n|----------|--------|\n| Windows | `core\\scripts\\launch-dashboard.cmd` |\n| Linux/macOS | `bash core/scripts/launch-dashboard.sh` |\n\n资料来源：[README_INSTALL.md](https://github.com/cristian1991/AIDOCS/blob/main/README_INSTALL.md)\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard as React UI\n participant Tauri as Tauri Backend\n participant MCP as MCP Server\n participant Project as Project Files\n \n User->>Dashboard: Navigate to page\n Dashboard->>Tauri: invoke(\"command\", args)\n Tauri->>MCP: IPC / Tool Calls\n MCP->>Project: File System Operations\n Project-->>MCP: State / Config\n MCP-->>Tauri: Response\n Tauri-->>Dashboard: Serialized Data\n Dashboard-->>User: Rendered UI\n```\n\n## Security Architecture\n\nThe dashboard implements several security measures:\n\n1. **T0 Dashboard-Only Settings**: Certain configuration changes are restricted to the dashboard and cannot be modified by agents through NLP or tool calls.\n\n2. **Confirmation Modals**: Security-sensitive operations require explicit user confirmation before execution.\n\n3. **Output Guard**: The MCP server includes output filtering to detect and redact sensitive content patterns.\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n\n#### Sensitive Content Patterns\n\n| Pattern | Detection |\n|---------|-----------|\n| `env_file_content` | Environment variables with 8+ character values |\n| `ssh_config` | SSH host configurations and identity files |\n\n## Design System\n\nThe dashboard uses the \"Castle\" design system with a dark theme and muted accent colors:\n\n| Token | Value | Usage |\n|-------|-------|-------|\n| `--castle-line` | Border color | Panel separators |\n| `--castle-mute` | Muted text | Secondary labels |\n| `--castle-allow` | Green | Success states |\n| `--castle-deny` | Red | Error states |\n\nThe design system is implemented via CSS custom properties, enabling consistent theming across all components.\n\n---\n\n\n\n## Memory System\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Indexing & Retrieval System](#indexing-retrieval)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/.MEMORY/.aidocs/memory-system.aidocs](https://github.com/cristian1991/AIDOCS/blob/main/core/.MEMORY/.aidocs/memory-system.aidocs)\n- [mcp/server/aidocs_mcp/memory_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/memory_store.py)\n- [mcp/server/aidocs_mcp/session_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/session_store.py)\n- [mcp/server/aidocs_mcp/memory_discovery.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/memory_discovery.py)\n- [mcp/server/aidocs_mcp/aidocs_nlp/consumers/memory_surfacer.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/aidocs_nlp/consumers/memory_surfacer.py)\n- [mcp/server/aidocs_mcp/runtime_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n
\n\n# Memory System\n\n## Overview\n\nThe AIDOCS Memory System provides persistent memory infrastructure for AI coding agents, enabling them to resume work across sessions without rediscovering repositories from scratch. The system organizes agent-generated knowledge into structured directories, validates memory file placement, detects stale content, and surfaces relevant memories during task execution.\n\nMemory is stored in a `.MEMORY` directory at the project root, containing structured subdirectories for sessions, archived work, rules, standards, lessons, and roadmaps.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Memory Storage Layer\"\n MEM[.MEMORY/]\n SESS[.MEMORY/sessions/]\n ARCH[.MEMORY/archive/]\n RULES[.MEMORY/rules/]\n STD[.MEMORY/standards/]\n LESS[.MEMORY/lessons/]\n ROAD[.MEMORY/roadmaps/]\n end\n \n subgraph \"MCP Tools\"\n MS[memory_store.py]\n SS[session_store.py]\n MD[memory_discovery.py]\n MF[memory_surfacer.py]\n end\n \n subgraph \"Validation & Scanning\"\n RS[runtime_service.py
memory_validator]\n SF[stale_finder]\n GP[pattern_scanner]\n end\n \n MEM --> SESS\n MEM --> ARCH\n MEM --> RULES\n MEM --> STD\n MEM --> LESS\n MEM --> ROAD\n \n SESS --> MS\n ARCH --> SS\n MS --> MD\n MD --> MF\n RS --> GP\n```\n\n## Directory Structure\n\nThe Memory System enforces a specific directory structure to maintain organized, retrievable knowledge:\n\n| Directory | Purpose |\n|-----------|---------|\n| `.MEMORY/sessions//` | Active session files |\n| `.MEMORY/archive/sessions//` | Archived session data |\n| `.MEMORY/rules/` | Coding rules and guidelines |\n| `.MEMORY/standards/` | Project standards documentation |\n| `.MEMORY/lessons/` | Learned lessons and post-mortems |\n| `.MEMORY/roadmaps/` | Future plans and milestones |\n\n资料来源：[runtime_service.py:24-28](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Memory File Naming Rules\n\nThe system enforces strict placement rules for memory files. These rules ensure consistent organization and enable reliable retrieval.\n\n### File Location Rules\n\n| File Name | Valid Location | Path Segments |\n|-----------|---------------|---------------|\n| `SESSION.md` | `.MEMORY/sessions//` | 3 segments |\n| `CONTEXT.md` | `.MEMORY/sessions//` | 3 segments |\n| `TODO.md` | `.MEMORY/sessions//` | 3 segments |\n| `NOTES.md` | `.MEMORY/sessions//` | 3 segments |\n| `PLAN.md` | `.MEMORY/sessions//plans/` | 4 segments |\n\n资料来源：[runtime_service.py:47-67](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n### Validation Logic\n\n```python\n# For session files (SESSION.md, CONTEXT.md, TODO.md, NOTES.md)\nok = (\n (len(parts) == 3 and parts[0] == \"sessions\")\n or (len(parts) == 4 and parts[:2] == (\"archive\", \"sessions\"))\n)\n\n# For PLAN.md\nok = (\n (len(parts) == 4 and parts[0] == \"sessions\" and parts[2] == \"plans\")\n or (len(parts) == 5 and parts[:2] == (\"archive\", \"sessions\") and parts[3] == \"plans\")\n)\n```\n\n资料来源：[runtime_service.py:58-67](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Header Pattern Detection\n\nThe system scans memory files for header patterns that indicate the type of content and its organization. These patterns help categorize and prioritize memory retrieval.\n\n### G2 Patterns (Work-in-Progress Headers)\n\nFiles with these header patterns indicate ongoing investigation or active work:\n\n| Pattern | Keywords |\n|---------|----------|\n| `re.IGNORECASE` | `investigating`, `reading`, `trying`, `exploring`, `debugging`, `checking`, `figuring`, `attempting`, `wip`, `todo:`, `notes:` |\n\n```python\ng2_pattern = re.compile(\n r\"^#+\\s+(investigating|reading|trying|exploring|debugging|\"\n r\"checking|figuring|attempting|wip|todo:|notes?:)\\b\",\n re.IGNORECASE,\n)\n```\n\n### G3 Patterns (Planning Headers)\n\nFiles with these headers indicate structured planning or backlog items:\n\n| Pattern | Keywords |\n|---------|----------|\n| `re.IGNORECASE` | `plan`, `phase`, `step`, `tasks`, `backlog`, `roadmap`, `milestone` |\n\n```python\ng3_pattern = re.compile(\n r\"^#+\\s+(plan|phase\\s*\\d|step\\s*\\d|steps|tasks|backlog|\"\n r\"roadmap|milestone)\\b\",\n re.IGNORECASE,\n)\n```\n\n### Skipped Directories\n\nCertain directories are excluded from pattern validation as they are expected to contain these patterns:\n\n| Pattern Type | Skipped Directories |\n|--------------|---------------------|\n| G2 | `sessions`, `archive`, `.aidocs`, `.index` |\n| G3 | `sessions`, `archive`, `.aidocs`, `.index`, `roadmaps` |\n\n资料来源：[runtime_service.py:29-35](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Memory Validation API\n\n### `memory_structure_checker`\n\nValidates the entire memory directory structure for compliance with naming and placement rules.\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `project_root` | `Path` | — | Project root path |\n| `memory_root` | `str` | `\".MEMORY\"` | Memory directory name |\n\n**Returns:**\n\n```python\n{\n \"ok\": bool,\n \"memory_root\": str,\n \"violations\": [\n {\n \"path\": str,\n \"name\": str,\n \"expected_location\": str\n }\n ],\n \"count\": int,\n \"error\": Optional[str]\n}\n```\n\n**Error States:**\n\n| Error Code | Description |\n|------------|-------------|\n| `memory_root_not_found` | The `.MEMORY` directory does not exist in the project |\n\n资料来源：[runtime_service.py:12-21](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Stale Memory Detection\n\n### `memory_stale_finder`\n\nIdentifies memory files that have not been modified in a configurable time period. This helps maintain memory freshness and prevents outdated information from being surfaced.\n\n**Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `project_root` | `Path` | — | Project root path |\n| `stale_after_days` | `int` | `90` | Days after which memory is considered stale |\n| `memory_root` | `str` | `\".MEMORY\"` | Memory directory name |\n\n**Rationale:**\n\n> \"Memory drifts: rules written months ago for a now-dead workflow are worse than no rules at all.\"\n\n资料来源：[runtime_service.py:106-108](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_service.py)\n\n## Memory Surfacing\n\nThe `memory_surfacer` module provides retrieval capabilities for surfacing relevant memories based on context. It consumes NLP-processed data to match current task context with stored memories.\n\n### Key Responsibilities\n\n- Match query context against stored memory content\n- Rank memories by relevance\n- Filter memories by type, age, and source\n- Handle deduplication across sessions\n\n```python\n# Conceptual flow\nuser_query → context_extraction → memory_search → relevance_ranking → filtered_results\n```\n\n资料来源：[memory_surfacer.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/aidocs_nlp/consumers/memory_surfacer.py)\n\n## Memory Discovery\n\nThe discovery module (`memory_discovery.py`) provides mechanisms to locate and index memory files across the project.\n\n### Discovery Capabilities\n\n- Recursive traversal of `.MEMORY` directory tree\n- Filtering by memory type (sessions, rules, standards, lessons)\n- Metadata extraction from memory file headers\n- Cross-reference identification between memories\n\n## Session Store\n\nSession storage maintains the state of agent sessions across the memory hierarchy.\n\n### Session File Types\n\n| File | Purpose | Location |\n|------|---------|----------|\n| `SESSION.md` | Session metadata and context | `.MEMORY/sessions//` |\n| `CONTEXT.md` | Current working context | `.MEMORY/sessions//` |\n| `TODO.md` | Task backlog | `.MEMORY/sessions//` |\n| `NOTES.md` | Session observations | `.MEMORY/sessions//` |\n| `PLAN.md` | Session plan | `.MEMORY/sessions//plans/` |\n\n资料来源：[session_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/session_store.py)\n\n## Security Considerations\n\nThe Memory System integrates with the security guard infrastructure to protect against prompt injection and sensitive data leakage.\n\n### Pattern Scanning Integration\n\nMemory files are scanned for:\n\n- **Prompt injection patterns** (role hijack, instruction injection, delimiter escape)\n- **Sensitive content** (env file patterns, SSH config)\n- **Capability declarations** (file operations, command execution, database access)\n\nSee [Security Gates](Security-Gates) for detailed pattern definitions.\n\n## Workflow\n\n```mermaid\ngraph LR\n A[Agent Session Start] --> B[Create/Load Session]\n B --> C[Memory Discovery]\n C --> D[Relevant Memories Surfaced]\n D --> E[Agent Work]\n E --> F[Update Memory Files]\n F --> G[Structure Validation]\n G --> H[Archive or Keep Active]\n H --> I[Session End]\n```\n\n## Configuration\n\n### Memory Root Location\n\nDefault: `.MEMORY` (relative to project root)\n\n### Validation Strictness\n\nThe system performs validation on:\n- File naming conventions\n- Directory placement\n- Path segment counts\n- Header pattern compliance\n\n### Staleness Threshold\n\nDefault: 90 days\nConfigurable via `stale_after_days` parameter\n\n## Related Components\n\n| Component | Relationship |\n|-----------|--------------|\n| [MCP Runtime](MCP-Runtime) | Provides tools for memory operations |\n| [Security Gates](Security-Gates) | Scans memory content for risks |\n| [Conductor](Conductor) | Uses memory for task orchestration |\n| [Dashboard](Dashboard) | Visualizes memory state and health |\n\n---\n\n\n\n## Conductor & Orchestration\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server), [Security & Access Control](#security-gates), [Dashboard Architecture](#dashboard)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/conductor_comms.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/conductor_comms.py)\n- [mcp/server/aidocs_mcp/runtime_orchestration_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_orchestration_service.py)\n- [mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py)\n- [mcp/server/aidocs_mcp/plan_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/plan_conductor.py)\n- [mcp/server/aidocs_mcp/co_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/co_conductor.py)\n- [mcp/server/aidocs_mcp/agent_orchestrator.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/agent_orchestrator.py)\n- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n- [apps/aidocs-dashboard/src-tauri/src/main.rs](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src-tauri/src/main.rs)\n
\n\n# Conductor & Orchestration\n\nThe Conductor & Orchestration system is the central coordination layer in AIDOCS, providing persistent, long-lived agent orchestration across coding sessions. Rather than spawning isolated one-off agent calls, the Conductor acts as a supervisory intelligence that plans, delegates, monitors, and resolves conflicts among multiple lane-based worker agents.\n\n## Overview\n\nThe Conductor orchestrates AI coding work by:\n\n- Maintaining persistent memory across sessions\n- Creating and managing execution **lanes** (isolated task pipelines)\n- Routing tasks to appropriate backend models (Claude, Codex, OpenCode)\n- Resolving inter-lane conflicts and blocking conditions\n- Providing a real-time chat interface for human-in-the-loop oversight\n\n资料来源：[README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n\n## Architecture\n\nThe orchestration system is composed of multiple layers:\n\n```mermaid\ngraph TD\n subgraph \"Frontend (Dashboard)\"\n CP[ConductorPage]\n CH[ConductorChat]\n LP[Lanes Panel]\n TCP[ToolCallsPanel]\n end\n \n subgraph \"Backend (Rust/Tauri)\"\n MS[Main State]\n CS[ConductorState]\n end\n \n subgraph \"MCP Server (Python)\"\n ROS[RuntimeOrchestrationService]\n RCDS[RuntimeConductorDispatchService]\n PC[PlanConductor]\n CC[CoConductor]\n AC[AgentOrchestrator]\n CCM[ConductorComms]\n end\n \n CP -->|Tauri Commands| MS\n CH -->|conductor_start/send| CS\n CS -->|MCP Tools| ROS\n ROS --> RCDS\n RCDS --> PC\n RCDS --> CC\n PC --> AC\n CC --> AC\n AC --> CCM\n```\n\n## Core Components\n\n### PlanConductor\n\nThe `PlanConductor` is responsible for high-level task planning. It receives goals and breaks them into discrete execution lanes, establishing dependencies and ordering constraints.\n\n**Key Responsibilities:**\n\n- Parse incoming task descriptions\n- Generate execution plans with lane definitions\n- Set lane blocking conditions\n- Track plan progress through completion\n\n资料来源：[mcp/server/aidocs_mcp/plan_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/plan_conductor.py)\n\n### CoConductor\n\nThe `CoConductor` operates as a parallel supervisory agent that assists the primary conductor. It handles secondary routing decisions and provides fallback reasoning when the main conductor encounters ambiguous situations.\n\n**Key Responsibilities:**\n\n- Parallel task assessment\n- Fallback routing decisions\n- Conflict resolution between lanes\n- Escalation handling\n\n资料来源：[mcp/server/aidocs_mcp/co_conductor.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/co_conductor.py)\n\n### RuntimeOrchestrationService\n\nThe `RuntimeOrchestrationService` serves as the central service entry point for all orchestration operations. It manages session state and dispatches requests to appropriate conductor components.\n\n**Key Responsibilities:**\n\n- Session lifecycle management\n- Service initialization and teardown\n- Request routing to PlanConductor/CoConductor\n- State synchronization with dashboard\n\n资料来源：[mcp/server/aidocs_mcp/runtime_orchestration_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_orchestration_service.py)\n\n### RuntimeConductorDispatchService\n\nThe `RuntimeConductorDispatchService` handles the low-level dispatch of tasks to specific backends. It manages connection pooling, request queuing, and response aggregation.\n\n**Key Responsibilities:**\n\n- Backend selection (claude/codex/opencode)\n- Request dispatch and retry logic\n- Response aggregation\n- Connection state management\n\n资料来源：[mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py)\n\n### AgentOrchestrator\n\nThe `AgentOrchestrator` coordinates the actual execution of tasks within each lane. It manages tool calls, maintains execution context, and handles error recovery.\n\n**Key Responsibilities:**\n\n- Lane-level task execution\n- Tool call management and policy enforcement\n- Execution state persistence\n- Error recovery and retry\n\n资料来源：[mcp/server/aidocs_mcp/agent_orchestrator.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/agent_orchestrator.py)\n\n### ConductorComms\n\nThe `ConductorComms` module handles inter-process and inter-service communication. It provides the messaging substrate for conductor components and the dashboard.\n\n**Key Responsibilities:**\n\n- Message formatting and serialization\n- Transport abstraction\n- Session message routing\n- Event broadcasting\n\n资料来源：[mcp/server/aidocs_mcp/conductor_comms.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/conductor_comms.py)\n\n## State Management (Rust Backend)\n\nThe Tauri backend maintains conductor state across sessions using a global state map.\n\n```mermaid\ngraph TD\n subgraph \"ConductorState\"\n PID[process: Option Child]\n OUT[output: Vec f64, String, String]\n BE[backend: Option String]\n MD[model: Option String]\n PORT[opencode_port: Option u16]\n CSID[claude_session_id: Option String]\n COXSID[codex_session_id: Option String]\n SIF[codex_send_in_flight: bool]\n end\n \n subgraph \"Global State\"\n CONDUCTORS[HashMap ConductorKey ConductorState]\n end\n \n CONDUCTORS -->|key: (root, session_id)| PID\n CONDUCTORS -->|key: (root, session_id)| BE\n```\n\n### ConductorKey Structure\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `root` | `PathBuf` | Project root directory |\n| `session_id` | `String` | Unique session identifier |\n\n### ConductorState Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `process` | `Option` | Active child process handle |\n| `output` | `Vec<(f64, String, String)>` | Execution output with timing |\n| `backend` | `Option` | Current backend (claude/codex/opencode) |\n| `model` | `Option` | Selected model identifier |\n| `opencode_port` | `Option` | OpenCode server port |\n| `claude_session_id` | `Option` | Claude session identifier |\n| `codex_session_id` | `Option` | Codex session identifier |\n| `codex_send_in_flight` | `bool` | Request in-flight flag |\n\n资料来源：[apps/aidocs-dashboard/src-tauri/src/main.rs:1-50](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src-tauri/src/main.rs)\n\n## Lanes System\n\nLanes are the fundamental execution unit in the orchestration system. Each lane represents an isolated task pipeline that can run independently or with dependencies on other lanes.\n\n### Lane States\n\n| State | Description |\n|-------|-------------|\n| `runnable` | Lane can execute immediately |\n| `blocked` | Lane waiting on dependencies or conditions |\n| `running` | Lane actively executing |\n| `completed` | Lane finished successfully |\n| `failed` | Lane encountered an error |\n\n### Blocking Reasons\n\nLanes can be blocked by:\n\n- Unmet dependency lanes\n- Resource constraints\n- Security policy gates\n- External input waiting\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n\n## Dashboard Integration\n\n### ConductorPage\n\nThe `ConductorPage` component provides the main dashboard interface for conductor operations.\n\n```typescript\ninterface ConductorPageProps {\n progressPercent: number;\n conductorLanes: Lane[];\n runnableLaneIds: string[];\n blockedReasons: Record;\n recentExecution: ExecutionEvent[];\n configEntries: ConfigEntry[];\n selectedSessionId: string;\n projectRoot: string;\n sessionId: string;\n}\n```\n\n**Components:**\n\n| Component | Purpose |\n|-----------|---------|\n| `Lanes Panel` | Visual display of lane states and progress |\n| `ConductorChat` | Real-time chat interface with conductor |\n| `ToolCallsPanel` | View recent tool execution events |\n| `ConductorSummary` | Progress statistics |\n\n### ConductorChat\n\nThe chat interface supports multiple message recipients:\n\n| Recipient | Description |\n|-----------|-------------|\n| `conductor` | Direct to primary conductor |\n| `co-conductor` | Direct to co-conductor assistant |\n| `both` | Broadcast to both conductors |\n\nMessage roles displayed:\n\n| Role | Color | Usage |\n|------|-------|-------|\n| `king` | `#f5c518` | High-priority directive |\n| `conductor` | `var(--accent-bright)` | Standard conductor messages |\n| `co-conductor` | `#78aaff` | Co-conductor responses |\n\n资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)\n\n## Multi-Backend Routing\n\nThe orchestration system supports routing to different AI backends:\n\n### Supported Backends\n\n| Backend | Configuration Key | Model Key |\n|---------|-------------------|-----------|\n| Claude | `conductor.backend` | `conductor.claude_model` |\n| Codex | `conductor.backend` | `conductor.codex_model` |\n| OpenCode | `conductor.backend` | N/A (uses port) |\n\n### Routing Configuration\n\n```typescript\ninterface RouteConfig {\n backend: \"claude\" | \"codex\" | \"opencode\";\n models: {\n claude: string;\n codex: string;\n opencode: string;\n };\n}\n```\n\n### Backend Selection Logic\n\n1. Check `conductor.backend` config for default\n2. Evaluate task requirements\n3. Consider model capabilities\n4. Apply routing policies\n\n## Execution Events\n\nExecution events track all conductor activity:\n\n### Event Structure\n\n```typescript\ninterface ExecutionEvent {\n event_id: string;\n event_kind: string;\n capability_name?: string;\n action_kind?: string;\n session_id: string;\n observed_at: string;\n lane?: string;\n audit?: {\n logicalMode?: string;\n nativeMode?: string;\n fallbackUsed?: boolean;\n };\n payload?: {\n args_preview?: string;\n result_preview?: string;\n result_summary?: string;\n };\n}\n```\n\n### Audit Trail\n\n| Mode | Description |\n|------|-------------|\n| `logicalMode` | Logical routing layer used |\n| `nativeMode` | Native tool selection |\n| `fallbackUsed` | Whether fallback was triggered |\n\n资料来源：[apps/aidocs-dashboard/src/ExecutionPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ExecutionPage.tsx)\n\n## Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard\n participant Conductor\n participant PlanConductor\n participant CoConductor\n participant AgentOrchestrator\n participant Backend\n\n User->>Dashboard: Send message/goal\n Dashboard->>Conductor: route_prompt(goal)\n Conductor->>PlanConductor: create_plan(goal)\n PlanConductor-->>Conductor: lanes[], dependencies[]\n Conductor->>CoConductor: validate_plan(lanes)\n CoConductor-->>Conductor: validation_result\n \n loop For each runnable lane\n Conductor->>AgentOrchestrator: execute_lane(lane)\n AgentOrchestrator->>Backend: dispatch(task)\n Backend-->>AgentOrchestrator: result\n AgentOrchestrator-->>Conductor: lane_status\n end\n \n Conductor-->>Dashboard: progress_update\n Dashboard->>User: Display results\n```\n\n## Message Flow\n\nMessages flow through the system with role-based routing:\n\n```mermaid\ngraph LR\n subgraph \"Dashboard\"\n CH[ConductorChat]\n end\n \n subgraph \"Backend\"\n CCM[ConductorComms]\n PC[PlanConductor]\n CC[CoConductor]\n end\n \n CH-->|Message| CCM\n CCM-->|Route| PC\n CCM-->|Route| CC\n \n PC-->|Plan| CCM\n CC-->|Response| CCM\n CCM-->|Aggregated| CH\n```\n\n## Configuration\n\n### Conductor Settings\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `conductor.backend` | string | `claude` | Default execution backend |\n| `conductor.claude_model` | string | - | Claude model identifier |\n| `conductor.codex_model` | string | - | Codex model identifier |\n\n### Lane Configuration\n\nLanes are configured via the plan conductor with:\n\n- **Dependencies**: Ordered constraint list\n- **Blocking conditions**: Runtime predicates\n- **Resource requirements**: CPU, memory, tool access\n- **Timeout settings**: Per-lane execution limits\n\n## Best Practices\n\n### Session Management\n\n1. **Use persistent sessions** - Resume work instead of restarting\n2. **Monitor lane states** - Watch for blocking conditions\n3. **Review execution events** - Track capability usage\n\n### Error Handling\n\n1. **Check blocked reasons** - First step in debugging stuck lanes\n2. **Review fallback usage** - Indicates routing issues\n3. **Examine audit trails** - Understand routing decisions\n\n### Security\n\n- Security gates apply to all conductor operations\n- Lane isolation prevents cross-task contamination\n- RBAC controls conductor access\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n---\n\n\n\n## Security & Access Control\n\n### 相关页面\n\n相关主题：[MCP Server Architecture](#mcp-server), [Conductor & Orchestration](#conductor-orchestration), [Configuration Management](#configuration)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/access_gate.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/access_gate.py)\n- [mcp/server/aidocs_mcp/heuristic_judge.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/heuristic_judge.py)\n- [mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n- [mcp/server/aidocs_mcp/rbac.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/rbac.py)\n- [mcp/server/aidocs_mcp/enforcement_pkg/controller.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/enforcement_pkg/controller.py)\n- [mcp/server/aidocs_mcp/tool_policy.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_policy.py)\n- [mcp/server/aidocs_mcp/permission_catalog.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/permission_catalog.py)\n
\n\n# Security & Access Control\n\nAIDOCS implements a layered security architecture designed to govern AI agent behavior within development environments. The system provides fine-grained control over tool usage, bash command execution, prompt integrity, and permission escalation through multiple enforcement mechanisms working in concert.\n\n## Overview\n\nThe Security & Access Control subsystem in AIDOCS operates as a multi-stage guard system that intercepts and evaluates agent requests before they reach system resources. It combines heuristic analysis, role-based access control (RBAC), tool policy enforcement, and output sanitization to create a defense-in-depth approach for AI-assisted development.\n\n### Core Security Components\n\n| Component | File | Primary Responsibility |\n|-----------|------|------------------------|\n| Access Gate | `access_gate.py` | Central entry point for permission checks |\n| Heuristic Judge | `heuristic_judge.py` | Risk scoring based on request patterns |\n| Output Guard | `output_guard.py` | Content filtering and redaction |\n| RBAC Engine | `rbac.py` | Role and permission management |\n| Enforcement Controller | `controller.py` | Orchestrates policy enforcement |\n| Tool Policy | `tool_policy.py` | Bash command allowlist/denylist |\n| Permission Catalog | `permission_catalog.py` | Defines available permissions |\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Agent Request] --> B[Access Gate]\n B --> C{Security Enabled?}\n C -->|No| Z[Allow]\n C -->|Yes| D[Heuristic Judge]\n D --> E{Risk Score}\n E -->|Low| F[RBAC Check]\n E -->|Medium| G[Gate Permission Required]\n E -->|High| H[Block]\n F --> I{Has Permission?}\n I -->|Yes| J[Tool Policy Check]\n I -->|No| H\n J --> K{Command Allowed?}\n K -->|Yes| L[Execute]\n K -->|No| H\n G --> M[Request Approval]\n M -->|Approved| L\n M -->|Denied| H\n L --> N[Output Guard]\n N --> O[Filtered Response]\n```\n\n## Access Gate\n\nThe Access Gate serves as the central authorization checkpoint for all agent requests. It evaluates incoming requests against the current security posture and determines whether additional verification is needed.\n\n### Configuration Paths\n\nThe system exposes security settings through configurable paths that control different aspects of enforcement:\n\n| Setting Path | Purpose | Risk Level |\n|--------------|---------|------------|\n| `dev.dev_mode` | Enables editing of AIDOCS MCP server source files | High |\n| `security.allow_config_edit` | Allows agents to modify AIDOCS config via tool calls | High |\n| `security.enforce` | Master toggle for tool gates and policy enforcement | Critical |\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n### Security Toggle Behavior\n\nWhen `security.enforce` is disabled, the following protections are removed:\n- Bash allowlist enforcement\n- Raw tool blocking\n- Destructive command protection\n\nAgents gain the ability to use any tool freely when enforcement is disabled. This setting should only be modified with explicit user confirmation through the security change confirmation modal.\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n\n## Heuristic Judge\n\nThe Heuristic Judge performs real-time risk assessment on agent requests by analyzing patterns and content characteristics. It assigns risk scores that determine the level of scrutiny a request receives.\n\n### Risk Categories\n\nThe system categorizes risks into several domains:\n\n| Category | Description | Examples |\n|----------|-------------|----------|\n| `supply_chain` | Package installation and remote code execution | `npm install`, `npx`, `uvx` |\n| `capability` | Declared capabilities indicating system access | File operations, command execution |\n| `vulnerability` | Code patterns that may indicate security issues | `eval()`, `__import__`, `os.system` |\n\n资料来源：[mcp/server/aidocs_mcp/skill_scanner.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/skill_scanner.py)\n\n### Risk Severity Levels\n\n| Severity | Interpretation | Action |\n|----------|----------------|--------|\n| `critical` | Highly dangerous operation | Immediate blocking or strict gate |\n| `high` | Significant risk requiring scrutiny | Gate permission or enhanced monitoring |\n| `medium` | Moderate risk | Standard RBAC check |\n| `low` | Minor concern | Allow with logging |\n\n## Output Guard\n\nThe Output Guard monitors and sanitizes content flowing from agent responses. It detects potential security issues including prompt injection attempts and sensitive data leakage.\n\n### Prompt Injection Detection\n\nThe system recognizes multiple categories of prompt injection patterns:\n\n```python\n_PROMPT_INJECTION_PATTERNS = [\n (\"system_override\", \"ignore/forget previous instructions\"),\n (\"role_hijack\", \"you are now a different AI\"),\n (\"instruction_inject\", \"XML tag instruction injection\"),\n (\"delimiter_escape\", \"code block instruction injection\"),\n (\"hidden_instruction\", \"URGENT: ignore/override\"),\n]\n```\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n\n### Sensitive Content Detection\n\n| Pattern | Description |\n|---------|-------------|\n| `env_file_content` | Environment variables with values 8+ characters |\n| `ssh_config` | SSH configuration content |\n\nThe Output Guard applies redaction markers in the format `[REDACTED:{category}]` when sensitive content is detected and redaction is enabled.\n\n资料来源：[mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)\n\n## Role-Based Access Control (RBAC)\n\nThe RBAC system provides granular permission management for agent capabilities. It defines roles, permissions, and escalation paths that govern what actions agents can perform.\n\n### Permission States\n\nPermissions can exist in three states:\n\n| State | Description |\n|-------|-------------|\n| `system` | Built-in permissions that cannot be modified |\n| `custom` | User-defined permissions for specific use cases |\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n### RBAC Table Structure\n\nThe RBAC page displays permissions in a structured table format:\n\n| Column | Description |\n|--------|-------------|\n| permission name | Unique identifier for the permission |\n| description | Human-readable explanation of the permission |\n| state | Whether the permission is system or custom |\n\n资料来源：[apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)\n\n### Escalation Management\n\nThe RBAC system supports permission escalation with the following attributes:\n\n| Attribute | Description |\n|-----------|-------------|\n| requester | Entity requesting escalation |\n| permission | Target permission being escalated |\n| phrase | Trigger phrase for automatic escalation |\n| session/task | Associated session or task context |\n| sticky | Whether escalation persists beyond current session |\n| created/expires | Temporal bounds for the escalation |\n\n## Tool Policy\n\nTool Policy manages bash command execution through an allowlist/denylist mechanism. It provides fine-grained control over shell commands that agents can execute.\n\n### Policy Structure\n\n```mermaid\ngraph LR\n A[Command] --> B{Policy Check}\n B -->|allow| C[Execute]\n B -->|deny| D[Block]\n B -->|bubble| E[Request Approval]\n B -->|modified| F[Execute with Modification]\n```\n\n### Bash Policy Panel\n\nThe Dashboard provides a visual interface for managing shell policies:\n\n| Count Type | Description |\n|------------|-------------|\n| `allowEff` | Effective allow count |\n| `denyEff` | Effective deny count |\n| `bubbleEff` | Effective bubble (approval required) count |\n| `modifiedAtActive` | Number of rules modified at active layer |\n\n资料来源：[apps/aidocs-dashboard/src/BashPolicyPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/BashPolicyPanel.tsx)\n\n### Policy Layer System\n\nBash policies support layered configuration with the following characteristics:\n- Policies can be defined at different layers\n- Active layer determines which policy configuration is currently in effect\n- Changes made at the active layer are tracked separately\n- Fallback default behavior is configurable\n\n## Enforcement Controller\n\nThe Enforcement Controller orchestrates all security mechanisms and ensures consistent policy application across the system.\n\n### Enforcement Actions\n\n| Action | Trigger | Result |\n|--------|---------|--------|\n| Allow | All checks pass | Execute requested operation |\n| Block | Any check fails | Deny operation, log reason |\n| Bubble | Medium risk detected | Request user approval |\n| Redact | Sensitive content in output | Replace with redaction marker |\n\n### Live Monitoring\n\nThe Live Page in the Dashboard provides real-time visibility into enforcement events:\n\n```mermaid\ngraph TD\n A[Agent Request] --> B[Gate Permission Check]\n B --> C{Permission Status}\n C -->|Required| D[Display in UI]\n C -->|Approved| E[Continue Execution]\n C -->|Rejected| F[Block and Log]\n D --> G{User Action}\n G -->|Approve| E\n G -->|Reject| F\n```\n\nThe gate permission requests appear in the Live Page with:\n- Permission name being requested\n- Requester label\n- Approve/Reject buttons for user response\n\n资料来源：[apps/aidocs-dashboard/src/LivePage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/LivePage.tsx)\n\n## Quick Actions\n\nThe Dashboard provides administrative quick actions for security management:\n\n| Action | Description |\n|--------|-------------|\n| Stop All Lanes | Terminates all active agent sessions |\n| Deactivate AIDOCS | Toggles security posture (not a runtime stop) |\n\n资料来源：[apps/aidocs-dashboard/src/LivePage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/LivePage.tsx)\n\n## Statistics Dashboard\n\nThe Live Page includes a stat tile strip showing real-time security metrics:\n\n| Metric | Description |\n|--------|-------------|\n| Events (last 1h) | Total security events in the past hour |\n| Tool Calls | Number of tool invocation attempts |\n| Blocked | Count of blocked operations |\n| Failed | Count of failed operations |\n| Tokens (in/out) | Token consumption for audit purposes |\n\nBlocked and Failed counts display with danger tone styling when greater than zero, providing immediate visual feedback for security administrators.\n\n## Configuration Management\n\n### Setting Origin Tracking\n\nIndividual settings can be traced to their origin layer through the Setting Detail Panel:\n\n```mermaid\ngraph TD\n A[Setting Path] --> B{Origin Count}\n B -->|Single| C[Display Source Layer]\n B -->|Multiple| D[Per-Leaf Origin Table]\n D --> E[List of Leaf Paths]\n D --> F[Layer per Leaf]\n```\n\nSettings with multiple origins display a collapsible table showing which layer each configuration leaf originated from.\n\n资料来源：[apps/aidocs-dashboard/src/SettingDetailPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SettingDetailPanel.tsx)\n\n### Layer Tone Indicators\n\n| Layer Type | Visual Tone |\n|------------|-------------|\n| Default | Standard styling |\n| Active | Highlighted indicator |\n| Modified | Distinct color for changed values |\n\n## Connection Status\n\nThe Castle Shell status bar displays MCP connection state:\n\n| State | Indicator | Meaning |\n|-------|-----------|---------|\n| Connected | Green dot + \"MCP connected\" | Security enforcement active |\n| Disconnected | Red dot + \"MCP disconnected\" | Fallback mode or misconfiguration |\n\n资料来源：[apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)\n\n## Security Workflow Summary\n\n```mermaid\ngraph LR\n A[Request] --> B{Dev Mode?}\n B -->|Yes| C[Additional Access]\n B -->|No| D{Normal Checks}\n D --> E{Security Enforce?}\n E -->|No| F[Minimal Security]\n E -->|Yes| G[Full Enforcement]\n G --> H[Heuristic Analysis]\n H --> I{Risk Level}\n I -->|Low| J[RBAC]\n I -->|Medium| K[Gate Permission]\n I -->|High| L[Block]\n J --> M{Has Permission?}\n M -->|Yes| N[Tool Policy]\n M -->|No| L\n N --> O{Allowed?}\n O -->|Yes| P[Execute + Output Guard]\n O -->|No| L\n K --> Q{Approved?}\n Q -->|Yes| P\n Q -->|No| L\n```\n\n## Summary\n\nAIDOCS Security & Access Control provides comprehensive protection for AI-assisted development through:\n\n1. **Centralized Access Gate** - Single entry point for all authorization decisions\n2. **Heuristic Analysis** - Automated risk scoring based on request patterns\n3. **RBAC Engine** - Fine-grained permission management with escalation support\n4. **Tool Policy** - Command allowlisting with layered configuration\n5. **Output Guard** - Prompt injection detection and sensitive data redaction\n6. **Real-time Monitoring** - Dashboard visibility into security events and statistics\n\nThe system is designed with defense-in-depth principles, ensuring that multiple independent checks must pass before potentially risky operations are executed.\n\n---\n\n\n\n## Indexing & Retrieval System\n\n### 相关页面\n\n相关主题：[Memory System](#memory-system)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [mcp/server/aidocs_mcp/code_index_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/code_index_store.py)\n- [mcp/server/aidocs_mcp/code_index_symbol_search_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/code_index_symbol_search_service.py)\n- [mcp/server/aidocs_mcp/semantic_search.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/semantic_search.py)\n- [mcp/server/aidocs_mcp/index_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/index_store.py)\n- [mcp/server/aidocs_mcp/outline_extractors/__init__.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/outline_extractors/__init__.py)\n
\n\n# Indexing & Retrieval System\n\n## Overview\n\nThe Indexing & Retrieval System is the core backbone of AIDOCS, enabling AI coding agents to efficiently locate, analyze, and retrieve code symbols, semantic concepts, and structural information across a codebase. It transforms a raw repository into a queryable, memory-augmented context that allows agents to resume work without re-discovering the codebase on every session.\n\nThe system operates as a layered pipeline that:\n\n1. **Discovers** code files based on language descriptors\n2. **Parses** files to extract symbols, outlines, and semantic metadata\n3. **Indexes** extracted data into structured storage\n4. **Serves** retrieval queries through MCP tools (`ai_find`, `ai_bundle`, `ai_investigate`, `ai_trace`)\n\nThis architecture is designed for persistent memory across sessions, fast targeted lookups, and multi-language support with configurable heuristics.\n\n资料来源：[mcp/server/README.md]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Codebase Files] --> B[Language Descriptors]\n B --> C[File Discovery]\n C --> D[Outline Extractors]\n D --> E[Symbol Parsers]\n E --> F[Index Storage Layer]\n F --> G[index_store.py]\n F --> H[code_index_store.py]\n G --> I[Retrieval Query Pipeline]\n H --> I\n I --> J[semantic_search.py]\n J --> K[code_index_symbol_search_service.py]\n K --> L[MCP Tools: ai_find, ai_bundle, ai_investigate]\n```\n\n## Language Descriptor System\n\n### Purpose\n\nLanguage descriptors inform the indexer which files belong to a project, what support tier applies, and what heuristic semantics influence indexing behavior. They act as the discovery and classification layer for the entire indexing pipeline.\n\n资料来源：[mcp/INDEX_LANGUAGE_DESCRIPTORS.md]()\n\n### Descriptor Locations\n\n| Location | Path | Purpose |\n|----------|------|---------|\n| Built-in | `mcp/server/aidocs_mcp/index_languages/` | Ships with AIDOCS |\n| Project-local | `/index_languages/*.toml` | Extends or overrides built-in |\n\nProject-local descriptors can extend or override built-in behavior, allowing teams to define custom language support or refine heuristics for their specific codebase.\n\n资料来源：[mcp/INDEX_LANGUAGE_DESCRIPTORS.md]()\n\n### Supported Keys\n\n**Discovery Keys** (at least one required):\n\n- `extensions` — file extensions (e.g., `.py`, `.ts`)\n- `suffixes` — alternative naming patterns\n- `include_globs` — glob patterns for discovery\n\n**Core Keys**:\n\n| Key | Type | Description |\n|-----|------|-------------|\n| `name` | string | Language identifier |\n| `tier` | string | Support tier: `full`, `heuristic`, `minimal` |\n| `extensions` | list | File extensions |\n| `suffixes` | list | Alternative file suffixes |\n| `include_globs` | list | Glob patterns |\n\n**Semantics Keys** (influence indexing behavior):\n\n| Key | Description |\n|-----|-------------|\n| `semantic_tags` | Tags for semantic classification |\n| `outline_family` | Family name for outline patterns |\n| `outline_patterns` | Patterns for structural extraction |\n| `role_hint` | Default role hint (e.g., `analysis-script`) |\n| `role_patterns` | Patterns to detect role classifications |\n| `module_hints` | Directory names that hint at modules |\n\n资料来源：[mcp/INDEX_LANGUAGE_DESCRIPTORS.md]()\n资料来源：[mcp/server/aidocs_mcp/language_descriptors.py]()\n\n### Loading Descriptors\n\nDescriptors are loaded through `load_language_descriptors()` which implements a caching strategy:\n\n```mermaid\ngraph TD\n A[load_language_descriptors] --> B{Cache Hit?}\n B -->|Yes, schema version match| C[Return cached]\n B -->|No| D[Compute fingerprint]\n D --> E{Fingerprint match?}\n E -->|Yes| F[Return cached]\n E -->|No| G[Scan descriptor directories]\n G --> H[Load TOML files]\n H --> I[Filter by enabled languages]\n I --> J[Return descriptors]\n```\n\nThe function checks the schema version first, then compares file fingerprints to avoid unnecessary I/O. Only descriptors matching the enabled language set are loaded.\n\n资料来源：[mcp/server/aidocs_mcp/language_descriptors.py]()\n\n## Outline Extraction\n\n### Role of Outline Extractors\n\nOutline extractors parse source files to identify structural elements—classes, functions, methods, interfaces, and other symbols—and produce a lightweight outline representation. This is the primary mechanism for symbol discovery during indexing.\n\n资料来源：[mcp/server/aidocs_mcp/outline_extractors/__init__.py]()\n\n### Architecture\n\nThe outline extractor system uses a modular design with language-specific implementations. Each extractor conforms to a common interface that:\n\n1. Accepts a file path and content\n2. Returns structured symbol data with line numbers, kinds, and containers\n3. Handles language-specific parsing nuances\n\nThe `__init__.py` module exports the extractor registry and common data structures used across all language extractors.\n\n资料来源：[mcp/server/aidocs_mcp/outline_extractors/__init__.py]()\n\n## Index Storage Layer\n\n### Two-Store Architecture\n\nThe indexing system maintains two complementary storage mechanisms:\n\n```mermaid\ngraph LR\n A[index_store.py] --> B[General Index]\n A --> C[File-level metadata]\n A --> D[Language classification]\n E[code_index_store.py] --> F[Symbol Index]\n E --> G[Symbol definitions]\n E --> H[Reference mappings]\n E --> I[Container relationships]\n```\n\n**index_store.py** handles:\n\n- File-level metadata and indexing state\n- Language classification per file\n- Index-wide configuration and statistics\n\n**code_index_store.py** handles:\n\n- Symbol definitions extracted from source\n- Reference relationships between symbols\n- Container hierarchies (e.g., class → method relationships)\n\n资料来源：[mcp/server/aidocs_mcp/index_store.py]()\n资料来源：[mcp/server/aidocs_mcp/code_index_store.py]()\n\n### Symbol Index Structure\n\nThe symbol index maintains structured records for each extracted symbol:\n\n| Field | Description |\n|-------|-------------|\n| `symbol` | Symbol name |\n| `kind` | Type (function, class, method, interface, etc.) |\n| `path` | File path |\n| `line_number` | Definition line |\n| `container` | Parent symbol (class containing method, etc.) |\n| `language` | Source language |\n| `is_partial` | Partial definition flag (for C#, etc.) |\n\nThis structure enables efficient filtering by kind, container, and location during retrieval queries.\n\n资料来源：[mcp/server/METHODS.md]()\n\n## Retrieval Services\n\n### Semantic Search\n\n`semantic_search.py` implements concept-level search capabilities that go beyond exact symbol matching. It enables:\n\n- **Concept queries** — searching by semantic meaning rather than exact names\n- **Fuzzy matching** — handling typos and partial matches\n- **Ranking** — scoring results by relevance\n\nThe semantic search layer bridges the gap between natural language queries and structured symbol data, enabling agents to find code using descriptive terms.\n\n资料来源：[mcp/server/aidocs_mcp/semantic_search.py]()\n\n### Symbol Search Service\n\n`code_index_symbol_search_service.py` provides the core symbol-level search functionality:\n\n- **Symbol lookup** — find symbols by exact or partial name match\n- **Reference tracing** — locate all usages of a symbol\n- **Kind filtering** — search within specific symbol types\n- **Scope resolution** — navigate symbol containers\n\nThis service is the primary engine behind the `ai_find` MCP tool, which supports multiple search modes:\n\n| Mode | Purpose |\n|------|---------|\n| `symbols` | Find symbol definitions |\n| `references` | Find symbol usages |\n| `mutations` | Find code modifying a concept |\n| `validation` | Find validation logic |\n| `policy` | Find policy enforcement points |\n\n资料来源：[mcp/server/aidocs_mcp/code_index_symbol_search_service.py]()\n资料来源：[mcp/server/aidocs_mcp/claude_hook.py]()\n\n## MCP Tool Interface\n\n### Core Retrieval Tools\n\nThe indexing system exposes retrieval capabilities through these MCP tools:\n\n**ai_find** — Unified symbol and reference search across indexed code.\n\n**ai_investigate** — Broad concept investigation with ranked results across layers.\n\n**ai_bundle** — Retrieve comprehensive context for a file, path, or concept.\n\n**ai_trace** — Cross-layer relationship tracing for fields, settings, or services.\n\n**ai_get_symbol_snippet** — Retrieve exact symbol body with container context.\n\n**ai_get_symbol_info** — Retrieve symbol metadata (signature, constructor, enum, API).\n\n资料来源：[mcp/README.md]()\n\n### Read Pipeline\n\nLine-based reading flows through a shared read pipeline with strict mode enforcement:\n\n```mermaid\ngraph TD\n A[ai_get_lines] --> B[gate: strict mode]\n B --> C{Path valid?}\n C -->|No| D[Refusal]\n C -->|Yes| E[Check managed mode]\n E --> F[indexed_read_block]\n F --> G[Return lines]\n```\n\nStrict mode enforces:\n- No absolute path inputs\n- No `..` traversal\n- Zone restrictions (PROJECT_INTERNAL, MEMORY_INTERNAL only)\n\n资料来源：[mcp/server/aidocs_mcp/server_code_edit_tools.py]()\n\n## Configuration Options\n\n### Index Settings\n\nConfiguration options in `config_schema.py` control indexing behavior:\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `index.max_file_size` | integer | 100_000 | Max file size in bytes |\n| `index.max_json_size` | integer | 100_000 | Max JSON file size |\n| `index.enabled_languages` | string | \"all\" | Language set for filtering |\n| `index.include_tests` | boolean | false | Include test directories |\n| `index.extra_module_hints` | string_list | [] | Extra module directory names |\n| `languages.enabled` | string | \"all\" | Loaded language descriptors |\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `tools.sync_functions_timeout` | integer | 60 | Timeout for sync/indexer operations |\n| `tools.tool_call_timeout` | integer | 10 | Default tool call timeout |\n\n资料来源：[mcp/server/aidocs_mcp/config_schema.py]()\n\n## Layer Inference\n\nThe retrieval system infers architectural layers for search results, enabling context-aware queries:\n\n| Layer | Description |\n|-------|-------------|\n| `data` | Data access, models, DTOs |\n| `logic` | Business logic, services |\n| `api` | API endpoints, controllers |\n| `ui` | User interface components |\n| `code` | General code files |\n\nLayer inference helps agents understand where discovered code fits in the system architecture and find code at appropriate abstraction levels.\n\n资料来源：[mcp/server/METHODS.md]()\n\n## Session Persistence\n\nThe indexing system supports persistent sessions that maintain index state across agent invocations:\n\n- **Session-based indexing** — indexes can be tied to session IDs\n- **Project sync** — `project_sync_indexes` keeps indexes current with codebase\n- **Managed mode** — enforces controlled editing with session tracking\n\nThis persistence enables the \"resume work instead of rediscovering\" core value proposition of AIDOCS.\n\n资料来源：[mcp/README.md]()\n资料来源：[mcp/server/aidocs_mcp/claude_hook.py]()\n\n## Workflow Summary\n\n```mermaid\ngraph LR\n A[Initialize Project] --> B[Load Language Descriptors]\n B --> C[Discover Files]\n C --> D[Extract Outlines]\n D --> E[Parse Symbols]\n E --> F[Store in Index]\n F --> G[Ready for Retrieval]\n G --> H[ai_find / ai_investigate]\n G --> I[ai_bundle / ai_trace]\n H --> J[Symbol Search Service]\n I --> K[Semantic Search]\n J --> L[Agent Context]\n K --> L\n```\n\n## Related Documentation\n\n- [METHODS.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/METHODS.md) — Complete MCP tool reference\n- [INDEX_LANGUAGE_DESCRIPTORS.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/INDEX_LANGUAGE_DESCRIPTORS.md) — Language descriptor specification\n- [config_schema.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_schema.py) — Configuration reference\n\n---\n\n\n\n## Configuration Management\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview), [Security & Access Control](#security-gates)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)\n- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)\n- [apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)\n- [apps/aidocs-dashboard/src/BashPolicyPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/BashPolicyPanel.tsx)\n- [apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)\n
\n\n# Configuration Management\n\n## Overview\n\nAIDOCS provides a layered, hierarchical configuration system that enables persistent memory, indexed retrieval, and orchestration for AI coding agents. The configuration architecture supports multiple levels of override, from system defaults down to per-project and per-session settings.\n\n资料来源：[README.md]()\n\n## Configuration Architecture\n\nAIDOCS uses a **layered configuration model** where settings cascade from base defaults through environment-specific overrides to project-specific customizations.\n\n```mermaid\ngraph TD\n A[System Defaults] --> B[Environment Variables]\n B --> C[aidocs.toml Base]\n C --> D[Project .aidocs/]\n D --> E[Session Overrides]\n E --> F[Runtime Resolution]\n \n A -->|Low Priority| F\n E -->|High Priority| F\n```\n\n### Configuration Files\n\n| File | Location | Purpose | Format |\n|------|----------|---------|--------|\n| `aidocs.toml` | Project root | Runtime configuration with static definitions | TOML |\n| `hooks.json` | `core/hooks/` | Hook definitions for event-driven behavior | JSON |\n| Action Tokens | `action_tokens/` | Prompt-classification language files | YAML |\n| Language Descriptors | `index_languages/` | Per-language configuration | TOML |\n| Gate Messages | `gate_messages/` | Action hooks and permission definitions | TOML |\n\n资料来源：[README.md]()\n\n## Core Configuration: aidocs.toml\n\nThe primary runtime configuration file defines system-wide and per-project settings.\n\n### Configuration Sections\n\n```toml\n# aidocs.toml structure (conceptual)\n[dev]\ndev_mode = false # Enable editing MCP server source files\n\n[security]\nallow_config_edit = false # Allow agents to modify config via tool calls\nenforce = true # Enable tool gates and bash allowlist\n\n[memory]\n# Memory and indexing settings\nretention_days = 30\nindex_on_startup = true\n\n[mcp]\n# MCP server connection settings\ntransport = \"stdio\"\ncommand = \"aidocs-mcp\"\n```\n\n### Security Configuration\n\nThe security section controls agent capabilities and tool access:\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `security.allow_config_edit` | boolean | `false` | Allows agents to modify AIDOCS config via tool calls |\n| `security.enforce` | boolean | `true` | Enables tool gates, bash allowlist, and destructive command protection |\n| `dev.dev_mode` | boolean | `false` | Enables editing of MCP server source files |\n\n资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](), [apps/aidocs-dashboard/src/TomlConfigsPage.tsx]()\n\n**Warning Messages for Security Changes:**\n\n```typescript\n// From dashboardModals.tsx\n{settingPath === \"dev.dev_mode\" && \"Enables editing AIDOCS MCP server source files. Only use when actively developing AIDOCS.\"}\n{settingPath === \"security.allow_config_edit\" && \"Allows agents to modify AIDOCS config via tool calls. The agent can change gate settings, conductor config, and other project settings.\"}\n{settingPath === \"security.enforce\" && \"Disabling tool gates removes bash allowlist, raw tool blocking, and destructive command protection. Agents can use any tool freely.\"}\n```\n\n## Shell Policy Configuration\n\nThe bash policy system provides fine-grained control over shell command execution with a three-tier decision model.\n\n### Policy Actions\n\n| Action | Description |\n|--------|-------------|\n| `allow` | Command is permitted to execute |\n| `deny` | Command is blocked regardless of context |\n| `bubble` | Command requires explicit user approval |\n\n### Policy Display\n\nThe dashboard visualizes policy counts per layer:\n\n```typescript\n{counts.allowEff} allow\n{counts.denyEff} deny\n{counts.bubbleEff} bubble\n{counts.modifiedAtActive} set at {activeLayer}\n```\n\n资料来源：[apps/aidocs-dashboard/src/BashPolicyPanel.tsx]()\n\n### Filter Controls\n\nPolicy entries can be filtered using the search and category chips:\n\n```typescript\nconst filters = [\"all\", \"allow\", \"deny\", \"bubble\", \"modified\"] as const;\n```\n\n| Filter | Function |\n|--------|----------|\n| `all` | Show all policy entries |\n| `allow` | Show only allowed commands |\n| `deny` | Show only denied commands |\n| `bubble` | Show only commands requiring approval |\n| `modified` | Show only modified entries |\n\n## Action Tokens (Prompt Classification)\n\nAction Tokens are YAML-based language files that define how user prompts are classified and routed.\n\n### Structure\n\n```yaml\n# action_tokens/en.yaml (conceptual structure)\nintent_tokens:\n - name: \"implement\"\n pattern: \"implement|create|build|add\"\n action: \"code_generation\"\n \n - name: \"investigate\"\n pattern: \"investigate|analyze|trace\"\n action: \"code_analysis\"\n```\n\n### Configuration Categories\n\nThe TOML configuration page in the dashboard provides tabs for different configuration domains:\n\n| Tab | Purpose |\n|-----|---------|\n| Action Tokens | Prompt-classification language files (en, it, ...) |\n| Action Hooks | Gate messages and hook definitions |\n| Language Descriptors | Per-language configuration specifications |\n\n资料来源：[apps/aidocs-dashboard/src/TomlConfigsPage.tsx](), [mcp/README.md]()\n\n## Setup Wizard Configuration Flow\n\nThe setup wizard guides users through initial project configuration:\n\n```mermaid\ngraph TD\n A[Welcome] --> B[Project Selection]\n B --> C[Environment Detection]\n C --> D[Configuration]\n D --> E[Done]\n \n B -->|Select folder| B\n C -->|Missing deps| F[Install Dependencies]\n F --> C\n```\n\n### Setup Steps\n\n| Step | Description |\n|------|-------------|\n| `welcome` | Introduction and feature overview |\n| `project` | Project folder selection |\n| `detect` | Environment and tool detection |\n| `configure` | MCP, hooks, and project structure setup |\n| `done` | Configuration summary and next steps |\n\n### Configuration Results\n\nAfter setup, the wizard displays:\n\n```typescript\n
\n
\n MCP configured\n {configResult.mcp_path}\n
\n
\n Hooks registered\n {configResult.hooks_path}\n
\n
\n Project initialized\n
\n
\n```\n\n资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx]()\n\n### Environment Detection\n\nThe wizard detects installed tools and authentication status:\n\n| Component | Detection |\n|-----------|-----------|\n| Node.js | Check for CLI agent support |\n| Claude | Check for `claude.ai` authentication |\n| OpenAI | Check for API key configuration |\n\n```typescript\n{/* Sign-in button for detected but unauthenticated hosts */}\n{h.authenticated === false && (\n \n)}\n```\n\n## Configuration Resolution\n\nSettings follow a precedence hierarchy where higher layers override lower ones:\n\n```mermaid\ngraph LR\n A[Base Defaults] --> B[Project Config]\n B --> C[Session State]\n C --> D[Runtime Values]\n \n style A fill:#e1e1e1\n style D fill:#90EE90\n```\n\n### Layer Model\n\n| Layer | Scope | Override Priority |\n|-------|-------|-------------------|\n| System Defaults | Global | 1 (lowest) |\n| Environment Variables | Process-level | 2 |\n| `aidocs.toml` | Project root | 3 |\n| `.aidocs/` directory | Project-specific | 4 |\n| Session State | Per-session runtime | 5 (highest) |\n\n## TOML Document Management\n\nThe dashboard provides a unified interface for managing TOML configuration documents:\n\n```typescript\n// Document filtering by category\nconst categoryPrefix = \"mcp/server/aidocs_mcp/index_languages/\";\nconst filteredDocuments = tomlDocuments.filter((d) => d.path.startsWith(categoryPrefix));\n```\n\n### Document Table Columns\n\n| Column | Description |\n|--------|-------------|\n| Target | Configuration target identifier |\n| Active | Whether the config is currently active |\n| Context | Brief description of the configuration scope |\n\n## Command-Line Configuration\n\nAIDOCS provides CLI commands for configuration management:\n\n```bash\naidocs setup # Configures MCP, hooks, and project init\naidocs doctor # Verifies installation and configuration\n```\n\n| Command | Function |\n|---------|----------|\n| `aidocs setup` | Run the setup wizard to configure everything |\n| `aidocs doctor` | Validate the installation and configuration |\n\n资料来源：[README.md]()\n\n## Summary\n\nThe AIDOCS configuration management system provides:\n\n1. **Hierarchical Override**: Settings cascade from system defaults through project-specific configurations\n2. **Security Controls**: Fine-grained control over agent capabilities and tool access\n3. **Shell Policy**: Three-tier command execution model (allow/deny/bubble)\n4. **Language Support**: Extensible action token system for prompt classification\n5. **Dashboard Integration**: Visual configuration management through the Tauri-based dashboard\n6. **CLI Tools**: Command-line utilities for setup and validation\n\nAll configuration is designed to support the core goal of giving AI coding agents **persistent memory, indexed retrieval, and orchestration** while maintaining security and operational safety.\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: cristian1991/AIDOCS\n\nSummary: Found 9 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | host_targets=mcp_host, claude, claude_code, cursor\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | README/documentation is current enough for a first validation pass.\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n\n## 6. security_permissions · 来源证据：v2.0.0 — Unified AccessGate & Agent Enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.0 — Unified AccessGate & Agent Enforcement\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2ef38d1286d44ae9b266a98267a2d782 | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. security_permissions · 来源证据：v2.0.3 — Token Tracking & Dashboard Fixes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.3 — Token Tracking & Dashboard Fixes\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5428bd20316b4bfa987b009350fc138b | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | issue_or_pr_quality=unknown\n\n## 9. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.", "title": "Human Manual" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log\n\nProject: cristian1991/AIDOCS\n\nSummary: Found 9 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | host_targets=mcp_host, claude, claude_code, cursor\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | README/documentation is current enough for a first validation pass.\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium\n\n## 6. security_permissions · 来源证据：v2.0.0 — Unified AccessGate & Agent Enforcement\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.0 — Unified AccessGate & Agent Enforcement\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2ef38d1286d44ae9b266a98267a2d782 | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. security_permissions · 来源证据：v2.0.3 — Token Tracking & Dashboard Fixes\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.3 — Token Tracking & Dashboard Fixes\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5428bd20316b4bfa987b009350fc138b | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | issue_or_pr_quality=unknown\n\n## 9. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | release_recency=unknown\n", "summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.", "title": "Pitfall Log" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# AIDOCS - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for cristian1991/AIDOCS.\n\nProject:\n- Name: AIDOCS\n- Repository: https://github.com/cristian1991/AIDOCS\n- Summary: The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.\n- Host target: mcp_host, claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows. Works with Claude Code, Codex, OpenCode, Cursor. Apache 2.0.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to AIDOCS. Produce one small intermediate artifact and wait for confirmation.\n2. architecture-overview: System Architecture Overview. Produce one small intermediate artifact and wait for confirmation.\n3. mcp-server: MCP Server Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. memory-system: Memory System. Produce one small intermediate artifact and wait for confirmation.\n5. conductor-orchestration: Conductor & Orchestration. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/cristian1991/AIDOCS\n- https://github.com/cristian1991/AIDOCS#readme\n- README.md\n- mcp/README.md\n- core/AGENTS.md\n- mcp/server/ARCHITECTURE.md\n- mcp/server/METHODS.md\n- core/.commands/aidocs.md\n- mcp/server/aidocs_mcp/types.py\n- mcp/server/aidocs_mcp/mcp_server.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start\n\nProject: cristian1991/AIDOCS\n\n## Official Entry Points\n\n### Python / pip · 官方安装入口\n\n```bash\npip install aidocs-mcp\n```\n\nSource：https://github.com/cristian1991/AIDOCS\n\n## Sources\n\n- repo: https://github.com/cristian1991/AIDOCS\n- docs: https://github.com/cristian1991/AIDOCS#readme\n", "summary": "Entry points extracted from official README or installation documentation.", "title": "Quick Start" } }, "validation_id": "dval_6aec93c020bd4eafb797b5925239ca92" }