|
|
@@ -16,3 +16,37 @@ InkOS pi-agent 持久化模块设计在 `docs/superpowers/specs/2026-04-27-pi-ag
|
|
|
4. **解释因果关系**：说明某个设计为什么能产生对应结果，以及缺少这个设计会触发什么失败场景。
|
|
|
5. **避免空泛对比**：不要用简单二分对比替代解释；对比只能作为结论，不能作为证明过程。
|
|
|
6. **控制信息密度**：每一层只放支撑当前结论所需的信息，细节服务于推理，不做无目的罗列。
|
|
|
+
|
|
|
+## TypeScript 代码实践
|
|
|
+
|
|
|
+回答或改写 TypeScript 代码时，先说明数据如何从“不可信输入”变成“可信领域对象”。每个判断都要回答四件事：它消除什么非法状态；由哪个类型、schema 或函数保证；下游因此获得什么前置条件；缺少它会触发什么失败场景。
|
|
|
+
|
|
|
+### 1. 核心分类
|
|
|
+
|
|
|
+1. **边界收敛**：外部输入不可信。文件、网络、JSON、数据库、第三方库返回值可以先是 `unknown`，但必须在模块边界通过 schema、parser 或 type guard 收窄。
|
|
|
+2. **领域建模**：业务状态要可区分。字段集合随 `role`、`type`、`kind` 改变时，用 discriminated union，不用 optional 字段堆出一个宽接口。
|
|
|
+3. **合法状态约束落地**：系统声称某份数据合法时必须满足的规则要有归属。单个对象自身就能判断的规则，放进类型或 schema；必须结合事件顺序、上下文或外部状态才能判断的规则，放进命名清楚的校验、转换或清理函数。
|
|
|
+4. **演进验证**：新增分支不能静默漏处理。union 要穷尽处理，非法状态要有测试覆盖。
|
|
|
+
|
|
|
+### 2. 推演链路
|
|
|
+
|
|
|
+解释 TypeScript 代码时按这条链路展开：
|
|
|
+
|
|
|
+```text
|
|
|
+问题背景：哪些输入不可信，或哪些业务状态容易混在一起。
|
|
|
+关键数据结构：raw input、validated event、domain message、cleaned message 分别是什么。
|
|
|
+执行步骤：哪个函数负责读取，哪个函数负责收窄，哪个函数负责合法状态校验，哪个函数返回可信结果。
|
|
|
+结果影响：下游少做哪些重复判断；缺少该设计时，非法状态会在哪里爆炸。
|
|
|
+```
|
|
|
+
|
|
|
+例如 transcript 恢复：`readTranscriptEvents()` 读取并解析事件，`committedMessageEvents()` 排除未提交请求，`cleanRestoredAgentMessages()` 清理孤立 `toolResult`、空 assistant 和非法 trailing thinking。推理重点不是“调用了这些函数”，而是这些函数分别阻断了哪些非法历史进入模型上下文。
|
|
|
+
|
|
|
+### 3. 代码准则
|
|
|
+
|
|
|
+1. 宽类型止于边界：`unknown`、`any`、`Record<string, unknown>` 不进入核心业务流程。
|
|
|
+2. 互斥状态用 union：不要用大量 optional 字段模拟状态机。
|
|
|
+3. 合法状态约束集中实现：不要把“必须 committed”“必须有对应 toolCall”“assistant 不能为空”散落成临时 `if`。
|
|
|
+4. 类型断言要有证据：`as SomeType` 前面必须有 schema、parser 或 guard 支撑。
|
|
|
+5. 分支处理要穷尽：用 `switch`、明确窄化和 `assertNever` 暴露新增分支。
|
|
|
+6. 函数名表达可信度：`parse*` 表示可能失败，`normalize*` 表示转换形状，`clean*` 表示执行合法性修复。
|
|
|
+7. 测试覆盖非法状态：恢复、迁移、IO、LLM message、tool loop 必须测坏数据、缺字段、未提交请求、孤立 `toolResult`、空 assistant、trailing thinking。
|
fanghanjun