Skip to content

Commit f78f277

Browse files
ZaneL1uZaneL1u
committed
docs: create milestone v2.0 roadmap (5 phases, 15 requirements)
Phase 24-28: 受管镜像 FUSE → CLI 骨架 → 参数透传 → 双 session 映射 → 生产验证 Made-with: Cursor
1 parent 13de679 commit f78f277

3 files changed

Lines changed: 107 additions & 120 deletions

File tree

‎.planning/REQUIREMENTS.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -61,27 +61,27 @@ Deferred to future release. Tracked but not in current roadmap.
6161

6262
| Requirement | Phase | Status |
6363
|-------------|-------|--------|
64-
| CLI-01 | TBD | Pending |
65-
| CLI-02 | TBD | Pending |
66-
| CLI-03 | TBD | Pending |
67-
| CLI-04 | TBD | Pending |
68-
| CLI-05 | TBD | Pending |
69-
| TTY-01 | TBD | Pending |
70-
| TTY-02 | TBD | Pending |
71-
| TTY-03 | TBD | Pending |
72-
| MAP-01 | TBD | Pending |
73-
| MAP-02 | TBD | Pending |
74-
| MAP-03 | TBD | Pending |
75-
| SRV-01 | TBD | Pending |
76-
| SRV-02 | TBD | Pending |
77-
| SRV-03 | TBD | Pending |
78-
| SRV-04 | TBD | Pending |
64+
| SRV-01 | Phase 24 | Pending |
65+
| SRV-02 | Phase 24 | Pending |
66+
| SRV-03 | Phase 24 | Pending |
67+
| CLI-01 | Phase 25 | Pending |
68+
| CLI-02 | Phase 25 | Pending |
69+
| CLI-04 | Phase 25 | Pending |
70+
| CLI-05 | Phase 25 | Pending |
71+
| CLI-03 | Phase 26 | Pending |
72+
| TTY-01 | Phase 26 | Pending |
73+
| TTY-02 | Phase 26 | Pending |
74+
| TTY-03 | Phase 26 | Pending |
75+
| MAP-01 | Phase 27 | Pending |
76+
| MAP-02 | Phase 27 | Pending |
77+
| MAP-03 | Phase 27 | Pending |
78+
| SRV-04 | Phase 28 | Pending |
7979

8080
**Coverage:**
8181
- v2.0 requirements: 15 total
82-
- Mapped to phases: 0
83-
- Unmapped: 15 ⚠️
82+
- Mapped to phases: 15 ✓
83+
- Unmapped: 0
8484

8585
---
8686
*Requirements defined: 2026-04-14*
87-
*Last updated: 2026-04-14 after initial definition*
87+
*Last updated: 2026-04-15 after roadmap creation*

‎.planning/ROADMAP.md‎

Lines changed: 73 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@
44

55
- ✅ **v1.0 MVP** — Phases 1-6 (shipped 2026-03-28) — [Archive](milestones/v1.0-ROADMAP.md)
66
- ✅ **v1.1 支持代理协议出网** — Phases 7-10 (shipped 2026-03-28) — [Archive](milestones/v1.1-ROADMAP.md)
7-
- 🚧 **v1.2 用户自助面板与 Bootstrap 重设计** — Phases 11-16 (partially shipped, remaining deferred)
8-
- 🚧 **v1.3 claude-shell 本地透明代理** — Phases 17-23 (in progress)
7+
- ⏸️ **v1.2 用户自助面板与 Bootstrap 重设计** — Phases 11-16 (partially shipped, remaining deferred)
8+
- ⏸️ **v1.3 claude-shell 本地透明代理** — Phases 17-23 (paused)
9+
- 🚧 **v2.0 cloud-claude 透明远程 CLI** — Phases 24-28 (in progress)
910

1011
## Phases
1112

@@ -42,7 +43,7 @@
4243
- [ ] **Phase 15: Bootstrap 重设计** — 短 URL 入口与实时状态推送
4344
- [ ] **Phase 16: 级联禁用与到期治理** — 用户/账号/主机到期联动与自动关机
4445

45-
## Phase Details
46+
## Phase Details — v1.2 (Deferred)
4647

4748
### Phase 11: 认证基础设施与数据迁移
4849
**Goal**: 用户可以使用自己的凭证登录系统，系统能区分管理员和普通用户角色，Claude 账号数据模型就绪
@@ -122,9 +123,8 @@ Plans:
122123
7. 所有级联操作都记录在事件日志中，包含操作原因（用户禁用、到期等）
123124
**Plans**: TBD
124125

125-
### 🚧 v1.3 claude-shell 本地透明代理
126-
127-
**Milestone Goal:** 交付单一 Go 二进制 `claude` 命令，透明启动 Docker 容器运行 Claude Code，容器内全流量走代理出口，设备指纹完全伪装，用户和 Claude Code 均无感知。
126+
<details>
127+
<summary>⏸️ v1.3 claude-shell 本地透明代理 (Phases 17-23) — PAUSED</summary>
128128

129129
- [ ] **Phase 17: 镜像与 Entrypoint 基线** — 容器镜像和启动编排就绪，Claude Code 通过官方安装脚本运行
130130
- [ ] **Phase 18: 网络隔离与分流** — sing-box tun + nftables 全流量代理，公网走出口，私网回连宿主机
@@ -134,92 +134,77 @@ Plans:
134134
- [ ] **Phase 22: 验证与自检** — verify 子命令一键检测出口 IP、DNS、指纹和容器标记
135135
- [ ] **Phase 23: 混淆构建与交付** — garble 混淆产出可直接替换的单一二进制
136136

137-
## Phase Details — v1.3
137+
</details>
138138

139-
### Phase 17: 镜像与 Entrypoint 基线
140-
**Goal**: 容器镜像和 entrypoint 就绪，Claude Code 通过官方安装脚本正确安装并启动
141-
**Depends on**: Nothing (v1.3 首个阶段，与 v1.2 无代码依赖)
142-
**Requirements**: INFRA-01, INFRA-02, INFRA-03
143-
**Success Criteria** (what must be TRUE):
144-
1. docker build 产出可用镜像，镜像包含 sing-box 二进制和基础开发工具
145-
2. Claude Code 通过官方 curl 安装脚本（Bun standalone）安装，容器内 `claude` 命令可执行
146-
3. entrypoint 按"网络配置 → 指纹伪造 → 反检测 → Claude Code"顺序编排，各步骤失败时输出明确错误
147-
4. DISABLE_AUTOUPDATER=1 生效，Claude Code 不会在运行时触发自动更新
148-
**Plans**: 1 plan
149-
Plans:
150-
- [ ] 17-01-PLAN.md — claude-shell Dockerfile + entrypoint 编排脚本
139+
### 🚧 v2.0 cloud-claude 透明远程 CLI
151140

152-
### Phase 18: 网络隔离与分流
153-
**Goal**: 容器内所有出站流量强制走代理出口，DNS 不泄漏，本地流量正确回连宿主机
154-
**Depends on**: Phase 17
155-
**Requirements**: NET-01, NET-02, NET-03, NET-04, NET-05
156-
**Success Criteria** (what must be TRUE):
157-
1. sing-box tun 接管容器内所有出站流量，外网请求走配置的代理出口 IP
158-
2. nftables 默认拒绝策略生效，绕过 tun 的直连外网请求被丢弃
159-
3. 外网域名的 DNS 查询通过代理通道解析，不通过宿主机或容器默认 DNS 泄漏
160-
4. 本地地址（127.0.0.1、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）可通过 host-gateway 回连宿主机
161-
5. 支持 SOCKS5、HTTP、VMess、Shadowsocks、Trojan 五种代理协议出站
162-
**Plans**: TBD
141+
**Milestone Goal:** 交付一个可替代原生 `claude` 命令的 Go 二进制文件 `cloud-claude`，用户 `alias claude=cloud-claude` 后输入 `claude` 的体验与本地完全一致——实际运行在远端配好代理出口的 Docker 容器里，本地目录通过 sshfs slave 实时映射到容器内。
142+
143+
- [ ] **Phase 24: 受管镜像 FUSE 硬化与容器参数** — 镜像预装 sshfs/fuse3，Worker 附加 FUSE 设备权限，SSH Proxy 零改造验证
144+
- [ ] **Phase 25: cloud-claude CLI 骨架与连接** — Go 二进制 cloud-claude 的配置、认证和远端容器连接闭环
145+
- [ ] **Phase 26: 参数透传与终端体验** — claude 参数原样透传，TTY/信号/退出码与本地一致
146+
- [ ] **Phase 27: 双 session 目录映射** — sshfs slave + SFTP 实现当前目录到容器 /workspace 的实时双向映射
147+
- [ ] **Phase 28: 生产环境 FUSE 兼容性验证** — 在目标 Linux 环境验证 FUSE + AppArmor/seccomp 完整兼容性
148+
149+
## Phase Details — v2.0
163150

164-
### Phase 19: CLI 骨架与 Docker 编排
165-
**Goal**: 用户可以在终端执行 `claude` 命令，由 Go 二进制完成配置加载、Docker 检测和容器启动的基础闭环
166-
**Depends on**: Phase 18
167-
**Requirements**: CLI-01, CLI-03, CLI-05, CLI-06, BUILD-02
151+
### Phase 24: 受管镜像 FUSE 硬化与容器参数
152+
**Goal**: 容器侧 FUSE/sshfs 前置条件和运行参数就绪，SSH Proxy 零改造验证通过
153+
**Depends on**: Nothing (v2.0 首个阶段，基于 v1.1 受管镜像)
154+
**Requirements**: SRV-01, SRV-02, SRV-03
168155
**Success Criteria** (what must be TRUE):
169-
1. `claude` 命令无子命令时透传所有参数给容器内 Claude Code，基本输入输出可用
170-
2. `claude init` 在 ~/.claude-shell/ 生成包含代理、指纹、网络选项的 config.yaml 配置模板
171-
3. Docker 不可用时给出明确中文错误提示；镜像不存在时自动拉取并显示进度
172-
4. claude-shell/ 子目录拥有独立 go.mod，与 cloud-cli-proxy 主项目零依赖
156+
1. 受管镜像 docker build 产出的镜像包含 sshfs 和 fuse3，/etc/fuse.conf 中 user_allow_other 已启用
157+
2. Worker 创建容器时附加 --device /dev/fuse 和 --cap-add SYS_ADMIN，容器内非 root 用户可成功执行 sshfs 挂载
158+
3. SSH Proxy 现有多 session channel 和 exec 转发能力无需代码改动即可支持 cloud-claude 的连接模式
173159
**Plans**: TBD
174160

175-
### Phase 20: TTY 透传与交互体验
176-
**Goal**: 容器内 Claude Code 的终端交互与直接运行原生 `claude` 无差异——尺寸、信号、退出码完全透传
177-
**Depends on**: Phase 19
178-
**Requirements**: CLI-02
161+
### Phase 25: cloud-claude CLI 骨架与连接
162+
**Goal**: 用户可以运行 cloud-claude 命令完成配置、认证和远端容器连接
163+
**Depends on**: Phase 24
164+
**Requirements**: CLI-01, CLI-02, CLI-04, CLI-05
179165
**Success Criteria** (what must be TRUE):
180-
1. docker run 以交互模式启动，bind mount 当前目录到 /workspace 作为工作目录
181-
2. 终端窗口 resize 时 SIGWINCH 正确传递到容器内进程，Claude Code 界面跟随调整
182-
3. Ctrl+C / Ctrl+\ 等信号正确转发到容器，容器退出码透传给宿主机 CLI 进程
183-
4. 容器退出时自动清理（--rm），不留孤儿容器或残留网络资源
166+
1. 用户运行 `cloud-claude`（无参数）后，CLI 自动连接网关、认证、等待容器就绪，并进入远端 Claude Code 会话
167+
2. 用户运行 `cloud-claude init` 后，网关地址和凭证持久化到 `~/.cloud-claude/config.yaml`，后续运行自动读取
168+
3. 网关不可达、认证失败、容器未就绪时，CLI 输出清晰的中文错误提示并返回合适的退出码
169+
4. 用户可以在 config.yaml 中配置自有网关地址，CLI 连接到该地址而非默认地址
184170
**Plans**: TBD
185171

186-
### Phase 21: 指纹伪造与反检测
187-
**Goal**: 容器的设备指纹完全伪装，常规容器检测手段无法识别出 Docker 环境
188-
**Depends on**: Phase 20
189-
**Requirements**: SPOOF-01, SPOOF-02, SPOOF-03, SPOOF-04
172+
### Phase 26: 参数透传与终端体验
173+
**Goal**: cloud-claude 的参数透传和终端交互与本地 claude 完全一致
174+
**Depends on**: Phase 25
175+
**Requirements**: CLI-03, TTY-01, TTY-02, TTY-03
190176
**Success Criteria** (what must be TRUE):
191-
1. /etc/machine-id 包含基于配置派生的稳定伪造值，重启容器后保持一致
192-
2. 容器 hostname 通过 Docker --hostname 设为配置的伪造主机名
193-
3. 容器内 cat /proc/cpuinfo 和 cat /proc/meminfo 显示伪造的硬件信息（通过 docker run -v 注入）
194-
4. /.dockerenv 文件不存在、/proc/1/cgroup 无 docker 关键字、container 环境变量已清除
177+
1. 用户传入的所有 claude 参数（如 `-p "prompt"`, `--model`, `--allowedTools` 等）原样传递到容器内 Claude Code，行为与本地一致
178+
2. 终端窗口 resize 时 SIGWINCH 正确传递到容器内 Claude Code 进程，界面跟随调整
179+
3. Ctrl+C / Ctrl+\ 等信号正确转发到容器内进程，Claude Code 正常响应中断
180+
4. 容器内 Claude Code 退出码透传给本地 cloud-claude 进程，脚本可基于退出码判断结果
195181
**Plans**: TBD
196182

197-
### Phase 22: 验证与自检
198-
**Goal**: 用户可以一键验证容器环境的网络出口、DNS 路径、设备指纹和容器标记是否符合预期
199-
**Depends on**: Phase 21
200-
**Requirements**: CLI-04
183+
### Phase 27: 双 session 目录映射
184+
**Goal**: 用户当前目录通过 sshfs slave 实时映射到容器 /workspace，双向读写可靠
185+
**Depends on**: Phase 26, Phase 24
186+
**Requirements**: MAP-01, MAP-02, MAP-03
201187
**Success Criteria** (what must be TRUE):
202-
1. `claude verify` 在容器内运行检测脚本，输出出口 IP 是否匹配配置的代理出口
203-
2. verify 检测 DNS 查询是否走代理通道，报告是否存在泄漏
204-
3. verify 检测 machine-id、hostname、/proc/* 文件是否为伪造值
205-
4. verify 检测容器标记（/.dockerenv、cgroup、环境变量）是否已清除
206-
5. 所有检测项以清晰的 ✓/✗ 状态逐项输出，便于排查
188+
1. 用户运行 cloud-claude 时，CLI 自动在第二个 SSH session 上通过 sshfs slave 将当前目录映射到容器 /workspace
189+
2. 本地文件修改在容器内即时可见，容器内文件修改在本地即时可见（双向实时读写）
190+
3. Claude Code 以 /workspace 为工作目录运行，可正常读写项目文件
191+
4. 会话正常或异常退出时，容器内 sshfs 挂载点和相关资源自动清理
207192
**Plans**: TBD
208193

209-
### Phase 23: 混淆构建与交付
210-
**Goal**: 交付经 garble 混淆的单一 Go 二进制，可直接放入 PATH 替代原生 `claude` 命令
211-
**Depends on**: Phase 22
212-
**Requirements**: BUILD-01
194+
### Phase 28: 生产环境 FUSE 兼容性验证
195+
**Goal**: 在 Linux 生产环境验证 FUSE + 安全模块兼容性，确保全栈端到端可用
196+
**Depends on**: Phase 27
197+
**Requirements**: SRV-04
213198
**Success Criteria** (what must be TRUE):
214-
1. garble build 成功产出单一可执行二进制文件，体积合理
215-
2. 混淆后二进制的所有功能（启动、init、verify）与未混淆版本行为一致
216-
3. 二进制可直接放入 PATH 替代原生 claude 命令使用，用户无感知差异
199+
1. 在目标 Linux 宿主机（含 AppArmor 或 seccomp）上，容器内 sshfs 挂载成功且读写正常
200+
2. FUSE 挂载与 sing-box tun / nftables 默认拒绝策略共存，映射通道不被防火墙阻断
201+
3. 完整流程（cloud-claude → SSH Proxy → 目录映射 → Claude Code 运行）在生产环境端到端通过
217202
**Plans**: TBD
218203

219204
## Progress
220205

221206
**Execution Order:**
222-
Phases execute in numeric order: 17 → 18 → 19 → 20 → 21 → 22 → 23
207+
Phases execute in numeric order: 24 → 25 → 26 → 27 → 28
223208

224209
| Phase | Milestone | Plans Complete | Status | Completed |
225210
|-------|-----------|----------------|--------|-----------|
@@ -235,17 +220,22 @@ Phases execute in numeric order: 17 → 18 → 19 → 20 → 21 → 22 → 23
235220
| 10. 技术债务清理 | v1.1 | 2/2 | Complete | 2026-03-28 |
236221
| 11. 认证基础设施与数据迁移 | v1.2 | 1/3 | Complete | 2026-03-29 |
237222
| 12. 用户自助 API 与前端路由 | v1.2 | 2/2 | Complete | 2026-03-29 |
238-
| 13. 账号管理与用户资源视图 | v1.2 | 0/0 | Not started | - |
239-
| 14. KasmVNC 用户面 | v1.2 | 0/0 | Not started | - |
240-
| 15. Bootstrap 重设计 | v1.2 | 0/0 | Not started | - |
241-
| 16. 级联禁用与到期治理 | v1.2 | 0/0 | Not started | - |
242-
| 17. 镜像与 Entrypoint 基线 | v1.3 | 0/0 | Not started | - |
243-
| 18. 网络隔离与分流 | v1.3 | 0/0 | Not started | - |
244-
| 19. CLI 骨架与 Docker 编排 | v1.3 | 0/0 | Not started | - |
245-
| 20. TTY 透传与交互体验 | v1.3 | 0/0 | Not started | - |
246-
| 21. 指纹伪造与反检测 | v1.3 | 0/0 | Not started | - |
247-
| 22. 验证与自检 | v1.3 | 0/0 | Not started | - |
248-
| 23. 混淆构建与交付 | v1.3 | 0/0 | Not started | - |
223+
| 13. 账号管理与用户资源视图 | v1.2 | 0/0 | Deferred | - |
224+
| 14. KasmVNC 用户面 | v1.2 | 0/0 | Deferred | - |
225+
| 15. Bootstrap 重设计 | v1.2 | 0/0 | Deferred | - |
226+
| 16. 级联禁用与到期治理 | v1.2 | 0/0 | Deferred | - |
227+
| 17. 镜像与 Entrypoint 基线 | v1.3 | 0/0 | Paused | - |
228+
| 18. 网络隔离与分流 | v1.3 | 0/0 | Paused | - |
229+
| 19. CLI 骨架与 Docker 编排 | v1.3 | 0/0 | Paused | - |
230+
| 20. TTY 透传与交互体验 | v1.3 | 0/0 | Paused | - |
231+
| 21. 指纹伪造与反检测 | v1.3 | 0/0 | Paused | - |
232+
| 22. 验证与自检 | v1.3 | 0/0 | Paused | - |
233+
| 23. 混淆构建与交付 | v1.3 | 0/0 | Paused | - |
234+
| 24. 受管镜像 FUSE 硬化与容器参数 | v2.0 | 0/0 | Not started | - |
235+
| 25. cloud-claude CLI 骨架与连接 | v2.0 | 0/0 | Not started | - |
236+
| 26. 参数透传与终端体验 | v2.0 | 0/0 | Not started | - |
237+
| 27. 双 session 目录映射 | v2.0 | 0/0 | Not started | - |
238+
| 28. 生产环境 FUSE 兼容性验证 | v2.0 | 0/0 | Not started | - |
249239

250240
---
251-
*Last updated: 2026-04-09 — v1.3 roadmap created*
241+
*Last updated: 2026-04-15 — v2.0 roadmap created*

‎.planning/STATE.md‎

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,29 @@
55
See: .planning/PROJECT.md (updated 2026-04-14)
66

77
**Core value:** 给每个用户提供一台开箱即用的 SSH 云主机，并且严格保证其所有出网流量都走受控的指定出口 IP
8-
**Current focus:** v2.0 cloud-claude 透明远程 CLI — 定义需求中
8+
**Current focus:** Phase 24 — 受管镜像 FUSE 硬化与容器参数
99

1010
## Current Position
1111

12-
Phase: Not started (defining requirements)
13-
Plan: —
14-
Status: Defining requirements
15-
Last activity: 2026-04-14 — Milestone v2.0 started
12+
Phase: 24 (1 of 5 in v2.0)
13+
Plan: 0 of 0 in current phase
14+
Status: Ready to plan
15+
Last activity: 2026-04-15 — v2.0 roadmap created
1616

17-
Progress: [░░░░░░░░░░] 0%
17+
Progress: [░░░░░░░░░░] 0% (v2.0)
1818

1919
## Performance Metrics
2020

2121
**Velocity:**
2222
- Total plans completed: 0 (v2.0)
23-
- Average duration: —
24-
- Total execution time: 0 hours
23+
- Average duration: -
24+
- Total execution time: -
2525

2626
**By Phase:**
2727

2828
| Phase | Plans | Total | Avg/Plan |
2929
|-------|-------|-------|----------|
30-
| — | — | — | — |
30+
| - | - | - | - |
3131

3232
*Updated after each plan completion*
3333

@@ -38,23 +38,20 @@ Progress: [░░░░░░░░░░] 0%
3838
Decisions are logged in PROJECT.md Key Decisions table.
3939
Recent decisions affecting current work:
4040

41-
- [v2.0 design]: 客户端为独立 Go 二进制 cloud-claude，与 cloud-cli-proxy 服务端零依赖
42-
- [v2.0 design]: 目录映射首选 sshfs -o slave over SSH 多路复用，备选 Mutagen
43-
- [v2.0 design]: 用户配置存储在 ~/.cloud-claude/config.yaml
44-
- [v2.0 design]: SSH Proxy 已支持多 session channel + exec 转发，零改造可用
41+
- [v2.0 roadmap]: 目录映射主路径为 sshfs slave + SFTP，Mutagen 作为 v2.x 备选
42+
- [v2.0 roadmap]: SSH Proxy 保持零改造，cloud-claude 通过现有多 session channel 连接
4543

4644
### Pending Todos
4745

4846
None yet.
4947

5048
### Blockers/Concerns
5149

52-
- sshfs -o slave 方案需在真实 SSH Proxy 上端到端验证
53-
- 容器 FUSE 设备权限对 AppArmor/SELinux 环境的兼容性待测
54-
- 目录映射在高延迟网络下的 I/O 性能需评估
50+
- FUSE + AppArmor/seccomp 兼容性需在目标 Linux 宿主上验证（Phase 28 专项）
51+
- golang.org/x/crypto 全仓版本统一需在 Phase 25 开发前完成
5552

5653
## Session Continuity
5754

58-
Last session: 2026-04-14
59-
Stopped at: Milestone v2.0 initialized, defining requirements
60-
Resume file: —
55+
Last session: 2026-04-15
56+
Stopped at: v2.0 roadmap created, ready to plan Phase 24
57+
Resume file: None

0 commit comments

Comments
 (0)