HT1072公开知识系统
返回列表总览 ↗
决决策档案2026-05-24 · 决策记录
2026-05-24 · DECISION TRACE

Hermes 引入 Project Workspace 管理层评估

保留方案、指标、验证、复盘和治理判断，让结论能够追溯。

2026-05-24记录日期
决策记录记录类型
23章节数

Hermes 引入 Project Workspace 管理层评估

  • HTML: https://decision.ht1072.top/2026-05-24-hermes-project-workspace-layer.html
  • Local HTML: [已移除本地路径]
  • Generated: 2026-05-24T21:52:16+08:00

Hermes 引入 Project Workspace 管理层评估

结论

如果要给 Hermes 引入类似 Codex / Claude Code 的项目管理层，最佳解法不是重做一个“大而全项目系统”，而是在现有官方能力上加一个轻量的一等对象：Project Workspace。

推荐路线：

  1. 新增 hermes project CLI，管理项目注册表。
  2. 每个 project 绑定 root、默认 profile、默认 board、context 文件、checkpoint 策略、workspace_root guard。
  3. 不替代 profiles、kanban、sessions、worktrees、checkpoints，而是把它们串起来。
  4. 第一阶段只做 registry + resolve + enter，不碰 agent 核心循环。
  5. 第二阶段再把 project 注入 gateway / cron / kanban / session metadata。

一句话：Project 应该是“协调层”和“默认值容器”，不要变成新的状态孤岛。

GitHub / 官方现状

Hermes 官方已有这些构件：

1. Context Files

官方支持项目上下文文件：

  • .hermes.md / HERMES.md
  • AGENTS.md
  • CLAUDE.md
  • .cursorrules

优先级是：

.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules

AGENTS.md / CLAUDE.md 支持子目录渐进发现。适合承载项目结构、命令、约定、禁区。

2. Profiles

Profile 是 Hermes 状态隔离单元：

  • config.yaml
  • .env
  • SOUL.md
  • memories
  • sessions
  • skills
  • cron
  • gateway state

但官方明确区分：

  • profile 不是 workspace
  • profile 不限制文件访问
  • workspace / working directory 由 terminal.cwd 控制
  • sandbox 是另一层东西

所以 profile 不能直接当 project。

3. Worktrees

官方已有 hermes -w 自动 worktree 模式：

  • 在 repo 下创建 .worktrees/
  • 自动创建隔离 branch
  • 在 worktree 内运行 Hermes session

这是并行 coding agent 的好基础。

4. Checkpoints

Hermes 有 shadow git checkpoint：

  • 文件修改前自动快照
  • /rollback
  • /rollback diff <N>
  • /rollback <N> <file>

适合做项目级安全网，但目前按工作目录 hash 组织，不是 project 对象。

5. Kanban Boards

当前代码已有 multi-board：

  • board per project / workstream
  • board 有自己的 DB、workspaces、dispatcher loop
  • task 有 workspace_kind: scratch / worktree / dir
  • task 有 workspace_path

这说明官方已经有“项目/工作流队列”的雏形。

GitHub 风险信号

GitHub 上相关 issue/PR 显示：workspace 语义已经是痛点。

典型信号：

  • feat(security): add optional workspace_root guardrails：说明社区也在补 workspace 边界。
  • feat(cli): add /set-workspace command to change session cwd：说明 session 级切换 workspace 是刚需。
  • Kanban scratch workspace cleanup 删除真实项目目录的 issue/PR：说明现在 scratch、dir、board default_workdir 之间边界不够硬。

这几个信号共同说明：

Hermes 缺的不是“又一个任务系统”，而是一个统一的 Project Workspace 语义层，用来给 profile、kanban、cwd、context、checkpoint、安全边界提供同一个锚点。

推荐架构

Project Workspace 是什么

Project Workspace 是一个注册表对象：

slug: hermes-agent
name: Hermes Agent 本机维护
root: [已移除本地路径]
repo: https://github.com/NousResearch/hermes-agent.git
profile: default
board: hermes-agent
context_file: AGENTS.md
status_file: PROJECT_STATUS.md
wiki_index: [已移除本地路径]
checkpoints: true
workspace_root_guard: true
default_mode: dir
worktree_root: [已移除本地路径]
created_at: ...
updated_at: ...

存储位置建议：

~/.hermes/projects/projects.yaml
~/.hermes/projects/<slug>/state.json
~/.hermes/projects/<slug>/notes.md

不要放到 profile 里面。原因：一个项目可能被多个 profile 操作；一个 profile 也可能服务多个项目。

CLI 形态

建议新增：

hermes project init [path] --slug <slug> --name <name>
hermes project list
hermes project show <slug>
hermes project use <slug>
hermes project status <slug>
hermes project open <slug>
hermes project doctor <slug>
hermes project archive <slug>

后续可加：

hermes project link-board <slug> <board>
hermes project link-profile <slug> <profile>
hermes project worktree <slug> --new <branch>

和现有能力的关系

现有能力 Project 层如何使用
profile 作为默认 agent 身份/配置，不当项目边界
terminal.cwd project root 是默认 cwd
context files project root 下 .hermes.md / AGENTS.md 是项目说明
kanban board project 默认 board，任务继承 project root / worktree policy
checkpoints project 级默认开启或提示开启
worktree project 级并行 coding 的推荐执行模式
sessions session metadata 记录 project slug
cron cron job 可绑定 project workdir
gateway 来自飞书/Telegram 的任务可显式指定 project

为什么不建议直接用 Kanban Board 当 Project

Kanban Board 已经很接近 project，但不建议把 board 直接升级成 project 的全部原因：

  1. Board 是任务队列，不是项目事实源。
  2. 有些项目没有 kanban 任务，也需要 context/status/wiki。
  3. Board workspace 语义正在踩坑，直接承载项目边界风险大。
  4. Project 生命周期比 board 更稳定；board 可以有多个，比如 dev、ops、research。

正确关系：

Project 1 ──> default board 1
          ├─> optional board 2
          ├─> profile
          ├─> root/worktree policy
          └─> context/status/wiki

为什么不建议每个项目一个 Profile

每项目一个 profile 看似简单，但长期会膨胀：

  • API key / model / skills 重复
  • memory 分裂
  • gateway / cron 状态复杂
  • 项目切换不够轻

更好的分层：

  • profile：人设/模型/权限/工具集
  • project：文件根、上下文、状态、board、checkpoint 策略
  • session：一次具体对话或执行
  • task：kanban 中的可执行单元

最小可行实现

Phase 1：本地 registry + CLI

不改 agent loop，只加 hermes_cli/projects.py。

能力：

  • 注册项目
  • 展示项目
  • 记录 root/profile/board/status/wiki
  • project use 设置当前 project
  • project doctor 检查 root、git、AGENTS.md、PROJECT_STATUS.md、board、checkpoint

这阶段风险最低，最快能用。

Phase 2：运行态接入

把当前 project 解析成运行环境：

  • TERMINAL_CWD=<project.root>
  • 可选 HERMES_PROJECT=<slug>
  • prompt footer 显示 project
  • session metadata 记录 project slug
  • gateway /project use <slug> 或消息前缀指定 project

Phase 3：Kanban / Worktree 绑定

  • board metadata 增加 project_slug
  • task 默认 workspace 从 project policy 继承
  • scratch 只允许 Hermes 管理目录
  • project root 永远按 dir，不能被 scratch cleanup 删除
  • coding task 默认 worktree

Phase 4：安全边界

引入或等待官方 security.workspace_root 后，把 project root 作为默认 workspace_root。

规则：

  • 读写文件默认限制在 project root
  • terminal workdir 默认在 project root
  • 需要跨项目访问必须显式声明/确认

本机落地建议

对涛哥这套环境，我建议先做本地增强，不急着上游大 PR：

  1. 先建 ~/llm-wikis/hermes-ops/concepts/project-workspace-layer.md 作为规范。
  2. 在 ~/.hermes/projects/projects.yaml 建 registry。
  3. 写一个轻量脚本：~/.hermes/scripts/hermes_project.py。
  4. 先支持：list/show/init/doctor/use。
  5. 跑 3-5 个真实项目后，再决定是否进 Hermes core。

优先纳入的项目：

  • hermes-agent 本体
  • morning-brief
  • decision-trace
  • CLIProxyAPI / CPA-X
  • B站 source-pool pipeline

推荐数据结构

version: 1
current: hermes-agent
projects:
  hermes-agent:
    name: Hermes Agent 本机维护
    root: [已移除本地路径]
    repo: https://github.com/NousResearch/hermes-agent.git
    default_profile: default
    default_board: hermes-agent
    status_file: PROJECT_STATUS.md
    context_file: AGENTS.md
    wiki_index: [已移除本地路径]
    checkpoints: true
    workspace_policy:
      default: dir
      coding: worktree
      scratch_root: [已移除本地路径]
    retain:
      decision_trace: true

关键约束

  1. project root 必须是绝对路径。
  2. scratch workspace 只能在 Hermes 管理目录下。
  3. project root 永远不能被当成 scratch 删除。
  4. profile 不等于 project，不拿 profile 做项目边界。
  5. board 不等于 project，不拿 board 做项目事实源。
  6. HTML/wiki/retain 仍是重要设计和决策的归档层，不塞回 project registry。

最终建议

推荐采用：

Project Registry + Current Project Resolver + Existing Hermes Primitives

不要一开始就改 agent 核心。先做外层 registry 和 CLI，验证真实工作流。等稳定后再逐步把 project slug 接入 session、gateway、kanban、cron。

这是最稳的路线：低侵入、能复用官方能力、又能解决当前 Hermes 缺少项目一等对象的问题。