简介

AIDOCS 是一个面向 AI 编码代理的持久化记忆与编排平台。它为 AI 代理提供持久化记忆、索引检索和任务编排功能，使代理能够从中断处恢复工作，而无需每次重新探索代码仓库。资料来源：README.md:1

核心功能

主要特性

资料来源：README.md:1-5

系统架构

整体架构图

graph TD
    subgraph 前端层
        A[AIDOCS Dashboard]
    end
    
    subgraph MCP 服务层
        B[MCP Server]
        C[output_guard]
    end
    
    subgraph 核心功能
        D[Conductor]
        E[Execution Engine]
        F[Skills Registry]
    end
    
    subgraph 数据层
        G[上下文存储]
        H[执行快照]
    end
    
    A -->|Tauri IPC| B
    B --> C
    B --> D
    D --> E
    E --> F
    E --> G
    E --> H

Dashboard 应用结构

Dashboard 是一个基于 React 和 Tauri 构建的桌面应用，提供图形化界面。资料来源：index.html:1-9

graph TD
    subgraph Shell 容器
        A[CastleShell]
        B[Navigation]
        C[StatusBar]
    end
    
    subgraph 主要页面
        D[OverviewPage]
        E[ExecutionPage]
        F[ConductorPage]
        G[RBACPage]
        H[SkillsPage]
        I[RegistryPage]
        J[MonitoringPage]
        K[TomlConfigsPage]
        L[SetupWizardPage]
    end
    
    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    A --> G
    A --> H
    A --> I
    A --> J
    A --> K
    A --> L

页面功能详解

概览页面 (OverviewPage)

概览页面展示当前会话的核心信息，包括执行快照和上下文预算状态。资料来源：OverviewPage.tsx:1-50

上下文预算管理：

interface ContextBudget {
    status?: string;
    reason?: string;
    estimated_tokens?: number;
    journal_entries?: number;
    available?: boolean;
}

资料来源：OverviewPage.tsx:30-35

设置向导页面 (SetupWizardPage)

设置向导引导用户完成项目初始化配置流程，包含以下步骤：资料来源：SetupWizardPage.tsx:1-100

stateDiagram-v2
    [*] --> Welcome
    Welcome --> Project: 选择项目路径
    Project --> Environment: 检测环境
    Environment --> Configure: 环境就绪
    Configure --> Done: 配置完成
    Done --> [*]

环境检测结果：

interface DetectResult {
    node: { found: boolean };
    hosts: Array<{
        name: string;
        found: boolean;
        authenticated?: boolean;
        path?: string;
        installable?: boolean;
    }>;
}

资料来源：SetupWizardPage.tsx:50-80

执行页面 (ExecutionPage)

执行页面记录和展示工具调用的详细信息，包括路由审计和执行状态。资料来源：ExecutionPage.tsx:1-60

事件详情面板：

路由审计信息：

interface RoutingAudit {
    logicalMode?: string;
    nativeMode?: string;
    fallbackUsed?: boolean;
    visible: boolean;
}

资料来源：ConductorPage.tsx:20-30

权限控制页面 (RBACPage)

RBAC 页面提供基于角色的访问控制管理功能。资料来源：RBACPage.tsx:1-100

权限升级记录字段：

• requester：请求者
• permission：权限名称
• phrase：触发短语
• session/task：关联会话或任务
• sticky：是否持久化
• created · expires：创建和过期时间

技能页面 (SkillsPage)

技能页面管理和展示可用的 AI 技能列表。资料来源：SkillsPage.tsx:1-80

技能属性：

TOML 配置页面 (TomlConfigsPage)

TOML 配置页面管理项目配置文件，支持分类查看。资料来源：TomlConfigsPage.tsx:1-80

配置文档属性：

监控页面 (MonitoringPage)

监控页面展示系统事件统计信息，按事件类型和来源分类。资料来源：MonitoringPage.tsx:1-50

安全机制

输出守卫 (output_guard)

MCP 服务层包含 output_guard.py 模块，用于检测和防护提示注入攻击。资料来源：output_guard.py:1-50

检测的威胁模式：

敏感内容检测：

Shell 布局组件

CastleShell 是应用的主容器组件，整合导航、状态栏和页面内容。资料来源：CastleShell.tsx:1-100

graph TD
    subgraph CastleShell
        A[Navigation Sidebar]
        B[Top Strip]
        C[Main Content Area]
        D[Context Rail]
        E[Status Bar]
    end
    
    subgraph Navigation Items
        A -->|NavKey| O[Overview]
        A --> E[Execution]
        A --> C[Conductor]
        A --> R[RBAC]
        A --> S[Skills]
        A --> M[Registry]
        A --> M2[Monitoring]
        A --> T[TomlConfigs]
    end

状态栏信息：

版本信息显示：

{version && (
    <div className="mx-3 mb-3 rounded-xl border border-castle-line bg-black/25 px-3 py-2">
        <div className="text-[9px] font-bold uppercase tracking-widest text-castle-mute">
            Version
        </div>
        <div className="mt-0.5 font-mono text-xs text-slate-300">{version}</div>
    </div>
)}

资料来源：CastleShell.tsx:20-35

数据模型

执行事件 (ExecutionEvent)

执行事件是系统的核心数据单元，记录每次工具调用的详细信息。资料来源：OverviewPage.tsx:15-25

interface ExecutionEvent {
    event_id: string;
    capability_name?: string;
    event_kind: string;
    action_kind?: string;
    observed_at: string;
    status?: string;
    session_id?: string;
    payload?: Record<string, unknown>;
}

会话快照 (SessionSnapshot)

会话快照包含会话的完整上下文信息。资料来源：OverviewPage.tsx:20-35

interface SessionSnapshot {
    overview: {
        status: string;
        goal: string;
        owner: string;
    };
    execution: {
        recent: ExecutionEvent[];
    };
}

通道事件 (LaneEvent)

通道事件记录与特定执行通道相关的活动。资料来源：LaneDetailPanel.tsx:1-50

安装与部署

前提条件

资料来源：SetupWizardPage.tsx:60-70

安装命令

AIDOCS 支持通过 pip 安装 MCP 服务器组件。资料来源：README_INSTALL.md:1-20

连接配置

Dashboard 与 MCP 服务器通过 Tauri IPC 通信，状态栏实时显示连接状态。资料来源：CastleShell.tsx:50-70

路线图

AIDOCS 的公开路线图记录了项目的未来规划。资料来源：PUBLIC_ROADMAP.md:1-50

总结

AIDOCS 为 AI 编码代理提供了完整的上下文管理解决方案。通过持久化记忆、索引检索、执行监控和权限控制等核心功能，它使 AI 代理能够在复杂项目中保持连贯的工作状态。Dashboard 应用提供了直观的图形化界面，让用户能够轻松管理会话、查看执行历史、配置权限和监控系统运行状态。资料来源：README.md:1-5

概述

持久化记忆系统（Persistent Memory System）是 AIDOCS 的核心基础设施，为 AI 编码代理提供持久化上下文存储和检索能力。该系统使代理能够跨会话恢复工作，无需每次都重新探索代码仓库。

AIDOCS 的记忆系统基于 Markdown 文件结构，存储在项目根目录的 .MEMORY/ 目录中。所有记忆内容以结构化 Markdown 格式保存，支持版本控制和语义搜索。

核心功能：

• 持久化上下文 — 代理会话间的记忆保持
• 结构化存储 — 预定义的文件夹层次和文件名规范
• 语义索引 — 基于符号、概念和关系的检索
• 访问控制 — 文件位置校验和内容验证

资料来源：mcp/server/aidocs_mcp/runtime_service.py:1-50

概述

Conductor调度系统是AIDOCS框架中的核心任务编排与多代理协调引擎。该系统负责管理AI编码代理的工作流程、任务分发、状态追踪以及多代理间的通信协作。

Conductor系统的主要职责包括：

• 任务分解与分配：将复杂任务拆解为可执行的车道（Lane），并智能分配给合适的代理
• 多代理协调：支持主代理（Conductor）、副代理（Co-Conductor）以及King角色的分层协作
• 执行路由：根据配置和运行时状态选择合适的执行后端（claude、codex、opencode）
• 状态管理：维护任务执行状态、阻塞关系和进度追踪
• 持久化编排：通过持久内存机制确保代理在重启后能够恢复工作上下文

资料来源：ConductorPage.tsx:1-50

系统架构

核心组件

资料来源：runtime_conductor_dispatch_service.py, ConductorPage.tsx:1-30

层级关系

graph TD
    A[King Role] --> B[Conductor]
    A --> C[Co-Conductor]
    B --> D[Agent Worker Pool]
    C --> D
    B <--> C
    D --> E[External AI Backends]
    E --> F[Claude]
    E --> G[Codex]
    E --> H[OpenCode]

King角色位于层级顶端，负责全局战略决策；Conductor负责战术层面的任务分解和调度；Co-Conductor作为辅助角色协助完成复杂任务；Agent Worker实际执行具体任务单元。

资料来源：ConductorPage.tsx:180-200

消息角色系统

MsgRole 类型定义

系统定义了三种消息角色，用于标识不同代理在通信中的职能定位：

type MsgRole = "king" | "conductor" | "co-conductor";

const MSG_ROLE_LABEL: Record<MsgRole, string> = {
  king: "King",
  conductor: "Conductor",
  "co-conductor": "Co-Conductor",
};

资料来源：ConductorPage.tsx:210-230

消息接收者路由

消息可以定向发送给特定接收者或广播给多个角色：

type MsgRecipient = "conductor" | "co-conductor" | "both";

资料来源：ConductorPage.tsx:50-80

车道（Lane）机制

概念定义

Lane是Conductor调度系统中的核心执行单元概念，代表一个可独立或顺序执行的任务链路。系统通过分析任务依赖关系，自动计算车道的可运行状态。

车道状态模型

graph TD
    A[Lane Created] --> B{Runnable?}
    B -->|Yes| C[Runnable]
    B -->|No| D[Blocked]
    D --> E{Dependency Met?}
    E -->|Yes| C
    E -->|No| D
    C --> F[Executing]
    F --> G[Completed]

状态统计展示

前端界面通过Summary面板展示车道聚合状态：

<div className="conductor-summary">
  <div className="summary-row"><span>Progress</span><strong>{progressPercent}%</strong></div>
  <div className="summary-row"><span>Total lanes</span><strong>{conductorLanes.length}</strong></div>
  <div className="summary-row"><span>Runnable</span><strong>{runnableLaneIds.length}</strong></div>
  <div className="summary-row"><span>Blocked</span><strong>{Object.keys(blockedReasons).length}</strong></div>
</div>

资料来源：ConductorPage.tsx:100-115

执行路由机制

后端选择

Conductor支持多后端AI服务集成，运行时根据配置和策略选择合适的执行后端：

conductorDefaults = {
  backend: entry("conductor.backend")?.current_value ?? "claude",
  models: {
    claude: entry("conductor.claude_model")?.current_value ?? "",
    codex: entry("conductor.codex_model")?.current_value ?? "",
    opencode: entry("conductor.opencode_model")?.current_value ?? "",
  },
};

执行模式

每条执行事件记录包含多种执行模式标记：

<span className="execution-event-tokens">L:{logicalMode}</span>
<span className="execution-event-tokens">N:{nativeMode}</span>
<span className="execution-event-lane" style={{ color: "#fbbf24" }}>fallback</span>

资料来源：ConductorPage.tsx:150-170, ExecutionPage.tsx:1-30

配置管理

路由配置结构

const [routing, setRouting] = useState<Record<string, RouteConfig>>({});
const [routingOpen, setRoutingOpen] = useState(false);
const [routingError, setRoutingError] = useState<string | null>(null);

配置获取流程

sequenceDiagram
    participant UI as ConductorPage
    participant Config as ConfigEntries
    participant Backend as AI Backend
    
    UI->>Config: find("conductor.backend")
    Config-->>UI: current_value: "claude"
    UI->>Config: find("conductor.claude_model")
    Config-->>UI: model string
    UI->>Backend: dispatch(model)
    Backend-->>UI: execution result

前端交互界面

组件层级

graph TD
    A[ConductorPage] --> B[ToolCallsPanel]
    A --> C[ConductorChat]
    A --> D[ConductorLanesView]
    A --> E[ConductorSummary]
    C --> F[recipient selector]
    C --> G[message input]
    D --> H[blocked reasons]
    D --> I[runnable indicators]

消息显示组件

<div className={`conductor-msg conductor-msg-${msg.role}`}>
  {msg.msgRole ? <MsgRoleChip role={msg.msgRole} /> : null}
  <strong>{msg.role}</strong>
  <span>{msg.text}</span>
</div>

等待回复状态显示：

{awaitingReply ? (
  <div className="conductor-msg conductor-msg-system conductor-msg-pending">
    <strong>agent</strong>
    <span>Thinking...</span>
  </div>
) : null}

资料来源：ConductorPage.tsx:30-60

运行时状态

MCP连接状态

Conductor系统依赖MCP（Model Context Protocol）进行通信，状态栏实时反映连接状态：

<span className="flex items-center gap-1">
  <span className="h-1.5 w-1.5 rounded-full bg-castle-allow" />
  {mcpConnected ? "MCP connected" : "MCP disconnected"}
</span>

会话追踪

每个Conductor会话具有唯一标识，用于持久化和恢复：

<span>Session</span><strong>{selectedEvent.session_id ?? "n/a"}</strong>

资料来源：CastleShell.tsx:80-100, ExecutionPage.tsx:1-20

执行事件记录

事件数据结构

执行事件包含完整的执行上下文信息：

<div className="tool-detail-row"><span>Session</span><strong>{selectedEvent.session_id}</strong></div>
<div className="tool-detail-row"><span>Observed</span><strong>{formatTimestamp(selectedEvent.observed_at)}</strong></div>
<div className="tool-detail-row"><span>Lane</span><strong>{eventLane(selectedEvent)}</strong></div>

详情展示

{payload.args_preview ? (
  <div className="tool-detail-code">
    <div className="section-label">Arguments</div>
    <pre>{detailValue(payload.args_preview)}</pre>
  </div>
) : null}

资料来源：ExecutionPage.tsx:20-60

概览页面集成

上下文预算监控

Conductor与上下文管理集成，提供预算监控功能：

<div className="section-label">Context Budget</div>
<div className="summary-row"><span>Status</span><strong>{contextBudget?.status ?? contextBudget?.reason}</strong></div>
<div className="summary-row"><span>Estimated tokens</span><strong>{contextBudget?.estimated_tokens?.toLocaleString()}</strong></div>
<div className="summary-row"><span>Journal entries</span><strong>{contextBudget?.journal_entries ?? 0}</strong></div>

最近执行展示

{snapshot.execution.recent.slice(0, 6).map((event) => (
  <div key={event.event_id} className="feed-row execution-table-row">
    <strong>{event.capability_name ?? event.event_kind}</strong>
    <span>{event.action_kind ?? event.event_kind}</span>
    <time>{event.observed_at}</time>
  </div>
))}

资料来源：OverviewPage.tsx:1-50

总结

Conductor调度系统是AIDOCS框架中实现智能任务编排的核心引擎，通过多角色协作、车道机制和灵活的路由策略，使AI代理能够高效协同处理复杂任务。系统采用前后端分离架构，前端提供直观的可视化界面，后端通过Python服务实现核心调度逻辑，并通过MCP协议与各类AI后端集成。

主要特性包括：

• 分层角色系统：King、Conductor、Co-Conductor形成清晰的职责层级
• Lane驱动执行：基于依赖的车道模型确保任务正确排序
• 多后端支持：统一接口支持Claude、Codex、OpenCode等多种AI后端
• 实时状态追踪：完善的执行事件记录和进度可视化
• 配置灵活性：可定制的路由规则和模型参数

概述

AIDOCS 安全门控系统是保护 AI 编码代理安全运行的核心组件，它通过多层防护机制控制代理对系统资源的访问权限。该系统旨在防止代理意外或恶意修改敏感文件、执行危险命令，以及遭受提示词注入攻击。

安全门控系统采用分层架构设计，从文件访问控制、工具策略执行、输出内容审查到基于角色的权限管理，形成完整的防御体系。资料来源：access_gate.py:1-50

系统架构

组件层次

安全门控系统由以下核心组件构成：

graph TD
    subgraph "访问控制层"
        AG[access_gate.py<br/>访问门控]
        RB[rbac.py<br/>RBAC权限控制]
    end
    
    subgraph "策略执行层"
        TP[tool_policy.py<br/>工具策略]
        EN[controller.py<br/>执行控制器]
    end
    
    subgraph "内容审查层"
        OG[output_guard.py<br/>输出守卫]
        HJ[heuristic_judge.py<br/>启发式判断]
    end
    
    AG --> RB
    TP --> EN
    EN --> AG
    OG --> HJ

门控决策流程

graph TD
    A[请求进入门控] --> B{请求类型}
    B -->|读取| C[check_read]
    B -->|编辑| D[check_edit<br/>层级1检查]
    B -->|写入| E[check_write<br/>层级2-4检查]
    
    C --> F{路径检查}
    F -->|全局引导文件| G[BLOCK<br/>Tier0拒绝]
    F -->|敏感文件| H[BLOCK<br/>敏感文件保护]
    F -->|正常路径| I[ALLOW]
    
    D --> J{intent标志}
    J -->|true| K[ALLOW]
    J -->|false| L[check_write]
    
    E --> M{配置文件编辑}
    M -->|dev_mode启用| N[ALLOW]
    M -->|正常配置| O[BLOCK]
    
    E --> P{敏感文件检查}
    P -->|是| Q[BLOCK]
    P -->|否| R{其他检查}

核心组件详解

访问门控 (access_gate.py)

access_gate.py 是安全门控系统的核心模块，负责对文件操作进行细粒度控制。

#### 门控决策数据结构

class GateDecision:
    allowed: bool          # 是否允许操作
    level: str             # 门控层级标识
    reason: str            # 决策原因说明

#### 门控层级定义

资料来源：access_gate.py:30-80

#### 关键检查函数

check_edit() - 层级1编辑检查

@staticmethod
def check_edit(ctx: GateContext, path: str, *, has_intent: bool = False) -> GateDecision:
    """检查文件编辑是否允许"""
    # 层级1：全局引导文件永不接受代理编辑
    if _is_global_bootstrap(path):
        return GateDecision(allowed=False, level="edit_gate", reason="...")
    
    # 如果代理有明确意图且配置允许，则放行
    if has_intent and _check_dev_mode_and_state(path):
        return GateDecision(allowed=True, level="edit_gate")
    
    return GateDecision(allowed=False, level="edit_gate", reason=...)

资料来源：access_gate.py:60-90

check_write() - 层级2/3/4写入检查

@staticmethod
def check_write(ctx: GateContext, path: str, *, config_edit_mode: str | None = None, has_intent: bool = False) -> GateDecision:
    """检查文件写入/创建是否允许"""
    normalized = _normalize_path(path)
    
    # Tier 0: 全局引导文件保护
    # 永不通过代理修改，仅允许AIDOCS安装器操作
    if _is_global_bootstrap(normalized):
        return GateDecision(
            allowed=False,
            level="global_bootstrap_tier0",
            reason=f"Global host bootstrap file is never agent-writable: {normalized}"
        )
    
    # Level 3: 敏感文件保护
    if _is_sensitive(normalized):
        return GateDecision(
            allowed=False,
            level="sensitive_file_protection",
            reason=_gate_msg("sensitive_file_blocked", path=normalized)
        )
    
    # Level 2a: 配置文件处理
    # ...

资料来源：access_gate.py:95-140

输出守卫 (output_guard.py)

output_guard.py 负责检测和过滤代理输出中的潜在威胁内容。

#### 守卫模式分类

提示词注入检测模式

资料来源：output_guard.py:50-70

敏感内容检测模式

资料来源：output_guard.py:75-80

#### 扫描与脱敏

REDACTION_MARKER = "[REDACTED:{category}]"

def scan_text(text: str, *, redact: bool = True) -> GuardResult:
    """扫描文本中的安全威胁并可选地进行脱敏处理"""
    # 1. 检测提示词注入模式
    # 2. 检测敏感内容模式
    # 3. 根据redact参数决定是否替换敏感内容
    # 4. 返回GuardResult结构

资料来源：output_guard.py:82-95

工具策略 (tool_policy.py)

tool_policy.py 定义了工具执行的策略规则，包括允许列表、拒绝列表和气泡策略。

#### 策略动作类型

#### Shell策略管理

graph LR
    subgraph "BashPolicyPanel"
        PI[策略信息]
        SC[搜索/过滤]
        RB[规则列表]
    end
    
    PI -->|显示统计| SA[允许数/拒绝数/气泡数]
    SC -->|筛选| RB
    RB -->|应用| CT[当前活动层级配置]

资料来源：BashPolicyPanel.tsx:1-50

RBAC权限控制 (rbac.py)

RBAC模块实现了基于角色的访问控制，为不同类型的代理和用户分配不同的权限级别。

#### 权限层级

graph TD
    R1[管理员角色] --> A[全部权限]
    R2[高级代理角色] --> B[受限写权限]
    R3[普通代理角色] --> C[只读+部分写]
    R4[受限角色] --> D[仅读取]
    
    style R1 fill:#ff6b6b
    style R2 fill:#feca57
    style R3 fill:#48dbfb
    style R4 fill:#1dd1a1

启发式判断 (heuristic_judge.py)

heuristic_judge.py 通过启发式规则评估代理请求的风险级别，辅助门控决策。

#### 风险评估维度

资料来源：skill_scanner.py:40-70

执行控制器 (enforcement_pkg/controller.py)

controller.py 是安全策略的执行中枢，协调各组件的协作。

class EnforcementController:
    """执行控制器 - 协调所有安全检查"""
    
    def check_request(self, request: Request) -> EnforcementResult:
        # 1. RBAC权限检查
        # 2. 工具策略检查
        # 3. 访问门控检查
        # 4. 内容审查
        # 5. 汇总决策

资料来源：controller.py:1-40

配置管理

TOML配置文件

AIDOCS通过TOML文件管理安全配置，支持多层级配置覆盖。

# 配置文件结构示例
[gate_messages]
# 操作钩子配置

[language_descriptors]
# 语言描述符配置

[security]
allow_config_edit = false
enforce = true

资料来源：TomlConfigsPage.tsx:1-30

安全设置面板

安全相关配置可通过Dashboard界面管理：

资料来源：dashboardModals.tsx:1-20

危险操作确认

对于高风险操作，系统会弹出确认对话框：

sequenceDiagram
    participant AG as 代理请求
    participant GW as 网关
    participant UI as 用户界面
    participant AD as 管理员
    
    AG->>GW: 高风险操作请求
    GW->>UI: 显示确认对话框
    UI->>AD: 请求用户确认
    AD-->>UI: 用户决策
    UI-->>GW: 确认/拒绝结果
    GW->>AG: 执行或阻止

资料来源：dashboardModals.tsx:20-40

确认对话框警告文本

资料来源：dashboardModals.tsx:25-30

状态监控

MCP连接状态

Dashboard底部状态栏显示MCP连接状态：

<span className={mcpConnected ? "text-castle-allow" : "text-castle-deny"}>
  <span className="h-1.5 w-1.5 rounded-full bg-castle-allow" />
  MCP connected
</span>

资料来源：CastleShell.tsx:1-30

运行时快照

export function LoadingOverlay() {
  return (
    <div className="app-overlay" role="status" aria-live="polite">
      <div className="app-overlay-panel">
        <div className="overlay-spinner" />
        <strong>Loading runtime snapshot</strong>
        <span>Refreshing project, session, and settings state.</span>
      </div>
    </div>
  );
}

资料来源：dashboardModals.tsx:50-65

工作流程示例

文件编辑请求流程

graph TD
    A[代理请求编辑文件] --> B{是否为全局引导文件?}
    B -->|是| C[直接拒绝<br/>Tier0保护]
    B -->|否| D{是否为敏感文件?}
    D -->|是| E[拒绝<br/>敏感文件保护]
    D -->|否| F{是否启用dev_mode?}
    F -->|是| G{has_intent标志}
    G -->|true| H[允许编辑]
    G -->|false| I[拒绝]
    F -->|否| J[检查配置文件规则]
    J -->|允许| K[允许写入]
    J -->|拒绝| L[拒绝]

提示词注入检测流程

graph TD
    A[代理输出文本] --> B{检查system_override模式}
    B -->|匹配| C[标记为注入<br/>记录日志]
    B -->|无| D{检查role_hijack模式}
    D -->|匹配| E[标记为注入]
    D -->|无| F{检查instruction_inject模式}
    F -->|匹配| G[标记为注入]
    F -->|无| H{检查其他模式}
    H --> I[扫描敏感内容]
    I --> J{发现敏感数据?}
    J -->|是| K[脱敏处理]
    J -->|否| L[放行]
    C --> M[返回GuardResult]
    E --> M
    G --> M
    K --> M
    L --> M

最佳实践

开发环境配置

1. 仅在需要开发AIDOCS本身时启用 dev.dev_mode
2. 谨慎使用 security.allow_config_edit，确认代理确实需要此权限
3. 生产环境建议保持 security.enforce 启用状态

安全审查要点

异常处理

当门控拒绝操作时，系统会返回详细的原因信息：

GateDecision(
    allowed=False,
    level="sensitive_file_protection",
    reason="敏感文件被阻止: {path}"
)

开发者应捕获这些响应并向用户呈现友好的错误信息。

总结

AIDOCS安全门控系统通过多层次、细粒度的防护机制，为AI编码代理提供了全面的安全保障。系统从访问控制、策略执行、内容审查到权限管理等多个维度构建防御体系，有效防止了误操作、恶意攻击和敏感信息泄露等安全风险。理解并正确配置安全门控系统是确保AIDOCS稳定、安全运行的关键。

存储架构总览

AIDOCS 的存储架构由多个独立的存储模块组成，每个模块负责特定的数据域。整个系统遵循"文件是唯一真相来源"（Files remain the only source of truth）的核心原则，所有索引都是派生的、可从源文件重建的。

graph TD
    A[项目根目录] --> B[aidocs.toml]
    A --> C[.MEMORY/]
    A --> D[.aidocs/]
    
    B --> E[ConfigStore<br/>配置存储]
    C --> F[SessionStore<br/>会话存储]
    C --> G[MemoryStore<br/>内存文档存储]
    D --> H[CodeIndexStore<br/>代码索引存储]
    
    E --> I[SQLite: aidocs_config.db]
    F --> I
    G --> I
    H --> I
    
    I --> J[派生索引]
    J --> K[代码符号索引]
    J --> L[语义搜索索引]

资料来源：README.md

核心存储模块

ConfigStore（配置存储）

ConfigStore 负责管理项目级配置文件 aidocs.toml 的读取、验证和写入。该模块维护配置项的当前值、默认值，并支持配置变更的历史追踪。

配置存储采用 TOML 格式，主要配置域包括：

配置项具有以下属性结构：

• path: 配置项的 TOML 路径（如 security.enforce）
• kind: 配置值类型（布尔、字符串、数组等）
• default_value: 系统默认值
• current_value: 当前活跃值
• scope: 作用范围（全局或会话级别）

资料来源：mcp/server/aidocs_mcp/config_store.py

SessionStore（会话存储）

SessionStore 管理会话生命周期和会话相关的数据持久化。每个 AI 编码会话在启动时创建唯一标识符，用于关联该会话产生的所有上下文和操作记录。

会话存储的关键职责：

1. 会话创建与标识: 生成会话 ID，建立会话与项目的绑定关系
2. 上下文快照: 定期保存会话状态快照，支持会话恢复
3. 会话元数据: 记录会话起始时间、最近活动时间、关联的代码文件列表
4. 会话清理: 管理过期会话的清理策略

graph LR
    A[会话启动] --> B[创建会话ID]
    B --> C[初始化会话目录]
    C --> D[绑定到项目]
    D --> E[活动状态]
    E --> F[会话快照]
    E --> G[上下文检索]
    F --> H[会话终止]
    G --> H
    H --> I[归档或清理]

资料来源：mcp/server/aidocs_mcp/session_store.py

MemoryStore（内存文档存储）

MemoryStore 是 AIDOCS 的核心文档存储模块，负责管理 .MEMORY/ 目录下的所有持久化文档。这些文档构成了 AI 代理的"持久记忆"，包括项目不变式、架构决策、工作流程规则等。

#### 文档分类体系

AIDOCS 定义了严格的文档分类体系，每种类型对应特定的存储位置：

资料来源：mcp/server/aidocs_mcp/memory_store.py

#### 保留文件名规则

系统强制执行保留文件名规则，防止文档被错误放置：

_RESERVED_FILENAMES = {
    "plans.md": "只能位于 .MEMORY/plans/",
    "plan.md": "只能位于 .MEMORY/plans/ 或会话文件夹",
    "roadmap.md": "只能位于 .MEMORY/roadmaps/",
    "roadmaps.md": "只能位于 .MEMORY/roadmaps/",
    "bugs.md": "不应存储在 memory 中，应使用 issue tracker",
    "issues.md": "不应存储在 memory 中，应使用 issue tracker",
    "changelog.md": "仅在 .MEMORY/CHANGELOG.md 或 archive/",
}

#### 内容模式检测

系统包含内容模式检测器，用于识别可能被错误分类的文档：

资料来源：mcp/server/aidocs_mcp/memory_store.py

CodeIndexStore（代码索引存储）

CodeIndexStore 负责构建和维护代码库的符号索引，支持语义搜索、符号查找和代码导航。索引数据存储在 SQLite 数据库中，是完全派生的——可以从源代码随时重建。

#### 索引类型

#### 索引触发器

代码索引在以下事件发生时触发重建：

1. 项目初始化: 首次启用 AIDOCS 时执行全量索引
2. 显式同步: 调用 project_sync_indexes 方法
3. 增量更新: 检测到文件变更时更新相关索引条目

索引重建采用增量策略，仅重新索引变更的文件及其依赖项，以优化大规模项目的性能。

资料来源：mcp/server/aidocs_mcp/code_index_store.py

项目注册服务

ProjectRegistryService 维护系统中所有已初始化 AIDOCS 的项目列表。该服务跟踪每个项目的根路径、初始化时间、最后访问时间和运行时状态。

项目元数据结构

注册表持久化

项目注册表存储在全局配置目录下的 SQLite 数据库中，与单个项目的 .MEMORY/ 目录分离，确保即使项目目录被删除，注册信息仍可查询。

graph TD
    A[全局注册表<br/>~/.aidocs/projects.db] --> B[项目元数据表]
    A --> C[运行时快照表]
    A --> D[历史记录表]
    
    B --> E[project_root]
    B --> F[project_name]
    B --> G[initialized_at]
    
    C --> H[snapshot_json]
    C --> I[created_at]
    
    D --> J[change_type]
    D --> K[change_data]
    D --> L[timestamp]

资料来源：mcp/server/aidocs_mcp/project_registry_service.py

托管存储（Managed Store）

aidocs_managed_store.py 实现 AIDOCS 的托管模式存储逻辑。托管模式是 AIDOCS 的核心安全特性，在该模式下，系统对文件操作实施严格的访问控制。

托管模式架构

graph TD
    A[文件操作请求] --> B{托管模式启用?}
    B -->|否| C[允许直接访问]
    B -->|是| D[Gate 检查链]
    
    D --> E[Level 1: Managed Mode<br/>阻止原始文件工具]
    E --> F[Level 2: Infrastructure<br/>阻止 aidocs.toml 写入]
    F --> G[Level 3: Sensitive Files<br/>阻止凭证文件访问]
    G --> H[Level 4: Memory Path<br/>.MEMORY 读写策略]
    H --> I[Level 5: Read Gate<br/>按文件发现权限]
    I --> J[Level 6: Edit Gate<br/>需要先读取/发现]
    
    J -->|通过| K[允许操作]
    J -->|拒绝| L[阻止操作<br/>返回原因]
    
    C --> K

存储策略

托管存储支持多种读写策略：

资料来源：mcp/server/aidocs_mcp/aidocs_managed_store.py

运行时快照

运行时快照是 AIDOCS 在特定时刻捕获的项目状态记录，用于支持会话恢复和状态回溯。

快照内容

快照存储

快照数据存储在以下位置：

• 项目级: .aidocs/snapshots/{timestamp}.json
• 全局缓存: ~/.aidocs/cache/snapshots/

Dashboard 应用通过 Tauri 后端读取和显示运行时快照，刷新时显示加载动画，提示用户正在同步项目、会话和设置状态。

资料来源：apps/aidocs-dashboard/src-tauri/src/main.rs

索引同步方法

MCP 服务器提供以下方法用于索引管理：

project_sync_indexes

def project_sync_indexes(project_root: Path, include_tests: bool = False) -> dict

参数说明：

返回值：

{
    "memory_index_sync_result": {...},
    "code_manifest_sync_result": {...}
}

project_check

运行项目结构检查，验证 AIDOCS 初始化完整性。

返回值：

资料来源：mcp/server/METHODS.md

TOML 配置文档管理

Dashboard 提供 TOML 配置文档的可视化浏览和管理界面，支持按类别筛选和快速切换。

配置文件分类

配置文档显示

配置文档页面使用扁平表格布局，每行显示：

• Target: 配置目标名称
• Active: 激活状态（开关形式）
• Context: 上下文信息

资料来源：apps/aidocs-dashboard/src/TomlConfigsPage.tsx

安全与权限

AIDOCS 的存储系统集成了多层安全机制：

敏感文件保护

系统自动阻止对以下文件的读写操作：

• .env 文件
• 凭证文件
• API 密钥存储
• 其他安全敏感配置

配置变更确认

修改特定配置项时需要用户确认：

资料来源：apps/aidocs-dashboard/src/dashboardModals.tsx

总结

AIDOCS 的数据存储与索引系统采用模块化设计，通过清晰的职责划分实现了高效的状态管理和安全的访问控制：

• ConfigStore 集中管理项目配置
• SessionStore 维护会话生命周期
• MemoryStore 组织项目记忆文档
• CodeIndexStore 提供快速的代码检索能力
• ProjectRegistryService 追踪全局项目状态
• ManagedStore 实施安全策略

整个系统的设计哲学是"文件即真相"，所有派生数据都可以从源文件重建，确保了系统的可靠性和可恢复性。

概述

MCP运行时（MCP Runtime）是AIDOCS项目的核心组件，为AI编码代理提供持久化记忆、索引检索和工作流编排能力。它作为Model Context Protocol（MCP）服务器运行，使AI代理能够在项目中恢复工作，而无需每次重新探索代码库。

MCP运行时的核心职责包括：

• 工具发现与注册：自动扫描项目中的MCP服务器和服务
• 代码理解与检索：提供符号搜索、依赖分析、上下文聚合等能力
• 安全门控：6级级联安全机制，控制工具使用权限
• 会话管理：维护代理会话状态和记忆持久化

资料来源：mcp/README.md

架构概览

graph TD
    subgraph "MCP客户端层"
        IDE[IDE / Claude CLI]
    end
    
    subgraph "MCP运行时核心"
        Server[MCP Server]
        Tools[工具注册表]
        Gates[安全门控]
        Session[会话管理]
    end
    
    subgraph "记忆存储层"
        Index[.MEMORY/索引]
        SQLite[SQLite索引]
        Plans[计划/路标]
    end
    
    IDE <--> Server
    Server <--> Tools
    Server <--> Gates
    Server <--> Session
    Session <--> Index
    Session <--> SQLite
    Session <--> Plans

目录结构

MCP服务器代码位于 mcp/server/aidocs_mcp/ 目录：

mcp/server/aidocs_mcp/
  mcp_server.py          # MCP协议服务器主入口
  cli.py                 # 命令行接口
  tool_discovery.py      # 工具发现与注册
  server_code_tools.py   # 代码理解工具集
  runtime_prompt_handling_service.py  # 运行时提示词处理
  memory_store.py        # 记忆存储服务
  skill_scanner.py       # 技能/风险扫描
  claude_hook.py         # Claude交互钩子

资料来源：mcp/server/README.md

核心组件

MCP服务器

mcp_server.py 是MCP协议的Python实现，负责与AI代理进行通信。它暴露一组工具（Tools）供AI调用：

资料来源：mcp/server/aidocs_mcp/mcp_server.py

工具发现系统

tool_discovery.py 负责自动扫描和注册项目中可用的MCP服务器：

graph LR
    Scan[扫描目录] --> Parse[解析配置]
    Parse --> Register[注册工具]
    Register --> Expose[暴露给AI]

支持发现的服务类型包括：

• 本地MCP服务器
• NPM包中的服务器
• Python包中的服务器
• STDIO传输的服务器

资料来源：mcp/server/aidocs_mcp/tool_discovery.py

代码工具集

server_code_tools.py 实现代码理解和检索的核心功能：

# 使用示例
if m == "dependency":
    return _grant(hub.code.get_dependency_bundle(root, path=target, limit=limit))
if m == "symbol":
    return _grant(hub.code.get_symbol_bundle(root, symbol=target, limit=limit))

资料来源：mcp/server/aidocs_mcp/server_code_tools.py:1-50

安全门控架构

MCP运行时实现了6级级联安全门控机制，首次匹配优先：

资料来源：mcp/README.md

风险模式检测

skill_scanner.py 包含技能和风险模式检测：

# 供应链风险模式
_CAPABILITY_RISKS = [
    (re.compile(r"npm\s+install"), "supply_chain", "medium"),
    (re.compile(r"\|\s*(?:ba)?sh"), "supply_chain", "critical"),
    (re.compile(r"https?://..."), "supply_chain", "low"),
]

# 能力声明风险
_CAPABILITY_RISKS = [
    (re.compile(r"read|write|delete\s+file"), "capability", "medium"),
    (re.compile(r"execute|run\s+command"), "capability", "high"),
    (re.compile(r"send|post\s+data"), "capability", "high"),
]

资料来源：mcp/server/aidocs_mcp/skill_scanner.py

运行时提示词处理

runtime_prompt_handling_service.py 处理AI代理的提示词路由：

graph TD
    Prompt[接收提示词] --> Classify[分类动作类型]
    Classify --> Route{路由决策}
    Route -->|需要AIDOCS入口| Entry[/aidocs入口流程]
    Route -->|已阻止| Blocked[返回阻止原因]
    Route -->|可处理| Handled[执行托管处理]
    Entry --> Handled
    Handled --> Report[生成报告]

处理模式

资料来源：mcp/server/aidocs_mcp/runtime_prompt_handling_service.py

CLI命令行接口

cli.py 提供命令行交互能力：

# 安装后可用命令
aidocs setup          # 配置MCP、钩子、项目初始化
aidocs doctor         # 验证安装状态

安装选项

资料来源：mcp/server/aidocs_mcp/cli.py, mcp/README.md

记忆模型

在初始化项目中，记忆存储在 /.MEMORY/ 目录：

/.MEMORY/
  .aidocs/index.aidocs     # 会话启动路由器
  plans/                   # 计划文档
  roadmaps/                # 路标文档
  archive/                 # 归档内容

保留文件名规则

为防止错误分类，系统定义了保留文件名规范：

资料来源：mcp/server/aidocs_mcp/memory_store.py

总结

MCP运行时是AIDOCS项目的技术核心，它通过：

1. 标准化工具接口 - MCP协议提供统一的AI-代码交互方式
2. 智能记忆检索 - 多模式上下文聚合，按会话引导
3. 分层安全防护 - 6级门控确保AI操作安全可控
4. 自动化配置 - 一键安装，自动发现和注册服务

这套架构使AI编码代理能够持久化工作记忆，在复杂项目中保持上下文连贯性，同时通过安全门控防止误操作。

概述

AIDOCS的MCP（Model Context Protocol）工具集是整个系统的核心组件，为AI编码代理提供持久化记忆、索引检索和编排能力。这些工具通过MCP协议暴露给AI代理，使其能够执行代码编辑、文件检索、项目管理、Shell命令执行以及安全审计等操作。

MCP工具集采用模块化架构设计，将不同功能域分离为独立的服务模块：

架构设计

graph TD
    subgraph "MCP服务端"
        A[MCP入口] --> B[工具路由器]
        B --> C[server_code_edit_tools]
        B --> D[server_code_tools]
        B --> E[server_memory_index_tools]
        B --> F[server_project_admin_tools]
        B --> G[server_run_tools]
    end
    
    subgraph "安全层"
        H[skill_scanner]
        I[output_guard]
        G --> H
        G --> I
    end
    
    subgraph "存储层"
        J[(索引数据库)]
        K[(项目配置)]
    end
    
    C --> J
    D --> J
    E --> J
    F --> K

代码编辑工具

server_code_edit_tools模块负责处理所有文件修改操作，提供细粒度的代码编辑能力。

核心工具函数

工作流程

sequenceDiagram
    participant Agent as AI代理
    participant Edit as 代码编辑工具
    participant Index as 索引服务
    participant Guard as 安全守卫

    Agent->>Edit: aidocs_str_replace(path, old, new)
    Edit->>Guard: 安全扫描旧/新字符串
    Guard-->>Edit: 扫描通过/拒绝
    Edit->>Edit: file_str_replace(project_root,...)
    Edit->>Index: post_edit_reindex_and_grant()
    Index-->>Edit: 索引更新完成
    Edit-->>Agent: 返回编辑结果

回合冲突检测

工具实现了_check_turn_edited机制，用于防止同一文件在同一回合内被连续编辑导致行号损坏：

顺序的基于行的编辑同一文件会损坏行号。强制代理批量操作。ai_batch_edit、ai_str_replace和ai_batch_str_replace绕过此检查——它们在内部处理排序或使用与行无关的匹配。

资料来源：server_code_edit_tools.py:_check_turn_edited

def _check_turn_edited(project_root: Path, path: str, tool_name: str) -> dict[str, Any] | None:
    managed = hub.managed_mode.get_mode(project_root)
    if not managed.get("active"):
        return None
    session_id = str(managed.get("session_id") or "").strip()
    canonical = str(path).replace("\\", "/").strip()

内存索引工具

server_memory_index_tools模块管理AIDOCS的持久化记忆系统，提供代码结构索引和语义检索能力。

索引模式

检索工具链

工具提供了一套递进式检索流程：

1. aidocs_bundle - 获取上下文束，支持结构化模式
2. aidocs_find - 符号级别搜索
3. aidocs_get_symbol_snippet - 读取符号所在代码片段
4. aidocs_get_method_signature - 获取方法签名
5. aidocs_get_constructor_params - 获取构造函数参数
6. aidocs_get_enum_values - 获取枚举值

资料来源：claude_hook.py:understand

aidocs_bundle(path, mode="file") (structure) → aidocs_find(query, mode="symbols") (find symbol) → aidocs_get_symbol_snippet (read it).

安全审计工具

技能扫描器（skill_scanner）

skill_scanner.py实现了多层次的风险模式识别系统，将风险分为四大类别：

#### 供应链风险模式

_SUPPLY_CHAIN_RISKS = [
    (re.compile(r"(?:curl|wget|fetch)\s+https?://"), "supply_chain", "high"),
    (re.compile(r"(?:pip|npm|cargo|go)\s+install\s+"), "supply_chain", "medium"),
    (re.compile(r"(?:npx|uvx|bunx)\s+\S+"), "supply_chain", "medium"),
    (re.compile(r"\|\s*(?:ba)?sh"), "supply_chain", "critical"),  # 管道到Shell
]

资料来源：skill_scanner.py:_SUPPLY_CHAIN_RISKS

#### 能力声明风险模式

_CAPABILITY_RISKS = [
    (re.compile(r"(?i)(?:read|write|delete|modify)\s+(?:file|directory)"), "capability", "medium"),
    (re.compile(r"(?i)(?:execute|run|spawn)\s+(?:command|shell)"), "capability", "high"),
    (re.compile(r"(?i)(?:send|post|upload)\s+data"), "capability", "high"),
]

输出守卫（output_guard）

output_guard.py模块负责在工具执行结果返回给AI代理前进行内容安全检查。

#### Prompt注入检测

_PROMPT_INJECTION_PATTERNS = [
    ("system_override", re.compile(r"(?i)ignore\s+(?:all\s+)?(?:previous|prior)")),  # 系统覆盖尝试
    ("role_hijack", re.compile(r"(?i)you\s+are\s+now\s+(?:a\s+)?(?:different|new)")),  # 角色劫持
    ("instruction_inject", re.compile(r"(?i)<\s*(?:system|instructions?)\s*>")),  # XML标签注入
    ("delimiter_escape", re.compile(r"(?i)```\s*(?:system|instructions?)\s*\n")),  # 代码块注入
]

#### 敏感内容模式

_SENSITIVE_CONTENT_PATTERNS = [
    ("env_file_content", re.compile(r"(?m)^[A-Z_]{3,}=\S{8,}$"), "Possible .env file content"),
    ("ssh_config", re.compile(r"(?i)(?:Host\s+\S+|IdentityFile\s+~/)"), "SSH config content"),
]

Shell执行工具

server_run_tools模块管理Shell命令执行，是AIDOCS中最敏感的工具集之一。它与Bash策略系统集成，支持命令的允许/拒绝/气泡策略。

策略机制

执行流程

graph TD
    A[执行Shell命令] --> B{匹配Bash策略}
    B -->|allow| C[直接执行]
    B -->|deny| D[阻止执行]
    B -->|bubble| E[气泡到用户确认]
    B -->|default| F{执行?}
    F -->|yes| C
    F -->|no| D
    C --> G[skill_scanner扫描]
    G --> H{发现风险?}
    H -->|yes| I[记录警告/阻止]
    H -->|no| J[返回结果]

项目管理工具

server_project_admin_tools模块处理项目级配置和层叠设置系统（Layer System）。

层叠配置

AIDOCS使用层叠配置系统，允许不同来源的配置按优先级合并：

配置编辑权限

该模块还管理allow_config_edit设置，控制代理是否有权限通过工具调用修改AIDOCS配置：

Allows agents to modify AIDOCS config via tool calls. The agent can change gate settings, conductor config, and other project settings.

资料来源：apps/aidocs-dashboard/src/dashboardModals.tsx

工具使用指南

推荐编辑流程

Claude Hook中定义了标准化的编辑工作流程：

aidocs_task_begin → 
  read with aidocs_get_lines or aidocs_get_symbol_snippet → 
  write with ONE of:
    - aidocs_str_replace (small exact-match edit)
    - aidocs_edit_lines (line-range rewrite)
    - aidocs_batch_edit (multiple edits atomic, up to 20)
→ aidocs_task_complete

资料来源：claude_hook.py:edit

工具签名快捷方式

在编辑前应使用以下工具获取精确的代码签名信息：

• aidocs_get_method_signature - 获取方法签名
• aidocs_get_constructor_params - 获取构造函数参数
• aidocs_get_enum_values - 获取枚举值
• aidocs_trace(class, mode="css_class") - CSS追踪
• aidocs_schema_query(name, mode="entity") - 数据库架构查询

安全考虑

双重编辑禁止

在同一回合内，禁止对同一文件的重叠区域进行两次写入操作。系统会检测并阻止这类操作以避免数据损坏。

索引刷新机制

每次文件编辑完成后，系统会自动执行post_edit_reindex_and_grant操作以确保后续读取不会返回过期数据。

危险设置确认

对于关键安全设置（如security.enforce、dev.dev_mode），系统会弹出确认对话框，要求用户明确确认更改：

Disabling tool gates removes bash allowlist, raw tool blocking, and destructive command protection. Agents can use any tool freely.

资料来源：apps/aidocs-dashboard/src/dashboardModals.tsx

概述

AIDOCS 仪表盘前端是基于 Tauri + React + TypeScript 构建的桌面应用，为 AI 编码智能体提供项目状态监控、配置管理、工具审计和安全策略可视化界面。

技术栈

入口文件位于 apps/aidocs-dashboard/index.html，根组件挂载到 #root 节点。

架构设计

整体布局结构

┌─────────────────────────────────────────────────────────────┐
│                      CastleShell (外壳)                      │
├──────────┬──────────────────────────────────────────────────┤
│          │                                                   │
│   导航    │                  主内容区域                       │
│   侧边栏   │               (各功能页面组件)                    │
│          │                                                   │
├──────────┴──────────────────────────────────────────────────┤
│                      状态栏 (Status Bar)                     │
└─────────────────────────────────────────────────────────────┘

核心组件层次

graph TD
    A[App.tsx - 根组件] --> B[CastleShell - 外壳布局]
    B --> C[导航相关组件]
    B --> D[主内容区]
    B --> E[StatusBar 状态栏]
    D --> F[OverviewPage 概览]
    D --> G[ConductorPage conductor]
    D --> H[TomlConfigsPage 配置]
    D --> I[RBACPage 权限]
    D --> J[SetupWizardPage 向导]
    D --> K[RegistryPage 注册表]

主要功能模块

1. 设置向导 (SetupWizardPage)

设置向导引导用户完成 AIDOCS 的初始配置，包含以下步骤：

资料来源：SetupWizardPage.tsx:1-150

#### 进度指示器

<div className="setup-steps">
  {SETUP_STEPS.map((s, i) => (
    <div key={s} className={`setup-step-dot ${
      step === s ? "active" : 
      i < SETUP_STEPS.indexOf(step) ? "completed" : ""
    }`} />
  ))}
</div>

步骤状态通过 step 状态变量控制，支持三种视觉状态：active（当前步骤）、completed（已完成）、默认（未完成）。

#### 环境检测面板

环境检测模块验证以下依赖项：

• Node.js：CLI 智能体必需
• 主机服务：Claude AI、OpenAI API 等登录状态检测
• MCP 可用性：Model Context Protocol 连接状态

对于未检测到的可安装项，提供内联安装复选框：

{!h.found && h.installable && (
  <label className="setup-install-toggle">
    <input type="checkbox" checked={installTargets.has(h.name)} 
           onChange={() => toggleTarget(h.name)} />
    Install
  </label>
)}

资料来源：SetupWizardPage.tsx:45-60

2. 概览页面 (OverviewPage)

概览页面展示当前项目的运行时快照信息，包括：

• 项目状态概览
• 最近执行事件列表

#### 执行事件表格

<div className="flat-table">
  <div className="table-head execution-table-row">
    <span>Capability</span>
    <span>Action</span>
    <span>Observed</span>
  </div>
  {snapshot.execution.recent.slice(0, 6).map((event) => (
    <div key={event.event_id} className="feed-row execution-table-row">
      <strong>{event.capability_name ?? event.event_kind}</strong>
      <span>{event.action_kind ?? event.event_kind}</span>
      <time>{event.observed_at}</time>
    </div>
  ))}
</div>

显示最近 6 条执行事件，每条包含能力名称、操作类型和观察时间戳。

资料来源：OverviewPage.tsx:1-50

3. Conductor 页面 (ConductorPage)

Conductor 页面是工具调用审计的核心界面，提供以下功能：

#### 功能特性

• Lane 可视化：展示 conductor lanes 和阻塞原因
• 工具调用详情：查看每次工具调用的 payload 和 diff
• 路由审计：记录工具路由决策过程

#### 组件 Props

#### 工具调用详情模态框

当用户选择某次工具调用事件时，显示详细信息：

<div className="tool-detail-row">
  <span>Action</span>
  <strong>{selectedEvent.action_kind ?? selectedEvent.event_kind}</strong>
</div>
<div className="tool-detail-diff">
  <DiffViewer original={oldText} modified={newText} />
</div>

支持 old_str/new_str 或 old_content/new_content 两种 payload 结构。

资料来源：ConductorPage.tsx:1-100

4. 导航外壳 (CastleShell)

CastleShell 是仪表盘的主布局组件，负责：

• 侧边导航栏
• 顶部导航条
• 上下文轨道（Context Rail）
• 状态栏

#### 导航项类型

type NavKey = "overview" | "conductor" | "live" | "configs" | 
              "bash_policy" | "rbac" | "registry" | "settings" | "wizard";

#### 状态栏组件

type CastleStatusBarProps = {
  mcpConnected: boolean;      // MCP 连接状态
  projectName?: string;       // 项目名称
  sessionId?: string;         // 会话 ID
  activeLayer?: string;       // 活跃配置层级
  saveState?: string;         // 保存状态
};

状态指示器根据 mcpConnected 布尔值显示绿色（MCP connected）或红色（MCP disconnected）。

资料来源：CastleShell.tsx:1-80

5. RBAC 页面 (RBACPage)

RBAC（基于角色的访问控制）页面管理权限条目和会话绑定状态。

#### 功能特性

• 查看所有权限条目列表
• 筛选 sticky（持久）或 once（一次性）权限
• 显示权限的创建时间和过期时间

#### 状态显示

{e.sticky ? (
  <span className="rbac-state-sticky">sticky</span>
) : (
  <span className="rbac-state-once">once</span>
)}

资料来源：RBACPage.tsx:1-80

6. Bash 策略面板 (BashPolicyPanel)

Bash 策略面板管理 shell 命令的允许/拒绝规则。

#### 策略统计

#### 过滤控件

<div className="settings-filter-chips">
  {(["all", "allow", "deny", "bubble", "modified"] as const).map((f) => (
    <button key={f} type="button" 
            className={"filter-chip" + (filter === f ? " is-active" : "")}>
      {f}
    </button>
  ))}
</div>

支持按名称匹配过滤和按类型过滤两种方式。

资料来源：BashPolicyPanel.tsx:1-60

7. TOML 配置页面 (TomlConfigsPage)

TOML 配置页面提供静态配置的可视化管理。

#### 配置分类

#### 文档表格

<div className="flat-table">
  <div className="table-head toml-table-row">
    <span>Target</span>
    <span>Active</span>
    <span>Context</span>
  </div>
  {filteredDocuments.map((document) => (
    <button key={document.path} type="button" 
            className={document.path === selectedTomlPath ? "table-row ... is-selected" : "table-row ..."}>
      <span title={document.path}>{document.target}</span>
      <span className="toggle-cell">
        <span className={isDocumentActive(document) ? "toggle is-on" : "toggle"}>
          <span className="toggle-knob" />
        </span>
      </span>
    </button>
  ))}
</div>

资料来源：TomlConfigsPage.tsx:1-80

8. 注册表页面 (RegistryPage)

注册表页面用于搜索和浏览 MCP 服务器列表。

#### 搜索结果卡片

每个 MCP 服务器卡片显示：

• 服务器名称
• 传输方式 (transport)
• 启动命令 (command)
• 安装命令（支持多种格式）

const installText = typeof firstCmd === "string" 
  ? firstCmd 
  : typeof firstCmd === "object" && firstCmd 
    ? String((firstCmd as Record<string, string>).command ?? "") 
    : "";

资料来源：RegistryPage.tsx:1-50

9. 设置详情面板 (SettingDetailPanel)

设置详情面板展示单个配置项的完整信息和来源追踪。

#### 功能特性

• 显示配置的当前值、默认值和来源层级
• 支持查看每个叶子节点（leaf）的来源
• 按层级着色的 pill 标签显示

#### 来源追踪表格

资料来源：SettingDetailPanel.tsx:1-80

10. 模态组件 (dashboardModals)

#### 安全变更确认模态

当用户尝试修改敏感配置时，显示确认对话框：

{settingPath === "dev.dev_mode" && "Enables editing AIDOCS MCP server source files."}
{settingPath === "security.allow_config_edit" && "Allows agents to modify AIDOCS config via tool calls."}
{settingPath === "security.enforce" && "Disabling tool gates removes bash allowlist..."}

#### 加载遮罩

<div className="app-overlay" role="status" aria-live="polite">
  <div className="app-overlay-panel">
    <div className="overlay-spinner" aria-hidden="true" />
    <strong>Loading runtime snapshot</strong>
    <span>Refreshing project, session, and settings state.</span>
  </div>
</div>

资料来源：dashboardModals.tsx:1-80

11. Lane 详情面板 (LaneDetailPanel)

Lane 详情面板展示特定 lane 的详细信息和关联事件。

#### 事件列表组件

<div className="flex items-start gap-2 rounded-md bg-black/25 px-2 py-1.5 text-[11px]">
  <time className="shrink-0 font-mono text-castle-mute">
    {(e.observed_at || "").slice(11, 19)}
  </time>
  <div className="min-w-0 flex-1">
    <div className="truncate font-bold text-slate-200">
      {e.capability_name || e.event_kind}
    </div>
    {e.action_kind && (
      <div className="text-castle-mute">{e.action_kind}</div>
    )}
  </div>
  <CastlePill tone={/* 状态相关颜色 */}>
    {e.status}
  </CastlePill>
</div>

状态颜色映射：

资料来源：LaneDetailPanel.tsx:1-60

数据流架构

状态管理流程

graph LR
    A[仪表盘启动] --> B[加载 Runtime Snapshot]
    B --> C[解析项目配置]
    C --> D[渲染导航树]
    D --> E[按需加载页面数据]
    E --> F[WebSocket 实时更新]
    F --> G[状态同步到 UI]

API 交互模式

仪表盘通过 Tauri 命令与后端通信：

invoke("open_url", { url }).catch(() => 
  window.open(url, "_blank", "noopener,noreferrer")
);

主要 API 调用包括：

• open_url：在浏览器中打开 URL
• 项目配置读写
• 会话状态查询
• 配置变更推送

设计系统

Castle 主题色板

通用样式类

总结

AIDOCS 仪表盘前端采用组件化架构，通过 CastleShell 提供统一的布局框架，各功能页面（概览、Conductor、配置、权限等）作为子组件按需渲染。状态管理依赖 Tauri 的命令调用和 React 的本地状态，实时更新通过 WebSocket 实现。设计系统采用暗色 "Castle" 主题，提供一致的视觉体验和清晰的状态反馈。

系统架构概览

AIDOCS 采用分层架构设计，将宿主代理集成划分为前端展示层、业务编排层和安全策略层三个主要部分。前端展示层负责可视化配置界面，包括 Conductor 页面、设置详情面板和安装向导；业务编排层处理代理路由、能力声明和执行审计；安全策略层则通过能力风险扫描和配置门控确保代理行为安全可控。

graph TD
    subgraph 前端展示层
        CP[ConductorPage 导体页面]
        SW[SetupWizardPage 安装向导]
        SP[SettingDetailPanel 设置详情]
        DM[dashboardModals 安全确认弹窗]
    end
    
    subgraph 业务编排层
        CR[Conductor 导体编排器]
        RM[路由管理器]
        AU[审计追踪]
    end
    
    subgraph 安全策略层
        SS[skill_scanner 技能扫描器]
        GP[门控策略]
        RB[RBAC 权限控制]
    end
    
    subgraph 宿主代理
        CA[Claude 代理]
        OX[OpenAI Codex]
        OC[OpenCode]
    end
    
    CP --> CR
    SW --> CR
    SP --> GP
    DM --> GP
    CR --> RM
    CR --> AU
    RM --> SS
    SS --> GP
    GP --> RB
    CA --> CR
    OX --> CR
    OC --> CR

导体配置与后端路由

后端类型定义

Conductor 页面提供了对多个 AI 后端的统一配置接口。系统支持三种主要后端类型，分别对应不同的 AI 服务提供商：

资料来源：apps/aidocs-dashboard/src/ConductorPage.tsx:conductorDefaults

导体配置通过 configEntries 数组管理，每个配置项包含路径（path）、当前值（current_value）等属性。配置项的读取采用防御性编程模式，使用可选链和空值合并确保在配置缺失时系统仍能正常运行：

const conductorDefaults = useMemo(() => {
  const entry = (path: string) => configEntries?.find((item) => item.path === path);
  return {
    backend: ((entry("conductor.backend")?.current_value as string | undefined) ?? "claude") as "claude" | "codex" | "opencode",
    models: {
      claude: String(entry("conductor.claude_model")?.current_value ?? ""),
      codex: String(entry("conductor.codex_model")?.current_value ?? ""),
      opencode: String(entry("conductor.opencode_model")?.current_value ?? "")
    }
  };
}, [configEntries]);

路由配置管理

Conductor 的路由配置存储在 routing 状态中，采用 Record<string, RouteConfig> 的数据结构，其中键为路由标识符，值为路由配置对象。路由状态通过 useState 钩子管理，支持动态更新和错误处理：

const [routing, setRouting] = useState<Record<string, RouteConfig>>({});
const [routingOpen, setRoutingOpen] = useState(false);
const [routingError, setRoutingError] = useState<string | null>(null);

能力声明与执行追踪

工具调用事件模型

当宿主代理调用工具时，Conductor 页面会记录完整的事件信息。事件数据结构包含能力名称（capability_name）、动作类型（action_kind）、时间戳（observed_at）以及关联的负载信息：

interface ToolCallEvent {
  event_id: string;
  capability_name?: string;
  action_kind?: string;
  event_kind: string;
  observed_at: string;
  payload?: Record<string, unknown>;
}

资料来源：apps/aidocs-dashboard/src/ConductorPage.tsx:toolCallEvent

差异对比与负载展示

对于包含文本变更的事件，系统提供差异对比视图（DiffViewer）来直观展示旧内容与新内容的变更：

const oldText = typeof payload.old_str === "string" 
  ? payload.old_str 
  : typeof payload.old_content === "string" 
    ? payload.old_content 
    : null;
const newText = typeof payload.new_str === "string" 
  ? payload.new_str 
  : typeof payload.new_content === "string" 
    ? payload.new_content 
    : null;

{oldText && newText 
  ? <div className="tool-detail-diff">
      <div className="section-label">Diff</div>
      <DiffViewer original={oldText} modified={newText} />
    </div>
  : null
}

资料来源：apps/aidocs-dashboard/src/ConductorPage.tsx:DiffViewer

当事件不包含文本差异但有其他负载数据时，系统以 JSON 格式展示完整的负载内容：

{!oldText && !newText && payload && Object.keys(payload).length > 0 
  ? <div className="tool-detail-code">
      <div className="section-label">Payload</div>
      <pre>{JSON.stringify(payload, null, 2)}</pre>
    </div>
  : null
}

能力风险扫描

风险模式定义

skill_scanner 模块定义了针对代理能力声明的风险扫描规则。系统通过正则表达式匹配来识别潜在的危险能力声明，并根据严重程度分为 critical、high、medium、low 四个等级：

资料来源：mcp/server/aidocs_mcp/skill_scanner.py:_CAPABILITY_RISKS

供应链安全扫描

除能力声明外，skill_scanner 还包含供应链安全相关的扫描规则，用于检测代理脚本中可能存在的供应链攻击风险：

_CAPABILITY_RISKS: list[tuple[re.Pattern[str], str, str, str]] = [
    # 远程包执行
    (re.compile(r"(?:npx|uvx|bunx)\s+\S+"), "supply_chain", "medium", "Remote package execution"),
    # 外部 URL 引用
    (re.compile(r"https?://(?!(?:github\.com|docs\.|api\.|registry\.))[^\s\"'<>]{20,}"), 
     "supply_chain", "low", "External URL reference"),
    # 管道到 shell
    (re.compile(r"\|\s*(?:ba)?sh"), "supply_chain", "critical", "Pipe to shell execution"),
]

资料来源：mcp/server/aidocs_mcp/skill_scanner.py:_SUPPLY_CHAIN_RISKS

安全策略与配置门控

关键配置项

AIDOCS 提供了多个与宿主代理集成相关的安全配置项，通过安全确认弹窗进行保护：

资料来源：apps/aidocs-dashboard/src/dashboardModals.tsx:SecurityConfirmModal

安全确认流程

当用户尝试修改敏感配置项时，系统会弹出确认对话框，详细说明变更的潜在风险：

export function SecurityConfirmModal({ settingPath, close, confirm }) {
  return (
    <div className="modal-backdrop" onClick={close}>
      <div className="modal-panel danger-modal" onClick={(e) => e.stopPropagation()}>
        <div className="page-header modal-header">
          <div>
            <div className="section-label">Confirm Security Change</div>
            <h3>{settingPath}</h3>
          </div>
        </div>
        <p className="warning-text modal-warning-copy">
          {settingPath === "dev.dev_mode" && 
            "Enables editing AIDOCS MCP server source files. Only use when actively developing AIDOCS."}
          {settingPath === "security.allow_config_edit" && 
            "Allows agents to modify AIDOCS config via tool calls."}
          {settingPath === "security.enforce" && 
            "Disabling tool gates removes bash allowlist, raw tool blocking, and destructive command protection."}
        </p>
      </div>
    </div>
  );
}

安装向导与平台认证

主机检测流程

SetupWizardPage 负责引导用户完成 AIDOCS 的初始配置。安装向导会检测系统中已安装的 AI 平台主机，并为未安装的平台提供安装选项：

{detectResult.hosts.map((h) => (
  <div key={h.name} 
    className={`setup-check ${h.found 
      ? (h.authenticated === false ? "warn" : "pass") 
      : "missing"}`}>
    <span className="setup-check-icon">
      {h.found ? (h.authenticated === false ? "!" : "+") : "-"}
    </span>
    <span>
      {h.name}
      {h.found && h.authenticated === false ? " (not signed in)" : ""}
    </span>
  </div>
))}

资料来源：apps/aidocs-dashboard/src/SetupWizardPage.tsx:hostDetection

平台认证流程

对于已安装但未认证的主机，向导提供一键跳转认证功能：

<button onClick={() => {
  const url = h.name.includes("Claude") 
    ? "https://claude.ai" 
    : "https://platform.openai.com/api-keys";
  invoke("open_url", { url }).catch(() => 
    window.open(url, "_blank", "noopener,noreferrer")
  );
}}>Sign in</button>

配置完成清单

安装完成后，向导展示详细的配置结果，包括 MCP 配置路径、钩子注册路径以及已安装的平台列表：

<div className="setup-checklist">
  <div className="setup-check pass">
    <span className="setup-check-icon">+</span>
    <span>MCP configured</span>
    <span className="setup-check-detail">{configResult.mcp_path}</span>
  </div>
  <div className="setup-check pass">
    <span className="setup-check-icon">+</span>
    <span>Hooks registered</span>
    <span className="setup-check-detail">{configResult.hooks_path}</span>
  </div>
  {installResult && installResult.installed.length > 0 && (
    <div className="setup-check pass">
      <span className="setup-check-icon">+</span>
      <span>Installed: {installResult.installed.join(", ")}</span>
    </div>
  )}
</div>

页面懒加载架构

动态导入配置

AIDOCS Dashboard 采用 React 的 lazy 和 Suspense 机制实现页面级代码分割，减少初始加载体积。代理相关的页面组件按需加载：

const ConductorPage = lazy(() => 
  import("./ConductorPage").then((module) => ({ 
    default: module.ConductorPage 
  }))
);
const ConductorAgentsPage = lazy(() => 
  import("./ConductorAgentsPage").then((module) => ({ 
    default: module.ConductorAgentsPage 
  }))
);
const ExecutionPage = lazy(() => 
  import("./ExecutionPage").then((module) => ({ 
    default: module.ExecutionPage 
  }))
);
const MonitoringPage = lazy(() => 
  import("./MonitoringPage").then((module) => ({ 
    default: module.MonitoringPage 
  }))
);

资料来源：apps/aidocs-dashboard/src/App.tsx:lazyImports

路由与状态管理

主应用根据当前激活的导航键（NavKey）动态渲染对应的页面组件。状态管理通过 useState 和 useReducer 实现，确保导航状态与页面渲染的同步：

const [activeNav, setActiveNav] = useState<NavKey>("overview");
const [isLoading, setIsLoading] = useState(false);
const [runtimeSnapshot, setRuntimeSnapshot] = useState<RuntimeSnapshot | null>(null);

执行流程图

sequenceDiagram
    participant U as 用户
    participant SW as SetupWizard
    participant MC as MCP Server
    participant CA as Claude Agent
    participant CR as Conductor
    
    U->>SW: 选择项目路径
    SW->>MC: 检测主机环境
    MC-->>SW: 返回检测结果
    U->>SW: 安装/认证平台
    U->>SW: 确认配置
    SW->>MC: 应用 MCP 配置
    MC-->>SW: 配置完成
    Note over SW,MC: 安装向导完成
    
    CA->>CR: 工具调用
    CR->>MC: 路由审计
    MC-->>CR: 审计结果
    CR->>CR: 风险扫描
    alt 高风险操作
        CR-->>U: 安全确认弹窗
        U->>CR: 确认/取消
    end
    CR-->>CA: 执行结果

总结

宿主代理集成是 AIDOCS 系统的核心功能模块，它通过多层架构实现了 AI 代理与项目持久化系统的无缝连接。该模块的主要特性包括：

• 多后端支持：统一管理 Claude、Codex、OpenCode 等多种 AI 后端
• 动态路由：支持基于配置的能力路由和执行审计
• 安全门控：通过能力风险扫描和安全确认弹窗防止危险操作
• 平台认证：集成化的安装向导简化 AI 平台配置流程
• 代码分割：采用懒加载机制优化前端性能

通过这些机制，AIDOCS 能够为 AI 编码代理提供一致的上下文感知能力和安全可控的执行环境。

Pitfall Log / 踩坑日志

项目：cristian1991/AIDOCS

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | host_targets=mcp_host, claude, claude_code, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：v2.0.0 — Unified AccessGate & Agent Enforcement

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.0 — Unified AccessGate & Agent Enforcement
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2ef38d1286d44ae9b266a98267a2d782 | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。

7. 安全/权限坑 · 来源证据：v2.0.3 — Token Tracking & Dashboard Fixes

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.3 — Token Tracking & Dashboard Fixes
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5428bd20316b4bfa987b009350fc138b | https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3 | 来源类型 github_release 暴露的待验证使用条件。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | release_recency=unknown