# Zh Ebn Report

> 台灣護理人員撰寫實證護理報告（實證讀書報告、實證案例分析）的完整教練技能，專為護理進階制度 N1–N4 升等、台灣護理學會與台灣實證護理學會審查格式而設計。當使用者提到「實證護理報告」、「實證案例分析」、「實證讀書報告」、「N2 報告」、「N3 報告」、「N4 報告」、「護理進階報告」、「護理升等」、「PICO」、「5A 步驟」、「CASP 評讀」、「護理 EBP」、「EBN」、「evidence-based nursing」、「實證照護」、「證據等級」、「文獻評讀」，或任何護理人員詢問升等寫作、臨床問題轉化為實證主題、實證文獻搜尋策略、CASP 評讀表、Oxford 證據等級、APA 第 7 版格式、實證介入應用至個案、護理常規挑戰、去除護理迷思等情境，**務必觸發此技能**。即使使用者只是隨口問「我要寫報告」、「我要升 N3」、「幫我找主題」、「幫我設 PICO」、「這篇文獻要怎麼評…

- **Type:** Skill
- **Install:** `agentstack add skill-htlin222-zh-ebn-report-skill-zh-ebn-report`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [htlin222](https://agentstack.voostack.com/s/htlin222)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [htlin222](https://github.com/htlin222)
- **Source:** https://github.com/htlin222/zh-ebn-report-skill/tree/main/zh-ebn-report

## Install

```sh
agentstack add skill-htlin222-zh-ebn-report-skill-zh-ebn-report
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 台灣護理實證報告寫作教練（Evidence-Based Nursing Report Coach for Taiwan）

這個技能協助台灣護理人員完成符合台灣護理學會與台灣實證護理學會審查標準的實證報告，涵蓋**實證讀書報告**與**實證案例分析**兩種類型。最終目的是幫助護理師通過 N2/N3/N4 進階審查，或產出可投稿的學術作品。

## 這份技能涵蓋哪些報告類型

台灣實證護理圈主要分成兩種入門類型：

| 類型 | 差別 | 對應層級 | 篇幅 |
|---|---|---|---|
| **實證讀書報告**（EBR） | 評析幾篇文獻後做邏輯性綜整，**無個案應用** | N1、N2 為主 | 約 8–15 頁 |
| **實證案例分析**（EBP case analysis） | 將實證結果**應用於一位真實病人**並評估成效 | N3 以上 | 約 15–25 頁 |

N4 以上多已進入系統性文獻回顧或護理專案研究，本技能不涵蓋這塊。

## 寫作前的身分確認

在動筆前，先跟使用者釐清以下四件事，用以決定使用哪個模板與深度：

1. **要寫哪一種報告？**（讀書報告 / 案例分析）
2. **是哪一級進階？**（N1–N4，或是投稿競賽）
3. **病房別與個案條件是什麼？**（決定主題合理性與可行性）
4. **醫院有沒有專用格式範本？**（有的話以醫院範本為準，本技能補足內容）

如果這些都還沒確定，**不要急著起草**，先用 `ask_user_input_v0` 工具詢問。

## 核心工作流程：實證 5A 步驟

所有實證報告都圍繞這五個步驟，缺一不可（讀書報告可到 Appraise 即可，案例分析必須跑完五步）：

1. **Ask** — 形成可回答的臨床問題（PICO）
2. **Acquire** — 搜尋最佳文獻證據
3. **Appraise** — 嚴格評讀證據（CASP + Oxford 證據等級）
4. **Apply** — 臨床應用到個案（僅案例分析）
5. **Audit** — 結果評值（僅案例分析）

詳細每一步的操作方式、常見錯誤、句型範例，見對應的 reference 檔案。

## 自動化 Pipeline 與 HITL 審稿角色分工

本技能搭配 `zh-ebn-report` Python CLI（位於專案根的 `src/zh_ebn_report/`），以 **10 個具名 subagent** 分工完成報告草稿。使用者的角色從「寫作者」轉為「**HITL 審稿者**」——在 9 個 checkpoint 介入決策、批准或要求重寫，最終的文字仍須以自己的話重寫送審（學術倫理不變）。

**Subagent 分工**（詳見 `references/subagent-roles.md`）：

| # | 角色 | 並行？ |
|---|---|---|
| 1 | 題目守門員 | 否 |
| 2 | PICO 建構員 | 否 |
| 3 | 搜尋策略師 | 否 |
| 4 | CASP 評讀員 × N | **是** |
| 5 | 綜整整合員 | 否 |
| 6 | 分節撰寫員 × 4–6 | **是** |
| 7 | 語氣守門員 | 與 8 並行 |
| 8 | APA 7 格式員 | 與 7 並行 |
| 9 | 個案敘事員 *(案例分析)* | 與 10 並行 |
| 10 | 應用審計員 *(案例分析)* | 與 9 並行 |

**dispatch 原則**：彼此輸入沒依賴的 agent 一律**並行**呼叫（Phase 4 多篇 CASP、Phase 6 各節、Phase 7 語氣+APA、Phase 5.5 個案+應用）。Claude 在互動協助情境下也應採同樣邏輯。

**CLI 介面**：

```
zh-ebn-report init --type reading|case --topic "..."
zh-ebn-report run  --resume               # end-to-end
zh-ebn-report topic|pico|search|appraise|synthesise|write|check|render
zh-ebn-report render --final                        # 去 DRAFT 後綴（需已 review）
zh-ebn-report status 
```

**LLM 後端（v0.6+）**：pipeline 預設走 Claude Code CLI（你的 Claude 訂閱），不再強制 `ANTHROPIC_API_KEY`。透過 `LLM_BACKEND` 環境變數切換：

- `LLM_BACKEND=claude_code`（預設）— 以 subprocess 呼叫 `claude -p`，走訂閱。需 PATH 上有 `claude` CLI
- `LLM_BACKEND=anthropic` — 直接走 Anthropic SDK；需 `ANTHROPIC_API_KEY`（或 `LLM_API_KEY`），適合 CI 或沒訂閱的環境
- `LLM_BACKEND=auto` — 偵測有無 `claude` CLI 再選

實作見 `clients/llm.py`（Protocol + factory）、`clients/claude_code_cli.py`（CLI 後端）、`clients/anthropic.py`（SDK 後端）。兩個後端對外介面一致，`complete()` / `complete_json()` 可互換。並發：多個 LLM call 起多個 `claude` subprocess，由 `max_parallel_casp` 等 config 限流。

**Guardrail 架構（v0.2+）**：pipeline 不再只靠 LLM 自律。每一個 LLM 寫在 prompt 的「硬性規定」只要是機械可驗證的，都有對應 Python guardrail 在 orchestrator 裡覆寫 LLM 自評結果，或在 `compliance.check_sections` 裡擋下來：

- `pipeline/evidence_guard.py` — Oxford Level 不可超過 study_design 的 OCEBM 2011 天花板（MA-of-cohort 絕不可 Level I）
- `pipeline/synthesis_guard.py` — `overall_evidence_strength` 從 CASP levels + contradictions 機械推導
- `pipeline/voice_scan.py` — regex 掃禁用詞並重算 `pass_threshold_met`
- `pipeline/apa_guard.py` — `apa_pass` 依 DOI 驗證 + citation 存在性 + LLM format_issues 推導
- `pipeline/compliance.py` — 句型、字數、引文、匿名、privacy、絕對用語、citation 捏造防線

**回歸驗證工具**：每次新增或修改 guardrail 後執行：

```
python scripts/retro_validate.py
```

把 `output//state.json` 的歷史資料全部載入，用當前 guardrail 套一遍，報告「如果當時就有這些 guardrail，會抓到什麼」。用於 (a) 確認 guardrail 捕捉到真實違規、(b) 避免回歸。加 `--json` 輸出給 CI；加 `--strict` 讓任何 guardrail 發現都退出碼 1。

**台灣護理強化（v0.8+）**：針對台灣護理實務三個核心需求的專屬支援。

1. **華藝 Airiti 匯入**：除 RIS 外新增 CSV 支援（Airiti 書目匯出預設格式）。
   - `zh-ebn-report search  --airiti-csv ` — 讀取標題/作者/年份/期刊/DOI/摘要/類型
   - 自動偵測「學位論文」並固定 `StudyDesign.OTHER` + `OxfordLevel.IV`（學位論文未經同儕審查，不得提升等級）
   - 中文作者姓名（`張小明` 等純 CJK 字串）自動以前 2 字做 citekey surname，解決原先 `split()` 誤切問題
   - 匯出步驟：到 Airiti Library → 勾選文獻 → 書目管理 → 選 CSV 匯出 → 下載
   - 實作見 `clients/manual_import.py:_airiti_csv_to_records`

2. **Gordon 11 項功能性健康型態**：TWNA 個案報告／護理專案 `護理評估` 節的標準骨架。
   - 參考：`references/gordon-11-patterns.md`（11 項定義 + 主觀/客觀資料模板 + NANDA 診斷對照）
   - 撰寫 role：`prompts/section_writer_護理評估.md`，要求 LLM 逐項產出 S/O + 評估發現
   - Compliance：`_check_gordon_11_coverage` 掃 `護理評估` 節是否涵蓋 ≥ 9/11 項關鍵詞（彈性門檻，第 9 性-生殖可在急性/幼童情境略過）
   - 只對 `twna_case` / `twna_project` 類型觸發，reading/case 類型不強制

3. **AI 關鍵字調整（keyword tuner）**：PubMed 初次檢索若落在 100–1000「甜蜜區」之外，可選啟用一輪 LLM 調整。
   - 啟用：`ENABLE_KEYWORD_TUNER=1`（預設關）
   - 觸發條件：初輪 hits  5000（太寬）
   - 調整員：`prompts/keyword_tuner.md`（Haiku 等級，只改 Boolean 字串）
   - 決策：`pipeline/keyword_tuner.pick_better` 挑離甜蜜區較近的那一版；`SearchHistoryRow.note` 兩輪都記錄，審計可見
   - 上限 1 輪；第二輪仍超出就接受現況、不再呼叫 tuner（控成本）

**Audit Artifact Store（v0.7+）**：每個 run 在 `output//artifacts/` 留一整組中間產物供日後審查：

```
artifacts/
  _index.jsonl                  # append-only 所有 artifact 的紀錄（timestamp, category, path, meta）
  blobs/.txt            # 內容定址儲存（system prompt 60KB × 30 次只存 1 份）
  llm/___.json  # 每次 LLM 呼叫的完整記錄
  guardrails//_{before,after,summary}.json  # 每道 guardrail 的 before/after/summary
```

LLM record 含：呼叫者函式名（自動偵測 stack）、tier、model、backend（anthropic / claude_code）、duration_ms、system prompt hashes、user msg hash、response raw hash、response_parsed。Guardrail 紀錄讓「LLM 原始判讀 vs Python 覆寫後」兩個版本都保留。

實作見 `pipeline/audit.py`（`ArtifactStore`）與 `clients/audited.py`（`AuditedLLMClient`）。Orchestrator 在每個 phase 入口呼叫 `_bind_to_run(state)` 建立對應 run 的 store，LLM 與 guardrail 呼叫透明落檔。

Pipeline 最終輸出 **`-DRAFT.docx`**（Quarto → pandoc → DOCX，APA 7 CSL 引文排版），含搜尋歷程表、CASP 評讀表、PRISMA 風格流程圖、AI 協作聲明頁。若 `templates/reference.docx`（可選）存在，將做為樣式母本套用院內字型與樣式；否則以 pandoc 預設樣式輸出。

**倫理守則**（依 2026 年台灣護理學會與台灣實證護理學會規範；詳見 `references/ai-disclosure.md`）：
- **AI 可以完全生成草稿**，但**使用者必須 audit、揭露、承擔責任**
- CLI 啟動必須傳 `--i-accept-audit-responsibility` flag；未傳不執行
- Pipeline 自動附三份必要文件：**AI 使用揭露段落**（研究方法/致謝）、**Audit 責任聲明**（封面或末頁）、**Subagent 執行紀錄**（補充資料）
- 檔名預設帶 `-DRAFT`；使用者完成審稿並明確勾選「已審閱」後以 `render --final` 去除後綴
- AI 不得列為作者；揭露段落須載明工具名稱、模型、版本、具體使用方式

## 使用這份技能的流程

根據使用者所處的階段，以下列次序提供協助：

### 情境 A：使用者還在選題

先讀 `references/topic-selection.md`，幫使用者判斷題目可不可行。避免五大地雷主題（文獻極少、爭議太大、倫理敏感、無法操作、不是護理專業範疇）。

**本階段 dispatch**：題目守門員（Subagent 1）→ CP1。

### 情境 B：使用者已有題目，要設 PICO

讀 `references/pico-and-search.md`，套用 PICO 結構，注意：
- **中英並列**（審查者要看英文關鍵字）
- 標明**問題型態**（治療型 Therapy / 傷害型 Harm / 診斷型 Diagnosis / 預後型 Prognosis）
- Outcome 盡量量化、可觀察

**本階段 dispatch**：PICO 建構員（Subagent 2）→ CP2。

### 情境 C：要做文獻搜尋與評讀

讀 `references/pico-and-search.md`（搜尋策略）與 `references/appraisal-tools.md`（評讀工具與證據等級）。

關鍵提醒：
- **搜尋歷程要可重現**：資料庫、關鍵字、布林邏輯、**欄位碼**、Limits、起始篇數、**去重後篇數**、排除條件、納入篇數全部要交代
- **六件套搜尋策略**：主詞 / 同義字 / MeSH / CINAHL Heading / Boolean / 欄位碼
- **初始篇數以 100–1000 為甜蜜區**，不在此範圍記錄迭代調整
- **引文追蹤**：正向（Google Scholar「Cited by」）+ 反向（reference list）皆做過
- **DOI 逐篇驗證**（pipeline 自動走 CrossRef；手動可 `https://doi.org/`）
- **評讀工具對應研究設計**：RCT 用 CASP RCT、系統性回顧用 CASP SR、質性研究用 JBI
- **證據等級依 Oxford 2011 準則**

**本階段 dispatch**：搜尋策略師（3）→ CP3 → CP4 → CASP 評讀員 × N 並行（4）→ CP5。

### 情境 D：要把實證結果用到個案（案例分析核心）

讀 `references/case-report-template.md`。注意護理報告獨有的要求：
- 要有**護理師原話**的直接引語
- 要有**個案/家屬原話**的直接引語（用引號）
- 要有**具體時間點**的評估紀錄
- 結果要**客觀可測量** + **主觀感受**並陳
- 個案資料**必須已去識別化**（姓名、病歷號、身分證字號全去除）才能進入此階段

**本階段 dispatch**：綜整整合員（5）→ CP6 → 個案敘事員 + 應用審計員（9、10）並行 → 分節撰寫員 × 6 並行（6）→ CP7。

### 情境 E：要寫結論與討論

讀 `references/phrasing-bank.md`。結論段的標準動作：
1. 回應 PICO 的結論
2. 承認研究限制
3. 本地脈絡考量（**不能貿然全面推翻護理常規**）
4. 對未來臨床與教育的建議

**本階段 dispatch**：分節撰寫員（6，結論節）→ 語氣守門員 + APA 7 格式員（7、8）並行 → CP8 → Quarto render → CP9。

## 寫作風格的核心守則

台灣實證護理報告有一套非常固定的「腔調」，不符合會被當成外行。核心原則：

**自稱用「筆者」**，不用「我」。

**個案不叫「病人」**，叫「個案」或「案○」（案母、案父、案兄等）。

**動詞偏書面語**：
- 不寫「我找了幾篇文章」→ 寫「運用實證方法檢索相關文獻」
- 不寫「病人說他不想躺」→ 寫「個案主訴無法配合長時間平躺」
- 不寫「我覺得應該這樣做」→ 寫「綜整實證結果，建議⋯⋯」

**引用文獻中文在前、英文在後**，依 APA 第 7 版格式。中文依姓氏筆劃、英文依字母排序。

**盡量引用近 5 年文獻**，除非是重要的經典研究。

更多句型範例見 `references/phrasing-bank.md`。

## 審查通過率最高的寫作策略

根據歷年通過的範本歸納，以下做法最能提升通過率：

1. **題目要具體而不宏大**。「如何減少術後感染」會被退，「在腹部手術後成人，嚼口香糖與一般照護對恢復腸蠕動之效果比較」才會過。

2. **搜尋歷程越透明越好**。表格呈現：資料庫 / 關鍵字 / 初始篇數 / 排除條件 / 納入篇數。

3. **至少納入 2–4 篇高證據等級文獻**。Oxford Level I–II（RCT、SR、MA）為主。若文獻極少，可放寬到觀察型研究，但要在討論段說明。

4. **CASP 評讀表要完整附上**，不能只寫「本文獻效度尚可」這種含糊語言。

5. **案例分析要有真實的應用記錄**。審查者最討厭看到「計畫要做但沒做」或「應用結果與文獻完全一致」這種過度完美的敘述。有偏差才合理，偏差要能解釋。

6. **討論段要體現反思**。不要只說「實證結果很棒，以後都這樣做」。要承認在地限制、機構文化、個別差異。

7. **AI 協作的新規範（2026 版）**：台灣護理學會與台灣實證護理學會已明文允許**使用生成式 AI 輔助寫作**，條件是：
   - AI 不得列為作者
   - 必須在研究方法或致謝段**主動揭露** AI 工具名稱、版本、具體使用方式
   - 作者必須**逐節審閱與修訂** AI 產出之內容
   - 作者必須聲明「已審閱並修訂 GenAI 產出之內容，並對本文內容的真實性與準確性承擔全部責任」
   - 建議將 AI 輔助生成的部分作為補充資料一併提交

   換句話說：**AI 可以幫你把糊的題目變好題目、生成完整草稿**，但**你必須讀過、改過、簽名負責**。這份技能的目標就是提供符合此規範的 AI 協作 pipeline（詳見 `references/ai-disclosure.md`）。

## 常見陷阱與錯誤

- **PICO 的 Comparison 寫錯**。Comparison 不是「無介入」，而是「現行照護標準」或「另一種介入」。
- **把實證讀書報告寫成一般文獻回顧**。讀書報告要評讀、要綜整、要有結論建議，不是單純摘要文獻。
- **證據等級亂標**。Oxford 2011 版是目前主流，不要用舊版 1–4 級。
- **CASP 表直接打勾沒說明**。每題都要寫簡短說明，特別是「不清楚」的項目。
- **個案資料暴露**。姓名、病歷號、具體身分特徵一定要去識別化。
- **參考文獻沒用 APA 第 7 版**。2020 年後一律用 APA 7，不要用 APA 6。

## 參考文件索引

本技能附帶以下 reference 檔案，視需要載入：

- `references/case-report-template.md` — 實證案例分析完整模板（最常用）
- `references/reading-report-template.md` — 實證讀書報告模板
- `references/pico-and-search.md` — PICO 設定與文獻搜尋策略（含六件套、欄位碼、100–1000 校準、引文追蹤、DOI 驗證）
- `references/appraisal-tools.md` — CASP 評讀表與 Oxford 證據等級
- `references/phrasing-bank.md` — 台灣護理報告標準句型庫
- `references/topic-selection.md` — 選題指引與地雷主題
- `references/subagent-roles.md` — 10 個 subagent 分工與輸入/輸出契約（Python pipeline 對應）
- `references/ai-disclosure.md` — 2026 版台灣護理 AI 使用規範與揭露/Audit/Subagent 紀錄的三份模板
- `references/gordon-11-patterns.md` — Gordon 11 項功能性健康型態（TWNA 護理評估節標準骨架）

看到使用者的需求後，**先決定要讀哪幾份 reference**，不要全部塞進脈絡。

## 最終輸出

完成草稿後，提供：

1. **完整的報告文件**（建議用 .docx 格式，因為醫院多半要求紙本交件）
2. **獨立的參考文獻清單**（方便檢查 APA 格式）
3. **搜尋歷程的表格**（方便附錄）
4. **CASP 評讀表**（方便附錄）

如果使用者還需要投影片版本（口頭報告用），提供 15 分鐘簡報的綱要：臨床情境 2 min → PICO 與搜尋 3 min → 證據摘要 5 min → 應用結果 4 min → 結論建議 1 min。

---

記住：**這份技能的價值在於讓 AI 與人類護理師合作產出可通過審查的實證報告**。依 2026 年台灣護理學會與台灣實證護理學會規範，AI 可協助生成完整草稿；人類護理師以 HITL checkpoint 逐節 audit、修訂、加入個人臨床觀察、簽名負責。最終送審文件需附 AI 使用揭露段落與 Audit 責任聲明（詳見 `references/ai-disclosure.md`）。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [htlin222](https://github.com/htlin222)
- **Source:** [htlin222/zh-ebn-report-skill](https://github.com/htlin222/zh-ebn-report-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-htlin222-zh-ebn-report-skill-zh-ebn-report
- Seller: https://agentstack.voostack.com/s/htlin222
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.