# 用户流程与项目结构

## 员工公共使用流程

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 和五件套中的稳定事实。

## 请求与输出路径

```text
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/` | 设计决策背景；不替代现行合同 |