它实际做的是三件事
非开发者第一次打开 Claude Code，会卡在三个地方。答案里的术语不认识；答案太长，不知道先做什么；而当一条命令要粘进终端时，手会停下来，因为担心有些事会变得无法撤回。novice 用三个彼此独立的层分别处理这三件事。
学习层处理术语。commit、branch 这类词原样写出，后面用括号补上含义，等同一个术语在本次会话里出现得够多，释义就被悄悄撤掉。一开始每次都跟着的括号，到某个时刻就不见了。
focus 处理答案的形状。打开后第一行会变成可以直接执行的命令或路径，超过一步就变成编号清单，开场白和结束语被禁止。它和等级是各自独立的开关，所以把 novice 设为 off，focus 仍然照常工作。
安全闸门处理命令，但方向和一般预期相反。它只拦截确定具有破坏性且不可逆的操作，其余一概不作判断。为什么这样设计，下面单独写了。
在此之上还有外部服务 CLI 引导。像 Vercel 或 GitHub CLI 的安装与登录过程，会逐步取得同意后替你走完。边界很明确：创建账号、填入数值、执行部署，都由用户自己做。
安装 — marketplace 与 npm 是两条独立路径
推荐路径是 marketplace。在 Claude Code 运行的状态下，依次输入下面三行。这是在 Claude Code 里输入的命令，不是在终端里。
/plugin marketplace add hjsh200219/novice
/plugin install novice@novice
/reload-plugins确认装好了没有，以及以后怎么更新
确认分两步。先看 `/plugin` 列表里 novice 是不是 enabled，再执行 `/novice`，出现状态面板就说明正常。面板里会一并显示当前等级、学习层状态、安全闸门是否生效，以及 mute 列表。
这里有一个所有人都会踩一次的坑。装上的是缓存副本而不是原件，不会自动更新。新版本发布了，旧版本还会悄悄继续跑。要在 `/plugin` 菜单里更新 novice marketplace，然后重新安装插件。
卸载是 `/plugin uninstall novice`。卸载会连同学习层一起把安全闸门也拿走。所谓 always-on，只在插件启用期间才有意义。
除了 GitHub 简写，git URL 或本地克隆路径也能用同一条命令注册，例如 `/plugin marketplace add https://github.com/hjsh200219/novice.git`。
用 npm 安装 — 同一个插件，不同的投递方式
novice 也以 `claude-novice` 的名字发布在 npm 上，是与 marketplace 版本同步递进的另一条通道。marketplace 安装是从 GitHub 仓库树取，这一条是从 npm registry 取。适合用在代理或防火墙挡住 GitHub 访问的环境，或者像 CI 镜像那样 npm 本来就是标准投递方式的场合。
最简单的形式是全局安装后直接加载进会话。这些命令是在终端里敲的，不是在 Claude Code 里。
npm install -g claude-novice
claude --plugin-dir "$(npm root -g)/claude-novice"{
"name": "novice",
"source": { "source": "npm", "package": "claude-novice" }
}两条路径怎么选
个人环境里，marketplace 的三行是最短的做法。不用离开 Claude Code，也不用操心 npm 或 Node 版本。
npm 路径用于两种情况：GitHub 直连被挡住的环境，以及想把版本钉住的时候。在自建 marketplace 条目的 source 里写上 `version`，就会停在那个版本而不再跟随最新。如果需要预先塞进容器或 CI，可以用 `CLAUDE_CODE_PLUGIN_SEED_DIR` 在构建镜像时把插件缓存埋进去。
只想在本次会话里试一下而不安装，可以用 `claude --plugin-dir <克隆路径>`，会话结束就消失。只测一次托管的 ZIP，则用 `claude --plugin-url <ZIP 地址>`。
有一件事不能做：只把技能文件手工复制到 `~/.claude/skills/` 是不被支持的。那样技能会加载，但 hook 不会加载，于是安全闸门和学习层都不工作。看起来装好了，实际上毫无防护。
在团队里铺开 — 队友不需要学任何命令
让非开发者队友先学会 `/plugin` 命令，本身就已经是门槛。所以另有一条路径：把下面这段提交到工作仓库的 `.claude/settings.json`，那么凡是信任该仓库的人，Claude Code 都会主动建议安装 novice。
{
"extraKnownMarketplaces": {
"novice": { "source": { "source": "github", "repo": "hjsh200219/novice" } }
},
"enabledPlugins": { "novice@novice": true }
}为什么不把术语换成通俗说法
入门工具通常的做法是把难词去掉。把 commit 叫作保存，把 branch 叫作副本，当下确实轻松。问题出现在这个人开始搜索的那一刻——搜保存什么也搜不到。
novice 走相反的方向：原样写出真正的术语，后面补上含义。下面是实际输出的样子。
commit（把当前改动记录为一个保存点）完成 — 记录了 3 个文件。等级 1、2、3、off — 释义会跟你多久
等级决定的不是解释多少，而是解释什么时候撤掉。默认是 1，用 `/novice:mode 2` 切换。当整条提示词正好是 `novice 2` 时，效果相同。
off 只关掉学习层。语气、解释、可视化都会消失，安全闸门照旧运行。这部分也无法用配置关掉——即便把插件设置里的 `novice_enabled` 关掉，闸门仍然工作。
| 等级 | 释义附着的范围 | 什么时候用 |
|---|---|---|
| 1（默认） | 所有术语都附释义，执行前后都有解说。同一术语在会话中出现 3 次后释义撤掉 | 刚打开的那天 |
| 2 | 最多解释 3 次，只解说关键决策 | 术语眼熟了但流程还陌生 |
| 3 | 只在请求时解释，以架构与用户流程为主 | 想专注在做什么上 |
| off | 完全移除学习层（安全闸门保留） | 已经熟悉，或要给别人看屏幕 |
mute 与 reset — 哪些是会话级，哪些是项目级
对已经懂的术语还附着解释，那就是噪音。所以有按术语开关的命令。只有整条提示词完全一致时才生效，仅容忍首尾空白和一个句号。像“说得再简单点”这样的普通句子只影响当前这次回答，不改变任何设置。
reset 与 mute 方向相反。reset 把计数器归零，于是这个术语会再被解释 N 次；mute 则立刻停止解释并一直停着。
存储范围也不同。mute 按项目保存，换了会话仍然有效；reset 和术语计数器是会话级的。术语也可以用韩文别名指定，`novice mute 커밋` 是同一个意思。词表里没有的术语会被直接忽略。
| 命令 | 行为 | 范围 |
|---|---|---|
| `novice mute commit` | 从现在起永久停止解释该术语 | 项目（跨会话保留） |
| `novice unmute commit` | 解除 mute — 重新按淡出规则来 | 项目 |
| `novice reset commit` | 该术语计数器归零 — 再解释 N 次 | 会话 |
| `novice reset all` | 重置所有术语计数器 | 会话 |
focus — 答案变长时打开的形状规则
这是 0.4.0 加上的拨盘，用 `/novice:focus on` 打开。它针对的是答案又长又准确、却仍然不知道先做什么的那种情形。
打开后会强制十条规则。第一行必须是可以直接执行的行动、命令或路径，背景放在后面。超过一步就要用编号清单，一项只放一个动作。还有事情没做完时，末尾要给出一个两分钟内能完成的下一步。旁枝被抑制，第二个问题要等第一个问题结束后再单独提出。并且每一轮都重新写一遍当前状态，比如“五步中已完成三步”。
另外五条是：时间估计要用具体单位；做完的事要以现在能做什么来呈现；错误只平实地写原因和修法；清单不超过五项；禁止开场白、事后总结和结束语。以“好问题”开头、以“希望有帮助”结尾的回答会消失。
规则里还写明了六种例外。要求解释的请求要写够长；破坏性操作前先确认；连续三轮“还是不行”时停止改代码，转而指出可能错误的前提。当规则会把答案本身抹掉时，答案优先——对“有哪些选择”只给一条路，那不是守规则，而是没回答。
focus 与等级是各自独立的拨盘。在 `novice off` 状态下它照样工作，关掉 focus 也不影响等级指令。两者冲突时 focus 胜出，唯独术语括号释义保留，因为 `commit(…)` 是行内的，不是开场白。想在所有项目里默认打开，把插件设置的 `focus_default` 设为 true；按项目的 `/novice:focus off` 优先级更高。
规则体系本身不是原创，取自 ayghri/i-have-adhd（MIT）并译为韩文。原作面向 ADHD 读者写成，而那些条件与入门者面对长答案时的处境重叠：工作记忆小，事情死在“知道”与“做到”之间的落差里，以及起步是最难的一步。
安全闸门把拦什么和不拦什么分开写清楚
这是整个插件里写得最谨慎的部分。安全功能容易被夸大，而被夸大的安全功能不如没有。所以 README 里专门有一节明确的不保证事项，这里也照搬一遍。
闸门是最小的 deny-only 内核。只拦截被正面识别出来的不可逆破坏性操作和暴露的密钥值；凡是解析不了或拿不准的命令，一律不作判断，交给 Claude Code 自己的权限提示。
| 威胁 | 拦截 | 不拦截（交给原生权限） |
|---|---|---|
| 本地破坏性命令 | `rm -rf ~`、`/`、项目根目录，`dd`/`mkfs`/`shred`，PowerShell `Format-Volume`/`Clear-Disk` | 复杂的 wrapper 选项、混淆、带管道与链式与替换的命令、删除普通文件夹 |
| Git 历史破坏 | 针对受保护分支的 `push --force` | 对非保护分支 force-push，`reset --hard`，`clean`，在其他 Git 客户端里的操作 |
| 远程资源删除 | 针对 production 或未知目标的破坏性操作（CLI、MCP） | staging 与 dev 目标，直接在外部控制台里做的操作 |
| 密钥泄露 | 在待提交树、部署参数、命令行中发现的密钥值 | 不支持的格式，加密或混淆过的值，无法扫描的超大文件 |
| 成本循环 | 每批最多介入一次 | 精确的计费核算，硬性消费上限 |
为什么去掉了确认询问层
最初的版本里有确认步骤：遇到拿不准的命令就弹出询问，问是否真的执行。听上去很安全。
实际结果相反。闸门并不解析管道或 `&&` 这类语法，于是像 `find . | sort` 或 `npm run build && npm test` 这种毫无问题的命令，每次都会弹确认。确认弹得多了，人就不读直接点。然后在真正危险的那一刻，也不读直接点。当警报频繁到被无视时，这个安全装置就在削减安全。
所以 0.2.0 把确认层整个去掉了。现在只拦确定的，拿不准就干脆不发表意见，那块位置交给 Claude Code 自己的权限规则。这个选择有明写的代价：带管道的破坏性命令 novice 抓不到。把抓不到这件事写进文档，比装作抓得到要好。
其他不保证的事项也都写了下来。它不是通用 shell 解析器，不是完整的 DLP，不是密钥管理器，也不是针对恶意 MCP 的防御，检测只基于已知模式。在用户已承担全部风险的 `bypassPermissions` 模式下，闸门完全退场。Git 只保护被追踪的本地文件，未被追踪的文件、外部数据库、已部署的资源都不在其恢复范围内。
外部服务能替你做到哪一步
真正让入门者卡最久的不是代码，而是账号和 CLI。要部署到 Vercel 就得装 CLI，装 CLI 就得知道包管理器，登录又要在浏览器和终端之间来回。novice 把这一段做成状态机来走。
自动化边界固定成一句话：探测、安装、执行登录、确认认证状态。再往后就不做了。创建与连接资源、填入 env 或密钥值、部署、付费、同意条款，这些会逐步说明做什么、为什么、用哪条命令，然后由用户自己执行。
CLI 分成两层。Tier 1 是随仓库附带、事先审阅过的 manifest，目前是 Vercel、GitHub CLI 和 Supabase，安装与登录各取得一次同意，按固定的包坐标执行。Tier 2 是其余所有 CLI：把官方文档 URL、包坐标和实际要执行的命令行原样显示在屏幕上，只有用户核对依据并同意后，才用同一套引擎继续。若无法确认官方出处，就降级为只做指引的手动路径。
如果拒绝安装 CLI 或前置检查失败，路径会逐级下降：CLI，然后是官方或已同意的 MCP，再是可见的 Chrome 操作，最后是只做指引的手动。MCP 只在两种情况下使用——事先审阅过的 allowlist 条目，或者用户已在 Claude 中注册且针对本次任务明确同意的服务器。默认 allowlist 是空的，并且不会自动安装 MCP 服务器。
任何路径上都不请求、不保存、不转发、不自动填入凭据值。当支持安全存储的 CLI 在某环境下退化为明文保存时，自动登录会直接中止；而以文件保存为官方默认行为的 CLI，会在批准登录之前先告知保存位置和登出路径。
什么留在哪里，什么绝不外发
状态只保存在 `CLAUDE_PLUGIN_DATA` 之下，插件安装目录里什么都不写。保存的内容是按项目的设置和按会话的术语计数器。
状态文件采用原子写入、权限 0600、拒绝符号链接，并有大小上限。会话状态在 `/clear` 时删除，30 天后过期。
密钥扫描器只在内存中检查候选字节，不会把原文留在日志、状态或指标里。引导流程的审计记录只保留服务 ID、manifest 修订号、步骤和退出状态。
不发送远程 telemetry。这个插件没有服务器、没有 cron、也没有部署平台。
目前的状态，以及还有什么没被验证
当前是 0.4.0。运行时零外部依赖，需要 Node 18 以上，测试 195 项全部通过。最低支持运行时是 Claude Code 2.1.215。
安全闸门不只靠测试，还有变异测试作为验证：把 35 条危险命令变形成 106 个变体，确认没有绕过检测的路径。延迟同样被写成回归测试——因为这些 hook 会阻塞用户输入，p95 预算被强制为 UserPromptSubmit 300 毫秒、PreToolUse 250 毫秒。focus 另有一套 eval，包含 16 个用例和 13 种确定性形状检查。
无法用代码验证的部分也一并写下。真实的 CLI 安装与登录全流程需要用户的环境和账号；破坏性 MCP 的负载无法在无界面环境下复现；而最关键的一点——人是否真的少卡壳，只有有参与者时才能测。现在是先在团队内部使用、收集卡点的阶段。
所以这篇更像是分享而不是发布。如果你有把 Claude Code 交到非开发者手里的场合，先试一试并告诉我在哪里卡住了，在现阶段是最有用的。
原始仓库（MIT）：github.com/hjsh200219/novice · npm：claude-novice