前言¶
在 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（以目录页/仓库页面为准）。
插件自带两个预设：
| 预设 ID | 用途 |
|---|---|
project-forge |
完整管家：协议、实时文档 digest、compaction 恢复、写入守卫 |
project-forge-review（位于 review/） |
偏只读审查：代码审查、简单任务、干净审查子 Agent |
核心功能¶
以下能力均来自官方 README 与仓库说明。
状态边界与三类状态¶
项目自留信息默认集中在 private/（可通过配置改边界或回退到边界出现前的根目录布局）。边界外是 public surface：按「项目已开源」的方式书写——可移植、除配置文件示例外不在边界外写私有事实、不引用边界内路径；发布时可机械地删边界、复制树、git init。
边界内状态分三类：
-
契约（Contracts）——每轮 全文内联 进 prompt，有软预算（超预算只告警，不截断）：
-private/steward.md：仓库自身规则
-plan.md：策略
-done.md：当前状态
-todo.md：队列
若文档仍在项目根，插件会按旧布局读取（规则在.agents/steward.md），避免历史项目无法接管。 -
记录（Records）——只追加 JSONL，不全文内联；digest 与恢复消息里只带「一行一条的索引」和 journal 末尾若干条：
-private/journal.jsonl：工作日志
-private/tortuous.jsonl：负向知识（失败路径与已记录偏差） -
按需材料——
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 组织，可按读者意图选读：
- docs/getting-started.md：教程——安装、确认当前生效副本、首次接管项目。
- docs/init-a-project.md：如何把现有项目纳入该模式。
- docs/how-to-change-the-mode.md：修改协议文本、守卫或配置字段。
- docs/configuration.md：33 项配置参考。
- 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 任务。
务必注意：
- 插件以 当前 DSH 进程权限 运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证，勿在未检查的情况下信任远程 bundle。
- 模式默认 不 push；若你依赖远程协作，需在用户明确要求后再改 Git 远程策略。
- 与主机版本绑定：低于 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。
