D21 打包与发布：全局命令、配置目录、版本与更新，二十一天总复盘

今日目标

能把一个 TS 项目打包成可全局安装的命令行工具，并验证安装后真的可用
能设计配置的分层与覆盖顺序，让环境变量、配置文件与命令行参数各就各位
能把项目包装成可展示的作品：README、演示、已知限制

最后一天不加任何新能力，只做一件事：让别人也能用上前二十天做出来的东西。做完之后回到页面顶部把三条目标勾掉。

小白版讲解

转正与交付工牌：别人也能把他请去用

第一天我们给这位新同事发了工位和内线电话，二十天里他学会了读代码、改文件、跑命令、停下来问、记住上次的事、接别的部门的工具、按老师傅的手艺卡干活、把活分给几个临时工去并行做、把车间规矩焊成他绕不过去的流程、看懂图纸、还能给自己算一笔工时与花销的账。今天是他转正的日子，而转正真正的标志不是能力清单又长了一条，是别的部门可以把他借走。

借走这件事有它自己的门槛，而且和能力无关。他得有一张工牌，别人刷一下就知道他是谁、哪个版本。他得能在别人的车间里干活，而不是只认自己那间。别人的规矩和他的习惯冲突时，得有一套说法决定听谁的。第一次被借走那天，如果他开口第一句是一串谁也看不懂的编号，这次借调基本就到此为止了。

这些事都很小，小到容易被当成「收尾的杂活」。但它们决定的是同一件事：这东西到底是一个作品，还是只是你机器上的一堆代码。 二十天写下来的所有机制对一个装不上、跑不起、第一屏就报堆栈的工具来说，价值精确地等于零。

今天要做四件「不做就等于没做完」的事：可执行入口与打包产物、配置的分层与来源、版本与更新提示、第一次运行的引导。收尾是一条必须真跑的验证链。

第一道坎：TypeScript 怎么进包

这是所有 TS 命令行工具的第一个问题，而它的标准答案经常被绕过去：把 tsx 写进运行时依赖，入口直接跑 TS 源码。这确实能用，代价是每个装你工具的人都要跟着装一个几十兆的构建工具。零依赖纪律守了二十天，最后一天崩在这里很可惜。

所以本课的裁定是编译成 JS 再发出去：源码在 src，产物在 dist，包里只有产物。代价是多一个构建步骤，收益是用户装到的是能被 Node 直接执行的普通 JS。

但这一步有个坑：编译器只搬它会编译的文件。 src 下那些不是 TS 的东西——要被子进程起起来的脚本、模板、静态页、数据文件——它一个都不管。而本地开发跑的是源码，根本没用到产物，所以这类故障在本地永远复现不出来，只有装到别人机器上才报一句找不到模块。

修法是在构建脚本里自己搬一次，而且必须按目录遍历而不是手写清单。手写清单会在加第一个新文件的那天悄悄过期，没有任何东西会报错——本课的产物里正好有两个这样的文件，第十五天那个笔记库子进程和第十八天那个后台任务执行器，它们是在构建脚本写完之后才各自出现的，而没有人为它们改过那个脚本一个字。同一条道理决定了包清单怎么写：files 列目录，不列文件。

JSONJSON

"files": ["bin", "dist", "skills", "README.md", ".env.example"]

写成逐个文件枚举的那一刻，这个包就开始了它的过期倒计时。

入口：JS 交一个带 shebang 的文件，Python 交一个函数

全局命令要有一个入口。两种生态在这里的分工很不一样，对照着看一次，「入口」这个概念会清楚很多。

Node 这边，你在 bin 字段里指一个文件，安装器给它建一条符号链接。执行这条链接的是 shell 不是 node，所以第一行必须是 shebang；少了它报的是一句语法错误，完全指不到病根。Python 那边正相反：你在打包配置里声明一个可调用对象，启动器由安装器生成——你从来不写 shebang，因为那个文件不是你写的。

bin/mca.mjs

#!/usr/bin/env node
// 三件事：① 第一行的 shebang 不能少 ② 扩展名写 .mjs，不指望 package.json 的 type
// ③ 一行业务都不写——bin 路径是发布契约的一部分，公开之后就不好改了
import '../dist/index.js'

src/mca/cli.py

import sys
# pyproject.toml 里写 [project.scripts] 那一段：mca = "mca.cli:main"
# 声明的是一个**函数**，启动器由 pip 生成，所以这里既没有 shebang 也没有入口判断
def main() -> int:
    args = sys.argv[1:]
    if "--version" in args or "-v" in args:
        from importlib.metadata import version  # 版本号的唯一真源同样是包元数据
 
        print(f"mca {version('mca')}")
        return 0
    return run_repl(args)

两边还有一条一样的纪律：版本号只能有一个真源，Node 是包描述文件、Python 是包元数据。代码里另写一个版本常量，发版时改一处忘一处，用户报的 issue 就会全部带着错的版本号——这种 bug 不会让任何测试变红。

配置分层：作用范围越窄的越大

前二十天 mca 的配置只有一层：环境变量。够用是因为只有一个用户、一个仓库、一个终端。装到别人机器上之后，同一个值会同时有四个人想说了算。

Mermaid 源码

mermaidmermaid

flowchart TD
  A[内置默认值<br/>什么都没配时的兜底] --> B[用户配置<br/>这台机器上我个人的默认]
  B --> C[项目配置<br/>这个仓库的团队约定 进 git]
  C --> D[环境变量<br/>这个终端会话]
  D --> E[命令行参数<br/>就这一次]
  E --> F[最终生效的值<br/>并且记得自己从哪一层来]

优先级就是这个顺序，而它不是品味是推导：作用范围越窄的越大。 范围越窄，说明用户越明确地在说「就这一次」「就这里」。倒过来排的症状都一样——用户加了个参数却没生效，而且没有任何报错。

实现上只有一个要点：把五层排成一个有序数组依次覆盖，而不是写一串条件判断；加一层只要插一个元素。

比覆盖顺序更值得说的是第二件事：每个值都要记住自己从哪来。 配置分层最常见的支持问题不是「值错了」，是「我不知道它为什么是这样」。所以解析的产物不该只有值，而要每个键都带着来源，再配一条把它们全摊开的命令。这不是调试功能，是这套分层能不能被人用起来的前提。

src/ship/config-layers.ts

// 数组顺序就是覆盖顺序：后写的盖先写的，写的时候连来源一起写
for (const entry of stack) {
  for (const key of ['baseUrl', 'model']) {
    const value = entry.data[key]
    if (value === undefined) continue
    traced[key] = { value, layer: entry.layer, from: entry.from }
  }
}

src/mca/config.py

from collections import ChainMap
 
# ChainMap 天生就是「分层查找」：前面的盖后面的，所以这里按优先级从高到低排
merged = ChainMap(flags, env, project, user, defaults)
labels = ["命令行参数", "环境变量", "项目配置", "用户配置", "内置默认值"]
 
def trace(key: str) -> tuple[object, str]:
    # maps 保留了每一层，所以「谁提供了这个值」不用额外记账，查一遍就知道
    for layer, label in zip(merged.maps, labels):
        if key in layer:
            return layer[key], label
    raise KeyError(key)

顺带一个工程细节：前二十天所有读配置的地方读的都是环境变量，其中三个还是冻结文件。新加一层有两条路——把配置对象一路传下去（要改二十个文件，有的改不动），或者在入口处把最终值写回环境变量（改一处，下游一行不动）。本课选后者，前提是有且只有一个写入点且它在任何 provider 被造出来之前执行；没有这个前提，它就退化成「环境变量被谁改过谁也说不清」。

配置目录里放什么，以及绝不放什么

配置文件放两处：用户目录一份（我个人的默认，不进任何仓库），项目目录一份（团队约定，要进 git）。项目那份从当前目录往上找第一个带配置目录的祖先——人经常在子目录里敲命令，而项目级配置属于整个仓库；停在第一个命中的祖先不再往上翻，是为了让嵌套仓库有确定答案：离你最近的那份赢。

然后是今天最该记住的一条红线：密钥不进配置文件。

理由不是洁癖。项目配置要进 git，用户配置明文躺在家目录里，两者都会被备份工具、同步盘、截屏，以及一句「你把配置发我看看」顺走。而环境变量只活在这个进程里，.env 至少有一条人人都懂的规矩叫别提交它。

做法上有个容易错的分叉：读到密钥是忽略还是拒绝并说出来。必须是后者。静默忽略的结果是用户明明写了 key 却一直被告知没有 key，他会以为工具坏了。拼错的键名同理，也要说一句。另外打印配置时密钥必须打码：日志、截图、issue 里最常见的泄漏就是有人把配置输出整段贴了出来。

全局安装之后，三个根第一次分开

本地开发时，「代码在哪」「我在哪个仓库干活」「我的个人偏好在哪」是同一个目录，所以一个取当前目录的函数就够了。全局安装把这三件事彻底拆开：代码躺在安装前缀里，和用户八竿子打不着。

规矩只有一条：随包分发的东西一律从包的位置去找，用户的东西一律不从包里找。 找包的位置要从模块自身的地址向上找，而不是写死几层相对路径——源码和产物的层级今天恰好一样，换个构建配置就不一样了。这条一破，症状是「我自己跑没问题，别人装完找不到文件」，而且本地永远复现不出来，因为本地这三个根是同一个目录。

今天顺手用这条规矩把技能目录也扩成三个来源：随包分发的、用户自己的、当前仓库的，同名时离项目最近的赢——并且要说一句谁盖了谁。

两件不许添乱的小事：首次运行与更新提示

第一次敲一个刚装好的工具，是它唯一一次不需要争取就能得到的注意力，而这一刻能给的最差回应是一段堆栈。合格的人话要回答三件事：缺的到底是什么、敲哪条命令能补上（要能直接复制）、以及我不想补能不能先看看它长什么样——最后这条退路必须给，它是把「我再研究研究」变成「我先跑一下」的唯一办法。

更新检查的难点也不在怎么查，在怎么不添乱：做坏了能让启动多等两秒、离线时报红字、上游抽风时整个工具起不来，每一条都比「用户晚一周升级」严重。所以四条硬规矩：失败一律静默、必须带超时、一天只查一次、离线模式一次都不查。没有超时的网络请求，等于把别人的可用性接进了自己的启动路径。

src/ship/update.ts

export async function fetchLatestFromRegistry(name) {
  try {
    // 超时不是优化，是这个功能能不能存在的前提
    const response = await fetch(`${registry}/${name}/latest`, {
      signal: AbortSignal.timeout(1500),
    })
    if (!response.ok) return null
    const body = await response.json()
    return typeof body.version === 'string' ? body.version : null
  } catch {
    // 「这次没查到」和「查到了没有新版」在用户看来是同一件事：屏幕上什么都不多
    return null
  }
}

src/mca/update.py

import json
import urllib.request
from contextlib import suppress
 
def fetch_latest(name: str) -> str | None:
    # suppress 是 Python 里表达「这一段失败就当没发生」最直白的写法，
    # 比一个空的 except 块更能说明这是有意为之而不是忘了处理
    with suppress(Exception):
        url = f"https://pypi.org/pypi/{name}/json"
        with urllib.request.urlopen(url, timeout=1.5) as response:
            return json.load(response)["info"]["version"]
    return None

非交互模式：审批的默认答案必须是拒绝

装出去之后，这个工具立刻会被塞进人以外的地方：脚本、CI、git 钩子。而 REPL 是给人用的——无交互终端下标准输入立刻结束，程序打印一行提示就退出，退出码还是 0。这正是本课从第一天就在防的那个假绿，今天它从验收纪律变成了真实的产品需求：得有一个跑一次就退出的模式。

这个模式有条自己的纪律：审批的默认答案必须是拒绝。 交互模式里「没回答」是用户在犹豫，非交互模式里「没回答」是常态；当成同意等于给所有 CI 发了一张无限授权。要动东西必须显式加开关，而且被挡下时那句话要说给模型听——让它改走只读的路，而不是对着同一个调用原地重试。

最后一步：验证不是看它有没有报错，是装完再跑一遍

构建成功、打包成功、没有任何红字——然后包在别人机器上第一秒就挂了。原因永远是同一类：本地跑的是源码，发出去的是产物。

所以验证链必须真跑，四步都不能省：打成包、装到一个临时前缀、在一个新建的空目录里跑版本命令、再在同一个目录里跑一次真实任务。临时前缀是为了绝不碰用户的全局环境，空目录是因为当前目录和包毫无关系正是要验的那件事。跑完把临时目录和包文件一起删掉。

实验里这条链是五项全绿，包体积 192 KB（包内 134 个文件）——同一份代码上稳定可复现；安装耗时不可复现，取决于网络与缓存，所以那条脚本一个耗时数字都不打印。

源码导读

动手实验

🧪 D21 实验：把 mca 打成包、装到临时前缀、在一个陌生目录里跑通一次真实任务

代码位置：labs/my-coding-agent-21days/day-21-ship-it

五个练习点全是「本地全绿、装完就炸」的那一类：包清单逐个文件枚举、入口少了第一行、构建只编译不搬资产、分层顺序排反且丢了一层、密钥闸没装、第一屏给的是堆栈、更新检查能把启动带崩。起点代码原样跑是十四项过四项。

把包清单改成按目录枚举、给入口补上第一行，看第 2、3 项从红变绿。
在构建脚本里补上「按目录遍历搬非 TS 资产」那一段，看第 4 项打出来的缺件清单清空。
把配置分层的顺序排对、补上命令行参数那一层，看同一个值在四层里各赢一次，且每次都说得出来自哪一层。
装上密钥闸，看写进配置文件的密钥被拒绝并警告，而打印出来的配置里没有明文。
把第一屏换成人话三选一、把更新检查的异常就地吞掉，跑 MOCK=1 SELFTEST=1 pnpm start 看到十四项全过，再跑一次 pnpm verify:pack 看完整的打包验证链。

验收看五条勾：自检十四项全过；源码目录下每个文件在产物里都有对应物；包里有产物与入口、没有源码与 .env；不加授权开关时写操作被拒且文件一字未改；打包验证五项全绿且跑完临时目录都没了。

面试题

今天三道题，考的是分发与配置的工程判断：

把一个命令行工具发布成可全局安装的包，有哪些容易忽略的坑？
配置的分层与覆盖顺序你怎么定？密钥该放哪里？
把这个项目写进简历，你会怎么用三句话说清它的技术含量？

完整题干、分析过程与答题要点见本课面试题库的第二十一天。第一题最有区分度——多数人会答「记得写 bin 和 files」，能说出「本地跑源码、发出去的是产物，所以必须装完再跑一遍」并举出一类只在安装后暴露的故障的人很少。

检查清单与明日预告

能说清 TS 项目为什么该编译成 JS 发出去，而不是把构建工具拖成运行时依赖
能说出编译器不搬非 TS 资产这个坑，以及它为什么在本地永远复现不出来
能解释包清单与搬资产为什么都必须按目录而不是按文件枚举
能把配置五层的优先级推导出来，而不是背下来
能说出为什么每个配置值都要记住来源，以及打印来源为什么不是调试功能
能说清密钥为什么不进配置文件，以及为什么必须「拒绝并说出来」
能说出全局安装之后哪三个根会分开，以及本地为什么复现不出这类 bug
能背出更新检查的四条规矩，并说清没有超时的后果
能解释非交互模式的审批默认答案为什么必须是拒绝

二十一天做出了什么

回到第一天：那时屏幕上只有一个提示符，敲一句话进去什么都不会发生。今天它是一条能装到任何机器上的命令，在别人的仓库里读代码、改文件、跑测试、停下来问你、记住上次说过的话、接别人的工具、按团队的手艺卡干活、把大活拆给子 Agent 并行跑、用钩子把「先读后改」这类规矩变成绕不过去的流程、把长命令扔到后台、看懂你贴给它的截图，还能拿一套基准集给自己打分并算清这一轮花了多少钱，并且随时可以回退。

中间那二十层每层只做一件小事。回头看，最难的一层不是流式解析也不是压缩，是审批——它第一次要求你回答「这个东西被允许做什么」，而那不是技术问题。最值钱的一层大概是事件日志：所有事都被追加记录下来之后，恢复、分叉、回退、评估、成本统计全都变成在同一份数据上做不同的读法。而最容易被跳过、跳过之后最伤的一层，就是今天这一层。

和真正产品级的 Coding Agent 差多远

诚实地说：差得不少，而且差的地方大多不在你以为的地方。

编辑能力：我们只有精确替换。产品级要处理补丁格式、缩进漂移、同一处多次修改、大文件的局部改写。
检索能力：我们的 grep 就是字符串匹配，真实仓库要的是语义检索与符号索引。
并发与隔离：我们的子 Agent 是进程内的。产品级要处理真实的工作树隔离、冲突合并、跑到一半被杀掉之后的残留清理。
稳定性：我们只覆盖了已知的那几类错误，而真实世界里网关会返回你从没见过的形状。
安全：我们的审批门挡的是本机写操作，产品级还要考虑提示注入、越权读取、密钥外泄。

但这份清单本身就是收获：你现在能具体地说出差在哪里，而不是笼统地觉得「人家的更厉害」。

接下来往哪走

三个方向，按投入从小到大：

把它变成你真的每天用的工具。 先改今天 README 里点名的那条取舍（别往用户仓库里写沙盒），再按你的工作习惯加两条斜杠命令。日用一周比再读十篇文章有用。
补齐某一块的深度。 检索去看 RAG 课，上下文预算去看上下文工程课，工具生态与经验复用去看 MCP 课与 Skills 课。
把它讲成作品。 简历上写「实现了一个 Coding Agent」没有信息量，写「手写 SSE 解析与工具分片归并、用事件日志做会话恢复与分叉、用内容寻址快照做回退」才有。今天做的打包与 README 就是这件事的载体：一段能直接跑的演示，胜过一屏功能列表。

第一天那句话现在可以还给你了：模型没有记忆，也不会自己动手——是你写的那二十一层让它看起来像会。