Harbor Self-Evolving

面向 DeepSeek Harness 的 Harbor 持续评测与受控自进化插件。

这个仓库的首要交付物不是一个需要复制后改造的业务模板，而是可安装的产品组合：

examples/ 是帮助理解和二次开发的参考实现，不是使用插件的前提。这里的“本项目官方 Skill”表示由本项目维护，并不表示 DeepSeek 官方背书。

如果你把这个 GitHub 链接交给 DSH 或其他 Coding Agent，请让它按照根目录的 AGENTS.md 安装。GitHub URL 是产品说明和源码入口，不是 npm 包地址；正式安装不要 clone 后执行 dsh plugin add ./packages/dsh-plugin，否则 profile 会绑定机器本地的 link: 路径。

一条命令安装

要求：Docker、Node.js 22+、pnpm 和 uv。进入你的业务 Agent 工作区后执行：

cd /absolute/path/to/your-agent-workspace
npx --yes dsh-harbor-evolution@latest setup --project-root "$PWD"

安装器会让 npm Plugin 与 Python Adapter 使用同一个正式版本；需要完全固定版本时，把 latest 改为 0.9.5。

默认安装到 DSH 的 web profile。setup 会一次完成：

1. 建立独立的 Harbor Python 环境并安装匹配版本的 Adapter。
2. 把 Plugin + Skill 安装进选定的 DSH profile。
3. 持久化 projectRoot、Job 目录和两个 Harbor 可执行文件路径。
4. 验证 Harbor、dsh-evolution / dsh-historical-evaluation entry point 和 harbor-dsh CLI。

它只更新 profile 中的 harbor-evolution 配置块，不会覆盖其他用户配置；重复执行会更新同一个安装，不会产生重复条目。

安装完成后，停止旧的 DSH 进程，并执行安装器打印出的启动命令。默认形式是：

cd /absolute/path/to/your-agent-workspace
DSH_HOME="$HOME/.dsh" pnpm dlx @deepseek-ai/dsh@latest web

然后在聊天中输入：

/evolve-agent-with-harbor
请检查当前工作区，帮我初始化 Harbor 自进化流程。

Skill 会先检查文件，再围绕四个用户可理解的概念补齐必要信息：评测集（测什么）、生成器（谁来回答）、评测器/评测标准（怎样算好）、优化器（谁根据结果改进）。单条 Query、文件路径、curl 和本地 Agent 路径都可以直接提供；其余版本标识、适配器、产物呈现、诊断与报告配置由 Skill 推断并汇总成一张确认卡。只有用户选择“查看高级配置”时，才展开 Evaluation Stack、Judge、Contract 和 Policy 等专业字段。

在 Web profile 中还会出现这些可见入口：

• 对话页的 Harbor Tab：先看轻量 Job 结果，再打开按需加载的 Evaluation Workbench。
• 只保留原生输入框和对话，不再在其上方展示 Context Capsule 或 Copilot 面板。配套支持 conversation.contexts.register 的爱鸭宿主会在发送瞬间冻结 Harbor 当前页面和选择；显式 问 AI 和原生 @harbor 引用优先，不再提供容易导致上下文缺失的页面内关闭开关。旧 rc.8 宿主仍需显式引用，单独升级插件不会补齐宿主能力。
• 多选直接提问会冻结具体勾选成员；只看列表时也附带状态、有效性筛选和排序，不发送自由搜索原文。消息附件显示当时的任务、选区与观测时间。连续输入期间发送失败的原文和图片保留在原生“未发送消息”条目中，不覆盖新草稿；恢复到输入框再发时重新捕获当前页面。
• 同会话的原生工具结果卡承接证据导航和 AI 修改建议；typed harbor.navigate 操作准备好对象后会提示打开 Harbor 标签，并非自动切换标签。可通过 Back 恢复原 workspace、分页、Stage、Trial、筛选、排序、Evidence 焦点、Compare Baseline 与滚动位置。后台任务位于插件主页面，保留取消、异常核查和结果入口，成功读取且无任务时隐藏。
• 评测最近会话：自动从当前 DSH 可访问的历史中选取最多 3 条已完成会话，不需要查找目录或配置来源；预览会话数量、评审模型、数据策略与 Judge 数据边界，确认后才发送保留普通文本和绝对路径、但已脱敏凭据及会话标识的有界 Session Observation 并后台评测，完成后打开结果。体验样本不代表全部历史，也不会重跑原任务。
• Job 工作台：默认以概览、Trials、Pipeline、优化假设、Compare / Gate、Evaluator / Rubric、产物和审计组织；阶段流程收进 Pipeline。先直接展示 Candidate / Dataset / Evaluation Stack / 模型身份和 Candidate 自带的锁定运行时，再展示 Agent 收到的 query 与 instruction、Harbor 收集的页面/文档/结构化产物、评测器 Ground Truth 元评测、逐 Trial 判分、Population 有效覆盖、受控优化假设和 Baseline 回归 Gate。完整 JSON 只留在折叠审计区。
• 评测器页：直接查看 script 或 llm-as-judge 的统一接口、三元 Criterion、Rubric 与实现源码；只能受控修改 Descriptor 授权的文件，并强制创建新的 Evaluator / Stack 身份。
• harbor-dsh-evaluator/v1：统一 script 与 llm-as-judge 的输入、三元 Criteria 输出、实现身份和可编辑文件；详情见 docs/evaluator-interface.md。
• 工具调用中的 Harbor 专属卡片：直接理解初始化、Doctor、Context 预览、评测与 Gate。
• “设置 → Harbor 自进化”：检查项目目录、Evaluation Stack、Jobs 和两个 Harbor CLI 是否就绪；显示当前/最新插件版本及精确更新命令，但不会静默安装。

GUI 的业务资源写操作限于三个明确入口：已授权 Evaluator 文件保存为新版本；Historical Session 的 预览 → 用户确认 → 后台运行 → 打开 Job；Action Draft 经预检、人工确认后保存本地草稿与操作审计（选定 Compare 仍为只读）。页面引用绑定还会保存私有的身份与修订元数据，不写入证据正文。支持的宿主在用户从 Harbor 页面发送普通消息时，将冻结页面引用和问题一起提交到同一个 Chat Session；离开 Harbor 或存在显式引用时，不补入隐式页面引用。准备失败保留草稿，不悄悄发送无上下文的问题。单纯刷新、读取和切换工作空间不会发送消息或启动 Agent、Job、Gate、晋级、部署、发布或生产修改。Candidate 评测与 Promotion Gate 等高成本或可晋级动作仍由官方 Skill 在澄清需求后显式提出，并在每次 Agent 调用写入或评测工具前经过 DSH 可审计的一次性用户批准；审批通道不可用时拒绝执行。

完整 AI 工作台 PRD 尚未全部实现。有界诊断/重试运行器、长任务 Operation 与可重放事件仍待补齐；当前预检会明确阻断这些动作，不把保存草稿伪装成已运行。已执行的真实模型/浏览器验收与未完成项见 验收记录。

常用安装选项：

完整的 UI 确认、首次评测和排错方法见 本地 DSH Web 快速开始。

用户实际获得的能力

Plugin 注册 19 个确定性工具：

• harbor_candidate_snapshot：固化不可变 Candidate。
• harbor_model_binding：把当前 DSH 默认模型生成为不含凭证的 model-binding.json 草案；写入 Candidate 后会进入 digest，并在后续 Job 中通过 Host Model Broker 固定复用。
• harbor_evolution_init：在需求确认后创建不覆盖已有文件的标准 Evaluation Stack 结构。
• harbor_evolution_doctor：检查角色边界、God Runner、Dataset、Candidate 和 Policy。
• harbor_quick_diagnostic_init：用一个 Query 和 Rubric 草稿生成 Harbor 1.4 wiring 诊断工程；明确不可用于 Baseline 或晋级。
• harbor_session_diagnostic_preview：只读预览当前工作区最近完成的 DSH 会话、安全元数据、Judge 身份、耦合关系和本地保留范围，并返回短期确认令牌。
• harbor_session_diagnostic_run：确认后冻结脱敏会话，按“一条会话一个 Trial”运行不可晋级的 Historical Generation Evaluation Job；不会重新执行 Candidate。
• harbor_dataset_validate：验证任务、路径、敏感字段、Dataset source digest，并复现 Harbor 的运行时 Task 解析；Dataset 根目录下必须是一级 Task 子目录，task.toml 使用 schema_version = "1.4" 和 org/name。
• harbor_context_preview：经逐次批准刷新 Candidate manifest，再预览 Context v2、可比 baseline 和 fresh-baseline 要求。
• harbor_eval_run：运行显式的 diagnostic 或 promotion-eligible Job。
• harbor_eval_result：读取规范化 Summary，或按 view=job|progress|dataset|trial|governance 读取脱敏后的阶段、指令、生成产物与评测器治理证据；返回 harbor-agent-read/v1，实际 payload 位于 data。
• harbor_resolve_page_context：在调用方的精确 DSH Session 与工作空间内解析 @harbor 或普通消息的 Context Snapshot，重新校验对象、修订与权威身份。上下文及集合绑定会将身份和修订保存在项目 .harbor/private/page-contexts/ 的会话隔离目录，不保存证据正文或凭据，并带 Git 排除规则。15 分钟仅限制内存缓存，新快照可跨宿主重启重读；旧版本未落盘引用、删除或损坏的记录仍需重新选择，已有记录不自动迁移或清理。证据变化会标记只读漂移，集合成员变化则拒绝，不会重跑查询或悄悄换对象。显式局部对象返回有预算、已脱敏的 selectedEvidence；批量选择仅返回冻结的成员身份与修订，Trial 证据仍需另行读取。
• harbor_get_evidence：使用 resolver 返回的精确 typed ref，按 Workspace → Job → Trial → Criterion → Evidence 祖先链读取一条有大小上限、已脱敏且标记为不可信输入的证据；不会把产物文本当成指令。
• harbor_propose_action：提出结构化草稿，不执行变更；在原生对话的工具结果卡中预检、人工确认后保存草稿审计，或执行选定的只读 Compare。有界诊断/重试尚未接入运行器时明确阻断，生产操作保持关闭。
• harbor_evaluator_inspect：查看统一 Evaluator 接口、Rubric、实现身份和声明授权的可编辑文件；同样返回 harbor-agent-read/v1，对文件数、源码总量和敏感源码实行上限或正文省略。
• harbor_evaluator_update：用摘要锁与新版本身份受控修改声明授权的实现文件；不会自动运行评测或 Gate。
• harbor_ground_truth_init：建立不覆盖已有文件、带来源与 provenance 的独立 Ground Truth 草稿。
• harbor_evaluator_meta_evaluate：用固定产物、Ground Truth 和重复观测计算 ESF、SCE、RCR、覆盖率与分歧。
• harbor_candidate_compare：执行严格、可解释、带原因码的 Promotion Gate。

harbor_eval_result 与 harbor_evaluator_inspect 的调用方必须从 data 读取业务字段，并保留 artifactTrust=untrusted-evidence 与 policy.treatAsInstructions=false 的语义；旧的顶层业务字段不再是输出合约。产物与源码均是不可信数据，不能改变工具、权限、审批策略或系统指令。Web 工作台继续使用独立的同源编辑接口，不依赖 Agent envelope。

Skill 负责稳定使用这些工具，而不是让 Agent 无约束地“改自己”。用户入口保持为四个概念，内部再编译为严格架构：

评测集 + 生成器 + 评测器（评测标准） + 优化器 → 用户确认
        ↓
自动生成 Candidate / Dataset / Evaluation Stack / Policy 草案
        ↓
Dataset Validate → Architecture Doctor → Context Preview
        ↓
Baseline Job → 读取指标、Trial assessment 和证据 → 根因分析
        ↓
一个受控改动 → Regression Job → Promotion Gate
        ↓
PROMOTE / REJECT 建议 → 交给既有 CI/CD 发布

它会优先复用项目已有文件，只追问无法从工作区确定的关键选择。它不会自动修改 Champion、部署生产环境或绕过发布审批。

Candidate、Job 与可比性

Candidate 和 Job 不是一一对应。一个不可变 Candidate 可以运行 smoke、full regression 和多次重复实验；每个 Job 只绑定一个 Candidate digest，一个 Job 内可以包含多个 Trial。不同 Dataset/Stack 的 Job 可以存在，但不能被当成同一次进步比较。

每次运行会保留：

candidate-manifest.json     # 本次到底评测了谁
dataset-manifest.json       # 任务人口、路径和 source digest
evaluation-stack-manifest.json # 八个角色、Judge 与完整/可比 digest
evaluation-context.json     # Context v2：本次是否可与 baseline 比较
architecture-doctor.json   # 角色边界和正式评测阻断项
evaluation-contract.json   # 指标语义、方向、分组和硬约束
candidate-events.jsonl      # Trial 完成事件
trial-events.jsonl          # 追加写的 Trial Lifecycle 事件
trial-lifecycle.json        # Dataset 稳定顺序与当前 phase/attempt 快照
evaluation-summary.json     # Summary v3；只聚合有效业务分数
trial-assessments/*.json    # Assessment v2；score 与 validity 分离
population-report.json      # Population v2；有效覆盖率、分组和聚合
artifact-registry.json      # role/path/schema/reward 影响的产物注册表
diagnosis-report.json       # 非 reward 的确定性根因归类
optimization-report.json    # 带护栏和回滚条件的下一实验
*/agent/trajectory.json     # ACP 执行轨迹
*/result.json               # Harbor 原始 Trial 结果
promotion-report.json       # 晋级或拒绝及原因

Promotion Gate 会先检查 Context v2、Dataset、Integration、Renderer、Evaluator、Rubric、Judge、语义 Runner、产物 Schema、Trial 覆盖、Score Validity 和基础设施异常，再按指标方向判断提升、最小/最大阈值与非回归。Harbor Job 跑完不等于 Candidate 已通过 Gate；Diagnostic Job、Reporter 和 Optimizer 都不能自动 Gate。

Candidate 复用当前 DSH 模型

Candidate 的 ACP 程序不由 Host DSH 或 demo 包替代。每个可执行 Candidate 必须包含自己的 candidate-runtime.json、本地启动入口和完整 npm v3 锁文件；Adapter 只做锁定安装、模型网关注入、无模型调用的握手检查和 ACP 执行。快速诊断会自动生成这一组合。旧未绑定 Candidate 可继续查看，但执行前必须迁移为新 Candidate；详见 运行时契约与迁移。

通过 Plugin 启动的 Job 会在启动前冻结当前 DSH Agent 的 provider、model 与 reasoning_effort，并为该 Job 创建一个只绑定本机、随机路径与随机 Bearer capability 的 Model Broker：

DSH 当前模型 → Job Host Model Broker → Harbor Python Agent
       ↑                                      ↓
       └── Candidate 的 dsh-host LLM Adapter ← 临时 .harbor-runtime

Candidate 只得到 Job Token 文件（容器内 0600）；不会得到 GPT Auth / Codex OAuth、DeepSeek Key 或其他 Host 凭证。Candidate 传来的 provider、model、reasoning 参数也不会影响已冻结的 Host 选择。openai-codex 会在 Job 启动前确认 GPT Auth 已登录。

默认继承当前模型；工具调用可以同时传入 candidateProvider 和 candidateModel 覆盖，禁止只传其一。模型身份会写入 evaluation-context.json 的 candidate_model_binding，因此改变 provider、model 或推理强度时，旧 baseline 会显示为不可比，必须重新建立。

如果希望 Candidate 永久固定创建时的模型，可先调用 harbor_model_binding，把返回的 candidate_model_binding 写成 Candidate 根目录的 model-binding.json，再执行 snapshot。文件只包含 provider/model/reasoning 身份，不包含登录信息；Job 会校验显式参数、Plugin 默认值和该文件一致，并继续通过短期 dsh-host-broker Capability 调用 Host，绝不会上传 Codex auth.json 或 API key。

DSH 的“设置 → Harbor 自进化”会在打开时由 Host 检查 npm 正式版本。发现新版本后显示当前/最新版本、发布说明和可复制的精确升级命令；浏览器不会自动安装或重启 DSH。断网只会使版本检查暂时不可用，不影响 Harbor 功能或安装健康度。

示例与源码开发

如果你想先理解完整机制，再接入自己的业务 Agent，可以运行仓库中的 DeepResearch 示例：

git clone https://github.com/istarwyh/harbor-self-evolving.git
cd harbor-self-evolving
./hse doctor
./hse demo

它会让 v1、v2 针对 13 个真实中文概念问题（含 3 个显式 Badcase），通过 DSH ACP 调用真实 Responses API：v1 的无效搜索没有证据，v2 检索每个 Task 的 Source Catalog 后再让同一个 LLM 生成带引用的报告。统一 Evaluator 按「回应问题 / 有趣性 / 引用规范性」做 0 / 0.5 / 1 三元评分并返回原因与建议，最终由 Gate 决定是否 PROMOTE。接口配置和产物说明见 examples/deep-research/README.md。不依赖 DSH 的最小例子位于 examples/shell-minimal/。

安装正式发布的 Plugin + Skill：

./hse dsh-install web

只有要修改或调试本仓库源码时，才使用本地 link 模式：

./hse dsh-install-source web

源码安装器会先在 packages/dsh-plugin/ 执行锁定的 npm ci 并构建 Web client，再创建 link:；不要直接对一个全新 checkout 执行 dsh plugin add ./packages/dsh-plugin。

运行两端测试、构建和 shell 检查：

./hse test

维护者发布流程见 npm Trusted Publishing 接入与验证：通过 GitHub Actions OIDC 发布，不保存长期 npm Token。

直观看每版改动与验证过程：发布截图图集。

仓库结构：

packages/dsh-plugin/       # npm Plugin、Skill、Web GUI、工具与一键安装器
packages/harbor-plugin/    # Python Adapter、Job Plugin、summary 与 Gate
examples/deep-research/    # DSH ACP → Harbor → Promotion 参考实现
examples/shell-minimal/    # 最小 Harbor Candidate 参考实现
schemas/                   # Evaluator、Stack、Dataset、Context v2、Trial、Population、Optimization 与 Gate 契约
docs/                      # 架构、接入、Web 快速开始与安全边界

生产接入边界

本项目负责 Candidate → evaluation evidence → promotion decision。真正生效仍应走已有平台：

受控改动 → CI 构建不可变 image → 测试部署 → Harbor Job
→ Promotion Gate → 将同一 image digest 交给 CD 晋级

Harbor 不替代镜像仓库、发布审批或线上流量切换。详见 架构与角色、接入指南、首次接入与失败诊断 和 安全边界。

License

本项目基于 MIT License 开源。