PROJECT OVERVIEW
不是聊天机器人，而是一个工作系统
我想解决的不是“AI 会不会回答”，而是它能否在真实团队里知道背景、执行任务，并为结果负责。
群聊、文档、表格与个人经验彼此割裂，普通 Agent 很难理解正在发生什么。
用五层 Harness 组织 Context、Skill、任务状态、执行验证与运维治理。
让一次 AI 调用，变成可确认、可追踪、可验证、可恢复的完整业务任务。
飞书原生入口
用户不必切换工具，在日常协作现场直接提出需求、确认风险操作并接收结果。
完整任务生命周期
从理解、规划、确认、执行，到验证、回写与失败恢复，都有明确状态。
确定性控制 AI
关键门禁由代码而不是模型判断，降低重复执行、越权写入和“看似完成”的风险。
“我把一个容易失控的 AI Agent，设计成可以在真实工作场景中被确认、验证、恢复和治理的系统。
| 对比 | 直接使用 Codex | Distill Agent |
|---|---|---|
| 使用入口 | 个人打开工具，逐次描述和推进任务 | 从飞书统一入口发起业务任务 |
| 工作背景 | 依赖当前任务、工作区和个人提供的信息 | 使用团队共享、持续同步、带来源与确认状态的 Context |
| 任务执行 | 更适合按需完成一次具体工作 | 管理确认、幂等、执行、验证、回写和通知的完整生命周期 |
| 安全治理 | 由使用者在当次任务中把控 | 统一能力白名单、风险门、独立审核和运维规则 |
60-SECOND DEMO
一条飞书消息，怎样变成可靠结果
以“整理本周项目进展、更新项目表并同步风险”为例。用户只描述目标，系统负责补齐上下文、识别风险，并在写入前请求确认。
整理本周项目进展，更新项目表，并把风险同步到群里。
已完成信息核对。发现 2 项进度变化与 1 项延期风险，接下来会更新项目表并发送群消息。
写操作确认更新 3 条记录 · 发送 1 条消息
等待确认VERIFIED RESULT
任务完成，不只是一句“已完成”
项目表已读回验证3 / 3 条记录与计划一致
群消息发送成功消息 ID 与回写状态已保存
任务证据已归档后续可查询、重试或恢复
理解
识别目标、任务关系与缺失信息
召回
检索文档、群聊与历史任务证据
确认
写操作范围清晰后才请求用户授权
执行
按 Skill 与状态图完成真实业务操作
验证
读回外部结果，独立审核语义与风险
恢复
中断或超时后从安全停点继续
MY ROLE
这个项目里，我负责什么
我负责把一个模糊的“飞书 AI 分身”想法，拆成可实现、可验证、可长期运行的系统方案，并完成产品表达与技术落地。
从问题定义到系统落地
不是只接一个模型 API，而是同时设计产品入口、工作记忆、能力边界、执行流程、安全控制和运维机制。
- 产品定义明确目标用户、核心任务、风险边界，以及“完成”应该满足的证据标准。
- 系统架构设计交互、认知、能力、执行、治理五层 Harness，并定义层间数据流。
- Context 工程把飞书消息与文档加工成带来源、版本和确认状态的工作记忆。
- 可靠执行用状态图组织门禁、写 Lease、幂等、验证、独立审核与失败恢复。
- 交付与表达沉淀完整设计文档，并把复杂系统转化成可被招聘方快速理解的公开案例。
DESIGN DECISIONS
真正难的不是调用模型，而是控制不确定性
真实业务里，模型的回答“看起来合理”远远不够。系统必须在信息、权限、执行和结果四个环节建立确定性边界。
信息会过期，也会互相冲突
保留原始证据和版本，不直接把检索结果当事实；生成带来源的 Context Briefing，并让新事实进入审核区。
版本化证据 → 可追溯理解写操作不能因为重试而重复
确认、输入指纹、幂等 Attempt 与写 Lease 共同组成执行前门禁，重复请求不会再次产生副作用。
确定性门禁 → 安全执行超时后不能盲目重新开始
Checkpoint 保存流程位置，Reconcile 在重试前先读取外部状态，判断应该继续、补回写还是人工介入。
安全停点 → 可恢复任务“已完成”可能只是模型自信
Verifier 检查外部读回和业务不变量，独立 Reviewer 再审核范围、语义、遗漏与风险。
双重验证 → 有证据的结果AGENT HARNESS
五层 Harness 架构
Agent Harness 是 Agent 的完整运行环境。它把入口、认知、工作记忆、业务能力、任务状态、安全门、执行验证和运维治理组织到一起。
Distill Agent
=Distill Agent：五层 Agent Harness
五层之间是什么关系
交互层
公司前台谁提出了什么需求，它与哪条任务有关？
标准化消息、回复关系、用户反馈
认知层
项目经理＋档案室现在发生了什么，应该知道哪些背景？
Decision、Context Briefing、任务关系
能力层
岗位目录＋SOP这件事能不能做、怎样做、完成标准是什么？
TaskIntent、Skill、执行 / 验收契约
执行层
生产线＋操作员＋质检如何安全执行、恢复、验证和结束？
Task、Attempt、Artifact、验证审核结果
治理层
值班与运维团队系统是否健康，问题能否被安全修复？
探针证据、问题账本、发布 / 回滚证据
五层怎样共同工作
一条任务不是从上到下只走一次。正常情况是：请求向下流动，状态和证据持续写入，结果向上反馈。
一次完整任务的主链路
交互层 将飞书原始事件标准化，保留发送人、会话和回复关系。
认知层 判断任务关系，检索 Context，再形成 Situation、Goal、Plan、Missing、Risk 与 Next Action。
能力层 检查能力、参数、风险和确认要求。
执行层 进入 Preflight → Execute → Verify → Review → Finalize，并分别记录业务、回写与通知状态。
交互层 返回进度与结果；新的稳定信息先进入 Review Inbox。
治理层 持续观察服务、连接、Context、Skill 与部署健康。
COGNITION
一个模型 API 怎样形成认知循环
认知层由 1 个模型 + Context 库组成主 Agent。它结合回复关系、最近任务、执行结果和相关工作流，理解一句自然语言真正对应的工作。
第一次理解
先看消息、回复关系、近期任务和能力目录，判断任务关系并生成 Context 查询。
Context 召回
从项目、工作流、Memory、Views 和来源状态中取回带来源、版本和确认状态的证据。
第二次理解
把原话与证据放在一起，形成目标、计划、缺失信息、风险与下一步。
Context 库：不是“大号知识库”
Context 是一套从工作证据逐层加工出来的结构化工作记忆。它同时回答：信息从哪里来？怎样存得清楚？一次任务开始时怎样被正确使用？
2.3.1 · COLLECT
Context 怎样收集
- 消息从上次入库的最新时间继续，只抓活跃群和新增消息。
- 文档先小批量刷新索引，再按类型选择只读连接器。
- 文档无变化时跳过正文；变化时保存新 revision，保留旧版本审计。
- 每次同步保存 run 级原始批次，问题可回到抓取现场。
2.3.2 · STORE
收集后怎样存
- Raw Evidence 只追加，不修改。
- Canonical Store 自动合并、去重和刷新索引。
- Views 可自动重建，回答当前发生了什么。
- Memory 保存长期背景，不被定时任务覆盖。
- Review Inbox 等待人工确认候选事实。
2.3.3 · SHAPE
怎样变成结构化 Context
系统补充领域、项目、工作流、行动、风险、决策和时效标签，再生成来源地图与来源健康状态。
2.3.4 · USE
主 Agent 怎样使用
先生成 1～4 个检索查询，再召回证据形成 grounded briefing，交给执行 Agent 理解任务背景。
CAPABILITY
能力注册表 + Skill
主 Agent 判断任务“可以做”，不等于执行 Agent 已经具备这项能力。能力层把开放边界、执行 SOP 和验收标准写成机器可检查的契约。
Ability Registry
记录能力是否开放、名称、风险、输入、执行者和审核者。主 Agent 无需运行完整 Skill 即可读取。
Skill
说明去哪里读取、按什么顺序操作、异常怎样处理、结果写回哪里。
Execution Contract
约束不应反问的内部参数、执行范围与稳定边界。
Verification Contract
定义必须返回的事实与不变量，再由 TypeScript Verifier 检查。
EXECUTION
用 LangGraph 组织完整任务流程
LangGraph 是基于有向图的状态编排框架。它本质上是“组合代码块”：开发者亲手设计节点与连线，告诉程序第一步做什么、何时暂停、失败后从哪里恢复。
Preflight确定性门禁
校验确认、策略、容量与输入指纹；失败即停止。
Execute CodexAgent 执行
取得写 Lease，调用 Codex Worker，保存结构化结果与 Artifact。
Verify确定性验证
检查外部读回、数量关系、能力不变量和回写状态。
Review独立语义审核
新的只读 Codex 调用检查范围、语义、遗漏和风险。
Finalize确定性收口
把证据转换成 completed、failed 或 writeback_pending。
Reconcile安全停点
承接超时、中断和 uncertain Attempt；重试前先读外部状态。
Checkpoint持久化基础设施
以 taskId 保存图位置和状态，支持服务重启后继续。
为什么选择 LangGraph 组织任务
装修好的办公室
前台、电话、房间和员工工位基本齐全，适合快速连接渠道与 Agent。
自己设计的生产线
工位、检查点、暂停条件与返工路径都由我们定义，适合长期、复杂、可审计任务。
| 对比问题 | OpenClaw | LangGraph |
|---|---|---|
| 首要问题 | 把渠道、用户和会话路由给合适的 Agent | 任务经过哪些步骤，当前执行到哪里 |
| 组织方式 | 独立工作区、会话、渠道绑定与子 Agent | Agent / 子图成为流程节点，由状态和条件边控制 |
| 突出能力 | 渠道接入、会话、多 Agent 路由与 Skill 生态 | Checkpoint、中断、条件分支、恢复与持久化执行 |
| 更适合 | 多渠道个人助手、知识问答、通用工具调用 | 高风险写操作、长任务、审批、对账和严格验收 |
GOVERNANCE
Harness 之外的简易治理系统
业务 Agent 能跑起来，只解决了第一步。长期运行还需要持续观察飞书连接、Context 新鲜度、部署版本与 Skill 漂移。
可观测
健康探针、问题账本和版本状态可见。
影子运行
自动巡检和评估，但不修改生产。
受限可逆修复
只有阶段门和用户授权同时满足，才允许白名单修复。
质量治理
观察 Context、Memory、Skill 与评测漂移，不自动改写业务资产。
运维可以修复系统，但不能替用户做业务决定，也不能绕过任何业务确认门。
DETERMINISTIC CONTROL
横跨三层的确定性安全控制
安全控制不是单独一个 Agent。它分布在不同层级的模块中，通过代码负责任务准入、状态、幂等、验收和收口。
Ability Registry
能力白名单、风险、输入、确认要求、执行契约与验收契约。
Orchestrator
任务归属、补参数、等待确认，以及允许发生的状态变化。
Task Store
Confirmation、幂等 Attempt、Lease、Artifact、Outbox 与业务状态事实。
Execution Harness
Preflight、条件边、Checkpoint 恢复、Reconcile 停点与 Finalize。
Verifier
外部读回声明、必填事实、数量关系、能力不变量与回写状态。
Ops Controller
授权、allowlist、隔离 worktree、diff、独立审核、发布与回滚门。
OUTCOME & NEXT
当前成果、反思与下一步
我选择只展示可以被项目本身核验的成果，不用未经验证的效率数字包装案例。下一阶段会用真实任务数据检验系统价值。
覆盖入口、认知、能力、执行与治理。
把门禁、执行、验证、审核、收口与恢复显式化。
让能力边界、状态、幂等、验收和运维可治理。
WHAT I LEARNED
最重要的反思
Agent 产品的核心竞争力不只是模型能力，而是能否把不确定的模型输出，放进确定的业务边界、状态和证据链里。
NEXT VALIDATION
下一步怎样验证
- 选定一个高频写操作场景进行真实试运行
- 记录任务成功率、人工介入率与平均耗时
- 统计重复执行拦截与异常恢复成功率
- 用真实反馈迭代 Context 与 Skill 质量
QUESTIONS
常见问题
01Context 和 Skill 都提供背景信息，有什么区别？＋
- Context 是认知层的工作记忆，回答“这次任务开始前，Agent 应该知道什么”。
- Skill 是能力层的业务 SOP，回答“这类任务现在具体应该怎样完成”。
- LangGraph 是执行层的流程骨架，回答“任务经过哪些状态，何时暂停、恢复或转入异常分支”。
- Codex 是执行层中承担 Worker / Reviewer 角色的具体运行时之一。
02Codex 作为执行层，是否遵从 LangGraph 架构？＋
更准确的说法是：Codex 是 LangGraph 执行图中的一个节点，而不是 Codex 内部按照 LangGraph 思考。
- LangGraph 决定何时进入
execute_codex。 - Harness 在调用前检查 Confirmation、幂等键和 Lease。
- Codex 按选定 Skill 工作，返回结构化结果。
- LangGraph 再进入 Verify、Review 或 Reconcile。
03Codex 自己的 Harness 和 Distill Agent 的 Harness 有什么区别？＋
Codex Harness 解决“一次 Codex 运行怎样使用工具、受沙箱约束并完成自检”；外层 Harness 解决“一个团队共享的业务任务怎样跨消息、跨进程和跨重启持续存在”。
- 执行前门禁：固定检查用户确认、输入指纹、策略、容量和写 Lease。
- 跨运行幂等与恢复：Task Store 保存业务事实，Checkpoint 保存图执行位置。
- 执行后独立裁决：Verifier 检查硬事实，独立 Reviewer 做语义审核。
- 副作用分段收口：业务成功但回写失败时，只补回写，不重做业务操作。
04Task Store 和 LangGraph Checkpoint 有什么区别？＋
05多轮对话中，怎样保持同一个 task_id？＋
- 优先使用用户明确写出的 task_id。
- 其次使用飞书回复关系绑定的 Bot 任务消息。
- 再把同一发送人的最近任务作为兜底候选。
- 只有出现“刚才、上一条、失败项、回写、重试”等指代且判断置信度足够时才自动关联；否则要求用户明确 task_id。
06一个任务怎样把 Harness 的五层串起来？＋
交互层 接收消息、保存 message ID、判断新任务或回复并去重。
认知层 生成 Context 查询，召回证据，形成目标、计划、风险和下一步。
能力层 匹配能力与 Skill，准备确认、执行契约和验收契约。
执行层 Preflight → Execute → Verify → Review → Finalize，并持久化事实。
治理层 观察连接、Context 与部署健康，异常进入问题账本。