# 第 38 章 实战案例三：从零到部署的全生命周期（Guardian Notes）

## 本章目标

- **O1** 能够按真实转移条件排列“需求与蓝图”“实现与评估”“部署与接管”（产物：全生命周期证据链）
  - 证据: 全生命周期证据链按时间或状态顺序排列“需求与蓝图”“实现与评估”和“部署与接管”
- **O2** 能够构造全生命周期证据链，为每个状态或里程碑定义入口和出口（产物：全生命周期证据链）
  - 证据: 全生命周期证据链为三个节点分别写出入口、出口和责任人
- **O3** 能够把需求、蓝图、实现、评估、部署和接管串成证据链（产物：全生命周期证据链）
  - 证据: 产物逐阶段链接输入、版本、实际结果、门禁和接手者

## 学习路径

- **初学者**: 本章迁移任务是：能够把需求、蓝图、实现、评估、部署和接管串成证据链。先按图中的“状态转移”关系完成全生命周期证据链的第一项证据，再逐项核对责任人与判断标准。
- **有经验者**: 先用当前项目完成这一任务：能够把需求、蓝图、实现、评估、部署和接管串成证据链。提交全生命周期证据链后，再对照正文复核关系类型、缺失证据和授权边界。

## 教学图解

- **必交产物**: 全生命周期证据链
- **图解类型**: delivery-lifecycle
- **关系语义**: 节点沿时间或状态从左向右推进；只有满足出口条件才能转移，时间经过本身不构成完成。
- **核心概念**: 需求与蓝图 · 实现与评估 · 部署与接管

![第 38 章全生命周期证据链教学图](/learning/diagrams/zh/chapter-38.svg)

按入口与出口条件阅读全生命周期证据链，避免把日期到达误当成阶段完成。

图沿水平轴依次放置“需求与蓝图”“实现与评估”“部署与接管”。连线表示时间或状态转移，但只有当前节点的出口证据齐全才能进入下一节点；日历时间经过不自动触发转移。

> **公开课程改编版。**正文依据内部教材整理，保留概念、流程与示范。案例规模、用时、提升比例及目标阈值均用于教学，不是本站交付成果或通用标准。工具、平台与技能描述需在实际环境核验。提示词不能授予权限；重试次数不自动触发恢复；恢复须先保护工作并确认目标、共享状态和外部数据影响。

## 课程讲解

### 38.1 阶段一：文档先行，建立约束层

项目背景：一个安全的、跨平台的、支持离线使用的笔记应用——"Guardian Notes"（教学重组案例：情节由真实项目的典型片段重组而成，数字为演示量级）。它集合了多种常见技术难题：

> 产品经理的原始需求："我们要做一款笔记应用，用户可以在上面写私密的日记、备忘录。我们最大的卖点是'安全'和'随处可用'：1. 绝对安全——用户的笔记内容必须在他们自己的设备上加密，就算服务器被黑，黑客也拿不到任何有意义的内容；2. 跨平台——必须能在 Web 浏览器、桌面应用（Windows, macOS）上使用；3. 离线优先——没网也能查看、创建和编辑笔记，有网后自动同步；4. 基本功能——支持 Markdown、按文件夹组织笔记。"

这个案例的"魔鬼之处"：跨平台（Web + Desktop）——处理不同运行环境的差异，是"环境约束"的绝佳演练场；离线优先（Offline-First）——在本地持久化数据并处理复杂的数据同步和冲突解决逻辑；端到端加密（E2EE）——极其严肃的安全需求，加密逻辑一旦出错后果是灾难性的。

技术栈：核心逻辑 TypeScript（一份代码多处运行）+ Web 端 React + 桌面端 Electron + 本地存储 IndexedDB（Dexie.js）+ 云端同步 RESTful API（简化）+ 加密库 libsodium-wrappers。

阶段一：文档先行，建立约束层。

目标：在编写任何一行应用代码之前，先用文档为 AI 和我们自己构建起坚不可摧的"思想护栏"。这是架构约束的集中体现。

行动：在项目根目录创建 CONTEXT.md，另在 .docs/ 创建三份配套文件，按第 12、13 章分工。下面保留案例三层设计，但把事实与约束分别落盘。

先创建 CONTEXT.md（项目蓝图）：

<!-- code-example:chapter-38-E1 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```markdown
## Guardian Notes — CONTEXT
目标：安全、跨平台、离线可用的 Markdown 笔记，支持文件夹与恢复联网后同步。
技术栈：TypeScript、React、Electron、Dexie.js、RESTful API、libsodium-wrappers。
理由：复用核心逻辑，通过适配器隔离平台差异；本地存储支持离线工作。
三层事实：
1. Core Logic：平台无关的 TypeScript 业务与加密模块。
2. Platform Adapters：连接核心逻辑与 Web/Electron 运行环境。
3. UI Layer：消费适配器的 React 组件。
数据模型、API 契约和目录：调研后在本文件补齐并批准，不在宪法复制。
首个里程碑：加密模块接口与测试；后续为本地读写、平台集成及同步。
实施约束：ARCHITECTURE.md。
行为准则：AGENTS.md。
```

蓝图中的待定契约必须在对应实施前补齐；以上摘录不是跳过调研的许可。

① 创建 .docs/AGENTS.md（AI 行为准则）：

<!-- code-example:chapter-38-E2 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```markdown
## AI Agent Directives: Project "Guardian Notes"
## Persona: Senior Security-Focused Engineer
You are to act as a Senior Software Engineer with a specialization in security.

## Reading and Enforcement:
1. Read project facts and goals.
2. Read implementation constraints and cite applicable rule IDs.
3. Read verified progress before selecting the next task.
4. Report conflicts or unknown security assumptions before implementation.
5. Do not weaken constraints to obtain a passing result.
```

② 创建 .docs/ARCHITECTURE.md（架构宪法 + 负空间红线）：

<!-- code-example:chapter-38-E3 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```markdown
## "Guardian Notes" - Architecture Document (v0.1)
## 1. Project Facts
See CONTEXT.md for goals, stack, three layers, models and contracts.
CONTEXT.md links back to .docs/ARCHITECTURE.md. Do not duplicate those facts here.

## 2. Red Lines and Review Triggers
- G1: Treat user-data changes as security-critical; review before implementation.
- G2: Do not break offline behavior or supported-platform compatibility.
- G3: Prefer simple auditable code; review complexity before adding abstractions.
- G4: Never treat the server as a trust anchor.
- G5: Do not disable TypeScript strict mode.

## 3. The "Forbidden Zone" (Negative Constraints) —— 负空间红线
- G6 — No Unencrypted Data on the Wire: 发送到服务器的任何数据都必须先加密。
- G7 — No Private Keys on the Server: 用户的主解密密钥绝不允许存在服务器上。
- G8 — Core Logic Cannot Access `window` or `document`: 核心逻辑必须平台无关。
- G9 — UI Components Cannot Perform Direct Data-Access: 所有数据操作必须通过 Core Logic。
```

③ 初始化 .docs/CHANGELOG.md（航行日志）：

<!-- code-example:chapter-38-E4 mode:reference -->
> **示例类型：参考。** 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。
```markdown
## Changelog
## Unreleased
- Decision: Established the initial project structure and core architectural principles.
- Next Step: Begin implementation of the "Core Logic" layer, starting with the encryption module.
```

阶段复盘：我们花了大约一个小时，没有写任何一行应用代码，但取得的成果是决定性的——设定了基调（通过 AGENTS.md 让 AI 知道这是一个严肃的安全优先项目）、建立了骨架（通过 CONTEXT.md 记录三层事实与选型理由，用 ARCHITECTURE.md 单独约束跨层访问）、划定了红线（通过负空间约束提前封死最可能导致项目失败的"捷径"）、明确了起点（通过 CHANGELOG.md 清晰知道下一步该做什么）。

心法："慢就是快"——花在文档上的 1 小时，往往能为后续省下远超于此的返工时间（"1 小时省 10 小时"是量级比喻，非测量值）。"先想好不做什么"——负空间约束，比正面描述功能更能体现架构的智慧。

### 38.2 阶段二：核心流程，"三步走"强制执行

目标：实现项目的核心功能——笔记的本地加密、存储和读取。在这个过程中严格执"调研 → 谋局 → 落地"的流程约束，强制"慢思考"。

场景：实现 EncryptionService，负责生成密钥、加密和解密文本。

第一步：调研（Research）。不能直接让 AI 写代码，先让它当"研究助理"（在保存状态后的新会话中先读取蓝图与三份配套文档）：

> [读取 CONTEXT.md、.docs/AGENTS.md、.docs/ARCHITECTURE.md、.docs/CHANGELOG.md]
> Acknowledge and internalize. Our next step is to implement the encryption module.
> Your Role: Act as the Senior Security-Focused Engineer defined in the agent directives.
> Task: We have decided to use libsodium-wrappers. Before we write code, conduct a brief research:
> 1. Key Derivation: What is the recommended function for deriving a strong encryption key from a user's password? What parameters (salt, ops-limit, mem-limit) are involved, and what are sane defaults?
> 2. Encryption/Decryption: What is the specific function for symmetric encryption using XChaCha20-Poly1305-IETF? What are the inputs (key, nonce, plaintext) and outputs? How should the nonce be generated and stored?
> Constraint: Do not provide a full implementation yet. Focus on background information and function signatures.

AI 会返回一份关于 `crypto_pwhash`（密钥派生）和 `crypto_aead_xchacha20poly1305_ietf`（加密）的、详尽的、带有安全警告的技术备忘录，解释"盐"（salt）和"随机数"（nonce）的重要性。

第二步：谋局（Strategizing）。基于研究结果，要求 AI 设计 EncryptionService 的"蓝图"（接口 + 实现策略注释 + 任务清单，没有方法体）：

> Task: 1. Define the Interface: Propose a TypeScript interface named IEncryptionService that exposes methods for: generating a new master key, deriving a key from a password, encrypting a string, decrypting a ciphertext.
> 2. Plan the Implementation: For each method, write a short comment describing its implementation strategy based on your research.
> 3. Task Breakdown: Create a sequential task list.
> Constraint: Provide only the interface, comments, and task list. No method bodies yet.

这个"谋局"过程，迫使我们思考模块的"公共契约"，而不是过早陷入实现细节。

第三步：落地（Implementation）。所有思考和设计完成后，进入"高速编码"阶段，逐一完成任务清单里的任务，并让 AI 为每个方法编写单元测试、确保覆盖率达标（质量约束初步介入）。

阶段复盘：我们抵制住了"直接让 AI 写加密代码"的诱惑。通过"三步走"，将一个复杂的、安全敏感的任务分解成可控、可审查的多个小步骤。最终得到的代码不是 AI"一拍脑袋"想出来的，而是我们和 AI 基于共同研究和设计深思熟虑后的产物，其可靠性远高于"一步到位"式的生成。

### 38.3 阶段三：环境调试，遥测日志攻克平台差异

目标：将核心逻辑集成到 Web 和 Electron 两个不同的平台，解决"环境依赖型"问题。这是环境约束的实战。

场景：在 Electron 桌面端发现笔记的保存速度偶尔变得极慢，甚至导致应用卡死；但同样的操作在 Web 端非常流畅。代码是同一份（Core Logic），不同环境表现天差地别。

错误的流程：对 AI 说"我的 Electron 应用很卡，Web 上却不卡，为什么？"——这是一个无法回答的问题，AI 只能靠猜。

正确的流程（遥测驱动）：

1. 植入遥测探针：在 Core Logic 的"保存笔记"流程中植入详细的结构化日志，覆盖关键阶段：SAVE_NOTE_STARTED → ENCRYPTION_STARTED → ENCRYPTION_FINISHED（记录耗时）→ LOCAL_DB_WRITE_STARTED → LOCAL_DB_WRITE_FINISHED（记录耗时）→ SAVE_NOTE_FINISHED（记录总耗时），日志包含 trace_id、时间戳、note_id 等上下文；
2. 在真实环境中取证：在 Electron 应用中打开开发者工具，执行几次缓慢的"保存"操作，从控制台复制完整的、JSON 格式的结构化日志流；
3. 逆向投喂日志：把日志流投喂给 AI（角色：精通 Electron 和浏览器存储的性能工程师），并给出关键问题："同一操作在 Chrome 里 DB 写入只要 100ms，为什么 Electron 里 IndexedDB 写入慢 80 多倍？（它们用同一个 V8 引擎）";
4. AI 的精准诊断：日志清晰地显示 8.5 秒耗时 99% 花在 LOCAL_DB_WRITE 上（加密很快）。AI 的知识库中有大量关于 Electron 和 Web 性能差异的知识——Electron 主进程和渲染进程虽然都用 V8，但底层 I/O 模型和磁盘交互方式与沙箱化的浏览器环境有本质区别。它提出极具洞见的假设："Electron 中频繁小批量地向 IndexedDB（底层是文件系统）写入，可能受主进程 I/O 瓶颈或杀毒软件实时扫描影响。Chrome 浏览器对此有更深度的优化。常见解决方案是把多次小写入批处理为一次大写入。";
5. 修复与验证：根据 AI 建议，使用 Dexie.js 的 `bulkPut()` API，把多个保存操作缓存起来一次性写入数据库。再次运行——Electron 端保存速度恢复到与 Web 端一样的毫秒级。

阶段复盘：面对"黑盒"环境问题，我们没有陷入猜测。我们用"遥测"将问题"数据化"和"可视化"，利用 AI 渊博的跨领域知识库对数据做出精准解读，找到了那个隐藏在平台差异中的"魔鬼"。

### 38.4 阶段四：重构优化，测试守住底线

目标：核心功能完成后进行"净化"，移除技术债务、优化结构，同时确保没有破坏任何现有功能。这是质量约束和定期垃圾回收的实践。

场景：NoteService.ts 在多次迭代后变得臃肿，混杂了数据操作、加密调用和初步的同步逻辑。我们想让 AI 重构它，拆分成更内聚的多个模块。

行动：

1. 建立"防退化"基线：功能防线——为 NoteService.ts 的所有公共方法编写 100% 分支覆盖率的单元测试（运行一遍全部通过，作为"功能正确性基线"）；性能防线——为最关键的 saveNote 和 loadNotes 函数编写基准测试，记录平均执行时间（作为"性能基线"）；
2. 授权 AI 进行"戴着镣铐的舞蹈"——下发防退化契约：

> Context: We need to refactor our NoteService.ts module. It has grown too large.
> Role: Senior Software Architect, obsessed with the Single Responsibility Principle (SRP).
> Task: 1. Propose a Refactoring Plan (split into NoteRepository.ts, SyncService.ts, etc.); 2. Execute after approval.
> ANTI-REGRESSION CONTRACT (ABSOLUTE & NON-NEGOTIABLE):
> 1. No Functional Regression: must pass all existing unit tests without modifying test files.
> 2. No Performance Regression: key operations must remain within 5% of baselines.
> 3. Clean Up: after refactoring, run ts-prune to remove now-unused helpers/imports.

3. AI 执行与自动化验收：AI 把 500 行的文件拆成 3 个 100 多行的新文件。验收三关：第一关单元测试（若有失败，把失败日志逆向投喂给 AI 自我修复）；第二关性能测试（若有退化，反馈给 AI 优化）；第三关垃圾回收（ts-prune 和 depcheck 清理死代码和孤儿依赖）。

阶段复盘：我们成功完成了一次复杂的、有风险的重构，但整个过程充满信心——信心不来自于对 AI 的"盲目信任"，而来自于我们建立的、自动化的、不可逾越的"质量电网"。重构的结果不仅是代码更清晰，我们还通过"垃圾回收"让代码库变得比重构前更小、更纯粹——实现了一次真正的"逆生长"。

### 【复盘】有效约束的完整闭环

| 阶段 | 核心任务 | 关键决策点/心法 | 约束体系 |
|------|---------|----------------|---------|
| 一：文档先行 | 建立共识，划定边界 | "慢就是快"：文档上的 1 小时节省远超于此的返工（"省 10 小时"为量级比喻）；"先想好不做什么"：负空间约束比正面描述更能体现架构智慧 | 架构约束 |
| 二：核心流程 | "三步走"强制执行 | 抵制"直接让 AI 写加密代码"的诱惑；把复杂安全任务分解为可控可审查的小步骤 | 流程约束 |
| 三：环境调试 | 遥测日志攻克平台差异 | 不靠猜测靠数据；用遥测把"黑盒"问题数据化，用 AI 跨领域知识解读 | 环境约束 |
| 四：重构优化 | 边做减法边用测试守住底线 | 测试电网是重构许可证；防退化契约让 AI"戴着镣铐跳舞"；垃圾回收实现"逆生长" | 质量约束 |

Guardian Notes 案例展示了"有效约束"的完整闭环：架构约束定方向（文档先行）、流程约束控节奏（三步走）、环境约束长眼睛（遥测驱动）、质量约束守底线（测试电网）。四类约束像一个全方位"护城河"，确保 AI 这头巨兽始终在你规划好的安全航道内行进。

---

<!-- cognitive-load-checkpoint -->
## 暂停整理：先完成本章最小闭环

先只写出“需求与蓝图”与“实现与评估”之间的一条关系，并把它填进全生命周期证据链。确认这一步有输入、判断和证据后，再加入“部署与接管”；三项尚未连通时，不进入独立练习。

## 独立练习

使用虚构或已获授权的脱敏材料，先独立作答，再查看参考。将产物保存为 `chapter-38.md`，写上版本、决定、证据和缺项。

为教学笔记应用画登录、解锁、编辑、离线、同步状态图。写威胁模型和密钥边界，设计冲突及重试检查。

<!-- chapter-artifact-requirement -->
### 本章必交产物：全生命周期证据链

以下证据必须出现在本次独立练习的提交物中；正文原有问题用于提供内容，不能替代这些验收项。

- O1: 全生命周期证据链按时间或状态顺序排列“需求与蓝图”“实现与评估”和“部署与接管”
- O2: 全生命周期证据链为三个节点分别写出入口、出口和责任人
- O3: 产物逐阶段链接输入、版本、实际结果、门禁和接手者

<details>
<summary>查看参考反馈（先独立作答）</summary>

## 参考反馈

把‘绝对安全’改为明确攻击者、保护资产与限制；使用经审查的标准密码库，不自造算法或记录密钥。离线操作需标识、幂等和冲突处理，平台错误靠脱敏最小复现。生命周期演练不等于正式安全审计或真实部署证明。

### 自评与下一步

对照本章目标检查：决定是否明确，依据是否能复现，未知项是否如实记录。参考给出一种判断方式，不是唯一答案；若不同结论能提供同等证据，可请同伴复核。缺少证据的部分记未完成，再回到对应步骤补充。

</details>

## 来源与边界

登记来源只支持本章涉及的外部事实；全生命周期证据链、示例数字和练习情境属于课程内部教学设计，必须在实际项目中重新验证。

- [GitHub Actions 官方文档](https://docs.github.com/en/actions) — GitHub, 2026-09-17. 仓库工作流可以自动执行构建、测试和持续集成任务。
- [OWASP 大语言模型应用风险](https://genai.owasp.org/llm-top-10/) — OWASP Foundation, 2026-09-17. 模型输出、敏感信息、工具权限和人工控制需要独立风险边界。