文档即系统：探索人机协作的“智能语言”新范式

彭岳林
54 阅读5分钟

文档即系统：探索人机协作的“智能语言”新范式

前言

从机器码到汇编，再到面向对象的高级语言，计算机语言的发展史就是一部“提升人类友好度”的历史。随着 AI Agent（如 OpenCode）的成熟，我们正站在一个新的转折点：是否需要设计一门同时面向人和 AI 的语言？

它应比高级语言更接近自然语言，同时具备易操作性且AI能准确理解。本文以“配置平台”的迭代为例，探索如何通过 PlantUML + Markdown 构建一种“智能语言”，实现开发即设计、文档即系统。

核心目标

  • 极致交付：通过清晰定义意图，极大地加速系统开发与重构速度。
  • 同步演进：开发文档 = 系统实现；维护文档 = 系统更新。

效能复盘

阶段投入时间核心工作内容
设计阶段约 2 天定义核心模型、上下文映射、接口契约（最关键环节）
实现阶段约 1 天AI 根据文档自动生成代码，工程师进行微调与验证

核心逻辑：当意图被清晰定义，AI 负责“搬砖”。工程师的角色转变为“意图审核员”——通过观察 AI 的输出，反向修正文档中的表达缺失或逻辑错误。

技术栈与工具

  • AI 编程智能体：OpenCode (具备项目全局上下文理解、自主决策与任务执行能力)
  • 底层模型：Gemini 3 Flash / Pro
  • 智能语言载体：PlantUML (模型/架构) + Markdown (逻辑/约束)

注： 其他模型也可以实现类似效果

实践：配置平台（Config Platform）设计规范

项目背景：构建一个类型安全、集中式、低时延的配置管理平台。

1. 上下文映射（Context Mapping）

通过 PlantUML 明确系统边界：

  • Manager Page: 配置管理后台，负责增删改查。
  • Config Platform Runtime: 核心运行环境，包含 gRPC API、SPI 校验逻辑。
  • Config Sync Queue: 基于 Kafka 的实时配置分发中心。
  • Config Getter SDK: 嵌入业务系统的客户端，支持混合推拉架构。

2. 核心领域模型（Core Domain）

  • Config Aggregate: 聚合根，封装了租户、命名空间、版本及自验证逻辑。
  • ConfigMeta & Checker: 声明式校验逻辑（Regex、RPC、Boolean），实现“配置即策略”。

3. 存储模型（E-R）

物理架构采用版本化设计，config 表记录当前状态，config_history 追踪演进过程，确保每一次变更都可追溯、可回滚。

SDK 设计：混合推拉架构

为了保证配置获取的高可用与强一致性，SDK 采用“推拉结合”的策略：

A. 实时推送 (Push Mode)
  • 监听 Kafka Topic。
  • 版本防御：仅当 Incoming Version > Local Version 时触发更新，防止数据回退。
B. 智能轮询 (Smart Pull Mode)
  • 抖动算法 (Jitter) ：增加 +/- 10% 的随机延迟，避免大集群“惊群效应”。
  • 轻量化检查：先通过 GetVersionNo 检查高水位线，仅在有变更时才拉取具体键值。
C. 自愈与降级 (Self-Healing)
  • 逻辑校验：SDK 在注入配置前运行本地 Validator。
  • 自动回滚：若新配置校验失败，SDK 自动请求 getPreviousVersion 并标记为 FALLBACK 状态，确保业务不因错误配置中断。

AI 协作流水线

graph LR
    A[编写设计文档] --> B[AI实现<br/>包含自动化测试集]
    A --> C[重构<br/>AI]
    B --> D[Review]
    C --> D
    
    D -- 自动同步 AI --> A
    
    D --> E{结束}
    
    subgraph 结束条件
    E --- F[1. 自动化测试集完善<br/>2. 自动化测试全部通过<br/>3. 代码完全满足意图<br/>4. 代码与文档一致]
    end

    %% 样式美化
    style A fill:#fff,stroke:#333,stroke-width:2px
    style B fill:#fff,stroke:#333,stroke-width:2px
    style C fill:#fff,stroke:#333,stroke-width:2px
    style D fill:#fff,stroke:#333,stroke-width:2px
    style E fill:#fff,stroke:#333,stroke-width:2px

  1. 意图注入：工程师向 OpenCode 提供 core_model.puml 和 Markdown 需求描述。

  2. 上下文对齐：OpenCode 通过提前定义的skills和reference定义流程和独有代码库，识别依赖关系。

  3. 任务拆解：AI 根据skill自动执行实现步骤：

    • 第一步：生成实体类（Entity）与值对象（Value Object）。
    • 第二步：构建 CheckerFactory 的逻辑分支。
    • 第三步：编写 Vert.x 的路由处理器（Handler）。
    • 第三步：生成单元测试和集成测试，循环迭代，支持所有测试均通过。

  4. 循环修正：工程师发现 AI 生成的 batchUpdateConfig 事务控制范围过大，直接在文档中补充 “事务需控制在单次 Request 级别” ，AI 重新生成代码。

  5. 代码与文档同步: 通过AI指令，修正原先设计，做到文档与代码一致

AI 时代下的岗位重构

💡 价值高低，取决于你所能解决问题的大小。

对各岗位的冲击与机遇

  1. 产品经理：产研比可能从 1:5 向 1:1 靠拢。如果产品经理能掌握“智能语言”，甚至可以直接驱动 AI 生成原型或简单系统，缩短反馈路径。
  2. 研发工程师：初级“码农”的生存空间被压缩。核心竞争力将转向系统设计、认知抽象以及智能语言的表达能力。
  3. QA (质量保证) ：当研发速度提升 5-10 倍，传统的排期测试模式将崩塌。QA 必须转型为测试工具的设计者和 AI 指令的审计者。

核心竞争力：如何定义自己的“智能语言”？

很多读者会关心“我也想用 AI，但我该怎么定义自己的智能语言？”。这里可以提炼一个方法论：

智能语言的三要素

  • 结构化（Structure） ：放弃长篇大论，使用 PlantUML 或 JSON Schema 定义对象关系。
  • 约束化（Constraint） ：用 Markdown 列表清晰描述逻辑约束（如：“版本号必须单调递增”、“校验失败需回滚至 Version n-1”）。
  • 示例化（Examples） ：给 AI 提供 1-2 个具体的 Input/Output 示例，这比任何文字描述都有效。

结语：程序员会被 AI “干掉”吗？

AI 最先影响的确实是它的创造者——程序员。但这并非为了贩卖焦虑，而是提示我们要升级自己的核心能力：

  • 认知能力：理解现实世界的复杂逻辑，并将其抽象为精准的模型。
  • 表达能力：将认知转化为 AI 可理解的“智能语言”。
  • 协作沟通能力：在虚拟系统与现实需求之间建立链接。
  • 站在前人的肩膀上: 通过持续学习，学习前人经验，努力提升各项能力

文档即系统，意图即代码。 拥抱 AI，从定义第一行智能语言开始。

avatar
文章
阅读
粉丝