-
Notifications
You must be signed in to change notification settings - Fork 0
tool creation guide
本文档一步步说明如何从零创建一个完整的 know-yourself 心理学工具。
你需要先决定创建哪种类型的工具，因为不同类型在格式和内容上有本质区别。工具规范 tool-spec.md 中定义了五种类型。
评测类工具用于测量用户的某种心理特质或状态，比如价值观评测、依恋类型评测。这类工具的核心是题库和计分算法，输出是评测报告。
对话探索类工具通过开放式对话引导用户探索某个主题，比如探索个人信念、复盘梦境。这类工具的核心是对话策略和引导技巧，输出是探索记录或档案。
引导练习类工具提供结构化的练习步骤，用户按照指引完成某个心理练习，比如冥想引导、认知重评练习。这类工具的核心是练习脚本和引导词，输出是练习记录。
结构化对话类工具在特定框架下与用户进行有目标的对话，比如苏格拉底式提问、认知行为对话。这类工具的核心是对话框架和角色定义，输出是对话摘要。
元工具类工具是对其他工具进行管理和配置的辅助工具，不直接面向心理探索。这类工具需要根据具体管理功能来设计交互方式。
在确定类型时，想清楚你的工具最终要产出什么、用户和它的交互方式是什么样的，然后对号入座。
在对应 know-yourself-{模型名}/ 目录下的 tools/ 中创建以工具名命名的文件夹。工具名建议使用英文或拼音，简洁且能体现工具内容。
在该文件夹下创建 知识库/ 子目录。知识库文件统一放在这个子目录中，Skill 主文件则直接放在工具名的根目录下。
最终的目录结构应该是这样的：
know-yourself-{模型名}/
tools/
{工具名}/
{工具名}.md ← Skill 主文件
知识库/
overview.md ← 知识库文件
...
Skill 主文件是工具的核心，AI 加载它之后才能理解自己要扮演的角色和要完成的任务。创建时以 templates/skill-template.md 为起点。
元信息必须完整。工具类型名称、用途描述、目标用户、核心概念列表、理论基础，这些字段在文件开头的元信息区定义，一个都不能少。元信息不仅用于 AI 理解工具，也用于注册器扫描和 map.md 的生成。
AI 角色定义和行为边界必须清晰。你需要告诉 AI 它扮演什么角色、有什么专业背景、对待用户的态度是什么样的。更重要的是，要明确告诉 AI 它不应该做什么——不能给出诊断结论、不能超出自己的专业范围回答。
模式判断逻辑必须覆盖用户可能的输入。用户的对话在工具运行过程中会呈现不同的形态：有些是回答问题、有些是询问概念、有些是偏离话题、有些是想结束对话。你的 Skill 主文件需要定义这些模式以及对应的处理方式，确保 AI 在任何情况下都知道该怎么做。
知识库文件为 Skill 主文件提供背景知识支撑。AI 在对话中需要查询这些知识来理解用户的回答、给出准确的反馈。
不同类型的工具需要不同类型的知识库。
评测类工具的知识库通常包含以下文件。总览文件 overview.md 概述评测的主题、理论基础和整体框架。各维度文件按维度分别创建，详细描述每个维度的含义、特征表现和相关理论。题库文件 items.md 收录所有题目及其维度映射。
对话探索类工具的知识库需要包含以下内容。概念文件解释探索主题涉及的核心概念和理论背景，帮助 AI 理解用户提到的内容背后的含义。探索对话指南文件说明探索的目标、阶段划分和引导策略，让 AI 知道如何推进对话。
引导练习类工具的知识库侧重于操作层面。技术详解文件说明练习所基于的技术原理和步骤分解。引导词文件提供具体的引导语言范例，帮助 AI 掌握语气和节奏。
这一步只针对评测类工具。题库的质量直接决定了评测工具的可用性。
根据 templates/quiz-template.md 的格式编写题目。每道题需要包含题目标号、题目正文、选项列表以及每个选项对应的维度映射信息。维度映射是指每个选项属于哪个维度以及在该维度上的分值。
维度映射要清晰。一道题目可能只测一个维度，也可能同时测多个维度。无论哪种情况，每个选项的维度归属和分值都必须明确无误，不能有歧义。
计分规则要定义完整的判定逻辑。原始分如何汇总、维度分如何计算、最终结论如何生成，这些规则需要写在 Skill 主文件中的计分部分。计分逻辑应该考虑边界情况，比如用户跳过了某些题目应该怎么处理。
完成所有文件的创建后，做一次完整的验证。
首先确保产物符合产物规范。用 output-spec.md 中定义的格式要求逐一对照你的工具产出的内容。产物格式错误是提交后最容易被发现的问题，也是最容易避免的问题。
然后确保 AI 的输出格式符合要求。Skill 主文件中定义了 AI 的输出格式要求，检查这些要求是否足够具体、是否覆盖了所有需要格式化的输出场景。
最后运行注册器。注册器会扫描工具目录并更新 map.md。如果没有自动化注册器，手动在 map.md 中添加工具信息也可以，但要注意格式与其他条目保持一致。注册信息包括工具名称、类型、路径和简要描述。