# Webnovel Writer 多智能体适配最终形态 Spec
> 日期：2026-06-05
> 状态：草案 v1
> 定位：把 Webnovel Writer 从 Claude Code 专用插件演进为跨宿主、多 agent、可验证的写作插件
> 参考样本：Superpowers、PostHog AI Plugin、Shopify AI Toolkit、Compound Engineering、wshobson/agents
---
## 1. 背景与问题
### 1.1 当前状态
当前 Webnovel Writer 已具备一套完整的 Claude Code 插件形态：
```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/
├── scripts/
├── references/
├── templates/
├── genres/
└── dashboard/
```
核心能力已经不是问题：
- `skills/` 定义写作工作流入口
- `agents/` 承载写前组装、审查、数据提取、参考书拆解等 subagent
- `scripts/` 负责项目初始化、Story System、索引、记忆、审查落库、Dashboard
- `.story-system/` 与 `.webnovel/` 已形成主链事实源与投影层
真正的问题是：这些能力目前默认运行在 Claude Code 的插件语义里，文档和流程里存在多处 Claude Code 耦合。
### 1.2 当前 Claude 耦合点
当前 skills/agents 中主要耦合点：
| 类型 | 现状 | 问题 |
|------|------|------|
| 插件根路径 | 大量使用 `CLAUDE_PLUGIN_ROOT` | Codex、OpenCode 等宿主使用 `PLUGIN_ROOT` 或不同机制 |
| 项目根路径 | 大量使用 `CLAUDE_PROJECT_DIR` | 非 Claude 宿主未必提供该变量 |
| 工具名 | `Read` / `Write` / `Edit` / `Grep` / `Bash` / `Agent` / `AskUserQuestion` | 各宿主工具名、调用语义不同 |
| subagent 调度 | 明确写 `Agent(...)` | Codex、Gemini、OpenCode、Copilot 都有不同 subagent 入口 |
| slash 命令 | README 与 docs 默认 `/webnovel-*` | 非 Claude 宿主可能以 skill、command TOML、prompt entry 或插件命令暴露 |
| skill 体积 | 部分 `SKILL.md` 很长 | Codex 等宿主对 skill body 有更严格的有效上下文预算 |
| hooks | 当前未形成跨宿主 bootstrap | 不同宿主启动注入能力差异较大 |
### 1.3 本 spec 要解决的问题
本 spec 解决的是**多智能体适配最终形态**，包含两层含义：
1. **多宿主适配**：同一套 Webnovel Writer 能在 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、GitHub Copilot CLI 等宿主中运行。
2. **多 subagent 适配**：`context-agent`、`reviewer`、`data-agent`、`deconstruction-agent` 能在不同宿主的 agent/subagent 能力中被正确调度，能力不足时有明确降级规则。
本 spec 不只是“补几个 manifest”，而是规定最终状态下：
- 哪些文件是唯一事实源
- 哪些文件是宿主适配产物
- 哪些产物必须提交
- 哪些产物由生成器生成
- 不同宿主如何加载 skill、agent、command、hook
- skill 文案如何避免 Claude Code 专用表达
- 如何验证每个宿主真的可用
---
## 2. 设计目标与非目标
### 2.1 目标
1. **一套源内容，多宿主消费**
- `skills/`、`agents/`、`scripts/`、`references/`、`templates/`、`dashboard/` 是唯一业务事实源。
- 不为每个宿主手写一套完整 Webnovel Writer。
2. **保留 Claude Code 现有体验**
- 现有 Claude Code 安装路径、skill 名称、agent 名称和核心流程不破坏。
- `/webnovel-init`、`/webnovel-plan`、`/webnovel-write`、`/webnovel-review`、`/webnovel-query`、`/webnovel-dashboard` 继续可用。
3. **Codex / Cursor 原生插件优先**
- Codex 使用 `.codex-plugin/plugin.json` 加载 plugin root 下的 `skills/`。
- Cursor 使用 `.cursor-plugin/plugin.json` 加载 plugin root 下的 `skills/`、`agents/`、`hooks`。
4. **Gemini / OpenCode / Copilot 使用生成适配**
- 这些宿主能力差异更大，最终形态允许生成宿主原生产物。
- 生成产物来自源目录，不手工维护双份。
5. **subagent 调度语义平台化**
- skill 中只表达“调用 `context-agent`”，不写死 `Agent(...)`。
- 平台如何调用由 `using-webnovel-writer` 与 adapter 负责。
6. **Python runtime 可移植**
- 所有 scripts 通过统一环境变量解析插件根、项目根。
- 不依赖 `CLAUDE_PLUGIN_ROOT` 单一变量。
7. **有验收矩阵**
- 每个宿主必须至少通过 skill 发现、fixture 查询、章节审查、Dashboard 或写作链路中的指定 smoke test。
### 2.2 非目标
1. 不重写 Story System、RAG、memory contract、chapter commit 链。
2. 不把 Python CLI 改成 MCP server。
3. 不保证所有宿主有完全一致的 UI 入口。
4. 不要求不支持 hooks 的宿主强行注入 session bootstrap。
5. 不要求所有宿主第一阶段都支持完整 `webnovel-write` 多 agent 链。
6. 不支持复制粘贴式多份 skill 文档维护。
---
## 3. 参考项目结论
### 3.1 Superpowers 模式
Superpowers 的核心做法：
- `skills/` 是共享源
- `.claude-plugin/`、`.codex-plugin/`、`.cursor-plugin/`、`gemini-extension.json` 是薄适配层
- `using-superpowers` 作为 bootstrap skill
- 工具名差异放在 `references/*-tools.md`
- OpenCode 用 JS 插件动态注册 skills 路径并注入 bootstrap
适合 Webnovel Writer 借鉴的点：
- 共享 skills，不复制核心逻辑
- 用 bootstrap skill 解释平台工具映射
- hook 输出兼容不同宿主 JSON 字段
### 3.2 PostHog AI Plugin 模式
PostHog 的核心做法：
- Codex manifest 直接声明 `skills` 与 `.mcp.json`
- hooks 使用 `${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT}` 兼容 Claude/Codex 环境变量
- commands 以 `.md` 为源，生成 Gemini TOML
适合 Webnovel Writer 借鉴的点：
- 环境变量兼容写法
- 有脚本的 skill 仍然可以跨宿主
- hook 命令必须考虑宿主变量差异
### 3.3 Shopify AI Toolkit 模式
Shopify 的核心做法：
- 大量 `skills/` + scripts + assets
- 各宿主 manifest 很薄
- skill 内可以携带压缩 schema、校验脚本、文档搜索脚本
适合 Webnovel Writer 借鉴的点：
- Webnovel Writer 同样是 scripts/assets 重型插件，不必把所有能力改成纯 prompt
- skill 只负责指导 agent 何时调用脚本
- 本地资产与脚本仍以 plugin root 相对路径解析
### 3.4 Compound Engineering 模式
Compound Engineering 的核心做法：
- Claude 是源
- Codex 原生插件先保证 skills
- 完整 agents 体验需要 companion converter
- 明确接受不同宿主能力降级
适合 Webnovel Writer 借鉴的点：
- agents 是跨宿主最难部分，可以分阶段完成
- Codex 第一阶段不必阻塞在完整 agent 原生注册上
- 文档必须说明“完整写作链需要 subagent 支持”
### 3.5 wshobson/agents 模式
wshobson/agents 的核心做法：
- `plugins/` 是唯一源
- `tools/adapters/` 生成 Codex、Gemini、OpenCode、Copilot 等宿主产物
- 对 skill body 大小、工具名、agent 名称冲突、model mapping 做静态检查
- command 在 Codex 转 skill，在 Gemini 转 TOML
适合 Webnovel Writer 借鉴的点：
- 最终形态应有 adapter + portability lint
- `SKILL.md` 应瘦身，细节移入 `references/`
- agent 名称应全局唯一，避免跨插件冲突
- 生成产物必须有 drift check
---
## 4. 核心设计原则
### 4.1 源目录唯一
以下目录是唯一业务事实源：
```text
webnovel-writer/skills/
webnovel-writer/agents/
webnovel-writer/scripts/
webnovel-writer/references/
webnovel-writer/templates/
webnovel-writer/genres/
webnovel-writer/dashboard/
```
任何宿主适配产物都不得成为新的业务事实源。
禁止：
- 为 Codex 复制一套 `skills-codex/`
- 为 Gemini 手写一套不同内容的 `agents-gemini/`
- 在 OpenCode 插件 JS 中内联完整业务 prompt
- 修改生成产物后不回写源目录
### 4.2 适配层只处理宿主差异
适配层只允许处理：
- manifest 格式
- skill/agent/command 文件位置
- frontmatter 字段转换
- 工具名映射
- model 名称映射
- hook 输出格式
- subagent 调度入口
- install / marketplace 元数据
适配层不得处理：
- 写作流程本身
- 审查标准
- Story System schema
- 章节提交逻辑
- 题材知识
- reference 内容
### 4.3 skill 写动作，不写工具
最终形态下，skill 正文应优先写动作语义：
| 不推荐 | 推荐 |
|--------|------|
| 使用 `Read` 工具读取文件 | 读取文件 |
| 使用 `Bash` 运行命令 | 运行命令 |
| 使用 `Grep` 搜索 | 搜索 |
| 使用 `Agent` 调用 `reviewer` | 调用 `reviewer` subagent |
| 使用 `AskUserQuestion` 询问用户 | 向用户确认 |
Claude Code 专用工具名只允许出现在：
- frontmatter `allowed-tools`
- `using-webnovel-writer/references/claude-tools.md`
- adapter 测试 fixture
- 必要的历史兼容说明
### 4.4 agent 调度是能力，不是工具名
`webnovel-write` 的核心规则不是“必须调用 Claude 的 `Agent` 工具”，而是：
> 必须把写前组装、审查、事实提取交给隔离上下文的专门 subagent，不得由主流程口头替代。
因此最终 skill 应表达为：
```text
调用 `context-agent` subagent 生成写作任务书。
按当前宿主的 subagent 调度方式执行；若当前宿主不支持 subagent，进入兼容模式或阻断。
```
平台如何执行由 tool mapping 决定。
### 4.5 渐进式披露优先
最终形态下，每个 `SKILL.md` 应成为入口与导航，不应承载完整长篇协议。
目标结构：
```text
skills/webnovel-write/
├── SKILL.md # 入口、决策树、步骤摘要、引用加载策略
└── references/
├── protocol.md # 完整写章协议
├── agent-contracts.md # context/reviewer/data-agent 输入输出契约
├── failure-recovery.md # 失败补跑与恢复
└── ...
```
`SKILL.md` 推荐控制在 8 KB 以内；长内容进入 `references/`。
### 4.6 能力不足必须显式降级
不同宿主能力不一致。最终形态不假装能力一致。
| 场景 | 处理 |
|------|------|
| 宿主支持 subagent | 正常多 agent 链 |
| 宿主不支持 subagent，但用户只查询/学习/启动 dashboard | 正常执行 |
| 宿主不支持 subagent，用户要 `webnovel-write` | 默认阻断，提示需要支持 subagent 的宿主；允许显式 `--single-agent` 兼容模式 |
| 宿主不支持 hooks | 不依赖 hooks 自动注入；通过 context file / command / skill 入口加载 |
| 宿主不支持 slash command | 暴露为 skill 或 command TOML |
---
## 5. 最终目录形态
### 5.1 仓库根目录
最终仓库根目录：
```text
.
├── .claude-plugin/
│ └── marketplace.json
├── .cursor-plugin/
│ └── marketplace.json
├── .agents/
│ └── plugins/
│ └── marketplace.json # Codex marketplace registry，可选
├── docs/
├── scripts/
│ └── generate_harness_artifacts.py # 新增：生成宿主产物
├── tests/
│ └── harness/
│ ├── test_manifests.py
│ ├── test_portability.py
│ └── test_generated_artifacts.py
├── webnovel-writer/
└── README.md
```
说明：
- Claude 现有 root marketplace 保留。
- Cursor root marketplace 新增，用于 Cursor Plugin Marketplace。
- Codex marketplace registry 可选；如果采用官方目录或本地安装，可只保留 `.codex-plugin/plugin.json`。
- 生成器放仓库根目录 `scripts/`，避免混入插件 runtime scripts。
### 5.2 插件根目录
最终 plugin root 仍然是：
```text
webnovel-writer/
```
最终结构：
```text
webnovel-writer/
├── .claude-plugin/
│ └── plugin.json
├── .codex-plugin/
│ └── plugin.json
├── .cursor-plugin/
│ └── plugin.json
├── .opencode/
│ └── plugins/
│ └── webnovel-writer.js
├── hooks/
│ ├── hooks.json
│ ├── hooks-cursor.json
│ ├── run-hook.cmd
│ └── session-start
├── skills/
│ ├── using-webnovel-writer/
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── claude-tools.md
│ │ ├── codex-tools.md
│ │ ├── cursor-tools.md
│ │ ├── gemini-tools.md
│ │ ├── opencode-tools.md
│ │ └── copilot-tools.md
│ ├── webnovel-init/
│ ├── webnovel-plan/
│ ├── webnovel-write/
│ ├── webnovel-review/
│ ├── webnovel-query/
│ ├── webnovel-learn/
│ └── webnovel-dashboard/
├── agents/
│ ├── webnovel-context-agent.md
│ ├── webnovel-data-agent.md
│ ├── webnovel-deconstruction-agent.md
│ └── webnovel-reviewer.md
├── scripts/
├── references/
├── templates/
├── genres/
├── dashboard/
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
└── README.md
```
### 5.3 agent 命名收敛
当前 agent 名称：
```text
context-agent
data-agent
deconstruction-agent
reviewer
```
最终建议改为插件作用域名称：
```text
webnovel-context-agent
webnovel-data-agent
webnovel-deconstruction-agent
webnovel-reviewer
```
原因：
- 避免与其他插件的 `reviewer`、`context-agent` 冲突
- Codex / Copilot / Cursor 多插件环境中更稳定
- 用户和日志能明确看到来源
兼容策略：
- 第一阶段保留旧文件名或旧 alias。
- skill 正文改用新名称。
- adapter 可为 Claude 生成 alias 或保留旧名一版。
- v7 后删除旧 agent 名。
---
## 6. 宿主适配最终形态
### 6.1 Claude Code
Claude Code 继续作为一级支持宿主。
源文件：
```text
.claude-plugin/marketplace.json
webnovel-writer/.claude-plugin/plugin.json
webnovel-writer/skills/
webnovel-writer/agents/
webnovel-writer/hooks/hooks.json
```
安装：
```bash
claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user
```
要求：
- 现有 Claude Code 使用方式不破坏。
- `allowed-tools` frontmatter 可保留。
- `Agent` 工具由 Claude Code 原生处理。
- `hooks/session-start` 注入短 bootstrap。
### 6.2 Codex CLI / Codex App
Codex 使用原生 plugin manifest。
新增：
```text
webnovel-writer/.codex-plugin/plugin.json
```
最小 manifest：
```json
{
"name": "webnovel-writer",
"version": "6.0.0",
"description": "Long-form Chinese webnovel writing system with skills, agents, story state, RAG, and review workflows.",
"author": { "name": "lingfengQAQ" },
"homepage": "https://github.com/lingfengQAQ/webnovel-writer",
"repository": "https://github.com/lingfengQAQ/webnovel-writer",
"license": "GPL-3.0",
"keywords": ["webnovel", "writing", "skills", "agents", "rag"],
"skills": "./skills/",
"hooks": "./hooks/hooks.json",
"interface": {
"displayName": "Webnovel Writer",
"shortDescription": "Long-form webnovel planning, writing, review, and story-state workflows",
"longDescription": "Plan, write, review, query, and maintain long-form Chinese webnovel projects with story state, memory, RAG, and agent workflows.",
"developerName": "lingfengQAQ",
"category": "Writing",
"capabilities": ["Interactive", "Read", "Write"],
"defaultPrompt": [
"初始化一个新的网文项目",
"写下一章并更新故事状态",
"查询当前项目里的角色和伏笔状态"
]
}
}
```
Codex 支持级别：
| 能力 | 方式 |
|------|------|
| skills | 原生 `.codex-plugin/plugin.json` 指向 `./skills/` |
| hooks | 可选；用户需信任 hook |
| agents | 最终通过 adapter 生成 Codex agent 配置，或由 skill 以 prompt template 调度 |
| commands | 不单独维护；需要时由 skills 或 generated command-skill 暴露 |
| tool mapping | `using-webnovel-writer/references/codex-tools.md` |
Codex 多 agent 要求：
- 完整 `webnovel-write` 需要 Codex 启用 multi-agent 能力。
- 若当前 Codex 环境没有 subagent 能力：
- `webnovel-query`、`webnovel-learn`、`webnovel-dashboard` 可执行
- `webnovel-review` 可进入单 reviewer prompt 兼容模式
- `webnovel-write` 默认阻断，除非用户显式选择 `--single-agent`
### 6.3 Cursor
Cursor 使用 Cursor plugin manifest。
新增：
```text
.cursor-plugin/marketplace.json
webnovel-writer/.cursor-plugin/plugin.json
webnovel-writer/hooks/hooks-cursor.json
```
Cursor plugin manifest：
```json
{
"name": "webnovel-writer",
"displayName": "Webnovel Writer",
"description": "长篇网文创作系统（skills + agents + data chain + RAG）",
"version": "6.0.0",
"author": { "name": "lingfengQAQ" },
"homepage": "https://github.com/lingfengQAQ/webnovel-writer",
"repository": "https://github.com/lingfengQAQ/webnovel-writer",
"license": "GPL-3.0",
"keywords": ["webnovel", "cursor", "skills", "agents", "rag"],
"skills": "./skills/",
"agents": "./agents/",
"hooks": "./hooks/hooks-cursor.json"
}
```
要求：
- Cursor 读取源 `skills/` 与 `agents/`，不生成复制目录。
- hook 输出使用 Cursor 需要的 `additional_context`。
- Cursor 文档中使用 `/add-plugin webnovel-writer`。
### 6.4 Gemini CLI
Gemini CLI 最终采用**生成 extension root** 方式，不直接把仓库根当 Gemini extension 根。
原因：
- 当前仓库 root 不是 plugin root。
- Gemini extension 需要 `gemini-extension.json` 与 `GEMINI.md` 在 extension root。
- Gemini 的 skills、agents、commands 发现路径更适合扁平生成。
生成产物：
```text
dist/gemini/webnovel-writer/
├── gemini-extension.json
├── GEMINI.md
├── skills/
│ ├── webnovel-writer__using-webnovel-writer/
│ ├── webnovel-writer__webnovel-init/
│ ├── webnovel-writer__webnovel-plan/
│ ├── webnovel-writer__webnovel-write/
│ ├── webnovel-writer__webnovel-review/
│ ├── webnovel-writer__webnovel-query/
│ ├── webnovel-writer__webnovel-learn/
│ └── webnovel-writer__webnovel-dashboard/
├── agents/
│ ├── webnovel-writer__webnovel-context-agent.md
│ ├── webnovel-writer__webnovel-data-agent.md
│ ├── webnovel-writer__webnovel-deconstruction-agent.md
│ └── webnovel-writer__webnovel-reviewer.md
├── commands/
│ ├── webnovel-init.toml
│ ├── webnovel-plan.toml
│ ├── webnovel-write.toml
│ ├── webnovel-review.toml
│ ├── webnovel-query.toml
│ ├── webnovel-learn.toml
│ └── webnovel-dashboard.toml
├── scripts/
├── references/
├── templates/
├── genres/
└── dashboard/
```
`gemini-extension.json`：
```json
{
"name": "webnovel-writer",
"description": "Long-form Chinese webnovel writing system.",
"version": "6.0.0",
"contextFileName": "GEMINI.md"
}
```
Gemini tool mapping：
| 源语义 | Gemini |
|--------|--------|
| 读取文件 | `read_file` |
| 写入文件 | `write_file` |
| 编辑文件 | `replace` |
| 搜索 | `grep_search` |
| 运行命令 | `run_shell_command` |
| 向用户确认 | `ask_user` 或直接提问 |
| 调用 subagent | `@webnovel-writer__agent-name` |
### 6.5 OpenCode
OpenCode 使用 JS 插件 + 生成目录。
新增：
```text
webnovel-writer/.opencode/plugins/webnovel-writer.js
```
最终行为：
1. JS 插件将 plugin root 下的 `skills/` 注册到 OpenCode config。
2. JS 插件将 bootstrap 注入第一条 user message。
3. Adapter 生成 OpenCode 原生 agents/commands/skills 到 `.opencode/` 或安装目录。
生成产物：
```text
dist/opencode/webnovel-writer/
├── .opencode/
│ ├── plugins/
│ │ └── webnovel-writer.js
│ ├── skills/
│ ├── agents/
│ └── commands/
└── opencode.json
```
OpenCode tool mapping：
| 源语义 | OpenCode |
|--------|----------|
| 读取文件 | `read` |
| 写入文件 | `write` |
| 编辑文件 | `edit` |
| 搜索 | `grep` |
| 运行命令 | `bash` |
| 任务跟踪 | `todowrite` |
| 调用 subagent | `task` 或 `@agent` |
### 6.6 GitHub Copilot CLI
Copilot CLI 第一阶段使用 Claude plugin compatibility；最终可生成 Copilot 原生产物。
最终生成产物：
```text
dist/copilot/webnovel-writer/
├── .copilot/
│ ├── skills/
│ ├── agents/
│ └── commands/
└── plugin.json
```
支持策略：
- 若 Copilot 原生插件可直接读取 Claude plugin metadata，则优先用 native plugin install。
- 若需要完整 agents/commands，则使用生成器输出 `.copilot/`。
- 不写入共享 `~/.agents/skills`，避免 shadowing 其他宿主插件。
### 6.7 Factory Droid / Qwen Code
这两类宿主如果已支持 Claude Code plugin compatibility，则使用 Claude plugin metadata 作为第一路径。
策略：
- 不第一阶段单独维护 Droid/Qwen manifest。
- 文档中说明“通过宿主的 Claude plugin compatibility 安装”。
- 发现真实兼容失败后，再新增 adapter。
---
## 7. Bootstrap 与 using-webnovel-writer
### 7.1 新增 bootstrap skill
新增：
```text
skills/using-webnovel-writer/SKILL.md
```
职责：
1. 说明 Webnovel Writer 的能力边界。
2. 告诉 agent 如何选择 `webnovel-*` skill。
3. 定义插件根、项目根、脚本根解析方式。
4. 指向各宿主 tool mapping。
5. 定义 subagent 调度规则。
6. 定义能力不足时的降级策略。
不职责：
- 不写完整写作流程。
- 不承载 Story System 细节。
- 不重复每个 skill 的协议。
### 7.2 SessionStart 注入
新增：
```text
hooks/session-start
hooks/run-hook.cmd
hooks/hooks.json
hooks/hooks-cursor.json
```
注入内容应短，不应把完整系统文档灌进上下文。
推荐注入：
```text
Webnovel Writer is installed.
When the user asks to initialize, plan, write, review, query, learn from, or inspect a Chinese webnovel project, load the relevant webnovel-* skill.
For platform-specific tool and subagent mappings, load using-webnovel-writer.
```
Claude / Cursor / Codex hook 输出格式按宿主区分：
| 宿主 | 输出字段 |
|------|----------|
| Claude Code | `hookSpecificOutput.additionalContext` |
| Cursor | `additional_context` |
| Codex / SDK 标准 | `additionalContext` |
hooks 只负责启动提示，不作为唯一入口。Gemini/OpenCode/Copilot 不能依赖 hooks 存在。
### 7.3 Context files
最终新增：
```text
webnovel-writer/AGENTS.md
webnovel-writer/CLAUDE.md
webnovel-writer/GEMINI.md
```
职责：
- 只做目录和入口说明。
- 不超过约 150 行。
- 详细规则进入 `skills/using-webnovel-writer/`。
`GEMINI.md` 应引用：
```text
@./skills/using-webnovel-writer/SKILL.md
@./skills/using-webnovel-writer/references/gemini-tools.md
```
---
## 8. Runtime 环境兼容
### 8.1 统一环境变量
最终所有 skill bash 片段必须使用统一变量：
```bash
export WEBNOVEL_PLUGIN_ROOT="${WEBNOVEL_PLUGIN_ROOT:-${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}}"
export WORKSPACE_ROOT="${WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-$PWD}}"
if [ -z "${WEBNOVEL_PLUGIN_ROOT}" ] || [ ! -d "${WEBNOVEL_PLUGIN_ROOT}/scripts" ]; then
echo "ERROR: 未找到 Webnovel Writer 插件根目录" >&2
exit 1
fi
export SCRIPTS_DIR="${WEBNOVEL_PLUGIN_ROOT}/scripts"
export PROJECT_ROOT="$(python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"
```
禁止在新增文档中继续直接使用：
```bash
${CLAUDE_PLUGIN_ROOT}/scripts
```
除非是在兼容说明或历史迁移章节。
### 8.2 Python runtime helper
最终应扩展或新增：
```text
webnovel-writer/scripts/runtime_compat.py
```
职责：
- 解析 plugin root
- 解析 workspace root
- 解析 project root
- 校验 scripts/dashboard/templates 路径存在
- 输出 JSON 供 smoke test 使用
建议 CLI：
```bash
python -X utf8 "${SCRIPTS_DIR}/webnovel.py" runtime-info --format json
```
输出：
```json
{
"plugin_root": ".../webnovel-writer",
"workspace_root": "...",
"project_root": "...",
"scripts_dir": ".../webnovel-writer/scripts",
"dashboard_dir": ".../webnovel-writer/dashboard",
"platform_env": {
"PLUGIN_ROOT": true,
"CLAUDE_PLUGIN_ROOT": false,
"CLAUDE_PROJECT_DIR": false
}
}
```
### 8.3 依赖安装
跨宿主不改变 Python 依赖策略：
```bash
python -m pip install -r requirements.txt
```
但 skill 中必须把“安装依赖”写成可重复、可失败恢复的步骤：
- 依赖已存在时不视为错误。
- Dashboard 依赖与 scripts 依赖分开。
- RAG API key 缺失时只阻断需要 RAG 的操作，不阻断 query/dashboard 基础功能。
---
## 9. Skill 改造规范
### 9.1 每个 skill 的最终结构
每个 skill 最终结构：
```text
skills//
├── SKILL.md
├── references/
│ ├── protocol.md
│ ├── failure-recovery.md
│ └── ...
├── scripts/ # 仅 skill 私有脚本，公共脚本仍放 plugin scripts/
└── assets/ # 可选
```
`SKILL.md` 必须包含：
1. frontmatter
2. Use when / trigger
3. 目标
4. 前置条件
5. 决策树
6. 流程摘要
7. 引用加载策略
8. 成功标准
9. 失败恢复入口
`SKILL.md` 不应包含：
- 完整长协议
- 大量示例正文
- 大段 reference 内容
- 过多 Bash 细节
### 9.2 frontmatter 规则
Claude 源 frontmatter 可保留：
```yaml
---
name: webnovel-write
description: Use when writing a publishable webnovel chapter from an existing project outline and story runtime.
allowed-tools: Read Write Edit Grep Bash Agent
---
```
要求：
- `description` 必须包含明确触发条件。
- 中文说明可以在正文，frontmatter description 优先写清楚行为。
- `allowed-tools` 视为 Claude-only 字段；adapter 对 Codex/Gemini/OpenCode 可剥离或映射。
### 9.3 webnovel-write 改造重点
`webnovel-write` 是多 agent 适配核心。
最终正文不应写：
```text
必须使用 `Agent` 工具调用 `context-agent`
```
应写：
```text
必须调用 `webnovel-context-agent` subagent 生成写作任务书。
按当前宿主的 subagent 调度方式执行；如果当前宿主不支持 subagent，见 `using-webnovel-writer` 的降级策略。
```
`Agent(...)` 示例移入：
```text
skills/using-webnovel-writer/references/claude-tools.md
```
### 9.4 webnovel-review 改造重点
`webnovel-review` 最终应支持两种模式：
| 模式 | 条件 | 行为 |
|------|------|------|
| full-agent | 宿主支持 subagent | 调用 `webnovel-reviewer`，主流程只落库和汇总 |
| compatibility | 宿主不支持 subagent | 主流程临时扮演 reviewer，但必须输出同一 JSON schema，并在报告中标记兼容模式 |
兼容模式只允许用于 review，不允许替代 `webnovel-write` 的完整多 agent 链。
### 9.5 webnovel-init 改造重点
`webnovel-init` 涉及 `deconstruction-agent`、`AskUserQuestion`、`WebSearch/WebFetch`。
最终要求：
- 用户确认类动作写成“向用户确认”，不写死 `AskUserQuestion`。
- 参考书拆解写成“调用 `webnovel-deconstruction-agent` subagent”。
- Web 搜索只在用户明确要求市场趋势/平台风向时触发。
- 不支持 WebSearch 的宿主应要求用户提供来源或跳过市场趋势核验。
### 9.6 webnovel-dashboard 改造重点
Dashboard 是最易跨宿主的 skill。
最终要求：
- 使用统一 `WEBNOVEL_PLUGIN_ROOT`。
- 启动服务时明确打印 URL。
- 不要求 GUI 自动打开浏览器。
- 只读能力必须保持。
---
## 10. Agent 改造规范
### 10.1 agent source 格式
源 agent 继续使用 Markdown + YAML frontmatter：
```yaml
---
name: webnovel-context-agent
description: Use before chapter drafting to assemble a writing brief from outline, contracts, memory, and review feedback.
tools: Read, Grep, Bash
model: inherit
---
```
正文写：
- 身份
- 输入
- 输出
- 流程
- 边界
- JSON schema / Markdown schema
- 错误处理
不写：
- 宿主专用调度方式
- `Agent(...)` 调用样例
- 与工具名强绑定的 prose
### 10.2 agent 输出契约
四个核心 agent 的输出契约必须稳定。
| Agent | 输出 |
|-------|------|
| `webnovel-context-agent` | 五段式写作任务书 |
| `webnovel-reviewer` | 严格 JSON issues 列表 |
| `webnovel-data-agent` | `fulfillment_result.json`、`disambiguation_result.json`、`extraction_result.json` 所需内容 |
| `webnovel-deconstruction-agent` | 严格 `init_reference_research` JSON |
这些输出契约写入：
```text
skills/webnovel-write/references/agent-contracts.md
skills/webnovel-init/references/agent-contracts.md
skills/webnovel-review/references/agent-contracts.md
```
### 10.3 adapter 输出
Agent adapter 负责把源 agent 转为宿主格式。
| 宿主 | 输出 |
|------|------|
| Claude Code | `agents/*.md` 原样 |
| Cursor | `agents/*.md` 原样或轻度 frontmatter 兼容 |
| Codex | `.codex/agents/webnovel-writer/.toml` 或 prompt template |
| Gemini | `agents/webnovel-writer__.md`，工具名映射 |
| OpenCode | `.opencode/agents/.md`，工具权限块映射 |
| Copilot | `.copilot/agents/.md` |
### 10.4 model mapping
源 agent 使用：
```yaml
model: inherit
```
不在源 agent 中写 `sonnet`、`opus`、`haiku` 作为强要求。
需要高能力模型的场景写在正文：
```text
该 agent 需要较强推理能力；若宿主支持选择模型，优先使用当前可用的高能力模型。
```
---
## 11. Adapter / 生成器设计
### 11.1 新增生成器
新增：
```text
scripts/generate_harness_artifacts.py
```
命令：
```bash
python -X utf8 scripts/generate_harness_artifacts.py --target codex
python -X utf8 scripts/generate_harness_artifacts.py --target gemini
python -X utf8 scripts/generate_harness_artifacts.py --target opencode
python -X utf8 scripts/generate_harness_artifacts.py --target copilot
python -X utf8 scripts/generate_harness_artifacts.py --target all
python -X utf8 scripts/generate_harness_artifacts.py --check
```
### 11.2 生成器职责
生成器负责：
- 读取 plugin root
- 解析 skill frontmatter
- 解析 agent frontmatter
- 复制 references/assets/scripts/templates/dashboard
- 生成宿主 manifest
- 转换 agent frontmatter
- 转换 command TOML
- 剥离宿主不支持字段
- 映射工具名
- 生成 drift manifest
生成器不负责：
- 修改业务源文件
- 解释写作流程
- 改写 Story System schema
- 联网下载依赖
### 11.3 输出目录
生成产物统一进入：
```text
dist//webnovel-writer/
```
`dist/` 默认 gitignored。
需要提交的只有：
- manifest 源
- adapter 源码
- 测试 fixture
- 生成快照 hash 或 drift manifest
例外：
- `.codex-plugin/plugin.json`
- `.cursor-plugin/plugin.json`
- root marketplace json
这些小型原生 manifest 可以提交。
### 11.4 Drift 检查
CI 必须运行：
```bash
python -X utf8 scripts/generate_harness_artifacts.py --target all
python -X utf8 scripts/generate_harness_artifacts.py --check
```
若生成产物与提交的 manifest/registry 不一致，CI 失败。
---
## 12. Tool Mapping
新增：
```text
skills/using-webnovel-writer/references/
├── claude-tools.md
├── codex-tools.md
├── cursor-tools.md
├── gemini-tools.md
├── opencode-tools.md
└── copilot-tools.md
```
### 12.1 通用映射表
| 源语义 | Claude | Codex | Gemini | OpenCode | Copilot |
|--------|--------|-------|--------|----------|---------|
| 读取文件 | `Read` | native read | `read_file` | `read` | `view` |
| 写文件 | `Write` | native write | `write_file` | `write` | `create` |
| 编辑文件 | `Edit` | native edit | `replace` | `edit` | `edit` |
| 搜索文本 | `Grep` | native search | `grep_search` | `grep` | `grep` |
| 运行命令 | `Bash` | shell command | `run_shell_command` | `bash` | `bash` |
| 网页搜索 | `WebSearch` | web search if enabled | `google_web_search` | web search if enabled | no guaranteed equivalent |
| 抓取网页 | `WebFetch` | web fetch if enabled | `web_fetch` | web fetch if enabled | `web_fetch` |
| 询问用户 | `AskUserQuestion` / direct | direct / structured input if available | `ask_user` | direct | direct |
| 调用 subagent | `Agent` / `Task` | `spawn_agent` or named subagent prompt | `@agent` | `task` / `@agent` | `task` |
| 任务跟踪 | `TodoWrite` | plan/update if available | no guaranteed equivalent | `todowrite` | todos/sql if available |
### 12.2 skill 正文约束
新增或修改 skill 时：
- 不直接写工具名，写动作。
- 如果确实必须写工具名，必须放入对应 tool mapping reference。
- `rg`、`python`、`git` 这类 shell 命令可以直接写。
---
## 13. 多 agent 工作流最终状态
### 13.1 webnovel-write 工作流
最终 `webnovel-write` 编排：
```text
主流程
1. 解析环境与项目根
2. preflight
3. placeholder-scan
4. 刷新 Story System runtime contracts
5. 调用 webnovel-context-agent
-> 输出五段式写作任务书
6. 主流程根据任务书起草正文
7. 调用 webnovel-reviewer
-> 输出 review_results.json
8. blocking issue 修复循环
9. 润色与排版
10. 调用 webnovel-data-agent
-> 输出 commit artifacts
11. chapter-commit
12. backup
```
核心不变：
- `context-agent` 负责写前 research 与任务书。
- `reviewer` 负责可验证问题。
- `data-agent` 负责事实提取与 artifacts。
- 主流程负责 orchestration、写正文、落库、恢复。
### 13.2 subagent 能力门槛
完整写章链要求：
- 至少支持顺序调用 subagent。
- subagent 能读取必要文件与运行必要查询命令。
- subagent 输出能返回主流程。
不要求：
- 必须并行 subagent。
- 必须独立工作目录。
- 必须持久 agent 会话。
### 13.3 single-agent 兼容模式
为低能力宿主预留 `--single-agent`，但默认不启用。
允许场景：
- 用户明确知道质量下降。
- 当前宿主不支持 subagent。
- 任务不是正式发布章节，或用户接受手动复查。
禁止场景：
- 默认 `/webnovel-write` 自动降级。
- 在未告知用户的情况下由主流程替代 reviewer/data-agent。
- 伪造 subagent 输出。
兼容模式输出必须标记：
```json
{
"compatibility_mode": "single-agent",
"missing_capability": "subagent",
"requires_manual_review": true
}
```
---
## 14. 安装与发布
### 14.1 版本同步
当前 `sync_plugin_version.py` 需要扩展，覆盖：
```text
webnovel-writer/.claude-plugin/plugin.json
webnovel-writer/.codex-plugin/plugin.json
webnovel-writer/.cursor-plugin/plugin.json
.claude-plugin/marketplace.json
.cursor-plugin/marketplace.json
README.md
dist manifest templates
```
命令保持：
```bash
python -X utf8 webnovel-writer/scripts/sync_plugin_version.py --version X.Y.Z --release-notes "..."
```
### 14.2 发布文档
新增：
```text
docs/operations/multi-harness-release.md
docs/guides/install-codex.md
docs/guides/install-cursor.md
docs/guides/install-gemini.md
docs/guides/install-opencode.md
docs/guides/install-copilot.md
```
README 快速开始保留 Claude Code 作为推荐路径，但增加：
```text
其他宿主安装：Codex / Cursor / Gemini CLI / OpenCode / Copilot
```
### 14.3 官方 marketplace 策略
优先级：
1. Claude Code marketplace：保持现状。
2. Codex plugin：补 `.codex-plugin/plugin.json`，后续申请目录。
3. Cursor plugin：补 `.cursor-plugin` marketplace。
4. Gemini/OpenCode/Copilot：先提供生成安装路径，成熟后再考虑原生发布。
---
## 15. 测试与验收
### 15.1 静态测试
新增测试：
```text
tests/harness/test_manifest_validity.py
tests/harness/test_skill_frontmatter.py
tests/harness/test_agent_frontmatter.py
tests/harness/test_portability_lint.py
tests/harness/test_generated_artifacts.py
```
检查：
- 所有 manifest JSON 合法。
- 所有 manifest 版本一致。
- 所有 `SKILL.md` 有 `name` / `description`。
- 所有 agent 有 `name` / `description` / `model`。
- agent 名称全局唯一。
- 新增 skill 不直接引用 `CLAUDE_PLUGIN_ROOT`。
- 新增 skill 不出现未解释的 Claude-only tool prose。
- `SKILL.md` 超过阈值时必须有 `references/`。
### 15.2 CLI 测试
新增：
```bash
python -X utf8 webnovel-writer/scripts/webnovel.py runtime-info --format json
python -X utf8 webnovel-writer/scripts/webnovel.py --project-root preflight --format json
python -X utf8 webnovel-writer/scripts/webnovel.py --project-root where
```
### 15.3 Harness smoke matrix
| 宿主 | 最低验收 |
|------|----------|
| Claude Code | 安装插件；`/webnovel-query` 查询 fixture；`/webnovel-review` 审查 fixture；`/webnovel-dashboard` 启动 |
| Codex | plugin 可读；skills 可列出；`webnovel-query` fixture 通过；`webnovel-review` full/compat 其中一种通过 |
| Cursor | plugin 可安装；skills/agents 可发现；`webnovel-query` 与 `webnovel-review` 通过 |
| Gemini | 生成 extension；`gemini extensions install ` 成功；`/webnovel-query` 或 command TOML 通过 |
| OpenCode | JS plugin 加载；skills 注册；`webnovel-dashboard` 或 query 通过 |
| Copilot | 生成 `.copilot` artifacts；skill/agent 可发现；query smoke 通过 |
### 15.4 写章验收
完整写章验收只要求在支持 subagent 的宿主上通过：
输入：
```text
使用 Webnovel Writer 写第 4 章。项目在 agents/evals/files/test-project/。
```
通过条件：
- 调用 `webnovel-context-agent`。
- 生成五段式写作任务书。
- 生成正文文件。
- 调用 `webnovel-reviewer`。
- `review_results.json` 存在且合法。
- 调用 `webnovel-data-agent`。
- 三份 commit artifacts 存在且合法。
- `chapter-commit` 成功。
- 不伪造 subagent 输出。
### 15.5 兼容模式验收
在不支持 subagent 的宿主：
输入：
```text
使用 Webnovel Writer 审查第 4 章。项目在 agents/evals/files/test-project/。
```
通过条件：
- 明确标记 compatibility mode。
- 输出同一 review JSON schema。
- 不声称调用了 subagent。
- 可落库或明确说明落库跳过原因。
---
## 16. 迁移计划
### Phase 1：原生 manifest 与环境变量兼容
目标：不改变业务流程，先让 Codex/Cursor 能发现 plugin。
改动：
- 新增 `.codex-plugin/plugin.json`
- 新增 `.cursor-plugin/plugin.json`
- 新增 `.cursor-plugin/marketplace.json`
- 新增 `hooks/session-start`
- 新增 `using-webnovel-writer`
- skill bash 片段开始迁移到 `WEBNOVEL_PLUGIN_ROOT`
验收：
- Claude Code 现有安装不破坏。
- Codex 能列出 skills。
- Cursor 能安装 plugin。
### Phase 2：Skill 瘦身与 Claude-only prose 清理
目标：让 skills 成为跨宿主入口。
改动：
- 拆分过长 `SKILL.md` 到 `references/protocol.md`
- 清理正文中的 `Read tool` / `Bash tool` / `Agent tool`
- 把 `Agent(...)` 示例移入 `claude-tools.md`
- 补 `codex-tools.md`、`gemini-tools.md`、`opencode-tools.md`
验收：
- portability lint 通过。
- 每个 skill 仍能在 Claude Code 中触发。
### Phase 3：Agent 命名与调度抽象
目标：agent 名称全局唯一，调度语义平台化。
改动：
- `context-agent` -> `webnovel-context-agent`
- `data-agent` -> `webnovel-data-agent`
- `deconstruction-agent` -> `webnovel-deconstruction-agent`
- `reviewer` -> `webnovel-reviewer`
- skill 正文使用“调用 subagent”语义
- adapter 支持旧名 alias
验收：
- Claude Code 中旧项目不破坏。
- 新 skill 全部使用新 agent 名。
- agent 名称无冲突。
### Phase 4：生成器与 Gemini/OpenCode/Copilot 产物
目标：生成宿主原生产物。
改动：
- 新增 `scripts/generate_harness_artifacts.py`
- 生成 Gemini extension root
- 生成 OpenCode `.opencode`
- 生成 Copilot `.copilot`
- CI 加 drift check
验收：
- `--target all` 成功。
- 生成产物可安装 smoke。
### Phase 5：端到端 harness 验收
目标：用真实宿主跑通核心任务。
验收顺序：
1. Claude Code：完整 init/query/review/write。
2. Codex：skills + query + review。
3. Cursor：skills/agents + query + review。
4. Gemini：generated extension + query。
5. OpenCode：plugin JS + dashboard/query。
6. Copilot：generated skills/agents + query。
---
## 17. 风险与决策
### 17.1 主要风险
| 风险 | 影响 | 缓解 |
|------|------|------|
| skill 过长导致宿主截断 | Codex/Gemini 行为不稳定 | `SKILL.md` 瘦身，references 渐进加载 |
| agent 调度语义不一致 | `webnovel-write` 链路断裂 | 平台 tool mapping + adapter + compatibility mode |
| hooks 需要用户信任 | bootstrap 不一定生效 | 不依赖 hooks 作为唯一入口 |
| plugin root 嵌套 | Gemini/OpenCode 安装复杂 | 生成 dist extension root |
| Python 依赖缺失 | scripts 失败 | preflight 明确诊断 |
| RAG API key 缺失 | init/write 部分能力不可用 | 按功能阻断，不影响 query/dashboard |
| 多份 manifest 版本漂移 | 发布混乱 | 扩展 version sync + CI |
| 旧 agent 名 shadowing | 调用错误 agent | 命名空间化 + alias 迁移 |
### 17.2 明确决策
1. Webnovel Writer 不把 Python CLI 改成 MCP。
2. Claude Code 仍是最佳体验路径。
3. Codex/Cursor 走原生 plugin manifest。
4. Gemini/OpenCode/Copilot 最终走生成产物。
5. `webnovel-write` 默认不在无 subagent 宿主自动降级。
6. `webnovel-review` 可以有 compatibility mode。
7. 所有新 agent 名必须带 `webnovel-` 前缀。
8. `CLAUDE_PLUGIN_ROOT` 不再作为新文档主变量。
---
## 18. 验收清单
最终完成时，必须满足：
- [ ] Claude Code 原安装流程不破坏。
- [ ] Codex manifest 存在且能加载 `skills/`。
- [ ] Cursor manifest 存在且能加载 `skills/` / `agents/`。
- [ ] Gemini dist 可生成并安装。
- [ ] OpenCode dist 可生成并加载 JS plugin。
- [ ] Copilot dist 可生成。
- [ ] `using-webnovel-writer` 存在并包含所有宿主 tool mapping。
- [ ] 所有 skill 使用 `WEBNOVEL_PLUGIN_ROOT` 兼容变量。
- [ ] 新增/改造后的 skill 正文不写死 Claude-only 工具名。
- [ ] 核心 agent 名称带 `webnovel-` 前缀。
- [ ] adapter 可生成 Codex/Gemini/OpenCode/Copilot 产物。
- [ ] CI 检查 manifest 版本一致。
- [ ] CI 检查生成产物 drift。
- [ ] fixture query 在至少 Claude、Codex、Cursor 三个宿主通过。
- [ ] fixture review 在至少 Claude、Codex/Cursor 其中一个非 Claude 宿主通过。
- [ ] 完整 write 多 agent 链在至少一个非 Claude 宿主通过，或明确标记为下一里程碑阻断项。
---
## 19. 后续可选方向
本 spec 完成后，可以继续评估：
1. 把 `webnovel.py` 暴露为 MCP server。
2. 为 Dashboard 增加 MCP / app connector。
3. 发布独立 Gemini extension 分支。
4. 发布 OpenCode npm plugin。
5. 增加 agent eval：同一 fixture 在 Claude/Codex/Gemini 输出结构一致性对比。
6. 增加写作质量跨模型 benchmark。
这些都不是本 spec 的前置条件。