docs: sync genarrative shared skills

.hermes/skills/genarrative-profile-features/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: genarrative-profile-features
+description: 在 Genarrative “我的”页签新增或修改个人中心入口、独立 profile 路由、反馈/记录/设置类页面时使用。
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [Genarrative, profile, 我的页签, 前端, 路由, 反馈]
+    related_skills: [writing-plans, test-driven-development]
+---
+
+# Genarrative “我的”页签功能接入
+
+用于在 Genarrative 平台“我的”页签新增或修改入口，以及把入口接到独立页面阶段/路由。例如：帮助与反馈、反馈记录、个人设置、账号相关轻量页面。
+
+## 适用场景
+
+- 在“我的”页签新增快捷入口或卡片按钮。
+- 点击入口后进入独立页面，而不是在当前面板下方展开内容。
+- 新增 `/profile/...` 路由或 `SelectionStage`。
+- 新增移动端优先的个人中心子页面组件。
+- 修改 `RpgEntryHomeView`、`PlatformEntryFlowShellImpl`、`appPageRoutes` 等前端 profile 链路。
+
+## 必读约束
+
+1. 按项目约束：先检查/补齐文档，再落地工程修改。
+2. UI 面板保持清爽，不要默认堆功能说明文案。
+3. 点击按钮弹出/进入独立面板的设计，不要实现成在当前面板下方追加内容。
+4. 移动端优先，同时兼顾网页端容器宽度。
+5. 包含中文的文件优先局部补丁，修改后运行编码检查。
+6. 非必要不新建系统；优先复用现有平台入口、阶段和路由机制。
+
+## 代码接入路径
+
+常见文件：
+
+- `src/components/rpg-entry/RpgEntryHomeView.tsx`
+  - “我的”页签 UI 主入口通常在此。
+  - 新增入口时优先扩展 props，例如 `onOpenFeedback?: () => void`。
+  - 在现有快捷入口区新增 `ProfileShortcutButton`，保持图标、label、subLabel 风格一致。
+
+- `src/components/platform-entry/platformEntryTypes.ts`
+  - 若需要独立页面阶段，扩展 `SelectionStage` union。
+  - 例如新增 `'profile-feedback'`。
+
+- `src/routing/appPageRoutes.ts`
+  - 在 `STAGE_ROUTE_ENTRIES` 添加 `/profile/...` 路由映射。
+  - 验证 `resolveSelectionStageFromPath()` 与 `resolvePathForSelectionStage()` 双向一致。
+
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+  - 引入新页面组件。
+  - 新增打开函数：必要时先检查登录态，未登录调用 `authUi?.openLoginModal()`。
+  - 打开 profile 子页时同步 `setPlatformTab('profile')`，再 `setSelectionStage(...)`。
+  - 当 `selectionStage` 直接由路由进入 profile 子页时，用 `useEffect` 同步当前 tab 到 `profile`。
+  - 在主渲染分支中为新阶段渲染独立 `<motion.div>` 页面；返回时回到 `platform` 阶段并保持 `profile` tab。
+
+- `src/components/platform-entry/<FeatureView>.tsx`
+  - 页面组件可放在 platform-entry 下，与 shell 阶段渲染保持一致。
+  - 表单首版没有后端接口时，可通过可选 `onSubmit` prop 暴露提交 payload，并在组件内展示成功/失败态；注释说明后续替换为 API 调用。
+
+## 推荐实施顺序
+
+1. 读取 `.hermes/plans/...` 或产品文档，确认入口、路由、页面行为。
+2. 若现有文档不足，先在 `docs/prd/` 增加可编码落地的 PRD。
+3. 增加 `SelectionStage` 与 `appPageRoutes` 映射，并先跑 `npm run typecheck`。
+4. 新建独立页面组件，尽量通过 props 暴露 `onBack`/`onSubmit`，避免直接耦合全局状态。
+5. 在 `RpgEntryHomeView.tsx` 增加入口 prop 与按钮。
+6. 在 `PlatformEntryFlowShellImpl.tsx` 串联导航、登录态、阶段渲染和返回逻辑。
+7. 增加基础测试：路由解析、页面字段渲染、关键交互/校验、返回按钮。
+8. 跑编码检查、类型检查和相关 vitest。
+9. 分阶段 commit；用户要求更新工作区时再 push。
+
+## 测试与验证命令
+
+常用命令：
+
+```bash
+npm run check:encoding
+npm run typecheck
+npx vitest run src/routing/appPageRoutes.test.ts src/components/platform-entry/<FeatureView>.test.tsx
+# 或项目脚本：
+npm run test -- --run src/routing/appPageRoutes.test.ts src/components/platform-entry/<FeatureView>.test.tsx
+```
+
+如果新增/修改中文文档或中文 UI，`check:encoding` 必跑。
+
+## 参考案例
+
+- `references/profile-feedback-entry-2026-05-08.md`：帮助与反馈入口案例，覆盖文档、路由阶段、独立页面组件、“我的”页签按钮、shell 导航、测试和验证命令。
+
+## 常见坑
+
+1. 只在 `RpgEntryHomeView` 新增按钮但没有接 shell 导航，导致点击无效果。
+2. 只新增 `SelectionStage` 但忘记 `appPageRoutes`，导致刷新/直达路由不能恢复页面。
+3. 直达 `/profile/...` 时没有同步 `setPlatformTab('profile')`，底部 tab 状态与页面不一致。
+4. 把反馈/设置表单插到“我的”面板下方，违背独立页面体验。
+5. 没有测试 `resolveSelectionStageFromPath`/`resolvePathForSelectionStage`，后续路由改动容易回归。
+6. 中文页面或文档改动后忘记编码检查。

.hermes/skills/genarrative-profile-features/references/profile-feedback-entry-2026-05-08.md

@@ -0,0 +1,80 @@
+# 帮助与反馈入口案例（2026-05-08）
+
+本案例来自 Genarrative “我的”页签新增反馈入口与独立反馈页实现。
+
+## 目标
+
+- 在“我的”页签新增“反馈”快捷入口。
+- 点击后进入独立路由 `/profile/feedback`。
+- 页面按移动端参考图实现“帮助与反馈”表单：问题描述、上传凭证、联系电话、提交、查看反馈与投诉记录。
+
+## 关键文件
+
+- `docs/prd/PROFILE_FEEDBACK_ENTRY_PRD_2026-05-08.md`
+- `src/components/platform-entry/platformEntryTypes.ts`
+- `src/routing/appPageRoutes.ts`
+- `src/components/platform-entry/PlatformFeedbackView.tsx`
+- `src/components/rpg-entry/RpgEntryHomeView.tsx`
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- `src/routing/appPageRoutes.test.ts`
+- `src/components/platform-entry/PlatformFeedbackView.test.tsx`
+
+## 落地顺序
+
+1. 先补 PRD，避免从参考图直接猜代码细节。
+2. 在 `SelectionStage` 中新增 `'profile-feedback'`。
+3. 在 `STAGE_ROUTE_ENTRIES` 添加：
+   - `['profile-feedback', '/profile/feedback']`
+4. 新建 `PlatformFeedbackView`：
+   - `onBack: () => void`
+   - `onSubmit?: (payload) => void | Promise<void>`
+   - 内部维护描述、联系电话、上传图片预览、错误态、成功态。
+   - 首版没有后端接口时，`onSubmit` 为后续 API 接入点。
+5. 在 `RpgEntryHomeViewProps` 添加 `onOpenFeedback?: () => void`。
+6. 在“我的”页签快捷入口区新增 `ProfileShortcutButton`：
+   - `label="反馈"`
+   - `subLabel="帮助与反馈"`
+   - `onClick={onOpenFeedback}`
+7. 在 `PlatformEntryFlowShellImpl`：
+   - import `PlatformFeedbackView`
+   - 新增 `openProfileFeedback`
+   - 未登录则 `authUi?.openLoginModal()`
+   - 已登录则 `setPlatformTab('profile')` + `setSelectionStage('profile-feedback')`
+   - 直达阶段时 `useEffect` 同步 `profile` tab
+   - 渲染 `selectionStage === 'profile-feedback'` 的独立 `<motion.div>`
+8. 增加测试：
+   - 路由双向解析
+   - 页面字段渲染
+   - 描述低于 10 字不提交
+   - 提交时 trim payload
+   - 顶部返回按钮调用 `onBack`
+
+## UI 参考要点
+
+- 移动端优先，页面最大宽度约 30rem。
+- 浅灰背景，白色圆角卡片。
+- 顶部标题：`帮助与反馈`。
+- 分区标题：`反馈问题`。
+- 问题描述 placeholder：提示填写 10 字以上，勿填身份证号等隐私。
+- 字数计数：`0/200`。
+- 上传凭证：最多四张，上传占位显示 `上传凭证` 和 `(最多四张)`。
+- 联系电话：选填。
+- 主按钮：蓝色圆角 `提交`。
+- 底部链接：`查看反馈与投诉记录`。
+
+## 验证命令
+
+```bash
+npm run check:encoding
+npm run typecheck
+npx vitest run src/routing/appPageRoutes.test.ts src/components/platform-entry/PlatformFeedbackView.test.tsx
+# 或
+npm run test -- --run src/routing/appPageRoutes.test.ts src/components/platform-entry/PlatformFeedbackView.test.tsx
+```
+
+## 已踩坑/经验
+
+- `appPageRoutes.test.ts` 若已有历史内容，写入测试时注意不要误删旧用例；最终 commit 里出现 “insertions + deletions” 时要检查是否覆盖了既有测试。
+- 页面组件里的图片预览需要在移除或卸载时 `URL.revokeObjectURL`，避免泄漏。
+- 对隐藏 file input 的测试可以先不强行覆盖，首版覆盖表单字段、校验和 payload 更稳定。
+- 如果用 `authUi` 对象作为 callback 依赖，需确认引用稳定性；现有 shell 中可接受，但复杂化时考虑拆出具体字段依赖。