# Gemworks

**装在对话窗口边的工作台。**

陪你做项目：管产物、总结经验、记住你定下的事，让流程自己长出来。就在你天天用的 Claude Code 里。

[English](README.md) | 中文

<!-- 截图待补：状态带和看板，放到 docs/images/band-and-board.png 后改成 ![状态带和看板](docs/images/band-and-board.png) -->

## 装上后你会看到

- **输入框上方多一行**：你在做哪件事、走到哪一步、等你定什么、接下来模型去做什么。
  轮到你拍板时，选项就是按钮；不点，直接打字回答也行。
- **一个看板**，五个页签：
  - **会话**：这个项目所有的会话，每轮问了什么、做了什么。
  - **工作项**：每件事走到哪一步、还差什么。
  - **产物**：做出来的文件、提交、页面、链接，按版本列着，点开就看。
  - **流程**：每条流程有哪几步、每一步防什么坑、上面挂着哪些做法。
  - **工具**：哪个工具在哪一步能用（进阶，平时不用管）。
- **新学到几条、有几条提议**：它从你的纠正里学到东西，就在这一行告诉你。

## 三个场景

**开着好几个会话。** 以前：换个会话就得重新交代进度，A 里定的事 B 不知道。
装上后：定下的事所有会话共用，每条提示词自动带上；看板上一眼看到每件事停在哪。

**一个项目做好几周。** 以前：纠正过的错还会再犯，CLAUDE.md 越写越长。
装上后：纠正一次就记成一条做法，挂在那一步上，做到那一步才提醒；
同一类纠正攒多了，它会提议在流程里加一步。

**做内容、做研究。** 以前：稿子改了好几版，图和链接散一地。
装上后：每件事做出来的东西都收进产物页，按版本列着，最新的一眼就能找到。

## 安装

需要 Node 22 以上（用 `node --version` 看一下）。

在 Claude Code 的输入框里逐行输入（Claude Code 2.1.275 以上）：

```text
/plugin marketplace add geml-spec/geml
/plugin install gemworks --marketplace geml-spec/gemworks
```

第一行加上 GEML 的插件市场，gemworks 要用到其中的 geml 插件，装的时候会一并装上；
第二行加上 gemworks 的市场并安装，装的时候选范围。

装完看安装提示的最后一句：写着 `Plugin is now active.` 就能直接用；
要重载的话，Claude Code 会替你运行 `/reload-plugins`，它若提示重载会让提示缓存失效，
就自己输入 `/reload-plugins --force`。

第一次启动时，它会在后台读一遍这个项目以前的会话，状态带上显示
「正在了解这个项目以前的会话（3/120），只存在本机 .geml/ 目录」。
读完以后，看板上就能看到以前的会话和产物。

## 流程怎么长出来

自带十条起步流程：**新设计**、**新功能**、**bugfix**、**优化**、**线上事故**、**代码审查**、**调研选型**、
**重构**、**文档**、**数据分析**。每一步都写着它防什么坑。
比如新功能的第一步是「样稿：你看过说行」，防的是「做出来不是你要的，返工最贵」。

用着用着，流程会长，也会减：

1. 你纠正了模型一句，或者这一轮吃了亏：返工、测试没过、你说没修好；
2. 它记成一条**做法**，挂在那一步上，下次做到那一步就提醒；
3. 同一类纠正攒多了，它**提议**在流程里加一步；几件活都套不上现有流程，就提议一类新的活；
   某一步在最近 5 件里跳过了 4 件，就提议删掉。都要你同意了才改；
4. 你觉得某条做法必须守住，就点「改成规定」：那一步没做到，相关的操作会被拦下。

做法分三层：**个人**的跟着你到每个项目；**项目**的只管这个项目；点「分享给团队」，它就写进仓库的
`.gemworks/`，你提交后同事也用上。别的项目的 `.gemworks/`，或者导出的流程文件，可以导入当参考，
里面的步骤会在流程页上提议给你。

## 你的数据在哪

- 记录、做法、产物都在项目主检出的 `.geml/` 目录里，留在你自己的电脑上。
- 为了从你的纠正里学，一个小模型会读你的每条提示词。它用的是你自己的 Claude Code 账号，
  不经过第三方。这项默认开着；不想要，就在看板设置里关掉「从你的纠正里提议做法和流程步骤」，
  关掉后它不再读你的提示词。
- 你的每次工具调用都会经过它，但它自己出了错一律放行，不会把你卡住。

## 别的宿主

不用 Claude Code 也能用。各家拿到的不完全一样：

| | 工作台 | 进度、产物、做法 | 每轮自动带上进度和做法 | 小模型从纠正里学 |
|---|---|---|---|---|
| Claude Code | 输入框上方一行 + 看板 | 有 | 有 | 有 |
| Pi | 编辑框上方一行，`/gemworks` 打开看板 | 有 | 有 | 有（用你当前的模型） |
| DeepSeek Harness | 网页侧栏 | 有 | 有 | 还没接，靠模型自己记做法 |
| Codex | 一页 GEML 看板 | 有 | 有 | 没有，靠模型自己记做法 |
| Antigravity | 一页 GEML 看板 | 有 | 有 | 没有，靠模型自己记做法 |
| Cursor | 一页 GEML 看板 | 有 | 有，随这一轮第一次工具调用的结果送到 | 没有，靠模型自己记做法 |
| Qwen Code | 一页 GEML 看板 | 有 | 有 | 没有，靠模型自己记做法 |
| OpenCode | 一页 GEML 看板 | 有 | 有 | 没有，靠模型自己记做法 |
| Devin（原 Windsurf） | 一页 GEML 看板 | 有 | 有 | 没有，靠模型自己记做法 |
| TRAE | 一页 GEML 看板 | 有 | 有 | 没有，靠模型自己记做法 |
| Kiro | 一页 GEML 看板 | 有 | 有 | 没有，靠模型自己记做法 |
| 其他接 MCP 的 | 一页 GEML 看板 | 有 | 模型调用它的工具时才带上 | 没有，靠模型自己记做法 |

「改成规定」、提议删掉一步、导入参考，目前只有 Claude Code 有。

**一页 GEML 看板**：每轮都会重写项目里的 `.geml/board.geml`，上面有等你定的事、
工作项、产物、流程，还有别的会话定下的事。在 VS Code 一类的编辑器里
（Cursor、Antigravity IDE 也行）装上 GEML 扩展，侧边打开就能看，文件一改自动刷新；
也可以用 Chrome 的 GEML Viewer 看，不过要手动刷新。这页上没有按钮，
要你定的事直接在对话里回答。

各宿主的安装方法见 [docs/hosts.zh.md](docs/hosts.zh.md)。

## 要一步都不能跳：固化流程

起步流程只提醒、不拦人，你点了「改成规定」的那几步除外。有些活必须按顺序来，
比如没真跑过测试就不许说做完、没你批准就不许上线，这时就加一条**固化流程**：
模型只能一段一段往下走；某一段不该用的工具，它一用就会被拦下，并被告知为什么。

自带四条，挑一条加进来：

| 流程 | 分几段 | 管住什么 |
|---|---|---|
| `coding` | 探索 → 计划 → 实现 → 验证 → 评审 | 计划好之前不许改文件；没有真实的测试结果不许说做完；最后要你批准 |
| `dev` | 构建 → 评审 → 部署 → 上线 | 上线要你批准 |
| `matter` | 记下 → 待你定 → 实施 → 待验收 | 开工、验收都要你点头 |
| `video` | 剧本 → 素材 → 剪辑 → 出片 → 审片 → 发布 | 一段做完才进下一段 |

**怎么加**：在输入框里输入 `/gemworks add coding`（换成你要的那条的名字）。
它会把这条流程复制进项目的 `.geml/workflows/`。项目里还没有固化流程的话，
这条就成了默认流程，之后新开的工作项都按它走。

**怎么限定工具**：哪个工具算"改文件"、哪个算"跑测试"，写在 `.geml/tools.geml` 里。
自带的已经按 Claude Code 的工具写好了，比如 `Edit`、`Write` 算改文件，
`Bash(npm test)` 算跑测试。要改的话，打开看板的「工具」页签就地改。
没写进去的工具，从来不拦。

想改段落、改顺序，或者自己写一条，看 [docs/advanced.zh.md](docs/advanced.zh.md)；
另外三条的详细说明在 [docs/workflows.zh.md](docs/workflows.zh.md)。

## 命令行 · 开发 · 许可证

- **命令行**：`gemworks`（简写 `gwx`）在终端里看状态、推进阶段、导出记录，见 [docs/cli.zh.md](docs/cli.zh.md)。
- **开发**：项目布局、怎么构建和测试，见 [docs/development.zh.md](docs/development.zh.md)。
- **许可证**：AGPL-3.0-only。只是使用，不用做任何事；改了代码再分发，
  或者让别人通过网络使用你改过的版本，就要按 AGPL 公开改过的源码。