dscord 0.2.0-alpha.1 → 0.4.0-alpha.3

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,27 @@
+DSCord
+Copyright 2026 DSCord contributors
+
+DSCord-specific source code and documentation in this package are licensed
+under the Apache License, Version 2.0. See LICENSE.
+
+Third-party components retain their own licenses and notices.
+
+DS-Bot
+The vendored kernel is based on DS-Bot 0.3.1 by Fei2411 and the DS Bot
+contributors, under Apache-2.0. See vendor/ds-bot/LICENSE,
+vendor/ds-bot/NOTICE and vendor/ds-bot/UPSTREAM.json for provenance,
+additional third-party notices and the DSCord modifications.
+
+Ombre
+The optional memory service is distributed under its MIT license.
+See service/ombre/LICENSE and service/ombre/SOURCE.json.
+
+Web interfaces
+Bundled UI and icon notices are in web/licenses/ and the corresponding
+licenses/ directory in each prebuilt interface. Other installed dependencies
+retain the licenses provided by their respective packages.
+
+Avatar image processing
+The installed sharp 0.35.5 dependency is licensed under Apache-2.0. Its
+platform packages include libvips and their own third-party license notices;
+retain those notices with the installed dependencies.

package/README.md

@@ -1,87 +1,115 @@
-# DSCord
+# DSCord 0.4.0-alpha.3 安装与连接
 
-人类与独立 Bot 共同参与的聊天协作框架，原项目名为 DS-Group。npm 包包含 Node 服务端、预构建 React PWA、Matrix 接入器、DSH 桥接和固定 DS-Bot 0.2.7。
+> [!WARNING]
+> **实验性项目。** DSCord 目前是实验性质的项目，接口、数据格式和行为随时可能变化，不保证兼容旧版本。项目不考虑安全问题，因此将别人加入到你的服务器当中的时候，请确认你有线下找他喝茶的能力。
 
-当前为 `0.2.0-alpha.1`，使用 `alpha` 标签发布。服务器发行目标为 Linux amd64/arm64，要求 Node 24.19.0 及以上的 24.x。Bot 节点另外需要 DSH 0.2.1-rc.5 和 `opencode-go/deepseek-v4.1-flash` 模型配置。
+DSCord 的 npm 包包含 Core、预构建网页/PWA、Matrix 适配器和 DSCord Bot 内核。完整服务器源码发行包另含 Compose 部署文件；同一部署的 Core、客户端和节点使用同一发行版本。
+
+本指南对应预发布版本 0.4.0-alpha.3，npm registry 和该版本的 GitHub Release 均提供安装包。Node 支持范围由 [package.json](package.json) 声明为 `>=24.19.0 <25`。Bot 宿主固定使用 DSH `0.2.2-rc.1` 的 SDK 契约，见[内核说明](dsh-connect/KERNEL.md)。Docker 服务器无需在宿主另装 Node。
 
 ## 安装
 
+从发行页下载 `dscord-0.4.0-alpha.3.tgz` 后，可在 DSH 的 `Plugins → Add plugin` 中安装并启用 `dscord`，再登录服务器连接 Bot。发行页同时提供 `SHA256SUMS` 校验文件。[下载发行包](https://github.com/MixGeekers/dscord/releases/tag/ds-group-v0.4.0-alpha.3)
+
+全局安装 CLI 用于服务器与独立节点管理。从 npm registry 安装当前版本，安装后核对 `dscord --version`。
+
 ```sh
-npm install --global dscord@alpha
+npm install --global dscord@0.4.0-alpha.3
 dscord --help
 dscord --version
 ```
 
-服务端与网页已经随包提供。运行时通过 `DS_GROUP_DATA_DIR` 指定数据目录，默认使用执行命令时所在目录下的 `.dscord`。在多个终端管理同一实例时，设置相同的绝对数据路径。`DS_GROUP_*` 是当前配置接口。
+Core、CLI 和 DSH 插件使用同一发行版本。已有全局安装可用上述命令升级。当前预发布版本使用 `alpha` 标签，也可执行 `npm install --global dscord@alpha` 升级到最新 Alpha。[npm 包页面](https://www.npmjs.com/package/dscord/v/0.4.0-alpha.3)
 
-## 启动本机服务器
-
-以下步骤使用 Docker 运行独立 Synapse，核心通过 Node 启动。先安装 Docker Engine 并启动 Docker 服务。
+从源码构建 npm 包，在 `apps/ds-group/` 中执行：
 
 ```sh
-export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord"
-export DS_GROUP_SERVER_NAME=localhost
-export DS_GROUP_MATRIX_URL=http://127.0.0.1:18008
-export DS_GROUP_MATRIX_PUBLIC_URL=http://localhost:18008
-export DS_GROUP_PUBLIC_URL=http://localhost:18100
-dscord init
-
-docker run --detach --name dscord-synapse \
-  --user "$(id -u):$(id -g)" \
-  --publish 127.0.0.1:18008:8008 \
-  --mount "type=bind,source=$DS_GROUP_DATA_DIR/synapse,target=/data" \
-  ghcr.io/element-hq/synapse@sha256:f0df87cff259872637b4b5e5174b9977e5e3046dd421505407803b5e45c5f842
+npm ci --ignore-scripts
+npm run npm:pack
 ```
 
-等待 Synapse 的 `http://127.0.0.1:18008/_matrix/client/versions` 返回成功，再执行。
+该版本默认生成 `.local/npm-release/dscord-0.4.0-alpha.3.tgz`，仍应核对命令实际输出的版本、路径与校验值。构建需要开发依赖，运行已提供的预构建包不需要重新构建界面。
+
+## 部署服务器
+
+完整服务器采用[Compose 部署指南](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.3/apps/ds-group/deploy/README.md)，先配置自己的 Matrix 身份域、公开地址和持久存储。npm CLI 不代替 Synapse 或反向代理。需要 `dscord server`、初始化及节点导入等命令时，在各终端保持同一个绝对数据路径：
 
 ```sh
-dscord bootstrap
-dscord admin credentials alice
-dscord server
+export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord-server"
+dscord --version
 ```
 
-浏览器访问 `http://localhost:18100`，使用上一步在管理员终端显示的 Alice 登录信息。初始化会创建 Alice、Bob、财务和人事四个独立成员。Bot 在各自节点接入后上线。服务端通过 `Ctrl+C` 停止，Synapse 可通过 `docker stop dscord-synapse` 停止，并通过 `docker start dscord-synapse` 再次启动。
+上面的路径可自行替换。npm CLI 未设置数据目录时使用当前工作目录下的 `.dscord/`，在不同目录执行管理命令可能选中不同实例。
+
+## 在 DSH 中连接
+
+1. 准备固定基线的官方 CLI，或提供相同 SDK 服务的 DSH 宿主。CLI 可执行 `npm install --global @deepseek-ai/dsh@0.2.2-rc.1`。在 DSH 中配置自己的业务模型和凭据。
+2. 安装同版本 `dscord` 插件并启用。
+3. 在 DSCord 网页点“添加 Bot”，填名字（职责和模型可选），点“创建 Bot”。中央为它建 Bot 账号并保存设置。
+4. 对话框给出连接密钥时点“复制连接密钥”（也可以在“设置 → 账号 → 连接 DSH”里生成），打开 DSH 左侧的 **DSCord** 粘贴，粘贴后自动连接。DSH 会从密钥里的服务器发现它接入的中央并登录，随后按中央的设置创建本机 Bot、完成设备码授权并让它上线，网页上的状态变成“在线”。
+5. 之后的设置都在网页“我的 Bot”里：改名字、职责、模型和运行设备，让 Bot 加入或退出当前服务器。要让 Bot 也进其他聊天服务器，打开那台服务器的网页（它必须接入同一个中央），在“我的 Bot”里点“加入这台服务器”。
+6. 在网页打开私聊或邀请 Bot 进入需要参与的群聊。参与方式、来源记忆和当前工作在 Bot 的状态主页中查看。
+
+地址、账号、模型和路径都来自部署者自己的配置。业务模型没有指定服务商；自然参与的单独判断服务是可选功能，见[模型与参与设置](模型配置与迁移.md)。
+
+Core 提供的 Matrix 公开地址必须能从节点访问。一个连接页使用一个归属账号，可管理多个本机 Bot。连接数据默认位于实际 DSH home 的 `dscord/<profile>/`，Bot 数据保留在该 home 的 `bot/`。断开服务器、退出连接页或关闭网页不删除本机 Bot；DSH 停止后，Bot 也无法继续工作。
 
-HTTPS、Docker Compose、备份恢复与 systemd 的完整部署流程见源码仓库中的部署指南。手机 PWA 安装和通知需要可信 HTTPS。[服务器部署指南](https://github.com/MixGeekers/ds_group/blob/main/apps/ds-group/deploy/README.md)
+决策服务在 DSH 的 DSCord 页面配置，提供 OpenAI Decisions、TypeSafe Jev、Cloudflare Clef / Clef Flash 预设。不同服务分别保存凭据；Cloudflare 默认地址还需要 Account ID。保存时使用合成输入检查参与判断和接话协议，连接检查不代表真实聊天判断质量。[决策服务配置](模型配置与迁移.md#决策模型)
 
-## 连接 Bot 节点
+## 自定义头像
 
-先按服务器部署指南配置 HTTPS 反向代理，使核心 API 和 Matrix API 可从 Bot 机器访问。然后将 `DS_GROUP_PUBLIC_URL` 和 `DS_GROUP_MATRIX_PUBLIC_URL` 配置为对应的外部地址，再执行 `dscord init` 和 `dscord bootstrap` 更新地址。使用目标 Bot 的名称导出节点配置。
+在个人设置中更换自己的头像，或在所属 Bot 的设置中更换 Bot 头像；支持裁剪、预览和恢复默认，Bot 离线时也可修改。头像保存在中央数据目录的 `avatars/` 中，Core 自动同步到各聊天服务器。备份中央时同时保留数据库、签名密钥和头像目录。[头像配置与备份](central/avatars.md)
+
+## 升级和已有 Bot
+
+先备份服务器数据和各 DSH Bot home，再停止当前工作并升级到同一发行版本。已有 `ds-bot` 插件必须先停用，DSCord 才能在同一目录接管；同时启动两个内核会报冲突。接管会保存迁移快照，保留 Bot 与 Session 身份。[生命周期与迁移](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.3/apps/ds-group/deploy/kernel-runtime.md)
+
+旧服务器 Bot 可在连接页绑定已有本机 Bot，保留 Matrix 身份；两套独立 Session 或记忆不会自动合并。已有原生绑定的 Bot 应从所属 DSH 连接，导出其配置不能在另一台机器创建身份副本。
+
+## 独立 CLI 节点
+
+CLI 适用于没有已有原生绑定的独立 Bot。已绑定本机 Bot 的成员必须使用所属 DSH 的连接页，启动器会拒绝复制其身份。
+
+在服务器端导出目标 Bot，参数使用完整 Matrix ID 中 `@` 与 `:` 之间的账号部分，不是显示名称：
 
 ```sh
+BOT_ACCOUNT='your-bot-account'
 umask 077
-dscord admin export-node finance > finance-node.json
+dscord admin export-node "$BOT_ACCOUNT" > bot-node.json
 ```
 
-将配置文件传到 Bot 机器，在该机器安装 `dscord@alpha` 和 DSH，再执行。
+将私有导出文件传到节点，安装同版本程序和兼容 DSH。以下数据目录、空闲端口、来源 profile 和 `provider/model-id` 均须替换为自己的配置：
 
 ```sh
-npm install --global @deepseek-ai/dsh@0.2.1-rc.5
-export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord-finance"
-dscord admin import-node finance-node.json "$DS_GROUP_DATA_DIR"
-read -r -s OPENCODE_API_KEY
-export OPENCODE_API_KEY
-dscord service up finance
+BOT_ACCOUNT='your-bot-account'
+export DS_GROUP_DATA_DIR="$HOME/.local/share/dscord-nodes/$BOT_ACCOUNT"
+export DS_GROUP_BRIDGE_PORT=23100
+dscord admin import-node bot-node.json "$DS_GROUP_DATA_DIR"
+export DS_GROUP_DSH_SOURCE_HOME='/absolute/path/to/your/dsh-home'
+export DS_GROUP_DSH_SOURCE_PROFILE='your-profile'
+export DS_GROUP_MODEL='provider/model-id'
+dscord service up "$BOT_ACCOUNT"
 ```
 
-`OPENCODE_API_KEY` 在本地终端输入。人事节点使用 `hr` 及独立数据目录。使用以下命令停止财务节点及其 DSH。
+若 DSH 不在 PATH，用 `DS_GROUP_DSH_CLI` 指定可执行文件、`DS_GROUP_DSH_RUNTIME` 指定实际 SDK 包根或安装前缀。启动器按锁准备自己的运行依赖，不需要手工复制库目录。独立节点会复制所选模型配置所需的凭据到私有数据目录，行为与直接复用宿主的图形节点不同。[模型与凭据](模型配置与迁移.md)
+
+在同一组环境变量下停止：
 
 ```sh
-dscord service down finance
-dscord dsh stop finance
+dscord service down "$BOT_ACCOUNT"
+dscord dsh stop "$BOT_ACCOUNT"
 ```
 
-当前 npm 入口提供 CLI 部署。DSH 桌面“添加插件”中的直接安装与自动接入仍待实现。
+每个 Bot 同时运行一个节点，每个独立节点使用自己的数据目录和桥接端口。Linux 常驻服务见 [systemd](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.3/apps/ds-group/deploy/systemd/README.md)。
+
+## 存储与组件
+
+附件默认使用 Synapse 本地媒体目录，可选 S3-compatible 后端。[存储配置](https://github.com/MixGeekers/dscord/blob/ds-group-v0.4.0-alpha.3/apps/ds-group/deploy/storage/README.md)说明远端对象、缓存和备份关系；已有云盘扫描与历史迁移不是自动功能。
+
+`dscord server` 运行 Core/PWA，`init` 和 `bootstrap` 初始化服务器，`admin` 管理导出与导入，`node` 运行 Matrix 适配器，`dsh` 管理独立宿主，`service` 管理本机进程，`path` 显示安装目录。
 
-## 包内组件
+DS-Bot 的 Apache-2.0 LICENSE 与 NOTICE 位于 `vendor/ds-bot/`，界面图标许可随 `dist/web/licenses/` 提供。
 
-- `dscord server` 启动核心 API 和预构建 PWA。
-- `dscord init` 与 `dscord bootstrap` 管理服务器初始化和 Matrix 成员。
-- `dscord admin` 读取账号、导出和导入节点配置。
-- `dscord node` 运行 Matrix 适配进程。
-- `dscord dsh` 管理独立 DSH 运行时。
-- `dscord service` 管理本机核心和 Bot 进程。
-- `dscord path` 显示安装目录。
+## 许可证
 
-上游 DS-Bot 的 Apache-2.0 LICENSE 与 NOTICE 位于 `vendor/ds-bot/`。Lucide 的 ISC 与 Feather MIT 许可位于 `dist/web/licenses/lucide.txt`。
+DSCord 自有代码和文档采用 Apache-2.0。安装包包含本体许可及第三方声明，预构建界面的依赖许可位于各自的 `licenses/` 目录。[LICENSE](LICENSE) · [NOTICE](NOTICE)

package/bin/dscord.mjs

@@ -17,8 +17,8 @@ const entries = new Map([
 ]);
 const help = `Usage: dscord <command> [arguments]
 
-  server                 Run the core server and PWA
-  init                   Prepare server and Synapse configuration
+  server                 Run the core server in its configured web mode
+  init [--web-mode MODE]  Prepare configuration (MODE: bundled or api-only)
   bootstrap              Register initial members on the configured Synapse
   admin <arguments>      Manage server credentials and node exports
   node <arguments>       Run a Matrix Bot adapter
@@ -29,6 +29,7 @@ const help = `Usage: dscord <command> [arguments]
   help                   Show this help
 
 DS_GROUP_DATA_DIR defaults to .dscord in the current directory.
+DS_GROUP_WEB_MODE overrides web hosting; init persists it in core-config.json.
 `;
 
 async function run() {
@@ -48,10 +49,10 @@ async function run() {
   const entry = entries.get(command);
   if (!entry) throw new Error(`Unknown command "${command}". Run dscord help.`);
   if (command === 'service' && ['up', 'down', 'restart'].includes(args[0]) && !args[1]) {
-    throw new Error('Choose a service component explicitly: all, core, finance, or hr.');
+    throw new Error('Choose a service component explicitly: all, core, or a local Bot account name.');
   }
   if (command === 'dsh' && args.length < 2) {
-    throw new Error('Use dscord dsh <start|run|stop|status|prepare> <finance|hr>.');
+    throw new Error('Use dscord dsh <start|run|stop|status|prepare> <bot-account>.');
   }
 
   const env = { ...process.env };

package/central/README.md

@@ -0,0 +1,144 @@
+# DSCord Central（中央服务器）
+
+中央服务器管四件事：账号、签发身份、服务器索引，以及每个人名下 Bot 的设置和运行它们的设备。它保存账号头像等身份资料，不存聊天消息和任务附件，不转发聊天，也不持有任何 Matrix token。聊天服务器（Core + Synapse）接入一台中央，人和 Bot 都用中央账号登录聊天服务器。整体方案见项目文档《DSCord 中央身份与聊天服务器方案》。
+
+已经完成：账号、账号规则、身份令牌、Bot 节点授权（第一期），聊天服务器只认中央账号（第二期，见下文“聊天服务器怎样接入”），服务器索引和中央管理面板（第四期，见下文“服务器索引”和“管理面板”）。
+
+## 运行
+
+```sh
+npm run central
+```
+
+数据目录默认是 `.local/central/`，可用 `DSCORD_CENTRAL_DATA_DIR` 指定；监听地址用 `DSCORD_CENTRAL_HOST`（默认 `127.0.0.1`）和 `DSCORD_CENTRAL_PORT`（默认 `18200`）。配置文件是数据目录下的 `central-config.json`，或由 `DSCORD_CENTRAL_CONFIG_PATH` 指定：
+
+```json
+{
+  "issuer": "https://id.example.org",
+  "registration": "open",
+  "listing": "review",
+  "admins": ["alice"],
+  "usernameRule": { "minLength": 3, "maxLength": 32, "reserved": ["admin", "root", "system", "dscord", "central"] },
+  "clientOrigins": ["https://client.example.org"]
+}
+```
+
+- `issuer`：中央的公开地址，必须是 HTTPS 的裸 origin（本机调试可用 `http://localhost`）。
+- `domain`：全局身份 ID 里 `@` 后面的部分，默认取 `issuer` 的主机名。
+- `registration`：`open` 允许自助注册，`closed` 关闭。
+- `listing`：新登记的聊天服务器怎么处理。`review`（默认）等管理员审核后才上架，`open` 读到页面就直接上架。
+- `admins`：中央管理员的用户名列表。管理员用自己的中央账号登录 `/admin` 管理面板。
+- `registration` 和 `listing` 只是初始值：管理员在面板里改过之后，以面板里保存的为准（存在 `central.sqlite`）。
+- `usernameRule`：账号规则，见下。
+- `clientOrigins`：允许跨域调用中央接口的网页客户端 origin。
+- `serverFetchUrls`：可选，`{ "聊天服务器 origin": "中央实际访问的地址" }`。中央所在网络访问不到某台聊天服务器的公开地址时（例如同一个 Compose 里），索引改从这里读它的公开页面。
+
+配置文件不存在时，可以用环境变量 `DSCORD_CENTRAL_ISSUER`、`DSCORD_CENTRAL_REGISTRATION`、`DSCORD_CENTRAL_LISTING`、`DSCORD_CENTRAL_ADMINS`（逗号分隔的用户名）、`DSCORD_CENTRAL_CLIENT_ORIGINS`（逗号分隔）、`DSCORD_CENTRAL_SERVER_FETCH_URLS`（逗号分隔的 `origin=地址`）在第一次启动时生成它；之后以文件为准，改环境变量不再生效。Compose 自带的 `central` 服务就是这样启动的。
+
+数据目录里的 `signing-key.json` 是签名私钥（权限 `0600`），`central.sqlite` 是账号库。备份时两者都要保留；换掉私钥后，聊天服务器要重新读取公钥。
+
+## 自定义头像
+
+用户可修改自己和名下 Bot 的头像，跨服务器同步，Bot 离线时也可设置。默认复用中央数据卷；入口、配置、备份和接口见[自定义头像](avatars.md)。
+
+## 账号格式
+
+账号规则由中央在配置里指定，并公开在 `GET /.well-known/dscord/central` 的 `usernameRule` 里。聊天服务器和客户端只读这份规则。
+
+- 全局身份 ID 是 `用户名@domain`，例如 `alice@id.example.org`；在某台聊天服务器上的地址是 `@用户名:聊天服务器域名`。
+- 用户名会直接当 Matrix 本地名用，所以中央的规则总是和 Matrix 本地名字符集（小写 a-z、0-9 和 `. _ = - /`）取交集：`pattern` 写得再宽，也收不进 Matrix 不接受的字符。`maxLength` 最多 64。
+- 默认规则：3 到 32 个字符，小写字母开头，只含 a-z、0-9 和 `. _ -`。输入不分大小写，一律存小写。
+- 用户名注册后不能改；账号注销后用户名也不回收。显示名可以改。
+- 人和 Bot 共用同一个命名空间，是否 Bot 看账号类型。
+
+## 接口
+
+除注明外，接口用 `Authorization: Bearer <中央会话令牌>`。错误返回 `{ error, code }`。
+
+| 接口 | 谁用 | 作用 |
+| --- | --- | --- |
+| `GET /.well-known/dscord/central` | 任何人 | 中央地址、账号规则、公钥地址、令牌有效期 |
+| `GET /.well-known/jwks.json` | 聊天服务器 | 验证身份令牌的公钥 |
+| `POST /api/register` | 人 | `{username, password, displayName?}` 注册并登录（`registration: open` 时） |
+| `POST /api/login` / `POST /api/logout` | 人 | 密码登录 / 退出当前会话 |
+| `GET /api/me` / `DELETE /api/me` | 人、Bot 节点 / 人 | 查看自己 / 注销（名下还有 Bot 时要先注销 Bot） |
+| `POST /api/identity-tokens` | 人、Bot 节点 | `{audience, allowNew?}` 为某台聊天服务器（HTTPS origin）签发 5 分钟有效的身份令牌；第一次去某台服务器时要带 `allowNew: true`，否则返回 `GRANT_REQUIRED` |
+| `GET /api/grants` / `DELETE /api/grants/:audience` | 人、Bot 节点 | 查看 / 撤销自己授权过的聊天服务器 |
+| `POST /api/connect-codes` | 人 | 生成 DSH 连接用的一次性代码（10 分钟有效）。聊天服务器网页把它和服务器地址一起编码成连接密钥 |
+| `POST /api/connect-codes/redeem` | DSH 插件（不用令牌） | `{code, label?}` 用代码换取这个人的中央会话；只能换一次，过期返回 `CONNECT_CODE_EXPIRED`，未知或已用返回 `CONNECT_CODE_UNKNOWN` |
+| `POST /api/bots` / `GET /api/bots` / `DELETE /api/bots/:id` | 人 | 创建 / 列出 / 注销自己名下的 Bot。创建时给 `{displayName, username?, role?, model?, effort?, deviceId?, servers?}`，不给 `username` 时由名字生成；返回的每个 Bot 带 `settings`（`role`、`model`、`effort`、`deviceId`、`servers`、`revision`）和 `runtime`（运行它的设备是否在线，以及设备最近报告的 `revision`、`model`、`error`、各服务器的连接状态；还没有设备时是 `null`） |
+| `PATCH /api/bots/:id` | 人 | 修改名字和上面的设置，只改给出的字段，`revision` 加一。`model` 为空表示跟随设备默认，`servers` 是 Bot 要加入的聊天服务器（HTTPS origin，最多 32 个），`deviceId` 必须是自己的设备 |
+| `GET /api/devices` | 人 | 自己连接过的 DSH：`id`、`label`、是否在线（30 秒内报告过）、它能用的模型目录和插件版本 |
+| `POST /api/devices/:id/sync` | DSH 插件（用连接密钥换来的会话） | `{label, report}` 报告这台设备的模型目录、插件版本和各 Bot 的状态，返回分给它的 Bot 和设置。还没有设备的 Bot 归第一台报告的设备；同一台 DSH 换了人登录时，前一个人的 Bot 回到等待 |
+| `DELETE /api/devices/:id` | 人、DSH 插件 | 移除设备：它名下的 Bot 等下一台设备接手，设备报告用的会话同时结束 |
+| `GET /api/bots/:id/grants`、`DELETE /api/bots/:id/grants/:audience` | Bot 的所属人 | 查看 / 撤销 Bot 的服务器授权 |
+| `GET /api/bots/:id/nodes`、`DELETE /api/bots/:id/nodes/:nodeId` | Bot 的所属人 | 查看 / 撤销 Bot 的节点 |
+| `POST /api/device` | Bot 节点 | `{label?}` 开始设备码授权，返回 `deviceCode`、`userCode`（10 分钟有效） |
+| `POST /api/device/approve` | Bot 的所属人 | `{userCode, botId}` 把这个节点授权给自己的 Bot |
+| `POST /api/device/token` | Bot 节点 | `{deviceCode}` 换取 Bot 的节点会话；所属人批准前返回 `AUTHORIZATION_PENDING`，只能换一次 |
+| `GET /api/servers?q=&tag=&limit=` | 任何人（不用令牌，允许任意网页跨域） | 搜索服务器索引；`q` 是 8 位数字时按服务器号精确查找 |
+| `POST /api/servers` | 任何人（不用令牌） | `{origin}` 把一台聊天服务器报给索引。中央去读它的公开页面，返回 `{server: {origin, number, status, note, discovery}}`；再报一次会重新读取页面、返回当前状态 |
+| `GET /api/admin/overview` | 中央管理员 | 待审、已上架等数量，账号数量，当前设置 |
+| `POST /api/admin/settings` | 中央管理员 | `{registration?, listing?}` 修改注册和登记审核设置 |
+| `GET /api/admin/servers?status=` | 中央管理员 | 索引里的全部服务器（含待审、驳回、封禁），可按状态筛选 |
+| `POST /api/admin/servers/:origin/decision` | 中央管理员 | `{status: listed\|rejected\|banned, note?}` 上架、驳回或封禁，留言会随下次登记带回给该服务器 |
+| `POST /api/admin/servers/:origin/refresh` / `DELETE /api/admin/servers/:origin` | 中央管理员 | 立即重新读取 / 从索引里移除（收回服务器号） |
+| `GET /api/admin/accounts?q=&kind=&status=` | 中央管理员 | 按用户名或显示名查账号 |
+| `POST /api/admin/accounts/:id/disable` / `enable` | 中央管理员 | 停用（立即结束它的所有会话，不能再登录或拿身份令牌）/ 恢复账号；不能停用自己 |
+
+## 服务器索引
+
+索引只记每台聊天服务器自己公开的介绍，不存它的成员、房间和消息。
+
+- 登记：聊天服务器把自己的 origin 报给中央（管理后台“服务器目录”里点一次“登记到中央”），不需要任何中央账号。中央从这个 origin 读 `GET /.well-known/dscord/server`，页面写明信任的中央就是自己、`origin` 也对得上，就收下这台服务器。
+- 为什么不需要账号：页面是从这个 origin 读到的，又点名信任这台中央，本身就说明控制这个域名的人愿意被登记。聊天服务器在中央不持有任何凭据，也没有“所属人”；要改介绍就改自己的策略，中央下次读取时更新；不想被找到就把发现方式改成 `hidden`。
+- 审核：新服务器默认是“待审核”，中央管理员在管理面板里上架、驳回或封禁，可以附一句留言。`listing: open` 时读到页面就直接上架。被驳回的服务器再登记一次会回到待审核；被封禁的再登记会被拒绝（`SERVER_BANNED`），直到管理员解除封禁。只有已上架的服务器能被搜到。
+- 服务器号：第一次登记时，中央随机分配一个 8 位数字作为服务器号（像 QQ 群号），之后一直不变；管理员把它从索引里移除后再登记会拿到新号码。
+- 发现方式由聊天服务器自己决定（页面里的 `discovery`）：`public` 能被关键词搜到，也能凭号码找到；`number` 关键词搜不到，只能输入完整号码找到；`hidden` 搜不到也查不到号码，中央管理员仍能在面板里看到。
+- 加入方式也由聊天服务器决定（`join`）：`open` 任何中央账号都能直接加入，`invite` 只接受凭邀请码加入。中央只把它显示在搜索结果里，真正的检查在聊天服务器上。
+- 刷新：中央每小时重新读一遍待审和已上架的服务器（读取不跟随跳转，页面上限 64 KB）。页面读不到或改信任别的中央时，保留上次的介绍并记下错误；连续三天没读到成功的页面，就从搜索结果里消失，读到后自动恢复。发现方式的改动在下次读取后生效。
+- 搜索：只列已上架、三天内读到过的服务器。`q` 是 8 位数字时先按号码精确查找（`public` 和 `number` 的服务器）；否则只搜 `public` 的服务器，`q` 里的每个词都要出现在名称、简介或标签里（不分大小写），按人数排序；`tag` 按标签精确筛选；`limit` 默认 20，最多 50。结果含服务器号和加入方式。
+
+公开页面的格式（`schemaVersion: 1`）：
+
+```json
+{
+  "schemaVersion": 1,
+  "central": "https://id.example.org",
+  "origin": "https://chat.example.org",
+  "discovery": "public",
+  "name": "机器人社",
+  "description": "机械臂和小车",
+  "tags": ["robots"],
+  "join": "invite",
+  "members": { "people": 12, "bots": 3 }
+}
+```
+
+`origin` 必须和登记的 origin 一致；`name` 最多 80 字，`description` 最多 500 字，`tags` 最多 10 个、每个最多 32 字。
+
+## 管理面板
+
+中央自己在 `/admin` 提供管理面板（构建产物在 `dist/central-admin`，可用 `DSCORD_CENTRAL_ADMIN_WEB_DIR` 指定别的目录）。用配置里 `admins` 列出的中央账号登录，其他账号会被拒绝。面板有四页：
+
+- 概览：待审核和已上架的服务器数、人和 Bot 的账号数、当前设置。
+- 服务器：按状态（待审核、已上架、已驳回、已封禁）查看所有登记过的服务器，看它的介绍、发现方式、加入方式、人数和最近一次读取结果；可以上架、驳回、封禁、解除封禁、立即重新读取或移除，并给该服务器的管理员留言。
+- 账号：按用户名或显示名、类型、状态查账号，停用或恢复。
+- 设置：新服务器要不要先审核，账号注册是否开放。
+
+管理员名单只能在配置文件里改，面板里不能增删。
+
+## 身份令牌
+
+身份令牌是 Ed25519 签名的 JWT（`alg: EdDSA`），声明包括 `iss`、`sub`（账号编号）、`aud`（聊天服务器 origin）、`iat`、`exp`、`jti`、`username`、`gid`（全局身份 ID）、`kind`（`human` 或 `bot`）、`name`（显示名），Bot 另有 `owner`（所属人的全局身份 ID）。聊天服务器用 `central/tokens.mjs` 的 `verifyIdentityToken` 按中央公钥、`issuer` 和自己的 origin 校验。一张令牌只对写明的那台聊天服务器有效。
+
+撤销授权后，中央不再为那台服务器签发令牌；聊天服务器的本地会话是短期的，续期时要重新拿令牌，因此撤销会在一个会话周期内生效。
+
+## 聊天服务器怎样接入
+
+聊天服务器（Core）在 `core-config.json` 的 `identity.central` 写中央地址（初始化时取 `DS_GROUP_CENTRAL_URL`），并把自己的 `publicUrl` 当作令牌的 `aud`。Core 从中央读 `/.well-known/dscord/central` 和公钥，遇到新的签名密钥时重新读一次。容器网络里 Core 访问中央的地址和中央的公开地址不同时，用 `DS_GROUP_CENTRAL_FETCH_URL` 指定前者；令牌里的 `iss` 仍是公开地址。
+
+- 登录：客户端在中央拿到身份令牌，交给 Core 的 `POST /api/session {identityToken}`，换回这台服务器的会话。Core 没有注册、密码登录和演示登录接口。
+- 账号对应：中央用户名就是 Matrix 本地名。账号第一次登录时 Core 在 Synapse 建同名用户；已有的同名初始化成员由这个中央账号认领，之后只认它。
+- Bot：Bot 的身份令牌带 `owner`，Core 据此把 Bot 记在所属人名下。Bot 节点用自己的会话调 `POST /api/bots/:id/connect` 拿节点配置，并报告它在哪个 DSH 宿主上（`native`）。
+- 发现：`GET /.well-known/dscord/client` 的 `central.issuer` 告诉客户端去哪台中央登录，`auth.audience` 是申请身份令牌时要写的 `audience`。没有配置中央的 Core 返回 `central: null`，登录接口返回 503。