许愿池：把"功能建议反馈框"做成远程发号施令入口

> 📅 2026-10-24 建立 · 状态：方案待确认（未写代码） > > 相关文档： > - quant.aohan.net 站点基座：.claude/CLAUDE.md（部署铁律、小窗适配铁律） > - Agent 执行器底座：learn/量化工程优化/Trae-CLI接入方案与Agent自动化蓝图.md > - 动机同源：learn/LLM学习与应用/07-点子的自来水管道.md（降低"想到"到"做到"的摩擦） > - 小窗适配规范：learn/其他业务/网站设计/小窗尺寸兼容适配规范.md

---

一、需求本质

表面需求是"给网站加一个功能建议反馈入口"，真实需求是：

> 把「改需求」这件事的启动成本，从"找电脑 → 开 IDE → 描述 → 等"压缩到"掏出手机 → 打开自己的网站 → 打一段话 → 发送"。

所以这个功能同时是两件东西：

判定的唯一依据是登录态（_check_auth + _is_admin），不是前端传的字段。前端只决定"显示什么"，后端决定"能不能执行"。

---

二、执行层：三个方案（这是唯一真正的分叉）

页面和数据库怎么做没有争议，工作量和风险全在"谁来把一句话变成能跑的代码"。

方案 A：本机 AI CLI 无人值守（真·全自动）

网页提交 → 写库(pending) → 常驻 worker 轮询 → trae-cli run "任务" 
        → 在 git worktree 里改代码 → 语法检查 + 冒烟 → 合并 → ./restart.sh → 状态回写

• 底座已存在但未就绪：workspace/trae-agent/ 只有源码，没有 .venv、没有 .env、没有 trae_config.yaml（蓝图文档里的 T2/T3 待办仍未完成）。本机也没有 claude / codex / traecli 可执行文件。
• 优点：真后台，人不在线也能跑，最贴合"随时随处"的原始设想。
• 风险最高：无人值守改生产代码；一次性大改动没有 review；token 成本不可控；出错会污染 git 历史。

方案 B：Trae IDE 定时认领（推荐先落地）

网页提交 → 写库(pending) → Schedule 每 N 分钟起一个 Agent 会话
        → 认领最早一条 pending → 在主工作区实现 → 自测 → restart.sh → 状态回写

• 复用当前这套 Agent（Trae IDE + 本文件同款工具链），零额外安装、零密钥配置、上下文最熟（知道 CLAUDE.md 铁律、知道沙箱坑）。
• 依赖 IDE 开着、Schedule 任务在跑；不是"关掉电脑也能跑"，但对"人在外面用手机发需求"这个真实场景已经够用——你发完，回家一看已经做完。
• 必须配套：变更前自动 commit 快照，失败可 git revert。

方案 C：半自动（只做需求整理，不自动改代码）

网页提交 → DeepSeek 拆成结构化需求卡（标题/目标/影响模块/验收标准）
        → 入队 + Server酱推送 → 你在 IDE 里说一句"做第 N 条"

• 最安全、最快能上线，但没解决"不想碰 IDE"的痛点，只是把需求记下来了。

建议：C 的地基 + B 的闭环，A 留接口

• 先上线页面 + 表 + AI 需求拆解 + 推送（1 天内可用，风险为零）。
• 执行器做成可插拔（wish_runner.py 里一个 dispatch(wish_id)），先接 B，A 就绪后加个开关切过去。
• 全自动（A）必须过三道闸才能开：失败自动回滚、单日执行次数上限、只在独立 worktree 分支上改。

---

三、产品形态（页面长什么样）

路由 /wish，页面标题对外叫「许愿池」，副标题"想看什么功能，写下来"。

┌─────────────────────────────────────────┐
│  🔮 许愿池            [我要许愿]         │
│  想看什么功能？写下来，我看看能不能做。   │
├─────────────────────────────────────────┤
│  [全部] [已实现] [开发中] [已收录]        │  ← 筛选 chips（吸顶）
├─────────────────────────────────────────┤
│  ● 开发中   给择时页加一个"策略对比"开关   │
│    一句话说明…                  👍 3     │
│  ─────────────────────────────────────  │
│  ● 已实现   许愿池本身                    │
│    就是你现在看的这个页面        2026-10-24│
└─────────────────────────────────────────┘

• 提交区：一个 textarea + 「发送」按钮。不做标题字段——用户在外面只会打一段话，标题由 AI 生成。
• 列表：卡片流，状态点 + 标题 + 摘要 + 时间 + 点赞数。访客可点赞（同 IP/账号去重）。
• 管理员额外可见：

- 顶部多一个「开发队列」页签 - 每张卡右下角多出操作：开工 / 看日志 / 回滚 / 忽略 - 卡片上直接显示构建进度（排队中 → 改代码 → 自测 → 部署 → 完成）与最近 20 行日志

• 小窗适配（铁律 11）：.page 为唯一滚动容器；chips 栏 sticky;top:0；弹层窄屏 position:fixed 全屏。

> 对外它就是一个体面的 roadmap + 许愿池；对内它是你的远程工单系统。同一套页面，两种身份，不搞两套代码。

---

四、数据模型

新建 adata/aohan/quant/db/wish.py，照 db/messages.py 的写法（CREATE_SQL + 索引 + init_* + 模块级 _ensure_table()，因为 HTTP 线程不走 init_all_tables 的路径已经踩过坑）。

4.1 wish_item（许愿条目）

索引：(status, id DESC)、(is_admin, status)。

4.2 wish_run（一次执行尝试）

一次 wish 可有多条 run（失败重试），页面显示最新一条。

4.3 wish_vote

(wish_id, voter_key, created_at)，voter_key = username 或 sha1(ip+ua) 前 12 位。唯一索引防重复点赞。

---

五、状态机

              ┌──────────── 访客提交 ────────────┐
              ↓                                  │
            [new] ──AI拆解──> [triaged] ──管理员开工──> [building]
              │                  │                      │
              │                  └──管理员忽略──> [ignored] │
              │                                         ↓
              │                                    [verifying]
              │                                      │      │
              │                              成功    │      │ 失败
              │                                      ↓      ↓
              └────────────────────────────> [deployed]  [failed] ──重试──> [triaged]

• 访客条目最高只能到 triaged（已收录），进不了 building。
• deployed 会自动回写一张"已实现"卡片，这就是许愿池的对外门面。
• failed 保留日志，管理员可一键重试或标记放弃。

---

六、安全边界（这块比功能本身重要）

---

七、接口设计

接口写法规格照 unified_server.py 里 /api/messages/read（读 Content-Length → json.loads → 统一 {"ok":bool} 返回，未登录 401）。

POST 速率限制复用现有的 _track_visit 里的 IP 获取方式（X-Forwarded-For 优先，因为经过 Cloudflare）。

---

八、改动清单（精确到文件）

8.1 新增

8.2 修改

8.3 通知

管理员提交后写一条站内消息（复用 db/messages.add_message）+ Server酱推送，内容为"新愿望排队中：<标题>"。执行完成/失败同样推一条。这样手机上提交完能立刻得知结果。

---

九、分期与验收

P0（本次要做，零风险）

• 页面 + 三张表 + 提交/列表/点赞 + AI 拆解 + 站内消息
• 管理员队列页签可看条目（不能自动执行）
• 验收：手机小窗下能提交、能看到自己刚提交的卡片；访客身份提交的条目不出现管理操作

P1（执行器接 B）

• wish_runner.py --once 能认领一条并产出 git 分支 + 日志
• 页面能看实时日志尾巴；成功后自动 restart.sh 并回写 deployed
• 验收：真提交一条小需求（如"给许愿池加个字数统计"），全流程跑通，站点不挂

P2（可选，A 方案）

• 接通 trae-agent（需先补 .venv + .env），改成常驻 worker
• 加三道闸：日限额、worktree 隔离、失败自动回滚

---

十、待你拍板的三件事

• 执行模式：先 C（只整理需求+推送）？还是直接上 B（IDE 定时认领自动做完）？A 全自动暂缓？
• 对外可见性：访客能看到"已实现/开发中"全部卡片，还是只看到已实现的（开发中对你而言是内部工单）？
• 是否需要访客登录：匿名可提交（有刷屏风险）vs 必须登录（门槛高但干净）。