distilly 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

distilly 是一个使用 Python 标注、同时提供 Node.js 包装入口的开源项目，用于把消息、文档、访谈和公开资料等来源材料整理为可复用的“人物画像”（Person Profile），再以代理技能（Agent Skill）的形式供支持相应技能机制的代理或机器人使用。

仓库描述将它概括为“Distill how they think into reusable Skills for any Agent or Bot”。项目原名为 Colleague Skill／colleague-skill，当前定位已经从同事场景扩展到同事、关系对象和公众人物等人物类别。仓库默认分支为 dot-skill，许可证为 MIT，公开资料显示有 24,890 个 Star 和 2,162 个 Fork。

定位与目标用户

本项目的核心定位不是声称复制某个真实人物，而是依据可观察的经历、判断方式、表达方式和工作方式，生成具有来源依据的人物画像。README 明确说明，它“does not claim to clone the person behind them”，因此输出更接近可追溯的工作与表达参考，而不是对真实人格、意识或私人身份的复刻。

目标用户需要准备一定的人物相关材料，并且希望把这些材料转换为代理可调用的结构化技能。使用对象可以是已经离职的同事、完成指导关系的导师、转岗的队友，也可以是家人、伴侣、旧友、作者、偶像、思想家、公众人物、虚构角色或用户自己。

• 需要保留特定同事的决策习惯、上下文和协作方式的团队。
• 需要将访谈、书信、消息或公开作品整理为可复用人物参考的个人用户。
• 需要让代理在限定来源材料基础上模拟某种表达风格或工作方式的研究与实验人员。
• 已经使用支持 Agent Skill 的宿主，并且希望把人物画像作为可安装技能管理的用户。

核心功能

核心功能可以理解为一条“来源材料—人物画像—代理技能”的处理链。输入不是一个预设的人格标签，而是用户提供的材料与人物描述；输出是可移植的 Person Profile，当前版本将每个画像封装为一个 Agent Skill。

来源材料的整理

README 列出的来源包括消息、文档、访谈和公开来源。它们分别承载表达习惯、事实背景、直接问答和公开可验证信息；项目的任务是把这些材料用于提炼经验、判断、声音和工作方式，而不是仅生成一段无来源的角色介绍。

资料没有提供完整的输入文件格式、字段定义、编码要求、单次材料大小限制或命令行参数。因此，不能根据仓库摘要推断某一种消息导出格式、文档格式或批处理接口。实际输入边界应以当前分支中的 README.md、SKILL.md、prompts/ 和 references/ 内容为准。

人物类别建模

当前 README 将人物类别归纳为三类：colleague、relationship 和 celebrity。colleague 覆盖同事、导师、队友以及上下游合作方；relationship 覆盖前任、伴侣、父母、朋友和近亲；celebrity 覆盖公众人物等对象。

类别的意义在于为同一创建流程提供不同的人物语境，而不是把类别当作保证输出真实性的标签。资料没有给出三类之间的具体提示词差异、字段差异或评估规则，因此不能声称某一类别拥有独立的算法、模型或质量指标。

人物画像封装为 Agent Skill

人物画像是可复用输出，当前发行方式将其包装为 Agent Skill。README 指出，创建者 Skill 的规范名称为 distilly，应安装在名为 distilly 的目录中；支持本地 Skill 发现的宿主包括 Claude Code、Hermes、OpenClaw、Codex、DeepSeek Harness、Pi、Grok Build 和 OpenCode，Grok Bot 则被单独列为已保存 Skill 的工作流预览。

触发条件取决于宿主是否支持相应的本地 Skill 发现和调用机制。仓库资料未提供每个宿主的安装命令、发现路径、调用语法、权限模型或兼容性矩阵，所以部署时应分别参考仓库当前文档与宿主文档。

来源约束与表达边界

“source-grounded Person Profile”意味着人物画像应能回到用户提供的来源材料。此设计适合需要区分材料事实、材料中的判断和基于材料作出的推断的场景，但资料没有说明仓库是否自动保存引用位置、是否生成证据链、是否提供冲突检测或置信度字段。

“Distilly is the person-modeling layer for agents. It turns the materials you provide into a portable, source-grounded Person Profile built from observable experience, decision patterns, expression, and ways of working; it does not claim to clone the person behind them.”

来源：README

系统架构与关键模块

从仓库资料能够确认的架构边界，是一个用于创建人物画像的技能包，加上一个 Node.js 命令入口和若干提示词、参考资料、工具目录。资料没有提供完整的类图、调用图、HTTP 服务定义或模型适配器说明，以下只描述仓库已明确暴露的组成，不虚构未给出的内部实现。

创建器 Skill 与输出 Skill

distilly 是创建者 Skill 的规范名称，负责把用户提供的来源材料和人物描述转化为 Person Profile。生成的画像随后被打包为可安装、可调用的 Agent Skill；这使“创建人物画像”和“在代理中使用人物画像”成为两个相互衔接但职责不同的阶段。

仓库文件模块

根据 package.json 的发布文件列表，包中包含 bin/、SKILL.md、prompts/、references/、tools/、requirements.txt、INSTALL.md、INSTALL_EN.md、LICENSE 和 CITATION.cff。其中，bin/ 提供命令入口，prompts/ 和 references/ 从名称上表明与提示词及参考资料有关，但资料未给出每个文件的接口和内容结构。

依赖与运行环境

项目仓库元数据将主要语言标记为 Python，README 的徽章要求 Python 3.9+；同时，package.json 将该项目作为一个 ES Module 类型的 Node.js 包，并规定 Node.js 版本为 >=18。这说明使用者至少需要区分 Python 相关运行条件和 Node.js 命令入口相关运行条件。

• Python：README 徽章标注为 Python 3.9+。
• Node.js：package.json 的 engines.node 为 >=18。
• 模块系统：package.json 的 type 为 module。
• Python 依赖：仓库发布文件包含 requirements.txt，但给定资料未列出其中的具体包和版本。
• 模型、数据库、HTTP 端口和外部服务：官方仓库资料未提供明确要求。

不能因为仓库的主要语言标记为 Python，就推断 Node.js 只是可选工具；也不能因为存在 requirements.txt，就推断所有流程都必须在 Python 虚拟环境中执行。更准确的做法是先按命令入口检查包，再依据当前版本的安装文档配置具体运行时。

快速开始：安装、运行与验证

给定资料能够支持一个不依赖外部服务的本地检查闭环：克隆仓库、进入指定默认分支、执行包自检脚本。资料没有提供完整的生产安装命令或模型调用命令，因此示例不伪造这类接口。

最小可运行示例

下面的命令使用仓库地址和默认分支信息，安装步骤采用本地克隆；运行步骤调用 package.json 中明确存在的 bin/distilly.mjs --check-package；验证步骤根据 shell 的退出状态打印结果。该示例只进行本地包检查，不向第三方目标发起请求。

git clone --branch dot-skill https://github.com/titanwings/distilly.git
cd distilly
npm install
node bin/distilly.mjs --check-package && echo "package check passed"

npm install 是在本地安装 Node.js 包依赖的安装步骤；仓库给定资料没有列出该命令对应的锁文件、依赖清单或安装输出，因此不应据此推断具体下载内容。验证命令使用的是包入口中由 package.json 的 prepack 脚本明确声明的 --check-package 参数。

Skill 目录准备

README 明确要求当前创建者 Skill 使用 distilly 这一目录名。以下命令只创建本地目录并检查当前路径，不会写入真实人物材料，也不会启动代理。

mkdir -p distilly
test -d distilly && echo "distilly directory is ready"

如果宿主的 Skill 安装方式需要复制文件、建立符号链接或放入特定本地发现目录，给定资料没有提供统一命令。此时应以仓库中的 INSTALL.md、INSTALL_EN.md 和目标宿主的 Skill 文档为准。

配置说明

仓库资料没有提供 .env.example、YAML 配置或 TOML 配置，因此能够核查的配置项主要来自 package.json。下表把包元数据、入口和发布行为分开列出；“默认值”仅填写资料中明确给出的值，不把缺失信息推断成默认行为。

环境变量、API 密钥、模型名称、端口号、日志级别和并发参数在给定资料中均未提供。不要把这些缺失项写入生产配置；官方仓库未提供该信息，建议以最新 README、安装文档和目标宿主说明为准。

进阶用法

进阶使用的重点是建立材料边界、人物范围和调用宿主之间的对应关系，而不是单纯增加提示词长度。因为仓库没有给出完整 API 签名，进阶流程应围绕已确认的 Skill 包结构进行验证。

按人物类别组织材料

对于同事或导师，可以优先整理共同工作中的决策、协作方式和具体案例；对于关系对象，可以明确哪些内容属于个人记忆、哪些内容来自直接交流；对于公众人物，则应区分公开作品、公开采访和使用者自己的解读。这样做有助于减少把用户推测误写成来源事实的风险。

这些材料组织建议是根据本文作者的经验判断，并非仓库声明的强制格式。项目资料没有给出材料目录模板、字段名或类别专用校验器，因此不能把上述结构当作官方输入协议。

选择支持的宿主

README 列出了 Claude Code、Hermes、OpenClaw、Codex、DeepSeek Harness、Pi、Grok Build 和 OpenCode 的本地 Skill 发现文档。使用者应先确认目标宿主是否支持本地 Skill 发现，再将创建出的 distilly Skill 放到宿主要求的位置。

如果目标是 Grok Bot，应注意 README 将其描述为单独的 saved-Skill workflow preview，而不是与前述本地发现机制完全相同的宿主流程。资料没有说明该预览的稳定性、接口和权限范围，因此不能把它当成与其他宿主等价的安装目标。

打包前检查

维护者可以利用 prepack 脚本在打包前执行 --check-package。这项检查能确认仓库已声明的包检查流程是否通过，但资料没有说明它会检查哪些文件、是否校验 Skill 内容、是否验证 Python 依赖，不能将它扩展解释为完整测试套件。

可观测性与运维

给定资料只确认了一个本地包检查入口，没有提供日志格式、指标、链路追踪、健康检查端点、后台进程、服务端口或 SLA。因而，项目更适合先按本地文件和命令退出状态进行运维核验，而不应假设它自带在线服务监控能力。

• 安装阶段：记录 Node.js 版本、Python 版本和当前 Git 分支。
• 包检查阶段：保存 node bin/distilly.mjs --check-package 的退出状态与终端输出。
• Skill 部署阶段：确认目录名称为 distilly，并确认目标宿主能够发现该目录。
• 内容维护阶段：为每个人物画像记录来源材料范围、更新时间和人工审核状态。
• 故障定位阶段：优先区分依赖安装失败、包检查失败、Skill 未发现和来源内容不足四类问题。

上述记录策略中的“人工审核状态”和“来源材料范围”属于根据本文作者的经验判断提出的运维建议，不是项目内置字段。仓库没有提供集中式日志、审计数据库或远程管理接口，因此这些记录需要由部署方自行建立。

安全与合规边界

项目处理的对象可能包括同事、家人、伴侣、朋友和公众人物，输入可能包含消息、访谈、文档或个人公开资料。它不属于网络攻击工具，但具有人格建模和隐私处理风险，使用时必须限定在有权处理的材料和授权环境内。

授权与隐私

• 只处理部署方有权收集、保存和分析的材料，不应把未经授权的私人聊天、内部文档或受限资料直接交给处理流程。
• 对真实人物建立画像前，应评估告知、同意、删除、更正和访问控制等要求；具体法律义务取决于部署地区和材料来源。
• 涉及未成年人、健康信息、财务信息、身份信息或内部机密时，应先完成组织内部的合规评审和最小化处理。
• 将公开资料用于公众人物画像，并不等于获得了任意再利用、商业化或冒充该人物的授权。
• 人物画像应明确标注其来源范围和生成属性，避免把代理输出当作真实人物本人意见。

隔离与访问控制

建议把原始材料、生成的 Person Profile 和宿主调用权限分开管理，并限制不必要的读取与写入权限。不要把 API 密钥、个人身份信息或内部材料写入公开仓库；本文没有提供任何真实密钥，示例中的敏感参数必须替换为由部署方安全保存的占位值。

仓库资料未提供加密方式、数据保留期限、删除命令、审计功能、CVE 修复承诺或合规认证信息。官方仓库未提供该信息，建议在正式部署前依据组织安全政策完成隔离、备份和删除验证。

许可证与商用条款

仓库使用 MIT License，LICENSE 文件的版权标注为 Copyright (c) 2026 titanwings。MIT 许可文本允许获得软件的人员使用、复制、修改、合并、发布、分发、再许可和销售软件副本，但实际使用仍应以仓库中的完整 LICENSE 文本为准。

分发软件或其主要部分时，必须保留版权声明和许可声明。许可证同时按“现状”（AS IS）提供软件，并明确排除适销性、特定用途适用性和不侵权等担保；作者在许可文本规定的范围内不承担因软件使用产生的责任。

• 可以在符合 MIT 条款的前提下进行商业使用。
• 再分发时应保留版权声明和许可条款。
• 不能把项目作者的名称、人物画像对象的身份或第三方资料授权，误解为 MIT 许可证自动授予的权利。
• 个人资料、公开人物资料和组织内部资料的使用权限，不由 MIT 许可证单独决定。

以上许可说明依据仓库 LICENSE 文件；涉及第三方内容、人物姓名、肖像、隐私或数据保护的额外义务，应以相关法律、合同和资料来源条款为准。

局限性与已知限制

项目的公开资料完整说明了定位和包入口，但没有提供足够的工程细节来证明它具备某些常被期待的生产能力。以下限制来自给定资料中的缺失或明确边界，不应被解释为对源码内部未公开行为的断言。

• 没有提供公开的性能基准、吞吐量、延迟、并发上限或资源消耗数据。
• 没有提供模型供应商、模型版本、推理参数或离线推理说明。
• 没有提供 HTTP API、端口、数据库、队列或容器编排配置。
• 没有提供输入文件格式、输出 Schema、版本化迁移规则或批量处理接口。
• 没有提供事实一致性、人物相似度、引用完整性或幻觉率评估指标。
• Person Profile 不等同于真实人物本人，也不应被用作身份认证、授权决策或事实来源的唯一依据。
• 公开资料中的 Star、Fork 和社区贡献数量描述属于仓库页面或 README 的时间点信息，不代表质量、稳定性或服务承诺。

如果业务需要强审计、可重复推理、数据驻留或长期稳定接口，应先检查当前仓库文档和源码是否已经补充相关实现，再决定是否将它纳入生产架构。

适合谁

以下信号表明使用者能够为项目提供必要的材料治理和宿主环境，适合把它作为本地 Skill 创建与管理工具进行评估。

• 团队已经使用 Claude Code、Codex、OpenCode 等 README 列出的宿主，并能管理本地 Skill 的发现路径。
• 用户拥有合法来源的消息、文档、访谈或公开资料，并能区分原始事实与个人推断。
• 需求是保留人物的决策模式、表达方式和工作上下文，而不是宣称获得真实人物的意识或授权。
• 团队可以审查人物画像内容，处理删除、更新、访问控制和敏感资料隔离。
• 项目处于本地实验、研究、个人知识整理或有限范围的代理工作流中，并接受先按仓库文档验证能力。

不适合谁

以下信号意味着项目的公开资料不足以直接满足需求，或者使用目标超出了 Person Profile 的合理边界。

• 需要有明确 SLA、官方托管服务、固定 API 版本、性能基准或高并发保证的生产系统。
• 没有获得材料处理授权，却希望批量分析私人聊天、内部文档或受限制的个人信息。
• 希望把生成画像当作真实人物的身份替代、法律意见、招聘决策依据或权威事实来源。
• 要求项目提供公开资料未声明的模型、数据库、端口、容器或远程 API 集成。
• 团队无法承担来源记录、人工审核、数据删除和宿主权限隔离工作。

在这些场景中，替代方案不能凭空指定，因为给定资料没有明确列出可比较的替代项目。根据本文作者的经验判断，应先补齐数据治理和接口要求，再评估是否继续采用该仓库。

常见问题与排查（FAQ / Troubleshooting）

为什么仓库语言是 Python，但示例使用 Node.js？

仓库元数据将主要语言标记为 Python，而 package.json 明确提供了 Node.js 包入口 bin/distilly.mjs，并要求 Node.js >=18。两项信息并不矛盾，但资料没有描述两者在完整执行链中的分工，因此应以当前安装文档为准。

执行命令时提示找不到 Node.js，如何处理？

先确认本地 Node.js 是否满足 package.json 声明的 >=18 要求，再重新执行包检查。仓库没有提供版本管理文件和安装脚本；如果仍然失败，官方仓库未提供该信息，建议以最新 README 和 Node.js 环境文档为准。

为什么找不到 Skill？

先确认目录名称是否为 distilly，再确认目标宿主是否属于 README 列出的支持本地 Skill 发现的宿主。由于各宿主的发现路径和安装方式未在给定资料中展开，不能用一个统一路径解决所有宿主问题。

--check-package 检查失败意味着什么？

该参数来自 package.json 的 prepack 脚本，用于执行 node bin/distilly.mjs --check-package。资料没有公开检查项和错误码，因此应保留完整终端输出，并检查发布文件列表、入口文件和本地依赖；具体失败原因需要结合当前源码判断。

项目是否会自动访问网络或调用模型？

给定资料没有提供网络请求说明、模型配置、API 参数或端口信息，不能确认完整流程是否包含外部服务调用。最小示例只执行本地仓库检查，不提供也不要求 API 密钥。

可以把人物画像直接发布给其他人吗？

技术上的 MIT 许可与人物材料的隐私、版权、肖像、合同和数据保护权利是不同问题。发布前应确认原始材料的授权范围，并避免将画像描述成真实人物本人发言或官方立场；仓库没有替使用者完成这些法律审查。

项目地址与资源

以下链接均来自仓库资料或 README 中列出的官方项目资源，适合用于核对当前分支、安装说明、宿主兼容性和许可证文本。

• distilly GitHub 仓库
• Python 官方网站
• AgentSkills 标准网站
• Distilly Discord 社区
• COLLEAGUE.SKILL 技术报告
• 社区技能画廊