Loop Engineering 与 OrgReOrg 落地¶

概念关系¶

Prompt Engineering 关注单次指令如何写。

Context Engineering 关注给模型什么上下文、如何组织上下文、如何控制上下文窗口。

Harness Engineering 关注 runtime、工具、权限、workflow、审计、评测等外部工程系统。

Loop Engineering 关注 Agent 在真实任务中如何循环工作：什么时候触发、如何保存状态、如何规划、如何行动、如何验证、如何持久化、如何通知人。

Loop Engineering 更像近期围绕 Claude Code、Codex 和其他 agentic coding / agentic workflow 实践形成的工程范式，不应写成 Anthropic 官方正式产品名。它对 OrgReOrg 的价值在于：把“多轮 Agent 行为”从隐式聊天过程变成可设计、可验证、可审计的业务循环。

2026-06-13 补充判断：OrgReOrg / Harness 的 Framework 很大程度上就是要把 Loop Engineering 做好。上下文管理、SearchConnector、Ask Router、Knowledge Card、Tool Gateway、Eval、审计和项目看板不是分散模块，而是一组 loop 的组成部分。

2026-06-13 进一步补充：外部材料把 Agentic Engineering 拆成 Loop、Harness、FDE 三层，这与当前架构一致。Loop 是 Agent 内部工作循环，Harness 是上下文、工具、验证、状态、日志、预算和人工介入的工程外壳，FDE 是把这套系统嵌入真实业务并交付可衡量结果的人和方法。详见：Agentic Engineering 与本体论参考。

对我们来说，Loop Engineering 不是“提示词工程过时了”，也不是把 Agent 放开无限跑。更准确的产品化定义是：

Goal
  -> State
  -> Plan
  -> Act
  -> Verify
  -> Persist
  -> Decide
  -> Notify
  -> 下一轮或停止

先做封闭 loop：目标、步骤、验证、退出条件、权限和成本边界都由 Framework 明确。等闭环稳定后，再逐步放开探索空间。

当前第一版最小 contract 已收敛到保留的 eval、registry 和 review queue：Context Gap Collection 由 ask route、ask trace 和 pending knowledge card 验证；Knowledge Maintenance 由项目看板、实验索引、Semantic Review Queue 和 MkDocs strict build 验证；Projection Remediation 由 stale projection worker 的 timeout、retry schedule、attempt idempotency、lease token callback guard 和 safe output 边界验证。真实企微投递、签名校验、消息回调、reindex worker、持久化队列锁与 adapter callback 仍需对应 adapter 补齐。

Framework 的产品边界¶

Framework 要交付的不是某一个 prompt，也不是某一个搜索后端，而是一套可复用的 loop runtime：

loop contract：LoopSpec、LoopRun、输入输出 schema、状态字段和 handoff 条件。
context contract：按用户、任务、权限和 workspace topology 装载最小充分上下文。
action contract：SearchConnector、Ask Router、Knowledge Card、Tool Gateway、Connector / MCP adapter。
verifier contract：单测、lint、MkDocs strict build、eval、人工 review、权限策略和成本预算。
memory contract：vault、domain registry、experiment registry、project status、audit log 和外部系统对象。
governance contract：身份、权限、审批、审计、停止条件、预算上限和人工接管。

因此，framework/ 的核心职责是让不同团队能替换自己的 workspaces/variai/registry/ 私域知识后，仍然复用同一套 loop 结构来完成“发现任务 -> 装载上下文 -> 执行动作 -> 独立验证 -> 持久化状态 -> 决定下一步 -> 通知相关人”。

真实问题到 Loop Case¶

当前项目里的 loop case 应优先来自真实协作中暴露的问题，而不是为了演示临时编造。原因很简单：Loop Engineering 的难点不在 happy path，而在真实组织协作里的边界条件，包括来源不稳定、权限不清、构建失败、Agent 重复尝试、人工 review 滞后、成本异常、问错人和发布状态漂移。

真实问题进入 Harness 时，不能原样变成公开 demo，也不能让 Agent 一直停在原始截图、邮件、日志或临时链接上反复处理。它应该被转换成 loop case：

真实触发
  -> Evidence: 保留必要来源线索、时间、路径、hash、权限和脱敏标记
  -> Ontology: 抽象成对象、关系、规则、Skill、Workflow、ADR 或实验报告
  -> Runtime Projection: 变成可复跑 demo、benchmark、CI gate、review queue 或 dashboard event
  -> Review: 判断是否为缺陷、设计取舍、文档缺口、外部依赖或 adapter handoff
  -> Publish: 只发布脱敏结论、验证结果、成本/效果指标和下一步

每个真实实践 case 必须写清三项信息：

source class：来自团队讨论、企微消息、CI/Cloudflare/GitHub/GitGuardian、人工 review、实验失败还是用户反馈。
sanitization boundary：哪些原始信息被保留，哪些聊天全文、截图、临时 token、完整日志、完整 SHA、个人信息或客户材料被删除。
verification purpose：这个 case 用来验证哪个 Framework 能力，例如 Evidence closure、retry policy、SearchConnector 权限过滤、Ask Router owner 选择、Review Queue、CI gate 或项目 timeline。

一旦真实问题已经被转换成可复跑检查，后续就由检查结果和 Semantic Review Queue 接管；除非出现新证据，否则不继续回到同一个原始 incident 上循环。

Loop 的组成¶

Trigger
  谁或什么事件触发 loop

State
  当前任务、权限、上下文、历史、外部对象状态

Plan
  Agent 拆解步骤、选择工具、判断风险

Act
  调用搜索、Connector、MCP 工具或请求人工输入

Verify
  校验结果、证据、权限、测试、业务规则

Persist
  写入知识库、任务状态、审计日志、缓存或索引

Decide
  判断继续、暂停、升级、完成或失败

Notify
  通过 Web、企业微信、飞书或邮件通知相关人

一个可交付 loop 至少要有：

明确 goal 和完成条件。
外置状态文件或结构化状态，而不是只存在聊天上下文中。
可审计的 action 和 tool call。
外部 verifier：测试、lint、build、权限策略、人工 review 或 eval。
失败和成本边界：最大轮数、重复失败阈值、token/cost budget、人工接管条件。
持久化产物：knowledge card、ADR、报告、PR、任务状态或审计日志。

为什么需要 Loop Engineering¶

组织任务很少是一问一答。

例如“帮我判断这个客户项目能否本周交付”需要：

查 CRM 的客户承诺。
查项目管理系统的任务状态。
查 GitHub PR 和 CI。
查财务或合同中的交付条款。
查 BI 或工单中的上线风险。
向负责人确认异常。
输出判断、证据和后续动作。

这不是一个 prompt 能解决的问题，而是一个跨系统、跨权限、跨角色的 loop。

Search Loop¶

Trigger: 用户问题或 workflow 需要知识
State: 用户权限、任务范围、已读证据
Plan: 拆分关键词和数据源
Act: BM25 / Vector / Rerank / get_document
Verify: 证据是否足够、是否冲突、是否过期
Persist: 检索记录、引用、知识缺口
Decide: 继续检索、请求授权或生成答案
Notify: 返回带证据的回答

Search Loop 是 OrgReOrg 第一阶段最重要的 loop。

当前 Context Management Eval 已把 Search / Context Loop 的一部分实体化：每个 case 都通过 route_context_libraries 输出 route candidates、router selected libraries、permission-filtered libraries 和 trace log，同时记录 evidence coverage、token savings、knowledge gap。gap case 再通过 route_ask_request 输出 ask event、pending knowledge card 和 ask trace。后续真实 Context Router 与企业微信 Ask Router 接入时，应复用这套观测字段。

Collection Loop¶

Trigger: 搜索缺口、权限不足、系统缺失
State: 缺口类型、候选系统、候选负责人
Plan: 确定请求资料还是请求 Connector 授权
Act: 通过企业微信/飞书/Web 发起请求
Verify: 检查资料质量、权限范围和来源
Persist: 写入索引、知识库、connector registry
Decide: 关闭缺口或继续追问
Notify: 通知请求人和负责人

Collection Loop 的核心是跨部门业务系统的信息源接入与主动收集。

当前本地 contract 已先落地为 route_ask_request：发现 gap 后，Framework 选择 owner，生成包含任务、缺口、选择原因、期望格式、使用范围和 review_status 的消息，同时创建 pending knowledge card。回复侧已先落地 parse_ask_reply_text / append_parsed_reply_to_card：可把结构化文本解析成 answer、responder、permission_scope、confidence、source_uri 和 better_owner，再进入同一条 review / promote / reindex 链路。企微、飞书或 Web 工作台只是这条 loop 的 delivery / callback adapter。

2026-06-13 进一步补齐问错人反馈闭环：ask_feedback_event_from_reply 会把结构化回复中的 better_owner 或“不是我负责”信号转成 AskFeedbackEvent，apply_feedback_events 再把原 owner 标为 not_owner，并把解析出的更合适负责人提升到下一轮 suggested_owner_ids 前部。无企微 MVP 中，workspaces/variai/registry/ask-feedback-events.json 作为本地回调事件流。这使 Collection Loop 不只是“发出问题”，而是能把回复里的路由纠错持久化，并影响下一轮 Decide。

Permission Loop¶

Trigger: 工具调用、搜索、上下文注入或写入动作
State: 用户、角色、部门、项目、对象、动作等级
Plan: 判断是否允许、是否脱敏、是否审批
Act: policy check / approval request / deny
Verify: 源系统权限和 OrgReOrg 策略一致
Persist: 审计记录和授权记录
Decide: 执行、等待、拒绝或升级
Notify: 给用户和审批人明确说明

Permission Loop 确保 Agent 不因上下文能力增强而越权。

Knowledge Maintenance Loop¶

Trigger: 文档变更、系统更新、定期巡检、评测失败
State: 文档版本、索引状态、引用热度、过期标记
Plan: 判断重建索引、归档、更新或人工 review
Act: 解析、清洗、入库、生成变更摘要
Verify: MkDocs build、搜索抽样、链接检查
Persist: 更新 Site/Knowledge/index/audit
Decide: 发布、退回或创建维护任务
Notify: 通知 owner 和团队

这条 loop 让知识库不是静态文档，而是持续更新的组织知识系统。

当前最小实现由保留的 CI 门禁、实验 registry、项目看板和 Semantic Review Queue 共同承载。机械生成页只从 registry/source data 重新生成，不再把 outputs 下的分析报告当作提交事实源。

日常维护是精简的人审流程：人读的机械生成页（研发进度、实验索引、语义 review 队列）按需从 registry/ 源重新生成，经人工 review 的 PR 落地；生成物不提交、不做新鲜度门禁，也没有定时自动维护 PR 循环。机械门禁统一跑 bash scripts/ci_check.sh（与 CI 对齐）；自动化不直接推 main，也不静默删页或改写私域知识。

门禁与重新生成都替代不了人判断“内容语义是否过时”。因此语义冲突、架构口径不一致、删页/合并建议和权限疑问要进入 Semantic Review Queue。Semantic Review Queue 当前已接入本地 reviewer event log 和 scripts/semantic_review_queue.py --append-event 操作入口，后续真实 human reviewer、GitHub review comment 或企微回调都应写入同一种事件流。

PR / Site Health Loop¶

Trigger: 分支准备提交、推送、发 PR 或合并
State: CI 门禁结果、registry 驱动的生成页、文档构建状态
Plan: 跑 `bash scripts/ci_check.sh`（与 .github/workflows/ci.yml 同一套门禁）
Act: 执行 secret / boundary / architecture lint、行为 eval、单元测试和 MkDocs strict build
Verify: 全部门禁绿、生成页与 registry 源一致
Decide: 本地全绿后交 PR，等待真实 GitHub PR checks 与 review
Notify: 通过研发进度看板暴露当前 handoff

当前最小实现把合并前门禁收敛为单条命令 bash scripts/ci_check.sh，它与 .github/workflows/ci.yml 同步（由 tests/test_ci_check_mirrors_ci.py 防漂移），覆盖 secret / package boundary / architecture-alignment lint、行为 eval（context management、scope、ask router 等）、单元测试和 mkdocs build --strict。它不替代真实 GitHub PR checks 和 review comments，所以语义把关仍走人审与 Semantic Review Queue。早期为验证闭环搭的站点自维护脚手架（Docs Page Inventory、Site Publish / PR Review、GitHub Actions Run Ledger / Retry Policy、Task Skill Feedback / Review Bridge、LoopRun 报告持久化）已作为过度工程移除。

成本与验证边界¶

Loop 的价值不在“跑得更久”，而在“每一轮都有可验证信号”。Anthropic 的长任务 harness 实验展示了 planner / generator / evaluator 分工、sprint contract、Playwright 式端到端检查和文件通信的价值；同一篇实验也说明完整 harness 可能比 solo agent 显著更贵，且更强模型出现后，某些任务上的中间 evaluator 会变成额外开销。

这对 OrgReOrg 的约束是：

P0 先把每条 loop 做成小闭环，不做无人值守大循环。
verifier 只放在高风险、不确定、跨权限或长链路任务上；简单任务优先走轻量检查。
每个 loop 都要记录成本、轮数、失败原因和 handoff，而不是只记录最终答案。
evaluator 尽量使用独立上下文、明确 rubric 和工具证据，不让生成者单独判断自己是否完成。
当模型原生能力提升后，Framework 要能降低 loop 复杂度，保留真正有 lift 的 planner、router、verifier 和 governance。

与 Claude Code 实践的关系¶

Claude Code hooks、MCP 工具、skills、subagents、/goal、/loop 和长任务 session 都提示了同一个方向：Agent 的能力来自模型与外部 loop 的组合。

OrgReOrg 应把这些能力工程化：

Hooks 用于生命周期事件、权限检查和审计。
MCP 用于稳定工具边界。
Skills 用于任务模板和领域操作说明。
Sub-agents 用于分工处理搜索、审计、评测和专业任务。
Memory / Context 用于维护跨任务上下文，但必须受权限视图控制。
Goal / Loop 思想用于定义完成条件、重复节奏、退出条件和人工接管条件。

外部参考带来的取舍¶

这次外部资料给我们的可用部分：

loop 的核心是目标驱动迭代，而不是固定重复同一段代码。
可靠 loop 需要状态、反馈、验证和退出机制。
长时间运行的 Agent 不能只依赖对话上下文，需要仓库、状态文件、看板或 knowledge card 作为外置记忆。
写和审最好分开，至少要让测试、类型检查、构建、Playwright、Tool Gateway 或 eval 参与判断。
成本是硬约束。第一阶段应优先做封闭 loop，而不是开放式无人值守探索。
planner / generator / evaluator 的分离有价值，但不是免费午餐；完整多 agent harness 只应放在任务复杂度足以覆盖成本的位置。
企业级 loop 不是个人脚本问题，而是 runtime 问题：生命周期、身份、凭据、预算、审计、注册表和停止条件都要进入 Framework。
对 OrgReOrg 来说，Loop Engineering 不是替代 Context Engineering，而是把上下文路由、主动询问、knowledge card、权限检查、eval 和看板连成一个可运行闭环。

对 OrgReOrg 的糟粕部分：

不采用“Prompt 工程已死”的说法。提示词仍在 loop 内部，只是被纳入更大的系统。
不追逐“全自动全天候”叙事。企业场景必须先有权限、审计、成本和人工接管。
不把 loop 简化成 cron。定时只是触发器，真正的工程在状态、验证、持久化和退出条件。
不把 loop 当成个人效率技巧直接复制到企业里。能跑通的本地 loop，如果缺少身份、预算、审计和停止条件，规模化后会变成治理风险。

参考资料：

Addy Osmani, Loop Engineering：https://addyosmani.com/blog/loop-engineering/
53AI：《Loop Engineering 循环工程又是什么鬼？》：https://www.53ai.com/news/LargeLanguageModel/2026061058761.html
Anthropic, Harness design for long-running application development：https://www.anthropic.com/engineering/harness-design-long-running-apps
Anthropic, Effective harnesses for long-running agents：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
InfoQ：《AI 编程又变天了！Claude Code 之父、龙虾创始人同时力捧新范式》：https://www.infoq.cn/news/W3cHyeWfH0fbisevdoK6
TrueFoundry, Loop Engineering at Enterprise Grade：https://www.truefoundry.com/blog/loop-engineering-enterprise-agent-runtime
Claude Code Hooks 文档：https://docs.anthropic.com/en/docs/claude-code/hooks
Anthropic MCP Connector 文档：https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector
Claude API 概览：https://docs.anthropic.com/claude/reference/getting-started-with-the-api
Loop Engineering 争议与定义梳理：https://news.pedaily.cn/202606/565142.shtml
MacTalk / 虎嗅转载：Loop 与 goal、PR 守夜 loop、外置记忆和成本边界：https://www.huxiu.com/article/4866372.html?type=text
36氪转载：Loop 的目标、上下文、工具、评估、停止条件五要素：https://www.36kr.com/p/3848593295752071
AtomGit / CSDN 转载：封闭 loop、worktree、skills、connectors、subagents、memory 等工程模块：https://gitcode.csdn.net/6a295ad310ee7a33f27a8da1.html