Hermes STDD archive现象分析

问题起源

用户听到 STDD 作者的描述："你有 git 的话，他也会同步提交代码，文档则归档在 Archive 下"，但在 Forgejo 项目页面找不到任何 "Archive" 标签或特殊功能，产生困惑——怀疑自己的 Forgejo 实例缺少功能，或 Git 有某种未启用的自动归档机制。

四个视角还原真相

Hermes 视角

Hermes Agent 的 STDD skill（software-development/stdd）在 Phase 6 (DELIVER) 中描述了归档步骤：

Phase 6: DELIVER — 交付
执行流程：
1. 归档 change: python3 ~/.stdd/bin/stdd archive <change-name>
2. 合并 specs 到 specs/ 目录
3. Git commit + tag

Hermes 将 "archive" 视为 STDD 流程中的一个操作步骤，与 git commit 并列。它不假设任何特殊的 Git 平台功能——只是一个 CLI 命令调用。

Hermes 在与用户交互中，如果检测到 STDD 项目有已完成的变更，会建议执行 archive 操作。但 Hermes 自身并不自动触发 archive，需要用户在 Phase 6 确认后手动或通过 Hermes 执行。

STDD 视角

stdd archive 命令是一个纯 Python CLI 工具，定义在 ~/.stdd/stdd/cli/commands/archive.py。其实际行为：

  1. 查找： 在当前项目 changes/ 下找到指定名称的 change 目录
  2. 检查： 验证 Phase 5 (VERIFY) 是否已完成（可选强制归档）
  3. 合并 Specs： 将 changes/<name>/specs/*.md 合并到项目根 specs/ 目录（冲突检测 + 追加合并）
  4. 标记状态： 将 changes/<name>/.stdd.yaml 的 status 改为 archived
  5. 移动目录： 执行 shutil.move()，将整个 change 目录从 changes/ 移到 archive/

关键结论： STDD 的 "archive" 本质上就是一次目录移动（mv），附带 specs 合并和状态标记。没有数据库操作，没有 Git 平台 API 调用，没有特殊的服务端功能。

项目文件结构视角

archive 操作前后，项目的目录结构变化：

# 归档前
project-root/
├── changes/
│   └── v0.1.0-wrapper-layer/
│       ├── .stdd.yaml        # status: completed
│       ├── proposal.md
│       ├── design.md
│       ├── specs/
│       │   └── algorithm-spec.md
│       ├── test-plan.md
│       └── slices.md
├── specs/                     # 可能为空
└── scripts/

# 归档后
project-root/
├── changes/                   # 已完成移出
├── archive/
│   └── v0.1.0-wrapper-layer/ # 整个目录迁移至此
│       ├── .stdd.yaml        # status: archived
│       ├── proposal.md
│       ├── design.md
│       ├── specs/             # 内容已合并到 specs/
│       ├── test-plan.md
│       └── slices.md
├── specs/
│   └── algorithm-spec.md     # 新增（合并自 archive）
└── scripts/

archive/ 只是一个普通目录： 在项目根目录下，与 changes/、scripts/、specs/ 同级，没有任何特殊属性。

如果项目未被 STD init，则根本不存在 changes/ 和 archive/ 目录。

Git 视角

从 Git 的角度看，stdd archive 就是一次普通的工作区文件变更：

# git 看到的变更
git diff --stat
> changes/v0.1.0-wrapper-layer/...  (删除)
> archive/v0.1.0-wrapper-layer/...   (新增)
> specs/algorithm-spec.md             (新增或修改)

Git 机制对于 archive 完全无感知：

  • Git 不区分 "归档" 和 "普通文件移动"
  • archive/ 目录需要显式 git add archive/ 才能被跟踪
  • Forgejo/ Gitea 页面上没有特殊的 "Archive" 标签页
  • 在 Forgejo 浏览器中，archive/ 在文件树中显示为普通文件夹
  • 不存在 "自动同步"——用户必须手动 git add && git commit && git push

Forgejo 的唯一 "Archive" 功能 是仓库设置 → Danger Zone 里的 "Archive Repository"（将整个仓库设为只读），这与 STDD 的 archive 完全无关。

综合结论

"STDD archive" = 本地目录移动 + specs 合并，无任何 Git 平台联动。

用户的困惑来源于将 STDD 框架内部术语（archive）误解为 Forgejo/Git 平台功能。实际上：

  • STDD 的 archive 是 mv changes/xxx archive/xxx
  • STDD 的 git 提交 是普通的 git commit && git push
  • 两者在 Phase 6 中先后执行，但 没有技术上的联动
  • Forgejo 页面上永远看不到特殊的 "Archive" 入口——它只是文件树里的一个目录

附录：STDD CLI archive 命令源码摘要

def cmd_archive(args):
    project_root = Path.cwd()
    change_dir = find_change_dir(args.name, project_root)
    archive_dir = project_root / "archive" / change_dir.name

    # 1. 合并 specs 到 specs/
    # 2. 更新 .stdd.yaml status = archived
    # 3. shutil.move(change_dir, archive_dir)

    print(f" 归档完成: archive/{change_dir.name}")