Tutorial 2 How the Code Works zh HK

教程 2 · 程式碼如何工作

🌎 語言： 繁體中文（香港） — 查看全部 33 種語言

目標： 理解幾項讓專案容易且安全地交給 AI 智能體修改的設計選擇。無需背下程式碼， 只要建立足夠清晰的心智模型，便能精確指導智能體。

← 上一章：教程 1：入門 · 下一章： 教程 3：你的第一個智能體任務

---

專案地圖

lockedin-cli/
├── bin/lockedin.js      # 進入點——唯一負責輸入/輸出的部分
├── src/lockedin.js      # 核心——傳回字串的純函式
├── test/
│   ├── unit.test.js     # 直接測試核心函式
│   └── cli.test.js      # 啟動真實二進制檔案並檢查輸出
├── tools/screenshot.js  # 渲染 docs/ 中的 SVG
└── package.json         # 元資料 + `npm test` 指令碼

四個概念驅動整個專案。掌握它們，你就能放心要求智能體完成幾乎任何改動。

概念 1 —— 傳回字串的純函式核心

打開 src/lockedin.js。渲染函式不會輸出，而是傳回字串：

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...構建行陣列...
  return out.join('\n');   // 傳回文字，不輸出
}

真正的輸出和按鍵讀取都在 bin/lockedin.js 中完成。“核心傳回資料，邊緣處理 I/O” 是這裏最重要的拆分方式，因為只傳回字串的函式非常容易測試：

const out = app.renderConnect();
assert.ok(out.includes("“很想把你加入我的professional network。”——發送給"));

無需模擬終端機，也無需捕獲 stdout。因此，當你讓智能體加入功能時，它也能快速加入可靠測試。

概念 2 —— 內容池

笑話保存在 src/lockedin.js 頂部附近的普通陣列中：

const HOOKS = [ '一個不太主流的觀點：', '讓這句話沉澱一下。', /* ...約 25 項... */ ];
const LESSONS = [ '→ 你的人脈，就是你的淨值。', /* ... */ ];

生成器從這些池中抽取內容。在 v1.2.0 中，每個池增長到約 25 種變化，還加入了第二層 模板池（例如 POST_REVEALS 和 REFLECT_TAGSETS），讓每次輸出的結構也變化， 而不只是替換詞語。加入內容通常只需向陣列加字串，是非常適合交給智能體的第一個任務。

概念 3 —— 帶種子的隨機性 = 可重複的測試

隨機輸出似乎與自動化測試衝突。本專案用可設種子的隨機數生成器解決：

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → 相同種子，相同帖文

所有隨機選擇都通過共享的 pick() / shuffle() 助手，從帶種子的生成器取值。 設定 LOCKEDIN_SEED=42 後，CLI 輸出可完全重現。任何改動都必須遵守黃金規則： 新增隨機性只能使用 pick / shuffle，絕不能直接使用 Math.random，否則確定性和測試都會失效。 請記住這點；第 3 章要提醒智能體。

概念 4 —— 兩層測試

• test/unit.test.js 直接呼叫核心函式並斷言傳回字串，快速且精確。
• test/cli.test.js 真正啟動 bin/lockedin.js，檢查 stdout 和結束碼，證明端到端流程有效。

二者共同組成門禁，也編碼了應用的不變量。例如，帖文總以已知開場開頭，且至少包含 三個 → 教訓；“connect”介面總會出現 incalculable。智能體修改程式碼時，測試能捕獲 任何悄悄破壞承諾的行為。

---

為甚麼這對智能體協作很重要

四個概念結合後，智能體可以：

1. 把功能寫成傳回字串的純函式；
2. 無需復雜 I/O 模擬即可加入測試；
3. 通過帶種子的 RNG 保持輸出可重現；
4. 執行既有門禁，證明沒有破壞其他內容。

下一章會完整實踐這個循環。

✅ 和你的智能體一起試試

請智能體通過閱讀而非編輯來驗證你的理解：

1. “列出 src/lockedin.js 中所有內容池，以及每個池的條目數。”
2. “展示 test/unit.test.js 對 generatePost 強制執行的一條不變量，並解釋甚麼改動會破壞它。”
3. “帶種子的 RNG 在哪裏定義？哪些函式必須使用它而不是 Math.random？不要修改，只解釋。”

當它的回答與本章一致，你就可以開始構建功能了。

下一章：教程 3：你的第一個智能體任務 Y