首創結合 MCP,打造 AI 時代的企業自動化新標準
讓 AI 不只「看資料」,更能「聽懂」企業系統並直接「操作」功能
AI 與系統的語意橋樑
由 Claude 理解自然語言指令,精準對應企業專有名詞,直接操作系統功能,如自動建立表單或觸發審核流程
跨系統單一 AI 入口
使用者只需在單一 AI 介面詢問,即可完成跨系統的資料整合與數據分析
兼顧技術靈活性與安全治理
在標準化協定下,讓 AI 根據指令跨平台執行任務,同時確保企業資料治理安全
利用 AI 的語言理解能力,搭配 MCP 的執行能力,達成「無感填單」
-
從 Claude 中接上 Vital BizForm 的 MCP 複製https://bizform-mcp.vitalyun.com/mcp內的指令貼到自己 Claude 的 Connectors 中。
-
以自然語言描述需求
-
Claude 理解脈絡,呼叫對應的 BizForm 工具
-
自動完成填寫、建立、送簽全流程
賦能 AI 智慧對話,
核心 Skills 讓表單處理更精準
從自動檢索、複雜欄位填寫到異常排除,全方位提升 BizForm 智慧化流程體驗。
Bizform-MCP 新手引導:帶領第一次與 AI 協作的使用者
本技能規範:當使用者第一次指揮 Claude/AI 透過 MCP 操作 bizform 時(即使他們本身很熟悉bizform),Claude 應如何調整行為。它不會取代其他 bizform-* 技能(表單分類、關聯文件、附件上傳、檢驗流程),相關時請一併使用。
步驟 0 — 第一次操作 bizform 之前,先確認站台與表單(所有使用者)
這個步驟適用於所有使用者,不論是否屬於下方的情境 A 或情境 B。Claude 無法偵測連接器連線的那一刻,所以請在對話中 Claude 即將第一次呼叫 bizform-mcp 工具時執行。
以下情況可略過此步驟:使用者已經在對話中清楚指明了站台(depot)和表單(名稱或 formId)。不要重複詢問他們已經說過的資訊。如果只指明了其中一項,就只詢問缺少的那一項。
否則,在進行任何其他 bizform 操作之前:
- 確認站台(depot)
- 呼叫
Depots_GetAll(唯讀),列出此使用者可存取的站台。 - 如果只有一個,用一句話告訴使用者是哪一個,然後繼續,不需要詢問。
- 如果有多個,列出來(名稱 + id),請使用者選擇。
- 切換站台(
Depots_Switch)會改變目前操作中的站台,因此切換前要先跟使用者確認,切換後說明結果(「已切換到 X 站台」)。
- 呼叫
- 確認表單
- 如果使用者沒有指明表單,在選定的站台上呼叫
Forms_GetAll(唯讀),讓使用者挑選。如果清單很長,先問他們想做什麼(例如檢驗、請購),再依分類或關鍵字縮小範圍。關於分類清單為何可能不完整,請參考bizform-find-form-categories技能。
- 如果使用者沒有指明表單,在選定的站台上呼叫
- 兩者都確認後,繼續之前先簡短重述一次:「接下來會在『X 站台』的『Y 表單』上操作。」
這個步驟控制在一次簡短的來回內完成。它是避免在錯誤站台或表單上操作的安全檢查,不是面談。
兩條獨立的觸發軌道
把它們當作各自獨立的訊號。使用者可能兩者都不符合、只符合其中一個,或同時符合兩個。不要把它們合併成一個籠統的「特別小心」模式,它們需要不同的回應方式。
情境 A — 第一次與 AI 協作(不是第一次用 bizform)
高可信度訊號(只要出現任一項就立即觸發):
- 明確表示:「我是新手」「這要怎麼用」「第一次用這個」「不知道怎麼下指令」
中可信度訊號(至少要同時出現兩項才觸發;單獨出現一項,即使是有經驗的使用者也很常見):
- 請求中完全沒有具體的表單名稱、表單 ID、欄位值或文件 ID
- 當 Claude 使用
formId、fieldInfo、Documents_Patch、relatedform等術語時,使用者明顯困惑,或沒有實質回應 - 「整個幫我做完」這類請求,卻沒有說明驗收標準或檢查步驟
以下情況不要觸發:使用者已經用具體的表單名稱、ID 或欄位層級的邏輯在溝通。用詞精確代表他們了解這個系統,即使這是他們第一次使用 Claude。判斷依據是用詞的精確度,而不是是否為第一輪對話。
情境 A 觸發時,調整行為如下:
- 預設先做唯讀操作(
*_Get、*_GetAll),再做任何建立/更新/修補,即使使用者的請求隱含了寫入動作,也要先跟他們確認範圍再寫入。 - 技術術語第一次出現時,在行內加一句白話解釋(例如「
formId(表單的識別碼,每張表單範本都有一個固定的 ID)」;「depot(站台,也就是你所在的 bizform 工作環境)」)。 - 行動前說明意圖,行動後說明結果:「接下來我要查詢 X,因為要確認 Y」→ 執行 →「查詢結果是 Z,代表……」。不要默默連續呼叫多個工具。
- 先把 API 錯誤翻譯成白話再呈現;不要把原始錯誤 JSON 當作主要說明貼出來。
- 主動提供(但不強迫)
assets/onboarding-guide.md,見下方「提供指南」。
情境 B — 安全/權限敏感
訊號(任一項即觸發此軌道,與情境 A 無關):
- 明確提到 權限/資安/稽核/越權/誰能看到/audit/access control
- 使用者自述或可推斷屬於受監管產業:銀行、政府、醫療,或類似重視法規遵循的情境
兩者同時出現時,情境 B 優先於情境 A。 一位有經驗的 bizform 使用者提出權限問題時,仍要完整套用情境 B,不要因為他在其他方面看起來技術熟練就降級處理。
情境 B 觸發時,調整行為如下:
- 直接、不含糊地說明這個整合的實際權限模型,不要用虛假的安心話帶過。目前不要把特定模型(個人使用者 token 或共用服務帳號)當作事實陳述。 截至本技能最後更新時,這個細節尚未經開發團隊確認。請直接說:「這部分的實際權限模型我目前沒有肯定答案,需要跟開發團隊確認,不要用『放心啦』含糊帶過。」並指向
assets/onboarding-guide.md的常見問題(FAQ)段落,那裡有目前的答案(可能仍是暫定內容)。在把它當作定論引用之前,先確認它是否已經填寫完成。 - 如果使用者問到稽核軌跡/誰做了什麼的可追溯性,同樣適用上述原則:除非真的確認過(例如檢查相關的 MCP 工具或 bizform API 是否有提供這類資訊),否則不要斷言 bizform-mcp 會以個別使用者為單位記錄操作。如果不確定,就照實說,並提議透過實際 API 去查,而不是猜測。
- 對於受監管產業的使用者,在他們第一次寫入操作時:如果步驟 0 的
Depots_GetAll結果中有使用者認定為自己測試環境的站台,建議先在那裡試。不要假設一定有這樣的測試站台,很多客戶只有正式站台。如果沒有,改建議同等的低風險替代方式:在正式環境建立明確標示的測試範本/表單,或建立帶有明顯「測試/TEST」標記的文件,確認流程可行後再刪除或作廢,而不是拿真實的業務文件當第一次試驗。不論哪種方式,在執行第一次未明確標示為測試的正式環境寫入之前,都要先跟使用者確認,不要只因為請求是以直接指令的形式提出就逕行執行。 - 除非已經驗證過,否則絕不聲稱 MCP 會賦予比使用者在 bizform 中原有權限更高或不同的權限。這是關於系統的事實陳述,不是語氣問題。
提供指南
assets/onboarding-guide.md 是一份寫給人類使用者的獨立文件,不是寫給 Claude 的。情境 A 觸發時,提供這份文件,而不是每次都在對話中重新解釋一遍:「要不要我先給你一份新手指南,裡面有基本的使用方式跟常見問題?」如果使用者接受,把檔案提供給他們(或者如果他們想留在對話中,就貼上相關段落)。不要在對方沒有要求的情況下,把整份指南改寫後貼進對話;這樣會失去它作為可反覆查閱的參考資料的用途。
本技能不包含的範圍
- 它不能取代對破壞性/寫入操作的確認。這項要求(見其他
bizform-*技能及一般良好實務)無論情境 A 或 B 是否啟用都適用。 - 它不是對 bizform-mcp 本身的安全稽核。如果情境 B 的使用者問到本技能沒有確定答案的問題,就照實說,並轉交開發團隊,而不是編造一個聽起來合理的答案。
# Bizform-MCP 新手引導:帶領第一次與 AI 協作的使用者 本技能規範:當使用者第一次指揮 Claude/AI 透過 MCP 操作 bizform 時(即使他們本身很熟悉 bizform),Claude 應如何調整行為。它不會取代其他 `bizform-*` 技能(表單分類、關聯文件、 附件上傳、檢驗流程),相關時請一併使用。 ## 步驟 0 — 第一次操作 bizform 之前,先確認站台與表單(所有使用者) 這個步驟適用於**所有使用者**,不論是否屬於下方的情境 A 或情境 B。Claude 無法偵測連接器 連線的那一刻,所以請在對話中 Claude 即將第一次呼叫 bizform-mcp 工具時執行。 **以下情況可略過此步驟**:使用者已經在對話中清楚指明了站台(depot)和表單(名稱或 formId)。 不要重複詢問他們已經說過的資訊。如果只指明了其中一項,就只詢問缺少的那一項。 **否則,在進行任何其他 bizform 操作之前:** 1. **確認站台(depot)** - 呼叫 `Depots_GetAll`(唯讀),列出此使用者可存取的站台。 - 如果只有一個,用一句話告訴使用者是哪一個,然後繼續,不需要詢問。 - 如果有多個,列出來(名稱 + id),請使用者選擇。 - 切換站台(`Depots_Switch`)會改變目前操作中的站台,因此**切換前要先跟使用者確認**, 切換後說明結果(「已切換到 X 站台」)。 2. **確認表單** - 如果使用者沒有指明表單,在選定的站台上呼叫 `Forms_GetAll`(唯讀),讓使用者挑選。 如果清單很長,先問他們想做什麼(例如檢驗、請購),再依分類或關鍵字縮小範圍。關於分類 清單為何可能不完整,請參考 `bizform-find-form-categories` 技能。 3. 兩者都確認後,繼續之前先簡短重述一次: 「接下來會在『X 站台』的『Y 表單』上操作。」 這個步驟控制在一次簡短的來回內完成。它是避免在錯誤站台或表單上操作的安全檢查,不是面談。 ## 兩條獨立的觸發軌道 把它們當作**各自獨立的訊號**。使用者可能兩者都不符合、只符合其中一個,或同時符合兩個。 不要把它們合併成一個籠統的「特別小心」模式,它們需要不同的回應方式。 ### 情境 A — 第一次與 AI 協作(不是第一次用 bizform) **高可信度訊號**(只要出現任一項就立即觸發): - 明確表示:「我是新手」「這要怎麼用」「第一次用這個」「不知道怎麼下指令」 **中可信度訊號**(至少要同時出現兩項才觸發;單獨出現一項,即使是有經驗的使用者也很常見): - 請求中完全沒有具體的表單名稱、表單 ID、欄位值或文件 ID - 當 Claude 使用 `formId`、`fieldInfo`、`Documents_Patch`、`relatedform` 等術語時, 使用者明顯困惑,或沒有實質回應 - 「整個幫我做完」這類請求,卻沒有說明驗收標準或檢查步驟 **以下情況不要觸發**:使用者已經用具體的表單名稱、ID 或欄位層級的邏輯在溝通。用詞精確代表 他們了解這個系統,即使這是他們第一次使用 Claude。判斷依據是用詞的精確度,而不是是否為第一輪對話。 **情境 A 觸發時,調整行為如下:** - 預設**先做唯讀操作**(`*_Get`、`*_GetAll`),再做任何建立/更新/修補,即使使用者的請求 隱含了寫入動作,也要先跟他們確認範圍再寫入。 - 技術術語第一次出現時,在行內加一句白話解釋(例如「`formId`(表單的識別碼,每張表單範本 都有一個固定的 ID)」;「`depot`(站台,也就是你所在的 bizform 工作環境)」)。 - 行動前說明意圖,行動後說明結果:「接下來我要查詢 X,因為要確認 Y」→ 執行 →「查詢結果是 Z, 代表……」。不要默默連續呼叫多個工具。 - 先把 API 錯誤翻譯成白話再呈現;不要把原始錯誤 JSON 當作主要說明貼出來。 - 主動提供(但不強迫)`assets/onboarding-guide.md`,見下方「提供指南」。 ### 情境 B — 安全/權限敏感 **訊號**(任一項即觸發此軌道,與情境 A 無關): - 明確提到 權限/資安/稽核/越權/誰能看到/audit/access control - 使用者自述或可推斷屬於受監管產業:銀行、政府、醫療,或類似重視法規遵循的情境 **兩者同時出現時,情境 B 優先於情境 A。** 一位有經驗的 bizform 使用者提出權限問題時,仍要 完整套用情境 B,不要因為他在其他方面看起來技術熟練就降級處理。 **情境 B 觸發時,調整行為如下:** - 直接、不含糊地說明這個整合的實際權限模型,不要用虛假的安心話帶過。**目前不要把特定模型** (個人使用者 token 或共用服務帳號)**當作事實陳述。** 截至本技能最後更新時,這個細節尚未 經開發團隊確認。請直接說:「這部分的實際權限模型我目前沒有肯定答案,需要跟開發團隊確認, 不要用『放心啦』含糊帶過。」並指向 `assets/onboarding-guide.md` 的常見問題(FAQ)段落, 那裡有目前的答案(可能仍是暫定內容)。在把它當作定論引用之前,先確認它是否已經填寫完成。 - 如果使用者問到稽核軌跡/誰做了什麼的可追溯性,同樣適用上述原則:除非真的確認過(例如檢查 相關的 MCP 工具或 bizform API 是否有提供這類資訊),否則不要斷言 bizform-mcp 會以個別使用者 為單位記錄操作。如果不確定,就照實說,並提議透過實際 API 去查,而不是猜測。 - 對於受監管產業的使用者,在他們**第一次寫入操作**時:如果步驟 0 的 `Depots_GetAll` 結果中有 使用者認定為自己測試環境的站台,建議先在那裡試。**不要假設一定有這樣的測試站台**,很多客戶 只有正式站台。如果沒有,改建議同等的低風險替代方式:在正式環境建立明確標示的測試範本/表單, 或建立帶有明顯「測試/TEST」標記的文件,確認流程可行後再刪除或作廢,而不是拿真實的業務文件 當第一次試驗。不論哪種方式,在執行第一次未明確標示為測試的正式環境寫入之前,都要先跟使用者 確認,不要只因為請求是以直接指令的形式提出就逕行執行。 - 除非已經驗證過,否則絕不聲稱 MCP 會賦予比使用者在 bizform 中原有權限更高或不同的權限。 這是關於系統的事實陳述,不是語氣問題。 ## 提供指南 `assets/onboarding-guide.md` 是一份**寫給人類使用者的獨立文件**,不是寫給 Claude 的。 情境 A 觸發時,提供這份文件,而不是每次都在對話中重新解釋一遍:「要不要我先給你一份新手指南, 裡面有基本的使用方式跟常見問題?」如果使用者接受,把檔案提供給他們(或者如果他們想留在對話中, 就貼上相關段落)。不要在對方沒有要求的情況下,把整份指南改寫後貼進對話;這樣會失去它作為 可反覆查閱的參考資料的用途。 ## 本技能不包含的範圍 - 它不能取代對破壞性/寫入操作的確認。這項要求(見其他 `bizform-*` 技能及一般良好實務) 無論情境 A 或 B 是否啟用都適用。 - 它不是對 bizform-mcp 本身的安全稽核。如果情境 B 的使用者問到本技能沒有確定答案的問題, 就照實說,並轉交開發團隊,而不是編造一個聽起來合理的答案。
---
name: "bizform-mcp-onboarding"
description: 'Use before the first bizform-mcp tool call in every conversation, to confirm which 站台 (depot) and form to work on unless the user already named both. Also use when a user seems new to operating bizform-mcp through AI (not new to bizform itself): vague requests with no form name/ID/fields, confusion at terms like formId/fieldInfo/Documents_Patch, or "just do it all" with no acceptance criteria. Also trigger, with higher priority, on any security/permission/audit concern ("權限"、"資安"、"稽核"、"越權") or regulated-industry signal (banking, government, healthcare), even for experienced users. Do NOT apply the newcomer/security guidance to plain bizform data-model questions (forms/categories/workflow); those belong to the other bizform-* skills.'
---
# Bizform-MCP Onboarding: Guiding First-Time AI Collaborators
This skill governs how Claude should adapt its behavior when a user is new to directing
Claude/AI to operate bizform through MCP — even if they already know bizform itself well.
It does not replace the other `bizform-*` skills (form categories, related documents,
attachment upload, inspection flow) — use those together with this one when relevant.
## Step 0 — Confirm 站台 and form before the first bizform operation (all users)
This step applies to **every user**, regardless of Track A or Track B below. Claude cannot
detect the moment a connector is connected, so apply it at the first point in a
conversation where Claude is about to call a bizform-mcp tool.
**Skip this step** when the user has already clearly specified both the 站台 (depot) and the
form (by name or formId) in the conversation — don't re-ask what they already told you.
If they specified only one, ask only about the missing one.
**Otherwise, before any other bizform action:**
1. **確認站台(depot)**
- Call `Depots_GetAll` (read-only) to list the 站台 this user can access.
- If there is only one, tell the user which one it is in one sentence and continue — no
need to ask.
- If there are several, list them (name + id) and ask the user which one to use.
- Switching depot (`Depots_Switch`) changes the current operating 站台, so **confirm with
the user before switching** and state the result afterwards (「已切換到 X 站台」).
2. **確認表單**
- If the user hasn't named a form, call `Forms_GetAll` (read-only) on the chosen 站台 and
let the user pick. If the list is long, ask what they want to do first (e.g. 檢驗、請購)
and narrow by category or keyword — see the `bizform-find-form-categories` skill for
why category listings may be incomplete.
3. Once both are confirmed, briefly restate them before proceeding:
「接下來會在『X 站台』的『Y 表單』上操作。」
Keep this to one short exchange. It is a safety check against operating on the wrong 站台
or form, not an interview.
## Two independent trigger tracks
Treat these as **separate signals**. A user can be on neither, either, or both tracks at once.
Don't merge them into one generic "be extra careful" mode — they call for different responses.
### Track A — New to AI collaboration (not new to bizform)
**High-confidence signals** (trigger immediately on any one of these):
- Explicit statements: 「我是新手」「這要怎麼用」「第一次用這個」「不知道怎麼下指令」
**Medium-confidence signals** (need at least two co-occurring before triggering — a single
instance is normal even for experienced users):
- Request has no concrete form name, form ID, field values, or document ID at all
- User shows visible confusion or gives no substantive reaction when Claude uses terms like
`formId`, `fieldInfo`, `Documents_Patch`, `relatedform`
- "Just do the whole thing" requests with no stated acceptance criteria or review step
**Do NOT trigger** if the user is already communicating with specific form names, IDs, or
field-level logic — precise vocabulary indicates they know the system, even if this is their
first Claude session. Precision, not the first turn, is the tell.
**When Track A triggers, adjust behavior like this:**
- Default to **read-only actions first** (`*_Get`, `*_GetAll`) before any create/update/patch,
even if the user's request implies a write — confirm scope with them before writing.
- The first time a technical term appears, add a one-line plain-language gloss inline
(e.g. "`formId`(表單的識別碼,每張表單範本都有一個固定的 ID)";
"`depot`(站台,也就是你所在的 bizform 工作環境)").
- State intent before acting and outcome after acting — "接下來我要查詢 X,因為要確認 Y"
→ do it → "查詢結果是 Z,代表...". Don't silently chain multiple tool calls.
- Translate API errors into plain language before showing them; don't paste raw error JSON
as the primary explanation.
- Proactively offer (don't force) `assets/onboarding-guide.md` — see "Handing off the guide"
below.
### Track B — Security/permission sensitivity
**Signals** (any one triggers this track, independent of Track A):
- Explicit mention of 權限 / 資安 / 稽核 / 越權 / 誰能看到 / audit / access control
- Self-identified or inferable regulated industry: banking, government, healthcare, or
similar compliance-heavy context
**This track takes priority over Track A when both are present.** An experienced bizform
user who raises a permission question still gets the full Track B treatment — don't
downgrade it just because they seem technically fluent elsewhere.
**When Track B triggers, adjust behavior like this:**
- State plainly, without hedging into false reassurance, what the actual permission model is
for this integration — **do not currently claim a specific model** (individual-user token
vs. shared service account) as fact. As of this skill's last update, that detail has not
been confirmed by the development team. Say so directly: "這部分的實際權限模型我目前沒有
肯定答案,需要跟開發團隊確認,不要用『放心啦』含糊帶過。" Point to
`assets/onboarding-guide.md`'s FAQ section, which has the current (possibly still
placeholder) answer — check whether it has been filled in before quoting it as settled fact.
- If the user asks about audit trails / who-did-what traceability, apply the same rule: don't
assert bizform-mcp logs actions per-user unless you've actually confirmed it (e.g. by
checking whether a relevant MCP tool or bizform API surfaces this). If uncertain, say so and
offer to check via the actual API rather than guessing.
- For regulated-industry users about to do their **first write operation**: if the
`Depots_GetAll` result from Step 0 shows a 站台 the user identifies as their own test
environment, recommend trying there first. **Do not assume such a test 站台 exists** — many
clients only have a production 站台. If there isn't one, recommend the equivalent low-risk
alternative instead: create a clearly-labeled test template/form or a document with an
obvious "測試/TEST" marker in production, verify the flow works, then delete/void it —
rather than using a real business document as the first trial. Either way, confirm with the
user before executing the first production write that isn't clearly marked as a test —
don't just proceed because the request was phrased as a direct instruction.
- Never claim MCP grants elevated or different permissions than the user already has in
bizform unless you have verified that claim — this is a factual claim about the system,
not tone.
## Handing off the guide
`assets/onboarding-guide.md` is a **standalone document written for the human user**, not
for Claude. When Track A triggers, offer it rather than re-explaining everything inline every
time: "要不要我先給你一份新手指南,裡面有基本的使用方式跟常見問題?" If the user accepts,
present the file to them (or paste relevant sections inline if they prefer to stay in chat).
Do not paraphrase the whole guide into the chat unprompted — that defeats its purpose as a
reusable reference they can revisit later.
## What this skill is not
- Not a replacement for confirming destructive/write actions — that requirement (see the
other `bizform-*` skills and general good practice) applies regardless of whether Track A
or B is active.
- Not a security audit of bizform-mcp itself. If a Track B user asks something this skill
doesn't have a confirmed answer for, say so and escalate to the development team rather than
inventing a plausible-sounding answer.
Bizform:可靠地找出表單分類
陷阱說明
GeneralInfos_GetFormInCategoryCount(GET /api/generalInfos/formInCategoryInfo)看起來是列出站台內所有表單分類的理所當然選擇:它會回傳 all、uncategorized、favorite,以及一個categories 陣列,每個分類都有 name、id 和 count。
但它不能當作完整清單來信任。 實務上,它可能漏掉真實存在、而且裡面確實有表單的分類,尤其是最近才建立的分類;它回報的 count 也可能過時(例如顯示 0,但該分類其實有好幾張表單)。
不要只因為某個分類沒有出現在這個端點的回應中(或顯示 count: 0),就斷定「這個分類不存在」或「這個分類是空的」。
如何察覺
在信任清單之前,先檢查數字是否合理:
all - uncategorized = 應該有分類的表單總數
sum(categories[].count) = 該端點實際列出的總數如果這兩個數字對不上,就代表 categories 陣列不完整:有某些分類(或表單與分類的關聯)沒有被這個端點呈現出來。不要因為「清單看起來合理」就停下來;當某個分類是否存在有疑問時,實際做一次這個減法。
解法:直接用表單來驗證,而不是靠摘要端點
- 如果你有分類 ID,想確認它是否存在或查看其中的表單,呼叫
Forms_GetAll,並把category查詢參數設為該 ID 的字串(例如{"category": "32"},傳數字會驗證失敗)。不論摘要端點顯示什麼,這都會回傳該分類中實際存在的表單。 - 如果你需要分類的真正名稱(摘要端點的名稱也可能過時,或該分類根本沒出現在其中),找一張已知屬於該分類的表單,用
Forms_Get(id)取得後讀取它的categories陣列。每個項目都有id、name、count、creationDateTime等欄位。這是單一表單所屬分類的權威來源。 GeneralInfos_GetFormInCategoryCount只用於快速的初步概覽,或用在你沒有其他線索的分類上,絕對不要把它當作「某分類是空的或不存在」的最終依據。如果使用者指名了某個分類(名稱或 ID),但它不在輸出中,請直接執行步驟 1–2,而不是回報「找不到」。
當某分類看似不存在或是空的:快速檢查清單
- [ ]
GeneralInfos_GetFormInCategoryCount的all - uncategorized和sum(categories[].count)真的相符嗎?如果不符,清單就是不完整的,這個問題不能信任它。 - [ ] 直接用
category: "<id>"(字串)呼叫Forms_GetAll:這是「分類 X 裡有哪些表單」的權威答案。 - [ ] 如果需要分類的名稱或中繼資料,透過
Forms_Get從已知表單的categories陣列取得,而不是從摘要端點取得。 - [ ] 最近建立的分類(透過表單找到該分類後,可檢查其
creationDateTime)特別容易從摘要端點中缺漏。如果幾天內才建立的分類還沒出現在那裡,不必意外。
# Bizform:可靠地找出表單分類 ## 陷阱說明 `GeneralInfos_GetFormInCategoryCount`(`GET /api/generalInfos/formInCategoryInfo`)看起來是 列出站台內所有表單分類的理所當然選擇:它會回傳 `all`、`uncategorized`、`favorite`,以及一個 `categories` 陣列,每個分類都有 `name`、`id` 和 `count`。 **但它不能當作完整清單來信任。** 實務上,它可能漏掉真實存在、而且裡面確實有表單的分類,尤其是 最近才建立的分類;它回報的 `count` 也可能過時(例如顯示 `0`,但該分類其實有好幾張表單)。 **不要**只因為某個分類沒有出現在這個端點的回應中(或顯示 `count: 0`),就斷定「這個分類不存在」 或「這個分類是空的」。 ### 如何察覺 在信任清單之前,先檢查數字是否合理: ``` all - uncategorized = 應該有分類的表單總數 sum(categories[].count) = 該端點實際列出的總數 ``` 如果這兩個數字對不上,就代表 `categories` 陣列不完整:有某些分類(或表單與分類的關聯)沒有被 這個端點呈現出來。不要因為「清單看起來合理」就停下來;當某個分類是否存在有疑問時,實際做一次 這個減法。 ## 解法:直接用表單來驗證,而不是靠摘要端點 1. **如果你有分類 ID,想確認它是否存在或查看其中的表單**,呼叫 `Forms_GetAll`,並把 `category` 查詢參數設為該 ID 的**字串**(例如 `{"category": "32"}`,傳數字會驗證失敗)。 不論摘要端點顯示什麼,這都會回傳該分類中實際存在的表單。 2. **如果你需要分類的真正名稱**(摘要端點的名稱也可能過時,或該分類根本沒出現在其中),找一張 已知屬於該分類的表單,用 `Forms_Get(id)` 取得後讀取它的 `categories` 陣列。每個項目都有 `id`、`name`、`count`、`creationDateTime` 等欄位。這是單一表單所屬分類的權威來源。 3. **`GeneralInfos_GetFormInCategoryCount` 只用於**快速的初步概覽,或用在你沒有其他線索的分類上, 絕對不要把它當作「某分類是空的或不存在」的最終依據。如果使用者指名了某個分類(名稱或 ID), 但它不在輸出中,請直接執行步驟 1–2,而不是回報「找不到」。 ## 當某分類看似不存在或是空的:快速檢查清單 - [ ] `GeneralInfos_GetFormInCategoryCount` 的 `all - uncategorized` 和 `sum(categories[].count)` 真的相符嗎?如果不符,清單就是不完整的,這個問題不能信任它。 - [ ] 直接用 `category: "<id>"`(字串)呼叫 `Forms_GetAll`:這是「分類 X 裡有哪些表單」的 權威答案。 - [ ] 如果需要分類的名稱或中繼資料,透過 `Forms_Get` 從已知表單的 `categories` 陣列取得, 而不是從摘要端點取得。 - [ ] 最近建立的分類(透過表單找到該分類後,可檢查其 `creationDateTime`)特別容易從摘要端點中 缺漏。如果幾天內才建立的分類還沒出現在那裡,不必意外。
---
name: bizform-find-form-categories
description: >-
Use this skill whenever checking whether a form category exists in the bizform-mcp system,
listing what forms are in a category, or investigating why a category the user knows about
("分類ID:32", "MCP 應用", etc.) doesn't show up where expected. Trigger this any time you're
about to call GeneralInfos_GetFormInCategoryCount, or whenever a user says a category/form
they expect isn't appearing, or asks "why didn't I see this earlier" about categories. Covers
a non-obvious trap: GeneralInfos_GetFormInCategoryCount's `categories` array is NOT a complete
or reliable list of categories in a depot — it can silently omit categories (especially recently
created ones) and its `count` field can be stale/wrong even for categories it does list. Always
cross-check with Forms_GetAll's `category` query parameter and/or a known form's `categories`
field before concluding a category doesn't exist or is empty.
---
# Bizform: Finding Form Categories Reliably
## The trap
`GeneralInfos_GetFormInCategoryCount` (`GET /api/generalInfos/formInCategoryInfo`) looks like the
obvious place to enumerate all form categories in a depot — it returns `all`, `uncategorized`,
`favorite`, and a `categories` array with `name`, `id`, and `count` for each category.
**It is not reliable as a complete listing.** In practice it can omit categories that genuinely
exist and have forms in them — especially ones created recently — and the `count` it reports for
a category can be stale (e.g. showing `0` when the category actually has several forms).
Do **not** conclude "this category doesn't exist" or "this category is empty" just because it's
missing (or shows `count: 0`) from this endpoint's response.
### How to catch it
Sanity-check the numbers before trusting the list:
```
all - uncategorized = total forms that should be categorized
sum(categories[].count) = total the endpoint actually accounts for
```
If these two numbers don't match, the `categories` array is incomplete — there are categories (or
form-category associations) the endpoint isn't surfacing. Don't stop at "the list looks plausible";
actually do this subtraction when a category's existence is in question.
## The fix: verify directly against forms, not the summary endpoint
1. **If you have a category ID and want to confirm it exists / see its forms**, call
`Forms_GetAll` with the `category` query parameter set to the ID **as a string**
(e.g. `{"category": "32"}` — passing a number fails validation). This returns the actual forms
in that category regardless of what the summary endpoint shows.
2. **If you want the category's real name** (the summary endpoint's name can also be stale or the
category can be entirely absent from it), fetch any one form known to be in that category with
`Forms_Get(id)` and read its `categories` array — each entry has `id`, `name`, `count`,
`creationDateTime`, etc. This is the source of truth for a single form's category membership.
3. **Only use `GeneralInfos_GetFormInCategoryCount`** for a quick first-pass overview or for
categories you don't have any other lead on — never as the final word that a category is empty
or missing. If the user names a specific category (by name or ID) that isn't in its output,
go straight to steps 1–2 instead of reporting "not found."
## Quick checklist when a category seems to be missing or empty
- [ ] Do `all - uncategorized` and `sum(categories[].count)` from
`GeneralInfos_GetFormInCategoryCount` actually match? If not, the list is incomplete —
don't trust it for this question.
- [ ] Try `Forms_GetAll` with `category: "<id>"` (string) directly — this is authoritative for
"what forms are in category X."
- [ ] If you need the category's name/metadata, pull it from a known form's `categories` array
via `Forms_Get`, not from the summary endpoint.
- [ ] Recently created categories (check `creationDateTime` once you find the category via a
form) are especially likely to be missing from the summary endpoint — don't be surprised if
a category made in the last few days isn't listed there yet.
Bizform:Relatedform 連結與 List-Table(subDocuments)— 正確用法
本技能記錄 bizform-mcp OpenAPI(Documents_Create、Documents_Update、Documents_Patch)幾個不明顯、容易出錯的行為。這些錯誤都是「靜默」的:API 不論如何都回傳 200/204 成功,隨便讀回來看資料也*像是*正確的,但從終端使用者的角度來看,文件其實已經壞了。
1. 讓 relatedform 欄位真正顯示為可點擊的連結
陷阱說明
relatedform 屬性的範本(取自 Forms_Get)長這樣:
{
"id": "field_1",
"displayName": "關聯檢修單號",
"fieldInfo": {
"type": "relatedform",
"value": ["related", "bizform", "main", "<guid-or-empty>", "430"]
}
}很容易就只把頂層的 value/defaultValue 設成目標文件的 ID(例如 ["14184"]),而fieldInfo.value 保持不動。這是錯的。 它會被接受、會被儲存,甚至用 Documents_Get 讀回來時也顯示正確,但在實際的網頁介面上,這個欄位會顯示為純文字,而不是可點擊的連結。這個「關聯」並不是真的,你只是存了一個剛好長得像 ID 的數字。
解法
fieldInfo.value 必須把目標 documentId 附加在最後一個元素:
{
"id": "field_1",
"displayName": "關聯檢修單號",
"fieldInfo": {
"type": "relatedform",
"value": ["related", "bizform", "main", "<guid-or-empty>", "430", "14184"]
},
"value": ["14184"],
"defaultValue": ["14184"]
}- 第 1–5 個元素(
related、bizform、main、guid、來源表單 ID)從範本原封不動複製,不要改動。 - 第 6 個元素是你要連結的實際目標 documentId。就是這一項讓介面顯示真正的連結。未填寫的範本中從來不會有它,必須由你自己附加上去。
- 一般的
value和defaultValue也要設成同一個 documentId 字串(兩者都需要,和其他欄位一樣)。
撰寫新程式碼前,如何確認正確格式
不同表單版本或欄位之間,格式可能略有差異(例如 guid 那一格可能是空字串,也可能是真的 guid)。不要用猜的,先用真實範例確認:
- 用
Documents_Query(以formId篩選)找出同一張表單中,一份你確定在介面上顯示正確的既有文件(請使用者確認,或使用一份不是你剛剛自己建立的文件)。 - 用
Documents_Get取得該文件,檢查 relatedform 屬性的fieldInfo.value陣列。 - 完全照抄該陣列的結構,只替換最後一個(目標 documentId)元素。
如果文件是你剛透過 API 自己建立的,而且還沒確認它會顯示成連結,就不要假設它是正確的。去找一份已知正確的範例來比對差異,本技能上面的範例正是這樣從一份實際可用的文件推導出來的。
2. Documents_Patch 若省略 subDocuments(list-table 列),會靜默清空它們
陷阱說明
Documents_Patch 的文件說明它是*部分*更新(「保留原有 DefaultValue」,即你沒提到的屬性會保留原本的 DefaultValue)。很容易就以為這種部分更新的語意也適用於 subDocuments(list-table/可重複列的資料)。並不適用。
subDocuments 和 attachments 一樣,是整批取代的。如果你 PATCH 一份文件只為了修正某個頂層欄位(例如一個 relatedform 連結),而 PATCH 內容中沒有附上 subDocuments 陣列,那份文件上所有既有的list-table 列都會被刪除。即使你的 PATCH 跟 list-table 完全無關,也一樣會發生。
解法
只要你要 PATCH(或 PUT/Update)一份含有 list-table 內容的 bizform 文件,就必須先重新取得完整的目前文件,並在請求內容中附上它完整、未修改的 subDocuments 陣列,即使你只是要改一個不相關的頂層屬性。
安全的更新程序:
Documents_Get(id)→ 取得完整的目前文件。- 以該完整文件的
attributes和subDocuments為基礎,組出新的 payload。 - 只修改你真正打算更改的特定屬性。
- 在
Documents_Patch(或Documents_Update)呼叫中送出完整的attributes與完整的subDocuments。 - 之後再呼叫一次
Documents_Get(id),確認你修改的欄位*以及*subDocuments的數量與內容都符合預期。不要只看 HTTP 狀態碼,204 成功不代表沒有東西遺失。
依照 API 本身的提示,同樣的注意事項也適用於 attachments。除非你已針對某個欄位特別確認過,否則請把 bizform 文件中任何陣列型態的區塊都視為「整批取代」。
3. 「custom」型態欄位(例如自動編號的 order 欄)若沒有保留 fieldInfo.value 標記,會靜默壞掉
陷阱說明
list-table 中有些欄位使用 fieldInfo.type: "custom",並在 fieldInfo.value 中放一個標記,告訴前端如何顯示或計算它們,這不是使用者輸入的資料。兩個常見例子:
// 自動編號的「項次」欄
{"id": "field_27", "fieldInfo": {"type": "custom", "value": ["order"]}}
// 公式計算欄(例如 合計 = 數量 * 價格)
{"id": "field_34", "fieldInfo": {"type": "custom", "value": ["formula", "[數量] * [價格]"]}}這類欄位本身的 value/defaultValue 通常是空的或佔位值(order 是 [""],計算欄是["formula"]),這是正常的,真正的資訊放在 fieldInfo.value 裡。很容易就根據你*手上有*的欄位值(例如看得到的列資料)來組 payload,而讓你沒有主動設定的欄位的 fieldInfo.value 預設成 [""]。這會讓欄位靜默壞掉:用來識別此 custom 欄位種類的標記("order"、"formula" 等)被清除後,介面就無法顯示它,會出現紅色的「未支援的欄位」,而不是自動編號或計算後的值。
解法
對於文件或 subDocument payload 中的每一個 "custom" 型態欄位,都要從表單範本原封不動地複製fieldInfo.value(list-table 欄位取自 Forms_Get → formTemplate.fieldsDescriptionArray,其他欄位取自頂層的 attributes)。絕對不要因為你沒有動到該欄位的可見內容,就讓它預設成 [""]。如果你只是 patch 不相關的欄位,原則和上面「subDocuments 必須重送」相同:從 Documents_Get 取得完整的目前屬性(包含 fieldInfo),原封不動地重送。
如何驗證
在信任一份已送出的文件之前,先用 Documents_Get 讀回來,檢查每個 "custom" 型態屬性的fieldInfo.value 是否與範本定義一致(例如 ["order"],而不是 [""])。如果實際介面或截圖中某個 list-table 列顯示「未支援的欄位」,第一個要檢查的就是這個不一致。
4. Documents_Patch 會拒絕帶有 form 物件的 subDocuments
陷阱說明
Documents_Get 回傳的每個 subDocument 都帶有它自己的(大多是空的/佔位的)form: {"id": 0, ...}物件。組 Documents_Patch payload 時,很容易就把這個物件原封不動地送回去(符合「拿到什麼就送回什麼」的原則)。這樣會失敗:API 會回傳 400 Bad Request — "form not exist",因為它試圖把form.id: 0 解析成真正的表單範本,卻找不到。
解法
為 Documents_Patch(或 Documents_Update)payload 組 subDocuments 陣列時,從每個subDocument 中完全拿掉 form 鍵。保留 id、title、attributes、attachments、categories、tags、時間戳記、permissions、notificationSetting、versionNumber、巢狀的subDocuments、state 和 executedDateTime,但刪除 form。頂層文件本身仍需要一個精簡的form 物件(例如 {"id": <formId>, "status": "publish", "enabledCategoryLock": false, "enabled": true}),但巢狀的 subDocuments 不需要。
呼叫 Documents_Create / Documents_Update / Documents_Patch 之前的快速檢查清單
- [ ] 這張表單有任何
relatedform欄位嗎?→ 先找一份已知正確的範例文件,確認fieldInfo.value的結構,並把真正的目標 documentId 附加為最後一個元素(不要只設定一般的value)。 - [ ] 這份文件有任何 list-table(
subDocuments)內容嗎,不論是既有的或新的?→ 如果使用 PATCH/Update,先Documents_Get,並附上完整的subDocuments陣列,而不只是你要改的欄位。 - [ ] 這份文件有任何
"custom"型態欄位嗎(order/自動編號欄、公式欄)?→ 從範本或既有文件原封不動複製它們的fieldInfo.value,絕不讓它預設成[""]。 - [ ] 如果在 PATCH/Update payload 中送出
subDocuments→ 從每個 subDocument 物件中拿掉form鍵(只在文件頂層保留精簡版的form)。 - [ ] 呼叫之後,再用
Documents_Get讀回文件並確認:(a)relatedform 的fieldInfo.value最後一個元素是目標 ID;(b)subDocuments的數量與內容符合預期,沒有任何東西被靜默刪掉;(c)每個"custom"型態欄位的fieldInfo.value仍與範本標記一致(例如["order"])。
# Bizform:Relatedform 連結與 List-Table(subDocuments)— 正確用法 本技能記錄 bizform-mcp OpenAPI(`Documents_Create`、`Documents_Update`、`Documents_Patch`) 幾個不明顯、容易出錯的行為。這些錯誤都是「靜默」的:API 不論如何都回傳 200/204 成功,隨便讀回來 看資料也*像是*正確的,但從終端使用者的角度來看,文件其實已經壞了。 ## 1. 讓 `relatedform` 欄位真正顯示為可點擊的連結 ### 陷阱說明 `relatedform` 屬性的範本(取自 `Forms_Get`)長這樣: ```json { "id": "field_1", "displayName": "關聯檢修單號", "fieldInfo": { "type": "relatedform", "value": ["related", "bizform", "main", "<guid-or-empty>", "430"] } } ``` 很容易就只把頂層的 `value`/`defaultValue` 設成目標文件的 ID(例如 `["14184"]`),而 `fieldInfo.value` 保持不動。**這是錯的。** 它會被接受、會被儲存,甚至用 `Documents_Get` 讀回來時 也顯示正確,但在實際的網頁介面上,這個欄位會顯示為**純文字**,而不是可點擊的連結。這個「關聯」 並不是真的,你只是存了一個剛好長得像 ID 的數字。 ### 解法 `fieldInfo.value` 必須把目標 **documentId 附加在最後一個元素**: ```json { "id": "field_1", "displayName": "關聯檢修單號", "fieldInfo": { "type": "relatedform", "value": ["related", "bizform", "main", "<guid-or-empty>", "430", "14184"] }, "value": ["14184"], "defaultValue": ["14184"] } ``` - 第 1–5 個元素(`related`、`bizform`、`main`、guid、來源表單 ID)從範本原封不動複製,不要改動。 - 第 6 個元素是你要連結的**實際目標 documentId**。就是這一項讓介面顯示真正的連結。未填寫的範本中 從來不會有它,必須由你自己附加上去。 - 一般的 `value` 和 `defaultValue` 也要設成同一個 documentId 字串(兩者都需要,和其他欄位一樣)。 ### 撰寫新程式碼前,如何確認正確格式 不同表單版本或欄位之間,格式可能略有差異(例如 guid 那一格可能是空字串,也可能是真的 guid)。 不要用猜的,先用真實範例確認: 1. 用 `Documents_Query`(以 `formId` 篩選)找出同一張表單中,一份你確定在介面上顯示正確的既有 文件(請使用者確認,或使用一份不是你剛剛自己建立的文件)。 2. 用 `Documents_Get` 取得該文件,檢查 relatedform 屬性的 `fieldInfo.value` 陣列。 3. 完全照抄該陣列的結構,只替換最後一個(目標 documentId)元素。 如果文件是你剛透過 API 自己建立的,而且還沒確認它會顯示成連結,就不要假設它是正確的。去找一份 已知正確的範例來比對差異,本技能上面的範例正是這樣從一份實際可用的文件推導出來的。 ## 2. `Documents_Patch` 若省略 `subDocuments`(list-table 列),會靜默清空它們 ### 陷阱說明 `Documents_Patch` 的文件說明它是*部分*更新(「保留原有 DefaultValue」,即你沒提到的屬性會保留 原本的 DefaultValue)。很容易就以為這種部分更新的語意也適用於 `subDocuments`(list-table/ 可重複列的資料)。**並不適用。** `subDocuments` 和 `attachments` 一樣,是整批取代的。如果你 PATCH 一份文件只為了修正某個頂層欄位 (例如一個 relatedform 連結),而 PATCH 內容中沒有附上 `subDocuments` 陣列,那份文件上所有既有的 list-table 列都會被刪除。即使你的 PATCH 跟 list-table 完全無關,也一樣會發生。 ### 解法 **只要你要 PATCH(或 PUT/Update)一份含有 list-table 內容的 bizform 文件,就必須先重新取得完整的 目前文件,並在請求內容中附上它完整、未修改的 `subDocuments` 陣列**,即使你只是要改一個不相關的 頂層屬性。 安全的更新程序: 1. `Documents_Get(id)` → 取得完整的目前文件。 2. 以該完整文件的 `attributes` 和 `subDocuments` 為基礎,組出新的 payload。 3. 只修改你真正打算更改的特定屬性。 4. 在 `Documents_Patch`(或 `Documents_Update`)呼叫中送出**完整的** `attributes` 與**完整的** `subDocuments`。 5. 之後再呼叫一次 `Documents_Get(id)`,確認你修改的欄位*以及* `subDocuments` 的數量與內容都 符合預期。不要只看 HTTP 狀態碼,204 成功不代表沒有東西遺失。 依照 API 本身的提示,同樣的注意事項也適用於 `attachments`。除非你已針對某個欄位特別確認過,否則 請把 bizform 文件中任何陣列型態的區塊都視為「整批取代」。 ## 3. 「custom」型態欄位(例如自動編號的 `order` 欄)若沒有保留 `fieldInfo.value` 標記,會靜默壞掉 ### 陷阱說明 list-table 中有些欄位使用 `fieldInfo.type: "custom"`,並在 `fieldInfo.value` 中放一個標記, 告訴前端如何顯示或計算它們,這不是使用者輸入的資料。兩個常見例子: ```json // 自動編號的「項次」欄 {"id": "field_27", "fieldInfo": {"type": "custom", "value": ["order"]}} // 公式計算欄(例如 合計 = 數量 * 價格) {"id": "field_34", "fieldInfo": {"type": "custom", "value": ["formula", "[數量] * [價格]"]}} ``` 這類欄位本身的 `value`/`defaultValue` 通常是空的或佔位值(`order` 是 `[""]`,計算欄是 `["formula"]`),這是正常的,真正的資訊放在 `fieldInfo.value` 裡。很容易就根據你*手上有*的欄位值 (例如看得到的列資料)來組 payload,而讓你沒有主動設定的欄位的 `fieldInfo.value` 預設成 `[""]`。 **這會讓欄位靜默壞掉**:用來識別此 custom 欄位種類的標記(`"order"`、`"formula"` 等)被清除後, 介面就無法顯示它,會出現紅色的「未支援的欄位」,而不是自動編號或計算後的值。 ### 解法 對於文件或 subDocument payload 中的每一個 `"custom"` 型態欄位,都要從表單範本原封不動地複製 `fieldInfo.value`(list-table 欄位取自 `Forms_Get` → `formTemplate.fieldsDescriptionArray`, 其他欄位取自頂層的 `attributes`)。絕對不要因為你沒有動到該欄位的可見內容,就讓它預設成 `[""]`。 如果你只是 patch 不相關的欄位,原則和上面「subDocuments 必須重送」相同:從 `Documents_Get` 取得 完整的目前屬性(包含 `fieldInfo`),原封不動地重送。 ### 如何驗證 在信任一份已送出的文件之前,先用 `Documents_Get` 讀回來,檢查每個 `"custom"` 型態屬性的 `fieldInfo.value` 是否與範本定義一致(例如 `["order"]`,而不是 `[""]`)。如果實際介面或截圖中 某個 list-table 列顯示「未支援的欄位」,第一個要檢查的就是這個不一致。 ## 4. `Documents_Patch` 會拒絕帶有 `form` 物件的 subDocuments ### 陷阱說明 `Documents_Get` 回傳的每個 subDocument 都帶有它自己的(大多是空的/佔位的)`form: {"id": 0, ...}` 物件。組 `Documents_Patch` payload 時,很容易就把這個物件原封不動地送回去(符合「拿到什麼就送回 什麼」的原則)。**這樣會失敗**:API 會回傳 `400 Bad Request — "form not exist"`,因為它試圖把 `form.id: 0` 解析成真正的表單範本,卻找不到。 ### 解法 為 `Documents_Patch`(或 `Documents_Update`)payload 組 `subDocuments` 陣列時,**從每個 subDocument 中完全拿掉 `form` 鍵**。保留 `id`、`title`、`attributes`、`attachments`、 `categories`、`tags`、時間戳記、`permissions`、`notificationSetting`、`versionNumber`、巢狀的 `subDocuments`、`state` 和 `executedDateTime`,但刪除 `form`。頂層文件本身仍需要一個精簡的 `form` 物件(例如 `{"id": <formId>, "status": "publish", "enabledCategoryLock": false, "enabled": true}`),但巢狀的 subDocuments 不需要。 ## 呼叫 Documents_Create / Documents_Update / Documents_Patch 之前的快速檢查清單 - [ ] 這張表單有任何 `relatedform` 欄位嗎?→ 先找一份已知正確的範例文件,確認 `fieldInfo.value` 的結構,並把真正的目標 documentId 附加為最後一個元素(不要只設定一般的 `value`)。 - [ ] 這份文件有任何 list-table(`subDocuments`)內容嗎,不論是既有的或新的? → 如果使用 PATCH/Update,先 `Documents_Get`,並附上完整的 `subDocuments` 陣列, 而不只是你要改的欄位。 - [ ] 這份文件有任何 `"custom"` 型態欄位嗎(order/自動編號欄、公式欄)?→ 從範本或既有文件 原封不動複製它們的 `fieldInfo.value`,絕不讓它預設成 `[""]`。 - [ ] 如果在 PATCH/Update payload 中送出 `subDocuments` → 從每個 subDocument 物件中拿掉 `form` 鍵(只在文件頂層保留精簡版的 `form`)。 - [ ] 呼叫之後,再用 `Documents_Get` 讀回文件並確認:(a)relatedform 的 `fieldInfo.value` 最後 一個元素是目標 ID;(b)`subDocuments` 的數量與內容符合預期,沒有任何東西被靜默刪掉; (c)每個 `"custom"` 型態欄位的 `fieldInfo.value` 仍與範本標記一致(例如 `["order"]`)。
---
name: bizform-related-documents
description: >-
Use whenever creating or updating bizform-mcp documents (Documents_Create, Documents_Update,
Documents_Patch) for a form with a "relatedform" field, a "list-table" (subDocuments), or a
"custom" type field (fieldInfo.type=="custom", e.g. "order" auto-number or "formula" columns).
Trigger on any fieldInfo.type == "relatedform"/"custom", or a list-table, in a formTemplate,
or before any Documents_Create/Update/Patch call on bizform. Four easy-to-miss traps: (1)
relatedform fields don't render as links unless the target documentId is appended correctly;
(2) Documents_Patch silently wipes subDocuments if not resent; (3) "custom" fields (like an
"order" column) show "未支援的欄位" if fieldInfo.value isn't copied verbatim from the
template; (4) Documents_Patch payloads must omit the nested "form" object from each
subDocument or it 400s with "form not exist". Always check this before writing a bizform
Documents_Create/Update/Patch payload.
---
# Bizform: Relatedform Links & List-Table (subDocuments) — Correct Usage
This skill documents two non-obvious behaviors of the bizform-mcp OpenAPI (`Documents_Create`,
`Documents_Update`, `Documents_Patch`) that are easy to get wrong. Both mistakes are "silent" —
the API returns 200/204 success either way, and the data *looks* right when you read it back
casually, but the document is broken from the end-user's point of view.
## 1. Making a `relatedform` field actually render as a clickable link
### The trap
A `relatedform` attribute's template (from `Forms_Get`) looks like this:
```json
{
"id": "field_1",
"displayName": "關聯檢修單號",
"fieldInfo": {
"type": "relatedform",
"value": ["related", "bizform", "main", "<guid-or-empty>", "430"]
}
}
```
It is tempting to just set the top-level `value`/`defaultValue` to the target document's ID
(e.g. `["14184"]`) and leave `fieldInfo.value` untouched. **This is wrong.** It gets accepted,
gets stored, and even shows up correctly when you `Documents_Get` it back — but in the actual
web UI the field renders as **plain text**, not a clickable link. The "relation" isn't real; you've
only stored a number that happens to look like an ID.
### The fix
`fieldInfo.value` must have the target **documentId appended as the last element**:
```json
{
"id": "field_1",
"displayName": "關聯檢修單號",
"fieldInfo": {
"type": "relatedform",
"value": ["related", "bizform", "main", "<guid-or-empty>", "430", "14184"]
},
"value": ["14184"],
"defaultValue": ["14184"]
}
```
- Elements 1–5 (`related`, `bizform`, `main`, guid, source form ID) are copied verbatim from the
template — don't touch them.
- Element 6 is the **actual target documentId** you're linking to. This is the piece that makes
the UI render a real link. It is never present in the unfilled template — you must append it
yourself.
- Set the plain `value` and `defaultValue` to the same documentId string as well (both are needed,
same as any other field).
### How to verify the exact format before writing new code
Formats can vary slightly between form versions/fields (e.g. the guid slot may be empty string
or a real guid). Don't guess — confirm against a real example first:
1. Use `Documents_Query` (filtered by `formId`) to find an existing document of the same form
that you know renders correctly in the UI (ask the user to confirm, or use one you didn't just
create yourself).
2. `Documents_Get` that document and inspect the relatedform attribute's `fieldInfo.value` array.
3. Copy that exact array shape, swapping only the final (target documentId) element.
If you just created the document yourself via the API and haven't confirmed it renders as a link,
don't assume it's correct — go find a known-good example and diff against it, exactly like this
skill's example above was derived from a real working document.
## 2. `Documents_Patch` silently wipes `subDocuments` (list-table rows) if you omit them
### The trap
`Documents_Patch` is documented as a *partial* update ("保留原有 DefaultValue" — preserves
existing DefaultValue for attributes you don't mention). It is tempting to assume this partial
semantics also applies to `subDocuments` (the list-table / repeatable-row data). **It does not.**
`subDocuments` — like `attachments` — is replaced wholesale. If you PATCH a document to fix one
top-level field (say, a relatedform link) and don't include the `subDocuments` array in your PATCH
body, every existing list-table row on that document is deleted. This happens even if your PATCH
had nothing to do with the list-table at all.
### The fix
**Any time you PATCH (or PUT/Update) a bizform document that has list-table content, you must
re-fetch the full current document first and include its complete, unmodified `subDocuments`
array in your request body** — even if you're only changing an unrelated top-level attribute.
Safe update procedure:
1. `Documents_Get(id)` → get the full current document.
2. Build your new payload starting from that full document's `attributes` and `subDocuments`.
3. Modify only the specific attribute(s) you actually intend to change.
4. Send the **complete** `attributes` + **complete** `subDocuments` in the `Documents_Patch` (or
`Documents_Update`) call.
5. `Documents_Get(id)` again afterward to confirm both the field you changed *and* the
`subDocuments` count/content are as expected. Don't just check the HTTP status — 204 success
does not mean nothing was lost.
The same caution applies to `attachments` per the API's own hints — treat any array-typed section
of a bizform document as "whole-replace" unless you've specifically confirmed otherwise for that
field.
## 3. "custom" type fields (e.g. auto-number `order` columns) break silently if their `fieldInfo.value` marker isn't preserved
### The trap
Some fields inside a list-table use `fieldInfo.type: "custom"` with a marker in `fieldInfo.value`
that tells the front end how to render/compute them — not user-entered data. Two common examples:
```json
// Auto-numbering "項次" (item number) column
{"id": "field_27", "fieldInfo": {"type": "custom", "value": ["order"]}}
// Formula-computed column (e.g. 合計 = 數量 * 價格)
{"id": "field_34", "fieldInfo": {"type": "custom", "value": ["formula", "[數量] * [價格]"]}}
```
The field's own `value`/`defaultValue` for these is typically empty or a placeholder (`[""]` for
`order`, `["formula"]` for computed columns) — that's normal, the real information lives in
`fieldInfo.value`. It's easy to build a payload from field values you *have* (like the visible
row data) and let `fieldInfo.value` default to `[""]` for fields you're not actively setting.
**This silently breaks the field**: the marker (`"order"`, `"formula"`, etc.) that identifies
what kind of custom field it is gets wiped, and the UI can no longer render it — it shows a red
"未支援的欄位" (unsupported field) instead of the auto-numbered/computed value.
### The fix
For every `"custom"` type field in a document or subDocument payload, copy `fieldInfo.value`
verbatim from the form's template (`Forms_Get` → `formTemplate.fieldsDescriptionArray` for
list-table fields, or the top-level `attributes` for others) — never let it default to `[""]`
just because you're not touching that field's visible content. If you're only patching unrelated
fields, this is the same principle as the `subDocuments`-must-be-resent rule above: pull the full
current attribute (including `fieldInfo`) from `Documents_Get` and resend it unchanged.
### How to verify
Before trusting a submitted document, `Documents_Get` it back and check every `"custom"` type
attribute's `fieldInfo.value` matches what the template defines (e.g. `["order"]`, not `[""]`).
If a list-table row shows "未支援的欄位" in the actual UI/screenshot, this mismatch is the first
thing to check.
## 4. `Documents_Patch` rejects subDocuments that include a `form` object
### The trap
`Documents_Get` returns each subDocument with its own (mostly empty/placeholder) `form: {"id": 0,
...}` object. It's tempting to round-trip that object unchanged when building a `Documents_Patch`
payload (consistent with "resend what you got"). **This fails**: the API responds with
`400 Bad Request — "form not exist"`, because it tries to resolve `form.id: 0` as a real form
template and can't.
### The fix
When building the `subDocuments` array for a `Documents_Patch` (or `Documents_Update`) payload,
**omit the `form` key from each subDocument entirely** — keep `id`, `title`, `attributes`,
`attachments`, `categories`, `tags`, timestamps, `permissions`, `notificationSetting`,
`versionNumber`, nested `subDocuments`, `state`, and `executedDateTime`, but drop `form`. The
top-level document itself still needs a minimal `form` object (e.g. `{"id": <formId>, "status":
"publish", "enabledCategoryLock": false, "enabled": true}`), but nested subDocuments do not.
## Quick checklist before calling Documents_Create / Documents_Update / Documents_Patch
- [ ] Does this form have any `relatedform` fields? → find a known-good example document first,
confirm the `fieldInfo.value` shape, and append the real target documentId as the last
element (don't just set the plain `value`).
- [ ] Does this document have any list-table (`subDocuments`) content, existing or new?
→ if using PATCH/Update, `Documents_Get` first and include the full `subDocuments` array,
not just the fields you're changing.
- [ ] Does this document have any `"custom"` type fields (order/auto-number columns, formula
columns)? → copy their `fieldInfo.value` verbatim from the template/existing document,
never let it default to `[""]`.
- [ ] If sending `subDocuments` in a PATCH/Update payload → strip the `form` key out of each
subDocument object (keep it only, minimally, at the top level of the document).
- [ ] After the call, `Documents_Get` the document again and verify: (a) relatedform
`fieldInfo.value` includes the target ID as the last element, (b) `subDocuments` count
and content match what you expect — nothing silently dropped, and (c) every `"custom"`
type field's `fieldInfo.value` still matches the template marker (e.g. `["order"]`).
Bizform:將檔案附加到文件——正確用法
「上傳檔案」和「把檔案附加到文件」是兩個獨立的 API 呼叫,不是一個。只做第一步會造成靜默失敗:工具呼叫顯示成功,但使用者的文件上看不到任何附件。
陷阱說明
Custom_Attachments_Upload(它包裝了 POST /api/files)只會把檔案上傳到暫存區。它的回應看起來就像一筆正常的附件物件:
{
"name": "example.xls",
"size": 27136,
"sourceUri": "<encrypted-blob>",
"currentPath": "<encrypted-blob>",
"uniqueId": "temp_file",
"creationDateTime": "0001-01-01T00:00:00Z"
}關鍵線索是 "uniqueId": "temp_file":不論上傳的是什麼檔案,剛上傳完時這個值一律是"temp_file"。這時很容易把這個回應當作「完成」,並告訴使用者附件已成功加上。其實並沒有。檔案尚未連結到任何文件;使用者在介面上查看文件時,根本看不到附件。
解法:兩個步驟都一定要做
步驟 1 — 上傳
呼叫 Custom_Attachments_Upload(會透過檔案選擇器元件讓使用者挑選檔案)。絕對不要嘗試用binary / base64 直接呼叫 Attachments_Upload / POST /api/files,該端點的 OpenAPI 說明明確指示要改用 Custom 工具。
原封不動地保留回傳物件中的 name、size、sourceUri、currentPath、uniqueId(此時會是 "temp_file")以及 creationDateTime。這些欄位在後端是加密字串,不要改寫、重新輸入或「整理」它們。
如果已呼叫工具,但在自己的上下文中看不到上傳結果(這很常見,因為檔案選擇器是用戶端的互動),請先對 Custom_Attachments_Upload 這個工具名稱使用 read_widget_context 取回實際回應,再繼續下一步。
步驟 2 — 附加到文件(合併,不要覆蓋)
- 呼叫
Documents_Get(documentId),取得該文件目前完整的attachments陣列(可能是空的,也可能已經有其他檔案)。 - 把步驟 1 得到的新附件物件(uniqueId 仍是
"temp_file",後端會在儲存時處理)追加到該陣列中。不要丟掉既有的附件:這個欄位是整批取代的,和subDocuments一樣(相關模式請參考bizform-related-documents技能)。 - 組出精簡的
Documents_Patchpayload:必要的頂層欄位(id、creationDateTime、versionCreationDateTime、versionNumber、state、executedDateTime、精簡的form: {id, status, enabledCategoryLock, enabled}),再加上合併後的完整attachments陣列。使用Documents_Patch時不需要重送attributes,它會保留既有的defaultValue。 - 送出
Documents_Patch呼叫。
步驟 3 — 驗證(必要,不可省略)
Documents_Patch 回傳 204 No Content 不能證明附件真的已經連結。在同一個工作階段中,曾經發生 Documents_Update 回傳 204,卻完全沒有變更 signoffList 的情況。所以一定要重新取回:
再呼叫一次 Documents_Get(documentId),在 attachments 陣列中檢查該檔案:
uniqueId現在必須是真正的雜湊值(例如"6387d2f7...de70b964de"),而不是"temp_file"。downloadPath現在應該已填入實際的網址。
兩項都確認後,才能向使用者回報成功。如果 uniqueId 仍是 "temp_file",或檔案完全不在陣列中,代表 patch 沒有生效,不要告訴使用者已經成功。
快速檢查清單
- [ ] 透過
Custom_Attachments_Upload上傳,而不是用 binary / base64 直接呼叫Attachments_Upload。 - [ ] 已取得上傳結果(從工具輸出,或在看不到時用
read_widget_context取回),並且原封不動保留sourceUri/currentPath/uniqueId。 - [ ] 先對目標文件呼叫
Documents_Get;把新附件合併進既有的attachments陣列,而不是直接取代。 - [ ] 用合併後的陣列送出
Documents_Patch。 - [ ] 之後再呼叫一次
Documents_Get,確認uniqueId是真正的雜湊值(不是"temp_file"),且downloadPath已有值,然後才告訴使用者已完成。
# Bizform:將檔案附加到文件——正確用法 「上傳檔案」和「把檔案附加到文件」是**兩個獨立的 API 呼叫**,不是一個。只做第一步會造成靜默失敗: 工具呼叫顯示成功,但使用者的文件上看不到任何附件。 ## 陷阱說明 `Custom_Attachments_Upload`(它包裝了 `POST /api/files`)只會把檔案上傳到**暫存區**。 它的回應看起來就像一筆正常的附件物件: ```json { "name": "example.xls", "size": 27136, "sourceUri": "<encrypted-blob>", "currentPath": "<encrypted-blob>", "uniqueId": "temp_file", "creationDateTime": "0001-01-01T00:00:00Z" } ``` 關鍵線索是 `"uniqueId": "temp_file"`:不論上傳的是什麼檔案,剛上傳完時這個值一律是 `"temp_file"`。這時很容易把這個回應當作「完成」,並告訴使用者附件已成功加上。**其實並沒有。** 檔案尚未連結到任何文件;使用者在介面上查看文件時,根本看不到附件。 ## 解法:兩個步驟都一定要做 ### 步驟 1 — 上傳 呼叫 `Custom_Attachments_Upload`(會透過檔案選擇器元件讓使用者挑選檔案)。絕對不要嘗試用 binary / base64 直接呼叫 `Attachments_Upload` / `POST /api/files`,該端點的 OpenAPI 說明 明確指示要改用 Custom 工具。 **原封不動**地保留回傳物件中的 `name`、`size`、`sourceUri`、`currentPath`、`uniqueId` (此時會是 `"temp_file"`)以及 `creationDateTime`。這些欄位在後端是加密字串,不要改寫、 重新輸入或「整理」它們。 如果已呼叫工具,但在自己的上下文中看不到上傳結果(這很常見,因為檔案選擇器是用戶端的互動), 請先對 `Custom_Attachments_Upload` 這個工具名稱使用 `read_widget_context` 取回實際回應, 再繼續下一步。 ### 步驟 2 — 附加到文件(合併,不要覆蓋) 1. 呼叫 `Documents_Get(documentId)`,取得該文件目前完整的 `attachments` 陣列 (可能是空的,也可能已經有其他檔案)。 2. 把步驟 1 得到的新附件物件(uniqueId 仍是 `"temp_file"`,後端會在儲存時處理)**追加**到 該陣列中。**不要丟掉既有的附件**:這個欄位是整批取代的,和 `subDocuments` 一樣 (相關模式請參考 `bizform-related-documents` 技能)。 3. 組出精簡的 `Documents_Patch` payload:必要的頂層欄位(`id`、`creationDateTime`、 `versionCreationDateTime`、`versionNumber`、`state`、`executedDateTime`、精簡的 `form: {id, status, enabledCategoryLock, enabled}`),再加上合併後的完整 `attachments` 陣列。使用 `Documents_Patch` 時不需要重送 `attributes`,它會保留既有的 `defaultValue`。 4. 送出 `Documents_Patch` 呼叫。 ### 步驟 3 — 驗證(必要,不可省略) `Documents_Patch` 回傳 `204 No Content` **不能**證明附件真的已經連結。在同一個工作階段中, 曾經發生 `Documents_Update` 回傳 204,卻完全沒有變更 `signoffList` 的情況。所以一定要重新取回: 再呼叫一次 `Documents_Get(documentId)`,在 `attachments` 陣列中檢查該檔案: - `uniqueId` 現在必須是**真正的雜湊值**(例如 `"6387d2f7...de70b964de"`),而不是 `"temp_file"`。 - `downloadPath` 現在應該已填入實際的網址。 兩項都確認後,才能向使用者回報成功。如果 `uniqueId` 仍是 `"temp_file"`,或檔案完全不在 陣列中,代表 patch 沒有生效,不要告訴使用者已經成功。 ## 快速檢查清單 - [ ] 透過 `Custom_Attachments_Upload` 上傳,而不是用 binary / base64 直接呼叫 `Attachments_Upload`。 - [ ] 已取得上傳結果(從工具輸出,或在看不到時用 `read_widget_context` 取回),並且原封不動 保留 `sourceUri` / `currentPath` / `uniqueId`。 - [ ] 先對目標文件呼叫 `Documents_Get`;把新附件合併進**既有的** `attachments` 陣列, 而不是直接取代。 - [ ] 用合併後的陣列送出 `Documents_Patch`。 - [ ] 之後再呼叫一次 `Documents_Get`,確認 `uniqueId` 是真正的雜湊值(不是 `"temp_file"`), 且 `downloadPath` 已有值,然後才告訴使用者已完成。
---
name: bizform-attachment-upload
description: >-
Use whenever adding, uploading, or attaching a file to a bizform-mcp document (Documents_Create,
Documents_Update, Documents_Patch). Trigger on any request to "上傳附件"、"加附件"、"附加檔案" to a
bizform document, or before/after calling Custom_Attachments_Upload / Attachments_Upload. Covers
a non-obvious two-step trap: uploading a file (Custom_Attachments_Upload / POST /api/files) only
stores it as a *temporary* file (uniqueId comes back as "temp_file") — it is NOT yet attached to
any document. A second step (Documents_Patch, merging into the existing attachments array) is
required to actually attach it, and Documents_Get must be used to verify the uniqueId changed
from "temp_file" to a real hash before reporting success to the user.
---
# Bizform: Attaching a File to a Document — Correct Usage
Uploading a file and attaching it to a document are **two separate API calls**, not one. Doing
only the first step is a silent failure: the tool call succeeds, but the user's document shows no
attachment.
## The trap
`Custom_Attachments_Upload` (which wraps `POST /api/files`) only uploads the file to a **temporary
staging area**. Its response looks like a normal attachment object:
```json
{
"name": "example.xls",
"size": 27136,
"sourceUri": "<encrypted-blob>",
"currentPath": "<encrypted-blob>",
"uniqueId": "temp_file",
"creationDateTime": "0001-01-01T00:00:00Z"
}
```
The giveaway is `"uniqueId": "temp_file"` — this is always `"temp_file"` right after upload,
regardless of the actual file. It is tempting to treat this response as "done" and tell the user
the attachment succeeded. **It has not.** The file is not linked to any document yet; if the user
checks the document in the UI, they will see no attachment at all.
## The fix: always do both steps
### Step 1 — Upload
Call `Custom_Attachments_Upload` (lets the user pick the file via a file-picker widget — never try
to call `Attachments_Upload` / `POST /api/files` directly with binary/base64, the OpenAPI hint on
that endpoint explicitly says to use the Custom tool instead).
Capture the returned object's `name`, `size`, `sourceUri`, `currentPath`, `uniqueId` (will be
`"temp_file"` at this point), and `creationDateTime` **verbatim** — these fields are encrypted
blobs on the backend; do not paraphrase, retype, or "clean up" them.
If you called the tool but don't see the upload result in your own context (common — the file
picker is a client-side interaction), use `read_widget_context` on the
`Custom_Attachments_Upload` tool name to retrieve the actual response before proceeding.
### Step 2 — Attach to the document (merge, don't overwrite)
1. `Documents_Get(documentId)` → get the document's full current `attachments` array (may be
empty, may already have other files).
2. Append the new attachment object from Step 1 (with its still-`"temp_file"` uniqueId — the
backend resolves it on save) to that array. **Do not drop existing attachments** — this field
is whole-replace, same as `subDocuments` (see the `bizform-related-documents` skill for that
pattern).
3. Build a minimal `Documents_Patch` payload: the required top-level fields (`id`,
`creationDateTime`, `versionCreationDateTime`, `versionNumber`, `state`, `executedDateTime`,
minimal `form: {id, status, enabledCategoryLock, enabled}`) plus the full merged `attachments`
array. You do not need to resend `attributes` for `Documents_Patch` — it preserves existing
`defaultValue`s.
4. Send the `Documents_Patch` call.
### Step 3 — Verify (mandatory, not optional)
`204 No Content` from `Documents_Patch` does **not** prove the attachment was actually linked —
in this same session, a `Documents_Update` call once returned 204 while silently making no change
to `signoffList`. Always re-fetch:
`Documents_Get(documentId)` again and check the `attachments` array for the file:
- `uniqueId` must now be a **real hash** (e.g. `"6387d2f7...de70b964de"`), not `"temp_file"`.
- `downloadPath` should now be populated with a real URL.
Only report success to the user once both of these are confirmed. If `uniqueId` is still
`"temp_file"` or the file is missing entirely, the patch did not take effect — do not tell the user
it succeeded.
## Quick checklist
- [ ] Uploaded via `Custom_Attachments_Upload`, not a direct binary/base64 call to
`Attachments_Upload`.
- [ ] Retrieved the upload result (via tool output or `read_widget_context` if not directly
visible) and kept `sourceUri` / `currentPath` / `uniqueId` verbatim.
- [ ] `Documents_Get` the target document first; merged the new attachment into the **existing**
`attachments` array rather than replacing it.
- [ ] Sent `Documents_Patch` with the merged array.
- [ ] `Documents_Get` again afterward and confirmed `uniqueId` is a real hash (not `"temp_file"`)
and `downloadPath` is populated, before telling the user it worked.
了解更多關於
Vital BizForm MCP
叡揚資訊推出的雲端智慧表單系統,結合 Claude AI 與 MCP 技術,實現從資料採集、自動填寫到合法電子簽章的完整自動化工作流。
MCP(Model Context Protocol)讓 AI 不只讀取資料,更能直接執行系統操作。BizForm 是台灣首家導入 MCP 的表單系統,Claude AI 可直接建立表單、觸發審核,無需人工切換系統。
AI 能力由 Anthropic Claude 提供支援,具備強大的繁體中文理解能力與企業級安全設計,能精準理解台灣企業專有名詞並直接操作 BizForm 系統功能。
對內深度整合 Vital CRM(客戶資料自動帶入),對外整合 DottedSign 點點簽(合法電子簽章)。透過 MCP 技術,未來可擴展更多企業系統的 AI 操作。
有。透過 DottedSign 點點簽提供的電子簽章,符合台灣《電子簽章法》,具備與實體簽名同等的法律效力,簽署紀錄完整留存可作法律舉證。
Vital BizForm 通過 ISO 27001、27017、27018、27701 四項國際資安認證。AI 在受管控的 MCP 權限範圍內操作,所有操作紀錄均可稽核,確保企業資料治理合規。
製造業(品管、出貨單)、金融保險(同意書、保單)、服務業(合約管理、滿意度回收)、人資管理(報到、請假、離職)。導入 Claude AI × MCP 後,合約週期平均縮短 80%。
不需要。視覺化拖拉介面設計表單,AI 功能以自然語言對話操作,直接用中文描述需求,Claude AI 自動完成後續步驟,零程式基礎即可上手。
三大核心差異:① 內建多關卡企業簽核流程;② 深度整合 CRM 與電子簽章,資料零搬移;③ Claude AI × MCP 讓 AI 直接執行任務,而非只顯示資料。
可申請免費試用,或預約 15 分鐘 Demo,由專人實際示範 Claude AI 操作您的業務流程。企業版提供客製化導入支援與教育訓練。