starry / 手册

维护这本手册

本地文件与网页编辑共用一份 MDX，日常只改内容与关系，沿用共享版式和图表。

手册维护
本页内容5 节

用网页或本地文件修改

在自己的电脑运行 pnpm dev，通过右上角“编辑内容”进入本地网页编辑器，文章标题下的“编辑本页”直接进入当前文章。选择文章，修改标题、简介、所属层级、阅读顺序与正文，保存后回阅读页查看。

本机网页编辑与即时预览地址为 http://127.0.0.1:3210。本地静态预览 http://127.0.0.1:3211/StarryManual/ 也提供这两个编辑入口，跳转到同一台电脑的网页编辑器；编辑服务需要保持运行。静态预览读取构建产物，保存后可先在 3210 查看，重新构建才会更新 3211。

同一篇文章也可以直接在 content/articles/ 编辑 MDX。网页编辑器与文件编辑没有两份内容，不自动 Git 提交或推送。

手册导览是普通文章，内容位于 content/articles/start-here.mdx。侧栏的模块选择菜单和当前模块功能树从共享登记与文章层级自动生成，不另建全站功能总览页。

首页的“推荐站点”可以在网页编辑器的“首页推荐站点”中修改名称、简介、网址和排列顺序，也可以直接编辑 content/site-links.json。两种方式使用同一份数据，卡片自动排版，无需改页面代码。

GitHub Pages 提供静态阅读、搜索、图谱与蓝图工具；可视化编辑器在本地运行。也可以用 GitHub 文件编辑器修改 MDX，再由构建流程发布。带登录的在线可视化编辑仍需另行配置。

先写读者要完成的任务

每篇总结已有功能、实际用法和已确认约束，接口名、单位与默认值从当前代码核对。按用户提供的图示或现有代码说明，不自行补出新功能、架构方案或示例组件。接口片段里的占位类型明确标注，不能写成项目已有类型。

新增文章沿用所属模块的稳定标识前缀，例如 input-。新模块在共享导航中登记一次，后续文章按前缀归组；尚未单独归组的文章显示在“项目系统”，无需创建空白占位页。

用 section 表示从外到内的子模块或功能分区。例如 section: [行为执行, 树后端] 会生成“AstraAI → 行为执行 → 树后端 → 当前文章”的目录。网页编辑器中的“所属层级”填写同样的两项即可，模块总览留空。

侧栏、模块入口的功能目录、当前位置、图谱的模块与功能筛选共用这份归属。模块由文章网址前缀自动识别，section 表示子模块路径，order 决定同一目录中的阅读顺序；新增笔记不必另填文章类型、图谱分组或配色。

小功能可在同一篇文章中说明用途、操作与机制；复杂子模块再按实际需要拆页，不为凑齐“架构／使用／参考”生成重复或空白文章。

具体模块的调试操作、状态含义、异常原因和检查路线集中在该模块的“调试与排查”中。例如 Gamepad／Actions 的操作、注入边界与输入诊断统一见 Input 调试与排查。HaloDebug 维护通用工具入口、远程连接与扩展说明，通过链接指向所属模块，不再为同一领域另设调试页面。

正文链接使用 /read/文章标识。这些真实链接生成图谱与反向关联，不需要再维护关系表或节点坐标。

图表直接复用模板

在网页正文编辑器中插入“自动排版图表”，填写标题与 Mermaid 文本。关系使用 flowchart，调用先后使用 sequenceDiagram，生命周期使用 stateDiagram。现有页面可以直接作为写作参考：

本地文件使用同一 Diagram 组件。下面复用 Input 的配置关系，标签中 \n 表示换行：

<Diagram
  title="配置与处理器的关系"
  source={
    'flowchart LR\n  Setup(Input Setup) --> IMC(映射上下文)\n  Setup --> Handler(共享 Handler)\n  IMC --> IA(Input Action)\n  IA --> Handler'
  }
/>

布局、四色主题、缩放与全屏由共享组件处理。日常不用写坐标、连线路径、单篇 CSS 或动画。图表出错先检查 Mermaid 关系，不重新搭页面。

正文组件

Note 提供带标题的说明卡片，Diagram 提供图表，BlueprintViewer 用于在功能说明里展示蓝图节点。三者均注册到 MDX 与网页编辑器。

介绍蓝图用法时，在正文插入“蓝图用法说明”，填写节点图标题和从 UE 复制的完整节点文本。节点文本随文章保存，读者打开页面即可看到图，不需要再手动粘贴。应在图前后说明前置配置、关键引脚与执行结果，具体格式见蓝图用法说明。

更新后的必要检查

先执行 pnpm check:content 核对元信息与站内链接。改名或删除文章时同步更新反向引用；新增图表只检查相关语法与显示。普通内容沿用共享组件，不例行做阅读适配、窄屏截图或全站视觉确认；只有布局、组件改动或实际显示问题需要时再检查对应部分。

发布构建使用 pnpm build:pages --base-path /StarryManual，再执行 pnpm check:pages 检查静态产物。是否推送发布按当前工作指令执行，本地保存与构建不会自动发布。

返回手册导览。

Starry手册导览从模块进入子模块与具体功能，查阅功能用途、配置步骤、技术架构和扩展方法。工程分层与系统协作了解 Framework、Gameplay 与通用插件的依赖方向，以及配置装配和运行状态的边界。模块总览与接入从行为系统、执行系统与机会调度了解 AstraAI，再为角色配置第一套组合决策。组合与覆盖正确区分优先级、行为分数与 Stack 顺序，按完整路径组织可撤销的配置。评分与抢占沿着条件、优先级、分数、持续有效性与冷却，解释一个行为为何开始或退出。Logic 与生命周期把动作接入 Start、Cancel、Cleanup，正确处理共享模板、蓝图实例与过期异步回调。BT、StateTree 与 HTN复用控制器上的树组件，正确传入数据、报告整树结果并等待安全退出。Objective 与机会生成把领域事实整理成当前机会，让评分只读数据，让生成器独立管理订阅。命令发布与领取发布一条命令后，经机会评估、Take、执行与 EndUse 完成一次受控使用。行为区域用可挂载的 Zone 组件分配行为层，并把回区机会与实际导航分开。调试与排查从初始化到候选、机会、应用层与后端，沿真实运行路径定位 AI 没有行动的原因。模块总览与使用了解通用调试工具的操作、远程连接与窗口扩展，再由各模块的排查说明定位具体问题。netImgui 远程面板在独立桌面程序查看调试窗口，区分远程 UI、游戏视口绘制与玩法网络权限。窗口扩展与属性绘制复用窗口生命周期、反射 Inspector 和场景绘制，避免为每个调试页重做基础设施。模块总览与接入从配置绑定、动作处理、通道缓存与玩家改键了解 Input，再接入角色的输入配置。绑定与配置生命周期理解跨 IMC 的共享绑定、配置所有权、延迟初始化，以及切换角色时的清理。Handler 与能力分派选择正确的输入阶段，把输入交给移动、GAS、GameplayEvent 或 UI，保持共享 Handler 无玩家状态。修饰器与双击选择输入值变换所在层，理解玩家设置修饰器与 Double Tap 的时序规则。通道输入缓存按 GameplayTag 通道开窗，保留首批或末批输入，正常关闭执行，中断取消丢弃。改键与玩家设置通过 GameSettings 统一编辑与应用，区分 SharedSettings 偏好和 Enhanced Input 键映射数据。调试与排查使用 Gamepad 与 Actions 观察和模拟输入，沿设备、映射、绑定、缓存与能力定位问题。模块总览与接入使用 UE 5.8 原生 Async Message System，把事件通知与接收方解耦，查阅消息收发、路由和 Starry 的实际接入。蓝图收发与解绑通过消息 Id、监听、载荷封装与解包的核心连线，掌握蓝图收发和任务解绑。C++ 收发与解绑按取得系统、登记监听、读取载荷、发送与解绑的顺序，查阅原生 C++ 接口用法。标签、时机与生命周期理解消息的标签层级、World 和 Endpoint 路由、游戏线程派发、载荷快照与 C++ 监听清理。项目消息与排查查阅 Starry 已接入的消息标签、载荷和触发点，区分本地通知、状态复制与 RPC 转发，并沿真实链路排查。模块总览与项目接入管理软引用加载、有序回调与任务作用域，了解指示器画布的实际接入，以及加载完成后的资源和宿主生命周期。软引用加载与 C++ 用法用组件加载软对象和控件类，保存加载结果，理解路径数组、同步回调、失败结果，以及重载与退出时的取消清理。主资产与资源驻留按主资产 ID 和 Bundle 预加载资源，理解句柄保留、取消与 GC 引用的关系，以及 AssetManager 和打包配置的职责。回调顺序与独立作用域理解并行加载与有序回调的区别，使用 FAsyncScope 分开取消任务，了解 AsyncEvent、开始完成通知和等待条件的当前边界。在文档中说明蓝图用法将真实蓝图节点嵌入正文，结合步骤、引脚和连线说明功能，节点文本随文章保存。维护这本手册本地文件与网页编辑共用一份 MDX，日常只改内容与关系，沿用共享版式和图表。
全部 32 篇文章