1. 项目概述：一个由AI驱动的桌面角色扮演游戏引擎

如果你是一个桌面角色扮演游戏（TRPG）的爱好者，同时又对AI技术如何融入创意工作流充满好奇，那么SkillsWeaver这个项目绝对值得你花时间深入研究。它不是一个简单的脚本集合，而是一个完整的、由Go语言编写、并深度集成Claude Code AI能力的游戏引擎。简单来说，SkillsWeaver让你能和一个“AI地下城主”（Dungeon Master, DM）一起，在《龙与地下城》第五版（D&D 5e）的规则框架下，进行一场沉浸式的单人或多人在线冒险。

项目的核心价值在于，它将传统TRPG中由人类DM承担的叙事、规则裁决、场景描述和NPC扮演等繁重工作，部分交给了AI来协同处理。你不再需要苦苦寻找一个能固定时间开团的朋友，也不必担心自己作为新手DM经验不足。SkillsWeaver提供了一个从角色创建、冒险生成到实时游戏会话的完整闭环。它尤其适合那些想体验D&D魅力但苦于没有同伴的“孤狼”玩家，或者希望借助AI获得灵感和辅助的传统DM。

整个系统设计得非常巧妙，它没有试图用AI完全取代人类（那会失去TRPG社交和即兴的精髓），而是作为一个强大的协作者。AI负责处理规则查询、投骰计算、生成描述性文本和图像，甚至根据你提供的主题自动构建一个包含三幕结构的战役计划。而你，作为玩家或主持者，则专注于决策、角色扮演和推动故事。这种“人机协作”的模式，正是SkillsWeaver最吸引人的地方。

2. 核心架构与设计思路拆解

要理解SkillsWeaver如何工作，我们需要把它拆解成几个核心层次。这不仅能帮你更好地使用它，如果你有兴趣进行二次开发，也能快速抓住重点。

2.1 三层架构：技能、代理与工具

SkillsWeaver的架构清晰地分为三层，这是一种非常模块化和可扩展的设计。

第一层：技能（Skills） 技能是存储在 .claude/skills/ 目录下的Markdown文件。你可以把它们理解为写给Claude Code的“使用说明书”。每份说明书都详细描述了一个特定工具的功能、输入参数和输出格式。例如， dice-roller.md 会告诉Claude：“当用户说‘投一个d20’时，你应该调用 sw-dice 这个Go程序，并传递‘1d20’作为参数”。这一层是“声明式”的，它不包含任何执行逻辑，只定义接口和意图。

第二层：代理（Agents） 代理位于 .claude/agents/ 目录，同样是Markdown文件。如果说技能是教AI使用单一工具，那么代理就是教AI完成一个复杂的、多步骤的任务。例如， dungeon-master.md 定义了一个完整的“地下城主”角色：它的性格（公正、叙事性强）、它的目标（推进故事、维护规则）、以及它应该如何根据游戏进程，智能地组合调用各种技能（如先调用 roll_dice 判定攻击，再调用 log_event 记录战斗结果，最后可能调用 generate_image 生成场景图）。代理是AI的“大脑”，负责决策和流程编排。

第三层：工具（Tools） 这是实际的执行层，由Go语言编写的命令行工具（CLI）构成，位于 cmd/ 目录下。例如 sw-dice 、 sw-character 、 sw-adventure 等。这些是实实在在的、可以独立运行的二进制程序。它们接收参数，处理业务逻辑（如计算骰子结果、生成角色数据、管理JSON状态文件），并返回结构化的结果（通常是JSON格式）。这一层是“命令式”的，包含了所有具体的实现代码。

工作流示例 ：当你在Claude Code中对AI说“为我的战士角色‘Marcus’生成一张肖像”时，AI会查阅 image-generator.md 技能，理解到需要调用 sw-image 工具，并传递角色描述作为参数。然后，AI通过Claude Code的执行环境去运行 ./sw-image character Marcus 。工具执行后，将生成的图片路径返回，AI再把这个结果解读给你听。整个过程，AI是协调者，Go工具是执行者。

2.2 双模式游戏体验：Web与CLI的取舍

SkillsWeaver提供了两种主要的游戏方式：现代化的Web界面（ sw-web ）和传统的命令行界面（ sw-dm ）。这两种模式并非简单的UI替换，其底层实现和适用场景有显著区别。

Web界面模式：面向体验与便捷性 sw-web 是一个用Gin框架构建的本地Web服务器。它的设计目标是降低门槛，提供开箱即用的流畅体验。

  • 自动战役规划 ：这是其王牌功能。你只需要提供一个冒险主题（如“被诅咒的六分仪”），它就能调用AI生成一个完整的三幕式战役结构，包括核心冲突、反派动机、关键伏笔和节奏安排。这对于新手DM或急需灵感的资深玩家来说，是巨大的助力。
  • 实时流式响应 ：通过Server-Sent Events技术，DM的叙述能够像聊天一样逐字实时显示在网页上，沉浸感很强。
  • 状态集中管理 ：所有角色状态、库存、地图和聊天记录都直观地展示在同一个界面中，无需在多个终端或文件间切换。
  • 模型热切换 ：你可以随时在Haiku（快速）、Sonnet（平衡）和Opus（高质量）三种Claude模型间切换，根据当前场景（快速战斗 vs. 深度角色对话）选择合适的响应速度和创意水平。

CLI地下城主模式：面向深度与控制力 sw-dm 是一个运行在终端里的、自包含的AI代理循环。它不依赖Claude Code的协调，而是直接通过Anthropic API与Claude对话，并内置了完整的工具调用能力。

  • 完整的代理循环 ：它实现了标准的“用户输入 -> AI思考 -> 工具调用 -> 执行 -> AI回复”的循环。这意味着这个DM拥有更高的自主性，能够更主动地推动剧情和做出裁决。
  • 极致的响应速度 ：由于去掉了Web层和浏览器渲染的开销，并且在本地直接进行工具调用，其响应延迟通常更低，尤其适合快节奏的遭遇战。
  • 对开发者和高级用户友好 ：你可以直接看到AI的原始思考过程（如果开启调试），更容易理解AI的决策逻辑，也方便进行自定义和调试。

选择建议 ：如果你是初次接触，或者希望获得最完整、最视觉化的体验， 从Web界面开始 。如果你想追求最快的游戏节奏，或者作为一个开发者想要深入研究AI代理的行为， 使用CLI模式 。事实上，你可以用Web界面创建角色和冒险，然后用CLI模式进行游戏，两者共享同一套 data/ 目录下的数据文件。

2.3 数据持久化设计：JSON为核心的轻量级存储

SkillsWeaver没有使用复杂的数据库，而是采用基于JSON文件的轻量级存储方案，这非常符合其个人向、本地优先的工具定位。所有数据都保存在 data/ 目录下，结构清晰。

data/
├── characters/          # 所有创建的角色模板
│   └── marcus-sanggo.json
├── adventures/          # 每个冒险一个独立目录
│   └── the-lost-mine/
│       ├── adventure.json       # 冒险元数据（名称、描述、创建时间）
│       ├── campaign-plan.json   # AI生成的战役计划（三幕结构）
│       ├── party.json           # 当前队伍成员列表（引用character文件）
│       ├── inventory.json       # 队伍共享财产（金币、魔法物品等）
│       ├── sessions.json        # 游戏会话历史记录
│       ├── journal-meta.json    # 日志索引
│       ├── journal-session-0.json # 实际日志内容（按会话分割）
│       └── images/              # 生成的场景图片
└── world/               # 静态世界设定（可选）
    ├── factions.json    # 四大王国背景
    └── ...

这种设计的好处是：

  1. 可移植性极强 ：整个游戏状态就是一堆JSON文件，压缩后通过邮件或网盘就能分享给朋友继续冒险。
  2. 易于调试和修改 ：如果发现某个物品数据错了，或者想手动调整角色等级，直接用文本编辑器打开对应的JSON文件修改即可。
  3. 版本控制友好 ：你可以用Git来管理你的冒险历程，每次游戏结束后提交一次，相当于拥有了一个完整的冒险日志版本库。
  4. 与AI配合自然 ：Claude Code等AI工具非常擅长理解和生成JSON格式，方便进行批量操作或数据提取。

一个实操心得 ：定期备份你的 data/ 目录。虽然JSON文件很健壮，但误操作或程序Bug可能导致数据损坏。最简单的备份方式就是复制整个 data 文件夹。你也可以写一个简单的Shell脚本，在每次启动游戏前自动创建一个带时间戳的备份。

3. 从零开始：环境配置与首次运行详解

让我们抛开理论，直接上手。假设你是一个macOS或Linux用户（Windows用户可以通过WSL获得几乎相同的体验），以下是确保你首次运行成功的详细步骤。

3.1 环境准备：不仅仅是安装Go

第一步：安装Go语言 SkillsWeaver的所有核心工具都是用Go编写的，因此Go是必须的。项目要求Go 1.25或更高版本。

# 在macOS上，使用Homebrew是最简单的方式
brew install go

# 在Linux上，例如Ubuntu/Debian
sudo apt update
sudo apt install golang-go

# 安装后，验证版本并设置环境变量（通常Homebrew会自动设置）
go version
# 应该输出类似 go version go1.25.0 darwin/amd64

# 确保GOPATH和GOMODULE设置正确（现代Go项目通常使用Go Modules）
echo $GOPATH
# 如果没有设置，可以添加到你的shell配置文件（如 ~/.zshrc 或 ~/.bashrc）
# export GOPATH=$HOME/go
# export PATH=$PATH:$GOPATH/bin

第二步：获取Anthropic API密钥（核心） 这是驱动AI地下城主的大脑。无论是Web模式还是CLI模式，都需要它。

  1. 访问 Anthropic Console 。
  2. 注册或登录你的账户。
  3. 在Dashboard中，找到“Get API Keys”或类似选项，创建一个新的密钥。
  4. 复制这串密钥（通常以 sk-ant- 开头）。

第三步：（可选）获取fal.ai API密钥 这个密钥用于图像生成，为你的冒险日志添加视觉元素。它不是必须的，但强烈推荐，能极大提升沉浸感。

  1. 访问 fal.ai 。
  2. 注册账号，在控制台创建一个新的API密钥。
  3. fal.ai提供免费的初始额度，足够你生成相当数量的图片进行测试。

第四步：设置环境变量 不要将API密钥硬编码在代码或命令行中，最佳实践是使用环境变量。

# 打开你的shell配置文件，例如 ~/.zshrc 或 ~/.bashrc
nano ~/.zshrc

# 在文件末尾添加以下行，替换为你自己的密钥
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"
export FAL_KEY="your_fal_key_here" # 可选，但建议设置

# 保存文件并退出编辑器，然后让配置生效
source ~/.zshrc

# 验证环境变量是否已设置
echo $ANTHROPIC_API_KEY
# 应该显示你的密钥（部分隐藏）

重要安全提示 ：永远不要将你的API密钥提交到Git等版本控制系统。SkillsWeaver项目本身的 .gitignore 文件已经排除了包含密钥的本地配置文件。确保你的密钥只存在于本地环境变量中。

3.2 项目构建与工具编译

获取项目代码并编译所有命令行工具。

# 克隆项目仓库
git clone https://github.com/nicmarti/skills-weaver.git
cd skills-weaver

# 使用项目提供的Makefile进行一键构建（推荐）
make build

# 如果make命令不可用，或者你想了解细节，可以手动编译每个工具
go build -o sw-web ./cmd/web
go build -o sw-dm ./cmd/dm
go build -o sw-dice ./cmd/dice
# ... 以此类推，编译其他工具

编译完成后，你会在项目根目录看到一系列以 sw- 开头的可执行文件。你可以运行 ls sw-* 来查看它们。

编译常见问题排查 ：

  • go: command not found ：说明Go没有正确安装或没有加入PATH。请重新检查第一步。
  • 网络超时或依赖下载失败 ：由于某些Go模块可能托管在海外，国内网络环境可能不稳定。可以尝试设置Go代理： 
    go env -w GOPROXY=https://goproxy.cn,direct
  • 权限错误 ：确保你对项目目录有读写权限。

3.3 创建你的第一个角色与冒险

现在，让我们不通过任何界面，直接用最“硬核”的CLI工具来创建游戏内容，这能帮你理解数据是如何流动的。

创建角色 ： 我们创建一个人类战士和一个精灵法师，组成一个基础的二人小队。

# 创建战士 Marcus。使用标准属性点分配法（27点购点），这里我们用参数直接指定。
# 注意：参数名是缩写，--str代表力量，--dex代表敏捷，等等。
./sw-character create "Marcus the Shield" \
  --species=human \
  --class=fighter \
  --str=16 --dex=13 --con=15 --int=10 --wis=12 --cha=8

# 创建精灵法师 Lyra
./sw-character create "Lyra Starlight" \
  --species=elf \
  --class=wizard \
  --str=8 --dex=15 --con=14 --int=17 --wis=13 --cha=10

# 查看创建的角色
./sw-character list
# 你应该能看到刚刚创建的两个角色文件，例如 `marcus-the-shield.json` 和 `lyra-starlight.json`

创建冒险并将角色加入队伍 ：

# 创建一个名为“幽暗密林试炼”的冒险
./sw-adventure create "trial-of-gloomwood"

# 将两个角色加入这个冒险的队伍中
./sw-adventure add-character "trial-of-gloomwood" "Marcus the Shield"
./sw-adventure add-character "trial-of-gloomwood" "Lyra Starlight"

# 查看冒险状态，确认队伍和初始库存（通常有少量启动金币）
./sw-adventure status "trial-of-gloomwood"

至此，你的第一个冒险框架已经搭建完成。所有数据都保存在 data/adventures/trial-of-gloomwood/ 目录下。你可以用 cat 命令查看 party.json ，里面已经包含了角色的完整信息。

4. 核心玩法深度解析：与AI地下城主互动

配置好环境并创建了冒险之后，真正的乐趣开始了：与AI地下城主互动。无论是通过Web界面还是CLI，其核心交互模式是相通的——自然语言对话。

4.1 启动你的第一个游戏会话

通过Web界面（推荐新手） ：

# 确保在项目根目录，并且API密钥已设置
./sw-web
# 默认会在 http://localhost:8085 启动服务

打开浏览器访问上述地址。你会看到一个暗黑奇幻风格的界面。点击你刚创建的“幽暗密林试炼”冒险卡片上的“Play”按钮。页面会加载，左侧是队伍状态和库存，中间是聊天主界面。在底部的输入框，你就可以开始和DM对话了。

通过CLI界面（追求速度与深度） ：

./sw-dm

程序启动后，会列出 data/adventures/ 目录下所有的冒险。用键盘上下键选择“trial-of-gloomwood”，按回车。CLI会加载冒险上下文（队伍、地点、日志），然后显示一个 > 提示符。在这里输入你的行动即可。

4.2 高效交互：给AI清晰、具体的指令

AI很强大，但它的表现很大程度上取决于你如何与它沟通。以下是一些经过验证的高效交互模式：

1. 声明你的行动意图，而非直接要求掷骰 ：

  • 低效 ：“我攻击地精，掷攻击检定。”
  • 高效 ：“Marcus举起他的长剑，怒吼着向最近的地精发起攻击。” 或者 “Lyra试图用‘侦测魔法’来探查房间中央的石碑是否有魔法灵光。”
  • 为什么 ：后者为AI提供了丰富的叙事素材。AI会自行判断这属于“近战武器攻击”并调用 roll_dice 工具进行d20+力量调整值+熟练加值的计算，然后根据结果编织一段生动的战斗描述。你享受的是故事，而不是数字。

2. 在复杂场景中主动提供信息 ： 当场景中有多个元素时，帮助AI聚焦。

  • 示例 ：“我们之前在这个地窖里发现了一个上锁的宝箱和一幅奇怪的壁画。Lyra想先仔细检查壁画，看看有没有隐藏的机关或符号。”
  • 作用 ：这提醒AI调用相关的技能（如 log_event 记录调查，或 generate_image 生成壁画描述），并基于已有的“宝箱”和“壁画”这两个故事元素进行推理。

3. 利用AI进行规则查询 ： 如果你不确定某个法术的细节或专长的效果，可以直接问。

  • 示例 ：“DM，请告诉我‘法师护甲’这个法术的具体效果、施法时间和持续时间。”
  • 背后原理 ：AI会调用 spell-reference 技能，通过 sw-spell 工具查询内置的D&D 5e SRD数据，并给你准确的规则摘要。

4. 推动叙事，而不仅仅是反应 ： 不要总是等待DM描述场景后你再行动。主动提出你的角色想做什么，想去哪里。

  • 示例 ：“在短暂休整后，我向队伍提议，‘这个隧道似乎通向更深的地下。我担心有更多伏击。我建议Lyra用她的法师之手在前面探路，我们保持十尺距离跟随。’”
  • 效果 ：这给了AI一个明确的叙事方向（探索隧道、使用法师之手、保持警戒），AI可以据此生成相应的环境描述、潜在遭遇或技能检定。

4.3 理解AI的决策与工具调用链

当你输入一个动作后，后台发生了什么？以CLI模式为例，其代理循环大致如下：

  1. 用户输入 ： “Marcus小心翼翼地推开吱呀作响的橡木门，长剑举在身前，探查门后的房间。”
  2. AI思考 ：Claude模型接收到输入，结合当前游戏上下文（队伍在城堡一层，刚经历一场战斗，HP不满）。它判断这是一个“侦察/探查”动作，可能涉及“察觉”或“调查”技能检定，并且门后可能有陷阱或敌人。
  3. 工具调用决策 ：AI决定需要两个工具：
    • roll_dice ：为Marcus进行一个“察觉”检定（d20 + 察觉技能加值）。
    • log_event ：无论检定结果如何，都需要将“Marcus探查橡木门”这个事件记录到日志中。
  4. 工具执行 ：
    • sw-dice 被调用，参数为 1d20+2 （假设Marcus的察觉加值是+2）。程序生成一个随机数并返回结果，例如 {“total”: 15, “rolls”: [13], “modifier”: 2} 。
    • sw-adventure log 被调用，将事件文本写入 journal-session-*.json 文件。
  5. AI整合与回复 ：Claude收到工具执行结果。它看到察觉检定为15。根据DM的“地下城主”人设和预设的难度等级（DC），它判断这个结果足以让Marcus发现一些东西，但可能不是全部。于是它生成叙事：“Marcus缓缓推开门，门轴发出刺耳的呻吟。借着Lyra法杖顶端的光亮，他瞥见房间角落里有一堆散乱的白骨，以及墙壁上似乎有湿漉漉的反光。然而，房间深处笼罩在阴影中，看不太清。请进行一次调查检定，或者直接进入房间？”
  6. 流式输出 ：这个回复被逐词（或逐句）发送到前端（Web的SSE或CLI的stdout），形成一种实时讲述的感觉。

一个关键技巧 ：在CLI模式下，你可以通过启动时添加 --debug 标志来部分观察这个过程（注意，这可能会输出大量信息）。在Web界面，虽然看不到底层调用，但你可以通过观察“网络”选项卡中的SSE流，看到结构化的数据块。

5. 高级功能与定制化指南

当你熟悉了基础玩法后，SkillsWeaver的一些高级功能可以让你打造真正独一无二的游戏体验。

5.1 利用世界背景与自定义数据

项目内置了一个包含四个王国的世界观（ data/world/factions.json ），但这只是一个起点。你可以轻松地扩展它。

自定义你的世界 ：

  1. 编辑 data/world/factions.json ，添加你自己的王国、城邦或组织。确保JSON格式正确。
  2. 你甚至可以创建 data/world/locations.json 来定义具体的地点，如“黑荆棘酒馆”、“哀嚎峡谷”。
  3. 创建 data/world/npcs.json ，预先定义一些重要的NPC，包括他们的阵营、秘密和与玩家的潜在关系。

如何在游戏中引用自定义内容 ？当你和DM描述背景时，直接提及这些名字。例如：“我的角色Caelian来自我自定义的‘翡翠同盟’，那是一个由德鲁伊和游侠保护的森林国度。” AI在生成叙事时，会尝试将这些元素融入其中。更进阶的做法是，你可以修改 sw-dm 的初始化提示词（在代码中），直接告诉AI你自定义世界的核心设定。

5.2 战役计划与故事生成的艺术

Web界面的“自动战役计划”功能非常强大。它的工作原理是：将你提供的冒险主题和描述，发送给Claude模型，并要求其按照经典的三幕剧结构生成一个计划。

如何写出更好的主题描述来激发AI ：

  • 糟糕 ：“一个地牢冒险。”（太宽泛）
  • 一般 ：“寻找失落的神器。”（有目标，但缺乏冲突）
  • 优秀 ：“在‘沉寂山脉’脚下，‘黑水镇’的村民接连失踪。镇长悬赏勇士调查，线索指向一个被遗忘的矮人矿坑。但镇上的老巫师警告，矿坑深处沉睡着并非矮人造物，而是某个远古的、被封印的饥饿存在。” （包含了地点、事件、委托人、线索、危险和神秘感）

生成后的战役计划 保存在 adventures/<your-adventure>/campaign-plan.json 中。它是一个结构化的文档，通常包含：

  • 核心主题与基调 ：如“绝望中的希望”、“知识的代价”。
  • 三幕结构 ：
    • 第一幕：集结 ：介绍问题，队伍集结，初步调查，首个挑战。
    • 第二幕：对抗 ：深入敌后，遭遇挫折，发现真相，重大转折。
    • 第三幕：决战 ：最终准备，直面反派，结局与后续。
  • 主要反派 ：动机、能力、弱点。
  • 关键伏笔 ：在早期埋下，在中后期回收的线索。
  • 预计节奏 ：建议的游戏会话次数和每幕时长。

你可以且应该修改这个计划 ！AI生成的计划是一个出色的蓝图，但你不是它的奴隶。在游戏过程中，如果玩家有了意想不到的想法（他们总是会有），或者你觉得某个转折不够有趣，随时可以打开这个JSON文件进行编辑。DM在后续游戏中会参考这个计划，但也会根据实时互动灵活调整。

5.3 图像生成与日志增强实战

这是让冒险记录变得栩栩如生的功能。它分为两步：先用AI为日志条目生成丰富的描述，再根据描述生成图片。

第一步：日志增强 

# 首先，进行试运行，看看哪些条目会被处理
./sw-adventure enrich "trial-of-gloomwood" --dry-run

# 输出会显示哪些日志条目缺少描述，以及将生成的描述预览。
# 确认无误后，运行实际增强
./sw-adventure enrich "trial-of-gloomwood"

# 如果你想为最近5条日志生成描述
./sw-adventure enrich "trial-of-gloomwood" --recent=5

这个命令会调用Claude API，为每条日志生成 双语描述 （英文用于图像生成，法文用于阅读）。英文描述严格遵循“[角色]在[地点][行动]，氛围是[氛围]，视觉细节包括[细节]”的格式，以最大化图像生成模型的效率。

第二步：图像生成 

# 同样，先预览
./sw-image journal "trial-of-gloomwood" --dry-run

# 开始生成。默认使用快速模型‘schnell’，约3秒一张图，成本极低。
./sw-image journal "trial-of-gloomwood"

# 如果你想为最终的精美版冒险日志生成更高质量的图片
./sw-image journal "trial-of-gloomwood" --model=banana

生成的图片会保存在 data/adventures/trial-of-gloomwood/images/ 目录下，并以日志条目编号和类型（如 combat , exploration ）命名。Web界面在显示日志时，会自动加载对应的图片。

成本控制技巧 ： schnell 模型每张图约0.3美分， banana 约3.9美分。建议在游戏过程中或初次生成时使用 schnell 快速迭代，看看构图和风格是否满意。在冒险结束后，挑选最关键的10-20个场景，用 banana 模型重新生成一次，作为最终版的精美插图。这样既能控制成本，又能保证关键场景的质量。

5.4 自定义技能与代理

这是为开发者或高级用户准备的“杀手锏”。SkillsWeaver的架构允许你扩展它的能力。

创建一个自定义技能 ： 假设你想添加一个“天气生成器”技能，用于动态生成游戏世界的天气。

  1. 在 .claude/skills/ 目录下创建新文件 weather-generator.md 。

  2. 文件内容遵循现有技能的格式：

    # Weather Generator

When the user asks about the weather, or when you as the DM need to describe the environment, you can generate a dynamic weather condition.

## Tool: `sw-weather`
This tool generates a weather description based on location and climate.

**Usage:**
```bash
sw-weather [--location=<forest|mountain|city|...>] [--climate=<temperate|arid|cold|...>]

    Examples:

    • "What's the weather like in the forest?" -> sw-weather --location=forest --climate=temperate
    • "Generate a storm for the mountain pass" -> sw-weather --location=mountain --climate=cold --stormy

  3. 你需要实际实现这个 sw-weather 的Go工具。可以在 cmd/ 下创建 weather/ 目录，编写 main.go ，实现一个简单的随机天气生成逻辑，并输出JSON。

  4. 编译这个新工具： go build -o sw-weather ./cmd/weather 。

  5. 下次启动Claude Code或 sw-dm 时，它就会自动发现这个新技能，并在合适的时机调用它。

修改地下城主人设 ： sw-dm 的行为由其系统提示词（定义在代码内部）决定。你可以直接修改 internal/agent/ 或 cmd/dm/ 中的相关代码，来改变DM的说话风格、裁决倾向（是更偏向规则严格还是叙事自由）、甚至是它的知识背景（例如，让它更熟悉《魔戒》或《冰与火之歌》的设定）。这是一个更深入的定制层面，需要一些Go编程基础。

6. 故障排除与性能优化

即使设计再完善，在实际操作中也可能遇到问题。这里汇总了一些常见情况及其解决方法。

6.1 常见问题速查表

问题现象 可能原因 解决方案
运行 ./sw-web 或 ./sw-dm 时报 ANTHROPIC_API_KEY not set 环境变量未正确设置或未生效。 1. 确认已在终端执行 export ANTHROPIC_API_KEY=你的密钥 。
2. 或者将变量写入 ~/.bashrc 或 ~/.zshrc 后执行 source ~/.zshrc 。
3. 在当前终端会话中直接设置变量再运行程序。
Web界面能打开，但发送消息后长时间无响应或报错。 1. API密钥无效或余额不足。
2. 网络问题，无法访问Anthropic API。
3. 模型暂时不可用。		 1. 登录Anthropic Console检查密钥状态和余额。
2. 在终端用 curl 测试API连通性。
3. 尝试在Web界面的模型选择器中切换到另一个模型（如从Opus换到Haiku）。
图像生成失败，日志显示FAL_KEY错误或超时。 1. 未设置FAL_KEY。
2. fal.ai服务暂时故障。
3. 生成的图片描述（Prompt）不符合其内容政策。		 1. 检查并设置 export FAL_KEY 。
2. 访问 fal.ai status 页面查看服务状态。
3. 尝试更简单、更符合奇幻风格的描述。可先用 --dry-run 查看生成的英文Prompt。
CLI模式下，AI的回应变得奇怪或脱离上下文。 对话历史过长，导致触发了模型的上下文窗口限制（通常200K tokens），较早的上下文被丢弃。 1. 这是预期行为。 sw-dm 会自动管理上下文，优先保留最近的对话和关键的游戏状态。
2. 对于超长战役，可以考虑在自然段落（如完成一个地城章节）后，手动重启 sw-dm 并让AI基于日志摘要开始新会话。
编译Go工具时失败，提示 missing go.mod file 或依赖错误。 未在项目根目录执行命令，或者Go模块未正确初始化。 1. 确保在 skills-weaver/ 目录下执行 go build 。
2. 运行 go mod tidy 下载并整理依赖。
3. 检查网络，必要时配置Go代理。
角色或冒险数据看起来损坏，程序读取时报JSON错误。 可能手动编辑JSON文件时格式错误（如缺少逗号、引号）。 1. 使用 jq 工具验证和格式化JSON文件： jq . data/characters/your-character.json 。
2. 从备份中恢复文件（再次强调备份的重要性）。
3. 如果问题不大，可以用文本编辑器仔细对照修复。

6.2 性能与成本优化建议

响应速度 ：

  • 模型选择 ：Haiku模型响应最快，成本最低，适合战斗轮、探索检定等需要快速回应的场景。Sonnet平衡速度和质量，适合一般叙事。Opus最智能、创意最丰富，但速度慢、成本高，适合重要的剧情转折点或最终Boss战独白。 在Web界面中善用模型切换器 。
  • 上下文长度 ：AI需要处理的上下文（之前的对话、角色数据、日志等）越长，响应越慢且Token消耗越多。虽然 sw-dm 会智能截断，但在长时间游戏后，主动重启一次会话可以显著提升后续响应速度。

API成本控制 ：

  • 理解计价 ：Anthropic API按Token数计费（输入+输出）。冗长的描述、庞大的角色数据、过长的历史记录都会增加输入Token。AI生成的冗长叙述则增加输出Token。
  • 实战策略 ：
    1. 角色卡精简 ：在创建角色时，背景故事写个概要即可，无需长篇大论。AI能从概要中发挥。
    2. 对话风格 ：作为玩家，你的输入可以精炼。作为DM（如果你用AI辅助），在要求AI生成描述时，可以加一句“请用三句话左右描述这个场景”，这能有效控制输出长度。
    3. 善用日志 ： sw-adventure enrich 功能很实用，但为每一条日志都生成描述会产生API调用。可以定期（如每次游戏结束后）批量处理一次，而不是实时开启。
    4. 图像生成节制 ：如前所述，用 schnell 模型做草稿， banana 模型做终稿。只为真正 memorable的场景生成高质量图片。

存储与维护 ：

  • data/ 目录会随着游戏进行而增长，尤其是图片文件。定期清理不再需要的旧冒险目录。
  • 考虑将整个 data 目录纳入云同步（如iCloud Drive, Dropbox），以便在多台设备间继续你的冒险。但请注意，如果同步服务对文件数量敏感，图片文件夹可能会带来压力。

SkillsWeaver打开了一扇新的大门，它让我们看到了大型语言模型在创意和娱乐领域极具潜力的应用方式。它不是要取代朋友间围桌而坐的欢笑与友情，而是为那些时间难以协调、或渴望独自探索奇幻世界的玩家，提供了一个充满智能与惊喜的伙伴。从一行命令开始，创建你的角色，构思一个冒险的火花，然后踏入门后的未知。剩下的，就交给AI和你共同的想象力去书写吧。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 复杂指令执行失败排查：为什么你的 RAG 管道吞掉了嵌套 JSON？

avatar DeepSeek技术社区
cover

DeepSeek Golang SDK 接入实战：多租户 API 网关的配额与熔断设计

avatar DeepSeek技术社区
cover

DeepSeek 成本看板搭建实战：如何从 per-token 粒度优化推理账单

avatar DeepSeek技术社区