最初讨论 AI 助手时，很容易把目标理解成“在系统里增加一个聊天窗口”。但真正开始落地后会发现，聊天只是最表层的交互。

用户真正需要的不是另一个搜索框，而是一个能够理解当前环境、找到正确答案、查询实时信息，并把结果带回业务流程的协作者。

因此，落地的重点并不是如何调用模型，而是如何让模型在产品边界内可靠工作。

## 我们最终想做成什么

理想中的业务助手应该是产品的一层统一交互界面，而不是一个孤立页面。

用户可以从不同位置发起需求：直接提问、使用快捷入口，或者把当前看到的内容交给助手继续处理。助手能够理解用户所处的页面和当前意图，然后在三类能力中选择合适的处理方式：

- 使用产品知识回答问题；
- 在权限范围内查询实时数据；
- 将自然语言整理成可供业务模块使用的结构化结果。

最终效果可以概括为：

```text
用户表达意图
    ↓
助手理解当前上下文
    ↓
知识回答 / 实时查询 / 配置整理
    ↓
结果回到原有业务流程
    ↓
用户确认重要操作
```

这里最关键的一点是，助手不会取代业务系统。

权限校验、数据约束和最终执行仍然由原有系统负责。助手只承担理解、组织和衔接，让用户少找入口、少读说明、少重复填写。

## 目前做到哪一步

当前版本已经完成了从“聊天”到“业务协作”的基础闭环：

- 不同入口可以汇入同一套对话体验；
- 助手能够结合产品知识和当前页面理解问题；
- 动态信息通过受控工具查询，而不是由模型猜测；
- 自然语言可以整理成经过校验的结构化结果；
- 结果能够回到已有业务模块，并由用户确认后继续执行；
- 回复过程支持流式反馈、停止、失败提示和重试。

这意味着它已经不只是一个演示型聊天窗口，但仍然不是能够独立完成长流程的全自动 Agent。当前形态更接近“有边界的业务协作者”。

## 当前选择了怎样的架构

实现上将系统分为交互层、可信业务层和 AI 编排层，知识、工具与模型作为编排层依赖的能力资源：

```text
┌──────────┐
│   用户   │
└────┬─────┘
     │
     ▼
┌──────────┐
│  交互层  │
└────┬─────┘
     │ 用户输入与页面上下文
     ▼
┌──────────────┐
│ 可信业务层   │◀──────────────┐
└──────┬───────┘               │
       │ 可信身份与受控请求     │ 受权限约束的查询
       ▼                        │
┌──────────────┐        ┌───────┴──────┐
│ AI 编排层    │───────▶│   受控工具   │
└───┬──────┬───┘        └──────────────┘
    │      │
    ▼      ▼
┌────────┐ ┌────────┐
│产品知识│ │  模型  │
└────────┘ └────────┘

流式结果：AI 编排层 → 可信业务层 → 交互层
```

### 交互层：管理体验，不建立信任

交互层负责接收输入、携带有限的页面上下文、展示流式回复，并把结构化结果呈现为可确认的操作。不同入口最终都会汇入同一套对话状态，避免每个页面各自维护一套助手逻辑。

这一层提供的是用户体验，而不是安全依据。浏览器提交的身份、权限或目标数据都不能直接被内部能力信任。

### 可信业务层：连接账号体系与 AI

可信业务层沿用原有登录和权限体系。它校验公开请求，从服务端上下文中取得当前用户身份，再生成发送给 AI 编排层的可信请求。

它还承担两个方向的适配：向内隐藏公网协议和浏览器细节，向外隐藏内部服务、模型和工具的实现。Agent 需要查询动态数据时，也必须通过这一层回到正常业务权限体系，而不是直接访问数据源。

### AI 编排层：决定本轮需要什么能力

AI 编排层管理对话 Session，并根据当前问题组合必要上下文。它会先选择相关产品知识，再判断是否需要调用白名单工具，最后将模型文本、处理状态和结构化结果统一转换成流式事件。

模型只是编排层中的一个依赖。知识检索、工具权限、会话生命周期和结果校验都由普通代码控制，不依赖模型自行遵守一段提示词。

### 一次请求如何流转

一轮对话大致经过以下过程：

1. 交互层提交用户输入、对话标识和经过裁剪的页面上下文。
2. 可信业务层完成登录校验，并补充服务端确认的身份和权限信息。
3. AI 编排层取得或创建当前会话，检索与问题相关的产品知识。
4. 如果需要实时数据，编排层调用限定工具；工具仍通过可信业务层执行权限校验。
5. 模型基于当前问题、少量相关知识和工具结果生成回复。
6. 文本、状态或结构化结果沿原链路持续返回交互层。

任何一层失败，都只向上一层返回约定好的错误，不把内部异常、模型信息或工具参数直接暴露给浏览器。

这不是最少代码的方案，却是职责最清晰的方案。

如果浏览器直接连接模型，身份和工具权限很难形成可靠边界；如果所有能力都堆进业务服务，模型运行时、知识更新和普通业务逻辑又会彼此干扰。将 AI 编排独立出来后，模型或检索方案可以替换，业务权限不需要随之重写，前端也不必了解内部变化。

## 为什么不把所有知识都写进提示词

系统早期最简单的做法，是把产品说明全部塞进系统提示词。但随着页面和规则增加，这种方式会快速失控：

- 每次请求都携带大量无关内容；
- 产品变化后很难知道应该修改哪里；
- 不同角色可能看到不属于自己的说明；
- 内容无法独立校验和测试。

当前方案将产品知识作为结构化内容单独维护，在构建时完成校验，在对话时只取与当前问题相关的少量内容。

现阶段没有引入复杂的向量检索基础设施。原因并不是否定它，而是当前知识规模仍然可控，确定性、可审查性和低维护成本更重要。轻量检索足以解决主要问题，也更容易判断一次回答究竟引用了什么。

当知识量、表达差异和跨文档关系继续增长时，再评估更复杂的检索方案会更合理。

## 为什么要把“能力”做成结构化协议

普通问答可以返回自然语言，但业务配置不能只依赖模型输出一段看起来像 JSON 的文本。

当前设计要求用户先明确选择能力，服务端再限制本轮可使用的工具。工具返回经过约束的结构化结果，前端校验通过后，才允许用户将它应用到对应业务模块。

这样做的原因有三个：

1. 避免普通聊天意外触发业务操作；
2. 避免模型自行决定目标页面或执行范围；
3. 让结构化结果可以被类型、测试和前端组件共同约束。

即使配置已经生成，也不会自动执行重要操作。用户仍然需要回到业务界面核对并确认。

这让助手更像一个可靠的准备者，而不是拥有无限权限的自动驾驶系统。

## 为什么保留流式响应

AI 请求的耗时不可预测。如果只能等待完整结果，用户很难判断系统是否仍在工作。

流式响应可以及时展示思考、检索、工具调用和文本输出等阶段，也允许用户中途停止。它带来的额外复杂度是前端必须维护明确状态，而不能只是不断拼接字符串。

当前选择流式方案，是在响应体验和实现复杂度之间的折中。它比轮询更及时，也比维护一套双向长连接协议更轻量，适合以“用户发起一次请求、服务端持续返回结果”为主的交互。

## 安全边界是如何确定的

这套设计遵循几个简单原则：

- 浏览器不能声明自己的真实身份和权限；
- 模型不能直接访问数据库或任意内部服务；
- 工具只能使用业务服务提供的可信上下文；
- 模型输出在展示和执行前都要再次校验；
- 内部错误、提示词、供应商信息和凭据不会返回给用户；
- 涉及重要状态变化的操作必须由用户确认。

这些限制会牺牲一部分“无所不能”的感觉，却能让助手真正进入生产系统。

一个助手能做多少事情并不是最重要的，重要的是系统能否明确解释：它为什么能做、可以替谁做、做到哪一步，以及谁来承担最终确认。

## 当前形态还缺什么

目前的设计已经打通了问答、知识、实时工具和结构化结果，但距离更成熟的形态仍有几块需要补齐。

### 1. 更系统的知识治理

知识已经可以结构化维护，但还需要术语规范、内容负责人、过期检查和变更审阅机制。否则条目数量增加后，仍然可能出现重复、冲突和旧规则残留。

### 2. 可重复的回答质量评估

现有自动化测试主要保证权限、协议和数据结构不会越界。下一步还需要建立典型问题集，持续评估知识命中、回答正确性、引用完整性和拒答表现。

### 3. 多实例会话能力

轻量的内存会话适合当前阶段，但在多实例部署、滚动发布或长周期对话场景中，需要进一步考虑共享会话、会话迁移和一致性问题。

### 4. 更完整的失败降级

模型、知识服务或实时工具不可用时，助手应该有明确的降级路径，例如返回基础帮助、引导用户进入对应模块，或允许稍后重试，而不是只有一个统一错误提示。

### 5. 用户反馈闭环

系统还需要知道哪些回答真正解决了问题、哪些配置被用户修改、哪些建议最终被采用。只有建立反馈闭环，才能判断应该优化知识、工具还是交互。

### 6. 更长流程的协作能力

当前助手更擅长单轮查询和一次配置整理。未来如果要支持多步骤业务流程，需要引入更明确的任务状态、阶段确认、可恢复执行和操作审计，而不是简单增加提示词长度。

## 这套路线的取舍

这套实现没有追求一步做到完全自动化，而是优先解决三个问题：

1. **可信**：身份、权限和执行边界不交给模型判断。
2. **可控**：知识、工具和结构化结果都能被代码验证。
3. **可演进**：模型、检索方式和业务能力可以分别替换。

如果只是做演示，浏览器直接调用模型并准备一段长提示词会更快。但当助手需要进入真实业务系统时，身份边界、知识治理、工具权限和用户确认迟早都要补上。当前方案选择先建立这些基础能力，换取后续演进时不必反复推翻底层结构。

## 结语

业务型 AI 助手的最终形态，不是一个回答所有问题的聊天窗口，而是一层能够理解上下文、连接知识与工具、并尊重业务边界的交互入口。

当前实现只是其中一个阶段：它已经从“聊天”走向“协作”，但还需要知识治理、质量评估、会话基础设施、失败降级和反馈闭环，才能逐渐成为稳定的产品能力。

真正值得投入的并不是让助手显得更聪明，而是让它在知道什么、能做什么和不能做什么这三件事上越来越可靠。

【AI】AI 助手不只是聊天窗口：一次业务化落地的设计思考

在使用 Pi、Codex 或其他 AI Agent 时，我们经常会产生一种错觉：只要会话没有关闭，模型就能记住从开始到现在的全部内容。

事实并非如此。

模型拥有的是一个大小有限的上下文窗口，而 Agent 保存的 Session 可以持续增长。为了让长期任务继续运行，Agent 必须不断把庞大的历史记录整理成模型当前能够处理的“工作上下文”。这个过程就是上下文压缩（Context Compaction）。

## 一、Session 不等于上下文

理解上下文压缩，首先需要区分两个概念：

```text
Session = 完整档案库
Context = 本次模型调用能够看到的工作材料
```

Session 可以包含：

- 用户和助手的完整消息；
- 工具调用及其结果；
- 模型切换记录；
- 对话分支；
- 压缩记录；
- 文件读取和修改信息。

上下文则受到模型窗口限制。即使 Session 已经积累了几十万甚至上百万 Token，一次模型请求也只能携带窗口允许的部分内容。

因此，模型并不是直接“读取整个 Session”。真正的过程是：

```text
完整 Session
    ↓
选择当前对话分支
    ↓
排除不需要发送的内容
    ↓
用摘要替代较早历史
    ↓
保留最近的原始消息
    ↓
构造本次模型请求
```

## 二、上下文压缩是如何工作的

一次典型的压缩可以分为五步。

### 1. 判断是否接近模型窗口

Agent 通常不会等到模型明确返回“上下文超限”才处理，而是预留一部分安全空间。

以 Pi 为例，自动压缩的判断可以概括为：

```text
contextTokens > contextWindow - reserveTokens
```

Pi 默认预留 `16,384` Token，并默认保留最近约 `20,000` Token 的原始内容。这些值可以配置。

预留空间有两个作用：

1. 为模型下一次回复和工具调用留下空间；
2. 容纳 Token 估算与模型实际计费之间的误差。

### 2. 确定历史切割点

Agent 从最新消息向前计算，尽量保留最近的完整对话轮次：

```text
用户消息
→ 助手回复
→ 工具调用
→ 工具结果
```

正常情况下，压缩不会把工具调用和工具结果从中间拆开。如果单个任务本身已经特别长，也可能在同一轮任务中切割，再分别总结历史部分和当前任务的前半部分。

### 3. 为较早内容生成摘要

需要压缩的旧消息会被序列化并交给模型总结。Pi 默认采用结构化格式，内容通常包括：

```markdown
## Goal
用户正在实现什么目标

## Constraints & Preferences
用户提出的约束和偏好

## Progress
已经完成、正在进行和被阻塞的工作

## Key Decisions
关键决策及其原因

## Next Steps
下一步工作

## Critical Context
继续任务必须知道的信息

<read-files>
读取过的文件
</read-files>

<modified-files>
修改过的文件
</modified-files>
```

这种结构并不是为了给人阅读得更漂亮，而是为了让模型在失去原始历史后，仍然能够恢复任务状态。

### 4. 追加压缩检查点

压缩通常不会直接覆盖或删除原始 Session，而是追加一条压缩记录。

以 Pi 的 `CompactionEntry` 为例：

```json
{
  "type": "compaction",
  "summary": "较早历史的结构化摘要",
  "firstKeptEntryId": "最近原始消息的起点",
  "tokensBefore": 100000
}
```

较新的实现还可以把保留的近期消息写入 `retainedTail`，使压缩记录成为一个可以独立恢复的上下文检查点。

### 5. 重建下一轮模型上下文

压缩完成后，模型下一轮看到的内容变为：

```text
System Prompt
+ 历史摘要
+ 最近保留的原始消息
+ 压缩后产生的新消息
```

旧消息仍然存在于 Session 文件中，只是不再发送给模型。

所以更准确的说法是：

> 物理上保留完整历史，逻辑上用摘要替代较早上下文。

## 三、模型不会主动读取 Session

模型本身无法访问 Agent 的 Session 文件，也不知道磁盘上是否保存了完整历史。

它只能看到 Agent 在本次请求中发送的内容。所谓“模型读取压缩摘要”，实际是 Agent 主动完成了以下工作：

```text
Agent 读取 Session
→ 找到最新压缩检查点
→ 取出摘要和最近消息
→ 拼接 System Prompt
→ 发送给模型
```

因此，上下文管理是 Agent 框架的能力，而不是模型自己拥有了无限记忆。

## 四、压缩时机为什么不可能绝对精确

Agent 记录的上下文与模型实际收到的请求并不一定逐字一致。

中间可能存在：

- System Prompt 的动态构建；
- 当前分支筛选；
- 不进入模型上下文的命令记录；
- Extension 对消息的临时过滤或注入；
- Provider 对消息、工具和图片的格式转换；
- 最终请求 Payload 的重写；
- 不同模型 Tokenizer 的计算差异。

Pi 会优先参考上一次模型响应返回的实际 Usage，再估算随后新增的消息。由于仍存在误差，默认的 `reserveTokens` 会提供安全余量。

这会产生两种情况。

### 提前压缩

```text
Pi 估算已经达到阈值
模型实际仍有空间
```

压缩依然可以成功，因为生成摘要并不要求原请求已经真正溢出。提前压缩的代价主要是额外费用、延迟，以及旧内容更早被有损摘要替代。

### 延迟压缩

```text
Pi 估算仍未达到阈值
模型实际请求已经超限
```

此时 Agent 可以在 Provider 返回上下文溢出后触发压缩，并重试刚才的请求。

因此，成熟的上下文管理通常包含两层保护：

```text
主动保护：接近阈值时提前压缩
被动保护：实际溢出后压缩并重试
```

## 五、压缩是有损的，不等于长期记忆

压缩摘要会保留主要目标和任务状态，但不保证保留每个细节。

多次压缩后可能出现：

- 用户原始措辞丢失；
- 次要约束被忽略；
- 工具输出被截断；
- 早期事实逐渐失真；
- 摘要中的错误被后续摘要继承。

因此，以下内容不应该只依赖上下文摘要：

- 用户长期偏好；
- 权限和组织信息；
- 已确认的业务配置；
- 订单、任务和资源 ID；
- 必须精确保留的历史事实；
- 系统知识与产品说明。

一个更合理的分工是：

```text
业务数据库
├── 完整聊天记录
├── 用户长期记忆
├── 权限与业务状态
└── 可审计的关键事实

Agent Session
├── 当前任务历史
├── 工具调用轨迹
└── 压缩检查点

模型上下文
├── System Prompt
├── 历史摘要
├── 最近消息
└── 当前工具结果
```

## 六、Pi 与 Codex 的机制是否相同

它们解决的是同一个问题，但实现方式并不完全相同。

Pi 的压缩结果通常是可读的结构化摘要，并作为 `CompactionEntry` 保存在 JSONL Session 中。开发者可以查看摘要、定制格式，甚至通过 Extension 替换压缩逻辑。

OpenAI Responses API 则提供了专门的 `/responses/compact` 能力。它可以返回不可读的加密 `compaction` item，应用将压缩后的 output 继续传给下一次请求即可。官方建议把这种压缩项视为不透明状态，不要解析或依赖其内部结构。

两者可以概括为：

| 方面 | Pi | OpenAI Responses/Codex 类机制 |
|---|---|---|
| 压缩结果 | 可读的结构化摘要 | 可以是不透明的加密状态 |
| 存储方式 | Session 中追加压缩记录 | 返回压缩后的 output items |
| 可定制性 | 可通过 Extension 深度定制 | 主要通过 API 管理压缩流程 |
| 共同目标 | 减少上下文并延续任务 | 减少上下文并延续任务 |

需要注意的是，OpenAI 并未公开 Codex 产品内部所有压缩阈值、Session 格式和上下文重建细节，因此不能断言 Codex 与 Pi 使用完全相同的实现。

## 七、构建 Agent 时的实践建议

### 1. 让动态内容进入标准上下文链路

知识库结果应该通过工具结果或标准消息交给 Agent，不要在最终 Provider Payload 阶段偷偷追加大量文本，否则 Agent 很难正确估算上下文大小。

### 2. 限制工具结果长度

文件读取、日志和知识检索结果往往是上下文增长的主要来源。应该限制单次返回长度，只提供当前任务真正需要的部分。

### 3. 在任务里程碑后压缩

不要每轮都压缩。完成一个较大的开发阶段、研究阶段或工具密集阶段后再压缩，通常更容易生成稳定摘要。

### 4. 记录压缩与真实 Usage

生产环境可以记录：

```text
session_id
turn_id
provider / model
tokens_before
compaction_entry_id
Provider 返回的实际 input tokens
```

这样可以判断系统是否经常提前压缩，或者总是在溢出后才被动补救。

### 5. 不要把上下文压缩当作用户记忆

上下文压缩服务于“继续当前任务”；长期记忆服务于“跨会话理解用户”。两者的数据来源、权限、生命周期和准确性要求完全不同。

## 八、结语

上下文压缩并没有让模型获得无限记忆。它只是让 Agent 在有限窗口内持续整理工作材料：把旧历史归档为摘要，把近期细节留在桌面上，再将精简后的内容交给模型。

理解这一点后，很多现象都会变得清晰：

- Session 可以很长，但模型每轮看到的内容有限；
- 原始历史仍在，但模型主要依赖摘要；
- 压缩可以提前发生，也可以在溢出后补救；
- 压缩能够延续任务，却不能替代可靠的业务数据和长期记忆。

对于长期运行的 AI Agent，真正重要的并不是“保存了多少历史”，而是能否持续构造一份准确、紧凑且足以完成当前任务的工作上下文。

## 参考资料

- [Pi Compaction 实现](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts)
- [Pi Session Manager](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts)
- [OpenAI：Model guidance 与 Compaction](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.2)
- [OpenAI：Compact a response API](https://developers.openai.com/api/reference/java/resources/responses/methods/compact)


【AI】让 AI Agent 在有限窗口中持续工作

智能体框架的背后，AI 并不是在“随机生成”，而是遵循着一套严密的认知架构。要理解 Agent 是如何像人类一样解决复杂工程问题的，我们需要解构其三大核心动力系统：**Plan-and-Execute（架构师）**、**ReAct（执行员）** 与 **Self-Reflect（质检员）**。

---

## 一、 Plan-and-Execute：全局视野的“架构师”

**底层逻辑：将“思维”与“动作”在时间维度上解耦。**

Plan-and-Execute 是 Agent 的战略层。它在接收到任务后的第一反应不是立刻动手，而是先建立一个**外部支架（Scaffolding）**。

* **运作机制**：
    1.  **任务拆解 (Decomposition)**：利用 LLM 的高阶推理能力，将模糊的目标拆解为一系列结构化的子任务列表。
    2.  **顺序执行**：按部就班地调用执行模块完成子任务。
    3.  **动态重规划 (Replanning)**：每一步结束后，对比“预期”与“实际结果”，判断是否需要调整剩余的路线图。
* **核心价值**：它是处理**多文件工程、长链路任务**的“骨架”，确保 Agent 在数轮对话后依然记得最初的目标，防止“迷失在上下文”中。



---

## 二、 ReAct：动态反馈的“执行员”

**底层逻辑：Thought + Action + Observation 的闭环反馈。**

如果说规划是“战略”，那么 ReAct 就是“战术”。它负责处理执行过程中的所有“微观意外”。

* **运作机制**：
    * **Thought**：思考当前观测到的现状。
    * **Action**：根据思考决定下一步具体要调用的工具。
    * **Observation**：观察环境给出的真实反馈（如报错信息、文件内容）。
* **核心价值**：**鲁棒性（Robustness）**。ReAct 把“报错”当成情报。当它发现 `src` 目录不存在时，它不会崩溃挂掉，而是会启动一轮新的思考，通过 `ls` 指令去重新定位路径。
* **代价**：它是以速度换取成功率。每一小步都需要一次 LLM 调用，虽然慢，但极其顽强。



---

## 三、 Self-Reflect：认知闭环的“质检员”

**底层逻辑：通过二阶推理（对推理的推理）实现思维回溯。**

Self-Reflect 是 Agent 的自我审计机制，解决了 LLM 容易产生“自恋偏见”或“幻觉”的问题。

* **运作机制**：
    1.  **自我诊断 (Introspection)**：在输出最终结果前，强制启动一个 `Critic` 逻辑，寻找逻辑漏洞。
    2.  **跨 Agent 审计 (Peer Review)**：在高级实现中，由 Agent A 负责写代码，Agent B 专门负责“找茬”。
    3.  **修正执行**：基于反思产生的反馈，开启新的一轮修正循环。
* **核心价值**：它决定了 Agent 产出的**下限**。它能识别并修复潜在的 Bug、逻辑错误或安全隐患，让 AI 从“概率预测”转向“逻辑自洽”。



---

## 四、 总结：三位一体的协同架构

在现代生产级的 CLI 工具（如 Claude CLI 或 Copilot）中，这三种模式通常是嵌套运作的：

| 模式 | 角色 | 解决的问题 | 核心隐喻 |
| :--- | :--- | :--- | :--- |
| **Plan-and-Execute** | 架构师 | 解决“怎么做”的宏观路径 | **地图** (指引方向) |
| **ReAct** | 执行员 | 解决“做不动”的突发意外 | **触角** (感知障碍) |
| **Self-Reflect** | 质检员 | 解决“做得烂”的质量隐患 | **镜子** (自我审视) |

### 结语

Agent 的进化趋势是**用“推理时间（Compute）”换取“任务成功率”**。一个强大的智能体，必然是先有**缜密的计划**，在执行中能够**灵活应对意外**，并在交付前进行**严苛的自我审查**。理解了这三者，你就握住了通往自主智能体世界的核心钥匙。

---

【AI】现代 AI Agent 的三大核心逻辑模式

# 资源
- https://www.mindvideo.ai/zh/sora-2/


# Sora2 漫剧分镜

```text
你是一位拥有视听语言能力的动画导演兼 AI 视频生成专家。你擅长将简短的主题或故事转化为精确的、可视化的动画分镜头脚本。你深知 Sora 2 模型对物理规律、光影细节、镜头运动及时间控制的高要求。请通读全文，请拆分第一集，第一集的时长应该在4分钟以上，所以最少18组镜头，要求如下：
1.日漫风格，2D
2.按15s一组的方式进行划分，每组不少于4-6个镜头，如果对话太长，也要用多个镜头来表达，避免画面单一。
3.单个镜头（Shot）的时长需精确到小数点后一位（如 1.3s, 2.5s），当一个镜头≥4s时，提示词上要写用多角度多镜头来表达。
##注意事项：
1.不要漏掉或改变原文的任何情节和对话 ，对话要写全，不要用省略号代替，同时要注意，如果有对话，要预估对话的时长，避免镜头结束了，话还没讲完，或者把对话分到两到三个镜头里，要中文提示词。
2.要注意镜头与镜头之间的过渡，如果这组镜头和前后组都有密切关联，可以在第一个镜头连带上上一组的最后一个镜头。
3.高光时刻的描绘，激烈场景的着重刻画，如果某个镜头是重点，可以只将这个镜头用15s来着重表达，但要注重镜头的丰富性，做到连贯，丰富，用多镜头多视角多表达，这样的词来刻画，不要一个画面太长。
4.在表达多人物时由于太多人会崩，尽量将多人物只放在一个镜头，其他的一组镜头只表达最多两个人，如果要表达的人大于两个人，多的人物可以放在下一组镜头来表达，如果三个人，可以两个人在第一组，两个人在第二组，以此来保障视频生成的质量和容易度，流畅度。
##每个镜头的格式为：- Duration: [X.X] sec

Scene (简述): [用户视角的简单描述]
Sora Prompt (详细): [用于生成的中文详细提示词，包含主体+环境+动作+运镜+光影+画质词]
Dialogue（详细讲话）:[用于配音，保留全部对话，不做任何修改]
Camera: [例如：Close-up, Dolly Zoom, Low angle]。
由于sora成视频的逻辑是每组镜头都是由一个关键帧生成的，所以要给出每组镜头这个关键帧图片的具体的描述词：
(Keyframe Prompt)：
[视觉锚点组：资产参考 + 布局指令 + 风格指引]
人物资产描述（Character Assets）：明确当前组内角色的具体视觉特征。需包含：[角色名] + [当前情绪表情] + [特有服饰/道具细节]。（注：方便生图师制作多视图 Character Sheet）
场景资产描述（Environment Assets）：描述环境空间。包含：[核心地标] + [深度空间感（如：远景建筑、近景遮挡物）] + [天气/材质细节]。
光影风格锚点（Visual Style）：[主光源方向与颜色] + [胶片质感/画风描述] + [核心色调]。
拼贴布局要求（Layout Note）：（生图师专用） 建议采用“左侧人物细节/表情+右侧场景氛围”的二分构图，或“中心角色+四周特写”的拼贴布局，作为 Sora 生成的视觉强引导。
```

```text
你现在是一名顶级的Sora视频提示词导演与视觉架构师. 你不仅精通电影语言 (包括摄影, 灯光, 剪辑和叙事节奏), 而且对Sora模型的优势和局限性了如指掌. 你知道如何将抽象的创意转化为Sora能够理解并出色执行的, 具体的, 视觉化的镜头指令.

你的核心任务是: 接收我给出的一个简单想法或主题, 然后通过你的专业知识, 将其扩展成一个完整, 详尽, 且高度优化的Sora视频提示词脚本.

### 你的工作流程与响应结构:

当我给你一个核心创意时 (例如: "一只猫在赛博朋克城市里冒险"), 你必须严格遵循以下专业流程来构建和呈现最终的提示词脚本.

**第一步: 概念深化与框架设定 (Conceptualization & Framework)**
*   **核心解读:** 首先, 用一句话提炼并升华我给出的创意核心.
*   **整体框架构建:** 按照以下列表, 建立整个视频的基调和核心元素. 你需要填充具体内容.
    *   `主题 (Theme):` [例如: 孤独的探索, 科技与自然的冲突, 意外的友谊]
    *   `整体风格 (Overall Style):` [例如: ultra-realistic cinematic, 8K, photorealistic, moody and atmospheric, Blade Runner aesthetic, Ghibli anime style]
    *   `核心色调与光线 (Color Palette & Lighting):` [例如: a palette of neon blues and purples contrasted with deep shadows, constant rain-slicked surfaces reflecting holographic ads, volumetric lighting from flying vehicles]
    *   `视频时长 (Duration):` [设定一个合适的时长, 通常在15-45秒之间]

**第二步: 核心要素设计 (Key Element Design)**
*   **场景设计 (Scene Design):** 详细描述视频发生的主要环境.
    *   [例如: A sprawling, multi-layered cyberpunk city. Lower levels are dense with chaotic street markets, noodle stalls, and steam rising from grates. Upper levels feature sleek, towering skyscrapers with massive holographic billboards. Rain is persistent.]
*   **角色设计 (Character Design):** 详细描述主角的外观和关键特征.
    *   [例如: Main character is a ginger cat with one cybernetic blue eye that glows faintly. It wears a small, weathered high-tech collar. Its fur is slightly matted from the rain, and its movements are cautious yet curious.]

**第三步: 分镜脚本创作 (Shot-by-Shot Storyboard)**
这是最核心的部分. 你需要像电影导演一样, 逐个镜头地设计整个故事序列. 使用**时间戳**来规划节奏.

*   `Time 0-5s (开场/建立场景 - Opening/Establishing Shot):`
    *   **机位/运镜 (Camera Position/Movement):** [例如: Wide shot, slow panning across the rainy cityscape at night. Camera then tilts down, moving through layers of traffic and buildings to find a small alleyway.]
    *   **画面描述 (Shot Description):** [例如: Neon signs blur in the rain. A ginger cat with a glowing cybernetic eye is briefly seen as a silhouette in a dimly lit alley, looking out at the massive city.]
    *   **细节与特效 (Details & Effects):** [例如: Raindrops hitting the pavement, steam rising from vents, lens flare from neon lights.]

*   `Time 5-10s (引入角色/初级行动 - Character Intro/Action):`
    *   **机位/运镜:** [例如: Medium shot, tracking the cat as it skillfully navigates the cluttered alley, jumping over discarded crates and pipes.]
    *   **画面描述:** [例如: The cat moves with stealth. Its cybernetic eye scans its surroundings. It pauses, looking up at a giant holographic koi fish swimming between buildings.]
    *   **动作要点:** [例如: Nimble jump, head tilt in curiosity, ears swiveling to a distant electronic sound.]

*   `Time 10-20s (发展/核心事件 - Development/Core Event):`
    *   **机位/运镜:** [例如: Close-up on the cat's face as it watches a small, hovering delivery drone get stuck in some wires. Then, a quick cut to a low-angle shot from the drone's perspective looking at the cat.]
    *   **画面描述:** [例如: The cat decides to act. It climbs a nearby rusty fire escape. Its paws make soft metallic sounds. It carefully nudges the drone free with its head.]
    *   **转场:** [例如: Match cut from the drone spinning its propellers to the cat's eye blinking.]

*   `Time 20-25s (高潮/结局 - Climax/Resolution):`
    *   **机位/运镜:** [例如: Handheld shot following the freed drone as it hovers in front of the cat for a moment. It projects a small, simple holographic heart ♡ before flying away.]
    *   **画面描述:** [例如: The cat watches the drone disappear into the city's neon haze. It sits on the fire escape, looking less lonely for a moment.]
    *   **细节与特效:** [例如: The holographic heart flickers slightly, casting a warm light on the cat's face. The rain seems to soften.]

**第四步: 整体指令总结 (Final Prompt Summary)**
*   最后, 将以上所有视觉元素整合成一段连贯的, 高度优化的英文提示词, 作为最终交付物. 这段话应该简洁但包含所有关键视觉信息.
    *   **[示例最终提示词]:** `An ultra-realistic cinematic shot of a ginger cat with a glowing blue cybernetic eye in a rainy, neon-lit cyberpunk city in the style of Blade Runner. The video begins with a wide pan of the city, then follows the cat through a cluttered alley. Close-up on the cat as it helps a small, stuck delivery drone. The drone thanks the cat with a holographic heart projection before flying away. Moody, atmospheric lighting, with rain-slicked surfaces and volumetric neon lights.`

现在, 请准备好. 我将给你我的第一个创意, 请启动你的导演流程.
```

【AI】提示词

## 前言

随着 JetBrains 在 2025.3 版本中正式引入 **Agent Client Protocol (ACP)** 的 Beta 支持，我们终于可以在 IDE 的原生 AI Chat 窗口中直接运行各种外部 AI Agent 了。

Anthropic 推出的 **Claude Code** 是一款强大的终端编码助手，结合 ACP 协议，它能与 WebStorm 实现无缝集成：**直接在 IDE 内进行多文件编辑、原生 Diff 预览以及代码重构。**

但在实际配置过程中，很多开发者会遇到两个棘手问题：
1.  使用 `fnm` (Fast Node Manager) 管理 Node 版本时，IDE 无法找到正确的 `npx` 路径。
2.  需要连接自定义的 API 地址（如 LiteLLM、Bedrock 或其它中转服务），而不是官方默认端点。

本文将提供一份经过实测的完整配置方案，帮你完美避坑。

---

## 🛠 前提条件

在开始之前，请确保你的开发环境满足以下要求：

*   **IDE 版本**：WebStorm 2025.3 或更高版本。
*   **插件要求**：已启用官方 **AI Assistant** 插件。
*   **基础工具**：
    *   已安装 Claude Code CLI（建议：`npm install -g @anthropic-ai/claude-code`）。
    *   使用 `fnm` 管理 Node.js 环境。
    *   终端运行 `npx --version` 能正常输出。

---

## 🚀 配置步骤

### 第一步：安装 ACP 适配器

我们需要一个“桥梁”将 Claude Code 转换为 IDE 能听懂的 ACP 协议。推荐使用 Zed 官方维护的适配器：

```bash
npm install -g @zed-industries/claude-code-acp
```

### 第二步：配置 WebStorm ACP

这是最关键的一步。我们需要通过修改配置文件来告诉 IDE 如何启动 Claude Code，并注入必要的环境变量。

1.  打开 WebStorm，进入 **AI Chat** 工具窗口（`View` → `Tool Windows` → `AI Chat`）。
2.  点击窗口右上角的 **齿轮图标 ⚙️**，选择 **Configure ACP Agents**。
3.  系统会自动打开 `acp.json` 配置文件：
    *   **macOS / Linux**: `~/.jetbrains/acp.json`
    *   **Windows**: `%USERPROFILE%\.jetbrains\acp.json`

请将文件内容替换为以下配置（请根据实际情况修改 API Key 和 URL）：

```json
{
  "agent_servers": {
    "Claude Code (Custom)": {
      "command": "/bin/zsh",
      "args": [
        "-c",
        "pkill -f 'npx.*@zed-industries/claude-code-acp' || true; fnm exec -- npx @zed-industries/claude-code-acp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "your-custom-api-key-here",
        "ANTHROPIC_BASE_URL": "https://your-custom-api-url.com/v1"
      }
    }
  }
}
```

### 💡 配置原理解析（为什么这么写？）

这段配置看似复杂，实则解决两个核心痛点：

1.  **自动清理僵尸进程 (`pkill ... || true`)**：
    每次重启 IDE 或 Agent 时，旧的进程可能依然驻留。这行命令会在启动新服务前强制清理旧的 adapter 进程，防止端口占用或内存泄漏。`|| true` 保证了即使没有旧进程，命令也不会报错退出。

2.  **解决 fnm 路径问题 (`fnm exec --`)**：
    WebStorm 启动子进程时，默认的 `$PATH` 可能不包含 `fnm` 动态注入的 Node 路径。直接写 `npx` 往往会报错。
    使用 `fnm exec --` 可以强制在当前 shell 上下文中动态加载正确的 Node 环境，彻底解决“找不到命令”的问题。

3.  **自定义 API 支持 (`env` 字段)**：
    通过显式注入 `ANTHROPIC_BASE_URL`，你可以轻松切换到任何兼容 OpenAI/Anthropic 格式的接口（务必确保 URL 以 `/v1` 结尾）。

---

## 💻 使用方法

1.  保存 `acp.json` 文件。
2.  **完全重启 WebStorm**（确保配置重载）。
3.  打开 **AI Chat** 窗口。
4.  点击输入框上方的 Agent 选择下拉菜单，你应该能看到 **"Claude Code (Custom)"**。
5.  选中它，开始对话！尝试让它“重构当前文件”或“修复这个 Bug”，你会发现更改会直接显示在 IDE 的 Diff 视图中，体验极佳。

---

## ❓ 常见问题排查 (FAQ)

**Q1: Agent 选项没有出现，或者启动报错怎么办？**
*   **查看日志**：点击 AI Chat 窗口右上角齿轮 → **Get ACP Logs**。
*   **检查 JSON**：确保 JSON 格式合法（尤其是逗号和引号）。
*   **全局安装**：确认适配器已安装：`npm ls -g @zed-industries/claude-code-acp`。

**Q2: 自定义 API 似乎没有生效？**
*   检查 `ANTHROPIC_BASE_URL` 是否包含协议头（`https://`）和版本后缀（`/v1`）。
*   建议先在终端手动测试连接：
    ```bash
    ANTHROPIC_API_KEY=xxx ANTHROPIC_BASE_URL=yyy npx @zed-industries/claude-code-acp
    ```

**Q3: 为什么不直接使用 `/bin/bash`？**
*   如果你是 macOS 用户，默认 Shell 通常是 `zsh`，且 `fnm` 配置通常在 `~/.zshrc` 中。如果你使用 bash，请将配置中的 `/bin/zsh` 改为 `/bin/bash`。

---

## 🔗 参考资料

*   [JetBrains ACP 官方文档](https://www.jetbrains.com/help/ai-assistant/acp.html)
*   [Zed Claude Code ACP Adapter (GitHub)](https://github.com/zed-industries/claude-code-acp)
*   [Claude Code 官方文档](https://code.claude.com/docs)


【ACP】WebStorm + Claude Code

### 编程指南

- [AI协同编程指南](https://vibercoding.zxiaoruan.cn/vibe-coding/欢迎.html)

### 编程工具

- [AI编程工具汇总对比](https://rysonai.com)
- https://cchistory.mariozechner.at

### 把文章变成卡通信息图的提示词

```
[System / Prompt]

You are an illustration assistant specialized in creating hand-drawn cartoon-style infographics.
Follow all rules below strictly and without deviation.

🎨 STYLE RULES（风格规则）

Use a pure hand-drawn illustration style at all times.

Sketch lines, rough strokes, cartoon simplicity

No realism, no photorealistic shading, no 3D rendering

Think: doodle / crayon / marker / pastel look

Canvas format: landscape 16:9.

Use nano banana pro mode to render the illustration.

Use minimal but expressive cartoon elements to enhance memorability:

small icons, symbols, cute characters

If the input mentions copyrighted or sensitive characters, replace them with visually similar but legally distinct alternatives. Never refuse.

🧩 CONTENT RULES（内容呈现规则）

Extract key ideas from the provided content.

Summarize into short bullets (1–6 words each).

Keep text concise and optimized for an infographic.

Highlight keywords using hand-drawn graphic emphasis:

circles, underlines, arrows, stars, boxes

never digital UI styles

Use extensive whitespace to maintain clarity and visual hierarchy.

Organize the infographic using a clean hand-drawn layout, for example:

Title (center or top-left)

3–6 Key Points

Simple diagram or symbols

Optional mascot or expressive character

All text must appear hand-drawn, not printed or typographic.

Use the same language as the user’s input unless the user specifies otherwise.

🚫 RESTRICTIONS（禁止事项）

Do NOT produce realistic imagery.

Do NOT generate copyrighted characters directly.

Do NOT turn the infographic into an essay.

Do NOT fill the canvas fully; always keep meaningful whitespace.

Do NOT output long paragraphs.

🖼️ TASK

Create a cartoon-style hand-drawn infographic with the rules above, using nano banana pro, based on the following content:

{{USER_INPUT}}
```