Visit https://aiagentskills.net/ to freely browse open-source contributions crafted by developer communities worldwide.

看了代码目前还没支持

主要功能：改写、降重、语法纠错、语气调整，支持博客、电商文案、邮件和日常写作场景。可以直接免费试用，不需要装软件，网页打开即用。

我的产品收录了一些 AI 导航站，论坛里第一次发布，欢迎大家试试并提意见。项目主页：ReWords AI https://rewordsai.app/

https://github.com/abandon1a2b/slacker-office

近期收到不少功能建议，其中部分已经完成。这里简单整理一下后续考虑推进的方向。以下内容不代表确定的开发顺序或发布时间，具体安排会根据实际情况和使用反馈调整。

基础能力与安全

• 完善账号封禁、登录日志、注册限制等功能
• 支持邀请码注册及更多人机验证方式
• 增加分类级帖子、回复审核规则
• 完善附件上传和文件管理
• 支持 SQLite 数据库备份至 S3
• 提供更友好的后台及前端数据导入、导出功能
• 完善站点条款、用户名规则等后台配置
• 正文直接 @ 通知其他用户

内容发布能力

• 文章内容密码保护
• 修改文章发布日期和时间
• 支持未来时间发布、定时发布
• 支持已发布、草稿等状态切换
• 增加版权协议、关闭回复等文章设置

社区与账号功能

• TOTP 二次验证
• 账号注销与冷静期
• 编辑历史及差异查看
• 浏览器通知
• 更多 OAuth 和社交平台支持

需要进一步设计的功能

投票、正文部分隐藏、选中内容引用、树状回复等功能都比较重要，但可能涉及正文存储结构、编辑器协议和主题展示方式的调整，需要先认真设计，不会为了赶进度仓促实现。

其中，树状回复可以先完善服务端数据能力，再由不同主题选择列表式或树状展示；默认主题不一定直接改成嵌套结构。

以上内容仅作为未来开发方向说明，不是固定的开发清单和发布时间表。会优先保证基础能力、稳定性和安全性，再逐步推进涉及底层结构的功能，也欢迎大家继续补充具体使用场景和建议。

以下是之前制作的几套主题参考原型，分别偏向传统论坛、社区门户、问答、编辑精选和作品展示。它们不代表最终实现，也不一定全部支持，主要想了解大家更喜欢哪种方向，以及实际需要哪些展示能力。

1. 敏感词检测：如果有成员在帖子里输入了敏感词包含的内容则不允许发布

2. 验证码功能：现在只有一个图形验证码，是否可以接入像Cloudflare Turnstile，Google reCAPTCHA这样的人机验证？且可以设置发帖时是否需要进行验证

3. 附件上传：可以支持一下7z，rar，zip，tar.gz这些压缩包格式，有些时候需要直接分享点文件资源但是上传不了，还得弄个网盘，怪费劲的，压缩包可以上传到S3或者本地服务器

4. 帖子审核：后台好像没有找到这个选项，可以开发一下

5. 邀请码注册：适合一些私有小论坛，开启后只有受邀用户可以注册

6. 账号封禁：被封禁的用户在用户主页显示封禁状态和封禁原因，且登录后出现相关提示（例：您的账号已被封禁，部分功能将被限制使用，如存在误封请通过xxx@example.com发送邮件申诉），同时增加可选封禁时间（有些人可能情况不严重，临时封禁几天那种）

7. 帖子功能：可以设置帖子部分内容或全部内容隐藏（登录后查看/回复后查看），以及在帖子中设置投票，并且可以关闭回复（类似于锁帖）

8. S3配置可视化：把S3的配置从配置文件移动到管理后台，更加方便和理解

9. 版权信息展示：开启后自动增加到帖子尾部，用于一些教程类/知识类帖子，比如CC BY、CC BY-SA、CC BY-NC、CC BY-NC-SA、CC BY-ND、CC BY-NC-ND（示例：本帖采用 CC BY-NC-SA 4.0 许可协议发布）

10. 搜索功能：移动端现在貌似不会展示搜索按钮，只能通过URL进搜索页面

11. 修改密码功能优化：有时候忘记了密码需要重置，但是现在重置又需要输入旧密码，就很尬，可以增加一个使用邮箱验证的方式重置密码作为备选

12. 帖子表情：增加一些emoji表情，丰富帖子内容

上面是目前体验到的不足，如果有些做不了就算了，不强求，之前用过Discourse很强，但是唯一的问题就是性能开销太大，这个论坛程序简直是低配服/卡预算站长的福音

不是因为react 抛弃vue ，而是为了更好的使用shadcn和更好的使用基于shadcn的相关生态，包括两种不同的前端驱动方式。

React + shadcn 迁移与 Next 并存架构

状态

• 决策状态：方向已确定，隔离的 React workspace 与开发入口已经初始化。
• 下一步：将当前 Vue 客户端迁移为 React，并采用 React 官方 shadcn/ui 生态。
• 长期并存能力：Next 作为可选渲染方式接入，不取代 Go SSR，也不是 React 迁移的下一阶段或完成条件。
• 历史基线：docs/shadcn-vue-site-migration.md 记录了当前 shadcn-vue/Reka UI 基础层的迁移结果；该实现继续作为迁移前的行为与视觉基线。

背景

GooseForum 当前由 Go 提供页面 payload、HTML 模板、SEO/no-js 内容与业务 API，浏览器端由 Vue 3 应用接管主站和管理后台。基础 UI 已统一到 shadcn-vue 与 Reka UI，但 Vue 侧的 shadcn 生态在官方组件、registry、示例、第三方模板和工具支持方面弱于 React 侧。

迁移的直接目标是使用 React 官方 shadcn/ui 生态，同时保留现有 Go 页面渲染体系。Next 的目标不同：它是与 Go SSR 并存的另一种可选渲染方式，未来可由 GooseForum 主进程按配置启动并承接指定页面路由。

核心决策

1. React + shadcn 是当前前端演进方向。
2. Go 继续拥有业务逻辑、认证授权、数据库访问、API、文件服务和现有 SSR/payload 能力。
3. React 业务组件不得直接依赖 Next；通过小型运行时适配层接入不同宿主。
4. Go SSR 是长期受支持的运行方式，不视为等待 Next 替换的临时实现。
5. Next 是可选并存能力。未启用 Next 时，程序必须能够只依赖 Go 正常运行。
6. Next 不成为 React 迁移的验收条件；React 版本完成后即可独立交付。
7. 不在 Next 中复制 Go 业务逻辑。Next 只负责页面渲染、路由集成和必要的数据编排。

目标结构

resource/
├── packages/
│   ├── client/             现有框架无关 payload、API 与浏览器协议
│   └── react/              React 业务组件、hooks、shadcn/ui 与宿主适配接口
├── apps/
│   ├── react/              C 端与后台双入口的 Vite 开发应用和 Go payload 适配
│   └── next/               可选 Next App Router 适配与服务端入口
├── templates/              长期保留的 Go HTML/SEO/no-js 模板
└── static/                 Go 模式使用的浏览器端构建产物

具体目录可以在实现阶段根据 pnpm workspace 调整，但依赖方向必须保持：

@gooseforum/client
        ↑
@gooseforum/react
    ↑          ↑
Go 客户端适配   Next 适配

@gooseforum/react 不能反向导入 Next 应用代码。

React 运行时适配层

适配层只解决宿主差异，不抽象论坛业务。候选边界包括：

• 页面 payload 的初始读取和后续获取。
• 链接渲染与客户端导航。
• 当前路径、查询参数和滚动恢复。
• locale、主题和页面元数据的宿主接入。
• 服务端与浏览器环境差异。

页面数据结构、权限判断结果和 API 请求继续使用 @gooseforum/client。主题 token 和现有视觉规范继续作为迁移基线。

避免为了同时支持两个宿主而构造庞大的通用运行时。普通组件应优先接收数据与回调；只有确实依赖路由或宿主环境的能力才进入适配接口。

React + shadcn 迁移原则

1. 使用 React 官方 shadcn/ui 组件源码和官方支持的 primitives。
2. 不逐文件翻译当前 resource/src/components/ui。根据真实调用重新生成组件，再迁移 GooseForum 的主题、variant 和产品行为。
3. 迁移目标是完整保留功能和设计意图，不是逐像素、逐 DOM 或逐行代码复刻。旧实现是重要参考，但不默认代表最优实现。
4. 开发每个页面或功能前，先通过旧版源码理解其功能、排版、响应式行为、交互流程、状态变化及异常分支，整理清楚功能契约和设计目的，再用符合 React 生态的方式实现。默认不要求运行旧版逐页比对。
5. 在功能完整、信息层级和整体体验一致的前提下，允许优化间距、层级、反馈、组件组合和实现细节。与旧版产生的差异应当是有理由、可验证的正向差异，不能以“优化”为由遗漏具体功能。
6. Vue 和 React 即使都使用 shadcn，也存在生命周期、缓存、路由、状态管理和组件行为上的差异。只有效果明确、替换后稳定性很高的部分可以直接迁移。
7. 遇到行为等价性不明确、可能改变用户体验或存在多种合理方案的部分，必须在实现前与维护者讨论并确认，不能自行选一种近似实现。典型例子包括 Vue KeepAlive 的页面状态保留语义，以及详情页时间轴的结构、滚动和交互行为。
8. 保持现有页面信息架构、内容密度、键盘行为、焦点管理和移动端体验；任何有意改变都应在对应功能的迁移记录中明确说明。
9. 复用框架无关代码，包括 @gooseforum/client、API、Markdown、ProseMirror、图片处理、格式化和 payload 类型。
10. 实现方式和依赖选择应符合当前 React 主流实践，优先采用官方、稳定、广泛验证且与项目边界匹配的方案，不为机械对应 Vue 结构而引入非惯用写法。
11. React 业务组件不导入 next/link、next/navigation、Server Actions 或 Next 缓存 API。
12. Next 专属的 Server Component 边界、metadata 和路由文件只存在于 Next 适配应用。
13. React 版本采用旁路集中开发：现有 Vue 版本在整个开发与验证期间保持可运行且不感知 React 改造。先完成新的 React 版本并进行整体测试，确认无误后再统一切换；迁移阶段不讨论或执行逐页替换、逐步删除旧实现。

开发与审查方式

1. 首先阅读旧版源码和相关 payload、API、样式与测试，通过代码理解功能和设计意图。
2. 列出必须保留的功能、数据、权限、交互状态、响应式行为、无障碍行为和异常处理。
3. 如果旧版代码较复杂，且仅靠代码无法可靠判断视觉层级、真实布局或交互效果，再请维护者提供对应页面和状态的截图，不默认要求先运行旧版。
4. 标记 Vue 与 React 无法直接等价的部分；凡是不容易判断且不能确认稳定替换的，先讨论再实现。
5. 基于 shadcn/ui 和主流 React 模式设计实现，不受旧组件拆分方式约束。
6. 对照功能清单验证新实现，同时检查允许的视觉和交互优化没有造成能力退化。
7. 记录有意保留的差异和仍待确认的问题，供 React 版本整体测试和最终切换前统一审查。

组件位置与依赖方向

• shadcn/ui 只作为基础组件层，不是页面和业务组件的替代品。不能因为已有 shadcn primitives，就在每个页面中重复堆叠一整套相同的结构、交互和状态处理。
• shadcn/ui primitives 放在 resource/packages/react/src/components/ui/，保持通用、无业务语义；通用 variant 和视觉基础可以留在这一层，论坛业务规则不得下沉到 primitives。
• 具有稳定产品语义或重复交互模式的组合应封装为 GooseForum 业务组件，例如用户摘要、主题列表项、页面标题区、管理表格操作区和内容状态反馈。页面负责组织业务流程，不重复拼装这些细节。
• 组件封装以清晰职责、稳定语义和实际复用为依据。既避免所有内容都直接“一把梭”式使用 shadcn，也避免只为减少几行 JSX 而制造过度抽象。
• 可同时被 Vite 和未来 Next 使用的论坛业务组件、hooks 与宿主接口放在 resource/packages/react/，不得依赖具体应用入口。
• 仅属于 C 端或后台 SPA 的布局、路由组合和页面组件分别放在 resource/apps/react/src/site/ 与 resource/apps/react/src/admin/。
• 仅被单个页面使用的组件优先与页面就近放置；出现清晰、稳定的跨页面复用后再提升到共享层，不提前制造抽象。
• payload、API、路由和主题等宿主差异通过明确的适配层接入，展示组件优先接收数据和回调，不直接读取全局环境。
• 引入新库前确认其维护状态、社区采用度、React 19 兼容性、无障碍表现和是否真的优于现有依赖，避免同一能力长期并存多套实现。

实施顺序

阶段一：React 基础设施

• 建立 React workspace、TypeScript 和构建入口。
• 使用同一 Vite 应用的两个 HTML 入口：根 index.html 对应 C 端，admin/index.html 对应管理后台；两套源码分别位于 src/site/ 和 src/admin/。
• 管理后台保持纯 SPA 模型；开发环境中的 /admin 与 /admin/* 始终回退到后台 HTML，admin.shell 仅提供启动所需的用户、权限和主题数据。
• 未检测到 Go 注入 payload 时，通过 Vite 代理读取真实 Go 页面 payload。
• React 开发构建产物保留在新 app 自己的 dist/，不进入现有 resource/static/ 或 Go embed.FS。
• 初始化官方 shadcn/ui，映射现有主题 token；管理后台 shell 以官方 dashboard-01 block 为起点，C 端按 GooseForum 的信息架构自行设计。
• 建立 Go payload、导航、i18n、主题和 flash message 的 React 适配。
• 保持现有 Go 模板与 X-Goose-Page 协议。
• 为核心交互增加浏览器级回归测试。

阶段二：集中开发 React 版本

以下顺序只用于组织开发精力，不代表逐页上线、逐页替换或逐步删除 Vue：

1. 登录、重置密码、目录和静态信息页面。
2. 管理后台 CRUD 页面。
3. 首页、分类、搜索和用户页。
4. 设置、通知、消息、审核和发布。
5. Topic、PostComposer、编辑器、滚动窗口和内容增强。
6. AppShell、共享状态和全局交互收尾。

该阶段始终保持旧运行环境不变。完整 React 版本完成并通过功能、交互、视觉和回归测试后，再单独执行整体切换。Go SSR + React 届时即为独立、完整的目标运行方式，无需等待 Next；旧实现的清理不属于当前迁移开发阶段。

独立工作流：Next 并存能力

Next 接入建立在可复用的 React 组件和适配边界之上，但属于独立能力，不是上述迁移的后续替换阶段。

预期运行拓扑：

浏览器
  └── Go 公共监听端口
      ├── /api/*、/file/*、/oauth2/*、SEO 资源  → Go
      ├── Go 渲染路由                         → Go SSR + React
      └── 配置给 Next 的页面与 /_next/*       → Next 子进程

约束如下：

• Go 是主进程和统一公开入口。
• Next 仅监听 loopback 地址。
• Go 根据明确配置启动 Next，并通过反向代理路由请求。
• Next 服务端携带原始 Cookie 向 Go 获取 payload；Go 始终是认证和权限事实来源。
• 必须设计内部回源标识或内部 page-data endpoint，避免 Next 请求再次被代理回 Next。
• 初期按固定配置或路由白名单选择渲染器，不做随机灰度。
• Next 不可用时采用“启动失败”还是“降级到 Go SSR”，必须由配置明确决定，不能静默切换。

Next 构建与 embed 边界

Next SSR 是需要 Node 运行时的服务，不能像普通 Vite 静态资源一样直接从 Go embed.FS 执行。

预期方案是：

1. 构建 Next standalone 产物。
2. 将 standalone、.next/static 和 public 作为发布产物；如要求单 Go 文件携带，可将其嵌入 Go 二进制。
3. 启动时把嵌入产物释放到临时目录。
4. Go 通过 exec 启动 Next 服务，并管理健康检查、退出和清理。
5. Node 运行时采用宿主依赖、发布包 sidecar 或平台专属嵌入方案，另行决策。

“Next 产物可被 Go 携带”与“Next 不需要独立运行时”是两件事。是否把 Node 可执行文件也嵌入最终二进制，需要结合发布体积、平台矩阵、签名和安全更新成本单独评估。

配置方向

最终配置名称在实现时确定，语义至少应覆盖：

[frontend]
renderer = "go"

[frontend.next]
enabled = false
command = "node"
host = "127.0.0.1"
startupTimeout = "15s"
failurePolicy = "fail-startup"
routes = []

其中：

• renderer = "go" 表示使用长期支持的 Go SSR + React 路径。
• 启用 Next 不代表关闭或删除 Go SSR。
• routes 允许稳定地把部分页面交给 Next；空列表的具体含义必须在实现时定义清楚。
• failurePolicy 必须显式配置是否允许回退。

非目标

• 不以 React 迁移为契机重写 Go 业务服务。
• 不要求把所有数据修改改造成 Next Server Actions。
• 不把 Next 作为 GooseForum 的唯一部署方式。
• 不在 React 迁移阶段实现 Next 进程管理和代理。
• 不承诺首版就把 Node 运行时嵌入单个 Go 二进制。
• 不同时长期维护两套 React 业务组件。

验收标准

React + shadcn

• Go SSR、SEO/no-js 模板与现有 URL 行为保持有效。
• 主站和管理后台达到当前 Vue 版本的功能与无障碍基线。
• 明亮、暗色和自定义主题表现一致。
• 页面导航、返回滚动、登录态、编辑器和上传流程通过回归测试。
• React 开发和验证期间不改变旧 Vue 运行路径；最终切换作为独立步骤执行。
• Next 未实现或未启用时不影响 React 版本交付。

Next 并存能力

• 配置关闭时不启动 Node/Next，Go 模式独立工作。
• 配置开启时由 Go 启动、检查和停止 Next 子进程。
• /api、文件、OAuth/OIDC 和认证仍由 Go 处理。
• Cookie、状态码、重定向、流式响应和代理头行为正确。
• Next 故障策略符合配置，且不会形成代理循环。
• 同一业务组件不因 Next 接入产生第二份实现。

待后续决策

• Next 路由按全局模式、固定白名单还是更细粒度规则切换。
• Node 由宿主提供、作为 sidecar 发布，还是按平台嵌入。
• Next 启动失败时的默认策略。
• Next 内部回源使用独立 loopback endpoint 还是受保护的内部请求头。
• Next 缓存、个性化 payload 和多实例部署策略。

这个路线是我经过对比，以及查询相关作品得出的一个上限较高的即使路线，可以极大的提高GooseForum的体验上限未来会在这个基础上渐进的实现。 shadcn 无论是能力是使用范围上 要比 Naive UI 这种重 base 框架有着更广的应用空间。 在 https://www.shadcn.io/template 有着丰富的面向c端的模板例子，足以撑起一个年轻现代化的论坛项目。具体流程如下。

GFUI
  ↓
shadcn-vue
  ↓
稳定
  ↓
React + shadcn
  ↓
内置多主题
  ↓
可选 Next Runtime

1. GFUI → shadcn-vue

必要性：

• 减少基础 UI 自研成本。

• 避免 Naive UI 这类完整 UI Framework 的运行时负担。

• 保留 Vue 当前优势。

• 提前统一组件语义和 Design Token，为 React 迁移做准备。

原则：

shadcn 负责基础 UI，论坛业务组件继续自己维护。

2. 稳定后迁移 React + shadcn

必要性：

• shadcn React 生态、组件、模板、动效明显更丰富。

• Payload 等周边对 React 支持更深。

• 迁移时可继续保留 Tailwind、Design Token、ProseMirror、Markdown、API Client 和纯 TS 逻辑。

3. React 稳定后支持内置多主题

默认提供约 3 套真正不同的 C 端主题，而不只是多配色。

主题可以改变：

布局
信息密度
圆角
边框
Typography
组件表现

Admin 不受 C 端主题控制。

4. 支持两种前端运行模式

GooseForum React Core
       │
   ┌───┴───┐
   │       │
Static    Next
默认       可选

Static：

Go + embedded React/Vite dist

Next：

Go
→ 检测 Node
→ 启动 Next
→ Reverse Proxy

5. Next 保持薄

React 是产品层，Next 只是运行时宿主。

Next 只负责 SSR、SEO、Metadata 等增强能力，业务组件不绑定 Next。

6. 支持运行时切换

Static
  ↓
启动 Next
  ↓
健康检查
  ↓
切流
  ↓
Next

Next 异常时可降级回 Static。

最终目标：

默认模式足够轻，高级模式有更高上限，同时尽量避免框架绑定。

是一个托盘程序，最初版本是我完全手撸的，这个新版本是我上周收集了老的功能然后完全ai重构的。公司的和我家里的电脑都装了，就是方便维护一些常驻程序和定时程序。

是应用软件，托盘维护的。

maichongbo.com 脉冲波AI工具合集

收集了全网最全AI工具 和分好类

并且每周保持更新 公益项目

如果遇到访问不了的情况请联系我

绝不死链! 公益项目

github.com/traefik/yaegi/interp  
go install github.com/codesenberg/bombardier@latest
go install github.com/cosmtrek/air@latest
go install github.com/goreleaser/goreleaser@latest

  yh:download    Download YH video by film ID
  yh:films       List YH films
  yh:get         YH website crawler
  yh:save        Save YH video to file
  yh:videos      List YH film videos

（alpha 能100多也是没谁了）

接下来看bate的表演

are u kidding me??

背景是有人和我说sub2api 可能不被codex 支持了，另外就是 CLIProxyAPI 被官方支持，但是 CLIProxyAPI 基本上可以认为是一个服务端的 ccswitch，如果只是 CLIProxyAPI 还不足以公司内部分配使用/监控。

这次尝试并不是为了主动替换 Sub2API。

起因是一个更直接的问题：如果有一天 Sub2API 因为版本、维护、部署环境或其他原因无法继续使用，现有的模型账号和内部用户是否还有一条可以较快恢复的服务链路？

基于这个问题，我们在沙箱中搭建并验证了一个组合方案：

New API + CLIProxyAPI

它的目标不是复刻 Sub2API 的全部实现，而是在原系统不可用时，先恢复几个最基本的能力：

• 给内部用户提供统一 API 地址。
• 为不同使用者签发独立 API Key。
• 接入现有模型账号。
• 提供基础模型权限、额度和调用日志。
• 保留后续迁移或回切的空间。

本文记录这套备用链路的结构、已验证范围和仍然存在的缺口。

备用链路结构

Codex / OpenAI SDK / 内部应用
              |
              | New API Key
              v
       New API（对外网关）
       - 用户与 API Key
       - 模型和分组权限
       - 额度与调用日志
       - 渠道路由
              |
              | 内部专用 Key
              v
    CLIProxyAPI（上游适配）
       - OAuth 认证文件
       - 多账号选择
       - 账号状态维护
       - 协议转换
              |
              v
        官方模型服务

部署环境需要统一出口时，再增加一层本机代理：

CLIProxyAPI -> Hushsocks -> 上游服务

普通使用者只接触 New API。CLIProxyAPI、认证目录和 Hushsocks 都只监听本机地址，不直接暴露给下游用户。

为什么需要两个项目

单独使用其中任何一个项目，都不能直接覆盖我们需要的最小范围。

New API 有用户、API Key、分组、额度和日志，但它并不擅长完成订阅账号的首次登录和账号池维护。

CLIProxyAPI 可以管理 Codex 等账号并提供兼容接口，但它的多个入口 Key 更接近多个访问凭据，不是完整的多用户、额度和运营体系。

因此在备用方案中，两者分别承担一部分工作：

New API：面向内部使用者
CLIProxyAPI：面向上游模型账号

这只是为了补齐应急链路，不代表这种拆分一定优于 Sub2API 的一体化实现。

应急覆盖范围

备用链路能够先恢复日常调用，但不能直接声明为完整替代。特别是计费口径、协议细节、错误处理和运营流程，需要单独核对。

存储方式

New API 和 CLIProxyAPI 的存储方式不同。

New API 的用户、渠道、Key、额度和日志存放在数据库。沙箱使用 PostgreSQL，并在现有数据库中创建独立 schema：

PostgreSQL database
├── public    -> Sub2API
└── new_api   -> New API

New API 的连接固定为：

search_path=new_api

没有配置 new_api,public 的回退路径，避免 New API 在迁移期间命中 public 中的同名表。实际验证中，New API 的表全部创建在 new_api，Sub2API 的 public 表没有发生变化。

CLIProxyAPI 主要使用文件：

config.yaml       服务配置和内部 Key
auth/*.json       OAuth 认证凭据
plugins/          可选插件
logs/             可选日志

这意味着认证目录必须放在持久化磁盘，并纳入权限控制和备份。它不像数据库那样方便做集中查询和变更审计，是备用方案中需要接受的运维成本。

单机沙箱部署

目前的目标规模是单企业、100 人以内团队，先用单机验证恢复链路是否成立。

沙箱中的服务布局为：

New API       0.0.0.0:3000
Sub2API       0.0.0.0:8080
CLIProxyAPI   127.0.0.1:8317
Hushsocks     127.0.0.1:1080
Prompt Guard  127.0.0.1:8000

目录结构如下：

/opt/sub2apideployhome/
├── app4yun/
├── sub2api/
├── newapi/
├── cliproxyapi/
│   ├── config.yaml
│   └── auth/
├── hushsocks/
├── prompt_guard_stub
└── sub2api.start.sh

统一启动脚本按顺序启动并探活各个服务。任一关键进程退出时，启动脚本结束整组进程，由云平台重新拉起。

这种方式便于沙箱部署，但也意味着单个新增服务启动失败时，其他进程会一起退出。它适合作为当前验证方式，不应直接视为最终高可用设计。

搭建中遇到的问题

1. Linux amd64 不等于一定兼容

首次使用的 New API 官方 Linux amd64 二进制是动态链接版本，要求较新的 glibc：

GLIBC_2.32
GLIBC_2.34

沙箱系统只有 glibc 2.28，因此二进制在启动前就无法加载。由于统一启动脚本会结束整组进程，最终表现为所有服务都没有运行。

处理方式是基于同一版本源码重新构建静态二进制：

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build

重新打包后确认：

ELF 64-bit x86-64
statically linked

这次问题说明，应急包不能只检查文件名中的 linux_amd64，还要检查：

file binary
ldd binary

2. New API 模型需要配置渠道和价格策略

New API 创建渠道后，不能只填写上游地址和 Key。还需要同步实际模型列表，并选择合适的价格或自用模式，否则测试请求可能在到达上游前被 New API 拒绝。

沙箱采用自用模式，只用于验证内部链路，不代表正式计费配置已经完成。

3. CLIProxyAPI 的认证目录需要单独维护

CLIProxyAPI 的账号信息保存在文件中。账号导入、备份、权限和迁移都需要明确操作流程。对少量管理员维护的单机环境尚可接受，但如果后续发展为多节点，需要重新评估存储和同步方式。

当前已验证内容

沙箱中已经完成以下检查：

• New API PostgreSQL schema 初始化。
• New API 连续启动迁移。
• New API 与 Sub2API 表空间隔离。
• CLIProxyAPI 读取认证文件。
• New API 通过内部 Key 访问 CLIProxyAPI。
• New API /v1/models 返回模型列表。
• New API 和 Sub2API 页面探活。
• Hushsocks 建立上游连接。
• Linux 静态二进制在旧 glibc 环境下的兼容修复。
• 整体部署包的 SHA-256 和文件权限检查。

尚未完成或需要扩大验证的内容：

• 长时间并发稳定性。
• 所有模型和协议的逐项测试。
• 流式响应、工具调用和图片接口的完整回归。
• 与 Sub2API 一致的计费结果对比。
• 多用户额度和限流边界测试。
• 日志清理、数据库备份和恢复演练。
• 单服务故障时的独立恢复能力。

什么时候启用备用链路

这套组合更适合作为预案，而不是在当前系统正常时立即切换。

建议触发条件包括：

• Sub2API 无法在目标环境启动，短期内无法修复。
• Sub2API 发布包或依赖不可获得。
• 升级后核心接口出现阻断性问题，需要临时回避。
• 需要在修复主系统期间维持内部模型调用。

启用时可以分三步进行：

1. 先由少量体验用户验证模型列表和基础请求。
2. 再逐步签发 New API Key，观察错误率和日志。
3. 主系统恢复后，根据实际情况选择回切或继续并行评估。

结论

New API + CLIProxyAPI 是一次面向故障场景的可行性验证。

它证明了当 Sub2API 暂时不可用时，可以通过两个现有项目重新拼出一条基本可用的内部 API 链路。但这套组合增加了服务数量，也带来了认证文件、跨服务日志、兼容性和故障联动等新的运维问题。

因此当前更准确的定位是：

一套已经跑通基础链路的 Sub2API 应急备选方案。

它是否值得长期保留，需要等并发、协议、计费和恢复演练完成后再决定。现在的价值主要是降低单一实现不可用时完全中断服务的风险。

人话

我觉得我需要一个类似向量服务的功能维护我多个项目的一些codex上下文，docs以及其他方面，要求要比文本好。正好我也在用meilisearch 我就这么搞了一个。并且类似以半钩子的形式自由的让各个项目自己写收集方式，定义好协议，然后统一收集，并用于后续检索。（不是代码索引）

机话

和编码 Agent 协作久了，一个常见问题是：它并不知道之前发生过什么。

为什么这样改？上次排查得出了什么结论？哪个判断后来被推翻了？很多工作明明做过，却不得不重新翻代码、日志和对话。

ohyeah 是一个面向编码 Agent 的本地工作记忆与证据检索服务。它从 Codex 对话、项目文档、需求分析和工具输出中采集历史记录，保存结论、决策、纠错、证据与未完成事项，并让每条结果都能回到原始来源。

它不试图成为新的事实源。历史记忆用于帮助定位，时效性信息仍需回到代码、Git、数据库或日志中复核。

运行一个命令：

ohyeah serve

即可启动后台同步、文件监听、搜索 API 和嵌入式 Web 管理界面。你可以直接搜索历史工作、阅读完整上下文、查看同步状态、调整配置和重建索引。

ohyeah 想解决的事情很简单：少做重复调查，让 Agent 从团队和个人已经完成的工作继续向前。

其实就是一个 tmux 实时的监控面板，tmux的会话保持比较好，可以让ai操作的时候同步进行监控查看。

今日份的随便研究研究如下，随便尝试一下godot，看到8方图后，我觉得怎么说呢，2d的一些贴图感觉资源不比3d的少准备的素材还挺多的，每个角度各一张。当然啦，感觉今天token有点少，所以就让codex帮我找一个精灵图搞一个角色展示看看。

虽然可以快速出东西，但是一些高级的复杂的，没有知识体系的话，无法更好的指引ai。

日期：2026-08-25
项目：Platformer → Room Transitions → Isometric
目标读者：已经有后端或 Web 开发经验，正在借助 AI 系统学习 Godot，希望能够理解节点职责、空间转换、场景生命周期和素材工程，而不只是看到 Demo 能运行的人。

1. 今天真正练习的不是三个地图

表面上，今天完成了横版平台、俯视房间切换和 Isometric 地图。真正贯穿三者的主题是：

一个游戏世界怎样定义空间、约束运动、管理内容生命周期，并把同一份状态投影成不同画面。

三个项目各自负责一个层次：

能力递进可以概括为：

flowchart LR
    A[连续物理运动] --> B[世界碰撞与平台规则]
    B --> C[场景内容的装载与卸载]
    C --> D[跨场景状态所有权]
    D --> E[逻辑网格与屏幕投影]
    E --> F[高度、遮挡与寻路]
    F --> G[同一模型的多种表现层]

昨天建立了 Node、Scene、Signal、Resource、状态机和数据驱动的基础；今天进一步回答了三个更接近真实游戏工程的问题：

1. 角色为什么能以某种“手感”运动，而不只是修改位置？
2. 一个房间销毁后，什么应该消失，什么必须继续存在？
3. 当逻辑世界不是屏幕上的正方形网格时，怎样保持数据、导航和画面一致？

2. 先建立今天的总心智模型：世界不是一张图片

今天反复出现四个彼此不同的层次：

Model / Rule
    角色参数、逻辑格、阻挡、房间 ID、Flag
            ↓
World Structure
    Node Tree、TileMapLayer、RoomRoot、Objects
            ↓
Simulation
    Physics、AStar、输入、Signal、生命周期
            ↓
Presentation
    Sprite、Animation、Camera、HUD、SubViewport

它们不能因为最终都出现在屏幕上，就混成同一件事。

例如 Isometric 高地同时涉及：

• Vector3i(x, y, z)：逻辑表面。
• AStar3D：哪些表面可以互相到达。
• HighGround: TileMapLayer：高地的地砖表现。
• -z × 33px：投影后的视觉高度。
• z_index = z × 10：覆盖普通 Y Sort 的绘制优先级。

只把 Sprite 向上挪 33 像素，不会自动创建一个可寻路的高地；只给导航点增加 z=1，屏幕画面也不会自动抬升。逻辑和表现必须显式连接。

3. Platformer：实时运动是每个物理帧的一次求解

Platformer 最终画面。左侧是角色和 TileMap 地形，右侧遥测面板实时显示运动状态、速度、地面法线、碰撞对象和跳跃容错计时。

3.1 为什么使用 CharacterBody2D

Player 的根节点是 CharacterBody2D。它适合“由代码决定移动意图、由物理世界修正最终结果”的角色。

基本流程是：

读取输入
→ 计算期望 velocity
→ move_and_slide()
→ Godot 检测碰撞并修正位移
→ is_on_floor() / get_floor_normal() / SlideCollision
→ 下一物理帧继续计算

这里的 velocity 不是“这一帧一定移动到哪里”，而是角色希望采用的速度。move_and_slide() 才会结合 TileMap、平台和斜坡碰撞，决定实际位移。

这与直接写：

position += velocity * delta

完全不同。后者绕过 CharacterBody2D 的滑动、地面判断和碰撞响应，可能直接穿过墙体。

3.2 用跳高和时间推导重力

MovementProfile 没有让人同时手调“跳跃初速度、上升重力、跳高”三个互相牵制的数字，而是暴露更符合设计意图的字段：

jump_height = 120px
time_to_jump_apex = 0.34s
time_from_apex = 0.28s

然后由运动公式计算：

跳跃初速度 v = -(2h / t_up)
上升重力 g_up = 2h / t_up²
下落重力 g_down = 2h / t_down²

GDScript 对应：

func jump_velocity() -> float:
    return -(2.0 * jump_height) / time_to_jump_apex

func rising_gravity() -> float:
    return (2.0 * jump_height) / pow(time_to_jump_apex, 2)

Godot 的 Y 轴向下为正，因此向上跳跃的初速度是负数。

上下使用不同重力，意味着角色可以慢一些上升、快一些落下。这不是物理模拟必须如此，而是平台游戏手感的设计选择。

3.3 一次物理帧的顺序

Player 的 _physics_process() 顺序不是随意排列的：

记录移动前是否在地面
→ 读取输入
→ 更新 Coyote / Buffer 计时
→ 尝试起跳
→ 处理提前松键
→ 应用分段重力
→ 应用水平加减速
→ move_and_slide()
→ 读取本帧碰撞结果
→ 更新朝向与动画
→ 判断是否刚刚落地

需要注意一个时间关系：

• is_on_floor() 在调用 move_and_slide() 前，描述上一物理步得到的接触状态。
• move_and_slide() 完成后，再读取 is_on_floor()，才能知道本帧是否刚刚落地。

所以代码先保存：

var was_on_floor := is_on_floor()

移动后再比较：

if not was_on_floor and is_on_floor():
    landed.emit(speed_before_move)

3.4 Coyote Time、Jump Buffer 与 Jump Cut

这三项都是输入意图和严格物理条件之间的缓冲。

Coyote Time

角色刚离开平台边缘后，保留约 0.12s 的起跳资格：

上一刻在地面
→ coyote_time_left = 0.12
→ 离地后逐帧递减
→ 计时未归零时仍可起跳

Jump Buffer

玩家在落地前约 0.12s 按下跳跃，输入不会丢失：

按下 Space
→ jump_buffer_left = 0.12
→ 稍后获得地面资格
→ 自动消费缓冲并起跳

Jump Cut

角色仍在上升时提前松开 Space：

velocity.y *= jump_cut_multiplier

负的上升速度绝对值被缩小，于是更早到达顶点，形成长按高跳、轻按低跳。

起跳条件因此不再只是 is_on_floor() and just_pressed，而是：

jump_buffer_left > 0
AND
coyote_time_left > 0

3.5 CharacterBody2D、AnimatableBody2D 与 Area2D

Platformer 把三种容易混淆的节点放在了同一关卡：

Checkpoint 只表示“玩家进入过这个区域”，所以它使用 Area2D。真正的新出生点由常驻 World 保存：

Player 进入 Checkpoint Area
→ World.activate_checkpoint()
→ active_spawn_position 更新
→ Player 跌出 death_y
→ World 把 Player 放回 active_spawn_position

Player 不应该自己知道关卡里有几个检查点，也不应该决定世界的重生规则。

3.6 TileMapLayer 为什么同时负责画面和地形碰撞

地面、普通平台和斜坡属于大量重复的静态世界数据。它们使用带 Physics Layer 的 TileSet：

TileSet Atlas
├── 视觉区域
├── 碰撞多边形
└── Custom Data: surface_type
        ↓
TileMapLayer
├── 画出地形
├── 提供权威碰撞
└── 允许 Player 查询脚下语义

而移动木板、踩落木板有独立状态和行为，因此保留为 PlatformActor Scene。

判断标准不是“它们看起来都是平台”，而是：

这是大量静态世界数据，还是一个具有生命周期和行为的 Gameplay Object？

3.7 地面法线和斜坡

get_floor_normal() 返回的是接触面的法线。

平地大致是：

(0, -1)

斜坡法线会同时包含 X 和 Y 分量。CharacterBody2D 根据 up_direction 和接触夹角判断一块表面是否属于地面。

这说明斜坡不是贴图造成的视觉倾斜；TileSet Physics Layer 中实际存在不同形状的碰撞多边形。

3.8 AnimatedSprite2D 的职责

角色动画使用：

Player
└── Visuals
    └── Sprite: AnimatedSprite2D
            ↓
       SpriteFrames Resource
       idle / run / rising / apex / falling

Player 脚本只选择动画名：

sprite.play(&"run")

帧顺序、FPS 和是否循环属于 SpriteFrames Resource，不应该由 _process() 手动计时切帧。

4. Room Transitions：场景切换本质是节点子树的生命周期管理

Room Transitions 刻意保留诊断型表现：HUD、Player 与对话系统常驻，房间地面、NPC 和右侧出口属于当前可卸载 Room。

4.1 为什么没有直接调用 change_scene_to_file()

如果每扇门都直接切换整个主场景：

Door
→ change_scene_to_file(next_room)
→ 当前根场景整体销毁

那么 Player、HUD、对话框和运行时状态也会跟着销毁。之后必须重新创建，并额外恢复所有状态。

当前项目采用常驻 Game：

Game（常驻）
├── RoomRoot
│   └── CurrentRoom（可替换）
├── Player（常驻）
└── Interface（常驻）

切换房间真正执行的是：

从 RoomRoot 移除旧房间
→ 实例化新房间
→ 加入 RoomRoot
→ 移动同一个 Player 实例

这让“内容场景的生命周期”和“游戏会话的生命周期”分开。

4.2 PackedScene 和运行时实例不是同一个对象

房间表保存的是：

Dictionary[StringName, PackedScene]

PackedScene 是可以重复实例化的场景模板。调用：

var next_room := packed_room.instantiate()

才得到运行时 Node Tree。

可以类比为：

PackedScene ≈ 类定义 / 组件模板
instantiate() ≈ new / 创建组件实例
add_child() ≈ 挂载到运行时树
queue_free() ≈ 延迟销毁实例

4.3 room_id + entry_id 是稳定地址

出口没有保存另一个房间中的绝对坐标，而是声明：

target_room_id = "ruins"
target_entry_id = "from_forest"

目标房间内部维护：

Entries
├── default: Marker2D
├── from_forest: Marker2D
└── from_north_gate: Marker2D

因此门知道“去哪里”，但目标房间自己决定入口的真实坐标。

这比把 Vector2(742, 318) 写进出口更稳定：房间布局变化时只需移动 Marker2D，不必修改所有引用它的门、存档和任务。

4.4 房间替换为什么要先验证后提交

错误流程：

销毁当前房间
→ 尝试加载目标
→ 才发现 room_id 或 entry_id 无效
→ 游戏只剩空 RoomRoot

当前流程：

查找 PackedScene
→ instantiate()
→ 验证类型
→ 验证 Entry 是否存在
→ 全部通过
→ 才 mount_room()

这和数据库事务、Tetris 的“候选—验证—提交”是同一种工程思想：

先证明新状态可以成立，再破坏旧状态。

4.5 一次房间切换的完整事件流

sequenceDiagram
    participant P as Player
    participant E as RoomExit / Area2D
    participant R as TransitionRoom
    participant G as Game
    participant S as GameSession

    P->>E: body_entered
    E->>R: transition_requested(room_id, entry_id)
    R->>G: exit_requested(room_id, entry_id)
    G->>G: instantiate_valid_room()
    G->>P: input_enabled = false
    G->>G: fade_to(1.0)
    G->>G: mount_room()
    G->>P: 设置 Entry 位置并清空 velocity
    G->>S: record_arrival()
    G->>G: fade_to(0.0)
    G->>P: input_enabled = true

这里故意让 Signal 逐层转发：

• RoomExit 不知道 Game 在哪里。
• TransitionRoom 负责聚合本房间的出口和交互事件。
• Game 是唯一有权替换房间的对象。

4.6 为什么淡出时锁定输入

淡出和淡入由 Tween 驱动，是异步过程：

await fade_to(1.0)
mount_room(...)
await fade_to(0.0)

如果期间仍接受输入，可能出现：

• 玩家在黑屏中继续移动。
• 新房间刚挂载就离开入口。
• 连续触发另一个出口。
• 同时开始第二次切换。

因此同时使用：

transition_in_progress
player.input_enabled = false
RoomExit.armed = false

它们分别保护全局切换流程、角色输入和单个出口的重复触发。

4.7 Autoload 保存什么，不保存什么

GameSession 是 Autoload：

/root/GameSession
├── current_room_id
├── arrival_entry_id
└── flags

房间销毁时它不会销毁，所以 NPC 第二次实例化后仍能判断：

met_forest_guide 是否存在？

但 Autoload 不应该成为可以随意操纵所有节点的万能 Manager。当前它只保存跨房间会话数据，并发出数据变化 Signal；NPC 对话 UI 仍由 Game 管理。

4.8 @onready 的生命周期边界

@onready var exits = $Exits 只有节点进入 SceneTree、执行 _ready() 前才完成赋值。

但是房间预验证发生在：

instantiate()
→ 尚未 add_child()
→ 尚未进入 SceneTree

因此 has_entry() 不能依赖只在 _ready() 后才可用的缓存引用，而要显式读取：

get_node("Entries").has_node(entry_id)

这是 Scene 实例化和 SceneTree 生命周期之间很具体的边界。

5. Isometric：逻辑网格没有倾斜，倾斜的是投影

Isometric 最终画面。主世界由 Camera2D 观察，右侧 CanvasLayer 显示三种坐标空间，左下 SubViewport 根据共享逻辑数据绘制实时小地图。

5.1 Isometric 不是把地图整体旋转 45°

逻辑地图仍然是普通二维网格：

(0,0) (1,0) (2,0)
(0,1) (1,1) (2,1)
(0,2) (1,2) (2,2)

变化发生在 Grid 到屏幕坐标的投影。当前 Tile 逻辑脚印为 132×66：

screen_x = (x - y) × 66 + 66
screen_y = (x + y) × 33 + 33

因此：

+X → 屏幕右下 (+66, +33)
+Y → 屏幕左下 (-66, +33)

这里常说的“45°”是屏幕上的视觉描述，不是 Godot 存在一个只能设置为 45° 的游戏规则。2:1 Isometric 菱形边缘在屏幕坐标中的斜率由宽高比决定。

5.2 三个坐标空间

项目同时维护：

正变换由 IsoGridMath.grid_to_world() 实现；逆变换是解同一组方程：

grid_x = centered_x / 132 + centered_y / 66
grid_y = centered_y / 66 - centered_x / 132

连续 Grid 适合数学和插值；真正选择离散菱形格时，使用 TileMapLayer 的：

local_to_map()

让 Godot 根据 TileSet 的 Isometric 几何判断鼠标落在哪个菱形内。

5.3 Camera 启用后，鼠标坐标为什么要再转换

鼠标事件最初处于 Viewport 坐标，但 TileMap 接收世界/局部坐标。Camera2D 启用后，两者不再相等：

Viewport Mouse Position
→ Canvas Transform 的逆变换
→ World Position
→ TileMapLayer.to_local()
→ local_to_map()
→ Cell

项目也可以直接使用 get_global_mouse_position() 取得 Camera 变换后的世界坐标。

如果仍把 event.position 直接传给 TileMap，角色在相机移动后会走向鼠标之外的错误格子。

5.4 图片尺寸、Tile 脚印与素材脚点

Kenney 地砖图片高度可以是 99px，但 TileSet 的逻辑尺寸是 132×66。

原因是图片还包含地块侧面：

顶部菱形：逻辑地面脚印
土壤侧面：视觉厚度

同样，Player 和建筑根节点放在“脚接触地面的位置”，Sprite 作为子节点向上偏移。

Y Sort 比较 Node2D 原点的 Y，不会自动读取 PNG Alpha 边界或人物脚底。

5.5 Y Sort 与遮挡淡化是两个系统

场景结构：

Objects（y_sort_enabled = true）
├── Player（原点是脚点）
└── RedBuilding（原点是建筑脚点）
    ├── Visual: Sprite2D
    └── OcclusionArea: Area2D

普通前后关系由 Y Sort 决定：

Player.y < Building.y → Player 先绘制 → 建筑在前
Player.y > Building.y → Player 后绘制 → Player 在前

建筑淡化则由 OcclusionArea 检测 Player 的 VisibilityProbe：

Area 重叠
→ Tween 修改 Visual.modulate.a

职责分别是：

• Y Sort：谁先画、谁后画。
• Area2D：玩家是否进入特定遮挡区域。
• AStar 阻挡：建筑脚下的 Cell 是否可以通行。

三者看起来都与“建筑挡住玩家”有关，但不能合并成同一套数据。

5.6 为什么二维游戏使用了 AStar3D

初始地图只有一层，可以使用：

AStarGrid2D + Vector2i(x, y)

加入高地后，逻辑表面升级为：

Vector3i(x, y, z)

AStar3D 不是因为画面变成了 3D，而是它天然接受带三个分量的位置，并允许显式建立跨层连接。

当前规则是：

相同 z 的四方向相邻格 → 自动连接
不同 z → 默认不连接
坡道低端与高端 → 显式连接

所以角色不能从高地边缘直接“爬墙”，只能经过：

(9,12,0) ↔ (10,12,1)

5.7 高度、Y Sort 与 z_index

高地画面向上移动：

screen_position = iso_position - Vector2(0, z × 33)

但角色被视觉抬高后，它的屏幕 Y 反而变小。仅使用 Y Sort，可能把高地角色判断成“更靠后”。

因此逻辑高度需要覆盖普通 Y Sort：

z_index = current_surface.z * 10

这说明：

Y Sort 适合解决同一逻辑平面上的前后顺序；跨逻辑层级时需要额外的绘制规则。

5.8 Camera2D、CanvasLayer 与 SubViewport

这三个节点经常同时出现在屏幕系统中，但职责完全不同：

节点结构：

Interface: CanvasLayer
└── Minimap: PanelContainer
    └── SubViewportContainer
        └── SubViewport
            └── MinimapRenderer: Node2D

小地图没有用第二台 Camera 原样拍摄整个主世界，而是让 MinimapRenderer._draw() 根据共享逻辑数据绘制简化视图：

MAP_SIZE / HIGH_REGION / BLOCKED_CELLS / Ramp / Building
                       ↓
              MinimapRenderer._draw()
                       ↓
      地面、高地、阻挡、建筑、路径、目标、Player

这形成了同一模型的两种表现：

地图模型
├── 主世界：Tile、Sprite、遮挡、Camera
└── 小地图：颜色、线段和标记

Player 的连续 Grid 位置每帧同步；地图结构只初始化一次；路径和目标只在路线改变时更新。不同数据采用不同更新频率。

6. 三个项目放在一起后，节点职责更清楚了

6.1 物理节点选择

需要主动移动且碰撞响应？
→ CharacterBody2D

需要成为会运动的实体表面？
→ AnimatableBody2D

只需要检测进入、离开、重叠？
→ Area2D

大量静态地形由 Tile 数据描述？
→ TileMapLayer + TileSet Physics Layer

具体对应：

6.2 四种“位置”不是同一个值

今天至少出现了四类位置：

它们之间应该通过明确函数转换，不能靠“看起来差不多”直接传递。

6.3 三种生命周期

应用生命周期
└── GameSession / Autoload

运行关卡生命周期
└── Game / Player / Interface

内容生命周期
└── CurrentRoom / Props / 临时场景

对象应该放在哪一层，取决于它需要活多久，而不是它在节点树中看起来适合放哪里。

6.4 三种更新方式

不是所有逻辑都应该放进 _process()。能由事件驱动的状态，不需要每帧轮询。

7. 真实素材不是“最后再美化”，而是工程输入

Platformer 和 Isometric 都开始使用真正素材，但素材类型决定处理方式。

7.1 Source 与 Runtime 分层

assets/source/
    完整供应商包、AI 原图、审计基线
            ↓ 选择、检查、转换
assets/runtime/
    游戏实际加载的最小集合
            ↓ 构建工具
TileSet / SpriteFrames / Scene

完整供应商包通过 .gdignore 避免 Godot 导入数百个不使用的文件；Runtime 目录只保留真正需要进入项目和导出的素材。

7.2 为什么角色动画不继续切生成式大图

AI 图适合：

• 背景氛围。
• 单张角色立绘。
• 概念草图。
• 对严格像素边界要求较低的素材。

逐帧角色动画要求：

• 每帧尺寸一致。
• 脚点稳定。
• 动作周期连续。
• Alpha 边界可预测。
• 切片位置精确。

Platformer 最终改用 SunnyLand 官方独立帧，而不是继续猜测 AI 大图中的帧边界。Isometric 当前只需要静态角色，因此 AI 透明 PNG 可以胜任。

关键不是坚持某一种素材来源，而是：

根据资产的技术契约选择来源，并对尺寸、Alpha、脚点、授权和运行效果进行验收。

7.3 TileSet 构建工具的价值

TileSet 包含 Atlas 坐标、Tile 尺寸、碰撞多边形、Custom Data 等结构化信息。用工具脚本生成派生 .tres，可以：

• 固定输入素材和 Atlas 坐标。
• 避免 Inspector 手工操作无法复现。
• 自动重建碰撞和元数据。
• 用测试检查生成结果。

所以资产管线也属于代码和测试范围，而不是仓库外的手工步骤。

8. 今天反复使用的工程模式

8.1 数据所有权必须单一

表现层可以读取或订阅数据，但不应该偷偷建立第二份权威状态。

8.2 候选—验证—提交

昨天在 Tetris 旋转中出现，今天又用于房间切换：

构造候选状态
→ 验证是否合法
→ 验证通过才替换真实状态

后续背包交易、装备更换和存档加载都应该继续采用同一模式。

8.3 Scene 表达可复用对象，Resource 表达可复用数据

PlatformActor.tscn
→ 节点结构、碰撞、Trigger、Visuals

MovementProfile.tres
→ 速度、跳高、时间、容错参数

Scene 实例化后进入 SceneTree并拥有生命周期；Resource 通常被节点引用，保存配置和领域数据。

8.4 Signal 表达意图，所有者执行改变

Checkpoint body_entered
→ World 修改出生点

RoomExit transition_requested
→ Game 替换房间

Actor path_changed
→ 主场景和小地图更新路线表现

发出事件的对象不一定有权直接修改最终状态。

8.5 调试表现是理解系统的工具

Platformer HUD 暴露：

• 速度。
• 运动状态。
• 地面法线。
• Coyote 和 Jump Buffer 计时。
• Tile Cell 和 Surface Type。

Isometric HUD 暴露：

• 离散 Cell。
• 连续 Grid。
• Map-local Pixel。
• Z Level。
• Path Steps。

调试 UI 的价值不是好看，而是把不可见的运行状态变得可观察。学习项目尤其应该保留这种可解释性。

9. 自动测试与人工画面验收分别负责什么

9.1 自动测试适合验证

• 跳跃公式是否满足目标高度和时间。
• Coyote、Buffer、Jump Cut 是否按条件发生。
• TileSet 是否包含正确碰撞和 Custom Data。
• 所有平台高度是否在跳跃预算内。
• 房间与入口映射是否正确。
• 非法房间请求是否保留当前状态。
• Flag 是否跨房间恢复。
• Grid 正逆变换是否一致。
• AStar 路径是否绕开阻挡并经过坡道。
• 高地 Player 是否获得正确 z-index。
• SubViewport 小地图是否收到共享状态。
• 素材尺寸、Alpha 和来源记录是否符合契约。

9.2 人工运行适合判断

• 加速、减速、顶点停留和下落是否舒服。
• 平台高度理论可达，但实际是否容易跳上去。
• 斜坡有没有卡顿或视觉错位。
• 淡出节奏是否自然。
• 建筑遮挡淡化是否让玩家看得清。
• Character Sprite 的大小和脚点是否合适。
• 1152×648 Mac 窗口下 HUD 是否遮挡主要画面。
• 小地图信息是否能辨认。

可以概括为：

自动测试验证规则和契约，人负责判断手感、构图与可读性。

10. 我们主动跳过了什么

10.1 Platformer 没有继续加入敌人和战斗

Action Arena 已经实践过攻击、生命、伤害、敌人状态、音效和命中反馈。继续加入只会扩大关卡，而不会显著增加平台物理知识。

10.2 Room Transitions 保持诊断型画面

这个短专项的独特价值是 Scene 生命周期、入口映射和跨房间状态。真实素材管线已经在 Platformer 中实践，因此没有再次花大量时间包装两间房。

10.3 Isometric 没有继续加入 NPC 和战斗

Isometric 已覆盖投影、选格、AStar3D、Y Sort、高度、遮挡、Camera 和小地图。继续加入 NPC 战斗会重复 Action Arena 与 Room Transitions 的系统。

10.4 没有把小地图扩展成完整导航产品

当前没有加入：

• 点击小地图移动。
• Camera 可见范围框。
• 敌人、任务和楼层筛选。
• 战争迷雾。
• 图标聚合。

这些都可以继续做，但已经超出 Isometric 项目的必要学习上限。

11. 今天怎样继续训练“驾驭 AI”

11.1 不接受只在代码里成立的功能

AI 完成节点和脚本后，还需要：

Godot 导入
→ Parse / Headless Tests
→ 主场景启动
→ 真实渲染截图
→ 人工查看布局和素材

例如小地图测试通过，只能说明状态连接成立；实际 1152×648 截图才能确认它没有和 Telemetry 重叠。

11.2 要求下一步和下下步

先知道后续两步，可以判断当前实现是否在建立必要接口，还是在没有目标的情况下扩建。

但提前知道后续，不等于提前实现后续。当前 Demo 达到独特学习目标后，应主动停止。

11.3 发现实现偏离预期时，回到原生节点

角色动画曾经只有代码绘制表现，没有 AnimatedSprite2D。问题不是“画面能不能动”，而是它绕开了要学习的 Godot 原生动画资源和编辑器工作流。

修正后的标准是：

需要学习动画资源
→ AnimatedSprite2D + SpriteFrames

需要学习时间线和 Gameplay 事件
→ AnimationPlayer

需要复杂混合
→ 后续 AnimationTree 专项

11.4 素材也要有契约和来源

不能只要求“换成真实贴图”，还应检查：

1. 来源和许可证。
2. 原图与 Runtime 文件分层。
3. 尺寸、Alpha 和脚点。
4. Tile 或动画帧的切割方式。
5. 编辑器能否预览。
6. 构建和导出时是否可用。

11.5 用问题审查架构，而不是逐行背代码

面对 AI 生成的 Godot 项目，优先回答：

1. 根节点是谁？
2. 哪些节点是常驻的，哪些会销毁？
3. 权威状态保存在哪里？
4. 谁只发出意图，谁真正提交修改？
5. 坐标从哪个空间转换到哪个空间？
6. 物理、导航和绘制各自负责什么？
7. 哪些数据每帧更新，哪些只在事件发生时更新？
8. 如何自动验证，如何人工验收？

12. 关键词词典

物理与运动

• CharacterBody2D：由代码控制速度，并通过 move_and_slide() 接受碰撞约束的角色物理体。
• AnimatableBody2D：适合移动平台等由脚本或动画改变位置、同时影响其他物理体的对象。
• Area2D：检测重叠，不提供普通实体阻挡。
• velocity：期望速度，不等于未经物理修正的最终位移。
• Floor Normal：角色与地面接触面的法向量。
• One-way Collision：通常只从上方阻挡角色的平台碰撞。
• Coyote Time：离开平台后短暂保留的起跳资格。
• Jump Buffer：起跳条件满足前短暂保存的输入意图。
• Jump Cut：松开跳跃键时削减上升速度，形成可变跳高。

场景与生命周期

• PackedScene：尚未实例化的可复用 Scene 资源。
• instantiate()：从 PackedScene 创建运行时节点树。
• add_child()：把节点加入 SceneTree，使其开始接收完整生命周期。
• queue_free()：在安全时机延迟销毁节点。
• Autoload：在项目启动时挂载到根节点、可跨普通场景存在的全局节点。
• Entry Marker：房间内部有语义名称的到达位置。
• Mount：把已经验证的内容节点挂载到指定父节点。

Tile 与空间

• TileSet：Tile 的纹理区域、几何、碰撞和元数据定义。
• TileMapLayer：使用 TileSet 在地图坐标上放置 Tile 的单层地图节点。
• Grid Space：规则使用的逻辑格坐标。
• Map-local Space：TileMapLayer 内部的二维像素坐标。
• Viewport Space：窗口或渲染目标中的屏幕坐标。
• Canvas Transform：世界 Canvas 与 Viewport 之间由 Camera 等产生的变换。
• Isometric Projection：将正交逻辑网格映射到菱形屏幕布局的投影。
• Foot Point：Sprite 对应地面接触位置的节点原点。

导航与绘制

• AStar3D：在任意三维点图上寻找低成本路径；本项目用第三维表达逻辑高度。
• Y Sort：根据同一排序上下文中的 CanvasItem Y 位置决定绘制顺序。
• z_index：显式调整 CanvasItem 绘制层级。
• Camera2D：决定主 Canvas 的观察位置、缩放和边界。
• CanvasLayer：为 HUD 建立不受主世界 Camera 影响的 Canvas 层。
• SubViewport：独立渲染一棵子节点树并产生 ViewportTexture。
• SubViewportContainer：在 Control UI 中显示 SubViewport 的渲染结果。
• _draw()：CanvasItem 的自定义绘制回调。
• queue_redraw()：请求 Godot 在后续绘制阶段再次调用 _draw()。

13. 读完后应该能够回答的问题

1. 为什么 Platformer Player 应调用 move_and_slide()，而不是直接修改 position？
2. 为什么跳跃参数使用高度和时间，而不是同时手调初速度与重力？
3. Coyote Time 和 Jump Buffer 分别保存什么？
4. CharacterBody2D、AnimatableBody2D 和 Area2D 在三个项目中分别对应哪些对象？
5. 为什么静态地形使用 TileMapLayer，而移动木板使用独立 Scene？
6. get_floor_normal() 怎样证明斜坡底层碰撞确实不同？
7. 为什么 Player 和 HUD 不放在 CurrentRoom 里面？
8. PackedScene 和实例化后的 Room Node 有什么区别？
9. 为什么房间切换必须先验证新房间，再卸载旧房间？
10. 为什么用 room_id + entry_id，而不是在门上写目标坐标？
11. Autoload 应该保存什么，为什么不应该控制所有节点？
12. 未进入 SceneTree 的实例为什么不能依赖 @onready 字段？
13. Isometric 地图的逻辑网格是否真的旋转了 45°？
14. 离散 Cell、连续 Grid 和 Map-local Pixel 分别用在什么地方？
15. Camera2D 启用后，为什么鼠标事件需要转换回世界坐标？
16. 为什么 99px 高的地砖图片可以拥有 66px 高的逻辑 Tile 脚印？
17. Y Sort、Occlusion Area 和 AStar 阻挡分别解决什么问题？
18. 二维游戏为什么会选择 AStar3D？
19. 为什么高地角色还需要显式 z-index？
20. Camera2D、CanvasLayer 和 SubViewport 的底层职责有什么不同？
21. 为什么小地图没有直接重复渲染主世界的所有 Sprite？
22. 哪些状态应该每帧同步，哪些应该由 Signal 更新？
23. 为什么真正素材也需要自动测试和授权记录？
24. 自动测试与人工画面验收各自不能替代什么？
25. 怎样判断一个教学 Demo 已经达到学习上限，应当停止扩建？

14. 下一步

下一项目进入：

07-inventory-shop/

它承担长期路线中的“背包 + 商店 + 装备”，重点第一次系统学习数据层：

ItemDefinition: Resource
→ Inventory Model
→ Inventory Slot / Stack Rule
→ Control UI
→ Drag and Drop
→ Shop Transaction
→ Equipment Rule
→ Serialization / Save

这里会继续复用今天的原则：

• Resource 定义共享物品数据。
• 背包模型是权威状态，UI 只是表现。
• 买卖采用候选—验证—提交，避免金币和物品只改了一边。
• 拖放事件表达用户意图，Inventory 决定操作是否合法。
• 存档加载先验证，再替换当前状态。

真正的新增目标不是画出一排物品格，而是让数据模型、UI、交易和持久化第一次形成完整闭环。

0.2.60以下都正常没有报错

Meilisearch这个0.2.60以下都有吧？

日期：2026-08-24
项目：Snake → Tetris → Action Arena
目标读者：准备借助 AI 入门游戏开发，但不满足于“代码能跑”，希望能理解、判断、修改和继续扩展的人。

1. 今天真正练习的不是三个小游戏

表面上，我们实现了贪吃蛇、俄罗斯方块和俯视角动作竞技场。真正的学习路线是：

1. 先理解 Godot 如何启动、更新和连接节点。
2. 再学习如何用数据表达游戏世界，而不是用画面节点代替数据。
3. 再把规则、角色能力、状态、配置、AI 和表现拆成可以独立思考的系统。
4. 最后学习怎样让 AI 生成的代码仍然可检查、可替换、可测试、可继续扩展。

三个项目分别承担了不同职责：

这条路线可以概括为：

flowchart LR
    A[Godot 运行模型] --> B[数据表达游戏状态]
    B --> C[规则与表现分离]
    C --> D[组件化与状态机]
    D --> E[数据驱动与事件解耦]
    E --> F[AI / 动画 / 音频 / VFX]
    F --> G[能够审查和驾驭 AI 生成的项目]

2. 先建立 Godot 的总心智模型

2.1 Godot 没有传统意义上的 main()

Godot 的入口不是某个由我们手写的 main() 函数，而是：

project.godot
    ↓ run/main_scene
入口 .tscn 场景
    ↓ Godot 实例化节点树
各节点收到生命周期回调

常见回调包括：

• _ready()：节点已经进入 SceneTree，并且子节点已经准备完成。
• _process(delta)：每个渲染帧调用，适合 UI、普通动画和视觉时间。
• _physics_process(delta)：按固定物理频率调用，适合移动与物理逻辑。
• _unhandled_input(event)：接收尚未被 UI 等系统处理掉的输入事件。
• _draw()：自定义绘制函数；调用 queue_redraw() 后，Godot 会安排重新绘制。

开头的下划线不是“私有”的语法标记。对于 _ready()、_process() 等函数，它表示 Godot 约定的引擎回调；对于 _on_timer_timeout()，则只是常用命名风格，真正使它运行的是 Signal Connection。

例如：

Timer 发出 timeout
    ↓ 场景中的 connection
_on_move_timer_timeout()

把函数改名为 move_snake_now() 也可以，只要 Signal 连接同步修改。因此：

函数名帮助人理解，连接关系决定事件最终调用谁。

2.2 Scene、Node、Script 的关系

可以把 Godot 的核心关系理解为：

Scene（可保存、可复用的节点树）
└── Node（运行时对象）
    ├── 属性
    ├── 子节点
    ├── Signal
    └── Script（附加行为）

• Node 是组成游戏的基本运行对象。
• Scene 是一棵可以保存为 .tscn、以后重复实例化的节点树。
• Script 是附着在节点上的行为，不等于节点本身。
• SceneTree 是当前正在运行的整棵节点树。
• Main Scene 是项目启动时首先实例化的场景。

2.3 与 Web/DOM/JS 的类比

这个类比非常有用，但不是完全等价：

最重要的类比是：

.tscn 更像结构模板，.gd 更像行为模块；但 Godot 的节点不仅是 DOM 元素，也可能是物理、音频、导航、计时和纯逻辑对象。

2.4 常见文件与路径

并不是所有字符串都要加 res://：

• 加载项目文件时使用：preload("res://scripts/game.gd")。
• 场景内查找子节点时使用 NodePath：$StateMachine/Idle。
• 普通字符串、Signal 名称、Group 名称不需要 res://。

3. 项目目录：领域边界比文件数量更重要

省略 .uid、.import 和编辑器缓存后，仓库的主要结构是：

godot-learning-roadmap/
├── 01-snake/
│   ├── project.godot
│   ├── main.tscn
│   ├── scripts/
│   │   ├── main.gd
│   │   ├── snake_game.gd
│   │   └── grid_utils.gd
│   └── tests/
├── 02-tetris/
│   ├── project.godot
│   ├── main.tscn
│   ├── scripts/
│   │   ├── main.gd
│   │   ├── tetris_board.gd
│   │   ├── tetromino.gd
│   │   ├── tetromino_catalog.gd
│   │   └── tetromino_bag.gd
│   └── tests/
└── 03-action-arena/
    ├── assets/audio/
    ├── resources/attacks/
    ├── scenes/
    │   ├── world.tscn
    │   ├── player.tscn
    │   ├── enemy.tscn
    │   └── effects/hit_effect.tscn
    └── scripts/
        ├── actors/
        │   ├── player.gd
        │   ├── enemy.gd
        │   ├── player_states/
        │   ├── enemy_states/
        │   └── shared_states/
        ├── combat/
        ├── components/
        ├── data/
        ├── presentation/
        ├── state_machine/
        └── world.gd

目录不是为了“看起来专业”，而是在表达领域：

• actors/：角色拥有哪些能力。
• states/：角色在什么条件下使用能力。
• components/：可组合、职责单一的 Gameplay 功能。
• data/ 和 resources/：配置结构与具体配置资产。
• combat/：一次战斗事件的数据协议。
• presentation/：镜头、音频、粒子、数字等反馈。
• scenes/：上述对象怎样被装配起来。

AI 生成项目时，目录树是第一份架构文档。先读目录，再读事件流，最后才需要逐行读代码。

4. Snake：先理解运行循环与数据模型

4.1 固定 Tick 与逐帧表现

贪吃蛇不是每一帧移动一点，而是每隔固定时间移动一格：

sequenceDiagram
    participant Input as 输入事件
    participant Model as SnakeGame
    participant Timer as MoveTimer
    participant View as main.gd / _draw

    Input->>Model: queue_direction(direction)
    Timer->>Model: step()
    Model-->>Timer: MOVED / ATE_FOOD / HIT_WALL / HIT_SELF
    Timer->>View: 更新 UI、状态、VFX
    View->>View: queue_redraw()

这里分成两种时间：

• Rule Tick：由 Timer.timeout 驱动，每次处理一格移动。
• Render Frame：由 _process(delta) 驱动，用于食物呼吸和吃到食物的扩散圆环。

这比“所有东西都放进 _process()”更容易保证规则稳定。

4.2 蛇身不是递归，而是有序序列

蛇身使用：

Array[Vector2i]

数组中的第一个元素是蛇头，后面的元素依次表示身体。普通移动的核心是：

计算新蛇头
→ push_front(new_head)
→ 如果没吃食物，pop_back()

所以之前的直觉“移除最后一个，然后加第一个”基本正确。准确说是：增加新的头部，并在普通移动时移除旧尾部。吃到食物时不移除尾部，因此长度增加。

没有使用递归，因为身体不是“节点包含下一个节点”的链式调用；它只是一次遍历即可绘制的有序坐标数组。

4.3 为什么没有只用 Map 保存身体

Map/Dictionary 或 Set 很适合回答：

某个格子是否已被占用？

但蛇还需要回答：

谁是头？
谁是尾？
身体顺序是什么？
下一步应该删除哪一格？

这些是有序序列问题，因此 Array 更自然。大型蛇可以使用混合结构：

Array / Deque：维护身体顺序
Set / Dictionary：O(1) 查询占用

当前棋盘很小，遍历成本可以忽略；为了学习清晰度，先使用单一 Array。

4.4 输入缓冲

如果玩家在两个 Tick 之间快速按“上、左”，只保存最后一个按键可能丢失意图。我们使用最多两个方向的队列：

渲染帧输入：上 → 左
规则 Tick 1：消费“上”
规则 Tick 2：消费“左”

禁止反向时比较的不是当前方向，而是“最后一个已经计划的方向”。这是实时输入系统常见的 Buffered Input。

4.5 模型与表现分离

SnakeGame 继承 RefCounted，不进入 SceneTree：

• 它保存蛇身、食物、方向、分数和碰撞规则。
• 它不知道 Label、Timer、颜色或屏幕坐标。
• main.gd 负责输入、节点、UI、绘制和 VFX。

这是今天第一次建立清晰的 Model/View 边界。

Web 类比：

SnakeGame ≈ reducer / domain model
main.gd ≈ UI controller / component
_draw() ≈ 根据 state 渲染 UI
StepResult ≈ domain event / action result

4.6 测试学到了什么

Snake 的纯规则模型可以无头运行：

/Applications/Godot.app/Contents/MacOS/Godot \
  --headless \
  --path 01-snake \
  --script res://tests/test_snake_game.gd

无头不是唯一执行方式，只是自动化最方便的方式。还可以：

• 把测试脚本挂到专门测试场景并从编辑器运行。
• 使用 GUT 等第三方测试插件。
• 直接运行普通游戏场景做人工交互验证。

无头测试的价值是速度快、退出码明确、适合 AI 每次改动后自动验证。

5. Tetris：用候选状态驾驭复杂规则

5.1 棋盘为什么用二维数组

俄罗斯方块的核心问题是占用关系：一个确定的 10 × 20 空间里，哪些格子是空的，哪些已锁定。

cells[y][x] = -1    空格
cells[y][x] = 0..6  某种方块颜色/类型

这是稠密、固定大小的二维空间，二维数组比 Dictionary 更直观：

• 容量只有 200 格。
• 消行天然按 row 操作。
• 绘制天然按 y/x 遍历。
• 不需要为稀疏存储增加复杂度。

5.2 局部坐标与棋盘坐标

Tetromino 不直接保存四个绝对棋盘坐标，而是保存：

四个 local_cells + 一个 position

换算关系：

board_cell = position + local_cell

Web/图形类比：一个 SVG Group 或 DOM 容器拥有整体 transform，子元素保存相对位置。移动整个方块只需修改 position，不需要分别修改四个格子。

5.3 候选—验证—提交

旋转和移动都遵守同一个重要模式：

flowchart LR
    A[当前合法状态] --> B[计算候选状态]
    B --> C{can_place?}
    C -- 是 --> D[提交修改]
    C -- 否 --> A

旋转不是先改再撤销，而是：

1. 计算候选局部坐标 (x, y) → (-y, x)。
2. 转换成棋盘坐标。
3. 检查边界和固定格。
4. 全部合法才 apply_shape()。

这个模式可以迁移到很多领域：

• 背包是否能放入物品。
• 技能是否有足够资源。
• 建筑是否能放在地图上。
• 网络服务器是否接受客户端操作。
• 数据库事务是否满足约束。

5.4 为什么有多个地方调用 _lock_active_piece()

锁定方块有两个不同触发入口：

Gravity / Soft Drop 无法继续向下
                    ├──→ _lock_active_piece()
Hard Drop 到达落点 ─┘

它们触发原因不同，但锁定后的规则完全相同：写入棋盘、消行、计分、生成新方块、判断 Game Over。因此应该汇聚到同一个函数，避免复制两份规则。

这叫“多个入口，一个领域操作”，与 Web 中多个按钮最终调用同一个 service method 类似。

5.5 7-bag、Next、Ghost 与 Hard Drop

• 7-bag：七种方块各放一次，Fisher–Yates 洗牌，一袋用完再生成下一袋。
• Next Piece：提前从 bag 取出一个类型作为预览。
• Ghost Piece：逐格计算还能下降的距离，只绘制半透明候选位置。
• Hard Drop：复用同一个下降距离，移动并立即锁定。

Ghost 与 Hard Drop 共用规则非常重要：

视觉预测和真实执行必须来自同一个计算，否则 AI 很容易生成“影子在这里，实际落在另一格”的重复逻辑 Bug。

6. Action Arena：从规则脚本进入游戏架构

上图来自当前 Godot 项目的真实运行截帧。橙红折线是 NavigationAgent2D 的调试路径；角色头顶文字是当前 FSM 状态；右侧敌人身上的橙色点状爆发和伤害数字来自临时 HitEffect 场景。

6.1 最小战斗闭环

最早的闭环只有：

Player 移动
→ 开启 Hitbox
→ Enemy Hurtbox 收到命中
→ HealthComponent 扣血
→ 血量归零后 Enemy queue_free()

这里建立了三个可复用组件：

• Hitbox：攻击生效区域，负责发送伤害。
• Hurtbox：可受击区域，负责接收并转发命中。
• HealthComponent：管理生命值，发出 health_changed、damaged、died。

Hitbox 不应该直接写：

enemy.health -= 1

因为这会要求攻击者认识 Enemy 的具体结构。当前方案让 Hitbox 只寻找拥有 receive_hit() 的 Area，Hurtbox 再通过 Signal 转发。

6.2 Signal 是解耦，不只是回调写法

同一个 Hurtbox.hit_received 可以有多个监听者：

flowchart LR
    A[Hurtbox.hit_received] --> B[HealthComponent.take_hit]
    A --> C[Actor 请求命中反馈]
    B --> D[扣血 / damaged / died]
    C --> E[音效 / 震动 / Hit Stop / 粒子 / 伤害数字]

Gameplay 和 Presentation 收到同一个事实，但各自处理自己的领域。这类似 Web 中一次业务事件同时更新 Store、埋点和通知 UI。

6.3 有限状态机 FSM

Player 同时只能处于：

stateDiagram-v2
    [*] --> Idle
    Idle --> Move: 有方向输入
    Move --> Idle: 方向归零
    Idle --> Attack: 攻击输入且冷却完成
    Move --> Attack: 攻击输入且冷却完成
    Attack --> Idle: 动画结束
    Idle --> Hurt: 收到攻击
    Move --> Hurt: 收到攻击
    Attack --> Hurt: 收到攻击，中断攻击
    Hurt --> Idle: 硬直结束

Enemy 复用相同的 StateMachine 调度器，但使用不同策略：

Idle → Chase → Attack
  ↖       ↑       ↓
    Hurt 恢复后根据目标决定

关键职责：

• StateMachine：保存唯一 current_state，调用 exit()/enter()，转发输入和物理帧。
• State：决定什么时候请求转换。
• Actor：提供移动、攻击、停止、受伤等能力。
• State 不直接替换 current_state，只发出 transition_requested。

Web 类比：

StateMachine ≈ reducer / XState machine
State Node ≈ 某个状态下允许的 action handler
Actor 能力 ≈ service / command methods
transition_requested ≈ dispatch(action)

状态机解决的是“当前谁有决策权”，不是把所有函数机械地拆成文件。

6.4 数据驱动：AttackData 与 .tres

AttackData 定义攻击配置结构：

damage
knockback_force
hitstun_duration
active_duration
cooldown_duration
reach
hitbox_size

basic_slash.tres 和 enemy_strike.tres 是两份具体数据：

AttackData.gd：定义 schema / 类型
basic_slash.tres：一条具体配置记录
player.tscn：把配置注入 Player
Player：消费配置，不硬编码每个数值

Web 类比：TypeScript interface/class 定义结构，JSON/数据库记录保存具体值，组件通过 props 或依赖注入获得配置。

注意：Resource 是持久配置，不等于运行时事件。

6.5 AttackData 与 HitData 为什么是两个对象

HitData 携带：

• 本次伤害。
• 攻击来源位置。
• 击退力度。
• 硬直时间。

这种对象也叫 Event Payload、Message、DTO。Signal 不是只能发出“发生了”，还可以携带事件上下文。

6.6 碰撞 Layer 与 Mask

• Layer：我属于哪些类别，“我是谁”。
• Mask：我希望检测哪些类别，“我要找谁”。

本项目使用独立通道：

Player Hitbox  → Enemy Hurtbox
Enemy Hitbox   → Player Hurtbox
Player Body    ↔ Arena Wall
Enemy Body     ↔ Arena Wall

它更像一张允许通信的过滤矩阵，不是 CSS 的 z-index。视觉遮挡顺序和物理 Layer 是两件事。

6.7 敌人感知与语义身份

Enemy 的 PerceptionArea 通过 body_entered 和 body_exited 维护 target。Player 通过 player Group 表达身份，不依赖节点名必须叫 Player。

PerceptionArea 检测 Body
→ body.is_in_group("player")
→ 保存 target 引用
→ Idle 请求 Chase

Group 相当于语义标签。它比检查具体脚本类型或固定路径更松耦合。

6.8 寻路与物理碰撞不是同一件事

场景中的墙被两个系统描述：

NavigationPolygon 的空洞：告诉 AI 路线不能经过这里
StaticBody2D Collision：真的阻挡角色身体

NavigationAgent2D 的工作流程：

target_position = Player.global_position
→ get_next_path_position()
→ 朝下一个路径点移动
→ move_and_slide() 处理真实物理移动

导航回答“应该走哪条路线”，物理回答“此刻能不能穿过去”。如果只做导航没有墙体，玩家仍可能走穿；如果只有墙没有导航，敌人可能一直顶着墙追玩家。

6.9 受击、硬直、击退与无敌时间

命中后的完整流程：

sequenceDiagram
    participant Hitbox
    participant Hurtbox
    participant Health as HealthComponent
    participant FSM as StateMachine
    participant Actor

    Hitbox->>Hurtbox: receive_hit(HitData)
    Hurtbox->>Health: hit_received(HitData)
    Health->>Health: 扣除生命值
    Health-->>FSM: damaged(HitData)
    FSM->>Actor: 进入 Hurt
    Actor->>Actor: 中断攻击、击退、开启无敌
    Actor->>FSM: HurtTimer 到期
    FSM->>Actor: 恢复 Idle 或 Chase
    Actor->>Actor: InvincibilityTimer 到期后重新启用 Hurtbox

相关术语：

• Knockback：命中造成的位置推移。
• Hitstun：受击后不能行动的硬直时间。
• Invincibility Frames / I-frames：短暂无敌窗口。
• Interrupt：当前 Attack/Move/Chase 被 Hurt 强制打断。
• Recovery State：受击结束后返回哪个状态。

HurtTimer 与 InvincibilityTimer 分开，是因为“恢复行动”和“可以再次受击”不一定在同一时刻。

6.10 动画驱动战斗

早期攻击由 AttackTimer 直接控制 Hitbox。后来 Player 改为 AnimationPlayer 时间线：

0.00s ───── 0.15s ───── 0.25s ───────── 0.42s
      前摇       有效命中帧           后摇结束
                 ↑       ↑                ↑
              open()  close()    animation_finished

AnimationPlayer 中包含：

• Value Track：改变 Weapon 的 rotation、scale。
• Keyframe：某个时间点的属性值。
• Call Method Track：在 0.15s/0.25s 调用 Hitbox 开关函数。
• animation_finished Signal：整段动画结束，Attack State 才返回 Idle。

WeaponPivot 负责角色朝向，Weapon 自己播放挥砍。我们没有旋转 Player 根节点，因为根节点还包含碰撞体、状态机和移动坐标系。

这一步建立了 Animation-driven Gameplay：动画不只是装饰，而是战斗时间线的一部分。

6.11 命中反馈：Camera、Hit Stop 与 Audio

CombatFeedback 集中处理表现：

• Camera2D offset：150ms 轻微随机震动。
• Hit Stop：把 Engine.time_scale 暂时降到 0.08。
• Hit Audio：播放撞击声并轻微随机 pitch。
• Swing Audio：Player 开始挥砍时播放空间音效。

Hit Stop 的恢复 Timer 使用 ignore_time_scale=true，否则负责恢复时间的 Timer 也会被自己减速。

连续命中还引入了异步竞争问题。通过递增 serial，只允许最后一次命中的等待任务恢复 time scale：

Hit #1 → serial 1 ──等待──┐ 发现已过期，不恢复
Hit #2 → serial 2 ────────┴→ 最后恢复到 1.0

这与 Web 中避免旧请求覆盖新请求的 request id / cancellation token 很相似。

6.12 临时特效场景与生命周期

每次命中动态创建 hit_effect.tscn：

preload PackedScene
→ instantiate()
→ setup(damage)
→ add_child()
→ GPUParticles2D 播放火花
→ Tween 上浮、淡出伤害数字
→ tween.finished
→ queue_free()

这个对象拥有自己的出生、播放和死亡，不要求 World 保存引用并定期清理。

相关概念：

• GPUParticles2D：批量模拟粒子。
• ParticleProcessMaterial：速度、扩散角、重力、阻尼、缩放和颜色渐变。
• one_shot：只播放一次。
• explosiveness：粒子在开始时集中喷发。
• Tween：用插值在一段时间内改变属性。
• Transient Object：短生命周期对象。

7. 今天反复使用的架构模式

7.1 单一职责

一个对象应该有一个主要变化原因：

• HealthComponent 因生命规则变化而修改。
• Hitbox 因命中规则变化而修改。
• CombatFeedback 因表现风格变化而修改。
• AttackData 因数值设计变化而修改。

7.2 组合优于巨型脚本

Player 不是一个包含所有系统的 1000 行脚本，而是组合：

CharacterBody2D
+ Hitbox
+ Hurtbox
+ HealthComponent
+ StateMachine
+ AnimationPlayer
+ Timer
+ AudioStreamPlayer2D

组件化不是“文件越多越好”，而是让可独立变化、可复用、可替换的职责获得边界。

7.3 事件驱动

Signal 表达已经发生的事实或请求：

• timeout
• health_changed
• damaged
• died
• transition_requested
• attack_finished
• animation_finished
• hit_feedback_requested

命名通常使用过去式表示事实，例如 damaged、died；使用 requested 表示请求尚需权威对象批准。

7.4 数据驱动

把“1 点伤害、44 像素距离”写在攻击逻辑里叫硬编码；把它们放在 AttackData Resource 中，逻辑读取数据，叫数据驱动。

数据驱动的价值：

• AI 可以帮你生成新配置，而不复制逻辑。
• 设计调参不需要改代码。
• Player 和 Enemy 可以复用同一套组件。
• 更容易形成技能表、武器表、敌人配置表。

7.5 先构造候选，再验证，再提交

这一模式从 Tetris 延伸到 Action Arena：

• 旋转候选是否合法。
• 状态切换请求是否来自当前状态。
• Hitbox 是否已经命中过同一个目标。
• 是否处于冷却、死亡或无敌状态。

它是控制 AI 生成代码副作用的关键方式。

7.6 规则与表现分离

规则层：坐标、血量、状态、伤害、路径
表现层：颜色、动画、音效、震动、粒子、数字

表现可以很华丽，但不能成为扣血是否发生的唯一依据；规则可以被测试，但不需要加载所有视觉资产。

8. 我们主动跳过了什么

跳过不是遗漏，而是控制学习范围。

8.1 Tetris Hold Piece

计划用 Hold Piece 学习“每个活动方块只能交换一次”的状态约束，但我们判断这一概念已经容易理解，因此没有继续实现。

如果以后补做，需要状态：

held_piece_type
can_hold_current_piece

新方块出生时重置权限，当前方块已经 Hold 过就拒绝再次交换。

8.2 Tetris Wall Kick / SRS

当前旋转靠墙失败，不会尝试左右平移寻找合法位置。正式俄罗斯方块通常使用 Super Rotation System 和 Wall Kick 表。这里跳过是因为重点是候选旋转与验证，不是完整复刻竞技规则。

8.3 后续自动化测试

Snake 和 Tetris 建立了纯模型测试及无头执行方法。Action Arena 后半段以学习架构和表现为主，没有为每个状态和反馈系统继续增加永久测试。

这适合学习 Demo，但生产项目至少应继续测试：

• 状态转换是否合法。
• 致命攻击与普通受伤的事件顺序。
• 同一攻击不能重复命中同一 Hurtbox。
• Hit Stop 后 time scale 必须恢复。
• 临时特效必须销毁。

今天仍然使用了短暂 smoke test 验证运行时关键链路，只是不把它们保留成正式测试套件。

8.4 RVO 群体避让

我们研究并明确跳过了 RVO。

• NavigationAgent/A*：解决从 A 到 B 应该走哪条路。
• RVO/ORCA：解决附近多个移动 Agent 怎样选择彼此不冲突的速度。
• Physics Collision：解决物体最终能不能相互穿透。

RVO 不是物理碰撞。它是一种 Local Avoidance（局部避让）。

没有在当前项目实现的原因：

• 场上只有少量敌人，收益不明显。
• 动作游戏敌人过度互相礼让，可能显得犹豫、绕圈、不敢进攻。
• 近战敌人更适合使用 Attack Slot、Reservation 或简单分离力。
• RVO 最适合专门的几十个 Agent 交叉移动实验场景。

RVO 不是“没用”，而是特定群众移动问题的工具，不应该因为引擎提供就默认打开。

8.5 Attack Slot、AnimationTree、对象池和正式资产管线

这些都没有在今天实现：

• Attack Slot：控制多个近战敌人谁能进入攻击位置。
• AnimationTree：处理更复杂的动画状态混合和 BlendSpace。
• Object Pool：大量重复特效时复用对象，避免频繁实例化/销毁。
• Audio Bus：统一管理 SFX/Music/UI 音量、压缩和效果。
• Sprite/Skeletal Animation：真实美术资产的导入和动画管线。
• Save/Load、设置菜单、输入重映射、导出发布。

当前项目的目标是建立这些系统出现之前所需要的架构语言。

9. 怎样驾驭 AI 生成游戏，而不是被生成结果驾驭

9.1 每一步先问五个问题

1. 这一阶段只增加了哪个新能力？
2. 新增了哪些 Node、Scene、Resource、Signal？
3. 谁拥有数据，谁有权修改数据？
4. 事件从哪里发出，经过哪里，最终由谁处理？
5. 如果要替换视觉、AI 或数值，需要修改哪些文件？

如果 AI 无法用一张目录树和一条事件流说明改动，通常说明边界还不清楚。

9.2 要求 AI 先给结构，再给代码

推荐顺序：

目标
→ 当前问题
→ 可选方案
→ 为什么选择其中一种
→ 将新增的目录/节点树
→ 事件流
→ 实现
→ 运行验证
→ 独立 commit
→ 下一步

这能防止 AI 一次生成大量互相耦合的脚本，而你只能“相信它”。

9.3 用小提交保存知识增量

今天的提交不是按“文件”划分，而是按能力划分，例如：

build component-based combat loop
introduce player state machine
drive attacks with custom resources
add state-driven enemy combat
add obstacle-aware navigation
add hit reactions and invincibility
drive player attacks with animation
add combat feedback and audio
add transient hit effects

小提交的价值：

• 可以比较某个概念加入前后的差异。
• AI 改坏时容易定位和回退。
• 每个 commit 本身就是学习章节。
• 避免“重构、功能、格式化、资源替换”全部混在一起。

9.4 让 AI 运行真实引擎验证

只检查 GDScript 文本不够。至少应分层验证：

1. git diff --check：格式和冲突标记。
2. Godot Editor headless load：资源路径、场景语法、脚本解析。
3. 运行若干帧：_ready() 和场景装配是否报错。
4. 针对关键事件写临时 smoke test：动画关键帧、time scale 恢复、对象销毁。
5. 视觉功能使用正常渲染窗口截帧检查。
6. 需要手感判断时由人实际操作。

AI 很适合验证“是否发生”，人仍需判断“是否好玩”。

9.5 要求解释名词，但把名词绑定到项目中的对象

只背定义很容易忘。更好的提问方式是：

不要只解释 Dependency Injection；指出当前项目中谁把什么注入给了谁。
不要只解释 Signal；画出本次命中的发送方和接收方。
不要只解释 Resource；比较 AttackData.tres 与 HitData 的生命周期。

9.6 防止 AI 过度架构

常见危险信号：

• 为只有一个调用者的简单函数创建五层抽象。
• 项目还没有第二种需求，就先建立庞大的通用框架。
• 用复杂设计模式替代清晰的数据结构。
• 因为引擎提供某功能，就自动加入 RVO、行为树、对象池等系统。
• 所有节点都通过全局 Singleton 通信。

判断标准不是“专业项目是否用过”，而是：

当前问题是否已经需要这层复杂度，它是否让下一次变化更容易？

9.7 一份可复用的 AI 协作提示词

请分阶段实现这个 Godot 功能，每阶段只引入一个主要新概念。

实现前说明：
1. 当前问题和目标；
2. 至少两种可行方案；
3. 选择方案及原因；
4. 将变化的目录树和节点树；
5. 新名词及其在本项目中的对应对象；
6. 完整事件流和数据所有权。

实现时：
- Gameplay、数据、AI 和表现尽量分离；
- 每个 gd 文件开头写一句文件职责；
- 不覆盖已有未提交修改；
- 使用 Godot 实际加载并做与风险相称的运行验证；
- 一个知识增量对应一个 Git commit。

实现后说明：
1. 改了什么；
2. 我应该先看哪些文件；
3. 在 Godot 编辑器中如何观察；
4. 哪些内容有意跳过；
5. 下一阶段是什么。

10. 关键词词典

Godot 基础

• Node：运行时基本对象。
• Scene：可保存和重复实例化的节点树。
• SceneTree：当前运行中的整棵节点树。
• Main Scene：项目入口场景。
• Lifecycle Callback：由引擎在特定阶段调用的函数。
• Signal：节点之间的一对多事件通信。
• Connection：Signal 与接收方法之间的连接关系。
• NodePath：在节点树中定位节点或属性的路径。
• res://：项目资源根路径。
• preload()：脚本解析时加载依赖。
• load()：运行时加载依赖。
• @onready：节点 ready 后再取得子节点引用。
• @export：把属性暴露给 Inspector 和场景装配。

数据与对象

• Resource：可保存、复用、由 Inspector 编辑的数据对象。
• .tres：文本 Resource 文件。
• RefCounted：通过引用计数管理生命周期、不必进入 SceneTree 的对象。
• PackedScene：尚未实例化的 Scene 资源。
• Instance：模板在运行时创建出的具体对象。
• Dependency Injection：由外部把依赖交给对象，而不是对象内部硬编码寻找或创建。
• Data-driven：逻辑读取数据配置，而不是把每个数值写死在流程代码中。
• Runtime Payload：某次事件临时携带的数据，例如 HitData。

时间、输入与状态

• Delta：上一帧经过的秒数。
• Fixed Tick：固定时间间隔推进规则。
• Timer：时间到期后发出 timeout 的节点。
• Input Action：对键盘、手柄等具体输入的语义抽象。
• Input Buffer：暂存尚未被规则 Tick 消费的输入。
• FSM：Finite State Machine，有限状态机。
• State Transition：从一个状态切换到另一个状态。
• Enter/Exit：状态取得或失去控制权时的生命周期。
• Cooldown：动作再次允许执行前的等待时间。

空间、物理与 AI

• Local Position：相对父节点的位置。
• Global Position：相对整个世界的位置。
• CharacterBody2D：由代码控制移动的 2D 角色物理体。
• Area2D：检测重叠和进入/离开事件的区域。
• Collision Layer：对象所属的物理类别。
• Collision Mask：对象希望检测的物理类别。
• Navigation Mesh/Polygon：描述 AI 可以行走的区域。
• NavigationAgent2D：查询目标路径和下一个路径点。
• Local Avoidance：避免附近移动对象的局部速度规划。
• RVO：Reciprocal Velocity Obstacles，互惠速度障碍。
• ORCA：基于速度约束的互惠避碰方法。
• Attack Slot：预约玩家周围的有限攻击位置。

战斗与表现

• Hitbox：能够造成命中的区域。
• Hurtbox：能够接收命中的区域。
• Knockback：击退。
• Hitstun：受击硬直。
• I-frames：无敌帧/无敌时间。
• Wind-up/Anticipation：攻击前摇。
• Active Frames：攻击有效帧。
• Recovery：攻击后摇。
• Animation Track：动画控制某个属性或方法的轨道。
• Keyframe：动画时间线上的关键值。
• Call Method Track：在动画指定时间调用方法的轨道。
• Hit Stop：命中瞬间的短暂停顿或极慢时间。
• Camera Shake：通过 Camera offset 等方式制造冲击反馈。
• AudioStreamPlayer2D：带世界位置的音频播放器。
• GPUParticles2D：GPU 驱动的 2D 粒子系统。
• Tween：随时间插值改变属性的轻量动画工具。
• VFX：Visual Effects，视觉特效。
• Transient Object：创建后短暂存在并自行销毁的对象。

算法与规则

• Grid：离散网格。
• Dense Array：适合固定、密集空间的数组表示。
• Candidate State：尚未提交的候选状态。
• Validate Before Commit：验证通过后才修改真实状态。
• Fisher–Yates Shuffle：均匀洗牌算法。
• 7-bag：每袋包含全部七种 Tetromino 的随机系统。
• Ghost Piece：显示方块预测落点的半透明影子。
• Hard Drop：立即移动到最终落点并锁定。
• Wall Kick：旋转碰壁时尝试位置修正。

11. 从这里继续时应该掌握的判断能力

读完这份总结后，不必记住每一行代码，但应该能够回答：

1. 一个 Godot 项目从哪里启动？
2. Scene、Node、Script 和 Resource 分别负责什么？
3. 哪些数据必须进入 SceneTree，哪些可以只是 RefCounted 模型？
4. Signal 的发送方、接收方和 Payload 分别是谁？
5. 为什么规则数据不应该只存在于画面节点？
6. 为什么移动或旋转应先验证候选结果？
7. 为什么 Hitbox、Hurtbox、Health 不合并成 Player/Enemy 的特例代码？
8. 状态机解决了什么控制权问题？
9. 导航和物理碰撞为什么要同时存在？
10. AttackData 和 HitData 为什么不能混为一谈？
11. 动画如何精确控制攻击有效帧？
12. Hit Stop 为什么必须使用不受 time scale 影响的恢复计时？
13. 临时特效为什么要自行销毁？
14. 哪些系统当前值得实现，哪些属于过早复杂化？
15. AI 生成改动后，应该如何从结构、事件流和运行结果三层验证？

如果这些问题能够用自己的话解释，就已经不再只是“让 AI 帮我写一个游戏”，而是在使用 AI 驱动一个自己理解的游戏工程。

12. 下一步

下一次可以先做一次 Action Arena 复盘：不看实现，从空白画出目录树、状态图和完整命中事件流，再用实际代码核对。

之后第四个项目应该进入一个新的领域，而不是继续堆 Action Arena 功能。可选方向：

1. 2D 平台跳跃：重力、地面检测、Coyote Time、Jump Buffer、Camera 跟随。
2. 程序生成地牢：随机、图结构、连通性、TileMap 和种子复现。
3. UI/背包专项：Control 布局、Drag & Drop、Resource 物品数据、存档。
4. 3D 小型探索：从 Node2D/CharacterBody2D 过渡到 3D 坐标、相机和光照。

选择标准仍然是：下一个项目必须带来新的核心知识，而不是只增加更多已经理解的规则。

代码语法最近可以稍微调整一下了

AI 把“执行门槛”大幅降低了，但没有消灭“认知门槛”。

完全不懂 → AI 很强，但你驾驭不了。
懂一点 → AI 突然变得极强。
很懂 → AI 又变成一个超级执行工具。

不是你驾驭不了 AI，而是你缺少“驾驭 AI 所需要的最小知识地图”。

真正的问题往往不是提示词不够好，而是你不知道这个领域有哪些东西。

关于学习

以前学习，是为了获得执行能力。
现在学习，越来越是在获得指挥能力。

我不一定记得怎么写，但我要知道：有什么、什么时候用、什么方案闻起来不对。

不要一上来就学知识，先学地图。

先知道名词，再理解关系，最后才补细节。

一旦知道关键词，AI 的能力就会被释放出来。

关于陌生领域

进入一个陌生领域，先问：这个领域由哪些模块组成？

再问：每个模块分别解决什么问题？

再建立“问题 → 模块 / 方案”的映射。

比“不知道怎么做”更危险的是“不知道有这个东西”。

最致命的不是不会踩刹车，而是根本不知道前面还有岔路。

关于经验

经验的价值，不只是让人知道怎么做，更是让人知道什么时候该踩刹车。

真正成熟的能力，是看到一种新方案时，能迅速判断它值不值得采用。

熟悉一个领域，不代表知道所有东西，而是知道哪些东西重要、哪些方向危险、哪些决策以后很难改。

关于方向

最危险的不是 AI 写错，而是它带着你在错误方向上高速前进。

不要只问“能不能做”，还要问“如果选错了，以后改起来贵不贵”。

如果这个选择是错的，6 个月以后，我要付出什么代价？

陌生领域里，不必追求第一次就选对，但最好保证选错以后还能回来。

关于 AI 生成代码

AI 每次生成几百行代码，真正的问题不是我能不能看完，而是我有没有漏掉一个根本不知道存在的关键词。

keep-alive 被遗漏了。
Shader 被遗漏了。
Resource 被遗漏了。
最麻烦的是：你甚至不知道自己遗漏了什么。

AI 可能用了一个重要模块，却没有告诉你它叫什么。

AI 也可能根本没有想到某个模块，而你因为不知道它存在，也不会追问。

AI 默认认为：没有被问到的内容，可以不说。

对陌生领域来说，这恰恰是最危险的。

关于学习与生成的边界

永远不要只拿走代码，也要拿走关键词。

不是所有 AI 生成的代码都值得学习。

真正值得留下来的，是那些会改变你以后判断方式的东西。

任何一个让我事后产生“原来还有这个东西”的概念，都值得记录下来。

它们往往不是技巧，而是整个生态里的关键节点。

最后几句

你真正害怕的，从来不是学习本身。

你害怕的是：在错误的方向上，高效率地前进。

以前我们害怕的是不会。
现在我们还要警惕：AI 帮我们绕过了本该发生的学习过程。

功能实现了，代码运行了，不代表认知也留下来了。

AI 把执行门槛打掉以后，真正暴露出来的，反而是认知门槛。

但继续往下想，我觉得还有一个更麻烦的问题。

不是 AI 不会做。

而是它太会做了。

快到什么程度呢？

你给它一个方向，它可以很快帮你搭起来。

再给一点要求，它继续往前推。

如果方向本来就是对的，这种感觉非常爽。

但如果方向从一开始就是错的，那就会出现一种以前没那么明显的问题：

你会在错误方向上，以一种非常高的效率前进。

这其实比“代码写错了”更麻烦。

代码写错，通常很快就能发现。

报错了。

测试不过。

页面坏了。

接口不通。

这些问题都比较显性。

真正麻烦的是：

代码没有错，功能也实现了，但架构方向错了。

而且因为 AI 很快，所以这个错误方向还会不断长大。

我自己做 GooseForum 的时候，就经历过这种事情。

一开始我希望它：

• Go 打包成单文件

• 对 SEO 友好

• 前端又尽量现代化

• 管理界面不能太难用

• 最好还能兼顾 No-JS

这些目标单独看都不奇怪。

但放在一起以后，其实天然就有冲突。

我一开始走过 SPA。

因为 SPA 很自然。

前后端分开，现代前端生态又成熟，管理界面也好做。

但很快 SEO 的问题就出来了。

如果我当时完全不知道 SEO 是什么，那这条路很可能就一路走下去了。

而且 AI 还会不断帮我把 SPA 做得越来越完整。

路由、状态管理、组件、接口，全都可以继续往上堆。

最后等我哪一天突然意识到：

“论坛这个东西，SEO 很重要。”

那就已经不是改几行代码的问题了。

后来我又走到了纯服务端渲染。

SEO 好了。

结构也简单。

和 Go 很搭。

但前端交互又开始变得难受。

再后来是 Alpine + 服务端渲染。

当时看起来也很合理。

轻。

简单。

不需要很重的前端框架。

但做着做着，又发现复杂管理界面并不适合。

再往后，才慢慢走到 Vue、Payload、Tailwind，再加 No-JS 兜底。

现在回头看，这个过程当然可以说是摸索。

但也可以说：

我是在不断发现之前不知道的约束。

SEO 是一个约束。

管理界面的复杂度是一个约束。

部署方式是一个约束。

No-JS 又是一个约束。

问题就在这里。

如果一个约束你根本不知道存在，你就不可能在一开始把它放进决策里。

而 AI 也不会自动替你承担这件事。

所以我后来越来越觉得，一个人在熟悉领域里的真正优势，可能根本不是“会写”。

而是：

他知道什么条件下，什么方案不该选。

比如我现在如果在比较熟悉的服务端领域里和 AI 协作，我通常会有一种比较明确的感觉。

这个规模没必要拆服务。

这里没必要上消息队列。

这个缓存做早了。

这个接口边界不对。

这个依赖以后会很麻烦。

很多时候甚至说不出特别完整的理论。

但就是会觉得：

“这个方向不太对。”

这种能力，其实就是经验。

你脑子里已经有了一套隐藏的约束系统。

AI 给出方案。

你会下意识拿它和这些约束比较。

然后决定：

继续。

修改。

或者直接踩刹车。

这也是为什么我觉得，在陌生领域里，最大的风险不是“我不会”。

不会其实很好解决。

AI 会写。

文档可以查。

例子可以看。

真正危险的是：

你没有刹车系统。

因为你不知道有哪些方案。

不知道什么时候该选哪个方案。

也不知道什么东西以后改起来特别痛。

这时候 AI 一旦开始高速生成，反而会放大问题。

所以我现在会特别在意一个东西：

这个决策如果错了，以后改起来贵不贵？

这个问题可能比“现在是不是最优”更重要。

比如有些东西选错了，问题不大。

UI 库不喜欢，换。

CSS 方案不喜欢，慢慢改。

某个动画实现不满意，也可以重做。

但有些东西就不一样。

数据模型。

模块边界。

部署方式。

核心资源组织。

这些东西一旦走得很深，再回头就非常贵。

所以陌生领域里，我现在越来越倾向于：

不要追求第一次选对，而是先保证第一次选错以后还能回来。

这和追求最优解是两回事。

你甚至可以先问：

如果这个方案 6 个月以后证明是错的，我要付出什么代价？

这其实就是一个很有价值的架构问题。

这件事放到 Godot 里也是一样的。

比如我以后让 AI 帮我做一个系统。

我现在不会只问：

“怎么实现？”

我更想先知道：

“有几种实现方式？”

“这个项目规模下，通常会选哪种？”

“哪些方案只是 Demo 里方便？”

“哪些做法以后扩展会比较痛？”

“有没有我不知道的模块，会改变这个问题的解法？”

因为这几个问题决定的是方向。

代码本身反而是后面的事。

以前大家总担心 AI 会不会写错代码。

我现在觉得，这已经不是最值得担心的问题了。

代码错了，通常还能发现。

真正麻烦的是：

它给你写了一套完全能跑的东西。

你觉得挺好。

AI 也觉得完成了。

项目继续往前推进。

一个月以后，你才突然发现：

一开始其实还有另一条路。

而那条路更适合你。

这时候真正浪费掉的，不是几百行代码。

而是你在错误方向上累积下来的整个结构。

所以如果说 AI 时代还有什么能力会越来越值钱，我觉得其中一个一定是：

知道什么时候该踩刹车。

而经验的价值，也越来越不像“我会写得比 AI 好”。

更像是：

我知道什么时候不应该让它继续写。

我的想象力，好像开始追不上使用 AI 之后的执行效率了。

以前不是这样。

以前更像是，我脑子里有很多想法，但是实现很慢。

想做一个东西，先查资料，再写，再调，再改。一个想法可能折腾几天，甚至更久。

所以以前真正限制我的，是执行能力。

但现在用了 AI 以后，这个关系有点反过来了。

你有一个想法，马上可以试。

试完觉得不对，再换一个。

以前积攒很久的“以后可以试试”，现在可能很快就被消耗掉了。

一开始我觉得，这可能是一个很有意思的新问题：

以前是执行力追不上想象力，现在开始变成想象力追不上执行力。

但后来我又觉得，这句话不完整。

因为这种效率其实是有边界的。

只要进入一个自己不熟悉的领域，问题马上就出来了。

我以前在 Vue 里就遇到过一个很典型的例子。

我当时想实现一个效果，大概是页面返回以后，希望之前的状态还在。

AI 当然也能帮我实现。

但是实现得很糟糕。

后来别人提醒了我一个词：

keep-alive

然后一下就解决得很好。

这件事后来我一直记得。

因为问题其实不是我不会写 keep-alive。

如果我知道这个东西存在，剩下怎么用，我完全可以交给 AI。

真正的问题是：

我根本不知道有这么个东西。

这个差别其实很大。

因为如果你不知道某个概念存在，你甚至不会去问它。

你只能描述表面需求：

“我返回以后，希望状态还保留。”

AI 可能会顺着你的描述，给你搞状态保存、恢复、缓存，甚至自己绕一大圈。

最后功能也许能跑。

但方向可能从一开始就不是最好的。

所以后来我越来越觉得：

AI 把执行门槛大幅降低了，但没有消灭认知门槛。

其实一年前，我自己就总结过一个很类似的观点：

完全不懂 → AI 很强，但你驾驭不了。
懂一点 → AI 突然变得极强。
很懂 → AI 又变成一个超级执行工具。

现在重新看，我觉得中间那个“懂一点”可能比我当时想得还重要。

因为这个“懂一点”不一定是会写。

甚至不一定是深入理解。

更像是：

我知道这个领域大概有哪些东西。

我知道一个问题通常对应哪个模块。

我知道可能有几种方向。

我知道什么方案一看就不太对。

只要有这些东西，AI 的能力一下就被放出来了。

但如果没有，就很容易出现一种情况：

AI 很快。

你也很快。

但你们两个一起在错误方向上跑。

这也是为什么我最近接触 Godot 的时候，会特别明显地感觉到这个问题。

比如着色器。

Shader。

如果我不知道这个东西存在，那我想做一个水面效果、描边、像素化或者某种视觉效果的时候，我可能根本不会问：

“这个是不是应该用 Shader？”

我甚至不知道这个问题属于哪个模块。

这和之前的 keep-alive 本质上是一样的。

最麻烦的不是不会。

而是：

你不知道自己不知道。

而 AI 又不会保证主动把所有相关概念都告诉你。

它可能用了一个重要模块，但没有告诉你这个模块叫什么。

也可能根本没用某个更合适的模块。

而你因为不知道它存在，也不会提出质疑。

所以我现在觉得，AI 时代学习一个新领域，第一件事可能已经不是学怎么写了。

而是先搞清楚：

这个领域到底有哪些东西？

比如 Godot，不是先去记 API。

而是先知道：

Scene、Node、Signal、Resource、Shader、Animation、Navigation、Physics……

先知道名字。

知道这些东西分别大概解决什么问题。

这样以后遇到需求的时候，脑子里至少会出现一个反应：

“这个问题是不是属于某个已有模块？”

而不是直接让 AI 开始生成代码。

这可能也是 AI 出现以后，“学习”这件事情发生的一个变化。

以前学习很多时候是在获得执行能力：

我要知道怎么写，因为我要自己写。

现在越来越像是在获得指挥能力：

我不一定要记住怎么写，但我要知道有什么、什么时候用、什么方向可能是错的。

所以现在回头看，我最开始那句“我的想象力开始追不上 AI 的执行速度了”，其实还可以再补一句。

真正麻烦的地方可能不是想象力。

而是当 AI 跑得越来越快以后：

我的认知地图，有时候开始追不上它的执行速度了。

而这件事，可能比“怎么写一个更好的提示词”重要得多。

现如今加上封装的dogdog，公司所有流程基本也很少打开浏览器，别人发的消息，也用内部im的cli直接让codex对接。

维护好agent.md更改-cr-commit-push-部署-测试后通知前端或者测试同学。

因为开的程序少了。所以总的内存用的更少了。

当然硬盘还是那么的不够用～

现在的合作方式已经很成熟：我告诉 Codex 一个功能点，带它看一次页面；Codex 负责分析请求、实现代码、补测试和文档。真正写代码的人不是我，单个功能的接入也已经足够高效。

但我还是开始疲惫。

问题不是实现太难，而是每天都要由我回答：

下一个应该封装什么？

今天提一个列表，明天提一个详情，后天再想起某个筛选。Codex 很能干，但它一直在等我点菜。我仍然是唯一的需求发现者、产品经理和启动按钮。

这不是编码疲惫，而是持续发起任务的疲惫。

从点菜变成审核

现在的流程是：

我想起一个功能
→ 告诉 Codex
→ Codex 分析并实现
→ 等我想起下一个

下一阶段应该改成：

我指定一个站点或业务范围
→ Codex 主动盘点页面和现有能力
→ 找出缺失的列表、详情、筛选和关联查询
→ 生成候选清单，标注价值、风险和成本
→ 我集中审核
→ Codex 批量实现

交互单位不再是一个按钮，而是一个页面或一段工作流。我的职责也从“每天想需求”变成“偶尔定方向、审候选”。

候选从哪里来

Codex 可以从几个地方主动发现下一步：

• 一次页面探索中尚未接入的筛选、分页、详情和关联入口。
• 使用频率高、但需要多次拼接才能完成的现有能力。
• 对话中反复出现的临时网页操作。
• 页面功能与已注册能力之间的缺口。

候选项需要说明用途、预期收益、读写属性、实现成本，以及仍需我确认的问题。

主动发现不等于自由扩张。写操作仍需逐项批准；查询型 POST 仍需判断副作用；运行时不能开放任意 URL；凭据和敏感数据不能进入候选记录、测试或日志。

下一步

不必一开始就建设复杂平台。先做三件事：

1. 建立候选能力清单，记录来源、价值、风险和待确认问题。
2. 每次探索页面时，默认盘点完整只读工作流，而不只实现当次点名的功能。
3. 定期根据使用记录和重复对话生成候选项，让我一次审核一组。

Codex 已经能够很好地分析和实现能力。现在真正缺少的，是一套不再依赖我逐个发起任务的演进机制。

我希望自己从每天点菜的人，变成偶尔确定方向和审核边界的人。

用ai/不用ai都是手段，而非目的。

如果用ai不能提高效率，反而会拖慢进度的场景应该做适当调整，比如让ai生成工具，而非ai接管全局。

相反小说/论文的目的是高质量的产出，如果质量很高，用不用ai有什么关系呢，茴香豆的四种写法重要吗？

LS6F-H4HK-WMBN

PP4J-B2S9-YDJ7

8VJ9-YY34-P77Z

TDUQ-7EAC-F26J
没抢到的宝子可以将注册的邮箱打在评论区
也可以https://t.me/Zooproxy7 联系这个

原生独享IP也只要几块钱，各个地区都有，官网没有的私我
号段：23.158.220.46
23.158.220.45
194.179.152.45
103.5.248.242

这边关于分组的配置可能得走 EXISTS 控制了。主要是GooseForum目前仍打算保持多分类这个能力。

一般来说，一个主题或者文章会绑定一个分类，但是实际情况是，如果一个文章，例如一个关于物理问题的数学公式，那么这个文章天然应该分别出现在物理/数学两个分类里面，就目前为止确实看到不少论坛因为限制了单类型，导致用户针对同一个文章发布多次的情况。

赶车～晚点补充

主题列表缓存

修复新主题发布后，其他用户返回主题列表仍看到旧数据的问题。

来源：功能建议、安装网站后的问题

Windows 安装与启动

降低非开发者第一次运行 GooseForum 的门槛。

可以处理：

• 在 Windows 发布包中提供 start.bat。
• 改进未传入 CLI 子命令时的提示。
• 提供最短启动流程说明。
• 明确 Intel、AMD 用户选择 x86_64。
• 明确 Windows ARM 设备选择 ARM64。
• 评估无参数运行时是否可以默认启动服务。

来源：安装网站问题

主题与权限模型

设计一套可以被分类、主题、用户组和未来圈子功能共同使用的权限模型。

第一阶段重点考虑：

• 分类查看权限。
• 分类发帖权限。
• 管理员和版主的权限规则。
• 多分类主题的权限合并规则。
• 首页、分类页、详情页和搜索结果统一过滤。
• 权限过滤对主题列表查询性能的影响。

暂时不急于实现完整圈子系统。权限底座稳定后，再评估用户创建群组、群组管理员、置顶、加精等功能。

来源：功能建议、下一次更新建议

1 有权限的类型不可做多分类。保持干净的边界。如果一个分类设置了可见权限，那么这个分类的主题只可选择一种类型且不可修改。同时增加隐私分类id字段。
2 分类做以下处理，隐私，隐私开启入口。
3 支持邀请和申请。开启入口的可以申请。隐私状态下关闭入口的只可邀请不可申请。
4 分类管理可以增加分类详情管理页面。查看分组成员。扩大版主权限。

用户密码重置

为管理后台增加安全的用户密码重置入口。

建议采用：

• 管理员在后台触发密码重置。
• 系统生成一次性重置链接。
• 通过邮件通知用户自行设置新密码。
• 记录管理员的重置操作。
• 后台不展示或保存明文密码。

现有 CLI 重置密码能力可以继续作为部署维护手段。

来源：功能建议

Markdown 编辑器增强

在保持 Markdown 为原始内容的前提下，降低普通用户的编辑门槛。

可以先支持：

• 标题。
• 粗体和斜体。
• 引用。
• 代码和代码块。
• 链接。
• 图片。
• 有序和无序列表。

后续再逐步支持：

• 附件。
• 投票。
• 数学公式。
• Mermaid。
• 代码高亮等客户端补充渲染。

编辑器预览需要持续通过测试规约与服务端最终渲染保持一致，不急于引入完整富文本编辑器。

来源：能添加圈子或群组功能吗

上传图片出现

image.png: HTTP 400

没选分类发表按钮就一直无法点击，找了一会未什么，交互体验需要优化~

[ 后端 / AI ] ──(生成纯逻辑与契约)──>  🧠 Headless 核心引擎 (状态、数据、校验)
                                              │
                                              ▼
                                    🔗 前端胶水层 (极简打通 / 神经反射)
                                              │
                                              ▼
[ 视觉 / UI ] ──(精简渲染)─────────>  🎨 纯 UI 皮肤 (Tailwind / 极简组件)

一句话总结：

• 后端/AI 负责长脑子（Headless 逻辑）。

• UI 负责长颜值（轻量皮肤）。

• 前端 只当最纯粹的胶水桥梁，把逻辑和皮肤丝滑缝合。

一、简单介绍：Zooproxy核心定位

Zooproxy是一款主打高可用、低延迟、高存活率的代理服务，适配个人开发者、轻量业务场景，支持动态住宅代理、静态代理等多种类型，覆盖节点范围广。区别于很多小众代理工具稳定性差、IP失效快、延迟波动大的问题，Zooproxy主打轻量化、易上手，无需复杂配置，新手也能快速落地使用，非常适合日常开发和轻量网络需求。

二、核心优势实测（对比多款同类工具）

这段时间持续压测使用，总结了几个比较亮眼的核心优势，也是我长期留存使用的关键：

1. IP存活率高，失效率极低：实测常规时段IP可用率能稳定在95%以上，不像部分代理工具批量获取后大半失效，大幅减少无效重试的时间成本。同时支持自动剔除无效IP，留存可用优质节点，使用体验更流畅。

2. 延迟稳定，波动小：无论是国内访问还是跨境轻量请求，延迟表现均衡，无突发高延迟、丢包等问题，适合需要稳定网络链路的爬虫测试、接口调试、数据采集等场景。

3. 配置简单，兼容性强：支持主流请求方式，适配Python、Go、Java等各类开发语言，同时兼容Proxifier等代理工具，全局代理、局部接口代理均可灵活配置，适配绝大多数个人开发场景。

4. 节点资源充足：拥有海量运营商原生IP资源，IP池更新频率高，重复率低，能够有效规避IP封禁、频次限制问题，爬虫、批量请求场景适配性极佳。

三、完整使用流程（新手零基础可上手）

给大家整理了一套最简单的实操步骤，全程无复杂操作，新手直接照搬即可：

1. 登录Zooproxy官方平台，根据自身业务场景选择对应代理类型（日常使用选动态代理、长期固定访问选静态代理）；

2. 批量获取代理IP列表，建议优先进行本地有效性检测，筛选低延迟、高可用节点；

3. 对接项目或工具，支持随机调用节点，单次请求自动匹配优质IP；

4. 依托平台自动容错机制，请求失败自动剔除失效IP，无需手动筛选维护节点。

四、实用使用技巧&避坑指南

结合实测踩坑经验，分享几个能大幅提升使用体验的小技巧，帮大家规避问题、提升效率：

1. 必做前置检测：批量获取IP后，不要直接投入使用，优先做一轮有效性+延迟检测，剔除超时、无效节点，避免影响业务稳定性。

2. 控制请求频次：轻量请求无需高频切换IP，固定优质节点短时使用即可；批量高频请求建议开启随机轮换，降低IP封禁概率。

3. 区分场景选代理类型：短期临时访问、爬虫采集选动态住宅代理，性价比更高；需要固定IP访问、账号常驻场景，优先静态代理，避免频繁换IP导致风控。

4. 规避高频并发滥用：个人轻量使用完全足够，切勿超大流量、超高并发暴力请求，容易触发风控限制，影响节点可用性。

五、整体总结

综合来看，Zooproxy是一款轻量化、高稳定、低门槛的优质代理工具，没有复杂的部署和配置流程，IP质量、延迟稳定性远超多数同价位小众代理服务，完美适配个人开发者、学生党日常开发、接口测试、轻量爬虫、网络访问等场景。

对于追求稳定、不想折腾节点维护、需要低成本解决网络代理需求的朋友，非常值得尝试。

最后欢迎各位坛友交流讨论！大家平时都用哪些代理工具？有没有更好的使用技巧？评论区一起交流避坑～

项目中使用ts了吗，用的谁家什么版本库

Codex:…(前面几个不重要的回复省略)

间接还是直接。

Codex:…(前面几个不重要的回复省略)

两个版本？不会有影响么。

Codex:…(前面几个不重要的回复省略)

亮点来了

正中眉心～

Whether your child is starting preschool or heading off to elementary school, lunch notes are a simple tradition that can create lasting memories.

Why Add a Lunch Note for Kids?

Children often look forward to discovering a surprise inside their lunchbox. A thoughtful lunch note can:

• Make your child feel loved and supported.

• Encourage positive thinking throughout the day.

• Ease first-day or back-to-school anxiety.

• Build confidence before a test or presentation.

• Strengthen your daily connection, even when you’re apart.

A handwritten message only takes a few seconds but can have a lasting impact.

What to Write on a Lunch Note

You don’t need to write a long letter. Short, cheerful messages work best. Here are a few ideas:

• Have an amazing day!

• I believe in you.

• You make me proud every day.

• Smile—you’ve got this!

• Can’t wait to hear about your day!

• You’re kind, smart, and brave.

• Remember to be yourself.

• Have fun with your friends!

• Good luck on your spelling test!

• I love you to the moon and back.

Adding a small drawing, heart, or smiley face makes the note even more personal.

Funny Lunch Note Ideas

Kids love to laugh! Try including a joke in their lunchbox.

• What do you call cheese that isn’t yours? Nacho cheese!

• Why did the banana go to school? Because it wanted to be a little smarter!

• What kind of tree fits in your hand? A palm tree.

• Why was the math book sad? It had too many problems.

• What do bees use to brush their hair? A honeycomb.

A simple joke can turn lunchtime into the best part of the day.

Inspirational Lunch Notes

If your child needs extra encouragement, motivational messages can help.

• Every day is a new adventure.

• Mistakes help us learn.

• Believe in yourself because I believe in you.

• Be kind whenever you can.

• Today is full of possibilities.

• Your best is always enough.

• Keep trying—you can do hard things.

• Be curious and keep learning.

Lunch Notes for Different Ages

Preschool

Young children enjoy simple messages with colorful drawings.

• Have fun today!

• Big hugs!

• You’re my sunshine.

• I love you!

Elementary School

School-age children appreciate encouraging words and jokes.

• You’re doing an awesome job.

• Make someone smile today.

• Have fun learning something new.

• You’re amazing!

Older Kids

As children grow, they often enjoy more mature and supportive messages.

• Good luck today—you’ve prepared well.

• Believe in your abilities.

• Keep being kind and confident.

• I’m proud of the person you’re becoming.

Make Lunch Notes More Fun

Here are a few creative ideas:

• Use colorful pens or markers.

• Add stickers or stamps.

• Include a small puzzle or riddle.

• Draw a simple cartoon.

• Add seasonal or holiday themes.

• Write messages on reusable lunch cards.

Reusable lunch note cards are especially convenient because they can be used throughout the school year.

Benefits Beyond Lunchtime

A lunch note for kids does more than brighten lunch. It helps create positive family routines and reminds children they are supported wherever they go.

Many parents say their children save these little notes for years, making them treasured keepsakes long after the school year ends.

Final Thoughts

Including a lunch note for kids is one of the easiest ways to make school lunches more meaningful. Whether you write a heartfelt message, share a funny joke, or offer words of encouragement, your child will appreciate knowing you’re thinking about them.

If you’re looking for creative ways to make lunchtime more enjoyable, explore our collection of lunch accessories, lunchbox ideas, and printable lunch notes to make every school day a little brighter.

如图

本版本开始除了一些编辑和ui优化，增加了Http事件通知支持，搭建GooseForum第三方通知频道提供一个切入点

HTTP 通知使用说明

HTTP 通知会在选中的站内事件发生后，异步向回调地址发送 POST 请求。这个功能是尽力通知，失败不会影响用户发帖、回复或注册。

支持的事件

• article.published
• article.updated
• comment.created
• user.signup
• moderation.report.created

请求格式

请求体固定为 JSON，Header 会带上事件名、投递 ID、时间戳和签名。

POST /your-webhook HTTP/1.1
Content-Type: application/json
X-Goose-Event: article.published
X-Goose-Delivery: 7c9f0b0fd4e2a111
X-Goose-Timestamp: 1710000000
X-Goose-Signature: sha256=...

{
  "event": "article.published",
  "timestamp": 1710000000,
  "data": {
    "articleId": 123,
    "title": "Hello GooseForum",
    "userId": 1
  }
}

签名校验

X-Goose-Signature 由 Secret、时间戳和原始请求体计算得出。

sha256 = HMAC_SHA256(secret, timestamp + "." + rawBody)

验签时请使用原始 body，不要先解析再重新序列化。

Node.js

import crypto from 'node:crypto'

function verify(secret, timestamp, rawBody, signature) {
  const digest = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex')

  return signature === 'sha256=' + digest
}

Go

func verify(secret string, timestamp string, rawBody []byte, signature string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(timestamp))
    mac.Write([]byte("."))
    mac.Write(rawBody)
    want := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(signature), []byte(want))
}

失败保护

同一个回调地址连续 3 次通知失败后，系统会自动关闭该地址，并标记为异常终止。重新启用并保存后会清空失败状态。

后面把附件功能做好，就太棒了

• 第一版支持版主功能的版本。版主当前可以参与封禁和解封主题。
• 优化了回复组件，支持用户在回复中上传图片。
• admin 组件风格统一化，优化之前部分有细节风格不同的问题。

2C2G都可以上几百QPS（目前还暂不支持cdn，只是页面的返回的qps）。

默认备份以及超轻量的空间占用

虽然只是列表里小小的一行，但对我这种个人为爱发电项目来说，还是挺开心的。一路边写边改，边踩坑边修，终于也算在 Go 生态的小角落里露了个脸。

GooseForum 是一个基于 Go、Vue 和 Tailwind CSS 的自托管论坛系统。目标也很简单：做一个部署起来不折腾、用起来清爽、后续还能慢慢折腾主题和社区玩法的论坛。

项目地址： https://github.com/leancodebox/GooseForum
Awesome Go： https://github.com/avelino/awesome-go

继续加油，继续慢慢打磨。

并且预设了4种配置，欢迎大家使用～

其实高数并不难，只要你把它放下，你的生活就会瞬间变得轻松很多。

因为项目是基于 tailwind 的。之前也有小伙伴说过字体小（我觉得刚刚好）。另外深色和浅色主题。所以规划一下走类似daisyui 的调色板配置这一套，但是还不能出现影响admin的情况，应该可以做到。先标记一下。后面打算走这个方向。老版本使用 daisyui 的时候能调整的从字体/颜色到圆角，还是很全面的。是个比较可行的方向。

现象是：已经授权过的老用户可以正常登录，但新用户点击 GitHub 登录后，会跳到 GitHub 的 404 页面。URL 看起来又很正常：

https://github.com/login/oauth/authorize?client_id=...&redirect_uri=...

一开始我以为是回调地址、client_id、OAuth 库版本或者 state 校验出了问题。但检查下来发现都不是。

真正的原因是：这个应用创建的是 GitHub App，而不是传统的 OAuth App，并且这个 GitHub App 默认还是 Private 状态。

Private 状态下，已有授权关系的账号可能还能继续用，但新的外部用户访问授权页面时，就会直接看到 GitHub 404。这个 404 很迷惑，因为它不像普通配置错误那样给出明确提示。

解决方式是在 GitHub App 设置里打开：

Settings -> Developer settings -> GitHub Apps -> 你的 App -> Advanced -> Danger zone -> Make public

也就是把 GitHub App 从 private 改成 public。

这里的说明是：

Make this GitHub App public
Allow this GitHub App to be installed on other accounts.

改完之后，新用户才能正常进入 GitHub 授权流程。

顺便也确认了一下，GitHub App 和 OAuth App 现在确实是两套东西。GitHub App 也可以用于用户授权登录，但如果是面向公开用户登录，就要注意它的公开状态、callback URL、权限配置这些地方。

这次问题最坑的地方在于：链接看起来完全没问题，代码也没明显错误，GitHub 只给了一个 404。以后如果遇到“老用户能登录，新用户 OAuth 直接 404”，可以优先检查应用是不是还处在 private 状态。

脱敏说明：本文已隐去真实公司域名、系统名称、仓库地址、表名、集群名、人员账号和业务数据。文中出现的“数据库平台”“日志平台”“发布平台”“工程平台”等均为抽象称呼，示例字段也经过泛化处理。

背景：浏览器不是所有办公查询的最佳入口

公司内部通常会有很多办公网站：数据库管理平台、日志平台、发布平台、工程管理平台、审批系统、工单系统、监控系统。它们承担了很多关键流程，但日常使用时常常有一个共同问题：用户只是想查一个结果，却不得不打开页面、等待前端加载、切换菜单、输入筛选条件、翻页、再复制几段信息。

这些操作本身并不复杂，很多时候背后只是几个 HTTP 请求。真正复杂的是：

• 登录态在浏览器里。
• 权限必须跟随用户本人。
• 每个系统的接口风格都不一样。
• 页面更新后，封装能力要能持续维护。
• 不能为了效率绕过安全边界。

于是我们开始做一个本机工具：把内网办公网站中高频、只读、低风险的查询动作封装成 CLI、MCP 和 Codex Skill。

它的目标不是替代原系统，也不是做一个大而全的内部网关，而是把“每天反复点页面查信息”的动作变成结构化、可复用、可被 AI 工具调用的本机能力。

核心原则：只读、本机、本人权限

这个项目一开始就定了三个边界。

第一，只做只读能力。

查询列表、查看详情、查表结构、看少量样例数据、搜索日志、查工程和集群映射，这些可以封装。审批、删除、发布、修改配置、创建分支等会改变服务端状态的动作，不做。

第二，在用户本机运行。

工具不部署成集中服务，也不使用共享账号。每个人在自己的机器上运行，访问范围由自己的账号权限决定。

第三，复用浏览器登录态。

用户已经在 Chrome 或 Edge 里登录了内部系统，工具就从本机浏览器读取目标域名的 Cookie，并用同样的 Cookie 发起只读 HTTP 请求。这样既避免重复登录，也避免在项目里保存密码或长期 token。

换句话说，这个工具不是“绕过浏览器”，而是“把浏览器已经拥有的本人登录态用于更快的只读查询”。

形态：CLI、MCP、Skill 放在同一个仓库

这个项目最终有三个入口，但核心实现只有一份。

-------------------+        +-------------------+
| CLI               |        | MCP Server         |
| dogdog action ... |        | tools/call         |
+---------+---------+        +---------+---------+
          |                            |
          +-------------+--------------+
                        |
              +---------v----------+
              | Action Registry    |
              | shared capability  |
              +---------+----------+
                        |
              +---------v----------+
              | Site Adapters      |
              | database/log/etc.  |
              +---------+----------+
                        |
              +---------v----------+
              | Intranet Websites  |
              +--------------------+

Codex Skill:
- 项目说明
- 接入流程
- 安全边界
- 站点文档索引

CLI 适合人直接调试和日常使用。比如：

dogdog capabilities
dogdog action database.find_table --json-input '{"table":"example_table"}' --json
dogdog action logs.query --json-input '{"keyword":"exampleKeyword","startAt":"2026-01-01 10:00:00","endAt":"2026-01-01 10:30:00"}' --json

MCP 适合接入 AI 客户端，让模型在用户授权的本机环境里调用这些只读能力。

Skill 则不是运行时逻辑。它更像一本给 Codex 看的项目手册：什么时候应该使用这个项目、怎么和用户一起浏览页面、怎么提取接口、哪些能力不能封装、文档写在哪里。

一个关键设计是：业务能力只实现一次，放在共享 action registry 里。CLI 和 MCP 都只是薄入口，Skill 只保存工作流和规范，不复制业务逻辑。

最关键的一步：打通浏览器登录态

内网工具最容易卡住的地方不是发 HTTP 请求，而是登录态。

如果让每个用户手动复制 Cookie，体验很差，也不安全。如果要求用户配置账号密码，更不合适。更自然的方式是读取本机浏览器已经保存的 Cookie。

以 Chromium 系浏览器为例，Cookie 存在本机 profile 目录里，但敏感值会被系统加密。macOS 上通常需要通过 Keychain 获取浏览器的 Safe Storage 密钥，再解密 Cookie；Windows 和 Linux 则分别有自己的系统密钥机制。

这个项目里的运行时策略大致是：

1. 根据站点配置确认允许读取的目标域名。
2. 在 Chrome / Edge 的常见 profile 中查找 Cookie 数据库。
3. 复制一份 Cookie 数据库到临时目录，避免直接锁住浏览器文件。
4. 只查询目标域名相关 Cookie。
5. 解密后拼成请求头。
6. 请求结束后不保存 Cookie，不打印 Cookie。

这里有一个很重要的小原则：工具不扫描所有 Cookie，不把 Cookie 当配置持久化，也不在日志里输出原始登录态。它只是按站点白名单临时读取、临时使用。

如何新增一个能力：和用户一起操作浏览器

这个项目的迭代方式也挺有意思。它不是靠猜接口，也不是先写一个抽象框架再慢慢填空，而是从真实页面出发。

一次能力接入通常这样走：

1. 用户说清楚目标：想查什么，页面在哪里，最后希望得到什么。
2. 用户和 Codex 一起打开浏览器，按日常方式操作一遍。
3. 观察页面展示和 Network 请求。
4. 区分核心接口、静态资源、埋点、菜单配置、噪音请求。
5. 找到最小稳定的只读 HTTP 请求。
6. 记录页面流程、请求参数、响应结构、只读判断。
7. 在站点 adapter 中封装成 action。
8. 同时验证 CLI 和 MCP 能看到这个 action。
9. 更新 Skill 和站点文档，方便下一次继续维护。

这个流程的价值在于：用户懂业务，Codex 擅长从页面和代码中抽象接口。两者一起走一遍真实操作，通常能很快把“网页里的按钮”提炼成“可复用的读能力”。

一个能力应该长什么样

一个好的 action 不应该暴露任意 URL，也不应该让调用方拼业务系统的内部参数。它应该接收业务语义明确的输入，返回结构化输出。

比如“搜索工程和集群映射”可以抽象成：

{
  "keyword": "example-service",
  "groupName": "",
  "includeUnavailable": true
}

输出则整理成：

{
  "total": 1,
  "items": [
    {
      "repository": "example-group/example-service",
      "moduleName": "example-service",
      "clusterName": "example_cluster",
      "moduleType": "service",
      "gitProjectId": 12345,
      "gitSshUrl": "git@example.internal:example-group/example-service.git",
      "searchStatusName": "available"
    }
  ]
}

调用者不需要知道底层页面是哪个弹窗，也不需要关心底层请求叫 moduleName 还是 keyword。这些都由 adapter 消化。

目前接入过的几类能力

为了验证这套方式，我们陆续封装了几类典型只读场景。

数据库平台：

• 查询当前用户可见的数据库实例。
• 按表名定位表在哪个库。
• 查询表结构。
• 执行受限的只读 SELECT。
• 预览少量数据。

日志平台：

• 查询业务域和集群枚举。
• 按关键词、时间范围、集群搜索日志。
• 对容易超时的大范围查询做分片限制。

发布 / 云平台：

• 查询集群列表。
• 查询集群分组。
• 查询实例信息。
• 查询集群总览。

工程平台：

• 搜索工程、仓库和集群之间的映射。
• 识别当前用户对工程的可用状态。

这些能力有一个共同点：它们都能显著减少打开浏览器、等待页面、复制信息的时间；同时它们又都是读取信息，不改变服务端状态。

安全边界比功能更重要

这个项目越好用，越需要克制。

我们给它设了几条硬规则：

• 不做写操作。
• 不暴露任意 URL fetch。
• 查询型 POST 必须逐个记录为只读接口。
• SQL 只允许单条 SELECT，拒绝多语句、DDL、DML 和危险关键字。
• 不保存密码、Cookie、token。
• 不在文档、日志、fixture 里留下真实敏感数据。
• 能力输出尽量结构化，必要字段脱敏。
• MCP tool schema 必须明确，不能让模型自由拼接内部接口。

尤其是 MCP 场景，工具越容易被模型调用，schema 和边界越要清晰。模型应该调用“查某张表结构”这样的业务能力，而不是拿到一个“请求任意内部 URL”的万能工具。

项目局部上下文：让工具越用越顺

实际使用中还有一个小发现：很多查询不是孤立的。

比如某个业务项目经常要查同一批数据库表、同一个日志集群、同一组服务和工程映射。如果每次都重新找这些关系，效率还是不够高。

所以项目里引入了“用户项目本地上下文”的概念：在用户自己的业务工程目录里维护一个轻量说明文件，记录稳定的、非敏感的关联信息，例如：

• 常查表名和数据库位置。
• 常用日志业务域、集群和关键词。
• 服务名、工程名、仓库名、集群名的映射。
• 排查问题时积累下来的路径提示。

这个文件不属于工具安装目录，也不存任何凭据。它更像一张本地索引，让 AI 和用户下次在同一个业务项目里工作时少走弯路。

为什么要把 Skill 放进同一个仓库

这个项目不只是一个 CLI，也不只是一个 MCP server。它还有一个很重要的维护问题：能力会越来越多，接入方式需要一致。

把 Codex Skill 放在仓库根目录，有几个好处：

• Codex 能直接知道项目规范。
• 新增能力时能自动找到文档、源码、测试入口。
• 运行时和开发期边界写得清楚。
• 项目分发时，CLI、MCP、Skill、文档一起走。

Skill 的职责不是实现功能，而是告诉 Codex：

• 这是一个只读内网工具项目。
• 每个能力要放进共享 action registry。
• CLI 和 MCP 不重复业务逻辑。
• 浏览器控制只用于开发期发现接口。
• 运行时必须自己读取默认浏览器登录态。
• 哪些东西不能提交、不能打印、不能封装。

这让项目在持续增长时不容易散。

一点工程取舍

为了启动快、维护轻，项目一开始没有引入复杂框架。Node 直接运行 TypeScript 源码，CLI 和 MCP 共享同一套 registry。站点 adapter 只是普通模块，按需注册 action。

这种选择有几个现实收益：

• 启动快。
• 调试简单。
• 新增站点成本低。
• 不需要先理解一个很重的插件体系。
• 后续如果要加测试、缓存、TUI 或本地 Web UI，也可以在核心 registry 上扩展。

当然，轻量不等于随意。真正要守住的是能力定义、认证读取、安全策略、文档记录这几条主线。

总结

这个项目的核心不是“把网页接口扒出来”这么简单，而是建立一套可持续的本机只读能力生产方式：

• 用户在浏览器里完成真实操作。
• Codex 协助观察页面和请求。
• 把最小稳定的读接口封装成 action。
• CLI 和 MCP 共享能力。
• Skill 记录流程和边界。
• 运行时复用用户自己的浏览器登录态。
• 权限始终跟随用户本人。

它解决的是一个很日常、但很有价值的问题：让内部工具从“只能在浏览器里慢慢点”变成“可以被命令行、AI 和自动化上下文可靠调用”的结构化能力。

更重要的是，这条路没有要求重建所有系统，也没有要求目标系统立刻提供完美开放 API。它只是从高频只读场景开始，一点点把已经存在的页面能力沉淀成更快、更稳、更适合协作的本机工具。

这可能是内部效率工具最舒服的一种形态：小、快、克制，但能不断长出新的爪子。

原文：https://github.com/openclaw/openclaw/releases/tag/v2026.6.1
发布时间：2026 年 6 月

OpenClaw 最新版本 2026.6.1 已经上线。这一次更新没有 headline-grabbing 的「新功能」，但每一个改进都精准地打在运行时的痛点上——从代理恢复、渠道稳定性，到 Skill Workshop 的完整工作流，再到数十项边界情况的安全加固。对于把 OpenClaw 当作日常基础设施的用户来说，这是一次值得认真升级的版本。

一、核心改进：运行时更「抗揍」

1. 代理与 CLI 运行时的故障恢复

• 被打断的工具调用、过期的会话绑定、压缩交接（compaction handoff）以及媒体重试，现在都能更干净地恢复而不会留下脏状态。 相关 PR：#88129、#88136、#88141、#88162、#88182

• Codex 运行时修复了包括：直播会话锁、CLI 工具转录恢复、ACP 元数据持久化、真实工具结果优先于合成修复输出、以及被中止的 app-server 句柄清理。 相关 PR：#88405、#88724、#88730 感谢 @vincentkoc

2. 渠道与移动推送的稳定性

• Telegram、WhatsApp、iMessage、Slack、Discord、Microsoft Teams、Google Chat、Google Meet 和 iOS 实时 Talk 的请求/重试计时器全面加帽，减少因超时无限挂起导致的「消息发不出去」或「会话假死」。 相关 PR：#88096、#88105、#88183、#88231

• WhatsApp QR 登录的 408 超时现在会自动重试。

• iOS 支持了原生 iPad 布局，并新增托管推送中继（hosted push relay）和更可靠的 WebSocket ping 路径。

3. 请求与下载的边界防护

• 对 provider 和 plugin 的计时器、重试、OAuth/设备码生命周期、媒体下载、本地服务探测、生成内容轮询等路径，全面增加了上限保护，防止单个任务「hang 住」整个运行。
• 覆盖范围包括 OpenAI、Runway、xAI、MiniMax、BytePlus、DashScope、FAL、OpenRouter、Google、Vydra、Comfy 等 provider 的生成媒体下载。

二、新功能：Skill Workshop 正式可用

Skill Workshop 不再只是概念，现在拥有完整的 Control UI 工作流：

• 提案列表：查看待审核的 Skill 提案，支持今日视图和看板视图切换。
• 可修订：在审批前可以就地修订提案，带有版本化的日期 frontmatter。
• 支持文件：提案可以携带经扫描、哈希校验和回滚保护的支持文件。
• 审核操作：通过 CLI 或 Gateway 对提案执行 apply、reject、quarantine。
• 文件预览：可搜索的文件预览模态框，配合会话交接功能。
• 多语言：完整的 locale 覆盖。

相关文档与实现：

• Skill Workshop 官方指南 —— 涵盖治理式 Skill 创建、可审核提案、CLI/Gateway 操作、审批策略与恢复。 感谢 @shakkernerd 和 @vyctorbrzezowski
• 核心 Skill 索引与运行时加载统一：Skill 的加载、状态、过滤和 prompt 格式化现在集中管理。
• Codex app-server 的 prompt 中现在会注入 Skill Workshop 指引，当 skill_workshop 可用时自动生效。

三、Workboard 与编排能力

• Workboard：新增多代理规划与运行跟踪的编排原语（orchestration primitives）和代理协调工具。 相关 PR：#87469
• 任务驱动的看板运行（task-backed board runs）和任务评论在编辑模态框中展示。
• SecretRef 插件清单：提供 provider 集成清单契约，并提取共享的 LLM 核心包供 provider/plugin 复用。 相关 PR：#82326、#88117

四、插件与 Provider 生态更新

官方插件独立发布

• Tokenjuice 作为官方 @openclaw/tokenjuice 插件独立发布，支持 npm 和 ClawHub 安装。
• GitHub Copilot 作为官方 @openclaw/copilot 插件独立发布，同样支持 npm 和 ClawHub。

Provider 支持扩展

• MiniMax M3 模型正式支持。 相关 PR：#88860
• Google 默认解析到 google-generative-ai，Vertex 静态目录行修复。
• OpenRouter 增加 SQLite 模型缓存。
• Copilot Claude 1M 上下文能力保留。
• Foundry 推理元数据对齐，DeepSeek V4 thinking 参数在 Foundry fallback 时跳过。
• OpenAI 响应回放（replay）防护，避免 disabled Responses store 时仍携带 replay id。

五、性能与状态持久化

• SQLite 迁移：iMessage 监控状态、入站队列、插件安装索引全面迁移到 SQLite，重启和本地监控恢复时减少重复文件扫描。 相关 PR：#88794、#88797
• 内存优化：QMD 更新/嵌入写入按 store 串行化、Linux 文件监听 fan-out 减少、临时文件读取重试、元数据清理、Linux 原生 watcher 在目录重建后自动重连。 相关 PR：#89185、#89188、#85351 感谢 @RomneyDa 和 @NianJiuZst

六、Control UI 与聊天体验

• Dreaming 标签：新增代理选择器，支持在 Dreaming 状态、日记和日记动作中传播所选代理。 相关 PR：#78748 感谢 @stevenepalmer
• Composer 体验：聊天 composer 控件更克制（calmer），本地草稿在输入时保持本地状态，发送后自动清空。流式增量渲染跳过 markdown 工作，首输出延迟（first-output latency）可追踪。 相关 PR：#88772、#88825、#88998、#89030、#89106 感谢 @vincentkoc 和 @sallyom
• 错误可见：Gateway 聊天失败现在在 Control UI 中显示为可见的助理消息，而非不可见的错误状态。
• 工具卡片：折叠的工具卡片现在显示工具名称和动作，而非通用的输出文本。 感谢 @shakkernerd

七、CI、发布与诊断

• 发布候选读取、Beta smoke REST 调用、插件 npm 验证、变更日志恢复、跨 OS 进程组、Kitchen Sink 就绪探测、Telegram 凭证超时、Control UI i18n 生成、Vitest 路由等全面加帽。 相关 PR：#88127、#88137、#88155、#88160、#88966 感谢 @RomneyDa
• 磁盘空间健康检查加入 Doctor 工具。
• 更新流程：当缺失的外部插件修复下载卡住时，核心更新保持非阻塞；但已安装活跃插件的 payload smoke 失败仍会阻塞。
• 插件安装失败时提供更清晰的修复路径指引。

八、值得关注的修复

• CLI：openclaw agents add 不再强制实时验证 provider 目录，添加辅助代理不再依赖目录可用性。 相关 Issue/PR：#76284、#88314 感谢 @zhangguiping-xydt
• WSL 剪贴板：通过 shell 桥接 WSL 剪贴板操作。 相关 PR：#88764、#88689 感谢 @alexzhu0
• Cron：SQLite cron 迁移兼容旧版运行日志表、归档作业存储、诊断 cron 名称和旧版一次性 delete-after-run 行为。 相关 PR：#88285
• Skills：跳过来自过时持久化快照的禁用 Skill 环境覆盖，防止禁用 Skill 的 apiKey SecretRefs 中止嵌入或渠道回合。 相关 Issue/PR：#79072、#79173 感谢 @zeus1959

总结

OpenClaw 2026.6.1 的改进关键词是 「韧性」 和 「治理」：

• 韧性：代理恢复、渠道超时、媒体下载、生成内容轮询等边界情况全面加固，系统更难被「一个异常任务」拖垮。
• 治理：Skill Workshop 从概念变为完整可用的审核工作流，配合 SecretRef 清单和插件独立发布，生态治理更加规范。
• 体验：Control UI 的聊天 composer、Dreaming 标签、错误可见性等改进，让日常交互更顺畅。

如果你正在运行 OpenClaw 作为基础设施，这个版本值得优先升级。

完整变更列表与 PR 链接： https://github.com/openclaw/openclaw/releases/tag/v2026.6.1

减少四周留白

核心亮点

🧠 Agent 运行时更稳定

• 子代理保持 cwd/工作空间隔离
• 钩子上下文保持 prompt-local
• 超时中止时释放会话锁，避免过时的重启续传
• Codex 应用服务器/辅助器故障不再摧毁共享运行时状态

🔐 渠道交付和会话身份更安全

• 覆盖出站插件钩子、Matrix 房间 ID
• iMessage 反应/批准、Slack 最终回复、Discord 恢复工具警告
• 运行时配置消息操作、WhatsApp 个人资料认证根
• Telegram 轮询、Microsoft Teams 服务 URL 信任检查

📱 移动端和聊天界面刷新

• iOS Pro UI 全面刷新
• 托管推送中继默认设置
• 实时 Talk 标签播放
• Gateway 聊天传输、引导、Talk 权限
• WebChat 重新连接交付、会话选择器行为优化

🛡️ 输入验证更严格

• 浏览器工具超时、视口/标签索引、Gateway 端口
• cron 重试处理、Discord 组件 ID
• 模式数组引用、Telegram 回调页面、渠道进度回调等现在更早拒绝畸形值

🤖 模型和媒体覆盖扩展

• Claude Opus 4.8、Fal Krea 图像模型
• NVIDIA 精选模型、MiniMax 流媒体音乐响应
• 加密 PDF 提取、语音模型目录
• GitHub Copilot 代理运行时、Codex Supervisor 插件

🔧 CLI / 认证 / 诊断更可靠

• 畸形数字/版本选项被拒绝
• 工作区 dotenv 提供商凭据被忽略
• OAuth/令牌生命周期和本地服务启动请求被限制
• 代理认证健康标签更清晰
• 旧版 api_key 认证配置文件迁移到规范形式

主要变更

状态与子代理

• 在状态输出中显示活动子代理详情

Diffs 与语言包

• 拆分默认语言包并扩展默认 Diffs 语言覆盖

ClawHub 插件市场

• 添加插件显示名称
• 技能验证和信任界面

iOS 移动端

• 刷新开发应用
• 支持 Pro Command、Chat、Agents、Settings
• 托管推送中继默认设置
• 实时 Talk 播放

文档更新

• 澄清 Codex 计算机使用设置
• 粘贴令牌 stdin 认证设置
• macOS Gateway 睡眠故障排除
• 原生 Codex 钩子中继恢复
• 容器模型认证等

PDF 与工具链

• 使用 ClawPDF 进行 PDF 提取
• 支持加密 PDF 提取
• 在代理工具结果中显示 MCP 结构化内容

新模型与提供商支持

• Claude Opus 4.8
• Fal Krea 图像模型
• NVIDIA 精选模型目录
• MiniMax 流媒体音乐
• 提供商支持的语音模型目录

GitHub Copilot 与 Codex

• 添加 GitHub Copilot 代理运行时
• Codex Supervisor 插件包

插件架构

• 将 GitHub Copilot 和 Tokenjuice 外部化为官方按需安装插件

Workboard 代理协调

• 添加代理协调工具，用于跟踪和移交活动代理工作

Discord 集成

• 在进度草稿中显示评论，以便实时 Discord 运行展示有用的进行中上下文

插件 SDK

• 添加回复负载发送钩子
• SDK 声明扁平化包类型

策略与合规

• 添加策略比较
• 入站渠道合规性检查
• 沙箱姿态合规性检查

下载与验证

macOS

npm

npm install -g openclaw@2026.5.28

• npm 包页面：https://www.npmjs.com/package/openclaw/v/2026.5.28
• registry tarball：https://registry.npmjs.org/openclaw/-/openclaw-2026.5.28.tgz
• 完整性：sha512-p7jGN9wzCrqEvHNI6Y7+eh6DWoYDzJ1iQGKTm8xqQ2uQ9/2mY1CCf87WoZeb0+m3eHKSGchlI3tN33fE1lMtEA==

依赖证据

• openclaw-2026.5.28-dependency-evidence.zip (60.4 KB)

发布验证

• npm preflight：https://github.com/openclaw/openclaw/actions/runs/26692293231
• 完整发布验证：https://github.com/openclaw/openclaw/actions/runs/26692292739
• 发布检查：https://github.com/openclaw/openclaw/actions/runs/26692419552
• npm Telegram 包 E2E：https://github.com/openclaw/openclaw/actions/runs/26692496669
• macOS 预检/签名/公证：https://github.com/openclaw/releases/actions/runs/26694473893
• macOS 验证：https://github.com/openclaw/releases/actions/runs/26695381614
• macOS 发布/appcast：https://github.com/openclaw/releases/actions/runs/26695523506

appcast 订阅：https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml

标签： v2026.5.27 | 正式版本 | 非预发布

核心亮点

• 安全性升级 — 群组提示文本从系统提示中隔离、重复点主机名规范化、阻止有副作用的命令包装器、拒绝不安全的 Node 运行时环境覆盖、禁止无认证 Tailscale 暴露，节点/设备角色审批现需管理员权限。（#87144, #87305, #87292, #87308, #87146）

• Codex 运行时更稳 — 运行时模型优先解析、工作区内存通过工具路由、共享应用服务器客户端在启动和辅助进程故障后存活、原生 Hook 中继生成在重启和回退时保持、避免错误的运行时实时切换。（#87383, #87403, #87375, #72574, #87428）

• 网关和回复路径加速 — 会话读取、插件元数据指纹、认证环境快照、自动启用插件配置、工具搜索目录等减少热路径重新发现，可见回复不再继承隐藏清理超时。（#86439, #87044）

• 更多提供商和模型支持 — OpenAI 兼容嵌入提供商成为核心、DeepInfra 目录浏览加载完整凭证感知模型集、Pixverse 新增视频生成和 API 区域选择、VLLM 思考参数接入、Claude CLI OAuth 覆盖层支持 PI 认证配置文件、裸 Anthropic 模型 ID 直接可用。（#85269, #84549, #87167）

• 通道投递更稳 — Telegram sendMessage 使用持久出站投递、iMessage 抑制重复原生执行审批提示和发送、Slack 在延迟清理期间保留最终回复、Matrix 提及预览/终稿更严格、QQBot 回退审批按钮遵循斜杠命令认证、Discord 公会请求检查更紧、Google Chat 在 DM 中停止线程发送。（#87261, #87154）

主要变更

• 内存： 新增核心 OpenAI 兼容嵌入提供商，支持本地和托管的 OpenAI 风格端点，含配置、诊断和文档支持。（#85269）
• 插件 SDK： 标记内存专用嵌入提供商注册为已弃用兼容性，并在插件兼容性诊断中显示非捆绑使用。（#85072）
• 提供商： 新增 Pixverse 视频生成提供商、API 区域选择、文档和外部插件打包支持。
• DeepInfra： 用户在引导期间浏览模型时加载完整模型目录，保留配置的 API 密钥目录，刷新媒体/视频默认值，保持价格/默认模型元数据对齐。（#84549）
• 插件 SDK： 公开插件审批操作元数据，停止从公共 SDK 表面导出 Vitest 测试助手。（#87120）
• 通道 SDK： 将通道消息兼容性移入核心，移除旧通道回合运行时别名，保留插件的运行时目录 Markdown 元数据。
• ClawHub： 添加插件显示元数据，使目录/包列表使用更简洁的名称。（#87354）
• 代理： 将心跳运行时模板从文档资源中拆分，并为旧版心跳模板内容添加兼容性修复。（#85416）

修复汇总

• 安全/内容边界（9 项）— 系统提示外路由不信任群组提示、规范化重复尾部主机名点、阻止有副作用的命令包装器、拒绝不安全 Node 运行时环境覆盖、拒绝无认证 Tailscale 暴露、阻止不信任 Microsoft Teams 服务 URL、强制 /allowlist configWrites 来源策略、门控 QQBot 回退审批按钮、要求管理员进行节点/设备角色审批。
• Codex（9 项）— 运行时模型优先解析、工作区内存通过工具路由、保留共享应用服务器客户端、保留原生 Hook 中继生成、保持原始推理/源回复保护完整、报告隔离动态工具、保持尝试看门狗在排队终端回合时启用、Codex OAuth 压缩通过 OpenAI-Codex 路由。
• 代理/运行时（12 项）— 避免会话事件队列自等待、限制压缩唤醒和引导重试、保留待处理错误诊断的优雅、避免错误的 Codex 运行时实时切换、避免陈旧的重启继续重用、保留会话回退错误、抑制重复的 Claude CLI 技能提示、保持活动用户回合前的运行时上下文、剥离陈旧的 Anthropic 思考、隔离不受支持的工具模式、安全恢复已完成的写入超时、超时中止时释放保留的会话写入锁。
• 回复/会话投递（5 项）— 保持可见回合准入无界、在最新目标上保留可见回退投递、保留桥接 Hook 上下文、按通道语法分类直接回退目标、在桥接模式下报告审批决议。
• 通道（7 项）— Telegram sendMessage 操作回复持久化、抑制 iMessage 重复原生执行审批提示和发送、保持 iMessage 审批轮询在拒绝反应后存活、Slack 保留延迟清理期间的最终回复、Matrix 提及预览/终稿不提及且正常投递、忽略嵌入文件名的 Matrix ID、抑制成功回复中恢复的 Discord 工具警告伪影、抑制 Google Chat DM 中的线程发送。
• 内存（2 项）— 在非常退出后恢复 QMD 搜索 JSON，尽可能通过 Codex 工具路径保持工作区内存路由。
• 提供商/模型（9 项）— 在 OpenAI 兼容聊天完成中转发缓存令牌使用、为 PI 认证配置文件加载 Claude CLI OAuth 覆盖层、发送裸直接 Anthropic 模型 ID、连接配置的 VLLM 思考参数、尊重 OpenAI 兼容缓存保留、规范化 OpenAI 响应重放工具 ID、在没有缓存目录的情况下解析 OpenAI gpt-5.5、保留 retry-after 回退处理、限制 GitHub Copilot 认证请求。
• 网关/性能（8 项）— 借用只读会话元数据和活动会话工作区存储、缓存当前/稳定插件元数据指纹、缓存自动启用插件配置、精简元数据身份缓存、信任当前元数据生命周期缓存、稳定隔离 cron 提示缓存亲和性、持久化模型认证配置文件后缀、排空探测客户端关闭。
• CLI/帮助/配置（5 项）— 拒绝松散或畸形的数字选项（网关超时、模型限制、目录限制、消息选项、Webhook、部分值）、尊重子命令版本选项、正确路由生成/根/插件帮助目标、保持技能 JSON 输出自然刷新、在根帮助中保持插件描述符加载安静。
• 插件状态/工具搜索（4 项）— 插件行达到上限时驱逐当前命名空间、重用未更改的工具搜索目录、对齐发布目录重用包装器、保持回退工具警告不提及。
• 安装/包/发布（8 项）— 匹配 npm globstar 排除、在清单中尊重 dist 包排除、省略解包的测试助手、跳过 Homebrew 直到 macOS 包需要它、打包 Docker 运行时工作区模板、在完整验证期间对 Docker 运行时模板进行冒烟测试、合并嵌套 shrinkwrap 覆盖引脚、保留分支 shrinkwrap 引脚。
• E2E/QA/Crabbox（10 项）— 限制 Telegram、Open WebUI、ClawHub、Matrix、工具搜索、MCP、网关网络、捆绑运行时、厨房水槽、Codex 媒体、配置重载和代理回合断言等待；Windows 目标优先选择 Azure；重新初始化无效更改门 git 目录；完整同步稀疏容器运行；空显式测试请求失败。

下载资源

• npm 包：openclaw@2026.5.27 — registry
• 完整发布 CI 报告：evidence/2026.5.27/release-evidence.md
• appcast：appcast.xml

GitHub Release： https://github.com/openclaw/openclaw/releases/tag/v2026.5.27

TL;DR

这次更新没有花哨的新功能，但每一个细节都在让 OpenClaw 变得更好用——启动更快、响应更及时、语音更靠谱、审批更方便，而且安全边界更严格。如果你之前觉得 Gateway 启动慢、移动端审批麻烦、或者语音对话容易被打断，这次更新值得认真看看。

一、性能：Gateway 和回复终于不再"热身"了

过去的 Gateway 启动有点像老式汽车：点火之后要预热一圈，反复扫描插件、频道、会话、成本索引……现在这些元数据被缓存起来，启动时直接复用，不再重复发现。

更妙的是，可见回复和后续工作被拆开了。你看到的回复先出去，慢一点的收尾工作在后台继续。主观感受就是：字出来得更快了。

相关 PR: #84649, #85843, #86517, #86678

二、Transcripts：所有对话都有了"记忆"

这次把转录 (Transcripts) 做成了核心基础设施：

• 会议摘要可以直接回溯原始转录
• CLI、WebChat、媒体输入、Codex 镜像……所有用户输入统一走一条更可靠的持久化路径
• 附带来源元数据、媒体溯源、清理后的文本

简单说，以后复盘对话、做总结、或者排查问题，都有据可查，不再依赖零散的日志拼凑。

三、频道：移动端审批终于不用打字了

Signal / iMessage / WhatsApp 现在支持反应式审批——直接在消息上点 👍 就能批准敏感操作，不用输入 /approve 命令。这在手机上用起来舒服太多了。

其他频道也有实质性改进：

相关 PR: #85894, #85952, #85477

四、语音：Talk 模式真正可用了

实时语音 (Talk) 这次做了大量底层重构，核心收益：

• Web UI 和 Discord 语音里可以实时查看、引导、取消 Talk 运行
• 唤醒词识别更宽容，但不会让环境语音随便触发代理
• barge-in（打断）检测更聪明，知道什么时候该听你的
• 发言者归因在 Discord 语音中更准确

如果你在用 OpenClaw 做语音助手，这次更新会让体验从"能跑"变成"好用"。

五、安全：把能堵的漏洞都堵了一遍

虽然枯燥，但很重要：

• SSRF 防护：浏览器快照读取前先过策略检查
• 提示注入防护：系统事件文本无法伪造嵌套 <<< 标记
• 外部内容隔离：web_fetch 获取的文本默认包装为不可信外部内容
• ClickClack 白名单：入站消息先过发送者允许列表，再进代理
• 设备令牌轮换：过期/失效的令牌直接拒绝 RPC
• 工具调用文本清洗：序列化的工具调用内容不会泄露到最终回复

贡献者：@zsxsoft, @ttzero25, @mmaps

六、Codex 与提供商：少一些 provider-specific 的坑

• Codex CLI 升级到 0.134.0
• OpenAI 采样参数（temperature、top_p 等）现在能正确透传到 Gateway
• xAI 使用限制错误现在会明确暴露给用户
• Ollama 的 top_p 做了归一化，避免贪婪采样异常
• 动态工具模式加了保护，防止不受支持的配置把代理带崩

七、其他值得注意的改动

结语

这次更新的关键词是**“打磨”**——没有惊天动地的新功能，但启动速度、响应体感、语音稳定性、移动端体验、安全边界，全都有实质性的进步。对于日常高频使用 OpenClaw 的人来说，这是最舒服的一类更新。

完整变更列表请见 GitHub Releases： 🔗 https://github.com/openclaw/openclaw/releases/tag/v2026.5.26

发布于 2026-05-27 · OpenClaw Team