# Dominds（斟发作们）—— 斟酌开发运作的智能体们

> 以一支具备自我迭代能力的 AI DevOps 团队，实现产品的持续交付。

- English: [README.md](./README.md)

## 重要提示（CAVEATS）

- **无担保 / 风险自担**：Dominds 是一套高性能自动化框架。若配置不当、目标模糊或盲目采信输出结果，可能导致时间损耗或代码损坏。
  - 合并代码或发布版本前，务必核查所有修改；建议先在测试分支或克隆仓库中试运行验证。
- **成本 / 隐私 / 合规性**：调用大语言模型（LLM）供应商服务会产生费用，且提示词（部分场景含代码片段）可能传输至第三方。
  - 请仔细阅读服务条款，设置费用额度上限，切勿将密钥写入提示词或日志文件。
- **授权即执行**：Dominds 并非“辅助工具”，一旦获得授权，智能体将直接执行操作，你需对最终结果承担全部责任。
- **项目处于早期阶段**：目前存在功能边界不完善、破坏性更新及文档缺失等问题，欢迎提交 issue 或 PR 参与优化。

## 关于 Dominds

Dominds 是一款面向开发运作（DevOps）场景的智能体框架，它将“团队配置、记忆存储、流程规范、工具权限”整合至统一运行时工作区（rtws），使多智能体团队能够长期稳定运行、持续学习，并在明确边界内高效执行任务。

其核心定位并非一次性完成产品开发，而是聚焦“持续交付”的全周期流程，涵盖任务拆分、职责分工、决策可追溯、工具使用管控及上下文健康度维护等关键环节。

## 安装指南

### 环境要求

- **Node.js（含 npm）**：版本 24.5+ LTS
- **npm（如直接使用）**：使用当前安装的 Node.js 24 LTS 自带 npm；本仓库当前最低要求为 `11.16.0`，更高版本也允许。
- **至少一个可用的 LLM 服务提供商**：Dominds 内置提供商目录（路径：[main/llm/defaults.yaml](./main/llm/defaults.yaml)），需为其中至少一个提供商配置有效凭证（通过环境变量设置）。
- **pnpm（可选）**：仅在开发 Dominds 本体时推荐使用。优先执行一次 `npm run setup:pm` 启用并缓存仓库固定的 pnpm；若你的环境无法启用 Corepack shim，再手动安装 `pnpm@11.5.0`。

开发本仓库时，建议在 `nvm use --lts` 之后先执行一次：

```bash
npm run setup:pm
```

### 代理支持

Dominds 在 Windows、macOS、Linux 上都可以使用 Node 内建的环境变量代理能力。

默认行为：

- `DOMINDS_USE_ENV_PROXY` 默认启用。
- 启用后，Dominds 会在 CLI 启动早期调用 Node 的运行时环境代理初始化。
- Dominds 不会设置或清理 `NODE_USE_ENV_PROXY`；这个变量留给确实需要 Node 启动期行为或子进程继承语义的用户自己管理。
- 若要让 Dominds 不再自动开启环境代理支持，设置 `DOMINDS_USE_ENV_PROXY=0`。

支持的代理变量：

- `HTTP_PROXY`
- `HTTPS_PROXY`
- `NO_PROXY`
- `http_proxy`
- `https_proxy`
- `no_proxy`

实践建议：

- 若同一网络对 HTTP/HTTPS 都走同一代理，建议 `HTTP_PROXY` 和 `HTTPS_PROXY` 一起设置。小写变量名同样有效。
- `NO_PROXY` 用于排除不经过代理的主机。Node 内置支持包括精确主机名、后缀匹配（如 `.company.com`）、通配主机（如 `*.company.com`）、精确 IP、IP 范围（如 `192.168.1.1-192.168.1.100`）以及带端口的主机名。
- `NO_PROXY` 的语法在不同语言和客户端里并没有统一标准。除非目标运行时明确支持，不要把 CIDR 写法如 `192.168.0.0/16` 当成默认可用。
- 代理值应使用标准 URL 形式，例如 `http://proxy.company.com:8080`。
- 如果你的 shell 已经导出了代理变量，Dominds 也会读取它们；想要干净的测试环境时，请清掉无关的代理变量。

示例：

```bash
# Windows PowerShell
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,.corp.local,192.168.1.1-192.168.1.100"
dominds

# macOS / Linux shell
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.local,192.168.1.1-192.168.1.100"
dominds

# 关闭 Dominds 的环境代理支持
export DOMINDS_USE_ENV_PROXY=0
dominds
```

### 安装 Dominds

```bash
# 推荐全局安装
npm install -g dominds
# 或使用 pnpm 安装
# pnpm add -g dominds

# 查看帮助文档
dominds --help
```

也可以选择 **无需全局安装** 的方式运行（适合临时试用 / CI / 不想污染环境）：

```bash
# 运行最新版（会临时下载到 npm cache 并执行）
npx -y dominds@latest --help
npx -y dominds@latest

# 或固定到某个版本（更利于复现）
# npx -y dominds@1.2.3
```

说明：

- 仅写 `npx dominds` **不一定**会自动跑“最新版”：如果你本地项目已安装了 `dominds`，或 npm cache 已存在旧版本，`npx` 可能会直接复用已有版本。
- 想要“每次都按 latest 标签解析版本”，请显式写 `dominds@latest`；它仍可能复用 cache 中已下载的同版本（属于正常行为）。

### 安装 Dominds app

安装 `dominds` CLI 本体，和把一个 **Dominds app** 装进当前 rtws，是两件不同的事：

- `npm install -g dominds` / `pnpm add -g dominds`：安装 Dominds CLI。
- `npx -y dominds@latest`：无需全局安装，直接运行 Dominds CLI。
- `dominds install <app>`：把一个 Dominds app 纳入当前 rtws 的能力图。

示例：

```bash
# 安装已发布 app 到当前 rtws
dominds install @longrun-ai/web-dev --enable

# 安装本地开发中的 app 到当前 rtws
dominds install ./dominds-apps/@longrun-ai/web-dev --local --enable
```

几个关键区别：

- `npm install` / `pnpm add` 只负责下载包；它们**不会**自动把 app 登记到当前 rtws 的 `.minds/app.yaml`。
- `npx` 在这里主要是 Kernel/CLI 的包执行后端。安装 app 时，Kernel 可能会在底层执行 `npx -y <pkg> --dominds-app` 来做握手。
- `--dominds-app` 是 Kernel/CLI 与 app 包之间的底层握手参数，不是普通用户的常规操作入口。

### 开发与贡献（树内工作流 / in-tree 工作流）

若你计划为 Dominds 开源项目贡献代码，建议使用树内包装器（in-tree wrapper）运行时工作区（rtws）：

https://github.com/longrun-ai/dominds-feat-dev

1. 克隆 dominds-feat-dev 仓库
2. 在 dominds-feat-dev/dominds/ 目录下，克隆你自己的 Dominds fork 仓库
3. 在内层 dominds/ 目录中，向 longrun-ai/dominds 提交 PR

### 贡献者测试约定（脚本测试 rtws 隔离）

当你在 Dominds 仓库里运行脚本测试（如 `pnpm -C tests run rtws -- ...`）时：

- 可先用 `pnpm -C tests run` 查看可用测试脚本，再用 `pnpm -C tests run <script-name>` 运行目标用例。
- 默认是**隔离 rtws**：每次运行都会把 `tests/script-rtws` 复制到独立临时目录后执行。
- 因为默认隔离，脚本测试可安全并发运行，不再依赖共享 `script-rtws` 的串行假设。
- `--shared-rtws` 仅用于调试，会直接使用 `tests/script-rtws`，禁止并发运行多个用例。
- 需要保留失败现场时，设置 `DOMINDS_TEST_RTWS_KEEP_TMP=1`，测试 CLI 会保留临时 rtws 路径。

### 本仓库源码构建

开发 Dominds 本体时，推荐把仓库根目录下的完整构建入口当成唯一标准用法：

```bash
pnpm run clean
pnpm run build
pnpm run lint:types
```

说明：

- `pnpm run build` 才是标准的一体构建入口；它会先构建 backend，再构建 frontend。
- `pnpm run build:backend` / `pnpm run build:frontend` 只是便于聚焦排障的子步骤，不应被当成“完整重建”的推荐命令。
- 不要手工并行执行多个顶层构建命令，例如同时跑两个 `pnpm run build`，或把 `pnpm run build` 与 `pnpm run build:backend` 并行跑。它们会共享 `dist/` 产物目录，容易制造竞态与误导性结果。
- `build:backend` 内部的 `pnpm -r ... run build` 仍可能按依赖图并发构建彼此独立的 workspace package；这是 pnpm 调度器控制的正常行为，与“手工并行多个顶层 build”不是一回事。

## 快速上手（推荐：通过模板创建运行时工作区）

```bash
# 1) 基于模板创建运行时工作区
dominds create web-scaffold my-project
cd my-project

# 2) 启动 WebUI（默认自动打开浏览器；未指定端口时等价于 5666-）
dominds
```

首次启动后，通常会自动跳转至本机 WebUI 的 `/setup` 配置页面（优先使用 `http://localhost:5666/setup`，如果端口被占用则自动尝试更小端口），按以下步骤操作：

1. 选择提供商（provider）及模型（model），创建或覆盖 `.minds/team.yaml`（最小化可运行配置文件）。
2. 根据提示设置提供商所需的环境变量（配置页可将变量写入 `.env.local`，并在 Linux/macOS 上额外支持写入 `~/.zshrc` 或 `~/.bashrc` 的托管区块）。
3. 进入主界面，创建对话即可开始工作（对话、记忆、差遣牒等运行态数据均存储在当前 rtws 下）。

平台说明：

- Windows 也会注册 `codex_inspect_and_patch_tools`；其中 `readonly_shell` 通过 `cmd.exe` 执行，因此优先使用该 shell/PATH 中可用的白名单命令，例如 `rg`、`git`、`dir`、`type` 和 `where`。

### 本地 HTTPS 证书

Dominds 默认始终提供 HTTP 监听；当 `~/.dominds/certs/` 下存在匹配当前 `--host` 的有效证书时，会额外启用 HTTPS。证书按 DNS/IP 主机名匹配，不绑定端口，因此同一张证书可覆盖该主机上的所有 Dominds WebUI 端口。

证书由 Dominds 通过 npm 依赖生成，无需额外安装 `openssl` 等系统命令。

```bash
# 自动为检测到的一个或多个非 loopback LAN 主机创建 10 年有效的自签名证书
dominds cert create

# 显式指定证书 SAN，可重复 --host
dominds cert create --host 192.168.1.10 --host my-host.local

# 查看检测到的 LAN 主机是否能匹配到证书
dominds cert status
```

`localhost`、`loopback`、`127.0.0.0/8`、`169.254.0.0/16`、`::1`、`fe80::/10`、`0.0.0.0`、`::` 不会作为 HTTPS 证书主机；其中 `0.0.0.0` / `::` 仅表示绑定所有地址，匹配证书时会使用检测到的非 loopback LAN 主机。使用裸 `--port 5666` 启动时，Dominds 会认为 HTTPS 由前置代理负责，不启用内建 HTTPS；使用默认端口或 `--port 5666+/-` 时才会自动启用内建 HTTPS。

## 从零开始（空文件夹启动）

若暂无模板或团队配置，可直接从空目录启动：

```bash
mkdir my-rtws
cd my-rtws
dominds
```

完成初始化配置后，建议先与影子团队管理者 “伏羲”(`@fuxi`) 对话，由其根据你的产品需求，搭建适配的团队配置（例如生成完整的 `.minds/team.yaml` 文件，分配成员职责及工具权限）。

## 核心理念（Core Philosophy）

Dominds 面向“长期开发运作（DevOps）”场景设计，基于社会化分工理念，所有功能均围绕以下三大核心目标展开：

- 降低 **智能体心智负担**：将工作分配给不同专长的智能体成员，并且对话过程中智能体可以自主清理头脑（也会在上下文窗口吃紧、告急情况下被提醒以及强制清理头脑），控制长程任务中过时的工具调用历史噪音对上下文造成污染，优于传统上比较勉强的"上下文压缩"手段。
- 防范 **工具滥用风险**：将软件工具交给专职智能体把关使用，确保牠们不受任务上下文影响，能够专心审核使用合规性，以及负责工具的正确使用。
- 避免 **信息过时问题**：将关键决策、约定及配置，以可版本追踪的运行时工作区文件形式，体现为智能体上下文的直接内容（团队以及个人记忆，差遣牒，对话附加提醒项），而非散落在仓库中等着智能体自己去找。

### 1) 清心定界：上下文清爽、任务明确

> 将宏大目标拆解为边界清晰的细分任务，每个智能体成员仅获取完成当前任务所需的最小上下文。

- 上下文范围越小，智能体产生幻觉及误操作的概率越低
- 任务边界越清晰，结果评估与迭代优化的效率越高
- 任务契约越明确，越容易实现并行处理与流程复用

### 2) 意图导向的工具调用：安全的核心是“先判断再约束”

> 强力赋能的工具一般都伴随使用风险，安全保障必须来自基于意图的判断与约束，经常提醒智能体“要小心谨慎”，或者靠人来把关每个小细节，都是反生产力提升的。

核心原则：

- 默认赋予最小权限，仅在必要时扩展权限范围
- 针对危险工具，每次使用时由专职智能体进行确认：
  - 会产生意外副作用吗？
  - 不小心用错了？(防呆)
  - 被恶意滥用了？
  - 是否有更安全/更简单的替代手段？
  - 常规文本匹配对这些问题是力不从心的；更可靠的是由纪律严明的专职智能体做出判断，确保合规。
- 工具授权需满足可读取、可审计、可追溯（含工具集、成员工具清单、目录读写范围等）

### 3) 基于领域专有模板：多元团队，自我进化

> 基于模板快速搭建团队，将个体及团队记忆作为版本追踪的数字资产，持续迭代优化。

- 通过领域模板引导团队职责划分与工作流搭建
- 将角色设定（personas）、经验知识（knowhow）、避坑指南（pitfalls）、操作手册（playbooks）存入 `.minds/**` 目录，对于人类完全透明，方便阅读审核
- 伴随产品迭代，同步升级治理模式与团队结构

## 相关文档

- **[Terminology](docs/dominds-terminology.md)** — Dominds 专有术语
- **[Memory System](docs/memory-system.zh.md)** — 分层记忆系统
- **[CLI Usage Guide](docs/cli-usage.zh.md)** — 命令行工具及使用方法
- **[Q4H](docs/q4h.zh.md)** — 向人类提问（`askHuman`）机制与 WebUI 支持
- **[MCP Support](docs/mcp-support.zh.md)** — MCP 工具集成指南
- **[封装式差遣牒](docs/encapsulated-taskdoc.zh.md)** — `*.tsk/` 任务包与访问约束
- **[FBR](docs/fbr.zh.md)** — 扪心自问（`freshBootsReasoning`）机制设计与增强
- **[Context Health](docs/context-health.zh.md)** — 上下文健康维护
- **[Diligence Push](docs/diligence-push.zh.md)** — 鞭策机制
- **[Showing-by-Doing](docs/showing-by-doing.zh.md)** — “做给祂看”：对话创建时建立诉请机制体感
- **[Design](docs/design.zh.md)** — Dominds 架构设计与核心抽象
- **[Roadmap](docs/roadmap.zh.md)** — 发展规划与版本演进方向
- **[OEC Philosophy](docs/OEC-philosophy.zh.md)** — 全方位优化管理法

- **[Team Mgmt Toolset](docs/team_mgmt-toolset.zh.md)** — 团队管理工具集
- **[Text Editing Tools (ws_mod)](docs/txt-editing-tools.zh.md)** — 文本编辑工具集设计文档（以当前实现为准）
- **[i18n](docs/i18n.zh.md)** — 语言支持与本地化配置
- **[Dialog System](docs/dialog-system.zh.md)** — 对话系统与流式事件
- **[Dialog Persistence](docs/dialog-persistence.zh.md)** — 磁盘持久化存储结构
- **[Interruption & Resumption](docs/interruption-resumption.zh.md)** — 任务中断与恢复语义
- **[Auth](docs/auth.zh.md)** — 认证机制与访问模型（WebUI + API）
- **[Mottos](docs/mottos.zh.md)** — 警世名言

## 获取帮助

如需协助，可在 GitHub 提交 issue：[https://github.com/longrun-ai/dominds/issues](https://github.com/longrun-ai/dominds/issues)

---

**License:**[LGPL](./LICENSE) | **Repository:**[https://github.com/longrun-ai/dominds](https://github.com/longrun-ai/dominds)
