用户流程与项目结构

员工公共使用流程

员工从后台或 home 的“连接 Workbuddy”入口创建设备配置。
base 生成 GWS_xxx、服务端 MCP token session 和 Redis Gateway session；配置中不暴露 mcp_token。
Workbuddy 连接公网 /mcp，通过 Header、Bearer 或 Cookie 稳定携带同一 GWS_xxx。
initialize 完成握手，tools/list 返回 Gateway 候选集合与 fmsoperate 动态启用列表的交集。
tools/call 解析设备会话、按会话和工具限流，再携带服务端 token 调用 fmsoperate。
ThinkPHP 校验员工、公司、工具和业务数据权限；Gateway 将结果转为安全 MCP 展示。
设备撤销、token 失效或 Gateway session 过期后，后续调用关闭失败，员工重新创建设备配置。

本地调试流程

开发者从 Y:/mcp 或员工可访问的 UNC 路径运行 python app.py serve-stdio。
本地 session 从 Redis 读取；文件 token store 只用于开发排障，不放在共享目录。
使用 python app.py list-tools 检查动态可见工具，使用 python app.py call --tool ... 查看原始 ThinkPHP 信封。
使用真实 MCP 客户端验证 initialize、tools/list、tools/call 和 Presenter 展示。
工具或 Schema 变化后重启 stdio 进程并重新连接客户端；tools.listChanged=false 不会主动推送变化。

AI 工具选择流程

确认结果意图：普通订单、精准订单、轨迹、报关资料、排舱列表、排舱详情、筛选项或导出。
确认号码类型：订单号、排舱单号、物流单号、柜号、提单号或 SO 号。上下文不明确时先询问。
只调用一个已确认的目标工具；不得按号码格式猜测、并行试查、跨字段试查或失败后自行换工具。
需要筛选值时先调用对应筛选工具。唯一命中可传递内部 value，多条命中让用户选择。
排舱列表统一使用 list_outbound_filter_options 查询七类选项，包括集货仓库；不另设仓库工具。
面向用户展示中文标签和完整业务结果，内部值只用于结构化串联。

跨仓开发流程

从 README.md 与 project-docs/ 确认产品合同，再读取 AGENTS.md 的所有权和红线。
在 Y:/mcp 同步工具 metadata、输入 Schema、stdio/public 双注册、CLI、Presenter 与 Python 测试。
在 Y:/fmsoperate 按 Controller / Logic / Model / Validate 分层同步路由、业务权限、动态注册和 PHP 测试。
涉及员工身份、设备会话或 token 生命周期时，在 Y:/base 同步认证实现和合同测试；home 保持 UI/薄代理边界。
运行各仓定向与全量验证，核对双注册表和实际 tools/list。
发布后确认 Gateway 已重启、Workbuddy 已重连、动态启用值符合预期，再更新 README 和五件套中的稳定事实。

请求与输出路径

Workbuddy
  -> /mcp (GWS_xxx)
  -> PublicMcpHttpHandler
  -> PublicGatewayApp + GatewaySessionStore
  -> ScopedApiClient (server-side mcp_token)
  -> fmsoperate MCP route
  -> ThinkPHP permission/data checks
  -> OutputPresenter
  -> MCP content + structuredContent + _meta.request_id

本地 stdio 使用 GatewayApp + ApiClient + TokenStore，从协议处理开始与公网共用相同的工具合同和 Presenter。query_order 是旧展示例外。

目录地图

路径	内容
`app.py`	本地入口、CLI 和 `GatewayApp`
`public_gateway.py`、`public_server.py`	公网 Gateway 与 HTTP JSON-RPC 服务
`mcp_protocol.py`	MCP 协议处理与结果分流
`tools/`	11 个工具的 Schema、说明和路由封装
`services/`	API、认证、session、request context、scoped client 与 Presenter
`utils/`	限流和安全散列工具
`tests/`	Python 单元、协议、展示、会话和安全回归测试
`project-docs/`	现行项目五件套
`docs/superpowers/specs/`	设计决策背景；不替代现行合同

user-structure.md 4.0 KB Historique Raw

用户流程与项目结构

员工公共使用流程

本地调试流程

AI 工具选择流程

跨仓开发流程

请求与输出路径

目录地图

user-structure.md 4.0 KB

Historique Raw