Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,9 +174,17 @@ GitHub authentication remains outside that database:
an explicit reconcile. Rebind and repair transactions must reject changing an
active binding to another Gist. Preserve historical orphan queues without
restoring Workspace switching.
- A user-confirmed **Reset this device** is a separate recovery operation. It
atomically clears the current binding, cached business snapshot, and complete
active queue, while preserving historical orphan queues, quarantined evidence,
and the monotonic fencing counter. It must reject changed state and an active
dispatcher lease. Reset never writes to GitHub; only a subsequent explicit
connection may run unbound discovery or initialize an empty Workspace.
- Cloud refresh uses compare-and-swap checks so a concurrent edit cannot be
silently discarded. Abandoning active pending work requires confirmation to
discard the complete queue and reload the latest original cloud document.
silently discarded. Ordinary cloud reload requires confirmation before
discarding the complete active queue and loading the latest original document.
Stale reads or dispatchers must not restore a binding abandoned by device reset,
including when cross-tab notifications are unavailable.
- One dispatcher owns a persisted lease with an owner ID, monotonically allocated
fencing token, expiry, and heartbeat. Web Locks and BroadcastChannel are
optional coordination aids, not correctness boundaries.
Expand Down Expand Up @@ -207,7 +215,9 @@ GitHub authentication remains outside that database:
preview and confirmation. Unbound setup may inspect an explicit original Gist
ID; ambiguous discovery requires that ID. Bound startup and reconnection must
read only the original Gist, never choose or create another one. Legacy checks
require an explicit ID and do not create a Gist.
require an explicit ID and do not create a Gist. A deliberate device reset may
remove the binding before a new connection; it must prevent legacy storage from
restoring the abandoned binding or uploading the old cache.
- `workspace.migrate` is an internal, source-hash-checked browser mutation. It
preserves the original Gist, output bytes, filenames, and publication metadata;
it does not regenerate or republish outputs. Pending/repair evidence must be
Expand Down
21 changes: 21 additions & 0 deletions docs/wiki/Changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,27 @@ production deployment and real-provider acceptance require separate evidence.

## Unreleased

### 2026-10-31 - Explicit device reset and fresh connection

- Added a confirmed Settings recovery action for devices whose original Gist was
deleted or is inaccessible, including signed-out and cloud-error states.
- Reset atomically removes the current binding, cached business data, and complete
active queue; preserves historical queues and quarantined evidence; and rejects
active delivery or concurrent changes. Stale tabs cannot restore the old binding.
- Kept reset local: authentication clears only after storage commits, and a
separate connection loads cloud data or initializes an empty Workspace.
- Retry a concurrent cloud load once against the original Workspace when another
tab updates local delivery state; a reset or changed binding still stops stale loads.

### 2026-10-31 - Read-only Gist file viewer

- Made Gists read-only for every file kind, removing output deletion and stale
bootstrap marker cleanup controls and handlers. Kept refresh, file links,
link copying, file classification, and bootstrap warnings.
- Added English and Chinese guidance to manage publications in Aggregation or
Client Exports, with browser coverage for viewing and refreshing files without
submitting cloud mutations. Existing repair states still require diagnosis.

### 2026-10-28 - Primer interface and interaction system

- Unified the six routes around the approved GitHub-style concepts: white/dark
Expand Down
16 changes: 16 additions & 0 deletions docs/wiki/Changelog.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,22 @@

## 未发布

### 2026-10-31 - 显式设备重置与重新连接

- 在设置中增加需确认的恢复入口,支持原 Gist 已删除或不可访问、退出登录和云端加载失败的场景。
- 以事务清除当前绑定、本机业务缓存和当前完整队列;保留历史队列与隔离证据,
正在发送或并发变化时拒绝重置,旧标签页不能恢复已放弃的绑定。
- 重置仅作用于本地,存储提交后才清除认证;用户再次连接时才加载云端或初始化空工作区。
- 并行打开多个标签页时,本机发送状态的正常并发更新会触发一次原工作区的云端重读;
重置或绑定变化仍会阻止旧加载恢复数据。

### 2026-10-31 - Gists 文件页面改为只读

- 所有类型的 Gist 文件均只读,移除输出删除和过期引导标记清理按钮及处理逻辑;
保留刷新、文件链接、复制链接、文件分类和引导状态提示。
- 增加中英文说明,引导到聚合或客户端导出页面管理发布,并通过浏览器测试验证
查看和刷新文件不会提交云端变更。已有修复状态仍需单独排查。

### 2026-10-28 - Primer 界面与交互系统

- 按已确认的 GitHub 风格概念稿统一六个页面:明暗主画布、更清楚的页面标题、
Expand Down
33 changes: 29 additions & 4 deletions docs/wiki/User-Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ empty Workspace, then recent resources and confirmed publication metadata.

| Page | Purpose |
| --- | --- |
| `/auth` | Connection, token, delivery status, cloud reload, migration, and diagnostics |
| `/auth` | Connection, token, delivery status, cloud reload, device reset, migration, and diagnostics |
| `/nodes` | Nodes and subscriptions, tags, search, filters, and batch import |
| `/aggregate` | Rule editing, preview ordering, publish targets, and publication |
| `/exports` | sing-box configuration preview, copy, download, and publication |
| `/gists` | Output files, raw links, and cleanup |
| `/gists` | Read-only cloud file list, raw links, and link copying |

Import one URI per line or paste base64 subscription content. Preview and
resolve duplicates before adding. Aggregates select nodes and subscriptions,
Expand All @@ -58,8 +58,11 @@ a file creates a new URL; review the cleanup result before removing the old file
Node edits do not automatically republish existing aggregate or sing-box files.

Configuration and outputs are committed together through the coordinator.
`subman.json`, `subman.v1.backup.json`, and `subman.bootstrap.json` are reserved;
they cannot be outputs or be removed in the file manager.
The Gists page is read-only for all files, including managed outputs, external
files, and bootstrap markers. Use Aggregation or Client Exports to manage
publications; file preview, link copying, and refresh remain available in Gists.
`subman.json`, `subman.v1.backup.json`, and `subman.bootstrap.json` are reserved
and cannot be outputs.

## Delivery and recovery

Expand All @@ -82,6 +85,28 @@ they do not export business data or credentials. There is no browser business
JSON backup/restore, local overwrite/merge, manual push, or Workspace switching.
For operator procedures, see [operations and repair](../workspace-v2-operations.md).

## Start again after removing your Gist

Disconnect removes your token but keeps this device's Workspace binding and
pending changes. Reconnecting still reads the original Gist, even when it is
unavailable. A GitHub 404 can also mean the token cannot access it.

If you deliberately deleted the original Gist or want to abandon this device's
current connection, open Settings and choose **Reset this device**. The control
is available while signed out or when cloud loading fails. Close other SubMan
tabs, then review the confirmation: reset removes the current binding, cached
business data, and the complete current pending queue. Unconfirmed changes in
that queue will be lost. Historical queues and quarantined recovery evidence
remain available in Sync recovery; existing cloud files are unchanged.

After a successful reset, enter your token and choose **Connect** again. SubMan
finds existing cloud data or, if none exists, initializes an empty private
Workspace. Reset itself never creates or deletes a Gist or uploads an old cache.
The local reset affects other SubMan tabs on the same site. If delivery is active,
wait for it to finish and retry; if state changes during confirmation, review the
new state before trying again. A failed storage transaction does not report a
successful reset or clear authentication.

## Backend automation

The public API supports health and node CRUD/by-key updates. Start with the
Expand Down
24 changes: 20 additions & 4 deletions docs/wiki/User-Guide.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,11 @@ SubMan 查找描述为 `SubMan-Data`、包含权威文档 `subman.json` 的私

| 页面 | 用途 |
| --- | --- |
| `/auth` | 连接、Token、发送状态、云端重载、迁移和诊断 |
| `/auth` | 连接、Token、发送状态、云端重载、设备重置、迁移和诊断 |
| `/nodes` | 节点与订阅、标签、搜索、过滤、批量导入 |
| `/aggregate` | 规则编辑、预览排序、发布目标与发布 |
| `/exports` | sing-box 配置预览、复制、下载和发布 |
| `/gists` | 输出文件、原始链接和清理 |
| `/gists` | 只读云端文件列表、查看与复制原始链接 |

每行粘贴一个 URI,也可导入 base64 订阅内容;预览并处理重复项后再添加。
聚合规则可选择节点和订阅、排除标签、过滤协议、正则重命名、添加地区旗帜,
Expand All @@ -46,8 +46,9 @@ SubMan 查找描述为 `SubMan-Data`、包含权威文档 `subman.json` 的私
同一 Gist 和文件名可保持原始订阅 URL 稳定;重命名会产生新 URL,删除旧文件前先查看清理结果。
修改节点后不会自动重新发布现有聚合或 sing-box 文件。

配置与输出由协调器一并提交。`subman.json`、`subman.v1.backup.json` 和
`subman.bootstrap.json` 为保留文件,不可用作输出,也不能通过文件管理器删除。
配置与输出由协调器一并提交。Gists 页面中的所有文件均为只读,包括托管输出、外部文件
和引导标记。请在聚合或客户端导出页面管理发布;Gists 保留查看文件、复制链接和刷新功能。
`subman.json`、`subman.v1.backup.json` 和 `subman.bootstrap.json` 为保留文件,不可用作输出。

## 发送与恢复

Expand All @@ -63,6 +64,21 @@ SubMan 查找描述为 `SubMan-Data`、包含权威文档 `subman.json` 的私
浏览器不提供业务 JSON 备份/恢复、本地覆盖/合并、手动推送或工作区切换。
操作人员的修复步骤见[运维与恢复](../workspace-v2-operations.zh-CN.md)。

## 删除 Gist 后重新开始

断开连接只清除 Token,保留此设备的工作区绑定和待确认变更。重新连接仍会读取原 Gist,
不会因其不可用而自动换一个。GitHub 返回 404 也可能表示 Token 无权访问它。

如果已主动删除原 Gist,或决定放弃此设备当前的连接,可在设置中选择**重置此设备**。
退出登录或云端加载失败时也能使用这个入口。先关闭其他 SubMan 标签页,再检查确认说明:
重置会清除当前绑定、本机业务缓存和当前完整待发送队列,队列中尚未确认的变更会丢失。
历史队列与已隔离的修复证据仍保留在“同步恢复”中,已有云端文件不变。

重置成功后,重新输入 Token 并点击**连接**。SubMan 会查找已有云端数据;不存在时,
初始化空的私有工作区。重置本身不会创建或删除 Gist,也不会上传旧缓存。
本地重置会影响同一站点的其他 SubMan 标签页。若有变更正在发送,等待其结束后重试;
若确认期间状态发生变化,应重新检查后再操作。存储事务失败时不会报告重置成功或清除认证。

## 后端自动化

公共 API 支持健康检查和节点 CRUD/按外部键更新。参阅
Expand Down
35 changes: 35 additions & 0 deletions docs/workspace-v2-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ rollback for the Workspace Schema V2 coordinator.
- The browser has one cloud binding, with no Workspace list or switching. Both
rebind and queue-repair transactions reject replacing an active binding with
another Gist, including competing browser tabs and legacy recovery paths.
A confirmed device reset may explicitly remove the binding before a separate
fresh connection; it never selects or creates a replacement Gist itself.
- Startup loads the latest cloud document before enabling business pages. Login
and token replacement retain the existing Gist identity; a failed lookup must
never fall through to another Gist or create a new one. An ambiguous initial
Expand Down Expand Up @@ -276,6 +278,39 @@ discarded; timestamps never authorize overwrite and remote tombstones stay
protected. Logout clears authentication and stops delivery without deleting the
binding, cache, pending mutation identities, or recovery evidence.

## Device Reset After An Unavailable Gist

Ordinary reconnect remains pinned to the original Gist. A 404 does not prove
deletion: it may also reflect missing access. First check the token and original
Gist if recovery is intended. If the user deliberately removed it or chooses to
abandon the current local connection, Settings offers **Reset this device** even
without authentication or a successful cloud load.

The user must confirm loss of the current cached business snapshot and complete
active queue. Close other SubMan tabs before confirming. In one
`WorkspacePersistence` transaction, reset compares the inspected binding,
snapshot, and active queue, rejects an unexpired active dispatcher lease, clears
that binding and complete queue, and writes an empty unbound snapshot. It retains
historical orphan queues, quarantine metadata and inaccessible raw evidence, and
the monotonically allocated fencing counter. It records completed migration so
legacy localStorage cannot restore the abandoned binding or cache.

The initiating tab clears authentication only after the transaction commits.
Other same-origin tabs refresh their persistent state; delayed cloud reads,
captured queue heads, and delivery acknowledgements cannot restore the old
binding. Persisted compare-and-swap and fencing checks enforce this even when
cross-tab notifications are unavailable. An active-delivery or concurrent-change
rejection requires waiting or refreshing and a new confirmation; unavailable or
failed storage remains fail-closed without a success report.

Reset sends no GitHub or coordinator mutation requests, deletes no cloud files,
and does not reconnect automatically. The user subsequently enters a token and
chooses **Connect**. Unbound discovery then loads existing cloud data or creates
an empty private bootstrap Gist and initializes it through the coordinator. The
discarded browser cache is never uploaded as business authority. Safe historical
queue evidence remains in Sync recovery and is never automatically rebound or
delivered.

## Leases, Retry, And Upstream Failures

Each Workspace dispatcher acquires a persisted lease with a random owner ID,
Expand Down
26 changes: 25 additions & 1 deletion docs/workspace-v2-operations.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@
- 所有能改变配置的浏览器和 Server API mutation 经过协调器;公共 API 契约不变,
浏览器 mutation 是内部协议,页面/API 不直接 PATCH 配置。
- 浏览器只绑定一个云端 Gist,没有工作区列表/切换。重绑和队列修复事务也拒绝替换已有绑定,
包括跨标签页与旧恢复路径。
包括跨标签页与旧恢复路径。用户确认的设备重置可先明确移除绑定,再单独重新连接;
重置本身不选择或新建替代 Gist。
- 启动先读取最新云端再开放业务编辑;登录/替换 token 保留原 ID。
原 Gist 查询失败不能另选/新建;初次发现多份候选必须填写原 ID。
- `subman-workspace` IndexedDB v1 通过 `WorkspacePersistence` 在同一事务中保存缓存、
Expand Down Expand Up @@ -180,6 +181,29 @@ Token 不进入该数据库。默认 sessionStorage;明确选择 Remember toke
domain conflict/修复证据继续阻塞;时间戳不赋予覆盖权,墓碑仍有效。
退出登录只清认证并停止发送,不删绑定、缓存、mutation 身份或证据。

## 原 Gist 不可用时重置设备

普通重新连接继续锁定原 Gist。404 不能证明它已删除,也可能是缺少访问权限;
若希望恢复原数据,应先检查 Token 和原 Gist。用户主动删除原 Gist,或决定放弃当前本地连接时,
可在设置中选择**重置此设备**,无需先登录或成功加载云端。

用户必须确认丢弃当前本机业务缓存和完整当前队列,建议先关闭其他 SubMan 标签页。
重置通过一个 `WorkspacePersistence` 事务比较已检查的 binding、snapshot 和当前 queue,
拒绝尚未到期的当前 dispatcher 租约,然后清除当前绑定与完整队列,并写入空的未绑定快照。
历史 orphan 队列、隔离元数据与不可直接访问的原始证据、单调分配的 fencing 计数继续保留。
迁移状态标记为完成,避免旧 localStorage 重新恢复已放弃的绑定或缓存。

发起重置的标签页仅在事务提交后清除认证;同源其他标签页重读持久状态。
延迟返回的云端读取、已捕获的队列头和发送回执不得恢复旧绑定,即使跨标签页通知不可用,
持久 compare-and-swap 与 fencing 校验也必须保证这一点。
发送中或并发变化导致拒绝时,应等待或刷新后重新确认;存储不可用或失败时保持关闭编辑,
不报告成功。

重置不发送 GitHub 或协调器 mutation 请求,不删除云端文件,也不自动重新连接。
用户随后重新输入 Token 并点击**连接**,未绑定发现流程才会加载已有云端数据,
或创建空的私有 bootstrap Gist 并由协调器完成初始化;已丢弃的浏览器缓存不会成为上传来源。
历史队列的安全证据仍可在“同步恢复”中查看,不会自动重绑或发送。

## 租约、重试和上游故障

dispatcher 持久租约含随机 owner、单调 fencing token、到期和 heartbeat;
Expand Down
Loading
Loading