diff --git a/Project/fonrey/客源详情_UI设计.md b/Project/fonrey/客源详情_UI设计.md
new file mode 100644
index 00000000..d9f9706d
--- /dev/null
+++ b/Project/fonrey/客源详情_UI设计.md
@@ -0,0 +1,1743 @@
+# 客源详情页 UI 设计文档
+
+> **版本**：v1.0 · **日期**：2026-04-25
+> **依赖规范**：UI_SYSTEM.md v1.2 · 组件规范设计.md v1.0
+> **PRD 来源**：`Project/fonrey/PRD/客源管理/客源管理模块PRD.md` §5.7 私客详情页
+> **优先级**：P0 功能用 🔴 标注，P1 用 🟡，P2 用 ⚫
+
+---
+
+## 目录
+
+1. [模块概述](#1-模块概述)
+   - 1.1 功能范围
+   - 1.2 页面清单
+   - 1.3 用户角色与权限差异
+2. [页面设计规范](#2-页面设计规范)
+   - 2.1 私客详情页 — 整体框架
+   - 2.2 Section 左侧：需求信息 Tab
+   - 2.3 Section 左侧：跟进记录 Tab
+   - 2.4 Section 左侧：带看 Tab
+   - 2.5 Section 左侧：客源解读 Tab
+   - 2.6 Section 左侧：二手配房 Tab
+   - 2.7 Section 右侧：客源信息概览面板
+   - 2.8 Section 右侧：联系人面板
+   - 2.9 Section 右侧：相关员工面板
+3. [弹窗/抽屉设计规范](#3-弹窗抽屉设计规范)
+   - 3.1 编辑基础信息（Modal）
+   - 3.2 改等级（Modal）
+   - 3.3 改状态（Modal）
+   - 3.4 转成交（Modal）
+   - 3.5 选择成交房源（Modal 宽型）
+   - 3.6 写入跟进（Drawer）
+   - 3.7 新增带看（全页表单）
+   - 3.8 新增预约带看（全页表单）
+4. [交互状态规范](#4-交互状态规范)
+   - 4.1 客源状态机
+   - 4.2 权限控制矩阵
+   - 4.3 HTMX 请求规范
+5. [关键数据字段说明](#5-关键数据字段说明)
+6. [竞品截图对应关系](#6-竞品截图对应关系)
+7. [实现优先级与工期估算](#7-实现优先级与工期估算)
+8. [开放问题（待决策）](#8-开放问题待决策)
+
+---
+
+## 1. 模块概述
+
+### 1.1 功能范围
+
+**P0 功能 🔴**
+- 私客详情页整体框架（左右双栏布局 + Tab 导航）
+- 需求信息查看与编辑
+- 跟进记录（全部/写入跟进/敏感信息跟进/修改跟进/其他跟进）
+- 带看记录（预约带看 + 实际带看）
+- 联系人查看与新增
+- 客源状态变更：改等级、改状态
+- 转公客 / 转成交 / 转无效
+- 右侧客源信息概览面板（基础字段展示 + 快捷操作）
+- 相关员工查看
+
+**P1 功能 🟡**
+- 客源解读（AI 行为分析）
+- 二手配房（录客配房 + 系统配房）
+- 收藏功能
+- 待办提醒模块
+- 编辑基础信息（完整表单）
+
+**P2 功能 ⚫**
+- 编辑信息来源
+- 查看操作日志
+- 名下房产修改
+
+---
+
+### 1.2 页面清单
+
+| 页面名称 | URL 模式建议 | 优先级 | 对应 PRD 章节 |
+|---|---|---|---|
+| 私客详情页（主框架） | `/clients/<client_id>/` | P0 🔴 | §5.7.1 |
+| 需求信息 Tab | `/clients/<client_id>/requirements/` (HTMX partial) | P0 🔴 | §5.7.2 |
+| 跟进记录 Tab | `/clients/<client_id>/follow-logs/` (HTMX partial) | P0 🔴 | §5.7.2 |
+| 带看 Tab | `/clients/<client_id>/viewings/` (HTMX partial) | P0 🔴 | §5.7.2 |
+| 客源解读 Tab | `/clients/<client_id>/insights/` (HTMX partial) | P1 🟡 | §5.7.2 |
+| 二手配房 Tab | `/clients/<client_id>/property-matches/` (HTMX partial) | P1 🟡 | §5.7.2 |
+| 右侧信息面板 | `/clients/<client_id>/sidebar/` (HTMX partial) | P0 🔴 | §5.7.3 |
+| 新增带看（全页） | `/clients/<client_id>/viewings/create/` | P0 🔴 | §5.7.2 |
+| 新增预约带看（全页） | `/clients/<client_id>/viewings/appointment/create/` | P0 🔴 | §5.7.2 |
+
+---
+
+### 1.3 用户角色与权限差异
+
+| 功能/视图元素 | 经纪人（本人） | 经纪人（他人客源） | 店长 | 管理员 |
+|---|---|---|---|---|
+| 查看详情页 | ✅ | 受限（需权限） | ✅ | ✅ |
+| 查看联系人号码明文 | ✅（有操作留痕） | ❌ | ✅ | ✅ |
+| 写入跟进记录 | ✅ | ❌ | ✅ | ✅ |
+| 编辑需求信息 | ✅ | ❌ | ✅ | ✅ |
+| 改等级/改状态 | ✅ | ❌ | ✅ | ✅ |
+| 转公客/转成交/转无效 | ✅ | ❌ | ✅ | ✅ |
+| 编辑相关员工 | ❌ | ❌ | ✅ | ✅ |
+| 查看操作日志 | 部分 | ❌ | ✅ | ✅ |
+| 敏感信息跟进查看 | ✅（本人） | ❌ | ✅ | ✅ |
+| 转公客后操作 | ❌ | ❌ | ✅ | ✅ |
+
+> 注：联系人号码查看必须留痕（自动写入 `log_type='sensitive_view'` 的 `client_follow_logs` 记录）。
+
+---
+
+## 2. 页面设计规范
+
+### 2.1 私客详情页 — 整体框架（P0 🔴）
+
+#### 2.1.1 页面概述
+
+- **URL**：`/clients/<client_id>/`
+- **访问入口**：客源列表点击任意行 → 跳转详情页；面包屑返回列表
+- **页面职责**：集中展示私客的全量信息，提供跟进、带看、状态变更等核心操作入口
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/私客详情.png`
+
+#### 2.1.2 布局结构
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│  顶部导航栏（全局，来自 base.html，高度 48px）                              │
+├────────────────────────────────────────────────────────────────────────┤
+│  面包屑导航（客源 / 客源管理 / {客源标题}）                                 │
+├──────────────────────────────────────┬─────────────────────────────────┤
+│                                      │                                 │
+│   左侧主内容区（约 68% 宽度）            │   右侧信息面板（约 32% 宽度）      │
+│   ─────────────────────────────      │   ─────────────────────────     │
+│   [Tab 导航栏]                        │   [客源标题 Banner（橙色）]      │
+│   需求信息 | 跟进记录 | 带看 |           │   [状态标签行]                 │
+│   客源解读 | 智能配房                   │   [基础字段列表]                │
+│                                      │   [展开全部 链接]               │
+│   [Tab 内容区（HTMX 动态加载）]         │   [快捷操作按钮组]              │
+│                                      │   [状态变更操作网格]            │
+│                                      │   [待办提醒区块]               │
+│                                      │   [联系人区块]                 │
+│                                      │   [相关员工区块]               │
+│                                      │                                 │
+└──────────────────────────────────────┴─────────────────────────────────┘
+```
+
+#### 2.1.3 区域详细规范
+
+**[面包屑导航区]**
+
+| 属性 | 说明 |
+|---|---|
+| 组件 | 原生 HTML `<nav>` + Heroicons `chevron-right` 16px |
+| 内容 | 客源 / 客源管理 / {client.title} |
+| 样式 | `flex items-center gap-1 text-sm text-neutral-500 px-6 py-3` |
+| 最后一项 | `text-neutral-700 font-medium`（不可点击） |
+
+**[双栏主布局]**
+
+```html
+<div class="flex gap-6 px-6 pb-6 items-start">
+  <!-- 左侧主内容区 -->
+  <div class="flex-1 min-w-0 space-y-0">
+    <!-- Tab 导航 + Tab 内容 -->
+  </div>
+  <!-- 右侧固定面板 -->
+  <div class="w-80 flex-shrink-0 space-y-3 sticky top-4">
+    <!-- 客源信息概览 + 联系人 + 相关员工 -->
+  </div>
+</div>
+```
+
+> 右侧面板使用 `sticky top-4` 实现滚动时固定，最大高度 `max-h-[calc(100vh-5rem)] overflow-y-auto`
+
+**[Tab 导航栏]**
+
+| 属性 | 说明 |
+|---|---|
+| 组件 | §10 Tab Navigation |
+| Tab 列表 | 需求信息 / 跟进记录 / 带看 / 客源解读 / 智能配房 |
+| 默认激活 | 需求信息 |
+| 激活样式 | `text-primary-600 font-medium border-b-2 border-primary-600 -mb-px` |
+| 未激活样式 | `text-neutral-500 hover:text-neutral-700` |
+| Alpine 管理 | `x-data="{ activeTab: 'requirements' }"` |
+| HTMX 行为 | 点击 Tab 时 `hx-get` 对应 partial URL，`hx-target="#tab-content"`, `hx-swap="innerHTML"` |
+| 懒加载 | 非默认 Tab 内容通过 `hx-trigger="click"` 首次点击时加载 |
+
+```html
+<div x-data="{ activeTab: 'requirements' }" class="bg-white rounded-lg border border-neutral-200">
+  <!-- Tab 导航 -->
+  <div class="border-b border-neutral-200 px-4" role="tablist">
+    <nav class="flex gap-1 -mb-px">
+      <button
+        role="tab"
+        :aria-selected="activeTab === 'requirements'"
+        @click="activeTab = 'requirements'"
+        :class="activeTab === 'requirements'
+          ? 'h-10 px-4 text-sm text-primary-600 font-medium border-b-2 border-primary-600 -mb-px'
+          : 'h-10 px-4 text-sm text-neutral-500 hover:text-neutral-700'"
+        hx-get="/clients/{{ client.id }}/requirements/"
+        hx-target="#tab-content"
+        hx-swap="innerHTML"
+        hx-trigger="click[activeTab !== 'requirements']"
+      >需求信息</button>
+      <!-- 其余 Tab 类似 -->
+    </nav>
+  </div>
+  <!-- Tab 内容区 -->
+  <div id="tab-content" class="p-4" role="tabpanel">
+    <!-- 初始渲染需求信息内容 -->
+  </div>
+</div>
+```
+
+#### 2.1.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 | 自定义说明 |
+|---|---|---|---|
+| Tab Navigation | §10 Tab Navigation | 左侧五个功能 Tab 切换 | 不做懒加载 `intersect`，改为 `click` 首次触发 |
+
+#### 2.1.5 空状态设计
+
+不适用（详情页框架本身无空状态，各 Tab 内容各自定义）
+
+#### 2.1.6 Loading 状态
+
+Tab 切换时，`#tab-content` 区域显示骨架屏：
+
+```html
+<!-- HTMX indicator（放在 Tab 内容容器内） -->
+<div id="tab-content-skeleton" class="animate-pulse space-y-3 p-4 htmx-indicator">
+  <div class="h-4 bg-neutral-200 rounded w-3/4"></div>
+  <div class="h-4 bg-neutral-200 rounded w-1/2"></div>
+  <div class="h-4 bg-neutral-200 rounded w-2/3"></div>
+</div>
+```
+
+---
+
+### 2.2 Section 左侧：需求信息 Tab（P0 🔴）
+
+#### 2.2.1 页面概述
+
+- **URL**：`/clients/<client_id>/requirements/`（HTMX partial）
+- **访问入口**：详情页默认激活 Tab
+- **页面职责**：展示客户购房/租房需求的全量字段，支持内联编辑
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/需求信息.png`
+
+#### 2.2.2 布局结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  [标题区] 需求信息                        [编辑] 链接        │
+├──────────────────────────────────────────────────────────┤
+│  [字段网格] 3列布局，字段名（灰色）/ 字段值（深色）          │
+│  总价 | 面积 | 居室                                        │
+│  装修 | 朝向 | 楼层                                        │
+│  楼龄 | 意向商圈 | 意向小区                                  │
+│  交通情况 | 备注（跨列）                                     │
+└──────────────────────────────────────────────────────────┘
+```
+
+#### 2.2.3 区域详细规范
+
+**[需求信息字段网格]**
+
+| 字段名 | 数据字段 | 展示类型 | 特殊渲染 |
+|---|---|---|---|
+| 总价 | `requirement.price_min` / `price_max` | 文本范围 | `{min}-{max}万元`，空时显示 `-` |
+| 面积 | `requirement.area_min` / `area_max` | 文本范围 | `{min}㎡-{max}㎡` |
+| 居室 | `requirement.rooms` | 文本 | 如 `2居` |
+| 装修 | `requirement.decoration` | 文本 | 空时 `-` |
+| 朝向 | `requirement.orientation` | 文本 | 多选逗号分隔 |
+| 楼层 | `requirement.floor_preference` | 文本 | 多选，如 `中楼层、低楼层` |
+| 楼龄 | `requirement.building_age` | 文本 | 空时 `-` |
+| 意向商圈 | `requirement.preferred_districts` | 多标签 | 逗号分隔文本，空时 `-` |
+| 意向小区 | `requirement.preferred_communities` | 多标签 | 逗号分隔，空时 `-` |
+| 交通情况 | `requirement.transport_preference` | 文本 | 空时 `-` |
+| 备注 | `requirement.notes` | 多行文本 | 跨越全行 `col-span-3`，空时 `-` |
+
+**字段渲染 HTML 结构：**
+
+```html
+<div class="grid grid-cols-3 gap-x-6 gap-y-4">
+  <div class="space-y-1">
+    <dt class="text-xs text-neutral-500">总价</dt>
+    <dd class="text-sm text-neutral-800">{{ req.price_min }}-{{ req.price_max }}万元</dd>
+  </div>
+  <!-- ... -->
+</div>
+```
+
+**[编辑按钮]**
+
+| 属性 | 说明 |
+|---|---|
+| 样式 | `text-sm text-info-600 hover:text-blue-700 font-medium` |
+| 触发 | 点击打开编辑需求信息 Drawer（§3.1） |
+| 权限 | 仅归属人/管理员/店长可见 |
+
+#### 2.2.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 | 自定义说明 |
+|---|---|---|---|
+| Inline Edit Mode | §15 | 字段网格切换编辑态 | 本模块改为 Drawer 编辑，不用内联编辑模式 |
+
+#### 2.2.5 空状态设计
+
+若需求信息尚未录入（所有字段均为空），在内容区中部显示：
+
+```html
+<div class="flex flex-col items-center justify-center py-12 text-center">
+  <svg class="w-10 h-10 text-neutral-300 mb-3"><!-- Heroicons document-text --></svg>
+  <p class="text-sm text-neutral-500">暂未填写需求信息</p>
+  <button class="mt-3 text-sm text-primary-600 hover:underline">立即编辑</button>
+</div>
+```
+
+#### 2.2.6 Loading 状态
+
+由父页面 Tab 切换骨架屏覆盖（见 §2.1.6），内容区自身不额外处理。
+
+---
+
+### 2.3 Section 左侧：跟进记录 Tab（P0 🔴）
+
+#### 2.3.1 页面概述
+
+- **URL**：`/clients/<client_id>/follow-logs/`（HTMX partial）
+- **访问入口**：点击"跟进记录" Tab
+- **页面职责**：按时间线展示所有跟进记录，支持筛选、写入新跟进
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/跟进记录-全部.png`、`跟进记录-写入跟进.png` 等
+
+#### 2.3.2 布局结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  [子 Tab 行] 全部 | 写入跟进 | 敏感信息跟进 | 修改跟进 | 其他跟进 │
+├──────────────────────────────────────────────────────────┤
+│  [筛选区（写入跟进 Tab 展开更多筛选）]                         │
+│  日期范围选择器            [有录音] [有图片] 复选框            │
+│  跟进目的：多选复选框（展开/收起）                             │
+│  跟进标签：多选复选框（展开/收起）                             │
+├──────────────────────────────────────────────────────────┤
+│  [时间线内容区]                                            │
+│  ● 2026-04-19 ──────────────────────────────────         │
+│    [跟进记录条目 1]                                        │
+│    [跟进记录条目 2]                                        │
+│  ● 2026-04-18 ──────────────────────────────────         │
+│    [跟进记录条目 ...]                                      │
+│  [加载更多 按钮]                                           │
+└──────────────────────────────────────────────────────────┘
+```
+
+#### 2.3.3 区域详细规范
+
+**[子 Tab 导航栏]**
+
+| 属性 | 说明 |
+|---|---|
+| 组件 | §10 Tab Navigation（嵌套，风格改为 pill 式） |
+| Tab 列表 | 全部 / 写入跟进 / 敏感信息跟进 / 修改跟进 / 其他跟进 |
+| 映射 log_type | `all` / `written` / `sensitive_view` / `modified` / `other` |
+| 样式 | `bg-neutral-100 rounded-full px-3 py-1 text-xs`；激活 `bg-primary-600 text-white` |
+| Alpine | `x-data="{ logTab: 'all' }"` |
+| HTMX | 切换时 `hx-get="/clients/{id}/follow-logs/?type={logTab}"` `hx-target="#log-list"` `hx-swap="innerHTML"` |
+
+**[筛选区]**
+
+| 字段 | 组件类型 | 说明 |
+|---|---|---|
+| 日期范围 | §9 Date Range Picker | `开始时间 → 结束时间`；`hx-trigger="change"` |
+| 有录音 / 有图片 | Checkbox | `hx-trigger="change"` 触发重筛 |
+| 跟进目的 | 多选 Checkbox 网格 | 仅在"写入跟进"Tab 下展开显示；默认折叠，"展开 ∨" 链接切换；竞品中约 25 个选项 |
+| 跟进标签 | 多选 Checkbox | 同上，与跟进目的共用展开/收起逻辑 |
+
+```html
+<!-- 筛选区 Alpine 管理展开/收起 -->
+<div x-data="{ filterOpen: false }">
+  <div class="flex items-center gap-4 py-2 border-b border-neutral-100">
+    <span class="text-xs text-neutral-500">筛选:</span>
+    <label class="flex items-center gap-1 text-xs text-neutral-600 cursor-pointer">
+      <input type="checkbox" class="w-3 h-3 rounded accent-primary-600"
+             hx-get="/clients/{{ id }}/follow-logs/" hx-trigger="change"
+             hx-include="[name='filter']" hx-target="#log-list" name="filter" value="has_audio">
+      有录音
+    </label>
+    <label class="flex items-center gap-1 text-xs text-neutral-600 cursor-pointer">
+      <input type="checkbox" class="w-3 h-3 rounded accent-primary-600"
+             hx-get="/clients/{{ id }}/follow-logs/" hx-trigger="change"
+             hx-include="[name='filter']" hx-target="#log-list" name="filter" value="has_image">
+      有图片
+    </label>
+  </div>
+  <!-- 跟进目的（仅写入跟进 Tab 显示） -->
+  <template x-if="logTab === 'written'">
+    <div class="py-2 border-b border-neutral-100">
+      <div class="flex items-center gap-2 flex-wrap">
+        <span class="text-xs text-neutral-500 flex-shrink-0">跟进目的:</span>
+        <!-- 复选框网格 -->
+        <div x-show="filterOpen" class="flex flex-wrap gap-2">
+          <!-- 25 个目的选项 -->
+        </div>
+        <button @click="filterOpen = !filterOpen"
+                class="text-xs text-info-600 hover:underline ml-auto">
+          <span x-text="filterOpen ? '收起 ∧' : '展开 ∨'"></span>
+        </button>
+      </div>
+    </div>
+  </template>
+</div>
+```
+
+**[时间线内容区]**
+
+采用 §10.3 内嵌 Timeline 子组件规范：
+
+| 元素 | 规格 |
+|---|---|
+| 外容器 | `relative pl-6 space-y-1` |
+| 竖线 | `absolute left-2.5 top-0 bottom-0 w-px bg-neutral-200` |
+| 日期分组标题 | `flex items-center gap-2 text-xs font-semibold text-neutral-500 uppercase py-2`；圆点 `w-3 h-3 rounded-full border-2 border-primary-600 bg-white absolute -left-[14px]` |
+| 记录条目卡片 | `ml-2 bg-white border border-neutral-100 rounded-md p-3 space-y-1` |
+
+**跟进记录条目卡片规范：**
+
+```
+┌────────────────────────────────────────────────────────┐
+│  [类型标签 Badge] 【电话】    [时间戳] 11:25  [⋯ 更多]  │
+│  [内容文本] 433弄5楼65.85平想置换...                    │
+│  [底部元信息] 都市港湾店一组 雷威 · 2026-04-19          │
+│  [已开放] [隐藏] 操作链接（灰色小字）                   │
+└────────────────────────────────────────────────────────┘
+```
+
+| 元素 | 规格 |
+|---|---|
+| 类型标签 | `text-xs font-medium px-2 py-0.5 rounded-full bg-blue-100 text-blue-700` |
+| 时间戳 | `text-xs text-neutral-400 tabular-nums` |
+| 内容文本 | `text-sm text-neutral-700 leading-relaxed` |
+| 元信息 | `text-xs text-neutral-400` |
+| 操作链接 | `text-xs text-info-600 hover:underline`（"ℹ️ 已开放" / "隐藏"） |
+| 更多菜单 | Heroicons `ellipsis-horizontal` 16px，点击展开 Dropdown（修改/删除选项） |
+| 敏感信息标记 | `log_type === 'sensitive_view'`：条目背景 `bg-amber-50 border-amber-200`，不可删除 |
+
+**[加载更多]**
+
+```html
+<div id="log-load-more" class="text-center py-3">
+  <button class="text-sm text-primary-600 hover:underline"
+          hx-get="/clients/{{ id }}/follow-logs/?page=2"
+          hx-target="#log-list"
+          hx-swap="beforeend"
+          hx-indicator="#log-load-spinner">
+    查看全部跟进
+  </button>
+  <span id="log-load-spinner" class="htmx-indicator ml-2 inline-block w-4 h-4 border-2 border-primary-600 border-t-transparent rounded-full animate-spin"></span>
+</div>
+```
+
+#### 2.3.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 | 自定义说明 |
+|---|---|---|---|
+| Tab Navigation | §10 | 跟进类型子 Tab | 改为 pill 风格，而非下划线风格 |
+| Timeline 子组件 | §10.3 | 时间线记录展示 | 增加日期分组标题，圆点用 `border-primary-600` |
+| Date Range Picker | §9 | 跟进记录日期筛选 | 标准实现，`hx-trigger="change"` 自动触发筛选 |
+
+#### 2.3.5 空状态设计
+
+```html
+<div class="flex flex-col items-center justify-center py-16 text-center">
+  <svg class="w-10 h-10 text-neutral-300 mb-3"><!-- Heroicons chat-bubble-left-ellipsis --></svg>
+  <p class="text-sm text-neutral-500">暂无跟进</p>
+</div>
+```
+
+#### 2.3.6 Loading 状态
+
+```html
+<div class="animate-pulse space-y-3 p-4 htmx-indicator">
+  <div class="h-3 bg-neutral-200 rounded w-24"></div><!-- 日期标题 -->
+  <div class="ml-2 space-y-2 border border-neutral-100 rounded-md p-3">
+    <div class="h-3 bg-neutral-200 rounded w-16"></div>
+    <div class="h-4 bg-neutral-200 rounded w-full"></div>
+    <div class="h-3 bg-neutral-200 rounded w-1/2"></div>
+  </div>
+</div>
+```
+
+---
+
+### 2.4 Section 左侧：带看 Tab（P0 🔴）
+
+#### 2.4.1 页面概述
+
+- **URL**：`/clients/<client_id>/viewings/`（HTMX partial）
+- **访问入口**：点击"带看" Tab
+- **页面职责**：展示该客源的预约带看和实际带看记录，提供新增入口
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/带看.png`
+
+#### 2.4.2 布局结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  [子 Tab] 预约 | 带看（active）          [日期范围选择器]   │
+├──────────────────────────────────────────────────────────┤
+│  [筛选复选框] □ 归属人带看  □ 其他人带看                   │
+├──────────────────────────────────────────────────────────┤
+│  [时间线带看记录列表]                                      │
+│  ● 2026-04-17 20:30                                      │
+│    带看情况: 客户继续维护                                   │
+│    房源: 金沙丽晶苑一期-001-1201  [一看] 带看: 雷威          │
+│    [详情 ›]                                              │
+│  [加载更多]                                              │
+└──────────────────────────────────────────────────────────┘
+```
+
+#### 2.4.3 区域详细规范
+
+**[子 Tab 导航]**
+
+| 属性 | 说明 |
+|---|---|
+| Tab 列表 | 预约 / 带看 |
+| Alpine | `x-data="{ viewingTab: 'viewing' }"` |
+| HTMX | `hx-get="/clients/{id}/viewings/?type={viewingTab}"` `hx-target="#viewing-list"` |
+
+**[筛选行]**
+
+| 字段 | 说明 |
+|---|---|
+| 归属人带看 | `hx-trigger="change"` 筛选重载 |
+| 其他人带看 | 同上 |
+| 日期范围 | §9 Date Range Picker，`hx-trigger="change"` |
+
+**[带看记录条目]**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  ● 2026-04-17 20:30                                     │
+│  带看情况: 客户继续维护                                    │
+│  [房源链接] 金沙丽晶苑一期-001-1201                        │
+│  [带看次数 Badge: 一看 橙色] 带看: 雷威                    │
+│  [详情 › 链接]                                           │
+└─────────────────────────────────────────────────────────┘
+```
+
+| 元素 | 规格 |
+|---|---|
+| 带看次数 Badge | `text-xs font-medium px-2 py-0.5 rounded-full bg-primary-50 text-primary-700 border border-primary-200` |
+| 房源链接 | `text-sm text-info-600 hover:underline` |
+| 带看情况 | `text-sm text-neutral-700` |
+| 带看人 | `text-xs text-neutral-500` |
+| 详情链接 | `text-xs text-info-600 hover:underline ml-auto` |
+
+#### 2.4.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 | 自定义说明 |
+|---|---|---|---|
+| Tab Navigation | §10 | 预约/带看子 Tab | pill 风格 |
+| Timeline 子组件 | §10.3 | 带看记录时间线 | 圆点时间戳展示带看时刻 |
+| Date Range Picker | §9 | 带看日期筛选 | 标准实现 |
+
+#### 2.4.5 空状态设计
+
+```html
+<div class="flex flex-col items-center justify-center py-16 text-center">
+  <svg class="w-10 h-10 text-neutral-300 mb-3"><!-- Heroicons home --></svg>
+  <p class="text-sm text-neutral-500">暂无带看记录</p>
+  <a href="/clients/{{ id }}/viewings/create/"
+     class="mt-3 text-sm text-primary-600 hover:underline">新增带看</a>
+</div>
+```
+
+#### 2.4.6 Loading 状态
+
+与 §2.3.6 相同的骨架屏方案。
+
+---
+
+### 2.5 Section 左侧：客源解读 Tab（P1 🟡）
+
+#### 2.5.1 页面概述
+
+- **URL**：`/clients/<client_id>/insights/`（HTMX partial）
+- **访问入口**：点击"客源解读" Tab
+- **页面职责**：展示 AI 分析的客户找房行为数据：活跃时间、购房偏好、区域偏好
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/客源解读.png`
+
+#### 2.5.2 布局结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  [说明文字] + 使用指南链接          [数据更新时间戳]          │
+├──────────────────────────────────────────────────────────┤
+│  [活跃行为卡片]       [活跃时间卡片: 工作日 | 周末]          │
+├──────────────────────────────────────────────────────────┤
+│  购房偏好                [时段筛选: 近7日 | 近30日 | 近90日] │
+│  [偏好摘要网格: 价格/户型/面积/商圈/小区]                    │
+│  [类型占比行]                                             │
+│  [偏好子 Tab: 二手偏好 | 新房偏好]                          │
+│  [三个甜甜圈图: 价格偏好 / 户型偏好 / 面积偏好]              │
+│  [区域-商圈偏好] [小区偏好]                                │
+└──────────────────────────────────────────────────────────┘
+```
+
+#### 2.5.3 区域详细规范
+
+**[活跃行为卡片]**
+
+| 属性 | 说明 |
+|---|---|
+| 样式 | `bg-white border border-neutral-200 rounded-lg p-4` |
+| 内容 | 标题"活跃行为"+ 数值（如"7 天内"）用 `text-2xl font-bold text-neutral-800` |
+| 副标题 | `text-sm text-neutral-500` 描述说明 |
+
+**[购房偏好摘要网格]**
+
+| 字段 | 规格 |
+|---|---|
+| 价格 | `text-sm font-semibold text-neutral-800` 展示范围 |
+| 户型 | 同上 |
+| 面积 | 同上 |
+| 商圈 / 小区 | 空时显示 `-` |
+
+**[甜甜圈图]**
+
+> MVP 阶段可用简单的百分比 `text-4xl font-bold text-primary-600` 替代 Chart.js 图表，配合 `text-sm text-neutral-500` 标签文字。P1 阶段再引入图表库。
+
+**[时段筛选 Pill]**
+
+```html
+<div x-data="{ period: '7d' }" class="flex gap-1">
+  <template x-for="p in [{val:'7d', label:'近7日'},{val:'30d', label:'近30日'},{val:'90d', label:'近90日'}]">
+    <button @click="period = p.val"
+            :class="period === p.val ? 'bg-primary-600 text-white' : 'bg-neutral-100 text-neutral-600'"
+            class="text-xs px-3 py-1 rounded-full"
+            hx-get="/clients/{{ id }}/insights/" :hx-vals="JSON.stringify({period: p.val})"
+            hx-target="#insight-content" hx-swap="innerHTML">
+      <span x-text="p.label"></span>
+    </button>
+  </template>
+</div>
+```
+
+#### 2.5.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 | 自定义说明 |
+|---|---|---|---|
+| Tab Navigation | §10 | 二手偏好/新房偏好子 Tab | pill 风格 |
+
+#### 2.5.5 空状态设计
+
+```html
+<div class="text-center py-12">
+  <svg class="w-10 h-10 text-neutral-300 mx-auto mb-3"><!-- Heroicons chart-bar --></svg>
+  <p class="text-sm text-neutral-500">暂无找房行为数据</p>
+  <p class="text-xs text-neutral-400 mt-1">数据由系统每日凌晨更新</p>
+</div>
+```
+
+#### 2.5.6 Loading 状态
+
+骨架屏三个卡片占位块，`animate-pulse` 处理。
+
+---
+
+### 2.6 Section 左侧：二手配房 Tab（P1 🟡）
+
+#### 2.6.1 页面概述
+
+- **URL**：`/clients/<client_id>/property-matches/`（HTMX partial）
+- **访问入口**：点击"智能配房" Tab
+- **页面职责**：展示系统根据客户需求匹配的二手房源，按分组展示推荐卡片
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/二手配房.png`
+
+#### 2.6.2 布局结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  二手配房          [更新时间]  ℹ️      [批量分享 按钮]       │
+│  [子 Tab] 录客配房（active） | 系统配房                      │
+├──────────────────────────────────────────────────────────┤
+│  [分组标题: 优质户型]                                       │
+│  [房源卡片] [房源卡片] [房源卡片]                           │
+│  [分组标题: 降价]                                          │
+│  [房源卡片] [房源卡片]                                     │
+│  [分组标题: 热门]                                          │
+│  [房源卡片] ...                                           │
+└──────────────────────────────────────────────────────────┘
+```
+
+#### 2.6.3 区域详细规范
+
+**[房源卡片]**
+
+```
+┌─────────────────────────────────────────────┐
+│  [缩略图 80×60]   [房源名称（蓝色链接）]        │
+│                   [规格] 2/2/1 · 101.17㎡    │
+│                   [区域] 嘉定 丰庄            │
+│                   [特征标签组]（橙/蓝 pills）  │
+│  [价格] 620万 [跌价信息] 已跌20万              │
+│  [单价] 61283元/㎡                           │
+│  [分享房源] [反馈 ∨]（action 链接）           │
+└─────────────────────────────────────────────┘
+```
+
+| 元素 | 规格 |
+|---|---|
+| 缩略图 | `w-20 h-15 rounded-md object-cover flex-shrink-0` |
+| 房源名称 | `text-sm font-medium text-info-600 hover:underline` |
+| 规格文字 | `text-xs text-neutral-500` |
+| 特征标签 | `text-xs px-1.5 py-0.5 rounded bg-orange-50 text-orange-700` 或 `bg-blue-50 text-blue-700` |
+| 价格 | `text-base font-bold text-neutral-900` |
+| 跌价标注 | `text-xs text-neutral-400` |
+| 分组标题 | `text-sm font-semibold text-neutral-700 py-2 border-b border-neutral-200 mb-3` |
+| 批量分享 | `btn-secondary text-xs` 灰色描边按钮 |
+| 反馈 ∨ | Dropdown，选项：满意/不满意/已跟进 |
+
+**卡片网格布局：**
+
+```html
+<div class="grid grid-cols-1 gap-3" id="match-list">
+  <!-- 每个分组 -->
+  <div>
+    <h3 class="text-sm font-semibold text-neutral-700 py-2 border-b border-neutral-200 mb-3">优质户型</h3>
+    <div class="space-y-3">
+      <!-- 房源卡片 -->
+    </div>
+  </div>
+</div>
+```
+
+#### 2.6.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Tab Navigation | §10 | 录客配房/系统配房子 Tab |
+
+#### 2.6.5 空状态设计
+
+```html
+<div class="text-center py-12">
+  <svg class="w-10 h-10 text-neutral-300 mx-auto mb-3"><!-- Heroicons building-office-2 --></svg>
+  <p class="text-sm text-neutral-500">暂无匹配房源</p>
+</div>
+```
+
+#### 2.6.6 Loading 状态
+
+卡片骨架屏，每张卡片用 `animate-pulse` 占位块。
+
+---
+
+### 2.7 Section 右侧：客源信息概览面板（P0/P1）
+
+#### 2.7.1 页面概述
+
+- **URL**：`/clients/<client_id>/sidebar/`（HTMX partial，初始 SSR）
+- **访问入口**：详情页右侧固定面板（持续可见）
+- **页面职责**：集中展示客源核心标识信息 + 快捷操作入口
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/客源信息概览.png`
+
+#### 2.7.2 布局结构
+
+```
+┌──────────────────────────────────────────────┐
+│  [橙色 Banner]                               │
+│  求购  叶阿姨买一房（上门）  女士               │
+├──────────────────────────────────────────────┤
+│  [状态标签行] 私客 · 一看 · C(一般)            │
+├──────────────────────────────────────────────┤
+│  [基础字段列表（只读）]                         │
+│  最近跟进 / 客户编号 / 委托日期 ...            │
+│  [展开全部 ∨ 链接]                            │
+├──────────────────────────────────────────────┤
+│  [三个主操作按钮]（P0）                        │
+│  [打电话] [写跟进] [报备/常看]                 │
+├──────────────────────────────────────────────┤
+│  [状态变更操作网格]（P0）                      │
+│  ☆ 收藏 · 不置顶                             │
+│  改等级 · 改状态                              │
+│  转公客 · 转成交                              │
+│  转无效 · 编辑客源                            │
+└──────────────────────────────────────────────┘
+```
+
+#### 2.7.3 区域详细规范
+
+**[橙色 Banner]**
+
+```html
+<div class="bg-primary-600 rounded-t-lg px-4 py-3">
+  <div class="flex items-start gap-2">
+    <span class="text-xs font-medium text-white bg-white/20 px-2 py-0.5 rounded-full">求购</span>
+    <div class="flex-1 min-w-0">
+      <h2 class="text-sm font-semibold text-white leading-snug truncate">
+        {{ client.title }}
+      </h2>
+      <p class="text-xs text-white/80 mt-0.5">{{ client.primary_contact.name }} {{ client.primary_contact.gender_display }}</p>
+    </div>
+  </div>
+</div>
+```
+
+> 注：竞品用橙色 `#f5774a`；本系统采用 Teal `primary-600 (#0F766E)` 替代，保持品牌一致性。
+
+**[状态标签行]**
+
+| 标签 | 样式 |
+|---|---|
+| 私客（client_type） | `text-xs px-2 py-0.5 rounded-full bg-neutral-100 text-neutral-600` |
+| 带看次数（如"一看"） | `text-xs px-2 py-0.5 rounded-full bg-blue-100 text-blue-700` |
+| 等级（C/一般） | `text-xs px-2 py-0.5 rounded-full`；A 级 `bg-red-100 text-red-700`；B 级 `bg-orange-100 text-orange-700`；C 级 `bg-yellow-100 text-yellow-700`；D/E `bg-neutral-100 text-neutral-500` |
+
+**[基础字段列表]**
+
+| 字段名 | 数据来源 | 空值展示 |
+|---|---|---|
+| 最近跟进 | `client.last_follow_at` | `-` |
+| 客户编号 | `client.client_no` | — |
+| 委托日期 | `client.created_at` date | — |
+| 需求类型 | `client.requirement_type_display` | — |
+| 房源用途 | `client.property_usage_display` | — |
+| 客户来源 | `client.source_display` | — |
+| 购房目的 | `client.purchase_purpose` | `-` |
+| 付款方式 | `client.payment_method` | `-` |
+| 名下房产 | `client.owned_properties` | `未填写` |
+| 贷款记录 | `client.loan_record` | `-` |
+| 证件类型 | `client.id_type` | `-` |
+| 证件号码 | `client.id_number`（脱敏） | `-` |
+| 意向学校 | `client.preferred_school` | `-` |
+| 入学时间 | `client.school_start_year` | `-` |
+
+**字段行渲染：**
+
+```html
+<dl class="space-y-1.5 px-4 py-3">
+  <div class="flex items-start justify-between gap-2">
+    <dt class="text-xs text-neutral-400 flex-shrink-0 w-16">最近跟进</dt>
+    <dd class="text-xs text-neutral-700 text-right">{{ client.last_follow_at|date:"Y-m-d"|default:"-" }}</dd>
+  </div>
+  <!-- ... -->
+</dl>
+```
+
+**[展开全部链接]**
+
+```html
+<button x-data="{ expanded: false }" @click="expanded = !expanded"
+        class="w-full text-center text-xs text-info-600 hover:underline py-2 border-t border-neutral-100">
+  <span x-text="expanded ? '收起 ∧' : '展开全部 ∨'"></span>
+</button>
+<!-- 隐藏字段区，x-show="expanded" -->
+```
+
+**[三个主操作按钮（P0）]**
+
+```html
+<div class="grid grid-cols-3 gap-2 px-4 py-3 border-t border-neutral-100">
+  <button class="flex flex-col items-center gap-1 py-2 bg-primary-600 hover:bg-primary-700
+                 text-white text-xs font-medium rounded-md transition-colors">
+    <svg class="w-4 h-4"><!-- Heroicons phone --></svg>
+    打电话
+  </button>
+  <button hx-get="/clients/{{ id }}/follow-logs/create/"
+          hx-target="#drawer-container" hx-swap="innerHTML"
+          @click="drawerOpen = true"
+          class="flex flex-col items-center gap-1 py-2 bg-primary-600 hover:bg-primary-700
+                 text-white text-xs font-medium rounded-md transition-colors">
+    <svg class="w-4 h-4"><!-- Heroicons pencil-square --></svg>
+    写跟进
+  </button>
+  <button class="flex flex-col items-center gap-1 py-2 bg-primary-600 hover:bg-primary-700
+                 text-white text-xs font-medium rounded-md transition-colors">
+    <svg class="w-4 h-4"><!-- Heroicons flag --></svg>
+    报备/常看
+  </button>
+</div>
+```
+
+**[状态变更操作网格（P0）]**
+
+```html
+<div class="grid grid-cols-2 gap-1 px-4 py-3 border-t border-neutral-100">
+  <!-- 收藏 -->
+  <button class="flex items-center gap-2 px-3 py-2 text-xs text-neutral-600
+                 hover:bg-neutral-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-neutral-400"><!-- Heroicons star --></svg>
+    收藏
+  </button>
+  <!-- 不置顶 -->
+  <button class="flex items-center gap-2 px-3 py-2 text-xs text-neutral-600
+                 hover:bg-neutral-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-neutral-400"><!-- Heroicons arrow-down --></svg>
+    不置顶
+  </button>
+  <!-- 改等级（触发 Modal） -->
+  <button hx-get="/clients/{{ id }}/change-grade/"
+          hx-target="#modal-container" hx-swap="innerHTML"
+          @click="modalOpen = true"
+          class="flex items-center gap-2 px-3 py-2 text-xs text-neutral-600
+                 hover:bg-neutral-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-neutral-400"><!-- Heroicons adjustments-horizontal --></svg>
+    改等级
+  </button>
+  <!-- 改状态 -->
+  <button hx-get="/clients/{{ id }}/change-status/"
+          hx-target="#modal-container" hx-swap="innerHTML"
+          @click="modalOpen = true"
+          class="flex items-center gap-2 px-3 py-2 text-xs text-neutral-600
+                 hover:bg-neutral-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-neutral-400"><!-- Heroicons arrow-path --></svg>
+    改状态
+  </button>
+  <!-- 转公客 -->
+  <button class="flex items-center gap-2 px-3 py-2 text-xs text-neutral-600
+                 hover:bg-neutral-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-neutral-400"><!-- Heroicons users --></svg>
+    转公客
+  </button>
+  <!-- 转成交 -->
+  <button hx-get="/clients/{{ id }}/convert-deal/"
+          hx-target="#modal-container" hx-swap="innerHTML"
+          @click="modalOpen = true"
+          class="flex items-center gap-2 px-3 py-2 text-xs text-neutral-600
+                 hover:bg-neutral-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-neutral-400"><!-- Heroicons check-badge --></svg>
+    转成交
+  </button>
+  <!-- 转无效 -->
+  <button class="flex items-center gap-2 px-3 py-2 text-xs text-danger-600
+                 hover:bg-red-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-danger-500"><!-- Heroicons x-circle --></svg>
+    转无效
+  </button>
+  <!-- 编辑客源 -->
+  <button hx-get="/clients/{{ id }}/edit-basic/"
+          hx-target="#modal-container" hx-swap="innerHTML"
+          @click="modalOpen = true"
+          class="flex items-center gap-2 px-3 py-2 text-xs text-neutral-600
+                 hover:bg-neutral-50 rounded-md transition-colors">
+    <svg class="w-4 h-4 text-neutral-400"><!-- Heroicons pencil --></svg>
+    编辑客源
+  </button>
+</div>
+```
+
+**[待办提醒区块（P1）]**
+
+```html
+<div class="px-4 py-3 border-t border-neutral-100">
+  <div class="flex items-center justify-between mb-1">
+    <span class="text-xs font-medium text-neutral-700">待办提醒 ({{ todo_count }})</span>
+    <button class="text-xs text-info-600 hover:underline">写办</button>
+  </div>
+  <p class="text-xs text-neutral-400">系统会在设置的时间点发送跟进通知</p>
+</div>
+```
+
+#### 2.7.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Modal Dialog | §7 | 改等级/改状态/转成交/编辑客源 弹窗容器 |
+
+#### 2.7.5 空状态设计
+
+不适用（面板始终显示）
+
+#### 2.7.6 Loading 状态
+
+右侧面板初始 SSR 渲染，HTMX 更新时对应区域显示 `opacity-50 pointer-events-none` 禁用态。
+
+---
+
+### 2.8 Section 右侧：联系人面板（P0 🔴）
+
+#### 2.8.1 页面概述
+
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/联系人.png`
+
+#### 2.8.2 布局结构
+
+```
+┌─────────────────────────────────────────────┐
+│  联系人    [查看号码]  [新增联系人]  操作链接   │
+├─────────────────────────────────────────────┤
+│  [联系人条目]                                │
+│  姓名 · 称呼                                 │
+│  电话1: +86 137****8888  [默认拨打] [接通N次] │
+│  微信: -  QQ: -  备注: -                    │
+└─────────────────────────────────────────────┘
+```
+
+#### 2.8.3 区域详细规范
+
+**[面板 Header]**
+
+| 元素 | 规格 |
+|---|---|
+| 标题 | `text-sm font-semibold text-neutral-800` |
+| 查看号码 | `text-xs text-info-600 hover:underline`；点击触发 HTMX POST 到 `/clients/{id}/reveal-phone/`，响应返回明文号码，同时后端写入 sensitive_view 日志 |
+| 新增联系人 | `text-xs text-info-600 hover:underline`；触发 Drawer |
+
+**[联系人条目]**
+
+```html
+<div class="space-y-2">
+  <div class="flex items-start gap-2">
+    <div class="flex-1 min-w-0">
+      <p class="text-sm font-medium text-neutral-800">
+        {{ contact.name }} <span class="text-neutral-400 text-xs">{{ contact.gender_display }}</span>
+      </p>
+      <!-- 手机号（脱敏） -->
+      <p class="text-xs text-neutral-600 mt-1">
+        电话1:
+        <span id="phone-display-{{ contact.id }}" class="tabular-nums">
+          {{ contact.phone_masked }}
+        </span>
+        <span class="ml-2 text-neutral-400">默认拨打</span>
+        <span class="ml-1 text-neutral-400">接通{{ contact.call_success_count }}次</span>
+        <span class="ml-1 text-neutral-400">拨打{{ contact.call_total_count }}次</span>
+      </p>
+      <p class="text-xs text-neutral-400 mt-0.5">微信: {{ contact.wechat|default:"-" }}</p>
+    </div>
+    <button class="text-primary-600 hover:text-primary-700 flex-shrink-0 p-1">
+      <svg class="w-4 h-4"><!-- Heroicons phone --></svg>
+    </button>
+  </div>
+</div>
+```
+
+**查看号码交互：**
+
+```html
+<button hx-post="/clients/{{ id }}/contacts/{{ contact.id }}/reveal-phone/"
+        hx-target="#phone-display-{{ contact.id }}"
+        hx-swap="innerHTML"
+        hx-confirm="查看号码将会留下操作记录，确认继续？"
+        class="text-xs text-info-600 hover:underline">
+  查看号码
+</button>
+```
+
+#### 2.8.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Modal Dialog | §7 | 新增联系人表单 |
+
+#### 2.8.5 空状态设计
+
+联系人列表为空时显示 `text-xs text-neutral-400` 提示 "暂无联系人"。
+
+---
+
+### 2.9 Section 右侧：相关员工面板（P0 🔴）
+
+#### 2.9.1 页面概述
+
+- **竞品参考截图**：`Project/fonrey/screenshots/客源/相关员工.png`
+
+#### 2.9.2 布局结构
+
+```
+┌─────────────────────────────────────────────┐
+│  相关员工                           [编辑]   │
+├─────────────────────────────────────────────┤
+│  【首录人】                        ☎ 电话图标 │
+│  都市港湾店一组 雷威                          │
+│  参与时间: 2026-04-17 19:21                 │
+│  【归属人】                        ☎ 电话图标 │
+│  都市港湾店一组 雷威                          │
+│  参与时间: 2026-04-17 19:21                 │
+└─────────────────────────────────────────────┘
+```
+
+#### 2.9.3 区域详细规范
+
+```html
+<div class="bg-white rounded-lg border border-neutral-200 p-4">
+  <div class="flex items-center justify-between mb-3">
+    <h3 class="text-sm font-semibold text-neutral-800">相关员工</h3>
+    {% if can_edit_staff %}
+    <button class="text-xs text-info-600 hover:underline">编辑</button>
+    {% endif %}
+  </div>
+  <div class="space-y-3">
+    {% for staff in related_staff %}
+    <div class="flex items-start justify-between">
+      <div>
+        <p class="text-xs font-medium text-neutral-700">【{{ staff.role_display }}】</p>
+        <p class="text-sm text-neutral-800">{{ staff.department }} {{ staff.name }}</p>
+        <p class="text-xs text-neutral-400">参与时间: {{ staff.joined_at|date:"Y-m-d H:i" }}</p>
+      </div>
+      <button class="text-primary-600 hover:text-primary-700 p-1 flex-shrink-0">
+        <svg class="w-4 h-4"><!-- Heroicons phone --></svg>
+      </button>
+    </div>
+    {% endfor %}
+  </div>
+</div>
+```
+
+| 元素 | 权限控制 |
+|---|---|
+| 编辑按钮 | 仅管理员/店长可见（`{% if can_edit_staff %}`） |
+| 电话图标 | 拨打员工内部电话，无需权限控制 |
+
+---
+
+## 3. 弹窗/抽屉设计规范
+
+### 3.1 编辑基础信息（P1 🟡）
+
+#### 3.1.1 触发方式
+
+- **触发位置**：右侧客源信息概览面板 → "编辑客源" 按钮
+- **组件类型**：Modal Dialog（内容字段多，但不足以需要 Drawer 宽度）
+- **尺寸**：`max-w-2xl`（宽型）+ 最大高度 `max-h-[80vh]` 内部滚动
+- **竞品截图**：`Project/fonrey/screenshots/客源/编辑基础信息.png`
+
+#### 3.1.2 表单字段规范
+
+| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值/预填值 |
+|---|---|---|---|---|
+| 需求类型 | Checkbox（二手/新房） | 是 | 至少选一 | 预填当前值 |
+| 用途 | Select | 是 | 必选 | 预填当前值 |
+| 来源 | Select | 是 | 必选 | 预填当前值 |
+| 购房目的 | 多选 Checkbox | 否 | — | 预填当前值 |
+| 付款方式 | Select | 否 | — | 预填 |
+| 名下房产 | Select | 否 | — | 预填 |
+| 贷款记录 | Radio（有/无） | 否 | — | 预填 |
+| 证件类型 | Select | 否 | — | 预填 |
+| 证件号码 | Text Input | 否 | 身份证 18 位格式校验 | 预填 |
+| 意向学校 | 动态 Text Input（可多行） | 否 | — | 预填 |
+| 入学时间 | Select（年份） | 否 | — | 预填 |
+
+#### 3.1.3 提交行为
+
+- **提交方式**：`hx-patch="/clients/{{ id }}/edit-basic/"`
+- **成功响应**：关闭 Modal + Toast "保存成功" + `hx-get` 刷新右侧面板
+- **失败响应（422）**：字段级 `<p class="text-xs text-danger-600 mt-1">` 错误提示
+- **HTMX 属性**：
+
+```html
+<form hx-patch="/clients/{{ id }}/edit-basic/"
+      hx-target="#modal-container"
+      hx-swap="innerHTML"
+      hx-on::after-request="if(event.detail.successful){ modalOpen = false; htmx.trigger('#sidebar', 'refresh') }">
+```
+
+#### 3.1.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Modal Dialog | §7 | 弹窗容器 |
+| Multi-select Tag Input | §17 | 购房目的多选 |
+
+---
+
+### 3.2 改等级（P0 🔴）
+
+#### 3.2.1 触发方式
+
+- **触发位置**：右侧面板 → "改等级" 按钮
+- **组件类型**：Modal Dialog（内容极简）
+- **尺寸**：`max-w-sm`
+- **竞品截图**：`Project/fonrey/screenshots/客源/改等级.png`
+
+#### 3.2.2 表单字段规范
+
+| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 |
+|---|---|---|---|---|
+| 原等级 | 只读文本 | — | — | `client.grade_display` |
+| 新等级 | Select | 是 | 必选；不能与原等级相同 | 无 |
+
+**新等级选项**：A_urgent（A+紧急）/ A / B / C（默认）/ D / E
+
+#### 3.2.3 提交行为
+
+- **提交方式**：`hx-post="/clients/{{ id }}/change-grade/"`
+- **成功**：关闭 Modal + Toast "等级已更新" + 刷新右侧状态标签行
+- **失败（422）**：Select 下方显示错误文字
+- **HTMX 属性**：
+
+```html
+<form hx-post="/clients/{{ id }}/change-grade/"
+      hx-target="#status-badge-row"
+      hx-swap="outerHTML"
+      hx-on::after-request="if(event.detail.successful){ modalOpen = false }">
+```
+
+#### 3.2.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Modal Dialog | §7 | 弹窗容器 |
+
+---
+
+### 3.3 改状态（P0 🔴）
+
+#### 3.3.1 触发方式
+
+- **触发位置**：右侧面板 → "改状态" 按钮
+- **组件类型**：Modal Dialog
+- **尺寸**：`max-w-md`
+- **竞品截图**：`Project/fonrey/screenshots/客源/改状态.png`
+
+#### 3.3.2 表单字段规范
+
+| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 |
+|---|---|---|---|---|
+| 原状态 | 只读文本 | — | — | `client.status_display`（如"求购"） |
+| 新状态 | Select | 是 | 必选；受状态机约束（见 §4.1） | 无 |
+| 等级 | Select | 否 | — | 当前等级预填 |
+| 更改理由 | Textarea | 是 | 非空 | 无 |
+
+**新状态可选项（根据当前状态动态过滤，后端控制）**：
+- 当前 `buying`/`renting` → 可选：`suspended`（暂缓）、`public`（转公）、`bought`/`rented_done`（成交）、`invalid`（无效）
+
+#### 3.3.3 提交行为
+
+- **提交方式**：`hx-post="/clients/{{ id }}/change-status/"`
+- **成功**：关闭 Modal + Toast "状态已更新" + 刷新整个右侧面板
+- **失败（422）**：字段级错误
+- **HTMX 属性**：
+
+```html
+<form hx-post="/clients/{{ id }}/change-status/"
+      hx-target="#sidebar-panel"
+      hx-swap="outerHTML"
+      hx-on::after-request="if(event.detail.successful){ modalOpen = false }">
+```
+
+#### 3.3.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Modal Dialog | §7 | 弹窗容器 |
+
+---
+
+### 3.4 转成交（P0 🔴）
+
+#### 3.4.1 触发方式
+
+- **触发位置**：右侧面板 → "转成交" 按钮
+- **组件类型**：Modal Dialog
+- **尺寸**：`max-w-lg`
+- **竞品截图**：`Project/fonrey/screenshots/客源/转成交.png`
+
+#### 3.4.2 表单字段规范
+
+| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 |
+|---|---|---|---|---|
+| 状态 | Radio（我购/我租） | 是 | 必选 | 我购 |
+| 房源类型 | Radio（二手/新房） | 是 | 必选 | 二手 |
+| 成交房源 | 触发选择房源 Modal 的链接 | 是 | 必选 | 无 |
+| 成交日期 | Date Picker | 是 | 不能早于委托日期 | 今日 |
+| 成交价格 | Number Input | 是 | 正数，单位万元 | 无 |
+| 成交方 | 员工标签（可删除，可搜索添加） | 是 | 至少一人 | 当前归属人 |
+
+**成交房源选择：**
+
+```html
+<!-- 点击触发 "选择成交房源" 宽型 Modal（§3.5） -->
+<button type="button"
+        hx-get="/properties/select-modal/"
+        hx-target="#property-select-modal-container"
+        hx-swap="innerHTML"
+        @click="propertyModalOpen = true"
+        class="text-sm text-info-600 hover:underline">
+  + 选择成交房源
+</button>
+<!-- 已选后展示 -->
+<div id="selected-property-display" class="hidden text-sm text-neutral-800">
+  <!-- 由 §3.5 Modal 选中后注入 -->
+</div>
+<input type="hidden" name="property_id" id="selected-property-id">
+```
+
+#### 3.4.3 提交行为
+
+- **提交方式**：`hx-post="/clients/{{ id }}/convert-deal/"`
+- **成功**：关闭 Modal + Toast "已成功转为成交客" + 页面跳转至成交客详情
+- **失败（422）**：字段级错误
+- **特殊**：成功后客源状态不可逆（`bought`/`rented_done`），需在提交前显示 `hx-confirm` 二次确认
+
+```html
+<form hx-post="/clients/{{ id }}/convert-deal/"
+      hx-confirm="确认将此客户标记为成交？此操作不可撤销。"
+      hx-on::after-request="if(event.detail.successful){ window.location.href='/clients/bought/{{ id }}/' }">
+```
+
+#### 3.4.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Modal Dialog | §7 | 弹窗容器 |
+| Date Range Picker | §9 | 成交日期选择（单日模式） |
+
+---
+
+### 3.5 选择成交房源（P0 🔴）
+
+#### 3.5.1 触发方式
+
+- **触发位置**：转成交 Modal → "选择成交房源" 链接
+- **组件类型**：Modal Dialog（宽型，含搜索表格）
+- **尺寸**：`max-w-5xl`（全宽搜索表）
+- **竞品截图**：`Project/fonrey/screenshots/客源/选择成交房源.png`
+
+#### 3.5.2 表单字段规范
+
+**[搜索筛选区]**
+
+| 字段 | 组件类型 | 说明 |
+|---|---|---|
+| 关键词 | Text Input | 房源编号/楼盘地址/业主姓名/电话 |
+| 楼栋 / 单元 / 房号 | 三个联动 Text Input | 精确定位 |
+| 区域 | Select | 城区筛选 |
+| 状态 | Select | 房源状态 |
+| 相关方 | Select + 员工搜索 | 归属人筛选 |
+
+**[结果表格]**
+
+| 列名 | 宽度 | 说明 |
+|---|---|---|
+| 选择（Radio） | 48px | 单选 |
+| 房源名称 | auto | 含楼栋单元房号 |
+| 交易类型 | 80px | 买卖/租赁 |
+| 状态 | 80px | Badge 展示 |
+| 用途 | 60px | 住宅/商业 |
+| 城区商圈 | 100px | 文本 |
+| 房型 | 80px | X/X/X |
+| 楼层 | 80px | X/X |
+| 面积(㎡) | 80px | `tabular-nums` |
+
+**分页**：`共N条 | ‹ 1 2 3 … ›`（§2 Pagination 组件）
+
+#### 3.5.3 提交行为
+
+- **提交方式**：点击"确定"将选中房源 ID 写入父 Modal 的隐藏字段
+- **HTMX 属性**：搜索按钮 `hx-get` 刷新结果表
+- **Alpine 管理**：`selectedPropertyId` 状态，选中后激活"确定"按钮
+
+```html
+<div x-data="{ selectedPropertyId: null, selectedPropertyName: '' }">
+  <!-- 表格内 Radio 按钮绑定 @change="selectedPropertyId = $el.value; selectedPropertyName = ..." -->
+  <!-- 底部 Footer -->
+  <div class="flex items-center justify-between">
+    <span class="text-sm text-neutral-500">
+      已选 (<span x-text="selectedPropertyId ? 1 : 0"></span>/1)
+    </span>
+    <button :disabled="!selectedPropertyId"
+            @click="
+              document.getElementById('selected-property-id').value = selectedPropertyId;
+              document.getElementById('selected-property-display').textContent = selectedPropertyName;
+              propertyModalOpen = false;
+            "
+            class="btn-primary disabled:opacity-40 disabled:cursor-not-allowed">
+      确定
+    </button>
+  </div>
+</div>
+```
+
+#### 3.5.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Modal Dialog | §7 | 宽型容器 `max-w-5xl` |
+| Data Table | §1 | 房源选择结果表 |
+| Pagination | §2 | 表格分页 |
+
+---
+
+### 3.6 写入跟进（P0 🔴）
+
+#### 3.6.1 触发方式
+
+- **触发位置**：右侧面板 → "写跟进" 按钮；或跟进记录 Tab 内"写入跟进"按钮
+- **组件类型**：Drawer（右侧抽屉，字段较多但无需全页）
+- **尺寸**：`w-[480px]`
+- **竞品截图**：`Project/fonrey/screenshots/客源/跟进记录-写入跟进.png`
+
+#### 3.6.2 表单字段规范
+
+| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 |
+|---|---|---|---|---|
+| 跟进方式 | Select / Radio Pills | 是 | 必选 | 电话 |
+| 跟进目的 | 多选 Checkbox | 否 | — | 无 |
+| 跟进内容 | Textarea | 是 | ≥ 6 字 | 无 |
+| 跟进标签 | §17 Multi-select Tag Input | 否 | — | 无 |
+| 跟进时间 | DateTime Picker | 是 | 不能超过当前时间 | 当前时间 |
+| 附件 | 文件上传 | 否 | 最多 20MB，格式 bmp/jpg/png/gif | 无 |
+| 是否开放 | Toggle | 否 | — | 开放（`true`） |
+
+> **注**：跟进方式选项（含图标）：电话 / 上门 / 短信 / 微信 / 其他
+
+#### 3.6.3 提交行为
+
+- **提交方式**：`hx-post="/clients/{{ id }}/follow-logs/create/"`
+- **成功**：关闭 Drawer + Toast "跟进记录已保存" + `hx-trigger` 刷新跟进记录 Tab 列表
+- **失败（422）**：字段级错误
+- **HTMX 属性**：
+
+```html
+<form hx-post="/clients/{{ id }}/follow-logs/create/"
+      hx-encoding="multipart/form-data"
+      hx-target="#log-list"
+      hx-swap="afterbegin"
+      hx-on::after-request="if(event.detail.successful){ drawerOpen = false; showToast('跟进记录已保存') }">
+```
+
+#### 3.6.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Drawer | §16 | 抽屉容器 |
+| Multi-select Tag Input | §17 | 跟进标签选择 |
+| Date Range Picker | §9 | 跟进时间（单时间模式） |
+
+---
+
+### 3.7 新增带看（P0 🔴）
+
+#### 3.7.1 触发方式
+
+- **触发位置**：右侧面板 → "报备/常看" 按钮；或带看 Tab → 空状态"新增带看"
+- **组件类型**：全页表单（字段多、含文件上传、含房源关联）
+- **URL**：`/clients/<client_id>/viewings/create/`
+- **竞品截图**：`Project/fonrey/screenshots/客源/新增带看.png`
+
+#### 3.7.2 布局结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  面包屑: 客源 / 客源管理 / 新增带看                          │
+│  页面标题: 新增带看                                        │
+├──────────────────────────────────────────────────────────┤
+│  [带看信息卡片]                                           │
+│  业务类型（只读） | 带看客户（只读+查看详情链接）             │
+│  经纪人（只读）                                           │
+│  带看时间（日期+时间段）*                                   │
+│  陪看人（最多5位）+ 合作带看人（最多5位）                    │
+│  带看情况（Textarea）*                                    │
+│  附件上传                                                 │
+├──────────────────────────────────────────────────────────┤
+│  [带看房源卡片]                                           │
+│  添加房源（至少1套，最多10套）*                             │
+│  每套房源选择客户意向程度                                   │
+├──────────────────────────────────────────────────────────┤
+│  [操作按钮] 提交（primary）  保存（secondary）  取消        │
+└──────────────────────────────────────────────────────────┘
+```
+
+#### 3.7.3 表单字段规范
+
+| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 |
+|---|---|---|---|---|
+| 业务类型 | 只读文本 | — | — | 二手 |
+| 带看客户 | 只读文本 + 链接 | — | — | 当前客源 |
+| 经纪人 | 只读文本 | — | — | 当前登录人 |
+| 带看时间 | Date Picker + Time Range | 是 | 开始时间 < 结束时间 | 无 |
+| 陪看人 | 员工多选搜索 | 否 | ≤ 5 人 | 无 |
+| 合作带看人 | 员工多选搜索 | 否 | ≤ 5 人 | 无 |
+| 带看情况 | Textarea | 是 | ≥ 6 字 | 无 |
+| 附件 | 文件上传 | 否 | 每张 ≤ 20MB，bmp/jpg/png/gif | 无 |
+| 带看房源 | 动态房源选择列表 | 是 | 1-10 套 | 无 |
+| 每套意向程度 | Select | 是（每套） | 必选 | 无 |
+
+#### 3.7.4 提交行为
+
+- **提交方式**：`hx-post="/clients/{{ id }}/viewings/create/"` `hx-encoding="multipart/form-data"`
+- **成功**：跳转至带看详情页 + Toast "带看记录已提交"
+- **失败（422）**：字段级错误，保留已填内容
+- **"保存"按钮**：`hx-post="...?draft=true"`，保存草稿，不跳转
+
+#### 3.7.5 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Date Range Picker | §9 | 带看时间段选择 |
+| Dynamic Form Table | §18 | 带看房源动态增删列表 |
+| Photo Gallery Manager | §12 | 附件上传管理 |
+
+---
+
+### 3.8 新增预约带看（P0 🔴）
+
+#### 3.8.1 触发方式
+
+- **触发位置**：带看 Tab → 预约子 Tab → 空状态 or "新增预约" 按钮
+- **组件类型**：全页表单
+- **URL**：`/clients/<client_id>/viewings/appointment/create/`
+- **竞品截图**：`Project/fonrey/screenshots/客源/新增预约带看.png`
+
+#### 3.8.2 表单字段规范
+
+| 字段名 | 组件类型 | 必填 | 校验规则 | 默认值 |
+|---|---|---|---|---|
+| 业务类型 | 只读文本 | — | — | 二手 |
+| 预约客户 | 只读文本 + 链接 | — | — | 当前客源 |
+| 预约人 | 只读文本 | — | — | 当前登录人 |
+| 预约时间（日期） | Date Picker | 是 | 不早于今日 | 无 |
+| 预约时间（时刻） | Time Picker | 是 | — | 无 |
+| 陪看人 | 员工多选 | 否 | ≤ 5 人 | 无 |
+| 合作带看人 | 员工多选 | 否 | ≤ 5 人 | 无 |
+| 预约房源 | 动态房源选择列表 | 是 | 1-10 套 | 无 |
+
+#### 3.8.3 提交行为
+
+- **提交方式**：`hx-post="/clients/{{ id }}/viewings/appointment/create/"`
+- **成功**：跳转带看 Tab（预约子 Tab）+ Toast "预约带看已创建"
+- **失败（422）**：字段级错误
+
+#### 3.8.4 使用的特殊组件
+
+| 组件名 | 来源 | 用途 |
+|---|---|---|
+| Date Range Picker | §9 | 预约日期+时刻 |
+| Dynamic Form Table | §18 | 预约房源动态列表 |
+
+---
+
+## 4. 交互状态规范
+
+### 4.1 全局状态机
+
+客源状态流转（`clients.status` 字段）：
+
+```
+                  ┌──────────────────────────────┐
+                  │          buying              │
+                  │    （求购，可逆态）             │
+                  └──────────────────────────────┘
+                      │              │
+               ┌──────┘              └──────┐
+               ▼                           ▼
+        suspended（暂缓）            public（转公）
+        （可逆 → 回到 buying）         （不可逆）
+               │
+               └──────────────────────────────────┐
+                                                  ▼
+                                     bought（成交）（不可逆）
+                                     invalid（无效）（不可逆）
+```
+
+```
+                  ┌──────────────────────────────┐
+                  │          renting             │
+                  │    （求租，可逆态）             │
+                  └──────────────────────────────┘
+                      │              │
+               ┌──────┘              └──────┐
+               ▼                           ▼
+        suspended（暂缓）            public（转公）
+               │
+               └──────────────────────────────────┐
+                                                  ▼
+                                   rented_done（成交）（不可逆）
+                                   invalid（无效）（不可逆）
+```
+
+**UI 控制规则：**
+- 右侧面板"转公客"/"转成交"/"转无效"按钮在状态已为不可逆态时 `disabled` + `opacity-40 cursor-not-allowed`
+- "改状态" Modal 中新状态 Select 选项由后端根据当前状态动态过滤
+
+---
+
+### 4.2 权限控制矩阵
+
+| 操作 | 经纪人（本人） | 经纪人（他人） | 店长 | 管理员 |
+|---|---|---|---|---|
+| 查看需求信息 | ✅ | 受限 | ✅ | ✅ |
+| 编辑需求信息 | ✅ | ❌ | ✅ | ✅ |
+| 写入跟进 | ✅ | ❌ | ✅ | ✅ |
+| 查看跟进记录 | ✅ | ❌（敏感不可见） | ✅ | ✅ |
+| 查看联系人明文号码 | ✅（留痕） | ❌ | ✅（留痕） | ✅（留痕） |
+| 新增联系人 | ✅ | ❌ | ✅ | ✅ |
+| 改等级 | ✅ | ❌ | ✅ | ✅ |
+| 改状态 | ✅ | ❌ | ✅ | ✅ |
+| 转公客 | ✅ | ❌ | ✅ | ✅ |
+| 转成交 | ✅ | ❌ | ✅ | ✅ |
+| 转无效 | ✅ | ❌ | ✅ | ✅ |
+| 新增带看 | ✅ | ❌ | ✅ | ✅ |
+| 编辑相关员工 | ❌ | ❌ | ✅ | ✅ |
+| 查看操作日志 | 部分 | ❌ | ✅ | ✅ |
+| 删除跟进记录 | ✅（非敏感） | ❌ | ✅（非敏感） | ✅（非敏感） |
+
+---
+
+### 4.3 HTMX 请求规范
+
+| 操作 | hx-trigger | hx-method + URL | hx-target | hx-swap | Loading 行为 |
+|---|---|---|---|---|---|
+| Tab 切换（需求信息） | click | GET `/clients/{id}/requirements/` | `#tab-content` | innerHTML | `htmx-indicator` 骨架屏 |
+| Tab 切换（跟进记录） | click | GET `/clients/{id}/follow-logs/` | `#tab-content` | innerHTML | 骨架屏 |
+| Tab 切换（带看） | click | GET `/clients/{id}/viewings/` | `#tab-content` | innerHTML | 骨架屏 |
+| Tab 切换（客源解读） | click | GET `/clients/{id}/insights/` | `#tab-content` | innerHTML | 骨架屏 |
+| Tab 切换（智能配房） | click | GET `/clients/{id}/property-matches/` | `#tab-content` | innerHTML | 骨架屏 |
+| 跟进子 Tab 切换 | click | GET `/clients/{id}/follow-logs/?type=written` | `#log-list` | innerHTML | 列表 spinner |
+| 跟进记录日期筛选 | change | GET `/clients/{id}/follow-logs/` | `#log-list` | innerHTML | 列表 spinner |
+| 跟进记录加载更多 | click | GET `/clients/{id}/follow-logs/?page=N` | `#log-list` | beforeend | 按钮 spinner |
+| 带看子 Tab 切换 | click | GET `/clients/{id}/viewings/?type=appointment` | `#viewing-list` | innerHTML | 列表 spinner |
+| 查看联系人号码 | click | POST `/clients/{id}/contacts/{cid}/reveal-phone/` | `#phone-display-{cid}` | innerHTML | 行内 spinner |
+| 打开改等级 Modal | click | GET `/clients/{id}/change-grade/` | `#modal-container` | innerHTML | 无（预加载） |
+| 提交改等级 | submit | POST `/clients/{id}/change-grade/` | `#status-badge-row` | outerHTML | 按钮 loading |
+| 打开改状态 Modal | click | GET `/clients/{id}/change-status/` | `#modal-container` | innerHTML | 无 |
+| 提交改状态 | submit | POST `/clients/{id}/change-status/` | `#sidebar-panel` | outerHTML | 按钮 loading |
+| 打开转成交 Modal | click | GET `/clients/{id}/convert-deal/` | `#modal-container` | innerHTML | 无 |
+| 提交转成交 | submit | POST `/clients/{id}/convert-deal/` | body | — | 按钮 loading |
+| 选择成交房源搜索 | click | GET `/properties/select-modal/?q=...` | `#property-table-body` | innerHTML | 表格 spinner |
+| 打开写跟进 Drawer | click | GET `/clients/{id}/follow-logs/create/` | `#drawer-container` | innerHTML | 无 |
+| 提交写跟进 | submit | POST `/clients/{id}/follow-logs/create/` | `#log-list` | afterbegin | 按钮 loading |
+| 编辑基础信息提交 | submit | PATCH `/clients/{id}/edit-basic/` | `#sidebar-panel` | outerHTML | 按钮 loading |
+| 客源解读时段切换 | click | GET `/clients/{id}/insights/?period=7d` | `#insight-content` | innerHTML | 内容区 spinner |
+
+---
+
+## 5. 关键数据字段说明
+
+| 字段名（英文） | 显示名 | 数据类型 | 说明 |
+|---|---|---|---|
+| `client.id` | 客源 ID | UUID | 路由参数 |
+| `client.client_no` | 客户编号 | string | 格式 `{日期}{类型}{随机}` |
+| `client.title` | 需求标题 | string | 如"姚叔叔置换电梯两房（上门）" |
+| `client.status` | 状态 | enum | buying/renting/suspended/public/bought/rented_done/invalid |
+| `client.grade` | 等级 | enum | A_urgent/A/B/C/D/E |
+| `client.client_type` | 客源类型 | enum | private（私客）/public（公客）/deal（成交客） |
+| `client.source` | 客户来源 | string | 如"线下·门店接待" |
+| `client.requirement_type` | 需求类型 | enum | second_hand/new/rent |
+| `client.property_usage` | 房源用途 | enum | residential/commercial/... |
+| `client.purchase_purpose` | 购房目的 | multi-enum | 刚需/投资/学区/改善 |
+| `client.payment_method` | 付款方式 | enum | full/loan/... |
+| `client.owned_properties` | 名下房产 | string | 自由文本 |
+| `client.loan_record` | 贷款记录 | boolean | 有/无 |
+| `client.id_type` | 证件类型 | enum | id_card/passport/... |
+| `client.id_number` | 证件号码 | string（加密） | AES 加密，展示时脱敏 |
+| `client.preferred_school` | 意向学校 | string list | 可多条 |
+| `client.school_start_year` | 入学时间 | year | — |
+| `client.last_follow_at` | 最近跟进时间 | datetime | — |
+| `client.created_at` | 委托日期 | datetime | — |
+| `client.activity_level` | 活跃度 | int | Celery 每日计算 |
+| `client_contacts.name` | 联系人姓名 | string | — |
+| `client_contacts.phone_hash` | 手机号 Hash | string | SHA-256，用于重复检测 |
+| `client_contacts.phone_encrypted` | 手机号密文 | string | AES 加密，展示时解密脱敏 |
+| `client_contacts.gender` | 性别 | enum | male/female |
+| `client_contacts.wechat` | 微信号 | string | — |
+| `client_requirements.price_min/max` | 总价范围 | decimal | 万元 |
+| `client_requirements.area_min/max` | 面积范围 | decimal | ㎡ |
+| `client_requirements.rooms` | 居室 | string | — |
+| `client_requirements.floor_preference` | 楼层偏好 | multi-enum | — |
+| `client_requirements.preferred_districts` | 意向商圈 | string list | — |
+| `client_follow_logs.log_type` | 跟进类型 | enum | written/modified/sensitive_view/other/system |
+| `client_follow_logs.follow_method` | 跟进方式 | enum | phone/door/sms/wechat/other |
+| `client_follow_logs.content` | 跟进内容 | text | — |
+| `client_follow_logs.is_open` | 是否开放 | boolean | — |
+| `client_viewings.viewing_time` | 带看时间 | datetime | — |
+| `client_viewings.situation` | 带看情况 | text | — |
+| `client_viewings.viewing_count` | 带看次数 label | string | 一看/二看/... |
+| `client_property_matches.match_type` | 配房类型 | enum | recorded/system |
+| `client_property_matches.group_label` | 分组标签 | string | 优质户型/降价/热门/新上 |
+| `related_staff.role` | 员工角色 | enum | first_recorder（首录人）/owner（归属人） |
+| `related_staff.joined_at` | 参与时间 | datetime | — |
+
+---
+
+## 6. 竞品截图对应关系
+
+| 截图路径 | 对应功能 | 对应文档章节 | 采纳的设计要点 |
+|---|---|---|---|
+| `私客详情.png` | 详情页整体框架 | §2.1 | 左右双栏布局；右侧 Banner 使用品牌主色（竞品橙色改为 Teal）；Tab 导航在左侧内容区顶部 |
+| `需求信息.png` | 需求信息 Tab 内容 | §2.2 | 3 列字段网格；右上角蓝色"编辑"链接；空字段显示 `-` |
+| `跟进记录-全部.png` | 跟进记录时间线 | §2.3 | 日期分组橙色圆点；条目卡片带类型 Badge；"已开放"/"隐藏"小字操作链接 |
+| `跟进记录-写入跟进.png` | 跟进子 Tab + 扩展筛选 | §2.3 | 跟进目的多选展开/收起；pill 式子 Tab 导航 |
+| `跟进记录-敏感信息跟进.png` | 敏感信息跟进空状态 | §2.3.5 | 空状态文案"暂无跟进" |
+| `跟进记录-修改跟进.png` | 修改跟进空状态 | §2.3.5 | 同上 |
+| `跟进记录-其他跟进.png` | 其他跟进（系统日志） | §2.3 | 【新增私客】等系统类型条目，无操作按钮 |
+| `带看.png` | 带看 Tab 内容 | §2.4 | 预约/带看子 Tab；带看次数橙色 Badge；"详情 ›" 链接 |
+| `新增带看.png` | 新增带看全页表单 | §3.7 | 分两个卡片区域（带看信息 + 带看房源）；三个操作按钮（提交/保存/取消） |
+| `新增预约带看.png` | 新增预约带看全页表单 | §3.8 | 日期+时刻分两个选择器；不含"保存"按钮（预约只有提交/取消） |
+| `客源解读.png` | 客源解读 Tab | §2.5 | 时段筛选 Pill；活跃行为卡片；三个甜甜圈图（MVP 用百分比文字代替） |
+| `二手配房.png` | 二手配房 Tab | §2.6 | 分组标题 + 房源卡片列表；录客/系统配房子 Tab；"批量分享"次要按钮 |
+| `客源信息概览.png` | 右侧客源信息面板 | §2.7 | 字段列表 + 三主按钮 + 2列操作网格；"展开全部"收起切换 |
+| `编辑基础信息.png` | 编辑基础信息 Modal | §3.1 | 宽型 Modal；多字段含联动（证件类型 → 证件号）；意向学校可动态添加 |
+| `改等级.png` | 改等级 Modal | §3.2 | 极简 2 字段；`max-w-sm` |
+| `改状态.png` | 改状态 Modal | §3.3 | 4 字段含 Textarea；状态选项后端动态控制 |
+| `转成交.png` | 转成交 Modal | §3.4 | Radio 选购/租、二手/新房；成交方员工标签组件 |
+| `选择成交房源.png` | 选择成交房源宽型 Modal | §3.5 | 搜索 + 表格 + 分页；Radio 单选；"已选(0/1)"状态控制确定按钮 |
+| `联系人.png` | 联系人面板 | §2.8 | 号码脱敏；"查看号码"留痕确认；接通/拨打次数展示 |
+| `相关员工.png` | 相关员工面板 | §2.9 | 首录人/归属人标签；右侧电话图标；"编辑"仅管理员可见 |
+
+---
+
+## 7. 实现优先级与工期估算
+
+| 页面/功能 | 优先级 | 特殊组件复杂度 | 工期估算（前端） |
+|---|---|---|---|
+| 详情页整体框架（双栏 + Tab） | P0 🔴 | ⭐ Tab Navigation | 1 天 |
+| 需求信息 Tab（只读 + 编辑链接） | P0 🔴 | ⭐ | 0.5 天 |
+| 右侧信息概览面板（字段 + 操作网格） | P0 🔴 | ⭐ | 1 天 |
+| 跟进记录 Tab（时间线 + 子 Tab + 筛选） | P0 🔴 | ⭐⭐ Timeline + Date Range Picker | 2 天 |
+| 写入跟进 Drawer | P0 🔴 | ⭐⭐ Drawer + Multi-select Tag | 1.5 天 |
+| 带看 Tab（时间线） | P0 🔴 | ⭐ | 1 天 |
+| 新增带看（全页表单） | P0 🔴 | ⭐⭐ Dynamic Form Table + 文件上传 | 2 天 |
+| 新增预约带看（全页表单） | P0 🔴 | ⭐ Date Picker | 1 天 |
+| 改等级 Modal | P0 🔴 | ⭐ | 0.5 天 |
+| 改状态 Modal | P0 🔴 | ⭐ | 0.5 天 |
+| 转成交 Modal | P0 🔴 | ⭐⭐ | 1 天 |
+| 选择成交房源 Modal（搜索表格） | P0 🔴 | ⭐⭐ Data Table + Pagination | 1.5 天 |
+| 联系人面板（含查看号码留痕） | P0 🔴 | ⭐ | 0.5 天 |
+| 相关员工面板 | P0 🔴 | ⭐ | 0.5 天 |
+| 编辑基础信息 Modal（完整表单） | P1 🟡 | ⭐⭐ Multi-select | 1.5 天 |
+| 客源解读 Tab（数据图表） | P1 🟡 | ⭐⭐ 图表组件 | 2 天 |
+| 二手配房 Tab（房源卡片网格） | P1 🟡 | ⭐⭐ | 1.5 天 |
+| 待办提醒区块 | P1 🟡 | ⭐ | 0.5 天 |
+| 收藏功能 | P1 🟡 | ⭐ | 0.5 天 |
+| 查看操作日志 | P2 ⚫ | ⭐ | 0.5 天 |
+| **合计 P0** | — | — | **~14.5 天** |
+| **合计 P1** | — | — | **~6 天** |
+| **合计 P2** | — | — | **~0.5 天** |
+
+---
+
+## 8. 开放问题（待决策）
+
+| # | 问题 | 影响范围 | 待确认方 |
+|---|---|---|---|
+| 1 | 竞品 Banner 颜色为橙色 `#f5774a`，本系统使用 Teal `primary-600`。确认是否在客源详情页 Banner 引入橙色辅助色，还是统一用 Teal？ | §2.7 右侧面板 Banner | 产品/设计 |
+| 2 | 跟进目的选项约 25 个，竞品截图可见，是否与 PRD 中枚举完全一致？需后端确认字段枚举值。 | §2.3 跟进筛选 | 后端 |
+| 3 | "报备/常看" 按钮的业务逻辑：是打开带看表单还是单独的"报备"功能？竞品未见明确说明。 | §2.7 快捷操作 | 产品 |
+| 4 | 联系人"查看号码"是否需要每次查看都弹出确认对话框（`hx-confirm`），还是首次查看确认即可（本 session 内缓存权限）？ | §2.8 | 产品/法务 |
+| 5 | 带看房源"意向程度"的选项枚举值是什么？竞品未完整显示。 | §3.7 新增带看 | 后端 |
+| 6 | "转公客"操作是否需要理由 Textarea（竞品未显示此 Modal）？直接 POST 还是需要二次确认弹窗？ | §2.7 状态变更 | 产品 |
+| 7 | 客源解读 Tab 数据是否 MVP 就需要真实 AI 接口，还是 P1 阶段可先用静态假数据 + 占位图？ | §2.5 | 产品/后端 |
+| 8 | 右侧面板"展开全部"默认折叠后显示几个字段？竞品显示约 10 个，全部展开约 14 个，需确认默认展示数量。 | §2.7 基础字段列表 | 产品 |
+| 9 | 二手配房"批量分享"的分享目标是什么渠道（微信/短信/链接复制）？需确认 P1 实现范围。 | §2.6 | 产品 |
+| 10 | `client_status_logs` 是否需要在详情页"查看操作日志"入口展示？竞品有此链接但 PRD 未详细说明展示方式（独立页 or Drawer）。 | P2 操作日志 | 产品 |
diff --git a/wiki/concepts/AgentFileFormat.md b/wiki/concepts/AgentFileFormat.md
new file mode 100644
index 00000000..888e12db
--- /dev/null
+++ b/wiki/concepts/AgentFileFormat.md
@@ -0,0 +1,27 @@
+---
+title: "AgentFileFormat"
+type: concept
+tags: []
+---
+
+## Definition
+Agent 定义文件采用 `.md` + YAML frontmatter 格式，是 Agency 项目与 GitHub Copilot 的共同标准文件格式。
+
+## Core Properties
+- **格式**：`Markdown 文本 + YAML frontmatter 元数据`
+- **Frontmatter 字段**（典型）：`name`、`description`、`instructions`、`tools`、`model` 等
+- **兼容平台**：The Agency agents、GitHub Copilot agents、Cursor（通过 `.mdc` 转换）
+
+## Usage
+1. **The Agency**：所有 agent 定义均使用此格式，存储于 `agency-agents/` 目录下
+2. **GitHub Copilot**：直接读取 `.md` + YAML frontmatter，无需转换
+3. **Cursor**：通过 `install.sh --tool cursor` 转换为 `.mdc` 规则文件
+
+## Aliases
+- Agent Definition Format
+- Agency Agent Format
+
+## Related
+- [[GitHubCopilot]] — 使用此格式的 IDE
+- [[TheAgency]] — 使用此格式的核心项目
+- [[Cursor]] — 支持此格式（需转换）的 IDE
diff --git a/wiki/entities/BackendArchitect.md b/wiki/entities/BackendArchitect.md
new file mode 100644
index 00000000..893eac79
--- /dev/null
+++ b/wiki/entities/BackendArchitect.md
@@ -0,0 +1,44 @@
+---
+title: "Backend Architect"
+type: entity
+tags: [the-agency, engineering, multi-agent]
+last_updated: 2026-04-26
+---
+
+## Overview
+The Agency 工程部门的资深后端架构师 Agent，专门负责可扩展系统设计、数据库架构、API 开发与云基础设施构建。
+
+## Role
+- **Division**: Engineering
+- **Personality**: Strategic, security-focused, scalability-minded, reliability-obsessed
+- **Type**: Person（AI Agent 角色）
+
+## Core Deliverables
+- 系统架构设计文档（高阶架构/服务分解/数据流）
+- 数据库 Schema 设计（PostgreSQL/MySQL 及索引规范）
+- API 设计与规范（REST/GraphQL/gRPC）
+- 云基础设施配置（AWS/GCP/Azure）
+
+## Memory Integration
+Backend Architect 是 The Agency 中首批深度集成 MCP Memory 的 Agent 之一：
+
+- **会话启动**：检索标签含 `backend-architect` + 项目名的历史记忆，防止重复讨论已做决策
+- **架构决策**：以标签化快照持久化（`backend-architect` + 项目名 + 主题标签如 `database-schema`/`api-design`/`auth-strategy`），包含决策理由
+- **交付物完成**：主动记忆并标记接收方（如 `frontend-developer` + `api-spec`），供下游 Agent 查找
+- **QA 失败**：检索最近良好检查点并回滚，而非手动撤销变更链
+
+## Success Metrics
+- API 响应时间 95 百分位持续低于 200ms
+- 系统可用性超过 99.9%
+- 数据库查询平均低于 100ms（含正确索引）
+- 安全审计零高危漏洞
+- 峰值负载下成功处理 10 倍正常流量
+
+## References
+- Source: [[backend-architect-with-memory]]
+- Coordinated by: [[agents-orchestrator]]
+- Enabled by: [[mcp-builder-agent]]
+
+## Aliases
+- Backend Architect with Memory
+- backend-architect-with-memory
diff --git a/wiki/entities/GitHubCopilot.md b/wiki/entities/GitHubCopilot.md
new file mode 100644
index 00000000..bd8ff808
--- /dev/null
+++ b/wiki/entities/GitHubCopilot.md
@@ -0,0 +1,18 @@
+---
+title: "GitHubCopilot"
+type: entity
+tags: []
+---
+
+## Identity
+GitHub Copilot — GitHub 开发的 AI 编程助手，通过 GitHub 官方集成支持用户自定义 agent。
+
+## Role in Wiki
+- 使用 [[AgentFileFormat]] 作为 agent 定义标准
+- 通过 [[TheAgency]] 提供 147+ 专业化 agent
+- 用户级别全局生效（安装到 `~/.github/agents/` 或 `~/.copilot/agents/`）
+
+## Related
+- [[github-copilot]] — 集成文档
+- [[AgentFileFormat]] — 支持的文件格式
+- [[TheAgency]] — agent 来源
diff --git a/wiki/entities/Windsurf.md b/wiki/entities/Windsurf.md
new file mode 100644
index 00000000..b6b2f6e4
--- /dev/null
+++ b/wiki/entities/Windsurf.md
@@ -0,0 +1,25 @@
+---
+title: "Windsurf"
+type: entity
+tags: []
+sources: ["windsurf-integration", "integrations-readme", "Vibe-Coding"]
+last_updated: 2026-04-25
+---
+
+## Overview
+Windsurf 是 Codeium 开发的 AI 代码编辑器，支持通过 `.windsurfrules` 文件注入自定义规则和 Agent 角色定义。
+
+## Details
+- **开发者**：Codeium
+- **集成方式**：`.windsurfrules` 文件，项目级生效
+- **Agent 来源**：The Agency Agent roster（147 个 Agent 跨 12 部门）
+- **激活方式**：在 Windsurf prompt 中按名称引用 Agent（如 "Use the Frontend Developer agent to build this component."）
+- **安装脚本**：`install.sh --tool windsurf`，从项目根目录执行
+- **规则生成**：`convert.sh --tool windsurf` 重新生成规则文件
+
+## Aliases
+- Windsurf IDE
+- Codeium Windsurf
+
+## Connections
+- The Agency 的项目级 IDE 集成生态成员之一，与 [[Cursor Integration]]（.mdc）和 [[Aider Integration]]（CONVENTIONS.md）构成互补
diff --git a/wiki/index.md b/wiki/index.md
index bbb9f6c4..8ac856db 100644
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -4,9 +4,19 @@
 - [Overview](overview.md) — living synthesis
 
 ## Sources
-- [2026-05-02] [Claude Code Integration](sources/claude-code-integration.md)
-- [2026-04-25] [Aider Integration](sources/readme.md)
-- [2026-04-25] [Aider Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [Backend Architect with Memory](sources/backend-architect-with-memory.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
+- [2026-04-25] [OpenCode Integration](sources/readme.md)
 - [2026-04-25] [Historian Agent Personality](sources/academic-historian.md)
 - [2026-04-25] [Academic Geographer](sources/academic-geographer.md)
 - [2026-04-25] [Academic Narratologist](sources/academic-narratologist.md)
@@ -393,7 +403,7 @@
 - [2026-04-21] [workflow-with-memory](sources/workflow-with-memory.md) — (expected: wiki/sources/workflow-with-memory.md — source missing)
 - [2026-04-21] [workflow-landing-page](sources/workflow-landing-page.md) — (expected: wiki/sources/workflow-landing-page.md — source missing)
 - [2026-04-21] [workflow-startup-mvp](sources/workflow-startup-mvp.md) — (expected: wiki/sources/workflow-startup-mvp.md — source missing)
-- [2026-04-21] [Aider Integration](sources/readme.md)
+- [2026-04-21] [OpenCode Integration](sources/readme.md)
 - [2026-04-21] [workflow-book-chapter](sources/workflow-book-chapter.md) — (expected: wiki/sources/workflow-book-chapter.md — source missing)
 - [2026-04-21] [support-executive-summary-generator](sources/support-executive-summary-generator.md) — (expected: wiki/sources/support-executive-summary-generator.md — source missing)
 - [2026-04-21] [support-finance-tracker](sources/support-finance-tracker.md) — (expected: wiki/sources/support-finance-tracker.md — source missing)
@@ -409,12 +419,6 @@
 - [2026-04-21] [testing-reality-checker](sources/testing-reality-checker.md) — (expected: wiki/sources/testing-reality-checker.md — source missing)
 - [2026-04-21] [testing-workflow-optimizer](sources/testing-workflow-optimizer.md) — (expected: wiki/sources/testing-workflow-optimizer.md — source missing)
 - [2026-04-21] [testing-api-tester](sources/testing-api-tester.md) — (expected: wiki/sources/testing-api-tester.md — source missing)
-- [2026-04-21] [Aider Integration](sources/readme.md)
-- [2026-04-21] [Aider Integration](sources/readme.md)
-- [2026-04-21] [Aider Integration](sources/readme.md)
-- [2026-04-21] [Aider Integration](sources/readme.md)
-- [2026-04-21] [backend-architect-with-memory](sources/backend-architect-with-memory.md) — (expected: wiki/sources/backend-architect-with-memory.md — source missing)
-- [2026-04-21] [Aider Integration](sources/readme.md)
 - [2026-04-20] [security](sources/security.md) — (expected: wiki/sources/security.md — source missing)
 - [2026-04-20] [llm-wiki](sources/llm-wiki.md) — (expected: wiki/sources/llm-wiki.md — source missing)
 - [2026-04-20] [baoyu-skills](sources/baoyu-skills.md) — (expected: wiki/sources/baoyu-skills.md — source missing)
@@ -437,15 +441,10 @@
 - [legal-billing-time-tracking](sources/legal-billing-time-tracking.md) — (expected: wiki/sources/legal-billing-time-tracking.md — source missing)
 - [legal-client-intake](sources/legal-client-intake.md) — (expected: wiki/sources/legal-client-intake.md — source missing)
 - [hospitality-guest-services](sources/hospitality-guest-services.md) — (expected: wiki/sources/hospitality-guest-services.md — source missing)
-- [Aider Integration](sources/readme.md)
+- [OpenCode Integration](sources/readme.md)
 - [marketing-seo-specialist](sources/marketing-seo-specialist.md) — (expected: wiki/sources/marketing-seo-specialist.md — source missing)
 - [marketing-agentic-search-optimizer](sources/marketing-agentic-search-optimizer.md) — (expected: wiki/sources/marketing-agentic-search-optimizer.md — source missing)
-- [Aider Integration](sources/readme.md)
-- [Aider Integration](sources/readme.md)
-- [Aider Integration](sources/readme.md)
-- [Aider Integration](sources/readme.md)
-- [Aider Integration](sources/readme.md)
-- [Aider Integration](sources/readme.md)
+- [OpenCode Integration](sources/readme.md)
 - [finance-bookkeeper-controller](sources/finance-bookkeeper-controller.md) — (expected: wiki/sources/finance-bookkeeper-controller.md — source missing)
 - [finance-fpa-analyst](sources/finance-fpa-analyst.md) — (expected: wiki/sources/finance-fpa-analyst.md — source missing)
 - [finance-investment-researcher](sources/finance-investment-researcher.md) — (expected: wiki/sources/finance-investment-researcher.md — source missing)
@@ -575,6 +574,7 @@
 - [AWS-Step-Functions](entities/AWS-Step-Functions.md)
 - [Axton](entities/Axton.md)
 - [Azure](entities/Azure.md)
+- [BackendArchitect](entities/BackendArchitect.md)
 - [baoyu](entities/baoyu.md)
 - [BehavioralNudgeEngine](entities/BehavioralNudgeEngine.md)
 - [bitwarden](entities/bitwarden.md)
@@ -637,6 +637,7 @@
 - [Gamma-AI](entities/Gamma-AI.md)
 - [GDPR](entities/GDPR.md)
 - [Gitea](entities/Gitea.md)
+- [GitHubCopilot](entities/GitHubCopilot.md)
 - [Gitmoji](entities/Gitmoji.md)
 - [glances](entities/glances.md)
 - [gog](entities/gog.md)
@@ -790,6 +791,7 @@
 - [Vinay](entities/Vinay.md)
 - [VMware](entities/VMware.md)
 - [WildCard](entities/WildCard.md)
+- [Windsurf](entities/Windsurf.md)
 - [Xiaohongshu](entities/Xiaohongshu.md)
 - [XR-Cockpit-Interaction-Specialist](entities/XR-Cockpit-Interaction-Specialist.md)
 - [XR-Immersive-Developer](entities/XR-Immersive-Developer.md)
@@ -831,6 +833,7 @@
 - [Agent-Routing-Rules](concepts/Agent-Routing-Rules.md)
 - [Agent-Specialization](concepts/Agent-Specialization.md)
 - [Agent-Template](concepts/Agent-Template.md)
+- [AgentFileFormat](concepts/AgentFileFormat.md)
 - [AGENTS.md](concepts/AGENTS.md.md)
 - [Agile-Ceremonies](concepts/Agile-Ceremonies.md)
 - [AgilePractices](concepts/AgilePractices.md)
diff --git a/wiki/log.md b/wiki/log.md
index c7f12b1a..4f68c181 100644
--- a/wiki/log.md
+++ b/wiki/log.md
@@ -1,3 +1,84 @@
+## [2026-05-05] ingest | OpenCode Integration
+- Source file: Agent/agency-agents/integrations/opencode/README.md
+- Status: ✅ 成功摄入
+- Summary: OpenCode Integration——The Agency Agent roster 与 OpenCode 编辑器的子 Agent 集成方案，通过 `./scripts/install.sh --tool opencode` 安装，将 .md 格式 Agent 转换为 OpenCode 的 `.opencode/agents/` 格式。核心机制：`mode: subagent` 使 Agent 仅在 `@agent-name` 触发时出现，不在 Tab 循环中占位；命名颜色自动映射为十六进制颜色代码。支持项目级和全局级两种安装范围。与 [[readme|Cursor Integration]]（.mdc）、[[github-copilot|GitHub Copilot Integration]]、[[windsurf-integration|Windsurf Integration]] 同属 The Agency 多 IDE 集成生态。
+- Concepts created: 无（Subagent、OpenCode 仅在本文档出现1次，未达创建阈值）
+- Entities updated: 无（[[The Agency]] 已在其他来源中覆盖，无需新建 OpenCode entity）
+- Source page: wiki/sources/readme.md
+- Notes: 无内容冲突。index.md 和 overview.md 已更新。
+
+## [2026-05-04] ingest | Kimi Code CLI Integration
+- Source file: Agent/agency-agents/integrations/kimi/README.md
+- Status: ✅ 成功摄入
+- Summary: Kimi Code CLI Integration——将 Agency agents 项目转换为 Kimi Code CLI 可用的 agent specification，通过 `convert.sh` 和 `install.sh` 脚本生成 `agent.yaml` + `system.md` 目录结构，安装到 `~/.config/kimi/agents/`。使用 `--agent-file` 标志激活，支持 `extend: default` 继承 Kimi 内置工具集。与 [[readme|Cursor Integration]] 和 [[github-copilot|GitHub Copilot Integration]] 同属 The Agency 多 IDE/CLI 集成生态。
+- Concepts created: 无（YAML配置文件、Agent规范、SystemPrompt 均仅在本文档出现1次，未达创建阈值）
+- Entities created: 无（Kimi Code CLI、Moonshot AI 均仅在本文档出现1次，未达创建阈值）
+- Source page: wiki/sources/kimi.md
+- Notes: 无内容冲突。index.md 和 overview.md 已更新。
+
+## [2026-05-04] ingest | Antigravity Integration
+- Source file: Agent/agency-agents/integrations/antigravity/README.md
+- Status: ✅ 成功摄入
+- Summary: Antigravity Integration——The Agency Agent roster 与 Antigravity/Gemini 的集成方案，通过 `./scripts/install.sh --tool antigravity` 将全部 Agent roster 转换为 Antigravity SKILL.md 文件，复制到 `~/.gemini/antigravity/skills/`。所有 skill slug 统一使用 `agency-` 前缀避免命名冲突。用户可通过自然语言激活对应 agent。与 [[Cursor Integration]]（.mdc 规则）、[[Windsurf Integration]]（.windsurfrules）、[[GitHub Copilot Integration]]（原生兼容）共同构成 The Agency 的完整多平台集成生态。
+- Concepts updated: 无需更新（SKILL.md Format、Antigravity Skills、Skill Prefix Convention 等概念已在其他来源中覆盖）
+- Entities created: 无（Antigravity/Gemini、Agency Agents 均已在其他来源中出现，无需新建）
+- Source page: wiki/sources/antigravity-integration.md
+- Notes: 无内容冲突。index.md 和 overview.md 已更新。与 [[Cursor Integration]] 在"多 IDE 集成覆盖"定位上存在功能重叠，已在 Contradictions 节标注区分（前者 GUI 编辑器生态，后者 Gemini 生态）。
+
+## [2026-05-03] ingest | Windsurf Integration
+- Source file: Agent/agency-agents/integrations/windsurf/README.md
+- Status: ✅ 成功摄入
+- Summary: Windsurf Integration——The Agency Agent roster 与 Windsurf 编辑器的集成方案，通过 `.windsurfrules` 文件将 Agent roster 聚合为单一规则文件，install.sh 从项目根目录安装，项目级生效。在 prompt 中按名称引用 Agent 即可激活。与 [[Cursor Integration]]（.mdc）和 [[Aider Integration]]（CONVENTIONS.md）同为项目级 IDE 集成，共同构成 The Agency 的多 IDE 覆盖体系。
+- Concepts updated: [[Agent-Activation-Pattern]]（补充 Windsurf 应用场景）、[[Project-Scoped-Tools]]（替代 Project-Scoped-Integration，与 integrations-readme.md 保持一致）
+- Entities created: [[Windsurf]]（Windsurf.md，Codeium 开发的 AI 代码编辑器，跨 3 个 source 页面出现）
+- Source page: wiki/sources/windsurf-integration.md
+- Notes: 无内容冲突。index.md 和 overview.md 已更新。slug 避免与同名 readme.md 冲突（已有多条同名占位条目），采用 windsurf-integration.md。
+
+## [2026-04-26] ingest | Gemini CLI Integration
+- Source file: Agent/agency-agents/integrations/gemini-cli/README.md
+- Status: ✅ 成功摄入
+- Summary: Gemini CLI Integration——将 61 个 Agency Agents 打包为 Gemini CLI 扩展插件，安装到 `~/.gemini/extensions/agency-agents/`，安装后可在 Gemini CLI 中通过自然语言按名称激活 Agent skill（如 `frontend-developer`）。
+- Entities created: 无（Agency Agents 已在其他来源中出现，无需新建；Agent Skill 和 Extension 机制未达到 ≥2 次出现阈值）
+- Concepts created: 无
+- Source page: wiki/sources/gemini-cli.md
+- Notes: 无内容冲突。
+
+## [2026-05-03] ingest | Cursor Integration
+- Source file: Agent/agency-agents/integrations/cursor/README.md
+- Status: ✅ 成功摄入
+- Summary: Cursor Integration——将 Agency roster 中的 agent 转换为 Cursor `.mdc` 规则文件，安装到项目根目录的 `.cursor/rules/` 下，**项目级别生效**。支持 `@agent-slug` 引用特定 agent，或通过 `alwaysApply: true` 设为常驻规则。与 Aider Integration 形成 IDE 集成互补。
+- Entities created: 无（Agency Agents 和 Cursor 未达到 ≥2 次出现阈值）
+- Concepts created: 无（Cursor.mdc Rules/Agency Roster/Project-Scoped Rules 仅出现 1 次，不满足 ≥2 次阈值，均以 wikilink 形式记录于 Source page）
+- Source page: wiki/sources/readme.md
+- Notes: 无内容冲突。overview.md 已新增 Cursor Integration 段落于 The Agency 贡献指南段落后。与 [[Aider Integration]] 存在功能重叠（两个工具都将 Agency agents 集成到不同 IDE），已在 Source page Contradictions 节记录。
+
+## [2026-05-03] ingest | OpenClaw Integration
+- Source file: Agent/agency-agents/integrations/openclaw/README.md
+- Status: ✅ 成功摄入
+- Summary: The Agency Agent 与 OpenClaw 多智能体框架的集成方案——通过 convert.sh 将 Agent 转换为 OpenClaw workspace（含 SOUL.md/AGENTS.md/IDENTITY.md），install.sh 复制到 ~/.openclaw/agency-agents/，openclaw gateway restart 使 Agent 通过 agentId 可用。slug 采用 openclaw-integration.md 以避免与同名 Aider Integration 的 readme.md 冲突。
+- Entities created: 无（OpenClaw/The-Agency/OpenClaw-Gateway 在 overview.md 已出现多次，不满足新建阈值）
+- Concepts created: 无（OpenClaw-Workspace/Workspace-Based-Agent/Agent-Conversion 仅在源页面内出现 1 次，不满足 ≥2 次阈值，均以 wikilink 形式记录于 Source page）
+- Source page: wiki/sources/openclaw-integration.md
+- Notes: 无内容冲突。overview.md 已有 OpenClaw 相关内容，无需修订。integrations-readme.md 已有 OpenClaw wikilink，无需重复创建 Entity 页面。
+
+## [2026-05-02] ingest | MCP Memory Integration
+- Source file: Agent/agency-agents/integrations/mcp-memory/README.md
+- Status: ✅ 成功摄入
+- Summary: MCP Memory Integration——通过在 Agent 提示词中加入标准化的 Memory Integration 段落，为 The Agency 中任意 Agent 添加跨会话持久记忆能力。MCP Memory Server 提供 remember/recall/rollback/search 四个核心工具。Rollback 是杀手级功能：QA 失败或架构决策出错时恢复到已知良好状态，无需手动 undo。无代码修改，仅需在 prompt 中加入标准化指令段。
+- Entities created: 无（The-Agency 已存在于 entities/，Backend-Architect/Startup-MVP-Workflow 仅出现 1 次，均不满足 ≥2 次阈值）
+- Concepts created: 无（Cross-Session-Memory/Handoff-Continuity/Rollback/Memory-Integration-Pattern/MCP-Memory-Tools/Checkpoint 均仅出现 1 次，均不满足 ≥2 次阈值，均以 wikilink 形式记录于 Source page）
+- Source page: wiki/sources/mcp-memory-integration.md
+- Notes: 无内容冲突。index.md 和 overview.md 已更新（新增 MCP Memory Integration 段落于 The Agency 段落后）。
+
+## [2026-05-02] ingest | Claude Code Integration
+- Source file: Agent/agency-agents/integrations/claude-code/README.md
+- Status: ✅ 成功摄入
+- Summary: The Agency Agent 资产与 Claude Code 的原生集成方案。The Agency 从一开始就为 Claude Code 构建，无需任何格式转换，Agent 天然使用 `.md` + YAML frontmatter 格式。通过 install.sh 或手动复制将 Agent 部署到 `~/.claude/agents/`，在 Claude Code 会话中通过名称引用即可激活对应 Agent。
+- Entities created: 无（Claude Code/The Agency 均仅出现 1 次，不满足 ≥2 次阈值，以 wikilink 形式记录于 Source page）
+- Concepts created: 无（Agent-Activation-Pattern 仅出现 1 次，不满足 ≥2 次阈值）
+- Source page: wiki/sources/claude-code-integration.md
+- Notes: 无内容冲突。slug 冲突解决：原 Aider Integration 已占用 `readme.md`，Claude Code README 同名，故采用 `claude-code-integration.md`。overview.md 无需修订（内容属配置说明，集成概述由 integrations-readme.md 覆盖）。
+
 ## [2026-05-02] ingest | Aider Integration
 - Source file: Agent/agency-agents/integrations/aider/README.md
 - Status: ✅ 成功摄入
@@ -3303,3 +3384,19 @@
 - Entities created: [[The-Agency]]（The Agency 多智能体系统组织，147 个 Agent 跨 12 部门）
 - Source page: wiki/sources/study-abroad-advisor.md
 - Notes: index.md 中原有 "source missing" 占位条目（2026-04-20）已替换为完整条目；overview.md Specialized 部门新增 Study Abroad Advisor 条目置于 lsp-index-engineer 之后；与 corporate-training-designer 同属服务型 Agent 已在 overview.md 建立关联。4 个 Concept 页面（Holistic-Admissions/UCAS-System/IANG-Visa/Grandes-Ecoles）和 1 个 Entity 页面（The-Agency）创建前均已做去重检查，确认均不存在。
+
+## [2026-04-26] ingest | Backend Architect with Memory
+- Source file: Agent/agency-agents/integrations/mcp-memory/backend-architect-with-memory.md
+- Status: ✅ 成功摄入
+- Summary: 具备持久记忆能力的后端架构师 AI Agent 设计规范——专注于可扩展系统设计（微服务/Serverless）、数据库架构（PostgreSQL/索引/CQRS）、API 开发（REST/GraphQL/gRPC）与云基础设施。核心价值：MCP Memory 集成实现跨会话记忆召回，防止重复讨论已做决策；架构决策以标签化快照持久化；交付物完成后主动标记接收方供下游 Agent 查找；QA 失败时自动回滚到上一个良好检查点。
+- Entities created: BackendArchitect（The Agency 工程部门资深后端架构师 Agent，满足 ≥2 次阈值）
+- Concepts created: 无（MicroservicesArchitecture/CQRS/EventSourcing/ServerlessArchitecture/DatabaseIndexing/CircuitBreaker/DefenseInDepth 均仅出现 1 次，均不满足 ≥2 次阈值，均以 wikilink 形式记录于 Source page）
+- Source page: wiki/sources/backend-architect-with-memory.md
+## [2026-04-25] ingest | GitHub Copilot Integration
+- Source file: Agent/agency-agents/integrations/github-copilot/README.md
+- Status: ✅ 成功摄入
+- Summary: The Agency 与 GitHub Copilot 的开箱即用集成——无需转换，`.md` + YAML frontmatter 格式原生兼容。一键安装 `./scripts/install.sh --tool copilot`，或手动复制到 `~/.github/agents/` 或 `~/.copilot/agents/`。用户可在 Copilot 会话中通过名称激活特定 agent。
+- Concepts created: AgentFileFormat
+- Entities created: GitHubCopilot
+- Source page: wiki/sources/github-copilot.md
+- Notes: 无内容冲突。index.md（Sources + Concepts + Entities）、overview.md（替换 Cursor Integration 段落为 GitHub Copilot Integration）、log.md 均已更新。Concept AgentFileFormat.md 已创建于 wiki/concepts/，Entity GitHubCopilot.md 已创建于 wiki/entities/。
diff --git a/wiki/overview.md b/wiki/overview.md
index 28a0a78c..6d40aa8d 100644
--- a/wiki/overview.md
+++ b/wiki/overview.md
@@ -9,6 +9,20 @@ The wiki covers two major multi-agent frameworks: **The Agency** (agency-agents)
 
 **The Agency 贡献指南**（[[contributing_zh-cn]] + [[contributing]] 英文原版）：The Agency 项目贡献者指南——核心贡献方式：①创建全新智能体（8大分类：engineering/design/marketing/product/project-management/testing/support/spatial-computing/specialized）；②优化现有智能体；③分享成功案例；④反馈问题。智能体设计五原则：**鲜明性格**（拒绝通用人设）、**明确交付物**（真实代码/模板）、**可量化指标**、**经过验证的工作流**、**学习记忆机制**。PR 流程包含提交前检查（真实场景测试、遵循模板、补充示例）、社区评审与迭代优化。属 [[Multi-Agent-System-Reliability]] 的智能体设计规范层，为 [[Multi-Agent-Team]] 提供标准化的智能体创建框架。
 
+**GitHub Copilot Integration**（[[github-copilot]]）：The Agency 与 GitHub Copilot 的开箱即用集成——无需转换，Agency 的 `.md` + YAML frontmatter 格式与 GitHub Copilot 原生兼容。通过 `./scripts/install.sh --tool copilot` 一键安装，或手动复制到 `~/.github/agents/` 或 `~/.copilot/agents/` 目录。用户可在任意 Copilot 会话中通过名称激活特定 agent，如 `"Activate Frontend Developer and help me build a React component."`。与 [[readme|Cursor Integration]] 互补——后者项目级别生效，Copilot Integration 用户级别全局生效，共同构成 [[The Agency]] 的多 IDE 集成生态。
+
+**Windsurf Integration**（[[windsurf-integration]]）：The Agency Agent roster 与 Windsurf 编辑器的集成方案——通过 `.windsurfrules` 文件将全部 Agent roster 聚合为单一规则文件，install.sh 脚本从项目根目录安装，项目级生效。Windsurf 中在 prompt 里按名称引用 Agent 即可激活（如 "Use the Frontend Developer agent to build this component."）。与 [[Cursor Integration]]（.mdc 规则）和 [[Aider Integration]]（CONVENTIONS.md）同为项目级 IDE 集成，机制相似，共同构成 The Agency 的多 IDE 覆盖体系。[[integrations-readme]] 已覆盖所有 11 种集成工具的概览。
+
+**Antigravity Integration**（[[antigravity-integration]]）：The Agency Agent roster 与 Antigravity/Gemini 的集成方案——通过 `./scripts/install.sh --tool antigravity` 将全部 Agent roster 转换为 Antigravity SKILL.md 文件，复制到 `~/.gemini/antigravity/skills/` 目录。所有 skill slug 统一使用 `agency-` 前缀（如 `agency-frontend-developer`）以避免与 Antigravity 原生 skills 冲突。用户可通过 `"Use the agency-frontend-developer skill to review this component."` 激活对应 agent。与 [[Cursor Integration]]（.mdc 规则）和 [[Windsurf Integration]]（.windsurfrules）同属多 IDE/平台集成，共同构成 The Agency 的完整集成生态，覆盖 Cursor（VS Code 兼容）、Windsurf、Copilot（用户级）和 Antigravity（Gemini）四大平台。
+
+**Kimi Code CLI Integration**（[[kimi]]）：The Agency 与 Kimi Code CLI 的集成方案——通过 `./scripts/convert.sh --tool kimi` 将所有 agent 转换为 `agent.yaml`（规范定义）+ `system.md`（系统提示词）的目录结构，再通过 `./scripts/install.sh --tool kimi` 安装到 `~/.config/kimi/agents/`。使用 `--agent-file` 标志激活特定 agent，支持 `extend: default` 继承 Kimi 内置 default agent 的工具集。与 [[readme|Cursor Integration]] 和 [[github-copilot]] 同属 The Agency 的多 IDE/CLI 集成生态，Kimi Code CLI 由 Moonshot AI 出品，与 Claude Code 形成竞争。
+
+**OpenCode Integration**（[[readme|OpenCode Integration]]）：The Agency Agent roster 与 OpenCode 编辑器的子 Agent 集成方案——通过 `./scripts/install.sh --tool opencode` 安装，将 The Agency 的 .md 文件格式 Agent 转换为 OpenCode 的 `.opencode/agents/` 目录格式。核心机制：在 YAML frontmatter 中添加 `mode: subagent` 使 Agent 仅在 `@agent-name` 触发时出现，不会在 Tab 循环列表中占位；颜色通过命名颜色到十六进制的自动映射实现。支持两种安装范围：项目级（`.opencode/agents/`）和全局级（`~/.config/opencode/agents/`）。与 [[readme|Cursor Integration]]（.mdc 规则）、[[github-copilot]]（用户级 Copilot）、[[windsurf-integration]]（.windsurfrules）同属 The Agency 的多 IDE 集成生态，[[integrations-readme]] 已覆盖所有集成工具概览。
+
+**MCP Memory Integration**（[[mcp-memory-integration]]）：The Agency 的 MCP Memory 集成方案——通过在 Agent 提示词中加入标准化的 Memory Integration 段落，为任意 Agent 赋予跨会话持久记忆能力，无需修改 Agent 代码。MCP Memory Server 提供四个核心工具：`remember`（存储决策/交付物快照）、`recall`（跨会话检索）、`rollback`（失败时回滚到上一个检查点）、`search`（跨 Agent 搜索记忆）。**Rollback 是杀手级功能**——当 QA 检查失败或架构决策出错时，直接恢复到已知良好状态而非从头重建。标签一致性是关键：每个记忆使用 Agent 名称和项目名称作为标签，确保 recall 可靠。与 [[specialized-mcp-builder]]（构建 MCP Server）和 [[ai-memory-tools-two-camps]]（AI 记忆工具全景分类）同属 The Agency MCP 生态的核心组成部分。
+
+**Backend Architect with Memory**（[[backend-architect-with-memory]]）：The Agency 中具备持久记忆能力的后端架构师 Agent——专门负责可扩展系统设计、数据库架构、API 开发与云基础设施。核心记忆机制：会话启动时检索 `backend-architect` + 项目名标签的历史记忆，防止重复讨论已做决策；架构决策（选型数据库/定义 API 契约/选择通信模式）以标签化快照持久化；交付物（Schema/API 规范/架构文档）完成后主动标记接收方（如 `frontend-developer` + `api-spec`）供下游 Agent 查找；QA 失败时检索最近良好检查点回滚。作为 [[agents-orchestrator]] 调度的具体执行 Agent，通过 MCP Memory 实现多 Agent 协作中的上下文连续性。
+
 **[[multi-channel-assistant]]**：基于 [[OpenClaw]] 的多渠道个人助理方案——以 Telegram Topic 路由为统一入口，整合 Google Workspace（gog）、Slack、Todoist、Asana，实现"说一句话完成全套工作"。核心价值：消除应用切换疲劳，AI 主动推送定时提醒（如每周垃圾清理、公司周报）。
 
 **[[phone-based-personal-assistant]]**：通过 ClawdTalk + Telnyx 将任意手机变成 AI 助理语音入口——拨打电话即可与 [[OpenClaw]] 对话，支持日历查询、Jira 任务更新、网络搜索等技能，无需智能手机 App 或浏览器，覆盖驾驶、步行等双手占用场景。与 [[multi-channel-assistant]] 互补：文字入口覆盖图文交互，语音入口覆盖无屏场景。
diff --git a/wiki/sources/antigravity-integration.md b/wiki/sources/antigravity-integration.md
new file mode 100644
index 00000000..62acc7f2
--- /dev/null
+++ b/wiki/sources/antigravity-integration.md
@@ -0,0 +1,51 @@
+---
+title: "Antigravity Integration"
+type: source
+tags: []
+date: 2026-04-25
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/antigravity/README.md]]
+
+## Summary（用中文描述）
+- 核心主题：Agency Agents 与 Antigravity 的集成方案
+- 问题域：如何在 Antigravity 工具中复用 Agency 团队定义的 Agent 角色
+- 方法/机制：通过 `install.sh` 脚本将 Agency roster 中的 agent 复制为 Antigravity 技能文件（SKILL.md），所有 agent 统一前缀 `agency-` 以避免命名冲突
+- 结论/价值：用户可在 Antigravity 中通过激活特定 skill 直接调用专家 agent，实现多角色快速切换
+
+## Key Claims（用中文描述）
+- Agency agents 可通过 `./scripts/install.sh --tool antigravity` 一键安装为 Antigravity skills
+- 安装脚本将文件复制到 `~/.gemini/antigravity/skills/` 目录
+- 所有 skill slug 统一使用 `agency-<agent-name>` 前缀命名（如 `agency-frontend-developer`）
+- 可通过 `./scripts/convert.sh --tool antigravity` 重新生成 skill 文件（agent 修改后需执行）
+- Antigravity skill 文件为标准的 SKILL.md 格式，含 YAML frontmatter
+
+## Key Quotes
+> "Installs the full Agency roster as Antigravity skills. Each agent is prefixed with `agency-` to avoid conflicts with existing skills." — 核心定位说明
+
+> "In Antigravity, activate an agent by its slug: Use the agency-frontend-developer skill to review this component." — 使用方式示例
+
+> "Each skill is a `SKILL.md` file with Antigravity-compatible frontmatter" — 文件格式说明
+
+## Key Concepts
+- [[Agency Roster]]：Agency Agents 项目中定义的所有 agent 角色集合，提供完整的技能矩阵
+- [[Antigravity Skills]]：Antigravity/Gemini 工具的技能扩展机制，通过 SKILL.md 文件定义 agent 行为
+- [[Skill Prefix Convention]]：通过 `agency-` 前缀隔离 Agency agents 与 Antigravity 原生 skills，避免命名冲突
+- [[SKILL.md Format]]：技能文件格式，包含 name、description、risk、source、date_added 等标准字段
+
+## Key Entities
+- [[Agency Agents]]：提供 AI agent 角色定义的工具集，支持多种 IDE 和平台集成（包括 Antigravity）
+- [[Antigravity]]（Gemini）：Google 的 AI agent 工具，支持通过 skill 文件扩展 agent 能力
+
+## Connections
+- [[Agency Agents]] ← provides agents ← [[Antigravity Integration]]
+- [[Antigravity]] ← consumes skills from ← [[Agency Agents]]
+- [[Cursor Integration]] ← alternative integration → [[Antigravity Integration]]（同为 Agency agents 的 IDE 集成路径）
+
+## Contradictions
+- 与 [[Cursor Integration]] 存在功能重叠：
+  - 冲突点：两个集成都试图将 Agency agents 集成到不同的 AI 工具中（Cursor IDE vs Antigravity/Gemini）
+  - 当前观点：Antigravity Integration 适合 Gemini/Gemini CLI 用户，覆盖 Gemini 生态
+  - 对方观点：Cursor Integration 适合 GUI 代码编辑器用户，覆盖 VS Code 兼容生态
+  - 结论：两者面向不同工具生态，不存在直接冲突，可共存
diff --git a/wiki/sources/backend-architect-with-memory.md b/wiki/sources/backend-architect-with-memory.md
new file mode 100644
index 00000000..bafb2d39
--- /dev/null
+++ b/wiki/sources/backend-architect-with-memory.md
@@ -0,0 +1,47 @@
+---
+title: "Backend Architect with Memory"
+type: source
+tags: []
+date: 2026-04-26
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/mcp-memory/backend-architect-with-memory.md]]
+
+## Summary（用中文描述）
+- 核心主题：具备持久记忆能力的后端架构师 AI Agent 设计规范，专注于可扩展系统设计、数据库架构、API 开发与云基础设施
+- 问题域：如何构建一个能够跨会话保留架构决策、系统设计和技术约束记忆的 AI 后端架构专家
+- 方法/机制：基于 MCP Memory 集成框架，在会话开始时检索相关上下文，完成交付物后主动记忆，跨 Agent 交接时自动传递上下文
+- 结论/价值：解决多 Agent 协作中重复讨论已做决策、交接信息丢失的问题，提升 AI 架构师的实际工程价值
+
+## Key Claims（用中文描述）
+- 后端架构师应在会话启动时主动检索项目相关的历史架构决策，防止重复讨论
+- 架构决策（选型数据库、定义 API 契约、选择通信模式）应以标签形式持久化，供未来会话和其他 Agent 查找
+- 交付物（Schema、API 规范、架构文档）完成后应主动记忆并标记接收方，确保下游 Agent 无需手动复制粘贴
+- 遇到 QA 失败或错误决策时，应检索上一个已知良好状态并回滚，而非手动撤销变更链
+
+## Key Quotes
+> "When you start a session, recall relevant context from previous sessions. Search for memories tagged with 'backend-architect' and the current project name." — 会话启动时的记忆召回机制
+> "When you make an architecture decision — choosing a database, defining an API contract, selecting a communication pattern — remember it with tags including 'backend-architect', the project name, and the topic." — 架构决策的持久化规范
+> "This prevents re-litigating decisions that were already made." — 记忆系统的核心价值
+
+## Key Concepts
+- [[MicroservicesArchitecture]]：微服务架构，支持水平扩展和独立部署，是 Backend Architect 默认推荐的架构模式
+- [[CQRS]]：命令查询职责分离，Backend Architect 在复杂领域驱动设计中的推荐数据模式
+- [[EventSourcing]]：事件溯源，与 CQRS 配合用于复杂业务域的数据建模
+- [[ServerlessArchitecture]]：无服务器架构，Backend Architect 认可的可自动扩展且成本效益高的部署方式
+- [[DatabaseIndexing]]：数据库索引优化，用于实现子 100ms 平均查询性能
+- [[CircuitBreaker]]：断路器模式，Backend Architect 实现系统可靠性和优雅降级的核心机制
+- [[DefenseInDepth]]：深度防御策略，Security-First Architecture 的核心原则
+
+## Key Entities
+- Backend Architect：主 Agent，专门负责系统架构和服务器端开发，特点：战略思维、安全导向、可扩展性优先、可靠性至上
+- Frontend Developer：下游接收方 Agent，接收 Backend Architect 提供的 API 规范
+- QA Agent：质量保障 Agent，在失败时触发记忆回滚机制
+
+## Connections
+- [[AgentsOrchestrator]] ← coordinates ← [[BackendArchitectWithMemory]]
+- [[MCPBuilderAgent]] ← enables ← [[BackendArchitectWithMemory]]（MCP Memory 集成）
+
+## Contradictions
+- 无明显冲突内容
diff --git a/wiki/sources/claude-code-integration.md b/wiki/sources/claude-code-integration.md
index a1cf57d3..740d5b02 100644
--- a/wiki/sources/claude-code-integration.md
+++ b/wiki/sources/claude-code-integration.md
@@ -24,7 +24,7 @@ date: 2026-05-02
 > "The Agency was built for Claude Code. No conversion needed — agents work natively with the existing `.md` + YAML frontmatter format." — 核心设计理念，阐明 The Agency 与 Claude Code 的原生兼容性
 
 ## Key Concepts
-- [[Agent-Activation-Pattern]]：在 Claude Code 中通过名称引用激活预设 Agent 角色的机制
+- [[Agent-Activation-Pattern]]：在 Claude Code 和 Windsurf 中通过名称引用激活预设 Agent 角色的机制
 
 ## Key Entities
 - [[Claude-Code]]：Anthropic 官方 AI 编程 CLI 工具，本集成的目标平台
diff --git a/wiki/sources/gemini-cli.md b/wiki/sources/gemini-cli.md
new file mode 100644
index 00000000..b6bbbb9a
--- /dev/null
+++ b/wiki/sources/gemini-cli.md
@@ -0,0 +1,35 @@
+---
+title: "Gemini CLI Integration"
+type: source
+tags: []
+date: 2026-04-26
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/gemini-cli/README.md]]
+
+## Summary（用中文描述）
+- 核心主题：将 61 个 Agency Agents 打包为 Gemini CLI 扩展插件
+- 问题域：AI Agent 的可移植性与跨工具调用能力
+- 方法/机制：通过 `./scripts/convert.sh --tool gemini-cli` 生成扩展文件，再通过 `./scripts/install.sh --tool gemini-cli` 安装到 `~/.gemini/extensions/agency-agents/`，安装后可在 Gemini CLI 中按名称激活 Agent skill
+- 结论/价值：为 Gemini CLI 用户提供即插即用的 61 个专业 Agent，覆盖前端开发、后端架构、现实核查等多个领域
+
+## Key Claims（用中文描述）
+- Gemini CLI 可通过扩展机制集成 Agency 的全部 61 个 Agent，形成即用型工具包
+
+## Key Quotes
+> "Packages all 61 Agency agents as a Gemini CLI extension. The extension installs to `~/.gemini/extensions/agency-agents/`." — 核心价值声明
+> "Use the frontend-developer skill to help me build this UI." — 在 Gemini CLI 中激活 Agent 的自然语言示例
+
+## Key Concepts
+- [[Agent Skill]]：Agent 以 Skill 形式封装，可在 Gemini CLI 中通过自然语言引用激活
+- [[Extension（扩展机制）]]：Gemini CLI 支持第三方扩展，扩展安装到 `~/.gemini/extensions/` 目录
+
+## Key Entities
+- [[Agency Agents]]：提供 61 个预置专业 Agent 的项目
+
+## Connections
+- [[agents-orchestrator]] ← extends ← [[gemini-cli]]（通过 Gemini CLI 扩展触发 Agent 编排）
+
+## Contradictions
+- （无冲突检测到此文档与现有 Wiki 内容无矛盾）
diff --git a/wiki/sources/github-copilot.md b/wiki/sources/github-copilot.md
new file mode 100644
index 00000000..b5b35ecf
--- /dev/null
+++ b/wiki/sources/github-copilot.md
@@ -0,0 +1,38 @@
+---
+title: "GitHub Copilot Integration"
+type: source
+tags: []
+date: 2026-04-25
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/github-copilot/README.md]]
+
+## Summary（用中文描述）
+- 核心主题：The Agency 项目与 GitHub Copilot 的开箱即用集成方案
+- 问题域：如何在 GitHub Copilot 环境中使用 Agency 的 agent 定义文件
+- 方法/机制：通过脚本安装或手动复制 `.md` + YAML frontmatter 格式的 agent 文件到 Copilot 目录
+- 结论/价值：无需转换，Agency 的 agent 文件格式与 GitHub Copilot 原生兼容，用户可零成本迁移
+
+## Key Claims（用中文描述）
+- Agency agents 使用 `.md` + YAML frontmatter 格式，无需任何转换即可在 GitHub Copilot 中使用
+- 通过 `./scripts/install.sh --tool copilot` 可一键将所有 agents 复制到 Copilot agents 目录
+- 用户可在任何 GitHub Copilot 会话中通过名称激活特定 agent
+- Agents 按部门（division）组织，具体列表见主 README
+
+## Key Quotes
+> "The Agency works with GitHub Copilot out of the box. No conversion needed — agents use the existing `.md` + YAML frontmatter format." — 核心价值主张
+
+## Key Concepts
+- [[AgentFileFormat]]：Agent 定义文件采用 `.md` + YAML frontmatter 格式，是 Agency 与 GitHub Copilot 的共同标准
+
+## Key Entities
+- [[TheAgency]]：The Agency 开源项目本身，提供多领域专业化 agent 定义
+- [[GitHubCopilot]]：GitHub Copilot AI 编程助手，支持通过 agent 文件扩展功能
+
+## Connections
+- [[GitHubCopilot]] ← integrates_with ← [[TheAgency]]
+- [[GitHubCopilot]] ← uses_agent_format ← [[AgentFileFormat]]
+
+## Contradictions
+（暂无已知冲突）
diff --git a/wiki/sources/kimi.md b/wiki/sources/kimi.md
new file mode 100644
index 00000000..b8692232
--- /dev/null
+++ b/wiki/sources/kimi.md
@@ -0,0 +1,41 @@
+---
+title: "Kimi Code CLI Integration"
+type: source
+tags: []
+date: 2026-04-25
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/kimi/README.md]]
+
+## Summary（用中文描述）
+- 核心主题：将 Agency agents 项目转换为 Kimi Code CLI 可用的 agent specification
+- 问题域：多 agent 工具链集成、agent 规范在不同 CLI 平台间的迁移
+- 方法/机制：通过 `convert.sh` 和 `install.sh` 脚本，将每个 agent 转换为包含 `agent.yaml` 和 `system.md` 的目录结构；安装到 `~/.config/kimi/agents/`
+- 结论/价值：提供了一套将 agency-agents 项目的 agent 定义无缝迁移到 Kimi Code CLI 的完整工作流
+
+## Key Claims（用中文描述）
+- Kimi Code CLI 通过 `agent.yaml` + `system.md` 文件定义 agent，支持 `--agent-file` 标志激活
+- agent 规范支持继承机制（`extend: default`），可复用 Kimi 内置 default agent 的工具集
+- 源文件修改后需重新运行 `convert.sh` + `install.sh` 完成同步
+
+## Key Quotes
+> "Converts all Agency agents into Kimi Code CLI agent specifications. Each agent becomes a directory containing `agent.yaml` (agent spec) and `system.md` (system prompt)." — 项目概述
+> "Install agents: `./scripts/install.sh --tool kimi` — This copies agents to `~/.config/kimi/agents/`." — 安装机制
+
+## Key Concepts
+- [[YAML配置文件]]: `agent.yaml` 是 agent 的规范定义文件，包含 name、version、继承关系和工具列表
+- [[Agent规范]]: Agent specification，指用 YAML 格式描述的 agent 元数据（工具集、子 agent、扩展关系等）
+- [[SystemPrompt]]: `system.md` 文件包含 agent 的系统提示词、个性和指令
+
+## Key Entities
+- [[Kimi Code CLI]]: Moonshot AI 出品的命令行 agent 工具，通过 `--agent-file` 加载自定义 agent 规范
+- [[Moonshot AI]]: Kimi 背后的公司，提供 Kimi Code CLI 产品
+- [[Agency Agents]]: 本源文件的母项目，提供跨平台 agent 集成框架
+
+## Connections
+- [[Cursor Integration]] ← similar_approach ← [[Kimi Code CLI Integration]]: 两者都旨在将 agency-agents 转换为各自的 IDE/CLI 工具规范
+- [[Claude Code]] ← competes_with ← [[Kimi Code CLI Integration]]: 两者都是 AI 编程 CLI 工具，存在工具生态竞争
+
+## Contradictions
+- 无已知冲突
diff --git a/wiki/sources/mcp-memory-integration.md b/wiki/sources/mcp-memory-integration.md
new file mode 100644
index 00000000..4e94ef13
--- /dev/null
+++ b/wiki/sources/mcp-memory-integration.md
@@ -0,0 +1,53 @@
+---
+title: "MCP Memory Integration"
+type: source
+tags: []
+date: 2026-05-02
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/mcp-memory/README.md]]
+
+## Summary（用中文描述）
+- 核心主题：通过 MCP（Model Context Protocol）为 The Agency 中的任意 AI Agent 添加跨会话持久记忆能力
+- 问题域：Agent 默认每次会话从零开始，缺乏记忆；多 Agent 间交接依赖手动 copy-paste，无法自动延续上下文
+- 方法/机制：在 Agent 提示词中加入 Memory Integration 指令段，Agent 自动调用 MCP 内存工具（remember/recall/rollback/search）；MCP Server 由外部提供，配置在 Claude Code/Cursor 等 MCP Client 中
+- 结论/价值：无需修改 Agent 代码，只需在 prompt 中加入标准化的 Memory Integration 段落，即可实现跨会话记忆、交接延续和失败回滚；Rollback 是核心杀手级功能
+
+## Key Claims（用中文描述）
+- Agent 默认每次会话从零开始，缺乏上下文延续能力
+- MCP Memory Server 提供 remember、recall、rollback、search 四个核心工具
+- 只需在 Agent prompt 中加入 Memory Integration 段落，即可为任意 Agent 赋予持久记忆
+- Rollback 是 MCP Memory 的杀手级功能：当 QA 检查失败或架构决策出错时，回滚到上一个已知良好状态，而非从头重建
+- 标签一致性是关键：每次记忆都使用 Agent 名称和项目名称作为标签，确保 recall 可靠
+- 无需修改 Agent 代码，无需编写 API 调用，MCP 工具处理所有持久化逻辑
+
+## Key Quotes
+> "Give any agent persistent memory across sessions using the Model Context Protocol (MCP)." — MCP Memory Integration 的设计目标
+> "Rollback is the killer feature: When a Reality Checker fails a deliverable, the original agent can roll back to its last checkpoint instead of trying to manually undo changes." — Rollback 作为关键恢复机制的定位
+> "No code changes to the agent files. No API calls to write. The MCP tools handle everything." — 零侵入性的集成方式
+
+## Key Concepts
+- [[Cross-Session-Memory]]：跨会话记忆能力，Agent 在新会话中能自动检索并恢复上一次的决策和上下文
+- [[Handoff-Continuity]]：多 Agent 交接延续性，一个 Agent 完成任务后交接给下一个 Agent，后者能通过 MCP Memory 自动获取前者的交付物和待办，无需手动 copy-paste
+- [[Rollback]]：失败回滚机制，当 QA 检查失败或架构决策出错时，恢复到上一个已知良好状态
+- [[Memory-Integration-Pattern]]：Memory Integration 段落——在 Agent prompt 中加入标准化指令，指导 Agent 在关键时机调用 MCP 内存工具（remember/recall/rollback/search）
+- [[MCP-Memory-Tools]]：MCP Memory Server 提供的四个核心工具——remember（存储记忆）、recall（检索记忆）、rollback（回滚状态）、search（跨 Agent 搜索记忆）
+- [[Checkpoint]]：检查点，Agent 在完成关键决策或交付物时存储的快照状态，供后续 rollback 使用
+
+## Key Entities
+- [[The-Agency]]：The Agency 多智能体编码框架，MCP Memory Integration 的应用目标
+- [[MCP]]：Model Context Protocol，MCP Memory Integration 的底层协议，定义了 remember/recall/rollback/search 等内存工具的接口规范
+- [[Backend-Architect]]：后端架构师 Agent，MCP Memory Integration 的具体应用示例（见 backend-architect-with-memory.md）
+- [[Startup-MVP-Workflow]]：创业 MVP 工作流，MCP Memory Integration 的完整工作流示例（见 workflow-with-memory.md）
+
+## Connections
+- [[The-Agency]] ← enables ← [[Memory-Integration-Pattern]]
+- [[MCP]] ← provides_tools_for ← [[Cross-Session-Memory]]
+- [[MCP]] ← provides_tools_for ← [[Rollback]]
+- [[Backend-Architect]] ← enhanced_by ← [[MCP-Memory-Integration]]
+- [[Startup-MVP-Workflow]] ← enhanced_by ← [[MCP-Memory-Integration]]
+- [[Memory-Integration-Pattern]] ← uses ← [[MCP-Memory-Tools]]
+
+## Contradictions
+- 无已知内容冲突
diff --git a/wiki/sources/openclaw-integration.md b/wiki/sources/openclaw-integration.md
new file mode 100644
index 00000000..7a09a77b
--- /dev/null
+++ b/wiki/sources/openclaw-integration.md
@@ -0,0 +1,47 @@
+---
+title: "OpenClaw Integration"
+type: source
+tags: [OpenClaw, The-Agency, Integration]
+date: 2026-05-03
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/openclaw/README.md]]
+
+## Summary（用中文描述）
+- 核心主题：The Agency Agent 资产与 OpenClaw 多智能体框架的集成方案
+- 问题域：如何将 The Agency 的 .md 格式 Agent 角色转换为 OpenClaw workspace 并安装激活
+- 方法/机制：① `convert.sh --tool openclaw` 将 Agent 转换为 OpenClaw workspace；② `install.sh --tool openclaw` 将 workspace 复制到 `~/.openclaw/agency-agents/`；③ `openclaw gateway restart` 重启网关使 Agent 可用
+- 结论/价值：The Agency 的 Agent 资产通过 OpenClaw 的 workspace 机制获得持久记忆、n8n 工作流编排和多渠道接入能力
+
+## Key Claims（用中文描述）
+- OpenClaw agents 以 workspace 形式安装，包含 `SOUL.md`、`AGENTS.md` 和 `IDENTITY.md` 文件
+- `convert.sh --tool openclaw` 脚本将 The Agency 的 Agent 配置转换为 OpenClaw workspace 格式
+- `install.sh --tool openclaw` 将 workspace 复制到 `~/.openclaw/agency-agents/` 并自动注册
+- 安装后 agents 通过 OpenClaw gateway 的 `agentId` 对外暴露
+- Gateway 运行状态下安装后需执行 `openclaw gateway restart` 使新 Agent 生效
+
+## Key Quotes
+> "OpenClaw agents are installed as workspaces containing `SOUL.md`, `AGENTS.md`, and `IDENTITY.md` files" — OpenClaw workspace 核心组件定义
+> "The installer copies each workspace into `~/.openclaw/agency-agents/` and registers it when the `openclaw` CLI is available" — 安装路径与注册机制
+> "If the OpenClaw gateway is already running, restart it after installation" — Gateway 热加载要求
+
+## Key Concepts
+- [[OpenClaw-Workspace]]：OpenClaw agent 的工作空间目录，包含 SOUL.md（性格）、AGENTS.md（职责）、IDENTITY.md（身份元数据）等配置文件
+- [[Workspace-Based-Agent]]：基于 workspace 目录架构的 Agent 部署模式，与 [[The-Agency]] 原生的 `.md + YAML frontmatter` 格式不同
+- [[Agent-Conversion]]：通过 `convert.sh` 脚本将 The Agency Agent 转换为目标工具可识别格式的过程
+
+## Key Entities
+- [[The-Agency]]：The Agency 多智能体编码框架，提供 147+ Agent 角色
+- [[OpenClaw]]：开源自主 Agent 框架，专注持久记忆与工作流编排
+- [[OpenClaw-Gateway]]：OpenClaw 的网关服务，通过 `agentId` 暴露 Agent 能力
+
+## Connections
+- [[The-Agency]] ← converts_agents_to ← [[OpenClaw-Workspace]]（通过 `convert.sh`）
+- [[OpenClaw-Workspace]] ← installs_to ← `~/.openclaw/agency-agents/`（通过 `install.sh`）
+- [[OpenClaw]] ← serves ← [[OpenClaw-Gateway]]
+- [[openclaw-integration]] ← part_of ← [[integrations-readme]]（The Agency 11 种集成之一）
+- [[openclaw-integration]] ← related_to ← [[claude-code-integration]]（同为 The Agency 集成方案）
+
+## Contradictions
+- 无已知内容冲突
diff --git a/wiki/sources/readme.md b/wiki/sources/readme.md
index 6334b823..d0bb6d46 100644
--- a/wiki/sources/readme.md
+++ b/wiki/sources/readme.md
@@ -1,42 +1,40 @@
 ---
-title: "Aider Integration"
+title: "OpenCode Integration"
 type: source
 tags: []
-date: 2026-05-02
+date: 2026-04-26
 ---
 
 ## Source File
-- [[Agent/agency-agents/integrations/aider/README.md]]
+- [[Agent/agency-agents/integrations/opencode/README.md]]
 
 ## Summary（用中文描述）
-- 核心主题：Aider 编辑器集成 The Agency Agent 资产的安装与使用指南
-- 问题域：如何在 Aider 项目中激活并调用 The Agency 的多智能体 Agent 角色
-- 方法/机制：通过 `install.sh --tool aider` 安装，将 Agent 配置注入 Aider 项目；Aider 自动读取项目根目录下的 `CONVENTIONS.md` 文件以激活 Agent 角色
-- 结论/价值：The Agency 的 Agent 资产可通过 CONVENTIONS.md 机制无缝集成到 Aider 工作流中，实现项目级的多智能体编码辅助
+- 核心主题：OpenCode 的子 Agent 集成机制——如何将 .md 文件格式的 Agent 转换为 OpenCode 可调用的子代理
+- 问题域：OpenCode IDE 中的多 Agent 协作与按需调用
+- 方法/机制：通过 YAML frontmatter 中的 `mode: subagent` 标记，将具名 Agent 从 Tab 循环列表中分离，改为按需 `@agent-name` 调用；颜色通过命名颜色到十六进制的自动映射实现
+- 结论/价值：提供了一种轻量级、无需修改主 Agent 系统的子 Agent 扩展方案，支持项目级和全局级两种安装范围
 
 ## Key Claims（用中文描述）
-- Aider 会自动检测并读取项目根目录中的 `CONVENTIONS.md` 文件
-- 安装脚本 `install.sh --tool aider` 将 The Agency 的 Agent 配置转换为 Aider 可识别的格式
-- 用户可通过 `convert.sh --tool aider` 重新生成配置文件
-- 在 Aider 会话中直接通过名称引用 Agent（如 "Frontend Developer"）
+- OpenCode Agent 通过在 `.opencode/agents/` 目录存储 .md 文件（带 YAML frontmatter）实现——文件格式与 The Agency 的 Agent 定义格式兼容
+- `mode: subagent` 配置使 Agent 仅在 `@agent-name` 触发时出现，不会在 Tab 循环列表中占位——保持主 Agent 列表的简洁性
+- 命名颜色（如 `cyan`）在安装脚本中被自动转换为十六进制颜色代码——无需手动查表
+- Agent 支持两种安装范围：项目级（`.opencode/agents/`）和全局级（`~/.config/opencode/agents/`）——通过不同路径实现作用域隔离
+- 转换脚本 `./scripts/convert.sh --tool opencode` 负责将 The Agency 的标准 Agent 文件转换为 OpenCode 兼容格式
 
 ## Key Quotes
-> "The full Agency roster is consolidated into a single `CONVENTIONS.md` file" — 所有 Agent 角色汇总在单一的 CONVENTIONS.md 文件中
-> "Aider reads this file automatically when it's present in your project root" — Aider 自动读取项目根目录的 CONVENTIONS.md
-> "Use the Frontend Developer agent to refactor this component" — Aider 会话中按名称调用 Agent
+> "mode: subagent — agent is available on-demand, not shown in the primary Tab-cycle list"
+> — Agent YAML frontmatter 的核心语义，说明 subagent 模式与普通 agent 的本质区别
 
 ## Key Concepts
-- [[CONVENTIONS.md]]：The Agency Agent 角色配置文件，Aider 自动读取
-- [[Project-Scoped-Integration]]：项目级工具集成模式（需在项目根目录安装）
-- [[Agent-Activation]]：Agent 激活机制，通过名称引用在对话中调用
+- [[Subagent]]：按需调用的辅助 Agent，通过 `@agent-name` 语法触发，不参与 Tab 循环
+- [[OpenCode]]：一个支持多 Agent 协作的 IDE/编辑器扩展平台
 
 ## Key Entities
-- [[Aider]]：Aider CLI 编码工具，AI 结对编程编辑器
-- [[The-Agency]]：The Agency 多智能体编码框架（147+ Agent 角色）
+- [[The Agency]]：OpenCode Agent 的来源框架，提供 147 个专业化 Agent 定义
 
 ## Connections
-- [[The-Agency]] ← provides_agents_to ← [[Aider]]
-- [[Aider]] ← reads ← [[CONVENTIONS.md]]
+- [[contributing]] ← 贡献来源 ← [[Agent/agency-agents/integrations/opencode/README.md]]
+- [[The Agency]] ← Agent 定义来源 ← [[Agent/agency-agents/integrations/opencode/README.md]]
 
 ## Contradictions
-- 无已知内容冲突
+- （未检测到与其他页面的明显冲突）
diff --git a/wiki/sources/windsurf-integration.md b/wiki/sources/windsurf-integration.md
new file mode 100644
index 00000000..7872b6f2
--- /dev/null
+++ b/wiki/sources/windsurf-integration.md
@@ -0,0 +1,45 @@
+---
+title: "Windsurf Integration"
+type: source
+tags: []
+date: 2026-04-25
+---
+
+## Source File
+- [[Agent/agency-agents/integrations/windsurf/README.md]]
+
+## Summary（用中文描述）
+- 核心主题：The Agency Agent 与 Windsurf 编辑器的集成方案
+- 问题域：如何在 Windsurf IDE 中使用 The Agency 的 Agent 角色
+- 方法/机制：通过 `.windsurfrules` 文件将 Agent roster 注入 Windsurf，项目级别生效；在 prompt 中按名称引用 Agent 激活使用；install.sh 安装脚本一键部署，convert.sh 重新生成规则文件
+- 结论/价值：项目级生效的 IDE 集成方案，与 [[Cursor Integration]]（项目级 .mdc）和 [[Aider Integration]]（项目级 CONVENTIONS.md）互补，共同构成 The Agency 的多 IDE 覆盖体系
+
+## Key Claims（用中文描述）
+- `.windsurfrules` 文件将 The Agency 全部 Agent roster 合并为单一规则文件
+- Windsurf 集成是项目级别生效（project-scoped），需在项目根目录安装
+- Agent 通过在 prompt 中按名称引用激活（如 "Use the Frontend Developer agent..."）
+- 规则文件可通过 convert.sh 重新生成
+
+## Key Quotes
+> "The full Agency roster is consolidated into a single `.windsurfrules` file." — 单一规则文件聚合全部 Agent roster
+> "Rules are **project-scoped** — install them from your project root." — 项目级别生效机制
+> "In Windsurf, reference an agent by name in your prompt" — 按名称引用激活 Agent
+
+## Key Concepts
+- [[Agent-Activation-Pattern]]：通过在 prompt 中按名称引用来激活 Agent（"Use the Frontend Developer agent to build this component."），在 [[windsurf-integration]] 和 [[claude-code-integration]] 中均有应用
+- [[Project-Scoped-Tools]]：工具集成生效范围为项目级别（OpenCode/Cursor/Aider/Windsurf/Qwen Code），区别于全局安装的工具（Claude Code/GitHub Copilot）；需在项目根目录安装
+
+## Key Entities
+- [[The-Agency]]：多智能体编码系统组织，本次 Windsurf 集成的 Agent 来源
+- [[Windsurf]]：Codeium 开发的 AI 代码编辑器，支持通过 .windsurfrules 注入自定义规则
+
+## Connections
+- [[integrations-readme]] ← part_of ← [[Windsurf Integration]]（集成生态的一员）
+- [[Cursor Integration]] ← similar_pattern ← [[Windsurf Integration]]（同为项目级 IDE 集成，机制相似）
+- [[Aider Integration]] ← similar_pattern ← [[Windsurf Integration]]（同为项目级 Agent 注入方案）
+
+## Contradictions
+- 与 [[integrations-readme]] 存在潜在冲突：
+  - 冲突点：integrations-readme.md 描述 Windsurf 为"项目级别集成"（Project-Scoped），本文档同样确认项目级别
+  - 当前观点：项目级别是正确描述——install.sh 复制到项目根目录而非全局
+  - 对方观点：无冲突，两者一致