funcpn/volens

volens（如意）

volens 是一个面向编码智能体的插件。它维护一套结构，让项目的文档与决策保持同步、永远新鲜——设计文档跟随你做出的每一个决策，而你完全不必操心。而且你只需在项目中设置一次：咒语一旦施下便持续生效，无需每次改变想法时重新施法。

适用于：

- Claude Code
- Codex CLI、ChatGPT 桌面应用
- DeepSeek Harness（DSH）

计划支持更多智能体。

为什么你需要 volens

得益于模型能力的快速提升和智能体产品的成熟，我们的想法可以在智能体的帮助下从念头变成可运行的代码，而不会因为自身不具备的技术知识而被挡在门外。但在从一个粗略想法到一件完成作品的过程中，还会发生另一件事。当我们把想法细化、逐一推敲每个细节、在构建过程中学习和选择技术时，脑海中的蓝图一直在变——这些变化可能推翻先前的决策，也可能让我们在同一个决策上反复摇摆。而随着时间推移，手工维护的设计文档会悄悄过时：它们误导我们，让项目变得混乱，也让模型更容易产生幻觉。

volens 正是为解决这一问题而构建的插件：

- 它维护一份只追加的决策日志（docs/DECISION-LOG.md），记录我们做出的每一个决策，使每一个决策都可追溯；

- 它从该日志派生设计文档（docs/DESIGN.md）并可自动更新，让设计文档与决策保持同步、永远新鲜，而我们无需操心；

- 无论你是在落地一个新想法，还是在迭代一个已有项目，volens 都能帮上忙——它让设计快照跟随你的决策。

volens 让设计文档与你的思考保持同步。让你的智能体依据设计文档实现代码，项目就会如你所愿地成型。

工作原理

在项目中运行一次 volens（Claude Code：/volens:volens；Codex：$volens:volens；DSH：/volens）。它首先勘察项目中已有的内容（不会覆盖任何东西），然后放置以下文件：

- 项目指令文件中的契约模块——Claude Code 上是 CLAUDE.md，Codex 和 DSH 上是 AGENTS.md（DSH 会同时加载两个文件，仅当内容完全相同时才去重）。如果文件不存在，它会创建一个仅包含契约模块的文件；如果已存在，它会在标记之间插入或更新该模块，其中包含文档模型 + 工作约定。文件中的其他内容一概不动。
- docs/DECISION-LOG.md——一份只追加的决策日志，初始包含一条记录，记载采纳此结构的决策。此后每一个设计决策都追加到这里；历史只增不改。
- docs/DESIGN.md —— 一份从日志中派生出的设计快照。已有项目在脚手架生成时就会得到一份；全新项目会跳过它，同步机制会在首次同步时根据决策日志生成它。
- .volens/lang —— 关于本项目文档以何种语言记录的“项目级决策”，写为一个语言标签（zh、en、pt-BR），只询问一次并提交。不是标签的值会被忽略：同步机制会回退到你的偏好设置，并在下一次同步通知中说明这一点。（早期版本会把它写到 .claude/volens.lang；旧项目的文件仍然有效，volens 会在下一次刷新时把它移到新位置。）
- docs/.volens-cursor —— 同步机制的游标：它记录设计文档已经反映到日志的哪个位置。纯运行时状态；写入 .gitignore，永不提交。

同步机制本身随插件一起发布，永远不会写入你的项目 —— 上述文件是 volens 在那里添加的唯一文件。

有了这些之后，日常的保鲜运行在一个追加 → 通知 → 增量同步循环上：

1. 决策落地 —— 每次你做出设计决策时，向 docs/DECISION-LOG.md 追加一条记录（Context → Decision → Consequences）。只追加；永不重写历史。
2. 同步通知 —— 它在每个会话时刻自动运行（Claude Code：Stop（一次回复结束）和 SessionStart（一个会话开始）；Codex：UserPromptSubmit，在你发送的每条消息上；DSH：在每个回合的开头，来自进程内插件），将日志的行数与 docs/.volens-cursor 游标进行比较。
3. 增量被注入 —— 如果日志中有超出游标的行，恰好这些行会作为额外上下文交给 agent 以进行同步；如果设计文档已经是最新的，游标会被静默快进。
4. 只重新生成受影响的部分 —— agent 只更新设计文档中受影响的部分、“生效中的设计决策”列表以及“最后重新生成”头部。它不会重新读取整个日志或重写整个文档。如果日志被重写或回滚（行数下降），游标会被重置，并请求对 docs/DESIGN.md 进行完整重建。

因此 docs/DESIGN.md 始终是设计“截至当前”的快照 —— 从日志派生，自动保持新鲜。你来做决策；volens 处理其余的事。

同步机制做什么 —— 以及不做什么

同步机制随插件一起发布。在 Claude Code 上，它由 hooks/hooks.json 注册，并在 Stop（一次回复结束）和 SessionStart（一个会话开始、被清除或被压缩）时运行；在 Codex 上，它由 hooks/hooks-codex.json 注册，仅在 UserPromptSubmit 时运行 —— 即你发送的每条消息。这两者共用一个 shell 脚本。DSH 完全不经过 hook：同样的逻辑作为 JavaScript 在其自己的进程内运行（index.js），在每个回合的开头触发。
它读取什么 —— docs/DECISION-LOG.md 的行数、存储在 docs/.volens-cursor 中的数字、docs/DESIGN.md 的修改时间，以及你的语言偏好（~/.config/volens/lang —— 或在设置了 XDG_CONFIG_HOME 时位于其下 —— 或项目的 .volens/lang）。

这就是全部清单。它从不读取你的日志、设计文档或源代码的内容 —— 它只统计一个文件中的行数并比较一个时间戳。

它写入什么 —— 恰好一个文件，docs/.volens-cursor。它本身不写入 docs/DESIGN.md：它会发出一个提示，要求 agent 去写入，并且只有当该写入落地后，游标才会前进。

它不做什么：

- 无网络。 没有 HTTP，没有套接字，没有遥测，没有分析。没有任何东西离开你的机器。
- 不在 docs/ 之外写入。 它从不触碰你的源代码或指令文件，并且它只读取 .volens/lang。
- 不执行你项目中的任何内容。 逻辑是固定的，并随插件一起发布：在 Claude Code 和 Codex 上它是一个 shell 脚本，在 DSH 上它是运行在 agent 自身进程内的插件代码。
- 不阻塞。 在 Claude Code 和 Codex 上它始终以 0 退出；在 DSH 上它不返回任何决策。无论哪种方式，它都只能向对话中添加上下文 —— 它不能停止一个回合或拒绝一次工具调用。
- 不注入到子代理会话（DSH）。 子代理继承其父级的工作目录，无法对增量采取行动，因此 DSH 会跳过它。

当没有任何需要同步的内容时，它不打印任何内容。沉默意味着没有注入任何内容 —— 而不是某些东西失败了。

安装

先决条件：

- git 在你的 PATH 中
- git 可以访问 GitHub
- 一个用于运行该钩子的 bash

macOS 和 Linux 自带一个；在 Windows 上，安装 Git for Windows —— 而如果你有 WSL，它放在 Windows\System32 中的 bash.exe 不算数：它是一个进入 Linux 发行版的启动器，无法运行该钩子。

DSH 在这两点上都是例外：它的那一半在进程内运行，并且它的 skill 随同一个 npm 包一起发布，因此它既不需要 bash，也不需要检出此仓库。

在 Claude Code 中安装

1. 添加市场：

/plugin marketplace add https://github.com/funcpn/volens.git

2. 从市场安装：

/plugin install volens@volens

3. 确认已安装：运行 claude plugin list，查找状态为 ✔ enabled 的 volens@volens。

在 Codex 中安装

volens 也通过 Codex 自己的市场机制作为插件安装到 Codex 中：

1. 添加市场：

codex plugin marketplace add https://github.com/funcpn/volens

2. 从市场安装：

codex plugin add volens@volens

3. 确认已安装：运行 codex plugin list，查找状态为 installed, enabled 的 volens。

市场和插件共享名称 volens，这就是为什么安装行读作 volens@volens —— 市场在前，插件在后。

在 ChatGPT 桌面应用（Codex）中安装
同一个插件，同一套机制：在应用的插件界面中，添加市场 https://github.com/funcpn/volens（将 Git ref 留空）并安装 volens。之后用法与 Codex 完全一致——volens:volens 会出现在斜杠菜单中。

只有两点不同，而这两点在你依赖它们之前都值得了解：

- 安装并不会授权该 hook，也不会有任何提示。 不受信任的 hook 会被静默跳过——没有对话框、没有徽标、没有注入——因此插件看起来一切正常，而 docs/DESIGN.md 却悄悄停止更新。要授权它，请打开 volens 的插件详情（管理）页面，在 “1 hook needs review before it can run” 下选择 Trust all。该页面显示的是它询问的命令字符串——即将要运行哪个文件——而不是脚本的内容，并且信任绑定到该字符串：之后插件更新只要不改动该命令，就不会再次询问。
- 同步通知以工具提示的形式出现，而不是对话中的一行。 将鼠标悬停在会话中的 hook 图标上即可看到；终端 CLI 会以内联方式打印同样的通知（↳ Hook · 📝 DECISION-LOG …）。

在 DSH 中安装

DSH 不像另外两者那样读取插件清单。它把 cordis bundles——附带配置层的 npm 包——加载到自己的进程中，并且从已注册的提供方发现技能，而不是从插件的清单中发现。volens-dsh 同时兼具两者：同步插件和技能打包在同一个包中，因此无需手动放置任何东西。

1. 将其安装到一个 profile 中：

dsh plugin --profile web add volens-dsh

这相当于在 ~/.dsh/profiles/web 内运行 pnpm add；web 是随附的 web 模板，如果你的 profile 名称不同，请替换为你自己的名称。该包声明了一个 bundle，因此安装它会使它的层对该 profile 可用——并且它会注册自己的技能，这就是为什么 DSH 重启后 /volens 会出现在菜单中。

2. 重启 DSH：profile 的补丁和插件模块在进程启动时读取。

在你依赖它之前，有两点值得了解：

- 更新意味着要指定版本。 该命令在 profile 内运行 pnpm add，而只要记录的版本范围仍被满足，pnpm 就不会动已安装的包——对已安装的副本运行 add volens-dsh 会报告 “Lockfile is up to date” 并且不做任何更改。请改为指定版本（add volens-dsh@0.4.0）；如果该发行版比 profile 的供应链策略所允许的更新，CLI 会说明这一点，并在安装前将其添加到 profile 的 pnpm-workspace.yaml 中的 minimumReleaseAgeExclude。技能打包在同一个包中，因此会随之一起到达。
- 同步通知以折叠的上下文行的形式出现，而不是单独的一行。 寻找一个带有 volens 的小上下文图标以及旁边的通知文本——它位于工具调用行所在的位置，很容易被滚动略过。同步并不依赖于你是否看到它。

替代方案：从 ZIP 安装
如果 git 无法访问 GitHub，Claude Code 和 Codex 可以通过下载来安装。下载和解压的方式相同；区别在于将文件夹放到正确位置的方式。(DSH 不需要这样做：它的包来自 npm，技能就在其中。)

首先获取文件夹：

1. 打开此仓库的 Releases 页面，在最新版本下，下载 Source code (zip) —— 或者打包好的 zip(如果该版本附带了一个)
2. 解压它。文件夹名称带有后缀(volens-0.4.0、volens-main……)—— 将其重命名为 volens

Claude Code —— 将整个文件夹移入你的技能目录：

- macOS / Linux：~/.claude/skills/
- Windows：%USERPROFILE%\.claude\skills\

如果该目录不存在，请创建它。你最终应该得到 …/.claude/skills/volens/，其中包含 .claude-plugin、skills 和 hooks。重启 Claude Code，然后运行 claude plugin list，确认你看到 volens@skills-dir，状态为 ✔ loaded。

Codex —— 文件夹可以放在任何位置(比如 ~/plugins/volens)；将其添加为本地市场：

codex plugin marketplace add ~/plugins/volens
codex plugin add volens@volens

运行 codex plugin list，确认状态为 installed, enabled。你的第一个会话同样会显示 Hooks need review —— 选择 Trust all and continue。

如何使用它

插件只会在你重启一次你的 agent 之后加载。之后，在你想要纳入该结构的项目中，运行：

在 Claude Code 上：

/volens:volens

在 Codex 上：

$volens:volens

在 DSH 上：

/volens

Codex 会在首次运行时要求你信任这些 hooks 一次。 你的第一个 Codex 会话会显示 Hooks need review —— 选择 Trust all and continue。如果不这样做，插件虽然已安装，但设计快照永远不会更新。

DSH 没有命名空间，也没有需要信任的 hook。 该技能就是菜单中裸的 /volens；插件随其 profile 一起加载，因此只需重启进程即可。

它会调查已存在的内容(它不会覆盖任何内容)，设置文档语言(仅一次)，确保契约模块就位，初始化 docs/DECISION-LOG.md，并确认同步机制已生效(Claude Code 和 Codex 上是 hook，DSH 上是进程内插件)。从那时起，每当设计决策发生变化，就向日志追加一条记录；同步机制会处理其余的事情。

许可证

本项目基于 MIT 许可证开源 —— 参见 LICENSE。