writing-agent/docs/context-assembly.md

上下文拼接

1. 定位

Worker / skill 执行时，Runtime 将黑板 tag 与固定体裁说明拼成 LLM prompt。
拼接规则在 skill 定义期定制；拼接执行由 Runtime 机械完成；agent 不临场改 inputTags。

详见 docs/worker-skill-format.md（字段）、docs/tag-blackboard.md（标签原则）。

---

2. 上半固定、下半动态

每条 worker prompt 自上而下拼接（一段式 stack，越稳定越靠上）：

┌─ Preset（会话 presetId）────────────────────────────┐
│  生成参数、prompt 条目（system / 文风片段等）       │
│  见 preset-format.md；与 skill 包正交               │
└────────────────────────────────────────────────────┘
┌─ 上半：固定上下文（Static）────────────────────────┐
│  shared-context.md（包级体裁约束）                  │
│  worker SKILL.md 正文（能力说明、自检）             │
│  contextSegments 中 tier=static 的 tag              │
│    例：角色卡.确认稿、世界.蓝图、设计.worker集 切片  │
│    （含 narrator 的 presentation，无单独美学纲领 tag）│
└────────────────────────────────────────────────────┘
┌─ 下半：动态上下文（Dynamic）────────────────────────┐
│  contextSegments 中 tier=dynamic 的 tag             │
│    例：运行.事件流、可见信息、用户.最新输入          │
│  按 policy 裁剪（tail_lines、tail_tokens、concat）   │
└────────────────────────────────────────────────────┘

原则：

越稳定、越少改 → 越靠上（preset / static）
越增量、每轮变 → 越靠下（dynamic）

不是 agent 在游玩时自由往 prompt 里插段落；agent 只决定 invoke 哪个 skill；该 skill 的契约决定看见什么。

---

3. 三分工

谁	管什么	何时定
Skill 定义（workers/*/SKILL.md）	inputTags、contextSegments、tier、policy、隔离	写 skill 时
实例 manifest	启用哪些 run skill、contextProfile 选哪档 variant	实例化时 agent 产出
Agent	何时 invoke 哪个 skill；可用 read_blackboard 辅助决策	运行中
Runtime	assembleWorkerContext() 唯一拼接点	每次 invoke

---

4. contextSegments（Worker Skill 字段）

在 SKILL.md frontmatter 声明（inputTags 仍保留，作为取数白名单）：

contextSegments:
  - id: persona
    tier: static
    tags: ["角色卡.确认稿"]
    label: "## 角色设定"
  - id: world
    tier: static
    tags: ["世界.蓝图"]
    label: "## 世界"
  - id: history
    tier: dynamic
    tags: ["运行.事件流"]
    policy: tail_lines_80
  - id: turn
    tier: dynamic
    tags: ["可见信息", "用户.最新输入"]
    label: "## 本轮"

字段	含义
tier	static（上半）或 dynamic（下半）
tags	从黑板取的 pattern，须在 inputTags 内
label	拼进 prompt 的 Markdown 标题（可选）
policy	动态段裁剪，见 §5

未声明 contextSegments 时，Runtime 回退：按 inputTags 顺序输出 JSON inputs。

有 contextSegments 时：按 static → dynamic 顺序拼 Markdown（含 label 标题）；实现见 src/skills/context-segments.ts → assembleWorkerContext()。

创作前情：创作.已验收内容 存各单位最后一次验收的内容切片，拼装时格式化为只读前情提要。

---

5. 动态段裁剪 policy

policy	行为
latest	每 pattern 取最新一条（默认）
concat	同 pattern 多条合并
tail_lines_N	事件流等取最后 N 行
tail_tokens_N	按估算 token 截断（预留）

上下文过长时（本节管 Run worker 拼装；创作会话见 design-orchestrator-guide.md §7.2）：

1. 优先靠 policy 裁剪动态段
2. Run 验收后压缩：过程 tag 归档，仅终产物 + 上下文.定稿摘要 进入下一 worker（compress-after-worker.ts）
3. 实例 manifest 可覆盖 variant（如 historyPolicy: last_10_turns）
4. 长线再考虑显式 compress-history / RAG，禁止「完整历史喂一个 LLM 再筛给另一个」

创作不走本拼装栈：讨论放 session messages；单位验收后 删交互、留产物。Worker 执行仍始终按契约从黑板重装。

---

6. contextProfile（实例 manifest）

实例化阶段产出（写入 设计.worker集 或 Book manifest），agent 只选预置档位，不列 tag：

{
  "runSkills": ["world-simulator", "narrator"],
  "contextProfile": {
    "narrator": { "variant": "card_rp", "historyPolicy": "last_15_turns" },
    "world-simulator": { "variant": "light_rules" }
  }
}

variant 在 skill 包内预定义多组 contextSegments 覆盖或 policy 差异。
例：narrator 的 card_rp 强制 static 含 角色卡.确认稿；short_emotion_flow 缩短 dynamic 历史。

---

7. 隔离

与 inputTags 正交，由 skill 声明 contextIsolation：

contextIsolation: none | role_pov | blind_review

• role_pov：role-decide 等，Runtime 调用 filterInputsForRolePerspective
• blind_review：review 不可见指定 tag（如 核心.危险.隐藏）

隔离在 取数之后、拼接之前 应用。

---

8. 与 agent tool loop 的边界

两套上下文 不得混用：

	Agent tool loop messages[]	Worker prompt
用途	总管推理、选 skill	具体 skill 执行
内容	tool 结果、read_blackboard	assembleWorkerContext 输出
增长	两次用户操作之间的 burst 内累积	每次 invoke 按契约重建

总管 read_blackboard 不注入 worker prompt；只帮助 agent 决定下一个 run_worker。

---

9. 拼接结果形态（目标）

system:
  {shared-context}
  {worker SKILL body}
  {固定输出协议}

user:
  {按 segment 顺序格式化的 Markdown 或结构化块}

实现：src/skills/context-segments.ts → assembleWorkerContext()；由 src/worker/executor.ts 调用。

---

10. 设计 checklist

□ 列出 static / dynamic 各需要哪些 tag
□ static 写入 contextSegments tier=static
□ dynamic 写入 tier=dynamic 并选 policy
□ inputTags 覆盖 segments 中全部 pattern
□ 画隔离表：谁不可见哪些 tag
□ 若有多游玩模式，在包内预置 contextProfile variant
□ 实例化 manifest 只选 variant，不临场改 tag 列表

---

11. 相关文档

文档	关系
worker-skill-format.md	frontmatter 字段定义
skill-design-guide.md	如何倒推 tag 与 skill 能力
tag-blackboard.md	标签命名与黑板
tool-contracts.md	agent 不得传 inputTags