前言¶

在 DeepSeek Harness（DSH）里用智能体长期维护一个代码库时，常见问题是：上下文被压缩后 Agent 忘记约定、文档与仓库状态脱节、多会话并行写同一文件、以及误把凭证提交进 Git。社区插件按「一切皆插件」的方式扩展 DSH 的行为；目录站点 skillhub.cn 是独立生态入口，与 DeepSeek / 幻方无官方从属关系。

下面介绍 Project Forge（项目锻造模式）——维护者 sopreigj 发布的工作流类预设，把 Agent 约束成项目的「管家」：本地 Git、四份契约文档、布局与命名纪律、压缩后恢复，以及五类写入守卫。

这是什么¶

dsh-project-forge 是一个 DSH agent preset（bundle 插件），一句话定位：在 仅本地 Git、四份状态契约 + 只追加记录、布局与命名纪律、compaction 恢复 和 写入守卫 下，让项目可恢复、可追踪、上下文丢失后仍可续作。

仓库：https://github.com/sopreigj/dsh-project-forge
目录页：https://www.skillhub.cn/plugins/sopreigj/dsh-project-forge
当前 bundle 版本（package.json）：3.7.0，许可证 MIT。GitHub 星标为 0（以目录页/仓库页面为准）。

插件自带两个预设：

核心功能¶

以下能力均来自官方 README 与仓库说明。

状态边界与三类状态¶

项目自留信息默认集中在 private/（可通过配置改边界或回退到边界出现前的根目录布局）。边界外是 public surface：按「项目已开源」的方式书写——可移植、除配置文件示例外不在边界外写私有事实、不引用边界内路径；发布时可机械地删边界、复制树、git init。

边界内状态分三类：

1. 契约（Contracts）——每轮 全文内联 进 prompt，有软预算（超预算只告警，不截断）：
   - private/steward.md：仓库自身规则
   - plan.md：策略
   - done.md：当前状态
   - todo.md：队列
   若文档仍在项目根，插件会按旧布局读取（规则在 .agents/steward.md），避免历史项目无法接管。

2. 记录（Records）——只追加 JSONL，不全文内联；digest 与恢复消息里只带「一行一条的索引」和 journal 末尾若干条：
   - private/journal.jsonl：工作日志
   - private/tortuous.jsonl：负向知识（失败路径与已记录偏差）

3. 按需材料——private/rationale/。

本地 Git 与检查点协议¶

• Local-only git：在用户明确要求前，不 push、不添加 remote、不改写历史。
• Checkpoint protocol：结束一个逻辑单元 → 跑检查 → 更新文档 → 一次 commit；禁止「每条命令一次 commit」。
• No secrets in git：拒绝在边界外提交凭证文件（边界内本地-only 仓库存凭证由模式规则覆盖）。

布局、命名与并行会话¶

• Layout & naming：目录/文件/标识符遵循「一词一义」；每个检查点校验；布局守卫拒绝未承认的混合产物根目录。
• Parallel sessions：单一文档 owner；private/.forge-claims/ 下按文件声明占用，commit 时释放；10 分钟无活动则过期。

Compaction 与写入守卫¶

• Compaction recovery：真实的 compaction/end 事件会在下一步折叠恢复消息（协议重述 + 新鲜 digest）。
• 模式强调 five write guards（写入守卫在模型不配合时仍应生效）；具体切片实现在 plugin/ 各 guard 模块，完整配置见 docs/configuration.md（33 个字段，默认全开；release/check-consistency.mjs 保证文档与 schema 一致）。

捆绑技能¶

仓库包含 skills/project-forge-grilling/ 讨论类 skill；审查 bundle 在 review/ 内有 skill 副本。

安装与启用¶

要求 DeepSeek Harness >= 0.2.1-rc。 digest 对 {{...}} 原样保留，并把插值交给 systemPrompt.context 的 interpolate: false；更旧的主机在 prompt 组装阶段可能对引号大括号的文档报错（README 指向 CHANGELOG 3.4.0 与负向知识记录中的 V11）。

安装 bundle 后需 重启 dsh web，再在模式选择器中选 项目锻造模式 或 项目锻造 · 干净审查。

官方安装命令：

# 本地开发 checkout
dsh plugin --profile web add link:/path/to/dsh-project-forge
dsh plugin --profile web add link:/path/to/dsh-project-forge/review

# 或直接从 git 安装
dsh plugin --profile web add github:sopreigj/dsh-project-forge#main

典型用法与文档入口¶

仓库文档按 Diátaxis 组织，可按读者意图选读：

1. docs/getting-started.md：教程——安装、确认当前生效副本、首次接管项目。
2. docs/init-a-project.md：如何把现有项目纳入该模式。
3. docs/how-to-change-the-mode.md：修改协议文本、守卫或配置字段。
4. docs/configuration.md：33 项配置参考。
5. docs/state-boundary.md：边界设计、导出流程、守卫覆盖范围。

最常改动的两项配置示例（README）：

- id: project-forge
  name: 'dsh-project-forge'
  config:
    sizeLimitMode: ratchet    # 对已超限文档再增大也拒绝 commit
    stateDir: '.'             # 回退到边界出现前的根目录文档布局

版本变更与升级注意见仓库根目录 CHANGELOG.md（按版本倒序，package.json 版本需有对应条目）。

开发仓库自测示例：

node test/run.mjs plugin/index.js   # 配置、digest、守卫、patch↔schema 漂移
node release/check-consistency.mjs

插件仅依赖 Node 内置模块，profile 安装的 bundle 不解析第三方 npm 包。

适用场景与注意¶

适合谁： 需要 Agent 长期 steward 单个仓库、强调可恢复 Git 历史、用 plan/done/todo/steward 四契约对齐策略与状态、并要在 context compaction 后自动「拉回协议」的团队或个人。审查子 bundle 适合以读为主、少改状态文档的 review 任务。

务必注意：

1. 插件以 当前 DSH 进程权限 运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证，勿在未检查的情况下信任远程 bundle。
2. 模式默认 不 push；若你依赖远程协作，需在用户明确要求后再改 Git 远程策略。
3. 与主机版本绑定：低于 0.2.1-rc 可能无法安全组装含 {{variable}} 的文档 digest。

结尾¶

dsh-project-forge 把「本地 Git + 四契约 + 只追加记录 + 检查点提交 + compaction 恢复 + 写入守卫」打包成 DSH 工作流预设，适合把 Agent 从单次对话工具变成可续作的项目管家。进一步了解请访问目录页 skillhub.cn/plugins/sopreigj/dsh-project-forge 与仓库 github.com/sopreigj/dsh-project-forge。