audiology_taiwan Skill

共享 Skill 套件的原始碼與分發來源 repo。

概述

本專案統一管理 AI Agent 所需的 AGENTS.md、skills/、模板與 CLI，讓跨專案、跨電腦的 Skill 分發、升級與診斷有一致標準。

• 原始碼管理：GitHub repo 作為唯一 source of truth
• 版本化分發：透過 npm 發布 yoz_agent_cli
• 多 Agent 掛載：共用根目錄 AGENTS.md，Skill 同步到 .agent/skills/ 與 .codex/skills/
• 低門檻使用：以 npx 完成初始化、升級與檢查

目前官方隨附 Skills

• security-standards：資安開發規則基準
• security-scan：Skill / 專案目錄靜態資安掃描
• hearing-xml-normalization：固定聽力 XML schema 正規化
• hearing-report-rendering：聽圖、報告與匯出渲染
• hearing-report-from-xml：串接 XML 正規化到最終報告的整體流程

使用者快速開始

新專案初始化

npx yoz_agent_cli@latest agent init

初始化後，專案內會建立：

AGENTS.md
.agent-source/
.agent/skills/
.codex/skills/
.agent-skill.json

只同步特定 Agent 掛載點

npx yoz_agent_cli@latest agent init --agent agent
npx yoz_agent_cli@latest agent init --agent codex

升級既有專案

npx yoz_agent_cli@latest agent upgrade

若只升級特定掛載點：

npx yoz_agent_cli@latest agent upgrade --agent codex

檢查安裝狀態與漂移

npx yoz_agent_cli@latest agent doctor

預覽變更但不寫檔

npx yoz_agent_cli@latest agent init --dry-run
npx yoz_agent_cli@latest agent upgrade --dry-run

upgrade 結果判讀

• Already up to date：目前專案與執行中的 CLI 版本內容一致，沒有實際變更
• Upgrade applied successfully：已有新內容被寫入專案
• Dry run: ...：只預覽結果，不會真的寫檔

JSON 輸出另外會提供：

• outcome：例如 already_up_to_date、changes_applied
• summary：列出 created / updated / skipped / backups / warnings 數量

既有專案中的覆蓋規則

在已有檔案的專案中執行 agent init 或 agent upgrade 時，CLI 依以下規則處理：

1. 檔案不存在：直接建立
2. Markdown 檔案已有受管標記：只更新受管區域
3. 檔案已存在但沒有受管標記：中止並回報衝突
4. 使用 --force：先備份，再覆蓋受管理的 skills 檔案；AGENTS.md 仍保留局部合併與衝突保護

對於已有受管區塊的 Markdown，若本地改動只發生在託管範圍外，upgrade 會保留這些內容，不會因整檔 hash 差異而直接阻擋。

受管區塊

<!-- agent:begin managed:skills-index -->
- Skill A
- Skill B
<!-- agent:end managed:skills-index -->

受管 frontmatter

---
managed_by: yoz_agent_cli
managed_version: 0.1.0
managed_blocks:
  - skills-index
---

只有受管區塊與受管欄位會被 CLI 更新，標記外內容一律保留。

doctor 狀態說明

• ok：受管理檔案與記錄一致
• warning：中央來源 .agent-source/ 發生漂移或缺檔
• issues：共享檔案或掛載點發生漂移、缺檔或其他阻擋問題

常見情況：

• 手動改了 .agent/skills/*：doctor 會回報 issues
• 手動改了 .agent-source/*：doctor 會回報 warning
• .agent-skill.json 損壞或不是合法 JSON：doctor 會回報 issues，並明確指出 state file 狀態
• upgrade 遇到掛載點漂移：預設阻擋
• upgrade --force：建立 .agent-backup/ 後覆蓋受管理的 skills 檔案；不直接整份覆蓋 AGENTS.md

本地開發

環境需求

• Node.js >=20
• npm >=11

本地執行

node .\bin\agent.js --help
node .\bin\agent.js init --dry-run
node .\bin\agent.js doctor

或使用 package script：

npm run agent -- --help
npm run init:dry
npm run doctor

測試

npm test

目前測試涵蓋：

• 空專案初始化
• --agent agent / --agent codex
• --dry-run
• 初始化冪等性
• 無受管標記衝突阻擋
• doctor 的 mount/source 漂移分級
• upgrade --force 技能覆蓋與備份流程
• Markdown 受管區塊與 frontmatter 更新

專案結構

audiology_taiwan Skill/
├── AGENTS.md
├── README.md
├── bin/
├── docs/
├── skills/
├── src/
├── test/
└── test-support/

文件索引

| 文件 | 說明 | |---|---| | AGENTS.md | 共享 Skill 套件治理規則 | | 技術決策 - Skill 分發與同步策略 | 分發架構與決策背景 | | CLI 規格草案 - yoz_agent_cli | init / upgrade / doctor 規格 | | Implementation Tasks - yoz_agent_cli | 實作任務分解與里程碑 | | 發版流程 - yoz_agent_cli | npm publish、semver、release checklist | | Skill 編寫規範 | Skill 結構與撰寫規則 |

常見問題

為什麼 AGENTS.md 只有一份？

因為不同 Agent 共用同一份治理規則。第一版的差異只存在於各自的 skills/ 掛載點。

為什麼 .agent-source/ 也要存在？

.agent-source/ 是中央來源，CLI 先把 Skill 寫到這裡，再同步到 .agent/skills/ 與 .codex/skills/。

什麼是漂移？

漂移代表受管理檔案已經偏離 CLI 上次安裝或升級時記錄的內容。CLI 透過 managedFileHashes 比對這件事。

如果 init 或 upgrade 報衝突怎麼辦？

先跑：

npx yoz_agent_cli@latest agent doctor

確認哪些檔案已被手動修改。若確定要覆蓋，再使用：

npx yoz_agent_cli@latest agent upgrade --force

注意：

• --force 只作用在 skills/ 同步鏈上，包括 .agent-source/skills/、.agent/skills/、.codex/skills/
• AGENTS.md 仍優先走受管區塊 / 受管 frontmatter 合併
• 若 AGENTS.md 發生無法合併的衝突，即使帶 --force 也會中止，避免覆蓋專案自訂規則

語言規則

• 所有說明文件與交付摘要使用繁體中文
• 程式碼、檔名、frontmatter key、CLI 指令與 package 名稱可保留英文