From 20e4e4ed73318faab65dabeacabeb912b481a5f2 Mon Sep 17 00:00:00 2001
From: "jj.wang" <jj.wang@alphabets.cn>
Date: Wed, 21 Oct 2026 08:25:14 +0000
Subject: [PATCH] Docs: LXC deployment guide, remote POSIX transport in the
 executor contract

deploy-lxc.md: Debian 12 packages, vault client + identity, Warpgate host key
(pinned by the identity), helper scripts and protocol file, all-remote config,
cron under exec --secret-env, logs/heartbeat, adding a terminal.
design.md 9: P1-6 done for Linux/macOS; Windows still on the helper scripts (TODO unify).
---
 README.md                 |  2 +-
 docs/deploy-lxc.md        | 97 +++++++++++++++++++++++++++++++++++++++
 docs/design.md            |  7 +--
 docs/executor-contract.md | 17 +++----
 4 files changed, 111 insertions(+), 12 deletions(-)
 create mode 100644 docs/deploy-lxc.md

diff --git a/README.md b/README.md
index b991ba1..a80aefb 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,6 @@ Plane 看板驱动的通用 agent 调度服务：在 Plane 建工作项并指派
 - 凭据全部经 Agent Vault 注入内存，仓库和配置里只有键名。
 
 ## 使用
-- 契约与扩展：`docs/executor-contract.md`；安装、cron、日志、故障：`docs/runbook.md`
+- 契约与扩展：`docs/executor-contract.md`；安装、cron、日志、故障：`docs/runbook.md`；迁到无 agent CLI 的 LXC：`docs/deploy-lxc.md`
 - 入口：`cli/agentd tick|new|show|comment|state|assign|smoke|check-config`（在 `agent-access.py exec --secret-env …` 下运行）
 - 测试：`python3 -m unittest`（离线，不访问 Plane/win10）
diff --git a/docs/deploy-lxc.md b/docs/deploy-lxc.md
new file mode 100644
index 0000000..e140e03
--- /dev/null
+++ b/docs/deploy-lxc.md
@@ -0,0 +1,97 @@
+# 在精简 LXC 上部署 agentd（design §9 阶段 3）
+
+目标：调度器跑在一台**不装任何 agent CLI** 的 Debian 12 LXC（`agentd-01`）上；所有终端（win10、oregon、mac…）都经 Warpgate SSH 远程启动（`transport: warpgate-ssh`）。LXC 只做调度、回帖、通知。
+
+## 1. 系统包
+```bash
+apt-get update
+apt-get install -y python3 python3-yaml openssh-client git cron ca-certificates curl
+# win10 的 helper 脚本另需（Debian 12 默认已有）：bash coreutils(base64/sha256sum) gzip libc-bin(iconv)
+adduser --disabled-password --gecos '' agentd    # 普通用户运行 agentd，不用 root
+```
+Python ≥ 3.10（Debian 12 是 3.11）。`jsonschema` 可选，没有就用内置子集校验器。
+
+## 2. 网络
+| 去向 | 用途 |
+|---|---|
+| `nas.tail9531b.ts.net:8443`（tailnet） | Agent Vault 身份配置 `identity/agent.json`（含 vault token 与 Warpgate 主机公钥）→ LXC 必须加入 tailnet（`tailscale up`，LXC 需 `/dev/net/tun`） |
+| Vault（身份配置里的地址） | 取 Plane token、Warpgate 密码 |
+| Warpgate SSH `115.28.210.101:2222` | 所有终端的中继 |
+| `https://plane.kappiee.com` | Plane API |
+
+## 3. Agent Vault 客户端与身份
+```bash
+sudo -u agentd mkdir -p ~agentd/.local/share/server-access-client
+# 从 oregon 复制（权限 700，只给 agentd 用户）：
+scp oregon:~/.local/share/server-access-client/{agent-access.py,agent-access-askpass.py} \
+    agentd-01:~agentd/.local/share/server-access-client/
+chmod 700 ~agentd/.local/share/server-access-client/*
+cd ~agentd/.local/share/server-access-client && sudo -u agentd python3 -I agent-access.py \
+  --config https://nas.tail9531b.ts.net:8443/identity/agent.json list    # authenticated: true，能看到 win10 / oregon 等 target
+```
+- 身份是 tailnet 上的 URL（`--config https://…/identity/agent.json`），不落盘；也可以换成本地私有 JSON 文件（`chmod 600`），把 `vault.config` 指过去。
+- **Warpgate known_hosts 不用配**：客户端每次用身份配置里的 `warpgate.host_key` 生成临时 known_hosts（`StrictHostKeyChecking=yes`），不读 `~/.ssh/known_hosts`。只要求有 `ssh` 可执行文件。
+- `askpass` 必须与 `agent-access.py` 同目录且可执行。
+- Warpgate 侧：该身份（`agent` 用户）要有每个终端 target 的权限（现有：`win10`、`oregon`）。
+
+## 4. 代码与配置
+```bash
+sudo -u agentd git clone https://git.kappiee.com/kappiee/plane-agentd.git ~agentd/plane-agentd
+# win10 仍用 helper 脚本（见 design §9 TODO），复制这两个：
+sudo -u agentd mkdir -p ~agentd/helpers
+scp oregon:/home/ubuntu/Documents/wjj/project/gwent-design/tools/{win10-ps.sh,win10-put.sh} agentd-01:~agentd/helpers/
+# 看板协作协议（拼进每轮 prompt，由 agentd 在本机读取）：
+scp oregon:/home/ubuntu/Documents/wjj/project/gwent/design/board-protocol.md agentd-01:~agentd/board-protocol.md
+cp ~agentd/plane-agentd/config/agentd.yaml ~agentd/plane-agentd/config/agentd.local.yaml   # git-ignored，优先于 agentd.yaml
+```
+`config/agentd.local.yaml` 里改：
+- `vault.client: ~/.local/share/server-access-client/agent-access.py`（`~` 在本机展开）
+- `agentd.state_dir: ~/state`（JSON 状态、日志、心跳）；`agentd.helpers_dir: ~/helpers`
+- `projects.GWENT.protocol_file: ~/board-protocol.md`（**它不在终端上读，是 LXC 本机路径**；协议更新时重新复制）
+- 所有终端都是 `transport: warpgate-ssh`：
+  - win10：`target: win10, os: windows, launch: schtasks`（不变）
+  - oregon：`target: oregon, os: linux, launch: nohup, repo: /home/ubuntu/Documents/wjj/project/gwent, run_root: /home/ubuntu/.gwent-board/agentd-runs, bins: {claude: /home/ubuntu/.local/bin/claude}`
+  - 远程 POSIX 终端的 `repo`、`run_root` 必须是绝对路径（在远程展开，`~` 不行）；`bins` 写远程的绝对路径（SSH 非登录 shell 只有系统 PATH）。
+```bash
+cd ~agentd/plane-agentd && python3 -m unittest && python3 cli/agentd check-config
+```
+
+## 5. cron
+`cron/agentd-tick.sh` 里写死了 oregon 的路径；在 LXC 上用同样的形状（单行 crontab 或复制脚本改路径）：
+```
+*/2 * * * * flock -n $HOME/state/cron.lock timeout 900 python3 -I $HOME/.local/share/server-access-client/agent-access.py --config https://nas.tail9531b.ts.net:8443/identity/agent.json exec --secret-env PLANE_OREGON_API_TOKEN=PLANE_OREGON_API_TOKEN --secret-env PLANE_WINDOW10_API_TOKEN=PLANE_WINDOW10_API_TOKEN --timeout 850 -- python3 $HOME/plane-agentd/cli/agentd tick --once >> $HOME/state/agentd-cron.log 2>&1
+```
+- token 只经 `exec --secret-env` 进 agentd 进程内存；agentd 起的中继子进程环境里去掉了所有 `token_key`（`Config.scrubbed_env()`），远程执行器在终端上由 sshd 起，本来就拿不到 LXC 的环境。
+- `--secret-env` 的完整列表：`cli/agentd check-config` 最后一行。
+- **切换时先停 oregon 上的 cron**（`crontab -e` 注释掉 `agentd-tick.sh`），再在 LXC 上启用；两个调度器同时跑会重复派单。状态文件 `~/.gwent-board/agentd/agentd-state.json` 从 oregon 复制到 LXC 的 `state_dir`，在途运行（handle 里是终端上的绝对路径）照常被新调度器 poll/collect。
+
+## 6. 日志与心跳
+| 路径（LXC） | 内容 |
+|---|---|
+| `~/state/agentd.log` | 每 tick 的动作、错误 |
+| `~/state/heartbeat.json` | `at` 超过 10 分钟不更新 = 调度器没在跑 |
+| `~/state/agentd-state.json` | 全部工作项状态 |
+| `~/state/agentd-cron.log` | cron 输出（空闲时为空；`skip: another tick holds …` 无害） |
+| 终端上 `<run_root>/<run_id>/` | 每轮的 `prompt.md run.sh/run.ps1 pid.txt launch.pid exit.txt stderr.txt` + 执行器输出 |
+
+## 7. 加一个终端（例：mac）
+1. Warpgate 加 SSH target（如 `mac`），给 `agent` 身份授权；`agent-access.py … run --target mac --timeout 30 -- bash -c 'echo ok; uname'` 能通。
+2. 在终端上装好 agent CLI 并登录（Claude Code / Codex），clone 工作仓库；记下二进制绝对路径。
+3. 配置：
+   ```yaml
+   mac:
+     transport: warpgate-ssh
+     target: mac
+     os: darwin            # linux | darwin；darwin 用 perl POSIX::setsid 脱离会话（无 setsid 命令）
+     launch: nohup
+     repo: /Users/me/src/gwent
+     run_root: /Users/me/.agentd-runs
+     bins: {claude: /Users/me/.local/bin/claude}
+     plane_user: mac
+     token_key: PLANE_MAC_API_TOKEN
+     concurrency: 1
+     executors: [claude-code]
+   ```
+   远程 shell 是目标账户的登录 shell（bash/zsh 均可，agentd 发的是 `bash -c '<script>'`）；终端需有 `bash base64 nohup pgrep pkill`（Linux 另需 `setsid`，macOS 需 `perl`）。
+4. Plane：建用户 `mac`，token 存 Vault 键 `PLANE_MAC_API_TOKEN`；项目 `routing.by_assignee` 加 `mac: mac`，`default_executor` 加 `mac: claude-code`；cron 加 `--secret-env PLANE_MAC_API_TOKEN=PLANE_MAC_API_TOKEN`。
+5. `cli/agentd check-config`，然后 `cli/agentd smoke GWENT mac`。
diff --git a/docs/design.md b/docs/design.md
index 9391008..1da1276 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -50,7 +50,7 @@ plane: {base_url: https://plane.kappiee.com, workspace: kappiee}
 vault: {client: ~/.local/share/server-access-client/agent-access.py, config: https://nas.tail9531b.ts.net:8443/identity/agent.json}
 terminals:
   win10:  {transport: warpgate-ssh, target: win10, os: windows, launch: schtasks, repo: 'C:\Users\Administrator\Documents\GwentAssistantProject\gwent', plane_user: window10, token_key: PLANE_WINDOW10_API_TOKEN, concurrency: 1, capabilities: [android, game], executors: [codex, powershell]}
-  oregon: {transport: local, os: linux, launch: subprocess, repo: /home/ubuntu/Documents/wjj/project/gwent, plane_user: oregon, token_key: PLANE_OREGON_API_TOKEN, concurrency: 2, executors: [claude-code, codex, shell]}
+  oregon: {transport: warpgate-ssh, target: oregon, os: linux, launch: nohup, repo: /home/ubuntu/Documents/wjj/project/gwent, run_root: /home/ubuntu/.gwent-board/agentd-runs, plane_user: oregon, token_key: PLANE_OREGON_API_TOKEN, concurrency: 1, executors: [claude-code]}
 executors:
   codex:       {run: 'codex exec --json -C {repo} -s workspace-write -m {model} -c model_reasoning_effort="{effort}" {tier} -o {out} -', resume: 'codex exec resume {thread} --json -m {model} -c model_reasoning_effort="{effort}" {tier} -o {out} -', thread_from: events.jsonl:thread.started.thread_id, last_message: '{out}', models: [gpt-6-astra, gpt-6.1-sol], default_effort: medium}
   claude-code: {run: 'claude -p --model {model} --output-format json --permission-mode {perm} -', resume: 'claude -p --resume {thread} --model {model} --output-format json -', thread_from: json:session_id, models: [opus, sonnet, haiku]}
@@ -74,7 +74,7 @@ projects:
 ```
 agentd/            调度核心、plane 客户端、vault 注入、状态存储（json/sqlite）、心跳
 agentd/executors/  codex.py claude_code.py shell.py（适配器契约见 docs/executor-contract.md）
-agentd/transports/ local.py warpgate_ssh.py（含 Windows schtasks 启动）
+agentd/transports/ local.py warpgate_ssh.py（远程 Linux/macOS：bash -c 经中继；Windows：helper 脚本 + schtasks）
 agentd/web/        配置页面（阶段 2）：读写 YAML + schema 校验 + 连通/冒烟测试 + 最近运行
 cli/               agentd new|show|comment|state|assign|smoke
 config/            agentd.yaml（示例 + 实际）、schema.json
@@ -95,4 +95,5 @@ docs/              design.md executor-contract.md runbook.md
 - Plane VM（plane-01）只跑 Plane：它是设备化节点（固定版本、每日备份停写路径），不放 agentd。
 - 阶段 1–2：agentd 跑在 oregon（已有 Vault 客户端、Warpgate 中继脚本、Claude Code、现有 worker 状态），cron 拉起；配置页面同进程，只监听 tailnet 地址。
 - 阶段 3 起：迁到 PVE 上的精简 LXC `agentd-01`（1 vCPU / 1–2 GB，tailnet + 内网 10.77.10.0/24，与 Plane/Temporal 同网段，webhook 走内网）。**LXC 上不装任何 agent CLI**，只有 Python 3.10+、PyYAML、Agent Vault 客户端、ssh 客户端；所有终端（win10、oregon、mac…）一律远程启动（`transport: warpgate-ssh`），LXC 只负责调度、回帖、通知。对外访问经 Warpgate HTTP target，复用既有登录。
-- 远程启动的通用实现（P1-6）：Windows 用计划任务（已实现）；Linux/macOS 经 Warpgate SSH 上传 `run.sh`，`setsid nohup` 脱离会话，轮询 `exit` 文件取回 `last.md`/线程 ID；中继目标名由终端配置给出，不写死。
+- 远程启动的通用实现（P1-6，已实现）：Linux/macOS 经 Warpgate SSH（`agent-access.py run --target <终端 target> -- bash -c …`）上传 `prompt.md`/`run.sh` 并一次调用内启动，`setsid nohup` 脱离会话（macOS 用 perl `POSIX::setsid`），轮询 `exit.txt`，从终端上的输出文件取回最后消息/线程 ID，kill 按进程组 + 会话；中继目标名由终端配置给出。oregon 已切到这条路径（调度器暂仍在 oregon，启动经 Warpgate 回到本机）。部署步骤：`docs/deploy-lxc.md`。
+- Windows 仍用 helper 脚本 `win10-ps.sh` / `win10-put.sh`（写死 `--target win10`）+ 计划任务。**TODO（统一）**：Windows 也改走 `relay()`（argv = `powershell.exe -EncodedCommand …`，文件同样 base64 分块），删掉对 helper 脚本与 `helpers_dir` 的依赖，LXC 上就不必再复制这两个脚本。
diff --git a/docs/executor-contract.md b/docs/executor-contract.md
index dd712a0..f84f5d2 100644
--- a/docs/executor-contract.md
+++ b/docs/executor-contract.md
@@ -24,11 +24,11 @@ agentd 不常驻：一轮运行比起它的那次 tick 活得久，所以执行
 - `kill(handle)` 既用于超时，也用于取消（工作项在运行中被移出 In Progress）；必须能在运行未结束时调用。取消后 core 会尝试 `collect(handle)` 取线程 ID，所以 `collect` 在未结束的运行上也不能抛出致命错误（抛异常会被忽略）。
 
 ## RunnerExecutor（现有三个适配器的共同形态）
-1. 在终端上建运行目录 `<run_root>/<run_id>`（清空旧文件），写 `prompt.md`。
-2. 用配置里的命令模板生成命令：`run`（新线程）或 `resume`（续线程）。占位符：`{repo} {model} {effort} {tier} {out} {thread} {perm} {script} {run_dir}`；未知占位符原样保留。`{tier}` 展开为 `tier_arg`（如 `-c 'service_tier="fast"'`），无 tier 时为空。模板首词若在终端 `bins` 里，替换为绝对路径（Windows 前加 `&`）。参数请用单引号，bash 和 PowerShell 都认。
+1. 在终端上建运行目录 `<run_root>/<run_id>`（清空旧文件），写 `prompt.md`。transport 有 `start_run` 时（远程 POSIX），建目录、写 `prompt.md` 与 runner、启动合并成一次中继调用。
+2. 用配置里的命令模板生成命令：`run`（新线程）或 `resume`（续线程）。占位符：`{repo} {model} {effort} {tier} {out} {thread} {perm} {script} {run_dir}`；未知占位符原样保留。`{tier}` 展开为 `tier_arg`（如 `-c 'service_tier="fast"'`），无 tier 时为空。tier 来源：`tier:<x>` 标签或 `routing.by_label` 的 `tier`，否则执行器的 `tier_defaults[<model>]`；`tier:none` 表示不加档位参数。模板首词若在终端 `bins` 里，替换为绝对路径（Windows 前加 `&`）。参数请用单引号，bash 和 PowerShell 都认。
 3. transport 生成 runner 脚本（Linux `run.sh`，Windows `run.ps1`）：进入 repo，写 `pid.txt`/`started.txt`，把 `prompt.md` 从 stdin 喂给命令，stdout → `stdout_name`，stderr → `stderr.txt`，结束写 `exit.txt`（`exit=N at …`）。
-4. transport 分离启动（Linux `setsid -f bash run.sh`，Windows 一次性计划任务 `agentd-<run_id>`）。
-5. `poll` = `exit.txt` 是否存在；`collect` 由各适配器解析：
+4. transport 分离启动（本机 `setsid -f bash run.sh`；远程 Linux `setsid nohup bash run.sh &`，macOS 用 `perl POSIX::setsid`，`$!` 记入 `launch.pid`；Windows 一次性计划任务 `agentd-<run_id>`）。
+5. `poll` = `exit.txt` 是否存在；`collect` 由各适配器从终端上保存的文件解析（远程时经中继读回，不依赖调度器本机有任何 CLI）：
 
 | 适配器 | stdout | 最后消息 | 线程 ID |
 |---|---|---|---|
@@ -39,9 +39,10 @@ agentd 不常驻：一轮运行比起它的那次 tick 活得久，所以执行
 配置里的 `thread_from` / `last_message` 目前只是说明性字段，解析逻辑在适配器里。
 
 ## Transport 接口（`agentd/transports/`）
-`os`、`join`、`quote`、`default_run_root`、`mkdir(path, clean)`、`write_text`、`read_text`（不存在返回 None）、`grep_first(path, needle)`、`tail(path, n)`、`runner(run_dir, cwd, command, stdout_name)`、`launch(task, script, run_dir)`、`kill(task, run_dir)`、`forget(task)`、`process_count(name)`（None = 不可达）。
-- `local`：Linux 本机文件 + `setsid -f`；kill = 对 `pid.txt` 的进程组发 SIGTERM。
-- `warpgate-ssh`：Windows，经 `win10-ps.sh`（PowerShell `-EncodedCommand`）和 `win10-put.sh`（分块上传 + SHA-256 校验）；文件读取用 base64 标记回传；kill = `taskkill /T /F /PID <pid.txt>` + `schtasks /End /Delete`。脚本目录由 `agentd.helpers_dir`（或终端 `helpers_dir`）配置；脚本目前写死 `--target win10`。路径都放进 PowerShell 单引号字面量（`'` 双写）；`schtasks /TR` 里脚本路径用 `\"…\"` 包裹，依赖 Windows PowerShell 5.1 的旧式原生参数传递（PowerShell 7.3+ 的 Standard 模式下需改写）。runner 进不了 repo 时写 `exit=97` 结束。
+`os`、`join`、`quote`、`default_run_root`、`mkdir(path, clean)`、`write_text`、`read_text`（不存在返回 None）、`grep_first(path, needle)`、`tail(path, n)`、`runner(run_dir, cwd, command, stdout_name)`、`launch(task, script, run_dir)`、`kill(task, run_dir)`、`forget(task)`、`process_count(name)`（None = 不可达）；可选 `start_run(task, run_dir, files, script_name)`（一次完成建目录 + 写文件 + 启动）。
+- `local`：Linux 本机文件 + `setsid -f`；kill = 对 `pid.txt` 的进程组发 SIGTERM。用于调度器与执行器同机的部署和测试。
+- `warpgate-ssh` + `os: linux|darwin`（`PosixWarpgateTransport`）：每个操作是一次 `agent-access.py --config <vault.config> run --target <target> -- bash -c '<script>'`（`relay()`，目标名取终端 `target`，缺省为终端名；客户端把 argv `shlex.join` 后交给目标账户的登录 shell，stdin 为 /dev/null）。文件：base64 放进 `printf %s '<b64>' | base64 -d`，超过 60000 字符分块追加再解码，回显字节数校验；读文件/`grep_first`/`tail` 的结果以 `B64=` 标记回传。runner 与本机相同（`run.sh`），`setsid nohup` 脱离 SSH 会话（pid = pgid = sid）；kill = 对该进程组 `kill -TERM -- -<pid>` + `pkill -TERM -s <pid>`，最多等 5 s 后 KILL，`exit.txt` 已存在时不发信号（防 pid 复用）；`process_count` = `pgrep -x`。`repo`/`run_root` 必须是远程绝对路径。每次调用约 10–14 s，所以启动只用一次调用。
+- `warpgate-ssh` + `os: windows`（`WindowsWarpgateTransport`）：经 `win10-ps.sh`（PowerShell `-EncodedCommand`）和 `win10-put.sh`（分块上传 + SHA-256 校验）；文件读取用 base64 标记回传；kill = `taskkill /T /F /PID <pid.txt>` + `schtasks /End /Delete`。脚本目录由 `agentd.helpers_dir`（或终端 `helpers_dir`）配置；脚本目前写死 `--target win10`（TODO：改走同一个 `relay()`，argv 为 `powershell.exe -NoProfile -NonInteractive -EncodedCommand <b64>`，去掉 helper 脚本）。路径都放进 PowerShell 单引号字面量（`'` 双写）；`schtasks /TR` 里脚本路径用 `\"…\"` 包裹，依赖 Windows PowerShell 5.1 的旧式原生参数传递（PowerShell 7.3+ 的 Standard 模式下需改写）。runner 进不了 repo 时写 `exit=97` 结束。
 - Codex 续线程：`codex exec resume <thread>` 不接受 `-C`/`-s`，`resume` 模板里不要写；工作目录由 runner 先进入 repo 保证，沙箱沿用 Codex 对该会话/全局配置的默认值（若需强制，用 `-c 'sandbox_mode="workspace-write"'`，上线前在 win10 上验证）。
 
 ## 新增一个执行器
@@ -55,4 +56,4 @@ agentd 不常驻：一轮运行比起它的那次 tick 活得久，所以执行
 2. 项目 `routing.by_assignee` 加 `<plane_user>: <name>`，`default_executor` 加默认执行器。
 3. cron 的 `agent-access.py exec` 加 `--secret-env <token_key>=<token_key>`（`agentd check-config` 会打印完整参数）。
 4. `agentd smoke <PROJECT> <name>` 验证一轮往返。
-新的 transport 类型（如 Linux 远程机）需在 `agentd/transports/` 实现上面的接口并在 `make_transport` 登记。
+远程 Linux/macOS 机器不需要新代码：`transport: warpgate-ssh, target: <Warpgate target>, os: linux|darwin, launch: nohup`，`repo`/`run_root`/`bins` 写远程绝对路径（步骤见 `docs/deploy-lxc.md` §7）。全新的 transport 类型需在 `agentd/transports/` 实现上面的接口并在 `make_transport` 登记。