Ana Sayfa Keşfet Yardım
Üye Ol Giriş Yap
haiany
/
webnovel-writer
şunun yansıması https://github.com/lingfengQAQ/webnovel-writer.git
1
0
Çatalla 0
Dosyalar Sorunlar 0 Wiki
Ağaç: a1c19456b5
Dallar Biçim İmleri
webnovel-writer
/
docs
/
architecture
/
phase0-tool-and-registration-audit-2026-06-06.md

phase0-tool-and-registration-audit-2026-06-06.md 17 KB
Geçmiş Ham

Phase 0 审计：工具能力与插件注册名（2026-06-06）

只读审计。本文件只「记录证据」，不修改任何 skill / agent / plugin.json / 测试文件。 目的：为 context-minimal-writing-flow-plan 提供可信的运行基线，复核计划中假设的 webnovel-writer:<agent> 注册名、agent/skill frontmatter、以及计划依赖的官方工具行为结论。

工作目录（git 仓库根 = worktree）：D:/wk/novel skill/webnovel-writer/.worktrees/context-minimal-flow 插件目录（嵌套）：仓库根下的 webnovel-writer/ 子目录。

1. Claude Code 版本与环境

项 值 证据
宿主 Claude Code（固定，本插件唯一目标宿主） —
claude --version 2.1.161 (Claude Code) Bash 直接执行成功（非「subagent 不可用」）
平台 Windows（win32），PowerShell + Bash 双可用 环境说明
本审计执行体 subagent（Task 1）；本机 claude --version 可正常返回 —

结论：版本/环境均可确认，无降级记录。

2. 插件注册（真实名）

2.1 plugin.json

文件：webnovel-writer/.claude-plugin/plugin.json（全文 18 行）。

{
  "name": "webnovel-writer",
  "version": "6.1.0",
  "description": "长篇网文创作系统（skills + agents + data chain + RAG）",
  "author": { "name": "lingfengQAQ" },
  "homepage": "https://github.com/lingfengQAQ/webnovel-writer",
  "repository": "https://github.com/lingfengQAQ/webnovel-writer",
  "license": "GPL-3.0",
  "keywords": ["webnovel", "claude-code", "skills", "agents", "rag"]
}
  • 插件名（namespace 前缀来源）：webnovel-writer。
  • manifest 没有显式 agents / skills / commands 路径数组。 → 因此 agents 与 skills 全部走约定式 auto-discovery：
    • 官方 plugin-structure/SKILL.md:11 —「automatic component discovery」；
    • 同文件第 28-32 行：agents/（.md 文件）与 skills/（子目录，每个含 SKILL.md）。
    • 官方 skill-development/SKILL.md:271-273 —「Claude Code automatically discovers skills: Scans skills/ directory; Finds subdirectories containing SKILL.md」。

2.2 真实 on-disk agent 名（4 个）

每个 agent 是单一 .md 文件，frontmatter name: 与文件名（去 .md）一致：

文件 frontmatter name: (行 2) 一致？
webnovel-writer/agents/context-agent.md context-agent ✅
webnovel-writer/agents/data-agent.md data-agent ✅
webnovel-writer/agents/deconstruction-agent.md deconstruction-agent ✅
webnovel-writer/agents/reviewer.md reviewer ✅

另有 webnovel-writer/agents/evals/（含 evals.json + files/）——非 agent 定义，是评测夹具，auto-discovery 不会把它当 agent（不是顶层 .md）。无 agents/references/ 目录。

2.3 真实 on-disk skill 名（8 个）

每个 skill 是含 SKILL.md 的子目录，frontmatter name:（均在行 2）与目录名一致：

目录 frontmatter name: 一致？
skills/webnovel-write/ webnovel-write ✅
skills/webnovel-init/ webnovel-init ✅
skills/webnovel-plan/ webnovel-plan ✅
skills/webnovel-review/ webnovel-review ✅
skills/webnovel-query/ webnovel-query ✅
skills/webnovel-learn/ webnovel-learn ✅
skills/webnovel-dashboard/ webnovel-dashboard ✅
skills/webnovel-doctor/ webnovel-doctor ✅

（路径前缀省略 webnovel-writer/。）

2.4 注册名 ↔ 计划引用名 复核（关键）

计划 docs/architecture/context-minimal-writing-flow-plan-2026-06-05.md 在多处用 webnovel-writer:<agent> 形式引用 4 个 agent，例如：

  • L181 必须调用 webnovel-writer:context-agent
  • L195 ... webnovel-writer:reviewer
  • L228 ... webnovel-writer:data-agent
  • L97 ... webnovel-writer:deconstruction-agent
  • L463/L698/L713/L728 Use the Agent tool to run webnovel-writer:context-agent 等
  • L430 计划自带告警：「plugin scoped agent 的真实注册名必须在 Phase 0 复核」（即本节）。

复核结论：

  • on-disk agent 名 = context-agent / data-agent / deconstruction-agent / reviewer， 与计划里冒号后半段完全一致，无错名。
  • 关于前缀：官方 agent-development/SKILL.md:281-285「Namespacing」原文：
    • 「Agents are namespaced automatically: Single plugin: agent-name; With subdirectories: plugin:subdir:agent-name」。
    • 即官方文档把「单插件、无子目录」的 agent 标识写作裸名 agent-name，把带前缀的形态留给「子目录」场景（plugin:subdir:agent）。
    • 命令侧旁证：command-development 与 plugin-features-reference.md:30 显示插件组件在 /help 里带 (plugin:plugin-name) 标签，说明「插件名:组件名」是 marketplace 场景下的实际可见限定形态。
    • ⚠️ 轻微风险（命名形态，非错名）：官方 agent-development 文档对「单插件无子目录」给出的范式是裸 agent-name，并未把 plugin:agent（无 subdir）列为 canonical 形态。计划统一用 webnovel-writer:context-agent 这类带插件前缀、无 subdir 的写法，是合理且更显式的（在多插件并存时消歧），但官方文档没有把这一形态写成单插件的标准范式。
    • 建议：Phase 1 真正接线时，以运行时实测（Agent/Task 工具能否用 webnovel-writer:context-agent 解析到该 agent）为准；若实测裸名 context-agent 才解析得到、带前缀失败，则按裸名修正计划。本审计无法在 subagent 内实跑 Agent 工具来终判，故标注为「待运行时验证」。

3. Agent frontmatter 审计（4 个）

逐项抄录 frontmatter（行号以各文件为准；所有 4 个 agent 的 frontmatter 块均为第 1-7 行）：

agent name description（摘） model color tools
context-agent context-agent 写前 research，输出写作任务书。 inherit blue Read, Grep, Bash
data-agent data-agent 从正文提取事实，生成 commit artifacts。 inherit green Read, Write, Bash
deconstruction-agent deconstruction-agent /webnovel-init 的参考书拆解子代理…… inherit purple Read, Grep, Bash
reviewer reviewer 统一审查 agent。逐维度检查…… inherit yellow Read, Grep, Bash

对照 agent-development 规则：

  • 单一 .md 文件：✅ 全部满足。
  • 必备字段 name/description/model/color：✅ 4 个全齐。
    • model: inherit 符合官方推荐（agent-development/SKILL.md:100,105）。
    • color 取值：blue/green/purple/yellow。⚠️ 官方 agent-development/SKILL.md:111 列出的合法色为 blue, cyan, green, yellow, magenta, red，未列 purple。deconstruction-agent 的 color: purple 不在官方枚举内（应为 magenta）。属轻微规范偏差，不影响功能/注册（color 仅 UI 着色）。
  • tools 最小集：✅ 都是 3 个工具的小集合（least privilege，符合 SKILL.md:134）。
  • FLAG：tools 含 Agent 或 AskUserQuestion？ → ❌ 均不含。 4 个 agent 的 tools 仅为 {Read, Grep/Write, Bash} 组合，没有任何一个带 Agent/AskUserQuestion/Task。 → 与计划「subagent 不得用 Agent/AskUserQuestion」一致，无违例。
  • FLAG：缺必备 frontmatter 字段？ → 无。4 个 agent 字段齐全。
  • FLAG：依赖外部 agents/references/* 当隐藏手册？ → 无。agents/references/ 目录不存在； 4 个 agent 正文未引用 agents/references/...。（注：正文大量引用 ${SCRIPTS_DIR}/webnovel.py 子命令， 那是运行时脚本调用，不是「隐藏 manual 文件」。）
  • skills: frontmatter 字段？ → 4 个 agent 均无 skills: 字段（Grep ^(name|skills): 仅命中 name:）。即当前没有任何 agent 预载 Skill 内容。

4. Skill frontmatter 审计（8 个）

逐项抄录（name/allowed-tools 行号见下；所有 skill name: 均在行 2）：

skill name description 触发型 allowed-tools
webnovel-write webnovel-write 产出可发布章节，完整执行上下文→起草→审查→润色→提交→备份。 Read Write Edit Grep Bash Agent AskUserQuestion
webnovel-init webnovel-init 深度初始化网文项目。分阶段交互收集…… Read Write Edit Grep Bash Agent AskUserQuestion WebSearch WebFetch
webnovel-plan webnovel-plan 基于总纲生成卷纲、时间线和章纲…… Read Write Edit Bash AskUserQuestion
webnovel-review webnovel-review 使用审查 Agent 评估章节质量…… Read Grep Write Edit Bash Agent AskUserQuestion
webnovel-query webnovel-query 查询项目设定、角色、力量体系、势力、伏笔…… Read Grep Bash
webnovel-learn webnovel-learn 从当前会话提取成功模式并写入 project_memory.json Read Bash
webnovel-dashboard webnovel-dashboard 启动只读小说管理面板…… Bash Read
webnovel-doctor webnovel-doctor This skill should be used when the user asks to "/webnovel-doctor", "检查项目环境"…… Read Bash

对照 skill-development 规则：

  • 目录 + SKILL.md 结构：✅ 8 个目录均含 SKILL.md（逐一 test -f 通过）。
  • frontmatter 含 name + 触发型 description：✅ 全部有 name + description。
    • 官方只强制 name + description（skill-development/SKILL.md:33-34）。
    • 触发表述：7 个用中文动作/场景式触发短语（计划偏好），webnovel-doctor 用英文官方范式 「This skill should be used when…」并把中文触发词内嵌其中——两类都满足「具体触发」要求。
    • webnovel-doctor 还带 version: 0.1.0（额外字段，无害）。
  • allowed-tools 是否存在及其值：✅ 8 个 skill 全部声明了 allowed-tools（值见上表）。
    • 4 个编排型 skill（write/init/plan/review）的 allowed-tools 含 Agent（write/init/review） 与 AskUserQuestion（write/init/plan/review）——这是顶层 skill / 命令层用来「预批准」调度子代理 与向用户提问的工具集，不是 subagent 的 tools。与计划角色分工（编排在 skill 层、执行在 agent 层）一致。
    • 只读型 skill（query/learn/dashboard/doctor）的 allowed-tools 收敛为 Read/Bash(/Grep)，无 Agent/AskUserQuestion。

说明：官方 skill-development/SKILL.md 通篇未出现 allowed-tools 字段名（仅强制 name+description）。 因此「allowed-tools 是预批准而非限制」这一语义无法从本地官方 skill 文档直接证实，见 §5。

5. 计划依赖的官方工具行为结论（运行基线）

交叉核对源（实际使用路径）： C:/Users/lcy/.claude/plugins/marketplaces/claude-plugins-official/plugins/plugin-dev/skills/ （primary 路径存在；fallback .tmp/plugin-dev-official/... 不存在，未使用）。 核对的三个 skill：agent-development/、skill-development/、plugin-structure/（含其 references/、examples/）。

逐条结论与本地可证实性：

# 计划依赖的结论 本地官方文档可证实？ 证据 / 标注
(a) subagent 不能再生成另一个 subagent ❌ 未找到 在 plugin-dev 全树 Grep spawn / another (sub)?agent / nested / recursi 仅命中 MCP 进程「spawn」，无 subagent 嵌套禁令条文。→ 「计划断言，本地未证实」。（与之相容的旁证：command-development/SKILL.md:720「Claude uses Task tool to launch agent」——launch agent 是上层/命令侧动作；官方未给出 subagent 自身可再调 Task 的任何示例，但「未给出」≠「明文禁止」。）
(b) Agent / AskUserQuestion 不作为 subagent 的 tools ⚠️ 部分（间接） 官方 agent tools 文档（agent-development/SKILL.md:122-140）给的「常用 tool set」全是 Read/Write/Grep/Glob/Bash，从不把 Agent/AskUserQuestion 列进 agent 的 tools。AskUserQuestion 出现处均在命令/skill 层的 allowed-tools（plugin-dev/commands/create-plugin.md:12、plugin-settings/examples/create-settings-command.md:3），不在任何 agent frontmatter。→ 官方惯例支持该结论，但无一句明文「禁止」。标注为「官方惯例支持，无明文禁令」。本仓 4 个 agent 实测也无人含 Agent/AskUserQuestion（§3）。
(c) tools / disallowedTools 控制 subagent 工具边界 ⚠️ 一半 tools 控制边界：✅ 明文——agent-development/SKILL.md:124「Restrict agent to specific tools」、:132「If omitted, agent has access to all tools」、:134 least-privilege。disallowedTools：❌ 在 plugin-dev 全树 Grep 无任何命中。→ tools 部分「本地已证实」；disallowedTools 部分「计划断言，本地未证实」。
(d) agent skills: frontmatter 会把整份 Skill 内容预载进 subagent ❌ 未找到 官方 agent frontmatter 文档只列 name/description/model/color/tools（SKILL.md:122 区段 + :340-342 表），无 skills: 字段说明；全树 Grep skills:（agent 语境）无命中。→ 「计划断言，本地未证实」。当前本仓也无 agent 使用该字段（§3），故即便成立也属「未来才会用到」的能力。
(e) Skill 的 allowed-tools 是预批准、不是限制 ❌ 未找到 skill-development/SKILL.md 全篇无 allowed-tools 字样；官方只把 allowed-tools 用在命令 frontmatter（command-development / plugin-settings 示例）。其「预批准/非限制」语义在本地官方文档中无直接定义。→ 「计划断言，本地未证实」。（注：经验上 skill/command 的 allowed-tools 行为确为预批准，但本审计按要求不凭记忆造引用，仅据本地文档判定为「未证实」。）

补充已证实的注册/调度事实（支撑计划接线）：

  • 自动发现：agents 扫 agents/*.md、skills 扫 skills/*/SKILL.md（plugin-structure/SKILL.md:11,28-32；skill-development/SKILL.md:271-273）。✅
  • agent 命名空间：单插件裸名 agent-name，带子目录 plugin:subdir:agent-name（agent-development/SKILL.md:283-285）。✅
  • 上层用 Task 工具 启动 agent（command-development/SKILL.md:720）。✅

6. 结论 / 风险清单

与计划假设一致的部分（无阻断）

  1. 4 个 agent 的 on-disk 名（context-agent / data-agent / deconstruction-agent / reviewer）与计划 webnovel-writer:<agent> 引用的冒号后半段完全一致，无错名、无缺失。
  2. 8 个 skill 目录名与各自 name: 一致，结构合规（目录 + SKILL.md，name + 触发型 description）。
  3. 没有任何 agent 的 tools 含 Agent / AskUserQuestion / Task → 计划「subagent 不持调度工具」的红线 在现状下已天然满足，无需先修。
  4. 没有 agent 缺必备 frontmatter 字段；没有 agent 依赖 agents/references/* 隐藏手册（该目录不存在）。
  5. 没有 agent 使用 skills: 预载字段（即 (d) 即便成立，也不会与现状冲突）。
  6. 8 个 skill 均显式声明 allowed-tools，且编排型/只读型分工与计划角色划分吻合。

会动摇计划假设的风险点（需后续处理 / 实测）

  • R1（命名形态，待运行时验证）：官方 agent-development 文档把「单插件无子目录」agent 的 canonical 标识写成 裸 agent-name，未把 plugin:agent（无 subdir）列为标准范式。计划统一用 webnovel-writer:context-agent 这类带前缀写法。名字本身没错，但前缀形态能否被 Agent/Task 工具解析到，需 Phase 1 运行时实测确认； 若实测仅裸名可解析，应回改计划为裸名。本审计（subagent 内）无法实跑 Agent 工具终判。
  • R2（工具行为，本地未证实——见 §5）：计划依赖的 (a) subagent 不能再开 subagent、(d) agent skills: 预载整份 Skill、(e) skill allowed-tools 为预批准——这三条在本地官方 plugin-dev 文档中找不到出处；(c) 的 disallowedTools、(b) 的「明文禁止」也无出处。这些应作为「计划断言、本地未证实」对待： 计划据此设计无妨，但任何「以 skills: 预载替代 reference 大块文本」「靠 subagent 链式分发」的关键改动， 应在实现期以小样例实测，不能仅以官方文档为据。
  • R3（轻微规范偏差，不阻断）：deconstruction-agent 的 color: purple 不在官方合法色枚举 （blue/cyan/green/yellow/magenta/red）内。仅 UI 着色，无功能影响；如要严格合规，应改 magenta。 本审计为只读，不修改。

一句话总览

注册名与 frontmatter 现状与计划高度一致、无错名、无 Agent/AskUserQuestion 违例；唯一需在实现期落实的是 R1 的 webnovel-writer:<agent> 前缀形态运行时实测 与 R2 中那几条「本地未证实」的工具行为以实测兜底。