mcp/project-docs/user-structure.md

用户流程与项目结构

员工公共使用流程

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

本地调试流程

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

AI 工具选择流程

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

跨仓开发流程

1. 从 README.md 与 project-docs/ 确认产品合同，再读取 AGENTS.md 的所有权和红线。
2. 在 Y:/mcp 同步工具 metadata、输入 Schema、stdio/public 双注册、CLI、Presenter 与 Python 测试。
3. 在 Y:/fmsoperate 按 Controller / Logic / Model / Validate 分层同步路由、业务权限、动态注册和 PHP 测试。
4. 涉及员工身份、设备会话或 token 生命周期时，在 Y:/base 同步认证实现和合同测试；home 保持 UI/薄代理边界。
5. 运行各仓定向与全量验证，核对双注册表和实际 tools/list。
6. 发布后确认 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/	设计决策背景；不替代现行合同