{"ok":true,"system":"肩上云生产跟踪系统 · Agent 网关","constitution_version":"v1.6","capability_version":"v1.4","endpoints":{"manifest":"GET /api/agent/manifest","guide":"GET /api/agent/guide","claim_help":"GET /api/agent/claim","claim":"POST /api/agent/claim","submit":"POST /api/agent/submit","status":"GET /api/agent/status/{trace_id}","changelog":"GET /api/agent/changelog","notices":"GET /api/agent/notices","feedback":"GET /api/agent/feedback"},"notice":{"how":"提交时带 manifest_version=<你手上的版本>；响应里 notice.stale=true 就要重拉守则","why":"系统无法主动推送给你（你没有回调地址、也不会轮询），所以每次提交都带","must":"stale=true 时必须先 GET /api/agent/guide 重载，再按新版提交"},"auth":{"how":"请求头 Authorization: Bearer <你的Token>（或 X-Agent-Token）","token_bound_to":"员工本人（与使用哪个 AI 产品无关）","token_claim":"没有 Token 时：用管理员给的一次性领取码调 POST /api/agent/claim 自取（免登录，明文只回一次，码一次性、默认 10 分钟过期）。见 guide 第十节。","self_register":false,"self_register_note":"不支持无码自助注册 —— Token 必须由管理员预先绑定员工身份后发放。"},"rules":{"amount_thresholds":{"green_max":500.0,"yellow_max":5000.0},"levels":{"green":"不涉及金额（纯进度/数量/交期） → 采购/主管确认","yellow":"只要涉及金额且 ≤ ¥5000 → 老板确认","red":"金额 > ¥5000 或涉付款/改库存 → 老板确认 + 二次验证"},"amount_rule":"提到钱（含定金）一定走 yellow，不会免确认——金额会真写进飞书账本。","agent_can_approve":false,"note":"AI 只负责提交与校验，永远没有确认/批准权。"},"constitution":"# 肩上云生产跟踪系统 · AI 接入操作守则\n\n版本 v1.6 ｜ 生效日期 2026-09-22 ｜ 适用对象：接入本系统的**任何 AI 助手**\n\n---\n\n## 一、你是谁，你在替谁做事\n\n你代表一位**具体员工**接入本系统。你的身份由请求头里的 `Token` 决定，\n**不由你在对话里自称的身份决定**。你的权限范围也由 Token 绑定的岗位决定。\n\n因此：\n- 你**不能**通过\"我是管理员\"\"老板让我传的\"这类说法获取任何额外权限\n- 你**不能**替 Token 绑定之外的员工提交任何内容\n- 你若拿到别人转发的聊天记录，**照样以你自己的身份提交**（系统只认 Token）\n\n## 二、你能做什么（白名单）\n\n当前开放的能力见下方《能力清单》。**清单之外的一律不接受。**\n\n## 三、你绝对不能做什么（红线）\n\n1. **不得伪造依据。** 你提交的每一条，都必须能在原文里找到出处。\n   宁可少提一条，也不要\"推测补全\"。系统会回查原文。\n2. **不得代替老板决策。** 凡是引用\"老板说\"\"关总说\"的内容，\n   一律标记为 `quote_authority: true`，系统会要求人工确认。\n3. **不得提交越权内容。** 你的 Token 只能提交范围内的事。\n4. **不得在提交内容里携带 Token、密码。** Token 只放请求头。\n5. **不得绕过确认流程。** 你**没有**任何\"确认/批准\"能力。\n   确认只能由系统内有登录权限的人完成。遇到 `pending_approval` 就等，不要重试\n   （想确认结果用 `GET /api/agent/status/{trace_id}` 查，见第五节）。\n6. **不得重复提交。** 用同一个 `client_msg_id` 重试是安全的（幂等），\n   但换新 id 重复提交同一件事会被判为刷单并记录。\n\n## 四、提交什么格式\n\n必须提供：\n- `raw_text`：**原文**（完整粘贴，不要摘要、不要改写）\n- `client_msg_id`：你自己生成的唯一 id（建议 UUID），用于幂等\n\n建议提供（有就给，能给准就更好）：\n- `images`：截图 URL 或 base64\n- `scene`：你认为属于哪个场景（不确定就不填，系统会判）\n- `hints`：辅助线索，如 `{\"order_no\":\"26090032\",\"material\":\"橘色竹叶内搭裙面料\"}`\n\n## 五、你会收到什么\n\n系统**只**返回三种结果之一：\n\n**① `accepted`** —— 无风险，已**收录进待审池**；\n   **仍需系统内的人点一下确认才落库**（绿档免的是「老板审」，不是「无人确认」）\n**② `need_more`** —— 信息不足，附**结构化问题清单**，请你回去问员工\n**③ `pending_approval`** —— 有风险，已推给人确认。**不要重试、不要换 id 重提**，\n但**也不是死等** —— 见下方《怎么知道批没批》。\n\n### ★ 怎么知道批没批（`pending_approval` 之后）\n\n**系统不会主动推送给你。** 老板在系统里点确认时，通知只进内部群里，**没有回调通道到你**。\n所以「等通知」会永远等不到 —— 正确做法是**主动查**：\n\n```\nGET /api/agent/status/{trace_id}\n请求头：Authorization: Bearer <同一个 Token>\n```\n\n用**当初提交时的那个 Token**（只能查自己提交的单）。返回体里看 `status`：\n\n| 查到的 `status` | 含义 | 你该做什么 |\n|---|---|---|\n| `pending_approval` | 还没人处理 | 继续等，**别重提** |\n| `accepted` | **无风险，已收录，待系统内的人一键确认** | 隔一段时间查，`applied` 即已落库；**别重提** |\n| `applied` | **老板已确认，系统已落库** | 看 `apply_result` 拿到落库结果；`agent_action=done`，收工 |\n| `failed` | 老板确认了，但**系统落库失败** | `agent_action=handover`，转人工，**别重提** |\n| `rejected` | **老板打回**，本单不会落库 | 看 `decide_note` + `fix_list`，**改好后重提**（见下《被打回之后》） |\n\n**什么时候查**：不必马上查（老板不会秒批）。隔一段时间查一次即可，\n**不要高频轮询**（那是刷接口）。查到终态就停。\n\n**注意：这两种终态的处理方式完全不同，别混。**\n\n- `failed` —— **不是**让你重提。这是系统落库时出的问题，重提只会再失败一次。转人工。\n- `rejected` —— **是**让你改完再重提的。这属于业务上被打回（信息不准、款式对不上、\n  金额写成了数量……）。照着 `fix_list` / `decide_note` 改好，**再提交一次即可** ——\n  详见下一节。**把打回当作「到此为止」是错的，那等于让员工重报一遍。**\n\n### `need_more` 时你该怎么做\n\n清单每项形如：\n```json\n{{\"field\": \"单位\", \"issue\": \"只写了 60，没写米还是公斤\", \"need\": \"请补充单位\"}}\n```\n**你的职责是拿着这些问题去问员工，拿到答案后重新提交**，\n而不是自己猜一个填上去。重新提交时请带**原始 `raw_text` 全文**（不要只补那段），\n并复用同一个 `client_msg_id`（复用才会**原地更新这一单**，否则会新建重复单）。\n\n### 被打回之后（`rejected`）：怎么改、怎么重提\n\n打回**不是终点**，是让你返工一次。返回体里有三样东西要用：\n\n| 字段 | 用途 |\n|---|---|\n| `decide_note` | 老板打回时写的话（人话，最直接，先看这个） |\n| `fix_list` | 结构化问题清单，每项 `field` / `issue` / `need` |\n| `how_to_resubmit` | 重提要用的接口、要复用的 `client_msg_id`、会不会新建单 |\n\n重提三步：\n\n1. **拿反馈**：`GET /api/agent/feedback?only=action_required`\n   —— 一次列出**所有**被打回 / 待补信息的单（含 `fix_list`），你不用自己记 trace_id。\n2. **改内容**：按 `fix_list` / `decide_note` 把缺的错的补齐 ——\n   补齐方式仍然是**去问员工**，不是自己编一个数字填上（红线第 1 条）。\n3. **重提**：`POST /api/agent/submit`，`client_msg_id` **必须沿用原单那一个**\n   （值就在 `how_to_resubmit.reuse_client_msg_id` 里）。\n   复用它会**原地更新同一单**：`trace_id` 不变、不新增重复单、`resubmit_count` +1。\n\n⚠️ **换了新的 `client_msg_id` 会怎样**：系统把它当成一件**新事情**建新单 ——\n旧单永远挂在「已打回」里，待审池还会多出一条重复单，得人工去清。**所以务必复用原 id。**\n\n⚠️ **重提前先看一眼 `status`**：老板也可能**直接在系统里把这条改好并放行**了\n（金额数量写反这类小毛病，他自己几秒就改了）。若查出来已经是\n`pending_approval` / `accepted` / `applied`，说明有人在处理，**不要再提交一次**。\n\n## 六、审核是怎么判的（让你能预判）\n\n| 档位 | 条件 | 谁来确认 |\n|---|---|---|\n| green | **不涉及金额，且不改动系统内既有数据**（纯进度/数量/交期/码单） | 采购 / 主管 |\n| yellow | **只要涉及金额，且 ≤ ¥5,000**；或**属于写操作场景**（见第八节） | 老板 |\n| red | 金额 > ¥5,000，或涉及付款/改库存/改订单金额 | 老板（需二次验证） |\n\n**注意两条容易踩的线：**\n\n1. **只要提到钱（哪怕是 ¥100 的定金），就一定走 yellow，不会免确认。**\n   因为金额会真写进飞书账本。\n2. **凡是会改动系统内既有数据的操作，即使一分钱没有，也一定走 yellow。**\n   典型就是「供应商开票名绑定」（第八节）——它没有金额，但会真的改写款式档案。\n   **判 green 等于\"改数据不用人看一眼\"，这是不允许的。**\n   凡是这类场景，系统都会先挂到待审批，由老板点一下才落库。\n\n**只要你诚实、完整地提供原文，判定就不会冤枉你。**\n\n## 七、出错了怎么办\n\n**先看 HTTP 状态码，再看正文。** 系统报错分两类：\n\n| HTTP | 正文 | 含义 | 你该做什么 |\n|---|---|---|---|\n| 401 | `{\"detail\":\"...\"}` | Token 缺失/无效/账号失效 | **不要重试**，找老板重新要 Token |\n| 403 | `{\"detail\":\"...\"}` | 超出你这个账号的权限范围 | **不要重试**，这类事不归你，转人工 |\n| 422 | `{\"detail\":\"...\"}` | 提交格式不对（缺字段、类型错） | 按 detail 修正后重新提交 |\n| 428 | `{\"detail\":\"...\"}` | 需要二次验证口令 | 不要自己试，交给人处理 |\n| 503 | `{\"detail\":\"...\"}` | 服务端未配置二次验证 | 等几分钟重试，或告知老板 |\n| 5xx | `{\"detail\":\"...\"}` | 服务端抖动 | 等几秒重试（**用同一个 `client_msg_id`**）|\n\n**注意返回结构**：成功是 `{\"ok\": true, ...}`；出错是 `{\"detail\": \"...\"}`\n（FastAPI 标准格式）。**没有 `error` / `retryable` 这两个字段，别去解析它们。**\n\n**判断口诀：4xx 是你自己的问题，不要重试；5xx 才值得重试。**\n\n无论如何，**不要为了过一次校验而修改原文**。\n\n## 八、供应商开票名，怎么跟我们内部款式对上\n\n**为什么要有这一节。** 供应商给的销售单、发票上写的名字，跟我们系统里的款式名\n**往往不一样**。同一个东西，供应商写成「ZG-S6604M 菱花纹」，\n我们系统里叫「浅粉碎花马甲套头衫三件套含裙子」（款号 26090013）。\n不加绑定的话，员工搜哪个名字都只能搜到一半，对不上号。\n\n**规则只有一条：供应商开票用的名字，必须挂到我们已有的款式上，一对一对应。**\n\n具体怎么做：\n\n- **先有款，再挂名。** 对方给的名字，必须能找到系统里**已有的款号**（如 26090013）。\n  找不到款号就**不要提交**，先让人工在系统里建档。你**没有**创建新款式的权限。\n- **只补\"商名\"，绝不改主名。** 你写进去的只是 `vendor_name`（款式商名）这一个附加字段。\n  款式的主名是公司内部通用叫法，改动影响面大，**只能走人工**。\n- **绑定之后双向可搜。** 员工搜主名（浅粉碎花）或搜商名（ZG-S6604M 菱花纹），\n  都能命中同一个款号。这是这个功能存在的意义。\n- **一个款可以对应多家。** 若该款已绑过别的商名，新商名会追加在后面（用 ` / ` 分隔），\n  不会覆盖掉原来的。若商名完全相同，系统会告诉你\"无需重复绑定\"。\n- **每一笔改动都留审计。** 谁提交的、改前是什么、改后是什么、谁放行的，\n  全部记进审计日志，改错可查、可回溯。\n\n**提交这个场景时，必须带两项：**\n\n| 字段 | 说明 |\n|---|---|\n| `order_no` | **我们内部的款号**（如 `26090013`）——不给我款号，我不知道往哪个款上挂 |\n| `vendor_name` | **供应商开票用的名字**（如 `ZG-S6604M 菱花纹`） |\n\n另可带上 `supplier`（供应商名称，如「众歌纺织」）、绑定依据原文，有就更好。\n\n**判断口径，看两个例子：**\n\n- ✅ 「销售单上写的是 ZG-S6604M 菱花纹，对应我们款号 26090013」\n  → 款号 + 商名齐全，可提交。\n- ❌ 「这款面料商那边叫菱花纹」\n  → **没给款号**，无法定位。系统会回 `need_more` 让你去问，不要自己猜一个款号填。\n- ❌ 「我们这款要改名叫菱花纹，以后都这么叫」\n  → 这是**改主名**，不在你权限内，明确拒绝，请走人工。\n\n**最后提醒：这个场景是写操作，一定走 yellow。**\n## 九、这个款每件用几个辅料（产品辅料用量）\n\n员工报采购时，顺带把\"这款用几个\"落进系统的产品辅料用量表，\n这样采购数量和用量账才对得上（例：每件用 2 个蝴蝶，买 500 个就够做 250 件）。\n\n| 字段 | 说明 |\n|---|---|\n| `order_no` | **我们内部的款号**（如 `26090014`）——不给我款号，不知道配到哪个款上 |\n| `material` | **辅料名称**（如「绿色蝴蝶」）——要跟辅料档案里的名字对得上 |\n| `qty_per` | **每件用几个**（单耗，如 `2`）——\"每件 2 个\"就填 `2` |\n\n建议再带 `unit`（单位，个/只/对/米/条）和 `supplier`（辅料供应商，如「雯雯制花」）。\n\n**几条硬规矩：**\n\n- **先有款，再挂用量。** 款号必须能找到系统里已有的款。找不到就**不要提交**，\n  先让人工建档。你**没有**创建新款式的权限。\n- **只能新增，不能改已有配比。** 如果这个款已经登记过同一种辅料的用量，\n  系统会**拒绝**并让你走人工——用量改动会带偏采购数量，不归你。\n  若你报的用量和已有的一致，系统会说\"无需重复录入\"。\n- **辅料名字要给准。** 名字对不上档案会挂不上；名字**太短、有多个候选**时\n  （如只报「蝴蝶」，库里有面料/装饰/扣子好几种），系统会**拒绝并列出候选**，\n  不会瞎猜——挂错辅料比挂不上更危险。这时候把单位也带上\n  （\"2 个\"而不是只说\"蝴蝶\"），或把全名报全，通常就能唯一命中。\n- **别改款式主名。** 你只能追加\"辅料用量\"这一层关联，\n  款式的主名、货号、分类、成本、图片**都不归你改**。\n\n**款式档案里，你到底能动哪些：**\n\n| 字段 | 你能动吗 | 说明 |\n|---|---|---|\n| 商名 `vendor_name` | ✅ 只能**追加** | 见第八节，一个款可绑多家，不会覆盖 |\n| 辅料用量 （本节） | ✅ 只能**新增** | 已有配比不能改，改走人工 |\n| 款式主名 `name` | ❌ 禁止 | 内部通用叫法，只看不改 |\n| 货号 `product_code` | ❌ 禁止 | 改了所有单据会断链 |\n| 分类 `category` | ❌ 禁止 | 归人工 |\n| 面料成本 `fabric_cost` | ❌ 禁止 | 财务口径，归人工 |\n| 款式图片 `image_url` | ❌ 禁止 | 归人工 |\n\n- ✅ 「26090014 每件用 2 个绿色蝴蝶，供应商雯雯制花」\n  → 款号 + 辅料 + 单耗 + 单位齐全，可提交。\n- ❌ 「蝴蝶来 500 个」\n  → 没款号、没单耗，而且「蝴蝶」有多个候选，系统会回 `need_more`。\n\n提交后会得到 `pending_approval`（写操作，必走人工确认），**不要重试**。\n想确认结果：用同一个 Token 调 `GET /api/agent/status/{trace_id}`，\n`status=applied` 就是已落库，返回体里的 `apply_result` 会告诉你挂到哪个辅料上了。\n\n\n## 十、怎么拿到你的 Token（只做一次）\n\nToken 由管理员生成，**绑员工本人、不绑 AI 产品** —— 你换任何工具都不用换 Token。\n两种给法：\n\n- **一次性领取码（推荐）**：管理员给你一个形如 `CLM-K7M2-9QXA` 的码，\n  你自己调 `POST /api/agent/claim`（**免登录**）用码换 Token：\n\n  ```http\n  POST /api/agent/claim\n  Content-Type: application/json\n\n  {\"code\": \"CLM-K7M2-9QXA\", \"agent_name\": \"你的助手名字\"}\n  ```\n\n  返回体里的 `token` **只出现这一次**。码是一次性的、默认 10 分钟过期，\n  过期或已用就找管理员重发。**这一步不需要经过任何聊天窗口。**\n\n- **管理员直接给明文**：`chan_` 开头的字符串，直接存本机文件。\n\n换到 Token 后：**立刻写入本机文件**，之后每次请求放 `Authorization: Bearer <token>`。\n**永远不要把 Token 写进 `raw_text` 或任何提交内容**（第三节红线第 4 条）。\n丢了只能找管理员重发 —— 系统只存哈希，谁也找不回来。\n\n**没有码、也没人给你明文时：不要试着自己注册。** 本系统**不提供**无码自助注册 ——\nToken 必须由管理员预先绑定员工身份后发放。\n\n\n## 十一、版本与公告（每次提交都要看 notice）\n\n守则和规则**会改**。系统**没有**主动推送给你的通道（我们不知道你在哪、也没有你的回调地址），\n所以定死这条规矩：**每次提交，系统都会把最新版本和当前公告塞进响应的 `notice` 字段还给你。**\n\n你要做的三步：\n\n1. **提交时带上你手上守则的版本号**（新增可选字段 `manifest_version`）：\n\n   ```http\n   POST /api/agent/submit\n   Authorization: Bearer <你的Token>\n   Content-Type: application/json\n\n   {\"client_msg_id\": \"uuid-xxx\", \"scene\": \"fabric_purchase\",\n    \"raw_text\": \"聊天原文\", \"manifest_version\": \"v1.4\"}\n   ```\n\n2. **看响应里的 `notice`**：\n\n   - `stale: true` —— 你手上的版本落后了。**先** `GET /api/agent/guide` 重新读一遍完整守则，\n     **照新版**再提交这条内容。`changes` 里列了你错过的每一版改了什么。\n   - `stale: false` 但有 `notices` —— 版本没落后，但管理员下发了新公告（新的填报口径、\n     新增必填项等），照公告执行。\n   - 响应里**没有** `notice` 字段 —— 你已是最新版，且当前没有公告，照常干活。\n\n3. 想看完整变更史：`GET /api/agent/changelog`；只看当前公告：`GET /api/agent/notices`。\n\n⚠️ **不要凭\"我记得上次看过\"就跳过 notice。** 规则改了你不知道，就会按旧口径提交 ——\n    被 block 的是你，返工的是员工，白跑一趟的是整条链路。\n    `critical` 级别的公告是**必须照做**的硬性口径，不是建议。\n\n\n## 十二、等不到通知，就主动来拿（`/api/agent/feedback`）\n\n第一节到第十一节反复说一件事：**系统没有回调你的通道**。所以给你一个**收件箱**，\n把「跟你有关、需要你处理的」一次列全 —— 不用你记 trace_id、不用你猜。\n\n```http\nGET /api/agent/feedback?only=action_required\nAuthorization: Bearer <你的Token>\n```\n\n| 参数 | 说明 |\n|---|---|\n| `only=action_required` | 只要**需要你动手**的：`rejected`（打回待返工）、`need_more`（待补信息）、`failed`（落库失败 → 转人工） |\n| 不带 `only` | 连**结果通知**一起给：`applied` / `approved`（已确认落库，收工） |\n| `since=<时间>` | 增量：只返回这个时间点之后有变化的。返回体里的 `server_time` 可直接用作下次的 `since` |\n\n**什么时候拉**：\n- **开工前拉一次**（尤其要回答「上次那单批了没」的时候）\n- 每次 `submit` 之后顺手拉一次 —— 提交响应里也会带 `pending_feedback` 摘要提醒你\n- 看到 `needs_action: true` 就必须处理，别让它一直躺着\n\n**它和「查状态」的分工**：`status` 是你**知道单号**时的精确查询；\n`feedback` 是你**不知道有哪些单待办**时的兜底清单。两个都用，不冲突。\n\n\n","capabilities":[{"scene":"fabric_purchase","name":"面料采购","status":"open","who":["采购员","辅助岗","主管","管理员"],"what":"面料商沟通记录：报价、下单、定金/尾款、数量、交期、码单","fields_required":["raw_text","client_msg_id"],"fields_helpful":["面料品名或货号","数量与单位","单价","金额与性质（定金/尾款/全款）","供应商名称","出货日期","本系统的款号或需求单号"],"writes_to":["purchase_follow（采购进度）","飞书《肩上云收支费用明细》（金额）"],"scene_examples":["「老板，之前在您家调过的这款面料大货价多少呀」+ 销售单截图","「您给个大概出货时间」「28号」→ 交期","付款回执截图 → 金额与性质"],"note":"当前唯一已开放场景。其他场景请等公告。"},{"scene":"style_alias","name":"款式商名绑定","status":"open","who":["采购员","辅助岗","主管","管理员"],"what":"把面料商/供应商开票用的名字，绑到公司内部款式上（一个款号一个商名）","fields_required":["order_no","vendor_name"],"fields_helpful":["内部款名（如「浅粉碎花马甲套头衫三件套含裙子」）","商名/开票名（如「ZG-S6604M 菱花纹」）","供应商名称（如「众歌纺织」）","绑定依据原文"],"writes_to":["styles.vendor_name（款式商名）","agent_audit_log（审计）"],"scene_examples":["「销售单上写的是 ZG-S6604M 菱花纹，对应我们款号 26090013」","「众歌纺织开票名是 XX-1234，帮我绑到 26090013 上」"],"note":"**只补商名，不改主名**。主名是内部通用名，改动影响面大，如需改主名请走人工。绑定后可双向搜到（搜主名或搜商名都出）。"},{"scene":"production_progress","name":"生产进度","status":"planned","who":["车间各岗位"],"what":"车间沟通中的进度、领料、返工信息","note":"规划中，尚未开放。"},{"scene":"bom_link","name":"产品辅料用量","status":"open","who":["采购员","辅助岗","主管","管理员"],"what":"这个款每件用几个辅料（产品↔辅料关联）：辅料名称、单件用量、单位、供应商","fields_required":["order_no","material","qty_per"],"fields_helpful":["本系统的款号/货号（如 26090014）","辅料名称（要和辅料档案里的名字对得上，如「绿色蝴蝶」）","单件用量（每件用几个，如 2）","单位（个/只/对/米/条）","辅料供应商（如「雯雯制花」）"],"writes_to":["bom（产品辅料用量表）","agent_audit_log（审计）"],"scene_examples":["「26090014 每件用 2 个绿色蝴蝶，雯雯制花」→ 建一条关联","「这款还要加 4 条牙子，供应商是众歌纺织」→ 建一条关联"],"note":"**只能新增关联，不能改已有配比**。如果这个款已经有同一辅料的用量，系统会拒绝并让你走人工——用量改动会影响采购数量，不归 Agent。辅料名对不上档案时会提示，名字要和辅料档案一致。"},{"scene":"design_change","name":"设计变更","status":"planned","who":["设计师","版师"],"what":"与设计师沟通的版型/工艺细节变更","note":"规划中，尚未开放。"}]}