dsh-team-bots 0.2.289 → 0.2.347

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.
Files changed (119) hide show
  1. package/README.md +60 -122
  2. package/docs/README.zh.md +61 -123
  3. package/docs/assets/channel-redesign.png +0 -0
  4. package/docs/assets/global-config-dark.png +0 -0
  5. package/docs/assets/global-config-light.png +0 -0
  6. package/docs/assets/global-config-light.zh.png +0 -0
  7. package/docs/assets/global-config-redesign.png +0 -0
  8. package/docs/assets/secrets-redesign.png +0 -0
  9. package/docs/assets/tasks.png +0 -0
  10. package/docs/assets/tasks.zh.png +0 -0
  11. package/docs/assets/usage-redesign-global.png +0 -0
  12. package/docs/assets/usage.png +0 -0
  13. package/docs/assets/usage.zh.png +0 -0
  14. package/package.json +17 -5
  15. package/scripts/doctor.mjs +4 -4
  16. package/src/api.js +6 -3
  17. package/src/botmsg.js +1 -1
  18. package/src/config.js +18 -8
  19. package/src/db-migrations.js +76 -9
  20. package/src/db.js +28 -2
  21. package/src/http.js +22 -3
  22. package/src/paths.js +32 -1
  23. package/src/pricing.js +2 -2
  24. package/src/runtime.js +1 -1
  25. package/src/secrets.js +4 -4
  26. package/src/service.js +14 -5
  27. package/src/services/approvals.js +109 -24
  28. package/src/services/backoff.js +34 -0
  29. package/src/services/bot-quota.js +242 -0
  30. package/src/services/bots.js +35 -6
  31. package/src/services/chat.js +15 -9
  32. package/src/services/core.js +33 -5
  33. package/src/services/hygiene.js +8 -4
  34. package/src/services/locale.js +17 -0
  35. package/src/services/memory.js +112 -1
  36. package/src/services/message-images.js +3 -3
  37. package/src/services/notify.js +169 -0
  38. package/src/services/projects.js +119 -10
  39. package/src/services/proposals.js +2 -3
  40. package/src/services/questions.js +75 -32
  41. package/src/services/review-watchdog.js +261 -30
  42. package/src/services/run-finish.js +186 -17
  43. package/src/services/runs.js +42 -13
  44. package/src/services/runtime/lifecycle.js +3 -1
  45. package/src/services/runtime/model-restore.js +5 -5
  46. package/src/services/runtime/prompt.js +106 -45
  47. package/src/services/runtime/session.js +38 -14
  48. package/src/services/runtime/trajectory.js +1 -1
  49. package/src/services/scheduler.js +146 -19
  50. package/src/services/secrets.js +1 -1
  51. package/src/services/system.js +23 -6
  52. package/src/services/task-dispatch.js +315 -0
  53. package/src/services/task-notify.js +55 -11
  54. package/src/services/task-runs.js +179 -0
  55. package/src/services/task-stage.js +4 -0
  56. package/src/services/tasks.js +51 -399
  57. package/src/services/terminal.js +2 -2
  58. package/src/services/vision-proxy.js +3 -3
  59. package/src/services/wechat.js +228 -7
  60. package/src/services/workspace-groups.js +4 -3
  61. package/src/skill-parse.js +1 -1
  62. package/src/skills.js +1 -1
  63. package/src/tools.js +275 -6
  64. package/src/updater.js +52 -0
  65. package/src/usage-reconcile.js +1 -1
  66. package/src/usage.js +52 -11
  67. package/src/wechat/channel.js +14 -20
  68. package/src/wechat/commands.js +129 -81
  69. package/src/wechat/format.js +247 -0
  70. package/src/wechat/store.js +30 -2
  71. package/ui/app.js +57 -53
  72. package/ui/i18n/en/chat.js +140 -0
  73. package/ui/i18n/en/common.js +187 -0
  74. package/ui/i18n/en/nav.js +89 -0
  75. package/ui/i18n/en/settings.js +352 -0
  76. package/ui/i18n/en/tasks.js +229 -0
  77. package/ui/i18n/en/usage.js +141 -0
  78. package/ui/i18n/en/wechat.js +23 -0
  79. package/ui/i18n/en.js +17 -237
  80. package/ui/i18n/zh/chat.js +140 -0
  81. package/ui/i18n/zh/common.js +187 -0
  82. package/ui/i18n/zh/nav.js +89 -0
  83. package/ui/i18n/zh/settings.js +352 -0
  84. package/ui/i18n/zh/tasks.js +229 -0
  85. package/ui/i18n/zh/usage.js +141 -0
  86. package/ui/i18n/zh/wechat.js +23 -0
  87. package/ui/i18n/zh.js +17 -236
  88. package/ui/modules/api.js +4 -3
  89. package/ui/modules/bot-quota.js +27 -0
  90. package/ui/modules/cards.js +96 -58
  91. package/ui/modules/chat.js +28 -30
  92. package/ui/modules/composer.js +41 -37
  93. package/ui/modules/dom-morph.js +292 -0
  94. package/ui/modules/events-board.js +22 -22
  95. package/ui/modules/events-click.js +100 -68
  96. package/ui/modules/events-misc.js +34 -34
  97. package/ui/modules/events-submit.js +28 -28
  98. package/ui/modules/global-pages.js +125 -116
  99. package/ui/modules/i18n.js +0 -5
  100. package/ui/modules/icons.js +0 -1
  101. package/ui/modules/markdown.js +1 -1
  102. package/ui/modules/modal-forms.js +196 -203
  103. package/ui/modules/modal-layer.js +6 -9
  104. package/ui/modules/page-shell.js +62 -0
  105. package/ui/modules/settings.js +211 -198
  106. package/ui/modules/solo-archive.js +0 -4
  107. package/ui/modules/state.js +57 -50
  108. package/ui/modules/tasks.js +167 -171
  109. package/ui/modules/typing-linger.js +1 -4
  110. package/ui/modules/usage.js +65 -78
  111. package/ui/modules/util.js +92 -25
  112. package/ui/styles/avatars.css +14 -0
  113. package/ui/styles/cards.css +49 -0
  114. package/ui/styles/chat-cards.css +17 -21
  115. package/ui/styles/global-config.css +56 -2
  116. package/ui/styles/modal.css +13 -0
  117. package/ui/styles/usage.css +3 -61
  118. package/CONTRIBUTING.md +0 -20
  119. package/docs/assets/usage-dark.png +0 -0
package/README.md CHANGED
@@ -2,173 +2,111 @@
2
2
 
3
3
  [中文](docs/README.zh.md)
4
4
 
5
- DSH Team Bots is the npm package `dsh-team-bots`, a DSH (DeepSeek Harness) plugin that packs a collaborating crew of bots into one workspace: project group chats, a task board, write-scope parallel scheduling, memory and skills, usage and cost, plus a personal WeChat channel.
5
+ `dsh-team-bots` is a DSH plugin that turns one workspace into a team: project group chats, a task board, write-scope parallel scheduling, shared memory and skills, approval cards, usage and cost, and a personal WeChat channel. Every run keeps its trajectory, duration, token count and cost.
6
6
 
7
- ![DSH Team Bots workspace](docs/assets/tasks.png)
7
+ ## Requirements
8
8
 
9
- This file is the English edition of the project documentation; the Chinese edition is [docs/README.zh.md](docs/README.zh.md).
9
+ - Node.js ≥ 22.19
10
+ - the DSH CLI (`dsh`)
10
11
 
11
- ---
12
+ The plugin runs inside the DSH Web process. It has no standalone service and no port of its own.
12
13
 
13
- ## 1. Project Overview
14
-
15
- `dsh-team-bots` runs inside the DSH Web process — no separate service — and lets several bots divide work across the same project spaces, exposing the collaboration as an operable web workspace.
16
-
17
- 1. **Collaboration happens in projects, not in a chat window.** Each project has its own group chat, members, tasks and working directory; the project director bot splits, assigns and accepts work there.
18
- 2. **Parallelism is declared, not hoped for.** A task declares the paths it will write; the scheduler runs two write runs in the same project in parallel only when both declare and their path prefixes do not overlap. Anything undeclared is treated as serial.
19
- 3. **Everything is traceable.** Every run keeps a trajectory, duration, token count and cost; bot configuration keeps an immutable history that can be rolled back; secrets stay encrypted at rest and are materialised as one-time plaintext files that are burned after use.
20
-
21
- The repository shape: `index.js` is the plugin entry point, `src/` is the server side and scheduler, `ui/` is the workspace frontend, `tests/` holds the guard tests, and `docs/` holds design specs, review records and screenshots.
22
-
23
- ---
24
-
25
- ## 2. Quick Start
26
-
27
- ### 2.1 Requirements and install
28
-
29
- Node.js ≥ 22.19 (see `engines` in `package.json`) and the DSH CLI installed (`dsh --version`); the plugin runs inside the DSH Web process, with no standalone process or port.
14
+ ## Install
30
15
 
31
16
  ```sh
32
- cd <repo>
33
- npm pack # produces dsh-team-bots-<version>.tgz
34
- dsh plugin --profile <name> add ./dsh-team-bots-<version>.tgz
35
- dsh --profile <name> # read the tokenised dsh web entry from the startup log
17
+ dsh plugin --profile <name> add dsh-team-bots
36
18
  ```
37
19
 
38
- ### 2.2 Reinstall and local preview
20
+ From a checkout (packs the working tree and installs it into the profile):
39
21
 
40
22
  ```sh
41
- npm run profile:install -- --profile <name> # installs into team-bots when --profile is omitted
42
- npm run dev # local preview at http://127.0.0.1:4317, fake runtime
23
+ npm run profile:install -- --profile <name>
43
24
  ```
44
25
 
45
- `profile:install` packs the repository and reinstalls the plugin into a profile. **Plugin files inside a profile are a snapshot and DSH does not pick up replaced files on its own**: after changing code you must reinstall, or the page sticks at "connecting to the team space". Team data is decoupled from the profile: `DSH_TEAM_WORKSPACE` / `DSH_TEAM_DATA` alone decide the data directory. The preview server uses a fake DSH runtime — **no authentication, no DSH configuration touched, not for production**; override the port with `PORT`.
26
+ Plugin files inside a profile are a snapshot. After changing code, reinstall — otherwise the page keeps serving the old build.
46
27
 
47
- ### 2.3 Data, secrets and skills
48
-
49
- Data lives under `DSH_TEAM_DATA` (default `<workspace>/.data`, workspace root `DSH_TEAM_WORKSPACE`, default `~/.dsh/workspace/team-bots`): `team.sqlite`, `wechat-channel.sqlite`, `secret.key`, `memory/`, `messages/` and `secrets-runtime/` (burned on TTL expiry). Back up `secret.key` together with the data — without it the existing ciphertext cannot be decrypted. Schema changes go through the idempotent migrations in `src/db-migrations.js`. Skills come from a shared pool fixed at `~/.agents/skills`, plus project-local `<project>/.agents/skills`, `<project>/.claude/skills` and `<project>/.codex/skills`.
50
-
51
- A template for the common variables lives in `.env.example`; **do not put a `.env` file in the repository root**, because that would leak `DSH_*` into `npm test` and `npm run dev`.
52
-
53
- ### 2.4 Entry points and environment variables
28
+ ## Open the workspace
54
29
 
55
30
  ```text
56
- http://<host>:<port>/ auto-login, straight into the team workspace
57
- http://<host>:<port>/api/dsh-team/ui the DSH Team Bots workspace (direct)
58
- http://<host>:<port>/index.html the native DSH web UI
31
+ http://<host>:<port>/ DSH web, auto-login into the team workspace
32
+ http://<host>:<port>/api/dsh-team/ui the team workspace itself
59
33
  ```
60
34
 
61
- The first visit to the home page exchanges the current startup token for a 30-day login cookie. Auto-login means **anyone who can reach the port becomes owner**, so listen on the local machine or a trusted network; public exposure needs an HTTPS reverse proxy that forwards Host and WebSocket correctly.
35
+ The first visit exchanges the current startup token for a 30-day login cookie. Auto-login means anyone who can reach the port becomes owner, so listen on the local machine or a trusted network; for public use put an HTTPS reverse proxy in front that forwards Host and WebSocket correctly.
36
+
37
+ ## What the workspace does
62
38
 
63
- The two paths that matter are `DSH_TEAM_WORKSPACE` (team workspace root) and `DSH_TEAM_DATA` (team database and run records); every other variable, its default and its resolution order (explicit env > value saved on the page > code default) live in `src/config.js`.
39
+ ### Group chats and dispatch
64
40
 
65
- ---
41
+ Every project is a group chat. A bot can also be addressed one-to-one in a dispatch view. Session bindings run in four lanes — task, solo, dm, project — so a group chat, a task run and a direct message never block each other.
66
42
 
67
- ## 3. Feature Overview
43
+ ### Task board
68
44
 
69
- - **Project group chat:** every project has one group chat and one director bot. Plain messages, `@Bot`, `/task @Bot <title>`, `/remember` and `/clear` are supported, with `/` and `@` completions for commands, skills and members. Conclusions stay in the chat; full deliveries go to task comments.
70
- - **Task board:** a Linear-style panel grouped by status, with a parent/child tree, priority and assignee, comments delivered into running sessions, drag-to-transition, and inline delivery artefacts and run list.
71
- - **Write-scope parallel scheduling:** declared write scopes decide whether two write runs in one project may run at once; write runs are independent, and neither tasks nor chats block one another.
72
- - **Memory and skill pool:** bot- and project-level long-term memory with a human review queue; the shared skill pool is fixed at `~/.agents/skills` and projects can add their own skill directories; skill changes go through proposal approval with rollback snapshots.
73
- - **Versioned evolution and team tools:** role, model, intensity and skill changes go through proposal approval, and bot configuration keeps an immutable, rollback-able history. The plugin registers the team tools for task assignment, review, memory, recall, evolution proposals, direct bot messaging and secret requests.
74
- - **Secret pipeline:** AES-256-GCM at rest; once approved, materialised into the data directory (**not the project workspace**) and burned when the run ends or the TTL expires; messages and run output are always masked as `$<name>`.
75
- - **Usage and cost:** tokens, call counts, cost and runtime aggregated at global, project and bot level; cost comes from configurable model prices and calls without a price are not billed as zero; CSV export and monthly reconciliation are available.
76
- - **Approvals, questions and terminal:** privilege or human-answer requests become workspace cards — approvals time out to `rejected`, an expired question stays answerable. Each project has an interactive terminal with a hard timeout, live tailing, cancellation and persisted history.
77
- - **WeChat channel and code hygiene:** QR-authorised task push plus a plain-text command surface (see 4.4); a per-project line limit (800 by default) is scanned at the end of every run, and an over-limit file triggers one 【系统指令】 asking the director to schedule a split card.
45
+ States: backlog, todo, in progress, blocked, in review, done, canceled. A card carries assignee, priority, parent/child links, tags, write scopes, an optional time budget (a hard limit that aborts the run), comments, and its own usage. Rows are grouped by state and can be dragged onto another group to change status.
78
46
 
79
- ---
47
+ ### Write scopes and parallel scheduling
80
48
 
81
- ## 4. Architecture and Layout
49
+ A card declares the paths it will write, relative to the project working directory. Two runs of the same project run in parallel only when both declare scopes and the path prefixes do not overlap; a card with no declared scope is treated as serial. An urgent card may be exempted from the queue — the exemption is written into the card's creation message rather than applied silently.
82
50
 
83
- ### 4.1 Wiring
51
+ ### Memory, skills, evolution proposals
84
52
 
85
- `apply(ctx, config)` in `index.js` is the only entry point, and it assembles the layers in dependency order — configuration, database, domain service, host runtime, team tools, skill pool, HTTP. `service.initialize()` then creates the database and seeds the default bots and buddies before `service.start()` brings up the scheduler.
53
+ Memory entries are written, reviewed, frozen and archived by the owner, and are readable by every bot in the project. Skills come from a shared skill root plus per-project skills; changing them goes through a proposal, an approval and an apply, with a canary stage before promotion to full effect. The same path can change a bot's role instructions.
86
54
 
87
- ### 4.2 The `src/` directory
55
+ ### Approval and question cards
88
56
 
89
- | Path | Responsibility |
90
- | --- | --- |
91
- | `index.js`, `src/config.js`, `src/db.js`, `src/db-migrations.js` | plugin entry point; configuration resolution; SQLite access and idempotent migrations |
92
- | `src/service.js`, `src/services/`, `src/runtime.js`, `src/services/runtime/` | the `TeamService` facade and its domain methods; the host adapter (prompts, sessions, model recovery, trajectories) |
93
- | `src/http.js`, `src/api.js`, `src/tools.js`, `src/botmsg.js`, `src/skill-parse.js` | HTTP routes and UI slices; the `/api/dsh-team/api` dispatch entry; team tools; bot-to-bot messages; skill parsing |
94
- | `src/wechat/`, `src/secrets.js`, `src/pricing.js`, `src/usage*.js`, `src/skills*.js`, `src/seed-bots.js`, `src/updater.js`, `src/paths.js`, `src/util.js`, `src/errors.js` | WeChat channel; secret crypto; pricing and usage; skill pools; seed bots; update check; path boundaries; utilities; error types |
57
+ When a bot asks for a tool approval, a secret, or an answer, the workspace shows a card in the chat. The owner approves, denies or answers in place, and the decision is recorded on the card.
95
58
 
96
- ### 4.3 The `ui/` directory
59
+ ### Usage and cost
97
60
 
98
- The frontend is plain ES modules with no build step; every slice is loaded straight from an HTTP route. `ui/modules/` holds one module per domain, `ui/styles/` one CSS file per domain, and `ui/i18n/{zh,en}.js` the interface dictionaries. Contribution rules for this tree (style-slice registration, the 800-line limit) are in `CONTRIBUTING.md`.
61
+ The usage page breaks the numbers down by model, bot and project, exports CSV, and reads model prices from configuration. Run limits (timeout abort, no-progress watchdog, review idle threshold) and budgets are set per workspace.
99
62
 
100
- ### 4.4 The WeChat channel
63
+ ### Terminal, channels, secrets
101
64
 
102
- The channel is off by default (`DSH_TEAM_WECHAT=0`) and becomes active after QR authorisation. Its command surface is plain text, and `帮助 / help / ?` pulls it up at any time:
65
+ A per-project terminal runs commands in the project directory. The WeChat channel binds by QR code and pushes task activity to the owner's WeChat. Secrets are scoped to the team or to one project; values are only ever shown as a fingerprint and are handed out as one-time runtime copies that expire.
103
66
 
104
- | Command | Effect |
105
- | --- | --- |
106
- | `帮助` / `help` / `?` | show the command help |
107
- | `状态` | overview of the projects and the tasks pending review |
108
- | `验收 <task number> [comment]` | accept a delivery, e.g. `验收 web-3 做得好` |
109
- | `驳回 <task number> <reason>` | send it back for rework; the reason is mandatory |
110
- | `详情 <task number>` | show the task card and its latest comments |
111
- | `q` | list the project keys that can be assigned |
112
- | `<key>: <message>` | forward a message into the project chat for the director to arrange, e.g. `web: 上线新版官网` |
67
+ ## Configuration
113
68
 
114
- Pushes go through a local outbox; its discard policy (retry budget, batching window, connection-epoch retention) is defined in `src/wechat/channel.js`. When investigating a missed push, `outbox.attempts` and `gave_up_at` tell you whether the item was dropped by design or is still queued.
69
+ | Variable | Default | Meaning |
70
+ | --- | --- | --- |
71
+ | `DSH_TEAM_WORKSPACE` | `~/.dsh/workspace/team-bots` | team workspace root |
72
+ | `DSH_TEAM_DATA` | `<workspace>/.data` | database and run records |
115
73
 
116
- ---
74
+ Every other variable, its default, and its resolution order (explicit env > value saved in the workspace > code default) live in `src/config.ts`; `.env.example` lists the common ones. Do not put a `.env` file in the repository root — it would leak `DSH_*` into `npm test` and `npm run dev`.
117
75
 
118
- ## 5. Testing and Development Conventions
76
+ `DSH_TEAM_DATA` holds `team.sqlite`, `wechat-channel.sqlite`, `secret.key`, `memory/`, `messages/` and `secrets-runtime/`. Back up `secret.key` together with the data: without it the stored ciphertext cannot be decrypted.
119
77
 
120
- ### 5.1 Common commands
78
+ ## Develop
121
79
 
122
80
  ```sh
123
- npm test # node --test "tests/*.test.js"
124
- npm run dev # local preview (fake runtime)
125
- npm run doctor # check Node/DSH versions and the writability of the workspace and skill-pool paths
126
- npm run profile:install # pack and reinstall into a profile (team-bots by default)
127
- npm run backup # back up the team data
128
- npm run restore-check # check that a backup can be restored
81
+ npm install
82
+ npm run build # compile TypeScript into the shipped .js files
83
+ npm run typecheck
84
+ npm test # build, then node --test over tests/ and scripts/
85
+ npm run dev # local dev server on http://127.0.0.1:4317
86
+ npm run doctor # check node, dsh, paths and profile references
129
87
  ```
130
88
 
131
- ### 5.2 Guard tests and commit conventions
132
-
133
- `npm test` covers every feature domain plus the architectural pins. The guard-test details, the commit conventions and the `ui/` contribution rules are in `CONTRIBUTING.md`.
134
-
135
- ### 5.3 CI
136
-
137
- Pushing a `v*` tag triggers the publish workflow (`.github/workflows/publish.yml`): it installs dependencies, runs the full `npm test`, and only publishes to registry.npmjs.org when everything is green.
89
+ Additional harnesses: `npm run backup` / `npm run restore-check` for data, `npm run verify:agent-team` for the agent-team capability, `npm run load-test` and `npm run fault-test` for the runtime.
138
90
 
139
- ---
91
+ Repository layout:
140
92
 
141
- ## 6. Troubleshooting and FAQ
142
-
143
- **Q: I changed the code but the page is still the old one?**
144
- The plugin files inside a profile are a snapshot and are not hot-reloaded. Reinstall with `npm run profile:install -- --profile <name>`. A page stuck at "connecting to the team space" usually has the same cause.
145
-
146
- **Q: Where does the data live, and how do I take it to another machine?**
147
- Under `<DSH_TEAM_DATA>` are `team.sqlite`, `wechat-channel.sqlite`, `secret.key`, `memory/` and `messages/`. Back it up with `npm run backup`, and **do not leave `secret.key` behind** — without it the existing ciphertext can never be decrypted again.
148
-
149
- **Q: WeChat did not receive the push?**
150
- Look at `outbox.attempts` and `gave_up_at` first: a value means the item was dropped by design, not missed; no value means it is still in the queue.
151
-
152
- **Q: What is the "code hygiene" alert in the project chat?**
153
- At the end of every run the source files in the project workspace are scanned, and a file over the project's line limit (800 by default, judgement line 880) triggers one 【系统指令】 asking the director to schedule a split card. Raise the limit in the project settings, or set it to 0 to switch the check off.
154
-
155
- **Q: Can it be exposed to the public internet?**
156
- The plugin ships no sandbox: bot sessions run under DSH's `danger-full-access` as the current user. Together with auto-login (reaching the port means owner), public exposure requires an HTTPS reverse proxy and your own authentication; teams that do not trust each other should not share one DSH instance and workspace.
157
-
158
- ---
159
-
160
- ## Screenshots
161
-
162
- Usage stats carry the summary window, the last 14 days of detail, a per-model / per-bot / per-project breakdown and a CSV export:
163
-
164
- ![Usage stats](docs/assets/usage.png)
93
+ ```text
94
+ ui/ the browser workspace (modules, styles, zh/en copy)
95
+ src/ HTTP API, database, runtime and domain services
96
+ src/services/ domain logic: chat, tasks, scheduler, memory, skills, approvals, usage
97
+ src/tools.ts the tool surface bots see (team_* tools)
98
+ scripts/ build, dev server, doctor, release, backup, test harnesses
99
+ tests/ node:test suites
100
+ ```
165
101
 
166
- The global configuration page keeps only the core groups — preferences, run limits and ops; channels, secrets, version status and pricing rules live on their own top-level pages:
102
+ ## Release
167
103
 
168
- ![Global configuration](docs/assets/global-config-light.png)
104
+ ```sh
105
+ npm run release # add --dry-run to print the plan without touching anything
106
+ ```
169
107
 
170
- ---
108
+ The tool pushes `dev`, lands it on `main` (fast-forward when possible, otherwise a content snapshot), pushes `main` and the tag, then syncs `dev` back. Publishing uses npm OIDC trusted publishing — no `NPM_TOKEN` — and the workflow installs npm ≥ 11.5.1 before publishing.
171
109
 
172
110
  ## License
173
111
 
174
- Apache-2.0, see `LICENSE` and `NOTICE` in the repository root.
112
+ Apache-2.0, see `LICENSE` and `NOTICE`.
package/docs/README.zh.md CHANGED
@@ -2,173 +2,111 @@
2
2
 
3
3
  [English](../README.md)
4
4
 
5
- DSH Team Bots 是 npm 包 `dsh-team-bots`,一个 DSH(DeepSeek Harness)插件,把一整个协作的 bot 团队装进同一个工作区:项目群聊、任务板、按写范围并行调度、记忆与技能、用量与成本,外加一条个人微信通道。
5
+ `dsh-team-bots` 是一个 DSH 插件,把一个工作区变成一支团队:项目群聊、任务板、写范围并行调度、共享记忆与技能、审批卡、用量与成本,以及个人微信通道。每次运行都留下轨迹、时长、token 数与成本。
6
6
 
7
- ![DSH Team Bots 工作区](assets/tasks.png)
7
+ ## 运行前提
8
8
 
9
- 本文件是项目文档的中文版,英文版见 [../README.md](../README.md)。
9
+ - Node.js ≥ 22.19
10
+ - DSH 命令行(`dsh`)
10
11
 
11
- ---
12
+ 插件运行在 DSH Web 进程内,没有独立服务,也不单独占端口。
12
13
 
13
- ## 1. 项目简介与定位
14
-
15
- `dsh-team-bots` 跑在 DSH Web 进程里 —— 没有独立服务 —— 让多个 bot 在同一个项目空间里分工,并把整个协作暴露成一个可操作的 Web 工作区。
16
-
17
- 1. **协作发生在项目里,而不是聊天窗里。** 每个项目有自己的群聊、成员、任务和工作目录;项目 director bot 在那里拆分、派发和验收工作。
18
- 2. **并行是声明出来的,不是碰运气。** 任务声明它会写哪些路径;调度器只在两个写 run 都声明、且写路径前缀互不重叠时,才让它们在同一项目里并行。没声明的一律按串行处理。
19
- 3. **一切可追溯。** 每个 run 都保留轨迹、时长、token 数和成本;bot 配置保留可回滚的不可变历史;密钥在落盘时加密,使用时才物化成一次性明文文件,用完即焚。
20
-
21
- 仓库结构:`index.js` 是插件入口,`src/` 是服务端与调度器,`ui/` 是工作区前端,`tests/` 是守门测试,`docs/` 是设计稿、评审记录和截图。
22
-
23
- ---
24
-
25
- ## 2. 快速开始
26
-
27
- ### 2.1 环境要求与安装
28
-
29
- Node.js ≥ 22.19(见 `package.json` 的 `engines`),并装好 DSH CLI(`dsh --version`);插件跑在 DSH Web 进程里,没有独立进程和端口。
14
+ ## 安装
30
15
 
31
16
  ```sh
32
- cd <repo>
33
- npm pack # 产出 dsh-team-bots-<version>.tgz
34
- dsh plugin --profile <name> add ./dsh-team-bots-<version>.tgz
35
- dsh --profile <name> # 从启动日志里读带 token 的 dsh web 入口
17
+ dsh plugin --profile <name> add dsh-team-bots
36
18
  ```
37
19
 
38
- ### 2.2 重装与本地预览
20
+ 从源码装(打包当前工作树并装进指定 profile):
39
21
 
40
22
  ```sh
41
- npm run profile:install -- --profile <name> # 省略 --profile 时装进 team-bots
42
- npm run dev # 本地预览 http://127.0.0.1:4317,假 runtime
23
+ npm run profile:install -- --profile <name>
43
24
  ```
44
25
 
45
- `profile:install` 把仓库打包并重装进 profile。**profile 里的插件文件是快照,DSH 不会自动加载替换后的文件**:改了代码必须重装,否则页面会卡在「connecting to the team space」。团队数据与 profile 解耦:数据目录只由 `DSH_TEAM_WORKSPACE` / `DSH_TEAM_DATA` 决定。预览服务器用的是假 DSH runtime —— **不做鉴权、不动 DSH 配置、不可用于生产**;端口可用 `PORT` 覆盖。
26
+ profile 里的插件文件是一份快照。改完代码要重新安装,否则页面一直跑旧版本。
46
27
 
47
- ### 2.3 数据、密钥与技能放在哪
48
-
49
- 数据位于 `DSH_TEAM_DATA`(缺省 `<workspace>/.data`,工作区根目录 `DSH_TEAM_WORKSPACE`,缺省 `~/.dsh/workspace/team-bots`):`team.sqlite`、`wechat-channel.sqlite`、`secret.key`、`memory/`、`messages/` 和 `secrets-runtime/`(TTL 到期即焚)。备份时请把 `secret.key` 一起带走 —— 没有它,已有的密文永远解不开。表结构变更走 `src/db-migrations.js` 的幂等迁移。技能来自固定在 `~/.agents/skills` 的共享池,以及项目本地的 `<project>/.agents/skills`、`<project>/.claude/skills`、`<project>/.codex/skills`。
50
-
51
- 常用变量的模板在 `.env.example`;**不要把 `.env` 放在仓库根目录**,否则 `DSH_*` 会漏进 `npm test` 和 `npm run dev`。
52
-
53
- ### 2.4 访问入口与常用环境变量
28
+ ## 打开工作台
54
29
 
55
30
  ```text
56
- http://<host>:<port>/ 自动登录,直接进入团队工作区
57
- http://<host>:<port>/api/dsh-team/ui DSH Team Bots 工作区(直达)
58
- http://<host>:<port>/index.html DSH 原生 Web UI
31
+ http://<host>:<port>/ DSH Web 首页,自动登录进团队工作台
32
+ http://<host>:<port>/api/dsh-team/ui 团队工作台本身
59
33
  ```
60
34
 
61
- 首次访问首页会用当前启动 token 换一张 30 天登录 cookie。自动登录意味着**任何能访问到端口的人都是 owner**,所以请只监听本机或可信网络;要公网暴露,需要一个正确转发 Host 与 WebSocket 的 HTTPS 反向代理。
35
+ 首次访问会把当前启动 token 换成 30 天登录 cookie。自动登录意味着能访问该端口的人就是 owner,请只监听本机或可信网络;要对外暴露,前面放一层转发 Host 与 WebSocket 的 HTTPS 反向代理。
36
+
37
+ ## 工作台能做什么
62
38
 
63
- 真正要紧的两个路径是 `DSH_TEAM_WORKSPACE`(团队工作区根目录)和 `DSH_TEAM_DATA`(团队数据库与 run 记录);其余变量、缺省值和解析顺序(显式 env > 页面保存值 > 代码缺省)都在 `src/config.js`。
39
+ ### 群聊与调度
64
40
 
65
- ---
41
+ 每个项目是一个群聊;单个 Bot 也可以被单独一对一调度。会话绑定分四道车道——task、solo、dm、project——群聊、任务运行和私信互不阻塞。
66
42
 
67
- ## 3. 功能总览
43
+ ### 任务板
68
44
 
69
- - **项目群聊:** 每个项目一个群聊、一个 director bot。支持纯文本、`@Bot`、`/task @Bot <标题>`、`/remember` 和 `/clear`,`/` 与 `@` 可补全命令、技能和成员。结论留在聊天里,完整交付走任务评论。
70
- - **任务板:** Linear 风格、按状态分组的面板,带父子树、优先级与负责人,评论会送进正在跑的会话,支持拖拽流转,行内展示交付物和 run 列表。
71
- - **按写范围并行调度:** 由声明的写范围决定同一项目的两个写 run 能否同时跑;写 run 彼此独立,任务和聊天互不阻塞。
72
- - **记忆与技能池:** bot 级和项目级长期记忆,带人工审核队列;共享技能池固定在 `~/.agents/skills`,项目可追加自己的技能目录;技能变更走提案审批并保留回滚快照。
73
- - **版本化演进与团队工具:** 角色、模型、强度和技能变更走提案审批,bot 配置保留不可变、可回滚的历史。插件注册了任务派发、评审、记忆、召回、演进提案、bot 间直发消息和密钥申请等团队工具。
74
- - **密钥流水线:** 落盘用 AES-256-GCM;审批通过后物化到数据目录(**不是项目工作区**),run 结束或 TTL 到期即焚;消息和 run 输出里始终以 `$<name>` 掩码。
75
- - **用量与成本:** token、调用次数、成本和运行时长按全局、项目、bot 三级汇总;成本来自可配置的模型价格,未配置价格的调用不按 0 计费;支持 CSV 导出和月度对账。
76
- - **审批、提问与终端:** 提权或要人回答的请求变成工作区卡片 —— 审批超时变 `rejected`,提问过期后仍可回答。每个项目有一个交互式终端,带硬超时、实时 tail、取消和持久历史。
77
- - **微信通道与代码卫生:** 扫码授权后推送任务,外加纯文本命令面(见 4.4);每个项目有行数上限(缺省 800),每个 run 结束时扫描,超限文件触发一条【系统指令】请 director 派拆分卡。
45
+ 状态:待规划、待执行、进行中、受阻、待验收、已完成、已取消。一张卡带负责人、优先级、父子任务、标签、写范围、可选的时效要求(硬性时限,到期中止运行)、评论,以及本卡自己的用量。任务行按状态分组,可拖到别的分组直接改状态。
78
46
 
79
- ---
47
+ ### 写范围与并行调度
80
48
 
81
- ## 4. 架构与目录说明
49
+ 每张卡声明自己会写哪些路径(相对项目工作目录)。同一项目下两个运行只有在双方都声明了写范围、且路径前缀互不重叠时才并行;没声明写范围的卡按串行处理。紧急卡可以豁免排队,但豁免会写进建卡消息,不做静默处理。
82
50
 
83
- ### 4.1 装配链路
51
+ ### 记忆、技能与进化提案
84
52
 
85
- `index.js` 里的 `apply(ctx, config)` 是唯一入口,它按依赖顺序把各层装起来 —— 配置、数据库、领域服务、宿主 runtime、团队工具、技能池、HTTP。`service.initialize()` 先建库、播种缺省 bot 与 buddy,之后 `service.start()` 才拉起调度器。
53
+ 记忆由 owner 写入、复核、冻结与归档,项目内所有 Bot 都能读到。技能来自共享技能根目录加项目级技能;改动走提案 → 审批 → 落地,先灰度再转全量。同一条路径也能改 Bot 的角色指令。
86
54
 
87
- ### 4.2 `src/` 目录
55
+ ### 审批卡与提问卡
88
56
 
89
- | 路径 | 职责 |
90
- | --- | --- |
91
- | `index.js`、`src/config.js`、`src/db.js`、`src/db-migrations.js` | 插件入口;配置解析;SQLite 访问与幂等迁移 |
92
- | `src/service.js`、`src/services/`、`src/runtime.js`、`src/services/runtime/` | `TeamService` 门面及其领域方法;宿主适配器(提示词、会话、模型恢复、轨迹) |
93
- | `src/http.js`、`src/api.js`、`src/tools.js`、`src/botmsg.js`、`src/skill-parse.js` | HTTP 路由与 UI 切片;`/api/dsh-team/api` 分发入口;团队工具;bot 间消息;技能包解析 |
94
- | `src/wechat/`、`src/secrets.js`、`src/pricing.js`、`src/usage*.js`、`src/skills*.js`、`src/seed-bots.js`、`src/updater.js`、`src/paths.js`、`src/util.js`、`src/errors.js` | 微信通道;密钥加解密;定价与用量;技能池;种子 bot;更新检查;路径边界;工具函数;错误类型 |
57
+ Bot 要工具审批、要密钥或要人回答时,工作台在聊天里出一张卡。owner 就地批准、拒绝或回答,结论记在卡上。
95
58
 
96
- ### 4.3 `ui/` 目录
59
+ ### 用量与成本
97
60
 
98
- 前端是纯 ES 模块,无构建步骤,每个切片由 HTTP 路由直接加载。`ui/modules/` 每个领域一个模块,`ui/styles/` 每个领域一个 CSS 文件,`ui/i18n/{zh,en}.js` 是界面字典。这棵树的贡献约定(样式切片注册、800 行铁律)见 `CONTRIBUTING.md`。
61
+ 用量页按模型、按 Bot、按项目拆分,可导出 CSV,模型价格来自配置。运行限制(超时中止、无进展看门狗、验收滞留阈值)与预算按工作区设置。
99
62
 
100
- ### 4.4 微信通道
63
+ ### 终端、通道与密钥
101
64
 
102
- 通道缺省关闭(`DSH_TEAM_WECHAT=0`),扫码授权后启用。命令面是纯文本,随时可用 `帮助 / help / ?` 唤出:
65
+ 每个项目有终端,在项目目录里执行命令。微信通道扫码绑定后,把任务动态推给 owner 的微信。密钥分团队级与项目级,界面上只显示指纹,取值以一次性运行时副本下发,到期即失效。
103
66
 
104
- | 命令 | 作用 |
105
- | --- | --- |
106
- | `帮助` / `help` / `?` | 显示命令帮助 |
107
- | `状态` | 项目与待验收任务总览 |
108
- | `验收 <任务号> [评语]` | 验收交付,如 `验收 web-3 做得好` |
109
- | `驳回 <任务号> <原因>` | 打回重做,原因必填 |
110
- | `详情 <任务号>` | 显示任务卡与最新评论 |
111
- | `q` | 列出可指派的项目 key |
112
- | `<key>: <消息>` | 转发消息到项目群聊交 director 安排,如 `web: 上线新版官网` |
67
+ ## 配置
113
68
 
114
- 推送走本地 outbox,其丢弃策略(重试预算、批量窗口、连接周期保留)定义在 `src/wechat/channel.js`。排查漏推时看 `outbox.attempts` 和 `gave_up_at`:有值说明该条目是被设计丢弃的,没值说明还在队列里。
69
+ | 变量 | 默认值 | 含义 |
70
+ | --- | --- | --- |
71
+ | `DSH_TEAM_WORKSPACE` | `~/.dsh/workspace/team-bots` | 团队工作区根目录 |
72
+ | `DSH_TEAM_DATA` | `<workspace>/.data` | 数据库与运行记录 |
115
73
 
116
- ---
74
+ 其余变量的默认值与解析顺序(显式环境变量 > 页面上保存的值 > 代码默认值)都写在 `src/config.ts`,常用项见 `.env.example`。不要在仓库根目录放 `.env`,否则 `DSH_*` 会泄进 `npm test` 和 `npm run dev`。
117
75
 
118
- ## 5. 测试与开发约定
76
+ `DSH_TEAM_DATA` 下有 `team.sqlite`、`wechat-channel.sqlite`、`secret.key`、`memory/`、`messages/` 与 `secrets-runtime/`。备份时把 `secret.key` 和数据一起带走——没有它,已存的密文解不开。
119
77
 
120
- ### 5.1 常用命令
78
+ ## 开发
121
79
 
122
80
  ```sh
123
- npm test # node --test "tests/*.test.js"
124
- npm run dev # 本地预览(假 runtime)
125
- npm run doctor # 检查 Node/DSH 版本,以及工作区与技能池路径的可写性
126
- npm run profile:install # 打包并重装进 profile(缺省 team-bots)
127
- npm run backup # 备份团队数据
128
- npm run restore-check # 检查备份能否恢复
81
+ npm install
82
+ npm run build # 把 TypeScript 编译成发布的 .js
83
+ npm run typecheck
84
+ npm test # 先 build,再对 tests/ 与 scripts/ 跑 node --test
85
+ npm run dev # 本地开发服务器:http://127.0.0.1:4317
86
+ npm run doctor # 检查 node、dsh、路径与 profile 引用
129
87
  ```
130
88
 
131
- ### 5.2 守门测试与提交约定
132
-
133
- `npm test` 覆盖每个功能域,另加几条架构约定的钉子。守门测试细节、提交约定和 `ui/` 贡献约定都在 `CONTRIBUTING.md`。
134
-
135
- ### 5.3 CI
136
-
137
- 推送 `v*` tag 触发发布工作流(`.github/workflows/publish.yml`):装依赖、跑完整 `npm test`,全绿才发布到 registry.npmjs.org。
89
+ 另有几套工具:`npm run backup` / `npm run restore-check` 备份与校验数据,`npm run verify:agent-team` 验证 agent team 能力,`npm run load-test` 与 `npm run fault-test` 压运行时。
138
90
 
139
- ---
91
+ 仓库结构:
140
92
 
141
- ## 6. 故障排查与常见问题
142
-
143
- **Q:改了代码,页面还是旧的?**
144
- profile 里的插件文件是快照,不会热加载。用 `npm run profile:install -- --profile <name>` 重装。页面卡在「connecting to the team space」通常也是同一个原因。
145
-
146
- **Q:数据在哪,怎么搬到另一台机器?**
147
- `<DSH_TEAM_DATA>` 下有 `team.sqlite`、`wechat-channel.sqlite`、`secret.key`、`memory/` 和 `messages/`。用 `npm run backup` 备份,**不要把 `secret.key` 落下** —— 没有它,已有密文永远解不开。
148
-
149
- **Q:微信没收到推送?**
150
- 先看 `outbox.attempts` 和 `gave_up_at`:有值说明条目是被设计丢弃的,不是漏发;没值说明还在队列里。
151
-
152
- **Q:项目聊天里的「代码卫生」提醒是什么?**
153
- 每个 run 结束时会扫描项目工作区里的源文件,超过项目行数上限(缺省 800,判定线 880)的文件会触发一条【系统指令】请 director 派拆分卡。可在项目设置里调高上限,或设为 0 关闭检查。
154
-
155
- **Q:能暴露到公网吗?**
156
- 插件本身不带沙箱:bot 会话以当前用户身份跑在 DSH 的 `danger-full-access` 下。加上自动登录(能访问端口就是 owner),公网暴露需要 HTTPS 反向代理和自有鉴权;互不信任的团队不应共用同一个 DSH 实例和工作区。
157
-
158
- ---
159
-
160
- ## 截图
161
-
162
- 用量统计带汇总窗口、最近 14 天明细、按模型 / 按 bot / 按项目拆分和 CSV 导出:
163
-
164
- ![用量统计](assets/usage.png)
93
+ ```text
94
+ ui/ 浏览器端工作台(modules、styles、中英文案)
95
+ src/ HTTP 接口、数据库、运行时与领域服务
96
+ src/services/ 领域逻辑:chat、tasks、scheduler、memory、skills、approvals、usage
97
+ src/tools.ts Bot 看到的工具面(team_* 系列)
98
+ scripts/ 构建、开发服务器、doctor、发版、备份与测试工具
99
+ tests/ node:test 用例
100
+ ```
165
101
 
166
- 全局配置页只保留偏好、运行时效与系统运维核心组;通道、密钥、版本与价格规则在各自的一级页:
102
+ ## 发版
167
103
 
168
- ![全局配置](assets/global-config-light.png)
104
+ ```sh
105
+ npm run release # 加 --dry-run 可只打印计划,不做任何改动
106
+ ```
169
107
 
170
- ---
108
+ 工具先把 `dev` 推上去,再把 dev 落到 `main`(能快进就快进,否则落一份内容快照),推 `main` 与 tag,最后把 `dev` 同步回来。发布走 npm OIDC trusted publishing,不用 `NPM_TOKEN`,工作流在发布前会把 npm 升到 ≥ 11.5.1。
171
109
 
172
- ## License
110
+ ## 许可
173
111
 
174
- Apache-2.0,见仓库根目录的 `LICENSE` 和 `NOTICE`。
112
+ Apache-2.0,见 `LICENSE` 与 `NOTICE`。
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-team-bots",
3
- "version": "0.2.289",
3
+ "version": "0.2.347",
4
4
  "description": "Project spaces, group chats, task boards, memory and usage for teams of DSH bots",
5
5
  "repository": {
6
6
  "type": "git",
@@ -19,21 +19,33 @@
19
19
  "files": [
20
20
  "index.js",
21
21
  "src/",
22
+ "!src/**/*.ts",
22
23
  "scripts/doctor.mjs",
23
24
  "ui/",
25
+ "!ui/**/*.ts",
24
26
  "vendor/",
25
27
  "cordis.patch.yml",
26
28
  "README.md",
27
- "CONTRIBUTING.md",
28
29
  "docs/README.zh.md",
29
30
  "docs/assets/",
30
31
  "NOTICE",
31
32
  "LICENSE"
32
33
  ],
34
+ "devDependencies": {
35
+ "@types/node": "26.6.6",
36
+ "typescript": "6.0.3"
37
+ },
33
38
  "scripts": {
34
- "test": "node --test \"tests/*.test.js\"",
35
- "dev": "node scripts/dev-server.js",
36
- "start": "node scripts/dev-server.js",
39
+ "build": "node scripts/build.mjs",
40
+ "typecheck": "tsc -p tsconfig.json",
41
+ "pretest": "npm run build",
42
+ "test": "node --test \"tests/*.test.js\" \"scripts/*.test.js\"",
43
+ "release": "node scripts/release.mjs",
44
+ "predev": "npm run build",
45
+ "dev": "node scripts/dev-server.mjs",
46
+ "prestart": "npm run build",
47
+ "start": "node scripts/dev-server.mjs",
48
+ "prepack": "npm run build",
37
49
  "doctor": "node scripts/doctor.mjs",
38
50
  "profile:install": "node scripts/install-profile.mjs",
39
51
  "verify:agent-team": "node scripts/verify-agent-team.mjs",
@@ -29,7 +29,7 @@ const describe = path => {
29
29
  let entry
30
30
  try {
31
31
  entry = lstatSync(path)
32
- } catch (error) {
32
+ } catch (error ) {
33
33
  if (error.code === 'ENOENT') return { label: 'missing', dir: false, target: null }
34
34
  return { label: error.code === 'ELOOP' ? 'broken symlink loop' : (error.code ?? 'error'), dir: false, target: null }
35
35
  }
@@ -44,7 +44,7 @@ const describe = path => {
44
44
  dir: targetEntry.isDirectory(),
45
45
  target,
46
46
  }
47
- } catch (error) {
47
+ } catch (error ) {
48
48
  return {
49
49
  label: error.code === 'ELOOP' ? 'broken symlink loop' : `dangling symlink (${error.code ?? 'error'})`,
50
50
  dir: false,
@@ -67,7 +67,7 @@ const writable = path => {
67
67
 
68
68
  function main() {
69
69
  const config = resolveConfig()
70
- const targets = [
70
+ const targets = [
71
71
  ['DSH home', config.dshHome, true],
72
72
  ['workspace', config.workspace, false],
73
73
  ['data dir', config.dataDir, false],
@@ -78,7 +78,7 @@ function main() {
78
78
  console.log(`node ${process.versions.node} uid=${process.getuid?.() ?? 'n/a'} gid=${process.getgid?.() ?? 'n/a'} home=${homedir()}`)
79
79
 
80
80
  const dsh = spawnSync('dsh', ['--version'], { encoding: 'utf8' })
81
- const dshVersion = dsh.status === 0 ? String(dsh.stdout).trim() : (dsh.error?.code === 'ENOENT' ? 'not installed' : 'unknown')
81
+ const dshVersion = dsh.status === 0 ? String(dsh.stdout).trim() : ((dsh.error )?.code === 'ENOENT' ? 'not installed' : 'unknown')
82
82
  console.log(`dsh ${dshVersion}`)
83
83
  console.log('')
84
84