<!-- 文档分类: OPS-MAN-035 | 阶段: 运维 | 原路径: docs/维护者/特性访问-维护速查-2026-06-01.md -->
# Feature Access 与代理解耦维护速记

**日期**: 2026-06-01
**适用对象**: `khy`、小模型维护者、首次接手代理/登录边界问题的开发者

---

## 1. 这份速记是干什么的

当你遇到下面这类问题时，先看这份，再决定要不要读长文档：

- `khy claude` 为什么没登录也能用
- `gateway relay` 为什么要登录，但 `gateway manage` 不要
- 代理、IDE、管理入口的登录边界该改哪
- feature key / label 该去哪里加，不要写散

详细背景与完整修复过程见：

- `docs/04_IMPL_实现/[IMPL-RPT-009] 特性访问与代理解耦-2026-06-01.md`

---

## 2. 先记结论

### 运行时行为

- `proxy.*`：免登录
- `gateway.manage.*`：免登录
- `claude|codex|cursor|kiro|trae.*`：免登录
- `gateway.relay.*`：需要登录
- 未匹配 feature：默认需要登录

### 架构分工

- 启动链路问题：先看 `khy_platform/cli.py`
- 登录策略问题：先看 `backend/src/services/authGuard.js`
- feature key / family prefix / label 命名：先看 `backend/src/services/featureKeyBuilder.js`

---

## 3. 先看哪几个文件

按优先级：

1. `khy_platform/cli.py`
2. `backend/src/services/authGuard.js`
3. `backend/src/services/featureKeyBuilder.js`
4. `backend/src/cli/handlers/gateway.js`
5. `backend/src/cli/handlers/ide.js`
6. `backend/src/services/gateway/adapters/webRelayAdapter.js`
7. `backend/src/services/gateway/adapters/clipboardRelayAdapter.js`

---

## 4. 修改原则

### 如果你要改“谁该登录”

不要先改 handler 或 adapter。

先改：

- `backend/src/services/authGuard.js`

然后再看调用侧是否需要接入 `requireFeatureAccess(...)`。

### 如果你要改 feature key / 前缀 / label

不要在 handler 里直接写新字符串。

先改：

- `backend/src/services/featureKeyBuilder.js`

优先使用：

- `getFeatureFamilyPrefix(...)`
- `buildFeatureFamilyPrefixRegex(...)`
- `joinFeatureKey(...)`

### 如果你看到这些 helper

下面这些已经是**内部兼容层**，新代码不要优先依赖：

- `buildGatewayRelayFeatureKey`
- `buildGatewayManageFeaturePrefix`
- `buildGatewayManageFeatureKey`
- `buildIdeFeaturePrefixRegex`
- `buildIdeLaunchFeatureKey`
- `buildProxyFeaturePrefix`
- `buildProxyRelayFeatureKey`

它们还保留着，是为了兼容旧调用，不是推荐入口。

---

## 5. 你最容易改错的地方

### 错误 1：在业务层直接写登录判断

不要这样做：

- 在 handler 里直接写 `requireLogin(...)`
- 在 adapter 里自己决定某个入口要不要登录

正确做法：

- 统一走 `requireFeatureAccess(featureKey, fallbackLabel)`

### 错误 2：在多个文件里手写同一个 feature key

不要把这些散着写：

- `gateway.relay`
- `gateway.manage.open`
- `proxy.relay.web`

正确做法：

- family prefix 从 `featureKeyBuilder` 取
- 再用 `joinFeatureKey(...)` 组合

### 错误 3：把 `khy claude` 又绑回完整 CLI 链路

`khy claude` 现在优先直接拉起代理守护进程。

如果你未来改代理启动逻辑，不要轻易把它重新改回“必须经过完整外层命令分发链路”。

---

## 6. 最小验证命令

### Python 侧

```bash
python3 -m py_compile khy_platform/cli.py
python3 -m unittest unit_tests.test_claude_proxy_bootstrap unit_tests.test_proxy_endpoint_discovery
```

### Node / JS 侧

```bash
node --check backend/src/services/authGuard.js
node --check backend/src/services/featureKeyBuilder.js
node --check backend/src/cli/handlers/gateway.js
node --check backend/src/cli/handlers/ide.js
node --check backend/src/services/gateway/adapters/webRelayAdapter.js
node --check backend/src/services/gateway/adapters/clipboardRelayAdapter.js
npm --prefix backend test -- --runTestsByPath \
  tests/security/featureKeyBuilder.test.js \
  tests/security/authGuard.exports.test.js \
  tests/gateway/relayAccessBoundary.test.js \
  tests/cli/ide.access.test.js
```

---

## 7. 一句话工作流

看到代理/登录边界问题时，用这个顺序：

1. 先确认是启动链路问题，还是登录策略问题
2. 启动链路看 `cli.py`
3. 登录策略看 `authGuard.js`
4. 命名与前缀看 `featureKeyBuilder.js`
5. 调用层只做最小接线
6. 只跑最小验证，不要一上来全仓库乱测

---

## 8. 什么时候去看长文档

如果你遇到下面任意一种情况，直接读长文档：

- 不知道为什么要这样分层
- 想知道这轮修复完整演进顺序
- 想继续清理兼容 helper
- 想理解为什么 `khy claude` 要和外层 CLI 解耦

长文档：

- `docs/04_IMPL_实现/[IMPL-RPT-009] 特性访问与代理解耦-2026-06-01.md`
