命令行智能工具:先定输入边界再接模型能力
把命令的输入当成不可信数据
这个工具的第一版不递归扫描目录,也不接受 URL,更不跟随 Markdown 里的本地链接。参数解析后先转成规范路径,再确认它仍在允许的工作目录中;符号链接、过大的文件和二进制内容都直接拒绝。这样做听起来保守,但命令行工具一旦默认“顺手帮忙找文件”,实际使用时就很容易读到调用者没打算交出的内容。
标题提取也不该靠一条宽松的正则结束。空标题、代码围栏里的 ##、引用块里的示例都要排除。解析器返回的是标题文本、行号和层级,不直接返回改写后的文件内容。模型只看到这些已经裁剪过的结构化字段,不能从提示词中获得原始文档的其余部分。模型返回结果先按 JSON schema 校验:字段未知、建议索引越界、置信说明为空,都当作无效建议处理。
让写入动作足够显眼
--dry-run 的输出应列出每一项候选合并:原来的两条标题、预计保留哪一条、修改所在行。用户若要写回,必须显式传 --write,并且工具在落盘前再检查文件的修改时间;文件在预览后被其他程序改过,就停止而不是覆盖。写入时采用临时文件加原子替换,失败不会留下半截 Markdown。
我还会把退出码约定写清楚:参数或权限问题是一类,解析失败是一类,模型不可用则单独返回一个可识别的状态。调用脚本据此决定重试还是提示用户,不需要从自然语言错误里猜意思。日志只记录命令版本、输入字节数、规则命中数和请求结果,不记录标题正文。
用小样例维护行为
样例不需要很多,但要覆盖会误伤的情况:两个相邻的同名标题、标题中带反引号、引用中的假标题、未闭合代码围栏,以及只读文件。每次修改解析逻辑,先比较这些样例的预期输出。发现模型建议变得飘忽时,也先检查传给模型的候选列表是否变化,而不是马上调整提示词。
这个边界让工具的能力很有限:它不能替人判断一篇文章的结构是否合理。不过它能稳定完成“找出可能重复的二级标题,并把决定交给用户”这一件事。对于刚接入模型的命令行工具,这样的限制比看似聪明的自动改写更容易维护。
我先把需求写成一条可验收的命令,而不是让 Agent 直接“做完功能”。这次练习的目标是:输入一个公开的 Markdown 文件,输出其中的二级标题;模型只负责建议标题是否需要合并。
产品侧给出两类样例:重复标题和正常标题。研发侧把输入大小、允许读取的目录、模型输出 JSON 格式写进 README。命令先跑本地规则,再把候选项交给模型:
tool outline demo.md --dry-run
我会人工核对 --dry-run 的差异,确认后才允许 --write。模型不能执行 shell,也不能读取命令参数以外的文件。这样讨论不会停在“效果好不好”,而能落到同一份输入和输出上。
模型只评估,不负责发现结构
标题扫描、层级判断和相邻关系应由本地解析器完成。模型拿到的只是两条候选标题、层级和行号,不能自行从正文补出一条“看起来像标题”的内容。候选为空或只有一条时不发请求;返回中出现换行、未知字段或超出候选范围的索引,就丢弃整条建议。这样能减少无效请求,也避免模型输出反过来改变解析器的职责。
建议可以区分“可合并”“疑似重复”和“不处理”。前两类都显示理由,但理由不能直接变成写入指令。两个标题都带“配置”不一定重复:读取配置和热更新配置可能正好需要分开导航。用户在预览里看的是原文 diff,不是模型替他下的结论。
写回前重新核对文件
网络超时或 schema 不通过时,工具仍应输出本地规则找出的候选,并允许 --no-model 离线运行。写回前再读取一次文件并重新解析;若预览后的行号或候选关系变了,就要求重新预览。这样用户确认的是哪两条标题,落盘时改的也仍是那两条,而不是被别人插入内容后偏移的位置。
1809



被折叠的 条评论
为什么被折叠?



