从零散 CLI 命令到可靠的 AI Agent 工作流¶
快速答案： 可靠性来自围绕命令序列建立明确边界：先分类请求，选择最小路由，保护文件修改，只持久化确实需要恢复的工作，并用证据验证结果。Harness CLI 提供这些边界，但不会把每个只读问题都强行变成重型计划。
Shell 别名可以启动 AI 编程客户端，却无法单独回答：这次任务是否可以安全修改、上一次尝试是否应该恢复、一个绿色命令是否真的覆盖了所有变更面。原始 CLI 包装器与可靠工作流的区别，就是执行周围有没有清晰契约。
五个重要边界¶
1. 输入边界¶
把请求转成明确目标，区分提问、检查、小修改和多步骤目标。空输入或只有确认语时，不应该创建工作项。
2. 路由边界¶
在选择客户端或 playbook 之前，先选择 noop、direct、guarded 或 planned。这样流程强度才能和风险匹配。
3. 编辑边界¶
创建或修改文件前运行编辑前安全门禁，检查影响范围、依赖、风格和测试覆盖。如果代码图服务不可用，应明确使用定向仓库搜索和现有测试作为回退，而不是悄悄跳过检查。
4. 状态边界¶
只有在继续工作确实有价值时才持久化计划。项目 registry 可以描述可用上下文，不代表每个 prompt 都自动注入完整历史。恢复任务时只加载选定任务和 handoff，不加载无关会话噪声。
5. 证据边界¶
运行与变更面匹配的检查，并说明每个检查证明了什么。构建成功只证明构建成功，并不自动证明外部浏览器会话、模型 provider 或人工批准已经可用。
一个具体的迁移方式¶
假设旧流程是：
claude "update the docs"
git diff
它留下了太多未回答的问题。可以换成下面的契约：
- 明确涉及哪些公开界面和语言。
- 如果横跨内容、导航和测试，就把请求分类为
planned。 - 编写计划，注明文件所有权和验收检查。
- 每批编辑前运行
pre-edit-safety-gate。 - 不把生成目录加入源文件变更集。
- 运行内容契约、站点同步检查和严格构建。
- 记录准确的验证证据，以及没有测试的外部依赖。
具体命令取决于项目，但顺序是可复用的。这使流程可以在 Codex CLI、Claude Code、Gemini CLI、OpenCode、Grok Build 等客户端之间迁移。
让浏览器工作也变得显式¶
浏览器自动化同样容易被原始命令隐藏状态。可靠模式是：
- 使用目标 profile 启动可见的 CDP 浏览器。
- 连接浏览器。
- 先读取语义快照或抽取文本。
- 执行一个可见动作。
- 等待状态变化，再次读取页面。
- 对认证墙和敏感外发操作保留人工控制。
这样浏览器步骤可审计，也不会把“已配置 MCP 服务”误报成“线上会话已成功”。
用内容契约保护文档工作¶
文档是公开产品的一部分，也值得拥有测试。实用契约包括：
- 每个 P0 页面在所有支持语言中都存在；
- 多语言导航只指向存在的文件；
- 首页链接推广文章之前，文章文件已经存在；
- 旧声明要么删除，要么明确标注为兼容性行为；
- docs 和 blog 站点都能通过严格 MkDocs 构建。
这些检查小而快，特别适合 SEO/GEO 工作，因为它们能在文案快速变化时保护可抓取结构。
常见问题¶
这是不是给 CLI 套了一层项目管理？¶
不是。这里的边界是可执行检查和状态规则：路由分类、编辑安全、上下文选择和验证。它们减少的是 Agent 在不可逆或难复核节点上的歧义。
是否应该持久化每次完整对话？¶
不应该。Pull-based 上下文更可预测。持久化稳定项目事实、选定工作项和有用 handoff，下一次任务需要时再加载。
最小升级是什么？¶
先加入路由矩阵、编辑前检查和验证清单。只有当工作确实需要恢复或独立所有权时，再加入 solo harness 或团队委派。