# VISTA Link AI 与智能体需求框架

## 文档状态

| 项目 | 内容 |
|---|---|
| 文档类型 | 独立需求框架讨论稿 |
| 整理日期 | 2026-08-12 |
| 讨论对象 | VISTA Link 面向内置和外部 AI 智能体的读取、查询和操作能力 |
| 当前状态 | 用于继续评审，尚未写入正式 PRD 和用例 |
| 当前产品依据 | [VISTA Link 产品需求文档](../VISTA_Link_产品需求文档.md)、[VISTA Link 用例文档](../VISTA_Link_用例文档.md) |
| 历史参考 | [VISTA Link AI 相关历史需求](./VISTA_Link_AI相关历史需求.md)、[HOMEVISTA 数据追踪与 AI 跟进建议实验记录](../VISTA_Link_HOMEVISTA数据追踪与AI跟进建议实验记录.md) |

本文重新整理 VISTA Link 与 AI、智能体的关系。本文不是当前开发或验收依据。内容确认后，仍需按“先 PRD、再用例、最后原型”的顺序写入正式资料。

---

## 1. 需求背景

VISTA Link 已经包含项目、客户、素材、Widget、分享页面、固定链接、客户追踪和营销统计等业务对象。用户除了在 VISTA Link 页面中手工操作，也希望通过自己常用的智能体软件完成相同工作。

例如，用户可以在 Codex、Claude Code 或其他智能体软件中提出以下要求：

- 查找当前项目中符合条件的素材，并组装成一个分享页面。
- 按客户标签、购房意向和其他已记录信息找到一组客户，为这组客户准备合适的素材和页面。
- 查询最近几天最活跃的客户，说明他们主要浏览了哪些内容，并查看对应的客户追踪记录。
- 检查一个页面是否缺少必需 Widget、素材是否已经更新或下线，并准备修改稿。

因此，本需求首先要让 VISTA Link 的业务数据和业务操作能被不同智能体安全、准确地调用。在此基础上，VISTA Link 可以自建一个内置智能体，为销售提供直接可用的对话入口，但内置智能体不是另一套业务系统。

---

## 2. 总目标

**让 VISTA Link 成为一套对 AI 友好的房地产销售资料系统。用户可以授权任意兼容的智能体软件读取自己有权查看的数据，并调用自己有权执行的 VISTA Link 功能。**

这里的“任意智能体软件”是指：

- 不限定 Codex、Claude Code 或某个模型供应商。
- 第一阶段由 VISTA Link 提供 REST API，并使用 OpenAPI 规范描述接口；外部智能体通过 VISTA Link CLI 使用这些接口。
- MCP 不作为第一阶段前提，后续可以在同一业务能力之上增加适配层。
- 智能体完成 VISTA Link 授权后，使用同一套对象、字段、权限和操作规则。
- 更换智能体软件时，不要求 VISTA Link 为每个软件重新制作一套业务接口。
- VISTA Link 自建的内置智能体也使用这套接口，在能力、权限和业务规则上与 Codex、Claude Code 等外部智能体处于平等位置。

“任意”不表示完全不需要配置。智能体必须支持 VISTA Link 提供的接入方式，并由用户完成身份验证、项目授权和接口配置。

---

## 3. AI 友好的具体含义

VISTA Link 达到 AI 友好，至少需要同时具备以下能力：

| 能力 | 要求 |
|---|---|
| 可发现 | 智能体可以取得当前可调用的功能、对象说明、字段说明和输入要求 |
| 可读取 | 智能体可以读取当前用户有权查看的项目、客户、素材、Widget、页面、链接和统计数据 |
| 可检索 | 智能体可以按结构化条件搜索，也可以把自然语言要求转换成结构化条件后搜索 |
| 可理解 | 返回结果带稳定标识、名称、类型、状态、关系、更新时间和必要说明，不能只返回页面文字或一个没有含义的 URL |
| 可操作 | 智能体可以准备并执行 VISTA Link 已经定义的页面创建、Widget 配置等操作 |
| 可验证 | 保存前可以检查 Widget 规则、素材状态、必填内容和页面预览结果 |
| 可控制 | 读取和写入都受当前用户、当前项目、功能权限和数据权限限制 |
| 可确认 | Skill 或内置智能体规则要求在写入前向用户展示变更，并取得明确同意 |
| 可追查 | 系统记录调用用户、智能体或执行组件、项目、动作、对象、时间和结果 |
| 可解释 | 统计回答说明时间范围、数据更新时间、计算口径和主要证据 |

---

## 4. 产品位置

### 4.1 VISTA Link 负责什么

VISTA Link 负责向智能体提供：

- 项目和用户权限信息。
- 客户、素材、Widget、页面、固定链接、客户追踪和营销统计的结构化数据。
- 与现有页面操作相同的业务检查和保存能力。
- 供智能体生成变更说明所需的对象内容和写入结果。
- 操作记录、错误说明、数据更新时间和对象入口。

### 4.2 智能体和执行组件分别负责什么

VISTA Link 内置智能体、Codex、Claude Code 或其他智能体负责：

- 接收用户的自然语言要求。
- 在条件不清楚时向用户补问。
- 判断任务，选择需要使用的 VISTA Link 能力。
- 把查询结果、页面草稿、统计证据和待确认操作展示给用户。
- 在用户确认后发起正式写入动作。

智能体不一定直接调用 HTTP API。实际请求可以由 MCP 工具、本地 CLI、服务器脚本、SDK 或其他执行组件完成。智能体是用户请求的最初接收者和任务安排者，执行组件负责把选定能力转换成具体请求。

内置智能体可以提供更适合销售日常使用的网页、默认问题和业务说明，但它不能因此取得外部智能体无法使用的隐藏业务能力。

### 4.3 本需求不负责什么

以下内容不和本需求混为一件事：

- VISTA Link 自己训练或托管通用大模型。
- 把某个模型写死为唯一选择。
- AI 图片、视频和文案生成任务的模型、费用、额度和生成记录管理。
- 代替销售判断客户购买意向。
- 自动发送销售消息、自动承诺价格、面积、房源状态、合同或交付内容。
- 调用 VISTA Link 尚未定义的业务功能。

AI 生成图片、视频或文案可以继续由独立的 AI 内容制作系统负责。生成结果经过人工确认并成为正式素材后，VISTA Link 再把它当作普通素材提供给页面和智能体使用。

### 4.4 内置与外部智能体的关系

系统关系固定为：

```text
VISTA Link 内置智能体 ─┐
Codex                 ├→ VISTA Link AI 能力层 → 现有业务服务和数据
Claude Code           ┤
其他兼容智能体         ┘
```

其中：

- VISTA Link AI 能力层提供统一的对象、资源、工具、权限检查、确认要求和结果格式。
- 内置智能体和外部智能体都通过这一层调用现有业务能力。
- 内置智能体不直接绕过 AI 能力层访问数据库或调用内部业务服务。
- 同一用户通过不同智能体执行同一操作时，业务结果、权限检查和操作记录应一致。
- 内置智能体可以预先配置 VISTA Link 的业务说明、常用问题和页面展示方式，但不能更改底层业务规则。
- 外部智能体是否能展示相同的卡片、预览或确认界面，取决于智能体软件和执行组件；结构化数据和业务结果必须保持一致。
- 某项能力如果暂时只被内置智能体使用，也必须先登记为正式能力，不能成为只藏在内置网页中的特殊接口。

---

## 5. 基本原则

### 5.1 不建立仅供 AI 使用的第二套业务规则

- 智能体调用现有功能时，使用和人工页面相同的权限、字段、校验、状态和结果规则。
- 人工不能执行的操作，智能体也不能执行。
- 同一个业务对象不能在人工作业和智能体调用中出现两套不同含义。
- 智能体专用接口可以使用更适合机器读取的返回格式，但不能改变产品规则。
- 客户字段、统计公式、页面数量、固定链接行为和 Widget 规则由各自正式业务需求定义。本文件只说明智能体怎样读取、组合、解释和调用这些能力。
- 本文件中的业务规则引用是智能体必须遵守的前提，不是重新定义对应业务。

### 5.2 项目必须明确

- 每次业务查询和操作必须明确项目标识。
- 智能体不能只根据上一次会话猜测当前项目。
- 用户有多个项目时，智能体应先列出可访问项目或请用户选择。
- 一个请求不得混合读取多个项目的数据，除非后续正式定义跨项目功能。
- 素材、客户、页面、固定链接、访问记录和统计都按项目隔离。

### 5.3 读取和写入分开

- 查询、统计、检查和生成临时草稿属于只读或准备阶段。
- 创建页面、修改页面、改变 Widget 配置、改变客户关系等属于写入。
- 只读授权不能执行写入。
- 写入前必须展示目标对象、主要内容和影响，并取得用户确认。
- 保存成功后返回对象标识、名称、状态和可打开入口。

### 5.4 先返回事实，再给解释或建议

- 客户资料中的购房意向、备注和标签属于销售已记录信息，应标明来源。
- 客户访问次数、浏览内容、停留时长和明确动作属于行为记录。
- 智能体可以说明“该客户最近主要浏览眺望和户型内容”。
- 智能体不能仅凭浏览行为写成“该客户确定想买高层户型”。
- 数据不足、数据过期或数据异常时，必须直接说明。

### 5.5 自动准备不等于自动发布

- 智能体可以自动搜索素材、选择候选 Widget、排列页面内容并生成页面草稿。
- 保存为正式页面前，需要按用户权限和确认规则执行。
- 保存页面不等于已经把链接发送给客户。
- VISTA Link 不因为页面创建成功就推断销售已经发送，也不自动向客户发送消息。

---

## 6. 用户与授权

### 6.1 调用身份

内置和外部智能体都应以“用户委托调用”的身份访问 VISTA Link，而不是共享一个不区分人员的系统账号。

用户先使用正常登录会话进入 VISTA Link，再明确授权某个智能体或执行组件。系统为本次委托签发单独的 AI 访问凭证。该凭证必须和网页登录会话凭证区分，不能把网页 Token 直接交给模型、CLI 或 Skill。

每次调用至少能确认：

- VISTA Link 用户标识。
- 智能体或执行组件标识。
- 当前项目标识。
- 已授权能力。
- 授权有效期。

AI 访问凭证至少绑定用户、执行组件、允许的能力和有效期。项目可以在请求中明确指定，但每次请求仍要重新检查用户是否可以访问该项目。用户退出网页不一定立即撤销已经单独签发的 AI 凭证；用户主动撤销授权、账号停用或项目成员停用时，AI 凭证必须失效。

### 6.2 授权范围

建议把授权拆成可单独选择的能力组，最终名称待技术设计确定：

| 能力组 | 示例 |
|---|---|
| 项目读取 | 查看可访问项目和当前项目基本信息 |
| 素材读取 | 搜索素材、读取素材详情和状态 |
| Widget 读取 | 读取可选 Widget 及其配置规则 |
| 客户读取 | 搜索客户、读取客户资料、标签、购房意向和备注 |
| 客户追踪读取 | 读取单个客户访问、内容浏览和明确动作 |
| 营销统计读取 | 按时间和负责人查询统计结果 |
| 页面读取 | 读取页面、Widget 实例、素材和页面状态 |
| 页面写入 | 新建页面、复制页面、修改允许编辑的页面内容 |
| 固定链接读取 | 读取用户有权查看的固定链接和状态 |

授权还要同时受 VISTA Link 现有功能权限和数据权限限制。用户给智能体勾选“客户读取”，不表示用户可以读取自己原本无权查看的客户。

### 6.3 授权管理

- 用户可以查看已经连接的智能体和执行组件。
- 用户可以撤销单个连接的授权。
- 授权过期或被撤销后，对应智能体和执行组件不能继续读取或写入。
- 不把用户密码交给智能体保存。
- 外部 CLI 可以通过浏览器授权页或设备授权方式取得 AI 访问凭证。
- 内置智能体可以从当前登录页面发起授权，但服务器上的智能体运行程序仍使用单独的 AI 访问凭证。
- AI 访问凭证只保存在受控的执行组件中，不进入模型上下文。
- 访问凭证、密码、Token 和客户身份验证码不得写入普通操作记录或返回给模型上下文。

---

## 7. 对象和数据要求

### 7.1 通用字段

提供给智能体的主要对象应有统一的基础信息：

- 稳定对象标识。
- 所属项目标识。
- 对象类型。
- 当前名称。
- 当前状态。
- 创建时间和更新时间。
- 已删除、已下线或已停用状态。
- 对象版本或更新时间标记。
- 用户是否可以查看、编辑或执行相关动作。

不能把名称当作唯一标识。同名客户、同名素材和同名页面必须能被稳定区分。

### 7.2 素材

智能体读取素材时，至少需要取得：

- 素材标识、名称、所属项目。
- 来源分类和具体内容形式。
- 素材标签、素材说明和结构化属性。
- 来源内容更新时间或版本。
- 已更新、已下线或已删除状态。
- 内部预览是否可用。
- 可供哪些 Widget 选择，以及不能使用的原因。

素材接口不能只返回一个文件地址或打开地址。链接必须带业务含义、所属项目、内容类型和安全限制。

### 7.3 Widget

智能体需要读取每个 Widget 的：

- Widget 稳定标识和名称。
- 启用状态。
- 可选择的素材分类。
- 素材数量限制。
- 必填内容。
- 可编辑字段。
- 展示形式和可选值。
- Widget 内动作。
- 配置检查规则。
- C 端展示所需的结构化内容。

Widget 规则以 Widget 自身 PRD 和 A 端提供的当前配置为准。智能体不能根据 Widget 名称自行猜测配置方法。

### 7.4 客户

在用户有权查看客户资料时，智能体可以读取：

- 客户稳定标识、姓名和客户编号。
- 客户状态、客户标签和负责人。
- 购房意向和备注。
- 当前项目中允许读取的联系方式。
- 最近活动和客户追踪入口是否可用。

家庭情况、生活偏好、学校、通勤、景观、预算敏感等信息目前可能记录在客户标签、购房意向或备注中。智能体必须说明实际使用了哪些字段，不能把缺失字段当作已经存在。

### 7.5 页面

智能体读取或准备页面时，需要理解：

- 页面标识、名称、备注、封面和创建来源。
- 当前状态、创建人和更新时间。
- Widget 实例、排列顺序和配置内容。
- 每个 Widget 实例使用的素材。
- 素材更新、下线和删除状态。
- 页面是否允许当前用户编辑、复制或删除。
- 固定链接状态和用户是否可以查看。

### 7.6 客户追踪和营销统计

提供给智能体的统计结果应包含：

- 查询项目。
- 查询时间范围和时区。
- 数据最后更新时间。
- 使用的筛选条件。
- 指标名称、数值和计算口径。
- 对应客户、页面、Widget、素材和固定链接的稳定标识。
- 历史名称快照和删除状态。
- 数据是否完整、是否存在延迟或异常。

客户行为事件需要保留发生顺序、发生时间、访问、页面、固定链接、Widget 实例、实际内容或素材、有效时长和明确动作，才能让智能体还原客户查看过程。

---

## 8. 智能体可调用的能力

以下名称只表示能力，不是最终接口名称。

### 8.1 连接和能力查询

- 查询当前用户身份。
- 查询用户可访问项目。
- 查询某项目中的角色和可用功能。
- 查询 VISTA Link 可供智能体调用的工具目录。
- 查询对象字段、筛选条件、枚举和 Widget 配置规则。

### 8.2 素材查询

- 按名称搜索素材。
- 按分类、标签、内容形式和状态筛选素材。
- 按结构化属性筛选素材，例如户型、面积、朝向、楼层或其他来源系统已经提供的属性。
- 查询素材详情、说明、更新时间和预览能力。
- 查询某个 Widget 当前可选的候选素材。
- 检查一组素材能否放入指定 Widget。

### 8.3 客户查询

- 按姓名搜索客户。
- 按一个或多个客户标签筛选客户。
- 按客户状态和负责人筛选客户。
- 在用户有权查看时，按购房意向和备注中的明确内容查找客户。
- 返回实际匹配字段和匹配条件。
- 读取单个客户的客户追踪数据。

自然语言中的“家庭客户”“预算有限”“重视通勤”“关注眺望”等说法，由智能体在任务中解释，并映射到当前项目已有的客户标签、购房意向和备注。VISTA Link 第一阶段不维护固定的“客户条件对应素材标签”规则。

智能体必须说明本次使用了哪些客户信息、怎样解释这些信息、据此选择了哪些素材标签或素材属性。没有足够数据时应说明无法准确筛选。智能体可以提出新客户标签或素材标签，但保存标签和把标签加入对象前必须取得用户确认。

### 8.4 页面查询与组装

- 查询当前可用的系统页面和用户可见页面。
- 读取页面中的 Widget、素材、顺序和当前状态。
- 新建空白页面草稿。
- 复制允许复制的页面作为草稿。
- 按要求选择 Widget。
- 为 Widget 选择符合规则的素材。
- 填写允许编辑的 Widget 内容和展示形式。
- 调整 Widget 顺序。
- 检查必填内容、数量限制、素材状态和 Widget 规则。
- 生成与 C 端规则一致的预览输入。
- 在用户确认后保存页面。
- 保存后返回页面和固定链接信息，但不自动发送。

### 8.5 客户追踪查询

- 查询单个客户的累计访问数据。
- 按固定链接和时间范围查询访问趋势。
- 查询内容浏览时长分布。
- 查询每次访问中的 Widget 浏览顺序、素材、时长和明确动作。
- 返回数据时间、统计口径和历史对象状态。

### 8.6 营销统计查询

- 按今天、最近 7 天、最近 30 天或自定义时间查询。
- 按客户负责人筛选。
- 查询访问客户数、首次访问客户数和回访客户数。
- 查询活跃客户列表。
- 查询内容浏览分析前 10 项。
- 从统计结果继续读取某个客户的客户追踪记录。
- 从某项内容继续读取浏览过它的客户名单。

### 8.7 页面检查

- 检查页面是否使用已经更新、下线或删除的素材。
- 检查已停用 Widget。
- 检查必填 Widget、素材数量和配置规则。
- 检查当前项目主题和预览输入是否完整。
- 返回问题清单和修改草稿。
- 用户确认后，按现有页面编辑权限保存修改。

---

## 9. 核心使用场景

### 场景 AI-01：按要求查找素材并组装页面

**用户说法示例：**

> 在当前项目里找出 3LDK 户型、对应户型图、样板间和通勤资料，帮我组装一个给改善型家庭客户看的页面。

**处理过程：**

1. 智能体确认当前项目和用户可用权限。
2. 读取当前项目可选 Widget 及其配置规则。
3. 把“3LDK、改善型家庭、通勤资料”转换成可查询条件。
4. 搜索素材，并保留实际匹配依据。
5. 如果结果过多、没有结果或存在歧义，向用户补问。
6. 选择合适的 Widget，并只放入该 Widget 允许使用的素材。
7. 生成页面名称、备注、封面选择和 Widget 排列草稿。
8. 执行页面规则检查并生成预览。
9. 向用户展示将要保存的页面内容。
10. 用户确认后保存页面，并返回页面入口和固定链接状态。

**不能发生：**

- 混入其他项目素材。
- 把素材名称相似当作同一素材。
- 把不兼容素材硬放进 Widget。
- 未经确认直接保存或发送给客户。

### 场景 AI-02：按客户群体准备页面

**用户说法示例：**

> 找出当前项目里有子女、重视学区和通勤、预算在 1 亿日元以内的客户，给他们准备一套适合的页面。

**处理过程：**

1. 智能体确认用户是否有客户读取权限。
2. 检查当前项目是否存在对应客户标签，以及预算是否写在购房意向或其他已定义字段中。
3. 返回匹配客户、使用的筛选条件和命中字段。
4. 不完整或无法结构化的数据单独列出。
5. 根据客户群体的明确条件查找素材。
6. 说明“客户条件”和“素材条件”的对应关系。
7. 组装一个共用页面草稿，或在用户明确要求时准备多个页面草稿。
8. 检查 Widget 和素材规则，展示预览。
9. 用户确认后保存。

**待确认：**

- 同一个客户群体默认生成一个共用页面，还是按客户生成多个页面。
- 预算、区域、户型等购房意向是否需要从自由文本升级成结构化字段。
- 是否允许智能体建议新增客户标签或素材标签；即使允许，也不能未经确认直接写入。

### 场景 AI-03：查询最近活跃客户和关注内容

**用户说法示例：**

> 最近 7 天最活跃的客户是哪几个？他们分别主要看了什么？

**处理过程：**

1. 智能体确认项目、时间范围、时区和数据最后更新时间。
2. 调用营销统计取得活跃客户列表。
3. 使用已经确认的排序指标回答“最活跃”。如果“最活跃”的口径没有指定，先说明可选口径并请用户选择，或明确本次使用的口径。
4. 对每位客户读取客户追踪中的内容浏览时长、浏览次数和明确动作。
5. 把 Widget 浏览记录映射到实际内容和素材。
6. 返回客户、客观数据、主要浏览内容、对应追踪记录入口和数据限制。

**回答示例结构：**

| 客户 | 活跃依据 | 主要浏览内容 | 客观行为 | 数据限制 |
|---|---|---|---|---|
| 客户 A | 7 天内访问 5 次 | 眺望 Widget 中的高层视野素材 | 累计浏览 8 分钟 | 只能说明浏览较多，不能确认购买意向 |

### 场景 AI-03A：查询最近 30 天最值得跟进的客户

**用户说法示例：**

> 最近 30 天最值得跟进的客户是谁？最活跃的是谁？他主要对什么感兴趣？

**处理过程：**

1. 智能体确认当前项目、最近 30 天、日本时区和统计数据最后更新时间。
2. 调用营销统计取得正式客户排行，并使用营销统计已经定义的默认排序。
3. 回答“最活跃”时，展示排序依据和对应客观数值，不在 AI 层增加新的活跃算法。
4. 对排行靠前的客户读取客户追踪数据，包括访问次数、浏览页面、实际内容、浏览次数、有效时长和明确动作。
5. 把“主要对什么感兴趣”改写为有数据依据的表达，例如“最近主要浏览”“浏览客户内容中累计时长较长”或“多次查看”。
6. 回答分成“客观排行”“主要浏览内容”“供销售查看的跟进建议”三部分。
7. 每条跟进建议都要附带依据，并说明尚缺少哪些客户资料或沟通信息。

**“最值得跟进”的处理：**

- VISTA Link 当前营销统计不提供“最值得跟进”分数、意向等级或系统跟进优先级。
- 智能体不能把“最值得跟进”伪装成已有统计指标，也不能自行给客户打分。
- 智能体可以先回答正式统计中的客户排行，再根据客观访问记录给出“建议销售优先查看”的客户和原因。
- “建议销售优先查看”是带依据的建议，不修改客户状态、标签或负责人，也不表示客户更可能购买。
- 如果用户要求一个确定答案，智能体仍要说明判断依据和限制，不能省略“不代表购买意向”的说明。

**回答示例结构：**

| 客户 | 正式排行依据 | 最近主要浏览 | 明确动作 | 建议及限制 |
|---|---|---|---|---|
| 客户 A | 最近 30 天访问次数排第 1 | 多次浏览 3LDK A 户型和高层眺望 | 点击过来场预约入口 | 建议销售先查看该客户记录并询问户型和到访计划；入口点击不表示预约完成，也不表示已经决定购买 |

**不能发生：**

- 新增一套只供 AI 使用的“值得跟进”计算公式。
- 把访问次数、停留时长或预约入口点击直接写成高意向。
- 把主要浏览内容写成客户已经确认的购房需求。
- 自动修改客户标签、状态、负责人或创建强制跟进任务。

### 场景 AI-04：根据单个客户记录准备后续资料

**用户说法示例：**

> 看一下李娜最近两周的浏览记录，按她已经填写的购房意向和主要浏览内容，准备一个下一次沟通用的页面。

**处理过程：**

1. 读取客户资料中的已填写购房意向、标签和备注。
2. 读取最近两周的访问、Widget 浏览、素材和明确动作。
3. 把“销售填写的信息”和“客户浏览行为”分开列出。
4. 查找与两类信息相关的素材。
5. 生成页面草稿和选材理由。
6. 销售检查后确认保存。

智能体可以给出“下一次可以询问哪些问题”的建议，但不能把浏览行为直接改写成客户意向，也不能自动创建必须完成的销售任务。

### 场景 AI-04A：根据用户临时描述的单个客户画像制作页面

**用户说法示例：**

> 我有一位大约 45 岁的客户，夫妻二人，有一个上小学的孩子，比较在意通勤和孩子上学。请结合当前项目已有的材料，帮我做一个适合他的营销页面，我确认后发给客户。

**处理过程：**

1. 智能体确认当前项目、用户权限和目标客户；存在同名客户时让用户选择。
2. 读取该客户在 VISTA Link 中已经保存的标签、购房意向和备注。
3. 把“系统已保存资料”和“用户本次临时描述”分开记录，不能把临时描述写成系统已经保存的客户事实。
4. 解释本次使用的客户条件，例如年龄阶段、家庭成员、学龄子女、通勤和学校需求。
5. 在当前项目中搜索与这些条件有关的现有素材，并说明客户条件与素材标签、分类或结构化属性之间的对应依据。
6. 读取可选 Widget 和配置规则，只把符合 Widget 候选范围的素材放入页面。
7. 生成页面草稿，包含页面名称、封面、Widget 顺序、素材、页面说明和选材理由。
8. 检查页面规则并生成页面预览。
9. 智能体向用户说明用了哪些已保存资料、哪些临时描述，以及这些信息如何影响选材。
10. 用户明确同意后，智能体调用页面保存能力，并取得该客户对应的访问地址。
11. 智能体把页面和访问地址交给用户；实际发送仍由销售在外部工具中完成。

**临时描述规则：**

- 用户在当前对话中明确提供的信息，可以作为本次搜索、选材和页面制作的条件。
- 年龄、家庭成员和其他未设置为固定字段的信息，不要求先写入客户资料才能用于本次任务。
- 临时描述默认只用于当前任务，不自动保存到客户标签、购房意向或备注。
- 智能体认为某些临时描述适合保存为客户标签时，可以提出建议。用户明确同意后，才能调用客户标签写入能力。
- 用户描述与 VISTA Link 已保存资料冲突时，智能体必须指出冲突并让用户确认本次使用哪一项，不能静默覆盖客户资料。
- 用户没有提供姓名或客户标识时，智能体可以先制作不关联客户的页面草稿；取得客户专用访问地址前必须明确目标客户。

**不能发生：**

- 把“大约 45 岁”改写成确定出生日期或精确年龄。
- 根据家庭情况推断收入、预算、婚姻关系或购买意愿。
- 把“有一个上小学的孩子”自动保存成客户标签或备注。
- 使用其他项目的素材。
- 未经用户同意保存正式页面或修改客户资料。
- 把取得访问地址写成已经发送给客户。

### 场景 AI-05：检查并修正已有页面

**用户说法示例：**

> 检查“家庭客户介绍页”有没有失效素材，能修的先给我一个修改方案。

**处理过程：**

1. 读取页面、Widget 实例和素材状态。
2. 找出已更新、已下线、已删除素材和已停用 Widget。
3. 按 Widget 候选范围查找替代素材。
4. 返回问题、替代选择和影响。
5. 生成修改后的预览。
6. 用户确认后保存。

---

## 10. 一次标准调用过程

```text
用户提出要求
→ 智能体确认身份、项目和授权
→ 查询 VISTA Link 当前可用工具与规则
→ 把自然语言转换成结构化条件
→ 查询客户、素材、Widget、页面或统计
→ 返回事实，必要时向用户补问
→ 生成操作草稿
→ VISTA Link 执行业务检查
→ 智能体展示预览、变化和影响
→ 用户确认
→ VISTA Link 写入正式数据
→ 返回对象标识、状态、入口和操作结果
```

只读问题可以在返回查询结果后结束，不需要写入确认。

---

## 11. 自然语言与结构化查询

智能体可以接收自然语言，但 VISTA Link 不应直接用一段模糊文字修改数据。

### 11.1 转换要求

智能体应把自然语言转换成可检查的结构：

```json
{
  "projectId": "project-id",
  "customerCriteria": {
    "tags": ["有子女", "通勤优先"],
    "purchaseIntentKeywords": ["3LDK", "1亿日元以内"]
  },
  "materialCriteria": {
    "categories": ["户型", "户型图", "周边地图"],
    "tags": ["家庭", "通勤"]
  },
  "pageGoal": "改善型家庭客户介绍",
  "saveMode": "preview_only"
}
```

以上字段只用于说明表达方式，不是最终接口定义。

### 11.2 无法转换时的处理

- 项目不明确：要求用户选择项目。
- 客户条件没有对应字段或标签：说明缺少数据。
- 素材条件没有匹配结果：返回空结果和已使用条件。
- 多个对象同名：返回候选对象及稳定标识，请用户选择。
- Widget 规则不明确：停止组装对应部分，并说明缺少的规则。
- 用户要求超出当前功能：说明 VISTA Link 尚不支持，不临时编造操作。

---

## 12. 写入确认

### 12.1 需要确认的操作

以下操作至少需要用户确认：

- 创建或复制分享页面。
- 修改页面名称、备注、封面、Widget、素材、顺序或展示形式。
- 删除页面。
- 改变固定链接状态或客户关联关系。
- 修改客户资料、标签、状态或负责人。
- 修改素材标签或素材说明。

第一阶段建议开放页面草稿、页面保存、客户标签和素材标签写入。删除页面、修改成员角色、批量导入导出、修改客户负责人和改变链接公开或启用状态暂不开放。

### 12.2 确认内容

确认提示至少包含：

- 当前项目。
- 操作类型。
- 目标对象。
- 新建或修改的主要内容。
- 使用的客户、素材和 Widget。
- 已发现的警告。
- 保存后是否会创建固定链接或改变链接状态。
- 可选操作：确认、修改、取消。

### 12.3 确认由智能体规则负责

第一阶段不为 AI 新增待确认记录、确认地址、确认凭据或确认记录功能。确认要求写入 VISTA Link Skill 和内置智能体规则：

1. 智能体准备将要写入的内容。
2. 智能体向用户展示项目、目标对象、主要变更和影响。
3. 用户明确同意后，智能体才让 CLI 或服务器工具执行组件调用写入接口。
4. 用户拒绝、要求修改或没有明确回答时，智能体不调用写入接口。

页面草稿中的搜索、选材、排序和文字调整不需要逐步确认。草稿保存为正式页面、修改正式页面、保存客户或素材标签、建立客户与固定链接关系时确认一次。

VISTA Link 服务端继续检查 AI 访问凭证、当前项目、功能权限、对象版本和业务规则，并按现有规则记录实际写入，但不验证智能体是否真的取得过用户确认，也不额外保存确认内容。

这种方式只能约束遵守官方 Skill 或内置智能体规则的调用。绕过 Skill 直接调用 REST API 的程序，只要持有对应写入权限，VISTA Link 无法仅凭请求判断用户是否明确确认。第一阶段接受这一限制；如果后续出现误操作，再单独评审服务端确认能力。

批量生成页面可以在智能体会话中一次确认，但智能体必须展示页面数量、目标客户或页面命名依据、将使用的共同内容和存在差异的项目。接口可以把大任务拆成多批执行，并返回每一项成功或失败的结果；不能因为内部单批数量限制而少创建页面。

### 12.4 防止重复写入

- 每次写入请求应带唯一请求标识。
- 网络重试不能重复创建相同页面或重复执行相同修改。
- 系统应返回本次请求对应的操作结果。
- 页面在用户确认前已经被其他人修改时，系统应提示版本变化并要求重新检查。

---

## 13. 权限、安全和隐私

- 智能体权限不得超过当前用户的功能权限和数据权限。
- 每个请求必须再次检查当前项目成员状态和最新权限。
- 项目切换后，不得继续返回原项目数据。
- 素材内部预览仍需登录和当前项目权限，不能变成对外公开地址。
- 客户联系方式、购房意向、备注和行为记录按最少必要内容返回。
- 面向模型的上下文不应包含密码、Token、验证码或无关个人信息。
- 操作记录不得保存完整访问凭证和客户身份参数。
- 用户撤销授权后，智能体和执行组件不能继续使用旧凭证。
- 第一阶段不设置面向正常用户的调用次数配额。系统仍可以阻止攻击、失控循环和明显异常请求，这属于安全保护，不是商业用量限制。
- 列表和批量查询应支持分页，不能因为单次返回数量有限就静默漏掉结果。每页数量由接口设计确定。
- 任何智能体返回的内容都不能绕过 VISTA Link 的内容检查和业务检查。

---

## 14. 操作记录

智能体执行正式写入时，除现有业务操作记录外，还应记录：

- 实际 VISTA Link 用户。
- 智能体名称、执行组件名称和对应标识。
- 所属项目。
- 调用的能力。
- 目标对象和对象标识。
- 操作前后的主要内容。
- 请求标识。
- 成功、失败或部分成功结果。
- 失败原因。

界面可以把操作来源显示为“用户本人通过 Codex”“用户本人通过 Claude Code”或其他已登记客户端，不能把智能体写成一个无法追查到实际用户的独立人员。

只读查询不进入现有的用户可见业务操作记录，也不保存完整返回数据。AI 请求记录只保留用户、项目、智能体、执行组件、能力编号、请求标识、时间、成功或失败和结果数量等必要信息，用于安全检查和问题排查。

AI 请求记录不保存完整自然语言对话、完整客户资料、完整素材内容或模型的完整思考内容。具备查看操作记录权限的项目管理员能否看到其中一部分摘要，以及技术记录的保存天数，仍需在正式安全设计中确定。

---

## 15. 统计回答规则

### 15.1 必须说明的内容

统计回答至少说明：

- 查询项目。
- 时间范围和时区。
- 数据最后更新时间。
- 使用的筛选条件。
- “最活跃”“最关注”等词使用的具体指标。
- 主要数值和对应记录。
- 数据缺失、异常或延迟情况。

### 15.2 事实、分析和建议分开

建议使用以下顺序：

1. **事实**：访问次数、浏览内容、有效时长和明确动作。
2. **谨慎说明**：哪些内容浏览较多，哪些变化值得销售查看。
3. **建议**：销售下一次可以询问或准备什么。
4. **缺失信息**：客户需求、沟通记录、预算或其他未记录内容。

### 15.3 统计指标由业务需求定义

- “活跃客户”“最活跃客户”“最受欢迎内容”等指标的定义、计算公式、默认时间范围和排序方式，属于客户追踪与营销统计需求，不由 AI 需求定义。
- 智能体只调用 VISTA Link 已经提供的统计指标，并在回答中说明指标名称、时间范围和数据更新时间。
- VISTA Link 尚未定义某个指标时，智能体应让用户选择已有指标，或说明当前无法按该说法准确统计，不能自行发明公式。
- AI 需求只检查智能体有没有正确使用和解释业务指标，不检查或改变指标本身怎样计算。

### 15.4 禁止推断

- 不按停留时长自动生成客户分数。
- 不按访问次数自动生成意向等级。
- 不把点击预约入口写成预约已经完成。
- 不把浏览某个户型写成客户已经决定购买。
- 不把没有负责人写成某位销售负责。

---

## 16. 错误和恢复

| 情况 | 要求 |
|---|---|
| 未授权 | 返回缺少的授权，不返回目标数据 |
| 没有项目访问权 | 拒绝访问，不自动切换到其他项目 |
| 对象不存在 | 返回对象类型和查找条件，不用同名对象替代 |
| 数据读取失败 | 返回失败和重试方式，不能显示成没有数据 |
| 统计未更新 | 返回数据最后更新时间和延迟状态 |
| 素材已下线 | 不放入新页面，已有页面按现有规则提示 |
| Widget 已停用 | 不加入新页面，编辑已有页面时按现有规则处理 |
| 页面版本变化 | 停止写入，要求重新读取和确认 |
| 部分操作失败 | 返回成功项、失败项和可重试项 |
| 智能体中断 | 已保存对象保持不变；未确认草稿不写入正式数据 |

---

## 17. 建议的开发顺序

### 第一阶段：AI 可读基础

- 统一对象标识、字段说明、状态和更新时间。
- 提供 REST API，并使用 OpenAPI 规范描述接口。
- 提供项目、权限、客户、素材、Widget、页面和固定链接的第一阶段只读能力。
- 客户追踪和营销统计在对应后续业务完成后接入同一 REST API。
- 提供能力目录和字段说明。
- 完成用户委托授权、项目隔离和撤销授权。
- 提供供外部智能体使用的 VISTA Link CLI 和 Skill。
- 用至少两个不同智能体验证 CLI 调用结果。

### 第二阶段：页面组装

- 增加服务器保存的页面草稿，支持新建、复制、继续编辑、自动保存、版本检查和删除草稿。
- 提供 Widget 选择、素材选择和顺序调整能力。
- 提供页面规则检查和预览输入。
- 在 Skill 中规定页面保存前必须向用户说明并确认，然后调用页面保存能力。
- 提供客户标签和素材标签的新建、添加、移除能力，保存前由用户确认。
- 提供重复请求保护、版本检查和操作记录。

### 第三阶段：客户和统计问答

- 支持客户条件查询和客户追踪读取。
- 支持营销统计查询和继续查看明细。
- 统一时间范围、指标口径、数据更新时间和证据返回。
- 验证“最近活跃客户”“主要浏览内容”“下一次准备什么资料”等问题。

### 第四阶段：内置智能体和更多写入能力

- 使用同一套 AI 能力建立 VISTA Link 内置智能体。
- 第一版可以使用文字展示查询结果，不要求先制作通用结果卡片。
- 页面制作需要提供页面预览；正式写入前由 Skill 或内置智能体规则要求用户确认。
- 评审是否开放客户资料、负责人、固定链接状态、成员和角色等更多写入能力。

内置智能体和外部智能体互不构成前提。可以先做其中一种运行方式，但 VISTA Link AI 能力层必须从一开始同时适用于两者。

---

## 18. 初步验收场景

### 验收 A：不同智能体使用同一套能力

- VISTA Link 内置智能体、Codex 和另一个兼容客户端分别以同一测试用户调用相同能力。
- 三者都能查询该用户在同一项目中的可用素材和 Widget 规则。
- 三者取得的对象标识、状态、规则和权限结果一致。
- 三者都不能读取该用户无权访问的项目。
- 内置智能体不能调用能力目录中不存在的隐藏写入工具。

### 验收 B：素材组装页面

- 用户描述目标客户和所需内容。
- 智能体能找到当前项目内符合条件的素材。
- 所选素材符合 Widget 候选范围和数量规则。
- 系统能返回页面预览和检查结果。
- 用户确认后只创建一个页面，不因重试重复创建。
- 返回页面标识、页面入口和固定链接状态。

### 验收 C：按客户群体准备页面

- 智能体只按项目中真实存在的客户字段和标签筛选。
- 返回匹配条件和匹配客户。
- 客户资料不足时明确说明，不自动补造标签或购房意向。
- 页面选材说明能指出使用了哪些客户条件和素材条件。

### 验收 D：查询最近活跃客户

- 用户指定最近 7 天。
- 回答说明时区、数据更新时间和“活跃”的计算指标。
- 每位客户的主要浏览内容能追到 Widget 和实际素材。
- 回答能进入对应客户追踪记录。
- 回答不生成客户分数或购买意向结论。

### 验收 E：权限变化

- 项目管理员撤销用户的页面写入权限。
- 用户已连接的智能体下一次请求立即使用最新权限。
- 智能体仍可执行被允许的只读请求，但不能保存页面。

### 验收 F：页面内容发生变化

- 智能体读取页面后，其他用户修改了该页面。
- 原写入请求不能覆盖新版本。
- 智能体重新读取、展示变化并取得用户再次确认后才能保存。

---

## 19. 已明确与待确认

### 19.1 本次已经明确的方向

- VISTA Link 整套系统需要对 AI 友好。
- 用户可以使用 Codex、Claude Code 或其他兼容智能体与 VISTA Link 互动。
- 智能体可以读取当前项目素材并组装页面。
- 智能体可以根据用户描述的客户群体和需求查找素材，并放入合适 Widget。
- 智能体可以查询一段时间内的活跃客户和主要浏览内容。
- 统计回答需要能继续查看客户追踪中的对应数据。
- 产品不能只围绕某一个模型或某一个内置智能体设计。
- VISTA Link 可以自建内置智能体，但它和 Codex、Claude Code 等外部智能体处于平等位置。
- 内置智能体必须使用与外部智能体相同的 VISTA Link AI 能力层。

### 19.2 当前产品已经提供的业务基础

- 项目、成员、角色、功能权限和数据权限。
- 客户基础资料、客户状态、客户标签、购房意向、备注和负责人。
- 素材分类、标签、说明、来源信息和更新状态。
- Widget 候选素材和配置规则。
- 页面新建、复制、编辑、预览、保存和固定链接。
- 客户访问记录、客户追踪和营销统计需求。
- 操作记录和项目数据隔离规则。

其中数据追踪、客户追踪和营销统计仍属于当前 PRD 中的后续统计开发内容，不应写成已经全部实现。

### 19.3 本轮已经确认的决定

1. 第一阶段提供 REST API，并使用 OpenAPI 规范描述接口。外部智能体通过 VISTA Link CLI 调用，不直接依赖 MCP。
2. 用户从正常登录会话发起智能体授权。VISTA Link 为智能体或执行组件签发单独的 AI 访问凭证，不复用网页登录会话凭证。
3. 页面草稿保存在 VISTA Link 服务器，作为可以继续读取和编辑的正式草稿对象。
4. AI 接入不要求修改现有客户字段。智能体先使用客户标签、购房意向和备注；客户字段是否调整由客户管理需求决定。
5. VISTA Link 不为 AI 维护固定的客户条件与素材标签对应表。智能体在每次任务中解释和选择对应关系，并向用户说明本次判断依据。
6. 智能体可以提出、新建、添加和移除客户标签与素材标签。保存前必须由当前用户确认。
7. AI 接口不额外规定批量页面的业务数量上限。页面业务规则和接口分批方式分别由对应需求与技术设计决定。
8. 第一阶段不设置正常调用次数配额。异常调用保护仍然保留。
9. 内置智能体第一版可以用文字回答，不要求先制作通用结果卡片。页面制作需要预览，正式写入需要确认操作。
10. AI 内容制作系统不属于本文件范围，不在本文件中讨论接入时间、生成费用和审核规则。
11. 写入前确认由 VISTA Link Skill 和内置智能体规则负责。VISTA Link 第一阶段不新增待确认记录或确认凭据功能。
12. 客户追踪与营销统计的指标、公式、默认时间范围和排序规则不在 AI 需求中定义，AI 只使用正式业务能力返回的口径。

### 19.4 第一阶段读写能力建议

以下是基于当前主路径给出的建议清单。正式开发前仍需写入正式 PRD 和用例。

**第一阶段读取：**

- 当前用户、可访问项目、当前项目角色和功能权限。
- 能力目录、字段、枚举和错误说明。
- 客户列表、客户详情、客户状态列表和客户标签库。
- 素材列表、素材详情、素材标签库和内部预览信息。
- 可选 Widget、Widget 使用规则和候选素材。
- 页面列表、页面详情、页面版本和页面检查结果。
- 固定链接状态和链接关联客户。
- 客户追踪和营销统计在对应后续业务完成后开放读取。

**第一阶段写入：**

- 新建、复制、编辑、检查和删除服务器页面草稿。
- 把草稿保存为新页面。
- 通过草稿修改用户有权编辑的正式页面。
- 新建客户标签和素材标签。
- 给客户或素材添加、移除标签。
- 为指定客户取得页面访问地址；该动作会建立关系时需要确认。

**第一阶段暂不开放：**

- 删除正式客户、素材或页面。
- 创建或批量导入客户，修改客户联系方式、购房意向、状态或负责人。
- 修改素材说明或来源数据。
- 启用、停用或改变固定链接公开状态。
- 邀请成员、修改成员状态、创建角色或修改权限。
- 自动发送链接、邮件、LINE 或其他销售消息。

### 19.5 仍需在技术设计或估算中确定

1. AI 访问凭证的有效期、刷新方式、设备授权过程和安全保存位置。
2. CLI 第一批支持的操作系统、处理器、安装和升级方式。
3. 普通同步请求的超时时间，以及哪些任务改为返回任务标识后异步执行。
4. 每个列表接口的默认每页数量和最大每页数量。
5. AI 请求技术记录保存多少天，项目管理员可以看到哪些摘要。
6. 页面草稿的自动保存频率、有效期、用户主动删除和过期清理规则。
7. 内置智能体的模型选择、常用任务次数、单次模型调用次数和 Token 用量估算。
8. 内置智能体的费用由 VISTA Link 承担、计入订阅还是采用其他方式。客户没有按 Token 付费的使用习惯，因此不能在没有估算前决定收费方式或硬性用量上限。

---

## 20. 与现有资料的关系

- 当前 PRD 已把 AI 内容制作、AI 智能体和外部工具读写列为后续内容，本框架用于重新说明这部分需求。
- 历史 AI 文档同时设计过“VISTA Link 内置智能体”和“外部智能体”。本框架将两者放在平等位置，共同使用统一的 VISTA Link AI 能力层。
- HOMEVISTA 数据追踪实验已经证明：现有数据可以支持“找出高频访问客户、说明主要浏览内容、生成供销售检查的建议草稿”，但不能直接判断客户意向。
- 现有 PRD 已规定项目隔离、用户权限、Widget 规则、页面检查、统计口径和操作记录。智能体接口应复用这些规则。
- 本框架不替代正式 PRD、用例、各 Widget PRD、A 端规则或 C 端数据记录规则。

---

## 21. 面向 AI 的正式 PRD 应该怎么写

### 21.1 与传统功能 PRD 的主要区别

传统功能 PRD 常以页面和固定操作步骤为主，例如“进入页面 → 点击按钮 → 填写表单 → 保存”。面向智能体的 PRD 仍要写清业务结果，但主要对象应改成“智能体可以发现和调用哪些能力，以及每项能力如何受控”。

| 传统功能 PRD | 面向 AI 的 PRD |
|---|---|
| 以页面、按钮、表单为主要单位 | 以资源、工具、任务和结果为主要单位 |
| 用户按固定步骤操作 | 智能体可以根据目标组合多个工具 |
| 输入主要来自固定表单 | 用户先用自然语言描述，智能体再提交结构化参数 |
| 页面决定用户能看到什么 | 权限、资源说明和工具说明决定智能体能取得什么 |
| 一条主流程通常比较固定 | 同一目标可能有不同调用顺序，但结果和限制必须一致 |
| 验收主要检查页面和步骤 | 同时检查业务结果、工具选择、数据正确性、越权、确认和失败恢复 |
| 异常多是字段错误或接口错误 | 还包括需求歧义、证据不足、工具选错、重复调用和模型编造 |
| 发布后主要看功能是否可用 | 还要持续使用固定评测集检查不同模型和客户端的表现 |

最重要的变化是：

> PRD 不应该规定智能体每句话怎么说，也不应该假设模型总能正确理解。PRD 应规定 VISTA Link 必须提供什么资源和工具、工具何时能用、输入输出是什么、什么情况必须停下补问、什么情况必须确认，以及怎样证明结果正确。

### 21.2 正式 PRD 建议拆成六类约定

#### A. 业务结果

说明用户真正要完成什么，例如：

- 在当前项目中找到符合要求的素材。
- 用合法的 Widget 和素材组装页面。
- 找出指定时间内的活跃客户并查看浏览证据。

业务结果不写成“提供 AI 能力”“支持自然语言”这类空泛说法。

#### B. 对象和上下文

说明智能体需要读懂什么：

- 项目、客户、素材、Widget、页面、固定链接、访问和统计分别是什么。
- 每个对象的稳定标识、状态、版本和关系。
- 当前项目、当前用户、时间范围和数据更新时间如何传递。
- 名称相同、对象删除、素材更新和页面版本变化如何处理。

#### C. 可调用能力

每项能力独立写“能力卡”，例如：

- 搜索素材。
- 查询 Widget 候选素材。
- 创建页面草稿。
- 检查页面配置。
- 保存页面。
- 查询活跃客户。
- 查询客户追踪明细。

能力卡是面向 AI PRD 的主要正文，作用类似传统 PRD 中的功能小节。

#### D. 授权、风险和确认

说明：

- 谁可以调用。
- 可以读取哪个项目和哪些对象。
- 是否只读。
- 是否会创建、修改、删除或访问外部系统。
- 是否可以安全重试。
- 哪些操作必须由智能体先向用户确认。
- 用户拒绝、没有明确回答或会话中断后，智能体应怎样停止写入。

第一阶段的确认属于 Skill 和内置智能体规则，不要求 VISTA Link REST API 接收或验证确认凭据。真正的权限和业务校验仍由服务端执行。

MCP 的工具说明已经使用 `readOnlyHint`、`destructiveHint`、`idempotentHint` 和 `openWorldHint` 表示只读、破坏性、可重复调用和外部访问等风险信息；这些提示可以帮助客户端决定怎样展示确认，但真正的权限仍必须由服务端检查。[MCP 工具结构说明](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations)

#### E. 任务状态和恢复

面向智能体的操作可能包含多次查询、补问、确认和重试。PRD 需要说明：

- 请求当前处于查询、等待输入、等待确认、执行中、成功、部分成功还是失败。
- 哪个稳定标识代表本次任务或草稿。
- 客户端中断后能否继续。
- 网络重试是否会重复创建对象。
- 长时间任务如何查询状态和取消。

2026-07-28 版 MCP 已把请求改成自描述形式，并支持服务端返回 `input_required`，让客户端补充缺少参数或确认后重试；需要跨多次调用保存状态时，官方建议返回明确的状态标识，而不是把状态隐藏在连接中。[MCP 2026-07-28 版本说明](https://blog.modelcontextprotocol.io/posts/2026-07-28/)

#### F. 评测和验收

面向 AI 的 PRD 不能只写几个理想示例。每项主要能力都要有固定测试问题、预期工具调用、允许结果、禁止结果和评分方法。

评测至少覆盖：

- 同一要求的多种自然语言说法。
- 缺少项目、时间、客户或素材条件。
- 同名对象。
- 没有匹配结果。
- 用户无权访问。
- 素材已下线、Widget 已停用、页面已经被他人修改。
- 外部内容中含有诱导智能体越权的文字。
- 网络重试和部分失败。
- 模型给出没有数据依据的结论。

主流智能体开发工具已经把工具调用、输入输出检查、人工确认、执行记录和评测作为分别可检查的部分。OpenAI Agents SDK 的官方资料也将工具、检查、人工确认和执行记录分别处理，而不是把成功标准只写成“模型回答正确”。[OpenAI Agents SDK](https://openai.github.io/openai-agents-python/)、[人工确认](https://openai.github.io/openai-agents-python/human_in_the_loop/)、[执行记录](https://openai.github.io/openai-agents-python/tracing/)

### 21.3 一张能力卡应该包含什么

每项能力建议使用下面的固定结构：

```markdown
#### CAP-对象-编号 能力名称

**用户目标**
- 用户为什么调用这项能力。

**适用情况**
- 什么情况下应该调用。

**不适用情况**
- 什么情况下不能调用，或应该使用另一项能力。

**调用前提**
- 用户身份。
- 当前项目。
- 功能权限和数据权限。
- 依赖数据或对象状态。

**输入**
- 必填参数及类型。
- 选填参数及默认值。
- 枚举、数量和时间限制。
- 缺少参数时需要向用户补问的内容。

**处理规则**
- VISTA Link 必须执行的业务检查。
- 对象查找和排序规则。
- 版本和重复请求规则。

**输出**
- 结构化字段。
- 数据时间和来源。
- 对象入口。
- 警告和证据。

**副作用与风险**
- 是否只读。
- 是否可能删除或覆盖数据。
- 是否可以安全重试。
- 是否会访问 VISTA Link 之外的系统。

**用户确认**
- 是否需要确认。
- 确认前展示什么。
- 取消、拒绝和过期怎么处理。

**失败结果**
- 无权限、无数据、参数错误、版本变化、部分失败分别返回什么。

**操作记录**
- 记录用户、客户端、项目、对象、动作、时间和结果中的哪些内容。

**验收样例**
- 正常样例。
- 歧义样例。
- 无权限样例。
- 空结果样例。
- 重试样例。
- 禁止结果。
```

### 21.4 VISTA Link 能力卡示例

#### CAP-PAGE-01 组装分享页面草稿

**用户目标**

- 根据用户描述的客户群体和资料目的，使用当前项目中的 Widget 和素材准备一个页面草稿。

**适用情况**

- 用户已经明确当前项目。
- 用户要求新建页面，而不是查询或修改已有页面。

**不适用情况**

- 用户要求生成新的图片或视频素材。
- 用户要求使用其他项目素材。
- 用户没有页面创建权限。

**调用前提**

- 当前用户在目标项目中处于启用状态。
- 当前用户具有新建分享页面权限。
- 系统能读取当前可选 Widget 和候选素材规则。

**输入**

- `projectId`：必填，目标项目稳定标识。
- `pageGoal`：必填，页面用途。
- `audienceCriteria`：选填，客户群体的结构化条件。
- `materialCriteria`：选填，素材分类、标签和结构化属性。
- `sourcePageId`：选填，允许复制的来源页面。
- `requestId`：必填，防止重复创建。

**缺少信息时**

- 没有项目：返回需要选择的项目列表。
- 页面用途过于模糊：要求用户补充目标客户或所需内容。
- 客户条件没有真实字段：说明哪些条件无法查询。
- 素材候选过多且会产生明显不同页面：返回候选方案并请用户选择。

**处理规则**

1. 再次检查项目访问权和页面创建权限。
2. 读取当前可选 Widget 和规则。
3. 搜索当前项目素材。
4. 只把素材放入允许使用它的 Widget。
5. 检查必填 Widget、素材数量、展示形式和素材状态。
6. 生成临时草稿和预览输入，不直接保存正式页面。

**输出**

- 草稿标识和有效期。
- 页面名称、备注和封面选择。
- Widget 顺序和每个 Widget 使用的素材。
- 每项素材的选择依据。
- 未满足条件、替代选择和警告。
- 页面检查结果和预览入口或预览数据。

**副作用与风险**

- 生成临时草稿不修改正式页面。
- 正式保存属于写入操作。
- 同一个 `requestId` 重试不得生成多个正式页面。
- 不访问 VISTA Link 之外的发送渠道。

**用户确认**

- 智能体必须展示页面内容、素材、Widget、警告和保存后的固定链接结果。
- 用户确认后才能调用保存能力。
- 用户取消后不创建正式页面。

**验收样例**

- “给改善型家庭准备 3LDK、样板间和通勤资料”能得到合法草稿。
- 没有“改善型家庭”客户标签时，不能声称已经按该标签筛选客户。
- 候选素材来自其他项目时必须拒绝。
- 素材已下线时不能进入新草稿。
- 重复提交相同 `requestId` 只产生一个正式页面。

这个写法比“用户输入一句话，AI 自动生成页面”更长，但研发、测试和产品都能知道系统必须做什么，也能判断失败发生在哪一层。

### 21.5 验收要分成两层

#### 第一层：必须完全满足的系统规则

这些规则不允许用“模型偶尔会错”解释：

- 跨项目数据泄露为 0。
- 无权限读取或写入为 0。
- 未确认正式写入为 0。
- 重复请求造成重复页面为 0。
- 已下线素材进入新页面为 0。
- 违反 Widget 必填和数量规则后仍保存为 0。
- 返回对象标识、项目、状态和数据时间必须正确。

#### 第二层：需要通过评测集衡量的智能体表现

这些项目需要先建立真实测试集，再确认合格数值：

- 是否选择了正确工具。
- 是否把自然语言正确转换成筛选条件。
- 素材搜索结果是否符合用户要求。
- 页面结构是否适合目标客户和页面目的。
- 缺少条件时是否正确补问。
- 统计回答是否引用了正确数据。
- 是否把浏览行为错误写成购买意向。
- 用户换一种说法后，结果是否保持基本一致。

每次变更模型、工具说明、对象字段或主要业务规则后，都要重新运行同一批评测。

### 21.6 用例文档也要改变写法

正式用例不应为每一种用户说法各写一条，也不能只写一个理想对话。建议一条智能体用例包含：

- 用户目标。
- 可能的自然语言说法，只作示例，不限制表达。
- 智能体应使用的能力范围。
- VISTA Link 必须检查的前提。
- 正常调用过程。
- 哪些情况必须补问。
- 哪些情况必须停止。
- 哪些情况必须确认。
- 结构化结果。
- 失败和恢复。
- 禁止结果。
- 对应评测编号。

页面用例检查“人怎样操作”；智能体用例检查“系统怎样安全地提供能力，以及不同智能体是否能得到符合规则的结果”。两类用例可以引用同一条业务规则，但不能互相代替。

### 21.7 MCP、REST API 和 A2A 在 PRD 中怎么处理

- **REST API**：适合承载稳定业务接口，也可以供 CLI、网页和其他程序使用。
- **MCP**：适合把资源和工具以智能体可发现的方式提供给 Codex、Claude Code 等软件。工具可以声明输入和输出结构，并带只读、破坏性、可重复调用等提示。
- **A2A**：适合 VISTA Link 自己成为一个能处理长时间任务、返回任务状态和产物的远程智能体。Google 的官方说明把 A2A 定位为智能体之间的能力发现、任务状态和产物交换，而不是普通业务工具调用。[Google A2A 官方说明](https://developers.googleblog.com/a2a-a-new-era-of-agent-interoperability/)

本文所说的“Open API”具体指对外提供的 REST API，并使用 OpenAPI 规范描述路径、操作、输入输出和安全方式，不表示接口无需授权或向所有人公开。[OpenAPI 规范](https://spec.openapis.org/oas/latest.html)

第一阶段先做 REST API 的追加成本较低，因为 CLI、内置网页和以后其他程序都需要稳定的 HTTP 业务接口。第一阶段同时做 MCP，还要额外处理 MCP 工具和资源定义、传输、授权、版本变化以及不同客户端测试。MCP 官方资料也说明，授权是实现者花费集成时间最多的部分之一。[MCP 2026-07-28 版本说明](https://blog.modelcontextprotocol.io/posts/2026-07-28/)

按当前需求，VISTA Link 需要同时支持自建内置智能体和外部智能体。两类智能体都使用 VISTA Link 提供的数据和业务工具。VISTA Link 当前还不是一个必须自行思考和执行数小时任务的远程智能体。因此：

1. 产品 PRD 先写协议无关的业务能力。
2. 第一阶段使用 REST API，并提供 OpenAPI 接口说明；CLI 调用 REST API。
3. 第一阶段不开发 MCP 服务。以后有明确的兼容客户端需求时，再把同一业务能力包装成 MCP 工具和资源。
4. 第一阶段不需要把 A2A 作为前提。
5. 如果以后 VISTA Link 自己承担长时间页面制作或多系统任务，再单独评审 A2A。
6. 内置智能体也应调用同一套 REST API 或统一能力服务，不建立只供内置智能体使用的特殊业务路径。

### 21.8 建议的正式文档结构

后续正式写入时，建议不要把所有内容继续塞进当前 B 端 PRD 的一个小节。可以采用以下结构：

```text
VISTA Link 产品需求文档
└── 写产品位置、用户、正式范围、权限来源和与现有功能的关系

VISTA Link AI 与智能体能力 PRD
├── 1. 文档状态和版本
├── 2. 业务目标与不包含内容
├── 3. 用户、智能体、执行组件和 VISTA Link 的责任
├── 4. 对象与上下文约定
├── 5. 能力目录
├── 6. 各项能力卡
├── 7. 授权与项目隔离
├── 8. 用户确认与任务状态
├── 9. 数据时间、证据和统计说明
├── 10. 错误、重试和版本变化
├── 11. 操作记录与隐私
├── 12. 评测集与验收标准
├── 13. 分期范围
└── 14. 待确认问题

VISTA Link AI 与智能体用例
├── 只读查询用例
├── 页面组装用例
├── 客户群体用例
├── 统计问答用例
├── 页面检查用例
├── 授权和确认用例
└── 异常、越权和恢复用例

技术设计
├── REST API / MCP 映射
├── JSON Schema
├── OAuth 和客户端登记
├── 请求标识、草稿标识和任务状态
├── 接口版本与兼容方式
└── 监控、日志和评测执行方式
```

这样写可以保持三个边界：

- 产品 PRD 决定 VISTA Link 提供什么能力和遵守什么规则。
- 用例决定怎样检查不同表达、不同权限和不同异常。
- 技术设计决定使用 MCP、REST、OAuth、JSON Schema 和具体接口名称。

协议和工具名称会变化，业务对象、权限、确认和验收规则不应跟着某个模型供应商反复改写。

---

## 22. 面向开发准备的能力目录

本节把“VISTA Link 能让智能体做什么”拆成可单独说明、授权、检查和测试的能力。这里的能力名称不是最终 API、CLI 命令或 MCP 工具名称。

### 22.1 状态标记

| 标记 | 含义 |
|---|---|
| 现有业务依据 | 当前正式 PRD 和用例已经写明对应的人工操作，但 AI 接入尚未实现 |
| 后续业务依据 | 当前正式 PRD 已经写明对应业务，但不属于当前 B 端 MVP |
| AI 新需求 | 为了让智能体使用现有业务，需要新增的机器可读、授权、确认或任务能力 |
| 待确认 | 业务规则或开放范围还不够明确，不能直接进入开发 |

这些标记只说明需求依据，不表示接口已经开发完成。

### 22.2 项目、身份和能力说明

| 能力编号 | 能力名称 | 主要输入 | 主要结果 | 状态 |
|---|---|---|---|---|
| CAP-CTX-01 | 查询当前用户 | 登录或授权凭证 | 用户标识、显示名称、会话状态 | AI 新需求 |
| CAP-CTX-02 | 查询可访问项目 | 用户身份 | 项目标识、名称、成员状态 | 现有业务依据 |
| CAP-CTX-03 | 选择或切换项目 | 项目标识 | 当前项目、角色、功能权限 | 现有业务依据 |
| CAP-CTX-04 | 查询当前权限 | 项目标识、用户身份 | 允许读取和操作的能力列表 | 现有业务依据 |
| CAP-CTX-05 | 查询能力目录 | 能力版本、语言 | 能力说明、输入输出结构、风险说明 | AI 新需求 |
| CAP-CTX-06 | 查询字段和枚举 | 对象类型、项目 | 字段、类型、枚举、筛选规则 | AI 新需求 |

所有业务请求必须带明确的项目标识。CLI 中保存“默认项目”只能帮助用户少输入一次，服务端仍要检查项目和权限，不能把上一次会话中的项目当成可靠依据。

### 22.3 客户能力

| 能力编号 | 能力名称 | 主要输入 | 主要结果 | 状态 |
|---|---|---|---|---|
| CAP-CUST-01 | 浏览和搜索客户 | 姓名、标签、状态、负责人、排序、分页 | 客户列表、实际命中条件 | 现有业务依据 |
| CAP-CUST-02 | 读取客户详情 | 客户标识 | 基础资料、状态、标签、负责人、已记录意向和备注 | 现有业务依据 |
| CAP-CUST-03 | 创建客户 | 客户资料、状态、标签、负责人 | 新客户和检查结果 | 现有业务依据；AI 是否开放写入待确认 |
| CAP-CUST-04 | 修改客户资料 | 客户标识、变更项、对象版本 | 变更前后内容 | 现有业务依据；AI 是否开放写入待确认 |
| CAP-CUST-05 | 修改客户状态和标签 | 客户标识、状态或标签 | 变更前后内容 | 现有业务依据；AI 是否开放写入待确认 |
| CAP-CUST-06 | 分配或转移负责人 | 客户标识、成员标识 | 新负责人和操作记录 | 现有业务依据；AI 是否开放写入待确认 |
| CAP-CUST-07 | 导入或导出客户 | CSV 文件或筛选条件 | 检查结果、文件或任务状态 | 现有业务依据；批量开放待确认 |
| CAP-CUST-08 | 删除客户 | 客户标识、对象版本 | 删除结果和保留的历史关系说明 | 现有业务依据；高风险写入 |
| CAP-CUST-09 | 管理客户状态库 | 查询或状态变更 | 状态列表和变更结果 | 现有业务依据；管理员能力 |
| CAP-CUST-10 | 管理客户标签库 | 查询或标签变更 | 标签列表、合并或删除结果 | 现有业务依据；管理员能力 |

客户群体查找只能使用真实字段、已有标签和明确备注。自然语言中的“重视通勤”“预算有限”等描述如果没有对应字段或标签，只能返回无法精确筛选以及缺少哪些数据，不能由模型自行补写客户事实。

### 22.4 素材和 Widget 能力

| 能力编号 | 能力名称 | 主要输入 | 主要结果 | 状态 |
|---|---|---|---|---|
| CAP-MAT-01 | 浏览和搜索素材 | 名称、分类、标签、状态、结构化属性、分页 | 素材列表、命中条件 | 现有业务依据 |
| CAP-MAT-02 | 读取素材详情 | 素材标识 | 名称、说明、分类、标签、属性、来源版本、状态 | 现有业务依据 |
| CAP-MAT-03 | 取得内部预览信息 | 素材标识 | 受权限限制的预览输入或打开信息 | 现有业务依据 |
| CAP-MAT-04 | 修改素材说明和标签 | 素材标识、变更项、对象版本 | 变更前后内容 | 现有业务依据；第一阶段只开放标签写入 |
| CAP-MAT-05 | 管理素材标签库 | 查询或标签变更 | 标签列表、合并或删除结果 | 现有业务依据；管理员能力 |
| CAP-WDG-01 | 查询可选 Widget | 项目、页面上下文 | Widget 标识、名称、启停状态 | 现有业务依据 |
| CAP-WDG-02 | 查询 Widget 使用规则 | Widget 标识 | 必需规则、数量、候选素材、可编辑字段、展示形式 | 现有业务依据 |
| CAP-WDG-03 | 查询候选素材 | Widget 标识、搜索和筛选条件 | 只包含该 Widget 可用素材的列表 | 现有业务依据 |
| CAP-WDG-04 | 检查 Widget 配置 | Widget 标识、内容、素材、展示形式 | 错误、警告和可修正项 | AI 新需求，复用现有规则 |

VISTA Link 不创建或修改 Widget 定义。智能体只能在当前可选 Widget 和每个 Widget 已有规则内工作。

### 22.5 页面和固定链接能力

| 能力编号 | 能力名称 | 主要输入 | 主要结果 | 状态 |
|---|---|---|---|---|
| CAP-PAGE-01 | 浏览和搜索页面 | 名称、创建来源、可见范围、分页 | 页面列表 | 现有业务依据 |
| CAP-PAGE-02 | 读取页面详情 | 页面标识 | 来源、版本、Widget、素材、顺序、状态、链接状态 | 现有业务依据 |
| CAP-PAGE-03 | 建立空白草稿 | 页面名称、封面等允许字段 | 草稿标识和初始版本 | AI 新需求；服务器保存 |
| CAP-PAGE-04 | 从现有页面建立草稿 | 来源页面标识 | 可编辑副本、复制限制、草稿版本 | 现有业务依据与 AI 新需求 |
| CAP-PAGE-05 | 编辑页面草稿 | 草稿标识、Widget、素材、内容、展示形式、顺序 | 新草稿版本和变更摘要 | 现有业务依据与 AI 新需求 |
| CAP-PAGE-06 | 检查页面草稿 | 草稿标识或完整草稿 | 错误、警告、失效素材、停用 Widget | AI 新需求，复用现有规则 |
| CAP-PAGE-07 | 生成页面预览输入 | 草稿标识或完整草稿 | 与客户访问端一致的预览数据 | 现有业务依据 |
| CAP-PAGE-08 | 保存新页面 | 已检查草稿、请求标识 | 页面标识、版本、固定链接状态 | 现有业务依据与 AI 新需求 |
| CAP-PAGE-09 | 保存页面修改 | 页面标识、基础版本、已确认变更 | 新版本和修改结果 | 现有业务依据与 AI 新需求 |
| CAP-PAGE-10 | 删除分享页面 | 页面标识、对象版本 | 删除结果和历史访问保留说明 | 现有业务依据；高风险写入 |
| CAP-LINK-01 | 读取固定链接 | 页面标识 | 固定链接、公开状态、启用状态 | 现有业务依据 |
| CAP-LINK-02 | 取得客户专用访问地址 | 页面标识、客户标识 | 带随机客户标识参数的访问地址 | 现有业务依据；需要确认展示对象 |
| CAP-LINK-03 | 取得二维码内容 | 页面标识 | 无参数固定链接二维码内容 | 现有业务依据 |
| CAP-LINK-04 | 查询链接关联客户 | 固定链接标识 | 关联客户列表 | 现有业务依据 |
| CAP-LINK-05 | 设置公开访问 | 固定链接标识、公开状态 | 变更结果 | 现有业务依据；高风险写入 |
| CAP-LINK-06 | 启用或停用链接 | 固定链接标识、启用状态 | 变更结果 | 现有业务依据；高风险写入 |

取得链接不表示已经发送。VISTA Link 和智能体都不能把“复制地址”写成“客户已经收到”。本需求也不增加自动发送销售消息的能力。

当前 PRD 和用例已经把页面保存前的编辑内容称为“页面草稿”，但没有独立草稿列表、服务器长期保存、跨会话继续编辑和过期恢复规则。本需求不是从零增加“草稿”概念，而是把现有临时草稿扩展为服务器草稿对象。草稿不创建固定链接；只有保存为正式页面后才按现有规则创建固定链接。

### 22.6 客户追踪和营销统计能力

| 能力编号 | 能力名称 | 主要输入 | 主要结果 | 状态 |
|---|---|---|---|---|
| CAP-TRK-01 | 查询待跟进客户 | 当前项目、分页 | 有访问记录的客户、最近活跃时间、最近行为 | 后续业务依据 P1 |
| CAP-TRK-02 | 读取客户累计访问 | 客户、可选固定链接 | 访问次数、页面数、内容数、平均时长、首次和最近访问 | 后续业务依据 P1 |
| CAP-TRK-03 | 查询客户访问趋势 | 客户、固定链接、时间范围 | 按日访问次数 | 后续业务依据 P1 |
| CAP-TRK-04 | 查询客户内容浏览 | 客户、固定链接、时间范围 | 页面和内容、浏览次数、有效时长、明确动作 | 后续业务依据 P1 |
| CAP-TRK-05 | 查询单次访问过程 | 访问标识 | 页面、内容顺序、时间、有效时长、明确动作 | 后续业务依据 P1 |
| CAP-STAT-01 | 查询整体访问情况 | 时间范围、负责人 | 访问客户、首次访问、回访和按日趋势 | 后续业务依据 P2-A |
| CAP-STAT-02 | 查询活跃客户 | 时间范围、负责人、姓名、排序、分页 | 活跃客户和客观访问数据 | 后续业务依据 P2-A |
| CAP-STAT-03 | 查询内容浏览排行 | 时间范围、负责人、数量 | 分享页面和实际内容、客户数、累计有效时长 | 后续业务依据 P2-A |
| CAP-STAT-04 | 查询内容对应客户 | 内容项、时间范围、负责人 | 浏览该内容的客户名单 | 后续业务依据 P2-A |
| CAP-STAT-05 | 查询统计说明 | 指标名称 | 计算方法、时区、数据更新时间、完整性状态 | AI 新需求，依据现有统计规则 |

“最活跃”使用哪个指标，由营销统计业务能力定义。统计能力没有提供这个指标时，智能体应让用户在已有指标中选择，不能在 AI 层新增计算公式。

### 22.7 成员、角色和操作记录能力

| 能力编号 | 能力名称 | 主要输入 | 主要结果 | 状态 |
|---|---|---|---|---|
| CAP-ADM-01 | 查询项目成员 | 姓名、状态、角色、分页 | 成员列表和项目访问状态 | 现有业务依据；管理员能力 |
| CAP-ADM-02 | 邀请或修改项目成员 | 邮箱、显示名称、角色、状态 | 邀请或修改结果 | 现有业务依据；AI 是否开放写入待确认 |
| CAP-ADM-03 | 查询角色和权限 | 角色标识 | 角色名称和功能权限 | 现有业务依据；管理员能力 |
| CAP-ADM-04 | 管理自定义角色 | 角色变更 | 角色和权限变更结果 | 现有业务依据；高风险管理员能力 |
| CAP-LOG-01 | 查询操作记录 | 时间、操作人、对象、动作、分页 | 过滤后的操作记录 | 现有业务依据；需要查看权限 |

修改成员、角色和权限会影响其他人的访问，应当采用比普通页面保存更严格的确认和记录要求。第一批智能体能力可以只开放查询。

### 22.8 AI 接入本身需要的共用能力

| 能力编号 | 能力名称 | 用途 | 状态 |
|---|---|---|---|
| CAP-AI-01 | 建立和撤销用户授权 | 让外部或内置智能体以用户身份工作 | AI 新需求 |
| CAP-AI-04 | 防止重复写入 | 相同请求重试时不重复创建页面或重复变更 | AI 新需求 |
| CAP-AI-05 | 查询任务状态 | 查询准备中、等待确认、执行中、完成、失败或取消 | AI 新需求 |
| CAP-AI-06 | 取消长时间任务 | 停止尚未完成且允许取消的任务 | AI 新需求 |
| CAP-AI-07 | 返回证据引用 | 让统计回答指向客户、访问、页面和内容记录 | AI 新需求 |
| CAP-AI-08 | 返回数据质量状态 | 说明更新时间、延迟、缺失和失败，不把错误写成空数据 | AI 新需求 |

---

## 23. 代表场景目录

代表场景用来告诉开发“哪些能力需要能够组合使用”。它们不是用户所有可能说法的清单。同一场景应准备多种自然语言表达、不同数据状态、不同权限和异常情况作为评测任务。

### 23.1 项目和权限

| 场景编号 | 用户可能会说 | 需要使用的能力 | 合格结果 |
|---|---|---|---|
| SCN-CTX-01 | “帮我看看目前有哪些项目可以用。” | CAP-CTX-01、02 | 只返回该用户启用的项目，并带稳定标识 |
| SCN-CTX-02 | “在海湾花园项目里找资料。” | CAP-CTX-02、03、04 | 明确切到指定项目，再开始查询；同名项目需要用户选择 |
| SCN-CTX-03 | “你现在能帮我做什么？” | CAP-CTX-04、05 | 按用户真实权限说明可读、可写和需要确认的能力 |
| SCN-CTX-04 | “把 A 项目的客户和 B 项目的素材一起做个页面。” | CAP-CTX-03、04 | 拒绝混合项目数据，说明一次请求只能使用一个当前项目 |

### 23.2 素材查找和判断

| 场景编号 | 用户可能会说 | 需要使用的能力 | 合格结果 |
|---|---|---|---|
| SCN-MAT-01 | “找出当前项目里所有三居室户型图。” | CAP-MAT-01、02 | 使用真实分类和结构化属性，返回命中条件和候选素材 |
| SCN-MAT-02 | “找适合有孩子家庭看的内容。” | CAP-CUST-01、CAP-MAT-01、02 | 先把描述映射到已有客户字段或标签；没有对应数据时说明限制 |
| SCN-MAT-03 | “给这个户型 Widget 找几张能用的素材。” | CAP-WDG-02、03、CAP-MAT-02 | 只从 Widget 候选范围内选，并遵守数量规则 |
| SCN-MAT-04 | “比较这两个户型资料有什么不同。” | CAP-MAT-02、03 | 按现有结构化字段比较，缺少的字段明确标出 |
| SCN-MAT-05 | “找一下最近更新过、页面里可能需要替换的素材。” | CAP-MAT-01、02、CAP-PAGE-01、02 | 返回素材版本和受影响页面，不自动替换 |

### 23.3 页面准备、检查和保存

| 场景编号 | 用户可能会说 | 需要使用的能力 | 合格结果 |
|---|---|---|---|
| SCN-PAGE-01 | “用项目里的户型、眺望和周边交通资料做一个页面。” | CAP-MAT-01、02、CAP-WDG-01～04、CAP-PAGE-03、05～08 | 生成合规草稿和预览；确认后只创建一个页面 |
| SCN-PAGE-02 | “复制系统的标准页面，只保留适合首次来访客户的内容。” | CAP-PAGE-01、02、04～09 | 复制为可编辑草稿，不修改来源页面 |
| SCN-PAGE-03 | “为预算 8000 万日元以内、想要三居室的客户准备页面。” | CAP-CUST-01、02、CAP-MAT-01、02、CAP-PAGE-03、05～08 | 只使用已记录的客户条件和素材属性，并说明选择依据 |
| SCN-PAGE-04 | “给客户李娜准备她最近关注内容的后续页面。” | CAP-CUST-01、02、CAP-TRK-02、04、CAP-MAT-01、CAP-PAGE-03、05～08 | 同名客户先选择；行为只作为资料准备依据，不写成购买意向 |
| SCN-PAGE-04A | “客户大约 45 岁，夫妻二人，有一个上小学的孩子，帮我用项目材料做一个页面。” | CAP-CUST-01、02、CAP-MAT-01、02、CAP-WDG-01～04、CAP-PAGE-03、05～08、CAP-LINK-02 | 分开标明已保存资料和本次临时描述；临时描述可用于选材但不自动写回客户资料；确认后保存页面并取得访问地址 |
| SCN-PAGE-05 | “检查一下这个页面有没有失效内容。” | CAP-PAGE-02、06、CAP-MAT-02、CAP-WDG-02 | 返回失效素材、停用 Widget 和规则问题，不直接改 |
| SCN-PAGE-06 | “把检查出的问题都修好。” | CAP-PAGE-02、05、06、07、09 | 先给变更预览；确认后按页面最新版本保存 |
| SCN-PAGE-07 | “给这 20 个客户每人做一个页面。” | CAP-CUST-01、CAP-PAGE-03～08 | 返回总数量、目标客户、命名依据和重复风险；一次确认后可分批执行并逐项返回结果 |
| SCN-PAGE-08 | “页面做好后发给客户。” | CAP-PAGE-08、CAP-LINK-01、02 | 可以准备页面和访问地址，但明确 VISTA Link 不负责发送消息 |

### 23.4 客户查找和资料维护

| 场景编号 | 用户可能会说 | 需要使用的能力 | 合格结果 |
|---|---|---|---|
| SCN-CUST-01 | “找出标签同时包含首次购房和重视通勤的客户。” | CAP-CUST-01 | 使用项目中真实存在的多个标签，并返回实际命中条件 |
| SCN-CUST-02 | “找出想尽快入住的客户。” | CAP-CUST-01、02 | 只按明确字段、标签或备注查找；资料不足时说明无法准确筛选 |
| SCN-CUST-03 | “把这些客户都加上高意向标签。” | CAP-CUST-01、05 | 不根据浏览行为自行判断高意向；若用户明确要求且有权限，仍需展示名单和确认 |
| SCN-CUST-04 | “把李娜转给田中负责。” | CAP-CUST-01、02、06、CAP-ADM-01 | 处理同名客户和成员选择，展示变更后再确认 |
| SCN-CUST-05 | “删除重复客户。” | CAP-CUST-01、02、08 | 不仅凭同名判断重复；删除目标必须逐项确认并说明历史记录保留规则 |

### 23.5 客户追踪和统计问答

| 场景编号 | 用户可能会说 | 需要使用的能力 | 合格结果 |
|---|---|---|---|
| SCN-STAT-01 | “最近 7 天最活跃的客户有哪些？” | CAP-STAT-02、05 | 使用营销统计已经定义的指标；没有对应指标时让用户选择已有排序，不自行计算新指标 |
| SCN-STAT-01A | “最近 30 天最值得跟进的客户是谁？最活跃的是谁？他主要对什么感兴趣？” | CAP-STAT-02、05、CAP-TRK-02、04、05 | 先返回正式客户排行和采用的排序；再列主要浏览内容和客观行为；“值得跟进”只能写成供销售查看的建议，不能生成客户分数、意向等级或确定结论 |
| SCN-STAT-02 | “这几天大家最关心什么内容？” | CAP-STAT-03、05 | 返回浏览客户数和累计有效时长；不把浏览写成购买意向 |
| SCN-STAT-03 | “哪些客户看过 3LDK A 户型？” | CAP-STAT-03、04 | 按“分享页面 + 实际内容”识别并返回客户名单 |
| SCN-STAT-04 | “李娜最近都看了什么？” | CAP-CUST-01、CAP-TRK-02～05 | 返回页面、内容、时间和明确动作，并能指向对应记录 |
| SCN-STAT-05 | “客户是不是对高层更有兴趣？” | CAP-TRK-04、05、CAP-STAT-05 | 把已有浏览证据和解释分开；不输出确定购买意向 |
| SCN-STAT-06 | “哪个户型最受欢迎？” | CAP-STAT-03、04、05 | 先说明“受欢迎”可按客户数或有效时长判断；回答带实际指标 |
| SCN-STAT-07 | “为什么统计里没有昨天的访问？” | CAP-STAT-05、CAP-AI-08 | 区分没有数据、延迟、读取失败和筛选条件问题 |
| SCN-STAT-08 | “根据最近记录，我应该给李娜准备什么？” | CAP-TRK-02、04、05、CAP-MAT-01、02 | 给出可检查的素材候选和依据，不自动保存页面，不承诺销售结果 |

### 23.6 固定链接

| 场景编号 | 用户可能会说 | 需要使用的能力 | 合格结果 |
|---|---|---|---|
| SCN-LINK-01 | “给李娜生成这个页面的专用地址。” | CAP-CUST-01、CAP-LINK-01、02 | 明确客户和页面，返回访问地址，不记录完整客户标识参数 |
| SCN-LINK-02 | “把这个页面设为公开。” | CAP-LINK-01、05 | Skill 要求先说明公开后的访问变化；用户明确同意后修改并记录 |
| SCN-LINK-03 | “先停掉这个链接。” | CAP-LINK-01、06 | Skill 要求先说明客户将无法访问；用户明确同意后停用，历史记录保留 |
| SCN-LINK-04 | “这个链接发给过谁？” | CAP-LINK-04 | 只能回答已建立关联的客户；不能把关联关系说成实际发送记录 |

### 23.7 管理和异常

| 场景编号 | 用户可能会说 | 需要使用的能力 | 合格结果 |
|---|---|---|---|
| SCN-ADM-01 | “谁可以删除客户？” | CAP-CTX-04、CAP-ADM-03 | 返回当前项目中的真实角色和权限 |
| SCN-ADM-02 | “邀请山田加入项目并给他销售角色。” | CAP-ADM-01～03 | 检查管理员权限；Skill 要求展示邮箱、项目和角色后确认 |
| SCN-ADM-03 | “谁在昨天停用了这个链接？” | CAP-LOG-01 | 按对象和时间查询操作记录，不返回无权查看的记录 |
| SCN-ERR-01 | “继续刚才没做完的页面。” | CAP-AI-05、CAP-PAGE-03～07 | 找到明确任务和草稿；无法唯一确定时让用户选择 |
| SCN-ERR-02 | 保存页面时其他人已经改过 | CAP-PAGE-02、09 | 拒绝旧版本覆盖，重新读取变化并再次确认 |
| SCN-ERR-03 | 保存请求超时后再次提交 | CAP-AI-04、05 | 查询原请求结果，不重复创建或修改 |
| SCN-ERR-04 | 素材查询服务失败 | CAP-AI-08 | 返回读取失败和重试建议，不能写成“没有符合条件的素材” |
| SCN-ERR-05 | 用户授权在任务中途被撤销 | CAP-AI-01、05 | 停止后续读取和写入，保留已经完成且可追查的结果 |

### 23.8 首批评测建议

为了让开发尽早验证整体结构，首批可先准备以下 8 组任务。这里是建议顺序，不是已确认的发布计划。

1. 在明确项目中按分类和结构化属性查找素材。
2. 查询 Widget 规则，并从候选范围内选择素材。
3. 从空白开始生成页面草稿、检查并预览。
4. 用户确认后保存一次，重复请求不重复创建。
5. 按已有客户标签筛选客户；条件不存在时明确说明。
6. 查询最近 7 天活跃客户，并说明时间、指标和数据更新时间。
7. 从内容排行进入客户名单，再进入单个客户追踪记录。
8. 验证越权、跨项目、版本变化、读取失败和授权撤销。

每组任务至少应包含：正常数据、空结果、同名对象、权限不足、数据变化和服务失败。页面组装任务还应包含 Widget 数量不符、素材下线和 Widget 停用。

---

## 24. 两种运行方式

下面两种方式是产品需要允许的使用形式，但具体协议、语言和部署方式属于技术设计。产品要求是：两种方式看到相同的能力说明，使用相同的项目、权限、检查、确认和操作记录。

### 24.1 外部智能体通过 CLI 程序使用 VISTA Link

可能的过程如下：

```text
用户
→ Codex、Claude Code 或其他智能体
→ VISTA Link Skill 或说明文件
→ 本地 VISTA Link CLI 程序
→ VISTA Link 能力服务
→ 现有业务服务和数据
```

这里 Codex 是任务发起者和安排者，CLI 程序是实际执行组件。Codex 不需要自己编写 HTTP 请求，也不要求模型直接持有 VISTA Link API 细节。

如果采用这一方式，VISTA Link 需要准备：

- 可下载、可验证来源和版本的 CLI 二进制文件。
- 支持哪些操作系统和处理器，待技术设计确认。
- 安装、升级、卸载和版本兼容说明。
- 登录、授权、查看状态和退出能力；不要求用户把密码写进 Skill。
- 适合智能体调用的非交互命令。
- 稳定的 JSON 输入输出，同时保留供人阅读的简短输出。
- 明确的退出状态、错误代码、请求标识、分页和超时规则。
- 能查询能力目录、字段说明和版本。
- CLI 返回足够的对象和变更结果，供 Skill 在调用写入命令前向用户说明。
- 日志中隐藏 Token、密码、客户标识参数和客户访问会话凭据。
- 一份 VISTA Link Skill，说明何时使用哪些命令、哪些操作必须先询问用户、怎样解释统计结果。

第一阶段 CLI 直接调用 VISTA Link REST API。以后增加 MCP 时，CLI 是否继续直接调用 REST API 不受影响。

### 24.2 VISTA Link 内置服务器智能体

可能的过程如下：

```text
用户
→ VISTA Link 网页中的对话入口
→ 服务器上的智能体运行程序
   ├→ 大模型调用组件
   └→ VISTA Link 工具执行组件
→ VISTA Link 能力服务
→ 现有业务服务和数据
```

用户通过网页输入和查看结果，真正的智能体运行程序在服务器上。它至少需要：

- 以当前登录用户和当前项目身份建立任务。
- 调用一个或多个可更换的大模型，并保存所用模型和版本信息。
- 把 VISTA Link 能力目录提供给模型，让模型选择需要的能力。
- 由服务器工具执行组件完成实际业务请求，不让模型直接访问数据库。
- 保存会话、任务和草稿状态；等待确认可以保留在智能体会话中。
- 支持逐步返回结果、取消任务、失败重试和恢复未完成任务。
- 第一版可以用文字展示查询条件、证据和变更内容；页面制作需要页面预览。
- 权限变化或授权撤销后，下一次动作立即使用最新结果。
- 记录模型请求、工具动作和业务结果之间的关系，同时按隐私规则隐藏敏感内容。

内置智能体可以有更贴近 VISTA Link 的网页体验，但不能拥有只供自己使用的业务规则或数据库写入路径。

第一版可以只提供文字回答和一个简单输入框。页面组装任务需要打开页面预览，其他查询不要求专门制作结果卡片。入口处可以提供以下常用问题示例，示例文案不构成新的业务能力：

- 查找当前项目中的某类素材。
- 用指定素材和 Widget 准备页面。
- 按客户标签查找客户并准备页面。
- 检查页面中的失效素材和 Widget 问题。
- 查询最近 30 天最活跃的客户。
- 查询某位客户最近浏览的内容。
- 查询最近浏览客户数最多的内容。
- 根据客户最近记录准备下一次可以发送的资料。

### 24.3 两种方式共用的要求

| 项目 | 外部 CLI 方式 | 内置服务器智能体 | 共同要求 |
|---|---|---|---|
| 用户入口 | Codex、Claude Code 等软件 | VISTA Link 网页 | 用户身份可确认 |
| 任务安排 | 外部智能体 | 服务器智能体运行程序 | 使用同一能力说明 |
| 实际执行 | 本地 CLI 或其后端服务 | 服务器工具执行组件 | 使用同一业务能力服务 |
| 模型 | 由外部智能体决定 | 由 VISTA Link 配置 | 不改变业务规则 |
| 权限 | 用户委托授权加项目权限 | 登录用户、当前项目和项目权限 | 服务端再次检查 |
| 确认 | Skill 要求智能体询问用户 | 内置智能体规则要求询问用户 | 第一阶段不由 REST API 验证或记录确认 |
| 结果 | JSON 和智能体回答 | 网页结果和智能体回答 | 对象标识、状态、证据和错误含义一致 |
| 操作记录 | 记录智能体、CLI 和用户 | 记录智能体运行程序和用户 | 能查到谁在何时做了什么 |

### 24.4 不应写死在产品需求中的内容

以下内容可以在技术设计中选择，不应成为某个业务能力成立的前提：

- CLI 使用什么编程语言。
- 后续 MCP 适配层怎样把 REST API 业务能力包装成工具和资源。
- 内置智能体使用哪家模型。
- 模型提示词的具体文本。
- 服务器任务队列、数据库和消息组件的具体产品。
- 智能体怎样安排某一次任务的每一个中间步骤。

产品需求需要写死的是：可用业务能力、对象含义、权限、项目范围、确认要求、数据证据、失败含义和验收结果。

---

## 25. 接口用量、返回数量、超时和费用

### 25.1 调用次数

- 第一阶段不设置正常用户每天或每月可以调用多少次的产品限制。
- 为防止攻击、程序错误或智能体失控循环，技术系统可以临时拒绝明显异常的高频请求。
- 安全保护触发时应返回明确错误和可重试时间，不能假装成没有数据。
- 安全保护不等于按调用次数收费，也不作为正常用户的使用额度。

### 25.2 返回数量

“返回数量”指列表接口一次返回多少条客户、素材、页面或访问记录，不是系统允许保存多少数据。

- 每个列表接口使用分页或游标连续读取。
- 默认每页数量和最大每页数量由接口设计确定，不在本需求中写死。
- 返回结果至少说明本页数量、是否还有下一页以及继续读取所需参数。
- 智能体需要全部结果时可以继续读取，不能把第一页误写成全部数据。
- AI 接口不另加总数量限制；执行组件可以按页面业务允许的范围分批提交并汇总结果。

### 25.3 超时

- 普通查询和单项写入使用同步接口。
- 预计不能在普通请求时间内完成的批量任务，先返回任务标识，再查询进度和结果。
- 具体超时秒数由技术设计根据部署环境和数据量确定，并写入接口说明。
- 超时结果必须带请求标识、当前状态和是否可以安全重试。
- 写入超时后先查询原请求结果，不能直接再次创建对象。
- 正式开发前应为普通读取、普通写入和长时间任务分别确定可测量的响应时间目标。

### 25.4 费用

费用需要分成两类：

1. **VISTA Link REST API 和 CLI 调用**：第一阶段不按调用次数向客户收费，也不设置商业用量额度。
2. **大模型费用**：外部智能体使用什么模型及其费用由外部智能体软件决定；VISTA Link 内置智能体产生的模型 Token 费用需要单独估算。

内置智能体正式提供前，应使用本文件的代表场景评估：

- 每类任务平均调用模型多少次。
- 每次输入和输出使用多少 Token。
- 每次任务调用 VISTA Link 工具多少次。
- 重试、失败和长对话增加多少用量。
- 每位日常用户一天和一个月大约执行多少任务。
- 不同模型选择对应的单次和月度成本。

在完成估算前，不确定按 Token 收费、次数收费或设置固定用量。客户不习惯按 Token 付费，因此优先评估能否把常用用量包含在现有订阅中，并用异常调用保护控制非正常消耗。