Tutorial 2 How the Code Works zh

教程 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：你的第一个智能体任务