Hermes Decision Trace

Hermes 引入 Project Workspace 管理层评估

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

HTML完整论证
Wiki可检索归档
Feishu短入口交付
🎯
核心结论

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

🧭
推荐路径

先用结构化字段吸收，保持执行链路隔离。

🛡️
关键边界

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

关键判断

判断项摘要
推荐方案见正文的选中方案与推荐路径。
关键依据见完整记录中的评分依据、状态摘要和证据链。
落地方式按行动清单推进，保持可回退。
风险边界GitHub 上相关 issue/PR 显示：workspace 语义已经是痛点。

证据摘要

  • 由 Hermes 会话生成。证据点 1
  • 如涉及外部事实，应在正文中保留来源或验证路径。证据点 2

行动清单

Kanban Board 已经很接近 project，但不建议把 board 直接升级成 project 的全部原因：
Board 是任务队列，不是项目事实源。
有些项目没有 kanban 任务，也需要 context/status/wiki。
Board workspace 语义正在踩坑，直接承载项目边界风险大。
Project 生命周期比 board 更稳定；board 可以有多个，比如 dev、ops、research。
正确关系：

边界 / 风险

风险点

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 之间边界不够硬。

风险点

这几个信号共同说明：

完整记录

本节目录结论GitHub / 官方现状GitHub 风险信号推荐架构为什么不建议直接用 Kanban Board 当 Project为什么不建议每个项目一个 Profile最小可行实现本机落地建议推荐数据结构关键约束最终建议

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: /home/ht/.hermes/hermes-agent repo: https://github.com/NousResearch/hermes-agent.git profile: default board: hermes-agent context_file: AGENTS.md status_file: PROJECT_STATUS.md wiki_index: /home/ht/llm-wikis/hermes-ops/index.md checkpoints: true workspace_root_guard: true default_mode: dir worktree_root: /home/ht/.hermes/hermes-agent/.worktrees 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.cwdproject root 是默认 cwd
context filesproject root 下 .hermes.md / AGENTS.md 是项目说明
kanban boardproject 默认 board，任务继承 project root / worktree policy
checkpointsproject 级默认开启或提示开启
worktreeproject 级并行 coding 的推荐执行模式
sessionssession metadata 记录 project slug
croncron 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: /home/ht/.hermes/hermes-agent 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: /home/ht/llm-wikis/hermes-ops/index.md checkpoints: true workspace_policy: default: dir coding: worktree scratch_root: /home/ht/.hermes/projects/hermes-agent/scratch 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 缺少项目一等对象的问题。

Generated 2026-05-24T21:52:16+08:00 · Hermes decision trace