Maintenance

維護指南

本頁說明維護 meta-pipe 的日常任務：環境、測試、依賴、發版與慣例。逐步的流程操作指令請見各 ma-*/SKILL.md。

---

環境設定

情境	指令	時間
首次設定	bash setup.sh	30–60 分鐘（一次性）
隨時驗證	bash verify_environment.sh	約 2 分鐘
詳細說明	見 ENVIRONMENT_QUICK_START.md	—

語言與套件管理慣例

• Python：一律 uv run，不要直接呼叫 python3。新增依賴用 uv add <package>（在 tooling/python/），並確認 uv lock 已更新。
• R：install.packages() 後於專案根目錄執行 renv::snapshot() 鎖定版本。
• API keys：從 .env 讀取，範本見 .env.example 與 ma-search-bibliography/references/api-setup.md。
• 刪除檔案：使用 rip，不要用 rm（避免誤刪、可還原）。
• 保留 rounds：所有 round-XX 資料一律保留，永不覆寫。

---

測試

Python 測試套件位於 tests/。

cd /Users/htlin/meta-pipe/tooling/python
uv run pytest                      # 全部測試
uv run pytest tests/test_xxx.py    # 單一檔案
uv run pytest -k "keyword"         # 依關鍵字篩選

維護原則：

• 修改工具腳本的輸出 schema（例如 project_status.py 檢查的檔案結構）時，同步更新對應 fixture。近期就有 test_project_status.py 因 04_fulltext/manifest.csv schema 變更而需修 fixture 的案例（見 CHANGELOG「Unreleased」）。
• 保持 pytest 無 DeprecationWarning。近期已將 13 個檔案、29 處 datetime.utcnow() 換成 timezone-aware 的 datetime.now(timezone.utc)，並保留輸出字串形狀（...Z 結尾）。新程式碼請沿用此慣例。

---

品質檢核工具

Stage 09 的品質工具可獨立執行，維護時也可用來 smoke test：

工具	用途
publication_readiness_score.py	客觀 0–100% 投稿就緒分數（8 個構面）
validate_nma_outputs.py	NMA 專屬驗證（7 項檢查）
claim_audit.py	過度宣稱偵測（12 種樣式）
validate_pipeline.py	全流程完整性檢查，支援 --json 與 strict/draft 模式
project_status.py	專案階段狀態總覽（--verbose）

---

專案狀態與續作

協助使用者「continue」或「status」時的標準流程：

cd /Users/htlin/meta-pipe/tooling/python

# 1. 檢查專案狀態
uv run project_status.py --project <project-name> --verbose

# 2. 顯示上次工作階段摘要
uv run session_log.py --project <project-name> resume

# 3. 找最新的 NEXT_STEPS 檔
ls -t projects/<project-name>/NEXT_STEPS_*.md | head -1

品質模式（strict vs draft）

init_project.py --mode {strict,draft} 決定專案品質模式，寫入 .ma_meta.json（單一事實來源，由 project_meta.py 讀取）：

• strict：validate_pipeline.py 把未通過項目視為 FAILURE（exit 2）。
• draft：視為 NOTE（exit 0），並產生 DRAFT_MODE.md 標示為不可投稿的快速原型。

---

發版與 Changelog

• 所有變更記錄在 CHANGELOG.md，採 Keep a Changelog 風格：Added / Changed / Fixed，未發布內容置於 [Unreleased]。
• 提交規範：不要 auto-commit；由維護者明確要求時才 commit。commit 前先 Read 目標檔。
• PR 對應 issue 時，在 CHANGELOG 標註 issue 編號（例如 (#38)）。

---

Agent Teams（實驗性）

多個 Claude Code 實例平行協作於同一專案。

• 啟用：在 .claude/settings.local.json 設 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（需 Claude Code v2.1.32+）。
• 產生 spawn prompt：

  uv run tooling/python/team_spawn_helper.py --project <name> --role <role> [--list]

• 角色與檔案所有權對照表見 AGENTS.md（root）。每個 teammate 只寫入自己負責的目錄，避免跨 teammate 寫入衝突。

---

Claude CLI 相依性注意事項

• AI 篩選（ai_screen.py）需要 claude CLI ≥ 2.1.100，且支援 --bare 與 --output-format flag；啟動時會以 _assert_claude_cli() 檢查。
• 設有 ANTHROPIC_API_KEY 時，改用 claude -p --bare --output-format json，每次呼叫 input token 從約 10k 降到約 1.5k；僅有 OAuth 時 fallback 到 non-bare 並印一次性警告。
• 詳見 tooling/python/CLAUDE_CLI_FLAGS.md。

---

常見維運檢查清單

• verify_environment.sh 全綠
• uv run pytest 全過、無 DeprecationWarning
• uv lock 與 pyproject.toml 一致
• R 端 renv::status() 無漂移
• 新增腳本／模組後執行 /module-management 驗證 registry
• CHANGELOG 的 [Unreleased] 已更新