智能代理框架
TR
本页目录
本页面生成自 content/docs/agentic-harness/ — 下方每个小节都链接至其自身的源文件。
✎ Edit TR
智能代理框架（agentic harness）是 folio-assistant 运行所基于的交互模型——即规范智能体与用户在此平台中如何协作的规则、状态和工作流。此类行为大都已在各个独立技能和指导文档中有所描述；本页面将其整合为一份参考，以便进入会话的智能体能够查阅预期的行为规范，而不必从零散的规则中自行推导重构。
这并不涉及智能体的内部架构，而是关乎智能体与用户之间的可观察契约：交互可能处于哪些状态、如何对请求进行分类、智能体针对每个类别进入哪种工作流，以及用户在各个阶段应抱有何种预期。
交互状态
✎ Edit TR
用户与智能体之间的交互始终处于以下两种状态之一：
空闲状态
智能体没有处于活动状态的工作流，正在等待用户请求。在收到请求后，它会对请求进行分类（参见请求分类），并转换到相应的工作流状态。
工作流状态
智能体正在执行某个具名工作流——每个工作流均由一个 BPMN 流程图表示，其中智能体与用户位于各自独立的泳道中。活动工作流决定了智能体接下来的操作以及对用户的预期。
此平台中的活动工作流：
| 工作流 | BPMN 源文件 | 进入时机 |
|---|---|---|
| 撰写（论文） | authoring-a-paper.bpmn | 用户请求在论文 folio 中撰写内容 |
| 撰写（文档） | authoring-a-document.bpmn | 用户请求在文档 folio 中撰写内容 |
| 内容生命周期 | content-lifecycle.bpmn | 内容经过 validate → render → publish 阶段 |
| 文档摄取 | document-ingestion.bpmn | 用户将文件放入 uploads/ |
| 草稿至发布 | draft-to-publication.bpmn | 内容从草稿状态转为已发布状态 |
| CRDM 需求 | crdm-requirements.bpmn | 智能体检测到功能需求 |
| 证据检索 | evidence-retrieval.bpmn | 智能体检索证据以支持某项主张 |
状态转换： 当用户要求切换上下文时，工作流可以被挂起。智能体会记录当前所在位置（当前的 BPMN 活动），以便稍后恢复。同一时刻只能有一个处于活动状态的工作流，但挂起的工作流会构成一个栈——最近挂起的工作流最先被恢复。
核心规则：智能体始终清楚自己处于哪个工作流中。如果无法确定，则说明它处于空闲状态，下一个请求将开启一个新的工作流。
会话生命周期
✎ Edit TR
每个智能体会话都遵循相同的生命周期：
启动 — 运行会话启动巡检（
beans prime、beans list、scripts/session-start-coord-sweep.sh）。这会呈现当前的工作计划、默认分支的推进程度以及近期的同胞分支活动。参见AGENTS.md § At session start。分类 — 对每个用户请求进行分类（参见下一节），并路由到相应的工作流。
执行 — 智能体在活动工作流中开展工作，并遵循其 BPMN 流程。每个轮次都会报告正在处理的 bean 以及下一步计划。
提交 — 每个有意义的工作单元都会单独进行 commit 和 push。PR 在第一次 commit 时即创建，而不是等到最后。参见
AGENTS.md § Commit early, commit often, always PR。交接 — 当会话结束时（用户离开、上下文达到上限、Token 耗尽），智能体的持久化状态包括：
- 已提交并推送的代码
- 更新了状态和备注的 beans
- 包含已完成工作摘要的 Issue 评论
- 聊天记录是瞬态的；其他所有内容均会留存
请求分类
✎ Edit TR
每个用户请求都会被归入以下类别之一。分类决定了智能体进入哪个工作流。
| 类别 | 描述 | 进入的工作流 |
|---|---|---|
| 内容撰写 | 编写、编辑、扩充 folio 内容（章节、块、小节） | 撰写工作流（论文或文档） |
| 内容评审 | 评审、验证现有内容并提供反馈 | 内容生命周期 / editing-HCI 工作流 |
| 内容摄取 | 将源文档摄取到 folio 中 | 文档摄取工作流 |
| 功能需求 | 请求新的平台功能（参见 crdm-detect） | CRDM 需求工作流 |
| 信息咨询 | 询问有关平台、内容或流程的问题 | 无工作流 — 直接回答 |
| 工具调用 | 运行特定工具（content_validate、qa_sweep 等） | 无工作流 — 执行并报告 |
| 工作计划管理 | 创建、更新或查询 beans | 无工作流 — 执行并报告 |
| 缺陷报告 | 报告现有功能中的异常行为 | 分流处理：若问题较小则直接修复；若需要重新设计则走 CRDM |
功能需求检测规则
最关键的分类边界存在于内容撰写与功能需求之间。crdm-detect 技能（skills/sdlc/crdm/crdm-detect.md）提供了详细的检测信号。总结性规则如下：
如果实现该请求需要修改 folio-assistant（平台仓库）而非 folio 仓库，则该请求属于新功能，智能体应当进入 CRDM 工作流。
当无法确定时，智能体会询问：“这听起来可能需要修改平台——情况是否如此？还是说我可以在现有的内容模型内完成？”
内容工作流
✎ Edit TR
当请求被归类为内容工作（撰写、评审、摄取）时，智能体将遵循相应的 BPMN 工作流。现有文档页面对此进行了详细阐述：
发布工作流 — 从草稿到验证、渲染和发布的内容生命周期。涵盖各个角色（作者、评审人、编辑）、基础流程、活动及技能。
文档摄取 — 放入的文件如何转化为 L1 源：提取结构、派生内容、构建 L1 知识图谱以及完整性关卡。
撰写指南：
本框架并未重新定义这些工作流。它提供了入口点——对请求进行分类并路由至正确的工作流——以及出口点——在工作流完成时返回空闲状态，或在用户切换上下文时予以挂起。
确定性与智能体化处理
✎ Edit QA TR
在此，工作流处理是一个光谱，而非开关，而本框架在尚未为该维度命名时，就已经处于其上的四个不同点位：cat-harness.processes:policy enforcement 决定未启用的步骤是被拒绝还是仅予记录；relaxable="false" 决定程序包是否可以通过协商省去某个基础步骤；cat-harness.processes:decision 决定分支是由表格计算得出还是由人工选择；而提交边界关卡则由智能体之外的机制来拒绝写入。
这些并非同一维度，将其混为一谈首先就会导致理解偏差。这里至少混淆了三个问题——谁来决定分支、如果决定有误会发生什么，以及谁来执行约束。某个步骤在第一个问题上可以是完全智能体驱动的，而在第三个问题上则是完全确定性的：提交边界正是如此，智能体自由做出决定，而钩子无论如何都会拒绝写入。
现在网关会指明其属于哪一种。<cat-harness.processes:decision> 意味着由表格进行计算，手工提供的结果将被拒绝；<cat-harness.processes:judgement reason="…"> 意味着这是某人的主观判断，且必须提供原因。在该标记出现之前，“没有表格是因为这属于主观判断”与“没有表格是因为没人编写”之间是无法区分的——现在 bun run cat check:workflow-refs 会打印三向分类结果，因此“其中有多少是由模型决定的？”这个问题有了一个经过统计而非仅凭主观宣称的答案。
这一统计数据的用途在于研究，且该议题保持开放。 哪些判断节点存在安全风险、有多少内容必须是确定性的，以及在受控的上下文和记忆叠加下模型在各个子工作流中的表现如何对比，这是当前仓库能够提出但尚未解答的三个问题。包含每项主张（标记为已测量、已决定或假设）的研究议程见 deterministic-and-agentic。请将其视为一份议程：其中假设多于实测，文内亦已如实说明。
BPMN 执行：一项技能，两个引擎
✎ Edit TR TR
所有者于 2026-09-23 给出了该光谱所指的技能定义：
BPMN 执行技能： 给定流程、上下文、状态和角色，运用一项或多项技能以执行任务。
一项技能，两类工具。 两端的技能是相同的：获取流程、上下文、当前状态和角色，选取技能，并执行任务。发生变化的是运行它的工具，正如这里的其他所有工具一样，技能背后的工具是可以替换的。
| 确定性端 | 智能体端 | |
|---|---|---|
| 工具 | 任何开源 BPMN 2.0 引擎 | 智能体集群 |
| 智能体范围 | 一次执行一个任务，由引擎指派 | 大部分或全部任务 |
| 状态 | 由引擎严格持有 | 非托管：由集群持有 |
| 泳道 | 强制执行：仅泳道对应的角色可执行其任务 | 放宽限制：智能体可跨泳道操作 |
| 保障机制 | 引擎在步骤发生之前予以拒绝 | 机械 + 智能体 QA/QC 报告在事后从记录中发现 |
两种极端在规则检查的时机上有所不同，而非检查何种规则。 相同的流程、相同的角色和相同的权限对两者均适用。引擎在任务启动之前检查规则并进行拒绝；智能体集群先行操作，而 QA/QC 报告在事后根据操作记录进行检查。这仅在规则和记录均为报告可读取的数据时方可生效，而作为权限语言的 W3C ODRL 2.2 和作为执行日志的 W3C PROV-O 正是如此（所有者，2026-09-23；此举所蕴含的 Schema 即为参与者、ODRL 与 PROV-O 提案）。
大多数实际运行介于两端之间，并且是针对单个任务而非整个流程：上一节已经统计了哪些网关是计算得出的，哪些是主观判断。在通常由智能体自主执行的运行中，签名步骤可以由引擎强制执行，这是该任务本身的属性，而非整张流程图的属性。
部分已构建。 尚未接入 BPMN 引擎。机械化 QA/QC 报告现已存在：bun run cat prov:qaqc 将每个工作流实例的历史记录编写为 PROV-O 日志，并根据 ODRL 策略重新检查每个步骤，仅提供建议（Issue #1180，第 5 步；task-authorization 技能）。智能体 QA/QC 报告目前尚不存在。本节其余部分明确了目标，以便提案有据可依。
功能需求工作流（CRDM）
✎ Edit TR
当请求被归类为功能需求时，智能体进入 CRDM 需求工作流（完整文档，BPMN）。
功能需求工作流是本框架文档价值最显著之处，因为它描述了一种此前一直处于隐性状态的行为。撰写和评审工作流数月前就已形成文档；而需求工作流此前仅存在于零散的对话中。
智能体如何进入 CRDM
检测逻辑位于 skills/sdlc/crdm/crdm-detect.md。三种场景：
新会话，首个请求即为功能需求： → 确认请求，说明将首先协助梳理需求，进入阶段 1。
现有会话，已处于 CRDM 中： → 将新请求纳入当前的需求文档中，继续推进。
现有会话，正在进行内容工作： → 综合归纳功能需求，询问用户是暂停内容工作并立即处理该功能，还是先记录 bean 留待后续处理。
用户所看到的内容
智能体不会说“正在进入 CRDM 模式”或使用方法论术语。相反，它会这样表达：
“这听起来像是平台层面的变更——属于我们需要添加到 folio-assistant 本身的功能。在开始构建任何内容之前，让我先协助您理清具体的需求细节，以确保方案准确无误。我会在 Issue 上记录这些需求，以便其他人也能参与讨论。”
智能体如何退出 CRDM
CRDM 工作流在满足以下条件时退出：
- 经签发的需求所对应的所有 bean 均已解决，或者
- 用户明确推迟剩余工作
退出时，若先前有被挂起的内容工作流，智能体将予以恢复。
用户提供的内容与源材料
✎ Edit TR
用户通过多种渠道提供内容和源材料。智能体应当接收所有这些材料并将其路由到适当的流程管线中：
| 渠道 | 示例 | 路由至 |
|---|---|---|
uploads/ 目录 | 用户放入 Word 文档、PDF、Excel 文件 | 文档摄取管线 |
library/ 引用 | 用户引用已摄取的 L1 源 | 在内容中直接引用 |
content/ 编辑 | 用户直接编辑 .md 块 | 内容撰写工作流 |
| GitHub Issue 附件 | 用户向 Issue 评论中附加文件 | 智能体下载并处理 |
| 聊天界面上传 | 用户在 LLM 聊天界面上传文件 | 智能体保存至 uploads/ 或内联处理 |
| URL 引用 | 用户粘贴文档链接 | 智能体在适当时抓取并摄取 |
针对 CRDM 的特别说明
在需求收集阶段，用户提供的材料是需求的输入，而非待撰写的内容。智能体应当：
- 阅读并理解所提供的材料
- 提取与需求相关的信息
- 将其综合整理至需求陈述或需求文档中
- 在 Issue 评论中引用源材料（附带链接或附件）
示例：用户上传了一份公众咨询反馈的 Excel 表格。智能体不会尝试将其作为 folio 内容摄取；而是阅读反馈条目，并将其提炼为评审分流工具的功能需求。
Issue 与 Bean 纪律
✎ Edit TR
功能开发必须关联到 GitHub Issue。内容工作使用 beans。两者互相关联但非同义词。
Issue 与 Bean 的对比
| GitHub Issue | Bean | |
|---|---|---|
| 范围 | 一项功能、一组需求或一个用户故事 | 单个 PR 规模的工作单元 |
| 受众 | 利益相关者、需求提出者、业务分析师（BA） | 智能体、开发者 |
| 生命周期 | 开启（Open）→ 需求梳理（requirements）→ 签发（sign-off）→ 实现（implementation）→ 关闭（close） | 已创建（Created）→ 进行中（in-progress）→ 已解决（resolved） |
| 关系 | 一个 Issue 包含多个 beans | 每个 bean 引用其所属的父 Issue |
智能体守则
- 功能开发 → Issue 先行。 在动手实现之前，检查：
- 是否存在现有的未关闭 Issue？通过关键字搜索。
- 若无开启的匹配项，检查近期关闭的 Issue。
- 若完全没有匹配项，请用户创建一个。未经用户许可，切勿创建 Issue。
始终使用 feature 分支 + PR。 功能开发绝无例外。分支名称应包含 Issue 编号（例如
feat/197-word-import）。合并到 main 分支前务必询问。 必须得到用户的明确确认。由于功能变更会影响平台本身，这比
AGENTS.md中针对内容工作的一般规则更为严格。- 在 Issue 上发布轮次摘要。 每轮实现完成后（解决了一个或多个 bean），在关联的 Issue 上发布一条评论，包含：
- 本轮已完成的内容
- 尚待完成的内容（未解决的 beans）
- 供评审的已更新内容链接（预发布环境 URL、文档页面）
- 变更页面的修改前/修改后对比表
未经明确授权，绝不可关闭 Issue。 由 BA 或利益相关者来关闭。只有在 BA 明确指示时，智能体才可以关闭 Issue。智能体绝不能擅自假定任务已完成。
需求可能跨越多个 Issue。 智能体应当链接到所有相关 Issue 并说明它们之间的关系。
- Bean 不是 Issue。
beans create用于工作计划项。Issue 则面向利益相关者明确需求。切勿混淆两者。
综合技能参考
✎ Edit TR
本页描述的行为提炼自分散在仓库各处的技能和指导文档。本节将整合后的行为映射回其权威源头。
| 行为 | 源技能 / 文档 | 位置 |
|---|---|---|
| 会话启动巡检 | AGENTS.md § At session start | AGENTS.md |
| Bean 协议 | todo-manager.md、bean-coordination.md | skills/folio-core/ |
| 提交与 PR 纪律 | AGENTS.md § Commit early, commit often | AGENTS.md |
| 功能需求检测 | crdm-detect.md | skills/sdlc/crdm/crdm-detect.md |
| CRDM 需求工作流 | crdm-requirements-workflow.md | skills/sdlc/crdm/crdm-requirements-workflow.md |
| 内容撰写（论文） | authoring-math 技能 | skill_list → authoring-math |
| 内容撰写（文档） | folio-document-adapter 技能 | skill_list → folio-document-adapter |
| 内容生命周期 | content-lifecycle 技能 | skills/authoring/content-lifecycle/ |
| 文档摄取 | docs-generation.md | skills/ui/ui-core/docs-generation.md |
| 调度与协调 | dispatch-agent.md、coordinate.md | skills/folio-core/ |
| 内容类型与适配器 | AGENTS.md § Content types | AGENTS.md |
| BPMN 图绘制 | bpmn-authoring 技能 | skills/folio-core/ |
当某项技能与本页面存在分歧时，以技能为准。 本页面属于综合汇编，并非新的权威源。如果您发现差异，请修正本页面。
尚未构建的内容
✎ Edit TR
工作流状态持久化 — 本框架描述了工作流的挂起与恢复，但目前尚无跨会话持久化智能体工作流状态的机制。当前这依赖于 beans 和 Issue 评论作为代理。
自动化请求分类 — 分类表供智能体查阅参考；目前尚无自动进行路由的分类器工具。
Beans 生命周期的 BPMN 图 — beans 工作计划具有生命周期（create → claim → in-progress → resolve），虽然在
AGENTS.md和 todo-manager 技能中对此进行了讨论，但尚未绘制 BPMN 图。智能代理框架本身的 BPMN 图 — 展示空闲/工作流状态机以及分类路由的顶层 BPMN 图尚未绘制。
会话交接协议 — 会话结束前需要提交的内容规则已在
AGENTS.md中说明，但目前尚无结构化的交接工件供新会话读取，以精确恢复到上一会话中断的位置。
跟进于： #203