PI BLUEBOOK

繁體中文

简体中文

繁體中文

简体中文

外觀模式

MODULE 02 · STEP 06 · 可練習

檔案與工作目錄 ​

第一個任務能順利完成，有一個容易被忽略的前提：你先進入了 pi-practice 目錄，然後才啟動 Pi。對 Agent 來說，當前工作目錄影一張攤在桌上的工作區域，它幫助 Pi 理解相對路徑和專案上下文。

工作目錄不是安全隔離

Pi 的工具仍然以當前使用者權限執行，技術上可以存取當前目錄以外的位置。專用練習目錄能讓範圍更清楚，但不代表已經進入沙箱。

先看懂路徑 ​

在普通終端機裡執行：

bash
pwd

pwd 會告訴你當前所在的目錄。例如：

text
/Users/你的使用者名稱/Downloads/pi-practice

路徑就是檔案在電腦上的位置。/ 用來分隔一層層資料夾，~ 則是你的使用者主目錄的簡寫。~/Downloads/pi-practice 和上面那條完整路徑通常指向同一個位置。

Windows 使用者繼續使用 Git Bash；你的練習目錄寫作 ~/pi-practice，pwd 通常顯示 /c/Users/你的使用者名稱/pi-practice。不要把 Git Bash 中的 / 改成 Windows 資源管理器使用的反斜槓。

執行 ls 可以檢視當前目錄裡有什麼。執行 cd 目錄名 可以進入另一個目錄。這三條命令已經足夠支撐新手的前幾次練習。

先確認位置再啟動

不要在主目錄、整個下載目錄或重要專案的上層目錄直接練習。先建一個專用資料夾，執行 pwd 檢查，再輸入 pi。

@檔案 解決什麼問題 ​

在 Pi 的輸入區輸入 @，可以搜尋當前專案中的檔案。選中後，輸入區會保留這次訊息的明確檔案引用；這不等於 Pi 已經自動讀完，更不代表你可以跳過後面的讀寫記錄與結果核對。

這裡的完整操作是：

  1. 確認 Pi 底部的編輯區可以輸入。
  2. 輸入 @，再繼續輸入 專案會議。
  3. 在出現的檔案清單中，用上下方向鍵選中 input/專案會議記錄.md。
  4. 按 Return 確認。輸入區中保留了這個檔案引用，才繼續寫後面的任務。

在 Pi 編輯區輸入檔名並看到真實候選路徑

這張圖停在提交前。輸入區裡仍是搜尋文字，下面已經出現 input/專案會議記錄.md 候選；先核對右側相對路徑，再按 Return 選中。候選出現只證明 Pi 找到了檔案，不能證明它已經讀取內容。

如果輸入 @ 後沒有出現檔案清單，先用 /quit 退出 Pi。在普通終端機執行 pwd 和 ls input，確認你在正確練習目錄，且檔案確實存在，再重新啟動 Pi。

比如，你可以輸入：

text
請閱讀 @input/專案會議記錄.md，
把行動項整理到 output/行動清單.md。
不要修改原文。

這比“看一下那份會議記錄”更可靠。它減少了檔案同名、材料選錯和路徑理解不一致的機會。Pi 也支援在啟動時把 @file 作為檔案引數傳入，但新手先在互動介面裡使用 @ 即可。

實作：用明確檔案生成第二份結果 ​

開始前應已經完成第 5 課，input/專案會議記錄.md 和 input-before.sha256 都存在。先在普通終端機執行：

bash
cd ~/Downloads/pi-practice
pwd
shasum -a 256 -c input-before.sha256
test -f input/專案會議記錄.md && echo "PASS: 輸入存在"

Linux 和 Windows Git Bash 把第一條指紋檢查替換為 sha256sum -c input-before.sha256；Windows 同時把 cd 路徑換成 ~/pi-practice。

如果練習目錄不是 pi-practice，替換成你記錄的實際名稱。指紋不是 OK、輸入不存在，或 pwd 位置不對時都不要繼續；回到第 5 課的乾淨材料。

啟動 Pi，在編輯區用 @ 選擇 input/專案會議記錄.md，然後提交：

text
材料：@input/專案會議記錄.md
處理：只提取三個截止日期，按從早到晚排序，並保留對應負責人
輸出：output/截止日期索引.md
限制：不要修改 input，不要覆蓋已有的 output/行動清單.md；原文沒有的資訊寫“未知”
驗收：輸出必須恰好三項，並報告實際讀取和寫入的路徑

觀察實際讀寫路徑。如果出現另一個同名檔案、準備寫入 input，或輸出路徑不是 output/截止日期索引.md，立即中止並核對工作目錄。若輸出目錄不存在，退出 Pi，在普通終端機執行 mkdir -p output 後再重試；不要臨時改成一個自己也找不到的位置。

用四句話寫清任務 ​

不知道怎麼下指令時，就按這個順序寫：

  1. 材料在哪裡。
  2. 要進行什麼處理。
  3. 結果要放在哪裡。
  4. 哪些事不允許做，結果怎樣才算透過。
text
材料：@input/專案會議記錄.md
處理：提取事項、負責人、日期和風險提醒
輸出：output/行動清單.md
限制：不修改 input，輸出必須包含原文的 3 個事項

別忘了專案上下文檔案 ​

除了你用 @ 明確引用的材料，Pi 預設還會從當前目錄向上查詢 AGENTS.override.md、AGENTS.md 和 CLAUDE.md，也會讀取使用者級 ~/.pi/agent/AGENTS.md。它們用於提供專案規則，並不是你這條訊息裡手動附加的普通材料。

面對陌生倉庫時，要把這些檔案也列入檢查範圍。需要一次啟動完全忽略上下文檔案，可在普通終端機使用：

bash
pi --no-context-files

自動發現位置中的上下文檔案發生變化後，可以在 Pi 中用 /reload 重新載入。--no-context-files 只是關閉這類說明檔案，不會限制內建工具的檔案權限，也不是沙箱。

完成後的最小檢查 ​

退出 Pi 或開啟新的終端機視窗，先確認位置，再查檔案。

bash
cd ~/Downloads/pi-practice
pwd
ls input output
shasum -a 256 -c input-before.sha256
test -f output/截止日期索引.md && echo "PASS: 日期索引存在"
sed -n '1,80p' output/截止日期索引.md

Linux 和 Windows Git Bash 同樣把 shasum -a 256 -c 替換為 sha256sum -c；Windows 的 cd 路徑仍使用 ~/pi-practice。

如果你在第 1 課使用了 pi-practice-2 或其他名字，這裡和後續課程的 pi-practice 都要替換成你實際記下的練習目錄名。

你至少要能回答三個問題：Pi 讀了哪個檔案，寫了哪個檔案，原文是否仍然保留。日期索引還應恰好包含小林、2026-08-28；小周、2026-08-30；小陳、2026-09-01，順序從早到晚。等這些邊界穩定下來，再讓任務變複雜。

本課驗收 ​

  • @ 引用在提交前指向正確的 input/專案會議記錄.md。
  • 實際讀寫記錄沒有出現意外目錄，也沒有覆蓋上一課的行動清單。
  • 輸入指紋仍顯示 OK，新輸出存在且三項日期、負責人、順序正確。
  • 出現同名檔案、錯誤路徑或輸入修改時，你知道先停止並回到普通終端機核對，而不是繼續猜。

本章依據 ​