i-have-adhd扩展API全解registerFlag、registerCommand与on(input)实战【免费下载链接】i-have-adhdA skill to stop your coding agent from burying the answer. ADHD-friendly output.项目地址: https://gitcode.com/GitHub_Trending/ih/i-have-adhdi-have-adhd 是一款让编码 Agent 输出ADHD 友好回复的技能插件——答案先行、步骤编号、没有废话开头。本文带你拆解它的 Pi 扩展 APIregisterFlag、registerCommand与on(input)三个核心接口的实战用法全部实现就在 extensions/i-have-adhd.ts 一个文件里约 220 行是学习 Agent 扩展开发的上佳样本。先认识 i-have-adhd 扩展规则与行为的分工这个项目把内容和行为拆开了文件职责skills/i-have-adhd/SKILL.md10 条 ADHD 友好输出规则内容extensions/i-have-adhd.tsPi/OMP 运行时扩展负责开关、命令、拦截行为extensions/context-compat.ts上下文探测工具判断规则是否还活着package.json声明pi.extensions入口Pi 靠它发现扩展扩展启动时先读取 SKILL.md 正文去掉 frontmatter然后在 Pi 提供的扩展 API 上挂三样东西一个启动标志、一个斜杠命令、一组事件监听。下面逐个拆解。registerFlag 实战一行--adhd启动开关pi.registerFlag(adhd, { description: Start with ADHD-friendly output enabled, type: boolean, default: false, });这段代码注册了一个布尔型 CLI 参数extensions/i-have-adhd.ts#L163-L167。注册后用户启动 Pi 时就能带上参数pi --adhd扩展内部再用pi.getFlag(adhd)读回它的值决定新会话是否默认开启 ADHD 模式。它与一个常驻标志文件互为兜底pi.getFlag(adhd) true→ 本次启动显式开启existsSync(alwaysOnFlag)→ 检测到~/.pi/agent/.i-have-adhd-always空文件等于每次默认开启。要点registerFlag只负责声明 默认值真正的使用发生在session_start恢复状态时两个时机分离是这类扩展的常见模式。registerCommand 实战/i-have-adhd会话级开关pi.registerCommand(i-have-adhd, { description: Toggle ADHD-friendly output for this session, handler: async (args, ctx) { /* 解析 on/off 参数 */ }, });注册后用户在对话框输入/i-have-adhd即可切换模式。handler 的参数解析很简单extensions/i-have-adhd.ts#L169-L191输入行为/i-have-adhd不带参数翻转当前状态开→关、关→开/i-have-adhd on显式开启/i-have-adhd off/stop显式关闭其他参数弹出用法提示Usage: /i-have-adhd [on\|off]切换时做的三件事值得注意pi.appendEntry(STATE_ENTRY_TYPE, { enabled })—— 把开关状态写入会话分支重开会话能恢复ctx.ui.setStatus(STATUS_KEY, ● ADHD ON)—— 在底部状态栏打上绿色标记ctx.ui.notify(...)—— 弹一条 ADHD mode enabled/disabled 通知。要点registerCommand提供的是确定性入口用户随时能精确控制模式这比让模型自己决定何时切换更可靠。on(input) 实战拦截用户输入做关键词魔法on(input)是扩展监听用户每条输入的机会返回不同的 action 决定这条输入的命运pi.on(input, async (event, ctx) { const input event.text.trim().toLowerCase(); if (input /skill:i-have-adhd) { setEnabled(true, ctx); return { action: handled }; // 拦截不发给模型 } if (enabled STOP_PHRASES.has(input)) { setEnabled(false, ctx); if (ctx.hasUI) return { action: handled }; return { action: transform, text: Reply with exactly: ADHD mode disabled. }; } return { action: continue }; // 放行正常处理 });三种返回值各有用途extensions/i-have-adhd.ts#L193-L217返回值效果本项目的用法{ action: handled }输入被吞掉模型完全看不到把/skill:i-have-adhd当作开启别名避免规则被重复注入{ action: transform, text }替换成指定文本再发给模型无 UI 环境下把stop adhd mode改写为只回复确认句{ action: continue }原样放行绝大多数输入最巧妙的地方是自然语言停止词用户直接输入stop adhd mode或normal mode不是斜杠命令也能关闭模式。停止词集合就一行new Set([stop adhd mode, normal mode])。会话事件与上下文同步保证规则永远在场除了input扩展还监听了三个会话事件pi.on(session_start, async (_e, ctx) restoreState(ctx)); pi.on(session_tree, async (_e, ctx) restoreState(ctx)); pi.on(session_compact, async (_e, ctx) syncContext(ctx));session_start / session_tree新会话、恢复或分叉时从分支历史读回保存的开关状态必要时把规则注入对话session_compact会话压缩会丢掉已总结的旧消息此时检测规则是否还在上下文里不在就重新注入。规则是否还在的判断在 extensions/context-compat.ts 中contextMessages()兼容探测不同运行时的 sessionManager API探测失败时安全降级为不在宁可重复注入也不破坏启动latestMarkerIsActive()只看最新一个标记——后出现的 disabled 通知可以覆盖之前的规则集。注入本身用pi.sendMessage完成display: false保证用户看不见这条规则消息triggerTurn: false保证不会触发模型额外回复。核心 API 速查表API作用本项目用途pi.registerFlag(name, opts)注册 CLI 启动参数--adhd布尔开关pi.getFlag(name)读取标志值判断本次启动是否默认开启pi.registerCommand(name, opts)注册斜杠命令/i-have-adhd [on\|off]pi.on(input, handler)拦截用户输入停止词关闭、skill 命令别名pi.on(session_start, handler)会话开始事件恢复上次的开关状态pi.on(session_compact, handler)上下文压缩事件重新注入被压缩掉的规则pi.sendMessage(msg, opts)向会话注入消息静默注入/撤销规则集pi.appendEntry(type, data)写会话自定义数据持久化开关状态ctx.ui.setStatus / notify状态栏 / 通知● ADHD ON标记、切换提示快速验证效果按 INSTALL.md 中 Pi 章节安装扩展输入/i-have-adhd状态栏出现● ADHD ON提问一个多步骤任务观察回复是否命令先行 编号步骤 无寒暄输入stop adhd mode确认模式即被关闭——这正是on(input)的功劳。总结三个 API 各司其职registerFlag管启动时——pi --adhd让默认状态由用户掌控registerCommand管会话中——/i-have-adhd提供随时可预测的开关on(input)管每条输入——自然语言停止词和别名拦截让体验更顺滑。配合session_start/session_compact两个事件整个扩展做到了规则注入一次、压缩后补注、随用户意愿关闭。想动手实践通读 extensions/i-have-adhd.ts 全文再对照 AGENTS.md 里的仓库地图你会对 Agent 扩展的事件模型建立完整认知。【免费下载链接】i-have-adhdA skill to stop your coding agent from burying the answer. ADHD-friendly output.项目地址: https://gitcode.com/GitHub_Trending/ih/i-have-adhd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考