Forge once. Work consistently across coding agents.
English · 简体中文
Harnessmith 是一个本地优先的 Personal Coding Agent Harness initializer。它把同一套个人工作规则、 渐进式文档、记忆协议和任务状态工具，安全地安装到 Codex、Cursor 与 Claude Code。
npx harnessmith一次配置，多端保持一致。你的 coding agent 会知道如何开始任务、何时读取上下文、怎样保护现有改动， 以及在什么条件下才能宣告完成。
不同 Agent 的规则文件、作用域和目录结构各不相同。手工维护通常会遇到三个问题：规则逐渐漂移、 升级容易覆盖个人内容、长任务换会话后丢失上下文。
Harnessmith 将它们拆成职责清晰的四层：
| 层 | 解决什么问题 |
|---|---|
| Instructions | 为每个宿主安装紧凑、常驻的高损失规则 |
| Progressive docs | 按任务类型读取详细流程，不把整套手册塞进上下文 |
| Memory & work state | 保存非权威记忆、紧凑用户画像和可恢复的长任务状态 |
| Installer safety | 通过预检、备份、校验、锁与回滚保护用户文件 |
Harnessmith 不替代 Agent Runtime，也不接管模型循环、工具调用、sandbox 或权限审批。Markdown 规则 属于行为引导；真正的安全强制仍由安装器、测试、CI 和宿主权限系统承担。
要求 Node.js 24.12 或更高版本。
# 交互式选择要安装的 Agent
npx harnessmith
# 或直接安装到 Codex
npx harnessmith --agent codex
# 写入前先查看所有目标和动作
npx harnessmith --agent all --project /absolute/path/to/repository --dry-run安装完成后，Harnessmith 会初始化：
- 宿主对应的规则入口和内嵌 Harness CLI；
- 用户维护的
~/.agent-harnesspersonal overlay； - 默认位于
~/.agent-docs的跨项目个人记忆； - 最多 32 条、按当前状态原位更新的紧凑用户画像。
Note
使用 LLM 或 coding agent 安装
将下面的指令直接发送给 AI。它会先读取 llms.txt，再按照其中的安装流程、目标核对、权限边界和失败处理规范完成安装。
请先阅读 https://raw.githubusercontent.com/Alessandro-Pang/harnessmith/refs/heads/main/llms.txt，并按照其中的协议为我安装 Harnessmith。
| Agent | 生效的规则入口 | Harness 目录 | 作用域 |
|---|---|---|---|
| Codex | $CODEX_HOME/AGENTS.md |
$CODEX_HOME/agent-harness |
全局 |
| Claude Code | $CLAUDE_CONFIG_DIR/CLAUDE.md，并保留 AGENTS.md |
$CLAUDE_CONFIG_DIR/agent-harness |
全局 |
| Cursor | <project>/.cursor/rules/agent-harness.mdc |
<project>/.cursor/agent-harness |
项目 |
Cursor 的文件化规则按项目安装。使用 --project 指定仓库；Harnessmith 只把自己管理的文件写入
repository-local Git exclude 和 .cursor/.ignore，不会隐藏或覆盖团队已有的整个 .cursor/ 目录。
# 安装单个或多个 Agent
npx harnessmith install --agent codex
npx harnessmith --agent codex,cursor,claude --project /absolute/path/to/repository
# 为自动化输出稳定的 JSON Lines
npx harnessmith --agent all --project . --dry-run --json
# 只读查看各 Adapter 的作用域、激活和 enforcement owner
npx harnessmith capabilities --agent all --json
# 查看安装所有权与文件完整性
npx harnessmith status --agent all --project .
# 恢复上一层安装
npx harnessmith restore --agent codex
# 逐层恢复到首次安装前
npx harnessmith uninstall --agent codex
# 安装后聚合检查 Runtime、安装与全局记忆健康度
node <harness-path>/bin/harness.mjs health --json只有项目已经执行过 init project 时，才应再传 health --project <absolute-path> 检查项目记忆；
未初始化项目记忆不等于安装不健康。
restore 和 uninstall 不会删除共享/项目 .agent-docs 或用户维护的 personal overlay。--yes 只
关闭交互，并在没有指定 Agent 时默认选择 Codex；它不会自动同意文件冲突。只有审阅目标并接受
备份接管后，才应使用 --force。
常驻 AGENTS.md 只保留高损失、不可推断的默认规则；诊断、评审、变更、发布、Git 和工具路由等
详细流程按任务读取。宿主显式加载的项目规则可细化项目工作，但不能扩大权限或降低安全要求。
内嵌 CLI 的 route / explain 根据 manifest trigger 只返回命中的文档名称、路径和 trigger，不加载
正文。search 的 --limit 只限制结果数；扫描另有独立的条目、目录、深度、文件、单文件字节、
总字节和时间预算，具体默认值以 JSON scanLimits 与 --help 为准。JSON 同时返回 provenance、
scanTruncated、scanStats 和结构化跳过原因；普通输出也会提示扫描不完整。
Harnessmith 将“如何工作”“用户是谁”“之前发生了什么”和“项目当前事实”刻意分开：
| 位置 | 保存内容 | 边界 |
|---|---|---|
| 宿主原生 memory | 宿主自动召回的历史线索 | 只作待核对输入，不是 Harness 当前画像 |
~/.agent-harness |
用户维护的个人规则和仓库关系 | 属于规则 overlay，不是记忆；升级和卸载不会覆盖 |
~/.agent-docs/profile.md |
当前身份、工作方式、技术背景、偏好和研究方向 | Harness 内唯一当前用户画像；明确要求维护时原位更新 |
~/.agent-docs/core.md 与其他全局 memory |
跨项目活跃主题、经历及高价值提炼发现 | 只保留名称级入口、来源和上下文，不保存第二份当前画像 |
<project>/.agent-docs |
项目输入、会话、工作状态、证据、提炼发现和历史归档 | 可审阅但非权威；默认被 Git 与普通索引忽略 |
docs/、ADR、代码、测试、schema、lint、CI |
项目当前事实、正式决策与可执行约束 | 权威层；稳定结论最终应提升到这里 |
项目 .agent-docs 采用渐进披露的最小模型：
.agent-docs/
├── core.md # 活跃主题与高价值记忆入口
├── inputs/ # 用户原话、附件说明、验收标准
├── sessions/ # 会话经历、交接、未完成项与下一步
├── working/ # 计划、调研、评审、状态和长任务账本
├── distilled/ # 多次经历提炼出的昂贵发现与来源指针
├── evidence/ # 脱敏测试、日志、截图 manifest
└── _archive/ # 已完成、被替代或低热度记忆
这些内容对应 input、episode、working、distilled、evidence 五类记忆；core.md 是索引。
长任务的目标、checkpoint、验收项和下一步保存在 working/<task-id>/task.json，稳定事实仍必须提升到
正式事实层。记忆支持 active、blocked、complete、superseded、archived 生命周期，以及
检查、检索、替代、归档和 proposal-only 提升。memory check --indexed 会拒绝无法从索引到达的
active/blocked 记忆，memory maintain 只读报告未索引、过期 working、可归档内容、重复 active title
和 supersession cycle。
memory list --json 和 memory check --json 提供版本化机器契约。旧 metadata 只通过显式
memory migrate --set ... 迁移：默认输出 proposal，审阅且 ready 后才使用 --apply；初始化、
task progress 和 Memory 写命令通过共享 memory-root lock 串行化。
项目记忆只在已获工作区写入授权且任务确实需要跨会话交接、未完成状态或脱敏证据时初始化；简单
问答和一次性小修改不触发初始化，只读任务即使发现昂贵结论也只报告 proposal。读取时先看
core.md 和名称/元信息，再按引用加载正文，不默认读取整棵目录或 archive。
达到沉淀阈值的任务在交付时明确报告记忆为 proposed、updated、unchanged 或 blocked；长任务
入口由 task 命令自动同步到 core.md，稳定经验只有实际写入并验证正式文档后才算完成提升。
Personal overlay 使用 projects/repository-map.yaml 保存带职责描述的仓库目录和有类型的直接关系，
repository-map.md 只是确定性生成视图。harness repository-map check 校验 schema、方向、双侧证据与
容量预算；discover packages --apply 可从本地 package manifest 幂等维护直接包依赖；verify --record 把 source fingerprint 和时效记录到宿主 state/；maintain 只读报告漂移和缺失。外部或
启发式 observation 始终停留在 proposal，不能通过自报 deterministic 自动写回。
内嵌 Harness CLI 可以保存目标、下一步、checkpoint 和 acceptance evidence。任务只能通过
acceptance gate 进入 complete，并发更新使用任务锁。task verify 只证明调用方选择的机械检查已
执行、结果新鲜且 scope 在执行期间稳定；它不自动判断自由文本 criterion 与证据的语义相关性，也
不是防篡改边界。证据绑定 task/criterion，可拒绝原样跨任务复制，但直接编辑 ledger 或替换 verifier
仍在威胁模型之外。高风险验收应由用户审阅或 CI/Host-owned verifier 定义
不可由当前任务随意替换的 predicate，再由 task verify 调用；外部 evidence 只能记为 failed 或
inconclusive，不能直接通过 gate。
- 写入前完整 staging，并对生成的
.mjs做语法检查； - 对 output、backup、record 和 ignore path 做 lexical 与 canonical containment 校验；
- 默认拒绝授权根下的 symlink、junction 和 reparse path；
- 遇到陌生文件或用户修改过的受管理文件时 fail closed；
- 多 Agent 操作使用进程锁和完整预检；失败时按已登记路径尝试事务回滚，若回滚不完整则报错并 保留 recovery path，不能声称已原子恢复；
- 升级保留可变
state/，personal overlay 永不被升级、restore 或 uninstall 覆盖。
完整边界与 enforcement owner 见架构说明和安全策略。
自动化参数与退出码
可重复传入 --agent；支持 codex、cursor、claude、claude-code 和 all。非交互调用应显式
指定 Agent，并在需要稳定协议时使用 --json。
capabilities 是不解析安装路径、不写文件的只读命令。dry-run、install result 和 status JSON 也
包含同一 Adapter capabilities，用于区分作用域、激活方式、文件所有权和权限 owner。
--no-init-global 只跳过共享全局记忆初始化，不会跳过 personal overlay。
JSON 失败输出为单条 stderr 对象，包含 version、error.code、message 和 exitCode：
| Exit code | 含义 |
|---|---|
| 1 | 未分类内部错误 |
| 2 | CLI 用法错误 |
| 3 | 安全或完整性拒绝 |
| 4 | operation lock 冲突 |
| 5 | 没有可操作的安装状态 |
环境变量
| 变量 | 用途 | 默认值 |
|---|---|---|
CODEX_HOME |
Codex 安装目标 | ~/.codex |
CLAUDE_CONFIG_DIR |
Claude Code 安装目标 | ~/.claude |
HARNESS_MEMORY_HOME |
跨项目个人记忆 | ~/.agent-docs |
HARNESS_PERSONAL_HOME |
用户维护的规则与仓库关系 | ~/.agent-harness |
HARNESS_REPOSITORY_ROOT |
仓库集合根目录 | ~/git-repo |
HARNESS_OWNER |
记忆模板 owner | 当前用户 |
宿主专用变量只存在于对应 Adapter，不会进入宿主中立的 Harness 模板和运行时契约。
仓库使用 Node.js 24.12+ 和 pnpm 10.13.0。根 dist/ 与
template/agent-harness/dist/ 均为构建产物，不要直接修改。
pnpm install --frozen-lockfile --ignore-scripts
pnpm run build
node bin/harnessmith.mjs --help
pnpm run preflight
pnpm run test:harness
pnpm run test:coverage
npm pack --dry-run项目使用 Biome、Markdownlint、Commitlint、Vitest、lint-staged 和 Husky。依赖安装、脚本编排与 CI
统一使用 pnpm；npm pack --dry-run 仅用于验证最终 npm 分发清单。
如果你希望不同 coding agent 以同样谨慎、可恢复、可验证的方式工作，Harnessmith 就是那层共同的 个人基础设施。