X-agent v0.6.6

X-agent v0.6.6

改进

• 支持在设置 → 通用导出本地诊断包，帮助定位崩溃；不包含密钥、完整对话或项目源码，不自动上传。
• 小屏和 Windows 高 DPI 下按显示器可用区域调整窗口，窄窗工具面板覆盖展示，聊天输入和设置滚动保持可用。
• 目标模式结合工具结果判断完成，评估开销计入用量和预算；预算耗尽后停止续轮。

修复

• 配置损坏或保存失败时保留原文件并报告错误；工具设置只有在保存和应用成功后才返回成功。
• 撤回保留 Agent 未修改的用户文件；停用供应商不再误删相同地址下其他供应商配置。
• 修复 Godot 桥使用随机端口时发布错误连接地址的问题。

安全

• 加强项目、插件和策划目录的链接路径检查，拒绝联接或符号链接指向授权目录之外。
• 模型列表探测禁止重定向，并在连接时检查 DNS 地址；需使用最终公网服务地址。

测试 & 质量

• 增加实际静态检查、业务回归、崩溃与缩放测试，以及真实 Godot 编辑器集成验证。
• 发布前验证版本、tag、提交及变更记录一致，并要求完整检查通过后才打包上传。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.6.5

X-agent v0.6.5

改进

• Godot 工具响应更快：play 场景错误收集、wait_for_import_done、RPC round-trip、桥接启动 grace、export 桥接余量等超时统一下调；运行场景时报错多在前 1-2s 返回，长跑玩家继续走 godot_play_errors 拉新错。
• 自动重试状态显示在聊天面板：发起重试时插入「自动重试 N/M（等待 Xs）」行，恢复成功自动消失，失败转为「重试失败：xxx」错误行——Pi SDK 的 auto_retry_start/auto_retry_end 事件真正落到 UI，不再只是 status 通灯变化。
• 取消请求不再等满超时：godot-rpc bridge 接受上游 AbortSignal，桥接级 bridgeAbortController 让 bridge.stop() 与会话切换立刻 reject 所有 pending，不再各自等满 timeout；git / fetch / splash 等子进程也可由 AbortSignal 主动 kill。
• 启动体感收紧：splash 兜底 30s → 15s、自动检查更新延迟 8s → 3s、auto-maintain debounce 5s → 3s、供应商档案首次 fetch 单端点 15s → 8s 并改用 AbortSignal.timeout 单次 signal。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.6.4

X-agent v0.6.4

改进

• DeepSeek 模型元数据自动取真值：供应商档案「拉取模型」走 /v1/models（含 /models）扩展 schema（context_window / max_output_tokens / input_modalities / effort），由 effort.supported_levels 自动翻译为 Pi thinkingLevelMap 写入 models.json；不再依赖仓库内 hardcoded 字段。DeepSeek thinking 二态（on/off）落地到所有 5 个非 off 档位的运行时映射，deepseek-flash 等历史遗漏 id 走启动期 repair 自动补齐 contextWindow / compat。

修复

• OCR review Round 1 Critical — handler-throw 中文翻译激活：register-ipc.ts handler 抛错路径改走 TranslatedIpcError 子类，renderer 侧 error-i18n.ts 翻译不再 dead code，IPC 错误提示恢复中文本地化。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.6.3

X-agent v0.6.3

修复

• 供应商「图片输入」配置静默失效：编辑 / 新增供应商档案时，模型行的 image chip 默认改为「未表态」（dashed border 视觉），保存时按已知 vision 模型家族（gpt-4o / 4.1 / 5 / o1 / o3 / o4-mini / claude / gemini-1.5+ / mistral-small|medium|pixtral / MiniMax-M3 / qwen-vl / 含 vision 或 vl 关键字）由 guessDefaultInput 启发式兜底，避免 Pi SDK 0.83+ modelFromJson 用 ?? ["text"] 覆盖 bundled vision。已配置 ["text","image"] 的旧档案不受影响。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.6.2

X-agent v0.6.2

改进

• 供应商模型加支持图片开关：「设置 → 供应商 → 编辑」模型行新增 text / image 多选 chip；勾上 image 后，OpenAI 兼容 / 自建网关也能正常发图，Pi SDK mistral-conversations 等 adapter 不再把 user message 含 image 的整条消息替换为 (image omitted) 占位文本。
• /init 命令 + AGENT.md 自动加载：composer / 菜单新增 init 命令，为当前项目一键生成根目录 AGENTS.md（已有时按 Mavis init 流程停下询问 skip / overwrite with backup / show diff，绝不绕过用户确认覆盖）；项目根的 AGENT.md / agent.md 单数变体自动并入模型上下文，与现有 AGENTS.md / CLAUDE.md 共存不冲突。
• Slash 命令走 <cmd> chip 渲染：/init 等 Pi extension command 在 user bubble 渲染为可折叠的 <cmd name="…"> chip（与 <skill> / <prompt> / <file> 同型），不再把整个 bootstrap body 作为 raw markdown 灌进 user bubble。
• 清理未引用的代码与类型声明：移除全仓零引用的 9 个 export（含 4 个 godot-rpc 类型别名、isDebugMode / isSkipPiSyncForTests / isGodotPiPackageInstalled / gitDownloadUrl / IpcEventChannel），以及与 vite/client 重复的 src/assets/png.d.ts。无用户可见行为变化。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.6.1

X-agent v0.6.1

改进

• Composer 支持附件：可在输入框直接粘贴或拖放图片（缩略图 chip 化显示在 composer 内部）；拖入非图片文件以文件 chip 形式呈现（与图片同区域，cwd 内文件发送时内联展开，cwd 外文件以绝对路径送达模型）。粘贴的图片走多模态协议，AI 实际可见；当前模型不支持图片时，发送前提示切到 vision 模型，并支持拖图时提前在 composer 上方给出警告条。
• 策划会话错误提示措辞：design 模式下被守卫拦截时，错误文案改用策划会话语境，避免误以为处于 plan 模式。
• 项目网站响应式与 favicon：Hero 背景层跨满视口（旧版 1180px 容器会切掉宽屏的渐变与浮层），favicon 替换为从 logo.png 派生的多尺寸渲染集（16/32/48 + apple-touch），部署 README 的 URL / node_id 同步更新。
• 主依赖升级：vite 8.2.2、electron-vite 6.0.0-beta.1、@vitejs/plugin-react 6.1.0，构建与启动性能优化。
• 内部架构加深：session / session-mode / hooks / electron main / IPC / shared / provider 等模块的内部边界收口（主题 A–J 共 8 项重构）；Vitest 覆盖扩展（godot-rpc 跨文件 drift check、IPC 工具注册表 derive / boundary、user-bubble images、model capability 等）。

修复

• CI dependabot-auto-merge race condition：gh pr merge --auto 偶发因 branch protection 元数据未就绪失败，3 次 5s 重试兜底，避免依赖更新自动合并漏触。
• Vitest CI 冷启动超时：testTimeout 由 5s 扩到 15s，CI 冷启动偶发的 5s 超时不再误报。
• e2e：session-type plan mode 接受 design session rollback 路径：策划会话回滚路径与 session-type 判定对齐，避免回滚误判。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.6.0

X-agent v0.6.0

minor 线起点：自动汇总 0.5.0–0.5.5 各补丁；本节先列本周期新增，再附 ### 0.5.0–0.5.5 汇总。

改进

• MiniMax 思考强度开关：供应商预设从单一 M2.7 升级为 M3 / M2.7 / M2.7-highspeed；M3 暴露 off / max 两级强度，上下文窗口 1,000,000；M2.7 仍走 5 档（off / minimal / low / medium / high）。
• 策划会话 system prompt 优化：明示 8 工具白名单与 write_plan / godot_set_* 黑名单（避免 agent 第一轮误用 bash 读项目外路径）；附加 9 份标准 GDD 骨架（主设计 + 9 个子系统）作为"整理 / 写入 设计文档"任务的隐含模板，禁产 summary / audit / integration-plan 这类自由发挥副产物。
• X-agent 项目网站上线：marketing 站点首次发布，独立 repo 单独 build / deploy，不影响 app 包体；README 改写为 Hero + 三段叙事，附 splash 启动屏截图。

修复

• 仅展示模型支持的 thinking 级别：消除 Pi 静默 clamp 后回弹导致的「切到 max 实际是 high」等错觉。
• node 22 → 24 升级 + WSL cold start 修复：CI 与本地开发环境对齐 Node 24；Bash 探针在 WSL 冷启动下不再误判。

0.5.x 累计变更

以下为 0.5.0 起各小版本面向用户的说明汇总（新→旧）。

0.5.5

改进

• 策划会话类型 code / design（issue #22）：在原有 4 个 AgentSessionMode（agent / 调研 / 计划 / 目标）之上，新增会话级 sessionType 抽象——code（默认，写入无限制）与 design（策划会话，写操作硬约束到 <cwd>/game-design/，UI 切暖色主题）。design 类型的工具集为「read + 写/编辑 + readonly bash」，不包含 write_plan（策划文档应直接 write 到 game-design/），且对 write / edit / godot-mutating 工具的路径参数做强约束：相对路径自动补 <cwd>/game-design/，绝对路径 / .. / UNC / 盘符越界 / ~ 展开 / file:// 全部拒绝。type 信息通过 <sessionPath>.session-type.json sidecar 持久化（旧会话自动回退到 code）；顶栏新增会话类型切换按钮、Sidebar / ReadyChecklist 加 design 徽标；35 个 vitest 用例覆盖路径规范化、逃逸尝试、godot 工具、bash 只读与扩展 hookup。
• 策划会话预装 5 个内置 skill（issue #23）：首次打开策划会话（或 main 进程启动预热）自动懒写 5 个 SKILL.md 到 ~/.pi/agent/skills/design-*/SKILL.md：design-initiation（立项策划工作坊）、design-process（开发流程 5 阶段 + 想法池 + 周节奏）、design-systems（角色 / 世界观 / 关卡系统设计）、design-numerical（数值表 + 平衡方法）、design-core-loop（30s 循环 + 乐趣四象限）。由 Pi 的 DefaultResourceLoader 自动发现并入 <available_skills> 顶部，body 不入 system prompt——agent 通过 read 工具按需加载完整方法论，0 token 浪费在「用不上的方法论」上。懒写幂等：内容一致则跳过，用户改过则不覆盖（sha256 记录到 ~/.pi/agent/x-agent/builtin-skills-installed.json），force: true 可强制重写。6 个 design chat starter id 保持不变（design-character / design-world / design-core-loop / design-data-table / design-level / design-gdd-scaffold），prompt 文案显式点名对应 skill（5-loose 映射：character/world/level 共享 design-systems）。
• 可切换的客户端 logo（issue #19 + #20）：在「设置 → 通用 → 品牌」新增 logo 选择器，8 套内置预设（霓虹赛博 / 熔岩灼烧 / 电浆雷霆 / 全息彩虹 / 玫瑰金金属 / 像素 8-bit / 故障 Glitch / 宇宙星云）+ 自定义上传（PNG / JPG，64–4096 px，≤ 4 MB）。切换即时生效：favicon、BrowserWindow 标题栏 / 任务栏图标；内置 logo 资产从 PNG 1024 改为 webp 双尺寸，体积节省 88%。splash 启动屏与打包后的 .exe / NSIS 安装包图标不在运行时替换范围内（需要 npm run dist 重新打包）；自定义 logo 存到 ~/.pi/agent/x-agent-logos/<uuid>.png，由新注册的 x-agent-logos:// 自定义协议对外提供；删除自定义且其是当前活跃项时自动回退到默认。
• 仓库文档归位：根目录的领域文档（roadmap / context / agent / design / maintenance / adr 等）统一搬到 docs/，README 链接同步更新，CLAUDE.md 指引仍指向唯一权威 docs/context.md + docs/maintenance.md。

0.5.4

改进

• UI 主次分明改版（v1.1 设计语言）：告别"全窗单 Surface + 1px 边线切一切"的扁平网格感，改为 elevation 驱动的层级式布局。Composer / 输入区是整窗唯一主元素，三栏壳层（TopBar / Sidebar / RightPanel）降为低调 chrome。10 主题族（default / nord / tokyo / paper / contrast × dark/light）全部补齐新 token；contrast 仍走硬边、paper 阴影最轻。
• Sidebar 可折叠：新增折叠按钮，56px 图标态 ↔ 260px 完整态，偏好记忆化；窗口 ≤960px 自动展开。
• RightPanel 改版：水平 tabs 改左侧垂直 nav；上下文占用区提为唯一主卡，section 间 1px 横线删除。
• 仓库健康流程落地：补齐 LICENSE / CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / MAINTENANCE 等开源协议与协作流程文件；启用 dependabot 周更 + actionlint + commit-msg 钩。

移除

• 游戏开发四阶段工作流：2026-08-23 引入的策划 / 原型 / 测试 / 扩充 4 阶段项目级工作流（顶栏进度条、阶段 modal、阶段化 skill 过滤）整体回滚，回到核心 4 mode（agent / 调研 / 计划 / 目标）独享工作流。

修复

• 一键安装本地 Packages 不再被静默删除：路径解析统一以 ~/.pi/agent 为基准（与 pi CLI 一致），安装记录不再被 pruneMissingPiPackageSources 误判清除。

0.5.3

改进

• Diff 显示：Agent 每回合结束（Shadow 检查点可用时）在回复下方折叠展示本轮改动的高亮 diff（+/- 行着色、文件数与增删统计（+N 绿 / -N 红）、超长截断）；撤回确认弹窗新增「将被还原的内容」diff 预览（pre→HEAD 统一 diff），与「涉及文件」列表并列，撤回前可逐行确认影响范围。
• Diff 显示（无 Git 降级）：本机未安装 Git 时不再完全缺失 diff——基于 write / edit 工具执行前记录的字节基线，与当前文件内容对比（jsdiff）生成同样的高亮 diff；回合 diff 与撤回预览「write/edit 改动预览（无 Git 降级）」均可用。bash 改盘等无基线的改动仍无法追踪（与"无法还原"的降级语义一致）。
• Clarify 问答每题支持自行输入答案：Plan 模式 AI 追问（<clarify> 多选块）每题新增「自行输入答案」选项——点选展开输入框填写自由文本，与选项互斥（选选项会清掉自定义、开自定义会取消选项）；已填文本计入作答进度，提交时自定义答案与选项同格式（问题 → 答案）发送给模型。

安全（项目整体审查后修复）

• Godot 项目设置硬闸：godot_set_project_setting 经 shared/godot-project-setting.ts 校验——敏感前缀（autoload/* / input/* / debug/file_logging/* / debug/shapes/* / project_settings_override/* / editor_plugins/enabled / network/tls/certificate_bundle_override 等）拒绝写入；value 收窄为 string / number / boolean 或简单嵌套（最多 1 层）；key 限 ASCII 字母数字+/_，避免 project.godot 注入。
• Provider baseUrl DNS 闸：保存供应商档案时 upsertProviderProfile 经 validateUpsertAsync 双重校验（静态 host 黑名单 + 异步 DNS rebinding 解析），拒绝私网 / localtest.me / *.nip.io 等。
• Godot RPC 客户端与项目绑定：GodotRpcBridge 新增 setCurrentCwd——已绑定时仅当前会话项目下的客户端合法；显式 clientId 与 cwd 不匹配直接拒绝（不静默改道）；切换项目时若原 active 不匹配则重置为首个匹配客户端。
• shellPath 真 Bash 闸：applyBashShellPath 要求 --version 输出包含 GNU bash 特征；非可信目录会同时返回 warning，由 renderer 横幅提示。
• Godot 资源清理：RPC 启动期 server.unref()、stop() 强制 1s 超时降级；编辑器子进程 spawn 失败路径也 unref()；auto-updater 启动检查 unref()。
• 持久化原子化：plan-journal / goal-journal 改走 atomic-write.ts 的 writeJsonAtomicSync（tmp + rename），不再写半截；package-manager registry 同步入口加 per-key 自旋锁，避免 install / prune 并发互相覆盖。
• 启动失败摘要：recover / bridge / package install 失败写入 getStartupReport 通道并 dbgLog，renderer 经 ReadyChecklist 提示用户。
• abort 失败状态修正：abort 抛错时不再盲目 setStatus('idle')——重读 isStreaming，仍 streaming 时保留 error 状态并 emit notice。
• usage 写入失败：error-bridge 内 catch 改为 dbgWarn，便于诊断。
• orphan 清理：启动期清理残留 .tmp / bash-liveness probe / 90 天未用的 godot-rpc endpoint。

测试 & 质量

• Vitest 覆盖扩展：新增 bash-readonly / external-url / secret-codec / atomic-write / provider-persist 五套 vitest 单元测试（与 godot-project-setting / godot-rpc-bridge 合计 24 套 323 测试 92% 覆盖率）；新增 setSkipDnsForTests / setSkipPiSyncForTests 用于隔离外部依赖。
• E2E 契约扩展：从 2 个扩到 6 个（contracts / mode-flow / mode-attestation / ipc-validation / startup-report）——锁定 facade 行为、IPC 校验、状态机契约。
• CI 加固：新增 concurrency 与 lint 步骤；e2e job 加 Playwright 浏览器缓存；release workflow 加 lint 与 test-extract-changelog 校验。

0.5.2

修复（Godot 工具 · 插件 0.6.3）

• godot_list_project_files 恒超时根因修复：请求携带 type 过滤参数，插件 _handle_line 用 data.has("type") 区分请求/事件时被误判为事件直接丢弃（1.3 引入 type 参数以来一直如此——表现为任意参数组合恒 timeout、无 SCRIPT ERROR、其余 16 个工具正常）。判定改为以 method 为准。另：移除逐文件 uid 主线程查询（uid 需要时用 godot_resolve_uid 按需查询）、遍历排除 res://.godot/ 缓存目录、每 300 个文件分帧让出主线程（不再冻结编辑器）、编辑器文件系统重扫中返回 scanning 标记供稍后重试。
• godot_inspect_script 恒返回空修复：get_constants() / can_reload() 均为版本敏感 API（4.6/4.7 已移除），无守卫调用会运行时中断整个函数 → 响应为空对象（全 none + 无 extends）。改为 has_method 守卫 + 引擎反射为空时从源码提取（func / @export / signal / const）兜底；方法返回类型改从 return 子字段提取（顶层无 type 字段）。
• godot_lint_scripts 误报 class_name 脚本：裸脚本 reload 对含 class_name 的合法脚本伪报 Parse error；--check-only 子进程改为 exit code + 输出双信号判定（exit 0 即判合法），不再回退错误码文案误报。
• godot_get_node_properties 补 hint 详情：hint 输出语义名（RANGE / ENUM / …），新增 hintString（range 的 min/max/step、enum 成员列表、数组元素类型线索）。
• godot_open_scenes 无场景时返回 []：过滤 EditorInterface.get_open_scenes() 返回的空字符串条目。

修复（chat / 其他）

• 长会话发送消息不再弹到上面：虚拟列表贴底与异步行测量解耦——启用 tanstack anchorTo: "end" 贴底补偿（测量完成当帧同步修正滚动位置），尾行不可见时也保持跟随；"回到底部"按钮层级修复（isolation: isolate，不再被消息气泡盖住）。
• 供应商模型残留：档案编辑删除的模型不再残留在模型选择器——按档案声明的模型 id 过滤（Pi 内置目录合并残留同步收敛，大小写不敏感）。

改进

• 打包仅 NSIS 安装包：移除 portable 便携版产物，安装包为唯一分发形态（CI 产物匹配同步收紧）。
• Godot RPC 诊断：桥接侧新增请求发送 / 响应命中（含 unmatched）/ 超时日志（X_AGENT_DEBUG=1 可见）；插件侧 recv/send 闭环 print（编辑器 Output 面板），RPC 链路问题可远程定位。

UI 与设计规范

• Composer 状态行动画化并常驻：移植 thinking-orbs（MIT © Jakub Antalik）点阵思考球引擎（src/lib/thinking-orbs/）——空闲时显示呼吸环「已就绪」，模型响应中显示粒子轨道，接收回复时切换波形环，自动重试时显示星座连线；四态之间 350ms 交叉溶解过渡，离屏 / 标签隐藏自动暂停，prefers-reduced-motion 下渲染静态帧。
• 顶栏去重：移除 TopBar 的 status-chip 状态徽标（运行中 / 空闲），状态语义统一由 Composer 状态行承载。

0.5.1

安全（全面审查后修复）

• 命令注入修复（高危）：Windows 下 pi.cmd 经 cmd.exe 执行时 Node 对 args 只做拼接不转义（DEP0190）。spawnCli 现对每个参数做完整 cmd 转义（含 % 环境变量展开防护）；installPackage / uninstallPackage 入口加包源格式白名单（仅 npm: / git+ / https: / ssh: 或本机存在的目录）。
• SSRF 防护统一：fetchProviderModels 与供应商档案 baseUrl 保存侧均接入 URL 校验——仅 http(s) 且 host 非回环 / 私网 / 链路本地 / 已知 DNS 重绑定域（localtest.me / *.nip.io 等）；validateExternalHttpUrl 补 IPv4-mapped IPv6 十六进制形态（::ffff:7f00:1）绕过，并对域名做 DNS 解析后校验。本地 LLM（Ollama 等）需经公网代理中转。
• Ask/Plan 只读硬闸加深：
  • bash 只读过滤补拦：裸 git stash（= stash push）、git branch <名> / git tag <名> / git remote add|set-url 等 ref/config 写入、$VAR / ~ / $'…' 展开、>| / < 重定向、date -s；路径检查支持 ~ 展开判越界与 Windows 大小写归一，..foo 不再误拦。
  • read / grep / find / ls / godot_detect_project 的 path 参数现强制落在项目 cwd 内（Pi 工具会展开 ~ / 绝对路径 / file://）。
• Godot 工具开关不可绕过：godotRpcRequest 现校验 prefs.tools 是否启用对应工具（GODOT_TOOLS 默认关闭的硬闸从纯 UI 偏好恢复为安全边界），并做参数长度/类型钳制。
• IPC sender 统一校验：全部 87 个 invoke handler 经包装器校验来源（主窗口 webContents + frame origin 匹配），纵深防御。
• lastProjectPath 路径约束：patchPrefs 仅接受已存在目录；Godot addon 安装 / 编辑器启动消费处二次确认。
• 主窗口 sandbox: true：preload 改为 CJS 单文件（关闭 externalizeDeps，仅依赖 electron 受限 API），contextBridge 不再是唯一防线。
• 供应商密钥保护：safeStorage 解密失败（换机器 / 密钥环重置）时保留盘上密文（encryptedKey），任一次保存不再用空串覆盖导致密钥永久丢失。
• 外部链接 / 导航边界：will-navigate 改 origin 精确匹配（堵 127.0.0.1:5173.evil.com 前缀伪匹配）。

修复（数据完整性与健壮性）

• 撤回与发送竞态：prompt 的「检查点准备 → session.prompt」过渡窗口内撤回被拒绝；撤回后丢弃未绑定的 pending pre-sha，旧状态不再「复活」。
• Shadow 撤回按 diff 路径还原：不再整库 reset --hard（会静默丢弃回合期间的用户手动编辑）——只还原该回合内变化过的文件；预览文案同步说明。
• 供应商档案并发：importExistingProviderProfiles 读-改-写整体纳入 storePath 锁；syncProfileToPi 的 activeId 更新在锁内重读最新 store；repairDeepSeekModelsJson 改走锁 + 原子写。
• chat 归并修复：pending 气泡替换保留占位 id（消除虚拟行 remount 闪烁）、按 FIFO 替换未确认项（连发两条不再内容互换）；发送按钮在 pending 未确认时禁用；removePendingUser 不误删已确认气泡。
• 检查点仓库防膨胀：shadow commit 后 reflog expire + gc --auto 修剪撤回孤儿 commit；persistDirty 改增量落盘（dirtyTurns / droppedTurns），会话文件不再 O(N²) 全量快照。
• settings.json 双写入方原子化：bash `shell...

X-agent v0.5.5

X-agent v0.5.5

改进

• 策划会话类型 code / design（issue #22）：在原有 4 个 AgentSessionMode（agent / 调研 / 计划 / 目标）之上，新增会话级 sessionType 抽象——code（默认，写入无限制）与 design（策划会话，写操作硬约束到 <cwd>/game-design/，UI 切暖色主题）。design 类型的工具集为「read + 写/编辑 + readonly bash」，不包含 write_plan（策划文档应直接 write 到 game-design/），且对 write / edit / godot-mutating 工具的路径参数做强约束：相对路径自动补 <cwd>/game-design/，绝对路径 / .. / UNC / 盘符越界 / ~ 展开 / file:// 全部拒绝。type 信息通过 <sessionPath>.session-type.json sidecar 持久化（旧会话自动回退到 code）；顶栏新增会话类型切换按钮、Sidebar / ReadyChecklist 加 design 徽标；35 个 vitest 用例覆盖路径规范化、逃逸尝试、godot 工具、bash 只读与扩展 hookup。
• 策划会话预装 5 个内置 skill（issue #23）：首次打开策划会话（或 main 进程启动预热）自动懒写 5 个 SKILL.md 到 ~/.pi/agent/skills/design-*/SKILL.md：design-initiation（立项策划工作坊）、design-process（开发流程 5 阶段 + 想法池 + 周节奏）、design-systems（角色 / 世界观 / 关卡系统设计）、design-numerical（数值表 + 平衡方法）、design-core-loop（30s 循环 + 乐趣四象限）。由 Pi 的 DefaultResourceLoader 自动发现并入 <available_skills> 顶部，body 不入 system prompt——agent 通过 read 工具按需加载完整方法论，0 token 浪费在「用不上的方法论」上。懒写幂等：内容一致则跳过，用户改过则不覆盖（sha256 记录到 ~/.pi/agent/x-agent/builtin-skills-installed.json），force: true 可强制重写。6 个 design chat starter id 保持不变（design-character / design-world / design-core-loop / design-data-table / design-level / design-gdd-scaffold），prompt 文案显式点名对应 skill（5-loose 映射：character/world/level 共享 design-systems）。
• 可切换的客户端 logo（issue #19 + #20）：在「设置 → 通用 → 品牌」新增 logo 选择器，8 套内置预设（霓虹赛博 / 熔岩灼烧 / 电浆雷霆 / 全息彩虹 / 玫瑰金金属 / 像素 8-bit / 故障 Glitch / 宇宙星云）+ 自定义上传（PNG / JPG，64–4096 px，≤ 4 MB）。切换即时生效：favicon、BrowserWindow 标题栏 / 任务栏图标；内置 logo 资产从 PNG 1024 改为 webp 双尺寸，体积节省 88%。splash 启动屏与打包后的 .exe / NSIS 安装包图标不在运行时替换范围内（需要 npm run dist 重新打包）；自定义 logo 存到 ~/.pi/agent/x-agent-logos/<uuid>.png，由新注册的 x-agent-logos:// 自定义协议对外提供；删除自定义且其是当前活跃项时自动回退到默认。
• 仓库文档归位：根目录的领域文档（roadmap / context / agent / design / maintenance / adr 等）统一搬到 docs/，README 链接同步更新，CLAUDE.md 指引仍指向唯一权威 docs/context.md + docs/maintenance.md。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.5.4

X-agent v0.5.4

改进

• UI 主次分明改版（v1.1 设计语言）：告别"全窗单 Surface + 1px 边线切一切"的扁平网格感，改为 elevation 驱动的层级式布局。Composer / 输入区是整窗唯一主元素，三栏壳层（TopBar / Sidebar / RightPanel）降为低调 chrome。10 主题族（default / nord / tokyo / paper / contrast × dark/light）全部补齐新 token；contrast 仍走硬边、paper 阴影最轻。
• Sidebar 可折叠：新增折叠按钮，56px 图标态 ↔ 260px 完整态，偏好记忆化；窗口 ≤960px 自动展开。
• RightPanel 改版：水平 tabs 改左侧垂直 nav；上下文占用区提为唯一主卡，section 间 1px 横线删除。
• 仓库健康流程落地：补齐 LICENSE / CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / MAINTENANCE 等开源协议与协作流程文件；启用 dependabot 周更 + actionlint + commit-msg 钩。

移除

• 游戏开发四阶段工作流：2026-08-23 引入的策划 / 原型 / 测试 / 扩充 4 阶段项目级工作流（顶栏进度条、阶段 modal、阶段化 skill 过滤）整体回滚，回到核心 4 mode（agent / 调研 / 计划 / 目标）独享工作流。

修复

• 一键安装本地 Packages 不再被静默删除：路径解析统一以 ~/.pi/agent 为基准（与 pi CLI 一致），安装记录不再被 pruneMissingPiPackageSources 误判清除。

---

完整变更记录见仓库 CHANGELOG.md。

X-agent v0.5.3

X-agent v0.5.3

改进

• Diff 显示：Agent 每回合结束（Shadow 检查点可用时）在回复下方折叠展示本轮改动的高亮 diff（+/- 行着色、文件数与增删统计（+N 绿 / -N 红）、超长截断）；撤回确认弹窗新增「将被还原的内容」diff 预览（pre→HEAD 统一 diff），与「涉及文件」列表并列，撤回前可逐行确认影响范围。
• Diff 显示（无 Git 降级）：本机未安装 Git 时不再完全缺失 diff——基于 write / edit 工具执行前记录的字节基线，与当前文件内容对比（jsdiff）生成同样的高亮 diff；回合 diff 与撤回预览「write/edit 改动预览（无 Git 降级）」均可用。bash 改盘等无基线的改动仍无法追踪（与"无法还原"的降级语义一致）。
• Clarify 问答每题支持自行输入答案：Plan 模式 AI 追问（<clarify> 多选块）每题新增「自行输入答案」选项——点选展开输入框填写自由文本，与选项互斥（选选项会清掉自定义、开自定义会取消选项）；已填文本计入作答进度，提交时自定义答案与选项同格式（问题 → 答案）发送给模型。

安全（项目整体审查后修复）

• Godot 项目设置硬闸：godot_set_project_setting 经 shared/godot-project-setting.ts 校验——敏感前缀（autoload/* / input/* / debug/file_logging/* / debug/shapes/* / project_settings_override/* / editor_plugins/enabled / network/tls/certificate_bundle_override 等）拒绝写入；value 收窄为 string / number / boolean 或简单嵌套（最多 1 层）；key 限 ASCII 字母数字+/_，避免 project.godot 注入。
• Provider baseUrl DNS 闸：保存供应商档案时 upsertProviderProfile 经 validateUpsertAsync 双重校验（静态 host 黑名单 + 异步 DNS rebinding 解析），拒绝私网 / localtest.me / *.nip.io 等。
• Godot RPC 客户端与项目绑定：GodotRpcBridge 新增 setCurrentCwd——已绑定时仅当前会话项目下的客户端合法；显式 clientId 与 cwd 不匹配直接拒绝（不静默改道）；切换项目时若原 active 不匹配则重置为首个匹配客户端。
• shellPath 真 Bash 闸：applyBashShellPath 要求 --version 输出包含 GNU bash 特征；非可信目录会同时返回 warning，由 renderer 横幅提示。
• Godot 资源清理：RPC 启动期 server.unref()、stop() 强制 1s 超时降级；编辑器子进程 spawn 失败路径也 unref()；auto-updater 启动检查 unref()。
• 持久化原子化：plan-journal / goal-journal 改走 atomic-write.ts 的 writeJsonAtomicSync（tmp + rename），不再写半截；package-manager registry 同步入口加 per-key 自旋锁，避免 install / prune 并发互相覆盖。
• 启动失败摘要：recover / bridge / package install 失败写入 getStartupReport 通道并 dbgLog，renderer 经 ReadyChecklist 提示用户。
• abort 失败状态修正：abort 抛错时不再盲目 setStatus('idle')——重读 isStreaming，仍 streaming 时保留 error 状态并 emit notice。
• usage 写入失败：error-bridge 内 catch 改为 dbgWarn，便于诊断。
• orphan 清理：启动期清理残留 .tmp / bash-liveness probe / 90 天未用的 godot-rpc endpoint。

测试 & 质量

• Vitest 覆盖扩展：新增 bash-readonly / external-url / secret-codec / atomic-write / provider-persist 五套 vitest 单元测试（与 godot-project-setting / godot-rpc-bridge 合计 24 套 323 测试 92% 覆盖率）；新增 setSkipDnsForTests / setSkipPiSyncForTests 用于隔离外部依赖。
• E2E 契约扩展：从 2 个扩到 6 个（contracts / mode-flow / mode-attestation / ipc-validation / startup-report）——锁定 facade 行为、IPC 校验、状态机契约。
• CI 加固：新增 concurrency 与 lint 步骤；e2e job 加 Playwright 浏览器缓存；release workflow 加 lint 与 test-extract-changelog 校验。

---

完整变更记录见仓库 CHANGELOG.md。