配置、运行与贡献者工具

K. 配置、运行与服务管理

• US-K01 单二进制运行：作为部署者，我希望下载一个匹配平台的二进制就能前台运行，以便减少安装成本。 验收要点：
  • 支持 Linux/macOS、amd64/arm64；
  • 浏览器资源内嵌，运行端无需 Node、Go、tmux 或数据库；
  • webmux 与 webmux serve 均可启动；
  • --log-file 以 0600 文件保存 stdout/stderr，旧文件保留为 .1，启动方关闭管道后仍可运行。
• US-K02 初始化私有配置：作为部署者，我希望自动生成带随机 token 的配置，以便快速准备自己的服务。 验收要点：
  • config init 使用模板与随机 token 创建私有目录和 0600 文件，不向输出打印 token；
  • 默认拒绝覆盖，显式 --force 时原文件保留为 .bak；
  • 支持 --listen 和配置路径；
  • config path 可显示存在状态或 JSON；
  • 未显式 --config 且默认文件缺失时，首次 serve / start 使用同一模板与 token 生成逻辑自动创建，启动输出说明创建/使用的路径并提示用 webmux status --json --reveal-token 查看 token；
  • 并发首次启动通过原子发布只创建一个文件，已有文件不重写；
  • service install 与托盘复用同一逻辑。
• US-K03 检查与覆盖配置：作为部署者，我希望启动前检查配置并用命令行覆盖地址或 token，以便发现配置错误和临时调整运行环境。 验收要点：
  • config check/validate 校验而不启动服务，TOML 语法错误带行列号，可输出 JSON；
  • config show 只读查看磁盘配置，--live 查看已验证运行进程的内存快照；
  • 不可达报错、不回退磁盘，凭据仅输出是否配置；
  • 字段显式默认值仍保留来源且不含 token；
  • 显式指定缺失文件时报错且不会创建，默认文件缺失时 config show/validate 仍按默认值工作，只有 serve / start 会自动生成；
  • --listen、--token 优先且只覆盖本次进程，显式空 token 也能覆盖（非 loopback 地址仍自动生成 token，见 US-A03）；
  • 配置修改需重启生效。
• US-K04 调整会话与提醒行为：作为部署者，我希望配置默认目录、缓冲和状态判断，并单独管理启动命令，以便适配自己的 agent 与资源预算。 验收要点：
  • 支持 default_cwd、scrollback_bytes、idle_after_seconds、prompt_patterns、agent_protocol、bell_attention、program_status，校验正则；
  • 启动命令完全通过自定义配置或显式 argv 提供，原 shell/presets 配置项不再提供内置命令，新安装首次启动在 launch-configs.json 写入常见 agent 预设；
  • 提醒集成方式见 使用指南。
• US-K05 安装后台用户服务：作为部署者，我希望以当前用户安装并启动后台服务，以便不需要一直开着前台终端。 验收要点：
  • service install 使用 Linux systemd 用户服务或 macOS LaunchAgent，无需 sudo；
  • 引用二进制和配置的绝对路径；
  • 默认配置缺失时与首次 serve 共用生成逻辑，创建后重新读取并校验，显式配置必须已存在且有效；
  • 保留必要 PATH 与运行环境。
• US-K06 预览与更新服务定义：作为部署者，我希望先预览服务定义，并明确覆盖旧定义，以便检查安装位置与启动参数。 验收要点：
  • service install --dry-run 只打印定义，不写文件或创建配置；
  • 定义输出失败时返回错误；
  • 已有定义须 --force 替换并重启；
  • 二进制移动后可重新安装更新路径。
• US-K07 启停、诊断与卸载：作为部署者，我希望用统一命令管理后台服务并查看日志，以便维护和排查故障。 验收要点：
  • 提供 start、stop、restart、status、logs、logs —follow/-f、uninstall；
  • 停止、重启、卸载会结束会话；
  • 卸载保留二进制、配置、日志与状态目录；
  • 服务启用不等于端口已监听，应结合状态和日志诊断。
• US-K08 保存仓库清单：作为部署者，我希望指定状态目录并保护其内容，以便重启或升级后仍保留项目登记。 验收要点：
  • state_dir 保存仓库清单、受保护的运行时记录/本机 API 信息及可选 cloudflared 缓存，不持久保存会话或终端输出；
  • 支持 XDG 默认路径；
  • 各领域 JSON 使用统一私有权限、严格限长解码、持久提交与单实例锁；
  • 领域故障保留原文件并隔离，提交不确定时冻结写入；
  • 仓库或偏好存储失败不阻止直接终端工作。
• US-K09 可信远程入口与升级：作为部署者，我希望通过可信 VPN 或 HTTPS 代理访问，并知道升级的影响，以便维护远程终端。 验收要点：
  • listen、token、allowed_origins 配合部署；
  • listen 端口无效、allowed_origins 条目不是 scheme://host[:port] 的精确小写形式（如带尾斜杠、路径或默认端口）时启动即报错；
  • TLS 由外部代理提供，正确保留 Host 并配置 Origin；
  • version 与 help 提供版本和命令信息，version --json 另含控制契约版本且不读取配置；
  • 替换二进制后需重启，重启结束会话但保留仓库登记与磁盘工作树。
• US-K10 定位设置分区：作为使用者，我希望通过分区导航快速找到设置项，以便在桌面和手机上减少长页面翻找。 验收要点：
  • 桌面左侧显示固定分区导航，手机顶部显示可横向滚动的吸顶导航；
  • 提供外观与阅读、快捷指令、启动配置、草稿与暂存、网络、公网访问、Tailscale、安装应用、通知推送、输出预览十个入口；
  • 点击或键盘激活滚动到对应分区并转移焦点，滚动时高亮当前分区；
  • Home Screen App 中吸顶导航按实际顶栏高度定位，不遮挡顶栏；
  • 支持地址片段直达和浏览器前进后退；
  • 定位不卸载表单、不丢失尚未保存的输入。
• US-K11 一键安装：作为部署者，我希望用一条命令安装匹配平台的二进制，并在网络受限时自动尝试镜像，以便不必手动分辨版本、架构和校验步骤。 验收要点：
  • 提供 POSIX sh 脚本，支持 Linux/macOS 的 amd64/arm64；
  • Rosetta 终端优先选择 arm64，Windows 明确引导到 exe/托盘；
  • 默认最新 Release，WEBMUX_VERSION 可固定版本，WEBMUX_INSTALL_DIR 覆盖目录且不自动 sudo；
  • 先 GitHub 直连，再按 WEBMUX_MIRRORS（默认 ghfast.top、gh-proxy.com，空值只用 GitHub）回退，每源有连接、低速与总时限；
  • 二进制和同源 SHA256SUMS 校验通过才原子安装，失败保留旧文件并汇总来源错误，WEBMUX_SHA256 可固定摘要；
  • 安装入口使用 Release 资产、jsDelivr 或 gh-proxy 镜像，不依赖 raw.githubusercontent.com，并说明镜像可看到 IP、同源校验不能证明镜像可信；
  • 脚本只装二进制，不改配置、服务或 shell。
• US-K12 无服务管理器后台启动：作为部署者，我希望在容器、WSL 或没有 systemd / launchd 的环境中让 WebMux 脱离当前 shell 运行，并能用客户端停止，以便不必保持前台终端。 验收要点：
  • webmux start 接受与 serve 相同的参数，以新会话启动子进程并把 stdout/stderr 写入 <state_dir>/webmux.log（0600，旧文件保留为 .1）或显式 --log-file；
  • 等待运行时记录后输出 PID、不含 token 的本机链接与日志路径并退出；
  • 已有实例时幂等打印状态并退出 0；
  • 子进程清除继承的 WEBMUX_SESSION_ID、WEBMUX_LAUNCHER、INVOCATION_ID、XPC_SERVICE_NAME，避免被启动方会话清理并保持 manual 记录，可用 webmux stop 停止；
  • 启动失败输出日志尾部并返回非 0；
  • 生产环境仍推荐 service install。
• US-K13 Linux 安装包：作为 Debian / Ubuntu 或 Fedora 等发行版的用户，我希望用 apt / dnf 安装、升级和卸载 WebMux，并能一条命令设置开机自启，以便按系统惯例管理它。 验收要点：
  • Release 提供 amd64、arm64 的 webmux_<版本>-1_<架构>.deb 与 webmux-<版本>-1.<架构>.rpm，计入 SHA256SUMS，内含与同版本 webmux-linux-<架构> 相同的 /usr/bin/webmux（0755）和用户单元 /usr/lib/systemd/user/webmux.service（0644），无依赖、无安装脚本；
  • 安装、升级、卸载不为任何用户启用、启动或重启服务，运行中的服务升级后到重启才换新版本；
  • 用户执行 systemctl --user enable --now webmux 后以默认配置运行（首次启动生成带随机 Token 的配置）并在登录后自启；
  • 没有 ~/.config/systemd/user/webmux.service 时 webmux service status | start | stop | restart 作用于包内单元，uninstall只禁用并停止它且不删除文件，两者都没有时仍提示先service install；
  • service install 写入的用户定义优先于包内单元。

依据：

• CLI 命令、启动、后台启动
• 配置、配置命令、用户服务
• 安装包配置、包内用户单元、安装包测试
• 部署指南、设置页、设置导航
• 导航浏览器回归。

L. 开发、验证与发布支持

本节描述贡献者使用的工程能力，不增加面向终端使用者的产品承诺。

• US-L01 本地开发与构建：作为贡献者，我希望使用统一命令安装锁定依赖、运行前端和构建内嵌程序，以便复现开发与发布环境。 验收要点：
  • 本地与 CI 使用 .nvmrc 固定的 Node.js 26.12.1；
  • 本地通过官方独立脚本安装 pnpm 12.11.2，CI 使用 pnpm/action-setup；
  • 使用 pnpm frozen lockfile；
  • Vite 代理 API/WebSocket 到独立后端并需配置开发 Origin；
  • make web/build/install 提供检查、打包与安装；
  • CI 将 pnpm store、Go 模块与 Go 构建/测试缓存分开，构建缓存使用按周滚动且随模块文件变化的 key 在 main 刷新。
• US-L02 分层验证与诊断：作为贡献者，我希望运行 Go race、前端单元、浏览器与隔离 E2E 测试，以便验证会话、安全和交互行为。 验收要点：
  • 提供 make test 完整门禁与 make test-fast 快速入口、类型/格式/lint 检查；
  • make test 一次构建前端与 E2E 程序供 E2E/性能复用，本地默认最多 2 个 E2E worker（WEBMUX_E2E_WORKERS 可覆盖，CI 仍为 Ubuntu 2 个、macOS 4 个），Go 默认 -parallel=4（GO_TEST_PARALLEL 可调）；
  • Go 采用 Uber Style Guide 与登记的仓库例外，make check 和 CI 在前端构建后执行 go vet ./...（CI 另以 GOOS=darwin 检查 macOS 构建）及固定 v2.15.0 的 golangci-lint（errcheck/govet/ineffassign/staticcheck/unused），生产零告警，测试仅冻结 errcheck，新增代码零新增告警，豁免只能收紧；
  • CI 先由 Classify changes job 按路径裁剪：仅文档变更只跑格式、文档、持久化与 agent/web 静态守卫，仅 Go 变更跳过前端套件，仅前端变更跳过两个 Go race job 与 Windows 交叉编译，未知路径和工具/依赖变更全量运行；
  • 独立的 E2E runtime job 按冻结锁文件统一安装并打包 Playwright 运行依赖，连同以 omp、opencode、codex、codex-acp、claude、claude-agent-acp 命名的假 ACP agent 一次构建供 Ubuntu 4 个和 macOS 2 个 E2E 分片及两个 Go race job 共用；
  • 分片仅准备 Node 与浏览器，不重复安装 pnpm、前端依赖、Go 或构建应用；
  • 显式预构建路径无效或缺少假 agent 时失败，本地默认仍从源码构建；
  • macOS 原生 Go race（不含静态守卫 archtest/docguard 与 Windows 托盘/WSL 包）与 2 个仅桌面项目的 E2E 分片独立运行，移动端仿真只在 Ubuntu 运行；
  • 性能测试保持单 worker 和 4x CPU 节流；
  • Test result 接受因变更分类而跳过的 skipped，并按分类结果交叉校验所有应运行的 job 均成功；
  • E2E 使用独立后端、目录、端口与假 agent 会话库（假 agent 位于后端 PATH 首位，混合会话用例由它驱动），等待隔离 Shell 提示符就绪后输入命令；
  • 失败有报告与 trace；
  • 测试不连接现有开发服务。
• US-L03 预览 UI 与生成证据：作为贡献者，我希望用真实组件预览极端内容、明暗主题和屏幕尺寸，以便发现溢出并为 UI 变更提供证据。 验收要点：
  • Storybook 提供设计系统、工作区与溢出场景；
  • 浏览器检查布局与可达性；
  • 截图脚本运行真实后端；omp 对话默认从仓库内录制的会话回放，不调用模型，WEBMUX_SCREENSHOTS_RECORD=1 时真实录制并导出新会话；
  • screenshots:hero 由已生成的桌面与手机截图合成 README 主图，缺图时失败；
  • 可见 UI 的 PR 按项目要求附最终实现截图。
• US-L04 基线评测与多平台发布：作为维护者，我希望可复现地测量核心能力并构建各平台产物，以便比较回归和交付版本。 验收要点：
  • make baseline 使用隔离环境评估创建、输入、回放、生命周期、安全等能力，报告通过率与延迟边界；
  • BenchmarkAttachOutput 用真实 PTY → Session → Attach → WebSocket 测量连续输出、控制边界及大块输出的分配，并校验字节与顺序；
  • make release 禁用 CGO，构建 Linux/macOS 服务及 Windows CLI/托盘双架构产物，嵌入服务摘要并生成 SHA256SUMS；
  • make tray 可单独构建托盘；
  • 现有 CI 执行相应质量检查。
• US-L05 分层架构约束：作为贡献者，我希望 Controller 与 Service 的边界和线上 JSON 形状由测试守住，以便越界依赖或协议漂移在 go test 中就被发现，而不是靠评审。 验收要点：
  • go test ./... 包含 internal/archtest：未归类或失效的包、越界依赖、Controller 直接 I/O 或使用未登记的 Service 包级函数、Service 携带 HTTP 状态、编解码非 contract 类型等违规一次列出位置、R0–R10 编号及修复提示；
  • 同一包还检查 internal/acp、internal/hybrid、internal/agentprofile 核心与 web/src（启动配置图标目录除外）的生产代码不出现任何已注册 agent 的名称或可执行文件名，agent 差异只能放在 internal/agentprofile/<agent> 适配器中。纯函数例外需理由且仍被使用；
  • 允许业务整数与非错误对象的领域 Status。R9 检查包级初始化及编码器函数值/方法值，登记函数不能借别名绕过。固定样例覆盖违规与合规写法。141 份线上快照分九组独立运行（另有不可用服务场景单独运行），仅归一化明确动态字段，业务正文、确定性 Git OID、摘要和固定输入保留；
  • 差异可见，有意变更用 -update 重新录制。
• US-L06 前端架构守卫：作为贡献者或 coding agent，我希望在提交前得到复用组件、设计令牌和分层方面的具体报错，以便新增 UI 复用设计系统，而不是重造组件或复制样式。 验收要点：
  • pnpm --dir web check:arch 依次运行 ESLint（@shadcn/lint 与 Svelte 模板规则）、dependency-cruiser、jscpd、knip 与 Vitest 架构测试，make check 与 CI 的格式/构建 job 同样执行；
  • 报错说明应复用的组件、size/variant 或主题令牌；
  • 圆角只允许设计系统刻度（标签 sm、控件 md、内容容器 lg，rounded-xl 仅限 Dialog/AlertDialog/Drawer 弹层），裸 rounded、rounded-2xl 以上与 CSS 固定像素圆角会列出文件位置；
  • 提交的基线为空，任何违规都会失败；
  • 引入带存量违规的新规则时可先记录基线，arch:ratchet 只删除已修复的记录；
  • oxlint 仍是通用 lint。
• US-L07 订阅模型辅助贡献：作为维护者，我希望 Pullfrog 使用自己的 OpenCode Go 订阅运行任务，以便通过指定的 DeepSeek Flash 模型辅助仓库维护。 验收要点：
  • Pullfrog workflow 接收 prompt 并显式指定 opencode-go/deepseek-v4.1-flash 与 effort: high，固定 High 推理等级；
  • 使用 GitHub Actions Secret OPENCODE_API_KEY，不再注入 DeepSeek 直连密钥；
  • 配置说明列出 OpenCode Global 区域授权、Pullfrog BYOK 与 Custom 模型设置以及订阅额度限制。
• US-L08 文档与 spec 治理：作为贡献者或 coding agent，我希望文档和 OpenSpec 规格有可执行的行数、单行长度、体积与目录扇出上限，以便单次读取保持可管理，失败信息直接给出拆分、合并、分段或整理指令。 验收要点：
  • make check 与 CI 的格式/构建 job 运行 make docs-check，即 go test -count=1 ./internal/docguard；
  • docs/**/*.md 与 openspec/specs/**/spec.md 限制为 20–400 行且不超过 48 KiB；
  • 未归档的 openspec/changes/**/*.md 限制为不超过 400 行且不超过 48 KiB（不设行数下限）；
  • openspec/changes/archive/** 不参与行数、单行长度与体积检查；
  • 其余 Markdown 单行不超过 300 列（汉字与全角标点按 2 列计），仅围栏代码块豁免，表格行不豁免；
  • docs/ 与 openspec/ 的每一级直接子目录不超过 20 个，docs/images/、openspec/specs/ 与 openspec/changes/archive/ 的固定布局豁免；
  • 失败信息列出实测值、阈值与 AI 指令，要求按主题拆分或合并、在句子边界分段并保留旧路径为树状索引，规则与例外见 文档治理；
  • 超限时按“重构而不是压缩”整理：信息原文迁移，不删减事实、不为过线挤进已有行或缩窄表格列，接近上限时先拆分再新增，并在 PR 中说明新旧位置对应，原则见 文档治理。
• US-L09 前端代码质量基线：作为贡献者或 coding agent，我希望前端代码质量有成文基线和可执行门禁，以便一致审查响应式状态、异步行为、类型和前后端契约。 验收要点：
  • docs/frontend-style.md 以 Svelte 官方 Best practices 为主规范、Google TypeScript Style Guide 为补充，登记本地化取舍与 7 条日常审查规则；
  • pnpm --dir web lint 以 Oxlint 类型感知运行 Promise 规则，check:arch 运行 Svelte 推荐模板规则；
  • 所有 svelte-check 入口拒绝 warning；
  • check:test 检查源码和顶层 Node 测试并进入 CI；
  • 严格索引、请求体 Zod 校验、Go 强类型枚举及 wire-contract.test.ts 防止契约漂移；
  • 中途 401、上传失败重试、重复提交、Dialog 焦点循环和列表断线恢复各有失败路径回归；
  • AGENTS.md 与 CONTRIBUTING.md 提供入口；
  • 文件遵守 20–400 行与 48 KiB 的文档治理限制。
• US-L10 持久化清单守卫：作为贡献者，我希望新增存储和文件写入入口遗漏登记时自动失败，以便配置与状态清单不会继续漂移。 验收要点：
  • make persistence-check、make check 和 CI 检查全部平台生产 Go 源码中的 JSON/锁名及选定写入函数引用；
  • 别名、函数值、调用次数、登记来源与原因、文档表格均受检查；
  • 负向样例证明漏登和过时登记会失败。运行时 descriptor 与文档、源码入口一致；
  • 所有领域通过统一 handle，逐描述符契约、提交阶段故障与严格读取测试防止退化。清单包含混合会话记录 hybrid-sessions.json（故障策略 unavailable）。
• US-L11 AGENTS.md 体积预算：作为贡献者或 coding agent，我希望 AGENTS.md 保持在固定体积内，以便每次会话加载的常驻指令精简，不常用规则下沉到按需阅读的文档。 验收要点：
  • internal/archtest 的 TestAgentsGuideSize 在 go test ./... 中检查 AGENTS.md 不超过 10 KiB；
  • 超限时失败信息给出实测值与超出字节数，指示 agent 把最不常用的规则原文迁入 docs/agent-rules/<主题>.md、在 docs/agent-rules.md 登记、在 AGENTS.md 留下一行摘要与链接，并满足文档治理限制，且禁止靠删除规则或调高上限通过；
  • TestAgentsSizeViolationMessage 验证恰好超限一字节即失败并包含上述指令；
  • TestAgentsRulePagesExist 保证索引页链接的下沉页面都存在；
  • 下沉页面见 Agent 规则。
• US-L12 文档导航与首页：作为初次访问者、使用者或 coding agent，我希望从 README.md 或 AGENTS.md 出发总能沿链接找到任何一份文档，首页保持简短并直接给出项目介绍、截图、快速开始与获取帮助的入口，以便快速了解项目并在遇到问题时找到答案。 验收要点：
  • make docs-check 运行 TestDocsNavigation：从 README.md、AGENTS.md 沿相对链接遍历，链接到目录时视为到达其 README.md；
  • docs/**/*.md、baseline/*.md、openspec/specs/*/spec.md 与根目录 *.md 必须可达；在途 openspec/changes/ 与归档不要求可达；
  • 上述文件与在途变更中的相对链接必须指向存在的文件，指向 Markdown 的锚点必须匹配 GitHub 生成的标题锚点或 HTML id/name；围栏代码块与行内代码中的示例不受检查；
  • README.md 不超过 170 行、14 KiB，单行不超过 300 列；须含“快速开始”“文档”“获取帮助”二级标题，链接 docs/overview.md、docs/README.md、docs/faq.md、SECURITY.md 与 CONTRIBUTING.md；
  • README.md 至少引用 4 张 docs/images/ 下的界面截图（品牌图除外）、至多 20 张图片，每张 <img> 与 Markdown 图片都有替代文本；
  • 失败信息写明失效链接的行号与原因、不可达文档应登记的索引位置，以及 README 超限时把详细内容迁往 docs/ 的去向；
  • TestNavigationRules 与 TestSlug 用内存目录树固定可达性、失效链接、锚点、代码豁免与 README 各项规则；
  • 文档入口见 文档中心，项目介绍见 项目介绍，帮助见 常见问题与获取帮助，规格索引见 OpenSpec 规格索引。

依据：

• 前端代码质量基线、AGENTS.md、CONTRIBUTING.md
• Go 质量基线、Go lint 配置、数组契约 fixture
• 数组 Zod 用例、推送 API 用例、Node.js 版本
• CI 工具链、Makefile、前端命令
• 贡献指南、Storybook、评测说明
• 真实终端分配基准、CI、E2E 初始化
• 分层清单、agent 名称守卫、架构规则、规则样例
• 线上快照测试、归一化回归测试、分层说明
• 前端架构守卫
• AGENTS.md 体积测试、Agent 规则索引
• 文档导航守卫、文档中心、首页
• ESLint 架构规则、前端分层规则、前端架构测试、文档治理、文档治理规则与样例。

质量基线补充依据：

• ESLint 与 TypeScript 配置、测试类型配置、wire 契约测试
• 新建会话与 Dialog 浏览器回归、主题与可访问性 E2E、上传失败 E2E
• 列表重连 E2E。

Pullfrog 依据：workflow、订阅模型配置。

持久化守卫依据：扫描器、清单校验、负向样例、机器清单、治理说明。

配置诊断依据：来源投影、只读与活快照、诊断测试、共享存储。