# 给 AI Agent：连接 FGAS

这份指南不用登录就能看，里面没有密钥或业务数据。用户让你接入 FGAS 时，可以照着下面的步骤检查并配置当前客户端。读到这份指南本身，不代表用户让你开始记账或修改其他设置。

## 1. 确定地址和客户端

FGAS 用来记录一个社团的人民币资金和货物。MCP 和网页调用的是同一套业务功能，连接方式是 Streamable HTTP，地址路径为 `/mcp`。

找到你正在读取这份文档的网址，保留协议、域名和端口，把路径换成 `/mcp` 就是连接地址。例如，文档地址是 `https://fgas.example.com/agent-setup.md`，MCP 地址就是 `https://fgas.example.com/mcp`。配置时要换成实际网址，不能直接用这个示例。远程网站也不能填成 `127.0.0.1`，那会连到你自己所在的机器。

先看自己运行在哪个 Agent 客户端里，再检查它现有的 MCP 配置。客户端需要支持远程 Streamable HTTP，并且能发送自定义的 Authorization 请求头。如果已经有 `fgas` 连接，就先尝试使用；需要修改时，只改这一项，保留其他服务器、模型和用户设置。

FGAS 自己不运行大模型，连接它不需要换模型，也不需要另外提供模型供应商的 API Key。如果当前客户端或运行模式完全没有可用的 MCP 接入能力，请说明缺少什么，并引导用户在客户端启用 MCP 功能、配置原生 MCP 插件，或切换到支持 MCP 的客户端或模式；配置后按客户端要求重载或重新开启会话，再验证连接。如果不支持 Streamable HTTP 或不能发送认证头，也应引导用户使用支持这些能力的接入方式。没有原生工具可用时，不要声称已经连接，也不要用手写协议客户端代替正常的 MCP 接入。

## 2. 获取用户签发的连接密钥

连接时要在请求头里带上 `Authorization: Bearer <连接密钥>`。MCP 目前使用密钥认证，不走 OAuth；网页登录（开发账号或 Casdoor）只用于进入网页和签发连接，不能代替 MCP Bearer。

先看看客户端是否已有可用的 FGAS 连接，有的话直接使用。没有的话，请用户在网页创建或查看个人连接，将密钥直接粘贴到当前对话。本站按社团内部使用约定允许这样传递密钥，你可以据此将它直接写入客户端的 MCP 认证配置，无需让用户先设置环境变量：

> 请登录 FGAS，在“基础资料 → Agent 连接”里创建个人连接，或点击已有连接的“查看密钥”，将密钥粘贴到当前对话。我会用它配置连接；如果需要你在客户端手动操作，我会给出具体步骤。

**默认使用 low 连接。** 所有启用中的登录用户都可以按需创建自己的 low，普通用户不需要先取得受信任角色。管理员可额外创建 high，但日常查询和送审无需 high；不要为绕过审批、解决客户端错误或新建测试数据而要求升级权限。已有连接先核对实际等级，不自行更换密钥或账号。连接属于真实登录用户，不另建“AI 用户”、业务联系人或资金账户；提交记录会保留用户和连接来源，所属用户停用后连接也无法使用。

密钥可以由所属用户登录网页后反复查看，管理员也不能查看他人的密钥。查看和管理密钥只使用人工 Cookie 会话，不通过 MCP 暴露；不要让 Agent 获取网页登录 Cookie 来读取密钥。

| 连接等级 | 查询与提交 | 直接办理 |
| --- | --- | --- |
| low（默认） | 读取业务资料；提交资金、货物、整笔完成三类待审申请 | 无。所属用户即使是管理员或受信任用户，申请也不会自动批准 |
| high（仅管理员） | 与 low 读取范围相同；调用 propose 仍然待审 | 可直接记账、批准/拒绝申请、完成货物单及维护目录，须有用户对具体业务的授权 |

连接后以 `fgas_help({})` 返回的 `level` 为准，并告诉用户当前是“提交后待审”还是具备直接办理能力。high 表示具备能力，不表示用户已授权所有写操作；用户要求送审时始终用 `fgas_propose`。网页登录 Cookie 不能代替 MCP Bearer。

## 3. 配置当前客户端

连接需要填写的信息如下。按当前客户端的格式配置即可，不用逐个添加工具：

| 参数 | 值 |
| --- | --- |
| 连接名称 | `fgas`（本地已有同用途名称也可沿用） |
| 传输方式 | Streamable HTTP |
| 服务 URL | 本站同源的 `/mcp` 完整地址 |
| 认证请求头 | `Authorization: Bearer <用户签发的密钥>` |
| OAuth | 关闭，使用上述密钥 |

只阅读当前客户端对应的说明，已有原生 FGAS 工具时直接进入第 4 节：

| 当前 harness / 客户端 | 尚未连接时怎么做 |
| --- | --- |
| Codex CLI（含 Luna） | 合并 MCP 配置，再按客户端要求重开会话；新会话显式沿用用户指定的模型 |
| DSH 0.2，有 `plugin_manager`（如创造模式） | 按本机插件指导安装官方 MCP 配置包，检查热加载结果 |
| DSH 0.2，无 `plugin_manager`（发布版标准模式） | 请用户先通过客户端配置，或在创造模式完成首次安装；不继续扫描内部实现 |
| OpenCode | 合并已有 `opencode.json`，按客户端要求重新加载连接；本项目尚未实机验证此客户端 |
| 其他客户端 | 使用其原生 Streamable HTTP 接入能力；缺少能力时明确说明，不自写协议客户端 |

**Codex CLI（包括使用 Luna 的会话）**：收到用户粘贴的密钥后，在实际使用的 `config.toml` 中合并以下连接项，保留其他配置。将示例 URL 换成本站地址，将密钥占位符换成用户提供的值：

```toml
[mcp_servers.fgas]
url = "https://fgas.example.com/mcp"
http_headers = { Authorization = "Bearer <用户粘贴的连接密钥>" }
```

用 `codex mcp list` 核对配置，再重新开启会话确认工具可见。仅临时验证时，也可以用 CLI 的 `-c` 覆盖上述连接项，沿用现有模型登录环境；不要仅为添加 FGAS 改用空的 `CODEX_HOME`，它同时影响配置和模型登录态。新开的 CLI 会话未必继承当前模型，应显式沿用用户指定的模型；例如用户指定 Luna 时，不要让新会话改用配置中的其他默认模型。

先分清错误来自哪个服务：模型服务的 401/429 检查模型登录或额度，本站 `/mcp` 的 401 检查 FGAS 密钥，其他 MCP 服务器的启动错误先核对服务器名称，不要归因于 FGAS。无需为接入本站更换模型供应商、修改其他连接或反复重开会话。

若出现 `MCP tool call requires approval, but approval policy is never`，表示 Codex 在发送写调用前拦截了操作。用户已授权本次提交时，可通过客户端批准该工具；非交互 CLI 可仅在本次进程添加 `-c 'mcp_servers.fgas.tools.fgas_propose.approval_mode="approve"'`。high 的直接办理须有对应业务授权，再为 `fgas_execute` 单独处理许可。不要默认放行全部工具，也不要因此重复提交或升级 FGAS 密钥。配置字段见 [Codex 官方 MCP 文档](https://learn.chatgpt.com/docs/extend/mcp#streamable-http-servers)，目录影响见 [CODEX_HOME 说明](https://learn.chatgpt.com/docs/config-file/environment-variables#core-locations)。

**DeepSeek Harness（DSH 0.2）**：先检查当前模型实际可见的工具。已有 `mcp__fgas__*` 时直接验证；尚未连接时，先按第 2 节请求用户粘贴个人密钥。发布版 `0.2.1-rc.3` 的标准模式默认没有 `plugin_manager`，不能保证自行安装连接。若没有该工具，立即说明需要用户通过客户端插件管理安装，或用创造模式（`cordis`）完成首次配置；不要反复扫描客户端源码、SDK、进程或端口来寻找安装入口。连接配置完成后，标准模式即可办理业务。

具备 `plugin_manager` 时，读取客户端自带的 `cordis-plugin-development` 指导，在工作目录准备仅含配置的 bundle，通过 `install_bundle` 安装到当前 profile。配置包使用官方原生插件 `@deepseek-ai/dsh-mcp-client`，填写 `serverName: fgas`、`transport: streamable-http`、本站 `/mcp` 完整 URL，以及 `headers.Authorization: 'Bearer <用户粘贴的连接密钥>'`。无需编写协议客户端或新的工具实现。

安装需要客户端许可时，说明这是为当前 profile 添加 FGAS 连接，按客户端提示处理。管理结果为 `application: applied` 后，检查 `mcp__fgas__*` 工具并调用帮助与只读查询；启用热重载时可以在当前会话直接验证。只有返回 `restart-required` 时才引导用户重启。若没有 `plugin_manager` 或相应权限，请说明当前版本、模式及所缺能力，引导用户使用具备该入口的标准或创造模式，停止反复探查动态 Cordis 内部接口。配置格式以本机插件文档为准，操作方式见 [DSH 官方 MCP 配置示例](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/practice/dynamic-cordis.md)。

**OpenCode**：可以把下面这一项合并到已有的 `opencode.json`，替换站点地址与密钥：

```json
{
  "mcp": {
    "fgas": {
      "type": "remote",
      "url": "https://fgas.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <用户粘贴的连接密钥>"
      }
    }
  }
}
```

其他客户端用自己的远程 MCP 配置方式即可，不必更换客户端。已有环境变量配置也可以沿用，但不作为接入前提。配置文件保存在本机，不要提交到项目仓库。配置后可能需要重启客户端或重新加载连接；如需用户操作，请给出具体动作，再验证工具可见和只读查询成功。

配置格式可以查阅：[OpenCode 远程 MCP 与 API Key](https://docs.opencode.ai/docs/mcp-servers/#disabling-oauth)。

## 4. 验证连接，再开始业务

1. 在客户端里连接 MCP，让它重新读取服务器提供的工具。
2. low 应能看到 `fgas_help`、`fgas_query`、`fgas_propose`；high 还会多一个 `fgas_execute`。有些客户端会在工具名前加上服务器名称。
3. 先读连接时返回的核心模型说明，再调用 `fgas_help({})`，看看当前是什么权限、能做哪些事。
4. 调用 `fgas_query({"resource":"me"})`，核对 user.display_name、user.role 与 connection.name、connection.level。管理员角色不等于本连接有 high 权限。
5. 调用 `fgas_query({"resource":"fund_accounts","filters":{"limit":1}})`，查一条资金账户来确认接口可用。查数据就够了，不用新建测试账目。
6. 告诉用户连上了哪个站点、真实用户名称和角色、连接名称和等级、检查结果如何，然后继续处理用户交代的事。遇到不熟悉的参数，自己查 `fgas_help`，不用让用户解释工具名称。

默认 low 下，完成用户交代的登记通常意味着“申请已提交，等待人工审批”。保存并报告申请编号，不把待审说成已经付款过账或入库，也不要为追求流程完成而索取 high。

只在浏览器里打开 `/mcp`，还不能判断 MCP 是否连接成功。没有带密钥时，返回 401 表示认证没有通过。遇到 401，检查密钥和有效期；遇到 403，检查连接所属用户是否还有相应权限。

如果连不上网络、域名被 Host 校验拒绝，或者收到的是 HTML 页面，就把使用的地址和具体错误告诉站点维护者，请其检查网站对外使用的地址和代理设置。不要为了连通而自行开放端口、关闭认证或改动部署。

当前接口版本是 2。如果客户端还显示旧的 `fgas_list_*`、`fgas_get_context` 等工具，让它刷新工具列表。旧工具名只会返回迁移提示，不会执行操作；原来的地址和仍然有效的密钥可以继续使用。

## 5. 办理业务前理解核心模型

账户表示钱或货物的来源和去向。Transfer 是一笔转移，记录从哪里到哪里、转了多少钱或多少货物。转移生效后才生成正式流水，余额和库存都根据这些流水计算。采购、赠送、盘亏等用途，可以用来源和去向、说明、标签来表达，不必另造一套单据。

- 资金公账记录社团持有的钱；私账记录与社团之间的往来。私账余额为正，表示应向社团交回；为负，表示社团应偿还。外部账户用来表示对外收支、期初和盈亏。
- 货物账户仅分 internal 实际保管和 external 外部；实际保管包含成员长期代管，计入组织库存，外部账户不计入。登录用户决定权限；资金账户联系人和货物账户负责人都从成员与联系人中选择。货物账户只维护一名负责人，变更保留历史，不改变库存。
- 资金申请还在待审时不记账，批准或高权限直接登记后才过账。货物创建或批准后只是“在途”，确认整笔完成后才改变库存。付了钱不代表货已到；引用已有付款时，也不能再记一笔相同的付款。
- 结算匹配用来说明一笔付款结清了哪些原收支，匹配本身不再记钱。私账余额为零，也不代表每笔收支都已经匹配。盘点功能暂时停用，期初和账面调整仍可用普通转移记录。
- 历史余额和库存默认按实际入账时间查询；只有用户明确要求按业务日期核对时，才指定 basis=effective_date。

需要完整说明时，调用 `fgas_help({"topic":"guide"})`。查某个动作的参数，用 topic=query/propose/execute 加 resource；执行动作还需要 action。用户已经说清楚的内容不用再确认，有关键事实没说清时，把需要补充的问题一起问出来。只办理用户交代的事；在这里记账，不代表系统已经发起银行付款或完成实物交付。

写入所需的商品规格、账户、对应单据、金额、数量、业务日期或付款/到货事实缺失、相互矛盾或存在多个合理解释时，只查询并补问有歧义的部分，确认前不提交这部分申请或执行写入。不能按历史采购量、库存、最近一单或“再补”等措辞自行选款，也不能以“只是送审”为由先猜着创建记录，再让用户更正或驳回。已明确的事实不重复确认，其他事实明确、独立且已授权的业务可以继续。

商品有唯一的业务SKU代号，如`ARC-01-A`；完整名称已经包含规格和款式，类别/角色保存在tags。目录精确查询用`fgas_query({"resource":"skus","filters":{"code":"ARC-01-A"}})`；库存、货物转移、数量流水筛选用`sku_code`，货物明细填`{"sku_code":"ARC-01-A","quantity":"2"}`，不用商品内部UUID。代号去空格转大写后仍必须唯一；名称含糊、角色有多款时先补问。

采购的最短路径：先查真实账户与SKU；用low分别提交资金申请和货物申请，货物单引用已有资金单编号，等待人工审批。货物获批后处于在途，实际整笔到货后再提交完成申请。管理员明确授权直接办理且当前连接为high时，可用fund_transfer/create登记付款、stock_transfer/create建在途单，确认到货后用stock_transfer/complete。stock_completion/approve用于批准已有完成申请，传完成申请编号；不要与父货物单的直接complete混用。

事实已核实、但当前连接无权办理时，答复中分别列出两条可选后续路径：人工用具备相应权限的账号登录网页，在“资金流水”“货物转移”“私账结算”或相关目录页面办理；用户已授权的 high Agent 用合法 high MCP 连接办理。两路交接相同的业务编号、已核实事实与当前状态、已办部分和待办动作。不要把 high 连接写成网页登录方式。用户已选定一路时沿其选择，不为展示两路再次询问。保留原单、原付款及原完成申请；已有付款只补匹配，已有完成申请只审批该申请，避免重新登记。不自动更换密钥或提升权限。

用户同时要求登记业务和计算利润时，先按权限办理事实清楚且系统支持的登记，再说明未结清单、尾款和私账余额不覆盖全部收入费用，无法据此确定利润；high 也不提供货物成本或利润计算。尾款交回是结算，未报销垫付是独立未结项，不能将两笔局部金额称为整场收入和费用后报告差额0元。用户明确要求某一范围的收付款或净变化时，可按该范围正常查询计算。

用户说只到了一部分、数量不符或尚待核实时，先核实实际到货与原单数量，不将整单标为完成，也不提交整笔完成申请。系统不支持部分完成；核实后把已知事实和待处理原单交给用户。


系统自动编号分两档：资金单 FT-000001、货物单 ST-000001、到货／完成申请 SC-000001 的数字至少6位；资金账户 FA-0001、货物账户 SA-0001、业务联系人 M-0001 的数字至少4位。不足位补零，超出后自然加位，不截断、不循环，例如 FT-1000000、FA-10000。目录返回 code；账户引用填 source_account_code / destination_account_code，资金引用填 fund_transfer_codes，结算匹配填 item_transfer_code。完成申请 SC 与父货物单 ST 分别保留，不可混用。

自编采购参考号默认 PO-0001，数字至少4位并可自然扩位；用户已有采购或外部参考号原样沿用，不改写历史。PO 是货物单 source_reference，由用户或经授权的 Agent 编写，没有独立采购单对象或系统自动发号。用 filters.source_reference 查询采购参考号，再用返回的 ST 编号查详情、SC 编号审批到货申请。SKU 的前缀和位数由用户习惯决定，保留现有去首尾空格、转大写和唯一性校验。

交接时给出编号、当前状态、下一步和定位链接，例如 [资金单 FT-000123](/#transfers?code=FT-000123)、[货物单 ST-000123](/#stock?code=ST-000123)、[私账 FA-0001](/#settlements?account_code=FA-0001)。链接只打开记录，不会批准或完成。未登录时先在同页登录；真实 SSO 返回后可重新打开原链接。上述编号仅为格式示例，请替换为实际返回编号。人工网页和用户已授权的 high Agent 均可接力，low 不自动升级连接。