Skip to content

project-handoff-notes.md

Latest commit

 

History

History
239 lines (185 loc) · 24.3 KB

project-handoff-notes.md

File metadata and controls

239 lines (185 loc) · 24.3 KB

Project Handoff Notes

这份文档用于新对话接手前快速建立上下文。它是项目级 handoff，只保留长期有效的事实、约束和工作方式，不记录单次 UI 调整、临时文案、按钮位置或某一轮对话的细枝末节，除非该信息会影响后续实现或审查判断。

最高优先级

  1. 同一对话中一旦已经读取本文件，后续所有任务都必须持续遵守本文件；不能因为任务切换、上下文变长、用户只说“继续”或进入图片/命令/提交等非代码流程而遗忘、降级或绕开这些约束。
  2. 如果本文件约束与一般主动性、效率优先、工具习惯或临时推断冲突，以本文件为准；先收窄范围、确认证据和保护工作区，再执行。

使用方式

  1. 新对话开始时先读本文件，再读当前代码和 git status。
  2. 本文件不是最终事实库；如果代码、测试、日志和本文件冲突，以可复现证据和当前代码为准。
  3. 只把跨功能、跨对话仍有价值的信息写入这里。一次性任务细节应留在对应任务说明、提交信息或临时审查文档里。
  4. 读取后先形成当前任务的成功标准，再决定是否需要查代码、跑测试或请求用户确认。
  5. 开始执行前必须先确认本轮任务类型：代码修改、文档修改、运行命令、审查、回退、提交、图片生成或纯回答。任务类型不同，允许动作不同，不能把非代码任务扩展成代码实现。
  6. 若用户已经点名“严格遵守本文件 / 按规范 / 不要猜 / 不污染”，本文件约束优先级高于一般主动性；先收窄范围，再执行。
  7. 若用户纠正“你又猜了 / 走偏了 / 重做 / 撤销刚刚的”，立即停止继续扩展，只处理本轮错误范围；不得在错误方案上继续追加补丁。
  8. 上方“最高优先级”对整场对话持续生效；后续每个任务都按该优先级解释和执行。

执行前硬检查

每次动手前都要完成以下检查；不能跳过：

  1. 明确本轮只允许改哪些文件或只允许执行什么命令；如果用户没有要求改代码，不要改代码。
  2. 先看 git status --short，识别已有未提交修改、未跟踪文件和 .agent 文件；不要把它们默认当作自己可处理的内容。
  3. 如果要编辑文件，先确认该文件属于本轮目标；只改目标文件和必要的直接测试文件。
  4. 如果要撤销修改，必须先用 git diff -- <path> 或等价证据确认要撤销的具体片段；禁止用宽泛命令回退整仓、整目录或所有 tracked files。
  5. 如果任务是生成图片、查资料、设计参考、审查或纯文档讨论，不得顺手写代码、改 CSS、改测试或改构建产物。
  6. 如果发现当前工作区已有大量用户修改，默认保留；除非用户明确要求提交、回退或整理，否则不要清理、恢复或重排。
  7. 如果需要从“猜测实现”变成“事实实现”，先补证据：读当前链路、跑测试、看运行日志或用浏览器/Playwright 观察，再落代码。

快照与回退证据

  1. 用户要求“回到某句话之前 / 撤销到某一步 / 有快照 / 对话上下文里有状态”时，任务类型是精确回退，不是重新设计或继续修复。
  2. 精确回退必须先定位可靠锚点：对话 rollout、git diff、当时的 git status、补丁记录、测试输出或其它可复现状态；不能用记忆、设计文档或当前代码形态推断目标状态。
  3. 如果存在 Codex rollout 或等价快照，优先从快照重建目标状态：定位目标用户消息前一刻，提取该时点之前的真实工具调用、补丁和状态输出，在临时目录重放或还原，再与当前工作区逐文件比对。
  4. “回退到快照”完成标准是目标文件内容与快照一致；可用 cmp、git diff --no-index、diff stat 和状态文件列表验证。只说“看起来恢复了”不算完成。
  5. 回退任务中禁止把设计目标、产品理解或“应该这样”混入恢复内容；先做到快照一致，再根据用户新的明确要求继续改。
  6. 如果快照显示某个文件当时不该改动，应恢复该文件；如果快照显示未跟踪 .agent 或临时产物不属于目标，不要顺手清理或提交。
  7. 发现自己已经在错误方向上继续补丁时，先停止新增实现，用快照或 diff 证据撤回错误方向；不要在错误实现上继续“修到像对的”。

背景范围

本文件覆盖两类内容：

  1. 存储位置相关启动流程的已确认事实与调查边界。
  2. 跨任务仍会复用的通用约束，例如文档优先级、跨端一致性、验证方式、提交边界和表现层改造原则。

当前已确认：

  1. 纯后端在真正全新的隔离环境下，首次启动会进入 selection_required。
  2. 因此，“首次不弹”不能直接归因为后端首次判定函数失效。
  3. 完全新用户正常首次启动时，默认 current_root / recommended_root 指向平台标准 app data 目录下的 N.E.K.O：
    • macOS: ~/Library/Application Support/N.E.K.O
    • Windows: %LOCALAPPDATA%\N.E.K.O
    • Linux: ${XDG_DATA_HOME:-~/.local/share}/N.E.K.O
  4. 产品意图是引导用户使用/迁移到上述系统推荐数据目录，而不是鼓励随意选择位置。

当前未闭环的候选原因：

  1. 桌面壳复用已有后端，可能影响用户以为的“首次启动”。
  2. 关闭窗口但应用未真正退出，可能造成启动状态误判。
  3. 旧后端、旧状态或状态文件可能短路存储位置选择流程。

这些只能作为待验证假设，不能写成已确认根因。

首次存储位置语义

  1. ConfigManager 负责解析平台标准目录，并把运行根拼成 <standard-app-data>/N.E.K.O。
  2. 没有 storage_policy.json 时，should_require_storage_selection() 返回 True，前端 storage sentinel 阻断主 UI。
  3. 用户确认当前路径后，后端写入 storage_policy.json，设置 first_run_completed: true，然后释放启动闸门。
  4. 提醒页主页正文当前按用户要求不要改；只允许在明确需求下调整按钮文案和动作。
  5. 中文提醒页按钮的当前产品决策：
    • 主按钮：使用专属小窝，动作是直接接受当前推荐/默认位置。
    • 次按钮：其他小窝，动作是进入后续存储位置选择页。
  6. 不要在提醒页重复放“原来的窝”。如果用户要旧路径或自定义路径，应在后续选择页处理。
  7. 若修改按钮文案，需要同步 8 个 locale，并更新相关测试。

调查原则

  1. 明确区分“已确认事实”“候选原因”“待验证假设”。
  2. 没有真实复现、日志链路、代码链路三者闭环前，不得把候选根因表述成最终根因。
  3. 根因未证实时，不要提前提交“彻底修复方案”或大范围改代码。
  4. 高概率猜测也必须标注为“怀疑”“候选原因”或“需要验证”。
  5. 如果用户只是要本地复现某个启动状态，优先调整本地测试状态，不要把测试触发文件或临时状态提交。
  6. 调试运行时 UI 行为时，不要仅凭代码阅读推测原因。应在关键状态翻转点加诊断日志，然后用 Playwright 自动化捕获实际运行日志。项目已有 Playwright（.venv/bin/python + playwright.sync_api），可直接编写诊断脚本。
  7. 用户说“别猜，实际上手”时，意味着要用自动化工具实际观察运行时行为，不要从代码理论推导。
  8. avatar 按钮视觉样式来源不止 CSS 文件；JS 内联样式和 JS 注入 <style> 也可能影响。排查时搜索所有 avatar 专属 JS 文件。
  9. 排查跨窗口或跨页面联动失败时，要拆开验证：入口是否打开了正确页面、启动消息是否真正发出并被接收、后续 ready/done 或回执是否返回；不要只看“窗口打开了”这一层。

上下文组织

  1. 优先写清楚任务目标、成功标准、已知约束、禁止事项和验证方式；不要堆长聊天摘录。
  2. 长上下文应压缩成“结论 + 证据 + 未解决问题”，不要只保存流水账。
  3. 引入外部结论时记录来源或证据位置；没有来源的内容只能作为待验证背景。
  4. 一个文档只服务一个清晰主题。主题变宽时，优先新建或重命名文档，而不是让旧标题承载新内容。
  5. 如果某段内容会误导新对话以为“已经确认”，应改写为假设或删除。

需求文档与现有链路

  1. 同一需求若同时存在 feature.md、design.md、implementation-flow.md，先确认文档是否已经收敛；若 design.md 或实施流明确说明早期设想已收口，以后者为准，不要按 feature 里的早期业务假设直接落代码。
  2. 做前端行为改造前，先确认“当前真正生效的链路”和“仅为兼容保留的旧链路”。不要因为旧 DOM、隐藏容器或遗留 class 仍在代码里，就误判它是当前可见主流程。
  3. 用户要求“参考设计目标和规范执行”时，不能只抄文档名；要把成功标准翻译成当前代码里的真实入口、事件、DOM 和恢复链路。
  4. 如果用户指出“重新设计思考做”或“先参考现有链路再继续”，意味着当前方向已经偏离；应先撤回错误实现，再从设计文档和现有行为重新对齐，不要在错误方案上继续修补。

潜意识维护态文档优先级

  1. subconscious-maintenance-feature.md 主要定义玩法体感和玩家视角规则。
  2. subconscious-maintenance-reference.md 主要定义第一版实现边界。
  3. subconscious-maintenance-v2.md 定义第二版新增能力和对第一版边界的明确覆盖项。
  4. 若三者冲突，先判断是否属于第二版明确扩展。已明确扩展的内容不要再按第一版“非邀约池 / 不扩展”的旧边界误判为 bug。
  5. 这组文档里当前最容易误判的三点是：
    • 邀约池接入是第二版有意扩展，不是 bug。
    • 浏览器 fallback 跑通，不等于桌面透明覆盖层已真实达标。
    • 稳定值若仍主要挂在顶部全局 HUD，而不是贴近 NEKO 呈现，属于真实设计偏差，应继续收口。

高效提示词模式

  1. “全量检查 / 按设计目标检查 / 有无多余缺失 / 收口”：进入审查模式，先对照设计文档、当前 diff、真实调用链和下游消费者；优先找越界、冗余、污染其他链路、与项目既有语义不一致的问题，再决定是否改代码。
  2. “不属于设计功能的多余 / 自己臆测 / 没有根据实际项目代码”：要求删除或重写没有证据的实现。不能用“看起来合理”的默认值、情绪分类、资源名、DOM 目标或兜底动作替代项目已有链路。
  3. “不是放进去，是规范化”：表示通用模块应提供可复用能力，页面/业务适配层负责把现有 step、事件、目标元素和语义输入转换成模块 DSL；不要把页面剧情、按钮选择器、文案、特殊状态写进通用层。
  4. “不要影响其他功能链路 / 会不会污染”：必须检查正常聊天、idle、模型切换、拖拽、最小化、教程、跨窗口、独立页面和恢复链路；只锁定当前演出声明的 capability，未锁能力应继续由原系统工作。
  5. “已有程序功能判断 / 不要猜情绪”：情绪、动作、表情等语义应使用项目现有分类、映射、资源表和 manager API；适配器只传递已有结果，不自行分类、不默认 neutral、不硬编码具体 Live2D 表情/动作文件名。
  6. “先检查再实施 / 检查测试是否完整”：先列出可观察成功标准和涉及入口，再实施；完成后跑与改动范围匹配的语法检查、回归测试和必要的运行时验证，并明确未验证范围。
  7. “别瞎猜 / 找资料 / 看实际模型和历史实现”：表示不能靠常识补动作或表情，必须先查模型资源、既有 emotion/motion 映射、历史同类实现和当前真实调用链，再决定复用还是扩展。
  8. “重做 / 回到最开始的问题与要求”：表示当前方向已经偏离，应先撤回错误实现，回到原始目标、当前真实生效链路和设计约束重新做。
  9. “按钮不动，只移动模型 / 不要整体移动”：表示局部构图需求只作用于 avatar 自身或其专属表现层，不能把按钮、弹窗或 spotlight 一起带走。
  10. “持续整个语音 / 结束后恢复原样”：表示动作时长应绑定整段 narration/voice 生命周期，结束后必须恢复当前场景演出和周期状态。
  11. “直接生成图片 / 生成图 / 出方案图”：表示只产出图片或图片参考，不等于允许改前端实现；除非用户另说，不写代码、不改样式、不新增项目引用。
  12. “把刚刚的错误修改撤销”：只撤销当前助手本轮或最近明确错误动作引入的改动；先列出精确文件和 diff 证据，再做最小撤销，不得回退用户之前的功能修改。
  13. “继续”：延续上一条明确任务的正确边界；如果上一轮被用户打断或指出错误，继续的含义是先修正边界和错误，不是继续原错误方向。

外部 AI 工作流参考

来源：https://github.com/luongnv89/claude-howto

仅作为可迁移的方法论参考，不等于本项目既有规范；若与当前代码、团队约束或上面的项目规则冲突，以本项目规则为准。

  1. 不要把 AI 只当成单轮问答器。长期效率来自“命令/技能 + 记忆 + checkpoint + 自动化”的组合工作流，而不是不断重写长 prompt。
  2. 重复任务优先产品化成技能或命令，而不是每次临时聊天说明。高频流程应尽量做成可复用入口，减少每轮重新组织 prompt 的成本。
  3. 复杂或高风险任务先建立可回退点，再探索方案。checkpoint / rewind 适合分叉尝试、回滚错误方向和比较方案，但不能替代 git 提交；探索完成后仍应落回可审查的代码和 commit。
  4. 记忆入口必须短且稳定。项目级记忆只保留高频规则、事实和边界，把主题化细节拆到按需文档；不要让入口记忆被聊天流水、临时发现和一次性结论淹没。
  5. 记忆要分层：项目规则放项目级记忆，个人习惯放用户级记忆；长期约束写成可维护文本，临时发现先观察是否反复出现，再决定是否沉淀。
  6. 采用渐进式接入：先落一个高频命令模板、一个项目记忆文件、一个高价值技能；只有当任务已重复出现、人工切换成本明显时，再补 hooks、MCP 或更复杂自动化。
  7. 子代理或并行分工只适合职责清晰、边界明确、可独立验证的子任务；主线程负责定义问题、守住全局语义、整合结果，不要把核心判断完全外包。
  8. hooks 更适合做格式化、校验、日志、通知这类事件驱动自动化，不适合承载核心业务判断；一旦 hook 会改变主要业务语义，就应回到显式代码或显式流程层。

表现层改造边界

  1. 对现有业务底座上的表现层需求，优先复用既有业务语义、事件和恢复链路，不要轻易发明新的业务状态、新入口或新恢复协议。
  2. 用户明确要求“独立分开”时，应把新行为做成独立编排层；不要把 idle、dock、临时视觉态之类的条件分支塞进正常最小化、恢复、goodbye、return 等通用方法内部。
  3. 对“缩小后停靠”的交互要求，要按时序实现：先走原本的缩小/最小化，再移动到目标锚点；恢复时应回到 idle 前的原始位置，而不是停靠后的临时位置。
  4. 做首页 UI 改造时，要额外确认不会污染这些现有能力：正常最小化流程、拖拽能力、教程接管、兼容旧链路、React chat host、/chat 独立窗口和桌面端展示。
  5. 如果某项新行为只应该作用于特定表现阶段或特定页面，就把作用域收紧到那一层；不要让手动流程、其他阶段或独立窗口被顺带接管。
  6. 页面适配层如果只是在消费通用运行时能力，就应尽量把页面专属语义、临时构图和局部恢复逻辑收在适配层，不要通过修改共享 baseline、共享恢复快照或共享 UI 定位链来“顺手保住”某个页面状态。
  7. 排查前端表现异常时，先区分“共享运行时问题”和“页面适配层问题”。没有证据前，不要把页面专属故障直接归因到通用模块，也不要把通用模块改成只服务某个页面。

首页教程打断演出的长期经验

  1. 首页教程里的轻打断、强打断、退出前生气态，本质上都是“当前 scene 上的临时插播”。实现时先抓当前展示快照，结束后恢复；不要把打断态写成新的全局基线。
  2. 打断可能发生在教程任何阶段。实现时必须按“任意时刻可重入”设计，不能假设只会落在某个固定 step、站位或语音段。
  3. 打断态要隔离三类干扰：narration 恢复、当前 scene 的 emotion/口型继续写回、其他正常 idle/教程动作继续推进。常见异常如表情突变、动作被覆盖、前后衔接不自然，多半都属于隔离不完整。
  4. “靠近并阻止点击”这类需求，优先只移动模型专属表现层；按钮、弹窗和其他 UI 锚点保持原位。“靠近”的核心语义是放大并下移，同时尽量保持核心观察点稳定。
  5. 如果出现多手、残影、淡入淡出打架，优先排查是否有两个来源同时驱动同一部位或同一恢复链，而不是继续叠新动作补偿。
  6. 这类演出的验收必须看真实运行时：进入前不被其他流程抢写，持续时间覆盖整段语音，结束后能恢复原 scene 或按设计退出，且不污染正常教程和其他页面链路。

i18n 约束

  1. 用户可见文案原则上应走规范 i18n key，不要只在 JS/HTML 中写中文 fallback。
  2. 新增或修改文案时，需要同步检查 8 个 locale：en/es/ja/ko/pt/ru/zh-CN/zh-TW。
  3. 检查 i18n 缺口时要过滤 CSS class、DOM tag、事件名、日志标记等误报，重点确认用户可见文案。
  4. 不要把数据结构字段名当 UI 文案乱改，例如角色数据中的固定字段名、历史兼容字段、协议字段。
  5. 完成后至少验证 locale JSON 可解析、各语言 key 集合一致、相关代码使用的 key 存在。

跨端与平台

  1. 同时存在桌面端和网页端入口的功能，应对比核心流程是否一致；入口可以不同，状态语义和用户可见结果不应分叉。
  2. 涉及 Windows / Linux / macOS 的路径、权限、关闭、重启、迁移、缓存等逻辑时，需要特别检查平台路径规范和运行时目录差异。
  3. 桌面端关闭、后端退出、重启、维护页跳转等行为要按真实运行链路验证，不能只凭前端窗口状态下结论。
  4. 桌面端多窗口或子页面流程里，运行时端口、origin、opener 来源和后端重定向都可能变化；不要把本地 loopback 地址、固定端口或注入 base 当成永远可靠的真值。
  5. 需要从前端打开本地服务承载的页面时，优先走统一后端入口或运行时解析后的地址，不要在前端写死 127.0.0.1:port。

验证与完成标准

  1. 修改前先明确“完成”的可观察标准，例如页面表现、API 返回、状态文件变化、日志内容或测试结果。
  2. 验证尽量使用外部信号：测试、命令输出、浏览器/桌面端真实运行、日志和文件状态。不要只让模型自我判断。
  3. 不能完整验证时，要明确写出未验证范围和剩余风险。
  4. 修复失败或绕路尝试也有价值；记录压缩后的失败原因、排除项和下一步，而不是保留大段原始错误。
  5. 改 frontend/*/src 一类前端源码时，要确认项目实际服务的是源码还是构建产物；若页面依赖 dist / hash 包，必须重建并验证实际被引用的产物已经包含修改。
  6. 用户要求“自己检查直到成功”时，检查对象仍必须限于本轮功能目标；不得借机重构或扩展无关链路。
  7. 验证通过后要明确说明跑过哪些检查、哪些没跑；不能把“看起来合理”当作完成。

代码审查与修复范围

  1. 根据审查文档处理问题时，先判断是否由当前分支或当前功能引入；不是当前范围引入的，不要混入本次修复。
  2. 低风险修复应保持原有业务语义，优先增强可观测性、错误记录和边界保护，不要顺手重构大范围逻辑。
  3. 已解决的问题应从临时审查文档中删除或标注清楚，避免新对话重复处理。
  4. 修复前先确认现有行为设计意图，避免把用户明确保留的交互或兼容逻辑当成冗余删除。
  5. 用户刚调过的视觉参数、动效强度、粒子概率和类似数值，不要为了让旧测试断言通过而静默改回；应更新测试断言或先确认设计意图。
  6. 工作区已有修改不等于本轮可随意编辑；必须区分“本轮要修的文件”“用户已有但不相关的文件”“未跟踪笔记/产物”。
  7. 发现自己先前实现方向错误时，优先撤销错误方向的最小补丁，再重新基于当前代码和文档目标设计；不要在错误实现上继续补偿。

需要升级确认的情况

  1. 修改会改变用户数据、删除旧目录、影响启动/关闭/迁移语义时，先停下来确认。
  2. 当前证据不足但要做不可逆改动时，先补证据或请用户确认。
  3. 工作区出现与当前任务直接冲突的用户修改时，先说明冲突并等待指示。
  4. 需要在“兼容旧行为”和“清理技术债”之间取舍时，先说明代价，不要静默替用户决定。
  5. 用户要求撤销但范围不明确，且工作区存在多轮未提交修改时，先确认或用 diff 证据限定范围；不得自行推断为“撤销所有修改”。
  6. 非代码任务如果需要保存产物到仓库路径，先确认保存位置；默认使用未跟踪且被忽略的临时目录，避免污染源码和资源链路。

交互与工作偏好

  1. 用户偏好简短直接的中文指令，如"执行 X""再来一次""提交推送"。不需要先解释脚本内容或确认，直接执行即可。
  2. 提交格式：英文标题 + 中文正文（body）。标题遵循 conventional commits 风格（如 fix(chat): ...）。
  3. 代码删改后用户常追问"是否影响其他链路"，应主动检查跨文件引用和下游消费者，给出明确结论。
  4. 构建前端直接运行 bash build_frontend.sh，无需额外确认。
  5. 用户指定在某个分支上改（如"在 game_test 分支改"）时，必须直接读该分支的实际代码并在此基础上修改，不要分析另一个分支的代码再尝试移植。
  6. 用户纠正方向时，立即撤回错误实现，回到原始要求重新开始，不要在错误方向上继续修补。

提交与工作区

  1. 用户明确要求：.agent 内的文件都不提交。
  2. 如果提交推送，必须带清晰标题；提交前确认 .agent/notes/ 未被纳入 staged。
  3. 工作区可能保留用户自己的测试文件或状态文件；除非用户明确要求，不要清理或提交这些文件。
  4. 提交前检查 git status，区分本次修改、用户已有修改、未跟踪笔记和测试残留。
  5. 禁止使用 git restore .、git checkout -- .、git reset --hard 等宽范围回退来处理局部错误；除非用户明确点名并确认风险。
  6. 需要撤销局部错误时，优先使用 apply_patch 删除具体片段，或对明确文件执行精确回退；操作前后都要看 git diff --stat / git status --short。
  7. .agent 文件是工作记忆，不进入普通功能提交；即使本轮按要求修改了 .agent 文档，也只能在用户明确要求提交文档时单独处理。

文档维护规则

  1. 追加内容前先判断它是否仍会在未来对话中复用。
  2. 不要在每个段落记录日期；只有确有历史追溯价值时才写时间背景。
  3. 不要把单次功能的按钮名、颜色、图片、布局、临时文案写成长记忆；但会影响后续实现判断的产品语义可以短写。
  4. 用短标题和列表组织，确保新对话能在一分钟内读完并知道边界。
  5. 如果某条信息已经能从代码、测试或提交中稳定获得，不要重复长篇描述。
  6. 文档变长时优先删减、归并和去重；保持它像“接手清单”，不要变成聊天档案。