---
name: harness-install
description: 将已经可用的 Harness Anything 接入一个尚无台账的目标仓库：检查项目、确认身份、初始化、合并 Agent 入口、建立主控知识位置，并用一个真实任务验证完整流程。缺少源码或 CLI 时先使用 harness-download 完成工具准备，再返回本流程；不重复维护下载步骤。
---

# Harness 仓库初始化

本技能负责把 Harness 接入具体项目。机器环境、持久源码与用户级技能链接由 [harness-download](../harness-download/SKILL.md) 负责；本技能从可用 CLI 开始。完整引导过程中由同一个 Agent 连续执行，不要求用户在阶段之间重新发指令。

## 入口与版本

使用本次安装所选源码中的完整技能包，不混用不同版本的技能与 CLI。正式源码分发来自 `main`，可用 `git show origin/main:skills/harness-install/SKILL.md` 核对发布分支；明确验证候选分支时使用该候选包并记录版本。

读取项目之前不写入。检查已有 `harness/`、`.harness/`、配置及 CLI 可读状态：

- 已有当前可用台账：复用工作区，转入主控初始化和用户任务，不重新 `init`。
- 明确为旧代台账且用户要迁移：转 [harness-migration](../harness-migration/SKILL.md)，保留它的数据处置审批。
- `harness/` 是无关业务目录，或无法判断已有内容：展示真实冲突，先澄清，不覆盖。
- 没有台账：继续。

## 0. 先读项目

读取项目布局、Git 状态和历史、现有 `AGENTS.md` / `CLAUDE.md`、忽略规则、CI、构建和测试入口。能从磁盘得到的答案不问用户。

| 观察 | 对下一步的影响 |
| --- | --- |
| 当前初始化方式要求 Git，但项目无仓库或提交 | 在用户授权的目标内先建立必要基础，不操作其他目录 |
| 已有 Agent 指令 | 预备合并草案，保留原指令并取得具体合并批准 |
| 已有忽略规则 | 初始化后回读差异，确认私有台账不会进入公开项目 |
| 有 CI | 记录真实验证入口，首任务按实际结果收口 |
| 没有 CI | 不把完成参数当成真实运行证据；按任务类型取得可验证结果，明确未运行 CI |
| 多人协作 | 提前说明 owner 与评审身份的实际绑定，不能把环境变量当作另一个人 |
| 用户已给首任务 | 直接复用，不再造一个名为“安装测试”的占位任务 |

只合并询问尚缺少的项目标识、首次任务等信息。owner 身份与指令文件合并仍按下文保留具体审批。

## 1. 取得当前 CLI 入口

复用 `harness-download` 传来的绝对源码入口和 Node 路径。工具未准备好时读取同一技能包里的下载技能，完成其环境、源码、链接阶段后返回；不在这里再复制 clone 或 npm 安装配方。

下面用 `ha` 表示本次已核实的 CLI。若使用源码，后续调用均展开为 `node "<源码目录>/packages/cli/src/index.ts" ...`；临时 shell 函数不会跨工具调用自动保留，不把“node 加参数”装进一个字符串再当命令执行。

检查目标是否已有中心注册和在飞初始化，使用正常的服务根。不要通过 `HARNESS_DAEMON_USER_ROOT` 为正式安装切换到测试根；若发现现有环境指向隔离根，先核实用途，明确选择正式入口，不能静默把用户已有配置清掉。

## 2. 确认身份与初始 owner

读取当前 `ha init --help`。向用户展示将写入的人员标识、显示名及实际登录身份，取得明确答复；已确认的内容直接复用，不能从 Git 配置猜 owner。

当前纯本地路径也要求 Keycloak 登录及适用的策略组。全新用户在没有身份服务与登录会话的独立 daemon 根中直接执行下一节的 `init`，会退出 1：

```text
configure_verify_failed
init Configure-Verify smoke failed: Sign in with Keycloak and request an applicable policy group.
```

因此，下载和本地 Unix socket 可用不等于已能初始化项目；不能承诺未登录的新用户直接走通。先按公开[服务端运维的首次管理员与登录流程](../../docs-release/operations-server-daemon.md#headless-center-first-administrator)配置身份、登录并取得适用权限，再继续。`--person-id` 是初始化输入，不能替代认证，也不再使用 `unix-socket-owner-boundary` 凭据示例。缺少前提时记录该阶段的原始错误及已完成的写入，不删台账重来。

人员与策略组由身份管理入口办理；当前 `ha people` 只提供执行委托与撤销委托，不提供 `add/remove`。不手改人员文件，也不用通用文档同步替代身份管理。

## 3. 初始化并回读

命令形状以当前帮助为准，在明确的目标仓库执行：

```bash
ha --root "<目标仓库绝对路径>" init --repo-id <项目标识> --person-id <人员标识> --display-name "<显示名>"
```

初次本地安装若要求 Git 基础，先核实是否已有仓库与提交，只补真正缺失的部分，不重置原历史。多个边缘节点不能各自初始化同一个逻辑工作区；由当前有权协调者完成中心写入，其他节点接入已有记录。

回读而不是只看成功回执：

- `preserved` / `drifted` 中有原 Agent 文件时，确认新入口是否尚未进入，继续下一节。
- 用 `git check-ignore -v harness .harness` 和 `git ls-files harness .harness` 核对私有目录边界，检查实际忽略差异。`git check-ignore -q` 一次只传一个路径。
- 用当前 JSON 状态入口核对工作区是否已注册、已附着，不机械重做回执里的下一步。
- 台账自动提交与目标项目提交是两件事。列出项目中新建或修改的指令、忽略文件；是否提交项目变更按用户范围处理。
- 台账分支可能与项目分支不同；不为了名字统一重命名正在服务的分支。

失败时先识别哪些写入已完成、是否有当前持有者及可用恢复路径。不能自动删台账、清锁或重启服务重来。必要的破坏性清理由用户对具体对象与影响确认；不能影响同一服务下其他项目。

## 4. 合并既有 Agent 指令

只有原文件存在且 Harness 入口尚未接入时才合并。通过当前 `template render` 读取仓库模板，如 `template://repository/agent-base@1`、`agent-overlay@1`、`claude-entry@1`，以返回的正文与必需锚点为准，不复制其他人的 AGENTS 文件。

保留原文与项目特有规则；先准备完整合并结果和差异，再让用户批准这一具体修改。保留明确要求的锚点，不用模板覆盖用户内容。同一差异已获批时不再确认。

## 5. 验证能读取，并初始化知识位置

```bash
ha --root "<目标仓库绝对路径>" --json daemon status
ha --root "<目标仓库绝对路径>" --json task list
```

查看目标工作区真实状态和错误，不因文本摘要过短就判断服务损坏。空任务集是新工作区的正常结果。

部分 CLI 回执的 `evidence` 是 JSON 编码字符串。按实际类型解析，不直接假定字段在顶层；例如读取任务时先解析外层，再解析 `evidence`。报错与业务数据要分开判断。

随后读取 [harness-ceo](../harness-ceo/SKILL.md) 的[知识初始化方法](../harness-ceo/references/initialization.md)，建立或复用用户约定、模型矩阵、运行时问题、反馈与执行证据的落点。只建必要索引，不填满空表，不将公共技能中的建议当成用户事实。

## 6. 由主控带完一个真实任务

复用用户给的首任务，在主控方法下完成真实工作和仓库要求的收口。本阶段与下载引导的首任务是同一个任务。

### 真实的评审独立性

当前完成契约若要求独立执行评审，应在实施前明确可用评审身份与负责人。可能的拒绝为：

```text
Execution Review requires an independent transport-bound arbiter.
```

`HARNESS_ACTOR=agent:...` 是身份声明，不是创造独立评审者的方法。不能同一个执行者改名批准自己，也不能清空变量冒充用户的判断。需另一真实执行者、用户判断或宿主支持的独立评审通道时，交付可审阅材料后由该身份完成。只有一个模型不等于只有一个身份，但是否独立必须符合当前契约。

### 创建、执行和取证

先读 [preset-trigger](../preset-trigger/SKILL.md) 选择当前预设；一般任务形状如下：

```bash
ha --root "<目标仓库绝对路径>" task create --title "<真实任务>" --vertical software/coding --preset standard-task
ha --root "<目标仓库绝对路径>" task start <任务标识>
```

从回执取得真实任务路径，不能手拼派生的 slug。按当前生命周期要求执行，重复启动前先回读已有执行。若启动回执未带执行标识，查询 `task show`；部分版本将其放在 `evidence.lease.executionId`，需先解析 `evidence` 字符串，再读取 `["lease"]["executionId"]`。

### 任务工作树与准备步骤

输出为仓库变更的任务，在本节点第一次 `task start` 或派工时由 Harness 建立工作树：分支 `<任务标识>`，目录 `.worktrees/<任务标识>`，基线为 `origin/HEAD` 指向的远端默认分支，无远端时取主检出的当前分支。回执写明路径与基线，不需要也不应手动 `git worktree add`。不改仓库文件的任务没有工作树，`task show` 的工作区行指向任务包目录。

新工作树需要的准备写在仓库 Settings 的 `worktree.setup`，按顺序在工作树内只运行一次，环境带 `HARNESS_TASK_ID`、`HARNESS_WORKTREE`、`HARNESS_REPO_ROOT`。`init` 检测到 npm workspaces 时已写入 `node-modules`，回执会说明；其他项目按实际需要声明：

```bash
ha --root "<目标仓库绝对路径>" settings update --worktree-setup node-modules           # Node：镜像根目录 node_modules
ha --root "<目标仓库绝对路径>" settings update --worktree-setup "run: uv sync"         # Python，或 "run: pip install -e ."
ha --root "<目标仓库绝对路径>" settings update --worktree-setup "run: make bootstrap"  # 单条命令
ha --root "<目标仓库绝对路径>" settings update --worktree-setup none                   # 清空
```

重复 `--worktree-setup` 表示多步，顺序即执行顺序；`settings read` 回读。某步失败时工作树保留、启动或派工被拒，提示写明步骤编号和日志（工作树 Git 目录下 `harness-setup/step-<n>.log`）。读日志修复原因后重跑同一条 `task start` 或派工，只重跑尚未成功的步骤；不要删工作树重来。旧命名 `codex/<slug>-<id8>` 的工作树用 `task contract migrate --apply` 一次性改名，有未提交改动或在飞执行者的会被列出、不强行移动。

做实际工作并取得证据。交付日志和报告归本次执行；会支撑后续判断的可复核观察按当前事实入口记录，不为凑数量编造事实。仓库规定的事实与关系要求仍然有效。

### 确有承重选择时记录决策

读取当前决策能力和输入契约；以下展示常见结构，实际字段和合法值以所用版本为准：

```json
{
  "title": "<决策标题>",
  "question": "<要解决的问题>",
  "riskTier": "low",
  "urgency": "low",
  "decisionClass": "ordinary",
  "appliesTo": { "modules": [], "productLines": [] },
  "chosen": [{ "id": "CH1", "text": "<选择>", "rationale": "<理由>" }],
  "rejected": [{ "id": "RJ1", "text": "<真实替代>", "whyNot": "<未采用原因>" }],
  "claims": [], "fulfillments": [], "relations": []
}
```

`decisionClass` 常用 `ordinary` 或 `standing_policy`；不编造替代方案。输入文件放在工作区允许的任务产物位置。遇到 `fromFile must stay inside the workspace` 时修正输入落点，不能把临时目录当成有效来源。

原始观察先记录，再按当前 `ha relation` 契约将决策声明关联证据，选择关联派生任务。不要复制退役的 `decision relate` 命令。用户需要裁决时展示问题、选择、替代和证据后取得批准，由真实有权身份办理；不通过更换环境变量代替用户。一时答不了的问题、上手验收或同意请求，在明确具有关系写权时，用 `ha relation relate --type awaits` 把任务或决策挂到该人名下（理由写 `<question|acceptance|consent|reopen>: <问的是什么>`），只有文档或 fact 写权时，把具体问题写进获准报告并请 owner 登记关系。它会出现在对方的 `ha agenda`「等你处理」和图形界面总览「等你答复」里；对方可在图形界面就地答复，或让 Agent 执行 `ha relation unrelate <relation-id> --reason "<答复>"`，答复后回到提问方的「已答复，待你跟进」。

### 提交、独立评审、同意和完成

把收口材料写实，先 `doc status` 检查候选，再通过受支持的 `doc sync --submit` 登记本任务文档。不要提交无关候选；路径限定与执行身份的组合以当前能力为准。

收口声明、交付物、验证与风险写入任务包的 `closeout.md`，通过文档同步接受；`task submit` 从已接受的文档与本地提交冻结交付，不再接收 JSON 提交文件：

```bash
ha --root "<目标仓库绝对路径>" doc sync --submit --task <任务标识>
ha --root "<目标仓库绝对路径>" task submit <任务标识>
```

需要显式指定交付提交时，使用当前帮助中的 `--commit <40 位 SHA>`；不要用已退役的 `--from-file`。

代码文档锚通过当前 `task code-doc reconcile` 在所需阶段产生，不手写机器文件。由真实独立评审者通过 `task review-execution` 提交评审（参数与文件路径约束先读其 `--help`）；`task review` 只检查旧评审契约，不能批准完成。评审材料包含：

```json
{ "verdict": "approved", "reason": "<依据>", "evidenceChecked": ["<实际检查的证据>"] }
```

`verdict` 使用当前合法值，如 `approved`、`changes_requested`、`dismissed`。owner 的同意绑定实际已记录评审与内容版本，不把工作者的报告当作同意。使用当前 `task review-consent` 和 `task complete` 契约完成；不添加过期的提交版本参数或自己制造摘要。

`task complete` 不接受已退役的 `--ci passed`。CI 证据由完成契约要求的见证来源提供，不能用参数代替运行结果。所选任务无需 CI 时按实际契约处理；无法满足必需门时交付具体缺口，不伪造完成。

最后回读任务是否真的到 `done`，并检查原始目标确实实现。独立评审尚缺时，准确报告“环境和仓库已就绪，首任务待评审”，不能把整个引导说成已验证。

## 接入已有 Fleet 中心的边缘节点

这是已有中心的接入路线，不能在边缘重新 `init` 同一个逻辑工作区。先取得中心提供的仓库标识、项目 Git remote、TLS 地址、CA、已注册的节点标识与机器凭据、镜像存放位置及配额；身份与节点注册沿用上面的运维文档。

1. Clone **目标项目**（工具源码下载仍只由 harness-download 维护），确认 Git remote 与中心项目一致。
2. 在 clone 目录注册已有仓库的本地边缘模式：

   ```bash
   ha daemon repo register --repo-id <中心仓库标识> --root "<项目 clone 绝对路径>" --mode remote-edge
   ```

3. 在同一目录做首次同步，参数使用中心给出的真实值：

   ```bash
   ha daemon fleet edge sync --host <中心地址> --port <TLS端口> --ca "<CA文件>" --node-id <节点标识> --credential <机器凭据> --view-root "<本地镜像目录>" --quota-bytes <配额字节数>
   ```

   凭据不写入报告或共享 shell 历史；已有受保护的 `fleet-edge.json` 配置时可省略 `--credential`，由 CLI 读取。同步要求匹配的已启用 `remote-edge` 注册，不是把 ledger 当成另一个 Git remote 来拉取。
4. 回读 `daemon status` 与 `task list`，确认中心任务在本地可见。后续任务命令使用项目根下的受保护 `fleet-edge.json` 选择通道；该文件按 `packages/daemon/src/client/fleet-edge-config.ts` 的 `fleet-edge-config/v1` 契约准备，不把含机器凭据的文件纳入项目 Git。首次同步成功后仍须确认该配置可用，再按正常任务认领与派工入口工作。注册或同步失败时保留原始错误，不切换为本地初始化。

此入口的命令形状已按 CLI 帮助和路由核对；真实中心、TLS、节点授权与首任务仍须在用户的已授权部署中验收，不能把帮助通过当成 Fleet 已接通。

## 7. 交接

交付绝对 CLI 入口、目标工作区、用户知识索引、首任务与其证据、真实评审身份及未完成项。工具进入 PATH 的选项由下载技能统一负责，本技能不另提供第二套安装命令。

说明台账与项目各自的历史边界，不在台账里手工补 `git commit`。列出项目仍未提交的文件，不替用户隐瞒这些变化。下一次使用 `harness-ceo`，另一个新项目直接使用本技能。

## 完成条件

- CLI 和同版本技能可用；实际目标工作区可读写。
- 私有台账未进入公开项目；既有指令修改经过具体批准。
- 用户知识入口能找到模型、问题、反馈与证据位置。
- 一个用户指定的真实任务完成当前契约要求的取证、提交、独立评审与同意，回读状态为 `done`。
- 未提交文件、未验证部分和使用命令已如实交接；任一必需阶段仍受阻就报告该阶段，不提前宣称全流程完成。