zizi 9bed4a426e refactor: separate Muse business and agent framework layers

2026-08-24 02:16:01 +08:00

17 KiB

Raw Blame History

双底座适配接缝 plan

日期：2026-08-24 范围：agent-example/；父仓仅改仍指向本仓旧路径的活文档。状态：取代 2026-08-23-目录分层改造，作为当前执行入口；阶段 0、阶段 1 与阶段 2 的无宿主门禁已落地，DSH 配置与无凭据失败闭环已核实，真实模型、只读工具闭集和 Muse 业务旅程仍未验收。架构事实：DSH / Pi 与 Muse 的框架业务分离研究（2026-08-23；DSH 上游 0.1.1-rc.2 / Pi 本机 0.84.2）。

1. 意图

上一轮目录分层抓住了主权边界，但不能再按「把 58 个 Skill 搬进嵌套目录」当主路径执行。

正确合同：

DSH / Pi 负责一次 Agent 如何运行；Muse 负责作品现在是什么、候选能否进正典、用户做了什么决定。 代码上可以只有 muse/ 与 framework/，中间必须有一条适配接缝。适配器不是第三个业务所有者。

目标结构：

Muse 业务层
  作品 / 正文 / 实体 / 范式
  Context Freeze / asOf / 候选 CAS / 人闸 / 额度 / 证据
  Studio / 决策通道
          │
          │ FrameworkPort
          ▼
framework/
  RoleTaskRequest 由 Muse 解析之后，只进下面三类对象：
  FrameworkExecutionRequest / FrameworkEvent / FrameworkExecutionResult
     ┌────┴────┐
     ▼         ▼
  adapters/pi  adapters/dsh
     │         │
   Pi          DSH + Cordis

本改造先把依赖方向拆开，再用同一份冻结任务接 DSH 最小切片。不再把剩余 git mv 当主工单。

2. 对上一份 plan 的修正

旧 plan 假设	核对后的事实
`framework/` 还不存在，从拆 dispatch 五文件开始	`framework/primitives/agent` 与 `framework/adapters/pi` 已在盘上
目录分开 ≈ 框架业务分开	目录已分开；`runner.py` 仍 `import agent_trace`，`agent_task.py` 仍加载 Muse 角色合同，`dispatch_agent_task.py` 仍做 `fixed-opus` 检查
方法 Skill 沉到 `.agent/skills/{planning,writing,diagnosis}/` 即可被任何宿主发现	嵌套已经发生。DSH 默认 Skill Provider 不支持递归 `**/SKILL.md`。不能回滚嵌套，必须加扁平投影或自定义 `SkillProvider`
「插件 / Skill / Agent」是 DSH 原生三层	DSH 原生是 Cordis service、scope、event waterfall、Session、Agent preset、subagent provider。Muse 的三层是上层约定，不能把 Skill 文本当权限
`dsh-llm-pi-ai` 能复用 Pi coding agent	它只用 `@earendil-works/pi-ai`。DSH 与 Pi coding agent 仍是两个适配器
session log 投影进库可以当原子审计	DSH `session/event` 观察与持久化异步分开；session log 是执行事实，不是内容权威
用 `agent/turn-stopping` 当 JSON Schema 门	结构化输出由 Muse 任务宿主或明确声明该能力的 Provider 校验

旧 plan 第 8 节映射表描述的 muse/ 落点大体已经在盘上。剩余缺口是 SoT 仍在 muse/sot/、入口文档目录树仍写旧根、以及框架反向依赖业务。

3. 当前磁盘（执行起点，不是目标）

根上已是 framework/ + muse/ + .agent/（方法 Skill 嵌套）+ docs/ + tests/。requirements.txt 已指向 muse/platform/* 与 muse/lifecycle/quality/humanization。

仍未拆开的耦合（本轮已读源码，不是推断）：

位置	问题
`framework/adapters/pi/runner.py`	`from agent_trace import AgentTraceWriter`
`framework/primitives/agent/agent_task.py`	`import muse_role` / `muse_role_contract`；`SUPPORTED_AGENT_ROLES` 绑死五个 Muse 角色
`muse/lifecycle/dispatch/skills/dispatch-agent-task/scripts/dispatch_agent_task.py`	在派发前做 `fixed-opus` 模型策略检查
`tests/architecture/test_import_boundaries.py`	适配器白名单已是 `framework/adapters/pi/runner.py`，不禁止框架 import 业务证据脚本

Skill 发现：

Muse harness 已扫 .agent/skills 与 muse 下 **/SKILL.md，以 skills.json 的 skill_path 为位置 SoT。
15 个方法 Skill 已在 .agent/skills/{planning,writing,diagnosis}/<name>/。
编排 Skill 已在 muse/**/skills/<name>/。
DSH 默认发现器对这套嵌套布局会漏掉方法 Skill，除非自定义 Provider 或生成扁平投影。

本机运行基线（2026-08-24）已核实：dsh --version 为 0.1.1-rc.2；dsh --profile web --dump-config 与 dsh --profile headless --dump-config 退出码为 0；无 API key 的 headless 任务按 MISSING_CREDENTIAL 失败关闭。该事实只证明 profile 可组合和错误路径可达，不证明真实模型或 Muse 业务旅程可用。framework/adapters/dsh/ 已补无工具 fresh 对照适配器与 session JSONL 归一测试，生产默认仍是 Pi。

Skill strict 门禁在研究采样点为 9 个 blocking + 2 个 major，迁移稳定后必须重跑；采样数字不构成当前完成证据。

4. 稳定对象（先固化，再写适配器）

Muse RoleTaskRequest
  角色、业务任务、冻结上下文、模型策略、输出 Schema
        │  Muse 解析（角色合同、额度、fixed-opus / governed-chain）
        ▼
FrameworkExecutionRequest
  system prompt、user content、工具闭集、已解析模型、超时、会话模式
        │  适配器
        ▼
FrameworkEvent
  framework、session、sourceSeq、kind、payload hash
        │
        ▼
FrameworkExecutionResult
  final output、actual model、usage、stop reason、artifact locator
        │  回到 Muse
        ▼
Schema 门 → 一致性检测 → 质量审核 → 人闸

框架只处理后三类。workId / targetChapter / candidateStatus / acceptanceEligible 不得成为框架判断条件。

插件可以做：只读 Context Tools、角色 Prompt Provider、工具准入与 asOf 防护、事件观察与 raw 导出、可选 Trajectory / TUI。不得做成模型可喊 Skill：decide-candidate、confirm-knowledge-draft、record-run-evidence、freeze-context、assemble-context、Canonical 写入、CAS、人闸、额度结算。

5. Skill 挂载：不回滚嵌套，补发现投影

方法 Skill 的所有权留在 .agent/skills/{planning,writing,diagnosis}/（Muse 源）。 DSH / Pi 只消费同一源的扁平投影，禁止复制第二份正文：

.agent/skills/planning/scene-craft/SKILL.md     # 源（已在盘上；scene-craft 实际在 writing/）
framework/catalog/dsh/skills/scene-craft/SKILL.md   # 生成物：单层 <name>/SKILL.md
framework/catalog/pi/…                              # 若 Pi 也需要显式 override，同样生成

生成器读 skills.json 里 invocation=model_routed 的条目，写出 DSH 能发现的 <name>/SKILL.md（链接或渲染，不是手改副本）。编排 Skill 不进该投影。

机械门：

model_routed 必须在 .agent/skills/ 下；orchestrated 必须在 muse/ 下。
业务 manifest、Pi catalog、DSH catalog 三方对账。
DSH 默认发现器扫到的名字集合 = model_routed 闭集；漏发现失败关闭。

二选一实现，阶段三开工前裁定，不允许「嵌套了就算 DSH 能用」：

生成扁平投影（推荐，零运行时插件）。
自定义 DSH SkillProvider 读 skills.json。

6. 阶段

依赖：0 可与 1 并行；2 依赖 1；3 依赖 0+1+2 且本机有可执行 dsh（或 CI 固定版本）；4 依赖 3 的同源对照证据。

0  活文档与 Skill 门禁基线
1  收紧 Pi 接缝（对象拆分 + 依赖方向）
2  跨框架协议、工件与门禁
3  DSH 最小切片：writer / planner
4  detector / extractor / judge → 再决定生产主宿主

不把「迁完剩余目录 / 把 SoT 搬到 muse/sot」做成前置。那些跟提交走，不单独开搬家阶段。

阶段 0：活文档与 Skill 门禁基线

意图：入口文档不再描述已不存在的根目录；Skill strict 失败项先清成后续迁移基线。

改：

AGENTS.md §3 目录树改成当前 framework/ + muse/ + .agent/skills/{planning,writing,diagnosis}。
README.md、.agent/_index.md 同步。
研究采样点的 9 个 blocking + 2 个 major：先重跑 muse/lifecycle/quality/harness/skill_harness.py --strict，按当场输出修 invocation / 死链，不沿用采样数字。
test_import_boundaries.py 扫描范围去掉已不存在的根（若仍列 dashboard/ 作 ACTIVE root，改成 muse/authority/studio 或删除空根）。

验证：

.venv/bin/python muse/lifecycle/quality/harness/skill_harness.py --strict
.venv/bin/python tests/architecture/test_skills_index.py
.venv/bin/python tests/architecture/test_import_boundaries.py

文档：本阶段只改入口树与发现合同表述，不改领域 SoT 正文。

阶段 1：收紧当前 Pi 接缝

意图：Pi 行为与回执字段不变；框架不再拥有 Muse 合同。

改：

拆 AgentTaskSpec：
- Muse：RoleTaskRequest（角色、冻结输入、modelPolicyRef、outputSchemaRef、toolPolicyRef、contextRef）。
- framework：FrameworkExecutionRequest（已拼好的 system/user、工具闭集、已解析 model id、超时、fresh|continue、仅 runId 关联）。
AgentTraceWriter 改为注入的 TraceSink 协议；framework/adapters/pi/runner.py 删除 import agent_trace。
fixed-opus / governed-chain 校验移出 dispatch 里「看起来像框架」的位置，回到 Muse 角色策略（dispatch 在调用 adapter 之前解析模型；adapter 只记账 requested/actual）。
agent_task.py 不再 import muse_role_contract。角色文件与角色合同的装配留在 muse/lifecycle/dispatch/。
端口纯度门：framework/ 不得 import agent_trace、Postgres、候选状态机、muse_role_contract、额度常量。

验证（必须证明「重构不改业务结果」）：

.venv/bin/python tests/architecture/test_import_boundaries.py
.venv/bin/python tests/skills/dispatch-agent-task/test_dispatch_agent_task.py
.venv/bin/python tests/skills/record-run-evidence/test_agent_trace.py

新增：tests/architecture/test_framework_port_purity.py（扫描 framework/ 的 forbidden import）。现有 dispatch 离线项全绿；不把真实模型调用算完成。

文档：framework/README.md、dispatch-agent-task/SKILL.md、边界合同.md 结构列、07 §2 执行底座——写明三类框架对象与 Muse 解析职责。

阶段 2：跨框架协议与真实工件

意图：Pi 与未来 DSH 共用同一套 Event / Result，而不是各自发明业务含义。

改：

固化 FrameworkExecutionRequest / FrameworkEvent / FrameworkExecutionResult Schema（Draft 2020-12），放 framework/primitives/。
事件必须带 framework、frameworkVersion、sessionId、sourceSeq、payloadSha256；未知事件进 raw，不得丢弃后声称轨迹完整。
定义 Pi JSONL / 运行目录 transcript 与（预留）DSH session artifact 的定位、hash、flush 规则。flush 前 = live view；flush 后完整工件 = 审计证据。投影幂等、可检测 seq gap。
只读五工具输出保持结构化 JSON；Pi 与 DSH 只做工具适配，SQL 仍在 muse/authority/tools/read/。
Skill 扁平投影生成器（或记录「阶段 3 用自定义 Provider」的书面裁定）落地，并加三方对账测试。

验证：flush / 崩溃重放 / seq gap / 重复投影的离线测试；catalog 对账测试。无 dsh 二进制时，DSH artifact 规则用夹具，不假装跑过 DSH。

文档：协议 Schema 本身是合同；08 只引用「执行日志 ≠ 正典」，不复制字段。

阶段 3：DSH 最小切片（writer / planner）

前置：本机或 CI 有可执行的固定版本 dsh。本机已满足该安装前置（0.1.1-rc.2），但真实模型、只读工具插件和同源业务旅程仍未验收；没有这些证据不得把阶段 3 或 DSH 生产接入标记完成。

只做：

framework/adapters/dsh/：唯一碰 dsh 二进制/SDK 的位置，列入适配器白名单。
一个 profile：只读工具插件 + 角色 preset/prompt section + tools.guard + 事件观察 + 最终工件导出。
自定义 SkillProvider 或消费阶段 2 的扁平投影。
能力矩阵：角色 × 场景 × Provider 声明 toolFilter / persona / outputSchema / continuable；不支持则启动前失败，禁止静默降级。
评委不在本阶段。子代理默认 spawn 新会话。

对照：

同一 RoleTaskRequest（冻结输入 + 角色合同 + 模型策略）
    ├── Pi Adapter
    └── DSH Adapter
          ↓
同一 Schema 门 / 一致性检测 / 质量审核 / 人闸

对照指标：Schema 合规、工具越权、asOf 泄漏、超时与恢复、轨迹完整性。质量分数是观察项，不代替机械门。

不做：迁 58 个 Skill、DSH 内嵌正文台、Canonical 写入插件、detector/extractor/judge。

文档：framework/adapters/dsh/README.md、docs/research/2026-08-24-dsh-local-runtime-baseline.md；07 补「双适配器、单一业务门」；AGENTS.md 写明生产默认仍是 Pi，直到阶段 4 有证据。

阶段 4：其余角色与生产主宿主

先 detector / extractor，再 judge。评委必须 fresh spawn，禁止 fork 父历史；进程外 Provider 缺能力则启动失败。
Trajectory / Conversation Node 只投影执行；Studio 仍读库。节点必须带稳定业务 ID。
以同源对照的机械指标 + 标注为 external-live 的旅程证据，决定 DSH 是否成为默认执行宿主。没有回放和失败恢复证据前，Pi 保留为可用适配器。
两者都不得写 Canonical。

7. 机械门（阶段 1 起逐条装，阶段 3 齐）

端口纯度：framework/ 不得 import 业务证据、库、候选状态机、角色合同、额度。
能力矩阵：Provider 不支持的能力启动前失败。
Canonical 写入：模型可见工具闭集无写正典动作；写者白名单。
冻结与泄漏：只读工具核验 workId / asOf；未来章、oracle、其他评委结果不可见。
结构化输出：Draft 2020-12，不用 turn-stopping 冒充。
轨迹完整性：源 session、sourceSeq、hash；flush 后才算审计；投影幂等。
Skill 发现：manifest / Pi 投影 / DSH 投影对账；嵌套源不得被当成 DSH 已发现。
双框架黄金旅程：同一冻结任务两臂，后续统一进 Muse 门。adapter fake 不算宿主证据。
版本：DSH、Pi、业务合同、角色合同、输出 Schema 各有版本和哈希。

8. 文档同步（跟阶段走，不是收尾）

阶段	必须改的活文档
0	`AGENTS.md` §3 树、`README.md`、`.agent/_index.md`
1	`framework/README.md`、`dispatch-agent-task/SKILL.md`、`边界合同.md`、`07` §2
2	框架 Schema 文件本身；`08` 仅引用执行日志边界
3	DSH adapter README、`07` 双适配器、AGENTS.md 默认宿主
4	角色合同里评委 spawn 纪律（若尚未写死为机械门）

仍被 SoT 引用、路径会随阶段 0 入口树一起对账的：创作周期与Skill导读.md、可视化模块合同.md、muse/authority/db/表映射.md、父仓 design-docs/流程-02B（若仍指向 muse/sot）。死链失败关闭；不改 docs/write-chapter/artifacts/ 与本文件对照用的旧路径。

SoT 已位于 muse/sot/：不阻塞阶段 1–3。后续若调整归属需单独提交，并同步 ROLE_CONTRACT_RELATIVE_PATH 与相对链接。

9. 明确不做

不把业务做成 DSH 插件全集。
不回滚方法 Skill 嵌套；用投影或自定义 Provider 兼容 DSH。
不把 dsh-llm-pi-ai 当成 Pi coding agent 适配器。
不把 session log 当正典，不把 DSH Session 与 PostgreSQL 当同一事务。
不先做 DSH 正文台、不先接评委、不先让两个框架各写一套写作逻辑。
无独立可执行 dsh 时，不声称 DSH 集成完成。
不改候选状态机、CAS、人闸通道、表结构。

10. 完成的定义

阶段 0：入口文档与磁盘一致；当场 skill_harness.py --strict 绿。
阶段 1：端口纯度门绿；既有 Pi 派发离线测试绿；框架不再 import agent_trace / muse_role_contract。
阶段 2：三类对象有 Schema 与离线重放测试；Skill 投影或 Provider 裁定已落盘并有对账测试。
阶段 3：可执行 DSH 上 writer/planner 与 Pi 同源对照有机械证据（Schema / 越权 / asOf / 轨迹）。
阶段 4：未获对照证据前，生产默认宿主不得改口。

无自动化绿证据不得声称阶段完成。研究记录里的采样数字只证明当时，不构成本 plan 的完成证据。

17 KiB Raw Blame History Unescape Escape