1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | storybloq |
| 作者/维护者 | Story bloq（GitHub 组织账号，核心维护者 Amir Shayegh，npm 包维护者账号 ashayegh） |
| 来源链接 | https://github.com/Storybloq/storybloq |
| 许可证 | PolyForm Shield 1.0.0（源码可见、非竞争许可，取自仓库 LICENSE 文件） |
| GitHub Stars | 669（GitHub API 获取） |
| Forks | 35（GitHub API 获取） |
| 最新版本 | v1.7.0，发布于 2026-07-11（GitHub Releases API 获取） |
| 安装方式 | npm 全局安装 + storybloq setup；另提供 Mac App Store 原生桌面应用 |
2. 功能介绍与亮点
storybloq 把“跨会话的项目记忆”落地成仓库里的普通文件：所有工单（tickets）、问题（issues）、路线图阶段与交接记录都以 JSON/Markdown 形式存放在项目根目录的 .story/ 下，任何编码 agent 或人都能直接读写。
核心组成：
- CLI（
storybloq）：检查、修改.story/目录中的项目状态 - MCP Server：为 Claude Code、Codex 提供结构化工具调用接口，避免每次调用都启动子进程
- Skill：Claude Code 中用
/story、Codex 中用$story触发，会话开始时自动加载最新交接记录、未完成工单与问题列表，让下一次会话“接着上一次继续”而不是从零解释项目背景 - 原生 macOS App（Mac App Store 分发）：以看板形式实时展示工单与问题，与 CLI/MCP 写入的同一份文件双向同步
项目自 2026-04-17 创建至今约 3 个月，已有 13 个正式发布版本、npm 近一个月下载约 1,579 次；GitHub issue 区可见多名独立用户提交详细技术报告并参与调试，一处“符号链接被覆盖”的缺陷从上报到修复不到一天，一处 macOS 客户端读取工单失败的问题在维护者与用户共同排查下约两周内解决，响应速度和过程透明度都较为突出。
3. 适用场景
固定分类：元技能与 Agent 增强。
适合长期在同一项目上反复开合会话、且可能同时使用 Claude Code 与 Codex 的中高级开发者与小团队：会话因上下文压缩、--resume、崩溃恢复或更换设备而中断后，工单、交接记录与路线图不会随之丢失；也适合需要给非技术同事一个可视化看板、了解 agent 当前在做什么的场景。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持，
SKILL.md中明确定义了 claude client profile，以/story触发 - Codex：✅ 原生支持，
SKILL.md中通过STORYBLOQ_CLIENT=codex定义了独立 client profile，以$story触发 - OpenClaw：❓ 未验证，抓取到的
SKILL.md与 README 中只区分 claude 与 codex 两种 client profile，未提及该平台 - Hermes Agent：❓ 未验证，理由同上
5. 推荐理由
多数“记忆类”技能解决的是“让 agent 记住聊过什么”，这一个解决的是更具体的工程问题——工单、交接记录与路线图这些本该随项目一起进版本库的东西，不该因为一次会话重置就消失。它用普通文件而非账户或云端数据库承载状态，CLI、MCP、Skill 三件套覆盖了查、改、自动加载三个环节，且维护者对缺陷反馈的响应速度经 GitHub issue 记录可查证。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | 669 stars、35 forks，创建仅约 3 个月；npm 近一个月下载约 1,579 次；issue 区有多名独立用户提交详细技术报告并主动参与调试，显示真实活跃使用，但尚未达到千 star 级别的大规模热度 |
| 可用性 | 8 | 两条命令即可完成安装（npm 全局安装 + setup），依赖 Node.js 20+；13 个正式发布版本，文档基本完整；缺陷响应极快（symlink 覆盖问题当日修复，macOS App 读取失败问题约两周内修复并经用户确认）；SKILL.md 具体安装落地路径在 README 中说明不够详尽，原生 macOS App 仍有个别未解决的小问题（如持续 CPU 占用） |
| 安全性 | 8 | ①CLI 会写入项目内 .story/ 目录及全局 ~/.claude/settings.json（用于注册 hook），范围有文档说明，且此前发现的 symlink 覆盖风险已在当日修复；②未发现向第三方服务器外发数据的证据，官方定位为“无服务器、无账户”，内部 status.json 仅用于本地/自有客户端展示；③无需 API Key 或其他凭据；④抓取到的 SKILL.md 与 issue 讨论中未见可疑指令或提示词注入迹象；⑤维护者为可查证的真实 GitHub 账号，修复过程公开透明；⑥License 为 PolyForm Shield 1.0.0，条款清晰（允许个人/内部/商业使用，禁止用其代码构建竞品或转售托管服务）；⑦最新版本 8 天前发布，维护活跃 |
| 综合分 | 7.3 | 三项均值 |
7. 跟同类 Skills 相比的优势
“跨会话项目记忆”这个方向已有几种不同取舍的实现：
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| storybloq（本技能） | 仓库文件（.story/）+ CLI + MCP Server + 原生 macOS 看板 App 四件套 |
以人类可读的工单/问题/路线图结构呈现状态，而非语义摘要；提供原生桌面看板做实时可视化 |
| claude-mem | 5 个生命周期钩子自动捕获操作，AI 压缩后存入本地 SQLite + 向量库，按需检索注入 | 记忆自动化程度更高，覆盖 Claude Code、OpenClaw、Codex、Hermes 等更广的 agent 生态，但呈现形式是语义摘要而非结构化工单看板 |
| project-butler | 会话日志 + 项目 wiki + 规则 + TODO + handoff 的项目记忆系统 | 覆盖场景相近，但不含 MCP Server 与原生桌面 App，社区体量更小 |
storybloq 的差异化在于把状态明确落成“工单/问题/路线图”这类工程团队熟悉的结构化对象，而不是一段自动生成的摘要文字，且原生 App 提供了 CLI 之外的可视化入口。
8. 用户评价
- 用户 Huggyduggy 在一份技术缺陷报告（GitHub issue #21）开头写道：“we run it daily to drive long autonomous coding sessions and it has genuinely changed how we work”（我们每天用它驱动长时间的自主编码会话，它切实改变了我们的工作方式）——https://github.com/Storybloq/storybloq/issues/21
- 未见其他已验证的第三方具名评价来源。
9. 其他补充
src/skill/SKILL.md 对 Claude Code 与 Codex 的 client profile 做了明确区分，同一份技能文件可在两个平台间无缝切换触发命令。原生 macOS App 与 CLI/MCP 共享同一份 .story/ 数据，团队中不直接使用终端的成员也能通过看板了解 agent 进度。
10. 安装使用方式
npm install -g @storybloq/storybloq@latest
storybloq setup --client all- 安装后在 Claude Code 中输入
/story、在 Codex 中输入$story即可触发，无需重启终端或客户端 - 也可从 Mac App Store 安装原生桌面应用，与 CLI/MCP 共享同一项目数据
- 升级只需重新执行上述 npm 安装命令
11. 注意事项
- 许可证为 PolyForm Shield（源码可见但非 OSI 标准开源协议），禁止基于其代码构建竞品或转售托管服务，个人/内部/商业使用不受此限
- 早期版本中
registerHook会以覆盖方式写入全局~/.claude/settings.json，若该文件由 stow/chezmoi/yadm 等工具管理为符号链接，会被替换为普通文件；此问题已在 v1.4.3 修复，建议安装该版本及以上 - 官方目前仅明确支持 Claude Code 与 Codex，在 OpenClaw、Hermes Agent 上使用需自行验证兼容性
- 原生 macOS App 为可选组件，早期存在持续 CPU 占用等尚未完全解决的小问题，不影响 CLI/MCP 核心功能