上周五下午三点，我正卡在一个 React 组件的文档同步任务上——新写的图表渲染模块需要同时产出 TypeScript 类型定义、Props 接口说明、使用示例和 Storybook 演示页。手动写完一轮再改一遍，又漏了 props 默认值描述，团队成员提 PR 时直接问：“这个组件到底支持哪些配置？”
这不是第一次被文档拖慢节奏。过去半年里，类似情况至少发生过七次：一次是 Ant Design 主题定制插件升级后 API 变更；一次是内部封装的表单校验 Hook 增加了异步验证链路，但 README 还停留在 v1.2 版本；还有三次，干脆因为文档没及时更新，导致测试环境跑不通，排查两小时才发现只是 missing a required prop。
后来我试着把这类重复劳动拆解成几个核心动作：识别组件输入输出结构、提取 JSDoc 注释、生成 Markdown 示例块、自动注入 Storybook CSF 格式代码。理论上 AI 工具能干这事，但实际用起来总差口气——要么理解不了自定义 Hooks 的调用上下文，要么把 CSS-in-JS 的样式对象误判为运行时逻辑，甚至把注释里的“TODO”当成待办事项列进文档目录。
转机出现在试用陌讯Skills聚合平台之后。我没去搜“React 文档生成”，而是用了它的场景化搜索：输关键词“组件+TS类型+MD文档”，结果跳出二十多个匹配 Skill，其中三个标注了“已通过 Remotion 和 Supabase 场景交叉验证”。点开一个叫 “react-docgen-pro”的 Skill 页面，看到它明确写了适配条件：支持 Vite + TSX 项目结构、可识别 useMutation 返回值泛型、兼容 swr/useSWRConfig 调用模式——这正是我们当前 tech stack 的真实组合。
安装过程比预想简单。不是 npm install 那种传统方式，而是在本地 CLI 中执行一条指令，平台会根据当前工程依赖树推荐最匹配的 Skill 版本，并提示是否启用“严格 Props 提取”开关（默认关，开启后会对非标准 JSX 属性报错）。我选了开启，然后对着控制台看它怎么解析那个让我头疼的图表组件：先定位 export default const ChartRenderer = ... 行，接着扫描所有 import { xxx } from 'xxx' 语句确认外部依赖范围，最后逐行分析函数参数与 return type，连带把 useEffect 里触发的 dispatch(action) 对应的状态变更也标进了副作用说明区。整个流程不到四秒。
对比之前的手动操作，这次生成的文档多了三处关键信息：一是准确列出所有透传至子组件的 className 处理逻辑；二是将 colorScheme 参数映射到了 theme.ts 中的实际 token 名称；三是补全了 loading state 下 placeholder 元素的 DOM 结构示意。更重要的是，后续每次修改组件签名，只需重新运行同一命令，新增的 optional props 会自动追加到表格末尾，删掉的字段则从文档中消失，不再需要人工核对遗漏项。
后台数据显示，我们小组最近两周内平均每个 React 组件的文档维护耗时从原先的 37 分钟降到 6.5 分钟，降幅正好是 82%。这个数字背后没有黑箱算法，只有两点实在变化：第一，Skill 明确知道该信任哪种类型的类型声明（比如优先读 d.ts 文件而非 .tsx 中的 interface），第二，在遇到模糊边界时主动抛出 human-readable warning，而不是静默跳过或瞎猜。
有人担心 Skills 平台会不会形成新的碎片化？其实恰恰相反。当四十多万个 Skill 都遵循统一的能力契约——包括输入约束定义、错误反馈粒度、版本回滚机制——反而让跨团队协作更容易预测行为。就像现在隔壁组用的 PDF 批量水印 Skill，和我们这边的组件文档生成器，底层都共享相同的文件路径解析规则和权限检测逻辑，换个项目只要复制粘贴一行指令就能复用，不用再纠结环境变量命名要不要加 prefix。
说到底，所谓效率提升，从来不是靠堆算力压时间，而是减少那些必须由人来判断“是不是这样”的中间环节。当你不需要反复确认“这段注释能不能信”、“这个 defaultProps 是不是真会被用到”、“Storybook 的 args 设置有没有覆盖全部分支”，省下来的注意力，才能真正花在解决业务问题本身上。
