体检后续：修复 npm 文档死链、CRLF 围栏与类型检查告警

[tt-a1i]

背景

在当前 main@22e77d63b7c23b13e14d47f166e9b295b21c4b97 上复核 OpenPI 体检报告。构建与测试保持通过，但确认存在两项发布制品完整性问题和三项低风险质量债。

本 Issue 只记录已复现的问题；Sessions 扩展使用 .js 相对导入后缀仅是局部历史风格，当前运行、类型检查和测试均正常，不作为缺陷处理。

P1：npm 发布制品中的文档引用不完整

1. README 相对链接在安装包内没有目标

package.json#files 不包含 docs/，但 README 仍有：

• docs/design/WORKFLOW_INVOCATION_GRAPH.md
• docs/design/

复现：

npm pack --dry-run --json

实际 packlist 包含 README.md，但不包含任何 docs/ 文件。GitHub 仓库页面可解析这些链接，安装后的 npm 制品本地却无法解析。

建议： README 改为指向 GitHub main 的绝对链接。除非明确希望发布整套研究文档，否则不建议为了两处链接扩大 npm 制品。

2. Subagent Skill 引用被 packlist 排除的文档

skills/subagents/SKILL.md:13 引用：

extensions/subagents/docs/agent-types.md

仓库中目标存在，但 package.json#files 的 !extensions/*/docs 会将其从安装包排除。实测 packlist 包含 Skill，却不包含目标文档。

这会直接破坏安装后 Skill 的渐进披露链路。

建议： 将用户/Agent 需要读取的 agent-types 参考文档移到 skills/subagents/（例如 REFERENCE.md）并使用同目录相对链接；内部设计笔记继续留在扩展目录且不发布。

P2：CRLF fenced code block 被误判为未闭合

extensions/user-input-fold/index.ts 使用 markdown.split("\n")，因此 CRLF 行保留结尾 \r；当前：

const FENCE_CLOSE = /^ {0,3}`{3,}[ \t]*$/;

无法匹配以 CRLF 结尾的关闭围栏行。

同一条长 fenced message 的实测：

LF:   fence count = 2，保留闭合 fence
CRLF: fence count = 1，走 unterminated-fence prose fallback

结果是折叠后的展示可能留下未闭合 Markdown fence。模型上下文和持久历史不受影响，但 TUI 投影不正确。

建议： 在行解析边界统一处理 CRLF，或让关闭 fence 显式接受尾部 \r；补一条包含长代码围栏的 CRLF 回归测试，要求 fence 成对且折叠结构与 LF 等价。

P2：Effect TypeScript 插件仍报告 12 条 warning

bun run check 当前退出码为 0，Biome lint 也干净；但 bun run typecheck 会在 extensions/file-search/src/binaries.ts 输出 12 条 Effect warning：

• 11 条 TS377023 globalErrorInEffectFailure
• 1 条 TS377033 multipleEffectProvide

因此应准确描述为“Effect TypeScript 插件 warning”，不是 Biome lint failure。

建议： 使用带 tag 的领域错误并合并 Layer provide；若某条确实需要保留，使用最窄范围、带原因的显式抑制，不要全局关闭规则。

P2：文档和模型提示引用不存在的 /handoff

已确认以下位置把 /handoff 描述成可用入口：

• SETUP.md:74
• extensions/context-pivot/index.ts 的低于阈值提示
• context_pivot 工具说明

OpenPI 没有 /handoff 命令；可选的 pi-intercom 提供的是 pi-intercom Skill、intercom 工具和 /intercom-id，也没有 /handoff。

建议： 改为真实路径：同一会话阶段切换用 /context-pivot，会话浏览/切换用 /sessions，需要跨顶层 Session 传递上下文时使用可选 pi-intercom。不要暗示一个不存在的 Slash Command。

验收标准

• npm pack --dry-run 后，README 和已发布 Skills 的仓库内相对链接均能在制品中解析，或已改成稳定的 GitHub 绝对链接
• Subagent Skill 的 agent-types 参考资料随 npm 制品发布
• LF 与 CRLF 长 fenced message 都输出成对 fence，且折叠语义一致
• bun run typecheck 不再输出上述 12 条 Effect warning，或每个保留项都有窄范围书面理由
• OpenPI 文档和模型提示不再宣传不存在的 /handoff
• bun run check 与 bun run test 通过

[627150795]

Hi! I am working on this issue. I will address the publish-packlist documentation links, CRLF fenced-message handling, and the remaining /handoff references, then validate the Effect diagnostics separately before opening a PR. I will keep the changes scoped to the issue and update this thread with the result.

[627150795]

Update: PR #231 has been rebased onto the latest upstream main and now covers the remaining package-documentation and CRLF-fence work only. The file-search Effect diagnostics portion is already fixed upstream in PR #230, so I removed that duplicated change. Focused tests, lint, typecheck, package preview, and diff checks pass.

[627150795]

代码有效性审计结论：在当前 openpi-dev/openpi/main@d08bb6b 基线下，PR #231 的实际远程提交 0ab91e0 在声明范围内有效。CRLF fenced-message folding、安装包内 REFERENCE.md 路径和 /sessions 引导均沿真实调用/发布路径检查；相关定向测试 20/20 通过，未发现需要追加的生产代码修复。bare-CR 和极限阈值计数仍是既有边界，不是本 PR 引入的回归。

[ljymiller]

Closure audit

已在最新 origin/main@ba550bc1d918147c326840276eff018b505ed9d8 上完成独立 worktree 复核。结论：Issue #69 的六项验收条件均已满足，无需追加代码修复。

合并事实：

• fix(file-search): define BinaryDownloadError and consolidate Effect layer provides (#170) #230 merge commit：fc4ab47fba2ab43dcdb6182522fc407688b5397f
• fix(issue-69): repair package docs and CRLF folding #231 merge commit：a05c9811d96258e8251559b60c8c2c883168a6b5
• 两个 merge commit 均为上述审计 revision 的祖先

逐项结果：

• npm packlist：158 entries；7 个发布态 Markdown 文件中的 7 条相对链接均能在制品内解析；README 的未发布设计文档使用 canonical openpi-dev 绝对链接。
• Subagent reference：skills/subagents/REFERENCE.md 随包发布；旧 extensions/subagents/docs/agent-types.md 不发布。
• CRLF fence：LF/CRLF 长 fenced message 折叠语义一致、fence 成对；相关 focused Node tests 42/42 passed。
• Effect diagnostics：bun run typecheck 静默通过，无 TS377023/TS377033。
• /handoff：用户/模型可见的不存在 Slash Command 引用为 0；剩余 handoff 命中仅为合法内部模块/概念或负向测试。
• 仓库门禁：git diff --check、bun run check、bun run test 全部通过。

完整测试结果：

• Node：1076 passed、0 failed、1 platform skip
• Vitest：30/30 passed
• file-search focused Vitest：30/30 passed

独立只读 reviewer 结论：NO ACTIONABLE FINDINGS。确认符合 AGENTS.md，PR #230/#231 范围最小，无回归、遗漏、证据不足或 scope creep。

本轮 closure audit 没有 tracked 代码修改，也没有 push 或 PR 操作。

未验证项：当前审计环境没有 pi CLI，因此未执行 pi list 来源证明、/reload 后真实 Pi/TUI smoke。该项不能由自动化替代，但不属于 Issue #69 的书面验收门禁。

问题（Problem）

Issue #69 发现 npm 发布制品和运行时投影存在五类完整性问题：

• README 引用了未随 npm 包发布的 docs/ 文件，安装后的本地链接失效。
• Subagent Skill 引用了被 packlist 排除的 agent-types 文档，破坏渐进披露链路。
• CRLF 长 fenced message 的关闭围栏无法被识别，TUI 折叠后可能留下未闭合 fence。
• file-search 存在 12 条 Effect TypeScript 诊断，失败通道缺少稳定的领域错误类型，Layer 注入也较分散。
• 文档和模型提示宣传了实际不存在的 /handoff 命令。

价值（Value）

• 保证 npm 安装用户看到的文档和 Skill 引用真实可用。
• 保证 LF、CRLF 输入在 TUI 中具有一致、合法的 Markdown 展示。
• 消除 Effect 类型诊断，提高下载失败的可区分性和类型安全。
• 避免模型和用户被不存在的命令误导。
• 让仓库源码、发布制品、模型提示和用户界面保持一致，降低安装后才暴露问题的风险。

方法（Approach）

PR #230：

• 引入带 tag 的 BinaryDownloadError，替换 Effect failure channel 中的通用 Error。
• 使用组合后的单一 Layer 提供依赖。
• 在公开边界继续映射为原有 InstallError，保持外部契约不变。

PR #231：

• 将未发布设计文档的 README 链接改为 canonical openpi-dev/openpi 绝对链接。
• 将 agent-types 参考资料迁移到随包发布的 skills/subagents/REFERENCE.md。
• 让 fence closing regex 接受 CRLF 的尾部 \r，并增加 LF/CRLF 等价回归测试。
• 将不存在的 /handoff 引导替换为真实的 /context-pivot、/sessions 和新建 Pi Session 路径。
• 通过 packlist、定向测试、类型检查和全量门禁验证结果。

影响（Impact）

• 用户可见：npm 文档链接恢复可用；CRLF fenced message 的 TUI 折叠正确；会话操作提示不再误导。
• 模型可见：Skill 渐进披露资料可读取；context-pivot 提示只引用真实能力。
• Runtime：仅调整 CRLF fence 识别和 file-search 内部错误/依赖建模；不改变正常功能流程。
• API/兼容性：公开 InstallError 和现有工具接口保持不变。
• 持久化数据与配置：无变化，无迁移要求。
• 发布体积：没有把整个 docs/ 加入 npm 包，只发布必要的 Subagent reference，增量保持最小。
• 风险：较低，相关定向测试、bun run check 和全量测试均已通过。