★ FEATURED ARTICLE 后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载本指南围绕 explainshell 仓库中.claude/skills/my-plan/SKILL.md定义的设计规划技能展开讲解其「ground → draft → dual-review → iterate → commit」五步规划舞步、七步执行流程与约束边界并以仓库内唯一已落盘的计划文档plans/positional-prefix-matching.md作为完整实战案例说明每一类计划要素在真实产物中的写法。读完你将掌握这套「先计划、后构建」的仓库协作惯例并能在自己的变更中复用该模板与评审回路。技能定位产出计划文档而非生产代码my-plan是 explainshell 仓库CLAUDE.md描述其核心功能为解析 man 页面并将命令行参数逐一匹配到对应帮助文本中一个可交互调用的 Claude 技能frontmatter 中user_invocable: true其职责被一句话概括为Codifies this repos planning workflow:ground - draft - dual-review - iterate - commit. The output is a reviewed plan document underplans/. It doesnotwrite production code - thats a later, separate build pass against the committed plan.两个关键承诺决定了它与普通编码任务的分工输出物是plans/下的计划文档plans/目录被仓库追踪非 gitignore已提交的计划是持久化记录后续构建阶段会以它为蓝本不写生产代码技能本身不编辑源码、不跑构建、不应用变更构建是对已提交计划的另一次独立执行。技能还声明了它适配的环境与仓库约定This is tuned for ~/dev/vibe/explainshell提交信息遵循 conventional-commit 风格feat(web):、chore(deps):等提交一律进入master分支CLAUDE.md/AGENTS.md是结构、工作流与既定约定的权威来源source of truth任何计划若想重开已定案的约定或工作流调用都必须先核对这两份文档。七步流程逐层拆解技能正文把规划过程展开为七个步骤下面结合仓库现状逐条说明其执行要点与产出形态。Step 1 — 界定范围Scope it先确认计划针对什么变更。如果需求含糊在起草前先问一两个尖锐问题——a plan for the wrong thing wastes the review为错误的东西做计划就是在浪费评审。这一步没有仓库内代码动作纯粹是需求对齐。Step 2 — 用真实代码夯实计划Ground the plan in real code first这是让计划值得被评审的关键一步必须实际阅读变更触及的文件、符号、路由与 schema不允许空谈。具体要求引用真实的file:line、函数名、CLI 子命令、数据库表在重开既定约定或工作流调用之前先检查CLAUDE.md/AGENTS.md一份夯实过的计划必须点名crux核心权衡、必须保留的invariants不变量、以及open questions开放问题含糊的计划做不到这一点。这条要求直接体现在仓库唯一一份计划文档plans/positional-prefix-matching.md中问题小节精确到Matcher.visitwordexplainshell/matcher.py与ParsedManpage.positionalsexplainshell/models.py的行号甚至给出了matched_group.positional_indexexplainshell/matcher.py#L28这一计数器在顺序匹配中的具体行为。Step 3 — 写入plans/slug.md计划文件命名使用简短的 kebab-case slug如batch-extraction.md。技能给出了经过实践验证的文档结构七类要素要素内容要求Status 行如design draft - not yet implemented并记录需求来源Problem今天的问题是什么用真实符号grounded in real symbols描述The crux核心权衡与拟议解决方案并点名被否掉的替代方案Changes提取管线 / 匹配 / 存储 / Web / 工具链的具体改动函数签名、CLI 标志、schema 变更、路由Invariants to preserve变更不得破坏的约定与设计规则Tests and validation适用哪套测试make tests-quickvsmake tests-all提取器改动是否需跑/eval-llm、mandoc 渲染改动是否需跑/eval-renderMigration/dataDB 重建或db-latest发布影响如有Open questions需要用户与评审者权衡的决策点技能还注明plans/在仓库中是被追踪的非 gitignore已提交的计划是持久化记录。Step 4 — 双重评审Dual-review it调用dual-review技能的设计模式指向该计划/dual-review design plans/slug.md。评审会同时运行两个评审者codex 一个 Claude 子代理并产出综合结论synthesis。技能明确强调不要跳过这一步——交叉检查正是这套舞步的意义所在。注dual-review技能在本仓库的技能目录.claude/skills/中仅有eval-llm、eval-render、mandoc-fix、my-plan四个dual-review是 my-plan 依赖的外部技能按其文档所述运行 codex 与 Claude 双评审并产出综合结论。Step 5 — 综合并与用户迭代Synthesize and iterate with the user向用户呈现评审综合结论两位评审者在哪些点上意见一致置信度最高、各自发现了对方遗漏的什么、以及——关键——当评审者与仓库自身文档CLAUDE.md/AGENTS.md、不变量、既定工作流相矛盾时要带着引用证据提出反驳。然后提出一轮修订集apply / defer / skip-with-reason在编辑计划之前必须获得用户对方向的签字确认——这是 human-in-the-loop 步骤不是自动应用。Step 6 — 把接受的修订并入计划正文更新plans/slug.md重写受影响小节、用评审结论消解开放问题、并记录被有意推迟如拆成后续工作的发现避免它们被静默丢弃。同时在 Status 行注明评审情况如dual-reviewed (codex claude date), revisions folded in。Step 7 — 签字后提交Commit on sign-off用户满意后提交计划提交信息使用 conventional-commit 风格如docs(plans): add slug design plan。其他纪律按仓库约定提交到master但除非用户要求否则不 push——push 到master会经 CI 触发生产部署只暂存计划文件绝不混入无关的工作区改动本技能不提交生产代码结束时报告提交哈希commit hash。约束与边界技能用 Constraints 一节划定了四条红线避免规划技能越界变成构建工具Plan, dont build只规划不构建技能只产出计划文档不编辑生产代码、不跑构建、不应用变更。CLAUDE.md中的make format/测试工作流在此不适用——唯一输出是 markdown。Dont auto-apply review findings不自动应用评审发现综合、建议、获得签字、再并入。采用、推迟还是跳过由用户决定。Dont commit without the users go-ahead无用户许可不提交计划内容得到明确认可如「Commit it」才是提交信号。Respect repo conventions尊重仓库约定重开已定案问题前先查CLAUDE.md/AGENTS.md触及 LLM 提取器或 mandoc 渲染的计划必须指明用于验证的 eval。此外技能允许部分执行如果用户只想要其中某几步如「just draft it, skip the review」就照做——这套舞步是默认流程不是枷锁the dance is the default, not a straitjacket。实战案例plans/positional-prefix-matching.md仓库中唯一一份已落盘的计划文档就是本技能流程的完整产物可直接对照模板验证每个要素的写法。背景issue #361 与错误的位置参数归属计划源于 GitHub issue #361dig ns foo.bar 8.8.8.8中8.8.8.8被解释到了错误的位置参数文本上。其根因在于匹配器纯按顺序分配位置参数当词不是标志时Matcher.visitword会遍历ParsedManpage.positionals一个「位置参数名 → 合并帮助文本」的OrderedDict用单一计数器positional_index依次消费——第一个未匹配的词取第一个位置参数、第二个取第二个唯一例外是word in d的精确名匹配针对start/stop这类关键字式位置参数。dig 提取出的位置参数顺序是server, name, type于是词现状归属问题nsserver693 字符全页最长的文本——最差的落点顺序错配foo.barname碰巧正确8.8.8.8type错误而 dig 的 synopsis 是dig [server] [name] [type] ...——记号明确只附着在一个操作数上匹配器却完全没有「token 形状shape」的概念无法利用这一信息。The cruxsigil 知识放在哪一层计划把核心权衡提炼为「Where does the sigil knowledge live?」列出三个候选方案方案结论理由1. LLM 产出的 schema 字段prefix采纳提取 prompt 本就让模型识别位置参数sigil 在 synopsis[server]中可见通用性强任何 synopsis 把字面 sigil 附着到操作数的页面都能携带无 sigil 的页面行为完全不变2. 匹配器侧启发式硬编码「 名为 server 的位置参数」拒绝只修 dig把命令专属知识编码进错误的层且会无界膨胀3. UI 截断正交折叠长帮助文本是独立的产品问题不解决错误归属配套的次级设计决策是带前缀的位置参数整体退出有序消费池——它只能被携带其前缀的 token 认领。这修复的是整条命令而非单个-tokenserver退出有序池后ns与foo.bar依次消费name, type而非server, name。权衡代价是dig 8.8.8.8无会把裸地址映射到name——而这恰好符合 dig 的真实语义裸地址是查询名而非服务器。Changes四层落点计划按仓库分层给出具体改动数据模型explainshell/models.pyOption新增prefix: str | None None——token 必须以此字面串开头才能认领该位置参数文档化为仅在positional设置时有意义与positionalvs flags 的既有规则一致明确不塞进Option.metameta是提取侧边带数据{lines: [start, end]}而prefix是匹配行为应作为一等字段序列化零成本to_store()走model_dump()旧 DB 行缺少该键时反序列化落到None默认值ParsedManpage.positionals保持「名 → 文本」形状但排除带前缀选项新增prefixed_positionals属性返回有序「名 → (prefix, text)」映射positionals仅被matcher.py两个调用点消费形状变更可控。这一设计与当前仓库源码完全吻合explainshell/models.py#L39-L44定义了OPTION_PREFIX_SIGILS frozenset({, , :})#L64有prefix: str | None None#L118-L145实现了positionals排除前缀与prefixed_positionals名 →(prefix, 合并文本)双属性。匹配器explainshell/matcher.py——visitword位置参数分支改为双池分配加宽分支门原分支以if self.man_page.positionals:为门带前缀条目离开该字典后门必须变成「存在任何位置参数」positionals or prefixed_positionals否则唯一位置参数带前缀的页面cmd [server]永远进不了前缀池cmd 8.8.8.8会落到 unknown前缀池优先词以任何已声明前缀开头即认领该位置参数并返回多个带前缀 token 可复用同一位置参数镜像现有 variadic 行为多个位置参数声明相同前缀时按文档顺序取先者有序池加一道新护栏精确名匹配 → 按索引有序消费 末尾键 variadic 复用沿用单一positional_index计数器无需 consumed-set因为前缀池与索引永不交互。新护栏有序池为空所有位置参数都带前缀时不带前缀的 token 必须落到 unknown——现有keys[-1]variadic 回退在空列表上会抛IndexError而这是 Web 服务路径。当前源码explainshell/matcher.py#L671-L672正是prefixed self.man_page.prefixed_positionals配合if self.man_page.positionals or prefixed:的门判断#L715-L722保留精确名匹配与索引有序消费与计划设计一一对应。提取层explainshell/extraction/llm/prompt.pyJSON schema 增加prefix: 字段指令大意synopsis 附着在该位置参数操作数上的字面 sigil如dig [server]中的仅与positional同时有效否则省略Sigil 约束承重设计带前缀的位置参数整体退出有序消费因此流行页面上的一个prefix误报会破坏其最常见操作数的裸形式。两个典型陷阱ssh/scp 的[user]hostname是可选子组件而非操作数 sigil若模型在此误发prefix: ssh example.com将不再匹配hostname占位符风格名如FILE不得被规范化为前缀。因此prefix被限制为来自语料实证白名单的单一标点字符在两个 sanitize 站点同时强制其余一律丢弃并打 debug 日志response.pyllm_option_to_store_option读取prefix传给Optionsanitize_option_fields在positional为空时清空prefix与既有 positional-vs-flags 规则并行并丢弃白名单外取值normalize_option_fields处理模型最可能的错误——把 sigil 嵌进位置参数名本身positional: server且无 prefix 字段时剥离进prefix该规则仅作用于白名单 sigil 字符FILE式占位符不受影响postprocess.py的sanitize_option获得同样的「prefix 需 positional 白名单」规则所有重建Option的站点必须透传prefix实现可改用opt.model_copy(update{...})让未来字段免费扩展。Diff 工具explainshell/diff.pyprefix加入_OPT_FIELDS与_FALSY_EQUIVALENT后者保证None与缺失对旧行比较干净diff db即可在数据刷新时暴露前缀变更。Web 层正常渲染零改动——匹配在服务端 matcher 完成views.py仅透传positional用于展示唯一例外是 DEBUG 面板会镜像选项字段matcher.py的_option_debug需把prefix加进调试字典否则在调试「某 token 为何被匹配」时新匹配提示不可见。源码explainshell/matcher.py#L52-L62的_option_debug已包含prefix: option.prefix与计划一致。Sigil 白名单的语料依据白名单不是拍脑袋定的而是扫描数据库全部61,322个原始页面的 SYNOPSIS 段、匹配独立的括号 sigil 操作数[前有空白排除粘在别的 token 上的后缀语法得到的sigil命中页数代表用法197dig/delv/adigserver、GNUas/gccFILEargfiles、javadoc/jarfiles、bdepcfg-name、cargo-installversion117date FORMAT、vi 风格linemg、mcedit、vile、geany、pr page、xset dpms:19X display 编号Xorg :display、tightvncserver :display、broadwayd :DISPLAY被证据驳回的候选与%几乎只出现在粘前 token 的后缀语法中--flag[VALUE]、samba 的user[%password]——恰是此约束要拦截的误报形态TeXformat与#是 shell 元字符永远不会以普通词形式到达匹配器、[、{、(、引号是占位/交替语法而非 sigil。种子列表一次性到位是因为页面会在未来每次重提取时机会性地获得前缀。不变量、测试与迁移计划以「Invariants to preserve」锁定四条底线帮助文本保持 manpage 原文逐字不动quote-the-manpage 契约本计划只改归属不改文本无prefix的页面当前整个语料匹配行为必须逐字节与今天一致前缀池必须是严格超集功能response.py与postprocess.py强制相同的字段规则既有 sanitization parity 约定工具链用普通Store、生产 Web 才用CachingStore见CLAUDE.md的 Store 生命周期章节本计划不触碰存储生命周期旧行兼容——缺失prefix键不得导致 Pydantic 校验失败默认None兜底需确认无extraforbid式配置干扰。测试与验证部分给出了分层验证矩阵单元测试在tests/test_matcher.py增加带前缀位置参数的 fixture 页面与tests/helpers.py的withmultipos并列覆盖乱序认领、首位置前缀、非前缀 token 跳过前缀位置参数、无声明前缀的前缀 token 回落、双前缀 token 复用、以及「唯一位置参数带前缀」页面的空有序池护栏套件选择上因 matcher models 在 Web 服务路径上而要求make tests-alle2e 需重建tests/e2e/e2e.db加入 dig 页面并对 issue-361 命令dig ns foo.bar 8.8.8.8做快照固定当前仓库的Makefile中e2e-db目标已包含tests/e2e/manpages/ubuntu/26.04/1/dig.1.gz且tests/e2e/snapshots/下已有explain-dig-prefixed-positional.png快照说明该计划已实现落地prompt 变更触及 LLM 提取器落地前需按CLAUDE.md的 stash 工作流跑/eval-llmbaseline vs change重点关注无 sigil 页面的扰动新 schema 字段对它们应是无操作与 ssh/scp 形态页面的误报文档要求同步更新AGENTS.md的 Data Model 小节与匹配器描述手工验证命令为python -m explainshell.manager diff db --mode llm:model manpages/arch/latest/1/dig.1.gz应显示server获得prefix: 随后本地匹配dig ns foo.bar 8.8.8.8应得到8.8.8.8→ server、ns→ name、foo.bar→ type。迁移/数据方面仅两条 dig 行需要新字段ubuntu/26.04/1/dig.1.gz与arch/latest/1/dig.1.gz优先用--overwrite重提取而非手改 JSON走真实管线语料其余部分保持原样前缀在后续重提取中机会性获得不做批量重提取生产库烘焙进 Docker 镜像修复只能经make upload-live-db pushmaster部署管线到达线上且代码应随数据同时或先于数据部署。计划还以「Out of scope」显式记录了两项有意推迟的工作nsvsfoo.bar仍需值域知识schema 的has_argument允许值列表扩展到位置参数才能语义区分长帮助文本的 UI 截断/展开是正交产品决策。最后「Open questions」一节展示了双评审与用户签字如何闭环字段名定为prefix双评审均无异议、prompt 范围限定 synopsis-only评审的误报分析强化了这一点、e2e 覆盖采纳、回填范围仅 dig、白名单以语料扫描替代猜测——结论是No open questions remain.无遗留开放问题。配套基础设施让评审可验证的仓库支撑my-plan依赖仓库里一组配套技能与脚本才能真正闭环eval-llm对 LLM 提取管线变更执行 baseline vs candidate 双跑、compare后按 merge / regression / defer 三分法则出结论正是计划中「提取器改动需跑/eval-llm」的执行者eval-render对候选 mandoc 二进制的 markdown 渲染做评估并产出 merge / regression / defer 结论对应「mandoc 渲染改动需跑/eval-render」mandoc-fix编排 mandoc 渲染缺陷的 diagnose → fix → validate → promote 全周期并把/eval-render、/eval-llm作为子步骤复用tests/evals/llm/llm_eval.py与CLAUDE.md中的 stash 工作流git stash push -- explainshell/extraction/llm/→ 旧代码跑 baseline → 恢复 → 新代码跑 change →compare为提取器变更提供可复现的前后对比Makefile的tests-quicklint unit不含 e2e、tests-alllint unit e2e botshed prod-integration提供了计划模板中「Tests and validation」一节的套件语义。总结my-plan把 explainshell 的规划协作固化为一条可重复的纪律先用真实代码夯实计划并点名核心权衡落盘为plans/slug.md的结构化模板经 codex Claude 双评审交叉验证后由用户签字最后以 conventional-commit 提交到master不 push。它与eval-llm/eval-render等验证技能共同构成「计划 → 评审 → 验证 → 构建」的完整闭环而plans/positional-prefix-matching.md则展示了这套流程在真实问题dig 的server误解释上的完整落地——从问题根因、三层选型权衡到四层代码变更、语料实证的白名单、分层测试与数据迁移最终在No open questions remain中闭环。对于任何准备在 explainshell 上做变更的开发者把变更先写进plans/并跑完这套舞步是让设计经得起评审、让实现有据可依的推荐路径。赞分享后端开发工具【免费下载链接】explainshellmatch command-line arguments to their help text项目地址https://gitcode.com/gh_mirrors/ex/explainshell点击查看免费下载相关推荐gstack OpenClaw Plan 层详解用 gstack-plan 流水线为 Claude Code 项目产出全量评审过的实施计划gstack OpenClaw Plan 层详解用 gstack plan 流水线为 Claude Code 项目产出全量评审过的实施计划 gstack 与人工智能AI 技能浏览器控制AI 评测Kimi Code CLI 计划模式Plan Mode全解析从 EnterPlanMode 到 ExitPlanMode 的规划与审批工作流Kimi Code CLI 计划模式Plan Mode全解析从 EnterPlanMode 到 ExitPlanMode 的规划与审批工作流 导读 Kim人工智能AI Agent代码智能体交互助手CLI工具调用ulw-plan CLEAR 意图路径解析oh-my-openagent 中如何以最少提问产出决策完备的工作计划ulw plan CLEAR 意图路径解析oh my openagent 中如何以最少提问产出决策完备的工作计划 导读 在 oh my openagent 的人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
