Pangolin 文档索引

App 内统一通知收件箱（铃铛+列表），六类：重要/新特性/新闻/到账(个人定向)/版本/活动。单 notices 表 + user_id(NULL=广播)；已读用服务端 last_read_at 水位多端同步；GET /v1/notices(合并广播+定向,unread_count) + POST /read。生产三路：nodectl notice 子命令(手工) / 事件钩子同事务(购买开通·邀请·首充·TG 到账,零孤儿通知) / 发版脚本联动插 version 公告。邮件仅 important+显式 --email(SMTP 直发+email_sent_at 幂等)。不做：APNs/FCM(二期)/逐条已读/偏好开关/六语内容。原型先行：两端通知视图先统一(桌面pill vs 移动icon)再动代码。

用「送 Pro 会员天数」驱动增长，两条并行途径共用发天数原语（applySubscription source=invite/task）。① 邀请两段式双方都得：注册各 +3、被邀请人首充双方再各 +7（每转化 +10/+10）。② 奖励任务首个「加入 Telegram 频道」+3，经 Bot getChatMember 真校验（token 绑号→/tg/webhook→查成员→发）。防刷：自邀请拦截 + invitee 唯一 + dp_uuid 设备去重 + 注册段月度封顶（首充不封）+ telegram_id 全局唯一领。数据：users +invite_code/first_paid_at、referrals、通用 reward_claims。不做现金/多级/退群回收；通知集成留接缝待 Spec③。

去重 + 归位：App 自足、Web 退居次要；每功能一个家。桌面提 Account 为一级侧栏项，移动 Account tab 含设置/联系下钻。收敛联系渠道(×3→1)/语言主题(×2→1)/购买入口(散3→Account)。为「🔔 通知」(顶栏铃铛)+「邀请好友」(账户入口)预留落点。决策：奖励双方都得、兑换码保留、Web 链接保留。后续 ②推广激励 ③系统通知 另立 spec。

pangolin 出口 IP 曾等价于「只有我」，多用户后退化成「所有 pangolin 用户」——家庭内网服务（brain/nas/git/win.51yanmei.com）因此对全体用户敞开。在节点 sing-box 加一道按 dp_uuid 的闸：节点本地 acl.json（照 warp.json 骨架）→ 每个目的地渲染「放行白名单 + 兜底拒绝」一对规则，与 WARP 规则合并而非覆写。控制面/DB/proto/客户端/管理后台一律不动，改动收敛在 internal/agentd/。关键点：失效方向必须 fail-closed（与 WARP 的 fail-open 先例相反）、白名单须同时含设备级与账户级 dp_uuid（否则 /sub 订阅链接把自己锁在外面）、生效走 agent SIGHUP 以免重启踢掉全部在线用户。含四态渲染矩阵、规则顺序三条硬约束、名单维护 runbook、验收清单。

#30。参考 jiu 的 scripts/ci + .gitea/workflows：tag 触发（site-v*/server-v*/client-v*）→ 编译 → 测试 → Gitea release → 部署。runner 混合（nas=官网+服务端容器化 / mac=Android+macOS / windows=Windows）。服务端部署固化 F3/F4「备份→migrate→换二进制→重启→健康检查+回滚」；官网部署 pangolin.yanmeiai.com；客户端 apk/dmg/exe 挂 release 喂官网下载链接。密钥作用域：Apple/token 账户级、部署 key/Android keystore 仓库级。范围 A~F（排除 iOS/#26/#25）。

点 Telegram 进二级页，按 kind 分组（频道/群组/Bot）列多条链接，含 @handle/说明/认证/「打开·加入」动作，全渠道（含邮箱/发卡）统一一张 contact_link 表（靠 url 协议区分 mailto/https/tg）。独立 GET /v1/contact。规则：平台 >1 条链接才进二级，否则点击直达。LINE 同构但先灰置「即将开放」（registry comingSoon 开关，配好即去灰）。不展示成员数、群组=加入。含可点原型。

免费版真卡控（账户级/全设备共享）：连接期倒计时 + 到点自动切断 + 耗尽按钮灰化 + 点击弹广告看完 +10 分钟（累加，每日封顶 120）。桌面硬 10 分钟不可延。服务端 ad_bonus_minutes 累加模型 + ConnectNode 按 remaining 卡控 + TTL 硬切断；占位 DevVerifier。#21。

真正启用套餐设备上限（free 1 / pro 3 / team 10）：卡在登录（非硬拒登，返回 device_limit 信号）+ 选择移除/一键踢最旧 + 服务端按 last_seen 自动清理久不活跃。复用现成 DeleteDevice/ResolvePlan。无 DB schema 变更。#16。

「我的设备」管理（名称/平台/客户端版本/在线/最后登录 + 强制退出/清除登录信息）+ 控制面 sessions 表绑设备 + 数据面每设备 dp_uuid 记账。核心洞察：后端大半已建但 RegisterIfAbsent 未接线致 devices 表空。P1–P5 路线。

把 M2 纸面 PoC 推到真机端到端连通 + 切节点 + KillSwitch（清 TODO 11G）。里程碑 A–F、三处定调。

iOS 隧道从 PoC 桩推到真机连通 + TestFlight；五条工作线 + NE 50MB 内存闸门；iPad 横屏侧栏布局适配。

Windows 端 sing-box 子进程 + wintun 隧道客户端设计。

阅读版；执行真相源 docs/superpowers/plans/2026-07-27-configurable-proxy-phase1.md（Task 0 前置 + 10 任务 TDD，含 checkbox）。Task 0 先合并 main(拿私有分流/reverse_mapping/route_exclude,落后 37 commit)。服务端(1-5)：迁移 000028(routing_profiles per-user) → Profile 类型+Store(双方言) → 校验/规范化(type/CIDR/geo白名单/上限200/去重) → GET/POST /v1/me/routing+openapi → BuildClientConfig 翻译用户规则(层级插私有分流后·geoip前;IP直连并入 route_exclude、域名直连开 reverse_mapping;三模式;nil逐字节不变) → connect 读档案 fail-safe 回退。客户端(6-9)：RoutingProfile model+AccountApi+AsyncNotifier → 分流规则子屏(模式段选/内置/我的规则增删排序/添加弹层/冲突提示) → 设置入口下钻行+双形态导航 → 存档案后自动重连。设计见 configurable-proxy-spec.html。

阅读版；执行真相源 docs/superpowers/plans/2026-07-13-notifications.md（11 任务 TDD，含 checkbox）。后端(1-7)：迁移 000026(notices 表+users.notices_read_at) → notices.Store(广播∪定向合并/已读水位/事务内插) → GET /v1/notices+POST /read(替换空壳)+openapi 扩展 → 四事件钩子同事务(邀请注册/首充/TG任务/购买开通，零孤儿) → notices.Service(发布/撤回/important 邮件兜底幂等) → nodectl notice add/list/revoke → main.go 装配+发版脚本联动插 version 公告。原型与客户端(8-10)：原型先行统一两端通知视图(桌面式pill+未读点)+reward/version/promo 示例 → notices api/provider(未读计数/延迟首拉) → 通知页真实化+铃铛红点接 provider+三新类型六语标签。Subagent 驱动执行。设计见 notifications-design.html。

阅读版；执行真相源 docs/superpowers/plans/2026-07-12-invite-task-rewards.md（14 任务 TDD，含 checkbox）。后端(1-10)：迁移 000024(referrals/reward_claims + source 扩容) → codes.GrantRewardTx 发奖原语 → reward.Store/Service(邀请码+防刷) → 接注册 ReferralHook → 接首充 pay webhook Rewarder → GET /v1/invite → TG 绑定 token → TG webhook getChatMember 真校验 → main.go 装配。客户端(11-13)：invite api/provider → invite_page 真实化+六语 l10n → 注册页邀请码输入(deep-link 预填单列可选后置)。设计见 invite-task-rewards-design.html。

阅读版；执行真相源 docs/superpowers/plans/2026-07-23-private-dest-acl.md（含 checkbox）。设计见 docs/private-dest-acl-design.html。6 个 TDD 任务：①ACL 配置类型 + fail-closed 的 active()（空白名单=拒绝所有人，非「未启用」）→ ②rules() 产出「全部放行→全部拒绝」规则对，两侧目的地条件逐字相同 → ③buildRoute 合并 ACL 与 WARP（四态矩阵；现状 cfg["route"] 是整块覆盖，直接赋值会干掉 WARP）→ ④渲染时读 ACL + 内存/磁盘双层 last-good 兜底（fail-closed 须跨重启成立）→ ⑤SIGHUP 触发热重渲染（重启 agent 会冷启 sing-box 踢掉全部在线用户）→ ⑥配置样例与 runbook。改动收敛在 internal/agentd/ + cmd/agent，零 migration/零 proto/零客户端改动。

阅读版；执行真相源 docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md（含 checkbox）。用 ds-flow 把 Flutter 五端 + 官网 + 用户中心收口到「设计单源·代码镜像·静态闸拦漂移·golden/fidelity 双级像素验收兜底」。非从零 bootstrap（已约 65% 达标）：补原型三件套（atoms.css/icons.js/index.html 登记页）+ Web 共享原子层去重（各自实现+同源闸）+ 硬编码色/fidelity 闸 + 启用 pre-commit。6 阶段：CLAUDE.md → 原型单源 → Web token 同源 → Web 原子对齐 → Flutter golden 补齐 → 闸挂满。主题保持 light/dark。

阅读版；执行真相源 docs/superpowers/plans/2026-07-06-control-plane-tls-tunnel.md（含 checkbox）。把控制面 API 从明文 http://103.119.13.48:8080 迁到 https://api.yanmeiai.com（cloudflared 出站隧道前置，源站仅绑 127.0.0.1，数据面 sing-box REALITY :443 全程不动）。6 任务：CF Tunnel 供给 → 客户端切 https/Android 去明文 → CI 守护禁明文 → PANGOLIN_PUBLIC_URL 切 https → 退役明文口（收 loopback，带上线顺序闸）→ 文档。

阅读版；执行真相源 docs/superpowers/plans/2026-07-05-cicd.md（含 checkbox）。三期 11 任务：Phase1 基座+官网+服务端(无签名可立即上线，服务端固化 F3/F4 备份/迁移/回滚) → Phase2 Android(接 release keystore 签名，解锁下载链接) → Phase3 macOS 公证 dmg + Windows 安装包。runner 混合 nas/mac/windows；密钥已建(对齐 jiu)。设计见 cicd-design.html。

阅读版；执行真相源为 docs/superpowers/plans/2026-06-29-device-session-management.md（含 checkbox）。P1 设备注册打通 → P2 sessions表+在线/最后登录 → P3 强制退出/清除 → P4 每设备流量 → P5 2FA信任(future) → P6 UI重做。

11 个任务：Go 1.24.3 工具链 → 构建 libbox.aar → 解析真实 API → Dart 接线 → 修原生编译 → 模拟器端到端 → 统计 → 切节点 → KillSwitch → 真机验证。

阅读版；执行真相源为 docs/superpowers/plans/2026-06-22-ios-ipad-support.md（含 checkbox）。6 阶段 12 任务。

Windows 客户端的分步实现计划。

阅读版；执行真相源为 docs/superpowers/plans/2026-06-24-stats-overhaul.md（含 checkbox）。三期：四端实时统计修复 → 每设备归因+GB综合配额 → 统计页重设计(上聚合·下分设备)。

场景锁定「个人账号 + 含 NetworkExtension 的 VPN + 大陆散户」。官方七渠道评级(TF ⭐⭐⭐⭐ 唯一现实可行 / Ad Hoc·企业·ABM·EU DMA·PWA·sideload 各为何不行)+ 国内灰产梯度(超级签 16–20 元/台最稳 / 企业签共享掉签严重 / 独立稳定签 / MDM 签 / TF 代上架)+ 稳定性成本对比表 + 合规封号风险 + 给 Pangolin 的落地建议(TF 打门面 + 超级签兜底 + 落地页重装引导,主账号务必隔离)。附中英来源 URL。2026-07 联网调研。

Task 8 终验：server/client 全量测试矩阵结果（含新增 SQLite 文件库带数据升级彩排 + MySQL 8 容器验证 000021 MODIFY ENUM）、OpenAPI 新端点登记、Self-Review 取舍、联调 checklist、部署附录（pay 种子/biz 配置/pangolin env/迁移顺序）。附带发现一处既有的 wangjia/codes 本地路径依赖会阻断异机构建，登记为部署前置阻断项。

Flutter 五端 + 官网 + 用户中心的设计系统治理全景：一次 UI 改动标准路径、目录地图、三层真相源模型、令牌 codegen、四道静态闸「违规谁拦」、像素验收（golden 双主题 + fidelity 待建）、响应式五端、规则速查。原型单源 design/prototype/（tokens/atoms/icons/index.html）、check-ds/check-l1-sync/check_ds_code/codegen-drift 四闸进 CI、golden 全量 34 绿含 CJK。

核心链路精读式审查，13 项发现分 P0/P1/P2：明文 HTTP、SQLite 零备份（P0）；同机换账号 403 死结、disconnect 撤错凭证、用量取走即焚、Redis 重启全员掉线、argon2id OOM（P1）；留存/UTC 日界/三时钟口径等（P2）。附「做得好的」与处理顺序建议。

「怎么写才好测」——开发规范作为可测试性前置条件。五支柱（接缝即接口/契约单源/纯逻辑分离/错误是值/可观测）+ 支柱↔测试层咬合矩阵图 + 反例→真实bug→对应支柱对照表。与测试框架文档咬合。

多端项目可复用的分层测试方法论（L0 契约→L4 E2E）+ 四类诉求(界面一致/交互/数值/后端记账)→层→工具→量化指标映射 + 五张架构图（金字塔/契约接缝/CI 流水线/E2E 拓扑）+ ⑩「已知缺口/测试盲区」单一跟踪源（没测什么·为什么·何时补）。

逐功能盘点验证五端是否正确：A 共享逻辑+后端(控制面 21 包/数据面渲染+记账/Flutter 共享)，每行「现有能力→已覆盖+怎么覆盖→欠缺→只能人工」；B 平台隧道层五端矩阵 + 每端真连通验收清单(出口IP变化/DNS劫持/分流/记账对账/KillSwitch/切节点)。配套 test-architecture.html 的「逐功能」视角。

客户端两处"上传/下载"为何对不上：连接页实时来自内核 Clash API 全局吞吐(/traffic+/connections)含直连；统计页累计来自服务端节点 v2ray_api per-user 计数仅代理。差额=直连流量(国内站/分流)，设计使然非 bug；附对账口径警示(不能拿连接页含直连的数去对节点计数)。

断网保护 L0–L3 分级模型 + 各平台能力天花板 / 当前实现矩阵。KillSwitch 决策依据。

Pangolin 整体技术选型与架构方案。

sing-box 内核在各端的内嵌方式调研。

VPN 黑盒测试方法与口径调研。

国内外站点矩阵 + 延迟/连通性测试计划。

连接页"延迟"= 内核 urltest(非直连实测)。根因链:服务端配置无 clash_api、libbox 单 client Group 不回调、Dart 广播流抢 EventChannel sink、连接态直连实测假值。各端(macOS/iOS/Android/Windows)注入 clash_api + 本地 HTTP 取法 + 排障打点 + libbox 构建前置(Android 要 JDK 17、包名 io.nekohasekai.libbox)。

gitea Actions self-hosted runner 记录:决定用 1 个(mac-pangolin-2,项目级·mac host·label nas·复用 jiu relay)、已删 orphan 的清理命令、launchd 持久化 + 单点韧性(runner 离线 Telegram 告警)。CI 首跑 run #298。

PacketTunnel 系统扩展无法激活的三个叠加配置 bug 排查与修复。

macOS 原生 System Extension 隧道方案说明。

节点重装/重建的操作检查清单。

调度器运维手册。