WHCandCursor
f00aad9e3e
Password Realm no longer auto-enables parliament (keeps task/worker tools); finished jobs fan out to agent notes + TUI; raise PAR_MAX/grep caps and tag truncations. Co-authored-by: Cursor <cursoragent@cursor.com>
123 lines
4.2 KiB
Markdown
123 lines
4.2 KiB
Markdown
# Parliament（议会）快速上手
|
||
|
||
密码串派生 Realm → 登录夺主席 / 加入席位 → 常驻服务密封同步共享上下文。
|
||
主席是用户入口；成员席位在本机干活并用 `parliament_note` 通报进度。
|
||
|
||
## 一次性初始化
|
||
|
||
```bash
|
||
# 交互输入密码，或事先 export CST_REALM_PASSWORD=…
|
||
cst-agent --realm-password-init
|
||
```
|
||
|
||
磁盘只存 salt + 公钥，**不存私钥**。
|
||
|
||
## 日常：登录夺主席，或加入席位
|
||
|
||
```bash
|
||
export CST_INSTANCE_ID=laptop-a # 可选；默认用本机 hostname
|
||
cst-agent --login --realm-label "thinkpad"
|
||
# 其他机器（同 salt/公钥 + 密码）：
|
||
cst-agent --join --instance phone-b --realm-label "pixel"
|
||
# TUI: /realm login（夺主席）或 /realm join（不抢主席）
|
||
```
|
||
|
||
跨网段（如 Tailscale）多播发现不可用时，在 Realm 目录放 `peers.json`：
|
||
|
||
```json
|
||
{"peers":[{"host":"100.64.0.13","port":9100,"iid":"labpc","name":"labpc"}]}
|
||
```
|
||
|
||
效果：
|
||
|
||
1. 用密码解锁 Realm；`--login` / `/realm login` 使本机成为**唯一主席**
|
||
2. `--join` / `/realm join` 只登记席位票：主席空缺时才夺椅，否则以 **member** 身份加入
|
||
3. 写入本地登录票（24h；成员票在主席易主后仍有效，除非本席被剥夺主席）
|
||
4. 拉起后台议会服务（发现 + 密封通道按 revision 同步 `parliament.context`；
|
||
Unix 下 accept 独立线程，dial 失败会指数退避，避免饿死入站）
|
||
|
||
查看状态：
|
||
|
||
```bash
|
||
cst-agent # TUI: /status 或 /realm
|
||
# /realm login|join|stop
|
||
cst-agent --service-stop
|
||
```
|
||
|
||
### 常驻服务（推荐）
|
||
|
||
登录后会 fork 后台席位进程；也可用 systemd --user 托管前台循环（崩溃自动拉起）：
|
||
|
||
```bash
|
||
# 安装脚本附带的辅助命令
|
||
cst-agent-service install-unit
|
||
# 在 ~/.config/cst-agent/parliament.env 写入：
|
||
# CST_REALM_PASSWORD=…
|
||
# CST_INSTANCE_ID=my-laptop
|
||
systemctl --user enable --now cst-agent-parliament.service
|
||
cst-agent-service status
|
||
```
|
||
|
||
或手动前台：`CST_REALM_PASSWORD=… cst-agent --service-fg`。
|
||
|
||
## 单机默认（solo）
|
||
|
||
未设置 `collaboration` 时，**即使存在密码 Realm，默认也是单机 solo**：`task` /
|
||
`worker_*` / runtime jobs 可用，不强制登录闸。密码 Realm 仅保管密钥，不再自动开议会。
|
||
|
||
要进入议会模式，任选其一：
|
||
|
||
- `CST_COLLABORATION=parliament` 或 `settings.json` 里 `"collaboration": "parliament"`
|
||
- 已有 open 状态的 parliament meta（例如刚 `--login` 过）
|
||
|
||
显式议会模式下打开 agent 才要求登录（TTY 下可当场输入密码）。强制恢复本机 worker：
|
||
`CST_COLLABORATION=legacy_workers`。
|
||
|
||
## 议员协作协议
|
||
|
||
席位通过共享 `parliament.context` 协作（不是进程内 `task`/`worker_*`）：
|
||
|
||
1. 开工前阅读 Environment 里的 Shared parliament context
|
||
2. 用本机工具完成分配切片
|
||
3. 跨席相关的进度/议程/结果用工具 **`parliament_note`** 发布（`kind=status|agenda|result|handover`）
|
||
4. 服务在写入后尽快 dial peers；回合内若 revision 变化，会注入 `[cst] Parliament shared context updated`
|
||
|
||
显式 `"collaboration": "parliament"`（或 env）时：
|
||
|
||
- **硬禁用** `task` / `worker_*` / runtime 委托工具
|
||
- 提供 `parliament_note`；提示词说明 chair / member 角色合同
|
||
|
||
## 换项目（清场）
|
||
|
||
```bash
|
||
cst-agent --new-project my-app
|
||
```
|
||
|
||
清空共享上下文、撤销主席与登录票，并停止本机服务。Realm 密钥保留。
|
||
|
||
## 传输安全
|
||
|
||
Peer 在 Realm 证书互鉴后做 **临时 X25519 密钥交换**，后续议会上下文同步走
|
||
**XChaCha20-Poly1305**（Monocypher，无需 OpenSSL）。握手前的发现/证书交换仍是明文元数据。
|
||
|
||
## Docker 冒烟
|
||
|
||
```bash
|
||
bash scripts/docker_parliament_test.sh
|
||
```
|
||
|
||
Alpine 内构建，chair↔member 握手 + 密封通道同步（`sealed=1` / `peer_sync`）。
|
||
|
||
## 相关标志
|
||
|
||
| 标志 | 作用 |
|
||
|------|------|
|
||
| `--realm-password-init` | 创建密码 Realm |
|
||
| `--login` | 登录 + 夺主席 + 启服务 |
|
||
| `--join` | 加入席位（不抢主席）+ 启服务 |
|
||
| `--service` / `--service-fg` | 仅启服务 |
|
||
| `--service-stop` | 停服务 |
|
||
| `--new-project ID` | 清场换项目 |
|
||
| `--peer-port N` | 登录/服务用的 TCP 端口（默认 9100） |
|
||
| `--instance ID` | 实例 id（也可用 `CST_INSTANCE_ID`；默认 hostname） |
|