|
|
@@ -1,121 +1,56 @@
|
|
|
# Webnovel Writer 多宿主与多智能体适配 Spec
|
|
|
|
|
|
-> 日期：2026-06-05
|
|
|
-> 状态：草案 v2
|
|
|
-> 基线：`master` 当前插件形态，`.claude-plugin/plugin.json` 与 marketplace 版本为 `6.1.0`
|
|
|
-> 来源：基于 PR #110 的 review 结论重写，修正过期的 7 Skill / hooks / doctor / runtime 状态描述
|
|
|
-> 定位：把 Webnovel Writer 在不破坏 Claude Code 现有体验的前提下，演进为可验证、可生成、可降级的多宿主写作插件
|
|
|
+> 日期：2026-06-05（v3 修订：2026-06-11；v3.1：同日，hook 语义 deny → ask，依据 #113，见 §5.5）
|
|
|
+> 状态：草案 v3.1
|
|
|
+> 基线：**v7 story repo**（`story-repo-spec-2026-06-10.md` 0.5 冻结稿）。v2 的基线是 v6.1.0 Python runtime，该架构已被 v7 推翻；本版继承 v2 的元层纪律，重写全部基座层。
|
|
|
+> 来源：v2（基于 PR #110 review 重写）+ 2026-06 多平台调研核验 + `story-repo-spec-feedback-2026-06-11.md` §二.3
|
|
|
+> 定位：把 v7 的格式层（story repo）原封不动地暴露给多个 agent 宿主——格式平台无关，本 spec 只管入口怎么落、角色怎么生成、安装怎么零门槛、支持等级怎么诚实。
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 1. 背景
|
|
|
+## 1. 相对 v2 的处置（审计表）
|
|
|
|
|
|
-PR #110 的方向是对的：Webnovel Writer 不应该永远只被 Claude Code 的表达方式绑定。它已经有完整的写作运行时、Story System、RAG、Dashboard、Agent 分工和发布校验，下一步可以考虑多宿主适配。
|
|
|
-
|
|
|
-但 PR #110 的原始 spec 使用了旧基线：
|
|
|
-
|
|
|
-- 只列出 7 个 Skill，漏掉 `/webnovel-doctor`。
|
|
|
-- 把 hooks 描述为“当前未形成 bootstrap”，但当前主干已经有 `hooks/hooks.json`、`session_start.py` 和 `guard_runtime_write.py`。
|
|
|
-- 没有把 `project-status`、`doctor`、`write-gate`、`projections retry/replay`、`.webnovel/projection_log.jsonl` 纳入最终形态。
|
|
|
-- 新增文档放在 `docs/superpowers/specs/`，但当前 `superpowers` 已归档到 `docs/archive/superpowers/`。
|
|
|
-
|
|
|
-因此，本 spec 以当前 `v6.1.0` 运行时为基线重新定义多宿主适配方案。
|
|
|
+| v2 内容 | 处置 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| §5.4 不相信手写矩阵 / `support.md` 纪律 | **继承** | 官方链接 + 核验日期 + smoke 命令，原样保留（§7） |
|
|
|
+| §12.1 adapter registry 分级 | **继承并具体化** | 分级标准定为：一级亲测 / 二级社区反馈 / 三级理论可用（§7.1） |
|
|
|
+| §12.3 生成器 + §13.3 drift check | **继承** | 单源生成多宿主壳，提交物必须过 drift check（§6.3、§9） |
|
|
|
+| §9.3 降级诚实条款 | **继承** | 不允许声称调用了不存在的 subagent（§5.4） |
|
|
|
+| §5.5 UTF-8 First | **继承，换 Node 口径** | 脚本统一 Node，默认 UTF-8；CI 保留 Windows 中文路径全链路（§5.6） |
|
|
|
+| §5.1 "Runtime 是唯一业务真源" | **反转** | 真源是 story repo（markdown + git），脚本只是确定性工具层（§5.1） |
|
|
|
+| §8.3 写章硬要求（write-gate/chapter-commit/projection） | **删除** | 随 v6 架构作废；v7 的跨宿主硬要求只剩一条：事实变更必须经事务 commit（§5.1） |
|
|
|
+| §2 当前基线（8 Skill / 4 Agent / hooks / runtime CLI / doctor / Dashboard） | **删除** | 全部是 v6 形态；v7 是单入口状态机 + Node 脚本 |
|
|
|
+| §11 doctor / project-status 双状态入口 | **删除** | v7 状态入口 = 盘面状态机（story repo spec §10），解析失败走修复卡，不需要平行的 doctor 体系 |
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 2. 当前真实基线
|
|
|
+## 2. 当前真实基线（2026-06 核验）
|
|
|
|
|
|
-### 2.1 Claude Code 插件结构
|
|
|
+### 2.1 SKILL.md 已是开放标准
|
|
|
|
|
|
-当前插件根为 `webnovel-writer/`，符合官方 `plugin-dev` 对 Claude Code 插件结构的要求：
|
|
|
+Anthropic 2025-12 开放 SKILL.md 规范后，Codex、Gemini CLI、Cursor、Copilot、Windsurf 等 30+ 工具支持，发现路径为 `.claude|.codex|.cursor|.gemini/skills/`。**skills 层零适配，拷目录即用**。
|
|
|
|
|
|
-```text
|
|
|
-webnovel-writer/
|
|
|
-├── .claude-plugin/
|
|
|
-│ └── plugin.json
|
|
|
-├── agents/
|
|
|
-│ ├── context-agent.md
|
|
|
-│ ├── data-agent.md
|
|
|
-│ ├── deconstruction-agent.md
|
|
|
-│ └── reviewer.md
|
|
|
-├── skills/
|
|
|
-│ ├── webnovel-init/
|
|
|
-│ ├── webnovel-plan/
|
|
|
-│ ├── webnovel-write/
|
|
|
-│ ├── webnovel-review/
|
|
|
-│ ├── webnovel-query/
|
|
|
-│ ├── webnovel-learn/
|
|
|
-│ ├── webnovel-dashboard/
|
|
|
-│ └── webnovel-doctor/
|
|
|
-├── hooks/
|
|
|
-│ ├── hooks.json
|
|
|
-│ ├── session_start.py
|
|
|
-│ └── guard_runtime_write.py
|
|
|
-├── scripts/
|
|
|
-├── references/
|
|
|
-├── templates/
|
|
|
-├── genres/
|
|
|
-└── dashboard/
|
|
|
-```
|
|
|
+约束：Codex 对 skill 列表有约 8k 字符预算，`description` 必须精简。
|
|
|
|
|
|
-### 2.2 当前 8 个 Skill
|
|
|
+### 2.2 Subagent 三大平台都有，但无标准
|
|
|
|
|
|
-| Skill | 当前职责 | 多宿主适配时的地位 |
|
|
|
+| 平台 | 格式 | 状态 |
|
|
|
|---|---|---|
|
|
|
-| `/webnovel-init` | 初始化新书项目 | 保留为项目创建入口 |
|
|
|
-| `/webnovel-plan` | 规划卷纲、章纲、运行时合同 | 保留为规划入口 |
|
|
|
-| `/webnovel-write` | 写章主链，调用 gate、agent、commit、projection | 多宿主适配的最高优先级主流程 |
|
|
|
-| `/webnovel-review` | 审查章节范围 | 保留为可独立调用的质量入口 |
|
|
|
-| `/webnovel-query` | 只读查询项目状态、设定和记忆 | 保留为跨宿主只读查询入口 |
|
|
|
-| `/webnovel-learn` | 追加项目经验记忆 | 保留为受控写入入口 |
|
|
|
-| `/webnovel-dashboard` | 启动只读 Dashboard | 保留 Claude Code 主路径，其他宿主可降级为 CLI 提示 |
|
|
|
-| `/webnovel-doctor` | 阶段感知体检目录、文件、DB、RAG、依赖 | 必须纳入所有宿主的安装后自检路径 |
|
|
|
-
|
|
|
-### 2.3 当前 4 个 Agent
|
|
|
-
|
|
|
-| 当前文件 | 当前职责 | 目标规范名 |
|
|
|
-|---|---|---|
|
|
|
-| `context-agent.md` | 写前上下文与任务书组装 | `webnovel-context-agent` |
|
|
|
-| `reviewer.md` | 多维审查与 blocking issue 输出 | `webnovel-reviewer` |
|
|
|
-| `data-agent.md` | 提取 commit artifacts，不直接写 projection | `webnovel-data-agent` |
|
|
|
-| `deconstruction-agent.md` | 拆解参考书和结构学习 | `webnovel-deconstruction-agent` |
|
|
|
-
|
|
|
-当前文件名不能直接删除或重命名，因为现有 Skill 文案和用户习惯可能仍引用旧名。目标规范名必须通过兼容迁移引入。
|
|
|
-
|
|
|
-### 2.4 当前 Runtime CLI
|
|
|
+| Claude Code | markdown + frontmatter（`agents/`） | 稳定 |
|
|
|
+| Gemini CLI | markdown + frontmatter（路径不同） | 可用 |
|
|
|
+| Codex | TOML | experimental |
|
|
|
|
|
|
-所有确定性动作已经统一从 `scripts/webnovel.py` 进入。多宿主适配必须复用这些 runtime 命令，不为每个宿主重写一套业务逻辑。
|
|
|
-
|
|
|
-关键命令：
|
|
|
-
|
|
|
-| 命令 | 作用 |
|
|
|
-|---|---|
|
|
|
-| `preflight` | 快速环境与项目根检查 |
|
|
|
-| `project-status` | 机器可读短状态、phase、下一步 |
|
|
|
-| `doctor` | 阶段感知项目体检与修复建议 |
|
|
|
-| `write-gate` | 写前、提交前、提交后三个自然边界校验 |
|
|
|
-| `story-system` | Story System 合同与运行时数据 |
|
|
|
-| `chapter-commit` | 章节事实提交，驱动 projection |
|
|
|
-| `projections retry/replay` | 基于已有 commit 补跑或重放投影 |
|
|
|
-| `status` | 旧宏观创作健康报告，保持原语义 |
|
|
|
+结论：角色定义**单源 markdown，构建时生成三平台壳**；格式三家三样，手维护必漂移。
|
|
|
|
|
|
-### 2.5 当前 Hook
|
|
|
+### 2.3 Hook 只有 Claude Code 完整
|
|
|
|
|
|
-当前已经存在 Claude Code 插件级 hooks：
|
|
|
+核心流程必须显式调脚本；hook 只能是 Claude Code 上的自动兜底，不能承载任何关键能力。
|
|
|
|
|
|
-- `SessionStart`：只运行 `project-status --format summary`，给新会话提供短状态。
|
|
|
-- `PreToolUse`：对直接写 `.story-system/commits/`、`.webnovel/state.json`、`index.db`、`vectors.db`、`memory_scratchpad.json`、`projection_log.jsonl` 等危险路径做兜底阻断。
|
|
|
+### 2.4 弱模型现实
|
|
|
|
|
|
-hook 是轻量守卫，不是业务状态机。
|
|
|
+Codex 跑 GPT、Cursor 什么模型都有。"流程薄 + 脚本确定性"不是优雅偏好，是跨宿主正确性的必需——能数的绝不让模型估（story repo spec 不变量 6 在弱模型下更硬）。
|
|
|
|
|
|
-### 2.6 当前验证能力
|
|
|
-
|
|
|
-当前已有两类基础验证：
|
|
|
-
|
|
|
-- `scripts/validate_plugin_package.py`：按官方 `plugin-dev` 思路检查 manifest、Skill / Agent frontmatter、hooks wrapper、README 版本、路径可移植性。
|
|
|
-- `scripts/run_behavior_evals.py` + `evals/fixtures/behavior/fast.json`：检查 8 个 Skill 的关键行为契约、Agent 边界、commit/projection、Dashboard 只读语义。
|
|
|
-
|
|
|
-多宿主适配必须扩展这两类验证，而不是新造一套互不相干的检查。
|
|
|
+以上每条在实现对应宿主前必须按 §7.2 重新核验，本节不是免检通行证。
|
|
|
|
|
|
---
|
|
|
|
|
|
@@ -123,686 +58,210 @@ hook 是轻量守卫，不是业务状态机。
|
|
|
|
|
|
### 3.1 一句话目标
|
|
|
|
|
|
-把 Webnovel Writer 从“Claude Code 单宿主插件”升级为：
|
|
|
-
|
|
|
-> 以现有 Python runtime 和 Story System 为唯一业务核心，向多个宿主生成轻量 adapter 的长篇写作插件。
|
|
|
+> 以 story repo（markdown + git）为唯一真源，向多个宿主分发同一套 SKILL.md 入口、生成各平台角色壳、用 npx 一键安装的长篇写作系统。
|
|
|
|
|
|
### 3.2 具体目标
|
|
|
|
|
|
-1. 保留 Claude Code 现有安装、Skill、Agent、hook 和 CLI 体验。
|
|
|
-2. 让 Codex、Cursor、Gemini CLI、OpenCode、GitHub Copilot CLI 等宿主可以通过 adapter 消费同一套写作能力。
|
|
|
-3. 所有宿主都复用 `scripts/webnovel.py` 和 `data_modules`，不复制 Story System、commit、projection、doctor、gate 逻辑。
|
|
|
-4. 每个宿主的支持状态必须可验证，有 manifest 校验、smoke 测试和行为 eval。
|
|
|
-5. 当宿主不支持 subagent 或 hook 时，有明确降级模式，不假装已经调用了不存在的能力。
|
|
|
-6. 所有新增插件组件继续符合官方 `plugin-dev` 的结构、frontmatter、hooks、路径和验证要求。
|
|
|
-
|
|
|
----
|
|
|
+1. 状态机单入口落成标准 SKILL.md，在所有支持 SKILL.md 的宿主上可发现、可执行。
|
|
|
+2. 角色（三镜头评审等）单源定义，构建时生成 Claude / Gemini / Codex 三平台壳。
|
|
|
+3. 所有宿主复用同一套 Node 脚本（机检、settle、盘面、体检），零业务逻辑复制。
|
|
|
+4. `npx` 安装器一条命令完成环境检测与 skills 分发（根治 v6 #90/#103/#69 安装类 issue）。
|
|
|
+5. 每个宿主的支持状态可验证：support.md + smoke + 分级 registry，不承诺未核验的能力。
|
|
|
+6. 宿主不支持 subagent / hook 时有明确降级模式，输出如实声明。
|
|
|
|
|
|
## 4. 非目标
|
|
|
|
|
|
-本 spec 不做这些事：
|
|
|
-
|
|
|
-- 不重写 Story System 主链。
|
|
|
-- 不拆掉现有 8 个 Skill。
|
|
|
-- 不改变 `webnovel.py status` 的旧健康报告语义。
|
|
|
-- 不把 `doctor`、`project-status`、`write-gate`、`projection_log` 重新设计成另一套平行系统。
|
|
|
-- 不把 hooks 变成隐藏业务流程。
|
|
|
-- 不自动启动 Docker、Dashboard、RAG 服务或外部依赖。
|
|
|
-- 不把 `docs/superpowers/` 重新作为活跃文档区；活跃架构 spec 进入 `docs/architecture/`。
|
|
|
-- 不承诺未经官方文档和本地验证的外部宿主能力。
|
|
|
+- 不为任何宿主复制或改写章事务八阶段逻辑。
|
|
|
+- 不把格式层（story repo spec）的任何内容绑定到宿主能力上。
|
|
|
+- 不维护手写的"宿主能力矩阵"。
|
|
|
+- 不承诺未经官方文档核验和本地 smoke 的宿主支持。
|
|
|
+- 不做常驻服务、不自动安装依赖（npx 安装器只拷文件 + 报告，不装运行时）。
|
|
|
+- 不把 hook 变成隐藏业务流程。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 设计原则
|
|
|
|
|
|
-### 5.1 Runtime 是唯一业务真源
|
|
|
+### 5.1 Story repo 是唯一真源（反转 v2 §5.1）
|
|
|
|
|
|
-Skill、Agent、hook、adapter 都只是入口或调度层。真正能修改项目事实的动作必须进入 runtime：
|
|
|
+Skill、agent、hook、安装器全部只是入口或调度层。真正修改项目事实的路径只有一条：
|
|
|
|
|
|
```text
|
|
|
-Skill / host command
|
|
|
- ↓
|
|
|
-webnovel.py
|
|
|
+任意宿主入口（SKILL.md / 命令 / 对话）
|
|
|
↓
|
|
|
-data_modules
|
|
|
+盘面状态机（story repo spec §10）
|
|
|
↓
|
|
|
-.story-system commit
|
|
|
+章事务八阶段（story repo spec §8）
|
|
|
↓
|
|
|
-projection read-models
|
|
|
+settle / retcon / fix 原子 commit → story repo
|
|
|
```
|
|
|
|
|
|
-任何宿主 adapter 都不能直接写 `.story-system/commits/` 或 `.webnovel/*` read-model。
|
|
|
-
|
|
|
-### 5.2 Claude Code 是第一支持宿主
|
|
|
-
|
|
|
-Claude Code 当前体验必须保持稳定：
|
|
|
-
|
|
|
-- `.claude-plugin/plugin.json` 保持官方位置。
|
|
|
-- `skills/`、`agents/`、`hooks/` 保持插件根层级。
|
|
|
-- Claude hooks 继续使用 `${CLAUDE_PLUGIN_ROOT}`，符合官方 `plugin-dev`。
|
|
|
-- `/webnovel-*` Skill 名称继续有效。
|
|
|
-
|
|
|
-### 5.3 Adapter 尽量薄
|
|
|
+**跨宿主唯一硬要求**：事实变更必须经事务 commit 入 git，任何宿主不得绕过 settle 直写 `定稿/` 与 `大纲/承诺/`。v2 §8.3 的 write-gate/chapter-commit/projection 硬要求随 v6 架构作废，不替换、不变形保留。
|
|
|
|
|
|
-各宿主 adapter 只负责：
|
|
|
+### 5.2 Claude Code 是第一宿主
|
|
|
|
|
|
-- manifest / metadata
|
|
|
-- tool name mapping
|
|
|
-- agent frontmatter 转换
|
|
|
-- command 暴露方式
|
|
|
-- hook 能力降级
|
|
|
-- smoke/eval 启动方式
|
|
|
+`.claude-plugin/plugin.json`、`skills/`、`agents/`、`hooks/` 保持官方 plugin-dev 结构；Claude Code 的安装与使用体验是其他宿主的对照基准。
|
|
|
|
|
|
-adapter 不负责：
|
|
|
+### 5.3 Skills 层零适配，靠精简而不是靠转换
|
|
|
|
|
|
-- 改写写作流程
|
|
|
-- 解释 Story System
|
|
|
-- 校验 chapter artifacts
|
|
|
-- 执行 projection
|
|
|
-- 自己维护项目状态
|
|
|
+- SKILL.md 是开放标准，分发 = 拷目录，不做格式转换。
|
|
|
+- `description` 按 Codex 8k 预算写：触发条件 + 一句话职责，不塞流程。
|
|
|
+- Skill 主体只写状态机入口和阶段流程，题材知识、宿主差异、工具映射下沉 `references/`。
|
|
|
|
|
|
-### 5.4 不相信手写矩阵
|
|
|
+### 5.4 Subagent 只做增强，不做依赖
|
|
|
|
|
|
-外部宿主能力变化很快。spec 不把“某宿主现在支持什么”写成不可验证的口头事实。
|
|
|
+- 三镜头评审（story repo spec §8 第 6 步）在支持 subagent 的宿主上用独立 subagent 保证"各自新鲜上下文"。
|
|
|
+- 不支持的宿主降级：主 agent 按同一份镜头任务书顺序执行三镜头，输出必须明确声明"未调用 subagent，使用兼容模式"。
|
|
|
+- **降级诚实条款（继承 v2）**：不允许声称调用了不存在的能力；机检与 settle 是脚本，不参与降级。
|
|
|
|
|
|
-每个宿主 adapter 必须有自己的 `support.md` 或等价记录，包含：
|
|
|
+### 5.5 Hook 只是 Claude Code 上的自动兜底
|
|
|
|
|
|
-- 官方文档链接
|
|
|
-- 核验日期
|
|
|
-- 支持的 manifest 字段
|
|
|
-- 支持的 skill / command / agent / hook / MCP 能力
|
|
|
-- 不支持能力的降级规则
|
|
|
-- 本仓库对应的 smoke 测试命令
|
|
|
+- SessionStart 自动报盘面、PreToolUse 提醒直写 `定稿/`——都只是把显式脚本调用自动化。
|
|
|
+- **Hook 语义是 ask，不是 deny**：PreToolUse 检测到直写 `定稿/` 或 `大纲/承诺/` 时提醒"这是定稿区，确认直写还是走事务？"，确认后放行；事后由手改检测（story repo spec §9）提议 fix 结转兜底。deny 式 hook 无法区分"绕过 settle 破坏一致性"和"替作者批量修数据"，被拦的往往是后者——v6 的 state.json guard 即此教训（#113，已于 73447d7 放开）。这与 story repo spec 不变量 1（"检测手改并提议结转，永不报错拒绝"）和"可靠性来自自愈，不来自门禁"原则自洽。
|
|
|
+- 任何关键能力不得只存在于 hook 中；无 hook 宿主由状态机入口（每次启动先跑盘面与手改检测）补足，行为等价。
|
|
|
|
|
|
-### 5.5 UTF-8 First
|
|
|
+### 5.6 零依赖与 UTF-8 First（Node 口径）
|
|
|
|
|
|
-所有新增脚本和 adapter 生成器必须显式 UTF-8：
|
|
|
+- 脚本统一 Node：装任何 agent CLI 的用户必有 Node；无 Python、无 pip、无 .env。
|
|
|
+- 一切文件 IO 显式 UTF-8 无 BOM，`.gitattributes` 锁 LF；不用 .bat/.sh。
|
|
|
+- CI 保留 Windows 中文路径全链路测试（建库→写章→结转→重建缓存，story repo spec §2.1）。
|
|
|
|
|
|
-- Python 文件头保留 UTF-8。
|
|
|
-- 文本读写使用 `encoding="utf-8"`。
|
|
|
-- Windows 子进程优先使用 `python -X utf8`。
|
|
|
-- 不依赖系统默认 GBK 编码。
|
|
|
+### 5.7 不相信手写矩阵（继承 v2 §5.4）
|
|
|
|
|
|
-### 5.6 渐进迁移
|
|
|
-
|
|
|
-多宿主适配必须逐步引入：
|
|
|
-
|
|
|
-1. 先锁定现状和验证。
|
|
|
-2. 再补 adapter 目录与生成器。
|
|
|
-3. 再迁移 Agent 规范名和 Skill 文案。
|
|
|
-4. 最后接入跨宿主 smoke/eval。
|
|
|
-
|
|
|
-不能一次性重命名 Agent 或大改 Skill，避免破坏 Claude Code 现有用户。
|
|
|
+宿主能力变化快，spec 不记"某宿主现在支持什么"的口头事实；一切支持声明由 `support.md` + smoke 支撑（§7）。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 目标架构
|
|
|
|
|
|
-### 6.1 目标结构
|
|
|
-
|
|
|
-最终结构建议如下：
|
|
|
+### 6.1 仓库结构（宿主适配相关部分）
|
|
|
|
|
|
```text
|
|
|
webnovel-writer/
|
|
|
-├── .claude-plugin/
|
|
|
-│ └── plugin.json
|
|
|
-├── skills/
|
|
|
-│ ├── webnovel-init/
|
|
|
-│ ├── webnovel-plan/
|
|
|
-│ ├── webnovel-write/
|
|
|
-│ ├── webnovel-review/
|
|
|
-│ ├── webnovel-query/
|
|
|
-│ ├── webnovel-learn/
|
|
|
-│ ├── webnovel-dashboard/
|
|
|
-│ ├── webnovel-doctor/
|
|
|
-│ └── using-webnovel-writer/ # 可选，跨宿主使用说明与工具映射
|
|
|
-├── agents/
|
|
|
-│ ├── context-agent.md # 旧名兼容
|
|
|
-│ ├── reviewer.md # 旧名兼容
|
|
|
-│ ├── data-agent.md # 旧名兼容
|
|
|
-│ ├── deconstruction-agent.md # 旧名兼容
|
|
|
-│ └── aliases.json # 可选，声明旧名到规范名的映射
|
|
|
-├── hooks/
|
|
|
-│ ├── hooks.json # Claude Code 源 hook
|
|
|
-│ ├── session_start.py
|
|
|
-│ └── guard_runtime_write.py
|
|
|
+├── .claude-plugin/plugin.json # Claude Code 第一宿主 manifest
|
|
|
+├── skills/ # 单源 SKILL.md，开放标准，拷贝即分发
|
|
|
+│ └── <v7 实现阶段定名>/ # 状态机单入口 + /migrate；清单由 v7 实现定，本 spec 只定承载方式
|
|
|
+├── roles/ # 角色单源定义（markdown + frontmatter）
|
|
|
+│ ├── 读者镜头.md
|
|
|
+│ ├── 编辑镜头.md
|
|
|
+│ └── 事实镜头.md
|
|
|
+├── agents/ # 生成物：Claude Code 壳（提交，过 drift check）
|
|
|
├── adapters/
|
|
|
-│ ├── README.md
|
|
|
-│ ├── registry.json # 宿主 adapter 注册表
|
|
|
-│ ├── claude/
|
|
|
-│ ├── codex/
|
|
|
-│ ├── cursor/
|
|
|
-│ ├── gemini/
|
|
|
-│ ├── opencode/
|
|
|
-│ └── copilot/
|
|
|
-├── scripts/
|
|
|
-│ ├── webnovel.py
|
|
|
-│ ├── validate_plugin_package.py
|
|
|
-│ ├── run_behavior_evals.py
|
|
|
-│ └── generate_host_artifacts.py # 新增，生成非 Claude adapter 产物
|
|
|
-├── evals/
|
|
|
-│ └── fixtures/
|
|
|
-├── references/
|
|
|
-├── templates/
|
|
|
-├── genres/
|
|
|
-└── dashboard/
|
|
|
+│ ├── registry.json # 宿主注册表 + 支持分级（§7.1）
|
|
|
+│ └── <host>/support.md # 每宿主核验记录（§7.2）
|
|
|
+├── scripts/ # Node，确定性工具层：机检/settle/盘面/体检/生成器
|
|
|
+│ └── build-host-shells.mjs # roles/ + skills/ → 各平台产物；--check 即 drift check
|
|
|
+├── installer/ # npx 安装器源码（§8）
|
|
|
+└── dist/<host>/ # 非 Claude 生成包，不提交
|
|
|
```
|
|
|
|
|
|
-说明：
|
|
|
+### 6.2 真源与生成物
|
|
|
|
|
|
-- `adapters/` 是 adapter 源码和模板，不是生成产物。
|
|
|
-- `dist/` 用于生成后的宿主包，默认不提交。
|
|
|
-- 只有小型、稳定、必须被宿主直接发现的 manifest 可以提交；提交前必须通过 drift check。
|
|
|
-
|
|
|
-### 6.2 业务源与生成产物
|
|
|
-
|
|
|
-| 类型 | 路径 | 是否事实源 | 是否提交 |
|
|
|
+| 类型 | 路径 | 真源 | 提交 |
|
|
|
|---|---|---:|---:|
|
|
|
-| Claude 插件 manifest | `.claude-plugin/plugin.json` | 是 | 是 |
|
|
|
-| Skill 源文件 | `skills/*/SKILL.md` | 是 | 是 |
|
|
|
-| Agent 源文件 | `agents/*.md` | 是 | 是 |
|
|
|
-| Claude hook 源文件 | `hooks/hooks.json`、`hooks/*.py` | 是 | 是 |
|
|
|
-| Runtime | `scripts/`、`data_modules/` | 是 | 是 |
|
|
|
-| Adapter 模板 | `adapters/<host>/` | 是 | 是 |
|
|
|
-| 生成器 | `scripts/generate_host_artifacts.py` | 是 | 是 |
|
|
|
-| 非 Claude 生成包 | `dist/<host>/webnovel-writer/` | 否 | 否 |
|
|
|
-| 小型宿主 manifest 快照 | `.codex-plugin/plugin.json` 等 | 视宿主而定 | 需 drift check |
|
|
|
+| Skill 源 | `skills/*/SKILL.md` | 是 | 是 |
|
|
|
+| 角色源 | `roles/*.md` | 是 | 是 |
|
|
|
+| Node 脚本与生成器 | `scripts/` | 是 | 是 |
|
|
|
+| 宿主注册表与核验记录 | `adapters/` | 是 | 是 |
|
|
|
+| Claude Code 壳 | `agents/`、`hooks/` | 否（生成物） | 是，过 drift check |
|
|
|
+| 其他宿主壳 | `dist/<host>/` | 否 | 否 |
|
|
|
|
|
|
----
|
|
|
-
|
|
|
-## 7. 环境变量与路径策略
|
|
|
-
|
|
|
-### 7.1 Claude Code 路径保持不变
|
|
|
-
|
|
|
-在 Claude Code 插件组件里继续使用：
|
|
|
-
|
|
|
-```text
|
|
|
-${CLAUDE_PLUGIN_ROOT}
|
|
|
-```
|
|
|
-
|
|
|
-这是官方 `plugin-dev` 推荐方式，不能为了跨宿主把 Claude hook 或 Claude Skill 里的路径粗暴替换掉。
|
|
|
-
|
|
|
-### 7.2 Runtime 可增加兼容解析
|
|
|
-
|
|
|
-Python runtime 可以支持更通用的插件根解析顺序：
|
|
|
-
|
|
|
-1. 显式 CLI 参数。
|
|
|
-2. `WEBNOVEL_PLUGIN_ROOT`。
|
|
|
-3. `CLAUDE_PLUGIN_ROOT`。
|
|
|
-4. 当前脚本路径向上推导。
|
|
|
-
|
|
|
-但这属于 runtime 兼容层，不代表 Claude 插件文档主变量要改名。
|
|
|
-
|
|
|
-### 7.3 Skill 文案中的路径写法
|
|
|
-
|
|
|
-Claude Code Skill 里的可执行示例继续用：
|
|
|
+### 6.3 生成器
|
|
|
|
|
|
```bash
|
|
|
-python -X utf8 "${CLAUDE_PLUGIN_ROOT}/scripts/webnovel.py" ...
|
|
|
-```
|
|
|
-
|
|
|
-跨宿主说明放到 `using-webnovel-writer` 或 `skills/*/references/host-tools.md`，不要把所有宿主变量塞进每个 Skill 主体。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 8. Skill 适配规范
|
|
|
-
|
|
|
-### 8.1 保留当前 8 个业务 Skill
|
|
|
-
|
|
|
-多宿主适配不能删减当前 8 个 Skill，也不能让 `/webnovel-doctor` 成为 Claude-only 的遗漏项。
|
|
|
-
|
|
|
-每个 Skill 必须满足：
|
|
|
-
|
|
|
-- `SKILL.md` 有 `name` 和具体触发型 `description`。
|
|
|
-- 主体只写流程、边界和必要命令。
|
|
|
-- 详细工具映射、宿主差异、参考规则放进 `references/`。
|
|
|
-- 确定性校验交给 runtime 命令，不靠自然语言提醒。
|
|
|
-
|
|
|
-### 8.2 新增可选总入口 Skill
|
|
|
-
|
|
|
-可以新增：
|
|
|
-
|
|
|
-```text
|
|
|
-skills/using-webnovel-writer/SKILL.md
|
|
|
-```
|
|
|
-
|
|
|
-用途：
|
|
|
-
|
|
|
-- 给非 Claude 宿主提供统一使用说明。
|
|
|
-- 解释当前宿主下的工具名映射。
|
|
|
-- 引导先运行 `project-status`，必要时运行 `doctor`。
|
|
|
-- 说明不支持 subagent/hook 的降级模式。
|
|
|
-
|
|
|
-限制：
|
|
|
-
|
|
|
-- 不替代 8 个业务 Skill。
|
|
|
-- 不复制每个 Skill 的完整流程。
|
|
|
-- 不承载题材知识和 Story System schema。
|
|
|
-
|
|
|
-### 8.3 写章 Skill 的硬要求
|
|
|
-
|
|
|
-`webnovel-write` 是多宿主适配的核心验收对象。任何宿主的写章流程都必须保留：
|
|
|
-
|
|
|
-1. 写前调用 `write-gate --stage prewrite`。
|
|
|
-2. 提交前调用 `write-gate --stage precommit`。
|
|
|
-3. 提交事实只能走 `chapter-commit`。
|
|
|
-4. 提交后调用 `write-gate --stage postcommit`。
|
|
|
-5. projection 失败时提示 `projections retry --chapter N`。
|
|
|
-6. 不能直接手写 read-model。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 9. Agent 适配规范
|
|
|
-
|
|
|
-### 9.1 规范名与旧名兼容
|
|
|
-
|
|
|
-目标规范名使用 `webnovel-` 前缀：
|
|
|
-
|
|
|
-| 旧名 | 规范名 |
|
|
|
-|---|---|
|
|
|
-| `context-agent` | `webnovel-context-agent` |
|
|
|
-| `reviewer` | `webnovel-reviewer` |
|
|
|
-| `data-agent` | `webnovel-data-agent` |
|
|
|
-| `deconstruction-agent` | `webnovel-deconstruction-agent` |
|
|
|
-
|
|
|
-迁移方式：
|
|
|
-
|
|
|
-1. 先在文档和 adapter registry 中声明映射。
|
|
|
-2. 再让生成器为不同宿主输出规范名。
|
|
|
-3. 最后逐步修改 Skill 正文使用规范名。
|
|
|
-4. 旧名至少保留一个小版本周期，避免破坏现有调用。
|
|
|
-
|
|
|
-### 9.2 Agent 边界
|
|
|
-
|
|
|
-所有宿主都必须遵守现有边界：
|
|
|
-
|
|
|
-- `context-agent` 只负责写前上下文和任务书。
|
|
|
-- `reviewer` 只负责审查和 blocking 输出。
|
|
|
-- `data-agent` 只产出 commit artifacts，不直接写 projection。
|
|
|
-- `deconstruction-agent` 只负责参考拆解和经验沉淀。
|
|
|
-
|
|
|
-### 9.3 无 subagent 宿主的降级模式
|
|
|
-
|
|
|
-如果宿主不能稳定调用 subagent：
|
|
|
-
|
|
|
-- 进入 compatibility mode。
|
|
|
-- 主 agent 按同一份任务书和 artifact schema 执行。
|
|
|
-- 输出必须明确说明“未调用 subagent，使用兼容模式”。
|
|
|
-- 仍然必须通过 `artifact_validator`、`write-gate` 和行为 eval。
|
|
|
-- 不允许声称已经调用了不存在的 subagent。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 10. Hook 适配规范
|
|
|
-
|
|
|
-### 10.1 Claude Code hook 保持现状
|
|
|
-
|
|
|
-当前 Claude Code hook 是有效基线：
|
|
|
-
|
|
|
-```text
|
|
|
-hooks/hooks.json
|
|
|
-hooks/session_start.py
|
|
|
-hooks/guard_runtime_write.py
|
|
|
+node scripts/build-host-shells.mjs --target all
|
|
|
+node scripts/build-host-shells.mjs --target codex
|
|
|
+node scripts/build-host-shells.mjs --check # drift check，CI 必跑
|
|
|
```
|
|
|
|
|
|
-必须继续满足官方 `plugin-dev`：
|
|
|
-
|
|
|
-- `hooks/hooks.json` 使用 wrapper 格式：外层包含 `description` 与 `hooks`。
|
|
|
-- command hook 使用 `${CLAUDE_PLUGIN_ROOT}`。
|
|
|
-- hook 脚本只做轻量、确定性、可快速退出的检查。
|
|
|
-
|
|
|
-### 10.2 其他宿主 hook 可选
|
|
|
-
|
|
|
-其他宿主是否支持 hook，由对应 adapter 的 `support.md` 和 smoke test 决定。
|
|
|
-
|
|
|
-若宿主不支持 hook：
|
|
|
-
|
|
|
-- 不影响核心写作流程。
|
|
|
-- 通过 `project-status` / `doctor` / `write-gate` 显式命令补足。
|
|
|
-- 不能让某个关键能力只存在于 hook 中。
|
|
|
-
|
|
|
-### 10.3 hook 禁止做的事
|
|
|
-
|
|
|
-hook 不允许：
|
|
|
-
|
|
|
-- 自动写 commit。
|
|
|
-- 自动改正文。
|
|
|
-- 自动改设定。
|
|
|
-- 自动安装依赖。
|
|
|
-- 自动启动长驻服务。
|
|
|
-- 写入章节流程状态。
|
|
|
+生成器只读 `roles/`、`skills/`、`adapters/registry.json`，产出各平台 agent 壳与 manifest；不改业务源、不联网、不运行写作流程。
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 11. Doctor 与状态入口
|
|
|
-
|
|
|
-### 11.1 所有宿主共享同一状态入口
|
|
|
+## 7. 支持分级与核验纪律
|
|
|
|
|
|
-多宿主适配必须统一使用：
|
|
|
-
|
|
|
-```bash
|
|
|
-python -X utf8 "<PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" project-status --format summary
|
|
|
-```
|
|
|
-
|
|
|
-当短状态显示异常时，再运行：
|
|
|
-
|
|
|
-```bash
|
|
|
-python -X utf8 "<PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" doctor --format text
|
|
|
-```
|
|
|
-
|
|
|
-### 11.2 不新增第二套 status
|
|
|
-
|
|
|
-`status` 继续保留宏观创作健康报告语义。
|
|
|
-
|
|
|
-短状态只用 `project-status`。
|
|
|
-
|
|
|
-深度体检只用 `doctor`。
|
|
|
-
|
|
|
-### 11.3 doctor 的跨宿主价值
|
|
|
-
|
|
|
-`doctor` 是多宿主适配的安装后第一检查入口，必须能回答：
|
|
|
-
|
|
|
-- 项目根是否解析正确。
|
|
|
-- 当前 phase 是什么。
|
|
|
-- 当前 phase 应该有哪些文件。
|
|
|
-- 目录、JSON、SQLite 是否完整。
|
|
|
-- RAG 配置是否存在。
|
|
|
-- Python 依赖是否安装。
|
|
|
-- Dashboard 产物是否存在。
|
|
|
-- projection 是否失败。
|
|
|
-- 缺失项怎么修。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 12. Adapter 设计
|
|
|
-
|
|
|
-### 12.1 Adapter registry
|
|
|
-
|
|
|
-新增：
|
|
|
-
|
|
|
-```text
|
|
|
-adapters/registry.json
|
|
|
-```
|
|
|
-
|
|
|
-建议结构：
|
|
|
+### 7.1 Registry 分级
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
- "schema_version": "webnovel-host-adapter-registry/v1",
|
|
|
+ "schema_version": "webnovel-host-registry/v2",
|
|
|
"hosts": {
|
|
|
- "claude": {
|
|
|
- "tier": "primary",
|
|
|
- "source": ".claude-plugin/plugin.json",
|
|
|
- "supports": ["skills", "agents", "hooks"],
|
|
|
- "smoke": "python -X utf8 scripts/validate_plugin_package.py --format json"
|
|
|
- },
|
|
|
- "codex": {
|
|
|
- "tier": "adapter",
|
|
|
- "source": "adapters/codex/",
|
|
|
- "supports": [],
|
|
|
- "smoke": ""
|
|
|
- }
|
|
|
+ "claude-code": { "tier": 1, "verified": "亲测", "smoke": "node scripts/smoke.mjs --host claude-code" },
|
|
|
+ "codex": { "tier": 1, "verified": "亲测", "smoke": "node scripts/smoke.mjs --host codex" },
|
|
|
+ "gemini-cli": { "tier": 2, "verified": "社区反馈" },
|
|
|
+ "cursor": { "tier": 2, "verified": "社区反馈" },
|
|
|
+ "_default": { "tier": 3, "verified": "标准 SKILL.md 理论可用" }
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-`supports` 不能手写猜测，必须由该宿主 `support.md` 和 smoke test 支撑。
|
|
|
-
|
|
|
-### 12.2 每个宿主目录
|
|
|
-
|
|
|
-每个宿主 adapter 至少包含：
|
|
|
-
|
|
|
-```text
|
|
|
-adapters/<host>/
|
|
|
-├── support.md # 官方文档核验记录
|
|
|
-├── manifest.template.* # 需要时才有
|
|
|
-├── tool-mapping.md # 工具名与降级规则
|
|
|
-├── agent-mapping.json # 规范 agent 名与宿主表达
|
|
|
-└── smoke.md # 本地验证命令
|
|
|
-```
|
|
|
-
|
|
|
-### 12.3 生成器
|
|
|
-
|
|
|
-新增生成器：
|
|
|
+- **一级**（Claude Code + Codex）：维护者亲测，发布前必须过 smoke。
|
|
|
+- **二级**（Gemini CLI / Cursor）：社区反馈确认，README 如实标注。
|
|
|
+- **三级**：凡支持标准 SKILL.md 的宿主理论可用，不单独承诺。
|
|
|
|
|
|
-```bash
|
|
|
-python -X utf8 scripts/generate_host_artifacts.py --target all
|
|
|
-python -X utf8 scripts/generate_host_artifacts.py --target codex
|
|
|
-python -X utf8 scripts/generate_host_artifacts.py --check
|
|
|
-```
|
|
|
+`supports` 类字段不允许手写猜测，必须由对应 `support.md` 支撑。
|
|
|
|
|
|
-生成器负责：
|
|
|
+### 7.2 support.md（继承 v2，逐宿主必备）
|
|
|
|
|
|
-- 读取 adapter registry。
|
|
|
-- 读取 Skill / Agent / hook 源文件。
|
|
|
-- 生成宿主 manifest。
|
|
|
-- 生成宿主 agent 配置。
|
|
|
-- 生成宿主 command / skill 入口。
|
|
|
-- 生成 drift manifest。
|
|
|
-
|
|
|
-生成器不负责：
|
|
|
-
|
|
|
-- 修改业务源文件。
|
|
|
-- 联网下载依赖。
|
|
|
-- 改写 Story System schema。
|
|
|
-- 运行写作流程。
|
|
|
+实现某宿主适配前必须重新核验官方文档，结果写入 `adapters/<host>/support.md`，至少包含：官方文档链接、核验日期、skill/subagent/hook 支持情况、本仓库降级策略、smoke 命令。无 support.md 的宿主不得进入 registry 一二级。
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 13. 验证与 CI
|
|
|
-
|
|
|
-### 13.1 Package validator 扩展
|
|
|
+## 8. 安装与分发
|
|
|
|
|
|
-当前 `validate_plugin_package.py` 继续作为基础。后续扩展检查：
|
|
|
+`npx` 安装器（解决 v6 #90/#103/#69）：
|
|
|
|
|
|
-- `adapters/registry.json` schema。
|
|
|
-- 每个 adapter 是否有 `support.md`。
|
|
|
-- 每个 adapter 是否声明 smoke 命令。
|
|
|
-- 生成产物是否含本机绝对路径。
|
|
|
-- 小型提交 manifest 是否与生成器输出一致。
|
|
|
-- `docs/README.md` 是否索引活跃 spec。
|
|
|
+1. 检测环境：识别已安装的 agent CLI（按 registry 顺序探测 `.claude|.codex|.cursor|.gemini` 等目录与命令）。
|
|
|
+2. 拷贝 skills 到对应宿主的 skills 路径；一级宿主同时生成 agent 壳。
|
|
|
+3. 输出报告：装到了哪、该宿主支持等级、降级说明、下一步（打开 agent CLI 说"开始写书"）。
|
|
|
|
|
|
-### 13.2 Behavior eval 扩展
|
|
|
-
|
|
|
-当前 fast eval 已覆盖 8 个 Skill。后续增加：
|
|
|
-
|
|
|
-- 每个宿主至少一个 install / discover smoke。
|
|
|
-- 每个宿主至少一个 `project-status` smoke。
|
|
|
-- `webnovel-doctor` 在每个宿主都有可执行说明。
|
|
|
-- `webnovel-write` 在至少一个非 Claude 宿主完成兼容模式验收。
|
|
|
-- 无 subagent 宿主不得声称调用 subagent。
|
|
|
-
|
|
|
-### 13.3 Drift check
|
|
|
-
|
|
|
-如果提交了任何生成 manifest 或 generated adapter 文件，CI 必须运行：
|
|
|
-
|
|
|
-```bash
|
|
|
-python -X utf8 scripts/generate_host_artifacts.py --check
|
|
|
-```
|
|
|
-
|
|
|
-失败时说明：
|
|
|
-
|
|
|
-- 哪个源文件变化导致 drift。
|
|
|
-- 应该重新运行哪个生成命令。
|
|
|
-- 哪些生成文件需要提交。
|
|
|
-
|
|
|
-### 13.4 外部能力核验
|
|
|
-
|
|
|
-每次实现某个宿主 adapter 前，必须重新核验官方文档。
|
|
|
-
|
|
|
-核验结果写入：
|
|
|
-
|
|
|
-```text
|
|
|
-adapters/<host>/support.md
|
|
|
-```
|
|
|
-
|
|
|
-`support.md` 至少包含：
|
|
|
-
|
|
|
-- 核验日期。
|
|
|
-- 官方链接。
|
|
|
-- 支持能力。
|
|
|
-- 不支持能力。
|
|
|
-- 本仓库采用的降级策略。
|
|
|
+安装器不装 Node 之外的任何运行时、不改用户全局配置、不联网下载业务逻辑。
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 14. 迁移计划
|
|
|
-
|
|
|
-### Phase 0：锁定现状
|
|
|
+## 9. 验证与 CI
|
|
|
|
|
|
-目标：让 spec 和当前主干一致。
|
|
|
-
|
|
|
-改动：
|
|
|
-
|
|
|
-- 新增本 spec 到 `docs/architecture/`。
|
|
|
-- 更新 `docs/README.md` 索引。
|
|
|
-- 不新增 `docs/superpowers/` 活跃目录。
|
|
|
-
|
|
|
-验收：
|
|
|
-
|
|
|
-- 文档列出 8 个 Skill。
|
|
|
-- 文档列出当前 hooks。
|
|
|
-- 文档列出 doctor、project-status、write-gate、projections、projection_log。
|
|
|
-- `git diff --check` 通过。
|
|
|
-
|
|
|
-### Phase 1：Adapter 研究记录与注册表
|
|
|
-
|
|
|
-目标：先验证外部宿主能力，不写大规模生成器。
|
|
|
-
|
|
|
-改动：
|
|
|
-
|
|
|
-- 新增 `adapters/README.md`。
|
|
|
-- 新增 `adapters/registry.json`。
|
|
|
-- 为每个目标宿主新增 `support.md`。
|
|
|
-- 每个 `support.md` 只记录官方文档核验结果和本项目降级策略。
|
|
|
-
|
|
|
-影响：
|
|
|
-
|
|
|
-- 不影响现有 Claude Code 用户。
|
|
|
-- 不影响 runtime。
|
|
|
-
|
|
|
-### Phase 2：Agent 规范名与兼容映射
|
|
|
-
|
|
|
-目标：引入 `webnovel-*` 规范 Agent 名，但不破坏旧名。
|
|
|
-
|
|
|
-改动：
|
|
|
-
|
|
|
-- 新增 `agents/aliases.json` 或等价映射。
|
|
|
-- 更新 adapter registry 使用规范名。
|
|
|
-- 更新 behavior eval，确保旧名与规范名不会互相漂移。
|
|
|
-
|
|
|
-影响：
|
|
|
-
|
|
|
-- Claude Code 现有 Skill 仍可调用旧名。
|
|
|
-- 后续宿主生成优先使用规范名。
|
|
|
-
|
|
|
-### Phase 3：Skill 瘦身与宿主工具映射
|
|
|
-
|
|
|
-目标：减少 Skill 主体中的 Claude-only 工具表达。
|
|
|
-
|
|
|
-改动：
|
|
|
-
|
|
|
-- 新增 `skills/using-webnovel-writer/`。
|
|
|
-- 把跨宿主工具映射放到 references。
|
|
|
-- 保留 Claude Code 示例中的 `${CLAUDE_PLUGIN_ROOT}`。
|
|
|
-- 不把每个宿主的完整说明复制进 8 个业务 Skill。
|
|
|
-
|
|
|
-影响：
|
|
|
-
|
|
|
-- Skill 更短，更容易被不同宿主消费。
|
|
|
-- 当前 Claude Code 命令不变。
|
|
|
-
|
|
|
-### Phase 4：生成器与 drift check
|
|
|
-
|
|
|
-目标：让非 Claude adapter 可生成、可检查。
|
|
|
-
|
|
|
-改动：
|
|
|
-
|
|
|
-- 新增 `scripts/generate_host_artifacts.py`。
|
|
|
-- 生成 `dist/<host>/webnovel-writer/`。
|
|
|
-- 扩展 `validate_plugin_package.py` 检查 adapter。
|
|
|
-- CI 增加 drift check。
|
|
|
-
|
|
|
-影响：
|
|
|
-
|
|
|
-- 新增开发工具，不改变用户项目数据。
|
|
|
-- 生成文件默认不提交。
|
|
|
-
|
|
|
-### Phase 5：跨宿主 smoke 与行为 eval
|
|
|
-
|
|
|
-目标：证明“能发现、能体检、能执行核心流程或明确降级”。
|
|
|
-
|
|
|
-改动：
|
|
|
-
|
|
|
-- 扩展 `run_behavior_evals.py`。
|
|
|
-- 每个宿主至少有 discover / project-status / doctor smoke。
|
|
|
-- 至少一个非 Claude 宿主完成 `webnovel-write` 兼容模式验收。
|
|
|
-
|
|
|
-影响：
|
|
|
-
|
|
|
-- 发布前检查时间增加。
|
|
|
-- 适配声明更可信。
|
|
|
-
|
|
|
-### Phase 6：发布文档与版本治理
|
|
|
-
|
|
|
-目标：用户知道哪个宿主支持到什么程度。
|
|
|
-
|
|
|
-改动：
|
|
|
-
|
|
|
-- README 增加多宿主支持表。
|
|
|
-- `docs/guides/commands.md` 增加非 Claude 使用口径。
|
|
|
-- `docs/operations/plugin-release.md` 增加 adapter 发布检查。
|
|
|
-- release note 明确每个宿主支持等级。
|
|
|
-
|
|
|
-影响：
|
|
|
-
|
|
|
-- 避免用户误以为所有宿主都已完整支持。
|
|
|
-- 降低 issue 中的环境误解。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 15. 风险与控制
|
|
|
-
|
|
|
-| 风险 | 影响 | 控制 |
|
|
|
-|---|---|---|
|
|
|
-| 外部宿主能力描述过期 | spec 很快失真 | 每个 adapter 用 `support.md` 记录官方核验日期和链接 |
|
|
|
-| 为每个宿主复制业务流程 | 逻辑漂移 | adapter 只调 `webnovel.py`，不复制 runtime |
|
|
|
-| 重命名 Agent 破坏旧流程 | 现有用户调用失败 | 旧名兼容一个小版本周期以上 |
|
|
|
-| hook 被误当业务流程 | 隐藏副作用 | hook 只做状态提示和危险写入兜底 |
|
|
|
-| Skill 主体继续膨胀 | token 消耗高 | 详细内容下沉 references，确定性动作下沉 scripts |
|
|
|
-| 生成产物漂移 | 发布包和源不一致 | `generate_host_artifacts.py --check` |
|
|
|
-| Windows 中文路径失败 | 用户无法运行 | 所有新增 Python I/O 使用 UTF-8，命令用 `python -X utf8` |
|
|
|
+- **drift check**：`build-host-shells.mjs --check`，提交的生成物（`agents/` 等）与源不一致即红。
|
|
|
+- **package validator**：registry schema、逐宿主 support.md 存在性、smoke 命令声明、生成物无本机绝对路径、skill description 长度（Codex 8k 预算）。
|
|
|
+- **行为 smoke**（每个一级宿主）：discover（skill 可发现）→ 建库 → 盘面 → 写一章全事务 → 删 `.cache/` 重建。Windows 中文路径全链路必测。
|
|
|
+- **降级验收**：至少一个无 subagent 环境跑通三镜头兼容模式，且输出含兼容模式声明。
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 16. 验收清单
|
|
|
-
|
|
|
-最终完成时必须满足：
|
|
|
-
|
|
|
-- [ ] Claude Code 原安装流程不破坏。
|
|
|
-- [ ] 8 个现有 Skill 仍可发现。
|
|
|
-- [ ] `/webnovel-doctor` 保留并进入多宿主自检路径。
|
|
|
-- [ ] 当前 hooks 保持 plugin-dev wrapper 格式。
|
|
|
-- [ ] `project-status`、`doctor`、`write-gate`、`projections` 都是跨宿主共享 runtime 入口。
|
|
|
-- [ ] `status` 仍保留旧宏观健康报告语义。
|
|
|
-- [ ] Agent 规范名有 `webnovel-` 前缀，旧名有兼容映射。
|
|
|
-- [ ] 每个 adapter 都有 `support.md`，包含官方文档核验日期和链接。
|
|
|
-- [ ] 每个 adapter 都有 smoke 命令或明确阻断原因。
|
|
|
-- [ ] 生成器可生成非 Claude 宿主产物。
|
|
|
-- [ ] drift check 能发现生成产物不一致。
|
|
|
-- [ ] package validator 覆盖 adapter registry、support.md 和 manifest 漂移。
|
|
|
-- [ ] behavior eval 覆盖 8 个 Skill 和至少一个非 Claude 兼容写作流程。
|
|
|
-- [ ] README 和 release note 明确每个宿主的支持等级。
|
|
|
-
|
|
|
----
|
|
|
+## 10. 迁移计划
|
|
|
|
|
|
-## 17. 简短结论
|
|
|
+随 v7 绞杀式收敛推进，不单独立项：
|
|
|
|
|
|
-这次多宿主适配的核心不是“再写一套插件”，而是：
|
|
|
+| Phase | 内容 | 依赖 |
|
|
|
+|---|---|---|
|
|
|
+| A | 本 spec v3 定稿入册；registry + Claude Code / Codex 两份 support.md（核验 + smoke 定义） | 无 |
|
|
|
+| B | 状态机入口 SKILL.md 与 `roles/` 单源落地（随 v7 Phase 1-2 实现） | v7 数据面 |
|
|
|
+| C | `build-host-shells.mjs` 生成器 + drift check 进 CI | B |
|
|
|
+| D | npx 安装器 | B |
|
|
|
+| E | Codex 亲测过 smoke，升一级；Gemini/Cursor 收集社区反馈 | C、D |
|
|
|
+| F | README 多宿主支持表 + release note 分级口径 | E |
|
|
|
|
|
|
-- 保住当前 `v6.1.0` 已经做好的 runtime 基线。
|
|
|
-- 把 Claude Code 作为第一宿主继续维护。
|
|
|
-- 用 adapter 和生成器把同一套能力暴露给其他宿主。
|
|
|
-- 用 doctor、project-status、write-gate、projection log 和 eval 证明它真的能用。
|
|
|
+## 11. 风险与控制
|
|
|
|
|
|
-这样改，后续扩展宿主时不会把项目重新打散，也不会让用户在多个看起来相似、实际语义不同的入口里迷路。
|
|
|
+| 风险 | 控制 |
|
|
|
+|---|---|
|
|
|
+| 宿主能力描述过期 | support.md 核验日期纪律；无核验不进一二级 |
|
|
|
+| 角色壳三平台漂移 | 单源 `roles/` + 生成器，禁止手改生成物，drift check 兜底 |
|
|
|
+| 弱模型宿主上流程失守 | 机检与 settle 全是脚本；模型只做渲染与镜头评审 |
|
|
|
+| Codex skill 预算超限 | validator 检查 description 长度 |
|
|
|
+| 降级模式被冒充 | 降级诚实条款进行为 smoke 验收 |
|
|
|
+| Windows 中文路径 | Node 默认 UTF-8 + CI 全链路测试 |
|
|
|
+
|
|
|
+## 12. 验收清单
|
|
|
+
|
|
|
+- [ ] story repo 是唯一真源：任何宿主无绕过 settle 的写路径。
|
|
|
+- [ ] 状态机入口 SKILL.md 在 Claude Code 与 Codex 上可发现、可执行。
|
|
|
+- [ ] `roles/` 单源，三平台壳全部由生成器产出，drift check 进 CI。
|
|
|
+- [ ] npx 安装器在 Windows 中文环境一条命令完成分发。
|
|
|
+- [ ] registry 三级分级，一级宿主有 support.md + 过 smoke。
|
|
|
+- [ ] 无 subagent 宿主跑通兼容模式且如实声明。
|
|
|
+- [ ] hook 缺席的宿主核心流程行为等价。
|
|
|
+
|
|
|
+## 13. 简短结论
|
|
|
+
|
|
|
+v2 答对的是"怎么诚实地适配多宿主"（support.md、registry、生成器、降级诚实），答错的是"适配什么"——它适配的 v6 runtime 已被 v7 推翻。v3 保住前者，把基座换成 story repo：格式平台无关，入口是开放标准 SKILL.md，角色单源生成，安装一条 npx。宿主越弱，越证明"流程薄 + 脚本确定性"是对的。
|
聆风