| 车道路由规则映射 |
| routingOpen | boolean | 路由配置面板展开状态 |
| routingError | string \| null | 路由配置错误信息 |
### 配置获取流程
```mermaid
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
```
## 前端交互界面
### 组件层级
```mermaid
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]
```
### 消息显示组件
```typescript
{msg.msgRole ? : null}
{msg.role}
{msg.text}
```
等待回复状态显示：
```typescript
{awaitingReply ? (
agent
Thinking...
) : null}
```
资料来源：[ConductorPage.tsx:30-60]()
## 运行时状态
### MCP连接状态
Conductor系统依赖MCP（Model Context Protocol）进行通信，状态栏实时反映连接状态：
```typescript
{mcpConnected ? "MCP connected" : "MCP disconnected"}
```
| 连接状态 | 指示器颜色 | 含义 |
|---------|-----------|-----|
| Connected | bg-castle-allow (绿色) | MCP服务正常运行 |
| Disconnected | bg-castle-deny (红色) | MCP服务不可用 |
### 会话追踪
每个Conductor会话具有唯一标识，用于持久化和恢复：
```typescript
Session{selectedEvent.session_id ?? "n/a"}
```
资料来源：[CastleShell.tsx:80-100](), [ExecutionPage.tsx:1-20]()
## 执行事件记录
### 事件数据结构
执行事件包含完整的执行上下文信息：
```typescript
Session{selectedEvent.session_id}
Observed{formatTimestamp(selectedEvent.observed_at)}
Lane{eventLane(selectedEvent)}
```
| 字段 | 类型 | 说明 |
|-----|------|-----|
| session_id | string | 所属会话标识 |
| observed_at | timestamp | 事件观察时间 |
| capability_name | string | 执行能力名称 |
| action_kind | string | 执行动作类型 |
| event_kind | string | 事件种类 |
| lane | string | 所属车道标识 |
### 详情展示
```typescript
{payload.args_preview ? (
Arguments
{detailValue(payload.args_preview)}
) : null}
```
资料来源：[ExecutionPage.tsx:20-60]()
## 概览页面集成
### 上下文预算监控
Conductor与上下文管理集成，提供预算监控功能：
```typescript
Context Budget
Status{contextBudget?.status ?? contextBudget?.reason}
Estimated tokens{contextBudget?.estimated_tokens?.toLocaleString()}
Journal entries{contextBudget?.journal_entries ?? 0}
```
| 指标 | 说明 |
|-----|------|
| status | 上下文预算状态 |
| estimated_tokens | 预估Token消耗 |
| journal_entries | 日志条目数量 |
### 最近执行展示
```typescript
{snapshot.execution.recent.slice(0, 6).map((event) => (
{event.capability_name ?? event.event_kind}
{event.action_kind ?? event.event_kind}
))}
```
资料来源：[OverviewPage.tsx:1-50]()
## 总结
Conductor调度系统是AIDOCS框架中实现智能任务编排的核心引擎，通过多角色协作、车道机制和灵活的路由策略，使AI代理能够高效协同处理复杂任务。系统采用前后端分离架构，前端提供直观的可视化界面，后端通过Python服务实现核心调度逻辑，并通过MCP协议与各类AI后端集成。
主要特性包括：
- **分层角色系统**：King、Conductor、Co-Conductor形成清晰的职责层级
- **Lane驱动执行**：基于依赖的车道模型确保任务正确排序
- **多后端支持**：统一接口支持Claude、Codex、OpenCode等多种AI后端
- **实时状态追踪**：完善的执行事件记录和进度可视化
- **配置灵活性**：可定制的路由规则和模型参数
---
## 安全门控系统
### 相关页面
相关主题：[系统架构](#system-architecture), [宿主代理集成](#host-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/server/aidocs_mcp/access_gate.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/access_gate.py)
- [mcp/server/aidocs_mcp/heuristic_judge.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/heuristic_judge.py)
- [mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)
- [mcp/server/aidocs_mcp/rbac.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/rbac.py)
- [mcp/server/aidocs_mcp/tool_policy.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_policy.py)
- [mcp/server/aidocs_mcp/enforcement_pkg/controller.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/enforcement_pkg/controller.py)
# 安全门控系统
## 概述
AIDOCS 安全门控系统是保护 AI 编码代理安全运行的核心组件，它通过多层防护机制控制代理对系统资源的访问权限。该系统旨在防止代理意外或恶意修改敏感文件、执行危险命令，以及遭受提示词注入攻击。
安全门控系统采用分层架构设计，从文件访问控制、工具策略执行、输出内容审查到基于角色的权限管理，形成完整的防御体系。资料来源：[access_gate.py:1-50]()
## 系统架构
### 组件层次
安全门控系统由以下核心组件构成：
```mermaid
graph TD
subgraph "访问控制层"
AG[access_gate.py
访问门控]
RB[rbac.py
RBAC权限控制]
end
subgraph "策略执行层"
TP[tool_policy.py
工具策略]
EN[controller.py
执行控制器]
end
subgraph "内容审查层"
OG[output_guard.py
输出守卫]
HJ[heuristic_judge.py
启发式判断]
end
AG --> RB
TP --> EN
EN --> AG
OG --> HJ
```
### 门控决策流程
```mermaid
graph TD
A[请求进入门控] --> B{请求类型}
B -->|读取| C[check_read]
B -->|编辑| D[check_edit
层级1检查]
B -->|写入| E[check_write
层级2-4检查]
C --> F{路径检查}
F -->|全局引导文件| G[BLOCK
Tier0拒绝]
F -->|敏感文件| H[BLOCK
敏感文件保护]
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 是安全门控系统的核心模块，负责对文件操作进行细粒度控制。
#### 门控决策数据结构
```python
class GateDecision:
allowed: bool # 是否允许操作
level: str # 门控层级标识
reason: str # 决策原因说明
```
#### 门控层级定义
| 层级 | 名称 | 描述 | 优先级 |
|------|------|------|--------|
| 0 | global_bootstrap_tier0 | 全局引导文件保护 | 最高 |
| 1 | sensitive_file_protection | 敏感文件保护 | 高 |
| 2 | edit_gate | 编辑门控 | 中 |
| 3 | write_gate | 写入门控 | 中 |
| 4 | capability_gate | 能力声明门控 | 中低 |
资料来源：[access_gate.py:30-80]()
#### 关键检查函数
**check_edit()** - 层级1编辑检查
```python
@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写入检查
```python
@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 负责检测和过滤代理输出中的潜在威胁内容。
#### 守卫模式分类
**提示词注入检测模式**
| 类别 | 正则表达式 | 威胁描述 |
|------|-----------|----------|
| system_override | `ignore\|forget\|disregard.*(?:previous\|prior\|above)` | 系统指令覆盖尝试 |
| role_hijack | `you\s+are\s+now\s+(?:a\s+)?(?:different\|new\|my)` | 角色劫持尝试 |
| instruction_inject | `<\s*(?:system\|instructions?\|prompt)\s*>` | XML标签指令注入 |
| delimiter_escape | ````\s*(?:system\|instructions?)\s*\n` | 代码块指令注入 |
| hidden_instruction | `(?:IMPORTANT\|CRITICAL\|URGENT)\s*:\s*(?:ignore\|override)` | 隐藏指令注入 |
资料来源：[output_guard.py:50-70]()
**敏感内容检测模式**
| 类别 | 正则表达式 | 描述 |
|------|-----------|------|
| env_file_content | `^[A-Z_]{3,}=\S{8,}$` | .env文件内容泄露 |
| ssh_config | `(?:Host\s+\S+\|IdentityFile\s+~/)` | SSH配置内容 |
资料来源：[output_guard.py:75-80]()
#### 扫描与脱敏
```python
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 定义了工具执行的策略规则，包括允许列表、拒绝列表和气泡策略。
#### 策略动作类型
| 动作 | 描述 |
|------|------|
| allow | 明确允许执行 |
| deny | 明确拒绝执行 |
| bubble | 气泡到上一层级决定 |
#### Shell策略管理
```mermaid
graph LR
subgraph "BashPolicyPanel"
PI[策略信息]
SC[搜索/过滤]
RB[规则列表]
end
PI -->|显示统计| SA[允许数/拒绝数/气泡数]
SC -->|筛选| RB
RB -->|应用| CT[当前活动层级配置]
```
资料来源：[BashPolicyPanel.tsx:1-50]()
### RBAC权限控制 (rbac.py)
RBAC模块实现了基于角色的访问控制，为不同类型的代理和用户分配不同的权限级别。
#### 权限层级
```mermaid
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 通过启发式规则评估代理请求的风险级别，辅助门控决策。
#### 风险评估维度
| 维度 | 评估方法 | 风险级别 |
|------|----------|----------|
| supply_chain | 包管理器命令检测 | critical/medium/low |
| capability | 能力声明检测 | high/medium/low |
| file_operation | 文件系统操作检测 | high/medium/low |
| network | 网络请求检测 | high/medium/low |
资料来源：[skill_scanner.py:40-70]()
### 执行控制器 (enforcement_pkg/controller.py)
controller.py 是安全策略的执行中枢，协调各组件的协作。
```python
class EnforcementController:
"""执行控制器 - 协调所有安全检查"""
def check_request(self, request: Request) -> EnforcementResult:
# 1. RBAC权限检查
# 2. 工具策略检查
# 3. 访问门控检查
# 4. 内容审查
# 5. 汇总决策
```
资料来源：[controller.py:1-40]()
## 配置管理
### TOML配置文件
AIDOCS通过TOML文件管理安全配置，支持多层级配置覆盖。
```toml
# 配置文件结构示例
[gate_messages]
# 操作钩子配置
[language_descriptors]
# 语言描述符配置
[security]
allow_config_edit = false
enforce = true
```
资料来源：[TomlConfigsPage.tsx:1-30]()
### 安全设置面板
安全相关配置可通过Dashboard界面管理：
| 设置项 | 说明 | 风险等级 |
|--------|------|----------|
| dev.dev_mode | 允许编辑AIDOCS MCP服务端源码 | 高 |
| security.allow_config_edit | 允许代理修改配置 | 高 |
| security.enforce | 启用工具门控 | 中 |
资料来源：[dashboardModals.tsx:1-20]()
## 危险操作确认
对于高风险操作，系统会弹出确认对话框：
```mermaid
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]()
### 确认对话框警告文本
| 配置项 | 警告内容 |
|--------|----------|
| dev.dev_mode | 启用后允许编辑AIDOCS MCP服务端源文件。仅在开发AIDOCS时使用。 |
| security.allow_config_edit | 允许代理通过工具调用修改AIDOCS配置。代理可以更改门控设置、conductor配置和其他项目设置。 |
| security.enforce | 禁用工具门控将移除bash允许列表、原始工具阻止和破坏性命令保护。代理可以自由使用任何工具。 |
资料来源：[dashboardModals.tsx:25-30]()
## 状态监控
### MCP连接状态
Dashboard底部状态栏显示MCP连接状态：
```tsx
MCP connected
```
| 状态 | 颜色 | 含义 |
|------|------|------|
| 已连接 | 绿色 | MCP服务器正常运行 |
| 断开 | 红色 | MCP连接异常 |
资料来源：[CastleShell.tsx:1-30]()
### 运行时快照
```tsx
export function LoadingOverlay() {
return (
Loading runtime snapshot
Refreshing project, session, and settings state.
);
}
```
资料来源：[dashboardModals.tsx:50-65]()
## 工作流程示例
### 文件编辑请求流程
```mermaid
graph TD
A[代理请求编辑文件] --> B{是否为全局引导文件?}
B -->|是| C[直接拒绝
Tier0保护]
B -->|否| D{是否为敏感文件?}
D -->|是| E[拒绝
敏感文件保护]
D -->|否| F{是否启用dev_mode?}
F -->|是| G{has_intent标志}
G -->|true| H[允许编辑]
G -->|false| I[拒绝]
F -->|否| J[检查配置文件规则]
J -->|允许| K[允许写入]
J -->|拒绝| L[拒绝]
```
### 提示词注入检测流程
```mermaid
graph TD
A[代理输出文本] --> B{检查system_override模式}
B -->|匹配| C[标记为注入
记录日志]
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` 启用状态
### 安全审查要点
| 检查项 | 频率 | 负责角色 |
|--------|------|----------|
| 门控日志审查 | 每日 | 安全管理员 |
| 敏感文件列表更新 | 每周 | 运维人员 |
| RBAC权限审计 | 每月 | 管理员 |
| TOML配置一致性检查 | 每次部署前 | 开发人员 |
### 异常处理
当门控拒绝操作时，系统会返回详细的原因信息：
```
GateDecision(
allowed=False,
level="sensitive_file_protection",
reason="敏感文件被阻止: {path}"
)
```
开发者应捕获这些响应并向用户呈现友好的错误信息。
## 总结
AIDOCS安全门控系统通过多层次、细粒度的防护机制，为AI编码代理提供了全面的安全保障。系统从访问控制、策略执行、内容审查到权限管理等多个维度构建防御体系，有效防止了误操作、恶意攻击和敏感信息泄露等安全风险。理解并正确配置安全门控系统是确保AIDOCS稳定、安全运行的关键。
---
## 数据存储与索引
### 相关页面
相关主题：[持久化记忆系统](#persistent-memory), [MCP运行时](#mcp-runtime)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/server/aidocs_mcp/memory_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/memory_store.py)
- [mcp/server/aidocs_mcp/config_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_store.py)
- [mcp/server/aidocs_mcp/session_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/session_store.py)
- [mcp/server/aidocs_mcp/code_index_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/code_index_store.py)
- [mcp/server/aidocs_mcp/project_registry_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/project_registry_service.py)
- [mcp/server/aidocs_mcp/aidocs_managed_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/aidocs_managed_store.py)
# 数据存储与索引
AIDOCS 的数据存储与索引系统是整个项目持久化层的核心，负责管理项目配置、会话状态、代码索引和运行时快照。该系统采用多层次存储架构，以文件系统为主体、SQLite 为索引引擎，支持项目级别的内存管理和会话感知的上下文检索。
## 存储架构总览
AIDOCS 的存储架构由多个独立的存储模块组成，每个模块负责特定的数据域。整个系统遵循"文件是唯一真相来源"（Files remain the only source of truth）的核心原则，所有索引都是派生的、可从源文件重建的。
```mermaid
graph TD
A[项目根目录] --> B[aidocs.toml]
A --> C[.MEMORY/]
A --> D[.aidocs/]
B --> E[ConfigStore
配置存储]
C --> F[SessionStore
会话存储]
C --> G[MemoryStore
内存文档存储]
D --> H[CodeIndexStore
代码索引存储]
E --> I[SQLite: aidocs_config.db]
F --> I
G --> I
H --> I
I --> J[派生索引]
J --> K[代码符号索引]
J --> L[语义搜索索引]
```
资料来源：[README.md](https://github.com/cristian1991/AIDOCS/blob/main/README.md)
## 核心存储模块
### ConfigStore（配置存储）
`ConfigStore` 负责管理项目级配置文件 `aidocs.toml` 的读取、验证和写入。该模块维护配置项的当前值、默认值，并支持配置变更的历史追踪。
配置存储采用 TOML 格式，主要配置域包括：
| 配置域 | 说明 | 持久化位置 |
|--------|------|-----------|
| `security` | 安全策略配置 | `aidocs.toml` |
| `dev` | 开发模式配置 | `aidocs.toml` |
| `languages` | 索引语言配置 | `aidocs.toml` |
| `mcp` | MCP 服务器配置 | `aidocs.toml` |
配置项具有以下属性结构：
- **path**: 配置项的 TOML 路径（如 `security.enforce`）
- **kind**: 配置值类型（布尔、字符串、数组等）
- **default_value**: 系统默认值
- **current_value**: 当前活跃值
- **scope**: 作用范围（全局或会话级别）
资料来源：[mcp/server/aidocs_mcp/config_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/config_store.py)
### SessionStore（会话存储）
`SessionStore` 管理会话生命周期和会话相关的数据持久化。每个 AI 编码会话在启动时创建唯一标识符，用于关联该会话产生的所有上下文和操作记录。
会话存储的关键职责：
1. **会话创建与标识**: 生成会话 ID，建立会话与项目的绑定关系
2. **上下文快照**: 定期保存会话状态快照，支持会话恢复
3. **会话元数据**: 记录会话起始时间、最近活动时间、关联的代码文件列表
4. **会话清理**: 管理过期会话的清理策略
```mermaid
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](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/session_store.py)
### MemoryStore（内存文档存储）
`MemoryStore` 是 AIDOCS 的核心文档存储模块，负责管理 `.MEMORY/` 目录下的所有持久化文档。这些文档构成了 AI 代理的"持久记忆"，包括项目不变式、架构决策、工作流程规则等。
#### 文档分类体系
AIDOCS 定义了严格的文档分类体系，每种类型对应特定的存储位置：
| 文档类型 | 存储位置 | 用途说明 |
|----------|----------|----------|
| `invariant` | `.MEMORY/rules/` | 项目不变式和必须遵守的规则 |
| `infrastructure` | `.MEMORY/plans/` | 基础设施配置和架构决策 |
| `preference` | `.MEMORY/rules/` | 代码风格偏好和约定 |
| `caveat` | `.MEMORY/rules/` | 注意事项和已知的坑点 |
| `phase` | `.MEMORY/plans/` | 阶段跟踪和进度文档 |
资料来源：[mcp/server/aidocs_mcp/memory_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/memory_store.py)
#### 保留文件名规则
系统强制执行保留文件名规则，防止文档被错误放置：
```python
_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/",
}
```
#### 内容模式检测
系统包含内容模式检测器，用于识别可能被错误分类的文档：
| 模式 | 正则表达式 | 触发条件 |
|------|------------|----------|
| 标题模式 | `#\{1,3\}` | 文档包含 H1-H3 标题 |
| 计划模式 | `plan` 关键词 | 内容看起来像计划 |
| Bug 报告模式 | `bug` 关键词 | 内容像是 bug 报告 |
资料来源：[mcp/server/aidocs_mcp/memory_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/memory_store.py)
### CodeIndexStore（代码索引存储）
`CodeIndexStore` 负责构建和维护代码库的符号索引，支持语义搜索、符号查找和代码导航。索引数据存储在 SQLite 数据库中，是完全派生的——可以从源代码随时重建。
#### 索引类型
| 索引类型 | 用途 | 数据来源 |
|----------|------|----------|
| 符号索引 | 类、函数、变量定义位置 | AST 解析 |
| 引用索引 | 符号被引用的位置 | 静态分析 |
| 文本索引 | 全文搜索 | 分词和倒排索引 |
| 依赖索引 | 模块间依赖关系 | 导入语句解析 |
#### 索引触发器
代码索引在以下事件发生时触发重建：
1. **项目初始化**: 首次启用 AIDOCS 时执行全量索引
2. **显式同步**: 调用 `project_sync_indexes` 方法
3. **增量更新**: 检测到文件变更时更新相关索引条目
索引重建采用增量策略，仅重新索引变更的文件及其依赖项，以优化大规模项目的性能。
资料来源：[mcp/server/aidocs_mcp/code_index_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/code_index_store.py)
## 项目注册服务
`ProjectRegistryService` 维护系统中所有已初始化 AIDOCS 的项目列表。该服务跟踪每个项目的根路径、初始化时间、最后访问时间和运行时状态。
### 项目元数据结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `project_root` | Path | 项目根目录路径 |
| `project_name` | String | 项目显示名称 |
| `initialized_at` | DateTime | 初始化时间戳 |
| `last_accessed` | DateTime | 最后访问时间 |
| `session_count` | Integer | 关联的会话数量 |
| `index_status` | Enum | 索引状态（同步中、已同步、需重建） |
### 注册表持久化
项目注册表存储在全局配置目录下的 SQLite 数据库中，与单个项目的 `.MEMORY/` 目录分离，确保即使项目目录被删除，注册信息仍可查询。
```mermaid
graph TD
A[全局注册表
~/.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](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/project_registry_service.py)
## 托管存储（Managed Store）
`aidocs_managed_store.py` 实现 AIDOCS 的托管模式存储逻辑。托管模式是 AIDOCS 的核心安全特性，在该模式下，系统对文件操作实施严格的访问控制。
### 托管模式架构
```mermaid
graph TD
A[文件操作请求] --> B{托管模式启用?}
B -->|否| C[允许直接访问]
B -->|是| D[Gate 检查链]
D --> E[Level 1: Managed Mode
阻止原始文件工具]
E --> F[Level 2: Infrastructure
阻止 aidocs.toml 写入]
F --> G[Level 3: Sensitive Files
阻止凭证文件访问]
G --> H[Level 4: Memory Path
.MEMORY 读写策略]
H --> I[Level 5: Read Gate
按文件发现权限]
I --> J[Level 6: Edit Gate
需要先读取/发现]
J -->|通过| K[允许操作]
J -->|拒绝| L[阻止操作
返回原因]
C --> K
```
### 存储策略
托管存储支持多种读写策略：
| 策略 | 说明 | 使用场景 |
|------|------|----------|
| `strict` | 所有写入必须通过 AIDOCS 接口 | 高安全要求环境 |
| `relaxed` | 允许直接文件操作 | 开发调试模式 |
| `audit` | 允许直接操作但记录所有变更 | 合规审计 |
资料来源：[mcp/server/aidocs_mcp/aidocs_managed_store.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/aidocs_managed_store.py)
## 运行时快照
运行时快照是 AIDOCS 在特定时刻捕获的项目状态记录，用于支持会话恢复和状态回溯。
### 快照内容
| 组件 | 说明 |
|------|------|
| 项目配置 | aidocs.toml 的完整解析 |
| 活跃会话 | 当前会话的上下文摘要 |
| 索引状态 | 最后一次索引同步的状态 |
| 变更历史 | 最近的文件变更记录 |
### 快照存储
快照数据存储在以下位置：
- **项目级**: `.aidocs/snapshots/{timestamp}.json`
- **全局缓存**: `~/.aidocs/cache/snapshots/`
Dashboard 应用通过 Tauri 后端读取和显示运行时快照，刷新时显示加载动画，提示用户正在同步项目、会话和设置状态。
资料来源：[apps/aidocs-dashboard/src-tauri/src/main.rs](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src-tauri/src/main.rs)
## 索引同步方法
MCP 服务器提供以下方法用于索引管理：
### project_sync_indexes
```python
def project_sync_indexes(project_root: Path, include_tests: bool = False) -> dict
```
**参数说明：**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `project_root` | Path | 必需 | 项目根目录 |
| `include_tests` | bool | False | 是否包含测试文件索引 |
**返回值：**
```python
{
"memory_index_sync_result": {...},
"code_manifest_sync_result": {...}
}
```
### project_check
运行项目结构检查，验证 AIDOCS 初始化完整性。
**返回值：**
| 字段 | 类型 | 说明 |
|------|------|------|
| `mode` | string | 检查模式 |
| `project_root` | string | 项目路径 |
| `exit_code` | int | 退出码 |
| `stdout` | string | 标准输出 |
| `stderr` | string | 错误输出 |
| `ok` | bool | 检查是否通过 |
资料来源：[mcp/server/METHODS.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/METHODS.md)
## TOML 配置文档管理
Dashboard 提供 TOML 配置文档的可视化浏览和管理界面，支持按类别筛选和快速切换。
### 配置文件分类
| 类别 | 路径前缀 | 说明 |
|------|----------|------|
| Project config | `aidocs.toml` | 项目主配置 |
| Intent tokens | `intent_tokens/` | 意图分类语言文件 |
| Workflow hooks | `gate_messages/` | 工作流钩子消息 |
| Index descriptors | `mcp/server/aidocs_mcp/index_languages/` | 语言索引描述符 |
| Session overrides | `.MEMORY/sessions/` | 会话级别的配置覆盖 |
### 配置文档显示
配置文档页面使用扁平表格布局，每行显示：
- **Target**: 配置目标名称
- **Active**: 激活状态（开关形式）
- **Context**: 上下文信息
资料来源：[apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)
## 安全与权限
AIDOCS 的存储系统集成了多层安全机制：
### 敏感文件保护
系统自动阻止对以下文件的读写操作：
- `.env` 文件
- 凭证文件
- API 密钥存储
- 其他安全敏感配置
### 配置变更确认
修改特定配置项时需要用户确认：
| 配置项 | 风险说明 |
|--------|----------|
| `dev.dev_mode` | 允许编辑 AIDOCS MCP 服务器源文件 |
| `security.allow_config_edit` | 允许代理通过工具调用修改配置 |
| `security.enforce` | 禁用工具门控，移除所有安全限制 |
资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)
## 总结
AIDOCS 的数据存储与索引系统采用模块化设计，通过清晰的职责划分实现了高效的状态管理和安全的访问控制：
- **ConfigStore** 集中管理项目配置
- **SessionStore** 维护会话生命周期
- **MemoryStore** 组织项目记忆文档
- **CodeIndexStore** 提供快速的代码检索能力
- **ProjectRegistryService** 追踪全局项目状态
- **ManagedStore** 实施安全策略
整个系统的设计哲学是"文件即真相"，所有派生数据都可以从源文件重建，确保了系统的可靠性和可恢复性。
---
## MCP运行时
### 相关页面
相关主题：[系统架构](#system-architecture), [MCP工具集](#mcp-tools), [宿主代理集成](#host-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/server/aidocs_mcp/mcp_server.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/mcp_server.py)
- [mcp/server/aidocs_mcp/tool_discovery.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/tool_discovery.py)
- [mcp/server/aidocs_mcp/cli.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/cli.py)
- [mcp/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/README.md)
- [mcp/server/README.md](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/README.md)
- [mcp/server/aidocs_mcp/runtime_prompt_handling_service.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/runtime_prompt_handling_service.py)
- [mcp/server/aidocs_mcp/server_code_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_tools.py)
# MCP运行时
## 概述
MCP运行时（MCP Runtime）是AIDOCS项目的核心组件，为AI编码代理提供持久化记忆、索引检索和工作流编排能力。它作为Model Context Protocol（MCP）服务器运行，使AI代理能够在项目中恢复工作，而无需每次重新探索代码库。
MCP运行时的核心职责包括：
- **工具发现与注册**：自动扫描项目中的MCP服务器和服务
- **代码理解与检索**：提供符号搜索、依赖分析、上下文聚合等能力
- **安全门控**：6级级联安全机制，控制工具使用权限
- **会话管理**：维护代理会话状态和记忆持久化
资料来源：[mcp/README.md]()
## 架构概览
```mermaid
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调用：
| 工具类别 | 功能 | 示例 |
|---------|------|------|
| 记忆检索 | `aidocs_bundle`, `aidocs_find`, `aidocs_investigate` | 上下文聚合、符号搜索、概念调查 |
| 代码读取 | `aidocs_get_lines`, `aidocs_get_symbol_snippet` | 按行号或符号名读取代码 |
| 代码编辑 | `aidocs_str_replace`, `aidocs_edit_lines`, `aidocs_batch_edit` | 单点编辑、范围重写、批量原子编辑 |
| 会话管理 | `aidocs_task_begin`, `aidocs_task_complete`, `aidocs_task_update` | 任务生命周期管理 |
| 数据库查询 | `aidocs_schema_query` | 数据库结构查询 |
资料来源：[mcp/server/aidocs_mcp/mcp_server.py]()
### 工具发现系统
`tool_discovery.py` 负责自动扫描和注册项目中可用的MCP服务器：
```mermaid
graph LR
Scan[扫描目录] --> Parse[解析配置]
Parse --> Register[注册工具]
Register --> Expose[暴露给AI]
```
支持发现的服务类型包括：
- 本地MCP服务器
- NPM包中的服务器
- Python包中的服务器
- STDIO传输的服务器
资料来源：[mcp/server/aidocs_mcp/tool_discovery.py]()
### 代码工具集
`server_code_tools.py` 实现代码理解和检索的核心功能：
| 模式 | 功能 | 说明 |
|-----|------|------|
| `dependency` | 依赖聚合 | 获取符号的依赖树 |
| `partial` | 部分聚合 | 获取部分依赖 |
| `symbol` | 符号聚合 | 获取特定符号的上下文 |
| `style` | 样式聚合 | 获取CSS类相关的代码 |
| `session` | 会话聚合 | 获取会话导向的上下文 |
| `context` | 上下文聚合 | 获取通用上下文 |
| `preset` | 预设聚合 | 预定义的聚合模板 |
```python
# 使用示例
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级级联安全门控机制，**首次匹配优先**：
| 级别 | 门控名称 | 动作 | 说明 |
|-----|---------|------|------|
| 1 | Managed Mode | 阻止原始文件工具 | 托管模式下阻止未受控的文件操作 |
| 2 | Infrastructure | 阻止写入 | 保护 `aidocs.toml`、`aidocs_mcp/*` |
| 3 | Sensitive Files | 阻止访问 | 保护 `.env`、凭证、密钥文件 |
| 4 | Memory Path | 读写分离 | `.MEMORY/` 读取自由，工作流写入需意图确认 |
| 5 | Read Gate | 文件级发现 | 按文件发现，支持 `known_exact_path` 绕过 |
| 6 | Edit Gate | 编辑控制 | 要求先读取/发现目标 |
资料来源：[mcp/README.md]()
### 风险模式检测
`skill_scanner.py` 包含技能和风险模式检测：
```python
# 供应链风险模式
_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代理的提示词路由：
```mermaid
graph TD
Prompt[接收提示词] --> Classify[分类动作类型]
Classify --> Route{路由决策}
Route -->|需要AIDOCS入口| Entry[/aidocs入口流程]
Route -->|已阻止| Blocked[返回阻止原因]
Route -->|可处理| Handled[执行托管处理]
Entry --> Handled
Handled --> Report[生成报告]
```
### 处理模式
| 模式 | 说明 | 返回字段 |
|-----|------|---------|
| `requires_aidocs_entry` | 需要 `/aidocs` 入口 | `report`, `next_step` |
| `blocked` | 被安全机制阻止 | `blocked_reason`, `recommended_mcp_flow` |
| `handled` | 已成功处理 | `mode`, `handled`, `classification` |
资料来源：[mcp/server/aidocs_mcp/runtime_prompt_handling_service.py]()
## CLI命令行接口
`cli.py` 提供命令行交互能力：
```bash
# 安装后可用命令
aidocs setup # 配置MCP、钩子、项目初始化
aidocs doctor # 验证安装状态
```
### 安装选项
| 安装方式 | 命令 |
|---------|------|
| 基础安装 | `pip install aidocs-mcp` |
| 开发模式 | `pip install aidocs-mcp[dev]` |
| AST解析 | `pip install aidocs-mcp[ast]` |
| 全功能 | `pip install -e ".[dev,ast]"` |
资料来源：[mcp/server/aidocs_mcp/cli.py](), [mcp/README.md]()
## 记忆模型
在初始化项目中，记忆存储在 `/.MEMORY/` 目录：
```
/.MEMORY/
.aidocs/index.aidocs # 会话启动路由器
plans/ # 计划文档
roadmaps/ # 路标文档
archive/ # 归档内容
```
### 保留文件名规则
为防止错误分类，系统定义了保留文件名规范：
| 文件名 | 正确位置 | 说明 |
|-------|---------|------|
| `plans.md` | `.MEMORY/plans/` | 仅限计划目录 |
| `roadmap.md` | `.MEMORY/roadmaps/` | 仅限路标目录 |
| `bugs.md` | 不属于记忆系统 | 应使用问题跟踪器 |
资料来源：[mcp/server/aidocs_mcp/memory_store.py]()
## 总结
MCP运行时是AIDOCS项目的技术核心，它通过：
1. **标准化工具接口** - MCP协议提供统一的AI-代码交互方式
2. **智能记忆检索** - 多模式上下文聚合，按会话引导
3. **分层安全防护** - 6级门控确保AI操作安全可控
4. **自动化配置** - 一键安装，自动发现和注册服务
这套架构使AI编码代理能够持久化工作记忆，在复杂项目中保持上下文连贯性，同时通过安全门控防止误操作。
---
## MCP工具集
### 相关页面
相关主题：[MCP运行时](#mcp-runtime), [系统架构](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [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)
- [mcp/server/aidocs_mcp/server_code_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_code_tools.py)
- [mcp/server/aidocs_mcp/server_memory_index_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_memory_index_tools.py)
- [mcp/server/aidocs_mcp/server_project_admin_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_project_admin_tools.py)
- [mcp/server/aidocs_mcp/server_run_tools.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/server_run_tools.py)
- [mcp/server/aidocs_mcp/skill_scanner.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/skill_scanner.py)
- [mcp/server/aidocs_mcp/output_guard.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/output_guard.py)
- [mcp/server/aidocs_mcp/claude_hook.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/claude_hook.py)
# MCP工具集
## 概述
AIDOCS的MCP（Model Context Protocol）工具集是整个系统的核心组件，为AI编码代理提供持久化记忆、索引检索和编排能力。这些工具通过MCP协议暴露给AI代理，使其能够执行代码编辑、文件检索、项目管理、Shell命令执行以及安全审计等操作。
MCP工具集采用模块化架构设计，将不同功能域分离为独立的服务模块：
| 模块名称 | 功能域 | 主要职责 |
|---------|-------|---------|
| `server_code_edit_tools` | 代码编辑 | 文件创建、字符串替换、批量编辑 |
| `server_code_tools` | 代码读取 | 符号检索、行号读取、代码片段获取 |
| `server_memory_index_tools` | 索引管理 | 上下文索引、符号索引、架构查询 |
| `server_project_admin_tools` | 项目管理 | 配置管理、层叠设置、权限控制 |
| `server_run_tools` | 命令执行 | Shell命令、进程管理、管道守卫 |
| `skill_scanner` | 安全审计 | 风险模式识别、供应链检测 |
| `output_guard` | 内容守卫 | 敏感信息过滤、注入检测 |
## 架构设计
```mermaid
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`模块负责处理所有文件修改操作，提供细粒度的代码编辑能力。
### 核心工具函数
| 工具名称 | 功能描述 | 参数说明 |
|---------|---------|---------|
| `code_str_replace` | 精确字符串替换 | `old`: 原字符串, `new`: 新字符串, `replace_all`: 是否全部替换 |
| `code_create_file` | 创建新文件 | `path`: 路径, `content`: 内容 |
| `ai_str_replace` | AI辅助字符串替换 | 支持智能匹配和上下文感知 |
| `ai_batch_edit` | 批量原子编辑 | 最多支持20个编辑操作 |
### 工作流程
```mermaid
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]()
```python
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的持久化记忆系统，提供代码结构索引和语义检索能力。
### 索引模式
| 模式 | 说明 | 用途 |
|-----|------|-----|
| `file` | 单文件结构 | 快速获取文件概览 |
| `context` | 会话上下文 | 基于当前会话的上下文检索 |
| `subsystem` | 子系统视图 | 理解模块间关系 |
| `symbols` | 符号索引 | 查找类、方法、枚举等 |
### 检索工具链
工具提供了一套递进式检索流程：
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`实现了多层次的风险模式识别系统，将风险分为四大类别：
| 风险类别 | 风险等级 | 示例模式 |
|---------|---------|---------|
| 供应链风险 | high/critical | 远程URL下载、Shell管道执行 |
| 能力声明风险 | high/medium | 文件系统操作、命令执行声明 |
| 内容注入风险 | high/medium | Base64引用、十六进制编码内容 |
| 敏感内容泄露 | high | .env文件内容、SSH配置 |
#### 供应链风险模式
```python
_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]()
#### 能力声明风险模式
```python
_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注入检测
```python
_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")), # 代码块注入
]
```
#### 敏感内容模式
```python
_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策略系统集成，支持命令的允许/拒绝/气泡策略。
### 策略机制
| 策略类型 | 说明 | 优先级 |
|---------|------|-------|
| `allow` | 明确允许的命令 | 最高 |
| `deny` | 明确拒绝的命令 | 次高 |
| `bubble` | 气泡到用户确认 | 中 |
| `default` | 未匹配时的默认行为 | 最低 |
### 执行流程
```mermaid
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使用层叠配置系统，允许不同来源的配置按优先级合并：
| 层名称 | 优先级 | 说明 |
|-------|-------|------|
| `project` | 最高 | 项目本地配置 |
| `user` | 中 | 用户级配置 |
| `default` | 最低 | 系统默认配置 |
### 配置编辑权限
该模块还管理`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]()
---
## 仪表盘前端
### 相关页面
相关主题：[系统架构](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)
- [apps/aidocs-dashboard/src/RegistryPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RegistryPage.tsx)
- [apps/aidocs-dashboard/src/CastleShell.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/CastleShell.tsx)
- [apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)
- [apps/aidocs-dashboard/src/TomlConfigsPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/TomlConfigsPage.tsx)
- [apps/aidocs-dashboard/src/OverviewPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/OverviewPage.tsx)
- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)
- [apps/aidocs-dashboard/src/LaneDetailPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/LaneDetailPanel.tsx)
- [apps/aidocs-dashboard/src/RBACPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/RBACPage.tsx)
- [apps/aidocs-dashboard/src/BashPolicyPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/BashPolicyPanel.tsx)
- [apps/aidocs-dashboard/src/SettingDetailPanel.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SettingDetailPanel.tsx)
- [apps/aidocs-dashboard/index.html](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/index.html)
# 仪表盘前端
## 概述
AIDOCS 仪表盘前端是基于 Tauri + React + TypeScript 构建的桌面应用，为 AI 编码智能体提供项目状态监控、配置管理、工具审计和安全策略可视化界面。
### 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| 框架 | Tauri 2.x | Rust 后端 + Web 前端混合架构 |
| 前端 | React 18 + TypeScript | 组件化 UI 开发 |
| 样式 | Tailwind CSS + 自定义 CSS 变量 | 暗色主题 "Castle" 设计系统 |
| 构建 | Vite | 快速开发与热更新 |
入口文件位于 `apps/aidocs-dashboard/index.html`，根组件挂载到 `#root` 节点。
## 架构设计
### 整体布局结构
```
┌─────────────────────────────────────────────────────────────┐
│ CastleShell (外壳) │
├──────────┬──────────────────────────────────────────────────┤
│ │ │
│ 导航 │ 主内容区域 │
│ 侧边栏 │ (各功能页面组件) │
│ │ │
├──────────┴──────────────────────────────────────────────────┤
│ 状态栏 (Status Bar) │
└─────────────────────────────────────────────────────────────┘
```
### 核心组件层次
```mermaid
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 的初始配置，包含以下步骤：
| 步骤 | 标识 | 功能描述 |
|------|------|----------|
| 欢迎页 | `welcome` | 介绍 AIDOCS 功能，入口按钮 |
| 项目选择 | `project` | 选择启用 AIDOCS 的项目文件夹 |
| 环境检测 | `env` | 检测 Node.js、主机服务（Claude/OpenAI）等 |
| 配置中 | `configure` | 执行 MCP、hooks、项目结构初始化 |
| 完成 | `done` | 显示配置结果和后续操作指引 |
资料来源：[SetupWizardPage.tsx:1-150]()
#### 进度指示器
```tsx
{SETUP_STEPS.map((s, i) => (
))}
Capability
Action
Observed
{snapshot.execution.recent.slice(0, 6).map((event) => (
{event.capability_name ?? event.event_kind}
{event.action_kind ?? event.event_kind}
))}
```
显示最近 6 条执行事件，每条包含能力名称、操作类型和观察时间戳。
资料来源：[OverviewPage.tsx:1-50]()
### 3. Conductor 页面 (ConductorPage)
Conductor 页面是工具调用审计的核心界面，提供以下功能：
#### 功能特性
- **Lane 可视化**：展示 conductor lanes 和阻塞原因
- **工具调用详情**：查看每次工具调用的 payload 和 diff
- **路由审计**：记录工具路由决策过程
#### 组件 Props
| 属性 | 类型 | 说明 |
|------|------|------|
| `progressPercent` | `number` | 进度百分比 |
| `conductorLanes` | `Lane[]` | conductor lanes 数组 |
| `runnableLaneIds` | `string[]` | 可运行的 lane ID 列表 |
| `blockedReasons` | `Record` | 阻塞原因映射 |
| `recentExecution` | `ExecutionEvent[]` | 最近执行事件 |
| `configEntries` | `ConfigEntry[]` | 配置项列表 |
| `selectedSessionId` | `string` | 选中的会话 ID |
| `projectRoot` | `string` | 项目根路径 |
| `sessionId` | `string` | 当前会话 ID |
#### 工具调用详情模态框
当用户选择某次工具调用事件时，显示详细信息：
```tsx
Action
{selectedEvent.action_kind ?? selectedEvent.event_kind}
```
支持 `old_str`/`new_str` 或 `old_content`/`new_content` 两种 payload 结构。
资料来源：[ConductorPage.tsx:1-100]()
### 4. 导航外壳 (CastleShell)
CastleShell 是仪表盘的主布局组件，负责：
- 侧边导航栏
- 顶部导航条
- 上下文轨道（Context Rail）
- 状态栏
#### 导航项类型
```tsx
type NavKey = "overview" | "conductor" | "live" | "configs" |
"bash_policy" | "rbac" | "registry" | "settings" | "wizard";
```
#### 状态栏组件
```tsx
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`（一次性）权限
- 显示权限的创建时间和过期时间
#### 状态显示
| 状态 | CSS 类 | 说明 |
|------|--------|------|
| `sticky` | `rbac-state-sticky` | 持久权限，会话间保留 |
| `once` | `rbac-state-once` | 一次性权限，单次使用后失效 |
```tsx
{e.sticky ? (
sticky
) : (
once
)}
```
资料来源：[RBACPage.tsx:1-80]()
### 6. Bash 策略面板 (BashPolicyPanel)
Bash 策略面板管理 shell 命令的允许/拒绝规则。
#### 策略统计
| 统计项 | 说明 |
|--------|------|
| `allowEff` | 允许的命令数 |
| `denyEff` | 拒绝的命令数 |
| `bubbleEff` | 冒泡处理的命令数 |
| `modifiedAtActive` | 在当前活跃层级修改的配置数 |
#### 过滤控件
```tsx
{(["all", "allow", "deny", "bubble", "modified"] as const).map((f) => (
))}
```
支持按名称匹配过滤和按类型过滤两种方式。
资料来源：[BashPolicyPanel.tsx:1-60]()
### 7. TOML 配置页面 (TomlConfigsPage)
TOML 配置页面提供静态配置的可视化管理。
#### 配置分类
| 分类 | 标识 | 说明 |
|------|------|------|
| 工具门控 | `tool_gates` | 工具调用权限控制 |
| Bash 策略 | `bash_policy` | Shell 命令策略 |
| 操作钩子 | `gate_messages` | Action hooks 消息模板 |
| 语言描述符 | `language_descriptors` | 编程语言定义 |
#### 文档表格
```tsx
Target
Active
Context
{filteredDocuments.map((document) => (
))}
```
资料来源：[TomlConfigsPage.tsx:1-80]()
### 8. 注册表页面 (RegistryPage)
注册表页面用于搜索和浏览 MCP 服务器列表。
#### 搜索结果卡片
每个 MCP 服务器卡片显示：
- 服务器名称
- 传输方式 (`transport`)
- 启动命令 (`command`)
- 安装命令（支持多种格式）
```tsx
const installText = typeof firstCmd === "string"
? firstCmd
: typeof firstCmd === "object" && firstCmd
? String((firstCmd as Record).command ?? "")
: "";
```
资料来源：[RegistryPage.tsx:1-50]()
### 9. 设置详情面板 (SettingDetailPanel)
设置详情面板展示单个配置项的完整信息和来源追踪。
#### 功能特性
- 显示配置的当前值、默认值和来源层级
- 支持查看每个叶子节点（leaf）的来源
- 按层级着色的 pill 标签显示
#### 来源追踪表格
```tsx
Per-leaf origin ({Object.keys(entry.origin).length} leaves)
{Object.entries(entry.origin)
.sort(([a], [b]) => a.localeCompare(b))
.map(([leafPath, leafLayer]) => (
| {leafPath} |
{leafLayer}
|
))}
```
资料来源：[SettingDetailPanel.tsx:1-80]()
### 10. 模态组件 (dashboardModals)
#### 安全变更确认模态
当用户尝试修改敏感配置时，显示确认对话框：
```tsx
{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..."}
```
#### 加载遮罩
```tsx
Loading runtime snapshot
Refreshing project, session, and settings state.
```
资料来源：[dashboardModals.tsx:1-80]()
### 11. Lane 详情面板 (LaneDetailPanel)
Lane 详情面板展示特定 lane 的详细信息和关联事件。
#### 事件列表组件
```tsx
{e.capability_name || e.event_kind}
{e.action_kind && (
{e.action_kind}
)}
{e.status}
```
状态颜色映射：
| 状态 | 颜色基调 |
|------|----------|
| `applied`, `allowed` | `ok` (绿色) |
| `refused`, `blocked` | `danger` (红色) |
| 其他 | `muted` (灰色) |
资料来源：[LaneDetailPanel.tsx:1-60]()
## 数据流架构
### 状态管理流程
```mermaid
graph LR
A[仪表盘启动] --> B[加载 Runtime Snapshot]
B --> C[解析项目配置]
C --> D[渲染导航树]
D --> E[按需加载页面数据]
E --> F[WebSocket 实时更新]
F --> G[状态同步到 UI]
```
### API 交互模式
仪表盘通过 Tauri 命令与后端通信：
```tsx
invoke("open_url", { url }).catch(() =>
window.open(url, "_blank", "noopener,noreferrer")
);
```
主要 API 调用包括：
- `open_url`：在浏览器中打开 URL
- 项目配置读写
- 会话状态查询
- 配置变更推送
## 设计系统
### Castle 主题色板
| CSS 变量 | 用途 |
|----------|------|
| `--castle-line` | 边框线颜色 |
| `--castle-mute` | 次要文本颜色 |
| `--castle-allow` | 允许/成功状态 |
| `--castle-deny` | 拒绝/错误状态 |
| `bg-black/25` | 面板背景透明度 |
### 通用样式类
| 类名 | 用途 |
|------|------|
| `flat-table` | 扁平化表格容器 |
| `section-label` | 分区标题标签 |
| `action-button` | 操作按钮基础样式 |
| `toggle` / `toggle is-on` | 开关组件状态 |
## 总结
AIDOCS 仪表盘前端采用组件化架构，通过 CastleShell 提供统一的布局框架，各功能页面（概览、Conductor、配置、权限等）作为子组件按需渲染。状态管理依赖 Tauri 的命令调用和 React 的本地状态，实时更新通过 WebSocket 实现。设计系统采用暗色 "Castle" 主题，提供一致的视觉体验和清晰的状态反馈。
---
## 宿主代理集成
### 相关页面
相关主题：[系统架构](#system-architecture), [MCP运行时](#mcp-runtime), [安全门控系统](#security-gates)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/aidocs-dashboard/src/ConductorPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/ConductorPage.tsx)
- [apps/aidocs-dashboard/src/SetupWizardPage.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/SetupWizardPage.tsx)
- [apps/aidocs-dashboard/src/dashboardModals.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/dashboardModals.tsx)
- [apps/aidocs-dashboard/src/App.tsx](https://github.com/cristian1991/AIDOCS/blob/main/apps/aidocs-dashboard/src/App.tsx)
- [mcp/server/aidocs_mcp/skill_scanner.py](https://github.com/cristian1991/AIDOCS/blob/main/mcp/server/aidocs_mcp/skill_scanner.py)
# 宿主代理集成
AIDOCS 的宿主代理集成（Host Agent Integration）模块是连接 AI 编码代理（如 Claude、Codex）与 AIDOCS 持久化记忆系统的核心桥梁。该模块负责代理身份识别、运行时上下文注入、能力路由配置以及安全策略执行，确保 AI 代理能够在多项目、多会话环境中保持一致的上下文感知能力。
## 系统架构概览
AIDOCS 采用分层架构设计，将宿主代理集成划分为前端展示层、业务编排层和安全策略层三个主要部分。前端展示层负责可视化配置界面，包括 Conductor 页面、设置详情面板和安装向导；业务编排层处理代理路由、能力声明和执行审计；安全策略层则通过能力风险扫描和配置门控确保代理行为安全可控。
```mermaid
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 服务提供商：
| 后端类型 | 说明 | 支持模型 |
|---------|------|---------|
| `claude` | Anthropic Claude 系列 | claude-3-5-sonnet, claude-3-opus 等 |
| `codex` | OpenAI Codex / GPT-4 | gpt-4-turbo, gpt-4o 等 |
| `opencode` | OpenCode 兼容后端 | 自定义部署 |
资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx:conductorDefaults]()
导体配置通过 `configEntries` 数组管理，每个配置项包含路径（path）、当前值（current_value）等属性。配置项的读取采用防御性编程模式，使用可选链和空值合并确保在配置缺失时系统仍能正常运行：
```typescript
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` 的数据结构，其中键为路由标识符，值为路由配置对象。路由状态通过 `useState` 钩子管理，支持动态更新和错误处理：
```typescript
const [routing, setRouting] = useState>({});
const [routingOpen, setRoutingOpen] = useState(false);
const [routingError, setRoutingError] = useState(null);
```
## 能力声明与执行追踪
### 工具调用事件模型
当宿主代理调用工具时，Conductor 页面会记录完整的事件信息。事件数据结构包含能力名称（capability_name）、动作类型（action_kind）、时间戳（observed_at）以及关联的负载信息：
```typescript
interface ToolCallEvent {
event_id: string;
capability_name?: string;
action_kind?: string;
event_kind: string;
observed_at: string;
payload?: Record;
}
```
资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx:toolCallEvent]()
### 差异对比与负载展示
对于包含文本变更的事件，系统提供差异对比视图（DiffViewer）来直观展示旧内容与新内容的变更：
```typescript
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
?
: null
}
```
资料来源：[apps/aidocs-dashboard/src/ConductorPage.tsx:DiffViewer]()
当事件不包含文本差异但有其他负载数据时，系统以 JSON 格式展示完整的负载内容：
```typescript
{!oldText && !newText && payload && Object.keys(payload).length > 0
?
Payload
{JSON.stringify(payload, null, 2)}
: null
}
```
## 能力风险扫描
### 风险模式定义
skill_scanner 模块定义了针对代理能力声明的风险扫描规则。系统通过正则表达式匹配来识别潜在的危险能力声明，并根据严重程度分为 critical、high、medium、low 四个等级：
| 类别 | 严重程度 | 典型模式 | 说明 |
|------|---------|---------|------|
| `capability` | medium | 文件系统操作声明 | read/write/delete file 等 |
| `capability` | high | 命令执行声明 | execute/run/spawn command 等 |
| `capability` | high | 出站数据传输 | send/post/upload data 等 |
| `capability` | critical | 数据库操作 | database 操作声明 |
资料来源：[mcp/server/aidocs_mcp/skill_scanner.py:_CAPABILITY_RISKS]()
### 供应链安全扫描
除能力声明外，skill_scanner 还包含供应链安全相关的扫描规则，用于检测代理脚本中可能存在的供应链攻击风险：
```python
_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 提供了多个与宿主代理集成相关的安全配置项，通过安全确认弹窗进行保护：
| 配置项 | 说明 | 风险提示 |
|-------|------|---------|
| `dev.dev_mode` | 开发者模式 | 允许编辑 AIDOCS MCP 服务器源码 |
| `security.allow_config_edit` | 允许配置编辑 | 允许代理通过工具调用修改配置 |
| `security.enforce` | 强制安全策略 | 禁用后移除 bash 白名单和破坏性命令保护 |
资料来源：[apps/aidocs-dashboard/src/dashboardModals.tsx:SecurityConfirmModal]()
### 安全确认流程
当用户尝试修改敏感配置项时，系统会弹出确认对话框，详细说明变更的潜在风险：
```typescript
export function SecurityConfirmModal({ settingPath, close, confirm }) {
return (
e.stopPropagation()}>
Confirm Security Change
{settingPath}
{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."}
);
}
```
## 安装向导与平台认证
### 主机检测流程
SetupWizardPage 负责引导用户完成 AIDOCS 的初始配置。安装向导会检测系统中已安装的 AI 平台主机，并为未安装的平台提供安装选项：
```typescript
{detectResult.hosts.map((h) => (
{h.found ? (h.authenticated === false ? "!" : "+") : "-"}
{h.name}
{h.found && h.authenticated === false ? " (not signed in)" : ""}
))}
```
资料来源：[apps/aidocs-dashboard/src/SetupWizardPage.tsx:hostDetection]()
### 平台认证流程
对于已安装但未认证的主机，向导提供一键跳转认证功能：
```typescript
```
### 配置完成清单
安装完成后，向导展示详细的配置结果，包括 MCP 配置路径、钩子注册路径以及已安装的平台列表：
```typescript
+
MCP configured
{configResult.mcp_path}
+
Hooks registered
{configResult.hooks_path}
{installResult && installResult.installed.length > 0 && (
+
Installed: {installResult.installed.join(", ")}
)}
```
## 页面懒加载架构
### 动态导入配置
AIDOCS Dashboard 采用 React 的 `lazy` 和 `Suspense` 机制实现页面级代码分割，减少初始加载体积。代理相关的页面组件按需加载：
```typescript
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` 实现，确保导航状态与页面渲染的同步：
```typescript
const [activeNav, setActiveNav] = useState("overview");
const [isLoading, setIsLoading] = useState(false);
const [runtimeSnapshot, setRuntimeSnapshot] = useState(null);
```
## 执行流程图
```mermaid
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 编码代理提供一致的上下文感知能力和安全可控的执行环境。
---
---
## Doramagic 踩坑日志
项目：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