distill-skill · 给 agent 的引导（Agent bootstrap）
====================================================

你（coding agent）读到这一页，说明有人要你在一台新机器上：把机器上的项目"蒸馏"成成长档案，
并给其中的网站产品打一张十一维记分卡。整套流程都在 distill-skill 这个库里，装好后照 SKILL.md 做即可。
本页只负责把库装起来并跑通预检。全文可直接执行。需要主人在场的只有三处（见第 5 节末尾的清单）：
勾选根目录与项目、每个薄项目一轮四题的访谈、第一次上站时在自己终端里跑一次 connect.sh（脚本会问地址与一次服务器密码）。

0. 前提
   - Linux、macOS，或 Windows（Git Bash）；Python 3.10+；git。
     Windows 注意三件事：脚本会自己找 python3 或 python（应用商店的 python3 空壳会被识别并跳过）；
     Git Bash 会把单独的 "/" 参数改写成 MSYS 根目录，给 snapshot.mjs 传路径时写成 --path users/x/（不带开头的斜杠）
     或设置 MSYS_NO_PATHCONV=1；install.sh 用目录联接（junction）代替软链，不需要管理员权限。
   - 记分卡还要 Node 18.20+（推荐 22）、npm，以及能访问被测网站和 api.osv.dev 的网络。
   - 评审需要能开"新上下文子代理并读图"的 agent 运行时（Claude Code 即可；评审模型记在卡上）。
   - 小机器（2 核 / 2 GB）也能跑，但评审最多两个并发，Lighthouse 跑时不要构建。

1. 取库（三选一）
   git clone https://mekxa.cn/next/distill-skill/distill-skill.git ~/distill-skill
   （新站切到根目录后地址去掉 /next；版本见 https://mekxa.cn/next/distill-skill/VERSION）
   克隆过程中若打印 "error: inflate: data stream error" 或 "File … corrupt"，可以忽略：过渡期旧站对不存在的路径返回 200，
   git 先试散对象再回退到 pack 文件，结果完整。不放心就 git -C ~/distill-skill fsck，应无输出。
   （站点把这条路径改成返回 404 之后这段提示就会消失。）

2. 装 skill 与依赖
   ~/distill-skill/install.sh                       # 软链全部 skills 到 ~/.claude/skills/
   export DISTILL_HOME=~/.distill                   # 私有产物目录，写进 shell rc；永远不要提交它
   cd ~/distill-skill/skills/distill-assess/scripts && npm install     # 约 200 MB
   npx playwright install chromium                  # Debian/Ubuntu 还需：sudo npx playwright install-deps chromium

3. 预检（直到它打印 ready）
   ~/distill-skill/scripts/preflight.sh --url https://要评测的站/
   每一行 MISSING 后面就是修复命令。WARN 可以继续，但会印在卡上（例如没有 GPU 时 WebGL 帧率只作相对值）。

4. 先保住证据
   编码 agent 会定期清掉本地会话记录（Claude Code 默认 30 天）。把 cleanupPeriodDays 调到 3650（不能是 0），
   否则"心理过程"这一层的证据会消失。distill-survey 会检查这一项。

5. 跑
   a) 蒸馏（历史 → 成长档案）：对 agent 说"普查这台机器"或"蒸馏这个项目"。
      普查先列候选根目录（每个 /home/<用户>、/data、/srv、/opt、挂载盘等，标出归属与可读性），你勾选要扫的；
      同时跑 distill-survey/scripts/hints.py：它读 VS Code（及 Cursor / Trae / Windsurf）、JetBrains、MATLAB 记住的"最近项目"，
      把编辑器打开过的文件夹（含已不在磁盘上的）交给 survey.py --hints——老项目多半没有 package.json，也不在今年的目录里；
      没有清单文件的文件夹只要有工程文件（.sln / .xcodeproj / .prj / .ipynb …）、IDE 目录或四个以上源码文件就算项目，
      起点按最早文件的创建时间（Windows / macOS 保留），未解压的归档单列一行让主人决定是否解压；
      survey.py --site https://mekxa.cn/next/ 会读站上公开清单 /work/index.json，把已经上站的项目标 on_site，不重复发、不占第二颗行星；
      再列项目清单（id、路径、形态、提交数、证据分、档位），你勾选要做的项目并选并行数（脚本按核数与内存封顶）；
      结果写成 plan.json，之后按它逐个执行。多用户主机：别人的家目录即使可读也不扫，主机本身不算你的项目。
      路由 skill 是 distill，它会按证据丰富度选 distill-survey / evidence / episodes / measure / narrate / remix / verify。
      产物在 $DISTILL_HOME/<项目>/（普查文件在 $DISTILL_HOME/<机器名>/）；发布前必须过 distill-verify（引用检查 + 密钥扫描）。
      过程记录薄的项目（无 git、没有自己的会话、只剩结果）走"产品档案"流程，不许手写，顺序固定：snapshot.mjs 截图并读页面（需登录的
      页面用 --dir 本机渲染目录）→ interview.py 访谈 → factcard.py 自动填数据块并写正文。
      访谈是一个项目一轮、四道选择题（是什么给谁用怎么用 / 价值 / 自己拿的主意与最难处 / 现状），起点不明（无 git、文件明显早于首次提交、
      或什么都没日期）时再追一问"什么时候开始做的"，选项是各条带依据的日期，主人说的算（basis owner），"记不清"就留空，脚本永不自己猜起点；选项由 interview.py 从 README、
      依赖清单、页面自述、最初几条提示、最近提交、改动最多的文件、日期里拟出，每个选项注明出自哪条证据；没有证据的问题只留"其他"，
      不许拿空泛模板凑数；第一题带"跳过这个项目的访谈"。确认的原话带时间戳入档。有网址的项目蒸馏之后一律排记分卡。
      没有可访问网址的项目（想法、论文、课程作业、跑一半停下的）打不了分，必须补一段第一人称小传：
      firstperson.py brief 摊证据 → agent 写三段（起因 / 做了什么 / 后来，110–480 字，落在日期与数字上）→
      firstperson.py check 过关（AI 腔一律退回）→ firstperson.py apply 写进事实卡。站上没有它就拒收。
      每个项目过核验后，agent 必须主动提议上站（见 c）：手动模式给清单等主人说"发"，自动模式直接发并回链接。不提议就是没做完。
   b) 记分卡（产品 → 十一维分数）：对 agent 说"用 distill-assess 给 <网址> 打分，仓库在 <目录>"。
      顺序见 skills/distill-assess/SKILL.md：collect.sh 采证据 → calibration.mjs + packet.py 封包 →
      三位新上下文评审（每维一包，两两并发）→ merge.py → assess-peers 找同类 → 十一份 score.py →
      scorecard2.py → export_site.py 导出公开子集。
      铁律：只评产品；工具失败记缺席不给分；建造者不评审；每个数字带工具与输入；一事一维；
      真实条目不足三个或仍有占位页时总分封顶 69。
   普查的判断规则：一份会话只算一个项目（子目录是自己的项目时，它的会话归它，父项目自动排除）；软件安装目录（site-packages、
   conda、MATLAB toolbox、编辑器插件、Program Files、AppData）默认跳过，--exclude 可再加；清单每行有唯一 id（重名文件夹带上级目录名）；
   文件数到 20000 封顶时写成 ≥20000。
   c) 上站（公开子集 → mekxa.cn）：
      python3 ~/distill-skill/scripts/publish.py $DISTILL_HOME/<项目> --slug <slug> [--title … --summary …]
      时代不用填：站主在站上定义了时代（起止年月），服务器按项目起始日期自动归属；所以起始日期要准（记录定不下来时访谈会问，不许猜）。
      --era 只在站主明确要求时才填，且只能填站上已有的 id（https://mekxa.cn/next/work/index.json 的 eras），填错服务器拒收并列出可选值。
      它只导出能公开的部分（记分卡、相簿、脱敏证据索引），写 meta.json，过密钥扫描，打成 $DISTILL_HOME/outbox/<slug>.distill.tar.gz。
      模式在 $DISTILL_HOME/config.json 的 publish.mode：
        manual（默认）：停在清单，把清单给主人看，主人说"发"再加 --send；
        auto：直接送到服务器，服务器导入、构建、发布，回一行 JSON 含页面地址。
      第一次上站前先接入，一台机器只做一次。agent 不在对话里问 ssh 地址 / 用户 / 密码——那是主人的活，脚本会自己问：
        1) agent 检查 $DISTILL_HOME/config.json 有没有 publish.to；有就直接 publish.py，不再提接入。
        2) 没有就把这一行原样交给主人，请他在自己的终端里跑：
             bash ~/distill-skill/scripts/connect.sh
           脚本自己依次问：服务器地址、登录名、ssh 端口（默认 22）、这台机器的名字、发布模式（manual / auto）；
           它在本机生成专用钥匙（私钥不出本机），登录服务器时由 ssh 问一次密码（就在这一步，之后不再需要），
           把公钥登记为只能执行 put 的受限钥匙，ping 通后把 publish.{mode,to,port,key} 写进 config.json。
           agent 可以带上 --host / --user 预填，但永远不碰密码。
        3) 主人说跑完了，agent 跑 `bash ~/distill-skill/scripts/connect.sh --check`（只读：有没有目的地、钥匙能不能用），
           然后接着跑 publish.py。以后每台机器都不再问 ssh。
      星轨上是行星还是流星，由主人在访谈"现状"题的回答决定：选了"只是想法或骨架，没做成"才是流星，其余（做完、能跑、比赛、课程作业、论文、搁置）都是行星；
      证据薄只让行星更小更暗，不改类别；未受访默认行星。publish.py --kind planet|meteor 可以强行指定。
      slug 已存在时服务器拒收，除非 --replace。标题、摘要、时代写进 config.json 的 projects.<slug> 后以后不用再填。
      服务器拒收时的回答里带日志最后 20 行（log_tail），publish.py 会原样打印，不用再登录服务器找日志。

   需要主人在场的步骤（如实）：
      - 普查：勾选根目录（1 轮）、勾选项目与并行数（1–2 轮）、没有 git 身份时确认"你是谁"（1 轮）。
      - 每个薄项目：访谈 1 轮（四题一次问完，可整项目跳过）。
      - 第一次上站：在自己的终端里跑一次 connect.sh，按它问的填（地址 / 登录名 / 端口 / 名字 / 模式）并输一次服务器密码（1 次）；手动模式下每个项目说一次"发"。
      其余全部由 agent 和脚本完成。一台有 6 个薄项目的机器，主人大约需要回应 10 轮。
   d) 改公式前先跑 python3 tests/test_scorers.py；改了标准要升版本号。

6. 别做的事
   - 不要把 $DISTILL_HOME 里的任何东西提交进库或网站仓库（真实证据只以脱敏后的公开子集上站）。
   - 不要让写站的同一个上下文去当评审。
   - 不要手改分数；改输入、改量规或改标准并升版本。

7. 卡长什么样
   https://mekxa.cn/next/work/mekxa-site/  （这套流程给它自己打的分，含相簿、同类与评审记录）

维护者：mekxa.cn。库为 MIT，自托管，不上 GitHub。