dsh-inbox-bridge 2.20.0 → 2.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,19 @@
1
+ ## 2.21.0
2
+
3
+ - **定位换了:现在是会话通知器,不是 GitHub 通知器。** 它不再回答「我账号上有什么消息」,而是回答「这个会话在 GitHub 上做的事有没有回音」——查的是这个会话自己的条目、以及它接管的仓库。结果:插件与 GitHub 账号解耦,两个共用同一账号的实例不再互相干扰。
4
+ - **接管取代订阅。** 打开工作区的第一个会话自动接管它所在的仓库,之后的会话默认不接管;面板里可以接管或释放。措辞从「订阅/取消订阅」统一为「接管/释放」,因为接管听起来是「我把这个仓库的账算在自己头上」,而不是「我在追踪一个仓库的事件」。
5
+ - **两级归属。** 仓库级事实(默认分支 CI、`recovered`、安全告警)只给接管者;条目级事实(某个 PR / issue 上的检查、评审、指派、@提及、评审意见)给在这个仓库里干活的会话——没人干活时给接管者,连接管者都没有时给最近说话的那个。一条事实只叫一个会话。
6
+ - **自己的工作跟人走。** 用搜索接口在账号能读到的范围内找我自己的条目(我开的 PR、派给我的 issue、提到我的评论),`owner/name#pr:42:mine` 这类 key 只送到我这儿,不触发仓库级动作。
7
+ - **清理固定下来,不再是一个档位。** 面板上的「消息清理」三档删掉:读过的线程一律标已读;仓库级线程(`/actions/runs/`、`/security/`、`/releases/`、`/commit/`)由接管者归档进 Done;条目级的回复留在收件箱,谁收到谁清。`sweep` 默认开启,`clear` 仍可关。
8
+ - **轮询的仓库 = 所有活着的会话接管的并集**(加实例级 `repo`/`repos`)。没人接管就不轮询,日志与面板都照实说,不再摆着没人要看的仓库。
9
+ - **顺手修的三个缺陷。** ①待投事实落盘时丢了 `repo`,回读后两道归属门空转,把它交给了恰好空闲的会话;现在落盘与回读都保留仓库,插件侧再用 key 前缀兜底。②被留下的事实用每一轮被当成「新发现」,于是一个 pending 就让归档每分钟开一次浏览器;现在只在新事实出现时才归档,失败后 30 分钟不重试。③没有 message 的失败(浏览器侧异常)被记成 `Uncaught`,现在打印真正的错误行。
10
+ - 文档按新定位重写(README / README.en / how-it-works / configuration / DETAIL),README 增加一张架构图。
11
+ - **没送到的事实不会过期。** 以前「留下待投」的事实若 6 小时内没人接手就会被当成过期丢弃;issue、评论、评审意见这类只报一次的事实因此会凭空消失。现在它们一直留在队列里,直到真的送到某个会话(投递之后的 6 小时重提窗口照旧)。
12
+ - 回归测试:`a fact that lost its repository is still routed by its key`、`a held fact does not sweep the inbox`、`a repository fact belongs to its owner, an item fact to whoever works there`、`my own items collapse into one fact each, wherever they live`、`nothing owned means nothing is polled`。
13
+
14
+ ## 2.20.1
15
+
16
+ - 修复「谁来接」在多会话工作区里不可用:以前同一仓库有多个会话又没指定负责者时谁都不唤醒,而两个会话的标题与目录完全一样,面板上并列两个同名项、也没法知道谁在接。现在每个会话都带会话 id 末四位,面板标出实际会接的那一个;默认负责者改成「最近跟你说话的那个会话」,显式指定的仍然优先且不会被绕过。
1
17
  ## 2.20.0
2
18
 
3
19
  - **谁来接这一轮。** 同一仓库有多个会话在看时,谁都不唤醒,直到你在面板上指定负责的那个;只剩一个会话时它自动负责。判定放在唤醒的五道门里,测试覆盖「两个会话谁都没被叫」与「指定之后只叫指定的那个」。
package/README.en.md CHANGED
@@ -7,7 +7,9 @@
7
7
 
8
8
  English | [中文](README.md)
9
9
 
10
- `dsh-inbox-bridge` is a DSH plugin. For each session it looks at the GitHub repositories that session subscribes to, collects the events that concern you (failed checks, review requests, issues assigned to you, comments mentioning you), and hands them over at the next turn boundary. When the session is idle and the fact matters, it opens a turn itself so the agent fixes the check, reviews the pull request, or takes the issue. It reads only and never acts on your behalf.
10
+ `dsh-inbox-bridge` is a DSH plugin that gives each session its own GitHub notifier. It watches **what this session did on GitHub and whether that came back**: your pull request failed its checks, received a review, the issue assigned to you moved, a comment mentioned you. What it finds becomes one notice at the session that should act on it — and when the session is idle and the fact matters, it opens a turn itself.
11
+
12
+ It does not track "what is in the GitHub account". It tracks "did what my agent did get an answer", so it is decoupled from the account: several sessions on one account each receive their own.
11
13
 
12
14
  <p align="center">
13
15
  <img src="https://c3115644151.github.io/dsh-inbox-bridge/assets/panel.png" width="300" alt="The chip in the status row and the panel it opens">
@@ -15,20 +17,23 @@ English | [中文](README.md)
15
17
 
16
18
  ## Why it exists
17
19
 
18
- When an agent writes the code, the repository does not move in step with the conversation. A CI run takes minutes to half an hour; meanwhile the agent is editing something else and does not see the failure happen. A pull request waits for review, an issue waits for an answer, and nobody picks them up. By the time anyone looks, the cheapest moment to fix it has passed.
20
+ When an agent writes the code, the repository does not move in step with the conversation. A CI run takes minutes to half an hour; meanwhile the agent is editing something else and does not see the failure happen. A review arrives, an issue gets answered, and nobody picks it up. By the time anyone looks, the cheapest moment to fix it has passed.
19
21
 
20
- This plugin hands that loop to the agent: once per turn it reads the repository and puts the facts that need action into the context — a failing check gets fixed, a review request gets reviewed, an assigned issue gets taken. Product work and repository upkeep stop interrupting each other, and the agent keeps the repository in shape the way a maintainer does instead of waiting for you to check.
22
+ This plugin hands that loop to the agent: once per turn it reads the sources and puts the facts that need this session into the context. Product work and repository upkeep stop interrupting each other, and the agent keeps the repository in shape the way a maintainer does instead of waiting for you to check.
21
23
 
22
24
  That is also why it only reads: its job is to make the agent aware. The work happens in the agent's own turn — the one you are in, or the one it was given — not in the background behind your back.
23
25
 
24
26
  ## What it does
25
27
 
26
- - **Relevance comes from your identity.** It queries the repositories as your `gh` login (or a configured App identity) and keeps only events where you are the author, the reviewer, the assignee, or are mentioned. Failed checks on someone else's PR, and unrelated repositories, never enter the queue.
27
- - **It reads repositories, not the notification inbox.** GitHub's notification inbox pushes per account and cannot tell one session or repository from another; querying repository state directly keeps two repositories on the same account apart.
28
+ - **Relevance comes from your identity.** It queries as your `gh` login (or a configured App identity) and keeps only facts where you are the author, the reviewer, the assignee, or are mentioned. Someone else's red PR, and unrelated repositories, never enter the queue.
29
+ - **Your own work follows you.** Beyond the current repository it searches everything the account can read: pull requests you opened elsewhere, issues assigned to you, comments that mention you — the answer reaches the session that is working.
30
+ - **Take a repository over, and its own facts are yours.** The first session in a workspace takes over the repository it sits in; only then do repository-level facts (default-branch CI, security advisories) reach that session. Taking over and releasing are both manual, and one repository may have several owners.
31
+ - **Two tiers of ownership.** Repository-level facts go to the owners; item-level facts (one pull request, one issue) go to the sessions working in that repository. When both would match, one fact still wakes one session.
28
32
  - **Polling follows turns.** Once when a session starts, every minute while a turn runs, once when it ends; an idle session makes no request. Only with `delivery: wakeup` does it also read on that interval while idle — without that it could never wake you while you are away.
29
33
  - **It also watches security and merge state.** Open Dependabot and code-scanning alerts, and a pull request of yours that conflicts with the base branch or is behind it, matter as much as a red check.
30
34
  - **The run that happens at night counts too.** A scheduled workflow that fails says it was scheduled, instead of reading as the last push failing; a review comment on your own pull request is reported as itself, and a push that answers it closes it.
31
- - **It goes into the context, and opens a turn only when it has to.** By default a notice arrives at the next safe injection point and does not interrupt the tool loop; with `delivery: wakeup` it opens a turn only for a listed `wakeOn` role, in the one session responsible for that repository (or the one you named), idle for 15 minutes, at most 3 times in a row per session, and at most 2 times an hour — anything else keeps queueing. A notice is marked `delivered`, and unhandled events come back once after six hours.
35
+ - **It tidies what it read, without a switch.** Repository-level facts (CI, advisories) are archived by the owner; item-level facts (answers on a pull request or issue) are only marked read — whoever received them clears them, and nobody touches another session's ledger.
36
+ - **It goes into the context, and opens a turn only when it has to.** By default a notice arrives at the next safe injection point and does not interrupt the tool loop; with `delivery: wakeup` it opens a turn only for a listed `wakeOn` role, after the session has been idle for 15 minutes, at most 3 times in a row per session, and at most 2 times an hour — anything else keeps queueing. A notice is marked `delivered`, and unhandled events come back once after six hours.
32
37
 
33
38
  ## What you will see
34
39
 
@@ -42,15 +47,23 @@ At the top of a turn:
42
47
 
43
48
  `[Dependabot]` is an open dependency advisory, `[Code scanning]` an open code-scanning alert, `[Scheduled]` a scheduled run that failed, and `[Review]` a review comment on your own pull request (with file and line). The rest of the bracket states the relation to that identity: `reviewer` means it waits for your review, `author` means you opened it, `assignee` means it is assigned to you, `mention` means a comment mentions you. Run the `ack` command when you are done; an unacknowledged event is repeated after six hours rather than piling up.
44
49
 
50
+ ## How it works
51
+
52
+ <p align="center">
53
+ <img src="docs/assets/architecture.png" width="640" alt="How a session, the plugin, the collector and GitHub relate">
54
+ </p>
55
+
56
+ Three boundaries: **GitHub is read-only** (queried as your identity, never changed); **the plugin only knows and decides when to speak**; **the work happens in the session's own turn**. Polling follows turns, facts are routed by tier, and only the session that owns one is woken.
57
+
45
58
  ## The panel
46
59
 
47
60
  The status row under the composer carries a chip: when something is waiting, a blue dot appears on the icon and the count follows. Hovering it opens a panel with:
48
61
 
49
62
  - the events: role, repository, title (link), time;
50
63
  - the identity and the last poll;
51
- - four controls: delivery (queue only / may wake), who takes it (when several sessions watch the same repository, say which one may be woken; a lone watcher owns it by itself), the rhythm (how idle is idle: 1 / 5 / 15 minutes; wakes per hour: 1 / 2 / 4), message clearing (off / mark read / archive to Done — one choice), and which repositories this session subscribes to (paste a repository link or type `owner/name`; one list per session).
64
+ - two controls: delivery (queue only / may wake) and the rhythm (how idle is idle: 1 / 5 / 15 minutes; wakes per hour: 1 / 2 / 4), plus the repositories this session took over (paste a repository link or type `owner/name`; `×` releases).
52
65
 
53
- Each control explains itself on hover. Changes apply immediately and are stored in `<cwd>/.work/inbox-bridge/prefs.json`; they do not rewrite the DSH plugin configuration, and a reset returns to the configured values. The panel is per session: switching sessions shows that session's repositories, and says so plainly when they are not subscribed.
66
+ Each control explains itself on hover. Changes apply immediately and are stored in `<cwd>/.work/inbox-bridge/prefs.json`; they do not rewrite the DSH plugin configuration, and a reset returns to the configured values. The panel is per session: switching sessions shows what that session took over and what would reach it.
54
67
 
55
68
  ## Install
56
69
 
@@ -62,7 +75,7 @@ You need DSH and a `gh` that is already logged in on this machine (`gh auth stat
62
75
  https://c3115644151.github.io/dsh-inbox-bridge/index.json
63
76
  ```
64
77
 
65
- GitHub inbox then shows up in the list and installs from there.
78
+ GitHub inbox shows up in the list; install it and it works.
66
79
 
67
80
  **From source:**
68
81
 
@@ -71,45 +84,44 @@ git clone https://github.com/c3115644151/dsh-inbox-bridge
71
84
  dsh plugin add ./dsh-inbox-bridge
72
85
  ```
73
86
 
74
- **From npm** (all the profile needs is a working pnpm):
87
+ **From npm** (the profile needs to run pnpm):
75
88
 
76
89
  ```powershell
77
90
  dsh plugin add dsh-inbox-bridge
78
91
  ```
79
92
 
80
- All three routes install the same package; versions live on [npm](https://www.npmjs.com/package/dsh-inbox-bridge).
93
+ All three install the same package; the version is on [npm](https://www.npmjs.com/package/dsh-inbox-bridge).
81
94
 
82
- Then give it a working directory (`cwd`) in the plugin configuration. The repository and the identity are read from that directory's `git remote` and from `gh`; nothing else needs filling in.
95
+ After installing, set the working directory `cwd` in the plugin configuration. The repository and the identity are read from that directory's `git remote` and from `gh`; there is nothing else to fill in.
83
96
 
84
- To see what it can actually see: `node scripts/inbox-bridge.mjs doctor` walks the identity, repository access, each repository's last poll and the queue; for one event that never reached you, `node scripts/inbox-bridge.mjs explain <key>` says where it stopped.
97
+ To see what it can actually see: `node scripts/inbox-bridge.mjs doctor` checks the identity, repository access, the last poll and the queue; when something did not reach you, `node scripts/inbox-bridge.mjs explain <key>` shows where it stopped.
85
98
 
86
- ## Configuration
99
+ ## Settings
87
100
 
88
- | Key | Default | Effect |
101
+ | Key | Default | Meaning |
89
102
  | --- | --- | --- |
90
- | `cwd` | DSH process directory | where state lives; where the repository is inferred from |
91
- | `repo` / `repos` | inferred from `origin` | one or several `owner/name` repositories to watch; non-empty `repos` wins |
92
- | `delivery` | `quiet` | `quiet` queues only; `wakeup` may start a turn while the session is idle |
93
- | `wakeOn` | empty | roles allowed to wake under `wakeup`; empty never wakes |
94
- | `clear` | `repo` | mark read after a poll: `repo` / `off`. Only the subscribed repositories, never the whole account |
95
- | `sweep` | off | archive the threads of the **repositories you subscribe to** into Done on turns that found something; the plugin opens a sign-in window when one is missing |
96
-
97
- The panel's "message clearing" choice sets both: **off** (neither), **read** (clear the blue dot), **archive** (mark read and move to Done).
103
+ | `cwd` | DSH process directory | Where state lives; the starting point for inferring repositories |
104
+ | `repo` / `repos` | `[]` | Instance-level ownership: these `owner/name` are watched no matter which session. Usually empty — session ownership joins in automatically |
105
+ | `delivery` | `quiet` | `quiet` only queues; `wakeup` may open a turn while the session is idle |
106
+ | `wakeOn` | empty | Role whitelist for waking under `wakeup`; empty means it never wakes |
107
+ | `clear` | `repo` | Mark the threads it read as read: `repo` / `all` / `off`. Never touches what it did not read |
108
+ | `sweep` | on | Archive repository-level facts (CI, advisories) into Done; a missing sign-in opens a window instead of asking you to type |
98
109
 
99
- Full configuration, CLI and state files: [configuration](docs/configuration.md).
110
+ Full settings, command line and state files: [settings and commands](docs/configuration.md).
100
111
 
101
112
  ## Boundaries
102
113
 
103
- - **Read-only.** It does not merge, comment, or change anything.
104
- - **No turn by default.** Only `delivery: wakeup` with a matching `wakeOn` role, one responsible session for that repository, enough idle time, and room in both budgets may start one; any gate that fails falls back to queueing.
105
- - **Archiving needs one browser sign-in, but you do not type a command for it.** GitHub has no archive API; `scripts/clear-inbox.mjs` drives a local Chromium-based browser (Edge, Chrome or Chromium). Switching "message clearing" to archive opens the sign-in window by itself, and it opens again if the session expires.
106
- - **Archiving touches only the repositories you subscribe to.** It opens GitHub's notification search per repository (`repo:owner/name`) and archives what is in that view; with no subscription it archives nothing. The whole inbox needs an explicit `--all`.
107
- - **State is local.** It lives under `.work/` in the working directory and is not synced across machines.
114
+ - **Read-only.** It does not merge, comment, or change a repository.
115
+ - **It does not open a conversation by default.** Only with `delivery: wakeup`, a matching `wakeOn` role, a long enough idle window, and budget left; any gate that fails falls back to queueing.
116
+ - **One fact wakes one session.** It does not arbitrate concurrent work: one pull request never wakes two sessions, but two agents already acting on it are beyond it.
117
+ - **Archiving needs one browser sign-in, and you are not asked to run anything.** GitHub has no archive API, so `scripts/clear-inbox.mjs` uses the local browser (Edge / Chrome / Chromium); when the sign-in is missing the plugin opens the window itself, and opens it again when the session expires.
118
+ - **Archiving only touches repository-level facts.** It walks the repositories you took over through GitHub's notification search view (`repo:owner/name`) and archives only runs, advisories and releases; answers on pull requests and issues are only marked read. The whole inbox needs an explicit `--all`.
119
+ - **State is local.** It lives under the workspace's `.work/` and is not synced across machines.
108
120
 
109
- ## Further reading
121
+ ## More
110
122
 
111
- - Polling, relevance, state machine and known limits: [how it works](docs/how-it-works.md)
112
- - All configuration, CLI, identity and roles: [configuration](docs/configuration.md)
123
+ - Ownership rules, polling, state machine and known limits: [how it works](docs/how-it-works.md)
124
+ - Every setting, the command line, identity and roles: [settings and commands](docs/configuration.md)
113
125
  - Version history: [CHANGELOG.md](CHANGELOG.md)
114
126
  - What comes next: [ROADMAP.md](ROADMAP.md)
115
- - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
127
+ - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
package/README.md CHANGED
@@ -7,7 +7,9 @@
7
7
 
8
8
  [English](README.en.md) | 中文
9
9
 
10
- `dsh-inbox-bridge` 是一个 DSH 插件。它按会话订阅的 GitHub 仓库,收集与你相关、需要你处理的事件(失败的 CI、待你评审的 PR、指派给你的 issue、@你的评论),汇总成一条消息,在回合边界送进上下文;会话空闲又遇到要紧的事,它也能主动开一轮,让 agent 自己去修、去审、去接。它只读 GitHub,不代替你操作。
10
+ `dsh-inbox-bridge` 是一个 DSH 插件,给每个会话配一个自己的 GitHub 通知器:它盯着**你这个会话在 GitHub 上的动作有没有得到回应**——自己开的 PR 挂了 CI、收到了评审意见,指派的 issue 有了动静,评论里有人 @ 你——把结果汇成一条消息送到该会话面前。会话空闲又遇到要紧的事,它还能主动开一轮,让 agent 自己去修、去审、去接。
11
+
12
+ 它不管「GitHub 账号上有什么消息」,只管「我这个 agent 做的事有没有回音」。所以它和账号解耦:同一个账号下的多个会话各自收各自的事。
11
13
 
12
14
  <p align="center">
13
15
  <img src="https://c3115644151.github.io/dsh-inbox-bridge/assets/panel.png" width="300" alt="状态行里的胶囊与悬停展开的面板">
@@ -15,42 +17,53 @@
15
17
 
16
18
  ## 为什么需要它
17
19
 
18
- 用 agent 写代码,仓库里的工作并不跟着对话走。一次 CI 要跑几分钟到几十分钟,这期间 agent 已经在改别的东西,失败发生时它看不见;PR 等人评审、issue 等人回应,同样没人接手。等想起来去翻,往往已经过了最该修的时候。
20
+ 用 agent 写代码,仓库里的工作并不跟着对话走。一次 CI 要跑几分钟到几十分钟,这期间 agent 已经在改别的东西,失败发生时它看不见;评审意见来了、issue 有人接了,同样没人处理。等想起来去翻,往往已经过了最该动手的时候。
19
21
 
20
- 它的意图是把这件事交给 agent:每轮取一次数,把「需要你动手」的事实带进上下文——CI 挂了就修,有人请你评审就审,指派给你的 issue 就接。开发本身和仓库维护不再互相打断,agent 像维护者一样把仓库维持在健康状态,而不是等你回来看。
22
+ 它的意图是把这件事交给 agent 自己:每轮取一次数,把「你做的事现在需要你」的事实带进上下文。开发本身和仓库维护不再互相打断,agent 像维护者一样把仓库维持在健康状态,而不是等你回来看。
21
23
 
22
24
  这也是它只读的原因:它负责让 agent 知道该做什么;动手的是 agent 自己那一轮——可能是你正在开的,也可能是它替你开的——而不是在后台背着你改仓库。
23
25
 
24
26
  ## 它做什么
25
27
 
26
- - **按身份判断相关性。** 用 `gh` 的登录身份(或配置的 App 身份)查询仓库,只保留以你为作者、评审人、指派对象或提及对象的事件;其他 PR 的检查失败、无关仓库的变动不会进入队列。
27
- - **只看仓库,不看通知箱。** GitHub 的通知箱(`/notifications`)按账号推送,无法区分是哪个会话、哪个仓库;这里直接查仓库状态,因此同一个账号下的两个仓库互不干扰。
28
+ - **按身份判断相关性。** 用 `gh` 的登录身份(或配置的 App 身份)查询,只保留以你为作者、评审人、指派对象或提及对象的事实;别人的 PR 失败、无关仓库的变动不会进入队列。
29
+ - **自己的事,走到哪跟到哪。** 除了当前仓库,它还会搜索整个账号能读到的范围:你在别的仓库开的 PR、被指派的 issue、被 @ 的评论,回音都送到正在干活的那个会话。
30
+ - **接管一个仓库,才管整个仓库的事。** 打开工作区的第一个会话自动接管该仓库;接管之后,仓库级的事实(默认分支 CI、安全告警)才归这个会话。接管可以手动加、也可以释放,一个仓库可以有多个接管者。
31
+ - **两级归属。** 仓库级事实只给接管者;条目级事实(某个 PR、某个 issue)给在这个仓库里干活的会话。两件事同时命中时,同一条事实只叫一个会话。
28
32
  - **轮询跟随回合。** 会话开始时一次、进行中每 1 分钟一次、结束时一次,空闲会话不发请求;开启 `delivery: wakeup` 后空闲时也按同一间隔读一次,否则它没机会在你不在时叫醒你。
29
- - **也看安全与合并状态。** 开着的 Dependabot 告警、code scanning 告警,以及我这些 PR 与基分支的冲突或落后,和 CI 失败一样是要紧的事。
30
- - **夜里跑的那次也算。** 定时工作流(`schedule`)失败时标明是定时任务,不与「最后一次推送失败」混在一起;我自己的 PR 收到评审意见时把那条意见本身报出来,推了新提交、意见被代码回答之后自然收口。
31
- - **送进上下文,必要时才开一轮。** 默认只在这一轮的下一次安全注入点进入会话,不打断工具循环;开启 `delivery: wakeup` 后,只有命中 `wakeOn` 的角色、这个仓库只有它一个会话在看(或被你指定负责)、会话空闲满 15 分钟、每会话连续不超过 3 次、每小时不超过 2 次时才主动开一轮,其余情况仍然排队。送达后标为 `delivered`,未处理的 6 小时后重新提醒一次。
33
+ - **也看安全与合并状态。** 开着的 Dependabot 告警、code scanning 告警,以及我这些 PR 与基分支的冲突或落后,和 CI 失败一样要紧。
34
+ - **夜里跑的那次也算。** 定时工作流(`schedule`)失败时标明是定时任务,不与「最后一次推送失败」混在一起;自己的 PR 收到评审意见时把那条意见本身报出来,推了新提交、意见被代码回答之后自然收口。
35
+ - **顺手清掉读过的。** 固定行为,没有开关:仓库级的事实(CI、安全告警)由接管者在 GitHub 上归档;条目级的事实(PR、issue 的回复)只标已读——谁收到谁清,不动别人的账。
36
+ - **送进上下文,必要时才开一轮。** 默认只在这一轮的下一次安全注入点进入会话,不打断工具循环;开启 `delivery: wakeup` 后,只有命中 `wakeOn` 的角色、会话空闲满 15 分钟、每会话连续不超过 3 次、每小时不超过 2 次时才主动开一轮,其余情况仍然排队。送达后标为 `delivered`,未处理的 6 小时后重新提醒一次。
32
37
 
33
38
  ## 你会看到什么
34
39
 
35
40
  出现在回合开头:
36
41
 
37
42
  > 外部收件箱(后台轮询,不是用户提问)· 读取身份:c3115644151:
38
- > - [PR/reviewer] #23 review requested from you:fix: retry on flaky upload https://github.com/…
43
+ > - [PR/reviewer] #23 review requested from you: fix: retry on flaky upload https://github.com/…
39
44
  > - [CI] run 43934997486 failed: chore: release 2.3.1 https://github.com/…
40
45
  >
41
46
  > 只在它影响当前工作时处理;处理完运行 `node "...\dsh-inbox-bridge\scripts\inbox-bridge.mjs" ack --done -- <key>` 标记完成。
42
47
 
43
48
  `[Dependabot]` 表示一条开着的依赖告警,`[Code scanning]` 表示一条开着的代码告警,`[Scheduled]` 表示定时任务跑了并失败,`[Review]` 表示你自己的 PR 收到了评审意见(后面跟着文件:行号)。方括号里其余部分是该事件与该身份的关系:`reviewer` 表示你是评审人,`author` 表示你是作者,`assignee` 表示指派给你,`mention` 表示评论中提到你。处理完执行提示里的 `ack` 命令;未 ack 的事件在 6 小时后重新提示,不会重复累积。
44
49
 
50
+ ## 它怎么运作
51
+
52
+ <p align="center">
53
+ <img src="docs/assets/architecture.png" width="640" alt="会话、插件、采集器与 GitHub 之间的流向">
54
+ </p>
55
+
56
+ 三个边界:**GitHub 只读**(按身份查,不改动);**插件只负责知道与何时开口**;**动手发生在会话的那一轮里**。轮询跟着回合走,事件按仓库级/条目级分给会话,只有该负责的那个会被叫起来。交互版见 [architecture.html](docs/assets/architecture.html)。
57
+
45
58
  ## 界面
46
59
 
47
60
  输入框下方的状态行里有一个胶囊:有未处理事件时,图标右上角出现一个蓝点,旁边是数量。鼠标悬停展开面板:
48
61
 
49
62
  - 事件列表:角色、仓库、标题(可点开)、时间。
50
63
  - 身份、上次轮询时间。
51
- - 四组开关:提醒方式(仅注入 / 主动唤醒)、谁来接(同一仓库有多个会话在看时,指定由哪个会话接受唤醒;只有一个时它自动负责)、节奏(空闲多久算空闲:1 / 5 / 15 分钟;每小时最多几次:1 / 2 / 4)、消息清理(关闭 / 已读 / 归档,一档三态)、订阅仓库(粘贴仓库链接或写 `owner/name` 添加,每个会话各有一份)。
64
+ - 两组开关:提醒方式(仅注入 / 主动唤醒)、节奏(空闲多久算空闲:1 / 5 / 15 分钟;每小时最多几次:1 / 2 / 4),外加接管的仓库清单(粘贴仓库链接或写 `owner/name` 接管;`×` 释放)。
52
65
 
53
- 每个按钮的悬停提示写明了它的作用。改动立即生效,记录在 `<cwd>/.work/inbox-bridge/prefs.json`,不修改 DSH 的插件配置;重置后回到配置里的值。面板按会话取数:切换会话显示该会话订阅的仓库;仓库未订阅时直接说明。
66
+ 每个按钮的悬停提示写明了它的作用。改动立即生效,记录在 `<cwd>/.work/inbox-bridge/prefs.json`,不修改 DSH 的插件配置;重置后回到配置里的值。面板按会话取数:切换会话显示该会话接管了什么、会收到什么。
54
67
 
55
68
  ## 安装
56
69
 
@@ -81,35 +94,34 @@ dsh plugin add dsh-inbox-bridge
81
94
 
82
95
  安装后在插件配置里指定工作目录 `cwd`。仓库名与身份都从该目录的 `git remote` 与 `gh` 读取,不需要另外填写。
83
96
 
84
- 想确认它到底能看见什么:`node scripts/inbox-bridge.mjs doctor` 逐项检查身份、仓库可读性、每个仓库的上次轮询与队列;某件事没到眼前,用 `node scripts/inbox-bridge.mjs explain <key>` 看它卡在哪一步。
97
+ 想确认它到底能看见什么:`node scripts/inbox-bridge.mjs doctor` 逐项检查身份、仓库可读性、上次轮询与队列;某件事没到眼前,用 `node scripts/inbox-bridge.mjs explain <key>` 看它卡在哪一步。
85
98
 
86
99
  ## 配置
87
100
 
88
101
  | 键 | 默认 | 作用 |
89
102
  | --- | --- | --- |
90
103
  | `cwd` | DSH 进程工作目录 | 状态文件位置;推断仓库的起点 |
91
- | `repo` / `repos` | 从 `origin` 推断 | 订阅一个或一组 `owner/name`;非空 `repos` 优先 |
104
+ | `repo` / `repos` | `[]` | 实例级接管:无论哪个会话都盯这些 `owner/name`。平时不用写——会话接管会自动并进来 |
92
105
  | `delivery` | `quiet` | `quiet` 只入队;`wakeup` 可在会话空闲时主动开启一轮 |
93
106
  | `wakeOn` | 空 | `wakeup` 下允许唤醒的角色白名单;为空则永不唤醒 |
94
- | `clear` | `repo` | 将订阅仓库里读过的通知标为已读:`repo` / `off`。只清订阅的仓库,不动整个账号 |
95
- | `sweep` | 关 | 有发现的回合把**订阅的仓库**的通知归档到 Done;缺登录时插件自己弹窗口让你登录一次 |
96
-
97
- 面板里的「消息清理」一档同时管这两件事:**关闭**(都不做)、**已读**(清蓝点)、**归档**(标已读并存进 Done)。
107
+ | `clear` | `repo` | 把读过的通知标为已读:`repo` / `all` / `off`。只清自己读过的,不动别人的 |
108
+ | `sweep` | 开 | 仓库级事实(CI、安全告警)归档到 Done;缺登录时插件自己弹窗口让你登录一次 |
98
109
 
99
110
  完整配置、命令行与状态文件见 [配置与命令](docs/configuration.md)。
100
111
 
101
112
  ## 边界
102
113
 
103
114
  - **只读。** 不合并、不评论、不修改仓库。
104
- - **默认不主动开启对话。** 只有显式设置 `delivery: wakeup` 且命中 `wakeOn`、这个仓库只由一个会话负责、会话足够空闲、两个预算都还有余额时才会;任何一道门不过,就退回只排队。
105
- - **Done 归档依赖一次浏览器登录,但不用你敲命令。** GitHub 没有归档 API,`scripts/clear-inbox.mjs` 通过本机浏览器(Edge / Chrome / Chromium)完成。把「消息清理」切到归档,插件会自己弹出登录窗口;会话失效时会再弹一次。
106
- - **归档只碰你订阅的仓库。** 它按仓库逐个打开 GitHub 的通知搜索视图(`repo:owner/name`),只归档这些视图里的线程;没有订阅就什么都不归档。整个收件箱要显式 `--all` 才会动。
115
+ - **默认不主动开启对话。** 只有显式设置 `delivery: wakeup` 且命中 `wakeOn`、会话足够空闲、两个预算都还有余额时才会;任何一道门不过,就退回只排队。
116
+ - **一件事实只叫一个会话。** 它不仲裁并发行动:同一个 PR 不会同时唤醒两个会话,但已经动手的两个 agent 之间它管不了。
117
+ - **Done 归档依赖一次浏览器登录,但不用你敲命令。** GitHub 没有归档 API,`scripts/clear-inbox.mjs` 通过本机浏览器(Edge / Chrome / Chromium)完成;缺登录时插件自己弹窗口,会话失效时会再弹一次。
118
+ - **归档只碰仓库级事实。** 它按接管的仓库逐个打开 GitHub 的通知搜索视图(`repo:owner/name`),只归档 CI 运行、安全告警、发布这类线程;PR 与 issue 的回复只标已读。整个收件箱要显式 `--all` 才会动。
107
119
  - **状态在本机。** 存放在工作目录的 `.work/` 下,不跨机器同步。
108
120
 
109
121
  ## 更多
110
122
 
111
- - 轮询时机、相关性判断、状态机与已知限制:[工作原理](docs/how-it-works.md)
123
+ - 归属规则、轮询时机、状态机与已知限制:[工作原理](docs/how-it-works.md)
112
124
  - 全部配置项、命令行、身份与角色:[配置与命令](docs/configuration.md)
113
125
  - 版本变更:[CHANGELOG.md](CHANGELOG.md)
114
126
  - 后续计划:[ROADMAP.md](ROADMAP.md)
115
- - 参与开发:[CONTRIBUTING.md](CONTRIBUTING.md)
127
+ - 参与开发:[CONTRIBUTING.md](CONTRIBUTING.md)
package/client.js CHANGED
@@ -103,9 +103,9 @@ window.__ModuleLoader__.load({
103
103
  clear: "已标为已读",
104
104
  sweep: "已归档到 Done",
105
105
  quiet: "不会主动开启对话",
106
- unwatched: (repo) => `此会话的 ${repo} 不在订阅列表`,
106
+ unwatched: (repo) => `还没有会话接管 ${repo},插件不轮询它`,
107
107
  scopeRead: "身份",
108
- scopeWatch: "订阅仓库",
108
+ scopeWatch: "接管的仓库",
109
109
  scopeSync: "上次轮询",
110
110
  none: "未配置仓库",
111
111
  open: "打开收件箱",
@@ -120,21 +120,10 @@ window.__ModuleLoader__.load({
120
120
  quietTip: "只排队,等你下次发消息时随该轮进入上下文。",
121
121
  wakeup: "主动唤醒",
122
122
  wakeupTip: "会话空闲时,插件可以替你开启一轮来处理这些事件。",
123
- clean: "消息清理",
124
- cleanTip: "处理完通知后,GitHub 侧留下什么。只作用于订阅的仓库。",
125
- cleanOff: "关闭",
126
- cleanOffTip: "保留未读圆点,什么都不做。",
127
- read: "已读",
128
- readTip: "把通知标为已读,清掉圆点;不进 Done。",
129
- done: "归档",
130
- doneTip: "标为已读并移入 Done。归档需要一次浏览器登录。",
131
- signInNeeded: "归档还没登录 GitHub,事件不会进 Done。",
123
+ signInNeeded: "归档还没登录 GitHub,仓库的事件不会进 Done。",
132
124
  signInWaiting: "已打开登录窗口,登录后自动生效。",
133
125
  signInOpen: "打开登录窗口",
134
126
  signInTip: "在插件自己的浏览器配置里登录一次;之后归档会自动运行,失效时会再打开这个窗口。",
135
- owner: "谁来接",
136
- ownerTip: "这个仓库的唤醒落到哪个会话。多个会话在看同一仓库时,没指定就不会叫任何人。",
137
- ownerReleaseTip: "再点一次取消指定",
138
127
  idle: "空闲多久",
139
128
  idleTip: "会话安静满这么长时间,才允许唤醒;否则只把事件留下等下一轮。",
140
129
  minute1: "1 分钟",
@@ -142,14 +131,14 @@ window.__ModuleLoader__.load({
142
131
  minute15: "15 分钟",
143
132
  budget: "每小时",
144
133
  budgetTip: "这个实例每小时最多唤醒几次,用完后只排队。",
145
- subscribe: "订阅仓库",
146
- subscribeTip: "此会话关注的 GitHub 仓库;事件只按这里的仓库投递。",
134
+ subscribe: "接管的仓库",
135
+ subscribeTip: "本会话接管这些仓库:整仓信号投到这里,仓库的事件也由这里归档。条目级的回音不属于这一行。",
147
136
  typeRepo: "owner/repo 或链接",
148
137
  typeRepoTip: "可以粘贴 https://github.com/owner/repo,也可以直接写 owner/repo。",
149
138
  add: "添加",
150
- addTip: "订阅输入框里的仓库。",
151
- addHere: "订阅当前仓库",
152
- remove: "取消订阅",
139
+ addTip: "接管输入框里的仓库。",
140
+ addHere: "接管当前仓库",
141
+ remove: "释放",
153
142
  reset: "恢复配置",
154
143
  },
155
144
  },
@@ -169,7 +158,7 @@ window.__ModuleLoader__.load({
169
158
  clear: "marked read",
170
159
  sweep: "archived to done",
171
160
  quiet: "never starts a turn",
172
- unwatched: (repo) => `${repo} is not watched by this instance`,
161
+ unwatched: (repo) => `${repo} is not owned by any session, so it is not polled`,
173
162
  scopeRead: "identity",
174
163
  scopeWatch: "repositories",
175
164
  scopeSync: "last poll",
@@ -186,21 +175,10 @@ window.__ModuleLoader__.load({
186
175
  quietTip: "Wait for your next message; the notice rides along with that turn.",
187
176
  wakeup: "may wake it",
188
177
  wakeupTip: "When the session is idle, the plugin may start a turn to handle it.",
189
- clean: "cleaning",
190
- cleanTip: "What is left in GitHub after a notice is handled. Subscribed repositories only.",
191
- cleanOff: "off",
192
- cleanOffTip: "Keep the unread dot; do nothing on GitHub.",
193
- read: "read",
194
- readTip: "Clear the unread dot without moving the thread to Done.",
195
- done: "done",
196
- doneTip: "Mark read and move the thread to Done. Archiving needs a one-time browser sign-in.",
197
- signInNeeded: "Archiving is not signed in yet, so nothing reaches Done.",
178
+ signInNeeded: "Archiving is not signed in yet, so repository events do not reach Done.",
198
179
  signInWaiting: "The sign-in window is open; archiving resumes when you finish.",
199
180
  signInOpen: "open sign-in",
200
181
  signInTip: "Sign in once in this plugin's own browser profile; afterwards archiving runs on its own and reopens this window if the session expires.",
201
- owner: "who takes it",
202
- ownerTip: "Which session a wakeup for this repository reaches. With several sessions watching one repository, nobody is woken until you name one.",
203
- ownerReleaseTip: "click again to clear",
204
182
  idle: "quiet for",
205
183
  idleTip: "A session must be this quiet before a wakeup may open a turn; otherwise the event waits for a later poll.",
206
184
  minute1: "1 min",
@@ -208,14 +186,14 @@ window.__ModuleLoader__.load({
208
186
  minute15: "15 min",
209
187
  budget: "per hour",
210
188
  budgetTip: "How many wakeups this instance may spend each hour; past that, events only queue.",
211
- subscribe: "repositories",
212
- subscribeTip: "The repositories this session follows; events are delivered only for them.",
189
+ subscribe: "repositories owned",
190
+ subscribeTip: "This session maintains these repositories: repository-wide signals arrive here, and their threads are archived from here. Item-level replies are separate.",
213
191
  typeRepo: "owner/repo or link",
214
192
  typeRepoTip: "Paste https://github.com/owner/repo, or type owner/repo.",
215
193
  add: "add",
216
- addTip: "Subscribe to the repository in the field.",
217
- addHere: "watch this repo",
218
- remove: "unwatch",
194
+ addTip: "Take over the repository in the field.",
195
+ addHere: "own this repo",
196
+ remove: "release",
219
197
  reset: "reset",
220
198
  },
221
199
  },
@@ -462,14 +440,6 @@ window.__ModuleLoader__.load({
462
440
  textOverflow: "ellipsis",
463
441
  whiteSpace: "nowrap",
464
442
  },
465
- ownerList: {
466
- display: "flex",
467
- alignItems: "center",
468
- flexWrap: "wrap",
469
- gap: "4px",
470
- minWidth: 0,
471
- justifyContent: "flex-end",
472
- },
473
443
  metaValue: {
474
444
  color: "var(--dsw-alias-label-secondary)",
475
445
  textAlign: "right",
@@ -716,18 +686,15 @@ window.__ModuleLoader__.load({
716
686
  * One change at a time, through the host's own route. The token is the one
717
687
  * this process handed out with the status, so another page cannot do this.
718
688
  */
719
- async function change(status, set, value, target) {
689
+ async function change(status, set, value) {
720
690
  const token = status?.token;
721
691
  if (!token) return { ok: false, error: "no token" };
722
692
  const session = status?.sessionId
723
693
  ? `&session=${encodeURIComponent(status.sessionId)}`
724
694
  : "";
725
- // A claim names the session that should own a repository, which need not be
726
- // the session this page belongs to.
727
- const named = target ? `&target=${encodeURIComponent(target)}` : "";
728
695
  const url = `/inbox-bridge/prefs?token=${encodeURIComponent(token)}&set=${encodeURIComponent(
729
696
  set,
730
- )}&value=${encodeURIComponent(value)}${session}${named}`;
697
+ )}&value=${encodeURIComponent(value)}${session}`;
731
698
  try {
732
699
  const response = await fetch(url, { cache: "no-store" });
733
700
  return await response.json();
@@ -748,11 +715,11 @@ window.__ModuleLoader__.load({
748
715
  const [error, setError] = React.useState(null);
749
716
  const [draft, setDraft] = React.useState("");
750
717
  const pick = text.pick;
751
- const send = async (set, value, target) => {
718
+ const send = async (set, value) => {
752
719
  if (busy) return;
753
720
  setBusy(true);
754
721
  setError(null);
755
- const result = await change(status, set, value, target);
722
+ const result = await change(status, set, value);
756
723
  setBusy(false);
757
724
  if (!result.ok) {
758
725
  setError(result.error ?? "failed");
@@ -782,13 +749,12 @@ window.__ModuleLoader__.load({
782
749
  );
783
750
  const repos = status.session?.repos ?? status.repos ?? [];
784
751
  const sessionRepo = status.scope === "session" ? (status.session?.repo ?? null) : null;
785
- // Two mechanisms, one decision: what happens to the notice after this poll.
786
- const cleanLevel = status.sweepOn ? "done" : status.clear === "off" ? "off" : "read";
752
+
787
753
  const addDraft = () => {
788
754
  const value = draft.trim();
789
755
  if (!value) return;
790
756
  setDraft("");
791
- void send("subscribe", value);
757
+ void send("own", value);
792
758
  };
793
759
  return h(
794
760
  "div",
@@ -808,35 +774,6 @@ window.__ModuleLoader__.load({
808
774
  "mode",
809
775
  ),
810
776
  ),
811
- // A wakeup has to reach one session. When several sessions watch the same
812
- // repository only the person can say which one is responsible, so the
813
- // choice belongs next to the switch that makes wakeups possible at all.
814
- status.delivery === "wakeup" && sessionRepo && (status.wake?.viewers?.length ?? 0) > 1
815
- ? h(
816
- "div",
817
- { style: styles.controlRow },
818
- h("span", { style: styles.controlLabel, title: pick.ownerTip }, pick.owner),
819
- h(
820
- "div",
821
- { style: styles.ownerList },
822
- status.wake.viewers.map((viewer) =>
823
- h(
824
- "button",
825
- {
826
- key: viewer.id,
827
- type: "button",
828
- disabled: busy,
829
- "aria-pressed": Boolean(viewer.primary),
830
- title: viewer.primary ? `${viewer.label} · ${pick.ownerReleaseTip}` : viewer.label,
831
- onClick: () => void send("primary", viewer.primary ? "" : sessionRepo, viewer.id),
832
- style: { ...styles.seg, ...(viewer.primary ? styles.segOn : {}) },
833
- },
834
- viewer.label,
835
- ),
836
- ),
837
- ),
838
- )
839
- : null,
840
777
  // How patient the wakeup is: quiet at least this long, at most this many
841
778
  // times an hour. Both were file-only settings until a session could ask
842
779
  // for them from here.
@@ -876,26 +813,12 @@ window.__ModuleLoader__.load({
876
813
  ),
877
814
  )
878
815
  : null,
879
- h(
880
- "div",
881
- { style: styles.controlRow },
882
- h("span", { style: styles.controlLabel, title: pick.cleanTip }, pick.clean),
883
- seg(
884
- pick.clean,
885
- [
886
- ["off", pick.cleanOff, pick.cleanOffTip],
887
- ["read", pick.read, pick.readTip],
888
- ["done", pick.done, pick.doneTip],
889
- ],
890
- cleanLevel,
891
- "clean",
892
- "clean",
893
- ),
894
- ),
895
- // Archiving is a page action in GitHub, so it needs a browser session in
896
- // the plugin's own profile. Say that here, and open the window from here —
897
- // the operator should not have to run a command to make the mode work.
898
- cleanLevel === "done" && status.signIn?.signedIn !== true
816
+ // Cleaning has no switch any more: the tier decides. Item-tier notices are
817
+ // marked read; repository-tier notices are archived by the session that
818
+ // maintains that repository. Archiving is a page action in GitHub, so it
819
+ // needs a browser session in the plugin's own profile — say that here and
820
+ // open the window from here, because the name of the game is "no command".
821
+ status.sweepOn && status.signIn?.signedIn !== true
899
822
  ? h(
900
823
  "div",
901
824
  { style: styles.signInRow },
@@ -940,7 +863,7 @@ window.__ModuleLoader__.load({
940
863
  disabled: busy,
941
864
  "aria-label": `${pick.remove} ${entry}`,
942
865
  title: `${pick.remove} ${entry}`,
943
- onClick: () => void send("unsubscribe", entry),
866
+ onClick: () => void send("release", entry),
944
867
  style: styles.iconBtn,
945
868
  },
946
869
  "×",
@@ -953,7 +876,7 @@ window.__ModuleLoader__.load({
953
876
  {
954
877
  type: "button",
955
878
  disabled: busy,
956
- onClick: () => void send("subscribe", sessionRepo),
879
+ onClick: () => void send("own", sessionRepo),
957
880
  style: styles.addBtn,
958
881
  title: `${pick.addHere}:${sessionRepo}`,
959
882
  },