Skip to content

[P2][架构] CLI 客户端依赖服务端执行器、Git 存储和密钥库,缺少独立客户端依赖边界 #158

Closed

Description

@LIghtJUNction

范围与基线

本项检查客户端/服务端的包依赖与发行边界,不分析具体加密、文件写入或请求处理实现,也不声称客户端因此获得服务器权限或必须连接数据库。

基线:476e64f04ed1d9c7dcab4a41c4f3cdb72faad6a7。Refs #85、#82。#82 关注客户端功能与现场矩阵;本项单独处理客户端公共能力的代码归属及安装依赖,不重复其功能待办。

已观察到的依赖

客户端模块 直接依赖 被依赖模块的职责
cli.py core.executor.result_wire 网络业务执行内核
client.py storage.git.durable_write 服务端私有 Git 文本存储及二进制 CAS
client.py security.vault.client_upgrade_proof 服务端托管密钥材料的存储模块

固定源码:cli.py、client.py、storage/git.py、security/vault.py。

此外,pyproject.toml 在同一基础依赖集合中声明 Starlette、Uvicorn、psycopg、Valkey 等服务端依赖;可选依赖只有 dev,没有表达仅客户端所需的依赖集合。命令入口为 msg 和 msgd。

架构问题

客户端需要的是稳定的协议编码、签名/恢复证明和本地凭据持久化能力,却通过服务端实现模块取得这些公共能力。代码复用了,但依赖方向没有隔离:调整服务器执行器、存储后端或托管 vault 的模块组织,会连带影响客户端导入边界。

基础安装依赖也没有区分两种运行角色。项目面向受限 Agent,这让“只安装并运行客户端”缺少明确的依赖契约;这里没有测量包大小、启动时间或资源开销,不据此编造性能结论。

同仓库、同一个 Python 包或只发行两个命令都不是问题;需要解决的是客户端为何必须依赖这些服务端实现模块,而不是单纯把 client_*.py 搬进一个新目录。

建议的目标边界

保持现有仓库、公共 API 和 msg/msgd 两个命令。把真实共用的协议表示、恢复证明编码、受保护文件持久化辅助能力放在职责中立且边界小的模块中,由客户端和服务端分别引用;不复制安全敏感逻辑,也不另造通用 utils 大杂烩。

服务端业务执行、Git/CAS 后端和 server-held vault 继续留在服务端一侧。共享签名/加密代码仍保留各自 purpose、主体和上下文绑定,不因为抽公共模块而混淆客户端凭据与服务端持钥能力。

发行配置应明确客户端必需依赖与服务端依赖,为仅客户端使用提供受支持的安装方案;可以评估 extras 等方式,不强制拆成独立仓库或多个发行包,原完整安装路径需有兼容方案。

验收条件

  • 记录 CLI/TUI/签名客户端允许依赖的模块范围;不再为上述三个公共辅助能力导入服务端执行器、Git/CAS 后端或托管 vault 实现。
  • 公共能力只有一份实现和一个清晰所有者;移动不能改变签署字节、恢复证明格式、一次释放秘密语义或本地凭据保护。
  • 用导入边界检查或最小客户端装配测试防止重新引入服务端依赖,不能只检查目录名。
  • 安装元数据区分客户端与服务端角色;最小客户端环境可在没有 PostgreSQL/Valkey 服务和服务端专用 Python 依赖时加载帮助、签名及传输客户端。不得用跳过依赖错误或空成功实现。
  • 原有完整服务端安装、CLI/MCP/多传输、凭据 journal/恢复及构建回归保留;本次不改变公开命令和协议版本。

依据权威设计第01、02、13、14章。本项不要求拆微服务、重写客户端或修改生产部署。

Activity

  1. LIghtJUNction commented on Sep 28, 2026

    @LIghtJUNction
    ContributorAuthor

    本轮接手 #158,独立分支 fix/client-boundary-20260929 从 f14fd15(#165 工具端口)建立,不改 #155/#166 的恢复或数据库分支。目标是把 result_wire、原子本地文件写入、客户端升级证明及迁移签署语句收敛到中立所有者,并提供真实无服务端 Python 依赖的 wheel 客户端验证。拟用 server extra 保留完整服务端安装,dev 仍包含完整服务端测试依赖;公开命令和签署格式不变。先补云端失败回归,再提交实现;当前未完成、未关闭。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions