框架: 对齐SoT纠偏——agent按专题-06§3三层清单标身份(4槽位件+judge保护件),上下文包改专题-03§4四层口径,skill形态定python脚本封装(.venv直连PG实测通)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-09 07:59:07 -07:00 · 2026-07-09 07:59:07 -07:00 · e91bb98590
commit e91bb98590
parent f216e8bff2
6 changed files with 46 additions and 34 deletions
--- a/.claude/skills/read-context/SKILL.md
+++ b/.claude/skills/read-context/SKILL.md
@ -5,22 +5,24 @@ description: 组装智能体上下文包——统一创作数据读取器(专题

 # 组装上下文(统一读取器)

-**输入**:作品名、用途(`planning` / `generation` / `detection` / `extraction`)、目标(如"写第7章")。
+SoT 对齐:包结构=专题-03 §4.2 **四层上下文**;字段级 aiContext 裁剪=专题-06 §7 统一读取器。
+
+**输入**:作品名、用途(scenario:`planning` / `generation` / `detection` / `extraction`)、目标(如"写第7章")。

 ## 步骤

-1. 读 `works/<书>/装配.yaml`:拿槽位绑定与知识绑定。**未绑定的 `knowledge/` 内容一律不读**。
+1. 读 `works/<书>/装配.yaml`:拿槽位绑定与知识绑定。**未绑定的 `knowledge/` 内容一律不读**(=Layer 3 的授权门)。
 2. 读 `meta/schemas/` 相关型的 `aiContext`,得出本用途的可见字段集:`true` 可见;`false` 不可见;`[用途…]` 仅列出的用途可见。
-3. 分区取数并**逐字段裁剪**:
-   - **设定**:`设定.md` 四节(如 `generation` 用途要裁掉「谜底与真相」「结局方向」「弃案记录」等);
-   - **大纲**:`generation` 只取主线一句话+当前卷细纲+近三章细纲;「未来卷粗纲」仅 `planning`;
-   - **状态**:`状态.md` 全文;
-   - **知识卡**:只取本章细纲出场清单涉及的人物/关系卡及其关联地点/势力/功法/物品/事件卡,**不整库倾倒**;卡内字段同样按 aiContext 裁(如「创作备忘」永不进包、「成长弧线」续写不进);
-   - **近邻正文**:上一章末尾 1–2 个场景原文 + 再前一章的 frontmatter 摘要;
-   - **公共范式**:仅装配已绑定者。
-4. 产出**上下文包**:按分区分节拼装;包尾附**裁剪清单**——被 aiContext 挡掉的字段名与原因、因未绑定而跳过的库、因出场无关而未选的卡数。
+3. 按**四层**取数并逐字段裁剪:
+   - **Layer 0 当前输入**(不可省略):任务目标+本章细纲(出自大纲当前章);
+   - **Layer 1 近邻正文**(续写不可省略):上一章末尾 1–2 个场景原文+再前一章 frontmatter 摘要+`状态.md`(伏笔台账/时间线/最新状态);
+   - **Layer 2 作品事实**(只读已确认):`设定.md` 四节(`generation` 裁掉「谜底与真相」「结局方向」「弃案记录」等)、大纲(`generation` 只取主线一句话+当前卷细纲+近三章细纲,「未来卷粗纲」仅 `planning`)、知识卡(只取本章出场清单涉及的卡及其关联卡,**不整库倾倒**;卡内字段同按 aiContext 裁,如「创作备忘」永不进包、「成长弧线」续写不进);
+   - **Layer 3 授权资料**(按场景可省):装配已绑定的公共范式卡。
+4. 产出**上下文包**:按 Layer 0→3 分节拼装;超长先摘要化 L3/L2 再截断,L0 必须完整(预算顺序对齐专题-03 §4.2)。包尾附**裁剪回显**两段:字段级=被 aiContext 挡掉的字段名与原因;来源级=omittedSources(未绑定跳过的库、出场无关未选的卡数,原因对齐 `not_authorized`/`not_relevant`/`token_budget` 枚举)。
 5. 回显落盘:`works/<书>/评审/上下文-第NNN章-<用途>.md`(运行噪音,gitignore 已挡,不提交)。

+PG 版(闭环 C4)只换 L2/L3 取数方式(search skill 召回+授权过滤),层结构与回显合同不变。
+
 ## 红线

 - 不得绕过裁剪把整文件塞给智能体;
--- a/.gitignore
+++ b/.gitignore
@ -1,3 +1,6 @@
 # 评审报告是运行噪音:可看、可复跑,永不入历史
 works/*/评审/
 .DS_Store
+# python 虚拟环境(依赖清单在 requirements.txt,uv 一键重建)
+.venv/
+__pycache__/
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -22,7 +22,7 @@

 ## 生成纪律

- **所有 API/工具能力一律封装为 skill**（`.claude/skills/`）：数据库、嵌入、检索、导入、确认、组装全走 skill，主会话与智能体不得裸调外部服务（PG/New-API）或散写一次性工具脚本。能力清单见 README §四。
+- **所有 API/工具能力一律封装为 skill**（`.claude/skills/`）：数据库、嵌入、检索、导入、确认、组装全走 skill，主会话与智能体不得裸调外部服务（PG/New-API）或散写一次性工具脚本。skill 形态 = SKILL.md + `scripts/*.py` 封装（uv `.venv` + requirements.txt，通用依赖优先）。能力清单见 README §四。
 - 组装上下文只走 `read-context`，按 schema 的 `aiContext` 裁剪；智能体不得自行翻仓库找上下文。
 - 未在 `装配.yaml` 绑定的 `knowledge/` 内容不得进入上下文。
 - 每次生成后向用户报：依据了什么、产出在哪、伏笔动作；等用户裁决。
--- a/README.md
+++ b/README.md
@ -56,33 +56,34 @@ agent-example/
 | embed | New-API 嵌入封装：Qwen3-Embedding-8B、`dimensions:1024`、`--noproxy`、批量+失败重试 | AI 网关（嵌入） | B2 交付 |
 | search | 向量检索：意图→embed→pgvector 相似度召回→授权过滤（仅已确认+已绑定）+字段裁剪→带相似度分的结果集 | 知识检索 | B3 交付 |

-**agent = 动脑的**（LLM 判断力，达标 prompt 即未来 agent_version.config 种子）——共 **5** 个，全 opus，闭环内不新增。
+**skill 形态公约**：每只 skill = `SKILL.md`（何时用+输入输出合同）+ `scripts/*.py`（**封装好的确定性实现**）。Python 3.12 + uv 管理的 `.venv`，依赖清单 `requirements.txt`（psycopg[binary] / requests / pyyaml / click），多用通用依赖不造轮子；PG 经 psycopg 直连（连通事实与凭据见 `db/连接信息.md`），New-API 调用禁系统代理（`trust_env=False`）；脚本失败原样报错不静默。现有三只流程型 skill（read-context/confirm/eval）以流程管控为主，涉库涉外步骤在 PG 版升级时同样下沉进脚本。

-| agent | 做什么 | 用在 |
-|---|---|---|
-| planner | 设定包/大纲/细纲候选；字段全覆盖或标「字段存疑」；设定咬合自查 | C2 |
-| writer | 整章正文候选：2500–3500 字、AI 味黑名单零命中、新设定申报注释块 | C4 |
-| extractor | 两用场：**拆书**（B2，按库内 schema 逐章产知识行草稿+出处链）与**章后抽取**（C5）；与既有知识冲突标「⚠ 冲突待裁决」不覆盖 | B2 / C5 |
-| detector | 一致性/伏笔/设定违背检查，只出报告落 `评审/` | C4 伴随 |
-| judge | 六维 rubric 1–5 打分，引文证据制，≥4.0 达标 | C6 / eval 内 |
+**agent = 动脑的**（LLM 判断力，达标 prompt 即未来 agent_version.config 种子）——共 **5** 个，全 opus，与 [专题-06 §3 智能体三层清单](../design-docs/专题-06-元数据驱动的智能体架构.md) 一一对应、无自造型：**第一层开放槽位件 4 + 第二层保护节点件 1**。

-分工判据：需要 LLM 判断的进 agent；确定性的取数、写库、外部调用、流程管控进 skill。agent 只经 skill 拿上下文与落库。
+| agent | SoT 身份（专题-06 §3 / 专题-03 §2.3） | 做什么 | 用在 |
+|---|---|---|---|
+| writer | 一层 · 写作（Writing 槽位） | 整章正文候选：2500–3500 字、AI 味黑名单零命中、新设定申报注释块；只进待审 | C4 |
+| planner | 一层 · 规划（规划链槽位） | 设定包/大纲/细纲候选；字段全覆盖或标「字段存疑」；未确认不进后续生成上下文 | C2 |
+| extractor | 一层 · 拆书/分析（Analysis 槽位） | 两用场：**拆书**（B2，按库内 schema 产知识行草稿+出处链；系统级只产抽象范式、不留原文）与**章后抽取**（C5）；冲突标「⚠ 冲突待裁决」不覆盖 | B2 / C5 |
+| detector | 一层 · 检测（Detection 槽位） | 一致性/伏笔/设定违背检查，只产解释与定位落 `评审/`，不改正文与知识 | C4 伴随 |
+| judge | **二层 · 保护节点（质量门控与 LLM-Judge）**——不可被装配替换，即 G2 判据的活体 | 六维 rubric 1–5 打分，引文证据制，≥4.0 达标 | C6 / eval 内 |

-### 上下文组装结构（read-context 的产出合同，操作细节以该 skill 为准）
+SoT 第三层「知识基座」（检索/切块/入库，明文不是 app）在实验里即 **skill 层**（db/import/embed/search）——正好印证「所有 API/工具皆 skill」。分工判据：需要 LLM 判断的进 agent；确定性的取数、写库、外部调用、流程管控进 skill。agent 只经 skill 拿上下文与落库。
+
+### 上下文组装结构（SoT=[专题-03 §4 四层上下文](../design-docs/专题-03-AI编排上下文与质量评测实现规范.md) + [专题-06 §7 统一读取器](../design-docs/专题-06-元数据驱动的智能体架构.md)；操作细节以 read-context skill 为准）

 ```
-上下文包(输入:作品+用途+目标;用途∈planning/generation/detection/extraction)
-├── 1 设定区    设定.md 四节,字段级裁剪(如 generation 不给「谜底与真相」「结局方向」)
-├── 2 规划区    主线一句话+当前卷细纲+近三章细纲;「未来卷粗纲」仅 planning 可见
-├── 3 状态区    状态.md 全文(伏笔台账/时间线/角色最新状态)
-├── 4 知识区    仅本章出场清单涉及的卡+其关联卡,不整库倾倒;卡内字段同样按 aiContext 裁
-├── 5 正文近邻  上一章末尾 1–2 场景原文 + 再前一章 frontmatter 摘要
-├── 6 公共范式  仅 装配.yaml 已绑定的库
-└── 尾 裁剪清单  被挡字段+原因 / 未绑定跳过的库 / 出场无关未选卡数 → 回显落 评审/(验收证据)
-(任务指令与输出合同由主会话派发时另附,不属读取器)
+四层上下文(专题-03 §4.2;请求带 scenario 用途与授权语义)
+├── Layer 0 当前输入   任务目标+本章细纲+当前文本 ——不可省略
+├── Layer 1 近邻正文   上一章末尾场景原文+再前一章摘要+近期叙事状态 ——续写不可省略
+├── Layer 2 作品事实   设定四节+正式规划+状态台账+知识卡(仅出场+关联) ——只读已确认(Canonical)
+└── Layer 3 授权资料   绑定的公共范式库/全局知识 ——按场景可省;必须有绑定授权
+预算顺序:先留输出预算 → L0 完整保留 → L1 优先 L2 优先 L3;超限先摘要化低层再截断
+裁剪回显(落 评审/,验收证据):字段级=aiContext 裁剪清单(专题-06 §7)
+  + 来源级=omittedSources(原因枚举:token_budget/not_authorized/stale_source/low_confidence/not_relevant/blocked)
 ```

-三级裁剪对齐专题-06：**字段级**（aiContext）/ **来源级**（装配绑定）/ **用途级**（purpose）。PG 版只改第 4 区取数方式（人工选卡 → search 召回+授权过滤），包结构不变。
+文件版落位：设定/大纲/状态/知识卡→L2，正文近邻→L1，装配绑定的公共范式→L3，派发指令与细纲→L0。三级裁剪=**字段级** aiContext / **来源级** 装配绑定 / **用途级** scenario。PG 版只改 L2/L3 取数方式（search 召回+授权过滤），层结构与回显合同不变。

 ## 五、一次续写怎么走

--- a/db/连接信息.md
+++ b/db/连接信息.md
@ -7,9 +7,9 @@
 - 主机 `100.64.0.8` 端口 `5433` 库名 `muse-example`(本实验专属;**严禁触碰** muse_local / muse_slice_live / *_test)
 - 用户 `root` 密码 `f6710e2d0294eb1c10e26a805a64bc54`
 - 直连串: `postgresql://root:f6710e2d0294eb1c10e26a805a64bc54@100.64.0.8:5433/muse-example`
- 本机无 psql:一律经 SSH 在容器内执行(本机 mini-infra 别名未配,用 IP):
-  `ssh root@100.64.0.8 "docker exec -i <pg容器> psql -U root -d muse-example"`(容器名先 `docker ps | grep -i postgres` 确认,预期 infra-postgres)
- A1(原K0)状态(2026-07-09):库与 vector 插件**尚未创建**(首次尝试因 ssh 别名失败中断);SSH root@100.64.0.8 已验通
+- **首选通道(2026-07-09 实测通)**:本机 Python `psycopg` 直连 `100.64.0.8:5433` 成功(PostgreSQL 17.10);skill 脚本一律走直连,环境 = 仓库 `.venv`(uv + requirements.txt,psycopg[binary]/requests/pyyaml/click 已装并验)
+- 备用通道:本机无 psql,可经 SSH 在容器内执行:`ssh root@100.64.0.8 "docker exec -i <pg容器> psql -U root -d muse-example"`(容器名先 `docker ps | grep -i postgres` 确认,预期 infra-postgres);SSH root@100.64.0.8 已验通(mini-infra 别名本机未配)
+- A1(原K0)状态(2026-07-09):`muse-example` 库与 vector 插件**尚未创建**;直连通道已备好,A1 起跑即建

 ## New-API(嵌入与 LLM 网关)

--- a/requirements.txt
+++ b/requirements.txt
@ -0,0 +1,6 @@
+# skill 脚本层通用依赖(公约见 README §四能力清单)
+# 初始化: uv venv .venv && uv pip install --python .venv/bin/python -r requirements.txt
+psycopg[binary]
+requests
+pyyaml
+click