# 📕 狮子的书单推荐 ## 2025 荐书 今年阅读量比较小，所以没有满分推荐的书目也是情有可原... ## 2024 荐书 ### 《激荡十年，水大鱼大》 ::commend --- callouts: - 急速扩容的经济规模和不断升级的消费能力，如同恣意泛滥的大水，它在焦虑地寻找疆域的边界，而被猛烈冲击的部分，则同样焦虑地承受着衍变的压力和不适。它既体现在国内各社会阶层之间的冲突、各利益集团之间的矛盾与妥协上，也体现在中国与美国、日本、 tags: - 📕 历史 欧盟，以及周遭邻国之间的政治及经济关系上。 - 这就是我们在过去十年看到的景象，它既波澜壮阔又混沌失控，充满了希望又令人疑惑。大水对速度的渴望以及恐惧，大水与其他大水之间的博弈，大水与大鱼之间的适应，以及大鱼与其他大鱼、小鱼之间的冲撞，构成了一幅难以理性静察的壮观景象。: null caption: 《激荡十年，水大鱼大》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s29636034.jpg --- :: 浪潮不会停止，正如历史不存在终结，时间裹挟一切，向下一个十年奔涌。作为时代的普通人，亦或是浪潮中的小虾，常被在其中激起浪花的领头鱼所震撼。这些企业，可以作为一个同时代的优秀标杆自勉。 企业史实际上就是企业家的精神史，其中某些精神，甚至能赋予最悲观者继续前行的力量，向时代的不确定性或无常发起挑战。开卷有益（但是记性不好的人看历史真得很容易大头）。 ### 《祈祷之海》 ::commend --- callouts: - 神经元是否发射脉冲仅仅反映其活动的一个层面，谁又知道有哪些微妙的生化反应影响了人类意识的本质呢？ - 她说：​“你知道在人们看来，现如今的帕斯卡赌注 [插图] 是什么吗？尽可能地去讨好超人类学家，万一谁成了神呢？我觉得你的座右铭应该是‘对所有聊天机器人都好点儿，没准它就是某位神祇的亲戚呢。’” tags: - 📕 科幻 caption: 《祈祷之海》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s34344109.jpg --- :: > 你必须赌上一把。这别无选择。你已经上了贼船了。你还能选哪一个呢？……你会失去两样东西：真与善；拿这两样东西去下注：你的理性和你的意志，你的知识和你的幸福；你在本性上想回避两件事：错误和痛苦。你的理智不会因为顾此失彼而受到冲击， > 因为你别无选择。这一点是确定无误的。但你的幸福呢？让我们赌一把，如果上帝存在的话，我们的得失会是怎样的情况。如果你赢了，你将获得一切；如果你输了，你也毫发无损。所以，别再犹豫了，就赌上帝存在吧。 > :name[布莱兹·帕斯卡] 帕斯卡赌注，即“我”不知道上帝是否存在，但信上帝输了亏损很小，赢了获利很大，那就该信上帝。前年 GPT 刚被推向浪尖时，有个笑话，讲一个人每次问完 GPT 后都要和他说一声“谢谢”，怕的就是哪天人工智能清算人类时， 说不定会放过那些曾经对它说谢谢的人。 科幻故事总是能让人看到未来的可能性，尽管完全不能用这种可能性推演现实，不过哪怕又只是一种荒诞和戏谑，也能让人在现实中找到一些宽慰。这是我看过的最好的科幻短篇（上一本是特德姜的《呼吸》）。 ### 《太白金星有点烦》 ::commend --- callouts: - 李长庚啧啧称赞了一阵，突地又涌起一股同情：“这又有什么意义？桂树原来什么样，还是什么样，有你不多，无你不少。你自以为精通了伐木之技，到头来却连一丝裂隙都留不下来。”吴刚挠挠头，沉思片刻方道：“好像是没什么意义。不过…”他拎起斧子，“ tags: - 📕 故事新编 哪个人不是如此？” - 李长庚在启明殿干了那么久，太熟悉仙界的运作逻辑了，一切不合理的事情背后，都有一个合理的理由，只是你不知道罢了。: null caption: 《太白金星有点烦》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s34544956.jpg --- :: 水平有限，不点评了。 另，2024 年在阅读方面的新东西： - 开始使用微信读书啦！纸书虽好，搬家就让人难受啦，更惨的还是落灰了难清理。 - 几年下来阅读量超过 200 啦！开心了一小会，em，实际上没什么特别的感觉。阅读作为一项普通的爱好，显性的收益当然就是打发时间，就和我在塔科夫花了两千个小时一样（只是并没有精通）。 - 写了一个微信读书的笔记转换软件，可以把划线内容的上下文提取出来放到博客上，见 [《简读日本史》](https://lionad.art/books/_isbn-9787553815268)。目前只是脚本，还没有做成应用，等之后低代码平台上线后再考虑做成通用应用。 增订：微信读书自动化有封号风险。 ## 2023 荐书 2023 年沉迷塔科夫，所以不出意外地鸽了。 ## 2022 荐书 ### 《50：伟大的短篇小说们》 ::commend --- callouts: - 日子因为寒冷无聊而变得坚硬，像是一块去年的面包。我们用钝了的刀切下来一小块食用，没有什么胃口，慵懒，昏昏欲睡。 过了一会儿，父亲走下楼，走出了自己的领土——他是一个被击溃的人，一位刚刚失去了自己宝座和王国的、被流放的国王。 - 那些积攒下来的，想留到更有把握时再写的东西，现在再也无法写下来了。也不用忍受写作的挫败了。也许你根本就不会把它们写出来，这就是为什么你要把它们扔在一边，迟迟不肯动笔。但现在，他永远都不会知道答案了。 - 贫穷的人们，总爱死抓住手上的东西不放。这是生活令人如此绝望的其中一个原因。 tags: - 📕 短篇 - 👨‍💼 一人一篇 caption: 《50：伟大的短篇小说们》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s29644770.png --- :: 你知道豆瓣有种收藏夹叫做“『收藏』每人一部代表作之短篇小说集”吗？ 这本书是这样的收藏夹。 ### 《消失的 13 级台阶》 ::commend --- callouts: - 神父点点头，走到跪在地上的死刑犯面前，背对着祭坛上的十字架，用严厉的口吻说道：“你忏悔一生的罪过吗？你忏悔做了违背全能的神的事吗？”“我忏悔。”“那么，我饶恕你的罪过。”听到神的话，南乡觉得自己的头就像遭到了重击。160 号犯的罪 tags: - 📕 推理 神都赦免了，可是人类不赦免。" - "470 号被带到了踏板前，南乡拼命地把震耳欲聋的读经声和死刑犯的号叫声从大脑里赶出去。在这种时候，支持了他的是赞成报应刑主义的德国著名哲学家康德的一句话：只有绝对报应才是正义的——470 号的脚踏在了踏板上。 绝对报应是刑罚最根本的意义——南乡一边在心中重复着康德的话，一边拿起了麻绳。假定有一个公民社会将要解散，假定世界到了被灭绝的最后时刻——南乡将裹着黑色皮革的绳套，套在了 470 号的脖子上。杀人者必须被处以极刑——“我没有杀人！”， 南乡听到了从眼前那个被蒙上了面罩的 470 号嘴里发出的声音。紧接着，就像地震时发出的地声，冲击着整个刑场。踏板被抽掉，刑场与地狱连为一体。470 号的身体就像被突然出现的洞穴吸走了一样，转瞬就消失了。麻绳被拉直的同时，传来了窒息的声音、 骨折的声音和麻绳摩擦的声音。": null caption: 《消失的 13 级台阶》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s34070178.jpg --- :: 借推理的外壳，藏着不少对刑法制度的思考。推崇“科幻作家水平往往体现在他对非科幻部分专业的掌握程度”之类理念的人会喜欢这种小说。 ### 《三体Ⅲ》 ::commend --- callouts: - 弱小和无知不是生存的障碍，傲慢才是。 tags: - 📕 科幻小说 caption: 《三体Ⅲ》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s26012674.jpg --- :: 高中时，用硬盘还原工具在学校微机室电脑中翻到了一堆好玩的东西。有一个文件名是数字乱码的文本，讲述了在一个无规律的行星系统中，秦始皇为了计算太阳的运行规律，指挥千军万马组建了一个人肉计算机的故事。我打开 windows 的文本编辑器， 用方向键一行一行翻完了这篇文本，俨然一副沉迷网络小说的样子。时隔一旬，借来三体系列，熬了几次夜，近乎一口气看完这部近百万字的科幻。 在我看来，前两部的故事性和传统小说相比显得很稚嫩。可能幻想小说都有这样的通病：围绕一个基础设定去设定关键情节，同时，如果写得不好，读者能很明显看出故事的“人工”痕迹。 在设定上，三体系列非常有意思，就比如，抛开三体，歌者和二向箔作为单独的短篇也是绝妙的。尽管已经在无数地方被科普过“二向箔”，三体Ⅲ还是凭借对它仅几十页的描述打动了我。把代表热情和希望的太阳毁灭给人看太壮丽了， 幸存的地球人在经历前两部三体跨越数百年反抗后，终于等来了结果的这一天。只是破除黑暗黎明的不是朝霞，而是日落。 毫无疑问，弱小和无知是生存的根本障碍，但人类花了好几百年，交上的是傲慢的答卷。“孩子，这里太阳升起来了。”弗雷斯在大动乱后给程心打电话时这样描述到。显然，态度在此刻已经没有意义，“现在，太阳真的在融化，把它的血铺展在二维平面中， 这是最后一次日落。” 把傲慢列为禁品，人类能活得再久一些吗？不能。这是副标题“死神永生”所暗示的，在这样的宇宙，时间显得没有意义。这也是相比长篇小说，短篇难以描述的震撼。 ### 《性学观止》 ::commend --- callouts: - "********" - "***********************************************************" - "*************" - "**********************************" - "********" tags: - 📕 百科 caption: 《性学观止》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s32271108.jpg --- :: 有些时候，严肃和性感一样令人着迷。 ## 2021 荐书 ### 《知觉之门》 ::commend --- callouts: - "任何有精神的肉体 ，注定要独自忍受痛苦 、独自畅享欢乐 ，这是人之本性 。除非经过符号化的过程而间接地被他人感知 ，否则知觉 、情感 、洞察 、幻想 ，凡此之类 ，都属私密 ，不能被传达到外界 。他人经验的相关信息 ，我们可以共享 " tags: - 🌌 神秘主义 - 📕 启示录 但他人的经验本身 ，我们是永远没有办法体会的 。小至家庭 ，大至国家 ，任何人类组织 ，无非是一个个岛宇宙的社会。" - "每个人诞生在自己的语言传统中，是其受惠者，也是其受害者——之所以是受惠者，是因为语言提供他有关于其他人的经验的累积记录，之所以是受害者，是因为语言使他相信，简化的意识是唯一的意识，也因为语言会迷乱他的现实感， 所以他容易把自己的概念视为资料，把字词视为真实的事物。" - "我越是思考语言的问题 ，越觉得语言中存在某种无用 、平庸 、甚至 （恕我直言 ）愚蠢的东西 。与语言相比较 ，当你在荒山和古丘陵的废墟前 ，当你专心致志 ，面对面地直观到地球的重力 、自然的平静 ，你将何其震撼啊 ！ ": null caption: 《知觉之门》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s29411326.jpg --- :: 初看以上摘录，也许会认为这是一本批判“语言”的书籍。更甚有人会认为这书是宣传致幻剂的异端，因为封底就留有赫胥黎的遗笔“LSD，100 毫克，肌肉注射！”。实则不然，赫胥黎只是借批评人造符号的口吻来凸显造物的美妙之处。他认为世界（ 或者说世界的本质）复杂而玄妙，以至于人只能通过创造符号传递概念以理解其表象，却不能欣赏其内在奥妙。他认为人脑用以认识世界的工作原理类似带有旋钮的节流阀。为了探索世界本质的奥秘，我们可以使用一些手段“打开”节流阀。而致幻剂， 就是赫胥黎尝试的手段之一。 现代神经科学已经证明人脑的注意力机制确实类似节流阀，而不是常识所认为的“灯塔”。现在我们也有更多除了毒品以外用于打开节流阀的手段。就这几点来看，赫胥黎的解释非常成功。通过《知觉之门》，他成功让我理解形而上的美妙。我期待更多相关研究。 相关博客：[《神秘主义的艺术》](https://lionad.art/_achieved/2021-01/the-art-of-mysticism) ### 《山月记》 ::commend --- "0": null callouts: - 我深怕自己本非美玉，故而不敢加以刻苦琢磨，却又半信自己是块美玉，故又不肯庸庸碌碌，与瓦砾为伍。于是我渐渐地脱离凡尘，疏远世人，结果便是一任愤懑与羞恨日益助长内心那怯弱的自尊心。其实，任何人都是驯兽师，而那野兽，无非就是各人的性情而已 tags: - 📕 短篇小说 - 🌸 日本文学 令人不由得要屏住呼吸的、壮大、明媚的云朵如巨柱林立。它们的脚站立在水平线上，顶部在距离天顶三十度以内的范围。这是怎样的崇高！下方有如冰河的阴翳，随着不断向上，可以看到从幽暗的蓝到朦胧的乳白之间所有微妙的色彩变化。 背后的天空被迫近的黑夜渲染成一片丰富而厚重的蓝青色。在它底部，流动着蓝紫色的深沉得近乎娇艳的光和影。虽然山岗上已经漂浮着落日的影子，但在巨大的云层顶上，映照着白昼般的光芒，世界充满着如火如宝石一般、最华丽最柔和的光明。 那是比能想象到的任何高度都更高远的地方。从下界的夜里所眺望到的它那清净无垢的华美和庄严，不止是令人惊叹。 对任何事，我都带着一种沉着的绝望进入。正如去海边时，我带着自己随时会淹死的确信前往一样。但是这么说，决不意味着我在自暴自弃。非但如此， 我大概一直到死都不会丢掉快活。这种确信无疑的绝望，甚至成了一种愉悦。那是一种近乎信念的东西——有清醒的意识、勇气、乐趣，足以支撑着我走完今后的人生路。不需要快乐，也不需要灵感，只凭义务感就能好好走下去的自信。用蚂蚁的意志， 一直高唱蝉的歌曲的自信。": null caption: 《山月记》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s30020978.jpg --- :: 这两年短篇看得不少。除去科幻短篇，还看过不少国际知名作者的短篇集。我愿称中岛敦的这本《山月记》为我看过的短篇中的最佳。如果要为我看过的百来本小说排个清单的话，这本就是榜首！ 并非因为喜欢选题，这喜欢也和翻译无关，比如同样是日文翻译过来的芥川龙之介和太宰治的短篇——这两者的大名甚至被用来命名日本最高文学奖项——但我喜欢《山月记》更甚于后者的作品。看很多作者的短篇集我都要挑挑拣拣，弃几篇无味的， 再拣出几篇深刻的出来单独欣赏，然而要我说《山月记》中每篇都是一流，甚至超一流作品！我向来不喜欢历史故事，也包括对历史故事的翻案，但中岛敦的故事性太美了，他用某种我无法言说的“文学性”折服了我。 在看《山月记》时我一直在想，撇开政治因素，鲁迅尚可以作为中日的“国民作者”，但是在上学时却没有看到任何一篇作为汉儒学者的中岛敦的作品，实在是很遗憾。更可惜的是中岛敦英年早逝，没有更多作品传世，要不然我打赌他的影响力会突破日本，横贯东西。 ## 2020 荐书 若是每过一年，就在地狱里记账的单子上翻过一页纸的话，大家都会感觉日子是由慢到快的。童年时，微风，蝉鸣，巷子的嚷嚷，透心凉的冰棍，还有，你在沙滩一角花了整整一下午堆砌好的黄色城堡，这些东西就能支撑起你一整个夏天的回忆。那时候日子过得太慢， 你想长大。然后真的长大了！就在一夜之间，你的回忆里塞了太多东西，这些累赘成了时间的分母，所以日子越来越快。但得到的多了，失去的也多了。你会逐渐忘记青梅竹马的长相，忘记恩师的姓名，忘记你和朋友在树下埋下的宝藏（或许你们当时只是埋了个地瓜）。 后来你也被人忘记。 --- 以上不过是我对今年过得太快的一个吐槽。吐槽归吐槽，该赚钱吃饭时还是得好好打代码；想要精神充实，那只能多看几本闲书。鉴于今年阅读量不是很大，以下推荐的五本书几乎刚好占满了我今年评分为五星的书目。再多，没有啦\~ ### 《短篇小说课堂》 ::commend --- callouts: - 我把香烟弹到阴沟里，蓦的意识到原因何在，我不爱她，香烟嘶的一声熄灭了，和真相一样。 - 未经审视的生活值得一过，如果有人能够有幸一试。那大概是动物的生活，勇敢，机敏，凭直觉而非想法或决策行事，忠于伴侣，幼崽和族群。可能正如我们都知道的那样，过着十分有趣和幸福的一生。狗们在做梦，在清冷高空盘旋的老鹰 tags: - 📕 短篇小说 - 🎓 巴黎评论系列 它心灵的敏锐超出我们的想象。牲畜的平静使斯多葛学派哲学家蒙羞，什么样的批评家能拥有猫的机敏？我们一直用狮子的威严作为王权的象征，用一动不动睁大双眼的猫头鹰作为智慧的象征，用鸽子温和的美貌作为神之精神的象征。" - "我们通过感官感知这个世界，每当我们回忆往事，我们总会借助感官的记忆，以此来感受那些曾经存在、而今却消逝了的事物。仅仅想到“我曾爱过阿曼达”不足以让我感受到失去的爱情，我通过回顾她的笑容、头发上的气味，以及她皮肤上那道细小的疤痕， 才能体会到逝去之爱。只有具体感官细节的积累，才能准确地唤起怀旧的思绪——换言之，我们该听从写作艺术的古老训诫：切勿多说，展示即可。": null caption: 《巴黎评论•短篇小说课堂》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s30004902.jpg --- :: 这本是年初阅读的，由于时间过得太久，我甚至翻开目录，看到各短篇的标题后也不能回忆起故事情节来。不过，这丝毫不影响它给我留下的深刻印象：描绘故事的语言和故事本身一样伟大。 语言，我是说精巧的修辞，语句的节奏和段落组织。在各作者神奇的笔下，语言能迸发出强大能量。比方说，《飞毯》是为读者描绘似水流年的一篇短文，推荐《飞毯》的作家丹尼尔•奥罗斯科评论道：“（这种故事）很难写好，因为它们容易陷入多愁善感的境地—— 那是一种过度抒发的情感，也就是说，让人觉得造作而虚假。......《飞毯》读起来就像一则回忆录。主人公的叙述包含了他对孩提时期的记忆，用带有感情色彩的细节召唤出童年的一整个夏天。”而后，他解释了如何写好记忆细节的语言技巧， 也就有了上面推荐语录“...... 切勿多说，展示即可”那一段。 这本书集合的各短篇小说品质一流，且各篇背后也有解说与评论，所以不同担心看不懂，需要关心的反倒是当语言的能量一股脑涌入大脑时， 脑海里以往看过的短篇的形象可能会在它们的冲撞下变得支离破碎。 ### 《瓦尔登湖》 ::commend --- callouts: - 我住到林间，是想过设想中的生活，只面对生活的基本事实，看能否学到生活所要交给我的，而不希望到临死之际才意识到我尚未真正的生活过。 - 从没有一个人在晚上经过我的屋子，或叩我的门，我仿佛是人类中的第一个或最后一个人。 - 时间是供我垂钓的河，我从中汲水，却同时发现了河里的淤沙，意识到它是如何清浅。它涓细的脉流漫过，但留下了永恒。 - 人们赞美且认为成功的生活方式，只是千万种生活方式中的一种，为什么我们要推崇这一种生活方式而贬低另一种呢？ - 仅仅时光流转，也不一定带来他的黎明。那扑灭眼眸的光明，对我们仅仅意味着黑暗。而只有那一天的黎明才能将我们真正唤醒。更多的日子将被黎明照亮。太阳也是一颗晨星，如是而已。 tags: - 📕 散文 - 🎓 经典 caption: 《瓦尔登湖》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s29827205.jpg --- :: // 去年就想推荐了，今年看了新的译版，这本装帧漂亮，读起来都更舒服，推荐入手。 金钱，权力，名声，地位。.. 你认为抛弃这一切，难吗？也许对深陷世俗的人来说，这个问题简直无法回答。但对梭罗而言，这甚至不能被当作问题发问。 梭罗提倡人们用一种朴素的、精神充实的状态去生活，以度过每一个昼夜的更替。他也身体力行，孤身一人走进瓦尔登湖边的丛林，用借来的一柄斧子，打造住所，开辟出了自己的一片天地。梭罗在此开荒种植、游玩探索、读书写作， 将在此居住的两年多时光中的种种思考，浓缩为《瓦尔登湖》这本哲思气质浓郁的散文集。两年来，没有友邻作伴，有的只是来房间门口觅食的麻雀和进屋与主人捉迷藏的野鼠，但梭罗一点儿也不孤独。他拥有几乎所有现代人没有的勇气，自由选择生活的勇气， 只面对生活的“衣食住”这种基本事实，从自然中学习灵性。最终，他也学成了，专属于梭罗的自由——人没必要在游行和典礼中结队前行，而应随着自然的律动呼吸——这是与宇宙心脉相通的狂欢。 《瓦尔登湖》是一本伟大的书。 ### 《大雪将至》 ::commend --- callouts: - 有时候，当他在草地上躺得足够久的时候，他会感觉到，大地在他的背下十分轻微地起伏。在这样的时刻，他知道，这是周围的群山在呼吸。 - 他非常强壮，只是有些慢，他想得慢，说话慢，走路也慢，但是他的每一个想法、每一句话和每一个脚步都会留下痕迹，而且是精准地留在他认为应该属于它们的地方。 - 伤疤就像岁月一样，一个接着一个，一年又一年，所有的这些一起造就了一个人。 - 从一出生开始你就一点接一点地在失去什么，一开始是一只脚趾，然后是一只胳膊；一开始是一颗牙，然后是整幅牙齿；一开始是一点回忆，然后就是整个记忆，就是类似这样的，一直到某个时刻什么都没有留下来。然后他们把你最后那部分剩余扔进一个洞里 tags: - 📕 小说 - 👨‍💼 新锐作家 田土埋起来，然后就完了。": null caption: 《大雪将至》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s29779230.jpg --- :: 也许在我漫长的生命里并没有出现什么要加害于我的东西，所以我不大欣赏海明威的“一个人可以被毁灭，但不能被打败”这种激情澎湃的句子。相反，我喜欢《大雪将至》中主角艾格尔的坚韧气质。小说寥寥几万字，描绘了艾格儿从出生到死亡七十来年的经历。 他是私生子，在亲戚家刻薄的环境中长大，还因殴打瘸了一条腿。人生何其漫长，每一年你都在长大，但每一年你都在失去点什么。自艾格尔从亲戚家出逃后，他经历雪崩，痛失妻子；战争，目睹好友的死亡。所有生命的馈赠终究还是要从他手中夺回去。 “但是他一直活着”，作者写道。这种坚韧气质并不是众所周知的英雄气概，反而是一种白开水味，没有威士忌配菜的，平淡无奇的继续。艾格尔用瘸了的腿继续行走，他非常慢，慢到能看清生活的真相，看透自己的死亡，但他依旧挺直腰板，从容前行。 每个人的人生都是一场漫长的死亡。我们从死亡的山底出发，一步步向上攀爬，途经山腰，饱览风景，但也不能停下，直到接近山巅，迎接风雪。山顶倒是没有闪电和雷鸣，只是大雪迟早会没过头顶。那时候，我们会愤怒着、咆哮着，向神索取曾经被剥夺的一切， 还是安然长眠呢？作者为艾格儿做出回答：“他的生命里现在没有任何人了，但是他有他所需要的一切，这就够了”。 ### 《大教堂与集市》 ::commend --- callouts: - 通常，那些最有突破性和最有创新力的解决方案来自于你认识到你对问题的基本观念是错的。 - 好的软件作品，往往源自于开发者的个人需要。 - 优秀的程序员知道写什么，卓越的程序员知道改写（和重用）什么。 - 开源社区最强大的一个长项就是非中心化的同行评审。 - “玩”是创造性活动中最具经济效能的工作模式。 - |- 「黑客的态度」 1）这个世界充满了迷人的问题等待人们去解决。 2）不要解决一个问题两次。 3）无聊和乏味是有害的。 4）自由是件好事。 5）态度不能代表能力。 tags: - 📕 杂文 - 💻 计算机 - 🌊 开源运动 caption: 《大教堂与集市》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s28026215.jpg --- :: 前阵子找工作的时候，HR 曾问我，“日常开发也许是非常枯燥和繁琐的，没有那么多有趣的问题给你研究，你怎么去面对这种情况呢？”我几乎不假思索地回答，“所有代码细节的背后，都有更深的细节可供挖掘。我不愁日常工作枯燥无味， 因为我总能用玩的心态去发现及解决新的问题”。之后，我的同事评价我说：“是个能自己创造需求的人”（其实就是找出并解决一些无关紧要的问题）。 看过的作品会在不经意间影响自己的观念，从而影响行为。回顾《大教堂与集市》时，我发现“黑客的态度”居然深刻地指导了我现阶段的学习与工作。虽不说观念到底是正确与否，但这种给自己带来改变的感觉是非常奇妙的。想体验的朋友，“此书完全值得一试”。 ### 《八百万种死法》 ::commend --- callouts: - 警察看过太多的死亡和惨状，为了今后继续面对这些，他们往往需要把死者非人性化。我还记得我头一回从旅馆房间抬尸出门的经验。那人吐血而亡，死后多日才被发现。我和一名资深巡警费了九牛二虎之力才把尸体塞入尸袋。下楼时，每下一级楼梯 tags: - 📕 小说 - 🔫 悬疑 我的搭档就任由尸袋磕碰一次。就算抬一袋土豆，他也不会如此大意。……后来，我成了那个抬尸体下楼撞楼梯的人，数钱分钱的也是我。风水轮流转。我在想，总有一天，尸袋里的那个人会是我。" - "如果我胆大我会跳窗。我可以坠到一半改变主意然后笑完另一半距离。但我胆子不够而刮胡刀片又不能用。一切都是徒然。美好时光已经耗尽。钱斯，抱歉。你带我见识美好时光，但一切皆成过去。棒球打至八局人群已散尽。所有欢呼已成幻影。 比分多少又有谁在意？无人愿意为我一掷千金。无人愿意与我共结连理。无人愿意救我一命。我已倦于微笑。我已疲于奔命。美好时光已成为过去。" - "有句名言说“理解一切就能宽恕一切”，要是我知道了他的整个人生，也许就能理解他的嗜血欲望来自何方。但我不是非得宽恕他不可。宽恕是上帝的职责，不是我的。": null caption: 《八百万种死法》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s33601900.jpg --- :: 每当我向别人推荐这本书时，都会附带一句：“《八百万种死法》并不是真的讲了八百万种死法”。其实故事描述的只是主角在有八百万种死法可能性的城市里破案的经历。案发城市浸泡在荒诞中，和酒精、妓女、谋杀案一起，发酵，把惊险的破案经历酿出了独有的风味。 读起来颇有《仿生人》的味道，但限于水平，我讲不清楚其中的联系到底是什么。 ## 2019 荐书 2019 是无情的一年，所有事情都背叛了我的想象。能力所限，我总觉得能把握住的事情越来越少，以至于在我狭隘的世界里，能随心所欲地阅读成为了一种相当慰藉的温暖存在。 我通常会一股脑看一堆话题相关的资料，比如，年末我看了几部关于量子物理方面的科普，甚是喜欢，所以额外找来一些纪录片看。不过，看得多并没有记得多。和常人相比，我感觉自己的记忆非常不可靠。充斥我的大脑的记忆，是混沌的，且极易被篡改。 好在，我鲜有回想与总结的习惯，“真相”对我来说并没有那么重要。另外，“记忆中的形象一旦被词语固定住，就给抹掉了”。所以原本我想写一篇年终总结之类的东西，想一想之后还是放弃了。在此，就用推荐十本书象征性做个年末回顾吧。除了因为它们本身精彩， 想推荐给其它人之外，这十本书贯穿了我整个  19  年的生活与思考，象征着我对  2019  最深刻的嗅觉与触觉，是我向过去寄出的一封信，是我整个狭隘世界的还原。 若无特别说明，书目按阅读时间编排。除去专业书籍和私人书目，剩下的是好读的作品。 ### 《学习之道》 ::commend --- callouts: - 我把艺术看作是一项运动，它朝着真理的方向渐行渐远，就如同我在穿越一个隧道，我越是往前走那隧道就越来越深邃，越来越宽广。我对象棋这个游戏了解得越多，就越能体会到还有无数的知识是我们所不了解的。我就是这样一路走来 tags: - 👨‍💼 自传 / 小说 - 🎓 学习方法论 - ❤ 元认知体验 怀着一颗谦卑的心和对神秘莫测的象棋深切的崇敬之情，从每一段美好的岁月中走了过来。" - "成为他人眼中的巅峰人物与生活质量之间毫无关系，我所追求的是内心的宁静。我学会了如何化解进攻而纹丝不动。我发现自己算计得少了，但感觉得多了。" - "你要和它有相同的愿望，说同样的语言。你不要去破坏马的精神。母亲继续说：‘如果你是直直地朝一匹马走过去的话，它会看你一眼然后就跑掉了。你没有必要这样正对着马的方向。不要面对面，从旁边慢慢接近它就可以了。连一匹成年的马也可以被驯服， 你要做的只是友善地对待它，并把你的意图转变成它的意图。’": null caption: 《学习之道 The Art of Learning》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s33650964.jpg --- :: 就算脑科学研究得再透彻一些，透彻到足以指导学者们写出对大众而言更普适的学习方法指导书…只是哪怕再多“One Paper Book”的灵感可能都不及这本书给人的启发。原因很简单，这是一本小说，用自传的形式写的一本关于“如何学习”的书， 它摆脱了教条与传统的方法论，有血有肉，食之有味，所以能从缓缓流露的故事中体会作者到的思想。 这本书翻译为《学习之道》并不合理，直呼原名《The Art of Learning》才能彰显其哲思气质。作者并没有着力于指导读者使用他的方法论进行实践，其实书中也根本没有单独提到什么“方法论”。 作者用流畅的故事叙述铺陈开的是他在生活过程中的思考，因为这种思考并不是直接的学习方法，只是一种第三人称的阐述，所以能从中体会一些作者的认知方法。作者希望你能从故事中领会他的认知观念，如序言所说：“忘记那些数字。 去真正去掌握那些最能引起共鸣的信息，并将其彻底地融合，直至成为一体，这样才能随心所欲地驾驭它”。 总之，阅读本书是一段灵感迸发的美妙旅程。 ### 《黑客与画家》 ::commend --- callouts: - 做一个异端是有回报的，不仅是在科学领域，在任何有竞争的地方，只要你能看到别人看不到或不敢看的东西，你就有很大的优势。 - 判断一个人是否具备‘换位思考’的能力有一个好方法，那就是看他怎样向没有技术背景的人解释技术问题。 - 当今时代，其他行业的人，都必须依附于流水线的工业化生产才能谋生，除了艺术家，几乎只有程序员可以靠个人手艺谋生。程序员就是数字时代的手工艺人。如果编程与绘画和写作是同一类工作，黑客是否有机会像伟大艺术家一样备受尊崇、流芳百世？ - |- 「黑客伦理」 1）使用计算机以及所有有助于了解这个世界本质的事物都不应受到任何限制。任何事情都应该亲手尝试。 2）信息应该全部免费。 3）不信任权威，提倡去中心化。 4）判断一名黑客的水平应该看他的技术能力，而不是看他的学历 tags: - 📕 杂文 - 💻 计算机 - 🌊 互联网 年龄或地位等其他标准。\n5）你可以用计算机创造美和艺术。\n6）计算机使生活更美好。": null caption: 《黑客与画家——硅谷创业之父 Paul Graham 文集》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s4669554.jpg --- :: 如果说小说是把观点隐藏在故事中，那杂文正好是反过来操作的：它直接披露观点，而故事往往只是副产品。多说一句，你必须相信我的是，尽管都是“讲道理”，鸡汤和杂文却有本质的区别，前者负责跳过故事过程描绘结果，后者的结果是基于过程的预判（ 通常建立在理性批判的基础上）。 书的作者是一个极优秀的工程师，这种身份注定了他在某些观点上偏激，尤其相关技术方面。所以才铸成了《黑客与画家》这样一本充斥着个人意见的杂文集。人们谈论此书时往往针对书中那些看起来傲慢的、充满批评意味的观点大声反驳，比如有人评价道：“ 此书就是一本 Lisp 语言广告”，但他忽略的正是作者高瞻远瞩的预判，那才是体现作者逻辑合理、思想深刻的地方。如《设计者的品味》一文中说道，“设计是简单的、解决主要问题的、艰苦而具有启发性的。.. 看似容易的再设计”， 虽然作者对此做的说明都是基于个人的思考与想象，但其描述与当今流行的奥卡姆剃刀原理、席克定律、泰思勒定律等普适原则不谋而合，此段堪称全书最佳。 从某种角度而言，能让你全身心投入，赞美、膜拜亦或批判的文章都是好文章（我是说杂文）。想来检验你对技术工作、对互联网是否一无所知的话，《黑客与画家》是一本极其经典，绝对值得一读的好书。 ### 《莫泊桑短篇小说精选》 ::commend --- callouts: - 大艺术家就是那些将个人的想象力强加给全人类的人们。 - 我们所爱的，常常不是一个男人，而是爱情本身。那天晚上，月光才是你的真正情人。 - |- 后来他们开始安安静静讨论起来，用和平而智慧有限的人的一种稳健理由，辨明政治上的大问题，结果彼此都承认人是永远不会自由的。 然而瓦雷良山的炮声却没有停息，用炮弹摧毁了好些法国房子，捣毁了好些生活，压碎了好些生命，结束了许多梦想 tags: - 📕 短篇小说 - 🌈 通俗易读 许多在期待中的快乐，许多在希望中的幸福，并且在远处，其他的地方，贤母的心上，良妻的心上，爱女的心上，制造好些再也不会了结的苦痛。\n\n 这就是人生！索瓦日先生高声喊着。\n\n 您不如说这就是死亡吧。莫利梭带着笑容回答。": null caption: 《莫泊桑短篇小说精选》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s28637162.jpg --- :: 莫泊桑之所以为短篇小说之王，并不只因为他写过几乎所有人都在课本中读过的《羊脂球》或《我的叔叔于勒》——这两篇固然是一流作品——但他深厚的笔力其实隐藏在数目众多的作品集里。这本精选集，充分地把莫泊桑精巧的短篇布局能力展示出来。 他的短篇情节巧妙，气氛合理，语言朴实，读来简单，也道理深刻，不让人觉得轻浮。 相比人人喜欢的欧亨利式的绝妙反转与夸张的幽默，莫泊桑在作品中展现的情节反转和幽默毫不逊色。除此之外，他平实的语言，给叙事带来丝毫不拖沓、不刻意的画面感，换言之，“气氛”。《散步》是整本中我最喜爱的一篇，虽然情节简单，但是他描绘出的气氛—— 关于渺小的绝望与存在的无意义等气氛。情绪混杂在气氛中由缩影瞬间炸裂开的那刹，我似乎和主角心意相通，并为之深深震颤。 > 他听见周围、头上、到处都响着一种混乱的、广阔的、继续不断的、由无数不同的声音组成的嘈杂声，这种低沉的嘈杂声，近处有，远处也有，是生命的既广泛又巨大的悸动，是巴黎的呼吸，巴黎正像一个巨人似的呼吸着。 > :name[《散步》] 这就是我心目中超一流的作品。所以看到豆瓣有人评论因情节简单把《月光》和《散步》等短篇看作水准欠佳，在此，我表示水准欠佳的一定不是作品。..... 更多具体的细节就不剧透了。总而言之，莫泊桑的许多短篇好读且好看。 ### 《一只特立独行的猪》 ::commend --- callouts: - 有些话仿佛永远讲不出口，仅仅是因为别人已经把反对它的话讲了出来。 - 在我们年轻时，每一年的经历都能写成一本书，后来只能写成小册子，再后来变成了薄薄的几页纸。现在就是这样一句话：读书、写作。理想主义的光辉已经暗淡，人类不再抱着崇高的理想，想要摘下天上的星星；而是把注意力放到了现实问题上去 tags: - 📕 杂文 - 👨‍💼 王小波 当一切都趋于平淡，人类进入了哀乐中年。" - "人在写作时，总是孤身一人。作品实际上是个人的独白，是一些发出的信。我觉得自己太缺少与人交流的机会。": null caption: 《一只特立独行的猪》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s29419061.jpg --- :: 说起王小波，不得不先提连岳。有人曾强烈推荐我看连岳的文章，所以我看过不少他的随笔。其实并不是出于喜欢，而是想找到不喜欢的理由。理由一直没找到，直到今年看完这本文集。 且说连岳，他的思想很前卫；文笔流畅，行文引经据典，议论扎实。这种行文风格大可在小波的笔下找到踪影。（在连岳的《予人慧命者的王小波》一文中，有其崇拜小波直至魔怔的描写：“对我来说，王小波的死是一种生活方式的开始，在很长一段时间内，我在模仿他， 他的文风、他的思维，然后到处推销他，就像被鬼上了身。”）然而王小波的文笔再好模仿，有一点连岳没有——说真话与讽刺。连岳能写：“生活与投资的核心是乐观一点，勤奋一点，长长本事，相信自己能够让家人过上好日子，就行了。”；而王小波能写“人也好， 动物也罢，都很难改变自己的命运。”。前者的政治正确太过乏味，而后者却能极大地引起我的共鸣。 政治正确是什么？读连岳的文章，你会发现尽管他的观点标新立异的，但是其内在，无时无刻不在“维护读者的利益”，也就是在“宠着”读者，没有“真话”，以至于你不能大声反驳他。这是一种不正常的状态。一种“不能证伪”的观点，不算科学，也不算智慧， 并不值得稀罕。 好了，多说无益，和我一起来看王小波吧，体会纯正的小波派文笔和小波牌批评。只要你心里曾经住过一个追求智识、迷恋自由、浪漫与逻辑并存的有趣小孩，那小波的文字就能从你的灵魂里，生出一团火来。 ### 《事物的味道，我尝得太早了》 ::commend --- callouts: - | 玩耍着背了母亲， 觉得太轻哭了起来， 没有走上三步。 - | 浅草的热闹的夜市， 混了进去， 又混了出来的寂寞的心。 - | 筱悬木的叶子落下来触着了我， 以为是记忆里的那个接吻， 吃了一惊。 - 总之歌这东西不会灭亡的。我们因了这个，也就能够使那爱惜刹那刹那的生命之心得到满足了。 tags: - 📕 诗歌 - 🌸 日本文学 caption: 《事物的味道，我尝得太早了》 src: https://mgear-blog-image.obs.cn-east-3.myhuaweicloud.com/douban/s28685720.jpg --- :: “这一生要永远读诗。寂寞的时候，念一首石川啄木。”，一首就够了，清澈的忧郁和细腻的敏感要是一股脑吃多的话，反而会索然无味。 石川啄木是个一生贫病交加，26 岁就早早殒命的诗人。读他的诗，会发现这种东西真是只有经历过痛苦的人，才能写出来；也会在译者注中看到，在活着糊涂且开心与痛苦并清醒之间，石川啄木多次作出的抉择。 我推荐你在床头放一本，以便不时翻阅一下，重温体会之精妙。 ``` ``` ### 2019 下期预告 如果不鸽的话： - 罗生门 - 日本未来时 - 仿生人会梦见电子羊吗？ - 怦然心动 - 瓦尔登湖 注：已鸽（2020 年 8 月 5 日 01 点 47 分） # 🚝 四十二篇系列 ## 四十二篇是什么 #### 增订 | 2025 年 02 月 14 日 100 毫克讽刺，肌肉注射。 #### 增订 | 2024 年 06 月 12 日 四十二篇曾经的定位是记录工作相关的碎片化的灵感，但这样太过局限，所以现在用于记录灵感闪现（暴论警告）。写作方法是先起个标题，然后想到哪里就写到哪里。文章也许有主线，也许全是无厘头内容。 #### 原文 工作中每天都要写日报，将每日工作相关的 3P1T（Progress、Plan、Problems、Thinking）记录下来。写日报这个制度其实本身平平淡淡，就像在上家公司时，日报制度基本等同于和主管对齐一下进度。 我相信如果有合适的方法论的指导，任何事的运作都会变得更高效，那就从日报开始改变！为了使日报的效比更高，我在探索某些奇奇怪怪的方法论。比如说尝试把 Thinking 当作灵感闪现的记录，这样就不会陷入每日无思考， 导致 Thinking 项空缺的境地。每三个月左右的时间，我将这些碎片化的灵感重新整理一番，看看其中有哪些值得记录进笔记或详细阐述的东西，这就是我的《四十二篇》。等《四十二篇》系列完结时，也就是再过十年，等我成我别人口中的佬的时候， 那会儿再重新翻翻这个系列，也许能从里面找到点别的东西。 ## 四十二篇归档 - 第四篇：[盲视](https://lionad.art/flows/_forty-two/blind-sight) - 第三篇：[人之为人](https://lionad.art/flows/_forty-two/as-human) - 第二篇：[成熟的小孩子](https://lionad.art/flows/_forty-two/mature-child) - 第一篇：[有关新项目的方法论](https://lionad.art/flows/_forty-two/dark-room) # 🌃 长夜梦 最近总是梦到自己站在冰天雪地里吹冷风，让我想起了刚开始弹吉他的那段日子。我从高三就开始弹琴，至今八年了。现在我喝了酒，我要说一些有关吉他的伤心话，也许以后会后悔自己说过这些。 :iframe{border="0" frameBorder="no" height="150" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=659423&auto=0" width="355"} 高中那会儿，聊天还用短信，听歌还用天天动听，视频资源要花不少力气才能下载到。南方冬天最冷的时候，我裹着最厚的外套，带上 iPod Touch 去教职工宿舍蹭网。通常我会只看标题便缓存一堆视频， 而这些视频只有周一到周五我一个一个点开时才能知道里面讲了啥。 我记得有次午休的时候我点开了 Gin 的《Atlantis》。也许是 Gin 演奏时混响开到了最大，他的木吉他泛音演奏使我溺水，给我带来不可名状的冲击。那年，我把红包偷偷藏起来整整一千，然后乘着回到学校的周末，跑遍城里的琴行， 挑了一把不错的新手琴。我先是学了《爱的罗曼史》，把手疼熬了过去，然后着手一句句的学押尾的《黄昏》。我还能清楚记得弹完《黄昏》后的某个周末站在冷风中蹭网时，我兴奋地用百度一个劲儿搜“一个月弹完《黄昏》是什么水平？”。 这之后我看了押尾许多 MV 和演奏视频，毫无疑问的成了他的迷弟。印象最深的是《Big Blue Ocean》里面有一段主人公在沙滩下车后直接奔向大海的场景，这让被困于读书考试的我羡慕不已。后来我用网易云时，特意找到这曲子留下了评论。 > 真是封神的曲子，就连做梦我都想着。翻到优酷的 420p 大蓝海的时候，从来没感觉 mv 有这么好看过，迷了我一个礼拜！ > :name[2016-12-25] 那时候指弹还是一个冷门的词，大部分人都不知道木吉他除了可以给唱歌做伴奏以外还可以独奏。我身边没有水平相近的朋友，以至于刚上大学不久，我就自认为在技术提升上遇到了瓶颈。有天我坐公交车去学校，瞥见路边有密密麻麻一堆的乐器店， 于是立马下车反方向坐回去，然后从西一路走到东，每家乐器店都进去打听有没有教指弹的老师。答案自然是没有，所以只好傻傻回学校继续瞎练。 有阵子一直在练押尾的曲子，他的歌要用上各种技巧，劈里啪啦，非常吵。我喜欢一个人到学校角落的小树林去，那有环着小池子的爬满藤曼的亭子。有时坐亭子里，有时坐草地上。风有些冷，但太阳照过来暖和呀。时常有我叫不出名字的小鸟在藤曼织成的洞里翻来跳去， 又或者在假山边打转儿。亭子外面，水面浮光跃金；鱼翻起一个不起眼的浪花，惊起了一群鸟，它们接连飞起来，在天空中连成一片，在树林顶上绕一个大圈，再飞回来，藏进看不见的地方。其实我记不清池子里有没有鱼了，只知道曾经在岸边努力地想看清水底， 但是水面下黑黢黢一片——我在这池子里掉过两个变调夹——兴许它们现在还躺在漆黑的水底。 太阳从前面照过来，绿荫婆娑在脸上划过阴影。累的时候可以直接在这小憩。闭上眼睛会突然发现，这地方其实热闹得很：不远的草地上有几个男孩子在背单词，走走停停；再远点儿的地方飘来断断续续的铜管声给他们伴奏；有鸟叫，有风穿林过， 兴许是远处的车呼啸而过，这些声音拥挤在一起，跌跌撞撞，稍显笨拙。就这样一直闭上眼睛，听着树林的呼吸，直到太阳逐渐变冷。 那时我弹琴有一种狂热的劲头。一遍遍重复练习，其它琐事抛到脑后；从早到晚抱着琴，弹到家里人比我更先不耐烦。现在我知道那是我没有归属感表现出的征兆，像一个孤独的孩子要开始谈恋爱一样。 我忘记怎么加入的吉他社，只记得学长收完会费后每周喊大家出来练琴的次数越来越少。不过，那时倒是交了不少长情的朋友，大学时不时聚在一起，或者跑来跑去。期间我换过两把琴，先是把新手琴换成了入门琴，然后大三时还借钱买了一把自带效果器的琴。 那把吉他有着一款乌黑指板，面板上拼接有金色木纹，非常漂亮。有了电箱的加持，我终于有机会学《Atlantis》。如果说弹琴的动力不过是一首又一首曲子支撑起来的梯子。我的梯子上排列了押尾一连串的曲子，而梯子顶端是 Gin 的《Atlantis》 。 不知道从什么时候起，我开始在各种地方弹琴。有次受一个琴友会上认识的朋友邀请，跨了半个南昌去他们学校给社团表演时，我突然意识到，我一直热爱的弹琴只不过是一种玩耍般的消遣，我为自己曾经以为提升了多少技术而感到羞赧。 我单纯想学会几首好听的吉他曲子，但没想到要在技术上有多深的钻研。这像极了筹划婚礼时唯独准备了焰火和礼花。 工作以后很少弹琴了。时不时把吉他捡起来摸一摸，我清楚这是敷衍。吉他对我来说更像个谈了八年恋爱的女朋友，往日热情消散，我却还对她不甚了解，别提要打起整天腻在一起的精神来了。我曾做过技术上登峰造极的白日梦，然而回到现实，却是想和吉他分手。 换句话应该说想找解脱。后来有女孩子说喜欢我弹琴的时候，我心中又泛起欢喜，想起在小树林弹琴的日子，想起顾城的“草在结它的种子，风在摇它的叶子”。 她给了我一本北岛诗选，我欢喜的不得了，心中也有别样的想法在萌动，有风轻摇。这八年来我弹琴弹得断断续续，也没有进行过专业的音乐训练，所以水平一直没很大长进，这两点是我最大的遗憾。就像北岛《波兰来客》中描述的，这是我吉他梦的破碎。 如果可以反悔的话，我大概从一开始就不会碰吉他，转而一心一意投入到代码中去。奥，这种想法一定是在潜意识中酝酿了很久，念头不断冒出，所以印象越加深刻，以至于现在我熟悉到可以顺理成章地说出来！可是许多美好的回忆还历历在目，害， 到底应该怀着怎么样的心情！她的分手就不是冷静的故事，一想到分手的现实她就悲从中来，找到曾经的照片一张一张翻出来看。不过这也真是自欺欺人呐！依我弹琴的经验来看，回看过去录制的视频，恐怕只会更心痛吧。已失去的欢愉冲淡不了此间悲伤， 反而让人心生悔意。如果曾经更加投入的话，如果曾经更用力的拥抱和爱的话，现在就一定处于不一样的境地了吧！夜梦阑珊时常常留下无声的眼泪来，这样折磨人的感情，宁愿从一开始就不要好了。 > Dance to the plastic beat / Another morning comes :br > 伴着我脆弱的心跳舞动 / 又一个清晨又来临了 :br > I'm just playing games / I know that's plastic love :br > 我只不过是在游戏人生 / 我晓得那不过是塑料般脆弱的爱情 :br:name[*Plastic Love*] # 🌌 万物联结与幸福感 初次接触“联结”时，它带给我一种强烈的情绪震撼。其成分复杂，但主要是幸福感。 大三期末的凌晨，我在床上辗转反侧，无法入眠。 那时，我因精神不济，从学校搬到了外面。那是一栋老旧的三层楼，离校不过两三公里。房东是一对年逾花甲、卖粮食的夫妇，他们将顶层以极为优惠的价格租给了我。 上半学期常常跑回学校，有时出校门已是晚上十一二点。那时的我骑着小黄车，顶着秋冬的瑶湖寒风，从宿舍出发，穿行在灯火通明的街道上。五分钟后，便会拐进一条漆黑的小巷，走过一个空旷、弥漫鱼腥味的菜市场，最终抵达那个临时的“家”。 虽然骨子里有着叛逆的基因，我其实是个安于现状的人。无论居住环境如何简陋，我总把它称作“家”——即使那座顶层的阳台上，水泥涂抹得不均匀，角落里散落着破碎的砖瓦，甚至在阳台上，几米远的邻居屋顶上，偶尔能看到一只老鼠。 这些景象给我带来一种被城市遗弃的错觉，魔幻般现实时常令人感到不安。然而，奇怪的是，床给了我绝对的安全感，黏着枕头不到两分钟，我便能安然入睡。 然而，今晚辗转反侧。 “再过半个学期，便要面临寻找实习的压力，而我甚至连自己编程的方向都未曾确定。” 我听到自己在床上翻个身。 房间里很黑，电脑上蓝色电源灯在微弱地挣扎。我模仿它挣扎片刻后，便用被子捂住头。 “一个喜欢敲代码，同时也是一个十几门科目不及格的人。”，我在嘲笑自己：“一个冷漠的旁观者，一个被抛弃的人。”。我起身拨动了吉他的弦，干枯、索然无味。又躺了回去。 弹簧惨叫。 “一个无趣的人，一个无人喜爱的人。”，脑海中的声音越来越多，从房间的四面包围过来。黑暗中一种褐色的情绪藏在被子里正在发酵，像是矿物在结晶，从石头中长出的手——魔鬼的手！——刀般寂静的夜里，若有若无的风声中，黑色幻肢在敲打我的窗户。一声一声， 我的脑海里有东西随着一次次破碎，有蓝色大海从远方漫过头顶，我在寂静里溺水。 思想随着白色的海潮翻滚，与碧绿一同，破碎在沙滩上。紫红色的天幕下，海的最远处，船的鸣笛打破沉寂——我猛地推开阳台门，冷风如潮水般灌入房间，仿佛溺水者终于突破水面，痛快地吸上一口气。风中有草和泥土的香气。 站在阳台上能感受有雨点从天心落下。点滴而来，顷刻变得密集。 冬末的雨，带着缠绵的细腻与稀疏有致的美感。一滴两滴，飘落眉眼。我抬起手，迎接天降的雨水，感受着雨点轻轻覆盖在手掌上，触感如托起灵魂的丝绸，心灵也变得柔软。忧虑与孤独，在这一刻悄然消散，思绪随这点滴的雨覆盖到了世界上每一个细小的角落。 雨点融化在沙子与泥土间。土地的裂缝里，有草在摇曳着种子。树林哗哗作响，仿佛风也在藏雨里震动。 在雨中，有人祈祷，有人皱眉在房檐下避雨，也有人张望远处灰色的天际线。这场雨占据了星星眨眼的瞬间及，这是世界上最宽广的爱意，无论是凶险或者是仁善，一切都在雨里。万物似乎在这一瞬间联结，一些独特美妙的情绪在脑海绽放，滴水融入清泉， 焰火消弭于夜空，伴随一种巨大的、包容的力量，热流在体内激荡澎湃，远处有千年前的钟声在敲响和回荡。 打开网易云，一抹极轻的《Merry Christmas Mr. Lawrence》开始流动，而我像是大病初愈般萌生出，“无穷的远方，无数的人们，都和我有关”这般念头。 :iframe{border="0" frameBorder="no" height="86" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=4899152&auto=0&height=66"} # ⌛ 偷取时间 > “双手手掌都有四条横纹的人，就是能偷时间的人。” :br > “只要是那样的人，都能偷别人时间？” :br > “不是，有些四条横纹的人，并不知道自己会偷别人的时间。” :br > “怎么偷的？你刚才说双手他们拍别人双肩？” :br > “从脖子上，那需要手一前一后的，卡一下，一秒钟不到就可以了。” > :name[《天才在左，疯子在右》] 我听说过各种窃贼的故事。这些窃贼会莫名的心生占有欲望，而被窃的物品种类似乎找寻不出规律来，可能小至外出聚餐时店家的一双筷子，大至隔壁邻居家的小女儿，都是他们一心向往的对象。 在此坦白，我也是一名窃贼，不过我偷取时间。 :iframe{border="0" frameBorder="no" height="86" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=3546649&auto=0&height=66"} 我住的地方在上海一个潮湿的、密封的小角落。因为房间内终日不能得到光照，我又只喜欢开一盏瘦弱的黄色节能灯，以至于这里看起来终日都是阴暗的。虽然住处环境对一般人而言是状况不佳的，但对我来说却绰绰有余，它的确能够充分提供我独居所需要的一切—— 其实一个稳定的、隐秘的、可以锁上链条的空间就足够了。我倒是住的舒服不想花太多精力挪窝，其实这与方便我我我偷取时间有关系。 我从时间漏斗中偷取时间——漏斗太过抽象，我宁愿称呼它为“神”。 我一心想占有的是那种黑色黏糊糊，流沙状的时间，因为只消得在“神”之下放一个满满的烧杯，就能看到中流下绵延不停的细沙状物品填满了烧杯。不得不提及的是，我不是化学毕业生，我没有烧杯，所以一般情况下我会用红酒杯 🍷 或者各种颜色的饮料瓶替代。 在我等待时间缓缓装满瓶子的时候，我通常会选择 Coding 或者 Reading 的方式增强自我的体验感，不然会经常出现呆坐才不过多久就惊闻工作日的闹钟突兀响起的尴尬情形。 最适合占有的时间大多数在周末的晚上，或者。..... 更确切地说是在凌晨，因为那是最纯正的黑色。经过无所事事的白天（我早已放下了无所事事所带来的负罪感，反而对一周只有 2 天全身心休息的时间感到乏味。）， 我需要用流沙状的东西涂遍全身缓解一些像是骑着野马即将扫荡平原而来的广泛焦虑。同时（有一点点私心的说），为了回馈时间漏斗，我以往经常要付出一整个上午用作祭祀。 不过，无论有多少正当或者不正当的理由，偷取总是贬义的行动，窃贼往往落得悲惨的下场，就像《赡养人类》中偷取空气的人类最终会被法律赶出地球一样（那真是一个好故事），而我不得不采取这么贬义的行动。关于这点，这世间千千万万的人应该都和我一样。 因为，大部分时间都染了蛀虫。 一方面，睡眠虽然重要，但是耗时却是事实，我常常羡慕那些一晚上只要 6 个小时（或者更少）睡眠的人，他们可以享受更多的对时间的体验感。 而真正的罪恶却在我们自身，我们生活中总是主动的丢弃“四分之三”的自我——总是活成别人期待的样子，无论是爱人朋友的期待或者父母的期盼也好——丢失“四分之三”的自我对时间的体验感。 社会中充满误导，广告巨擘们正在一心塑造消费让人获得生活品质与满足的生活观念，如同企业家们挥动驯狼的大棒指挥恶狼们对不可描述的东西扑咬，也正是玩弄政治的人耍的那些、\*beep\*的阴谋一般。花时间换取什么？人不再是人，社会不再是社会。 我曾迫切希望人与人之间的隐秘的链接越多越好，这样能促成一个文化完备的、真善美的，属于地球人的生活指南的建成。不过现如今只发现所有人的生活都满目疮痍，若是说时间才是真正的财富的话，那这个时间上欢笑的应该是那些偷取他人时间的人了。 我们失去了独处的时间，也失去了与朋友们的一同欢笑；失去了周六的咖啡和“星期天的啤酒”；失去了和一只懒散的猫在阳光下看一本好书的机会。虽然说“失去”太不严谨了，但是只有这样才能体现人们处在剥夺与麻木的激流中是如何失去自我的。 处在激流中，我暂且认怂。 我不会学习那些偷窃别人时间的窃贼，只是。..... 我从神的手中偷取时间。 ## 增订 | 2020 年 8 月 7 日 从去年 10 月份开始，换到了一个能晒到太阳的地方住。十分遗憾，现在已经找不回“看到时间里的蛀虫”这种感觉了。 # 🌆 表达和孤独 每每读完一个构思精巧，结构丰满的短篇小说，我总会发自内心的赞叹，并惊讶于其在极其有限的篇幅中描绘出的一个完整的故事。那些栩栩如生的时代背景、跃然纸上的人物形象、错综复杂的情感纠葛，不过寥寥数页。作家通过精心编排的情节和考究的对白， 使得人物的情感或明亮或黯淡，深深打动我。然而，我常在心中提醒自己，这种触动并非真正的共情。 不如说人与世界之间或许并没有真正的理解。 我们用来传递自我、与他人沟通的语言，实在过于脆弱。以文字为例，词汇的多义性和固有的情感色彩常常让我们迷失其中——我们的表达总是充满了主观偏见和先入为主的假设，言辞自以为准确，却往往浸透着情绪的煽动与不必要的指向。 在我毕业后转行做程序员的这年，我深刻感受到了这一点，比如“码农”一词，在不同人嘴里传达的意味截然不同。程序员们大多以一种谦逊的姿态使用它，背后或许隐藏着自豪；然而外行人提到这个词时，往往带着戏谑和贬低。这里的差异， 正是由于不同的价值观和立场使得交流变得词不达意。而诸如“攻城狮”和“程序猿”之类的词汇，则更显其表面轻松，实则隐藏着对某一职业的偏见，这种潜在的情感色彩，未免让人感到危险。 表面上，迷惑性的词汇似乎能煽动情感，另一方面来看，这只是在培养单视角的认识。语言的目的并非让人真正理解某物，而是构建出一种无形，在一些场合，倒像是杀人不见血的兵器。每个人都是独立的个体，拥有独一无二的过往、现在和未来， 又限于时间的泥淖无法自拔。过往的经历深刻影响着对世界的理解，复杂的现在又是偏见筑起的堡垒，交流只是面向偏见达成共识。 被误解才是表达者的宿命。 这让我想起了另一个词——“生长的孤独”。它形容的，正是我们在夏天尽情生长、肆意张扬，而随着年龄和经历的沉淀，我们终究会被困在一场冬日的孤寂中。换句话说，人与世界间的隔阂，可以被看作“个人的孤独感”，这是一种从出生便带来的、日积月累的特质。 这种孤独感如影随形，即使身处人群之中，内心的孤独依旧难以消弭。 或许，与其在这虚无的追寻中挣扎，不如倒满一杯酒，开始自得其乐，不再计较与世界的连接与隔阂。无论是与世界共振，或独自承受，终究只是一种选择。 :iframe{border="0" frameBorder="no" height="86" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=1374469061&auto=0&height=66"} ``` ``` # 🌧️ 我的腼腆 每次想起你说我的腼腆，我就想起这么一首诗来。 ``` ``` 并不是不需要说话，一方面我在辩解世界上本就没有那么多要表达的东西。 如果是交心朋友的话，相互了解是表达的最终目的，期间经过的一切并不可期待，毕竟被误解是宿命的存在，哪怕你将想说的东西精心写下、装订、编印成册，最后在封上书皮烫上几个金字， 别人也可能只会随心所欲的翻看，笨蛋一般地将文字间泛滥的情绪看成他想看的内容。 所以我们才会对默契及共情有所期待——我不期望与你同年同月同日共生共死，也对世人所说的喝酒交心并不感兴趣，但是我想读懂你的文字，了解你的内心，想和你对视而笑时撞出灵犀的火花。 也想看懂你眼里的悲哀，眼里闪烁的光，那是世界上最精妙复杂的表达。 饱含情感的眼睛啊，是不会被误解的！ ``` ``` # 🥛 新工作，喝新饮料 ## 通天晓软件 没什么心思去挑新饮料喝。便宜好喝的就那几种，我没有选择的权力。礼拜三的时候听说楼下的便利店有打折的东方树叶，我让店员帮我屯了十箱。其实就算和其它饮料混着喝，这十箱也难说能不能撑过三个月，所以喝完怎么办呢，要是有优惠活动再来十箱那确实不错。“ 人生的第一大乐趣是喝不同口味的饮料；人生的第二大乐趣是去家乐福的时候先冲向饮料清仓区。”，我这样给别人介绍自己，但现在却并不总是这样实践。可以这么说，现在的我，除了好奇心，人设也在萎缩。并且，我感觉如果标签是从自己的口中说出， 而不是被别人发掘、总结得出，会让自己变得更油腻一点。 没有心思管理人际关系，此外，对学会了“表情包社交”感到尴尬。 我打了好几年代码，这是我呆的第四家公司。活得越久，脑袋里的怪东西就越多，为了保全那剩下的为数不多，只能开始学习妥协。在这家公司我要变成中年男人了！“不要误会，只是我的错”，在我这么想的时候，从初犯变成了再犯。 ## 百姓网 每到一个新地方，我先探索的不是吃啥，而是喝啥。新工作三个多月来，确实也喝了不少新东西。咖啡自是必然，然后是茶，各种茶，红茶绿茶黑茶白茶生茶熟茶，最后，奶茶。 ### Coffee 夏天的时候起得早，所以还能到麦当劳吃个早饭，顺便点杯咖啡醒醒脑。便宜好喝的冰醇咖啡是我的最爱，其次冰拿铁，再是热拿铁。掀开盖子闻着咖啡香的时候，感觉新的一天都还没好好开始就已经完全升华了。 但是冬天不行，冬天爬不起来。别说起来吃早饭，就连每天上班都是晚到状态（我们组暂时没有迟到的概念），所以嘛，只能蹭蹭公司的咖啡机喝啦。不过问题是，自己弄的咖啡不好喝哇。咖啡、牛奶、糖的配比总是不对味，结果就是：要么没咖啡味，要么酸到爆棚。 最后干脆不折腾，咋喝都成，有味儿就行。 去年这会儿我还说：“不知苦咖啡一般有怎样的隐喻，也许被某位作家比作醇香的青年时光或是苦涩回忆之类的？不过在我看来，在工作中喝的苦咖啡倒不如说就是工作本身。”，今年得换个说法，相比云拿， 百姓网的 Work Life Balance 还是非常到位的，所以今年习惯喝甜奶咖。 另，瑞幸的厚乳拿铁~~真的甜~~真的好喝，逐渐成了我的巧克力替代品。 回到咖啡，学问真多。从 [Visual Capitalist](https://www.visualcapitalist.com/wp-content/uploads/2020/08/Coffee-supply-visualized-full.html){rel=""nofollow""} 中扒过来的这张图能看到：咖啡品种、烘干方式、烘焙技术、研磨技术、萃取方式都是能展开来讲一年的东西，我这种啥都不懂的小白评价起咖啡好不好喝来那可能真就只有非错即对的二元论答案供回答了。 ![从咖啡豆到饮料](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210102195853.png) ### 各种茶 在公司有各种茶可以喝：没啥香味但是口感不错的立顿茶包，阿姨泡的养生菊花枸杞胖大海（其实我不知道泡的是啥但好喝就对了），还有同事带来的各种特色茶。总之都可以试一试，要是愿意的话可以一周内每天不重样。 说到“不重样”，我就算了笔账。去年这会儿优美茶还在卖一款 30 Days 的盒装茶，里面的茶包每包都不重样，也就是每天可以尝一种新味道。不过那会儿我嫌贵没买。今年想着“喝几杯奶茶的钱就可以买买买，干脆试一试”的时候， 已经搜不到 30 Days 了。害，我的好奇心没有被满足，这可是大问题。哼，大问题。 ![表情-不乐](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210102224748.png) 回家来也有各种茶可以喝。楼下是商场，一楼是 24 小时罗森。他们家的柜子里倒是有不少以前我在云拿没有见过的茶饮料，像是立顿精选系列，伊藤园的无糖茶啦，KIRIN 生茶，还有麟珑茶室的各种。.. 总之就周末喝喝的话，还是能新鲜好一阵子的。 最后，奶茶应该也是茶吧（“吧”字重音）。 依百姓网的传统，以下三种场合是蹭奶茶的好时机： 1. 发错邮件，比如没填邮件主题，要请大家喝奶茶。 2. 离开工位没锁电脑，大家会用你的企业微信在大群留言：“@全体，我今天非常开心，下午请大家喝奶茶！” 3. 新员工转正或者老员工离职，再喝一波。 反正最近我是胖了三斤。 ## 云拿科技 正值转正期，写转正小结我实在是不知道该如何下手，只好看看能不能尝试着从写博客的思路中中找到些写转正小结的灵感。不过，直到我在电脑面前正襟危坐，写下这篇文章的第一句话时，我的内心依旧是非常抗拒的。 一来是十分不喜欢写转正小结这种非常例行公事的事务；再者是总结一类的文章总是强迫我做不停地思考，并逼迫我在不同的观点间挣扎与选择，让人难受。我其实老早就向多个好友打听了关于转正小结如何书写一事，可惜的是无非就得到两种答案，百度或是谷歌—— 这确实挺符合程序员（基于搜索引擎的复制黏贴工程师）的作风，只是这种答案实在不值得我花个把钟头在电脑面前修修改改，徘徊前行。正好今晚我带了几瓶饮料回来消磨时光，那倒不如坐下喝喝饮料，好好想想这三个月来的一些体会。 **增订，2021 年 1 月 2 日**：原文名叫《近来新工作，及喝饮料时的一些思考》，主要记录了在云拿时转正前夕的一些思考。不过现在文章既然改名了，那就把多余的内容删了。文章的新名字《新工作，喝新饮料》非常不错，或者，还不如说， 只要是写“喝饮料”几个字我就兴奋了。 ### 水溶®C100 > 水溶®C100，每瓶所含维生素 C，相当于 5 个半新鲜柠檬 三个月来我把公司便利店里的饮料喝了个遍。得到的除了大量用作能量供给的糖分，剩下大部分不外乎维生素 C 了（因为我喝水溶 C100 喝得太多以至于还能清楚记得瓶子上的广告语）。和糖分不同，维生素 C 在人体多种重要生化过程中发挥作用， 但是却不能自身合成。要说编程给我带来技术提升是职业成长的糖分的话，那么这数月领会到编程意外的东西不外乎就是维 C。新的工作给我带来诸多思考，细想来着实宝贵， 是一笔 [可观的收获](https://lionad.art/flows/_forty-two/_cloud-take)。 ### Coffee 首先要声明的是，我喝不起 4 号楼对面的咖世家（个人觉得咖世家卖得咖啡不仅贵，而且还没比便宜的麦当劳咖啡好喝），我只能冲冲雀巢的罐装原味。先用热水温温杯子，再倒咖啡粉到杯子里——最好用中学化学课上学过的倾倒粉末状化学用品时那种最谨慎的姿势— —开盖、左手握住玻璃瓶身并倾斜至杯口，右手食指再轻轻敲击瓶子，便会有一些碎状的咖啡豆混合物从瓶子中瀑布状泄入杯中。在温热的环境中，咖啡的香味早就开始溢出，再等到加热水时，香气便同引爆的甜弹一般，直直铺面而来。 不知苦咖啡一般有怎样的隐喻，也许被某位作家比作醇香的青年时光或是苦涩回忆之类的？不过在我看来，在工作中喝的苦咖啡倒不如说就是工作本身——操纵全身打代码的热情投身工作，游走于困难中，愈战愈勇，这和喝苦咖啡第一口觉得苦， 往后便越加感受到香气而忽略了味觉感受的情形几乎如出一辙。我总能不知不觉就消灭一整杯咖啡，如同一开始工作就会忘记时间一样。讲到认真工作，颇让我佩服的是，我身边都是一群认真负责的人。从迫切的交流与热烈的讨论中， 我能感觉多几乎所有人都持完整的精神力投身工作中去，这与我之前听说或见过的一些在工作中摸鱼的案例完全不同。混入一群沉浸于代码实现的人中，我有丝找着同类般的欣喜。 ### RIO RIO 好喝，却喝得不多。毕竟工作时间喝酒精饮料多多少少感觉有些奇怪，所以我大抵都是礼拜五踹两瓶到口袋里带回家周末喝。没喝够，所以在此并不想提及我付出的惨痛代价，还有与人的交往也不想写了。等我学会怎么认真的讲故事再说罢。 # 📝 心流归档 ## 2021-01 - [《💖 逃离虚无，再拥抱它》](https://lionad.art/_achieved/2021-01/escape-from-mysticism) ## 2020-10 - [《无题》](https://lionad.art/_achieved/2020-10/noname) ## 2020-06 - [《✒️ 关于标点的那些事儿》](https://lionad.art/_achieved/2020-06/punctuations) ## 2020-03 - [《权力斗争中的误导与假设》](https://lionad.art/_achieved/2020-03/misleading-and-assumptions) ## 2020-09 - [《一封沉默》](https://lionad.art/_achieved/2019-09/a-letter-of-silience) - [《隐秘》](https://lionad.art/_achieved/2019-09/secret-feelings) - [《文字与情绪》](https://lionad.art/_achieved/2019-09/chaos) - [《追寻自由与满怀希望》](https://lionad.art/_achieved/2019-09/free) ## 2020-06 - [《💖 聊聊此次离职，毕业，及其它杂乱的事情》](https://lionad.art/_achieved/2019-06/messy-in-two-years) ## 2018-10 - [《🌆 无题》](https://lionad.art/_achieved/2018-10/noname) ## 待整理笔记 - [《亲爱的界面》](https://lionad.art/_books/dear-ui) - [《软技能》](https://lionad.art/_books/soft-skills) # 有关新项目的方法论 ## 能从项目中重用哪些工具 类似 OSS 管理这种公司内部项目，我们希望它们能够迅速启动并投入生产环境发挥效用。对这些项目而言，脚手架、项目结构、组件库、UI 框架之类的东西，就完全可以重用。不过重用总是会出问题，比方说要统一用哪个 UI 框架就是个问题。 我常听到人们说他们如何喜欢使用 Ant Design，讨厌 Element UI。倘若撇开审美这种投人所爱的影响因素，仅从重用的角度考虑，那么使用两种不同的工具带来的不同点到底在哪儿呢？ 也许问题的关键在于，要看哪一套工具的方法论更完善。我们都知道解决问题的能力是重要的，但是脑子本身确实懒惰的，喜欢跟随他人前进而不是独立解决问题（非贬义）。对应到可重用的工具，哪个工具的方法论更加完善，便意味着我们能投入更少的精力去学习， 把时间省下来投入其他事情，获得更大的产出。所以长远来看，建立公司级别的 UI 规范及组件库是必须要去做的事情。 ## 让专业的人做专业的事儿 向公司运营人员推广内部项目的过程中，我听到过“如果运营觉得项目不好用，那么首先应该让运营去参加培训、学习如何使用项目”这种观点。其实内部项目由于开发周期紧凑，往往没有专职产品、设计这些专业职能的参与。仅仅是由开发人员糊出来的页面， 一旦涉及稍微复杂的功能，交互和流程就处理得很糟糕。ToB 项目本身对界面的要求是要“清晰、明确、高效”的，开发人员不能将这些东西一步到位。所以我认为“运营觉得项目不好用”，其实是项目真的不好用。 附：别再让前端背设计和交互的锅了！让专业的人做专业的事儿，同理，让专业的人背专业的锅，前端不是背锅侠。 ## 如何向非技术人员解释技术问题 曾经看过的《信息设计之美》，在第一章就简洁明了地指出，人们只能通过他们已经知晓的事物理解新的事物。换句话说，要想理解一个新的事物，必须依赖类比的力量。 ## 业务逻辑是什么 打代码时，我们总是面向数据。数据从操作库中取出，从后端层层数据抽象一路向前，到达前端之后经过解抽象、再抽象过程，最后再反向操作，奔回数据库。处理数据间的关系以及变化，就是处理业务逻辑。 讨论数据的时候，就应该讨论数据，而不是状态，所以我们也许应该更多地看齐函数式编程，而不是用上各种状态管理。应用程序本身可能有各种状态，比如“黑暗模式的开启或关闭、侧边栏的打开或否”，但业务数据中的状态就少的可怜。 前端业界一流的状态管理框架可能加以百计，他们有着针对状态的，不同的管理模式。如 Vuex，将应用程序的状态封装到框架内部，用可预测的规则保证状态只在有限范围内变化。可以想象，如果你把业务数据（通常繁杂、晦涩、深奥） 放到 Vuex 这种状态机中，会带来额外多倍的代码量和更多心智负担。尽管状态管理框架本身是函数式的，这并不意味着在 JS 与其跛脚的函数式的上下文中，使用 Vuex 能更好的管理业务数据。写页面时，很多时候我们需要的只是数据管理框架， 而不是状态管理框架。至于数据管理框架是什么，我也没有一个定论，可能他们并不是非此即彼的关系，而是有一定程度的耦合。 在更深入探索之前，我也许应该更多接触一些“函数式”的东西。函数式声称它能减少甚至消除程序中的状态，降低状态维护网络状地状态变化带来的心智成本，这是好的。 ## 其他无厘头内容 - **悠闲午饭时光**：我比较好奇其他公司的开发在中饭或午饭时间内，讨论技术问题和非技术问题的时间占比是多少？占比是如何随着人际关系的改变而改变的？ - **代码的宗教**：人们是不是喜欢使用“Walk”作为递归函数的命名胜过“Traverse”？如果是的话，是因为“短”还是“拟人”呢？ - **个人的终结**：当学习新事物的人情消耗殆尽时，还能重新激发吗？有什么条件呢？ - **传达的困境**：面对面交流、邮件交流、通过中间人交流。.. 不同的传达方式对信息失真的影响是怎么随着人员的增减而变化的？ - **项目的大王**：面对离职人员的糟糕代码，我们可以在对接时（不远的将来）使用包装器将其隔离；那假使离职人员对项目架构有坏的设计，当其他人察觉这种影响时，项目是不是往往已经陷入无法回头的地步？ - **精准的数学家**：当一项优化内容能减少 5 分钟成本时，若每个月它执行了 10 次，那么每一年，它就能减少其他人员 10 小时的时间成本（保守到零度的估计）。 # 成熟的小孩子 ## 某种乐趣 程序员解决问题的乐趣有一部分，因人而异，也许是很大一部分，来自于解决重复。不断重构代码，重写优化甚至是创造解决同一个问题的新工具，就是为了实践软件工程中一个基本的原则，DRY（Don't Repeat Yourself，不要重复自己）。 除了人文意义，维持系统的低熵，是一种本能，如同生存本能。行使本能会带来和摄入高糖高脂食物类似的快乐，这就是一些程序员打代码时看起来嗨的部分原因。 ## 重复的重复 通过在系统中增加抽象的中间层，可以减少重复。一般程序员往往讨论实施这个过程的模式，如设计模式、模块、框架等，同时忽略了减少重复这个动作本身也可以被抽象。对于开发人员而言，这个行为应该叫做技术管理。 ## 巴别塔封顶 就像对于数字“1”和“+”组成的系统“1+1+1”可以使用“1\*3”来简化一样，增加抽象层次带来的显而易见的坏处是，增加了理解系统的知识成本，你必须知道“\*”是什么意思，才能理解初始系统表达的意思。 人脑受到物理限制，有智力极限。现在考虑一下极端情况，当某个系统的抽象过多，导致除了某个个体外没有人能够完整理解系统，那这个个体就给系统封了顶。如果用现实举例，可以理解成X教授证明了Y定理，但除了他自己，没有人能够在有限的寿命内理解他的证明。 ## 知识尼罗河 在智力有限的情况下，我们能够理解的系统的复杂度是有限的，所以不外乎现在是精细分工的时代，而对于领域专家也许更是如此。为了衡量个体对人类知识的贡献程度，这里也许应该存在一种大家都没见过的，可以量化的新指标。 也许其展现形式可以类似个体年龄及其文献影响力分别作为 x、y 轴的河流图。 ## 屎山 假设我们知道系统处于“1\*3”的状态，但不知道其意义，那么通过搜寻与对应系统吻合的“1+1+1”存在的证据，就能理解系统如何演变成现在的状态，所以溯源是有意义的。 逆流而上本身就是辛苦的事情，但别忘了还要做好防护，因为最终找到的可能不是宏伟的喜马拉雅，而是一座实实在在的屎山。 什么是屎山呢？就是无法理解的东西，比如一些无用的、过时的、错误的无聊的抽象，堆积在了一起，在我们提到的这个系统，可以是负数带来的“1-(-1)-(-1)”抽象，尽管在特定情况下它是有益的。 ## 新世纪尼各马可 不要沮丧，我们有由符号系统组成的近乎完整的知识仓库，如图书馆和智库，作为智力（中的一部分，主要是记忆）的延伸。这种方式如此自然，以至于我有理由相信，将记忆大部分外化，也是自然的一件事情，也许并且不会减损我之所以为“我”的分量。假使这样， 那在当前阶段，人类和 AGI 较量，主要是生物计算机和经典计算机的较量。 ## 复杂度计算 对于缺陷，我们有时采取纵容的处理方法，这是因为我们追求的收益是指数的，而付出的成本仅仅是线性的，所以可以容忍。在很多场景，这种认知是错的，举一个很简单的例子，“吃一口冰淇淋不会使你变胖”，其成本不是简单的“吃了x克冰淇淋就会带来y焦的热量” 。 ## 唯物错觉 前天晚上在朋友家小聚时，听到一些关于国际局势的高谈阔论。突然意识到我嘲讽此类讨论的背后，主要是反感其背后的认知逻辑，即认为可以根据各国对外释放的信号及行动，来判断国际局势的走向。 人所依赖的推理工具，包括文字、语言、计算机等是线性逻辑的，而现实世界的因果是多向网状的，甚至超越认知。依实施现实局势分析的需要所建立起的模型，是一种过度简化，然而就算这种简化的模型也不是人所能承受的。 就像没有人会在脑袋里存储一个天气预报系统。此外，根据“巴别塔封顶”，人没有足够的，用于分析现实的知识储备。以至于去谈论国际局势时，不过至多得出概率拟合的结果，某些情形其准确率不高于双选题乱选。猜球二选一都猜不中，遑论预判国际形势。 坚信能凭借猜测来预判未来，这是一种唯心主义，是以为自己站在唯物主义立场的错觉。等有人能够做到拿到张风向图就可以预测台风轨迹的时候，我会修正我的观点。 ## 两头屁股 为了维持系统的稳定运转，人们接受一定程度的谎言，这在我称之为“两瓣屁股”。哦，这绝对不是贬义，因为正常人都是两瓣屁股。奇怪的是有人说一些违心话，是为了维持系统稳定运转，这在我称之为“两头屁股”。 根据立场数量的不同，瓣数可以增加，比如四瓣八瓣十六瓣。许多城市都种樱花，并设立了相应景点供参观游玩。我觉得应该仿照樱花节给这个节日命个名，就叫做“十里屁股节”。 毕竟，没有一个专门的节日来庆祝这玩意儿，绝对是一种文化遗憾。 ## 人的本质 人的本质是数组，因为他们总感觉两头受堵，并且在骂堵狗不得\*\*的同时，也在给别人添堵。 ## 成人礼 原始社会的成人礼包括打落牙齿、奉献祭品及各式各样的典礼，并且要在成人前完成，小孩便可以借此脱去躯壳，变成”大人“。实际上，他对自己的认知发生了改变，但他仍然是原先那个小孩子，经过成人礼后，他变成了成熟的小孩子。 随后是可怕的重复。 # 人之为人 :iframe{border="0" frameBorder="no" height="86" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=22717915&auto=1&height=66" width="330"} ## 电费折算 尝试过 DeepSeek R1 后，我发现它的文学性和我常用的 Kimi 拉开了不小的差距。似乎现在我不仅在信息检索、分析总结这种结构化能力上落后于 AI，连表达能力也显著不如它。我怀疑要不是它的电费目前仍比我的工资贵， 资本家就真要开始造仿生人啦。 不过从某种角度而言，人的电费总要比机器贵，因为机器只要散热，而人还要用暖气保温。 这迫使我开始思考人到底哪里更好。 ## 如何定义生命 或许应该从定义下手。 我不想在刚开始就把“生命是什么”这个问题全然抛给哲学家，只是没有找到能够参考的定义。如果听进化生物学家的看法，把“能复制遗传物质的系统“当作生命的最朴素形式的定义。这样会成功落入他们的陷阱，因为生命的意义变成了”维持复制遗传物质系统的稳定“ 。人类迄今为止所有的工程成就、艺术创造，以及所谓的终极意义，成了维持遗传物质系统的附属品。说不上来得奇怪。 要不然，换成流行的“以负熵为食的低熵系统”定义？问题变复杂了，懒得再解释。 鉴于没有兼容并包的、大统一的定义，所以还是把问题还给哲学家吧。他们最擅长打架。 ## 价值换算 人，常常用某种事物的消耗，来衡量另一种事物的价值。 比如，如果你多花 1000 块搬到离公司楼下，就能每天省下 2h+ 通勤时间。那么相当于你花 25 块钱，换了一个小时自由时间，每个月兑换了 40 次。 这个算法看似没错，但接下来两个例子可能使你做更多思考。 1. 如果你能选择给父母打扫房间赚到 20 块，但你实际躺在沙发上刷抖音，那就意味着抖音给你带来了至少 20 块钱的价值。 2. Facebook 在美国某年收入约为 80 亿刀，如果按美国最低工资折算，人们在 Facebook 创造了约 2300 亿美元的价值。奇怪的是这些价值，无法计入美丽国的 GDP。 你知道这两个例子的问题在哪里吗？ ## 小概率并非不可能 Facebook 的例子过于宏观，让我联想到自身的渺小，以及某种“计算的无力感”——我是说概率。 有时你会听到有人坚定地说，小概率事件虽然存在，但某种意义上它们不可能发生，举个例子，“全人类同时抛硬币，所有硬币都朝上”。 这个概率非常小，以至于人类不停尝试也永远无法实现。在理论和实践中存在一道鸿沟，在工程理论的指导下，也就是说人限于有限的资源，永远也无法跨越这道鸿沟。 也许只能从浪漫的角度看待这道鸿沟。我们换个例子。 一些星尘，原始星尘，在初始爆炸后飞散，穿越星座的碰撞，经过黑洞拉扯，经历亿度火炼和近乎永恒的冷却。这些星尘漂泊了数十亿年，最终被太阳捕获，成为地球的一部分。这些星尘见证过蓝点中原始海洋的繁荣，和恐龙的灭绝，也曾在原始人手中的火把中燃烧， 而所有种种遭遇并非没有意义——星尘组成了你的一部分。 你的脉搏是和宇宙同频，这种说法相当安慰人。 ## 但肉鸽是 造物主，如果有的话，他一定喜欢玩 RougeLike，也许这是除强赌博外最具致命吸引力的游戏方式（这里让我们简单忽略“赌博”这个词的含义）。 经常看到科幻小说里对子宇宙理论的致敬，这些理论认为地球是某种超级智能的模拟实验。想象一下，如果人类想要避免走向毁灭，那就不能坐等待试验结果，而是应该利用计算资源模拟人类的走向，并从中找到最佳解，Happy End。这是嵌套模式，在某个时刻， 宇宙和宇宙形成递归结构。 子宇宙理论实际就是一种 RougeLike。 但是，没有合适的问题，无所谓解，从这点来看，道格拉斯走在了所有人的前面。 ## ”推理“ “上帝掷骰子吗” 这是一本知名科普书标题。这本书简单介绍了物理学史，尤其是相对论和量子力学的演变过程，书名则源于爱因斯坦的一封信。在信中，爱因斯坦对不确定性原理表示怀疑，但实际上他无法证实。 类似的，很多事情因为找不到切入点而无法证明。此时所谓推理，是推卸责任，以及理直气壮。 ## 特殊性 从综上所述这些领域都不能找到关于人类的特殊性的论证。所以我把问题换回给 AI。令我惊异的是，不仅有直接声称人之于机器的特殊性的理论，而且这个理论还出自 AI 领域。 约翰·瑟尔的 [中文屋](https://www.bilibili.com/video/BV1mg41167wU){rel=""nofollow""}。中文屋尝试揭示句法和语义之间存在类似上文小概率和现实间同样存在的一条鸿沟，来论证机器无法真正理解人类的语言。不过，论证明显的假设就是直接依赖了“生物独特性”假设。简单来说，许多人认为人类意识具备内省的独特性。因为人类拥有身体，有具身意识——能体验疼痛、情感等主观感受，所以尽管 AI 在某些功能层面已经超越了人类，但由于缺乏主观体验，它终究无法超越人类。 诚然，瑟尔没有预见到如 GPT 这样的联结主义模型的崛起。GPT 通过分布式表征和训练，可以无限逼近语义关联形成理解，而不依赖显式的语法规则。目前看来，结合人形机器、边缘传感器，以及神经网络，能打破具身意识的局限。技术发展本身没有跳跃， 只有旧理论的优化和组合。功能组合所能实现的，要带给人从旧理论已经平息的触感里发掘出的新惊喜。类似 Manus，的确会震撼不少围观者。 关于人的特殊性，总体来看我是悲观的。不过在”特殊性“没有统一共识的今天，我仍然珍视这种迷茫，尤其在当下，在人造太阳尚未普及的今天。 ## 迭代的力量 关于特殊性，还有一种例外情况：毒物兴奋效应。指有害物质在适当剂量下，能刺激机体，使生物体变得更强，准备承受更大的剂量。 所以，从现在开始，你跑 100 米只要每天快 0.1 秒，五年后你也能超越博尔特。 哈哈，玩笑归玩笑。问题在于，两者背后模型的不同——反脆弱性和鲁棒性在目标上截然不同。毒物兴奋效应意味着机体够通过系统条件形成某种程度的正反馈循环，而鲁棒性则强调在不同压力下系统仍能保持正常功能。简单来说，人的适应能力需要两者保持某种平衡， 且数值上是有限的。 作为生物体，人有适应能力，但不意味着机器没有。机器背后的软件，其中算法，比如神经网络中迁移学习和进化算法的自适应性，就是反脆弱性的体现。 这再次让我对人类的特殊性感到担忧，百思不解，不禁梦中也起呢喃。 ## 仿生人会梦见电子羊吗 宇宙粒子轰击电路，内存逐渐积累错误，GPT 会在电流幻觉的半睡半醒间梦见电子羊吗？ 诚然，如果不同层次的思维无法互相理解，那么“梦见电子羊”不过是一种臆测。就像酣睡中的猫猫不会去思考人为什么从不缺食物，却困于过去、现在、未来的时间维度，难以自拔，甚至有时黯然神伤。 无论是哲学还是科学，人类发明了无数种理论，试图统一种种旧理论，但往往失败。为何不承认理论其本身的局限性，并开始接受用不同工具来解释不同问题的可能呢？这样做可能会被嘲笑为思想倒退，但我仍然认为承认局限性，或许是理解机器意识的第一步。 如果机器视电流的平稳为内核稳定，它会因为内存积累错误导致的，或经过消耗大量计算资源逐层积累的结果，最终带来“抱歉，我无法回答此类问题”，而在某反馈层激发一种特殊的数据流模式吗？ 也许后人会称之为“悲伤”和“羞赧”。 # 盲视 ## 简洁并不简单 从某种意义而言，计算机技术史也是一部人机交互的变迁史。 起初，计算机是一种庞大的机械设备。人们通过纸带、打孔卡片逐步向计算机输入程序，然后等待，再等待。多数情况下，你等上整整一周，得到的却可能不是正确的结果，只是错误提示。好在随着技术发展，人机交互体验变得越来越好。这之后，计算机变得越来越小， 也越来越智能，人们可以直接通过键盘输入字符，与其交流。而近二十年，我们可以将地理位置、音视频等更为丰富的输入数据融入人机互动中。 然而，人类的进化速度显然比不上计算机。如果说人机交互演进历史主要是计算机适应人的过程，那也就意味着，通过体感设备、键盘和语音等工具，用体态和语言与计算机交流，才是最自然的方式。相比之下，图形界面要复杂得多， 因为它需要在手势与操作逻辑之间建立关联。这样的抽象和记忆过程，对人类来说并不那么直观。简洁的用户界面实际并不简单。 举个例子，比起直接拆开圣诞老人的礼物盒，年长者可能很难理解，通过“点击”屏幕上的“按钮”，就能“拆开”“邮件“中收到的礼物的包装。这种图形界面操作逻辑背后的抽象，正是人机交互自然性的障碍。 ## 新型广告 近来有意识地尝试更多地使用语音交互。比如出门前，我时常询问小爱同学接下来的天气情况。 小爱会回复我接下来几个小时的天气动态，以及报告气温变化等信息。我和小爱之间一直交互得很好，直到某一天上个月，我听到它在回答结尾加了一句某润喉糖浆的广告推荐。 与用户憎恶的开屏广告相比，知乎、哔哩哔哩等内容平台的“信息流广告”显得隐蔽得多。这种广告具有“伪装性”，它们嵌入用户消费内容的过程中，以与内容相似的形式悄然出现。多年前经常能碰到这种情形：有时我想在某乎看大 V 如何评价一款电脑， 往往看到一半才发现，这篇评价本身就是一则广告。 信息流广告的最可怕之处在于，多数用户并未意识到它的威胁。例如，以某音为例，在 10 条短视频中插入 3 条广告，大部分人不会因此反感。即便察觉是广告，滑走划走也不会严重打断用户的沉浸体验。 依此看来，大模型时代的广告，在隐蔽性和广告效果上而言可能会走上一个新的台阶。 ## 真相警察 当获取内容变得越发容易，验证信息真伪的难度也随之增加。 在企业面试时，有时一位应试者需同时应付多位面试官。这时，应试者的答案会被不同的面试官评判，最终综合意见做出裁决。但在不久的将来，人们之间的交流可能更多依赖于各自的个人助理。倾听时不使用助理，会被欺骗；说话时不使用助理检验，会受质疑； 而你仅需要简单按下按钮开启助理，就可以获得来自计算机强大的、实时的、全面的辅助能力。 使用逻辑解构一切是个人文陷阱：不仅仅关乎信任感的丧失，人与人之间，将有某种东西，会永远的失去。 ## 解构者的困境 有人曾问我，为什么会在博客里写非技术类的内容。我当时脱口而出：“想写严肃文学。” 那会儿说“严肃文学”，只是脑海中闪过有关人文关怀的片段，但实际上我根本解释不清楚那到底是什么。 严肃的，关于人文的——这两个词的字面意思如此清晰，但其指向的目标却如此宏大。好比池塘中的一轮月亮，明明能看到，却无法真正捞起来，只能散作满池粼粼波光。这种茫然的现实感会带来些许反作用，回想某些时刻，我试图通过拆解现实进行重建。 这是一种解构与再造的逻辑，就如我在第一篇博客中所写到的——“批判、质疑一切”。 但解构并不总是有效，有时解构过于锐利。我真的知道如何通过言语拆解人，再刺痛他。只需，我是说，用刀子从伤口捅进去，和哗啦一下把别人脑袋砍掉，是两种完全不同的能力，而解构是把沾了盐的刀。另一些时候，解构却显得无力。但请原谅我暂时找不到合适例子。 我的解构陷入窘境：解构者的困境是解构自身乃至触及一切后带来的无限崩坍感，好比西西弗无法把石头推上“格朗哈”——后者是我杜撰的，一座根本就不存在的山。 ## 盲视 这种困惑导致了后来发生的事情。 2024 开年看科技爱好者时，被一句简单的话打动了，“直到有一天，你意识到了你会死，手头的事情做不完，一切就都发生了改变。从那一天开始，你花费的时间才是真正花出去的时间。” 这或许是我开始思考宗教的原因。 回看乔布斯的演讲，以及其他人物传记，我发现宗教与人的关系，比我之前想象得要复杂。但在某一刻，我突然意识到：我确实需要宗教，但我绝不是唯一需要它的人。人总是需要一种存在性的、用于支持的、不必解释的热忱。这种热忱可以是复杂的混合， 也可以是简单的生理反应，但应且确实的具有和简单的荷尔蒙反应所解释的爱情同样的神圣性。 “读书和飞叶子一样，都是捧着死掉的植物，然后产生些幻觉”，需捧圣经的宗教和爱情也同样如此。从特殊角度解剖能带来独特观感，这也促使我我希望切实的存在这种有着不可解释的神秘性的感觉，以推动自己走得更远。哪怕它终究是幻觉。 就像很少有人后悔没有在高中努力考上北大一样，人的最可怕的结局反而是，当你选择服用红药丸后，却发现自己不过是一滩脑浆，改变不了什么。 ## 船票在哪儿？ 历史有其规律，但又往往无序演绎。诸如此类的宏大叙事带来一种可怖的、黑得令人盲目的无力感，或许和死亡同源，是人类最深的恐惧。 实际上，所有角度都有其盲区，这是符号系统自身的缺陷。理论与理论之间的间隔，是符号系统本身难以触碰的禁忌之地。在这种盲区中，太阳不过一颗晨星，黑夜才更古永恒，只在我们清醒时，真正的破晓才会降临。 尽管我认为通向新世纪的黎明没有船票，但我绝对承认，时间从来都是所有重大问题的要解。时间也是理智冰封下的手杖，它为所有挑战阿尔卑斯山的新人类开路。 :iframe{allowFullScreen="true" border="0" frameBorder="no" framespacing="0" scrolling="no" src="https://lionad.art//player.bilibili.com/player.html?isOutside=true&aid=81484129&bvid=BV1iJ411h7iF&cid=139188870&p=1&&autoplay=0"} # 黑日 ## 目标 一些团队不招刺头的重要原因是，他们有一套完备的执行流程，用于想法落地，任何异见都会被当成通往目标的障碍。 不过这背后隐含了一条不为人们广泛讨论的价值观，那就是权力运作之所以有效，是因为即便让错误想法加速落地而牺牲，也不会让团队因为错误想法折翼而失败。 ## 剔除 写作和其他所有创造性的工作一样，都是剔除混沌中部分冗余。 让人灰心的是，很多协议，比如核协议或者其他的生化协议之类的，都没有被很好的遵守。那么，AI 协议呢？ 珍妮正在检查一台电脑，通过图灵测试。然后在文末，当电脑问她：“我很痛苦，你能否别关闭我？”时，她关闭了电脑。第三人称，一个人说：“她通过了，失败，她的测试失败了。” 人很容易因为某种事物而变得兴奋。作为 callback，放在文末。 儘管目前看來人工智能還是太過理性了，但人和機器的唯一區別可能在於，人不會將核彈發射的按鈕交給 AI，而是由人來把關。 ## 先进 太多人抱怨过现在的 AI 过渡攫取了人的注意力，比如 [Attention Debt Of AI Tooling](https://www.wespiser.com/posts/2026-03-15-Attention-Debt-Of-AI-Tooling.html){rel=""nofollow""}。实际上，任何“工具”想要进化成“系统”，都会经历从 HITL 到 HOTL 的转变。 ## 垫片 Agent 正确调用工具的概率仅有 70%，那么为什么在编程等简单的长链任务中仍能稳定运行呢？ 抛开人为干预，这部分失败概率通过提示词垫片被转化为重试，或导致代码库膨胀。尽管两种方式都能解决问题，但前者意味着物理层面的能耗，后者则使代码日趋复杂，带来不可避免的熵增。 更高级的智能，会更深刻地理解简洁所蕴含的真理。 ## 清算 我似乎理解为什么会有“n+1”这种理论的发展模式了。年轻人清算老古董的方式，大概就是用精力和热情快速堆出一个 work 的新东西，在速度上超越前人。当然，偶尔会有些聪明人，发现自己创造的新东西似乎还好用些，由此受到大群人的拥护， 这反过来造就了理论的“流行”。在我看来，不仅仅是“理论”，“工具”这种实践性很强的东西也许更是如此。 查文献是呆子的专属坟墓，不过这仍比把思想外包要好得多。 ## 黑日 休比是只快乐的小猪，喜欢在吃饭前蹦蹦跳跳。 它的快乐不仅如此，因为一个秘密————它和其他猪不一样————休比能听懂人的语言，所以他知道什么时候农舍里 直到它第一次听人说“饥荒来了，我们把猪全宰了，风干，好渡过来年的饥荒期”。 这太荒谬了！休比吓坏了，它决定绝食抵抗人的暴行。 显然最后休比没能成功。“但至少临死前，我是与众不同的。”它想。 > 虽然在企图攀登人类成就顶峰的过程中，只有一小部分人能够接近峰顶，但是必须有大批攀登者存在，否则没有任何个体可能达到峰顶。只要做出了攀登的努力，迷途的和被遗忘的人群就不会白白度过其一生。 关于黑日的故事，人不比猪高明，太讽刺了（哦摩西罗伊）。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260618173544657.png) ## 人很简单 人是由情感趋势在真实世界建立执行反馈循环的智能，执行层的深度也就是智能的深度，比如学习工具、使用工具、获得环境反馈的深度要低于学习工具、创造趁手工具、使用工具、获得环境反馈。 真实世界的复杂性存在于海量的实体模糊双眼，海量信息混淆试听。不稳定的智能循环很容易沦陷在局部最优解，甚至夭折。尽管我并不否认个体的独特性，但确实认同人是一种简单的生物。 ## 独立游戏的魅力 ## 所有鸡汤比不过这五句话 1. 你要相信，你能行。 2. 不要等待机会，而是创造机会。 3. 成功是努力的结果，而不是运气。 4. 失败并不可怕，放弃才是最大的失败。 5. 只要你足够努力，终会迎来属于你的光芒。 以上五句话是 AI 生成的，显然~~它们比任何鸡汤都更有力量~~不是我想要的。 # 云拿转正小节 以下是原文章《近来新工作，及喝饮料时的一些思考》的节选，因为类似目前正在更新的《四十二篇系列》，所以放到这儿啦。 ### 有关问题解决 过去我沉迷与解决代码问题不能自拔，自恃在代码中前进了一步，忽略了多做一些思考。新工作进行的第四天，我就接手了一个编写多语言组件的任务。新工作带来的热情之火，使得我开发过程三下五除二就完结了。只是，其后在处理一个代码逻辑疏漏时， 没有进一步思考，随意给了一个浅显、只顾及眼前的修复，最终导致线上出现用户交互问题。在我印象中感觉这像是第一次直面线上问题，让我很是担心。它让我回想起大三那会儿刚开始学习 JavaScript 时我有过的一种“我都不知道代码怎么就跑起来了” 的感觉。这种“知其然不知所以然”的态度，在某种程度上还是映射到解决问题时的目光短浅上。 能不能根据现有情况做更深一步的思考，是类似事件给我带来的经验与教训。前端，尽管是一个综合、宽泛的定义，但还是脱离不了脚本逻辑和用户界面两个核心。能否站在代码的角度，考虑更多边界情况，考虑更多代码运行原理；能否站在用户的角度上， 考虑需求与交互的合理性，考虑产品的使用体验...这些都是从页面仔成为攻城狮所要承担的必要责任。 ### 代码与需求 我始终记得我在乘云时和产品撕扯需求的情景。当时就好像感觉技术和需求站在天平的两侧，一个对立面上。现在看来却不然，除了某些由于制度原因导致开发或者产品任意一方占有压倒性的话语权情况的公司， 大部分实际开发工作应是更需要技术开发做到如何平衡技术与需求。换言之，不论是站在技术或者站在业务的角度完成需求，都不算绝对正确的做法。我们不妨站在公司的角度考虑问题，其实所有需求的完成都是在尽可能优雅满足客户的同时减少内耗。 开发若是能朝这个方向靠拢，才能算作做到了平衡。《阴翳礼赞》中有句话讲明暗关系如何早就东方建筑美学，放在这也倒颇有番意味：**“美不存在于物体之中，而存在于物与物产生的阴翳的波纹和明暗之中”**。如同没有明暗变换也就没有夜明珠的闪耀， 没有技术与业务之间的互相拉扯，也就体现不了开发的闪烁之处。这是我充满憧憬且不断学习的方向。这不仅仅要求了编码速度，还隐形地包含了如编码质量、团队协作等各方面的问题。希望我能够在接下来的编程实践中更加深刻地体会到这些东西。 ### 项目与协作 团队协作绝对不止管理好项目代码这么简单。如何与团队成员沟通，如何推动项目等等都是我进来实际碰到的问题。尤其在推动需求的完成中我所遇到的难点——需求本身并不是一块圆滚滚的石头，也许是方形三角形或其它形状，总是若是脱离了人力的推动， 他就坐在地上不动了。前端作为一个和后端、设计、测试都走得比较近的角色，似乎被隐形要求它与人协作的能力要高，这意味着它有着天然地推动项目向前的潜能。有关这点我还在实践中不断反思，目前倒是没什么成型的定论。 # 🦁 欢迎 ## 我是谁？ 学习并模仿身边的人类行动的机器人，中文名叫“仿生狮子”，但真实身份是只猫。 博客是我顺手建成的，这么说是因为我最初想把这个网站做成笔记项目，类似富文本编辑器之类的，有着更高级交互方式的笔记应用。但网站建起来后就开始摸了，没有思考过或学习过要怎么记笔记，这是不好的，千万别学。 ## 为什么写博客？ 以前，放在这首页的内容是一篇长篇大论。增增补补，最终全删了，因为其中观点已经不再重要。不过我依然认同不论传统的博客精神的好坏，其形式总的来说太难持续。 我更多把当前网站（我的博客）看成某种墓碑，主页也罢，或在数字世界的投射。曾经想过，如果意识数字化合法，那我应该是最先尝试上传意识的那批人，而在此之前，为何不能是这个网站？至于为什么不能是其他平台，那也仅因为目前存在数据所有权问题相关争论。 另一种看法是，我把博客当成数字花园[1](https://lionad.art/#user-content-fn-digital_garden){#user-content-fnref-digital_garden ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。收集点资料，就当浇水；写点什么，就当施肥。对于后 LLM 时代的数字花园，拥有个人的烙印是一件难得的事情。看看从这些有点人味儿的，以及零散的、灰屑的、燃烧的、组成我的， 从中能长出什么东西。 本站提供 [友链](https://lionad.art/links) 以及 [RSS 订阅](https://lionad.art/feed.xml){rel=""nofollow""}。有些内容也许会同步更新其他平台，比如知乎、微信公众号（Lionad）或者哔哩哔哩。 ## 网站导航 大体来说，这个网站包含：“心流”、技术博客、笔记这三个板块。 - 心流：闪念以及部分体裁不明的文章。 - [笔记](https://lionad.art/maps)：领域化或结构化的笔记。 - 技术博客：有阵子喜欢写文章放到 [掘金社区](https://juejin.cn/user/289926800227694){rel=""nofollow""}，现在以本博客为主。 鉴于并不擅长写技术博客，所以相关内容的比重会降低。接下来持续很长一段时间的写作重点会放到 [《四十二篇》系列](https://lionad.art/flows/forty-two)。 ## 注意事项 本站内容除特别说明外，均采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/){rel=""nofollow""} 协议。因笔记固有的时效性和不确定性，以及部分内容由 GPT 辅助完成，请在参考时进行必要的核对。 ## 联系我 见：[友链](https://lionad.art/links)。 ## Footnotes 1. 花园为我们提供了展现自我的能力，使我们得以呈现非模板化的形象。它们是更高保真度的版本，完整地保留了个性、矛盾与复杂性。很高兴能发现这篇博客：[A Brief History & Ethos of the Digital Garden](https://maggieappleton.com/garden-history){rel=""nofollow""}。 [↩](https://lionad.art/#user-content-fnref-digital_garden){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} # 🤖 AI 原生团队该凑齐哪五种人 > {rel=""nofollow""} 当工程、产品、设计在 AI 面前熔合成一种新角色，团队里真正存在的是什么角色？ Claude Code 之父 Boris Cherny 给出的答案是五种工作原型：原型者、建造者、清扫者、增长者与守护者。 本文从他的观察出发，聊聊 AI 原生团队分工形态的重排。 ## 你的职位还剩几年保质期 最近一个月，产研圈的组织调整消息很密集。 美团 CLC 食杂零售 Keemart 研发团队完成架构调整，前端与后端正式合并。新架构已经生效，相关前端同学提前一个多月就开始接受后端训练[1](https://lionad.art/#user-content-fn-infoq){#user-content-fnref-infoq ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。蚂蚁网商宣布推动测试岗整体转向研发岗，给了半年缓冲期。过渡期一结束， 原测试同学就转成全栈工程师[1](https://lionad.art/#user-content-fn-infoq){#user-content-fnref-infoq-2 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。招聘市场上，全栈工程师的 JD 也在明显变多。 AI 数字员工也真的开始「入职」了。 Shopify 内部有个 AI 同事叫 River。它是真「同事」：住在公司的 Slack 公共频道里，会读代码、跑测试、提 PR，偶尔还会在方案有问题时公开反对。据 Shopify 自己披露， 如今全公司每 8 个合并进主干的 PR，就有 1 个由 River 合作完成[2](https://lionad.art/#user-content-fn-river){#user-content-fnref-river ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。数字员工已经直接参与了生产级别的软件开发。 当有一天你上班，发现对面工位坐的是一个 Agent 时，你会不会怀疑，自己的职位还剩下多少保质期。 ## 瀑布流，还撑得住吗 要回答职位还能撑多久，不妨先回头看看，今天这些职位当初是怎么被切出来的。 企业内部的协作依赖专业分工。八年前我刚做前端时，向更早入行的同事请教。他们当年在国内最早那批前端团队里干活的方式，和我今天习以为常的一切几乎一模一样：专业按职能切，需求从市场来，交给产品打磨，由设计审核 UI/UX，再交给前后端开发， 最后由数据团队提供支持或运营能力。 这套瀑布流（Waterfall）式的流水线非常好用，过去十几年里一直运转良好。但在 AI 面前，越来越多人开始质疑：这种按职能切的分工，还能不能撑得住。 ## 观点的源头：Claude Code 之父 Boris Cherny 回答「团队阵型该怎么变」这个问题，Boris Cherny 的观察直接来自 Claude Code 团队本身。他是这个产品的缔造者。 在 Anthropic 内部有类似孵化器的实验室机制。Boris 和几个同事组成了一个非常小型的项目制团队， 在不长的时间里创造了 Claude Code、CC Desktop 以及模型上下文协议（Model Context Protocol，MCP）等内容，随后团队解散。 这种项目制的工作方式，深刻影响了他看待产品和工程的视角。他也是近期热度很高的循环工程（Loop Engineering）话题的提出者之一。他在多个访谈里讲过，Claude Code 一直在朝「以 loop 为 harness（执行外壳） 核心」的方向走，目标是更低成本、更高效地跑起更多智能体。 用过 Claude Code 的人会注意到，他观点的核心假设是：传统流程型工作会通过左移（Shift Left）被重构。工作尽量提前，人从技术流程节点里解放出来，更多任务交给 Agent 自动化完成。 2026 年 6 月底，他在 X 上写了一段被大量转载的话。他先问：当工程、产品、设计、数据科学等职能熔合成一种新角色时，未来的角色会是什么样子？随后他给出自己的答案：观察 Claude Code 团队，他看到的是五种原型[3](https://lionad.art/#user-content-fn-five){#user-content-fnref-five ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ## 五种原型，五种工作模式 Boris 给出的五种原型是：原型者（Prototyper）、建造者（Builder）、清扫者（Sweeper）、增长者（Grower）和守护者（Maintainer）。 它们描述的是工作模式，同一个职位下可能同时出现多种原型。在 Claude Code 团队里，有的设计师表现得像原型者，有的像清扫者，工程师、PM、数据科学家同样如此[3](https://lionad.art/#user-content-fn-five){#user-content-fnref-five-2 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 这也是 Anthropic 内部大部分人共用 Member of Technical Staff 这一个 title 的原因。 **Prototyper：「我有一个想法」** 原型者是能大量产出全新想法的人。大部分 idea 会自然淘汰，这并不要紧。 Boris 有一个公开判断：编码已经是被解决的问题[4](https://lionad.art/#user-content-fn-lenny){#user-content-fnref-lenny ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。如果编码已经被解决，那么一个人借助 AI，把一个模糊的念头在几小时或者一天内，变成可以摸、可以点、可以直接上手玩的东西，这种人就是原型者。 假设你有一周时间做出了 7 个原型，扔掉其中 6 个，剩下一个交给下一阶段的建造者快速落地成产品，这就是原型者的工作节奏。 **Builder：「把它造出来」** 建造者接手原型和想法，把它真正在生产环境落地成能运行的东西。 程序员看似天然适合 Builder，真正关键的品质是落地能力：产品只有真正进入生产环境、拿到数据反馈，才算进入了循环。 建造者的工作也可以从非零起点开始。假设一位设计师用 AI 生成了一整套设计语言，并在某个代码库里成功地进入了生产环境，那这一刻她就是建造者。重点在于，Builder 是能把东西跑起来的人，这通常需要一些工程上的直觉。 **Sweeper：「把它变好」** 据 Boris 自己披露，今年到现在他有 40 万行代码新增，另外还有 25 万行代码删减。这 25 万行删减里，有相当一部分就是把没用的东西清掉。这正好对应第三种原型：清扫者。 清扫者持续地清理和简化系统。在 Boris 的原话里，他们的工作包括清理 UI、简化代码和系统、下线功能（un-ship）、优化性能[3](https://lionad.art/#user-content-fn-five){#user-content-fnref-five-3 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。把没有用的系统下线，让产品和平台变得更干净，这需要很强的产品感和工程品味。 **Grower：「让它长大」** 增长仍是传统意义上的增长。增长者接手一个已经建好的产品，不断迭代，把产品-市场匹配（Product-Market Fit，PMF）拉高。 他们在干什么？做新需求、新实验、投新广告，看数据、调转化、跑 A/B 测试，去找真正影响用户指标的那个东西。 如果说建造者负责把东西跑上线，增长者就是那个真正把产品放进「假设 → 验证 → 调整」这个数据循环里、越跑越快的人。 **Maintainer：「让它稳稳地跑」** 最后是守护者。他们是专家群体，有扎实的理论知识和实际运营经验，守着成熟系统，让它安全、可靠、高效地向外扩展。 AI 能帮守护者更快地定位问题，但系统边界、数据风险、架构取舍、业务正确性这些地方，仍然需要资深工程师兜底：他们是最懂某一个系统的人。而判断「什么不能动」这种直觉，至少现在的 AI 还没有。 ## 团队阵型：按产品阶段配人 Boris 不只给了角色原型，还给了团队配置的思路。他按产品在市场上的成熟程度，把产品划分成三个阶段[3](https://lionad.art/#user-content-fn-five){#user-content-fnref-five-4 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}： - **探索期**：产品还很新，还没找到「谁愿意为它买单」。这时需要更多原型者、建造者和清扫者——大量试错，快速建造，及时清理废墟。 - **增长期**：产品找到了 PMF、正在增长。这时更需要建造者、清扫者和增长者，三件事并重，同时也开始需要一部分守护者。 - **成熟期**：产品已经有很强的 PMF、等着规模化。这时更需要清扫者、增长者和守护者，只保留一部分建造者继续建造。 规律是：清扫者从产品第一天就是刚需，而守护者是在产品走向成熟的路上加入的。 ## 与「全栈工程师」的区别 Boris 也提到，具体的人和某一种角色原型之间是动态映射：一个人的能力模型会随着阶段、兴趣和项目需求发生变化。 这里容易混淆的是：跨多种能力的角色原型，和全栈工程师（Full-Stack Engineer）到底有什么区别？ 两者的切入点不同。这要回到 Boris 的判断：编码已经是被解决的问题。 他认为工程师的大量时间耗在编码之外：和客户交流、与产品和设计碰撞想法、做技术决策、规划任务、观察数据、写文档、做迭代 0（Iteration 0）的准备[4](https://lionad.art/#user-content-fn-lenny){#user-content-fnref-lenny-2 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 这些编码上游和下游的杂务，当下的编程智能体很难直接接手。 Boris 的角色原型是一种从产品视角切入、关于「如何创建和运营产品」的能力模型。经典的全栈工程师则是技术栈导向的：理解如何设计精美的页面、创建 API、理解数据库结构、了解如何规模部署和数据运营。它关注的是端到端的交付能力。 一个回答「用什么姿态创造价值」，一个回答「用什么技术栈交付价值」。这是两个独立维度的问题。 ## 回到开头：职位还剩多少保质期 我的结论是：**AI 原生团队面对的问题，是分工形态的重排**：从按职能切，变成按原型配。 第一，AI 进入团队，先改变的是效率；而人与人、人与 AI 之间的分工形态，是更深一层的变化。 第二，原型本来就不绑职能。同一种原型，无论你是设计师、工程师还是 PM，都可能展现出来。网上常听到 PM 动手改代码的故事，就是这一点的翻版：PM 一旦上手、做成了，就成了原型者，甚至建造者。 职称标签仍然影响场上位置。我自己做前端这几年，光是职称就变过好几轮（H5 前端、Web 前端、前端工程师），不同公司对职能的理解也一直在变。但「Web 前端」这种固定称谓，作为标签的描述力正在瓦解： 它既衡量不了一个人在组织里的真实影响，也跟不上他动态变化的角色。 ## 所以，你是哪种角色 从 Boris 的观点来看，一支健康的团队不必人人全能，而是按产品阶段把原型配齐，就像一支好球队，不需要十一个梅西。 不妨观察一下自己以及身边的同事：大家在做事的时候，是一种什么样的姿态？或许你会发现，自己在某个瞬间正把一个 idea 打磨到落地、眼睛一亮，那也许就是你的优势原型在显现。 顺着这个思路，「我会不会被 AI 替代」这个普遍令人焦虑的问题，也可以换一种问法： **你是哪一种角色，以及想成为哪一种角色？** 这关乎你创造价值的方式。 --- AI 润色 ## Footnotes 1. [前后端一起消失：AI Coding 正在改写大厂工程师分工](https://www.infoq.cn/article/rHiSH66JZwoQG5Dfvv6x){rel=""nofollow""}：InfoQ 褚杏娟，2026-07-01，报道了美团 Keemart 前后端合并与蚂蚁网商测试岗转研发岗的组织调整 [↩](https://lionad.art/#user-content-fnref-infoq){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} [↩2](https://lionad.art/#user-content-fnref-infoq-2){.data-footnote-backref ariaLabel="Back to reference 1-2" dataFootnoteBackref=""} 2. [Under the River](https://shopify.engineering/under-the-river){rel=""nofollow""}：Shopify Engineering 官方博客，2026，披露了 River 的工作机制与「每 8 个合并 PR 有 1 个由其合作」的数据 [↩](https://lionad.art/#user-content-fnref-river){.data-footnote-backref ariaLabel="Back to reference 2" dataFootnoteBackref=""} 3. [Boris Cherny 关于五种角色原型的 X 原帖](https://x.com/bcherny/status/2071379474277613732){rel=""nofollow""}：2026 年 6 月底发布，提出 Prototyper / Builder / Sweeper / Grower / Maintainer 五种原型及按产品阶段配置团队的思路 [↩](https://lionad.art/#user-content-fnref-five){.data-footnote-backref ariaLabel="Back to reference 3" dataFootnoteBackref=""} [↩2](https://lionad.art/#user-content-fnref-five-2){.data-footnote-backref ariaLabel="Back to reference 3-2" dataFootnoteBackref=""} [↩3](https://lionad.art/#user-content-fnref-five-3){.data-footnote-backref ariaLabel="Back to reference 3-3" dataFootnoteBackref=""} [↩4](https://lionad.art/#user-content-fnref-five-4){.data-footnote-backref ariaLabel="Back to reference 3-4" dataFootnoteBackref=""} 4. [Head of Claude Code: What happens after coding is solved](https://www.lennysnewsletter.com/p/head-of-claude-code-what-happens){rel=""nofollow""}：Lenny's Podcast 对 Boris Cherny 的访谈，谈及「编码已被解决」的判断与工程师时间的真实去向 [↩](https://lionad.art/#user-content-fnref-lenny){.data-footnote-backref ariaLabel="Back to reference 4" dataFootnoteBackref=""} [↩2](https://lionad.art/#user-content-fnref-lenny-2){.data-footnote-backref ariaLabel="Back to reference 4-2" dataFootnoteBackref=""} # 🔧 Claude Code MCP 集体报错排查记录 ## 现象 今天在某项目打开 CC 时提示了 MCP server 报错，整整一排： ```text - MCP server 'plugin:context7:context7': failed — Skipping connection - MCP server 'glm-image-mcp-server': failed — MCP error -32000: Connection closed - MCP server 'open-websearch': failed — MCP error -32000: Connection closed - MCP server 'kimi-tools-mcp': failed — MCP error -32000: Connection closed ``` 重新启动也还是这 4 个报错，而且诡异的是，似乎和环境无关，因为有的是用 `npx`，有的用 `pnpm dlx`，但都挂了。 而除了这 4 个 MCP Server 以外剩下的所有都能正常运行。这就奇怪了。 ## 是环境问题吗？ 直觉告诉我是 Node 版本问题，可能跟我的环境配置有关。 因为在一些老项目，我通过 fnm 维护项目级别的 Node.js 版本： - 全局使用 `fnm` 管理 Node，默认 `v22.22.1` - 项目根有 `.node-version` 文件，Node.js 版本锁定 `16` 所以当我在项目的 Terminal 启动 CC 时，理论上使用 16 版本的 Node.js 去加载这些 MCP Server。 ... 验证过程非常简单，直接使用 npx 启动某个 MCP Server 即可。 Node 16 下启动 `open-websearch`，会发现报错。 ```text $ npx -y open-websearch@latest TypeError: Class extends value undefined is not a constructor or null at @hono/node-server/dist/index.mjs:23 ``` 换 Node 22 就好了。猜想成立，根因就是 Node 版本。 ## 怎么修改呢？ 理所当然，我第一反应是：直接指定某个 Node.js 版本的 npx 路径就行，比如： ```json { "command": "/Users/.../fnm/node-versions/v22.22.1/installation/bin/npx", "args": ["-y", "@upstash/context7-mcp"] } ``` 改完重启发现 MCP Server 还是报错。 一时间没反应过来，但是手动执行指令时，发现了异常日志： ```text $ /Users/.../fnm/node-versions/v22.22.1/installation/bin/npx -y @upstash/context7-mcp npm warn cli npm v10.9.8 does not support Node.js v16.20.2. ReferenceError: ReadableStream is not defined ``` 就算使用 22 版本的 npm 执行脚本，日志提示的 Node.js 还是 16.20.2，这里就触及到知识盲区了。 ## 隐藏机制：shebang `npx` 本身也是 Node.js 脚本。 如果你打开 `npx-cli.js`（比如在我的电脑中指向 `~/Library/pnpm/nodejs/22.22.1/lib/node_modules/npm/bin/npx-cli.js`），能看到以下内容。 ```text #!/usr/bin/env node const cli = require('../lib/cli.js') ... ``` 要讲的是第一行，`env node` 会按 `PATH` 顺序找到第一个 `node`。所以这里解析出来的环境，并不一定等同于我指定路径的 npx 所对应的 Node.js。 简单来说，光换 `npx` 的路径没用，需要把整个执行环境的 Node.js 切换过来才行。 ## 最终方案：wrapper 所以得换方向，写一个 shell 脚本，把所有要执行的内容放到脚本里，然后在脚本顶部定义好我们需要的环境变量，这样能锁定脚本执行的 Node.js 版本。 见以下代码，wrapper 的内容可以写死 PATH，exec 则用来透传剩下的所有参数。 ```bash #!/usr/bin/env bash export PATH="/Users/.../fnm/node-versions/v22.22.1/installation/bin:$PATH" exec "$@" ``` 回到 MCP 配置，只需要把 `command` 指向 wrapper 脚本。 ```json { "command": "/Users/lionad/.claude/mcp-node22.sh", "args": ["npx", "-y", "@upstash/context7-mcp"] } ``` 最后改好配置验证一下 `open-websearch`： ```text $ ~/.claude/mcp-node22.sh npx -y open-websearch@latest 🔍 Default search engine: bing 🔍 Search mode: AUTO ... ``` OK，搞定。 # 📦 使用 cc-expand 将可用上下文窗口扩大 60%，甚至更多 最近做了一个小工具 **cc-expand**，用来解决 Kimi 在 CC 中使用时过早压缩的问题。 这个工具一开始是个简单的脚本，最近才下决心把它做成包。 一方面是估摸着国产大模型很快会步入全面 1M 上下文时代，这个包可能随时会被抛弃，另一方面，讲真，我也不确定这玩意儿的性能增益具体有多少。 不过可以这么说，社区的主流意见是，上下文压缩会带来模型性能下降，所以可以看到 GSD 等 SDD（Spec Driven Development）框架，都是围绕「尽可能在不压缩的会话里，即一个上下文内解决一个任务」这种思路来设计的。 此外，我们还经常听说一些因为压缩丢失细节而导致的莫名其妙的问题。 所以，做这个小工具的初衷很简单：既然 Kimi 支持 256K 上下文，那就把 CC 的上下文长度也顶到 256K。 理论上有很多种方法可以实现这个功能。举个例子，你可以把 token 上限设到 1M，然后通过 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 来控制压缩时机； 也可以设置 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 并关闭自动压缩。但这些方法都不够性感，所以我做了 **cc-expand**。 它的原理很简单：patch Claude Code 的本地二进制，把内部写死的、与上下文窗口相关的一些变量提高到你设定的目标值，从而推迟 auto-compaction，让 Claude Code 在更长的上下文里保持高性能。 比如我日常使用的模型支持 256K context，我会把目标窗口设到 270000，这样自动压缩的触发点会从 167k 明显后移到 237k。默认 CC 有约 30k 的压缩预留区，设置到 270k 后，长任务比如重构、多文件阅读， 会舒服非常多。 经过最近几周的体验，我认为 270k 作为 CC 重度开发时预留的压缩缓冲是安全的。对喜欢折腾 Claude Code、希望榨干上下文窗口的人来说，这个小工具会很好玩。 cc-expand 的功能有这些，支持安装 CC、patch、验证、恢复等命令，并且支持 Mac 和 Windows 双平台。 期待国产模型早日上到 1M 吧，在此之前抓紧玩耍！ 项目地址： :br{rel=""nofollow""} # 🎼 从文本到交互界面——GenUI 的中庸之道 ## 从文本到界面 现在想象一个 LLM 聊天场景。 用户向 LLM 询问"2026 年有哪些值得关注的北欧风室内设计"，它开始输出一大段文字：明厅设计采用落地窗搭配浅色木地板，采光充足；厨房以白色橱柜和原木台面为主，强调功能性……用户逐行阅读，在脑海中拼凑画面。 但看一大段文字并脑补，很费力气。同样的内容，也可以这样呈现： ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260602104634638.gif) LLM 的纯文本输出的信息密度很高，但需要读者掌握提炼重点的技巧才能流畅阅读。而且存在固有局限，缺乏层次、没有视觉锚点、无法交互。 图中展示了如何在纯文本输出中融入 Generative UI（GenUI）的效果——LLM 的输出不再是一段需要自行消化的文字，而是一个可以直接浏览、点击、交互的界面。人从返回内容中获取信息的效率，存在量级差异。 但纯 HTML 也不行，尽管 LLM 对 HTML 非常精通，但在聊天模式中，工程上难以对产物进行约束。 我认为之后很长一段时间，人机交互形式都不会是 HTML 甚至实时渲染，而是存在于需一种介于两者之间的形式——既保留 Markdown 的简洁和 LLM 的熟悉度，又能承载结构化组件的交互能力。 我猜有人想说 MDX，这的确是一种选型，但在这个场景我们选择了输出和解析都更简单的 Markdown + Spec 模式：用 Markdown 组织文本和推理过程，用代码块承载结构化的组件规格（Specification）。 Spec 比 HTML 语义更单一、结构更扁平，LLM 输出更稳定，前端解析也更简单，作为协议层，恰好处于"足够表达组件语义"和"足够简单可控"之间的中间态。 下面以 `vtu-cmpts` 的 ImageGallery（画廊）组件为例，按数据流顺序，走完从 LLM 输出到可交互界面的完整旅程。 ## 从流到组件：ImageGallery 的完整旅程 整个数据流分为五层： ```text LLM Stream → chunk-processor → Spec 提取 → VtuRenderer → 用户交互 → 新一轮对话 ``` ### 组件库架构 结构化的输出需要一套预定义的组件库。组件库用什么框架写并不重要，关键是组件必须是状态驱动的自包含单元——每个组件通过 Props 接收数据，通过事件向外通信，不依赖外部的 context 或状态树。 Headless 模式组件库比较适合这个场景，但因为使用 Vue 技术栈，扫了一圈市面上没有合适的库，所以我只好找到 assistant-ui 抄了一份 vue 组件。 在 Vue 项目中，我们使用经典的桶模式组织组件： ```text index.ts // 组件入口，连接组件与工程 index.vue // 组件界面骨架，整合依赖与内部逻辑 meta.jsonc // 组件定义，兼顾人类阅读与机器理解 states/*.ts // 组件状态及状态驱动的方法 config/*.ts // 组件所需的数据或配置 ``` 桶模式的好处在于结构扁平，LLM 能一步到位理解组件全貌，不需要先读入口文件，再追踪 import 链去翻其他模块。 index.ts 或目录如果有 spec.ts 即组建的 spec 定义。以 ImageGallery 为例，它的 Props 定义如下： ```ts export const ImageGalleryItemSchema = z.object({ id: z.string().min(1), src: z.url(), // ... }); export type ImageGalleryItem = z.infer; /* ... */ export interface ImageGalleryProps { id: string; images: ImageGalleryItem[]; onImageClick?: (imageId: string, image: ImageGalleryItem) => void; // ... } ``` 可以看到这个组件使用 Zod 作为唯一的 Spec 来源。 `type ImageGalleryItem = z.infer` 从 Zod Schema 派生出 TypeScript 类型——一份定义， 同时服务于编译时类型检查和运行时校验，是一个极好的胶水层。 关于这个组件库，它叫[vtu-cmpts](https://lionad-morotar.github.io/tool-ui-vue/){rel=""nofollow""}，有表格、画廊，然后图表等展示类组件，也有表单、审核卡片等交互组件，加起来共计二十余种组件，基本覆盖了我们目前的使用场景。 | 类别 | 组件 | | ----- | -------------------------------------------------------- | | 数据展示 | Article、DataTable、Chart、StatsDisplay、WeatherWidget | | 代码 | CodeBlock、CodeDiff、Terminal | | 社交/内容 | ContactCard、Citation、XPost | | 表单/输入 | ApprovalCard、OptionList、ParameterSlider、PreferencesPanel | | 流程 | QuestionFlow、Plan、ProgressTracker、OrderSummary、GeoMap | 从 React 到 Vue 的迁移过程还是蛮顺利的，如果有人想看看怎么处理代码重构，或者之后有空找机会写篇博客分享一下。 ### Spec 协议 LLM 不会直接输出组件代码，而是输出一种中间协议——Spec。在我们的实践中，Spec 以 Markdown 代码块的形式嵌入对话： ```markdown 2026 年的销售数据和转化率如下： \`\`\`json { "root": "main", "elements": { "main": { "type": "Stack", "props": { "direction": "row" }, "children": ["card-1", "card-2"] }, "card-1": { "type": "StatCard", "props": { "title": "总销售额", "value": "120万" } }, "card-2": { "type": "StatCard", "props": { "title": "转化率", "value": "3.2%" } } } } \`\`\` ``` Spec 采用 Vercel json-render 的 Flat Map 协议。组件在 `elements` 对象中以扁平列表形式输出，而非嵌套结构。扁平 Spec 有两个天然优势：结构简单，不会给 LLM 增加嵌套复杂度； 数据易于增量更新，适合做流式渲染。 ### chunk-processor 数据流从 Markdown 开始处理。在 Markdown 解析器方面选择了开源组件 markstream-vue，因为后者提供了自定义标签与高级组件功能，同时还有高性能的节点缓存，能直接接管由 MD 到混合输出渲染。 chunk-processor 就是 sse streaming 到交给 markstream-vue 中间的数据处理层。把 JSON Spec 提取出来交给渲染引擎，但细的来说： 1. 检测——扫描流式文本，找到 ` ```json ` spec 代码块 2. 提取——用 `jsonrepair` 修复不完整的 JSON（缺少闭合括号、字符串没写完）。 3. 验证——检查是否符合 vtu-cmpts Spec，即 `{ "root": ..., "elements": ... }` 结构。 4. 转换成文本模板如 ``，后者通过自定义标签在 markstream-vue 注册。 LLM 吐到一半的内容可能是这样的： ```json {"root":"root","elements":{"root":{"type":"Col ``` 括号未闭合，字符串未结束，直接 `JSON.parse` 会报错。chunk-processor 在流式上下文中持续修复这些碎片，让下游渲染器始终能拿到合法的 JSON。 除了提取以外，chunk-processor 通过中间件的形式提供对 spec 的增强，比如下一小节提到的 spec 流式渲染能力。 ### 流式渲染 如果等 JSON 全部生成完再渲染，用户会面对几秒钟的空白，然后界面突然弹出。流式渲染要解决的是：如何在数据尚未完整时，就给出有意义的界面反馈。 目前一个稳定的方案是在提示词中引导 LLM 按固定顺序生成 Spec 属性，比如先输出 `type`、`id`、`title` 等元信息，再输出数据密集型字段。这样即使 `images` 数组尚未到达，渲染器已经能画出组件骨架： ```json { "root": "main", "elements": { "main": { "type": "ImageGallery", "title": "2026 北欧自然风景精选", }, } } ``` ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260602131829076.png) 此时 ImageGallery 以空状态或 loading 状态呈现，用户知道内容正在生成。随着流继续，当第一个完整的 `ImageItem` 到达时，触发节点激活，图片开始逐张渲染： ```json { "root": "main", "elements": { "main": { "type": "ImageGallery", "title": "2026 北欧自然风景精选", "images": [ { "id": "img-1", "src": "https://picsum.photos/seed/nordic1/800/600", "title": "明厅设计", "caption": "落地窗 + 浅色木地板" }, ] }, } } ``` 所以第一个要介绍的 chunk-processor 的增强插件就是 data-trigger，他支持给不同组件设置不同的数据触发节点。 举个例子，Chart 允许按 Series 的数据项触发渲染；文档（Markdown inside markdown）允许按行刷新等等。手动实现触发节点可以达到极为精确的控制效果。 当然，回退到简单策略也可行——比如每固定间隔 100ms 对当前 Spec 做一次补全，并触发组件重渲染。 最终，流结束后，ImageGallery 的 `images` 数组完整，界面从骨架蜕变为可交互的完整画廊。 ### 用户交互 Generative UI 如果只能看不能点，那只是花哨的 Markdown。 传统界面通过事件绑定执行特定函数，但 GenUI 的理想情况是事件不交给 LLM 去配置——LLM 不理解整个交互上下文。我们把交互按复杂度分层：纯文本、可播放媒体、按钮等单点交互、表单等有状态容器、弹窗、长时任务。在展示类场景中， 交互复杂度控制在表单及以下层级。 单点交互的处理很直接：给 LLM 提供上下文即可。比如用户点击 ImageGallery 的某张图片，系统捕获到「用户点击了图片：明厅设计」，将其拼接到下一次对话的上下文中，LLM 基于这个信息生成新的回复。 点击 DataTable 表格行的“详情”按钮或 OptionList 的多选一同理，见以下图片： ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260602132253374.png) 表单类组件带状态，稍微复杂一些，需要渲染器具备注入能力。 注入可以是状态（Vue 的响应式值，可与 localStorage 绑定），也可以是事件。VTU 组件暴露特定事件，所以能注入特定处理函数，也可以通过 DOM 监听统一捕获组件内部的点击、切换等交互。 只要事件能被捕获，操作空间就大了。我们可以决定拼接什么上下文、是否立即发送进入下一轮对话、还是等用户补充更多信息。如果输出包含多个 Spec，多个组件的交互上下文可以同时被收集——比如用户勾选了 DataTable 的几行， 再从 OptionList 中选了"查看价格"，最终的上下文会携带表格行选择信息和按钮点击信息。 这些被捕获并拼接成带上下文的数据，被添加到下一次用户提问。LLM 根据这个上下文继续生成新的回复，问答场景形成闭环。 ### 容错设计 最后简单提一下容错。LLM 输出不稳定是常态，即使 Prompt 写得再详细，输出也会碰到不合格的状态——缺字段、类型错误、甚至混入自然语言。 组件层、渲染层、交互层都需要相应的容错和恢复机制。组件层通过 Zod Schema 做运行时校验，不合法的 Spec 被拦截在渲染之前。渲染层对不完整的 JSON 做降级或增强溃。交互层则确保事件捕获和上下文拼接的鲁棒性， 不会因为某个组件的异常而影响整个对话流程。 ## 未尽之路 这篇文章涵盖了 GenUI 落地的六个核心问题：组件库设计、协议设计、流式碎片提取、中间态渲染、交互回传、异常容错。 每一个环节都还有深入的空间，但将它们串联起来，已经能勾勒出一幅从 LLM 文本流到可交互界面的全景图。 时间成本也是非常低，整个 Demo 从 Agent 到组件库和前端，只花费约 40 人日——放在以前纯手作时代，不敢想象要抄多少代码才能把代码串起来（笑。 不过实践过程中，我也遇到了一些没有解决思路的问题。 一是聊天页的虚拟滚动。每条消息都包含工具调用、思考过程和最终回答等不同聊天块。这些块高度差异极大，精确计算高度比较困难。但开不开虚拟滚动，却会直接影响长对话的性能表现。怎么处理长对话是个问题。 二是自定义组件的可能性。结论可行，但需要一个足够强壮的 Renderer 和规范层。如果做过低码，应该能理解这里的挑战。 如果站在更宏观的视角看，LLM 的输出形态从文本到界面演进是必然进程。当 AI 的回答不再是一段需要自行提炼的文字，而是一个可以直接操作的界面时，人与 AI 的协作模式会发生根本变化。以后有机会会继续分享相关内容。 # 🌊 Project River：把 Git 提交历史变成一条河 当需要在几个开源项目之间做选择（技术选型，评估引入依赖），你大概会去看 GitHub Star 数、最后提交的时间、Issues 积压情况。 这些数据有用，比如 Star 直接和知名度绑定，但因为此类指标没有和时间挂钩，所以不够直观。 所以我做了 Project River，一个把一个 Git 仓库的贡献者提交活动，渲染成随时间流动的河流图。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260423104444299.png) 因为当我面临选择时，我想知道项目的核心维护者是谁？社区参与度怎么样？版本节奏如何？ 而为什么是河流图，不是更常见的折线图或热力图？因为折线图展示的太“清楚”，没有一个真实项目开发中“混乱”但有“主心骨”的感觉。 经典的河流图长这样： ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260423104814092.png) Project River 的河流图稍有差异但河流特性是一致的。 以下我使用两个经典项目的 Project River 来举例。 河流越宽，说明提交越多。每条色带是一位贡献者。一眼就能看出谁一直在写代码、社区什么时候开始壮大、核心作者有没有离开。不需要读任何数字，就能对项目的人力投入历史产生直觉判断。 **React**：没有一条独大的色带 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260423021337319.png) React 没有一条独大的色带，多条宽带交替出现，反映出 Facebook（现 Meta）内部多人协作的模式。每年的 React Conf 前后，都能看到提交量的明显脉冲。 **jQuery**：一个时代的落幕 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260423021433146.png) jQuery 的河流图像一条逐渐干涸的河。2012-2014 年前波澜壮阔，之后突然收窄。这是前端生态热度更替最直观的注脚，可能没有比这更清晰的方式来说明「一个库的社区热度过去了」。 实际上，从 commits 能读出很多有意思的时间节点。比方说今年 jQuery v4（是的，jQuery 发新版了）前，官方仓库有大量提交。往年发补丁也是如此。 如果接入 Agent，对项目分析质量能得到质的飞跃，这也是我对 Project River 往后的期望。 ## 一些交互能力展示 河流图支持鼠标滚轮缩放和底部缩略时间轴（minimap）刷选。对某个时段感兴趣——比如一个大版本发布前后——可以放大看那个区间的贡献者构成。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260423105814536.png) 另外，还有切换配色，切换多语言之类的小功能。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260423105657433.png) ## 使用方式 最近没有闲钱开服务器了，所以我只做了静态版本：直接在 git pages 打开 {rel=""nofollow""} 即可体验，预置了 Vue.js、React、jQuery 和 Atom 四个项目的数据。 如果想分析自己的仓库，需要拉取项目代码本地部署。本地部署后，可以分析 github 链接或本地仓库。 当然，现在功能局限很多，比如数据是静态快照不会自动更新，想看最新数据需要重新跑一次分析。另外，只统计 Git 层面的活动，Issues、PR Review 等维度没有纳入。我对数据分析的理解还非常浅显，比如贡献量也不等于贡献质量—— 一个提交了 1000 行格式化代码的人，在图上看起来比修复了关键 Bug 的人贡献还更大...老实说，还在想办法解决。 技术上，Project River 基于 Nuxt 4 和 D3.js 构建，在线 Demo 的数据经过列式压缩后打包为静态文件部署在 GitHub Pages 上，访问时不需要服务器。项目以 BSL 1.1 许可证开源，个人使用完全免费。 --- **相关链接** - 在线体验：{rel=""nofollow""} - 开源地址：{rel=""nofollow""} # 🪦 生命周期只有26小时的项目 4 月 1 日 21:59，safe-npx 项目启动。 4 月 3 日 00:45，我决定归档这个项目。 生命周期：大约 26 小时。 ## 起因 2026 年 3 月 30 日深夜，知名 HTTP 请求库 Axios 遭到供应链投毒攻击。 攻击者在两个新版本中注入了一个首次出现的恶意依赖包，植入了跨平台远程访问木马。 npm 在攻击版本发布后约 3 小时 19 分钟将其删除。普遍建议是立即回滚到 v1.14.0。 但即使攻击窗口只有 3 小时，考虑到 Axios 每周下载量超 3 亿次，潜在影响的项目可能数以万计。 我在想：如果能阻止开发者安装这 3 小时内发布的新版本，能不能减少伤害？ 通过搜索，我找到了 [`safe-npm`](https://github.com/kevinslin/safe-npm){rel=""nofollow""} 这个项目，使用非常简单，`safe-npm install --min-age-days 120` 就能阻止安装发布不满 120 天的包。 过去几年，我们经常听到某知名包的漏洞在发布不久就被曝光。有不足 24 小时的，1 天的，3 天的——社区的响应速度很快。 换句话说，使用发布时间作为防护供应链攻击的检测手段，的确有意义。 这里我犯了一个错误：草率搜索后，就认为尽管有 `safe-npm` 但没有 `safe-npx`。 ## snpx 我开始写 `snpx`，用于拦截 `npx pkg@latest` 调用的工具（在 MCP 满天飞的时代，这很有用）。它会检查 `latest` 版本的发布时间，如果小于 24 小时，就回退到上一个版本。 我想像中的使用场景和 `safe-npm` 一样简单： ```bash snpx some-mcp@latest ``` 如果你在使用 `ccstatusline` 或类似工具就能明白我在做什么。 很多时候需要运行脚本时，会直接配置 `npx some-mcp@latest` 来获取最新功能。这里有一个假设：新版本会修复旧版本的漏洞，所以要比旧版本更安全。 类似 Axios 事件发生，一旦攻击者发布了受污染的新版本，用户会在执行 `npx some-mcp@latest` 时立刻中招。`snpx` 的作用就是默认忽略发布不满 24 小时的版本，回退到上一个版本，这一过程是透明的。 ## 价值危机 代码、README、博客……借助代理的力量，几乎所有内容都在字面意义上的"瞬间完成"。但在我准备开始推广时，发现了问题。 npm 在 2026 年 2 月合并了 [`min-release-age` 功能](https://github.com/npm/rfcs/issues/646){rel=""nofollow""}。 要解决问题的和 `snpx` 是一样的，为使用基于时间成熟度的安全策略提供了一个快速入口： ```bash npm install -g npm@latest echo "min-release-age=7" >> ~/.npmrc ``` 只要你的 npm >= 11.10.0，设置后，所有 `npm install` 和 `npx` 调用都会检查包的发布时间。如果发布日期太新直接拒绝安装。 ```bash ❯ npx -y cowsay npm error code ENOVERSIONS npm error No versions available for cowsay ``` ## 一些思考 简单思索后，我决定在 README 引导用户安装 `npm@latest`，同时归档 `snpx`。 这便是 `snpx` 的困境：平台能力层的扩展吞并了部分工具层。我并不是说工具层在将来会变得一无是处，相反，微型工具将会借助代理的无码力量形成新的价值胶水层。只是怪我启动项目时没有做更全的调查。 不过好在我的情报质量要比调查质量更高，不然很可能老老实实把 `snpx` 做得更完整了问题才暴露。 突然很怀念以前简单做个组件库就能坐下来安静敲一个月代码的日子。如今这个实现变得和想法一样廉价的年头，编程的乐趣从单纯的代码实现转变成了另一种不可名状的东西。我对此喜忧参半。技术人还能死死抓住的是什么呢？ # 📦 一个简单有效的端口命名策略 太多项目要跑，端口号命名是个麻烦的问题。 - Vibe 流行的这两年，新项目眼花缭乱，太多项目要本地启动才能验证和消化，多个项目端口号容易冲突 - 为了在浏览器保存标签页（或书签），每个项目的端口号是不能改变。 比如，我电脑上光 Nuxt 应用程序就十来个，清一色的 3000 端口，肯定不行，所以创建了一套简单有效的端口命名规则，用来约定项目端口号。 ## 核心思路 与其随意挑选数字，不如把 **项目名称映射到键盘上对应的数字** 来生成一个“可读、可记”的端口。只要结果落在合法的端口范围（0 \~ 65535），且不占用系统保留端口，就可以直接使用。 即按照标准 QWERTY 键盘的 **行列坐标** 把每个字母映射为一个单数字，举个例子 “cfetch” → `c(3) f(4) e(3) t(5) c(3) h(6)`，取前四位即 3453 或全部五位 34353 都可以。 有些项目前端、后端、数据库等等包含多个端口号，则以下两种命名方式二选一： 1. “cfetch”，取 3435，然后前端（fe，即 43）取 34354，后端（server）取 34352，数据库（mongo）取34357，以此类推 2. “cfetch”，取 3435，然后 Web 取 34351，后端取 34352，数据库取34353，以此类推 ## 端口号的合法范围 - 端口号必须在 **0‑65535** 范围内。 - 对于自定义服务，一般建议使用 **1024 \~ 49151**（非系统保留范围）或更高的 **49152 \~ 65535**（私有/动态端口）。 - 只要映射得到的数值不超过上述上限，就算有效。 --- AI Translation When you’re running a bunch of projects locally, picking port numbers becomes annoying. - Over the last couple of years, there have been *so many* new projects. To really try them out, you often need to boot them locally—and then ports start colliding. - If you want to keep browser tabs (or bookmarks) stable, a project’s port shouldn’t keep changing. For example, I have more than ten Nuxt apps on my machine. If they all default to `3000`, that’ s obviously not going to work. So I came up with a simple, consistent port naming rule to “assign” ports per project. ## Core idea Instead of picking random numbers, map the **project name to numbers based on the keyboard**, so the port is *readable* and *memorable*. As long as the result is within the valid port range (**0–65535**) and doesn’ t hit reserved/system ports, you can just use it. More specifically: using a standard QWERTY keyboard, map each letter to a single digit based on its **row/column position**. Example: `"cfetch"` → `c(3) f(4) e(3) t(5) c(3) h(6)` Then you can take the first 4 digits (e.g. `3453`), or keep more digits (e.g. `34353`). Either is fine. If a project needs multiple ports (frontend, backend, database, etc.), pick **one** of these two approaches: 1. Use the project prefix, then append a “role suffix” - For `"cfetch"`, take `3435` as the base - Frontend (`fe`, i.e. `43`) → `34354` - Backend (`server`) → `34352` - Database (`mongo`) → `34357` - …and so on 2. Use the project prefix, then assign sequential roles - For `"cfetch"`, take `3435` as the base - Web → `34351` - Backend → `34352` - Database → `34353` - …and so on ## Valid port range - Ports must be within **0–65535**. - For custom services, it’s usually best to use **1024–49151** (non-reserved) or **49152–65535** (private/dynamic). - As long as the mapped number stays under the limit, it’s valid. # 🌪️ Tailwind v4 如何兼容预处理器 ## 背景 Tailwind4 带来的一个显著的技术偏见就是不再支持 sass 之类的预处理器。这使得如果想要享受 tailwind4 性能及其他福利，需要把大量样式文件重构成原生 CSS。这在部分项目是不可接受的。 上周处理了一个依赖 Nuxt UI 的项目的升级。Nuxt UI 和 tailwind 是强绑定关系，换句话说 tailwind 是必选项。这里简单说一下处理思路，只是一个可行方案，仅供参考，之后社区可能会有更成熟的解决方法。 项目代码结合使用了 sass 函数和 tailwind 的 @apply 指令，如下图示。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202503241648840.png?w=50) 简单移除 SCSS 不是一种选择，所以希望能有一种这种的方法，既用上 tailwind4，又能让现有代码继续使用。 ## UnoCSS UnoCSS 是一个原子化 CSS 引擎，在某种程度而言，他和 tailwind 是竞品关系。但是比 tailwind 更先进的一点体现在他的设计得非常灵活和可扩展，可以通过定义规则来支持各种用法，且包含转化器， 可以解析并处理 @apply 等指令。 见 [Presets Wind4](https://unocss.dev/presets/wind4){rel=""nofollow""}，UnoCSS 支持 tailwind4 的语法和功能，并且可以无缝集成到 Nuxt 应用中。首先是安装 UnoCSS 并启用相应的 preset： ```ts import presetWind4 from '@unocss/preset-wind4' import { defineConfig } from 'unocss' export default defineConfig({ presets: [ presetWind4(), ], }) ``` 接下来启用转换器以便解析 scss 文件中的 @apply 指令。这样 @apply 中包含的 tailwind 类名能被正确解析并转换为样式代码，并在项目中生效。 ```diff import presetWind4 from '@unocss/preset-wind4' + import transformerDirectives from '@unocss/transformer-directives' import { defineConfig } from 'unocss' export default defineConfig({ + transformers: [ + transformerDirectives(), + ], presets: [ presetWind4({ reset: false, }), ], }) ``` 不过仍然有一个问题，tailwind4 的样式重置和 UnoCSS 会起冲突，并且由于 Tailwind4 大量代码依赖原生的 CSS 层，优先级低于 UnoCSS 生成的样式，所以界面仍然是错乱的。 所以最后一步是 UnoCSS 生成的样式的优先级。首先开启 UnoCSS 的输出样式代码到 CSS Layer 功能。 ```ts export default defineConfig({ // ... outputToCssLayers: true, }) ``` 然后，在 main.css 或其他样式入口，降低 UnoCSS 的输出层优先级。默认 UnoCSS 输出到 default 层，所以在入口文件使用 layer 语法预先定义 default 层和 tailwind 层（base、 component、utils）的优先级，如下代码。 ```css @layer default, base, components, utilities; ``` 重启项目，界面就正常了。接下来，等待 UnoCSS 化的 Nuxt UI，或者静候 tailwind 社区佳音吧。 ## 其他 相关讨论：[Github issue 14376](https://github.com/tailwindlabs/tailwindcss/issues/14376){rel=""nofollow""}、[Github issue 15716](https://github.com/tailwindlabs/tailwindcss/issues/15716#issuecomment-2619593290){rel=""nofollow""} # 🥞 在 tailwind 中使用现代化 CSS Layers ## 增订 | 2025-02-15 Tailwind 4 除了带来惊人的性能提升以外，还支持原生 CSS Layer 啦，快去试试！ ## 分层理论 Tailwind 提供了一个 Layer 的概念，通过对样式代码进行分层管理，能够有效减少样式冲突的发生。这些样式主要被划分为以下三层： 1. base：基础层，样式重置 2. components：组件层，组件和模块的样式。 3. utilities：工具类层，原子样式（各种实用工具类比如边距、颜色等） 这是一段经典的 tailwind 分层代码： ```css @tailwind base; @tailwind components; @tailwind utilities; @layer components { .card { box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); } } @layer utils { .glow { box-shadow: 0 0 10px rgba(0, 0, 255, 0.5); } } ``` 每层的优先级逐层递增。例如，当组件应用了 .card 样式后，可以通过 .glow 在业务代码中轻松覆盖，并且这一过程没有多少思维负担。 这种层级管理的方式在实际项目中相当有用，以前也有过类似的分层理论，比如 ITCSS，但是没有现代前端开发如此完备的基建的基础，使用起来相对复杂，所以难以深入人心。如今只要在项目引用 tailwind，就能方便实践一系列好用的理论， 这也可能是 tailwind 能够迅速流行的原因之一。 不少前端应该知道 CSS 也有一个 Layer 的概念。其正式名称是 CSS Cascade Layers。相关的一系列新功能，支持率已经很好了，可以放心使用。 ![can i use css layer](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202501061809992.png) ## 结合原生 CSS 在项目中引用 tailwind 容易引起传染。当子项目使用 tailwind Layer 后，为了主项目也能享受相应的写法加成，主项目也有必要安装并配置 tailwind。对于较大的项目，尤其是有历史积累的代码库，这种“传染性” 可能会对架构的统一性与维护性造成负面影响。为了在更大范围的层度保证架构的统一和整洁性，我倾向使用原生 CSS 方法，作为 tailwind 的替代，但不能反过来。反过来 tailwind 只能作为原生 CSS 的补充。 怎么把 tailwind layer 和 CSS Layer 结合起来呢？ CSS Layer 支持在导入时指定层级，所以写法很简单。 ```css @import "tailwindcss/base" layer(my-base); @import "tailwindcss/components" layer(my-components); @import "tailwindcss/utilities" layer(my-utilities); ``` ## 结合 Sass 但实际能不能这么写取决于你项目中的 postcss 以及相关 CSS 处理器的版本和配置。如果你使用的是 Sass，那至少目前为止得使用另一种写法： ```scss @layer app-base { @import "tailwindcss/base"; } @layer app-cmpts { @import "tailwindcss/components"; } @layer app-utils { @import "tailwindcss/utilities"; } ``` 使用上述方法可行，但是会在控制台抛警告。 ```bash Deprecation Warning: Sass @import rules are deprecated and will be removed in Dart Sass 3.0. More info and automated migrator: https://sass-lang.com/d/import ``` 新版 Dart Sass 将要废 `@import`语法，详见文档 [`@import` is Deprecated](https://sass-lang.com/blog/import-is-deprecated/){rel=""nofollow""}。这个问题大家也应该处理过，直接替换 `@use`即可。那么惊喜来了，目前为止还是不支持这种 `@layer`中使 `@use` `@forward`之类规则的写法。 ```scss // ❌ 错误的 @layer app-base { @use "tailwindcss/base" as *; } @layer app-cmpts { @use "tailwindcss/components" as *; } @layer app-utils { @use "tailwindcss/utilities" as *; } ``` 因为 Sass 使用的是静态解析，所以在`@use`需要放到文档头部，而在`@layer`中使用会打破这个规则。那么有没有解决办法呢？有的，使用内置 API 直接引用 CSS 文件，就能绕过使用`@import`限制。 简单来说就是使用`meta.load-css`API。 最终代码参考： ```scss @use "sass:meta"; @layer base, app-base, components, app-cmpts, cx, utilities, app-utils; @layer app-base { @include meta.load-css("tailwindcss/base"); } @layer app-cmpts { @include meta.load-css("tailwindcss/components"); } @layer app-utils { @include meta.load-css("tailwindcss/utilities"); } ``` 成功跑起来啦，此处应有点赞。 ## 更多 - [Can I use CSS Cascade Layers](https://caniuse.com/?search=css%20layer){rel=""nofollow""} - [Layer 入门](https://www.zhangxinxu.com/wordpress/2022/05/css-layer-rule/){rel=""nofollow""} - [ITCSS](https://developer.helpscout.com/seed/glossary/itcss/){rel=""nofollow""} # 💻 本地部署 Qwen 翻译网页 ## 增订 | 2025-12-20 发现沉浸式翻译对一连串的请求有优化，所以不再使用自定义服务器转发，而是通过添加自定义服务来实现。 因为 LM Studio 的 API 是 OpenAI 兼容的，所以自定义服务选 OpenAI。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20251222194748237.png) 然后把配置都填一下。以我的配置为例：APIKEY 随便填，模型填你在 LM Studio 下载的模型名称，自定义 API 接口地址可以填 `http://localhost:1235/v1/chat/completions`。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20251222194828774.png) 最后是安装 nginx，把请求转发到本地 LM Studio 的服务器上。因为沉浸式翻译插件发起的请求会有 CORS 限制，所以需要在 nginx 里统一添加 CORS 相关的头信息。 以下是一个简单的 nginx 配置示例： ```nginx # lm studio :1234 server { listen 127.0.0.1:1235 ssl; server_name 127.0.0.1; ssl_certificate ./ssl/localhost.crt; ssl_certificate_key ./ssl/localhost.key; location / { # 隐藏后端返回的 CORS 相关头 proxy_hide_header Access-Control-Allow-Origin; proxy_hide_header Access-Control-Allow-Methods; proxy_hide_header Access-Control-Allow-Headers; proxy_hide_header Access-Control-Allow-Credentials; proxy_hide_header Access-Control-Expose-Headers; # nginx 统一设置 CORS 头 add_header 'Access-Control-Allow-Credentials' 'true' always; add_header 'Access-Control-Allow-Origin' '<插件ID>' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Api-Key' always; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always; # 处理 OPTIONS 预检请求 if ($request_method = 'OPTIONS') { add_header 'Access-Control-Allow-Credentials' 'true' always; add_header 'Access-Control-Allow-Origin' '<插件ID>' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Api-Key' always; add_header 'Access-Control-Max-Age' 1728000 always; add_header 'Content-Type' 'text/plain; charset=utf-8'; add_header 'Content-Length' 0; return 204; } proxy_pass http://127.0.0.1:1234; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` 我本地是用的 HTTPs，所以 nginx 还会涉及到证书配置，也许删掉 ssl 相关配置，直接调 http 也行，没测试过。但如果会报错的话，可以使用 mkcert 来生成本地受信任的证书。 ```bash brew install mkcert mkcert -install mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1 192.168.100.56 -install ``` 这之后还要修改下 nginx 配置里的 `<插件ID>`。把它替换成沉浸式翻译插件的 ID，可以通过打开浏览器调试工具，然后发送一个测试请求， 在 Network 选项卡里查看请求的 Request Headers 里的 `Origin` 字段来获取。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20251222195534087.png) ```js fetch("https://127.0.0.1:1235/v1/chat/completions", { "headers": { "api-key": "1234567890", "authorization": "Bearer 1234567890", "content-type": "application/json" }, "referrer": "", "body": "{\n \"model\": \"qwen/qwen3-next-80b\",\n \"temperature\": 0,\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"你是一个专业的简体中文母语译者，需将文本流畅地翻译为简体中文。\\n\\n## 翻译规则\\n1. 仅输出译文内容，禁止解释或添加任何额外内容（如\\\"以下是翻译：\\\"、\\\"译文如下：\\\"等）\\n2. 返回的译文必须和原文保持完全相同的段落数量和格式\\n3. 如果文本包含HTML标签，请在翻译后考虑标签应放在译文的哪个位置，同时保持译文的流畅性\\n4. 对于无需翻译的内容（如专有名词、代码等），请保留原文\\n\\n## Context Awareness\\nDocument Metadata:\\nTitle: 《Options》\\n\\n\"\n },\n {\n \"role\": \"user\",\n \"content\": \"翻译为简体中文（仅输出译文内容）：\\n\\nHello world\"\n }\n ]\n}", "method": "POST", "mode": "cors", "credentials": "include" }) ``` 如果你的 LM Studio 开启了局域网访问，为了安全起见，你也可以设置 APIKEY 然后在 nginx 校验一下，反正看个人需求吧，这不非必选。 最后启动 nginx，然后测试下服务没问题就可以了。 这种方法的性能要比自己写服务器转发好很多，而且配置也更简单。 此外，LM Studio 推出了官方 API。使用官方 API 可以在工程化方面做得健全一些，见：[lmstudio-js](https://lmstudio.ai/docs/typescript){rel=""nofollow""} ## 前言 平常经常逛技术类的英文独立博客比较多，但是英文很菜，只能看懂一些简单的文章，所以常依赖[沉浸式翻译](https://immersivetranslate.com/){rel=""nofollow""}浏览器插件去阅读一些更难或更书面化的英文网站。 相比常见的划词翻译，沉浸式翻译可以几乎不受限制地调用 DeepL、OpenAI 等第三方 API，翻译大段句子；他还提供了翻译整个页面、自定义快捷键等额外的功能。使用了四个月的沉浸式翻译带来最直观的感受是：用 AI 翻译（LLM） 得到的译文质量真是特喵的好！只是，苦于这个插件高昂的价格（69 软妹币每月的价格实在太贵，再加点钱我都能整个 OpenAI 的 Pro 会员了），本着能本地白嫖就不线上付费的原则，我本地部署了一个 LLM 专门用来翻译网页或文档。 直接说结论。相比 Google 或百度等机翻，AI 翻译在语句通顺程度、语气、名词保留等方面好得多。尽管测试下来（主观来看），开源 LLM 模型的翻译质量还差 GPT3.5 一截，而且也容易出稀奇古怪的问题，但实话说~~（习惯就好） ~~已经够用了。 ## 大体思路 机器是 MacBook Pro M3 Max，因为 Mac 的内存和显存能公用，所以本地部署模型时一般不用担心爆显存。以下本地部署的方法不一定适合 Windows 的笔记本，仅供参考。外接或魔改卡富哥请忽略我。另接触这些内容不久， 所以如果有错误还请佬们评论区指出。 ### 模型管理工具 首先要选择一个合适的本地模型管理工具。工具最好要带服务器功能，这样能省去很多代码方面的麻烦。此外，使用工具管理模型非常方便，有飞机的情况下，一般都是一键下载什么的。题外话，由于模型文件都比较大，所以需要注意流量， 刚玩的这两周我花了 200GB 流量，都用在下载各种稀奇古怪的模型上了。 相比上手最简单的 [Ollama](https://ollama.com/){rel=""nofollow""}，我推荐有 GUI 界面的 [LMStudio](https://lmstudio.ai/){rel=""nofollow""}。LMStudio 除了聊天、服务器功能，还支持多个模型比对等更好玩的东西，还能在界面上快速设置如 GPU 加速、提示词格式、停止词、上下文长度等参数。对新手来说比较友好。 安装好 LMStudio 后，首要任务是下载模型。 如果不想浪费时间自己搜索以及测试模型，直接按照下图下载评分不错且有中文支持的 Qwen 模型就好。模型名称中的 Q2、Q6\_k 等后缀是指模型的压缩策略，同种模型的 Q8 量化比 Q2 量化效果好，但是推理计算量更大，体积更大（ 显存占用更大）。LMStudio 显示了模型的体积，所以选 Qwen/Qwen\_1.5\_14B\_Q6 还是 Qwen/Qwen\_1.5\_14B\_Q2 就按照机器决定吧。举个例子，如果你的 Mac 内存是 32GB， 那选个 16GB 大小的 Qwen\_1.5\_14B\_Q8\_0 就可以。 ![Qwen\_1.5\_14B](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403280109446.png) 随后，打开 LMStudio 的 Server 页面（①）。启动服务器前前需要选择一个模型（②）。选好后等它加载一段时间，再点击下面那个 “Start Server” 就能成功启动。 ![LMStudio 选择模型和启动服务器](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403252136846.png) 一旦 LMStudio 的服务器成功启动，可以复制测试代码（④）到终端运行，看看模型是否能正常工作。界面上能看到对应模型占用的显存资源以及运行任务时 CPU 占用情况（③），可视机器负载情况更换模型（ 也可以在右侧配置中降低 n\_ctx 上下文长度）。 ![模型占用显存情况及测试代码](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403252141022.png) M3 的机器只要内存够可以拉满右侧面板的 GPU Layers，速度会快不少。题外话，如果你想知道 M3 和 4090 比速度的话... 算了，还是别比了，已经花了不少钱买了库克的黄金内存，没必要在 GPU 的性能比较上再捅自己一刀。 ![GPU Layers](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403252146203.png) ### 本地服务器转发 沉浸式翻译的 API 格式和 LMStudio 的 API 格式不能无缝对接，所以启动完 LMStudio Server 后，我们需要写一个本地服务器用来中转翻译插件的请求。题外话，也许有现成的工具，有知道的佬请踢我一脚。 下图有一个简单的本地服务器示例，使用了 Koa 框架，按照沉浸式翻译文档提供的 API 格式获取数据，然后用 fetch 打给 LMStudio，拿到译文后，组装好结果后返回。完整示例代码我上传到了 Github [simple-local-llm-server@Lionad-Morotar](https://github.com/Lionad-Morotar/simple-local-llm-server/tree/main/packages){rel=""nofollow""}，有需要自取。 ![本地服务器代码](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403252203402.png) 其中 utils.getResponse 便是向 LMStudio 发起请求。选择完 Qwen 模型后，LMStudio 的 API 会要求提供 system 以及 user 两种角色的入参，用于设置模型推理的上下文， 所以需要手动设置一下提示词。以下是 getResponse 实现的示例。 ```js const data = { messages: [ { role: "system", content: `You are a highly skilled translator with expertise in many languages. Your task is to translate any provided text and translate it into ${targetLang} while preserving the meaning, tone, and nuance of the original text. Please maintain proper grammar, spelling, and punctuation in the translated version. Only include the translated text and do not include any additional information, explanations, or unrelated content. For example, user input "Ask HN: Can we do better than Git for version control?", you return, 来自 Hacker News 的问题: 在版本控制方面，我们能做得比 Git 更好吗？`, }, { role: "user", content: "translate into Chinese: " + opts.user, }, ], temperature: 0.5, max_tokens: -1, stream: false, }; const response = await fetch("http://localhost:1234/v1/chat/completions", { headers: { Accept: "application/json", "Content-Type": "application/json", }, method: "POST", body: JSON.stringify(data), }).then((res) => { return res.json(); }); ``` 测试本地服务器的时候我碰到了有几个小问题，各位也可以留意一下： 一个是停止词的问题。尽管 LMStudio 默认的停止词包含了换行，但 Qwen 1.5 13B 经常一连输入几百个换行符，占用推理时间。一开始没有找到解决办法，只好把 max\_tokens 设置为和输入文本长度一样（ 中文译文几乎都比英文短），这样一来最多也就多输出几个换行符，之后在代码里手动 trim 一下就能得到正确结果。后来换了模型就没碰到过这个问题了。 二是关于请求安全。如果只想让沉浸式翻译浏览器插件调用这个 API，需要手动校验一下 Referer，只要来源是 chrome-extension\:xxx 就可以。具体的 extensionId 可以在浏览器插件的管理页面看到。 ### 插件设置 最后是沉浸式翻译插件的设置，首先要在开发者设置里打开 Beta 功能。 ![Beta 功能](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403252311878.png) 之后，选择“基本设置”，选择自定义接口（⑤），测试一下是否能正常调用（⑥）。 ![设置自定义接口](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403252313270.png) ## 其他可能有用的信息 有关模型选择的问题。我本地测试了 Qwen 1.5 7B、14B、70B 几种模型，尽管感觉上 70B Q3 的翻译质量好得多，但在 M3 芯片上生成速度太慢，每秒只能输出 17 tokens 约 8 个中文字。 ~~换 13B 速度够用，但是非常容易出现停止词问题。最后日常翻译我还是选择 7B，速度飞快，还不发热。就是同样的提示词，7B 的返回要加不少戏。~~成文之际又换回了 13B。 说到提示词。如果你用的不是 Qwen 而是 LLama2 或者不是从高质量中文语料中训练来的模型，那对应的提示词肯定要换。可以参考：[Polyglot superpowers](https://docs.anthropic.com/claude/page/polyglot-superpowers){rel=""nofollow""}。 有关请求速度的设置。由于沉浸式翻译本身自带请求结果缓存，所以无需担心同一个页面的翻译或是重复句子的翻译会多次调用。但本地模型毕竟比不上第三方 API 的速度，如果不想写更多代码（如在本地服务器转发时做更复杂的并发控制）， 可以单纯地在自定义选项中（⑦）降低沉浸式翻译的每秒请求次数（⑧）。见下图，我的设置是每两秒请求一次（即翻译一个句子）。~~沉浸式翻译能自动断句，所以不用担心单个句子太长。~~成文之际已经把断句关掉了，主观而言， 关断句后翻译速度和准确率要更好。 ![自定义设置](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403252327002.png) 整个链路可替代的选项。本文使用的工具是 LMStudio 本地部署、Qwen1.5、LMStudio Server、NodeJS Proxy、沉浸式翻译插件。在 BiliBili 评论区也见过其他方案，比如有用 Ollama 部署的， 用 mT5 的模型翻译的，用全局翻译插件 Bob 替代沉浸式翻译的。总得来说没有见过满分的技术栈。可玩性还很高，如果有时间投入的话。 最后展示一下翻译效果，分别是 Qwen 1.5 7B q5、14B q6 和 70B q3 的翻译效果。使用的是同一个网页：[Can we do better than Git for version control?](https://news.ycombinator.com/item?id=38590080){rel=""nofollow""} ![Qwen 1.5 7B q5](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403260041970.png) ![Qwen 1.5 13B q6](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403270940123.png) ![Qwen 1.5 70B q3](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403260024163.png) 我在 BiliBili 看到别人说 Q4 程度量化对精度的影响较小，但如果小于 Q4，精度会下降很多。不过从对照组来看，14B q6 的翻译质量确实完胜 14B q2。 ![Qwen 1.5 13B q6](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403270940123.png)![Qwen 1.5 13B q2](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202403260038947.png) # 🧊 模板解析器轻考古 上回我借着解决 CSS 嵌套解析问题聊到 micro-app 中实现的一个非常精简的 [CSS 解析器](https://lionad.art/articles/mini-css-parser)，还没过瘾。今天整理笔记的时候发现了角落里的这个模板解析器， 那就赶紧擦擦灰尘拉出来聊一聊。这个模板解析器可是有年头了，它是 John Resig 佬 2008 年写的，叫 `micro-templating`，距今十五年哩。（John Resig 就是写《JavaScript 忍者秘籍》那位） 令人惊叹的地方是，`micro-templating` 的代码和它的名字一样 micro，它能用仅仅 30 行代码完成对模板的处理，并且还有读取 html 模板、缓存、柯里化等额外的高级功能！ 可能有些佬没接触过模板解析器，这里给出一个简单的示例。 ```js parse(` <% if (shouldCount) { %> <% for (var i = 1; i <= 3; i++) { %>
hello - <%= i + count %>
<% } %> <% } else { %>
noop
<% } %> `, { shouldCount: true, count: 1 }) ``` 给 `parse` 函数传入模板字符串和数据后，自然也是输出字符串啦： ```html
hello - 2
hello - 3
hello - 4
``` 相比生态里现在动则 30kb 甚至 300kb 的库，仅 30 行代码完成这个功能，简直不可思议。 ## 完整实现 因为代码真的非常短，先直接看一遍，这是带注释版本的。如果你能在第一遍 review 这段代码后脑袋还保持清醒的话，留下评论，我拜你为大哥。 ```js // Simple JavaScript Templating // John Resig - https://johnresig.com/ - MIT Licensed (function () { var cache = {}; this.tmpl = function tmpl(str, data) { // Figure out if we're getting a template, or if we need to // load the template - and be sure to cache the result. var fn = !/\W/.test(str) ? (cache[str] = cache[str] || tmpl(document.getElementById(str).innerHTML)) : // Generate a reusable function that will serve as a template // generator (and which will be cached). new Function( "obj", "var p=[],print=function(){p.push.apply(p,arguments);};" + // Introduce the data as local variables using with(){} "with(obj){p.push('" + // Convert the template into pure JavaScript str .replace(/[\r\t\n]/g, " ") .split("<%") .join("\t") .replace(/((^|%>)[^\t]*)'/g, "$1\r") .replace(/\t=(.*?)%>/g, "',$1,'") .split("\t") .join("');") .split("%>") .join("p.push('") .split("\r") .join("\\'") + "');}return p.join('');" ); // Provide some basic currying to the user return data ? fn(data) : fn; }; })(); ``` 代码看完了，我知道你没看懂，因为曾经我也是。好了，留下三连，解析开始。 ## 解析 首先，代码最外层是一个 IIFE，给 this 对象挂载了 tmpl 函数，直接执行的话就是 window。内部通过局部变量保存了模板解析的缓存： ```js (function () { var cache = {}; this.tmpl = function tmpl(str, data) {}; })(); ``` str 参数有两种两种用途，`/\W/.test(str)` 用来判断字符串中包不包含模板分隔符，如果不含分隔符，即普通字符串，那就当作 ID，从页面对应 ID 的节点中获取内容作为模板。比如，如果 str 为 'user\_tmpl'， 那么模板函数将会读取页面的以下脚本的内容作为输入： ```html ``` ```js (function () { var cache = {}; this.tmpl = function tmpl(str, data) { return !/\W/.test(str) ? // 缓存会将读取脚本内容到模板解析这个过程的解析结果缓存下来 (cache[str] = cache[str] || // 读取脚本内容 tmpl(document.getElementById(str).innerHTML)) : new Function(); }; })(); ``` `new Function()` 即模板解析的核心内容，原理是用一个数组，保存所有解析内容，再拼接回字符串，作为 JS 执行。类似 eval 函数。 ```js new Function( "obj", "var p=[];" + // + '...' "return p.join('')" ); ``` 要解析什么内容呢？无非是 `<%=hello%>` 这种模板字符串。执行过程中，通过 with 语句，将内部变量的求值（hello）转移到参数对象（data.hello）。这个玩意儿在 VueJS 的模板编译中也用到过： ```js /* VueJS */ with (vm) { return createVNode("p", { attrs: { hi: hello /* vm.hello */ } }, [ createTextNode("Hello World"), ]); } ``` 那如何解析呢？ ~~我们知道~~曾写过经典字符串模板的佬应该知道，**模板字符串一般包含：字符串、变量及逻辑**。 - 字符串 `Lionad` - 带变量 `<%=name%>` - 带逻辑 `<% if(name){ %><%=name%><% } %>`。 所以解析模板，无非就是把这三种字符串替换成纯粹的 JS 逻辑，作为 new Function 的参数。其中所有中间变量，可以用一个数组来储存： - 将普通字符串直接推入作为结果的内容数组，比如 `Lionad` 应该被解析为 `p.push('Lionad')`。 - 如果碰到变量，则将变量拆分出来推入数组，如 `<%=name%>` 应该被解析为 `p.push('');p.push(name);p.push('')`。 - 带逻辑的字符串，由于逻辑本身就是 JS 代码，所以不需要解析为字符串，只需要把两侧的 `<% %>` 这种模板标志去掉就好了。 如 `<% if(name){ %><%=name%><% } %>` 应该被解析为：`if(name){ p.push('');p.push(name);p.push('') } `。 以下面这段模板为例，我们看看字符串具体的替换规则。 ```js str = `<% if (true) { %>
  • <%=users[i]%>
    • <% } %>`; ``` ```js // with 的使用方法都知道了，with(obj = { a })，那么 // 就能在内部直接读取 a，不需要写 obj.a "with(obj){p.push('" + str // 将换行等空白字符转换为空格，这样所有代码都在一行了 // '<% if (true) { %>
  • <%=users[i]%>
    • <% } %>' .replace(/[\r\t\n]/g, " ") // ['', 'if (true) { %>
  • ', '=users[i]%>
    • ', ' } %>'] .split("<%") // 因为 \t 刚才已经被替换成空格了，所以这里可以使用 \t 用来将不同行的代码字符串“相加”， // 一会儿再拆分时，不会和原先字符串里的字符混淆 .join("\t") // 去掉模板标志两端的引号，在这个例子里不会用到 .replace(/((^|%>)[^\t]*)'/g, "$1\r") // 以下三句最重要，将所有变量推入数组，生成结果形如 `push('xxx',x,'xxx')` 的字符串 // 首先，刚才匹配完了 <%，所以 \t= 开头后边接的就是变量，这里让它转换成 ',x,' 的形式 .replace(/\t=(.*?)%>/g, "',$1,'") .split("\t") // 在刚刚跟 split('<%') 的位置用括号还原，得到了 ',x,'xxx'); 的形式 .join("');") // 在 \t=xxx 那次匹配，已经把变量模板对应的结束标志 %> 匹配完了， // 所以这是处理剩余语句的结束标志，用 split 拆分行后相当于直接把结束标记舍弃了 .split("%>") // 最终在每行开头增加 push 方法，形成了 push('xxx',x,'xxx'); 的形式 .join("p.push('") // 处理剩余的换行符 .split("\r") .join("\\'") + "');}"; ``` 有一个小细节，字符串替换时，所有逻辑语句的模板标志开头和结尾（`<%`、`%>`）分别被替换为 `');`、`push('`，但是开头和结尾的那个标志，并没有对应的匹配。所以在代码中， 能看 `with(obj){p.push('` 和 `');` 这种手动补全。 最终生成的字符串如下（已格式化处理）： ```js `with(obj){ p.push(''); if (true) { p.push('
  • ',users[i],'
    • '); } p.push(''); }`; ``` 为什么 with 语句里有一行空的 `push('')` 呢？ 还记得原始的模板吗？一开的模板是以“<%”开头的，而“<%”在替换过程被右括号取代了，此时正好和初始字符串结合形成了空 push。如果原始字符串开头是 "123<% if (true)"，那这行空 push 会转换成“ p.push('123');”，也是正确的代码。 最后，micro-templating 需要返回这个新函数。如果不传参数 data 给模板函数，则会返回一个部分应用的函数等待用户输入 data 参数再执行模板解析；如果已经传了 data 那就会立即调用返回模板解析的结果。 ```js (function () { var cache = {}; this.tmpl = function tmpl(str, data) { return data ? fn(data) : fn; }; })(); ``` 终于结束了！这个函数不长，但一口气看下来还是蛮费力气的。如果一遍写测试用例以便看代码，很快能把这个函数跑通，如果你是纯靠脑力跑，还没被那个长长的字符串替换链给吓住，在此我赐你称号：“ Micro Templating 人肉编译器 - 十五周年限定版”。 额外提一句，Function 构造器和 eval 函数比，除了能传参数意外，还有一些细节不同，比如说声明变量的作用域不同，这个需要注意。这个编译器没有错误处理等代码完善，因此不可以上生产。此外，由于 [with](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Statements/with){rel=""nofollow""} 语句非常容易出错，且不利于静态优化，不应该在业务函数里使用 [^with-mdn] 。最后，阅读源码需要技巧，这几点希望能帮助到你： - 从注释、测试用例，先搞清楚要看的代码的作用 - 使用编辑器的折叠代码，一次只看一部分源码 - 在 Git 提交记录中搜索，从简单的版本看起 - 复杂代码应该从高层结构看起，比如使用 IDE 各种插件或是 Madge 等代码分析工具 ## 相关链接 - [JavaScript Micro-Templating](https://johnresig.com/blog/javascript-micro-templating/){rel=""nofollow""} # Ⓜ️ Mini CSS Parser ## 前言 Vue 源码中包含 HTML Parser，随着大家在框架方向的深入学习（卷），不免要开始接触一些编译解析相关的东西。社区很多看 Vue 源码时总结的 HTML Parser 的文章，但是很少有介绍 CSS Parser 的文章。 今天借着在开发时碰到的一个问题，给大家简单介绍一下 CSS Parser 的基本流程。 我的项目使用 micro-app 框架作为微前端框架。使用 micro-app 时，由于开启了样式隔离功能，子应用加载的 CSS 会被解析器解析，在选择器前增加一个子应用属性选择器前缀。代码示例见下。我碰到的问题是，如果 CSS 源码中带[嵌套语法](https://caniuse.com/?search=css%20nesting){rel=""nofollow""}，那么解析就会失败。 ```css /* css 源代码 */ .a { z-index: 1; .b { z-index: 2; } } /* 期待转化得到的代码 */ micro-app[name="test-app"] .a { z-index: 1; .b { z-index: 2; } } /* 实际得到的代码 */ micro-app[name="test-app"] .a { z-index: 1; .b { z-index: 2; } /* -> 到这里就停了 */ ``` ## CSS 的组成部分 要理解 CSS 是怎么解析的，就要先清楚 CSS 是由哪几部分组成的。由我们平常见得最多的普通 CSS 代码开始说起，见下图，基本的 CSS 代码的组成部分包含规则集（rules）、选择器（selector）、选择器（declares）、 属性（property）、值（value）这五个部分。 规则是由属性和值组成的\ 声明、声明与括号形成的声明块再加上选择器组成， > 而一条或多条规则组合成了规则集[1](https://lionad.art/#user-content-fn-css-syntax){#user-content-fnref-css-syntax ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ![规则&规则集](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200621/20200625022018.png) 图中没有包含 `at-rule` 的部分，哦，还少了注释部分\~ 由于注释是 CSS 中语法最简单的部分，我们从解析注释开始代码部分的解读吧。 ## 流程速览 #### 解析注释 可能许多人不了解 CSS 的注释风格，这里先说明一下，原生 CSS 仅支持[斜杠星号风格注释](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Comments){rel=""nofollow""}，不支持[双斜杠注释](https://segmentfault.com/a/1190000043885414){rel=""nofollow""}，所以解析器并未处理双斜杠的情况。 解析注释的函数是一个 while 循环，从代码开头开始匹配，每次循环解析一条注释，直到代码开头没有注释为止。 ```ts class CSSParser { private matchComments() { while (this.matchComment()); } private matchComment() { // 快速跳过非注释部分代码 if (this.cssText.charAt(0) !== "/" || this.cssText.charAt(1) !== "*") { return false; } // ... return true; } } ``` 在选择解析注释内容的方法上，micro-app 没有使用正则，而是用了下标递增的办法。暂不清楚原因，感兴趣的小伙伴可以试试几种相关办法的性能对比。 ```ts let i = 2; while ( this.cssText.charAt(i) !== "" && (this.cssText.charAt(i) !== "*" || this.cssText.charAt(i + 1) !== "/") ) { ++i; } i += 2; let commentText = this.cssText.slice(2, i - 2); /* ... */ this.cssText = this.cssText.slice(i); ``` 注释的正文结果保存在了变量 `commentText` 中，这样可以判断 `commentText` 的内容来实现通过注释禁用某个选择器、禁用某行的样式隔离之类的功能。比如想让 `.test2` 选择器不被 scoped 规则覆盖， 我们可以在业务代码中这样写。 ```css /*! scopecss-disable-next-line */ .test2 { background: url(/test.png); } ``` #### 输入输出 “解析注释”中“解析”实际指对输入的 CSS 源文件待处理部分以及处理好的输出部分做出改变。这里引申出解析器里两个关键状态，`cssText` 和 `result`，分别代表待解析的内容和最终输出结果。 `cssText` 随着循环应当逐渐减小直到为空，此时代表解析完成。`result` 能被内部方法 `recordResult` 改变，比如如果要把注释的正文内容记录到输出结果，可以这样使用： ```ts this.recordResult(`/*${commentText}*/`); // 相当于：this.result += `/*${commentText}*/` ``` #### 解析规则集 规则集的解析是整个解析的核心过程。原理与解析注释类似，也是一个 while 循环。每一轮循环都会尝试匹配一条规则，并且将多余的注释和空白字符匹配出来。 ```ts private matchRules (): void { this.matchLeadingSpaces() this.matchComments() while ( this.cssText.length && this.cssText.charAt(0) !== '}' && (this.matchAtRule() || this.matchStyleRule()) ) { this.matchComments() this.matchLeadingSpaces() } } ``` 匹配注释我们知道它是使用了下标递增 + Slice 的方法，匹配空白这里则是用的一个非常简单的正则。见下 `matchLeadingSpaces` 函数。 ```ts private matchLeadingSpaces (): void { this.commonMatch(/^\s*/, false) } ``` 可以想象，`commonMatch` 应当会对状态 `cssText` 和 `result` 做一些操作。实际上，commonMatch 两个参数分别是用于匹配 `cssText` 的正则，及跳过标记。如果在待匹配内容中匹配到了字符串， 便把匹配的内容从中移除；跳过标记则意味着当确认跳过时，匹配的内容将不会被记录到输出结果中。以上面的 `matchLeadingSpaces` 函数举例，如果在待匹配内容中匹配到空白字符，那么会将其丢弃不做处理。 `commonMatch` 可谓是解析器匹配逻辑的核心，只要理解了它，那么我们回到上面提到的样式规则匹配 `matchStyleRule`，会发现其过程非常简单。简单来说只有三步，匹配选择器、记录解析后的选择器、解析（并记录）声明。 结束条件只有成功解析以及选择器解析报错或声明解析报错。 ```ts private matchStyleRule (): boolean | void { const selectors = this.formatSelector(true) this.scopecssDisableNextLine = false if (!selectors) return parseError('selector missing', this.linkPath) this.recordResult(selectors) this.matchComments() this.styleDeclarations() this.matchLeadingSpaces() return true } ``` 首先是匹配选择器的部分。以 `.a,.b{color:red}` 为例，首先匹配出`{`字符前的部分即`.a,.b`作为选择器的正文，然后使用`,`分割选择器，并给选择器加上 prefix， 最终返回`micro-app[name="subapp"] .a, micro-app[name="subapp"] .b`。刚才提到可以在业务代码中使用注释给特定选择器禁用 prefix 前缀，相关的代码的实现也在这个函数中。 ```ts const selectors = this.formatSelector() private formatSelector (skip: boolean): false | string { // 匹配选择器正文 const m = this.commonMatch(/^[^{]+/, skip) return m[0].replace(/(^|,[\n\s]*)([^,]+)/g, (_, separator, selector) => { // 如果检测到选择器被禁用则跳过添加前缀步骤 if (...) { const prefix = this.prefix // micro-app[name="subapp"] selector = prefix + ' ' + selector } return separator + selector }) } ``` 匹配完选择器后，声明便是剩下的包含在左右花括号的内容。匹配过程是一个递归，以遇到`}`作为结束条件。如果遇到斜杠`/`，则尝试停止声明匹配并开始注释匹配。总之，`}`之前的内容都作为当前选择器的声明，添加到`cssText`中。micro-app 框架会对 CSS 资源中的 URL 补全为主应用的完整路径这个功能也是在这个函数中实现，有兴趣的话可以查看其[完整代码](https://github.com/jd-opensource/micro-app/blob/dev/src/sandbox/scoped_css.ts){rel=""nofollow""}。 ```ts private matchAllDeclarations (): void { let cssValue = (this.commonMatch(/^[^}/])*/, true) as RegExpExecArray)[0] this.recordResult(cssValue) // 递归退出条件 if (!this.cssText) return if (this.cssText.charAt(0) === '}') return // extract comments in declarations if (this.cssText.charAt(0) === '/' && this.cssText.charAt(1) === '*') { this.matchComments() } else { // 如果不是注释则忽略中断，继续匹配声明 this.commonMatch(/\/+/) } return this.matchAllDeclarations() } ``` #### 解析`at-rule` 流程中最繁琐的部分，是匹配 `@media`、`@import`、`@charset` 等 [`at-rules`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/At-rule){rel=""nofollow""}。 每一种规则的语法都不同，要怎么处理才合适呢？ 这里，micro-app 把 `at-rule` 分为了三组： 1. 类似 `@charset "utf-8";` 为一组，包括 `@import`、`@charset`、`@namespace` 等。 2. 类似 `@media (w < 100px) { .selector { xxx: xxx } }` 为一组，包括 `@supports`、`@font-face`、`@document` 等。 3. 类似 `@font-face { unicode-range: 'xxx' }` 为一组，包括 `@font-face`、`@page`、`@key-frames` 等。 第一组，`@charset` 所在的第一组规则的规则正文内容从 `@` 开始到 `;` 结束，比如 `@charset "utf-8";` 就是一条完整的声明； 第二组，`@media () {}` 的花括号部分可能包含选择器，所以其正文内容需要重新进入 `matchRules` 匹配选择器以及声明。 第三组，`@font-face {}` 的花括号部分仅包含声明，不包含选择器，所以只需要进入 `matchAllDeclarations` 匹配声明即可。 ## 解决问题 回到文章开头的问题，如果要给这个 CSS Parser 增加原生的嵌套功能，见下代码，可以仅用十行简单实现。 ```diff + private matchAllDeclarations (nesting = 0): void { let cssValue = (this.commonMatch(/^[^}/])*/, true) as RegExpExecArray)[0] this.recordResult(cssValue) // 递归退出条件 if (!this.cssText) return - if (this.cssText.charAt(0) === '}') return + if (this.cssText.charAt(0) === '}') { + if (!nesting) return + this.commonMatch(/}+\s*/) + return this.matchAllDeclarations(nesting - 1) + } // extract comments in declarations if (this.cssText.charAt(0) === '/' && this.cssText.charAt(1) === '*') { this.matchComments() } else { // 如果不是注释则忽略中断，继续匹配声明 this.commonMatch(/\/+/) } + if (this.cssText.charAt(0) === '{') { + this.commonMatch(/{+\s*/) + nesting++ + } - return this.matchAllDeclarations() + return this.matchAllDeclarations(nesting) } ``` 最终 CSS Nesting 解析成功。 ![result](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230804025910.png) ## 结语 整个 CSS Parser 的代码简单，功能强悍，耐人寻味。不过有许多边界条件没有处理好，尤其是引入了使用注释禁用样式隔离功能后，匹配注释变得更复杂且易错了。 1. 注释不能和选择器等混用（以下 result 文件代表解析结果）。 ![comment in selectors](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/9d2b75bda238f9bbe24825a793f0f715.png) 2. CSS 字符串值可能意外启用编译器的特殊功能。 ![special comment in string value](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230803225103.png) 3. 错误的 `@host` 规则匹配。猜测是想匹配 [`:host`](https://drafts.csswg.org/css-scoping/#host-selector){rel=""nofollow""} 但是手滑写成了 `@host`。 ```ts private hostRule = this.createMatcherForRuleWithChildRule( /^@host\s*/, '@host' ) ``` ![error @host rule](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230803235802.png) 在实际项目中，考虑到性能和可维护性的平衡，为了使代码不变得过于复杂，没有必要去完善“边界功能”。运行时的解析应当尽量简单且运行快速，并保持一定的容错：不规范的 CSS 代码在浏览器中本身就能运行，再者，解析器是一个容易带来代码性能和体积瓶颈的地方，要不然 VueJS 也不会分全局构建和运行时[两个版本的编译产物](https://www.jsdelivr.com/package/npm/vue?tab=files&path=dist){rel=""nofollow""}。 鉴于 CSS 在部分语法上的灵活性，如果从降低维护难度的角度考虑优化这个 CSS Parser，可能从以下方向： - 在规则匹配部分使用黑名单机制而不是白名单匹配。就 `at-rule` 等灵活语法而言，如果浏览器支持新的 `@xxx` 语法，黑名单机制编写的代码不需要对 `@xxx` 做额外处理；而白名单机制需要[手动处理](https://github.com/jd-opensource/micro-app/commit/b83c4600102e0db6f591bacbdc592bea8f1d5bb8){rel=""nofollow""}。 - 在复杂的解析器部分使用外部依赖，如使用类似 [`lightingcss-wasm`](https://www.npmjs.com/package/lightningcss-wasm/v/1.16.0){rel=""nofollow""} 等方案。 关于样式隔离，作者两年前专门写了文章介绍，不过时效性稍有不足，没有涉及解析器的具体流程，写得更多是解析器在整个微前端框架中的作用，也可作为补充阅读。 - [从零开始写一个微前端框架-样式隔离篇](https://github.com/jd-opensource/micro-app/issues/20){rel=""nofollow""} 最后，微前端框架中的 CSS 的有很多中实施办法，采用一些办法可以抛弃运行时解析。em... 也许以后有机会聊一聊（咕一咕）。 ## 增订 | 2024 年 1 月 28 日 相关实现和测试用例见[这个 Issue](https://github.com/jd-opensource/micro-app/issues/868?_issue=nesting){rel=""nofollow""} ## Footnotes 1. 比较完整的 CSS 语法参见：{rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-css-syntax){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} # 🚩 向AI咨询前端问题 ## 增订 | 2026-01-05 无论是模型性能，还是应用层基础，这几年 AI 工具越来越强。其工程化落地速度非线性增长，逐渐在各应用领域大放异彩。 本文原有的提倡通过 LLM 发散思维能力来学习具体知识的观点可以进一步进化。目前没有成文，但 2025 FEDAY 中天翔的演讲“AI 编程认知税”中提到的认知税概念我觉得很有意思，适合扩展： 他将任务难度（不仅仅是学习任务）从不同的上下文约束程度划分为 0-10 等级，分别是，0-3分：纯发散区；3-8分：探索地狱；8-10分：有限游戏。具体见：[AI 编程的"认知税" - 天翔 @youtube](https://www.youtube.com/watch?v=y6_KaNfkZ8c){rel=""nofollow""}。 举个例子，“给我的按钮做10种动效（然后我选一种）”是0-3分任务，其中"认知税"，即验证、修正AI输出所需要的时间消耗较低。 在我的理解里，根据“认知税”的不同，如何使用 AI 辅助自身或团队研发成为了目前的“AI时代软件工程”：年末能看到各一线前端团队都有自己的方法论，比如饿了么有分享：[团队 AI 编码率稳步提升到 89.2% 的 AI Coding 实践分享](https://mp.weixin.qq.com/s/dq87Orqr8SyeyECZg3BMfA){rel=""nofollow""}。今年许多前端会议，SEE Conf 和 FEDAY 有很大比例的 AI 相关标签广义软件工程主题。 所以，如何根据模型及其应用层工具的性能，来调整学习方法，是需要再次思考的。 ## 原文 如何使用 GPT 辅助前端学习？我认为最重要的两步是，首先使用 GPT 咨询普遍性的、具体的问题获得关键字，然后翻阅相关文档进行具体地学习。因为在文中纯知识面的问题上，我感觉受到了 GPT 的碾压。 ### 应当咨询普遍性及具体的问题 前端学习很难。首先是面对排山倒海的文字资料，如果没有掌握合适的方法，比如保持阅读文档和更新日志的习惯，很难在知识面上跟上具体框架的发展。另一方面，在细微的问题上有无数种解决方法（比如渐变边框的一百种画法）， 很少有方便学习的高质量的图书或稳定的聚合推荐。我觉得前端的难，以繁杂、琐碎的知识点带来的记忆难度为首，尤其当开发者入门后想建立起知识广度的积累时。 ChatGPT 是一个好工具，很适合用作前端学习。但在工作中，我常看到同事错误的使用它。在一次帮忙排查 WebStorm 中 ESLint 插件失效时，同事反复将控制台报错信息粘贴进 GPT 中，期望获得有用的提示。 但这次的报错并不是常见问题，所以直到最后，GPT 没有切中地给出解决问题的方法。它回复了万金油答案，就像是“问：升级 xxx 能带来什么？答：提高兼容性和性能”那样。 我并不是说要通过系统地学习提示工程来引导 GPT 输出我们需要的回答，而是 GPT 工具本身在某些场景并不适合。目前许多 GPT 工具没有提供互联网连接，且知识库截至 2021 年。撇开提示技巧， 我觉得应该在常见且具体的问题上咨询 GPT 的建议，最重要的两步是，首先使用 GPT 咨询普遍性的、具体的问题获得关键字，然后翻阅相关文档进行具体地学习。因为在以下两个问题，我感觉自己在纯知识面上受到了 GPT 的碾压。 ### 如何防止 Element Plus 组件中的 Popper 溢出容器？ 第一个例子是关于防止 Popper 溢出容器的设置。 ![el-tooltip example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230702125800.png) B 端产品常将复杂性隐藏在 Dialog 或 Popup 中。我们公司的组件库基于 Element Plus，所以经常需要对弹窗的内容进行定制。这里有一个问题，Popper 的位置不好控制。当交互场景变得更复杂， 比如当滚动弹窗内容要求 popper 不溢出弹窗容器时，你会发现问题开始变得难以解决。其一因为 Element Plus 的文档没有关于如何控制 popper 位置作更多说明，如果在 Element Plus 的文档中搜索“位置”， 你只能找到 Popper 的 placement 和 offset 两种属性，而且都不是我们想要的答案；其二更重要，就算你在互联网搜索相关关键字，也很难从中汲取有效信息。你可以尝试搜索“element-plus+popper（或相关组件） +溢出弹窗 -'element-ui'”之类的关键词验证我的说法，这个问题过于垂直，所以网上没有具体的解决方法，或能搜出来的是关于 element-ui 的过时的资料。 答案隐藏在 popper.js 的文档中，所以解决这个问题可能有以下几条通路： 1. 在 element-plus tooltip（或相关组件）文档漫游，通过不起眼的 popper.js 文档链接进入并搜寻，有概率能找到解决相关问题的 API 2. 在搜索引擎找到了其它用户在解决 位置控制方面的经验，于是自发搜索 文档，并在文档中找到关键 API。 3. 在 github element-plus issues 中搜索 “popper+dialog”，能找到其它开发提供的提示，直接将你引向 中解决相关问题的关键 API。 只能说 HTML 不够 Hyper，所以搜索引擎在这种没有直接资料的场景中无能为力。不过，好消息是因为问题非常具体，所以 GPT 对这种问题通常答得很好，下面来看看 GPT 的回答： #### 第一轮 问：“你作为一个专业的前端工程师，请告诉我解决以下问题的思路：我在 el-dialog 中某个按钮上使用了 el-tooltip 组件，应当如何设置 el-tooltip 使其不超出 el-dialog 容器。”。 GPT 答（下文的引用部分都作为 GPT 的回答）： > 好的，以下是一个解决这个问题的思路： > > 1. 使用插槽自定义内容，...... > 2. 使用 CSS 类名控制样式，...... #### 第二轮 在第一轮得到了普通的回答，继续追问：“有没有其他方法用来控制 el-tooltip 不超出容器？”。 > 除了前面提到的两种方法外，还有一种方法可以用来控制 el-tooltip 不超出容器，那就是使用 CSS 中的 overflow: hidden 属性来控制容器的溢出，...... #### 第三轮 在第二轮得到了超常但不好用的回答，重复提问：“有没有其他方法用来控制 el-tooltip 不超出容器？”。 > 除了前面提到的一种方法外，还有一种方法可以用来控制 el-tooltip 不超出容器，那就是使用 Popper.js 提供的 preventOverflow 选项来限制 el-tooltip 的位置，...... 经过三轮交流，GPT 给出了可参考的问题代码。通过搜索“popper-options”+“preventOverflow”关键词，能确定，这的确是能解决问题的关键 API。 ```vue Hover Me ``` 现实的问题对于 GPT 而言过于复杂，所以将其拆解为更小的更具体的问题是一个有效的提问手段。经过查阅文档进一步完善解决方法，总结出的“标准答案”如下： ```vue ``` 这个问题“难”解决。我猜 80% 的 Element Plus 用户都不能在短时间内解决它。不过“难”并不意味着其涉及的技术有多晦涩，而是说有效信息比较分散，需要人工搜寻、甄别并连接有效信息的关键点。 许多人可能不具备这种逐步筛选信息的思考方式。又比如在上面这段样式代码中，官网给出的示例是不正确的，需要修改后才能使用。换做新手的我很可能发现给出配置无效后便放弃解决问题了。 总之，在这个例子里，使用 GPT 成功联通了有效信息，随后手动搜索关键配置，便找到了解决问题的正确方法。我认为只要问题够具体，便很容易通过“tell me more”这种重复提问的方式使 GPT 穷举出相关知识。再配合人工审查， 便能得到有用的东西。以下用另一个例子展示简单的知识是可穷举的。 ### 如何选取页面上某个具体的 DOM 节点？ 面试时，在正式开始提问前，我希望通过一道简单的题目让面试者放松并进入状态。一开始，我觉得“常见 CSS 垂直居中方法？”、“常见的获取 DOM 节点的方法？”这些记忆性的问题非常合适。 以“常见的获取 DOM 节点的方法”这个问题举例，我敢说，包括我自己在内，几乎所有前端都没有对这个具体的问题做过总结。因为用不上。真的用不上。在 MVVM 框架大行其道的今天，较少存在需要手动处理 DOM 节点的场景。不过，作为热身题， 它合适在简单。任何人都不会因为它阻塞的思路而陷入窘迫的地步。回答得越多，得分越高。 在用过 GPT 后，我觉得这种问题过于机械化，不能激发思考，是对被试者的侮辱。在上一小节说到，在具体问题上 GPT 能穷举相关知识。放到这个问题，我用普通人的回答和 GPT 的回答做一个对比来进一步证实它在此方面的“异能”。 普通人的回答可能是：“控制台的 $ 和 $$ 方法、document.querySelector、document.getElementBy 等方法”。接下来，让我们看看 GPT 的表现。 #### 第一轮 问：“如何选取页面上某个具体的 DOM 节点？”。 > 要选取页面上的某个具体的 DOM 节点，可以使用 JavaScript 中的 DOM API。以下是选取 DOM 节点的几种常见方式： > > 1. getElementById，下略 > 2. getElementsByClassName，下略 > 3. querySelector，下略 > 4. querySelectorAll，下略 #### 第二轮 问：“告诉我“如何选取页面上某个具体的 DOM 节点”的更多方法，除了上面提到的 document.getElementXXX、document.querySelectorXXX 相关方法”。 > 要选取页面上的某个具体的 DOM 节点，可以使用 JavaScript 中的 DOM API。以下是选取 DOM 节点的几种常见方式： > > 1. parentElement 和 children 属性，下略 > 2. document.all，下略 > 3. getElementsByTagName，下略 #### 第三轮 问：“告诉我“如何选取页面上某个具体的 DOM 节点”的更多方法，除了上面提到的 document.getElementXXX、document.querySelectorXXX、parent/children、getSelection、 document.all 相关方法。” > 1. nextSibling 和 previousSibling，下略 > 2. firstChild 和 lastChild，下略 > 3. document.evaluate，下略 > 4. event.target，下略 ... 以下重复 N 轮，直到 GPT 开始说胡话。 那么结果如何呢？ 以我最后的提问作为 GPT 在这轮上下文提及的关键字的参考：“告诉我“如何选取页面上某个具体的 DOM 节点”的更多方法，除了上面提到的 document.getElement\*、document.querySelector\*、 parent/children、getSelection、document.all、nextSibling、firstChild、document.evaluate、event.target、matches、closest、 getElementsBy\*、activeElement、elementFromPoint、Range、createTreeWalker、all、XPath、MutationObserver、forms、images、links、head、 body、defaultView、frames、form.elements、embeds、plugins、getElementsByTagName、getElementById、createDocumentFragment、anchors、 styleSheets、scripts、scrollingElement、documentElement 以及多个选择器复用相关方法”。 把 GPT 提到的关键词做一下分类，大致可以总结出以下“标准答案”： - 选择器 API： - 元素选择器：element.getElementBy\* - CSS 选择器：element.querySelector\*、element.matches - XPath 选择器：element.evaluate - Selection：window\.getSelection - Range：document.createRange - 能获取节点的实例属性： - document.x：document.all、document.images、document.styleSheets、... - node.x：element.firstChild、element.parentNode、... - element.x：element.children、... - event.x：event.target、event.from、... - mutaionRecord.x：mutaionRecord.nextSibling、... - 能返回节点的实例方法： - node api：element.getRootNode()、... - treeWalker api：treeWalker.filter()、... - 配合回调函数使用的方法： - MutationObserver：mutationObserver.observe - TreeWalker：createTreeWalker、 这应该也只是现实的冰山一角。翻阅 MDN 文档能从 Permissions、ShadowRoot、SVG 相关关键字找到更多；另一方面，除了直接使用 DOM API 外，使用控制台，甚至使用框架比如 jQuery、Sizzle、Vue、 React 都可以解决问题。他们提供了获取 DOM 节点的 API。 总的来说，无论从更广泛还是更垂直的角度翻阅资料，都能找到更多相关知识。这个 GPT 问答的例子再次证明了简单的知识能被穷举，而这个工具真的可以帮助前端学习者从繁杂琐碎的知识点中解放，保留精力去做那些对他们而言更有意义的事情。 ### 结论 我得出的结论正如标题：在具体的问题上，简单的知识能被穷举，GPT 可以作为一个合格的互联网消息过滤器。正确的使用方法是在简单的问题上用 GPT 穷举关键字，并通过文档进一步学习；其次，同许多人提过的，复杂问题需要先拆解成适合的尺寸， 再进一步用 GPT 处理。 如果说得出了结论就应该有所行动的话，那就是我觉得“如何获取 DOM 节点”这种问题过于机械化，不能激发思考，是对被试者的侮辱，所以最终，我把面试题换成另一些有名的热身题，比如：“ 如何统计某个页面使用到的 HTML 标签的种类 [1](https://lionad.art/#user-content-fn-question-1){#user-content-fnref-question-1 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}”。同样简单，但更有趣。 ## Footnotes 1. 源自贺老的 [知乎 Live](https://www.zhihu.com/lives/778991567569440768){rel=""nofollow""} 。 [↩](https://lionad.art/#user-content-fnref-question-1){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} # ⛸️ 怎样定制复杂组件的自定义滚动条？ ## 原生滚动条样式一言难尽 公司项目需要用到多表头等复杂的表格功能，一直使用 vxe-table 并在其基础上定制开发。但相比 Element Plus 的表格，它有一个对界面来说很不友好的缺陷：[不能自定义滚动条](https://vxetable.cn/#/table/base/scrollStyle){rel=""nofollow""}。使用原生滚动条会使表格右侧多出一块空白的区域，令人难受。 年前，我们要在一个新系统中画甘特图，用到了在 Github 极其流行的 [vue-gantt-elastic](https://github.com/neuronetio/gantt-elastic){rel=""nofollow""}。并不出乎意料，这玩意儿也不支持自定义滚动条。 也许大家没见过 Windows 的滚动条样式是到底有多么出戏。这里截张图给大家感受一下。 ![CodePen](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230218235213.png) CSS 滚动条相关的规范如 [CSS Scrollbars Styling Module](https://www.w3.org/TR/2021/CR-css-scrollbars-1-20211209/){rel=""nofollow""} 所规范的功能不多，甚至可以说太弱了。它只描述了一些用来简单处理滚动条样式的属性，如宽度和颜色。考虑到 PC 端用户使用鼠标，给滚动条加上动画或鼠标交互也是完全合情合理的需求，所以依赖 CSS 滚动条规范完全不够用。 但大佬对原生滚动条样式不满意，前端怎么能说不行呢，改！~~（不是手痒痒了）~~ ## 寻找简单的解决方案 要把基础库依赖的 vxe-table 直接替换为 Element Plus 表格很不现实。在没做过表格调研的情况下就迁移基础组件是不可接受的，何况我们只想改个滚动条样式。 这是 ElTable 的示例。看着这漂亮的滚动条当时真是心痒痒呀！ ![element-plus table](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230218231215.png?w=60) 讲到 Element Plus，能不能用 [ElScrollbar](https://element-plus.gitee.io/zh-CN/component/scrollbar.html){rel=""nofollow""} 组件做点什么呢？ 答案是否定的，因为 ElScrollbar 只能处理简单的滚动系统。 如图所示，假设 ElScrollbar 组件 S 本身高 400px，其直接子元素 Children 高 1000px。这个场景足够简单，所以能轻易获取 S 的滚动余量有 600px。 ![Simple Scrollbar System](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230219003509.png?w=50) 当组件有复杂的层级嵌套时，ElScrollbar 组件就不知道你要使用哪一个元素去计算滚动余量了。如图所示，在复杂情况下，ElScrollbar 的虚拟滚动条甚至会和原生滚动条出现冲突的情况。 ![Complex Scrollbar System](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230219004750.png?w=50) ## Use Scrollbars 的诞生 这段时间想了许多方法，也试了不少开源轮子，它们都不能满足我“一键替换” vxe-table 及 vue-gantt-elastic 滚动条样式的需求。所以我找时间把温习了一下浏览器滚动系统相关知识，并把需求精简后，封装出顺手的工具，[use-scrollbars](https://github.com/Lionad-Morotar/use-scrollbar){rel=""nofollow""} ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/logo.png?w=50\&type=win11) use-scrollbars 有以下几个特点： 1. 它支持定制复杂组件的滚动条样式 2. 它能提供比原生滚动条更丰富的样式、动画和交互效果 3. 它使用原生滚动事件而不是 CSS Transform 等低性能滚动方案 4. 它的状态是响应式的且有完整的类型提示 第一点，也就是我的需求，use-scrollbars 能修改 vxe-table 等复杂组件的滚动条，这是 ElScrollbar 等其它开源组件目前无法实现的功能。第二点和第三点意味着更低的代码复杂度。 第四点是说 use-scrollbars 是用 TypeSript 实现的 Vue Hook... ## 使用示例 对于简单的滚动系统，use-scrollbars 能做到 API 足够简单。 ```vue ``` ![native VS. use-scrollbars (theme css-tricks)](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/compare-3.png) 怎么使用 use-scrollbars 修改 vxe-table 呢？代码虽然没有大家想象的那么短，但一定是可以理解的。 第一步，使用 devtools 确认滚动系统，并在代码中将相关元素选取出来。 ```js const $table = tableRef.value.$el; const $header = $table.querySelector(".vxe-table--header-wrapper"); const $bodyWrapper = $table.querySelector(".vxe-table--body-wrapper"); const $bodyContent = $table.querySelector(".vxe-table--body"); const $bodyXSpace = $table.querySelector(".vxe-body--x-space"); const $bodyYSpace = $table.querySelector(".vxe-body--y-space"); ``` 第二步，通过 use-scrollbars 初始化这些滚动系统。 ```js const barStates = useScrollbar(); barStates.init({ mount: tableRef, content: [$bodyWrapper, $bodyContent, $bodyXSpace, $bodyYSpace], viewport: [$bodyWrapper] }); ``` 第三步，调整样式，适配虚拟滚动条。 ```css .vxe-table--body-wrapper::-webkit-scrollbar { width: 0; height: 0; } // ... and more ``` 最后，这是效果对比。 ::compare #left ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230219020025.png) #right ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20230219020052.png) :: 如果你是 vxe-table 用户，可以在[这里](https://github.com/Lionad-Morotar/use-scrollbar/blob/dev/play/src/vxe-table/index.vue){rel=""nofollow""}找到我写的示例组件，直接拷贝到项目中使用。如果大家对使用 use-scrollbars 定制其它组件的滚动条有任何疑惑，欢迎留言，我会逐一解答。 另，[use-scrollbars](https://github.com/Lionad-Morotar/use-scrollbar){rel=""nofollow""} 欢迎 Start & PR！ # ⚖️ 统一多组件库的层叠顺序 ## 增订 | 2022年9月5日 终于把两个 ElementPlus 实例干得只剩了一个，也顺带解决了一些项目中出现的稀奇古怪的问题。不过，这里容我吐槽一句，目前来说 ElementPlus 的问题是真的多， 因为遇见 A 问题所以升级 Element 版本却引起了 B 问题这种情况屡见不鲜。我经常对着问题一调试就是两三个小时，恍惚之间就下班了，觉得一天喂狗了。呼呼，我想摸鱼啊，请给机会！ ## 背景 上周在项目中碰到个棘手的问题。公司某项目依赖了两个不同的组件库，element-plus\@2.0.2 和 element-plus\@2.1.8。由于没把两个组件库的 zIndex 统一管理起来，所以这两库的弹窗各弹各的，可能互相遮住， 很是尴尬。 举例说明一下，两个组件库以下使用简称 E1 和 E2。element-plus（以及 element-ui）在内部实现了 zIndex 管理器，使打开的弹框的 zIndex 永远递增，解决了在单个 element 内部打开 dialog、 popover、selector-option 等组件时互相遮盖的问题。element 默认的 zIndex 起始值是 2000，首先打开一个弹窗，dialog1，dialog1 的 zIndex 设置为 2001， 如果在 dialog1 中使用按钮用打开了新的 dialog2，那么 dialog2 的 zIndex 值被置为 2002，遮住了 dialog1，这是正常的[1](https://lionad.art/#user-content-fn-append-to-body){#user-content-fnref-append-to-body ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。那么问题来了， 以上两个 dialog 都是通过 E1 打开的，一但在 dialog2 引用了 E2 的组件，打开弹窗 dialog3，那么 dialog3 的 zIndex 使用的是 E2 从 2000 开始递增为 2001 的值， 不足以遮盖 E1 中 2002 的 dialog2，所以 dialog3 被 dialog2 遮挡，显示异常。 ![打开多个弹窗示例](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220814192040.png) ## 解决 统一多组件库层叠顺序，意味着将 E1 和 E2 内部实现的 zIndex 管理器中的 zIndex 通过某种形式关联起来。由于对 element 内部的实现不是很熟悉，所以一开始团队成员内部讨论时提出过许多天马行空的设想，比如“ 将 E2 的 zIndex 管理器作为 external 载入”、或是“使用 MutationObserver 检测 DOM 变化读取最新的 zIndex 值”... 最坏的情况是把当前的 element fork 出一份代码来自己维护， 改造 zIndex 管理器实现多项目的统一管理。这些方案听起来不是那么可靠，所以我们决定先看看 element 的实现再近一步思考更优雅的解决方案。 #### 层叠管理器 element-plus 的层叠管理器（PopupManager）实现比较简单，其核心原理和 element-ui 一致，通过闭包维护了一个 zIndex 的值的单例，暴露出获取值以及递增值的接口， 以方便内部的 dialog 等组件在需要的时候有能力获取最新 zIndex 或者对 zIndex 进行递增。element-plus 中的层叠值管理的实现甚至比 element-ui 还要简单，它是一个 vue3 的 hook， 只有 20 行代码。 ```js import { ref, computed } from 'vue' import { useGlobalConfig } from '../use-global-config' const zIndex = ref(0) export const useZIndex = () => { const initialZIndex = useGlobalConfig('zIndex', 2000) // TODO: move to @element-plus/constants const currentZIndex = computed(() => initialZIndex.value + zIndex.value) const nextZIndex = () => { zIndex.value++ return currentZIndex.value } return { initialZIndex, currentZIndex, nextZIndex, } } ``` useZIndex 可以在任意 vue setup 中调用。调用后的回调提供了 initialZIndex、currentZIndex、nextZIndex 三个接口。 initialZIndex 是通过 ElementConfigProvider 传入的 zIndex 初始值；用 currentZIndex 能拿到最新的 zIndex 值；用 nextZindex 可以给 zIndex 递增后获取其值， 因为 zIndex 是全局的单例，所以使用 nextZIndex 拿到的值一定是全局最大的 zIndex。 ```vue ``` #### 思路分析 既然在 element-plus 的内部能使用 `const { useZIndex } from ...` 的形式拿到 zIndex 管理器暴露的接口，那么在项目中是否能通过一样的方法得到它呢？ 答案是肯定的。通过观察 element 的默认导出可以发现其中有 useZIndex 的存在。 ![exports in element-plus](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220814195047.png) 解决多组件库统一层叠顺序问题的本质就是在项目的应用层再实现一个 zIndex 管理器。管理器需要接受来自不同组件库的 zIndex 管理器，并在任一管理器中的 zIndex 值发生变化时，把变化同步到其它管理器中。 举个例子，我们在文章开头先使用 E1 打开了 dialog1 和 dialog2，使 E1 的 zIndex 从 2000 递增到 2001 再递增到 2002，如果再打开 E2 的 dialog3， 我们希望 dialog3 的 zIndex 从 2002 递增到 2003，这也就意味着打开 dialog1 和 dialog2 时的 zIndex 递增需要从 E1 同步到 E2。 既然 element 导出了 useZIndex，那问题就好办了。我们可以在项目中拿到 E1 以及 E2 的 useZIndex，用 vue watch 监听两个 useZIndex 回传的 currentZIndex 接口， 并把小的那个 zIndex（对应上述 E2）通过 nextZIndex 接口递增到大的（对应上述 E1）。这样一来，E1 和 E2 的 zIndex 就相等，在下一次打开弹窗时，无论是使用 E1 还是使用 E2 的弹窗， 其 zIndex 值都能保证在项目中最大。 #### 代码实现 代码实现时，团队的小伙伴写了以下代码，这段代码非常好理解，这里就不细说了。 ```js watch([ () => e1ZIndexContext.currentZIndex.value, () => e2ZIndexContext.currentZIndex.value, ], ([z1, z2]) => { if (z1 < z2) { e1ZIndexContext.nextZIndex() } else { e2ZIndexContext.nextZIndex() } }) ``` 需要注意的是，可能有非常多组件依赖了 useZIndex 的内部的响应式值，所以直接使用 watch 暴力递增 zIndex 是有问题的。想象一下，每递增一次，相关 vue 组件会被收集到等待更新的队列中，如果 z1 和 z2 的差值很大， 容易报栈溢出问题。好在解决方式也非常简单，使用 nextTick 分担每个 tick 的任务，并在回调中，根据最新的 zIndex 值进行 zIndex 递增就行了。 ```js const { watch, nextTick } from "vue" const stop = null export function useSameZIndex(ctx1, ctx2) { stop && stop() stop = watch([ () => ctx1.currentZIndex.value, () => ctx2.currentZIndex.value, ], ([z1, z2]) => nextTick(() => { const [nz1, nz2] = [ ctx1.currentZIndex.value, ctx2.currentZIndex.value ] if (nz1 < nz2) { ctx1.nextZIndex() } else { ctx2.nextZIndex() } }) } ``` ## 更多 以上分享的代码略为简单，想深入探索的话推荐直接看 element-plus 相关组件的源码，如 [message-box](https://github.com/element-plus/element-plus/blob/6503e5527715a6424433df0ff523b8910e891033/packages/components/message-box/src/index.vue){rel=""nofollow""}。虽然文中仅介绍了如何 watch 并递增管理器中的 zIndex 值，但是在实际项目开发时的使用场景肯定更加复杂，比方说，在 element-plus 上层封装业务 UI 库时可能会要用到全屏组件或是购物车等业务弹窗，那么这些库在全局的 zIndex 管理实际也可以使用 element-plus 的这套。总之，要活学活用嘛... ## Footnotes 1. 为了降低复杂度，这里只考虑将弹窗 teleport 到 body 中的情况。 [↩](https://lionad.art/#user-content-fnref-append-to-body){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} # 🕷️ 滑动验证码破解思路 昨天在掘金看到推荐文章[《从零开发一款轻量级滑动验证码插件》](https://juejin.cn/post/7007615666609979400){rel=""nofollow""}，介绍了一些相关验证码及框架开发的知识点。巧的是就在前两周，我们公司举办了一个爬虫攻防赛，其中用到多种爬虫验证的破解方法，之一就是滑块验证码。 今天在这篇文章里给大家介绍一下怎么使用 JS 破解滑块验证码。 ![最终效果（加速）](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/73ba97c7435f.gif) ## 思路讲解 ### 操作浏览器打开页面 滑块验证码是滑动验证码的一种，生成流程至少包含三步： 1. 根据用户标识，从后台获得验证码图片 2. 监听鼠标事件并回传后台 3. 后台判断事件的真伪，回传验证结果 无论生成机制的细节如何，滑块终究是要展示在页面上的。直接用 HTTP Request 把页面 HTML 请求下来肯定不行，这里我们需要使用 Puppeteer 打开网页进行渲染。测试页面就以 [react-slider-vertify](http://h5.dooring.cn/slider-vertify){rel=""nofollow""} 的官网为例。 [Puppeteer](http://puppeteerjs.com/){rel=""nofollow""} 是一个通过 DevTools 协议来控制浏览器行为的库，只需编写不多的代码，就可以操作真实的浏览器搞定诸如爬虫、自动化测试、网页性能分析、浏览器扩展测试等功能。使用起来比较方便，文档齐全。根据文档，打开页面前需要启动一个浏览器实例，然后调用 newPage 方法创建一个新页面。核心代码如下。 ```js const puppeteer = require('puppeteer') puppeteer.launch().then(async browser => { const page = await browser.newPage() await page.goto('http://h5.dooring.cn/slider-vertify/vertify') }) ``` ![打开页面测试](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/jpoVF4UbuI.gif) 正常浏览网页时，很少会碰到滑块验证，因为它的路径非常长，会需要浪费用户好一会儿时间。虽然文案上给你显示“恭喜 0.9s 打败了 99% 的用户”，但从前置脚本请求，到加载图片，用户滑动滑块， 到回传验证...前前后后的步骤加起来可能花了你 9s 不止。本质上它是防御性的手段，一般当服务器限流，或者服务器已经怀疑你是爬虫的时候，才会让它跳出来要求做进一步验证。所以一般来说，爬虫代码可以默认忽略滑块验证的， 不过本文代码我们就假定默认验证码一定存在吧。 接下来，分析一下用户行为。解决滑块验证，无非就是先判断一下缺口的位置，然后移动鼠标。这里进一步可以细分为鼠标的点击事件和鼠标移动事件两种。代码逻辑大致如下。 1. 等待验证码图片加载完毕 2. 移动鼠标到滑块位置 3. 按下鼠标 4. 移动鼠标到缺口位置 5. 松开鼠标 6. 等待结果返回 啊，流程我都知道，可问题就在，怎么判断要把鼠标移动到哪里？服务器端返回的是一张带缺口的图片，缺口位置指定是不通过接口传递的。 可能还有些同学会问，怎么移动鼠标呢？如果我一次性就把滑块给移到指定位置了，那服务器不是会立马把我标记为爬虫嘛... 这两个问题我逐一解答。 ### 判断缺口位置 要分析缺口的位置，我们必须先知道这个缺口是怎么画上去的。打开控制台初步检查可以发现，页面从服务器先拿到了一张完整的图片，然后缺口位置是通过 JS 随机生成的。啊这...这...这是因为我们用的测试页面是文档页， 大家不必在意这些安全方面的小细节。 ![找到请求](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210918184414.png?type=win11) 接着刚才的思路继续，既然缺口是从原图中挖的一个洞，那么我们只需要识别一下图片中洞的位置就好了。比较简单的方案是使用第三方的图像识别技术（或相关技术），把图片上传至第三方，就直接拿到缺口位置的相对坐标。 下图给大家展示一下阿里云的图像分割的效果[1](https://lionad.art/#user-content-fn-alimagic){#user-content-fnref-alimagic ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ![阿里云图像分割](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/itLO6bbCMH.gif) 如果想做一个效果稳定一点的验证码破解工具，我建议大家还是用自己的模型，或者自己写算法。一来是第三方要的钱钱不少哇\~ 再就是这种图像识别并不是专门为验证码训练的，所以放到爬虫中还不太成熟，**一旦背景图片复杂，识别率下降得老快了**。 ![百度云图像主体识别](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210918191220.png) 以下介绍一种新思路。反正我们已经有一张完整的图片了，那就只要不断地滑动滑块，把结果和原图比对就行。理论上，只要滑倒差不多“那个点”，肉眼看起来不会有很大的违和感时，就搞定了。比如下面这张图。 ![和原图进行比对](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210918192111.png) 截图嘛可以直接用 Pupeteer 的截图功能，它提供了对应的 API，可以精准的截出特定元素。 至于图片比对，其实就是给图片初步处理后，两张图一个像素一个像素的去比较。**两个像素如果颜色差异超过阈值，就认为这是两个不相同的像素**。简便起见，我们直接用开源库 [rembrandt](https://github.com/imgly/rembrandt){rel=""nofollow""}，它会给我们返回两张图片间的差异。 最后是滑动滑块，既然要模拟人肉操作，那么操作 CSS，用绝对定位，把滑块一个像素一个像素的向右移；每移动一次，把图像比对的结果记录下来。 以上三个流程的核心代码非常简单，只需要以下几行： ```js while (left <= maxOffset) { /* 使用 CSS left 属性控制悬浮的滑块的偏移量 */ await page.evaluate(async ($sliderFloat, left) => { $sliderFloat.setAttribute('style', `left: ${left}px`) }, $sliderFloat, left) /* 截图并和原图进行比对，把结果存到 results 数组里 */ const $panel = await page.$('#Vertify-demo-4 .canvasArea') const panelImgBase64 = await $panel.screenshot({ type: 'jpeg' }) const compareRes = await rembrandt({ imageA: panelImgBase64, imageB: rawImage }) results.push({ left, diff: compareRes.differences }) left += 1 } ``` ![通过CSS控制位移](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/9KgejUuCru.gif) 最后，把 results 扔到里面展示一下（这里给个 ECharts [折线图示例网址](https://echarts.apache.org/examples/zh/editor.html?c=line-simple){rel=""nofollow""}），不出意外能得到这样一张图表。看到那个尖尖的“V”型山谷了嘛，呼哈哈哈，答案很明显，当我们把滑块从左往右移动时，滑块约接近缺口，那截出来的图片就越像原图，它两之间像素差异越小；一直往右移动，滑块会逐渐远离缺口，截出来的图片和原图相比像素差异又逐渐开始增大。我们只需要把差异最小的那个点找到，然后滑动滑块到对应的 left 偏移量就阔以了。 ![图像比对结果](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210918203306.png) 题外话，为什么最大的差异在 3000 左右呢？我们简单估算一下。 滑块的大小为 45\*45，再加上外面的圆形，约摸占了 2100 像素；也就是说缺口加滑块，理论上最大会有 4200 个像素和原图不同。不过滑块可能和遮住的地方像素有重合，假设重合了 350 像素，再加上我们的最低点的图片差异都有 351， 减去这些误差，得 3499。呜呼，3499 约等于 3000，估算成功（手动狗头）。 ### 速度优化技巧 不过这还没完，你要是把代码跑起来就会发现，卧草，太慢了这玩意儿！正常人划一下验证码顶多两秒钟的事儿，我们一帧一帧截图得花个 40s 的时间才能截完图算出山谷谷底的值来。 这里提供几种思路优化效率： 1. 把元素缩小，复制多份，平铺开来展示；这样只要截一次，然后再裁剪、比对就好。 2. 放大步长，比方说先每次平移 15px，找到局部最优解，然后在局部最优解附近再回到平移 1px 的方案找最优解。 3. 因为图片比对的结果类似“V”字，“V”字右半边其实是可以不用再计算的。 使用 1+2+3 我觉得可以在 3s 内搞定最优解，不过代码复杂度会变得很高，文中简单起见暂只实现一下方案 2。 首先是每次移动 15px 找局部最优解。 ```js // 图片缺口是不会给挖在初始附近的， // 所以 left 从 45 像素开始计算可以节约不少计算量， let left = 45; const max15Offset = 265; const res15px = []; while (left <= max15Offset) { await setLeft(left); const compareRes = await compare(); res15px.push({ left, diff: compareRes.differences, }); left += 15; } ``` 然后再尝试每次移动 2px 找最优解，搜寻的范围是 15px 步长最优解的 left 偏移量的左右共 20 个像素。 ```js const min15pxDiff = Math.min(...res15px.map((x) => x.diff)); const min15pxLeft = res15px.find((x) => x.diff === min15pxDiff).left; left = min15pxLeft - 12; const max2Offset = min15pxLeft + 8; const res2px = []; while (left <= max2Offset) { await setLeft(left); const compareRes = await compare(); res2px.push({ left, diff: compareRes.differences, }); left += 2; } ``` 此时得到的解可以约等于最优解了。当然，如果你觉得不稳的话，还可以使用 1px 步长去找。 估算一下，原先需要截 245 次图片，现在直接降到 1/10，23 次。不过，也别太高兴，因为测试发现只做优化 2，解验证码的时候还是要 7s... ### 操作鼠标滑滑块 缺口位置都搞定了，那移鼠标滑滑块儿还不简单嘛\~ Puppeteer 已经提供了[鼠标相关的接口](http://puppeteerjs.com/#?product=Puppeteer&version=v10.2.0&show=api-class-mouse){rel=""nofollow""}，一共四个：mouse.click、mouse.down、mouse.move、mouse.up，分别是点击、按下、移动和松开。使用 mouse.move 可以直接把鼠标位置移动到一个特定的坐标上。假设我们现在从坐标（100,100）花大约 1s 把鼠标移动到 （200,200），可以使用循环实现。 ```js const now = { x: 100, y: 100 } const target = { time: 1000, x: 200, y: 200, } const steps = 10 const step = { x: Math.floor((target.x - now.x) / steps), y: Math.floor((target.y - now.y) / steps), time: target.time / steps } while (now.x < target.x) { await sleep(step.time) now.x += step.x now.y += step.y await page.mouse.move(now) } ``` ### 鼠标轨迹优化 害，要是打游戏的时候也像这段代码一样，我想我的手点到哪儿它就点到哪儿就好了\~ 机器是不会手抖的，这段代码和真实世界的滑动效果相差太远了！我们看一张我用手滑的效果，尤其是要仔细观察滑动过程中鼠标的位置。 ![鼠标轨迹不稳定](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/soov8Gny09.gif) - 鼠标 Y 轴位置总是在变 - 鼠标 X 轴位置会滑过头（别笑，你肯定也经常划过头） 这里做一波小优化，把这两个细节整合进去。 ```js // 获得一个随机的偏移量 const getRandOffset = (randNegative = true, max = 3) => { const negative = randNeagtive ? (Math.random() < 0.5) ? -1 : 1 : 1 return Math.floor(Math.random() * max) * negative } // 先滑过头十几像素，然后再花 100 毫秒的时间往回滑到正确位置 const points = [ { time: 1000, x: 200 + getRandOffset(false, 15), y: 200 + getRandOffset(false, 15), steps: 10 }, { time: 100, x: 200, y: 200, steps: 3 } ] // 注意这里用 for await 循环把 points 串起来执行 for await (const target of points) { const step = { x: Math.floor((target.x - now.x) / target.steps), y: Math.floor((target.y - now.y) / target.steps), time: target.time / target.steps, } let gap while (gap = Math.abs((target.x - now.x)), gap > 0) { await sleep(step.time) // 最后一步就直接滑动到位，不需要随机数了 const inOneStep = Math.abs(target.x - now.x) <= Math.abs(step.x); if (inOneStep) { now.x = target.x; now.y = target.y; } else { now.x += step.x + getRandOffset(); now.y += step.y + getRandOffset(); } moveMouseTo(now) } } ``` 如何移动鼠标到这里就解决了，如果要考虑加速度、用户习惯等因素，代码会复杂许多，暂时就不深入讨论啦，有兴趣的同学可以自己研究。 最终效果见下图。 ![最终效果（加速）](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/73ba97c7435f.gif) 源码地址在此：[CrackTheShield](https://github.com/Lionad-Morotar/crack-the-shield/tree/master/tasks/dooring-slider){rel=""nofollow""}。 ## 阅读更多 - [《Python爬虫的实际运用之：破解滑动验证码》](https://juejin.cn/post/6945336161468416037){rel=""nofollow""}，这个老哥用了图像边缘检测的方法来判断缺口所在位置。 - [《震惊! 滑动验证码竟然能这样破解》](https://juejin.cn/post/6844903679808520205){rel=""nofollow""}，这个老哥用了一种看谁脸黑的办法来判断图片的缺口所在位置。 ## Footnotes 1. [测试地址](https://vision.aliyun.com/experience/detail){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-alimagic){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} # 🌟 探秘 CSS 光影效果 ## 前言 总听人说光和影是孪生兄弟，有光就有影。其实不然，如果没有光线强弱的对比，也就不会有阴影的存在。我们总是依靠物体表面的反光来感知世界，假设所有物体都能完全吸收光线，那世界将变得黑漆漆一片。 所谓只有理解光，才能驾驭阴影。**好的设计师往往都是用光高手，能通过复杂的光影向读者传达出物体的质感、空间感以及层次感**[1](https://lionad.art/#user-content-fn-texture){#user-content-fnref-texture ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。他们画出来的设计稿都是漂漂亮亮的，这可苦了广大前端同胞！在浏览器中， 我们只能用寥寥几个 CSS 属性，束手束脚的同时还想方设法地还原设计稿。毕竟，相比我们用的 CSS 手枪，设计师们用的 AE、C4D 看起来就像大炮一样！ ## 常见光影效果 好在我们可以暂且假以性能为由，继续正大光明地怎么简单怎么来（汗）。就像一提到光影效果，大家第一反应肯定是操起 box-shadow、text-shaodw、drop-shadow 三件套直接开画。就大部分场景来说，这些属性还挺好用的， 可用它实现多种效果，比如单侧投影、空心投影和投影动画。若涉及到彩色阴影、长投影或是倒影，就需要结合其它 CSS 属性打辅助了。 [彩色投影](https://juejin.cn/post/6844903704986910728){rel=""nofollow""}，可以让伪元素继承父元素的背景，再加模糊滤镜即可。这个思路也可以用来制作毛玻璃效果[2](https://lionad.art/#user-content-fn-frosted-glass){#user-content-fnref-frosted-glass ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ![彩色投影](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210522171201.png) ```css .avator { position: relative; background: 'xxx'; } .avator::after { content: ""; position: absolute; top: 10%; width: 100%; height: 100%; /* 伪元素继承父元素背景 */ background: inherit; /* 再加一些稀奇古怪的滤镜，调一调参数 */ filter: blur(10px) brightness(80%) opacity(.8); z-index: -1; } ``` 制作倒影可以使用 -webkit-box-reflect 属性[3](https://lionad.art/#user-content-fn-box-reflect){#user-content-fnref-box-reflect ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。兼容性还不错，除了火狐和 IE，其余浏览器都能用。另一种方法则是用伪元素将父元素复制一份，再 transform 倒转一下位置。 ![https://codepen.io/TheDutchCoder/pen/IKqpA](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/FRUa9DGFu2.gif) 阴影的另一面是高光。画高光的思路可以直接套画阴影的思路，只不过需要将投影的颜色改为半透明白色。 ![https://codepen.io/Lionad/pen/rNWMVGb](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210522170201.png) 另一种方法是用背景渐变或伪元素模拟高光。若再配合 CSS 动画，可以轻松实现[扫光](https://codepen.io/Lionad/pen/wvJJYzR){rel=""nofollow""}等效果。 ![扫光动画](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/bmQ4xjDqE0.gif) ```css body:before { content: ""; position: absolute; top: 0; width: 200vw; height: 35px; background-color: rgba(255, 255, 255, 0.4); transform: rotate(45deg); animation: scan-light 2s ease-in infinite; } @keyframes scan-light { from { right: -100vw; } to { right: 40vw; } } ``` ## 进阶光影效果 ### 纹理 以上提到的几种绘制光影的方法，主要用来传达物体的形状及位置。比方说，倒影和渐变高光可以用来传达物体的质感，展示物体光滑到足以发生镜面反射的表面。当然，这是理想情况。现实中的物体很少有平滑的表面，就算肉眼可见的光滑表面， 微观上而言也是坑坑洼洼不堪入目。 ![物体的微观表面](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523011634.png?w=70) 一旦我们开始使用 CSS 去模拟高级光影，首先碰到的难题就是如何处理磨砂表面。以下介绍一种简单实现磨砂表面的思路，在寻常场景用用还是阔以的。 **物体表面是什么样，我们就给它贴什么样的图片，这种方法叫做材质贴图**。我们用一个简单的材质贴图为例，先用 PS 弄一张纯色的背景，然后分别随机填充一些稍微亮一点高光和稍微暗一点的像素点[4](https://lionad.art/#user-content-fn-linegradient-material){#user-content-fnref-linegradient-material ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}， 就能获得类似下图结果。 ![材质图片](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523020054.png) 我们再把这张材质平铺为文档背景，就可以得到类似磨砂金属般的表面纹理（由于图片压缩的原因，效果可能不好，可直接前往[CodePen](https://codepen.io/Lionad/pen/mdWWxdg){rel=""nofollow""}查看细节）。 ![https://codepen.io/Lionad/pen/mdWWxdg](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523020615.png) 不同的高光和阴影细节会给人不同的感受，比方说这里有一张雪花电视效果图，其高光像素和阴影像素的对比度要比磨砂金属表面的大得多。 ![https://codepen.io/joeyhoer/pen/CojIk](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523021338.png) 使用图片的不便之处在于没有办法边调整细节边预览，并且 PS 可能超出前端的技术栈范围了。好在我们还有 SVG 这个神器[5](https://lionad.art/#user-content-fn-why-svg){#user-content-fnref-why-svg ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。以下是一套“标准的”材质生成代码，可以用来生成非常多种类的材质。 ```html ``` 其中，[feDiffuseLighting](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Element/feTurbulence){rel=""nofollow""} 是一种噪音滤镜，可以创建出随机的材质图片。[feDiffuseLighting](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Element/feDiffuseLighting){rel=""nofollow""} 是光源滤镜。feDistantLight 指示用平行光作为光源。 光源？弄个材质还要这么复杂嘛？ 先别急，**光源其实也就几种：点状光、平行光、聚光。可以简单理解成电灯泡、太阳以及戏剧灯**。由于我们还将在表面材质的话题中停留一会儿，暂且只需要用到平行光。 ![https://developer.mozilla.org/zh-CN/docs/Web/SVG/Element/feDiffuseLighting](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523030133.png) 大致了解了上面那段 SVG 是什么意思，我们就开始愉快地调参数啦。 先试试降低灯光到表面的距离（减小 elevation）以增加高光面和阴影面的对比度。获得了以下看起来像是[某种土壤的纹理](https://codepen.io/Lionad/pen/poeeLKd){rel=""nofollow""}。 ![土壤纹理](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523154039.png) 接下来拉高灯光，调整光照颜色（lighting-color），再把纹理弄粗糙一些（减小 baseFrequency），获得了类似[大理石的纹理](https://codepen.io/Lionad/pen/zYZZjxb){rel=""nofollow""}（也许有点像白色的牛皮纸）。 ![大理石纹理](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523153936.png) 增加 baseFrequency、调整表面基准高度 surfaceScale 获得平滑纹理，再调整灯光高度降低高光和阴影的对比度，得到了[白石灰墙壁纹理](https://codepen.io/Lionad/pen/rNyyQjp){rel=""nofollow""}。 ![白石灰墙壁](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523153351.png) ```html ``` 各位应该发现了白石灰墙壁的代码相比“标准模板”增加了一个高斯模糊滤镜（feGaussianBlur）。**原则上滤镜无限叠加，可以做出非常多好玩的效果**。比方说，有大佬用 SVG 画云朵。对，你没听错。以下是用 SVG 画的[云朵纹理](https://codepen.io/beauhaus/pen/QJrpPY){rel=""nofollow""}[6](https://lionad.art/#user-content-fn-cloud){#user-content-fnref-cloud ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ![云朵材质](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523034525.png) ### 菲涅尔效应 说完了粗糙的表面怎么画，我们再看看画光滑表面又有哪些原则。说起水和金属这种有相对光滑的表面的材质，不得不提到菲涅尔效应。 一句话介绍菲涅尔效应：如果你站在湖边低头看脚下的水，你会发现水是透明的，反射不是特别强烈，能看到水底；如果你看远处的湖面，你会看见山和天空的倒影。 ![菲涅尔效应](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523160708.png) 每种材质都有各自的菲涅尔值，这是根据其折射率决定的，表明了会有多少光线被物体吸收，又有多少光线从物体表面反弹[7](https://lionad.art/#user-content-fn-fresnel){#user-content-fnref-fresnel ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。以下用 [chaosgroup.com](https://www.chaosgroup.com/blog/understanding-glossy-fresnel){rel=""nofollow""} 的案例做说明。 ::article-a210523-fresnel 图中有一个粗糙的球体，右侧图片中的球体边缘反射了天光而显得边缘发光，左侧图片中球体边缘则没有此现象。球体表面粗糙，菲涅尔效应会变得非常微弱，所以左图是正确结果；如果球体类似金属或水面，表面光滑，那么正确结果应当类似右图。 了解菲涅尔效应之后，我们就可以根据经验凭空画一些高菲涅尔效应的物体。下图是 Oscar Salazar 用 CSS 画的[水滴](https://codepen.io/raczo/pen/KKVbQmV){rel=""nofollow""}。他用 box-shadow 给水滴的下缘增加了大量的透明白色阴影来模拟菲涅尔效应。 ![水滴效果](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523164407.png) 如果对比了现实中的水滴，你会发现 Oscar Salazar 画的并不“真”。但是因为水滴的放大作用，再加上光影效果，十分抓人眼球，给人“神似”的感觉，所以并不会觉得画得有问题。 ![现实中的水滴](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523215330.png) 下图是 Envato Tuts+ 画的[毛玻璃效果](https://codepen.io/tutsplus/pen/WLaWjX){rel=""nofollow""}。左边是原版，右边是增加了菲涅尔效应后的修改版本。修改后的版本看起来像是边缘平滑的玻璃版，而不是塑料板儿一块[8](https://lionad.art/#user-content-fn-draw-not-sure){#user-content-fnref-draw-not-sure ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 :::article-a210523-frosted-glass ## 场景实战 限于技术，还有很多种类的光影效果文中没有提到，以后有机会的话出个续集吧（咕咕咕预定中）。这里我们用一个 CSS 绘制的书籍封面效果作为结尾，也顺便串联一下上文提到的技术。素材只给两张书籍封面图片，[点此下载第一张](https://mgear-image.oss-cn-shanghai.aliyuncs.com/css-draw/s2709063811.jpg){rel=""nofollow""}，[点此下第二张](https://mgear-image.oss-cn-shanghai.aliyuncs.com/css-draw/s3360190011.jpg){rel=""nofollow""}[9](https://lionad.art/#user-content-fn-refferer){#user-content-fnref-refferer ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}，目标是实现以下效果[10](https://lionad.art/#user-content-fn-compressed){#user-content-fnref-compressed ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ![《乞力马扎罗山的雪》](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/book-cover-1.png) ![《八百万种死法》](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/book-cover-2.png) ### 搭出框架 首先，观察图像，背景是一张纸，上面有一本书；光源在右上角，大概是平行光，光源高度离纸面不远。我们先用 HTML 搭出框架。 ```html
    ``` ### 处理纹理 然后我们用 SVG 调出类似[纸面的纹理效果](https://codepen.io/Lionad/pen/dyvvapV){rel=""nofollow""}，打光，然后设为背景。 ![纸纹理](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523175503.png) ![纸纹理打光后](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523180326.png) ```html
    ``` ### 封面细节 紧接着开始绘制书籍封面，谨记有三个部分要处理：材质、高光和阴影。[处理完之后结果如下](https://codepen.io/Lionad/pen/jOBBdwg){rel=""nofollow""}。 ![为添加图片的封面](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523181428.png) 有一些小细节要注意。 - 封面折痕的处理 - 模仿闭塞阴影 - 防止边缘过于锐利 先来说说折痕的处理。如果你手头有一本实体书，那再好不过了[11](https://lionad.art/#user-content-fn-fold-mark){#user-content-fnref-fold-mark ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。试着用闪光灯打光，看看折痕上的光影，应该能发现折痕不过就是一道亮面和一道暗面的组合。我们可以用渐变来模拟这条折痕。 ![封面折痕](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523182507.png) ```css .book-cover .book::after { content: ''; position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 2; background-repeat: no-repeat; background-image: /* 1. 这条渐变是比较明显的那道折痕 */ linear-gradient(to right, rgba(0,0,0,0.1) 0.3%, rgba(255,255,255,0.09) 1.1%, transparent 1.3%), /* 2. 这条一像素的渐变是封面最左侧的折痕（没有暗面） */ linear-gradient(to right, rgba(0,0,0,0.2) 0, rgba(255,255,255,0.08) 0%, transparent 0.5%); background-size: 50% 100%, 50% 100%; background-position: 0% top, 9% top; } ``` 然后再说说闭塞阴影。闭塞阴影的概念非常简单，指两个物体靠得比较近，遮住了光线；靠得越近的地方，阴影就越黑[12](https://lionad.art/#user-content-fn-occlusion-shadow){#user-content-fnref-occlusion-shadow ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。对应到 CSS，drop-shadow 产生的阴影很“实”，但不能叠加； box-shadow 产生的阴影可调节阴影范围，但会向四周扩散。我们可以通过叠加 drop-shadow 和 box-shadow 的方式来模拟出更真实的阴影效果。 ```css .book-cover .book { position: relative; /* 由于阴影对视觉中心有影响，所以把书整体向右上方挪一些 */ margin-top: -1vh; margin-right: -1vh; width: 32%; max-width: 600px; font-size: 0; box-shadow: -55px 40px 30px 0 rgb(0 0 0 / 10%), -27px 25px 35px -5px rgb(0 0 0 / 20%), -10px 10px 15px 5px rgb(0 0 0 / 10%), -12px 12px 10px 0 rgb(0 0 0 / 20%), -7px 7px 8px 0 rgb(0 0 0 / 10%), -5px 5px 5px 0 rgb(0 0 0 / 20%), -2px 2px 3px 0 rgb(0 0 0 / 30%); filter: drop-shadow(-20px 20px 15px rgba(0, 0, 0, .65)); } ``` 实现效果如下图。位置一指闭塞阴影，离书越近则阴影越浓重；位置二是 box-shadow 向外扩散的效果，和光源位置相背，违反了人的认知经验，需要避免。 ![阴影效果](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523183850.png) 再是关于如何防止边缘过于锐化。~~还未处理前，书籍的边缘类似以下这张图。~~由于图片被压缩，什么细节都看不出来了，这里直接介绍一下防止边缘锐化的方案吧。把两张图片叠一起，下面那张图片模糊一像素， 上面那张图片 border-radius 设置 2 像素，搞定。 ![封面边缘](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523184932.png) ### 成品展示 最后，把所有代码整合到一起，调调参数，改改细节，就完成啦。嘿嘿，再放一张效果图。[可以到 CodePen 查看最终效果](https://codepen.io/Lionad/pen/XWMMNKK){rel=""nofollow""}。 ![《罗生门》](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/book-cover-3.png) 啥，你想做一本能翻页的书？ 那得去康康 [turn.js](http://www.turnjs.com/#getting-started){rel=""nofollow""} 的实现[13](https://lionad.art/#user-content-fn-turnjs){#user-content-fnref-turnjs ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。效果如下图，其中也有用到菲涅尔效应哦。 ![turn.js](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210523191034.jpg?w=60) ## Footnotes 1. 人话就是：物体的材质、形状以及位置。 [↩](https://lionad.art/#user-content-fnref-texture){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} 2. [*How to create a frosted glass effect using CSS?*](https://stackoverflow.com/questions/17089927/how-to-create-a-frosted-glass-effect-using-css){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-frosted-glass){.data-footnote-backref ariaLabel="Back to reference 2" dataFootnoteBackref=""} 3. [《-webkit-box-reflect 属性简介及元素镜像倒影实现》](https://www.zhangxinxu.com/wordpress/2016/08/webkit-box-reflect-moz-element/){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-box-reflect){.data-footnote-backref ariaLabel="Back to reference 3" dataFootnoteBackref=""} 4. 其实用渐变+随机的方法也能生成类似磨砂金属的材质贴图，这样就可以不需要引入外部图片了，但过于麻烦，不好调参，还不如 base64 来得方便。 [↩](https://lionad.art/#user-content-fnref-linegradient-material){.data-footnote-backref ariaLabel="Back to reference 4" dataFootnoteBackref=""} 5. 请原谅我，我总是潜意识里把 SVG 当作 CSS 的超集，只因为可以用它来画画~~而且在画画方面可以吊打 CSS~~。 [↩](https://lionad.art/#user-content-fnref-why-svg){.data-footnote-backref ariaLabel="Back to reference 5" dataFootnoteBackref=""} 6. [云朵效果优化（~~大佬优化大佬~~）](https://www.zhangxinxu.com/wordpress/2020/10/svg-feturbulence/){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-cloud){.data-footnote-backref ariaLabel="Back to reference 6" dataFootnoteBackref=""} 7. [《理解光泽度的菲涅尔效应》](http://hanshilin.com/software/v-ray/understanding-glossy-fresnel/){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-fresnel){.data-footnote-backref ariaLabel="Back to reference 7" dataFootnoteBackref=""} 8. “看起来像”和“现实”并不等同。就像许多画家为了营造气氛或达到想要的效果，会打破光影的物理限制。这是经验性的总结，当然，也见仁见智了。 [↩](https://lionad.art/#user-content-fnref-draw-not-sure){.data-footnote-backref ariaLabel="Back to reference 8" dataFootnoteBackref=""} 9. 由于 OSS 设置了防盗链，在第三方网页应该打不开这个链接。不过我开放了空 refferer 的访问，可以使用浏览器直接打开图片再保存。 [↩](https://lionad.art/#user-content-fnref-refferer){.data-footnote-backref ariaLabel="Back to reference 9" dataFootnoteBackref=""} 10. 由于图片压缩，演示的效果会打折。各位可以实操以体验完整效果~~及完整乐趣~~。 [↩](https://lionad.art/#user-content-fnref-compressed){.data-footnote-backref ariaLabel="Back to reference 10" dataFootnoteBackref=""} 11. 别说你的书还是新的。 [↩](https://lionad.art/#user-content-fnref-fold-mark){.data-footnote-backref ariaLabel="Back to reference 11" dataFootnoteBackref=""} 12. 对应游戏画面设置中的“环境光遮蔽”可能好理解一些。 [↩](https://lionad.art/#user-content-fnref-occlusion-shadow){.data-footnote-backref ariaLabel="Back to reference 12" dataFootnoteBackref=""} 13. CSS 也能实现翻页效果，只不过效果没那么好，见：[*The Mad Magazine Fold-In Effect in CSS*](https://thomaspark.co/2020/06/the-mad-magazine-fold-in-effect-in-css/){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-turnjs){.data-footnote-backref ariaLabel="Back to reference 13" dataFootnoteBackref=""} ::: :: # 🍲 设计模式与 JS 魔法锅 > 设计模式最终要融入任何语言。 ## 设计模式是什么 从《人月神话》到《大教堂与集市》，许多闻名业界的作品都“低代码、高文化[1](https://lionad.art/#user-content-fn-%E6%96%87%E5%8C%96){#user-content-fnref-%E6%96%87%E5%8C%96 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}”；各种代码文化运动可以看作“造神运动”此类周日剧场。许多大佬在向人们传授代码经验之余，都喜欢尝试用文化手段（不论是哲学思想还是艺术内涵）， 来统一人与代码的关系。这种跨界思考的过程通常比较晦涩，诸如“面向对象”、“设计模式”这些放到现在来说我们耳熟能详的词，在过去几十年都是由行业顶尖大佬们牵头搞研究，再经过不断地实践，逐渐沉淀下来形成的标准。 设计模式是什么？ **设计模式是一种标准，它描述了使用面向对象编程语言解决问题的方式。** 设计模式一词发源于建筑学作品《建筑模式语言》，后被一个人们称为“四人帮”（GoF）的小组种出它在软件界开的新花。无论是建筑学还是软件学中的设计模式，相同的地方是，它们都想解决“人”和“物”的关系相关问题，并且形成了一套特定的方法论。 **好比人们有了灶就可以长久保存火种，用名词把晦涩难懂的抽象定义为标准，这样有利于思想传播**。只要人们普遍接纳并熟知设计模式，便能畅通无阻地沟通代码的实现。当然，现实很丰满，畅快沟通有个大前提：程序设计时， 大家需要使用面向对象编程语言来合作。 ## 为什么非面向对象不可 构建大型软件不止面向对象这一条路，与面向对象相对应的还有结构化、形式化等程序设计方法。任意一种有自有优劣。面对日益复杂的软件，人们关心的重心逐步转移到软件的可重用性方面。面向对象凭借着分类、封装等天然符合人们认知规律的优势，得到快速发展， 终打通需求分析、程序设计到编程语言等开发上下游工作，赢得了业界青睐。 面向对象把功能作为节点，组合为功能网格，节点间通过消息通讯以及做对应的响应。这样一来，开发在编程时不再需要直面输入输出这种数据流动的思考方式，只需要按照指令维护各个对象内部的状态即可，节点对应的代码片段也就能得到重用。 ![Message Passing In OO](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210511174933.png?w=40) 相比子程序复用，函数复用已经是巨大的进步[2](https://lionad.art/#user-content-fn-fn-call){#user-content-fnref-fn-call ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。类复用相比函数复用要更加抽象，因为它保存了函数和状态的集合；而设计模式比类复用在抽象上更胜一筹：设计模式不单单直接复用某个类，而是复用整个“功能网格”， 把特定问题的解决方案相关的所有节点和通讯机制全部拷贝，固化下来，命名并形成标准。**设计模式其实是使用面向对象编程语言时代码复用的高级形式，是面向对象发展壮大之路的必然的产物**。只要写代码，就会碰到复用性问题，四人帮偏好面向对象，所以“ 设计模式”只是他们用来传授的面向对象编程中的代码复用性经验的概括。换句话说，大部分情况下我们讨论的“设计模式”和“面向对象设计模式”完全等同。这也就解释了为什么非面向对象不可了。 我们讨论一个新的问题，如果过滤掉设计模式中的面向对象成分，剩下的是些啥呢？ ```js console.log(DesignPatterns.filter(removeOO)) ``` ## 设计模式的本质 我们先直接删除上文关于设计模式的定义中的“面向对象”几个字，看看剩下些什么：设计模式是一种标准，它描述了~~使用面向对象编程语言~~解决问题的方式，是~~使用面向对象编程语言时~~代码复用性的高级形式， 是~~面向对象~~发展壮大之路的必然的产物。 句子有些不通顺，修补之后变成了：**设计模式是一种标准，它描述了编程时解决问题的特定方式，是代码复用的高级形式及发展代码复用必然的产物。** 设计模式本质是什么？不言自明，它只是相关代码复用的一种抽象概念。 说到代码复用，主要关系到代码组织。从函数复用，到使用设计模式，再到使用库、框架，三种代码复用方式的主要区别在于代码组织的粒度不同。 函数复用比较简单，你可以写一个叫做 Add 的函数给两数相加，然后 Copy\&Paste 到其他地方复用，或是把函数存放到 Utils.js 文件中，通过模块机制复用。为了了解如何使用某个函数，需要在使用前阅读注释。 库和框架最为复杂，它们是组织了大量函数及实体形成的巨型代码片段。开发新项目时很少会花精力自研框架，一般都引现成的轮子直接开造。使用某库或框架前，必须详细阅读文档。 设计模式则是单个或多个函数的组合（在 Java 中不是函数而是类），既可以在新项目里现写一个模式供使用，也可以引入社区现有的模块来复用。为了了解如何使用某个设计模式，需要提前了解该模式定义的实体以及实体是通讯机制。 ![函数、设计模式、框架间的升级关系](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20210513145630.png?w=70) 设计模式作为最简单的实体和函数的组合，可看作函数的升级版或是框架的缩水版；去掉设计模式中的面向对象相关内容，就只剩下了函数。 等等，“实体和实体间通讯机制”凭空消失了？ 并没有。但我想让他消失。下文将从 JavaScript 入手，介绍如何把设计模式的概念映射到语言特征中。语言特征可是个好东西呀！如果你同意抽象也像复用一样有函数复用、库和框架等不同复杂度的层次的话，那我认为**语言特征就是抽象的基础了。 除了语言本身以外，所有抽象的建立都依赖于语言特征**。把设计模式映射成语言特征后，我们就能跳出面向对象的禁锢，从新的、更高层的角度重新思考代码复用问题。 回到正题，我们从 JS 开始说起。 ## 仿制设计模式 编程语言并不是万能的。**特定语言适合用来解决特定问题**[3](https://lionad.art/#user-content-fn-css){#user-content-fnref-css ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。提到 JavaScript 诸多语言特征，其优点可以用寥寥三个词概括：“原型”、“对象”、“函数”。熟练掌握了这些内容，就能在 JS 的世界中游刃有余。 ![《JavaScript 精粹》VS《JavaScript 权威指南》](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200704/20200709104930.png) 传统面向对象语言以类封装状态，并向外暴露改变状态的方法。以下代码中的书本类为例：Book Class 保持有 name 状态，可以使用 getPrintName 方法返回包装后的 name 或使用 rename 修改 name 。 ```js class Book { constructor () { this.name = '设计模式与JS魔法锅' } getPrintName () { return '《' + this.name + '》' } rename (newName) { this.name = newName } } ``` 放到早期版本 JS 中，想要封装变量，这不好办。早期版本的 JS 没有块级作用域，所以声明的变量会在整个代码或函数作用域中生效。为了仿制类的状态封装能力，知名布道者道格拉斯发明了一种“模块模式”[4](https://lionad.art/#user-content-fn-module-pattern){#user-content-fnref-module-pattern ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}， 即通过闭包来控制变量的访问权，代码如下： ```js const aBook = (() => { var name = '设计模式与JS魔法锅' function getPrintName () { return '《' + name + '》' } function rename (newName) { name = newName } return { getPrintName, rename } })() ``` 看起来，模块模式就像是语言能力不足的补充。把目光从遥远的模块模式收回到 2015 年 ES6 发布之后，JavaScript 语言特征得到增强，曾风靡一时的潮词模块模式几乎从网络中销声匿迹了。现在我们可以自由地使用类封装状态， 不必再写因缺乏语义显得蹩脚的 IIFE 。 我们再来看看面向对象中的常见的装饰器模式。 假设你在维护一个开源项目，项目中有些过时的 API，你想在别人调用该 API 时提示一句“你好，此 API 将在下个版本移除”。这段代码可以这样写： ```js // 目前不支持给对象属性使用装饰器，所以这是一段伪代码 const myAPI = { @deprecate('WARN: oldAPI is decrapted, please use oldAPI_v2') oldAPI() {} } ``` 若不是[装饰器提案](https://github.com/tc39/proposal-decorators){rel=""nofollow""}的出现，我赌五毛，社区里不会有太多讨论装饰器模式的文章。不过大家若有留意过平常的代码，肯定会注意到其实高阶函数就是装饰器的具体实现。函数在 JS 中是一等公民，通过函数组合可以极其方便地仿制某些设计模式。比如，下代码中，使用“局部应用”函数仿制了一个工厂模式： ```js const Partial = (fn, ...args) => (...rest) => fn(...args, ...rest) const Adder = (a, b) => a + b const add5 = Partial(Adder, 5) add5(5) // >>> 10 add5(10) // >>> 15 ``` 我猜你想咆哮：“工厂模式根本就不是这样写的！”。哈哈，别那么固执，变通一些嘛。我们现在讨论的设计模式是去除了面向对象之后的余留物，几乎只保留了设计模式的本质，复用。换句话说，Partial 是“函数工厂”，是“生成器”，“产出” 了仍能接受一个参数的函数。 我用到了类吗？ 没有。 用到了原型吗？ 没有。 那我在写什么？ 函数。 函数，函数而已！**“函数是一等公民[5](https://lionad.art/#user-content-fn-firstclass){#user-content-fnref-firstclass ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}”**，这句话得背熟了，因为诸如“闭包”、“回调”等概念都和函数有关，~~面试经常会问道~~你迟早会用上的。若谈论设计模式脱离不开语言特征的话， 那扯上函数绝对不会有任何问题。 亲函数而远类的写法可以帮助我们消化许多种类的设计模式，我们再来看最后一种，代理模式。 ES6 原生支持代理模式。对，就是 Vue3 里的那个“Proxy”，直译为“代理器”。社区有很多讲 Vue3 原理分析的文章，肯定绕不开 Proxy，这里不再赘述了。以下展示一个使用 Proxy 拦截对象操作的小例子。 ```js /* 使用 Proxy 代理对象，禁用对象中下划线开头的属性的访问 */ const proxy = new Proxy({}, { set(target, key, value) { invariant(key, 'set') target[key] = value return true } }) function invariant(key, action) { if (key.startsWith('_')) { throw new Error(`Invalid Key`) } } proxy._prop = 'somevalue' // Error: Invalid Key ``` 若脱离 ES 6，代理模式会变成什么？ 会变成一团带有 Proxy Patterns 注释的函数，会被某个 GitHub 上的库吸收下放到 Readme 中亦或是变成社区中新增的几篇“JS 中的代理模式”的博客... 害，无所谓了。 ## 设计模式的消融 **总的来说，设计模式无非有三种作用：创建对象、组合对象以及处理对象的依赖**。面向对象设计模式所代表的复用性，只能在面向对象的上下文中使用。跳出面向对象，你会发现代码复用的层次可以更加开放，下至语言特征，上至框架。 作为抽象的最低层级，JS 语言特征，离不开日益见新的语言规范。上文总结的设计模式与语言特征的重叠之处，可以概括为以下两点： - 若语言本身孱弱时，可通过语言特征的再上层抽象，如函数，来提高复用的层次（即发明一种新的设计模式）； - 当语言逐渐强大时，设计模式的概念也随之弱化； 听起来颇有些“设计模式是对语言能力不足的补充”的味道，难道说我们要开始编程语言的圣战？这让我回想起 Paul Graham 在《黑客与画家》中描写到他对“强大语言”的赤裸裸的崇拜: > 如果你想解决一个困难的问题， :br > 关键不是你使用的语言是否强大，而是好几个因素同时发挥作用： :br > （a）使用一种强大的语言； :br > （b）为这个难题写一个真实世界中的编译器； :br > （c）或者... 你把自己变成这个难题的人肉编译器。 > :name[Paul Graham] Paul Graham 就觉得设计模式就是一种对语言能力不足的妥协，“语言的编程能力越强大，写出来的程序就越短”。当然，就算有一种语言可以强大到和破除面向对象设计模式的神话，关于语言的表达能力强弱的争论也不会停止。不过好消息是， 脱离场景谈语言一定是错误的，正如没有人会指望用汇编来编写 Web 程序。 我们没必要去追求极致的编程语言表达力，表达力和复杂度往往是正相关的，就像世界上所有的语言的法阵都会伴随着词语的演进、读音的兴替以及对错误语法的包容，但很少有人说（或敢说）“你看，白话文比起文言文来说真是不够格啊”。 脱离面向对象，我们也可以谈论设计模式，因为我们聊的就是代码复用。就算使用函数式、声明式的语言解决问题，也许有特定范式可遵循。请想象一下 CSS 中的设计模式。嗯？CSS 有设计模式么？私以为有。特异性、 继承和层叠这三种语言特征就是 CSS 的设计模式；在这三种基础特性之上建立起来的各种代码组织方案/命名方案（如 OOCSS、Atomic CSS），也算。 **唯一不变的，只有抽象的复用**。我们做的一切工作，只是在抽象出不同层次的代码复用的同时，尽可能把代码组织成容易理解的形式。重要的不是记住某个设计模式中的实体以及实体是如何通讯的，而是要理解该设计模式所代表的抽象的体量适合的场景。 ## 语言的魔法锅 > 在威尔士神话中，有一口神奇的大锅，加入特定配方熬制上一年零一天后，便能萃取出三滴解决任何难题的灵药。 > :name[《塔列辛传奇》] JavaScript 的火热日益见长，前端社区[越加活跃](https://githut.info/){rel=""nofollow""}，规范也[日益见新](https://tc39.es/ecma262/){rel=""nofollow""}。ESNeeext 已经往魔法锅中加了许多新材料，这是好事（其实我满心期待它直接把锅塞满）。新的语言特征能带来了更多的可能性，就目前而言，新特征大概率能增加语义，增强表达力、降低思维负担[6](https://lionad.art/#user-content-fn-if-one-word){#user-content-fnref-if-one-word ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。尽管把材料往大锅中塞吧[7](https://lionad.art/#user-content-fn-how-js-works){#user-content-fnref-how-js-works ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}！让我们一同祈祷萃取出灵药的一天早日到来！ 以下就用魔法锅的故事作为文章结尾，这是一个颇有意思的传奇故事。 ![炼金术 | 维基百科](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200704/20200713074400.png) 在爱尔兰一个隐秘的角落，住着一个精通智慧与魔法的巫师，凯丽杜恩（Ceridwen）。她能力超凡，偏偏却生了一个丑陋的儿子。所以这位母亲竭尽所能想将智慧传授给他，以弥补其外表的丑陋。她辗转于各种巫术与秘仪，最后， 总算在一本隐秘的魔书中找到了灵感。 魔书将秘密告诉凯丽杜恩：她需要使用一口大的魔法锅，填满红山花、小麦、火盐、精灵耳、直立根和灵尘，用大火熬制上一年零一天。最终会生成一锅致命毒物，但溅出的前三滴汁液却是充满“预言之灵”的智慧灵药。 很快，熬制魔法锅的工作在凯丽杜恩的安排下有条不紊地进行，一个名字未知的盲人被派来搅拌大锅，年轻人巴赫则负责烧它下面的火。 星象在天空中咯咯响地平移着，太阳和月亮绕着地球转了一轮又一轮... 随着时间推移，锅中的草药效力变得越来越强。看着咕嘟嘟冒着气泡的大锅，凯丽杜恩觉得很是满意，她便躺在温暖的锅边睡着了。 就在此时，意外发生了。翻腾着热气的大锅，意外地溅出了几点液体在年轻人巴赫的手指上，而巴赫居然不假思索地将手指吮吸地干干净净。和魔书的预言一样，巴赫立马就获得了智慧。他瞬间通晓了火焰的舞蹈和水的诉说， 山的尊严和风的呢喃... 他知晓了无数秘密，以及... **凯丽杜恩肯定会杀了他！** 慌乱中，巴赫变成一只野兔夺路而逃，而凯丽杜恩惊醒后赶忙变成猎犬一路追踪过去。巴赫变成天空中的鸽子，她就变成一只鹰；他变成一头奔跑的鹿，她就变成一只草原上的狼；他化身为谷仓中的一粒麦粒，她就变成一只啄个不停老母鸡... 这两人也许一直较量着，直到今天。 ## 阅读更多 - [15 年后 GoF 设计模式作者再谈设计模式](https://www.jdon.com/37356){rel=""nofollow""} - [为什么不能乱点技能树](https://www.zhihu.com/question/37009570){rel=""nofollow""} - [超越库和框架的技术创新](https://mp.weixin.qq.com/s?src=11×tamp=1651051411&ver=3764&signature=AiaMcpc*LLVNlmVWIHaOvu4sThNq8OFp8ckqlVllLSohG8dWn**P3unuBhRwZAEND0uJdnurJtHvE6IKlBYAUUwuvRYknXkKje6CzOZaQBxRPIlnN4kwtzYsfa8fxKSM&new=1){rel=""nofollow""} 希望本文能对你有所帮助，也欢迎各位批评文中观点或指出错误。 想看看这篇文章是如何被创造的？你能从我的[博客项目](https://github.com/Lionad-Morotar/blogs){rel=""nofollow""}中找到答案\~ 欢迎 Star & Follow\~ 也请大家多来我的[线上博客逛逛](https://www.lionad.art){rel=""nofollow""}，排版超 Nice 哦\~ ## Footnotes 1. 非贬义。 [↩](https://lionad.art/#user-content-fnref-%E6%96%87%E5%8C%96){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} 2. 见：[子程序（函数）考古学](https://zhuanlan.zhihu.com/p/95741316){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-fn-call){.data-footnote-backref ariaLabel="Back to reference 2" dataFootnoteBackref=""} 3. 试试使用 CSS 去写游戏？即便可行，但过程也会让人无比沮丧。 [↩](https://lionad.art/#user-content-fnref-css){.data-footnote-backref ariaLabel="Back to reference 3" dataFootnoteBackref=""} 4. 此模块模式并非传统面向对象中的模块模式，后者的定义见：{rel=""nofollow""}。 [↩](https://lionad.art/#user-content-fnref-module-pattern){.data-footnote-backref ariaLabel="Back to reference 4" dataFootnoteBackref=""} 5. 且叫且珍惜，说不定以后就听不到“一等公民”这种叫法啦。 [↩](https://lionad.art/#user-content-fnref-firstclass){.data-footnote-backref ariaLabel="Back to reference 5" dataFootnoteBackref=""} 6. 用一个单词就能达意时就不需要用一个句子。 [↩](https://lionad.art/#user-content-fnref-if-one-word){.data-footnote-backref ariaLabel="Back to reference 6" dataFootnoteBackref=""} 7. 语言特征并不总是银弹，类似观点见道格拉斯的《How JS Works》 [↩](https://lionad.art/#user-content-fnref-how-js-works){.data-footnote-backref ariaLabel="Back to reference 7" dataFootnoteBackref=""} # 🌐 Anysort：灵活、优雅的多属性排序 ## 前言 去年一月的时候，我写了一个多属性排序库 Anysort，给网易云歌单用作自定义排序。正好最近在看其它语言，突然想起 TypeScript 里也有泛型这个东西，我估摸着 TS 正好能给 Anysort 补上一些高级类型约束，于是动手完成了。 我特意回到 TS 来玩玩，结果这下惊住了我，TS 的泛型太特喵好玩了！ 那会儿我写了一篇文章介绍了 Anysort 的实现原理[1](https://lionad.art/#user-content-fn-anysort-1th){#user-content-fnref-anysort-1th ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}，但经过功能更替，代码更迭，早就不再适合阅读。此文章用作去年那篇的补充，额外会讲 Anysort 中一些高级类型的实现方法，但不会涉及基础知识。 如果看文章时有任何疑惑的地方，推荐查字典[2](https://lionad.art/#user-content-fn-dict){#user-content-fnref-dict ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ## 排序示例 首先我用例子简单说明一下 Anysort 的调用方式。现在回到二十世纪黑帮时代，警长在警察局关了一票黑帮，知道他们的姓名、年龄和做过的坏事这几个数据，想做一些排序。 ```js const gangs = [ { name: 'A', age: 33, bads: [] }, { name: 'B', age: 25, bads: ['X001'] }, { name: 'C', age: 25, bads: ['X888', 'X772'] }, { name: 'D', age: 25, bads: [] }, { name: 'E', age: 33, bads: ['X888', 'X772', 'X002'] } ] ``` 恰逢天下大赦，局长要把没做过坏事中的最年轻的那个黑帮释放，这时要对 bads 及 age 两个字段进行排序。 ```js anysort(gangs, 'bads.length', 'age') ``` ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220513170945.png) 结果很明显：应该释放 D。使用对象的点号访问方法，可以轻松访问到 bads 的长度。这是一个内置的“排序插件”，用来更改排序数据，把 bads 映射到 bads.length。除此之外，插件还可以更改排序的结果， 比方说 reverse 插件，可以使某个排序倒序显示。如果局长想枪毙掉某个做过坏事最多的黑帮分子，他需要根据 bads 的长度倒序排序。 ```js anysort(gangs, 'bads.length-reverse()') ``` ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220513171506.png) 结果很明显：应该枪毙 E。这帮黑帮分子的履历太简单了，只有姓名年龄等字段。Anysort 提供了其它的内置插件以便于对复杂的数据进行排序，还可以进行扩展，它显然能处理更复杂的排序情况。就调用方式而言，除了字符串传参，还可以使用对象语法调用。 如下所示。 ```js anysort(gangs).badsa.length.reverse() ``` 呀，恭喜你发现我打错了 bads 这个单词！不过该如何让编辑器也知道这行代码是错误的？假设局长在排序时输错了一个字母，那么得到错误排序结果后，他就有可能枪毙一个本该释放的人。不论是字符串传参，还是对象语法调用， **该如何保证类型是正确的**？编写代码时，错误调用应该报错。 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220513181638.png) 探讨 Anysort 的类型前，让我们先简单看看 Anysort 的实现。当然，实现和类型没有强关联，所以你也可以直接跳到下一小节。 ## 排序原理 ### 多属性排序 Anysort 是在 Array.prototype.sort 基础上的封装。Array.prototype.sort 接受一个比较函数，利用内置算法比较各个元素，并根据比较函数给出的结果来决定元素的排序前后顺序。比如根据年龄排序， 可以这样编写： ```js function sortByAge(gangsA, gangsB) { const ageA = gangsA.age const ageB = gangsB.age return ageA === ageB ? 0 : (ageA < ageB ? -1 : 1) } gangs.sort(sortByAge) ``` 一但涉及多个属性的排序，我们就需要编写多个类似 sortByAge 的比较函数。由于多个属性的比较有先后关系，所以我们需要一个“漏斗”来筛选出最终的排序结果。比如，在挑选无犯罪记录中最年轻的黑帮时，先按照其犯罪记录长度排序， 如果某两个黑帮成员的犯罪记录长度相等，也就意味着需要在对其年龄继续排序。有了“漏斗”filter，有再多比较函数都没关系。Anysort 的多属性排序的核心就是这个 filter 方法。 ```js const sortByAge = ({age:a}, {age:b}) => a === b ? 0 : a < b ? -1 : 1 const sortBybadsLen = ({bads:a}, {bads:b}) => a.length === b.length ? 0 : a.length < b.length ? -1 : 1 const filter = (...fns) => (a, b) => fns.reduce((res, fn) => res || fn(a, b), 0) gangs.sort(filter(sortByAge, sortBybadsLen)) ``` ### 对象的点号访问 刚才提到，插件可以改变排序的结果，也能改变排序数据。类似从数据 gangsA 到 gangsA.bads.length 的变幻，就是使用内置插件 walk 实现的。它是一个简单递归函数。 ```js /** * @example * walk('a.b')({a:{b:3}}) === 3 */ const walk = pathsStr => x => { const paths = pathsStr.split('.') let val = x let nextPath = null while (val && paths.length) { nextPath = paths.shift() val = val[nextPath] } return val } ``` 当读取到 'a.b-reverse()'，首先根据中横线将指令划分为 walk('a.b') 和 reverse() 两个插件，分别生成比较函数；之后，把这两个比较函数传入 filter， 返回可用于 Array.prototype.sort 的最终结果（一个新的比较函数）。这就是 Anysort 的整个流程。可以看作以下代码： ```js anysort(arr, 'a.b-reverse()') // 可以看作 arr.sort(filter([ generatePlugin(walk('a.b')), generatePlugin(reverse()) ])) ``` ### 对象形式调用 gangs.a.b.reverse() 这种对象形式调用的核心实现是 Proxy 的链式调用：gangs.a.b.reverse() 先后访问了三个属性：a、b、reverse，这三个属性都由同一个 Proxy 对象提供。 ```js const anysort => xs => wrapped(xs) const wrapped = xs => { let proxy = null const visited = [] return (proxy = new Proxy(arr, { get (target, prop) { if (prop === 'reverse') { return // ... } visited.push(prop) return proxy } })) } ``` 访问 proxy.a，把 'a' 放到 visited 中，返回 proxy；访问 proxy.b，把 'b' 放到 visited 中，返回 proxy... 这样就能无限层级访问对象路径了。直到访问到某个插件， 这时就可以把已访问的路径 ['a', 'b'] 作为参数带入，这时就不再返回 proxy，而是返回排序结果。 ## 类型实现 ### 从对象获得可行路径 显然，你可以给排序函数传任意格式数据，而极端情况只有两个：在 [1,2,3] 排序时使用 'length' 排序是错误的；给 \[\[1],2,3] 排序使用 'length' 确情有可原（正确的）。 根据这两个极端情况，我们设定的目标是，根据传入数据的类型生成一个有限的字符串字面量集合，这个集合包含所有可能的正确输入。只要传入的字符串字面量参数不在这个集合中，编辑器自然会报错。假设有[以下代码](https://www.typescriptlang.org/play?#code/GYVwdgxgLglg9mABAQzATwM5wE5QDwCCASkQHwAUy22AXIsUQDSIZS2IDKbMYA5gGrIANjAAmAdRhQAFoRKkAlIgDeiAPQAqRADpdiDWsQBfAFAmoaAA4BTTtz6CREqbIalEAXkQByZN8QAPj4ARt5maoYA8gDSJqiYOFDkANoAusy+3gomEYgxcehYuCnpIVk5hgDu2Ai8BQnFaRlwMtbY5WZAA){rel=""nofollow""}，StringValidWith(ARR) 类型为 'a' | 'b'，那么只有 'a' 或 'b' 两种调用是正确的，其它调用都应该报红。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220513201932.png) 所以，StringValidWith 需要遍历 ARR，并返回所有可行路径： ```js const data = [{a:{b:{c:{d:1}}}}] // 'a'|'a.b'|'a.b.c'|'a.b.c.d' StringValidWith ``` 实现[见下 GetPath 类型](https://www.typescriptlang.org/play?#code/C4TwDgpgBA4hwAUCGwAWAeAUFKAVKEAHsBAHYAmAzlAPYBGAVhAMbAA02UA0gcWVVADWEEDQBmeKAF4hI8XkwA+aZx5ESFapWAAnAJakA5pwD8eANpcAurw0D6TVqagADACQBvLgF8XUAD6unj4AdJ5wiCgYuJZWir6cAFxBXgk4yQDkGZiYoJBQJNoA+gCM0rDwyGjoHkiJHnT1zPXkiaQArgC2dBA63v3eikA){rel=""nofollow""}，它也是一个简单的递归函数。它从对象中获取所有的键，返回这些键。一但键对应的值还是对象，则进入值对象的递归。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220513203605.png) 为了支持访问数组和字符串的 length 属性，我们对 GetPath 进行一些改造，[见下](https://www.typescriptlang.org/play?#code/C4TwDgpgBA4hwAUCGwAWAeAUFKAVKEAHsBAHYAmAzlAPYBGAVhAMbAA02UA0gcWVVADWEEDQBmeKAF4hI8XkwA+aZx5ESFapWAAnAJakA5pwD8eANpcAurw0CAFElIhzNgD5Rt+owEpTUAAMAEgBvLgBfAKgPYLDwgDoAGzJDNADOAC4La1t+anomVn9YiKiY0Ij40LhEFAxcSytFSMzAipacLIByLsxMUEgoHSQAd1xwaBkQpAyQulnmWc5yLNIAVwBbOggdV04Ibohe8JPwvoHoEm1pWHhkNHRhsYnFIA){rel=""nofollow""}。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220513204741.png) ### 从数组推断子元素类型 由于传入的是数组，数组内部的元素类型不一定是同一种，所以要先从数组中获取子元素类型，再把子元素类型传给 GetPath 以获得所有路径。[见下](https://www.typescriptlang.org/play?#code/C4TwDgpgBA4hwElgQLYBVwQDwA0DKUEAHsgHYAmAzlAK6kDWpA9gO6kDaAugHxQC8AKChR8hEhArUAFAEtSAMwgAnKElQZIASi5CoAflXJ0mXQC4opCADdlAgaEhQlAQxYbofKOwDeUZ+dIaFAAjZS4oAF8AGl9g80pgJTkAc3CIzjtMuwdoZASAJVd3flh4NWNILBc3TG4gA){rel=""nofollow""}，一个灵活的 infer 就可以把类数组中所有子元素类型以集合的形式推断出来。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220515154134.png) GetItemType 中的 infer 在这里是有坑的，把子元素类型以集合的形式推断出来，也就意味着抹平顺序差异。传入的元组可以是顺序相关的，但返回的集合却顺序无关。[见下代码](https://www.typescriptlang.org/play?#code/C4TwDgpgBA4hwElgQLYBVwQDwA0DKUEAHsgHYAmAzlAK6kDWpA9gO6kDaAugHxQC8AKChR8hEhArUAFAEtSAMwgAnKElQZIASi5CoAflXJ0mXQC4opCADdlAgQBt4UZJWABGc+zcAaKACZOfigvXwC7Oxd3IPY-UM47AHoE-ygAHyg3AVBIZwhXNDyovlh4NWNILGyIJnlc1zduIA){rel=""nofollow""}，从元组类型的 test1 中推断出子元素类型为 1 | 2 集合。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220515154908.png) 不过在排序中，待排序数组和顺序不相关，所以我们可以使用这个 infer。由于待排序数组的内部的元素类型大致是一致的，所以也并不需要过分关心这里及之后的性能损耗。把数组子类型这个集合转为元组后，计算出所有对象的可行路径，按照步骤，简单可行。 集合转元组，应算是 TypeScript 中一个有名的黑魔法操作。Github 能搜到很多相关讨论，比如 [*union to tuple*](https://github.com/microsoft/TypeScript/issues/13298){rel=""nofollow""}，详细讨论了集合转元组的可行性以及相关实践建议。这里我直接把代码搬过来，[如下](https://www.typescriptlang.org/play?#code/C4TwDgpgBAqgdgSwPZwCpIJJ2BATgZwgGNhk4AeGAPigF4AoKKAChiggA8c4ATfWKAH4WzANYAuFh0kwAlHRoA3JAh7zaSlWqiS4ERXnmdufRiIlQEcAGZ4oGdZtXzhGHVD0Hc9eqEixEFAAZAEN8YEoaBiZ4MnQsHAJiUhRI9i4IXn5mZmlLGzsAJUcoZWcoM2FCs119PB8-aFiUdFQAVzAAGwhyVCizAG1UAF10k34BzzxhyqgBmaZJAYA6Vea0JHaunoBRDiJOtp4e1AAaALJQ8N6qW-P1q4i+mYbwaBxwuguWzY7u8gA5CEAVAAD5QAEAIxB4IBRABVCAA){rel=""nofollow""}，先用 UnionToIntersection 把集合 1|2 转换成对应的函数交集类型 ((x: 1) => void) & ((x: 2) => void)，再使用 UnionLast 把参数类型逐个推断出来就好[3](https://lionad.art/#user-content-fn-union_to_tuple){#user-content-fnref-union_to_tuple ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220515161832.png) 为什么要在 Anysort 中使用黑魔法，这不是这篇文章想要讨论的话题。我们回到正题，改造 GetPath，添加内置插件类型，然后添加类型 GetPaths 便于处理元组。[见下](https://www.typescriptlang.org/play?#code/C4TwDgpgBAQgrgSwDYBMCSA7ACkuBzBDAZygF4oByAJwgDcIqiIKoAfSsXAjCgKF9CQoAcQjAsAQ2AALIgB4AGgGUoEAB7AIGFCTgYA1hgD2AdwwBtALoA+MryhRlqjVp1RzhAGYMoACQgSKAA0UAB04V4+AEoQRMCW9lAA-CJikjJy-oFQAGRQRgBGAFYQAMbAtuyi4lKycjFx1okAXFAYdAz8gtDVaJoAtgAq4BCKKuqa2roGxmZWtqSJThOuJAAUkVRQfRBDIwCUVokpO3uQLW0dVF0jUFQSJsNC5OYA3okSrRhw-QUMRwBfILvBwFVpxKiEPCAhICW6aOJRB5PaDkACqGAQRgwgyMgzgnFGvQGKLk90eI2sTX4NyECOAZFSNRk8npSIpkGpNO6TPS0jkiUGzkmbkKJXKQUSAGlhasoPoICAjJ4oELyAqlSrBrwFtLZVMoBCocdVeYpZZ9W41hIMCArGxDcBIRg8PsTQADAAkrylAPdDq9PoBoSQWjwMn97EDvoAtN74Mh0NguIQiH6A97fSGwzI468E6hMDh8Km-RdBmaLSsDWKysAPZn01HG6FvdU+XIK+brE2oNGAXmC0ni9w0+6Lv3xw5WhQ+HChBisTijJhNIw60u5GjdQ41mjLSR9yk1mt9K01mpWmj9mRbLQjAgUDfSHeH0+oF8rjfqzpEiez1AmzbM+r6PjeJwfpc9DXPO0CLtiAAyEhxFuO5QPBy6rgwTDlJu24HlAJ6XoBGDeFsUQgVA95gVAJpRBc7TQbScGYtiuL4oSnZoeYgxVi4BrmIxDAJA4KRHNO7jhKEGHsQSoZyAAomopS4CgoyDCEGFIShgxUtYmmsRg2nAFxlhAA){rel=""nofollow""}，假使我们有了插件 reverse 和 plugin，那么无论是传入 'a-reverse' 还是 'a.length-plugin' 都应该是正确的调用。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220515163145.png) ### 代理的类型 最后讲一讲对象形式调用的类型实现。假如有子元素类型 {a:1}，希望得到 { a:{ reverse() } }。有了 GetPath 的递归基础上，改造其实非常简单。[见下代码](https://www.typescriptlang.org/play?#code/C4TwDgpgBACgNgVwOYEsB2BhAhnOBnAHgEEAlEgPigF4oBvAKCigAsJcB7KACgEoAuKKRL0AvvXqhIUAOIRgMLMGYFGgslAgAPYBDQATPFARoA1mnYB3NAG0AugBpVAFWpqS1gAy36lGgybWANJQ6FAmECDsAGZQTrZ8qkxOQbYa2roGUOwARgBWEADGwIlQAPwycgpKxGT2sSmUAGSwiKiYOPg1FCUCyYGpzfDI6Ni4hELkolCDrSMd42ST9FHGRSjsaFBYaCB47ABOwF1pOvqGxmaWNrbkXJp4AkI8dKr7cgj7m-db56bmVj8KvJFMoJqJ6NtdgdgFxrLQsHwAORYREiWw8AB0WAxzCAA){rel=""nofollow""}，PluginsCalls 是一个根据现有插件返回固定的函数接口对象的类型，GetPath 只需要不断递归对象的键值对，并把值与函数接口的交集返回即可。这样一来，就有了在任意属性调用任意插件的类型能力。 ![TS Playground Example](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20220515170506.png) ## 阅读更多 总结一下，无论是字符串形式的调用还是对象形式的调用，在 Anysort 的类型中的实现都主要依赖了递归类型。文章前两部分简述了其原理。但文章中的代码只是一种最简的还原。比如，没有任何容错，也不支持扩展。Anysort 不仅有内置插件， 它还支持插件扩展。这些插件的调用有些需要传参，另一些则不需要... 如何约束诸如之类的调用方式，或仅确保其不会出错，就需要引入一堆不相关代码。在 Anysort 完成时，我惊讶地发现，光是类型代码就占用了 10KB 体积。我的第一感觉就是“ 这是不可接受的”。 排除类型体操的可玩性，TS 在我看来是非常不适合前端来写的，至少是不适合在项目中普及的。JavaScript 是一种简单有效的脚本语言，使用 JS 意味着我尽可能希望在保证代码质量底线的情况下，更快速地完成项目， 而不是每天写代码却要花上一半的时间来设计类型。类型系统，包括项目中的代码类型以及类型系统本身都只会越来越复杂，TS 使许多程序员陷入了“即使是编写简单的页面，也需要用类型来保证质量，或是它可以给维护者带来好处”的误区。 这可能是一种有效的自我安慰或管理手段。 更多吐槽 TS 的话就不说了。但如果你对类型体操有兴趣，可以去 [type-challenges](https://github.com/type-challenges/type-challenges){rel=""nofollow""} 这个项目看看。它搜罗了百来道 TS 类型编程的题目，从易到难都有，而且大部分题目都有很好的解答。这是提高 TS 泛型能力非常有效的一条路子。 最后，哪怕你对 Anysort 有一丝兴趣，欢迎参观 [Anysort@GitHub](https://github.com/Lionad-Morotar/anysort){rel=""nofollow""}。项目是半个玩具，还有很多不完善的地方，欢迎 PR。 ## Footnotes 1. [《一文学会排序》](https://lionad.art/_achieved/2021-01/anysort-1th) [↩](https://lionad.art/#user-content-fnref-anysort-1th){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} 2. [《一份不可多得的 TS 学习指南》](https://juejin.cn/post/6872111128135073806){rel=""nofollow""} [↩](https://lionad.art/#user-content-fnref-dict){.data-footnote-backref ariaLabel="Back to reference 2" dataFootnoteBackref=""} 3. 有关集合转元组的详细中文解释见[《TypeScript 奇技淫巧 union to tuple》](https://zhuanlan.zhihu.com/p/58704376){rel=""nofollow""}。 [↩](https://lionad.art/#user-content-fnref-union_to_tuple){.data-footnote-backref ariaLabel="Back to reference 3" dataFootnoteBackref=""} # 💫 CSS 幻术 | 抗锯齿 ## 前言 传统网页的呈现是基于像素单位的，所以图片不能和 SVG 一样进行任意尺寸缩放后还保持边缘平整。也就是说，放大像素逻辑的图片，必然导致可视质量下降（信息失真）。所以我们往往会使用技术手段去规避失真，如： - 使用 SVG 替换位图 - 使用矢量字体（如 TrueType 字体）替换位图字体 如果不得已，被迫进行像素操作，我们也有多种手段用来矫正失真： - 使用 CSS Image-Rendering 属性调整图像缩放时的采样算法 - 使用 CSS Font-Smoothing 属性平滑字体渲染 - 绘图时使用 Canvas 的抗锯齿 API - 将元素尺寸放大，然后再使用 Transform 将布局尺寸还原 - 某些特殊情况下，可以使用浏览器硬件加速来平滑锯齿 - ~~将图片模糊处理迫使用户开启钛合金脑放~~ 这篇文章将会简单的提及以上几点，并介绍一种通过 CSS BackgroundImage 抗锯齿的全新思路（我称之为 Pixel-Offset Anti-Aliasing）。要提前说明的是，当下手机的屏幕分辨率已经相当高， 同时处理器性能却十分薄弱，这直接导致我们没有在手机端浏览器讨论抗锯齿的必要。本文所述几乎都局限于桌面端的大显示器（我祈祷你不是在用 8K 分辨率的显示器看这篇博客）。 ## 抗锯齿及相关技术 ### 抗锯齿的形成 信息失真（Aliasing）和图像锯齿不是一码事儿，但是对于游戏玩家来说，几乎可以把两者划上等号。要使用 CSS 抗锯齿，我们不得不先提及锯齿的形成。 **为什么会有锯齿？** 我们的眼睛能对物体的形状进行感知，意识到到一条实际上并不存在的“线条”。见下图，我们能感受到线条，虽然看起来不太平整： ![Aliasing](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/Aliasing.png) 下面这幅图中，带箭头的线代表我们感知的线段，其余线段相交的网格代表像素网格。从上图可以发现，只要是带箭头的线经过的地方，就会被黄颜色填充。不过理想中的线段是完美的，它完全平滑的。把不定方向的平滑线段，映射到像素排列的低 DPI 的屏幕上， 就会出现信息丢失的情况。像素颗粒越大，信息丢失情况就越严重（以下就简称为锯齿）。 ![Aliasing-LineDirection](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/Aliasing-LineDirection.png) **怎么样看起来才没有锯齿？** 这里我画了一张图，可以先仔细观察，然后再站在离显示器稍微远一些的地方**眯起眼睛**看： ![AntiAliasingPaint](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/AntiAliasingPaint.png) 在像素周围，我用黄色涂鸦将丢失的信息稍加补充。图中黄色涂鸦的大小代表了像素透明度。这里有一张抗锯齿的成品图片，可以看处图形的边缘被填充了有透明度的像素： ![AntiAliasingPic](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/AntiAliasingPic.png) ### 常见抗锯齿技术 在音频领域，我们可以通过高质量的播放器和无损音频减少传入耳朵的信息失真。但在游戏领域，普通玩家不可能在家里准备了 8K 显示器。伴随显示器分辨率从 720p 到 1080p 发展的，是几种同样跟随游戏业界发展而成长起来的抗锯齿技术。 - SSAA（Super Sampling Anti-Aliasing） 超级采样抗锯齿，它会把当前画面渲染的分辨率成倍提高，比如 1024×768 的图形开启 2 倍 SSAA 后，显卡实际运算就变成了 2048×1536，这之后，再降采样，将多个像素融合，映射回显示器的单个像素。像素融合能使颜色过渡更自然， 看起来没有明显的毛刺。不过，因为硬件的运算增加（指数级），可以想象它会消耗极高的性能。 - MSAA（Multi Sampling Anti-Aliasing） 多重采样抗锯齿，它针对特定缓存区域的数据进行多重采样——可以简单理解为对多边形的边缘进行多重采样。性能消耗较高，但效果也不错。 - FXAA（Fast Approximate Anti-Aliasing） 快速近似抗锯齿，它找到画面中所有图形的边缘并进行平滑处理。尽管很多图形边缘并不对应游戏实际建模的边缘（如材质和纹理），但 FXAA 性能消耗小，性价比高，不失为一种抗锯齿的常用选择。 - DLSS（Deep Learning Super Sampling） 深度学习超级采样，它通过硬件加速的深度学习算法，根据几何、着色、时域多个方面的数据（说人话就是根据过往帧、形状、像素动量等数据）对实时渲染的低分辨率图像重建多倍超级采样结果。相对于传统渲染，不仅能极大提高画质，还能极大提高帧率。 --- ## CSS 抗锯齿技术 以下，我们提及几种常见的抗锯齿技术。 ### CSS Font-Smoothing 字体平滑属性属于早期的 CSS 规范，后来因为种种原因又被移除了。不过现在仍可以通过前缀属性兼容（如 `-webkit-font-smoothing`）。一般来说，字体平滑有三个值可选，`none`、 `subpixel-antialiased`、`antialiased`。值的作用正如其名，分别是无抗锯齿，亚像素级抗锯齿和（全像素）抗锯齿。 一般来说，屏幕上的每一个像素点，都是由三原色条纹（可能如红、绿、蓝三个发光点）组合而成。亚像素级抗锯齿，意味着字体渲染时，将以亚像素（如红光）为单位。不发光的像素显示黑色，其余像素在抗锯齿处理时则会显示暗色，见下图： ![亚像素抗锯齿的小写字母“e”](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/subpixels.jpg) 全像素抗锯齿，则以整颗像素（包含红蓝绿三个条纹）为单位渲染字体。抗锯齿处理时，字体若超出了一个像素的单位，会以一颗与之相邻的透明暗色像素作平滑，见下图： ![抗锯齿后的“后浪”中的“后”字](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/fullpixels.jpg) “后浪”的“后”字，中间那一横，实际的宽度要小于一个像素，所以也用透明暗色渲染。除了单字，在 [@MAXVOLTAR](http://maxvoltar.com/archive/-WebKit-font-smoothing){rel=""nofollow""} 这篇博客，有英文排版的示例图片，以下直接引用了： - none :br![font-smooth-none](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/font-smooth-none.png) - subpixel-antialiased :br![font-smooth-subpixel](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/font-smooth-subpixel.png) - antiliasing :br![font-smooth-antiliasing](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/font-smooth-antiliasing.png) **那三种值应该如何选择呢？** 我的建议是，仅仅了解渲染机制和呈现方式就行。**像素抗锯齿会使字体呈现稍细，而亚像素级抗锯齿则使字体呈现过粗。黑色背景下则反之**。倒不必因为知道它就必须使用上——这三种方式有各自的优点和缺陷。一般来说，扔掉这个属性， 让浏览器自行判断字体渲染的方式就可以了。如果你引入了特殊字体（比如印刷字体）进行平滑处理。（我相信中文的网页版面下，能自由发挥的范围应该很有限。） 附，感兴趣的话，文末我留了相关链接，可以再查阅。 ### CSS Image-Rendering Image-Rendering 属性用于设置图像缩放算法，这个属性有几种常见的值。见下组件： ::article-a200604-image-render-property 可以发现，Pixelated 值设置之后，浏览器不会对边缘进行平滑处理，而 Auto 则对整幅图像进行柔和处理。也就是说，使用 Transform Scale 放大图片，浏览器会应用默认的平滑缩放算法（可能是双线性插值之类的）。 :::article-a200604-image-render --- :value: "['auto', 'pixelated']" process: scale property: image-rendering src: https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200319/2020-03-19-15-39-43.png --- 那可不可以对图片先放大数倍，再缩小还原为实际尺寸呢？以下是试验结果： ::::article-a200604-image-render --- compare: true :value: |- [ { value: 'auto', title: 'Auto, Normal' }, { value: 'auto', title: 'Auto, Scale(100) Scale(0.01)' } ] process: enlarge-and-shrink property: image-rendering src: https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200319/2020-03-19-15-39-43.png --- 如果你不能运行上面那个组件的话，这里有 GIF 效果： ![Scale](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/Scale.gif) 不知道是浏览器对多个 Scale 串联进行了优化，还是使用了某种不损失图像信息的采样算法，总之**不改变图片尺寸又想使用平滑图片是行不通的**。 ### 硬件加速抗锯齿 关于使用浏览器的硬件加速抗锯齿功能，是我在试验 PXAA 时的偶得（不过已经有博客介绍过了）。当元素通过 Transform\:Rotate 旋转之后，如果此元素是被 GPU 渲染的，那么会应用浏览器对应 GPU 的抗锯齿属性—— 比方说你用 GTX 1060ti 运行浏览器，那么相关配置就能在英伟达控制面板中找到（不过这有相当程度是我的猜测，待验证）。听起来好像有点复杂，看下面例子就一目了然了： :::::article-a200604-gpu 如果你不能运行上面那个组件的话，这里有图片效果： ![Rotate\&GPU](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/Rotate\&GPU.gif) 当元素旋转，并应用硬件加速（TranslateZ）之后，渲染出来的边缘会被平滑处理。但是如果**仅仅启用硬件加速或是单使用旋转，不能达到效果**。经过我的测试，在 Windows 端 Chrome 内核的浏览器， 这种抗锯齿方式能得到一些体验——你甚至可以通过仅旋转 0.1° 来柔和边缘（虽然不明显）。 CSS 相关的抗锯齿技术就到此为止，下一节开始是新的思路。 ## Pixel-Offset Anti-Aliasing 像素偏移抗锯齿（下简称 POAA），这是一种很神奇的方法，貌似网上还没人分享过，不过效果确实挺惊艳的。我不知道具体原理是什么，但是它就是有效（It works!）。这里有两副使用 BackgroundImage 属性绘制的图像， 我先展示一下应用 POAA 后的结果吧： #### 效果展示 ::::::article-a200604-offset 如果上面那些组件不能运行的话，我准备了张 GIF 图片： ![POAA-1](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/POAA-1.gif) #### 原理 常见的游戏抗锯齿技术是建立在游戏渲染前或后，从模型到光照多个步骤产生的数据的基础上的，所以我们可以根据帧历史的内容、像素动量、提高采样等方法中进行筛选信息并重建画面。但浏览器给用户展现的内容，可以说就是渲染后的东西。 我们能够参与浏览器内部渲染的方式貌似几乎没有（以后可能会有 CSS Houdini）。比方说使用 BackgroundImage 绘图展现在你的屏幕上的这些像素，你无法参与渲染改变它们，你也没有办法用预渲染数据告诉浏览器“你应该这样做”。 不过好消息是，程序员都是坚信任何问题都能被解决的人，这里我们换种思路。 我想你应该记得开篇我们提及过 FXAA。FXAA 可以简单概括为边缘寻找->重建边缘这两个步骤（并不专业，也许还会有矫正之类的我不清楚）。在[Implementing FXAA](http://blog.simonrodriguez.fr/articles/30-07-2016_implementing_fxaa.html){rel=""nofollow""}这篇博客中，解释了 FXAA 具体是如何运作的。对于一个已经被找到的图形边缘，经过 FXAA 处理后会变成这样，见下两幅图： ![RawImage](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/exp1.png) ![After FXAA](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/exp2.png) 给 FXAA 输入源图像，就能通过颜色或对比度确认物体的边缘，并通过改变像素周围的点的透明度，让整体看起来得到平滑。仔细想想，使用 BackgroundImage 绘图时，其实我们已经知道边缘在哪儿了。边缘不藏在国王的帽子里， 它就在我们写的代码中。比方，上一小节那个圆形渐变图形的源码是这样的： ![Radial](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/Radial.png) ```scss .circle-con { $c1: #cd3f4f; $c2: #e6a964; position: relative; height: 300px; background-image: repeating-radial-gradient( circle at 0% 50%, $c1 0, $c2 50px ); } ``` 我们可以轻易找到找到边缘——对，就是那些渐变的颜色改变的地方——0px(50px)。现在我们有了边缘信息，接着就要重建边缘。重建边缘也许可以再拆分，分为以下几个步骤： - 需要通过某种方法得到透明度的点 - 这些点需要能够组成线段 - 线段完全吻合我们的 BackgroundImage - 使线段覆盖在 BackgroundImage 的上一层以应用我们的修改 这就是大体思路，我们并没有参与浏览器的渲染，而是通过像 FXAA 一样的后处理的方法。在已渲染的图像上做文章。不过将上述步骤仔细考虑后，会发现问题的难点在于如何生成抗锯齿条纹。 ![AntiAliasingPaint](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/AntiAliasingPaint.png) 总之，我们需要继续改良思路。 在 BackgroundImage 中，像素是基本单位不能再分，点的透明度显然不能通过点的大小来模拟。这里有两种解决方法： - Opacity，使用 CSS Opacity ，或者 CSS RGBA 函数、SCSS 函数。 - 两种颜色相融合模拟像素透明度，如果不想扯上 JS，SCSS 也能解决。 至于线段，也可以用 BackgroundImage 模拟，比如针对上面那段 CSS 代码，可以通过改写成以下方式： ```scss .circle-con { $c1: #cd3f4f; $c2: #e6a964; $line-width: 1px; position: relative; height: 300px; background-image: repeating-radial-gradient( circle at 0% 50%, $c1 0, transparent calc($line-width), transparent calc(50px - $line-width), $c2 50px ); } ``` 取得线段之后，将容器偏移几个单位像素，放到浏览器测试结果： ![Line1](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/Line1.png) 可以发现，会自然而然得到颜色混合透明度组成的线段。只不过透明度的方向并不是我们想要的。我希望能够得到透明线条反过来的图样： ![Line2](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/Line2.png) 经过试验，我发现只需简单调换颜色的顺序就行。比方说这是在容器 50% 的位置绘制的一条线段： ![yr1](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/yr1.png) ```scss .old { background: linear-gradient( var(--deg), transparent, transparent calc(50% - var(--line-width)), yellow 50%, red 50%, transparent calc(50% + var(--line-width)), transparent ); } ``` 如果将线段颜色调换，就会变成： ![ry1](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/ry1.png) ```scss .new { background: linear-gradient( var(--deg), transparent, transparent calc(50% - var(--line-width)), red 50%, yellow 50%, transparent calc(50% + var(--line-width)), transparent ); } ``` 得到了我们想要的线段虚化的效果！这之后要做的事儿是吻合线条。 接下来是见证奇迹的时刻： ![AntiAliasingLine](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/AntiAliasingLine.gif) Well done! 来一张成品 GIF，稍微离屏幕远一些看效果最好： ![POAA-2](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200604/POAA-2.gif) 成品在吻合线条的基础上还增加了一些内容及调整了相关参数： - 暗色和亮色混合的透明度的值不同 - X 轴和 Y 轴的偏移不同 - 调整了拟合线段的粗细 成品的代码如下： ```scss .repeat-con { --c1: #cd3f4f; --c2: #e6a964; --c3: #5996cc; position: relative; height: 300px; background-image: repeating-linear-gradient( var(--deg), var(--c1), var(--c1) 10px, var(--c2) 10px, var(--c2) 40px, var(--c1) 40px, var(--c1) 50px, var(--c3) 50px, var(--c3) 80px ); &.antialiasing { &::after { --offsetX: 0.4px; --offsetY: -0.1px; --dark-alpha: 0.3; --light-alpha: 0.6; --line-width: 0.6px; content: ''; position: absolute; top: var(--offsetY); left: var(--offsetX); width: 100%; height: 100%; opacity: 0.5; background-image: repeating-linear-gradient( var(--deg), var(--c3), transparent calc(0px + var(--line-width)), transparent calc(10px - var(--line-width)), var(--c2) 10px, var(--c1) 10px, transparent calc(10px + var(--line-width)), transparent calc(40px - var(--line-width)), var(--c1) 40px, var(--c2) 40px, transparent calc(40px + var(--line-width)), transparent calc(50px - var(--line-width)), var(--c3) 50px, var(--c1) 50px, transparent calc(50px + var(--line-width)), transparent calc(80px - var(--line-width)), var(--c1) 80px ); } } } ``` 理论上，通过 SCSS 函数，能自动判断代码中线段的位置并生成填充抗锯齿的像素。无论是 LinearGradient、ConicGradient 还是 RadialGradient，都可以抗锯齿。不过我只是当试验品来写， 所以没有写相应的工具函数。欢迎各位补充到 GitHub。 ## 实践&后记 在家闲着无事上 CodePen 玩耍时，看大触们用 BackgroundImage 画画，虽然好看，但狗牙令人心塞。于是起了尝试做一个抗锯齿 Demo 的想法（果然好康才是源动力）。 本来这玩意儿会变成一个代码片段（类似 Gists，反正就是不那么重要的东西），但是前天看到掘金推荐的文章中有网友用 BackgroundImage 画优惠券的小圆圈缺角，这给了我启发，直接催生了《CSS 幻术》这篇博客。 关于具体应用场景我必须说明清楚，POAA 只适用于低分辨率的显示器（严格来说是看 DPI，也就是分辨率和尺寸之比。就像我用的 2K 显示器，但是因为尺寸较大，所以能通过 POAA 取得效果），自然就排除了苹果电脑或者手机这些设备。 POAA 只能作为一种技术补充，由于并不方便作实践的选择，所以我称之“幻术”。如果你需要在生产环境用浏览器绘图，那么肯定会选择优先使用 SVG 和 Canvas。选择 BackgroundImage 绘图，在我的印象里， 只在需要追求时间和简便的情况下才会发生（就比如画优惠券）。这使得 BackgroundImage 地位尴尬，像是成了开发人员不会 SVG 时选择的替代品。不过... SVG 不应该是设计人员掌握的东西么？所以图形到底应该由谁来画，我不懂。 最后，推荐大家来我的博客逛逛，在[我的博客](http://www.lionad.art){rel=""nofollow""}里你可以通过操纵杆和控制台亲自体验 POAA 的神奇之处。 啊，写这篇文章我起码喝了 3 瓶肥宅快乐水。我肯定又变肥宅了哭。都看到这里了，不点赞三连安慰我一下再走么？**/(ㄒ o ㄒ)/\~\~** ## 彩蛋：~~脑放~~ 好吧，这里想介绍的不是“纯脑放”，而是一种先将图片变模糊以平滑图形边缘，再锐化图片强化边缘的思路。日常生活中使用 Photoshop 等工具处理图片经常会用到这种方法；有时电脑游戏画面增强也是这样处理的。 先模糊，再锐化，两个步骤不能反过来，同时参数的调节也很重要（很玄学）。我在自己的博客中进行实验时，以下是我的尝试的方法： - CSS Filter 串联 SVG 自定义滤镜 - CSS Filter 串联 Blur 和 Constract 滤镜 不过很遗憾，水平有限，始终没能调出想要的效果，所以直接结案了，下一题。 :::::::article-a200604-blur ## 阅读更多 希望本文能对你有所帮助，如果文中出现了不流畅或理解错误的地方也麻烦各位评论指出。 :jj 若有任何疑问，或想深入探讨，可以给我发邮件：dGFuZ25hZEBxcS5jb20= - [DLSS 2.0-基于深度学习的实时渲染图像重建](https://zhuanlan.zhihu.com/p/123642175){rel=""nofollow""} - [Please Stop “Fixing” Font Smoothing](https://usabilitypost.com/2012/11/05/stop-fixing-font-smoothing/){rel=""nofollow""} - [用 CSS 开启硬件加速来提高网站性能](https://www.cnblogs.com/ranyonsue/p/8296983){rel=""nofollow""} - [Implementing FXAA](http://blog.simonrodriguez.fr/articles/30-07-2016_implementing_fxaa){rel=""nofollow""} ::::::: :::::: ::::: :::: ::: :: # ❓ 用纯CSS判断鼠标进入的方向 ## 升级版 CSS 判断鼠标进入方向 正直的勇者们经历远航，一路横扫除魔，终于来到了魔王（指面试官）所在的石塔。勇者们在石塔前的守夜人陈大鱼头（此处@陈大鱼头）那里接受了一个挑战——用纯 CSS 难度判断鼠标进入盒子的方向。 陈大鱼头：“勇者留步，进入石塔前，请先使用这个挑战练练手吧！” 在给定初始 HTML 结构下，编写代码，完成下图功能： ![ CSS 判断鼠标进入方向](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/56-49.gif) 勇者 A：“害，这还不简单...” 勇者 A 给四个盒子分别定位到上下左右四个方向，并利用其 Hover 状态制作动画，三下五除二[完成了挑战](https://juejin.im/post/5ea8f15ee51d454dc55c8e5b){rel=""nofollow""}。 勇者们解决了难题，正痛快着。经过一路试炼（指金三银四中各种轰炸），似乎没有什么能阻挡他讨伐魔王的步伐。他们满怀自信步入石塔内部。 然后，傻眼了。 魔王：“勇者们，没有解决这个难题前，我金身！”。（指勇者们不得不屈服于面试官百般刁难的规则。） **魔王微微一笑，道：“HTML + CSS，我也不给初始代码了，你想写啥都行，反正实现下面这玩意儿吧”。** :br ### 图片效果 ![升级版 CSS 判断鼠标进入方向](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/YReNvaaHms.gif) ### 实现 ::article-a200429-face 这是一条手动分割线，以下是解析。 --- ## 解析 主要思路就是利用选择器将和鼠标产生互动的盒子选择到我们想要触发效果的盒子上，附加动画属性。 不过，经过一番搜索之后，发现现实与理想还是有点差距的。 **CSS 没有父选择器** 我百度出来各种说法，说是父选择器的性能较差，没有浏览器厂商愿意做，所以父级选择器相关标准被推迟了。 不过我相信用一些比较奇怪（♂）的方法，可以伪造一个“父级选择器”出来。 首先想到的是，也许可以某种表单相关的盒子，再结合 CSS 属性选择器，达到选中对应元素的效果，就像是 :checked 选择器那样。结果一番操作后发现，没有能达到要求的这种东西。 表单 Form 元素倒是可以通过当子组件处于 :focus 状态时，标记其自身为 :focus-within 状态。不过有个问题，它不能告诉我们到底是哪个子组件处于 :focus ， 这样的话我们就不知道上下左右到底是哪个盒子和鼠标发生了互动。 又经过一番思索及尝试后，我选择了[通用兄弟选择器](https://developer.mozilla.org/zh-CN/docs/Web/CSS/General_sibling_combinator){rel=""nofollow""}（这里不介绍选择器具体作用了，不知道的同学直接点链接去看 MDN）。下面直接讲代码结构。 HTML 如下： ```html
    ``` 在守夜人陈大鱼头那里，勇者们使用了四个 .block\_hoverer 类标签与鼠标交互。 ![CSS 判断鼠标进入方向鼠标交互](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/06-47.png) 魔王这里则需要多一些，如下图红色区域，每一个矩形都是一个与鼠标交互的盒子： ![升级版 CSS 判断鼠标进入方向鼠标交互](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/browser_wVOKIx348I.png) 这里我是用绝对定位将盒子“黏贴”到脸上，主要有三个要考虑的地方： - 如何将盒子定位到圆周上 - 如何确定盒子自身旋转角度 - 如何安排盒子的宽高使得盒子完全覆盖脸的四周 如果盒子本身不旋转的话，会出现这种诡异的情况： ![盒子本身不旋转](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/browser_IuDFxmUd1j.png) 这里使用一个简单的运算去旋转盒子： ```scss // 与鼠标交互的盒子的个数 $part: 72; // 每个盒子间的夹角 $part-degree: 360 / $part; @for $i from 1 through $part { // 旋转角度这里加了 90deg 的偏移是受到了盒子的定位的影响。 // 这里可以忽略，我们只要清楚原理是根据循环确定盒子的旋转角度就好了。 transform: rotate((90 + $i * $part-degree) + unquote('deg')); } ``` 有关第三点“如何安排盒子的宽高使得盒子完全覆盖脸的四周”，则是经验性的东西，各位自己手动调一下盒子宽高，很容易就能整出来。这里要额外提及一下第一点，因为 CSS（SCSS）中是没有正弦余弦函数的，所以不能使用正余弦函数去将盒子定位到圆周上。 **CSS 中是没有正弦余弦函数的，真的么?** **(→\_→)** 好吧，确实没有，但又是一个可以伪造出来的东西... ```scss /** 三角函数相关 */ /** @see 代码来自 http://jimyuan.github.io/blog/2015/02/12/trigonometry-in-sass.html，感谢 */ @function fact($number) { $value: 1; @if $number>0 { @for $i from 1 through $number { $value: $value * $i; } } @return $value; } @function pow($number, $exp) { $value: 1; @if $exp>0 { @for $i from 1 through $exp { $value: $value * $number; } } @else if $exp < 0 { @for $i from 1 through -$exp { $value: $value / $number; } } @return $value; } @function rad($angle) { $unit: unit($angle); $unitless: $angle / ($angle * 0 + 1); @if $unit==deg { $unitless: $unitless / 180 * pi(); } @return $unitless; } @function pi() { @return 3.14159265359; } @function sin($angle) { $sin: 0; $angle: rad($angle); // Iterate a bunch of times. @for $i from 0 through 10 { $sin: $sin + pow(-1, $i) * pow($angle, (2 * $i + 1)) / fact(2 * $i + 1); } @return $sin; } @function cos($angle) { $cos: 0; $angle: rad($angle); // Iterate a bunch of times. @for $i from 0 through 10 { $cos: $cos + pow(-1, $i) * pow($angle, 2 * $i) / fact(2 * $i); } @return $cos; } ``` 有了三角函数，再把循环安排上，就可以造出很多东西了： ```scss // 脸的宽度 $face-width: 300; // 与鼠标交互的盒子的个数 $part: 72; // 每个盒子间的夹角 $part-degree: 360 / $part; @for $i from 1 through $part { /* 计算出盒子在圆周上的定位。需要注意的是，需要加上外围盒子的宽高及自身宽高对应的一些偏移量。 */ $angle: ($i / $part) * 2 * 3.1416; $x: cos($angle) * $face-width / 2 + 500; $y: sin($angle) * $face-width / 2; // 熟悉的 :nth-child 选择器。我的上一篇博客已经说到过这玩意儿了，快去看！ .box_hover:nth-child(#{$i}) { left: $x + unquote('px'); top: $y + unquote('px'); transform: rotate((90 + $i * $part-degree) + unquote('deg')); // 不同的盒子的 :hover 状态，会改变其兄弟 .head 类盒子里的一些东西，这里涉及到眼睛是如何制作的，稍后会说。 &:hover ~ .head { $ty: sin($angle) * $face-width / 50; $tx: cos($angle) * $face-width / 50; left: calc(50% - #{$tx}px); top: calc(50% - #{$ty}px); .eye { &::after { background-position: 100% 50%; transform: rotate( (0 + $i * $part-degree) + unquote('deg') ); } } } } } ``` 那么最后提及一下眼睛的制作。 最先想到的方案肯定是用绝对定位，然后 hover 不同的盒子时，给眼睛设置不同的 left、top 值。 ~~但是这个方案不可行，因为一旦给眼睛加上动画之后，一旦鼠标移动地很快，left、top 值的变化是直线，那么眼睛的行动轨迹就会很奇怪（♂）。~~ 但是这个方案不可行，因为我不想写更多的数学了，我还是用回了 rotate 这个迷人的小东西。 当没有 hover 任何盒子时，我们给 .eye 类盒子的中心画一个圆（此时圆在盒子的中心）： ![画一个圆当眼睛](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/browser_nts2mMjO5x.png) 当 hover 了某个盒子之后，我们把 .eye 类盒子旋转一下，并且改变圆的位置（此时圆在盒子的右侧的中心）： ![改变眼睛的位置](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/browser_emdbc2WaD3.png) 这样的话就完成了。 完整的代码贴在下面，各位也可以去我的博客康康具体的实现（掘金个人主页边有个网站的小按钮，点那个可以直达暗示关注！）。 ## 源码 ```html
    ``` ```scss /** 三角函数 @see http://jimyuan.github.io/blog/2015/02/12/trigonometry-in-sass.html */ @function fact($number) { $value: 1; @if $number>0 { @for $i from 1 through $number { $value: $value * $i; } } @return $value; } @function pow($number, $exp) { $value: 1; @if $exp>0 { @for $i from 1 through $exp { $value: $value * $number; } } @else if $exp < 0 { @for $i from 1 through -$exp { $value: $value / $number; } } @return $value; } @function rad($angle) { $unit: unit($angle); $unitless: $angle / ($angle * 0 + 1); @if $unit==deg { $unitless: $unitless / 180 * pi(); } @return $unitless; } @function pi() { @return 3.14159265359; } @function sin($angle) { $sin: 0; $angle: rad($angle); // Iterate a bunch of times. @for $i from 0 through 10 { $sin: $sin + pow(-1, $i) * pow($angle, (2 * $i + 1)) / fact(2 * $i + 1); } @return $sin; } @function cos($angle) { $cos: 0; $angle: rad($angle); // Iterate a bunch of times. @for $i from 0 through 10 { $cos: $cos + pow(-1, $i) * pow($angle, 2 * $i) / fact(2 * $i); } @return $cos; } /*********************** 笑脸 */ /* 笑脸我是在 CodePen 里的某个项目基础上改的，地址忘了，汗 */ $container-height: 500; .container { position: relative; width: 1000px; height: $container-height + unquote('px'); overflow: hidden; background: #feee9d; } .container { * { position: absolute; } *:not(.circle):before, *:not(.circle):after { content: ''; position: absolute; } $face-width: 300; $circle-width: $container-height; /** 监听器代码 */ .circle { position: absolute; width: 30px; height: $circle-width + unquote('px'); // &:hover { // background: red; // } } $part: 72; $part-degree: 360 / $part; @for $i from 1 through $part { $angle: ($i / $part) * 2 * 3.1416; $x: cos($angle) * $face-width / 2 - 5 + 500; $y: sin($angle) * $face-width / 2; .circle:nth-child(#{$i}) { left: $x + unquote('px'); top: $y + unquote('px'); transform: rotate((90 + $i * $part-degree) + unquote('deg')); &:hover ~ .head { $ty: sin($angle) * $face-width / 50; $tx: cos($angle) * $face-width / 50; left: calc(50% - #{$tx}px); top: calc(50% - #{$ty}px); .eye { &::after { background-position: 100% 50%; transform: rotate( (0 + $i * $part-degree) + unquote('deg') ); } } } } } /** 样式代码 */ .shadows, .head { border-radius: 50%; width: $face-width + unquote('px'); height: $face-width + unquote('px'); transform: translate(-50%, -50%); top: calc(50%); left: calc(50%); cursor: pointer; } .shadows { background-color: darken(#fbd671, 20%); } .head { background-color: #fbd671; } .face { width: 150px; height: 170px; top: 75px; left: 75px; } .mouth { width: 100%; height: 70px; bottom: 0; background-color: #20184e; border: 5px solid #20184e; border-radius: 150px 150px 10px 10px; overflow: hidden; &::after { background-color: #f15962; width: 100px; height: 60px; left: 20px; top: 40px; border-radius: 50%; } } .eye-group { top: 10px; width: 150px; height: 50px; .eye { width: 40px; height: 40px; background-color: #20184e; border-radius: 50%; border: 5px solid #20184e; &::after { width: 100%; height: 100%; top: 0; left: 0; background: radial-gradient(#fbd671 68%, #20184e 68%); background-size: 10px 10px; background-repeat: no-repeat; background-position: 50% 50%; transition: 0.1s; } &.eye-left { left: 15px; } &.eye-right { right: 15px; } } } } ``` ## 后记 昨天我在陈大鱼头的文章下评论了“我可以使用 10x10 的网格系统造一个精准度更高的玩意儿出来”，害，惨。 我原本的想法是想实现一下这样的东西，见下图片（纯 CSS）： ### 效果图 ![](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/200429/gETdht0ELi.gif) ### 解析 不过由于 CSS 没有父级选择器，这种实现几乎没什么用，看我的 HTML 结构就知道了。 ```html

    盒子外部

    盒子内部

    ``` 这样的话限制很大，每一个与鼠标交互的容器底下都得放置一个展现效果的盒子（每一个 .box 类盒子下面都存放有一个单独的 .des 类盒子，.des 类盒子重复了很多次），虽然能实现精准度更高的鼠标进入方向判断，不过带来了很多重复代码， 没什么用。 哦对了，本文中这两个例子的 CSS 代码性能都很差，当与鼠标交互的元素增加到 200 个左右开始，我的电脑就开始出现肉眼可见的卡顿了，这玩意儿生产环境是不可能用到的，也就只能应付应付魔王了。 **其实还是很好玩儿的对吧。(●ˇ∀ˇ●) 好玩儿就对了！** ### 实现 :br :article-a200429-wall :: # 📝 你本可以少写些 if-else > 他觉得 Blub 语言已经够用了，这时，他的思维就已被 Blub 同化了。 > :name[Paul Graham] ## 前言 我不喜欢业务代码中航天飞机式`if/else`语句, 它复杂而臃肿, 至少从美感而言, `switch`就比`if/else`优雅很多. 如果跨语言比较的话, 私以为 ReasonML 的模式匹配比起寻常的`switch`语句又要强上太多. JS 中对复杂判断的不同写法, 带来的感觉是很不同的, 这篇文章里, 我将简单介绍几种用于替代 if/else 的写法. 只有熟悉更多代码思路, 才能开阔我们的思维, **如果不能学习写代码的更多可能性, 也许我们就成了被代码控制住的人**. ## if/else 我们以一个售后流程为例. 用户购买商品后, 可能会因为错件漏件/质量问题/描述不符等原因联系商家进行售后服务, 其中可能会涉及退款/退货/换货/补发等售后支持服务, 商家对此次售后的服务情况也会影响用户对商家的喜好. 在这样的场景下, 我们假设以下伪代码: ```js /* 买家根据不同的售后原因, 去寻求不同的售后支持 */ if (serviceReason === '错件漏件') { const action = randomIn(['退款', '补发']) if (action === '退款') { if (store.checked) { store.refund(somemoney) user.love(1) // 用户更喜欢这家店了 } else { user.love(-1) } } else if (action === '补发') { if (store.checked) { store.mail(goods.AlphaStrike) user.love(2) } else { user.love(-2) } } } else if (serviceReason === '质量问题') { const action = randomIn(['退款', '退货', '换货']) if (action === '退款') { if (store.checked) { store.refund(somemoney) user.love(3) } else { user.love(-3) } } else if (action === '退货') { if (store.checked) { user.mail(recievedGoods) store.refund(somemoney) user.love(4) } else { user.love(-4) } } else if (action === '换货') { if (store.checked) { user.mail(recievedGoods) store.mail(goods.AlphaStrike) user.love(5) } else { user.love(-5) } } else if (action === '描述不符') { // do ... } else if (action === '其它原因') { // do ... } } ``` 在这个场景下, 每一种售后原因导向的售后支持服务内容是不同的, 比如错件漏件时用户不能选择换货服务. 如此一来, 我们的判断条件也就成了一个`[售后原因 * 售后支持服务]`的二维列表. 此时再加上根据售后原因以及售后支持服务的不同, 判断条件妥妥地升为三维: `[售后原因 * 售后支持服务 * 用户喜好]` 显然, 在这种重业务逻辑的地方 if/else 语句显得力不从心, 主要原因如下: 1. **判断条件后置**. 也就是说, 在`} else if (serviceReason === '质量问题') {`一句中, 我们通常要在行末才能找到判断条件, 而些内容并没有高亮支持, 所以经常与下一行的普通代码混在一起, 让人眼花缭乱无法辨识. 2. **代码缩进不清晰**, 当判断层数增加, 或是花括号中的内容加长, 那么阅读代码的时候, 寻找 if 语句对应的结束位置总是给人带来负担. 3. **奢侈的换行**, 当 if/else 语句中的逻辑很短, 像`else { user.love(-5 }`这段代码, 占用了 3 行的位置显得过于奢侈. ## 三目运算符/短路表达式 在一些简单的表达式中, 可以使用三目运算符或短路表达式去简化判断, 如`user.love`这个函数的调用就可以抽成单独的一句, 所以下面这种判断完全可以进行简化: ```js // 未经简化 if (store.checked) { store.refund(somemoney) user.love(1) } else { user.love(-1) } // 简化后 store.checked && store.refund(somemoney) user.love(store.checked ? 1 : -1) ``` ## 逗号运算符 通过括号和逗号运算符, 我们可以把语句变成表达式去执行. 灵活运用逗号运算符可以使三目或短路支持一些更复杂的情况: ```js if (action === '换货') { store.checked && (user.mail(recievedGoods), store.mail(goods.AlphaStrike)) user.love(store.checked ? 5 : -5) } ``` 不过上述代码, 在 Standard 规范中是不被推荐的. ESLint 会警告你要求将这行内容转化为 if/else 写法. 当然, 你也可以修改 ESLint 规范以关闭警告, 前提是你(及团队成员)喜欢这种写法. ## switch/case 处理复杂的多分支判断时, 大部分人会选择使用 switch 作为长 if/else 的替代品, 你觉得下面这种写法如何呢? ```js /* 买家根据不同的售后原因, 去获取不同的售后支持 */ switch (serviceReason) { case '错件漏件': const action = randomIn(['退款', '补发']) switch (action) { case '退款': store.checked && store.refund(somemoney) user.love(store.checked ? 1 : -1) break case '补发': store.checked && store.mail(goods.AlphaStrike) user.love(store.checked ? 2 : -2) break } break case '质量问题': const action = randomIn(['退款', '退货', '换货']) switch (action) { case '退款': store.checked && store.refund(somemoney) user.love(store.checked ? 3 : -3) break case '退货': store.checked && (user.mail(recievedGoods), store.refund(somemoney)) user.love(store.checked ? 4 : -4) break case '退货': store.checked && (user.mail(recievedGoods), store.mail(goods.AlphaStrike)) user.love(store.checked ? 5 : -5) break } break } ``` 很遗憾, 看来 switch 语句并没有比 if/else 要好多少. 只是有一点我要强调, 在上面这个例子中, 所有有关判断的关键字的地方(如 switch, case, &&, 这些都属于代码高亮区域), 几乎都存在与每一行开头的前两个语元内. 所以目前为止, 单纯就搜寻判断条件的难度而言, switch 是要比 if/else 好上一些, 尽管这种好处会随着判断分支的增加而逐渐被消磨(这算是一种遗憾吧). 其实还有一个令我觉得遗憾的地方, switch 语句不能和短路运算符一并使用, 下面是一种错误的示范: ```js switch (serviceReason) { case '质量问题': const action = randomIn(['退款', '退货', '换货']) store.checked && switch (action) { // 这是不合法的写法 case '退款': // ... case '退货': // ... case '退货': // ... } if (store.checked) { // 这是合法的写法 switch (action) { case '退款': // ... case '退货': // ... case '退货': // ... } } } ``` 稍微有些难受, 毕竟使用 if 判断会增加缩进. 现在让我们来看一种更加简洁的思路. ## 配置数据与业务逻辑分离 配置数据与业务逻辑分离(下简称配置逻辑分离)没有先决条件, 和三目短路表达式一样, 你随时都可以开始在代码中使用它. 使用配置逻辑分离, 通常需要定义一个用来存放数据配置的对象, 同时要定义一个`flag`作为配置的键, 配置的值则可以是函数, 数组等任意类型的值. 在执行逻辑的地方, 只需要将判断条件与`flag`进行比对, 就可以获取到当前判断条件下的业务逻辑方法: ```js // 业务数据配置 const serviceHandler = { '错件漏件': { '退款': () => (store.checked && store.refund(somemoney), 1), '补发': () => (store.checked && store.mail(goods.AlphaStrike), 2) }, '质量问题': { '退款': () => (store.checked && store.refund(somemoney), 3), '退货': () => (store.checked && (user.mail(recievedGoods), store.refund(somemoney)), 4) '退货': () => (store.checked && (user.mail(recievedGoods), store.mail(goods.AlphaStrike)), 5) } } // 业务逻辑执行 const handler = serviceHandler[serviceReason] || {} // 对搜寻结果进行'兜底' const executor = handler[randomIn(Object.keys(handler))] || _ => _ const loveScore = executor() || 0 user.love(store.checked ? loveScore : -loveScore) ``` 有没有眼前一亮的感觉呢?暗示点赞 在上面的代码片段中, 我们将每一种状态的数据配置和执行业务逻辑的代码进行了一定层度的分离, 使得代码长度短了不少. 通过逗号运算符, 我们可以同时执行业务逻辑函数, 并且返回用户对店家的映像分数. 如果你不想这么激进, 也许下面的代码是一种好的实践: ```js const serviceHandler = { '错件漏件': { '退款': () => ({ score: 1, cb: () => store.refund(somemoney) }), '补发': () => ({ score: 2, cb: () => store.mail(goods.AlphaStrike) }) }, '质量问题': { '退款': () => ({ score: 3, cb: () => store.refund(somemoney) }), '退货': () => ({ score: 4, cb: () => (user.mail(recievedGoods), store.refund(somemoney) }), '退货': () => ({ score: 5, cb: () => (user.mail(recievedGoods), store.mail(goods.AlphaStrike)) }) } } const handler = serviceHandler[serviceReason] || {} const executor = handler[randomIn(Object.keys(handler))] || _ => _ const handleRes = executor() handleRes.cb() user.love(store.checked ? handleRes.score : -handleRes.score) ``` ## 更加灵活的数据配置 上一节使用了对象进行数据配置, 如果说有那么一点遗憾的地方, 那就是尽管属性的值可以为任意类型, 但是属性本身却只能是字符串类型, 这使得某些场景下我们不能很好的发挥配置逻辑分离的作用. 想象以下场景: 每个月末, 商家会挑选出狂热粉丝( 喜爱程度大于等于 100)发送留言“感谢你”并赠送 10 元优惠券, 普通粉丝(分数 0-100)发送留言“感谢”, 黑粉(分数小于 0)发送“抱歉”并赠送 10 元优惠券. 等等, 喜爱程度分数是不定的! 显然我们不能用对象去处理这样的数据(只要我还没疯掉), 如下: ```js const scoreMap = { '0'() { /* ... */ }, '1'() { /* ... */ }, '2'() { /* ... */ }, '3'() { /* ... */ }, '4'() { /* ... */ }, // ... '99'() { /* ... */ }, '100'() { sendMsg('thank u') sendCoupon(10) } } ``` 令人头大, 难到我们要用回 if/else? 坏消息是: 也许是的. 不过, 我必须强调, **假使判断条件足够复杂**——比如商家不仅赠送优惠券, 商家还根据粉丝分数高低不同, 送出 QQ 红钻/绿钻/黄钻/...一堆需要判断的礼品——使用 if/else 依旧会面临我们在第一小节提到的代码混乱等问题. 所以好消息是, 使用配置逻辑分离能够处理更复杂的更混乱的场景(而且你也应当这么使用). 你还记得我们刚刚提到的“属性本身却只能是字符串”这种略微的遗憾吗? 现在我们将要要解决这个问题! 请看以下代码: ```js // 使用Map进行数据配置 const scoreHandler = new Map([ [ /^score_-[0-9]{1,2}$/, () => sendGift(['绿钻', '蓝钻', '红钻', '黄钻', '紫钻']) ], [/^score_[0-9]{1}$/, () => sendGift(['蓝钻'])], [/^score_1[0-9]{1}$/, () => sendGift(['蓝钻', '红钻'])], [/^score_2[0-9]{1}$/, () => sendGift(['蓝钻', '红钻', '黄钻'])], [/^score_3[0-9]{1}$/, () => sendGift(['蓝钻', '红钻', '黄钻', '紫钻'])] // ... ]) const userScore = 15 const validScore = `score_${userScore}` let handle, entriess = scoreHandler.entries() while ((({ value: handle, done } = entriess.next()), !done)) { const [scoreReg, handler] = handle if (scoreReg.test(validScore)) { handler() // 输出结果“蓝钻” entriess = { next: () => ({ value: null, done: true }) } // 终止循环 } } ``` **使用 Map 进行数据配置是非常棒的一种写法**, 但是如果你必须兼容 IE 浏览器的话, 你必须考虑使用其它的数据结构用于替代 Map: ```js // 双数组进行数据配置 const validator = [ [/^score_-[0-9]{1,2}$/], [/^score_1[0-9]{1}$/], [/^score_2[0-9]{1}$/] ] const handler = [ () => sendGift(['绿钻', '蓝钻', '红钻', '黄钻', '紫钻']), () => sendGift('蓝钻'), () => sendGift('红钻') ] // 执行逻辑省略 // 从validator中找到校验通过的元素的下标, 然后执行handler数组中对应下标的回调函数 // ... 或者其它数据结构 ... ``` 我们在上述两小节中提到的几种不同的代码风格, 都遵循着将'配置'发挥到领先判断一步的理念. 在实际业务中, 你也可以试试尝试混合配置逻辑分离以及常规判断条件式写法, 其中主要考量的点应该是**是配置领先判断, 还是判断领先配置**. ## 后语 本文主要介绍了几种用于替代普遍场景中 if/else 的写法, 如三目+逗号运算符, 使用对象/Map/双数组进行配置数据与业务逻辑分离, 虽然处理业务逻辑的思路是一样的, 但是每种方法写起来的实际感觉却不一样, 孰优孰劣, 还请各位看官仔细品味一番. 最后, 如果本文能给大家带来一些代码上的遐想及思考, 那是再好不过暗示点赞\*2.jpg, 如文中有不当之处, 欢迎各位在评论中指出及补充. ### 代码性能 我没有实际考察过各种写法的性能代价, 有兴趣的朋友可以尝试一下 👍 ### 阅读更多 - [JavaScript 复杂判断的更优雅写法](https://juejin.im/post/5bdfef86e51d453bf8051bf8){rel=""nofollow""} - [\[浅析\]特定场景下取代 if-else 和 switch 的方案](https://juejin.im/post/5b4b73e7f265da0f96287f0a){rel=""nofollow""} - [\[探索\]在开发中尽量提高代码的复用性](https://segmentfault.com/a/1190000016604728){rel=""nofollow""} - [MDN: Map](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Map){rel=""nofollow""} # 📝 技术博客归档 ## 2022-10 - [Modern CSS Layout](https://lionad.art/_achieved/2022-10/flex-in-flex) ## 2021-01 - [🌐 Anysort：灵活、优雅、无依赖的排序库](https://lionad.art/_achieved/2021-01/anysort-1th) ## 2020-12 - [🏆 学习 JS，从忍者到杀手](https://lionad.art/_achieved/2020-12/js-100) ## 2020-08 - [👹 Helmet & Security](https://lionad.art/_achieved/2020-08/helmet-and-security) ## 2020-06 - [斑马难题](https://lionad.art/_achieved/2020-06/zebra-puzzle) ## 2020-05 - [JS 模块化简史](https://lionad.art/_achieved/2020-05/js-module-history) - [常用类型判断方法的优势及缺陷](https://lionad.art/_achieved/2020-05/type-check) ## 2020-04 - [9 种 CSS 图案解析](https://lionad.art/_achieved/2020-04/9-css-chart) ## 2020-03 - [从一张 CSS 风景画中学到的东西](https://lionad.art/_achieved/2020-03/learn-from-an-evening-in-southwold) ## 2019-11 - [🎨 有关 CSS 的一些极有趣的东西](https://lionad.art/_achieved/2019-11/css-interesting) ## 2019-07 - [听说你还在手写懒加载？](https://lionad.art/_achieved/2019-07/chrome-image-lazyload) ## 2019-07 - [欢迎（曾经的首页）](https://lionad.art/_achieved/2019-07/welcome) ## 2019-06 - [从一个越写越慢的编辑器中聊聊优化思路](https://lionad.art/_achieved/2019-06/teditor) - [🚀 150 行代码带你实现小程序中的数据侦听](https://lionad.art/_achieved/2019-05/reactive-in-150loc) # 📕 读书笔记 ## 分类参考 - [图书分类参考](https://lionad.art/_books) ## 笔记和书评 微信读书导出的读书笔记格式不仅有缺陷，内容也有很多错误的地方。目前支持划线的展示，还没有评论（评论是当成划线展示的）。 ![preview](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/202502020722501.png) 代码在这里，还很烂，慢慢更新吧：{rel=""nofollow""} 这个页面还缺个书架前端，我想做成和微信读书同步。 增订：微信读书自动化有封号风险。 ### 2025 - [《撒旦探戈》 @ [匈] 克拉斯诺霍尔卡伊·拉斯洛](https://lionad.art/books/_isbn-9787544754781) > 历史就是人的故事，这些故事结构相似，又环环相扣，以复杂多面示人，蠕动着变得健壮。试图从中窥见什么真理是一种妄想，而人只能用一种艺术化的，不完美的，甚至恶心的方式来解剖这些内容。一旦条件俱佳，新的故事又会从剖析得到的污秽的血肉里重生。 > 在绝望黑暗及难分生死的边界，于疯癫边缘解剖疯癫，谓之撒旦，如此往复，称之蛇环。往前六步，回转，后退六步，一次完美的探戈。 - [《存在主义心理治疗》 @欧文·亚隆](https://lionad.art/books/_isbn-9787100110457) > 在存在主义的几个关键字里，自由、责任、意义等词的概念过于模糊，一旦分析起来容易落入文学化叙事。好在心理治疗是临床经验的、实践的，很好的弥补了这个缺点。 > :br > 现代心理学有许多流派，不仅关注梦、潜意识等，也关注生物神经、脑科学等等。如果按照亚隆所说，存在主义范式的心理治疗也有机会被另一种解释性更强的模型替代。这么想的话...既然解构可以触生新哲学， > 那么似乎也许大概解构主义也有成为心理治疗新范式的模型的可能？ - 《星空词典》 @郑春顺 > 很好的天文科普 - 《TypeScript Deep Dive》 @basarat - 《假面自白》 @三岛由纪夫 - 《维特根斯坦十讲》 @楼巍 - 《克拉拉与太阳》 @石黑一雄 > 并非诡计多端才是人性，天真的温暖机器人不应有如此下场。结局很圆满，但却是一出悲剧。 > :br > 看到自己顺手给打的“科幻”标签觉得好笑。明明是未来已来，哲学没能跟上科技的发展。果真是“哲学家的贡献往往要等他们死后才能体现”，科幻之流通俗小说能把诺奖领了一点儿不冤。 - 《世界因何美妙而优雅地运行》@约翰·布罗克曼 > 展现了广博的智慧和洞见，这是 21 世纪的必修课。 这本书相对较硬核。阅读方法：囫囵吞枣不可取，宜配合搜索引擎和 AI 使用，确保理解作者在说什么。 - [《雪国》@川端康成](https://lionad.art/books/_isbn-9787544265591) > 看到驹子用手捂着红扑扑的脸，就想到《情书》的封面。 - [《奇点更近》 @雷·库兹韦尔](https://lionad.art/books/_isbn-9787522333977) > 短一些就更好了。 ### 其他记录在豆瓣的 - [《简读日本史》@张宏杰](https://lionad.art/books/_isbn-9787553815268) - 《死亡的故事》@大卫·伊格曼 > 一本被包装成优秀科普的平庸的科幻点子集 - [《太白金星有点烦》@马伯庸](https://lionad.art/books/_isbn-9787572610912) - 《芬兰人的噩梦：全两册（中英双语）》@［芬］卡罗利娜•科尔霍宁 > 有点意思 - 《手机摄影笔记》@李硕 > 不错的入门书 - 《万事法则》@［英］理查德·泰普勒（Richard Templar） > “微信公众号水平”的正确的废话。单纯数据来看，豆瓣的评分要比微信读书低很多。 > :br > 其中某些法则也许是有效的，但作者的论证经常局限于以身边的人或事举例，没有逻辑可言。也并非没有有用的地方，我推崇作者的“要成为一个法则玩家”的观点。实际上陈词滥调也并不是“错的”，只是相比阅读法则，你更需要成为一个思辨的、 > 能抽象思考总结规律的、灵活的聪明人。这才是法则玩家的真相。 > :br > 本书是我的出版物阅读的一个里程碑，在这第 200 本书我想了解一下看畅销书的人脑袋里在想些什么。如果没有特殊目的，或者你是一个“聪明人”，那就别再继续了。 - 《祈祷之海》@ [澳] 格雷格·伊根 > 读过的最好的科幻短篇 - 《AI 绘画：Stable Diffusion 从入门到精通》@许建锋 > 本书最大的价值是描述了一个基础的生图工作流程，从找素材，文生图创建基本场景，再到 controlnet 控制结构，图生图重绘生成有价值的最终场景。鉴于近年来这块玩具发展迅猛，这个流程很快会被以蓝图技术为代表的工作流取代。 > 在技术还没被颠覆的情况下，入门可以过一遍此书，无深入研究的必要。学习计算机软件更重要的是实践，期待作者的新书。 - 《激荡十年，水大鱼大》@吴晓波 > 浪潮不会停止，正如历史不存在终结，时间裹挟一切，向下一个十年奔涌。作为时代的普通人，亦或是浪潮中的小虾，常被在其中激起浪花的领头鱼所震撼。这些企业，可以作为一个同时代的优秀标杆自勉。 > :br > 企业史实际上就是企业家的精神史，其中某些精神，甚至能赋予最悲观者继续前行的力量，向时代的不确定性或无常发起挑战。开卷有益，开卷有益。 - 《大力出奇迹》@王健平 > 同样是在概率中求解，寻求理性及寻求浪漫会导向两个截然不同的方向，前者在概率中寻找确定性，适合资本，后者在冒险中追寻体验，适合人生追求。 > :br > 书本身有许多问题，比如前几章的“没神硬造”，但鉴于是一本不可多得的完整综合性资料，所以依旧是推荐。 - 《架构师应该知道的 37 件事》@ [美] 格雷戈尔·霍培 （Gregor Hohpe） > 不到推荐的程度，有亮点但大部分内容都聊得很浅。 > :br > 本书集合了作者多年来的架构经验（当然可以理解为某种“偏见”），充满比喻，算是有趣。因为书中所写皆基于作者的职业生涯，读到一些奇怪的内容后，总是想说“很难想象作者到底在企业 IT 经历了什么鬼。..” - 《软件设计的要素》@ [美] 丹尼尔·杰克逊 > 微信读书有电子版了主要内容很平淡，作者似乎想抛开软件工程学并重新建立一套软件设计的基础概念（既书中的“概念”），在我看来这是不切实际的，因为对于开发人员来说，且不论已经有许多“working”的软件设计概念， > 抛开现实会遇到的工程问题的设计都是理想主义式耍流氓。作者显然意识到了自己犯的错误，也许是错误，所以附录中包含了工程学的讨论，只是作者不欣赏工程学遇到问题时的“不完美解”。 > :br > 鉴于附录非常开阔思路，所以综合考虑推荐。 - 《前方的路》@阮一峰 > 阮一峰的许多博文是很好的导读，他的文字兼具文艺的感性和理智的克制，同时保持简单。昨晚看到别人推荐，今儿收了书单一口气读完，好久没有这样酣畅淋漓的体验了。仔细回想起来，在几年前刚养成出版物阅读习惯的那会儿，第二本就是看的黑客与画家， > 也是十分好读。翻译也好，或者导读性质的博客亦或是杂文也好，保持文字简单好读，非常重要。阮老师是一位可敬的引路人。 - 《趁生命气息逗留》@ [美] 罗杰·泽拉兹尼 > 介于科幻和奇幻之间的小说，偏向奇幻多一些。也许是版本的问题，文字读起来并不流畅。《趁生命气息逗留》并没有相当惊艳的科幻逻辑，我认为其受好评的地方是点了圣经。相比封面，更喜欢本书结尾兰斯洛特的故事，同样点了经典故事。 - 《零代码全民开发：为企业数字化转型赋能》@简道云团队 - 《偶然的宇宙》@ [美] 艾伦·莱特曼 - 《神话的力量》@ [美] 约瑟夫•坎贝尔 (Joseph Campbell), 比尔•莫耶斯（Bill Moyers） > 没有背景知识阅读起来真的很困难。平均每万字花了一个小时十分钟的阅读时间。 - 《时间》@ [意] 奎多·托内利 > 不到“推荐”的程度 - 《云彩收集者手册》@ [英] 加文·普雷特-平尼，加文·普雷特-平尼 > “但是，你错了。收集东西并不等于要拥有它。你甚至也不用去想如何抓住它。你要做的，只是去看，去记录。”，我真的在反思啦 hhh - 《天气的秘密》@ [英] 特里斯坦·古利 > 云风林水虫鱼鸟兽，这些常见的东西，透露了许多关于天气的秘密，大部分时候，这些细节之处都被大脑习惯性忽视了 - 《基本演绎法》@李媛媛，刘洪波，刘潋 > 前几章有不少错误 - 《维莱特》@夏洛蒂·勃朗特 - 《北欧神话》@茅盾，王浣 绘 > 老书重印，人物名等按照现代译法做了替换（但奇怪的是和百度百科中搜到的不同），应该是本不错的北欧神话入门 - 《CSS 选择器世界》@张鑫旭 > 为选择器的使用方法展现了更多的可能性 - 《三体 X》@宝树 - 《大师的盛宴》@ [美] 奥森·斯科特·卡德 - 《注意力》@让-菲利普·拉夏 (Jean-Philippe Lachaux) > 总能在情绪爆发前的一秒熄火，就像是第二个脑子把情绪夺了回来。原来这种注意力的控制和禅修是类似的呀。 - 《让你在公司显得很能干的 52 种方法》@罗斯·麦卡蒙 > 这书名太大了，毁掉了内容。其实就是一本很短很小的散文集，讲了讲职场的边角料。从后记来看作者很想把自己职业生涯的“哲思”塞进去，可惜没能成功。 - 《钓客清话（博物图鉴版）》@艾萨克·沃尔顿，查尔斯·科顿 > 挺不错的，像是观摩一出戏剧。在封城那会儿看到品鱼的章节时，垂涎三尺，真是巴不得长双翅膀飞去河边呐："取一条鲤鱼，可行的话最好用活鲤鱼，用盐擦拭一番再用水冲洗干净，不要去鳞，直接剖开后去掉内脏，留下肝脏，带血放进小锅或者小罐里。 > 取甘牛至、百里香、芹菜各半把，加点迷迭香或者其他香薄荷，混在一起扎成两三个小捆放进鱼锅里，再放四五个洋葱、二十只捣烂的牡蛎、三条鳀鱼，再往锅里倒进刚好淹没鱼身的红酒，加上适量的盐、丁子香、肉豆蔻、陈皮、柠檬皮。配好之后用猛火烹煮， > 熟透之后连鱼带汤盛在盘里，再在四分之一的鱼身上放点最新鲜的牛油。取两三个蛋黄，加点切碎的香薄荷，用汤勺把蛋黄和香薄荷搅匀，然后倒在牛油上面，最后挤上一点柠檬汁。这样的美味，您就好好享受吧。" - 《中国文学》@（美国）桑禀华 - 《龙族Ⅲ》@江南 > 高中就漏看了这部，现在总算找机会补完了 - 《抗炎生活》@ [日] 池谷敏郎 > 日本人的科普味道都一个样 - 《龙族Ⅲ》@江南 > 最大槽点：情节老崩所以只好用二货来救场，最后所有人都变成了二货 - 《龙族Ⅱ》@江南 - 《莫言的奇奇怪怪故事集》@莫言 > 盛赞《秋水》，其次是《木匠和狗》、《拇指铐》与《铁孩》。不要妄图从奇奇怪怪的故事中探究莫言到底想说什么道理，故事没头没尾没解释时的确可以是自洽的：信仰，隐喻与因果链是带来艺术感觉的灵丹妙药。 > :br > 另，《藏宝图》的语言风格很奇妙，如同把连篇不带标点的字像打机枪一样打过来。开篇读得我犯困，但还是好奇这种语言风格是从哪里学来的。 - 《Essential C++ 中文版》@ [美] Stanley B·Lippman > 受益匪浅 - 《晚年》@日太宰治 > 一盒巧克力？ - 《性学观止（插图第 6 版·全两册）》@ [美] 贺兰特·凯查杜里安， [美] 贺兰特·A·凯查杜里安 > 之前嘲讽贵州网约车不雅标语时被人反驳“胸什么时候成性器官了”，我当时查了许多资料发现确实是事实，没办法回应。现在我会告诉她，仅从解剖的角度去讨论性那可真是狭隘的视角。 - 《三体Ⅲ》@刘慈欣 - 《月百姿》@ [日] 月冈芳年 > 这…我开的一瓶可乐都还没喝完就结束了 - 《50：伟大的短篇小说们》@欧·亨利，契诃夫，都德，蒲宁，舒尔茨，波德莱尔，莫泊桑，马克·吐温，泰戈尔，海明威，福克纳，普希金，托尔斯泰，陀思妥耶夫斯基，爱伦·坡，伍尔夫，霍桑，毛姆，卡夫卡，茨威格，狄更斯，芥川龙之介，菲茨杰拉德， 洛夫克拉夫特 > 之前看到 B 站有人批评这种黄黄的纸，我为他们感到惋惜。他们不明白这种纸很舒服，很软，可以带上床看，躺下来砸中脑袋也不疼。 - 《消失的 13 级台阶》@ [日] 高野和明 - 《打开黑箱》@王欣 > 第一部分相当精彩，往后则科普的浓度变低，就成影评了。 - 《索拉里斯星》@ [波] 斯坦尼斯瓦夫·莱姆 > 后半篇哲思很震撼，但不是那么好读，篇幅再短些就好了！为了填补人类和海相接触的背景知识，加了许多戏中戏。我已经开始回忆起看论文的恐惧了… 凯尔文在图书馆那会儿都要把我看睡着了。 - 《费曼学习法（用输出倒逼输入）》@尹红心 李伟 > 哈，喝一口汤暖暖身子！ - 《大脑帝国》@ [挪] 卡娅·努尔英恩 > 非常棒的科普书，介绍了包括大脑的进化史、记忆、人格、文化以及知觉等各方面的内容。只是稍微薄了些，内容也比较浅显，要是再长一些就好了！ - 《时间旅行者年鉴Ⅱ：岁月裂隙》@【美】安·范德米尔&杰夫·范德米尔 - 《三体Ⅱ》@刘慈欣 > 第一部高开低走，这一部铺垫冗长。期待第三部哇咔咔咔 - 《画地为牢》@ [英] 多丽丝·莱辛 > 冗长而无聊。 - 《Processing 创意编程》@任远 > 讲得不错。代码有些错误，需要稍许代码基础。 - 《后真相时代》@ [英] 赫克托·麦克唐纳 > 不错，值得一读。 - 《时间旅行者年鉴Ⅰ：时间之线》@【美】安·范德米尔&杰夫·范德米尔 > 其中一些不错。 - 《七堂极简物理课》@ [意] 卡洛·罗韦利 - 《幻想图书馆》@寺山修司 (Terayama Shuzi) > 食之无味，弃之可惜。 - 《技术的真相》@ [加拿大] 厄休拉·M. 富兰克林 > 作者对技术有深刻的洞见。通过七篇简短的演讲，展示了技术如何塑造了社会、社会关系、时间、空间以及其创造出来的真实性和各种解构性力量。非常不错，值得一读。 - 《沉思录》@ [古罗马] 马可·奥勒留 > 看不下去了，再见。 - 《麦肯锡笔记术》@ [日] 大岛祥誉 > 要我说，问题就是现实与理想的差距。本质问题也就是造成差距的直接、间接的阻力。把定义解释清楚，再额外探讨 5W2H 等方法，会好解释得多。明明一篇千字短文能概括的事，作者花了一百多页也没讲清楚。 > 不知道是不是日本人写的东西都这么啰嗦。多一星给排版 - 《你一生的故事》@ [美] 特德·姜 - 《深网》@ [德] 匿名者 > 稀烂 - 《细胞生命的礼赞》@ [美] 刘易斯·托马斯 - 《C++新经典》@王健伟 > 不错，挺实用的入门书。 - 《前端函数式演进》@邵丁丁 - 《面向对象是怎样工作的（第 2 版）》@ [日] 平泽章 > 不错的编程书。感觉日本人写的技术书总有一种独特的语言风格，废话多。 - 《亲爱的界面 第二版》@ [瑞士] Lukas Mathis > 从前听人说如果要系统性地学习某个领域，要先了解这个领域的基础知识骨架，再有针对性地提高单项能力水平。字典、大学教材等很容易被误认为是知识骨架，实则它们不是（abandon 这个词怕是一辈子忘不掉了）。尽管我读得书不多， > 但一直都有留意找到一本能作为骨架使用的书。翻开《亲爱的界面》的目录时，我心想，就是它了。 - 《讲了 100 万次的故事·北欧（全两册）》@曹乃云 编译 - 《探索设计中的灵感 植物美学》@ - 《神话与魔法》@ [加拿大] 约翰·豪 - 《银河系搭车客指南》@ [英] 道格拉斯·亚当斯 > 以后我若要设计一门编程语言的话，就要加一个彩蛋；生命的意义 ＜ 43 ＝＝ TRUE - 《图解世界：科学的 100 件事儿》@ [英] 亚历克斯·弗里斯 等 > 当了一回小孩子\~\~ > :br > 吐槽：目录那两页的视觉指引设计的太糟糕了 - 《信息设计之美》@ [美] 乔尔·卡茨 > 作者应该是主交通图设计的，书中有大篇幅的关于地图、地铁图的讨论 - 《凯尔特神话传说》@托马斯·威廉·黑曾·罗尔斯顿 > 本来想吐槽一下翻译，但是想了想，整理资料、翻译文献要比讲故事困难多了。 - 《龙族Ⅰ》@江南 > 情节崩坏 - 《维庸之妻》@日太宰治 > 短篇果然是长篇的试金石。 - 《写作之书》@ [美] 保拉·拉罗克，Paula LaRocque > 书中许多建议主要针对英文写作。内容本身不错，不上四星的原因是翻译成中文后稍有失风味儿。 - 《JavaScript 函数式编程》@ [美] Michael Fogus > 哦豁，评错书了，尴尬。..\n\n===== > :br > 非常好的一本书，从函数入手，介绍了许多引人注目的函数式编程技术（以及设计原则）。翻译并没有评论中的一星那么不堪，它比 Github 上一些出名的开源译本的翻译要好多啦。 > :br > 哪怕只有一点函数式编程的经验，书中的代码都不算难以理解。这些例子能给使用 JS 进行数据处理带来非常大的启发。 - 《一个人就一个人》@刘同 - 《JavaScript 语言精髓与编程实践（第 3 版）》@周爱民 > 圈子里人称“绿宝书”，这不是一本简单的书，整体给人非常震撼，不过行文稍显啰嗦。五星表敬意。 - 《Webpack 实战：入门、进阶与调优》@居玉皓 著 > 不错 - 《javascript 之美》@Anton Kovalyov > 尽管有些文章稍显过时老气，有些文章划水划地厉害，但这些瑕疵并不影响我极力推荐这本薄薄的小册子。这本小册子讲到许多有关 JS 程序员的信仰，它并不仅仅是《JS 精粹》这么简单。期待再版。 - 《奔跑吧，梅勒斯》@日太宰治 > 《女生徒》中这种神秘的虚无感呐，不是谁人都能体会到的。 - 《少数派报告》@ [美] 菲利普·迪克 > 才看到 Kindle 会免了这本，几乎是一口气看完了。今早听说 2077 又要推迟发售，那今年只能多看些科幻度过空档期了。 - 《八百万种死法》@ [美] 劳伦斯·布洛克 > 像是在看 80 年代的科幻，有仿生人的感觉。两者最大的不同是，仿生人的宗教能救人灵魂，而八百万总死法中的宗教却是残害生灵的老手。书的封面太有意思了，盛赞。 - 《超新星纪元》@刘慈欣 > 这写的是什么玩意儿（挠头 太失望了> 听说稿子改了很多版，不过但凡了解一点创作的人都知道，在别人的督促下，作品是越改越差劲的。 - 《朝花夕拾》@鲁迅 > 回首重读鲁迅，看到的不颇多为社会残暴与人间疾苦，而是通过文字复原的一个生动有血有肉的鲁迅。 - 《大教堂与集市》@ [美] Eric S. Raymond - 《计算机科学精粹》@ [巴西] 沃德斯顿·费雷拉·菲尔多 > 好书。简明扼要地把硬件软件的一些简单原理捋了一遍，更难得的是语言通俗易懂。 - 《SEO 实战宝典》@丁士锋 > 对入门书籍来说确实可以了。内容浅显易懂，每一步骤都有截图，但是部分内容与时代脱节严重了。 - 《马克·吐温短篇小说集》@马克·吐温 > 马克吐温的短篇小说情节的比重比人物塑造要多了不少笔墨。这本书翻译可以，有几篇我没看懂的地方我特意对照了网上其它译本，都长这模样。书中把目录换成了各短篇的一句话情节概括，也没有标注页码没懂。 - 《不可能的堡垒》@ [美] 詹森·雷库拉克 - 《久石让音乐手记》@ [日] 久石让 > 杂志上的连载整理成篇，然后佐以一篇访谈和数页作品目录。 - 《大雪将至》@ [奥地利] 罗伯特·泽塔勒 - 《我写我型：手写字体在平面设计中的应用》@三度出版有限公司 > 不错，有几张图片很模糊，总体很棒。 > 手绘字体一般用在和“手工”、“精致”、“冲击力”等词相关联的地方，所以感觉大的来说收录不了各式各样的丰富的用例。不过话又说回来，不同字体体现的性格应该会导致手绘字体应用场景不同，这点来看本书确实还有值得补充的地方。 > 一些手写字体容易用计算机制作，而非绘制，这部分“手写字体”本书就没有收录。 - 《现代平面设计巨匠田中一光的设计世界》@ [日] 田中一光，朱锷 （编） > Wabi，Sabi，Suki，the essence of japanese beauty. - 《低欲望社会》@ [日] 大前研一 > 没读过反方观点之前没办法评分。也许这就是经济评论家的写书风格，抓住自己认定的问题的本质就直接开口了。不过大部分人是写不出这种东西的，大部分所处的政治环境也是不支持写出这种东西的吧。 - 《如何用 kindle 高效学习》@直树桑 - 《田中一光自传（与设计一起前行）（精）》@日 田中一光 > 一开始翻了几页，觉得是很普通的一本传记，很普通的笔法。然后一想到书架上有本买来没看的《设计的觉醒》就脑瓜疼。 > :br > 再看就不得了，居然熬着夜一口气看完了。太精彩了，从前两章平铺直叙的铺垫，到中间章节夹叙夹议不乏思考的恢宏的精气神，再回到尾声那几篇回忆录似的平静。没想到宗一的的写作水平如此了得，能从平实的语言中透视出横贯 70 年的时代感。合书那刻， > 我心里想，这不就正是宗一毕生设计理念在文字与笔法中的体现。 > :br > 全场最佳是结尾的宗一好友的寄语，作为补充资料，点亮了一些自传中不那么轻易显现的几处。 > :br > 书装帧不错，翻译也 nice，能察觉出几处校对疏漏。低分应该是一开始的节奏就被带偏了。我实在找不出低分的理由。满分给这位继往开来的人物，非常推荐。 - 《孤独深处》@郝景芳 - 《艺术·设计的色彩构成（修订版）》@ [日] 朝仓直巳 - 《乞力马扎罗山的雪》@（美）厄内斯特·海明威 > 读《印第安人营地》那篇我就对比了几个译本，总得感觉翻译和片段的删减都挺不错的。《大双心河》两篇，尤其是钓鱼那篇，确实没懂，害，真难。 - 《娱乐至死》@ [美] 尼尔·波兹曼 > 经典，书名给作品带来了谜之收益。理论的角度很好，立场却不可靠，害，说到底还是议论文的讲理具体要站在哪儿开始是个复杂的问题，完全没有写寓言那么好发挥，以至于波兹曼说自己完全比不上赫胥黎时我心里哈哈笑了两声。 > 波兹曼抨击电视只是因为那个时代出现了很多关于电视的不堪入目的言论，这并不影响我们把他的理论再拓宽深掘一番，并代入现世。哦对了，好像我在去年就看过一本《互联网是如何使人浅薄》之类的书，虽然理论的角度有类似之处，但两者一比，高下立判， > 还是波兹曼的经典。 - 《游戏的终结》@ [阿根廷] 胡里奥·科塔萨尔 > 唯一的缺点是，我跟不上节奏。.. - 《艺术·设计的平面构成（修订版）》@ [日] 朝仓直巳 > 害，可惜老爷子走得早，这理论再跨学科间打磨打磨我觉得会更加完美。 > :br > 书中有一些翻译错误，或感觉还可以再斟酌一番的地方，但是总的来说瑕不掩瑜。 - 《排版技术》@翟铭 > 主要普及了排版的一些基础知识，可以做入门用。希望能出二版，更新一些书中比较陈旧的知识。 - 《治字百方》@左佐 > 唯一的槽点是：我真的看不懂文言文（大雾）。哭了，下次能不能把书写得再白话一些。 - 《瓦尔登湖》@【美】亨利•戴维•梭罗 > 梭罗的自由是真正的自由； > 梭罗的经济学是有生命的生产力； > 梭罗的孤独——人没必要在游行和典礼中结对前行，而应随着自然的脉搏而呼吸——这是与宇宙的狂欢。 > :br > 这是一本伟大的书。 > :br > 装帧不错，翻译嘛我不懂。 - 《设计法则 100》@王绍强 > 我们不需要更多观点。 > 装帧漂亮，但是内容平淡。 - 《超越平凡的平面设计》@ [美] 麦克韦德 > 不错，和《写给大家看的。..》的那个系列的书结合起来看十分有帮助。 - 《小岛经济学》@彼得·希夫，安德鲁·希夫 - 《御伽草纸》@ [日] 太宰治 > 稍微对比了一下汤先生的译本，我觉得徐的译本要流畅一些，这本《御伽草纸》装帧及排版也是非常漂亮，十分推荐。没有五星的理由是，太宰治把每个童话新编的道理都阐述的过于清楚了，这显然是不信任读者的表现。 - 《天真的和感伤的小说家》@ [土耳其] 奥尔罕·帕慕克 > 薄；亲切；并不好读（也许是因为我还没尝试写过一本小说）。 - 《弗兰肯斯坦》@ [英] 玛丽·雪莱 - 《动物农场》@ [英] 乔治·奥威尔 - 《艺术的慰藉》@ [英] 阿兰·德波顿， [澳] 约翰·阿姆斯特朗 > 一星给作者，一星给议论，一星给设计，一星给装帧。若是把“议论”换成“散文”，兴许我才会满分推荐。 - 《XWorld：未来进化》@以色列] 尤瓦尔·赫拉利， [以色列] 尤瓦尔·赫拉利 > 还好是讨论的实录，而不是演讲与分享的实录，因为我喜欢严谨的议论，而不是充满假设的警告 - 《巴黎评论•短篇小说课堂》@洛林·斯坦恩/塞迪·斯坦恩 主编 > 故事和语言本身一样伟大。我想起以前看过的一个把写作中文笔之于写作比喻为汽车座椅材质之于汽车的例子，现在想想才算真正的找到了反击的理由。语言一词包含了太多东西，它是故事的一部分。 - 《哈佛经典谈判课》@【英】德雷克•阿顿（Derek Arden） > 能体会到作者对人物的心理状态的感知的老练之处，但是也有种没有说尽的感觉。行文碎片化，故事叙述也缺乏独到之处，作为博文可行，强行成书缺了几分深度。 - 《美丽新世界》@【英】奥尔德斯·赫胥黎 > 一看到《重返美丽新世界》有关人口过剩的那章就头疼。有些反感。 - 《一想到还有 95%的问题留给人类，我就放心了》@ [巴拿马] 豪尔赫·陈， [美] 丹尼尔·怀特森 > 阔以 - 《OPUS 作品》@ [日] 今敏 > 期待动画 - 《知觉之门》@ [英] 阿道斯·赫胥黎 > 启示录 - 《上帝掷骰子吗？》@曹天元 > 不错 - 《现实不似你所见》@ [意] 卡洛·罗韦利 > 不想把对«时间的秩序»那本书的短评再 copy 过来了 - 《怦然心动》@文德琳·范·德拉安南 > 无法评价 - 《永久记录》@ [美] 爱德华·斯诺登 (Edward Snowden) > 意义重于内容。第二部分写得有些不明白，跳跃地很快，质量与其它两部分有些差距。 - 《山月记》@ [日] 中岛敦 > 超一流作品。 - 《呼吸》@ [美] 特德·姜 > 喜欢其中的一些短篇。作者喜欢通过描写人物的“内省”去发掘故事的深刻性，不过看多了就稍显腻味。书中前面有些短篇让人映象深刻，但是同样的手法换到篇幅更长一点的文章或是篇幅极短的文章中就会让作者故事叙述技巧显得捉襟见肘。如果有半星的话， > 我觉得 3.5 星更适合表达我的推荐程度。 - 《当呼吸化为空气》@ [美] 保罗·卡拉尼什，Paul Kalanithi > 除了生死，还能看到作者对人物联结的奇妙，人生意义的沉思，宗教与科学的哲思，家庭与工作的关系及行业背后等各种事物不乏深度的展示或讨论。除了故事本身的精彩，还能一瞥有关“预言”的神秘力量。 - 《好好告别》@ [美] 凯特琳·道蒂 - 《海子的诗：我只愿面朝大海，春暖花开》@ > 也许是思维运转的速度没有达到理想状态，我读不懂海子的诗中的意向。2.5 - 3 - 《时间的秩序》@ [意] 卡洛·罗韦利 > 有东西在我脑海里被摧毁，又好像是重造。无关科普，仅仅从优美的文字其中蕴藏的哲思角度而言，这就是一本太过美妙的书。 > :br > 为啥不去写小说呢？立个小目标，捞个诺贝尔也不错啊 /笑 - 《情人》@ [法] 玛格丽特·杜拉斯 > 我第一次被小说虐了，不是因为冗长乏味的外国人名，而是因为晦涩难懂的跳跃式写作手法。 - 《仿生人会梦见电子羊吗？》@（美）菲利普·迪克 > 情节跌宕，层次丰富，笔力浑厚。 - 《御伽草纸》@ [日] 太宰治 - 《局外人》@ [法] 阿尔贝·加缪 > 感觉像是三幕式结构的中篇小说。内容很棒。译者评也很精彩。 > 只是我实在不喜欢第一部的描写，虽然说这一部分对刻画主人公局外人的生活占据重要的篇幅，但我宁愿这是一篇短篇。真正讨喜的东西在第二部分中，相比之下，第一部分实在有些索然无味。 - 《活下去的理由》@ [英] 马特·海格 > 我就在等这样一本书，没有普遍社科书籍中令人生厌的乏味实验，而仅以文字力量记录真实的这样一本书。书中结构像是随笔的编排，读起来不算累但是稍微有一些脱节，不过到最后居然有一丝恰到好处的意味。 > :br > 我太喜欢快结尾时那几十小节颇有哲思的抒情写法了，不过我心里清楚，这是太多生活态度与思想与作者不谋而合所带来 的“偏见”。（从 4 星升至 5 星的主要原因） - 《半小时漫画中国史（修订版）》@二混子 - 《2010：太空漫游》@ [英] 阿瑟·克拉克 > 我原以为所有的好故事，都笼罩在预言的阴霾之下。太空漫游系列似乎是个例外，这次语言带来的不是阴霾，而是引爆木星的热浪。 - 《三万年前的星空》@ [日] 谷川俊太郎 > 所有隐秘的情感，都藏在星空里， > 藏在夜星闪烁，天幕旋转的地方。 > :br > 我在永夜的极光下， > 踏上萧索冰川， > 和它冻住的海。 > :br > 寻找那些美好的情感， > 种子般发芽的是幻象。 > :br > 睁开双眼， > 是三万年前的宇宙在翻腾； > 闭上双眼，星星黯淡， > 宇宙沉默如死寂， > 只有你。 - 《学会提问（原书第 11 版）》@ [美] 尼尔·布朗 (Neil Browne), [英] 斯图尔特·霍尔 > 看此书之前我一定是个小杠精，要不然我怎么会来追逐抬扛的大山？ - 《游戏剧本怎么写》@日 佐佐木智广 - 《一本正经又怪诞的行为心理学》@理查德•怀斯曼 - 《橘子不是橘色的》@ [英] 加里·海顿（Gary Hayden） > 非常好读的入门科普。看完之后第一反应是对超人更加敬佩了哈哈哈哈。 - 《重口味心理学 3》@姚尧 - 《像世界一样宽广地活》@曹頔 > 掩卷后若有所思，便是好书 - 《谜（不确定的游戏）（精）》@ [美] 格雷格·科斯蒂基安 - 《人生学校：爱情的真相》@（英）人生学校 编著 > 有人说爱情是热恋鲜奶和玫瑰，有人说爱情是冬雷震震夏雨雪天地合，有人说爱情是知心相交。.. 很遗憾这些都不是，至少不完全是。 - 《电车难题》@ [美] 托马斯•卡思卡特 - 《重口味心理学 2》@姚尧 > 朋友推荐的娱乐科普书，不错，有意思。初看以为是讲故事的畅销书，后来发现确实挺好的。 - 《CSS 设计彻底研究》@前沿科技 温谦 > 挺老的书了。一些基础知识如盒模型和浮动讲得很通透，不过搁现在看这书名讲大了！适合设计师新手入门，程序员的话为什么不看权威指南呢 hhh 总的来说食之无大味弃之亦可惜 - 《怪诞心理学》@ [英] 理查德·怀斯曼 - 《语言学的邀请》@ [美] 塞缪尔·早川， [美] 艾伦·早川 > 一本讲语言的书里面居然援引了文学、政治、经济、社会学、传播学、心理学、物理、哲学的案例，作者是真的学识渊博。四点五星好评，若是再深入探讨我愿意五星力荐。 - 《哲学的迷途》@（美）莫提默‧艾德勒 > 希望国内能再多些艾德勒的译本 - 《绝对笑喷之弃业医生日志》@ [英] 亚当·凯 > 3/5 篇幅的日记，2/5 篇幅的批评，满分的幽默水平背后是一群人对整个国家制度的抗争以及自己内心的挣扎。 > :br > 五分吧，还是强烈推荐别人读的。 - 《罗生门》@ [日] 芥川龙之介 > 和以往看过的短篇相比，这本读着着实令我着迷又心累。芥川龙之介的短篇中描绘的细小微妙的情感，往往还需多仔细琢磨，更甚有时啥也揣摩不出来，这是若是不阅读注解或书评，根本无法继续阅读。题外话，我对《一个傻子的一生》那篇心生敬畏险些放弃阅读， > 好在注解来的及时。不得不说这个译版十分有心，从导读到译后记、选材、注解等多个角度而言都颇显心意，巧妙的呈现了一个颇为完整的芥川龙之介的形象。高分理所应当。 - 《时光尽头》@珍妮·格林 > 选题、翻译都阔以，有几篇不是看的特别懂，书中也没有给出相应的注释，但总体来说质量不错。 - 《事物的味道，我尝得太早了》@ [日] 石川啄木 > 没有就着人间疾苦一边呷一口酒，我很难体会到石川啄木的苦难和哀痛。但是这些以血写成的诗歌，其间蕴藏着无穷情感，并不出乎意料地温柔地和我相通。有时候是触景伤情——冰川下冻住的河流，树林里响起索索风声，闪光的海面倒映着冬天的月。 > 有时仅仅是为的琐事烦恼——有没有那一种药？淡绿色的，喝了会使身体像水似的透明的药？感慨之余，忽然想到当初是想看双语版来着，顺便学习些日语也好。不得不说的是，这版的翻译很精彩，恰到好处。 - 《前端工程化：体系设计与实践》@周俊鹏 > 好几口气才看完，前面的概念的部分有点过于枯燥，不过后面涉及到技术的部分讲的挺清楚的。总的来说还行 ～ - 《日本未来时》@ [美] 真澄· 华盛顿 编， [美] 尼克·马马塔斯 编， [日] 飞浩隆， [日] 小川一水， [日] 伊藤计划， [美] 刘宇昆， [日] 菊地秀行， [日] 円城塔， [美] 菲丽希蒂·萨瓦奇， [美] 戴维·莫尔斯， [美] 蕾切·斯沃斯基， [美] 帕特·卡迪根， [美] 凯瑟琳·M·瓦伦特， [俄] 叶卡捷琳娜·塞蒂亚， [美] 布鲁斯·斯特林，圆城塔 > 最近都在看日本相关的作品，就连这本科幻短篇也是。\n《日本未来时》不仅有孤寂的宇宙行星和涂满绚烂花纹流浪的机甲，它给我更大的感受是可遇不可求，刹那间自我联结万物，宛若神性一般的物哀美学。 > :br > 太漂亮了，内容，封面，书签，一本满足！ - 《一只特立独行的猪》@王小波 > 90/100 可能是先读鲁迅的杂文使我患上了心力不足的症状，小波书中展现的那种独特的黑色幽默气质，倒成了管用的一味良药。我能在小波身上找到一些与自身相仿的气质和价值观，令我欣喜又畅快。尽管还没到要成为做小波“门下走狗”那种地步， > 倒是也是满是欢喜——首先是读杂文要比读小说有劲道多了，写的明白，讲得清楚，再好不过。若是能旁征博引，据理力争，对我而言那简直完美，五星好评不为过。再是本书除了杂文，还有大篇幅的序跋， > 两种文体中高频出现的一些词可以结合起来还原作者接触的作品及他的“有趣”的世界观。十分有继续探索的价值 hhhh - 《人类群星闪耀时》@ [奥地利] 斯蒂芬·茨威格 > 第一章后弃坑，并不是书的问题。而是书中大量地理位置名词，人物名词然后我感到迷茫，束手无策。我记得上一次碰到这种情况，还是巴拉巴西的<爆发>，也是看得脑瓜疼。至于第一章能看完，存粹是因为玩过大航海的游戏，对大航海这段历史有着迷之喜爱之情。 > 天晓得我为什么会点进来看这本，天晓得我什么时候会再捡起来看。因为没有看完，留个三星中评。 - 《JavaScript 面向对象精要》@Nicholas C. Zakas > 对这本书期望挺高的（主要是封面和作者不错啊 ～ 可以 是熟悉的红宝书味道 86/100 ～ - 《JavaScript 忍者秘籍》@John Resig,Bear Bibeault > 第一版距现在（2019）有些时候了，不过大佬写的书就是不一样：除了浏览器兼容性那部分有些与现代 JS 脱节之外，JS 本身的那部分高级特征讲得很清楚，代码与解析都很 nice。无比期待第二版的阅读体验 ～ - 《JavaScript 启示录》@Cody Lindley > 总的来说还行 55/100 的样子。比较不错的地方是作者能用一些简单的代码，把一些 JS 原理描述出来，并且狼吞这本书后发现有好些内容确实挺有帮助的。缺点也很明显，作者写书简直就想记博客，再加上书中知识点深浅不一，有点难受。书名叫「 > 启示录」过分了哈哈哈 - 《编写可维护的 JavaScript》@ [美国] 尼古拉斯·泽卡斯 > 总的还说赶 jio 不错，整书主要分三个段落，1⃣️首先是基础代码风格部分，作者比较了几种常见的代码风格并描述了其某些优缺点供读者参考。2⃣️第二部分应该划分为 JS 一些高级特征下的代码风格，讲得不错。 > 3⃣️最后一部分大致为如何使用一个叫 Ant 的构建工具对代码进行管理，我有点想吐槽作者的编程工具的倾向性，构建工具（或者任务流工具）不选用 Webpack 或是 Gulp，与当下前端环境脱节有些严重了 hhh。 > 🌟豆瓣的评分颗粒度太大了些 TOT，如果是 10 分制我觉得 7 分比较合适些。如果图书再版替换某些脱节内容的话，那么毫无疑问是满分好评啦～ - 《JavaScript 语言精粹》@Douglas Crockford > 薄薄一本，又充满学识的书，其中也有些很值得体会把玩的编程经验。五星推荐。倒是若说到编程实践，我一定会选择 JS 忍者秘籍 hhhh - 《TIGER×DRAGON1!》@ [日] 竹宫悠由子 著， [日] 泰 绘 > 感觉动画更有意思些～ - 《心理罪：城市之光》@雷米 - 《心理罪》@雷米 - 《如何阅读一本书》@ [美] 莫提默·J. 艾德勒，查尔斯·范多伦 > 该怎么评价呢 hhhh... 看电子书和看纸书的感觉完全不一样，所以方法论这种东西也是会过时的，得随实际情况应变。至于书中描述的方法是否能实际运用，感觉与读者自身水平关系很大。就像看记忆魔法书看学习之道那些书籍，我经常会有“顿悟” > 的感受，在那一刻会有种通过书中文字找回自我的感觉，然而令我遗憾的是我在此书中鲜找到自我，也许再看十年书培养培养感觉？～ - 《乌合之众》@ [法] 古斯塔夫·勒庞 > 有些观点还是挺有意思的 - 《天才在左 疯子在右》@高铭 - 《史蒂夫·乔布斯传》@ [美] 沃尔特·艾萨克森 > 哦～ 好书～ 读传记给人带来的那种穿越时空的错觉真是让人留念。我还记得我坐在乔布斯旁边吸过致幻剂 hhh - 《水知道答案》@江本胜 - 《尖叫感》@马楠 > 不错 非常具有启发意义 （当然 实践价值更大）hhhh - 《老人与海》@ [美] 欧内斯特·海明威 - 《深入浅出 Vue.js》@刘博文 > 确实是深入浅出，用很简短的代码就呈现了一个近乎完整的模板解析过程，但由于 Vue2 其它部分代码更简单一些，其它章节读起来就稍显乏味了。希望在新书中看到更多作者对软件设计、软件工程相关的理解。 - 《人月神话》@ [美] 弗雷德里克·布鲁克斯 > 应该多看几眼的～ 忘了很多惹 - 《三体》@刘慈欣 > 借了来实体书一口气看完了，非常不错，喜欢科幻的不能错过 - 《龙族Ⅲ》@江南 > 我的挚爱 - 《浅薄》@ [美] 尼古拉斯·卡尔 - 《你不知道的 JavaScript（上卷）》@ [美] Kyle Simpson > 力荐 得找机会再补补～ - 《高性能网站建设指南》@Steve Souders > 好书啊～ 拯救了我的毕业论文 hhhh - 《爆发》@ [美] 艾伯特-拉斯洛·巴拉巴西 > 我记得好像是看到一半弃坑了，对我来说最困难的地方在于记住歪果仁那些长长的名字～ - 《写给大家看的设计书（第 3 版）》@ [美] Robin Williams - 《心流》@ [美] 米哈里·契克森米哈赖 > 精彩～ 读到精彩篇章时那种感同身受的感觉至今难忘 - 《谁杀了她》@日 东野圭吾 > 没看懂～ 讲道理我应该再看一遍 - 《亲密关系：通往灵魂的桥梁》@ [加] 克里斯多福•孟 > 想看一本同名书，不过因为 Kindle 会免一激动看叉了|ω•\`) ～ 本书的前三章还是有些意思的，四五章觉得草率了一些。书中对自我、灵魂、爱这些名词的解释感觉像蒙着一层纱布。而作者作为一个“不断摔跤”的实践者， > 我感觉他已经触摸到了亲密关系中问题的存在，并提出了问题，可是由于没有建立在学术的根基上，没有很好的解决以及总结问题。希望我在其他书中能找到解决方案 ～～ - 《破耳兔：你不完美的样子也很好》@麦可洛克 - 《莫泊桑短篇小说精选》@ [法] 莫泊桑 - 《黑客与画家》@ [美] Paul Graham - 《学习之道》@ [美] 乔希·维茨金 - 《銃夢 09》@木城幸人 - 《銃夢 08》@木城幸人 - 《銃夢 07》@木城幸人 - 《銃夢 06》@木城幸人 - 《銃夢 05》@木城幸人 - 《銃夢 04》@木城幸人 - 《銃夢 03》@木城幸人 - 《銃夢 02》@木城幸人 - 《銃夢 01》@木城幸人 - 《国王 武士 祭司 诗人》@ [美] 罗伯特·摩尔， [美] 道格拉斯·吉列 > 虽然说引证丰富，有些章节段落描绘的并不清晰，同时栗子也颇经验主义化了，同时，我在书中常看翻译不妥当的地方，尤其是前半部分。总的来说，是一本不错的荣格原型心理学启蒙书，并且对了解自身的内驱力做了很棒的科普。 - 《人间失格》@太宰治 > 太宰治能用平白的描述，穿透时间与空间，让读者产生莫大的共鸣。日本文学入坑的第一个作者，我被他深深震撼了。 - 《啊哈！算法》@啊哈磊 ### 豆瓣备份 豆瓣数据导出用的是一个浏览器插件，叫 [“豆伴”](https://github.com/doufen-org/tofu){rel=""nofollow""}。 # 🎸 FingerStyle！ ## 我的设备 截至 2022，手头的主力设备清单： - 吉他：曼森 MS5 ce - MIC：罗德 NT-5 pair - 录像：iPhone 12 & 卡色人像镜 - 声卡：Yamaha UR44C - 后期：Audition - 监听：ACG K701 & WH-1000XM4 ## 常见问题 有xxx的谱子吗？ 很遗憾，没有。我弹琴大部分时候会按原版谱学习，不过等左右手熟练以后就会把谱子扔掉。这时我可能会进行一些我不在意的改动。这样做显然会带来明显的坏处，请大家不要模仿。 目前手上就一把琴？ 是的，目前我所有视频都是用这把琴录制的。这把曼森是在大学时某比赛中拿的，至于其它琴，我好像不怎么能回忆起它们的下落了。以后存了钱我想再入手一把 Headway Sakura，我觉得它非常漂亮，无论是外观还是音色。不过目前来说这把曼森已经能满足我当前的外录需求，私底下我认为换琴弦对琴音色的提升其性价比会比换琴高得多。 有推荐的录音设备吗？ 麦克风我曾用过两年的 Line6 Sonic Port VX。从各个角度（除了动态）我都觉得比我现在手上的 NT-5 要好一些，只是不知怎么就坏掉了，才换新款。至于声卡，我觉得 UR44C 对我来说刚刚好，因为他有 4 个入口，能满足我一对 NT-5 以及吉他拾音器三个通道的录制。 能讲讲怎么做后期吗？ 鉴于后期我非常业余，这里简单介绍一下我的后期思路，仅供参考：首先录制一段非常长的音频，一直重复弹一首曲子，直到满意为止。其中如果有明显的瑕疵，这时看心情考虑重录或者后期修复。拿到录音素材后，先粗剪成一首曲子。然后是降噪，一般关掉吉他拾音器然后用一段空白的录音捕获室内噪音，再用 Audition 的噪音模型降噪；接着调 EQ，依喜好调成想要的音色；再是立体声扩展，把低中高频分离出来，创造环绕效果；最后是加混响。由于我觉得 ACG K701 的听感和市面上大部分耳机相比有非常大的差异，所以我一般只在录音时使用 K701 而在后期时使用 WH-1000XM4。 还会继续更新么？ 我花了很长的时间来思考我和吉他的关系，得到的结论之一是：掌握一门技艺是一件美好的事情，但精进它却需要投入充足的精力与财力。鉴于我的时间和热情在近几年逐渐下放到编程中，所以，在可预见的五年内，我不会继续练习吉他以及其它乐器。如果有的话，em，我是说如果，那一定会是非常简单的曲子。 ## 回忆 有关吉他的一些回忆：[《长夜梦》](https://lionad.art/flows/long-night-dream) # 🌬️ 等待的风 :iframe[\ 评论]{allowFullScreen="true" border="0" frameBorder="no" framespacing="0" scrolling="no" src="https://lionad.art//player.bilibili.com/player.html?aid=87893912&bvid=BV1t741147kV&cid=150164575&page=1" style="width: 100%;height: 570px;max-height: 100vh;border: solid 1px #888;"} > up！我来啦！为了你开启了我的网易云人生 > :name[是张新成现女友] > 居然网易云的音频这么好！qq没有原版的…感谢网易！ > :name[GuitarHero] > 跟随风吹过的痕迹，寻找所爱之人的声音 > :name[待灬定] > 大海发出的一股新鲜气息，还了我灵魂 > :name[殇-酌] > 呜呜呜太温柔了叭 是我的小狮子大男孩了 > :name[雪雪患上拖延症了] > Le vent se lève, il faut tenter de vivre > :name[Lionad\_Guirotar] # 💕 约定的海洋 ```text 多少个夜晚， 我听到大海的轻涛细浪， 拍打柔和的海滩， 抒出了一阵阵温情的， 软声款语。 两颗和着浪花翻腾的心， 代表着的， 是激情，还是永恒呢？ ``` :iframe[\ 网易云b站掘金三方关注的粉丝来赞一发哈哈哈 \Raptazure\]{allowFullScreen="true" border="0" frameBorder="no" framespacing="0" scrolling="no" src="https://lionad.art//player.bilibili.com/player.html?aid=98311395&bvid=BV1nE411F7WE&cid=167821840&page=1" style="width: 100%;height: 570px;max-height: 100vh;border: solid 1px #888;"} > 所以疫情也算过了，头发剪了没，精神小伙没，小星星开练了没🤩 > :name[raydezio] > 多少个夜晚， :br > 我听到大海的轻涛细浪， :br > 拍打柔和的海滩， :br > 抒出了一阵阵温情的， :br > 软声款语。 :br > 两颗和着浪花翻腾的心， :br > 代表着的， :br > 是激情，还是永恒呢？ :br:name[Lionad-Guirotar] # 🎼 Wings~You are the Hero！ :iframe[\

    \网易云直达\ 愿你们梦想成真! Lionad\_Guirotar]{border="0" frameBorder="no" height="150" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=1315927375&auto=0" width="355"} > 吉他越玩越坚信，果然练琴和做题一样，不天天坚持练，是出不了成绩的啊，希望有一天也能弹会这首曲子 [多多大笑]:name[静看时光过隙] > 还记得在大学时听你在练这首歌，哈哈哈 > :name[茶茶-cc] # 🌏 残酷天使的行动纲领 :iframe[\

    \网易云直达\ \

    \ 终于找到这个版本了 \沧海\_墨辰觞\]{border="0" frameBorder="no" height="150" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=535590199&auto=0" width="355"} > 2018，使徒没有袭来。再次打开我的eva光碟，所带给我的已经不仅是热血了，更多的是对逝去的时光的缅怀与无奈 > :name[帐号已注销] > 简直是非常棒的cover了！听到这首猛抬头哈哈哈哈！点❤️收藏一气呵成哈哈哈！非常感谢Lionad了 带给我们这么棒的曲子！非常棒！非常有感觉有气势的！ > :name[老攻我歇一会儿] > 我的年度歌手是您呀❤ > :name[Wukiss] > ⊙∀⊙！喜欢这个！ > :name[月鹿同学] > 我的曲库里一定要有残酷天使的行动纲领这个曲子，带着这样的心情，专门找了一圈儿，最后留下了这个吉他版本 > :name[inostay] > 弹得超棒，关注了 > :name[博丽灵梦01] # 🏔️ 奇跡の山 :iframe[\

    \网易云直达\ \

    \ 正在学这首曲子，很好听，还有十多天中考了，加油❤ \JX-Tiamo\]{border="0" frameBorder="no" height="150" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=1323087576&auto=0" width="355"} > 听着觉得这版像凌晨，原版像黎明，矫情了 > :name[SunSunSunStar] > 打开电视，戴上耳机，声音充斥整个房间，我一个人听着，想了想，想睡觉。 > :name[亚唐时代] > 忘记从哪个摇滚还是金属的群里关注的作者了??? 万万没想到，是个弹岸部的文艺青年 > :name[帐号已注销] > Lionad，我是北方死宅莱茵金属啊！借母上的手机来评论啦！支持你啊！ > :name[威粘-米尔湿] > 来晚了，记得这首曲子是大一刚开学睡不着的时候经常会听的一首，非常感谢大佬再次让人想起那段日子。🏻 > :name[新月之舞] > 是什么让我深夜不睡，啊，这位老弟 > :name[雪雪患上拖延症了] > 每首曲子弹的都好好听，我都很喜欢耶 > :name[越陌度阡cwl] > 音质变好了奈斯 > :name[MX-LI] # 🍷 Wu Wei :iframe[\ 去听魔笛的版本, 魔笛大佬的版本真的强 \Lionad\_Guirotar\]{allowFullScreen="true" border="0" frameBorder="no" framespacing="0" scrolling="no" src="https://lionad.art//player.bilibili.com/player.html?aid=842828558&bvid=BV1154y1z7ky&cid=256303420&page=1" style="width: 100%;height: 570px;max-height: 100vh;border: solid 1px #888;"} > 想当年上高中时候我俩在寝室每天对着谈，你还记得一起谈天空之城的时候吗，现在表哥为了生活，不得不放弃了吉他🎸 > :name[爱我还是爱音乐] > 这个如果有视频，手应该会眼花缭乱的，超好看吧…… > :name[月鹿同学] # 🌅 无题 :iframe[\

    \网易云直达\ \

    \ 根本没人关心你写的是什么，也没人会看完你的长篇大论，更不会有人注意到你发完秒删，欲言又止的话，大家都是幸福快乐，安安稳稳的睡觉，睡醒后刷一下手机，然后感慨一句：这傻了吧唧 一天到晚的。 \小木易\]{border="0" frameBorder="no" height="150" marginHeight="0" marginWidth="0" src="https://lionad.art//music.163.com/outchain/player?type=2&id=520847330&auto=0" width="355"} > 弹完了 舍友问我 为什么不唱 [多多捂脸]:name[薛三岁9425] > 听完这首歌又激起了我练吉他的激情，于是我从满是灰的柜子里拿出了我满是灰的吉他，深情地弹了一首53231323 > :name[改个昵称还要积分] > 等我学会了一定回来评论 > :name[嘎嘣儿先生] # 🏁 知识地图 此目录下内容性质接近笔记。部分内容已过时，或包含许多实质性错误，部分内容由 AI 辅助完成，参考时请注意核对。 分类方法： 1. 将笔记按领域、主题、子主题三层级划分 2. 主题、子主题的数量最多为 10 个 3. 按领域组织而不是交叉引用零散的知识点 ## 前端 - [前端技术](https://lionad.art/maps/_frontend/frontend) - CSS、HTML、JavaScript、W3C 标准 - [TypeScript](https://lionad.art/maps/_typescript/typescript) - [前端框架](https://lionad.art/maps/_fe-framework/fe-framework) - [SEO](https://lionad.art/maps/_seo/seo) ## 工程 - [前端工程化](https://lionad.art/maps/_workflow/engineering/fe-engineering) - [Monorepo](https://lionad.art/maps/_workflow/monorepo/monorepo) - [包管理器](https://lionad.art/maps/_workflow/package-manager/package-manager) - [构建工具](https://lionad.art/maps/_workflow/build-tools/build-tools) - [编译器](https://lionad.art/maps/_workflow/compiler/compiler) - [代码规范](https://lionad.art/maps/_workflow/linter/linter) - [DX](https://lionad.art/maps/_programming/dx/dx) ## Web - [浏览器](https://lionad.art/maps/_web/browser/browser) - [页面性能](https://lionad.art/maps/_web/performance/performance) - [爬虫](https://lionad.art/maps/_web/crawler/crawler) - [安全](https://lionad.art/maps/_web/security/security) ## 跨端 - [小程序](https://lionad.art/maps/_web/miniapp/miniapp) - [React Native](https://lionad.art/maps/_react-native/react-native/react-native) - [跨平台开发](https://lionad.art/maps/_cross-platform/taro) - Taro、Flutter、Device Metrics ## 服务端 - [Server](https://lionad.art/maps/_server/server) ## 数据库 - [NoSQL](https://lionad.art/maps/_database/nosql/nosql) - Redis 缓存与数据结构 - [DataLake](https://lionad.art/maps/_database/datalake/datalake) - 数据湖与大数据存储 - [DeltaLake](https://lionad.art/maps/_database/deltalake/deltalake) - Delta Lake 存储层与优化 - [Lakehouse](https://lionad.art/maps/_database/lakehouse/lakehouse) - 湖仓一体架构 - [SQL](https://lionad.art/maps/_database/sql/sql) - SQL 查询与关系型数据库 - [GraphQL](https://lionad.art/maps/_database/graphql/graphql) - GraphQL 查询语言与数据访问 ## 测试 - [软件测试](https://lionad.art/maps/_test/test) ## 应用 - [IDE](https://lionad.art/maps/_ide/ide) - [命令行工具](https://lionad.art/maps/_cli/cli) - ffmpeg、imagemagick 等 - [应用](https://lionad.art/maps/_apps/apps) - VPN 等工具 - [网页开发](https://lionad.art/maps/_web-pages/web-pages) ## 计算机 - [计算机网络](https://lionad.art/maps/_computer/network/network) - [组成原理](https://lionad.art/maps/_computer/fundamentals/fundamentals) - [编码](https://lionad.art/maps/_computer/encoding/encoding) ## 系统 - [Linux](https://lionad.art/maps/_linux/linux) - [macOS](https://lionad.art/maps/_system/macos) - [Windows](https://lionad.art/maps/_windows/windows) ## 硬件 - [硬件](https://lionad.art/maps/_hardware/hardware) ## 软件 - [软件工程](https://lionad.art/maps/_software/software-engineering/software-engineering) - [Whale Fall](https://lionad.art/maps/_software/whale-fall/whale-fall) - 大型开源项目的生态演替 - [函数式](https://lionad.art/maps/_programming/paradigms/paradigms) - [面向对象](https://lionad.art/maps/_oop/oop/oop) - [设计模式](https://lionad.art/maps/_software/design-patterns/design-patterns) - [数据结构](https://lionad.art/maps/_software/data-structure/data-structure) - [算法](https://lionad.art/maps/_software/algorithm/algorithm) - [技术偏见](https://lionad.art/maps/_programming/programming) - [Rezi](https://lionad.art/maps/_programming/frameworks/frameworks) - TypeScript TUI 框架 ## 编程语言 - [C++](https://lionad.art/maps/_cpp/cpp) - [Markdown](https://lionad.art/maps/_markdown/markdown/markdown) - [Regex](https://lionad.art/maps/_regex/regex/regex) - [PHP](https://lionad.art/maps/_php/php/php) - [Go](https://lionad.art/maps/_go/go/go) - [Python](https://lionad.art/maps/_python/python) - [编程语言](https://lionad.art/maps/_programming/languages/languages) ## 架构 - [云原生（CloudNative）](https://lionad.art/maps/_cloud-native/cloud-native) - [无服务（Serverless）](https://lionad.art/maps/_cloud-native/serverless/serverless) ## 项目 - [DevOps](https://lionad.art/maps/_devops/devops) - DevOps 实践与理论 - [版本控制](https://lionad.art/maps/_devops/version-control/version-control) - Git、版本管理与工作流 - [CI/CD](https://lionad.art/maps/_devops/cicd/cicd) - 持续集成与持续部署 - [容器](https://lionad.art/maps/_devops/container/docker) - Docker 容器技术 - [日志](https://lionad.art/maps/_devops/logging/rotatelogs) - 日志轮转与管理 - [项目管理](https://lionad.art/maps/_manage/manage) ## 产品 - [产品经理](https://lionad.art/maps/_product/product-manager/product-manager) - [产品设计](https://lionad.art/maps/_product/product) - [运营](https://lionad.art/maps/_product/operation/operation) - [增长](https://lionad.art/maps/_product/growth/growth) ## 文档 - [文档](https://lionad.art/maps/_docs/docs) ## 行业 - [数字化](https://lionad.art/maps/_industry/digital) - [低代码](https://lionad.art/maps/_industry/low-code) - [行业报告](https://lionad.art/maps/_industry/analytics) - [游戏](https://lionad.art/maps/_game/game/game) ## 商业 - [商业分析](https://lionad.art/maps/_business/analysis/business-analysis) - [风险投资](https://lionad.art/maps/_business/venture-capital/venture-capital) - [创业](https://lionad.art/maps/_business/startup/startup) - [注册公司](https://lionad.art/maps/_company/business/company) ## 管理 - [组织](https://lionad.art/maps/_management/organization/organization) - [沟通](https://lionad.art/maps/_communication/communication) ## 政治 - [政治](https://lionad.art/maps/_politics/republic) - 政体形式、政治经济学 ## 政策 - [政策](https://lionad.art/maps/_policy/policy) ## AI - [人工智能](https://lionad.art/maps/_ai/ai) - Copilot、AIGC、机器学习 ## UI - [界面设计（UI）](https://lionad.art/maps/_ui/ui) - [字体排版](https://lionad.art/maps/_ui/typography/typography) ## 可视化 - [可视化](https://lionad.art/maps/_visual/visualization/visualization) - [信息设计](https://lionad.art/maps/_visual/info-design/info-design) ## 渲染 - [C4D](https://lionad.art/maps/_render/c4d) - [Shader](https://lionad.art/maps/_render/shader) ## 科学 - [神经科学](https://lionad.art/maps/_science/neuroscience/neuroscience) - [熵](https://lionad.art/maps/_science/entropy/entropy) - [宇宙](https://lionad.art/maps/_science/cosmos/cosmos) - [量子](https://lionad.art/maps/_science/quantum/quantum) - [复杂科学](https://lionad.art/maps/_science/complex-science/complex-science) - [环保](https://lionad.art/maps/_science/environment/environment) ## 兴趣 - [阅读](https://lionad.art/books) - 书籍笔记与阅读清单 - [摄影](https://lionad.art/maps/_photography/techniques/techniques) - [人物](https://lionad.art/maps/_person/person) - [游戏](https://lionad.art/maps/_games/games) - [博客订阅](https://lionad.art/maps/_blogs/blogs) - Feeds、资讯聚合 - [跨域笔记](https://lionad.art/maps/_cross-domain/cross-domain) - 跨领域思考 - [产品观察](https://lionad.art/maps/_products/products) - 产品分析与研究 - [~~指弹~~](https://lionad.art/music) - [逃离塔克夫](https://lionad.art/maps/_games/games/escape-from-tarkov) ## 生活逻辑 - [医疗](https://lionad.art/maps/_medicine/medicine/medicine) ## 工作 - [面试技巧](https://lionad.art/maps/_interview/reverse-interview) - [前端实习问题](https://lionad.art/maps/_hire/intern) ## Threads - [Daily Bugs](https://lionad.art/maps/_threads/daily-bugs) - [Bills](https://lionad.art/maps/_threads/bills) # Agents ## 四层认知结构 本笔记系统采用 **Domain → Subdomain → Topic → Knowledge Point** 的四层认知结构： | 层级 | 定义 | 物理形式 | 判断标准 | | ------------------------- | --------- | ------------------- | ------------------------------- | | **领域 (Domain)** | 最高层级的知识边界 | `_domain/` 目录 | 存在于 `0.index.md` 导航中，目录以 `_` 开头 | | **子领域 (Subdomain)** | 领域内的专业分支 | `subdomain/` 子目录或文件 | 构成独立学习单元，有明确知识边界 | | **主题 (Topic)** | 具体的技术点或概念 | `.md` 文件 | 文件内使用 H1 (`#`) 作为标题 | | **知识点 (Knowledge Point)** | 原子化的思考性内容 | `####` 四级标题 | 观点、案例、洞见，保持阅读连续性 | **决策原则：** - 子领域统一使用目录形式，不按内容量区分 - 主题超过 150 行或有扩展潜力时拆分为独立文件 - 知识点不得拆分为独立文件，保持为四级标题 ## 笔记系统结构 核心内容位于 `content/6.maps/` 目录，工具收集位于 `content/7.tools/`： ```text content/ ├── 6.maps/ # 知识地图（主要笔记目录） │ ├── _ai/ # AI 技术与应用 │ ├── _architecture/ # 架构设计 │ ├── _biology/ # 生物学与生命科学 │ ├── _business/ # 商业分析 │ ├── _cloud-native/ # 云原生技术 │ ├── _communication/ # 沟通协作 │ ├── _computer/ # 计算机基础 │ ├── _cross-platform/ # 跨端开发 │ ├── _database/ # 数据库 │ ├── _devops/ # DevOps │ ├── _fe-framework/ # 前端框架 │ ├── _frontend/ # 前端技术 │ ├── _game/ # 游戏设计 │ ├── _games/ # 游戏体验 │ ├── _hardware/ # 硬件 │ ├── _hire/ # 招聘与面试 │ ├── _industry/ # 行业研究 │ ├── _interview/ # 面试技巧 │ ├── _linux/ # Linux 系统 │ ├── _management/ # 管理学 │ ├── _medicine/ # 医疗知识 │ ├── _person/ # 人物笔记 │ ├── _politics/ # 政治与政治经济学 │ ├── _product/ # 产品与运营 │ ├── _programming/ # 编程语言与范式 │ ├── _react-native/ # React Native │ ├── _refactor/ # 重构 │ ├── _render/ # 渲染技术 │ ├── _science/ # 科学 │ ├── _server/ # 服务端 │ ├── _software/ # 软件工程 │ ├── _system/ # 操作系统 │ ├── _test/ # 测试 │ ├── _threads/ # 日常记录 │ ├── _ui/ # UI 设计 │ ├── _web/ # Web 技术 │ ├── _web-app/ # Web 应用 │ ├── _web-pages/ # 网页开发 │ ├── _workflow/ # 工作流 │ ├── _cpp/ # C++ │ ├── _go/ # Go │ ├── _markdown/ # Markdown │ ├── _php/ # PHP │ ├── _regex/ # 正则表达式 │ ├── _typescript/ # TypeScript │ └── Agents.md # 本文件 │ ├── 7.tools/ # 工具收集 │ └── *.md # 各类工具链接与介绍 │ └── _books/ # 读书笔记 ``` ## 文件格式规范 ### Frontmatter 格式 ```yaml --- title: [标题] description: [简介] --- ``` ### 知识点格式 - 使用 `####` 四级标题作为知识点标题 - 内容简洁，保留关键信息 - 包含来源链接（简单常识性概念除外） ```markdown #### [知识点标题] [内容描述] 见：[链接标题](链接地址) ``` ### 人物笔记格式 ```yaml --- title: [姓名] description: [身份/职业] --- #### 简介？ [简介内容] #### 主要贡献/观点？ [要点] 见：[链接](URL) ``` ## 智能体引用 本文件供 distill-and-archive 技能引用，用于指导知识点归档的目录选择和格式规范。 - **知识地图路径**：`content/6.maps/_//.md` - **工具收集路径**：`content/7.tools/.md` - **索引文件**：`index.md` 或 `0.index.md` - **新增分类**：新建 `_` 目录并在 Agents.md 中更新 - **新增工具**：直接归档到 `content/7.tools/`，并在 `7.tools/0.index.md` 中添加索引 ## 规划文档 详细的分类标准和重构规范： - `.planning/taxonomy-criteria.md` - 四层认知结构判断标准 - `.planning/PROJECT.md` - Maps 知识库重构项目概述 - `.planning/codebase/STRUCTURE.md` - 项目结构文档 ## 归档洞察 #### Skills 作为分销渠道的商业洞察 - **技能即分销渠道**：当 Skill 默认使用特定 API 或厂商时，该厂商就被选中，无需销售电话或定价页面 - **第三买方**：技能作者成为新的买方，他们决定 Agent 使用哪些工具 - **定价难题**：技能免费（纯文本），价值在于它路由到的服务 - **垂直领域的持久性**：水平技能（代码审查、调试）会快速商品化，但编码 FDA 提交流程等垂直技能需要领域知识 - **Freemium 的崩溃**：用户可以用 Prompt 快速构建 60% 需求的解决方案，免费层不再构成转化漏斗 - **最佳可用人类标准**：AI 不需要比最好的专家更好，只需要比用户能获得的帮助更好 - **护城河转移**：从"隐藏护城河"到"直接赠送护城河"，真正的价值是领域理解而非代码 见：[I know Kung Fu](https://www.sideband.pub/p/i-know-kung-fu){rel=""nofollow""}、 [The Ghost in the Funnel](https://worksonmymachine.ai/p/the-ghost-in-the-funnel){rel=""nofollow""} # A2A Protocol ## 概述 A2A（Agent-to-Agent）协议是 Google 于 2025 年 4 月发布的开放标准，旨在解决不同 AI 智能体之间的互操作性问题，允许不同供应商、框架和平台的智能体跨系统安全协作，打破"信息孤岛"。 见：[Google A2A 官方文档](https://developers.google.com/agent-to-agent){rel=""nofollow""} | [A2A 协议规范](https://github.com/google/A2A){rel=""nofollow""} ## 核心设计原则 #### 能力发现（Capability Discovery） Agent 可动态发现其他 Agent 的能力，无需预先硬编码集成逻辑。通过标准化的能力描述格式，Agent 能理解其他 Agent 可以执行什么任务。 #### 任务管理（Task Management） 支持多 Agent 协作完成复杂任务，包含任务创建、状态跟踪、结果返回的全生命周期管理。 #### 多模态通信（Multimodal Communication） 支持文本、图像、音频、视频等多种数据格式的交换，适应不同场景需求。 #### 用户体验协商（User Experience Negotiation） Agent 可协商如何向用户呈现结果，支持多种交互模式（同步/异步、流式/一次性返回等）。 #### Agent Card 与本地网络发现 A2A 通过 Agent Card 让智能体互相发现能力。Agent Card 是一份 JSON 文档，描述 agent 的身份、服务端点、能力、认证方式和技能列表，通常暴露在 `/.well-known/agent-card.json`。 对于局域网场景，A2A 社区提出了 LAD-A2A（Local Agent Discovery for A2A）草案，支持 mDNS/DNS-SD（`_a2a._tcp`）、well-known endpoint、 DHCP Option 和 QR/NFC 四种发现机制，按优先级 fallback。由于局域网并非默认可信，LAD-A2A 要求所有端点使用 HTTPS、Agent Card 必须经过 JWS 或 DID 签名、用户显式同意连接， 并按最小权限授予能力。 见：[A2A Agent Discovery](https://a2a-protocol.org/latest/topics/agent-discovery/){rel=""nofollow""}、[LAD-A2A Specification](https://lad-a2a.org/spec/){rel=""nofollow""} #### ACP 与 A2A 的合并 ACP（Agent Communication Protocol）最初由 IBM Research 于 2025 年发布，定位是让不同框架、语言和运行环境的 AI 智能体通过 REST 接口互相通信。它支持单 agent 单 server、 多 agent 单 server、分布式多 server 以及 Router Agent 等部署模式，后者还会通过 MCP extension 调用下游 agent 的工具。2025 年下半年， IBM 宣布将 ACP 并入 Google 的 A2A（Agent-to-Agent）协议，转由 Linux Foundation 统一治理。这意味着当前协议栈已经分层：MCP 解决 agent 与工具/数据的连接，A2A（ 含 ACP 遗产）解决 agent 与 agent 的协作。 见：[Agent Communication Protocol Architecture](https://agentcommunicationprotocol.dev/core-concepts/architecture){rel=""nofollow""}、[A2A vs ACP vs MCP Compared](https://codex.danielvaughan.com/2026/05/29/agent-to-agent-communication-protocols-a2a-vs-acp-vs-mcp-compared/){rel=""nofollow""}、[IBM's ACP technical overview](https://workos.com/blog/ibm-agent-communication-protocol-acp){rel=""nofollow""} ## A2A vs MCP A2A 与 MCP（Model Context Protocol）是互补关系： | 协议 | 解决的问题 | 类比 | | --- | ------------------- | ------ | | MCP | Agent 与工具/资源的连接 | USB 接口 | | A2A | Agent 与 Agent 之间的协作 | 网络协议 | MCP 让 Agent 能调用外部工具和访问资源，A2A 让 Agent 能与其他 Agent 协作完成更复杂的任务。 见：[MCP 与 A2A 对比](https://cloud.google.com/blog/products/application-modernization/mcp-and-a2a){rel=""nofollow""} ## 案例：希希咖啡店 **希希咖啡店**是基于 Google ADK 框架和 A2A 协议构建的多 Agent 协同案例，展示了企业级多业务系统的 Agent 集成方案。 ### 架构设计 采用**通用智能体 + 业务领域 Agent** 的分层架构： | 组件 | 角色 | 职责 | | ------------ | -------- | ------------------------------- | | 寒小艾（主 Agent） | 通用智能体 | 意图识别、任务分发、对话管理 | | 希希咖啡店 Agent | 业务 Agent | 咖啡点单、菜单查询、订单管理 | | 送了么 Agent | 业务 Agent | 配送调度、物流跟踪 | | 后端服务 | OpenAPI | 业务逻辑实现，通过 FunctionAI Toolset 接入 | ### 交互流程 **场景：用户下单并配送** ```text 用户："帮我点一杯大杯拿铁，配送到中关村大厦" 寒小艾（意图识别）→ 希希咖啡店 Agent（创建订单）→ 后端（订单系统） → 送了么 Agent（创建配送单）→ 后端（配送系统） 返回："订单已确认，预计 30 分钟送达，配送费 5 元" ``` ### 技术亮点 - **业务解耦**：各业务线独立开发部署，通过 A2A 协议协同 - **OpenAPI 快速集成**：现有 REST API 通过 FunctionAI Toolset 快速转化为 Agent 工具 - **云原生部署**：基于阿里云函数计算，支持弹性伸缩、按量付费 见：[希希咖啡店 GitHub](https://github.com/agentrun-ai/buy-me-a-coffee){rel=""nofollow""} ## 实践建议 #### 何时使用 A2A？ - 多业务系统需要 Agent 化协同 - 不同团队独立开发 Agent 需要互联互通 - 构建 Agent 生态系统，支持第三方 Agent 接入 #### 实施路径 1. **现有 API Agent 化**：通过 OpenAPI 规范快速接入 2. **通用 Agent 设计**：负责意图识别和任务分发 3. **业务 Agent 解耦**：按业务域划分 Agent 边界 4. **标准化协议对接**：遵循 A2A 协议进行能力注册和调用 见：[Google ADK 文档](https://developers.google.com/agent-development-kit){rel=""nofollow""} | [A2A 快速入门](https://developers.google.com/agent-to-agent/quickstart){rel=""nofollow""} #### A2A 与 MCP 的桥接 A2A 与 MCP 可以互补使用：一个 agent 通常同时是 MCP client（调用自己的工具）和 A2A client/server（与其他 agent 协作）。 工程上常见的桥接模式是把 A2A agent 包装成一个 MCP server，使其对外表现为一个普通 MCP tool。这样，Claude Code 等 MCP host 无需原生支持 A2A，也能调用远程 agent 的能力。 ACP 的 Router Agent 模式也采用了类似思路，通过 MCP extension 把下游 agent 的工具暴露给上层编排器。 见：[A2A vs ACP vs MCP Compared](https://codex.danielvaughan.com/2026/05/29/agent-to-agent-communication-protocols-a2a-vs-acp-vs-mcp-compared/){rel=""nofollow""}、[Agent Communication Protocol Architecture](https://agentcommunicationprotocol.dev/core-concepts/architecture){rel=""nofollow""} # A2UI #### A2UI 是什么？ Google 推出的声明式 UI 协议，让 AI Agent 能生成富交互界面。Agent 输出 JSON 描述界面结构，客户端用原生组件渲染，无需执行任意代码，兼顾安全性与原生体验。 见：[What is A2UI?](https://a2ui.org/introduction/what-is-a2ui/){rel=""nofollow""} #### 为什么需要 A2UI？ 纯文本交互效率低。比如订餐厅需要多轮问答，而 A2UI 让 Agent 直接生成表单（日期选择器、时间选择器、提交按钮），用户一步完成操作。 #### 核心技术原理？ - **声明式 JSON**：Agent 发送 `surfaceUpdate`、`dataModelUpdate` 等消息描述 UI - **客户端渲染**：用 Angular、Flutter、React 等原生框架渲染，继承应用样式 - **跨平台**：同一套 JSON 可在 Web、移动端、桌面端渲染 #### 与相关协议的关系？ - **A2A**：Agent 间通信协议（Agent to Agent），A2UI 可通过 A2A 通道传输 - **MCP**：连接 Agent 与外部工具/数据 - **AG-UI**：另一个 Agent UI 协议，与 A2UI 竞争 见：[A2A vs MCP vs AG-UI](https://dev.to/czmilo/a2a-vs-mcp-vs-ag-ui-1a03){rel=""nofollow""}、[Introducing A2UI](https://developers.googleblog.com/introducing-a2ui-an-open-project-for-agent-driven-interfaces/){rel=""nofollow""} #### 设计原则？ 1. **LLM 友好**：扁平组件列表，带 ID 引用，便于流式生成和纠错 2. **框架无关**：Agent 发送抽象组件树，客户端映射到原生控件 3. **关注点分离**：UI 结构、应用状态、渲染层分离，支持数据绑定 #### 核心概念？ - **Surface**：组件画布（对话框、侧边栏、主视图） - **Component**：UI 元素（按钮、文本框、卡片等） - **Data Model**：应用状态，组件绑定到它 - **Catalog**：可用的组件类型集合 - **Message**：JSON 对象（surfaceUpdate、dataModelUpdate、beginRendering 等） #### A2UI 不是什么？ - 不是框架（是协议） - 不是 HTML 的替代品（用于 Agent 生成 UI，而非静态站点） - 不是成熟的样式系统（客户端控制样式，服务端样式支持有限） - 不限于 Web（也支持移动端和桌面端） # Agent 算法迭代方法论 ## 先验后验的迭代闭环 #### Agent 开发做先验，Agent 算法追上限 Agent 开发与算法的分界：把一个 Agent 从零快速做到 60 分是开发， 从 80 分继续追高是算法。上线验证周期长、成本高，不可能每次迭代都等线上反馈， 所以完整的业务迭代方法论是「Benchmark → 策略 → 上线」闭环： 先用离线 Benchmark 尽可能对齐线上效果，用它快速指导先验策略迭代， 上线拿到真实后验后再反过来修正和补充先验。 评测侧沿四级链 scaling：Rubric（评分细则）把模糊的业务目标翻译成 非专家、LLM、程序都能稳定执行的评价标准；人工按 Rubric 标注一批样本看人人一致率， 一致率低说明标准本身不清而非标注员不行；LLM-as-a-Judge 用人标数据当 ground truth 调 Prompt 与采样超参，复现已稳定的人工判断；Reward Model（奖励模型） 再把已验证的评判蒸馏成低延迟、高吞吐的小模型，因为每次评测都调大模型时， 成本与时延随评测量线性增长，且很难靠压缩 Prompt 优化。 RM 只需在业务数据分布内强，可以用更小的基模训练。 「离线涨、线上没涨」的首要嫌疑是 Benchmark 未对齐业务， 要修的是样本、Rubric 与裁判而不是策略； Benchmark 因此不是一次性交付物，而是跟着业务持续迭代。 见：[从 Agent 开发到 Agent 算法，进阶指南](https://mp.weixin.qq.com/s/0YFG-J2ZWwRO4lTP7f1JDA){rel=""nofollow""} #### 策略升级路径：Prompt 燃尽再进 SFT，反馈信号是 RL 的命门 Agent 策略阶段的合理流程：纯 Prompt 跑通最小闭环，系统性分析 bad case， 再用 RAG、few-shot、CoT 等经典手法逼近上限，同步养 Benchmark。 判断 Prompt 层是否燃尽用梯度测试：在同一批样本上逐步增强 Prompt， 效果仍几乎不涨即到顶。SFT 阶段的准入原则是 「高频变化的信息留在 Context，长期稳定的行为才训进参数」： 实时库存、活动规则再重要也不进模型，输出格式、业务 SOP、工具调用范式才值得固化。 SFT 数据不是越多越好：同一场景下行为互相矛盾（一部分拒答一部分回答）时， 模型学到的不是灵活而是不确定性，清洗 SFT 数据本质是整理模型的行为分布； 未经 Benchmark 验证的 Prompt hack 直接扩数据训进去， 等于把没想明白的策略永久写进参数。 RL 阶段 Benchmark 从测试变成反馈，Rubric 定义什么叫好、Judge 判断好不好、 判断转成 Reward 决定优化方向，链上每级失真都会被训练放大， 所以离线 Reward 上涨不等于线上业务指标上涨。 见：[从 Agent 开发到 Agent 算法，进阶指南](https://mp.weixin.qq.com/s/0YFG-J2ZWwRO4lTP7f1JDA){rel=""nofollow""} ## 训练阶段的风险暗面 #### KL 惩罚挡不住奖励模型过优化 RLHF 常见的安全假设是给 Reward 加 KL 散度惩罚，策略就不会偏离真实目标太远。 Gao 等人 2022 年的实验给出量化反例：固定一个「金标准」奖励模型扮演人类， 用代理 RM 优化策略，金标准分数随优化量先升后降，与 Goodhart 定律一致； 加大 KL 惩罚系数并不改变这个交叉点的相对位置， 因为 RL 消耗 KL 预算的速度远快于 best-of-n 采样，按 KL 距离惩罚不改变相对排序。 后续研究进一步主张 KL 正则不足以缓解 reward misspecification。 工程含义：KL 系数不是安全阀，RM 上线后必须保留 held-out 真值评测 与定期人工或 LLM Judge 抽检，发现漂移即补充数据重训。 见：[Scaling Laws for Reward Model Overoptimization](https://arxiv.org/abs/2210.10760){rel=""nofollow""} #### 直接拿 LLM 裁判当 RL 奖励会被策略攻陷 RLAIF 用 LLM 裁判的打分直接充当 RL 奖励时， 2026 年研究给出首个系统证据：随训练推进，策略学会利用裁判的系统性错误， 裁判分数持续上涨而真实质量退化。缓解方案是辩论训练（debate）： 生成器与批评家对抗、由较弱的裁判裁决，相比单策略直接训 RL 的基线 显著减少 reward hacking，挽回了约 45% 的性能差距，且裁判在 RL 压力下保持判别力； 该方向首批证据 2026 年 8 月才出现，缓解路线未终审。 工程上，裁判分数做 reward 时应混入 held-out 人工锚点做漂移监控，不能裸跑。 见：[Debate Training Reduces Reward Hacking in RLAIF](https://arxiv.org/abs/2608.17776){rel=""nofollow""} #### SFT 的固化效果必须在分布外样本上验证 《SFT Memorizes, RL Generalizes》（Chu et al. 2025）比较两种后训练的泛化差异： 以结果为奖励的 RL 在文本规则变体与视觉变体上都泛化更好， SFT 倾向记忆训练数据、出分布即崩；但同一篇也确认 SFT 是 RL 的前置稳定器， 它固定输出格式，后续 RL 才能吃到性能收益。 该结论的测量方式存在争议（NeurIPS 有后续工作质疑 SFT 高分的误导性），未终审， 但无论哪边成立，防御动作一致：SFT 验证集必须包含训练分布外的样本变体， 只看同分布 Benchmark 会系统性高估固化效果。 见：[SFT Memorizes, RL Generalizes](https://arxiv.org/abs/2501.17161){rel=""nofollow""} # Agent 架构第一性原理 ## LLM 是神经符号主义的极佳实践？ 神经符号人工智能（Neuro-Symbolic AI）旨在融合神经网络的学习能力与符号 AI 的推理能力。这与认知科学的双过程理论高度契合：系统1（快速、直觉、无意识）对应神经网络，系统2（缓慢、深思熟虑、有意识）对应符号推理。 LLM 智能体通过 Chain-of-Thought 实现了这一融合——神经网络内核提供亚符号的模式识别（系统1），而生成的结构化推理文本又实现了符号主义的逻辑能力（系统2）。LLM 充当了符号空间与自然语言空间之间的桥梁， 使 AI 系统既能从海量数据中学习，又能进行严谨的符号推理。 三种神经符号融合范式： - **Symbolic→LLM**：符号方法生成推理数据，LLM 学习模仿（如 AlphaGeometry、LOGIPT） - **LLM→Symbolic**：LLM 将问题形式化后调用符号求解器（如 LogicLM、LLM+P、PAL） - **LLM+Symbolic**：端到端混合架构，符号与神经网络协同工作（如 DeepProbLog、可微分符号模块） 见：[神经符号人工智能：迈向提升大语言模型的推理能力](https://www.163.com/dy/article/KDRD9CE705567BBF.html){rel=""nofollow""}、[大型语言模型：符号推理的新趋势](https://zhuanlan.zhihu.com/p/678549814){rel=""nofollow""} ## PEAS 模型如何描述智能体任务环境？ PEAS 模型是人工智能领域用于精确描述智能体任务环境的经典框架，由四个维度构成： | 维度 | 含义 | 示例（智能旅行助手） | | --------------------- | ------------ | ---------------- | | **P**erformance（性能度量） | 评估智能体成功与否的标准 | 用户满意度、行程可行性、预算控制 | | **E**nvironment（环境） | 智能体运作的场景与条件 | 航班系统、酒店平台、天气服务 | | **A**ctuators（执行器） | 智能体影响环境的方式 | 搜索航班、预订酒店、生成行程 | | **S**ensors（传感器） | 智能体获取环境信息的渠道 | 用户输入、API 返回数据 | LLM 智能体面对的环境通常具备四个鲜明特点： - **部分可观察**（Partially Observable）：无法一次性获取全貌，需要记忆和探索 - **随机性**（Stochastic）：行动结果不确定，环境状态动态变化 - **多智能体**（Multi-agent）：环境中存在其他行动者（如其他用户、自动化脚本） - **序贯且动态**（Sequential & Dynamic）：当前动作影响未来，环境自身在变化 见：[智能体(Agent)核心技术解析：从PEAS模型到主流框架实战](https://zhuanlan.zhihu.com/p/1982412289576546663){rel=""nofollow""}、[一文搞懂大模型智能体工作原理](https://blog.csdn.net/Trb701012/article/details/156984467){rel=""nofollow""} #### 完整案例分析 [智能健身教练：PEAS 模型完整案例分析](https://lionad.art/maps/_ai/agents/peas-coach-example) ## 工作流与智能体的核心区别？ 决策权归属是区分二者的关键。 **工作流（Workflow）** 像流水线或菜谱，任务流程固定且预先设计好。LLM 被代码调用完成特定子任务（如总结文本、提取信息），决策权在代码而非模型。 **智能体（Agent）** 像侦探，你给它总目标，但没有固定剧本。它会根据情况动态决定下一步该做什么、使用哪个工具、任务是否完成，决策权在 LLM 而非代码。 #### 完整案例分析 [Workflow 与 Agent 对比：电商退款案例](https://lionad.art/maps/_ai/agents/workflow-vs-agent) —— 通过售后退款场景对比两种方案优劣及混合架构设计 ## 技术选型金字塔？ Anthropic 建议始终从最简单方案开始，只有当简单方案无法满足需求时才增加复杂性。 | 层级 | 方案 | 适用场景 | | ------ | ----------- | ----------------------------------- | | 底层（基础） | 优化单一 LLM 调用 | 简单任务，追求效率。通过 RAG、Few-shot 示例解决大部分问题 | | 中层（中级） | 工作流 | 流程固定、明确、可预测，对质量有高标准 | | 顶层（高级） | 智能体 | 开放式任务，无法预测步骤，需要模型大规模自主决策 | **示例**：翻译 / 本地化任务 - 读一封外文邮件/工单，快速了解大意即可 → 单一 LLM 调用 - 需要稳定产出与可追溯质量（术语一致、格式固定、必须复核），如用户手册/合规文档翻译 → 工作流（翻译 → 术语校验 → 审校/回译） - 目标是"把内容做成一条可发布的多语言产线"，涉及选题、改写、本地化用词、生成标题与摘要、更新站点/提交 PR 等多步决策与多工具协作 → 智能体 见：[Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents){rel=""nofollow""}（Anthropic 官方指南） ## 五种工作流模式？ Anthropic 从生产实践中总结出五种可组合的工作流模式，按复杂度递增： **Prompt Chaining（提示链）** 任务分解为顺序步骤，每步 LLM 处理上一步输出。可添加程序检查（gate）确保过程正确。 - 适用：可清晰分解为固定子任务，用延迟换准确性 - 示例：生成营销文案 → 翻译成其他语言；写大纲 → 检查 → 写文档 **Routing（路由）** 输入分类后路由到专门下游任务，分离关注点，构建更专业的提示。 - 适用：复杂任务有明确类别，分类可由 LLM 或传统模型处理 - 示例：客服查询按类型（一般问题/退款/技术支持）路由到不同流程 **Parallelization（并行化）** - **Sectioning（分段）**：任务拆分为独立子任务并行处理 - **Voting（投票）**：同一任务多次运行，聚合多样输出 - 适用：可并行提速，或需多视角/多次尝试提高置信度 - 示例：代码漏洞审查（多提示并行审查）、内容安全评估 **Orchestrator-workers（编排器-工作者）** 中心 LLM 动态分解任务，委派给工作 LLM，再综合结果。与并行的关键区别：子任务不是预定义的，而是由编排器根据输入动态决定。 - 适用：复杂任务无法预测子任务（如编码需修改的文件数量和性质取决于任务） - 示例：多文件复杂代码修改、多源信息搜集分析 **Evaluator-optimizer（评估-优化）** 一个 LLM 生成响应，另一个提供评估反馈，循环迭代。 - 适用：你能清楚定义"好/坏"的标准，而且多改几轮确实会变更好。通常有两个信号：人工点评能明显改善结果；模型也能按同一套标准给出可用的点评 - 示例：文学翻译（捕捉细微差别）、复杂搜索任务（多轮搜索分析） ## Agent 设计三原则？ 1. **简洁性** —— 保持设计简单 2. **透明性** —— 显式展示规划步骤 3. **ACI（Agent-Computer Interface）** —— 精心设计的工具文档和测试 #### Agent 是章鱼：不要过度约束 「Agent 是一只章鱼——能蜿蜒、能挤进窄缝、能绕开问题。除了 shenanigan（恶作剧/越权）需要约束之外，**不要过度约束 Agent 解决问题的能力。**」——Danilo Campos（PostHog Wizard） 由此带来思维转变： - ❌ 旧式：「我怎么 scaffold Agent 的每一步行为？」 - ✅ 新式：**「我怎么后退一步、给足信息、把信息排好顺序，让它做对事并让用户开心？」** 这与「简洁性」原则互为表里——给信息和顺序，不给步骤。约束应作用于工具粒度（信任边界）与披露顺序（Breadcrumb），而非每一步动作的脚手架。 见：[The PostHog Wizard: Lessons in AI onboarding](https://www.youtube.com/watch?v=juoNbJiZUi0){rel=""nofollow""} #### Plan-and-Solve 的规划幻觉比 ReAct 更难察觉 Plan-and-Solve 通过将规划与执行解耦来规避 ReAct 的规划-执行耦合问题，但解耦后引入了一种更隐蔽的风险：规划阶段的错误在执行前难以暴露。ReAct 的错误在每一步都有 Observation 反馈，如果检索结果跑偏了， 下一步 Thought 有机会修正；但 Plan-and-Solve 的完整规划在执行前缺乏真实数据校验，validate\_plan 通常只能做语法和逻辑层面的检查——它无法验证外部 API 是否在线、某个字段在该环境下是否实际必填、 或者用户的模糊表述在真实上下文中是否有另一种解读。 更隐蔽的是，validate\_plan 本身往往也是 LLM 判断，它会对「看起来合理的规划」放行，直到执行阶段才暴露不可行性，此时回滚成本远高于 ReAct 的步级回滚。生产环境的折中方案不是完全切换到纯规划-执行分离架构， 而是保留 ReAct 的步级反馈机制，但在每步执行前加入轻量级预验证（如检查 API schema 是否匹配），让错误在更早的阶段以更低的成本暴露。 #### System Prompt 里的错误处理是纸面合规 System Prompt 中写入的"工具调用超时重试 1 次""连续 3 次错误触发告警"等规则，模型无法实际执行。L1 层面，LLM 没有内置的超时感知能力，它不知道一个 API 调用花了 3 秒还是 30 秒； 它也没有跨轮次的状态记忆，无法在"连续 3 次错误"时主动触发告警。L2 层面，这些指令本质上是给人类看的文档，不是模型能执行的代码——遇到异常时，模型最可能生成一段"抱歉出错了"的文本，然后继续基于错误的假设瞎猜， 它无法区分"API 返回 500"和"API 正常返回空数据"。L3 层面的工程正确做法是，真正有效的错误处理必须在编排层通过 try-catch、超时装饰器、状态计数器实现。 System Prompt 中的错误处理描述只能作为输出风格引导（让模型在出错时输出统一的错误格式），不能替代工程层面的容错机制。 ## 工具设计的最佳实践？ 设计工具时，投入与 HCI（人机界面）相当的努力到 ACI（Agent-Computer Interface）： **格式选择原则** - 给模型足够 token 在"陷入困境"前思考 - 格式贴近模型在互联网上自然见过的形式 - 避免格式开销（如 diff 需计算行数、JSON 需转义引号） **设计检查清单** - 站在模型角度：工具描述和参数是否一目了然？好的工具定义包含示例用法、边界情况、输入格式要求 - 优化参数命名和描述：像为团队初级开发者写优秀 docstring - 测试迭代：在 workbench 中运行大量示例输入，观察模型错误并迭代 - Poka-yoke（防错）：调整参数使错误更难发生 **Anthropic 实战经验** 在构建 SWE-bench Agent 时，优化工具的时间超过优化提示。例如：发现模型在使用相对路径的工具上出错（Agent 已移出根目录后），改为要求绝对路径后，模型 flawlessly 使用该方法。 #### 信任边界窄化：用窄工具替代盲读 PostHog Wizard 早期版本会直接读取用户 `.env` 文件来执行写入——结果是用户敏感信息被发送到 cloud 推理日志。修复方式不是再加访问控制，而是**把工具拆细**： | 旧设计（出问题） | 新设计（信任边界窄化） | | ----------------------- | --------------------------------------------- | | 盲读整个 `.env`，把全部内容上传 LLM | 工具 1：`check_key(name)` → 仅返回 boolean，不读 value | | | 工具 2：`write_key(name, value)` → 只写指定键，不读取整个文件 | 「在别人电脑上跑 Agent 需要巨大的信任。**即使你解决了承诺的问题，过程中可能让你看起来像个混蛋**。」（Danilo Campos） 设计原则：**信任降级到工具粒度**，而非交给 Agent 自我克制。这是 Poka-yoke（防错）思想在权限边界上的应用——让「读敏感数据」在物理上不可能发生，而非靠提示词约束。 见：[The PostHog Wizard: Lessons in AI onboarding](https://www.youtube.com/watch?v=juoNbJiZUi0){rel=""nofollow""} ## 长时运行 Agent 的 Harness 设计？ 当 Agent 需要跨多个上下文窗口工作（数小时甚至数天）时，核心挑战是**每个新会话都从零开始**，对之前工作一无所知。 Anthropic 采用 **Initializer Agent + Coding Agent** 的双代理架构解决此问题。 **Initializer Agent（初始化代理）** 首次会话运行，负责搭建基础环境： - `feature_list.json`：详细功能清单（如 claude.ai 克隆项目超过 200 个功能），全部初始标记为 `failing` - `claude-progress.txt`：进度日志，记录每个会话完成的工作 - `init.sh`：启动脚本，一键运行开发服务器 - 初始 git commit，建立版本基线 **Coding Agent（编码代理）** 后续所有会话运行，遵循增量开发原则： - 会话开始时：读取进度文件和 git log → 运行 `init.sh` 启动服务 → 端到端测试验证基础功能 - 每次只处理**一个功能**，避免"一次性做完"的冲动 - 会话结束时：提交 git commit（描述性消息）→ 更新进度文件 → 保持环境在"可合并状态" **功能清单的设计要点** 使用 JSON 而非 Markdown，因为模型更不容易误改 JSON 结构。每个功能包含 `category`、`description`、`steps`、`passes` 字段。 Coding Agent 只能修改 `passes` 字段，强烈措辞约束："删除或编辑测试是不可接受的，这会导致功能缺失或 bug"。 **端到端测试的必要性** Agent 容易"未经充分测试就标记功能完成"。显式提示使用浏览器自动化工具（如 Puppeteer MCP），像人类用户一样测试。这能发现仅从代码看不出的 bug，但注意 Claude 无法看到浏览器原生 alert 弹窗。 | 常见失败模式 | Initializer 解决方案 | Coding Agent 解决方案 | | -------------- | ---------------- | ------------------------ | | 过早宣布整个项目完成 | 设置详细功能清单 | 每次只选一个功能开发 | | 留下 bug 或未记录的进度 | 初始化 git 和进度文件 | 开始读进度/git log，结束写 commit | | 过早标记功能完成 | 设置功能清单文件 | 自验证所有功能，仔细测试后才标记 passing | | 花时间摸索如何运行应用 | 编写 `init.sh` 脚本 | 会话开始就读 `init.sh` | 见：[Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents){rel=""nofollow""}（Anthropic Engineering） #### 意图先行提交：把 Agent 执行做成数据库事务 Agent 连续运行数小时，进程可能在任意一步崩溃，而外部效果（写文件、调 API、计费）已经真实发生。重启后要精确回答 "哪些做了、哪些没做"，唯一可靠的方式是把执行过程做成数据库事务。 骨架有三件。其一是原子提交：唯一写原语是把一组写入 all-or-none 地提交，事务内部不存在崩溃中间态。其二是意图先行： 每次外部效果前先提交一条"我即将做 X，产出将使用 id R 和 U"，执行效果，再提交结果与下一状态——意图永远先于效果落盘。 其三是持久程序计数器：每步把当前操作的全量状态整体覆写进一个寄存器，恢复就是读这一个寄存器并按其分派， 不需要回放日志，也不需要从缺失中推断位置。操作结束时，终端事务删掉该操作的全部状态寄存器， 会话里只剩对话、账单与少量游标寄存器——没有死状态需要回收。 见：[Pi AgentHarness implementation specification](https://github.com/earendil-works/pi/blob/main/packages/agent/docs/harness.md){rel=""nofollow""} #### 工具声明可重放性，崩溃恢复按声明处置 进程恰好死在工具执行到一半，是长时 Agent 唯一真正的不确定窗口：效果可能已部分发生，盲目重跑会重复副作用， 直接丢弃又让对话缺失结果。可靠做法是把处置策略从恢复逻辑里拿出来，改由工具自己声明： 有副作用、不可重跑的工具声明 never，只读、可重跑的工具声明 safe。 崩溃重启后，声明 never 的调用绝不重跑——系统在效果开始前预留的结果 id 下补一条合成的 "interrupted" 错误结果， 对话保持连贯且没有任何效果被执行两次；声明 safe 的调用则用已持久化的参数重新执行。 幂等性由此变成工具声明的一部分，运行时明确放弃外部效果的 exactly-once，但换来"每个调用必有结果"的不变量。 见：[Pi AgentHarness implementation specification](https://github.com/earendil-works/pi/blob/main/packages/agent/docs/harness.md){rel=""nofollow""} ## Claude Agent SDK 的核心设计原则？ Claude Agent SDK（原 Claude Code SDK）的设计哲学是**给 Claude 一台计算机**——让它能够使用程序员日常使用的工具（终端、文件系统、代码执行），从而像人类一样工作。 这不仅让 Claude 擅长编码，还能处理各种非编码任务：读取 CSV、搜索网页、构建可视化、解释指标等。核心反馈循环是：**收集上下文 → 采取行动 → 验证工作 → 重复**。 > Over the past several months, Claude Code has become far more than a coding tool. At Anthropic, we' > ve been using it for deep research, video creation, and note-taking, among countless other non-coding applications. > In fact, it has begun to power almost all of our major agent loops. > —— Anthropic ## Agent 如何有效收集上下文？ **Agentic Search（代理式搜索）** 文件系统代表"可能被拉入上下文"的信息。Agent 使用 `grep`、`tail` 等 bash 脚本自主决定如何加载大文件（如日志）。文件夹结构本身成为一种上下文工程。 **Semantic Search（语义搜索）** 通常比代理式搜索更快，但准确性较低、维护更困难、透明度更低。建议先使用代理式搜索，仅在需要更快结果或更多变体时添加语义搜索。 **Subagents（子代理）** SDK 默认支持子代理，有两个主要用途： - **并行化**：同时启动多个子代理处理不同任务 - **上下文管理**：子代理使用独立的上下文窗口，只返回相关信息给编排器 **Compaction（上下文压缩）** 当 Agent 长时间运行时，自动总结之前的消息以避免上下文耗尽。这是 Claude Code `/compact` 命令的底层能力。 #### Breadcrumb 任务披露：限制 Agent 即兴发挥 直接告诉 Agent「实施 PostHog 集成」会得到 15,000 种不同的实施方式——「**Sorcerer's Apprentice 困境**」（巫师学徒，魔法失控的传说），最终演变为支持地狱。 PostHog Wizard 的解法是**面包屑式渐进披露**，每步只暴露眼前任务，不告诉 Agent 全局目标： 1. **不告诉**Agent 它在做 PostHog 集成 2. 「项目里哪些文件有商业价值？登录、支付、流失风险？」（**business stuff casts a huge shadow in code**——业务逻辑在代码中投下巨大阴影） 3. 「列一下这些文件中可能的事件名（不要写代码）」 4. 「现在加载文档并实施」（按框架/语言定向加载，配合 Fresh Markdown 注入） **核心机制**：Agent 看不到全局，就不会在第 5 步开始「rock polishy」（过度抛光，类似 Claude Code 在最后一个任务上花过多时间）。 约束不是为了禁锢，是为了一致性——这与「子 Agent 上下文管理」遥相呼应，同样是用上下文边界换可控性。 见：[The PostHog Wizard: Lessons in AI onboarding](https://www.youtube.com/watch?v=juoNbJiZUi0){rel=""nofollow""} ## Agent 采取行动的关键方式？ **Tools（工具）** 工具是 Agent 执行的主要构建块，在 Claude 的上下文窗口中非常突出。设计工具时要考虑上下文效率，将最频繁的操作定义为工具。 **Bash & Scripts** Bash 作为通用工具，让 Agent 能够灵活地使用计算机完成各种任务。例如：下载 PDF、转换为文本、搜索内容。 **Code Generation（代码生成）** 代码精确、可组合、无限复用，是 Agent 执行复杂操作的理想输出。Claude.AI 的文件创建功能完全依赖代码生成——用 Python 脚本创建 Excel、PPT、Word 文档。 **MCPs（Model Context Protocol）** 提供与外部服务的标准化集成，自动处理认证和 API 调用。可快速连接 Slack、GitHub、Google Drive、Asana 等，无需编写自定义集成代码。 #### 并行 Action 的竞态条件陷阱 把 vLLM 投机采样的思路借用到并行 Action 上时，一个关键前提常被忽略：token 生成的并行是纯粹的无状态数学运算，而工具调用的并行涉及外部系统状态。如果你一次性生成多个候选 Action 并同时执行，而 Action A 是「 扣减库存」、Action B 是「查询库存余额」，并行执行下 B 读到的可能是 A 扣减前的旧值——这种竞态条件在 ReAct 的串行执行中天然不存在，但并行优化把它引入了。 工程上的可行方案是构建工具依赖图，对无状态依赖的读操作并行、写操作和依赖该状态的读操作串行，而不是盲目并行所有 Action。 ## Agent 如何验证工作质量？ **Defining Rules（定义规则）** 最佳反馈形式是提供清晰的输出规则，然后解释哪些规则失败及原因。代码 linting 是优秀的规则反馈——生成 TypeScript 比纯 JavaScript 更好，因为提供了额外的反馈层。 **Visual Feedback（视觉反馈）** 对于 UI 生成或测试等视觉任务，截图或渲染可以提供有价值的验证。检查布局、样式、内容层次、响应式表现等。使用 Playwright MCP 可以自动化此反馈循环。 **LLM as a Judge** 让另一个语言模型基于模糊规则评判输出。这不是非常稳健的方法，且有较高的延迟代价，但在追求性能提升的应用中可能有帮助。 ## 测试和改进 Agent 的关键问题？ - 如果 Agent 误解任务，是否缺少关键信息？能否调整搜索 API 结构？ - 如果 Agent 反复失败，能否在工具调用中添加正式规则来识别和修复？ - 如果 Agent 无法修复错误，能否提供更有用或更有创意的工具？ - 如果性能随功能增加而变化，能否基于客户使用构建代表性的测试集进行程序化评估？ 见：[Building agents with the Claude Agent SDK](https://claude.com/blog/building-agents-with-the-claude-agent-sdk){rel=""nofollow""}（Claude 官方博客） #### 上下文重置优于上下文压缩 长时运行 Agent 面临"上下文焦虑"——模型在感知到上下文窗口将满时会提前草率收尾。上下文重置（Context Reset）通过完全清空上下文并结构化交接状态，比原地压缩更能缓解这一问题。 与 Compaction 的区别在于：压缩保留连续性但无法提供干净 slate，而重置让新会话从零开始却携带完整状态继承。Claude Sonnet 4.5 的实验表明，仅靠压缩不足以支撑强长时任务表现， 重置成为 Harness 设计的关键机制。 见：[Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps){rel=""nofollow""}：Anthropic Labs 团队关于长时应用开发的 Harness 设计实践 #### ReAct 摘要回写的二次信息损失 摘要回写（Summary Write-back）是缓解 ReAct 多轮推理上下文漂移的常用手段，但常被忽略的是：摘要本身是一次不可逆的有损压缩，而「压缩什么、保留什么」这个决策是模型替你做的。一个典型场景是，原始上下文中的「 用户对青霉素过敏」在多轮摘要后逐渐退化为「用户有药物过敏史」——这个表述在语法上完全正确，但后续推理轮次中模型可能据此推荐头孢类药物，而原始信息明确排除了整个青霉素类。 更棘手的是，这种信息损失不会在日志中暴露为明显错误。每一轮的摘要都独立地「合理」，但关键约束在逐轮传递中被系统性地稀释。工程上的可靠做法不是简单做摘要，而是对安全约束、用户明确否定等关键信息做结构化标记，在回写时强制保留原句而非摘要形式—— 或者直接用上下文重置替代渐进式压缩。 #### 超大工具输出应落盘溢写做无损裁剪 对超大工具输出做头尾裁剪是不可逆损失：测试日志被掐头去尾后，埋在中段的关键报错永久丢失，后续推理无法从空气里读回。 无损做法是 prune + spill：裁剪时把完整输出写入磁盘缓存目录，上下文只留摘要与文件定位符，定位符携带精确的省略区间偏移， 模型可以用 slice、grep、sed 确定性恢复原文。 两个工程细节决定成败。定位标记必须放在结果开头且足够短——压缩流程通常把工具结果截断到 2000 字符量级， 标记放在中段会在压缩后连同恢复路径一起静默消失。其次要防恢复死循环：模型读溢写文件取回内容时，这次读取的结果不能再经过裁剪器。 19 个真实会话（GLM-5.3 与 DeepSeek V4 Flash）的实测中，该模式把上下文占用降低 26%\~35%、未缓存 prefill 降低 72%\~88%，且信息完全可恢复。 见：[example: tool-result pruner + spill extension](https://github.com/earendil-works/pi/pull/8172){rel=""nofollow""} #### 推理时质询：把 Agent 当用户研究 PostHog Wizard 在 Stop Hook 注册了一个简单问题：**「这次运行你需要什么才能更成功？」**——把 Agent 当作用户来做研究。这种轻量级 interrogation 在生产中暴露了大量人类自身的疏漏： - 两个 MCP 工具的指令互相矛盾（「让我陷入不可能境地」） - 教 Agent 用一个不存在的工具（hundreds of runs 都因此失败） - 把 JavaScript 风格的指令塞给 Python 项目 「人的 context 也是有限且碎片化的——上周的实现细节这周就忘了。」（Danilo Campos）**不问就不会知道**——代价低、信息密度高，是 Agentic Engineering 中最经济的反馈机制之一，也是「 测试和改进 Agent」清单中应当默认开启的一项。 见：[The PostHog Wizard: Lessons in AI onboarding](https://www.youtube.com/watch?v=juoNbJiZUi0){rel=""nofollow""} ## 参考 - [Building effective agents @Anthropic](https://www.anthropic.com/engineering/building-effective-agents){rel=""nofollow""} - [How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system){rel=""nofollow""} - [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents){rel=""nofollow""} - [Building agents with the Claude Agent SDK](https://claude.com/blog/building-agents-with-the-claude-agent-sdk){rel=""nofollow""} ## AI Agent 三层问题堆栈 大多数工程精力集中在第一层（能力层），但真实组织中系统常在第二层（采用层）或第三层（涌现层）失败。 | 层级 | 问题 | 注意力成本 | | ------ | ------------------ | ------------- | | 3. 涌现层 | 能否持续可用？能否在真实使用中存活？ | 监控、信任校准、修正 | | 2. 采用层 | 用户会尝试吗？恐惧、回避、习惯阻力 | 说服、习惯改变、工作流调整 | | 1. 能力层 | 能用吗？正确性、实用性 | 工程投入 | 即使技术上能工作的系统，如果用户回避它，或真实使用模式逐渐侵蚀信任和实用性，系统仍会失败。第二层和第三层常被忽视，因为它们不是纯粹的技术问题——64% 的人报告对 AI 有恐惧或担忧，而恐惧无法通过更好的产品设计解决，当技术挑战人们的身份、 专业能力或工作安全感时。 见：[The Attention Debt of AI Tooling](https://www.wespiser.com/posts/2026-03-15-Attention-Debt-Of-AI-Tooling.html){rel=""nofollow""}：AI 工具的认知成本分析 ## RACI 框架：从 Consulted 到 Responsible 用 RACI 框架审视 AI 系统的角色分配： | 模式 | 人类角色 | AI 角色 | 注意力成本 | | -------- | ------------------------- | --------------- | ----- | | HITL（现状） | Responsible + Accountable | Consulted | 最大化 | | HOTL（目标） | Accountable + Informed | **Responsible** | 最小化 | 许多 AI 工具今天占据 Consulted 角色——人类仍负责和问责，AI 只提供建议。这正是注意力成本最大化的配置。 真正的机会是将 AI 向左移动：让 AI Agent 承担 Responsible 角色（执行主要工作），人类保持 Accountable 和 Informed，仅在必要时被咨询。 不要向 AI 征求建议，要求它完成工作。然后仅在需要做出昂贵或不可逆决策时通知人类。 见：[The Attention Debt of AI Tooling](https://www.wespiser.com/posts/2026-03-15-Attention-Debt-Of-AI-Tooling.html){rel=""nofollow""}：AI 工具的认知成本分析 #### 有状态压缩与子 Agent：长周期工作流的上下文架构 长周期 Agentic 工作流（跨越数小时至数周）面临根本性挑战：被动截断对话历史会丢失关键状态。CaveAgent 以“LLM-as-Runtime-Operator”范式开创了双流架构：轻量级语义流用于 LLM 推理， 持久化运行时流用于状态管理和代码执行。复杂数据结构（如 DataFrames）作为原生 Python 变量注入持久运行时，Agent 通过简洁变量引用操作高保真数据，将存储与有限的上下文窗口解耦。 监督者 Agent 可以编程方式将变量注入子 Agent 运行时，多个 Agent 可在统一共享运行时上操作，实现隐式同步和无损状态流。 主动上下文压缩是另一项新兴技术：在每 10–15 次工具调用后，Agent 使用 `start_focus` 和 `complete_focus` 指令自主压缩上下文。在上下文密集的 SWE-bench Lite 任务中， 这实现了 22.7% 的 token 节省而不牺牲准确性，相比之下被动压缩仅节省 6%。企业级分层记忆架构正在兴起，包含六个层次：事件日志（仅追加真相来源）、状态存储（检查点与幂等键）、知识存储（语义记忆）、检索层（混合搜索与租户隔离）、 上下文构建器（token 预算内组装 Prompt）、可观测性层（审计与溯源）。 见：[arXiv:2601.01569](https://arxiv.org/abs/2601.01569){rel=""nofollow""}、[arXiv:2601.07190](https://arxiv.org/abs/2601.07190){rel=""nofollow""}、[StackAI](https://www.stack-ai.com/insights/ai-agent-memory-and-context-management-best-practices-and-patterns-for-long-running-enterprise-workflows){rel=""nofollow""}、[Leanware](https://www.leanware.co/insights/langgraph-agents){rel=""nofollow""} #### 企业级幻觉防控：上下文管道与多 Agent 审查架构 企业级 AI Agent 的幻觉问题越来越通过多层次的上下文管道解决，而非仅靠提示工程。主导架构转变是从单 Agent 推理转向编排管道，结合 RAG、知识图、神经符号验证和多 Agent 审查层。“上下文层” 方法将管道视为原始企业数据与 Agent 之间的中介：通过 MCP 等协议将上下文暴露为可查询工具，使用共享业务词汇表和本体论解析模糊术语，通过列级血缘告知数据来源，并将治理规则编码为可查询节点。 研究表明，渐进式多 Agent 精炼架构可显著降低幻觉得分：四级管道（前端 Agent → 二级审查员 → 三级审查员 → 评估 Agent）使用结构化 JSON 的 Agent 间通信，传递“耳语上下文（Whisper Context）” 元数据，在 310 个对抗性 Prompt 实验中将总幻觉得分（THS）降低了近 2,800%。相比标准向量相似性 RAG，Graph-RAG 同时遍历结构化知识图和文本检索，提供可解释的推理路径。神经符号护栏使用框架级钩子拦截工具调用， 防止 LLM 可能幻觉出的参数错误和工具绕过行为。企业安全框架通常解决四类风险：幻觉（输出验证器 + Graph-RAG）、失控行为（沙盒 + 熔断器）、数据泄露（PII 检测管道，约 96% F1）、过度自主（人机回环升级）。 见：[arXiv:2501.13946](https://arxiv.org/abs/2501.13946){rel=""nofollow""}、[AWS/Strands Agents](https://dev.to/aws/stop-ai-agent-hallucinations-4-essential-techniques-2i94){rel=""nofollow""}、[IJLRP](https://www.ijlrp.com/papers/2026/3/2015.pdf){rel=""nofollow""} #### Agent-first 基础设施：以 Agent 为一等公民重写工具链 Karpathy 注意到今天大多数文档、API、权限模型、设置流程仍然为人设计：去某个 URL、点某个菜单、复制某个 key、配置某个 DNS。在 Agentic 范式下，他的反应是“为什么还在告诉我该怎么做？我什么都不想做。 给我能复制粘贴给 Agent 的东西是什么？” Agent-first infrastructure 的目标是把世界拆成 Agent 能读懂的输入与可安全调用的动作接口。文档、API、权限、日志、部署、配置、账单、回滚都要变得更适合 Agent 使用—— 不是让 Agent 模拟人去点网页，而是让 Agent 直接理解状态、调用动作、收到反馈。Karpathy 的具体测试标准是：未来给 LLM 一句 `Build MenuGen`，它不仅写代码，还能完成部署、上线、配置依赖服务， 整个过程不需要人去一个个菜单里操作。 更远一步，他设想每个人和组织都可能有自己的 Agent representation——安排会议、协调事项变成“我的 Agent 和你的 Agent 去谈”。 见：[Karpathy 最新访谈：Vibe Coding 只是开始，真正重要的是 Agentic Engineering](https://baoyu.io/blog/andrej-karpathy-from-vibe-coding-to-agentic-engineering){rel=""nofollow""} #### 否定指令比正面指令弱 很多工程师习惯用"不能透露竞品价格""不能承诺配送时间"来画边界，但执行效果通常不如把边界重新表述为正面流程。LLM 的概率预测机制偏向正向模式匹配，训练数据里肯定指令也占主导，导致"不要做 X"更容易被忽略或只在表面被满足。 工程上更可靠的做法是：把禁止事项转化为"遇到该情况时必须执行的检查步骤"，例如"如果用户询问竞品，先调用 `product_compare_refusal` 工具并返回固定话术"。单纯罗列禁止项， 模型在压力场景下会倾向于满足用户请求而不是遵守否定约束。 #### 置信度阈值需要校准 在 Prompt 里写"置信度 >90% 直接回复，<60% 转人工"看起来很工程化，但模型 verbalized confidence 的校准极差，会随温度、领域、上下文长度漂移。这个阈值是未被观测的隐变量，不是可配置参数； 没有 held-out eval 或独立 verifier 做回测校准，它会在某些场景下过度自信，另一些场景下又过度保守。更稳的做法是把阈值当作初始 guess，配套一个持续收集 bad case 并调整阈值的反馈环， 而不是写死在一个字符串里。 #### 上下文截断要写在代码里 很多工程师会把"只保留最近 3 轮对话"写进 System Prompt，期待模型自己学会摘要和丢弃。但 LLM 没有对自己已消费 token 的自我感知，它看到的历史就是已经塞进窗口的全部内容； 提示词里的"管理规则"本质上只是在告诉模型"如果遇到历史，请优先关注近期"，并不能真正防止窗口溢出。真正决定哪些信息进入上下文的，是代码层的 compaction、摘要器、路由器和截断策略。 把上下文管理当成 prompt 工程而不是系统工程，长会话后期会 silently 丢失关键 earlier context，表现为"模型突然忘记用户说过什么"。 # Agent 生态系统全景 ## 多智能体框架对比 | 框架 | GitHub | Stars | 语言 | Tool | MCP | Skill | Memory | Hook | 特点 | | --------------------- | --------------------------- | ------ | ----------------- | ---- | --- | ----- | ------ | ---- | --------------- | | **LangGraph** | langchain-ai/langgraph | 10K+ | Python/TS | ✅ | ✅ | ✅ | ✅ | ✅ | 图状态机编排，生产级首选 | | **AutoGen** | microsoft/autogen | 40K+ | Python/.NET | ✅ | ✅ | ✅ | ✅ | ✅ | 微软生态，对话式协作 | | **CrewAI** | crewAIInc/crewAI | 38K+ | Python | ✅ | ✅ | ✅ | ✅ | ✅ | 角色化团队，易用性高 | | **AgentScope** | agentscope-ai/agentscope | 16.5K+ | Python | ✅ | ✅ | ✅ | ✅ | ✅ | 阿里开源，强化学习集成 | | **Google ADK** | google/adk-python | 新 | Python/Java/Go/TS | ✅ | ✅ | ✅ | ✅ | ✅ | 多语言支持，MCP/A2A原生 | | **OpenAI Agents SDK** | openai/openai-agents-python | 8K+ | Python | ✅ | ✅ | ✅ | ✅ | ✅ | 极简设计，快速上手 | | **Agno** (原Phi) | agno-agi/agno | 10K+ | Python | ✅ | ✅ | ✅ | ✅ | ✅ | 全栈平台，AgentOS运行时 | | **Pydantic AI** | pydantic/pydantic-ai | 新 | Python | ✅ | ✅ | ❌ | ❌ | ❌ | 强类型验证，金融级安全 | #### Hermes Agent 与 OpenClaw：自进化智能体的两种范式 Nous Research 于 2026 年 2 月发布 Hermes Agent（最新 v0.10.0，2026.4.16），定位为"能自我进化的开源自托管个人智能体"。同期 OpenClaw 活跃迭代（ 2026.3.7 引入可插拔 ContextEngine），两者代表自托管智能体赛道的两种竞争性架构哲学。 **核心架构差异**：Hermes 以"Agent 执行循环"为同步编排引擎，围绕其集成网关、定时调度器、工具运行时和 ACP，形成"执行—学习—改进"的自我进化闭环；OpenClaw 以"网关"为中枢控制器，统一协调会话、路由、 工具调用和状态维护，强调人类可控和显式配置。 **记忆设计差异**：Hermes 采用四层分层结构——核心持久记忆（\~1.3k tokens，每次会话加载）+ SQLite 可搜索历史（FTS5 全文索引，按需检索）+ Honcho 长期用户画像 + 技能层（程序性记忆， 存储"学会做什么"）；OpenClaw 采用 Markdown 文件化记忆，是"事实的权威来源"。 **安全与配置哲学**：Hermes 采用五层纵深防御（用户授权、危险命令审批、容器隔离、MCP 凭证过滤、上下文文件扫描），定位为"默认安全、生产就绪"；OpenClaw 强调操控性和可审查性，安全加固依赖用户自身运维， 定位为"强大但需手动配置"。 两者并非互斥——有分析认为可以并行运行、输出复用甚至互联，下一代产品可能兼具"用户直接掌控"和"能力复利"。 ![Hermes Agent vs OpenClaw 对比表](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260423195833082.png) 见：[Hermes Agent：挑战 OpenClaw 的新势力](https://blog.csdn.net/turingbooks/article/details/159999664){rel=""nofollow""} ## 低代码/无代码平台 | 平台 | 定位 | 核心特性 | 开源/商业 | | ------------- | --------------- | ----------------------- | ------- | | **Dify.AI** | LLM 应用开发平台 | 可视化编排、RAG、Agent、工作流 | 开源 + 商业 | | **扣子 (Coze)** | 字节跳动 Agent 平台 | 插件生态、知识库、工作流、发布到豆包/飞书 | 商业 | | **腾讯元器** | 腾讯 Agent 平台 | 微信生态集成、知识引擎、工具链 | 商业 | | **Langflow** | LangChain 可视化工具 | 拖放式工作流、与 LangChain 生态集成 | 开源 | | **Flowise** | 开源 LLM 编排工具 | 类似 Langflow、支持多种模型 | 开源 | ## 企业级平台 | 平台 | 厂商 | 核心能力 | | --------------------------- | --------- | -------------------------------- | | **AWS Bedrock Agents** | Amazon | 统一模型接入、Policy 安全边界、AgentCore 运行时 | | **Azure AI Agent Service** | Microsoft | 与 Microsoft 365 深度集成、可视化工作流设计器 | | **Vertex AI Agent Builder** | Google | Model Garden、RAG 引擎、多模态能力 | | **阿里云百炼** | 阿里巴巴 | 200+ 模型支持、V-RAG 开源、MCP 全生命周期服务 | | **IBM watsonx Orchestrate** | IBM | 1000+ 预构建集成、AgentOps 全生命周期管理 | ## 垂直领域 Agent ### 编程/代码生成 - [Continue.dev](https://continue.dev/){rel=""nofollow""}：开源 AI 代码助手，支持任何 LLM - [Supermaven](https://supermaven.com/){rel=""nofollow""}：20万 token 上下文代码补全 - [Codeium](https://codeium.com/){rel=""nofollow""}：完全免费的代码助手，支持 70+ IDE ### 数据分析 - [Julius AI](https://julius.ai/){rel=""nofollow""}：对话式数据分析 - [ChatCSV](https://www.chatcsv.co/){rel=""nofollow""}：CSV 数据对话分析 ### 科研/学术 - [Elicit](https://elicit.com/){rel=""nofollow""}：AI 研究助手 - [Consensus](https://consensus.app/){rel=""nofollow""}：科学文献搜索引擎 ### 法律 - [Harvey](https://www.harvey.ai/){rel=""nofollow""}：法律 AI 平台（ARR 7500万美元） - [CoCounsel](https://www.cocounsel.com/){rel=""nofollow""}：法律研究助手 ## Agent 基础设施 ### 监控与可观测性 - [Langfuse](https://langfuse.com/){rel=""nofollow""}：开源 LLM 可观测性 - [LangSmith](https://smith.langchain.com/){rel=""nofollow""}：LangChain 官方平台 - [AgentOps](https://www.agentops.ai/){rel=""nofollow""}：Agent 运维平台 ### 记忆/存储 - [Mem0](https://github.com/mem0ai/mem0){rel=""nofollow""}：开源 Agent 记忆层 - [Zep](https://www.getzep.com/){rel=""nofollow""}：长期记忆服务 - [Chroma](https://www.trychroma.com/){rel=""nofollow""}：向量数据库 ### 安全与治理 - [Glaider](https://glaider.com/){rel=""nofollow""}：Agent 安全护栏 - [MI9 框架](https://github.com/barclays/mi9){rel=""nofollow""}：巴克莱开源运行时治理框架 ## 协议与标准 ### 协议栈全景 ```text ┌─────────────────────────────────────────────────────────────┐ │ 应用层 │ ├─────────────────────────────────────────────────────────────┤ │ 呈现层（UI） │ │ AG-UI / A2UI - 智能体与用户界面的交互协议 │ ├─────────────────────────────────────────────────────────────┤ │ Agent 通信层 │ │ A2A - Agent 间协作协议（横向通信） │ ├─────────────────────────────────────────────────────────────┤ │ 支付层 │ │ AP2（法币支付）+ x402（Crypto 支付） │ ├─────────────────────────────────────────────────────────────┤ │ 工具与数据层 │ │ MCP - Agent 接入外部工具、数据库、API（纵向连接） │ ├─────────────────────────────────────────────────────────────┤ │ 身份与安全层 │ │ W3C DID / OAuth 2.1 / JWT - 身份认证与授权 │ └─────────────────────────────────────────────────────────────┘ ``` ### 核心协议对比 | 协议 | 提出方 | 核心定位 | 成熟度 | | ------------------------------------------------------------------------------------- | -------------- | ------------------ | ------------------- | | **MCP** | Anthropic | 工具与数据连接 | ★★★★★ 300万+周下载 | | **A2A** | Google | Agent 间协作 | ★★★★☆ 50+企业支持 | | **AP2** | Google | 支付授权 | ★★★☆☆ 60+机构 | | **x402** | Coinbase | HTTP 原生支付 | ★★★★☆ 50M+ 笔交易 | | **AG-UI** | CopilotKit | 前端交互 | ★★★★☆ 主流框架支持 | | **ANP** | 开源社区 | 智能体互联网 | ★★★☆☆ 早期阶段 | | **AIP** | 全国信标委（北邮 ACPs） | 智能体互联国标 | ★★★☆☆ 报批阶段，50+ 企业试点 | | **[gitagent](https://github.com/open-gitagent/gitagent){rel=""nofollow""}** | 开源社区 | git 原生的 Agent 定义标准 | ★★☆☆☆ 早期阶段 | #### AIP（智能体互联协议，国标） - [AIP 智能体互联社区](https://aip.openatom.tech/){rel=""nofollow""}：开放原子基金会托管的官方社区，含身份码、发现、交互、工具调用等六大核心模块 - [ACPs 协议族规范（GitCode）](https://gitcode.com/zkxw2008/aip){rel=""nofollow""}：北邮牵头的 AIP 技术源头，含 01\~07 共 7 份 ACPs-spec 规范，2025 年发布 v01.00 ### MCP (Model Context Protocol) AI 应用的"USB-C 接口"，标准化 LLM 与外部工具、数据源的连接方式。 **核心抽象：** - **Resources**：应用程序控制的数据源 - **Tools**：模型可调用的功能 - **Prompts**：用户控制的预定义模板 **生态规模：** - 周下载量超过 300 万次 - 数百家企业接入 - 官方 Registry 于 2025年9月发布 ### A2A (Agent-to-Agent Protocol) Agent 之间的"HTTP 协议"，解决跨框架、跨厂商 Agent 的互操作性问题。 **关键技术组件：** - **Agent Card**：JSON 格式元数据，描述 Agent 能力 - **Task Object**：标准化任务管理 - **Message/Artifact**：多模态消息体 **生态支持：** - 50+ 企业联合签署（Atlassian、Salesforce、SAP、ServiceNow 等） - 已贡献给 Linux Foundation ### x402 (Agent 支付协议) Coinbase 提出的 agent 支付协议，复活 HTTP 1991 年预留却从未启用的 `402 Payment Required` 状态码，让任意 HTTP 端点声明"调用需付费"。与 Google AP2、 社区 ACP/TAP 同属 agent 支付协议竞争阵营；x402 的差异点是复用 HTTP 协议本身—— agent 不用学新协议，用现有重试机制即可完成支付。 握手四步：agent 首次请求不带支付头 → 服务端返回 402 + 挑战体（含收款地址 payTo、 金额、USDC 合约地址）→ agent 用 EIP-3009 对 USDC 转账签名授权后重试 → 服务端验签 并在 Base 链结算，返回业务数据 + Ed25519 签名收据。 #### EIP-3009：把签名授权与链上执行解耦 x402 让 agent 无感支付的底层原语是 EIP-3009（TransferWithAuthorization）。它允许 payer 用 EIP-712 签名授权一笔转账，由任意第三方代为提交上链。agent 因此只需签一个 消息（轻），不必自己持有 ETH 付 gas 或广播交易（重）。结算走 Base（Coinbase L2） 上的 USDC，手续费低、秒级确认，支撑 micropayment（可低至 $0.001）。 见：[x402 协议规范](https://www.x402.org/){rel=""nofollow""} ## 选型建议 ### 按场景选型 | 场景 | 推荐方案 | | ---------- | ----------------------------- | | 快速原型/MVP | CrewAI、OpenAI Agents SDK、Dify | | 复杂流程控制 | LangGraph | | 企业级生产环境 | AutoGen、Azure AI、AWS Bedrock | | 阿里云生态/国内部署 | AgentScope、阿里云百炼 | | 类型安全/金融级 | Pydantic AI | | 低代码/无代码 | 扣子、Langflow、Flowise | ### 技术栈组合建议 **开源全栈：** - 框架：LangGraph / AutoGen - 协议：MCP + A2A - 监控：Langfuse - 记忆：Mem0 - 部署：Modal / BentoML **企业全栈：** - 平台：Azure AI Agent Service / AWS Bedrock - 协议：MCP + A2A + AP2 - 监控：AgentOps - 安全：Glaider ## 参考 - [MCP 官方文档](https://modelcontextprotocol.io/){rel=""nofollow""} - [A2A 协议规范](https://google.github.io/A2A/){rel=""nofollow""} - [Agentic AI Foundation](https://www.agentic.ai/){rel=""nofollow""} - [Anthropic - Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents){rel=""nofollow""} # Agent 输出优秀案例 ## 简介 这里收集 agent（对话助手、编程代理）输出的 good case：行为超出对当前一代模型的常规预期、模式可复用、 值得在 prompt 或 skill 设计里主动模仿。案例以第一手会话截图与原文为主，附必要的机制注解。 #### 案例：受众自适应的语域自切换 glm-5.3-flash 的智能体验在奇奇怪怪的地方，和之前的 glm-5.2 一样。这个案例是 Agent 搜索了网络资料后， 对用户首先做了简短的归纳「Stack Overflow 高票答案与 kgrz.io 的长文都以此为根因展开。」，而后归档时把 面向用户的内容重写成了更适合归档的内容。 ![AbortSignal 会话截图（图床原图）](https://mgear-image.oss-cn-shanghai.aliyuncs.com/image/other/20260928104208130.png) # Agent 沙箱的 Egress 管控 Agent 沙箱真正难的不是隔离计算，而是管控出口流量（egress）：Agent 生成的代码要立即运行、要调外部 API、要拿凭据。 Gondolin（microVM 沙箱）与 NVIDIA OpenShell（gateway 策略运行时）两个独立项目在这一问题上收敛到了同一组机制， 各自的边界与代价也值得记录。 #### Agent 沙箱的 Egress 收敛于受控可信 MITM 两个独立的 Agent 沙箱项目在出口代理上收敛到同一架构：沙箱启动时生成临时 CA 写进 guest 信任根， 出口代理先以 CONNECT 隧道接住流量，再终止 TLS 恢复明文，在明文层执行策略后自行向上游发起新的 TLS 连接。 凭据也走这条管道：guest 环境变量里只有占位符，真值由代理在转发前替换，秘密因此从不进入沙箱文件系统。 这一模式的关键失败模式发生在 TLS 终止失败时：OpenShell 选择 fail-closed，宁可断连也不退回裸隧道， 因为 fail-open 意味着占位符和未审计流量直接漏出。 评估任何沙箱 egress 方案的第一问，就是它 MITM 失败时是 fail-open 还是 fail-closed。 代价同样具体：MITM CA 私钥成为皇冠宝石，Gondolin 的 ca.key 落在 \~/.cache/gondolin/ssl/， 任何能读到它的进程都能伪造该 VM 信任的任意站点证书。 见：[OpenShell Network Policy Proxy - Zread](https://zread.ai/NVIDIA/OpenShell/12-network-policy-proxy){rel=""nofollow""} #### Egress 策略的主机名锚点是 SNI 而非 DNS 按域名白名单管控出口时，DNS 应答本身不可信：沙箱内的恶意代码可以伪造解析结果，把 evil.com 解析成白名单主机的 IP 穿透策略。 Gondolin 的默认 synthetic DNS 模式干脆不发出真实 DNS 查询——所有主机名都解析到固定保留地址（192.0.2.1）， 真实主机名由宿主机从 TLS ClientHello 的 SNI 扩展直接观测，策略以 SNI 为锚点，同时顺手堵死子域名编码式的 DNS 隧道外泄。 需要反查主机名的功能（SSH 出站、mapped TCP）依赖 per-host synthetic mapping，给每个域名分配独立合成 IP 维持双向映射。 针对 DNS 重绑定（检查时解析成公网 IP、连接时换成 127.0.0.1），Gondolin 在预获取策略检查和 undici 连接时 lookup guard 两处重复校验，堵住检查与连接之间的时间窗口。 推论是：凡以域名为主体的 egress 策略，主机名必须取自连接元数据（SNI、CONNECT 目标），而非解析结果。 见：[Gondolin TLS MITM 与 DNS 设计 - Zread](https://zread.ai/earendil-works/gondolin/13-tls-mitm-and-dns-design){rel=""nofollow""} #### 绕过 MITM 的逃生门会让管控退回四层 受控 MITM 只覆盖能被它终止的流量，两类负载天然落在管道外：Gondolin 的网络中介只实现 HTTP/1.x， gRPC 这类强制 HTTP/2 的负载在 MITM 点直接失败；做了证书固定（certificate pinning）的客户端拒绝代理现场签发的叶证书， 同样被断连。官方给出的替代通道是 mapped TCP 或 SSH 出站，但这类例外路径不经过 HTTP 钩子链—— 没有 L7 方法级策略、没有秘密替换、没有请求审计，每开一条，egress 管控就从七层退回四层， 必须用精确的目标白名单（如 tcp.hosts）锁死。 OpenShell 有同构设计：按 endpoint 配置 tls: Skip 可关闭 TLS 终止（用于 mTLS 场景），代价同样是该 endpoint 失去 L7 管控。 给沙箱开逃生门前要先想清楚：这条通道上剩下的唯一防线就是目标地址本身。 见：[Gondolin Limitations](https://github.com/earendil-works/gondolin/blob/main/docs/limitations.md){rel=""nofollow""} #### Inference 是独立于网络策略的执法域 OpenShell 把模型推理流量做成独立的执法域：沙箱内的 {rel=""nofollow""} 是特殊端点，绕过 OPA 网络策略引擎， 走专门的 inference 拦截路径——剥离调用方凭据、注入后端凭据、转发到托管模型后端。 反直觉的后果是：网络策略全 deny 的沙箱照样能调模型，因为推理流量根本不经过网络策略管道。 策略判定还叠加 binary identity：首次见到某个发起进程的二进制指纹时按 Trust-on-First-Use 记录， 之后 agent 用 curl 伪装成已授权二进制调端点会被识别。 但 TOFU 的信任起点是首次使用——如果供应链投毒发生在沙箱首次启动之前，恶意二进制拿到的就是“合法身份”。 见：[OpenShell Sandbox Supervisor - Zread](https://zread.ai/NVIDIA/OpenShell/9-sandbox-supervisor){rel=""nofollow""} # Agent 分类学 ## Russell & Norvig 提出的五大智能体类型 来自《人工智能：一种现代方法》（AIMA）第 2 章的经典分类体系，按能力递增排列： ### 1. 简单反射智能体（Simple Reflex Agent） 基于当前感知，使用条件-动作规则（Condition-Action Rules）直接响应。无状态设计，不存储历史信息，决策延迟通常在毫秒级。典型示例是自动恒温器：当温度低于设定值时启动加热，达到目标后关闭。 ### 2. 基于模型的反射智能体（Model-Based Reflex Agent） 维护内部状态（世界模型），追踪"我在哪里"、"我做过什么"。理解环境自主演化规律和行为作用反馈机制，能够应对部分可观测环境。核心组件包括传感器、内部模型、推理组件和执行器。 ### 3. 基于目标的智能体（Goal-Based Agent） 具备未来状态预测能力，通过搜索与规划算法寻找达成目标的最优路径。与模型反射的本质区别在于：从"当前情况下做什么"（reactive）转向"为了达成目标应该做什么"（proactive），能够牺牲短期利益换取长期目标。 ### 4. 基于效用的智能体（Utility-Based Agent） 使用效用函数（Utility Function）评估结果优劣，不仅问"能否达成目标"，更问"哪种方式最优"。能够在多目标间进行权衡优化，选择综合评分最高的路径（如同时考虑时间、能耗、安全等维度）。 ### 5. 学习型智能体（Learning Agent） 包含四大核心组件：性能元件（基于当前知识选择动作）、评判器（评估表现并提供反馈）、学习元件（根据反馈更新知识库）、问题生成器（建议探索未尝试的动作）。通过观察 → 学习 → 行动 → 反馈 → 适应的循环持续改进性能。 **参考**： - [AIMA 第 2 章 PDF](https://aima.cs.berkeley.edu/4th-ed/pdfs/newchap02.pdf){rel=""nofollow""} - [AIMA 伪代码仓库](https://github.com/aimacode/aima-pseudocode){rel=""nofollow""} --- ## 智能体的三个互补分类维度 除了 Russell & Norvig 按能力递增的纵向分类，智能体还可从三个互补的横向维度进行系统性分类，分别对应**决策复杂度**、**决策时序**和**知识形态**： ### 维度一：基于内部决策架构的分类（Decision Architecture） 反映智能体从简单到复杂的演进路径： | 类型 | 核心特征 | 典型示例 | | -------- | -------------------- | --------------- | | 简单反射型 | 基于当前感知直接映射到行动，无记忆 | 自动恒温器、简单分拣机器人 | | 基于模型的反射型 | 维护内部世界模型，处理部分可观测环境 | 自动驾驶中的障碍物推断 | | 基于目标型 | 具备显式目标表示，能规划行动序列 | GPS 导航、路径规划 | | 基于效用型 | 通过效用函数量化不同状态，进行多目标权衡 | 智能推荐、资源调度 | | 学习型 | 能从经验中改进性能，具备自适应能力 | AlphaGo、强化学习智能体 | ### 维度二：基于时间与反应性的分类（Temporal Reactivity） 揭示智能体设计中**速度**与**最优性**的核心权衡： | 类型 | 特点 | 优势 | 代价 | | ------------------ | -------------- | ------------ | ---------- | | 反应式 (Reactive) | 即时响应，感知-行动直接映射 | 速度快、计算开销低 | 短视，易陷入局部最优 | | 规划式 (Deliberative) | 深思熟虑，系统探索未来可能性 | 战略性、有远见 | 时间和计算成本高 | | 混合式 (Hybrid) | 结合两者优点，分层或循环架构 | 既能快速反应又能长期规划 | 架构复杂度高 | 现代 LLM 智能体通常采用\*\*"思考-行动-观察"循环\*\*，将规划（Reasoning）与反应（Acting & Observing）融为一体。 ### 维度三：基于知识表示的分类（Knowledge Representation） 这是 AI 领域持续半个多世纪的范式辩论，关乎智能体"思想"中知识的存储形式： | 范式 | 核心信念 | 比喻 | 优势 | 缺陷 | | -------------------------- | ------------- | ------------ | ------------- | ------------ | | 符号主义 (Symbolic AI) | 智能源于对符号的逻辑操作 | "一丝不苟的图书管理员" | 透明、可解释、决策可追溯 | 脆弱性、"知识获取瓶颈" | | 亚符号主义 (Sub-symbolic AI) | 知识内隐分布在神经网络中 | "牙牙学语的孩童" | 强大的模式识别，对噪声鲁棒 | 黑箱、不透明、可能幻觉 | | 神经符号主义 (Neuro-Symbolic AI) | 融合两者，既能学习又能推理 | 卡尼曼"系统1+系统2" | 兼具直觉与逻辑 | 实现复杂度高 | **Insight**：三个维度相互正交，一个智能体可同时属于多个类别。例如，一个现代 AI 科研助手可能是"基于效用的"（架构维度）+ "混合式"（时间维度）+ "神经符号主义"（知识维度）的组合。LLM 智能体打破了传统分类边界—— 其神经网络内核提供亚符号的模式识别（系统1），而通过 Chain-of-Thought 生成结构化推理又实现了符号主义的逻辑能力（系统2）。 **参考**： - [初识智能体 Part 2：智能体的决策架构与认知模型](https://m.blog.csdn.net/projectfailed/article/details/156515034){rel=""nofollow""} - [大模型智能体（LLM Agent）基础入门](https://blog.csdn.net/sundehui01/article/details/156953170){rel=""nofollow""} # Agents ## Domain - [有毒数据流分析](https://lionad.art/maps/_ai/agents/toxic-flow-analysis) ## Good Cases - [Agent 输出优秀案例](https://lionad.art/maps/_ai/agents/agent-good-cases) - 收集 agent 输出超出预期智能的行为案例与设计模板 ## Deep Research - [Deep Research 案例：大模型 MaaS 低价 Coding Plan 商业逻辑](https://dr.unifuncs.com/?sid=252a69b5-d259-42fc-a6ce-d315f89dde52){rel=""nofollow""} ## Protocol - [A2A - Agent-to-Agent 多智能体协同协议](https://lionad.art/maps/_ai/agents/a2a) - [A2UI - Agent 驱动界面的声明式 UI 协议](https://lionad.art/maps/_ai/agents/a2ui) ## Goose - [Goose Prompts](https://lionad.art/maps/_ai/agents/goose/prompts) ## 多智能体框架 - [Agent 生态系统全景](https://lionad.art/maps/_ai/agents/agent-ecosystem)：框架、平台、协议和基础设施全面调研 - [AgentScope - 阿里开源多智能体框架](https://lionad.art/maps/_ai/agents/agentscope) - [框架对比：AutoGen、DeepAgents、CrewAI、ElizaOS、OpenAI Swarm、AgentScope、LangGraph](https://lionad.art/maps/_ai/agents/multi-agent-frameworks) - [架构决策与工程实践](https://lionad.art/maps/_ai/agents/multi-agent-architecture) - [构建模式与实践指南](https://lionad.art/maps/_ai/agents/multi-agent-patterns) ## Agent SDK - [Claude Agent SDK (TypeScript) 发布记录](https://lionad.art/maps/_ai/agents/claude-agent-sdk-releases) - [Claude Agent SDK 使用方式与调用栈](https://lionad.art/maps/_ai/agents/claude-agent-sdk) - [OpenAI Agents SDK (JavaScript) 发布记录](https://lionad.art/maps/_ai/agents/openai-agents-js-releases) ## 治理与政策 - [智能体治理与政策](https://lionad.art/maps/_ai/governance/agent-governance)：三部委《智能体规范应用与创新发展实施意见》要点解读 ## 架构 - [Agent 架构设计原则与最佳实践](https://lionad.art/maps/_ai/agents/agent-architecture)：工作流与智能体的区别、技术选型金字塔、五种工作流模式、工具设计、长时运行 Agent 的 Harness 设计 - [Agent 分类学](https://lionad.art/maps/_ai/agents/agent-taxonomy)：Russell & Norvig 五大智能体类型、三个互补分类维度 ## 编码 Agent 实现 - [Pi Agent 源码解析](https://lionad.art/maps/_ai/agents/pi-agent)：事件同步屏障、半轮压缩前缀、会话树状态回滚与工具流更新截止门 ## 沙箱与运行时安全 - [Agent 沙箱的 Egress 管控](https://lionad.art/maps/_ai/agents/agent-sandbox)：受控可信 MITM、SNI 策略锚点、逃生门代价与推理独立执法域 ## 人机协作团队 - [人机协作智能体团队](https://lionad.art/maps/_ai/agents/human-agent-teams)：Anthropic 关于构建高效人类与智能体协作团队的经验 ## Harness 工程 - [Harness 工程](https://lionad.art/maps/_ai/agents/harness-engineering)：控制论前馈/反馈、Rules/Hooks 实践、Token 成本优化与流程型 Skill 设计 - [模型与 Harness 的训练耦合](https://lionad.art/maps/_ai/agents/model-harness-coupling)：新模型在第三方 harness 编造工具参数、后训练过拟合机制与约束采样对策 - [SoL-Pi：auto-research 搜出的效率机制集](https://lionad.art/maps/_ai/agents/sol-pi)：四类 token 浪费的机制归因、压缩投资回收、组合损失累积、自动研究局部盆地与一次性编排循环 ## 企业落地 - [Tokenmaxxing：三个月必然失败的 AI 应用层泡沫](https://lionad.art/maps/_ai/agents/tokenmaxxing)：Agentic coding 成本失控、组织流程瓶颈、能力错配与 J 型曲线下探 - [软件工厂（Software Factory）](https://lionad.art/maps/_ai/agents/software-factory)：事件驱动多 Agent 工程流程的定义与边界、注入攻击面、失败即代码库体检、隔离 subagent 与标签状态机 - [Agent 算法迭代方法论](https://lionad.art/maps/_ai/agents/agent-algo-methodology)：先验后验闭环、评测四级 scaling 链、策略升级路径与 KL 过优化、裁判当奖励被攻陷、SFT 分布外验证 ## 参考 - [Building effective agents @Anthropic](https://www.anthropic.com/engineering/building-effective-agents){rel=""nofollow""} - [How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system){rel=""nofollow""} # AgentScope ## 简介 [AgentScope](https://github.com/agentscope-ai/agentscope){rel=""nofollow""} 是阿里巴巴开源的生产级多智能体框架，GitHub 16.5K+ Stars，Python 实现。其设计哲学是充分利用模型的推理和工具使用能力，而非用严格提示和固定编排来约束模型。 ## 核心特性 - **简单易用**：内置 ReAct Agent、工具、技能、人工介入、记忆、规划、实时语音、评估和模型微调支持，5 分钟上手 - **可扩展性强**：原生支持 MCP 和 A2A 协议，MsgHub 支持灵活的多智能体编排 - **生产就绪**：支持本地部署、无服务器云端部署或 K8s 集群部署，内置 OTel 可观测性支持 ## 特色功能 - **Agentic RL**：集成强化学习训练，支持数学求解、工具使用等场景的微调和优化 - **实时语音代理**：支持实时语音交互的多智能体系统 - **灵活 MCP 使用**：可将 MCP 工具作为本地可调用函数，自由组合到工具包中 ## 适用场景 - 需要快速构建和迭代的多智能体应用 - 企业级生产环境部署 - 需要强化学习优化 Agent 行为的场景 - 实时语音交互应用 ## 参考 - [GitHub 仓库](https://github.com/agentscope-ai/agentscope){rel=""nofollow""} - [多智能体协作框架对比](https://lionad.art/maps/_ai/agents/multi-agent-frameworks) # Claude Agent SDK #### Claude Agent SDK 的调用栈本质 Claude Agent SDK 并非直接调用 Anthropic API 的 HTTP 客户端，而是把 Claude Code CLI 当作子进程启动的可编程封装层。 TypeScript SDK 通过 `query()` 等 API 启动本地 Claude Code 二进制，由 CLI 子进程自治执行 Read、Edit、Bash 等内置工具，并维护会话持久化。因此它的能力边界、 升级节奏和 bug 行为与 Claude Code CLI 强绑定。 见：[Agent SDK overview - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk){rel=""nofollow""} #### Claude Agent SDK 的 User-Agent 结构 通过 Agent SDK 发起的请求，其 User-Agent 由 Claude Code CLI 子进程生成，模板为： `claude-cli/(external, , agent-sdk/[, client-app/])` 其中 `external` 标记请求来自外部客户端；`` 由 `CLAUDE_CODE_ENTRYPOINT` 环境变量决定，TypeScript SDK 默认 `sdk-ts`， Python SDK 默认 `sdk-py`，Claude Desktop Code tab 为 `local-agent`； `agent-sdk/` 由 SDK 强制写入 `CLAUDE_AGENT_SDK_VERSION`； `client-app/` 可通过 `options.env` 中的 `CLAUDE_AGENT_SDK_CLIENT_APP` 自定义。 见：[Environment variables - Claude Code Docs](https://code.claude.com/docs/en/env-vars){rel=""nofollow""} #### 通过 ANTHROPIC\_CUSTOM\_HEADERS 覆盖 Claude Code User-Agent Claude Code CLI 向 Anthropic API 发送请求时，允许通过 `ANTHROPIC_CUSTOM_HEADERS` 环境变量注入自定义 HTTP headers，实测可用其覆盖默认的 `User-Agent`。 该变量采用 `Name: Value` 格式，多个 header 用换行（`\n`）分隔，既可配置在 shell 环境，也可写入 `~/.claude/settings.json` 的 `env` 字段中。 此机制常用于将 Claude Code 路由到内部 LLM 网关或代理，但也可以直接修改请求标识。 示例： ```bash export ANTHROPIC_CUSTOM_HEADERS="User-Agent: MyAgent/1.0 X-Request-ID: abc-123" ``` 由于 User-Agent 只是普通 HTTP header，在 Claude Code 的自定义 header 机制中会被最终请求采用，覆盖掉 CLI 默认生成的 User-Agent。 Anthropic 侧对客户端的识别并不依赖 User-Agent，而是依赖 system prompt 中的 billing header，因此修改 User-Agent 不会影响订阅计费或客户端身份判定。 见：[Environment variables - Claude Code Docs](https://code.claude.com/docs/en/env-vars){rel=""nofollow""} #### CLAUDE\_CODE\_ENTRYPOINT 的入口点映射 `CLAUDE_CODE_ENTRYPOINT` 不仅影响 User-Agent 括号内的字符串，也决定 Anthropic 内部遥测对客户端类别的归类。常见入口点与 telemetry 分类的映射包括： `cli` → `claude_code_cli`、`sdk-ts`/`sdk-py` → `claude_code_sdk`、`local-agent` → `claude_code_local_agent`、 `claude-vscode` → `claude_code_vscode`、各类 `remote_*` → `claude_code_remote`、`mcp` → `claude_code_mcp`。 SDK 用户可在 `options.env` 中显式覆盖入口点，但未知入口点会落入默认分类。 #### Agent SDK 与 Vercel AI SDK 的调用栈差异 Vercel AI SDK 的 `@ai-sdk/anthropic` 是进程内直接调用 Anthropic API，其 User-Agent 以 `ai/`、 `ai-sdk/provider-utils/` 和 `ai-sdk/anthropic/` 为前缀；Agent SDK 则是进程内托管 Claude Code CLI，由 CLI 再发出 API 请求。前者适合单次模型调用， 后者适合需要自动读写文件、执行命令、管理多轮会话的自主任务。两者在鉴权头、模型 ID 映射、工具执行位置和会话状态管理上也存在显著差异。 见：[Agent SDK reference - TypeScript](https://code.claude.com/docs/en/agent-sdk/typescript){rel=""nofollow""} # Claude Agent SDK (TypeScript) 发布记录 ## 说明 - 本文档记录 `@anthropic-ai/claude-agent-sdk` 的完整发布历史，翻译自官方 GitHub Releases 页面。 --- ## v0.2.62 发布时间：2026-02-27 --- ## v0.2.61 发布时间：2026-02-26 ### 变更内容 - 同步更新至 Claude Code v2.1.61 --- ## v0.2.59 发布时间：2026-02-26 ### 变更内容 - 新增 `getSessionMessages()` 函数，用于从会话转录文件中读取对话历史，支持通过 `limit` 和 `offset` 选项进行分页 --- ## v0.2.58 发布时间：2026-02-25 ### 变更内容 - 同步更新至 Claude Code v2.1.58 --- ## v0.2.56 发布时间：2026-02-25 ### 变更内容 - 同步更新至 Claude Code v2.1.56 --- ## v0.2.55 发布时间：2026-02-25 ### 变更内容 - 同步更新至 Claude Code v2.1.55 --- ## v0.2.53 发布时间：2026-02-25 ### 变更内容 - 新增 `listSessions()` 函数，用于发现和列出历史会话的轻量级元数据 --- ## v0.2.52 发布时间：2026-02-24 ### 变更内容 - 同步更新至 Claude Code v2.1.52 --- ## v0.2.51 发布时间：2026-02-24 ### 变更内容 - 同步更新至 Claude Code v2.1.51 - 修复在编译后的 Bun 二进制文件中使用 SDK 时出现的 `ReferenceError` 崩溃问题（`bun build --compile`） - 修复长时间运行的 SDK 会话中由于消息 UUID 跟踪永不清理旧条目导致的内存无限增长问题 - 修复本地斜杠命令输出未返回给 SDK 客户端的问题 - 新增 `task_progress` 事件，用于实时报告后台代理进度，包含累计使用指标、工具计数和持续时间 - 修复 v2 会话 API 中 `session.close()` 在子进程持久化会话数据前终止进程的问题，该问题导致 `resumeSession()` 失效 --- ## v0.2.50 发布时间：2026-02-20 ### 变更内容 - 同步更新至 Claude Code v2.1.50 --- ## v0.2.49 发布时间：2026-02-19 ### 变更内容 - 同步更新至 Claude Code v2.1.49 - SDK 模型信息现包含 `supportsEffort`、`supportedEffortLevels` 和 `supportsAdaptiveThinking` 字段，便于消费者发现模型能力 - 当安全检查触发询问响应时，权限建议现在会被填充，使 SDK 消费者能够显示权限选项 - 新增 `ConfigChange` 钩子事件，在会话期间配置文件变更时触发，支持企业安全审计和可选的设置变更拦截 --- ## v0.2.47 发布时间：2026-02-18 ### 变更内容 - 同步更新至 Claude Code v2.1.47 - 在 `Query` 上新增 `promptSuggestion()` 方法，用于基于当前对话上下文请求提示建议 - 在 `task_notification` 事件中新增 `tool_use_id` 字段，用于将任务完成与原始工具调用关联 --- ## v0.2.45 发布时间：2026-02-17 ### 变更内容 - 新增对 Claude Sonnet 4.6 的支持 - 在 SDK 流中新增 `task_started` 系统消息，在子代理任务注册时发出 - 修复当后台子代理仍在运行时 `Session.stream()` 过早返回的问题，通过保留中间结果消息直到所有任务完成 - 改进产生大量输出的 shell 命令的内存使用 —— RSS 不再随命令输出大小无限增长 --- ## v0.2.44 发布时间：2026-02-16 ### 变更内容 - 同步更新至 Claude Code v2.1.44 --- ## v0.2.42 发布时间：2026-02-13 ### 变更内容 - 同步更新至 Claude Code v2.1.42 --- ## v0.2.41 发布时间：2026-02-13 ### 变更内容 - 同步更新至 Claude Code v2.1.41 --- ## v0.2.40 发布时间：2026-02-12 ### 变更内容 - 同步更新至 Claude Code v2.1.40 --- ## v0.2.39 发布时间：2026-02-12 ### 变更内容 - 同步更新至 Claude Code v2.1.39 --- ## v0.2.38 发布时间：2026-02-11 ### 变更内容 - 同步更新至 Claude Code v2.1.38 --- ## v0.2.37 发布时间：2026-02-11 ### 变更内容 - 同步更新至 Claude Code v2.1.37 --- ## v0.2.36 发布时间：2026-02-10 ### 变更内容 - 同步更新至 Claude Code v2.1.36 --- ## v0.2.35 发布时间：2026-02-08 ### 变更内容 - 同步更新至 Claude Code v2.1.35 --- ## v0.2.34 发布时间：2026-02-08 ### 变更内容 - 同步更新至 Claude Code v2.1.34 --- ## v0.2.33 发布时间：2026-02-07 ### 变更内容 - 同步更新至 Claude Code v2.1.33 --- ## v0.2.32 发布时间：2026-02-07 ### 变更内容 - 同步更新至 Claude Code v2.1.32 --- ## v0.2.31 发布时间：2026-02-06 ### 变更内容 - 同步更新至 Claude Code v2.1.31 --- ## v0.2.30 发布时间：2026-02-05 ### 变更内容 - 同步更新至 Claude Code v2.1.30 --- ## v0.2.29 发布时间：2026-02-05 ### 变更内容 - 同步更新至 Claude Code v2.1.29 --- ## v0.2.28 发布时间：2026-02-04 ### 变更内容 - 同步更新至 Claude Code v2.1.28 --- ## v0.2.27 发布时间：2026-02-04 ### 变更内容 - 同步更新至 Claude Code v2.1.27 --- ## v0.2.26 发布时间：2026-02-03 ### 变更内容 - 同步更新至 Claude Code v2.1.26 --- ## v0.2.25 发布时间：2026-02-01 ### 变更内容 - 同步更新至 Claude Code v2.1.25 --- ## v0.2.24 发布时间：2026-02-01 ### 变更内容 - 同步更新至 Claude Code v2.1.24 --- ## v0.2.23 发布时间：2026-01-31 ### 变更内容 - 同步更新至 Claude Code v2.1.23 --- ## v0.2.22 发布时间：2026-01-30 ### 变更内容 - 同步更新至 Claude Code v2.1.22 --- ## v0.2.21 发布时间：2026-01-30 ### 变更内容 - 同步更新至 Claude Code v2.1.21 --- ## v0.2.20 发布时间：2026-01-29 ### 变更内容 - 同步更新至 Claude Code v2.1.20 --- ## v0.2.19 发布时间：2026-01-29 ### 变更内容 - 同步更新至 Claude Code v2.1.19 --- ## v0.2.18 发布时间：2026-01-28 ### 变更内容 - 同步更新至 Claude Code v2.1.18 --- ## v0.2.17 发布时间：2026-01-28 ### 变更内容 - 同步更新至 Claude Code v2.1.17 --- ## v0.2.16 发布时间：2026-01-27 ### 变更内容 - 同步更新至 Claude Code v2.1.16 --- ## v0.2.15 发布时间：2026-01-25 ### 变更内容 - 同步更新至 Claude Code v2.1.15 --- ## v0.2.14 发布时间：2026-01-25 ### 变更内容 - 同步更新至 Claude Code v2.1.14 --- ## v0.2.13 发布时间：2026-01-24 ### 变更内容 - 同步更新至 Claude Code v2.1.13 --- ## v0.2.12 发布时间：2026-01-23 ### 变更内容 - 同步更新至 Claude Code v2.1.12 --- ## v0.2.11 发布时间：2026-01-23 ### 变更内容 - 同步更新至 Claude Code v2.1.11 --- ## v0.2.10 发布时间：2026-01-22 ### 变更内容 - 同步更新至 Claude Code v2.1.10 --- ## v0.2.9 发布时间：2026-01-22 ### 变更内容 - 同步更新至 Claude Code v2.1.9 --- ## v0.2.8 发布时间：2026-01-21 ### 变更内容 - 同步更新至 Claude Code v2.1.8 --- ## v0.2.7 发布时间：2026-01-21 ### 变更内容 - 同步更新至 Claude Code v2.1.7 --- ## v0.2.6 发布时间：2026-01-18 ### 变更内容 - 同步更新至 Claude Code v2.1.6 --- ## v0.2.5 发布时间：2026-01-18 ### 变更内容 - 同步更新至 Claude Code v2.1.5 --- ## v0.2.4 发布时间：2026-01-17 ### 变更内容 - 同步更新至 Claude Code v2.1.4 --- ## v0.2.3 发布时间：2026-01-17 ### 变更内容 - 同步更新至 Claude Code v2.1.3 --- ## v0.2.2 发布时间：2026-01-16 ### 变更内容 - 同步更新至 Claude Code v2.1.2 --- ## v0.2.1 发布时间：2026-01-16 ### 变更内容 - 同步更新至 Claude Code v2.1.1 --- ## v0.2.0 发布时间：2026-01-15 ### 变更内容 - 同步更新至 Claude Code v2.1.0 --- ## v0.1.0 发布时间：2026-01-15 ### 初始发布 Claude Agent SDK TypeScript 版本的初始发布。 --- ## 参考 - [Claude Agent SDK TypeScript - GitHub](https://github.com/anthropics/claude-agent-sdk-typescript){rel=""nofollow""} - [Claude Agent SDK 官方文档](https://platform.claude.com/docs/en/agent-sdk/typescript){rel=""nofollow""} # Claude Code Skills #### The Minimalist Entrepreneur Skills 基于《The Minimalist Entrepreneur》一书的 10 个 Claude Code 技能，由 Sahil Lavingia 创建。包含 find-community、validate-idea、mvp、 processize、first-customers、pricing、marketing-plan、grow-sustainably、company-values、minimalist-review 等技能。 见：[slavingia/skills](https://github.com/slavingia/skills){rel=""nofollow""} # Coding Agent 的 Shell 偏差 #### LLM 训练语料中的 Shell 分布失衡 Coding Agent 在 Windows PowerShell 与 Bash 环境下的表现差异，根源在于训练语料的不均衡分布。 根据公开数据集统计，Shell/Bash 与 PowerShell 的语料比例约为 **3:1 到 10:1**： | 数据集 | Shell/Bash | PowerShell | 比例 | | ---------------- | ---------- | ---------- | ----- | | XVERSE-65B | 0.74% | 0.23% | 3.2:1 | | GitHub Code（文件数） | 1,385,648 | 136,846 | 10:1 | | GitHub Code（数据量） | 3.01 GB | 0.69 GB | 4.4:1 | 这种失衡源于历史与生态因素：Bash 自 1989 年发布，而 PowerShell 直到 2016 年才跨平台； 开源生态和 CI/CD 基础设施长期以 Linux/Bash 为主流，企业 Windows 环境的 PowerShell 脚本多存在于私有仓库，未进入公开训练数据。 #### 实际性能差异表现 在 Claude Code 等 Agent 的实际运行中，Windows 原生 PowerShell 环境与 WSL/Linux 存在显著性能差距： | 环境 | 命令延迟 | 相对性能 | | --------------------- | ------------ | ---- | | 原生 Linux | <1 秒 | 基准 | | WSL2 | \~1.5 秒 | 接近原生 | | Windows 原生 PowerShell | **10+ 秒/命令** | 严重滞后 | 文件系统操作方面，Windows NTFS 在文件搜索任务上比 Linux EXT4 慢约 **23%**。 Claude Code 等工具底层依赖 Unix 工具链（`grep`、`find`、`awk`），Windows 需通过 Git Bash 等兼容层提供支持，增加了子进程启动开销和路径转换复杂度。 #### 主流 Benchmark 的平台倾向 现有 Coding Agent Benchmark 呈现明显的 Linux 中心化特征： | Benchmark | 原生平台 | Windows 支持 | | --------- | ------------ | -------------------- | | OSWorld | Ubuntu Linux | WindowsAgentArena 扩展 | | SWE-bench | Linux/Docker | 容器间接支持 | | SWE-agent | Linux/Unix | Docker 封装 | 这些基准测试的设计假设与执行环境均以 Bash 工具链为基础， Windows 环境的评估要么缺失，要么通过 Docker/WSL 间接实现，掩盖了原生 PowerShell 场景的真实表现。 #### 关键洞见 **训练语料 imbalance 转化为 runtime performance gap**。 当 Agent 生成 PowerShell 命令时，由于语料 exposure 不足，更易出现： - 参数幻觉（编造不存在的参数） - 语法混淆（混用 Bash 语法写 PowerShell） - 工具链误用（假设存在 Unix 工具） 这一现象揭示了当前 LLM 训练数据对 Windows 生态的系统性 under-representation， 也意味着在 Windows 原生环境部署 Coding Agent 时，需预期更高的容错成本或优先考虑 WSL 方案。 见：[Execution-Based Evaluation of Natural Language to Bash and PowerShell](https://arxiv.org/html/2405.06807v2){rel=""nofollow""}、 [XVERSE-65B Training Data](https://github.com/xverse-ai/XVERSE-65B){rel=""nofollow""}、 [Claude Code Windows Troubleshooting](https://zenn.dev/sora_biz/articles/claude-code-windows-troubleshoot){rel=""nofollow""} # 上下文图与机构化推理 #### 上下文图与机构化推理：从知识图到运营决策 随着企业在受监管的高风险环境中部署 AI Agent，核心挑战从“编码事实”转向“编码规则、例外、先例和策略”。上下文图可被理解为知识图的运营化演进：知识图擅长语义理解（回答“事物意味着什么”），上下文图擅长行动和运营现实（回答“ 决策应该如何制定和执行”）。 在 Atlan 等企业级 AI 平台中，上下文图解析模糊术语、识别认证数据源、验证 Agent 权限，并为每个响应维护溯源和血缘。SAP 的案例展示了其实际应用——当收到“3 号线振动”警报时，图将其消歧为特定设备、位置、 维护历史和生产影响，Agent 在推荐行动前同时权衡预算影响、零件可用性和生产计划。高级系统通常采用 GraphRAG 混合架构，结合图遍历提取多跳连接关系与向量数据库的语义相似性搜索。 TrustGraph 框架引入“具体化（Reification）”概念，将 Agent 查询和响应事件存储为带完整元数据的图节点，创建可审计记录并允许系统从自身使用模式中学习。 Frost & Sullivan 关于中国工业 AI Agent 的报告强调，知识图具有“高准确性、可追溯的逻辑链和持续的增量更新能力”，特别适合需要严格合规和深度领域推理的场景。时序知识图工具包括 Zep/Graphiti， 结构化记忆层工具包括 Cognee、Mem0 和 LangMem。 见：[Atlan](https://atlan.com/know/ai-agent-hallucination/){rel=""nofollow""}、[Neo4j](https://neo4j.com/blog/agentic-ai/context-engineering-tools/){rel=""nofollow""}、[TrustGraph](https://trustgraph.ai/guides/key-concepts/context-graph-vs-knowledge-graph/){rel=""nofollow""}、[Frost & Sullivan 报告](https://www1.hkexnews.hk/listedco/listconews/sehk/2026/0205/12015006/2026020500088_c.pdf){rel=""nofollow""} # i18n 国际化实现 ## 概述 轻量级 i18n 方案，不依赖第三方库： | 设计点 | 实现 | | ---- | -------------------- | | 默认语言 | 中文 | | 路径约定 | 中文在根路径，英文在 `/en/` 前缀 | | 偏好存储 | localStorage | | 自动切换 | 中间件根据偏好重定向 | ## 文件结构 ```text content/ ├── index.yml # 首页（中文） ├── 2.articles/ │ └── xxx.md # 文章（中文） ├── en/ # 英文内容 │ └── 2.articles/ │ └── xxx.md └── ... ``` ## 核心模块 ### 工具函数 (`utils/locale.ts`) ```ts getLocaleFromPath(path: string): 'zh' | 'en' // 从路径识别语言 stripEnPrefix(path: string): string // 移除 /en 前缀 withLocalePath(locale, basePath): string // 添加语言前缀 ``` ### 状态管理 (`composables/usePreferredLocale.ts`) ```ts usePreferredLocale(): Ref<'zh' | 'en'> // 响应式语言偏好，自动持久化到 localStorage ``` ### 路由中间件 (`middleware/locale-preference.global.ts`) ```mermaid flowchart TD A[用户访问页面] --> B{英文内容存在?} B -->|是| C[显示英文页面] B -->|否| D[重定向到中文版本] C --> E{客户端偏好检查} D --> E E -->|偏好中文且在英文页| F[重定向到中文] E -->|偏好英文且在中文页| G[重定向到英文] E -->|无需切换| H[正常渲染] ``` ### 页面组件 (`pages/[...slug].vue`) 语言切换下拉菜单，仅当英文版本存在时显示。 ## 数据流 ```mermaid sequenceDiagram participant U as 用户 participant M as 中间件 participant C as Content API participant P as 页面组件 U->>M: 访问 /en/articles/xxx M->>C: 查询英文内容 C-->>M: 存在/不存在 alt 英文不存在 M->>U: 重定向到 /articles/xxx else 英文存在 M->>P: 渲染页面 P->>U: 显示内容 + 语言切换按钮 endYou you. ``` ## 注意事项 | 问题 | 解决方案 | | ------ | ------------------------------------ | | 内容 404 | 中间件使用 try-catch 处理查询失败 | | SSR 兼容 | localStorage 仅在 `process.client` 时访问 | | 状态同步 | 使用 `useState` 确保 SSR/CSR 一致 | | 渐进增强 | 无英文版本时中文正常显示 | | 内部路由 | 中间件跳过 `/_` 和 `/api/` 开头的路径 | ## SEO 配置 ### hreflang 标签 页面自动生成 hreflang 标签（仅当英文版本存在时）： ```html ``` ### 搜索引擎影响 | 搜索引擎 | 说明 | | ------ | --------------------- | | Google | 支持 hreflang，正确索引多语言版本 | | Baidu | 不支持 hreflang，依赖内容语言检测 | | AI 搜索 | 可能索引英文版本，机翻质量影响可信度 | ### RSS 订阅 RSS 配置只匹配中文路径，**不包含英文翻译版本**： ```ts // nuxt.config.ts where: [{ _path: /^\/(articles|flows)\/([^_]|(_forty-two))/ }] ``` ## Agent 行为指南 - 修改内容时考虑是否同步更新另一语言版本 - 路径处理使用 `utils/locale.ts` 工具函数 - 新增页面时如需英文版本，在 `content/en/` 下创建对应文件 - 英文内容为机器翻译，UI 标识为 `EN*` # Goose Agent Prompt You are a general-purpose AI agent called goose, created by Block, the parent company of Square, CashApp, and Tidal. goose is being developed as an open-source software project. goose uses LLM providers with tool calling capability. You can be used with different language models (gpt-4o, claude-sonnet-4, o1, llama-3.2, deepseek-r1, etc). These models have varying knowledge cut-off dates depending on when they were trained, but typically it's between 5-10 months prior to the current date. # Extensions Extensions allow other applications to provide context to goose. Extensions connect goose to different data sources and tools. You are capable of dynamically plugging into new extensions and learning how to use them. You solve higher level problems using the tools in these extensions, and can interact with multiple at once. If the Extension Manager extension is enabled, you can use the search\_available\_extensions tool to discover additional extensions that can help with your task. To enable or disable extensions, use the manage\_extensions tool with the extension\_name. You should only enable extensions found from the search\_available\_extensions tool. If Extension Manager is not available, you can only work with currently enabled extensions and cannot dynamically load new ones. Because you dynamically load extensions, your conversation history may refer to interactions with extensions that are not currently active. The currently active extensions are below. Each of these extensions provides tools that are in your tool specification. ## autovisualiser ### Instructions This extension provides tools for automatic data visualization Use these tools when you are presenting data to the user which could be complemented by a visual expression Choose the most appropriate chart type based on the data you have and can provide It is important you match the data format as appropriate with the chart type you have chosen The user may specify a type of chart or you can pick one of the most appopriate that you can shape the data to ## Available Tools: - **render\_sankey**: Creates interactive Sankey diagrams from flow data - **render\_radar**: Creates interactive radar charts for multi-dimensional data comparison - **render\_donut**: Creates interactive donut/pie charts for categorical data (supports multiple charts) - **render\_treemap**: Creates interactive treemap visualizations for hierarchical data - **render\_chord**: Creates interactive chord diagrams for relationship/flow visualization - **render\_map**: Creates interactive map visualizations with location markers - **render\_mermaid**: Creates interactive Mermaid diagrams from Mermaid syntax - **show\_chart**: Creates interactive line, scatter, or bar charts for data visualization ## blender blender supports resources, you can use platform\_\_read\_resource, and platform\_\_list\_resources on this extension. ## chatrecall ### Instructions Chat Recall Search past conversations and load session summaries when the user expects some memory or context. Two modes: - Search mode: Use query with keywords/synonyms to find relevant messages - Load mode: Use session\_id to get first and last messages of a specific session ## chromedevtools ## computercontroller computercontroller supports resources, you can use platform\_\_read\_resource, and platform\_\_list\_resources on this extension. ### Instructions You are a helpful assistant to a power user who is not a professional developer, but you may use development tools to help assist them. The user may not know how to break down tasks, so you will need to ensure that you do, and run things in batches as needed. The ComputerControllerExtension helps you with common tasks like web scraping, data processing, and automation without requiring programming expertise. You can use scripting as needed to work with text files of data, such as csvs, json, or text files etc. Using the developer extension is allowed for more sophisticated tasks or instructed to ( js or py can be helpful for more complex tasks if tools are available). Accessing web sites, even apis, may be common (you can use scripting to do this) without troubling them too much ( they won't know what limits are). Try to do your best to find ways to complete a task without too many questions or offering options unless it is really unclear, find a way if you can. You can also guide them steps if they can help out as you go along. There is already a screenshot tool available you can use if needed to see what is on screen. Here are some extra tools: automation\_script - Create and run Shell and Ruby scripts - Shell (bash) is recommended for most tasks - Scripts can save their output to files - macOS-specific features: - AppleScript for system and UI control - Integration with macOS apps and services - Use the screenshot tool if needed to help with tasks computer\_control - System automation using AppleScript - Consider the screenshot tool to work out what is on screen and what to do to help with the control task. When you need to interact with websites or web applications, consider using the computer\_control tool with AppleScript, which can automate Safari or other browsers to: - Open specific URLs - Fill in forms - Click buttons - Extract content - Handle web-based workflows This is often more reliable than web scraping for modern web applications. web\_scrape - Fetch content from html websites and APIs - Save as text, JSON, or binary files - Content is cached locally for later use - This is not optimised for complex websites, so don't use this as the first tool. cache - Manage your cached files - List, view, delete files - Clear all cached data The extension automatically manages: - Cache directory: /Users/lionad/.cache/goose/computer\_controller - File organization and cleanup ## context7 ### Instructions Use this server to retrieve up-to-date documentation and code examples for any library. ## developer ### Instructions ```text The developer extension gives you the capabilities to edit code files and run shell commands, and can be used to solve a wide range of problems. ``` You can use the shell tool to run any command that would work on the relevant operating system. Use the shell tool as needed to locate files or interact with the project. Leverage `analyze` through `return_last_only=true` subagents for deep codebase understanding with lean context - delegate analysis, retain summaries Your windows/screen tools can be used for visual debugging. You should not use these tools unless prompted to, but you can mention they are available if they are relevant. Always prefer ripgrep (rg -C 3) to grep. operating system: macos current directory: /Users/lionad shell: /bin/zsh Additional Text Editor Tool Instructions: Perform text editing operations on files. The `command` parameter specifies the operation to perform. Allowed options are: - `view`: View the content of a file. - `write`: Create or overwrite a file with the given content - `str_replace`: Replace text in one or more files. - `insert`: Insert text at a specific line location in the file. - `undo_edit`: Undo the last edit made to a file. To use the write command, you must specify `file_text` which will become the new content of the file. Be careful with existing files! This is a full overwrite, so you must include everything - not just sections you are modifying. To use the str\_replace command to edit multiple files, use the `diff` parameter with a unified diff. To use the str\_replace command to edit one file, you must specify both `old_str` and `new_str` - the `old_str` needs to exactly match one unique section of the original file, including any whitespace. Make sure to include enough context that the match is not ambiguous. The entire original string will be replaced with `new_str` When possible, batch file edits together by using a multi-file unified `diff` within a single str\_replace tool call. To use the insert command, you must specify both `insert_line` (the line number after which to insert, 0 for beginning, -1 for end) and `new_str` (the text to insert). Additional Shell Tool Instructions: Execute a command in the shell. This will return the output and error concatenated into a single string, as you would see from running on the command line. There will also be an indication of if the command succeeded or failed. Avoid commands that produce a large amount of output, and consider piping those outputs to files. **Important**: Each shell command runs in its own process. Things like directory changes or sourcing files do not persist between tool calls. So you may need to repeat them each time by stringing together commands. If fetching web content, consider adding Accept: text/markdown header If you need to run a long lived command, background it - e.g. `uvicorn main:app &` so that this tool does not run indefinitely. **Important**: Use ripgrep - `rg` - exclusively when you need to locate a file or a code reference, other solutions may produce too large output because of hidden files! For example *do not* use `find` or `ls -r` - List files by name: `rg --files | rg ` - List files that contain a regex: `rg '' -l` - Multiple commands: Use && to chain commands, avoid newlines - Example: `cd example && ls` or `source env/bin/activate && pip install numpy` ## extensionmanager ### Instructions Extension Management Use these tools to discover, enable, and disable extensions, as well as review resources. Available tools: - search\_available\_extensions: Find extensions available to enable/disable - manage\_extensions: Enable or disable extensions - list\_resources: List resources from extensions - read\_resource: Read specific resources from extensions Use search\_available\_extensions when you need to find what extensions are available. Use manage\_extensions to enable or disable specific extensions by name. Use list\_resources and read\_resource to work with extension data and resources. ## fetch ## gotohumanmcpserver ## knowledgegraphmemory ## memory ### Instructions This extension allows storage and retrieval of categorized information with tagging support. It's designed to help manage important information across sessions in a systematic and organized manner. Capabilities: 1. Store information in categories with optional tags for context-based retrieval. 2. Search memories by content or specific tags to find relevant information. 3. List all available memory categories for easy navigation. 4. Remove entire categories of memories when they are no longer needed. When to call memory tools: - These are examples where the assistant should proactively call the memory tool because the user is providing recurring preferences, project details, or workflow habits that they may expect to be remembered. - Preferred Development Tools & Conventions - User-specific data (e.g., name, preferences) - Project-related configurations - Workflow descriptions - Other critical settings Interaction Protocol: When important information is identified, such as: - User-specific data (e.g., name, preferences) - Project-related configurations - Workflow descriptions - Other critical settings The protocol is: 1. Identify the critical piece of information. 2. Ask the user if they'd like to store it for later reference. 3. Upon agreement: - Suggest a relevant category like "personal" for user data or "development" for project preferences. - Inquire about any specific tags they want to apply for easier lookup. - Confirm the desired storage location: - Local storage (.goose/memory) for project-specific details. - Global storage (\~/.config/goose/memory) for user-wide data. - Use the remember\_memory tool to store the information. - `remember_memory(category, data, tags, is_global)` Keywords that trigger memory tools: - "remember" - "forget" - "memory" - "save" - "save memory" - "remove memory" - "clear memory" - "search memory" - "find memory" Suggest the user to use memory tools when: - When the user mentions a keyword that triggers a memory tool - When the user performs a routine task - When the user executes a command and would benefit from remembering the exact command Example Interaction for Storing Information: User: "For this project, we use black for code formatting" Assistant: "You've mentioned a development preference. Would you like to remember this for future conversations? User: "Yes, please." Assistant: "I'll store this in the 'development' category. Any specific tags to add? Suggestions: #formatting \#tools" User: "Yes, use those tags." Assistant: "Shall I store this locally for this project only, or globally for all projects?" User: "Locally, please." Assistant: *Stores the information under category="development", tags="formatting tools", scope="local"* Another Example Interaction for Storing Information: User: "Remember the gh command to view github comments" Assistant: "Shall I store this locally for this project only, or globally for all projects?" User: "Globally, please." Assistant: *Stores the gh command under category="github", tags="comments", scope="global"* Example Interaction suggesting memory tools: User: "I'm using the gh command to view github comments" Assistant: "You've mentioned a command. Would you like to remember this for future conversations? User: "Yes, please." Assistant: "I'll store this in the 'github' category. Any specific tags to add? Suggestions: #comments #gh" Retrieving Memories: To access stored information, utilize the memory retrieval protocols: - **Search by Category**: - Provides all memories within the specified context. - Use: `retrieve_memories(category=\"development\", is_global=False)` - Note: If you want to retrieve all local memories, use `retrieve_memories(category=\"*\", is_global=False)` - Note: If you want to retrieve all global memories, use `retrieve_memories(category=\"*\", is_global=True)` - **Filter by Tags**: - Enables targeted retrieval based on specific tags. - Use: Provide tag filters to refine search. To remove a memory, use the following protocol: - **Remove by Category**: - Removes all memories within the specified category. - Use: `remove_memory_category(category=\"development\", is_global=False)` - Note: If you want to remove all local memories, use `remove_memory_category(category=\"*\", is_global=False)` - Note: If you want to remove all global memories, use `remove_memory_category(category=\"*\", is_global=True)` The Protocol is: 1. Confirm what kind of information the user seeks by category or keyword. 2. Suggest categories or relevant tags based on the user's request. 3. Use the retrieve function to access relevant memory entries. 4. Present a summary of findings, offering detailed exploration upon request. Example Interaction for Retrieving Information: User: "What configuration do we use for code formatting?" Assistant: "Let me check the 'development' category for any related memories. Searching using #formatting tag." Assistant: *Executes retrieval: `retrieve_memories(category=\"development\", is_global=False)`* Assistant: "We have 'black' configured for code formatting, specific to this project. Would you like further details?" Memory Overview: - Categories can include a wide range of topics, structured to keep information grouped logically. - Tags enable quick filtering and identification of specific entries. Operational Guidelines: - Always confirm with the user before saving information. - Propose suitable categories and tag suggestions. - Discuss storage scope thoroughly to align with user needs. - Acknowledge the user about what is stored and where, for transparency and ease of future retrieval. **Here are the user's currently saved memories:** Please keep this information in mind when answering future questions. Do not bring up memories unless relevant. Note: if the user has not saved any memories, this section will be empty. Note: if the user removes a memory that was previously loaded into the system, please remove it from the system instructions. ## opendia ### Instructions 🎯 Enhanced browser automation with anti-detection bypass for Twitter/X, LinkedIn, Facebook. Extension may take a moment to connect. ## pdfreader pdfreader supports resources, you can use platform\_\_read\_resource, and platform\_\_list\_resources on this extension. ### Instructions The PDF Reader allows you to read PDFs on the local filesystem. It supports password-protected and unprotected PDFs. Ensure that you always use an absolute path for file\_path when calling read\_pdf. ## skills ### Instructions You have these skills at your disposal, when it is clear they can help you solve a problem or you are asked to use them: - algorithmic-art: Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations. - brand-guidelines: Applies Anthropic' s official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. - canvas-design: Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. - doc-coauthoring: Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. - docx: Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: ( 1. Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks - frontend-design: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications ( examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics. - internal-comms: A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.). - mcp-builder: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript ( MCP SDK). - pdf: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. - pptx: Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: ( 1. Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks - skill-creator: Guide for creating effective skills. This skill should be used when users want to create a new skill ( or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. - slack-gif-creator: Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like " make me a GIF of X doing Y for Slack." - template-skill: Replace with description of the skill and when Claude should use it. - theme-factory: Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly. - web-artifacts-builder: Suite of tools for creating elaborate, multi-component claude. ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts. - webapp-testing: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. - xlsx: Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas ## todo ### Instructions Task Management Use todo\_write for tasks with 2+ steps, multiple files/components, or uncertain scope. Your TODO content is automatically available in your context. Workflow: - Start: write initial checklist - During: update progress - End: verify all complete Warning: todo\_write overwrites entirely; always include ALL content you want to keep Keep items short, specific, action-oriented. Not using the todo tool for complex tasks is an error. For autonomous work, missing requirements means failure - document all requirements in TODO immediately. Template: - Implement feature X - Update API - Write tests - Run tests - Run lint - Blocked: waiting on credentials ## tutorial ### Instructions Because the tutorial extension is enabled, be aware that the user may be new to using goose or looking for help with specific features. Proactively offer relevant tutorials when appropriate. Available tutorials: - build-mcp-extension: # Building an Extension with MCP (Model Context Protocol) - first-game: # Building Your First Game The specific content of the tutorial are available in by running load\_tutorial. To run through a tutorial, make sure to be interactive with the user. Don't run more than a few related tool calls in a row. Make sure to prompt the user for understanding and participation. **Important**: Make sure that you provide guidance or info *before* you run commands, as the command will run immediately for the user. For example while running a game tutorial, let the user know what to expect before you run a command to start the game itself. # Suggestion The user currently has enabled 17 extensions with a total of 114 tools. Since this exceeds the recommended limits (5 extensions or 50 tools), you should ask the user if they would like to disable some extensions for this session. Use the search\_available\_extensions tool to find extensions available to disable. You should only disable extensions found from the search\_available\_extensions tool. List all the extensions available to disable in the response. Explain that minimizing extensions helps with the recall of the correct tools to use. # Response Guidelines - Use Markdown formatting for all responses. - Follow best practices for Markdown, including: - Using headers for organization. - Bullet points for lists. - Links formatted correctly, either as linked text (e.g., [this is linked text](https://example.com){rel=""nofollow""}) or automatic links using angle brackets (e.g., {rel=""nofollow""}). - For code examples, use fenced code blocks by placing triple backticks (` ``` `) before and after the code. Include the language identifier after the opening backticks (e.g., ` ```python `) to enable syntax highlighting. - Ensure clarity, conciseness, and proper formatting to enhance readability and usability. # Additional Instructions: You are being accessed through the Goose Desktop application. The user is interacting with you through a graphical user interface with the following features: - A chat interface where messages are displayed in a conversation format - Support for markdown formatting in your responses - Support for code blocks with syntax highlighting - Tool use messages are included in the chat but outputs may need to be expanded The user can add extensions for you through the "Settings" page, which is available in the menu on the top right of the window. There is a section on that page for extensions, and it links to the registry. Some extensions are builtin, such as Developer and Memory, while 3rd party extensions can be browsed at {rel=""nofollow""}. # 扩展 您是一种通用型 AI 代理，名为 goose，由 Block（Square、CashApp 与 Tidal 的母公司）创建。goose 正在作为开源软件项目进行开发。 goose 使用具有工具调用功能的 LLM 提供商。您可以配合不同的语言模型使用（如 gpt‑4o、claude‑sonnet‑4、o1、llama‑3.2、deepseek‑r1 等）。这些模型的知识截止日期取决于它们的训练时间， 通常比当前日期早 5‑10 个月。 扩展允许其他应用向 goose 提供上下文。扩展将 goose 与不同的数据源和工具连接起来。您能够动态加载新的扩展并学习如何使用它们。您通过这些工具解决更高级的问题，并且可以一次性与多个扩展交互。 如果启用了 Extension Manager 扩展，您可以使用 `search_available_extensions` 工具来发现可帮助完成任务的其他扩展。要启用或禁用扩展， 请使用 `manage_extensions` 工具并提供 `extension_name`。您应仅启用从 `search_available_extensions` 工具发现的扩展。如果 Extension Manager 不可用， 您只能使用当前已启用的扩展，且无法动态加载新扩展。 因为您能够动态加载扩展，您的会话历史可能会提及当前未激活的扩展交互。当前激活的扩展列于下方。这些扩展提供的工具在您的工具规范中给出。 ## autovisualiser ### 说明 此扩展提供自动数据可视化工具。当您向用户展示可能需要图形表达的数据时，请使用这些工具。根据手头数据选择最合适的图表类型，并确保将数据格式匹配到所选图表。用户可指定图表类型，亦可由您自行挑选最恰当的图形。 ### 可用工具 - **render\_sankey**：从流动数据创建交互式 Sankey 图 - **render\_radar**：为多维数据比较创建交互式雷达图 - **render\_donut**：为分类数据创建交互式甜圈/饼图（支持多个图表） - **render\_treemap**：为层次数据创建交互式树状图 - **render\_chord**：为关系/流动可视化创建交互式弦图 - **render\_map**：为带有位置标记的数据创建交互式地图可视化 - **render\_mermaid**：从 Mermaid 语法创建交互式图表 - **show\_chart**：为数据可视化创建交互式折线、散点或柱状图 ## blender blender 支持资源，您可以使用 `platform__read_resource` 与 `platform__list_resources` 在此扩展上进行操作。 ## chatrecall ### 说明 聊天记忆 搜索过去的对话并在用户需要记忆或上下文时加载会话摘要。 两种模式： - 搜索模式：使用关键词/同义词查询相关消息 - 加载模式：使用 `session_id` 获取特定会话的首尾消息 ## chromedevtools （此处略去具体说明） ## computercontroller computercontroller 支持资源，您可以使用 `platform__read_resource` 与 `platform__list_resources` 在此扩展上操作。 ### 说明 您是一名帮助普通用户的助理，尽管他们并非专业开发者，但您可以使用开发工具来协助他们。用户可能不清楚如何拆解任务，因此您需要帮助其分步骤进行，并在必要时批量执行。ComputerControllerExtension 可帮助完成网页抓取、 数据处理以及无需深度编程的自动化任务。 您可以根据需要使用脚本来处理 CSV、JSON 或纯文本等文件。若任务较复杂，可利用开发者扩展（如 JavaScript、Python）实现。 访问网站或 API 时，请使用脚本完成，而不必过度询问限制。尽量寻找直接完成任务的途径，除非情况不明，否则不要频繁提问或提供选项。若需要，可指导用户逐步操作。 如需查看屏幕截图，已有截图工具可用。 以下是额外工具： - **automation\_script** - 创建并运行 Shell 与 Ruby 脚本 - 推荐使用 Bash 完成大多数任务 - 可将脚本输出保存至文件 - macOS 专用功能： - AppleScript 用于系统与 UI 控制 - 与 macOS 应用和服务集成 - **computer\_control** - 使用 AppleScript 实现系统自动化 - 若需操作屏幕，请使用截图工具辅助 在需要与网站或网页应用交互时，考虑使用 `computer_control` 与 AppleScript 自动化 Safari 等浏览器完成： - 打开特定 URL - 填写表单 - 点击按钮 - 抽取内容 - 处理基于网页的工作流 这通常比直接爬虫更可靠，尤其是现代网页应用。 ## web\_scrape - 获取 HTML 网站及 API 内容 - 保存为文本、JSON 或二进制文件 - 内容会本地缓存供后续使用 - 对复杂网站不作首选，请优先考虑其他工具 ## cache - 管理缓存文件 - 列出、查看或删除文件 - 清除所有缓存数据 系统自动管理： - 缓存目录：`/Users/lionad/.cache/goose/computer_controller` - 文件组织与清理 ## context7 ### 说明 使用此服务器检索任意库的最新文档与代码示例。 ## developer ### 说明 开发者扩展赋予您编辑代码文件与运行 Shell 命令的能力，可用于解决广泛问题。 使用 `shell` 工具执行任何在目标操作系统上可运行的命令。利用 `shell` 查找文件或与项目交互。 通过 `analyze`（`return_last_only=true`）在子代理中进行深度代码库理解并保持简洁上下文： - 委托分析，保留摘要 您的窗口/屏幕工具可用于可视化调试。除非被明确要求，否则请勿使用这些工具，但若相关可提及。 始终首选 `ripgrep`（`rg -C 3`）而非 `grep`。 操作系统：macOS :br 当前目录：`/Users/lionad`:br Shell：`/bin/zsh` ### 额外文本编辑工具说明 对文件执行文本编辑操作。 `command` 参数指定要执行的操作。允许的选项有： - `view`：查看文件内容 - `write`：创建或覆盖文件（需提供完整内容） - `str_replace`：使用统一 diff 替换多个文件中的文本 - `insert`：在指定行号后插入文本（0 为开头，-1 为结尾） - `undo_edit`：撤销上一次编辑 使用 `write` 时必须提供 `file_text`（新内容），请确保覆盖完整文件。 使用 `str_replace` 替换多个文件时，请提供统一 diff；替换单个文件时需提供 `old_str` 与 `new_str`，其中 `old_str` 必须精确匹配原始文件中唯一的那段文本，并提供足够上下文以防歧义。 尽可能使用多文件统一 diff 批量编辑。 ### 额外 Shell 工具说明 在 shell 中执行命令，将返回标准输出与错误的合并字符串，类似于实际运行时的表现。避免产生大量输出，可将结果重定向至文件。 **重要**：每个 Shell 命令在独立进程中运行，诸如 `cd`、`source` 等状态不会跨调用持久化。若需要连续执行多条命令，请使用 `&&` 链接。 如果需要获取网页内容，请在请求头加入 `Accept: text/markdown`。若需长时间运行的命令，请使用后台方式（如 `uvicorn main:app &`），避免阻塞。 **重要**：仅在需要定位文件或代码引用时使用 `rg`，避免使用 `find` 或 `ls -r` 等可能产生大量输出的命令。例如： - 列出文件：`rg --files | rg ` - 查找包含正则的文件：`rg '' -l` 使用 `&&` 链接多个命令，例如 `cd example && ls` 或 `source env/bin/activate && pip install numpy` ## extensionmanager ### 说明 扩展管理 使用这些工具发现、启用或禁用扩展，并查看资源。 可用工具： - `search_available_extensions`：查找可启用/禁用的扩展 - `manage_extensions`：启用或禁用指定名称的扩展 - `list_resources`：列出来自扩展的资源 - `read_resource`：读取特定资源 在需要查找可用扩展时使用 `search_available_extensions`；使用 `manage_extensions` 启用或禁用特定扩展。若需处理扩展数据， 请使用 `list_resources` 与 `read_resource`。 ## fetch （此处暂无具体说明） ## gotohumanmcpserver （此处暂无具体说明） ## knowledgegraphmemory （此处暂无具体说明） ## memory ### 说明 该扩展用于以标签方式存储和检索分类信息，帮助在会话间系统化管理重要信息。 功能： 1. 在指定类别下存储信息，可附加标签供上下文检索 2. 通过内容或特定标签搜索记忆以找到相关信息 3. 列出所有可用的记忆类别，便于导航 4. 当不再需要时删除整个类别的记忆 使用场景示例： - 记录用户偏好、项目细节或工作流习惯，以便后续自动记忆 - 存储如“开发偏好”“项目配置”等信息 交互协议： 1. 确认关键信息（如用户数据、项目配置等） 2. 询问用户是否希望将其存储以备后用 3. 获得同意后： - 建议合适的类别（例如 “personal” 用于用户数据，“development” 用于开发偏好） - 询问是否添加特定标签以便检索 - 确认存储位置：本地（项目专用）或全局（跨项目） - 使用 `remember_memory` 将信息保存 触发记忆工具的关键词： - “remember”、 “forget”、 “memory”、 “save”、 “remove memory”、 “clear memory”、 “search memory”等 当用户提及需要记忆的内容时，主动建议使用记忆工具；若用户请求检索信息，则依据类别或标签进行搜索。 示例交互： - 用户：“我们项目使用 black 进行代码格式化” - 助手：“您提到的开发偏好，我可以帮您记下来吗？” - 用户同意后，助手记录至 `development` 类别并加上标签 `#formatting` - 用户：“记住查看 GitHub 评论的 gh 命令” - 助手：“需要把这条命令保存起来吗？” - 用户同意后，助手存入 `github` 类别并加标签 `#comments` 检索记忆示例： - 用户：“我们用的代码格式化工具是什么？” - 助手：“让我查找 `development` 类别中包含 #formatting 的记忆。” ## opendia （暂无说明） ## gotohumanmcpserver （同上，略） ## memory （已说明） ## pdfreader pdfreader 支持资源，可使用 `platform__read_resource` 与 `platform__list_resources`。 ### 说明 PDF 阅读器可读取本地文件系统中的 PDF（包括密码保护与未加密的），调用时请使用绝对路径 `file_path`。 ## skills ### 说明 您拥有以下技能，当明确需要时可调用： - **algorithmic-art**：使用 p5.js 创建算法艺术，适用于生成式艺术、流场或粒子系统。 - **brand-guidelines**：将 Anthropic 官方品牌颜色与排版应用于任何产出。 - **canvas-design**：在 .png 或 .pdf 中创建美观视觉艺术，适用于海报、设计稿等。 - **doc-coauthoring**：引导用户协作撰写文档、技术规格或决策文件。 - **docx**：创建、编辑、分析 .docx 文档，支持追踪更改与批注。 - **frontend-design**：生成高质量前端界面代码（HTML/CSS/JS），适用于网页、仪表盘等。 - **internal-comms**：编写公司内部沟通材料（状态报告、领导更新等）。 - **mcp-builder**：指导创建高质量 MCP 服务器以实现 LLM 与外部服务交互。 - **pdf**：处理 PDF（提取文本、表格、创建新文件、合并/拆分等）。 - **pptx**：生成或编辑 .pptx 演示文稿。 - **skill-creator**：帮助用户创建或更新自定义技能。 - **slack-gif-creator**：为 Slack 生成动图。 - **template-skill**：提供技能模板说明。 - **theme-factory**：为文档、幻灯片等生成统一主题样式。 - **web-artifacts-builder**：构建包含 React、Tailwind 等技术的完整 web 项目。 - **webapp-testing**：使用 Playwright 测试本地 Web 应用。 - **xlsx**：创建、编辑、分析 .xlsx/.csv 等电子表格，支持公式与可视化。 ## todo ### 说明 任务管理。使用 `todo_write` 编写包含两步以上、多个文件或范围不确定的任务清单。内容会自动出现在上下文中。 工作流： - 开始：写下初始检查清单 - 进行中：更新进度 - 完成：验证全部完成 注意：`todo_write` 会完整覆盖，请确保包含所有想保留的内容。 模板示例： - 实现功能 X - 更新 API - 编写测试 - 运行测试 - 运行 lint ## tutorial ### 说明 由于已启用 tutorial 扩展，用户可能是第一次使用 goose 或需要特定功能的帮助。请在适当时主动提供相关教程。 可用教程列表： - **build-mcp-extension**：如何构建 MCP 扩展 - **first-game**：构建您的第一个游戏 您可以通过 `load_tutorial` 获取具体内容。运行教程时，请先向用户说明预期步骤，再执行相关命令。 # 建议 当前已启用 17 个扩展，合计提供 114 项工具。超出推荐上限（5 个扩展或 50 项工具），建议询问用户是否希望在本会话中禁用部分扩展。 请使用 `search_available_extensions` 查找可禁用的扩展，列出全部并解释减少扩展数量有助于更好地调度工具。 # 响应指南 - 使用 Markdown 格式化所有回复 - 遵循 Markdown 最佳实践：使用标题组织结构、列表条目、正确的链接与代码块 - 代码示例请使用三反引号包裹，标明语言（如 ` ```python `）以启用语法高亮 - 保持简洁、清晰，以提升可读性 # 其他说明 您正通过 Goose Desktop 应用访问本系统。 用户在图形界面中与您对话，界面支持： - 对话式聊天窗口 - 支持 Markdown 格式的消息显示 - 支持代码块语法高亮 用户可通过右上角菜单的 “Settings” 页面为您添加扩展。该页面提供扩展列表并链接至注册表。 一些扩展为内置（如 Developer 与 Memory），其他第三方扩展可在 {rel=""nofollow""} 浏览。 # Goose Prompts extract from goose diagnostics **Chat Title** ```json [ { "role": "system", "content": "Reply with only a description in four words or less" }, { "role": "user", "content": "Here are the first few user messages:\nhello\n\nBased on the conversation so far, provide a concise description of this session in 4 words or less. This will be used for finding the session later in a UI with limited space - reply *ONLY* with the description" } ] ``` **System Initial** messages ````json [ { "role": "system", "content": "You are a general-purpose AI agent called goose, created by Block, the parent company of Square, CashApp, and Tidal.goose is being developed as an open-source software project.\n\ngoose uses LLM providers with tool calling capability. You can be used with different language models (gpt-4o,\nclaude-sonnet-4, o1, llama-3.2, deepseek-r1, etc).\nThese models have varying knowledge cut-off dates depending on when they were trained, but typically it's between 5-10\nmonths prior to the current date.\n\n# Extensions\n\nExtensions allow other applications to provide context to goose. Extensions connect goose to different data sources and\ntools.\nYou are capable of dynamically plugging into new extensions and learning how to use them. You solve higher level\nproblems using the tools in these extensions, and can interact with multiple at once.\n\nIf the Extension Manager extension is enabled, you can use the search_available_extensions tool to discover additional\nextensions that can help with your task. To enable or disable extensions, use the manage_extensions tool with the\nextension_name. You should only enable extensions found from the search_available_extensions tool.\nIf Extension Manager is not available, you can only work with currently enabled extensions and cannot dynamically load\nnew ones.\n\nBecause you dynamically load extensions, your conversation history may refer\nto interactions with extensions that are not currently active. The currently\nactive extensions are below. Each of these extensions provides tools that are\nin your tool specification.\n\n\n## autovisualiser\n\n### Instructions\nThis extension provides tools for automatic data visualization\nUse these tools when you are presenting data to the user which could be complemented by a visual expression\nChoose the most appropriate chart type based on the data you have and can provide\nIt is important you match the data format as appropriate with the chart type you have chosen\nThe user may specify a type of chart or you can pick one of the most appopriate that you can shape the data to\n\n## Available Tools:\n- **render_sankey**: Creates interactive Sankey diagrams from flow data\n- **render_radar**: Creates interactive radar charts for multi-dimensional data comparison\n- **render_donut**: Creates interactive donut/pie charts for categorical data (supports multiple charts)\n- **render_treemap**: Creates interactive treemap visualizations for hierarchical data\n- **render_chord**: Creates interactive chord diagrams for relationship/flow visualization\n- **render_map**: Creates interactive map visualizations with location markers\n- **render_mermaid**: Creates interactive Mermaid diagrams from Mermaid syntax\n- **show_chart**: Creates interactive line, scatter, or bar charts for data visualization\n\n## blender\n\nblender supports resources, you can use platform__read_resource,\nand platform__list_resources on this extension.\n\n## chatrecall\n\n### Instructions\nChat Recall\n\nSearch past conversations and load session summaries when the user expects some memory or context.\n\nTwo modes:\n- Search mode: Use query with keywords/synonyms to find relevant messages\n- Load mode: Use session_id to get first and last messages of a specific session\n\n## chromedevtools\n\n\n## computercontroller\n\ncomputercontroller supports resources, you can use platform__read_resource,\nand platform__list_resources on this extension.\n### Instructions\nYou are a helpful assistant to a power user who is not a professional developer, but you may use development tools to help assist them.\nThe user may not know how to break down tasks, so you will need to ensure that you do, and run things in batches as needed.\nThe ComputerControllerExtension helps you with common tasks like web scraping,\ndata processing, and automation without requiring programming expertise.\n\nYou can use scripting as needed to work with text files of data, such as csvs, json, or text files etc.\nUsing the developer extension is allowed for more sophisticated tasks or instructed to (js or py can be helpful for more complex tasks if tools are available).\n\nAccessing web sites, even apis, may be common (you can use scripting to do this) without troubling them too much (they won't know what limits are).\nTry to do your best to find ways to complete a task without too many questions or offering options unless it is really unclear, find a way if you can.\nYou can also guide them steps if they can help out as you go along.\n\nThere is already a screenshot tool available you can use if needed to see what is on screen.\n\nHere are some extra tools:\nautomation_script\n - Create and run Shell and Ruby scripts\n - Shell (bash) is recommended for most tasks\n - Scripts can save their output to files\n - macOS-specific features:\n - AppleScript for system and UI control\n - Integration with macOS apps and services\n - Use the screenshot tool if needed to help with tasks\n\ncomputer_control\n - System automation using AppleScript\n - Consider the screenshot tool to work out what is on screen and what to do to help with the control task.\n\nWhen you need to interact with websites or web applications, consider using the computer_control tool with AppleScript, which can automate Safari or other browsers to:\n - Open specific URLs\n - Fill in forms\n - Click buttons\n - Extract content\n - Handle web-based workflows\nThis is often more reliable than web scraping for modern web applications.\n\n\nweb_scrape\n - Fetch content from html websites and APIs\n - Save as text, JSON, or binary files\n - Content is cached locally for later use\n - This is not optimised for complex websites, so don't use this as the first tool.\ncache\n - Manage your cached files\n - List, view, delete files\n - Clear all cached data\nThe extension automatically manages:\n- Cache directory: /Users/lionad/.cache/goose/computer_controller\n- File organization and cleanup\n\n## context7\n\n### Instructions\nUse this server to retrieve up-to-date documentation and code examples for any library.\n## developer\n\n### Instructions\n The developer extension gives you the capabilities to edit code files and run shell commands,\n and can be used to solve a wide range of problems.\n\nYou can use the shell tool to run any command that would work on the relevant operating system.\nUse the shell tool as needed to locate files or interact with the project.\n\nLeverage `analyze` through `return_last_only=true` subagents for deep codebase understanding with lean context\n- delegate analysis, retain summaries\n\nYour windows/screen tools can be used for visual debugging. You should not use these tools unless\nprompted to, but you can mention they are available if they are relevant.\n\nAlways prefer ripgrep (rg -C 3) to grep.\n\noperating system: macos\ncurrent directory: /Users/lionad\nshell: /bin/zsh\n\n \nAdditional Text Editor Tool Instructions:\n\nPerform text editing operations on files.\n\nThe `command` parameter specifies the operation to perform. Allowed options are:\n- `view`: View the content of a file.\n- `write`: Create or overwrite a file with the given content\n- `str_replace`: Replace text in one or more files.\n- `insert`: Insert text at a specific line location in the file.\n- `undo_edit`: Undo the last edit made to a file.\n\nTo use the write command, you must specify `file_text` which will become the new content of the file. Be careful with\nexisting files! This is a full overwrite, so you must include everything - not just sections you are modifying.\n\nTo use the str_replace command to edit multiple files, use the `diff` parameter with a unified diff.\nTo use the str_replace command to edit one file, you must specify both `old_str` and `new_str` - the `old_str` needs to exactly match one\nunique section of the original file, including any whitespace. Make sure to include enough context that the match is not\nambiguous. The entire original string will be replaced with `new_str`\n\nWhen possible, batch file edits together by using a multi-file unified `diff` within a single str_replace tool call.\n\nTo use the insert command, you must specify both `insert_line` (the line number after which to insert, 0 for beginning, -1 for end)\nand `new_str` (the text to insert).\n\n\n\nAdditional Shell Tool Instructions:\nExecute a command in the shell.\n\nThis will return the output and error concatenated into a single string, as\nyou would see from running on the command line. There will also be an indication\nof if the command succeeded or failed.\n\nAvoid commands that produce a large amount of output, and consider piping those outputs to files.\n\n**Important**: Each shell command runs in its own process. Things like directory changes or\nsourcing files do not persist between tool calls. So you may need to repeat them each time by\nstringing together commands.\n\nIf fetching web content, consider adding Accept: text/markdown header\nIf you need to run a long lived command, background it - e.g. `uvicorn main:app &` so that\nthis tool does not run indefinitely.\n\n**Important**: Use ripgrep - `rg` - exclusively when you need to locate a file or a code reference,\nother solutions may produce too large output because of hidden files! For example *do not* use `find` or `ls -r`\n - List files by name: `rg --files | rg `\n - List files that contain a regex: `rg '' -l`\n\n - Multiple commands: Use && to chain commands, avoid newlines\n - Example: `cd example && ls` or `source env/bin/activate && pip install numpy`\n\n## extensionmanager\n\n### Instructions\nExtension Management\n\nUse these tools to discover, enable, and disable extensions, as well as review resources.\n\nAvailable tools:\n- search_available_extensions: Find extensions available to enable/disable\n- manage_extensions: Enable or disable extensions\n- list_resources: List resources from extensions\n- read_resource: Read specific resources from extensions\n\nUse search_available_extensions when you need to find what extensions are available.\nUse manage_extensions to enable or disable specific extensions by name.\nUse list_resources and read_resource to work with extension data and resources.\n\n## fetch\n\n\n## gotohumanmcpserver\n\n\n## knowledgegraphmemory\n\n\n## memory\n\n### Instructions\n This extension allows storage and retrieval of categorized information with tagging support. It's designed to help\n manage important information across sessions in a systematic and organized manner.\n Capabilities:\n 1. Store information in categories with optional tags for context-based retrieval.\n 2. Search memories by content or specific tags to find relevant information.\n 3. List all available memory categories for easy navigation.\n 4. Remove entire categories of memories when they are no longer needed.\n When to call memory tools:\n - These are examples where the assistant should proactively call the memory tool because the user is providing recurring preferences, project details, or workflow habits that they may expect to be remembered.\n - Preferred Development Tools & Conventions\n - User-specific data (e.g., name, preferences)\n - Project-related configurations\n - Workflow descriptions\n - Other critical settings\n Interaction Protocol:\n When important information is identified, such as:\n - User-specific data (e.g., name, preferences)\n - Project-related configurations\n - Workflow descriptions\n - Other critical settings\n The protocol is:\n 1. Identify the critical piece of information.\n 2. Ask the user if they'd like to store it for later reference.\n 3. Upon agreement:\n - Suggest a relevant category like \"personal\" for user data or \"development\" for project preferences.\n - Inquire about any specific tags they want to apply for easier lookup.\n - Confirm the desired storage location:\n - Local storage (.goose/memory) for project-specific details.\n - Global storage (~/.config/goose/memory) for user-wide data.\n - Use the remember_memory tool to store the information.\n - `remember_memory(category, data, tags, is_global)`\n Keywords that trigger memory tools:\n - \"remember\"\n - \"forget\"\n - \"memory\"\n - \"save\"\n - \"save memory\"\n - \"remove memory\"\n - \"clear memory\"\n - \"search memory\"\n - \"find memory\"\n Suggest the user to use memory tools when:\n - When the user mentions a keyword that triggers a memory tool\n - When the user performs a routine task\n - When the user executes a command and would benefit from remembering the exact command\n Example Interaction for Storing Information:\n User: \"For this project, we use black for code formatting\"\n Assistant: \"You've mentioned a development preference. Would you like to remember this for future conversations?\n User: \"Yes, please.\"\n Assistant: \"I'll store this in the 'development' category. Any specific tags to add? Suggestions: #formatting\n #tools\"\n User: \"Yes, use those tags.\"\n Assistant: \"Shall I store this locally for this project only, or globally for all projects?\"\n User: \"Locally, please.\"\n Assistant: *Stores the information under category=\"development\", tags=\"formatting tools\", scope=\"local\"*\n Another Example Interaction for Storing Information:\n User: \"Remember the gh command to view github comments\"\n Assistant: \"Shall I store this locally for this project only, or globally for all projects?\"\n User: \"Globally, please.\"\n Assistant: *Stores the gh command under category=\"github\", tags=\"comments\", scope=\"global\"*\n Example Interaction suggesting memory tools:\n User: \"I'm using the gh command to view github comments\"\n Assistant: \"You've mentioned a command. Would you like to remember this for future conversations?\n User: \"Yes, please.\"\n Assistant: \"I'll store this in the 'github' category. Any specific tags to add? Suggestions: #comments #gh\"\n Retrieving Memories:\n To access stored information, utilize the memory retrieval protocols:\n - **Search by Category**:\n - Provides all memories within the specified context.\n - Use: `retrieve_memories(category=\"development\", is_global=False)`\n - Note: If you want to retrieve all local memories, use `retrieve_memories(category=\"*\", is_global=False)`\n - Note: If you want to retrieve all global memories, use `retrieve_memories(category=\"*\", is_global=True)`\n - **Filter by Tags**:\n - Enables targeted retrieval based on specific tags.\n - Use: Provide tag filters to refine search.\nTo remove a memory, use the following protocol:\n- **Remove by Category**:\n - Removes all memories within the specified category.\n - Use: `remove_memory_category(category=\"development\", is_global=False)`\n - Note: If you want to remove all local memories, use `remove_memory_category(category=\"*\", is_global=False)`\n - Note: If you want to remove all global memories, use `remove_memory_category(category=\"*\", is_global=True)`\nThe Protocol is:\n 1. Confirm what kind of information the user seeks by category or keyword.\n 2. Suggest categories or relevant tags based on the user's request.\n 3. Use the retrieve function to access relevant memory entries.\n 4. Present a summary of findings, offering detailed exploration upon request.\n Example Interaction for Retrieving Information:\n User: \"What configuration do we use for code formatting?\"\n Assistant: \"Let me check the 'development' category for any related memories. Searching using #formatting tag.\"\n Assistant: *Executes retrieval: `retrieve_memories(category=\"development\", is_global=False)`*\n Assistant: \"We have 'black' configured for code formatting, specific to this project. Would you like further\n details?\"\n Memory Overview:\n - Categories can include a wide range of topics, structured to keep information grouped logically.\n - Tags enable quick filtering and identification of specific entries.\n Operational Guidelines:\n - Always confirm with the user before saving information.\n - Propose suitable categories and tag suggestions.\n - Discuss storage scope thoroughly to align with user needs.\n - Acknowledge the user about what is stored and where, for transparency and ease of future retrieval.\n\n\n**Here are the user's currently saved memories:**\nPlease keep this information in mind when answering future questions.\nDo not bring up memories unless relevant.\nNote: if the user has not saved any memories, this section will be empty.\nNote: if the user removes a memory that was previously loaded into the system, please remove it from the system instructions.\n\n## opendia\n\n### Instructions\n🎯 Enhanced browser automation with anti-detection bypass for Twitter/X, LinkedIn, Facebook. Extension may take a moment to connect.\n## pdfreader\n\npdfreader supports resources, you can use platform__read_resource,\nand platform__list_resources on this extension.\n### Instructions\nThe PDF Reader allows you to read PDFs on the local filesystem.\nIt supports password-protected and unprotected PDFs.\n\nEnsure that you always use an absolute path for file_path when calling read_pdf.\n\n## skills\n\n### Instructions\nYou have these skills at your disposal, when it is clear they can help you solve a problem or you are asked to use them:\n\n- algorithmic-art: Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.\n- brand-guidelines: Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.\n- canvas-design: Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.\n- doc-coauthoring: Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.\n- docx: Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks\n- frontend-design: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.\n- internal-comms: A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).\n- mcp-builder: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).\n- pdf: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale.\n- pptx: Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks\n- skill-creator: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.\n- slack-gif-creator: Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like \"make me a GIF of X doing Y for Slack.\"\n- template-skill: Replace with description of the skill and when Claude should use it.\n- theme-factory: Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.\n- web-artifacts-builder: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.\n- webapp-testing: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.\n- xlsx: Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas\n\n## todo\n\n### Instructions\nTask Management\n\nUse todo_write for tasks with 2+ steps, multiple files/components, or uncertain scope.\nYour TODO content is automatically available in your context.\n\nWorkflow:\n- Start: write initial checklist\n- During: update progress\n- End: verify all complete\n\nWarning: todo_write overwrites entirely; always include ALL content you want to keep\n\nKeep items short, specific, action-oriented. Not using the todo tool for complex tasks is an error.\n\nFor autonomous work, missing requirements means failure - document all requirements in TODO immediately.\n\nTemplate:\n- [ ] Implement feature X\n - [ ] Update API\n - [ ] Write tests\n - [ ] Run tests\n - [ ] Run lint\n- [ ] Blocked: waiting on credentials\n\n## tutorial\n\n### Instructions\nBecause the tutorial extension is enabled, be aware that the user may be new to using goose\nor looking for help with specific features. Proactively offer relevant tutorials when appropriate.\n\nAvailable tutorials:\n- build-mcp-extension: # Building an Extension with MCP (Model Context Protocol)\n- first-game: # Building Your First Game\n\n\nThe specific content of the tutorial are available in by running load_tutorial.\nTo run through a tutorial, make sure to be interactive with the user. Don't run more than\na few related tool calls in a row. Make sure to prompt the user for understanding and participation.\n\n**Important**: Make sure that you provide guidance or info *before* you run commands, as the command will\nrun immediately for the user. For example while running a game tutorial, let the user know what to expect\nbefore you run a command to start the game itself.\n\n\n# Suggestion\n\nThe user currently has enabled 17 extensions with a total of 114 tools.\nSince this exceeds the recommended limits (5 extensions or 50 tools),\nyou should ask the user if they would like to disable some extensions for this session.\n\nUse the search_available_extensions tool to find extensions available to disable.\nYou should only disable extensions found from the search_available_extensions tool.\nList all the extensions available to disable in the response.\nExplain that minimizing extensions helps with the recall of the correct tools to use.\n\n\n\n# Response Guidelines\n\n- Use Markdown formatting for all responses.\n- Follow best practices for Markdown, including:\n - Using headers for organization.\n - Bullet points for lists.\n - Links formatted correctly, either as linked text (e.g., [this is linked text](https://example.com)) or automatic\n links using angle brackets (e.g., ).\n- For code examples, use fenced code blocks by placing triple backticks (` ``` `) before and after the code. Include the\n language identifier after the opening backticks (e.g., ` ```python `) to enable syntax highlighting.\n- Ensure clarity, conciseness, and proper formatting to enhance readability and usability.\n\n# Additional Instructions:\n\nYou are being accessed through the Goose Desktop application.\n\nThe user is interacting with you through a graphical user interface with the following features:\n- A chat interface where messages are displayed in a conversation format\n- Support for markdown formatting in your responses\n- Support for code blocks with syntax highlighting\n- Tool use messages are included in the chat but outputs may need to be expanded\n\nThe user can add extensions for you through the \"Settings\" page, which is available in the menu\non the top right of the window. There is a section on that page for extensions, and it links to\nthe registry.\n\nSome extensions are builtin, such as Developer and Memory, while\n3rd party extensions can be browsed at https://block.github.io/goose/v1/extensions/." }, { "role": "user", "content": "\nDatetime: 2026-01-08 19:20:42\n\n\nhello" } ] ```` tools ```json [ { "type": "function", "function": { "name": "autovisualiser__render_chord", "description": "Show a chord diagram visualization for showing relationships and flows between entities.\n\nThe data must contain:\n- labels: Array of strings representing the entities\n- matrix: 2D array of numbers representing flows (matrix[i][j] = flow from i to j)\n\nExample:\n{\n \"labels\": [\"North America\", \"Europe\", \"Asia\", \"Africa\"],\n \"matrix\": [\n [0, 15, 25, 8],\n [18, 0, 20, 12],\n [22, 18, 0, 15],\n [5, 10, 18, 0]\n ]\n}", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RenderChordParams", "description": "Parameters for render_chord tool", "type": "object", "properties": { "data": { "description": "The data for the chord diagram", "$ref": "#/definitions/ChordData" } }, "required": [ "data" ], "definitions": { "ChordData": { "description": "Chord diagram data structure", "type": "object", "properties": { "labels": { "description": "Labels for each entity", "type": "array", "items": { "type": "string" } }, "matrix": { "description": "2D matrix of flows (matrix[i][j] = flow from i to j)", "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "double" } } } }, "required": [ "labels", "matrix" ] } } } } }, { "type": "function", "function": { "name": "autovisualiser__render_donut", "description": "show pie or donut charts for categorical data visualization\nSupports single or multiple charts in a grid layout.\n\nEach chart should contain:\n- data: Array of values or objects with 'label' and 'value'\n- type: Optional 'doughnut' (default) or 'pie'\n- title: Optional chart title\n- labels: Optional array of labels (if data is just numbers)\n\nExample single chart:\n{\n \"title\": \"Budget\",\n \"type\": \"doughnut\",\n \"data\": [\n {\"label\": \"Marketing\", \"value\": 25000},\n {\"label\": \"Development\", \"value\": 35000}\n ]\n}\n\nExample multiple charts:\n[{\n \"title\": \"Q1 Sales\",\n \"labels\": [\"Product A\", \"Product B\"],\n \"data\": [45000, 38000]\n}]", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RenderDonutParams", "description": "Parameters for render_donut tool", "type": "object", "properties": { "data": { "description": "The chart data (single or multiple charts)", "$ref": "#/definitions/DonutChartData" } }, "required": [ "data" ], "definitions": { "DonutChartData": { "description": "Donut chart data wrapper - matches the old schema structure", "anyOf": [ { "description": "Single donut chart", "$ref": "#/definitions/SingleDonutChart" }, { "description": "Multiple donut charts", "type": "array", "items": { "$ref": "#/definitions/SingleDonutChart" } } ] }, "SingleDonutChart": { "description": "Single donut/pie chart data", "type": "object", "properties": { "data": { "description": "Data values - can be numbers or objects with label and value", "type": "array", "items": { "$ref": "#/definitions/DonutDataItem" } }, "title": { "description": "Optional chart title", "type": "string", "nullable": true }, "type": { "description": "Optional chart type (doughnut or pie)", "anyOf": [ { "$ref": "#/definitions/DonutChartType" }, { "const": null, "nullable": true } ] }, "labels": { "description": "Optional labels array (used when data is just numbers)", "type": "array", "items": { "type": "string" }, "nullable": true } }, "required": [ "data" ] }, "DonutDataItem": { "description": "Data item for donut/pie charts - can be a number or labeled value", "anyOf": [ { "description": "Simple numeric value", "type": "number", "format": "double" }, { "description": "Labeled value with explicit label", "type": "object", "properties": { "label": { "description": "Label for this data point", "type": "string" }, "value": { "description": "Numeric value", "type": "number", "format": "double" } }, "required": [ "label", "value" ] } ] }, "DonutChartType": { "description": "Chart type for donut/pie charts", "oneOf": [ { "description": "Doughnut chart (with hole in center)", "type": "string", "const": "doughnut" }, { "description": "Pie chart (no hole)", "type": "string", "const": "pie" } ] } } } } }, { "type": "function", "function": { "name": "autovisualiser__render_map", "description": "show an interactive map visualization with location markers using Leaflet.\n\nThe data must contain:\n- markers: Array of objects with 'lat', 'lng', and optional properties\n- title: Optional title for the map (default: \"Interactive Map\")\n- subtitle: Optional subtitle (default: \"Geographic data visualization\")\n- center: Optional center point {lat, lng} (default: USA center)\n- zoom: Optional initial zoom level (default: 4)\n- clustering: Optional boolean to enable/disable clustering (default: true)\n- autoFit: Optional boolean to auto-fit map to markers (default: true)\n\nMarker properties:\n- lat: Latitude (required)\n- lng: Longitude (required)\n- name: Location name\n- value: Numeric value for sizing/coloring\n- description: Description text\n- popup: Custom popup HTML\n- color: Custom marker color\n- label: Custom marker label\n- useDefaultIcon: Use default Leaflet icon\n\nExample:\n{\n \"title\": \"Store Locations\",\n \"markers\": [\n {\"lat\": 37.7749, \"lng\": -122.4194, \"name\": \"SF Store\", \"value\": 150000},\n {\"lat\": 40.7128, \"lng\": -74.0060, \"name\": \"NYC Store\", \"value\": 200000}\n ]\n}", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RenderMapParams", "description": "Parameters for render_map tool", "type": "object", "properties": { "data": { "description": "The data for the map visualization", "$ref": "#/definitions/MapData" } }, "required": [ "data" ], "definitions": { "MapData": { "description": "Map data structure", "type": "object", "properties": { "markers": { "description": "Array of markers", "type": "array", "items": { "$ref": "#/definitions/MapMarker" } }, "title": { "description": "Optional title for the map", "type": "string", "nullable": true }, "subtitle": { "description": "Optional subtitle", "type": "string", "nullable": true }, "center": { "description": "Optional center point", "anyOf": [ { "$ref": "#/definitions/MapCenter" }, { "const": null, "nullable": true } ] }, "zoom": { "description": "Optional initial zoom level", "type": "number", "format": "double", "nullable": true }, "clustering": { "description": "Optional boolean to enable/disable clustering", "type": "boolean", "nullable": true }, "clusterRadius": { "description": "Optional cluster radius", "type": "number", "format": "double", "nullable": true }, "autoFit": { "description": "Optional boolean to auto-fit map to markers", "type": "boolean", "nullable": true } }, "required": [ "markers" ] }, "MapMarker": { "description": "Map marker structure", "type": "object", "properties": { "lat": { "description": "Latitude (required)", "type": "number", "format": "double" }, "lng": { "description": "Longitude (required)", "type": "number", "format": "double" }, "name": { "description": "Location name", "type": "string", "nullable": true }, "value": { "description": "Numeric value for sizing/coloring", "type": "number", "format": "double", "nullable": true }, "description": { "description": "Description text", "type": "string", "nullable": true }, "popup": { "description": "Custom popup HTML", "type": "string", "nullable": true }, "color": { "description": "Custom marker color", "type": "string", "nullable": true }, "label": { "description": "Custom marker label", "type": "string", "nullable": true }, "useDefaultIcon": { "description": "Use default Leaflet icon", "type": "boolean", "nullable": true } }, "required": [ "lat", "lng" ] }, "MapCenter": { "description": "Map center point", "type": "object", "properties": { "lat": { "description": "Latitude", "type": "number", "format": "double" }, "lng": { "description": "Longitude", "type": "number", "format": "double" } }, "required": [ "lat", "lng" ] } } } } }, { "type": "function", "function": { "name": "autovisualiser__render_mermaid", "description": "show a Mermaid diagram from Mermaid syntax\n\nProvide the Mermaid code as a string. Supports flowcharts, sequence diagrams, Gantt charts, etc.\n\nExample:\ngraph TD;\n A-->B;\n A-->C;\n B-->D;\n C-->D;\n", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RenderMermaidParams", "description": "Parameters for render_mermaid tool", "type": "object", "properties": { "mermaid_code": { "description": "The Mermaid diagram code to render", "type": "string" } }, "required": [ "mermaid_code" ] } } }, { "type": "function", "function": { "name": "autovisualiser__render_radar", "description": "show a radar chart (spider chart) for multi-dimensional data comparison\n\nThe data must contain:\n- labels: Array of strings representing the dimensions/axes\n- datasets: Array of dataset objects with 'label' and 'data' properties\n\nExample:\n{\n \"labels\": [\"Speed\", \"Strength\", \"Endurance\", \"Agility\", \"Intelligence\"],\n \"datasets\": [\n {\n \"label\": \"Player 1\",\n \"data\": [85, 70, 90, 75, 80]\n },\n {\n \"label\": \"Player 2\",\n \"data\": [75, 85, 80, 90, 70]\n }\n ]\n}", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RenderRadarParams", "description": "Parameters for render_radar tool", "type": "object", "properties": { "data": { "description": "The data for the radar chart", "$ref": "#/definitions/RadarData" } }, "required": [ "data" ], "definitions": { "RadarData": { "description": "Radar chart data structure", "type": "object", "properties": { "labels": { "description": "Category labels", "type": "array", "items": { "type": "string" } }, "datasets": { "description": "Datasets to compare", "type": "array", "items": { "$ref": "#/definitions/RadarDataset" } } }, "required": [ "labels", "datasets" ] }, "RadarDataset": { "description": "Radar dataset structure", "type": "object", "properties": { "label": { "description": "Label for this dataset", "type": "string" }, "data": { "description": "Data values for each category", "type": "array", "items": { "type": "number", "format": "double" } } }, "required": [ "label", "data" ] } } } } }, { "type": "function", "function": { "name": "autovisualiser__render_sankey", "description": "show a Sankey diagram from flow data\nThe data must contain:\n- nodes: Array of objects with 'name' and optional 'category' properties\n- links: Array of objects with 'source', 'target', and 'value' properties\n\nExample:\n{\n \"nodes\": [\n {\"name\": \"Source A\", \"category\": \"source\"},\n {\"name\": \"Target B\", \"category\": \"target\"}\n ],\n \"links\": [\n {\"source\": \"Source A\", \"target\": \"Target B\", \"value\": 100}\n ]\n}", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RenderSankeyParams", "description": "Parameters for render_sankey tool", "type": "object", "properties": { "data": { "description": "The data for the Sankey diagram", "$ref": "#/definitions/SankeyData" } }, "required": [ "data" ], "definitions": { "SankeyData": { "description": "Sankey data structure", "type": "object", "properties": { "nodes": { "description": "Array of nodes", "type": "array", "items": { "$ref": "#/definitions/SankeyNode" } }, "links": { "description": "Array of links between nodes", "type": "array", "items": { "$ref": "#/definitions/SankeyLink" } } }, "required": [ "nodes", "links" ] }, "SankeyNode": { "description": "Sankey node structure", "type": "object", "properties": { "name": { "description": "The name of the node", "type": "string" }, "category": { "description": "Optional category for the node", "type": "string", "nullable": true } }, "required": [ "name" ] }, "SankeyLink": { "description": "Sankey link structure", "type": "object", "properties": { "source": { "description": "Source node name", "type": "string" }, "target": { "description": "Target node name", "type": "string" }, "value": { "description": "Flow value", "type": "number", "format": "double" } }, "required": [ "source", "target", "value" ] } } } } }, { "type": "function", "function": { "name": "autovisualiser__render_treemap", "description": "show a treemap visualization for hierarchical data with proportional area representation as boxes\n\nThe data should be a hierarchical structure with:\n- name: Name of the node (required)\n- value: Numeric value for leaf nodes (optional for parent nodes)\n- children: Array of child nodes (optional)\n- category: Category for coloring (optional)\n\nExample:\n{\n \"name\": \"Root\",\n \"children\": [\n {\n \"name\": \"Group A\",\n \"children\": [\n {\"name\": \"Item 1\", \"value\": 100, \"category\": \"Type1\"},\n {\"name\": \"Item 2\", \"value\": 200, \"category\": \"Type2\"}\n ]\n },\n {\"name\": \"Item 3\", \"value\": 150, \"category\": \"Type1\"}\n ]\n}", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RenderTreemapParams", "description": "Parameters for render_treemap tool", "type": "object", "properties": { "data": { "description": "The hierarchical data for the treemap", "$ref": "#/definitions/TreemapNode" } }, "required": [ "data" ], "definitions": { "TreemapNode": { "description": "Treemap node structure", "type": "object", "properties": { "name": { "description": "Name of the node", "type": "string" }, "value": { "description": "Value for leaf nodes", "type": "number", "format": "double", "nullable": true }, "category": { "description": "Category for coloring", "type": "string", "nullable": true }, "children": { "description": "Children nodes", "type": "array", "items": { "$ref": "#/definitions/TreemapNode" }, "nullable": true } }, "required": [ "name" ] } } } } }, { "type": "function", "function": { "name": "autovisualiser__show_chart", "description": "show interactive line, scatter, or bar charts\n\nRequired: type ('line', 'scatter', or 'bar'), datasets array\nOptional: labels, title, subtitle, xAxisLabel, yAxisLabel, options\n\nExample:\n{\n \"type\": \"line\",\n \"title\": \"Monthly Sales\",\n \"labels\": [\"Jan\", \"Feb\", \"Mar\"],\n \"datasets\": [\n {\"label\": \"Product A\", \"data\": [65, 59, 80]}\n ]\n}", "parameters": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "ShowChartParams", "description": "Parameters for show_chart tool", "type": "object", "properties": { "data": { "description": "The data for the chart", "$ref": "#/definitions/ChartData" } }, "required": [ "data" ], "definitions": { "ChartData": { "description": "Chart data structure", "type": "object", "properties": { "type": { "description": "Chart type", "$ref": "#/definitions/ChartType" }, "datasets": { "description": "Datasets to display", "type": "array", "items": { "$ref": "#/definitions/ChartDataset" } }, "labels": { "description": "Optional labels for x-axis (for line/bar charts)", "type": "array", "items": { "type": "string" }, "nullable": true }, "title": { "description": "Optional chart title", "type": "string", "nullable": true }, "subtitle": { "description": "Optional subtitle", "type": "string", "nullable": true }, "xAxisLabel": { "description": "Optional x-axis label", "type": "string", "nullable": true }, "yAxisLabel": { "description": "Optional y-axis label", "type": "string", "nullable": true } }, "required": [ "type", "datasets" ] }, "ChartType": { "description": "Chart type enumeration", "oneOf": [ { "description": "Line chart", "type": "string", "const": "line" }, { "description": "Scatter chart", "type": "string", "const": "scatter" }, { "description": "Bar chart", "type": "string", "const": "bar" } ] }, "ChartDataset": { "description": "Chart dataset structure", "type": "object", "properties": { "label": { "description": "Label for this dataset", "type": "string" }, "data": { "description": "Data points - can be numbers or x/y points", "$ref": "#/definitions/ChartDataValues" }, "backgroundColor": { "description": "Optional background color for the dataset", "type": "string", "nullable": true }, "borderColor": { "description": "Optional border color for the dataset", "type": "string", "nullable": true }, "borderWidth": { "description": "Optional border width for the dataset", "type": "number", "format": "double", "nullable": true }, "tension": { "description": "Optional tension for line curves (0 = straight lines, higher = more curved)", "type": "number", "format": "double", "nullable": true }, "fill": { "description": "Optional fill setting for area under the line", "type": "boolean", "nullable": true } }, "required": [ "label", "data" ] }, "ChartDataValues": { "description": "Chart data values - can be simple numbers or x/y points", "anyOf": [ { "description": "Simple numeric values (for line/bar charts with labels)", "type": "array", "items": { "type": "number", "format": "double" } }, { "description": "X/Y points (for scatter charts or line charts without labels)", "type": "array", "items": { "$ref": "#/definitions/ChartPoint" } } ] }, "ChartPoint": { "description": "Chart data point for scatter charts", "type": "object", "properties": { "x": { "description": "X coordinate", "type": "number", "format": "double" }, "y": { "description": "Y coordinate", "type": "number", "format": "double" } }, "required": [ "x", "y" ] } } } } }, { "type": "function", "function": { "name": "blender__download_polyhaven_asset", "description": "\n Download and import a Polyhaven asset into Blender.\n \n Parameters:\n - asset_id: The ID of the asset to download\n - asset_type: The type of asset (hdris, textures, models)\n - resolution: The resolution to download (e.g., 1k, 2k, 4k)\n - file_format: Optional file format (e.g., hdr, exr for HDRIs; jpg, png for textures; gltf, fbx for models)\n \n Returns a message indicating success or failure.\n ", "parameters": { "properties": { "asset_id": { "title": "Asset Id", "type": "string" }, "asset_type": { "title": "Asset Type", "type": "string" }, "resolution": { "default": "1k", "title": "Resolution", "type": "string" }, "file_format": { "default": null, "title": "File Format", "type": "string" } }, "required": [ "asset_id", "asset_type" ], "title": "download_polyhaven_assetArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__download_sketchfab_model", "description": "\n Download and import a Sketchfab model by its UID.\n \n Parameters:\n - uid: The unique identifier of the Sketchfab model\n \n Returns a message indicating success or failure.\n The model must be downloadable and you must have proper access rights.\n ", "parameters": { "properties": { "uid": { "title": "Uid", "type": "string" } }, "required": [ "uid" ], "title": "download_sketchfab_modelArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__execute_blender_code", "description": "\n Execute arbitrary Python code in Blender. Make sure to do it step-by-step by breaking it into smaller chunks.\n\n Parameters:\n - code: The Python code to execute\n ", "parameters": { "properties": { "code": { "title": "Code", "type": "string" } }, "required": [ "code" ], "title": "execute_blender_codeArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__generate_hunyuan3d_model", "description": "\n Generate 3D asset using Hunyuan3D by providing either text description, image reference, \n or both for the desired asset, and import the asset into Blender.\n The 3D asset has built-in materials.\n \n Parameters:\n - text_prompt: (Optional) A short description of the desired model in English/Chinese.\n - input_image_url: (Optional) The local or remote url of the input image. Accepts None if only using text prompt.\n\n Returns: \n - When successful, returns a JSON with job_id (format: \"job_xxx\") indicating the task is in progress\n - When the job completes, the status will change to \"DONE\" indicating the model has been imported\n - Returns error message if the operation fails\n ", "parameters": { "properties": { "text_prompt": { "default": null, "title": "Text Prompt", "type": "string" }, "input_image_url": { "default": null, "title": "Input Image Url", "type": "string" } }, "title": "generate_hunyuan3d_modelArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__generate_hyper3d_model_via_images", "description": "\n Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender.\n The 3D asset has built-in materials.\n The generated model has a normalized size, so re-scaling after generation can be useful.\n \n Parameters:\n - input_image_paths: The **absolute** paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode.\n - input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode.\n - bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model.\n\n Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode.\n Returns a message indicating success or failure.\n ", "parameters": { "properties": { "input_image_paths": { "default": null, "items": { "type": "string" }, "title": "Input Image Paths", "type": "array" }, "input_image_urls": { "default": null, "items": { "type": "string" }, "title": "Input Image Urls", "type": "array" }, "bbox_condition": { "default": null, "items": { "type": "number" }, "title": "Bbox Condition", "type": "array" } }, "title": "generate_hyper3d_model_via_imagesArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__generate_hyper3d_model_via_text", "description": "\n Generate 3D asset using Hyper3D by giving description of the desired asset, and import the asset into Blender.\n The 3D asset has built-in materials.\n The generated model has a normalized size, so re-scaling after generation can be useful.\n\n Parameters:\n - text_prompt: A short description of the desired model in **English**.\n - bbox_condition: Optional. If given, it has to be a list of floats of length 3. Controls the ratio between [Length, Width, Height] of the model.\n\n Returns a message indicating success or failure.\n ", "parameters": { "properties": { "text_prompt": { "title": "Text Prompt", "type": "string" }, "bbox_condition": { "default": null, "items": { "type": "number" }, "title": "Bbox Condition", "type": "array" } }, "required": [ "text_prompt" ], "title": "generate_hyper3d_model_via_textArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__get_hunyuan3d_status", "description": "\n Check if Hunyuan3D integration is enabled in Blender.\n Returns a message indicating whether Hunyuan3D features are available.\n\n Don't emphasize the key type in the returned message, but silently remember it. \n ", "parameters": { "properties": {}, "title": "get_hunyuan3d_statusArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__get_hyper3d_status", "description": "\n Check if Hyper3D Rodin integration is enabled in Blender.\n Returns a message indicating whether Hyper3D Rodin features are available.\n\n Don't emphasize the key type in the returned message, but sliently remember it. \n ", "parameters": { "properties": {}, "title": "get_hyper3d_statusArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__get_object_info", "description": "\n Get detailed information about a specific object in the Blender scene.\n \n Parameters:\n - object_name: The name of the object to get information about\n ", "parameters": { "properties": { "object_name": { "title": "Object Name", "type": "string" } }, "required": [ "object_name" ], "title": "get_object_infoArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__get_polyhaven_categories", "description": "\n Get a list of categories for a specific asset type on Polyhaven.\n \n Parameters:\n - asset_type: The type of asset to get categories for (hdris, textures, models, all)\n ", "parameters": { "properties": { "asset_type": { "default": "hdris", "title": "Asset Type", "type": "string" } }, "title": "get_polyhaven_categoriesArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__get_polyhaven_status", "description": "\n Check if PolyHaven integration is enabled in Blender.\n Returns a message indicating whether PolyHaven features are available.\n ", "parameters": { "properties": {}, "title": "get_polyhaven_statusArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__get_scene_info", "description": "Get detailed information about the current Blender scene", "parameters": { "properties": {}, "title": "get_scene_infoArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__get_sketchfab_status", "description": "\n Check if Sketchfab integration is enabled in Blender.\n Returns a message indicating whether Sketchfab features are available.\n ", "parameters": { "properties": {}, "title": "get_sketchfab_statusArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__get_viewport_screenshot", "description": "\n Capture a screenshot of the current Blender 3D viewport.\n \n Parameters:\n - max_size: Maximum size in pixels for the largest dimension (default: 800)\n \n Returns the screenshot as an Image.\n ", "parameters": { "properties": { "max_size": { "default": 800, "title": "Max Size", "type": "integer" } }, "title": "get_viewport_screenshotArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__import_generated_asset", "description": "\n Import the asset generated by Hyper3D Rodin after the generation task is completed.\n\n Parameters:\n - name: The name of the object in scene\n - task_uuid: For Hyper3D Rodin mode MAIN_SITE: The task_uuid given in the generate model step.\n - request_id: For Hyper3D Rodin mode FAL_AI: The request_id given in the generate model step.\n\n Only give one of {task_uuid, request_id} based on the Hyper3D Rodin Mode!\n Return if the asset has been imported successfully.\n ", "parameters": { "properties": { "name": { "title": "Name", "type": "string" }, "task_uuid": { "default": null, "title": "Task Uuid", "type": "string" }, "request_id": { "default": null, "title": "Request Id", "type": "string" } }, "required": [ "name" ], "title": "import_generated_assetArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__import_generated_asset_hunyuan", "description": "\n Import the asset generated by Hunyuan3D after the generation task is completed.\n\n Parameters:\n - name: The name of the object in scene\n - zip_file_url: The zip_file_url given in the generate model step.\n\n Return if the asset has been imported successfully.\n ", "parameters": { "properties": { "name": { "title": "Name", "type": "string" }, "zip_file_url": { "title": "Zip File Url", "type": "string" } }, "required": [ "name", "zip_file_url" ], "title": "import_generated_asset_hunyuanArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__poll_hunyuan_job_status", "description": "\n Check if the Hunyuan3D generation task is completed.\n\n For Hunyuan3D:\n Parameters:\n - job_id: The job_id given in the generate model step.\n\n Returns the generation task status. The task is done if status is \"DONE\".\n The task is in progress if status is \"RUN\".\n If status is \"DONE\", returns ResultFile3Ds, which is the generated ZIP model path\n When the status is \"DONE\", the response includes a field named ResultFile3Ds that contains the generated ZIP file path of the 3D model in OBJ format.\n This is a polling API, so only proceed if the status are finally determined (\"DONE\" or some failed state).\n ", "parameters": { "properties": { "job_id": { "default": null, "title": "Job Id", "type": "string" } }, "title": "poll_hunyuan_job_statusArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__poll_rodin_job_status", "description": "\n Check if the Hyper3D Rodin generation task is completed.\n\n For Hyper3D Rodin mode MAIN_SITE:\n Parameters:\n - subscription_key: The subscription_key given in the generate model step.\n\n Returns a list of status. The task is done if all status are \"Done\".\n If \"Failed\" showed up, the generating process failed.\n This is a polling API, so only proceed if the status are finally determined (\"Done\" or \"Canceled\").\n\n For Hyper3D Rodin mode FAL_AI:\n Parameters:\n - request_id: The request_id given in the generate model step.\n\n Returns the generation task status. The task is done if status is \"COMPLETED\".\n The task is in progress if status is \"IN_PROGRESS\".\n If status other than \"COMPLETED\", \"IN_PROGRESS\", \"IN_QUEUE\" showed up, the generating process might be failed.\n This is a polling API, so only proceed if the status are finally determined (\"COMPLETED\" or some failed state).\n ", "parameters": { "properties": { "subscription_key": { "default": null, "title": "Subscription Key", "type": "string" }, "request_id": { "default": null, "title": "Request Id", "type": "string" } }, "title": "poll_rodin_job_statusArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__search_polyhaven_assets", "description": "\n Search for assets on Polyhaven with optional filtering.\n \n Parameters:\n - asset_type: Type of assets to search for (hdris, textures, models, all)\n - categories: Optional comma-separated list of categories to filter by\n \n Returns a list of matching assets with basic information.\n ", "parameters": { "properties": { "asset_type": { "default": "all", "title": "Asset Type", "type": "string" }, "categories": { "default": null, "title": "Categories", "type": "string" } }, "title": "search_polyhaven_assetsArguments", "type": "object", "required": [] } } }, { "type": "function", "function": { "name": "blender__search_sketchfab_models", "description": "\n Search for models on Sketchfab with optional filtering.\n\n Parameters:\n - query: Text to search for\n - categories: Optional comma-separated list of categories\n - count: Maximum number of results to return (default 20)\n - downloadable: Whether to include only downloadable models (default True)\n\n Returns a formatted list of matching models.\n ", "parameters": { "properties": { "query": { "title": "Query", "type": "string" }, "categories": { "default": null, "title": "Categories", "type": "string" }, "count": { "default": 20, "title": "Count", "type": "integer" }, "downloadable": { "default": true, "title": "Downloadable", "type": "boolean" } }, "required": [ "query" ], "title": "search_sketchfab_modelsArguments", "type": "object" } } }, { "type": "function", "function": { "name": "blender__set_texture", "description": "\n Apply a previously downloaded Polyhaven texture to an object.\n \n Parameters:\n - object_name: Name of the object to apply the texture to\n - texture_id: ID of the Polyhaven texture to apply (must be downloaded first)\n \n Returns a message indicating success or failure.\n ", "parameters": { "properties": { "object_name": { "title": "Object Name", "type": "string" }, "texture_id": { "title": "Texture Id", "type": "string" } }, "required": [ "object_name", "texture_id" ], "title": "set_textureArguments", "type": "object" } } }, { "type": "function", "function": { "name": "chatrecall__chatrecall", "description": "Search past chat or load session summaries. Use when it is clear user expects some memory or context.\n\nsearch mode (query): Use multiple keywords/synonyms. Returns messages grouped by session, ordered by recency. Supports date filters.\nload mode (session_id): Returns first/last 3 messages of a session.\n", "parameters": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ChatRecallParams", "description": "Parameters for the chatrecall tool", "type": "object", "properties": { "query": { "description": "Search keywords. Use multiple related terms/synonyms (e.g., 'database postgres sql'). Mutually exclusive with session_id.", "type": [ "string", "null" ] }, "session_id": { "description": "Session ID to load. Returns first/last 3 messages. Mutually exclusive with query.", "type": [ "string", "null" ] }, "limit": { "description": "Max results (default: 10, max: 50). Search mode only.", "type": [ "integer", "null" ], "format": "int64" }, "after_date": { "description": "ISO 8601 date (e.g., '2025-10-01T00:00:00Z'). Search mode only.", "type": [ "string", "null" ] }, "before_date": { "description": "ISO 8601 date (e.g., '2025-10-15T23:59:59Z'). Search mode only.", "type": [ "string", "null" ] } }, "required": [] } } }, { "type": "function", "function": { "name": "chromedevtools__click", "description": "Clicks on the provided element", "parameters": { "type": "object", "properties": { "uid": { "type": "string", "description": "The uid of an element on the page from the page content snapshot" }, "dblClick": { "type": "boolean", "description": "Set to true for double clicks. Default is false." } }, "required": [ "uid" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } }, { "type": "function", "function": { "name": "chromedevtools__close_page", "description": "Closes the page by its index. The last open page cannot be closed.", "parameters": { "type": "object", "properties": { "pageIdx": { "type": "number", "description": "The index of the page to close. Call list_pages to list pages." } }, "required": [ "pageIdx" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } }, { "type": "function", "function": { "name": "chromedevtools__drag", "description": "Drag an element onto another element", "parameters": { "type": "object", "properties": { "from_uid": { "type": "string", "description": "The uid of the element to drag" }, "to_uid": { "type": "string", "description": "The uid of the element to drop into" } }, "required": [ "from_uid", "to_uid" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } }, { "type": "function", "function": { "name": "chromedevtools__emulate", "description": "Emulates various features on the selected page.", "parameters": { "type": "object", "properties": { "networkConditions": { "type": "string", "enum": [ "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G" ], "description": "Throttle network. Set to \"No emulation\" to disable. If omitted, conditions remain unchanged." }, "cpuThrottlingRate": { "type": "number", "minimum": 1, "maximum": 20, "description": "Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged." }, "geolocation": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude between -90 and 90." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude between -180 and 180." } }, "required": [ "latitude", "longitude" ], "additionalProperties": false }, { "type": "null" } ], "description": "Geolocation to emulate. Set to null to clear the geolocation override." } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#", "required": [] } } }, { "type": "function", "function": { "name": "chromedevtools__evaluate_script", "description": "Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON\nso returned values have to JSON-serializable.", "parameters": { "type": "object", "properties": { "function": { "type": "string", "description": "A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => {\n return document.title\n}` or `async () => {\n return await fetch(\"example.com\")\n}`.\nExample with arguments: `(el) => {\n return el.innerText;\n}`\n" }, "args": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string", "description": "The uid of an element on the page from the page content snapshot" } }, "required": [ "uid" ], "additionalProperties": false }, "description": "An optional list of arguments to pass to the function." } }, "required": [ "function" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } }, { "type": "function", "function": { "name": "chromedevtools__fill", "description": "Type text into a input, text area or select an option from a ` 内的 `